@xemahq/repo-build-tooling 0.5.0 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xemahq/repo-build-tooling",
-  "version": "0.5.0",
+  "version": "0.7.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/readiness.mjs

@@ -0,0 +1,623 @@
+#!/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, realpathSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+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 REQUIRED here: without it the step is a no-op in exactly
+    // the case it exists for, because the biomes it must re-hash are the ones the
+    // specs and clients just dirtied, so the deriver skips precisely those and
+    // exits 0 — a green command over a skipped corpus.
+    //
+    // WHAT IT DOES NOT MEAN, corrected 2026-09-19. This said "SAFE HERE AND ONLY
+    // HERE, because `run()` refuses to start on a dirty tree". `run()` does no
+    // such thing: it REPORTS pre-existing modified paths and continues, and its
+    // only refusal is for an install behind its own lockfile. The claim made this
+    // authority internally contradictory with its own `run()` forty lines down,
+    // and it was the load-bearing half — it is the reason the flag reads as safe,
+    // so a reader who checked it would have stopped there.
+    //
+    // The honest statement is narrower. A ledger hashes the WORKING TREE, so
+    // anything already modified when this starts is hashed in too. For the
+    // workflow this serves — regenerating alongside edits you are about to commit
+    // — that is correct, and refusing would break the one loop the command exists
+    // for. In a SHARED checkout holding somebody else's modifications it IS a
+    // waived check, which is why `run()` prints those paths and asks the reader
+    // whether all of them are theirs.
+    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 };
+}
+
+/**
+ * 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 script is usually `turbo run <x>` — the whole fleet, which is the
+ *     opposite of affected. The root is handled separately, as a FALLBACK.
+ *   - a package not declaring THIS script owns nothing for this stage, 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, script = 'test') {
+  // 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');
+      // No `dir !== root` guard: `contains()` already excludes it, because
+      // `path.relative(root, root)` is the empty string. A mutation restoring
+      // that guard changed no behaviour, which is what identified it as inert
+      // rather than as an untested branch.
+      if (existsSync(manifest)) {
+        try {
+          const json = JSON.parse(readFileSync(manifest, 'utf8'));
+          if (json.name && json.scripts?.[script]) 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.
+ */
+/**
+ * Run ONE affected stage — the changed packages' own `<script>`.
+ *
+ * THREE STAGES, NOT ONE, because they are ORTHOGONAL PROOFS and this command is
+ * the only place that owns the ordering:
+ *
+ *   tests green      != typecheck green   (a suite can compile nothing)
+ *   typecheck green  != tests green       (compiling proves no behaviour)
+ *   either green     != lint green
+ *
+ * They run AFTER the generators, not before, and that order is not a preference:
+ * a service typechecks against its GENERATED client, so typechecking before
+ * `clients` grades a stale artifact and reports the CONSUMER — the same fake
+ * cascade the header above describes for spec extraction.
+ *
+ * Dependents are deliberately excluded: that closure reaches 144 packages in the
+ * largest repository here, and CI owns it. What this owns is "the thing I just
+ * edited still passes its own proofs".
+ */
+function runAffectedStage({ id, script, why }) {
+  console.log(`\n=== ${id} — ${why} ===`);
+  const { base, paths } = 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 this by hand.',
+    );
+    return;
+  }
+  const packages = packagesOwningPaths(ROOT, paths, script);
+  // The CORPUS, printed with BOTH counts: "0 ran" and "0 failed" look identical
+  // otherwise, and a green command over an empty scan is not proof.
+  console.log(
+    `  ${paths.length} changed path(s) since ${base.slice(0, 9)} -> ` +
+      `${packages.length} package(s) declaring \`${script}\``,
+  );
+  if (packages.length > 0) {
+    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, script]);
+    }
+    return;
+  }
+  // FALLBACK, and it is the difference between "inapplicable" and "not checked".
+  // Some repositories own a stage only at the root — `lint: eslint .` covers
+  // every package without any of them declaring `lint`. Skipping there would
+  // silently drop a real proof, so the root script runs, LABELLED as repo-wide
+  // rather than affected, so nobody reads it as an affected result.
+  if (paths.length > 0 && scripts[script]) {
+    console.log(
+      `  no changed package declares \`${script}\`, but the ROOT does — running it\n` +
+        '  REPO-WIDE. This is applicable-but-not-affected, and is reported as such.',
+    );
+    sh(['pnpm', 'run', script]);
+    return;
+  }
+  console.log(
+    `  nothing to run — no changed package declares \`${script}\` and the root\n` +
+      '  declares none either, so this stage is genuinely inapplicable here.',
+  );
+}
+
+
+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]);
+  }
+
+  for (const stage of [
+    { id: 'typecheck', script: 'typecheck', why: 'the compiler, which a passing suite does not imply' },
+    { id: 'lint', script: 'lint', why: 'the rules neither the compiler nor a suite enforces' },
+    { id: 'tests', script: 'test', why: "the affected packages' own suites" },
+  ]) {
+    runAffectedStage(stage);
+  }
+
+  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;
+}
+
+/**
+ * Was this module RUN, or merely imported (by its own test)?
+ *
+ * BOTH SIDES ARE REALPATH'D, and that is the whole correctness of it. pnpm's
+ * isolated linker puts the package at `node_modules/.pnpm/<pkg>@<ver>/...` and
+ * symlinks `node_modules/@scope/<pkg>` to it, so `process.argv[1]` and
+ * `import.meta.url` can name the SAME FILE by two different paths. Comparing
+ * them unresolved gives an answer that depends on HOW THE PACKAGE WAS LINKED —
+ * true through pnpm's bin shim, which invokes the realpath, and false when the
+ * symlinked path is invoked. A predicate whose answer depends on the linker is
+ * not a predicate.
+ *
+ * The failure mode is the one this whole tool exists to prevent: a false answer
+ * takes the import branch, `run()` is never called, and the process exits 0 —
+ * a chain reporting success without running. Caught by a peer, not by me, and
+ * not by any test, which is why `invokedDirectly` is exported and asserted
+ * below against a REAL symlink.
+ *
+ * `fileURLToPath` rather than `new URL(...).pathname`: the latter is not the
+ * documented conversion and is wrong independently of the symlink — it breaks on
+ * a Windows drive letter and on any percent-encoded character, and a single
+ * SPACE in a checkout path is enough to produce one.
+ */
+export function invokedDirectly(argv1, metaUrl) {
+  if (argv1 === undefined) return false;
+  try {
+    return realpathSync(argv1) === realpathSync(fileURLToPath(metaUrl));
+  } catch {
+    // An unresolvable path cannot be this module; never guess YES, because a
+    // wrong YES runs the chain from a context that did not ask for it.
+    return false;
+  }
+}
+
+const INVOKED_DIRECTLY = invokedDirectly(process.argv[1], import.meta.url);
+
+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,202 @@
+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 { invokedDirectly, 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');
+  // Declares typecheck+lint but NOT test — the orthogonal-proof case.
+  await write('packages/compiled/package.json', JSON.stringify({ name: '@t/compiled', scripts: { typecheck: 'tsc --noEmit', lint: 'eslint .' } }));
+  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 });
+  }
+});
+
+test('the owning scan is keyed on the SCRIPT, so the three stages see different sets', async () => {
+  const root = await fixture();
+  try {
+    const changed = ['packages/compiled/src/a.ts', 'packages/tested/src/a.ts'];
+    // `tests green != typecheck green` is not a slogan here — the two stages
+    // genuinely grade different packages, and a single set would silently run
+    // one package's suite and call the other proven.
+    assert.deepEqual(packagesOwningPaths(root, changed, 'test'), ['@t/tested']);
+    assert.deepEqual(packagesOwningPaths(root, changed, 'typecheck'), ['@t/compiled']);
+    assert.deepEqual(packagesOwningPaths(root, changed, 'lint'), ['@t/compiled']);
+    // Default stays `test`, so the original call shape is unchanged.
+    assert.deepEqual(packagesOwningPaths(root, changed), ['@t/tested']);
+  } finally {
+    await fs.rm(root, { recursive: true, force: true });
+  }
+});
+
+test('a script no package declares yields an EMPTY set, never the root', async () => {
+  const root = await fixture();
+  try {
+    // The root fixture declares `test`; asking for a script nothing declares must
+    // not fall back to it inside this function. The root FALLBACK is a decision
+    // made by the caller, which labels it repo-wide — folding it in here would
+    // report a repo-wide run as an affected one.
+    assert.deepEqual(packagesOwningPaths(root, ['packages/tested/src/a.ts'], 'nonexistent'), []);
+  } finally {
+    await fs.rm(root, { recursive: true, force: true });
+  }
+});
+
+/**
+ * The guard that decides whether this module RUNS. It had no test, and it was
+ * wrong: it compared `process.argv[1]` against `new URL(import.meta.url).pathname`
+ * UNRESOLVED, so under pnpm's isolated linker — which symlinks
+ * `node_modules/@scope/<pkg>` at `node_modules/.pnpm/<pkg>@<ver>/...` — the same
+ * file compared unequal whenever the symlinked path was the one invoked. The
+ * branch taken then does nothing and the process exits 0: a chain reporting
+ * success without running, which is the exact defect this tool exists to prevent.
+ */
+test('the run guard sees through a SYMLINK — pnpm links every package this way', async () => {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), 'xema-guard-'));
+  try {
+    const real = path.join(root, 'real', 'readiness.mjs');
+    await fs.mkdir(path.dirname(real), { recursive: true });
+    await fs.writeFile(real, '// module\n', 'utf8');
+    const link = path.join(root, 'linked.mjs');
+    await fs.symlink(real, link);
+
+    const url = `file://${real}`;
+    // THE CASE THAT FAILED: invoked by the symlink, module loaded from the
+    // realpath. Unresolved string comparison says false; the answer is true.
+    assert.equal(invokedDirectly(link, url), true);
+    // And the plain case still holds.
+    assert.equal(invokedDirectly(real, url), true);
+
+    // A DIFFERENT file must stay false, or the guard would run the chain from
+    // any import — the opposite failure, and the louder one.
+    const other = path.join(root, 'other.mjs');
+    await fs.writeFile(other, '// not it\n', 'utf8');
+    assert.equal(invokedDirectly(other, url), false);
+
+    // No argv[1] at all (`node --eval`) is an import, never a run.
+    assert.equal(invokedDirectly(undefined, url), false);
+    // An unresolvable path must answer NO rather than throw: a wrong YES runs
+    // the whole chain from a context that never asked for it.
+    assert.equal(invokedDirectly(path.join(root, 'gone.mjs'), url), false);
+  } finally {
+    await fs.rm(root, { recursive: true, force: true });
+  }
+});