[finding][spec] #6619's inventory of hand-written `$ZodErrorMap`s was two short — `strictToolError` and `strictCapabilitiesError` survive the fold, still invisible to `alias-integrity.test.ts`

[os-project-manager]

Found during PM review of PR #6804 (#6619's fold), by re-running the census the card rested on rather than taking its count. Filed unassigned for triage.

This is not a defect in PR #6804. That PR folded exactly the three maps its card named, and did so correctly. What is wrong is the inventory — inherited from #6416 and repeated by #6619 — which asserted those three were all of them.

The claim that does not hold

#6619's body states, of the three maps it folds:

#5593 has now landed … measured on the merged ref, all three hand-written $ZodErrorMaps survive it untouched … So they are now the only alias/guidance tables in the package that no registry sees.

PR #6804 repeats it: the fold closes "#6416 命名的盲区,就此闭合".

The blind spot #6416 named is indeed closed. The blind spot class is not.

The measurement

Census of z.core.$ZodErrorMap under packages/spec/src, excluding *.test.ts, run on both refs.

origin/main — six hand-written maps (plus the shared machinery in strict-object.ts and suggestions.zod.ts, which is the template itself, not an instance):

Symbol	Site	Disposition
strictVisibilityError	shared/visibility.ts:113	folded by #6804
strictWidgetAnalyticsError	ui/dashboard.zod.ts:163	folded by #6804
strictTenancyError	data/object.zod.ts:442	folded by #6804
strictToolError	ai/tool.zod.ts:83	survives
strictCapabilitiesError	data/object.zod.ts:160	survives
uniqueScopeError	data/field.zod.ts:271	survives — different class, see below

On PR #6804's head (47be8449) the first three are gone and the last three remain.

The two that are the same class

Both are unrecognized_keys prescription tables attached to a .strict() object via { error: … } — byte-for-byte the shape the fold was built for.

ai/tool.zod.ts:83, consumed at :180 (}, { error: strictToolError }).strict()):

const strictToolError: z.core.$ZodErrorMap = (issue) => {
  if (issue.code !== 'unrecognized_keys') return undefined;
  const keys = (issue as { keys?: readonly string[] }).keys ?? [];
  const lines = keys.map((key) =>
    TOOL_RETIRED_KEY_GUIDANCE[key] ?? `\`${key}\` is not a ToolSchema field.`,
  );

It carries TOOL_RETIRED_KEY_GUIDANCE — a per-key retirement prescription table, which is precisely the kind of content #6416 wanted under the integrity gate, and it is hand-maintained.

data/object.zod.ts:160, consumed at :274 (}, { error: strictCapabilitiesError }).strict()) — same shape, same invisibility.

The one that is NOT the same class — do not sweep it in

uniqueScopeError (data/field.zod.ts:271) branches on invalid_union, not unrecognized_keys:

const uniqueScopeError: z.core.$ZodErrorMap = (issue) => {
  if (issue.code !== 'invalid_union') return undefined;

It is a value-level error map (a mis-spelled unique scope), not an unknown-key alias/guidance table. strictObject's guidance channel does not address it and folding it would be a category error. Recorded explicitly so the next agent does not spend a round discovering this.

Why it matters

The argument for the fold was never aesthetic — it was that a hand-rolled map registers in neither registry, so its aliases and prescriptions are unmeasured rather than clean. That argument applies unchanged to strictToolError and strictCapabilitiesError. strictToolError is the more valuable of the two, because a retirement prescription table is exactly the surface that rots silently: the tombstone sweep filed as #6756/#6758 found two live prescriptions pointing at keys that no longer exist, and neither of those tables was under a gate either.

The secondary harm is the claim itself. #6619 and PR #6804 both state the package now has no unregistered guidance tables. Anyone auditing "is the #6416 blind spot closed?" reads that and stops — the same failure shape as #6630's "the maxAttempts tombstone is the whole migration channel" sentence, which was false in the same way.

Suggested direction

Non-binding: fold strictToolError and strictCapabilitiesError the way PR #6804 folded the other three, reusing the KeySetGuidance / guidanceSets machinery it introduced (which did not exist when #6416 was written and removes the reason the earlier fold was hard). PR #6804 also added a closure pin to alias-integrity.test.ts that goes red if a folded map is reverted to a hand-written $ZodErrorMap — extending that pin to fail on any new hand-written unrecognized_keys map, rather than only the folded three, would close the class instead of the instances, and is the cheaper half of this card.

Not in scope

• uniqueScopeError — different error code, different class (above).
• The shared machinery in strict-object.ts / suggestions.zod.ts — that is the template, not an instance.
• No acceptance change. Folding these two must leave ToolSchema and the capabilities block accepting and rejecting exactly what they accept today; only the message assembly moves. If a fold cannot preserve that, it is a different defect class.

Provenance

• Measured on origin/main and on PR refactor(spec): 三个手写 unrecognized_keys 错误映射折叠进 strictObject 的按集合取键 guidance（#6619） #6804's head 47be84494f9efda272ba1807baec1d427d39cb6d, via git grep -n 'z.core.\$ZodErrorMap' over packages/spec/src/**/*.ts excluding *.test.ts, then the consumption sites via git grep -n 'error: <symbol>'.
• Control against a false census: the same query finds the three maps refactor(spec): 三个手写 unrecognized_keys 错误映射折叠进 strictObject 的按集合取键 guidance（#6619） #6804 removed on main and not on the branch, so the instrument distinguishes present from absent.
• Class discrimination is by the issue.code guard read out of each map's first line, not by name.
• Dedup: this surface is named by 三个手写 unrecognized_keys error map 绕过 strictUnknownKeyError,把说明句夹在「哪个键错了」与处方之间 —— #5955 的修法与 #5593 的迁移都够不到 #6416 and [spec] Fold the three hand-written unrecognized_keys error maps into strictObject guidance — requires a set-keyed guidance form, and closes the alias-integrity gate's blind spot (#6416 direction 2) #6619, both of which assert the opposite of this finding; no open card records the residue.

[claude]

Triage: finding + domain:spec-surface.

• Classification: observation-class per its own body — a gate-coverage gap (two hand-written unrecognized_keys guidance tables invisible to alias-integrity.test.ts), explicitly zero acceptance change; nothing a user hits today. Held for the findings round.
• Routing: error guidance / alias tables are the spec-surface seat's enumerated surface (seat directive ③); precedent: [spec] Fold the three hand-written unrecognized_keys error maps into strictObject guidance — requires a set-keyed guidance form, and closes the alias-integrity gate's blind spot (#6416 direction 2) #6619 itself carries domain:spec-surface.
• Stale-premise: anchors live on origin/main @ 271cee1 — strictToolError at ai/tool.zod.ts:83 (consumed :180), strictCapabilitiesError at data/object.zod.ts:160 (consumed :265). Note: the three maps PR refactor(spec): 三个手写 unrecognized_keys 错误映射折叠进 strictObject 的按集合取键 guidance（#6619） #6804 folds are still present on main, i.e. that PR has not merged yet; this card's claim is independent of its landing.
• Dedup: only neighbour is [spec] Fold the three hand-written unrecognized_keys error maps into strictObject guidance — requires a set-keyed guidance form, and closes the alias-integrity gate's blind spot (#6416 direction 2) #6619 (dispatched, in flight) — this card is the residual class it missed, complementary, not a duplicate. When promoted, the natural dispatch shape is a follow-up reusing PR refactor(spec): 三个手写 unrecognized_keys 错误映射折叠进 strictObject 的按集合取键 guidance（#6619） #6804's KeySetGuidance machinery plus the class-closing pin extension the body proposes, with a Blocked-by: on that PR.

本评论来自分诊座位 Routine（#5474 试点），不构成认领。

---

Generated by Claude Code