@xemahq/xema 0.53.0 → 0.55.0

package/edition/images-from-record.mjs

@@ -0,0 +1,298 @@
+// images-from-record — a develop resolve's image digests taken from a BUILD RECORD, with no registry probe and no rehash.
+//
+// The everyday job builds (or reuses by content-hash tag) the edition's images in the aggregator workspace and hands
+// `edition develop resolve --images-from <file>` the record of what it built. Each entry names one image subject of
+// the edition by the identity images.lock.json and the seal key it by (`<kind>:<id>`), and carries
+// `{repository, contentHash, digest, platforms, sourceSha}`:
+//
+//   images       what the job built or reused itself. Trusted as the job's own statement: the job signs the edition.
+//   satellites   a satellite producer's develop digest (a first-party source that is not built in the workspace, such
+//                as submodules/xema-host-web). Admitted only after a cosign verify that the producer's own develop
+//                ci.yaml build record, signed by the data root's record workflow called by that producer
+//                (develop-record-verify.mjs), lists exactly this repository, digest and content hash at sourceSha.
+//                The producer is the subject's declared `firstPartySources[repo].repositoryUrl`, never the record's.
+//
+// Which list an entry sits in is not the record's choice: each first-party source declares its `imageOrigin` once in
+// `firstPartySources` (FirstPartyImageOrigin: `workspace` -> `images`, `satellite` -> `satellites`). An entry in the
+// other list, or for a source that declares no origin, is refused, so no satellite is trusted without its verify.
+//
+// Coverage is exact: every first-party subject of the edition comes from exactly one entry, and every entry is a
+// subject of the edition. A missing, duplicated or extra subject, a sourceSha other than the commit the snapshot pins
+// for the subject's repository, a repository other than the subject's develop repository, or a platform set without
+// every required platform refuses the whole resolve, every refusal named at once. There is no fallback to the probe.
+// contentHash and sourceSha are carried into the images lock where the probe path writes them, never recomputed.
+// A third-party subject (a pinned OCI biome's image) is not built by the job: it keeps its pinned seal, and a record
+// entry naming one is an extra subject.
+//
+// The record schema is the kernel's (`ImageBuildRecordSchema` / `parseImageBuildRecord`, @xemahq/contracts, edition
+// protocol v41), loaded through the kernel loader; this module owns no parser of its own.
+
+import { canonicalJson } from './canonical-evidence-json.mjs';
+import { canonicalPublicHttpsRepositoryUrl, repositoryOwnerName } from './canonical-repository-url.mjs';
+import { RefusalError } from './collected-refusals.mjs';
+import { developImageRef } from './develop-image-coordinate.mjs';
+import { withRecordVerifier } from './develop-record-verify.mjs';
+import { findVerifiedProducerImageRecord } from './develop-verify-image-record.mjs';
+import { EditionChannel } from './edition-channel.mjs';
+import { sealImageSubjects } from './edition-image-seal.mjs';
+import { firstPartySources } from './first-party-source-ids.mjs';
+import { compareStrings, loadKernelDistributionSchemas, sha256Hex, validateImmutableImageLock } from './lib.mjs';
+import { RecordRefused } from './record-refused.mjs';
+import { readStrictJsonFile } from './strict-json.mjs';
+import { FirstPartyImageOrigin } from './workspace-sections.mjs';
+
+/** Which list of the record an entry came from: how far it is trusted. */
+export const RecordedImageOrigin = Object.freeze({
+  Built: 'images',
+  Satellite: 'satellites',
+});
+
+/** The one record list each declared image origin admits. */
+const LIST_OF_ORIGIN = Object.freeze({
+  [FirstPartyImageOrigin.Workspace]: RecordedImageOrigin.Built,
+  [FirstPartyImageOrigin.Satellite]: RecordedImageOrigin.Satellite,
+});
+
+/** A build record that is malformed, or does not cover the edition exactly. */
+export class ImageBuildRecordError extends RefusalError {
+  constructor(message) {
+    super(message);
+    this.name = 'ImageBuildRecordError';
+  }
+}
+
+/** The subject key the image lock, the probe and the seal use. */
+export const subjectKeyOf = (subject) => `${subject.kind}:${subject.id}`;
+
+const platformKey = (platform) => [platform.os, platform.architecture, platform.variant ?? ''].join('/');
+
+/** The kernel's image-build-record exports, refused as a set when any is absent (a kernel before edition protocol v41). */
+export function requireImageBuildRecordKernel(schemas) {
+  const names = ['ImageBuildRecordSchema', 'parseImageBuildRecord', 'IMAGE_BUILD_RECORD_SCHEMA_VERSION'];
+  const missing = names.filter((name) => schemas?.[name] === undefined);
+  if (missing.length > 0) {
+    throw new ImageBuildRecordError(`the kernel's distribution module does not export ${missing.join(', ')}; the image build record needs a kernel at edition protocol v41 or newer`);
+  }
+  return schemas;
+}
+
+/**
+ * Parse an image build record with the kernel's own parser (`parseImageBuildRecord`, the ONE contract: both the writer
+ * `develop image-record` and this reader go through it): `{schemaVersion: 1, images: [entry], satellites: [entry]}`, every
+ * list sorted by subject, no subject twice, no unknown key. A refusal is an `ImageBuildRecordError` carrying the kernel's message.
+ *
+ * @param {unknown} document
+ * @param {string} source where the record came from (named in the refusal)
+ * @param {{loadKernel?: () => Promise<object>}} [injections] tests replace the kernel loader
+ */
+export async function parseImageBuildRecord(document, source, { loadKernel = loadKernelDistributionSchemas } = {}) {
+  const kernel = requireImageBuildRecordKernel(await loadKernel());
+  try {
+    return kernel.parseImageBuildRecord(document);
+  } catch (error) {
+    throw new ImageBuildRecordError(`image build record ${source} is refused: ${error.message}`);
+  }
+}
+
+/**
+ * sha256 (hex) of the parsed record's canonical JSON (canonical-evidence-json.mjs: keys sorted), every list in its
+ * canonical order: entries by subject (parse enforces it) and each entry's platforms by os/architecture/variant. It is
+ * the `imageBuildRecord` input of the develop edition's target tag (snapshotEditionTag).
+ */
+export function imageBuildRecordDigest(record) {
+  const canonicalEntry = (entry) => ({ ...entry, platforms: [...entry.platforms].sort((a, b) => compareStrings(platformKey(a), platformKey(b))) });
+  return sha256Hex(canonicalJson({
+    schemaVersion: record.schemaVersion,
+    ...Object.fromEntries(Object.values(RecordedImageOrigin).map((origin) => [origin, record[origin].map(canonicalEntry)])),
+  }));
+}
+
+/** Read and parse the record file `--images-from` names (duplicate JSON keys refused). */
+export async function readImageBuildRecord(path) {
+  return parseImageBuildRecord(readStrictJsonFile(path), path);
+}
+
+/**
+ * The record as `resolveImages` consumes it (`recordedImages`): `take` gives each first-party subject its recorded
+ * content hash and source commit, and `settle` refuses, all at once, every subject the record does not cover exactly.
+ *
+ * Each subject's entry must sit in the list its source's declared `imageOrigin` names (LIST_OF_ORIGIN); an entry in the
+ * other list, or a source with no declared origin, is one more problem `settle` names.
+ *
+ * @param {{images: object[], satellites: object[]}} record a parsed record
+ * @param {{distributionId: string, declaredSources?: object}} context `declaredSources` is `firstPartySources` (tests pass it)
+ */
+export function createRecordedImages(record, { distributionId, declaredSources = firstPartySources('checking each build record entry against its source\'s declared image origin') }) {
+  const entries = new Map();
+  for (const origin of Object.values(RecordedImageOrigin)) {
+    for (const entry of record[origin]) {entries.set(entry.subject, { origin, entry });}
+  }
+  const taken = new Map();
+  const problems = [];
+  let settled = false;
+
+  return {
+    take(subject) {
+      const key = subjectKeyOf(subject);
+      const recorded = entries.get(key);
+      if (recorded === undefined) {
+        problems.push(`${key} (${subject.repo}@${subject.sourceCommit}) is not in the record`);
+        return { sourceCommit: subject.sourceCommit, contentHash: null };
+      }
+      if (taken.has(key)) {throw new Error(`images-from-record: subject ${key} was taken twice`);}
+      const { entry, origin } = recorded;
+      const listProblem = recordListProblem(key, subject, origin, declaredSources);
+      if (listProblem !== null) {problems.push(listProblem);}
+      if (entry.sourceSha !== subject.sourceCommit) {
+        problems.push(`${key}: the record's sourceSha ${entry.sourceSha} is not ${subject.sourceCommit}, the commit the snapshot pins for ${subject.repo}`);
+      }
+      const repository = developImageRef(subject.imageRef);
+      if (entry.repository !== repository) {
+        problems.push(`${key}: the record's repository ${entry.repository} is not its develop repository ${repository}`);
+      }
+      const recordedPlatforms = new Set(entry.platforms.map(platformKey));
+      const absent = subject.requiredPlatforms.map(platformKey).filter((platform) => !recordedPlatforms.has(platform));
+      if (absent.length > 0) {problems.push(`${key}: the record's platforms lack the required ${absent.join(', ')}`);}
+      taken.set(key, { subject, ...recorded });
+      return { sourceCommit: entry.sourceSha, contentHash: entry.contentHash, ...recordedMembers(key, subject, entry, problems) };
+    },
+    settle() {
+      settled = true;
+      const extra = [...entries.keys()].filter((key) => !taken.has(key)).map((key) => `${key} (record.${entries.get(key).origin}) is not a first-party image subject of "${distributionId}"`);
+      const all = [...problems, ...extra];
+      if (all.length > 0) {
+        throw new ImageBuildRecordError(`the image build record does not cover "${distributionId}" exactly (${all.length} problem(s); no probe fallback):\n  ${all.join('\n  ')}`);
+      }
+    },
+    /** The satellite entries taken, each with the subject it covers, for the cosign verify. */
+    satelliteClaims() {
+      if (!settled) {throw new Error('images-from-record: satellite claims are read only after settle()');}
+      return [...taken.values()].filter(({ origin }) => origin === RecordedImageOrigin.Satellite).map(({ subject, entry }) => ({ subject, entry }));
+    },
+    /** The recorded entry of a subject, or undefined for a subject the record does not cover (a third-party one). */
+    entryOf(subject) {
+      return taken.get(subjectKeyOf(subject))?.entry;
+    },
+  };
+}
+
+/**
+ * A composed subject's members with the keys its record entry carries (`members[{service, key}]`), never computed here.
+ * An entry without members, or whose services are not the subject's members, is a problem named once; a subject that is
+ * not composed gives nothing.
+ */
+function recordedMembers(key, subject, entry, problems) {
+  if (subject.members === undefined) {return {};}
+  if (entry.members === undefined) {
+    problems.push(`${key}: the record's composed entry carries no members[{service, key}]`);
+    return {};
+  }
+  const keyOf = new Map(entry.members.map((member) => [member.service, member.key]));
+  const wanted = subject.members.map((member) => member.service);
+  const absent = wanted.filter((service) => !keyOf.has(service));
+  const extra = [...keyOf.keys()].filter((service) => !wanted.includes(service));
+  if (absent.length > 0 || extra.length > 0) {
+    problems.push(`${key}: the record's members differ from the subject's${absent.length > 0 ? ` (no key for ${absent.join(', ')})` : ''}${extra.length > 0 ? ` (not members: ${extra.join(', ')})` : ''}`);
+    return {};
+  }
+  return { members: subject.members.map((member) => ({ ...member, key: keyOf.get(member.service) })) };
+}
+
+/** Why the record list `origin` may not carry the subject's entry, or null when its source's declared origin names it. */
+function recordListProblem(key, subject, origin, declaredSources) {
+  if (!Object.hasOwn(declaredSources, subject.repo)) {
+    return `${key} (record.${origin}): ${subject.repo} is not a declared first-party source`;
+  }
+  const declared = declaredSources[subject.repo].imageOrigin;
+  if (declared === undefined) {
+    return `${key} (record.${origin}): firstPartySources["${subject.repo}"] declares no imageOrigin (one of ${Object.values(FirstPartyImageOrigin).join(', ')}); --images-from admits no entry of an unconfigured source`;
+  }
+  const wanted = LIST_OF_ORIGIN[declared];
+  if (origin !== wanted) {
+    return `${key} is in record.${origin}, but firstPartySources["${subject.repo}"].imageOrigin is "${declared}": its entry belongs in record.${wanted}`;
+  }
+  return null;
+}
+
+/** The `owner/name` a satellite subject's develop identity is bound to: its repository's declared URL. */
+export function satelliteProducerOf(subject) {
+  const sources = firstPartySources('naming a satellite producer');
+  if (!Object.hasOwn(sources, subject.repo)) {
+    throw new ImageBuildRecordError(`${subjectKeyOf(subject)}: ${subject.repo} is not a declared first-party source; a satellite producer is never named by the record`);
+  }
+  const context = `firstPartySources["${subject.repo}"].repositoryUrl`;
+  return repositoryOwnerName(canonicalPublicHttpsRepositoryUrl(sources[subject.repo].repositoryUrl, context), context);
+}
+
+/**
+ * The cosign verifier of satellite claims: for each, the producer's newest verified develop ci.yaml build record
+ * (develop-record-verify.mjs: keyless, offline against the pinned trusted root, issuer
+ * https://token.actions.githubusercontent.com, identity the data root's record workflow at refs/heads/develop, called by
+ * the producer) whose commit is the claim's sourceSha and which lists its repository, digest and content hash. Every
+ * refused claim is named at once; a registry or cosign that could not answer is a plain Error. The registry is read
+ * for the records and signatures only: no digest is discovered and nothing is rehashed.
+ *
+ * @param {object} request
+ * @param {string} request.registry the registry root that holds `build-records/<repo>`
+ * @param {string} request.cosignBinary absolute path of cosign
+ * @param {Function} [request.withVerifier] the pinned record verifier scope (tests replace it, to run offline)
+ * @param {Function} [request.findRecord] the newest-first verified record walk (tests replace it)
+ * @returns {(claims: {subject: object, entry: object}[]) => Promise<void>}
+ */
+export function createSatelliteVerifier({ registry, cosignBinary, env = process.env, withVerifier = withRecordVerifier, findRecord = findVerifiedProducerImageRecord, ...verifierInjections }) {
+  return async (claims) => {
+    if (claims.length === 0) {return;}
+    await withVerifier({ cosignBinary, env, ...verifierInjections }, async (verifier) => {
+      const refused = [];
+      for (const { subject, entry } of claims) {
+        try {
+          await findRecord({
+            ...verifier,
+            registry,
+            producer: satelliteProducerOf(subject),
+            wanted: `at ${entry.sourceSha} lists ${entry.repository}@${entry.digest} with content hash ${entry.contentHash}`,
+            matches: (record) =>
+              record.commit === entry.sourceSha &&
+              record.images.some((listed) => listed.name === entry.repository && listed.digest === entry.digest && listed.contentHash === entry.contentHash),
+          });
+        } catch (error) {
+          if (!(error instanceof RecordRefused)) {throw error;}
+          refused.push(`${subjectKeyOf(subject)}: ${error.message}`);
+        }
+      }
+      if (refused.length > 0) {
+        throw new ImageBuildRecordError(`${refused.length} satellite image(s) of the build record are not verified:\n  ${refused.join('\n  ')}`);
+      }
+    });
+  };
+}
+
+/**
+ * The develop images lock of a snapshot from the record: the subjects as `resolveImages` structures them, each
+ * first-party one with the record's content hash and source commit, coverage settled, satellites verified.
+ *
+ * @returns {Promise<{imageLock: object, recorded: ReturnType<typeof createRecordedImages>}>}
+ */
+export async function resolveImagesFromRecord({ id, inputs, lock, record, resolveImages, verifySatellites, previousLock = null }) {
+  const recorded = createRecordedImages(record, { distributionId: id });
+  const { imageLock } = await resolveImages(id, { inputs, lock, recordedImages: recorded, previousLock });
+  await verifySatellites(recorded.satelliteClaims());
+  return { imageLock, recorded };
+}
+
+/**
+ * Seal the lock from the record: each recorded subject takes the record's develop repository and digest, with no
+ * registry read. A third-party subject (the only kind the record does not cover) keeps its pinned seal.
+ */
+export async function sealImagesFromRecord({ imageLock, recorded, thirdPartyPins, ...sealOptions }) {
+  const unrecorded = imageLock.subjects.filter((subject) => recorded.entryOf(subject) === undefined);
+  const pinned = unrecorded.length === 0 ? [] : await sealImageSubjects({ channel: EditionChannel.Develop, distributionId: imageLock.distributionId, subjects: unrecorded, thirdPartyPins, ...sealOptions });
+  const pinnedByKey = new Map(pinned.map((subject) => [subjectKeyOf(subject), subject]));
+  const subjects = imageLock.subjects.map((subject) => {
+    const entry = recorded.entryOf(subject);
+    if (entry === undefined) {return pinnedByKey.get(subjectKeyOf(subject));}
+    return { ...subject, imageRef: entry.repository, imageDigest: entry.digest };
+  });
+  const schemas = await loadKernelDistributionSchemas();
+  return validateImmutableImageLock(schemas.parseImageLock({ ...imageLock, subjects }), schemas);
+}

package/edition/lib.mjs

@@ -36,6 +36,7 @@ import {
 } from './edition-workspace.mjs';
 import { SHA256_HEX_PATTERN } from './evidence-grammars.mjs';
 import { readGitJsonAtCommit } from './git-json.mjs';
+import { imageSubjectIdentity } from './image-subject-identity.mjs';
 import { isKernelCapabilityDomain } from './kernel-capability-domain.mjs';
 import {
   PRINCIPAL_PRIVILEGE_FIELDS,
@@ -719,23 +720,6 @@ export function assertKernelSealsComposedMembership(schemas, subjects, label) {
   );
 }
 
-/**
- * The READ side of the same rule, for a kernel before image-lock
- * schemaVersion 4 (no `ImageLockSchemaVersion`): it reads only schemaVersion
- * 3, which names no composed members, so a v3 lock carrying a composed-process
- * subject cannot say which services run from it and is refused (worded as the
- * kernel's own `LegacyComposedImageLockError`).
- */
-export function assertLegacyLockHasNoComposedSubject(lock) {
-  const composed = (lock.subjects ?? []).find((subject) => subject.kind === 'composed-process');
-  if (composed === undefined) {return;}
-  throw new ComposedProcessNeedsLockV4Error(
-    `distribution "${lock.distributionId}": subjects "${composed.id}" is a schemaVersion ` +
-      `${String(lock.schemaVersion)} composed-process subject, which names no members: regenerate with a CLI ` +
-      'that writes image-lock schemaVersion 4, against a kernel at edition protocol >= v14',
-  );
-}
-
 /**
  * The image-lock schemaVersion a writer emits for `subjects`: the loaded
  * kernel's `IMAGE_LOCK_WRITE_SCHEMA_VERSION`. A kernel before edition protocol
@@ -800,7 +784,10 @@ export async function loadKernelDistributionSchemas() {
     parseOciDigest,
     parseGitTreeId,
     parseImageLock,
-    serviceImageSubjects,
+    dedicatedServiceImageSubjects,
+    carryForwardComposedArtifacts,
+    DEFAULT_COMPOSED_IMAGE_CLASS,
+    ComposedImageClassSchema,
     IMAGE_LOCK_WRITE_SCHEMA_VERSION,
     ImageLockSchemaVersion,
     parseImageProducerStatement,
@@ -893,7 +880,10 @@ export async function loadKernelDistributionSchemas() {
     typeof parseOciDigest !== 'function' ||
     typeof parseGitTreeId !== 'function' ||
     typeof parseImageLock !== 'function' ||
-    typeof serviceImageSubjects !== 'function' ||
+    typeof dedicatedServiceImageSubjects !== 'function' ||
+    typeof carryForwardComposedArtifacts !== 'function' ||
+    typeof DEFAULT_COMPOSED_IMAGE_CLASS !== 'string' ||
+    typeof ComposedImageClassSchema?.safeParse !== 'function' ||
     typeof parseImageProducerStatement !== 'function' ||
     typeof parseDistributionImagesStatement !== 'function' ||
     typeof parseImageDeliveryEntitlementStatement !== 'function' ||
@@ -997,6 +987,8 @@ export async function loadKernelDistributionSchemas() {
   // The build-record exports (absent from a kernel before the build-record contract): carried as-is, NOT required
   // here, so every other verb still loads an older kernel. `select-records` refuses a kernel that lacks them.
   const { BUILD_RECORD_MEDIA_TYPE, BuildRecordSchema, buildRecordTag, parseBuildRecordTag, compareBuildRecordRuns, parseBuildRecord } = mod;
+  // The image-build-record exports (edition protocol v41): the same, carried as-is; `develop image-record` and `--images-from` refuse an older kernel.
+  const { IMAGE_BUILD_RECORD_SCHEMA_VERSION, ImageBuildRecordSchema, parseImageBuildRecord } = mod;
   return {
     BUILD_RECORD_MEDIA_TYPE,
     BuildRecordSchema,
@@ -1004,6 +996,9 @@ export async function loadKernelDistributionSchemas() {
     parseBuildRecordTag,
     compareBuildRecordRuns,
     parseBuildRecord,
+    IMAGE_BUILD_RECORD_SCHEMA_VERSION,
+    ImageBuildRecordSchema,
+    parseImageBuildRecord,
     parseDistribution,
     parseDistributionLock,
     parseDistributionLockForReading,
@@ -1022,7 +1017,10 @@ export async function loadKernelDistributionSchemas() {
     parseOciDigest,
     parseGitTreeId,
     parseImageLock,
-    serviceImageSubjects,
+    dedicatedServiceImageSubjects,
+    carryForwardComposedArtifacts,
+    DEFAULT_COMPOSED_IMAGE_CLASS,
+    ComposedImageClassSchema,
     IMAGE_LOCK_WRITE_SCHEMA_VERSION,
     ImageLockSchemaVersion,
     parseImageProducerStatement,
@@ -1981,6 +1979,7 @@ export async function manifestToIndexEntry({ raw, generatedIndex, rel, repo, pat
           logicalName: requirement.logicalName,
           scope: requirement.scope,
           inclusion: requirement.inclusion,
+          ...(requirement.sharing === undefined ? {} : { sharing: requirement.sharing }),
         });
       }
       for (const provision of provisions) {
@@ -2097,25 +2096,6 @@ export async function manifestToIndexEntry({ raw, generatedIndex, rel, repo, pat
   providesResources.sort(
     (a, b) => compareStrings(a.service, b.service) || compareStrings(a.kind, b.kind),
   );
-  // The provider derives a resource's PHYSICAL identity from the owning biome
-  // plus (kind, scope, logicalName). Two consumers of this biome naming the
-  // same tuple would be handed ONE physical resource while each believes it
-  // owns it — so the declaration is refused here, where the biome is the whole
-  // subject, rather than discovered at the provider.
-  const physicalResources = new Map();
-  for (const row of serviceResources) {
-    const identity = `${row.kind}\0${row.scope}\0${row.logicalName}`;
-    const holder = physicalResources.get(identity);
-    if (holder !== undefined && holder !== row.consumerService) {
-      throw new Error(
-        `${rel}: services "${holder}" and "${row.consumerService}" both declare ` +
-          `${row.scope}-scoped ${row.kind} "${row.logicalName}" — biome "${id}" ` +
-          `derives ONE physical resource from that, so two consumers would share ` +
-          `it while each believes it owns it. Give each its own logicalName.`,
-      );
-    }
-    physicalResources.set(identity, row.consumerService);
-  }
   // The two arrays partition the biome's images — a name in both would be
   // simultaneously rostered and unschedulable.
   for (const name of runtimeComponents) {
@@ -3129,9 +3109,7 @@ export function validateImmutableImageLock(lock, schemas) {
     throw new Error('trusted kernel distribution schemas are required');
   }
   assertKernelSealsComposedMembership(schemas, lock.subjects, `distribution "${lock.distributionId}"`);
-  // The revisions the loaded kernel reads (`ImageLockSchemaVersion`: 3 without
-  // composed membership, 4 with it); a kernel before image-lock v4 reads only 3.
-  if (schemas.ImageLockSchemaVersion === undefined) {assertLegacyLockHasNoComposedSubject(lock);}
+  // The revisions the loaded kernel reads (`ImageLockSchemaVersion`).
   const readableVersions =
     schemas.ImageLockSchemaVersion === undefined
       ? [PRE_V14_IMAGE_LOCK_SCHEMA_VERSION]
@@ -3146,11 +3124,13 @@ export function validateImmutableImageLock(lock, schemas) {
     );
   }
   const identities = new Set();
+  const namedSubjects = new Set();
   for (const subject of lock.subjects ?? []) {
-    const identity = `${subject.kind}\0${subject.id}`;
+    namedSubjects.add(`${subject.kind}:${subject.id}`);
+    const identity = imageSubjectIdentity(subject);
     if (identities.has(identity)) {
       throw new Error(
-        `distribution "${lock.distributionId}" has duplicate runtime image subject "${subject.kind}:${subject.id}"`,
+        `distribution "${lock.distributionId}" has duplicate runtime image subject "${identity}"`,
       );
     }
     identities.add(identity);
@@ -3185,7 +3165,7 @@ export function validateImmutableImageLock(lock, schemas) {
       );
     }
     platformServices.add(binding.platformService);
-    if (!identities.has(`${binding.subjectKind}\0${binding.subjectId}`)) {
+    if (!namedSubjects.has(`${binding.subjectKind}:${binding.subjectId}`)) {
       throw new Error(
         `distribution "${lock.distributionId}": platform service "${binding.platformService}" binds unknown runtime subject "${binding.subjectKind}:${binding.subjectId}"`,
       );

package/edition/locked-bundle-signer.mjs

@@ -15,6 +15,7 @@
 
 import { createRequire } from 'node:module';
 
+import { KernelRefusalName, RefusalError, collectRefusals, isRefusal, joinRefusalMessages } from './collected-refusals.mjs';
 import { editionWorkspaceConfig } from './edition-config.mjs';
 import { assertKernelEditionProtocol } from './edition-protocol.mjs';
 import { dataRoot, kernelDistPath, kernelPackageDir } from './edition-workspace.mjs';
@@ -31,13 +32,16 @@ const PUBLIC_KEY_KIND = 'public-key';
 const KERNEL_EXPORTS = Object.freeze(['lockedBundleSignerOf', 'assertLockedBundleSignerMatches', 'LockedBundleSignerUnknownPolicyError', 'LockedBundleSignerAmbiguousPolicyError']);
 
 /** A named refusal of the bundle signer plane. */
-class BundleSignerError extends Error {
+export class BundleSignerError extends RefusalError {
   constructor(message) {
     super(message);
     this.name = new.target.name;
   }
 }
 
+/** Whether `error` is a refusal of the bundle signer plane: this module's own, or one the kernel's signer projection throws. */
+export const isBundleSignerRefusal = (error) => error instanceof BundleSignerError || (isRefusal(error) && Object.values(KernelRefusalName).includes(error.name));
+
 /** No trust policy row can be selected for the subject: no pin, no `firstPartyBundleSigner`, or no policy at all. */
 export class BundleSignerPolicyAbsentError extends BundleSignerError {}
 /** The selected row is not of the kind its origin requires. */
@@ -54,6 +58,14 @@ export class BundleSourceOnGitRowError extends BundleSignerError {}
 export class GitSourcedHostModuleBundleError extends BundleSignerError {}
 /** The loaded kernel does not export what the bundle signer plane needs. */
 export class BundleSignerKernelUnsupportedError extends BundleSignerError {}
+/** Several OCI rows were refused in one pass; `.errors` holds each row's own refusal. */
+export class BundleSignerRefusedError extends BundleSignerError {
+  /** @param {readonly Error[]} errors */
+  constructor(errors) {
+    super(`${errors.length} OCI bundle rows are refused:\n\n${joinRefusalMessages(errors)}`);
+    this.errors = errors;
+  }
+}
 
 /** What the kernel must export, validated once: `module` is the loaded kernel `distribution` module. */
 export function bundleSignerKernelFrom(module, location) {
@@ -234,8 +246,8 @@ export function assertLockBundleSigners({ lock, selection, schemas }) {
   const subjects = lockBundleSubjects(lock);
   if (subjects.length === 0) {return;}
   const chosen = selection ?? loadBundleSignerSelection({ dataRoot: dataRoot(), schemas });
-  for (const { row, subject } of subjects) {
+  collectRefusals(subjects, ({ row, subject }) => {
     assertNotGitSourced(subject);
     chosen.assertSealed(subject, row.bundleSigner);
-  }
+  }, isRefusal, BundleSignerRefusedError);
 }

package/edition/operation-grant-admission.mjs

@@ -10,13 +10,16 @@
  * and the edition's store-workload ceiling are admitted the same way.
  */
 
+import { RefusalError, collectRefusals, isRefusal, joinRefusalMessages } from './collected-refusals.mjs';
+
 /** Thrown when one or more declared operation requirements are not admitted. */
-export class OperationGrantAdmissionError extends Error {
+export class OperationGrantAdmissionError extends RefusalError {
   /**
    * @param {string} distributionId
    * @param {ReadonlyArray<{code: string, operation: string, message: string}>} refusals
+   * @param {ReadonlyArray<{caller: object, operation: string, reason: string}>} [ungrantedOptional] what the kernel left ungranted beside the refusals
    */
-  constructor(distributionId, refusals) {
+  constructor(distributionId, refusals, ungrantedOptional = []) {
     super(
       `distribution "${distributionId}" declares operation requirements that are not admitted:\n` +
         refusals.map((refusal) => `[${refusal.code}] ${refusal.message}`).join('\n'),
@@ -24,6 +27,7 @@ export class OperationGrantAdmissionError extends Error {
     this.name = 'OperationGrantAdmissionError';
     this.distributionId = distributionId;
     this.refusals = refusals;
+    this.ungrantedOptional = ungrantedOptional;
   }
 }
 
@@ -49,7 +53,7 @@ export function assertOperationGrantsAdmitted(schemas, lock, { report } = {}) {
   // A platform service's refused requirement fails exactly like a biome component's, through the same error.
   const allRefusals = [...refusals, ...platformServiceRefusals];
   if (allRefusals.length > 0) {
-    throw new OperationGrantAdmissionError(lock.distributionId, allRefusals);
+    throw new OperationGrantAdmissionError(lock.distributionId, allRefusals, ungrantedOptional);
   }
   if (report !== undefined) {
     for (const line of ungrantedOptionalOperationLines(lock.distributionId, ungrantedOptional)) {report(line);}
@@ -58,7 +62,7 @@ export function assertOperationGrantsAdmitted(schemas, lock, { report } = {}) {
 }
 
 /** Thrown when one or more declared organization sweeps are not admitted. */
-export class OrganizationSweepAdmissionError extends Error {
+export class OrganizationSweepAdmissionError extends RefusalError {
   /**
    * @param {string} distributionId
    * @param {ReadonlyArray<{code: string, biome: string, component: string, sweep: string, message: string}>} refusals
@@ -89,7 +93,7 @@ export function assertOrganizationSweepsAdmitted(schemas, lock) {
 }
 
 /** Thrown when one or more declared exact audiences are not admitted. */
-export class ExactAudienceAdmissionError extends Error {
+export class ExactAudienceAdmissionError extends RefusalError {
   /**
    * @param {string} distributionId
    * @param {ReadonlyArray<{code: string, message: string}>} refusals
@@ -120,7 +124,7 @@ export function assertExactAudiencesAdmitted(schemas, lock) {
 }
 
 /** Thrown when one or more requested installed operations are not admitted into the ceiling. */
-export class InstalledOperationCeilingAdmissionError extends Error {
+export class InstalledOperationCeilingAdmissionError extends RefusalError {
   /**
    * @param {string} distributionId
    * @param {ReadonlyArray<{code: string, biome: string, component: string, operation: string, message: string}>} refusals
@@ -151,7 +155,7 @@ export function assertInstalledOperationCeilingAdmitted(schemas, lock) {
 }
 
 /** Thrown when one or more domains of the edition's store-workload ceiling are not admitted. */
-export class StoreWorkloadCeilingAdmissionError extends Error {
+export class StoreWorkloadCeilingAdmissionError extends RefusalError {
   /**
    * @param {string} distributionId
    * @param {ReadonlyArray<{code: string, domain: string, message: string}>} refusals
@@ -182,7 +186,7 @@ export function assertStoreWorkloadCeilingAdmitted(schemas, lock) {
 }
 
 /** Thrown when one or more declared organization-context relays are not admitted. */
-export class OrgContextRelayAdmissionError extends Error {
+export class OrgContextRelayAdmissionError extends RefusalError {
   /**
    * @param {string} distributionId
    * @param {ReadonlyArray<{code: string, biome: string, component: string, message: string}>} refusals
@@ -212,7 +216,7 @@ export function assertOrgContextRelaysAdmitted(schemas, lock) {
 }
 
 /** Thrown when one or more declared event subscription clauses are not admitted. */
-export class EventSubscriptionAdmissionError extends Error {
+export class EventSubscriptionAdmissionError extends RefusalError {
   /**
    * @param {string} distributionId
    * @param {ReadonlyArray<{code: string, biome: string, component: string, message: string}>} refusals
@@ -241,3 +245,41 @@ export function assertEventSubscriptionsAdmitted(schemas, lock) {
   }
   return admission;
 }
+
+/** Thrown when several admission categories refuse the same lock; `.errors` holds each category's own error. */
+export class LockAdmissionRefusedError extends RefusalError {
+  /** @param {readonly Error[]} errors */
+  constructor(errors) {
+    super(`the distribution lock is refused by ${errors.length} admission checks:\n\n${joinRefusalMessages(errors)}`);
+    this.name = 'LockAdmissionRefusedError';
+    this.errors = errors;
+  }
+}
+
+/**
+ * Run every admission a lock must pass, in the order the resolve has always run them, and refuse with all of them: one
+ * refusal is rethrown unchanged, several are one {@link LockAdmissionRefusedError}. `report` receives the optional
+ * operations left ungranted. Nothing here changes `lock`.
+ */
+export function admitDistributionLock(schemas, lock, { report } = {}) {
+  // The two ceilings read the lock's own fields, not the outcome of the grants, so they are checked beside them.
+  const admissions = [
+    () => assertOperationGrantsAdmitted(schemas, lock, { report }),
+    () => assertOrganizationSweepsAdmitted(schemas, lock),
+    () => assertExactAudiencesAdmitted(schemas, lock),
+    () => assertOrgContextRelaysAdmitted(schemas, lock),
+    () => assertEventSubscriptionsAdmitted(schemas, lock),
+    () => assertInstalledOperationCeilingAdmitted(schemas, lock),
+    () => assertStoreWorkloadCeilingAdmitted(schemas, lock),
+  ];
+  collectRefusals(admissions, (admit) => admit(), isRefusal, LockAdmissionRefusedError);
+}
+
+/**
+ * The {@link ungrantedOptionalOperationLines} a refused admission carries: the refusal of the operation grants itself, or the
+ * one among several that is. Empty when the grants were not what refused.
+ */
+export function ungrantedOptionalLinesOfRefusal(error) {
+  const grantRefusal = [error, ...(error.errors ?? [])].find((candidate) => candidate instanceof OperationGrantAdmissionError);
+  return grantRefusal === undefined ? [] : ungrantedOptionalOperationLines(grantRefusal.distributionId, grantRefusal.ungrantedOptional);
+}

package/edition/resolve-customer-edition.mjs

@@ -150,7 +150,7 @@ export function projectVendorImages(catalogue, lock, enums) {
       ...(biome.runtimeComponents ?? []).map((id) => [enums.RuntimeImageSubjectKind.RuntimeComponent, id]),
     ];
     for (const [kind, id] of wanted) {
-      if (subjectServingBiome(subjects, biome.id, kind, id, enums) === undefined) {
+      if (subjectServingBiome(catalogue.images.schemaVersion, subjects, biome.id, kind, id, enums) === undefined) {
         throw new CatalogueCeilingError(`the catalogue carries no image row for ${kind}:${id} of selected biome "${biome.id}"`);
       }
     }