@xemahq/xema 0.26.0 → 0.28.0

package/edition/resolve-images.mjs

@@ -0,0 +1,1606 @@
+#!/usr/bin/env node
+// Resolve a distribution into schema-v3 actual runtime image subjects.
+// Services, the host shell, and independently sourced platform images are
+// subjects. Biomes remain selection/ownership units and never become fictitious
+// one-container-per-Biome build outputs.
+//
+// ── "REGENERATE AND DIFF" IS NOT A VALID CHECK ON THIS ARTIFACT ─────────────
+//
+// This resolver emits NO `imageDigest`. The digests in a committed
+// `images.lock.json` are written afterwards, by `seal-image-digests.mjs`, and
+// nothing here reproduces them. So the obvious verification — regenerate the
+// lock and diff it against the committed one — reports drift that is purely the
+// absence of a seal, on every subject, every time.
+//
+// Measured 2026-09-23 on `origin/main`, running this script unmodified against a
+// pristine checkout with two editions left alone as controls:
+//
+//   core   54 of 54 subjects carried a digest  ->  0 after; `grep -c imageDigest` = 0
+//   cloud  66 of 66                            ->  0 after
+//   minimal / oss (not re-resolved)            ->  45 and 63, untouched
+//
+// The field is ABSENT rather than emptied, on `subjects`, `platformServiceBindings`
+// and `webBiomes` alike, and no merge path carries a subset forward. Two
+// consequences, and the second is the one that costs a night:
+//
+//   - to verify a lock, compare a fresh resolve against ANOTHER fresh resolve
+//     (which cancels both the seal and the wall-clock `resolvedAt`), never
+//     against the committed file;
+//   - a re-resolve DISARMS the sealer's moved-tag refusal, which fires only when
+//     the lock being sealed already carries a digest for that subject. That is
+//     not a bypass to reach for — it is why "re-resolve then seal" and "re-seal
+//     the committed lock" are different operations with different verdicts, and
+//     anyone comparing their outcomes needs to know which one they ran.
+
+import { execFileSync } from 'node:child_process';
+import { writeFileSync } from 'node:fs';
+import { join, relative, sep } from 'node:path';
+
+import {
+  assertCanonicalDistributionId,
+  distributionOutputPath,
+  readBoundDistributionFile,
+} from './distribution-paths.mjs';
+import { editionWorkspaceConfig } from './edition-config.mjs';
+import { biomeIndexPath, editionsRoot, runtimeImageSourceIndexPath, WorkspaceRoot, configureEditionWorkspaceFromProcess, isEntryModule, sourcePath, sourcesRoot } from './edition-workspace.mjs';
+import {
+  externalSourceCacheDir,
+  materializeGitSource,
+} from './external-source-walk.mjs';
+import { assertDeclaredSourceId, firstPartySourceId } from './first-party-source-ids.mjs';
+import {
+  CROSS_REPO_BUILD_INPUTS_PATH,
+  compareStrings,
+  crossRepoInputKey,
+  hashImageBuildInputs,
+  imageInputSourceHashAlgorithm,
+  loadKernelDistributionSchemas,
+  parseResolvedDistributionLock,
+  readGitJsonAtCommit,
+  resolveCrossRepoVendoredInputs,
+  serializeJson,
+  sha256Hex,
+  validateImmutableDistributionLock,
+  validateImmutableImageLock,
+} from './lib.mjs';
+import { assertReleaseContent } from './release-channel-guard.mjs';
+import { composeEdition } from './resolve-distribution.mjs';
+import { readStrictJsonFile } from './strict-json.mjs';
+
+if (isEntryModule(import.meta.url)) {
+  configureEditionWorkspaceFromProcess([WorkspaceRoot.Data, WorkspaceRoot.Editions, WorkspaceRoot.Sources, WorkspaceRoot.Kernel, WorkspaceRoot.Cache, WorkspaceRoot.SourceHash]);
+}
+
+const firstPartyImageRegistry = () => editionWorkspaceConfig().imageRegistry;
+
+/**
+ * WHERE A LOCKED BIOME'S SOURCE TREE IS ON DISK — the one answer this plane
+ * needs, and the one thing every read in this file used to assume.
+ *
+ * Every Git read here was `sourcePath(<repo>)`, which encodes an
+ * assumption that held while every biome came from a sibling repository in the
+ * aggregator's layout: that a `repo` HANDLE IS A PATH under `sourcesRoot()`. A
+ * biome drawn from an EXTERNAL source breaks it — its `repo` is that source's
+ * own LOGICAL name (`sources[].name`), deliberately not a `repos/<x>` path,
+ * because a hosting repository's name is source-management detail and must not
+ * become a biome's provenance. `<sourcesRoot()>/<logical name>` is a directory that
+ * does not exist, so the content hash could not be computed at all.
+ *
+ * The fix is ONE locator rather than a special case per read site: a `repo`
+ * handle resolves to a checkout DIRECTORY plus the BASE its `path` is relative
+ * to. Both kinds answer the same shape — a first-party repo's paths are
+ * `sourcesRoot()`-relative, an external source's are relative to the cache the walk
+ * materialised it into — so every call site reads the same two fields and none
+ * of them knows which kind it has.
+ *
+ * WHAT THE HASH THEN COVERS IS UNCHANGED, and that is the point of routing the
+ * DIRECTORY rather than teaching the hash about sources. `hashImageBuildInputs`
+ * reads the service's own source tree, the transitive workspace-package
+ * closure, the exact Dockerfile blob the build resolves to, every file the
+ * Dockerfile copies out of the context, the filtered pnpm lock graph, the
+ * context-directory residue and any vendored cross-repo tree — all out of the
+ * Git objects of whatever repository it is handed, at an exact commit. Handing
+ * it an external checkout therefore covers that repository's FULL build input
+ * by the same construction it already covers a first-party one, with no second
+ * definition of what an image is built from.
+ *
+ * MATERIALISATION IS AT THE LOCKED COMMIT, never at the declared ref. The lock
+ * already recorded the exact commit its manifests were read at; re-resolving a
+ * ref here would let a hash be computed over a different revision than the one
+ * the edition locked, silently and in the direction nothing detects.
+ * `materializeGitSource` short-circuits an exact 40-hex ref instead of sending
+ * it to `ls-remote`, so passing the commit AS the ref is the pin rather than a
+ * re-resolution.
+ */
+export function externalSourceTrees(
+  lock,
+  { cacheRoot = externalSourceCacheDir(), materialize = materializeGitSource } = {},
+) {
+  const byRepo = new Map();
+  for (const biome of lock.biomes ?? []) {
+    if (biome.source === undefined) {continue;}
+    const name = biome.source.name;
+    const incumbent = byRepo.get(name);
+    if (incumbent) {
+      if (incumbent.commit !== biome.source.commit) {
+        throw new Error(
+          `distribution "${lock.distributionId}" pins two commits for external source ` +
+            `"${name}" (${incumbent.commit} and ${biome.source.commit}) — one source is one ` +
+            'revision, so an image built from it cannot be addressed',
+        );
+      }
+      continue;
+    }
+    byRepo.set(name, { source: biome.source, commit: biome.source.commit });
+  }
+  const trees = new Map();
+  for (const [name, { source, commit }] of byRepo) {
+    const { directory } = materialize({ source: { ...source, ref: commit }, cacheRoot });
+    trees.set(name, { dir: directory, base: cacheRoot });
+  }
+  return trees;
+}
+
+/**
+ * `repo` handle -> `{ dir, base }`.
+ *
+ * An unknown handle is FIRST-PARTY, which is the only default that can be
+ * correct: the external set is CLOSED by the lock's own `sources[]`, so
+ * anything outside it came from this fleet's layout. A handle that is neither
+ * resolves to a directory that does not exist and fails at the first Git read,
+ * naming the path — a loud failure rather than a silent fall back to an empty
+ * tree, which would hash to a coordinate nothing ever published.
+ */
+export function sourceTreeLocator(externalTrees) {
+  return (repo) =>
+    externalTrees.get(repo) ?? { dir: sourcePath(repo), base: sourcesRoot() };
+}
+
+/** The first-party-only locator — for callers that hold no lock to read. */
+const FIRST_PARTY_TREES = (repo) => ({ dir: sourcePath(repo), base: sourcesRoot() });
+const imageBuildInputHashByIdentity = new Map();
+const sourceManifestHashByIdentity = new Map();
+
+function readJson(path) {
+  return readStrictJsonFile(path);
+}
+
+/**
+ * Memoized image build-input closure hash.
+ *
+ * Every distribution that ships a service resolves the SAME closure for it, and
+ * the closure reads immutable Git objects at an exact commit, so one digest per
+ * (service, service path, commit, vendored inputs) is exact — not a cache with
+ * an invalidation story.
+ */
+function exactImageBuildInputHash(request, algorithm) {
+  const identity = serializeJson({ request, algorithm });
+  const cached = imageBuildInputHashByIdentity.get(identity);
+  if (cached) {return cached;}
+  const hash = hashImageBuildInputs(request, algorithm);
+  imageBuildInputHashByIdentity.set(identity, hash);
+  return hash;
+}
+
+function exactSourceManifestHash(
+  repoDirectory,
+  repoRelativePath,
+  sourceCommit,
+) {
+  const identity = serializeJson({
+    repoDirectory,
+    repoRelativePath,
+    sourceCommit,
+  });
+  const cached = sourceManifestHashByIdentity.get(identity);
+  if (cached) {return cached;}
+  const hash = sha256Hex(
+    serializeJson(
+      readGitJsonAtCommit(repoDirectory, repoRelativePath, sourceCommit),
+    ),
+  );
+  sourceManifestHashByIdentity.set(identity, hash);
+  return hash;
+}
+
+/**
+ * Key of one vendored input WITHIN one consumer repository.
+ *
+ * Both the store and the lookup go through this, so the two sides cannot spell
+ * the separator differently — which they did, and every lookup missed.
+ */
+function consumerInputKey(consumerRepo, input) {
+  return `${consumerRepo}\u0000${crossRepoInputKey(input)}`;
+}
+
+/**
+ * Compose one image ref: WHERE the artifact lives, and WHAT it is called.
+ *
+ * `registry` defaults to the vendor namespace because that is where everything
+ * this organisation BUILDS is published, and every caller but one wants it. The
+ * exception is a biome drawn from an external source, whose coordinate is a
+ * DECLARED fact carried on the lock (`biome.source.imageRegistry`) rather than a
+ * constant — see the biomes loop in `resolveImageStructure`.
+ *
+ * `namePrefix` is the second half of that same declared coordinate, and it is
+ * what keeps a subject's LOGICAL id separate from its PUBLISHED name. Those two
+ * are the same string for every first-party subject — measured 2026-09-15, 67
+ * of 67 deploy-manifest entries and 60 of 60 `oci-image` component keys — but
+ * that is a property of owning the whole of the first-party registry namespace, not a law. A
+ * customer organisation's namespace is flat and carries every product that
+ * customer ships, so a bare component name there identifies nothing in
+ * particular and the first collision silently overwrites somebody's tags.
+ *
+ * DEFAULTING TO THE EMPTY STRING IS THE IDENTITY ELEMENT OF CONCATENATION, not
+ * a fallback: an unqualified name is what every existing subject already gets,
+ * so the absent case reproduces today's behaviour exactly rather than
+ * substituting something. Contrast `registry`, whose absence on an external
+ * source is REFUSED in `resolveImageStructure` — there the only available
+ * default names the wrong ORG, which is a misdirection rather than a preference.
+ *
+ * Both parameters are deliberately not module-level mutables: two editions are
+ * resolved in one process by `dist:check`, and a coordinate held in module scope
+ * would leak one edition's customer namespace into the next one's subjects.
+ */
+export function imageRefForSubject(
+  subjectId,
+  registry = firstPartyImageRegistry(),
+  namePrefix = '',
+) {
+  return `${registry}/${namePrefix}${subjectId}`;
+}
+
+/**
+ * The OCI platforms one distribution requires every runtime image to ship.
+ *
+ * Read from that edition's OWN `xema-distribution.json`
+ * and projected onto image-lock platform
+ * coordinates by the kernel. This deliberately replaced a global frozen
+ * `[{linux, amd64}]` constant: with one constant, every subject of every
+ * edition declared amd64 — including `appliance-lean`/`appliance-base`, whose
+ * installer (`xema-appliance/os/dgx/install-k3s.sh`, `ansible/site.yml`) refuses
+ * any host that is not ARM64. The image plane therefore declared the one
+ * architecture the appliance could not run, and nothing in the chain could say
+ * so.
+ *
+ * The kernel owns the vocabulary and the fail-fast: an absent, empty, unknown,
+ * duplicated or misordered declaration throws here rather than resolving to a
+ * default. There is no default.
+ */
+export function resolveDistributionRequiredPlatforms(schemas, id) {
+  assertCanonicalDistributionId(id);
+  const { requiredPlatforms } = composeEdition(schemas.parseDistribution, id);
+  return schemas.resolveRuntimeImagePlatforms(requiredPlatforms);
+}
+
+/**
+ * The edition's DECLARED `sources[]`, 
+ *
+ * WHY THIS IS A PARAMETER AND NOT A LOCK FIELD. `imageNamePrefix` is producer
+ * INPUT: it composes the image NAME and is then spent, because the lock carries
+ * the fully-qualified `imageRef`. It cannot travel in the lock to reach the
+ * resolver — `DistributionLockSchema` is `.strict()` and learned that key only
+ * in `@xemahq/contracts` 0.10.0, so a pinned image resolving `^0.9.x` refuses
+ * the whole lock at boot. Persisting it took presenca-dev's three lock
+ * consumers into CrashLoopBackOff on 2026-09-17.
+ *
+ * So the producer reads its OWN declaration, and `requiredPlatforms` one
+ * function up is the precedent: a declared fact the pure structure resolver
+ * needs arrives as an argument the impure caller composes. That keeps
+ * `resolveImageStructure` pure over the committed lock and runtime index, which
+ * is what lets `dist-check` grade an images lock offline.
+ */
+export function resolveDistributionDeclaredSources(schemas, id) {
+  assertCanonicalDistributionId(id);
+  const { declaredSources } = composeEdition(schemas.parseDistribution, id);
+  return declaredSources;
+}
+
+function subjectKey(subject) {
+  return `${subject.kind}\0${subject.id}`;
+}
+
+function bindingKey(binding) {
+  return `${binding.subjectKind}\0${binding.subjectId}`;
+}
+
+function compareSubject(left, right) {
+  return (
+    compareStrings(left.kind, right.kind) || compareStrings(left.id, right.id)
+  );
+}
+
+function compareOwner(left, right) {
+  return compareStrings(serializeJson(left), serializeJson(right));
+}
+
+function addSubject(subjects, candidate) {
+  const key = subjectKey(candidate);
+  const existing = subjects.get(key);
+  if (!existing) {
+    subjects.set(key, {
+      ...candidate,
+      owners: [...candidate.owners],
+    });
+    return;
+  }
+  const withoutOwners = ({ owners: _owners, ...value }) => value;
+  if (
+    serializeJson(withoutOwners(existing)) !==
+    serializeJson(withoutOwners(candidate))
+  ) {
+    throw new Error(
+      `runtime image subject "${candidate.kind}:${candidate.id}" has conflicting source identities`,
+    );
+  }
+  const ownerKeys = new Set(existing.owners.map(serializeJson));
+  for (const owner of candidate.owners) {
+    if (!ownerKeys.has(serializeJson(owner))) {existing.owners.push(owner);}
+  }
+}
+
+/**
+ * The refusal for a SELECTED platform service whose declared artifact
+ * dependency no selected biome produces.
+ *
+ * The edge is DECLARED, never inferred from a name: a platform service's
+ * `runtimeBinding` (platform-service-source-authority.mjs, projected into
+ * `runtime-image-source-index.json#platformServiceBindings`) says which image
+ * subject carries it — `opencode-image-prepuller` → `runtime-component:
+ * opencode-worker`. When that subject is not supplemental it is produced by a
+ * biome, and the biome that produces it is the one whose OWN manifest declares
+ * it (`services` / `runtimeComponents` in the biome index). So excluding the
+ * provider biome while keeping the dependent service is refused here, naming
+ * both ends; excluding both leaves no edge and resolves.
+ */
+function missingArtifactDependencyMessage(lock, serviceName, binding, biomeIndex) {
+  const field =
+    binding.subjectKind === 'runtime-component' ? 'runtimeComponents' : 'services';
+  const providers = Array.isArray(biomeIndex)
+    ? [
+        ...new Set(
+          biomeIndex
+            .filter((entry) => (entry[field] ?? []).includes(binding.subjectId))
+            .map((entry) => entry.id),
+        ),
+      ].sort(compareStrings)
+    : [];
+  const providerText =
+    providers.length > 0
+      ? `, which is declared by biome ${providers.map((id) => `"${id}"`).join(' / ')}` +
+        ' — and this edition does not select it'
+      : ', and no biome this edition selects declares it';
+  return (
+    `distribution "${lock.distributionId}" ships platform service "${serviceName}", ` +
+    `whose declared runtime binding requires image subject ` +
+    `"${binding.subjectKind}:${binding.subjectId}"${providerText}. ` +
+    `Either keep the providing biome, or exclude "${serviceName}" as well — ` +
+    'refusing rather than resolving an edition whose service has no image.'
+  );
+}
+
+/**
+ * Offline roster derivation. It reads only committed locks/indexes and performs
+ * no registry, GitHub, DigitalOcean, or source-worktree access.
+ *
+ * `requiredPlatforms` is supplied by the caller (see
+ * {@link resolveDistributionRequiredPlatforms}) rather than read here, so this
+ * function stays a pure projection of its inputs — and so a caller that forgets
+ * the distribution's declaration gets a hard error instead of a default.
+ *
+ * THE ROSTER IS THE ARTIFACT CLOSURE OF THE LOGICAL CLOSURE, and nothing else.
+ * `runtime-image-source-index.json` is the FLEET's catalogue — every platform
+ * service binding, every supplemental subject — and an edition selects from it.
+ * A binding for a platform service this edition does not ship is simply not
+ * part of this edition's artifact graph and is dropped; it is never a reason to
+ * refuse. What DOES refuse is a SELECTED service whose declared artifact
+ * dependency is absent from the closure (see `missingArtifactDependencyMessage`).
+ *
+ * `options.biomeIndex` is optional and used ONLY to name, in a refusal, which
+ * biome declares the missing artifact. It never changes a resolved roster.
+ */
+export function resolveImageStructure(
+  lock,
+  runtimeSourceIndex,
+  enums,
+  requiredPlatforms,
+  declaredSources,
+  { biomeIndex } = {},
+) {
+  if (!Array.isArray(requiredPlatforms) || requiredPlatforms.length === 0) {
+    throw new Error(
+      `distribution "${lock.distributionId}" resolved no required image platforms — ` +
+        `every distribution declares requiredPlatforms in its xema-distribution.json ` +
+        `and there is no default; a silent default is the bug this replaced`,
+    );
+  }
+  const subjects = new Map();
+  const webBiomes = [];
+  const platformServiceBindings = [];
+  const repositoryPins = new Map(
+    runtimeSourceIndex.repositoryPins.map((repository) => [
+      repository.repo,
+      repository,
+    ]),
+  );
+  const requireRepositoryPin = (repo) => {
+    const pin = repositoryPins.get(repo);
+    if (!pin) {
+      throw new Error(`runtime image source "${repo}" has no repository pin`);
+    }
+    return pin;
+  };
+
+  for (const biome of lock.biomes) {
+    // WHERE THIS BIOME'S IMAGES LIVE, and WHICH COMMIT THEY ARE BUILT FROM.
+    // Both answers move together when a biome is drawn from an external source,
+    // because both are facts about that source rather than about this fleet.
+    //
+    // ── THE REGISTRY ──
+    //
+    // A first-party biome is published to the vendor namespace. A biome drawn
+    // from an EXTERNAL source is not, and its coordinate is DECLARED — on the
+    // `sources[]` entry as `imageRegistry`, carried into the lock verbatim by
+    // `external-source-walk.mjs` and read HERE. This used to refuse
+    // unconditionally, including when the coordinate WAS declared, because
+    // reading it was not implemented; that was an honest partial and it is now
+    // implemented.
+    //
+    // THE REFUSAL SURVIVES, NARROWED TO THE CASE IT WAS ALWAYS ABOUT: an
+    // external source that declares NO registry. The kernel legislates that on
+    // the field itself — *"a plane that needs one and finds it absent must
+    // REFUSE rather than substitute the first-party registry, which would
+    // publish a customer's build into the vendor org."* Absent must never
+    // become a fallback to the first-party registry. That substitution is the entire
+    // defect; narrowing the refusal must not soften it into a default.
+    //
+    // ── THE COMMIT ──
+    //
+    // A first-party biome's commit comes from `runtime-image-source-index.json`
+    // via `requireRepositoryPin`. An external biome has no entry there and
+    // never will: its `repo` is the source's own LOGICAL name as declared in
+    // `sources[]`, not a `repos/<x>` path, so the pin lookup would fail with "has no
+    // repository pin" — a true sentence about the wrong plane. Its pin is the
+    // commit the WALK resolved and the lock recorded, which is the same fact
+    // held by the authority that actually resolved it.
+    //
+    // ── PLACEMENT ──
+    //
+    // Both are resolved BEFORE `requireRepositoryPin` and before the
+    // `target === 'web'` branch, so services, runtime components and web biomes
+    // are covered by one statement rather than leaving the web branch's
+    // `continue` as a hole.
+    //
+    // KNOWN NARROWING, stated rather than discovered: a web biome composes no
+    // image ref at all, so an external source shipping ONLY web biomes needs no
+    // registry and is nonetheless refused here. That is deliberately left
+    // fail-closed — it has no subject today (both externally-sourced biomes in
+    // this plane declare `target: "server"`), and loosening a fence for a case
+    // that does not exist is how a fence stops meaning anything.
+    let imageRegistry = firstPartyImageRegistry();
+    // The identity element, not a fallback — see `imageRefForSubject`. A
+    // first-party subject is published under its own id, which is exactly what
+    // an empty prefix composes.
+    let imageNamePrefix = '';
+    let sourceCommit;
+    if (biome.source === undefined) {
+      sourceCommit = requireRepositoryPin(biome.repo).sourceCommit;
+    } else {
+      if (biome.source.imageRegistry === undefined) {
+        throw new Error(
+          `distribution "${lock.distributionId}" biome "${biome.id}" was drawn from external ` +
+            `source "${biome.source.name}" (${biome.source.url}@${biome.source.commit}), which ` +
+            'declares no imageRegistry, so this plane cannot address its images. Composing ' +
+            `them under "${firstPartyImageRegistry()}" would address a build this organisation does not ` +
+            'produce, inside the vendor namespace. Declare `imageRegistry` on that sources[] ' +
+            'entry — refusing rather than substituting the first-party registry.',
+        );
+      }
+      imageRegistry = biome.source.imageRegistry;
+      // THE PREFIX COMES FROM THE DECLARATION, NEVER FROM THE LOCK.
+      //
+      // This read was `biome.source.imageNamePrefix`, which required the lock to
+      // carry the key — and a lock carrying it is refused outright by any
+      // consumer on `@xemahq/contracts` `^0.9.x`, whose DistributionLockSchema
+      // is `.strict()` and learned the key only in 0.10.0.
+      //
+      // Removing it from the lock WITHOUT moving this read is what composed
+      // `<customer-registry>/pai-core-api` instead of `<customer-registry>/presenca-pai-core-api`:
+      // the `?? ''` swallowed the absence, so an unqualified name in a shared
+      // organisation namespace resolved silently. That is worse than a 404 —
+      // the first collision overwrites another product's tags.
+      //
+      // A MISSING DECLARED ENTRY IS THEREFORE REFUSED, never defaulted. An entry
+      // that declares NO prefix is a different fact and is honoured: the empty
+      // prefix is the identity element, composing a subject under its bare id.
+      if (!Array.isArray(declaredSources)) {
+        throw new Error(
+          `distribution "${lock.distributionId}" biome "${biome.id}" was drawn from ` +
+            `external source "${biome.source.name}", but this resolve was given no ` +
+            'declared sources[] to read its imageNamePrefix from. That prefix is ' +
+            'producer input and is deliberately not carried in the lock; pass ' +
+            '`resolveDistributionDeclaredSources(schemas, id)` — refusing rather ' +
+            'than composing an unprefixed name.',
+        );
+      }
+      const declaredSource = declaredSources.find(
+        (candidate) => candidate.name === biome.source.name,
+      );
+      if (declaredSource === undefined) {
+        throw new Error(
+          `distribution "${lock.distributionId}" biome "${biome.id}" was drawn from ` +
+            `external source "${biome.source.name}", which this distribution's ` +
+            `composed sources[] does not declare (declared: ${
+              declaredSources.map((candidate) => candidate.name).join(', ') ||
+              'none'
+            }). The image name cannot be composed without its declaration — ` +
+            'refusing rather than publishing under an unprefixed name in a shared ' +
+            "organisation namespace, where the first collision overwrites another " +
+            "product's tags.",
+        );
+      }
+      imageNamePrefix = declaredSource.imageNamePrefix ?? '';
+      sourceCommit = biome.source.commit;
+    }
+    if (biome.target === 'web') {
+      webBiomes.push({
+        biomeId: biome.id,
+        repo: biome.repo,
+        path: biome.path,
+        sourceCommit,
+        sourceManifestHash: biome.sourceManifestHash,
+      });
+      continue;
+    }
+    // A worker that runs a sibling service's image builds none of its own: the
+    // service's subject is the one sealed coordinate, and the deploy plane
+    // reaches it through `workerImages[worker].imageOf`. Minting a subject for
+    // the worker would name an image nothing builds.
+    const sharedImageWorkers = new Set(Object.keys(biome.workerImages ?? {}));
+    for (const service of biome.services ?? []) {
+      if (sharedImageWorkers.has(service)) {
+        continue;
+      }
+      addSubject(subjects, {
+        kind: enums.RuntimeImageSubjectKind.Service,
+        id: service,
+        imageRef: imageRefForSubject(service, imageRegistry, imageNamePrefix),
+        repo: biome.repo,
+        path: biome.path,
+        sourceCommit,
+        sourceManifestHash: biome.sourceManifestHash,
+        requiredPlatforms,
+        owners: [
+          {
+            kind: enums.RuntimeImageOwnerKind.Biome,
+            biomeId: biome.id,
+          },
+        ],
+      });
+    }
+    // Runtime components are FULL delivery subjects — built, content-addressed,
+    // signed, mirrored and air-gapped exactly like a service image. They differ
+    // only in that nothing schedules them, which the deploy plane reads off the
+    // subject KIND. Their source path resolves through the same
+    // `ships.apis[].path` SSOT, because a runtime component IS a `ships.apis[]`
+    // entry — it just carries `workload: "runtime-component"`.
+    for (const component of biome.runtimeComponents ?? []) {
+      addSubject(subjects, {
+        kind: enums.RuntimeImageSubjectKind.RuntimeComponent,
+        id: component,
+        imageRef: imageRefForSubject(component, imageRegistry, imageNamePrefix),
+        repo: biome.repo,
+        path: biome.path,
+        sourceCommit,
+        sourceManifestHash: biome.sourceManifestHash,
+        requiredPlatforms,
+        owners: [
+          {
+            kind: enums.RuntimeImageOwnerKind.Biome,
+            biomeId: biome.id,
+          },
+        ],
+      });
+    }
+  }
+
+  const runtimeBindings = new Map(
+    runtimeSourceIndex.platformServiceBindings.map((binding) => [
+      binding.platformService,
+      binding,
+    ]),
+  );
+  const supplementalSubjects = new Map(
+    runtimeSourceIndex.supplementalSubjects.map((subject) => [
+      subjectKey(subject),
+      subject,
+    ]),
+  );
+
+  for (const service of lock.platformServices ?? []) {
+    let binding;
+    // The discriminator is the DECLARED runtime binding, never "does the lock
+    // carry a source". Every platform service carries an exact source identity
+    // now (`LockedPlatformService.source` is required at lock schemaVersion 2),
+    // so `if (service.source)` became unconditionally true — and it would have
+    // minted a repository-ROOT `platform` subject for `xema-kernel-server`,
+    // `docs-api`, `xema-host-web` and `opencode-image-prepuller`, hashing the
+    // wrong closure for three of them and inventing an image that has never
+    // existed for the fourth. A binding names the subject that really carries
+    // the service; its absence means the service IS its own repository image.
+    const runtimeBinding = runtimeBindings.get(service.name);
+    if (!runtimeBinding) {
+      if (!service.source) {
+        throw new Error(
+          `platform service "${service.name}" has no declared runtime image binding ` +
+            'and no exact source identity, so no image subject can be resolved for it',
+        );
+      }
+      const repository = requireRepositoryPin(service.source.repo);
+      if (service.source.sourceCommit !== repository.sourceCommit) {
+        throw new Error(
+          `platform service "${service.name}" source commit does not match its repository pin`,
+        );
+      }
+      binding = {
+        platformService: service.name,
+        subjectKind: enums.RuntimeImageSubjectKind.Platform,
+        subjectId: service.source.imageKey,
+      };
+      addSubject(subjects, {
+        kind: binding.subjectKind,
+        id: binding.subjectId,
+        imageRef: imageRefForSubject(binding.subjectId),
+        repo: service.source.repo,
+        path: service.source.repo,
+        sourceCommit: repository.sourceCommit,
+        sourceManifestHash: service.source.sourceManifestHash,
+        sourceManifestPath: service.source.path,
+        requiredPlatforms,
+        owners: [
+          {
+            kind: enums.RuntimeImageOwnerKind.PlatformService,
+            platformService: service.name,
+          },
+        ],
+      });
+    } else {
+      binding = runtimeBinding;
+      const key = bindingKey(binding);
+      const supplemental = supplementalSubjects.get(key);
+      if (supplemental) {
+        const repository = requireRepositoryPin(supplemental.repo);
+        if (supplemental.sourceCommit !== repository.sourceCommit) {
+          throw new Error(
+            `runtime subject "${supplemental.kind}:${supplemental.id}" source commit does not match its repository pin`,
+          );
+        }
+        addSubject(subjects, {
+          kind: supplemental.kind,
+          id: supplemental.id,
+          imageRef: supplemental.imageRef,
+          repo: supplemental.repo,
+          path: supplemental.path,
+          sourceCommit: repository.sourceCommit,
+          sourceManifestHash: supplemental.sourceManifestHash,
+          sourceManifestPath: supplemental.sourceManifestPath,
+          requiredPlatforms,
+          owners: [
+            {
+              kind: enums.RuntimeImageOwnerKind.PlatformService,
+              platformService: service.name,
+            },
+          ],
+        });
+      } else {
+        const target = subjects.get(key);
+        if (!target) {
+          throw new Error(
+            missingArtifactDependencyMessage(lock, service.name, binding, biomeIndex),
+          );
+        }
+        addSubject(subjects, {
+          ...target,
+          owners: [
+            {
+              kind: enums.RuntimeImageOwnerKind.PlatformService,
+              platformService: service.name,
+            },
+          ],
+        });
+      }
+    }
+    platformServiceBindings.push(binding);
+  }
+
+  // A binding for a service this edition does not ship is outside its artifact
+  // graph. It was REFUSED here ("runtime image source index contains unselected
+  // platform service"), which made every image-bearing platform service
+  // unexcludable: `billing-api` could be dropped only because it happens to be
+  // independently sourced and carries no binding, while `docs-api`,
+  // `xema-host-web` and `opencode-image-prepuller` could not. The index is the
+  // fleet catalogue, not this edition's roster; the roster is derived from the
+  // lock's `platformServices`, above. A binding naming a service the COMPOSED
+  // catalogue does not know at all is still a declaration defect, and is
+  // refused by `build-runtime-image-source-index.mjs --check`, which owns the
+  // index — not by every edition that happens to omit the service.
+
+  const orderedSubjects = [...subjects.values()]
+    .map((subject) => ({
+      ...subject,
+      owners: subject.owners.sort(compareOwner),
+    }))
+    .sort(compareSubject);
+  webBiomes.sort((left, right) => compareStrings(left.biomeId, right.biomeId));
+  platformServiceBindings.sort((left, right) =>
+    compareStrings(left.platformService, right.platformService),
+  );
+  return {
+    subjects: orderedSubjects,
+    webBiomes,
+    platformServiceBindings,
+  };
+}
+
+/**
+ * THE COMPOSED-PROCESS IMAGE OF ONE BUILD — where a producing repository
+ * declares it, and how an edition addresses it.
+ *
+ * The kernel (`RuntimeImageSubjectKind.ComposedProcess`) fixes WHAT the subject
+ * is: one repository at one commit, carrying every platform-scheduled service
+ * of that build and `@xemahq/xema-service-nest`'s `xema-composed-process`
+ * entrypoint, owned by the biomes whose services it carries. Neither the kernel
+ * nor the SDK fixes WHERE a repository builds it, so this plane does, once:
+ *
+ *   - the image directory is `infra/composed-process/` at the repository root,
+ *     holding its own `Dockerfile` and an `image-build-inputs.json` whose
+ *     `workspacePackages` lists every member service's workspace package
+ *     directory — the Dockerfile-only image shape `hashImageBuildInputs`
+ *     already reads (`opencode-worker` is the other one). Its tag is therefore
+ *     an ordinary `xema-image-input-sha256-v2` key, computed by the one
+ *     implementation every producer uses, with `SERVICE` = the subject id and
+ *     `SERVICE_PATH` = this directory;
+ *   - the DECLARATION is that `image-build-inputs.json` existing at the pinned
+ *     commit. A repository that declares none has no composed image, and an
+ *     edition carries no composed subject for it — which the deploy plane
+ *     reports as "the producer builds no composed-process image at that
+ *     commit". That is an honest absence, not a skipped subject: a DECLARED
+ *     image that has not been built is still emitted, carries no
+ *     `imageDigest`, and is undeliverable until it is sealed;
+ *   - the subject id is `<declared source id>-composed-process`. The source
+ *     id is DECLARED, never derived from where the repository is hosted: an
+ *     external source's is the edition's `sources[].name` (which the walk
+ *     also stamps as the biome's `repo`), a first-party repository's is
+ *     declared in `first-party-source-ids.mjs`. A rename or host move changes
+ *     `repositoryUrl` — provenance — and no subject id, `imageRef` or
+ *     `contentHash` (the id is the `SERVICE` input of the tag). It cannot be
+ *     a constant: two first-party repositories publish into one registry
+ *     namespace, and the image lock refuses two subjects sharing an
+ *     `imageRef`. The producing build publishes under this same name;
+ *   - `imageRef` is composed exactly as the repository's service subjects are
+ *     (`imageRefForSubject`, with the same registry and declared prefix).
+ */
+export const COMPOSED_PROCESS_IMAGE_PATH = 'infra/composed-process';
+export const COMPOSED_PROCESS_DECLARATION_FILE = 'image-build-inputs.json';
+const COMPOSED_PROCESS_ID_SUFFIX = '-composed-process';
+
+export function composedProcessSubjectId(sourceId) {
+  return `${assertDeclaredSourceId(sourceId, 'composed-process subject')}${COMPOSED_PROCESS_ID_SUFFIX}`;
+}
+
+/**
+ * The DECLARED source id of every repository this edition builds a service
+ * image from, keyed by the subject's `repo` handle — the edition's own
+ * `sources[].name` for a source-walked biome, the first-party declaration
+ * otherwise. Never read off a URL.
+ */
+export function editionSourceIds(lock) {
+  const ids = new Map();
+  for (const biome of lock.biomes ?? []) {
+    if (biome.source === undefined) {continue;}
+    if (biome.repo !== biome.source.name) {
+      throw new Error(
+        `lock biome "${biome.id}" is drawn from source "${biome.source.name}" but its repo ` +
+          `handle is "${biome.repo}" — a source-walked biome's repo IS its declared source id`,
+      );
+    }
+    ids.set(biome.repo, assertDeclaredSourceId(biome.source.name, `lock biome "${biome.id}" source`));
+  }
+  return { get: (repo) => ids.get(repo) ?? firstPartySourceId(repo) };
+}
+
+/**
+ * Read each repository's composed-process DECLARATION at the commit the
+ * edition builds its services from. Only repositories that contribute a
+ * service subject are asked: a composed image carries services, so a
+ * repository shipping none has nothing to compose.
+ */
+export function readComposedProcessDeclarations(
+  structure,
+  enums,
+  sourceIds,
+  locate = FIRST_PARTY_TREES,
+) {
+  const commits = new Map();
+  for (const subject of structure.subjects) {
+    if (subject.kind !== enums.RuntimeImageSubjectKind.Service) {continue;}
+    if (!subject.owners.some((owner) => owner.kind === enums.RuntimeImageOwnerKind.Biome)) {continue;}
+    commits.set(subject.repo, subject.sourceCommit);
+  }
+  const declarations = [];
+  for (const [repo, sourceCommit] of [...commits].sort(([a], [b]) => compareStrings(a, b))) {
+    const { dir, base } = locate(repo);
+    const declarationPath = `${COMPOSED_PROCESS_IMAGE_PATH}/${COMPOSED_PROCESS_DECLARATION_FILE}`;
+    // ABSENCE IS ONLY AN ANSWER ABOUT A COMMIT THAT WAS READ. A repository
+    // missing from this layout, or one lacking the pinned commit, would
+    // otherwise read as "declares nothing", and `dist-check` would grade a lock
+    // that dropped the composed subject as up to date.
+    try {
+      execFileSync('git', ['-C', dir, 'cat-file', '-e', `${sourceCommit}^{commit}`], {
+        stdio: ['ignore', 'ignore', 'ignore'],
+      });
+    } catch {
+      throw new Error(
+        `runtime image source "${repo}" pins commit "${sourceCommit}", which is absent from ` +
+          `${dir} — its composed-process declaration cannot be read; fetch the repository ` +
+          'before resolving',
+      );
+    }
+    try {
+      execFileSync('git', ['-C', dir, 'cat-file', '-e', `${sourceCommit}:${declarationPath}`], {
+        stdio: ['ignore', 'ignore', 'ignore'],
+      });
+    } catch {
+      continue; // declares no composed-process image at this commit
+    }
+    const sourceId = sourceIds.get(repo);
+    const repoRelative = relative(base, dir).split(sep).join('/');
+    declarations.push({
+      repo,
+      sourceId,
+      sourceCommit,
+      path: `${repoRelative}/${COMPOSED_PROCESS_IMAGE_PATH}`,
+      sourceManifestPath: `${repoRelative}/${declarationPath}`,
+      sourceManifestHash: exactSourceManifestHash(dir, declarationPath, sourceCommit),
+    });
+  }
+  return declarations;
+}
+
+/**
+ * Add ONE `composed-process` subject per declaring repository to an edition's
+ * structure. Pure over its inputs, so the structural check and the source
+ * resolve derive the same subject from the same declarations.
+ *
+ * Owners are the biomes whose service subjects come from that repository in
+ * this edition — the members the deploy plane may place in a process with it.
+ */
+export function withComposedProcessSubjects(structure, declarations, enums, requiredPlatforms) {
+  if (declarations.length === 0) {return structure;}
+  const subjects = new Map(structure.subjects.map((subject) => [subjectKey(subject), subject]));
+  for (const declaration of declarations) {
+    const services = structure.subjects.filter(
+      (subject) =>
+        subject.kind === enums.RuntimeImageSubjectKind.Service && subject.repo === declaration.repo,
+    );
+    // One owner per biome: a biome shipping several services owns the
+    // composed image once (the kernel refuses a repeated owner identity).
+    const biomeOwners = [
+      ...new Map(
+        services
+          .flatMap((subject) => subject.owners)
+          .filter((owner) => owner.kind === enums.RuntimeImageOwnerKind.Biome)
+          .map((owner) => [owner.biomeId, owner]),
+      ).values(),
+    ];
+    if (biomeOwners.length === 0) {
+      throw new Error(
+        `composed-process declaration for "${declaration.repo}" names no biome service ` +
+          'subject in this edition — a composed image carries services, so it has no owner',
+      );
+    }
+    for (const subject of services) {
+      if (subject.sourceCommit !== declaration.sourceCommit) {
+        throw new Error(
+          `runtime subject "${subject.kind}:${subject.id}" is resolved at ${subject.sourceCommit}, ` +
+            `but "${declaration.repo}"'s composed-process image is declared at ` +
+            `${declaration.sourceCommit} — one composed image is ONE build`,
+        );
+      }
+    }
+    // The registry and declared prefix the repository's services are published
+    // under: `imageRefForSubject` is `<registry>/<prefix><id>`, so stripping
+    // the service id recovers it exactly. Two services disagreeing would mean
+    // one build published under two coordinates, which nothing can address.
+    const namespaces = new Set(
+      services.map((subject) => {
+        if (!subject.imageRef.endsWith(subject.id)) {
+          throw new Error(
+            `runtime subject "${subject.kind}:${subject.id}" imageRef "${subject.imageRef}" ` +
+              'does not end with its id, so its namespace cannot be recovered',
+          );
+        }
+        return subject.imageRef.slice(0, -subject.id.length);
+      }),
+    );
+    if (namespaces.size !== 1) {
+      throw new Error(
+        `"${declaration.repo}"'s services publish under ${namespaces.size} namespaces ` +
+          `(${[...namespaces].join(', ')}) — a composed image of one build has one`,
+      );
+    }
+    const id = composedProcessSubjectId(declaration.sourceId);
+    addSubject(subjects, {
+      kind: enums.RuntimeImageSubjectKind.ComposedProcess,
+      id,
+      imageRef: `${[...namespaces][0]}${id}`,
+      repo: declaration.repo,
+      path: declaration.path,
+      sourceCommit: declaration.sourceCommit,
+      sourceManifestHash: declaration.sourceManifestHash,
+      sourceManifestPath: declaration.sourceManifestPath,
+      requiredPlatforms,
+      owners: biomeOwners.map((owner) => ({ kind: owner.kind, biomeId: owner.biomeId })),
+    });
+  }
+  return {
+    ...structure,
+    subjects: [...subjects.values()]
+      .map((subject) => ({ ...subject, owners: [...subject.owners].sort(compareOwner) }))
+      .sort(compareSubject),
+  };
+}
+
+/**
+ * The edition structure INCLUDING its composed-process subjects — the one
+ * entry point the source resolve and the structural check share, so neither
+ * can carry a subject the other does not. A repository that declares no
+ * composed image at its pinned commit contributes no subject.
+ */
+export function resolveComposedProcessStructure(
+  lock,
+  structure,
+  enums,
+  requiredPlatforms,
+  { locate } = {},
+) {
+  return withComposedProcessSubjects(
+    structure,
+    readComposedProcessDeclarations(
+      structure,
+      enums,
+      editionSourceIds(lock),
+      // Materialised only when something will be read through it.
+      locate ?? sourceTreeLocator(externalSourceTrees(lock)),
+    ),
+    enums,
+    requiredPlatforms,
+  );
+}
+
+/**
+ * The exact commit every image source repository is resolved at.
+ *
+ * The PIN is the authority, not the local checkout. Requiring each submodule's
+ * `HEAD` to equal its pin made regeneration impossible in any working tree that
+ * had moved on — which is every working tree — and bought nothing: the hashes
+ * read immutable Git objects at the pinned commit, so what is checked out
+ * cannot change a digest. What DOES have to hold is that the pinned commit is
+ * present in the local object database, which is asserted here.
+ */
+function sourceCommitMap(structure, locate = FIRST_PARTY_TREES) {
+  const commitByRepo = new Map();
+  for (const source of [...structure.subjects, ...structure.webBiomes]) {
+    if (!source.sourceCommit) {continue;}
+    const incumbent = commitByRepo.get(source.repo);
+    if (incumbent && incumbent !== source.sourceCommit) {
+      throw new Error(
+        `runtime image roster pins multiple commits for "${source.repo}"`,
+      );
+    }
+    commitByRepo.set(source.repo, source.sourceCommit);
+  }
+  const repositories = [
+    ...new Set([
+      ...structure.subjects.map((subject) => subject.repo),
+      ...structure.webBiomes.map((biome) => biome.repo),
+    ]),
+  ].sort(compareStrings);
+  for (const repo of repositories) {
+    const commit = commitByRepo.get(repo);
+    if (!commit) {
+      throw new Error(`runtime image source "${repo}" has no pinned commit`);
+    }
+    try {
+      execFileSync(
+        'git',
+        ['-C', locate(repo).dir, 'cat-file', '-e', `${commit}^{commit}`],
+        { stdio: ['ignore', 'ignore', 'pipe'] },
+      );
+    } catch {
+      throw new Error(
+        `runtime image source "${repo}" pins commit "${commit}", which is absent ` +
+          `from the local object database — fetch the repository before resolving`,
+      );
+    }
+  }
+  return commitByRepo;
+}
+
+/**
+ * The SERVICE directory an image is built from, repository-relative.
+ *
+ * A biome subject's `path` is the BIOME directory, and a biome can ship several
+ * services — `agent-runtime` ships four. Hashing the biome directory would give
+ * all four the same closure and would move all four when any one of them
+ * changes, so the service directory is read from the manifest SSOT
+ * (`xema.ships.apis[].path`) rather than synthesized. Non-biome subjects
+ * (`sourceManifestPath` present) already carry their own service directory.
+ *
+ * Exported for `assemble-producer-input.mjs`, which must derive the SAME
+ * service directory to hash the SAME build-input closure the lock names.
+ */
+export function subjectServicePath(subject, sourceCommit, locate = FIRST_PARTY_TREES) {
+  const { dir: repoDirectory, base } = locate(subject.repo);
+  const toRepoRelative = (absolute) =>
+    relative(repoDirectory, absolute).split(sep).join('/') || '.';
+  if (subject.sourceManifestPath) {
+    return toRepoRelative(join(base, subject.path));
+  }
+  const biomePath = toRepoRelative(join(base, subject.path));
+  const manifestPath =
+    biomePath === '.' ? 'xema-biome.json' : `${biomePath}/xema-biome.json`;
+  const manifest = readGitJsonAtCommit(
+    repoDirectory,
+    manifestPath,
+    sourceCommit,
+  );
+  const xema = manifest?.xema;
+  const apis = xema?.ships?.apis;
+  const legacyApis = Array.isArray(apis) ? apis : [];
+  // component-contract-v5: a component's source directory is declared by its
+  // own `artifact.path`.
+  //
+  // Both `service` AND `worker` kinds qualify. Restricting this to `service`
+  // was correct only while a runtime component was spelled in the legacy
+  // `ships.apis[]` block; v5 dropped that field, so `opencode-worker` —
+  // `kind: "worker"`, `scheduler: "runtime"` — fell through to the legacy
+  // branch and failed with "ships no apis" even though its manifest declares
+  // everything needed. What identifies the subject is
+  // `protocol.serviceName`, not the component kind.
+  const components = Array.isArray(xema?.components) ? xema.components : [];
+  const v4ServiceComponents = components.filter(
+    (component) =>
+      component !== null &&
+      typeof component === 'object' &&
+      (component.kind === 'service' || component.kind === 'worker'),
+  );
+  if (legacyApis.length > 0 && v4ServiceComponents.length > 0) {
+    throw new Error(
+      `${subject.repo}@${sourceCommit}:${manifestPath} declares services in BOTH ` +
+        `xema.ships.apis[] (legacy) and xema.components[] kind "service" ` +
+        `(component-contract-v4) — a biome must use exactly one shape`,
+    );
+  }
+  let servicePath;
+  if (v4ServiceComponents.length > 0) {
+    // A SERVICE is identified by `protocol.serviceName`; a WORKER has no
+    // service protocol and is identified by its component `key`. Matching only
+    // on `serviceName` silently found nothing for every worker subject and
+    // reported it as an undeclared service directory.
+    const component = v4ServiceComponents.find(
+      (entry) =>
+        entry?.protocol?.serviceName === subject.id || entry?.key === subject.id,
+    );
+    if (
+      !component ||
+      typeof component?.artifact?.path !== 'string' ||
+      component.artifact.path.length === 0
+    ) {
+      throw new Error(
+        `${subject.repo}@${sourceCommit}:${manifestPath} declares no xema.components[] ` +
+          `kind "service"/"worker" entry identified as "${subject.id}" (by ` +
+          `protocol.serviceName or component key) with an ` +
+          `artifact.path — the service source directory is the manifest's to declare ` +
+          `and must never be synthesized`,
+      );
+    }
+    servicePath = component.artifact.path;
+  } else {
+    if (legacyApis.length === 0) {
+      throw new Error(
+        `${subject.repo}@${sourceCommit}:${manifestPath} ships no apis, but runtime ` +
+          `subject "${subject.kind}:${subject.id}" claims to be one of them`,
+      );
+    }
+    const api = legacyApis.find((entry) => entry?.name === subject.id);
+    if (!api || typeof api.path !== 'string' || api.path.length === 0) {
+      throw new Error(
+        `${subject.repo}@${sourceCommit}:${manifestPath} declares no ships.apis[] entry ` +
+          `named "${subject.id}" with a "path" — the service source directory is the ` +
+          `manifest's to declare and must never be synthesized`,
+      );
+    }
+    servicePath = api.path;
+  }
+  return toRepoRelative(join(base, subject.path, servicePath));
+}
+
+function assertSourceManifestParity(structure, commitByRepo, locate = FIRST_PARTY_TREES) {
+  for (const source of structure.subjects) {
+    const { dir: repoDirectory, base } = locate(source.repo);
+    const sourceCommit = commitByRepo.get(source.repo);
+    const manifestPath = source.sourceManifestPath
+      ? relative(repoDirectory, join(base, source.sourceManifestPath))
+          .split(sep)
+          .join('/')
+      : relative(repoDirectory, join(base, source.path, 'xema-biome.json'))
+          .split(sep)
+          .join('/');
+    const actual = exactSourceManifestHash(
+      repoDirectory,
+      manifestPath,
+      sourceCommit,
+    );
+    if (actual !== source.sourceManifestHash) {
+      throw new Error(
+        `runtime subject "${source.kind}:${source.id}" sourceManifestHash does not match ${source.repo}@${sourceCommit}:${manifestPath}`,
+      );
+    }
+  }
+  for (const biome of structure.webBiomes) {
+    const { dir: repoDirectory, base } = locate(biome.repo);
+    const sourceCommit = commitByRepo.get(biome.repo);
+    const manifestPath = relative(
+      repoDirectory,
+      join(base, biome.path, 'xema-biome.json'),
+    )
+      .split(sep)
+      .join('/');
+    const actual = exactSourceManifestHash(
+      repoDirectory,
+      manifestPath,
+      sourceCommit,
+    );
+    if (actual !== biome.sourceManifestHash) {
+      throw new Error(
+        `web biome "${biome.biomeId}" sourceManifestHash does not match ${biome.repo}@${sourceCommit}:${manifestPath}`,
+      );
+    }
+  }
+}
+
+/**
+ * AN EXTERNAL SOURCE THAT VENDORS CROSS-REPOSITORY CONTENT IS REFUSED, LOUDLY.
+ *
+ * `runtime-image-source-index.json` declares the vendoring this fleet's own
+ * repositories do, and an external source has no entry there — correctly, since
+ * the index is the vendor's view of the vendor's repositories. Reading that
+ * absence as "this repository vendors nothing" is the silent half: a Dockerfile
+ * that copies a tree in from elsewhere would have those bytes drop out of the
+ * closure, and the hash would name an image whose content it does not describe.
+ *
+ * So the ABSENCE is checked rather than assumed. The producing repository's own
+ * committed record — the same file `vendor-cross-repo-inputs.mjs` reads to emit
+ * the `--vendored` arguments CI hands the tag computation — is read at the
+ * locked commit. Absent means genuinely nothing to vendor, which is the honest
+ * empty. PRESENT means this plane cannot pin the other side (it has no checkout
+ * of a repository the customer vendors from, and no authority to resolve one),
+ * and an undeclared input must fail rather than silently drop out.
+ */
+function assertExternalSourcesDeclareNoVendoring(lock, locate, commitByRepo) {
+  const external = new Set(
+    (lock.biomes ?? [])
+      .filter((biome) => biome.source !== undefined)
+      .map((biome) => biome.repo),
+  );
+  for (const repo of [...external].sort(compareStrings)) {
+    const { dir } = locate(repo);
+    const commit = commitByRepo.get(repo);
+    if (!commit) {continue;}
+    // Existence is probed with `cat-file -e` rather than by catching the read:
+    // a failed read writes `fatal: path ... does not exist` to stderr, and a
+    // `fatal:` printed during a successful run is a false signal a reader has
+    // to spend time discounting.
+    let present;
+    try {
+      execFileSync('git', ['-C', dir, 'cat-file', '-e', `${commit}:${CROSS_REPO_BUILD_INPUTS_PATH}`], {
+        stdio: ['ignore', 'ignore', 'ignore'],
+      });
+      present = true;
+    } catch {
+      present = false;
+    }
+    if (!present) {continue;} // absent — nothing vendored, which is the honest empty
+    const record = readGitJsonAtCommit(dir, CROSS_REPO_BUILD_INPUTS_PATH, commit);
+    const inputs = Array.isArray(record?.inputs) ? record.inputs : [];
+    if (inputs.length === 0) {continue;}
+    throw new Error(
+      `external source "${repo}" declares ${inputs.length} cross-repository build ` +
+        `input(s) in ${CROSS_REPO_BUILD_INPUTS_PATH} at ${commit}. This plane cannot pin ` +
+        'the other side of them — it holds no checkout of the repositories they vendor ' +
+        'from — so the image content hash would omit bytes the build bakes in and name a ' +
+        'coordinate it does not describe. Refusing rather than hashing an incomplete ' +
+        'closure.',
+    );
+  }
+}
+
+/**
+ * The vendored cross-repository build inputs of THIS roster's images, keyed
+ * `${consumerRepo}\0${consumerService ?? ''}`.
+ *
+ * EVERY COMMIT HERE COMES FROM A REPOSITORY PIN, NEVER FROM ROSTER MEMBERSHIP.
+ *
+ * The consumer commit — the commit whose committed
+ * `tooling/release/cross-repo-build-inputs.json` names the vendored revisions —
+ * is the consumer repository's `repositoryPins` entry. It used to be read out
+ * of the edition's resolved commit map, which knows a repository only if some
+ * SELECTED biome happens to come from it. That made an image's identity depend
+ * on unrelated membership, and made a trimmed edition unaddressable: an edition
+ * shipping no `repos/xema-community` biome refused with "cross-repo build inputs
+ * are declared for repos/xema-community, but this distribution resolves no
+ * commit for it" — although it shipped no xema-community image at all. For a
+ * first-party subject the two are the same commit by construction (a subject's
+ * `sourceCommit` IS its repository pin), so every edition that resolved before
+ * resolves to byte-identical hashes now.
+ *
+ * Only consumers the roster actually BUILDS FROM are resolved: a consumer with
+ * no selected subject contributes no input to any hash here, so reading its
+ * record would be work that grades nothing. The vendored revision itself is the
+ * consumer's own record at its pin (see the reasoning above the call site): the
+ * pin fixes the record, and the record fixes the bytes. A consumer, or a
+ * repository it vendors from, with NO repository pin is refused by name — the
+ * image cannot be addressed without one.
+ */
+export function resolveCrossRepoInputsForRoster({
+  runtimeSourceIndex,
+  subjects,
+  resolveVendored = resolveCrossRepoVendoredInputs,
+  repoRoot = sourcesRoot(),
+  // The subject kind that builds EVERY input of its repository (the composed
+  // process image carries every service of its build). Undefined: none does.
+  composedProcessKind = undefined,
+}) {
+  const pins = new Map(
+    runtimeSourceIndex.repositoryPins.map((pin) => [pin.repo, pin]),
+  );
+  const requirePin = (repo, role) => {
+    const pin = pins.get(repo);
+    if (!pin) {
+      throw new Error(
+        `cross-repo build inputs need a repository pin for "${repo}" (${role}), ` +
+          'and runtime-image-source-index.json declares none — the vendored content ' +
+          'cannot be pinned, so the image cannot be addressed',
+      );
+    }
+    return pin;
+  };
+  const builds = (input) =>
+    subjects.some(
+      (subject) =>
+        subject.repo === input.consumerRepo &&
+        (input.consumerService === undefined || input.consumerService === null ||
+          input.consumerService === subject.id ||
+          (composedProcessKind !== undefined && subject.kind === composedProcessKind)),
+    );
+  const needed = runtimeSourceIndex.crossRepoBuildInputs.filter(builds);
+  const vendoredCommitByInputKey = new Map();
+  for (const consumerRepo of [
+    ...new Set(needed.map((input) => input.consumerRepo)),
+  ].sort(compareStrings)) {
+    const consumerCommit = requirePin(consumerRepo, 'the consuming repository').sourceCommit;
+    for (const subject of subjects) {
+      if (subject.repo === consumerRepo && subject.sourceCommit !== undefined &&
+          subject.sourceCommit !== consumerCommit) {
+        throw new Error(
+          `runtime subject "${subject.kind}:${subject.id}" is resolved at ` +
+            `${subject.sourceCommit}, but "${consumerRepo}" is pinned at ${consumerCommit}`,
+        );
+      }
+    }
+    // The record is read against EVERY input the index declares for this
+    // consumer, not the roster-filtered subset: set equality with the
+    // consumer's record is the fence against a drifted declaration, and it must
+    // not weaken because an edition ships fewer services.
+    for (const resolved of resolveVendored({
+      indexInputs: runtimeSourceIndex.crossRepoBuildInputs,
+      consumerRepo,
+      consumerRepoDir: join(repoRoot, consumerRepo),
+      consumerCommit,
+    })) {
+      vendoredCommitByInputKey.set(
+        consumerInputKey(consumerRepo, {
+          sourceRepo: relative(repoRoot, resolved.sourceRepoDir),
+          sourcePath: resolved.sourcePath,
+          destinationPath: resolved.destinationPath,
+        }),
+        resolved.sourceCommit,
+      );
+    }
+  }
+  const crossRepoInputsByConsumer = new Map();
+  for (const input of needed) {
+    requirePin(input.sourceRepo, `vendored into "${input.consumerRepo}"`);
+    // A null `consumerService` means the vendoring step runs for EVERY service
+    // built from that repository; it is keyed on the repository alone.
+    const key = `${input.consumerRepo}\u0000${input.consumerService ?? ''}`;
+    const sourceCommit = vendoredCommitByInputKey.get(
+      consumerInputKey(input.consumerRepo, input),
+    );
+    if (!sourceCommit) {
+      throw new Error(
+        `cross-repo build input for "${input.consumerService}" vendoring ` +
+          `"${input.sourceRepo}:${input.sourcePath}" has no commit in ` +
+          `"${input.consumerRepo}"'s own cross-repo build-input record — its ` +
+          `vendored content cannot be pinned, so the image cannot be addressed`,
+      );
+    }
+    const entries = crossRepoInputsByConsumer.get(key) ?? [];
+    entries.push({
+      destinationPath: input.destinationPath,
+      sourceRepoDir: join(repoRoot, input.sourceRepo),
+      sourcePath: input.sourcePath,
+      sourceCommit,
+    });
+    crossRepoInputsByConsumer.set(key, entries);
+  }
+  return crossRepoInputsByConsumer;
+}
+
+/** The release's inputs: the COMMITTED locks and indexes, read from disk. */
+function releaseImageInputs(schemas, id) {
+  return {
+    lock: validateImmutableDistributionLock(
+      readBoundDistributionFile({
+        distributionsRoot: editionsRoot(),
+        distributionId: id,
+        fileName: 'distribution.lock.json',
+        // A pure READ of the committed lock: the tolerant reader, never the writer.
+        parse: (raw) => parseResolvedDistributionLock(schemas, raw),
+      }).value,
+    ),
+    runtimeSourceIndex: schemas.parseRuntimeImageSourceIndex(readJson(runtimeImageSourceIndexPath())),
+    biomeIndex: readJson(biomeIndexPath()),
+    requiredPlatforms: resolveDistributionRequiredPlatforms(schemas, id),
+    declaredSources: resolveDistributionDeclaredSources(schemas, id),
+  };
+}
+
+/**
+ * A develop snapshot's inputs: the SNAPSHOT distribution lock and the
+ * snapshot indexes and chain (`develop-snapshot-inputs.mjs`), all already
+ * resolved at the snapshot's pins. The runtime index carries the snapshot pins
+ * already and is not re-pinned here.
+ */
+function snapshotImageInputs(schemas, { inputs, lock }) {
+  return {
+    lock: validateImmutableDistributionLock(lock),
+    runtimeSourceIndex: inputs.runtimeImageSourceIndex,
+    biomeIndex: inputs.biomeIndex,
+    requiredPlatforms: schemas.resolveRuntimeImagePlatforms(inputs.composed.requiredPlatforms),
+    declaredSources: inputs.composed.declaredSources,
+  };
+}
+
+export async function resolveImages(id, { inputs, lock } = {}) {
+  assertCanonicalDistributionId(id);
+  if ((inputs === undefined) !== (lock === undefined)) {
+    throw new Error('resolveImages takes the snapshot `inputs` and its distribution `lock` together, or neither');
+  }
+  const schemas = await loadKernelDistributionSchemas();
+  const {
+    lock: distributionLock,
+    runtimeSourceIndex,
+    biomeIndex,
+    requiredPlatforms,
+    declaredSources,
+  } = inputs === undefined ? releaseImageInputs(schemas, id) : snapshotImageInputs(schemas, { inputs, lock });
+  // Materialise every EXTERNAL source at the commit the lock pins, and resolve
+  // every `repo` handle through one locator from here down.
+  const locate = sourceTreeLocator(externalSourceTrees(distributionLock));
+  const structure = resolveComposedProcessStructure(
+    distributionLock,
+    resolveImageStructure(
+      distributionLock,
+      runtimeSourceIndex,
+      schemas,
+      requiredPlatforms,
+      declaredSources,
+      { biomeIndex },
+    ),
+    schemas,
+    requiredPlatforms,
+    { locate },
+  );
+  const commitsBefore = sourceCommitMap(structure, locate);
+  assertSourceManifestParity(structure, commitsBefore, locate);
+  assertExternalSourcesDeclareNoVendoring(distributionLock, locate, commitsBefore);
+
+  const buildStepDirectoriesByRepo = new Map();
+  for (const directory of runtimeSourceIndex.buildStepContextDirectories) {
+    const entries = buildStepDirectoriesByRepo.get(directory.repo) ?? [];
+    entries.push(directory.path);
+    buildStepDirectoriesByRepo.set(directory.repo, entries);
+  }
+  // Vendored content is pinned from the CONSUMER REPOSITORY'S OWN committed
+  // record of what it vendored (`resolveCrossRepoVendoredInputs`) — never from
+  // the index's `repositoryPins` mirror of the vendored axis, and never from this
+  // edition's resolved commit map. The record is read at the CONSUMER's
+  // repository pin, which is what makes the result roster-independent (see
+  // `resolveCrossRepoInputsForRoster`).
+  //
+  // An image's identity is edition-INDEPENDENT, and that still holds: the record
+  // is a property of the consumer's COMMIT, not of any edition, so every edition
+  // shipping a subject derives the same `contentHash` for it.
+  // The first-party `biome-host-api` image is built once, by the producing
+  // repository's CI, which has no notion of an edition and vendors every
+  // declared cross-repo input. Reading the vendored commit from `commitsBefore`
+  // made that edition-independent quantity depend on the edition, which failed
+  // in both directions at once:
+  //   • it is UNCOMPUTABLE for an edition that does not itself resolve the
+  //     source repo — `appliance-lean` and `minimal` do not ship the xema-store
+  //     biome, so re-resolving either one threw here and their locks could not
+  //     be regenerated at all, even though the image they name is the very one
+  //     the other six editions resolve fine;
+  //   • had it not thrown it would have been WORSE, silently minting a second
+  //     content hash for one image — a coordinate no CI ever pushes, which is
+  //     the exact "the tag the lock names does not exist" failure the delivery
+  //     chain exists to prevent (.claude/rules/image-release-coordinate.md).
+  //
+  // Reading `index.repositoryPins` instead was the SAME failure by a different
+  // route, and it shipped. The mirror is generated from the index and committed
+  // separately, so lagging it by a pin is its normal resting state — and the
+  // vendored commit is framed into the image-input hash's component KEY, so a
+  // one-commit lag mints a `contentHash` for byte-identical bytes that no CI run
+  // has ever pushed. Measured 2026-09-07 on `origin/main`: five of sixty-eight
+  // coordinates 404'd for exactly this, while the tags CI DID push were served
+  // on both platforms. The gate that was supposed to catch it,
+  // `tooling/release/check-image-tag-parity.mjs` in the AGGREGATOR (a path that
+  // resolves in no producing repository, though two of them cite it as if it
+  // did), read `index.repositoryPins` too — so both of its halves consumed the
+  // one input that had diverged, and it reported 474/474 verified while the
+  // delivery plane was undeliverable. It now reads the consumer's record, as
+  // this does.
+  const crossRepoInputsByConsumer = resolveCrossRepoInputsForRoster({
+    runtimeSourceIndex,
+    subjects: structure.subjects,
+    composedProcessKind: schemas.RuntimeImageSubjectKind.ComposedProcess,
+  });
+  // A composed image carries EVERY service of its build, so it vendors every
+  // cross-repository input its repository declares — repository-wide and
+  // per-service alike. The set is a property of the repository at its commit,
+  // never of the edition, so every edition derives the same tag for it.
+  const crossRepoInputsFor = (subject) =>
+    subject.kind === schemas.RuntimeImageSubjectKind.ComposedProcess
+      ? [...crossRepoInputsByConsumer]
+          .filter(([key]) => key.startsWith(`${subject.repo}\u0000`))
+          .sort(([a], [b]) => compareStrings(a, b))
+          .flatMap(([, entries]) => entries)
+      : [
+          ...(crossRepoInputsByConsumer.get(`${subject.repo}\u0000`) ?? []),
+          ...(crossRepoInputsByConsumer.get(`${subject.repo}\u0000${subject.id}`) ?? []),
+        ];
+  const subjects = structure.subjects.map((subject) => {
+    const sourceCommit = commitsBefore.get(subject.repo);
+    const repoDirectory = locate(subject.repo).dir;
+    const servicePath = subjectServicePath(subject, sourceCommit, locate);
+    const { sourceManifestPath: ignoredSourceManifestPath, ...lockedSubject } =
+      subject;
+    void ignoredSourceManifestPath;
+    return {
+      ...lockedSubject,
+      sourceCommit,
+      contentHash: exactImageBuildInputHash(
+        {
+          repoDir: repoDirectory,
+          service: subject.id,
+          servicePath,
+          commit: sourceCommit,
+          crossRepoInputs: crossRepoInputsFor(subject),
+          buildStepDirectories:
+            buildStepDirectoriesByRepo.get(subject.repo) ?? [],
+        },
+        imageInputSourceHashAlgorithm(),
+      ),
+    };
+  });
+  const webBiomes = structure.webBiomes.map((biome) => ({
+    ...biome,
+    sourceCommit: commitsBefore.get(biome.repo),
+  }));
+  const imageLock = validateImmutableImageLock(
+    schemas.parseImageLock({
+      schemaVersion: 3,
+      sourceHashAlgorithm: schemas.ImageSourceHashAlgorithm.ImageInputV2,
+      distributionId: id,
+      contractAuthority: runtimeSourceIndex.contractAuthority,
+      subjects,
+      platformServiceBindings: structure.platformServiceBindings,
+      webBiomes,
+    }),
+    schemas,
+  );
+  // The SAME locator the hash used. The default locator resolves every repo
+  // handle to a first-party tree under the aggregator root, so for an edition
+  // with an external source it looked for `<sourcesRoot()>/<source name>`, found no
+  // repository there, and refused with "absent from the local object database"
+  // — after every hash had already been computed correctly through `locate`.
+  // Measured 2026-09-16 resolving a customer edition against a customer root.
+  const commitsAfter = sourceCommitMap(structure, locate);
+  if (serializeJson([...commitsBefore]) !== serializeJson([...commitsAfter])) {
+    throw new Error(
+      'refusing image-lock write: a source repository commit changed while hashing',
+    );
+  }
+  return { imageLock, commits: [...commitsBefore] };
+}
+
+/**
+ * Resolve and persist one schema-v3 image lock. Keeping the explicit trusted
+ * write acknowledgement on this exported boundary means the in-process plane
+ * refresh has the same safety contract as the standalone CLI.
+ */
+export async function writeResolvedImages(
+  id,
+  { trustedWriteV3 = false, log = true } = {},
+) {
+  assertCanonicalDistributionId(id);
+  if (!trustedWriteV3) {
+    throw new Error(
+      'refusing to write a schema-v3 runtime image roster without --trusted-write-v3',
+    );
+  }
+  // The RELEASE lock is published-only: a develop edition resolves through
+  // `develop-edition.mjs` and never reaches this writer.
+  const { imageLock, commits } = await resolveImages(id);
+  const outPath = distributionOutputPath(
+    editionsRoot(),
+    id,
+    'images.lock.json',
+  );
+  assertReleaseContent(imageLock, `the images lock for "${id}"`);
+  writeFileSync(outPath, serializeJson(imageLock));
+  if (log) {
+    console.log(
+      `[dist:images] wrote ${outPath} — ${imageLock.subjects.length} actual runtime image subjects, ${imageLock.webBiomes.length} bundled web biomes, ${imageLock.platformServiceBindings.length} platform bindings.`,
+    );
+    for (const [repo, commit] of commits) {
+      console.log(`  source ${repo}@${commit}`);
+    }
+  }
+  return { imageLock, commits };
+}
+
+async function main() {
+  const id = process.argv[2];
+  const trustedWriteV3 = process.argv.includes('--trusted-write-v3');
+  if (!id) {
+    throw new Error(
+      'usage: resolve-images.mjs <distribution-id> --trusted-write-v3',
+    );
+  }
+  // `--editions-root` (and its `=` spelling, plus the value that follows
+  // the bare form) is consumed by `editionsRoot()` in lib.mjs, off
+  // `process.argv`, before this parser ever runs. It has to be accepted here or
+  // the flag that decides WHICH editions root is read is rejected by the one
+  // command that reads it.
+  const rest = process.argv.slice(3);
+  const unknownArgs = [];
+  for (let i = 0; i < rest.length; i += 1) {
+    const argument = rest[i];
+    if (argument === '--trusted-write-v3') {continue;}
+    unknownArgs.push(argument);
+  }
+  if (unknownArgs.length > 0) {
+    throw new Error(`unknown argument "${unknownArgs[0]}"`);
+  }
+  await writeResolvedImages(id, { trustedWriteV3 });
+}
+
+if (isEntryModule(import.meta.url)) {
+  main().catch((error) => {
+    console.error(`[dist:images] ${error.message}`);
+    process.exit(1);
+  });
+}