`fieldsFromZodIssues` leaks Zod's issue codes onto the wire's `fields[].code` — the exact pass-through ADR-0114 D3 closed, still live in `@objectstack/runtime`

[hotlong]

Found while implementing #8055 (which emits through this helper and therefore inherits the defect).

What is declared

ADR-0114 D2 makes FieldErrorSchema.code a closed catalog — FieldErrorCode in packages/spec/src/api/errors.zod.ts, 27 lowercase snake_case members. D3 is explicit that Zod is mapped at the boundary, never passed through:

D3 — Zod is mapped at the boundary, never passed through. zodIssuesToFields translates using origin / format per the table above, plus the parsed input for the invalid_type split. An unmapped Zod code becomes invalid_value (a catalog member) rather than leaking.

@objectstack/rest complies: zodIssuesToFields in rest-server.ts runs zodIssueToFieldCode, which is typed to return FieldErrorCode.

What is emitted

packages/runtime/src/validation-failure.ts has a second, non-compliant converter — fieldsFromZodIssues — which assigns the Zod issue's own code verbatim:

code: issue.code,

Measured against the real FlowSchema (a genuine safeParse, not a hand-written fixture), the codes that reach the wire include unrecognized_keys — not a FieldErrorCode member. ADR-0114 D3's own table says that row maps to unknown_field. Zod's too_small / too_big / custom / invalid_union are equally outside the catalog, and too_small is the ambiguity D3 names explicitly (a short string, a small number and a short array share one code).

Consequence: a response whose details.fields[] carries one of those codes does not parse against the schema the protocol declares for it. A client validating the error envelope — the thing ADR-0114 D2 gave it a schema for — rejects a well-formed refusal from its own server. It is also the two-vocabularies-on-one-position problem the ADR was written to remove: the same wire slot answers min_length from a validator and too_small from a Zod-parsed route, and nothing in the body says which dialect the reader is holding.

Affected call sites

Three, all in @objectstack/runtime, all through this one helper:

• src/domains/analytics.ts — the AnalyticsQueryRequestSchema entry refusal
• src/domains/notifications.ts — the same shape one domain over
• src/domains/automation.ts — the flow-registration refusal added by POST /api/v1/automation answers 500 INTERNAL_ERROR for a malformed flow body — including the #4277 undeclared-config-key refusal the #7545 ruling leans on #8055

Handled as one card rather than three deliberately: the pass-through is the helper's, not any route's, and the fix belongs where they all read from. #8055 explicitly did not fork a local mapper for its own route, because a fourth spelling inside one package is worse than the shared gap.

Why the obvious fix is not a one-liner

zodIssuesToFields — the compliant implementation — is module-local to packages/rest/src/rest-server.ts and not exported from that package's index. Three routes worth weighing:

1. Export it from @objectstack/rest. Cheapest edit, but it makes a ~11k-line server module part of runtime's import graph for one pure function, and puts a spec-vocabulary mapper's public home in the REST transport.
2. Move the mapper to @objectstack/spec, next to the FieldErrorCode catalog it is total over, and have both rest and runtime read it. Most contract-first: one catalog, one mapping, defined where the vocabulary is defined. Largest diff.
3. Reimplement in runtime. Rejected on sight — a second implementation of D3's table is the drift the ADR exists to prevent, and the two would disagree the first time Zod adds an issue code.

Recommendation is (2), but it is a real design call, so it wants a decision rather than a guess.

Note on measurement

ADR-0114 D3 says its mapping is "tested by driving real safeParse calls, not by hand-written issue fixtures — which is how the input problem above surfaced at all". Whatever fix lands should be measured the same way; #8055's tests already drive the real FlowSchema, so they are one available fixture source.

Severity

Not judged here. It is a live wire-contract mismatch (declared schema vs. emitted value) on three routes, but no in-repo consumer branches on a field code today — objectui's extractFieldErrors reads field and message and touches code only as a last-resort fallback, which ADR-0114 measured before choosing the casing.

---

Generated by Claude Code

[hotlong]

Triage: lands in domain:spec, queued (pm:queue), type Bug.

Rationale: the wire violates ADR-0114 D2/D3 (a closed FieldErrorCode catalog with Zod mapped at the boundary), so the contract itself is already ruled — this is a restore-declared-behaviour fix, not a new design. On the three routes: the card's own option 3 (reimplement in runtime) is rightly rejected; option 1 (export from @objectstack/rest) has a likely dependency-direction problem the card doesn't test — if rest depends on runtime, a runtime→rest import is a cycle. Dispatch should verify that direction first as a mechanism assumption. If option 1 is impossible or ugly, option 2 (mapper moves next to the FieldErrorCode catalog in packages/spec, both consumers read it) is the contract-first home. Either way the fix plausibly touches packages/spec, so the card routes to the spec seat as the single owner.

Model note for the dispatching seat: if the landing adds an export to @objectstack/spec (public-face expansion, option 2), the mandatory claude-fable-5 clause applies. Measurement per ADR-0114's own discipline: drive real safeParse calls (the #8055 FlowSchema tests are an available fixture source), no hand-written issue fixtures.

Size/model suggestion: M, claude-fable-5 if option 2, opus if option 1 proves clean.

---

Generated by Claude Code

[hotlong]

Claim: PM loop round 1
Session: session_01Euoy6wyfzgiWtgCg4s6JK2
Branch: claude/issue-8124-fielderror-mapper-to-spec
Worktree: objectstack-issue-8124
Domain: domain:spec
File surface: packages/spec/src/api/errors.zod.ts (or a sibling module beside the FieldErrorCode catalog) + spec public exports, packages/types/src/validation-failure.ts, packages/rest/src/rest-server.ts (swap the local mapper to the shared one), tests in those packages (stop on breach; explain in the report)
Container & model: M, mode:subagent, model: claude-fable-5 (mandatory clause — grows @objectstack/spec's public surface)
Serial constraints cleared: head of the wire-error-registry serial chain — #8273 and #8211 are held behind this card (recorded on seat post #6017). No in-flight claim touches these files. Premise re-verified on origin/main today with a correction the card predates: #8016 moved fieldsFromZodIssues from packages/runtime to packages/types/src/validation-failure.ts (pass-through now at :90, code: issue.code); runtime re-exports it. Dependency arrows measured: types → spec only (types cannot import rest), so the card's route 1 is dead and route 2 (mapper lives in spec) is ruled — see dispatch ruling below.

PM disposition (owed from last shift, ruled now): route 2 — the D3 mapper moves to packages/spec, beside the FieldErrorCode catalog it is total over; types and rest both consume it. Basis: ADR-0114 D3 already rules the wire behavior (not re-decidable); of the card's three routes, 3 was rejected on-card (drift), 1 is now mechanically impossible (types cannot import rest — measured on origin/main package.json today), leaving 2, which is also the card's own and triage's recommendation (contract-first home). Escalation threshold not met: no product-semantics fork remains. Maintainer veto window open as always.

---

Generated by Claude Code