feat(workflow-executor): add 3-way execution mode to the load related record step (PRD-148)

[matthv]

What

Execution logic for the 3-way Execution mode (Manual / AI-assisted / Full AI) on the workflow Load Related Record step. Part of PRD-148 — 3-PR set (executor + ForestAdmin/forestadmin-server orchestrator + ForestAdmin/forestadmin editor).

• Manual (manual): present the narrowed candidate list with no AI — no relation chooser, no record suggestion. Single-record relations (xToOne, or HasMany with 1 candidate) still pre-fill, since that's the only option, not an AI pick. The Zod schema drops .catch(AutomatedWithConfirmation) and adds Manual, so a manual value is no longer silently coerced back into AI prefill (same reasoning as TriggerAction).
• AI-assisted (automated-with-confirmation, default): AI suggests a record, user confirms (unchanged).
• Full AI (fully-automated): AI selects and loads. Auto-skips (persists executionResult: { skipped: true } + success) when there is no source record (SourceRecordMissingError, Full-AI only), an empty candidate list, or the AI judges none relevant (select-record-by-content returns -1 via the new Full-AI-only allowNone).

selectedRecordRef is now optional on LoadRelatedRecordStepExecutionData (absent only on the no-source Full-AI skip); the wire serializer omits it instead of dereferencing undefined.

Tests

97 tests in the executor suite. Added: Manual = no AI / no pre-selection (incl. relation switch), Manual single-record pre-fill, Full-AI skip on each of the 3 causes, await-mode no-source still errors (regression guard), serializer no-source round-trip.

Validation

Validated end-to-end on the local stack (account → bills) across the 3 modes, plus a local multi-agent code review — 1 Critical found & fixed: serializer crash (503) on the no-source Full-AI skip.

Relates to PRD-148.

🤖 Generated with Claude Code

Note

Add Manual execution mode to LoadRelatedRecordStepExecutor with auto-skip for FullyAutomated

• Adds Manual as a valid executionType for the load-related-record step; in Manual mode, AI is not called for relation selection or candidate suggestion — the first eligible relation is picked deterministically and no suggestedRecord is included.
• In FullyAutomated mode, steps now auto-skip (via new persistSkip) when there is no source record, no linked xToOne record, or when the AI ranks all candidates as irrelevant (returns -1).
• selectBestRecordIndex gains an allowNone option so AI can return -1 only when the candidate list was not truncated, preventing forced selections.
• fetchRecordForRelation and fetchXToOneRecordRef now return null on absence instead of throwing, with callers deciding skip vs. error behavior.
• selectedRecordRef is made optional in LoadRelatedRecordStepExecutionData and the wire serializer skips the field when absent, fixing a serialization crash on auto-skipped steps.
• Behavioral Change: executionType schema no longer coerces unknown values to AutomatedWithConfirmation; invalid values will now fail validation instead of being silently swallowed.

Changes since #1728 opened

• Added 3-way execution mode allowing AI to decline record selection by returning -1 when no candidate satisfies the request [9ee1164]
• Changed FullyAutomated execution mode to fall back to awaiting-input with suggestNoRecord flag instead of auto-skipping when no relevant record exists [9ee1164]
• Added suggestNoRecord field to LoadRelatedRecordPendingData and updated LoadRelatedRecordStepExecutionData interface documentation [9ee1164]
• Removed helper methods and unified record resolution logic through collectCandidateIds and resolveAndLoadAutomatic [9ee1164]
• Updated test suite to validate new awaiting-input fallback behavior and AI -1 guidance [9ee1164]
• Implemented AI failure degradation logic throughout LoadRelatedRecordStepExecutor to convert AI unavailability or errors into deterministic manual fallback execution [f90b868]
• Implemented confidence-based record selection for fully automated mode where low-confidence AI picks trigger user confirmation instead of auto-loading [f90b868]
• Modified LoadRelatedRecordStepExecutor.refreshCandidatesForField to rebuild pendingData from scratch when switching target relations and conditionally set suggestNoRecord only when AI was attempted and returned no suggestion [f90b868]
• Updated select-record-by-content AI tool schema to accept and return a confident boolean parameter indicating AI confidence in record selection [f90b868]
• Updated and expanded tests in load-related-record-step-executor.test.ts to verify AI degradation behavior, low-confidence handling, and stale state clearing [f90b868]
• Created step-definition.test.ts to validate LoadRelatedRecordStepDefinitionSchema parsing of executionType enum values [f90b868]
• Added test verifying LoadRelatedRecordStepExecutor degrades to manual candidate selection when AI ranking fails during field switch [71542cd]
• Added test verifying LoadRelatedRecordStepExecutor propagates non-AI errors during field switch instead of degrading [71542cd]
• Updated inline comment in LoadRelatedRecordStepExecutor.resolveAndLoadAutomatic method [44e23be]
• Renamed test case for LoadRelatedRecordStepExecutor FullyAutomated BelongsTo functionality [44e23be]
• Appended explanatory comment to ESLint directive [08c1949]
• Revised documentation comments across AiAssistUnavailableError class and multiple methods in LoadRelatedRecordStepExecutor including doExecute, refreshCandidatesForField, degradeToManualAwaitInput, selectBestFromRelatedData, withAiAssist, and selectBestRecordIndex within the workflow-executor package [9fcdda2]
• Updated inline test comments throughout the load-related-record-step-executor.test.ts file in the workflow-executor package [9fcdda2]
• Modified the workflow-executor package's LoadRelatedRecordStepExecutor to consult AI for single-candidate scenarios during related record ranking [04b2be8]
• Refactored AI wrapper placement in workflow-executor package's LoadRelatedRecordStepExecutor methods for relation selection and candidate refresh [04b2be8]
• Updated tests in workflow-executor package's load-related-record-step-executor.test.ts to reflect AI consultation for single-candidate scenarios and narrowed AI-wrapping scope [04b2be8]
• Extracted AiAssistUnavailableError class from load-related-record-step-executor into a shared error class in the workflow-executor package [53670e4]
• Modified LoadRelatedRecordStepExecutor class in workflow-executor package to pre-select a single related record candidate in manual execution mode [2f50ee3]
• Added test case verifying single candidate pre-selection behavior in manual execution mode for to-many relations [2f50ee3]

^{Macroscope summarized 4f8b398.}

[linear-code]

PRD-148

[qltysh]

3 new issues

Tool	Category	Rule	Count
qlty	Structure	Function with many parameters (count = 4): selectBestFromRelatedData	2
qlty	Structure	Function with high complexity (count = 14): selectBestRecordIndex	1

[qltysh]

Coverage Impact

⬆️ Merging this pull request will increase total coverage on main by 0.14%.

Modified Files with Diff Coverage (2)

Rating	File	% Diff	Uncovered Line #s
	...ow-executor/src/executors/load-related-record-step-executor.ts	100.0%
	packages/workflow-executor/src/errors.ts	100.0%
	Total	100.0%

🚦 See full report on Qlty Cloud »

🛟 Help

• Diff Coverage: Coverage for added or modified lines of code (excludes deleted files). Learn more.

• Total Coverage: Coverage for the whole repository, calculated as the sum of all File Coverage. Learn more.

• File Coverage: Covered Lines divided by Covered Lines plus Missed Lines. (Excludes non-executable lines including blank lines and comments.)

  • Indirect Changes: Changes to File Coverage for files that were not modified in this PR. Learn more.

[Scra3]

Review of the 3-way execution mode against the PRD-148 acceptance criteria (plus a skeptic second pass on the findings). The edge-case handling is solid overall — Manual never calls the AI, no-source throws instead of auto-advancing, AI failure degrades to Manual, and -1/allowNone is correctly gated on a non-truncated list. Two points below: one blocking edge case in Full AI, one non-blocking error-classification smell.

[Scra3]

Follow-up architecture notes (non-blocking, complements the earlier review). Overall the executor conforms well to the trigger-record-action precedent — base machinery (invokeWithTool, handleConfirmationFlow, patchAndReloadPendingData) is reused rather than re-implemented, and the 3-mode schema mirrors TriggerAction. One inline placement suggestion, plus a nit: the sharedFields header comment (src/types/validated/step-definition.ts:23-24) still claims every schema normalizes via .default().catch(), now false for the LoadRelatedRecord and TriggerAction schemas that intentionally drop .catch — update it to avoid misleading future edits.