@xemahq/edition-tooling 0.0.0-stage → 0.1.1

package/edition/definition-checkout.mjs

@@ -0,0 +1,96 @@
+// definition-checkout — a distribution definition named as a repository triple, and the checkout that must hold it.
+//
+// The catalogue-free customer develop resolve (develop-catalogue-free-resolve.mjs) names the vendor offering it builds
+// on as `--offering <owner>/<repo>,<path>,<dataRoot>` and the customer definition as `--definition-at` in the same form:
+// the repository, the distribution directory and the data root inside it, each repository-relative. The offering is
+// read from the vendor data checkout, which must BE that triple: the repository the data root declares
+// (`dataRootRepositoryUrl`), clean at the pinned data commit, with the data root and the editions root's distribution
+// directory where the triple says.
+
+import { execFileSync } from 'node:child_process';
+import { existsSync, realpathSync } from 'node:fs';
+import { basename, join, normalize, relative } from 'node:path';
+
+import { canonicalPublicHttpsRepositoryUrl } from './canonical-repository-url.mjs';
+import { assertCanonicalDistributionId } from './distribution-paths.mjs';
+import { editionWorkspaceConfig } from './edition-config.mjs';
+import { dataRoot, editionsRoot } from './edition-workspace.mjs';
+
+const REPOSITORY_PATTERN = /^[A-Za-z0-9][A-Za-z0-9-]*\/[A-Za-z0-9._-]+$/;
+const RELATIVE_SEGMENT = /^[A-Za-z0-9._-]+$/;
+
+export class DataRootRepositoryUndeclaredError extends Error {
+  constructor() {
+    super('edition-workspace.json declares no dataRootRepositoryUrl; the definition checkout cannot be held to the data root\'s repository');
+    this.name = 'DataRootRepositoryUndeclaredError';
+  }
+}
+
+/** The data root's repository URL, from the workspace declaration; refused by name when it declares none. */
+export function declaredDataRootRepositoryUrl() {
+  const url = editionWorkspaceConfig().dataRootRepositoryUrl;
+  if (url === undefined) {throw new DataRootRepositoryUndeclaredError();}
+  return url;
+}
+
+/** A repository-relative path: `.` or `/`-separated plain segments, never absolute, never `..`. */
+function relativePath(text, what, flag) {
+  if (text === '.') {return '.';}
+  const segments = text.split('/');
+  if (text === '' || segments.some((segment) => !RELATIVE_SEGMENT.test(segment) || segment === '.' || segment === '..')) {
+    throw new Error(`${flag} ${what} ${JSON.stringify(text)} is not a repository-relative path ("." or plain segments joined by "/")`);
+  }
+  return segments.join('/');
+}
+
+/** `<owner>/<repo>,<path>,<dataRoot>` (of `flag`) -> `{ repository, path, dataRoot }`. */
+export function parseDefinitionTriple(text, flag) {
+  const parts = typeof text === 'string' ? text.split(',') : [];
+  if (parts.length !== 3) {
+    throw new Error(`${flag} is <owner>/<repo>,<path>,<dataRoot>, got ${JSON.stringify(text)}`);
+  }
+  const [repository, path, root] = parts;
+  if (!REPOSITORY_PATTERN.test(repository)) {
+    throw new Error(`${flag} repository ${JSON.stringify(repository)} is not <owner>/<repo>`);
+  }
+  const definition = { repository, path: relativePath(path, 'path', flag), dataRoot: relativePath(root, 'dataRoot', flag) };
+  if (definition.path === '.') {throw new Error(`${flag} path names the distribution directory, never the repository root`);}
+  assertCanonicalDistributionId(basename(definition.path));
+  return definition;
+}
+
+const runGitText = (args, cwd) => execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+
+/**
+ * Consistency with the caller's checkout: the data root checkout is the definition, the repository the data root
+ * declares, clean (untracked files included) at `dataSha`, with the data root and the editions root's distribution
+ * directory at the definition's dataRoot and path. Returns the id.
+ */
+export function assertDefinitionCheckout({ definition, dataSha, flag, shaLabel, git = runGitText }) {
+  const declared = canonicalPublicHttpsRepositoryUrl(declaredDataRootRepositoryUrl(), 'the data root\'s dataRootRepositoryUrl');
+  const named = canonicalPublicHttpsRepositoryUrl(`https://github.com/${definition.repository}.git`, `${flag} repository`);
+  if (declared !== named) {
+    throw new Error(`${flag} names ${definition.repository}, but the data root is the repository ${declared}: the data root is the definition's own`);
+  }
+  const top = realpathSync(git(['rev-parse', '--show-toplevel'], dataRoot()));
+  const head = git(['rev-parse', 'HEAD'], top);
+  if (head !== dataSha) {
+    throw new Error(`${shaLabel} is ${dataSha}, but the definition checkout ${top} is at ${head}`);
+  }
+  const dirty = git(['status', '--porcelain', '--untracked-files=all'], top);
+  if (dirty !== '') {
+    throw new Error(`the definition checkout ${top} has uncommitted or untracked changes: the definition is read only as committed at ${shaLabel}`);
+  }
+  const at = (dir) => normalize(relative(top, realpathSync(dir)) || '.');
+  if (at(dataRoot()) !== normalize(definition.dataRoot)) {
+    throw new Error(`--data-root is ${at(dataRoot())} of the definition checkout, but ${flag} names the data root ${definition.dataRoot}`);
+  }
+  const id = basename(definition.path);
+  if (!existsSync(join(editionsRoot(), id))) {
+    throw new Error(`the editions root holds no "${id}", but ${flag} names ${definition.path}`);
+  }
+  if (at(join(editionsRoot(), id)) !== normalize(definition.path)) {
+    throw new Error(`the editions root holds "${id}" at ${at(join(editionsRoot(), id))} of the definition checkout, but ${flag} names ${definition.path}`);
+  }
+  return id;
+}

package/edition/develop-build-record.mjs

@@ -0,0 +1,122 @@
+// develop-build-record — reading a member's develop build record from the registry, the one core the dev lane's channel
+// readers share (develop-channel-record.mjs: select-records, image-record and resolve --channel).
+//
+// A record is the single build-record layer of the manifest a tag names under <root>/build-records/<name>, parsed with
+// the CLI's own @xemahq/contracts BuildRecordSchema and held to its member (producer repository, branch). Nothing here verifies a
+// signature: the dev lane's records are unsigned and their trust is the registry write ACL.
+//
+// Two failure classes: `RecordRefused` (the record is missing, or the record itself says no) and a plain Error (the
+// registry could not answer), which the operator retries rather than reads.
+
+import { BUILD_RECORD_MEDIA_TYPE, BuildRecordSchema, buildRecordTag, compareBuildRecordRuns, parseBuildRecordTag } from '@xemahq/contracts/distribution';
+
+import { canonicalPublicHttpsRepositoryUrl, repositoryOwnerName } from './canonical-repository-url.mjs';
+import { RecordRefused } from './record-refused.mjs';
+import { registryClientFactory } from './registry-client-factory.mjs';
+import { splitImageRef } from './registry-credentials.mjs';
+import { isNotPublishedYet } from './seal-image-digests.mjs';
+
+/** The repository segment, under the registry root, that holds a member's build records. */
+export const BUILD_RECORDS_SEGMENT = 'build-records';
+/** The record's producer is a kind this CLI has no claims for: a closed set, never guessed at. */
+export class UnknownBuildRecordProducerError extends RecordRefused {
+  constructor(repo, kind) {
+    super(repo, `the record's producer kind ${JSON.stringify(kind)} is not one this CLI can read`);
+    this.name = 'UnknownBuildRecordProducerError';
+  }
+}
+
+/** The build-record contract of the `@xemahq/contracts` this CLI itself depends on: no kernel checkout, no workspace root. */
+export const CLI_BUILD_RECORD_CONTRACT = Object.freeze({ BUILD_RECORD_MEDIA_TYPE, BuildRecordSchema, buildRecordTag, parseBuildRecordTag, compareBuildRecordRuns });
+
+/** The member's `owner/name`, from its declared repository URL. */
+export const memberOwnerName = (memberRepositoryUrl) =>
+  repositoryOwnerName(canonicalPublicHttpsRepositoryUrl(memberRepositoryUrl, 'repositoryUrl'), 'repositoryUrl');
+
+/**
+ * What a record's producer says, read through the ONE switch over its kind: the repository that called the
+ * record workflow (the cosign caller claim, held equal to the member's) and the run the snapshot names.
+ */
+export function producerClaims({ record, repo, memberRepository }) {
+  switch (record.producer?.kind) {
+    case 'github-actions': {
+      const { repository, runNumber, runAttempt } = record.producer;
+      if (repository !== memberRepository) {throw new RecordRefused(repo, `record is produced by repository ${repository}, not ${memberRepository}`);}
+      return { repository, snapshot: `${runNumber}.${runAttempt}` };
+    }
+    default:
+      throw new UnknownBuildRecordProducerError(repo, record.producer?.kind);
+  }
+}
+
+/** Run one registry client call; ONLY a failure of the client itself is "the registry did not answer". */
+async function fromRegistry(repo, what, call) {
+  try {
+    return await call();
+  } catch (error) {
+    throw new Error(`select-records: ${repo}: the registry did not answer for ${what}: ${error.message}`, { cause: error });
+  }
+}
+
+/** Read one record by its tag: manifest by digest, its single layer, parsed against the kernel's schema. */
+export async function readRecord({ kernel, client, repository, repo, tag, absentIsRefusal = false }) {
+  let served;
+  try {
+    served = await fromRegistry(repo, `${repository}:${tag}`, () => client.getManifestByTag(repository, tag));
+  } catch (error) {
+    if (absentIsRefusal && isNotPublishedYet(error.cause)) {throw new RecordRefused(repo, `${repository}:${tag} does not exist`);}
+    throw error;
+  }
+  const manifest = await fromRegistry(repo, `${repository}@${served.digest}`, () => client.getManifestByDigest(repository, served.digest));
+  const layers = manifest.document.layers;
+  if (!Array.isArray(layers) || layers.length !== 1) {
+    throw new RecordRefused(repo, `record ${tag} has ${Array.isArray(layers) ? layers.length : 'no'} layers, not exactly one`);
+  }
+  const [layer] = layers;
+  if (layer.mediaType !== kernel.BUILD_RECORD_MEDIA_TYPE) {
+    throw new RecordRefused(repo, `record ${tag} layer media type is ${JSON.stringify(layer.mediaType)}, not ${kernel.BUILD_RECORD_MEDIA_TYPE}`);
+  }
+  const bytes = await fromRegistry(repo, `${repository}@${layer.digest}`, () => client.getBlob(repository, layer.digest));
+  let document;
+  try {
+    document = JSON.parse(bytes.toString('utf8'));
+  } catch (error) {
+    throw new RecordRefused(repo, `record ${tag} is not JSON: ${error.message}`);
+  }
+  const parsed = kernel.BuildRecordSchema.safeParse(document);
+  if (!parsed.success) {throw new RecordRefused(repo, `record ${tag} does not parse as a build record: ${parsed.error.message}`);}
+  return { record: parsed.data, digest: served.digest };
+}
+
+/** The record content check both lanes share: it is for the branch asked. */
+export function assertRecordBranch({ record, repo, tag, branch }) {
+  if (record.branch !== branch) {throw new RecordRefused(repo, `record ${tag} is for branch ${record.branch}, not ${branch}`);}
+}
+
+/** The registry repository that holds a member's build records: under the develop store root the member declares. */
+export function recordsRepositoryOf(member) {
+  if (member.developImageRegistry === undefined) {
+    throw new RecordRefused(member.repo, 'declares no developImageRegistry, so its build records repository is unknown');
+  }
+  return `${member.developImageRegistry}/${BUILD_RECORDS_SEGMENT}/${member.repo.split('/').at(-1)}`;
+}
+
+/**
+ * A member's build-records repository, the authority it lives on and that authority's registry client. The client is
+ * bound to the authority, so `repository` is the path under it; `ref` is the full reference, for messages.
+ */
+export function recordsClientOf({ clientFor, member }) {
+  const ref = recordsRepositoryOf(member);
+  const { authority, repository } = splitImageRef(ref);
+  return { ref, repository, authority, client: clientFor(authority) };
+}
+
+/**
+ * The CLI's build-record contract and the registry clients, with no cosign and no trust policy: what a read of a channel tag needs. The
+ * injections are replaced by tests.
+ */
+export async function withChannelReader({ env, loadKernel = async () => CLI_BUILD_RECORD_CONTRACT, clientsOverride }, use) {
+  const kernel = await loadKernel();
+  const { clientFor } = registryClientFactory({ clientsOverride, env });
+  return use({ kernel, clientFor });
+}

package/edition/develop-catalogue-free-resolve.mjs

@@ -0,0 +1,282 @@
+// develop-catalogue-free-resolve — the catalogue-free CUSTOMER develop resolve:
+//
+//   xema-edition develop resolve --definition-at <owner>/<repo>,<path>,<dataRoot> --offering <owner>/<repo>,<path>,<dataRoot>
+//       --pins <file> --out <dir> --registry <root> --engine-repository <repository> --engine-signer <certificate identity>
+//       --cosign <abs path> --offering-previous-lock <file> --offering-previous-lock-sha256 <hex>
+//       (--previous-lock <file> --previous-lock-sha256 <hex> | --first-seal) [--source-image <source>=<registry>/<prefix>]... [--local]
+//
+// The OFFICIAL lane (a customer definition built on a vendor offering): it keeps its verification. It resolves the
+// vendor offering it builds on IN THE SAME CALL instead of pinning a published catalogue: no catalogue.pin.json is read (its presence beside the definition is refused, never
+// a fallback), and no public flag substitutes a catalogue file. Two workspaces, two steps, one CLI:
+//
+//   vendor    a child process of this CLI on the VENDOR roots (the roots this call was given), the vendor step
+//             (develop-catalogue-free-vendor.mjs): the offering resolved on the VERIFIED lane (the engine found and
+//             cosign-proven from --engine-repository/--engine-signer, the images probed by content hash, the git-sourced
+//             bundles cosign-verified), writing the vendor artifact and catalogue.json into a scratch directory. It is
+//             not the vendor `develop resolve` verb, which is the channel lane and verifies none of this. --offering names
+//             the offering's directory inside the vendor data checkout, held to it (definition-checkout.mjs: the checkout
+//             is the declared repository, clean at the vendor data pin, the data root and the directory where the triple
+//             says). Never defaulted.
+//   customer  the definition repository fetched at --pins "definition-repository" (the walk's git source fetch, by
+//             exact commit) and its tree at that commit checked out from the object store into this call's private
+//             scratch before the vendor step runs (a temporary index, symlinks as plain files): the shared fetch cache
+//             is never read again, so a cache tree that moves or changes mid-run cannot change what is resolved. The
+//             workspace is re-stated on the scratch copy's roots (data = <copy>/<dataRoot>, editions = the parent of
+//             <copy>/<path>, a fresh sources root, the same cache), and the customer resolve run against the catalogue
+//             the vendor step wrote. The edition's pins are the catalogue-free form
+//             (edition-contract.json provenancePins.customerForms): the vendor pins, the customer's own
+//             sources/<name> commits, "definition-repository" and the definition digest, never a catalogue pin.
+//             The catalogue CONTENT digest is sha256 of the EXACT catalogue.json bytes the vendor step wrote (parsed
+//             strictly, so a duplicate key refuses), the convention of the catalogue layer digest of an offering
+//             artifact (produce-edition-catalogue-evidence's predicate catalogueDigest). It goes into the distribution
+//             lock only, as catalogueContentDigest (kernel edition protocol v37), never catalogueDigest: no catalogue
+//             artifact exists, so the lock never names one (catalogue-lock-field.mjs).
+//
+// --pins is the COMPLETE frozen set; nothing here reads a head. It is split once, before anything is fetched: a
+// sources/<name> key the definition declares is the customer's own, every other key but "definition-repository" goes
+// to the vendor step (which refuses what its offering does not declare). A source name both the offering and the
+// definition declare is refused before the vendor step: its one pin could not say whose source it is.
+
+import { execFileSync, spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { basename, dirname, join, resolve } from 'node:path';
+
+import { sha256Digest } from './canonical-evidence-json.mjs';
+import { CATALOGUE_PIN_FILE } from './catalogue-pin.mjs';
+import { CATALOGUE_FILE, parseCatalogue } from './catalogue.mjs';
+import { customerPreviousSeal, customerSourceImages, declaredSourceNamesOf, resolveCustomerChannelEdition } from './customer-edition-verbs.mjs';
+import { DEFINITION_AT_FLAG, OFFERING_FLAG, OFFERING_PREVIOUS_LOCK_FLAG, OFFERING_PREVIOUS_LOCK_SHA256_FLAG } from './customer-flags.mjs';
+import { assertDefinitionCheckout, parseDefinitionTriple } from './definition-checkout.mjs';
+import { vendorStepArgs } from './develop-catalogue-free-vendor.mjs';
+import { customerDevelopGitBundleVerifier } from './develop-git-bundles.mjs';
+import { assertCanonicalDistributionId } from './distribution-paths.mjs';
+import { LOCAL_WORKFLOW, parseEditionDescriptor, snapshotEditionTarget, workflowFromEnv, writeEditionArtifact } from './edition-artifact.mjs';
+import { resetEditionWorkspaceConfig } from './edition-config.mjs';
+import { CATALOGUE_PIN_KEY, DEFINITION_PIN_KEY, DEFINITION_REPOSITORY_PIN_KEY, EDITION_DESCRIPTOR_FILE, EditionChannel, EditionKind, VENDOR_MEMBER_PIN_PATTERN } from './edition-constants.mjs';
+import { WorkspaceRoot, cacheDir, configureEditionWorkspace, configuredWorkspace, editionsRoot, workspaceArgv } from './edition-workspace.mjs';
+import { descriptorEvidenceTrust } from './evidence-trust-policy.mjs';
+import { materializeGitSource } from './external-source-walk.mjs';
+import { serializeJson } from './lib.mjs';
+import { dataPinKey, isSourcePinKey, sortedSnapshotPins, sourceNameOfPinKey } from './pin-source.mjs';
+import { parseStrictJson, readStrictJsonFile } from './strict-json.mjs';
+
+export { DEFINITION_REPOSITORY_PIN_KEY };
+/** The definition file in a definition directory (the editions-root layout). */
+const DEFINITION_FILE = 'xema-distribution.json';
+const SHA_PATTERN = /^[0-9a-f]{40}$/;
+
+/**
+ * `sha256:<hex>` of the exact catalogue.json bytes the vendor step wrote (the catalogue layer digest convention): the
+ * lock's catalogueContentDigest, never a pin.
+ */
+export const catalogueContentDigestOf = (bytes) => sha256Digest(bytes);
+
+/**
+ * --pins checked and split once, before anything is fetched: `{ definitionRepositoryCommit, members }`, the members
+ * every other key. "catalogue" and "definition" are computed, never input.
+ */
+export function splitCatalogueFreePins(pins) {
+  if (pins === null || typeof pins !== 'object' || Array.isArray(pins)) {throw new Error('--pins must be an object mapping pin key -> 40-hex commit');}
+  for (const computed of [CATALOGUE_PIN_KEY, DEFINITION_PIN_KEY]) {
+    if (computed in pins) {throw new Error(`--pins names "${computed}": a catalogue-free resolve computes the definition digest and pins no catalogue`);}
+  }
+  const { [DEFINITION_REPOSITORY_PIN_KEY]: definitionRepositoryCommit, ...members } = pins;
+  if (typeof definitionRepositoryCommit !== 'string' || !SHA_PATTERN.test(definitionRepositoryCommit)) {
+    throw new Error(`--pins "${DEFINITION_REPOSITORY_PIN_KEY}" must be the 40-hex commit the definition repository is read at, got ${JSON.stringify(definitionRepositoryCommit)}`);
+  }
+  if (!Object.keys(members).some((key) => VENDOR_MEMBER_PIN_PATTERN.test(key))) {
+    throw new Error('--pins carries no vendor member pin (repos/<x> or submodules/<x>): a catalogue-free resolve resolves the vendor offering from them');
+  }
+  return { definitionRepositoryCommit, members };
+}
+
+/**
+ * The members of --pins between the two steps: `{ own, vendor }`, own the sources/<name> keys the definition declares.
+ * `offering` and `definition` are `{ label, sourceNames }`: a source name both declare is refused, naming both.
+ */
+export function partitionCatalogueFreePins(members, { offering, definition }) {
+  const vendorNames = new Set(offering.sourceNames);
+  const shared = [...new Set(definition.sourceNames)].filter((name) => vendorNames.has(name));
+  if (shared.length > 0) {
+    throw new Error(`the source${shared.length === 1 ? '' : 's'} ${shared.map((name) => `"${name}"`).join(', ')} ${shared.length === 1 ? 'is' : 'are'} declared by both the offering ${offering.label} and the definition ${definition.label}: a catalogue-free resolve splits each sources/<name> pin to one of them, so a source name is declared once`);
+  }
+  const ownNames = new Set(definition.sourceNames);
+  const own = {};
+  const vendor = {};
+  for (const [key, commit] of Object.entries(members)) {
+    if (isSourcePinKey(key) && ownNames.has(sourceNameOfPinKey(key))) {own[key] = commit;} else {vendor[key] = commit;}
+  }
+  return { own, vendor: sortedSnapshotPins(vendor) };
+}
+
+/** The definition repository at `commit`, through the source walk's fetch by exact commit; returns its (shared cache) directory. */
+export function fetchDefinitionRepository({ repository, commit, env }) {
+  const source = { kind: 'git', name: DEFINITION_REPOSITORY_PIN_KEY, url: `https://github.com/${repository}.git`, ref: commit };
+  return materializeGitSource({ source, cacheRoot: join(cacheDir(), 'definition-repositories', ...repository.split('/')), env }).directory;
+}
+
+/**
+ * The tree of `commit` in the repository at `repository`, written into the new directory `into` from the object store
+ * (a temporary index beside `into`, never the repository's own index or worktree; symlinks as plain files, so nothing
+ * read from `into` resolves outside it). Returns `into`.
+ */
+export function materializeDefinitionCommit({ repository, commit, into }) {
+  mkdirSync(into);
+  const env = { ...process.env, GIT_INDEX_FILE: `${into}.index`, GIT_NO_LAZY_FETCH: '1' };
+  const git = (args) => execFileSync('git', ['-C', repository, '-c', 'core.symlinks=false', ...args], { env, stdio: ['ignore', 'pipe', 'pipe'] });
+  try {
+    git(['read-tree', `${commit}^{tree}`]);
+    git(['checkout-index', '--all', `--prefix=${into}/`]);
+  } finally {
+    rmSync(`${into}.index`, { force: true });
+  }
+  return into;
+}
+
+/** The argv of the vendor step's child (after the node binary): the offering's own previous seal, the engine flags, the vendor roots. */
+export function vendorResolveArgs({ offeringId, pinsFile, outDir, options, roots }) {
+  return vendorStepArgs({
+    offeringId,
+    pinsFile,
+    outDir,
+    registry: options['--registry'],
+    engine: { repository: options['--engine-repository'], signer: options['--engine-signer'] },
+    cosignBinary: options['--cosign'],
+    previousLock: { path: options[OFFERING_PREVIOUS_LOCK_FLAG], sha256: options[OFFERING_PREVIOUS_LOCK_SHA256_FLAG] },
+    roots,
+  });
+}
+
+/** The vendor step: a child of this CLI (develop-catalogue-free-vendor.mjs) on the vendor roots, writing into `outDir`. */
+export function runVendorResolve({ offeringId, pinsFile, outDir, options, env, roots }) {
+  const result = spawnSync(process.execPath, vendorResolveArgs({ offeringId, pinsFile, outDir, options, roots }), { env, stdio: ['ignore', 'ignore', 'inherit'] });
+  if (result.error !== undefined || result.status !== 0) {
+    throw new Error(`the vendor resolve of the offering "${offeringId}" failed (${result.error?.message ?? `exit ${result.status ?? result.signal}`}); its refusal is above`);
+  }
+}
+
+/**
+ * The catalogue the vendor step wrote, its digest, the engine it proved, and the proof the vendor artifact is that offering
+ * at those pins. (The digest is of `bytes` as read, the same bytes parsed: never a re-serialisation.)
+ */
+export function readVendorCatalogue({ outDir, offeringId, vendorPins }) {
+  const path = join(outDir, CATALOGUE_FILE);
+  const bytes = readFileSync(path);
+  const catalogue = parseCatalogue(parseStrictJson(bytes.toString('utf8'), path));
+  if (catalogue.offeringId !== offeringId || catalogue.channel !== EditionChannel.Develop) {
+    throw new Error(`the vendor step wrote the catalogue of "${catalogue.offeringId}" (${catalogue.channel}), not of the develop offering "${offeringId}"`);
+  }
+  const descriptor = parseEditionDescriptor(readStrictJsonFile(join(outDir, EDITION_DESCRIPTOR_FILE)));
+  if (serializeJson(sortedSnapshotPins(descriptor.provenance.pins)) !== serializeJson(vendorPins)) {
+    throw new Error(`the vendor step resolved "${offeringId}" at other pins than the vendor pins it was given`);
+  }
+  return { catalogue, catalogueContentDigest: catalogueContentDigestOf(bytes), engineImage: descriptor.engine.image };
+}
+
+/** Run `body` with the workspace on `roots`, restoring the previous roots after. */
+async function onRoots(roots, body) {
+  const restored = configuredWorkspace();
+  resetEditionWorkspaceConfig();
+  configureEditionWorkspace(roots);
+  try {
+    return await body();
+  } finally {
+    resetEditionWorkspaceConfig();
+    configureEditionWorkspace(restored);
+  }
+}
+
+/**
+ * The catalogue-free customer develop resolve (see the header). Writes the artifact to --out and returns
+ * `{ id, pins, target, catalogueContentDigest, engineImage }`. The edition records the engine the vendor step proved, and
+ * carries the customer's own composed generations from --previous-lock (or --first-seal) under the customer's id.
+ * `fetchDefinition`, `vendorResolve`, `resolveCustomer`, `evidenceTrust` and `write` are replaced by tests; `print`
+ * receives the target.
+ */
+export async function resolveCatalogueFree({
+  options,
+  env = process.env,
+  fetchDefinition = fetchDefinitionRepository,
+  vendorResolve = runVendorResolve,
+  resolveCustomer = resolveCustomerChannelEdition,
+  evidenceTrust = descriptorEvidenceTrust,
+  write = writeEditionArtifact,
+  print = (line) => console.log(line),
+}) {
+  const definition = parseDefinitionTriple(options[DEFINITION_AT_FLAG], DEFINITION_AT_FLAG);
+  const offering = parseDefinitionTriple(options[OFFERING_FLAG], OFFERING_FLAG);
+  const rawPins = readStrictJsonFile(options['--pins']);
+  const offeringId = assertDefinitionCheckout({ definition: offering, dataSha: rawPins?.[dataPinKey()], flag: OFFERING_FLAG, shaLabel: `--pins "${dataPinKey()}"` });
+  const { definitionRepositoryCommit, members } = splitCatalogueFreePins(rawPins);
+  const offeringLabel = `${offering.repository}:${offering.path}/${DEFINITION_FILE}`;
+  const offeringSourceNames = declaredSourceNamesOf(readStrictJsonFile(join(editionsRoot(), offeringId, DEFINITION_FILE)));
+  const vendorRoots = configuredWorkspace();
+  const scratch = mkdtempSync(join(tmpdir(), 'xema-catalogue-free-'));
+  try {
+    const cached = fetchDefinition({ repository: definition.repository, commit: definitionRepositoryCommit, env });
+    const checkout = materializeDefinitionCommit({ repository: cached, commit: definitionRepositoryCommit, into: join(scratch, DEFINITION_REPOSITORY_PIN_KEY) });
+    const definitionDir = join(checkout, definition.path);
+    const definitionLabel = `${definition.repository}:${definition.path}/${DEFINITION_FILE}`;
+    if (existsSync(join(definitionDir, CATALOGUE_PIN_FILE))) {
+      throw new Error(`${definition.repository}:${definition.path} carries ${CATALOGUE_PIN_FILE}: a definition is resolved against its pinned catalogue (--definition <file>) or catalogue-free, never both`);
+    }
+    const rawDefinition = readStrictJsonFile(join(definitionDir, DEFINITION_FILE));
+    assertCanonicalDistributionId(rawDefinition?.id);
+    if (rawDefinition.id !== basename(definition.path)) {
+      throw new Error(`${definitionLabel} is "${rawDefinition.id}", not the directory's "${basename(definition.path)}"`);
+    }
+    const split = partitionCatalogueFreePins(members, {
+      offering: { label: offeringLabel, sourceNames: offeringSourceNames },
+      definition: { label: definitionLabel, sourceNames: declaredSourceNamesOf(rawDefinition) },
+    });
+    const sourceImages = customerSourceImages(options, rawDefinition);
+    const vendorOut = join(scratch, 'vendor');
+    const pinsFile = join(scratch, 'vendor-pins.json');
+    writeFileSync(pinsFile, serializeJson(split.vendor));
+    vendorResolve({ offeringId, pinsFile, outDir: vendorOut, options, env, roots: workspaceArgv() });
+    const { catalogue, catalogueContentDigest, engineImage } = readVendorCatalogue({ outDir: vendorOut, offeringId, vendorPins: split.vendor });
+    const sources = join(scratch, 'sources');
+    mkdirSync(sources);
+    const customerRoots = {
+      [WorkspaceRoot.Data]: join(checkout, definition.dataRoot),
+      [WorkspaceRoot.Editions]: dirname(definitionDir),
+      [WorkspaceRoot.Sources]: sources,
+      [WorkspaceRoot.Cache]: vendorRoots[WorkspaceRoot.Cache],
+    };
+    return await onRoots(customerRoots, async () => {
+      const { id, pins, ...resolved } = await resolveCustomer({
+        channel: EditionChannel.Develop,
+        rawDefinition,
+        catalogue,
+        catalogueContentDigest,
+        pins: split.own,
+        vendorPins: { ...split.vendor, [DEFINITION_REPOSITORY_PIN_KEY]: definitionRepositoryCommit },
+        previousSeal: customerPreviousSeal(EditionChannel.Develop, options),
+        sourceImages,
+        env,
+        // The customer's git-sourced OCI bundles, verified under the definition's own pinned policy (its data root).
+        developGitBundles: customerDevelopGitBundleVerifier({ channel: EditionChannel.Develop, cosignBinary: options['--cosign'], env }),
+      });
+      const evidenceTrustPolicy = await evidenceTrust({ kind: EditionKind.Resolved, channel: EditionChannel.Develop, consumesCatalogue: true });
+      const target = snapshotEditionTarget(EditionChannel.Develop, id, pins, { registry: options['--registry'], engineImage, sourceImages });
+      write({
+        outDir: resolve(options['--out']),
+        channel: EditionChannel.Develop,
+        distributionId: id,
+        pins,
+        workflow: options['--local'] ? LOCAL_WORKFLOW : workflowFromEnv(env),
+        evidenceTrustPolicy,
+        engineImage,
+        distributionLock: resolved.distributionLock,
+        imageLock: resolved.imageLock,
+        authorizationLock: resolved.authorizationLock,
+        chartSetLock: resolved.chartSetLock,
+      });
+      print(target);
+      return { id, pins, target, catalogueContentDigest, engineImage };
+    });
+  } finally {
+    rmSync(scratch, { recursive: true, force: true });
+  }
+}

package/edition/develop-catalogue-free-vendor.mjs

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+// develop-catalogue-free-vendor — the VENDOR step of the catalogue-free customer develop resolve
+// (develop-catalogue-free-resolve.mjs), an internal entry of the OFFICIAL lane, never a verb:
+//
+//   node develop-catalogue-free-vendor.mjs <offering id> --pins <file> --out <dir> --registry <root>
+//       --engine-repository <repository> --engine-signer <certificate identity> --cosign <absolute-path>
+//       --previous-lock <file> --previous-lock-sha256 <hex> <the vendor roots>
+//
+// The catalogue-free resolve runs it as a child process of this CLI on the vendor roots (the roots it was given), so
+// the vendor resolve has its own kernel load and workspace, and writes the vendor artifact and catalogue.json into the
+// parent's scratch directory. It resolves the offering on the VERIFIED lane (`verifiedVendorLane`): the engine found
+// and cosign-proven (develop-engine-image.mjs), every image probed by its computed content hash, every git-sourced OCI
+// bundle cosign-verified against its frozen source (develop-git-bundles.mjs `createDevelopGitBundleVerifier`), the
+// bundle signers asserted, the third-party pins held to the evidence trust pin, and the descriptor's evidence trust the
+// data root's pinned policy (`descriptorEvidenceTrust`). It seals against the OFFERING's own previous seal, held to its
+// sha256 and the offering's id. The descriptor records LOCAL_WORKFLOW: it never leaves the scratch directory.
+//
+// The channel lane's vendor `develop resolve` (develop-edition.mjs) takes none of this: its engine and digests are
+// the caller's and the build record's.
+
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseArgs } from 'node:util';
+
+import { writeCatalogue } from './catalogue.mjs';
+import { DEVELOP_VENDOR_ROOTS } from './customer-edition-verbs.mjs';
+import { resolveDevelopEdition } from './develop-edition-resolve.mjs';
+import { resolveDevelopEngineImage } from './develop-engine-image.mjs';
+import { createDevelopGitBundleVerifier } from './develop-git-bundles.mjs';
+import { assertCanonicalDistributionId } from './distribution-paths.mjs';
+import { LOCAL_WORKFLOW, writeEditionArtifact } from './edition-artifact.mjs';
+import { EditionChannel, EditionKind } from './edition-constants.mjs';
+import { configureEditionWorkspaceFromProcess, dataRoot, isEntryModule } from './edition-workspace.mjs';
+import { descriptorEvidenceTrust } from './evidence-trust-policy.mjs';
+import { resolvePreviousSeal } from './resolve-images.mjs';
+import { readStrictJsonFile } from './strict-json.mjs';
+import { loadTrustedThirdPartySourcePins } from './third-party-pins-trusted.mjs';
+
+/** The entry the catalogue-free resolve spawns. */
+export const VENDOR_STEP_ENTRY = fileURLToPath(import.meta.url);
+
+/** The step's flags, every one required (`--name` -> parseArgs key `name`). */
+const VENDOR_STEP_FLAGS = Object.freeze(['pins', 'out', 'registry', 'engine-repository', 'engine-signer', 'cosign', 'previous-lock', 'previous-lock-sha256']);
+
+/** The argv of the vendor step (after the node binary), the roots appended as `workspaceArgv()` states them. */
+export function vendorStepArgs({ offeringId, pinsFile, outDir, registry, engine, cosignBinary, previousLock, roots }) {
+  return [
+    VENDOR_STEP_ENTRY, offeringId, '--pins', pinsFile, '--out', outDir, '--registry', registry,
+    '--engine-repository', engine.repository, '--engine-signer', engine.signer, '--cosign', cosignBinary,
+    '--previous-lock', previousLock.path, '--previous-lock-sha256', previousLock.sha256,
+    ...roots,
+  ];
+}
+
+/** `<offering id> --flag value ...`, every flag required, nothing else admitted. */
+export function parseVendorStepArgs(argv) {
+  const { values, positionals } = parseArgs({
+    args: argv,
+    options: Object.fromEntries(VENDOR_STEP_FLAGS.map((name) => [name, { type: 'string' }])),
+    allowPositionals: true,
+    strict: true,
+  });
+  if (positionals.length !== 1) {throw new Error(`the catalogue-free vendor step takes exactly one <offering id>, got ${positionals.length}`);}
+  const missing = VENDOR_STEP_FLAGS.filter((name) => values[name] === undefined);
+  if (missing.length > 0) {throw new Error(`the catalogue-free vendor step requires ${missing.map((name) => `--${name}`).join(', ')}`);}
+  assertCanonicalDistributionId(positionals[0]);
+  return { offeringId: positionals[0], ...values };
+}
+
+/**
+ * The verified lane of the vendor step (see the header), for `resolveDevelopEdition`.
+ *
+ * @param {object} request
+ * @param {object} request.pins the vendor pins (the engine is the one published for their xema-deploy commit)
+ * @param {{repository: string, signer: string}} request.engine
+ * @param {string} request.cosignBinary absolute path of cosign, held to the data root's pinned policy
+ */
+export function verifiedVendorLane({ pins, engine, cosignBinary, env = process.env }) {
+  return Object.freeze({
+    engineImage: () => resolveDevelopEngineImage({ pins, engine, cosignBinary, env }),
+    developGitBundles: createDevelopGitBundleVerifier({ cosignBinary, dataRoot: dataRoot(), env }),
+    checkBundleSigners: true,
+    thirdPartyPins: () => loadTrustedThirdPartySourcePins(dataRoot()),
+  });
+}
+
+/** The vendor step: resolve the offering on the verified lane and write its artifact and catalogue to --out. */
+export async function runVendorStep({ argv, env = process.env, resolveEdition = resolveDevelopEdition, evidenceTrust = descriptorEvidenceTrust }) {
+  const args = parseVendorStepArgs(argv);
+  const pins = readStrictJsonFile(args.pins);
+  const { catalogue, engineImage, ...resolved } = await resolveEdition({
+    id: args.offeringId,
+    pins,
+    env,
+    lane: verifiedVendorLane({ pins, engine: { repository: args['engine-repository'], signer: args['engine-signer'] }, cosignBinary: args.cosign, env }),
+    previousLock: await resolvePreviousSeal({ distributionId: args.offeringId, previousLockPath: args['previous-lock'], previousLockSha256: args['previous-lock-sha256'] }),
+  });
+  const outDir = resolve(args.out);
+  writeEditionArtifact({
+    outDir,
+    channel: EditionChannel.Develop,
+    distributionId: args.offeringId,
+    pins,
+    workflow: LOCAL_WORKFLOW,
+    evidenceTrustPolicy: await evidenceTrust({ kind: EditionKind.Resolved, channel: EditionChannel.Develop }),
+    engineImage,
+    ...resolved,
+  });
+  writeCatalogue(outDir, catalogue);
+}
+
+if (isEntryModule(import.meta.url)) {
+  configureEditionWorkspaceFromProcess(DEVELOP_VENDOR_ROOTS);
+  runVendorStep({ argv: process.argv.slice(2) }).catch((error) => {
+    console.error(`[develop-catalogue-free-vendor] ${error.message}`);
+    process.exit(1);
+  });
+}

package/edition/develop-channel-evidence.mjs

@@ -0,0 +1,23 @@
+// develop-channel-evidence — the evidence trust a vendor develop edition records: its images come from a registry
+// channel (`resolve --images-from <record> --channel <tag>`), the only form of a vendor develop resolve.
+//
+// Channel images are baked unsigned: their trust is the registry write ACL, so there is no signature evidence for the
+// image-evidence verifier to check, and nothing here constructs the verifier or reads the data root's evidence-trust pin
+// (which records the verifier build). The edition therefore records `not-armed`, the descriptor state that says no
+// evidence was signature-verified; `resolve` says why once on stderr, and `check-existing` holds a pulled artifact to
+// the same state. The pinned verifier is the official lane's (evidence-trust-policy.mjs), never read here.
+
+import { EvidenceTrustState } from './edition-constants.mjs';
+
+/** What a channel-resolved develop edition says, once, in place of loading the evidence verifier. */
+export const CHANNEL_EVIDENCE_NOTICE =
+  'develop channel: image evidence is the registry write ACL (images are baked unsigned); the evidence verifier and its pin are not loaded';
+
+/** The evidence trust state every vendor develop edition records. */
+export const DEVELOP_CHANNEL_EVIDENCE_TRUST = EvidenceTrustState.NotArmed;
+
+/** The state a vendor develop resolve records, with its notice on `log`. */
+export function developResolveEvidenceTrust({ log = console.error } = {}) {
+  log(CHANNEL_EVIDENCE_NOTICE);
+  return DEVELOP_CHANNEL_EVIDENCE_TRUST;
+}