@mikeargento/bitgraph-verify 1.6.0 → 1.7.0

package/src/fuse-member.ts

@@ -7,6 +7,11 @@
  * canonical set manifest (placement set/1, see fuse.ts) and every member's
  * fused bytes carry the set's commitment via the member's own placement.
  * verifyFuse answers for the manifest; this module answers for a member.
+ * A set/2 (fuse.ts) commits the ROOT of a Merkle tree over the same rows
+ * instead of the list; its member carries its row, its leaf index and its
+ * sibling path, and binding means: root document hashed to the signed
+ * artifact and sealed to the slot, then the path reaching that root. From
+ * there the two set kinds share every step below.
  *
  * Given a proof whose signed attribution declares set/1 and a file:
  *   1. Verify the proof as an ordinary bitgraph/1 proof. Fail: stop.
@@ -47,9 +52,14 @@ import {
   PLACEMENTS,
   parseSetManifest,
   readFuseAttribution,
+  parseSetMemberProof,
+  parseSetRoot,
   readSetMetadata,
+  SET_MEMBER_METADATA_KEY,
   SET_METADATA_KEY,
   SET_PLACEMENT_ID,
+  SET2_PLACEMENT_ID,
+  setRootFromMember,
   type Located,
   type Placement,
   type SetMember,
@@ -60,6 +70,8 @@ export type FuseMemberCategory =
   | "SET_MEMBER_DIRECT"
   | "SET_MEMBER_FROM_ORIGIN"
   | "SET_NOT_MEMBER"
+  | "SET_MEMBERSHIP_UNPROVEN"
+  | "INVALID_SET_PATH"
   | "RECONSTRUCTION_MISMATCH"
   | "INVALID_SET_MANIFEST"
   | "INVALID_SLOT_COMMITMENT"
@@ -69,20 +81,29 @@ export type FuseMemberCategory =
   | "NO_MATCH";
 
 export interface FuseSetEvidence {
-  /** Where the manifest bytes came from: the proof's metadata, or the caller's argument. */
+  /** "set/1": the whole member list is the committed artifact. "set/2": a Merkle root over the rows is. */
+  kind: "set/1" | "set/2";
+  /** Where the committed artifact's bytes came from (the set/1 manifest or the set/2 root document): the proof's metadata, or the caller's argument. */
   manifestSource: "metadata" | "argument";
-  /** SHA-256 of the bound manifest bytes; equals artifactDigestB64 once bound. */
+  /** SHA-256 of the bound bytes; equals artifactDigestB64 once bound. */
   manifestDigestB64: string;
+  /** set/1: the rows listed. set/2: the count the root document states. */
   memberCount: number;
-  /** The matched row. Non-null ONLY on the two member categories. */
+  /** set/2 only: where the member's evidence (row, index, path) came from; null when none was in hand. */
+  memberSource: "metadata" | "argument" | null;
+  /** set/2 only: the tree root, standard base64. */
+  treeRootB64: string | null;
+  /** The matched row. Non-null ONLY on the two member categories. `index` is the row's index in the list (set/1) or its leaf index in the tree (set/2). */
   member: { index: number; placement: string; fusedDigestB64: string; originDigestB64: string } | null;
 }
 
 export interface FuseMemberOptions {
   proof: BitGraphProof;
   bytes: Uint8Array;
-  /** Canonical set manifest bytes; when given they replace proof.metadata as the source and are never silently replaced by it. */
+  /** Canonical bytes of the committed artifact (a set/1 manifest, or a set/2 root document); when given they replace proof.metadata as the source and are never silently replaced by it. */
   manifest?: Uint8Array | null;
+  /** set/2: the member's evidence (row, index, count, path) as its JSON object; when given it replaces proof.metadata[SET_MEMBER_METADATA_KEY]. */
+  member?: unknown;
   trustAnchors?: VerificationPolicy;
   /** Refuse to accept a span wider than this many positions (M - N). Never affects validity categories. */
   maxPositions?: bigint | number;
@@ -109,10 +130,18 @@ declare const admittedBrand: unique symbol;
  */
 interface BoundSet {
   readonly [boundBrand]: true;
+  readonly kind: "set/1" | "set/2";
   readonly source: "metadata" | "argument";
   readonly digestB64: string;
   readonly commitment: Uint8Array;
+  /** set/1: every listed row. set/2: the one row whose path reached the root, or none when no evidence was in hand. */
   readonly rows: readonly SetMember[];
+  /** The set's member count: rows.length for set/1, the root document's count for set/2. */
+  readonly count: number;
+  /** set/2: the leaf index of each of `rows` in the tree; null for set/1, where a row's index is its position in `rows`. */
+  readonly treeIndices: readonly number[] | null;
+  readonly memberSource: "metadata" | "argument" | null;
+  readonly rootB64: string | null;
   /** Lowercase hex of a row's artifact digest to its index. */
   readonly byArtifact: ReadonlyMap<string, number>;
   /** Lowercase hex of an origin digest to the indices listing it, in manifest order. */
@@ -167,7 +196,64 @@ function bindSetManifest(proof: BitGraphProof, commitment: Uint8Array, bytes: Ui
     const origin = bytesToHex(row.origin);
     byOrigin.set(origin, [...(byOrigin.get(origin) ?? []), index]);
   });
-  const bound: Omit<BoundSet, typeof boundBrand> = { source, digestB64: bytesToBase64(digest), commitment, rows: manifest.members, byArtifact, byOrigin };
+  const bound: Omit<BoundSet, typeof boundBrand> = { kind: "set/1", source, digestB64: bytesToBase64(digest), commitment, rows: manifest.members, count: manifest.members.length, treeIndices: null, memberSource: null, rootB64: null, byArtifact, byOrigin };
+  return bound as BoundSet;
+}
+
+/**
+ * The only constructor of a set/2 BoundSet. In order: strict parse of the
+ * root document, SHA-256 of its bytes equal to the SIGNED artifact digest,
+ * commitment equal to the one recomputed from the proof's own slot record;
+ * then, when member evidence is in hand, its strict parse, its count equal
+ * to the root document's, and its leaf and path recomputing exactly the
+ * committed root. A set bound without evidence lists no row: nothing can be
+ * admitted against it, and the caller's verdict is that membership was not
+ * shown. Rows never enter a BoundSet without their path reaching the root.
+ */
+function bindSetRoot(
+  proof: BitGraphProof,
+  commitment: Uint8Array,
+  bytes: Uint8Array,
+  source: "metadata" | "argument",
+  evidence: { value: unknown; from: "metadata" | "argument" } | null,
+): BoundSet | Unbound | { category: "INVALID_SET_PATH"; reason: string } {
+  const doc = parseSetRoot(bytes);
+  if (doc === null) {
+    return { category: "INVALID_SET_MANIFEST", reason: "the set root document is not canonical bitgraph-fuse/1 set/2 bytes" };
+  }
+  const digest = sha256(bytes);
+  const artifact = base64ToBytes(proof.artifact.digestB64);
+  if (artifact === null || !bytesEqual(digest, artifact)) {
+    return { category: "INVALID_SET_MANIFEST", reason: "the set root document does not hash to the committed artifact digest" };
+  }
+  if (!bytesEqual(doc.commitment, commitment)) {
+    return { category: "INVALID_SLOT_COMMITMENT", reason: "the commitment in the committed set root document does not match the proof's slot record" };
+  }
+  const common = { kind: "set/2" as const, source, digestB64: bytesToBase64(digest), commitment, count: doc.count, rootB64: bytesToBase64(doc.root) };
+  if (evidence === null) {
+    const empty: Omit<BoundSet, typeof boundBrand> = { ...common, rows: [], treeIndices: [], memberSource: null, byArtifact: new Map(), byOrigin: new Map() };
+    return empty as BoundSet;
+  }
+  const parsed = parseSetMemberProof(evidence.value);
+  if (parsed === null) {
+    return { category: "INVALID_SET_PATH", reason: "the member evidence is not a well-formed bitgraph-fuse/1 set/2 member proof" };
+  }
+  if (parsed.count !== doc.count) {
+    return { category: "INVALID_SET_PATH", reason: `the member evidence names a tree of ${parsed.count} leaves; the committed root document states ${doc.count}` };
+  }
+  const reached = setRootFromMember(parsed.member, parsed.index, parsed.count, parsed.path);
+  if (reached === null || !bytesEqual(reached, doc.root)) {
+    return { category: "INVALID_SET_PATH", reason: "the member's leaf and path do not recompute the committed root; the row is not shown to be in the set" };
+  }
+  const row = parsed.member;
+  const bound: Omit<BoundSet, typeof boundBrand> = {
+    ...common,
+    rows: [row],
+    treeIndices: [parsed.index],
+    memberSource: evidence.from,
+    byArtifact: new Map([[bytesToHex(row.artifact), 0]]),
+    byOrigin: new Map([[bytesToHex(row.origin), [0]]]),
+  };
   return bound as BoundSet;
 }
 
@@ -225,6 +311,16 @@ function strayReason(span: FuseSpan | null, memberCount: number): string {
   return `these bytes carry the commitment of ${slot}, so they were made after that slot existed, but their digest is not among the ${memberCount} members listed in the set manifest ${commit}; the set proof does not cover them`;
 }
 
+/** set/2: the two-part reason when the floor holds but no evidence, or evidence for another member, is in hand. */
+function unprovenReason(span: FuseSpan | null, memberCount: number, otherMember: boolean): string {
+  const slot = span !== null ? `the slot allocated at position ${span.slotCounter}` : "its slot";
+  const commit = span !== null ? `committed at position ${span.commitCounter}` : "at its commit";
+  const shown = otherMember
+    ? "the member evidence in hand describes a different member, so"
+    : "no member evidence (row, index, path) is in hand, so";
+  return `these bytes carry the commitment of ${slot}, so they were made after that slot existed, but ${shown} their place among the ${memberCount} members of the set ${commit} is not shown; a set/2 proof covers a member only with its path`;
+}
+
 export async function verifyFuseMember(opts: FuseMemberOptions): Promise<FuseMemberResult> {
   const { proof, bytes } = opts;
   const fileDigest = sha256(bytes);
@@ -274,11 +370,12 @@ export async function verifyFuseMember(opts: FuseMemberOptions): Promise<FuseMem
     maxPositions: maxPositions === null ? null : maxPositions.toString(),
   };
   const common = { proof: { valid: true }, marker, span, policy };
-  if (marker === null || marker.placement !== SET_PLACEMENT_ID) {
-    return base("INVALID_SET_MANIFEST", common, "the proof is not marked set/1; verifyFuse answers for this proof");
+  if (marker === null || (marker.placement !== SET_PLACEMENT_ID && marker.placement !== SET2_PLACEMENT_ID)) {
+    return base("INVALID_SET_MANIFEST", common, "the proof is not marked set/1 or set/2; verifyFuse answers for this proof");
   }
+  const setKind: "set/1" | "set/2" = marker.placement === SET2_PLACEMENT_ID ? "set/2" : "set/1";
   if (marker.originDigest !== undefined) {
-    return base("INVALID_SET_MANIFEST", common, "the proof is marked set/1 but its signed attribution names an origin digest; a set has no single origin");
+    return base("INVALID_SET_MANIFEST", common, `the proof is marked ${setKind} but its signed attribution names an origin digest; a set has no single origin`);
   }
 
   // 3. The commitment, from the proof's own slot record.
@@ -295,20 +392,36 @@ export async function verifyFuseMember(opts: FuseMemberOptions): Promise<FuseMem
   const slotCommitmentB64 = bytesToBase64(commitment);
   const withSlot = { ...common, slotCommitmentB64 };
 
-  // 4. Bind the manifest. An explicit argument replaces the metadata source
-  //    and is never silently replaced by it.
+  // 4. Bind the committed artifact: a set/1 manifest, or a set/2 root
+  //    document and, when in hand, the member's evidence. An explicit
+  //    argument replaces the metadata source and is never silently replaced
+  //    by it.
   const explicit = opts.manifest === undefined || opts.manifest === null ? null : opts.manifest;
   const metadata = explicit === null ? readSetMetadata(proof) : null;
   const source = explicit !== null ? { bytes: explicit, from: "argument" as const } : metadata !== null ? { bytes: metadata, from: "metadata" as const } : null;
   if (source === null) {
-    return base("INVALID_SET_MANIFEST", withSlot, `no set manifest: none under proof.metadata["${SET_METADATA_KEY}"] and none supplied`);
+    return base("INVALID_SET_MANIFEST", withSlot, `no set ${setKind === "set/1" ? "manifest" : "root document"}: none under proof.metadata["${SET_METADATA_KEY}"] and none supplied`);
+  }
+  let bound: BoundSet;
+  if (setKind === "set/1") {
+    const b = bindSetManifest(proof, commitment, source.bytes, source.from);
+    if ("category" in b) return base(b.category, withSlot, b.reason);
+    bound = b;
+  } else {
+    const explicitMember = opts.member === undefined || opts.member === null ? null : opts.member;
+    const metadataMember = explicitMember === null ? (proof.metadata?.[SET_MEMBER_METADATA_KEY] ?? null) : null;
+    const evidenceSource = explicitMember !== null ? { value: explicitMember, from: "argument" as const } : metadataMember !== null ? { value: metadataMember, from: "metadata" as const } : null;
+    const b = bindSetRoot(proof, commitment, source.bytes, source.from, evidenceSource);
+    if ("category" in b) return base(b.category, withSlot, b.reason);
+    bound = b;
   }
-  const bound = bindSetManifest(proof, commitment, source.bytes, source.from);
-  if ("category" in bound) return base(bound.category, withSlot, bound.reason);
   const evidence = (member: FuseSetEvidence["member"]): FuseSetEvidence => ({
+    kind: bound.kind,
     manifestSource: bound.source,
     manifestDigestB64: bound.digestB64,
-    memberCount: bound.rows.length,
+    memberCount: bound.count,
+    memberSource: bound.memberSource,
+    treeRootB64: bound.rootB64,
     member,
   });
   const withSet = { ...withSlot, set: evidence(null) };
@@ -324,19 +437,23 @@ export async function verifyFuseMember(opts: FuseMemberOptions): Promise<FuseMem
     if (bound.byArtifact.get(bytesToHex(row.artifact)) !== index || bound.rows[index] !== row) {
       throw new Error("verifyFuseMember: membership re-assertion failed");
     }
-    const count = bound.rows.length;
+    const count = bound.count;
+    // set/1: a row's index is its place in the list. set/2: its leaf index in the tree, carried by the bound evidence.
+    const shown = bound.treeIndices !== null ? bound.treeIndices[index]! : index;
+    const listed = bound.kind === "set/1" ? "listed in the set manifest committed" : "of the set whose Merkle root was committed";
     const statements: string[] = [];
     if (span !== null) {
       if (path === "direct") {
-        statements.push(`These exact fused bytes are member ${index + 1} of ${count} listed in the set manifest committed at position ${span.commitCounter}.`);
+        statements.push(`These exact fused bytes are member ${shown + 1} of ${count} ${listed} at position ${span.commitCounter}.`);
         if (admitted.originCompared) {
-          statements.push("The fused bytes carry an origin digest that matches the set manifest; the original itself was not supplied and was not checked.");
+          statements.push(`The fused bytes carry an origin digest that matches the set ${bound.kind === "set/1" ? "manifest" : "member evidence"}; the original itself was not supplied and was not checked.`);
         }
       } else {
         statements.push(
-          `The supplied original rebuilds member ${index + 1} of ${count} of the committed set byte for byte, so these exact original bytes existed no later than commit position ${span.commitCounter}.`,
+          `The supplied original rebuilds member ${shown + 1} of ${count} of the committed set byte for byte, so these exact original bytes existed no later than commit position ${span.commitCounter}.`,
         );
       }
+      if (bound.kind === "set/2") statements.push(`The member's leaf and its ${bound.treeIndices !== null ? "path" : "path"} recompute the committed root, so the row is one of the ${count} the set commits to.`);
       statements.push(floorStatement(span));
     }
     return {
@@ -352,13 +469,13 @@ export async function verifyFuseMember(opts: FuseMemberOptions): Promise<FuseMem
       policy,
       statements,
       reason: null,
-      set: evidence({ index, placement: placement.id, fusedDigestB64: bytesToBase64(row.artifact), originDigestB64: bytesToBase64(row.origin) }),
+      set: evidence({ index: shown, placement: placement.id, fusedDigestB64: bytesToBase64(row.artifact), originDigestB64: bytesToBase64(row.origin) }),
     };
   };
 
-  // 5. The bytes are the committed manifest itself: verifyFuse answers for it.
+  // 5. The bytes are the committed artifact itself: verifyFuse answers for it.
   if (fileDigestB64 === artifactDigestB64) {
-    return base("NO_MATCH", withSet, "these bytes are the committed set manifest itself, not a member; verifyFuse answers for the manifest");
+    return base("NO_MATCH", withSet, `these bytes are the committed set ${bound.kind === "set/1" ? "manifest" : "root document"} itself, not a member; verifyFuse answers for it`);
   }
 
   // 6. Direct path: the bytes hash to a listed member. Authoritative when it
@@ -417,14 +534,19 @@ export async function verifyFuseMember(opts: FuseMemberOptions): Promise<FuseMem
     );
   }
 
-  // 8. Stray scan: bytes that carry this slot's commitment yet are listed
-  //    nowhere. Made after the slot, not part of the committed set: the
-  //    two-part verdict, with no rendered floor.
+  // 8. Stray scan: bytes that carry this slot's commitment yet match no row
+  //    in hand. set/1 lists every row, so this is the two-part verdict: made
+  //    after the slot, not part of the committed set. set/2 has in hand at
+  //    most the one row its evidence proved, so absence is not shown: the
+  //    floor holds, membership is unproven (no evidence) or the evidence is
+  //    another member's. No rendered floor in either case.
   for (const p of PLACEMENTS) {
     const l = p.locate(bytes);
     if (l === null) continue;
     if (bytesEqual(l.commitment, commitment)) {
-      return base("SET_NOT_MEMBER", { ...withSet, placement: p.id, statements: [] }, strayReason(span, bound.rows.length));
+      if (bound.kind === "set/1") return base("SET_NOT_MEMBER", { ...withSet, placement: p.id, statements: [] }, strayReason(span, bound.count));
+      const other = bound.rows.length > 0;
+      return base(other ? "INVALID_SET_PATH" : "SET_MEMBERSHIP_UNPROVEN", { ...withSet, placement: p.id, statements: [] }, unprovenReason(span, bound.count, other));
     }
     return base("NO_MATCH", withSet, "these bytes carry a commitment to a different slot; the proof proves nothing about them");
   }

package/src/fuse-merkle.ts

@@ -0,0 +1,177 @@
+// Copyright (c) 2024-2026 Mike Argento. Licensed under the MIT License. See LICENSE.
+
+/**
+ * The Merkle tree a set/2 commits to: RFC 6962 (Certificate Transparency)
+ * hashing over an ordered list of leaf hashes, with the RFC 9162 inclusion
+ * proof. Domain separation is the RFC's: a leaf hash is SHA-256 of 0x00 and
+ * the leaf's bytes, an inner node SHA-256 of 0x01, left, right. A list of
+ * n leaves splits at k, the largest power of two below n, so every list has
+ * exactly one root and every leaf exactly one inclusion path of at most
+ * ceil(log2 n) siblings. Nothing here knows what a leaf is; fuse.ts says.
+ */
+
+import { sha256 } from "@noble/hashes/sha256";
+
+const LEAF_PREFIX = new Uint8Array([0x00]);
+const NODE_PREFIX = new Uint8Array([0x01]);
+
+function concat(...parts: Uint8Array[]): Uint8Array {
+  let n = 0;
+  for (const p of parts) n += p.length;
+  const out = new Uint8Array(n);
+  let o = 0;
+  for (const p of parts) {
+    out.set(p, o);
+    o += p.length;
+  }
+  return out;
+}
+
+/** SHA-256(0x00 || bytes): the hash of one leaf. */
+export function merkleLeafHash(bytes: Uint8Array): Uint8Array {
+  return sha256(concat(LEAF_PREFIX, bytes));
+}
+
+/** SHA-256(0x01 || left || right): one inner node. */
+export function merkleNodeHash(left: Uint8Array, right: Uint8Array): Uint8Array {
+  return sha256(concat(NODE_PREFIX, left, right));
+}
+
+/** The largest power of two strictly below n (n >= 2). */
+function split(n: number): number {
+  let k = 1;
+  while (k * 2 < n) k *= 2;
+  return k;
+}
+
+/**
+ * The root over leaf HASHES (each already merkleLeafHash of its leaf), in
+ * list order. Throws on an empty list; the root of one leaf hash is that
+ * hash itself, as in RFC 6962.
+ */
+export function merkleRoot(leafHashes: readonly Uint8Array[]): Uint8Array {
+  if (leafHashes.length === 0) throw new TypeError("a Merkle tree needs at least one leaf");
+  for (const h of leafHashes) if (h.length !== 32) throw new TypeError("a leaf hash is 32 bytes");
+  const build = (lo: number, hi: number): Uint8Array => {
+    const n = hi - lo;
+    if (n === 1) return leafHashes[lo]!;
+    const k = split(n);
+    return merkleNodeHash(build(lo, lo + k), build(lo + k, hi));
+  };
+  return build(0, leafHashes.length);
+}
+
+/**
+ * The inclusion path of the leaf at `index`: its siblings from the leaf's
+ * own level up to the root, in that order (RFC 6962 PATH). Empty for a tree
+ * of one leaf.
+ */
+export function merklePath(leafHashes: readonly Uint8Array[], index: number): Uint8Array[] {
+  const n = leafHashes.length;
+  if (n === 0) throw new TypeError("a Merkle tree needs at least one leaf");
+  if (!Number.isInteger(index) || index < 0 || index >= n) throw new RangeError("leaf index out of range");
+  const path: Uint8Array[] = [];
+  const walk = (lo: number, hi: number, m: number): void => {
+    const size = hi - lo;
+    if (size === 1) return;
+    const k = split(size);
+    const build = (a: number, b: number): Uint8Array => merkleRoot(leafHashes.slice(a, b));
+    if (m < lo + k) {
+      walk(lo, lo + k, m);
+      path.push(build(lo + k, hi));
+    } else {
+      walk(lo + k, hi, m);
+      path.push(build(lo, lo + k));
+    }
+  };
+  walk(0, n, index);
+  return path;
+}
+
+/**
+ * Recompute the root from one leaf hash, its index, the tree size and its
+ * path (RFC 9162 section 2.1.3.2). Null when the path does not fit the
+ * index and size: too short, too long, or an index outside the tree. A
+ * result that equals the committed root proves the leaf is at `index` in a
+ * tree of `size` leaves with that root; nothing else is proven.
+ */
+export function merkleRootFromPath(leafHash: Uint8Array, index: number, size: number, path: readonly Uint8Array[]): Uint8Array | null {
+  if (!Number.isInteger(index) || !Number.isInteger(size) || size < 1 || index < 0 || index >= size) return null;
+  if (leafHash.length !== 32) return null;
+  let fn = index;
+  let sn = size - 1;
+  let r = leafHash;
+  for (const p of path) {
+    if (p.length !== 32) return null;
+    if (sn === 0) return null;
+    if ((fn & 1) === 1 || fn === sn) {
+      r = merkleNodeHash(p, r);
+      if ((fn & 1) === 0) {
+        while ((fn & 1) === 0 && fn !== 0) {
+          fn >>>= 1;
+          sn >>>= 1;
+        }
+      }
+    } else {
+      r = merkleNodeHash(r, p);
+    }
+    fn >>>= 1;
+    sn >>>= 1;
+  }
+  if (sn !== 0) return null;
+  return r;
+}
+
+/**
+ * The whole tree over a list of leaf hashes, every subtree root computed
+ * once, so the paths of all N leaves cost N log N hashes in total instead of
+ * N per path. The split rule and the path order are merkleRoot's and
+ * merklePath's exactly; a test pins them equal.
+ */
+export class MerkleTree {
+  readonly size: number;
+  readonly root: Uint8Array;
+  private readonly leafHashes: readonly Uint8Array[];
+  /** Subtree root by "lo:hi". */
+  private readonly memo = new Map<string, Uint8Array>();
+
+  constructor(leafHashes: readonly Uint8Array[]) {
+    if (leafHashes.length === 0) throw new TypeError("a Merkle tree needs at least one leaf");
+    for (const h of leafHashes) if (h.length !== 32) throw new TypeError("a leaf hash is 32 bytes");
+    this.leafHashes = leafHashes;
+    this.size = leafHashes.length;
+    this.root = this.subtree(0, this.size);
+  }
+
+  private subtree(lo: number, hi: number): Uint8Array {
+    const n = hi - lo;
+    if (n === 1) return this.leafHashes[lo]!;
+    const key = `${lo}:${hi}`;
+    const known = this.memo.get(key);
+    if (known !== undefined) return known;
+    const k = split(n);
+    const h = merkleNodeHash(this.subtree(lo, lo + k), this.subtree(lo + k, hi));
+    this.memo.set(key, h);
+    return h;
+  }
+
+  /** The inclusion path of the leaf at `index`, siblings from the leaf's level up. */
+  path(index: number): Uint8Array[] {
+    if (!Number.isInteger(index) || index < 0 || index >= this.size) throw new RangeError("leaf index out of range");
+    const out: Uint8Array[] = [];
+    const walk = (lo: number, hi: number): void => {
+      const n = hi - lo;
+      if (n === 1) return;
+      const k = split(n);
+      if (index < lo + k) {
+        walk(lo, lo + k);
+        out.push(this.subtree(lo + k, hi));
+      } else {
+        walk(lo + k, hi);
+        out.push(this.subtree(lo, lo + k));
+      }
+    };
+    walk(0, this.size);
+    return out;
+  }
+}