@xemahq/xema 0.54.0 → 0.56.0

package/edition/develop-image-record.mjs

@@ -0,0 +1,194 @@
+// develop-image-record — the body of `xema edition develop image-record <id> --selection <file> --pins <file> --out <file>`.
+//
+// Writes the edition's image build record (images-from-record.mjs, the file `resolve --images-from` reads) from the
+// records `select-records` selected. Its subjects are per-edition (`<kind>:<id>`), so they come from the checked-out
+// snapshot, which select-records cannot know: the subjects are enumerated as `coverage` enumerates them
+// (resolveDevelopSnapshot, then resolveImages on the normal hashing path, no recorded images).
+//
+//   a first-party subject of a currentResolution member (develop-current-resolution.mjs) is probed as resolve probes it
+//   (createDevelopImageProbe): the digest `<develop repository>:<contentHash>` resolves to goes in `images`, with the
+//   computed hash and the snapshot's source commit.
+//   every other first-party subject takes the selection's image named by its develop repository: digest and hash from
+//   the selection, source commit the one selection.pins names for the repository, which must be the snapshot's. It goes
+//   in `satellites`. Several subjects may share one image.
+//   a third-party subject is ignored: it keeps its pinned seal at resolve.
+//
+// Each entry's platforms are read from the registry BY DIGEST (resolvePublishedPlatforms: the index's runnable
+// children, attestations skipped, each proven by its image config; or the single manifest's config). Every problem is
+// collected and refused at once (ImageBuildRecordError); nothing is written then. The output passes parseImageBuildRecord.
+
+
+import { writeOnce } from './customer-edition-verbs.mjs';
+import { keepsCurrentResolution } from './develop-current-resolution.mjs';
+import { DEVELOP_EDITION_STEPS, resolveDevelopSnapshot } from './develop-edition-resolve.mjs';
+import { developGraphMembers } from './develop-graph.mjs';
+import { developImageRef } from './develop-image-coordinate.mjs';
+import { createDevelopImageProbe } from './develop-image-probe.mjs';
+import { parseSelectionPins } from './develop-selection-pins.mjs';
+import { editionsRoot } from './edition-workspace.mjs';
+import { firstPartySources } from './first-party-source-ids.mjs';
+import { ImageBuildRecordError, parseImageBuildRecord, requireImageBuildRecordKernel, subjectKeyOf } from './images-from-record.mjs';
+import { loadKernelDistributionSchemas } from './lib.mjs';
+import { loadRegistryCredentialDeclarations, splitImageRef } from './registry-credentials.mjs';
+import { readStrictJsonFile } from './strict-json.mjs';
+import { compareStrings } from './string-order.mjs';
+import { registryClientsFor, resolvePublishedPlatforms } from './verify-image-platforms.mjs';
+
+const SELECTION_REQUIRED = Object.freeze(['pins', 'snapshot', 'images', 'behind']);
+const IMAGE_TEXT_KEYS = Object.freeze(['name', 'digest', 'contentHash', 'member']);
+const isPlainObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+
+/**
+ * A selection `select-records` wrote, checked strictly: its four sections are present and shaped, each image names its
+ * owning `member`, and `pins` and `currentResolution` pass the one selection-pins validation (40-hex pins, and
+ * `currentResolution` exactly what the graph members declare).
+ *
+ * @param {unknown} document
+ * @param {readonly {repo: string}[]} members the develop graph
+ * @param {string} source the file, named in the refusal
+ */
+export function parseSelection(document, members, source) {
+  if (!isPlainObject(document)) {throw new ImageBuildRecordError(`selection ${source} must be a JSON object`);}
+  const problems = SELECTION_REQUIRED.filter((key) => document[key] === undefined).map((key) => `has no "${key}"`);
+  for (const key of ['snapshot', 'behind']) {
+    if (document[key] !== undefined && !isPlainObject(document[key])) {problems.push(`"${key}" must be an object`);}
+  }
+  if (document.images !== undefined && !Array.isArray(document.images)) {problems.push('"images" must be an array');}
+  (Array.isArray(document.images) ? document.images : []).forEach((image, index) => {
+    for (const key of IMAGE_TEXT_KEYS) {
+      if (!isPlainObject(image) || typeof image[key] !== 'string') {problems.push(`images[${index}].${key} must be a string`);}
+    }
+    if (isPlainObject(image) && image.members !== undefined && !Array.isArray(image.members)) {problems.push(`images[${index}].members must be an array`);}
+  });
+  if (problems.length > 0) {throw new ImageBuildRecordError(`selection ${source} is refused:\n  ${problems.join('\n  ')}`);}
+  parseSelectionPins(document, source, '--selection', members);
+  return document;
+}
+
+const platformOf = ({ platform }) => ({ os: platform.os, architecture: platform.architecture, ...(platform.variant === undefined ? {} : { variant: platform.variant }) });
+
+/** A cached reader of the platforms a develop image serves, read by digest through one registry client per authority. */
+export function createPlatformReader(clientFor) {
+  const cache = new Map();
+  return (repository, digest) => {
+    const key = `${repository}@${digest}`;
+    if (!cache.has(key)) {
+      const { authority, repository: path } = splitImageRef(repository);
+      cache.set(key, resolvePublishedPlatforms({ client: clientFor(authority), repository: path, digest, coordinate: key })
+        .then(({ platforms }) => platforms.map(platformOf)));
+    }
+    return cache.get(key);
+  };
+}
+
+/**
+ * @param {object} request
+ * @param {string} request.id the edition
+ * @param {object} request.pins the snapshot pins
+ * @param {object} request.selection a parsed selection
+ * @param {object} request.steps resolve steps (tests replace them)
+ * @param {Function} [request.resolveSnapshot] ({id, pins, steps}) => {inputs, lock}; replaced by tests
+ * @param {Function} request.createProbe ({distributionId}) => the develop image probe
+ * @param {(repository: string, digest: string) => Promise<object[]>} request.platformsOf
+ * @param {object} request.declaredSources `firstPartySources`
+ * @param {Function} [request.loadKernel] the kernel loader (tests replace it)
+ * @returns {Promise<{schemaVersion: 1, images: object[], satellites: object[]}>}
+ */
+export async function buildImageRecord({ id, pins, selection, steps = DEVELOP_EDITION_STEPS, resolveSnapshot = resolveDevelopSnapshot, createProbe, platformsOf, declaredSources, loadKernel = loadKernelDistributionSchemas }) {
+  const kernel = requireImageBuildRecordKernel(await loadKernel());
+  const { inputs, lock } = await resolveSnapshot({ id, pins, steps });
+  const probe = createProbe({ distributionId: id });
+  const isFirstParty = (subject) => Object.hasOwn(declaredSources, subject.repo);
+  const { imageLock } = await steps.resolveImages(id, {
+    inputs,
+    lock,
+    onSubjectHashed: (subject) => {
+      if (isFirstParty(subject) && keepsCurrentResolution(declaredSources[subject.repo])) {probe.observe(subject);}
+    },
+  });
+  const probed = await probe.settle();
+  const problems = [];
+  const built = [];
+  const satellites = [];
+  for (const subject of imageLock.subjects.filter(isFirstParty)) {
+    const key = subjectKeyOf(subject);
+    const repository = developImageRef(subject.imageRef);
+    if (keepsCurrentResolution(declaredSources[subject.repo])) {
+      built.push({ subject: key, repository, contentHash: subject.contentHash, digest: probed.get(key), sourceSha: subject.sourceCommit });
+      continue;
+    }
+    const image = selection.images.find(({ name }) => name === repository);
+    if (image === undefined) {
+      problems.push(`${key} (${subject.repo}): the selection has no image ${repository}`);
+      continue;
+    }
+    if (image.member !== subject.repo) {
+      problems.push(`${key} (${subject.repo}): the selection's image ${repository} belongs to member ${image.member}, not ${subject.repo}`);
+      continue;
+    }
+    const selected = selection.pins[image.member];
+    if (selected !== subject.sourceCommit) {
+      problems.push(`${key} (${subject.repo}): the selection pins ${selected}, not ${subject.sourceCommit}, the commit the snapshot pins`);
+      continue;
+    }
+    // The subject's COMPUTED hash is the one recorded: the heads path's probe already finds dev/<image>:<computed hash>, so
+    // producer CI and this CLI agree on the hash, and a selected hash that differs is a real mismatch, never overwritten.
+    if (image.contentHash !== subject.contentHash) {
+      problems.push(`${key} (${subject.repo}): the selection's content hash ${image.contentHash} is not the computed ${subject.contentHash}`);
+      continue;
+    }
+    // A composed image's members[{service, key}] are the build record's own, copied unchanged and never recomputed; the kernel's
+    // ImageBuildRecord parse refuses them on any other entry.
+    satellites.push({ subject: key, repository, contentHash: subject.contentHash, digest: image.digest, sourceSha: selected, ...(image.members === undefined ? {} : { members: image.members }) });
+  }
+  const withPlatforms = async (entries) => {
+    const out = [];
+    for (const entry of entries) {
+      try {
+        out.push({ ...entry, platforms: await platformsOf(entry.repository, entry.digest) });
+      } catch (error) {
+        problems.push(`${entry.subject}: the platforms of ${entry.repository}@${entry.digest} could not be read: ${error.message}`);
+      }
+    }
+    return out.sort((a, b) => compareStrings(a.subject, b.subject));
+  };
+  const record = { schemaVersion: kernel.IMAGE_BUILD_RECORD_SCHEMA_VERSION, images: await withPlatforms(built), satellites: await withPlatforms(satellites) };
+  if (problems.length > 0) {
+    throw new ImageBuildRecordError(`the image build record of "${id}" cannot be written (${problems.length} problem(s)):\n  ${problems.join('\n  ')}`);
+  }
+  return parseImageBuildRecord(record, 'develop image-record', { loadKernel: async () => kernel });
+}
+
+/** The `image-record` verb. Writes `--out` once, only after every subject is covered. */
+export async function runImageRecord({
+  id,
+  options,
+  env = process.env,
+  steps = DEVELOP_EDITION_STEPS,
+  members = developGraphMembers(),
+  declaredSources = firstPartySources('enumerating the first-party image subjects'),
+  createProbe = (request) => createDevelopImageProbe({ ...request, env }),
+  resolveSnapshot,
+  clientFor,
+  write = writeOnce,
+}) {
+  const selection = parseSelection(readStrictJsonFile(options['--selection']), members, options['--selection']);
+  const declarations = clientFor === undefined ? loadRegistryCredentialDeclarations(editionsRoot()) : null;
+  const clients = new Map();
+  const registryClient = clientFor ?? ((authority) => {
+    if (!clients.has(authority)) {clients.set(authority, registryClientsFor([{ imageRef: `${authority}/x` }], { declarations, env }).get(authority));}
+    return clients.get(authority);
+  });
+  const record = await buildImageRecord({
+    id,
+    pins: readStrictJsonFile(options['--pins']),
+    selection,
+    steps,
+    ...(resolveSnapshot === undefined ? {} : { resolveSnapshot }),
+    createProbe,
+    platformsOf: createPlatformReader(registryClient),
+    declaredSources,
+  });
+  write(options['--out'], record);
+  return record;
+}

package/edition/develop-record-ancestry.mjs

@@ -9,9 +9,12 @@
 // With a published commit for the member, the records may not take it backwards: behind or equal keeps the published
 // commit (its own record must then exist), ahead selects the records' commit, otherwise the run is refused.
 //
+// The result also carries develop's head (`git rev-parse refs/heads/develop`) and `behind`, the commits the selected
+// one trails that head by (`git rev-list --count <selected>..refs/heads/develop`), both from the same fetch.
+//
 // Refusals (`RecordRefused`): a commit absent from the fetched develop history, two commits that are not
 // ancestor-related. Operational (plain Error): git cannot be spawned, a fetch fails, or merge-base answers
-// anything but 0 (ancestor) or 1 (not an ancestor).
+// anything but 0 (ancestor) or 1 (not an ancestor), or rev-parse or rev-list fails or answers a non-number.
 
 import { spawnSync } from 'node:child_process';
 import { mkdtempSync, rmSync } from 'node:fs';
@@ -72,7 +75,8 @@ export function defaultRunGit(args, { cwd, env }) {
  * @param {object} request.workspace the workspace config the source hold reads
  * @param {object} request.env
  * @param {Function} [request.runGit] (args, {cwd, env}) => {status, stdout, stderr}; replaced by tests
- * @returns {string} the selected commit
+ * @returns {{commit: string, head: string, behind: number}} the selected commit, develop's head in the same fetch, and
+ *   how many commits the selected one is behind that head (0 when it is the head)
  */
 export function newestCommitOnDevelop({ member, candidates, published, workspace, env, runGit = defaultRunGit }) {
   const byCommit = new Map();
@@ -109,10 +113,24 @@ export function newestCommitOnDevelop({ member, candidates, published, workspace
         if (!isAncestor(selected.commit, other.commit)) {throw new IncomparableRecordCommitsError(member.repo, selected, other);}
         selected = other;
       }
-      if (published === undefined) {return selected.commit;}
+      // develop's head and the chosen commit's distance from it, read in the same scratch the choice was made in
+      const withDistance = (commit) => {
+        const headResult = git(['rev-parse', DEVELOP_REF]);
+        const head = headResult.stdout.trim();
+        if (headResult.status !== 0 || !/^[0-9a-f]{40}$/.test(head)) {
+          throw new Error(`select-records: ${member.repo}: git rev-parse ${DEVELOP_REF} failed (exit ${headResult.status}): ${headResult.stderr.trim() || head}`);
+        }
+        const counted = git(['rev-list', '--count', `${commit}..${DEVELOP_REF}`]);
+        const behind = Number(counted.stdout.trim());
+        if (counted.status !== 0 || !/^\d+$/.test(counted.stdout.trim())) {
+          throw new Error(`select-records: ${member.repo}: git rev-list --count ${commit}..${DEVELOP_REF} failed (exit ${counted.status}): ${counted.stderr.trim() || counted.stdout.trim()}`);
+        }
+        return { commit, head, behind };
+      };
+      if (published === undefined) {return withDistance(selected.commit);}
       assertOnDevelop(published, ['published pin']);
-      if (isAncestor(selected.commit, published)) {return published;} // equal, or the records are behind it
-      if (isAncestor(published, selected.commit)) {return selected.commit;}
+      if (isAncestor(selected.commit, published)) {return withDistance(published);} // equal, or the records are behind it
+      if (isAncestor(published, selected.commit)) {return withDistance(selected.commit);}
       throw new DivergedFromPublishedError(member.repo, selected.commit, published);
     });
   } finally {

package/edition/develop-select-records.mjs

@@ -13,6 +13,15 @@
 // when the records are not ahead of it, and a diverged one is refused; without it the rule applies among the
 // records only (part 07 passes the flag).
 //
+// The output also carries `behind: { <repo>: { head, commits } }`: develop's head and how many commits the selected
+// commit trails it by, from the same fetch (0 when the record is the head). The verb prints one line per member, in
+// repo order, after writing --out, formatted by develop-selection-line.mjs (`<short name>: record <commit>, <N> commits behind HEAD`,
+// always `commits`, never singular; short name = the repo's last path segment, unambiguous across members).
+//
+// A member that declares a currentResolution (develop-current-resolution.mjs) is skipped, its registry never read; the
+// selection lists it as `currentResolution: { <repo>: <ticket> }` and the verb prints `<short name>: current resolution
+// (leaves the edition, <ticket>)` in its place. Every other member without a record still refuses.
+//
 // Every failure is a hard refusal naming the repository, and nothing is written. Two classes: `RecordRefused`
 // (the record is missing, or cosign or the record itself says no) and a plain Error (the registry or cosign
 // could not answer), which the operator retries rather than reads.
@@ -22,6 +31,7 @@
 // backwards. This verb checks nothing against current pins.
 
 import { writeOnce } from './customer-edition-verbs.mjs';
+import { currentResolutionOf, keepsCurrentResolution } from './develop-current-resolution.mjs';
 import { developGraphMembers } from './develop-graph.mjs';
 import { PublishedRecordMissingError, newestCommitOnDevelop } from './develop-record-ancestry.mjs';
 import {
@@ -32,10 +42,11 @@ import {
   requireBuildRecordKernel,
   withRecordVerifier,
 } from './develop-record-verify.mjs';
+import { assertShortNamesUnambiguous, formatSelectionLine } from './develop-selection-line.mjs';
+import { readSelectionPins } from './develop-selection-pins.mjs';
 import { editionWorkspaceConfig } from './edition-config.mjs';
 import { compareStrings } from './lib.mjs';
 import { RecordRefused } from './record-refused.mjs';
-import { readStrictJsonFile } from './strict-json.mjs';
 
 // The record-verification names this verb's tests and callers read from here, owned by the shared core.
 export {
@@ -64,16 +75,19 @@ const ISO_UTC = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?Z$/;
  * @param {object} request.workspace the workspace config the source hold reads
  * @param {object} request.env
  * @param {Function} [request.runGit] replaced by tests
- * @returns {Promise<{pins: object, snapshot: object, images: object[]}>}
+ * @returns {Promise<{pins: object, snapshot: object, behind: object, images: object[], currentResolution: object}>}
  */
 export async function selectRecords({ branch, registry, at, members, dataRootRepositoryUrl, kernel, clientFor, runCosign, cosignEnvFor, trustedRootPath, publishedPins, workspace, env, runGit }) {
   requireBuildRecordKernel(kernel);
+  assertShortNamesUnambiguous(members);
   recordSignerOrigin({ branch, dataRootRepositoryUrl });
   if (at !== undefined && (!ISO_UTC.test(at) || Number.isNaN(Date.parse(at)))) {
     throw new Error(`--at must be an ISO-8601 UTC time (YYYY-MM-DDTHH:MM:SSZ); got ${JSON.stringify(at)}`);
   }
   const selected = [];
   for (const member of members) {
+    // the one declared exception (develop-current-resolution.mjs): no registry read, no record
+    if (keepsCurrentResolution(member)) {continue;}
     const { repository, authority, client, runs } = await listBuildRecordRuns({ kernel, clientFor, registry, member, branch });
     // EVERY candidate is read and verified; any that fails refuses the run. None is skipped.
     const verified = [];
@@ -87,7 +101,7 @@ export async function selectRecords({ branch, registry, at, members, dataRootRep
     const eligible = at === undefined ? verified : verified.filter(({ record }) => Date.parse(record.completedAt) <= Date.parse(at));
     if (eligible.length === 0) {throw new RecordRefused(member.repo, `no build record for branch ${branch} completed at or before ${at}`);}
     const published = publishedPins?.[member.repo];
-    const commit = newestCommitOnDevelop({
+    const { commit, head, behind } = newestCommitOnDevelop({
       member, candidates: eligible.map(({ record, tag }) => ({ commit: record.commit, tag })), published, workspace, env, runGit,
     });
     // records of one commit are re-runs of it: the highest run, then attempt
@@ -96,46 +110,36 @@ export async function selectRecords({ branch, registry, at, members, dataRootRep
     const ofCommit = ofCommitIn(eligible).length > 0 ? ofCommitIn(eligible) : ofCommitIn(verified);
     if (ofCommit.length === 0) {throw new PublishedRecordMissingError(member.repo, commit);}
     const chosen = ofCommit[0];
-    selected.push({ member, ...chosen });
+    selected.push({ member, head, behind, ...chosen });
   }
-  return composeSelection(selected);
+  return { ...composeSelection(selected), currentResolution: currentResolutionOf(members) };
 }
 
 /** The snapshot a selection writes. A name built by two records is refused: an image has one builder. */
 export function composeSelection(selected) {
   const pins = {};
   const snapshot = {};
+  const behind = {};
   const owners = new Map();
   const images = [];
-  for (const { member, record, snapshot: run } of selected) {
+  for (const { member, record, snapshot: run, head, behind: commits } of selected) {
     pins[member.repo] = record.commit;
+    behind[member.repo] = { head, commits };
     snapshot[member.repo] = run;
     for (const image of record.images) {
       if (owners.has(image.name)) {
         throw new RecordRefused(member.repo, `image ${image.name} is also built by ${owners.get(image.name)}; an image has one builder`);
       }
       owners.set(image.name, member.repo);
-      images.push({ name: image.name, digest: image.digest, contentHash: image.contentHash });
+      images.push({ name: image.name, digest: image.digest, contentHash: image.contentHash, member: member.repo, ...(image.members === undefined ? {} : { members: image.members }) });
     }
   }
   const sorted = (object) => Object.fromEntries(Object.entries(object).sort(([a], [b]) => compareStrings(a, b)));
-  return { pins: sorted(pins), snapshot: sorted(snapshot), images: images.sort((a, b) => compareStrings(a.name, b.name)) };
+  return { pins: sorted(pins), snapshot: sorted(snapshot), behind: sorted(behind), images: images.sort((a, b) => compareStrings(a.name, b.name)) };
 }
 
 /** The `pins` of a file this verb wrote: member repo -> 40-hex commit. Nothing else of the file is read. */
-export function readPublishedPins(path) {
-  const document = readStrictJsonFile(path);
-  const { pins } = document ?? {};
-  if (pins === null || typeof pins !== 'object' || Array.isArray(pins)) {
-    throw new Error(`--published-pins ${path} has no "pins" object`);
-  }
-  for (const [repo, commit] of Object.entries(pins)) {
-    if (typeof commit !== 'string' || !/^[0-9a-f]{40}$/.test(commit)) {
-      throw new Error(`--published-pins ${path}: pin ${JSON.stringify(repo)} is not a 40-hex commit: ${JSON.stringify(commit)}`);
-    }
-  }
-  return pins;
-}
+export const readPublishedPins = (path) => readSelectionPins(path, '--published-pins');
 
 /** The `select-records` verb. Writes `--out` once, only after every member was selected. */
 export async function runSelectRecords({
@@ -144,6 +148,7 @@ export async function runSelectRecords({
   members = developGraphMembers(),
   runGit,
   write = writeOnce,
+  print = (text) => process.stdout.write(text),
   ...verifierInjections
 }) {
   return withRecordVerifier({ cosignBinary: options['--cosign'], env, ...verifierInjections }, async (verifier) => {
@@ -159,6 +164,9 @@ export async function runSelectRecords({
       runGit,
     });
     write(options['--out'], selection);
+    for (const member of members) {
+      print(`${formatSelectionLine(member, selection)}\n`);
+    }
     return selection;
   });
 }

package/edition/develop-selection-line.mjs

@@ -0,0 +1,30 @@
+// develop-selection-line — the one stdout line `select-records` prints per member, and the check that lines are unambiguous.
+//
+//   <short name>: record <40-hex commit>, <N> commits behind HEAD
+//   <short name>: current resolution (leaves the edition, <ticket>)
+//
+// The short name is the repo handle's last path segment. The develop-edition workflow in xema-distributions
+// (develop-edition.yaml) parses these lines with the same pattern; change both together.
+
+import { keepsCurrentResolution } from './develop-current-resolution.mjs';
+
+export const shortNameOf = (repo) => repo.split('/').at(-1);
+
+/** One graph member's line (no newline): its current-resolution line, or its record, commit and distance from develop HEAD. */
+export function formatSelectionLine(member, selection) {
+  const { repo } = member;
+  if (keepsCurrentResolution(member)) {
+    return `${shortNameOf(repo)}: current resolution (leaves the edition, ${member.currentResolution})`;
+  }
+  return `${shortNameOf(repo)}: record ${selection.pins[repo]}, ${selection.behind[repo].commits} commits behind HEAD`;
+}
+
+/** Two members with one short name would print indistinguishable lines: refused by name. */
+export function assertShortNamesUnambiguous(members) {
+  const seen = new Map();
+  for (const { repo } of members) {
+    const name = shortNameOf(repo);
+    if (seen.has(name)) {throw new Error(`select-records: members ${seen.get(name)} and ${repo} share the short name "${name}"; the printed lines would be ambiguous`);}
+    seen.set(name, repo);
+  }
+}

package/edition/develop-selection-pins.mjs

@@ -0,0 +1,30 @@
+// develop-selection-pins — the `pins` of a file `select-records` wrote: member repo -> 40-hex commit. Nothing else of
+// the file is read here. `flag` names the option the file came in on (--published-pins, --member-pins), for the refusal.
+
+import { currentResolutionProblem } from './develop-current-resolution.mjs';
+import { readStrictJsonFile } from './strict-json.mjs';
+
+/**
+ * @param {readonly {repo: string}[]} [members] when given, the file's `currentResolution` must also be exactly
+ *   what these graph members declare (develop-current-resolution.mjs)
+ * @returns {Record<string, string>} the file's `pins`, each a 40-hex commit
+ */
+export const readSelectionPins = (path, flag, members) => parseSelectionPins(readStrictJsonFile(path), path, flag, members);
+
+/** The same over a document already read: the ONE validation of a selection's `pins` (and `currentResolution`). */
+export function parseSelectionPins(document, path, flag, members) {
+  const { pins } = document ?? {};
+  if (pins === null || typeof pins !== 'object' || Array.isArray(pins)) {
+    throw new Error(`${flag} ${path} has no "pins" object`);
+  }
+  for (const [repo, commit] of Object.entries(pins)) {
+    if (typeof commit !== 'string' || !/^[0-9a-f]{40}$/.test(commit)) {
+      throw new Error(`${flag} ${path}: pin ${JSON.stringify(repo)} is not a 40-hex commit: ${JSON.stringify(commit)}`);
+    }
+  }
+  if (members !== undefined) {
+    const problem = currentResolutionProblem(document.currentResolution, members);
+    if (problem !== null) {throw new Error(`${flag} ${path}: ${problem}`);}
+  }
+  return pins;
+}

package/edition/dist-check.mjs

@@ -50,6 +50,7 @@ import { assertKernelEditionProtocol } from './edition-protocol.mjs';
 import { describeEditionHolds } from './edition-source-pins.mjs';
 import { WorkspaceRoot, biomeIndexPath, configureEditionWorkspaceFromProcess, dataRoot, editionsRoot, isEntryModule, kernelPackageDir, platformServiceIndexPath, runtimeImageSourceIndexPath, workspaceArgv } from './edition-workspace.mjs';
 import { checkEvidenceTrustPolicy } from './evidence-trust-policy.mjs';
+import { imageSubjectIdentity } from './image-subject-identity.mjs';
 import {
   compareIndexEntries,
   comparableDistributionLock,
@@ -58,6 +59,7 @@ import {
   loadKernelDistributionSchemas,
   parseResolvedDistributionLock,
   serializeJson,
+  sha256Hex,
   validateImmutableBiomeIndex,
   validateImmutableDistributionLock,
   validateImmutableImageLock,
@@ -69,6 +71,8 @@ import {
   resolveDistributionDeclaredSources,
   resolveDistributionRequiredPlatforms,
   externalSourceTrees,
+  carryComposedForwardStructurally,
+  readCommittedPreviousLock,
   resolveImages,
   resolveComposedProcessStructure,
   resolveImageStructure,
@@ -237,6 +241,24 @@ async function checkAuthorizationLock(id, kernel, index) {
  * with the same structure ship the same images and bundle the same web biomes,
  * regardless of current source content (which the build re-hashes anyway).
  */
+/**
+ * The committed lock with a stand-in `imageDigest` on every UNSEALED composed artifact, so the kernel can carry it forward.
+ * The kernel's v5 parse refuses two composed artifacts sharing one imageDigest, so each stand-in is unique to its subject:
+ * the sha256 of its identity (`imageSubjectIdentity`: `composed-process:<imageRef>:<contentHash>`, unique per lock).
+ * It equals a real manifest digest only by a sha256 preimage, and it never reaches a verdict: both sides of every
+ * comparison drop `imageDigest` (`withoutSealedDigests`).
+ */
+export function withStandInDigests(lock, schemas) {
+  return {
+    ...lock,
+    subjects: lock.subjects.map((subject) =>
+      subject.kind === schemas.RuntimeImageSubjectKind.ComposedProcess && subject.imageDigest === undefined
+        ? { ...subject, imageDigest: `sha256:${sha256Hex(imageSubjectIdentity(subject))}` }
+        : subject,
+    ),
+  };
+}
+
 function imageStructure(lock) {
   return serializeJson({
     distributionId: lock.distributionId,
@@ -315,12 +337,6 @@ export async function checkImagesLock(id, checkSourceEvidence) {
       schemas,
       requiredPlatforms,
     );
-    const fresh = {
-      distributionId: id,
-      contractAuthority: runtimeSourceIndex.contractAuthority,
-      ...structure,
-      subjects: structureSubjects(structure),
-    };
     if (!existsSync(imageLockPath)) {
       console.error(
         `[dist:check] ${id}: images.lock.json is missing. Run \`${commandFor('resolve-images.mjs', id)}\`.`,
@@ -328,9 +344,29 @@ export async function checkImagesLock(id, checkSourceEvidence) {
       return false;
     }
     const committed = validateImmutableImageLock(
-      schemas.parseImageLock(JSON.parse(readFileSync(imageLockPath, 'utf8'))),
+      (await readCommittedPreviousLock(id, imageLockPath)),
       schemas,
     );
+    // The committed lock is the previous lock of the fresh resolve, so the fresh view carries the composed artifacts forward
+    // exactly as a reseal does (generation, member keys, one artifact per live generation). Its digests are compared away
+    // below, so a committed lock that predates sealing is given one stand-in digest per subject to be carried.
+    const previousLock = withStandInDigests(committed, schemas);
+    let freshSubjects;
+    try {
+      freshSubjects = carryComposedForwardStructurally({ subjects: structureSubjects(structure), previousLock, schemas });
+    } catch (error) {
+      console.error(
+        `[dist:check] ${id}: images.lock.json is structurally out of date (its composed artifacts do not cover the declared composed processes: ${error.message}). ` +
+          `Run \`${commandFor('resolve-images.mjs', id)}\`.`,
+      );
+      return false;
+    }
+    const fresh = {
+      distributionId: id,
+      contractAuthority: runtimeSourceIndex.contractAuthority,
+      ...structure,
+      subjects: freshSubjects,
+    };
     if (
       serializeJson(committed.contractAuthority) !==
       serializeJson(runtimeSourceIndex.contractAuthority)
@@ -350,12 +386,12 @@ export async function checkImagesLock(id, checkSourceEvidence) {
       return false;
     }
     if (checkSourceEvidence) {
-      const { imageLock: sourceResolved } = await resolveImages(id);
+      const { imageLock: sourceResolved } = await resolveImages(id, { previousLock });
       // The same subtraction as the structural view above: the source resolve
       // carries no digest, and the committed lock may.
       if (
         normalize(withoutSealedDigests(committed)) !==
-        normalize(sourceResolved)
+        normalize(withoutSealedDigests(sourceResolved))
       ) {
         console.error(
           `[dist:check] ${id}: images.lock.json source content hashes are out of date. ` +

package/edition/distribution-evidence-set.mjs

@@ -56,6 +56,7 @@ import {
   sha256Digest,
   sourceIdentity,
 } from './image-evidence.mjs';
+import { completenessImageKey } from './image-subject-identity.mjs';
 import { assertKernelContractAuthorityEqual } from './kernel-contract-authority.mjs';
 import { compareStrings } from './lib.mjs';
 import { readBoundedNoFollowFile } from './no-follow-file.mjs';
@@ -133,7 +134,7 @@ export { compareCompletenessImages as compareEvidenceSubjects };
  * Keyed by the same `kind\0id` identity `image-evidence.mjs` uses everywhere
  * else, so two subjects can never collide and one subject can never move.
  */
-function subjectStem(subject) {
+export function subjectStem(subject) {
   return createHash('sha256')
     .update(sourceIdentity(subject))
     .digest('hex');
@@ -315,10 +316,9 @@ function indexOneEvidenceDirectory({
       });
       continue;
     }
-    const subjectKey = sourceIdentity({
-      kind: entry.subjectKind,
-      id: entry.subjectId,
-    });
+    // Only named in a defect: the record is indexed by the statement's own source coordinate, which already
+    // tells the generations of a composed artifact apart (its sourceTreeHash).
+    const subjectKey = `${entry.subjectKind}:${entry.subjectId}`;
     const descriptor = entry.evidence;
     let statementBytes;
     let bundleBytes;
@@ -691,12 +691,17 @@ export function buildDistributionImagesStatement({
   // Refusing here as well means an incomplete set can never be SIGNED, rather
   // than being signed and rejected days later at a customer install.
   const expectedIdentities = imageLock.subjects
-    .map((subject) => sourceIdentity(subject))
+    .map((subject) =>
+      completenessImageKey({
+        subjectKind: subject.kind,
+        subjectId: subject.id,
+        imageRepository: subject.imageRef,
+        manifestDigest: subject.imageDigest,
+      }),
+    )
     .sort(compareStrings);
   const actualIdentities = images
-    .map((image) =>
-      sourceIdentity({ kind: image.subjectKind, id: image.subjectId }),
-    )
+    .map((image) => completenessImageKey(image))
     .sort(compareStrings);
   if (
     new Set(actualIdentities).size !== actualIdentities.length ||

package/edition/edition-image-seal.mjs

@@ -19,6 +19,7 @@ import { developImageRef } from './develop-image-coordinate.mjs';
 import { notBuiltYetError } from './develop-image-probe.mjs';
 import { EditionChannel } from './edition-channel.mjs';
 import { editionsRoot } from './edition-workspace.mjs';
+import { imageSubjectIdentity } from './image-subject-identity.mjs';
 import { validateImmutableImageLock, loadKernelDistributionSchemas, } from './lib.mjs';
 import { isNotPublishedYet, planDigestSeal } from './seal-image-digests.mjs';
 import { imageSubjectKey, pinnedManifestDigests, thirdPartyImagePins } from './third-party-image-pins.mjs';
@@ -86,7 +87,7 @@ export async function sealImageSubjects({
   const digests = new Map([...writes, ...unchanged].map(({ key, digest }) => [key, digest]));
   return channelSubjects.map((subject) => ({
     ...subject,
-    imageDigest: digests.get(`${subject.kind}:${subject.id}`),
+    imageDigest: digests.get(imageSubjectIdentity(subject)),
   }));
 }