@xemahq/xema 0.40.3 → 0.41.1

package/edition/edition-artifact.mjs

@@ -5,7 +5,7 @@
 // from edition-contract.json), addressed by digest, whose titled layers are
 // `xema-edition.json` (the descriptor) plus the lock files. It is written to a
 // scratch directory; the workflow pushes it with oras and signs the digest.
-// Tags are for humans only (develop: the hash of every input, developEditionTag; release: the
+// Tags are for humans only (an edition resolved from a snapshot: the hash of every input, snapshotEditionTag; vendor release: the
 // coordinate). Admission rests on the signature of the manifest digest, never on
 // a channel label: no reader branches on `provenance.channel`.
 //
@@ -19,6 +19,8 @@ import { assertCanonicalDistributionId } from './distribution-paths.mjs';
 import { EDITION_CHART_SET_FILE, assertRosteredChartSetLock } from './edition-chart-set.mjs';
 import {
   CATALOGUE_PIN_KEY,
+  DEFINITION_PIN_KEY,
+  DIGEST_PIN_KEYS,
   EDITION_DESCRIPTOR_FILE,
   EDITION_DESCRIPTOR_SCHEMA,
   EDITION_LOCKS,
@@ -81,7 +83,7 @@ export function editionDescriptor({ distributionId, channel, pins, workflow, evi
     locks: [...EDITION_LOCKS],
     provenance: {
       channel,
-      pins: channel === EditionChannel.Develop ? sortedSnapshotPins(pins) : { ...pins },
+      pins: sortedSnapshotPins(pins),
       workflow: { repository: workflow?.repository, runId: workflow?.runId },
     },
     evidenceTrustPolicy,
@@ -90,7 +92,7 @@ export function editionDescriptor({ distributionId, channel, pins, workflow, evi
 }
 
 const COMMIT_PATTERN = /^[0-9a-f]{40}$/;
-const CATALOGUE_DIGEST_PATTERN = /^sha256:[0-9a-f]{64}$/;
+const DIGEST_PIN_PATTERN = /^sha256:[0-9a-f]{64}$/;
 
 const exactKeys = (value, keys, where) => {
   if (value === null || typeof value !== 'object' || Array.isArray(value) || Object.keys(value).sort().join() !== [...keys].sort().join()) {
@@ -114,13 +116,14 @@ export function parseEditionDescriptor(value) {
   }
   const { pins, workflow } = value.provenance;
   if (pins === null || typeof pins !== 'object' || Array.isArray(pins)) {
-    throw new Error(`${EDITION_DESCRIPTOR_FILE}: provenance.pins must map pin keys to 40-hex commits (the "${CATALOGUE_PIN_KEY}" pin to a sha256 digest)`);
+    throw new Error(`${EDITION_DESCRIPTOR_FILE}: provenance.pins must map pin keys to 40-hex commits (the ${DIGEST_PIN_KEYS.map((key) => `"${key}"`).join(' and ')} pins to sha256 digests)`);
   }
   for (const [key, pin] of Object.entries(pins)) {
-    const pattern = key === CATALOGUE_PIN_KEY ? CATALOGUE_DIGEST_PATTERN : COMMIT_PATTERN;
+    const digestPin = DIGEST_PIN_KEYS.includes(key);
+    const pattern = digestPin ? DIGEST_PIN_PATTERN : COMMIT_PATTERN;
     if (typeof pin !== 'string' || !pattern.test(pin)) {
       throw new Error(
-        key === CATALOGUE_PIN_KEY
+        digestPin
           ? `${EDITION_DESCRIPTOR_FILE}: provenance.pins["${key}"] must be a sha256:<64 hex> digest`
           : `${EDITION_DESCRIPTOR_FILE}: provenance.pins must map pin keys to 40-hex commits (${JSON.stringify(key)} is not)`,
       );
@@ -238,15 +241,17 @@ export function canonicalSourceImages(sourceImages = new Map()) {
 }
 
 /**
- * A develop edition's tag: sha256 of the canonical `{ cli, engine, pins, sourceImages }`. Every input of
- * the bytes the artifact records is inside it. The pins fix the locks and the descriptor's pins; the
+ * The tag of an edition resolved from a snapshot (a develop edition, a customer release edition): sha256 of the canonical `{ cli, engine, pins, sourceImages }`. Every input of
+ * the bytes the artifact records is inside it. The pins fix the locks and the descriptor's pins: a vendor edition's
+ * commits fix its definitions; a customer edition's pins carry its sources' commits, the catalogue digest and the
+ * digest of its canonical definition (`definition`: vendor selection, image registry mirror, Store publisher anchors); the
  * descriptor's `engine.image` is not a pin; a customer's `--source-image` map composes its own image rows
  * (`<registry>/<prefix><subject>`) and is not a pin either; and the CLI version is the writer of every
  * byte. A tag over the pins alone named two artifacts that differ in any of the others, and a re-run could
  * only refuse the existing one (`check-existing`) or reuse a stale one. `provenance.workflow` (the run that
  * wrote the bytes) is the one recorded field outside it: a fact about the artifact, not an input to it.
  */
-export function developEditionTag({ pins, engineImage, sourceImages = new Map(), version = cliVersion() }) {
+export function snapshotEditionTag({ pins, engineImage, sourceImages = new Map(), version = cliVersion() }) {
   return sha256Hex(
     serializeJson({
       cli: version,
@@ -257,9 +262,14 @@ export function developEditionTag({ pins, engineImage, sourceImages = new Map(),
   );
 }
 
-/** A develop edition's target: the tag is `developEditionTag` of the pins, the engine and the source images. */
+/** The target of an edition resolved from a snapshot of pins, on either channel: the tag is `snapshotEditionTag`. */
+export function snapshotEditionTarget(channel, distributionId, pins, { registry, engineImage, sourceImages }) {
+  return editionTarget(distributionId, registry, channel, snapshotEditionTag({ pins, engineImage, sourceImages }));
+}
+
+/** A develop edition's target: the tag is `snapshotEditionTag` of the pins, the engine and the source images. */
 export function developEditionTarget(distributionId, pins, { registry, engineImage, sourceImages }) {
-  return editionTarget(distributionId, registry, EditionChannel.Develop, developEditionTag({ pins, engineImage, sourceImages }));
+  return snapshotEditionTarget(EditionChannel.Develop, distributionId, pins, { registry, engineImage, sourceImages });
 }
 
 function realpathOfPlanned(path) {
@@ -329,10 +339,11 @@ export function writeEditionArtifact({
  * An existing develop tag is reused only if it IS this snapshot: the tag
  * is a hash of its inputs, but a tag is mutable registry state, so the pulled
  * descriptor must say the same edition, the same channel, exactly the same pins,
- * the same engine image, the same evidence trust state and the same lock set. A customer artifact (`catalogueDigest` given) must also record that digest
- * as its catalogue provenance pin. Throws naming the first difference.
+ * the same engine image, the same evidence trust state and the same lock set. A customer artifact (`catalogueDigest` and
+ * `definitionDigest` given) must also record those digests as its catalogue and definition provenance pins. Throws naming
+ * the first difference.
  */
-export function assertExistingArtifactMatches({ artifactDir, distributionId, channel, pins, engineImage, evidenceTrustPolicy, catalogueDigest }) {
+export function assertExistingArtifactMatches({ artifactDir, distributionId, channel, pins, engineImage, evidenceTrustPolicy, catalogueDigest, definitionDigest }) {
   const descriptorPath = join(artifactDir, EDITION_DESCRIPTOR_FILE);
   if (!existsSync(descriptorPath)) {
     throw new Error(`the existing artifact holds no ${EDITION_DESCRIPTOR_FILE}; refusing to reuse a tag that is not an edition`);
@@ -354,6 +365,12 @@ export function assertExistingArtifactMatches({ artifactDir, distributionId, cha
         `the pinned catalogue is ${catalogueDigest}; refusing to reuse it`,
     );
   }
+  if (definitionDigest !== undefined && existing.provenance.pins[DEFINITION_PIN_KEY] !== definitionDigest) {
+    throw new Error(
+      `the existing artifact was resolved from customer definition ${JSON.stringify(existing.provenance.pins[DEFINITION_PIN_KEY])}, ` +
+        `this definition is ${definitionDigest} (its selection, mirror or Store publisher anchors differ); refusing to reuse it`,
+    );
+  }
   if (serializeJson(existing.provenance.pins) !== serializeJson(sortedSnapshotPins(pins))) {
     throw new Error('the existing artifact was resolved from different pins than this snapshot (tag and content disagree); refusing to reuse it');
   }

package/edition/edition-constants.mjs

@@ -48,6 +48,15 @@ if (!(CATALOGUE_PIN_KEY in EDITION_CONTRACT.provenancePins)) {
   throw new Error('edition-contract.json provenancePins does not declare the catalogue pin');
 }
 
+/** The digest of the canonical customer definition a customer edition was resolved from: every input the pins of its sources and catalogue do not fix. */
+export const DEFINITION_PIN_KEY = 'definition';
+if (!(DEFINITION_PIN_KEY in EDITION_CONTRACT.provenancePins)) {
+  throw new Error('edition-contract.json provenancePins does not declare the definition pin');
+}
+
+/** The provenance pins that are sha256 digests, not commits. */
+export const DIGEST_PIN_KEYS = Object.freeze([CATALOGUE_PIN_KEY, DEFINITION_PIN_KEY]);
+
 /** The lock files an edition can carry. */
 export const EditionLockFile = Object.freeze({
   Distribution: 'distribution.lock.json',

package/edition/edition-contract.json

@@ -23,7 +23,8 @@
     "catalogue": "catalogue.json"
   },
   "provenancePins": {
-    "catalogue": "the sha256 digest (sha256:<64 hex>) of the offering artifact a customer edition was resolved against; every other pin is a 40-hex commit"
+    "catalogue": "the sha256 digest (sha256:<64 hex>) of the offering artifact a customer edition was resolved against",
+    "definition": "the sha256 digest (sha256:<64 hex>) of the canonical JSON of the customer definition a customer edition was resolved from (vendor selection, image registry mirror, Store publisher anchors, sources); every other pin is a 40-hex commit"
   },
   "imageNamespaceSegment": "dev",
   "evidenceTrust": {

package/edition/{develop-seal.mjs → edition-image-seal.mjs}

@@ -1,10 +1,13 @@
-// develop-seal — seal a snapshot's images lock against the DEVELOP repositories.
+// edition-image-seal — seal image subjects against the repositories of one channel.
 //
-// The release sealer verifies `<imageRef>:<contentHash>` and writes the digest
-// the registry served. This does the same for a develop edition, with the
+// The vendor release sealer verifies `<imageRef>:<contentHash>` and writes the digest
+// the registry served. This does the same for an edition of either channel, with the
 // SAME verifier (`verifyDistributionPlatforms`, required platforms enforced)
-// and the SAME digest decision (`planDigestSeal`), against the repository the
-// producer's develop lane pushes to (`developImageRef`, contract C1).
+// and the SAME digest decision (`planDigestSeal`). Only the repository differs:
+//   develop  the repository the producer's develop lane pushes to (`developImageRef`, contract C1)
+//   release  the subject's own imageRef (the identity)
+// It never builds or rebuilds an image: a coordinate that is not there is refused, and the digest
+// sealed is the digest the registry serves for `<repository>:<contentHash>`.
 //
 // A coordinate that is not there is "not built yet": the producer's CI is not
 // green or still running. EVERY such subject is collected and named at once;
@@ -13,23 +16,39 @@
 
 import { developImageRef } from './develop-image-coordinate.mjs';
 import { notBuiltYetError } from './develop-image-probe.mjs';
+import { EditionChannel } from './edition-channel.mjs';
 import { editionsRoot } from './edition-workspace.mjs';
 import { validateImmutableImageLock, loadKernelDistributionSchemas, } from './lib.mjs';
 import { isNotPublishedYet, planDigestSeal } from './seal-image-digests.mjs';
 import { verifyDistributionPlatforms } from './verify-image-platforms.mjs';
 
+/** The repository a channel's own image subjects are verified and sealed in, from the subject's release imageRef. */
+const CHANNEL_IMAGE_REF = Object.freeze({
+  [EditionChannel.Develop]: developImageRef,
+  [EditionChannel.Release]: (releaseImageRef) => releaseImageRef,
+});
+
+/** The repository `channel` seals a subject whose release imageRef is `releaseImageRef` in. */
+export function channelImageRef(channel, releaseImageRef) {
+  const toChannelRef = CHANNEL_IMAGE_REF[channel];
+  if (toChannelRef === undefined) {throw new Error(`cannot seal image subjects for channel ${JSON.stringify(channel)}`);}
+  return toChannelRef(releaseImageRef);
+}
+
 /**
- * The row-level seal: every subject re-homed to its develop repository, verified
+ * The row-level seal: every subject re-homed to its channel's repository, verified
  * there for its required platforms, and given the digest the registry served.
  * It takes SUBJECTS, not a lock, so a caller that owns only some rows of a lock
  * (a customer's own image rows) seals exactly those.
  *
  * @param {object} request
+ * @param {string} request.channel `develop` or `release`: which repositories the subjects are sealed in
  * @param {string} request.distributionId the edition the subjects belong to (named in refusals)
  * @param {object[]} request.subjects image subjects (release refs, unsealed)
- * @returns the subjects with develop refs and verified digests
+ * @returns the subjects with the channel's refs and verified digests
  */
-export async function sealDevelopImageSubjects({
+export async function sealImageSubjects({
+  channel,
   distributionId,
   subjects,
   distributionsRoot = editionsRoot(),
@@ -38,12 +57,12 @@ export async function sealDevelopImageSubjects({
   run = null,
   progress = null,
 }) {
-  const developSubjects = subjects.map((subject) => ({
+  const channelSubjects = subjects.map((subject) => ({
     ...subject,
-    imageRef: developImageRef(subject.imageRef),
+    imageRef: channelImageRef(channel, subject.imageRef),
   }));
   const report = await verifyDistributionPlatforms({
-    imageLock: { distributionId, subjects: developSubjects },
+    imageLock: { distributionId, subjects: channelSubjects },
     distributionsRoot,
     env,
     fetchImpl,
@@ -54,11 +73,11 @@ export async function sealDevelopImageSubjects({
   const aborting = report.failures.find(({ error }) => !isNotPublishedYet(error));
   if (aborting) {throw aborting.error;}
   if (report.failures.length > 0) {
-    throw notBuiltYetError(distributionId, report.failures.map(({ subject }) => subject));
+    throw notBuiltYetError(distributionId, report.failures.map(({ subject }) => subject), channel);
   }
-  const { writes, unchanged } = planDigestSeal({ subjects: developSubjects, verified: report.subjects });
+  const { writes, unchanged } = planDigestSeal({ subjects: channelSubjects, verified: report.subjects });
   const digests = new Map([...writes, ...unchanged].map(({ key, digest }) => [key, digest]));
-  return developSubjects.map((subject) => ({
+  return channelSubjects.map((subject) => ({
     ...subject,
     imageDigest: digests.get(`${subject.kind}:${subject.id}`),
   }));
@@ -70,10 +89,10 @@ export async function sealDevelopImageSubjects({
  *
  * @param {object} request
  * @param {object} request.imageLock the snapshot images lock (release refs, unsealed)
- * @returns the images lock with develop refs and verified digests, kernel-validated
+ * @returns the images lock with the channel's refs and verified digests, kernel-validated
  */
-export async function sealDevelopImages({ imageLock, ...sealOptions }) {
-  const subjects = await sealDevelopImageSubjects({
+export async function sealImages({ imageLock, ...sealOptions }) {
+  const subjects = await sealImageSubjects({
     distributionId: imageLock.distributionId,
     subjects: imageLock.subjects,
     ...sealOptions,

package/edition/edition-workspace.mjs

@@ -182,9 +182,10 @@ export function isEntryModule(moduleUrl) {
 /**
  * The entry's one call: configure the roots from `process.argv` and remove the
  * root flags from it, so the entry's own parser sees only its own arguments.
- * `options` are those of `configureEditionWorkspaceFromArgv`.
+ * `options` are those of `configureEditionWorkspaceFromArgv`, plus `failureExitCode` (default 1): the exit code of
+ * a refused root, for a verb whose exit 1 already means something else.
  */
-export function configureEditionWorkspaceFromProcess(needs, options) {
+export function configureEditionWorkspaceFromProcess(needs, { failureExitCode = 1, ...options } = {}) {
   let rest;
   try {
     rest = configureEditionWorkspaceFromArgv(process.argv.slice(2), needs, options);
@@ -195,7 +196,7 @@ export function configureEditionWorkspaceFromProcess(needs, options) {
     process.stderr.write(
       `${error.message}\nusage: this command takes ${needs.map((name) => `${WORKSPACE_FLAGS[name]} <dir>`).join(' ')}\n`,
     );
-    process.exit(1);
+    process.exit(failureExitCode);
   }
   process.argv.splice(2, process.argv.length - 2, ...rest);
 }

package/edition/evidence-trust-pin.mjs

@@ -10,13 +10,15 @@
 // change and the registry reader cannot change without a reviewed data-root
 // commit.
 //
+// A customer data root has no such index; its pin records `kernelContractAuthority: null` and pins only what exists.
+//
 // The kernel contract authority is pinned HERE because nothing else can hold
 // it: `runtime-image-source-index.json` states the authority, and the image
 // locks and statements are compared with what that file states. Comparing the
 // file with itself decides nothing, so its authority is first held to this
 // pin, and only the pinned authority is what evidence is compared with.
 
-import { closeSync, constants as fsConstants, openSync, writeFileSync } from 'node:fs';
+import { closeSync, constants as fsConstants, existsSync, openSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 
 import { COMMIT_PATTERN } from './evidence-grammars.mjs';
@@ -61,7 +63,7 @@ const VERIFIER_KEYS = Object.freeze(['bundleDigest', 'provenanceDigest']);
 const AUTHORITY_PIN_KEYS = Object.freeze(['digest', 'sourceCommit']);
 const PIN_SHAPE =
   '{schemaVersion, policyDigest, verifier: {bundleDigest, provenanceDigest}, ' +
-  'kernelContractAuthority: {sourceCommit, digest}, trustedOrasBinaryDigests: [sha256:…, …]}';
+  'kernelContractAuthority: {sourceCommit, digest} | null, trustedOrasBinaryDigests: [sha256:…, …]}';
 
 const exactKeys = (value, keys) =>
   value !== null &&
@@ -117,7 +119,7 @@ export function readEvidenceTrustPin({ dataRoot, declaration }) {
   if (
     !exactKeys(pin, PIN_KEYS) ||
     !exactKeys(pin.verifier, VERIFIER_KEYS) ||
-    !exactKeys(pin.kernelContractAuthority, AUTHORITY_PIN_KEYS) ||
+    !(pin.kernelContractAuthority === null || exactKeys(pin.kernelContractAuthority, AUTHORITY_PIN_KEYS)) ||
     !Array.isArray(pin.trustedOrasBinaryDigests)
   ) {
     throw new Error(`${declaration.pin}: the pin is exactly ${PIN_SHAPE}`);
@@ -137,10 +139,13 @@ export function readEvidenceTrustPin({ dataRoot, declaration }) {
         'verifier.provenanceDigest',
       ),
     }),
-    kernelContractAuthority: Object.freeze({
-      sourceCommit: requireCommit(pin.kernelContractAuthority.sourceCommit),
-      digest: requireDigest(pin.kernelContractAuthority.digest, 'kernelContractAuthority.digest'),
-    }),
+    kernelContractAuthority:
+      pin.kernelContractAuthority === null
+        ? null
+        : Object.freeze({
+            sourceCommit: requireCommit(pin.kernelContractAuthority.sourceCommit),
+            digest: requireDigest(pin.kernelContractAuthority.digest, 'kernelContractAuthority.digest'),
+          }),
     trustedOrasBinaryDigests: requireOrasDigests(pin.trustedOrasBinaryDigests),
   });
 }
@@ -175,6 +180,14 @@ export function kernelContractAuthorityPin(authority) {
   });
 }
 
+/**
+ * Whether the data root holds a runtime image source index. A vendor data root does; a customer data root has none
+ * (it consumes a catalogue and states no kernel contract authority of its own), and its pin records `null`.
+ */
+export function hasRuntimeImageSourceIndex(dataRoot) {
+  return existsSync(join(dataRoot, RUNTIME_IMAGE_SOURCE_INDEX_FILE));
+}
+
 /** The kernel contract authority the data root's runtime image source index STATES; nothing is trusted yet. */
 export function readStatedKernelContractAuthority({ dataRoot, schemas }) {
   if (!schemas?.parseRuntimeImageSourceIndex) {
@@ -192,6 +205,13 @@ export function readStatedKernelContractAuthority({ dataRoot, schemas }) {
 /** Refuse an authority that is not the one the pin records. */
 export function assertPinnedKernelContractAuthority({ pin, authority, label }) {
   const actual = kernelContractAuthorityPin(authority);
+  if (pin.kernelContractAuthority === null) {
+    throw new KernelContractAuthorityPinError(
+      KERNEL_CONTRACT_AUTHORITY_NOT_PINNED_ONE,
+      `${label} states kernel contract authority ${actual.sourceCommit} (${actual.digest}) but the pin records none ` +
+        `(it was written for a data root without a runtime image source index); review the index, then re-pin with \`${REPIN_COMMAND}\``,
+    );
+  }
   if (
     actual.sourceCommit !== pin.kernelContractAuthority.sourceCommit ||
     actual.digest !== pin.kernelContractAuthority.digest
@@ -283,7 +303,7 @@ export function writeEvidenceTrustPin({
       bundleDigest: verifier.bundleDigest,
       provenanceDigest: verifier.provenanceDigest,
     },
-    kernelContractAuthority: { ...kernelContractAuthorityPin(kernelContractAuthority) },
+    kernelContractAuthority: kernelContractAuthority === null ? null : { ...kernelContractAuthorityPin(kernelContractAuthority) },
     trustedOrasBinaryDigests: [...requireOrasDigests(trustedOrasBinaryDigests)].sort(),
   };
   const text = `${JSON.stringify(pin, null, 2)}\n`;

package/edition/evidence-trust-policy.mjs

@@ -133,6 +133,28 @@ function loadPinnedPolicy({ dataRoot, declaration, schemas, locateVerifier }) {
   return { policy, policyDigest };
 }
 
+/**
+ * The data root's declared policy, loaded and held to its pin exactly as the
+ * arming checks load it, for a READ-ONLY consumer (the develop coverage verb).
+ * A data root that declares no policy has nothing to report coverage against
+ * and is refused, naming the declaration it lacks. The POLICY is held to its pin; this CLI's built verifier
+ * is not. Coverage therefore runs this CLI's own, unpinned verifier code (case A), so a green coverage is a
+ * forecast of what resolve accepts, not a guarantee: resolve can still refuse under the pinned verifier.
+ *
+ * @returns {{ policy: object, dataRoot: string }}
+ */
+export async function loadDeclaredPinnedPolicy() {
+  const declaration = editionWorkspaceConfig().evidenceTrustPolicy;
+  const root = configuredDataRoot();
+  if (declaration.policy === null) {
+    throw new Error(`${join(root, EDITION_WORKSPACE_CONFIG_FILE)} declares no evidenceTrustPolicy; there is no pinned policy to report coverage against`);
+  }
+  const schemas = await loadKernelDistributionSchemas();
+  const { policy, policyDigest } = loadDeclaredTrustPolicy({ dataRoot: root, declaration, schemas });
+  assertPinnedPolicy({ pin: readEvidenceTrustPin({ dataRoot: root, declaration }), policyDigest });
+  return { policy, dataRoot: root };
+}
+
 /**
  * The arming of the data root's declared policy on `channel`, loaded and pinned
  * exactly as `descriptorEvidenceTrust` and the check load it: `{ declared, state,
@@ -140,9 +162,9 @@ function loadPinnedPolicy({ dataRoot, declaration, schemas, locateVerifier }) {
  * false` and one unmet entry; a declared policy that does not hold to its pin
  * (digest, verifier) throws. Nothing is written.
  *
- * @param {{ channel: string, locateVerifier?: () => {bundlePath: string, provenancePath: string} }} options
+ * @param {{ channel: string, locateVerifier?: () => {bundlePath: string, provenancePath: string}, consumesCatalogue?: boolean }} options
  */
-export async function assessDeclaredTrustPolicyArming({ channel, locateVerifier = locateBuiltVerifier }) {
+export async function assessDeclaredTrustPolicyArming({ channel, locateVerifier = locateBuiltVerifier, consumesCatalogue = false }) {
   const declaration = editionWorkspaceConfig().evidenceTrustPolicy;
   const root = configuredDataRoot();
   const schemas = await loadKernelDistributionSchemas();
@@ -155,13 +177,26 @@ export async function assessDeclaredTrustPolicyArming({ channel, locateVerifier
     };
   }
   const { policy } = loadPinnedPolicy({ dataRoot: root, declaration, schemas, locateVerifier });
-  const { state, unmet } = assessTrustPolicyArming(policy, schemas, channel);
+  const { state, unmet } = assessTrustPolicyArming(policy, schemas, channel, { consumesCatalogue });
   return { declared: true, state, unmet };
 }
 
 /** What a develop edition says, once, when it is written or checked without an armed develop channel. */
 export const DEVELOP_NOT_ARMED_NOTICE = 'develop channel: trust policy not armed, evidence is not signature-verified';
 
+/** A customer develop edition under a policy ARMED on develop: its catalogue carries no E4 evidence to verify. */
+export class CatalogueEvidenceUnverifiableError extends Error {
+  constructor(root) {
+    super(
+      `the data root ${root} declares an evidence trust policy ARMED on the develop channel, but a develop catalogue carries no ` +
+        'signed edition-catalogue (E4) evidence, so the catalogue this customer develop edition consumes cannot be verified and ' +
+        'the edition is never recorded as armed. Resolve it under a policy that is not armed on develop (no develop signer rows), ' +
+        'or resolve a release edition, whose catalogue evidence is verified.',
+    );
+    this.name = 'CatalogueEvidenceUnverifiableError';
+  }
+}
+
 /**
  * The evidence state an edition of `channel` records in its descriptor. Arming
  * is judged for that ONE channel (`assessTrustPolicyArming`): the signers of
@@ -179,9 +214,15 @@ export const DEVELOP_NOT_ARMED_NOTICE = 'develop channel: trust policy not armed
  * A policy edited after pinning, a drifted verifier, and a policy PARTIALLY
  * ARMED on `channel` are refused on either channel.
  *
- * @param {{ channel: string, locateVerifier?: () => {bundlePath: string, provenancePath: string} }} options
+ * `consumesCatalogue` (a customer edition consumes a catalogue): on RELEASE it adds the edition-catalogue (E4) row to the
+ * required ones, and the catalogue's E4 evidence is verified before it is parsed. A DEVELOP catalogue carries no E4
+ * evidence (the vendor's develop-edition workflow signs the artifact but attaches no E4 statement), so on develop no E4
+ * row is required and nothing can verify the catalogue: a customer develop edition is never written `armed`. A policy
+ * ARMED on develop throws CatalogueEvidenceUnverifiableError instead of recording a claim nothing checked.
+ *
+ * @param {{ channel: string, locateVerifier?: () => {bundlePath: string, provenancePath: string}, consumesCatalogue?: boolean }} options
  */
-export async function descriptorEvidenceTrust({ channel, locateVerifier = locateBuiltVerifier }) {
+export async function descriptorEvidenceTrust({ channel, locateVerifier = locateBuiltVerifier, consumesCatalogue = false }) {
   const declaration = editionWorkspaceConfig().evidenceTrustPolicy;
   const root = configuredDataRoot();
   const schemas = await loadKernelDistributionSchemas();
@@ -196,8 +237,11 @@ export async function descriptorEvidenceTrust({ channel, locateVerifier = locate
     return developNotArmed();
   }
   const { policy } = loadPinnedPolicy({ dataRoot: root, declaration, schemas, locateVerifier });
-  const { state, unmet } = assessTrustPolicyArming(policy, schemas, channel);
-  if (state === TrustPolicyArmingState.ARMED) {return EvidenceTrustState.Armed;}
+  const { state, unmet } = assessTrustPolicyArming(policy, schemas, channel, { consumesCatalogue: consumesCatalogue && release });
+  if (state === TrustPolicyArmingState.ARMED) {
+    if (consumesCatalogue && !release) {throw new CatalogueEvidenceUnverifiableError(root);}
+    return EvidenceTrustState.Armed;
+  }
   if (state === TrustPolicyArmingState.PARTIAL) {
     if (release) {throw new EvidenceTrustRequiredError(root, `declares a policy that is PARTIALLY ARMED on the ${channel} channel (${unmet.join('; ')})`);}
     throw new Error(`the declared evidence trust policy is PARTIALLY ARMED on the ${channel} channel (${unmet.join('; ')}); an edition cannot be written against it`);

package/edition/image-evidence.mjs

@@ -42,7 +42,7 @@ const MAX_SIGSTORE_BUNDLE_BYTES = 16 * 1024 * 1024;
 const MAX_TRUSTED_ROOT_BYTES = 8 * 1024 * 1024;
 /** The kernel's `SignerKind.OidcCertificate`: the one signer kind this verifier runs (cosign keyless). */
 const OIDC_CERTIFICATE_SIGNER = 'oidc-certificate';
-const COSIGN_ENV = Object.freeze({
+export const COSIGN_ENV = Object.freeze({
   LANG: 'C',
   LC_ALL: 'C',
   PATH: '/usr/bin:/bin',
@@ -632,7 +632,7 @@ function assertEvidenceChannel(channel) {
  * selects which policy rows are tried; what authenticates a channel is the
  * certificate matching a row of that channel.
  */
-function policyCandidates(policy, predicateType, channel, imageRepository) {
+export function policyCandidates(policy, predicateType, channel, imageRepository) {
   const candidates = policy.policies.filter(
     (candidate) =>
       candidate.channel === channel &&

package/edition/lib.mjs

@@ -20,6 +20,12 @@ import { readBiomeAuthorizationModuleAt } from './authorization-base.mjs';
 import {
   isAuthoritativeProductionBiomeSource,
 } from './connector-source-authority.mjs';
+import {
+  compareDispatchedEdges,
+  dispatchedEdgeIdentity,
+  isSupplementalEdge,
+  projectDispatchedTarget,
+} from './dispatched-runtime-components.mjs';
 import { assertKernelEditionProtocol } from './edition-protocol.mjs';
 import {
   kernelDistPath,
@@ -734,6 +740,8 @@ export async function loadKernelDistributionSchemas() {
     parseImageProducerStatement,
     parseDistributionImagesStatement,
     parseImageDeliveryEntitlementStatement,
+    parseEditionCatalogueStatement,
+    editionCatalogueRefusal,
     parseDistributionImageEvidenceSet,
     parseDistributionImageReplayState,
     parseSigstoreOfflineTrustPolicy,
@@ -751,6 +759,7 @@ export async function loadKernelDistributionSchemas() {
     IMAGE_PRODUCER_PREDICATE_TYPE,
     DISTRIBUTION_IMAGES_PREDICATE_TYPE,
     IMAGE_DELIVERY_ENTITLEMENT_PREDICATE_TYPE,
+    EDITION_CATALOGUE_PREDICATE_TYPE,
     EVIDENCE_CHANNELS,
     EVIDENCE_CHANNEL_REFS,
     resolveFirstPartyCapabilityDomains,
@@ -927,6 +936,8 @@ export async function loadKernelDistributionSchemas() {
     parseImageProducerStatement,
     parseDistributionImagesStatement,
     parseImageDeliveryEntitlementStatement,
+    parseEditionCatalogueStatement,
+    editionCatalogueRefusal,
     parseDistributionImageEvidenceSet,
     parseDistributionImageReplayState,
     parseSigstoreOfflineTrustPolicy,
@@ -943,6 +954,8 @@ export async function loadKernelDistributionSchemas() {
     IMAGE_PRODUCER_PREDICATE_TYPE,
     DISTRIBUTION_IMAGES_PREDICATE_TYPE,
     IMAGE_DELIVERY_ENTITLEMENT_PREDICATE_TYPE,
+    // Optional: a kernel without the E4 predicate is a catalogue consumer that cannot be armed (trust-policy-arming.mjs).
+    EDITION_CATALOGUE_PREDICATE_TYPE,
     EVIDENCE_CHANNELS,
     EVIDENCE_CHANNEL_REFS,
     resolveFirstPartyCapabilityDomains,
@@ -2030,16 +2043,10 @@ export async function manifestToIndexEntry({ raw, generatedIndex, rel, repo, pat
     ...new Map(
       parsedIndex.biome.edges
         .filter((edge) => edge.kind === kernelBiome.BiomeGeneratedEdgeKind.RuntimeImage)
-        .map((edge) => [
-          `${edge.target.biomeId}\0${edge.target.componentKey}`,
-          { biomeId: edge.target.biomeId, componentKey: edge.target.componentKey },
-        ]),
+        .map((edge) => projectDispatchedTarget(id, edge.target))
+        .map((target) => [dispatchedEdgeIdentity(target), target]),
     ).values(),
-  ].sort(
-    (a, b) =>
-      compareStrings(a.biomeId, b.biomeId) ||
-      compareStrings(a.componentKey, b.componentKey),
-  );
+  ].sort(compareDispatchedEdges);
 
   // Optional server biomes a web biome can integrate with but does not require
   // (never cause an ORPHANED resolution). Carried separately from `requires`.
@@ -2788,10 +2795,12 @@ export function validateImmutableBiomeIndex(index) {
     }
     const dispatched = new Set();
     for (const edge of biome.dispatchesRuntimeComponents ?? []) {
-      const edgeKey = `${edge.biomeId}\0${edge.componentKey}`;
+      const edgeKey = dispatchedEdgeIdentity(projectDispatchedTarget(biome.id, edge));
       if (dispatched.has(edgeKey)) {
         throw new Error(
-          `biome "${biome.id}" dispatches runtime component "${edge.componentKey}" of biome "${edge.biomeId}" more than once`,
+          isSupplementalEdge(edge)
+            ? `biome "${biome.id}" dispatches ${edgeKey} more than once`
+            : `biome "${biome.id}" dispatches runtime component "${edge.componentKey}" of biome "${edge.biomeId}" more than once`,
         );
       }
       dispatched.add(edgeKey);

package/edition/oci-image-source-evidence.mjs

@@ -22,6 +22,9 @@ import {
 
 export const IMAGE_SOURCE_EVIDENCE_ARTIFACT_TYPE =
   'application/vnd.xema.image-source-evidence.v2';
+/** The E4 statement an edition artifact carries as an `oras attach` referrer (the catalogue's signed evidence). */
+export const EDITION_CATALOGUE_EVIDENCE_ARTIFACT_TYPE =
+  'application/vnd.xema.edition-catalogue-evidence.v1';
 export const OCI_IMAGE_MANIFEST_MEDIA_TYPE =
   'application/vnd.oci.image.manifest.v1+json';
 const OCI_TITLE_ANNOTATION = 'org.opencontainers.image.title';

package/edition/oras-process.mjs

@@ -8,16 +8,16 @@
 import { execFile } from 'node:child_process';
 
 /**
- * Run `file` with `args`; resolve with stdout bytes. A failure rejects with the
+ * Run `file` with `args` (in `cwd` when given); resolve with stdout bytes. A failure rejects with the
  * child's stderr text on `error.stderr` (a string), so the caller reads the
  * registry status from what oras itself wrote.
  */
-export function runExecutable(file, args, { input, env, timeoutMs, maxBufferBytes }) {
+export function runExecutable(file, args, { input, env, cwd, timeoutMs, maxBufferBytes }) {
   return new Promise((resolve, reject) => {
     const child = execFile(
       file,
       args,
-      { env, timeout: timeoutMs, maxBuffer: maxBufferBytes, encoding: 'buffer' },
+      { env, ...(cwd === undefined ? {} : { cwd }), timeout: timeoutMs, maxBuffer: maxBufferBytes, encoding: 'buffer' },
       (error, stdout, stderr) => {
         if (error) {
           error.stderr = stderr.toString('utf8');