@xemahq/xema 0.57.1 → 0.59.0

package/edition/develop-record-ancestry.mjs

@@ -25,27 +25,31 @@ import { withSourceGitEnv } from './git-source-auth.mjs';
 import { RecordRefused } from './record-refused.mjs';
 
 const DEVELOP_REF = 'refs/heads/develop';
+/** The tag a published pin carries in a RecordCommitNotOnDevelopError. */
+export const PUBLISHED_PIN_TAG = 'published pin';
 // One external call to a git remote; a fetch that exceeds it fails naming the member, never a verdict.
 const GIT_CALL_TIMEOUT_MS = 300_000;
 const GIT_MAX_OUTPUT_BYTES = 8 * 1024 * 1024;
 
 export class IncomparableRecordCommitsError extends RecordRefused {
-  constructor(repo, first, second) {
-    super(repo, `record commits ${first.commit} (${first.tags.join(', ')}) and ${second.commit} (${second.tags.join(', ')}) are not ancestor-related on develop`);
+  constructor(repo, first, second, context) {
+    super(repo, `record commits ${first.commit} (${first.tags.join(', ')}) and ${second.commit} (${second.tags.join(', ')}) are not ancestor-related on develop`, context);
     this.name = 'IncomparableRecordCommitsError';
   }
 }
 
 export class RecordCommitNotOnDevelopError extends RecordRefused {
-  constructor(repo, commit, tags) {
-    super(repo, `record commit ${commit} (${tags.join(', ')}) is not in the fetched develop history`);
+  constructor(repo, commit, tags, context) {
+    super(repo, `record commit ${commit} (${tags.join(', ')}) is not in the fetched develop history`, context);
     this.name = 'RecordCommitNotOnDevelopError';
+    this.commit = commit;
+    this.tags = tags;
   }
 }
 
 export class DivergedFromPublishedError extends RecordRefused {
-  constructor(repo, selected, published) {
-    super(repo, `the newest record commit ${selected} and the published commit ${published} are not ancestor-related on develop`);
+  constructor(repo, selected, published, context) {
+    super(repo, `the newest record commit ${selected} and the published commit ${published} are not ancestor-related on develop`, context);
     this.name = 'DivergedFromPublishedError';
   }
 }
@@ -75,10 +79,11 @@ export function defaultRunGit(args, { cwd, env }) {
  * @param {object} request.workspace the workspace config the source hold reads
  * @param {object} request.env
  * @param {Function} [request.runGit] (args, {cwd, env}) => {status, stdout, stderr}; replaced by tests
+ * @param {string} [request.context] the verb its errors name (`select-records` by default)
  * @returns {{commit: string, head: string, behind: number}} the selected commit, develop's head in the same fetch, and
  *   how many commits the selected one is behind that head (0 when it is the head)
  */
-export function newestCommitOnDevelop({ member, candidates, published, workspace, env, runGit = defaultRunGit }) {
+export function newestCommitOnDevelop({ member, candidates, published, workspace, env, runGit = defaultRunGit, context = 'select-records' }) {
   const byCommit = new Map();
   for (const { commit, tag } of candidates) {
     byCommit.set(commit, [...(byCommit.get(commit) ?? []), tag]);
@@ -89,28 +94,28 @@ export function newestCommitOnDevelop({ member, candidates, published, workspace
     return withSourceGitEnv({ name: member.repo, url: member.repositoryUrl }, { workspace, env }, (gitEnv) => {
       const git = (args, extraEnv = {}) => runGit(args, { cwd: scratch, env: { ...gitEnv, ...extraEnv } });
       const init = git(['init', '--bare', '--quiet']);
-      if (init.status !== 0) {throw new Error(`select-records: ${member.repo}: git init failed: ${init.stderr.trim()}`);}
+      if (init.status !== 0) {throw new Error(`${context}: ${member.repo}: git init failed: ${init.stderr.trim()}`);}
       const fetched = git(['fetch', '--quiet', '--filter=blob:none', '--no-tags', member.repositoryUrl, `+${DEVELOP_REF}:${DEVELOP_REF}`]);
       if (fetched.status !== 0) {
-        throw new Error(`select-records: ${member.repo}: git fetch of develop from ${member.repositoryUrl} failed (exit ${fetched.status}): ${fetched.stderr.trim()}`);
+        throw new Error(`${context}: ${member.repo}: git fetch of develop from ${member.repositoryUrl} failed (exit ${fetched.status}): ${fetched.stderr.trim()}`);
       }
       // 0 = ancestor (or equal), 1 = not; anything else is git failing, never a verdict
       const isAncestor = (older, newer) => {
         const result = git(['merge-base', '--is-ancestor', older, newer]);
         if (result.status === 0) {return true;}
         if (result.status === 1) {return false;}
-        throw new Error(`select-records: ${member.repo}: git merge-base ${older} ${newer} failed (exit ${result.status}): ${result.stderr.trim()}`);
+        throw new Error(`${context}: ${member.repo}: git merge-base ${older} ${newer} failed (exit ${result.status}): ${result.stderr.trim()}`);
       };
       const assertOnDevelop = (commit, tags) => {
         // no lazy fetch: a commit the develop fetch did not bring is not on develop
         const known = git(['cat-file', '-e', `${commit}^{commit}`], { GIT_NO_LAZY_FETCH: '1' });
-        if (known.status !== 0 || !isAncestor(commit, DEVELOP_REF)) {throw new RecordCommitNotOnDevelopError(member.repo, commit, tags);}
+        if (known.status !== 0 || !isAncestor(commit, DEVELOP_REF)) {throw new RecordCommitNotOnDevelopError(member.repo, commit, tags, context);}
       };
       for (const { commit, tags } of commits) {assertOnDevelop(commit, tags);}
       let selected = commits[0];
       for (const other of commits.slice(1)) {
         if (isAncestor(other.commit, selected.commit)) {continue;}
-        if (!isAncestor(selected.commit, other.commit)) {throw new IncomparableRecordCommitsError(member.repo, selected, other);}
+        if (!isAncestor(selected.commit, other.commit)) {throw new IncomparableRecordCommitsError(member.repo, selected, other, context);}
         selected = other;
       }
       // develop's head and the chosen commit's distance from it, read in the same scratch the choice was made in
@@ -118,20 +123,20 @@ export function newestCommitOnDevelop({ member, candidates, published, workspace
         const headResult = git(['rev-parse', DEVELOP_REF]);
         const head = headResult.stdout.trim();
         if (headResult.status !== 0 || !/^[0-9a-f]{40}$/.test(head)) {
-          throw new Error(`select-records: ${member.repo}: git rev-parse ${DEVELOP_REF} failed (exit ${headResult.status}): ${headResult.stderr.trim() || head}`);
+          throw new Error(`${context}: ${member.repo}: git rev-parse ${DEVELOP_REF} failed (exit ${headResult.status}): ${headResult.stderr.trim() || head}`);
         }
         const counted = git(['rev-list', '--count', `${commit}..${DEVELOP_REF}`]);
         const behind = Number(counted.stdout.trim());
         if (counted.status !== 0 || !/^\d+$/.test(counted.stdout.trim())) {
-          throw new Error(`select-records: ${member.repo}: git rev-list --count ${commit}..${DEVELOP_REF} failed (exit ${counted.status}): ${counted.stderr.trim() || counted.stdout.trim()}`);
+          throw new Error(`${context}: ${member.repo}: git rev-list --count ${commit}..${DEVELOP_REF} failed (exit ${counted.status}): ${counted.stderr.trim() || counted.stdout.trim()}`);
         }
         return { commit, head, behind };
       };
       if (published === undefined) {return withDistance(selected.commit);}
-      assertOnDevelop(published, ['published pin']);
+      assertOnDevelop(published, [PUBLISHED_PIN_TAG]);
       if (isAncestor(selected.commit, published)) {return withDistance(published);} // equal, or the records are behind it
       if (isAncestor(published, selected.commit)) {return withDistance(selected.commit);}
-      throw new DivergedFromPublishedError(member.repo, selected.commit, published);
+      throw new DivergedFromPublishedError(member.repo, selected.commit, published, context);
     });
   } finally {
     rmSync(scratch, { recursive: true, force: true });

package/edition/develop-selection-pins.mjs

@@ -17,14 +17,20 @@ export function parseSelectionPins(document, path, flag, members) {
   if (pins === null || typeof pins !== 'object' || Array.isArray(pins)) {
     throw new Error(`${flag} ${path} has no "pins" object`);
   }
-  for (const [repo, commit] of Object.entries(pins)) {
-    if (typeof commit !== 'string' || !/^[0-9a-f]{40}$/.test(commit)) {
-      throw new Error(`${flag} ${path}: pin ${JSON.stringify(repo)} is not a 40-hex commit: ${JSON.stringify(commit)}`);
-    }
-  }
+  assertCommitPins(pins, `${flag} ${path}`);
   if (members !== undefined) {
     const problem = currentResolutionProblem(document.currentResolution, members);
     if (problem !== null) {throw new Error(`${flag} ${path}: ${problem}`);}
   }
   return pins;
 }
+
+/** A pin map's every value is a 40-hex commit (a selection's pins, follow's --current-pins); returns it. `label` names the input. */
+export function assertCommitPins(pins, label) {
+  for (const [key, commit] of Object.entries(pins)) {
+    if (typeof commit !== 'string' || !/^[0-9a-f]{40}$/.test(commit)) {
+      throw new Error(`${label}: pin ${JSON.stringify(key)} is not a 40-hex commit: ${JSON.stringify(commit)}`);
+    }
+  }
+  return pins;
+}

package/edition/distribution-evidence-set.mjs

@@ -829,6 +829,8 @@ export function buildImageDeliveryEntitlementStatement({
       lockDigest: schemas.distributionLockDigest(distributionLock),
       // Present-and-nullable: null states the lock carries no catalogue; the lock digest binds the lock either way.
       catalogueDigest: distributionLock.catalogueDigest ?? null,
+      // The field the lock carries, never both: a catalogue-free lock's catalogueContentDigest.
+      ...(distributionLock.catalogueContentDigest === undefined ? {} : { catalogueContentDigest: distributionLock.catalogueContentDigest }),
       distributionStatementDigest: completenessStatementDigest,
       mode,
       targetRegistry,

package/edition/edition-artifact.mjs

@@ -19,6 +19,7 @@ import { assertCanonicalDistributionId } from './distribution-paths.mjs';
 import { EDITION_CHART_SET_FILE, assertRosteredChartSetLock } from './edition-chart-set.mjs';
 import {
   CATALOGUE_PIN_KEY,
+  CustomerPinForm,
   DEFINITION_PIN_KEY,
   DIGEST_PIN_KEYS,
   EDITION_DESCRIPTOR_FILE,
@@ -31,11 +32,13 @@ import {
   EditionLockFile,
   SEALED_EDITION_CHANNEL,
   SEAL_OF_PATTERN,
+  VENDOR_MEMBER_PIN_PATTERN,
   admittedEvidenceTrustStates,
+  customerPinFormAdmitted,
 } from './edition-constants.mjs';
 import { dataRoot, editionsRoot } from './edition-workspace.mjs';
 import { serializeJson, sha256Hex } from './lib.mjs';
-import { sortedSnapshotPins } from './pin-source.mjs';
+import { isSourcePinKey, sortedSnapshotPins } from './pin-source.mjs';
 import { readStrictJsonFile } from './strict-json.mjs';
 
 /** Which GitHub Actions run produced the artifact; recorded in its descriptor. */
@@ -119,6 +122,45 @@ const exactKeys = (value, keys, where) => {
   }
 };
 
+/**
+ * The closed customer pin rule (edition-contract.json provenancePins.customerForms). A descriptor whose pins carry the
+ * definition pin is a customer edition, and it carries exactly one form: the CATALOGUE form (the catalogue pin, the
+ * definition pin and sources/<name> commits, nothing else), or the CATALOGUE-FREE form (no catalogue pin, at least one
+ * vendor member pin), each only on the kinds and channels the contract admits it on. A descriptor without the definition
+ * pin is not a customer edition and the rule does not apply to it.
+ */
+export function assertCustomerPinForm(kind, channel, pins, distributionId) {
+  if (!(DEFINITION_PIN_KEY in pins)) {
+    // only a customer edition records a vendor side: every other edition carries neither form's marker
+    if (CATALOGUE_PIN_KEY in pins) {
+      throw new Error(`${EDITION_DESCRIPTOR_FILE}: the ${kind} ${channel} edition "${distributionId}" carries the catalogue pin without the definition pin: only a customer edition (the definition pin) records the catalogue it was resolved against`);
+    }
+    return;
+  }
+  const where = `${EDITION_DESCRIPTOR_FILE}: the customer ${kind} ${channel} edition "${distributionId}"`;
+  if (CATALOGUE_PIN_KEY in pins) {
+    if (!customerPinFormAdmitted(CustomerPinForm.Catalogue, kind, channel)) {
+      throw new Error(`${where} carries the catalogue pin, but the contract admits the catalogue form on no ${kind} ${channel} edition`);
+    }
+    const stray = Object.keys(pins).filter((key) => key !== CATALOGUE_PIN_KEY && key !== DEFINITION_PIN_KEY && !isSourcePinKey(key));
+    if (stray.length > 0) {
+      throw new Error(`${where} carries the catalogue pin and also ${stray.map((key) => JSON.stringify(key)).join(', ')}: the catalogue form pins only the catalogue, the definition and sources/<name>`);
+    }
+    return;
+  }
+  if (!customerPinFormAdmitted(CustomerPinForm.CatalogueFree, kind, channel)) {
+    throw new Error(`${where} carries no catalogue pin: only a ${catalogueFreeAdmissions()} customer edition may be resolved catalogue-free`);
+  }
+  if (!Object.keys(pins).some((key) => VENDOR_MEMBER_PIN_PATTERN.test(key))) {
+    throw new Error(`${where} carries neither the catalogue pin nor a vendor member pin: a catalogue-free edition records the vendor member pins it was resolved from`);
+  }
+}
+
+const catalogueFreeAdmissions = () =>
+  Object.values(EditionKind)
+    .flatMap((kind) => Object.values(EditionChannel).filter((channel) => customerPinFormAdmitted(CustomerPinForm.CatalogueFree, kind, channel)).map((channel) => `${kind} ${channel}`))
+    .join(' or ');
+
 /**
  * The strict parse of a descriptor: exact keys, the closed kind enum (no default, never inferred), `sealOf` exactly on a
  * sealed edition, closed vocabularies, the evidence trust state the contract admits for the kind on the channel, an engine
@@ -164,6 +206,7 @@ export function parseEditionDescriptor(value) {
       );
     }
   }
+  assertCustomerPinForm(value.kind, value.provenance.channel, pins, value.distributionId);
   exactKeys(workflow, ['repository', 'runId'], `${EDITION_DESCRIPTOR_FILE} provenance.workflow`);
   if (!workflow.repository || !workflow.runId || typeof workflow.repository !== 'string' || typeof workflow.runId !== 'string') {
     throw new Error(`${EDITION_DESCRIPTOR_FILE}: provenance.workflow is {repository, runId}, both non-empty strings`);

package/edition/edition-constants.mjs

@@ -6,7 +6,7 @@
 
 import { EditionChannel } from './edition-channel.mjs';
 import { EDITION_CHART_SET_FILE } from './edition-chart-set.mjs';
-import { parseEditionContract } from './edition-contract-parse.mjs';
+import { CustomerPinForm, parseEditionContract } from './edition-contract-parse.mjs';
 import editionContract from './edition-contract.json' with { type: 'json' };
 import { EditionKind, EvidenceTrustState } from './edition-kind.mjs';
 
@@ -40,7 +40,7 @@ export const EDITION_REPOSITORY_SEGMENTS = Object.freeze(
   Object.fromEntries(Object.values(EditionChannel).map((channel) => [channel, EDITION_CONTRACT.repositories[channel].namespaceSegment])),
 );
 
-export { EditionChannel, EditionKind, EvidenceTrustState };
+export { CustomerPinForm, EditionChannel, EditionKind, EvidenceTrustState };
 
 /**
  * The evidence trust states an edition of `kind` on `channel` may record (contract `evidenceTrust.statesByKind`):
@@ -72,9 +72,29 @@ if (!(DEFINITION_PIN_KEY in EDITION_CONTRACT.provenancePins)) {
   throw new Error('edition-contract.json provenancePins does not declare the definition pin');
 }
 
+/**
+ * The commit of the customer definition repository a catalogue-free customer edition's definition was read at: a pin of
+ * the catalogue-free form only (provenancePins.customerForms["catalogue-free"].pins names it), a 40-hex commit.
+ */
+export const DEFINITION_REPOSITORY_PIN_KEY = 'definition-repository';
+if (!EDITION_CONTRACT.provenancePins.customerForms['catalogue-free'].pins.includes(`"${DEFINITION_REPOSITORY_PIN_KEY}"`)) {
+  throw new Error(`edition-contract.json provenancePins.customerForms["catalogue-free"].pins does not name the "${DEFINITION_REPOSITORY_PIN_KEY}" pin`);
+}
+
 /** The provenance pins that are sha256 digests, not commits. */
 export const DIGEST_PIN_KEYS = Object.freeze([CATALOGUE_PIN_KEY, DEFINITION_PIN_KEY]);
 
+/**
+ * The key of a vendor member (develop graph repository) pin, `repos/<x>` or `submodules/<x>`: the one statement is the
+ * contract's (provenancePins.customerForms.vendorMemberPinPattern); the snapshot pin namespaces read it from here.
+ */
+export const VENDOR_MEMBER_PIN_PATTERN = new RegExp(EDITION_CONTRACT.provenancePins.customerForms.vendorMemberPinPattern);
+
+/** Whether the contract admits customer pin form `form` (CustomerPinForm) on an edition of `kind` and `channel`. */
+export function customerPinFormAdmitted(form, kind, channel) {
+  return EDITION_CONTRACT.provenancePins.customerForms[form].kinds[kind]?.includes(channel) === true;
+}
+
 /** The lock files an edition can carry. */
 export const EditionLockFile = Object.freeze({
   Distribution: 'distribution.lock.json',

package/edition/edition-contract-parse.mjs

@@ -91,6 +91,47 @@ function assertDescriptorVocabulary(contract) {
   }
 }
 
+/** The customer pin forms (provenancePins.customerForms), one key per form. */
+export const CustomerPinForm = Object.freeze({ Catalogue: 'catalogue', CatalogueFree: 'catalogue-free' });
+
+/**
+ * `provenancePins`: exactly the catalogue and definition pin statements and `customerForms`, the closed statement of how a
+ * customer edition records its vendor side. The catalogue form is admitted on every kind and channel a kind has (a customer
+ * edition that is not catalogue-free still requires the catalogue pin), the catalogue-free form on a subset of them; the
+ * vendor member pin pattern is an anchored regular expression.
+ */
+function assertProvenancePins(contract) {
+  const pins = contract.provenancePins;
+  const texts = ['catalogue', 'definition'];
+  if (!isObject(pins) || !sameSet(Object.keys(pins), [...texts, 'customerForms']) || !texts.every((key) => typeof pins[key] === 'string' && pins[key] !== '')) {
+    throw new Error('edition-contract.json: "provenancePins" must be exactly {catalogue, definition, customerForms}');
+  }
+  const forms = pins.customerForms;
+  const formNames = Object.values(CustomerPinForm);
+  if (!isObject(forms) || !sameSet(Object.keys(forms), ['names', 'vendorMemberPinPattern', ...formNames]) || typeof forms.names !== 'string' || forms.names === '') {
+    throw new Error(`edition-contract.json: provenancePins.customerForms must be exactly {names, vendorMemberPinPattern, ${formNames.join(', ')}}`);
+  }
+  assertAnchoredPattern(forms.vendorMemberPinPattern, 'provenancePins.customerForms.vendorMemberPinPattern');
+  const channelsOf = { [EditionKind.Resolved]: Object.values(EditionChannel), [EditionKind.Sealed]: [contract.sealOf.channel] };
+  for (const name of formNames) {
+    const form = forms[name];
+    if (!isObject(form) || !sameSet(Object.keys(form), ['pins', 'kinds']) || typeof form.pins !== 'string' || form.pins === '' || !isObject(form.kinds)) {
+      throw new Error(`edition-contract.json: provenancePins.customerForms.${name} must be exactly {pins, kinds}`);
+    }
+    for (const [kind, channels] of Object.entries(form.kinds)) {
+      const own = channelsOf[kind];
+      if (own === undefined || !Array.isArray(channels) || channels.length === 0 || new Set(channels).size !== channels.length || !channels.every((channel) => own.includes(channel))) {
+        throw new Error(`edition-contract.json: provenancePins.customerForms.${name}.kinds.${kind} must be a non-empty set of the channels of a ${kind} edition`);
+      }
+    }
+  }
+  for (const [kind, own] of Object.entries(channelsOf)) {
+    if (!sameSet(forms[CustomerPinForm.Catalogue].kinds[kind], own)) {
+      throw new Error(`edition-contract.json: provenancePins.customerForms.catalogue.kinds.${kind} must name every channel of a ${kind} edition (${own.join(' | ')}): the catalogue form is the default form`);
+    }
+  }
+}
+
 const SEGMENT = /^[a-z0-9][a-z0-9.-]*$/;
 
 /** The strict parse of the contract; returns it unchanged. */
@@ -133,5 +174,6 @@ export function parseEditionContract(contract) {
     throw new Error('edition-contract.json: the channels\' namespace segments must differ');
   }
   assertDescriptorVocabulary(contract);
+  assertProvenancePins(contract);
   return contract;
 }

package/edition/edition-contract.json

@@ -35,7 +35,24 @@
   },
   "provenancePins": {
     "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"
+    "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",
+    "customerForms": {
+      "names": "a customer edition is one whose pins carry the definition pin. It records its vendor side in exactly one form, closed per kind and channel: the catalogue form, or the catalogue-free form. Every other edition carries neither form's marker: no catalogue pin. The kinds and channels each form admits are enforced by the writers and this CLI's readers (the descriptor parse); the catalogue-free form being develop only also rests on only the develop resolve identity being able to sign one. The deploy root's admission does not enforce the forms: it re-vendors this contract and reads neither provenancePins nor the forms",
+      "catalogue": {
+        "pins": "the catalogue pin, the definition pin, and a sources/<name> commit per source the definition declares; nothing else. The distribution lock names the catalogue artifact by catalogueDigest, never by catalogueContentDigest",
+        "kinds": {
+          "resolved": ["develop", "release"],
+          "sealed": ["release"]
+        }
+      },
+      "catalogue-free": {
+        "pins": "no catalogue pin: the vendor side was resolved from the vendor members in the same call, so the edition records the vendor member pins (keys matching vendorMemberPinPattern, at least one) as 40-hex commits, beside the definition pin, the \"definition-repository\" commit (the commit of the customer definition repository the definition was read at), the sources/<name> commits and the other 40-hex pins of the resolve. The catalogue the vendor step wrote is named in the distribution lock only, by catalogueContentDigest (sha256 of its exact catalogue.json bytes, kernel edition protocol v37), never by catalogueDigest: no catalogue artifact exists",
+        "kinds": {
+          "resolved": ["develop"]
+        }
+      },
+      "vendorMemberPinPattern": "^(?:repos|submodules)/[a-z0-9][a-z0-9-]*$"
+    }
   },
   "imageNamespaceSegment": "dev",
   "evidenceTrust": {

package/edition/image-evidence.mjs

@@ -1,4 +1,5 @@
 import { execFileSync } from 'node:child_process';
+import { X509Certificate, createPublicKey } from 'node:crypto';
 import {
   mkdtempSync,
   readFileSync,
@@ -126,6 +127,76 @@ export function validatePinnedTrustedRoot(policyRoot, policy) {
   return { path: trustedRoot, bytes: rootBytes };
 }
 
+/** The one transparency log a CLASSIC (`.sig` / `.att`) cosign signature is entered in: Rekor v1 of the public good instance. */
+const CLASSIC_REKOR_BASE_URL = 'https://rekor.sigstore.dev';
+const STRICT_BASE64 = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/u;
+
+const pemOf = (label, der) => `-----BEGIN ${label}-----\n${der.toString('base64').match(/.{1,64}/gu).join('\n')}\n-----END ${label}-----\n`;
+const isOpen = (entry) => entry?.validFor?.end === undefined;
+
+function derOf(rawBytes, what) {
+  if (typeof rawBytes !== 'string' || rawBytes.length === 0 || !STRICT_BASE64.test(rawBytes)) {
+    throw new Error(`Sigstore trusted root: ${what} rawBytes is not base64 DER`);
+  }
+  return Buffer.from(rawBytes, 'base64');
+}
+
+function publicKeyPem(entry, what) {
+  const der = derOf(entry?.publicKey?.rawBytes, what);
+  try {
+    createPublicKey({ key: der, format: 'der', type: 'spki' });
+  } catch {
+    throw new Error(`Sigstore trusted root: ${what} is not a DER SubjectPublicKeyInfo`);
+  }
+  return pemOf('PUBLIC KEY', der);
+}
+
+/**
+ * The classic cosign trust material of the pinned Sigstore trusted root, derived deterministically from its bytes (the
+ * output of `validatePinnedTrustedRoot`): what cosign's classic verification reads from `SIGSTORE_ROOT_FILE`,
+ * `SIGSTORE_REKOR_PUBLIC_KEY` and `SIGSTORE_CT_LOG_PUBLIC_KEY_FILE` when it cannot take `--trusted-root` (cosign 2.6
+ * `verify-attestation` accepts `--trusted-root` only with `--new-bundle-format`, which classic `.att` attestations are
+ * not). Only material still open is kept (no `validFor.end`): the Fulcio certificate chains of every open certificate
+ * authority (at least one), exactly one open Rekor v1 log (`https://rekor.sigstore.dev`; later logs carry new-format
+ * entries only) and exactly one open CT log. Any other count is refused.
+ *
+ * @returns {{fulcioPem: string, rekorPem: string, ctLogPem: string}}
+ */
+export function classicCosignTrustMaterial(rootBytes) {
+  const root = JSON.parse(decodeExactUtf8(rootBytes, 'Sigstore trusted root'));
+  const listOf = (key) => (Array.isArray(root?.[key]) ? root[key] : []);
+  const authorities = listOf('certificateAuthorities').filter(isOpen);
+  if (authorities.length === 0) {
+    throw new Error('Sigstore trusted root: no open Fulcio certificate authority (certificateAuthorities without validFor.end)');
+  }
+  const fulcioPem = authorities
+    .flatMap((authority, index) => {
+      const certificates = authority?.certChain?.certificates;
+      if (!Array.isArray(certificates) || certificates.length === 0) {
+        throw new Error(`Sigstore trusted root: open certificate authority ${index} has no certificate chain`);
+      }
+      return certificates.map((certificate) => {
+        const der = derOf(certificate?.rawBytes, `certificate authority ${index} certificate`);
+        try {
+          new X509Certificate(der);
+        } catch {
+          throw new Error(`Sigstore trusted root: certificate authority ${index} holds a certificate that is not DER X.509`);
+        }
+        return pemOf('CERTIFICATE', der);
+      });
+    })
+    .join('');
+  const rekor = listOf('tlogs').filter((log) => log?.baseUrl === CLASSIC_REKOR_BASE_URL && isOpen(log?.publicKey));
+  if (rekor.length !== 1) {
+    throw new Error(`Sigstore trusted root: ${rekor.length} open Rekor v1 logs (${CLASSIC_REKOR_BASE_URL}); exactly one is required`);
+  }
+  const ctLogs = listOf('ctlogs').filter((log) => isOpen(log?.publicKey));
+  if (ctLogs.length !== 1) {
+    throw new Error(`Sigstore trusted root: ${ctLogs.length} open CT logs (ctlogs without validFor.end); exactly one is required`);
+  }
+  return { fulcioPem, rekorPem: publicKeyPem(rekor[0], 'the Rekor v1 log key'), ctLogPem: publicKeyPem(ctLogs[0], 'the CT log key') };
+}
+
 function assertTimeWindow({ issuedAt, expiresAt, now, maxTtlSeconds, label }) {
   const issued = Date.parse(issuedAt);
   const expires = Date.parse(expiresAt);

package/edition/pin-source.mjs

@@ -23,6 +23,7 @@
 
 import { developGraphMembers } from './develop-graph.mjs';
 import { workspaceSection } from './edition-config.mjs';
+import { VENDOR_MEMBER_PIN_PATTERN } from './edition-constants.mjs';
 import { compareStrings } from './lib.mjs';
 import { PinRole } from './workspace-sections.mjs';
 
@@ -55,7 +56,8 @@ export const dataPinKey = () => pinKeyOf(PinRole.Data);
 export const kernelPinKey = () => pinKeyOf(PinRole.Kernel);
 export const deployPinKey = () => pinKeyOf(PinRole.Deploy);
 const SOURCE_PIN_PREFIX = 'sources/';
-const GRAPH_PIN_PATTERN = /^(?:repos|submodules)\/[a-z0-9][a-z0-9-]*$/;
+// A graph pin key is a vendor member pin key: the pattern is the edition contract's (customerForms.vendorMemberPinPattern).
+const GRAPH_PIN_PATTERN = VENDOR_MEMBER_PIN_PATTERN;
 
 /** The snapshot key of one declared `sources[]` entry. */
 export function sourcePinKey(name) {

package/edition/record-refused.mjs

@@ -3,8 +3,9 @@
 // selection can both subclass it. A registry, cosign or git that could not answer is a plain Error instead.
 
 export class RecordRefused extends Error {
-  constructor(repo, message) {
-    super(`select-records: ${repo}: ${message}`);
+  /** `context` labels the verb the refusal surfaces in (select-records by default, `follow` for its sources). */
+  constructor(repo, message, context = 'select-records') {
+    super(`${context}: ${repo}: ${message}`);
     this.name = 'RecordRefused';
     this.repo = repo;
   }

package/edition/repin-evidence-trust.mjs

@@ -98,7 +98,8 @@ if (isEntryModule(import.meta.url)) {
     const pin = await repinEvidenceTrust(parseRepinArguments(process.argv.slice(2)));
     console.log(
       `[repin-evidence-trust] pinned policy ${pin.policyDigest}, verifier ${pin.verifier.bundleDigest}, ` +
-        `kernel contract authority ${pin.kernelContractAuthority.sourceCommit} and ` +
+        // A customer data root states no kernel contract authority: its pin records none.
+        `kernel contract authority ${pin.kernelContractAuthority === null ? 'none' : pin.kernelContractAuthority.sourceCommit} and ` +
         `${pin.trustedOrasBinaryDigests.length} oras binary digest(s)`,
     );
   } catch (error) {

package/edition/resolve-customer-edition.mjs

@@ -20,6 +20,7 @@ import { isDeepStrictEqual } from 'node:util';
 
 import { adapterHostRow, assertAdapterBundlesMatchHost, fetchRegistryManifest } from './adapter-bundled-versions.mjs';
 import { AUTHORIZATION_LOCK_FILENAME, writeAuthorizationLock } from './authorization-base.mjs';
+import { catalogueLockFieldOf } from './catalogue-lock-field.mjs';
 import {
   assertCustomerLockWithinCatalogueCeiling,
   CatalogueCeilingError,
@@ -33,8 +34,9 @@ import {
   parseCustomerDefinition,
   parseImageRegistryMirror,
 } from './customer-definition.mjs';
+import { assertNoUnverifiedRequiredGitBundles } from './develop-git-bundles.mjs';
 import { assertRosteredChartSetLock } from './edition-chart-set.mjs';
-import { EditionLockFile } from './edition-constants.mjs';
+import { EditionChannel, EditionLockFile } from './edition-constants.mjs';
 import { editionsRoot } from './edition-workspace.mjs';
 import { subjectServingBiome } from './image-lock-service-rows.mjs';
 import { adoptCatalogueKernel } from './kernel-package.mjs';
@@ -212,8 +214,29 @@ export function assertVendorRowsAreCatalogueRows({ catalogue, imageLock, lock, m
   }
 }
 
-/** The customer's image lock: vendor rows copied (and mirrored), own rows resolved (and sealed by `sealOwn`, which takes and returns subjects), the merged lock parsed once. */
-export async function resolveCustomerImages({ id, catalogue, lock, composed, schemas, inputs, sealOwn }) {
+/**
+ * The customer's OWN lineage of a previous images lock: `previousLock` (the customer edition's own last images lock, its
+ * id already held to this edition's) narrowed to the composed-process rows every owner of which is one of this lock's
+ * own (customer-sourced) biomes. The vendor rows of a customer lock are the catalogue's (assertVendorRowsAreCatalogueRows)
+ * and carry the vendor's generations, never the customer's, so they never enter the customer's own carry-forward.
+ * Null (a first seal) stays null.
+ */
+export function ownComposedPreviousLock(previousLock, lock, enums) {
+  if (previousLock === null) {return null;}
+  const ownBiomes = new Set(lock.biomes.filter((biome) => biome.source !== undefined).map((biome) => biome.id));
+  const own = (subject) =>
+    subject.kind === enums.RuntimeImageSubjectKind.ComposedProcess &&
+    subject.owners.length > 0 &&
+    subject.owners.every((owner) => owner.kind === enums.RuntimeImageOwnerKind.Biome && ownBiomes.has(owner.biomeId));
+  return { ...previousLock, subjects: previousLock.subjects.filter(own) };
+}
+
+/**
+ * The customer's image lock: vendor rows copied (and mirrored), own rows resolved (and sealed by `sealOwn`, which takes
+ * and returns subjects), the merged lock parsed once. `previousLock` (the customer's own previous seal, null for a first
+ * seal) carries the own composed artifacts' generations forward (ownComposedPreviousLock).
+ */
+export async function resolveCustomerImages({ id, catalogue, lock, composed, schemas, inputs, sealOwn, previousLock = null }) {
   const vendor = projectVendorImages(catalogue, lock, schemas);
   const vendorSubjects = mirrorVendorSubjects(vendor.subjects, composed.mirror);
   const ownBiomes = lock.biomes.filter((biome) => biome.source !== undefined);
@@ -231,7 +254,7 @@ export async function resolveCustomerImages({ id, catalogue, lock, composed, sch
       buildStepContextDirectories: [],
     };
     // The own rows are ROWS, not a lock: the one parse is of the merged lock below.
-    own = await resolveImageRows(id, { inputs: { ...inputs, runtimeImageSourceIndex, composed }, lock: ownLock });
+    own = await resolveImageRows(id, { inputs: { ...inputs, runtimeImageSourceIndex, composed }, lock: ownLock, previousLock: ownComposedPreviousLock(previousLock, lock, schemas) });
     // A source that builds no image (a web biome) has no row to seal.
     if (sealOwn !== undefined && own.subjects.length > 0) {own = { ...own, subjects: await sealOwn({ distributionId: id, subjects: own.subjects }) };}
   }
@@ -257,19 +280,26 @@ export async function resolveCustomerImages({ id, catalogue, lock, composed, sch
 
 /**
  * The distribution and authorization locks of the customer edition `rawDefinition`
- * against `catalogue`. `catalogueDigest` is the digest of `catalogue`, written into the lock. `adoptKernel` (the catalogue's kernel from npm, proved its contract authority; returns the kernel schemas) and `materialize` are injectable for the test suites.
+ * against `catalogue`. Exactly one of `catalogueDigest` (a published catalogue artifact) and `catalogueContentDigest` (the
+ * catalogue bytes of a catalogue-free resolve) names `catalogue`; it is written into the lock under its own key. `adoptKernel` (the catalogue's kernel from npm, proved its contract authority; returns the kernel schemas) and `materialize` are injectable for the test suites.
  */
 export async function resolveCustomerDistribution({
   rawDefinition,
   catalogue,
   catalogueDigest,
+  catalogueContentDigest,
   sourceImages,
   pins,
   materialize,
   adoptKernel = adoptCatalogueKernel,
   fetchManifest = fetchRegistryManifest,
+  developGitBundles,
 }) {
-  if (catalogueDigest === undefined) {throw new CatalogueError('a customer resolve names the digest of its catalogue');}
+  const catalogueField = catalogueLockFieldOf({ catalogueDigest, catalogueContentDigest }, { what: 'a customer resolve', ErrorType: CatalogueError });
+  // Only a develop edition carries a git-sourced OCI bundle (develop-git-bundles.mjs); a release never verifies one.
+  if (developGitBundles !== undefined && catalogue.channel !== EditionChannel.Develop) {
+    throw new Error(`a git-sourced bundle verifier is a develop resolve's; the catalogue "${catalogue.offeringId}" is ${catalogue.channel}`);
+  }
   const schemas = await adoptKernel(catalogue);
   const { definition, mirror } = parseCustomerDefinition(schemas, rawDefinition);
   const composed = composeCustomerEdition({ schemas, definition, mirror, catalogue, sourceImages, pins });
@@ -284,6 +314,8 @@ export async function resolveCustomerDistribution({
     platformServiceIndex: { schemaVersion: 1, services: catalogue.platformServices },
     sourcesAvailable: false,
     storePublisherTrust: selectedStorePublisherTrust(catalogueCeiling(catalogue, schemas).storePublisherTrust, definition.storePublisherAnchorKeys),
+    // A develop resolve under a declared customer policy verifies its git-sourced OCI bundles and keeps them (by digest, with the signer).
+    ...(developGitBundles === undefined ? {} : { developGitBundles }),
   };
   let resolved;
   try {
@@ -295,6 +327,9 @@ export async function resolveCustomerDistribution({
     throw error;
   }
   const { lock, index } = resolved;
+  // Without a verifier no git-sourced OCI bundle is verified, so a required row that declares one is refused, never stripped.
+  // With one, resolve-distribution already refuses every such row it did not verify.
+  if (developGitBundles === undefined) {assertNoUnverifiedRequiredGitBundles({ lock, index, required: schemas.BiomeInstallPolicy.Required });}
   assertTrustCeilingAssignsCustomerBiomes(
     schemas,
     definition,
@@ -306,14 +341,19 @@ export async function resolveCustomerDistribution({
   await assertAdapterBundlesMatchHost({ lock, hostRow: adapterHostRow(catalogue.biomes), fetchManifest });
   const authorizationLock = await composeAuthorizationBase(id, lock, index);
   // A customer lock names the catalogue it was resolved against; seal and verify refuse any other.
-  return { id, schemas, composed, inputs, lock: { ...lock, catalogueDigest }, authorizationLock, storePublisherAnchorKeys };
+  return { id, schemas, composed, inputs, lock: { ...lock, [catalogueField.key]: catalogueField.digest }, authorizationLock, storePublisherAnchorKeys };
 }
 
-/** Resolve the customer edition of `channel` against `catalogue`; returns the four locks. `sealOwn` seals the customer's OWN image rows only (a develop edition); vendor rows arrive sealed. */
+/**
+ * Resolve the customer edition of `channel` against `catalogue`; returns the four locks. `sealOwn` seals the customer's OWN
+ * image rows only (a develop edition); vendor rows arrive sealed. `previousSeal` answers the customer's own previous seal
+ * (resolvePreviousSeal under this edition's id: null for a first seal), read only after the catalogue's kernel is adopted
+ * (it parses with that kernel); its own composed artifacts carry their generation forward. Absent: a first seal.
+ */
 export async function resolveCustomerEdition(request) {
   const { id, schemas, composed, inputs, lock, authorizationLock, storePublisherAnchorKeys } = await resolveCustomerDistribution(request);
   const { catalogue } = request;
-  const imageLock = await resolveCustomerImages({ id, catalogue, lock, composed, schemas, inputs, sealOwn: request.sealOwn });
+  const imageLock = await resolveCustomerImages({ id, catalogue, lock, composed, schemas, inputs, sealOwn: request.sealOwn, previousLock: request.previousSeal === undefined ? null : await request.previousSeal(id) });
   // The chart-set is copied whole, so it carries the coordinates of the channel it was published on:
   // the edition being written states its channel, and a chart-set of the other one is refused here.
   const chartSetLock = assertRosteredChartSetLock(catalogue.chartSet, `the catalogue's chart-set of "${catalogue.offeringId}"`);

package/edition/resolve-distribution.mjs

@@ -1823,7 +1823,8 @@ export function resolveUnadmittedDistributionFromInputs(
   //     resolve verified for it (`develop-git-bundles.mjs`: the develop signer at the attested commit, content-bound to
   //     the frozen one), by digest, and its develop bundle signer. A git-sourced OCI row the resolve did not verify is
   //     refused, never stripped;
-  //   - otherwise (release, customer, dist-check) it carries neither, as before; the release refuses the declaration.
+  //   - otherwise (release, customer, dist-check) it carries neither, as before; the release refuses the declaration,
+  //     and a customer resolve refuses it on a required row (develop-git-bundles.mjs `assertNoUnverifiedRequiredGitBundles`).
   // An OCI host-module bundle on a git-sourced biome is refused below in every channel. (An entry of a declared `oci`
   // source has a stamp but no record: not git.)
   const isGitSourced = (e) => e.source !== undefined && sourceRecords.has(e.source);

package/edition/resolve-edition.mjs

@@ -158,6 +158,9 @@ export function parseCustomerResolveArgs(args) {
   if (!Object.values(EditionChannel).includes(values.get(CHANNEL_FLAG))) {
     throw new Error(`${CHANNEL_FLAG} must be one of ${Object.values(EditionChannel).join(' | ')}`);
   }
+  if (values.get(CHANNEL_FLAG) === EditionChannel.Develop) {
+    throw new Error(`${DEFINITION_FLAG} with ${CHANNEL_FLAG} develop is refused here: this verb takes no previous seal, so the customer's own composed rows would restart at generation 1; use xema edition develop resolve ${DEFINITION_FLAG} <file> --previous-lock <file> --previous-lock-sha256 <hex> | --first-seal`);
+  }
   return { values, sourceImages: parseSourceImages(sourceImages) };
 }