@xemahq/xema 0.27.0 → 0.29.0

package/edition/catalogue-pin.mjs

@@ -0,0 +1,71 @@
+// catalogue-pin — `catalogue.pin.json`, the catalogues a customer edition is resolved against.
+//
+// It sits in the SAME directory as the customer's definition file:
+//   { "schemaVersion": 1, "develop": "oci://<repository>@sha256:<64 hex>" | null, "release": ... | null }
+// Exactly these keys, both channel keys present; null states that the edition is not produced on
+// that channel. A reference is parsed by `parseCatalogueRef`, and the repository channel of the
+// reference under a key must be that key. This is the only reader of the file: every customer
+// resolve takes the catalogue reference of its channel from here.
+
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+import { parseCatalogueRef } from './catalogue-fetch.mjs';
+import { CatalogueError } from './catalogue.mjs';
+import { EditionChannel } from './edition-constants.mjs';
+import { readStrictJsonFile } from './strict-json.mjs';
+
+export const CATALOGUE_PIN_FILE = 'catalogue.pin.json';
+export const CATALOGUE_PIN_SCHEMA_VERSION = 1;
+
+const SCHEMA_VERSION_KEY = 'schemaVersion';
+
+/** The catalogue pin file that sits beside `definitionFile`. */
+export const cataloguePinFile = (definitionFile) => join(dirname(definitionFile), CATALOGUE_PIN_FILE);
+
+/** The strict parse of a pin document read from `file`; returns it unchanged. */
+export function parseCataloguePins(document, file) {
+  const channels = Object.values(EditionChannel);
+  const expected = [SCHEMA_VERSION_KEY, ...channels].sort().join();
+  if (document === null || typeof document !== 'object' || Array.isArray(document) || Object.keys(document).sort().join() !== expected) {
+    throw new CatalogueError(`${file} must be exactly {${[SCHEMA_VERSION_KEY, ...channels].join(', ')}}, every key present`);
+  }
+  if (document[SCHEMA_VERSION_KEY] !== CATALOGUE_PIN_SCHEMA_VERSION) {
+    throw new CatalogueError(`${file}: ${SCHEMA_VERSION_KEY} must be ${CATALOGUE_PIN_SCHEMA_VERSION}`);
+  }
+  for (const channel of channels) {
+    const ref = document[channel];
+    if (ref === null) {continue;}
+    if (typeof ref !== 'string') {
+      throw new CatalogueError(`${file}: "${channel}" must be an oci://<repository>@sha256:<64 hex> reference or null`);
+    }
+    let parsed;
+    try {
+      parsed = parseCatalogueRef(ref);
+    } catch (error) {
+      throw new CatalogueError(`${file}: "${channel}": ${error.message}`, { cause: error });
+    }
+    if (parsed.edition.channel !== channel) {
+      throw new CatalogueError(
+        `${file}: "${channel}" pins ${ref}, whose repository is a ${parsed.edition.channel} repository; a ${channel} catalogue is pinned in a ${channel} repository`,
+      );
+    }
+  }
+  return document;
+}
+
+/** The catalogue reference pinned for `channel` beside `definitionFile`; a null pin or a missing file is refused. */
+export function readCataloguePin({ definitionFile, channel }) {
+  const file = cataloguePinFile(definitionFile);
+  if (!existsSync(file)) {
+    throw new CatalogueError(`${file} does not exist: a customer edition pins its catalogues in ${CATALOGUE_PIN_FILE}, beside the definition`);
+  }
+  const ref = parseCataloguePins(readStrictJsonFile(file), file)[channel];
+  if (ref === undefined) {
+    throw new CatalogueError(`${file}: ${JSON.stringify(channel)} is not a channel (${Object.values(EditionChannel).join(' | ')})`);
+  }
+  if (ref === null) {
+    throw new CatalogueError(`${file}: no ${channel} catalogue is pinned for this edition`);
+  }
+  return ref;
+}

package/edition/catalogue.mjs

@@ -133,3 +133,14 @@ export function writeCatalogue(outDir, catalogue) {
   writeFileSync(path, serializeJson(catalogue));
   return path;
 }
+
+const KERNEL_COMMIT = /^[0-9a-f]{40}$/;
+
+/** The commit the catalogue's contract authority was taken at (40 hex); read without the kernel schemas, which are not checked out yet where this is used. */
+export function contractAuthoritySourceCommit(catalogue) {
+  const commit = catalogue.contractAuthority.sourceCommit;
+  if (typeof commit !== 'string' || !KERNEL_COMMIT.test(commit)) {
+    throw new CatalogueError(`${CATALOGUE_FILE}: contractAuthority.sourceCommit is not a 40-hex commit: ${JSON.stringify(commit)}`);
+  }
+  return commit;
+}

package/edition/chart-set-source-commit.mjs

@@ -3,10 +3,11 @@
 //
 // The publisher stamps its index chart with `xema.dev/chart-set-source-sha`
 // next to `xema.dev/chart-set-charts`. This verb reads that stamp from the index
-// chart at the version the committed fleet `chart-set.lock.json` pins, and
-// prints one JSON document. It refuses, printing nothing, when the stamp is
-// absent or is not a 40-hex commit, or when the index's roster is not the one
-// the lock records for that publisher: the commit it would name would then be
+// chart at the digest the committed fleet `chart-set.lock.json` pins (a develop
+// lock has none and is refused), and prints one JSON document. It refuses,
+// printing nothing, when the stamp is absent or is not a 40-hex commit, when the
+// registry does not serve the locked digest, or when the index's roster is not
+// the one the lock records for that publisher: the commit it would name would then be
 // the commit of a different set than the locked one.
 
 import { EditionChannel } from './edition-channel.mjs';
@@ -19,9 +20,10 @@ import {
   INDEX_ROSTER_ANNOTATION,
   chartRegistryClient,
   chartSetLockPath,
-  indexAnnotations,
+  manifestAnnotations,
   parseIndexRoster,
   readLock,
+  registryRepository,
 } from './resolve-chart-set.mjs';
 
 if (isEntryModule(import.meta.url)) {
@@ -55,9 +57,17 @@ function rosterDifference(lockCharts, indexRoster) {
  */
 export async function chartSetSourceCommits({ client, lock }) {
   const publishers = [];
-  for (const { index, repo, version, charts } of lock.publishers) {
+  for (const { index, repo, version, indexDigest, charts } of lock.publishers) {
     const label = `${index}@${version}`;
-    const annotations = await indexAnnotations(client, index, version);
+    if (indexDigest === null) {
+      throw new Error(`${label}: a develop chart set names its deploy commit in the snapshot pins, not in an index chart (indexDigest is null)`);
+    }
+    // The index is read BY the digest the lock pins, so a re-pushed tag cannot answer.
+    const served = await client.getManifestByDigest(registryRepository(index), indexDigest);
+    if (served.digest !== indexDigest) {
+      throw new Error(`${label}: the registry served index manifest ${served.digest} but ${CHART_SET_LOCK_FILE} pins ${indexDigest}`);
+    }
+    const annotations = await manifestAnnotations(client, index, version, served);
     const difference = rosterDifference(charts, parseIndexRoster(annotations[INDEX_ROSTER_ANNOTATION], label));
     if (difference !== null) {
       throw new Error(`${label}: the index roster is not the set ${CHART_SET_LOCK_FILE} locks (${difference}), so its source commit is not the locked set's`);

package/edition/checkout-indexed-source-repositories.mjs

@@ -6,7 +6,7 @@ import { dirname, resolve } from 'node:path';
 
 import { editionWorkspaceConfig } from './edition-config.mjs';
 import { WorkspaceRoot, configureEditionWorkspaceFromProcess, isEntryModule, runtimeImageSourceIndexPath, sourcesRoot } from './edition-workspace.mjs';
-import { gitAuthEnv } from './git-source-auth.mjs';
+import { holdSource, withSourceGitEnv } from './git-source-auth.mjs';
 import { applyPinSource, snapshotPinSource } from './pin-source.mjs';
 import { readStrictJsonFile } from './strict-json.mjs';
 
@@ -45,29 +45,30 @@ function git(args, env) {
   execFileSync('git', args, { env, stdio: 'inherit' });
 }
 
-export function checkoutIndexedSources({ workspaceRoot, token, index }) {
+export function checkoutIndexedSources({ workspaceRoot, index, env = process.env }) {
   if (!workspaceRoot) {throw new Error('workspaceRoot is required');}
-  if (!token) {throw new Error('EVIDENCE_REPOSITORIES_TOKEN is required');}
   const workspace = editionWorkspaceConfig();
-  const env = gitAuthEnv(workspace.sourceRepositoryUrlPrefix, workspace.sourceAuthUsername, token);
   const plan = sourceCheckoutPlan(index, workspace);
+  for (const entry of plan) {holdSource({ name: entry.repo, url: entry.repositoryUrl }, workspace, env);}
   for (const entry of plan) {
     const target = resolve(workspaceRoot, entry.repo);
     if (existsSync(target)) {
       throw new Error(`${entry.repo} target already exists; refusing to reuse an unverified checkout`);
     }
-    mkdirSync(dirname(target), { recursive: true });
-    git(['init', '--quiet', target], env);
-    git(['-C', target, 'remote', 'add', 'origin', entry.repositoryUrl], env);
-    git(['-C', target, 'fetch', '--quiet', '--depth=1', 'origin', entry.sourceCommit], env);
-    git(['-C', target, 'checkout', '--quiet', '--detach', entry.sourceCommit], env);
-    const actual = execFileSync('git', ['-C', target, 'rev-parse', 'HEAD'], {
-      env,
-      encoding: 'utf8',
-    }).trim();
-    if (actual !== entry.sourceCommit) {
-      throw new Error(`${entry.repo} resolved ${actual}, expected ${entry.sourceCommit}`);
-    }
+    withSourceGitEnv({ name: entry.repo, url: entry.repositoryUrl }, { workspace, env }, (gitEnv) => {
+      mkdirSync(dirname(target), { recursive: true });
+      git(['init', '--quiet', target], gitEnv);
+      git(['-C', target, 'remote', 'add', 'origin', entry.repositoryUrl], gitEnv);
+      git(['-C', target, 'fetch', '--quiet', '--depth=1', 'origin', entry.sourceCommit], gitEnv);
+      git(['-C', target, 'checkout', '--quiet', '--detach', entry.sourceCommit], gitEnv);
+      const actual = execFileSync('git', ['-C', target, 'rev-parse', 'HEAD'], {
+        env: gitEnv,
+        encoding: 'utf8',
+      }).trim();
+      if (actual !== entry.sourceCommit) {
+        throw new Error(`${entry.repo} resolved ${actual}, expected ${entry.sourceCommit}`);
+      }
+    });
     console.log(`[source-checkout] ${entry.repo} @ ${entry.sourceCommit}`);
   }
   return plan.length;
@@ -94,7 +95,6 @@ if (isEntryModule(import.meta.url)) {
     const index = indexForCheckout(JSON.parse(readFileSync(runtimeImageSourceIndexPath(), 'utf8')), process.argv.slice(2));
     const count = checkoutIndexedSources({
       workspaceRoot: sourcesRoot(),
-      token: process.env.EVIDENCE_REPOSITORIES_TOKEN,
       index,
     });
     console.log(`[source-checkout] materialized ${count} indexed repositories at exact commits`);

package/edition/customer-flags.mjs

@@ -1,6 +1,5 @@
 // The flags that make a resolve a CUSTOMER resolve (against a catalogue).
 export const DEFINITION_FLAG = '--definition';
-export const CATALOGUE_FLAG = '--catalogue';
 export const CHANNEL_FLAG = '--channel';
 export const SOURCE_IMAGE_FLAG = '--source-image';
 export const CATALOGUE_USERNAME_FLAG = '--catalogue-username';

package/edition/develop-customer-edition.mjs

@@ -10,12 +10,16 @@
 // sealed against the develop image repositories.
 
 import { sealLock } from './biome-content.mjs';
-import { sealDevelopImages } from './develop-seal.mjs';
+import { parseCatalogueRef } from './catalogue-fetch.mjs';
+import { readCataloguePin } from './catalogue-pin.mjs';
+import { sealDevelopImageSubjects } from './develop-seal.mjs';
+import { assertCanonicalDistributionId } from './distribution-paths.mjs';
 import { CATALOGUE_PIN_KEY, EditionChannel } from './edition-constants.mjs';
 import { loadKernelDistributionSchemas } from './lib.mjs';
-import { snapshotPinNamespace, SnapshotPinNamespace, sortedSnapshotPins, sourcePinKey } from './pin-source.mjs';
+import { isSourcePinKey, sortedSnapshotPins, sourcePinKey } from './pin-source.mjs';
 import { resolveCustomerEdition } from './resolve-customer-edition.mjs';
 import { externalSourceTrees, sourceTreeLocator } from './resolve-images.mjs';
+import { readStrictJsonFile } from './strict-json.mjs';
 
 const SHA_PATTERN = /^[0-9a-f]{40}$/;
 
@@ -39,11 +43,11 @@ export function customerDevelopPins({ pins, declaredSourceNames, catalogueDigest
   for (const [key, value] of Object.entries(pins)) {
     if (key === CATALOGUE_PIN_KEY) {
       if (value !== catalogueDigest) {
-        throw new CustomerDevelopPinsError(`--pins "${CATALOGUE_PIN_KEY}" is ${JSON.stringify(value)}, but --catalogue is ${catalogueDigest}`);
+        throw new CustomerDevelopPinsError(`--pins "${CATALOGUE_PIN_KEY}" is ${JSON.stringify(value)}, but the pinned develop catalogue is ${catalogueDigest}`);
       }
       continue;
     }
-    if (snapshotPinNamespace(key) !== SnapshotPinNamespace.Source) {
+    if (!isSourcePinKey(key)) {
       throw new CustomerDevelopPinsError(`--pins "${key}" is not one of the customer's own repositories: a customer develop pins only sources/<name> (the vendor's pins are the catalogue's)`);
     }
     if (typeof value !== 'string' || !SHA_PATTERN.test(value)) {
@@ -79,7 +83,7 @@ export async function resolveCustomerDevelopEdition({ rawDefinition, catalogue,
     catalogueDigest,
     ...(verifyAuthority === undefined ? {} : { verifyAuthority }),
     ...(materialize === undefined ? {} : { materialize }),
-    sealOwn: (imageLock) => sealDevelopImages({ imageLock, env, ...sealOptions }),
+    sealOwn: ({ distributionId, subjects }) => sealDevelopImageSubjects({ distributionId, subjects, env, ...sealOptions }),
   });
   // The customer edition is sealed here: every biomeContentHash is recomputed through the
   // same code as the vendor's, vendor biomes on the CATALOGUE's authority (biome-content.mjs).
@@ -97,3 +101,17 @@ export async function resolveCustomerDevelopEdition({ rawDefinition, catalogue,
   });
   return { ...resolved, distributionLock, pins: frozen };
 }
+
+/**
+ * What a develop verb of a customer edition derives from its definition file and its `--pins` file with no
+ * network: the id (the definition's), the pinned develop catalogue reference and digest, and the frozen
+ * provenance pins (the customer's `sources/<name>` commits plus that digest).
+ */
+export function customerDevelopFrame({ definitionFile, pinsFile }) {
+  const rawDefinition = readStrictJsonFile(definitionFile);
+  assertCanonicalDistributionId(rawDefinition?.id);
+  const catalogueRef = readCataloguePin({ definitionFile, channel: EditionChannel.Develop });
+  const { digest } = parseCatalogueRef(catalogueRef);
+  const pins = customerDevelopPins({ pins: readStrictJsonFile(pinsFile), declaredSourceNames: declaredSourceNamesOf(rawDefinition), catalogueDigest: digest });
+  return { id: rawDefinition.id, rawDefinition, catalogueRef, catalogueDigest: digest, pins };
+}

package/edition/develop-edition.mjs

@@ -1,23 +1,27 @@
 #!/usr/bin/env node
 // develop-edition — the develop edition's command line.
 //
-//   resolve <id> --pins <file> --out <dir> --registry <namespace>
+//   resolve <id> --pins <file> --out <dir> --registry <root>
 //           --engine-image <repository>@sha256:<digest> [--local]
 //       resolve the edition from the snapshot, seal it against the develop image
 //       repositories, write the descriptor and the four locks to <dir>, print the target.
 //       The workflow run is recorded from GITHUB_REPOSITORY / GITHUB_RUN_ID;
 //       --local stamps `local` instead, for a resolve outside GitHub Actions.
-//   resolve --definition <file> --catalogue oci://<repo>@sha256:<digest> --pins <file> --out <dir> --registry <namespace>
+//   resolve --definition <file> --pins <file> --out <dir> --registry <root>
 //           --engine-image <repository>@sha256:<digest> [--source-image <source>=<registry>/<prefix>]...
 //           [--catalogue-username <name> --catalogue-token-env <VAR>] [--local]
-//       a CUSTOMER develop edition: the definition resolved against the catalogue (see resolve-customer-edition.mjs),
-//       frozen at the customer's own pins. --pins holds exactly one `sources/<name>` commit per source the definition
-//       declares; the catalogue digest is frozen into the descriptor's provenance pins as `catalogue`. The id is the
-//       definition's. Takes --data-root, --editions-root, --sources-root, --kernel, --cache-dir (no --deploy-root).
-//   target  <id> --pins <file> --registry <namespace>
-//       print <namespace>/xema-edition-<id>:<snapshot hash>. The namespace is always the caller's
-//       (e.g. registry.example.com/acme); the repository prefix comes from
-//       edition-contract.json, and no namespace is implied.
+//       a CUSTOMER develop edition: the definition resolved against the develop catalogue pinned in
+//       catalogue.pin.json beside it (see catalogue-pin.mjs and resolve-customer-edition.mjs), frozen at the
+//       customer's own pins. --pins holds exactly one `sources/<name>` commit per source the definition
+//       declares (`freeze-sources --definition` writes it); the catalogue digest is frozen into the descriptor's
+//       provenance pins as `catalogue`. The id is the definition's. Takes --data-root, --editions-root,
+//       --sources-root, --kernel, --cache-dir (no --deploy-root).
+//   target  <id> --pins <file> --registry <root>
+//       print <root>/<develop segment>/xema-edition-<id>:<snapshot hash>. The root is always the caller's
+//       registry root (e.g. registry.example.com/acme); the develop namespace segment and the repository
+//       prefix come from edition-contract.json, and no root is implied.
+//   target  --definition <file> --pins <file> --registry <root>
+//       the same for a customer edition (id = the definition's; the tag covers the pinned catalogue digest).
 //   freeze-graph --data-sha <sha> --kernel-sha <sha>
 //                --deploy-sha <sha> [--editions-root-url <https url>]
 //                [--overrides <json>] --out <file>
@@ -26,12 +30,21 @@
 //       repositories are pinned at what the workflow checked out; write the pins.
 //   check-existing <id> --pins <file> --artifact <dir> --engine-image <repository>@sha256:<digest>
 //       refuse to reuse a pulled artifact whose descriptor disagrees with this snapshot.
+//   check-existing --definition <file> --pins <file> --artifact <dir> --engine-image <repository>@sha256:<digest>
+//       the same for a customer artifact; its descriptor's catalogue provenance pin must also equal the
+//       pinned develop catalogue digest.
 //   check-overrides --overrides <json>
 //       refuse a pins override that would select the tooling this run executes
 //       (the edition tooling's own repository); the workflow runs it before any other checkout.
 //   freeze-sources <id> --pins <file> [--overrides <json>] --out <file>
 //       add one pin per source the edition's chain declares (run after the editions
 //       root is checked out and passed as --editions-root); write the final pins.
+//   freeze-sources --definition <file> --out <file>
+//       a CUSTOMER edition: one `sources/<name>` pin per source the definition declares, each the head of
+//       refs/heads/develop of that source's repository, resolved once; written exclusively (wx).
+//   kernel-commit --definition <file> [--catalogue-username <name> --catalogue-token-env <VAR>]
+//       fetch the pinned develop catalogue and print its contractAuthority.sourceCommit (one 40-hex line):
+//       the commit the kernel contracts are checked out at. Takes --data-root only (no --kernel).
 //
 // Tokens come from the environment (EVIDENCE_REPOSITORIES_TOKEN, XEMA_GHCR_PULL_TOKEN),
 // never argv. Nothing here writes git or publishes a release edition.
@@ -40,11 +53,12 @@ import { writeFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 
 import { fetchCatalogue } from './catalogue-fetch.mjs';
-import { writeCatalogue } from './catalogue.mjs';
-import { CATALOGUE_FLAG, CATALOGUE_TOKEN_ENV_FLAG, CATALOGUE_USERNAME_FLAG, DEFINITION_FLAG, SOURCE_IMAGE_FLAG } from './customer-flags.mjs';
-import { resolveCustomerDevelopEdition } from './develop-customer-edition.mjs';
+import { readCataloguePin } from './catalogue-pin.mjs';
+import { contractAuthoritySourceCommit, writeCatalogue } from './catalogue.mjs';
+import { CATALOGUE_TOKEN_ENV_FLAG, CATALOGUE_USERNAME_FLAG, DEFINITION_FLAG, SOURCE_IMAGE_FLAG } from './customer-flags.mjs';
+import { customerDevelopFrame, resolveCustomerDevelopEdition } from './develop-customer-edition.mjs';
 import { resolveDevelopEdition } from './develop-edition-resolve.mjs';
-import { assertNoToolingOverride, freezeGraph, freezeSources, lsRemoteDevelopHead } from './develop-freeze.mjs';
+import { assertNoToolingOverride, freezeCustomerSources, freezeGraph, freezeSources, lsRemoteDevelopHead } from './develop-freeze.mjs';
 import { assertCanonicalDistributionId } from './distribution-paths.mjs';
 import { LOCAL_WORKFLOW, assertEngineImage, assertExistingArtifactMatches, developEditionTarget, workflowFromEnv, writeEditionArtifact } from './edition-artifact.mjs';
 import { editionWorkspaceConfig } from './edition-config.mjs';
@@ -57,38 +71,73 @@ import { parseSourceImages } from './resolve-customer-edition.mjs';
 import { composeEdition } from './resolve-distribution.mjs';
 import { readStrictJsonFile } from './strict-json.mjs';
 
+// The roots a verb takes. A customer form (it names --definition) takes fewer: `target` none, `check-existing`
+// the data root and the kernel, `freeze-sources` and `kernel-commit` the data root only (`kernel-commit` runs
+// before the kernel is checked out), `resolve` all but the deploy root.
+const VENDOR_ROOTS = Object.freeze([WorkspaceRoot.Data, WorkspaceRoot.Editions, WorkspaceRoot.Sources, WorkspaceRoot.Kernel, WorkspaceRoot.Deploy, WorkspaceRoot.Cache]);
+const CUSTOMER_ROOTS = Object.freeze({
+  resolve: [WorkspaceRoot.Data, WorkspaceRoot.Editions, WorkspaceRoot.Sources, WorkspaceRoot.Kernel, WorkspaceRoot.Cache],
+  target: [],
+  'check-existing': [WorkspaceRoot.Data, WorkspaceRoot.Kernel],
+  'freeze-sources': [WorkspaceRoot.Data],
+  'kernel-commit': [WorkspaceRoot.Data],
+});
+
 if (isEntryModule(import.meta.url)) {
-  configureEditionWorkspaceFromProcess(
-    process.argv.includes(DEFINITION_FLAG)
-      ? [WorkspaceRoot.Data, WorkspaceRoot.Editions, WorkspaceRoot.Sources, WorkspaceRoot.Kernel, WorkspaceRoot.Cache, WorkspaceRoot.SourceHash]
-      : [WorkspaceRoot.Data, WorkspaceRoot.Editions, WorkspaceRoot.Sources, WorkspaceRoot.Kernel, WorkspaceRoot.Deploy, WorkspaceRoot.Cache, WorkspaceRoot.SourceHash],
-  );
+  const [command] = process.argv.slice(2);
+  const customerForm = process.argv.includes(DEFINITION_FLAG) || command === 'kernel-commit';
+  configureEditionWorkspaceFromProcess(customerForm ? (CUSTOMER_ROOTS[command] ?? VENDOR_ROOTS) : VENDOR_ROOTS, { refuseOthers: customerForm && CUSTOMER_ROOTS[command] !== undefined });
 }
 
-// The flags only a customer develop resolve takes, and the one of them that repeats.
-const CUSTOMER_VALUES = Object.freeze([DEFINITION_FLAG, CATALOGUE_FLAG, CATALOGUE_USERNAME_FLAG, CATALOGUE_TOKEN_ENV_FLAG, SOURCE_IMAGE_FLAG]);
-const CUSTOMER_REQUIRED = Object.freeze([DEFINITION_FLAG, CATALOGUE_FLAG]);
+// Per verb: the vendor form (`positional` id, `values`, `switches`) and, where the verb has one, the customer
+// form: the flags only it takes, the further flags it requires, and the vendor flags it refuses.
+const CREDENTIAL_FLAGS = Object.freeze([CATALOGUE_USERNAME_FLAG, CATALOGUE_TOKEN_ENV_FLAG]);
 const REPEATABLE = Object.freeze([SOURCE_IMAGE_FLAG]);
 
 const COMMANDS = Object.freeze({
-  resolve: { positional: true, values: ['--pins', '--out', '--registry', '--engine-image', ...CUSTOMER_VALUES], switches: ['--local'] },
-  target: { positional: true, values: ['--pins', '--registry'], switches: [] },
+  resolve: {
+    positional: true,
+    values: ['--pins', '--out', '--registry', '--engine-image'],
+    switches: ['--local'],
+    required: ['--pins', '--out', '--registry', '--engine-image'],
+    customer: { values: [DEFINITION_FLAG, ...CREDENTIAL_FLAGS, SOURCE_IMAGE_FLAG], required: ['--pins', '--out', '--registry', '--engine-image'], refused: [] },
+  },
+  target: {
+    positional: true,
+    values: ['--pins', '--registry'],
+    switches: [],
+    required: ['--pins', '--registry'],
+    customer: { values: [DEFINITION_FLAG], required: ['--pins', '--registry'], refused: [] },
+  },
   'freeze-graph': {
     positional: false,
     values: ['--data-sha', '--kernel-sha', '--deploy-sha', '--editions-root-url', '--overrides', '--out'],
     switches: [],
+    required: ['--data-sha', '--kernel-sha', '--deploy-sha', '--out'],
+  },
+  'freeze-sources': {
+    positional: true,
+    values: ['--pins', '--overrides', '--out'],
+    switches: [],
+    required: ['--pins', '--out'],
+    customer: { values: [DEFINITION_FLAG], required: ['--out'], refused: ['--pins', '--overrides'] },
+  },
+  'check-overrides': { positional: false, values: ['--overrides'], switches: [], required: ['--overrides'] },
+  'check-existing': {
+    positional: true,
+    values: ['--pins', '--artifact', '--engine-image'],
+    switches: [],
+    required: ['--pins', '--artifact', '--engine-image'],
+    customer: { values: [DEFINITION_FLAG], required: ['--pins', '--artifact', '--engine-image'], refused: [] },
+  },
+  'kernel-commit': {
+    positional: false,
+    values: [],
+    switches: [],
+    required: [],
+    customerOnly: true,
+    customer: { values: [DEFINITION_FLAG, ...CREDENTIAL_FLAGS], required: [], refused: [] },
   },
-  'freeze-sources': { positional: true, values: ['--pins', '--overrides', '--out'], switches: [] },
-  'check-overrides': { positional: false, values: ['--overrides'], switches: [] },
-  'check-existing': { positional: true, values: ['--pins', '--artifact', '--engine-image'], switches: [] },
-});
-const REQUIRED = Object.freeze({
-  resolve: ['--pins', '--out', '--registry', '--engine-image'],
-  target: ['--pins', '--registry'],
-  'freeze-graph': ['--data-sha', '--kernel-sha', '--deploy-sha', '--out'],
-  'freeze-sources': ['--pins', '--out'],
-  'check-overrides': ['--overrides'],
-  'check-existing': ['--pins', '--artifact', '--engine-image'],
 });
 
 /** Parse `<command> [<id>] --flag value ...` against the closed vocabulary of the command. */
@@ -98,13 +147,14 @@ export function parseDevelopEditionArgs(argv) {
   if (spec === undefined) {
     throw new Error(`unknown command ${JSON.stringify(command)}; expected ${Object.keys(COMMANDS).join(' | ')}`);
   }
+  const customerValues = spec.customer?.values ?? [];
   const options = {};
   const positional = [];
   for (let i = 0; i < rest.length; i += 1) {
     const arg = rest[i];
     if (spec.switches.includes(arg)) {
       options[arg] = true;
-    } else if (spec.values.includes(arg)) {
+    } else if (spec.values.includes(arg) || customerValues.includes(arg)) {
       const value = rest[i + 1];
       if (value === undefined || (value.startsWith('--') && value.length > 2)) {
         throw new Error(`${arg} requires a value`);
@@ -123,21 +173,22 @@ export function parseDevelopEditionArgs(argv) {
       positional.push(arg);
     }
   }
-  const customer = command === 'resolve' && CUSTOMER_VALUES.some((flag) => options[flag] !== undefined);
+  const customer = spec.customer !== undefined && (spec.customerOnly === true || customerValues.some((flag) => options[flag] !== undefined));
   if (customer) {
-    for (const required of CUSTOMER_REQUIRED) {
-      if (options[required] === undefined) {throw new Error(`a customer develop resolve requires ${required}`);}
+    if (options[DEFINITION_FLAG] === undefined) {throw new Error(`a customer ${command} requires ${DEFINITION_FLAG}`);}
+    for (const refused of spec.customer.refused) {
+      if (options[refused] !== undefined) {throw new Error(`a customer ${command} takes no ${refused}`);}
     }
-    if (positional.length !== 0) {throw new Error('a customer develop resolve takes no <distribution-id>: the id is the definition\'s');}
+    if (positional.length !== 0) {throw new Error(`a customer ${command} takes no <distribution-id>: the id is the definition's`);}
   } else if (spec.positional ? positional.length !== 1 : positional.length !== 0) {
     throw new Error(`${command} takes ${spec.positional ? 'exactly one <distribution-id>' : 'no positional argument'}`);
   }
-  for (const required of REQUIRED[command]) {
+  for (const required of customer ? spec.customer.required : spec.required) {
     if (options[required] === undefined) {throw new Error(`${command} requires ${required}`);}
   }
   if (spec.positional && !customer) {assertCanonicalDistributionId(positional[0]);}
   if (options['--engine-image'] !== undefined) {assertEngineImage(options['--engine-image']);}
-  return { command, id: positional[0], options };
+  return { command, id: positional[0], options, customer };
 }
 
 function parseOverrides(text) {
@@ -154,15 +205,15 @@ function writeOnce(path, value) {
 }
 
 function headResolver(env) {
-  const token = env.EVIDENCE_REPOSITORIES_TOKEN;
-  const username = editionWorkspaceConfig().sourceAuthUsername;
-  return (url) => lsRemoteDevelopHead(url, { username, token });
+  return (source) => lsRemoteDevelopHead(source, { workspace: editionWorkspaceConfig(), env });
 }
 
 /** A customer develop resolve: the artifact (descriptor and four locks, no catalogue: it is not an offering) goes to --out. */
 async function resolveCustomer(options, env) {
+  const ref = readCataloguePin({ definitionFile: options[DEFINITION_FLAG], channel: EditionChannel.Develop });
   const { catalogue, digest } = await fetchCatalogue({
-    ref: options[CATALOGUE_FLAG],
+    ref,
+    channel: EditionChannel.Develop,
     username: options[CATALOGUE_USERNAME_FLAG],
     tokenEnv: options[CATALOGUE_TOKEN_ENV_FLAG],
     env,
@@ -194,15 +245,37 @@ async function resolveCustomer(options, env) {
   console.log(target);
 }
 
+/**
+ * The commit the pinned develop catalogue's contract authority was taken at. The kernel contracts are
+ * not checked out yet when this runs, so nothing here validates against kernel schemas: the catalogue
+ * parser is kernel-free, and the one field read is `contractAuthority.sourceCommit`, held to 40 hex.
+ */
+async function customerKernelCommit(options, env) {
+  const ref = readCataloguePin({ definitionFile: options[DEFINITION_FLAG], channel: EditionChannel.Develop });
+  const { catalogue } = await fetchCatalogue({
+    ref,
+    channel: EditionChannel.Develop,
+    username: options[CATALOGUE_USERNAME_FLAG],
+    tokenEnv: options[CATALOGUE_TOKEN_ENV_FLAG],
+    env,
+  });
+  console.log(contractAuthoritySourceCommit(catalogue));
+}
+
 async function run(argv, env) {
-  const { command, id, options } = parseDevelopEditionArgs(argv);
+  const { command, id, options, customer } = parseDevelopEditionArgs(argv);
   switch (command) {
     case 'target': {
+      if (customer) {
+        const frame = customerDevelopFrame({ definitionFile: options[DEFINITION_FLAG], pinsFile: options['--pins'] });
+        console.log(developEditionTarget(frame.id, frame.pins, { registry: options['--registry'] }));
+        return;
+      }
       console.log(developEditionTarget(id, readStrictJsonFile(options['--pins']), { registry: options['--registry'] }));
       return;
     }
     case 'resolve': {
-      if (options[DEFINITION_FLAG] !== undefined) {return resolveCustomer(options, env);}
+      if (customer) {return resolveCustomer(options, env);}
       const pins = readStrictJsonFile(options['--pins']);
       const workflow = options['--local'] ? LOCAL_WORKFLOW : workflowFromEnv(env);
       const target = developEditionTarget(id, pins, { registry: options['--registry'] });
@@ -224,6 +297,19 @@ async function run(argv, env) {
       return;
     }
     case 'check-existing': {
+      if (customer) {
+        const frame = customerDevelopFrame({ definitionFile: options[DEFINITION_FLAG], pinsFile: options['--pins'] });
+        assertExistingArtifactMatches({
+          artifactDir: resolve(options['--artifact']),
+          distributionId: frame.id,
+          channel: EditionChannel.Develop,
+          evidenceTrustPolicy: await descriptorEvidenceTrust({ channel: EditionChannel.Develop }),
+          pins: frame.pins,
+          engineImage: options['--engine-image'],
+          catalogueDigest: frame.catalogueDigest,
+        });
+        return;
+      }
       assertExistingArtifactMatches({
         artifactDir: resolve(options['--artifact']),
         distributionId: id,
@@ -252,6 +338,17 @@ async function run(argv, env) {
       return;
     }
     case 'freeze-sources': {
+      if (customer) {
+        writeOnce(
+          options['--out'],
+          freezeCustomerSources({
+            definition: readStrictJsonFile(options[DEFINITION_FLAG]),
+            resolveHead: headResolver(env),
+            sourceRepositoryUrlPrefix: editionWorkspaceConfig().sourceRepositoryUrlPrefix,
+          }),
+        );
+        return;
+      }
       const pins = readStrictJsonFile(options['--pins']);
       const { parseDistribution } = await loadKernelDistributionSchemas();
       const declaredSources = composeEdition(parseDistribution, id, snapshotPinSource(pins)).declaredSources;
@@ -261,6 +358,8 @@ async function run(argv, env) {
       );
       return;
     }
+    case 'kernel-commit':
+      return customerKernelCommit(options, env);
     default:
       throw new Error(`unhandled command ${command}`);
   }