@xemahq/xema 0.26.0 → 0.27.0

package/edition/seal-image-digests.mjs

@@ -0,0 +1,855 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// seal-image-digests — write the PUBLISHED ARTIFACT's digest into the lock.
+//
+// WHY THIS EXISTS
+// ---------------
+// An `images.lock.json` subject records `contentHash`, `sourceCommit` and
+// `sourceManifestHash`. Every one of those is a BUILD INPUT. None of them names
+// the artifact that was actually produced, so the lock said what was INTENDED
+// and never what SHIPPED.
+//
+// The kernel has carried the field for this the whole time —
+// `RuntimeImageSubjectSchema.imageDigest`, optional, documented down to "this is
+// the INDEX digest, not a per-platform child" and "it belongs to the DELIVERY
+// step". Measured 2026-09-14: `imageDigest` occurs in NONE of the nine committed
+// locks and in NO .mjs in this repository. The contract was declared and the
+// producer was never built. This is the producer.
+//
+// WHAT IT COST TO BE MISSING. `chartlib.imageRef` refuses a 64-hex tag, and a
+// contentHash IS 64-hex — so with no digest to install from, NO Distribution
+// lock could render through the canonical chart library at all. Every fresh
+// customer install, every appliance and every air-gap bundle was blocked on a
+// field nothing wrote.
+//
+// IT RESOLVES NOTHING ITSELF, and that is deliberate
+// --------------------------------------------------
+// `verifyDistributionPlatforms` already fetches the index, hash-checks the bytes
+// against `Docker-Content-Digest` rather than trusting the header, walks every
+// child manifest BY DIGEST, reads each image CONFIG for its real platform, and
+// fails closed when a required platform is absent. It already returns
+// `manifestDigest` per subject and then throws it away. Re-implementing any of
+// that here would be a second resolver that can disagree with the verifier about
+// what was published — so this script performs the verification and records its
+// answer, and there is no path through it that writes a digest the verifier did
+// not prove.
+//
+// FOUR REFUSALS, none of which may be softened:
+//
+//   * A subject the verifier cannot resolve aborts the WHOLE run before
+//     anything is written. A partially sealed lock is worse than an unsealed
+//     one: it installs some services by digest and silently leaves the rest
+//     un-pinned.
+//   * A subject whose lock ALREADY carries a different `imageDigest` is a hard
+//     error, never an update. The tag is immutable by convention in this fleet;
+//     if the same contentHash now resolves to different bytes, either the tag
+//     moved or the registry is lying, and both are supply-chain incidents rather
+//     than drift to reconcile.
+//   * Nothing is invented. There is no fallback that derives a digest from the
+//     contentHash — they are different hashes of different things, and the whole
+//     defect this closes came from treating one as the other.
+//   * A run over zero subjects fails. An empty seal that reports success is the
+//     "reports green while executing nothing" shape.
+//
+// It is IDEMPOTENT: re-running against an already-sealed lock re-verifies every
+// subject, finds the same digests, and writes nothing.
+//
+//   node repos-infra/xema-distributions/seal-image-digests.mjs <distributionId>
+//   node repos-infra/xema-distributions/seal-image-digests.mjs <distributionId> --check
+//   node repos-infra/xema-distributions/seal-image-digests.mjs <distributionId> --if-published
+//   node repos-infra/xema-distributions/seal-image-digests.mjs <distributionId> --publication-verdict
+//
+// `--check` verifies and reports without writing — the CI shape, so a lock that
+// has drifted from the registry fails a pull request instead of a deploy.
+//
+// FOUR MODES, BECAUSE THEY ASK QUESTIONS AT DIFFERENT MOMENTS
+// -----------------------------------------------------------
+// The two added below exist because a lock is WRITTEN before the images it
+// names are built. `resolve-images.mjs` computes `contentHash` from git build
+// inputs, so it runs — correctly — against a registry that does not yet serve
+// the coordinate it just predicted. Sealing therefore cannot happen at lock
+// production, and a single mode cannot serve both the pass that re-pins and the
+// pass that publishes.
+//
+//   `--if-published`  RECONCILE. Seal every subject, or, if the coordinate is
+//                     not published YET, skip THE WHOLE EDITION and exit 0.
+//
+//                     This does NOT soften the partial-seal refusal above, and
+//                     the distinction is the reason it is safe: that refusal is
+//                     about writing SOME subjects of one lock. Skipping leaves
+//                     the lock ENTIRELY unsealed, which is the state the
+//                     publication gate then refuses. An edition is still all or
+//                     nothing; what changed is that "nothing" became reachable
+//                     without failing a scheduled job that re-pins every 20
+//                     minutes. Without it, every pin move reddens reconcile
+//                     fleet-wide for the interval between the pin landing and
+//                     its producers building — which is the normal case, not an
+//                     exceptional one.
+//
+//                     ONLY a 404 skips. The discriminator is `error.status`,
+//                     set by `manifestHttpError` and measured to survive
+//                     `verifyDistributionPlatforms` intact — never a match on
+//                     message text, which would silently widen the day a
+//                     registry reworded its error body. A 401, a 403, a
+//                     malformed index or an absent required platform all still
+//                     abort.
+//
+//   `--publication-verdict` PUBLICATION. Classify the lock PUBLISHABLE
+//                     (fully sealed) or WITHHELD (wholly unsealed — the resting
+//                     state a pin advance leaves, owner ruling 2026-09-29), as
+//                     ONE line on stdout, exit 0. A malformed, empty or
+//                     PARTIALLY sealed lock exits 1: a broken artifact.
+//                     OFFLINE and structural: it reads the lock and nothing
+//                     else. That is deliberate rather than a shortcut — a
+//                     publication gate that needs a registry credential can
+//                     fail for reasons that have nothing to do with the artifact
+//                     being published, and a gate people learn to re-run is a
+//                     gate that stops being read. `--check` answers the STRONGER
+//                     question (does the lock still AGREE with the registry) and
+//                     needs the network to do it; this one answers the question
+//                     publication actually turns on.
+// ─────────────────────────────────────────────────────────────────────────────
+
+import { readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { sealLock, verifyBiomeContentHashes } from './biome-content.mjs';
+import { fetchCatalogue } from './catalogue-fetch.mjs';
+import { CATALOGUE_FLAG, CATALOGUE_TOKEN_ENV_FLAG, CATALOGUE_USERNAME_FLAG } from './customer-flags.mjs';
+import { WorkspaceRoot, configureEditionWorkspaceFromProcess, editionsRoot, isEntryModule, runtimeImageSourceIndexPath } from './edition-workspace.mjs';
+import {
+  assertCoordinatesFinal,
+  collectFleetPlatformRequirements,
+  isNotFinalYet,
+  readFleetImageLocks,
+} from './fleet-coordinate-finality.mjs';
+import { loadKernelDistributionSchemas, serializeJson } from './lib.mjs';
+import { assertPlatformCanParseLock } from './platform-lock-readability.mjs';
+import { assertReleaseEditionTree } from './release-channel-guard.mjs';
+import { commandForSelf } from './remedy-command.mjs';
+import { externalSourceTrees, sourceTreeLocator } from './resolve-images.mjs';
+import { committedRepositoryPins, createPinnedSourceAuthority } from './source-authority.mjs';
+import {
+  loadImageLockForVerification,
+  verifyDistributionPlatforms,
+} from './verify-image-platforms.mjs';
+
+if (isEntryModule(import.meta.url)) {
+  configureEditionWorkspaceFromProcess([WorkspaceRoot.Data, WorkspaceRoot.Editions, WorkspaceRoot.Sources, WorkspaceRoot.Kernel, WorkspaceRoot.Cache, WorkspaceRoot.SourceHash]);
+}
+
+const SHA256_DIGEST = /^sha256:[a-f0-9]{64}$/u;
+
+// This file's own directory is the distributions root in BOTH layouts the fleet
+// runs — the aggregator's `repos-infra/xema-distributions/` and a FLAT checkout
+// of this repository alone. It is the FALLBACK only: `--editions-root` and
+// `XEMA_DISTRIBUTIONS_ROOT` still win, through the plane's own resolver, so an
+// external editions root is honoured here exactly as it is everywhere else.
+//
+// The module-level `editionsRoot()` in `lib.mjs` is deliberately NOT used: it
+// applies the resolver with a fallback that assumes the aggregator layout, and
+// measured from a flat checkout it answers a path that does not exist.
+
+/**
+ * The remedy, as a command the reader can actually run FROM WHERE THEY ARE.
+ *
+ * Built from this file's real path rather than printed as `pnpm dist:seal-digests`,
+ * because that script is declared in the AGGREGATOR's `package.json` and this
+ * repository has no `scripts` block at all — so the pnpm spelling is unrunnable
+ * in a flat checkout, which is exactly where the publication gate fails. A
+ * remedy that cannot be run where it is printed is a dead end.
+ *
+ * This was the only site in the repository that got it right, and the reasoning
+ * above is why. It now DELEGATES to `remedy-command.mjs`, which generalises it
+ * to the other ten diagnostics rather than leaving each to re-derive it.
+ */
+export function sealCommandFor(distributionId) {
+  return commandForSelf(import.meta.url, distributionId);
+}
+
+/**
+ * The lock as the RESOLVER sees it: every subject with its sealed `imageDigest`
+ * removed, everything else byte-for-byte as committed.
+ *
+ * `resolve-images.mjs` computes a lock from git build inputs and can never know
+ * the digest — the digest is what this module writes AFTER the registry has
+ * served the coordinate. So a comparison of a committed lock against a fresh
+ * resolve has to subtract exactly what the seal added, or a sealed lock reads
+ * as drifted from a resolver that is in fact in full agreement with it.
+ *
+ * Measured 2026-09-16: `dist-check.mjs` stripped `contentHash` and
+ * `sourceManifestPath` from its structural view and NOT `imageDigest`, so every
+ * lock this module had sealed (a customer edition, 63/63) was reported
+ * "structurally out of date" and the printed remedy — re-resolve — would have
+ * produced an UNSEALED lock that the publication gate then refuses. Sealing
+ * must never make the drift check red: the digest is a fact about what
+ * SHIPPED, layered over a lock whose structure and hashes it does not touch.
+ *
+ * Pure, and owned HERE rather than in the checker because this is the module
+ * that decides what a seal writes; a second list of "fields the seal adds" in
+ * `dist-check.mjs` is the pair that can only agree by hand.
+ */
+export function withoutSealedDigests(lock) {
+  return {
+    ...lock,
+    subjects: (lock.subjects ?? []).map(
+      ({ imageDigest: _imageDigest, ...subject }) => subject,
+    ),
+  };
+}
+
+/**
+ * Pure: decide what each subject's `imageDigest` should become.
+ *
+ * Separated from the I/O so the decision table is testable without a registry,
+ * and so the refusals are assertable rather than reachable only through a
+ * network round trip.
+ */
+export function planDigestSeal({ subjects, verified }) {
+  if (!Array.isArray(subjects) || subjects.length === 0) {
+    throw new Error(
+      'seal-image-digests: the lock declares no subjects; sealing nothing and ' +
+        'reporting success would be a verification that executed nothing',
+    );
+  }
+  const byId = new Map(
+    verified.map((entry) => [`${entry.subjectKind}:${entry.subjectId}`, entry]),
+  );
+  const writes = [];
+  const unchanged = [];
+  for (const subject of subjects) {
+    const key = `${subject.kind}:${subject.id}`;
+    const entry = byId.get(key);
+    if (!entry) {
+      throw new Error(
+        `seal-image-digests: ${key} has no verification result; refusing to seal a ` +
+          'lock the verifier did not fully cover',
+      );
+    }
+    const digest = entry.manifestDigest;
+    if (typeof digest !== 'string' || !SHA256_DIGEST.test(digest)) {
+      throw new Error(
+        `seal-image-digests: ${key} resolved to "${digest}", which is not a canonical ` +
+          'sha256 digest',
+      );
+    }
+    if (subject.imageDigest === digest) {
+      unchanged.push({ key, digest });
+      continue;
+    }
+    if (typeof subject.imageDigest === 'string' && subject.imageDigest.length > 0) {
+      throw new Error(
+        `seal-image-digests: ${key} is already sealed at ${subject.imageDigest} but ` +
+          `${entry.coordinate} now resolves to ${digest}. The tag MOVED, or the registry ` +
+          'is serving different bytes for the same coordinate. This is not drift to ' +
+          'reconcile — nothing is rewritten, and the cause must be established first.',
+      );
+    }
+    writes.push({ key, digest, coordinate: entry.coordinate });
+  }
+  return { writes, unchanged };
+}
+
+/** The two RESTING STATES a lock may be published from — or withheld in. */
+export const PublicationVerdict = Object.freeze({
+  Publishable: 'PUBLISHABLE',
+  Withheld: 'WITHHELD',
+});
+
+/**
+ * Pure: is this lock PUBLISHABLE, WITHHELD, or BROKEN?
+ *
+ * The publication gate. OFFLINE — it reads the parsed lock and nothing else — so
+ * it cannot fail for a reason unrelated to the artifact being published, and
+ * cannot be re-run into passing.
+ *
+ * THREE ANSWERS, NOT TWO. Owner ruling 2026-09-29: an unsealed lock blocks
+ * PUBLICATION and nothing else. A pin advance is committed UNSEALED — the
+ * resolver strips every `imageDigest` when it re-pins — and only the edition
+ * that must publish is sealed. So a wholly unsealed lock is a RESTING STATE of
+ * `main`, not a defect, and it gets the npm release lane's shape: the edition is
+ * WITHHELD, said out loud, and nothing is uploaded for it. It is never
+ * published, because an unsealed lock addresses its images by a MUTABLE tag and
+ * `chartlib.imageRef` refuses a bare 64-hex contentHash in the tag slot, so it
+ * could not be installed by the canonical chart library at all.
+ *
+ * What still THROWS is a lock no resting state produces — a BROKEN artifact:
+ *
+ *   * NO SUBJECTS — a gate passing over an empty roster has verified nothing;
+ *   * a NON-CANONICAL digest — a bare 64-hex contentHash laundered into the
+ *     digest slot, an uppercased or truncated one;
+ *   * a PARTIAL seal — some subjects carry a digest and others do not. The
+ *     sealer refuses to write one (it seals all or nothing) and the resolver
+ *     strips all or nothing, so no correct path produces it. It would install
+ *     some services by digest and silently leave the rest un-pinned.
+ *
+ * IT CHECKS SHAPE AS WELL AS PRESENCE. This gate reads the lock with
+ * `JSON.parse` because the publication workflow checks out this repository
+ * ALONE, with no built kernel to parse through, so the kernel's digest regex is
+ * not upstream of it and this file's own `SHA256_DIGEST` is the only rule on
+ * this path.
+ */
+export function classifyPublicationState({
+  distributionId,
+  subjects,
+  remedy = sealCommandFor(distributionId),
+}) {
+  if (!Array.isArray(subjects) || subjects.length === 0) {
+    throw new Error(
+      `seal-image-digests: "${distributionId}" declares no subjects; a publication gate ` +
+        'that passes over an empty roster has verified nothing',
+    );
+  }
+  // MALFORMED is reported before anything else: one verdict, not a cascade.
+  const malformed = subjects
+    .filter(
+      (subject) =>
+        typeof subject.imageDigest === 'string' &&
+        subject.imageDigest.length > 0 &&
+        !SHA256_DIGEST.test(subject.imageDigest),
+    )
+    .map((subject) => `${subject.kind}:${subject.id}=${subject.imageDigest}`);
+  if (malformed.length > 0) {
+    throw new Error(
+      `seal-image-digests: "${distributionId}" carries ${malformed.length} NON-CANONICAL ` +
+        `imageDigest value(s): ${malformed.slice(0, 4).join(', ')}. A digest is ` +
+        '`sha256:` followed by 64 lowercase hex characters. A BARE 64-hex value is a ' +
+        "contentHash — a hash of BUILD INPUTS, not of the artifact — and `chartlib.imageRef` " +
+        'refuses it in the tag slot for exactly this reason. Refusing to publish.',
+    );
+  }
+  const unsealed = subjects
+    .filter((subject) => typeof subject.imageDigest !== 'string' || subject.imageDigest.length === 0)
+    .map((subject) => `${subject.kind}:${subject.id}`);
+  if (unsealed.length === 0) {
+    return {
+      verdict: PublicationVerdict.Publishable,
+      distributionId,
+      subjectCount: subjects.length,
+      unsealedCount: 0,
+    };
+  }
+  if (unsealed.length < subjects.length) {
+    throw new Error(
+      `seal-image-digests: "${distributionId}" is PARTIALLY sealed — ${unsealed.length} of ` +
+        `${subjects.length} subject(s) carry no imageDigest: ${unsealed.slice(0, 8).join(', ')}` +
+        `${unsealed.length > 8 ? `, and ${unsealed.length - 8} more` : ''}. ` +
+        'No correct path produces this: the sealer writes all or nothing and the resolver ' +
+        'strips all or nothing. It would install some services by digest and silently ' +
+        'leave the rest un-pinned. This is a broken artifact, not a resting state; ' +
+        `refusing to publish. Re-seal the whole edition:\n    ${remedy}`,
+    );
+  }
+  return {
+    verdict: PublicationVerdict.Withheld,
+    distributionId,
+    subjectCount: subjects.length,
+    unsealedCount: unsealed.length,
+    remedy,
+  };
+}
+
+/**
+ * Is this failure "the coordinate is not published YET"?
+ *
+ * `manifestHttpError` stamps `error.status` from the HTTP response, and that
+ * property was measured surviving `verifyDistributionPlatforms` intact against
+ * the live registry (a fabricated tag on a real repository returns
+ * `status === 404`, body `MANIFEST_UNKNOWN`). Matching the MESSAGE instead would
+ * widen silently the day ghcr rewords its error body — and widening this
+ * predicate turns a hard failure into a skip, which is the one direction that
+ * must never happen by accident.
+ */
+export function isNotPublishedYet(error) {
+  return Boolean(error) && error.status === 404;
+}
+
+/**
+ * Pure: split argv into the mode flags and the ONE positional distribution id.
+ *
+ * WHY THIS EXISTS AS A FUNCTION
+ * -----------------------------
+ * The previous form was `args.filter((a) => !FLAGS.has(a))` over a set holding
+ * only the three MODE flags, and everything surviving that filter was treated as
+ * positional. `--editions-root <path>` therefore contributed TWO unexpected
+ * positionals and the usage error fired — so the editions-root flag was
+ * REJECTED by the very script that threads argv into the resolver
+ * (`editionsRoot()` below passes `args` to `resolveEditionsRootWithSource`,
+ * which reads exactly this flag).
+ *
+ * That is the "written and never wired" shape pointed at a CLI: the capability
+ * was reachable in code and unreachable from the command line, while
+ * `XEMA_DISTRIBUTIONS_ROOT` — the env half of the same precedence chain — worked.
+ * A customer edition resolved from a root this repository does not own is the
+ * case the flag exists for, and it is exactly the case that could not be spelled.
+ *
+ * The flag NAME is imported from `lib.mjs` rather than restated here, so this
+ * parser cannot drift from the resolver that consumes it.
+ *
+ * VALUE HANDLING IS DELIBERATELY NOT DUPLICATED. The space form's value is
+ * skipped without being validated, because `resolveEditionsRootWithSource`
+ * already refuses a missing value, an empty one, and one that swallows the next
+ * flag. Re-checking here would be a second implementation of a rule that owns
+ * itself — and the two could disagree about which is authoritative.
+ */
+export function parseSealArgs(args) {
+  const MODES = new Set(['--check', '--if-published', '--publication-verdict']);
+  const CATALOGUE_VALUE_FLAGS = new Set([CATALOGUE_FLAG, CATALOGUE_USERNAME_FLAG, CATALOGUE_TOKEN_ENV_FLAG]);
+  const positional = [];
+  const catalogueFlags = new Map();
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (MODES.has(arg)) {continue;}
+    if (CATALOGUE_VALUE_FLAGS.has(arg)) {
+      if (args[i + 1] === undefined || args[i + 1].startsWith('--')) {throw new Error(`${arg} takes a value`);}
+      catalogueFlags.set(arg, args[i + 1]);
+      i += 1;
+      continue;
+    }
+    positional.push(arg);
+  }
+  const [distributionId, ...rest] = positional;
+  return {
+    catalogueFlags,
+    distributionId,
+    rest,
+    check: args.includes('--check'),
+    ifPublished: args.includes('--if-published'),
+    publicationVerdict: args.includes('--publication-verdict'),
+  };
+}
+
+/** Where a lock is staged before it replaces `path`: beside it, so the rename never crosses a filesystem. */
+export const sealStagingPath = (path) => `${path}.sealing`;
+
+/**
+ * Replace the locks of one seal together. Every document is first written to its
+ * staging file; only when all of them are on disk is each renamed over its lock,
+ * in the order given. A failure while staging removes what was staged and leaves
+ * every committed lock byte-identical.
+ */
+function replaceLocksTogether(documents) {
+  const staged = [];
+  try {
+    for (const { path, text } of documents) {
+      writeFileSync(sealStagingPath(path), text);
+      staged.push(path);
+    }
+  } catch (error) {
+    for (const path of staged) {rmSync(sealStagingPath(path), { force: true });}
+    throw error;
+  }
+  for (const { path } of documents) {renameSync(sealStagingPath(path), path);}
+}
+
+/**
+ * The seal of one edition's two locks, as ONE write.
+ *
+ * `digests` (`kind:id` -> registry digest) are the image digests this run seals
+ * into the images lock. Each biome's `biomeContentHash` is then RECOMPUTED from
+ * its sources over that sealed images lock, and the unsealed distribution lock
+ * the resolver wrote is turned into the v5 lock by the kernel's
+ * `sealDistributionLock`. A distribution lock that is already sealed is VERIFIED
+ * instead: every hash is recomputed and a mismatch is refused, naming the biome.
+ *
+ * Nothing is written until both documents exist in memory, and the distribution
+ * lock is renamed LAST: a seal that fails for any reason before that leaves the
+ * committed pair as it was, and the one state a crash between the two renames
+ * can leave (images sealed, distribution unsealed) is refused by every reader of
+ * a sealed edition.
+ */
+export async function sealEditionLocks({ distributionId, root, digests = new Map(), check = false, label = 'dist:seal-digests', vendoredCommit, catalogue, catalogueDigest }) {
+  const schemas = await loadKernelDistributionSchemas();
+  const lockPath = join(root, distributionId, 'distribution.lock.json');
+  const imagesPath = join(root, distributionId, 'images.lock.json');
+  // The file is re-read rather than the PARSED lock re-serialised: the parse is a
+  // validation, not a round-trip, and writing back a schema-normalised document
+  // would silently reformat or drop anything the parser does not model.
+  const rawImages = JSON.parse(readFileSync(imagesPath, 'utf8'));
+  let applied = 0;
+  for (const subject of rawImages.subjects) {
+    const digest = digests.get(`${subject.kind}:${subject.id}`);
+    if (digest) {
+      subject.imageDigest = digest;
+      applied += 1;
+    }
+  }
+  if (applied !== digests.size) {
+    throw new Error(
+      `seal-image-digests: planned ${digests.size} writes but matched ${applied} subjects ` +
+        'in the file on disk; nothing written',
+    );
+  }
+  const raw = JSON.parse(readFileSync(lockPath, 'utf8'));
+  const imageLock = schemas.parseImageLock(rawImages);
+  const pinned = vendoredCommit ?? ((repo) => createPinnedSourceAuthority({ pins: committedRepositoryPins() }).vendoredSourceCommitForRepository(repo));
+  const lockDocument = raw !== null && typeof raw === 'object' && 'unsealedSchema' in raw ? schemas.parseUnsealedDistributionLock(raw) : schemas.parseDistributionLock(raw);
+  const result = await sealOrVerifyLock({
+    schemas,
+    lock: lockDocument,
+    imageLock,
+    locate: sourceTreeLocator(externalSourceTrees(lockDocument)),
+    vendoredCommit: pinned,
+    catalogue,
+    catalogueDigest,
+    check,
+    lockPath,
+  });
+  replaceLocksTogether([
+    ...(applied > 0 ? [{ path: imagesPath, text: `${JSON.stringify(rawImages, null, 2)}\n` }] : []),
+    ...(result.sealed ? [{ path: lockPath, text: serializeJson(result.lock) }] : []),
+  ]);
+  if (applied > 0) {console.log(`[${label}] sealed ${applied} subject(s) into ${imagesPath}.`);}
+  if (result.sealed) {
+    console.log(`[${label}] sealed ${result.lock.biomes.length} biomeContentHash(es) into ${lockPath}.`);
+  } else {
+    console.log(`[${label}] ${result.lock.biomes.length} biomeContentHash(es) recomputed from their inputs and agree with ${lockPath}.`);
+  }
+  return result.lock;
+}
+
+/**
+ * The decision, with no files: an UNSEALED lock is sealed (refused under `check`); a SEALED lock is VERIFIED -
+ * every hash recomputed, a mismatch refused naming the biome.
+ */
+export async function sealOrVerifyLock({ schemas, lock, imageLock, locate, vendoredCommit, catalogue, catalogueDigest, check = false, lockPath = 'distribution.lock.json' }) {
+  if ('unsealedSchema' in lock) {
+    if (check) {
+      throw new Error(`${lockPath} is unsealed (no biomeContentHash); run \`xema edition seal ${lock.distributionId}\``);
+    }
+    return { sealed: true, lock: await sealLock({ schemas, unsealed: lock, imageLock, locate, vendoredCommit, catalogue, catalogueDigest }) };
+  }
+  await verifyBiomeContentHashes({ schemas, lock, imageLock, locate, vendoredCommit, catalogue, catalogueDigest });
+  return { sealed: false, lock };
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  const { distributionId, rest, check, ifPublished, publicationVerdict, catalogueFlags } =
+    parseSealArgs(args);
+  if (!distributionId || rest.length > 0) {
+    throw new Error(
+      'usage: xema edition seal <distributionId> ' +
+        `[--check | --if-published | --publication-verdict] ` +
+        `[--catalogue oci://<repository>@sha256:<digest> [--catalogue-username <name> --catalogue-token-env <VAR>]]`,
+    );
+  }
+  // The modes answer different questions and combining them would make the
+  // verdict depend on precedence nobody declared.
+  const selected = [check, ifPublished, publicationVerdict].filter(Boolean).length;
+  if (selected > 1) {
+    throw new Error(
+      'seal-image-digests: --check, --if-published and --publication-verdict are mutually exclusive',
+    );
+  }
+
+  // PUBLICATION GATE — offline and structural. It returns BEFORE any call that
+  // would load the built kernel contracts, so it needs no sibling repository, no
+  // credential and no `node_modules`.
+  //
+  // The distinction is the IMPORT versus the CALL, and getting it wrong once
+  // cost a needless refactor: importing `verify-image-platforms.mjs`,
+  // `oras.mjs` and `lib.mjs` is all FINE without a kernel —
+  // measured, all three load in a flat checkout — because
+  // `loadKernelDistributionSchemas()` is invoked at USE time, not at module
+  // load. What fails in the publication checkout is CALLING
+  // `loadImageLockForVerification`. So the fix is to not call it, which is what
+  // this early return does; making the imports dynamic bought nothing and was
+  // reverted.
+  // EVERY mode, the offline publication verdict included: a release edition
+  // never carries develop content, whatever the sealer is asked to do with it.
+  assertReleaseEditionTree(join(editionsRoot(), distributionId));
+
+  if (publicationVerdict) {
+    const lockPath = join(editionsRoot(), distributionId, 'images.lock.json');
+    const raw = JSON.parse(readFileSync(lockPath, 'utf8'));
+    const state = classifyPublicationState({
+      distributionId,
+      subjects: raw.subjects,
+    });
+    // STDOUT CARRIES EXACTLY ONE MACHINE LINE, and nothing else. The publish
+    // loop branches on it, and accepts only these two shapes: anything else —
+    // including an empty stdout from a crash — is a failure there, never a
+    // withhold. The human explanation goes to stderr.
+    if (state.verdict === PublicationVerdict.Publishable) {
+      console.error(
+        `[dist:seal-digests --publication-verdict] "${distributionId}": all ` +
+          `${state.subjectCount} subject(s) carry a canonical imageDigest; publishable. ` +
+          `(${lockPath})`,
+      );
+      console.log(`${state.verdict} ${distributionId} ${state.subjectCount}`);
+      return;
+    }
+    console.error(
+      `[dist:seal-digests --publication-verdict] "${distributionId}": WITHHELD — all ` +
+        `${state.unsealedCount} subject(s) are unsealed. This is a resting state (owner ` +
+        'ruling 2026-09-29: an unsealed lock blocks PUBLICATION and nothing else), so ' +
+        'nothing is uploaded for it. To publish it, seal it once its producers have ' +
+        `built:\n    ${state.remedy}`,
+    );
+    console.log(
+      `${state.verdict} ${distributionId} ${state.unsealedCount} ${state.subjectCount}`,
+    );
+    return;
+  }
+
+  // THE ROOT MUST REACH THE READ, NOT ONLY THE WRITE.
+  //
+  // `loadImageLockForVerification` takes `(distributionId, distributionsRoot =
+  // dataRoot())`. Called with one argument it silently read the DEFAULT
+  // root while the write below used `editionsRoot()` — so with an external
+  // root configured, this script verified ONE lock and would have sealed the
+  // digests it proved into a DIFFERENT one. It failed safe only when the id was
+  // absent from the default root (ENOENT); an edition present in BOTH roots
+  // would have been sealed from the wrong verification, silently.
+  //
+  // That fix reached the LOCK read and NOT the sibling seven lines below it,
+  // and the sentence that used to stand here — "one root, resolved once, used
+  // by every path in this function" — was the reason: a reader confirms it
+  // against the call it is standing next to and stops. `verifyDistributionPlatforms`
+  // defaults `distributionsRoot` to `dataRoot()`, so the REGISTRY
+  // CREDENTIALS were still read out of this repository while the lock came from
+  // the configured root.
+  //
+  // The two halves fail with OPPOSITE loudness, which is why only the quiet one
+  // survived: a lock read against the wrong root is an ENOENT, and a credential
+  // read against the wrong root simply authenticates against a different
+  // declaration file and proceeds. A customer root declaring its own registry
+  // authority would have been verified with the vendor's declarations.
+  //
+  // Both reads now take `root`. Asserted BEHAVIOURALLY in
+  // `seal-image-digests.test.mjs` — the external root declares a sentinel
+  // `authTokenEnv` and the test reads which variable the refusal names, because
+  // no structural check can tell a threaded argument from an omitted one.
+  const root = editionsRoot();
+  // CUSTOMER MODE: the digest-pinned catalogue the edition was resolved against.
+  // Its vendor biomes' tree ids are inputs on ITS authority (biome-content.mjs).
+  const fetched =
+    catalogueFlags.has(CATALOGUE_FLAG)
+      ? await fetchCatalogue({
+          ref: catalogueFlags.get(CATALOGUE_FLAG),
+          username: catalogueFlags.get(CATALOGUE_USERNAME_FLAG),
+          tokenEnv: catalogueFlags.get(CATALOGUE_TOKEN_ENV_FLAG),
+        })
+      : undefined;
+  const catalogue = fetched?.catalogue;
+  const catalogueDigest = fetched?.digest;
+  const imageLock = await loadImageLockForVerification(distributionId, root);
+
+  // Throws on ANY unresolvable subject or missing required platform, before a
+  // single byte of the lock is touched.
+  let report;
+  try {
+    report = await verifyDistributionPlatforms({ imageLock, distributionsRoot: root });
+  } catch (error) {
+    // RECONCILE: a coordinate this pass just re-pinned has not been built yet.
+    // Skip the EDITION — never some of its subjects — and leave the lock
+    // entirely unsealed for the publication gate to refuse.
+    if (ifPublished && isNotPublishedYet(error)) {
+      console.log(
+        `[dist:seal-digests --if-published] "${distributionId}": not published yet — ` +
+          `${error.message.split('\n')[0]}`,
+      );
+      console.log(
+        `[dist:seal-digests --if-published] skipping this edition ENTIRELY and writing ` +
+          'nothing. It stays unsealed, and publication refuses an unsealed lock, so ' +
+          'nothing installable is produced from it until its producers have built.',
+      );
+      return;
+    }
+    throw error;
+  }
+
+  // ── BEFORE ANY DIGEST IS WRITTEN ───────────────────────────────────────────
+  //
+  // Can the images of this edition READ the lock it is about to be sealed
+  // against? The plane resolves with the contracts build in
+  // `repos/xema-kernel-contracts`, which runs ahead of what ships, and
+  // `DistributionLockSchema` is `.strict()` — so a key the plane knows and a
+  // pinned repository does not makes the whole artifact unreadable AT BOOT.
+  // That is not hypothetical: on 2026-09-17 `imageNamePrefix` did exactly this
+  // to three presenca-dev services at once, and the edition had sealed,
+  // published and installed perfectly first.
+  //
+  // It is asked of every pinned repository that SHIPS AN IMAGE INTO THIS
+  // EDITION and PARSES A LOCK — never of `repos/xema-base` alone, which
+  // declares the NEWEST range in the fleet and is therefore the weakest
+  // possible subject, and never of every pin, which grades repositories the
+  // edition's lock cannot reach. Both narrowings are DERIVED (from this
+  // edition's `images.lock.json` and from the pinned commit's own source);
+  // see `platform-lock-readability.mjs` for the measurement behind each.
+  //
+  // WHY HERE AND NOT BEFORE `verifyDistributionPlatforms`, which is where the
+  // original of this call sat. Three placements were available and only this
+  // one is correct today:
+  //
+  //   • before the lock read — `--publication-verdict` returns above it, and that
+  //     gate must stay offline and structural. It would also need a sibling
+  //     repository and the registry to answer a question about publication.
+  //   • before the verify — an edition whose coordinates are NOT PUBLISHED YET
+  //     is the ORDINARY daily outcome, and `--if-published` skips it in the
+  //     catch below. Asking first would make an edition nothing is about to
+  //     seal fail HARD on a readability question, and would pay the npm cost
+  //     for every skipped edition.
+  //   • HERE — after the skip, before `planDigestSeal` and therefore before any
+  //     write, so it runs exactly for the editions a digest is about to be
+  //     written into, and for `--check`, which is a verification mode and
+  //     should answer it.
+  //
+  // `runtimeImageSourceIndexPath()` is THIS repository's file rather than the
+  // editions root's, and deliberately: the pins are a fact about the vendor
+  // plane that BUILT the images, not about whose editions are being sealed.
+  // Every other consumer of the index (`dist-check.mjs`, `resolve-images.mjs`)
+  // reads it the same way.
+  //
+  // `imageLock` is THE EDITION'S OWN, already loaded above from `root`, and it
+  // is what narrows the question from the fleet to this edition: the pin index
+  // is fleet-wide, so grading every pin refuses a seal over a repository that
+  // ships nothing here. Measured 2026-09-27, that is not hypothetical — it
+  // blocked a customer-edition seal on `repos/xema-operator`, which has
+  // ZERO subjects in that edition.
+  // ── THE TWO LOCKS READ HERE ARE DIFFERENT CLASSES ────────────────────────
+  //
+  // `distribution.lock.json` is REBUILDABLE — a fresh resolve reproduces it,
+  // and zero of the 9 committed ones carries a digest. `imageLock` is SEALED:
+  // 523 of 523 subjects across those 9 editions carry an `imageDigest` that
+  // THIS script wrote, and `resolve-images.mjs` emits none, so re-resolving it
+  // DISCARDS them rather than recomputing them. They appear as two arguments
+  // to one call, which is exactly the shape that invites treating them alike;
+  // `dist-check.mjs`'s `compareCommittedLock` carries the full statement of
+  // the split, at its own read.
+  //
+  // The practical rule for anything added below: the distribution lock may be
+  // regenerated to answer a question; the image lock may not.
+  await assertPlatformCanParseLock({
+    lock: JSON.parse(
+      readFileSync(join(root, distributionId, 'distribution.lock.json'), 'utf8'),
+    ),
+    imageLock,
+    distributionId,
+    runtimeSourceIndex: JSON.parse(
+      readFileSync(runtimeImageSourceIndexPath(), 'utf8'),
+    ),
+  });
+
+  const { writes, unchanged } = planDigestSeal({
+    subjects: imageLock.subjects,
+    verified: report.subjects,
+  });
+
+  const label = check ? 'dist:seal-digests --check' : 'dist:seal-digests';
+  console.log(
+    `[${label}] "${distributionId}": ${report.subjectCount} subjects verified against ` +
+      `${report.registries.join(', ')}; ${unchanged.length} already sealed, ${writes.length} to seal.`,
+  );
+  for (const w of writes) {console.log(`    seal ${w.key} ${w.coordinate} -> ${w.digest}`);}
+
+  if (writes.length === 0) {
+    console.log(`[${label}] lock is fully sealed and agrees with the registry.`);
+    await sealEditionLocks({ distributionId, root, check, label, catalogue, catalogueDigest });
+    return;
+  }
+
+  // ── FLEET-SCOPED FINALITY ──────────────────────────────────────────────────
+  //
+  // Everything above this point is PER-EDITION and passed. That is exactly the
+  // state `xema-internal` was in at 09:25 on 2026-09-18, when it was sealed
+  // against 40 coordinates that were still amd64-only and whose arm64
+  // supplement then moved 63 of its 66 digests.
+  //
+  // A seal pins what a MUTABLE tag resolves to, so it is stable only once the
+  // coordinate is FINAL — and finality is a property of the FLEET, because the
+  // edition that can still supplement the coordinate is a DIFFERENT one. Asked
+  // here, over `writes`, because this is the moment the regression is
+  // introduced and the repository holding every edition's lock is where the
+  // question is answerable at all.
+  const { editions, withoutLock } = readFleetImageLocks(root);
+  const fleetRequirements = collectFleetPlatformRequirements({ editions });
+  try {
+    const finality = assertCoordinatesFinal({
+      distributionId,
+      writes,
+      verified: report.subjects,
+      fleetRequirements,
+    });
+    // The CORPUS, not a confirmation: how many coordinates were graded against
+    // how many editions, and which editions made no claim. Without the
+    // denominators a pass cannot be told from a pass over nothing, and the
+    // editions root is printed because it BOUNDS the fleet this answer is about.
+    console.log(
+      `[${label}] finality: ${finality.coordinateCount} coordinate(s) graded against ` +
+        `${editions.length} edition(s) under ${root}` +
+        (withoutLock.length > 0
+          ? ` (${withoutLock.length} declared no image lock: ${withoutLock.join(', ')})`
+          : '') +
+        `; ${finality.coordinateCount - finality.pendingElsewhere.length} final for every ` +
+        `edition, ${finality.pendingElsewhere.length} final for this edition's own platforms only.`,
+    );
+    // THE ACCEPTED RESIDUAL, recorded one line per coordinate (owner ruling
+    // 2026-09-29): another edition still awaits a platform THIS edition does not
+    // declare, so a later supplement may move the tag. This seal keeps pinning
+    // the manifest it verified, which serves every platform this edition needs.
+    for (const pending of finality.pendingElsewhere) {
+      console.log(
+        `[${label}] RECORDED: ${pending.key} ${pending.coordinate} — ` +
+          pending.unmet
+            .map((u) => `${u.platform} pending for ${u.requiredBy.join(', ')}`)
+            .join('; ') +
+          `; not required by "${distributionId}" (serves: ${pending.served.join(', ') || 'nothing'}).`,
+      );
+    }
+  } catch (error) {
+    // RECONCILE: another edition is still awaiting a platform here. That is the
+    // ORDINARY transient state while a supplement builds — the same shape as
+    // "not published yet", and treated the same way for the same reason: a
+    // daily job that reddens for a state nobody can act on today is one people
+    // learn to bypass. The edition is skipped WHOLE and stays unsealed, so the
+    // publication gate still refuses to ship it.
+    if (ifPublished && isNotFinalYet(error)) {
+      console.log(`[dist:seal-digests --if-published] ${error.message}`);
+      console.log(
+        `[dist:seal-digests --if-published] skipping this edition ENTIRELY and writing ` +
+          'nothing. It stays unsealed, and publication refuses an unsealed lock.',
+      );
+      return;
+    }
+    throw error;
+  }
+
+  if (check) {
+    throw new Error(
+      `${writes.length} subject(s) carry no imageDigest. Run without --check to seal them. ` +
+        'An unsealed lock cannot be installed by digest, and a tag-based install is ' +
+        'mutable lookup in the production path.',
+    );
+  }
+
+  await sealEditionLocks({
+    distributionId,
+    root,
+    digests: new Map(writes.map((w) => [w.key, w.digest])),
+    check,
+    label,
+    catalogue,
+    catalogueDigest,
+  });
+}
+
+if (isEntryModule(import.meta.url)) {
+  main().catch((error) => {
+    console.error(`[dist:seal-digests] ${error.message}`);
+    // The footer is MODE-AWARE. Pointing a reader at a registry credential when
+    // the gate that just failed never opens a socket is a remedy for the wrong
+    // problem, and a wrong remedy costs more than no remedy.
+    const offline = process.argv.includes('--publication-verdict');
+    console.error(
+      offline
+        ? '[dist:seal-digests] fail-closed: this gate is OFFLINE — it read the lock and ' +
+            'nothing else, so no credential, network or registry state is involved in ' +
+            'the verdict above.'
+        : '[dist:seal-digests] fail-closed: no digest above was assumed, and a partial ' +
+            'seal is never written. Registry credentials are declared in ' +
+            'image-registry-credentials.json.',
+    );
+    process.exit(1);
+  });
+}