feat(workflow-executor): make collection schema cache TTL configurable [PRD-430]

[matthv]

What

The collection-schema cache duration in the workflow-executor was fixed (~10 min) with no way to configure it. Schema changes on the orchestrator side (added/renamed field or relation, display-field change) were therefore only reflected after that fixed window, with no operator control.

This wires a schemaCacheTtlMs executor option through the CLI via the SCHEMA_CACHE_TTL_MS env var — exactly like the other executor tunables (POLLING_INTERVAL_MS, STEP_TIMEOUT_MS, MAX_CHAIN_DEPTH).

Changes

• defaults.ts: DEFAULT_SCHEMA_CACHE_TTL_MS = 10 * 60_000
• build-workflow-executor.ts: new ExecutorOptions.schemaCacheTtlMs, passed to new SchemaCache(...) (the cache already accepted a TTL in its constructor)
• cli-core.ts: parse SCHEMA_CACHE_TTL_MS + document it in --help
• cli.test.ts: parse / unset-default / non-numeric-throws coverage

Notes

• Default behaviour is unchanged: 10 min when SCHEMA_CACHE_TTL_MS is unset.
• Base branch is feat/prd-214-server-step-mapper (workflow-executor is not on main).

fixes PRD-430

🤖 Generated with Claude Code

Note

Make collection schema cache TTL configurable via schemaCacheTtlMs in workflow executor

• Adds schemaCacheTtlMs to the ExecutorOptions interface in build-workflow-executor.ts, passing it to the SchemaCache constructor with a fallback to DEFAULT_SCHEMA_CACHE_TTL_MS (10 minutes).
• Exposes SCHEMA_CACHE_TTL_MS as an environment variable in the CLI, parsed via parsePositiveIntEnv, with help text showing the default value.
• Adds the DEFAULT_SCHEMA_CACHE_TTL_MS constant to defaults.ts.

Changes since #1621 opened

• Moved the default schema cache TTL constant from schema-cache.ts to a centralized defaults module and updated SchemaCache constructor to use DEFAULT_SCHEMA_CACHE_TTL_MS from the defaults module [801303e]
• Added test coverage in buildInMemoryExecutor test suite to verify SchemaCache is constructed with correct TTL values [801303e]
• Extended help output test to verify the schema cache TTL default value is displayed [801303e]

^{Macroscope summarized b6caaac.}

[linear-code]

PRD-430

[qltysh]

Coverage Impact

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

Modified Files with Diff Coverage (2)

Rating	File	% Diff	Uncovered Line #s
	packages/workflow-executor/src/build-workflow-executor.ts	100.0%
	packages/workflow-executor/src/defaults.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]

As discussed on Slack - mitigating a cache issue by reducing a refresh delay only reduces the probability of data staleness, it doesn't avoid it completely. How about instead removing TTL entirely and have the orchestrator include a schemaVersion/hash in poll responses ? That way the executor can clear its schema cache when it detects a change which will automatically trigger a new fetch.

[matthv]

good idea, the TTL only lowers the probability of staleness, it doesn’t remove it.
One thing though: the schema comes from the agent, not the orchestrator. So the version/hash would need to track the agent’s schema, otherwise we’d miss changes or evict for nothing. IMO we can probably reuse the schemaFileHash that’s already computed at publish time instead of a new hash.
I’d keep this PR as-is and open a follow-up to design the hash-based invalidation properly. WDYT?