@xemahq/xema 0.53.0 → 0.55.0

package/edition/check-committed-image-evidence.mjs

@@ -66,6 +66,7 @@ import {
   evidenceDirectoryForDigest,
   sha256Digest,
 } from './image-evidence.mjs';
+import { evidenceSubjectKey } from './image-subject-identity.mjs';
 import { loadKernelDistributionSchemas } from './lib.mjs';
 import {
   assertProducerInput,
@@ -124,6 +125,29 @@ function assertContainedRelativePath(value, label) {
  *
  * @returns {{ evidenceDirectory: string, reusable: boolean, reason: string }}
  */
+/**
+ * The key of an index entry: its subject's evidence identity, which for a composed artifact names the generation, so it is read
+ * from the statement the entry points at (the index states only kind and id). An entry whose statement cannot be read keeps
+ * `kind\0id`; the unusable statement is reported below.
+ */
+export function entryKey(entry, absoluteDirectory) {
+  try {
+    const { predicate } = JSON.parse(
+      readBoundedFile(join(absoluteDirectory, assertContainedRelativePath(entry.evidence.statementPath, 'statementPath'))).toString('utf8'),
+    );
+    return evidenceSubjectKey({
+      kind: entry.subjectKind,
+      id: entry.subjectId,
+      imageRef: predicate.artifact.imageRepository,
+      contentHash: predicate.source.sourceTreeHash,
+    });
+  } catch {
+    return `${entry.subjectKind}\0${entry.subjectId}`;
+  }
+}
+
+const printable = (key) => key.replaceAll('\0', ':');
+
 export async function assessCommittedEvidence({
   input,
   repositoryRoot,
@@ -190,7 +214,12 @@ export async function assessCommittedEvidence({
   }
   const expectedByKey = new Map(
     expectedStatements.map((statement) => [
-      `${statement.predicate.source.kind}:${statement.predicate.source.id}`,
+      evidenceSubjectKey({
+        kind: statement.predicate.source.kind,
+        id: statement.predicate.source.id,
+        imageRef: statement.predicate.artifact.imageRepository,
+        contentHash: statement.predicate.source.sourceTreeHash,
+      }),
       statement,
     ]),
   );
@@ -200,20 +229,20 @@ export async function assessCommittedEvidence({
     if (entry === null || typeof entry !== 'object') {
       return unusable('producer-evidence.json carries a non-object entry');
     }
-    const key = `${entry.subjectKind}:${entry.subjectId}`;
+    const key = entryKey(entry, absoluteDirectory);
     if (seen.has(key)) {
-      return unusable(`producer-evidence.json duplicates subject ${key}`);
+      return unusable(`producer-evidence.json duplicates subject ${printable(key)}`);
     }
     seen.add(key);
     const expected = expectedByKey.get(key);
     if (expected === undefined) {
       return unusable(
-        `committed evidence carries subject ${key}, which this input does not evidence`,
+        `committed evidence carries subject ${printable(key)}, which this input does not evidence`,
       );
     }
     const descriptor = entry.evidence;
     if (descriptor === null || typeof descriptor !== 'object') {
-      return unusable(`subject ${key} has no evidence descriptor`);
+      return unusable(`subject ${printable(key)} has no evidence descriptor`);
     }
     let statementBytes;
     let bundleBytes;
@@ -223,7 +252,7 @@ export async function assessCommittedEvidence({
           absoluteDirectory,
           assertContainedRelativePath(
             descriptor.statementPath,
-            `subject ${key} statementPath`,
+            `subject ${printable(key)} statementPath`,
           ),
         ),
       );
@@ -232,25 +261,25 @@ export async function assessCommittedEvidence({
           absoluteDirectory,
           assertContainedRelativePath(
             descriptor.bundlePath,
-            `subject ${key} bundlePath`,
+            `subject ${printable(key)} bundlePath`,
           ),
         ),
       );
     } catch (error) {
-      return unusable(`subject ${key} artifacts are unreadable: ${error.message}`);
+      return unusable(`subject ${printable(key)} artifacts are unreadable: ${error.message}`);
     }
     if (
       sha256Digest(statementBytes) !== descriptor.statementDigest ||
       sha256Digest(bundleBytes) !== descriptor.bundleDigest
     ) {
       return unusable(
-        `subject ${key} artifacts do not match the digests producer-evidence.json records`,
+        `subject ${printable(key)} artifacts do not match the digests producer-evidence.json records`,
       );
     }
     try {
       validateProducedBundle(statementBytes, bundleBytes);
     } catch (error) {
-      return unusable(`subject ${key} bundle is malformed: ${error.message}`);
+      return unusable(`subject ${printable(key)} bundle is malformed: ${error.message}`);
     }
     let committed;
     try {
@@ -259,7 +288,7 @@ export async function assessCommittedEvidence({
       );
     } catch (error) {
       return unusable(
-        `subject ${key} statement does not parse under the kernel schema: ${error.message}`,
+        `subject ${printable(key)} statement does not parse under the kernel schema: ${error.message}`,
       );
     }
     // producerRun is deliberately fresh on every execution (run id, attempt,
@@ -269,24 +298,24 @@ export async function assessCommittedEvidence({
     // validate the existing run's own signature and lifetime independently.
     if (!producerStatementMatchesInput(committed, expected)) {
       return unusable(
-        `subject ${key} committed statement is not bound to this producer input ` +
+        `subject ${printable(key)} committed statement is not bound to this producer input ` +
           '(authority, source, build, artifact or platform set changed)',
       );
     }
     const expiresAt = Date.parse(committed.predicate.producerRun.expiresAt);
     if (!Number.isFinite(expiresAt)) {
-      return unusable(`subject ${key} statement has an unreadable expiresAt`);
+      return unusable(`subject ${printable(key)} statement has an unreadable expiresAt`);
     }
     const remainingSeconds = Math.floor((expiresAt - now) / 1000);
     if (remainingSeconds <= 0) {
       return unusable(
-        `subject ${key} evidence EXPIRED at ${committed.predicate.producerRun.expiresAt} — ` +
+        `subject ${printable(key)} evidence EXPIRED at ${committed.predicate.producerRun.expiresAt} — ` +
           'it can never verify again and must be re-produced',
       );
     }
     if (remainingSeconds < MIN_REMAINING_TTL_SECONDS) {
       return unusable(
-        `subject ${key} evidence expires in ${remainingSeconds}s, under the ` +
+        `subject ${printable(key)} evidence expires in ${remainingSeconds}s, under the ` +
           `${MIN_REMAINING_TTL_SECONDS}s reuse floor — refreshing it now`,
       );
     }

package/edition/checkout-indexed-source-repositories.mjs

@@ -11,6 +11,7 @@ import { readEditionSourcePins } from './edition-source-pins.mjs';
 import { WorkspaceRoot, configureEditionWorkspaceFromProcess, configuredWorkspace, editionsRoot, isEntryModule, platformServiceIndexPath, runtimeImageSourceIndexPath, sourcesRoot } from './edition-workspace.mjs';
 import { holdSource, withSourceGitEnv } from './git-source-auth.mjs';
 import { applyPinSource, snapshotPinSource } from './pin-source.mjs';
+import { shallowCheckout, shallowFetch } from './shallow-checkout.mjs';
 import { readStrictJsonFile } from './strict-json.mjs';
 
 const REPO_PATH = /^(repos|submodules)\/([a-z0-9][a-z0-9-]*)$/;
@@ -188,7 +189,7 @@ export function fetchCrossRepoVendoredCommits({ workspaceRoot, plan, index, work
     if (!commits) {continue;}
     withSourceGitEnv({ name: entry.repo, url: entry.repositoryUrl }, { workspace, env }, (gitEnv) => {
       for (const commit of commits) {
-        runGit(['-C', resolve(workspaceRoot, entry.repo), 'fetch', '--quiet', '--depth=1', 'origin', commit], gitEnv);
+        shallowFetch({ runGit, gitEnv, target: resolve(workspaceRoot, entry.repo), commit });
         console.log(`[source-checkout] ${entry.repo} also holds cross-repo vendored commit ${commit}`);
       }
     });
@@ -210,10 +211,7 @@ export function checkoutIndexedSources({ workspaceRoot, index, platformServiceIn
     }
     withSourceGitEnv({ name: entry.repo, url: entry.repositoryUrl }, { workspace, env }, (gitEnv) => {
       mkdirSync(dirname(target), { recursive: true });
-      runGit(['init', '--quiet', target], gitEnv);
-      runGit(['-C', target, 'remote', 'add', 'origin', entry.repositoryUrl], gitEnv);
-      runGit(['-C', target, 'fetch', '--quiet', '--depth=1', 'origin', entry.sourceCommit], gitEnv);
-      runGit(['-C', target, 'checkout', '--quiet', '--detach', entry.sourceCommit], gitEnv);
+      shallowCheckout({ runGit, gitEnv, target, url: entry.repositoryUrl, commit: entry.sourceCommit });
       const actual = execFileSync('git', ['-C', target, 'rev-parse', 'HEAD'], {
         env: gitEnv,
         encoding: 'utf8',
@@ -223,11 +221,11 @@ export function checkoutIndexedSources({ workspaceRoot, index, platformServiceIn
       }
       if (sourceAxisCommits.has(entry.repo)) {
         const commit = sourceAxisCommits.get(entry.repo);
-        runGit(['-C', target, 'fetch', '--quiet', '--depth=1', 'origin', commit], gitEnv);
+        shallowFetch({ runGit, gitEnv, target, commit });
         console.log(`[source-checkout] ${entry.repo} also holds source-axis commit ${commit}`);
       }
       for (const commit of extraCommits.get(entry.repo) ?? []) {
-        runGit(['-C', target, 'fetch', '--quiet', '--depth=1', 'origin', commit], gitEnv);
+        shallowFetch({ runGit, gitEnv, target, commit });
         console.log(`[source-checkout] ${entry.repo} also holds platform-service commit ${commit}`);
       }
       // A repository an edition holds: its main history (containment in origin/main is checked from it,
@@ -235,7 +233,7 @@ export function checkoutIndexedSources({ workspaceRoot, index, platformServiceIn
       if (heldCommits.has(entry.repo)) {
         runGit(['-C', target, 'fetch', '--quiet', 'origin', '+refs/heads/main:refs/remotes/origin/main'], gitEnv);
         for (const commit of heldCommits.get(entry.repo)) {
-          runGit(['-C', target, 'fetch', '--quiet', '--depth=1', 'origin', commit], gitEnv);
+          shallowFetch({ runGit, gitEnv, target, commit });
           console.log(`[source-checkout] ${entry.repo} also holds edition-held commit ${commit}`);
         }
       }

package/edition/collected-refusals.mjs

@@ -0,0 +1,59 @@
+// The one rule for a check that runs every independent assertion before it refuses.
+//
+// A REFUSAL is the answer "no" to the input: a lock the data does not admit, a commit that is not pinned, an image that is
+// not built. It is a `RefusalError` and is collected so one run names them all. Anything else is a DEFECT (a TypeError, a
+// missing file, a registry that answered 5xx, an unnamed Error): it is never collected, never reported as a refusal, and
+// propagates unchanged with its stack.
+//
+// Nothing refused returns; exactly one refusal is rethrown unchanged (its type and message are the contract of whoever
+// catches it); several become ONE error of the caller's class that joins their messages and keeps them as `.errors`.
+
+/** An error that is a REFUSAL of the input. Extend it for a named refusal; throw it directly for an unnamed one. */
+export class RefusalError extends Error {}
+
+/** The kernel's own bundle-signer refusals, named as the kernel names them (their classes load lazily from the built kernel). */
+export const KernelRefusalName = Object.freeze({
+  UnknownPolicy: 'LockedBundleSignerUnknownPolicyError',
+  AmbiguousPolicy: 'LockedBundleSignerAmbiguousPolicyError',
+  Mismatch: 'LockedBundleSignerMismatchError',
+});
+const KERNEL_REFUSAL_NAMES = new Set(Object.values(KernelRefusalName));
+
+/** Whether a thrown value is a refusal. Everything else (a TypeError, a failed system call, an unnamed Error) is a defect. */
+export const isRefusal = (error) => error instanceof RefusalError || (error instanceof Error && KERNEL_REFUSAL_NAMES.has(error.name));
+
+/** Run `fn`; a refusal is pushed on `errors` and `undefined` returned, anything else is rethrown unchanged. */
+export function captureRefusal(errors, fn, refusal) {
+  try {
+    return fn();
+  } catch (error) {
+    if (!refusal(error)) {throw error;}
+    errors.push(error);
+    return undefined;
+  }
+}
+
+/**
+ * Run `fn` on every item, keeping each refusal, then refuse once all were seen: one refusal is rethrown unchanged, several
+ * are one `CollectedError(errors)`. A defect stops the run at once and is rethrown as it was thrown.
+ *
+ * @param {Iterable<T>} items
+ * @param {(item: T) => void} fn
+ * @param {(error: unknown) => boolean} refusal which thrown values are refusals (`isRefusal`)
+ * @param {new (errors: readonly Error[]) => Error} CollectedError the class that carries several
+ */
+export function collectRefusals(items, fn, refusal, CollectedError) {
+  const errors = [];
+  for (const item of items) {captureRefusal(errors, () => fn(item), refusal);}
+  throwCollectedRefusals(errors, CollectedError);
+}
+
+/** Nothing collected returns, one is rethrown unchanged, several become one `CollectedError`. */
+export function throwCollectedRefusals(errors, CollectedError) {
+  if (errors.length === 0) {return;}
+  if (errors.length === 1) {throw errors[0];}
+  throw new CollectedError(errors);
+}
+
+/** The message of an error that stands for several: each refusal's message, separated by a blank line. */
+export const joinRefusalMessages = (errors) => errors.map((error) => error.message).join('\n\n');

package/edition/contract-authority.mjs

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+// `xema edition contract-authority`: the full kernel contract authority of the `@xemahq/contracts` this CLI
+// ships, as canonical JSON on stdout — the `--contract-authority <file>` a third-party publisher's public-input
+// run passes (Third-party sources, README).
+//
+// usage: xema edition contract-authority
+// stdout: the KernelContractAuthority object, canonical JSON, one line.
+//
+// The kernel's release derives the object at publish time, `sourceCommit` = the commit as the kernel release states it (carried, never proven here: only contentDigest and
+// sourcePaths are proven against the package), and ships
+// it as `dist/edition-protocol/contract-authority.json` (exported by name). This verb resolves that export from
+// this CLI's own resolution, parses it with the kernel's KernelContractAuthoritySchema, refuses it unless its
+// contentDigest is the bundled kernel's edition protocol digest, and then proves the bundled package IS that
+// authority (assertKernelPackageIsCatalogueAuthority). It fails closed: a kernel with no file (a dev build, or a
+// release older than the file) is refused by name, with no fallback to any derived or remembered authority.
+
+import { readFileSync, realpathSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { sep } from 'node:path';
+
+import { KernelContractAuthoritySchema } from '@xemahq/contracts/distribution';
+
+import { canonicalJson } from './canonical-evidence-json.mjs';
+import { readKernelEditionProtocol } from './edition-protocol.mjs';
+import { configureEditionWorkspaceFromArgv, isEntryModule, stateKernelPackageDir } from './edition-workspace.mjs';
+import { KERNEL_PACKAGE_NAME, assertKernelPackageIsCatalogueAuthority, shippedKernelPackageDir } from './kernel-package.mjs';
+import { loadKernelDistributionSchemas } from './lib.mjs';
+
+export const CONTRACT_AUTHORITY_EXPORT = '@xemahq/contracts/edition-protocol/contract-authority.json';
+export const CONTRACT_AUTHORITY_USAGE = 'usage: xema edition contract-authority';
+
+export class BundledContractAuthorityError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'BundledContractAuthorityError';
+  }
+}
+
+const ownRequire = createRequire(import.meta.url);
+
+/**
+ * The ONE refusal of a kernel that carries no contract-authority.json, for the verb and for every edition test
+ * fixture that reads the authority through this module: the file is emitted only at release, so a dev build (an
+ * aggregator-linked kernel) never carries one, by design.
+ */
+function missingContractAuthority(kernelDir, detail) {
+  return new BundledContractAuthorityError(
+    `the ${KERNEL_PACKAGE_NAME} at ${kernelDir} carries no edition-protocol/contract-authority.json (${detail}): the file is emitted ` +
+      `only at release, so a dev build of the kernel never has one. The verb, and the edition evidence tests, need a published ` +
+      `${KERNEL_PACKAGE_NAME} (install a released @xemahq/xema, or run the tests against the published kernel the CLI's lockfile installs)`,
+  );
+}
+
+/** The bundled kernel's contract-authority.json, resolved by its package export from this CLI's own resolution. */
+export function resolveBundledContractAuthorityFile({ resolve = (specifier) => ownRequire.resolve(specifier), kernelDir = shippedKernelPackageDir() } = {}) {
+  try {
+    return resolve(CONTRACT_AUTHORITY_EXPORT);
+  } catch (error) {
+    if (error?.code !== 'MODULE_NOT_FOUND' && error?.code !== 'ERR_PACKAGE_PATH_NOT_EXPORTED') {throw error;}
+    throw missingContractAuthority(kernelDir, error.code);
+  }
+}
+
+/**
+ * Read, parse and prove the contract authority at `file` against the kernel package at `kernelDir`: the file must
+ * be inside that package, parse as KernelContractAuthoritySchema, carry the package's edition protocol digest, and
+ * the package must be that authority. Returns the parsed authority.
+ */
+export async function readBundledContractAuthority({
+  kernelDir = shippedKernelPackageDir(),
+  file = resolveBundledContractAuthorityFile({ kernelDir }),
+  loadSchemas = loadKernelDistributionSchemas,
+} = {}) {
+  let real;
+  try {
+    real = realpathSync(file);
+  } catch (error) {
+    if (error?.code === 'ENOENT') {throw missingContractAuthority(kernelDir, `${file} does not exist`);}
+    throw new BundledContractAuthorityError(`${file} cannot be read: ${error.message}`);
+  }
+  if (!real.startsWith(`${realpathSync(kernelDir)}${sep}`)) {
+    throw new BundledContractAuthorityError(`${real} is not inside the kernel package this CLI ships (${kernelDir})`);
+  }
+  let raw;
+  try {
+    raw = JSON.parse(readFileSync(real, 'utf8'));
+  } catch (error) {
+    throw new BundledContractAuthorityError(`${real} is not JSON: ${error.message}`);
+  }
+  const parsed = KernelContractAuthoritySchema.safeParse(raw);
+  if (!parsed.success) {
+    const issues = parsed.error.issues.map((issue) => `${issue.path.join('.') || '(root)'}: ${issue.message}`).join('; ');
+    throw new BundledContractAuthorityError(`${real} is not a kernel contract authority: ${issues}`);
+  }
+  const authority = parsed.data;
+  const bundledDigest = readKernelEditionProtocol(kernelDir).contentDigest;
+  if (authority.contentDigest !== bundledDigest) {
+    throw new BundledContractAuthorityError(
+      `${real} states contentDigest ${authority.contentDigest}, but the bundled kernel's edition protocol digest is ${bundledDigest}`,
+    );
+  }
+  await assertKernelPackageIsCatalogueAuthority({ catalogue: { contractAuthority: authority }, kernelPackageDir: kernelDir, loadSchemas });
+  return authority;
+}
+
+async function main() {
+  const rest = configureEditionWorkspaceFromArgv(process.argv.slice(2), [], { refuseOthers: true });
+  if (rest.length > 0) {throw new Error(CONTRACT_AUTHORITY_USAGE);}
+  const kernelDir = shippedKernelPackageDir();
+  stateKernelPackageDir(kernelDir);
+  const authority = await readBundledContractAuthority({ kernelDir });
+  process.stdout.write(`${canonicalJson(authority)}\n`);
+}
+
+if (isEntryModule(import.meta.url)) {
+  try {
+    await main();
+  } catch (error) {
+    console.error(`[contract-authority] ${error.message}`);
+    process.exitCode = 1;
+  }
+}

package/edition/cosign-certificate-constraints.mjs

@@ -14,17 +14,17 @@ function requireText(value, what) {
 }
 
 /**
+ * The flags that pin a signer's exact identity, issuer, workflow repository and ref. They carry no workflow commit: use
+ * {@link certificateConstraintArgs} unless the signing workflow's own commit is, by design, not known to the verifier (a
+ * `workflow_run` follower runs the default branch's copy), and then bind the built commit by a signed annotation.
+ *
  * @param {{ certificateIdentity: string, oidcIssuer: string, githubWorkflow: { repository: string, ref: string } }} signer
- * @param {string} workflowSha the 40-hex commit the signing workflow ran at
- * @returns {string[]} the cosign flags that pin identity, issuer, workflow repository, ref and sha
+ * @returns {string[]}
  */
-export function certificateConstraintArgs(signer, workflowSha) {
+export function certificateIdentityArgs(signer) {
   if (signer === null || typeof signer !== 'object') {
     throw new Error('certificate constraints: the signer must be an object');
   }
-  if (typeof workflowSha !== 'string' || !WORKFLOW_SHA.test(workflowSha)) {
-    throw new Error(`certificate constraints: the workflow sha must be 40 lowercase hex characters; got ${JSON.stringify(workflowSha)}`);
-  }
   return [
     '--certificate-identity',
     requireText(signer.certificateIdentity, 'certificateIdentity'),
@@ -34,7 +34,17 @@ export function certificateConstraintArgs(signer, workflowSha) {
     requireText(signer.githubWorkflow?.repository, 'githubWorkflow.repository'),
     '--certificate-github-workflow-ref',
     requireText(signer.githubWorkflow?.ref, 'githubWorkflow.ref'),
-    '--certificate-github-workflow-sha',
-    workflowSha,
   ];
 }
+
+/**
+ * @param {{ certificateIdentity: string, oidcIssuer: string, githubWorkflow: { repository: string, ref: string } }} signer
+ * @param {string} workflowSha the 40-hex commit the signing workflow ran at
+ * @returns {string[]} the cosign flags that pin identity, issuer, workflow repository, ref and sha
+ */
+export function certificateConstraintArgs(signer, workflowSha) {
+  if (typeof workflowSha !== 'string' || !WORKFLOW_SHA.test(workflowSha)) {
+    throw new Error(`certificate constraints: the workflow sha must be 40 lowercase hex characters; got ${JSON.stringify(workflowSha)}`);
+  }
+  return [...certificateIdentityArgs(signer), '--certificate-github-workflow-sha', workflowSha];
+}

package/edition/customer-edition-verbs.mjs

@@ -178,25 +178,44 @@ export function customerRootsOf(command) {
 // customer form: the flags only it takes, the further flags it requires, and the vendor flags it refuses.
 const CREDENTIAL_FLAGS = Object.freeze([CATALOGUE_USERNAME_FLAG, CATALOGUE_TOKEN_ENV_FLAG]);
 const REPEATABLE = Object.freeze([SOURCE_IMAGE_FLAG]);
+// A vendor develop resolve finds and proves its engine itself (develop-engine-image.mjs); a customer resolve is handed one.
+const ENGINE_IMAGE_FLAG = '--engine-image';
+const ENGINE_REPOSITORY_FLAG = '--engine-repository';
+const ENGINE_SIGNER_FLAG = '--engine-signer';
+export const IMAGES_FROM_FLAG = '--images-from';
+export const PREVIOUS_LOCK_FLAG = '--previous-lock';
+export const PREVIOUS_LOCK_SHA256_FLAG = '--previous-lock-sha256';
+export const FIRST_SEAL_FLAG = '--first-seal';
 
 const COMMANDS = Object.freeze({
   resolve: {
     positional: true,
-    values: ['--pins', '--out', '--registry', '--engine-image'],
-    switches: ['--local'],
-    required: ['--pins', '--out', '--registry', '--engine-image'],
-    customer: { values: [DEFINITION_FLAG, ...CREDENTIAL_FLAGS, SOURCE_IMAGE_FLAG, COSIGN_FLAG], required: ['--pins', '--out', '--registry', '--engine-image'], refused: [], cosign: true },
+    // --images-from: the everyday job's image build record (images-from-record.mjs) instead of the registry probe; vendor only.
+    // --previous-lock with --previous-lock-sha256 (the digest of the latest signed, published edition's images.lock layer, passed by the workflow under
+    // the per-edition concurrency group) or --first-seal: the previous seal whose composed artifacts carry their generation forward; vendor only.
+    values: ['--pins', '--out', '--registry', ENGINE_REPOSITORY_FLAG, ENGINE_SIGNER_FLAG, COSIGN_FLAG, IMAGES_FROM_FLAG, PREVIOUS_LOCK_FLAG, PREVIOUS_LOCK_SHA256_FLAG],
+    switches: ['--local', FIRST_SEAL_FLAG],
+    required: ['--pins', '--out', '--registry', ENGINE_REPOSITORY_FLAG, ENGINE_SIGNER_FLAG, COSIGN_FLAG],
+    customer: { values: [DEFINITION_FLAG, ...CREDENTIAL_FLAGS, SOURCE_IMAGE_FLAG, COSIGN_FLAG, ENGINE_IMAGE_FLAG], required: ['--pins', '--out', '--registry', '--engine-image'], refused: [IMAGES_FROM_FLAG, PREVIOUS_LOCK_FLAG, PREVIOUS_LOCK_SHA256_FLAG, FIRST_SEAL_FLAG], cosign: true },
+    // A vendor resolve finds its engine itself; the old flag is refused by name, never read as a customer flag.
+    removedFromVendor: { [ENGINE_IMAGE_FLAG]: `use ${ENGINE_REPOSITORY_FLAG} and ${ENGINE_SIGNER_FLAG}` },
+  },
+  engine: {
+    positional: true,
+    values: ['--pins', ENGINE_REPOSITORY_FLAG, ENGINE_SIGNER_FLAG, COSIGN_FLAG],
+    switches: [],
+    required: ['--pins', ENGINE_REPOSITORY_FLAG, ENGINE_SIGNER_FLAG, COSIGN_FLAG],
   },
   target: {
     positional: true,
-    values: ['--pins', '--registry', '--engine-image'],
+    values: ['--pins', '--registry', '--engine-image', IMAGES_FROM_FLAG],
     switches: [],
     required: ['--pins', '--registry', '--engine-image'],
-    customer: { values: [DEFINITION_FLAG, SOURCE_IMAGE_FLAG], required: ['--pins', '--registry', '--engine-image'], refused: [] },
+    customer: { values: [DEFINITION_FLAG, SOURCE_IMAGE_FLAG], required: ['--pins', '--registry', '--engine-image'], refused: [IMAGES_FROM_FLAG] },
   },
   'freeze-graph': {
     positional: false,
-    values: ['--data-sha', '--kernel-sha', '--deploy-sha', '--editions-root-url', '--overrides', '--out'],
+    values: ['--data-sha', '--kernel-sha', '--deploy-sha', '--editions-root-url', '--overrides', '--member-pins', '--out'],
     switches: [],
     required: ['--data-sha', '--kernel-sha', '--deploy-sha', '--out'],
   },
@@ -219,6 +238,12 @@ const COMMANDS = Object.freeze({
     switches: [],
     required: ['--branch', '--registry', '--cosign', '--out'],
   },
+  'image-record': {
+    positional: true,
+    values: ['--selection', '--pins', '--out'],
+    switches: [],
+    required: ['--selection', '--pins', '--out'],
+  },
   'verify-image-record': {
     positional: false,
     values: ['--image', '--producer', '--registry', '--cosign'],
@@ -256,7 +281,8 @@ export function parseEditionVerbArgs(channel, argv) {
   if (spec === undefined) {
     throw new Error(`unknown command ${JSON.stringify(command)}; expected ${Object.keys(commands).join(' | ')}`);
   }
-  const customerValues = spec.customer?.values ?? [];
+  // The flags only the customer form takes: a flag the vendor form takes too (`--cosign` of a develop resolve) does not make it one.
+  const customerValues = (spec.customer?.values ?? []).filter((flag) => !spec.values.includes(flag));
   const options = {};
   const positional = [];
   for (let i = 0; i < rest.length; i += 1) {
@@ -283,13 +309,20 @@ export function parseEditionVerbArgs(channel, argv) {
     }
   }
   const customer = spec.customer !== undefined && customerValues.some((flag) => options[flag] !== undefined);
-  // `--cosign` of a customer form verifies a release catalogue; a vendor verb (develop `coverage`) takes its own `--cosign`.
-  if (spec.customer?.cosign === true && options[COSIGN_FLAG] !== undefined && channel !== EditionChannel.Release) {
+  // `--cosign` of a customer form verifies a release catalogue; a vendor verb (develop `coverage`, `resolve`, `engine`) takes its own `--cosign`.
+  if (customer && spec.customer?.cosign === true && options[COSIGN_FLAG] !== undefined && channel !== EditionChannel.Release) {
     throw new Error(`${COSIGN_FLAG} verifies a release catalogue's evidence; a ${channel} ${command} takes none`);
   }
   if (channel === EditionChannel.Release && options[DEFINITION_FLAG] === undefined) {
     throw new Error(`a ${channel} ${command} requires ${DEFINITION_FLAG}`);
   }
+  // A removed vendor flag with no other sign of a customer form (no --definition, no customer-only flag) is a stale vendor call.
+  const removedFlags = Object.keys(spec.removedFromVendor ?? {});
+  if (!customerValues.some((flag) => !removedFlags.includes(flag) && options[flag] !== undefined)) {
+    for (const flag of removedFlags) {
+      if (options[flag] !== undefined) {throw new Error(`${flag} was removed from a vendor ${command}: ${spec.removedFromVendor[flag]}`);}
+    }
+  }
   if (customer) {
     if (options[DEFINITION_FLAG] === undefined) {throw new Error(`a customer ${command} requires ${DEFINITION_FLAG}`);}
     for (const refused of spec.customer.refused) {

package/edition/develop-chart-set.mjs

@@ -29,6 +29,7 @@
 
 import { basename } from 'node:path';
 
+import { RefusalError } from './collected-refusals.mjs';
 import { readDevelopChartRoster } from './develop-chart-roster.mjs';
 import { assertRosteredChartSetLock } from './edition-chart-set.mjs';
 import { deployRoot } from './edition-workspace.mjs';
@@ -53,7 +54,7 @@ function deployPublisher() {
   const deployRepo = basename(deployPinKey());
   const publishers = chartSetPublishers().filter((publisher) => basename(publisher.repo) === deployRepo);
   if (publishers.length !== 1) {
-    throw new Error(
+    throw new RefusalError(
       `${publishers.length} configured chart publishers have repository ${deployRepo} (the deploy pin role); exactly one must, ` +
         'since a develop chart set is that publisher\'s set at the deploy commit',
     );
@@ -72,13 +73,13 @@ function committedInfraPublisher() {
   const path = chartSetLockPath();
   const committed = readLock(path);
   if (committed === null) {
-    throw new Error(`${path} is absent or unreadable; a develop edition carries the release infra chart set from it`);
+    throw new RefusalError(`${path} is absent or unreadable; a develop edition carries the release infra chart set from it`);
   }
   assertRosteredChartSetLock(committed, path);
   const indexes = infraPublisherIndexes();
   const found = committed.publishers.filter((publisher) => indexes.includes(publisher.index));
   if (indexes.length !== 1 || found.length !== 1) {
-    throw new Error(
+    throw new RefusalError(
       `${path} carries ${found.length} infra publisher entries (${indexes.length} infra publishers configured); exactly one is required`,
     );
   }
@@ -91,7 +92,7 @@ async function published(read, what, { publisher, xemaDeploySha }) {
     return await read();
   } catch (error) {
     if (error?.status !== NOT_FOUND) {throw error;}
-    throw new Error(`${what} is not published yet; ${publisher.repo} publish-charts for ${xemaDeploySha} not green`, { cause: error });
+    throw new RefusalError(`${what} is not published yet; ${publisher.repo} publish-charts for ${xemaDeploySha} not green`, { cause: error });
   }
 }
 
@@ -102,7 +103,7 @@ function assertIndexIsRoster(indexRoster, members, label) {
   const missing = expected.filter((line) => !actual.includes(line));
   const extra = actual.filter((line) => !expected.includes(line));
   if (missing.length > 0 || extra.length > 0) {
-    throw new Error(
+    throw new RefusalError(
       `${label} does not carry the deploy checkout's develop roster: ` +
         `missing [${missing.join(', ')}], unexpected [${extra.join(', ')}]`,
     );
@@ -116,7 +117,7 @@ function assertIndexIsRoster(indexRoster, members, label) {
  */
 export async function resolveDevelopChartSet({ xemaDeploySha, deployDir = deployRoot(), readRoster = readDevelopChartRoster, client }) {
   if (!COMMIT_PATTERN.test(xemaDeploySha ?? '')) {
-    throw new Error(`the deploy checkout SHA is not a 40-hex commit: ${JSON.stringify(xemaDeploySha)}`);
+    throw new RefusalError(`the deploy checkout SHA is not a 40-hex commit: ${JSON.stringify(xemaDeploySha)}`);
   }
   const publisher = deployPublisher();
   const infraPublisher = committedInfraPublisher();

package/edition/develop-current-resolution.mjs

@@ -0,0 +1,29 @@
+// develop-current-resolution — the members that keep the CURRENT develop resolution instead of a signed build record.
+//
+// A member keeps its current resolution (develop HEAD freeze plus the registry probe) only when the data root declares
+// it: `currentResolution: "<ticket>"` on its `firstPartySources` entry in edition-workspace.json, the ticket that
+// removes the exception (today xema-docs, whose develop lane is unsigned by owner decision and which leaves the
+// edition). It is a declared exception, not a fallback: absent means none, and every other member without a record
+// still refuses.
+
+import { compareStrings } from './lib.mjs';
+
+/** Whether a member (or its `firstPartySources` entry) keeps its current resolution. */
+export const keepsCurrentResolution = (member) => Object.hasOwn(member, 'currentResolution');
+
+/** The graph `members` that declare a current resolution, repo -> ticket, keys sorted: what a selection records. */
+export function currentResolutionOf(members) {
+  return Object.fromEntries(
+    members
+      .filter(keepsCurrentResolution)
+      .map(({ repo, currentResolution }) => [repo, currentResolution])
+      .sort(([a], [b]) => compareStrings(a, b)),
+  );
+}
+
+/** Why a selection's `currentResolution` (absent = none) is not exactly the one the graph `members` declare; null when it is. */
+export function currentResolutionProblem(declared, members) {
+  const expected = currentResolutionOf(members);
+  if (JSON.stringify(declared ?? {}) === JSON.stringify(expected)) {return null;}
+  return `"currentResolution" is ${JSON.stringify(declared)}, not ${JSON.stringify(expected)}, the members the data root declares keep their current resolution`;
+}

package/edition/develop-edition-invariants.mjs

@@ -22,6 +22,7 @@
 // admission of this edition for a biome it does not ship is a stale permission
 // and is refused; a declaration without a substantive consequence is refused.
 
+import { RefusalError } from './collected-refusals.mjs';
 import { editionWorkspaceConfig } from './edition-config.mjs';
 import { buildCapabilityDomainOwners, serializeJson } from './lib.mjs';
 
@@ -40,7 +41,7 @@ export const DevelopEditionInvariantReason = Object.freeze({
 const MIN_CONSEQUENCE_LENGTH = 40;
 
 /** A develop candidate broke a plane invariant. `violations` carries every one, each with its reason. */
-export class DevelopEditionInvariantError extends Error {
+export class DevelopEditionInvariantError extends RefusalError {
   /** @param {string} id @param {{ reason: string, detail: string }[]} violations */
   constructor(id, violations) {
     super(