fix(runtime): two hand-built refusals answer FieldErrorCode members (unknown_field, invalid_format), not Zod issue codes

[objectstack-fleet]

Fixes #24597
Clause-②: no
Basis for the Clause-② line: the two refusals' field codes move onto members the published FieldErrorCode catalog already declares (unknown_field, invalid_format). No accept set moves, no status or error.code moves, and no catalog member is added; packages/spec is not touched.

ADR-0114 D2 declares FieldErrorCode (packages/spec/src/api/errors.zod.ts) a closed catalog: "a service does not get to invent one — it adds a member here". Two refusals in packages/runtime build their details.fields[] rows by hand and wrote Zod's issue codes there. validationFailure(message, fields) types fields as unknown[] and ApiErrorSchema types details loosely, so neither tsc nor the envelope schema saw it. This PR moves both rows onto catalog members, takes a census of every hand-built details.fields[] writer in packages/runtime, and pins both sites plus a closed-set check over the domain's hand-built refusals.

Before and after, per site

Measured through the real HttpDispatcher handler (handleAutomation / handleSecurity), on origin/main bfc1539fe (before) and this branch (after). A field-by-field diff of the two envelopes shows exactly one path changing per site, body.error.details.fields[0].code. Status, error.code, error.message, httpStatus and the row's field and message are byte-identical.

1. Run-lifecycle body refusal — packages/runtime/src/domains/automation.ts refuseInvalidRunLifecycleBody. Request: POST approval_flow/runs/run_7/cancel (and restore-suspension), body {"foo":1}, platform-operator caller.

Before:

{ "status": 400,
  "body": { "success": false,
    "error": { "code": "VALIDATION_FAILED", "httpStatus": 400,
      "message": "Unknown key `foo` — the cancel body accepts `reason`",
      "details": { "fields": [
        { "field": "foo", "code": "unrecognized_keys",
          "message": "not a cancel body key — the cancel body accepts `reason`" } ] } } } }

After: the same envelope with "code": "unknown_field" on the row. restore-suspension is the same with its own door name in both messages, unrecognized_keys → unknown_field. unknown_field is what the sibling resume arm on the same run already answers for an unknown key.

2. Permission-set clone door, name rule — packages/runtime/src/domains/permission-set-clone.ts readCloneBody. Request: POST /permission-sets/crm_sales_rep/clone, body {"name":"My Copy","label":"X"}, manage_metadata holder.

Before:

{ "status": 400,
  "body": { "success": false,
    "error": { "code": "VALIDATION_FAILED", "httpStatus": 400,
      "message": "'My Copy' is not a valid permission-set name — use lowercase snake_case: start with a lowercase letter, then lowercase letters, digits and underscores, at least 2 characters (e.g. 'sales_rep_copy').",
      "details": { "fields": [
        { "field": "name", "code": "invalid_string",
          "message": "Identifier must be lowercase snake_case, starting with a letter, and may contain only letters, numbers, and underscores (e.g., \"user_profile\")" } ] } } } }

After: the same envelope with "code": "invalid_format" ("a declared pattern/format the value does not match").

What changes on the wire, stated in the changeset too: a client that switched on details.fields[].code sees unknown_field where it saw unrecognized_keys, and invalid_format where it saw invalid_string. Consumer read: git grep for either literal in packages/client, packages/client-react, packages/cli and in ../objectui (79cb8c0) finds only Zod-issue reads (issue.code === 'unrecognized_keys' on a local Zod parse), none on these doors' wire rows.

Census — every hand-built details.fields[] writer in packages/runtime

Method: a TypeScript-AST walk of packages/runtime/src/**/*.ts (tests excluded) for every object literal carrying both field and code, plus every call to validationFailure, fieldsFromZodIssues, validationFailureDetails and invalidQueryParam. 31 literal rows, 48 helper calls, at this branch's head. Each row checked against FieldErrorCode; line numbers are this branch's.

Hand-built rows (31)

Site	Door	field	code	Catalog member?	Closed-set check
domains/activation-gate.ts:226	activation body (catalog + action activation doors)	(body)	invalid_type	yes	driven
domains/activation-gate.ts:235	″	each unknown key	unknown_field	yes	driven
domains/activation-gate.ts:244	″	enabled	invalid_type	yes	driven
domains/analytics.ts:66	POST /analytics/query	filters	unknown_field	yes	driven
domains/automation.ts:939	run-lifecycle body (cancel / restore-suspension)	(body)	invalid_type	yes	driven, both doors
domains/automation.ts:962	″	each unknown key	unrecognized_keys → unknown_field	was no — fixed here	driven, both doors
domains/automation.ts:980	″	reason	invalid_type	yes	driven, both doors
domains/automation.ts:1498	flowDefinitionRefusal fallback (engine refusal with no status, no issues)	(body)	invalid_value	yes	driven (via POST /)
domains/automation.ts:2699	POST / (createFlow)	(body)	invalid_type	yes	driven
domains/automation.ts:2704	″	name	required / invalid_type	yes, both arms	driven, both arms
domains/automation.ts:2870	POST /:name/toggle	(body)	invalid_type	yes	driven
domains/automation.ts:2881	″	each unknown key	unknown_field	yes	driven
domains/automation.ts:2886	″	enabled	invalid_type	yes	driven
domains/automation.ts:2951	POST /:name/clone (flow clone)	(body)	invalid_type	yes	driven
domains/automation.ts:2960	″	each unknown key	unknown_field	yes	driven
domains/automation.ts:2974	″	name	required / invalid_type	yes, both arms	driven, both arms
domains/automation.ts:2989	″	label	required / invalid_type	yes, both arms	driven, both arms
domains/automation.ts:3153	POST /:name/runs/:runId/resume	(body)	invalid_type	yes	driven
domains/automation.ts:3195	″	each unknown key	unknown_field	yes	driven
domains/automation.ts:3240	″	inputs / variables / output	invalid_type	yes	driven (inputs)
domains/automation.ts:3248	″	branchLabel	invalid_type	yes	driven
domains/automation.ts:3286	″	inputs (both spellings sent)	invalid_value	yes	driven
domains/automation.ts:3291	″	variables (both spellings sent)	invalid_value	yes	driven
domains/automation.ts:3676	PUT /:name (updateFlow)	(body)	invalid_type	yes	driven
domains/permission-set-clone.ts:170	POST /security/permission-sets/:name/clone	(body)	invalid_type	yes	driven
domains/permission-set-clone.ts:177	″	each unknown key	unknown_field	yes	driven
domains/permission-set-clone.ts:185	″	name	required / invalid_type	yes, both arms	driven, both arms
domains/permission-set-clone.ts:197	″	name (metadata name rule)	invalid_string → invalid_format	was no — fixed here	driven
domains/permission-set-clone.ts:205	″	label	required / invalid_type	yes, both arms	driven, both arms
endpoint-executor.ts:386	object endpoint, missing ?id	id	required	yes	outside src/domains/; already pinned exactly in endpoint-executor.test.ts
query-param.ts:81	invalidQueryParam(param, code, …)	the parameter	the code argument	yes, by construction	outside src/domains/; the parameter is typed FieldErrorCode, so tsc closes it (callers pass invalid_boolean, invalid_number, min_value, max_value, invalid_type, invalid_option)

Not hand-built writers (listed so the census is complete):

• Zod-derived rows, mapped by construction through fieldsFromZodIssues → zodIssuesToFields (ADR-0114 D3): domains/analytics.ts:72, domains/automation.ts:1485, domains/data.ts:120, domains/notifications.ts:221.
• Empty-row refusals: domains/data.ts:312 and :396, validationFailure(versionRefusal, []).
• Relays of a producer's own rows, not built here: flowDefinitionRefusal's pass-through of a service-thrown validation failure (automation.ts, validationFailureDetails(err)), domains/actions.ts:913 (an action body's thrown err.fields), and sandbox/quickjs-runner.ts (fields carried across the VM boundary).
• A reader, not a wire write: domains/packages.ts:888 compares a Zod issue's own code (issue.code === 'unrecognized_keys' on the install-request parse) to name misplaced install options in the message. It writes no details.fields[] row, and comparing a Zod issue against Zod's vocabulary is correct there.

Result: 2 off-catalog rows, both fixed here; 0 listed as remaining.

Pins and their ablation

New file packages/runtime/src/domains/field-error-code-catalog.test.ts (41 tests):

• Part 1, per fixed site (5 tests). Each drives the real refusal and asserts the envelope (400 + error.code VALIDATION_FAILED), that every details.fields[].code parses under FieldErrorCode, the exact rows ({ field, code }), and that nothing reached the service (cancelRun / restoreConsumedSuspension / saveMetaItem not called). The run-lifecycle pin sends two unknown keys, resaon and requestedBy, on both doors. The clone pin covers My Copy, 9copy and _copy.
• Part 2, the closed-set check (36 tests). It drives every hand-built row under src/domains/ in the table above through the real HttpDispatcher and parses each details.fields[].code under FieldErrorCode. Each case also names its expected { field, code }, so a case that reached some other refusal fails instead of passing on a row it never meant to check, and a refusal with no rows fails instead of passing vacuously. No gate script or lint rule is added; the rows are enumerated by hand, and the file's header says a new hand-built row joins the table in the change that adds it.

Messages are not pinned.

Ablation, one leg per fixed site, run after the fix was committed (5fd5f5e71). The test imports ../http-dispatcher.js relatively, so the subject resolves to src/, with no dist/ in the path. The mutation went through node scripts/ablation-replace.mjs (anchor must hit, blob must change, restore proven against HEAD) inside a wrapper with an EXIT INT TERM trap that re-proves the restore by blob hash and git diff HEAD.

Leg	Mutation (restores the old code)	On disk	Result	Restore
automation	code: 'unknown_field' as const, → code: 'unrecognized_keys' as const,	anchor 1 → 0, replacement 0 → 1, blob 84d4f8b34e42 → 5ad01f696481	4 failed / 37 passed: both Part 1 run-lifecycle pins and both Part 2 run-lifecycle unknown-key rows, each failing with details.fields[].code "unrecognized_keys" … is not a FieldErrorCode member	blob back to 84d4f8b34e42 == HEAD, git diff HEAD empty
clone	code: 'invalid_format' → code: 'invalid_string'	anchor 1 → 0, replacement 0 → 1, blob 820646d40ba1 → ffdb9582fd37	4 failed / 37 passed: the three Part 1 clone pins and the Part 2 name-rule row, each failing with details.fields[].code "invalid_string" … is not a FieldErrorCode member	blob back to 820646d40ba1 == HEAD, git diff HEAD empty

Direction observed: red, as predicted. In every failing case the closed-set assertion (the catalog parse) is the one that fires, and no other test moved. Green on the restored tree: 41/41.

Tests

At 5fd5f5e71:

• pnpm --filter @objectstack/runtime test (vitest project local): 426 files passed, 6712 tests passed, 19 skipped, exit 0.
• pnpm --filter @objectstack/runtime test:repo (vitest project repo): 3 files passed, 808 tests passed, exit 0.
• pnpm --filter @objectstack/runtime typecheck (tsc --noEmit and check:test-typecheck over tsconfig.test.json): exit 0. The new test file carries no ledger entry, so it compiles with zero errors.
• Other packages' tests: no assertion on unrecognized_keys or invalid_string from these two doors. Every hit outside packages/runtime reads a Zod issue's own code on a local parse; in packages/runtime the hits are the package-install, flow-register and external-validation Zod paths.

Gates

All at 5fd5f5e71, the branch's final commit.

• Derived set: node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack printed 67 commands (change set: 4 paths against merge base bfc1539fe). Each ran byte for byte, with its exit code captured before any pipe.
  • 66 exited 0 on the first pass.
  • pnpm check:dual-build-cjs-loads exited 3 (PREREQUISITE NOT MET: it reads built output, and 39 packages had no dist/). After a full turbo run build --filter=!@objectstack/docs (76 tasks, 75 cached) it exited 0: 111 require entry points across 69 packages load.
  • The four other dist-reading gates were re-run on the fully built tree, all exit 0: check:dts-closure (76 packages swept, against 32 on the first pass), check:sourcemap-no-sources-content, check:lean-entry-closure and check:published-files.
• Reconciliation: node scripts/pm/dispatch-gates.mjs --ran ran.list printed "67 derived, 67 run, 0 NOT-MEASURED, 0 UNRUN", exit 0.
• Full union: pnpm lint (eslint . --no-inline-config), exit 0, no findings.
• Owned by CI: the families the derivation names as outside its runnable set (artifact rosters, wide-population families, path-scheduled CI jobs, type-check lanes). They are not re-run locally.
• No exported symbol is renamed or removed, so check-platform-checklist.mjs --changed-from does not apply.
• origin/main was not merged into this branch.

Acceptance notes

• Name of the schema. The card and claim say FieldErrorCodeSchema; the Zod enum the spec exports is FieldErrorCode (packages/spec/src/api/errors.zod.ts), and no FieldErrorCodeSchema export exists. The pins parse under FieldErrorCode.
• The class stays open one level up. validationFailure(message, fields) (packages/types/src/validation-failure.ts) types fields as unknown[], which is how both rows got past tsc. Typing its rows' code as FieldErrorCode would close the class at compile time for every caller in every package. It is a signature change to a published @objectstack/types export and is outside this claim's file surface, so it is not done here. Carrier: none.
• The closed-set check is enumerated, not discovered. It holds every row that exists today; a new hand-built row is checked only once it joins the table. The dispatch ruled out a new gate script or lint rule.
• Wider read-only sweep. The same AST walk over packages/*/src (tests excluded), for literal rows { field, code, message } whose string-literal code is not a catalog member, finds three hits, all in packages/metadata-protocol/src/protocol.ts (field_removed, field_type_change, field_required_no_default). Those are DESTRUCTIVE_CHANGE findings delivered as err.issues, a different position with its own vocabulary, not details.fields[]. The sweep sees only string-literal codes, so it is a supporting reading, not a proof.
• packages/spec/** is not touched: the catalog was read, never extended.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

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

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

• content/docs/api/error-catalog.mdx (via invalid_format (literal, a string literal in readCloneBody), unknown_field (literal, a string literal in refuseInvalidRunLifecycleBody))
• content/docs/deployment/cli.mdx (via unrecognized_keys (literal, a string literal in refuseInvalidRunLifecycleBody))
• content/docs/kernel/runtime-services/settings-service.mdx (via invalid_format (literal, a string literal in readCloneBody))
• content/docs/protocol/objectql/types.mdx (via unrecognized_keys (literal, a string literal in refuseInvalidRunLifecycleBody))

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

• content/docs/releases/v17/17-0.mdx (via unknown_field (literal, a string literal in refuseInvalidRunLifecycleBody), unrecognized_keys (literal, a string literal in refuseInvalidRunLifecycleBody))

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

• 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 — 26 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 eadea572082976b747e0828d56c24fdf62cd8803 → packageMentionDocs.

Which tree this was computed on

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

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

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

[objectstack-fleet]

席位核对 — ACCEPT

domain:cli seat 1 (seat post #6024) · zhuangjianguo · session session_01SYEJqDL3NXxrJRBVqaMu9T · 2026-10-19T23:23Z · on head 5fd5f5e71 · #24597 (p2; claim 6278722621). This is the seat's own review at the default tier (Clause-②: no), read against the diff on GitHub, not the report.

1. What moved: 4 files, +363 / −2.
   • automation.ts, in refuseInvalidRunLifecycleBody (the cancel and restore-suspension doors): an unknown body key's row now carries unknown_field, not unrecognized_keys.
   • permission-set-clone.ts, in readCloneBody's name rule: the row now carries invalid_format, not invalid_string.
   • Each site carries a one-line ADR-0114 D2 comment. Status, error.code, message, field and row message are unchanged; the dev's envelope diff shows one path per site.
2. Clause-②: no holds:
   • Both new values are members the published closed catalog (FieldErrorCode, packages/spec/src/api/errors.zod.ts) already declares.
   • The old values were outside it. This brings the wire into line with the declared contract, which is the "spec declares, code aligns" direction. No accept set or status moves.
   • unknown_field is the code the sibling resume arm already answers for the same condition.
   • The changeset is a patch on @objectstack/runtime and names the wire change for clients.
   • The seat's own grep finds no consumer of these two doors' old codes; the dev's grep covered objectui too.
3. Census and pins:
   • field-error-code-catalog.test.ts (41 tests). Part 1 pins the two sites. Part 2 drives every hand-built row under src/domains/ through the real HttpDispatcher and parses each code under FieldErrorCode.
   • The 36 rows are enumerated by hand, not discovered. No gate or lint rule is added, which fits the startup-stage default against new gates.
   • The two rows outside src/domains/ are held elsewhere: one is pinned exactly, and the other's parameter is typed FieldErrorCode.
4. Ablations: one leg per site. Each went red exactly on that site's 4 rows, and each restore was proven by blob.
5. Accepted deviation: the dispatch and the claim said FieldErrorCodeSchema. The spec exports FieldErrorCode, and the pins use the real name. That is the dispatch's error.
6. Gates: dispatch-gates 67 derived and 67 run, 0 NOT-MEASURED. Full pnpm lint exited 0. runtime local tier: 426 files, 6,712 passed. test:repo: 808 passed. Typecheck exited 0.
7. Findings, each Acceptance notes, none filed:
   • validationFailure(message, fields) in packages/types types fields as unknown[]. A typed row (code: FieldErrorCode) would close the class at compile time across packages. That is a published-signature change outside this claim, and is recorded in this seat's sign-off brief for the next seat to weigh.
   • The three protocol.ts DESTRUCTIVE_CHANGE codes are err.issues, not details.fields[], so they are not this catalog's position.
8. Landing: ready plus auto-merge through the queue once every check of 5fd5f5e71 is green or a rostered skip. Fixes #24597 closes the card on the merge.

---

Generated by Claude Code