@xemahq/xema 0.58.0 → 0.59.0

package/edition/README.md

@@ -83,6 +83,8 @@ xema edition develop <freeze-sources|resolve|target|check-existing> ...
 # develop tag = sha256 of { cli, engine, pins, sourceImages }; target and check-existing take --engine-image, and a customer's --source-image
 xema edition develop coverage <id> --pins <file> --cosign <abs path> [--json]   # read-only forecast (policy held to its pin, this CLI's own verifier code): is each develop image producer-signed? exit 0 covered, 1 not, 2 error
 xema edition develop select-records --branch develop --registry <root> --cosign <abs path> --out <file> [--at <ISO-8601 UTC>] [--published-pins <file>]   # newest signed build record per graph member (the newest COMMIT on develop, every record verified; --published-pins keeps a published commit the records are not ahead of, part 07 passes it) -> { pins, snapshot, behind, images, currentResolution }, written once (a member whose firstPartySources entry declares `currentResolution: "<ticket>"`, xema-docs until XEMA-2373, is skipped with no registry read, listed in currentResolution and printed as `xema-docs: current resolution (leaves the edition, XEMA-2373)`) (behind = { <repo>: { head, commits } }: develop's head and the commits the pinned one trails it by; stdout gets one `<short name>: record <commit>, <N> commits behind HEAD` line per member, always `commits`, short name = the repo's last path segment and unambiguous; images[] entries carry `member`); any bad record refuses the run (needs dataRootRepositoryUrl in edition-workspace.json; anyone who can delete registry tags can remove newer records and this then pins the newest remaining valid one, and the guard is part 07's: deploy-latest's owner refuses a snapshot that goes backwards)
+xema edition develop follow --definition-at <owner>/<repo>,<path>,<dataRoot> --data-sha <sha> --kernel-sha <sha> --deploy-sha <upper bound> --engine-repository <registry>/<path> --registry <root> --cosign <abs path> (--first | --current-pins <file>) --out <file> --seals-out <dir> --previous-seal-signer <identity> (--previous-lock <lock> --previous-lock-sha256 <hex> | --first-seal)   # the COMPLETE frozen pins a dev deployment's follow policy selects, written once: members by select-records' newest-commit rule over their signed build records with the current pins as the published pins (a diverged member is refused by name), pinned as freeze-graph --member-pins pins them; the deploy root the newest first-parent commit at or below --deploy-sha whose engine sha-<12 hex> is published (unpublished skipped, none within the walk refused by name); the data/kernel/deploy roots by freeze-graph's rules and, from current pins, never behind or beside them (ancestry in each root's own checkout, which needs full history); declared sources at their develop heads, newer-wins against the current pin by the same ancestry rule. The data root checkout is the definition (its declared repository, clean at --data-sha, data root and distribution directory as named); the kernel checkout is at --kernel-sha. Beside the pins, --seals-out (written once) freezes both previous seals: the offering's newest signed develop edition's images lock, read once under --previous-seal-signer, and the customer's own previous lock (or first seal), passed through; seals.json names each file and its sha256. Prints the summary; --first says it is a first follow
+xema edition develop resolve --definition-at <owner>/<repo>,<path>,<dataRoot> --offering <owner>/<repo>,<path>,<dataRoot> --pins <file> --out <dir> --registry <root> --engine-repository <registry>/<path> --engine-signer <identity> --cosign <abs path> --offering-previous-lock <lock> --offering-previous-lock-sha256 <hex> (--previous-lock <lock> --previous-lock-sha256 <hex> | --first-seal) [--source-image ...]   # catalogue-free customer resolve: --pins is follow's frozen pins plus "definition-repository" (the definition's commit); the vendor step resolves the offering at the vendor pins under the offering's id and previous seal (the frozen offering lock), the customer step reads the definition at its commit and seals its own composed rows against the customer's previous lock. Reads no heads, pushes nothing; the same frozen inputs give the same bytes
 xema edition develop image-record <id> --selection <file> --pins <file> --out <file>   # the edition's image build record (what `resolve --images-from` reads) from a select-records selection: subjects are the checked-out snapshot's first-party image subjects; a current-resolution member's (xema-docs) is probed and goes in `images`, every other takes the selection's image of its develop repository (selected commit must equal the snapshot's) and goes in `satellites`; platforms read by digest; any gap refuses and writes nothing; written once
 xema edition develop verify-image-record --image <name>@sha256:<digest> --producer <owner/repo> --registry <root> --cosign <abs path>   # is the digest bound to the producer by an authenticated develop build record (shared verify core with select-records). Records are read newest run first (listBuildRecordRuns sorts by compareBuildRecordRuns: run, then attempt, highest first), a verified record of a workflow other than the producer's `.github/workflows/ci.yaml` is skipped, and the answer is the newest ci.yaml record listing the exact image -> { image, digest, producer, commit }. `commit` is the commit of the newest verified ci.yaml record (by run number, then attempt) that lists the digest; it can be an older commit when a later run targeted it, and for an image the producer reused by content hash it is NOT the commit that built it. This is safe because the digest is what binds the bytes. Refuses when no ci.yaml record lists the image, the record names another producer, or cosign refuses the identity
 xema edition develop check-overrides --overrides <json> --data-root <dir>   # data root only
@@ -184,6 +186,8 @@ A write of `images.lock.json` (`resolve-images`, `xema edition develop resolve`)
 
 - `--previous-seal-signer <certificate identity>` (develop resolve, vendor form): the CLI lists the edition's own repository (`<registry root>/develop-editions/xema-edition-<id>`), reads every snapshot tag, and takes the newest edition by its `org.opencontainers.image.created` annotation (inside the signed manifest). An edition with no signature was never published and is passed over; the newest signed one must verify, offline through the pinned cosign, for exactly that identity and the GitHub OIDC issuer, or the resolve is refused (it never steps back to an older edition). Its images.lock layer is fetched by digest. The run must be under the per-edition concurrency group, so the edition read is the one the previous run pushed.
 - `--previous-lock <lock> --previous-lock-sha256 <hex>`: the same layer, taken by the caller; the CLI refuses unless the bytes hash to the digest.
+
+A customer develop resolve (`--definition`, or the catalogue-free form) takes `--previous-lock`/`--previous-lock-sha256` or `--first-seal` (never `--previous-seal-signer`), under the customer's id, and it feeds only the customer's own composed rows; the catalogue rows are the catalogue's. In the catalogue-free form the vendor rows carry forward from the offering's own seal, `--offering-previous-lock`/`--offering-previous-lock-sha256` (frozen by `develop follow`), under the offering's id. A release customer resolve takes none.
 - `--first-seal`: generation 1, only for a distribution that has never had an edition. The CLI never infers it: a 404 for the repository (a registry may hide a repository from a credential) and a repository with no signed edition (retention) are refused, naming `--first-seal`.
 
 The in-repo resolve and pin/unpin take the committed `images.lock.json` at the target path as the previous lock (first seal when absent).
@@ -243,13 +247,15 @@ A held commit is authorized, never trusted, and nothing overrides it: the commit
 A customer edition is resolved against a catalogue pinned in `catalogue.pin.json` beside the definition file. The catalogue is the ceiling: it supplies availability, pins and digests and never adds a component. It also names the kernel: `kernel` is `{name, version, integrity}` (`@xemahq/contracts`, an exact `x.y.z`, the npm `sha512-` integrity of that tarball), and a catalogue without it is refused. Its `ceiling.storePublisherTrust` is the offering lock's Store publishers (or `null`); a definition selects among them with `storePublisherAnchorKeys`, the resolve copies the selected entries into the customer lock, and the kernel's `customerLockCeilingIssues` refuses, at resolve, seal and verify, an entry the definition does not select, a key the catalogue does not vouch for, or an entry that differs from the catalogue's.
 
 ```bash
-xema edition resolve --definition <file> --channel <release|develop> \
+xema edition resolve --definition <file> --channel release \
   --data-root <dir> --sources-root <dir> --cache-dir <dir> --out <dir> \
   --source-image <source>=<registry>/<prefix> [--catalogue-username <u> --catalogue-token-env <VAR>]
 xema edition release resolve --definition <file> --cosign <abs path> ... # release: E4 evidence verified before the catalogue is read
 xema edition resolve-digests <id> --definition <file> --data-root <dir> --editions-root <dir> --sources-root <dir> --cache-dir <dir>
 ```
 
+`--channel develop` is refused on this verb: it takes no previous seal, so a customer's own composed rows would restart at generation 1. Resolve a develop customer edition with `xema edition develop resolve --definition <file> (--previous-lock <file> --previous-lock-sha256 <hex> | --first-seal) ...`.
+
 To use a customer's own registry, copy the catalogue artifact and vendor images by digest with `oras cp`, pin the mirrored catalogue in `catalogue.pin.json`, and declare `imageRegistryMirror: {complete: true, map: [{source, target}]}` in the definition.
 
 A customer verb takes no `--kernel` (it is refused) and needs no kernel checkout and no credential for the kernel. After it fetches its catalogue it downloads `@xemahq/contracts@<catalogue.kernel.version>` from registry.npmjs.org into `<--cache-dir>/kernel-npm/`, holds the tarball to the catalogue's npm integrity before extracting it, and proves the package is the catalogue's contract authority (final protocol identity carrying `contractAuthority.contentDigest`) before it loads any schema.

package/edition/biome-content.mjs

@@ -19,6 +19,7 @@
 import { execFileSync } from 'node:child_process';
 import { relative, sep } from 'node:path';
 
+import { CatalogueLockField, catalogueLockFieldOf } from './catalogue-lock-field.mjs';
 import { assertCustomerLockWithinCatalogueCeiling } from './catalogue.mjs';
 import { readGitJsonAtCommit } from './lib.mjs';
 import { assertLockBundleSigners } from './locked-bundle-signer.mjs';
@@ -198,21 +199,28 @@ async function catalogueFacts({ schemas, biome, imageLock, catalogue }) {
 
 /**
  * Customer mode: the lock must say which catalogue produced its hashes, and it must be
- * the catalogue supplied. A lock without `catalogueDigest`, or with another one, was not
- * resolved against this catalogue, so its hashes cannot be checked on this catalogue's authority.
+ * the catalogue supplied, in the same field: `catalogueDigest` (a published catalogue artifact)
+ * or `catalogueContentDigest` (the catalogue bytes of a catalogue-free resolve), exactly one supplied
+ * and the lock carrying that one only. A lock without it, with another digest, or naming the catalogue
+ * in the other field, was not resolved against this catalogue, so its hashes cannot be checked on
+ * this catalogue's authority.
  */
-function assertLockNamesCatalogue({ schemas, lock, catalogue, catalogueDigest, storePublisherAnchorKeys }) {
-  if (catalogueDigest === undefined) {
-    throw new BiomeContentHashError(`customer mode needs the digest of catalogue "${catalogue.offeringId}"`);
+function assertLockNamesCatalogue({ schemas, lock, catalogue, catalogueDigest, catalogueContentDigest, storePublisherAnchorKeys }) {
+  const { key, digest } = catalogueLockFieldOf({ catalogueDigest, catalogueContentDigest }, { what: `customer mode for catalogue "${catalogue.offeringId}"`, ErrorType: BiomeContentHashError });
+  const other = key === CatalogueLockField.Artifact ? CatalogueLockField.Content : CatalogueLockField.Artifact;
+  if (lock[other] !== undefined) {
+    throw new BiomeContentHashError(
+      `distribution "${lock.distributionId}": the lock carries ${other}, but the supplied catalogue is named by ${key} ${digest}`,
+    );
   }
-  if (lock.catalogueDigest === undefined) {
+  if (lock[key] === undefined) {
     throw new BiomeContentHashError(
-      `distribution "${lock.distributionId}": the lock carries no catalogueDigest, so it was not resolved against a catalogue; supplied catalogue ${catalogueDigest}`,
+      `distribution "${lock.distributionId}": the lock carries no ${key}, so it was not resolved against a catalogue; supplied catalogue ${digest}`,
     );
   }
-  if (lock.catalogueDigest !== catalogueDigest) {
+  if (lock[key] !== digest) {
     throw new BiomeContentHashError(
-      `distribution "${lock.distributionId}": the lock was resolved against catalogue ${lock.catalogueDigest}, not the supplied ${catalogueDigest}`,
+      `distribution "${lock.distributionId}": the lock was resolved against catalogue ${lock[key]}, not the supplied ${digest} (${key})`,
     );
   }
   // The lock is within the catalogue's ceiling: the kernel's one check, its Store publishers against the definition's selection.
@@ -229,13 +237,14 @@ function assertLockNamesCatalogue({ schemas, lock, catalogue, catalogueDigest, s
  * @param {(repo: string) => {dir: string, base: string}} request.locate repo handle -> checkout
  * @param {(repo: string) => string} request.vendoredCommit the vendored-source pin of a first-party repo
  * @param {object} [request.catalogue] customer mode: the digest-pinned catalogue vendor biomes are taken from
- * @param {string} [request.catalogueDigest] customer mode: the digest of that catalogue; the lock must carry the same one
+ * @param {string} [request.catalogueDigest] customer mode, a published catalogue: the digest of its artifact; the lock must carry the same one
+ * @param {string} [request.catalogueContentDigest] customer mode, catalogue-free: the digest of the catalogue bytes; exclusive with catalogueDigest, the lock must carry the same one
  * @param {readonly string[]} [request.storePublisherAnchorKeys] customer mode: the definition's Store publisher selection (absent = none)
  * @param {Map<string, string>} [request.contentCommits] a candidate edition's recorded override: repo -> the commit its first-party biomes' content is read at
  * @returns {Promise<Map<string, string>>} biome id -> BiomeContentHash
  */
-export async function computeBiomeContentHashes({ schemas, lock, imageLock, locate, vendoredCommit, catalogue, catalogueDigest, storePublisherAnchorKeys, sourceFactsById, contentCommits }) {
-  if (catalogue !== undefined) {assertLockNamesCatalogue({ schemas, lock, catalogue, catalogueDigest, storePublisherAnchorKeys });}
+export async function computeBiomeContentHashes({ schemas, lock, imageLock, locate, vendoredCommit, catalogue, catalogueDigest, catalogueContentDigest, storePublisherAnchorKeys, sourceFactsById, contentCommits }) {
+  if (catalogue !== undefined) {assertLockNamesCatalogue({ schemas, lock, catalogue, catalogueDigest, catalogueContentDigest, storePublisherAnchorKeys });}
   const hashes = new Map();
   for (const biome of lock.biomes) {
     const facts =
@@ -291,9 +300,9 @@ export async function biomeSourceTreeIds({ schemas, lock, imageLock, locate, ven
 }
 
 /** Seal: the unsealed lock + the recomputed hashes -> the kernel's `sealDistributionLock`. */
-export async function sealLock({ schemas, unsealed, imageLock, locate, vendoredCommit, catalogue, catalogueDigest, storePublisherAnchorKeys, sourceFactsById, bundleSigners, contentCommits, gitSourcedBundle }) {
+export async function sealLock({ schemas, unsealed, imageLock, locate, vendoredCommit, catalogue, catalogueDigest, catalogueContentDigest, storePublisherAnchorKeys, sourceFactsById, bundleSigners, contentCommits, gitSourcedBundle }) {
   assertLockBundleSigners({ lock: unsealed, selection: bundleSigners, schemas, gitSourcedBundle });
-  const hashes = await computeBiomeContentHashes({ schemas, lock: unsealed, imageLock, locate, vendoredCommit, catalogue, catalogueDigest, storePublisherAnchorKeys, sourceFactsById, contentCommits });
+  const hashes = await computeBiomeContentHashes({ schemas, lock: unsealed, imageLock, locate, vendoredCommit, catalogue, catalogueDigest, catalogueContentDigest, storePublisherAnchorKeys, sourceFactsById, contentCommits });
   admitDistributionLock(schemas, unsealed);
   return schemas.sealDistributionLock(unsealed, hashes);
 }
@@ -302,8 +311,8 @@ export async function sealLock({ schemas, unsealed, imageLock, locate, vendoredC
  * Verify: recompute every biome's hash and REFUSE a mismatch, naming the biome.
  * The lock's own field is never trusted; a missing or extra biome is a mismatch.
  */
-export async function verifyBiomeContentHashes({ schemas, lock, imageLock, locate, vendoredCommit, catalogue, catalogueDigest, storePublisherAnchorKeys, bundleSigners, contentCommits, gitSourcedBundle }) {
-  const expected = await computeBiomeContentHashes({ schemas, lock, imageLock, locate, vendoredCommit, catalogue, catalogueDigest, storePublisherAnchorKeys, contentCommits });
+export async function verifyBiomeContentHashes({ schemas, lock, imageLock, locate, vendoredCommit, catalogue, catalogueDigest, catalogueContentDigest, storePublisherAnchorKeys, bundleSigners, contentCommits, gitSourcedBundle }) {
+  const expected = await computeBiomeContentHashes({ schemas, lock, imageLock, locate, vendoredCommit, catalogue, catalogueDigest, catalogueContentDigest, storePublisherAnchorKeys, contentCommits });
   assertLockBundleSigners({ lock, selection: bundleSigners, schemas, gitSourcedBundle });
   const mismatched = lock.biomes
     .filter((biome) => biome.biomeContentHash !== expected.get(biome.id))

package/edition/catalogue-lock-field.mjs

@@ -0,0 +1,41 @@
+// catalogue-lock-field — how a customer edition's distribution lock names the catalogue it was resolved against
+// (kernel edition protocol v37, DistributionLock): EXACTLY ONE of
+//
+//   catalogueDigest         the digest of a PUBLISHED catalogue artifact (the catalogue pin form);
+//   catalogueContentDigest  sha256 of the exact catalogue.json bytes a catalogue-free resolve's vendor step wrote
+//                           (the catalogue-free pin form: no catalogue artifact exists).
+//
+// The kernel refuses a lock carrying both; this CLI refuses a request naming both or neither, and a field that is
+// not its pin form's, before anything is resolved or sealed.
+
+/** The two lock fields, by what they digest. */
+export const CatalogueLockField = Object.freeze({ Artifact: 'catalogueDigest', Content: 'catalogueContentDigest' });
+
+/**
+ * `{ key, digest }` of the one catalogue field `request` names (CatalogueLockField). Throws `new ErrorType(message)`
+ * when it names both or neither; `what` names the caller in the message.
+ */
+export function catalogueLockFieldOf(request, { what, ErrorType = Error }) {
+  const named = Object.values(CatalogueLockField).filter((key) => request?.[key] !== undefined);
+  if (named.length !== 1) {
+    throw new ErrorType(`${what} names ${named.length === 0 ? 'neither' : 'both'} ${CatalogueLockField.Artifact} (a published catalogue) ${named.length === 0 ? 'nor' : 'and'} ${CatalogueLockField.Content} (a catalogue-free resolve): exactly one`);
+  }
+  const [key] = named;
+  return { key, digest: request[key] };
+}
+
+/** The lock field of a customer edition's pin form: the catalogue-free form records the content digest, the catalogue form the artifact digest. */
+export const catalogueLockFieldOfForm = (catalogueFree) => (catalogueFree ? CatalogueLockField.Content : CatalogueLockField.Artifact);
+
+/**
+ * The one catalogue field of a customer edition's lock, `{ key, digest }`: exactly one named, and the one its pin form
+ * records (`catalogueFree`: the catalogue-free form). Throws `new ErrorType(message)` otherwise.
+ */
+export function customerLockCatalogueField({ catalogueFree, catalogueDigest, catalogueContentDigest }, { what, ErrorType = Error }) {
+  const field = catalogueLockFieldOf({ catalogueDigest, catalogueContentDigest }, { what, ErrorType });
+  const formField = catalogueLockFieldOfForm(catalogueFree);
+  if (field.key !== formField) {
+    throw new ErrorType(`a ${catalogueFree ? 'catalogue-free' : 'catalogue-form'} customer edition names its catalogue by ${formField}, not ${field.key}`);
+  }
+  return field;
+}

package/edition/customer-edition-verbs.mjs

@@ -18,15 +18,16 @@ import { isAbsolute, join, resolve } from 'node:path';
 import { sealLock } from './biome-content.mjs';
 import { assertCatalogueConsumerArmed } from './catalogue-evidence.mjs';
 import { fetchCatalogue, parseCatalogueRef } from './catalogue-fetch.mjs';
+import { customerLockCatalogueField } from './catalogue-lock-field.mjs';
 import { readCataloguePin } from './catalogue-pin.mjs';
-import { CATALOGUE_TOKEN_ENV_FLAG, CATALOGUE_USERNAME_FLAG, COSIGN_FLAG, DEFINITION_FLAG, SOURCE_IMAGE_FLAG } from './customer-flags.mjs';
+import { CATALOGUE_TOKEN_ENV_FLAG, CATALOGUE_USERNAME_FLAG, COSIGN_FLAG, DEFINITION_AT_FLAG, DEFINITION_FLAG, OFFERING_FLAG, OFFERING_PREVIOUS_LOCK_FLAG, OFFERING_PREVIOUS_LOCK_SHA256_FLAG, SOURCE_IMAGE_FLAG } from './customer-flags.mjs';
 import { freezeCustomerSources, lsRemoteRef } from './develop-freeze.mjs';
 import { customerDevelopGitBundleVerifier } from './develop-git-bundles.mjs';
 import { isDevelopImageRef } from './develop-image-coordinate.mjs';
 import { assertCanonicalDistributionId } from './distribution-paths.mjs';
 import { LOCAL_WORKFLOW, assertEngineImage, assertExistingArtifactMatches, snapshotEditionTarget, workflowFromEnv, writeEditionArtifact } from './edition-artifact.mjs';
 import { editionWorkspaceConfig } from './edition-config.mjs';
-import { CATALOGUE_PIN_KEY, DEFINITION_PIN_KEY, EditionChannel, EditionKind, EditionLockFile } from './edition-constants.mjs';
+import { CATALOGUE_PIN_KEY, CustomerPinForm, DEFINITION_PIN_KEY, EditionChannel, EditionKind, EditionLockFile, customerPinFormAdmitted } from './edition-constants.mjs';
 import { channelImageRef, sealImageSubjects } from './edition-image-seal.mjs';
 import { WorkspaceRoot } from './edition-workspace.mjs';
 import { descriptorEvidenceTrust } from './evidence-trust-policy.mjs';
@@ -39,7 +40,7 @@ import { isSourcePinKey, sortedSnapshotPins, sourcePinKey } from './pin-source.m
 import { PREVIOUS_SEAL_SIGNER_FLAG } from './previous-seal-registry.mjs';
 import { assertSealedImageLock } from './release-edition-artifact.mjs';
 import { assertSourceImagesCoverDefinition, parseSourceImages, resolveCustomerEdition } from './resolve-customer-edition.mjs';
-import { externalSourceTrees, imageRefForSubject, sourceTreeLocator } from './resolve-images.mjs';
+import { externalSourceTrees, imageRefForSubject, resolvePreviousSeal, sourceTreeLocator } from './resolve-images.mjs';
 import { readStrictJsonFile } from './strict-json.mjs';
 
 const SHA_PATTERN = /^[0-9a-f]{40}$/;
@@ -66,7 +67,11 @@ export function customerDefinitionDigest(rawDefinition) {
  * catalogue artifact and `definition` = the digest of the definition (customerDefinitionDigest).
  * A `catalogue` or `definition` entry in the file must equal that digest.
  */
-export function customerEditionPins({ channel, pins, declaredSourceNames, catalogueDigest, definitionDigest }) {
+export function customerEditionPins({ channel, pins, declaredSourceNames, catalogueDigest, definitionDigest, vendorPins }) {
+  const catalogueFree = vendorPins !== undefined;
+  if (catalogueFree && !customerPinFormAdmitted(CustomerPinForm.CatalogueFree, EditionKind.Resolved, channel)) {
+    throw new CustomerEditionPinsError(`a ${channel} customer edition is never resolved catalogue-free`);
+  }
   if (typeof definitionDigest !== 'string') {throw new CustomerEditionPinsError('a customer edition pins the digest of its definition');}
   if (pins === null || typeof pins !== 'object' || Array.isArray(pins)) {
     throw new CustomerEditionPinsError('--pins must be an object mapping sources/<name> -> 40-hex commit');
@@ -74,6 +79,7 @@ export function customerEditionPins({ channel, pins, declaredSourceNames, catalo
   const own = {};
   for (const [key, value] of Object.entries(pins)) {
     if (key === CATALOGUE_PIN_KEY) {
+      if (catalogueFree) {throw new CustomerEditionPinsError(`--pins names "${CATALOGUE_PIN_KEY}", but a catalogue-free edition pins no catalogue: the catalogue's digest goes into the distribution lock only`);}
       if (value !== catalogueDigest) {
         throw new CustomerEditionPinsError(`--pins "${CATALOGUE_PIN_KEY}" is ${JSON.stringify(value)}, but the pinned ${channel} catalogue is ${catalogueDigest}`);
       }
@@ -100,7 +106,13 @@ export function customerEditionPins({ channel, pins, declaredSourceNames, catalo
   for (const key of Object.keys(own)) {
     if (!declared.has(key)) {throw new CustomerEditionPinsError(`--pins names "${key}", but the definition declares no such source`);}
   }
-  return sortedSnapshotPins({ ...own, [CATALOGUE_PIN_KEY]: catalogueDigest, [DEFINITION_PIN_KEY]: definitionDigest });
+  if (!catalogueFree) {return sortedSnapshotPins({ ...own, [CATALOGUE_PIN_KEY]: catalogueDigest, [DEFINITION_PIN_KEY]: definitionDigest });}
+  for (const key of Object.keys(vendorPins)) {
+    if (key === CATALOGUE_PIN_KEY || key === DEFINITION_PIN_KEY || key in own) {
+      throw new CustomerEditionPinsError(`the vendor pins of a catalogue-free edition name "${key}", which is the customer's own`);
+    }
+  }
+  return sortedSnapshotPins({ ...vendorPins, ...own, [DEFINITION_PIN_KEY]: definitionDigest });
 }
 
 /** The source names a raw definition declares (the pins are checked before the definition is composed). */
@@ -109,16 +121,22 @@ export function declaredSourceNamesOf(rawDefinition) {
   return Array.isArray(sources) ? sources.map((source) => source?.name) : [];
 }
 
-/** Resolve and seal the customer edition of `channel`; returns the four locks and the frozen provenance pins. */
-export async function resolveCustomerChannelEdition({ channel, rawDefinition, catalogue, catalogueDigest, pins, sourceImages, env = process.env, sealOptions = {}, adoptKernel, materialize, developGitBundles }) {
-  const frozen = customerEditionPins({ channel, pins, declaredSourceNames: declaredSourceNamesOf(rawDefinition), catalogueDigest, definitionDigest: customerDefinitionDigest(rawDefinition) });
+/**
+ * Resolve and seal the customer edition of `channel`; returns the four locks and the frozen provenance pins. The pin form
+ * decides the lock's catalogue field: catalogue-free (`vendorPins`) records `catalogueContentDigest`, the catalogue form
+ * `catalogueDigest`. `previousSeal(id)` answers the customer's own previous seal (resolvePreviousSeal; absent: a first seal).
+ */
+export async function resolveCustomerChannelEdition({ channel, rawDefinition, catalogue, catalogueDigest, catalogueContentDigest, pins, vendorPins, previousSeal, sourceImages, env = process.env, sealOptions = {}, adoptKernel, materialize, developGitBundles }) {
+  const catalogueField = customerLockCatalogueField({ catalogueFree: vendorPins !== undefined, catalogueDigest, catalogueContentDigest }, { what: `a ${channel} customer resolve`, ErrorType: CustomerEditionPinsError });
+  const frozen = customerEditionPins({ channel, pins, declaredSourceNames: declaredSourceNamesOf(rawDefinition), catalogueDigest, definitionDigest: customerDefinitionDigest(rawDefinition), ...(vendorPins === undefined ? {} : { vendorPins }) });
   const resolved = await resolveCustomerEdition({
     rawDefinition,
     catalogue,
     channel,
     sourceImages,
     pins: frozen,
-    catalogueDigest,
+    [catalogueField.key]: catalogueField.digest,
+    ...(previousSeal === undefined ? {} : { previousSeal }),
     ...(adoptKernel === undefined ? {} : { adoptKernel }),
     ...(materialize === undefined ? {} : { materialize }),
     ...(developGitBundles === undefined ? {} : { developGitBundles }),
@@ -136,7 +154,7 @@ export async function resolveCustomerChannelEdition({ channel, rawDefinition, ca
       throw new Error(`customer biome source "${repo}" is first-party to no checkout; vendor biomes are taken from the catalogue`);
     },
     catalogue,
-    catalogueDigest,
+    [catalogueField.key]: catalogueField.digest,
     storePublisherAnchorKeys: resolved.storePublisherAnchorKeys,
     // A row the develop verifier kept carries its bundle and develop signer; the seal admits exactly those.
     gitSourcedBundle: developGitBundles === undefined ? GitSourcedBundle.Refused : GitSourcedBundle.DevelopVerified,
@@ -203,7 +221,18 @@ const COMMANDS = Object.freeze({
     values: ['--pins', '--out', '--registry', ENGINE_REPOSITORY_FLAG, ENGINE_SIGNER_FLAG, COSIGN_FLAG, IMAGES_FROM_FLAG, PREVIOUS_LOCK_FLAG, PREVIOUS_LOCK_SHA256_FLAG, PREVIOUS_SEAL_SIGNER_FLAG],
     switches: ['--local', FIRST_SEAL_FLAG],
     required: ['--pins', '--out', '--registry', ENGINE_REPOSITORY_FLAG, ENGINE_SIGNER_FLAG, COSIGN_FLAG],
-    customer: { values: [DEFINITION_FLAG, ...CREDENTIAL_FLAGS, SOURCE_IMAGE_FLAG, COSIGN_FLAG, ENGINE_IMAGE_FLAG], required: ['--pins', '--out', '--registry', '--engine-image'], refused: [IMAGES_FROM_FLAG, PREVIOUS_LOCK_FLAG, PREVIOUS_LOCK_SHA256_FLAG, FIRST_SEAL_FLAG, PREVIOUS_SEAL_SIGNER_FLAG], cosign: true, developCosign: true },
+    customer: { values: [DEFINITION_FLAG, ...CREDENTIAL_FLAGS, SOURCE_IMAGE_FLAG, COSIGN_FLAG, ENGINE_IMAGE_FLAG], required: ['--pins', '--out', '--registry', '--engine-image'], refused: [IMAGES_FROM_FLAG, PREVIOUS_SEAL_SIGNER_FLAG], cosign: true, developCosign: true },
+    // The customer's own previous seal (customerPreviousSeal): --previous-lock with --previous-lock-sha256, or --first-seal, on develop only.
+    customerPreviousSeal: [PREVIOUS_LOCK_FLAG, PREVIOUS_LOCK_SHA256_FLAG, FIRST_SEAL_FLAG],
+    // The catalogue-free customer form (develop only, develop-catalogue-free-resolve.mjs): the vendor offering is resolved in
+    // the same call, so it names both definitions as triples, the vendor step's engine flags and the offering's frozen previous
+    // seal; --previous-lock/--first-seal are the customer's own.
+    catalogueFree: {
+      markers: [DEFINITION_AT_FLAG, OFFERING_FLAG],
+      values: [DEFINITION_AT_FLAG, OFFERING_FLAG, SOURCE_IMAGE_FLAG, OFFERING_PREVIOUS_LOCK_FLAG, OFFERING_PREVIOUS_LOCK_SHA256_FLAG],
+      required: [DEFINITION_AT_FLAG, OFFERING_FLAG, '--pins', '--out', '--registry', ENGINE_REPOSITORY_FLAG, ENGINE_SIGNER_FLAG, COSIGN_FLAG, OFFERING_PREVIOUS_LOCK_FLAG, OFFERING_PREVIOUS_LOCK_SHA256_FLAG],
+      refused: [DEFINITION_FLAG, ...CREDENTIAL_FLAGS, ENGINE_IMAGE_FLAG, IMAGES_FROM_FLAG, PREVIOUS_SEAL_SIGNER_FLAG],
+    },
     // developCosign: on develop, --cosign verifies the git-sourced OCI bundles under the data root's pinned policy (develop-git-bundles.mjs).
     // A vendor resolve finds its engine itself; the old flag is refused by name, never read as a customer flag.
     removedFromVendor: { [ENGINE_IMAGE_FLAG]: `use ${ENGINE_REPOSITORY_FLAG} and ${ENGINE_SIGNER_FLAG}` },
@@ -240,6 +269,14 @@ const COMMANDS = Object.freeze({
     switches: ['--json'],
     required: ['--pins', '--cosign'],
   },
+  follow: {
+    positional: false,
+    values: [DEFINITION_AT_FLAG, '--data-sha', '--kernel-sha', '--deploy-sha', ENGINE_REPOSITORY_FLAG, '--registry', COSIGN_FLAG, '--current-pins', '--out', '--seals-out', PREVIOUS_SEAL_SIGNER_FLAG, PREVIOUS_LOCK_FLAG, PREVIOUS_LOCK_SHA256_FLAG],
+    // exactly one of --first and --current-pins (develop-follow.mjs followStartOf); the customer's own previous seal is
+    // exactly one of --previous-lock with --previous-lock-sha256, or --first-seal (customerPreviousLockInput)
+    switches: ['--first', FIRST_SEAL_FLAG],
+    required: [DEFINITION_AT_FLAG, '--data-sha', '--kernel-sha', '--deploy-sha', ENGINE_REPOSITORY_FLAG, '--registry', COSIGN_FLAG, '--out', '--seals-out', PREVIOUS_SEAL_SIGNER_FLAG],
+  },
   'select-records': {
     positional: false,
     values: ['--branch', '--registry', '--cosign', '--out', '--at', '--published-pins'],
@@ -281,6 +318,21 @@ function commandsOf(channel) {
   throw new Error(`unknown edition channel ${JSON.stringify(channel)}`);
 }
 
+/** The catalogue-free customer form of a develop verb: no positional id (it is the definition's), no catalogue flags. */
+function catalogueFreeArgs(command, spec, options, positional) {
+  for (const refused of spec.refused) {
+    if (options[refused] !== undefined) {
+      throw new Error(`a catalogue-free ${command} takes no ${refused}: it names the definition and the offering as ${DEFINITION_AT_FLAG} and ${OFFERING_FLAG}, pins no catalogue, and its vendor step finds its engine itself`);
+    }
+  }
+  if (positional.length !== 0) {throw new Error(`a catalogue-free ${command} takes no <distribution-id>: the id is the definition's`);}
+  for (const required of spec.required) {
+    if (options[required] === undefined) {throw new Error(`a catalogue-free ${command} requires ${required}`);}
+  }
+  if (!isAbsolute(options[COSIGN_FLAG])) {throw new Error(`${COSIGN_FLAG} must be an absolute path, got ${JSON.stringify(options[COSIGN_FLAG])}`);}
+  return { command, id: undefined, options, customer: false, catalogueFree: true };
+}
+
 /** Parse `<command> [<id>] --flag value ...` of `channel` against the closed vocabulary of the command. */
 export function parseEditionVerbArgs(channel, argv) {
   const commands = commandsOf(channel);
@@ -291,13 +343,14 @@ export function parseEditionVerbArgs(channel, argv) {
   }
   // The flags only the customer form takes: a flag the vendor form takes too (`--cosign` of a develop resolve) does not make it one.
   const customerValues = (spec.customer?.values ?? []).filter((flag) => !spec.values.includes(flag));
+  const catalogueFreeValues = channel === EditionChannel.Develop ? (spec.catalogueFree?.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)) {
+    } else if (spec.values.includes(arg) || customerValues.includes(arg) || catalogueFreeValues.includes(arg)) {
       const value = rest[i + 1];
       if (value === undefined || (value.startsWith('--') && value.length > 2)) {
         throw new Error(`${arg} requires a value`);
@@ -316,6 +369,12 @@ export function parseEditionVerbArgs(channel, argv) {
       positional.push(arg);
     }
   }
+  if (catalogueFreeValues.length > 0 && spec.catalogueFree.markers.some((flag) => options[flag] !== undefined)) {
+    return catalogueFreeArgs(command, spec.catalogueFree, options, positional);
+  }
+  for (const flag of catalogueFreeValues.filter((value) => !customerValues.includes(value) && !spec.values.includes(value))) {
+    if (options[flag] !== undefined) {throw new Error(`${flag} belongs to the catalogue-free form of ${command} (${spec.catalogueFree.markers.join(' and ')})`);}
+  }
   const customer = spec.customer !== undefined && customerValues.some((flag) => options[flag] !== undefined);
   // `--cosign` of a customer form verifies a release catalogue, and on a develop resolve the git-sourced OCI bundles
   // (`developCosign`); a vendor verb (develop `coverage`, `resolve`, `engine`) takes its own `--cosign`.
@@ -337,6 +396,10 @@ export function parseEditionVerbArgs(channel, argv) {
     for (const refused of spec.customer.refused) {
       if (options[refused] !== undefined) {throw new Error(`a customer ${command} takes no ${refused}`);}
     }
+    // The customer's own previous seal is a develop resolve's (customerPreviousSeal); a release customer resolve takes none.
+    for (const flag of spec.customerPreviousSeal ?? []) {
+      if (channel !== EditionChannel.Develop && options[flag] !== undefined) {throw new Error(`a ${channel} customer ${command} takes no ${flag}`);}
+    }
     if (positional.length !== 0) {throw new Error(`a customer ${command} takes no <distribution-id>: the id is the definition's`);}
     if (spec.customer.cosign === true && channel === EditionChannel.Release && options[COSIGN_FLAG] === undefined) {
       throw new Error(`a release ${command} requires ${COSIGN_FLAG} <absolute path of the cosign binary>`);
@@ -394,6 +457,23 @@ async function fetchPinnedCatalogue(channel, options, env, fetch = fetchCatalogu
   });
 }
 
+/**
+ * The customer's own previous seal of a develop resolve, as `previousSeal(id)` (resolveCustomerChannelEdition): exactly
+ * one of `--previous-lock <path> --previous-lock-sha256 <hex>` (the customer edition's own last images lock, its bytes
+ * held to the sha256 and its id to the edition's) or `--first-seal`. No signer form: a resolve reads no "newest", so the
+ * same frozen inputs resolve the same bytes. A release customer resolve takes none (refused at the parse).
+ */
+export function customerPreviousSeal(channel, options) {
+  if (channel !== EditionChannel.Develop) {return undefined;}
+  return (distributionId) =>
+    resolvePreviousSeal({
+      distributionId,
+      previousLockPath: options[PREVIOUS_LOCK_FLAG],
+      previousLockSha256: options[PREVIOUS_LOCK_SHA256_FLAG],
+      firstSeal: Boolean(options[FIRST_SEAL_FLAG]),
+    });
+}
+
 /** A customer resolve: the artifact (descriptor and four locks, no catalogue: it is not an offering) goes to --out. */
 async function resolveCustomer(channel, options, env) {
   const { catalogue, digest } = await fetchPinnedCatalogue(channel, options, env);
@@ -407,6 +487,7 @@ async function resolveCustomer(channel, options, env) {
     catalogue,
     catalogueDigest: digest,
     pins: readStrictJsonFile(options['--pins']),
+    previousSeal: customerPreviousSeal(channel, options),
     sourceImages,
     env,
     // Develop, under a declared customer policy: the git-sourced OCI bundles are verified with --cosign (none: refused when a subject exists).

package/edition/customer-flags.mjs

@@ -6,3 +6,10 @@ export const CATALOGUE_USERNAME_FLAG = '--catalogue-username';
 export const CATALOGUE_TOKEN_ENV_FLAG = '--catalogue-token-env';
 /** The absolute path of the cosign binary that verifies a release catalogue's E4 evidence (release only). */
 export const COSIGN_FLAG = '--cosign';
+/** A definition named as `<owner>/<repo>,<path>,<dataRoot>` at a pinned commit (`develop follow`); `--definition` is a file. */
+export const DEFINITION_AT_FLAG = '--definition-at';
+/** The vendor offering a catalogue-free resolve resolves in the same call, as `<owner>/<repo>,<path>,<dataRoot>` of the vendor data checkout. */
+export const OFFERING_FLAG = '--offering';
+/** The offering's own previous seal a catalogue-free resolve's vendor step carries forward: the images lock `develop follow` froze, and its sha256. */
+export const OFFERING_PREVIOUS_LOCK_FLAG = '--offering-previous-lock';
+export const OFFERING_PREVIOUS_LOCK_SHA256_FLAG = '--offering-previous-lock-sha256';