@xemahq/repo-build-tooling 0.4.0 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xemahq/repo-build-tooling",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Dev-time build tooling shared by every Xema repository. Ships as plain ESM with zero dependencies so the published artifact is the reviewed source.",
   "license": "Apache-2.0",
   "author": "Neuralchowder Inc. <developer@xema.dev> (https://xema.dev)",
@@ -21,17 +21,19 @@
     "src"
   ],
   "bin": {
-    "xema-scrub-swagger-paths": "src/scrub-swagger-plugin-paths.mjs",
+    "xema-check-no-vendored-deps": "src/check-no-vendored-deps.mjs",
     "xema-check-workspace-ranges": "src/check-workspace-range-matches-local.mjs",
-    "xema-check-no-vendored-deps": "src/check-no-vendored-deps.mjs"
+    "xema-readiness": "src/readiness.mjs",
+    "xema-scrub-swagger-paths": "src/scrub-swagger-plugin-paths.mjs"
   },
   "exports": {
     "./check-no-vendored-deps": "./src/check-no-vendored-deps.mjs",
     "./check-workspace-range-matches-local": "./src/check-workspace-range-matches-local.mjs",
     "./package.json": "./package.json",
+    "./readiness": "./src/readiness.mjs",
     "./scrub-swagger-plugin-paths": "./src/scrub-swagger-plugin-paths.mjs"
   },
   "scripts": {
-    "test": "node src/scrub-swagger-plugin-paths.mjs --self-test && node --test src/check-workspace-range-matches-local.test.mjs && node --test src/check-no-vendored-deps.test.mjs"
+    "test": "node src/scrub-swagger-plugin-paths.mjs --self-test && node --test src/check-workspace-range-matches-local.test.mjs && node --test src/check-no-vendored-deps.test.mjs && node --test src/readiness.test.mjs"
   }
 }

package/src/check-workspace-range-matches-local.mjs

@@ -75,19 +75,33 @@ export function satisfies(version, range) {
   return v[0] === base[0];
 }
 
-function listManifests() {
+/**
+ * Every `package.json` in the repository, EXCLUDING `node_modules`, `dist` and
+ * `.git`.
+ *
+ * `-prune` rather than `-not -path`, and the difference is not a style
+ * preference. A `-not -path` exclusion on a node_modules glob FILTERS the
+ * results while still
+ * DESCENDING into every one of them, so this walked hundreds of thousands of
+ * installed files to discard all of them — and, because it descended, it raced
+ * anything writing there. Measured 2026-09-18 on xema-base: the walk entered
+ * `node_modules/.cache/xema-declared-kernel/.staging-<version>-XXXX/`, a
+ * temporary directory another step deleted mid-walk, `find` exited non-zero,
+ * and `execFileSync` threw. The gate did not report a violation — it CRASHED,
+ * which reads in CI as a failing check rather than an absent one.
+ *
+ * Pruning cannot race what it never enters.
+ */
+export function listManifests(root = REPO_ROOT) {
   return execFileSync(
     'find',
     [
-      REPO_ROOT,
-      '-name',
-      'package.json',
-      '-not',
-      '-path',
-      '*/node_modules/*',
-      '-not',
-      '-path',
-      '*/dist/*',
+      root,
+      '(', '-name', 'node_modules', '-o', '-name', 'dist', '-o', '-name', '.git', ')',
+      '-prune',
+      '-o',
+      '-name', 'package.json',
+      '-print',
     ],
     { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 },
   )
@@ -131,16 +145,30 @@ export function findViolations({ rewrite = false } = {}) {
     }
     if (mutated) writeFileSync(file, `${JSON.stringify(pkg, null, 2)}\n`);
   }
-  return violations;
+  return { violations, scanned: manifests.length };
 }
 
 function main() {
   const rewrite = process.argv.includes('--fix');
-  const violations = findViolations({ rewrite });
+  const { violations, scanned } = findViolations({ rewrite });
+
+  // A scan that read NOTHING and a scan that found nothing wrong print the
+  // same green and exit the same 0. Only the corpus separates them, so this
+  // refuses rather than reporting a pass it cannot justify. REPO_ROOT's own
+  // manifest is asserted to exist above, so zero here means the walk failed.
+  if (scanned === 0) {
+    console.error(
+      `::error::scanned 0 manifests under ${REPO_ROOT} — the walk found nothing, ` +
+        'not even this repository\'s own package.json. Refusing to report a pass ' +
+        'over an empty corpus.',
+    );
+    return 1;
+  }
 
   if (violations.length === 0) {
     console.log(
-      'workspace ranges match their local packages — every build edge is visible to pnpm.',
+      `workspace ranges match their local packages in all ${scanned} manifest(s) — ` +
+        'every build edge is visible to pnpm.',
     );
     return 0;
   }

package/src/check-workspace-range-matches-local.test.mjs

@@ -10,9 +10,12 @@
  * that specific wrong implementation.
  */
 import assert from 'node:assert/strict';
+import { chmodSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, relative } from 'node:path';
 import test from 'node:test';
 
-import { satisfies } from './check-workspace-range-matches-local.mjs';
+import { listManifests, satisfies } from './check-workspace-range-matches-local.mjs';
 
 test('^0.y.z pins the MINOR — the rule the whole check turns on', () => {
   // The real defect: a client moved 0.2.0 -> 0.3.0 and fell out of every
@@ -52,3 +55,51 @@ test('a prerelease is compared on its release part, never string-wise', () => {
   assert.equal(satisfies('0.3.0-rc.1', '^0.2.0'), false);
   assert.equal(satisfies('0.2.5-rc.1', '^0.2.0'), true);
 });
+
+// ── The WALK, not the predicate ───────────────────────────────────────────
+// A `-not -path` exclusion on a node_modules glob filters results while still
+// DESCENDING into
+// every one of them. That is not merely slow: it made the gate race a sibling
+// step that was deleting a temp directory under `node_modules`, so `find`
+// exited non-zero and the check CRASHED rather than reporting a violation.
+// A crash reads in CI as a failing check rather than an absent one.
+//
+// Two-sided on purpose. Asserting only that the pruned paths are absent would
+// also pass if the walk returned NOTHING — the empty-corpus failure this file
+// already warns about, one function over.
+test('listManifests does not DESCEND into node_modules — an untraversable dir there must not break the walk', () => {
+  const root = mkdtempSync(join(tmpdir(), 'xema-prune-'));
+  const blocked = join(root, 'node_modules', 'blocked');
+  try {
+    const write = (rel) => {
+      mkdirSync(join(root, dirname(rel)), { recursive: true });
+      writeFileSync(join(root, rel), '{"name":"x","version":"1.0.0"}\n');
+    };
+    write('package.json');
+    write('packages/real/package.json');
+    write('packages/real/dist/package.json');
+    write('node_modules/installed/package.json');
+
+    // Reproduces the real failure: a directory under node_modules the walk
+    // cannot traverse. A FILTERING walk descends, `find` exits non-zero on
+    // "Permission denied", and execFileSync THROWS -- the gate crashes instead
+    // of reporting a violation. A PRUNING walk never enters it.
+    //
+    // This is what the previous version of this test missed: `-not -path`
+    // filters the OUTPUT, so both walks return the identical set and an
+    // output assertion cannot tell them apart. Only descent is observable,
+    // and this is how you observe it.
+    mkdirSync(blocked, { recursive: true });
+    chmodSync(blocked, 0o000);
+
+    const found = listManifests(root).map((f) => relative(root, f)).sort();
+
+    // Control: the walk really ran and found the real manifests.
+    assert.deepEqual(found, ['package.json', 'packages/real/package.json']);
+    assert.equal(found.some((f) => f.includes('node_modules')), false);
+    assert.equal(found.some((f) => f.includes('dist')), false);
+  } finally {
+    try { chmodSync(blocked, 0o755); } catch { /* never created */ }
+    rmSync(root, { recursive: true, force: true });
+  }
+});

package/src/readiness.mjs

@@ -0,0 +1,533 @@
+#!/usr/bin/env node
+/**
+ * One command between a source change and a push.
+ *
+ * -- WHY THIS EXISTS --
+ *
+ * Adopting one dependency on 2026-09-18 took SIX pushes to land, and not one of
+ * them found a new defect. Each found the NEXT derived artifact:
+ *
+ *   push -> CI: the OpenAPI specs no longer describe the code
+ *   push -> CI: the generated clients no longer match those specs
+ *   push -> CI: the biome index ledgers no longer describe those clients
+ *   push -> CI: ... and the ledgers again, for the specs regenerated since
+ *
+ * That is not four bugs. It is ONE ordered chain, discovered one failure at a
+ * time because nothing ran it in order:
+ *
+ *   prisma  ->  build  ->  specs  ->  clients  ->  ledgers  ->  checks
+ *
+ * CI's job is to CONFIRM a state, not to teach the dependency graph. This runs
+ * the repository's OWN generators, in the order the graph actually has, so the
+ * chain converges before the push instead of across it.
+ *
+ * -- PRISMA COMES FIRST, AND THAT WAS LEARNED BY THIS FILE FAILING --
+ *
+ * A service typechecks against its GENERATED Prisma client, and that client is
+ * produced by `postinstall`. So it is current only as of the last install --
+ * which means a checkout that moves to a commit adding a schema column has a
+ * STALE client and no step regenerates it. Measured 2026-09-18: a column was
+ * present in `schema.prisma` and absent from the generated `index.d.ts`, and
+ * the build reported five errors of the form "Property 'x' does not exist",
+ * naming the SERVICE rather than the stale artifact behind it. That reads
+ * exactly like a defect in somebody's commit, and it is not.
+ *
+ * It is the same class as everything below it: a derived artifact with an
+ * upstream, discovered one failure at a time because nothing ran it in order.
+ *
+ * -- THE ORDER IS NOT A PREFERENCE, AND THE FIRST STEP IS THE ONE PEOPLE SKIP --
+ *
+ * `build` comes first because spec extraction BOOTS each service's Nest
+ * AppModule, and a module whose workspace dependencies are unbuilt fails with
+ * `MODULE_NOT_FOUND` on a sibling's generated client. Skipping it produces a
+ * FAKE cascade: regenerate the five services whose specs drifted, and the run
+ * fails on a sixth; regenerate that, and it fails on a seventh. Every one of
+ * those is the same unbuilt closure wearing a different service's name. One
+ * `pnpm -r build` first, and the cascade does not exist.
+ *
+ * The graph is ACYCLIC, so ONE correctly ordered pass converges. This
+ * deliberately does not loop. If a second pass would change anything, that is a
+ * violated dependency to find and fix, not a retry to institutionalise — so the
+ * final check step is what proves convergence, and a red one is a real finding.
+ *
+ * -- WHAT THIS IS NOT --
+ *
+ * It is not a release engine, a second source of truth, or a new authority over
+ * generated artifacts. Every step below shells out to a script this repository
+ * already owns and already runs in CI. If a step here disagrees with CI, CI is
+ * right and this file is wrong.
+ *
+ * It is also not a gate. It regenerates files, so it must never run inside
+ * `pnpm check`: a check that rewrites the tree it is grading cannot fail
+ * honestly.
+ */
+import { execFileSync } from 'node:child_process';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+
+// THE ROOT IS THE CONSUMER'S REPOSITORY, NEVER THIS PACKAGE'S LOCATION.
+// This ships as a bin from `@xemahq/repo-build-tooling`, so `import.meta.url`
+// resolves inside `node_modules` — deriving the root from it would grade the
+// SDK's own directory and find nothing, which is the empty-scan pass this
+// repository has shipped before. pnpm runs a `scripts` entry with cwd set to the
+// directory of the manifest declaring it, so for a root `readiness` script that
+// is exactly the repository root. It is asserted and PRINTED rather than assumed.
+const ROOT = process.cwd();
+if (!existsSync(path.join(ROOT, 'package.json'))) {
+  console.error(
+    `\nreadiness: REFUSING — no package.json at ${ROOT}.\n\n` +
+      'This must run from a repository root (`pnpm readiness`), because every\n' +
+      'step below is resolved relative to it. Grading the wrong tree silently is\n' +
+      'worse than refusing.\n',
+  );
+  process.exit(1);
+}
+const scripts = JSON.parse(readFileSync(path.join(ROOT, 'package.json'), 'utf8')).scripts ?? {};
+
+/**
+ * Is this checkout's INSTALL actually the one its lockfile describes?
+ *
+ * Everything below regenerates artifacts from whatever `node_modules` currently
+ * holds. If that disagrees with the lockfile, every spec, client and ledger this
+ * run produces is derived from the wrong bytes — and the resulting failure names
+ * the CONSUMER, never the stale artifact behind it.
+ *
+ * Measured FOUR times on 2026-09-18, each producing a confident wrong diagnosis
+ * that blamed somebody else's commit:
+ *
+ *   · `@xemahq/contracts` resolving to 0.7.0 out of a foreign scratchpad while
+ *     the fleet was on 0.13.0 — a `.strict()` schema then REFUSED a valid
+ *     contribution, which reads as the declaration being broken;
+ *   · a generated Prisma client missing a column its own schema declared;
+ *   · `@xemahq/xema-decorators` at 0.17.0 (`humanBaseline` in ZERO files)
+ *     against a lockfile saying 0.18.0, after a `--lockfile-only` relock;
+ *   · `@xemahq/biome-supply-chain` at 0.3.0 against a lockfile saying 0.4.0,
+ *     after a REBASE — `Cannot find module '.../verdicts'`, which reads exactly
+ *     like somebody importing an unpublished subpath. It was published.
+ *
+ * A RELOCK IS NOT AN ADOPTION. A REBASE IS NOT AN ADOPTION. Only an install is.
+ *
+ * One-directional on purpose: extra versions PRESENT in the store are ordinary
+ * pnpm residue. A version the lockfile NAMES and the store LACKS is the
+ * direction that misleads.
+ */
+function installBehindLockfile() {
+  const store = path.join(ROOT, 'node_modules', '.pnpm');
+  const lock = path.join(ROOT, 'pnpm-lock.yaml');
+  if (!existsSync(store) || !existsSync(lock)) return [];
+  const entries = readdirSync(store);
+  const missing = [];
+  const seen = new Set();
+  for (const [, name, version] of readFileSync(lock, 'utf8').matchAll(
+    /^\s{2}'?(@xemahq\/[a-z0-9-]+)@([0-9]+\.[0-9]+\.[0-9]+[^':(\s]*)'?:/gm,
+  )) {
+    const key = `${name}@${version}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    const dir = `${name.replace('/', '+')}@${version}`;
+    // A peer-suffixed directory is the SAME version, so presence is a prefix
+    // test. Exact matching would report every peer-resolved package as missing.
+    if (!existsSync(path.join(store, dir)) && !entries.some((e) => e.startsWith(`${dir}_`))) {
+      missing.push(key);
+    }
+  }
+  return missing;
+}
+
+/** A step is SKIPPED when this repository does not own that generator, never faked. */
+const STEPS = [
+  {
+    id: 'prisma',
+    why: 'the generated Prisma clients the services TYPECHECK against',
+    perService: 'prisma:generate',
+  },
+  {
+    id: 'build',
+    why: 'spec extraction boots each AppModule; an unbuilt closure fakes a cascade',
+    run: ['pnpm', '-r', 'build'],
+    always: true,
+  },
+  {
+    id: 'specs',
+    why: 'the extracted OpenAPI documents',
+    perService: 'openapi',
+    gate: 'check:openapi-spec-current',
+  },
+  {
+    id: 'clients',
+    why: 'the generated clients, which are derived FROM those specs',
+    perService: 'client:generate',
+    gate: 'check:client-spec-drift',
+  },
+  {
+    id: 'ledgers',
+    why: "each biome's integrity claim over its own bytes, specs and clients included",
+    // `--allow-dirty` is SAFE HERE AND ONLY HERE, because `run()` refuses to start
+    // on a dirty tree — so every modified file at this point is output THIS RUN
+    // produced. Without it the step is a no-op in exactly the case it exists for:
+    // the biomes it must re-hash are the ones the specs and clients just dirtied,
+    // so the deriver skips precisely those and exits 0.
+    run: ['node', 'tooling/codegen/derive-biome-index.mjs', '--allow-dirty'],
+    needs: 'derive:biome-index',
+    gate: 'check:biome-index-ledger',
+  },
+];
+
+/**
+ * Surface classifications a human already decided, with the evidence.
+ *
+ * The client generator REFUSES to guess whether a retained export whose
+ * declaration moved is widening or narrowing — correctly, because a generated
+ * client does not record whether a type is a REQUEST or a RESPONSE, and those
+ * have opposite version consequences. That refusal stays.
+ *
+ * What this removes is the REPETITION. Before it, the same investigation —
+ * `npm pack` the published client, diff the declaration, decide — was owed by
+ * every run and every session, for a fact somebody had already established.
+ *
+ * It is deliberately NOT a global bump class. An entry names ONE export, and it
+ * is applied only when every export the generator names is recorded. Anything
+ * unrecognised still stops and asks, which is what keeps this from becoming
+ * `XEMA_CLIENT_BUMP_CLASS` set once and forgotten.
+ */
+function recordedSurfaceDecisions() {
+  const file = path.join(ROOT, 'tooling/release/client-surface-decisions.json');
+  if (!existsSync(file)) return new Map();
+  try {
+    const parsed = JSON.parse(readFileSync(file, 'utf8'));
+    return new Map((parsed.decisions ?? []).map((d) => [d.export, d]));
+  } catch {
+    return new Map(); // an unreadable ledger must not silently grant anything
+  }
+}
+
+/** The exports a refusal names, e.g. `models/problemDetailsDto#ProblemDetailsDto`. */
+function exportsNamedByRefusal(output) {
+  const named = new Set();
+  for (const line of output.split('\n')) {
+    const m = line.match(/exports whose DECLARATION changed \(\d+\): (.+)$/);
+    if (m) for (const e of m[1].split(/[,\s]+/).filter(Boolean)) named.add(e.trim());
+  }
+  return [...named];
+}
+
+function sh(argv, { capture = false, env } = {}) {
+  return execFileSync(argv[0], argv.slice(1), {
+    cwd: ROOT,
+    encoding: 'utf8',
+    // `pipe` for stderr even when inheriting stdout: a generator REFUSAL has to be
+    // readable by the caller to be matched against a recorded decision, and an
+    // inherited stderr reaches the terminal and nothing else.
+    stdio: capture ? ['ignore', 'pipe', 'pipe'] : ['inherit', 'inherit', 'pipe'],
+    maxBuffer: 1 << 28,
+    ...(env ? { env } : {}),
+  });
+}
+
+/** Services this repository can extract, read from the workspace rather than listed. */
+function servicesWith(script) {
+  const out = sh(['pnpm', '-r', '--depth', '-1', 'list', '--json'], { capture: true });
+  let parsed;
+  try {
+    parsed = JSON.parse(out);
+  } catch {
+    return [];
+  }
+  const names = [];
+  for (const entry of Array.isArray(parsed) ? parsed : [parsed]) {
+    const manifest = path.join(entry.path ?? '', 'package.json');
+    if (!existsSync(manifest)) continue;
+    try {
+      const json = JSON.parse(readFileSync(manifest, 'utf8'));
+      if (json.scripts?.[script] && json.name) names.push(json.name);
+    } catch {
+      /* unreadable manifest is not a service */
+    }
+  }
+  return names;
+}
+
+/**
+ * The packages this working tree actually CHANGED, against the branch it will
+ * merge into.
+ *
+ * This exists because the chain above proves CONVERGENCE and nothing else.
+ * Measured 2026-09-19: `xema-base/develop` was red for four consecutive commits
+ * on `shell-published-capability-surface.spec.ts` — a declaration change whose
+ * only witness was a semantic test. `prisma`, `build`, `specs`, `clients`,
+ * `ledgers` and `pnpm check` are all GREEN on that tree, because none of them
+ * runs it. `typecheck green != tests green`, and readiness proved only the first.
+ *
+ * The set is derived from git rather than from a build-graph filter, because no
+ * repository in this fleet has a turbo affected-filter to copy (measured: zero
+ * `--filter=...[origin/...]` invocations fleet-wide) and inventing one here would
+ * be a second build authority. `git diff <merge-base>` needs no tooling, is the
+ * same question every reviewer asks, and includes UNCOMMITTED work — which is
+ * the whole point of a pre-push command.
+ */
+function changedPackages() {
+  let base;
+  for (const ref of ['origin/develop', 'origin/main']) {
+    try {
+      base = sh(['git', 'merge-base', 'HEAD', ref], { capture: true }).trim();
+      if (base) break;
+    } catch {
+      /* the ref is not fetched here; try the next one */
+    }
+  }
+  if (!base) return { base: undefined, paths: [], packages: [] };
+  const paths = sh(['git', 'diff', '--name-only', base, '--'], { capture: true })
+    .split('\n')
+    .map((l) => l.trim())
+    .filter(Boolean);
+
+  return { base, paths, packages: packagesOwningPaths(ROOT, paths) };
+}
+
+/**
+ * The workspace packages owning these repo-relative paths, by walking UP to the
+ * nearest `package.json`. Pure over the filesystem, so it is the half that is
+ * tested directly.
+ *
+ * Two rules, both deliberate:
+ *   - the ROOT manifest never owns anything. It is not a workspace member, and
+ *     its `test` script is usually `turbo run test` — the whole fleet, which is
+ *     the opposite of affected.
+ *   - a package with no `test` script owns nothing, so it is absent from the set
+ *     rather than present-and-skipped. A skipped member inflates the corpus line
+ *     and makes "0 ran" look like "all passed".
+ */
+export function packagesOwningPaths(root, relPaths) {
+  // CONTAINMENT IS A PATH QUESTION, NEVER A STRING PREFIX. `dir.startsWith(root)`
+  // admits a SIBLING whose name merely begins with the same characters — for
+  // root `/x/repo`, the path `/x/repo-legacy/pkg` passes — and this fleet keeps
+  // sibling repositories one directory apart, so a climbing path would have
+  // scheduled a NEIGHBOURING repository's test suite. Found by a mutation test
+  // whose escaping path was made to reach a real manifest.
+  const contains = (dir) => {
+    const rel = path.relative(root, dir);
+    return rel !== '' && !rel.startsWith('..') && !path.isAbsolute(rel);
+  };
+  const owners = new Set();
+  for (const rel of relPaths) {
+    let dir = path.dirname(path.resolve(root, rel));
+    while (contains(dir)) {
+      const manifest = path.join(dir, 'package.json');
+      if (dir !== root && existsSync(manifest)) {
+        try {
+          const json = JSON.parse(readFileSync(manifest, 'utf8'));
+          if (json.name && json.scripts?.test) owners.add(json.name);
+        } catch {
+          /* an unreadable manifest owns nothing */
+        }
+        break;
+      }
+      const parent = path.dirname(dir);
+      if (parent === dir) break;
+      dir = parent;
+    }
+  }
+  return [...owners].sort();
+}
+
+/**
+ * Run the changed packages' own suites. NOT their dependents': this is the
+ * pre-push loop, and the dependent closure in this fleet reaches 144 packages —
+ * CI owns that question. What this owns is "the thing I just edited still
+ * passes its own tests", which is the one that was missing.
+ */
+function runAffectedTests() {
+  console.log('\n=== tests — the affected packages\' own suites ===');
+  const { base, paths, packages } = changedPackages();
+  if (!base) {
+    console.log(
+      '  SKIPPED — neither origin/develop nor origin/main is fetched here, so\n' +
+        '  there is no branch point to diff against. Fetch, or run the suites by hand.',
+    );
+    return;
+  }
+  // The CORPUS, printed: a verdict with no denominator cannot be graded in
+  // either direction, and "0 tests ran" and "0 tests failed" look identical.
+  console.log(
+    `  ${paths.length} changed path(s) since ${base.slice(0, 9)} -> ` +
+      `${packages.length} package(s) with a test script`,
+  );
+  if (packages.length === 0) {
+    console.log(
+      '  nothing to run — the changed paths belong to no workspace package with\n' +
+        '  a test script (a workflow, a root document, generated output).',
+    );
+    return;
+  }
+  for (const name of packages) console.log(`    - ${name}`);
+  for (const name of packages) {
+    // One at a time, so a failure NAMES the package; a single multi-filter
+    // invocation reports only the first.
+    sh(['pnpm', '--filter', name, 'test']);
+  }
+}
+
+function run() {
+  // ── WHAT `--allow-dirty` INCLUDES, STATED RATHER THAN ASSUMED ─────────────
+  // This regenerates derived artifacts and hashes them into biome ledgers, and a
+  // ledger hashes the WORKING TREE. So anything already modified when this starts
+  // is hashed in too.
+  //
+  // That is USUALLY exactly right — a developer regenerating alongside the edits
+  // they are about to commit is the case `--allow-dirty` was written for, and
+  // refusing it would break the one workflow this command exists to serve:
+  // change -> readiness -> push.
+  //
+  // It is wrong in ONE situation: a SHARED checkout where the modified files are
+  // somebody else's. That cannot be detected from here, so it is REPORTED rather
+  // than guessed at. A reader who sees a path they did not touch has the one fact
+  // they need; a refusal would have cost everyone else the workflow.
+  // PROVENANCE FIRST. Unlike a dirty tree, an install behind its own lockfile is
+  // never the intent — there is no workflow it serves, so this REFUSES rather
+  // than reporting. The remedy is one command and it is printed.
+  const behind = installBehindLockfile();
+  if (behind.length > 0) {
+    console.error(
+      `\nreadiness: REFUSING — this install is BEHIND its own lockfile.\n\n` +
+        `${behind.length} version(s) the lockfile records are NOT in the store:\n` +
+        behind.slice(0, 10).map((m) => `      ${m}`).join('\n') +
+        (behind.length > 10 ? `\n      ... and ${behind.length - 10} more` : '') +
+        '\n\nEverything this command regenerates would be derived from the WRONG\n' +
+        'bytes, and the failure would name whichever file imports them rather\n' +
+        'than the stale package behind it.\n\n' +
+        '  Remedy:  pnpm install --frozen-lockfile\n',
+    );
+    return 1;
+  }
+
+  const preexisting = sh(['git', 'status', '--porcelain'], { capture: true })
+    .trim()
+    .split('\n')
+    .filter(Boolean);
+  if (preexisting.length > 0) {
+    console.log(
+      `readiness: ${preexisting.length} path(s) already modified — these are hashed into\n` +
+        'any biome ledger they belong to. Every one of them should be YOURS:\n' +
+        preexisting.slice(0, 10).map((l) => `      ${l}`).join('\n') +
+        (preexisting.length > 10 ? `\n      ... and ${preexisting.length - 10} more` : '') +
+        '\n',
+    );
+  }
+
+  const only = process.argv.find((a) => a.startsWith('--only='))?.slice('--only='.length);
+  console.log(`readiness: ${path.basename(ROOT)} — prisma -> build -> specs -> clients -> ledgers -> checks\n`);
+
+  for (const step of STEPS) {
+    if (only && only !== step.id) continue;
+    if (step.needs && !scripts[step.needs]) {
+      console.log(`  - ${step.id}: SKIPPED — this repository has no \`${step.needs}\``);
+      continue;
+    }
+    console.log(`\n=== ${step.id} — ${step.why} ===`);
+    if (step.run) {
+      sh(step.run);
+      continue;
+    }
+    const services = servicesWith(step.perService);
+    if (services.length === 0) {
+      console.log(`  - no package declares \`${step.perService}\`; nothing to regenerate`);
+      continue;
+    }
+    console.log(`  ${services.length} package(s) declare \`${step.perService}\``);
+    const decided = step.id === 'clients' ? recordedSurfaceDecisions() : new Map();
+    for (const name of services) {
+      // One at a time on purpose: a failure must name the service, and a single
+      // `--filter a --filter b` invocation reports only the first.
+      try {
+        sh(['pnpm', '--filter', name, step.perService]);
+      } catch (error) {
+        const output = `${error?.stdout ?? ''}${error?.stderr ?? ''}${error?.message ?? ''}`;
+        const named = exportsNamedByRefusal(output);
+        if (named.length === 0) {
+          // stderr is PIPED so a refusal can be matched; an ordinary failure must
+          // not lose its diagnostics to that. Print what was captured before
+          // rethrowing, or the reader gets one line of `Command failed`.
+          if (output.trim()) console.error(output);
+          throw error;
+        }
+
+        const unrecorded = named.filter((e) => !decided.has(e));
+        if (unrecorded.length > 0) {
+          console.error(
+            `\n  ${name}: the generator cannot classify ${unrecorded.length} export(s), ` +
+              'and no recorded decision covers them:\n' +
+              unrecorded.map((e) => `      ${e}`).join('\n') +
+              '\n\n  This needs a HUMAN, and the generator is right to ask. Decide it from the' +
+              '\n  PUBLISHED tarball of the current version, never from this tree:' +
+              `\n      npm pack <client>@<published>  and diff the declaration.` +
+              '\n  Then record it in tooling/release/client-surface-decisions.json with the' +
+              '\n  evidence, so nobody has to establish it again.\n',
+          );
+          throw error;
+        }
+
+        const classes = [...new Set(named.map((e) => decided.get(e).class))];
+        if (classes.length !== 1) {
+          console.error(
+            `\n  ${name}: recorded decisions disagree (${classes.join(', ')}). ` +
+              'Refusing to pick one.\n',
+          );
+          throw error;
+        }
+
+        // Not a retry loop: ONE re-run, driven by recorded data rather than by hope,
+        // for a refusal whose every subject is already decided.
+        console.log(
+          `  ${name}: applying recorded classification ${classes[0]} for ` +
+            `${named.join(', ')}`,
+        );
+        sh(['pnpm', '--filter', name, step.perService], {
+          env: { ...process.env, XEMA_CLIENT_BUMP_CLASS: classes[0] },
+        });
+      }
+    }
+  }
+
+  if (only) {
+    console.log(`\nreadiness: ran --only=${only}. Run without it before pushing.`);
+    return 0;
+  }
+
+  console.log('\n=== checks — the proof that the chain CONVERGED ===');
+  // A second pass must not be needed. If a gate here is red, a dependency was
+  // violated; find it rather than re-running this command.
+  sh(['pnpm', 'check']);
+  for (const gate of STEPS.map((s) => s.gate).filter(Boolean)) {
+    if (scripts[gate]) sh(['pnpm', gate]);
+  }
+
+  runAffectedTests();
+
+  console.log(
+    '\nreadiness: converged. Every derived artifact describes the source beside it,\n' +
+      'and the repository\'s own checks agree. Safe to push.',
+  );
+  return 0;
+}
+
+// Executed as a bin, imported by its test. `process.argv[1]` is this file only
+// when node was asked to RUN it — an import leaves it pointing at the test.
+const INVOKED_DIRECTLY =
+  process.argv[1] !== undefined &&
+  path.resolve(process.argv[1]) === path.resolve(new URL(import.meta.url).pathname);
+
+try {
+  if (!INVOKED_DIRECTLY) {
+    // imported for its exports; nothing to do
+  } else process.exit(run());
+} catch (error) {
+  console.error(
+    `\nreadiness: FAILED at the step above. That is the ROOT cause — the steps after it\n` +
+      'were not reached, so do not read their absence as a second failure.\n' +
+      `\n  ${error?.message?.split('\n')[0] ?? error}\n` +
+      '\nIf a CHECK failed rather than a generator, a dependency in\n' +
+      'prisma -> build -> specs -> clients -> ledgers was violated. Find it; do not re-run.\n',
+  );
+  process.exit(1);
+}

package/src/readiness.test.mjs

@@ -0,0 +1,129 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import test from 'node:test';
+
+import { packagesOwningPaths } from './readiness.mjs';
+
+/** A throwaway workspace: root + four members with different shapes. */
+async function fixture() {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), 'xema-readiness-'));
+  const write = async (rel, json) => {
+    await fs.mkdir(path.join(root, path.dirname(rel)), { recursive: true });
+    await fs.writeFile(path.join(root, rel), json, 'utf8');
+  };
+  // The ROOT manifest declares a test script ON PURPOSE: it must still own nothing.
+  await write('package.json', JSON.stringify({ name: 'root', scripts: { test: 'turbo run test' } }));
+  await write('packages/tested/package.json', JSON.stringify({ name: '@t/tested', scripts: { test: 'jest' } }));
+  await write('packages/untested/package.json', JSON.stringify({ name: '@t/untested', scripts: { build: 'tsc' } }));
+  await write('packages/outer/package.json', JSON.stringify({ name: '@t/outer', scripts: { test: 'jest' } }));
+  await write('packages/outer/nested/package.json', JSON.stringify({ name: '@t/nested', scripts: { test: 'jest' } }));
+  await write('packages/broken/package.json', '{ this is not json');
+  return root;
+}
+
+test('a changed file maps to the package that owns it', async () => {
+  const root = await fixture();
+  try {
+    assert.deepEqual(
+      packagesOwningPaths(root, ['packages/tested/src/a.ts']),
+      ['@t/tested'],
+    );
+    // Two files in one package are ONE entry — the corpus line must not
+    // double-count, or "3 packages" would run one suite three times.
+    assert.deepEqual(
+      packagesOwningPaths(root, ['packages/tested/src/a.ts', 'packages/tested/src/b.ts']),
+      ['@t/tested'],
+    );
+  } finally {
+    await fs.rm(root, { recursive: true, force: true });
+  }
+});
+
+test('a package with no test script owns nothing — absent, never present-and-skipped', async () => {
+  const root = await fixture();
+  try {
+    // Present-and-skipped would inflate the corpus line, and "0 ran" would then
+    // look exactly like "all passed".
+    assert.deepEqual(packagesOwningPaths(root, ['packages/untested/src/a.ts']), []);
+    assert.deepEqual(
+      packagesOwningPaths(root, ['packages/untested/src/a.ts', 'packages/tested/src/a.ts']),
+      ['@t/tested'],
+    );
+  } finally {
+    await fs.rm(root, { recursive: true, force: true });
+  }
+});
+
+test('the ROOT manifest never owns anything, even declaring a test script', async () => {
+  const root = await fixture();
+  try {
+    // The fixture root declares `test: turbo run test` — the WHOLE fleet, which
+    // is the opposite of affected. Owning from the root would run everything on
+    // a README edit.
+    assert.deepEqual(packagesOwningPaths(root, ['README.md']), []);
+    assert.deepEqual(packagesOwningPaths(root, ['.github/workflows/ci.yaml']), []);
+  } finally {
+    await fs.rm(root, { recursive: true, force: true });
+  }
+});
+
+test('the NEAREST package wins, not an ancestor that also has a manifest', async () => {
+  const root = await fixture();
+  try {
+    assert.deepEqual(
+      packagesOwningPaths(root, ['packages/outer/nested/src/a.ts']),
+      ['@t/nested'],
+    );
+    assert.deepEqual(
+      packagesOwningPaths(root, ['packages/outer/src/a.ts']),
+      ['@t/outer'],
+    );
+  } finally {
+    await fs.rm(root, { recursive: true, force: true });
+  }
+});
+
+test('an unreadable manifest owns nothing and does not throw', async () => {
+  const root = await fixture();
+  try {
+    // A parse error here would abort the whole readiness run over one bad file.
+    assert.deepEqual(packagesOwningPaths(root, ['packages/broken/src/a.ts']), []);
+    // ...and it must not swallow its NEIGHBOURS.
+    assert.deepEqual(
+      packagesOwningPaths(root, ['packages/broken/src/a.ts', 'packages/tested/src/a.ts']),
+      ['@t/tested'],
+    );
+  } finally {
+    await fs.rm(root, { recursive: true, force: true });
+  }
+});
+
+test('a path escaping the root owns nothing, even reaching a REAL sibling manifest', async () => {
+  const root = await fixture();
+  // The hazard is concrete, not theoretical: in the aggregator,
+  // `repos/xema-base/../xema-community/package.json` exists. A climbing path
+  // must not reach a NEIGHBOURING repository's package and schedule its tests.
+  const sibling = path.join(path.dirname(root), `${path.basename(root)}-sibling`);
+  await fs.mkdir(path.join(sibling, 'packages/foreign'), { recursive: true });
+  await fs.writeFile(
+    path.join(sibling, 'packages/foreign/package.json'),
+    JSON.stringify({ name: '@other/foreign', scripts: { test: 'jest' } }),
+    'utf8',
+  );
+  try {
+    const escaping = path.join('..', path.basename(sibling), 'packages/foreign/src/a.ts');
+    // Control: that manifest IS reachable when the sibling is the root, so the
+    // empty result below is the ROOT BOUND working, not a path that resolves
+    // to nothing.
+    assert.deepEqual(
+      packagesOwningPaths(sibling, ['packages/foreign/src/a.ts']),
+      ['@other/foreign'],
+    );
+    assert.deepEqual(packagesOwningPaths(root, [escaping]), []);
+  } finally {
+    await fs.rm(root, { recursive: true, force: true });
+    await fs.rm(sibling, { recursive: true, force: true });
+  }
+});

package/src/scrub-swagger-plugin-paths.mjs

@@ -438,6 +438,83 @@ async function* walk(dir) {
   }
 }
 
+// ── WHERE THE PLUGIN'S REQUIRES LIVE, AND WHY THAT IS THE WHOLE SCOPE ────────
+//
+// This file's own header states the scope: "Post-build sanitizer for
+// @nestjs/swagger plugin v11.x output", and "the swagger CLI plugin emits
+// `_OPENAPI_METADATA_FACTORY()` blocks that contain `require("<path>")` calls".
+// Every leak it exists to repair is therefore INSIDE such a block.
+//
+// Shape 2 did not honour that. It rewrote `require("@xemahq/<pkg>/dist/<rest>")`
+// ANYWHERE in the emitted file, on the assumption recorded above — "every
+// package they have ever matched exposes a root export". That assumption is
+// measurably false today, and a HAND-WRITTEN deep import compiles to exactly
+// the shape the regex matches, so it was rewritten too:
+//
+//     src:   import { RealmTokenVerifier }
+//              from '@xemahq/platform-common/dist/nestjs/auth/realm-token-verifier';
+//     dist:  const realm_token_verifier_1 = require("@xemahq/platform-common");
+//
+// The module loads, the binding is not on the root barrel, and the service dies
+// at DI time with "RealmTokenVerifier is not a constructor". That is what took
+// xema-shell-api's rollout down on 2026-09-17 — and every check was green,
+// because typecheck, jest and the pre-push gate all read the SOURCE, and
+// nothing executes the rewritten dist before the pod does.
+//
+// Measured across the four packages shape 2 matches in shipped source, asking
+// each published tarball whether its ROOT entry exports the symbol:
+//
+//     @xemahq/platform-common    RealmTokenVerifier              NOT on root
+//     @xemahq/biome-supply-chain CosignErrorCode                 NOT on root
+//     @xemahq/xema-service-nest  buildResourcePath               NOT on root
+//     @xemahq/biome-database-nest assertMigrationHistoryCompatible NOT on root
+//
+// so the blind rewrite was wrong for all four. (Only two reach a shipped dist:
+// xema-shell-api, which fired, and biome-host-api, which is armed on the
+// bundle-fetch ERROR path. The other nine occurrences are in tests, which run
+// from TypeScript and never see this rewriter.)
+//
+// The fix is a SCOPE correction, not more proof machinery: rewrite only what
+// the plugin emitted, and REFUSE anything else. `reExportsReach` cannot stand
+// in for this — it proves a module is REACHED, not that a BINDING is
+// re-exported, and `nestjs/index.js` requires `./auth` while re-exporting only
+// some of its names, so it would have called the bad rewrite provable.
+//
+// A refusal here is the whole point: it converts a production CrashLoopBackOff
+// into a build failure in the repository that wrote the import.
+function openApiFactoryRanges(src) {
+  const ranges = [];
+  const token = '_OPENAPI_METADATA_FACTORY';
+  let from = 0;
+  for (;;) {
+    const hit = src.indexOf(token, from);
+    if (hit === -1) break;
+    from = hit + token.length;
+    const open = src.indexOf('{', from);
+    if (open === -1) break;
+    // Brace-match. String and comment bodies inside a metadata factory are
+    // emitted by tsc and contain no unbalanced braces in practice; a miscount
+    // can only ever END the range early, which fails CLOSED (the require is
+    // then treated as hand-written and refused) rather than widening the
+    // rewrite to code the plugin did not emit.
+    let depth = 0;
+    let i = open;
+    for (; i < src.length; i += 1) {
+      if (src[i] === '{') depth += 1;
+      else if (src[i] === '}') {
+        depth -= 1;
+        if (depth === 0) break;
+      }
+    }
+    ranges.push([open, Math.min(i + 1, src.length)]);
+    from = i + 1;
+  }
+  return ranges;
+}
+
+const inAnyRange = (ranges, offset) =>
+  ranges.some(([start, end]) => offset >= start && offset < end);
+
 async function scrubFile(path) {
   const src = await readFile(path, 'utf8');
   let count = 0;
@@ -455,10 +532,35 @@ async function scrubFile(path) {
     count += 1;
     return `require("${kept}")`;
   });
-  out = out.replace(FLAT_LEAK_REGEX, (_match, pkg) => {
+  // Shape 2 is scoped to the plugin's own emits. Anything else matching this
+  // shape is a hand-written deep import, and rewriting it silently changes
+  // which module the service loads — see the note above `openApiFactoryRanges`.
+  const factoryRanges = openApiFactoryRanges(out);
+  const handWritten = [];
+  out = out.replace(FLAT_LEAK_REGEX, (match, pkg, offset) => {
+    if (!inAnyRange(factoryRanges, offset)) {
+      handWritten.push(match.slice('require("'.length, -2));
+      return match;
+    }
     count += 1;
     return `require("${pkg}")`;
   });
+  if (handWritten.length > 0) {
+    throw new ScrubFailure(
+      `${path}\n` +
+        `  ${handWritten.length} hand-written deep import(s) into a package's dist/:\n` +
+        handWritten.map((spec) => `    ${spec}`).join('\n') +
+        `\n\n  These are NOT swagger-plugin emits — they are outside every\n` +
+        `  _OPENAPI_METADATA_FACTORY block, so this rewriter is not entitled to\n` +
+        `  touch them. Rewriting one to the bare package specifier (which is what\n` +
+        `  this step used to do, silently) loads the package root instead, and any\n` +
+        `  binding the root barrel does not re-export becomes \`undefined\` at\n` +
+        `  runtime — a DI crash in the pod, with every build check green.\n\n` +
+        `  Fix the IMPORT, in source: use the package's public surface. If the\n` +
+        `  symbol is not on it, the package is missing an export — add it there\n` +
+        `  rather than reaching through dist/.`,
+    );
+  }
   out = out.replace(RELATIVE_WORKSPACE_REGEX, (_match, pkgName, subpath) => {
     count += 1;
     return `require("@xemahq/${pkgName}/${subpath}")`;
@@ -637,16 +739,57 @@ async function selfTest() {
     const green = join(root, 'green');
     await mkdir(green, { recursive: true });
     const greenFile = join(green, 'dto.js');
-    await writeFile(greenFile, `${samples[0][1]};\n`, 'utf8');
+    // The plugin emits its requires INSIDE `_OPENAPI_METADATA_FACTORY`, so the
+    // green fixture has to as well — a bare literal at top level is a
+    // HAND-WRITTEN import and is now refused, which is the point of the scope.
+    await writeFile(
+      greenFile,
+      `class Dto {\n  static _OPENAPI_METADATA_FACTORY() {\n    return { x: { required: true, type: () => ${samples[0][1]} } };\n  }\n}\n`,
+      'utf8',
+    );
     const greenResult = await run([green]);
     if (greenResult.totalRewrites < 1) {
       throw new Error(`self-test: expected at least 1 rewrite, got ${greenResult.totalRewrites}`);
     }
+    // THE CASE THAT PINS THE SCOPE, both polarities in one fixture.
+    //
+    // Same package, same deep path, twice: once as the plugin emits it (inside
+    // `_OPENAPI_METADATA_FACTORY`) and once as tsc emits a hand-written
+    // `import ... from '@xemahq/<pkg>/dist/...'` (a top-level const). The
+    // rewriter must take the first and REFUSE the whole file for the second.
+    //
+    // Without this the fix is unpinned: the old blind pass rewrote both, and
+    // that is what put `require("@xemahq/platform-common")` into
+    // xema-shell-api's dist and crashlooped it in production with every build
+    // check green.
+    const mixed = join(root, 'mixed');
+    await mkdir(mixed, { recursive: true });
+    await writeFile(
+      join(mixed, 'dto.js'),
+      'const realm_token_verifier_1 = require("@xemahq/platform-common/dist/nestjs/auth/realm-token-verifier");\n' +
+        'class Dto {\n  static _OPENAPI_METADATA_FACTORY() {\n' +
+        '    return { x: { type: () => require("@xemahq/capability-contracts/dist/lib/capability-grant") } };\n  }\n}\n',
+      'utf8',
+    );
+    const refusal = await expectFailure('hand-written deep dist import', () => run([mixed]));
+    if (!refusal.message.includes('realm-token-verifier')) {
+      throw new Error(
+        `self-test: the refusal must NAME the offending specifier; got: ${refusal.message}`,
+      );
+    }
+    // And it must refuse the HAND-WRITTEN one, not the plugin's — if the scope
+    // check were inverted this assertion is what catches it.
+    if (refusal.message.includes('capability-grant')) {
+      throw new Error(
+        'self-test: the plugin-emitted require inside the factory was reported as hand-written — the scope test is inverted.',
+      );
+    }
+
     const greenAfter = await readFile(greenFile, 'utf8');
     // The NESTED pass unwraps to `@xemahq/subject-contracts/dist/lib/x`, which
     // the FLAT pass then reduces to the bare specifier — the two passes chain,
     // and the verification proves the chain terminated clean.
-    if (greenAfter.trim() !== 'require("@xemahq/subject-contracts");') {
+    if (!greenAfter.includes('require("@xemahq/subject-contracts")')) {
       throw new Error(`self-test: unexpected rewrite result: ${greenAfter.trim()}`);
     }
     if (findLeaks(greenAfter).length !== 0) {