@xemahq/xema 0.40.3 → 0.41.0

package/edition/develop-edition.mjs

@@ -18,7 +18,7 @@
 //       --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>
 //       print <root>/<develop segment>/xema-edition-<id>:<tag>, the tag being sha256 of the canonical
-//       { cli, engine, pins, sourceImages } (developEditionTag): every input of the bytes the artifact records,
+//       { 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
 //       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.
@@ -38,6 +38,12 @@
 //       the same for a customer artifact; its descriptor's catalogue provenance pin must also equal the
 //       pinned develop catalogue digest, and its own image rows must be the rows the --source-image map composes. It fetches that catalogue (as `resolve --definition` does) to take the
 //       kernel from it. Takes --data-root, --cache-dir.
+//   coverage <id> --pins <file> --cosign <absolute-path> [--json]
+//       READ-ONLY: for every image subject of the snapshot, whether its develop image is producer-signed
+//       in the form T72 resolve accepts (attested | signature-verified | no-row | unsigned |
+//       annotations-missing | annotation-mismatch | not-built). Prints a table grouped by producer repo
+//       and `covered N/M` (--json: the same as data). Exit 0 only when every subject is covered, 1 when
+//       not, 2 on an operational error. Takes the roots `resolve` takes; writes nothing.
 //   check-overrides --overrides <json>
 //       refuse a pins override that would select the tooling this run executes
 //       (the edition tooling's own repository); the workflow runs it before any other checkout.
@@ -51,27 +57,21 @@
 // Tokens come from the environment (EVIDENCE_REPOSITORIES_TOKEN, XEMA_GHCR_PULL_TOKEN),
 // never argv. Nothing here writes git or publishes a release edition.
 
-import { writeFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 
-import { fetchCatalogue } from './catalogue-fetch.mjs';
-import { readCataloguePin } from './catalogue-pin.mjs';
 import { writeCatalogue } from './catalogue.mjs';
-import { CATALOGUE_TOKEN_ENV_FLAG, CATALOGUE_USERNAME_FLAG, DEFINITION_FLAG, SOURCE_IMAGE_FLAG } from './customer-flags.mjs';
-import { assertOwnImageRowsMatch, customerDevelopFrame, resolveCustomerDevelopEdition } from './develop-customer-edition.mjs';
+import { CUSTOMER_ROOTS, 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 { assertNoToolingOverride, freezeCustomerSources, freezeGraph, freezeSources, lsRemoteDevelopHead } from './develop-freeze.mjs';
-import { assertCanonicalDistributionId } from './distribution-paths.mjs';
-import { LOCAL_WORKFLOW, assertEngineImage, assertExistingArtifactMatches, developEditionTarget, workflowFromEnv, writeEditionArtifact } from './edition-artifact.mjs';
-import { editionWorkspaceConfig } from './edition-config.mjs';
+import { assertNoToolingOverride, freezeGraph, freezeSources } from './develop-freeze.mjs';
+import { LOCAL_WORKFLOW, assertExistingArtifactMatches, developEditionTarget, workflowFromEnv, writeEditionArtifact } from './edition-artifact.mjs';
 import { EditionChannel } from './edition-constants.mjs';
 import { WorkspaceRoot, configureEditionWorkspaceFromProcess, isEntryModule, runtimeImageSourceIndexPath } from './edition-workspace.mjs';
 import { descriptorEvidenceTrust } from './evidence-trust-policy.mjs';
-import { holdSource } from './git-source-auth.mjs';
-import { adoptCatalogueKernel } from './kernel-package.mjs';
-import { loadKernelDistributionSchemas, serializeJson } from './lib.mjs';
+import { loadKernelDistributionSchemas } from './lib.mjs';
 import { snapshotPinSource } from './pin-source.mjs';
-import { assertSourceImagesCoverDefinition, parseSourceImages } from './resolve-customer-edition.mjs';
 import { composeEdition } from './resolve-distribution.mjs';
 import { readStrictJsonFile } from './strict-json.mjs';
 
@@ -81,12 +81,9 @@ import { readStrictJsonFile } from './strict-json.mjs';
 // takes only the data root in either form: it judges its --overrides JSON against the pin roles the data
 // root declares, so it reads nothing else and refuses every other root flag.
 const VENDOR_ROOTS = Object.freeze([WorkspaceRoot.Data, WorkspaceRoot.Editions, WorkspaceRoot.Sources, WorkspaceRoot.Kernel, WorkspaceRoot.Deploy, WorkspaceRoot.Cache]);
-const CUSTOMER_ROOTS = Object.freeze({
-  resolve: [WorkspaceRoot.Data, WorkspaceRoot.Editions, WorkspaceRoot.Sources, WorkspaceRoot.Cache],
-  target: [],
-  'check-existing': [WorkspaceRoot.Data, WorkspaceRoot.Cache],
-  'freeze-sources': [WorkspaceRoot.Data],
-});
+// `coverage` is the P2b gate: 1 means "not covered", so an operational error is a distinct 2.
+const COVERAGE_COMMAND = 'coverage';
+const COVERAGE_OPERATIONAL_EXIT = CoverageExit.Operational;
 const DATA_ROOT_ONLY_COMMANDS = Object.freeze(['check-overrides']);
 
 if (isEntryModule(import.meta.url)) {
@@ -95,103 +92,15 @@ if (isEntryModule(import.meta.url)) {
     configureEditionWorkspaceFromProcess([WorkspaceRoot.Data], { refuseOthers: true });
   } else {
     const customerForm = process.argv.includes(DEFINITION_FLAG);
-    configureEditionWorkspaceFromProcess(customerForm ? (CUSTOMER_ROOTS[command] ?? VENDOR_ROOTS) : VENDOR_ROOTS, { refuseOthers: customerForm && CUSTOMER_ROOTS[command] !== undefined });
+    configureEditionWorkspaceFromProcess(customerForm ? (CUSTOMER_ROOTS[command] ?? VENDOR_ROOTS) : VENDOR_ROOTS, {
+      refuseOthers: customerForm && CUSTOMER_ROOTS[command] !== undefined,
+      ...(command === COVERAGE_COMMAND ? { failureExitCode: COVERAGE_OPERATIONAL_EXIT } : {}),
+    });
   }
 }
 
-// Per verb: the vendor form (`positional` id, `values`, `switches`) and, where the verb has one, the 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]);
-
-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], required: ['--pins', '--out', '--registry', '--engine-image'], refused: [] },
-  },
-  target: {
-    positional: true,
-    values: ['--pins', '--registry', '--engine-image'],
-    switches: [],
-    required: ['--pins', '--registry', '--engine-image'],
-    customer: { values: [DEFINITION_FLAG, SOURCE_IMAGE_FLAG], required: ['--pins', '--registry', '--engine-image'], refused: [] },
-  },
-  'freeze-graph': {
-    positional: false,
-    values: ['--data-sha', '--kernel-sha', '--deploy-sha', '--editions-root-url', '--overrides', '--out'],
-    switches: [],
-    required: ['--data-sha', '--kernel-sha', '--deploy-sha', '--out'],
-  },
-  'freeze-sources': {
-    positional: true,
-    values: ['--pins', '--overrides', '--out'],
-    switches: [],
-    required: ['--pins', '--out'],
-    customer: { values: [DEFINITION_FLAG], required: ['--out'], refused: ['--pins', '--overrides'] },
-  },
-  'check-overrides': { positional: false, values: ['--overrides'], switches: [], required: ['--overrides'] },
-  'check-existing': {
-    positional: true,
-    values: ['--pins', '--artifact', '--engine-image'],
-    switches: [],
-    required: ['--pins', '--artifact', '--engine-image'],
-    customer: { values: [DEFINITION_FLAG, ...CREDENTIAL_FLAGS, SOURCE_IMAGE_FLAG], required: ['--pins', '--artifact', '--engine-image'], refused: [] },
-  },
-});
-
-/** Parse `<command> [<id>] --flag value ...` against the closed vocabulary of the command. */
-export function parseDevelopEditionArgs(argv) {
-  const [command, ...rest] = argv;
-  const spec = COMMANDS[command];
-  if (spec === undefined) {
-    throw new Error(`unknown command ${JSON.stringify(command)}; expected ${Object.keys(COMMANDS).join(' | ')}`);
-  }
-  const customerValues = spec.customer?.values ?? [];
-  const options = {};
-  const positional = [];
-  for (let i = 0; i < rest.length; i += 1) {
-    const arg = rest[i];
-    if (spec.switches.includes(arg)) {
-      options[arg] = true;
-    } else if (spec.values.includes(arg) || customerValues.includes(arg)) {
-      const value = rest[i + 1];
-      if (value === undefined || (value.startsWith('--') && value.length > 2)) {
-        throw new Error(`${arg} requires a value`);
-      }
-      if (REPEATABLE.includes(arg)) {
-        options[arg] = [...(options[arg] ?? []), value];
-      } else if (options[arg] !== undefined) {
-        throw new Error(`${arg} given twice`);
-      } else {
-        options[arg] = value;
-      }
-      i += 1;
-    } else if (arg.startsWith('--')) {
-      throw new Error(`unknown argument ${arg} for ${command}`);
-    } else {
-      positional.push(arg);
-    }
-  }
-  const customer = spec.customer !== undefined && customerValues.some((flag) => options[flag] !== undefined);
-  if (customer) {
-    if (options[DEFINITION_FLAG] === undefined) {throw new Error(`a customer ${command} requires ${DEFINITION_FLAG}`);}
-    for (const refused of spec.customer.refused) {
-      if (options[refused] !== undefined) {throw new Error(`a customer ${command} takes no ${refused}`);}
-    }
-    if (positional.length !== 0) {throw new Error(`a customer ${command} takes no <distribution-id>: the id is the definition's`);}
-  } else if (spec.positional ? positional.length !== 1 : positional.length !== 0) {
-    throw new Error(`${command} takes ${spec.positional ? 'exactly one <distribution-id>' : 'no positional argument'}`);
-  }
-  for (const required of customer ? spec.customer.required : spec.required) {
-    if (options[required] === undefined) {throw new Error(`${command} requires ${required}`);}
-  }
-  if (spec.positional && !customer) {assertCanonicalDistributionId(positional[0]);}
-  if (options['--engine-image'] !== undefined) {assertEngineImage(options['--engine-image']);}
-  return { command, id: positional[0], options, customer };
-}
+/** Parse `<command> [<id>] --flag value ...` against the closed vocabulary of the develop command. */
+export const parseDevelopEditionArgs = (argv) => parseEditionVerbArgs(EditionChannel.Develop, argv);
 
 function parseOverrides(text) {
   if (text === undefined || text.trim() === '') {return {};}
@@ -202,102 +111,16 @@ function parseOverrides(text) {
   return parsed;
 }
 
-function writeOnce(path, value) {
-  writeFileSync(path, serializeJson(value), { flag: 'wx' });
-}
-
-function headResolver(env) {
-  const workspace = editionWorkspaceConfig();
-  return { resolveHead: (source) => lsRemoteDevelopHead(source, { workspace, env }), holdSource: (source) => holdSource(source, workspace, env) };
-}
-
-/** The pinned develop catalogue of a customer definition: fetched by its digest, as every customer develop verb does. */
-function fetchPinnedDevelopCatalogue(options, env) {
-  return fetchCatalogue({
-    ref: readCataloguePin({ definitionFile: options[DEFINITION_FLAG], channel: EditionChannel.Develop }),
-    channel: EditionChannel.Develop,
-    username: options[CATALOGUE_USERNAME_FLAG],
-    tokenEnv: options[CATALOGUE_TOKEN_ENV_FLAG],
-    env,
-  });
-}
-
-/** A customer develop resolve: the artifact (descriptor and four locks, no catalogue: it is not an offering) goes to --out. */
-async function resolveCustomer(options, env) {
-  const { catalogue, digest } = await fetchPinnedDevelopCatalogue(options, env);
-  const rawDefinition = readStrictJsonFile(options[DEFINITION_FLAG]);
-  const sourceImages = parseSourceImages(options[SOURCE_IMAGE_FLAG] ?? []);
-  // The catalogue's kernel is adopted inside the resolve, before any kernel schema is loaded; the evidence trust
-  // state loads kernel schemas, so it is read after.
-  const { id, pins, ...resolved } = await resolveCustomerDevelopEdition({
-    rawDefinition,
-    catalogue,
-    catalogueDigest: digest,
-    pins: readStrictJsonFile(options['--pins']),
-    sourceImages,
-    env,
-  });
-  const evidenceTrustPolicy = await descriptorEvidenceTrust({ channel: EditionChannel.Develop });
-  const target = developEditionTarget(id, pins, { registry: options['--registry'], engineImage: options['--engine-image'], sourceImages });
-  writeEditionArtifact({
-    outDir: resolve(options['--out']),
-    channel: EditionChannel.Develop,
-    distributionId: id,
-    pins,
-    workflow: options['--local'] ? LOCAL_WORKFLOW : workflowFromEnv(env),
-    evidenceTrustPolicy,
-    engineImage: options['--engine-image'],
-    distributionLock: resolved.distributionLock,
-    imageLock: resolved.imageLock,
-    authorizationLock: resolved.authorizationLock,
-    chartSetLock: resolved.chartSetLock,
-  });
-  console.log(target);
-}
-
-/** A customer check-existing: the pinned catalogue is fetched to take its kernel; the digest fetched is the digest the artifact is compared with. */
-export async function checkExistingCustomer(options, env, { adopt = adoptCatalogueKernel } = {}) {
-  const frame = customerDevelopFrame({ definitionFile: options[DEFINITION_FLAG], pinsFile: options['--pins'] });
-  const sourceImages = customerSourceImages(options, frame.rawDefinition);
-  const { catalogue, digest } = await fetchPinnedDevelopCatalogue(options, env);
-  if (digest !== frame.catalogueDigest) {
-    throw new Error(`the fetched catalogue is ${digest}, not the pinned ${frame.catalogueDigest}`);
-  }
-  await adopt(catalogue);
-  assertExistingArtifactMatches({
-    artifactDir: resolve(options['--artifact']),
-    distributionId: frame.id,
-    channel: EditionChannel.Develop,
-    evidenceTrustPolicy: await descriptorEvidenceTrust({ channel: EditionChannel.Develop }),
-    pins: frame.pins,
-    engineImage: options['--engine-image'],
-    catalogueDigest: frame.catalogueDigest,
-  });
-  assertOwnImageRowsMatch({ artifactDir: resolve(options['--artifact']), sourceImages });
-}
-
-/** The parsed --source-image map of a customer verb, covering exactly the definition's declared sources. */
-function customerSourceImages(options, rawDefinition) {
-  const sourceImages = parseSourceImages(options[SOURCE_IMAGE_FLAG] ?? []);
-  assertSourceImagesCoverDefinition(rawDefinition, sourceImages);
-  return sourceImages;
-}
-
 async function run(argv, env) {
   const { command, id, options, customer } = parseDevelopEditionArgs(argv);
   switch (command) {
     case 'target': {
-      if (customer) {
-        const frame = customerDevelopFrame({ definitionFile: options[DEFINITION_FLAG], pinsFile: options['--pins'] });
-        const sourceImages = customerSourceImages(options, frame.rawDefinition);
-        console.log(developEditionTarget(frame.id, frame.pins, { registry: options['--registry'], engineImage: options['--engine-image'], sourceImages }));
-        return;
-      }
+      if (customer) {return runCustomerVerb({ channel: EditionChannel.Develop, command, options, env });}
       console.log(developEditionTarget(id, readStrictJsonFile(options['--pins']), { registry: options['--registry'], engineImage: options['--engine-image'] }));
       return;
     }
     case 'resolve': {
-      if (customer) {return resolveCustomer(options, env);}
+      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'] });
@@ -318,8 +141,16 @@ async function run(argv, env) {
       console.log(target);
       return;
     }
+    case 'coverage':
+      return runDevelopCoverage({
+        id,
+        pins: readStrictJsonFile(options['--pins']),
+        cosignBinary: options['--cosign'],
+        json: options['--json'] === true,
+        env,
+      });
     case 'check-existing': {
-      if (customer) {return checkExistingCustomer(options, env);}
+      if (customer) {return runCustomerVerb({ channel: EditionChannel.Develop, command, options, env });}
       assertExistingArtifactMatches({
         artifactDir: resolve(options['--artifact']),
         distributionId: id,
@@ -342,29 +173,19 @@ async function run(argv, env) {
         deploySha: options['--deploy-sha'],
         editionsRootUrl: options['--editions-root-url'],
         overrides: parseOverrides(options['--overrides']),
-        ...headResolver(env),
+        ...headResolver(EditionChannel.Develop, env),
       });
       writeOnce(options['--out'], pins);
       return;
     }
     case 'freeze-sources': {
-      if (customer) {
-        writeOnce(
-          options['--out'],
-          freezeCustomerSources({
-            definition: readStrictJsonFile(options[DEFINITION_FLAG]),
-            ...headResolver(env),
-            sourceRepositoryUrlPrefix: editionWorkspaceConfig().sourceRepositoryUrlPrefix,
-          }),
-        );
-        return;
-      }
+      if (customer) {return runCustomerVerb({ channel: EditionChannel.Develop, command, options, env });}
       const pins = readStrictJsonFile(options['--pins']);
       const { parseDistribution } = await loadKernelDistributionSchemas();
       const declaredSources = composeEdition(parseDistribution, id, snapshotPinSource(pins)).declaredSources;
       writeOnce(
         options['--out'],
-        freezeSources({ pins, declaredSources, overrides: parseOverrides(options['--overrides']), ...headResolver(env) }),
+        freezeSources({ pins, declaredSources, overrides: parseOverrides(options['--overrides']), ...headResolver(EditionChannel.Develop, env) }),
       );
       return;
     }
@@ -374,8 +195,14 @@ async function run(argv, env) {
 }
 
 if (isEntryModule(import.meta.url)) {
-  run(process.argv.slice(2), process.env).catch((error) => {
-    console.error(`[develop-edition] ${error.message}`);
-    process.exit(1);
-  });
+  const argv = process.argv.slice(2);
+  run(argv, process.env).then(
+    (code) => {
+      if (typeof code === 'number') {process.exitCode = code;}
+    },
+    (error) => {
+      console.error(`[develop-edition] ${error.message}`);
+      process.exit(argv[0] === COVERAGE_COMMAND ? COVERAGE_OPERATIONAL_EXIT : 1);
+    },
+  );
 }

package/edition/develop-freeze.mjs

@@ -15,6 +15,7 @@
 
 import { execFileSync } from 'node:child_process';
 
+import { EditionChannel } from './edition-channel.mjs';
 import { assertCanonicalSourceUrl, assertSourceDeclaresNoCredential, isUnderSourcePrefix, withSourceGitEnv } from './git-source-auth.mjs';
 import { canonicalPublicHttpsRepositoryUrl } from './lib.mjs';
 import {
@@ -29,35 +30,71 @@ import {
   sourcePinKey,
 } from './pin-source.mjs';
 
-const DEVELOP_REF = 'refs/heads/develop';
 const SHA_PATTERN = /^[0-9a-f]{40}$/;
 
+/** The ref namespaces a freeze may resolve a ref in. */
+export const RefKind = Object.freeze({ Branch: 'branch', Tag: 'tag' });
+
+const REF_PREFIX = Object.freeze({ [RefKind.Branch]: 'refs/heads/', [RefKind.Tag]: 'refs/tags/' });
+const PEELED_SUFFIX = '^{}';
+
+/**
+ * What each channel freezes a source at. A develop edition freezes the head of the `develop` BRANCH of every
+ * repository; a release edition freezes each source at the ref its definition declares, a branch or a tag.
+ */
+const FREEZE_REF_KINDS = Object.freeze({
+  [EditionChannel.Develop]: Object.freeze([RefKind.Branch]),
+  [EditionChannel.Release]: Object.freeze([RefKind.Branch, RefKind.Tag]),
+});
+
 /**
- * `git ls-remote <url> refs/heads/develop` for one source `{ name, url }`; throws naming the repository when
- * absent. The source is held and its git environment built by `withSourceGitEnv`: the workspace credential
- * reaches only a repository under `sourceRepositoryUrlPrefix`.
+ * The commit `ref` names in one source `{ name, url }`, by `git ls-remote <url> <refs/heads/ref | refs/tags/ref |
+ * refs/tags/ref^{}>` (only the namespaces the channel freezes at). A tag resolves to its peeled commit when it is annotated.
+ * Throws naming the repository when the ref is absent, or when it is both a branch and a tag. The source is held and its
+ * git environment built by `withSourceGitEnv`: the workspace credential reaches only a repository under `sourceRepositoryUrlPrefix`.
  */
-export function lsRemoteDevelopHead(source, { workspace, env = process.env, runGit = execFileSync }) {
+export function lsRemoteRef(source, ref, { channel, workspace, env = process.env, runGit = execFileSync }) {
+  const kinds = FREEZE_REF_KINDS[channel];
+  if (kinds === undefined) {throw new Error(`unknown edition channel ${JSON.stringify(channel)}`);}
+  if (typeof ref !== 'string' || ref.length === 0) {
+    throw new Error(`source "${source.name}" declares no ref; a ${channel} edition cannot be frozen without one`);
+  }
+  const names = kinds.flatMap((kind) => (kind === RefKind.Tag ? [`${REF_PREFIX[kind]}${ref}`, `${REF_PREFIX[kind]}${ref}${PEELED_SUFFIX}`] : [`${REF_PREFIX[kind]}${ref}`]));
   const output = withSourceGitEnv(source, { workspace, env }, (gitEnv) =>
-    runGit('git', ['ls-remote', source.url, DEVELOP_REF], {
+    runGit('git', ['ls-remote', source.url, ...names], {
       env: gitEnv,
       encoding: 'utf8',
       stdio: ['ignore', 'pipe', 'pipe'],
     }),
   ).trim();
-  const [sha, ref] = output.split(/\s+/);
-  if (!SHA_PATTERN.test(sha ?? '') || ref !== DEVELOP_REF) {
-    throw new Error(`${source.url} has no ${DEVELOP_REF}; a develop edition cannot be frozen without it`);
+  const served = new Map();
+  for (const line of output.split('\n')) {
+    const [sha, name] = line.trim().split(/\s+/);
+    if (names.includes(name)) {
+      if (!SHA_PATTERN.test(sha ?? '')) {throw new Error(`${source.url}: git ls-remote answered ${JSON.stringify(line)} for ${name}`);}
+      served.set(name, sha);
+    }
+  }
+  const branch = served.get(`${REF_PREFIX[RefKind.Branch]}${ref}`);
+  const tagName = `${REF_PREFIX[RefKind.Tag]}${ref}`;
+  const tag = served.get(`${tagName}${PEELED_SUFFIX}`) ?? served.get(tagName);
+  if (branch !== undefined && tag !== undefined) {
+    throw new Error(`${source.url}: ${JSON.stringify(ref)} is both a branch and a tag; a ${channel} edition cannot be frozen at an ambiguous ref`);
+  }
+  const commit = branch ?? tag;
+  if (commit === undefined) {
+    throw new Error(`${source.url} has no ${kinds.map((kind) => `${REF_PREFIX[kind]}${ref}`).join(' or ')}; a ${channel} edition cannot be frozen without it`);
   }
-  return sha;
+  return commit;
 }
 
-/** A resolver that asks `resolveHead` at most once per distinct URL; it takes the source `{ name, url }`. */
+/** A resolver that asks `resolveHead` at most once per distinct URL and ref; it takes the source `{ name, url, ref? }`. */
 function memoizedHeads(resolveHead) {
   const heads = new Map();
   return (source) => {
-    if (!heads.has(source.url)) {heads.set(source.url, resolveHead(source));}
-    return heads.get(source.url);
+    const key = JSON.stringify([source.url, source.ref]);
+    if (!heads.has(key)) {heads.set(key, resolveHead(source));}
+    return heads.get(key);
   };
 }
 

package/edition/develop-image-probe.mjs

@@ -18,20 +18,20 @@ import { registryClientsFor } from './verify-image-platforms.mjs';
 
 const DEFAULT_PROBE_CONCURRENCY = 6;
 
-/** One subject's line in the "not built yet" refusal. */
-export function notBuiltYetMessage(subject) {
+/** One subject's line in the "not built yet" refusal of `channel` (develop unless named). */
+export function notBuiltYetMessage(subject, channel = 'develop') {
   return (
-    `${subject.repo}@${subject.sourceCommit} develop image ` +
+    `${subject.repo}@${subject.sourceCommit} ${channel} image ` +
     `${subject.imageRef}:${subject.contentHash} not built yet`
   );
 }
 
-/** The ONE refusal naming every develop subject whose coordinate is absent. */
-export function notBuiltYetError(distributionId, missingSubjects) {
+/** 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(
-    `${missingSubjects.length} develop image(s) of "${distributionId}" are not built yet ` +
+    `${missingSubjects.length} ${channel} image(s) of "${distributionId}" are not built yet ` +
       "(the producer's CI is not green or still running):\n  " +
-      missingSubjects.map(notBuiltYetMessage).join('\n  '),
+      missingSubjects.map((subject) => notBuiltYetMessage(subject, channel)).join('\n  '),
   );
 }
 

package/edition/edition-artifact.mjs

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

package/edition/edition-constants.mjs

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

package/edition/edition-contract.json

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