[hercemer42]

Phase 1 of multiple related records, Forest Runtime side. Part of PRD-1693 (phase 1 of PRD-24). Nothing reaches customers until the go-live ticket PRD-1695 sets the front's version floors: before that the editor never offers Multiple, so no definition carries multiple or quantifier.

What changes

1. A Load Related Record step loads several records. Before: one record per step. After: with preRecordedArgs.multiple, the step lists up to 50 candidates (hasMoreRecords when the list is cut), the AI pre-checks its pick in suggestedRecords, told which collection the candidates come from, the confirmation's selectedRecordIds loads every record picked, each among those offered, and the step saves executionResult: { relation, records }. A Multiple step's relation cannot be switched at run time, and a record picked twice is refused. Full AI loads its pick only when it saw every candidate, picked some and is sure, and pauses with the pick pre-checked otherwise.
2. Steps sourced from it run once per record. Before: Get Data, Update Data, Trigger Action and Load Related Record ran once on one record. After: sourced from a Multiple step, they run once per record, in order, each through the unchanged single-record executor over a run store narrowed to that record, and save iterations[] on their row. Every record is attempted, the step errors when any failed, and { failedRecords: "retry" | "skip", sourceRecordId? } re-runs or skips the failed ones. { unfinishedRecords: "handle-manually", sourceRecordId } on the paused record hands every record not finished over at once, as a decline hands over one, so the step still errors over a record that failed. The step timeout applies per record, and a timed-out record's late result is never saved.
3. A Decision branches on any, every or no record. Before: a deterministic condition read one Get Data value. After: a condition on per-record Get Data carries quantifier and records { matched, evaluated, unchecked? } in its trace. A record without a value leaves it undecided unless the records read settle it (one match for any and none, one non-match for every), conditions and options combine three-valued, and only when an undecided condition could change the branch does the Decision decide nothing: it reports awaiting-input with executionParams.unchecked, and the operator's { selectedOption } completes it with selectedBy: "operator".
4. The run lock lasts the whole loop. Before: a runtime kept a run only by reporting a step, so 50 records could outlast the 7-minute lock. After: the runner renews it through POST /renew-run-lock before each record, stops the step without reporting when the orchestrator refuses (aborted or lost), and hands the run back when stopping. A step dispatched while carrying an error sends that error cleared when it next succeeds or pauses; every other report is unchanged.

Release plan

Merges and deploys after ForestAdmin/forestadmin-server#8634, which adds the renewal route. Against an orchestrator without it the renewal fails as unavailable and the step carries on under the lock it holds, so an early release degrades to today's lock behaviour rather than breaking.

Decisions

• PRD-1693: 1 functional, 1 architectural · 2 unticked

Tests

Red before the code (Tests: 18 failed, 112 passed, 130 total, 11 suites failing on the missing members), green after across the 19 files covering the changed sources (Test Suites: 19 passed, 19 total, Tests: 1081 passed, 1081 total). New: per-record-step-executor.test.ts, through StepExecutorFactory.create with the in-memory store. Later commits added 12 tests, each seen red before its fix: the relation-switch refusal and the review findings. None reaches shared state.

Definition of Done

General

• Write an explicit title for the Pull Request, following Conventional Commits specification
• Test manually the implemented changes
• Validate the code quality (indentation, syntax, style, simplicity, readability)

Security

• Consider the security impact of the changes made: step outcomes still carry no client data. Per-record results, the AI's pick and the unchecked record ids stay in the run store, on the client's side, and the renewal sends only the run id and its lock.

Squash message

feat(workflow-executor): run steps once per record of a Multiple related-records step

A Load Related Record step loaded one record, so a case with several UBOs
needed one workflow per UBO. A Multiple step now loads up to 50 records the
operator picks, each at most once, and every Get Data, Update Data, Trigger
Action and single Load Related Record sourced from it runs once per record,
in order and independently. Failed records are retried or skipped on their
own, handing the rest over by hand keeps a failed record's error, a timed-out record never writes its late result or starts its action,
and a Decision on per-record data branches on any, every or no record,
pausing for the operator when a record has no value. The runner renews the
run lock before each record and hands the run back when stopping, and a step
re-run after an error reports that error cleared.

🤖 Generated with Claude Code

Note

Add per-record execution for steps sourced from a Multiple related-records step

• Adds a multiple flag to Load Related Record step definitions. Steps pinned to such a source (ReadRecord, UpdateRecord, TriggerAction, LoadRelatedRecord) now run once per selected record via a new PerRecordStepExecutor with iteration-level storage, summaries, and wire serialization (step-executor-factory.ts, step-execution-data.ts)
• Adds an AI-assisted related-record picker and condition quantifiers (any, every, none) with new typed errors for invalid configurations (related-record-picker.ts, errors.ts)
• The runner renews the run lock with the orchestrator before each record; a refused renewal stops the loop, an unavailable one continues, per the accepted ADR
• HTTP confirmation payloads accept up to 50 selected records, deserialized from pipe-separated IDs (pending-data-validators.ts)
• Behavioral Change: Runner.executeStep and dispatchDetached now take the dispatch object instead of separate step/token arguments; stale errors are cleared only for steps marked carriesError: true. Sub-workflow calls pinned to a multi-record source now fail with SourceLoadsSeveralRecordsError

^{Macroscope summarized e29023f.}

[linear-code]

PRD-1693

[qltysh]

30 new issues

Tool	Category	Rule	Count
qlty	Structure	Function with many returns (count = 6): doExecute	18
qlty	Structure	Function with many parameters (count = 4): evaluateCondition	6
qlty	Structure	Function with high complexity (count = 12): doExecute	5
qlty	Structure	High total complexity (count = 70)	1

[qltysh]

Coverage Impact

This PR will not change total coverage.

Modified Files with Diff Coverage (19)

Rating	File	% Diff	Uncovered Line #s
	packages/workflow-executor/src/runner.ts	100.0%
	packages/workflow-executor/src/executors/step-executor-factory.ts	100.0%
	...ow-executor/src/executors/load-related-record-step-executor.ts	97.2%	604, 613
	...orkflow-executor/src/executors/summary/step-summary-builder.ts	100.0%
	packages/workflow-executor/src/executors/record-step-executor.ts	100.0%
	...ges/workflow-executor/src/executors/condition-step-executor.ts	100.0%
	packages/workflow-executor/src/http/pending-data-validators.ts	100.0%
	packages/workflow-executor/src/executors/base-step-executor.ts	100.0%
	.../workflow-executor/src/adapters/forest-server-workflow-port.ts	100.0%
	...workflow-executor/src/adapters/run-to-available-step-mapper.ts	100.0%
	packages/workflow-executor/src/errors.ts	100.0%
	packages/workflow-executor/src/types/validated/step-definition.ts	100.0%
	...ow-executor/src/adapters/step-outcome-to-update-step-mapper.ts	100.0%
	...ow-executor/src/executors/summary/step-execution-formatters.ts	100.0%
	packages/workflow-executor/src/http/step-serializer.ts	100.0%
	packages/workflow-executor/src/executors/iteration-run-store.ts	100.0%
	packages/workflow-executor/src/executors/related-record-picker.ts	100.0%
	packages/workflow-executor/src/types/step-execution-data.ts	100.0%
	...es/workflow-executor/src/executors/per-record-step-executor.ts	100.0%
	Total	99.6%

🤖 Increase coverage with AI coding...

In the `feature/prd-1693-phase-1-multiple-related-records-load-several-records-and` branch, add test coverage for this new code:

- `packages/workflow-executor/src/executors/load-related-record-step-executor.ts` -- Lines 604 and 613

🚦 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.

[hercemer42]

Spec (PRD-1693): conforms. PRD-1693 has 5 unvalidated decisions: not final.

Applies to: the PR as a whole
Claude Opus 5.5 (claude-opus-5-5): Preferential: the run lock renewal before each record has no ADR, so the next reader cannot learn why a step calls the orchestrator mid-step.

Code

Released runtimes call renew-run-lock on another repository, a reader asks why a step skips handing back, and two alternatives were turned down.

A way out: record it with /adr.

[hercemer42]

Claude Opus 5.5 (claude-opus-5-5): The missing ADR is now docs/adr/2026-10-21-a-step-running-once-per-record-renews-its-run-lock-with-the-orchestrat.md, recording the run lock renewal.

c8586d1

[hercemer42]

Closed, the run lock renewal is now an ADR in docs/adr/, with the two alternatives it turned down.

How it was checked

The predicate is a hard-to-reverse decision no ADR records.
The ADR names the route released runtimes call, its refusal and unanswered cases, and the hand-back and one-record dispatch it rejected.