@xemahq/xema 0.26.0 → 0.28.0

package/edition/platform-lock-readability.mjs

@@ -0,0 +1,892 @@
+#!/usr/bin/env node
+// INVOKER: `seal-image-digests.mjs`, before it writes a single digest.
+//
+// ── THE ASSERTION THAT WAS MISSING ──────────────────────────────────────────
+//
+// An edition's sealed lock must be PARSEABLE BY THE CONTRACTS VERSION THE
+// IMAGES OF THAT EDITION ACTUALLY RESOLVE. Nothing asserted that, and on
+// 2026-09-17 the gap took out three presenca-dev services at once:
+//
+//     Invalid distribution.lock.json: [biomes.87.source] Unrecognized key:
+//     "imageNamePrefix"
+//       at parseDistributionLock (@xemahq/contracts@0.9.2/…)
+//
+// `DistributionLockSchema` is `.strict()`. The plane resolves a lock with the
+// contracts build in `repos/xema-kernel-contracts`, which runs AHEAD of what
+// ships; every image parses the same bytes with the version ITS OWN repository
+// declares, and a caret on a `0.x` line is MINOR-LOCKED. So the plane happily
+// sealed an artifact its own images could not read — and the edition sealed,
+// published, installed and verified perfectly first.
+//
+// ── TWO NARROWINGS, AND THE SECOND OVERSHOOT THAT MADE THEM NECESSARY ───────
+//
+// THE ORIGINAL OF THIS FILE ASKED `repos/xema-base` ALONE. That is the WEAKEST
+// subject available — it declares the NEWEST range in the fleet, so a check
+// anchored on it parses with the most permissive schema any image resolves and
+// reports OK while the repositories that would actually crashloop are
+// invisible. The header called that "a correct measurement of the wrong
+// subject" and widened to EVERY PINNED REPOSITORY THAT DECLARES A RANGE.
+//
+// THE WIDENING OVERSHOT ONTO A DIFFERENT WRONG SUBJECT, and it is recorded
+// here rather than quietly corrected, because the next person to touch this
+// will be tempted exactly the same way: a subject that is too NARROW produces
+// a false green, so the instinct is to widen — and a subject that is too WIDE
+// produces a false RED, which blocks honest work and teaches everybody that
+// the seal gate is noise. Both are the wrong subject. Neither is fixed by
+// moving further along the same axis.
+//
+// Measured 2026-09-27 while it was refusing a legitimate customer edition
+// seal, it named two repositories and BOTH were wrong, one per defect:
+//
+//   • CORPUS. `repositoryPins` is FLEET-WIDE, so it graded repositories that
+//     contribute no image to the edition being sealed. `repos/xema-operator`
+//     has ZERO subjects in a customer edition's `images.lock.json` — it
+//     ships nothing there and therefore cannot crashloop there — and the seal
+//     was refused on its `^0.10.0`. The file's own stated invariant is "the
+//     images OF THAT EDITION", and `repositoryPins` is not that set.
+//
+//   • PREDICATE. "declares a contracts range" is a FALSE PROXY for "parses a
+//     lock". `@xemahq/contracts` is a TYPES package that nearly every
+//     first-party repository depends on for unrelated reasons. This file
+//     already contained the principle that refutes the proxy — "a repository
+//     that never parses a lock cannot be made to fail on one, and inventing a
+//     requirement for it would assert something untrue" — and applied it only
+//     to pins with NO contracts dependency at all. `submodules/xema-host-web`
+//     ships images into a customer edition and declares `^0.10.0`, and at
+//     its pinned commit `9b4f9ddda7` it calls the lock parser ZERO times.
+//
+// So the subject is now the INTERSECTION, and both halves are DERIVED:
+//
+//     graded ⟺ contributes ≥1 image subject to THIS edition
+//              AND its pinned commit CALLS the lock parser
+//
+// Measured across the pinned commits with a positive control that fires in
+// every repository (`git grep -l export` → 10224 files in `xema-base`, 6225 in
+// `xema-host-web`; a first pass read `xema-base` as 0 and that was a 1 MB
+// `execFileSync` buffer overflow, not a finding — hence `MAX_BUFFER` below):
+//
+//     repos/xema-base          parseDistributionLock in 3 files  ← a reader
+//     repos/xema-operator      parseDistributionLock in 5 files  ← a reader
+//     repos/xema-community     0     repos/xema-connectors    0
+//     repos/xema-cultivars     0     repos/xema-docs          0
+//     repos/xema-store-api     0     submodules/xema-host-web 0
+//     the five generic submodules                             0
+//
+// TWO of thirteen pins parse a lock. The other eleven were being graded on a
+// question they cannot fail.
+//
+// NEITHER NARROWING WEAKENS THE 2026-09-17 CASE, which is the only thing that
+// matters about them: the service that crashlooped was `biome-host-api`, out
+// of `repos/xema-base`, which ships images into that edition AND is one of the
+// two readers. It is graded by both rules, and `assertPlatformCanParseLock`
+// refuses that lock exactly as before. Asserted in the contract tests rather
+// than argued here.
+//
+// ── WHY A REPOSITORY WITH NO IMAGE IN THIS EDITION IS NOT AN ERROR ──────────
+//
+// Same reason a non-reader is not: the question does not arise. It is the
+// reading that makes this a seal-time gate rather than a fleet audit — the
+// artifact being sealed is ONE edition's lock, and the population that can be
+// broken by it is the images of that edition.
+//
+// KNOWN LIMIT, stated rather than discovered: a subject whose `repo` has NO
+// entry in `repositoryPins` is outside this check, because the pin index is
+// where a commit to read the declaration AT comes from. A customer edition
+// has one today — `presenca-biomes`, a customer repository pinned elsewhere.
+// It was outside this gate before the narrowing too, so nothing was lost here;
+// it is named so nobody reads the corpus line as covering it.
+//
+// AND VENDORED SOURCE IS CORRECTLY OUT, which is worth saying because it looks
+// like a gap: `repos/xema-connectors` contributes an image subject to NO
+// edition — its biomes are vendored INTO another repository's image — so it is
+// graded nowhere now, where it was graded everywhere before. That is right
+// rather than lax. An image built out of `repos/xema-base` resolves
+// `xema-base`'s contracts version whatever source was vendored into it, so the
+// version that decides whether that image can read the lock is the BUILDING
+// repository's, and grading the vendored one would assert something about a
+// resolution that does not happen.
+//
+// ── WHAT COUNTS AS CALLING THE PARSER ───────────────────────────────────────
+//
+// A CALL, NEVER A MENTION, and the distinction is live in this corpus rather
+// than theoretical: `submodules/xema-host-web`'s `src/lib/nav-registry.ts:1135`
+// and `repos/xema-cultivars`'s `decision-api.client.ts:53` each name
+// `distribution.lock.json` in a comment, and neither parses one. Source is
+// comment-blanked (`blankAllComments`) before any assertion.
+//
+// GENERATED CLIENT MIRRORS ARE EXCLUDED. A generated DTO naming a lock type is
+// an orval projection of somebody else's API, not a parser — measured at the
+// committed pins, `xema-operator` carries 15 lock-naming files under
+// `packages/clients/**` and `xema-host-web` 5 under
+// `src/lib/api/orval/clients/**`. Neither ever calls `parseDistributionLock`,
+// so today the exclusion changes no verdict; it is here because the day a
+// generated model is named after the schema is the day it would.
+//
+// IT ERRS TOWARD GRADING, deliberately, because the two errors are not
+// symmetric: over-grading is a seal that waits for a human, and under-grading
+// is the outage. So a CALL to `parseDistributionLock` or `sealDistributionLock`
+// counts, and so does ANY executable reference to `DistributionLockSchema` —
+// holding the strict schema is holding the failure. An imported-but-never-called
+// function is not a reader: it cannot fail at runtime, and a compiler refuses
+// it long before a boot does.
+//
+// ── WHICH SCHEMA A READER PARSES WITH (2026-10-01) ──────────────────────────
+//
+// A pure consumer of a lock now parses it with the kernel's tolerant READER
+// (`parseDistributionLockForReading`, `@xemahq/contracts` >= 0.27.0): every
+// field it knows is validated exactly as the writer validates it, and a key a
+// later edition adds is IGNORED. Grading such a repository with the strict
+// writer would refuse every additive lock change for a reader that can read
+// it — the false red this file already warns about. Not seeing it at all would
+// be worse: once xema-base and xema-operator moved, NEITHER called the strict
+// parser any more, so the graded set went empty and every seal was refused.
+//
+// So detection now sorts every parsing file into one of THREE ways to read:
+//
+//   • STRICT — `parseDistributionLock(`, `sealDistributionLock(`, any
+//     executable `DistributionLockSchema`;
+//   • READER — `parseDistributionLockForReading(`, `DistributionLockReaderSchema`;
+//   • SDK — `loadDistributionLockFromEnv(`, `readDistributionLockFile(`,
+//     `FirstPartyCapabilityDomainsModule`: `@xemahq/xema-service-nest` parses
+//     on the repository's behalf, with WHICHEVER schema the version that
+//     repository's lockfile resolves uses. Earlier SDK versions use the strict
+//     writer, so this is asked of the PUBLISHED SDK tarball at the version the
+//     pinned `pnpm-lock.yaml` records — never inferred from a range, which
+//     resolves the highest admitted version rather than the one that shipped.
+//
+// A repository is graded with the STRICTEST way any of its files reads: one
+// strict call anywhere, or an SDK version that is strict (or cannot be read
+// from the lockfile), and the whole repository is graded strict. Erring toward
+// strict is the same asymmetry as erring toward grading: over-strictness is a
+// seal that waits for a human, under-strictness is the outage. Every case is
+// still graded against the PUBLISHED version's own parser, so a reader on a
+// contracts version that predates a whole schemaVersion is still refused.
+//
+// ── WHY IT ASKS THE SCHEMA RATHER THAN ENCODING A LIST ──────────────────────
+//
+// A hand-kept ledger of "keys added after version V" is a change-tax: every new
+// kernel field would have to be remembered here, and the one nobody remembers
+// is exactly the one that ships. So this RESOLVES each repository's own
+// contracts version and parses the candidate lock with THAT schema. The
+// question is asked, not restated.
+//
+// The version comes from the pin, not from a guess: `runtime-image-source-index
+// .json#repositoryPins` names the exact commit each repository's subjects are
+// built from, and that commit's own manifests declare the range. Reading the
+// declaration AT THE PINNED COMMIT is what makes this true of the images that
+// actually ship rather than of somebody's checkout. The reader detection reads
+// that same commit, for the same reason.
+//
+// ── WHERE A RANGE IS DECLARED, IN PRECEDENCE ORDER ──────────────────────────
+//
+//   1. root `package.json` → `pnpm.overrides['@xemahq/contracts']`
+//   2. `pnpm-workspace.yaml` → the default `catalog:` entry
+//   3. root `package.json` → a LITERAL dependency range (not `catalog:`)
+//
+// An override outranks the catalog unconditionally, which is not hypothetical:
+// `repos/xema-operator` declares one. (3) is what reaches the npm-managed
+// repositories that have no pnpm workspace at all — `submodules/xema-host-web`
+// is the live case, and reading only a catalog misses it entirely.
+//
+// KNOWN LIMIT, stated rather than discovered: a workspace MEMBER that declares
+// its own literal range instead of `catalog:` is outside this read. Measured at
+// today's pins, none does — the only literals in any member manifest are OPEN
+// `peerDependencies` floors (`>=0.4.0`, `>=0.16.0`), which constrain nothing
+// that gets installed.
+//
+// ── FAILURE POSTURE ─────────────────────────────────────────────────────────
+//
+// REFUSES, and never degrades. A missing checkout, an unfetched pin, an
+// unreachable registry and a package exporting no `parseDistributionLock` each
+// throw: "every image can read this lock" is a claim, and a claim that cannot
+// be checked has not been established.
+//
+// THREE EMPTINESS REFUSALS, and the narrowing makes them MORE important rather
+// than less — a scan over nothing is not a pass, and there are now two more
+// ways to arrive at nothing than there were:
+//
+//   • an empty `repositoryPins` — nothing has been graded at all;
+//   • an edition whose image lock has no subjects — there is no population;
+//   • an empty GRADED SET — every pin was narrowed away. That would mean no
+//     image in this edition reads the lock, which is false of every edition
+//     that exists (all ten carry `repos/xema-base`), so it is a broken
+//     derivation rather than a clean bill of health.
+//
+// And one refusal for the case the two narrowings could otherwise hide: a
+// repository that PARSES a lock and declares NO contracts range. Its version
+// cannot be resolved, so its readability cannot be established, and skipping
+// it would be the silent half of the original defect. No pin is in that state
+// today; the arm is fail-closed rather than speculative.
+
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdtempSync, readFileSync, readdirSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { blankAllComments } from './comment-blanker.mjs';
+import { sourcesRoot } from './edition-workspace.mjs';
+
+const CONTRACTS_PACKAGE = '@xemahq/contracts';
+/** `'@xemahq/contracts': ^0.22.0` and `"@xemahq/contracts": ^0.10.0` alike. */
+const CATALOG_ENTRY = /^\s+['"]?@xemahq\/contracts['"]?:\s*(\S+)\s*$/u;
+/** A column-0 YAML key ends the `catalog:` block. */
+const TOP_LEVEL_KEY = /^\S/u;
+
+/**
+ * 256 MB, and it is load-bearing rather than defensive. `execFileSync`
+ * defaults to 1 MB; `git grep -l` over `repos/xema-base` at a pinned commit
+ * exceeds that, and the overflow surfaces as a THROW — which, caught, reads as
+ * "this repository matched nothing". A first measurement of the reader corpus
+ * reported `xema-base` as a non-reader for exactly that reason, and only a
+ * positive control that also came back 0 exposed it.
+ */
+const MAX_BUFFER = 256 * 1024 * 1024;
+
+/** Source a repository could plausibly parse a lock from. */
+const SOURCE_PATHSPECS = ['*.ts', '*.tsx', '*.mts', '*.cts', '*.js', '*.mjs', '*.cjs'];
+
+/**
+ * Generated client mirrors. Orval output, never authored, and a generated DTO
+ * named after a lock type is a projection of an API rather than a parser.
+ */
+const GENERATED_CLIENT_MIRRORS = [/(^|\/)packages\/clients\//u, /(^|\/)orval\/clients\//u];
+
+/** How a repository parses a distribution lock. Closed set. */
+export const LockReadMode = Object.freeze({
+  /** The strict WRITER schema — an unknown key refuses the whole lock. */
+  Strict: 'strict',
+  /** The tolerant READER schema — an unknown additive key is ignored. */
+  Reader: 'reader',
+});
+
+/** Executable shapes that parse a lock with the strict WRITER schema. */
+const STRICT_PARSER_PATTERNS = [
+  /\bparseDistributionLock\s*\(/u,
+  /\bsealDistributionLock\s*\(/u,
+  /\bDistributionLockSchema\b/u,
+];
+/** Executable shapes that parse a lock with the tolerant READER schema. */
+const READER_PARSER_PATTERNS = [
+  /\bparseDistributionLockForReading\s*\(/u,
+  /\bDistributionLockReaderSchema\b/u,
+];
+/**
+ * Executable shapes that have `@xemahq/xema-service-nest` parse the lock on the
+ * repository's behalf — with whichever schema that SDK version uses.
+ */
+const SDK_PARSER_PATTERNS = [
+  /\bloadDistributionLockFromEnv\s*\(/u,
+  /\breadDistributionLockFile\s*\(/u,
+  /\bFirstPartyCapabilityDomainsModule\b/u,
+];
+/**
+ * Cheap `git grep -F` prefilter — every regex above is anchored on one of
+ * these (`parseDistributionLockForReading` contains `parseDistributionLock`).
+ */
+const PARSER_NEEDLES = [
+  'parseDistributionLock',
+  'sealDistributionLock',
+  'DistributionLockSchema',
+  'DistributionLockReaderSchema',
+  'loadDistributionLockFromEnv',
+  'readDistributionLockFile',
+  'FirstPartyCapabilityDomainsModule',
+];
+
+const SDK_PACKAGE = '@xemahq/xema-service-nest';
+/** Where the SDK's boot-time lock read lives inside its published tarball. */
+const SDK_LOCK_READER_MODULE = join('dist', 'lib', 'distribution-lock', 'distribution-lock-env.js');
+/** Every resolved SDK version in a pnpm lockfile's `packages:`/`snapshots:` keys. */
+const SDK_LOCK_ENTRY = /^ {2}'?@xemahq\/xema-service-nest@(\d+\.\d+\.\d+[^('\s:]*)/gmu;
+
+/** One download per contracts VERSION and MODE per process. */
+const parserCache = new Map();
+/** One download per SDK VERSION per process. */
+const sdkModeCache = new Map();
+
+function run(command, args, options = {}) {
+  return execFileSync(command, args, {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+    maxBuffer: MAX_BUFFER,
+    ...options,
+  }).trim();
+}
+
+/** `git show <commit>:<path>`, or `undefined` when that path is not in the tree. */
+function showAtCommit(directory, commit, path) {
+  try {
+    return run('git', ['-C', directory, 'show', `${commit}:${path}`]);
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * The checkout and the pinned commit, or a refusal.
+ *
+ * @throws when either is absent. Both mean the question cannot be answered,
+ * and an unanswered question is not a pass.
+ */
+function pinnedCheckout({ repoRoot, repo, commit }) {
+  const directory = join(repoRoot, repo);
+  // A submodule's `.git` is a FILE holding a `gitdir:` pointer, not a
+  // directory, so this must stay an existence test rather than a directory one.
+  if (!existsSync(join(directory, '.git'))) {
+    throw new Error(
+      `platform lock readability: "${repo}" is not checked out at ${directory}, so the ` +
+        'contracts version its images resolve cannot be read. The assertion is not ' +
+        'optional — refusing rather than sealing a lock nothing has proven readable. ' +
+        'In CI, run checkout-indexed-source-repositories.mjs before sealing.',
+    );
+  }
+  try {
+    run('git', ['-C', directory, 'cat-file', '-e', `${commit}^{commit}`]);
+  } catch {
+    throw new Error(
+      `platform lock readability: ${repo} does not have its pinned commit ${commit}. ` +
+        'Fetch that exact commit before sealing — a lock cannot be proven readable ' +
+        'against a revision this checkout does not hold.',
+    );
+  }
+  return directory;
+}
+
+function catalogRange(workspaceYaml) {
+  if (workspaceYaml === undefined) {return undefined;}
+  let inCatalog = false;
+  for (const line of workspaceYaml.split('\n')) {
+    if (TOP_LEVEL_KEY.test(line)) {
+      inCatalog = line.startsWith('catalog:');
+      continue;
+    }
+    if (!inCatalog) {continue;}
+    const match = CATALOG_ENTRY.exec(line);
+    if (match) {return match[1].replace(/^['"]|['"]$/gu, '');}
+  }
+  return undefined;
+}
+
+function manifestRange(packageJson) {
+  if (packageJson === undefined) {return undefined;}
+  let parsed;
+  try {
+    parsed = JSON.parse(packageJson);
+  } catch {
+    return undefined;
+  }
+  const override = parsed?.pnpm?.overrides?.[CONTRACTS_PACKAGE];
+  if (typeof override === 'string' && override.length > 0) {
+    return { range: override, source: 'pnpm.overrides' };
+  }
+  for (const field of ['dependencies', 'devDependencies']) {
+    const declared = parsed?.[field]?.[CONTRACTS_PACKAGE];
+    // `catalog:` is a POINTER at the workspace catalog, never a range. Reading
+    // it as one would resolve the literal string against the registry.
+    if (typeof declared === 'string' && declared.length > 0 && declared !== 'catalog:') {
+      return { range: declared, source: `package.json ${field}` };
+    }
+  }
+  return undefined;
+}
+
+/** True for a path under a generated client mirror, which is never a parser. */
+export function isGeneratedClientMirror(path) {
+  return GENERATED_CLIENT_MIRRORS.some((pattern) => pattern.test(path));
+}
+
+/**
+ * The contracts range one pinned repository declares, and where it declares it.
+ *
+ * `undefined` means the repository declares none — see the header: that is a
+ * repository which parses no lock, and it is not an error.
+ *
+ * @throws when the checkout or the pinned commit is absent.
+ */
+export function declaredContractsRange({ repoRoot = sourcesRoot(), repo, commit }) {
+  const directory = pinnedCheckout({ repoRoot, repo, commit });
+  const fromManifest = manifestRange(showAtCommit(directory, commit, 'package.json'));
+  if (fromManifest?.source === 'pnpm.overrides') {return fromManifest;}
+  const fromCatalog = catalogRange(
+    showAtCommit(directory, commit, 'pnpm-workspace.yaml'),
+  );
+  if (fromCatalog !== undefined) {
+    return { range: fromCatalog, source: 'pnpm-workspace.yaml catalog' };
+  }
+  return fromManifest;
+}
+
+/**
+ * Does this repository, AT ITS PINNED COMMIT, actually parse a distribution
+ * lock?
+ *
+ * Returns `{ isReader, files, mentionOnly }`. `files` are the executable call
+ * sites; `mentionOnly` are files that name a parser symbol in PROSE alone and
+ * are reported so an over-blank shows up as a visible difference rather than
+ * as a silently smaller corpus.
+ *
+ * @throws when the checkout or the pinned commit is absent, and when `git
+ * grep` fails for any reason other than "no match" (exit 1). A search that did
+ * not run is not a search that found nothing.
+ */
+export function parsesDistributionLock({ repoRoot = sourcesRoot(), repo, commit }) {
+  const directory = pinnedCheckout({ repoRoot, repo, commit });
+  let listing;
+  try {
+    listing = run('git', [
+      '-C',
+      directory,
+      'grep',
+      '--name-only',
+      '--fixed-strings',
+      ...PARSER_NEEDLES.flatMap((needle) => ['-e', needle]),
+      commit,
+      '--',
+      ...SOURCE_PATHSPECS,
+    ]);
+  } catch (error) {
+    if (error.status === 1) {listing = '';}
+    else {
+      throw new Error(
+        `platform lock readability: could not search ${repo}@${commit.slice(0, 10)} for ` +
+          `lock-parser call sites (git grep exited ${error.status}). A search that did ` +
+          `not run is not a search that found nothing.`,
+      );
+    }
+  }
+  const candidates = listing
+    .split('\n')
+    .map((line) => line.trim())
+    // `git grep <commit>` prefixes every path with `<commit>:`.
+    .map((line) => (line.startsWith(`${commit}:`) ? line.slice(commit.length + 1) : line))
+    .filter((path) => path.length > 0 && !isGeneratedClientMirror(path));
+
+  const files = [];
+  const strictFiles = [];
+  const readerFiles = [];
+  const sdkFiles = [];
+  const mentionOnly = [];
+  for (const path of candidates) {
+    const source = showAtCommit(directory, commit, path);
+    if (source === undefined) {continue;}
+    const executable = blankAllComments(source);
+    const strict = STRICT_PARSER_PATTERNS.some((pattern) => pattern.test(executable));
+    const reader = READER_PARSER_PATTERNS.some((pattern) => pattern.test(executable));
+    const sdk = SDK_PARSER_PATTERNS.some((pattern) => pattern.test(executable));
+    if (strict) {strictFiles.push(path);}
+    if (reader) {readerFiles.push(path);}
+    if (sdk) {sdkFiles.push(path);}
+    if (strict || reader || sdk) {files.push(path);}
+    else {mentionOnly.push(path);}
+  }
+  return {
+    isReader: files.length > 0,
+    files,
+    strictFiles,
+    readerFiles,
+    sdkFiles,
+    mentionOnly,
+  };
+}
+
+/**
+ * Every `@xemahq/xema-service-nest` version the pinned `pnpm-lock.yaml`
+ * resolves — the versions that SHIP, not the highest a range admits.
+ * Empty when the repository has no pnpm lockfile or resolves no SDK.
+ */
+export function lockedSdkVersions({ repoRoot = sourcesRoot(), repo, commit }) {
+  const directory = pinnedCheckout({ repoRoot, repo, commit });
+  const lockfile = showAtCommit(directory, commit, 'pnpm-lock.yaml');
+  if (lockfile === undefined) {return [];}
+  const versions = new Set();
+  for (const match of lockfile.matchAll(SDK_LOCK_ENTRY)) {versions.add(match[1]);}
+  return [...versions].sort();
+}
+
+/**
+ * Does the PUBLISHED SDK at `version` parse the lock with the kernel READER?
+ * Asked of the tarball's own executable source (comments blanked), so a
+ * docblock that names the reader cannot answer for a body that does not call it.
+ */
+export function sdkReadsWithReader(version) {
+  const cached = sdkModeCache.get(version);
+  if (cached !== undefined) {return cached;}
+  const directory = mkdtempSync(join(tmpdir(), 'xema-service-nest-'));
+  run('npm', ['pack', `${SDK_PACKAGE}@${version}`], { cwd: directory });
+  const tarball = readdirSync(directory).find((name) => name.endsWith('.tgz'));
+  if (tarball === undefined) {
+    throw new Error(
+      `platform lock readability: \`npm pack ${SDK_PACKAGE}@${version}\` produced no tarball.`,
+    );
+  }
+  run('tar', ['xzf', join(directory, tarball), '-C', directory]);
+  const module = join(directory, 'package', SDK_LOCK_READER_MODULE);
+  if (!existsSync(module)) {
+    throw new Error(
+      `platform lock readability: ${SDK_PACKAGE}@${version} ships no ${SDK_LOCK_READER_MODULE}, ` +
+        'so the schema its boot-time lock read uses cannot be established.',
+    );
+  }
+  const executable = blankAllComments(readFileSync(module, 'utf8'));
+  const readsWithReader = /\bparseDistributionLockForReading\s*\(/u.test(executable);
+  sdkModeCache.set(version, readsWithReader);
+  return readsWithReader;
+}
+
+/**
+ * The schema a repository is graded with: the STRICTEST way any of its files
+ * reads a lock. See the header — erring strict is a seal that waits for a
+ * human; erring lenient is the outage.
+ */
+export function lockReadMode({
+  repoRoot = sourcesRoot(),
+  repo,
+  commit,
+  detected,
+  sdkUsesReader = sdkReadsWithReader,
+}) {
+  if (detected.strictFiles.length > 0) {
+    return {
+      mode: LockReadMode.Strict,
+      reason: `calls the strict writer schema in ${detected.strictFiles[0]}`,
+    };
+  }
+  if (detected.sdkFiles.length > 0) {
+    const versions = lockedSdkVersions({ repoRoot, repo, commit });
+    if (versions.length === 0) {
+      return {
+        mode: LockReadMode.Strict,
+        reason:
+          `reads through ${SDK_PACKAGE} (${detected.sdkFiles[0]}) but its pinned ` +
+          'pnpm-lock.yaml resolves no SDK version, so the SDK is assumed strict',
+      };
+    }
+    const strictSdk = versions.filter((version) => !sdkUsesReader(version));
+    if (strictSdk.length > 0) {
+      return {
+        mode: LockReadMode.Strict,
+        reason: `reads through ${SDK_PACKAGE}@${strictSdk.join(', ')}, which parses with the strict writer schema`,
+      };
+    }
+    return {
+      mode: LockReadMode.Reader,
+      reason: `reads through ${SDK_PACKAGE}@${versions.join(', ')}, which parses with the reader`,
+    };
+  }
+  return {
+    mode: LockReadMode.Reader,
+    reason: `parses with the reader in ${detected.readerFiles[0]}`,
+  };
+}
+
+/**
+ * The set of repositories that contribute at least one IMAGE SUBJECT to this
+ * edition. This — not `repositoryPins` — is the population an edition's lock
+ * can break.
+ *
+ * @throws on an image lock with no subjects, and on a subject that names no
+ * repository: neither can be graded, and neither is a pass.
+ */
+export function editionImageRepos({ imageLock, distributionId }) {
+  const subjects = imageLock?.subjects;
+  if (!Array.isArray(subjects) || subjects.length === 0) {
+    throw new Error(
+      `platform lock readability: "${distributionId}" has no image subjects, so the ` +
+        'population of images that must read this lock is unknown. A scan over nothing ' +
+        'is not a pass.',
+    );
+  }
+  const repos = new Set();
+  for (const subject of subjects) {
+    if (typeof subject?.repo !== 'string' || subject.repo.length === 0) {
+      throw new Error(
+        `platform lock readability: "${distributionId}" carries an image subject ` +
+          `(${subject?.id ?? 'unnamed'}) that names no source repository, so whether its ` +
+          'image can read this lock cannot be established.',
+      );
+    }
+    repos.add(subject.repo);
+  }
+  return repos;
+}
+
+/**
+ * The repositories this edition's lock must be readable by, grouped by the
+ * contracts version each resolves.
+ *
+ * Narrowed in two stages, corpus then predicate, cheapest first: the corpus
+ * test is pure set membership and needs no checkout, so a pin that ships
+ * nothing here is never read from disk at all.
+ */
+export function planReadabilityChecks({
+  imageLock,
+  distributionId,
+  runtimeSourceIndex,
+  repoRoot = sourcesRoot(),
+  resolveVersion = resolvedContractsVersion,
+  detectReader = parsesDistributionLock,
+  resolveReadMode = lockReadMode,
+}) {
+  const pins = runtimeSourceIndex?.repositoryPins;
+  if (!Array.isArray(pins) || pins.length === 0) {
+    throw new Error(
+      'platform lock readability: the runtime image source index declares no ' +
+        'repositoryPins, so no image has been graded. A scan over nothing is not a pass.',
+    );
+  }
+  const shipping = editionImageRepos({ imageLock, distributionId });
+
+  const contributing = [];
+  const notInThisEdition = [];
+  for (const pin of pins) {
+    if (shipping.has(pin.repo)) {contributing.push(pin);}
+    else {notInThisEdition.push(pin.repo);}
+  }
+  // A subject repository with no pin is outside this check by construction —
+  // there is no commit to read a declaration at. Reported, never inferred.
+  const unpinnedSubjectRepos = [...shipping]
+    .filter((repo) => !pins.some((pin) => pin.repo === repo))
+    .sort();
+
+  const readers = [];
+  const parseNoLock = [];
+  for (const pin of contributing) {
+    const detected = detectReader({ repoRoot, repo: pin.repo, commit: pin.sourceCommit });
+    if (detected.isReader) {readers.push({ pin, files: detected.files, detected });}
+    else {parseNoLock.push({ repo: pin.repo, mentionOnly: detected.mentionOnly });}
+  }
+
+  const declaring = [];
+  for (const { pin, files, detected } of readers) {
+    const declared = declaredContractsRange({
+      repoRoot,
+      repo: pin.repo,
+      commit: pin.sourceCommit,
+    });
+    if (declared === undefined) {
+      // A READER with no declared range. The two narrowings above both remove
+      // a repository on the grounds that a question does not arise for it;
+      // this one is the case where it does arise and cannot be answered.
+      throw new Error(
+        `platform lock readability: ${pin.repo}@${pin.sourceCommit.slice(0, 10)} PARSES a ` +
+          `distribution lock (${files.join(', ')}) but declares no ${CONTRACTS_PACKAGE} ` +
+          'range, so the version its images resolve — and therefore whether they can read ' +
+          'this lock — cannot be established. Declare the range, or establish why that ' +
+          'source does not ship in an image. Skipping it would be the silent half of the ' +
+          'defect this gate exists for.',
+      );
+    }
+    const { mode, reason } = resolveReadMode({
+      repoRoot,
+      repo: pin.repo,
+      commit: pin.sourceCommit,
+      detected,
+    });
+    declaring.push({
+      repo: pin.repo,
+      commit: pin.sourceCommit,
+      range: declared.range,
+      source: declared.source,
+      files,
+      mode,
+      modeReason: reason,
+      version: resolveVersion(declared.range),
+    });
+  }
+
+  if (declaring.length === 0) {
+    throw new Error(
+      `platform lock readability: no pinned repository contributing an image to ` +
+        `"${distributionId}" parses a distribution lock, so this seal has been graded ` +
+        'against nothing. Every edition that exists ships images out of at least one pinned repository ' +
+        'that IS a reader — so an empty graded set is a broken derivation, not a clean ' +
+        'bill of health. A scan over nothing is not a pass.',
+    );
+  }
+
+  // Keyed by VERSION AND MODE: one published version read two ways is two
+  // parsers, and grading both with one would be wrong in one direction or the
+  // other.
+  const byVersion = new Map();
+  for (const entry of declaring) {
+    const key = readabilityKey(entry.version, entry.mode);
+    const bucket = byVersion.get(key);
+    if (bucket) {bucket.push(entry);}
+    else {byVersion.set(key, [entry]);}
+  }
+  return {
+    pinCount: pins.length,
+    contributing: contributing.map((pin) => pin.repo),
+    notInThisEdition,
+    unpinnedSubjectRepos,
+    parseNoLock,
+    declaring,
+    byVersion,
+  };
+}
+
+/** The `byVersion` key: `<version>` for a strict reader, `<version>+reader` for a tolerant one. */
+export function readabilityKey(version, mode) {
+  return mode === LockReadMode.Reader ? `${version}+reader` : version;
+}
+
+/**
+ * The version a range ACTUALLY resolves, asked of the registry.
+ *
+ * `npm view <pkg>@<range> version` answers with the highest published version
+ * the range admits, which is the whole point: `^0.10.0` is minor-locked and
+ * resolves 0.10.0 even though 0.22.0 exists, and hand-reasoning about that is
+ * how the defect this file exists for was argued away twice.
+ */
+export function resolvedContractsVersion(range) {
+  const output = run('npm', [
+    'view',
+    `${CONTRACTS_PACKAGE}@${range}`,
+    'version',
+    '--json',
+  ]);
+  const parsed = JSON.parse(output);
+  const version = Array.isArray(parsed) ? parsed[parsed.length - 1] : parsed;
+  if (typeof version !== 'string' || version.length === 0) {
+    throw new Error(
+      `platform lock readability: the registry returned no version for ` +
+        `"${CONTRACTS_PACKAGE}@${range}". An unanswered question is not a pass.`,
+    );
+  }
+  return version;
+}
+
+/**
+ * The lock parser as that exact published version implements it — the strict
+ * `parseDistributionLock`, or the tolerant `parseDistributionLockForReading`
+ * for a repository graded as a READER.
+ */
+export async function loadPublishedLockParser(version, mode = LockReadMode.Strict) {
+  const cacheKey = readabilityKey(version, mode);
+  const cached = parserCache.get(cacheKey);
+  if (cached) {return cached;}
+  const directory = mkdtempSync(join(tmpdir(), 'xema-contracts-'));
+  run('npm', ['pack', `${CONTRACTS_PACKAGE}@${version}`], { cwd: directory });
+  const tarball = readdirSync(directory).find((name) => name.endsWith('.tgz'));
+  if (tarball === undefined) {
+    throw new Error(
+      `platform lock readability: \`npm pack ${CONTRACTS_PACKAGE}@${version}\` produced no tarball.`,
+    );
+  }
+  run('tar', ['xzf', join(directory, tarball), '-C', directory]);
+  // The tarball ships no `node_modules`, and the schema module requires `zod`
+  // at load. Installing the package's OWN declared runtime dependencies is what
+  // makes this a faithful reproduction of the platform's parse rather than a
+  // parse with whatever happens to be resolvable from here.
+  run('npm', ['install', '--omit=dev', '--no-audit', '--no-fund', '--silent'], {
+    cwd: join(directory, 'package'),
+  });
+  const entry = join(directory, 'package', 'dist', 'distribution', 'index.js');
+  const loaded = await import(`file://${entry}`);
+  const exportName =
+    mode === LockReadMode.Reader ? 'parseDistributionLockForReading' : 'parseDistributionLock';
+  const parse = loaded[exportName];
+  if (typeof parse !== 'function') {
+    throw new Error(
+      `platform lock readability: ${CONTRACTS_PACKAGE}@${version} exports no ` +
+        `${exportName}, so the platform-side parse cannot be reproduced.`,
+    );
+  }
+  parserCache.set(cacheKey, parse);
+  return parse;
+}
+
+/**
+ * REFUSE a lock an image of THIS EDITION cannot parse, naming the repository,
+ * its declared range, the version that range resolves, the file that parses
+ * and the offending key — none of which the raw zod message carries on its own.
+ */
+export async function assertPlatformCanParseLock({
+  lock,
+  imageLock,
+  distributionId,
+  runtimeSourceIndex,
+  repoRoot = sourcesRoot(),
+  resolveVersion = resolvedContractsVersion,
+  detectReader = parsesDistributionLock,
+  resolveReadMode = lockReadMode,
+  loadParser = loadPublishedLockParser,
+}) {
+  const plan = planReadabilityChecks({
+    imageLock,
+    distributionId,
+    runtimeSourceIndex,
+    repoRoot,
+    resolveVersion,
+    detectReader,
+    resolveReadMode,
+  });
+  for (const [_key, repos] of [...plan.byVersion].sort(([a], [b]) =>
+    a < b ? -1 : a > b ? 1 : 0,
+  )) {
+    const { version, mode } = repos[0];
+    const parse = await loadParser(version, mode);
+    try {
+      parse(JSON.parse(JSON.stringify(lock)));
+    } catch (error) {
+      const detail = String(error.message).replace(/\s+/gu, ' ').trim();
+      const named = repos
+        .map(
+          (r) =>
+            `${r.repo}@${r.commit.slice(0, 10)} declares ${r.range} (${r.source}) and parses a ` +
+            `lock in ${r.files.length} file${r.files.length === 1 ? '' : 's'}, e.g. ${r.files[0]} ` +
+            `— graded ${r.mode}: ${r.modeReason}`,
+        )
+        .join('\n    ');
+      throw new Error(
+        `REFUSING TO SEAL "${distributionId}": images built from ${repos.length} pinned ` +
+          `repositor${repos.length === 1 ? 'y' : 'ies'} SHIP INTO THIS EDITION, PARSE THIS ` +
+          `LOCK, and cannot read it.\n\n  ${detail}\n\n` +
+          `    ${named}\n\n` +
+          `  — and all of those RESOLVE ${CONTRACTS_PACKAGE}@${version} and read it with the ` +
+          `${mode === LockReadMode.Reader ? 'tolerant READER' : 'strict WRITER'} schema, because a caret on a ` +
+          `0.x line is MINOR-LOCKED.\n\n` +
+          `The plane resolved this lock with the contracts build in ` +
+          `the kernel checkout, which runs AHEAD of what ships, and ` +
+          `DistributionLockSchema is strict — so a key added after ${version} makes the whole ` +
+          `lock unreadable AT BOOT, for every service that reads it strictly, not only the biome ` +
+          `that carries it; and even the tolerant reader refuses a schemaVersion or a malformed ` +
+          `known field that ${version} does not admit.\n\n` +
+          `A strict-graded repository is cured by moving its readers to ` +
+          `parseDistributionLockForReading (or an ${SDK_PACKAGE} that uses it).\n\n` +
+          `Either stop persisting that key (a resolver INPUT does not belong in a sealed ` +
+          `artifact — see external-source-walk.mjs), or raise those repositories' contracts ` +
+          `ranges past the version that introduced it and rebuild their images before sealing. ` +
+          `Sealing now would publish an edition that installs and then crashloops.`,
+      );
+    }
+  }
+  // THE CORPUS LINE. A run that graded nothing and a run that graded everything
+  // exit the same way; the counts are the only thing that tells them apart —
+  // and after the narrowing there are two more ways to grade nothing than
+  // there were, so it now prints BOTH narrowings rather than one total.
+  const summary = [...plan.byVersion]
+    .map(([key, repos]) => `${key}×${repos.length}`)
+    .sort()
+    .join(', ');
+  const mentionOnly = plan.parseNoLock.filter((entry) => entry.mentionOnly.length > 0);
+  const named = (repos) => (repos.length > 0 ? ` [${repos.join(', ')}]` : '');
+  console.log(
+    `[dist:seal-digests] platform readability: OK — "${distributionId}" GRADED against ` +
+      `${plan.declaring.length} of ${plan.pinCount} pinned repositories (${summary}): ` +
+      `${plan.declaring.map((d) => `${d.repo}@${d.version} (${d.mode})`).join(', ')}. ` +
+      `NARROWED: ${plan.contributing.length} pins ship an image into this edition` +
+      `${named(plan.notInThisEdition.map((r) => `-${r}`))}` +
+      `, and of those ${plan.declaring.length} parse a distribution lock` +
+      `${named(plan.parseNoLock.map((e) => `-${e.repo}`))}` +
+      `${mentionOnly.length > 0 ? `; ${mentionOnly.map((e) => e.repo).join(', ')} name a parser symbol in PROSE only` : ''}` +
+      `${plan.unpinnedSubjectRepos.length > 0 ? `. OUTSIDE THIS CHECK: ${plan.unpinnedSubjectRepos.join(', ')} contribute an image subject but hold no repositoryPins entry` : ''}.`,
+  );
+  return {
+    declaring: plan.declaring,
+    contributing: plan.contributing,
+    notInThisEdition: plan.notInThisEdition,
+    parseNoLock: plan.parseNoLock,
+    unpinnedSubjectRepos: plan.unpinnedSubjectRepos,
+  };
+}