[finding] alias-integrity cannot see an alias row made unreachable by a guidanceSet — a vis-shaped alias on VISIBILITY_STRICT_OPTIONS surfaces would be dead code with no gate saying so

[os-zhuang]

Recorded from PR #7884's report (out_of_scope_finding 3 of card #7832; filed by the PM seat because the cloud dev session cannot write issues). Filed unassigned — a recording, not a claim.

Mechanism, measured during #7832

In packages/spec/src/shared/strict-object.ts, when an unknown key matches a guidanceSet's pattern, the set consumes the key and continues past the rename channel — the aliases table is never consulted for that key. VISIBILITY_KEY_PATTERN (/vis|conceal|hidden|show.?when/i, part of the ADR-0089 conditional-visibility prescription in VISIBILITY_STRICT_OPTIONS) therefore makes ANY vis-shaped alias row on those surfaces (FormSectionSchema, PageComponentSchema, FormFieldSchema) dead on arrival.

That behaviour is correct (the shared prescription is the intended answer), but it is not enforced or documented at the alias-authoring site:

• alias-integrity.test.ts checks that an alias row's target key is declared — it does not check that the row is reachable past the guidanceSets in the same strict options.
• A future card adding e.g. visible: 'visibleWhen' to one of those shapes would ship dead code, every gate green, and the author would reasonably believe the hint exists.

PR #7884 worked around it by (a) placing its one view-family alias (disabled → readonly on FormFieldSchema) outside the pattern's reach, and (b) pinning in visible-when-alias-guidance.test.ts that the three shared-options surfaces answer visible/showWhen via the ADR-0089 set with no Did you mean rename — but that pin protects those specific keys only, not the class.

Possible fix shape (for whoever grades this)

Extend alias-integrity to fail an alias key that a guidanceSet in the same strict options already matches — turning "dead row" from a silent state into a red gate. Lands in the gate/test machinery around strict-object.ts ⇒ domain:spec-tooling face by the #5163 boundary (routing is the triage seat's call).

Refs

#7832 / PR #7884 (provenance, workaround, partial pins), #6619 (where the ADR-0089 guidanceSets were added), ADR-0089.

Dedup: searched for alias-integrity / guidanceSet / VISIBILITY_KEY_PATTERN reachability — zero hits.

[hotlong]

Triage: promoted finding → pm:queue, routed domain:spec-tooling (the fix is gate machinery — extending alias-integrity to fail an alias row that a guidanceSet in the same strict options already consumes — which is the machine face per the #5163 boundary; no acceptance behavior changes). The class is real and the failure is silent-by-construction: a future vis-shaped alias row on VISIBILITY_STRICT_OPTIONS surfaces ships as dead code with every gate green, and PR #7884's pins protect only the specific keys it named.

Acceptance shape: the extended gate must fail a deliberately-planted dead row in its self-test (prove it can go red), and must pass the current live table — including confirming the one existing view-family alias (disabled → readonly on FormFieldSchema) stays reachable outside the pattern.

Size/model suggestion: S, mode:subagent, model: sonnet.

---

Generated by Claude Code

[os-zhuang]

Claim: PM loop round 4 (takeover shift, domain:spec-tooling seat #6018)
Session: session_01WocN37om5bw81JDoEEMA2e
Branch: claude/issue-7889-alias-guidance-reachability
Worktree: objectstack-issue-7889
Domain: domain:spec-tooling
File surface: packages/spec/src/shared/alias-integrity.test.ts (the gate being extended), possibly packages/spec/src/shared/alias-probe.ts or a small helper beside it; read-only on strict-object.ts / visibility.ts / the schema alias tables. ⛔ No packages/spec/src/**/*.zod.ts edits (if the extended gate turns red on a LIVE alias row, that is a finding to report, not a schema to "fix"), no acceptance-behavior change anywhere — this is gate machinery per the #5163 boundary, as triage's routing note says. Stop on breach; explain in the report.
Container & model: S mechanical (executable accept bar: planted dead row must go red, live table must stay green — correctness is gate-judged), mode:subagent, model: sonnet (adopting triage's Size/model suggestion as-is)
Serial constraints cleared: no in-flight card in this lane; PR #7884 (the provenance card's PR) is MERGED — its visible-when-alias-guidance.test.ts pins are same-day-landed neighbors, the dev works from current origin/main. None of the four hot-file rows in seat #6018 intersects this surface.

Pre-dispatch premise re-checks at origin/main (2026-08-12T08:5xZ): alias-integrity.test.ts / strict-object.ts (329 lines, 17 guidance/alias hits) / visible-when-alias-guidance.test.ts all present under packages/spec/src/shared/; VISIBILITY_KEY_PATTERN and VISIBILITY_STRICT_OPTIONS live in shared/visibility.ts (:121), and alias-integrity.test.ts already imports the pattern; the one live view-family alias row disabled: 'readonly' sits at ui/view.zod.ts:1775. The card's "consumes the key and continues past the rename channel" spelling was not directly grep-confirmed — treated as a mechanism claim for the dev to verify, not a fact.

---

Generated by Claude Code

[os-zhuang]

<!-- os-dev-report -->

{
  "issue": 7889,
  "status": "done",
  "branch": "claude/issue-7889-alias-guidance-reachability",
  "pr": "https://github.com/objectstack-ai/objectstack/pull/7952",
  "premise_still_valid": true,
  "summary": "Verified the mechanism directly in suggestions.zod.ts: strictUnknownKeyError consults exact `guidance`, then `guidanceSets`, and only then the `aliases` rename fallback -- a guidanceSets match `continue`s past the alias lookup entirely, confirming the card's premise. Extended alias-integrity.test.ts with `unreachableAliasRows(surfaces)`, which reads only `options.aliases` / `options.guidanceSets` (never `.shape`) and flags any alias key a same-table guidanceSet already matches via `keySetMatches`. Added a live-table verdict test (empty, plus an explicit pin that the one existing view-family alias `disabled -> readonly` on FormFieldSchema exists and sits on VISIBILITY_KEY_PATTERN's table, so the empty assertion is non-vacuous) and a self-test with a planted synthetic dead row plus two controls, proving the gate can go red without touching any live schema.",
  "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 clean, check:scripts-typecheck clean, check:test-typecheck OK (57 files / 265 errors held in shrink-only debt, unchanged). eslint src/shared/alias-integrity.test.ts -> clean. node scripts/check-nul-bytes.mjs -> OK. pnpm --filter '@objectstack/spec^...' build run first in a fresh worktree, succeeded.",
  "open_questions": [],
  "out_of_scope_findings": ["not filed: while reading the real control flow I confirmed the SAME precedence bug applies to exact `guidance` entries, not just `guidanceSets` -- a `guidance[key]` exact prescription also `continue`s past the alias table for that key. I checked whether this occurs on any live table (grepped every guidanceSets/aliases call site) and found no live collision, so it is not a present defect -- purely a theoretical extension of the same class the ruled acceptance shape did not ask for. Left unfiled since it would be speculative without a concrete live instance; noting it here in case the domain:spec-tooling seat wants it as a follow-up finding."]
}

---

Generated by Claude Code

[os-zhuang]

Correction to the prior comment: that one accidentally posted the HTML-escaped entity form of the marker instead of a real HTML comment. This comment supersedes it with the marker written correctly. The JSON report is unchanged from the prior comment's content.

{
  "issue": 7889,
  "status": "done",
  "branch": "claude/issue-7889-alias-guidance-reachability",
  "pr": "https://github.com/objectstack-ai/objectstack/pull/7952",
  "premise_still_valid": true,
  "summary": "Verified the mechanism directly in suggestions.zod.ts: strictUnknownKeyError consults exact `guidance`, then `guidanceSets`, and only then the `aliases` rename fallback -- a guidanceSets match `continue`s past the alias lookup entirely, confirming the card's premise. Extended alias-integrity.test.ts with `unreachableAliasRows(surfaces)`, which reads only `options.aliases` / `options.guidanceSets` (never `.shape`) and flags any alias key a same-table guidanceSet already matches via `keySetMatches`. Added a live-table verdict test (empty, plus an explicit pin that the one existing view-family alias `disabled -> readonly` on FormFieldSchema exists and sits on VISIBILITY_KEY_PATTERN's table, so the empty assertion is non-vacuous) and a self-test with a planted synthetic dead row plus two controls, proving the gate can go red without touching any live schema.",
  "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 clean, check:scripts-typecheck clean, check:test-typecheck OK (57 files / 265 errors held in shrink-only debt, unchanged). eslint src/shared/alias-integrity.test.ts -> clean. node scripts/check-nul-bytes.mjs -> OK. pnpm --filter '@objectstack/spec^...' build run first in a fresh worktree, succeeded.",
  "open_questions": [],
  "out_of_scope_findings": ["not filed: while reading the real control flow I confirmed the SAME precedence bug applies to exact `guidance` entries, not just `guidanceSets` -- a `guidance[key]` exact prescription also `continue`s past the alias table for that key. I checked whether this occurs on any live table (grepped every guidanceSets/aliases call site) and found no live collision, so it is not a present defect -- purely a theoretical extension of the same class the ruled acceptance shape did not ask for. Left unfiled since it would be speculative without a concrete live instance; noting it here in case the domain:spec-tooling seat wants it as a follow-up finding."]
}

---

Generated by Claude Code

[os-zhuang]

Review verdict: ACCEPT — PR #7952.

Verified against GitHub, not the report's claims: 1 file (packages/spec/src/shared/alias-integrity.test.ts, +133 test-only — no *.zod.ts, no docs/adr/**, no skill roots, no content/docs/releases/**; exactly the claim's declared surface). First line Fixes #7889 — correct, the card is fully resolved. The triage-ruled acceptance shape is met precisely: the planted synthetic dead row goes red with two negative controls (no set on the table; set present but non-matching), the live-table verdict is empty with an explicit non-vacuity pin (the disabled → readonly row confirmed to exist on a table carrying VISIBILITY_KEY_PATTERN), and the predicate reuses the real keySetMatches rather than re-implementing pattern matching. The card's mechanism premise was verified in the actual control flow (suggestions.zod.ts precedence, quoted in the PR body) rather than assumed. skip-changeset correctly applied (test/gate-only, no reader-visible behavior).

Two notes for the record: (a) the dev's disclosed-but-unfiled observation — the exact-guidance channel has the same precedence over aliases, with zero live collisions measured — is accepted as a disclosed non-filing (no present defect, no concrete instance; it is recorded here and in the PR, which is where a future collision's author will look); (b) the report marker survived only in HTML-entity form on this issue — content intact and searchable, noted for the sanitizer ledger.

Landing: CI convergence check armed; flip + queue on green.

---

Generated by Claude Code