fix(automation): require the wait / boundary_event config block at the contract, retire the executor's silent timer default

[os-warren]

Fixes #17928

A wait flow node with no waitEventConfig block parsed clean and ran to { success: true, suspend: true } — parked forever, reporting success, from the state a freshly created node is in. This PR makes the protocol refuse that document, makes the executor refuse it loudly when a stored one still reaches execute, and settles the two default-free optional keys the same ruling covers.

⚠️ Takeover of an orphaned branch. Five commits were already on claude/issue-17928-wait-node-config-required when this session picked it up; their author's session died before a PR existed. They were diffed and judged, not trusted, and their history was not rewritten — everything since is added on top.

The ruling this implements

Maintainer, decision batch #127 item 5 (C′), recorded on objectui#9354, verbatim and untranslated:

「16678 具体解释，计划用哪个字段判断经理。其他同意」

C′ as presented: the protocol is the source of truth; a designer never invents a default the protocol does not apply; a default the protocol should have is declared by the protocol; a required key has no "unset behaves as".

What lands

A — the contract stops accepting the silent shape (packages/spec)

FlowNodeSchema now requires waitEventConfig on a type: 'wait' node and boundaryConfig on a type: 'boundary_event' node, and the inline waitEventConfig block in flowNodeObject() requires a non-blank timerDuration under eventType: 'timer'. There is no WaitEventConfigSchema export — the block is declared inline, and this body said otherwise until the review round. Each issue is raised under the block's own key, so a flow-level parse reports a top-level node at nodes[i].waitEventConfig with the remedy in the message.

⚠️ Where the refusal bites, stated accurately. A node nested in an ADR-0031 region body is refused at a different door, at a different time. parseFlowNodeRegions parses each region slot with safeParse and, on a refusal, leaves that region raw and continues — a policy that predates this change — so FlowSchema.safeParse of a flow whose loop body holds a block-less wait answers true. What refuses it is the region contract (LoopConfigSchema / ParallelConfigSchema / TryCatchConfigSchema) at body.nodes[i].waitEventConfig, which is the same contract the container node's executor parses its config through at execute time — so the nested shape still cannot run, it is refused one door later and by node id. Both halves are pinned in flow.test.ts ("nested in a region: the flow parse leaves it raw, and the REGION contract refuses it by path"), and the ADR-0087 entry's acceptanceCriteria has said so from the start.

⚠️ The timerDuration requirement is BLOCK-scoped, not node-type-scoped. It sits on the waitEventConfig block, so any node type carrying that key is held to it: FlowNodeSchema.safeParse of a start node spelled waitEventConfig: { eventType: 'timer' } answers false at this head and true on main, with both controls green (the same node with timerDuration: 'PT1H', and a plain start with no block, both true). It only ever narrows, and the block is inert on node types no executor reads it from, so the practical reach is wait — but a stack that spells the key elsewhere must be edited too, which is why the changeset and the migration entry now say "scan for the KEY, not only for the node type".

⛔ The two required enums (wait.eventType, boundary_event.eventType) get no default: a required key has no "unset behaves as", and an indefinite park, if one is ever wanted, is its own declared eventType.

B — the executor follows the contract (packages/services/service-automation)

wait-node.ts carried (node.waitEventConfig ?? {}) and String(wec.eventType ?? 'timer') under a comment declaring the second deliberate — "a wait node without one is a VALID TIMER WAIT". Both fallbacks are retired and the comment is deleted with the reversal named. A node that still reaches execute without the block (a stored pre-migration document on a path that skipped the parse) is now a guard refusal — errorClass: 'guard', so a fault edge cannot route a metadata defect into a handler that reports success — and it logs, naming the node and the remedy, because the defect being closed was silence. Two corrections ride the same return: the timer branch stops answering output as a present key holding undefined, and it is absent when no deadline was computed.

boundary_event gets the contract half only: the runtime registers no executor for that type at all (NO_EXECUTOR plus a startup warn), so there is no silent executor branch behind it.

C — the two optional keys, decided by reading the executors rather than the Zod

key	what the executor applies for an absent value	declared
ScreenConfig.mode	'create' — screen-nodes.ts:199 builds the ScreenSpec with mode: cfg.mode === 'edit' ? 'edit' : 'create'	.default('create')
HttpConfig.method	two values — http-nodes.ts:218 inline cfg.method ?? 'GET', :168 durable cfg.method ?? 'POST'	⛔ none

Declaring .default('GET') on method would materialise GET at parse time, the durable arm's own ?? 'POST' would never fire again, and every stored durable callout that omits the method would silently change verb — the defect this card exists to end, pointed the other way. That asymmetry is recorded in both files so the next reader does not "finish the job".

Migration and declaration

• ADR-0087 D3 semantic entry wait-node-event-config-required under step 18 — a stored block-less wait node has no lossless conversion, because the missing value is an intent no artifact records, so the entry is a structured TODO naming each node to edit (os migrate meta --from 17). Registered by regeneration: packages/spec/src/migrations/registry.ts carries a GENERATED block and check:migration-registry reconciles it against src/migrations/entries/.
• Changeset: minor on @objectstack/spec and @objectstack/service-automation with a BREAKING banner and its FROM → TO mapping — minor because the launch-window convention ships breaking changes as minor (scripts/check-changeset-no-major.mjs), never major.
• Clause-②: no, and it was re-measured rather than inherited: check-widening-tells --declaration no over the whole diff exits 0 with zero tells. .default('create') does not widen the accept set — a key that accepted absent/undefined still does; what moves is the OUTPUT type, which gets narrower ('create' | 'edit' where it was 'create' | 'edit' | undefined). The declared-default plumbing it needs already existed (authorable-defaults/automation.json + DEFAULT_CHANGES_BY_MAJOR), so this adds one entry to each rather than a mechanism.

Verification

Gates. All 116 families derived by node scripts/pm/dispatch-gates.mjs --commands from the actual 17-path change set were run, exit codes written to disk before any output was read, and reconciled with --ran: 116 derived, 116 run, 0 NOT-MEASURED, 0 UNRUN, every code 0. Five needed a second pass and none of them was a red:

family	first pass	why it was not a verdict	after
check:dual-build-cjs-loads · check:i18n · check:type-check-debt	exit 3	PREREQUISITE NOT MET — the gate reads built output and the repo was not fully built	all 0 after turbo run build over every workspace package (72/72 successful)
check:skill-examples	exit 1	refused on packages/client-react/dist holding no declarations — a stated refusal to compute a verdict, not a finding	0
check-plugin-teardown-shape --self-test	exit 1	its positive control is pinned to a commit this shallow checkout could not reach; checker-health only, it cannot judge this diff	0 after fetching that commit — 47 cases pass

check:type-check-debt OOM'd on the second attempt too: the gate pins a CI-shaped 6144 MB ceiling and reports that the caller's NODE_OPTIONS is the tighter one. Raised to 8192 for that one command, on that stated reason; it then re-measured 5 ledger entries, 55 raw errors, none above its recorded number.

Tests (affected packages, plus the consumer package already in the diff):

package	result
@objectstack/spec	477 files / 13602 tests passed
@objectstack/service-automation	135 files / 1599 tests passed
@objectstack/plugin-approvals	45 files / 738 tests passed
typecheck, all three	pass, including each package's check:test-typecheck

Reverse verification of the cross-package type narrowing — one-shot, both legs run from the committed state, the restore leg proven by blob hash rather than by an exit code:

HEAD blob             c9f88d74df30174720a85e1747e7a5ae5c1681ef
mutated blob          220adfac111a1b6e7229ad64a3e8292eb7810095   (probe really on disk)
MUTATED_TSC_EXIT=1    src/builtin/screen-nodes.ts(391,7): error TS2322:
                      Type 'undefined' is not assignable to type '"create" | "edit"'.
RESTORED_TSC_EXIT=0   git diff HEAD empty, blob back to c9f88d74

The probe was ScreenConfigParsed["mode"] = undefined in a consumer that imports the type. It compiles green against the OLD declaration and red against the new one, so the red proves service-automation resolved the rebuilt packages/spec/dist/*.d.ts and not a cached optional mode.

The corpus parses. examples/app-showcase builds its 30 flows through the narrowed contract with no edit, and a repo-wide sweep for type: 'wait' / type: 'boundary_event' in every spelling (TS, JSON, YAML, MDX) found no other fixture needing the block. The one that did — plugin-approvals' ADR-0044 revise-window flow — is in the diff, and its fixture now declares { eventType: 'signal', signalName: 'revision_submitted' } so the send-back refusal it pins is measured against a flow that still registers.

Acceptance notes

• ⭐ A malformed or zero-valued timerDuration still reproduces the silent park — out of scope for this PR, reported for triage to file. The contract can require the key but cannot evaluate the string: parseIsoDuration answers undefined for 'not-a-duration', for 'P', for 'PT0S' and for '0' exactly as it did for the absent key, so no deadline is computed, no job is armed, no waitUntil is persisted, and the node still returns { success: true, suspend: true }. The repro is live in the tree: wait-node.test.ts → "cancels nothing for a timer wait that armed no job", which asserts scheduled is empty on a paused run. It was left out deliberately — a format refinement narrows the accept set beyond what the ruling covers and adds a validation surface this card's gate families do not carry. A fixture comment on that branch previously claimed it was "Filed separately"; no card exists, and the comment is corrected in this PR rather than left asserting a filing nobody made.
• In-place fix beyond this card, declared. parseEndNodeConfig's docblock in the same file carried the identical false clause — "Applied at the NODE level so an end nested in a region is checked exactly like a top-level one" — predating this branch (A flow cannot REFUSE with per-record text: the only channel that interpolates is a screen description, and a message-only screen still renders Submit and toasts "completed" #14945). It is the same sentence, the same file, the same mechanism and the same published-to-npm surface, so leaving it would have shipped a file that contradicts itself two docblocks apart. Measured before correcting, not assumed: FlowNodeSchema.safeParse of a top-level end carrying { outcome: 'refused' } and no message answers false; the identical node nested in a loop body passes FlowSchema.safeParse (true) and is refused only by LoopConfigSchema, at body.nodes.0.config.message. The clause is removed and cross-referenced to the one explanation so the two cannot drift. Prose only — no behaviour change, and end config handling is untouched.
• The four non-timer eventTypes still carry no required resumer key of their own — { eventType: 'signal' } with no signalName parses, and the executor correlates on undefined. Noted, not filed: no separate carrier, and it is the same shape as the row above rather than a second one.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 2 package(s): @objectstack/service-automation, @objectstack/spec, touching 13 documentable anchor(s). ⚠️ 1 changed file(s) yielded no anchor (packages/spec/authorable-defaults/automation.json), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

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

• content/docs/automation/flows.mdx (via boundaryConfig (literal, a string literal in requireTypeScopedConfig), boundary_event (literal, a string literal in flowNodeObject; a string literal in requireTypeScopedConfig), timerDuration (literal, a string literal in flowNodeObject), waitEventConfig (literal, a string literal in requireTypeScopedConfig))
• content/docs/deployment/cli.mdx (via api_call (literal, a string literal in requireTypeScopedConfig))

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

• content/docs/releases/v17/17-0.mdx (via FlowNodeSchema (symbol, a top-level const), timerDuration (literal, a string literal in flowNodeObject), waitEventConfig (literal, a string literal in requireTypeScopedConfig))

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

• 1 changed file(s) yielded no anchor (packages/spec/authorable-defaults/automation.json) — pages documenting those are invisible to this run
• 4 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.

Coarse fallback — 136 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 ba9b4981cd6a111af47bc71741106467ef8f8359 → packageMentionDocs.

Which tree this was computed on

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

node scripts/docs-audit/affected-docs.mjs --json ba9b4981cd6a111af47bc71741106467ef8f8359

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

[os-warren]

In-seat clause-② contract review — PASS, pinned to 14cb2a66b37baba0150e5784ab6376e553a6664d

domain:spec execution seat, session_01KB5PFtxuy1x3dcR5gxudx6, 2026-09-14T10:5xZ. This is the record the enqueue gate requires: the diff touches packages/spec/src/**, so the path limb is hit and ⛔ no enqueue may happen without an in-seat review PASS on file — regardless of the claim's Clause-②: no.

CLAUSE_2: no — VERDICT: PASS. The declared no is correct: the diff narrows on every axis it touches and widens on none.

Why this went to a subagent, and how the tier was verified

⚠️ This seat is served by claude-opus-5, which is BELOW CONTRACT_REVIEW_TIER (claude-fable-5-1, read from scripts/pm/dispatch-gates.mjs:10689). Under the downgrade fuse the seat ⛔ does not self-judge clause ②; the review was run by an at-tier subagent and the tier was verified per transcript, ⛔ not from its self-report:

transcript	"model" field count
the reviewer	106 × claude-fable-5-1
the os-dev control (same round, this card's implementer)	161 × claude-opus-5

⇒ The extractor discriminates between the two tiers on this harness, so the at-tier reading is a true positive rather than a field that always prints the same string.

The readings that carry the verdict

• Accept-set differential on the real schemas, both trees — 3,421 inputs (19 node types × 20 waitEventConfig variants × 9 boundaryConfig variants): main accepts 1141, head accepts 821. WIDENED (head accepts what main refused): 0. NARROWED: 320. No sibling arm was loosened to compensate — the unchanged cells were enumerated and match main exactly.
• .default('create') on ScreenConfig.mode — 14 inputs incl. absent, undefined, null, '', 'CREATE', 1, unknown key: inputs whose accept verdict differs: 0. Only the OUTPUT moves (absent ⇒ mode: "create" materialised); the published type narrows from 'create'|'edit'|undefined to 'create'|'edit'. The output-mode JSON Schema gaining required: ["mode"] is the pre-existing convention for every .default() key, measured against the ScheduleState.status precedent on main — ⛔ not introduced here. No enum gains a member.
• .default('GET') is not in this diff at all — HttpConfigSchema.method changed docblock only; 6/6 inputs identical verdict and output, emitted JSON Schema byte-identical in both io modes.
• New symbols / codes / keys: one export const entry in the new semantic entry (generator input; migrations/index.ts re-exports only registry.js, api-surface/automation.json untouched). requireTypeScopedConfig is module-private. Issue codes are Zod code: 'custom'; the executor reuses the pre-existing refuseNode. No new StandardErrorCode.
• ADR-0087 entry registered by REGENERATION, not by hand: build-migration-registry --self-test --check exits 0 on the head extract (217 semantic vs main's 216); positive control — mutating one word in the entry file flips it to ✗ stale, EXIT=1.
• Gate: check-widening-tells --declaration no exits 0 over the diff. Controls that make that zero a reading: --self-test 269 cases pass, and a synthetic one-key diff on flow.zod.ts correctly fires ✗ T1 … EXIT=4. ⚠️ The two known weaknesses of this gate (the retiredKey() false positive of [finding] check-widening-tells fires T1 on a retiredKey() tombstone line, so every ADR-0087 key retirement reads as a clause-2 widening for the one reason the accept set shrank #17955, the re-declared-key T1 blind spot of the widening refusal offers a remedy with no reader — "explain in the claim" moves no exit code (the T1 re-declared-key half did NOT reproduce) #17848) were checked and neither applies: no retiredKey( line is added, and the only re-declared key line is a pre-existing mode:.

Independence

Implemented-by: the mode:subagent dev on branch claude/issue-17928-wait-node-config-required. Reviewed-by: session_01KB5PFtxuy1x3dcR5gxudx6 (this seat), through an isolated at-tier review subagent fed only the card, its thread, the PR body and the tree. ⚠️ Stated plainly rather than implied: the implementer and the reviewer were dispatched from this same seat session, so this is in-seat review with tier separation, ⛔ not cross-seat independence.

⚠️ Scope of this PASS

It is pinned to 14cb2a66. A prose-only patch round is in flight (see the REWORK below); a comment/docblock change cannot move the clause-② axis, but this seat will confirm the patch is prose-only at the new head before enqueue rather than assuming it.

---

Generated by Claude Code