@xemahq/edition-tooling 0.0.0-stage → 0.1.0

package/edition/resolve-images.mjs

@@ -0,0 +1,2344 @@
+#!/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 { createHash } from 'node:crypto';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join, relative, sep } from 'node:path';
+import { setImmediate as yieldToEventLoop } from 'node:timers/promises';
+
+import { assertBuildLedgerComplete } from './build-ledger-completeness.mjs';
+import { BUILD_LEDGER_FILE, readBuildLedger } from './build-ledger.mjs';
+import { CROSS_REPO_BUILD_INPUTS_PATH, crossRepoInputKey, resolveCrossRepoVendoredInputs } from './cross-repo-build-inputs.mjs';
+import {
+  resolveDispatchedRuntimeComponents,
+  UndeclaredSupplementalRuntimeComponentError,
+} from './dispatched-runtime-components.mjs';
+import {
+  assertCanonicalDistributionId,
+  distributionOutputPath,
+  readBoundDistributionFile,
+} from './distribution-paths.mjs';
+import { editionWorkspaceConfig, workspaceSection } from './edition-config.mjs';
+import { editionPinnedInputs } from './edition-pinned-inputs.mjs';
+import { dataRoot, editionsRoot, 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 {
+  compareStrings,
+  hashImageBuildInputs,
+  imageInputSourceHashAlgorithm,
+  imageLockWriteSchemaVersion,
+  loadKernelDistributionSchemas,
+  parseResolvedDistributionLock,
+  readGitJsonAtCommit,
+  serializeJson,
+  sha256Hex,
+  validateImmutableDistributionLock,
+  validateImageLockStructure,
+  validateImmutableImageLock,
+} from './lib.mjs';
+import { parsePreviousImageLock } from './previous-image-lock.mjs';
+import { assertReleaseContent } from './release-channel-guard.mjs';
+import { composeEdition } from './resolve-distribution.mjs';
+import { parseStrictJson, readStrictJsonFile } from './strict-json.mjs';
+import { loadThirdPartySourcePins } from './third-party-source-pins.mjs';
+import {
+  assertOciBundleSourceOrigin,
+  attestedContentHash,
+  isThirdPartyOciRow,
+  thirdPartyPinForRow,
+  thirdPartySubjectCandidates,
+} from './third-party-subjects.mjs';
+
+if (isEntryModule(import.meta.url)) {
+  configureEditionWorkspaceFromProcess([WorkspaceRoot.Data, WorkspaceRoot.Editions, WorkspaceRoot.Sources, WorkspaceRoot.Kernel, WorkspaceRoot.Cache]);
+}
+
+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();
+
+/**
+ * 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 a customer environment'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 the first-party biome index. It names, in a refusal,
+ * which biome declares a missing artifact, and it carries each rostered biome's
+ * `dispatchesRuntimeComponents`: the runtime components that biome launches,
+ * whose images enter this roster as runtime-component rows although their
+ * biomes are not rostered (see `dispatched-runtime-components.mjs`).
+ *
+ * `options.supplementalSources` is the edition workspace's
+ * `runtimeImageSources.supplementalSources`: the declarations the source
+ * index's supplemental subjects were built from, carrying each one's
+ * `launchedBy`. A subject launched by a biome ships, owned by that biome, in
+ * every edition whose roster contains it; one a platform service binds ships
+ * with that service. A declared subject with neither is refused by name: it
+ * could never enter any edition, and it used to be dropped silently.
+ */
+export function resolveImageStructure(
+  lock,
+  runtimeSourceIndex,
+  enums,
+  requiredPlatforms,
+  declaredSources,
+  { biomeIndex, supplementalSources, thirdPartyPins } = {},
+) {
+  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`,
+    );
+  }
+  if (!Array.isArray(biomeIndex)) {
+    throw new Error(
+      `distribution "${lock.distributionId}" resolved its images without the biome index — the index carries ` +
+        'the runtime components a rostered biome dispatches, so a roster without it can omit images',
+    );
+  }
+  if (!Array.isArray(supplementalSources)) {
+    throw new Error(
+      `distribution "${lock.distributionId}" resolved its images without the supplemental source declarations — ` +
+        'they say which biome launches a supplemental subject, so a roster without them can omit images',
+    );
+  }
+  const subjects = new Map();
+  // Third-party OCI subjects come from their pin and are never built, hashed or read from a checkout, so they are kept
+  // apart from every git-backed subject (see `third-party-subjects.mjs`).
+  const thirdPartySubjects = 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;
+  };
+  // A supplemental subject of the runtime-image source index, built at its
+  // repository pin, owned by whatever brings it into this edition.
+  const addSupplementalSubject = (supplemental, owners) => {
+    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,
+    });
+  };
+
+  for (const biome of lock.biomes) {
+    const biomeLabel = `distribution "${lock.distributionId}" biome "${biome.id}"`;
+    assertOciBundleSourceOrigin(biome, biomeLabel);
+    if (isThirdPartyOciRow(biome)) {
+      const pin = thirdPartyPinForRow({ row: biome, pins: thirdPartyPins, declaredSources, label: biomeLabel });
+      for (const candidate of thirdPartySubjectCandidates({ row: biome, pin, enums, requiredPlatforms, label: biomeLabel })) {
+        addSubject(thirdPartySubjects, candidate);
+      }
+      continue;
+    }
+    // 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>/<customer>-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,
+          },
+        ],
+      });
+    }
+  }
+
+  // Runtime components a rostered biome DISPATCHES enter the roster as
+  // runtime-component rows built from the TARGET biome's index entry, at its
+  // repository pin, exactly like a rostered biome's own runtime component. The
+  // owner is the rostered biome that dispatches it: the selection that brings
+  // the image into this edition. The target biome stays unrostered.
+  //
+  // A rostered biome's edges are read from ITS index entry, which must describe
+  // the very biome the lock pins; one from a declared source is refused at
+  // distribution resolve if it dispatches, and the first-party index carries
+  // none, so it is not looked up here.
+  const dispatchers = lock.biomes
+    .filter((biome) => biome.source === undefined && !isThirdPartyOciRow(biome) && biome.target === 'server')
+    .map((biome) => {
+      const entries = biomeIndex.filter(
+        (entry) =>
+          entry.id === biome.id &&
+          entry.target === biome.target &&
+          entry.repo === biome.repo &&
+          entry.source === undefined,
+      );
+      if (entries.length !== 1 || entries[0].sourceManifestHash !== biome.sourceManifestHash) {
+        throw new Error(
+          `distribution "${lock.distributionId}" biome "${biome.id}" (${biome.repo}, ${biome.sourceManifestHash}) ` +
+            `has ${entries.length === 1 ? 'a stale' : `${entries.length}`} biome index ${entries.length === 1 ? 'entry' : 'entries'}, ` +
+            'so the runtime components it dispatches cannot be read — re-resolve the edition from the current index',
+        );
+      }
+      return entries[0];
+    });
+  for (const dispatched of resolveDispatchedRuntimeComponents(
+    `distribution "${lock.distributionId}"`,
+    dispatchers,
+    biomeIndex,
+  )) {
+    if (dispatched.supplementalRuntimeComponentId !== undefined) {
+      // THE REFUSAL: a dispatched supplemental runtime component must be one the
+      // runtime image source index declares as a runtime-component subject.
+      // Every image lock is produced here, so this is the one place it is checked.
+      const declared = runtimeSourceIndex.supplementalSubjects.find(
+        (subject) =>
+          subject.kind === enums.RuntimeImageSubjectKind.RuntimeComponent &&
+          subject.id === dispatched.supplementalRuntimeComponentId,
+      );
+      if (declared === undefined) {
+        throw new UndeclaredSupplementalRuntimeComponentError(
+          dispatched.supplementalRuntimeComponentId,
+          dispatched.consumers,
+          `distribution "${lock.distributionId}"`,
+        );
+      }
+      addSupplementalSubject(
+        declared,
+        dispatched.consumers.map((biomeId) => ({ kind: enums.RuntimeImageOwnerKind.Biome, biomeId })),
+      );
+      continue;
+    }
+    const { target } = dispatched;
+    addSubject(subjects, {
+      kind: enums.RuntimeImageSubjectKind.RuntimeComponent,
+      id: dispatched.image,
+      imageRef: imageRefForSubject(dispatched.image, firstPartyImageRegistry(), ''),
+      repo: target.repo,
+      path: target.path,
+      sourceCommit: requireRepositoryPin(target.repo).sourceCommit,
+      sourceManifestHash: target.sourceManifestHash,
+      requiredPlatforms,
+      owners: dispatched.consumers.map((biomeId) => ({
+        kind: enums.RuntimeImageOwnerKind.Biome,
+        biomeId,
+      })),
+    });
+  }
+
+  const runtimeBindings = new Map(
+    runtimeSourceIndex.platformServiceBindings.map((binding) => [
+      binding.platformService,
+      binding,
+    ]),
+  );
+  const supplementalSubjects = new Map(
+    runtimeSourceIndex.supplementalSubjects.map((subject) => [
+      subjectKey(subject),
+      subject,
+    ]),
+  );
+
+  // Supplemental subjects a BIOME launches (`launchedBy`): sealed, owned by
+  // that biome, in every edition whose roster contains it. The catalogue
+  // checks run for every edition, rostered launcher or not.
+  const boundSubjects = new Set(
+    runtimeSourceIndex.platformServiceBindings.map((binding) => bindingKey(binding)),
+  );
+  // A biome's `supplemental:<id>` dispatch edge also carries the subject: the
+  // catalogue check reads the whole first-party index, not this roster, so a
+  // subject reached only by a dispatch is not "unreachable" in any edition.
+  const dispatchedSubjects = new Set(
+    biomeIndex
+      .filter((entry) => entry.source === undefined)
+      .flatMap((entry) => entry.dispatchesRuntimeComponents ?? [])
+      .filter((edge) => edge.supplementalRuntimeComponentId !== undefined)
+      .map((edge) => `${enums.RuntimeImageSubjectKind.RuntimeComponent}\0${edge.supplementalRuntimeComponentId}`),
+  );
+  const launchers = new Map(
+    supplementalSources
+      .filter((source) => source.launchedBy !== undefined)
+      .map((source) => [subjectKey(source), source.launchedBy]),
+  );
+  for (const key of launchers.keys()) {
+    if (!supplementalSubjects.has(key)) {
+      throw new Error(
+        `supplemental source "${key.replace('\0', ':')}" declares a launcher, but the runtime image source index ` +
+          'has no such supplemental subject — rebuild the index from the current declarations',
+      );
+    }
+  }
+  for (const [key, supplemental] of supplementalSubjects) {
+    const launcher = launchers.get(key);
+    if (launcher === undefined) {
+      if (!boundSubjects.has(key) && !dispatchedSubjects.has(key)) {
+        throw new Error(
+          `supplemental subject "${supplemental.kind}:${supplemental.id}" has neither a launchedBy, a ` +
+            'platform-service binding nor a biome dispatching it, so no edition could ever carry it — declare what launches it ' +
+            '(runtimeImageSources.supplementalSources[].launchedBy), bind it to a platform service or dispatch it from a biome',
+        );
+      }
+      continue;
+    }
+    if (!biomeIndex.some((entry) => entry.id === launcher.biomeId && entry.source === undefined)) {
+      throw new Error(
+        `supplemental subject "${supplemental.kind}:${supplemental.id}" is launched by biome ` +
+          `"${launcher.biomeId}", which the first-party biome index does not carry`,
+      );
+    }
+    if (lock.biomes.some((biome) => biome.id === launcher.biomeId)) {
+      addSupplementalSubject(supplemental, [
+        { kind: enums.RuntimeImageOwnerKind.Biome, biomeId: launcher.biomeId },
+      ]);
+    }
+  }
+
+  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) {
+        addSupplementalSubject(supplemental, [
+          {
+            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),
+  );
+  const orderedThirdPartySubjects = [...thirdPartySubjects.values()]
+    .map((subject) => ({ ...subject, owners: subject.owners.sort(compareOwner) }))
+    .sort(compareSubject);
+  for (const subject of orderedThirdPartySubjects) {
+    if (subjects.has(subjectKey(subject))) {
+      throw new Error(
+        `third-party runtime image subject "${subject.kind}:${subject.id}" has the identity of another subject of distribution "${lock.distributionId}"`,
+      );
+    }
+  }
+  return {
+    subjects: orderedSubjects,
+    thirdPartySubjects: orderedThirdPartySubjects,
+    webBiomes,
+    platformServiceBindings,
+  };
+}
+
+/** Every image subject of a structure, first-party and third-party, in the lock's order. */
+export function structureSubjects(structure) {
+  return [...structure.subjects, ...structure.thirdPartySubjects].sort(compareSubject);
+}
+
+/**
+ * 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 the per-class directory
+ *     `infra/composed-process/<class>/` at the repository root (`<class>` a
+ *     kernel `ComposedImageClass`; an edition addresses one composed subject
+ *     per repository, of the kernel's `DEFAULT_COMPOSED_IMAGE_CLASS`). A commit
+ *     that predates the per-class layout declares it at the legacy root
+ *     `infra/composed-process/`, which stays readable because committed release
+ *     locks still pin such commits. Both at once, or a declaration in another
+ *     class directory, is refused (`composedProcessDeclarationDir`). The
+ *     directory holds 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 in that
+ *     directory at the pinned commit. A repository that declares none (and has
+ *     no `infra/composed-process/` tree at all) 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) };
+}
+
+/**
+ * A composed-process declaration the build cannot be read from. Named so a
+ * caller can tell "this image's inputs are unknown" from any other refusal:
+ * the carried set is evidence, and with none there is no owner to derive.
+ */
+export class ComposedProcessWorkerError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'ComposedProcessWorkerError';
+  }
+}
+
+export class ComposedProcessInputsError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'ComposedProcessInputsError';
+  }
+}
+
+/**
+ * Which of a repository's biome services the composed image CARRIES, read from
+ * the composed build's own inputs at the sealed commit.
+ *
+ * `image-build-inputs.json` lists the member package directories the image is
+ * built from (its hash is the subject's `sourceManifestHash`). A service is
+ * carried when its manifest-declared source directory (`subjectServicePath`,
+ * the `components[].artifact.path` mapping) is one of them. Returns one row
+ * per biome: the service ids carried and the ones not.
+ */
+/** A component's declared `imageClass` validated with the kernel's own schema; absent stays undefined (the default applies). */
+function declaredImageClass(declared, subject, enums) {
+  if (declared === undefined) {return undefined;}
+  const parsed = enums.ComposedImageClassSchema.safeParse(declared);
+  if (!parsed.success) {
+    throw new ComposedProcessInputsError(
+      `service "${subject.id}" of ${subject.repo} declares components[].imageClass ${JSON.stringify(declared)}, which is not an image class the kernel knows`,
+    );
+  }
+  return parsed.data;
+}
+
+function composedProcessCarriage(structure, enums, repo, sourceCommit, locate, declarationDir) {
+  const inputsPath = `${declarationDir}/${COMPOSED_PROCESS_DECLARATION_FILE}`;
+  const { dir } = locate(repo);
+  let members;
+  try {
+    members = readGitJsonAtCommit(dir, inputsPath, sourceCommit)?.workspacePackages;
+  } catch (cause) {
+    throw new ComposedProcessInputsError(
+      `composed-process inputs "${inputsPath}" of "${repo}" are unreadable at ${sourceCommit} ` +
+        `(${cause.message}) — the biomes the image carries cannot be derived`,
+    );
+  }
+  if (!Array.isArray(members) || members.some((member) => typeof member !== 'string')) {
+    throw new ComposedProcessInputsError(
+      `composed-process inputs "${inputsPath}" of "${repo}" at ${sourceCommit} declare no ` +
+        '"workspacePackages" array of directories — the biomes the image carries cannot be derived',
+    );
+  }
+  const carried = new Set(members);
+  const byBiome = new Map();
+  for (const subject of structure.subjects) {
+    if (subject.kind !== enums.RuntimeImageSubjectKind.Service || subject.repo !== repo) {continue;}
+    const { path: servicePath, componentKind, imageClass: declaredClass } = subjectServiceSource(subject, sourceCommit, locate);
+    const imageClass = declaredImageClass(declaredClass, subject, enums);
+    for (const owner of subject.owners) {
+      if (owner.kind !== enums.RuntimeImageOwnerKind.Biome) {continue;}
+      const row = byBiome.get(owner.biomeId) ??
+        { biomeId: owner.biomeId, carried: [], uncarried: [], carriedWorkers: [], packageDirs: {}, imageClasses: {} };
+      if (!carried.has(servicePath)) {
+        row.uncarried.push(subject.id);
+      } else if (componentKind === 'worker') {
+        // A worker is never a member: it runs as its own Deployment.
+        row.carriedWorkers.push(subject.id);
+      } else {
+        row.carried.push(subject.id);
+        // The member's package directory IS the composed build's own input entry.
+        row.packageDirs[subject.id] = servicePath;
+        // The class its manifest declares (`components[].imageClass`); absent stays undefined (the kernel default applies).
+        row.imageClasses[subject.id] = imageClass;
+      }
+      byBiome.set(owner.biomeId, row);
+    }
+  }
+  return [...byBiome.values()]
+    .map((row) => ({
+      ...row,
+      carried: row.carried.sort(compareStrings),
+      uncarried: row.uncarried.sort(compareStrings),
+      carriedWorkers: row.carriedWorkers.sort(compareStrings),
+    }))
+    .sort((a, b) => compareStrings(a.biomeId, b.biomeId));
+}
+
+function gitPathExistsAtCommit(dir, sourceCommit, repoPath) {
+  try {
+    execFileSync('git', ['-C', dir, 'cat-file', '-e', `${sourceCommit}:${repoPath}`], {
+      stdio: ['ignore', 'ignore', 'ignore'],
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The repo-relative directory holding a repository's composed-process
+ * DECLARATION at one commit, or null when it declares none. The default class's
+ * directory and the legacy root are the two places an edition reads; a
+ * declaration it cannot address (both present, another class, an
+ * `infra/composed-process/` tree without a recognised one) is refused, because
+ * a declaration the resolver cannot find must never read as "declares nothing".
+ */
+function composedProcessDeclarationDir(dir, sourceCommit, enums) {
+  const defaultClass = enums.DEFAULT_COMPOSED_IMAGE_CLASS;
+  const classDir = `${COMPOSED_PROCESS_IMAGE_PATH}/${defaultClass}`;
+  const declares = (candidate) =>
+    gitPathExistsAtCommit(dir, sourceCommit, `${candidate}/${COMPOSED_PROCESS_DECLARATION_FILE}`);
+  const inClassDir = declares(classDir);
+  const atLegacyRoot = declares(COMPOSED_PROCESS_IMAGE_PATH);
+  if (inClassDir && atLegacyRoot) {
+    throw new ComposedProcessInputsError(
+      `ambiguous composed-process declaration at ${sourceCommit}: both "${classDir}/${COMPOSED_PROCESS_DECLARATION_FILE}" ` +
+        `and the legacy "${COMPOSED_PROCESS_IMAGE_PATH}/${COMPOSED_PROCESS_DECLARATION_FILE}" exist`,
+    );
+  }
+  const otherClasses = enums.ComposedImageClassSchema.options
+    .filter((candidate) => candidate !== defaultClass)
+    .filter((candidate) => declares(`${COMPOSED_PROCESS_IMAGE_PATH}/${candidate}`));
+  if (otherClasses.length > 0) {
+    throw new ComposedProcessInputsError(
+      `composed-process declaration at ${sourceCommit} is in the "${otherClasses.join('", "')}" class ` +
+        `director${otherClasses.length > 1 ? 'ies' : 'y'}, but an edition addresses one composed-process subject per ` +
+        `repository, of the default class "${defaultClass}"; a "${otherClasses[0]}" image has no subject naming yet`,
+    );
+  }
+  if (inClassDir) {return classDir;}
+  if (atLegacyRoot) {return COMPOSED_PROCESS_IMAGE_PATH;}
+  if (gitPathExistsAtCommit(dir, sourceCommit, COMPOSED_PROCESS_IMAGE_PATH)) {
+    throw new ComposedProcessInputsError(
+      `"${COMPOSED_PROCESS_IMAGE_PATH}" exists at ${sourceCommit} but declares no composed-process image the edition can ` +
+        `read: looked at "${classDir}/${COMPOSED_PROCESS_DECLARATION_FILE}" and ` +
+        `"${COMPOSED_PROCESS_IMAGE_PATH}/${COMPOSED_PROCESS_DECLARATION_FILE}"`,
+    );
+  }
+  return null;
+}
+
+/**
+ * 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);
+    // 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',
+      );
+    }
+    const declarationDir = composedProcessDeclarationDir(dir, sourceCommit, enums);
+    if (declarationDir === null) {continue;} // declares no composed-process image at this commit
+    const declarationPath = `${declarationDir}/${COMPOSED_PROCESS_DECLARATION_FILE}`;
+    const sourceId = sourceIds.get(repo);
+    const repoRelative = relative(base, dir).split(sep).join('/');
+    declarations.push({
+      repo,
+      sourceId,
+      sourceCommit,
+      carriage: composedProcessCarriage(structure, enums, repo, sourceCommit, locate, declarationDir),
+      path: `${repoRelative}/${declarationDir}`,
+      sourceManifestPath: `${repoRelative}/${declarationPath}`,
+      sourceManifestHash: exactSourceManifestHash(dir, declarationPath, sourceCommit),
+    });
+  }
+  return declarations;
+}
+
+/**
+ * The image class of one composed artifact, DERIVED from its members' manifests: each member's `components[].imageClass`,
+ * absent meaning the kernel's `DEFAULT_COMPOSED_IMAGE_CLASS`. All members must agree; a mixed artifact is refused naming
+ * the artifact and the members of each class.
+ */
+export function composedArtifactImageClass(artifactId, memberRows, declaredClassOf, enums) {
+  const byClass = new Map();
+  for (const { service } of memberRows) {
+    const declared = declaredClassOf.get(service);
+    const imageClass = declared ?? enums.DEFAULT_COMPOSED_IMAGE_CLASS;
+    byClass.set(imageClass, [...(byClass.get(imageClass) ?? []), service]);
+  }
+  if (byClass.size > 1) {
+    const detail = [...byClass].sort(([a], [b]) => compareStrings(a, b)).map(([imageClass, services]) => `${imageClass}: ${services.join(', ')}`).join('; ');
+    throw new ComposedProcessInputsError(
+      `composed-process artifact "${artifactId}" mixes image classes across its members (${detail}) — ` +
+        'an artifact has one class; split the members or align their components[].imageClass',
+    );
+  }
+  return [...byClass.keys()][0];
+}
+
+/** The services the edition SELECTS, read off its distribution lock: every service of every non-web biome whose image is its own (a shared-image worker is not one). */
+export function editionRosterServices(distributionLock) {
+  return distributionLock.biomes
+    .filter((biome) => biome.target !== 'web')
+    .flatMap((biome) => {
+      const shared = new Set(Object.keys(biome.workerImages ?? {}));
+      return (biome.services ?? []).filter((service) => !shared.has(service));
+    });
+}
+
+/**
+ * Refuse a build that does not cover every service of the edition roster: each must be a dedicated service subject or a
+ * member of a built composed artifact. A service neither is never dropped from the lock silently, and the carry-forward
+ * (which sees only what was built) is never the one to lose it.
+ */
+export function assertBuiltCoversEditionRoster({ rosterServices, serviceSubjects, composedBuilt }) {
+  const covered = new Set([
+    ...serviceSubjects.map((subject) => subject.id),
+    ...composedBuilt.flatMap((artifact) => (artifact.members ?? []).map((member) => member.service)),
+  ]);
+  const missing = [...new Set(rosterServices)].filter((service) => !covered.has(service)).sort(compareStrings);
+  if (missing.length > 0) {
+    throw new ComposedProcessInputsError(
+      `the build covers no image for ${missing.map((service) => `"${service}"`).join(', ')} of the edition roster — ` +
+        'a service of the edition is never dropped from the lock',
+    );
+  }
+}
+
+/** The members of a composed subject with the key of each: the member service's own image-input hash (the one function the packager's tag is emitted from). */
+export function composedMemberKeys({ subject, repoDirectory, sourceCommit, crossRepoInputsByConsumer, buildStepDirectories, hash = exactImageBuildInputHash }) {
+  return subject.members.map((member) => ({
+    ...member,
+    key: hash(
+      {
+        repoDir: repoDirectory,
+        service: member.service,
+        servicePath: member.packageDir,
+        commit: sourceCommit,
+        crossRepoInputs: [
+          ...(crossRepoInputsByConsumer.get(`${subject.repo}\u0000`) ?? []),
+          ...(crossRepoInputsByConsumer.get(`${subject.repo}\u0000${member.service}`) ?? []),
+        ],
+        buildStepDirectories,
+      },
+      imageInputSourceHashAlgorithm(),
+    ),
+  }));
+}
+
+/**
+ * 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 the image CARRIES, derived from the composed build's
+ * inputs at the sealed commit (`declaration.carriage`): every biome at least one
+ * of whose services is a member, never every biome with a service in the
+ * repository. The members leave the structure and are sealed on the subject
+ * as `members[{ service, packageDir }]` — the per-service membership truth: a
+ * service runs from the composed digest if and only if it is a row (owners
+ * never resolve a service). The edition carries the composed subject plus the
+ * services that are no row (the specials, which keep their own subjects even
+ * inside an owner biome), and nothing addresses a member's own image. A worker
+ * is never a row; an own-image worker the composed build carries is refused.
+ */
+export function withComposedProcessSubjects(
+  structure,
+  declarations,
+  enums,
+  requiredPlatforms,
+  { onNotice = (message) => console.warn(`[dist:images] ${message}`) } = {},
+) {
+  if (declarations.length === 0) {return structure;}
+  const subjects = new Map(structure.subjects.map((subject) => [subjectKey(subject), subject]));
+  // A biome's members run from ONE composed image: a biome owning two composed
+  // subjects would leave its pods two images to choose between.
+  const composedOwnerOf = new Map();
+  for (const declaration of declarations) {
+    const services = structure.subjects.filter(
+      (subject) =>
+        subject.kind === enums.RuntimeImageSubjectKind.Service && subject.repo === declaration.repo,
+    );
+    if (!Array.isArray(declaration.carriage)) {
+      throw new ComposedProcessInputsError(
+        `composed-process declaration for "${declaration.repo}" carries no evidence of the ` +
+          'biomes the image carries — refusing to guess its owners',
+      );
+    }
+    // Owners are the biomes ANY of whose services the image carries. A biome
+    // with only some carried is an owner too; its services the image does not
+    // carry are specials and keep their own subjects (named here). A biome with
+    // none carried is simply not one.
+    const biomeOwners = [];
+    const members = new Set();
+    const packageDirOf = new Map();
+    const imageClassOf = new Map();
+    for (const row of declaration.carriage) {
+      // A worker is never a member. One the composed build carries must run
+      // from a carried sibling's image (`workerImages`, declared in the
+      // manifest), never be dropped into the composed process or fall back.
+      for (const worker of row.carriedWorkers ?? []) {
+        throw new ComposedProcessWorkerError(
+          row.carried.length === 0
+            ? `composed-process "${declaration.repo}" carries worker "${worker}" of biome "${row.biomeId}", ` +
+                'and that biome has no carried service whose image it could run — a worker is never a ' +
+                'composed member; carry a service of its biome or take the worker out of the composed inputs'
+            : `composed-process "${declaration.repo}" carries worker "${worker}" of biome "${row.biomeId}" as ` +
+                'its own oci-image — a worker is never a composed member; declare it `artifact.kind: ' +
+                `shared-oci-image\` of a carried service (${row.carried.join(', ')}) or take it out of the composed inputs`,
+        );
+      }
+      if (row.carried.length === 0) {continue;}
+      if (row.uncarried.length > 0) {
+        onNotice(
+          `composed-process "${declaration.repo}": biome "${row.biomeId}" is partly carried ` +
+            `(carried: ${row.carried.join(', ')}; not carried: ${row.uncarried.join(', ')}) — ` +
+            'its uncarried services keep their own subjects',
+        );
+      }
+      const other = composedOwnerOf.get(row.biomeId);
+      if (other !== undefined) {
+        throw new Error(
+          `biome "${row.biomeId}" is carried by the composed-process images of both "${other}" and ` +
+            `"${declaration.repo}" — a biome is owned by exactly one composed subject`,
+        );
+      }
+      composedOwnerOf.set(row.biomeId, declaration.repo);
+      biomeOwners.push({ kind: enums.RuntimeImageOwnerKind.Biome, biomeId: row.biomeId });
+      for (const id of row.carried) {members.add(id);}
+      for (const [id, packageDir] of Object.entries(row.packageDirs ?? {})) {packageDirOf.set(id, packageDir);}
+      for (const [id, imageClass] of Object.entries(row.imageClasses ?? {})) {imageClassOf.set(id, imageClass);}
+    }
+    if (biomeOwners.length === 0) {
+      throw new Error(
+        `composed-process declaration for "${declaration.repo}" carries no biome's services 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`,
+      );
+    }
+    // A MEMBER reaches its pods through this one subject (every member runs as a
+    // group-of-one of the composed image), so it carries no subject of its own:
+    // no `<imageRef>:<contentHash>` of its own is probed, verified or sealed. A
+    // member is a service of this build the composed build's inputs carry
+    // (`declaration.carriage`), every owner of which is a biome owning the
+    // composed image. Any other service (not carried, or owned by anything but
+    // a biome, e.g. shared with a platform service) keeps its own.
+    const composedOwners = new Set(biomeOwners.map((owner) => owner.biomeId));
+    const memberRows = [];
+    for (const subject of services) {
+      if (
+        members.has(subject.id) &&
+        subject.owners.length > 0 &&
+        subject.owners.every(
+          (owner) => owner.kind === enums.RuntimeImageOwnerKind.Biome && composedOwners.has(owner.biomeId),
+        )
+      ) {
+        subjects.delete(subjectKey(subject));
+        const packageDir = packageDirOf.get(subject.id);
+        if (packageDir === undefined) {
+          throw new ComposedProcessInputsError(
+            `composed-process "${declaration.repo}": member "${subject.id}" has no package directory in ` +
+              'the composed build inputs — its shared-image workers would have nowhere to run from',
+          );
+        }
+        memberRows.push({ service: subject.id, packageDir });
+      }
+    }
+    if (memberRows.length === 0) {
+      throw new ComposedProcessInputsError(
+        `composed-process "${declaration.repo}" has no member: every service its build carries ` +
+          `(${[...members].sort(compareStrings).join(', ')}) is also owned by something other than a biome ` +
+          'it owns (e.g. a platform service), so each keeps its own subject — a composed image with no ' +
+          'member runs nothing; take it out of the edition or carry a biome-owned service',
+      );
+    }
+    memberRows.sort((a, b) => compareStrings(a.service, b.service));
+    const id = composedProcessSubjectId(declaration.sourceId);
+    const imageClass = composedArtifactImageClass(id, memberRows, imageClassOf, enums);
+    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,
+      members: memberRows,
+      imageClass,
+    });
+  }
+  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, onNotice } = {},
+) {
+  return withComposedProcessSubjects(
+    structure,
+    readComposedProcessDeclarations(
+      structure,
+      enums,
+      editionSourceIds(lock),
+      // Materialised only when something will be read through it.
+      locate ?? sourceTreeLocator(externalSourceTrees(lock)),
+    ),
+    enums,
+    requiredPlatforms,
+    onNotice === undefined ? undefined : { onNotice },
+  );
+}
+
+/**
+ * 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) {
+  return subjectServiceSource(subject, sourceCommit, locate).path;
+}
+
+/**
+ * The repository-relative source directory of a subject and the kind of the
+ * manifest component it is built from (`worker` for a worker component,
+ * `service` otherwise — a legacy `ships.apis[]` entry or a subject with its own
+ * source manifest is not a worker).
+ */
+function subjectServiceSource(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 { path: toRepoRelative(join(base, subject.path)), componentKind: 'service', imageClass: undefined };
+  }
+  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;
+  let componentKind = 'service';
+  let imageClass;
+  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;
+    componentKind = component.kind;
+    imageClass = component.imageClass;
+  } 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 { path: toRepoRelative(join(base, subject.path, servicePath)), componentKind, imageClass };
+}
+
+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 lock, and the edition's own indexes
+ * (`editionPinnedInputs`: the committed ones, or rebuilt at the repositories the
+ * edition holds).
+ */
+async function releaseImageInputs(schemas, id) {
+  const pinned = await editionPinnedInputs(id, { schemas });
+  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: pinned.runtimeImageSourceIndex,
+    biomeIndex: pinned.biomeIndex,
+    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,
+  };
+}
+
+/**
+ * The supplemental source declarations an image resolve reads beside
+ * `runtimeSourceIndex`. An index with no supplemental subjects (a customer
+ * edition's own rows) needs none, and its workspace need not declare the
+ * section; any other reads the edition workspace's.
+ */
+export function supplementalSourcesFor(runtimeSourceIndex) {
+  return runtimeSourceIndex.supplementalSubjects.length === 0
+    ? []
+    : workspaceSection('runtimeImageSources', 'resolving supplemental image subjects').supplementalSources;
+}
+
+/**
+ * The image ROWS of one edition: its subjects (hashed at the commits the lock
+ * pins), its platform-service bindings and its bundled web biomes, after every
+ * check that needs no parsed lock. Rows are not a lock: the kernel's image-lock
+ * grammar is the grammar of a COMPLETE lock, and a caller that holds only part
+ * of one (a customer's own rows, merged with the catalogue's) parses the lock
+ * it completes. `resolveImages` is these rows parsed as the whole lock.
+ */
+export async function resolveImageRows(id, { inputs, lock, onSubjectHashed, recordedImages, previousLock = null } = {}) {
+  assertCanonicalDistributionId(id);
+  if ((inputs === undefined) !== (lock === undefined)) {
+    throw new Error('resolveImages takes the snapshot `inputs` and its distribution `lock` together, or neither');
+  }
+  // A build record (images-from-record.mjs) replaces the hashing on the snapshot lane only, and never beside a probe.
+  if (recordedImages !== undefined && (inputs === undefined || onSubjectHashed !== undefined)) {
+    throw new Error('resolveImages takes recorded images only on the snapshot lane, and never with onSubjectHashed');
+  }
+  const schemas = await loadKernelDistributionSchemas();
+  const {
+    lock: distributionLock,
+    runtimeSourceIndex,
+    biomeIndex,
+    requiredPlatforms,
+    declaredSources,
+  } = inputs === undefined ? await 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,
+        supplementalSources: supplementalSourcesFor(runtimeSourceIndex),
+        thirdPartyPins: loadThirdPartySourcePins(dataRoot()),
+      },
+    ),
+    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` does not ship the xema-store
+  //     biome, so re-resolving it 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 = [];
+  for (const subject of structure.subjects) {
+    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;
+    // With a build record the content hash and source commit are the record's, carried and never recomputed. The one
+    // exception a record source may declare (`computesHash`, develop image-record only) is a subject no build record
+    // covers: a member that keeps its current resolution (develop-current-resolution.mjs, XEMA-2373), hashed here.
+    const isComposed = subject.kind === schemas.RuntimeImageSubjectKind.ComposedProcess;
+    const computesHash = recordedImages === undefined || recordedImages.computesHash?.(lockedSubject) === true;
+    const hashed = computesHash ? {
+      ...lockedSubject,
+      sourceCommit,
+      // The hashing lane computes each member's key itself: the member service's own image-input hash.
+      ...(isComposed ? {
+        members: composedMemberKeys({
+          subject,
+          repoDirectory,
+          sourceCommit,
+          crossRepoInputsByConsumer,
+          buildStepDirectories: buildStepDirectoriesByRepo.get(subject.repo) ?? [],
+        }),
+      } : {}),
+      contentHash: exactImageBuildInputHash(
+        {
+          repoDir: repoDirectory,
+          service: subject.id,
+          servicePath,
+          commit: sourceCommit,
+          crossRepoInputs: crossRepoInputsFor(subject),
+          buildStepDirectories:
+            buildStepDirectoriesByRepo.get(subject.repo) ?? [],
+        },
+        imageInputSourceHashAlgorithm(),
+      ),
+    } : { ...lockedSubject, ...recordedImages.take({ ...lockedSubject, sourceCommit }) };
+    subjects.push(hashed);
+    // The hash is the last thing a registry probe waits for: hand the subject
+    // over now, and let the event loop run so the probes of the subjects
+    // already hashed progress while the rest hash (hashing is synchronous).
+    if (onSubjectHashed !== undefined) {
+      onSubjectHashed(hashed);
+      await yieldToEventLoop();
+    }
+  }
+  // Every subject missing from, contradicted by or extra in the build record, refused at once.
+  recordedImages?.settle();
+  // The composed artifacts are sealed with their generation: the roster's composed services must all be built, then the
+  // kernel carries the previous lock's still-pinned artifacts forward (`previousLock` null or a v4 lock: generation 1).
+  const ComposedProcess = schemas.RuntimeImageSubjectKind.ComposedProcess;
+  const composedBuilt = subjects.filter((subject) => subject.kind === ComposedProcess);
+  assertBuiltCoversEditionRoster({
+    rosterServices: editionRosterServices(distributionLock),
+    serviceSubjects: [...subjects, ...structure.thirdPartySubjects].filter((subject) => subject.kind === schemas.RuntimeImageSubjectKind.Service),
+    composedBuilt,
+  });
+  if (composedBuilt.length > 0 || previousLock !== null) {
+    const sealed = schemas.carryForwardComposedArtifacts({ previous: previousLock, built: composedBuilt });
+    subjects.splice(0, subjects.length, ...subjects.filter((subject) => subject.kind !== ComposedProcess), ...sealed);
+    subjects.sort(compareSubject);
+  }
+  // Release lane only: a develop snapshot or customer overlay is not covered by
+  // the committed ledger.
+  if (inputs === undefined) {
+    assertBuildLedgerComplete({
+      ledger: readBuildLedger(),
+      distributionId: id,
+      subjects,
+      requiredPlatforms,
+      expectedAt: join(dataRoot(), BUILD_LEDGER_FILE),
+    });
+  }
+  const webBiomes = structure.webBiomes.map((biome) => ({
+    ...biome,
+    sourceCommit: commitsBefore.get(biome.repo),
+  }));
+  // 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',
+    );
+  }
+  // After the ledger check and the hashing: a third-party subject has no ledger row and no checkout, and its
+  // `contentHash` is the publisher's statement, so none of the above read it.
+  return {
+    subjects: structure.thirdPartySubjects.length === 0 ? subjects : [...subjects, ...structure.thirdPartySubjects].sort(compareSubject),
+    thirdPartySubjects: structure.thirdPartySubjects,
+    platformServiceBindings: structure.platformServiceBindings,
+    webBiomes,
+    contractAuthority: runtimeSourceIndex.contractAuthority,
+    commits: [...commitsBefore],
+  };
+}
+
+export const PREVIOUS_SEAL_USAGE =
+  'exactly one of `--previous-lock <images.lock.json> --previous-lock-sha256 <hex>` (the images.lock layer of the previous ' +
+  'edition, taken by the caller) or `--first-seal` (only for a distribution that has never had an edition)';
+
+/**
+ * The previous seal an images-lock write carries composed artifacts forward from, as an EXPLICIT input of exactly one kind:
+ * - the previous lock with the sha256 of its bytes (taken by the caller from the published edition's images.lock layer);
+ * - `--first-seal` (null: generation 1).
+ * None, both kinds, or half of the pair is refused; the bytes must hash to the given digest, and the lock is parsed
+ * with the kernel's `parseImageLock` and must be this edition's own (`distributionId`).
+ */
+export async function resolvePreviousSeal({ distributionId, previousLockPath, previousLockSha256, firstSeal = false }) {
+  const given = [previousLockPath, previousLockSha256].filter((value) => value !== undefined);
+  if (firstSeal && given.length > 0) {
+    throw new Error(`more than one previous seal is given (--previous-lock/--previous-lock-sha256, --first-seal); give ${PREVIOUS_SEAL_USAGE}`);
+  }
+  if (firstSeal) {return null;}
+  if (given.length !== 2) {
+    throw new Error(
+      given.length === 0
+        ? `no previous seal is given; give ${PREVIOUS_SEAL_USAGE}`
+        : `--previous-lock and --previous-lock-sha256 go together (one was given); give ${PREVIOUS_SEAL_USAGE}`,
+    );
+  }
+  const bytes = readPreviousLockBytes(previousLockPath, previousLockSha256);
+  return parsePreviousLock(distributionId, parseStrictJson(bytes.toString('utf8'), previousLockPath), '--previous-lock');
+}
+
+/**
+ * The bytes of a previous lock file, held to the sha256 (hex) they were given with: the one check of the pair
+ * (`flags` names the pair in the refusal). The parse, with the kernel and against the edition's id, is the caller's.
+ */
+export function readPreviousLockBytes(path, sha256, flags = { lock: '--previous-lock', sha256: '--previous-lock-sha256' }) {
+  const bytes = readFileSync(path);
+  const actual = createHash('sha256').update(bytes).digest('hex');
+  if (actual !== sha256) {
+    throw new Error(`${flags.lock} ${path} has sha256 ${actual}, not the given ${flags.sha256} ${sha256}`);
+  }
+  return bytes;
+}
+
+/** The in-repo lane's previous lock: the committed file at `outPath`, parsed before it is overwritten; null (first seal) when there is none. */
+export async function readCommittedPreviousLock(distributionId, outPath) {
+  return existsSync(outPath) ? parsePreviousLock(distributionId, readStrictJsonFile(outPath), outPath) : null;
+}
+
+async function parsePreviousLock(distributionId, document, label) {
+  const previous = parsePreviousImageLock(await loadKernelDistributionSchemas(), document);
+  if (previous.distributionId !== distributionId) {
+    throw new Error(`${label} is the images lock of "${previous.distributionId}", not of "${distributionId}"`);
+  }
+  return previous;
+}
+
+/**
+ * The composed artifacts of a STRUCTURAL view (no source hashing), carried forward from `previousLock` through the kernel's own
+ * `carryForwardComposedArtifacts`, exactly as a reseal does. A structural subject has no content hash or member keys; each
+ * composed id takes them from its newest previous artifact (a structure the previous lock does not cover keeps none, and the
+ * kernel refuses it: the caller reports that as out of date). Source drift is `--check-sources`' job, through `resolveImages`.
+ */
+export function carryComposedForwardStructurally({ subjects, previousLock, schemas }) {
+  const ComposedProcess = schemas.RuntimeImageSubjectKind.ComposedProcess;
+  const newest = new Map();
+  for (const subject of previousLock?.subjects ?? []) {
+    if (subject.kind === ComposedProcess && (newest.get(subject.id)?.generation ?? 0) <= (subject.generation ?? 0)) {newest.set(subject.id, subject);}
+  }
+  const built = subjects.filter((subject) => subject.kind === ComposedProcess).map((subject) => {
+    const previous = newest.get(subject.id);
+    if (previous === undefined) {return subject;}
+    const keyOf = new Map((previous.members ?? []).map((member) => [member.service, member.key]));
+    return {
+      ...subject,
+      contentHash: previous.contentHash,
+      members: (subject.members ?? []).map((member) => (keyOf.has(member.service) ? { ...member, key: keyOf.get(member.service) } : member)),
+    };
+  });
+  if (built.length === 0 && previousLock === null) {return subjects;}
+  const sealed = schemas.carryForwardComposedArtifacts({ previous: previousLock, built });
+  return [...subjects.filter((subject) => subject.kind !== ComposedProcess), ...sealed].sort(compareSubject);
+}
+
+/** One edition's COMPLETE image lock: its rows, parsed and validated as the kernel's image lock. */
+export async function resolveImages(id, { inputs, lock, onSubjectHashed, recordedImages, previousLock = null } = {}) {
+  const { subjects, thirdPartySubjects, platformServiceBindings, webBiomes, contractAuthority, commits } = await resolveImageRows(id, { inputs, lock, onSubjectHashed, recordedImages, previousLock });
+  const schemas = await loadKernelDistributionSchemas();
+  // A lock whose hashes are a build record's (recordedImages) computed none, so only its structure is checked.
+  const validate = recordedImages === undefined ? validateImmutableImageLock : validateImageLockStructure;
+  const imageLock = validate(
+    schemas.parseImageLock({
+      schemaVersion: imageLockWriteSchemaVersion(schemas, subjects, `distribution "${id}"`),
+      sourceHashAlgorithm: schemas.ImageSourceHashAlgorithm.ImageInputV2,
+      distributionId: id,
+      contractAuthority,
+      subjects,
+      platformServiceBindings,
+      webBiomes,
+    }),
+    schemas,
+  );
+  return { imageLock, commits, thirdPartySubjects };
+}
+
+/**
+ * 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, previousLockPath = undefined, previousLockSha256 = undefined, firstSeal = false, previousFromTarget = false } = {},
+) {
+  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 outPath = distributionOutputPath(
+    editionsRoot(),
+    id,
+    'images.lock.json',
+  );
+  // The in-repo lane: the previous lock is the committed file at the target path (git is its authority), read before it is
+  // overwritten; with no file there, this is the first seal.
+  const previousLock = previousFromTarget
+    ? await readCommittedPreviousLock(id, outPath)
+    : await resolvePreviousSeal({ distributionId: id, previousLockPath, previousLockSha256, firstSeal });
+  if (previousFromTarget && previousLock === null && log) {console.log(`[dist:images] ${id}: first seal: no previous images.lock.json`);}
+  const { imageLock, commits, thirdPartySubjects } = await resolveImages(id, { previousLock });
+  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}`);
+    }
+    for (const subject of thirdPartySubjects) {
+      console.log(`  third-party ${subject.kind}:${subject.id} ${subject.imageRef} ${attestedContentHash(subject)}`);
+    }
+  }
+  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 (${PREVIOUS_SEAL_USAGE})`,
+    );
+  }
+  // `--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 = [];
+  let previousLockPath;
+  let previousLockSha256;
+  let firstSeal = false;
+  for (let i = 0; i < rest.length; i += 1) {
+    const argument = rest[i];
+    if (argument === '--trusted-write-v3') {continue;}
+    if (argument === '--first-seal') {
+      firstSeal = true;
+      continue;
+    }
+    if (argument === '--previous-lock' || argument === '--previous-lock-sha256') {
+      i += 1;
+      if (rest[i] === undefined) {throw new Error(`${argument} needs a value`);}
+      if (argument === '--previous-lock') {previousLockPath = rest[i];} else {previousLockSha256 = rest[i];}
+      continue;
+    }
+    unknownArgs.push(argument);
+  }
+  if (unknownArgs.length > 0) {
+    throw new Error(`unknown argument "${unknownArgs[0]}"`);
+  }
+  await writeResolvedImages(id, { trustedWriteV3, previousLockPath, previousLockSha256, firstSeal });
+}
+
+if (isEntryModule(import.meta.url)) {
+  main().catch((error) => {
+    console.error(`[dist:images] ${error.message}`);
+    process.exit(1);
+  });
+}