fix(workflow-executor): operation activity log targets the acted record (PRD-442 #1)

[Scra3]

Context

fixes PRD-442

A workflow step's operation activity-log entry (audit trail) pointed at the run's trigger record, even when the step acted on a record loaded earlier in the run — possibly in another collection. Root cause: the audit args were built before doExecute() (so the acted record wasn't resolved yet) and used context.collectionId + baseRecordRef.

Changes

Audit moved into a dedicated AgentWithLog wrapper. Activity-log responsibility left BaseStepExecutor / OperationStepExecutor (deleted) and now lives in AgentWithLog, which wraps AgentPort and emits one audit entry per data-access / write call (pending → succeeded/failed). The target is derived from the call itself — recordId = query.id, collectionId resolved from the call's collection — so each entry points at the acted record and its own collection, and fires only when the operation actually happens. Covers read / update / trigger-action / load-related; the MCP step uses the generic logged() (its side effect is a tool invocation, audited against the run's base record).

Acted collection's numeric id. CollectionSchema gains a required collectionId, resolved from the live schema via the new SchemaCache.getOrLoad(name, loader) (lazy cache-or-fetch, decoupled from WorkflowPort). The audit is not optional, so a missing id fails loud at the boundary (DomainValidationError).

Fail-loud schema resolution. AgentClientAgentPort.resolveSchema now throws SchemaNotCachedError instead of returning a synthetic fallback schema (which had a wrong primaryKeyFields / collectionId). Unreachable in the normal flow — AgentWithLog resolves (and caches) the schema right before delegating — so it's a true invariant guard.

Idempotency unchanged, ordering preserved. Idempotency stays entirely in the executors. The executing write-ahead marker is saved in a beforeCall thunk that AgentWithLog runs after createPending, before the side effect — so an audit-creation failure never leaves an orphan executing marker, and AgentWithLog stays ignorant of run state.

Activity-log failures surface as user-facing step errors; markFailed carries a local-only diagnostic message (the server status endpoint accepts just { status }).

⚠️ Coordinated deploy (cross-repo)

The orchestrator must include collectionId in every getCollectionSchema response. Until it does, steps on that collection fail at schema parse — so this must ship in tandem with the orchestrator change.

Scope

Bug #1 (wrong target), plus the confirmation-flow premature / duplicate symptom of #2: logging at the operation point means a confirmation step logs nothing while awaiting input, nothing on reject, and exactly once on confirm (covered by tests). Remaining #2 work: exactly-once across network retries (orchestrator-side dedup of identical (runId, stepIndex) outcomes).

Verification

• yarn workspace @forestadmin/workflow-executor build ✅
• 922 tests — incl. a cross-collection repro (trigger on customers, act on orders#99 → audit targets orders, not the trigger), per-executor target assertions, AgentWithLog unit tests (beforeCall ordering, createPending-throws, userMessage vs 'Unexpected error'), reject-emits-no-log, and getOrLoad hit/miss ✅
• lint: 0 errors ✅

🤖 Generated with Claude Code

Note

Target the acted record in operation activity logs for workflow executor steps

• Introduces AgentWithLog (agent-with-log.ts), a wrapper around AgentPort that emits per-operation activity log entries (pending → succeeded/failed) with collectionId resolved from the collection schema and recordId from the query target.
• Removes the step-level buildActivityLogArgs()/runWithActivityLog() hooks from BaseStepExecutor; activity logging now happens at the individual data-access call level inside each executor.
• Adds SchemaResolver (schema-resolver.ts) to lazily fetch and cache collection schemas per run, and extends CollectionSchemaSchema to require a non-empty collectionId field.
• StepExecutorFactory.buildContext now constructs both SchemaResolver and AgentWithLog and injects them into the execution context, replacing the schemaCache and direct agentPort access previously used by executors.
• markFailed on ActivityLogPort no longer accepts an errorMessage parameter; write operations pass a beforeCall thunk to persist idempotency state immediately before the side effect.
• Risk: collectionId is now a required field on collection schemas — any schema missing it will fail Zod validation.

Changes since #1628 opened

• Removed agentPort, workflowPort, and activityLogPort properties from ExecutionContext interface and removed the cached agent field from BaseStepExecutor class [a7f536a]
• Updated all step executor implementations to access agent through this.context.agent instead of this.agent [a7f536a]
• Updated test helpers and test cases to remove port properties from mock contexts and accept port overrides as separate parameters [a7f536a]
• Documented that AgentWithLog.getActionFormInfo is an unaudited passthrough method for read-only form information [6efee0f]
• Changed AgentWithLog class methods to pass the complete WriteOptions object through the call chain to the audit method instead of extracting and passing only the beforeCall callback function [e4e4186]
• Introduced ActivityLogger class to encapsulate activity-log emission around async operations [37f7048]
• Refactored AgentWithLog class to delegate activity-log management to injected ActivityLogger [37f7048]
• Updated ExecutionContext interface to include activityLogger property and modified StepExecutorFactory.buildContext to instantiate and inject ActivityLogger [37f7048]
• Replaced AgentWithLog.logged calls with activityLogger.run in McpStepExecutor.executeToolAndPersist method [37f7048]
• Updated all test suite context helpers to construct ActivityLogger instances and pass them to AgentWithLog instead of ActivityLogPort [37f7048]
• Added comprehensive test coverage for ActivityLogger class and updated AgentWithLog test suite to use ActivityLogger [37f7048]
• Renamed ActivityLogger to ActivityLog and refactored its primary method from run(target, operation, opts?) to track(target, { operation, beforeCall? }) in the workflow-executor package [e41c488]
• Updated AgentWithLog, McpStepExecutor, StepExecutorFactory, and the ExecutionContext interface to use ActivityLog instead of ActivityLogger and invoke track with an options object [e41c488]
• Updated all test files in the workflow-executor package to use ActivityLog instead of ActivityLogger and updated test invocations to call track with an options object [e41c488]

^{Macroscope summarized ec949b6.}

[linear-code]

PRD-442

[qltysh]

4 new issues

Tool	Category	Rule	Count
qlty	Structure	Function with high complexity (count = 11): execute	2
qlty	Duplication	Found 21 lines of similar code in 2 locations (mass = 103)	1
qlty	Structure	Function with many returns (count = 5): execute	1

[qltysh]

Coverage Impact

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

Modified Files with Diff Coverage (13)

Rating	File	% Diff	Uncovered Line #s
	packages/workflow-executor/src/executors/step-executor-factory.ts	100.0%
	...ow-executor/src/executors/load-related-record-step-executor.ts	100.0%
	...s/workflow-executor/src/executors/read-record-step-executor.ts	100.0%
	packages/workflow-executor/src/executors/record-step-executor.ts	100.0%
	packages/workflow-executor/src/executors/base-step-executor.ts	100.0%
	...workflow-executor/src/executors/update-record-step-executor.ts	100.0%
	packages/workflow-executor/src/executors/activity-log.ts	100.0%
	...-executor/src/executors/trigger-record-action-step-executor.ts	100.0%
	packages/workflow-executor/src/errors.ts	50.0%	266
	packages/workflow-executor/src/index.ts	100.0%
	packages/workflow-executor/src/executors/mcp-step-executor.ts	100.0%
	packages/workflow-executor/src/executors/agent-with-log.ts	100.0%
	packages/workflow-executor/src/schema-resolver.ts	100.0%
	Total	98.5%

🤖 Increase coverage with AI coding...

In the `fix/prd-442-activity-log-target` branch, add test coverage for this new code:

- `packages/workflow-executor/src/errors.ts` -- Line 266

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

not works

[Scra3]

should never occur because schema is already loaded at this point

[nbouliol]

why do we need to accept a load arg ? is it not always the same logic for getting the schema ?

This means you could access a cached value that was not loaded from the same loader as the one you provide

[Scra3]

I introduce a schemaResolver to avoid to pass this ugly getOrLoad

[nbouliol]

If beforeCall throws, we markFailed though the side effect never ran — the audit then shows a failed write on a record that was never touched. Intended, or should we only markFailed around run()?

[nbouliol]

Uncovered (qlty): a test with a real SchemaCache miss would exercise the workflowPort loader path here.

[nbouliol]

Code LGTM, needs manual testing

[Scra3]

schemaCache is only used by schema resolver. No need to inject schema cache

[Scra3]

useless

[Scra3]

unused

[Scra3]

unused

[Scra3]

unused