alias-integrity: fail an alias row a guidanceSet already consumes

[os-zhuang]

Fixes#7889

What

strictUnknownKeyError (packages/spec/src/shared/suggestions.zod.ts) consults three channels for each unrecognized key, in order: exact guidance, then guidanceSets, and only then the aliases rename fallback. A guidanceSets match continues past the alias lookup entirely (confirmed by reading the actual control flow, not assumed from the issue body):

constprescription=guidance[key];if(prescription){prescriptions.push(prescription);continue;}constset=guidanceSets.find((s)=>keySetMatches(s,key));if(set){/* … */continue;}// <-- alias table never consulted for this keyconstcanonical=aliases[aliasProbe(key)]??findClosestMatches(...);

So an alias row whose written key also matches a guidanceSet declared on the same strictObject table is dead on arrival — the set answers first, every time — and nothing checked for that before this PR. PR #7884 had to place its one view-family alias (disabled → readonly on FormFieldSchema) outside VISIBILITY_KEY_PATTERN's reach by hand; a future visible: 'visibleWhen' row on the same shared table would have shipped exactly as dead, with every existing gate green.

Change

Extends packages/spec/src/shared/alias-integrity.test.ts (test-only, no other files touched) with:

• unreachableAliasRows(surfaces) — reads only options.aliases and options.guidanceSets (never .shape), and flags any alias key a guidanceSet on the same table already matches via keySetMatches (the same function the real error map calls).
• Live-table verdict: unreachableAliasRows(SURFACES) must be empty, plus an explicit pin that the one existing view-family alias (disabled → readonly on FormFieldSchema, ui/view.zod.ts:1775) exists and sits on a table carrying VISIBILITY_KEY_PATTERN — so the empty-array assertion is judging a real, non-trivial table rather than passing vacuously.
• Self-test: a synthetic strict-options + alias table (no live schema touched) proves the check can go red on a planted dead row, plus two controls (no guidanceSet on the table; a guidanceSet present but not matching the alias key) proving the verdict tracks an actual pattern match rather than mere presence of a guidanceSets array.

No acceptance-behavior change anywhere — publish/parse behavior of every schema is byte-identical before and after. No *.zod.ts files touched.

Tests

pnpm --filter @objectstack/spec exec vitest run src/shared/alias-integrity.test.ts src/shared/strict-object.test.ts src/shared/visible-when-alias-guidance.test.ts
Test Files 3 passed (3)
Tests 69 passed (69)
pnpm --filter @objectstack/spec run test
Test Files 381 passed (381)
Tests 10033 passed (10033)
pnpm --filter @objectstack/spec run typecheck
tsc --noEmit ✓ / check:scripts-typecheck ✓ / check:test-typecheck: OK (57 file(s) / 265 error(s) held in shrink-only debt, unchanged)
eslint src/shared/alias-integrity.test.ts — clean
node scripts/check-nul-bytes.mjs — OK

This is a test/gate-only change with no reader-visible behavior — no changeset; skip-changeset label requested.

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectstack	Ignored		Aug 12, 2026 8:45am

[github-actions]

📓 Docs Drift Check

No hand-written docs reference the 0 changed package(s). ✅