@forestrie/forestrie-cli 0.8.0

package/src/lib/verify-checkpoint-chain.ts

@@ -0,0 +1,160 @@
+import { bytesEqual } from "./bytes.js";
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { verifyCoseSign1WithParsedKey } from "@forestrie/encoding";
+import {
+  resolveDelegatedVerifyKey,
+  type CheckpointChainLink,
+} from "@forestrie/receipt-verify";
+import type { AnchorCheck } from "./verify-anchored.js";
+
+/**
+ * Retained checkpoint-chain anchor (FOR-368 Phase 3, plan-2607-29).
+ *
+ * The log store's retained `.sth` objects chain contiguously post-FOR-410
+ * (ADR-0056: every checkpoint's embedded consistency proof spans its
+ * massif's entry boundary to its seal). `@forestrie/receipt-verify`'s
+ * `verifyCheckpointChain` folds that chain from size 0, authenticating the
+ * accumulator at EVERY retained seal — this rung depends only on the
+ * public log store: no tiles, no RPC, no holder cache. It is the
+ * complement of the `CheckpointPublished` event scan (public chain data
+ * only); the two paths are independently sufficient and cross-checkable.
+ *
+ * A receipt whose recomputed peak appears in ANY authenticated link is
+ * proven: each later link's signed consistency proof commits the earlier
+ * accumulator forward, so burial never turns an honest receipt
+ * tamper-shaped.
+ */
+
+/**
+ * Resolve `--checkpoint-chain` to ordered checkpoint files: a directory of
+ * `.sth` objects (store naming zero-pads massif indexes, so lexicographic
+ * order IS chain order), or an explicit comma-separated list in chain
+ * order.
+ */
+export function loadCheckpointChainFiles(pathspec: string): {
+  files: string[];
+  checkpoints: Uint8Array[];
+} {
+  let files: string[];
+  let isDirectory = false;
+  try {
+    isDirectory = statSync(pathspec).isDirectory();
+  } catch {
+    // A comma-separated list is not itself a path; fall through.
+  }
+  if (isDirectory) {
+    files = readdirSync(pathspec)
+      .filter((name) => name.endsWith(".sth"))
+      .sort()
+      .map((name) => join(pathspec, name));
+  } else {
+    files = pathspec.split(",").map((f) => f.trim()).filter((f) => f !== "");
+  }
+  if (files.length === 0) {
+    throw new Error(
+      `--checkpoint-chain matched no .sth checkpoints: '${pathspec}'`,
+    );
+  }
+  return {
+    files,
+    checkpoints: files.map((f) => new Uint8Array(readFileSync(f))),
+  };
+}
+
+/**
+ * Signature trust for chain links, rooted in the caller's trust anchor
+ * (genesis-derived roots or `--known-log-key`): resolve each checkpoint's
+ * label-1000 delegation cert under the root keys, then verify the COSE
+ * signature over the folded accumulator as detached payload. The payload
+ * is COMPUTED by the fold, never read from the checkpoint — a link only
+ * authenticates the accumulator its proof actually derives (ADR-0046).
+ */
+export function makeCheckpointSignatureVerifier(
+  rootKeys: CryptoKey[],
+): (
+  checkpointBytes: Uint8Array,
+  detachedPayload: Uint8Array,
+) => Promise<boolean> {
+  return async (checkpointBytes, detachedPayload) => {
+    const resolution = await resolveDelegatedVerifyKey(
+      checkpointBytes,
+      rootKeys,
+    );
+    if (resolution.kind === "broken") return false;
+    const candidates =
+      resolution.kind === "resolved"
+        ? [resolution.delegatedKey, ...rootKeys]
+        : rootKeys;
+    for (const key of candidates) {
+      if (
+        await verifyCoseSign1WithParsedKey(checkpointBytes, key, {
+          logPrefix: "checkpoint-chain",
+          detachedPayload,
+        })
+      ) {
+        return true;
+      }
+    }
+    return false;
+  };
+}
+
+export type CheckpointChainAnchorCheck = AnchorCheck & {
+  /** Number of authenticated links in the fold. */
+  linkCount: number;
+  /** Sealed size of the link holding the peak (null when unmatched). */
+  matchedLinkSize: bigint | null;
+};
+
+/**
+ * Find the recomputed receipt peak in the authenticated chain. Newest-first
+ * (mirrors the event-scan rung): the freshest cover gives the most useful
+ * report, and a match at ANY link is proof — later links' signed
+ * consistency proofs commit it forward. Newer-than-chain fails CLOSED with
+ * a refresh remedy: retention limits coverage, never validity.
+ */
+export function checkReceiptAnchoredToCheckpointChain(opts: {
+  links: CheckpointChainLink[];
+  recomputedPeak: Uint8Array;
+  leafMmrIndex: bigint;
+}): CheckpointChainAnchorCheck {
+  const final = opts.links[opts.links.length - 1]!;
+  const base = {
+    accumulator: final.accumulator,
+    size: final.treeSize2,
+    linkCount: opts.links.length,
+  };
+  if (opts.leafMmrIndex >= final.treeSize2) {
+    return {
+      ...base,
+      anchored: false,
+      matchedPeak: null,
+      matchedLinkSize: null,
+      reason: "receipt_newer_than_checkpoint_chain",
+    };
+  }
+  for (let i = opts.links.length - 1; i >= 0; i--) {
+    const link = opts.links[i]!;
+    for (let p = 0; p < link.accumulator.length; p++) {
+      if (bytesEqual(opts.recomputedPeak, link.accumulator[p]!)) {
+        return {
+          ...base,
+          anchored: true,
+          matchedPeak: p,
+          matchedLinkSize: link.treeSize2,
+          accumulator: link.accumulator,
+          size: link.treeSize2,
+        };
+      }
+    }
+  }
+  return {
+    ...base,
+    anchored: false,
+    matchedPeak: null,
+    matchedLinkSize: null,
+    reason: "peak_not_in_checkpoint_chain",
+  };
+}
+

package/src/lib/verify-eventscan.ts

@@ -0,0 +1,214 @@
+/**
+ * Historical anchor scan over `CheckpointPublished` events (FOR-368
+ * Phase 2, plan-2607-29).
+ *
+ * Univocity's `publishCheckpoint` verifies consistency from the current
+ * on-chain state before accepting a new accumulator, so **every anchored
+ * accumulator is a committed prefix of every later one**. A receipt whose
+ * recomputed peak appears in ANY historical anchored accumulator is
+ * therefore proven — consistency to the present is carried by the
+ * contract, not by a client-side grow proof. The event log is the durable
+ * record of those accumulators (`CheckpointPublished` carries `size` and
+ * `accumulator`; the contract stores nothing retrievable historically).
+ *
+ * This rung depends only on public blockchain data — deliberately
+ * independent of the log store (the retained-checkpoint chain rung is its
+ * complement with the opposite dependency; see plan-2607-29).
+ */
+import { bytesEqual } from "./bytes.js";
+import { normalizeHexAddress } from "@forestrie/chain-rpc";
+import { toContractLogId } from "./verify-anchored.js";
+
+/**
+ * keccak256 of
+ * `CheckpointPublished(bytes32,bytes32,bytes,address,bytes8,uint8,uint64,bytes32[],uint64,bytes32[])`
+ * (univocity `IUnivocityEvents.sol`). The contract is immutable per forest,
+ * so this signature is stable for every deployed instance.
+ */
+export const CHECKPOINT_PUBLISHED_TOPIC0 =
+  "0x156942b408823cb05a16027962ea485fa7171d99779ee04094280b2569482426";
+
+export type PublishedCheckpoint = {
+  /** Anchored MMR size. */
+  size: bigint;
+  /** Anchored accumulator peaks (32 bytes each), contract order. */
+  accumulator: Uint8Array[];
+  /** Block the anchor landed in. */
+  blockNumber: bigint;
+  /** Transaction that published it. */
+  txHash: string;
+  /** Hash of that block (falsifiability handle for the snapshot). */
+  blockHash: string;
+};
+
+export type HistoricalAnchor = PublishedCheckpoint & {
+  /** Index of the matching accumulator peak. */
+  matchedPeak: number;
+};
+
+type EthLog = {
+  data?: string;
+  blockNumber?: string;
+  transactionHash?: string;
+  blockHash?: string;
+};
+
+function readWord(hex: string, wordIndex: number): bigint {
+  const start = wordIndex * 64;
+  if (hex.length < start + 64) {
+    throw new Error(
+      `CheckpointPublished data too short: need word ${wordIndex}, have ${hex.length} hex chars`,
+    );
+  }
+  return BigInt("0x" + hex.slice(start, start + 64));
+}
+
+function hexToBytes(hex: string): Uint8Array {
+  const out = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < out.length; i++) {
+    out[i] = Number.parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+  }
+  return out;
+}
+
+/**
+ * Decode the non-indexed `CheckpointPublished` fields we need. Data layout
+ * (ABI, after the three indexed params): word0 `sender`, word1
+ * `grantIDTimestampBe` (padded bytes8), word2 `logKind`, word3 `size`,
+ * word4 offset→`accumulator`, word5 `grantIndex`, word6 offset→`grantPath`.
+ */
+export function decodeCheckpointPublishedData(dataHex: string): {
+  size: bigint;
+  accumulator: Uint8Array[];
+} {
+  const hex = dataHex.replace(/^0x/, "");
+  const size = readWord(hex, 3);
+  const accumulatorOffset = readWord(hex, 4);
+  const arrayBase = Number(accumulatorOffset) / 32;
+  const length = Number(readWord(hex, arrayBase));
+  const accumulator: Uint8Array[] = [];
+  for (let i = 0; i < length; i++) {
+    const start = (arrayBase + 1 + i) * 64;
+    if (hex.length < start + 64) {
+      throw new Error(
+        `CheckpointPublished accumulator truncated at peak ${i} of ${length}`,
+      );
+    }
+    accumulator.push(hexToBytes(hex.slice(start, start + 64)));
+  }
+  return { size, accumulator };
+}
+
+/** Minimal JSON-RPC fetch (mirrors fetch-accumulator's raw pattern). */
+async function rpc(
+  rpcUrl: string,
+  method: string,
+  params: unknown[],
+  fetchImpl: typeof fetch,
+): Promise<unknown> {
+  const res = await fetchImpl(rpcUrl, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ jsonrpc: "2.0", id: 1, method, params }),
+  });
+  if (!res.ok) {
+    throw new Error(`${method}: HTTP ${res.status}`);
+  }
+  const body = (await res.json()) as { result?: unknown; error?: { message?: string } };
+  if (body.error) {
+    throw new Error(`${method}: ${body.error.message ?? "rpc error"}`);
+  }
+  return body.result;
+}
+
+/**
+ * Fetch every `CheckpointPublished` for a log (topic1 = contract log id),
+ * ascending block order as returned by `eth_getLogs`.
+ */
+export async function fetchPublishedCheckpoints(opts: {
+  univocity: string;
+  logId: string;
+  rpcUrl: string;
+  /** First block to scan (the forest's deploy block bounds the range). */
+  fromBlock?: bigint | undefined;
+  fetchImpl?: typeof fetch;
+}): Promise<PublishedCheckpoint[]> {
+  const address = normalizeHexAddress(opts.univocity);
+  if (address === null) {
+    throw new Error(`--univocity is not a valid address: '${opts.univocity}'`);
+  }
+  const logs = (await rpc(
+    opts.rpcUrl,
+    "eth_getLogs",
+    [
+      {
+        address: `0x${address}`,
+        fromBlock:
+          opts.fromBlock !== undefined
+            ? `0x${opts.fromBlock.toString(16)}`
+            : "earliest",
+        toBlock: "latest",
+        topics: [CHECKPOINT_PUBLISHED_TOPIC0, toContractLogId(opts.logId)],
+      },
+    ],
+    opts.fetchImpl ?? fetch,
+  )) as EthLog[] | null;
+  const out: PublishedCheckpoint[] = [];
+  for (const log of logs ?? []) {
+    if (!log.data) continue;
+    const { size, accumulator } = decodeCheckpointPublishedData(log.data);
+    out.push({
+      size,
+      accumulator,
+      blockNumber: BigInt(log.blockNumber ?? "0x0"),
+      txHash: log.transactionHash ?? "",
+      blockHash: log.blockHash ?? "",
+    });
+  }
+  return out;
+}
+
+
+/**
+ * Find the recomputed receipt peak in any historically anchored
+ * accumulator. Newest-first: recent anchors are the likeliest cover for a
+ * recently buried peak, and the freshest match gives the most useful
+ * report. A match at ANY anchored state proves the receipt: univocity's
+ * consistency gating commits it forward to the present.
+ */
+export async function findPeakInPublishedHistory(opts: {
+  peak: Uint8Array;
+  univocity: string;
+  logId: string;
+  rpcUrl: string;
+  fromBlock?: bigint | undefined;
+  fetchImpl?: typeof fetch;
+}): Promise<HistoricalAnchor | null> {
+  const published = await fetchPublishedCheckpoints(opts);
+  for (let i = published.length - 1; i >= 0; i--) {
+    const cp = published[i]!;
+    for (let p = 0; p < cp.accumulator.length; p++) {
+      if (bytesEqual(opts.peak, cp.accumulator[p]!)) {
+        return { ...cp, matchedPeak: p };
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Latest anchored state at or before `atBlock` (FOR-368 Phase 2:
+ * `fetch-accumulator --at-block`): historical snapshots come from the
+ * event record, so no archive-state RPC is needed.
+ */
+export function selectPublishedAtBlock(
+  published: PublishedCheckpoint[],
+  atBlock: bigint,
+): PublishedCheckpoint | null {
+  let best: PublishedCheckpoint | null = null;
+  for (const cp of published) {
+    if (cp.blockNumber > atBlock) continue;
+    if (best === null || cp.blockNumber > best.blockNumber) best = cp;
+  }
+  return best;
+}

package/src/lib/verify-inputs.ts

@@ -0,0 +1,143 @@
+import { readFileSync } from "node:fs";
+import {
+  decodeForestrieGrantCose,
+  decodeGrantPayload,
+  entryIdHexToIdtimestampBe8,
+  type VerifyGrantReceiptOfflineInput,
+  type VerifyReceiptOfflineInput,
+} from "@forestrie/receipt-verify";
+
+/** `verify` (generic): the exact registered payload + its SCRAPI entry id. */
+export type PayloadVerifyInputOptions = {
+  /** Optional when the trust anchor is a caller-known key (FOR-297 D1). */
+  genesis: string | undefined;
+  receipt: string;
+  payload: string;
+  entryId: string;
+};
+
+/** Genesis-optional artifact shape (`--known-log-key` runs without genesis). */
+export type LoadedPayloadVerifyArtifacts = Omit<
+  VerifyReceiptOfflineInput,
+  "genesisCbor"
+> & { genesisCbor: Uint8Array | undefined };
+
+/** Load genesis/receipt/payload for the generic (SCITT-compatible) verify. */
+export function loadPayloadVerifyArtifacts(
+  options: PayloadVerifyInputOptions,
+): LoadedPayloadVerifyArtifacts {
+  return {
+    genesisCbor:
+      options.genesis !== undefined
+        ? readBytes(options.genesis, "--genesis")
+        : undefined,
+    receiptCbor: readBytes(options.receipt, "--receipt"),
+    payload: readBytes(options.payload, "--payload"),
+    idtimestampBe8: entryIdHexToIdtimestampBe8(options.entryId),
+  };
+}
+
+/**
+ * Load and decode `forestrie verify` inputs into the exact
+ * `verifyGrantReceiptOffline` input shape (FOR-347). Pure file/decode work
+ * — strictly no network.
+ *
+ * Grant sources (mirrors the canopy FOR-282 tracer):
+ * - `--committed-grant`: base64 of either a Forestrie-Grant COSE Sign1
+ *   (carries the idtimestamp in unprotected header -65537) or a raw grant
+ *   payload CBOR (keys 1–6; then `--entry-id` must supply the idtimestamp).
+ * - `--committed-grant-file` + `--entry-id`: grant CBOR file (COSE or raw
+ *   payload); the idtimestamp comes from the permanent SCRAPI entry id.
+ */
+export type VerifyInputOptions = {
+  /** Optional when the trust anchor is a caller-known key (FOR-297 D1). */
+  genesis: string | undefined;
+  receipt: string;
+  committedGrant: string | undefined;
+  committedGrantFile: string | undefined;
+  entryId: string | undefined;
+};
+
+/** Genesis-optional artifact shape (`--known-log-key` runs without genesis). */
+export type LoadedVerifyArtifacts = Omit<
+  VerifyGrantReceiptOfflineInput,
+  "genesisCbor"
+> & { genesisCbor: Uint8Array | undefined };
+
+function readBytes(path: string, flag: string): Uint8Array {
+  try {
+    return new Uint8Array(readFileSync(path));
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new Error(`cannot read ${flag} '${path}': ${message}`);
+  }
+}
+
+function decodeBase64(b64: string): Uint8Array {
+  const bytes = new Uint8Array(Buffer.from(b64, "base64"));
+  if (bytes.length === 0) {
+    throw new Error(
+      "--committed-grant is not valid base64 (decoded to 0 bytes)",
+    );
+  }
+  return bytes;
+}
+
+/** Decode grant bytes: Forestrie-Grant COSE Sign1 first, raw payload CBOR second. */
+function decodeGrantBytes(
+  bytes: Uint8Array,
+  entryId: string | undefined,
+  source: string,
+): Pick<VerifyGrantReceiptOfflineInput, "grant" | "idtimestampBe8"> {
+  try {
+    const decoded = decodeForestrieGrantCose(bytes);
+    return {
+      grant: decoded.grant,
+      idtimestampBe8:
+        entryId !== undefined
+          ? entryIdHexToIdtimestampBe8(entryId)
+          : decoded.idtimestampBe8,
+    };
+  } catch {
+    // Not a Forestrie-Grant COSE Sign1 — fall through to raw payload CBOR.
+  }
+  const grant = decodeGrantPayload(bytes);
+  if (entryId === undefined) {
+    throw new Error(
+      `${source} is a raw grant payload (no embedded idtimestamp) — pass --entry-id`,
+    );
+  }
+  return { grant, idtimestampBe8: entryIdHexToIdtimestampBe8(entryId) };
+}
+
+/** Read genesis/receipt/grant artefacts from disk into verify input bytes. */
+export function loadVerifyArtifacts(
+  options: VerifyInputOptions,
+): LoadedVerifyArtifacts {
+  const genesisCbor =
+    options.genesis !== undefined
+      ? readBytes(options.genesis, "--genesis")
+      : undefined;
+  const receiptCbor = readBytes(options.receipt, "--receipt");
+
+  let grantBytes: Uint8Array;
+  let source: string;
+  if (options.committedGrant !== undefined) {
+    grantBytes = decodeBase64(options.committedGrant);
+    source = "--committed-grant";
+  } else if (options.committedGrantFile !== undefined) {
+    grantBytes = readBytes(options.committedGrantFile, "--committed-grant-file");
+    source = `--committed-grant-file '${options.committedGrantFile}'`;
+  } else {
+    throw new Error(
+      "either --committed-grant or --committed-grant-file is required",
+    );
+  }
+
+  const { grant, idtimestampBe8 } = decodeGrantBytes(
+    grantBytes,
+    options.entryId,
+    source,
+  );
+  return { genesisCbor, receiptCbor, grant, idtimestampBe8 };
+}

package/src/lib/verify-known-accumulator.ts

@@ -0,0 +1,161 @@
+import { bytesEqual } from "./bytes.js";
+import {
+  assertSnapshotBinding,
+  computeAccumulatorPeak,
+  decodeKnownAccumulator,
+  encodeKnownAccumulator,
+  parseReceipt,
+  univocityLeafHash,
+  type KnownAccumulator,
+} from "@forestrie/receipt-verify";
+import { type AnchorCheck } from "./verify-anchored.js";
+
+/**
+ * Snapshot artifact (type, encode, decode, binding assertion) hoisted to
+ * `@forestrie/receipt-verify` (FOR-297 D5, plan-2607-34 slice 02 Part B) so
+ * the CLI and other consumers share one implementation. Re-exported here so
+ * existing local imports (`from "./verify-known-accumulator.js"`) keep
+ * working unchanged.
+ */
+export {
+  assertSnapshotBinding,
+  decodeKnownAccumulator,
+  encodeKnownAccumulator,
+  type KnownAccumulator,
+};
+
+/**
+ * Known-accumulator snapshot (FOR-297 D5): a cached, auditable chain read of
+ * the log's `logState`, letting chain-anchored verification run fully
+ * offline. The artifact type, encode/decode, and binding assertion moved to
+ * `@forestrie/receipt-verify` (plan-2607-34 slice 02 Part B) — re-exported
+ * above. See that package's `known-accumulator.ts` module doc for the trust
+ * model.
+ *
+ * What stays CLI-local: `checkReceiptAnchoredToSnapshot` below adds
+ * proof-path extension for stale snapshots (needs a local massif blob) —
+ * a bigger, file-shaped input the package's pure-bytes API doesn't take
+ * yet. The package's own `verifyReceiptOfflineAgainstKnownAccumulator`
+ * covers the same exact-peak-match case (its case 2) for callers that don't
+ * need extension.
+ */
+
+function bytesToHex(bytes: Uint8Array): string {
+  return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+export type SnapshotAnchorCheck = AnchorCheck & {
+  /** True when the match required proof-path extension via massif nodes. */
+  extended: boolean;
+  blockNumber: bigint;
+  blockHashHex: string;
+};
+
+/**
+ * Assert the receipt's peak is anchored in the known-accumulator snapshot —
+ * fully offline. Strategies, in order:
+ *
+ * 1. Fail closed when the receipt's leaf postdates the snapshot (refresh).
+ * 2. Exact peak match: the recomputed receipt peak is still a snapshot peak.
+ * 3. Proof-path extension (needs `massifBytes`): the receipt's peak is an
+ *    interior node of the snapshot state; rebuild the leaf's inclusion path
+ *    at the snapshot size from massif nodes and match the covering peak. The
+ *    massif's leaf value must equal the locally derived leaf commitment —
+ *    the payload stays bound even though the extension nodes come from the
+ *    (untrusted) massif: every node on the path is recomputed.
+ */
+export async function checkReceiptAnchoredToSnapshot(opts: {
+  snapshot: KnownAccumulator;
+  receiptCbor: Uint8Array;
+  idtimestampBe8: Uint8Array;
+  /** Leaf ContentHash: SHA-256(payload) or the grant commitment hash. */
+  inner: Uint8Array;
+  /** Recomputed receipt peak (leaf + receipt proof path, no signature). */
+  recomputedPeak: Uint8Array;
+  /** Local massif blob enabling proof-path extension for stale snapshots. */
+  massifBytes?: Uint8Array | undefined;
+}): Promise<SnapshotAnchorCheck> {
+  const { snapshot } = opts;
+  const base = {
+    accumulator: snapshot.accumulator,
+    size: snapshot.size,
+    blockNumber: snapshot.blockNumber,
+    blockHashHex: bytesToHex(snapshot.blockHash),
+  };
+
+  const { proof } = parseReceipt(opts.receiptCbor);
+  const leafMmrIndex =
+    proof.leafIndex !== undefined ? proof.leafIndex : proof.mmrIndex!;
+
+  // 1. Newer-than-snapshot fails CLOSED — staleness limits coverage, never
+  // validity, so the remedy is a refresh, not a pass.
+  if (leafMmrIndex >= snapshot.size) {
+    return {
+      ...base,
+      anchored: false,
+      matchedPeak: null,
+      extended: false,
+      reason: "receipt_newer_than_known_accumulator",
+    };
+  }
+
+  // 2. Exact peak match — receipt state is a snapshot-covered accumulator.
+  for (let i = 0; i < snapshot.accumulator.length; i++) {
+    if (bytesEqual(opts.recomputedPeak, snapshot.accumulator[i]!)) {
+      return { ...base, anchored: true, matchedPeak: i, extended: false };
+    }
+  }
+
+  // 3. Extension: the old peak should be interior to the snapshot state.
+  if (opts.massifBytes === undefined) {
+    return {
+      ...base,
+      anchored: false,
+      matchedPeak: null,
+      extended: false,
+      reason: "peak_not_in_known_accumulator",
+    };
+  }
+
+  const leafHash = await univocityLeafHash(opts.idtimestampBe8, opts.inner);
+  let computed: Awaited<ReturnType<typeof computeAccumulatorPeak>>;
+  try {
+    computed = await computeAccumulatorPeak({
+      massifBytes: opts.massifBytes,
+      mmrIndex: leafMmrIndex,
+      mmrSize: snapshot.size,
+    });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new Error(
+      `proof-path extension failed (massif does not cover the snapshot?): ${message}`,
+    );
+  }
+  if (!bytesEqual(computed.leafValue, leafHash)) {
+    // The massif's leaf disagrees with the payload-derived commitment — the
+    // extension cannot bind this payload.
+    return {
+      ...base,
+      anchored: false,
+      matchedPeak: null,
+      extended: false,
+      reason: "massif_leaf_mismatch",
+    };
+  }
+  const target = snapshot.accumulator[computed.peakIndex];
+  if (target !== undefined && bytesEqual(computed.peak, target)) {
+    return {
+      ...base,
+      anchored: true,
+      matchedPeak: computed.peakIndex,
+      extended: true,
+    };
+  }
+  return {
+    ...base,
+    anchored: false,
+    matchedPeak: null,
+    extended: false,
+    reason: "peak_not_in_known_accumulator",
+  };
+}