@xemahq/edition-tooling 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,428 @@
+#!/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,
+  loadValidatedImageLocks,
+} from './image-evidence.mjs';
+import { assertKernelContractAuthorityEqual } from './kernel-contract-authority.mjs';
+import { compareStrings, loadKernelDistributionSchemas } from './lib.mjs';
+import {
+  createRegistryClientResolver,
+  describeInvalidReferrer,
+  resolveImageSourceEvidenceReferrer,
+  writeInvalidReferrerReport,
+} 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, thirdPartySources } = await loadValidatedImageLocks(
+      distributionId,
+      dataRootDirectory,
+      schemas,
+      { editionsRoot: editionsRootDirectory },
+    );
+    assertKernelContractAuthorityEqual(
+      runtimeSourceIndex.contractAuthority,
+      expectedContractAuthority,
+      'runtime-image-source-index.json',
+    );
+    for (const subject of imageLock.subjects) {
+      // A third-party subject's contentHash is publisher-attested (no tag, no registry referrer here); its evidence is the committed bundle.
+      if (thirdPartySources.has(subject.repo)) {continue;}
+      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 unusableReason = null;
+      // Every referrer of this subject that is not valid evidence, as reported
+      // by the resolver. All of them invalid is a decided UNUSABLE verdict.
+      const invalidReferrers = [];
+      {
+        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;}
+          unusableReason =
+            `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,
+            expectedContractAuthority,
+            authorityBound: true, // first-party subject: bound to the contract authority on every channel (authority-binding.mjs)
+            onInvalidReferrer: (skipped) => {
+              invalidReferrers.push(skipped);
+              writeInvalidReferrerReport(skipped);
+            },
+          });
+          if (artifact === null && invalidReferrers.length > 0) {
+            unusableReason =
+              `every evidence referrer of ${subject.imageRef}@${image.digest} ` +
+              `(repo ${subject.repo}) is invalid under the required kernel contract ` +
+              `authority ${expectedContractAuthority.sourceCommit}: ` +
+              invalidReferrers.map(describeInvalidReferrer).join('; ');
+          }
+          if (artifact !== null) {
+            matches = artifact.records.filter(
+              (record) =>
+                canonicalJson(record.statement.predicate.source) ===
+                canonicalJson(expectedSource),
+            );
+          }
+        }
+      }
+      const verdict =
+        unusableReason !== null
+          ? {
+              status: EvidenceRefreshStatus.Unusable,
+              remainingSeconds: null,
+              reason: unusableReason,
+            }
+          : 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;
+  });
+}