@xemahq/xema 0.52.0 → 0.54.0

package/edition/images-from-record.mjs

@@ -0,0 +1,362 @@
+// 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 CLI-owned and versioned here, behind this one module. It is a generic image-evidence concept
+// that belongs in @xemahq/contracts (beside BuildRecordSchema); moving it there changes only `parseImageBuildRecord`.
+
+import { canonicalJson } from './canonical-evidence-json.mjs';
+import { canonicalPublicHttpsRepositoryUrl, repositoryOwnerName } from './canonical-repository-url.mjs';
+import { RefusalError } from './collected-refusals.mjs';
+import { developImageRef, isDevelopImageRef } 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';
+
+/** The one schema version of the image build record this CLI reads. */
+export const IMAGE_BUILD_RECORD_SCHEMA_VERSION = 1;
+
+/** 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,
+});
+
+const RECORD_KEYS = Object.freeze(['schemaVersion', ...Object.values(RecordedImageOrigin)]);
+const ENTRY_KEYS = Object.freeze(['subject', 'repository', 'contentHash', 'digest', 'platforms', 'sourceSha']);
+const PLATFORM_REQUIRED_KEYS = Object.freeze(['os', 'architecture']);
+const PLATFORM_KEYS = Object.freeze([...PLATFORM_REQUIRED_KEYS, 'variant']);
+
+const SUBJECT = /^[a-z][a-z0-9-]*:[a-z0-9][a-z0-9._-]*$/;
+const REPOSITORY = /^[a-z0-9.-]+(?::[1-9]\d{0,4})?\/(?:[a-z0-9._-]+\/)*[a-z0-9._-]+$/;
+const CONTENT_HASH = /^[0-9a-f]{64}$/;
+const DIGEST = /^sha256:[0-9a-f]{64}$/;
+const SOURCE_SHA = /^[0-9a-f]{40}$/;
+
+/** 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('/');
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function refuseUnknownKeys(value, allowed, where, problems) {
+  for (const key of Object.keys(value)) {
+    if (!allowed.includes(key)) {problems.push(`${where}: unknown key ${JSON.stringify(key)}`);}
+  }
+}
+
+function checkText(value, pattern, where, problems) {
+  if (typeof value !== 'string' || !pattern.test(value)) {problems.push(`${where} must match ${pattern}; got ${JSON.stringify(value)}`);}
+}
+
+function checkPlatforms(platforms, where, problems) {
+  if (!Array.isArray(platforms) || platforms.length === 0) {
+    problems.push(`${where} must be a non-empty array of {os, architecture[, variant]}`);
+    return;
+  }
+  const seen = new Set();
+  platforms.forEach((platform, index) => {
+    const at = `${where}[${index}]`;
+    if (!isPlainObject(platform)) {
+      problems.push(`${at} must be an object`);
+      return;
+    }
+    refuseUnknownKeys(platform, PLATFORM_KEYS, at, problems);
+    for (const key of Object.keys(platform).filter((name) => PLATFORM_KEYS.includes(name))) {
+      if (typeof platform[key] !== 'string' || platform[key].length === 0) {problems.push(`${at}.${key} must be a non-empty string`);}
+    }
+    for (const key of PLATFORM_REQUIRED_KEYS) {
+      if (!Object.hasOwn(platform, key)) {problems.push(`${at} has no ${key}`);}
+    }
+    const key = platformKey(platform);
+    if (seen.has(key)) {problems.push(`${at} repeats platform ${key}`);}
+    seen.add(key);
+  });
+}
+
+function checkEntry(entry, where, problems) {
+  if (!isPlainObject(entry)) {
+    problems.push(`${where} must be an object`);
+    return;
+  }
+  refuseUnknownKeys(entry, ENTRY_KEYS, where, problems);
+  for (const key of ENTRY_KEYS) {
+    if (!Object.hasOwn(entry, key)) {problems.push(`${where} has no ${key}`);}
+  }
+  checkText(entry.subject, SUBJECT, `${where}.subject`, problems);
+  checkText(entry.repository, REPOSITORY, `${where}.repository`, problems);
+  if (typeof entry.repository === 'string' && REPOSITORY.test(entry.repository) && !isDevelopImageRef(entry.repository)) {
+    problems.push(`${where}.repository ${entry.repository} is not a develop repository`);
+  }
+  checkText(entry.contentHash, CONTENT_HASH, `${where}.contentHash`, problems);
+  checkText(entry.digest, DIGEST, `${where}.digest`, problems);
+  checkText(entry.sourceSha, SOURCE_SHA, `${where}.sourceSha`, problems);
+  checkPlatforms(entry.platforms, `${where}.platforms`, problems);
+}
+
+/**
+ * Parse an image build record: `{schemaVersion: 1, images: [entry], satellites: [entry]}`, every list sorted by
+ * subject, no subject in two entries, and no unknown key anywhere. Every problem is named in one refusal.
+ *
+ * @param {unknown} document
+ * @param {string} source where the record came from (named in the refusal)
+ * @returns {{schemaVersion: 1, images: object[], satellites: object[]}}
+ */
+export function parseImageBuildRecord(document, source) {
+  const problems = [];
+  if (!isPlainObject(document)) {throw new ImageBuildRecordError(`image build record ${source} must be a JSON object`);}
+  refuseUnknownKeys(document, RECORD_KEYS, 'record', problems);
+  if (document.schemaVersion !== IMAGE_BUILD_RECORD_SCHEMA_VERSION) {
+    problems.push(`record.schemaVersion must be ${IMAGE_BUILD_RECORD_SCHEMA_VERSION}; got ${JSON.stringify(document.schemaVersion)}`);
+  }
+  const owner = new Map();
+  for (const origin of Object.values(RecordedImageOrigin)) {
+    const entries = document[origin];
+    if (!Array.isArray(entries)) {
+      problems.push(`record.${origin} must be an array`);
+      continue;
+    }
+    entries.forEach((entry, index) => {
+      const where = `record.${origin}[${index}]`;
+      checkEntry(entry, where, problems);
+      const subject = entry?.subject;
+      if (typeof subject !== 'string') {return;}
+      const previous = entries[index - 1]?.subject;
+      if (typeof previous === 'string' && previous >= subject && previous !== subject) {
+        problems.push(`${where}: record.${origin} must be sorted by subject ("${subject}" follows "${previous}")`);
+      }
+      if (owner.has(subject)) {problems.push(`${where}: subject ${subject} is already recorded at ${owner.get(subject)}`);}
+      else {owner.set(subject, where);}
+    });
+  }
+  if (problems.length > 0) {
+    throw new ImageBuildRecordError(`image build record ${source} is refused:\n  ${problems.join('\n  ')}`);
+  }
+  return document;
+}
+
+/**
+ * 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 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 };
+    },
+    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;
+    },
+  };
+}
+
+/** 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 }) {
+  const recorded = createRecordedImages(record, { distributionId: id });
+  const { imageLock } = await resolveImages(id, { inputs, lock, recordedImages: recorded });
+  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

@@ -1981,6 +1981,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 +2098,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) {

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/operation-requirements.mjs

@@ -60,6 +60,7 @@ function loadKernelAudienceGrammars() {
   kernelAudienceGrammars = {
     ExactAudienceSchema: elementSchema('requiresAudiences'),
     AudienceNamespaceSchema: elementSchema('ownsAudienceNamespaces'),
+    PeerServiceNameSchema: elementSchema('optionalPeers'),
   };
   return kernelAudienceGrammars;
 }
@@ -162,6 +163,16 @@ export function componentOwnedAudienceNamespaces(component, where) {
   return declaredPrivilegeList(component, where, 'ownsAudienceNamespaces', AudienceNamespaceSchema, 'audience namespace');
 }
 
+/**
+ * The peer services one platform service uses only when they are served
+ * (`optionalPeers`, edition protocol v38), each graded by the kernel's peer
+ * service name grammar. Declared INTENT only; `null` when undeclared.
+ */
+export function componentOptionalPeers(component, where) {
+  const { PeerServiceNameSchema } = loadKernelAudienceGrammars();
+  return declaredPrivilegeList(component, where, 'optionalPeers', PeerServiceNameSchema, 'peer service name');
+}
+
 /**
  * The event subscription clauses one workload component declares
  * (`subscribesEvents`), each graded by the kernel's clause grammar and returned

package/edition/platform-service-class.mjs

@@ -1,5 +1,5 @@
 import { isKernelCapabilityDomain } from './kernel-capability-domain.mjs';
-import { componentAudienceRequirements, componentOperationRequirements, componentOwnedAudienceNamespaces } from './operation-requirements.mjs';
+import { componentAudienceRequirements, componentOperationRequirements, componentOptionalPeers, componentOwnedAudienceNamespaces } from './operation-requirements.mjs';
 import { compareStrings } from './string-order.mjs';
 
 /**
@@ -58,7 +58,7 @@ export function sourceOwnedCapabilityDomains(sourceManifest, where) {
 /**
  * What a platform service declares it requires and owns, as the index carries it, read from the
  * same declaration as {@link sourceOwnedCapabilityDomains} (the `xema` block of its source manifest):
- * `requiresOperations`, `requiresAudiences` and `ownsAudienceNamespaces`. Each is sorted, unique and
+ * `requiresOperations`, `requiresAudiences`, `ownsAudienceNamespaces` and `optionalPeers`. Each is sorted, unique and
  * non-empty, or no key at all. Declared INTENT: the lock admits or refuses each
  * (`admitOperationGrants`, `admitExactAudiences`).
  *
@@ -70,10 +70,12 @@ export function sourceDeclaredRequirements(sourceManifest, where) {
   const requiresOperations = componentOperationRequirements(xema, where);
   const requiresAudiences = componentAudienceRequirements(xema, where);
   const ownsAudienceNamespaces = componentOwnedAudienceNamespaces(xema, where);
+  const optionalPeers = componentOptionalPeers(xema, where);
   return {
     ...(requiresOperations === null ? {} : { requiresOperations }),
     ...(requiresAudiences === null ? {} : { requiresAudiences }),
     ...(ownsAudienceNamespaces === null ? {} : { ownsAudienceNamespaces }),
+    ...(optionalPeers === null ? {} : { optionalPeers }),
   };
 }