@xemahq/xema 0.53.0 → 0.54.0

package/edition/develop-edition.mjs

@@ -2,9 +2,16 @@
 // develop-edition — the develop edition's command line.
 //
 //   resolve <id> --pins <file> --out <dir> --registry <root>
-//           --engine-image <repository>@sha256:<digest> [--local]
+//           --engine-repository <repository> --engine-signer <certificate identity> --cosign <absolute-path> [--local]
+//           [--images-from <image build record>]
 //       resolve the edition from the snapshot, seal it against the develop image
 //       repositories, write the descriptor and the four locks to <dir>, print the target.
+//       The engine is found and proven here (see `engine`), and every refusal of the run is reported
+//       in one table (develop-resolve-report.mjs): independent checks all run, a dependent one is
+//       reported `blocked by <check>`, and when anything is refused nothing is sealed or written.
+//       --images-from takes the digests from the everyday job's image build record instead of the registry probe:
+//       no probe and no rehash; satellite entries are cosign-verified against their producer's develop build
+//       records, and a subject missing, duplicated or extra in the record refuses (images-from-record.mjs).
 //       The workflow run is recorded from GITHUB_REPOSITORY / GITHUB_RUN_ID;
 //       --local stamps `local` instead, for a resolve outside GitHub Actions.
 //   resolve --definition <file> --pins <file> --out <dir> --registry <root>
@@ -16,10 +23,17 @@
 //       declares (`freeze-sources --definition` writes it); the catalogue digest is frozen into the descriptor's
 //       provenance pins as `catalogue`. The id is the definition's. Takes --data-root, --editions-root,
 //       --sources-root, --cache-dir (no --deploy-root, no --kernel: the kernel is the catalogue's, from npm).
-//   target  <id> --pins <file> --registry <root> --engine-image <repository>@sha256:<digest>
+//   engine  <id> --pins <file> --engine-repository <repository> --engine-signer <certificate identity> --cosign <absolute-path>
+//       print <repository>@sha256:<digest>: the engine xema-deploy CI published (tag sha-<12 hex>) for the
+//       snapshot's xema-deploy commit, its signature verified offline against the pinned trust root as made by
+//       --engine-signer with the signed annotations commit=<that commit> and branch=develop
+//       (develop-engine-image.mjs). The image `target` and `check-existing` take as --engine-image.
+//   target  <id> --pins <file> --registry <root> --engine-image <repository>@sha256:<digest> [--images-from <image build record>]
 //       print <root>/<develop segment>/xema-edition-<id>:<tag>, the tag being sha256 of the canonical
 //       { cli, engine, pins, sourceImages } (snapshotEditionTag): every input of the bytes the artifact records,
-//       so the same pins with another engine, source-image map or CLI version are another artifact. The root is always the caller's
+//       so the same pins with another engine, source-image map or CLI version are another artifact. With
+//       --images-from the record's digest (imageBuildRecordDigest) is one more input, named imageBuildRecord; resolve
+//       --images-from prints the same target. The root is always the caller's
 //       registry root (e.g. registry.example.com/acme); the develop namespace segment and the repository
 //       prefix come from edition-contract.json, and no root is implied.
 //   target  --definition <file> --pins <file> --registry <root> --engine-image <repository>@sha256:<digest>
@@ -92,11 +106,12 @@
 import { resolve } from 'node:path';
 
 import { writeCatalogue } from './catalogue.mjs';
-import { CUSTOMER_ROOTS, headResolver, parseEditionVerbArgs, runCustomerVerb, writeOnce } from './customer-edition-verbs.mjs';
+import { CUSTOMER_ROOTS, IMAGES_FROM_FLAG, headResolver, parseEditionVerbArgs, runCustomerVerb, writeOnce } from './customer-edition-verbs.mjs';
 import { DEFINITION_FLAG } from './customer-flags.mjs';
 import { runDevelopCoverage } from './develop-coverage-run.mjs';
 import { CoverageExit } from './develop-coverage.mjs';
 import { resolveDevelopEdition } from './develop-edition-resolve.mjs';
+import { resolveDevelopEngineImage } from './develop-engine-image.mjs';
 import { assertNoToolingOverride, freezeGraph, freezeSources } from './develop-freeze.mjs';
 import { runSelectRecords } from './develop-select-records.mjs';
 import { runVerifyImageRecord } from './develop-verify-image-record.mjs';
@@ -104,6 +119,7 @@ import { LOCAL_WORKFLOW, assertExistingArtifactMatches, developEditionTarget, wo
 import { EditionChannel, EditionKind } from './edition-constants.mjs';
 import { WorkspaceRoot, configureEditionWorkspaceFromProcess, isEntryModule, kernelRepoDir } from './edition-workspace.mjs';
 import { descriptorEvidenceTrust } from './evidence-trust-policy.mjs';
+import { createSatelliteVerifier, imageBuildRecordDigest, readImageBuildRecord } from './images-from-record.mjs';
 import { assertKernelCommitSupported, chooseKernelCommit } from './kernel-protocol-choice.mjs';
 import { loadKernelDistributionSchemas } from './lib.mjs';
 import { snapshotPinSource } from './pin-source.mjs';
@@ -150,21 +166,36 @@ function parseOverrides(text) {
   return parsed;
 }
 
+/** The target-tag input of `--images-from`: the record's digest, or nothing on the probe path. */
+function imageBuildRecordTagInput(options) {
+  return options[IMAGES_FROM_FLAG] === undefined ? {} : { imageBuildRecordDigest: imageBuildRecordDigest(readImageBuildRecord(options[IMAGES_FROM_FLAG])) };
+}
+
 async function run(argv, env) {
   const { command, id, options, customer } = parseDevelopEditionArgs(argv);
   switch (command) {
     case 'target': {
       if (customer) {return runCustomerVerb({ channel: EditionChannel.Develop, command, options, env });}
-      console.log(developEditionTarget(id, readStrictJsonFile(options['--pins']), { registry: options['--registry'], engineImage: options['--engine-image'] }));
+      console.log(developEditionTarget(id, readStrictJsonFile(options['--pins']), { registry: options['--registry'], engineImage: options['--engine-image'], ...imageBuildRecordTagInput(options) }));
       return;
     }
     case 'resolve': {
       if (customer) {return runCustomerVerb({ channel: EditionChannel.Develop, command, options, env });}
       const pins = readStrictJsonFile(options['--pins']);
       const workflow = options['--local'] ? LOCAL_WORKFLOW : workflowFromEnv(env);
-      const target = developEditionTarget(id, pins, { registry: options['--registry'], engineImage: options['--engine-image'] });
       const evidenceTrustPolicy = await descriptorEvidenceTrust({ kind: EditionKind.Resolved, channel: EditionChannel.Develop });
-      const { catalogue, ...resolved } = await resolveDevelopEdition({ id, pins, env });
+      const { catalogue, engineImage, ...resolved } = await resolveDevelopEdition({
+        id,
+        pins,
+        env,
+        engine: { repository: options['--engine-repository'], signer: options['--engine-signer'] },
+        cosignBinary: options['--cosign'],
+        ...(options[IMAGES_FROM_FLAG] === undefined ? {} : {
+          imagesFrom: readImageBuildRecord(options[IMAGES_FROM_FLAG]),
+          verifySatellites: createSatelliteVerifier({ registry: options['--registry'], cosignBinary: options['--cosign'], env }),
+        }),
+      });
+      const target = developEditionTarget(id, pins, { registry: options['--registry'], engineImage, ...imageBuildRecordTagInput(options) });
       const outDir = resolve(options['--out']);
       writeEditionArtifact({
         outDir,
@@ -173,13 +204,23 @@ async function run(argv, env) {
         pins,
         workflow,
         evidenceTrustPolicy,
-        engineImage: options['--engine-image'],
+        engineImage,
         ...resolved,
       });
       writeCatalogue(outDir, catalogue);
       console.log(target);
       return;
     }
+    case 'engine':
+      console.log(
+        await resolveDevelopEngineImage({
+          pins: readStrictJsonFile(options['--pins']),
+          engine: { repository: options['--engine-repository'], signer: options['--engine-signer'] },
+          cosignBinary: options['--cosign'],
+          env,
+        }),
+      );
+      return;
     case 'coverage':
       return runDevelopCoverage({
         id,

package/edition/develop-engine-image.mjs

@@ -0,0 +1,95 @@
+// develop-engine-image — the engine image a develop edition is deployed with, found and proven.
+//
+// The edition's engine is the one the deploy repository's CI published for EXACTLY the deploy commit the snapshot pins
+// (tag `sha-<12 hex>`, keyless signature by a `workflow_run` follower of a green push CI). The tag only finds the digest.
+// The signature is checked offline against the pinned trust root through the CLI's one cosign path (pinned-cosign.mjs)
+// with the publisher's EXACT identity, issuer, workflow repository and ref (cosign-certificate-constraints.mjs); never a
+// pattern. A follower runs the default branch's copy of the workflow, so the certificate's own workflow commit is not the
+// built one: the built commit is bound by the signed annotations commit=<40 hex> and branch=develop.
+// The digest is what the edition records.
+
+import { RefusalError } from './collected-refusals.mjs';
+import { certificateIdentityArgs } from './cosign-certificate-constraints.mjs';
+import { assertEngineImage } from './edition-artifact.mjs';
+import { assertPublisher, publisherIdentity } from './edition-publisher.mjs';
+import { deployPinKey } from './pin-source.mjs';
+import { cosignEnvironment, withPinnedCosign } from './pinned-cosign.mjs';
+import { splitImageRef } from './registry-credentials.mjs';
+import { isNotPublishedYet } from './seal-image-digests.mjs';
+import { GITHUB_ACTIONS_OIDC_ISSUER } from './third-party-source-evidence.mjs';
+
+const COMMIT_PATTERN = /^[a-f0-9]{40}$/;
+const TAG_PREFIX = 'sha-';
+const TAG_COMMIT_LENGTH = 12;
+const DEVELOP_BRANCH = 'develop';
+const STDERR_TAIL_BYTES = 800;
+
+/** The tag xema-deploy CI gives the engine it publishes for `deploySha`. */
+export const engineTagOf = (deploySha) => `${TAG_PREFIX}${deploySha.slice(0, TAG_COMMIT_LENGTH)}`;
+
+const IDENTITY_PATTERN = /^https:\/\/github\.com\/([^/@]+\/[^/@]+)\/(\.github\/workflows\/[^/@]+)@(.+)$/;
+
+/**
+ * The signer an exact certificate identity `https://github.com/<owner>/<name>/.github/workflows/<file>@<ref>` names, held to
+ * the publisher grammar of edition-contract.json (so no pattern, no wildcard).
+ */
+export function engineSignerOf(identity) {
+  const match = typeof identity === 'string' ? IDENTITY_PATTERN.exec(identity) : null;
+  if (match === null) {
+    throw new RefusalError(`--engine-signer must be the exact certificate identity https://github.com/<owner>/<name>/.github/workflows/<file>@<ref>; got ${JSON.stringify(identity)}`);
+  }
+  const publisher = assertPublisher({ repository: match[1], workflow: match[2], ref: match[3] }, '--engine-signer');
+  return { certificateIdentity: publisherIdentity(publisher), oidcIssuer: GITHUB_ACTIONS_OIDC_ISSUER, githubWorkflow: { repository: publisher.repository, ref: publisher.ref } };
+}
+
+const tail = (text) => String(text).trim().slice(-STDERR_TAIL_BYTES);
+
+/**
+ * @param {object} request
+ * @param {Record<string, string>} request.pins the snapshot's pins; the xema-deploy commit is read from them
+ * @param {{repository: string, signer: string}} request.engine the engine repository and the signer's exact certificate identity
+ * @param {string} request.cosignBinary absolute path of cosign
+ * @param {object} request.env the environment the registry credentials are named in
+ * @param {object} [request.pinned] withPinnedCosign's injections (tests)
+ * @returns {Promise<string>} `<repository>@sha256:<digest>`
+ */
+export async function resolveDevelopEngineImage({ pins, engine, cosignBinary, env, pinned = {} }) {
+  const deploySha = pins[deployPinKey()];
+  if (typeof deploySha !== 'string' || !COMMIT_PATTERN.test(deploySha)) {
+    throw new RefusalError(`the pin ${deployPinKey()} is ${JSON.stringify(deploySha)}, not a 40-hex commit`);
+  }
+  const { repository } = engine;
+  const signer = engineSignerOf(engine.signer);
+  const tag = engineTagOf(deploySha);
+  const { authority, repository: path } = splitImageRef(repository);
+  return withPinnedCosign({ cosignBinary, env, ...pinned }, async ({ runCosign, cosignEnvFor, clientFor, trustedRootPath }) => {
+    let digest;
+    try {
+      digest = (await clientFor(authority).getManifestByTag(path, tag)).digest;
+    } catch (error) {
+      if (!isNotPublishedYet(error)) {throw error;}
+      throw new RefusalError(
+        `no engine ${repository}:${tag} for the ${deployPinKey()} commit ${deploySha}. The deploy repository's CI publishes one for a green push to develop or main, ` +
+          'or a CI dispatch at that branch; a commit pushed with GITHUB_TOKEN has none until CI is dispatched. ' +
+          `Dispatch that CI at develop, or pin ${deployPinKey()} to a commit that has an engine.`,
+      );
+    }
+    const image = `${repository}@${digest}`;
+    const result = await runCosign(
+      [
+        'verify', '--offline', '--trusted-root', trustedRootPath,
+        ...certificateIdentityArgs(signer),
+        '-a', `commit=${deploySha}`, '-a', `branch=${DEVELOP_BRANCH}`,
+        image,
+      ],
+      cosignEnvironment(cosignEnvFor, authority),
+    );
+    if (result.code !== 0) {
+      throw new RefusalError(
+        `${image} (${tag}) is not signed by the engine signer ${signer.certificateIdentity} with commit=${deploySha} branch=${DEVELOP_BRANCH}; ` +
+          `refusing it as this edition's engine (cosign exit ${result.code}): ${tail(result.stderr)}`,
+      );
+    }
+    return assertEngineImage(image);
+  });
+}

package/edition/develop-image-probe.mjs

@@ -10,6 +10,7 @@
 // every missing coordinate. It verifies existence only: the platform check, the
 // digest decision and the size bounds stay in the seal, which still runs.
 
+import { RefusalError } from './collected-refusals.mjs';
 import { developImageRef } from './develop-image-coordinate.mjs';
 import { editionsRoot } from './edition-workspace.mjs';
 import { loadRegistryCredentialDeclarations, splitImageRef } from './registry-credentials.mjs';
@@ -28,7 +29,7 @@ export function notBuiltYetMessage(subject, channel = 'develop') {
 
 /** The ONE refusal naming every subject of `channel` (develop unless named) whose coordinate is absent. */
 export function notBuiltYetError(distributionId, missingSubjects, channel = 'develop') {
-  return new Error(
+  return new RefusalError(
     `${missingSubjects.length} ${channel} image(s) of "${distributionId}" are not built yet ` +
       "(the producer's CI is not green or still running):\n  " +
       missingSubjects.map((subject) => notBuiltYetMessage(subject, channel)).join('\n  '),

package/edition/develop-resolve-report.mjs

@@ -0,0 +1,159 @@
+import { isRefusal } from './collected-refusals.mjs';
+
+// develop-resolve-report — every refusal of one develop resolve, in one report.
+//
+// `xema edition develop resolve` runs a set of checks. A check that needs the output of another is a DEPENDENT of
+// it; every other check is independent. The collector runs each check, records a refusal instead of throwing it, and
+// skips (records as blocked) every check whose dependency was refused or blocked. `settle()` then throws ONE error whose
+// message is the table, so an operator sees what to fix, and who owns each fix, after a single run. Nothing is
+// downgraded: every refusal stays a refusal, and a run with a row writes nothing.
+
+/** The checks of a develop resolve, in the order the report lists them. */
+export const DevelopResolveCheck = Object.freeze({
+  EditionProtocol: 'edition-protocol',
+  DistributionLock: 'distribution-lock',
+  BundleSigner: 'bundle-signer',
+  PlaneInvariants: 'plane-invariants',
+  OperationAdmission: 'operation-admission',
+  AdapterBundles: 'adapter-bundles',
+  AuthorizationBase: 'authorization-base',
+  DevelopImages: 'develop-images',
+  EngineImage: 'engine-image',
+  ChartSet: 'chart-set',
+});
+
+/** Who fixes a refused check. */
+export const ResolveCheckOwner = Object.freeze({
+  Producer: 'producer (the repository the refusal names)',
+  XemaCli: 'xema-cli',
+  EditionOwner: 'edition-owner (the repository that declares the edition)',
+  DeployOwner: 'deploy-owner (the repository that builds the engine and the charts)',
+});
+
+export const RESOLVE_CHECK_OWNERS = Object.freeze({
+  [DevelopResolveCheck.EditionProtocol]: ResolveCheckOwner.XemaCli,
+  [DevelopResolveCheck.DistributionLock]: ResolveCheckOwner.EditionOwner,
+  [DevelopResolveCheck.BundleSigner]: ResolveCheckOwner.EditionOwner,
+  [DevelopResolveCheck.PlaneInvariants]: ResolveCheckOwner.EditionOwner,
+  [DevelopResolveCheck.OperationAdmission]: ResolveCheckOwner.Producer,
+  [DevelopResolveCheck.AdapterBundles]: ResolveCheckOwner.Producer,
+  [DevelopResolveCheck.AuthorizationBase]: ResolveCheckOwner.EditionOwner,
+  [DevelopResolveCheck.DevelopImages]: ResolveCheckOwner.Producer,
+  [DevelopResolveCheck.EngineImage]: ResolveCheckOwner.DeployOwner,
+  [DevelopResolveCheck.ChartSet]: ResolveCheckOwner.DeployOwner,
+});
+
+const C = DevelopResolveCheck;
+
+/**
+ * What each check needs verified before it runs: a check that consumes a predecessor's result is not run on the state a
+ * refused predecessor left behind, it is reported `blocked by` the refusal at the root.
+ * The checks that read the lock but consume no other check's verdict are independent of each other on purpose, so one run
+ * names all of them: the plane invariants (the graph), the operation admission (the lock's requirements) and the adapter
+ * bundles (the lock against the registry). The authorization base is composed from, and the images are hashed from, the
+ * lock AFTER those verified it. Chart set and engine image read only the pins.
+ */
+export const RESOLVE_CHECK_DEPENDENCIES = Object.freeze({
+  [C.EditionProtocol]: [],
+  [C.DistributionLock]: [C.EditionProtocol],
+  [C.BundleSigner]: [C.DistributionLock],
+  [C.PlaneInvariants]: [C.DistributionLock],
+  [C.OperationAdmission]: [C.DistributionLock],
+  [C.AdapterBundles]: [C.DistributionLock],
+  [C.AuthorizationBase]: [C.DistributionLock, C.BundleSigner, C.PlaneInvariants, C.OperationAdmission],
+  [C.DevelopImages]: [C.DistributionLock, C.BundleSigner, C.PlaneInvariants, C.OperationAdmission],
+  [C.EngineImage]: [],
+  [C.ChartSet]: [],
+});
+
+/** How a recorded check ended. */
+export const ResolveRowStatus = Object.freeze({ Refused: 'refused', Blocked: 'blocked' });
+
+/** What `run` returns for a check that did not produce a value: refused, or blocked by a dependency. */
+export const BLOCKED = Symbol('develop-resolve-blocked');
+
+const CHECK_ORDER = Object.values(DevelopResolveCheck);
+const COLUMNS = Object.freeze(['CHECK', 'OWNER', 'STATUS', 'DETAIL']);
+const DETAIL_INDENT = '    ';
+
+const statusOf = (row) => (row.status === ResolveRowStatus.Blocked ? `blocked by ${row.blockedBy}` : ResolveRowStatus.Refused);
+
+const NOTICE_HEADING = 'NOTICE: ungranted optional operations';
+
+/** The notices as one section: never a refusal, so it is separate from the table. Empty when there are none. */
+export const renderResolveNotices = (notices) =>
+  notices.length === 0 ? '' : [`${NOTICE_HEADING} (${notices.length})`, ...notices.map((notice) => `${DETAIL_INDENT}${notice}`)].join('\n');
+
+/** The report rows as one plain-text table, in the order of {@link DevelopResolveCheck}; a multi-line detail is indented under its row. */
+export function renderResolveReport(rows) {
+  const sorted = [...rows].sort((a, b) => CHECK_ORDER.indexOf(a.check) - CHECK_ORDER.indexOf(b.check));
+  const cells = sorted.map((row) => {
+    const [firstLine = '', ...more] = (row.detail ?? '').split('\n');
+    return { columns: [row.check, row.owner, statusOf(row), firstLine], more };
+  });
+  const widths = COLUMNS.slice(0, -1).map((name, i) => Math.max(name.length, ...cells.map((c) => c.columns[i].length)));
+  const line = (values) => [...values.slice(0, -1).map((v, i) => v.padEnd(widths[i])), values.at(-1)].join('  ').trimEnd();
+  const body = cells.flatMap(({ columns, more }) => [line(columns), ...more.map((m) => `${DETAIL_INDENT}${m}`.trimEnd())]);
+  return [`develop resolve refused: ${rows.length} check(s) did not pass; nothing was sealed or written`, line(COLUMNS), ...body].join('\n');
+}
+
+/** The one error of a develop resolve that had a refusal; `.rows` are the recorded rows, the message is the table. */
+export class DevelopResolveRefusedError extends Error {
+  constructor(rows, notices = []) {
+    super([renderResolveReport(rows), renderResolveNotices(notices)].filter((part) => part !== '').join('\n\n'));
+    this.name = 'DevelopResolveRefusedError';
+    this.rows = rows;
+    this.notices = notices;
+  }
+}
+
+export function createResolveReport() {
+  const rows = [];
+  const byCheck = new Map();
+  const notices = [];
+  const record = (row) => {
+    rows.push(row);
+    byCheck.set(row.check, row);
+  };
+
+  return {
+    rows,
+    notices,
+    /** Add one line to the NOTICE section; it never refuses and never changes the exit code. */
+    notice(line) {
+      notices.push(line);
+    },
+    /** The NOTICE section as text ('' when there is none). */
+    noticeText: () => renderResolveNotices(notices),
+    /**
+     * Run `fn` as `check`, unless a check it depends on was refused or blocked (it is then blocked by the root refusal).
+     * `classify(error)` may name another check the thrown error belongs to; that check is then the one refused,
+     * and `check` is blocked by it.
+     */
+    async run(check, dependsOn, fn, { classify = () => check } = {}) {
+      const blocker = dependsOn.map((dependency) => byCheck.get(dependency)).find((row) => row !== undefined);
+      if (blocker !== undefined) {
+        // Always the refusal at the root: a check blocked by a blocked check names the check that was refused.
+        const blockedBy = blocker.status === ResolveRowStatus.Blocked ? blocker.blockedBy : blocker.check;
+        record({ check, owner: RESOLVE_CHECK_OWNERS[check], status: ResolveRowStatus.Blocked, blockedBy });
+        return BLOCKED;
+      }
+      try {
+        return await fn();
+      } catch (error) {
+        // A defect (a TypeError, a failed system call, a registry answering 5xx) is not a refusal: it propagates as thrown.
+        if (!isRefusal(error)) {throw error;}
+        const filedUnder = classify(error);
+        record({ check: filedUnder, owner: RESOLVE_CHECK_OWNERS[filedUnder], status: ResolveRowStatus.Refused, detail: error.message, error });
+        if (filedUnder !== check) {
+          record({ check, owner: RESOLVE_CHECK_OWNERS[check], status: ResolveRowStatus.Blocked, blockedBy: filedUnder });
+        }
+        return BLOCKED;
+      }
+    },
+    /** Throw the one error when any check was refused or blocked. */
+    settle() {
+      if (rows.length > 0) {throw new DevelopResolveRefusedError(rows, notices);}
+    },
+  };
+}

package/edition/develop-snapshot-inputs.mjs

@@ -17,6 +17,7 @@
 
 import { execFileSync } from 'node:child_process';
 
+import { RefusalError } from './collected-refusals.mjs';
 import { dataRoot, deployRoot, editionsRoot, kernelRepoDir, runtimeImageSourceIndexPath } from './edition-workspace.mjs';
 import { buildIndexesAtPins } from './indexes-at-pins.mjs';
 import {
@@ -45,14 +46,14 @@ function git(dir, args) {
  */
 export function assertFrozenCheckout({ dir, pins, key }) {
   const pinned = pins[key];
-  if (pinned === undefined) {throw new Error(`the snapshot has no pin "${key}" for ${dir}`);}
+  if (pinned === undefined) {throw new RefusalError(`the snapshot has no pin "${key}" for ${dir}`);}
   const head = git(dir, ['rev-parse', 'HEAD']);
   if (head !== pinned) {
-    throw new Error(`${dir} is at ${head}, but the snapshot pins "${key}" at ${pinned}`);
+    throw new RefusalError(`${dir} is at ${head}, but the snapshot pins "${key}" at ${pinned}`);
   }
   const dirty = git(dir, ['status', '--porcelain']);
   if (dirty.length > 0) {
-    throw new Error(`${dir} is not clean, so it is not the frozen commit ${pinned} ("${key}"):\n${dirty}`);
+    throw new RefusalError(`${dir} is not clean, so it is not the frozen commit ${pinned} ("${key}"):\n${dirty}`);
   }
 }
 

package/edition/develop-verify-image-record.mjs

@@ -58,8 +58,28 @@ function producerMember(producer) {
  * @param {string} request.registry the registry root that holds `build-records/<repo>`
  * @returns {Promise<{image: string, digest: string, producer: string, commit: string}>}
  */
-export async function verifyImageRecord({ image, producer, registry, dataRootRepositoryUrl, kernel, clientFor, runCosign, cosignEnvFor, trustedRootPath }) {
+export async function verifyImageRecord({ image, producer, ...verifier }) {
   const { name, digest } = parseImageReference(image);
+  const record = await findVerifiedProducerImageRecord({
+    producer,
+    ...verifier,
+    wanted: `lists ${name}@${digest}`,
+    matches: (candidate) => candidate.images.some((listed) => listed.name === name && listed.digest === digest),
+  });
+  return { image: name, digest, producer, commit: record.commit };
+}
+
+/**
+ * The newest verified develop ci.yaml record of `producer` (newest run first) for which `matches(record)` holds.
+ * Every record read on the way is cosign-verified, so a newer bad record refuses before an older one is read.
+ * Refused, naming `wanted`, when no verified ci.yaml record matches.
+ *
+ * @param {object} request
+ * @param {string} request.producer `<owner>/<repo>`
+ * @param {(record: object) => boolean} request.matches
+ * @param {string} request.wanted what a match is, for the refusal ("lists <name>@<digest>")
+ */
+export async function findVerifiedProducerImageRecord({ producer, matches, wanted, registry, dataRootRepositoryUrl, kernel, clientFor, runCosign, cosignEnvFor, trustedRootPath }) {
   const member = producerMember(producer);
   const branch = VERIFY_IMAGE_RECORD_BRANCH;
   const { repository, authority, client, runs } = await listBuildRecordRuns({ kernel, clientFor, registry, member, branch });
@@ -69,10 +89,9 @@ export async function verifyImageRecord({ image, producer, registry, dataRootRep
       repository, member, branch, dataRootRepositoryUrl, tag,
     });
     if (record.producer.workflow !== PRODUCER_IMAGE_WORKFLOW) {continue;}
-    if (!record.images.some((listed) => listed.name === name && listed.digest === digest)) {continue;}
-    return { image: name, digest, producer, commit: record.commit };
+    if (matches(record)) {return record;}
   }
-  throw new RecordRefused(producer, `no verified ${PRODUCER_IMAGE_WORKFLOW} build record of ${repository} for branch ${branch} lists ${name}@${digest}`);
+  throw new RecordRefused(producer, `no verified ${PRODUCER_IMAGE_WORKFLOW} build record of ${repository} for branch ${branch} ${wanted}`);
 }
 
 /** The `verify-image-record` verb. */

package/edition/edition-artifact.mjs

@@ -290,7 +290,7 @@ export function canonicalSourceImages(sourceImages = new Map()) {
 }
 
 /**
- * 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 tag of an edition resolved from a snapshot (a develop edition, a customer release edition): sha256 of the canonical `{ cli, engine, pins, sourceImages }`, plus `imageBuildRecord` (the record's digest) for a develop resolve --images-from. 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
@@ -300,25 +300,35 @@ export function canonicalSourceImages(sourceImages = new Map()) {
  * 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 snapshotEditionTag({ pins, engineImage, sourceImages = new Map(), version = cliVersion() }) {
+export function snapshotEditionTag({ pins, engineImage, sourceImages = new Map(), imageBuildRecordDigest, version = cliVersion() }) {
   return sha256Hex(
     serializeJson({
       cli: version,
       engine: assertEngineImage(engineImage),
       pins: sortedSnapshotPins(pins),
       sourceImages: canonicalSourceImages(sourceImages),
+      // A develop resolve from an image build record (--images-from): the record fixes the image rows, and a satellite
+      // digest changes independently of the pins. Absent on the probe path, whose tag inputs are unchanged.
+      ...(imageBuildRecordDigest === undefined ? {} : { imageBuildRecord: assertImageBuildRecordDigest(imageBuildRecordDigest) }),
     }),
   );
 }
 
+function assertImageBuildRecordDigest(digest) {
+  if (typeof digest !== 'string' || !/^[0-9a-f]{64}$/.test(digest)) {
+    throw new Error(`an image build record digest must be 64 lowercase hex; got ${JSON.stringify(digest)}`);
+  }
+  return digest;
+}
+
 /** 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 }));
+export function snapshotEditionTarget(channel, distributionId, pins, { registry, engineImage, sourceImages, imageBuildRecordDigest }) {
+  return editionTarget(distributionId, registry, channel, snapshotEditionTag({ pins, engineImage, sourceImages, imageBuildRecordDigest }));
 }
 
-/** 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 snapshotEditionTarget(EditionChannel.Develop, distributionId, pins, { registry, engineImage, sourceImages });
+/** A develop edition's target: the tag is `snapshotEditionTag` of the pins, the engine, the source images and any image build record. */
+export function developEditionTarget(distributionId, pins, { registry, engineImage, sourceImages, imageBuildRecordDigest }) {
+  return snapshotEditionTarget(EditionChannel.Develop, distributionId, pins, { registry, engineImage, sourceImages, imageBuildRecordDigest });
 }
 
 function realpathOfPlanned(path) {

package/edition/edition-protocol.mjs

@@ -26,6 +26,7 @@
 
 import { realpathSync } from 'node:fs';
 
+import { RefusalError } from './collected-refusals.mjs';
 import { readBoundedNoFollowFile } from './no-follow-file.mjs';
 
 /** The edition protocols this library interprets: version -> content digest. A protocol is listed only
@@ -35,7 +36,7 @@ import { readBoundedNoFollowFile } from './no-follow-file.mjs';
  * bundle-signer protocol (`bundleSigner` on every OCI bundle row); v34 is the kernel's output-mapping, JSON Pointer and
  * handoff-repair-turns closure additions (XEMA-2122); v35 is the kernel's independent releases on a resolved deployment (XEMA-2244);
  * v36 is the kernel's JobFailureReason workflow closure addition (XEMA-2282);
- * v37 is the kernel's DistributionLock.catalogueContentDigest and effective-timeout wording (XEMA-2254, XEMA-2282); v38 is the kernel's optionalPeers service-manifest field (XEMA-2315); v33 to v38 are not yet published: their identities and contracts are captured from the
+ * v37 is the kernel's DistributionLock.catalogueContentDigest and effective-timeout wording (XEMA-2254, XEMA-2282); v38 is the kernel's optionalPeers service-manifest field (XEMA-2315); v39 admits an optional operation on an undeclared domain as ungranted (`owner-undeclared`, TEAM-1 EDR-2); v40 is the kernel's resource `sharing` field (owner or shared; one owner row per resource); v33 to v39 are not yet published: their identities and contracts are captured from the
  * linked kernel), so v29 is not listed either. */
 export const SUPPORTED_EDITION_PROTOCOLS = Object.freeze([
   Object.freeze({ version: 28, contentDigest: 'f7795478b1bfe9a41bcbea9efe496011fcd209a56c90294029a08801e84cf92c' }),
@@ -48,6 +49,8 @@ export const SUPPORTED_EDITION_PROTOCOLS = Object.freeze([
   Object.freeze({ version: 36, contentDigest: 'b6b0c8ec3fc4182c6c3b623685af6293cfed1321f8d7c1891a83652d864c3df0' }),
   Object.freeze({ version: 37, contentDigest: 'f10adca1ca5b6f51f3971756261032eeddd60e372ebfcff06a2a9d8a796d0fef' }),
   Object.freeze({ version: 38, contentDigest: 'f670cb922c989fd40ac03703a612e7a6df2937233a1a20a394a859ec835d47d4' }),
+  Object.freeze({ version: 39, contentDigest: 'b2159ede1755526cb63b6c533bc00caaead8151784864caf1a4d682281f47808' }),
+  Object.freeze({ version: 40, contentDigest: 'e26613bfccc87e2ccc0d94ac2c412cc35d1f48f48559bb8d0606f14d499db528' }),
 ]);
 
 /** Where a kernel package publishes its identity and its contract, package-relative. */
@@ -86,7 +89,7 @@ export const EditionProtocolMismatchReason = Object.freeze({
   NotOnDevelop: 'not-on-develop',
 });
 
-export class EditionProtocolMismatchError extends Error {
+export class EditionProtocolMismatchError extends RefusalError {
   constructor(reason, message) {
     super(message);
     this.name = 'EditionProtocolMismatchError';