@xemahq/xema 0.58.0 → 0.59.1

package/edition/develop-follow.mjs

@@ -0,0 +1,491 @@
+// develop-follow — the body of `xema edition develop follow`: the pins a dev deployment's follow policy selects.
+//
+// A dev deployment follows a reviewed distribution DEFINITION at its develop head: `--definition-at
+// <owner>/<repo>,<path>,<dataRoot>` names the repository, the distribution directory and the data root inside it,
+// each repository-relative. `follow` writes the COMPLETE frozen pin set a `develop resolve` reads, once (wx), and reads
+// no edition and no catalogue. It reuses, and never restates, two existing rules:
+//
+//   members   every develop-graph member at the newest commit of its signed build records (select-records'
+//             selectRecords / newestCommitOnDevelop), with the pins of the CURRENT input (--current-pins) as the
+//             published pins: a member whose records are not ahead of its current pin keeps it, one whose records
+//             diverged from it is refused by name (DivergedFromPublishedError).
+//   tooling   the data and kernel pins and the editions root keep freeze-graph's rules unchanged (freezeGraph):
+//             each checked-out root is pinned at what is checked out, and the kernel commit must declare an edition
+//             protocol this CLI supports; the deploy pin is chosen as below. The members enter freezeGraph as its
+//             member pins (freeze-graph --member-pins: a member that keeps its current resolution is pinned at its
+//             develop head, never selected). From current pins, each root is then classified against its current pin by ancestry in the root's OWN
+//             checkout (classifyToolingRoot): equal is kept, a descendant advanced, an ancestor refused
+//             (ToolingRootBehindError), an unrelated commit refused (ToolingRootDivergedError), and a current pin the
+//             checkout does not hold refused (ToolingRootHistoryMissingError: never fetched, never guessed; the follow
+//             job checks the roots out with full history). A first follow has nothing to classify against and says so.
+//   deploy    --deploy-sha is an UPPER BOUND, never the pin (the engine publishes on workflow_run after the deploy
+//             root's CI, so the head can be ahead of its engine): the pin is the newest first-parent commit of the deploy
+//             checkout at or below it whose engine `<--engine-repository>:sha-<12 hex>` the registry already serves.
+//             An unpublished commit is skipped; none published within ENGINE_WALK_LIMIT commits is refused by name
+//             (NoPublishedEngineError); any registry answer but 404 is operational, never a skip. The walk is
+//             deterministic: the same checkout and registry choose the same commit. The summary names it and the
+//             skip count. A walk that ends short of the limit at a shallow boundary or an absent parent is refused
+//             (ToolingRootHistoryMissingError), never read as "no engine published". The chosen commit is then classified against the current deploy pin like every tooling
+//             root, so a walk that lands behind it is refused (ToolingRootBehindError). Only existence is judged
+//             here; the engine's signature stays the apply's check.
+//   sources   every source the definition's chain declares, at its develop head (freezeSources), then newer-wins
+//             against its current pin by the same ancestry rule (newestCommitOnDevelop; a head equal to the pin
+//             fetches nothing); a diverged source is refused by name, and a current pin absent from the develop
+//             history of the source's declared URL is refused as a URL change (FollowSourceUrlChangedError).
+//
+//   seals     the previous seals the resolve carries generations forward from, frozen so a retry reads no "newest":
+//             the OFFERING's newest signed develop edition, read ONCE here from its edition repository through
+//             previous-seal-registry.mjs (--previous-seal-signer, verified offline with the pinned cosign), its
+//             images.lock bytes and sha256; and the CUSTOMER edition's own previous seal, a follow input passed through
+//             (--previous-lock <file> --previous-lock-sha256 <hex>, held to its sha256, or --first-seal). They are
+//             written once into --seals-out: offering.images.lock.json, customer.images.lock.json (absent on a first
+//             seal) and seals.json naming each file and its sha256 (followSealsDocument). The catalogue-free resolve
+//             takes the offering's as --offering-previous-lock and the customer's as --previous-lock.
+//
+// The data root checkout IS the definition's repository, held for consistency with the caller's checkout (the
+// declared repository URL is read from a file inside that checkout, so this is no trust boundary): the data root
+// declares the definition's repository, the checkout is clean (untracked files included) at --data-sha, the data root
+// and the distribution directory are the definition's dataRoot and path, and the editions root is that same
+// repository (there is no --editions-root-url). The kernel checkout is at --kernel-sha. A follow starts from exactly
+// one of `--first` (a FIRST follow, and the summary it prints says so) or `--current-pins <file>`.
+
+import { execFileSync, spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, realpathSync, writeFileSync } from 'node:fs';
+import { basename, join, normalize, relative } from 'node:path';
+
+import { canonicalPublicHttpsRepositoryUrl } from './canonical-repository-url.mjs';
+import { headResolver, writeOnce } from './customer-edition-verbs.mjs';
+import { DEFINITION_AT_FLAG } from './customer-flags.mjs';
+import { engineTagOf } from './develop-engine-image.mjs';
+import { freezeGraph, freezeSources } from './develop-freeze.mjs';
+import { developGraphMembers } from './develop-graph.mjs';
+import { PUBLISHED_PIN_TAG, RecordCommitNotOnDevelopError, newestCommitOnDevelop } from './develop-record-ancestry.mjs';
+import { declaredDataRootRepositoryUrl, withRecordVerifier } from './develop-record-verify.mjs';
+import { selectRecords } from './develop-select-records.mjs';
+import { assertCommitPins } from './develop-selection-pins.mjs';
+import { VERIFY_IMAGE_RECORD_BRANCH as DEVELOP_RECORD_BRANCH } from './develop-verify-image-record.mjs';
+import { assertCanonicalDistributionId } from './distribution-paths.mjs';
+import { editionRepository } from './edition-artifact.mjs';
+import { editionWorkspaceConfig } from './edition-config.mjs';
+import { EditionChannel } from './edition-constants.mjs';
+import { dataRoot, deployRoot, editionsRoot, kernelRepoDir } from './edition-workspace.mjs';
+import { assertKernelCommitSupported } from './kernel-protocol-choice.mjs';
+import { compareStrings, loadKernelDistributionSchemas, serializeJson } from './lib.mjs';
+import { SnapshotPinNamespace, dataPinKey, deployPinKey, kernelPinKey, snapshotPinNamespace, snapshotPinSource, sortedSnapshotPins } from './pin-source.mjs';
+import { PREVIOUS_SEAL_SIGNER_FLAG, previousSealFromRegistry } from './previous-seal-registry.mjs';
+import { splitImageRef } from './registry-credentials.mjs';
+import { composeEdition } from './resolve-distribution.mjs';
+import { readPreviousLockBytes } from './resolve-images.mjs';
+import { isNotPublishedYet } from './seal-image-digests.mjs';
+import { readStrictJsonFile } from './strict-json.mjs';
+
+const REPOSITORY_PATTERN = /^[A-Za-z0-9][A-Za-z0-9-]*\/[A-Za-z0-9._-]+$/;
+const RELATIVE_SEGMENT = /^[A-Za-z0-9._-]+$/;
+const SHA_PATTERN = /^[0-9a-f]{40}$/;
+// A repository, never a tag or a digest: `<registry>[:port]/<path>`.
+const ENGINE_REPOSITORY_PATTERN = /^[a-z0-9.-]+(:[0-9]+)?(\/[a-z0-9._-]+)+$/;
+
+/** How many first-parent commits of the deploy checkout, the upper bound included, the engine walk reads. */
+export const ENGINE_WALK_LIMIT = 50;
+
+/** No commit at or below the upper bound has a published engine within the walk. */
+export class NoPublishedEngineError extends Error {
+  constructor({ upperBound, engineRepository, walked }) {
+    super(`no deploy-root commit at or below --deploy-sha ${upperBound} has a published engine in ${engineRepository} within ${walked} first-parent commit(s) (limit ${ENGINE_WALK_LIMIT}): publish the engine for a develop commit (the deploy root's CI) and follow again`);
+    this.name = 'NoPublishedEngineError';
+  }
+}
+
+/**
+ * The newest commit of `commits` (first-parent order, newest first, the upper bound first) whose engine tag the
+ * registry serves: `{ deploySha, upperBound, skipped }`. A 404 skips the commit; any other failure throws.
+ */
+export async function selectPublishedEngineCommit({ commits, upperBound, engineRepository, client }) {
+  if (commits[0] !== upperBound) {
+    throw new Error(`the deploy walk starts at ${commits[0] ?? 'nothing'}, not at --deploy-sha ${upperBound}`);
+  }
+  for (const [skipped, commit] of commits.slice(0, ENGINE_WALK_LIMIT).entries()) {
+    try {
+      await client.getManifestByTag(engineRepository, engineTagOf(commit));
+      return { deploySha: commit, upperBound, skipped };
+    } catch (error) {
+      if (!isNotPublishedYet(error)) {
+        throw new Error(`follow: the registry did not answer for the engine ${engineRepository}:${engineTagOf(commit)}: ${error.message}`);
+      }
+    }
+  }
+  throw new NoPublishedEngineError({ upperBound, engineRepository, walked: Math.min(commits.length, ENGINE_WALK_LIMIT) });
+}
+
+/**
+ * The first-parent commits of the deploy checkout from `upperBound` back, newest first, at most the walk limit, read
+ * from the local object store only (never a lazy fetch). A walk that ends short of the limit must end at the root
+ * commit: a shallow checkout, or a commit of the walk whose object is absent (an absent --deploy-sha or an absent first
+ * parent, where git refuses the walk), is ToolingRootHistoryMissingError, never a short walk read as "no engine
+ * published".
+ */
+export function deployCommitsAtOrBelow(upperBound, git = runLocalGitText) {
+  if (!SHA_PATTERN.test(upperBound ?? '')) {throw new Error(`--deploy-sha is not a 40-hex commit SHA: ${JSON.stringify(upperBound)}`);}
+  const dir = deployRoot();
+  let listed;
+  try {
+    listed = git(['rev-list', '--first-parent', `--max-count=${ENGINE_WALK_LIMIT}`, upperBound], dir);
+  } catch (error) {
+    throw absentCommitOfWalk(upperBound, dir, git) ?? error;
+  }
+  const commits = listed.split('\n').filter(Boolean);
+  if (commits.length < ENGINE_WALK_LIMIT && git(['rev-parse', '--is-shallow-repository'], dir) === 'true') {
+    throw new ToolingRootHistoryMissingError(deployPinKey(), commits.at(-1) ?? upperBound, dir, 'history below the shallow boundary');
+  }
+  return commits;
+}
+
+/** The ToolingRootHistoryMissingError for the first commit of the first-parent walk from `upperBound` the checkout does not hold, or undefined. */
+function absentCommitOfWalk(upperBound, dir, git) {
+  const holds = (commit) => {
+    try {
+      git(['cat-file', '-e', `${commit}^{commit}`], dir);
+      return true;
+    } catch {
+      return false;
+    }
+  };
+  let commit = upperBound;
+  for (let walked = 0; walked < ENGINE_WALK_LIMIT; walked += 1) {
+    if (!holds(commit)) {
+      return new ToolingRootHistoryMissingError(deployPinKey(), commit, dir, walked === 0 ? '--deploy-sha' : 'first parent of the walk\'s last commit');
+    }
+    // the commit object's own header: rev-list would need the parent object to name it
+    const firstParent = /^parent ([0-9a-f]{40})$/m.exec(git(['cat-file', 'commit', commit], dir).split('\n\n')[0])?.[1];
+    if (firstParent === undefined) {return undefined;}
+    commit = firstParent;
+  }
+  return undefined;
+}
+
+/** How a follow started: from no input (first) or from the pins of the current input. */
+export const FollowStart = Object.freeze({ First: 'first', FromCurrent: 'from-current' });
+
+/** The flag naming the followed definition triple (freeze-sources' and resolve's `--definition` is a file). */
+export const FOLLOW_DEFINITION_FLAG = DEFINITION_AT_FLAG;
+
+/** 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`: follow's --definition-at, or the catalogue-free resolve's --offering) -> `{ repository, path, dataRoot }`. */
+export function parseFollowDefinition(text, flag = FOLLOW_DEFINITION_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;
+}
+
+/** The `--current-pins` file (a follow's own output, a bare pin map): key -> 40-hex commit, every key in a snapshot pin namespace. */
+export function readCurrentPins(path) {
+  const pins = readStrictJsonFile(path);
+  if (pins === null || typeof pins !== 'object' || Array.isArray(pins)) {
+    throw new Error(`--current-pins ${path} must be an object mapping pin key -> 40-hex commit`);
+  }
+  for (const key of Object.keys(pins)) {snapshotPinNamespace(key);}
+  return assertCommitPins(pins, `--current-pins ${path}`);
+}
+
+const runGitText = (args, cwd) => execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+/** runGitText that never lazily fetches a missing object (a partial clone answers from what it holds). */
+const runLocalGitText = (args, cwd) => execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], env: { ...process.env, GIT_NO_LAZY_FETCH: '1' } }).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 --data-sha, 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, git = runGitText, flag = FOLLOW_DEFINITION_FLAG, shaLabel = '--data-sha' }) {
+  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;
+}
+
+/** How a tooling root's followed commit stands against its current pin. */
+export const ToolingRootVerdict = Object.freeze({ Kept: 'kept', Advanced: 'advanced', Added: 'added' });
+
+/** The followed commit of a tooling root is an ancestor of its current pin: the follow would take it backwards. */
+export class ToolingRootBehindError extends Error {
+  constructor(key, followed, current) {
+    super(`${key}: the followed commit ${followed} is behind the current pin ${current} (an ancestor of it): a follow never takes a tooling root backwards; check out the current commit or a descendant`);
+    this.name = 'ToolingRootBehindError';
+  }
+}
+
+/** The followed commit of a tooling root and its current pin are not ancestor-related. */
+export class ToolingRootDivergedError extends Error {
+  constructor(key, followed, current) {
+    super(`${key}: the followed commit ${followed} and the current pin ${current} are not ancestor-related`);
+    this.name = 'ToolingRootDivergedError';
+  }
+}
+
+/** The root's checkout does not hold one of the two commits (`role`: the current pin or the followed commit), so they cannot be compared: refused, never fetched. */
+export class ToolingRootHistoryMissingError extends Error {
+  constructor(key, commit, dir, role) {
+    super(`${key}: the checkout ${dir} does not hold the ${role} ${commit}: check the root out with full history (fetch-depth 0) and follow again`);
+    this.role = role;
+    this.name = 'ToolingRootHistoryMissingError';
+  }
+}
+
+/** `{ status, stderr }` of one git run in `dir`, never lazily fetching a missing object. */
+const runGitStatus = (args, dir) => {
+  const result = spawnSync('git', args, { cwd: dir, env: { ...process.env, GIT_NO_LAZY_FETCH: '1' }, encoding: 'utf8' });
+  if (result.error !== undefined || result.status === null) {throw new Error(`git ${args[0]} could not run in ${dir}: ${result.error?.message ?? `killed by ${result.signal}`}`);}
+  return { status: result.status, stderr: result.stderr };
+};
+
+/**
+ * A tooling root's followed commit against its current pin, by ancestry in the root's own checkout `dir`: kept or
+ * advanced, otherwise a typed refusal. Equal commits answer without git.
+ */
+export function classifyToolingRoot({ key, dir, followed, current, git = runGitStatus }) {
+  if (followed === current) {return ToolingRootVerdict.Kept;}
+  for (const [role, commit] of [['current pin', current], ['followed commit', followed]]) {
+    if (git(['cat-file', '-e', `${commit}^{commit}`], dir).status !== 0) {throw new ToolingRootHistoryMissingError(key, commit, dir, role);}
+  }
+  // 0 = ancestor, 1 = not; anything else is git failing, never a verdict
+  const isAncestor = (older, newer) => {
+    const result = git(['merge-base', '--is-ancestor', older, newer], dir);
+    if (result.status === 0) {return true;}
+    if (result.status === 1) {return false;}
+    throw new Error(`follow: ${key}: git merge-base ${older} ${newer} failed in ${dir} (exit ${result.status}): ${result.stderr.trim()}`);
+  };
+  if (isAncestor(current, followed)) {return ToolingRootVerdict.Advanced;}
+  if (isAncestor(followed, current)) {throw new ToolingRootBehindError(key, followed, current);}
+  throw new ToolingRootDivergedError(key, followed, current);
+}
+
+/** A source's current pin is not in the develop history of its declared URL: the URL changed (or develop was rewritten). */
+export class FollowSourceUrlChangedError extends Error {
+  constructor(key, url, current) {
+    super(`follow: ${key}: the current pin ${current} is not in the develop history of the declared URL ${url}: the source's repository URL changed since the current input (or its develop was rewritten); a follow never carries a pin across a URL change, so follow with --first`);
+    this.name = 'FollowSourceUrlChangedError';
+  }
+}
+
+/**
+ * The newer of a source's develop head and its current pin, through the one ancestry rule. A head equal to the pin
+ * answers without a fetch; the pin missing from the URL's develop history is a URL change, never a record refusal.
+ */
+export function followSourceAncestry({ key, url, head, published, newest }) {
+  if (head === published) {return published;}
+  try {
+    return newest({ member: { repo: key, repositoryUrl: url }, candidates: [{ commit: head, tag: 'develop head' }], published, context: 'follow' }).commit;
+  } catch (error) {
+    if (error instanceof RecordCommitNotOnDevelopError && error.commit === published && error.tags.includes(PUBLISHED_PIN_TAG)) {
+      throw new FollowSourceUrlChangedError(key, url, published);
+    }
+    throw error;
+  }
+}
+
+/** The tooling root pin keys with the checkout each is classified in. */
+const toolingRoots = () => [
+  { key: dataPinKey(), dir: () => dataRoot() },
+  { key: kernelPinKey(), dir: () => kernelRepoDir() },
+  { key: deployPinKey(), dir: () => deployRoot() },
+];
+
+/** The kernel checkout is at --kernel-sha (consistency with the caller's checkout). */
+export function assertKernelCheckout({ kernelSha, git = runGitText }) {
+  const head = git(['rev-parse', 'HEAD'], kernelRepoDir());
+  if (head !== kernelSha) {throw new Error(`--kernel-sha is ${kernelSha}, but the kernel checkout ${kernelRepoDir()} is at ${head}`);}
+}
+
+/** Exactly one of `--first` and `--current-pins <file>`: the current pins, or undefined for a first follow. */
+export function followStartOf(options) {
+  const first = options['--first'] === true;
+  const current = options['--current-pins'];
+  if (first === (current !== undefined)) {
+    throw new Error('follow takes exactly one of --first (no current input) or --current-pins <file> (the pins of the current input)');
+  }
+  return first ? undefined : readCurrentPins(current);
+}
+
+/** What moved between the current pins and the followed ones, sorted. */
+function followSummary(currentPins, pins, tooling) {
+  if (currentPins === undefined) {return { follow: FollowStart.First, tooling: 'not classified: a first follow has no current pins', advanced: [], kept: [], added: Object.keys(pins), dropped: [] };}
+  const keys = (filter) => Object.keys(pins).filter(filter).sort(compareStrings);
+  return {
+    follow: FollowStart.FromCurrent,
+    tooling,
+    advanced: keys((key) => key in currentPins && currentPins[key] !== pins[key]),
+    kept: keys((key) => currentPins[key] === pins[key]),
+    added: keys((key) => !(key in currentPins)),
+    dropped: Object.keys(currentPins).filter((key) => !(key in pins)).sort(compareStrings),
+  };
+}
+
+/**
+ * The follow, over injected readers: `selectDeploy()` answers the deploy pin (selectPublishedEngineCommit), `select(publishedPins)` answers select-records' `{ pins }` for the graph members,
+ * `declaredSourcesAt(graphPins)` the sources the definition's chain declares at the graph pins (composeEdition, as
+ * freeze-sources reads them), `ancestry({ key, url, head, published })` the newer of a source's head and its current pin
+ * (or a refusal), `classifyRoot({ key, followed, current })` a tooling root against its current pin (or a refusal).
+ *
+ * @returns {Promise<{ pins: Record<string, string>, summary: object }>}
+ */
+export async function followDevelop({ dataSha, kernelSha, selectDeploy, currentPins, members, select, resolveHead, holdSource, declaredSourcesAt, ancestry, classifyRoot }) {
+  const graph = new Set(members.map((member) => member.repo));
+  const published = currentPins === undefined ? undefined : Object.fromEntries(Object.entries(currentPins).filter(([key]) => graph.has(key)));
+  const deploy = await selectDeploy();
+  const selection = await select(published);
+  // The members are freezeGraph's member pins (freeze-graph --member-pins): its tooling rules (checked-out roots, editions
+  // root) apply unchanged, and a member that keeps its current resolution is pinned at its develop head.
+  const graphPins = freezeGraph({ dataSha, kernelSha, deploySha: deploy.deploySha, memberPins: selection.pins, resolveHead, holdSource });
+  // From current pins, no tooling root goes backwards or sideways (a first follow has nothing to compare against).
+  const tooling = {};
+  if (currentPins !== undefined) {
+    for (const key of [dataPinKey(), kernelPinKey(), deployPinKey()].sort(compareStrings)) {
+      tooling[key] = currentPins[key] === undefined ? ToolingRootVerdict.Added : classifyRoot({ key, followed: graphPins[key], current: currentPins[key] });
+    }
+  }
+  const declaredSources = declaredSourcesAt(graphPins);
+  const headed = freezeSources({ pins: graphPins, declaredSources, resolveHead, holdSource });
+  const pins = { ...headed };
+  const urlOf = new Map(declaredSources.map((source) => [source.name, source.url]));
+  for (const [key, head] of Object.entries(headed)) {
+    if (snapshotPinNamespace(key) !== SnapshotPinNamespace.Source || currentPins?.[key] === undefined) {continue;}
+    pins[key] = ancestry({ key, url: urlOf.get(key.slice('sources/'.length)), head, published: currentPins[key] });
+  }
+  const sorted = sortedSnapshotPins(pins);
+  return { pins: sorted, summary: { ...followSummary(currentPins, sorted, tooling), deploy } };
+}
+
+/** The files of --seals-out. */
+export const FollowSealFile = Object.freeze({ Seals: 'seals.json', Offering: 'offering.images.lock.json', Customer: 'customer.images.lock.json' });
+
+/**
+ * The customer's own previous seal, a follow input passed through: exactly one of `--previous-lock <file>
+ * --previous-lock-sha256 <hex>` (the bytes, held to the sha256; the id is held to the customer edition's by the resolve,
+ * which knows it) or `--first-seal` (null).
+ */
+export function customerPreviousLockInput(options) {
+  const pair = [options['--previous-lock'], options['--previous-lock-sha256']];
+  const first = options['--first-seal'] === true;
+  if (first === pair.some((value) => value !== undefined) || (!first && pair.includes(undefined))) {
+    throw new Error('follow takes the customer edition\'s own previous seal as exactly one of --previous-lock <file> with --previous-lock-sha256 <hex>, or --first-seal');
+  }
+  return first ? null : { bytes: readPreviousLockBytes(pair[0], pair[1]), sha256: pair[1] };
+}
+
+/** seals.json: each frozen previous seal by file and sha256 (the customer's absent file is a first seal). */
+export function followSealsDocument({ offeringId, offering, customer }) {
+  return {
+    offering: { distributionId: offeringId, edition: offering.edition, previousLock: FollowSealFile.Offering, previousLockSha256: offering.imagesLockSha256 },
+    customer: customer === null ? { firstSeal: true } : { previousLock: FollowSealFile.Customer, previousLockSha256: customer.sha256 },
+  };
+}
+
+/** Writes --seals-out once: a new directory holding the frozen previous-seal bytes and seals.json. */
+export function writeFollowSeals(dir, { offeringId, offering, customer }) {
+  mkdirSync(dir);
+  writeFileSync(join(dir, FollowSealFile.Offering), offering.bytes, { flag: 'wx' });
+  if (customer !== null) {writeFileSync(join(dir, FollowSealFile.Customer), customer.bytes, { flag: 'wx' });}
+  writeFileSync(join(dir, FollowSealFile.Seals), serializeJson(followSealsDocument({ offeringId, offering, customer })), { flag: 'wx' });
+}
+
+/** The `follow` verb: writes `--out` and `--seals-out` once and prints the summary (it states a first follow). */
+export async function runFollow({
+  options,
+  env = process.env,
+  members = developGraphMembers(),
+  runGit,
+  git,
+  rootGit,
+  deployCommits = deployCommitsAtOrBelow,
+  heads,
+  assertKernel = assertKernelCommitSupported,
+  findOfferingSeal = ({ repository, signerIdentity }) => previousSealFromRegistry({ repository, signerIdentity, cosignBinary: options['--cosign'], env }),
+  write = writeOnce,
+  print = (line) => console.log(line),
+  ...verifierInjections
+}) {
+  const currentPins = followStartOf(options);
+  const customerSeal = customerPreviousLockInput(options);
+  if (existsSync(options['--seals-out'])) {throw new Error(`--seals-out ${options['--seals-out']} already exists: follow writes it once`);}
+  const definition = parseFollowDefinition(options[FOLLOW_DEFINITION_FLAG]);
+  if (!ENGINE_REPOSITORY_PATTERN.test(options['--engine-repository'] ?? '')) {
+    throw new Error(`--engine-repository is <registry>/<path> of the deploy engine, with no tag or digest; got ${JSON.stringify(options['--engine-repository'])}`);
+  }
+  const id = assertDefinitionCheckout({ definition, dataSha: options['--data-sha'], ...(git === undefined ? {} : { git }) });
+  assertKernelCheckout({ kernelSha: options['--kernel-sha'], ...(git === undefined ? {} : { git }) });
+  assertKernel({ repoDir: kernelRepoDir(), commit: options['--kernel-sha'], label: `--kernel-sha ${options['--kernel-sha']}` });
+  const workspace = editionWorkspaceConfig();
+  const { parseDistribution } = await loadKernelDistributionSchemas();
+  const { pins, summary } = await withRecordVerifier({ cosignBinary: options['--cosign'], env, ...verifierInjections }, (verifier) =>
+    followDevelop({
+      dataSha: options['--data-sha'],
+      kernelSha: options['--kernel-sha'],
+      selectDeploy: () => {
+        const engineRepository = options['--engine-repository'];
+        return selectPublishedEngineCommit({
+          commits: deployCommits(options['--deploy-sha']),
+          upperBound: options['--deploy-sha'],
+          engineRepository,
+          client: verifier.clientFor(splitImageRef(engineRepository).authority),
+        });
+      },
+      currentPins,
+      members,
+      select: (publishedPins) =>
+        selectRecords({ branch: DEVELOP_RECORD_BRANCH, registry: options['--registry'], members, ...verifier, publishedPins, workspace, env, runGit }),
+      ...(heads ?? headResolver(EditionChannel.Develop, env)),
+      declaredSourcesAt: (graphPins) => composeEdition(parseDistribution, id, snapshotPinSource(graphPins)).declaredSources,
+      ancestry: ({ key, url, head, published }) =>
+        followSourceAncestry({ key, url, head, published, newest: (request) => newestCommitOnDevelop({ ...request, workspace, env, ...(runGit === undefined ? {} : { runGit }) }) }),
+      classifyRoot: ({ key, followed, current }) =>
+        classifyToolingRoot({ key, dir: toolingRoots().find((root) => root.key === key).dir(), followed, current, ...(rootGit === undefined ? {} : { git: rootGit }) }),
+    }),
+  );
+  // The offering's newest signed develop edition, read once: the only "newest" a dev resolve depends on.
+  const offeringSeal = await findOfferingSeal({ repository: editionRepository(id, options['--registry'], EditionChannel.Develop), signerIdentity: options[PREVIOUS_SEAL_SIGNER_FLAG] });
+  write(options['--out'], pins);
+  writeFollowSeals(options['--seals-out'], { offeringId: id, offering: offeringSeal, customer: customerSeal });
+  const seals = followSealsDocument({ offeringId: id, offering: offeringSeal, customer: customerSeal });
+  print(JSON.stringify({ distributionId: id, definition, ...summary, seals }));
+  return { pins, summary, seals };
+}

package/edition/develop-record-ancestry.mjs

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

package/edition/develop-selection-pins.mjs

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

package/edition/distribution-evidence-set.mjs

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