fix: load related record

[EnkiP]

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

Note

Rework load-related-record step to support field selection, candidate ranking, and x-to-one fetching

• Redesigns the LoadRelatedRecordStepExecutor to produce richer pendingData containing availableFields, suggestedField, availableRecordIds (with optional referenceFieldValue), and suggestedRecord instead of the previous flat shape.
• Adds getSingleRelatedData to AgentPort and AgentClientAgentPort for fetching x-to-one (BelongsTo/HasOne) relations via parent-record projection rather than a list query.
• Supports mid-step field switching: a patch with only fieldName (no userConfirmed) triggers candidate refresh and returns awaiting-input without completing the step.
• Normalizes relatedCollectionName in getCollectionSchema to strip trailing target-key suffixes (e.g. store.id → store) and surfaces an optional referenceField from collection schemas.
• Updates loadRelatedRecordPatchSchema HTTP validator to accept preview patches (fieldName-only) and rename name → fieldName; selectedRecordId is only required when confirming with a relation override.
• Risk: getRelatedData now requires callers to supply relatedSchema; any adapter calling it without the new argument will break at runtime.

Changes since #1610 opened

• Updated comment in stripReferenceKey utility function to clarify that the related primary key is derived from the schema's primaryKeyFields rather than from a relatedPrimaryKey field [88bbefa]
• Removed relatedPrimaryKey property from mocked field definitions across test cases in ForestServerWorkflowPort.getCollectionSchema test suite and updated assertions to verify removal of arbitrary unknown field keys [88bbefa]

^{Macroscope summarized 7b222de.}

[qltysh]

All good ✅

[qltysh]

Coverage Impact

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

Modified Files with Diff Coverage (4)

Rating	File	% Diff	Uncovered Line #s
	...ow-executor/src/executors/load-related-record-step-executor.ts	100.0%
	packages/workflow-executor/src/http/pending-data-validators.ts	100.0%
	.../workflow-executor/src/adapters/forest-server-workflow-port.ts	100.0%
	...ages/workflow-executor/src/adapters/agent-client-agent-port.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.

[hercemer42]

Claude has added a lot of comments, but your code is readable as is, so in my opinion they aren't necessary. I'd recommend to keep them to a minimum.

[macroscopeapp]

🟡 Medium http/pending-data-validators.ts:56

The .refine() validation on line 56 requires selectedRecordId whenever fieldName is provided, even when userConfirmed is false. This means sending { userConfirmed: false, fieldName: "someField" } incorrectly fails validation with a message about "confirming with a relation override" — but declining a step is not confirming. The check should include data.userConfirmed === true to match the documented intent.

Suggested change

	if (data.fieldName !== undefined) return data.selectedRecordId !== undefined;
	if (data.userConfirmed === true && data.fieldName !== undefined) return data.selectedRecordId !== undefined;

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file packages/workflow-executor/src/http/pending-data-validators.ts around line 56:

The `.refine()` validation on line 56 requires `selectedRecordId` whenever `fieldName` is provided, even when `userConfirmed` is `false`. This means sending `{ userConfirmed: false, fieldName: "someField" }` incorrectly fails validation with a message about "confirming with a relation override" — but declining a step is not confirming. The check should include `data.userConfirmed === true` to match the documented intent.

Evidence trail:
packages/workflow-executor/src/http/pending-data-validators.ts lines 34-65 at REVIEWED_COMMIT. Line 54 only catches `userConfirmed === undefined`, line 56 applies to any defined `userConfirmed` (including `false`). The inline comment on line 55 says 'Confirm patch' but code doesn't check `userConfirmed === true`.

[Scra3]

Found a blocking bug in the xToOne relation projection (getSingleRelatedData).