fix(workflow): load-related chooses the relation by its target collection

[Scra3]

Context

Stacked on #1628 (base fix/prd-442-activity-log-target). Two distinct load-related improvements.

1. Choose the relation by its target collection

A load-related step picked the source record first (« which available record's collection best matches the request »), then the relation. With records accumulated from prior load-related steps, « Load the dvd X » latched onto an already-loaded dvd (collection matches) instead of the store that has the dvds relation → it followed dvd → store and re-loaded a store.

Fix: fuse the two choices into one over (record, relation) pairs, picked by what the relation leads to. New AI tool select-relation-to-follow (options labeled Source → relation (→ target)) replaces select-record + select-relation for load-related. preRecordedArgs (selectedRecordStepIndex / relationDisplayName) still pin source/relation; a single candidate skips the AI call. The shared select-record heuristic is untouched for read/update/trigger.

2. Thread the step title to the AI

The orchestrator sends a title on every step (ServerWorkflowStepBase.title) but the mapper dropped it. It's now mapped into StepDefinition and injected into buildContextMessage, so every AI call sees the step's intent — important when the prompt is weak/empty (e.g. a load-related prompt arriving as « Load » while the title says « Load the store »).

Verified live (_example)

account → load store → read store name → load dvd "Celine dion" → load dvd "titanic": the last step follows store#6 → dvds (GET /store/6/relationships/dvds, candidates incl. Titanic), no more dvd → store trap.

Tests

• load-related suite migrated to the single select-relation-to-follow call + a repro test (account + loaded store + loaded dvd → "Load the dvd titanic" follows store→dvds, asserts getRelatedData(collection: 'store', relation: 'dvds')).
• step-definition / run mappers assert title is carried through.
• build ✅ · lint 0 error ✅.

🤖 Generated with Claude Code

Note

Fix LoadRelatedRecordStepExecutor to select relations by target collection across all available records

• Replaces the previous single-record relation selection with a candidate pool built from all available source records, filtering out relations that lack a relatedCollectionName.
• Introduces resolveTarget to pick a (record, relation) pair, skipping the AI call entirely when only one candidate exists.
• Adds support for pinning selection via preRecordedArgs.selectedRecordStepIndex and preRecordedArgs.relationName (matched by technical field name); invalid pins now throw InvalidPreRecordedArgsError.
• The new selectRelationToFollow AI tool presents labeled options combining source record, collection, and relation details, and throws InvalidAIResponseError if the model returns an out-of-set value.
• Behavioral Change: relations without a target collection are now excluded; if all relations lack one, the executor raises NoRelationshipFieldsError instead of proceeding.

^{Macroscope summarized 780daee.}

[qltysh]

1 new issue

Tool	Category	Rule	Count
qlty	Structure	High total complexity (count = 60)	1

[qltysh]

Coverage Impact

Unable to calculate total coverage change because base branch coverage was not found.

Modified Files with Diff Coverage (1)

Rating	File	% Diff	Uncovered Line #s
	...ow-executor/src/executors/load-related-record-step-executor.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.