@xemahq/xema 0.59.1 → 0.60.1

package/edition/seal-image-digests.mjs

@@ -1,954 +0,0 @@
-// ─────────────────────────────────────────────────────────────────────────────
-// 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 locks and nothing
-//                     else (the distribution lock through the built kernel,
-//                     `--kernel`, only when the images lock is PUBLISHABLE). 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 { adapterHostRow, assertAdapterBundlesMatchHost, fetchRegistryManifest, lockMountsAdapters } from './adapter-bundled-versions.mjs';
-import { sealLock, verifyBiomeContentHashes } from './biome-content.mjs';
-import { fetchCatalogue } from './catalogue-fetch.mjs';
-import { readCataloguePin } from './catalogue-pin.mjs';
-import { parseCustomerDefinition } from './customer-definition.mjs';
-import { CATALOGUE_TOKEN_ENV_FLAG, CATALOGUE_USERNAME_FLAG, DEFINITION_FLAG } from './customer-flags.mjs';
-import { EditionChannel } from './edition-constants.mjs';
-import { editionPinnedInputs } from './edition-pinned-inputs.mjs';
-import { WorkspaceRoot, biomeIndexPath, configureEditionWorkspaceFromProcess, dataRoot, editionsRoot, isEntryModule, runtimeImageSourceIndexPath } from './edition-workspace.mjs';
-import {
-  assertCoordinatesFinal,
-  collectFleetPlatformRequirements,
-  isNotFinalYet,
-  readFleetImageLocks,
-} from './fleet-coordinate-finality.mjs';
-import { imageSubjectIdentity } from './image-subject-identity.mjs';
-import { adoptCatalogueKernel } from './kernel-package.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 { readSealedDistributionLock } from './sealed-distribution-lock.mjs';
-import { committedRepositoryPins, createPinnedSourceAuthority } from './source-authority.mjs';
-import { readStrictJsonFile } from './strict-json.mjs';
-import { pinnedManifestDigests, thirdPartyImagePins } from './third-party-image-pins.mjs';
-import { loadTrustedThirdPartySourcePins } from './third-party-pins-trusted.mjs';
-import {
-  loadImageLockForVerification,
-  verifyDistributionPlatforms,
-} from './verify-image-platforms.mjs';
-
-if (isEntryModule(import.meta.url)) {
-  // The customer form (it names --definition) reads exactly these roots - the data root (the vendor's
-  // runtime-image-source-index.json), the editions root, the sources root (the readability check of the
-  // vendor repositories) and the cache (external source trees, and the catalogue's kernel from npm) - and
-  // refuses any other, the kernel root included. A vendor seal takes the kernel root too.
-  let namesDefinition;
-  try {
-    namesDefinition = parseSealArgs(process.argv.slice(2)).catalogueFlags.has(DEFINITION_FLAG);
-  } catch (error) {
-    process.stderr.write(`${error.message}\n`);
-    process.exit(1);
-  }
-  configureEditionWorkspaceFromProcess(
-    namesDefinition
-      ? [WorkspaceRoot.Data, WorkspaceRoot.Editions, WorkspaceRoot.Sources, WorkspaceRoot.Cache]
-      : [WorkspaceRoot.Data, WorkspaceRoot.Editions, WorkspaceRoot.Sources, WorkspaceRoot.Kernel, WorkspaceRoot.Cache],
-    { refuseOthers: namesDefinition },
-  );
-}
-
-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) => [imageSubjectIdentity({ kind: entry.subjectKind, id: entry.subjectId, imageRef: entry.subjectImageRef, contentHash: entry.subjectContentHash }), entry]),
-  );
-  const writes = [];
-  const unchanged = [];
-  for (const subject of subjects) {
-    const key = imageSubjectIdentity(subject);
-    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`, so the kernel's digest regex is not upstream of it and this
- * file's own `SHA256_DIGEST` is the only rule on the images lock. (The sealed
- * grammar of the distribution lock is the kernel's, asked of it separately once
- * the images lock reads PUBLISHABLE.)
- */
-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) => imageSubjectIdentity(subject));
-  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([DEFINITION_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;}
-    const eq = arg.indexOf('=');
-    if (eq > 0 && CATALOGUE_VALUE_FLAGS.has(arg.slice(0, eq))) {
-      const value = arg.slice(eq + 1);
-      if (value === '' || value.startsWith('--')) {throw new Error(`${arg.slice(0, eq)} takes a value`);}
-      catalogueFlags.set(arg.slice(0, eq), value);
-      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 lock the images of an edition will actually READ, built IN MEMORY: the committed lock sealed against the image lock
- * carrying `digests`. Nothing is written. The readability grader asks its question of THIS, never of the committed
- * unsealed form, which every contracts reader refuses for want of a `schemaVersion` whatever the repositories do.
- */
-export async function buildSealedEditionLock(options) {
-  const { prepared } = await prepareEditionSeal({ ...options, checkAdapters: false, check: false });
-  return prepared.result.lock;
-}
-
-/**
- * Write each planned digest into the raw images lock's subject of the same identity (a composed artifact is its
- * `imageRef:contentHash`, so two live generations take their own digests), and count them. A plan the file does not
- * match, in either direction, is refused: nothing is written.
- */
-export function applyDigestsToSubjects(rawImages, digests) {
-  let applied = 0;
-  for (const subject of rawImages.subjects) {
-    const digest = digests.get(imageSubjectIdentity(subject));
-    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',
-    );
-  }
-  return applied;
-}
-
-/** The shared in-memory half of the seal: reads both locks, applies `digests`, seals or verifies. Writes nothing. */
-async function prepareEditionSeal({ distributionId, root, digests = new Map(), check = false, vendoredCommit, catalogue, catalogueDigest, storePublisherAnchorKeys, fetchManifest = fetchRegistryManifest, checkAdapters = true }) {
-  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'));
-  const applied = applyDigestsToSubjects(rawImages, digests);
-  const raw = JSON.parse(readFileSync(lockPath, 'utf8'));
-  const imageLock = schemas.parseImageLock(rawImages);
-  // A release seal reads the EDITION's indexes and pins (a held repository is sealed at the held commit); a
-  // customer seal (catalogue) and a develop seal (injected `vendoredCommit`) are not vendor release editions.
-  const editionInputs = catalogue === undefined && vendoredCommit === undefined ? await editionPinnedInputs(distributionId, { schemas }) : undefined;
-  const pinned = vendoredCommit ?? ((repo) => createPinnedSourceAuthority({ pins: editionInputs?.repositoryPins ?? committedRepositoryPins() }).vendoredSourceCommitForRepository(repo));
-  const lockDocument = raw !== null && typeof raw === 'object' && 'unsealedSchema' in raw ? schemas.parseUnsealedDistributionLock(raw) : schemas.parseDistributionLock(raw);
-  if (checkAdapters && lockMountsAdapters(lockDocument)) {
-    // The adapter host's row: the verified catalogue's for a customer, the data root's biome index for the vendor.
-    const rows = catalogue !== undefined ? catalogue.biomes : (editionInputs?.biomeIndex ?? JSON.parse(readFileSync(biomeIndexPath(), 'utf8')));
-    await assertAdapterBundlesMatchHost({ lock: lockDocument, hostRow: adapterHostRow(rows), fetchManifest });
-  }
-  const result = await sealOrVerifyLock({
-    schemas,
-    lock: lockDocument,
-    imageLock,
-    locate: sourceTreeLocator(externalSourceTrees(lockDocument)),
-    vendoredCommit: pinned,
-    catalogue,
-    catalogueDigest,
-    storePublisherAnchorKeys,
-    check,
-    lockPath,
-  });
-  return { prepared: { result, rawImages, applied, lockPath, imagesPath } };
-}
-
-/**
- * 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, storePublisherAnchorKeys, fetchManifest = fetchRegistryManifest }) {
-  const { prepared } = await prepareEditionSeal({ distributionId, root, digests, check, vendoredCommit, catalogue, catalogueDigest, storePublisherAnchorKeys, fetchManifest });
-  const { result, rawImages, applied, lockPath, imagesPath } = prepared;
-  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, storePublisherAnchorKeys, bundleSigners, check = false, lockPath = 'distribution.lock.json' }) {
-  if ('unsealedSchema' in lock) {
-    if (check) {
-      throw new Error(`${lockPath} is unsealed (no biomeContentHash); run \`xema edition resolve-digests ${lock.distributionId}\``);
-    }
-    return { sealed: true, lock: await sealLock({ schemas, unsealed: lock, imageLock, locate, vendoredCommit, catalogue, catalogueDigest, storePublisherAnchorKeys, bundleSigners }) };
-  }
-  await verifyBiomeContentHashes({ schemas, lock, imageLock, locate, vendoredCommit, catalogue, catalogueDigest, storePublisherAnchorKeys, bundleSigners });
-  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 resolve-digests <distributionId> ' +
-        `[--check | --if-published | --publication-verdict] ` +
-        `[--definition <file> [--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 (no network, no credential) and structural. The images lock is
-  // classified with no kernel at all. A PUBLISHABLE verdict then also reads the distribution lock
-  // through the BUILT kernel (`readSealedDistributionLock`, the predicate `xema edition artifact`
-  // uses), so the publication workflow provisions the built kernel before it asks (`--kernel`).
-  // It returns BEFORE `loadImageLockForVerification`, which needs sibling repositories and the registry.
-  //
-  // 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) {
-      // The artifact verb reads the distribution lock through this same predicate; a verdict that
-      // passed an unsealed one would be the first thing `xema edition artifact` contradicts.
-      readSealedDistributionLock({
-        schemas: await loadKernelDistributionSchemas(),
-        lockPath: join(editionsRoot(), distributionId, 'distribution.lock.json'),
-        distributionId,
-      });
-      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 (`--definition`): the digest-pinned RELEASE catalogue of catalogue.pin.json beside the
-  // definition, the one the edition was resolved against.
-  // Its vendor biomes' tree ids are inputs on ITS authority (biome-content.mjs).
-  const fetched =
-    catalogueFlags.has(DEFINITION_FLAG)
-      ? await fetchCatalogue({
-          ref: readCataloguePin({ definitionFile: catalogueFlags.get(DEFINITION_FLAG), channel: EditionChannel.Release }),
-          channel: EditionChannel.Release,
-          username: catalogueFlags.get(CATALOGUE_USERNAME_FLAG),
-          tokenEnv: catalogueFlags.get(CATALOGUE_TOKEN_ENV_FLAG),
-        })
-      : undefined;
-  const catalogue = fetched?.catalogue;
-  const catalogueDigest = fetched?.digest;
-  // A customer seal reads the kernel of its catalogue (from npm), proved its contract authority, before any kernel schema is loaded.
-  // Its definition's Store publisher selection is what the lock's `storePublisherTrust` is checked against (biome-content.mjs).
-  const storePublisherAnchorKeys =
-    catalogue === undefined
-      ? undefined
-      : parseCustomerDefinition(await adoptCatalogueKernel(catalogue), readStrictJsonFile(catalogueFlags.get(DEFINITION_FLAG))).definition.storePublisherAnchorKeys;
-  const imageLock = await loadImageLockForVerification(distributionId, root);
-  // A pinned third-party subject (its repository is in the data root's third-party source pins) is verified and sealed
-  // BY the pin's manifest digest: its contentHash is publisher-attested and is not a tag.
-  const thirdPartyPins = loadTrustedThirdPartySourcePins(dataRoot());
-  const pinnedImages = thirdPartyImagePins({ pins: thirdPartyPins, subjects: imageLock.subjects });
-
-  // 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, pinnedDigests: pinnedManifestDigests(pinnedImages) });
-  } 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 a customer environment 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.
-  const { writes, unchanged } = planDigestSeal({
-    subjects: imageLock.subjects,
-    verified: report.subjects,
-  });
-
-  const planned = new Map();
-  for (const w of writes) {planned.set(w.key, w.digest);}
-  await assertPlatformCanParseLock({
-    // The lock the images will READ: sealed in memory with this run's digests, never the committed unsealed form.
-    lock: await buildSealedEditionLock({
-      distributionId,
-      root,
-      digests: planned,
-      catalogue,
-      catalogueDigest,
-    }),
-    imageLock,
-    distributionId,
-    // A vendor edition grades the pins it RESOLVES at (a held repository is graded at the held commit);
-    // a customer seal grades the data root's committed index.
-    runtimeSourceIndex:
-      catalogue === undefined
-        ? (await editionPinnedInputs(distributionId, { schemas: await loadKernelDistributionSchemas() })).runtimeImageSourceIndex
-        : JSON.parse(readFileSync(runtimeImageSourceIndexPath(), 'utf8')),
-  });
-
-  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, storePublisherAnchorKeys });
-    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, isThirdPartySubject: (subject) => thirdPartyPins.byRepository(subject.repo) !== undefined });
-  try {
-    const finality = assertCoordinatesFinal({
-      distributionId,
-      writes,
-      verified: report.subjects,
-      fleetRequirements,
-      thirdPartyKeys: new Set(pinnedImages.keys()),
-    });
-    // Third-party subjects are NOT graded by the first-party fleet verdict, and are named here rather than skipped silently.
-    for (const key of finality.thirdParty) {
-      console.log(`[${label}] finality: ${key} third-party (pinned by digest), not a first-party fleet coordinate.`);
-    }
-    // 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,
-    storePublisherAnchorKeys,
-  });
-}
-
-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);
-  });
-}