@xemahq/xema 0.25.1 → 0.27.0

package/edition/fleet-coordinate-finality.mjs

@@ -0,0 +1,350 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// fleet-coordinate-finality — has this coordinate FINISHED MOVING?
+//
+// WHY THIS EXISTS
+// ---------------
+// A seal pins what a MUTABLE TAG currently resolves to. `imageRef:contentHash`
+// is a build-input key, not a content address: two builds of one input set wear
+// the same tag, and the arm64 lane REPUBLISHES that tag by design —
+// `imagetools create -t :<contentHash>` writes a NEW index at the SAME
+// coordinate. So sealing a coordinate that is still awaiting its arm64
+// supplement pins a manifest the tag will stop serving.
+//
+// THE REGRESSION THIS WAS WRITTEN FOR, measured — and how it is now graded
+// -----------------------------------------------------------------------
+// `xema-internal` was sealed at 09:25 on 2026-09-18 while 40 of its coordinates
+// were still amd64-only, awaiting the supplement. The arm64 backfill — the
+// CORRECT repair — then moved those digests, and 63 of its 66 seals named a
+// manifest their tag no longer served.
+//
+// Its own per-edition verification PASSED, and passed CORRECTLY: `xema-internal`
+// declares `requiredPlatforms: ["linux/amd64"]`, and amd64-only satisfies that.
+// No rule the sealer could evaluate was violated.
+//
+// WHY A PER-EDITION CHECK CANNOT CATCH IT — the whole point of this module
+// -----------------------------------------------------------------------
+// `appliance-base` and `appliance-lean` declare `linux/arm64`, and they share 63
+// of those coordinates with `xema-internal` by identical `imageRef` AND
+// `contentHash`. So `xema-internal`'s stability depended on a platform
+// requirement declared in an edition it cannot see.
+//
+//   > PLATFORM VERIFICATION IS PER-EDITION. FINALITY IS A FLEET PROPERTY.
+//
+// OWNER RULING 2026-09-29 NARROWS WHAT IS REFUSED. Finality is graded against
+// the sealing edition's OWN requiredPlatforms. The xema-internal shape above —
+// an amd64-only edition sealing while another edition's arm64 is pending — is
+// now ALLOWED and RECORDED (`pendingElsewhere`), the residual accepted: its
+// sealed digest stays resolvable and serves every platform it requires. A
+// coordinate pending a platform the sealing edition itself declares is still
+// refused. The fleet map is still built from every edition, because the
+// recorded residual must name who is waiting.
+//
+// A per-edition sealer cannot express that even in principle. This module is the
+// fleet-scoped half, and it lives HERE — beside the sealer, in the repository
+// that holds every edition's lock — because that is where the data and the edit
+// both are. An aggregator gate would grade this repository at a RECORDED
+// GITLINK: it would fire late, in a repository nobody was editing, about a
+// change made somewhere else.
+//
+// IT RESOLVES NOTHING ITSELF
+// --------------------------
+// `verifyDistributionPlatforms` already fetches each index, hash-checks the
+// bytes, walks every child manifest BY DIGEST and reads each image CONFIG for
+// its real platform — and it already returns `publishedPlatforms`, the FULL set
+// the coordinate serves rather than only the subset this edition required. That
+// return value is the input here. There is no second registry walk and no
+// second opinion about what a coordinate serves.
+//
+// WHAT IT DOES NOT COVER, said out loud rather than discovered
+// -----------------------------------------------------------
+// The fleet is the EDITIONS ROOT IT IS GIVEN. Run against a customer's own root
+// it grades that customer's editions and cannot see the vendor's, because they
+// are not there to read. That is why every verdict prints its corpus — the
+// number of editions and coordinates graded — so the scope of an answer is
+// visible in the answer rather than assumed from the fact that it passed.
+// ─────────────────────────────────────────────────────────────────────────────
+
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { discoverEditionDirectories } from './distribution-paths.mjs';
+import { platformIdentity } from './verify-image-platforms.mjs';
+
+export const IMAGE_LOCK_FILENAME = 'images.lock.json';
+
+/**
+ * The coordinate a subject names, in the ONE spelling the verifier uses.
+ *
+ * `verifyDistributionPlatforms` builds `${imageRef}:${contentHash}` and returns
+ * it as `coordinate` on every verified subject. This function must produce the
+ * same string for the lock-side map, or the two halves would silently fail to
+ * join and every lookup would miss — which is a refusal that grades nothing
+ * while reporting success. The join is asserted rather than trusted: see the
+ * unknown-coordinate throw in {@link assertCoordinatesFinal}.
+ */
+export function coordinateOf(subject) {
+  return `${subject.imageRef}:${subject.contentHash}`;
+}
+
+/**
+ * Pure: every platform any edition requires at each coordinate, and WHO
+ * requires it.
+ *
+ * `editions` is `[{ distributionId, subjects }]` — already read, so the
+ * decision table is testable without a filesystem or a registry.
+ *
+ * The returned shape is `Map<coordinate, Map<platformIdentity, string[]>>`,
+ * where the array is the sorted edition ids requiring that platform there. The
+ * REQUIRERS are carried rather than only the platforms because a refusal that
+ * cannot name who is still waiting sends the reader to look for the reason
+ * themselves, and the reason is in another edition's declaration.
+ */
+export function collectFleetPlatformRequirements({ editions }) {
+  if (!Array.isArray(editions) || editions.length === 0) {
+    throw new Error(
+      'fleet-coordinate-finality: no edition was supplied; a fleet requirement map ' +
+        'built over zero editions would make every coordinate look final, which is ' +
+        'the refusal passing while grading nothing',
+    );
+  }
+  const byCoordinate = new Map();
+  for (const edition of editions) {
+    const { distributionId, subjects } = edition;
+    if (typeof distributionId !== 'string' || distributionId.length === 0) {
+      throw new Error(
+        'fleet-coordinate-finality: an edition was supplied with no distributionId',
+      );
+    }
+    if (!Array.isArray(subjects) || subjects.length === 0) {
+      throw new Error(
+        `fleet-coordinate-finality: "${distributionId}" has an image lock declaring no ` +
+          'subjects. An edition that contributes no coordinate is indistinguishable ' +
+          'from one this pass failed to read, so it is refused rather than skipped.',
+      );
+    }
+    for (const subject of subjects) {
+      if (
+        !Array.isArray(subject.requiredPlatforms) ||
+        subject.requiredPlatforms.length === 0
+      ) {
+        throw new Error(
+          `fleet-coordinate-finality: "${distributionId}" subject ${subject.kind}:${subject.id} ` +
+            'declares no requiredPlatforms. It would contribute nothing to the fleet map ' +
+            'and silently weaken the refusal for every edition sharing its coordinate.',
+        );
+      }
+      const coordinate = coordinateOf(subject);
+      let platforms = byCoordinate.get(coordinate);
+      if (!platforms) {
+        platforms = new Map();
+        byCoordinate.set(coordinate, platforms);
+      }
+      for (const platform of subject.requiredPlatforms) {
+        const identity = platformIdentity(platform);
+        let requirers = platforms.get(identity);
+        if (!requirers) {
+          requirers = new Set();
+          platforms.set(identity, requirers);
+        }
+        requirers.add(distributionId);
+      }
+    }
+  }
+  // Freeze the requirer sets into sorted arrays so a message built from this map
+  // is deterministic, and so a caller cannot mutate the map it was handed.
+  return new Map(
+    [...byCoordinate].map(([coordinate, platforms]) => [
+      coordinate,
+      new Map(
+        [...platforms].map(([identity, requirers]) => [
+          identity,
+          [...requirers].sort(),
+        ]),
+      ),
+    ]),
+  );
+}
+
+/**
+ * Read every edition's image lock under `editionsRoot`, in BOTH tiers.
+ *
+ * A pending-merge edition is a real edition that will ship its coordinates, so
+ * a platform IT requires is just as much a reason a coordinate can still move.
+ * Measured 2026-09-19: the two pending editions carry a declaration and no lock,
+ * so today this widening admits nothing — which is the point at which to add it,
+ * rather than after a pending edition has acquired one.
+ *
+ * TWO ABSENCES THAT ARE NOT THE SAME, and conflating them is how this check
+ * would quietly stop working:
+ *
+ *   * NO LOCK FILE — the edition makes no coordinate claim at all. It
+ *     contributes nothing, legitimately, and is COUNTED and reported so the
+ *     corpus line shows it was seen and skipped.
+ *   * A LOCK THAT CANNOT BE READ — refused. An unreadable lock contributes no
+ *     requirements either, and the difference between "requires nothing" and
+ *     "we failed to find out" is the whole value of the refusal.
+ *
+ * `JSON.parse` rather than the kernel's `parseImageLock` is deliberate. Only
+ * three fields are read — `imageRef`, `contentHash`, `requiredPlatforms` — and
+ * requiring a BUILT KERNEL to grade the OTHER editions would make this refusal
+ * unrunnable in exactly the checkouts that have no kernel to build. The edition
+ * being sealed is still parsed by the kernel on the path that seals it.
+ */
+export function readFleetImageLocks(editionsRoot) {
+  const editions = [];
+  const withoutLock = [];
+  for (const { id, directory } of discoverEditionDirectories(editionsRoot)) {
+    const lockPath = join(directory, IMAGE_LOCK_FILENAME);
+    if (!existsSync(lockPath)) {
+      withoutLock.push(id);
+      continue;
+    }
+    let raw;
+    try {
+      raw = JSON.parse(readFileSync(lockPath, 'utf8'));
+    } catch (error) {
+      throw new Error(
+        `fleet-coordinate-finality: cannot read ${lockPath}: ${error.message}. ` +
+          'Refusing to grade coordinate finality over a fleet this pass could not ' +
+          'fully read — an unreadable lock declares no requirement, which would make ' +
+          'a coordinate look final because it was never asked about.',
+      );
+    }
+    editions.push({ distributionId: id, subjects: raw.subjects });
+  }
+  if (editions.length === 0) {
+    throw new Error(
+      `fleet-coordinate-finality: found no image lock under ${editionsRoot}; an empty ` +
+        'scan is not a result',
+    );
+  }
+  return { editions, withoutLock: withoutLock.sort() };
+}
+
+/**
+ * Refuse to seal a coordinate THIS edition still awaits a platform at; record —
+ * and allow — one only ANOTHER edition still awaits.
+ *
+ * Owner ruling 2026-09-29: finality is TARGET-PLATFORM aware. A coordinate
+ * pending only a platform this edition does not declare is the accepted
+ * residual, returned as `pendingElsewhere` so the caller prints it. A later
+ * supplement for that other edition may move the tag's digest; this edition's
+ * seal keeps pinning the manifest it verified, which still resolves by digest
+ * and still carries every platform this edition requires.
+ *
+ * `verified` is `verifyDistributionPlatforms(...).subjects`, each carrying
+ * `coordinate` and `publishedPlatforms` — the platforms the registry ACTUALLY
+ * serves there, which is strictly wider than the subset this edition required.
+ *
+ * THE SUBJECT SET IS THE WRITES, NOT THE LOCK. This grades the subjects about to
+ * RECEIVE a digest, because that is the moment the regression is introduced. An
+ * already-sealed subject is past it: re-refusing one would make the daily
+ * reconciler permanently red with no action available to clear it, and a gate
+ * that cannot be cleared is one people learn to bypass.
+ *
+ * Throws with `error.notFinal === true` — a PROPERTY, never a message match, so
+ * the reconciler's skip cannot silently widen the day this wording changes. Same
+ * discipline as `error.status` on the not-published-yet path.
+ */
+export function assertCoordinatesFinal({
+  distributionId,
+  writes,
+  verified,
+  fleetRequirements,
+}) {
+  const graded = [];
+  const pendingElsewhere = [];
+  if (!Array.isArray(writes) || writes.length === 0) {
+    return { distributionId, graded, coordinateCount: 0, pendingElsewhere };
+  }
+  const byKey = new Map(
+    verified.map((entry) => [`${entry.subjectKind}:${entry.subjectId}`, entry]),
+  );
+  const blockers = [];
+  for (const write of writes) {
+    const entry = byKey.get(write.key);
+    if (!entry) {
+      throw new Error(
+        `fleet-coordinate-finality: ${write.key} is planned for sealing but has no ` +
+          'verification result to read published platforms from; refusing to grade ' +
+          'finality for a subject the verifier did not cover',
+      );
+    }
+    const required = fleetRequirements.get(entry.coordinate);
+    if (!required) {
+      // NON-VACUITY GUARD. The edition being sealed is itself one of the
+      // editions read into the map, so every coordinate it seals MUST be in
+      // there. A miss means the two halves are keyed differently and every
+      // lookup would return nothing — a refusal that passes while grading
+      // nothing, which is this tree's most-repeated defect.
+      throw new Error(
+        `fleet-coordinate-finality: coordinate ${entry.coordinate} (${write.key}) is absent ` +
+          'from the fleet requirement map, which cannot happen while the edition being ' +
+          'sealed is itself in that map. The lock-side and verifier-side coordinate ' +
+          'spellings have diverged; refusing rather than passing over a lookup that ' +
+          'silently misses.',
+      );
+    }
+    const served = new Set(entry.publishedPlatforms ?? []);
+    const unmet = [...required]
+      .filter(([identity]) => !served.has(identity))
+      .map(([identity, requirers]) => ({ platform: identity, requiredBy: requirers }));
+    graded.push({ key: write.key, coordinate: entry.coordinate });
+    // TARGET-PLATFORM AWARE (owner ruling 2026-09-29). Finality is graded
+    // against THIS edition's own requiredPlatforms: a platform only ANOTHER
+    // edition awaits here is the accepted residual — allowed, and RECORDED so
+    // the caller can print it. A platform this edition itself declares and the
+    // registry does not serve is still refused.
+    const own = unmet.filter((u) => u.requiredBy.includes(distributionId));
+    const foreign = unmet.filter((u) => !u.requiredBy.includes(distributionId));
+    if (foreign.length > 0) {
+      pendingElsewhere.push({
+        key: write.key,
+        coordinate: entry.coordinate,
+        unmet: foreign,
+        served: [...served].sort(),
+      });
+    }
+    if (own.length > 0) {
+      blockers.push({ key: write.key, coordinate: entry.coordinate, unmet: own, served: [...served].sort() });
+    }
+  }
+  if (blockers.length > 0) {
+    const detail = blockers
+      .slice(0, 6)
+      .map(
+        (b) =>
+          `    ${b.key}  ${b.coordinate}\n` +
+          b.unmet
+            .map(
+              (u) =>
+                `        awaits ${u.platform}, required by ${u.requiredBy.join(', ')} ` +
+                `(serves: ${b.served.join(', ') || 'nothing'})`,
+            )
+            .join('\n'),
+      )
+      .join('\n');
+    const error = new Error(
+      `fleet-coordinate-finality: "${distributionId}" cannot be sealed — ${blockers.length} of ` +
+        `${writes.length} coordinate(s) are NOT FINAL for a platform THIS edition requires: ` +
+        'the registry does not yet serve it there, so the coordinate will be supplemented ' +
+        '— and the arm64 lane supplements by REPUBLISHING the tag (`imagetools create -t ' +
+        ':<contentHash>`), which would move the very digest this seal is about to pin.\n' +
+        `${detail}${blockers.length > 6 ? `\n    ... and ${blockers.length - 6} more` : ''}\n` +
+        'Complete the supplement for this edition\'s own platforms, then seal.',
+    );
+    error.notFinal = true;
+    error.blockers = blockers;
+    throw error;
+  }
+  return { distributionId, graded, coordinateCount: graded.length, pendingElsewhere };
+}
+
+/**
+ * Is this failure "another edition can still supplement this coordinate"?
+ *
+ * A PROPERTY, never a message match — see {@link assertCoordinatesFinal}.
+ */
+export function isNotFinalYet(error) {
+  return Boolean(error) && error.notFinal === true;
+}

package/edition/git-source-auth.mjs

@@ -0,0 +1,52 @@
+// git-source-auth — the ONE place the edition library turns a read token into git
+// authentication for a repository URL, shared by every script that fetches or
+// lists a repository (first-party sources and a customer's own git source alike).
+//
+// The credential reaches git through GIT_CONFIG_* environment variables, never
+// argv, a file or a clone's config, and it is scoped to the ORIGIN of the URL it
+// is for: `http.<origin>/.extraHeader` is applied by git only to URLs under that
+// origin, so the token is not sent to any other host, nor to a host a redirect
+// leads to. For a first-party source pass `sourceRepositoryUrlPrefix` (from
+// edition-workspace.json); for a customer git source pass its own url.
+//
+// Why this is not `gitEnvWithAuth` of the CLI's runtime (src/runtime/sources/kinds/git.ts):
+// the edition library is plain ESM that `node` runs straight from this directory
+// and that the evidence verifier bundle is built from, so it cannot import the CLI's
+// TypeScript sources or its compiled CommonJS output. The shape is the same
+// on purpose (Basic `<declared username>:<token>`, `Authorization` header, origin
+// scope; the username is a required argument, never a built-in default), so there is exactly ONE implementation per runtime.
+
+/**
+ * `base` plus the GIT_CONFIG_* header that authenticates git against `url`'s
+ * origin as `username` with `token`. A token that cannot be applied is refused: an empty
+ * token, or a URL that is not an absolute https URL with a host. There is no
+ * fall-back to the ambient credential helper.
+ */
+export function gitAuthEnv(url, username, token, base = process.env) {
+  if (typeof username !== 'string' || username.length === 0 || username.includes(':')) {
+    throw new Error(
+      `a git username is required to authenticate git against ${String(url)} (non-empty, no ":"); ` +
+        'it is declared, never defaulted: `sourceAuthUsername` in edition-workspace.json for first-party sources, ' +
+        'the source\'s own `authUsername` for a customer git source',
+    );
+  }
+  if (typeof token !== 'string' || token.length === 0) {
+    throw new Error(`a read token is required to authenticate git against ${String(url)}`);
+  }
+  let origin;
+  try {
+    const parsed = new URL(url);
+    if (parsed.protocol !== 'https:' || parsed.hostname === '') {throw new Error('not an https URL with a host');}
+    origin = parsed.origin;
+  } catch {
+    throw new Error(`cannot scope a git credential to "${String(url)}": it is not an absolute https URL with a host`);
+  }
+  const credential = Buffer.from(`${username}:${token}`, 'utf8').toString('base64');
+  return {
+    ...base,
+    GIT_CONFIG_COUNT: '1',
+    GIT_CONFIG_KEY_0: `http.${origin}/.extraHeader`,
+    GIT_CONFIG_VALUE_0: `Authorization: Basic ${credential}`,
+    GIT_TERMINAL_PROMPT: '0',
+  };
+}

package/edition/image-evidence-replay-state.mjs

@@ -0,0 +1,242 @@
+import { randomUUID } from 'node:crypto';
+import {
+  closeSync,
+  constants as fsConstants,
+  fstatSync,
+  fsyncSync,
+  openSync,
+  readSync,
+  realpathSync,
+  renameSync,
+  unlinkSync,
+  writeFileSync,
+} from 'node:fs';
+import { basename, dirname, isAbsolute, join } from 'node:path';
+
+import {
+  canonicalJsonBytes,
+  parseCanonicalJsonBytes,
+} from './image-evidence.mjs';
+
+const MAX_REPLAY_STATE_BYTES = 64 * 1024;
+
+function openRegularFileNoFollow(path) {
+  const descriptor = openSync(
+    path,
+    fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW,
+  );
+  const metadata = fstatSync(descriptor);
+  if (!metadata.isFile()) {
+    closeSync(descriptor);
+    throw new Error(`replay state "${path}" is not a regular file`);
+  }
+  if ((metadata.mode & 0o777) !== 0o600) {
+    closeSync(descriptor);
+    throw new Error(`replay state "${path}" must have exact mode 0600`);
+  }
+  if (
+    typeof process.getuid === 'function' &&
+    metadata.uid !== process.getuid()
+  ) {
+    closeSync(descriptor);
+    throw new Error(`replay state "${path}" must be owned by the verifier`);
+  }
+  return descriptor;
+}
+
+function assertTrustedStateDirectory(path) {
+  const descriptor = openSync(
+    path,
+    fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW,
+  );
+  try {
+    const metadata = fstatSync(descriptor);
+    if (!metadata.isDirectory()) {
+      throw new Error(`replay state parent "${path}" is not a directory`);
+    }
+    if ((metadata.mode & 0o777) !== 0o700) {
+      throw new Error(
+        `replay state parent "${path}" must have exact mode 0700`,
+      );
+    }
+    if (
+      typeof process.getuid === 'function' &&
+      metadata.uid !== process.getuid()
+    ) {
+      throw new Error(
+        `replay state parent "${path}" must be owned by the verifier`,
+      );
+    }
+  } finally {
+    closeSync(descriptor);
+  }
+}
+
+function writeDurableReplacement(path, value) {
+  const directory = realpathSync(dirname(path));
+  const temporaryPath = join(
+    directory,
+    `.${basename(path)}.${randomUUID()}.tmp`,
+  );
+  let descriptor;
+  try {
+    descriptor = openSync(
+      temporaryPath,
+      fsConstants.O_CREAT |
+        fsConstants.O_EXCL |
+        fsConstants.O_WRONLY |
+        fsConstants.O_NOFOLLOW,
+      0o600,
+    );
+    writeFileSync(descriptor, canonicalJsonBytes(value));
+    fsyncSync(descriptor);
+    closeSync(descriptor);
+    descriptor = undefined;
+    renameSync(temporaryPath, path);
+    const directoryDescriptor = openSync(directory, fsConstants.O_RDONLY);
+    try {
+      fsyncSync(directoryDescriptor);
+    } finally {
+      closeSync(directoryDescriptor);
+    }
+  } finally {
+    if (descriptor !== undefined) {closeSync(descriptor);}
+    removeIfPresent(temporaryPath);
+  }
+}
+
+/** Remove `path`; only its absence is tolerated. */
+function removeIfPresent(path) {
+  try {
+    unlinkSync(path);
+  } catch (error) {
+    if (error?.code !== 'ENOENT') {throw error;}
+  }
+}
+
+export async function verifyAndAdvanceReplayState({
+  statePath,
+  distributionId,
+  trustPolicyDigest,
+  parseReplayState,
+  verify,
+}) {
+  if (!isAbsolute(statePath)) {
+    throw new Error('replay state path must be absolute');
+  }
+  const stateDirectory = realpathSync(dirname(statePath));
+  if (stateDirectory !== dirname(statePath)) {
+    throw new Error('replay state parent path must be canonical');
+  }
+  assertTrustedStateDirectory(stateDirectory);
+  const canonicalStatePath = join(stateDirectory, basename(statePath));
+  const lockPath = `${canonicalStatePath}.lock`;
+  let lockDescriptor;
+  try {
+    lockDescriptor = openSync(
+      lockPath,
+      fsConstants.O_CREAT |
+        fsConstants.O_EXCL |
+        fsConstants.O_WRONLY |
+        fsConstants.O_NOFOLLOW,
+      0o600,
+    );
+  } catch (error) {
+    if (error?.code === 'EEXIST') {
+      throw new Error(
+        `replay state "${canonicalStatePath}" is locked by another verifier; explicit operator reconciliation is required for a stale lock`,
+      );
+    }
+    throw error;
+  }
+
+  try {
+    writeFileSync(
+      lockDescriptor,
+      `${process.pid} ${new Date().toISOString()}\n`,
+    );
+    fsyncSync(lockDescriptor);
+    const stateDescriptor = openRegularFileNoFollow(canonicalStatePath);
+    let state;
+    try {
+      const before = fstatSync(stateDescriptor);
+      if (before.size > MAX_REPLAY_STATE_BYTES) {
+        throw new Error(`replay state exceeds ${MAX_REPLAY_STATE_BYTES} bytes`);
+      }
+      const stateBytes = Buffer.alloc(before.size);
+      let offset = 0;
+      while (offset < stateBytes.length) {
+        const count = readSync(
+          stateDescriptor,
+          stateBytes,
+          offset,
+          stateBytes.length - offset,
+          offset,
+        );
+        if (count === 0) {
+          throw new Error('replay state was truncated while reading');
+        }
+        offset += count;
+      }
+      if (readSync(stateDescriptor, Buffer.alloc(1), 0, 1, offset) !== 0) {
+        throw new Error('replay state grew while reading');
+      }
+      const after = fstatSync(stateDescriptor);
+      for (const field of ['dev', 'ino', 'size', 'mtimeMs', 'ctimeMs']) {
+        if (after[field] !== before[field]) {
+          throw new Error('replay state changed while reading');
+        }
+      }
+      state = parseReplayState(
+        parseCanonicalJsonBytes(stateBytes, 'distribution image replay state'),
+      );
+    } finally {
+      closeSync(stateDescriptor);
+    }
+    if (
+      state.distributionId !== distributionId ||
+      state.trustPolicyDigest !== trustPolicyDigest
+    ) {
+      throw new Error(
+        'replay state does not match the selected distribution and committed trust policy',
+      );
+    }
+
+    const verified = await verify(state);
+    const completeness = verified.completenessStatement.predicate;
+    if (completeness.releaseSequence <= state.lastReleaseSequence) {
+      throw new Error(
+        'verified completeness evidence does not advance releaseSequence',
+      );
+    }
+    if (completeness.nonce === state.lastCompletenessNonce) {
+      throw new Error(
+        'verified completeness evidence reuses the last accepted nonce',
+      );
+    }
+    if (
+      verified.completenessStatementDigest ===
+      state.lastCompletenessStatementDigest
+    ) {
+      throw new Error(
+        'verified completeness evidence reuses the last accepted statement',
+      );
+    }
+    const nextState = parseReplayState({
+      schemaVersion: 1,
+      distributionId,
+      trustPolicyDigest,
+      lastReleaseSequence: completeness.releaseSequence,
+      lastCompletenessStatementDigest: verified.completenessStatementDigest,
+      lastCompletenessNonce: completeness.nonce,
+    });
+    writeDurableReplacement(canonicalStatePath, nextState);
+    return { verified, replayState: nextState };
+  } finally {
+    try {
+      closeSync(lockDescriptor);
+    } finally {
+      unlinkSync(lockPath);
+    }
+  }
+}