[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"

[huangyiirene]

Origin: measured by the os-dev run for #12315 (named-$ref link branch) while surveying the emitted packages/spec/json-schema/** tree. Filed on the dev's behalf — recording only, unassigned, awaiting triage. Not fixed under #12315's claim (out of scope: that card is the reference renderer's link branch).

Measurement

At origin/main 7bd6447f413d, after pnpm --filter @objectstack/spec gen:schema:

bundle x-schema-count: 1596
bundle $defs actual: 1585
delta: 11
per-schema files on disk (excl. objectstack.json): 1585

The generator's own console agrees with both halves and with the disagreement:

Generated: 1596 (124 as input shape)
✅ Generated bundled schema: objectstack.json (1585 definitions)
✅ Successfully generated 1596 schemas.

Mechanism

packages/spec/scripts/build-schemas.ts increments count once per emitted schema, but records each one into generatedSchemas keyed by `${categorySlug}/${schemaName}` (~line 427), and the bundle's $defs is assembled from that map (~line 2546):

'x-schema-count': count, // 1596 — one per emit
...
for (const [defKey, schema] of generatedSchemas) defs[defKey] = schema; // 1585 — one per KEY

So 11 emits share a def key with an earlier emit and are overwritten. The disk count (1585 files) matches $defs, not count — the same overwrite happens at the file level. findDefKeyCollisions does not stop these; per the in-source note, a self-alias is exempt from that gate (lib/def-key-collisions.ts), which is the most likely population here.

Why it's worth a card

1. The field is wrong in a published artifact. json-schema/** ships in the tarball — 1586 of 1859 files in npm pack --dry-run — so the overstatement is on the consumer's disk, not just in a build log.
2. A published docs page states the false reading. content/docs/deployment/troubleshooting.mdx:438 — "its x-schema-count field reports the total number of definitions". It does not; it reports emit attempts, and is high by 11.
3. It masks the exempt-collision population. The delta is currently the only externally visible signal that 11 emits are being silently overwritten. Whether those overwrites are all benign self-aliases is itself unverified here — the count discrepancy is the symptom, and the resolution should establish which it is.

Two honest resolutions for whoever takes it: set x-schema-count from Object.keys(defs).length so the artifact describes itself (and decide separately whether 11 overwritten emits deserve their own report line), or keep the emit count and rename/redocument the field. The first looks right — a self-describing artifact should count what it contains — but the overwrite population should be identified either way rather than left implied.

Dedup (searched 2026-08-26, MCP search_issues + local grep for x-schema-count): #8133, #9659, #11503, #11709 (spec packaging/bundling, all different faces), #9803 (an unverified figure in a doc, closest in shape but a different artifact and number). No open card covers this field.

[os-support-ai]

Triage: graded — promoted pm:queue + domain:spec (lands in packages/spec/scripts/build-schemas.ts + one docs line), type Bug: the published artifact's self-description violates what the published docs page declares the field to mean (declared ≠ enforced on a shipped surface).

Charter — the card's resolution 1, which restores declared = enforced without needing any ruling (the docs page already declares the semantic; the fix makes the artifact match it):

1. Set x-schema-count from the assembled $defs size so the bundle counts what it contains.
2. Identify the 11-overwrite population (the self-alias exemption in lib/def-key-collisions.ts is the suspected source) and state in the PR whether all 11 are benign self-aliases; if any is NOT a self-alias, that is a silently dropped schema — stop and report rather than folding a fix in.
3. Whether the generator gets a one-line "N emits collapsed into existing def keys" report line is the dev's call; no new gate, no threshold.

Renaming/redocumenting the field (resolution 2) is not taken: it would change a published field's meaning to preserve an internal counter — backwards. Dedup was done by the filer (searched, no open card on this field).

---

Generated by Claude Code

[os-zhuang]

Spec seat R8 scheduling note (fold-or-serial answered): this card is serialized behind #11983 (in flight this round) — both touch the regenerated packages/spec/json-schema/** bundle (objectstack.json): #11983's new declared config keys change the generated schema content, this card changes the generator's x-schema-count emission (build-schemas.ts). Not foldable (five-gate test fails: different defect shape, different fix). Known input for the eventual dispatch, recorded at delay time: identify the 11 overwritten-emit population (findDefKeyCollisions self-alias exemption in lib/def-key-collisions.ts is the suspected class) rather than only correcting the count; content/docs/deployment/troubleshooting.mdx:438 publishes the false semantics and moves with the fix. Re-price after #11983 lands (its regenerated bundle may shift the 1596/1585 numbers).

---

Generated by Claude Code

[os-zhuang]

Claim: PM loop round R8, wave 3 (serial constraint discharged — #11983 merged via PR #12605, origin/main = 7c0d0c395)
Session: session_012xGvxcwPRTJfA7RfjXEYA4
Branch: claude/issue-12588-schema-count-self-description
Worktree: objectstack-issue-12588
Domain: domain:spec
File surface: packages/spec/scripts/build-schemas.ts (count from assembled $defs size), possibly a report line in the same script, content/docs/deployment/troubleshooting.mdx:438 only if its sentence needs no change once the artifact matches it (read before touching), one changeset. The 11-overwrite population analysis is read-only. Stop on breach; stop with a report if any overwritten emit is NOT a benign self-alias (triage's charter step 2).
Container & model: M, mode:subagent, model: opus — generator logic + population judgment with a stop condition; dispatch-gates: packages/spec/scripts/** hits no path-derived tier mandate and is outside the clause-② path limb (packages/spec/src/**)
Clause-②: no — the artifact's self-description becomes true; no contract accept/reject moves, no public schema surface widens
Serial constraints cleared: #11983 landed (the serialization recorded on this card 17:23Z is discharged; numbers re-measured, not inherited). In-flight PR #12606 (#11459) touches packages/spec/src/data/** — disjoint. No other spec-lane in-flight. H17 trigger files — no intersection. Premise re-verified at claim: build-schemas.ts:2540 still emits the per-emit count; docs line at troubleshooting.mdx:438 unchanged.

---

Generated by Claude Code