feat(spec)!: the build doors judge an approval node config against its declared contract, whole — an undeclared key or a refused value is refused with a location

[objectstack-fleet]

Fixes #21850
Clause-②: yes (narrowing)

The build doors now judge an approval node's config against the contract the spec declares for it, ApprovalNodeConfigSchema, whole. escalation.bogusKey and escalation.timeoutHours: 0.5 are each refused with a location at FlowSchema.parse, objectstack validate and objectstack compile. Before this, both exited 0. The existing alias text ("did you mean timeout → timeoutHours") stays in the refusal. No plugin is loaded at build time, and no node type joins the map unless the spec declares its contract.

Draft. Patch round 1 adds the one domain:services fixture line that the claim revision now covers (see "The one domain:services fixture" below).

Two route changes, both measured before the edit

The dispatch route was to put approval into getBuiltinNodeConfigContracts beside the 13 builtins. I tried exactly that on the pristine base (5e0b489bca), rebuilt spec (the dist preflight found the marker in 20 built files) and measured two problems:

1. The builtin map is reconciled 1:1 against the builtin executors. service-automation's node-config-contract-ledger.test.ts reads every parseNodeConfig call in its own builtin/ sources. With approval in the map, 2 of its 5 tests went red: "the map names exactly the node types an executor parses a config contract for" and "every builtin node type is classified". That ledger is domain:services code, so this PR cannot change it.
2. The judge only checks for missing keys. flowNodeConfigRefusals keeps an issue only when the key it names is absent. The shipped flow-node-config-required-keys-refused entry says the same thing. With approval in the map, FlowSchema still accepted both card pins (success: true). Only an approval node with no approvers was refused.

What this PR does instead:

• A declared contract map beside the builtin one. getDeclaredPluginNodeConfigContracts() is private to the module, holds [APPROVAL_NODE_TYPE, ApprovalNodeConfigSchema], and is built on first use, never at module load. The same judge reads it. approval.zod.ts imports nothing from automation/ (zod, the membership-role leaf, lazySchema, strictObject), so no import cycle is added.
• That map is judged whole. The approval executor (plugin-approvals, approval-node.ts) runs safeParse on node.config before it does anything else and fails the node on any issue, so every issue the contract raises is refused:
  • An undeclared key, or a refused value, gets the new closed-set code node-config-refused-by-contract with params: { nodeType, key }. It is anchored at the key: escalation.bogusKey, or one refusal per key for top-level keys.
  • The message wraps the contract's own sentence, including its did-you-mean.
  • A missing required key keeps node-config-key-missing or node-config-key-required-by-rule.
• The builtin arm does not change. It still only checks for missing keys. A control test pins it: an http node with an undeclared key still parses.
• getBuiltinNodeConfigContracts keeps its export, shape and contents (the 13 builtins). A caller who looks up approval gets undefined. The approval contract is reachable through the exported judge, flowNodeConfigRefusals('approval', config).

Census, before any edit (at 5e0b489bca)

I wrote a census script that walks the TypeScript AST and checks every literal approval node config with ApprovalNodeConfigSchema.safeParse. Non-literal configs were read by hand. Lit controls: the same search pattern finds decision nodes in app-crm and app-todo, which author flows but no approval nodes, and it finds the known showcase hit dynamic-approval.flow.ts.

• examples/**: 15 approval nodes, all in the showcase, all accepted.
• content/docs/**: 6 snippets, accepted (3 by the script, 3 by reading).
• skills/**: 5 snippets, accepted.
• packages/qa/dogfood fixtures: 6 nodes, accepted.
• objectui at the pin 0abd4f9f87, read-only: the designer's approval seed defaultNodeExtras('approval') ({ approvers: [{ type: 'manager' }], behavior, lockRecord }) is accepted. objectui's flow-canvas-seeds.spec-parse.test.tsx parses seeds with FlowNodeSchema, which never calls this judge. flow-required-keys.ts asks the judge only whether some refusal names the probed path, and nothing here changes that answer for a missing key.
• hotcrm: NOT MEASURED, because the session's permission check denied the read-only clone.

No real writer is refused. In test code, 5 fixtures needed changes. They are listed under "Fixtures" and under "The one domain:services fixture".

Reproduction, before and after (a scratch copy of the showcase)

I added an escalation block to the co_sign approval node in dynamic-approval.flow.ts. The script proved each edit landed on disk and restored the file byte for byte afterwards.

variant	5e0b489bca (main)	this branch
control { timeoutHours: 2, action: 'notify' }	validate 0 · compile 0	validate 0 · compile 0
{ timeoutHours: 2, action: 'notify', bogusKey: 1 }	validate 0 (✓ Validation passed) · compile 0 (✓ Build complete), bogusKey written to dist/objectstack.json	validate 1 · compile 2, custom at nodes.2.config.escalation.bogusKey
{ timeoutHours: 0.5, action: 'notify' }	validate 0 · compile 0, 0.5 written to the artifact	validate 1 · compile 2, custom at nodes.2.config.escalation.timeoutHours

Branch wording at the validate door: "This approval node's config is refused at escalation.bogusKey by the approval contract: Unrecognized key(s) on this approval escalation: bogusKey. …". For the timeout alias, the contract's "Did you mean timeout → timeoutHours?" is carried through, next to the escalation.timeoutHours key-missing refusal.

Doors pinned (flow-approval-node-config-contract.test.ts)

Each door has a valid approval node as its control:

• FlowSchema refuses both pins, and the alias, top-level undeclared keys, a missing approvers and a rule finding (onEmptyApprovers: 'fail' together with fallbackApprovers).
• A sweep checks that the judge refuses exactly what the contract refuses.
• defineStack refuses with STACK_SCHEMA_INVALID / 422 at flows.1.nodes.1.config.escalation.bogusKey.
• ObjectStackDefinitionSchema refuses. This is the stack parse that validate and compile run.
• The registered flow type schema used by the metadata save door refuses.
• The artifact parse refuses.
• The validateStackExpressions door shows up in @objectstack/lint's run as flow 'leave_approval' · node 'approve' (approval) config.emptyApproverPolicy.

Ablation. I committed the fix first, then deleted the [APPROVAL_NODE_TYPE, …] entry with scripts/ablation-replace.mjs: anchor count 1 → 0, blob f915eb58bcd0 → 90e86f48dcc4. The subject resolves through src by relative import, so no build was involved.

• Prediction: 14 red, made up of 12 refusal tests in the new file plus 2 in flow-slot-refusal-codes.test.ts (the new code's pin, and "every code is reached").
• Result: Tests 14 failed | 26 passed (40), matching the prediction.
• Restore: blob equal to HEAD and git diff HEAD empty.

The ADR-0087 kit

• D3 entry. entries/semantic/18.flow-approval-node-config-contract-refused.ts, with its registry.ts region regenerated by gen:migration-registry.
• Step-18 rationale. A fragment at order 84. I re-read origin/main at e085a8c3be before opening this PR, and again at 67c544ccca in patch round 1: the highest order there is 83, and this id is absent. If security(data): a predicate-scoped update or delete is refused when its predicate matches only rows the caller cannot read, and succeeds with zero rows when it matches nothing: an existence signal the read door withholds #21829 or automation: an approval node's escalation values are checked only at execution — timeoutHours 0.5 registers and activates, then every run fails and the record is created with no approval gate #21848 also takes 84, the two fragments render in id order, as the registry header allows.
• No tombstone and no D2 conversion. No key is removed, and a refused node holds no intent that a rewrite could keep.
• Changeset. One BREAKING minor changeset for @objectstack/spec with the registered marker and the Clause-② line, at the level the precedents set (fix(spec)!: refuse a flow node config its executor cannot run — a required key left out, or a decision branch list it cannot read — at all three doors (#20316) #20416, feat(spec)!: FlowSchema refuses a create_record, update_record or delete_record node whose static objectName is a stored-metadata table, with the runtime's prescription (#21654) #21687). check-adr-0087-registration: [BREAKING+clause-②-narrowing] registered flow-approval-node-config-contract-refused.
• Regeneration. check:generated passes all 15 generated artifacts. None changed apart from the registry region, because the public exports did not change.

Fixtures

These fixtures fed the narrowed rule. Each one was re-judged:

• spec/.../flow-region-pause-and-end.test.ts: the pausingNode('approval') fixture had no config and is now refused for missing approvers. Fix: it now declares the one key the contract requires, approvers.
• lint/src/runtime-gate.test.ts, metadata-protocol/src/protocol.runtime-authoring-gate.test.ts, objectql/src/plugin.authoring-channel.test.ts: the "clean" approval flow in all three is a copy of one worked example, and it carried emptyApproverPolicy: 'reject'. That key was never declared by the contract, and the executor would have refused the node on every run. Fix: deleted the key. The flow is then the broken flow with its expression fixed, which is what those tests mean by "clean". These files are outside the original claim; claim revision round 1 covers them.
• spec/.../flow-slot-refusal-codes.test.ts: added a pin per new code and approval rows in the sweep. Its message pins follow the file's existing per-code convention.

The one domain:services fixture (patch round 1)

packages/services/service-automation/src/engine.test.ts, test "says nothing about a type a plugin registered AFTER the flow": its baseFlow('approval') helper registered an approval node with no config. registerFlow runs FlowSchema.parse first, so it now refused that node with nodes.1.config.approvers. The test is about sealing the node-type vocabulary, not about config. The claim revision covers this file. The only change is one line in the helper: an approval node now gets config: { approvers: [{ type: 'user', value: 'u1' }] }. That is the same disposition as pausingNode above. No service-automation source changed. service-automation now passes 2110/2110.

Relation to #21848 (#21848 remains open)

AutomationEngine.registerFlow runs FlowSchema.parse before anything else (engine.ts:4348), so this PR also makes registration refuse approval values like timeoutHours: 0.5, on every door that registers through it. That overlaps #21848's done-when and does not contradict it. Its seat should re-read what is left of its scope: package load paths that do not go through FlowSchema, and its own registration pins. The stable reuse point is the exported flowNodeConfigRefusals, not a second lookup. getBuiltinNodeConfigContracts().get('approval') returns undefined.

Verification (final union at 76118d27fe)

Tests

• @objectstack/spec: test 617 files / 18447 passed, exit 0; typecheck exit 0. Measured at 3fc48ab07f; patch round 1 changed no spec file.
• @objectstack/lint: before the fixture fix, the full suite had 2 failures, both in runtime-gate. After the fix, that file passes 46/46.
• @objectstack/metadata-protocol: before the fixture fix, 3 of the 4 files with approval fixtures passed. After it, the fourth passes too: protocol.runtime-authoring-gate.test.ts 70/70.
• @objectstack/objectql: the full suite at 76118d27fe passes, 374 files / 7464 tests, exit 0.
• @objectstack/http-conformance: the full suite at 76118d27fe passes, 8 files / 102 tests, exit 0.
• @objectstack/plugin-approvals: 895/895.
• @objectstack/service-automation: the full suite at 76118d27fe passes, 172 files / 2110 tests, exit 0. Typecheck exit 0.
• @objectstack/cli: test/authoring-rule-command-parity.test.ts 11/11, in its integration tier.
• Typecheck for lint, objectql and metadata-protocol: exit 0 each.

Gates

• dispatch-gates --ran at 76118d27fe: 96 derived, 96 run, 0 NOT-MEASURED, 0 unrun. The patch round adds check-tenant-audit-census and its --self-test, and both pass.
• check:dual-build-cjs-loads: exit 0 after a full build supplied the 8 missing dist/ folders. 106 require entry points across 66 packages load.
• check-engine-split-ratio --days 90: exit 2, refused on a shallow clone (oldest visible commit 2026-09-20). It is recorded as run, and its metric is not measured here.
• check:type-check-debt: exit 0, "none above its recorded number".

ESLint, narrowed to the changed files and shown to cover them

1. Population: ESLint's own isPathIgnored reports all 12 changed .ts files as linted.
2. Count: --format json reports 12 files, 0 errors, 0 warnings, at 76118d27fe.
3. Untouched files: eslint.config.mjs enables no type-aware linting (no parserOptions.project), so this diff cannot change the result for any file it does not touch.

Declared to CI: the full pnpm lint, the dogfood suite (the census found all 6 dogfood approval fixtures accepted), and the rest of the cli integration tier.

Acceptance notes (not filed)

• objectui's flow inspector (flow-node-config.ts:996) writes config.escalation.enabled. Its timeoutHours field only shows while enabled is 'true', so switching SLA escalation off can save escalation: { enabled: false } with no timeoutHours. The contract refuses that, and the executor already refused it on every run; it is now refused at save, at escalation.timeoutHours. This comes from reading the source; I did not drive the designer. Owner: none.
• When defineFlow throws while the CLI loads its config, the CLI prints the raw ZodError JSON, with a path relative to the flow and no flow name or file. This is existing behaviour for every defineFlow refusal.
• Nothing in plugin-approvals checks the approval executor's safeParse against the declared map, the way the builtin ledger does for builtins. That check would live in plugin-approvals (domain:services). automation: an approval node's escalation values are checked only at execution — timeoutHours 0.5 registers and activates, then every run fails and the record is created with no approval gate #21848's PR is the natural place for it.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/spec, touching 12 documentable anchor(s).

3 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/automation/flows.mdx (via FlowSchema (symbol, a top-level const))
• content/docs/deployment/cli.mdx (via unrecognized_keys (literal, a string literal in flowNodeConfigRefusals; a string literal in unrecognizedKeysOf))
• content/docs/protocol/objectql/types.mdx (via unrecognized_keys (literal, a string literal in flowNodeConfigRefusals; a string literal in unrecognizedKeysOf))

⛔ 2 release-owned page(s) also name something this change touched. These are read-only:

• content/docs/releases/v17/17-0.mdx (via FlowSchema (symbol, a top-level const), unrecognized_keys (literal, a string literal in flowNodeConfigRefusals; a string literal in unrecognizedKeysOf))
• content/docs/releases/v17/17-4.mdx (via FlowSchema (symbol, a top-level const))

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

What this run could not see

• 6 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 54 of 206 client-bound route-ledger rows — the other 152 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 152: 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; 97 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 — 138 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 67c544cccab757d5c27296a4265246c7e3dfffc0 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 8c983543a1a016be212f9d8cdcc22cd5889fff30 — the merge of head 76118d27fe2ed2592da573f73a23c186dc14e063 into base 67c544cccab757d5c27296a4265246c7e3dfffc0, 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 8c983543a1a016be212f9d8cdcc22cd5889fff30 && git checkout 8c983543a1a016be212f9d8cdcc22cd5889fff30
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 67c544cccab757d5c27296a4265246c7e3dfffc0 76118d27fe2ed2592da573f73a23c186dc14e063 && git checkout -B drift-repro 67c544cccab757d5c27296a4265246c7e3dfffc0 && git merge --no-ff 76118d27fe2ed2592da573f73a23c186dc14e063

node scripts/docs-audit/affected-docs.mjs --json 67c544cccab757d5c27296a4265246c7e3dfffc0

⚠️ 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 67c544cccab757d5c27296a4265246c7e3dfffc0 → pass the list as
args.docs, on the commit named under Which tree this was computed on.