fix(tooling): dispatcher error-vocabulary scan reports lowercase codes and the three stamp positions it could not see (#9460)

[os-zhuang]

Fixes#9460

Widens check:dispatcher-error-vocabulary so it measures "is this code outside the vocabulary" instead of "is this code SCREAMING_SNAKE" — scope half (1) only, per triage. ⛔ No ledger edit, no allowlist entry, no narrowed pattern, no raised ceiling.

The card's premise was wrong, and the real shape is bigger

The issue diagnosed a case-sensitive pattern. It is not — assign, classfield and objlit already matched [A-Za-z]. Two explicit post-match filters dropped the value with a named delegate:

if (!/^[A-Z][A-Z0-9_]*$/.test(code)) continue; // lowercase -> check:error-code-casing

And the card's own motivating producer was invisible for a completely different reason, so the prescribed one-line widening would not have found it. Measured, not assumed:

scan	sites	new findings
today	12	—
naive case-widening (the card's literal prescription)	94	82, and owd_widening_forbidden is not among them
this PR	18	6, including owd_widening_forbidden

All 82 of the naive widening's new findings were D6/D6b/D6c neighbours or Zod's own issue codes — it reports ctx.addIssue({ code: 'custom' }) as an unregistered ObjectStack error code, which is simply false.

What was actually broken: a hole between two gates

check:error-code-casing needs a quoted lowercase literal beside the token code (code: 'x', .code = 'x', code === 'x', code?: 'x' | 'y'). In those positions the delegation is genuine — that gate reads the identical characters and carries the D6/D6b/D6c discrimination this one does not have, so objlit and assign keep delegating.

Everywhere else it was a hole, not a hand-off. A code arriving through a constant, a template, or a helper parameter has no quoted literal at the stamp site, so that gate is structurally blind — and this gate dropping it for its casing meant nobody reported it. Both gates read object-posture-gate.ts and both reported nothing, each leaving it to the other. Those shapes now carry lowercase: 'here'.

Three stamp positions the scan could not see

• codehelper — a file declares one factory and throws through it everywhere. The stamp (err as any).code = code knows the token code but not the value; the call site knows the value and never writes the token. The join is the parameter, so its index names the argument to read — derived, never assumed zero, because makeError(status, code, message) and exposureError(message, code, status) both put it second and a first-argument rule reads a number and an English sentence as error codes. Constructors count, and a call-site argument that is itself a constant goes through the existing resolveConstant.
• assignconst — err.code = DENY_CODE. check-dispatcher-error-vocabulary is blind to a non-literal code: in an object literal — a constant or template produces no finding, silently #9223 closed exactly this gap for object literals; the assign position kept it.
• assign with a cast on the left — the old anchor demanded a bare identifier where (err as any).code = 'X' puts a ).

Predicted, then observed

Predicted: the pre-change scan cannot see the six sites this one reports, so run against the same tree with the same declaration table it must call every one of them stale.

Observed — origin/main's script, this tree:

check-dispatcher-error-vocabulary: 6 finding(s)
[stale-row] ... 'FLOW_CONVERSION_CONFLICT' at packages/metadata-protocol/src/protocol.ts (assign) but the scan no longer finds it.
[stale-row] ... 'owd_widening_forbidden' at packages/plugins/plugin-security/src/object-posture-gate.ts (codehelper) but the scan no longer finds it.
[stale-row] ... 'NO_SUCH_RUN' / 'NOT_COMPENSABLE' / 'PLAN_CHANGED' / 'PREFLIGHT_FAILED' at packages/core/src/utils/migration-journal.ts (codehelper)
scope: ... 12 unregistered code-stamping site(s) found; 18 classified.

Six producers sitting in source that the old scan reports as "moved or went away". A zero-hit control is not a finding, so the widened pattern was also fed the known lowercase stamp directly and reported it by name.

Every new find: fixed or filed, none silently classified

Six new sites, all classified with evidence in dispatcher-error-vocabulary.ts, and the two substantive decisions filed rather than taken here:

• FLOW_CONVERSION_CONFLICT — live 409 from the metadata write path → pending-registration, door rest. Filed Two live wire codes are outside the ADR-0112 vocabulary, newly measured: FLOW_CONVERSION_CONFLICT (409) and owd_widening_forbidden (403) #9567 for the spec lane.
• owd_widening_forbidden — live 403, wire-verbatim → pending-registration, door rest. Filed Two live wire codes are outside the ADR-0112 vocabulary, newly measured: FLOW_CONVERSION_CONFLICT (409) and owd_widening_forbidden (403) #9567. ⛔ The producer's spelling is untouched and the ledger is untouched: half (2) is settled and registering or renaming is the packages/spec lane's call. pending-registration is the only honest verdict available (foreign-vocabulary would be false — it is a request refusal on a wire; boot-refusal would be false — it crosses HTTP), and it records a measurement, it does not prescribe a remedy.
• NO_SUCH_RUN, NOT_COMPENSABLE, PLAN_CHANGED, PREFLIGHT_FAILED — MigrationJournalRefusal, whose only consumers are two CLI commands with no HTTP boundary → boot-refusal, door none, the [finding] MONGODB_MULTI_TENANT_UNSUPPORTED may be registered-but-unemittable in the error-code ledger — a boot refusal never reaches a wire envelope #8035 precedent.

PENDING_LEDGER_REGISTRATION goes 0 → 2 and classified sites 12 → 18 — the ratchet moving in the direction it exists to move.

Residual gap found while measuring and filed, not fixed: #9568 — a code held in a local ternary of literals (sys-metadata-repository.ts's live 403 NOT_CREATABLE / NOT_OVERRIDABLE) is still unresolved. Named in the published bounds too.

⚠️Premise note, no action taken: the issue states #9232 already demotes this code at the flat door. On origin/main at 65d4fff it does not — packages/rest/src/meta-object-owd-gate.test.ts asserts the raw lowercase code on the wire, and no commit carrying that change is in the history. Recorded in #9567; out of scope here.

Verification — all at 7c1840e46, the final commit

check-dispatcher-error-vocabulary: OK — 18 unregistered code-stamping site(s), all classified; 2 awaiting a ledger entry (#8846).
scope: 1839 non-test source files under packages/; 292 registered codes (239 ledger + 53 standard); 18 sites found; 18 classified.
--self-test: 8 shapes + 81 assertions OK (was 6 shapes + 57)
check-error-code-casing: no lowercase error codes in 4212 scanned file(s)
check-cross-package-test-inputs / affected-docs / nul-bytes / changeset gates: OK
pnpm --filter @objectstack/runtime typecheck: clean
pnpm --filter @objectstack/runtime test: 169 files, 2515 tests passed

The self-test is pinned capable of failing, in both directions:

• revert the lowercase-ownership rule → 4 red, incl. "the code-carrying-helper producer this widening exists for was not reported"
• read argument zero instead of the derived parameter index → 2 red

Restored byte-identical after each (empty git diff), and --self-test green again.

⚠️Lint & Repo Gates is the CI job that carries this gate family — the local runs above are not that job green.

File-surface note for the PM: the claim named scripts/check-dispatcher-error-vocabulary.mjs only. packages/runtime/src/dispatcher-error-vocabulary.ts is also edited — it is the gate's declaration half, and a widened scan that reports 6 more sites leaves the gate red until they are classified there. Same defect class, same gate family, no other claim on the file, and the row shape is pinned by the 12 rows already present. Flagging it rather than assuming it was covered.

Generated by Claude Code

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

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

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

• content/docs/api/wire-format.mdx(via /api/v1/meta/object/:name (route))
• content/docs/permissions/authorization.mdx(via owd_widening_forbidden (literal))
• content/docs/protocol/kernel/error-handling.mdx(via /api/v1/meta/object/:name (route))
• content/docs/protocol/kernel/http-protocol.mdx(via /api/v1/meta/object/:name (route))
• content/docs/ui/forms.mdx(via /api/v1/meta/object/:name (route))

What this run could not see

• 4 name(s) were too generic to anchor anything (single lowercase words)

Coarse fallback — 23 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 e6ee690999b5e47e88eece047a6b9edc311d0729 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 40e00b64bbc424e8b7ae33ebd79b65b26be1c0fd — the merge of head 7c1840e46599a7ab74b561d61807cc575aad558b into base e6ee690999b5e47e88eece047a6b9edc311d0729, 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 40e00b64bbc424e8b7ae33ebd79b65b26be1c0fd && git checkout 40e00b64bbc424e8b7ae33ebd79b65b26be1c0fd
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin e6ee690999b5e47e88eece047a6b9edc311d0729 7c1840e46599a7ab74b561d61807cc575aad558b && git checkout -B drift-repro e6ee690999b5e47e88eece047a6b9edc311d0729 && git merge --no-ff 7c1840e46599a7ab74b561d61807cc575aad558b
node scripts/docs-audit/affected-docs.mjs --json e6ee690999b5e47e88eece047a6b9edc311d0729

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