@xemahq/xema 0.25.1 → 0.27.0

package/edition/lib.mjs

@@ -0,0 +1,3018 @@
+// Shared helpers for the Xema distribution packaging tooling.
+//
+// These are pure Node ESM utilities (mjs tooling — Date.now()/clocks are fine
+// here, unlike kernel contracts). They centralize the few things the three
+// distribution scripts share: locating the repo root, resolving the BUILT
+// kernel contract schemas, the closed BiomeTier order, and the on-disk biome
+// walk. Keeping them here avoids duplicating the manifest-reading + tier-order
+// logic across build/resolve/check. Trusted index generation reads immutable
+// Git objects rather than mutable working-tree files.
+
+import { execFileSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { createRequire } from 'node:module';
+import { isIP } from 'node:net';
+import { join } from 'node:path';
+
+import { readBiomeAuthorizationModuleAt } from './authorization-base.mjs';
+import {
+  isAuthoritativeProductionBiomeSource,
+} from './connector-source-authority.mjs';
+import { assertKernelEditionProtocol } from './edition-protocol.mjs';
+import {
+  dataRoot,
+  kernelDistPath,
+  kernelPackageDir,
+  kernelRepoDir,
+  sourceHashPackageDir,
+  sourcePath,
+} from './edition-workspace.mjs';
+import { SHA256_HEX_PATTERN } from './evidence-grammars.mjs';
+import {
+  createSourceAuthority,
+  DistributionSourceMode,
+  PUBLISHED_SOURCE_REF,
+  publishedSourceCommit,
+} from './source-authority.mjs';
+import { parseStrictJson, readStrictJsonFile } from './strict-json.mjs';
+import { compareStrings } from './string-order.mjs';
+
+export {
+  compareStrings,
+  createSourceAuthority,
+  DistributionSourceMode,
+  PUBLISHED_SOURCE_REF,
+  publishedSourceCommit,
+};
+
+
+/**
+ * Closed BiomeTier order (low→high), READ FROM THE KERNEL.
+ *
+ * The VOCABULARY and the ORDER are both `@xemahq/contracts/biome`'s:
+ * `BIOME_TIER_ORDER` in `src/biome/lib/biome-tier-rank.ts`, itself derived
+ * from `BIOME_TIER_RANK` — a map exhaustively keyed on the `BiomeTier` enum, so
+ * a fifth tier is a compile error in the kernel rather than a value that reads
+ * back `undefined` here and sorts silently to one end.
+ *
+ * The package NAME above is `@xemahq/contracts`, not the retired
+ * `@xemahq/kernel-contracts`; the repository directory is still
+ * `repos/xema-kernel-contracts`, which is why the dist path below keeps it.
+ * Re-measured at that repository's `origin/main` (1e2f7d7, 2026-09-15):
+ * `packages/kernel/kernel-contracts/package.json` declares `@xemahq/contracts`,
+ * `BIOME_TIER_ORDER` is exported from `src/biome/lib/biome-tier-rank.ts`, and
+ * `src/biome/index.ts` re-exports it.
+ *
+ * ── This replaced a literal, and the comment above it was FALSE ──
+ *
+ * That comment said "the kernel exports no order constant — there is no
+ * `BIOME_TIER_ORDER` in `@xemahq/kernel-contracts` (verified 2026-08-31)", and
+ * justified the private copy with "so the tooling does not depend on the kernel
+ * package being workspace-linked at the repo root (it is not)". Both halves
+ * failed, and each failed differently:
+ *
+ *   • The FIRST half was true when written and is not now. The kernel ships
+ *     `BIOME_TIER_RANK`, `BIOME_TIER_ORDER`, `biomeTierRank` and
+ *     `biomeTierWithin`, re-exported by the `biome` barrel — and that file's own
+ *     header names `['infra', ...BIOME_TIER_ORDER, 'edge']` in
+ *     `resolve-distribution.mjs` as the hand-rolled copy it exists to delete.
+ *   • The SECOND half was never a reason. It is true that a BARE
+ *     `@xemahq/kernel-contracts` specifier does not resolve here — this repo's
+ *     `package.json` declares one devDependency and it is `esbuild` — but this
+ *     module has never used one. It reaches the kernel by the deterministic dist
+ *     PATH below (`loadKernelBiomeContracts`), and `readBiomeManifest`, the very
+ *     function that validated a tier against the deleted literal, already called
+ *     that loader four lines later for `isBiomeStoreListed`. The kernel was a
+ *     hard precondition of this exact code path the whole time.
+ *
+ * A justification that names a real constraint which does not apply is the
+ * worst shape of the three, because the constraint checks out: a reader
+ * verifying "the bare specifier does not resolve" confirms the sentence and
+ * stops. See `.claude/rules/writing-boundary-checks.md`, "A comment that
+ * JUSTIFIES a limitation is the last place anyone re-derives it".
+ *
+ * ── Why a function and not a const ──
+ *
+ * `loadKernelBiomeContracts` throws when the kernel dist is unbuilt. Reading it
+ * at module scope would make merely IMPORTING this module require a built
+ * kernel, for every consumer including those that never rank a tier. Lazy and
+ * memoized keeps the precondition where it already was.
+ *
+ * A remaining duplicate, deliberately not taken here: `PLATFORM_SERVICE_TIER_RANK`
+ * (kernel `src/distribution`) is `['infra', ...biome ladder, 'edge']` already
+ * derived, which is what `resolve-distribution.mjs` still builds by hand. That
+ * subpath is loaded through a DIFFERENT, async loader
+ * (`loadKernelDistributionSchemas`) and is a rank MAP rather than an array, so
+ * adopting it is its own change with its own call-site shape.
+ */
+export function biomeTierOrder() {
+  return loadKernelBiomeContracts().BIOME_TIER_ORDER;
+}
+
+/** Is `tier` a valid BiomeTier? (closed set — callers fail fast on false). */
+export function isBiomeTier(tier) {
+  return biomeTierOrder().includes(tier);
+}
+
+/**
+ * Filename of the committed per-biome generated index, beside every
+ * `xema-biome.json`. Value-identical to `BIOME_GENERATED_INDEX_FILENAME` in
+ * `@xemahq/contracts/biome`; asserted against the BUILT kernel export by
+ * `loadKernelBiomeContracts`, so the two cannot drift silently.
+ */
+export const BIOME_GENERATED_INDEX_FILENAME = 'xema-biome.index.json';
+
+/**
+ * Closed workload set for the v4 `xema.ships.apis[]` manifest shape this
+ * tooling reads.
+ *
+ * NO kernel enum spells it: there is no `BiomeWorkloadKind` and no
+ * `biome-workload-kind.ts` anywhere in `@xemahq/contracts` (verified
+ * against that repo's `origin/main`, 2026-08-31), so this literal is the only
+ * declaration of the set — it mirrors nothing. The v5 successor of the same
+ * distinction is `BiomeComponentScheduler` (`platform | runtime`) in
+ * `@xemahq/contracts/biome`
+ * (`src/biome/lib/biome-component-vocabulary.ts`), whose own docblock names
+ * `ships.apis[].workload: "runtime-component"` as the v4 spelling it carries
+ * forward. When this tooling moves to `components[]`, map onto that rather
+ * than re-deriving the distinction here. An entry of `xema.ships.apis[]` that
+ * omits `workload` resolves to `DEFAULT_BIOME_WORKLOAD_KIND`.
+ *
+ *  - `service`           — a standing cluster workload the deploy plane rosters.
+ *  - `runtime-component` — an image built/published/signed/mirrored like any
+ *    other but NEVER independently scheduled; another workload owns its
+ *    lifecycle. No chart, no release, no roster entry.
+ */
+export const BIOME_WORKLOAD_KINDS = new Set(['service', 'runtime-component']);
+
+/** The kind applied when a `ships.apis[]` entry omits `workload`. */
+export const DEFAULT_BIOME_WORKLOAD_KIND = 'service';
+
+/**
+ * The BUILT `@xemahq/distribution-source-hash` package (CJS dist), loaded from
+ * the directory the entry states with `--source-hash`.
+ *
+ * That package is the SINGLE owner of `xema-source-tree-sha256-v2` — the same
+ * implementation every producing repository's CI uses to derive the
+ * `<contentHash>` release tag. This tooling must never carry a second copy: a
+ * divergence would put a lock and its images at coordinates that silently
+ * disagree. It is NOT an npm dependency of the CLI: the evidence verifier never
+ * hashes a source tree, so its bundle must not reach this package; only the
+ * entries that resolve, build, index or seal state the root.
+ */
+const requireFromLib = createRequire(import.meta.url);
+
+const loadedSourceHash = new Map();
+
+function distributionSourceHash() {
+  const directory = sourceHashPackageDir();
+  const known = loadedSourceHash.get(directory);
+  if (known) {return known;}
+  let mod;
+  try {
+    mod = createRequire(join(directory, 'package.json'))(directory);
+  } catch (err) {
+    throw new Error(
+      `Cannot load the built distribution-source-hash package from ${directory}. ` +
+        `Build it first (\`pnpm install --frozen-lockfile && pnpm run build\` in its workspace). ` +
+        `Underlying error: ${err.message}`,
+    );
+  }
+  assertSourceHashMatchesKernel(mod);
+  loadedSourceHash.set(directory, mod);
+  return mod;
+}
+
+/**
+ * The one source-TREE hash algorithm identifier this tooling accepts — read
+ * from the implementation that actually derives the hash, never a local
+ * literal. `loadKernelDistributionSchemas` asserts it is value-identical to the
+ * kernel's `ImageSourceHashAlgorithm.MetadataV2`.
+ *
+ * This hashes ONE directory. It is a COMPONENT of an image coordinate, never an
+ * image coordinate on its own.
+ */
+function metadataSourceHashAlgorithm(sourceHash) {
+  return requireAlgorithmMember(
+    sourceHash.SourceTreeHashAlgorithm,
+    'SourceTreeHashAlgorithm',
+    'MetadataV2',
+  );
+}
+
+/**
+ * Read one member off a built enum, refusing `undefined`.
+ *
+ * A missing member on a JS enum object is an ordinary property read: it yields
+ * `undefined` and nothing complains at the read site. That is not hypothetical
+ * here — renaming `ImageInputV1` to `ImageInputV2` in the source-hash package
+ * turned every reader of the old name into a silent `undefined`, which reaches
+ * a lock's `sourceHashAlgorithm` and a producer statement before anything
+ * notices. Failing AT THE READ names the stale artifact instead.
+ */
+function requireAlgorithmMember(enumObject, enumName, member) {
+  const value = enumObject?.[member];
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new Error(
+      `Built @xemahq/distribution-source-hash does not declare ` +
+        `${enumName}.${member}. The installed package is `+
+        `stale or the member was renamed; raise the @xemahq/distribution-source-hash range and, if the `+
+        `rename was deliberate, move every reader in the same change.`,
+    );
+  }
+  return value;
+}
+
+/**
+ * The one IMAGE-BUILD-INPUT closure algorithm this tooling MINTS, and the only
+ * value admissible as an `ImageLock.sourceHashAlgorithm`. A subject's
+ * `contentHash` under this algorithm covers the whole declared build-input
+ * closure of its image, not just its own subtree.
+ *
+ * Read from the implementation that derives the hash, never a local literal,
+ * so "the algorithm this tooling accepts" and "the algorithm CI can compute"
+ * cannot drift apart. That implementation's `ImageBuildInputHashAlgorithm`
+ * declares `ImageInputV2` and `ImageInputV3`; this tooling mints only
+ * `ImageInputV2`. `@xemahq/contracts` 0.70.0 declares `ImageInputV3` (kernel-
+ * contracts 259c8f5e), but every producer's release lane (and the develop lane,
+ * contract C1) computes V2 keys, so a V3 lock would name coordinates no producer
+ * pushes. V3 adoption is increment 2 and moves the producers and this function
+ * together.
+ *
+ * The kernel's `ImageSourceHashAlgorithm` retains `ImageInputV1` because signed
+ * in-toto statements and already-published locks carry that string and are
+ * immutable. This function is deliberately not a set: a lock the current
+ * producer cannot reproduce is not deliverable, so a v1 lock must be
+ * REGENERATED, never silently accepted.
+ */
+export function imageInputSourceHashAlgorithm() {
+  return imageInputSourceHashAlgorithmOf(distributionSourceHash());
+}
+
+function imageInputSourceHashAlgorithmOf(sourceHash) {
+  return requireAlgorithmMember(
+    sourceHash.ImageBuildInputHashAlgorithm,
+    'ImageBuildInputHashAlgorithm',
+    'ImageInputV2',
+  );
+}
+
+/**
+ * Hold the built source-hash package value-identical to the kernel's wire names.
+ * Runs once per loaded package, so no hash is ever derived from a package that
+ * names its algorithms differently from the kernel that parses the lock.
+ */
+function assertSourceHashMatchesKernel(sourceHash) {
+  const { ImageSourceHashAlgorithm } = requireFromLib(kernelDistributionDist());
+  if (typeof ImageSourceHashAlgorithm !== 'object' || ImageSourceHashAlgorithm === null) {
+    throw new Error(
+      `Built kernel distribution module at ${kernelDistributionDist()} does not export ImageSourceHashAlgorithm — the dist is stale; rebuild kernel-contracts.`,
+    );
+  }
+  // The kernel owns the WIRE name of the source-hash algorithm; the
+  // source-hash package owns its IMPLEMENTATION and declares the identifier
+  // itself so it can ship dependency-free to every producing repo's CI. This
+  // is the one place both built artifacts are in hand, so it is where the two
+  // are held value-identical — a drift here would put a lock's `contentHash`
+  // and the tag CI pushes at coordinates that silently disagree.
+  //
+  // BOTH members are held identical. `MetadataV2` names the component tree
+  // digest; `ImageInputV2` names the full image build-input closure and is what
+  // a lock declares. A drift in either would put a lock's `contentHash` and the
+  // tag CI pushes at coordinates that silently disagree.
+  //
+  // The kernel enum is a SUPERSET: it keeps `ImageInputV1` so an already-signed
+  // statement stays readable, while the source-hash package declares only what
+  // it can still COMPUTE. So the assertion pairs each implemented member with
+  // the kernel member of the same name — it is not a set comparison, and adding
+  // a retired wire name to the kernel must not make this pass vacuously.
+  for (const [implemented, declared, label] of [
+    [
+      metadataSourceHashAlgorithm(sourceHash),
+      ImageSourceHashAlgorithm.MetadataV2,
+      'MetadataV2',
+    ],
+    [
+      imageInputSourceHashAlgorithmOf(sourceHash),
+      ImageSourceHashAlgorithm.ImageInputV2,
+      'ImageInputV2',
+    ],
+  ]) {
+    if (implemented !== declared) {
+      throw new Error(
+        `Source-hash algorithm drift (${label}): @xemahq/distribution-source-hash ` +
+          `implements "${String(implemented)}" but @xemahq/contracts declares ` +
+          `"${String(declared)}". Both must name the same algorithm; rebuild both ` +
+          `packages, and if they genuinely diverged, fix the producer side before ` +
+          `any lock is written.`,
+      );
+    }
+  }
+}
+
+/** Path to the BUILT kernel-contracts BIOME module (CJS dist). */
+const kernelBiomeDist = () => kernelDistPath('biome', 'index.js');
+
+let kernelBiomeContracts;
+
+/**
+ * The kernel's biome contracts, loaded SYNCHRONOUSLY (`createRequire`, like the
+ * source-hash module above) because the index builder is synchronous.
+ *
+ * It lives here rather than in each consumer because `isBiomeStoreListed` is a
+ * predicate with derived refusals, and a second reading of it is not a style
+ * problem — it is a wrong answer. `manifestToIndexEntry` used to resolve
+ * `storeListed` as `xema.storeListed ?? true`, which skips BOTH refusals the
+ * kernel applies: an `operator`-audience biome and a `kernel`-tier biome are
+ * never listed, whatever the flag says. So the index advertised every kernel
+ * biome as store-listed while the catalog projector — which calls the kernel
+ * function — refused them, and the two disagreed about the same bytes. The
+ * kernel's own docstring says it in as many words: resolve via
+ * `isBiomeStoreListed`, never read the field raw.
+ */
+export function loadKernelBiomeContracts() {
+  assertKernelEditionProtocol(kernelPackageDir());
+  if (kernelBiomeContracts) {return kernelBiomeContracts;}
+  let mod;
+  try {
+    mod = requireFromLib(kernelBiomeDist());
+  } catch (err) {
+    throw new Error(
+      `Cannot load built kernel biome contracts from ${kernelBiomeDist()}. ` +
+        `Build it first: run \`pnpm install --frozen-lockfile && pnpm run build\` ` +
+        `in the kernel checkout (${kernelRepoDir()}). That names no package deliberately — ` +
+        `a remedy naming one goes stale on a rename, silently, because ` +
+        `\`pnpm --filter\` exits 0 when nothing matches. ` +
+        `Underlying error: ${err.message}`,
+    );
+  }
+  if (
+    typeof mod.parseBiomeManifest !== 'function' ||
+    typeof mod.isBiomeStoreListed !== 'function' ||
+    typeof mod.BiomeTrustTier !== 'object' ||
+    typeof mod.BiomeOrigin !== 'object' ||
+    typeof mod.requiredBiomeDependencyIds !== 'function' ||
+    typeof mod.foldInstallationClass !== 'function' ||
+    typeof mod.BiomeComponentInstallationClass !== 'object' ||
+    // The GRAMMAR a service component's `protocol.databaseExtensions` entries
+    // are validated against. Read from the kernel, never restated here.
+    //
+    // A PREDICATE, not a set, and that is the whole point: a PostgreSQL
+    // extension name is an OPEN vocabulary owned by whoever runs the database,
+    // so the kernel declares `^[a-z_][a-z0-9_-]*$` (<=63) and ships
+    // `isPostgresExtensionName` rather than an enum. This guard asked for a
+    // closed `PostgresExtension` object the kernel has never exported, and its
+    // error told the reader to rebuild a dist that was already current --- a
+    // false remedy for a design disagreement. Whether a name may actually be
+    // INSTALLED is a deployment question (`infra.yaml#postgres.allowedExtensions`),
+    // deliberately not a contract one.
+    typeof mod.isPostgresExtensionName !== 'function' ||
+    typeof mod.BiomeBundleGeneratedIndexSchema?.parse !== 'function' ||
+    // The ONE shape a biome's `xema.bundleSource` is validated against before
+    // it is projected — onto a host module, or onto the biome itself. Read
+    // from the kernel so the index can never carry a source the lock schema
+    // (which reuses this exact schema) would then refuse.
+    typeof mod.BiomeBundleSourceSpecSchema?.safeParse !== 'function' ||
+    // A component's process facts (`@xemahq/contracts` >= 0.30.0): the
+    // scaling vocabulary and the intrinsic-facts block, projected into
+    // `serviceProcessFacts` by `componentProcessFacts`.
+    typeof mod.BiomeScalingMode !== 'object' ||
+    typeof mod.BiomeComponentProcessFactsSchema?.safeParse !== 'function' ||
+    // Worker protocol v2 (`@xemahq/contracts` >= 0.52.0): the ONE schema a
+    // worker's `protocol.taskQueues` / `protocol.nexus` are graded against
+    // before `componentNexusDeclarations` projects them into the index.
+    typeof mod.BiomeWorkerProtocolSchema?.safeParse !== 'function' ||
+    // The ONE schema a service's `protocol.workflowClientOf` entries are graded
+    // against (`@xemahq/contracts` >= 0.60.0), before `componentWorkflowClients`
+    // projects them into the index.
+    typeof mod.BiomeWorkflowClientOfSchema?.safeParse !== 'function' ||
+    // Asserted here, not read hopefully: `biomeTierOrder()` above returns this
+    // array straight to `.includes()` / `.indexOf()`, and an absent export
+    // would surface as a TypeError at some sort comparator rather than as the
+    // actionable "rebuild kernel-contracts" below.
+    !Array.isArray(mod.BIOME_TIER_ORDER) ||
+    mod.BIOME_TIER_ORDER.length === 0
+  ) {
+    throw new Error(
+      `Built kernel biome module at ${kernelBiomeDist()} does not export ` +
+        `parseBiomeManifest/isBiomeStoreListed/BiomeTrustTier/BiomeOrigin/` +
+        `requiredBiomeDependencyIds/foldInstallationClass/` +
+        `BiomeComponentInstallationClass/isPostgresExtensionName/` +
+        `BiomeBundleGeneratedIndexSchema/BiomeBundleSourceSpecSchema/BiomeScalingMode/` +
+        `BiomeComponentProcessFactsSchema/BiomeWorkerProtocolSchema/BiomeWorkflowClientOfSchema/BIOME_TIER_ORDER — ` +
+        `the dist is stale (isPostgresExtensionName needs @xemahq/contracts >= 0.12.0, ` +
+        `the process facts >= 0.30.0, worker protocol v2 >= 0.52.0, workflowClientOf >= 0.60.0); rebuild ` +
+        `kernel-contracts at a commit that carries it.`,
+    );
+  }
+  if (mod.BIOME_GENERATED_INDEX_FILENAME !== BIOME_GENERATED_INDEX_FILENAME) {
+    throw new Error(
+      `Kernel BIOME_GENERATED_INDEX_FILENAME is "${String(mod.BIOME_GENERATED_INDEX_FILENAME)}" ` +
+        `but this plane reads "${BIOME_GENERATED_INDEX_FILENAME}" — the literal drifted from the kernel.`,
+    );
+  }
+  kernelBiomeContracts = mod;
+  return kernelBiomeContracts;
+}
+
+/** Path to the BUILT kernel-contracts RESOURCE-REQUIREMENT module (CJS dist). */
+const kernelResourceRequirementDist = () => kernelDistPath('resource-requirement', 'index.js');
+
+let kernelResourceRequirementContracts;
+
+/**
+ * The kernel's resource-requirement grammar, loaded SYNCHRONOUSLY like
+ * {@link loadKernelBiomeContracts}. A component's `protocol.resources` and
+ * `protocol.providesResources` are validated by the kernel's own schemas —
+ * never a restated grammar — so the index can never carry a declaration the
+ * lock schema would then refuse.
+ */
+export function loadKernelResourceRequirementContracts() {
+  assertKernelEditionProtocol(kernelPackageDir());
+  if (kernelResourceRequirementContracts) {
+    return kernelResourceRequirementContracts;
+  }
+  let mod;
+  try {
+    mod = requireFromLib(kernelResourceRequirementDist());
+  } catch (err) {
+    throw new Error(
+      `Cannot load built kernel resource-requirement contracts from ` +
+        `${kernelResourceRequirementDist()}. Build kernel-contracts at a commit ` +
+        `that carries the resource-requirement subpath: run ` +
+        `\`pnpm install --frozen-lockfile && pnpm run build\` in ` +
+        `the kernel checkout (${kernelRepoDir()}). Underlying error: ${err.message}`,
+    );
+  }
+  if (
+    typeof mod.ResourceRequirementsSchema?.safeParse !== 'function' ||
+    typeof mod.ResourceProvisionsSchema?.safeParse !== 'function'
+  ) {
+    throw new Error(
+      `Built kernel resource-requirement module at ${kernelResourceRequirementDist()} ` +
+        `does not export ResourceRequirementsSchema/ResourceProvisionsSchema — ` +
+        `the dist is stale; rebuild kernel-contracts.`,
+    );
+  }
+  kernelResourceRequirementContracts = mod;
+  return kernelResourceRequirementContracts;
+}
+
+/**
+ * Validate one component's `protocol.resources` / `protocol.providesResources`
+ * with the KERNEL's schemas, naming the manifest and the component on failure.
+ * Returns `[]` for an absent field — absent and `[]` make the same claim.
+ */
+function parseComponentResourceDeclaration(schemaName, value, where) {
+  if (value === undefined) {return [];}
+  const schema = loadKernelResourceRequirementContracts()[schemaName];
+  const parsed = schema.safeParse(value);
+  if (!parsed.success) {
+    throw new Error(
+      `${where} is not a valid resource declaration: ` +
+        parsed.error.issues
+          .map((issue) => `[${issue.path.join('.')}] ${issue.message}`)
+          .join('; '),
+    );
+  }
+  return parsed.data;
+}
+
+/**
+ * Project one image component's Nexus declarations (worker protocol v2) into
+ * the two index rows the edition resolver binds from. The protocol is graded
+ * by the KERNEL's `BiomeWorkerProtocolSchema` first, so every v2 rule (a
+ * provided service names one of the worker's own `nexus` queues, nothing is
+ * provided and required by one worker, no duplicates) holds before anything
+ * is projected. Returns empty arrays for a component that declares no `nexus`
+ * — absent and `[]` make the same claim — so a biome that declares none adds
+ * no index key and `biome-index.json` stays byte-stable.
+ *
+ * Only a `worker` may declare one: the v2 shape is the worker protocol's, and
+ * a `nexus` block on any other kind is refused rather than dropped, because a
+ * dropped requirement reaches no lock and fails nothing.
+ */
+/** The protocol kinds a `worker` component may declare (closed). */
+const WorkerProtocolKind = Object.freeze({ Worker: 'worker', None: 'none' });
+
+/**
+ * The task queues a protocol `worker/v2` component polls, sorted by name (a bare
+ * short name, or `{ name, placement }` when the queue is placed),
+ * or null for anything else — a runtime-launched worker (protocol `none`) polls
+ * nothing, and a service carries no worker protocol. Validated by the kernel's own worker-protocol
+ * schema, naming the manifest. The deploy plane runs exactly these components
+ * under a Worker Controller (durable-execution plan W3.4 / U14), so a v2 worker
+ * is recognised by what it declares, never by a list of chart names.
+ */
+function componentWorkerTaskQueues(component, protocol, where) {
+  if (component.kind !== 'worker') {return null;}
+  // A CLOSED enum: a worker protocol kind this resolver does not know would
+  // otherwise silently contribute no queues, and a missing queue reaches no lock.
+  if (!Object.values(WorkerProtocolKind).includes(protocol.kind)) {
+    throw new Error(
+      `${where} declares worker protocol kind ${JSON.stringify(protocol.kind)}; ` +
+        `expected ${Object.values(WorkerProtocolKind).join(' | ')}`,
+    );
+  }
+  if (protocol.kind === WorkerProtocolKind.None) {return null;}
+  const parsed = loadKernelBiomeContracts().BiomeWorkerProtocolSchema.safeParse(protocol);
+  if (!parsed.success) {
+    throw new Error(
+      `${where} is not a valid worker protocol: ` +
+        parsed.error.issues.map((issue) => `[${issue.path.join('.')}] ${issue.message}`).join('; '),
+    );
+  }
+  // A queue with a `placement` keeps it: the lock carries `{ name, placement }`
+  // for it and the bare short name for every other queue.
+  return parsed.data.taskQueues
+    .map((queue) => lockedTaskQueueRef(queue.name, queue.placement))
+    .sort(compareTaskQueueRefs);
+}
+
+/** The lock's `WorkerTaskQueueRef`: a bare short name, or `{ name, placement }` when the queue is placed. */
+function lockedTaskQueueRef(name, placement) {
+  return placement === undefined ? name : { name, placement };
+}
+
+function taskQueueRefName(ref) {
+  return typeof ref === 'string' ? ref : ref.name;
+}
+
+function compareTaskQueueRefs(a, b) {
+  return compareStrings(taskQueueRefName(a), taskQueueRefName(b));
+}
+
+/**
+ * The `{ biome?, component, taskQueue }[]` a service's `protocol.workflowClientOf`
+ * declares (`biome` only when the entry names another biome's worker, passed
+ * through from the kernel schema's parse), sorted by biome (absent first), then
+ * component, then queue name (`taskQueue` is a bare short
+ * name, or `{ name, placement }` when the queue is placed), or `null` when it declares none (absent and `[]`
+ * make the same claim). Each entry is graded by the kernel's own schema; that
+ * the target is a shipped worker/v2 whose queue is polled is the lock's
+ * refinement, not restated here.
+ */
+function componentWorkflowClients(protocol, where) {
+  if (protocol.workflowClientOf === undefined) {return null;}
+  if (!Array.isArray(protocol.workflowClientOf)) {
+    throw new Error(`${where} protocol.workflowClientOf must be an array`);
+  }
+  if (protocol.workflowClientOf.length === 0) {return null;}
+  const schema = loadKernelBiomeContracts().BiomeWorkflowClientOfSchema;
+  return protocol.workflowClientOf.map((entry, index) => {
+    const parsed = schema.safeParse(entry);
+    if (!parsed.success) {
+      throw new Error(
+        `${where} has an invalid protocol.workflowClientOf[${index}]: ` +
+          parsed.error.issues.map((issue) => `[${issue.path.join('.')}] ${issue.message}`).join('; '),
+      );
+    }
+    return parsed.data;
+  }).sort(
+    (a, b) =>
+      compareStrings(a.biome ?? '', b.biome ?? '') ||
+      compareStrings(a.component, b.component) ||
+      compareTaskQueueRefs(a.taskQueue, b.taskQueue),
+  );
+}
+
+/**
+ * `{ imageOf, entry }` for a worker declaring `artifact.kind:
+ * shared-oci-image` — the sibling SERVICE whose sealed image it runs (by that
+ * service's image name, `protocol.serviceName`) and the module `node` runs in
+ * it — or `null` for any other component.
+ *
+ * The kernel manifest schema already refuses an inconsistent declaration; this
+ * projection reads the RAW manifest, so it re-checks exactly the facts it
+ * writes rather than trusting them: a lock naming a sibling that is not a
+ * platform-scheduled oci-image service would send the deploy plane to a
+ * subject that does not exist.
+ */
+function sharedImageWorker(component, components, where) {
+  if (component.artifact?.kind !== 'shared-oci-image') {return null;}
+  const siblingKey = component.artifact.component;
+  const sibling = components.find(
+    (candidate) =>
+      candidate !== null && typeof candidate === 'object' && candidate.key === siblingKey,
+  );
+  const imageOf = sibling?.protocol?.serviceName;
+  if (
+    sibling === undefined ||
+    sibling.kind !== 'service' ||
+    sibling.artifact?.kind !== 'oci-image' ||
+    sibling.scheduler !== 'platform' ||
+    typeof imageOf !== 'string' ||
+    imageOf.length === 0
+  ) {
+    throw new Error(
+      `${where} runs the image of component "${String(siblingKey)}", which is not a ` +
+        `platform-scheduled service shipping its own oci-image in this biome`,
+    );
+  }
+  const entry = component.entrypoint?.module;
+  if (component.entrypoint?.kind !== 'node-module' || typeof entry !== 'string' || entry.length === 0) {
+    throw new Error(
+      `${where} declares a shared-oci-image artifact without a node-module entrypoint ` +
+        `naming the module to run`,
+    );
+  }
+  return { imageOf, entry };
+}
+
+function componentNexusDeclarations(component, name, protocol, where) {
+  if (protocol.nexus === undefined) {return { provides: [], requires: [] };}
+  if (component.kind !== 'worker') {
+    throw new Error(
+      `${where} declares protocol.nexus on a "${String(component.kind)}" component — ` +
+        `only a worker (protocol worker/v2) provides or requires a Nexus service`,
+    );
+  }
+  const parsed = loadKernelBiomeContracts().BiomeWorkerProtocolSchema.safeParse(protocol);
+  if (!parsed.success) {
+    throw new Error(
+      `${where} is not a valid worker protocol: ` +
+        parsed.error.issues
+          .map((issue) => `[${issue.path.join('.')}] ${issue.message}`)
+          .join('; '),
+    );
+  }
+  const nexus = parsed.data.nexus ?? {};
+  return {
+    // `operations` travels with each row: the kernel's `resolveNexusBindings`
+    // binds a requirement only to a provider declaring EVERY operation it
+    // requires, so the operation names are binding facts, not decoration.
+    // Sorted by code unit, so the index is byte-stable whatever order the
+    // manifest lists them in.
+    provides: (nexus.provides ?? []).map((entry) => ({
+      component: name,
+      service: entry.service,
+      version: entry.version,
+      taskQueue: entry.taskQueue,
+      operations: entry.operations.map((operation) => operation.name).sort(compareStrings),
+    })),
+    requires: (nexus.requires ?? []).map((entry) => ({
+      component: name,
+      service: entry.service,
+      version: entry.version,
+      operations: [...entry.operations].sort(compareStrings),
+      ...(entry.optional === true ? { optional: true } : {}),
+    })),
+  };
+}
+
+const compareNexusRows = (a, b) =>
+  compareStrings(a.service, b.service) ||
+  compareStrings(a.version, b.version) ||
+  compareStrings(a.component, b.component);
+
+const compareResourceRows = (a, b) =>
+  compareStrings(a.consumerService, b.consumerService) ||
+  compareStrings(a.kind, b.kind) ||
+  compareStrings(a.logicalName, b.logicalName);
+
+
+
+const kernelDistributionDist = () => kernelDistPath('distribution', 'index.js');
+
+// The kernel's process-topology module: the ONE trust-domain grammar
+// (`deriveTrustCeiling`) a lock writer projects an edition's `trustCeiling`
+// through. A sibling of the distribution dist, loaded beside it.
+const kernelProcessTopologyDist = () => kernelDistPath('process-topology', 'index.js');
+
+/**
+ * Dynamically import the BUILT kernel distribution schemas. The kernel package
+ * is NOT linked into the repo-root node_modules (it lives in its own sub-
+ * workspace), so a bare `@xemahq/contracts/distribution` specifier does
+ * not resolve from root tooling. We import the deterministic dist path instead
+ * — fail-fast with an actionable message if the dist is not built.
+ */
+export async function loadKernelDistributionSchemas() {
+  assertKernelEditionProtocol(kernelPackageDir());
+  let mod;
+  try {
+    mod = await import(`file://${kernelDistributionDist()}`);
+  } catch (err) {
+    throw new Error(
+      `Cannot load built kernel distribution schemas from ${kernelDistributionDist()}. ` +
+        `Build it first: run \`pnpm install --frozen-lockfile && pnpm run build\` ` +
+          `in the kernel checkout (${kernelRepoDir()}) — naming no package, deliberately. ` +
+        `Underlying error: ${err.message}`,
+    );
+  }
+  const {
+    parseDistribution,
+    parseDistributionLock,
+    parseDistributionLockForReading,
+    parseUnsealedDistributionLock,
+    parseCustomerEditionDefinition,
+    customerTrustCeilingIssues,
+    sealDistributionLock,
+    unsealedProjection,
+    UNSEALED_DISTRIBUTION_LOCK_SCHEMA,
+    DISTRIBUTION_LOCK_SCHEMA_VERSION,
+    computeBiomeContentHash,
+    computeBiomeSourceManifestHash,
+    parseBiomeSourceManifestHash,
+    parseOciDigest,
+    parseGitTreeId,
+    parseImageLock,
+    parseImageProducerStatement,
+    parseDistributionImagesStatement,
+    parseImageDeliveryEntitlementStatement,
+    parseDistributionImageEvidenceSet,
+    parseDistributionImageReplayState,
+    parseSigstoreOfflineTrustPolicy,
+    parsePlatformServiceSourceIndex,
+    parseRuntimeImageSourceIndex,
+    resolveRuntimeImagePlatforms,
+    BiomeInstallPolicy,
+    BiomeLaunchMode,
+    ImageSourceHashAlgorithm,
+    RuntimeImagePlatformKey,
+    RuntimeImageOwnerKind,
+    RuntimeImageSubjectKind,
+    IMAGE_PRODUCER_PREDICATE_TYPE,
+    DISTRIBUTION_IMAGES_PREDICATE_TYPE,
+    IMAGE_DELIVERY_ENTITLEMENT_PREDICATE_TYPE,
+    EVIDENCE_CHANNELS,
+    EVIDENCE_CHANNEL_REFS,
+    resolveFirstPartyCapabilityDomains,
+    DistributionVisibility,
+    computeKernelContractAuthorityContentDigest,
+    KernelContractContentHashAlgorithm,
+    XEMA_KERNEL_CONTRACT_AUTHORITY_DIGEST_DOMAIN,
+    XEMA_KERNEL_CONTRACT_AUTHORITY_DIGEST_VERSION,
+    XEMA_KERNEL_CONTRACT_AUTHORITY_GENERATOR,
+    XEMA_KERNEL_CONTRACT_REPOSITORY_URL,
+    XEMA_KERNEL_CONTRACT_SOURCE_MODE,
+    XEMA_KERNEL_CONTRACT_SOURCE_PATHS,
+    compareLockedServiceResources,
+    resolveNexusBindings,
+    describeNexusBindingRefusal,
+    canonicalNexusFacts,
+    DistributionResolutionMode,
+    resolveBiomeClosure,
+    platformInvariantRoots,
+    BiomeClosureError,
+    ClosureEntityKind,
+    ClosureProvenanceKind,
+    describeProvenance,
+    describeHop,
+    deriveWorkflowSubjects,
+  } = mod;
+  let topology;
+  try {
+    topology = await import(`file://${kernelProcessTopologyDist()}`);
+  } catch (err) {
+    throw new Error(
+      `Cannot load the built kernel process-topology module from ${kernelProcessTopologyDist()}. ` +
+        `Rebuild the kernel checkout (${kernelRepoDir()}). Underlying error: ${err.message}`,
+    );
+  }
+  const { deriveTrustCeiling, defaultTrustDomain, FIRST_PARTY_TRUST_DOMAIN, ProcessTrustPolicySchema } = topology;
+  const { DistributionTrustPolicySchema } = mod;
+  if (
+    typeof parseDistribution !== 'function' ||
+    typeof parseDistributionLock !== 'function' ||
+    // The tolerant READER (`@xemahq/contracts` >= 0.27.0). Every PURE read of a
+    // lock in this repository goes through it; only the resolver, which WRITES
+    // the lock, uses the strict `parseDistributionLock`.
+    typeof parseDistributionLockForReading !== 'function' ||
+    // Lock v5 is the only grammar. The resolver writes the UNSEALED document,
+    // the seal mints each biomeContentHash (`computeBiomeContentHash`) and the
+    // kernel's `sealDistributionLock` attaches them; the CLI never assembles v5.
+    DISTRIBUTION_LOCK_SCHEMA_VERSION !== 5 ||
+    typeof parseUnsealedDistributionLock !== 'function' ||
+    typeof sealDistributionLock !== 'function' ||
+    typeof unsealedProjection !== 'function' ||
+    typeof UNSEALED_DISTRIBUTION_LOCK_SCHEMA !== 'string' ||
+    typeof computeBiomeContentHash !== 'function' ||
+    typeof computeBiomeSourceManifestHash !== 'function' ||
+    typeof parseBiomeSourceManifestHash !== 'function' ||
+    typeof parseOciDigest !== 'function' ||
+    typeof parseGitTreeId !== 'function' ||
+    typeof parseImageLock !== 'function' ||
+    typeof parseImageProducerStatement !== 'function' ||
+    typeof parseDistributionImagesStatement !== 'function' ||
+    typeof parseImageDeliveryEntitlementStatement !== 'function' ||
+    typeof parseDistributionImageEvidenceSet !== 'function' ||
+    typeof parseDistributionImageReplayState !== 'function' ||
+    typeof parseSigstoreOfflineTrustPolicy !== 'function' ||
+    typeof parsePlatformServiceSourceIndex !== 'function' ||
+    typeof parseRuntimeImageSourceIndex !== 'function' ||
+    typeof resolveRuntimeImagePlatforms !== 'function' ||
+    typeof resolveFirstPartyCapabilityDomains !== 'function' ||
+    typeof DistributionVisibility !== 'object' ||
+    typeof BiomeInstallPolicy !== 'object' ||
+    typeof BiomeLaunchMode !== 'object' ||
+    typeof ImageSourceHashAlgorithm !== 'object' ||
+    typeof RuntimeImagePlatformKey !== 'object' ||
+    typeof RuntimeImageOwnerKind !== 'object' ||
+    typeof RuntimeImageSubjectKind !== 'object' ||
+    typeof IMAGE_PRODUCER_PREDICATE_TYPE !== 'string' ||
+    typeof DISTRIBUTION_IMAGES_PREDICATE_TYPE !== 'string' ||
+    typeof IMAGE_DELIVERY_ENTITLEMENT_PREDICATE_TYPE !== 'string' ||
+    !Array.isArray(EVIDENCE_CHANNELS) ||
+    typeof EVIDENCE_CHANNEL_REFS !== 'object' ||
+    typeof computeKernelContractAuthorityContentDigest !== 'function' ||
+    typeof KernelContractContentHashAlgorithm !== 'object' ||
+    typeof XEMA_KERNEL_CONTRACT_AUTHORITY_DIGEST_DOMAIN !== 'string' ||
+    XEMA_KERNEL_CONTRACT_AUTHORITY_DIGEST_VERSION !== 1 ||
+    typeof XEMA_KERNEL_CONTRACT_AUTHORITY_GENERATOR !== 'string' ||
+    typeof XEMA_KERNEL_CONTRACT_REPOSITORY_URL !== 'string' ||
+    typeof XEMA_KERNEL_CONTRACT_SOURCE_MODE !== 'string' ||
+    !Array.isArray(XEMA_KERNEL_CONTRACT_SOURCE_PATHS) ||
+    !Object.isFrozen(XEMA_KERNEL_CONTRACT_SOURCE_PATHS) ||
+    // The ONE order a lock's `serviceResources` rows are emitted in — the
+    // comparator the kernel lock schema asserts, never a second spelling.
+    typeof compareLockedServiceResources !== 'function' ||
+    // THE Nexus binding rule — service, major version and every required
+    // operation — shared with the runtime resolver (>= 0.53.0).
+    typeof resolveNexusBindings !== 'function' ||
+    typeof describeNexusBindingRefusal !== 'function' ||
+    // The canonical per-biome Nexus facts a lock carries (>= 0.54.0).
+    typeof canonicalNexusFacts !== 'function' ||
+    // Positive closure (`@xemahq/contracts` >= the release that added the
+    // `resolution`/`roots` edition fields): the ONE closure algorithm, shared
+    // with runtime installation, and the vocabulary its provenance is written in.
+    typeof DistributionResolutionMode !== 'object' ||
+    typeof resolveBiomeClosure !== 'function' ||
+    typeof platformInvariantRoots !== 'function' ||
+    typeof BiomeClosureError !== 'function' ||
+    typeof ClosureEntityKind !== 'object' ||
+    typeof ClosureProvenanceKind !== 'object' ||
+    typeof describeProvenance !== 'function' ||
+    typeof describeHop !== 'function' ||
+    // A biome's workflow subjects and its edition trust ceiling, each written
+    // through the kernel's one derivation (`@xemahq/contracts` >= 0.71.0).
+    typeof deriveWorkflowSubjects !== 'function' ||
+    typeof deriveTrustCeiling !== 'function' ||
+    // The trust-domain vocabulary a customer edition is bounded by: the vendor's
+    // own domain, a biome's default domain, and the two ceiling grammars a
+    // catalogue carries.
+    typeof defaultTrustDomain !== 'function' ||
+    typeof FIRST_PARTY_TRUST_DOMAIN !== 'string' ||
+    typeof ProcessTrustPolicySchema?.safeParse !== 'function' ||
+    typeof DistributionTrustPolicySchema?.safeParse !== 'function'
+  ) {
+    throw new Error(
+      `Built kernel distribution module at ${kernelDistributionDist()} does not export ` +
+        `parseDistribution/parseDistributionLock/parseDistributionLockForReading/DISTRIBUTION_LOCK_SCHEMA_VERSION/parseUnsealedDistributionLock/sealDistributionLock/unsealedProjection/computeBiomeContentHash/computeBiomeSourceManifestHash/parseImageLock/image-evidence parsers/` +
+        `parsePlatformServiceSourceIndex/parseRuntimeImageSourceIndex/` +
+        `resolveRuntimeImagePlatforms/RuntimeImagePlatformKey/` +
+        `kernel contract-authority digest SSOT/compareLockedServiceResources/resolveNexusBindings/describeNexusBindingRefusal/canonicalNexusFacts/` +
+        `positive closure (resolveBiomeClosure/platformInvariantRoots/DistributionResolutionMode/provenance)/` +
+        `deriveWorkflowSubjects/deriveTrustCeiling (>= 0.71.0)/` +
+        `defaultTrustDomain/FIRST_PARTY_TRUST_DOMAIN/ProcessTrustPolicySchema/DistributionTrustPolicySchema/` +
+        `resolveFirstPartyCapabilityDomains/DistributionVisibility/` +
+        `BiomeInstallPolicy/BiomeLaunchMode/ImageSourceHashAlgorithm/runtime-image enums — ` +
+        `the dist is stale; rebuild kernel-contracts.`,
+    );
+  }
+  return {
+    parseDistribution,
+    parseDistributionLock,
+    parseDistributionLockForReading,
+    parseUnsealedDistributionLock,
+    parseCustomerEditionDefinition,
+    customerTrustCeilingIssues,
+    sealDistributionLock,
+    unsealedProjection,
+    UNSEALED_DISTRIBUTION_LOCK_SCHEMA,
+    DISTRIBUTION_LOCK_SCHEMA_VERSION,
+    computeBiomeContentHash,
+    computeBiomeSourceManifestHash,
+    parseBiomeSourceManifestHash,
+    parseOciDigest,
+    parseGitTreeId,
+    parseImageLock,
+    parseImageProducerStatement,
+    parseDistributionImagesStatement,
+    parseImageDeliveryEntitlementStatement,
+    parseDistributionImageEvidenceSet,
+    parseDistributionImageReplayState,
+    parseSigstoreOfflineTrustPolicy,
+    parsePlatformServiceSourceIndex,
+    parseRuntimeImageSourceIndex,
+    resolveRuntimeImagePlatforms,
+    BiomeInstallPolicy,
+    BiomeLaunchMode,
+    ImageSourceHashAlgorithm,
+    RuntimeImagePlatformKey,
+    RuntimeImageOwnerKind,
+    RuntimeImageSubjectKind,
+    IMAGE_PRODUCER_PREDICATE_TYPE,
+    DISTRIBUTION_IMAGES_PREDICATE_TYPE,
+    IMAGE_DELIVERY_ENTITLEMENT_PREDICATE_TYPE,
+    EVIDENCE_CHANNELS,
+    EVIDENCE_CHANNEL_REFS,
+    resolveFirstPartyCapabilityDomains,
+    DistributionVisibility,
+    computeKernelContractAuthorityContentDigest,
+    KernelContractContentHashAlgorithm,
+    XEMA_KERNEL_CONTRACT_AUTHORITY_DIGEST_DOMAIN,
+    XEMA_KERNEL_CONTRACT_AUTHORITY_DIGEST_VERSION,
+    XEMA_KERNEL_CONTRACT_AUTHORITY_GENERATOR,
+    XEMA_KERNEL_CONTRACT_REPOSITORY_URL,
+    XEMA_KERNEL_CONTRACT_SOURCE_MODE,
+    XEMA_KERNEL_CONTRACT_SOURCE_PATHS,
+    compareLockedServiceResources,
+    resolveNexusBindings,
+    describeNexusBindingRefusal,
+    canonicalNexusFacts,
+    DistributionResolutionMode,
+    resolveBiomeClosure,
+    platformInvariantRoots,
+    BiomeClosureError,
+    ClosureEntityKind,
+    ClosureProvenanceKind,
+    describeProvenance,
+    describeHop,
+    deriveWorkflowSubjects,
+    deriveTrustCeiling,
+    defaultTrustDomain,
+    FIRST_PARTY_TRUST_DOMAIN,
+    ProcessTrustPolicySchema,
+    DistributionTrustPolicySchema,
+  };
+}
+
+/**
+ * The published branch every image/platform source repository is pinned at.
+ *
+ * Deliberately NOT the local `HEAD`. A pin is a coordinate a CONSUMER has to be
+ * able to fetch: pinning a local HEAD records commits that exist only on this
+ * machine — an unpushed commit, or a branch someone is mid-way through — and a
+ * lock built on one is unresolvable anywhere else. It also made every generator
+ * hostage to the aggregator's checkout state, which is never quiescent.
+ *
+ * Every digest in release mode reads immutable Git objects at this exact
+ * commit, so the working tree is not an accidental input. Local development
+ * can opt into `workspace` authority explicitly; that mode also produces exact
+ * Git objects, but its synthetic commits are local-only and never selected by
+ * default.
+ */
+// Aligns with the CLI's manifest discovery rules:
+// `fixtures`/`templates` hold test-fixture and scaffold `xema-biome.json` files
+// that are NOT distributable biomes and must never enter the packaging index
+// (e.g. create-biome templates, any package's `test/fixtures/*-biome`).
+const SKIP_DIR_NAMES = new Set([
+  'node_modules',
+  '.git',
+  'dist',
+  'fixtures',
+  'templates',
+]);
+
+/**
+ * Whether a discovered manifest path is an OpenAPI/test fixture rather than a
+ * real biome. Fixtures live under `scripts/openapi-fixture/` and re-use real
+ * biome ids (e.g. `runtime`), which would otherwise collide in the index.
+ */
+function isFixtureManifest(repoRelativePath) {
+  return repoRelativePath.split('/').includes('openapi-fixture');
+}
+
+export function distributionBiomeSourceRepositories() {
+  const publishersPath = join(
+    dataRoot(),
+    'store-publisher-identities.json',
+  );
+  const publishers = readStrictJsonFile(publishersPath);
+  if (
+    !Array.isArray(publishers.publishers) ||
+    publishers.publishers.length === 0
+  ) {
+    throw new Error(`${publishersPath} declares no Store publishers`);
+  }
+  const repositoryNames = publishers.publishers.flatMap((publisher) => {
+    if (!Array.isArray(publisher.sourceRepositories)) {
+      throw new Error(
+        `${publishersPath} publisher ${String(publisher.anchorKey)} has no sourceRepositories`,
+      );
+    }
+    return publisher.sourceRepositories;
+  });
+  if (new Set(repositoryNames).size !== repositoryNames.length) {
+    throw new Error(
+      `${publishersPath} declares a source repository under more than one publisher`,
+    );
+  }
+  return repositoryNames
+    .map((repo) => ({ repo, directory: sourcePath(repo) }))
+    .sort((a, b) => compareStrings(a.repo, b.repo));
+}
+
+/**
+ * Ceiling for one `git ls-tree -r` listing of a whole repository.
+ *
+ * Node's default is 1 MiB and this call outgrew it in production: `xema-base`
+ * measured 1,056,095 bytes across 12,214 paths on 2026-08-20 — 7 KiB past the
+ * default — so the biome-index step began failing with a bare
+ * `spawnSync git ENOBUFS`, which names neither the repository nor the reason.
+ * The listing grows with every file added to any carved repo, so the ceiling
+ * has to sit far above today's number rather than just above it.
+ *
+ * A ceiling is safe to raise here because `execFileSync` THROWS on overflow
+ * rather than truncating: exceeding it is a loud failure, never a short read
+ * that would silently drop biomes from the index.
+ */
+const GIT_LS_TREE_MAX_BUFFER = 256 * 1024 * 1024;
+
+/**
+ * Every authoritative biome manifest in one repository AT ONE COMMIT, paired
+ * with the `xema-biome.index.json` committed beside it.
+ *
+ * Extracted so the IMAGE-axis pass and the SOURCE-axis pass read manifests the
+ * SAME way. Two copies of this walk would be two places for the skip rules, the
+ * authoritative-source filter and the missing-index error to drift apart — and
+ * the whole point of the split is that the two axes differ ONLY in which commit
+ * they read.
+ *
+ * The manifest and its generated index are read from the SAME commit, which is
+ * load-bearing and predates this split: the index is the authority for which
+ * biomes this one requires, so reading them apart would let it describe a
+ * different revision of the biome than the one being locked.
+ */
+function listBiomeManifestsAt(directory, repo, commit) {
+  const found = [];
+  const rawPaths = execFileSync(
+    'git',
+    ['-C', directory, 'ls-tree', '-r', '-z', '--name-only', commit],
+    { encoding: 'buffer', maxBuffer: GIT_LS_TREE_MAX_BUFFER },
+  );
+  for (const repoPath of decodeNullDelimitedGitRecords(
+    rawPaths,
+    `Git manifest paths in ${repo}@${commit}`,
+  )) {
+    if (
+      !repoPath.endsWith('/xema-biome.json') ||
+      repoPath.split('/').some((segment) => SKIP_DIR_NAMES.has(segment)) ||
+      isFixtureManifest(repoPath)
+    ) {
+      continue;
+    }
+    const manifestDirectory = repoPath.slice(0, -'/xema-biome.json'.length);
+    const rel = `${repo}/${repoPath}`;
+    const raw = readGitJsonAtCommit(directory, repoPath, commit);
+    const path = `${repo}/${manifestDirectory}`;
+    if (
+      !isAuthoritativeProductionBiomeSource({
+        id: raw?.xema?.id,
+        repo,
+        path,
+      })
+    ) {
+      continue;
+    }
+    // The generated index is COMMITTED beside the manifest and is the single
+    // authority for which biomes this one requires. It is read from the SAME
+    // pinned commit as the manifest, so the index cannot describe a different
+    // revision of the biome than the one being locked.
+    const indexRepoPath = `${manifestDirectory}/${BIOME_GENERATED_INDEX_FILENAME}`;
+    let generatedIndex;
+    try {
+      generatedIndex = readGitJsonAtCommit(directory, indexRepoPath, commit);
+    } catch (error) {
+      throw new Error(
+        `${repo}/${indexRepoPath} is missing at ${commit}: ${error.message}. ` +
+          `Every biome carries a committed ${BIOME_GENERATED_INDEX_FILENAME} — it replaced the ` +
+          `manifest field xema.requiresServerBiomes as the authority for required biomes. ` +
+          `Run \`pnpm derive:biome-index:write\` in the aggregator and commit the result.`,
+      );
+    }
+    // The biome's authorization module, read at the SAME pinned commit as the
+    // manifest, so the sealer composes exactly the bytes the bundle signs.
+    const authorizationModule = readBiomeAuthorizationModuleAt(
+      manifestDirectory,
+      (repoRelativePath) => readGitTextAtCommitOrNull(directory, repoRelativePath, commit),
+      rel,
+    );
+    found.push({
+      raw,
+      generatedIndex,
+      rel,
+      repo,
+      path,
+      ...(authorizationModule === null ? {} : { authorizationModule }),
+    });
+  }
+
+  return found;
+}
+
+/** A file's text at a commit, or `null` when the commit does not carry it. */
+export function readGitTextAtCommitOrNull(repoDir, repoRelativePath, commit) {
+  try {
+    execFileSync('git', ['-C', repoDir, 'cat-file', '-e', `${commit}:${repoRelativePath}`], {
+      stdio: 'ignore',
+    });
+  } catch {
+    return null;
+  }
+  return execFileSync('git', ['-C', repoDir, 'show', `${commit}:${repoRelativePath}`], {
+    encoding: 'utf8',
+    maxBuffer: GIT_LS_TREE_MAX_BUFFER,
+  });
+}
+
+/**
+ * Does this biome ship a runtime image subject?
+ *
+ * THE axis discriminator, declared once. A biome that ships a service or a
+ * runtime component earns image evidence, so every fact about it is pinned on
+ * the IMAGE axis and verified there (`assembleProducerInput` recomputes its
+ * `sourceManifestHash` at the image commit). A biome that ships neither can
+ * never earn image evidence, so pinning it on the image axis makes it
+ * permanently undeliverable — its content belongs on the SOURCE axis.
+ *
+ * Takes the `{ services, runtimeComponents }` shape that BOTH an index entry
+ * (`manifestToIndexEntry`) and a LOCKED biome carry, so the two consumers that
+ * must agree about this cannot drift: a second copy of the predicate is a
+ * second answer to the question the whole two-axis split turns on.
+ */
+export function biomeShipsRuntimeImage(entry) {
+  return (
+    (entry.services?.length ?? 0) > 0 ||
+    (entry.runtimeComponents?.length ?? 0) > 0
+  );
+}
+
+async function committedBiomeManifests(sourceRepositories, sourceAuthority) {
+
+
+const repositories = sourceRepositories.map((repository) => ({
+    ...repository,
+    commit: sourceAuthority.commitForRepository(repository.repo),
+    // The SOURCE axis, for the second pass below.
+    vendoredCommit: sourceAuthority.vendoredSourceCommitForRepository(repository.repo),
+  }));
+  const manifests = [];
+  for (const { repo, directory, commit } of repositories) {
+    manifests.push(...listBiomeManifestsAt(directory, repo, commit));
+  }
+
+  // ── SECOND PASS: CONTENT-ONLY BIOMES ARE READ ON THE SOURCE AXIS ──
+  //
+  // The pass above reads every manifest at the IMAGE commit, and for a biome
+  // that SHIPS A SERVICE that is exactly right: `resolve-images` pairs this
+  // biome's `sourceManifestHash` with that repository's image commit, and
+  // `assembleProducerInput` verifies the hash by recomputing it AT that commit.
+  // Move those and every image-producing service fails verification.
+  //
+  // A CONTENT-ONLY biome has no image subject, so nothing verifies it — and
+  // that same property is why it was undeliverable: it can never earn image
+  // evidence, so the image-evidence commit could never carry its changes. Its
+  // content belongs on the SOURCE axis, which is the commit whose bytes are
+  // actually vendored into whichever image carries it.
+  //
+  // Measured 2026-09-14: `memory-maintenance` (services: [], runtimeComponents:
+  // []) had migrated `modelClass` -> `modelLane`; the fix sat on cultivars' main
+  // while the image pin was 130 commits behind, and biome-host crashlooped in
+  // production on the retired key for 21 hours.
+  //
+  // Producing-ness is decided by PROJECTING the manifest through
+  // `manifestToIndexEntry` rather than re-deriving it here — one authority for
+  // "does this biome ship an image", not two that can disagree.
+  //
+  // This pass also lets a NEW content-only biome appear with no image build at
+  // all, which is the other half of the same defect.
+  let replaced = 0;
+  let added = 0;
+  for (const { repo, directory, commit, vendoredCommit } of repositories) {
+    if (!vendoredCommit || vendoredCommit === commit) {continue;}
+    for (const candidate of listBiomeManifestsAt(directory, repo, vendoredCommit)) {
+      let entry;
+      try {
+        entry = await manifestToIndexEntry(candidate);
+      } catch {
+        // A manifest that will not project is not this pass's problem to
+        // report: the image-axis pass above raises on it with its own message.
+        continue;
+      }
+      if (biomeShipsRuntimeImage(entry)) {continue;}
+      const at = manifests.findIndex((existing) => existing.rel === candidate.rel);
+      if (at === -1) {
+        manifests.push(candidate);
+        added += 1;
+      } else {
+        manifests[at] = candidate;
+        replaced += 1;
+      }
+    }
+  }
+  // A CORPUS LINE, because this pass is invisible in its output when the two
+  // axes happen to agree — which is the normal case and was the case on the run
+  // that introduced it: zero content-only manifests differed, so a no-op and a
+  // working pass produce byte-identical indexes. Printing what it SELECTED is
+  // the only thing that distinguishes them, and a future regression to
+  // `replaced=0` is then visible rather than silent.
+  console.log(
+    `[dist:index] source axis: ${replaced} content-only biome(s) re-read at the ` +
+      `vendored commit, ${added} added that exist only there ` +
+      `(${repositories.filter((r) => r.vendoredCommit && r.vendoredCommit !== r.commit).length} ` +
+      `repositor(y/ies) where the axes differ).`,
+  );
+  return manifests.sort((a, b) => compareStrings(a.rel, b.rel));
+}
+
+/**
+ * Validate a service component's `protocol.databaseExtensions` the way the
+ * kernel manifest schema does — an array of names matching the kernel's
+ * extension-name GRAMMAR, with no repeats — and return it SORTED and
+ * de-duplicated for the index. The predicate is read from the built kernel
+ * dist so this plane cannot admit a name the kernel refuses, or refuse one it
+ * admits.
+ *
+ * AN OPEN VOCABULARY, VALIDATED BY GRAMMAR — never a closed set. A PostgreSQL
+ * extension name is owned by whoever runs the database, so a closed kernel enum
+ * would produce members nothing can satisfy and would have to grow once per
+ * customer: the same defect that deleted `DataResidency.Eu`. The kernel says so
+ * itself — `PostgresExtensionNameSchema` is `z.string().regex(...)` and its
+ * docstring reads "An OPEN vocabulary validated by GRAMMAR".
+ *
+ * This function previously read `Object.values(PostgresExtension)` and required
+ * every entry to be a member. That export has never existed on any kernel
+ * branch, so the biome-index build could not run at all while any manifest
+ * declared the field, and its error blamed a stale dist. The consequence was
+ * silent and total: the field reached ZERO of 62 subjects in the sealed lock.
+ *
+ * WHAT THIS DOES NOT DECIDE. Grammar admission is not installation permission.
+ * Whether a deployment may install a given extension is
+ * `infra.yaml#postgres.allowedExtensions`, enforced by the privileged bootstrap
+ * — so a cloud tenant cannot install ad-hoc extensions even though the contract
+ * can express any name. Contract breadth and runtime authority are separate
+ * axes and this plane only carries the first.
+ *
+ * Throws naming the manifest and the component (`label`), because the index
+ * build is where a manifest that would strand a database at boot should fail:
+ * the runtime bootstrap only VERIFIES `pg_extension`, so a name nothing can
+ * install is a pod that never comes up, discovered at the first deploy.
+ */
+export function parseDatabaseExtensions(value, label) {
+  const { isPostgresExtensionName, POSTGRES_EXTENSION_NAME_PATTERN, POSTGRES_EXTENSION_NAME_MAX_LENGTH } =
+    loadKernelBiomeContracts();
+  const grammar =
+    `${String(POSTGRES_EXTENSION_NAME_PATTERN)}, at most ` +
+    `${POSTGRES_EXTENSION_NAME_MAX_LENGTH} characters`;
+  if (!Array.isArray(value)) {
+    throw new Error(
+      `${label} has protocol.databaseExtensions ${JSON.stringify(value)} — ` +
+        `expected an array of PostgreSQL extension names (${grammar})`,
+    );
+  }
+  const seen = new Set();
+  for (const extension of value) {
+    if (typeof extension !== 'string' || !isPostgresExtensionName(extension)) {
+      throw new Error(
+        `${label} has protocol.databaseExtensions entry ` +
+          `${JSON.stringify(extension)} — not a PostgreSQL extension NAME the ` +
+          `kernel grammar admits (${grammar}). The vocabulary is open, so this ` +
+          `is a malformed name rather than an unlisted one; whether this ` +
+          `deployment may install it is infra.yaml#postgres.allowedExtensions`,
+      );
+    }
+    if (seen.has(extension)) {
+      throw new Error(
+        `${label} repeats "${extension}" in protocol.databaseExtensions — ` +
+          `an extension is declared once`,
+      );
+    }
+    seen.add(extension);
+  }
+  return [...seen].sort(compareStrings);
+}
+
+/**
+ * Read + minimally validate a raw `xema-biome.json` and project it into one
+ * index entry. Fail-fast (throws) on missing id/scope/target or an unknown
+ * tier. The full biome-manifest zod schema is NOT applied here — the index only
+ * needs the packaging-relevant fields and must tolerate the wide variety of
+ * (already-valid) manifests in the tree.
+ */
+/**
+ * The process facts of ONE platform-scheduled image component, in the exact
+ * shape the kernel's `LockedServiceProcessFactsSchema` carries:
+ * `{ componentKind, scalingMode, processFacts? }`.
+ *
+ * The same three inputs the kernel's `deriveProcessMemberFacts` reads off a
+ * component (`kind`, `requirements.scaling.mode`, `processFacts`) — the rest
+ * of a member's facts (origin, version, build source) already travel in the
+ * lock and are joined by the deploy plane. Nothing is defaulted: a missing or
+ * unknown scaling class REFUSES, naming the manifest, because a guessed class
+ * bounds a process's replicas and the kernel requires the field on every
+ * component. `processFacts` is validated by the kernel's own schema so the
+ * index can never carry a block the lock schema would then refuse.
+ */
+function componentProcessFacts(component, where) {
+  const kernel = loadKernelBiomeContracts();
+  const scalingMode = component.requirements?.scaling?.mode;
+  if (!Object.values(kernel.BiomeScalingMode).includes(scalingMode)) {
+    throw new Error(
+      `${where} declares requirements.scaling.mode "${String(scalingMode)}" — ` +
+        `expected one of ${Object.values(kernel.BiomeScalingMode).join(', ')}. ` +
+        'The scaling class is what bounds a process\'s replicas, so it is read, never defaulted.',
+    );
+  }
+  const facts = { componentKind: component.kind, scalingMode };
+  if (component.processFacts !== undefined) {
+    const parsed = kernel.BiomeComponentProcessFactsSchema.safeParse(
+      component.processFacts,
+    );
+    if (!parsed.success) {
+      throw new Error(
+        `${where} declares an invalid processFacts block: ` +
+          parsed.error.issues
+            .map((issue) => `[${issue.path.join('.')}] ${issue.message}`)
+            .join('; '),
+      );
+    }
+    facts.processFacts = parsed.data;
+  }
+  return facts;
+}
+
+export async function manifestToIndexEntry({ raw, generatedIndex, rel, repo, path, authorizationModule }) {
+  const xema = raw?.xema;
+  if (!xema || typeof xema !== 'object') {
+    throw new Error(`${rel}: missing top-level "xema" object`);
+  }
+  const id = xema.id;
+  const tier = xema.scope;
+  const target = xema.target;
+  if (typeof id !== 'string' || id.length === 0) {
+    throw new Error(`${rel}: missing or empty xema.id`);
+  }
+  if (typeof tier !== 'string' || tier.length === 0) {
+    throw new Error(`${rel}: missing or empty xema.scope (the biome tier)`);
+  }
+  if (!isBiomeTier(tier)) {
+    throw new Error(
+      `${rel}: xema.scope "${tier}" is not a valid BiomeTier (one of ${biomeTierOrder().join(', ')})`,
+    );
+  }
+  if (typeof target !== 'string' || target.length === 0) {
+    throw new Error(`${rel}: missing or empty xema.target`);
+  }
+
+  const version = raw.version;
+  if (typeof version !== 'string' || version.length === 0) {
+    throw new Error(`${rel}: missing or empty top-level "version"`);
+  }
+
+  const origin = xema.trustTier ?? 'third-party';
+  // `mandatory` is NOT a manifest field — it is a distribution decision applied
+  // at resolve time from the `mandatory` selector flag (kernel-tier is always
+  // mandatory). The index carries only manifest-intrinsic facts.
+  const audience = xema.audience ?? 'org';
+  // Resolved by the KERNEL predicate, never read raw — it applies two derived
+  // refusals (operator audience, kernel tier) that a raw read silently skips.
+  const storeListed = loadKernelBiomeContracts().isBiomeStoreListed(raw);
+
+  // Deployable service names this biome ships (manifest `ships.apis[].name`).
+  // This is the biome→service mapping the deploy-roster generator needs; it is
+  // baked into the index (and forwarded into the lock) because the generator
+  // runs in a standalone checkout WITHOUT the biome sources. Pure skill/agent
+  // biomes and web biomes have no API and resolve to [].
+  const shipsApis = xema.ships?.apis;
+  const legacyApis = Array.isArray(shipsApis) ? shipsApis : [];
+  // component-contract-v5 shape: every image the biome ships is a
+  // `xema.components[]` entry whose `kind` is "service" or "worker" and whose
+  // `artifact.kind` is "oci-image". The remaining kinds (content, web, adapter,
+  // and any host-module service) are loaded INTO another process and ship no
+  // image of their own. This is DUAL SUPPORT for the staged ships.apis →
+  // components migration, not a fallback.
+  //
+  // WHICH PLANE SCHEDULES the image is read from the component's `scheduler`
+  // — the ONE owner of that fact, declared by the biome author. It is not
+  // derivable from anything else here: the four `kind: "worker"` components in
+  // xema-base are byte-identical in `entrypoint`, `protocol`, `executionModes`,
+  // `requirements.scaling`, `requirements.io` and `requirements.state`, yet
+  // three are standing Deployments and one must never be scheduled at all.
+  //
+  // Reading only `kind === "service"` (which this did until the contract regained
+  // the discriminator) silently reclassified five image subjects: it dropped the
+  // three platform-scheduled workers out of the roster entirely, dropped
+  // `opencode-worker` out of the image plane altogether, and PROMOTED
+  // `biome-adapter-host` to a rostered service that would have been given a
+  // Deployment it must never have.
+  const components = Array.isArray(xema.components) ? xema.components : [];
+  const hostModuleComponents = components.filter(
+    (component) =>
+      component !== null &&
+      typeof component === 'object' &&
+      component.artifact?.kind === 'host-module',
+  );
+  const hostModules = hostModuleComponents
+    .map((component) => {
+      if (target !== 'server') {
+        throw new Error(
+          `${rel}: web biome "${id}" cannot ship host module "${String(component.key)}"`,
+        );
+      }
+      if (!xema.bundleSource || typeof xema.bundleSource !== 'object') {
+        throw new Error(
+          `${rel}: host module "${String(component.key)}" requires xema.bundleSource; ` +
+            'a distribution host cannot fetch an executable from catalog prose or a source-tree path',
+        );
+      }
+      if (
+        component.entrypoint?.kind !== 'module-export' ||
+        typeof component.entrypoint.module !== 'string' ||
+        component.entrypoint.module.length === 0 ||
+        typeof component.entrypoint.exportName !== 'string' ||
+        component.entrypoint.exportName.length === 0
+      ) {
+        throw new Error(
+          `${rel}: host module "${String(component.key)}" must declare a non-empty module-export entrypoint`,
+        );
+      }
+      if (
+        typeof component.artifact.path !== 'string' ||
+        component.artifact.path.length === 0 ||
+        typeof component.hostAbi?.name !== 'string' ||
+        component.hostAbi.name.length === 0 ||
+        typeof component.hostAbi?.versionRange !== 'string' ||
+        component.hostAbi.versionRange.length === 0
+      ) {
+        throw new Error(
+          `${rel}: host module "${String(component.key)}" must declare artifact.path and hostAbi`,
+        );
+      }
+      return {
+        componentKey: component.key,
+        artifactPath: component.artifact.path,
+        modulePath: component.entrypoint.module,
+        exportName: component.entrypoint.exportName,
+        hostAbi: {
+          name: component.hostAbi.name,
+          versionRange: component.hostAbi.versionRange,
+        },
+        bundleSource: xema.bundleSource,
+      };
+    })
+    .sort((left, right) => compareStrings(left.componentKey, right.componentKey));
+  // The BIOME-LEVEL bundle source — `xema.bundleSource`, WHERE the runtime
+  // fetches this biome's bundle — for a biome whose bundle nothing above
+  // already names.
+  //
+  // Until this existed the manifest's declaration reached the lock in exactly
+  // one place: `hostModules[].bundleSource`, once per host module, because the
+  // only runtime consumer that fetched a distribution-selected bundle was the
+  // shared adapter host. A biome shipping `components[].kind = service` and no
+  // host module — the `pai-core` / `document-translation` shape in the
+  // customer edition — declared an `oci` source in its
+  // manifest and reached biome-host with NONE, so the required-biome
+  // reconciler reported it UNRESOLVABLE. Nothing at the runtime may guess the
+  // coordinate instead: `xema biome publish` pushes to the manifest's declared
+  // `ociRef` while `bundle-coordinate.mjs` derives `<registry>/<id>:<hash>`,
+  // and a third rule matching one of them today fetches a DIFFERENT signed
+  // bundle by the same publisher the day either moves, and fails nothing.
+  //
+  // STATED ONCE PER BIOME, and that is the byte-stability property: a biome
+  // that ships host modules keeps its source on each host module, unchanged,
+  // and gains NO biome-level key. Measured at `origin/develop`: the seventeen
+  // manifests that declare `xema.bundleSource` are all connector biomes with a
+  // host module, so every committed index entry and all nine committed vendor
+  // locks are byte-identical under this projection. Emitting it for those too
+  // would be the same value stated twice and would re-stamp five vendor locks
+  // to lock schemaVersion 4 — a fleet rollout, not a projection. A reader
+  // that wants one answer for any biome reads the biome-level field first and
+  // falls back to the host-module projection (biome-host's
+  // `resolveLockedBiomeBundleSource`).
+  //
+  // Validated by the KERNEL's own `BiomeBundleSourceSpecSchema` — the one
+  // shape the lock reuses — so a malformed declaration fails HERE, naming the
+  // manifest, rather than at `parseDistributionLock` forty fields in.
+  let bundleSource;
+  if (xema.bundleSource !== undefined && hostModules.length === 0) {
+    const parsed = loadKernelBiomeContracts().BiomeBundleSourceSpecSchema.safeParse(
+      xema.bundleSource,
+    );
+    if (!parsed.success) {
+      throw new Error(
+        `${rel}: xema.bundleSource is not a valid biome bundle source: ` +
+          parsed.error.issues
+            .map((issue) => `[${issue.path.join('.')}] ${issue.message}`)
+            .join('; '),
+      );
+    }
+    bundleSource = parsed.data;
+  }
+  const imageComponents = components.filter(
+    (component) =>
+      component !== null &&
+      typeof component === 'object' &&
+      (component.kind === 'service' || component.kind === 'worker') &&
+      (component.artifact?.kind === 'oci-image' ||
+        // A worker running its sibling service's image with its own entry
+        // module is a standing workload like any other image component — it is
+        // rostered, has process facts, task queues and peers — it just builds
+        // no image of its own. `workerImages` below records whose it runs.
+        (component.kind === 'worker' &&
+          component.artifact?.kind === 'shared-oci-image')),
+  );
+  // A worker is a standing workload that runs an image: its own oci-image or a
+  // sibling service's (shared-oci-image, validated by `sharedImageWorker`).
+  // A worker with neither would be rostered by nothing and ship no image.
+  const imagelessWorkers = components.filter(
+    (component) =>
+      component !== null &&
+      typeof component === 'object' &&
+      component.kind === 'worker' &&
+      !imageComponents.includes(component),
+  );
+  if (imagelessWorkers.length > 0) {
+    throw new Error(
+      `${rel}: worker component(s) ${imagelessWorkers.map((component) => JSON.stringify(component.name ?? component.key ?? '?')).join(', ')} ` +
+        'resolve no worker image: a worker declares artifact.kind "oci-image" or "shared-oci-image"',
+    );
+  }
+  // A biome must declare its images in EXACTLY ONE shape. Declaring both a
+  // legacy `ships.apis[]` entry and a v5 image component is ambiguous during
+  // the staged migration — fail fast instead of guessing.
+  if (legacyApis.length > 0 && imageComponents.length > 0) {
+    throw new Error(
+      `${rel}: declares deployable images in BOTH xema.ships.apis[] (legacy) and ` +
+        `xema.components[] (component-contract-v5) — a biome must use exactly one shape`,
+    );
+  }
+  const serviceRequirements = [];
+  const services = [];
+  // `service → database key` for the few services whose key is not derivable.
+  const serviceDatabases = {};
+  // `service → PostgreSQL extensions its database must carry`, for the few
+  // services that declare any. Travels beside `serviceDatabases` into the lock,
+  // where the deployment's privileged database bootstrap reads it.
+  const serviceDatabaseExtensions = {};
+  // Images the biome ships that are never scheduled (`workload:
+  // "runtime-component"`). They are built, content-addressed, signed and
+  // mirrored exactly like a service image, but the deploy plane must never
+  // roster a release for them — so they are carried in a SEPARATE array and
+  // contribute NO service-dependency edge and NO service owner.
+  const runtimeComponents = [];
+  // Infrastructure resources each rostered component NEEDS
+  // (`protocol.resources`) and the resource kinds it PROVIDES
+  // (`protocol.providesResources`). Declared INTENT only: the resolver binds
+  // each requirement to the one provider of its kind in the edition, and the
+  // lock carries that binding as an authorization input the provider enforces.
+  // Validated by the kernel's own schemas, at index build, naming the manifest.
+  const serviceResources = [];
+  const providesResources = [];
+  // `service → what sharing a process needs to know about it`, for EVERY
+  // platform-scheduled image component — see `componentProcessFacts`.
+  const serviceProcessFacts = {};
+  // Nexus services this biome's workers PROVIDE and REQUIRE (worker protocol
+  // v2). Declared intent only, exactly like resources: the edition resolver
+  // binds each requirement to the ONE shipped provider of the same
+  // (service, version) and seals the answer in the lock's `nexusBindings`.
+  const nexusProvides = [];
+  const nexusRequires = [];
+  // `component → its task queues`, for every protocol worker/v2 component —
+  // see `componentWorkerTaskQueues`.
+  const workerTaskQueues = {};
+  // `service → the worker queues it starts workflows on` — see
+  // `componentWorkflowClients`.
+  const workflowClients = {};
+  // `worker → { imageOf, entry }` for every worker that runs a sibling
+  // service's image — see `sharedImageWorker`.
+  const workerImages = {};
+  if (imageComponents.length > 0) {
+    for (const component of imageComponents) {
+      const protocol =
+        component.protocol !== null && typeof component.protocol === 'object'
+          ? component.protocol
+          : {};
+      // A `service` registers under `protocol.serviceName`; a `worker` never
+      // registers with the service registry, so its image name is the component
+      // key. Same rule the producing repo's build plane applies — the image name
+      // is the SERVICE build arg either way.
+      const name =
+        component.kind === 'service' ? protocol.serviceName : component.key;
+      if (typeof name !== 'string' || name.length === 0) {
+        throw new Error(
+          `${rel}: xema.components[] kind "${component.kind}" component ` +
+            `"${String(component.key)}" has no image name — a service declares ` +
+            `protocol.serviceName, a worker a non-empty key`,
+        );
+      }
+      if (target !== 'server') {
+        throw new Error(
+          `${rel}: web biome "${id}" cannot own deployable image "${name}"`,
+        );
+      }
+      if (services.includes(name) || runtimeComponents.includes(name)) {
+        throw new Error(
+          `${rel}: xema.components[] declares image "${name}" more than once`,
+        );
+      }
+      const where = `${rel}: xema.components[] "${name}"`;
+      const requirements = parseComponentResourceDeclaration(
+        'ResourceRequirementsSchema',
+        protocol.resources,
+        `${where} protocol.resources`,
+      );
+      const provisions = parseComponentResourceDeclaration(
+        'ResourceProvisionsSchema',
+        protocol.providesResources,
+        `${where} protocol.providesResources`,
+      );
+      const nexus = componentNexusDeclarations(component, name, protocol, where);
+      if (component.scheduler === 'runtime') {
+        // A Nexus binding names the provider COMPONENT the deploy plane points
+        // an endpoint at, which must be a rostered image; a component launched
+        // per allocation is not one. Refused rather than dropped.
+        if (nexus.provides.length > 0 || nexus.requires.length > 0) {
+          throw new Error(
+            `${where} declares scheduler "runtime" and protocol.nexus — a Nexus ` +
+              `binding names a rostered worker, and a component that is never ` +
+              `scheduled is not one`,
+          );
+        }
+        // A resource binding is admitted against the caller's VERIFIED SERVICE
+        // identity, and a runtime component — launched per allocation — is not
+        // a rostered service that identity could name. Refused rather than
+        // dropped: a skipped declaration would reach no lock and fail nothing.
+        if (requirements.length > 0 || provisions.length > 0) {
+          throw new Error(
+            `${where} declares scheduler "runtime" and protocol.resources / ` +
+              `protocol.providesResources — a resource binding names a rostered ` +
+              `service, and a component that is never scheduled is not one`,
+          );
+        }
+        // Never scheduled, so `requiresServices` — an edge between two ROSTERED
+        // services — is meaningless on it, exactly as it was for the legacy
+        // `workload: "runtime-component"` shape.
+        if (
+          Array.isArray(protocol.requiresServices) &&
+          protocol.requiresServices.length > 0
+        ) {
+          throw new Error(
+            `${rel}: xema.components[] "${name}" declares scheduler "runtime" and ` +
+              `protocol.requiresServices — a component that is never scheduled ` +
+              `cannot carry a service-dependency edge`,
+          );
+        }
+        runtimeComponents.push(name);
+        continue;
+      }
+      if (component.scheduler !== 'platform') {
+        throw new Error(
+          `${rel}: xema.components[] "${name}" declares scheduler ` +
+            `"${String(component.scheduler)}" — every image component must declare ` +
+            `"platform" (the deploy plane rosters a standing workload) or "runtime" ` +
+            `(the runtime plane launches it on demand)`,
+        );
+      }
+      const requiredServices = protocol.requiresServices ?? [];
+      if (
+        !Array.isArray(requiredServices) ||
+        requiredServices.some(
+          (service) => typeof service !== 'string' || service.length === 0,
+        )
+      ) {
+        throw new Error(
+          `${rel}: xema.components[] "${name}" protocol.requiresServices must be an ` +
+            `array of non-empty service names`,
+        );
+      }
+      // The shared-biome-cluster database key this service opens, declared ONLY
+      // when it is neither the biome id nor the service name minus `-api`.
+      // org-database-pool-api's ownership fence can derive those two and nothing
+      // else, so a service whose schema name outlived a rename
+      // (`scm-connector-api` → schema `scm-integration`) is unreachable unless
+      // the component says so. The v5 spelling is `protocol.databaseKey`; the
+      // legacy one below is `ships.apis[].database`.
+      if (protocol.databaseKey !== undefined) {
+        if (
+          typeof protocol.databaseKey !== 'string' ||
+          !/^[a-z][a-z0-9-]*$/.test(protocol.databaseKey)
+        ) {
+          throw new Error(
+            `${rel}: xema.components[] "${name}" has protocol.databaseKey ` +
+              `"${String(protocol.databaseKey)}" — expected lowercase kebab-case ` +
+              `(it becomes a Postgres schema name)`,
+          );
+        }
+        serviceDatabases[name] = protocol.databaseKey;
+      }
+      // The PostgreSQL extensions this service's database must carry BEFORE its
+      // first migration runs (`protocol.databaseExtensions`, the sibling of
+      // `databaseKey`). A database-level prerequisite the deployment's
+      // privileged bootstrap satisfies, never something the service creates —
+      // so it has to travel from the manifest to the lock, which is the one
+      // artifact the deploy plane reads without the biome sources. Validated
+      // here exactly as the kernel manifest schema does (closed set, no
+      // repeats), because this projection reads the RAW manifest and the full
+      // kernel schema is deliberately not applied on this path. ABSENT and
+      // `[]` make the same claim — no extension — and project to no key.
+      //
+      // Deliberately NO legacy `ships.apis[]` spelling: that shape predates the
+      // field, and every service that has an extension requirement is on the
+      // component contract.
+      if (protocol.databaseExtensions !== undefined) {
+        const extensions = parseDatabaseExtensions(
+          protocol.databaseExtensions,
+          `${rel}: xema.components[] "${name}"`,
+        );
+        if (extensions.length > 0) {
+          serviceDatabaseExtensions[name] = extensions;
+        }
+      }
+      for (const requirement of requirements) {
+        serviceResources.push({
+          consumerService: name,
+          kind: requirement.kind,
+          logicalName: requirement.logicalName,
+          scope: requirement.scope,
+          inclusion: requirement.inclusion,
+        });
+      }
+      for (const provision of provisions) {
+        providesResources.push({ service: name, kind: provision.kind });
+      }
+      nexusProvides.push(...nexus.provides);
+      nexusRequires.push(...nexus.requires);
+      services.push(name);
+      serviceProcessFacts[name] = componentProcessFacts(component, where);
+      const queues = componentWorkerTaskQueues(component, protocol, where);
+      if (queues !== null) {workerTaskQueues[name] = queues;}
+      const clients = componentWorkflowClients(protocol, where);
+      if (clients !== null) {workflowClients[name] = clients;}
+      const shared = sharedImageWorker(component, components, where);
+      if (shared !== null) {workerImages[name] = shared;}
+      serviceRequirements.push({
+        consumerService: name,
+        requiredServices: [...new Set(requiredServices)].sort(compareStrings),
+      });
+    }
+  } else {
+    for (const api of legacyApis) {
+      if (!api || typeof api.name !== 'string' || api.name.length === 0) {
+        throw new Error(
+          `${rel}: xema.ships.apis[] entry is missing a non-empty "name"`,
+        );
+      }
+      if (target !== 'server') {
+        throw new Error(
+          `${rel}: web biome "${id}" cannot own deployable API service "${api.name}"`,
+        );
+      }
+      const workload = api.workload ?? DEFAULT_BIOME_WORKLOAD_KIND;
+      if (!BIOME_WORKLOAD_KINDS.has(workload)) {
+        throw new Error(
+          `${rel}: xema.ships.apis[] "${api.name}" has unknown workload ` +
+            `"${String(workload)}" — expected one of ${[...BIOME_WORKLOAD_KINDS].join(', ')}`,
+        );
+      }
+      if (workload === 'runtime-component') {
+        // A runtime component has no standing workload, so `requiresServices`
+        // (an edge between two ROSTERED services) is meaningless on it.
+        if (
+          Array.isArray(api.requiresServices) &&
+          api.requiresServices.length > 0
+        ) {
+          throw new Error(
+            `${rel}: xema.ships.apis[] "${api.name}" declares workload ` +
+              `"runtime-component" and requiresServices — a component that is never ` +
+              `scheduled cannot carry a service-dependency edge`,
+          );
+        }
+        runtimeComponents.push(api.name);
+        continue;
+      }
+      const requiredServices = api.requiresServices ?? [];
+      if (
+        !Array.isArray(requiredServices) ||
+        requiredServices.some(
+          (service) => typeof service !== 'string' || service.length === 0,
+        )
+      ) {
+        throw new Error(
+          `${rel}: xema.ships.apis[] "${api.name}" requiresServices must be an array of non-empty service names`,
+        );
+      }
+      services.push(api.name);
+      // The shared-biome-cluster database key this service opens, declared ONLY
+      // when it is neither the biome id nor the service name minus `-api`.
+      // org-database-pool-api's ownership fence can derive those two and
+      // nothing else, so a service whose schema name outlived a rename
+      // (`scm-connector-api` → schema `scm-integration`) is unreachable unless
+      // the biome says so here. Carried into the lock, which is where the fence
+      // reads it — a distribution-time fact, never a request-time claim.
+      if (api.database !== undefined) {
+        if (typeof api.database !== 'string' || !/^[a-z][a-z0-9-]*$/.test(api.database)) {
+          throw new Error(
+            `${rel}: xema.ships.apis[] "${api.name}" has database ` +
+              `"${String(api.database)}" — expected lowercase kebab-case (it becomes a Postgres schema name)`,
+          );
+        }
+        serviceDatabases[api.name] = api.database;
+      }
+      serviceRequirements.push({
+        consumerService: api.name,
+        requiredServices: [...new Set(requiredServices)].sort(compareStrings),
+      });
+    }
+  }
+  services.sort(compareStrings);
+  runtimeComponents.sort(compareStrings);
+  serviceRequirements.sort((a, b) =>
+    compareStrings(a.consumerService, b.consumerService),
+  );
+  serviceResources.sort(compareResourceRows);
+  nexusProvides.sort(compareNexusRows);
+  nexusRequires.sort(compareNexusRows);
+  providesResources.sort(
+    (a, b) => compareStrings(a.service, b.service) || compareStrings(a.kind, b.kind),
+  );
+  // The provider derives a resource's PHYSICAL identity from the owning biome
+  // plus (kind, scope, logicalName). Two consumers of this biome naming the
+  // same tuple would be handed ONE physical resource while each believes it
+  // owns it — so the declaration is refused here, where the biome is the whole
+  // subject, rather than discovered at the provider.
+  const physicalResources = new Map();
+  for (const row of serviceResources) {
+    const identity = `${row.kind}\0${row.scope}\0${row.logicalName}`;
+    const holder = physicalResources.get(identity);
+    if (holder !== undefined && holder !== row.consumerService) {
+      throw new Error(
+        `${rel}: services "${holder}" and "${row.consumerService}" both declare ` +
+          `${row.scope}-scoped ${row.kind} "${row.logicalName}" — biome "${id}" ` +
+          `derives ONE physical resource from that, so two consumers would share ` +
+          `it while each believes it owns it. Give each its own logicalName.`,
+      );
+    }
+    physicalResources.set(identity, row.consumerService);
+  }
+  // The two arrays partition the biome's images — a name in both would be
+  // simultaneously rostered and unschedulable.
+  for (const name of runtimeComponents) {
+    if (services.includes(name)) {
+      throw new Error(
+        `${rel}: xema.ships.apis[] "${name}" is declared both as a service and ` +
+          `as a runtime component — an image is either scheduled or it is not`,
+      );
+    }
+  }
+
+  // Biomes this one REQUIRES, read from the committed generated index rather
+  // than restated in the manifest.
+  //
+  // This used to union three manifest fields: `xema.dependencies` (server
+  // biomes), `xema.requires` (an object form NO manifest has ever declared and
+  // the strict schema now rejects — dead, and deleted with this change), and
+  // `xema.requiresServerBiomes` (web biomes). That last one was never authored:
+  // it was a generator-owned projection of "package dependencies ∩ generated
+  // api-clients whose owner is a server biome". A web biome carries no
+  // `xema.dependencies`, so it was the ONLY producer of `requires` for a web
+  // biome — reading it after the field was deleted would silently produce
+  // `requires: []`, which makes `requiresServerBiomesSatisfied` permanently
+  // true and kills orphan detection outright.
+  //
+  // `requiredBiomeDependencyIds` answers the same question for BOTH targets
+  // from one typed, evidence-carrying edge set: `xema.dependencies` for server
+  // biomes and the derived client edges for web ones, filtered to
+  // kind=biome + strength=required (service/connector/capability/host-abi edges
+  // and optional edges are excluded by construction). Parsing with the kernel
+  // schema first means a malformed or foreign index fails here rather than
+  // resolving to an empty list.
+  const kernelBiome = loadKernelBiomeContracts();
+  let parsedIndex;
+  try {
+    parsedIndex = kernelBiome.BiomeBundleGeneratedIndexSchema.parse(generatedIndex);
+  } catch (error) {
+    throw new Error(
+      `${rel}: the committed ${BIOME_GENERATED_INDEX_FILENAME} is not a valid generated index: ${error.message}`,
+    );
+  }
+  if (parsedIndex.biome.biomeId !== id) {
+    throw new Error(
+      `${rel}: ${BIOME_GENERATED_INDEX_FILENAME} declares biomeId "${parsedIndex.biome.biomeId}" but the ` +
+        `manifest declares "${id}" — the index does not describe this biome`,
+    );
+  }
+  if (parsedIndex.biome.version !== version) {
+    throw new Error(
+      `${rel}: ${BIOME_GENERATED_INDEX_FILENAME} declares version "${parsedIndex.biome.version}" but the ` +
+        `manifest declares "${version}" — the index is stale; run \`pnpm derive:biome-index:write\``,
+    );
+  }
+  // Already de-duplicated and sorted by the kernel helper.
+  const requiresUnique = [...kernelBiome.requiredBiomeDependencyIds(parsedIndex.biome)];
+
+  // Optional server biomes a web biome can integrate with but does not require
+  // (never cause an ORPHANED resolution). Carried separately from `requires`.
+  const optionalServerBiomes = Array.isArray(xema.optionalServerBiomes)
+    ? [...new Set(xema.optionalServerBiomes)].sort()
+    : [];
+
+  // Capability DOMAINS this biome claims to own (manifest
+  // `xema.ownsCapabilityDomains`). The claim is carried verbatim into the index
+  // and then into the lock, where — and ONLY where — it becomes trustworthy:
+  // being present in a RESOLVED, COMMITTED, drift-checked lock makes ownership a
+  // distribution-author decision rather than a biome's self-declaration. See
+  // `first-party-capability-domains.ts` in @xemahq/contracts.
+  //
+  // The claim is EXPLICIT — it never defaults to `capabilityDomain` or `id`. An
+  // implicit default would silently make every locked biome first-party in its
+  // own id-domain, which would newly REFUSE org provider bindings that are
+  // legitimately org-bound today (e.g. `media:transcribe@1`).
+  const ownsCapabilityDomains = Array.isArray(xema.ownsCapabilityDomains)
+    ? [...new Set(xema.ownsCapabilityDomains)].sort(compareStrings)
+    : [];
+  for (const domain of ownsCapabilityDomains) {
+    if (typeof domain !== 'string' || !/^[a-z][a-z0-9-]*$/.test(domain)) {
+      throw new Error(
+        `${rel}: xema.ownsCapabilityDomains contains ${JSON.stringify(domain)}, ` +
+          `which is not a valid capability domain (^[a-z][a-z0-9-]*$)`,
+      );
+    }
+  }
+  // A biome that declares a projection domain MUST also own it — otherwise it
+  // projects refs into a domain any org could shadow with a provider binding.
+  if (
+    typeof xema.capabilityDomain === 'string' &&
+    xema.capabilityDomain.length > 0 &&
+    !ownsCapabilityDomains.includes(xema.capabilityDomain)
+  ) {
+    throw new Error(
+      `${rel}: xema.capabilityDomain "${xema.capabilityDomain}" is not listed in ` +
+        `xema.ownsCapabilityDomains [${ownsCapabilityDomains.join(', ')}] — a biome that ` +
+        `projects capabilities into a domain must also claim ownership of it.`,
+    );
+  }
+
+  // --- Catalog projection (consumed by biome-host's DistributionCatalogSource) ---
+  // The index/lock is the single source of truth for the biome CATALOG (which
+  // biomes exist + the facts the web/server registry DTOs need), replacing the
+  // filesystem-scan + vendored-manifest path. We carry the RAW manifest fields
+  // the catalog derivation needs; biome-host applies the SAME `@xemahq/biome-sdk`
+  // helpers (isSystemSurface / isBiomeStoreListed / defaultEnabledFor) it already
+  // uses, so the derivation logic lives in exactly one place (no reimplementation
+  // here, no drift).
+  const displayName =
+    typeof xema.displayName === 'string' && xema.displayName.length > 0
+      ? xema.displayName
+      : id;
+  // npm/workspace package name. For WEB biomes this is the SPA's import specifier
+  // (load-bearing) — required. For server biomes it is cosmetic.
+  const packageName = typeof raw.name === 'string' ? raw.name : null;
+  if (target === 'web' && !packageName) {
+    throw new Error(
+      `${rel}: web biome is missing a top-level "name" (the SPA import specifier).`,
+    );
+  }
+  // Raw `xema.display` block (icon/category/summary/accent), passed through
+  // verbatim; absent → omitted.
+  const display =
+    xema.display && typeof xema.display === 'object' ? xema.display : undefined;
+  // Raw `xema.systemSurface` flag (renders in the org rail vs the store). Only a
+  // boolean is meaningful; absence is normal and handled by the sdk helper.
+  const systemSurface =
+    typeof xema.systemSurface === 'boolean' ? xema.systemSurface : undefined;
+  // Content-addressed source-manifest hash — lets biome-host (and diagnostics)
+  // detect when a biome's authored manifest changed, distinct from distribution
+  // resolution. Hash of the canonical manifest JSON.
+  const { computeBiomeSourceManifestHash } = await loadKernelDistributionSchemas();
+  const sourceManifestHash = await computeBiomeSourceManifestHash(raw);
+
+  // --- Installation class (the `{ installationClass }` selector's input) -----
+  // HOW ESSENTIAL this biome is, folded from its components' declarations by
+  // the KERNEL's `foldInstallationClass` — most essential wins. The fold is not
+  // re-implemented here for the same reason `storeListed` calls
+  // `isBiomeStoreListed`: a second implementation of a kernel rule is a second
+  // answer waiting to drift, and this one decides whether a biome is on an
+  // edition's FLOOR.
+  //
+  // The class is declared per COMPONENT and selected per BIOME because the
+  // biome is the unit a distribution installs. Measured on 2026-09-05 across
+  // all 34 classified manifests in repos/xema-base: NO biome mixes classes
+  // across its runnable components, so today the fold is exact rather than
+  // lossy. It is still a fold, and the kernel's docblock says which direction
+  // it takes and why.
+  //
+  // OMITTED when no component declares a class — the third answer, never a
+  // default. That also keeps the index byte-stable for every biome that
+  // declares nothing, which at `origin/main` is currently all of them.
+  const installationClass = kernelBiome.foldInstallationClass(
+    components.map((component) =>
+      component !== null && typeof component === 'object'
+        ? component.installationClass
+        : undefined,
+    ),
+  );
+
+  return {
+    id,
+    tier,
+    target,
+    origin,
+    version,
+    audience,
+    storeListed,
+    // The kernel fold of the components' own declarations; OMITTED when none
+    // declares one (see above), so an unclassed biome stays byte-stable.
+    ...(installationClass !== undefined ? { installationClass } : {}),
+    services,
+    // Omitted when empty — which is almost every biome — so the index stays
+    // byte-stable for everything that needs no declaration.
+    ...(Object.keys(serviceDatabases).length > 0
+      ? {
+          serviceDatabases: Object.fromEntries(
+            Object.entries(serviceDatabases).sort(([a], [b]) =>
+              compareStrings(a, b),
+            ),
+          ),
+        }
+      : {}),
+    // Same omission rule as `serviceDatabases`, for the same reason: at
+    // `origin/main` no manifest declares an extension, so an unconditional key
+    // would move the bytes of every one of the ~117 entries for a fact none of
+    // them carries.
+    ...(Object.keys(serviceDatabaseExtensions).length > 0
+      ? {
+          serviceDatabaseExtensions: Object.fromEntries(
+            Object.entries(serviceDatabaseExtensions).sort(([a], [b]) =>
+              compareStrings(a, b),
+            ),
+          ),
+        }
+      : {}),
+    runtimeComponents,
+    hostModules,
+    // Omitted when the biome declares none, or when its host modules already
+    // carry it — see the projection above. At `origin/develop` that is every
+    // committed entry, which is what keeps `biome-index.json` byte-stable.
+    ...(bundleSource !== undefined ? { bundleSource } : {}),
+    // The biome's authorization module (plan biome-declared-authorization.md
+    // §2.1): the author's SOURCE manifest `{ envelope, moduleFiles, testFile }`
+    // and the `signedBiome` facts the sealer STAMPS onto it with the kernel's
+    // `stampAuthorizationModuleContribution` — derived here, from this pinned
+    // manifest and its generated index, never from the author's envelope.
+    // Omitted when the biome ships none — every committed biome today — so
+    // `biome-index.json` stays byte-stable.
+    ...(authorizationModule !== undefined
+      ? {
+          authorizationModule: {
+            source: authorizationModule,
+            signedBiome: {
+              tier,
+              declaredBiomeDependencies: requiresUnique,
+              serviceNames: [
+                ...new Set(
+                  (Array.isArray(xema.components) ? xema.components : [])
+                    .map((component) => component?.protocol?.serviceName)
+                    .filter((name) => typeof name === 'string' && name.length > 0),
+                ),
+              ].sort(compareStrings),
+            },
+          },
+        }
+      : {}),
+    serviceRequirements,
+    // Omitted when empty — which is every biome today — so the index stays
+    // byte-stable for everything that declares nothing.
+    ...(serviceResources.length > 0 ? { serviceResources } : {}),
+    ...(providesResources.length > 0 ? { providesResources } : {}),
+    // Omitted when empty — every committed biome today — so the index stays
+    // byte-stable for everything that declares no Nexus service.
+    ...(nexusProvides.length > 0 ? { nexusProvides } : {}),
+    ...(nexusRequires.length > 0 ? { nexusRequires } : {}),
+    // The v2 workers' task queues; omitted when the biome ships none (every
+    // committed biome today), so the index stays byte-stable.
+    ...(Object.keys(workerTaskQueues).length > 0
+      ? {
+          workerTaskQueues: Object.fromEntries(
+            Object.entries(workerTaskQueues).sort(([a], [b]) => compareStrings(a, b)),
+          ),
+        }
+      : {}),
+    // The queues each http service starts workflows on; omitted when no
+    // component declares any, so the index stays byte-stable.
+    ...(Object.keys(workflowClients).length > 0
+      ? {
+          workflowClients: Object.fromEntries(
+            Object.entries(workflowClients).sort(([a], [b]) => compareStrings(a, b)),
+          ),
+        }
+      : {}),
+    // The workers that run a sibling service's image with their own entry
+    // module; omitted when the biome has none, so the index stays byte-stable.
+    ...(Object.keys(workerImages).length > 0
+      ? {
+          workerImages: Object.fromEntries(
+            Object.entries(workerImages).sort(([a], [b]) => compareStrings(a, b)),
+          ),
+        }
+      : {}),
+    // Every platform-scheduled image this biome ships, with the facts a
+    // composed process is graded on. Present for EVERY service of a
+    // component-contract biome — a service declaring nothing still gets its
+    // derived `componentKind` + `scalingMode`, because absent facts are what
+    // the kernel grades as `unknown-member`. Omitted only when the biome ships
+    // no platform-scheduled image (and for the retired `ships.apis[]` shape,
+    // which declares no scaling class to read).
+    ...(Object.keys(serviceProcessFacts).length > 0
+      ? {
+          serviceProcessFacts: Object.fromEntries(
+            Object.entries(serviceProcessFacts).sort(([a], [b]) =>
+              compareStrings(a, b),
+            ),
+          ),
+        }
+      : {}),
+    // The biome's signed dependency contract — DERIVED by the builder from the
+    // SDK seams its code calls, read from the committed generated index and
+    // validated there by the kernel schema. The edge set positive closure
+    // closes over. Omitted when the biome has not adopted one, which is every
+    // committed biome today, so `biome-index.json` stays byte-stable; a
+    // positive-closure edition REFUSES a root or required biome that lacks it.
+    ...(parsedIndex.biome.dependencyContract === undefined
+      ? {}
+      : { dependencyContract: parsedIndex.biome.dependencyContract }),
+    repo,
+    path,
+    requires: requiresUnique,
+    // --- catalog projection ---
+    // Omitted entirely when the biome claims nothing, so the index stays stable
+    // for the overwhelming majority of biomes that own no domain.
+    ...(ownsCapabilityDomains.length > 0 ? { ownsCapabilityDomains } : {}),
+    displayName,
+    packageName,
+    optionalServerBiomes,
+    ...(display ? { display } : {}),
+    ...(systemSurface !== undefined ? { systemSurface } : {}),
+    sourceManifestHash,
+  };
+}
+
+/**
+ * Build the full biome index (array of entries) by walking every manifest.
+ * Sorted deterministically by (tier order, id, target, repo).
+ */
+function buildServiceOwners(entries, platformServiceIndex) {
+  const serviceOwners = new Map();
+  const registerOwner = (serviceName, owner, sourceDescription) => {
+    const existing = serviceOwners.get(serviceName);
+    if (existing !== undefined) {
+      throw new Error(
+        `service "${serviceName}" has ambiguous owners: ${existing.sourceDescription} and ${sourceDescription}`,
+      );
+    }
+    serviceOwners.set(serviceName, { owner, sourceDescription });
+  };
+  for (const entry of entries) {
+    for (const serviceName of entry.services) {
+      registerOwner(
+        serviceName,
+        {
+          kind: 'biome',
+          biomeId: entry.id,
+          target: entry.target,
+          repo: entry.repo,
+          path: entry.path,
+          version: entry.version,
+          sourceManifestHash: entry.sourceManifestHash,
+        },
+        `biome "${entry.id}" (${entry.target}@${entry.repo}/${entry.path})`,
+      );
+    }
+  }
+  for (const source of platformServiceIndex.services) {
+    registerOwner(
+      source.name,
+      { kind: 'platform', source },
+      `platform service (${source.sourceCommit}@${source.repo}/${source.path})`,
+    );
+  }
+  return serviceOwners;
+}
+
+export function resolveServiceDependencyOwners(entries, platformServiceIndex) {
+  const serviceOwners = buildServiceOwners(entries, platformServiceIndex);
+  for (const entry of entries) {
+    const serviceDependencies = [];
+    for (const requirement of entry.serviceRequirements) {
+      for (const requiredService of requirement.requiredServices) {
+        const resolved = serviceOwners.get(requiredService);
+        if (!resolved) {
+          throw new Error(
+            `biome "${entry.id}" API "${requirement.consumerService}" requires unknown service "${requiredService}"`,
+          );
+        }
+        if (
+          resolved.owner.kind === 'biome' &&
+          resolved.owner.target !== 'server'
+        ) {
+          throw new Error(
+            `biome "${entry.id}" API "${requirement.consumerService}" requires service "${requiredService}" ` +
+              `owned by cross-target ${resolved.owner.target} biome "${resolved.owner.biomeId}"`,
+          );
+        }
+        serviceDependencies.push({
+          consumerService: requirement.consumerService,
+          requiredService,
+          owner: resolved.owner,
+        });
+      }
+    }
+    serviceDependencies.sort((a, b) => {
+      const consumer = compareStrings(a.consumerService, b.consumerService);
+      return consumer === 0
+        ? compareStrings(a.requiredService, b.requiredService)
+        : consumer;
+    });
+    entry.serviceDependencies = serviceDependencies;
+    delete entry.serviceRequirements;
+  }
+  return entries;
+}
+
+/**
+ * Offline parity guard for the committed index: every recorded edge must still
+ * name the one canonical owner identity carried by that same index plus the
+ * committed platform-service index.
+ */
+export function validateServiceDependencyOwnerParity(
+  entries,
+  platformServiceIndex,
+) {
+  const serviceOwners = buildServiceOwners(entries, platformServiceIndex);
+  for (const entry of entries) {
+    if (!Array.isArray(entry.serviceDependencies)) {
+      throw new Error(
+        `biome "${entry.id}" has no serviceDependencies projection`,
+      );
+    }
+    for (const edge of entry.serviceDependencies) {
+      const canonical = serviceOwners.get(edge.requiredService);
+      if (!canonical) {
+        throw new Error(
+          `biome "${entry.id}" API "${edge.consumerService}" requires unknown service "${edge.requiredService}"`,
+        );
+      }
+      if (
+        canonical.owner.kind === 'biome' &&
+        canonical.owner.target !== 'server'
+      ) {
+        throw new Error(
+          `biome "${entry.id}" API "${edge.consumerService}" requires cross-target service "${edge.requiredService}"`,
+        );
+      }
+      if (serializeJson(edge.owner) !== serializeJson(canonical.owner)) {
+        throw new Error(
+          `biome "${entry.id}" API "${edge.consumerService}" service "${edge.requiredService}" ` +
+            `owner identity does not match ${canonical.sourceDescription}`,
+        );
+      }
+    }
+  }
+  return entries;
+}
+
+export async function buildBiomeIndex(
+  platformServiceIndex,
+  sourceRepositories = distributionBiomeSourceRepositories(),
+  sourceAuthority,
+) {
+  const authority =
+    sourceAuthority ??
+    createSourceAuthority({
+      knownRepositories: sourceRepositories.map(({ repo }) => repo),
+    });
+  const entries = [];
+  for (const manifest of await committedBiomeManifests(sourceRepositories, authority)) {
+    entries.push(await manifestToIndexEntry(manifest));
+  }
+  resolveServiceDependencyOwners(entries, platformServiceIndex);
+  assertDeclaredDatabasesUnowned(entries);
+  entries.sort(compareIndexEntries);
+  return entries;
+}
+
+/**
+ * A declared `serviceDatabases` key must name a database NOTHING else in the
+ * platform already answers to.
+ *
+ * This is the bound on the entitlement. org-database-pool-api hands out the
+ * shared cluster's credential for whatever key the caller is entitled to, and
+ * the two derived entitlements (biome id, service name minus `-api`) are
+ * self-evidently non-transferable because they are derivations of the caller's
+ * own verified identity. A DECLARED key is not — it is a free string in a
+ * manifest — so the only thing that keeps it from naming `llm-registry` is
+ * this check. The pool re-asserts it when it loads the lock; failing here too
+ * means a manifest that would strand or hijack a database fails the build
+ * instead of the fleet.
+ */
+export function assertDeclaredDatabasesUnowned(entries) {
+  const claimedBy = new Map();
+  for (const entry of entries) {
+    claimedBy.set(entry.id, `biome "${entry.id}"`);
+  }
+  for (const entry of entries) {
+    for (const service of entry.services ?? []) {
+      claimedBy.set(service.replace(/-api$/, ''), `service "${service}"`);
+    }
+  }
+  for (const entry of entries) {
+    for (const [service, key] of Object.entries(entry.serviceDatabases ?? {})) {
+      if (key === service.replace(/-api$/, '') || key === entry.id) {
+        // Already reachable by derivation; the declaration widens nothing.
+        continue;
+      }
+      const claimant = claimedBy.get(key);
+      if (claimant !== undefined) {
+        throw new Error(
+          `biome "${entry.id}" declares database "${key}" for service ` +
+            `"${service}", but "${key}" is already the database of ${claimant}. ` +
+            `A declared database must name one no other biome or service owns — ` +
+            `otherwise the declaration hands "${service}" another principal's schema.`,
+        );
+      }
+      claimedBy.set(key, `service "${service}"`);
+    }
+  }
+}
+
+/**
+ * Build the `capabilityDomainOwners` reservation table from the FULL biome
+ * index — every biome the packaging pipeline discovered, NOT the subset an
+ * edition selects.
+ *
+ * WHY THE FULL INDEX (this is the whole point of the table):
+ *
+ *   Ownership is a property of the PLATFORM, not of what an edition happens to
+ *   preload. If the table were built from the selected set, a trimmed edition
+ *   (`minimal`, `appliance-lean`) that ships without `knowledge-base` would
+ *   leave `kb` unowned — and an org admin could then install `knowledge-base`
+ *   from the store and bind `kb:page.read@1` to a URL they control, silently
+ *   shadowing the platform data plane. Being AUTHORED by a first-party biome is
+ *   what makes a domain un-shadowable; whether a given edition preloads that
+ *   biome is a packaging choice and must never change the security answer.
+ *
+ *   So every edition gets the IDENTICAL table. A domain is reserved even when
+ *   its owning biome is absent from the lock — that is precisely the case the
+ *   reservation exists to cover.
+ *
+ * Sorted by `domain` for deterministic, diffable output.
+ *
+ * @throws when two biomes claim the same domain. Ambiguous ownership decides
+ * whether an org may bind refs under the domain, so it has no safe resolution
+ * and must fail the build rather than pick a winner.
+ */
+export function buildCapabilityDomainOwners(index) {
+  const owners = new Map();
+  for (const entry of index) {
+    for (const domain of entry.ownsCapabilityDomains ?? []) {
+      const incumbent = owners.get(domain);
+      if (incumbent !== undefined && incumbent !== entry.id) {
+        throw new Error(
+          `capability domain "${domain}" is claimed by BOTH biome "${incumbent}" and biome "${entry.id}". ` +
+            `A domain has exactly one owner — ownership decides whether an org may bind refs in it, ` +
+            `so an ambiguous claim is refused.`,
+        );
+      }
+      owners.set(domain, entry.id);
+    }
+  }
+  return [...owners.entries()]
+    .map(([domain, biomeId]) => ({ domain, biomeId }))
+    .sort((a, b) => compareStrings(a.domain, b.domain));
+}
+
+/** Deterministic ordering used for both the index and the lock. */
+export function compareIndexEntries(a, b) {
+  const order = biomeTierOrder();
+  const ta = order.indexOf(a.tier);
+  const tb = order.indexOf(b.tier);
+  if (ta !== tb) {return ta - tb;}
+  if (a.id !== b.id) {return a.id < b.id ? -1 : 1;}
+  if (a.target !== b.target) {return a.target < b.target ? -1 : 1;}
+  if (a.repo !== b.repo) {return a.repo < b.repo ? -1 : 1;}
+  return 0;
+}
+
+/** Stable JSON serialization (pretty, trailing newline) for committed files. */
+export function serializeJson(value) {
+  return `${JSON.stringify(value, null, 2)}\n`;
+}
+
+/**
+ * Shared generated-artifact currency gate. Callers supply canonical serialized
+ * bytes; any authority change must make a previously committed projection fail.
+ */
+export function assertGeneratedArtifactCurrent(
+  label,
+  committed,
+  generated,
+  regenerateCommand,
+) {
+  if (committed !== generated) {
+    throw new Error(
+      `${label} is out of date. Run \`${regenerateCommand}\`.`,
+    );
+  }
+}
+
+/** sha256 hex of a string. */
+export function sha256Hex(input) {
+  return createHash('sha256').update(input).digest('hex');
+}
+
+const EXACT_SEMVER_PATTERN =
+  /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-(?:(?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*)(?:\.(?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*))*))?(?:\+(?:[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?$/;
+const IMAGE_REPOSITORY_SEGMENT_PATTERN =
+  /^[a-z0-9]+(?:(?:[._]|__|-+)[a-z0-9]+)*$/;
+const MAX_REGISTRY_HOST_LENGTH = 253;
+const MAX_DNS_LABEL_LENGTH = 63;
+const MAX_REPOSITORY_PATH_LENGTH = 255;
+
+function isCanonicalRegistryPort(port) {
+  if (port === undefined) {return true;}
+  if (!/^[0-9]+$/.test(port)) {return false;}
+  const numericPort = Number(port);
+  return numericPort >= 1 && numericPort <= 65535;
+}
+
+function isCanonicalDnsHost(host) {
+  if (
+    host.length === 0 ||
+    host.length > MAX_REGISTRY_HOST_LENGTH ||
+    host !== host.toLowerCase() ||
+    host.endsWith('.')
+  ) {
+    return false;
+  }
+  if (/^[0-9.]+$/.test(host)) {return isIP(host) === 4;}
+  const labels = host.split('.');
+  return labels.every(
+    (label) =>
+      label.length >= 1 &&
+      label.length <= MAX_DNS_LABEL_LENGTH &&
+      /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/.test(label),
+  );
+}
+
+export function isCanonicalRegistryAuthority(authority) {
+  if (authority.startsWith('[')) {
+    const closingBracket = authority.indexOf(']');
+    if (closingBracket < 0) {return false;}
+    const address = authority.slice(1, closingBracket);
+    const suffix = authority.slice(closingBracket + 1);
+    if (
+      address.length === 0 ||
+      address !== address.toLowerCase() ||
+      isIP(address) !== 6
+    ) {
+      return false;
+    }
+    if (suffix.length === 0) {return true;}
+    return suffix.startsWith(':') && isCanonicalRegistryPort(suffix.slice(1));
+  }
+
+  const firstColon = authority.indexOf(':');
+  const lastColon = authority.lastIndexOf(':');
+  if (firstColon !== lastColon) {return false;}
+  const host = lastColon < 0 ? authority : authority.slice(0, lastColon);
+  const port = lastColon < 0 ? undefined : authority.slice(lastColon + 1);
+  return isCanonicalDnsHost(host) && isCanonicalRegistryPort(port);
+}
+
+function isUntaggedImageRepository(imageRef) {
+  if (
+    typeof imageRef !== 'string' ||
+    imageRef.length === 0 ||
+    imageRef.trim() !== imageRef ||
+    imageRef.includes('@') ||
+    imageRef.includes('://') ||
+    imageRef.includes('//') ||
+    imageRef.endsWith('/')
+  ) {
+    return false;
+  }
+  const [authority, ...segments] = imageRef.split('/');
+  const repositoryPath = segments.join('/');
+  if (
+    segments.length === 0 ||
+    repositoryPath.length > MAX_REPOSITORY_PATH_LENGTH ||
+    !isCanonicalRegistryAuthority(authority) ||
+    segments.some(
+      (segment) =>
+        segment.includes(':') ||
+        !IMAGE_REPOSITORY_SEGMENT_PATTERN.test(segment),
+    )
+  ) {
+    return false;
+  }
+  return true;
+}
+
+export const IMAGE_PRODUCER_EVIDENCE_PREREQUISITE =
+  'a complete authorized signed image-producer evidence set that binds the ' +
+  'exact distribution inputHash, source repository commit, sourceManifestHash, ' +
+  'source-tree contentHash, image repository, OCI manifest digest, complete ' +
+  'platform set, SBOM, provenance, distribution release, and customer entitlement';
+
+/**
+ * Enforce the immutable fields carried by the existing DistributionLock
+ * schema. The kernel schema owns the shape; this packaging-plane guard owns
+ * the stronger provenance invariant: a resolved lock may contain only exact
+ * versions and full sha256 source-manifest identities.
+ */
+export function validateImmutableBiomeIndex(index) {
+  for (const biome of index) {
+    if (!EXACT_SEMVER_PATTERN.test(biome.version)) {
+      throw new Error(
+        `biome "${biome.id}" has mutable or invalid ` +
+          `version "${biome.version}" — resolved locks require an exact semantic version`,
+      );
+    }
+    if (!SHA256_HEX_PATTERN.test(biome.sourceManifestHash)) {
+      throw new Error(
+        `biome "${biome.id}" has invalid ` +
+          `sourceManifestHash "${String(biome.sourceManifestHash)}" — expected 64 lowercase sha256 hex characters`,
+      );
+    }
+    const services = new Set();
+    for (const service of biome.services ?? []) {
+      if (services.has(service)) {
+        throw new Error(
+          `biome "${biome.id}" owns duplicate service "${service}"`,
+        );
+      }
+      services.add(service);
+    }
+    // Runtime components are built/signed/mirrored like services but never
+    // rostered. They must be a disjoint set from `services` — a name in both
+    // would be simultaneously scheduled and unschedulable.
+    const runtimeComponents = new Set();
+    for (const component of biome.runtimeComponents ?? []) {
+      if (runtimeComponents.has(component)) {
+        throw new Error(
+          `biome "${biome.id}" owns duplicate runtime component "${component}"`,
+        );
+      }
+      if (services.has(component)) {
+        throw new Error(
+          `biome "${biome.id}" declares "${component}" both as a service and as a ` +
+            `runtime component — an image is either scheduled or it is not`,
+        );
+      }
+      runtimeComponents.add(component);
+    }
+    const edges = new Set();
+    for (const edge of biome.serviceDependencies ?? []) {
+      if (!services.has(edge.consumerService)) {
+        throw new Error(
+          `biome "${biome.id}" service dependency names unknown consumer API "${edge.consumerService}"`,
+        );
+      }
+      const edgeKey = `${edge.consumerService}\0${edge.requiredService}`;
+      if (edges.has(edgeKey)) {
+        throw new Error(
+          `biome "${biome.id}" has duplicate service dependency ${edge.consumerService} -> ${edge.requiredService}`,
+        );
+      }
+      edges.add(edgeKey);
+      if (edge.owner?.kind === 'biome') {
+        if (edge.owner.target !== 'server') {
+          throw new Error(
+            `biome "${biome.id}" service dependency ${edge.consumerService} -> ${edge.requiredService} ` +
+              `has cross-target ${String(edge.owner.target)} owner`,
+          );
+        }
+        if (!EXACT_SEMVER_PATTERN.test(edge.owner.version)) {
+          throw new Error(
+            `biome "${biome.id}" service dependency owner "${edge.owner.biomeId}" has invalid exact version`,
+          );
+        }
+        if (!SHA256_HEX_PATTERN.test(edge.owner.sourceManifestHash)) {
+          throw new Error(
+            `biome "${biome.id}" service dependency owner "${edge.owner.biomeId}" has invalid sourceManifestHash`,
+          );
+        }
+      } else if (edge.owner?.kind === 'platform') {
+        if (edge.owner.source?.name !== edge.requiredService) {
+          throw new Error(
+            `biome "${biome.id}" service dependency ${edge.consumerService} -> ${edge.requiredService} ` +
+              `has mismatched platform owner "${String(edge.owner.source?.name)}"`,
+          );
+        }
+      } else {
+        throw new Error(
+          `biome "${biome.id}" service dependency ${edge.consumerService} -> ${edge.requiredService} has no recognized owner`,
+        );
+      }
+    }
+  }
+  return index;
+}
+
+/**
+ * The distribution lock as the resolve pipeline reads it: the UNSEALED
+ * document a resolve just wrote, or the SEALED v5 lock a prior seal committed.
+ * Both carry the same body; the kernel's two parsers each refuse the other
+ * shape, so this dispatches on the document's own marker and never guesses.
+ * A pre-v5 lock is refused by the kernel (`unsupported-schema-version`).
+ */
+export function parseResolvedDistributionLock(schemas, raw) {
+  return raw !== null && typeof raw === 'object' && 'unsealedSchema' in raw
+    ? schemas.parseUnsealedDistributionLock(raw)
+    : schemas.parseDistributionLockForReading(raw);
+}
+
+/**
+ * The text two distribution locks are compared by: the UNSEALED projection of
+ * each, with the resolve timestamp removed. A committed lock is sealed (v5) and
+ * a fresh resolve is unsealed; the kernel's `unsealedProjection` maps the first
+ * onto the shape of the second (its key order is stable, so the comparison is
+ * byte for byte). Anything that is not one of the two v5 shapes is refused by
+ * the kernel's parsers, a pre-v5 lock with `unsupported-schema-version`.
+ */
+export function comparableDistributionLock(schemas, raw) {
+  const unsealed = schemas.parseUnsealedDistributionLock(
+    raw !== null && typeof raw === 'object' && 'unsealedSchema' in raw
+      ? raw
+      : schemas.unsealedProjection(schemas.parseDistributionLock(raw)),
+  );
+  const { resolvedAt: _resolvedAt, ...rest } = unsealed;
+  return serializeJson(rest);
+}
+
+export function validateImmutableDistributionLock(lock) {
+  if (!SHA256_HEX_PATTERN.test(lock.inputHash)) {
+    throw new Error(
+      `distribution "${lock.distributionId}" has invalid inputHash "${String(lock.inputHash)}" — ` +
+        'expected 64 lowercase sha256 hex characters',
+    );
+  }
+  try {
+    validateImmutableBiomeIndex(lock.biomes ?? []);
+  } catch (error) {
+    throw new Error(`distribution "${lock.distributionId}": ${error.message}`, {
+      cause: error,
+    });
+  }
+  return lock;
+}
+
+/**
+ * Enforce source-addressed image identities after canonical ImageLock parsing.
+ * `imageRef` is deliberately an untagged repository; the immutable build tag
+ * is the exact sha256 `contentHash` under the lock's explicit hash algorithm.
+ */
+export function validateImmutableImageLock(lock, schemas) {
+  if (!schemas) {
+    throw new Error('trusted kernel distribution schemas are required');
+  }
+  if (
+    lock.schemaVersion !== 3 ||
+    lock.sourceHashAlgorithm !== schemas.ImageSourceHashAlgorithm.ImageInputV2
+  ) {
+    throw new Error(
+      `distribution "${lock.distributionId}" has incompatible image-lock schema ${String(lock.schemaVersion)} ` +
+        `and sourceHashAlgorithm "${String(lock.sourceHashAlgorithm)}"`,
+    );
+  }
+  const identities = new Set();
+  for (const subject of lock.subjects ?? []) {
+    const identity = `${subject.kind}\0${subject.id}`;
+    if (identities.has(identity)) {
+      throw new Error(
+        `distribution "${lock.distributionId}" has duplicate runtime image subject "${subject.kind}:${subject.id}"`,
+      );
+    }
+    identities.add(identity);
+    if (!isUntaggedImageRepository(subject.imageRef)) {
+      throw new Error(
+        `distribution "${lock.distributionId}": runtime subject "${subject.kind}:${subject.id}" has mutable or invalid ` +
+          `imageRef "${subject.imageRef}" — expected an untagged image repository`,
+      );
+    }
+    if (!SHA256_HEX_PATTERN.test(subject.contentHash)) {
+      throw new Error(
+        `distribution "${lock.distributionId}": runtime subject "${subject.kind}:${subject.id}" has invalid ` +
+          `contentHash "${String(subject.contentHash)}" — expected 64 lowercase sha256 hex characters`,
+      );
+    }
+    const owners = new Set();
+    for (const owner of subject.owners ?? []) {
+      const key = serializeJson(owner);
+      if (owners.has(key)) {
+        throw new Error(
+          `distribution "${lock.distributionId}": runtime subject "${subject.kind}:${subject.id}" has a duplicate owner`,
+        );
+      }
+      owners.add(key);
+    }
+  }
+  const platformServices = new Set();
+  for (const binding of lock.platformServiceBindings ?? []) {
+    if (platformServices.has(binding.platformService)) {
+      throw new Error(
+        `distribution "${lock.distributionId}" has duplicate runtime image binding for platform service "${binding.platformService}"`,
+      );
+    }
+    platformServices.add(binding.platformService);
+    if (!identities.has(`${binding.subjectKind}\0${binding.subjectId}`)) {
+      throw new Error(
+        `distribution "${lock.distributionId}": platform service "${binding.platformService}" binds unknown runtime subject "${binding.subjectKind}:${binding.subjectId}"`,
+      );
+    }
+  }
+  return lock;
+}
+
+export function canonicalPublicHttpsRepositoryUrl(raw, context) {
+  if (typeof raw !== 'string' || raw.length === 0 || raw.trim() !== raw) {
+    throw new Error(`${context} must be a non-empty canonical HTTPS URL`);
+  }
+  let parsed;
+  try {
+    parsed = new URL(raw);
+  } catch {
+    throw new Error(`${context} is not a valid URL`);
+  }
+  if (parsed.protocol !== 'https:') {
+    throw new Error(`${context} must use HTTPS`);
+  }
+  if (parsed.username.length > 0 || parsed.password.length > 0) {
+    throw new Error(
+      `${context} must not contain username/password credentials`,
+    );
+  }
+  if (
+    parsed.search.length > 0 ||
+    parsed.hash.length > 0 ||
+    raw.includes('?') ||
+    raw.includes('#')
+  ) {
+    throw new Error(`${context} must not contain a query or fragment`);
+  }
+  if (parsed.hostname.length === 0) {
+    throw new Error(`${context} must identify a repository host`);
+  }
+  return parsed.toString();
+}
+
+/**
+ * Assert that an exact 40-hex commit exists in a source repository. Delegates
+ * to `@xemahq/distribution-source-hash` — the tooling holds no second copy of
+ * the Git-object reader the content hash is built on.
+ */
+export function assertGitCommitExists(repoDir, commit) {
+  return distributionSourceHash().assertGitCommitExists(repoDir, commit);
+}
+
+/** Split the NUL-delimited output of a `-z` Git plumbing command. */
+function decodeNullDelimitedGitRecords(raw, context) {
+  return distributionSourceHash().decodeNullDelimitedGitRecords(raw, context);
+}
+
+/**
+ * Hash the immutable tree of an exact Git commit — a distribution image
+ * subject's `contentHash`, and therefore its published image tag.
+ */
+export function hashGitSourceTree(
+  repoDir,
+  repoRelativeSourcePath,
+  commit,
+  algorithm,
+) {
+  return distributionSourceHash().hashGitSourceTree(
+    repoDir,
+    repoRelativeSourcePath,
+    commit,
+    algorithm,
+  );
+}
+
+/**
+ * Every workspace package in a repository at an exact commit, keyed by name.
+ *
+ * Delegates to `@xemahq/distribution-source-hash`. The tooling holds no second
+ * copy of the workspace-graph reader: it is derived by walking the commit's
+ * tree for `package.json` files rather than by expanding `pnpm-workspace.yaml`
+ * globs, and a hand-rolled YAML parser on the critical path of a release
+ * coordinate is exactly what that package exists to avoid.
+ */
+export function workspacePackagesAtCommit(repoDir, commit, tree) {
+  return distributionSourceHash().workspacePackagesAtCommit(repoDir, commit, tree);
+}
+
+/**
+ * The path index of one commit's tree — the input `workspacePackagesAtCommit`
+ * scans for `package.json` files.
+ *
+ * Exposed so a caller can build it ONCE per repository and reuse it across
+ * every biome in that repository. Building it per biome would re-read the whole
+ * tree 123 times for one index.
+ */
+export function gitCommitTreeIndex(repoDir, commit) {
+  return distributionSourceHash().GitCommitTreeIndex.atCommit(repoDir, commit);
+}
+
+/**
+ * The transitive workspace-package closure of one package directory, EXCLUDING
+ * the root — the root is hashed separately as its own source tree, so
+ * including it would frame one digest twice.
+ *
+ * Returns `[]` for a directory that is not a workspace member at all. For a
+ * BIOME that is the correct answer and not a gap: a biome with no
+ * `package.json` runs no build, so nothing outside its directory can change its
+ * bundle's bytes. `check-biome-bundle-closure-derivable` pins the premise that
+ * makes that true — a biome shipping BUILT OUTPUT always has a manifest.
+ */
+export function workspaceClosure(rootDirectory, graph, commit) {
+  return distributionSourceHash().workspaceClosure(rootDirectory, graph, commit);
+}
+
+/**
+ * Length-framed hash update — the same framing the image content hash uses.
+ *
+ * Framing is not decoration: without it, two different component lists can
+ * concatenate to identical bytes and collide onto one coordinate. Delegated
+ * rather than re-implemented for that reason.
+ */
+export function updateFramedHash(hash, field, value) {
+  return distributionSourceHash().updateFramedHash(hash, field, value);
+}
+
+/**
+ * Hash the FULL build-input closure of one service image — the subject's
+ * `contentHash`, and therefore its published image tag.
+ *
+ * Delegates to `@xemahq/distribution-source-hash`, which is the same code every
+ * producing repository's CI runs to derive the tag it pushes. The tooling holds
+ * no second copy: a divergence would resolve a lock whose images sit at a
+ * coordinate nothing published.
+ */
+export function hashImageBuildInputs(request, algorithm) {
+  return distributionSourceHash().hashImageBuildInputs(request, algorithm);
+}
+
+/**
+ * Read + parse a JSON file out of an exact Git commit (never the work tree).
+ *
+ * This is the seam every authored source file crosses on its way into a lock
+ * or an index — `xema-biome.json`, a platform service's `package.json`,
+ * `cross-repo-build-inputs.json`, the committed generated biome index — so it
+ * parses STRICTLY: a duplicated object key is refused, naming the commit, the
+ * path and the JSON pointer of the object. `JSON.parse` would keep the last
+ * occurrence, which is how a `resources` declaration was dropped from a sealed
+ * lock with every reader agreeing (see `strict-json.mjs`).
+ *
+ * The commit check, the buffer ceiling and the exact-UTF-8 decode are the
+ * source-hash package's own; only the parse differs from its
+ * `readGitJsonAtCommit`, which is lenient and is therefore not delegated to.
+ */
+export function readGitJsonAtCommit(repoDir, repoRelativePath, commit) {
+  const sourceHash = distributionSourceHash();
+  sourceHash.assertGitCommitExists(repoDir, commit);
+  let raw;
+  try {
+    raw = execFileSync(
+      'git',
+      ['-C', repoDir, 'show', `${commit}:${repoRelativePath}`],
+      {
+        encoding: 'buffer',
+        maxBuffer: sourceHash.GIT_OBJECT_MAX_BUFFER_BYTES,
+        stdio: ['ignore', 'pipe', 'pipe'],
+      },
+    );
+  } catch {
+    throw new Error(
+      `cannot read "${repoRelativePath}" from Git commit "${commit}"`,
+    );
+  }
+  const context = `Git object "${commit}:${repoRelativePath}"`;
+  return parseStrictJson(sourceHash.decodeExactUtf8(raw, context), context);
+}
+
+/**
+ * The producing repository's OWN committed record of what it vendored.
+ *
+ * `vendor-cross-repo-inputs.mjs` reads exactly this file, at the commit being
+ * built, to emit the `--vendored <dest>=<repoDir>@<commit>:<src>` arguments it
+ * hands `compute-image-tag.mjs`. It is therefore the ONLY source of the vendored
+ * commit that can agree with the tag CI pushes.
+ */
+export const CROSS_REPO_BUILD_INPUTS_PATH =
+  'tooling/release/cross-repo-build-inputs.json';
+
+/** Identity of one vendored input — the tuple that survives a pin bump. */
+export function crossRepoInputKey(input) {
+  return [input.sourceRepo, input.sourcePath, input.destinationPath].join('\u0000');
+}
+
+/**
+ * Resolve the vendored inputs of ONE consumer repository at ONE commit.
+ *
+ * WHY THE COMMIT COMES FROM THE CONSUMER, NOT FROM THE INDEX
+ *
+ * The index's `crossRepoBuildInputs` carry no `sourceCommit`; they name only
+ * WHICH content is vendored. Both this tooling and the parity gate used to
+ * supply the missing commit from `runtimeSourceIndex.repositoryPins`, and CI
+ * supplies it from the file above — so the two disagreed the moment a consumer
+ * repository's mirror lagged the index by one pin, which is its NORMAL resting
+ * state: the mirror is generated FROM the index and committed separately, so it
+ * is stale by construction between the index moving and the consumer
+ * regenerating.
+ *
+ * That is not a cosmetic disagreement. `crossRepo.sourceCommit` is framed into
+ * the component KEY of the image-input hash, so a pin that differs by one
+ * commit yields a different `contentHash` FOR BYTE-IDENTICAL VENDORED CONTENT —
+ * a coordinate no CI run has ever pushed or ever will. Measured 2026-09-07 on
+ * `origin/main`: five of the sixty-eight coordinates in the eight editions
+ * (`backlog-api`, `channel-gateway-api`, `control-plane-api`,
+ * `document-render-api` from repos/xema-community, and `biome-host-api` from
+ * repos/xema-base) 404'd in the registry for exactly this reason, while the tags
+ * their producing CI DID push were present and served on both platforms.
+ *
+ * Reading the index pin also imposed a requirement that cannot be satisfied.
+ * `repos/xema-base` vendors from `repos/xema-community` and vice versa, so
+ * "every mirror agrees with the index" is a mutual fixed point over a 2-cycle,
+ * and bumping either side invalidates the other. No such pair exists: scanning
+ * eighty commits of each on `origin/main` found ZERO mutually coherent pairs.
+ * Reading the consumer's own record removes the fixed point entirely — an
+ * image's identity depends only on the repository that builds it.
+ *
+ * It stays edition-INDEPENDENT, which is the property the previous design was
+ * protecting: the record is a property of the consumer's COMMIT, not of any
+ * edition's resolved commit map, so every edition shipping a subject still
+ * derives the same `contentHash` for it.
+ */
+export function resolveCrossRepoVendoredInputs({
+  indexInputs,
+  consumerRepo,
+  consumerRepoDir,
+  consumerCommit,
+}) {
+  const declared = indexInputs.filter(
+    (input) => input.consumerRepo === consumerRepo,
+  );
+  if (declared.length === 0) {return [];}
+  if (!consumerCommit) {
+    throw new Error(
+      `cross-repo build inputs are declared for "${consumerRepo}", but this ` +
+        `distribution resolves no commit for it — the vendored content cannot ` +
+        `be pinned, so the image cannot be addressed`,
+    );
+  }
+  let record;
+  try {
+    record = readGitJsonAtCommit(
+      consumerRepoDir,
+      CROSS_REPO_BUILD_INPUTS_PATH,
+      consumerCommit,
+    );
+  } catch (cause) {
+    throw new Error(
+      `"${consumerRepo}" declares cross-repo build inputs but ` +
+        `${CROSS_REPO_BUILD_INPUTS_PATH} is unreadable at ${consumerCommit}. ` +
+        `That file is what its CI feeds to compute-image-tag.mjs; without it ` +
+        `no coordinate this tooling derives can match the tag CI pushes.`,
+      { cause },
+    );
+  }
+  const mirrored = new Map();
+  for (const input of record?.inputs ?? []) {
+    mirrored.set(crossRepoInputKey(input), input.sourceCommit);
+  }
+  // Set equality in BOTH directions. A commit that LAGS is normal and is now
+  // honoured; a differing input SET is a genuine declaration disagreement, and
+  // it moves the hash just as surely — so it must fail rather than resolve to a
+  // coordinate built from a different closure.
+  const declaredKeys = new Set(declared.map((input) => crossRepoInputKey(input)));
+  const resolved = declared.map((input) => {
+    const sourceCommit = mirrored.get(crossRepoInputKey(input));
+    if (!sourceCommit) {
+      throw new Error(
+        `the runtime image source index declares a cross-repo build input for ` +
+          `"${consumerRepo}" vendoring "${input.sourceRepo}:${input.sourcePath}" ` +
+          `to "${input.destinationPath}", but ${CROSS_REPO_BUILD_INPUTS_PATH} at ` +
+          `${consumerCommit} declares no such input — its CI does not vendor it, ` +
+          `so the coordinate this tooling would derive is one nothing builds`,
+      );
+    }
+    return {
+      consumerService: input.consumerService ?? null,
+      destinationPath: input.destinationPath,
+      sourceRepoDir: sourcePath(input.sourceRepo),
+      sourcePath: input.sourcePath,
+      sourceCommit,
+    };
+  });
+  for (const key of mirrored.keys()) {
+    if (declaredKeys.has(key)) {continue;}
+    const [sourceRepo, sourcePath, destinationPath] = key.split('\0');
+    throw new Error(
+      `${CROSS_REPO_BUILD_INPUTS_PATH} at ${consumerCommit} vendors ` +
+        `"${sourceRepo}:${sourcePath}" to "${destinationPath}" for ` +
+        `"${consumerRepo}", which the runtime image source index does not ` +
+        `declare — its CI bakes content this tooling does not hash`,
+    );
+  }
+  return resolved;
+}