@xemahq/xema 0.52.0 → 0.54.0

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,21 +178,35 @@ 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';
 
 const COMMANDS = Object.freeze({
   resolve: {
     positional: true,
-    values: ['--pins', '--out', '--registry', '--engine-image'],
+    // --images-from: the everyday job's image build record (images-from-record.mjs) instead of the registry probe; vendor only.
+    values: ['--pins', '--out', '--registry', ENGINE_REPOSITORY_FLAG, ENGINE_SIGNER_FLAG, COSIGN_FLAG, IMAGES_FROM_FLAG],
     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 },
+    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], 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,
@@ -256,7 +270,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 +298,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-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(

package/edition/develop-edition-resolve.mjs

@@ -1,6 +1,6 @@
 // develop-edition-resolve — resolve and seal one DEVELOP edition from a snapshot.
 //
-// The whole pipeline, in the order the release runs it, over the snapshot's
+// The whole pipeline, in the order the release runs it (every check reports its refusal; see develop-resolve-report.mjs), over the snapshot's
 // injected inputs: distribution lock -> plane invariants (reservation table,
 // confinement; develop-edition-invariants.mjs) -> authorization base (composed, never
 // written) -> images lock -> develop seal, plus the chart-set lock: the frozen
@@ -12,15 +12,21 @@ import { biomeSourceTreeIds, readBiomeSourceFacts, sealLock } from './biome-cont
 import { buildCatalogue } from './catalogue.mjs';
 import { resolveDevelopChartSet } from './develop-chart-set.mjs';
 import { assertDevelopEditionInvariants } from './develop-edition-invariants.mjs';
+import { resolveDevelopEngineImage } from './develop-engine-image.mjs';
 import { createDevelopImageProbe } from './develop-image-probe.mjs';
+import { BLOCKED, DevelopResolveCheck, RESOLVE_CHECK_DEPENDENCIES, createResolveReport } from './develop-resolve-report.mjs';
 import { assertFrozenCheckouts, buildSnapshotInputs } from './develop-snapshot-inputs.mjs';
 import { EditionChannel } from './edition-constants.mjs';
 import { sealImages } from './edition-image-seal.mjs';
+import { assertKernelEditionProtocol } from './edition-protocol.mjs';
 import { dataRoot, kernelPackageDir } from './edition-workspace.mjs';
+import { resolveImagesFromRecord, sealImagesFromRecord } from './images-from-record.mjs';
 import { kernelPackageOfAuthority } from './kernel-package.mjs';
 import { loadKernelDistributionSchemas } from './lib.mjs';
+import { assertLockBundleSigners, isBundleSignerRefusal } from './locked-bundle-signer.mjs';
+import { admitDistributionLock, ungrantedOptionalLinesOfRefusal } from './operation-grant-admission.mjs';
 import { deployPinKey } from './pin-source.mjs';
-import { composeAuthorizationBase, resolveDistributionWithIndex } from './resolve-distribution.mjs';
+import { admitResolvedLock, composeAuthorizationBase, prepareDistributionWithIndex } from './resolve-distribution.mjs';
 import { externalSourceTrees, resolveImages, sourceTreeLocator } from './resolve-images.mjs';
 import { createPinnedSourceAuthority } from './source-authority.mjs';
 import { loadTrustedThirdPartySourcePins } from './third-party-pins-trusted.mjs';
@@ -32,12 +38,15 @@ import { loadTrustedThirdPartySourcePins } from './third-party-pins-trusted.mjs'
 export const DEVELOP_EDITION_STEPS = Object.freeze({
   assertFrozenCheckouts,
   buildSnapshotInputs,
-  resolveDistributionWithIndex,
+  assertKernelEditionProtocol,
+  prepareDistributionWithIndex,
+  resolveDevelopEngineImage,
   assertDevelopEditionInvariants,
   assertAdapterBundlesMatchHost,
   composeAuthorizationBase,
   resolveImages,
   sealImages,
+  sealImagesFromRecord,
   resolveDevelopChartSet,
 });
 
@@ -45,46 +54,117 @@ const stderrProgress = (line) => process.stderr.write(`${line}\n`);
 
 /**
  * The first half of every develop resolve: the frozen snapshot's inputs and the
- * distribution lock composed over them. `resolveDevelopEdition` and the
- * read-only `coverage` verb both start here, so the content hash each computes
- * for a subject is the same by construction.
+ * distribution lock composed over them, NOT yet admitted. `resolveDevelopEdition`
+ * admits it as one of its checks; `resolveDevelopSnapshot` admits it at once. Both
+ * start here, so the content hash each computes for a subject is the same by construction.
  */
-export async function resolveDevelopSnapshot({ id, pins, steps = DEVELOP_EDITION_STEPS, phase = () => {} }) {
+async function prepareDevelopSnapshot({ id, pins, steps, phase }) {
   const schemas = await loadKernelDistributionSchemas();
   steps.assertFrozenCheckouts(pins);
   const inputs = await steps.buildSnapshotInputs({ id, pins, schemas });
   phase('snapshot inputs built');
-  const { lock, index } = await steps.resolveDistributionWithIndex(id, { inputs });
-  return { schemas, inputs, lock, index };
+  const prepared = await steps.prepareDistributionWithIndex(id, { inputs });
+  // The schemas the lock was composed with are the ones that admit it.
+  return { inputs, ...prepared };
+}
+
+/** The read-only `coverage` verb's snapshot: prepared as the resolve prepares it, then admitted (a refusal throws). */
+export async function resolveDevelopSnapshot({ id, pins, steps = DEVELOP_EDITION_STEPS, phase = () => {} }) {
+  const snapshot = await prepareDevelopSnapshot({ id, pins, steps, phase });
+  admitResolvedLock(snapshot.schemas, snapshot.lock);
+  return snapshot;
 }
 
-export async function resolveDevelopEdition({ id, pins, env = process.env, sealOptions = {}, fetchKernelTarball, fetchManifest = fetchRegistryManifest, progress = stderrProgress, steps = DEVELOP_EDITION_STEPS }) {
+/**
+ * @param {object} request
+ * @param {object} [request.imagesFrom] a parsed image build record (images-from-record.mjs): the digests are the record's,
+ *   with no probe and no rehash, and `verifySatellites` (createSatelliteVerifier) admits its satellite entries
+ */
+export async function resolveDevelopEdition({ id, pins, engine, cosignBinary, env = process.env, sealOptions = {}, fetchKernelTarball, fetchManifest = fetchRegistryManifest, progress = stderrProgress, steps = DEVELOP_EDITION_STEPS, imagesFrom, verifySatellites }) {
+  if ((imagesFrom === undefined) !== (verifySatellites === undefined)) {
+    throw new Error('resolveDevelopEdition takes an image build record and its satellite verifier together, or neither');
+  }
   const startedAt = Date.now();
   // One line per phase, with the time since the resolve began, so the step is never silent for long.
   const phase = (name) => progress(`[develop-edition] ${name} (+${Date.now() - startedAt}ms)`);
-  const { schemas, inputs, lock, index } = await resolveDevelopSnapshot({ id, pins, steps, phase });
+  // Every check runs unless a check it needs was refused; all refusals are reported together, and nothing is sealed or written then.
+  const report = createResolveReport();
+  const checked = (check, fn, options) => report.run(check, RESOLVE_CHECK_DEPENDENCIES[check], fn, options);
+  const chartSetLock = await checked(DevelopResolveCheck.ChartSet, async () => {
+    const chartSet = await steps.resolveDevelopChartSet({ xemaDeploySha: pins[deployPinKey()] });
+    phase('chart set resolved');
+    return chartSet;
+  });
+  const engineImage = await checked(DevelopResolveCheck.EngineImage, async () => {
+    const image = await steps.resolveDevelopEngineImage({ pins, engine, cosignBinary, env });
+    phase('engine image resolved');
+    return image;
+  });
+  await checked(DevelopResolveCheck.EditionProtocol, () => steps.assertKernelEditionProtocol(kernelPackageDir()));
+  const snapshot = await checked(DevelopResolveCheck.DistributionLock, () => prepareDevelopSnapshot({ id, pins, steps, phase }), {
+    classify: (error) => (isBundleSignerRefusal(error) ? DevelopResolveCheck.BundleSigner : DevelopResolveCheck.DistributionLock),
+  });
+  const lockProduced = snapshot !== BLOCKED;
+  const { schemas, inputs, lock, index } = lockProduced ? snapshot : {};
+  if (lockProduced) {
+    await checked(DevelopResolveCheck.BundleSigner, () => assertLockBundleSigners({ lock, schemas }));
+  }
   // The plane invariants, against the graph this candidate froze (develop-edition-invariants.mjs).
-  const graded = steps.assertDevelopEditionInvariants({ id, lock, biomeIndex: inputs.biomeIndex, schemas });
-  phase(`reservation table asserted (${graded.reservedDomains} domains); confinement asserted (${graded.confinedBiomes} declaration(s))`);
-  await steps.assertAdapterBundlesMatchHost({ lock, hostRow: adapterHostRow(index), fetchManifest });
-  const authorizationLock = await steps.composeAuthorizationBase(id, lock, index);
-  phase('distribution lock resolved');
+  await checked(DevelopResolveCheck.PlaneInvariants, () => {
+    const graded = steps.assertDevelopEditionInvariants({ id, lock, biomeIndex: inputs.biomeIndex, schemas });
+    phase(`reservation table asserted (${graded.reservedDomains} domains); confinement asserted (${graded.confinedBiomes} declaration(s))`);
+  });
+  await checked(DevelopResolveCheck.OperationAdmission, () => {
+    try {
+      admitDistributionLock(schemas, lock, { report: (line) => report.notice(line) });
+    } catch (error) {
+      ungrantedOptionalLinesOfRefusal(error).forEach((line) => report.notice(line));
+      throw error;
+    }
+    phase('operation requirements admitted');
+  });
+  await checked(DevelopResolveCheck.AdapterBundles, () => steps.assertAdapterBundlesMatchHost({ lock, hostRow: adapterHostRow(index), fetchManifest }));
+  const authorizationLock = await checked(DevelopResolveCheck.AuthorizationBase, async () => {
+    const composed = await steps.composeAuthorizationBase(id, lock, index);
+    phase('distribution lock resolved');
+    return composed;
+  });
   // Every subject's develop image is probed the moment its hash is known, in
   // parallel with the hashing of the rest; an absent image refuses here, naming
   // all of them, before any later phase runs.
-  const probe = createDevelopImageProbe({
-    distributionId: id,
-    env,
-    ...(sealOptions.distributionsRoot === undefined ? {} : { distributionsRoot: sealOptions.distributionsRoot }),
-    ...(sealOptions.fetchImpl === undefined ? {} : { fetchImpl: sealOptions.fetchImpl }),
-    ...(sealOptions.run === undefined ? {} : { run: sealOptions.run }),
-    progress,
+  let recorded;
+  const imageLock = await checked(DevelopResolveCheck.DevelopImages, async () => {
+    if (imagesFrom !== undefined) {
+      const fromRecord = await resolveImagesFromRecord({ id, inputs, lock, record: imagesFrom, resolveImages: steps.resolveImages, verifySatellites });
+      ({ recorded } = fromRecord);
+      phase(`image subjects taken from the build record (${fromRecord.imageLock.subjects.length} subjects); satellites verified`);
+      return fromRecord.imageLock;
+    }
+    const probe = createDevelopImageProbe({
+      distributionId: id,
+      env,
+      ...(sealOptions.distributionsRoot === undefined ? {} : { distributionsRoot: sealOptions.distributionsRoot }),
+      ...(sealOptions.fetchImpl === undefined ? {} : { fetchImpl: sealOptions.fetchImpl }),
+      ...(sealOptions.run === undefined ? {} : { run: sealOptions.run }),
+      progress,
+    });
+    const resolved = await steps.resolveImages(id, { inputs, lock, onSubjectHashed: probe.observe });
+    phase(`image content hashes computed (${resolved.imageLock.subjects.length} subjects)`);
+    await probe.settle();
+    phase('every develop image is present');
+    return resolved.imageLock;
   });
-  const { imageLock } = await steps.resolveImages(id, { inputs, lock, onSubjectHashed: probe.observe });
-  phase(`image content hashes computed (${imageLock.subjects.length} subjects)`);
-  await probe.settle();
-  phase('every develop image is present');
-  const sealedImageLock = await steps.sealImages({ channel: EditionChannel.Develop, imageLock, env, progress, thirdPartyPins: loadTrustedThirdPartySourcePins(dataRoot()), ...sealOptions });
+  try {
+    report.settle();
+  } catch (error) {
+    progress(error.message);
+    throw error;
+  }
+  if (report.noticeText() !== '') {progress(report.noticeText());}
+  const sealArguments = { imageLock, env, progress, thirdPartyPins: loadTrustedThirdPartySourcePins(dataRoot()), ...sealOptions };
+  const sealedImageLock = recorded === undefined
+    ? await steps.sealImages({ channel: EditionChannel.Develop, ...sealArguments })
+    : await steps.sealImagesFromRecord({ ...sealArguments, recorded });
   phase('images sealed');
   // The unsealed lock becomes the one v5 grammar only here, once the images it
   // owns are sealed: each biomeContentHash is recomputed from the frozen sources.
@@ -100,8 +180,6 @@ export async function resolveDevelopEdition({ id, pins, env = process.env, sealO
   phase(`biome sources read (${sourceFactsById.size} biomes)`);
   const sealedLock = await sealLock({ ...biomeSources, unsealed: lock, sourceFactsById });
   phase('distribution lock sealed');
-  const chartSetLock = await steps.resolveDevelopChartSet({ xemaDeploySha: pins[deployPinKey()] });
-  phase('chart set resolved');
   const sourceTreeIds = await biomeSourceTreeIds({ ...biomeSources, lock, sourceFactsById });
   const catalogue = buildCatalogue({
     sourceTreeIds,
@@ -121,5 +199,5 @@ export async function resolveDevelopEdition({ id, pins, env = process.env, sealO
     leaf: inputs.composed.leaf,
   });
   phase('catalogue built');
-  return { distributionLock: sealedLock, imageLock: sealedImageLock, authorizationLock, chartSetLock, catalogue };
+  return { distributionLock: sealedLock, imageLock: sealedImageLock, authorizationLock, chartSetLock, catalogue, engineImage };
 }