@xemahq/xema 0.26.0 → 0.27.0

package/edition/dist-check.mjs

@@ -0,0 +1,986 @@
+#!/usr/bin/env node
+// dist-check — CI guard for the distribution packaging plane. Verifies:
+//   1. committed biome-index.json identities/order are valid offline
+//      (`--check-sources` additionally scans a trusted clean aggregator);
+//   2. packaging contract tests are green (closure, immutability, parity);
+//   3. every distribution under distributions/*/xema-distribution.json resolves
+//      cleanly AND its committed distribution.lock.json matches a fresh resolve;
+//   4. every distribution's committed images.lock.json is STRUCTURALLY in sync
+//      with the committed distribution lock — the same actual runtime subjects,
+//      complete platform bindings, and bundled web-biome set;
+//   5. the evidence trust policy the data root declares (if any): its
+//      trusted-root digest and the data-root pin of the policy and of this
+//      CLI's verifier agree, and its authority configuration is either
+//      explicitly unarmed or fully armed (never partially configured); a data
+//      root declaring none says so, and is refused if it holds an undeclared
+//      policy.
+//
+// The distribution lock is compared in FULL (timestamp normalized out): its
+// `inputHash` is deterministic over (biomes + platformServices + manifest), so
+// any real packaging drift is caught. The image lock is compared
+// STRUCTURALLY ONLY — `contentHash` is deliberately excluded by the default
+// offline check. A content hash is source-derived from an exact Git commit and
+// changes whenever that committed source path/type/mode/content changes.
+// Uncommitted and ignored working-tree files are never inputs. Trusted
+// regeneration verifies exact commits with `--check-sources`.
+// It is never treated as an OCI digest or sufficient reuse evidence. Nonzero
+// exit on any structural drift or resolver error.
+
+import { execFileSync } from 'node:child_process';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import {
+  AuthorizationLockCheck,
+  checkEditionAuthorizationLock,
+  loadKernelAuthorizationComposer,
+} from './authorization-base.mjs';
+import { verifyBiomeContentHashes } from './biome-content.mjs';
+import { EditionChannel } from './edition-channel.mjs';
+import {
+  EDITION_CHART_SET_FILE,
+  EditionChartSetCheck,
+  fleetChartSetLockPath,
+  assertRosteredChartSetLock,
+  checkEditionChartSet,
+} from './edition-chart-set.mjs';
+import { editionWorkspaceConfig } from './edition-config.mjs';
+import { assertKernelEditionProtocol } from './edition-protocol.mjs';
+import { WorkspaceRoot, biomeIndexPath, configureEditionWorkspaceFromProcess, editionsRoot, isEntryModule, kernelPackageDir, platformServiceIndexPath, runtimeImageSourceIndexPath, workspaceArgv } from './edition-workspace.mjs';
+import { checkEvidenceTrustPolicy } from './evidence-trust-policy.mjs';
+import {
+  compareIndexEntries,
+  comparableDistributionLock,
+  loadKernelDistributionSchemas,
+  serializeJson,
+  validateImmutableBiomeIndex,
+  validateImmutableDistributionLock,
+  validateImmutableImageLock,
+  validateServiceDependencyOwnerParity,
+} from './lib.mjs';
+import { commandFor } from './remedy-command.mjs';
+import { resolveDistributionWithIndex } from './resolve-distribution.mjs';
+import {
+  resolveDistributionDeclaredSources,
+  resolveDistributionRequiredPlatforms,
+  externalSourceTrees,
+  resolveImages,
+  resolveComposedProcessStructure,
+  resolveImageStructure,
+  sourceTreeLocator,
+} from './resolve-images.mjs';
+import { withoutSealedDigests } from './seal-image-digests.mjs';
+import { committedRepositoryPins, createPinnedSourceAuthority } from './source-authority.mjs';
+
+if (isEntryModule(import.meta.url)) {
+  configureEditionWorkspaceFromProcess([WorkspaceRoot.Data, WorkspaceRoot.Editions, WorkspaceRoot.Sources, WorkspaceRoot.Kernel, WorkspaceRoot.Deploy, WorkspaceRoot.Cache, WorkspaceRoot.SourceHash]);
+}
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+/** Strip the volatile timestamp so committed-vs-fresh locks compare cleanly. */
+function normalize(lock) {
+  const { resolvedAt: _resolvedAt, ...rest } = lock;
+  return serializeJson(rest);
+}
+
+/** Outcome of a single committed-vs-fresh lock comparison. */
+const LockCheck = Object.freeze({
+  GREEN: 'green',
+  MISSING: 'missing',
+  STALE: 'stale',
+});
+
+/**
+ * Compare a freshly-resolved lock against its committed file (timestamp
+ * normalized out). Pure — returns a {@link LockCheck} verdict; the caller owns
+ * messaging and exit handling.
+ *
+ * ── THIS IS THE REBUILDABLE LOCK, AND THAT IS WHY A PLAIN DIFF IS VALID ─────
+ *
+ * `distribution.lock.json` and `images.lock.json` live side by side in every
+ * edition directory and are DIFFERENT CLASSES. Only one of them may be checked
+ * this way, and the reader is who gets it wrong, so it is said at the read
+ * rather than at a definition:
+ *
+ *   distribution.lock.json  REBUILDABLE.  A fresh resolve REPRODUCES it, byte
+ *                           for byte once `resolvedAt` is normalised out. It
+ *                           records a SELECTION derived from the manifests and
+ *                           the pins, so regenerating it recomputes the same
+ *                           answer from the same inputs. Measured 2026-09-28:
+ *                           ZERO of the 9 committed distribution locks carries
+ *                           an `imageDigest`, or any `sha256:` at all.
+ *
+ *   images.lock.json        SEALED.  A fresh resolve does NOT reproduce it —
+ *                           `resolve-images.mjs` emits no `imageDigest` at all
+ *                           and says so in its own header, and the digests are
+ *                           written afterwards by `seal-image-digests.mjs`.
+ *                           Measured 2026-09-28 across the 9 committed locks:
+ *                           523 subjects, 523 of them sealed. So regenerating
+ *                           that file does not recompute an answer — it
+ *                           DISCARDS 523 approved digest bindings, and a plain
+ *                           regenerate-and-diff reports every one of them as
+ *                           drift.
+ *
+ * `checkImagesLock` below therefore subtracts the seal before comparing
+ * (`withoutSealedDigests`, plus a purely structural pass). Do not "simplify"
+ * the two reads into one shared helper: they agree on shape and disagree on
+ * the only thing that matters.
+ */
+async function compareCommittedLock(lockPath, fresh) {
+  if (!existsSync(lockPath)) {return LockCheck.MISSING;}
+  const schemas = await loadKernelDistributionSchemas();
+  const raw = JSON.parse(readFileSync(lockPath, 'utf8'));
+  validateImmutableDistributionLock(raw);
+  return comparableDistributionLock(schemas, raw) === comparableDistributionLock(schemas, fresh)
+    ? LockCheck.GREEN
+    : LockCheck.STALE;
+}
+
+/**
+ * Check one distribution's committed distribution.lock.json against a fresh
+ * resolve. Returns true on green. The image lock is only meaningful when the
+ * distribution lock is green (resolve-images reads it), so this gates that step.
+ *
+ * Returns the INDEX the fresh lock was resolved from (platform entries plus the
+ * edition's source-walked ones) on green, `null` otherwise — the authorization
+ * check below looks the lock's biomes up in that same index.
+ */
+async function checkDistributionLock(id) {
+  const lockPath = join(editionsRoot(), id, 'distribution.lock.json');
+  try {
+    const { lock: fresh, index } = await resolveDistributionWithIndex(id);
+    const verdict = await compareCommittedLock(lockPath, fresh);
+    if (verdict === LockCheck.MISSING) {
+      console.error(
+        `[dist:check] ${id}: distribution.lock.json is missing. Run \`${commandFor('resolve-distribution.mjs', id)}\`.`,
+      );
+      return null;
+    }
+    if (verdict === LockCheck.STALE) {
+      console.error(
+        `[dist:check] ${id}: distribution.lock.json is out of date. Run \`${commandFor('resolve-distribution.mjs', id)}\`.`,
+      );
+      return null;
+    }
+    console.log(
+      `[dist:check] ${id}: lock up to date (${fresh.biomes.length} biomes).`,
+    );
+    return index;
+  } catch (err) {
+    console.error(`[dist:check] ${id}: resolver error — ${err.message}`);
+    return null;
+  }
+}
+
+/**
+ * Check one edition's committed `authorization.lock.json` against a fresh
+ * composition by the PINNED kernel composer, over the edition's committed
+ * distribution lock. Only meaningful once that lock is green, so the caller
+ * gates on it. Returns true on green.
+ *
+ * Like `distribution.lock.json` this is a REBUILDABLE artifact — composition
+ * is deterministic over the pinned kernel and the pinned module bytes — so the
+ * whole lock is compared. The `.fga.yaml` tests are not re-run: an identical
+ * `modelHash` is the model the sealer tested.
+ */
+async function checkAuthorizationLock(id, kernel, index) {
+  const editionDir = join(editionsRoot(), id);
+  const remedy = `Run \`${commandFor('resolve-distribution.mjs', id)}\` with XEMA_FGA_CLI set.`;
+  try {
+    const lock = JSON.parse(readFileSync(join(editionDir, 'distribution.lock.json'), 'utf8'));
+    const verdict = checkEditionAuthorizationLock({
+      distributionId: id,
+      editionDir,
+      lockBiomes: lock.biomes,
+      index,
+      kernel,
+      serialize: serializeJson,
+    });
+    if (verdict === AuthorizationLockCheck.GREEN) {
+      console.log(
+        kernel === null
+          ? `[dist:check] ${id}: no authorization base (the pinned kernel ships no composer).`
+          : `[dist:check] ${id}: authorization.lock.json up to date (generation ${kernel.currentPlatformGeneration}).`,
+      );
+      return true;
+    }
+    const why = {
+      [AuthorizationLockCheck.MISSING]: 'authorization.lock.json is missing — the pinned kernel composes an authorization base for every edition.',
+      [AuthorizationLockCheck.STALE]: 'authorization.lock.json is out of date.',
+      [AuthorizationLockCheck.NOT_SEALABLE]: 'authorization.lock.json is committed, but the pinned kernel ships no composer that could reproduce it.',
+    }[verdict];
+    console.error(`[dist:check] ${id}: ${why} ${remedy}`);
+    return false;
+  } catch (err) {
+    console.error(`[dist:check] ${id}: authorization base error — ${err.message}`);
+    return false;
+  }
+}
+
+/**
+ * Structural view of an image lock: actual runtime subjects, platform bindings,
+ * and web-biome bundle inputs with the build-time `contentHash` removed. Exact
+ * repository commits remain part of the offline authority. Two locks
+ * with the same structure ship the same images and bundle the same web biomes,
+ * regardless of current source content (which the build re-hashes anyway).
+ */
+function imageStructure(lock) {
+  return serializeJson({
+    distributionId: lock.distributionId,
+    contractAuthority: lock.contractAuthority,
+    // The sealed `imageDigest` is removed FIRST, through the seal module's own
+    // view: a resolver never produces one, so a committed lock that has been
+    // sealed differs from a fresh resolve by exactly that field — and read raw
+    // it was reported "structurally out of date" with a remedy (re-resolve)
+    // that would have UNSEALED it. See `withoutSealedDigests`.
+    subjects: withoutSealedDigests(lock).subjects.map(
+      ({ contentHash: _contentHash, sourceManifestPath: _sourceManifestPath, ...rest }) => rest,
+    ),
+    webBiomes: lock.webBiomes ?? [],
+    platformServiceBindings: lock.platformServiceBindings ?? [],
+  });
+}
+
+/**
+ * Check one distribution's committed images.lock.json against the canonical
+ * image roster derived from its committed distribution lock. The default is
+ * structural; `checkSourceEvidence` additionally re-hashes trusted source
+ * trees. Returns true on green.
+ *
+ * ── THIS IS THE SEALED LOCK. IT IS NEVER COMPARED WHOLE ─────────────────────
+ *
+ * See `compareCommittedLock` above for the two classes. The consequence here
+ * is mechanical: neither comparison below reads the committed file whole.
+ * `imageStructure(...)` compares only the SHAPE (which subjects, which web
+ * biomes, which bindings), and the source-evidence pass compares
+ * `withoutSealedDigests(committed)` against a fresh resolve — the subtraction
+ * that makes the two sides describe the same thing. A `normalize(committed)
+ * === normalize(fresh)` here, which is exactly what the sibling check does and
+ * exactly what it looks like this should do, would report all 523 sealed
+ * subjects as stale on a clean tree and send the reader to re-resolve, which
+ * is the operation that destroys the seal.
+ */
+async function checkImagesLock(id, checkSourceEvidence) {
+  const imageLockPath = join(editionsRoot(), id, 'images.lock.json');
+  try {
+    const schemas = await loadKernelDistributionSchemas();
+    // A pure READ of the committed lock: the tolerant reader, never the writer.
+    const distributionLock = validateImmutableDistributionLock(
+      schemas.parseDistributionLockForReading(
+        JSON.parse(
+          readFileSync(
+            join(editionsRoot(), id, 'distribution.lock.json'),
+            'utf8',
+          ),
+        ),
+      ),
+    );
+    const runtimeSourceIndex = schemas.parseRuntimeImageSourceIndex(
+      JSON.parse(readFileSync(runtimeImageSourceIndexPath(), 'utf8')),
+    );
+    const requiredPlatforms = resolveDistributionRequiredPlatforms(schemas, id);
+    // The composed-process subjects are read from each producing repository's
+    // DECLARATION at the pinned commit — the one structural input not in the
+    // committed lock — through the same function the source resolve uses, so
+    // the two cannot disagree on which composed subjects exist.
+    const structure = resolveComposedProcessStructure(
+      distributionLock,
+      resolveImageStructure(
+        distributionLock,
+        runtimeSourceIndex,
+        schemas,
+        requiredPlatforms,
+        resolveDistributionDeclaredSources(schemas, id),
+        { biomeIndex: JSON.parse(readFileSync(biomeIndexPath(), 'utf8')) },
+      ),
+      schemas,
+      requiredPlatforms,
+    );
+    const fresh = {
+      distributionId: id,
+      contractAuthority: runtimeSourceIndex.contractAuthority,
+      ...structure,
+    };
+    if (!existsSync(imageLockPath)) {
+      console.error(
+        `[dist:check] ${id}: images.lock.json is missing. Run \`${commandFor('resolve-images.mjs', id)}\`.`,
+      );
+      return false;
+    }
+    const committed = validateImmutableImageLock(
+      schemas.parseImageLock(JSON.parse(readFileSync(imageLockPath, 'utf8'))),
+      schemas,
+    );
+    if (
+      serializeJson(committed.contractAuthority) !==
+      serializeJson(runtimeSourceIndex.contractAuthority)
+    ) {
+      console.error(
+        `[dist:check] ${id}: images.lock.json kernel contract authority does not exactly match runtime-image-source-index.json.`,
+      );
+      return false;
+    }
+    const inSync = imageStructure(committed) === imageStructure(fresh);
+    if (!inSync) {
+      console.error(
+        `[dist:check] ${id}: images.lock.json is structurally out of date ` +
+          `(server-image set or web-biome set differs from the distribution). ` +
+          `Run \`${commandFor('resolve-images.mjs', id)}\`.`,
+      );
+      return false;
+    }
+    if (checkSourceEvidence) {
+      const { imageLock: sourceResolved } = await resolveImages(id);
+      // The same subtraction as the structural view above: the source resolve
+      // carries no digest, and the committed lock may.
+      if (
+        normalize(withoutSealedDigests(committed)) !==
+        normalize(sourceResolved)
+      ) {
+        console.error(
+          `[dist:check] ${id}: images.lock.json source content hashes are out of date. ` +
+            `Run \`${commandFor('resolve-images.mjs', id)}\` only from trusted exact Git commits. ` +
+            `These hashes are source-derived tags, not OCI manifest digests.`,
+        );
+        return false;
+      }
+    }
+    console.log(
+      `[dist:check] ${id}: images lock up to date (${fresh.subjects.length} actual runtime subjects, ${fresh.webBiomes.length} web biomes` +
+        `, ${fresh.platformServiceBindings.length} platform bindings` +
+        `, ${committed.sourceHashAlgorithm}` +
+        (checkSourceEvidence ? ', source hashes verified' : '') +
+        ').',
+    );
+    return true;
+  } catch (err) {
+    console.error(`[dist:check] ${id}: image resolver error — ${err.message}`);
+    return false;
+  }
+}
+
+async function checkCommittedRuntimeImageSourceIndex(checkSources) {
+  try {
+    const schemas = await loadKernelDistributionSchemas();
+    schemas.parseRuntimeImageSourceIndex(
+      JSON.parse(readFileSync(runtimeImageSourceIndexPath(), 'utf8')),
+    );
+    execFileSync(
+      process.execPath,
+      [
+        join(HERE, 'build-runtime-image-source-index.mjs'),
+        checkSources ? '--check-sources' : '--check',
+        ...workspaceArgv(),
+      ],
+      { stdio: 'inherit' },
+    );
+    return true;
+  } catch (error) {
+    console.error(
+      `[dist:check] committed runtime-image source index FAILED: ${error.message}`,
+    );
+    return false;
+  }
+}
+
+function checkCommittedIndex() {
+  try {
+    const index = validateImmutableBiomeIndex(
+      JSON.parse(readFileSync(biomeIndexPath(), 'utf8')),
+    );
+    const sorted = [...index].sort(compareIndexEntries);
+    if (serializeJson(index) !== serializeJson(sorted)) {
+      throw new Error(
+        'entries are not in deterministic tier/id/target/repo order',
+      );
+    }
+    const keys = new Set();
+    for (const entry of index) {
+      if (!Array.isArray(entry.serviceDependencies)) {
+        throw new Error(
+          `biome "${entry.id}" has no serviceDependencies projection`,
+        );
+      }
+      const key = `${entry.id}\0${entry.target}\0${entry.repo}`;
+      if (keys.has(key)) {
+        throw new Error(
+          `duplicate immutable source identity for biome "${entry.id}" (${entry.target}, ${entry.repo})`,
+        );
+      }
+      keys.add(key);
+    }
+    console.log(
+      `[dist:check] committed biome index: green — ${index.length} immutable, deterministically ordered entries.`,
+    );
+    return true;
+  } catch (error) {
+    console.error(
+      `[dist:check] committed biome index FAILED: ${error.message}`,
+    );
+    return false;
+  }
+}
+
+async function checkCommittedPlatformServiceIndex() {
+  try {
+    const schemas = await loadKernelDistributionSchemas();
+    const index = schemas.parsePlatformServiceSourceIndex(
+      JSON.parse(readFileSync(platformServiceIndexPath(), 'utf8')),
+    );
+    validateServiceDependencyOwnerParity(
+      validateImmutableBiomeIndex(
+        JSON.parse(readFileSync(biomeIndexPath(), 'utf8')),
+      ),
+      index,
+    );
+    execFileSync(
+      process.execPath,
+      [join(HERE, 'build-platform-service-index.mjs'), '--check', ...workspaceArgv()],
+      { stdio: 'inherit' },
+    );
+    console.log(
+      `[dist:check] committed platform-service index: green — ${index.services.length} exact source identities.`,
+    );
+    return true;
+  } catch (error) {
+    console.error(
+      `[dist:check] committed platform-service index FAILED: ${error.message}`,
+    );
+    return false;
+  }
+}
+
+function discoverDistributionIds() {
+  if (!existsSync(editionsRoot())) {
+    console.error(`[dist:check] ${editionsRoot()} does not exist.`);
+    process.exit(1);
+  }
+  const ids = readdirSync(editionsRoot(), { withFileTypes: true })
+    .filter(
+      (d) =>
+        d.isDirectory() &&
+        existsSync(join(editionsRoot(), d.name, 'xema-distribution.json')),
+    )
+    .map((d) => d.name)
+    .sort();
+  if (ids.length === 0) {
+    console.error('[dist:check] no distributions found to check.');
+    process.exit(1);
+  }
+  return ids;
+}
+
+/**
+ * Guard for the capability-domain OWNERSHIP (reservation) table.
+ *
+ * This repo has no test runner (no package.json, no CI workflow of its own) —
+ * `dist:check` IS its gate — so the invariant is asserted here, where it
+ * actually runs, rather than in a spec file nothing would execute.
+ *
+ * THE INVARIANT THAT MATTERS: **every edition carries the IDENTICAL table.**
+ *
+ *   Ownership is a property of the platform, not of what an edition preloads.
+ *   An earlier design put the claim on each `LockedBiome`, which made a trimmed
+ *   edition (`minimal`, `appliance-lean`) leave `kb`/`agent`/… unowned — so an
+ *   org admin could install the owning biome from the store and THEN bind
+ *   `kb:page.read@1` to a URL they control, silently shadowing the platform
+ *   data plane. The table is now built from the FULL biome index and reserves
+ *   the domain even when its owning biome is absent from that edition — which
+ *   is exactly the case the reservation exists to cover.
+ *
+ * Also re-asserts the two structural rules, through the KERNEL's own reader:
+ *   (a) two biomes claiming the SAME domain is refused (ambiguous ownership has
+ *       no safe resolution — fail the build, never pick a winner);
+ *   (b) a domain in NO table entry is not first-party (so a claim that never
+ *       made it into a resolved, committed, drift-checked lock carries no
+ *       weight), and an invalid domain is refused rather than silently carried.
+ *
+ * @param {string[]} ids every distribution id discovered in this repo.
+ * @returns {Promise<boolean>} true when green.
+ */
+async function checkOwnershipInvariant(ids) {
+  const { resolveFirstPartyCapabilityDomains } =
+    await loadKernelDistributionSchemas();
+
+  const lockOf = (capabilityDomainOwners) => ({
+    schemaVersion: 1,
+    distributionId: 'dist-check-selftest',
+    biomes: [],
+    platformServices: [],
+    capabilityDomainOwners,
+  });
+
+  const failures = [];
+
+  // (a) collision → throws.
+  try {
+    resolveFirstPartyCapabilityDomains(
+      lockOf([
+        { domain: 'acme', biomeId: 'alpha' },
+        { domain: 'acme', biomeId: 'beta' },
+      ]),
+    );
+    failures.push(
+      'two biomes claiming the same domain "acme" did NOT throw — an ambiguous ownership claim must fail the resolve',
+    );
+  } catch (err) {
+    if (!err.message.includes('acme')) {
+      failures.push(
+        `collision threw, but the message does not name the domain: ${err.message}`,
+      );
+    }
+  }
+
+  // (b) a listed domain is first-party; an unlisted one is not.
+  const owners = resolveFirstPartyCapabilityDomains(
+    lockOf([{ domain: 'acme', biomeId: 'alpha' }]),
+  );
+  if (owners.get('acme') !== 'alpha') {
+    failures.push(
+      `a listed domain did not resolve to its owner (got ${String(owners.get('acme'))}, want "alpha")`,
+    );
+  }
+  if (resolveFirstPartyCapabilityDomains(lockOf([])).has('acme')) {
+    failures.push(
+      'a domain listed in NO table entry resolved as first-party — a claim outside the lock must carry no weight',
+    );
+  }
+
+  // (c) an invalid domain is refused rather than silently carried.
+  try {
+    resolveFirstPartyCapabilityDomains(
+      lockOf([{ domain: 'Acme!', biomeId: 'alpha' }]),
+    );
+    failures.push('an invalid capability domain "Acme!" was accepted');
+  } catch {
+    /* expected */
+  }
+
+  // (d) THE headline invariant — every committed edition carries the same,
+  //     non-empty table. An edition-specific table is the fail-open bug.
+  let reference;
+  for (const id of ids) {
+    const lockPath = join(editionsRoot(), id, 'distribution.lock.json');
+    if (!existsSync(lockPath)) {continue;}
+    const table = validateImmutableDistributionLock(
+      JSON.parse(readFileSync(lockPath, 'utf8')),
+    ).capabilityDomainOwners;
+    if (!Array.isArray(table) || table.length === 0) {
+      failures.push(
+        `distribution "${id}": capabilityDomainOwners is missing or empty — an empty reservation table means NOTHING is first-party (fail-open)`,
+      );
+      continue;
+    }
+    const serialized = serializeJson(table);
+    if (reference === undefined) {
+      reference = { id, serialized, size: table.length };
+    } else if (serialized !== reference.serialized) {
+      failures.push(
+        `distribution "${id}" carries a DIFFERENT capabilityDomainOwners table than "${reference.id}" — ` +
+          `ownership must not vary by edition, or a trimmed edition silently leaves domains org-bindable`,
+      );
+    }
+  }
+
+  if (failures.length > 0) {
+    for (const f of failures) {
+      console.error(`[dist:check] ownership-invariant FAILED: ${f}`);
+    }
+    return false;
+  }
+  console.log(
+    `[dist:check] capability-domain reservation table: green — ${reference?.size ?? 0} domains, identical across all ${ids.length} editions.`,
+  );
+  return true;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// BIOME CONFINEMENT — which editions may ship a biome whose CONTENTS must not
+// reach a customer installation.
+//
+// Two different facts, one mechanism, because the question is identical:
+// "which resolved locks may carry this biome, and what breaks if another one
+// does?" The ANSWER differs per declaration and is carried as data.
+//
+//   `licensing` holds two private keys: the Ed25519 key that signs long-lived
+//   customer licences, and the RSA key that signs registry tokens. The licence
+//   is verified OFFLINE by @xemahq/license-verifier against a CLOSED,
+//   compiled-in trust store — including on an air-gapped appliance that never
+//   reaches this service. So whoever holds the issuing key can mint any tier,
+//   unlimited seats, accepted fleet-wide, and revocation is unreachable
+//   offline.
+//
+//   `fleet-management` holds the Xema-VENDOR directory of customers and their
+//   installations — `Client`, `CustomerRepo`, `CustomerDistribution`,
+//   `CustomerImageEntitlement`, `CustomerDeployment`, `Appliance`,
+//   `ProvisioningProfile`. That is commercial operations, not the generic
+//   product model: inside a customer's own installation people are
+//   `Organization` / `Subject` / `ExternalSubject` / `Space`, and a
+//   customer-managed or offline Xema must not need our commercial inventory to
+//   function. An edition that shipped it would put every OTHER customer's name,
+//   slug, deployment targets, appliance serials and delivery grants into one
+//   customer's installation.
+//
+// WHAT ACTUALLY HOLDS THEM OUT TODAY, AND HOW THIN THAT IS
+//   `core` selects { tier: "base" }. BOTH biomes ARE tier "base", first-party,
+//   deliverable — they match core's selector on every axis but ONE:
+//   `e.audience !== 'operator'` in resolve-distribution.mjs. A single enum
+//   comparison, in a file nobody edits when they are editing an edition.
+//
+//   And an explicit { "biome": "<id>" } include is the SUPPORTED way to bypass
+//   that comparison: naming an operator biome is how you force it in. That is a
+//   one-line edit to an edition manifest which reads in review as a packaging
+//   diff and IS a key-custody — or a commercial-inventory — decision. The same
+//   shape .claude/rules/menu-audience-tiers.md forbids from the other direction
+//   — a permission derived from a packaging label — arriving here as an
+//   exposure derived from a selector.
+//
+// WHY THIS ASSERTS ON THE RESOLVED LOCK, NOT ON THE SELECTOR
+//   Because there are three ways in and only the OUTPUT sees all of them: an
+//   explicit `{ biome }` include, a widened `{ tier }`/`{ origin }` branch in
+//   the resolver, and an `audience` change in biome-index.json. A gate that
+//   read the selector would be blind to the other two.
+//
+// A comment explaining why licensing is absent from core is worth nothing
+// beside an assertion that fails when someone puts it there.
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Biomes whose contents must not reach an unadmitted installation, and the
+ * editions each is ADMITTED to. They are the data root's
+ * (`confinedBiomes` in edition-workspace.json): the library owns the rule and
+ * the schema, never which biome is confined or which edition may carry it.
+ * A data root that confines nothing declares no section and has no admissions
+ * to check. Adding an id to `admittedEditions` is the decision — make it
+ * deliberately, in its own commit, and say who agreed.
+ *
+ * `consequence` is not decoration: it is what the failure message tells the
+ * next reader is at stake, and it differs per declaration. A generic "this
+ * biome is confined" message would leave them weighing a packaging diff.
+ */
+const confinedBiomes = () => editionWorkspaceConfig().confinedBiomes ?? [];
+
+/**
+ * The decision, as a pure function so it can be exercised against synthetic
+ * input below rather than only against a tree that happens to be clean today.
+ *
+ * @param {{biomeId: string, holds: string, consequence: string, admittedEditions: readonly string[]}[]} declarations
+ * @param {Set<string>} knownBiomeIds every id biome-index.json carries
+ * @param {Map<string, string[]>} shippingByBiome biomeId -> edition ids shipping it
+ * @returns {string[]}
+ */
+function confinementFailures(declarations, knownBiomeIds, shippingByBiome, gradedEditions) {
+  const failures = [];
+  for (const decl of declarations) {
+    // POSITIVE CONTROL, and the reason this is not decoration: if the biome id
+    // ever stops resolving — a rename, a carve, a typo — every lock scan below
+    // looks for a name nothing can carry, finds nothing, and the gate passes
+    // while guarding nothing. That is the green-while-executing-nothing shape,
+    // so an unresolvable declaration is a FAILURE, never a skip.
+    if (!knownBiomeIds.has(decl.biomeId)) {
+      failures.push(
+        `confinement declaration names biome "${decl.biomeId}", which biome-index.json does not carry. ` +
+          'Either the biome was renamed — repoint this declaration — or it is genuinely gone and the ' +
+          'declaration should be deleted. It must not be left pointing at nothing: this gate would ' +
+          'then scan every lock for a name none of them can hold and pass without checking anything.',
+      );
+      continue;
+    }
+    const shipping = shippingByBiome.get(decl.biomeId) ?? [];
+    for (const edition of shipping) {
+      if (decl.admittedEditions.includes(edition)) {continue;}
+      failures.push(
+        `edition "${edition}" ships biome "${decl.biomeId}", which holds ${decl.holds}. ` +
+          `That is a CONFINEMENT decision, not a packaging one: ${decl.consequence}. ` +
+          'If this is intended, add the edition to admittedEditions in the ' +
+          '"confinedBiomes" section of edition-workspace.json in its own commit, naming who agreed.',
+      );
+    }
+    for (const edition of decl.admittedEditions) {
+      if (shipping.includes(edition)) {continue;}
+      // AN UNGRADED EDITION IS UNJUDGED, NOT STALE.
+      //
+      // `shipping` is built only from the locks this run actually READ, so
+      // "not shipping" and "not in the corpus" are the same absence here — and
+      // they have opposite meanings. Judged over a partial corpus, every
+      // admission naming an edition outside it reports as dead permission and
+      // the remedy printed is "Delete it", which would delete a live admission
+      // on the evidence of a lock the run never opened.
+      //
+      // It is not a customer-root accommodation: the same false finding fires
+      // in the vendor's own repository for any edition that is declared and not
+      // yet resolved. The corpus was always the right fence; nothing stated it
+      // while the corpus was always the full set.
+      if (!gradedEditions.has(edition)) {continue;}
+      failures.push(
+        `confinement admission "${decl.biomeId}" -> "${edition}" suppresses NOTHING: that edition does ` +
+          'not ship the biome. A standing admission for an edition that does not use it is a permission ' +
+          'nobody reviewed still sitting open. Delete it.',
+      );
+    }
+  }
+  return failures;
+}
+
+/**
+ * @param {string[]} ids every discovered distribution id
+ * @returns {boolean} true when the plane is within its declared confinement
+ */
+function checkConfinementScope(ids) {
+  const index = JSON.parse(readFileSync(biomeIndexPath(), 'utf8'));
+  const entries = Array.isArray(index) ? index : (index.biomes ?? []);
+  const knownBiomeIds = new Set(entries.map((entry) => entry?.id).filter(Boolean));
+
+  const shippingByBiome = new Map();
+  // THE LOCKS COME FROM THE EDITION CONTENT ROOT, never from `HERE`.
+  //
+  // `ids` is discovered under editionsRoot() and the locks were read from HERE,
+  // so the two agreed only while tooling and content were one directory. Point
+  // the root at a customer's `distribution/` and every `existsSync` below
+  // answered false, every id was skipped, `shippingByBiome` stayed empty — and
+  // `confinementFailures` over an empty map reports nothing. The confinement
+  // check PASSED while grading not one edition, which is worse than failing:
+  // it is the one shape that reads as protection in review.
+  let locksRead = 0;
+  /** The ids whose lock this run actually OPENED — the corpus, not the roster. */
+  const gradedEditions = new Set();
+  for (const id of ids) {
+    const lockPath = join(editionsRoot(), id, 'distribution.lock.json');
+    // A single unresolved edition is legitimate — it has a manifest and no lock
+    // yet, and the lock-currency check above is what speaks to that. ALL of them
+    // being unreadable is not, and is refused below rather than skipped.
+    if (!existsSync(lockPath)) {continue;}
+    locksRead += 1;
+    gradedEditions.add(id);
+    const lock = JSON.parse(readFileSync(lockPath, 'utf8'));
+    for (const biome of lock.biomes ?? []) {
+      const biomeId = biome?.id ?? biome?.biomeId;
+      if (!biomeId) {continue;}
+      if (!shippingByBiome.has(biomeId)) {shippingByBiome.set(biomeId, []);}
+      shippingByBiome.get(biomeId).push(id);
+    }
+  }
+
+  // The predicate, exercised against synthetic input. Without this the gate is
+  // only ever run against a tree that is already clean, which proves nothing
+  // about what it does when the tree is not.
+  const probe = [
+    { biomeId: 'probe', holds: 'a probe key', consequence: 'a probe consequence', admittedEditions: ['allowed'] },
+  ];
+  const known = new Set(['probe']);
+  const graded = new Set(['allowed', 'sneaked']);
+  const cases = [
+    [new Map([['probe', ['allowed']]]), graded, 0, 'an admitted edition is silent'],
+    [new Map([['probe', ['allowed', 'sneaked']]]), graded, 1, 'an unadmitted edition must fail'],
+    [new Map(), graded, 1, 'an admission that suppresses nothing must fail as stale'],
+    // THE CORPUS FENCE, both ways. The pair is the point: the SAME empty
+    // `shipping` is a stale admission when the edition was graded and silence
+    // when it was not. Without the second case a corpus regression is invisible,
+    // because the first one passes either way.
+    [new Map(), new Set(), 0, 'an admission for an edition OUTSIDE the corpus is unjudged, not stale'],
+    [
+      new Map([['probe', ['sneaked']]]),
+      new Set(),
+      1,
+      'confinement itself still fires on an ungraded corpus — only the STALE arm is scoped',
+    ],
+  ];
+  const selfTest = [];
+  for (const [shipping, corpus, want, why] of cases) {
+    const got = confinementFailures(probe, known, shipping, corpus).length;
+    if (got !== want) {selfTest.push(`confinement self-test: expected ${want} failure(s), got ${got} — ${why}`);}
+  }
+  if (
+    confinementFailures(
+      [{ biomeId: 'gone', holds: 'x', consequence: 'y', admittedEditions: [] }],
+      known,
+      new Map(),
+      graded,
+    ).length !== 1
+  ) {
+    selfTest.push('confinement self-test: a declaration naming an unknown biome must fail, not pass vacuously');
+  }
+  // Each declaration must name what is at stake. A blank `consequence` would
+  // still fail the right editions and would tell whoever hit it nothing, which
+  // is how an assertion becomes a speed bump.
+  for (const decl of confinedBiomes()) {
+    if (typeof decl.consequence !== 'string' || decl.consequence.trim().length < 40) {
+      selfTest.push(
+        `confinement declaration "${decl.biomeId}" carries no substantive \`consequence\`; the failure ` +
+          'message would name a rule without naming what it protects.',
+      );
+    }
+  }
+
+  // A ZERO-LOCK SCAN IS A FAILURE, not a pass. Without this the only signal that
+  // the check graded nothing is a corpus line nobody reads, and the exit code of
+  // a vacuous run is identical to the exit code of a clean one.
+  const emptyCorpus =
+    ids.length > 0 && locksRead === 0
+      ? [
+          `confinement read 0 of ${String(ids.length)} edition lock(s) under ${editionsRoot()}. ` +
+            'Nothing was graded, so this is not evidence that the plane is confined. Either the ' +
+            'editions root is wrong, or no edition in it has been resolved yet.',
+        ]
+      : [];
+
+  const failures = [
+    ...selfTest,
+    ...emptyCorpus,
+    ...confinementFailures(confinedBiomes(), knownBiomeIds, shippingByBiome, gradedEditions),
+  ];
+  if (failures.length > 0) {
+    console.error('✘ [dist-check] biome confinement:');
+    for (const failure of failures) {console.error(`   - ${failure}`);}
+    return false;
+  }
+  console.log(
+    `[dist-check] biome confinement: ${confinedBiomes().length} confined biome(s) checked against ` +
+      `${String(locksRead)} of ${String(ids.length)} edition lock(s) under ${editionsRoot()}; ` +
+      `${confinedBiomes().reduce((n, d) => n + d.admittedEditions.length, 0)} admission(s).`,
+  );
+  return true;
+}
+
+/**
+ * The verify half of the seal: every biome's `biomeContentHash` is RECOMPUTED
+ * from the manifest, the git tree at the pinned commit and the sealed image
+ * digests, and a mismatch is refused naming the biome. The kernel cannot do
+ * this ("sealed" is only a field). Returns true on green.
+ */
+async function checkBiomeContentHashes(id) {
+  try {
+    const schemas = await loadKernelDistributionSchemas();
+    const lock = schemas.parseDistributionLock(
+      JSON.parse(readFileSync(join(editionsRoot(), id, 'distribution.lock.json'), 'utf8')),
+    );
+    const imageLock = schemas.parseImageLock(
+      JSON.parse(readFileSync(join(editionsRoot(), id, 'images.lock.json'), 'utf8')),
+    );
+    const authority = createPinnedSourceAuthority({ pins: committedRepositoryPins() });
+    await verifyBiomeContentHashes({
+      schemas,
+      lock,
+      imageLock,
+      locate: sourceTreeLocator(externalSourceTrees(lock)),
+      vendoredCommit: (repo) => authority.vendoredSourceCommitForRepository(repo),
+    });
+    console.log(`[dist:check] ${id}: ${lock.biomes.length} biomeContentHash(es) recomputed from their sources.`);
+    return true;
+  } catch (err) {
+    console.error(`[dist:check] ${id}: ${err.message}`);
+    return false;
+  }
+}
+
+async function main() {
+  let failed = false;
+  // The tests spawned below resolve the editions root from THEIR OWN argv and
+  // env; a root stated here by --editions-root must reach them, or they
+  // would grade the vendor's editions under a customer's dist-check.
+  const checkSources = process.argv.includes('--check-sources');
+
+  // 0. The pinned kernel speaks an edition protocol this CLI supports. This is
+  // the ONE comparison between the CLI and the kernel; a refusal throws
+  // EditionProtocolMismatchError and stops the check before anything is read.
+  const protocol = assertKernelEditionProtocol(kernelPackageDir());
+  console.log(
+    `[dist:check] the kernel speaks edition protocol v${protocol.version} (${protocol.contentDigest}), which this CLI supports.`,
+  );
+
+  // 1. Offline committed-index validation is the default authority boundary.
+  // A live sibling-source scan is an explicit trusted regeneration audit only;
+  // CI/shared working trees must not make unrelated uncommitted sources into
+  // packaging inputs.
+  if (!checkCommittedIndex()) {failed = true;}
+  if (!(await checkCommittedPlatformServiceIndex())) {failed = true;}
+  if (!(await checkCommittedRuntimeImageSourceIndex(checkSources))) {
+    failed = true;
+  }
+  if (!(await checkEvidenceTrustPolicy())) {failed = true;}
+  if (checkSources) {
+    try {
+      execFileSync(
+        process.execPath,
+        [join(HERE, 'build-biome-index.mjs'), '--check', ...workspaceArgv()],
+        { stdio: 'inherit' },
+      );
+      execFileSync(
+        process.execPath,
+        [join(HERE, 'build-platform-service-index.mjs'), '--check-sources', ...workspaceArgv()],
+        { stdio: 'inherit' },
+      );
+    } catch {
+      failed = true;
+    }
+  }
+
+  const distributionIds = discoverDistributionIds();
+
+  if (!checkConfinementScope(distributionIds)) {failed = true;}
+
+  // 1b. Capability-domain reservation table (see checkOwnershipInvariant).
+  if (!(await checkOwnershipInvariant(distributionIds))) {failed = true;}
+
+  // The pinned kernel's authorization composer (null when the pin predates it).
+  let authorizationKernel;
+  try {
+    authorizationKernel = await loadKernelAuthorizationComposer({
+      kernelPackageDir: kernelPackageDir(),
+    });
+  } catch (err) {
+    console.error(`[dist:check] ${err.message}`);
+    failed = true;
+  }
+
+  // The fleet chart-set pin every edition must carry (edition-chart-set.mjs).
+  let chartSetPinText = null;
+  try {
+    chartSetPinText = readFileSync(fleetChartSetLockPath(), 'utf8');
+    assertRosteredChartSetLock(JSON.parse(chartSetPinText), EDITION_CHART_SET_FILE, EditionChannel.Release);
+  } catch (err) {
+    console.error(`[dist:check] chart-set pin: ${err.message}. Run \`${commandFor('resolve-chart-set.mjs')}\`.`);
+    failed = true;
+  }
+
+  // 3 + 4 + 5 + 6 + 7. Every distribution: distribution.lock, images.lock,
+  // authorization.lock, chart-set.lock.
+  for (const id of distributionIds) {
+    if (chartSetPinText !== null) {
+      const verdict = checkEditionChartSet(join(editionsRoot(), id), chartSetPinText);
+      if (verdict === EditionChartSetCheck.GREEN) {
+        console.log(`[dist:check] ${id}: ${EDITION_CHART_SET_FILE} carries the fleet chart-set pin.`);
+      } else {
+        console.error(
+          `[dist:check] ${id}: ${EDITION_CHART_SET_FILE} is ${verdict === EditionChartSetCheck.MISSING ? 'missing' : 'not the fleet pin'} — ` +
+            `an edition carries the chart generation it is rendered with. Run \`${commandFor('resolve-chart-set.mjs')}\`.`,
+        );
+        failed = true;
+      }
+    }
+    const resolutionIndex = await checkDistributionLock(id);
+    if (resolutionIndex === null) {
+      // A stale/missing distribution lock would only make the image check emit a
+      // misleading error (resolve-images reads it) — let the distribution-lock
+      // failure stand as the single actionable message for this distribution.
+      failed = true;
+      continue;
+    }
+    const imagesLockGreen = await checkImagesLock(id, checkSources);
+    if (!imagesLockGreen) {failed = true;}
+    else if (!(await checkBiomeContentHashes(id))) {failed = true;}
+    if (authorizationKernel !== undefined && !(await checkAuthorizationLock(id, authorizationKernel, resolutionIndex))) {
+      failed = true;
+    }
+  }
+
+  if (failed) {process.exit(1);}
+  console.log('[dist:check] all distributions green.');
+}
+
+main().catch((err) => {
+  console.error(`[dist:check] ${err.message}`);
+  process.exit(1);
+});