@xemahq/xema 0.59.0 → 0.60.1

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

@@ -1,427 +0,0 @@
-#!/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,
-            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;
-  });
-}