feat(spec,runtime,service-automation): the flow doors state callerParamKeys, and the headless screen verdict reads it

[objectstack-fleet]

Fixes #19846

Clause-②: yes

_{Rewritten short by the domain:spec#5 seat (2026-09-23T16:17Z). The dev report is on #19846; the earlier long body is in the edit history.}

AutomationContext gains an optional callerParamKeys?: string[] (packages/spec): the keys of the caller's own params. When it is present, the screen node's headless verdict reads it and never infers. When it is absent (an older producer), the inference from #15787 runs unchanged.

What changed

• Doors that fill it:

  • the action door, dispatchFlowAction (REST POST /api/v1/actions/..., MCP run_action);
  • the trigger door, buildAutomationContext (POST /automation/:name/trigger, the legacy route, a declarative type: 'flow' endpoint).

  Each door records the caller's keys before seeding anything. It leaves out its row-id keys: recordId, the camelCase object-id alias, and on the action door the action's recordIdParam.

• Producers that leave it absent (today's inference): the record-change, schedule, time-relative and webhook triggers, and direct engine.execute callers.

• Child runs: subflow and map drop the parent's list from the child run's context.

• Behaviour edge: a caller that sends the action's recordIdParam key with a value other than the row id no longer answers a screen field of that name. The changeset says so.

• Docs:

  • flows.mdx and the changeset describe the signal;
  • the flows.mdx "known gap" paragraph on durable resume is replaced, because it has been false since 4177ed3a84.

Pins

• Both boundary constructions from the card pause on the real engine (screen-headless-caller-signal.test.ts). Removing the signal read turns both red.
• screen-headless-satisfaction.test.ts and screen-headless-provenance-durable-resume.test.ts are untouched and green; they now pin the absent path. The dev report names the fixtures in them that encode the inference rather than the contract.
• One existing pin was edited: endpoint-executor.test.ts compares the whole context with toEqual, so it now includes callerParamKeys: ['reason'].

Not in this PR

• The schedule trigger's own params can still answer a screen: filed as A scheduled flow run skips a screen whose required field is named schedule, jobId or flowName: the schedule trigger's own params are read as the caller's answers #19900.
• MCP run_action on a screen flow dead-ends: the screen pauses even when every input is bound, and list_actions never surfaces flow input variables #15705 stays open for the MCP resume verb.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Sfe5YjBLwB9J3y8fvm2xq1

[github-actions]

📓 Docs Drift Check

This PR changes 3 package(s): @objectstack/runtime, @objectstack/service-automation, @objectstack/spec, touching 17 documentable anchor(s).

23 hand-written doc(s) name something this change touched — list omitted above 15 rows. Re-derive on the tree named below: node scripts/docs-audit/affected-docs.mjs --json 1f0b3419ff818c5b97c2d0c00dc917410a67e8b2.

⛔ 4 release-owned page(s) also affected — read-only, see AGENTS.md Documentation Guardrails.

What this run could not see

• 1 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 60 of 215 client-bound route-ledger rows — the other 155 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 155: 0 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 55 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 100 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.
• a key NAME is not a key, so the hand re-read the line above prescribes can land on the wrong schema. The same spelling is authorable on one governed type and a [REMOVED] tombstone on another for each of active, aria, joins, objects, template, tools and version (censused on [finding] tools is a key on BOTH AgentSchema (tombstoned, dead) and SkillSchema (live, cloud-attested), so a name-based search attributes skill examples to the agent key — it produced a false stop-the-line alarm on PR #19059 #19093 over the liveness ledger's governed types, top-level keys); nothing in a search result distinguishes the two, so a grep hit on a LIVE example reads as evidence about the DEAD key. Measured on fix(spec): the agent.tools liveness row says dead — it claimed live on a key the schema tombstoned #19059: content/docs/ai/agents.mdx was reported as contradicting the agent.tools tombstone over its tools: example at :161, which is inside the defineSkill({ block opened at :155 — the page was already correct. Settle ownership by PARSING the value against both schemas, never by the name: that literal PASSES SkillSchema, and as an AgentSchema it FAILS at tools with the tombstone prescription. ⛔ These names are not the whole class — a key retired through a .strict() guidance map leaves no tombstone in the walked shape and none of them here (tool.category, live as AIToolDefinition.category).

Coarse fallback — 141 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 1f0b3419ff818c5b97c2d0c00dc917410a67e8b2 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from b513eabdc4b92f077956a4f127a73e2682265505 — the merge of head 0155b343ef2c723a5a92f6c1a52b3a67b1db69cd into base 1f0b3419ff818c5b97c2d0c00dc917410a67e8b2, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin b513eabdc4b92f077956a4f127a73e2682265505 && git checkout b513eabdc4b92f077956a4f127a73e2682265505
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 1f0b3419ff818c5b97c2d0c00dc917410a67e8b2 0155b343ef2c723a5a92f6c1a52b3a67b1db69cd && git checkout -B drift-repro 1f0b3419ff818c5b97c2d0c00dc917410a67e8b2 && git merge --no-ff 0155b343ef2c723a5a92f6c1a52b3a67b1db69cd

node scripts/docs-audit/affected-docs.mjs --json 1f0b3419ff818c5b97c2d0c00dc917410a67e8b2

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs 1f0b3419ff818c5b97c2d0c00dc917410a67e8b2 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[objectstack-fleet]

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 0155b343ef2c723a5a92f6c1a52b3a67b1db69cd

_{Reviewed and posted 2026-09-23T16:55Z by the at-tier review subagent the domain:spec#5 seat spawned — inputs: card #19846 and its 3 comments, #15705 (9 comments), #19900, PR #19899 (merge-base diff dabf8d795e..0155b343ef, 12 files, 7 commits, 46 check-runs), AGENTS.md, contract-review.md, execution-duties.md; objectui read at the pin 62597c5880. Read: the whole diff and every producer named below. Ran: the three screen suites, the two runtime pin files and the spec pin at head in a detached worktree; four ablations (three re-measured from the dev's set, one my own) and one edge probe on the real engine. NOT MEASURED: the map-strip ablation (A3), the dev's claim that boundary construction 1 is unreachable through a shipped door, and the derived gate family (read from CI, per the rule).}

① Derived judgments

Producers of an AutomationContext that start or resume a run (my census: every .execute( into an automation engine/service over packages, examples, apps, non-test, plus the engine's trigger start callback at engine.ts:3607; the service registered as automation is the engine itself, plugin.ts:617, and resolveRunContext spreads ...context, engine.ts:5038, so the key reaches screen-nodes.ts:236 unfiltered):

producer	signal	judged
trigger door domains/automation.ts:1305 via buildAutomationContext — POST /:name/trigger, legacy POST /trigger/:name	filled	right; both routes pinned, 12/12 measured
declarative type:'flow' endpoint endpoint-executor.ts:537, same builder	filled	right; callerParamKeys: ['reason'] pin measured
action door action-execution.ts:947 dispatchFlowAction — REST /actions (domains/actions.ts:753, params: reqParams = raw body.params) and MCP run_action (domains/mcp.ts:727 → invokeBusinessAction:2261, params = raw input.params)	filled	right; nothing is merged into the caller's bag upstream on either path (the {...reqParams, recordId, objectName} merge at actions.ts:741 is the script/sandbox branch)
schedule (schedule-trigger.ts:806), time-relative (:726), record-change (:499), api/webhook (api-trigger.ts:143) — through engine.ts:3607	absent → inference	right per the ruling's scope; schedule's non-record seeds are #19900
subflow-node.ts:114, map-node.ts:193 child runs	stripped → inference	right: these are the only two engine.execute sites in builtin/; parallel/loop/try_catch run regions of the same run against the same bag, so the parent's list is the right list there
examples/app-showcase/src/security/seed-approval-demo.ts:308 direct engine.execute	absent	right
engine.resume (run.context, engine.ts:6783), retryExecution (same context), bubbleToParent (parent's own persisted context)	not a start	no foreign list is possible: ResumeSignal (automation-service.ts:503) carries no context; both stores JSON-clone on save and load (suspended-run-store.ts:145,178,183), and a string[] survives — the durable pin went red under A1

Can a caller make a filled list name a key it did not supply, or omit one it did? No and yes-by-design: both lists are Object.keys of the caller's own bag minus the door's row-id keys, nothing else; the omission is the row-id set only.

Row-id keys. Trigger door leaves out recordId and the object-id alias: right against shipped clients — objectui useConsoleActionRuntime.flowHandler at the pin mirrors the row id into params.recordId (line 578) before posting to that door; RecordDetailView.flowHandler, the SDK automation.trigger and verify's flows.run (handle.ts:369) reach the same door. Action door additionally leaves out the action's recordIdParam: on main, flows.mdx already says the id seeded "under an action's declared recordIdParam" is not "the caller supplying a screen value" (diff context lines 44-46), while the inference honoured that only by value. Measured edge (my probe on the real engine, required field named like recordIdParam, caller value ≠ row id): no signal → run continues with the caller's value; door-shaped signal → paused. Not an accept-set narrowing: no request key is refused, the value still lands in the bag ({...seeded, ...params}), no authorable key or export is removed — execution-duties.md:65 asks whether the accept set widens or the public surface grows; AGENTS.md's (narrowing) arm is for a removal or rename an author can write. Plain Clause-②: yes is the right arm; no ADR-0087 disposition owed. The changeset states the edge (its last bullet).

Pins. Head: service-automation 41/41 (11 new + 24 + 6 untouched), runtime 62/62, spec 2/2. Ablations (each mutated file hash-checked, restored with checkout HEAD --, blob == HEAD, tree clean): A1 signal read removed → 6 red of 41, BOUNDARY 1 and BOUNDARY 2 both red plus the durable-store pin; A2 subflow strip removed → 2 red of 11; A6 trigger-door exclusion removed → 5 red of 12; my own action-door exclusion removed → 3 red of 12.

Sentences that ship. Docblock, changeset, flows.mdx, PR body: the door list, the absent-producer list and the strip list equal my census; the inference paragraph in flows.mdx matches the four legs of callerSupplied at head; the replaced "known gap" paragraph was false since 4177ed3a84 (value comparison, #16392) as claimed; "no security middleware keys on it" — the twelve files naming the key are the PR's own; "one existing pin edited" — the diff's only modified test is endpoint-executor.test.ts. No false sentence found. Two incompletions, not falsehoods: flows.mdx names the trigger door without the legacy route the docblock and changeset name; the changeset's "two constructions still skipped" is the engine-level verdict (the dev's own report says construction 1 is not producible through a shipped door — NOT MEASURED by me).

Dev-report claim that is misattributed (not in shipped text): the action door's recordIdParam exclusion is justified by objectui resolveRecordIdParamSeed, but at the pin that call sits in the console's api handler (useConsoleActionRuntime.tsx:415-426; RecordDetailView.tsx:685 names it the apiHandler mirror), which never reaches dispatchFlowAction; console flow actions use the trigger door. The exclusion stands on the published flows.mdx sentence, not on that client.

Governed surfaces: none in the file list. Model identifiers: swept the diff, all seven commit messages and the PR body for every spelling — none.

② Semver level

• @objectstack/spec minor — a new optional member on the published AutomationContext (./contracts export): correct, and it is what makes Clause-②: yes true.
• @objectstack/runtime minor — no new entry-point export (buildAutomationContext/dispatchFlowAction are not on index.ts); the doors emit a new signal: at least right.
• @objectstack/service-automation patch — HeadlessScreenContext is new but screen-input-contract.ts is not re-exported by the package entry (exports map is . only), so no public surface moves; the behaviour is a skip→pause fix: defensible (minor would also be).
• Arm: plain yes, consistent with the changeset (no (narrowing); nothing removed). Check Changeset success.

CI at the head, 46 runs de-duplicated by name keeping the latest started_at: 35 checks, 31 success, 4 skipped by design, 0 red — Auto Label and Check PR Size (latest run is the seat's body-edit edited event, excluded by pr-automation.yml's github.event.action != 'edited'; their earlier push-event runs succeeded), Packed-tarball smoke (opt-in) (label needs:pack-smoke absent), Console Pin Gate (needs.filter.outputs.console false: no console path touched). All seven required contexts success.

③ Boundary flags

• Q1 (webhook trigger absent): answered — A. The ruling names the action and trigger doors; api-trigger.ts:143 seeds params as a copy of the payload it also sets as the record, so today's inference pauses; filling from the payload would move webhook screen behaviour without a ruling.
• Q2 (recordIdParam left out; arm): answered — keep, plain yes, no ADR-0087 disposition (① above, with the measured edge).
• Key name callerParamKeys: accepted — camelCase TS config key, reads as what it is.
• Locally unmeasured (dev): full spec suite and the out-of-package importers of AutomationContext — covered by Test Core (6/6 shards) and Type Check · workspace, both success.
• A scheduled flow run skips a screen whose required field is named schedule, jobId or flowName: the schedule trigger's own params are read as the caller's answers #19900 (schedule seeds answer a screen): correctly filed as class a, pm:blocked with Blocked-by: #19846; the only trigger with non-record seeds, so the class ends there.

Blocking: none.
Non-blocking: (1) the dev report's resolveRecordIdParamSeed justification is misattributed (api handler, not the flow door) — the shipped text does not carry it; (2) flows.mdx omits the legacy trigger route from its door list; (3) service-automation could equally be minor; (4) A3 and the boundary-1 reachability claim were not re-measured here.

Implemented-by: claude/issue-19846-automation-caller-provenance
Reviewed-by: session_01Sfe5YjBLwB9J3y8fvm2xq1 — at-tier review subagent spawned by the domain:spec#5 seat

VERDICT: PASS