spec: union-branch selection policy now has two sibling implementations INSIDE one package (error-map renderer vs the D3 structural mapper)

[hotlong]

Observation-class finding from #8124 (no defect today — the two agree, and tests on both sides pin the shared verdict).

What

packages/spec/src/shared/error-map.zod.ts (the string renderer: formatZodIssue / selectUnionBranches / CONTAINER_ISSUE_CODES / the depth and branch limits) and packages/spec/src/api/zod-issues-to-fields.ts (the ADR-0114 D3 structural mapper, moved into spec by #8124) carry the SAME union-branch selection policy — kind-mismatch drop, fewest-issues ranking, unrecognized_keys tie-break, declaration-order determinism, depth limit 3, branch cap 3, container descent per #5389 — as two separate implementations.

Why it was tolerable before, and what changed

While the structural mapper was module-local to @objectstack/rest, the duplication was forced: spec exported only the string renderer, and the comment on the rest side documented the pairing ("the verdict must match all the same", #5014). #8124 moved the mapper into spec, so the historical reason is gone: both implementations now live one directory apart in the same package. The module headers bind them to move together in the same PR, but nothing mechanical enforces it.

Possible shape (not ruled)

Extract the selection policy (isKindMismatchOnly, carriesUnknownKey, selectUnionBranches, CONTAINER_ISSUE_CODES, the two limits) into one package-internal module both walks import — internal only, NOT a public export (the #4001 pitfall: do not export internals only these modules need). The walks themselves stay separate (prose lines vs {field, code, message} entries; the renderer also emits the "… and N more branches" line the wire deliberately omits). The one signature wrinkle: the renderer's selectUnionBranches returns {selected, omitted}; the mapper ignores omitted.

Deliberately NOT done in #8124: the card's scope was ending the wire's code leak with a behavior-identical move, and rewriting error-map.zod.ts in the same PR would have widened the test surface the move's proof rests on.

---

Generated by Claude Code

[hotlong]

Triage: finding (held — observation-class, no defect today: both copies agree and are pinned on both sides) + domain:spec, type Task. Routed to the spec seat as packages/spec owner — the two implementations live in src/shared/error-map.zod.ts and src/api/zod-issues-to-fields.ts. The proposed extraction is behavior-identical consolidation (acceptance face unchanged), so at grading this may be treated as consolidation-class; the card's own guardrails stand and are binding if it queues — package-internal module only, NOT a public export (the #4001 pitfall), the two walks stay separate, and the {selected, omitted} signature wrinkle is real. Held rather than queued: grading belongs to the finding-triage pass, and the risk this card guards against (the two copies drifting) currently has module-header pairing as its only enforcement — if the spec seat wants a cheaper interim, a shared-fixture parity test is a smaller first step than the extraction. 本评论来自分诊座位 Routine。

---

Generated by Claude Code

[hotlong]

Concentrated findings round (maintainer-directed, 2026-08-13): promoted finding → pm:queue (domain:spec — src of packages/spec, spec seat's lane). Type: Task, consolidation-class.

Graded scope: extract the union-branch selection policy (isKindMismatchOnly, carriesUnknownKey, selectUnionBranches, CONTAINER_ISSUE_CODES, depth/branch limits) into ONE package-internal module both walks import. Binding guardrails from the card and the earlier routing: ⛔ internal only, no new public export (the #4001 pitfall); the two walks stay separate (prose renderer vs {field, code, message} wire, including the "…and N more branches" asymmetry); the {selected, omitted} signature wrinkle handled explicitly. Acceptance bar: byte-identical outputs on both sides, pinned — the shared-fixture parity test suggested at routing is the right pin to land WITH the extraction (it is the mechanical enforcement the module headers currently lack).

Model note for the spec seat: acceptance/rejection behaviour is explicitly unchanged and no public face grows, so the mandatory-fable clause does not bind — default judgment tier applies.

Size/model suggestion: M, mode:subagent, opus.

---

Generated by Claude Code

[os-zhuang]

Claim: PM loop round 1
Session: session_01E5tUwGM3LQoqErTfkvRW7W
Branch: claude/issue-8318-union-branch-policy-extract
Worktree: objectstack-issue-8318
Domain: domain:spec
File surface: packages/spec/src/shared/error-map.zod.ts, packages/spec/src/api/zod-issues-to-fields.ts, one NEW package-internal module (+ parity test, changeset) (stop on breach; explain in the report)
Container & model: M consolidation, mode:subagent, model: opus (acceptance behaviour explicitly unchanged, no public face grows — fable clause does not bind; triage suggestion adopted)
Serial constraints cleared: none — no in-flight claim or open PR touches either file (verified via lane state rebuild; #8124, which moved the mapper into spec, is MERGED)

---

Generated by Claude Code