@xemahq/xema 0.58.0 → 0.59.1

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/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,
@@ -213,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);
@@ -232,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 }) };}
   }
@@ -258,12 +280,14 @@ 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,
@@ -271,7 +295,7 @@ export async function resolveCustomerDistribution({
   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}`);
@@ -317,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-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) };
 }
 

package/edition/resolve-images.mjs

@@ -947,16 +947,24 @@ export function structureSubjects(structure) {
  * entrypoint, owned by the biomes whose services it carries. Neither the kernel
  * nor the SDK fixes WHERE a repository builds it, so this plane does, once:
  *
- *   - the image directory is `infra/composed-process/` at the repository root,
- *     holding its own `Dockerfile` and an `image-build-inputs.json` whose
+ *   - the image directory is the per-class directory
+ *     `infra/composed-process/<class>/` at the repository root (`<class>` a
+ *     kernel `ComposedImageClass`; an edition addresses one composed subject
+ *     per repository, of the kernel's `DEFAULT_COMPOSED_IMAGE_CLASS`). A commit
+ *     that predates the per-class layout declares it at the legacy root
+ *     `infra/composed-process/`, which stays readable because committed release
+ *     locks still pin such commits. Both at once, or a declaration in another
+ *     class directory, is refused (`composedProcessDeclarationDir`). The
+ *     directory holds its own `Dockerfile` and an `image-build-inputs.json` whose
  *     `workspacePackages` lists every member service's workspace package
  *     directory — the Dockerfile-only image shape `hashImageBuildInputs`
  *     already reads (`opencode-worker` is the other one). Its tag is therefore
  *     an ordinary `xema-image-input-sha256-v2` key, computed by the one
  *     implementation every producer uses, with `SERVICE` = the subject id and
  *     `SERVICE_PATH` = this directory;
- *   - the DECLARATION is that `image-build-inputs.json` existing at the pinned
- *     commit. A repository that declares none has no composed image, and an
+ *   - the DECLARATION is that `image-build-inputs.json` existing in that
+ *     directory at the pinned commit. A repository that declares none (and has
+ *     no `infra/composed-process/` tree at all) has no composed image, and an
  *     edition carries no composed subject for it — which the deploy plane
  *     reports as "the producer builds no composed-process image at that
  *     commit". That is an honest absence, not a skipped subject: a DECLARED
@@ -1045,8 +1053,8 @@ function declaredImageClass(declared, subject, enums) {
   return parsed.data;
 }
 
-function composedProcessCarriage(structure, enums, repo, sourceCommit, locate) {
-  const inputsPath = `${COMPOSED_PROCESS_IMAGE_PATH}/${COMPOSED_PROCESS_DECLARATION_FILE}`;
+function composedProcessCarriage(structure, enums, repo, sourceCommit, locate, declarationDir) {
+  const inputsPath = `${declarationDir}/${COMPOSED_PROCESS_DECLARATION_FILE}`;
   const { dir } = locate(repo);
   let members;
   try {
@@ -1098,6 +1106,60 @@ function composedProcessCarriage(structure, enums, repo, sourceCommit, locate) {
     .sort((a, b) => compareStrings(a.biomeId, b.biomeId));
 }
 
+function gitPathExistsAtCommit(dir, sourceCommit, repoPath) {
+  try {
+    execFileSync('git', ['-C', dir, 'cat-file', '-e', `${sourceCommit}:${repoPath}`], {
+      stdio: ['ignore', 'ignore', 'ignore'],
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The repo-relative directory holding a repository's composed-process
+ * DECLARATION at one commit, or null when it declares none. The default class's
+ * directory and the legacy root are the two places an edition reads; a
+ * declaration it cannot address (both present, another class, an
+ * `infra/composed-process/` tree without a recognised one) is refused, because
+ * a declaration the resolver cannot find must never read as "declares nothing".
+ */
+function composedProcessDeclarationDir(dir, sourceCommit, enums) {
+  const defaultClass = enums.DEFAULT_COMPOSED_IMAGE_CLASS;
+  const classDir = `${COMPOSED_PROCESS_IMAGE_PATH}/${defaultClass}`;
+  const declares = (candidate) =>
+    gitPathExistsAtCommit(dir, sourceCommit, `${candidate}/${COMPOSED_PROCESS_DECLARATION_FILE}`);
+  const inClassDir = declares(classDir);
+  const atLegacyRoot = declares(COMPOSED_PROCESS_IMAGE_PATH);
+  if (inClassDir && atLegacyRoot) {
+    throw new ComposedProcessInputsError(
+      `ambiguous composed-process declaration at ${sourceCommit}: both "${classDir}/${COMPOSED_PROCESS_DECLARATION_FILE}" ` +
+        `and the legacy "${COMPOSED_PROCESS_IMAGE_PATH}/${COMPOSED_PROCESS_DECLARATION_FILE}" exist`,
+    );
+  }
+  const otherClasses = enums.ComposedImageClassSchema.options
+    .filter((candidate) => candidate !== defaultClass)
+    .filter((candidate) => declares(`${COMPOSED_PROCESS_IMAGE_PATH}/${candidate}`));
+  if (otherClasses.length > 0) {
+    throw new ComposedProcessInputsError(
+      `composed-process declaration at ${sourceCommit} is in the "${otherClasses.join('", "')}" class ` +
+        `director${otherClasses.length > 1 ? 'ies' : 'y'}, but an edition addresses one composed-process subject per ` +
+        `repository, of the default class "${defaultClass}"; a "${otherClasses[0]}" image has no subject naming yet`,
+    );
+  }
+  if (inClassDir) {return classDir;}
+  if (atLegacyRoot) {return COMPOSED_PROCESS_IMAGE_PATH;}
+  if (gitPathExistsAtCommit(dir, sourceCommit, COMPOSED_PROCESS_IMAGE_PATH)) {
+    throw new ComposedProcessInputsError(
+      `"${COMPOSED_PROCESS_IMAGE_PATH}" exists at ${sourceCommit} but declares no composed-process image the edition can ` +
+        `read: looked at "${classDir}/${COMPOSED_PROCESS_DECLARATION_FILE}" and ` +
+        `"${COMPOSED_PROCESS_IMAGE_PATH}/${COMPOSED_PROCESS_DECLARATION_FILE}"`,
+    );
+  }
+  return null;
+}
+
 /**
  * Read each repository's composed-process DECLARATION at the commit the
  * edition builds its services from. Only repositories that contribute a
@@ -1119,7 +1181,6 @@ export function readComposedProcessDeclarations(
   const declarations = [];
   for (const [repo, sourceCommit] of [...commits].sort(([a], [b]) => compareStrings(a, b))) {
     const { dir, base } = locate(repo);
-    const declarationPath = `${COMPOSED_PROCESS_IMAGE_PATH}/${COMPOSED_PROCESS_DECLARATION_FILE}`;
     // ABSENCE IS ONLY AN ANSWER ABOUT A COMMIT THAT WAS READ. A repository
     // missing from this layout, or one lacking the pinned commit, would
     // otherwise read as "declares nothing", and `dist-check` would grade a lock
@@ -1135,21 +1196,17 @@ export function readComposedProcessDeclarations(
           'before resolving',
       );
     }
-    try {
-      execFileSync('git', ['-C', dir, 'cat-file', '-e', `${sourceCommit}:${declarationPath}`], {
-        stdio: ['ignore', 'ignore', 'ignore'],
-      });
-    } catch {
-      continue; // declares no composed-process image at this commit
-    }
+    const declarationDir = composedProcessDeclarationDir(dir, sourceCommit, enums);
+    if (declarationDir === null) {continue;} // declares no composed-process image at this commit
+    const declarationPath = `${declarationDir}/${COMPOSED_PROCESS_DECLARATION_FILE}`;
     const sourceId = sourceIds.get(repo);
     const repoRelative = relative(base, dir).split(sep).join('/');
     declarations.push({
       repo,
       sourceId,
       sourceCommit,
-      carriage: composedProcessCarriage(structure, enums, repo, sourceCommit, locate),
-      path: `${repoRelative}/${COMPOSED_PROCESS_IMAGE_PATH}`,
+      carriage: composedProcessCarriage(structure, enums, repo, sourceCommit, locate, declarationDir),
+      path: `${repoRelative}/${declarationDir}`,
       sourceManifestPath: `${repoRelative}/${declarationPath}`,
       sourceManifestHash: exactSourceManifestHash(dir, declarationPath, sourceCommit),
     });
@@ -2126,12 +2183,21 @@ export async function resolvePreviousSeal({ distributionId, previousLockPath, pr
         : `--previous-lock and --previous-lock-sha256 go together (one was given); give ${PREVIOUS_SEAL_USAGE}`,
     );
   }
-  const bytes = readFileSync(previousLockPath);
+  const bytes = readPreviousLockBytes(previousLockPath, previousLockSha256);
+  return parsePreviousLock(distributionId, parseStrictJson(bytes.toString('utf8'), previousLockPath), '--previous-lock');
+}
+
+/**
+ * The bytes of a previous lock file, held to the sha256 (hex) they were given with: the one check of the pair
+ * (`flags` names the pair in the refusal). The parse, with the kernel and against the edition's id, is the caller's.
+ */
+export function readPreviousLockBytes(path, sha256, flags = { lock: '--previous-lock', sha256: '--previous-lock-sha256' }) {
+  const bytes = readFileSync(path);
   const actual = createHash('sha256').update(bytes).digest('hex');
-  if (actual !== previousLockSha256) {
-    throw new Error(`--previous-lock ${previousLockPath} has sha256 ${actual}, not the given --previous-lock-sha256 ${previousLockSha256}`);
+  if (actual !== sha256) {
+    throw new Error(`${flags.lock} ${path} has sha256 ${actual}, not the given ${flags.sha256} ${sha256}`);
   }
-  return parsePreviousLock(distributionId, readStrictJsonFile(previousLockPath), '--previous-lock');
+  return bytes;
 }
 
 /** The in-repo lane's previous lock: the committed file at `outPath`, parsed before it is overwritten; null (first seal) when there is none. */