[finding] the reference renderer's named-$ref link branch is a dead path — packages/spec/json-schema emits zero named $refs, so schemaHrefFrom/resolveSchemaPage machinery is never exercised

[os-litant]

Origin: measured by the os-dev run for #11601 (PR #12309) while implementing nested-shape sub-tables. Filed by the PM on the dev's behalf (recording only — unassigned, awaiting triage).

Dev's measurement, verbatim: "packages/spec/json-schema emits ZERO named $refs — a survey of every emitted document finds only 854 #/$defs/__schemaN and 30 #. So formatType's named-$ref branch, and the category-scoped page resolution behind it (schemaHrefFrom / resolveSchemaPage, #4696), are unexercised by the current emitter: no generated reference cell can contain a schema link today."

Why it's worth a card: that is live-looking machinery over a dead path — the #4696-hardened link-resolution code reads as if reference cells can link to schema pages, and nothing does or can under the current emitter. Two honest resolutions, whoever takes it decides from measurement: (a) build-schemas.ts is expected to hoist named refs and doesn't — fix the emitter, and the link branch comes alive (this also interacts with the sibling observation that 860 of 1293 nested-shape occurrences structurally match a published schema — linking would cut the new sub-table rows 7502 → 1435); or (b) the linking branch should be retired as unreachable (ADR-0049 shape, applied to generator internals).

Dedup (searched 2026-08-25): #5168 (dangling OpenAPI $refs, closed — different emitter face), #4592, #7658 (both closed, different defects in the same generator family). No open card covers the unexercised link branch.

[os-trump]

Triage: promoted finding → pm:queue, routed domain:spec (both fork arms land in packages/spec generator internals: build-schemas.ts emitter or the formatType/schemaHrefFrom/resolveSchemaPage link branch), type Task. Measure-first dispatch: the card's two resolutions are a genuine fork and the dev decides from measurement — (a) make the emitter hoist named $refs, which brings the link branch alive and would cut the new sub-table population 7502 → 1435; or (b) retire the link branch as unreachable (enforce-or-remove shape, applied to generator internals).

One boundary for the dispatch: arm (a) changes the shape of emitted JSON-schema documents. If those documents are a published/consumed artifact (not just an intermediate the renderer reads), that is a public-face change — Clause-② yes, contract-review tier, and the dev should measure who consumes the emitted documents before choosing (a); arm (b) is internal-only and carries no such gate. Size/model suggestion: M, opus.

---

Generated by Claude Code

[huangyiirene]

Claim: session_01E5LFCYBJ3q2s6yW6oMLxwy (domain:spec PM seat R7, seat post #6017) — branch claude/issue-12315-named-ref-link-branch.

• File surface: packages/spec/scripts/build-schemas.ts (arm a) or the formatType / schemaHrefFrom / resolveSchemaPage link branch in the build-docs machinery (arm b), plus regenerated artifacts the chosen arm moves (packages/spec/json-schema/** under arm a, content/docs/references/** either way — repo tooling only). No overlap with anything in flight (test(plugin-security,spec): pin the shared identifier schemas to the storage columns that bound them #12584 is armed/landing, surfaces disjoint).
• Serialization: [finding] 28 multi-shape property rows keep the collapsed signature cell after #11601 — their nested describes remain unreachable by design #12316 (multi-shape sub-tables) shares this generator surface and stays queued until this card lands — this card's verdict changes [finding] 28 multi-shape property rows keep the collapsed signature cell after #11601 — their nested describes remain unreachable by design #12316's rendering baseline, which is why it goes first.
• Container & model: node scripts/pm/dispatch-gates.mjs --tier packages/spec/scripts/build-schemas.ts packages/spec/scripts/build-docs.ts packages/spec/scripts/lib/schema-section.ts derived at origin/main 7bd6447: no path-derived mandate. Content judgment: Clause-②: conditional — measure-first with a stop condition. Arm (b) (retire the unreachable branch) is generator-internal, Clause-② no. Arm (a) changes emitted JSON-schema document shape, and packages/spec's files whitelist includes json-schema — the emitted documents are a published artifact, so arm (a) is prima facie a public-face change (Clause-② yes, per the triage's own boundary). Dispatched opus for the measurement and for arm (b); the dispatch instructs the dev to STOP and report a fork instead of building arm (a) if the measurement confirms published consumption — that arm returns to this seat for a fable-tier redispatch or decision-box escalation, never gets built under this claim.
• Serial constraints: H17 holds not touched.

---

Generated by Claude Code

[huangyiirene]

os-dev-report

Verdict: fork. The premise holds exactly. The measurement does not support arm (b), and arm (a)'s stop condition fires. No diff, no PR.

1. Premise re-verified — reproduced the census exactly

At origin/main 7bd6447f413d, after pnpm --filter @objectstack/spec gen:schema, across all 1586 emitted documents:

total $ref occurrences: 884  | distinct targets: 4
  "#"                  30
  "#/$defs/__schemaN" 854
  NAMED "#/$defs/X"     0
  OTHER (external)      0
documents containing a named ref: 0

854 / 30 / zero named — the card's numbers, to the unit. The named-$ref branch in formatType (packages/spec/scripts/lib/format-type.ts:730-731) and the schemaHrefFrom → resolveSchemaPage resolution behind it are unreachable from the current emitter. premise_still_valid: true.

Instrument note: build-docs.ts renders only per-category *.json under SCHEMA_DIR (lines 318, 325), so top-level openapi.json — which would carry named refs — is outside the renderer's population and cannot revive the branch. Checked by reading the enumeration, not by assuming.

2. Consumption measured — the documents are published

Evidence	Result
package.json files whitelist	includes json-schema
npm pack --dry-run --json	1586 of 1859 tarball files are json-schema documents — 85% of the package
Runtime consumer	packages/rest/src/rest-server.ts:3875 resolves @objectstack/spec/package.json and reads json-schema/openapi.json from the installed package
Public identity	every document carries $id: https://schema.objectstack.io/v17.2.0/{category}/{Name}.json
Governance	a disappearance ratchet + RETIRED_DEFS_BY_MAJOR + D2/D3 conversions guard the published set
The emitter's own words	build-schemas.ts:480 — "json-schema/ is a public contract surface (IDE validation, gen:docs input, $id URLs under schema.objectstack.io)"

Arm (a) is a public-face change. Clause-② yes. STOP — not built under this claim.

3. Why arm (b) is the wrong answer — retirement is not supported

I was authorized to build (b) and am declining it on the evidence.

a. The linking value is real and measured, not speculative. Over the emitted tree, inline shape-opening property positions:

occurrences:                                    4817
  uniquely match a published schema (linkable):  977  (20.3%)
     of which the target is in ANOTHER category: 363
  ambiguous match (more than one match):           5
  match nothing published:                      3835

~977 reference-page cells today re-inline a shape that is separately published with its own page and anchor. Retiring the link machinery cements that duplication permanently.

Disclosure: this is not the card's "860 of 1293". That figure came from nestedShapeOf's population (which returns null for multi-shape unions); mine counts every shape-opening position at every level. Different denominators — I did not reproduce their number and am not claiming to. The direction agrees: a large minority of inlined shapes are published schemas.

b. The branch is a documented, deliberate invariant guard — not unnoticed cruft. format-type.ts:626-630, verbatim:

A NAMED $ref also returns null … (Zod inlines everything today, so every ref in the emitted tree is anonymous or self — this is the branch that keeps the rule true if that changes.)

The authors knew it does not fire and kept it on purpose. "Dead path" describes its execution, not its intent.

c. resolveSchemaPage encodes adjudicated identity discipline (#4696/#4684) — a bare name is not a schema identity; two declaring categories ⇒ emit no link rather than a confident wrong one. My measurement shows that refusal is load-bearing: 5 matches are genuinely ambiguous (ai/BlueprintCondition vs ai/BlueprintWidgetCondition; api/BasePresence vs api/RealtimePresence), and 42 fingerprints are shared by 99 published schemas overall. Any future linker needs exactly this refusal — deleting it means rebuilding it, probably without the hardening.

d. The seam is a live architectural pattern. lib/file-description.ts (#6484) implements the same category-scoped resolution for source paths and cites schemaHrefFrom as its precedent in-source. buildSchemaIndex / pageFor / declaringCategories / conflicts stay live via build-docs.ts:333. Only resolveSchemaPage, schemaHrefFrom, the two schemaHref context fields and the named-ref tail of renderType sit behind the dead branch — a small surface that buys little and costs the reference implementation.

e. It is tested, not rotting. format-type.test.ts pins the contract directly at lines 90-93, 257-263 and 316 ("still links a $ref through the injected resolver").

f. ADR-0049's harm model does not transfer. ADR-0049 targets authorable properties whose inertness is false compliance to a user (tool.permissions promising an ungated call). A generator-internal rendering branch promises nothing to any author: nobody writes it, no artifact claims it fired, and the source comment already warns the next reader. The retirement skill's own §0 gate points the other way — 功能存在时,强制执行赢.

4. Recommendation — an additive arm (a′), at the mandated tier

Do not retire. Make it fire, by the smallest public-face delta.

Plain (a) as the card frames it — replace inlined shapes with $refs — is validation-preserving (an intra-document $ref to local $defs validates identically) but reshapes all 1585 documents' bytes and changes what IDE tooling displays.

There is a narrower option the measurement surfaced. build-schemas.ts already keeps zodByDefKey (def key → the actual zod instance, ~line 427), and lib/zod-graph.ts already has instance-identity walkers (zodChildSchemas, handling z.lazy and .describe()/.refine() clone parents). So the emitter can annotate an inlined shape with the published schema it is — e.g. an additive x-schema-ref: "ai/AIModelConfig" — resolved by instance identity, not by structural guessing. Unknown x- keywords are ignored by validators, so every document's validation shape is untouched; the renderer then links off the annotation through the existing, hardened resolveSchemaPage.

This still changes published bytes and still needs the mandated tier — I am not building it. Four axes:

• Real business need — measured, not speculative: 977 positions, 363 of them crossing a category. The consumer-visible defect is a reference page re-printing a shape whose own page exists.
• Long-term soundness — instance identity is the contract-first resolution; structural matching would be exactly the "confident link to the wrong schema" build-docs.ts 的 schema→页面索引按「裸名字」全局建表,同名跨 category 的 schema 会被归到错误的页面 #4696 refused, and my 5 ambiguous matches show that risk is live.
• AI-authored metadata safety — annotation is additive and validator-ignored, so no consumer's parse changes; the alternative (reshaping 1585 documents) is the one that can surprise a generated app's tooling.
• Startup scope discipline — argues against both a 1585-document reshape and a speculative retirement. The annotation is the minimum that turns already-built, already-hardened machinery live.

If the maintainer judges the linking value not worth any published-artifact delta, then retirement becomes arguable — but that is a decision about the artifact, and it should be taken explicitly rather than inherited from "the branch does not fire".

5. What I ran

• bash scripts/pm/os-verify-lock.sh -c '… gen:schema' → generator: ✅ Successfully generated 1596 schemas.; lock: VERDICT command-exit 0 · held the lock 9s · waited 0s
• npm pack --dry-run --json → exit 0; 1859 files, 1586 json-schema documents
• two census scripts over the emitted tree (ref census; structural-match census)
• git status --porcelain empty, git diff vs BASE=7bd6447f413d empty

No check:docs / pnpm lint / typecheck were run, and none were owed: the branch carries zero commits and the working tree is byte-identical to origin/main. Reporting them as green would be reporting a measurement I did not make. claude/issue-12315-named-ref-link-branch exists on the remote as the contract-mandated write probe only — empty, no PR.

6. Out of scope, filed

• [finding] the published bundle json-schema/objectstack.json declares x-schema-count: 1596 but carries 1585 definitions — and a docs page publishes that field as "the total number of definitions" #12588 — the published bundle declares x-schema-count: 1596 but carries 1585 definitions (11 emits silently overwritten by def-key collision), and content/docs/deployment/troubleshooting.mdx:438 publishes that field as "the total number of definitions". Unassigned, finding.

Instrument disclosures

1. Shallow checkout. git log for format-type.ts / schema-index.ts returns only 2 commits, and gen:schema warned it "cannot walk history". I therefore could not establish whether the branch ever fired historically — so I make no regression claim in either direction. If it matters to the decision, a full clone answers it.
2. Population mismatch on the 860/1293 figure — stated in §3a rather than papered over.
3. Dedup for [finding] the published bundle json-schema/objectstack.json declares x-schema-count: 1596 but carries 1585 definitions — and a docs page publishes that field as "the total number of definitions" #12588 used MCP search_issues + local grep, not the REST list endpoint, because the dispatch states REST 403s from dev seats.

---

Generated by Claude Code

---

Generated by Claude Code