@xemahq/xema 0.54.0 → 0.56.0

package/edition/resolve-images.mjs

@@ -33,7 +33,8 @@
 //     anyone comparing their outcomes needs to know which one they ran.
 
 import { execFileSync } from 'node:child_process';
-import { writeFileSync } from 'node:fs';
+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';
 
@@ -72,6 +73,7 @@ import {
 } from './lib.mjs';
 import { assertReleaseContent } from './release-channel-guard.mjs';
 import { composeEdition } from './resolve-distribution.mjs';
+import { readStrictJsonFile } from './strict-json.mjs';
 import { loadThirdPartySourcePins } from './third-party-source-pins.mjs';
 import {
   assertOciBundleSourceOrigin,
@@ -1031,6 +1033,18 @@ export class ComposedProcessInputsError extends Error {
  * 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) {
   const inputsPath = `${COMPOSED_PROCESS_IMAGE_PATH}/${COMPOSED_PROCESS_DECLARATION_FILE}`;
   const { dir } = locate(repo);
@@ -1053,11 +1067,12 @@ function composedProcessCarriage(structure, enums, repo, sourceCommit, locate) {
   const byBiome = new Map();
   for (const subject of structure.subjects) {
     if (subject.kind !== enums.RuntimeImageSubjectKind.Service || subject.repo !== repo) {continue;}
-    const { path: servicePath, componentKind } = subjectServiceSource(subject, sourceCommit, locate);
+    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: {} };
+        { biomeId: owner.biomeId, carried: [], uncarried: [], carriedWorkers: [], packageDirs: {}, imageClasses: {} };
       if (!carried.has(servicePath)) {
         row.uncarried.push(subject.id);
       } else if (componentKind === 'worker') {
@@ -1067,6 +1082,8 @@ function composedProcessCarriage(structure, enums, repo, sourceCommit, locate) {
         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);
     }
@@ -1140,6 +1157,78 @@ export function readComposedProcessDeclarations(
   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
@@ -1186,6 +1275,7 @@ export function withComposedProcessSubjects(
     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
@@ -1220,6 +1310,7 @@ export function withComposedProcessSubjects(
       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(
@@ -1295,6 +1386,7 @@ export function withComposedProcessSubjects(
     }
     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,
@@ -1307,6 +1399,7 @@ export function withComposedProcessSubjects(
       requiredPlatforms,
       owners: biomeOwners,
       members: memberRows,
+      imageClass,
     });
   }
   return {
@@ -1422,7 +1515,7 @@ function subjectServiceSource(subject, sourceCommit, locate = FIRST_PARTY_TREES)
   const toRepoRelative = (absolute) =>
     relative(repoDirectory, absolute).split(sep).join('/') || '.';
   if (subject.sourceManifestPath) {
-    return { path: toRepoRelative(join(base, subject.path)), componentKind: 'service' };
+    return { path: toRepoRelative(join(base, subject.path)), componentKind: 'service', imageClass: undefined };
   }
   const biomePath = toRepoRelative(join(base, subject.path));
   const manifestPath =
@@ -1461,6 +1554,7 @@ function subjectServiceSource(subject, sourceCommit, locate = FIRST_PARTY_TREES)
   }
   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
@@ -1485,6 +1579,7 @@ function subjectServiceSource(subject, sourceCommit, locate = FIRST_PARTY_TREES)
     }
     servicePath = component.artifact.path;
     componentKind = component.kind;
+    imageClass = component.imageClass;
   } else {
     if (legacyApis.length === 0) {
       throw new Error(
@@ -1502,7 +1597,7 @@ function subjectServiceSource(subject, sourceCommit, locate = FIRST_PARTY_TREES)
     }
     servicePath = api.path;
   }
-  return { path: toRepoRelative(join(base, subject.path, servicePath)), componentKind };
+  return { path: toRepoRelative(join(base, subject.path, servicePath)), componentKind, imageClass };
 }
 
 function assertSourceManifestParity(structure, commitByRepo, locate = FIRST_PARTY_TREES) {
@@ -1787,7 +1882,7 @@ export function supplementalSourcesFor(runtimeSourceIndex) {
  * 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 } = {}) {
+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');
@@ -1902,9 +1997,20 @@ export async function resolveImageRows(id, { inputs, lock, onSubjectHashed, reco
       subject;
     void ignoredSourceManifestPath;
     // With a build record the content hash and source commit are the record's, carried and never recomputed.
+    const isComposed = subject.kind === schemas.RuntimeImageSubjectKind.ComposedProcess;
     const hashed = recordedImages === undefined ? {
       ...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,
@@ -1929,6 +2035,20 @@ export async function resolveImageRows(id, { inputs, lock, onSubjectHashed, reco
   }
   // 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) {
@@ -1968,9 +2088,82 @@ export async function resolveImageRows(id, { inputs, lock, onSubjectHashed, reco
   };
 }
 
+export const PREVIOUS_SEAL_USAGE =
+  'exactly one of `--previous-lock <images.lock.json> --previous-lock-sha256 <hex>` (the caller takes the digest from the images.lock ' +
+  'layer of the latest signed, published edition of this distribution, under the per-edition concurrency group) or `--first-seal`';
+
+/**
+ * The previous seal an images-lock write carries composed artifacts forward from, as an EXPLICIT input: the previous lock
+ * with the sha256 of its bytes (taken by the caller from the signed, published edition's images.lock layer), or
+ * `--first-seal` (null: generation 1). Neither, 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) {
+    if (given.length > 0) {
+      throw new Error(`--first-seal and a previous lock (--previous-lock/--previous-lock-sha256) are both given; give ${PREVIOUS_SEAL_USAGE}`);
+    }
+    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 = readFileSync(previousLockPath);
+  const actual = createHash('sha256').update(bytes).digest('hex');
+  if (actual !== previousLockSha256) {
+    throw new Error(`--previous-lock ${previousLockPath} has sha256 ${actual}, not the given --previous-lock-sha256 ${previousLockSha256}`);
+  }
+  return parsePreviousLock(distributionId, readStrictJsonFile(previousLockPath), '--previous-lock');
+}
+
+/** 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 = (await loadKernelDistributionSchemas()).parseImageLock(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 } = {}) {
-  const { subjects, thirdPartySubjects, platformServiceBindings, webBiomes, contractAuthority, commits } = await resolveImageRows(id, { inputs, lock, onSubjectHashed, recordedImages });
+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();
   const imageLock = validateImmutableImageLock(
     schemas.parseImageLock({
@@ -1994,7 +2187,7 @@ export async function resolveImages(id, { inputs, lock, onSubjectHashed, recorde
  */
 export async function writeResolvedImages(
   id,
-  { trustedWriteV3 = false, log = true } = {},
+  { trustedWriteV3 = false, log = true, previousLockPath = undefined, previousLockSha256 = undefined, firstSeal = false, previousFromTarget = false } = {},
 ) {
   assertCanonicalDistributionId(id);
   if (!trustedWriteV3) {
@@ -2004,12 +2197,18 @@ export async function writeResolvedImages(
   }
   // The RELEASE lock is published-only: a develop edition resolves through
   // `develop-edition.mjs` and never reaches this writer.
-  const { imageLock, commits, thirdPartySubjects } = await resolveImages(id);
   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) {
@@ -2031,7 +2230,7 @@ async function main() {
   const trustedWriteV3 = process.argv.includes('--trusted-write-v3');
   if (!id) {
     throw new Error(
-      'usage: resolve-images.mjs <distribution-id> --trusted-write-v3',
+      `usage: resolve-images.mjs <distribution-id> --trusted-write-v3 (${PREVIOUS_SEAL_USAGE})`,
     );
   }
   // `--editions-root` (and its `=` spelling, plus the value that follows
@@ -2041,15 +2240,28 @@ async function main() {
   // 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 });
+  await writeResolvedImages(id, { trustedWriteV3, previousLockPath, previousLockSha256, firstSeal });
 }
 
 if (isEntryModule(import.meta.url)) {

package/edition/seal-image-digests.mjs

@@ -128,6 +128,7 @@ import {
   isNotFinalYet,
   readFleetImageLocks,
 } from './fleet-coordinate-finality.mjs';
+import { imageSubjectIdentity } from './image-subject-identity.mjs';
 import { adoptCatalogueKernel } from './kernel-package.mjs';
 import { loadKernelDistributionSchemas, serializeJson } from './lib.mjs';
 import { assertPlatformCanParseLock } from './platform-lock-readability.mjs';
@@ -239,12 +240,12 @@ export function planDigestSeal({ subjects, verified }) {
     );
   }
   const byId = new Map(
-    verified.map((entry) => [`${entry.subjectKind}:${entry.subjectId}`, entry]),
+    verified.map((entry) => [imageSubjectIdentity({ kind: entry.subjectKind, id: entry.subjectId, imageRef: entry.subjectImageRef, contentHash: entry.subjectContentHash }), entry]),
   );
   const writes = [];
   const unchanged = [];
   for (const subject of subjects) {
-    const key = `${subject.kind}:${subject.id}`;
+    const key = imageSubjectIdentity(subject);
     const entry = byId.get(key);
     if (!entry) {
       throw new Error(
@@ -346,7 +347,7 @@ export function classifyPublicationState({
   }
   const unsealed = subjects
     .filter((subject) => typeof subject.imageDigest !== 'string' || subject.imageDigest.length === 0)
-    .map((subject) => `${subject.kind}:${subject.id}`);
+    .map((subject) => imageSubjectIdentity(subject));
   if (unsealed.length === 0) {
     return {
       verdict: PublicationVerdict.Publishable,
@@ -485,18 +486,15 @@ export async function buildSealedEditionLock(options) {
   return prepared.result.lock;
 }
 
-/** The shared in-memory half of the seal: reads both locks, applies `digests`, seals or verifies. Writes nothing. */
-async function prepareEditionSeal({ distributionId, root, digests = new Map(), check = false, vendoredCommit, catalogue, catalogueDigest, storePublisherAnchorKeys, fetchManifest = fetchRegistryManifest, checkAdapters = true }) {
-  const schemas = await loadKernelDistributionSchemas();
-  const lockPath = join(root, distributionId, 'distribution.lock.json');
-  const imagesPath = join(root, distributionId, 'images.lock.json');
-  // The file is re-read rather than the PARSED lock re-serialised: the parse is a
-  // validation, not a round-trip, and writing back a schema-normalised document
-  // would silently reformat or drop anything the parser does not model.
-  const rawImages = JSON.parse(readFileSync(imagesPath, 'utf8'));
+/**
+ * Write each planned digest into the raw images lock's subject of the same identity (a composed artifact is its
+ * `imageRef:contentHash`, so two live generations take their own digests), and count them. A plan the file does not
+ * match, in either direction, is refused: nothing is written.
+ */
+export function applyDigestsToSubjects(rawImages, digests) {
   let applied = 0;
   for (const subject of rawImages.subjects) {
-    const digest = digests.get(`${subject.kind}:${subject.id}`);
+    const digest = digests.get(imageSubjectIdentity(subject));
     if (digest) {
       subject.imageDigest = digest;
       applied += 1;
@@ -508,6 +506,19 @@ async function prepareEditionSeal({ distributionId, root, digests = new Map(), c
         'in the file on disk; nothing written',
     );
   }
+  return applied;
+}
+
+/** The shared in-memory half of the seal: reads both locks, applies `digests`, seals or verifies. Writes nothing. */
+async function prepareEditionSeal({ distributionId, root, digests = new Map(), check = false, vendoredCommit, catalogue, catalogueDigest, storePublisherAnchorKeys, fetchManifest = fetchRegistryManifest, checkAdapters = true }) {
+  const schemas = await loadKernelDistributionSchemas();
+  const lockPath = join(root, distributionId, 'distribution.lock.json');
+  const imagesPath = join(root, distributionId, 'images.lock.json');
+  // The file is re-read rather than the PARSED lock re-serialised: the parse is a
+  // validation, not a round-trip, and writing back a schema-normalised document
+  // would silently reformat or drop anything the parser does not model.
+  const rawImages = JSON.parse(readFileSync(imagesPath, 'utf8'));
+  const applied = applyDigestsToSubjects(rawImages, digests);
   const raw = JSON.parse(readFileSync(lockPath, 'utf8'));
   const imageLock = schemas.parseImageLock(rawImages);
   // A release seal reads the EDITION's indexes and pins (a held repository is sealed at the held commit); a

package/edition/third-party-bundle-registry.mjs

@@ -4,7 +4,7 @@
 
 import { execFileSync } from 'node:child_process';
 
-import { certificateConstraintArgs } from './cosign-certificate-constraints.mjs';
+import { certificateConstraintArgs, certificateIdentityArgs } from './cosign-certificate-constraints.mjs';
 import { COSIGN_ENV, decodeExactUtf8, sha256Digest, validatePinnedTrustedRoot } from './image-evidence.mjs';
 import { splitImageRef } from './registry-credentials.mjs';
 import { BUNDLE_MEDIA_TYPE } from './sigstore-bundle-media-type.mjs';
@@ -119,29 +119,85 @@ export async function fetchBundleProvenance({ clientFor, ociRef }) {
   return found[0];
 }
 
-const tail = (error) => String(error?.stderr ?? error?.message ?? error).trim().split('\n').slice(-4).join(' | ').slice(0, 1024);
-
 /**
- * (a) against the registry: keyless `cosign verify` and `cosign verify-attestation --type slsaprovenance1` of the bundle
- * artifact under EXACTLY the signer row's identity and issuer, the row's workflow repository, ref and the stated
- * commit, the pinned trusted root and the trusted cosign binary. `--offline` verifies the tlog inclusion proof carried
- * with the signature; the tlog is never ignored. The registry credential is the operator's (HOME / DOCKER_CONFIG).
+ * The `<repository>@sha256:<hex>` a bundle reference names: a digest reference as it is, a tag reference resolved at
+ * the registry (the manifest the tag serves, its bytes verified against the digest the registry described).
  */
-export function verifyBundleOnRegistry({ trustedCosign, policy, policyRoot, row, workflowSha, ociRef, env = process.env }) {
+export async function bundleDigestRef({ clientFor, ociRef }) {
+  if (ociRef.includes('@')) {return ociRef;}
+  const colon = ociRef.lastIndexOf(':');
+  if (colon <= ociRef.lastIndexOf('/')) {
+    throw new Error(`bundle reference ${JSON.stringify(ociRef)} names neither a tag nor a digest`);
+  }
+  const name = ociRef.slice(0, colon);
+  const { authority, repository } = splitImageRef(name);
+  const { digest } = await clientFor(authority).getManifestByTag(repository, ociRef.slice(colon + 1));
+  return `${name}@${digest}`;
+}
+
+const tail = (error) => String(error?.stderr ?? error?.message ?? error).trim().split('\n').slice(-4).join(' | ').slice(0, 1024);
+
+/** The cosign run of a registry verification: the trusted binary, the operator's registry credential (HOME / DOCKER_CONFIG). */
+function registryCosign({ trustedCosign, policy, policyRoot, row, ociRef, env }) {
   const root = validatePinnedTrustedRoot(policyRoot, policy);
-  const common = ['--offline', '--trusted-root', root.path, ...certificateConstraintArgs(row, workflowSha)];
   const environment = {
     ...COSIGN_ENV,
     ...(env.HOME === undefined ? {} : { HOME: env.HOME }),
     ...(env.DOCKER_CONFIG === undefined ? {} : { DOCKER_CONFIG: env.DOCKER_CONFIG }),
   };
-  const run = (command, args) => {
-    try {
-      execFileSync(assertPreparedExecutable(trustedCosign, 'cosign'), [command, ...args], { env: environment, stdio: ['ignore', 'ignore', 'pipe'], timeout: REGISTRY_COSIGN_TIMEOUT_MS });
-    } catch (error) {
-      throw new Error(`cosign ${command} refused ${ociRef} under row "${row.policyId}": ${tail(error)}`);
-    }
+  return {
+    trustArgs: ['--offline', '--trusted-root', root.path],
+    run(command, args) {
+      try {
+        return execFileSync(assertPreparedExecutable(trustedCosign, 'cosign'), [command, ...args], {
+          env: environment,
+          encoding: 'utf8',
+          stdio: ['ignore', 'pipe', 'pipe'],
+          timeout: REGISTRY_COSIGN_TIMEOUT_MS,
+        });
+      } catch (error) {
+        throw new Error(`cosign ${command} refused ${ociRef} under row "${row.policyId}": ${tail(error)}`);
+      }
+    },
   };
-  run('verify', [...common, ociRef]);
-  run('verify-attestation', ['--type', COSIGN_SLSA_PROVENANCE_ALIAS, ...common, ociRef]);
+}
+
+/**
+ * (a) against the registry: keyless `cosign verify` and `cosign verify-attestation --type slsaprovenance1` of the bundle
+ * artifact under EXACTLY the signer row's identity and issuer, the row's workflow repository, ref and the stated
+ * commit, the pinned trusted root and the trusted cosign binary. `--offline` verifies the tlog inclusion proof carried
+ * with the signature; the tlog is never ignored. The registry credential is the operator's (HOME / DOCKER_CONFIG).
+ */
+export function verifyBundleOnRegistry({ trustedCosign, policy, policyRoot, row, workflowSha, ociRef, env = process.env }) {
+  const cosign = registryCosign({ trustedCosign, policy, policyRoot, row, ociRef, env });
+  const common = [...cosign.trustArgs, ...certificateConstraintArgs(row, workflowSha)];
+  cosign.run('verify', [...common, ociRef]);
+  cosign.run('verify-attestation', ['--type', COSIGN_SLSA_PROVENANCE_ALIAS, ...common, ociRef]);
+}
+
+const WORKFLOW_SHA = /^[0-9a-f]{40}$/u;
+
+/**
+ * The commit the row's workflow signed the bundle artifact at, as cosign states it: `cosign verify` under the row's
+ * identity, issuer, workflow repository and ref (no commit: it is what is asked), and the `githubWorkflowSha` claim of
+ * every signature cosign verified. Exactly one commit is required; none, or two, is refused. The caller then holds the
+ * signature AND the provenance to that commit with `verifyBundleOnRegistry`.
+ */
+export function verifiedBundleSignerCommit({ trustedCosign, policy, policyRoot, row, ociRef, env = process.env }) {
+  const cosign = registryCosign({ trustedCosign, policy, policyRoot, row, ociRef, env });
+  const output = cosign.run('verify', [...cosign.trustArgs, ...certificateIdentityArgs(row), '--output', 'json', ociRef]);
+  let verified;
+  try {
+    verified = JSON.parse(output);
+  } catch {
+    throw new Error(`cosign verify of ${ociRef} under row "${row.policyId}" printed no JSON list of verified signatures`);
+  }
+  const commits = [...new Set((Array.isArray(verified) ? verified : []).map((signature) => signature?.optional?.githubWorkflowSha))];
+  if (commits.length !== 1 || !WORKFLOW_SHA.test(String(commits[0]))) {
+    throw new Error(
+      `${ociRef} carries signatures by row "${row.policyId}" (${row.certificateIdentity}) stating ${commits.length} workflow commits ` +
+        `(${commits.map(String).join(', ')}); exactly one 40-hex commit is required`,
+    );
+  }
+  return commits[0];
 }