fix(spec): register plugin-approvals as a second emitter of RESUME_FAILED

[os-bill]

Fixes #17909

Clause-②: yes

packages/spec declared ResumeFailureReport.code: ErrorCode as required and prescribed RESUME_FAILED in its docblock, but the provenance ledger listed that code only under @objectstack/rest. So the only correct implementation stamps a registered code its own owner key does not list, and check:error-code-provenance refuses it. This adds the missing provenance row under @objectstack/plugin-approvals.

The measurement the card declared NOT MEASURED

The card recorded its causal link as derived from the guard's stated rule, not from the guard's own output — a fresh worktree answered tsx: not found. Dependencies installed, the guard run, and here is its own text.

Before — branch base 5741ff10c30, ledger unchanged, PR #17908's stamp site injected from its head 109c9ce13:

scanned 2301 files; 336 registered-code stamp site(s): 318 listed, 17 waived

FAIL — 1 stamp site(s) of a registered code with no provenance row:
  @objectstack/plugin-approvals stamps 'RESUME_FAILED' (objlit) at packages/plugins/plugin-approvals/src/approval-service.ts:3370 — not listed under its own owner key

VERDICT guard-exit=1. Exactly one violation, exactly the site the card names.

After — this PR's row, same injected stamp site:

scanned 2301 files; 336 registered-code stamp site(s): 319 listed, 17 waived
OK — every registered-code stamp site is listed under its own owner key or carries a recorded waiver (10 waiver(s), all live)

VERDICT guard-exit=0, and the listed count moves 318 to 319 — the site is admitted as listed, not waived.

The card frames this as one code; it is three, and only one is stamped

The member's docblock names RESUME_FAILED, RESUME_TARGET_LOST and RESUME_IN_PROGRESS. Measured on the tree, not inherited:

code	ledger owner	who stamps it in a scanned position
RESUME_FAILED	@objectstack/rest (:287)	rest's catch maps the message prefix to a status, via a variable — not a literal the scan sees. plugin-approvals stamps the literal, once, at approval-service.ts:3370 (new in #17908). The row this PR adds.
RESUME_TARGET_LOST	@objectstack/rest (:288)	nobody, in a scanned position. plugin-approvals throws it as a message prefix (approval-service.ts:3189); rest's catch maps that prefix. No row owed.
RESUME_IN_PROGRESS	@objectstack/service-automation (:1044) — not rest, correcting the dispatch's open premise	service-automation/src/engine.ts:5795 and :6165, which its own owner key already lists. plugin-approvals only compares it (:3304). No row owed.

Why a row and not a waiver — the precedent's own predicate, applied

The EXTERNAL_IMPORT_ERROR waiver states the test plainly: the door's catch "stamps this code itself for EVERY importObject throw and never reads the producer's declaration — the door names the wire vocabulary." Both halves fail here, and the second decisively:

• resumeFailure rides a success answer. The REST approvals door serves decide / recall with res.json(out) (rest-server.ts), which copies the service's result verbatim — there is no envelope for the door to stamp on that path.
• git grep resumeFailure packages/rest/src matches nothing. The door neither stamps nor reads it. The producer's literal is the wire value.

The door's handleApprovalError catch is a real second moment, and it is the throw path — already covered by rest's existing row. This PR does not touch it.

⛔ The gate is not evaded. The literal stays exactly where it is; nothing is hoisted into a constant to dodge the textual scan.

Ablation and cost direction

Each leg mutates on disk, proves the mutation landed by occurrence count, runs the guard, and restores under a trap verified by git hash-object against the HEAD blob plus an empty git diff HEAD. The guard is a tsx script importing ../src/api/error-code-ledger.zod — source, no dist interposed, so no build sits between the edit and the reading.

leg	mutation	expected	measured
ablation	remove the row, keep the stamp site	reds, same site	exit=1, @objectstack/plugin-approvals stamps 'RESUME_FAILED' … at …:3370, listed back to 318
cost direction	keep the row, stamp RESUME_TARGET_LOST instead	still reds — the row must not over-permit	exit=1, names RESUME_TARGET_LOST at :3290. The row admits exactly the one code measured
#15970 coverage	keep the row, stamp RESUME_FAILED at two sites	green — a row is package-scoped	exit=0, 320 listed

Does this unblock #15970?

Yes, conditionally, and the condition is measured rather than asserted. The guard reconciles on (package, code), not on line number, so any number of RESUME_FAILED sites inside @objectstack/plugin-approvals are admitted by this one row — the third leg above proves it with two sites. ApprovalRecallResult.resumeFailure is the same member type in the same package, so an implementation that stamps RESUME_FAILED is covered with no further ledger edit.

⚠️ It is not covered if #15970's implementation stamps RESUME_TARGET_LOST for a lost run: the cost-direction leg is exactly that case, and it reds. That is the intended narrowness, not a gap — that code's wire emission belongs to rest's catch, and if a producer ever stamps it on a success answer it owes its own reading, not a pre-emptive row.

Clause ② and the changeset level

Declared Clause-②: yes, measured rather than argued: node scripts/pm/check-widening-tells.mjs --declaration no answers exit=4 with ✗ T4 … a new registration in a registry / catalog at error-code-ledger.zod.ts:1084; with --declaration yes it answers exit=0. The ledger's own header agrees — "Registering a code widens this face and is therefore a Clause-② change, door or no door." The changeset is minor accordingly.

⚠️ Worth a reviewer's eye, and stated rather than hidden: nothing an implementation may now emit actually changes. RESUME_FAILED was already in the registered union under rest, so no response can carry a code it could not carry before — the per-package rows are provenance, not identity, as this file's header says. The yes is the conservative direction, not a claim that the accept set grew.

needs:contract-review is hung on this PR.

Verification

check	verdict
pnpm --filter @objectstack/spec check:error-code-provenance	exit=0
pnpm --filter @objectstack/spec test (--project local)	exit=0 — 473 files passed, 1 skipped; 13483 tests passed, 1 skipped
pnpm --filter @objectstack/spec test:repo (--project repo)	exit=0 — 31 files, 523 tests passed
pnpm --filter @objectstack/spec typecheck	exit=0
pnpm check:nul-bytes	exit=0 — 8541 text files scanned
pnpm check:error-code-casing	exit=0
pnpm check:dispatcher-error-vocabulary	exit=0
spec gate family (check:liveness, check:duration-unit-keys, check:empty-state, check:variant-docs, check:llms-txt, check:skill-refs, check:strictness-ledger, check:yaml-examples, check:objectui-pin-citations, check:export-origins)	all exit=0

| pnpm --filter @objectstack/spec build + check:api-surface / check:authorable-surface / check:docs / check:exported-any / check:dual-source-exports / check:entry-nameability / check:browser-reachable-entries / check:generated | all exit=0 — no generated artifact moves |
| derived gate sweep (node scripts/pm/dispatch-gates.mjs --commands, all 78 families, reconciled with --ran) | 75 exit=0, 3 exit=3 NOT MEASURED |

The three NOT-MEASURED families are check:doc-formula-expressions, check:dual-build-cjs-loads and check:lean-entry-closure — each exits 3 with PREREQUISITE NOT MET, wanting a repo-wide pnpm build this diff does not otherwise need. CI's Build Core supplies it; recorded as not measured, ⛔ not as green.

Heavy steps ran through scripts/pm/os-verify-lock.sh on a shared box; verdicts are read from each command's own exit code captured before any pipe.

维护者速读(草稿)

改了什么。 packages/spec/src/api/error-code-ledger.zod.ts 里,在 '@objectstack/plugin-approvals' 的 owner key 下加了一行 'RESUME_FAILED',附带记录 wire 路径的注释;外加一份 minor changeset。一个数据表条目,没有新导出符号,没有已发布载荷上的新键。

为什么改。 spec 自己把 ResumeFailureReport.code 声明成必填并在 docblock 里点名 RESUME_FAILED,却没给会填它的那个包登记 provenance 行 —— 于是"照声明实现"这件事本身会被姊妹门禁 check:error-code-provenance 拒收。第一个来填槽的实现者只是第一个发现的人。这一行把声明补齐。

风险与代价(含回滚)。 风险低:RESUME_FAILED 本来就在已注册并集里(挂在 rest 名下),这一行只改 provenance 归属,不让任何响应能带上它此前带不了的码。代价是一条 minor changeset(条款② 的机械判据命中 T4,按保守方向申报 yes)。回滚 = 删掉这一行加这份 changeset,单文件 revert,无迁移、无数据、无 wire 影响。

席位意见。 (留空,待席位定稿)

你要做的。 确认两件事:(1) 同意这里走"加行"而不是"加 waiver" —— 判据是先例那句可测的话("门自己 stamp 且从不读生产者的声明")在成功路径上两半都不成立,证据在上面的 res.json(out) 与 packages/rest/src 零命中;(2) 条款② 申报为 yes 属于保守方向,而非真的放宽了接受集 —— 若你认为这类"已注册码的第二 emitter 行"不该触发契约复核,那是门禁 T4 的判据问题,值得单独立卡,⛔ 不在本 PR 处理。

Unblocks

• PR fix(automation): tell approval decide() callers when a subflow parent strands #17908 (service-automation: a subflow's bubbleToParent failure is swallowed, so an approval decision answers 200 resumed: true while the run behind it is stranded — #13807's three-outcome shape, one level up #15556) — blocked on this; its only failing step was Error-code provenance guard. #15556 is not addressed here.
• approvals: a recall whose resume strands reports it as an ordinary non-failure — no repairable discriminator, where the identical strand through decide carries one #15970 — covered for a RESUME_FAILED stamp, measured above. #15970 remains open.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

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

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

• content/docs/api/client-sdk.mdx (via ERROR_CODE_LEDGER (symbol, a top-level const object))
• content/docs/api/error-catalog.mdx (via ERROR_CODE_LEDGER (symbol, a top-level const object))
• content/docs/api/error-handling-server.mdx (via ERROR_CODE_LEDGER (symbol, a top-level const object))
• content/docs/kernel/contracts/data-engine.mdx (via ERROR_CODE_LEDGER (symbol, a top-level const object))

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

• content/docs/releases/v17/17-0.mdx (via ERROR_CODE_LEDGER (symbol, a top-level const object))
• content/docs/releases/v17/17-1.mdx (via ERROR_CODE_LEDGER (symbol, a top-level const object))
• content/docs/releases/v17/17-4.mdx (via ERROR_CODE_LEDGER (symbol, a top-level const object))

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

• 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 7135cf057e90dbe6d9177aef17e525da7277f68b → packageMentionDocs.

Which tree this was computed on

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

node scripts/docs-audit/affected-docs.mjs --json 7135cf057e90dbe6d9177aef17e525da7277f68b

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