@xemahq/xema 0.26.0 → 0.27.0

package/edition/pin-source.mjs

@@ -0,0 +1,227 @@
+// pin-source — where the resolver reads each first-party repository's commit.
+//
+// PUBLISHED (the default, and the only behaviour before this module): the
+// committed `runtime-image-source-index.json#repositoryPins`, untouched.
+//
+// SNAPSHOT: one frozen map of pins, replacing the published ones for ONE
+// in-memory resolution (the develop pipeline resolves a whole edition from it).
+// Nothing is written back to the index, and there is NO fallback: a repo in the
+// graph that the snapshot does not name is refused, never read from the
+// published pin. This module owns the SHAPE of that map: a flat object whose
+// keys live in six closed namespaces and whose values are exact 40-hex SHAs.
+//
+//   repos/<x> | submodules/<x>        every `repositoryPins[].repo` of the runtime
+//                                     image source index (the graph), no more, no fewer
+//   <pinRoles.data>                   the commit of the data root checkout (editions and indices)
+//   <pinRoles.kernel>                 the commit of the kernel the authorization lock is sealed
+//                                     with (may match repos/<x>, but is NOT in the graph)
+//   <pinRoles.deploy>                 the commit of the chart tree the chart-set lock digests
+//   editions-root                     the commit of the editions root checkout; present
+//                                     only when that root is NOT this repository
+//   sources/<name>                    one per `sources[]` entry declared in the chain
+
+import { workspaceSection } from './edition-config.mjs';
+import { compareStrings, serializeJson, sha256Hex } from './lib.mjs';
+import { PinRole } from './workspace-sections.mjs';
+
+export const PinSourceKind = Object.freeze({
+  Published: 'published',
+  Snapshot: 'snapshot',
+});
+
+const SHA_PATTERN = /^[0-9a-f]{40}$/;
+
+export const SnapshotPinNamespace = Object.freeze({
+  Graph: 'graph',
+  Distributions: 'distributions',
+  Kernel: 'kernel',
+  ChartSource: 'chart-source',
+  EditionsRoot: 'editions-root',
+  Source: 'source',
+});
+
+// The three checked-out roles a snapshot pins (data, kernel, deploy) are a closed
+// set the library defines; the repository key each is pinned under is the data
+// root's (`pinRoles` in edition-workspace.json), so a repository rename never
+// needs a library release. `editions-root` is not a repository key but a
+// protocol key of its own.
+export const EDITIONS_ROOT_PIN_KEY = 'editions-root';
+
+const pinKeyOf = (role) => workspaceSection('pinRoles', 'a snapshot pin')[role];
+
+export const dataPinKey = () => pinKeyOf(PinRole.Data);
+export const kernelPinKey = () => pinKeyOf(PinRole.Kernel);
+export const deployPinKey = () => pinKeyOf(PinRole.Deploy);
+const SOURCE_PIN_PREFIX = 'sources/';
+const GRAPH_PIN_PATTERN = /^(?:repos|submodules)\/[a-z0-9][a-z0-9-]*$/;
+
+/** The snapshot key of one declared `sources[]` entry. */
+export function sourcePinKey(name) {
+  return `${SOURCE_PIN_PREFIX}${name}`;
+}
+
+/** The `sources[].name` a Source-namespace key pins. */
+export function sourceNameOfPinKey(key) {
+  return key.slice(SOURCE_PIN_PREFIX.length);
+}
+
+/** Which closed namespace a snapshot key belongs to; refuses a key in none. */
+export function snapshotPinNamespace(key) {
+  if (key === dataPinKey()) {return SnapshotPinNamespace.Distributions;}
+  if (key === kernelPinKey()) {return SnapshotPinNamespace.Kernel;}
+  if (key === deployPinKey()) {return SnapshotPinNamespace.ChartSource;}
+  if (key === EDITIONS_ROOT_PIN_KEY) {return SnapshotPinNamespace.EditionsRoot;}
+  if (key.startsWith(SOURCE_PIN_PREFIX) && key.length > SOURCE_PIN_PREFIX.length) {
+    return SnapshotPinNamespace.Source;
+  }
+  if (GRAPH_PIN_PATTERN.test(key)) {return SnapshotPinNamespace.Graph;}
+  throw new Error(
+    `snapshot pin key "${key}" is in no namespace; expected a graph repository (repos/<x> or ` +
+      `submodules/<x>), "${dataPinKey()}", "${kernelPinKey()}", "${deployPinKey()}", "${EDITIONS_ROOT_PIN_KEY}" or "${SOURCE_PIN_PREFIX}<name>"`,
+  );
+}
+
+function assertPinsObject(pins) {
+  if (pins === null || typeof pins !== 'object' || Array.isArray(pins)) {
+    throw new Error('snapshot pins must be an object mapping key -> 40-hex commit');
+  }
+}
+
+function assertExactShas(pins) {
+  for (const [key, sha] of Object.entries(pins)) {
+    if (typeof sha !== 'string' || !SHA_PATTERN.test(sha)) {
+      throw new Error(
+        `snapshot pin for "${key}" is not a 40-hex commit SHA: ${JSON.stringify(sha)}`,
+      );
+    }
+  }
+}
+
+function graphPinsOf(pins) {
+  return Object.fromEntries(
+    Object.entries(pins).filter(([key]) => snapshotPinNamespace(key) === SnapshotPinNamespace.Graph),
+  );
+}
+
+/**
+ * Validate a COMPLETE snapshot against the graph and the composed chain.
+ * `declaredSourceNames` are the `sources[].name` entries the chain declares;
+ * `editionsRootExternal` is whether the editions root is another repository.
+ * Every refusal names the offending key; nothing falls back to a published pin.
+ */
+export function validateSnapshotPins(
+  pins,
+  { runtimeSourceIndex, declaredSourceNames, editionsRootExternal },
+) {
+  assertPinsObject(pins);
+  assertExactShas(pins);
+  for (const key of Object.keys(pins)) {snapshotPinNamespace(key);}
+  checkGraphPins(runtimeSourceIndex.repositoryPins, pins);
+  for (const [key, what] of [
+    [dataPinKey(), 'the commit of the data root checkout'],
+    [kernelPinKey(), 'the commit of the kernel the authorization lock is sealed with'],
+    [deployPinKey(), 'the commit of the chart tree the chart-set lock digests'],
+  ]) {
+    if (!(key in pins)) {throw new Error(`snapshot is missing "${key}", ${what}`);}
+  }
+  if (editionsRootExternal && !(EDITIONS_ROOT_PIN_KEY in pins)) {
+    throw new Error(`snapshot is missing "${EDITIONS_ROOT_PIN_KEY}": the editions root is not this repository`);
+  }
+  if (!editionsRootExternal && EDITIONS_ROOT_PIN_KEY in pins) {
+    throw new Error(`snapshot names "${EDITIONS_ROOT_PIN_KEY}", but the editions root is this repository`);
+  }
+  const declared = new Set(declaredSourceNames);
+  for (const name of declared) {
+    if (!(sourcePinKey(name) in pins)) {
+      throw new Error(`snapshot is missing "${sourcePinKey(name)}": the chain declares source "${name}"`);
+    }
+  }
+  for (const key of Object.keys(pins)) {
+    if (snapshotPinNamespace(key) === SnapshotPinNamespace.Source && !declared.has(sourceNameOfPinKey(key))) {
+      throw new Error(`snapshot names "${key}", but the chain declares no source "${sourceNameOfPinKey(key)}"`);
+    }
+  }
+}
+
+/** The pins sorted by key: the one canonical order, shared by the hash and the artifact. */
+export function sortedSnapshotPins(pins) {
+  assertPinsObject(pins);
+  return Object.fromEntries(Object.entries(pins).sort(([a], [b]) => compareStrings(a, b)));
+}
+
+/** sha256 hex of the canonical JSON of the pins sorted by key: the snapshot's identity. */
+export function snapshotHash(pins) {
+  return sha256Hex(serializeJson(sortedSnapshotPins(pins)));
+}
+
+/** A declared source with its ref replaced by the snapshot pin; identity under a published pin source. */
+export function pinnedSource(source, pinSource = PUBLISHED_PIN_SOURCE) {
+  if (pinSource?.kind !== PinSourceKind.Snapshot) {return source;}
+  const key = sourcePinKey(source.name);
+  const ref = pinSource.pins[key];
+  if (ref === undefined) {
+    throw new Error(`snapshot has no pin "${key}" for the declared source "${source.name}"; there is no fallback to its declared ref`);
+  }
+  return { ...source, ref };
+}
+
+export const PUBLISHED_PIN_SOURCE = Object.freeze({ kind: PinSourceKind.Published });
+
+/** @param {Record<string,string>} pins repo -> 40-hex commit */
+export function snapshotPinSource(pins) {
+  return Object.freeze({ kind: PinSourceKind.Snapshot, pins });
+}
+
+/**
+ * Apply a pin source to a parsed runtime image source index. Published returns
+ * the SAME object (inert, byte for byte). Snapshot returns a copy whose
+ * `repositoryPins` carry the snapshot SHAs.
+ */
+export function applyPinSource(runtimeSourceIndex, pinSource = PUBLISHED_PIN_SOURCE) {
+  switch (pinSource?.kind) {
+    case PinSourceKind.Published:
+      return runtimeSourceIndex;
+    case PinSourceKind.Snapshot:
+      return applySnapshot(runtimeSourceIndex, pinSource.pins);
+    default:
+      throw new Error(
+        `unknown pin source kind ${JSON.stringify(pinSource?.kind)}; expected ` +
+          `${Object.values(PinSourceKind).join(' | ')}`,
+      );
+  }
+}
+
+function checkGraphPins(graph, pins) {
+  const graphRepos = new Set(graph.map((pin) => pin.repo));
+  for (const repo of Object.keys(graphPinsOf(pins))) {
+    if (!graphRepos.has(repo)) {
+      throw new Error(`snapshot names "${repo}", which is not a repository in the graph`);
+    }
+  }
+  const missing = [...graphRepos].filter((repo) => !(repo in pins));
+  if (missing.length > 0) {
+    throw new Error(
+      `snapshot is missing ${missing.length} repositor${missing.length === 1 ? 'y' : 'ies'} ` +
+        `in the graph: ${missing.join(', ')}. There is no fallback to the published pin.`,
+    );
+  }
+}
+
+function applySnapshot(runtimeSourceIndex, pins) {
+  assertPinsObject(pins);
+  assertExactShas(pins);
+  for (const key of Object.keys(pins)) {snapshotPinNamespace(key);}
+  const graph = runtimeSourceIndex.repositoryPins;
+  checkGraphPins(graph, pins);
+  return {
+    ...runtimeSourceIndex,
+    repositoryPins: graph.map((pin) => ({
+      ...pin,
+      // The IMAGE axis only. `vendoredSourceCommit` is the SOURCE axis (the
+      // published tip vendored bytes come from) and is deliberately NOT fused
+      // with it: see `build-runtime-image-source-index.mjs#repositoryIdentity`
+      // for the measured production failure that fusing the two caused.
+      sourceCommit: pins[pin.repo],
+    })),
+  };
+}

package/edition/plan-image-evidence-refresh.mjs

@@ -0,0 +1,408 @@
+#!/usr/bin/env node
+// ═══════════════════════════════════════════════════════════════════════════
+// WHICH PRODUCING REPOSITORIES MUST RE-SIGN BEFORE THE NEXT RELEASE?
+//
+//   xema edition evidence plan-refresh \
+//     --data-root <dir> --editions-root <dir> --kernel <dir> \
+//     [--kernel-checkout exact|preview] \
+//     --distribution <id> [repeatable] \
+//     [--horizon-seconds <n>] [--now <epoch-millis>] [--github-output <path>]
+//
+// Producer evidence is read from ONE place: the OCI referrers of each locked
+// image, in the registry the lock names.
+//
+// `--kernel-checkout exact` (the default) loads the kernel schemas from a clean
+// kernel checkout at exactly the commit the data root's evidence-trust pin
+// records. `preview` loads whatever kernel is built at `--kernel`: that build
+// is held to no commit, so its plan is a LOCAL PREVIEW. It says so on every
+// run and cannot write `--github-output`, so no workflow can act on it.
+//
+// WHY THIS EXISTS
+//
+//   Producer evidence carries a hard `expiresAt` that the offline verifier
+//   enforces. Nothing was watching it. Evidence was produced only as a
+//   side-effect of an image BUILD (or a manual dispatch), so a subject whose
+//   source has not changed in a week has evidence that quietly ages out — and
+//   the failure surfaces at the worst possible moment: at a customer install, or
+//   as a release that cannot be delivered, with a green CI behind it.
+//
+//   This is the standing question asked on a schedule instead: for every subject
+//   of every named edition, is there a published producer bundle, is it usable,
+//   and does it still have enough life to survive the release that will consume
+//   it? Anything else is a refresh that is DUE, reported per producing
+//   repository so the owner of that repository can act on one line.
+//
+// EXIT CODES — the distinction is deliberate
+//
+//   0  every subject is CURRENT.
+//   2  a verdict was reached and a refresh IS due. This is the loud failure the
+//      scheduled workflow exists to produce.
+//   1  NO verdict could be reached (bad arguments, unreadable locks, a lock and
+//      the runtime index disagreeing about a repository pin). A planner that
+//      cannot decide must never report "nothing to do".
+//
+// THE HORIZON IS THE REUSE FLOOR
+//
+//   The default horizon is `MIN_REMAINING_TTL_SECONDS`, the same floor
+//   `check-committed-image-evidence.mjs` uses to decide a committed bundle is
+//   too close to expiry to hand forward. One number, one meaning: below it, the
+//   bundle is not something a release should be built on.
+// ═══════════════════════════════════════════════════════════════════════════
+
+import { appendFileSync } from 'node:fs';
+import { isAbsolute } from 'node:path';
+
+import { MIN_REMAINING_TTL_SECONDS } from './check-committed-image-evidence.mjs';
+import {
+  expectedProducerSource,
+  parseEvidenceCliFlags,
+} from './distribution-evidence-set.mjs';
+import {
+  WorkspaceRoot,
+  configureEditionWorkspaceFromArgv,
+  dataRoot,
+  editionsRoot,
+  isEntryModule,
+} from './edition-workspace.mjs';
+import {
+  canonicalJson,
+  loadValidatedLocks,
+} from './image-evidence.mjs';
+import { assertKernelContractAuthorityEqual } from './kernel-contract-authority.mjs';
+import { compareStrings, loadKernelDistributionSchemas } from './lib.mjs';
+import {
+  createRegistryClientResolver,
+  resolveImageSourceEvidenceReferrer,
+} from './oci-image-source-evidence.mjs';
+import {
+  loadProducerKernelSchemas,
+  readPinnedContractAuthority,
+} from './produce-image-source-evidence.mjs';
+import { splitImageRef } from './registry-credentials.mjs';
+
+/** Closed set of per-subject refresh verdicts. */
+export const EvidenceRefreshStatus = Object.freeze({
+  Current: 'CURRENT',
+  Absent: 'ABSENT',
+  Unusable: 'UNUSABLE',
+  Expired: 'EXPIRED',
+  Expiring: 'EXPIRING',
+});
+
+/** Where the kernel schemas of a planning run come from. */
+export const KernelCheckout = Object.freeze({
+  /** A clean kernel checkout at exactly the pinned authority commit. */
+  Exact: 'exact',
+  /** The kernel built at `--kernel`, held to no commit: a local preview only. */
+  Preview: 'preview',
+});
+
+const DUE_STATUSES = Object.freeze(
+  new Set([
+    EvidenceRefreshStatus.Absent,
+    EvidenceRefreshStatus.Unusable,
+    EvidenceRefreshStatus.Expired,
+    EvidenceRefreshStatus.Expiring,
+  ]),
+);
+
+/**
+ * @returns {Promise<{horizonSeconds: number, refreshDue: boolean,
+ *   subjects: Array<object>, groups: Array<object>}>}
+ */
+export async function planImageEvidenceRefresh({
+  distributionIds,
+  dataRoot: dataRootDirectory,
+  editionsRoot: editionsRootDirectory,
+  schemas,
+  expectedContractAuthority,
+  registryClientFactory,
+  horizonSeconds = MIN_REMAINING_TTL_SECONDS,
+  now = Date.now(),
+}) {
+  if (!Array.isArray(distributionIds) || distributionIds.length === 0) {
+    throw new Error('at least one distribution id is required');
+  }
+  if (!expectedContractAuthority) {
+    throw new Error('the expected kernel contract authority is required');
+  }
+  if (!isAbsolute(dataRootDirectory) || !isAbsolute(editionsRootDirectory)) {
+    throw new Error('the data root and the editions root must be absolute paths');
+  }
+  if (!Number.isSafeInteger(horizonSeconds) || horizonSeconds <= 0) {
+    throw new Error('the refresh horizon must be a positive whole number of seconds');
+  }
+  if (!Number.isSafeInteger(now) || now <= 0) {
+    throw new Error('the evaluation instant must be positive epoch milliseconds');
+  }
+  const clientFor = createRegistryClientResolver({
+    dataRoot: dataRootDirectory,
+    factory: registryClientFactory,
+  });
+
+  const subjects = [];
+  for (const distributionId of [...distributionIds].sort(compareStrings)) {
+    const { imageLock, repositoryPins, runtimeSourceIndex } = await loadValidatedLocks(
+      distributionId,
+      dataRootDirectory,
+      schemas,
+      { editionsRoot: editionsRootDirectory },
+    );
+    assertKernelContractAuthorityEqual(
+      runtimeSourceIndex.contractAuthority,
+      expectedContractAuthority,
+      'runtime-image-source-index.json',
+    );
+    for (const subject of imageLock.subjects) {
+      const repositoryPin = repositoryPins.get(subject.repo);
+      const expectedSource = expectedProducerSource({
+        subject,
+        repositoryPin,
+        sourceHashAlgorithm: imageLock.sourceHashAlgorithm,
+      });
+      let matches = [];
+      // Set when the registry ANSWERS that the locked coordinate holds no
+      // image. That is a decided verdict for this subject, not an undecidable
+      // one, so it is reported rather than thrown — see the exit-code contract
+      // in this file's header. Until 2026-09-02 the throw escaped the whole
+      // planner: measured that day, ALL 68 locked coordinates were absent from
+      // ghcr, and the run died on the first of them and said nothing about the
+      // other 67.
+      let coordinateAbsence = null;
+      {
+        const { authority, repository } = splitImageRef(subject.imageRef);
+        const client = clientFor(authority);
+        let image = null;
+        try {
+          image = await client.getManifestByTag(repository, subject.contentHash);
+        } catch (error) {
+          // A registry that says "no such manifest" has decided this subject.
+          // Any other failure means the question went UNANSWERED, and a planner
+          // that cannot decide must never report "nothing to do" — so it still
+          // escapes and the run still exits 1.
+          if (error?.status !== 404) {throw error;}
+          coordinateAbsence =
+            `the registry has no image at the locked coordinate ` +
+            `${subject.imageRef}:${subject.contentHash} — nothing was ever ` +
+            `published there, so no producer evidence can attest it and the ` +
+            `lock must be re-resolved against a commit that was actually built`;
+        }
+        if (image !== null) {
+          const artifact = await resolveImageSourceEvidenceReferrer({
+            client,
+            imageRepository: subject.imageRef,
+            subjectDigest: image.digest,
+            schemas,
+          });
+          if (artifact !== null) {
+            matches = artifact.records.filter(
+              (record) =>
+                canonicalJson(record.statement.predicate.source) ===
+                canonicalJson(expectedSource),
+            );
+          }
+        }
+      }
+      const verdict =
+        coordinateAbsence !== null
+          ? {
+              status: EvidenceRefreshStatus.Unusable,
+              remainingSeconds: null,
+              reason: coordinateAbsence,
+            }
+          : classifySubject({ matches, horizonSeconds, now });
+      subjects.push({
+        distributionId,
+        subjectKind: subject.kind,
+        subjectId: subject.id,
+        repo: subject.repo,
+        repositoryUrl: repositoryPin.repositoryUrl,
+        sourceCommit: subject.sourceCommit,
+        ...verdict,
+      });
+    }
+  }
+
+  subjects.sort(
+    (left, right) =>
+      compareStrings(left.repo, right.repo) ||
+      compareStrings(left.distributionId, right.distributionId) ||
+      compareStrings(left.subjectKind, right.subjectKind) ||
+      compareStrings(left.subjectId, right.subjectId),
+  );
+  const groups = [];
+  for (const subject of subjects) {
+    const incumbent = groups.at(-1);
+    if (incumbent?.repo === subject.repo) {
+      incumbent.subjects.push(subject);
+      incumbent.due ||= DUE_STATUSES.has(subject.status);
+      continue;
+    }
+    groups.push({
+      repo: subject.repo,
+      repositoryUrl: subject.repositoryUrl,
+      subjects: [subject],
+      due: DUE_STATUSES.has(subject.status),
+    });
+  }
+  return {
+    horizonSeconds,
+    refreshDue: subjects.some((subject) => DUE_STATUSES.has(subject.status)),
+    subjects,
+    groups,
+  };
+}
+
+function classifySubject({ matches, horizonSeconds, now }) {
+  if (matches.length === 0) {
+    return {
+      status: EvidenceRefreshStatus.Absent,
+      remainingSeconds: null,
+      reason: 'no published producer evidence attests this source coordinate',
+    };
+  }
+  const [match] = matches;
+  const expiresAt = match.statement.predicate.producerRun.expiresAt;
+  const remainingSeconds = Math.floor((Date.parse(expiresAt) - now) / 1000);
+  if (!Number.isFinite(remainingSeconds)) {
+    return {
+      status: EvidenceRefreshStatus.Unusable,
+      remainingSeconds: null,
+      reason: `published statement has an unreadable expiresAt "${String(expiresAt)}"`,
+    };
+  }
+  if (remainingSeconds <= 0) {
+    return {
+      status: EvidenceRefreshStatus.Expired,
+      remainingSeconds,
+      reason: `evidence EXPIRED at ${expiresAt}; it can never verify again`,
+    };
+  }
+  if (remainingSeconds < horizonSeconds) {
+    return {
+      status: EvidenceRefreshStatus.Expiring,
+      remainingSeconds,
+      reason: `evidence expires in ${remainingSeconds}s, inside the ${horizonSeconds}s refresh horizon`,
+    };
+  }
+  return {
+    status: EvidenceRefreshStatus.Current,
+    remainingSeconds,
+    reason: `evidence is usable for another ${remainingSeconds}s`,
+  };
+}
+
+/** One line per subject, plus GitHub annotations grouped by producing repo. */
+export function renderRefreshPlan(plan) {
+  const lines = [];
+  for (const group of plan.groups) {
+    const due = group.subjects.filter((subject) =>
+      DUE_STATUSES.has(subject.status),
+    );
+    if (due.length === 0) {
+      lines.push(
+        `[image-evidence-refresh] ${group.repo}: all ${group.subjects.length} subject(s) CURRENT`,
+      );
+      continue;
+    }
+    lines.push(
+      `::error::[image-evidence-refresh] ${group.repo} (${group.repositoryUrl}) must re-run its ` +
+        `image-source evidence producer for ${due.length} of ${group.subjects.length} subject(s): ` +
+        due
+          .map(
+            (subject) =>
+              `${subject.subjectKind}:${subject.subjectId} [${subject.distributionId}] ${subject.status} — ${subject.reason}`,
+          )
+          .join(' | '),
+    );
+  }
+  lines.push(
+    plan.refreshDue
+      ? `[image-evidence-refresh] REFRESH DUE for ${
+          plan.subjects.filter((subject) => DUE_STATUSES.has(subject.status))
+            .length
+        } of ${plan.subjects.length} subject(s) within a ${plan.horizonSeconds}s horizon`
+      : `[image-evidence-refresh] all ${plan.subjects.length} subject(s) hold evidence beyond the ${plan.horizonSeconds}s horizon`,
+  );
+  return lines;
+}
+
+/** The step outputs a workflow reads: whether a refresh is due, how many subjects, and which producing repositories. */
+export function renderGithubOutputs(plan) {
+  const dueCount = plan.subjects.filter((subject) => DUE_STATUSES.has(subject.status)).length;
+  return (
+    `refresh-due=${plan.refreshDue}\n` +
+    `due-subjects=${dueCount}\n` +
+    `total-subjects=${plan.subjects.length}\n` +
+    `due-repositories=${plan.groups
+      .filter((group) => group.due)
+      .map((group) => group.repo)
+      .join(',')}\n`
+  );
+}
+
+async function main() {
+  const argv = configureEditionWorkspaceFromArgv(process.argv.slice(2), [
+    WorkspaceRoot.Data,
+    WorkspaceRoot.Editions,
+    WorkspaceRoot.Kernel,
+  ]);
+  const flags = parseEvidenceCliFlags(argv, {
+    single: [
+      'horizon-seconds',
+      'now',
+      'github-output',
+      'kernel-checkout',
+    ],
+    repeated: ['distribution'],
+  });
+  const horizonRaw = flags.optional('horizon-seconds');
+  const nowRaw = flags.optional('now');
+  const kernelCheckout = flags.optional('kernel-checkout') ?? KernelCheckout.Exact;
+  if (!Object.values(KernelCheckout).includes(kernelCheckout)) {
+    throw new Error(`--kernel-checkout must be one of ${Object.values(KernelCheckout).join(', ')}`);
+  }
+  const githubOutput = flags.optional('github-output');
+  const preview = kernelCheckout === KernelCheckout.Preview;
+  if (preview && githubOutput !== undefined) {
+    throw new Error(
+      '--kernel-checkout preview plans with a kernel build that is held to no commit; ' +
+        'its plan is a local preview and cannot be written to --github-output',
+    );
+  }
+  const schemas = preview
+    ? await loadKernelDistributionSchemas()
+    : (await loadProducerKernelSchemas({ dataRoot: dataRoot() })).schemas;
+  const plan = await planImageEvidenceRefresh({
+    distributionIds: flags.requireMany('distribution'),
+    dataRoot: dataRoot(),
+    editionsRoot: editionsRoot(),
+    schemas,
+    expectedContractAuthority: readPinnedContractAuthority({ dataRoot: dataRoot(), schemas }),
+    horizonSeconds:
+      horizonRaw === undefined ? MIN_REMAINING_TTL_SECONDS : Number(horizonRaw),
+    now: nowRaw === undefined ? Date.now() : Number(nowRaw),
+  });
+  if (preview) {
+    console.log(
+      '[image-evidence-refresh] LOCAL PREVIEW: planned with the kernel built at --kernel, which is held to no commit. ' +
+        'Nothing may be sealed or scheduled from this plan; run without --kernel-checkout preview for a verdict.',
+    );
+  }
+  for (const line of renderRefreshPlan(plan)) {
+    console.log(line);
+  }
+  if (githubOutput !== undefined) {
+    appendFileSync(githubOutput, renderGithubOutputs(plan), 'utf8');
+  }
+  if (plan.refreshDue) {
+    process.exitCode = 2;
+  }
+}
+
+if (isEntryModule(import.meta.url)) {
+  main().catch((error) => {
+    console.error(`[image-evidence-refresh] ${error.message}`);
+    process.exitCode = 1;
+  });
+}