@xemahq/xema 0.59.1 → 0.60.1

package/edition/develop-follow.mjs

@@ -1,491 +0,0 @@
-// 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 };
-}