fix(spec): the bundled JSON Schema's x-schema-count counts the definitions it carries (#12588) (#12610)

* fix(spec): x-schema-count counts the definitions the bundle carries

The bundled objectstack.json took x-schema-count from the per-emit counter
while its $defs is keyed by def key, so every self-aliased key inflated the
published field: 1596 declared, 1585 shipped. Assemble $defs first and count
what the artifact contains.

Also name the exempt population the guard allows through, so the collapsed
emits are reported rather than left implicit in a subtraction.

* test(spec): pin that the bundle's x-schema-count equals its $defs size

Unit half: the exempt self-alias population and the emits it absorbs.
End-to-end half: the artifact the generator really writes, cross-checked
against the files on disk and the run's own console.

* chore(spec): changeset for the x-schema-count correction

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: os-zhuang

.changeset/schema-count-counts-the-definitions-shipped.md

@@ -0,0 +1,36 @@
+---
+"@objectstack/spec": patch
+---
+
+fix(spec): the bundled JSON Schema's `x-schema-count` counts the definitions it carries (#12588)
+
+`json-schema/objectstack.json` ships in the tarball (`json-schema` is in the
+package's `files`), and `content/docs/deployment/troubleshooting.mdx` publishes
+what the field means: "its `x-schema-count` field reports the total number of
+definitions". It did not. The generator took the number from `count` — a
+counter incremented once per emitted schema — while the bundle's `$defs` is
+assembled from a map keyed by `<category>/<Name>`. Every def key written more
+than once therefore widened a gap nothing reconciled: the published bundle
+declared **1596** definitions while carrying **1585**.
+
+`$defs` is now assembled before the envelope and the field is taken from its
+size, so the artifact describes itself. The per-schema files on disk already
+agreed with `$defs` (1585) — the same key collapses the file writes — so this
+brings the one disagreeing number into line with both of the others, and the
+docs sentence is true as written without changing it.
+
+**The collapsed emits are now named rather than implied.** The 11 def keys
+written twice are all **benign self-aliases** — `export const X = XSchema`
+spelled as `Object.assign(XSchema, …)`, one schema object reached by two export
+names, so the second write cannot change what is published. Eight in `api`
+(`ApiEndpoint`, `RestApiConfig`, `RestServerConfig`, `ApiDocumentationConfig`,
+`ApiTestCollection`, `OpenApiSpec`, `RestApiPluginConfig`,
+`RestApiRouteRegistration`) and three in `system` (`MiddlewareConfig`,
+`QueueConfig`, `Task`). No schema is being silently dropped: the existing
+`findDefKeyCollisions` guard exits the build on any def key claimed by two
+*different* schemas, so a build that produces a bundle at all has only exempt
+ones — and `gen:schema` now prints that population instead of leaving it
+visible only as a subtraction between two summary lines.
+
+No schema content changes; only the bundle's self-description and the
+generator's console output.

packages/spec/scripts/build-schemas-check-mode.test.ts

@@ -2185,6 +2185,118 @@ describe('build-schemas.ts — the output clean spares a sibling generator (#537
   );
 });
 
+// ─────────────────────────────────────────────────────────────────────────────
+// #12588 — the bundle's `x-schema-count` counts what the bundle carries.
+//
+// `objectstack.json` ships in the npm tarball and a docs page publishes the
+// field's meaning ("its `x-schema-count` field reports the total number of
+// definitions"), so the number is a contract, not a build log. It used to be
+// taken from `count` — incremented once per EMIT — while `$defs` is assembled
+// from a map keyed by `<category>/<Name>`. Every def key written twice therefore
+// widened a gap nothing reconciled: the published bundle declared 1596
+// definitions and shipped 1585.
+//
+// The unit half (scripts/def-key-collisions.test.ts) pins the arithmetic. What
+// only this sandbox can assert is that the artifact the generator really writes
+// describes itself correctly — the assertions below read the emitted bytes, not
+// a helper's return value. `src/` is symlinked into the sandbox, so this runs
+// over the REAL spec surface (~1600 schemas), which is also what makes the
+// non-vacuity guard below meaningful: this build genuinely collapses emits.
+//
+// The invariant is pinned, never today's absolute number — 1585 moves with
+// every schema anyone adds, and a test that has to be edited by unrelated PRs
+// gets edited without being read.
+describe('build-schemas.ts — the bundle counts the definitions it carries (#12588)', () => {
+  const OUT = () => path.join(sandbox, 'json-schema');
+
+  beforeEach(() => {
+    // A current, self-consistent tree, so the run exits 0 and these assertions
+    // are about the bundle rather than about some ratchet upstream of it.
+    seedManifest((s) => s);
+    const tip = seedBase((s) => s);
+    seedSurface((s) => s);
+    seedSurfaceBase(tip, (k) => k);
+  });
+
+  it(
+    'writes x-schema-count equal to its own $defs size, and to the files on disk',
+    { timeout: SPAWN_TIMEOUT_MS },
+    () => {
+      const { status, output } = run([]);
+      expect(status).toBe(0);
+
+      const bundle = JSON.parse(
+        fs.readFileSync(path.join(OUT(), 'objectstack.json'), 'utf8'),
+      ) as { 'x-schema-count': number; $defs: Record<string, unknown> };
+      const defCount = Object.keys(bundle.$defs).length;
+
+      // 1. The artifact describes itself.
+      expect(bundle['x-schema-count']).toBe(defCount);
+
+      // 2. A second, independent instrument: one file per def key on disk. The
+      //    per-schema writes collapse the same way the map does, so the tree is
+      //    a witness the bundle cannot fabricate. `openapi.json` belongs to
+      //    gen:openapi and objectstack.json is the bundle itself.
+      const onDisk = fs
+        .readdirSync(OUT(), { recursive: true, encoding: 'utf8' })
+        .filter(
+          (entry) =>
+            entry.endsWith('.json') &&
+            path.basename(entry) !== 'objectstack.json' &&
+            path.basename(entry) !== 'openapi.json',
+        );
+      expect(onDisk).toHaveLength(defCount);
+
+      // 3. The generator's own console agrees, so a reader of the build log and
+      //    a reader of the artifact reach the same number.
+      expect(output).toContain(`objectstack.json (${defCount} definitions)`);
+    },
+  );
+
+  it(
+    'accounts for every emit the definition count does not include',
+    { timeout: SPAWN_TIMEOUT_MS },
+    () => {
+      const { status, output } = run([]);
+      expect(status).toBe(0);
+
+      const bundle = JSON.parse(
+        fs.readFileSync(path.join(OUT(), 'objectstack.json'), 'utf8'),
+      ) as { 'x-schema-count': number };
+      const emitted = Number(/Successfully generated (\d+) schemas/.exec(output)?.[1]);
+      expect(Number.isFinite(emitted), 'summary line must report the emit total').toBe(true);
+
+      // Non-vacuity: this build must still collapse emits, or the case proves
+      // nothing about the defect. If a future PR removes the last self-alias
+      // from the spec, `x-schema-count: count` and the correct expression stop
+      // differing and this pin can no longer fail — delete it deliberately
+      // then, rather than discovering later that it had gone quiet.
+      expect(
+        emitted,
+        'no emit collapses any more — this build no longer models #12588',
+      ).toBeGreaterThan(bundle['x-schema-count']);
+
+      // The delta is reported, not left as a subtraction between two lines —
+      // that silence is what let a wrong number ship unnoticed. The reported
+      // figure must reconcile the two totals exactly.
+      const collapsed = Number(/ℹ️\s+(\d+) emit\(s\) collapsed/.exec(output)?.[1]);
+      expect(Number.isFinite(collapsed), 'the collapsed-emit report line must be printed').toBe(true);
+      expect(emitted - collapsed).toBe(bundle['x-schema-count']);
+
+      // Every collapsed key is named, and named as a self-alias: the guard
+      // upstream exits on any def key written twice by DIFFERENT schemas, so a
+      // build that reaches here has only benign ones. Stating it in the report
+      // is what makes that population readable instead of implied.
+      expect(output).toContain('all self-aliases');
+      const named = [...output.matchAll(/ {5}json-schema\/(\S+)\.json {2}<- {2}/g)].map((m) => m[1]);
+      expect(named.length).toBeGreaterThan(0);
+      for (const defKey of named) {
+        expect(fs.existsSync(path.join(OUT(), `${defKey}.json`))).toBe(true);
+      }
+    },
+  );
+});
+
 // ─────────────────────────────────────────────────────────────────────────────
 // #4659 — check (b) registers a tombstone by its EXACT key, not by its leaf.
 //

packages/spec/scripts/build-schemas.ts

@@ -11,7 +11,9 @@ import { spawnSync } from 'child_process';
 import { z } from 'zod';
 import { schemaNameFromExportKey } from './lib/schema-name';
 import {
+  collapsedEmitCount,
   findDefKeyCollisions,
+  findSelfAliasedDefKeys,
   formatDefKeyCollisions,
   type EmittedDef,
 } from './lib/def-key-collisions';
@@ -475,6 +477,28 @@ if (defKeyCollisions.length > 0) {
   process.exit(1);
 }
 
+// ─── Report: the writes the guard above exempted (#12588) ─────────────
+// Reaching here means every def key written twice is a self-alias, because the
+// guard exits on any that is not. Those writes still collapse — `count` is one
+// per EMIT while `generatedSchemas` is keyed by def key — so the emit total is
+// higher than the number of definitions this build publishes. That difference
+// used to be visible only as a subtraction between two summary lines, and it
+// leaked into the published bundle as an `x-schema-count` nobody could reconcile
+// with the `$defs` beside it. Name the population instead of implying it.
+// A report, not a gate: there is no threshold here and no exit path.
+const selfAliasedDefKeys = findSelfAliasedDefKeys(emittedDefs);
+const collapsedEmits = collapsedEmitCount(selfAliasedDefKeys);
+if (collapsedEmits > 0) {
+  console.log(
+    `\nℹ️  ${collapsedEmits} emit(s) collapsed into ${selfAliasedDefKeys.length} existing def key(s) ` +
+      `— all self-aliases (one schema object reached by two export names), so ${count} emits publish ` +
+      `${generatedSchemas.size} definitions:`,
+  );
+  for (const alias of selfAliasedDefKeys) {
+    console.log(`     json-schema/${alias.defKey}.json  <-  ${alias.exportKeys.join(', ')}`);
+  }
+}
+
 // ─── Ratchet: a published schema must never silently disappear ────────
 // json-schema/ is a public contract surface (IDE validation, gen:docs input,
 // $id URLs under schema.objectstack.io). The manifest is the committed record
@@ -2531,24 +2555,31 @@ if (defaultsChanged && !CHECK) {
 // ─── Generate Bundled Schema ─────────────────────────────────────────
 // Single-file bundled schema containing all generated schemas for IDE autocomplete
 
+// Assemble bundled $defs from the in-memory map populated during generation.
+// (Avoid re-reading the json-schema/ tree to dodge CI filesystem races.)
+//
+// Assembled BEFORE the envelope, so `x-schema-count` below is taken from what
+// this bundle actually carries (#12588). It used to be `count`, the per-EMIT
+// counter, while `$defs` is keyed by def key — so every self-aliased key
+// reported above widened the gap, and the published artifact declared 1596
+// definitions while shipping 1585. A self-describing artifact counts what it
+// contains; the emit total is a property of the build, not of the file, and is
+// still reported on the summary line at the end of this script.
+const defs: Record<string, unknown> = {};
+for (const [defKey, schema] of generatedSchemas) {
+  defs[defKey] = schema;
+}
+
 const bundledSchema: Record<string, unknown> = {
   $schema: 'https://json-schema.org/draft/2020-12/schema',
   $id: `${SCHEMA_BASE_URL}/objectstack.json`,
   title: 'ObjectStack Protocol',
   description: `ObjectStack Protocol v${SPEC_VERSION} — Complete bundled JSON Schema for IDE autocomplete`,
   'x-spec-version': SPEC_VERSION,
-  'x-schema-count': count,
-  $defs: {} as Record<string, unknown>,
+  'x-schema-count': Object.keys(defs).length,
+  $defs: defs,
 };
 
-const defs = bundledSchema.$defs as Record<string, unknown>;
-
-// Assemble bundled $defs from the in-memory map populated during generation.
-// (Avoid re-reading the json-schema/ tree to dodge CI filesystem races.)
-for (const [defKey, schema] of generatedSchemas) {
-  defs[defKey] = schema;
-}
-
 const bundledPath = path.join(OUT_DIR, 'objectstack.json');
 writeFileWithRetry(bundledPath, JSON.stringify(bundledSchema, null, 2));
 console.log(`\n✅ Generated bundled schema: objectstack.json (${Object.keys(defs).length} definitions)`);

packages/spec/scripts/def-key-collisions.test.ts

@@ -30,7 +30,9 @@ import path from 'node:path';
 import { SCHEMA_MANIFEST_DIR_NAME } from './lib/sharded-artifacts';
 
 import {
+  collapsedEmitCount,
   findDefKeyCollisions,
+  findSelfAliasedDefKeys,
   formatDefKeyCollisions,
   type EmittedDef,
 } from './lib/def-key-collisions';
@@ -110,6 +112,114 @@ describe('findDefKeyCollisions', () => {
   });
 });
 
+// ─────────────────────────────────────────────────────────────────────────
+// #12588 — the exempt population, enumerated.
+// ─────────────────────────────────────────────────────────────────────────
+//
+// `findDefKeyCollisions` is silent about self-aliases because they are not a
+// problem. They are, however, the reason a build's emit count exceeds the
+// number of definitions it publishes — and that unexplained delta is what put a
+// wrong `x-schema-count` into the shipped bundle. These pin the other half.
+
+describe('findSelfAliasedDefKeys — the population the guard exempts (#12588)', () => {
+  it('reports a self-alias, which is exactly what findDefKeyCollisions stays silent about', () => {
+    const task = { type: 'object' };
+    const entries = [emitted('system', 'Task', task), emitted('system', 'TaskSchema', task)];
+
+    expect(findSelfAliasedDefKeys(entries)).toEqual([
+      { defKey: 'system/Task', exportKeys: ['Task', 'TaskSchema'] },
+    ]);
+    // The two verdicts are complementary, not overlapping.
+    expect(findDefKeyCollisions(entries)).toEqual([]);
+  });
+
+  it('is silent about a real collision — that one belongs to the guard, not to a report', () => {
+    const entries = [
+      emitted('shared', 'HttpMethod', { enum: ['GET', 'HEAD'] }),
+      emitted('shared', 'HttpMethodSchema', { enum: ['GET'] }),
+    ];
+
+    expect(findSelfAliasedDefKeys(entries)).toEqual([]);
+    expect(findDefKeyCollisions(entries)).toHaveLength(1);
+  });
+
+  it('ignores a def key written once — one write collapses nothing', () => {
+    expect(findSelfAliasedDefKeys([emitted('data', 'FieldSchema', {})])).toEqual([]);
+  });
+
+  it('partitions every multiply-written def key between the two functions', () => {
+    // The invariant that makes "emits - definitions" fully accounted for: a key
+    // written more than once is either exempt or a collision, never neither and
+    // never both. Asserted over a mixed build rather than stated in prose.
+    const alias = {};
+    const entries = [
+      emitted('ui', 'ThemeModeSchema', alias),
+      emitted('ui', 'ThemeMode', alias),
+      emitted('shared', 'HttpMethod', { a: 1 }),
+      emitted('shared', 'HttpMethodSchema', { a: 2 }),
+      emitted('data', 'FieldSchema', {}),
+    ];
+
+    const aliases = findSelfAliasedDefKeys(entries).map((a) => a.defKey);
+    const collisions = findDefKeyCollisions(entries).map((c) => c.defKey);
+
+    expect(aliases).toEqual(['ui/ThemeMode']);
+    expect(collisions).toEqual(['shared/HttpMethod']);
+    expect(aliases.filter((k) => collisions.includes(k))).toEqual([]);
+    // Every key with more than one write is claimed by exactly one of them.
+    const writtenTwice = ['ui/ThemeMode', 'shared/HttpMethod'];
+    expect([...aliases, ...collisions].sort()).toEqual([...writtenTwice].sort());
+  });
+
+  it('follows first-encounter order, so a build report is stable across runs', () => {
+    const a = {};
+    const b = {};
+    expect(
+      findSelfAliasedDefKeys([
+        emitted('system', 'QueueConfig', b),
+        emitted('api', 'ApiEndpoint', a),
+        emitted('api', 'ApiEndpointSchema', a),
+        emitted('system', 'QueueConfigSchema', b),
+      ]).map((x) => x.defKey),
+    ).toEqual(['system/QueueConfig', 'api/ApiEndpoint']);
+  });
+});
+
+describe('collapsedEmitCount — the emits a self-aliased key absorbs (#12588)', () => {
+  it('counts N-1 per key: the first write is the definition, the rest collapse onto it', () => {
+    expect(
+      collapsedEmitCount([
+        { defKey: 'api/ApiEndpoint', exportKeys: ['ApiEndpoint', 'ApiEndpointSchema'] },
+        { defKey: 'system/Task', exportKeys: ['Task', 'TaskSchema'] },
+      ]),
+    ).toBe(2);
+  });
+
+  it('counts a triple alias as two collapsed emits, not one', () => {
+    expect(
+      collapsedEmitCount([{ defKey: 'api/Thing', exportKeys: ['Thing', 'ThingSchema', 'ThingZod'] }]),
+    ).toBe(2);
+  });
+
+  it('is zero on a build where nothing collapsed', () => {
+    expect(collapsedEmitCount([])).toBe(0);
+  });
+
+  it('reconciles the two totals: emits - collapsed = definitions', () => {
+    // The arithmetic the published `x-schema-count` got wrong, in miniature.
+    const alias = {};
+    const entries = [
+      emitted('api', 'ApiEndpoint', alias),
+      emitted('api', 'ApiEndpointSchema', alias),
+      emitted('data', 'FieldSchema', {}),
+      emitted('data', 'ObjectSchema', {}),
+    ];
+    const definitions = new Set(entries.map((e) => `${e.category}/${e.schemaName}`)).size;
+
+    expect(entries.length - collapsedEmitCount(findSelfAliasedDefKeys(entries))).toBe(definitions);
+  });
+});
+
 describe('formatDefKeyCollisions', () => {
   it('names the file that would be written, both export keys, and the source-side remedies', () => {
     const message = formatDefKeyCollisions([