@mikeargento/bitgraph-verify 1.5.0 → 1.7.0

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;
+  }
+}

package/src/fuse.ts

@@ -26,6 +26,7 @@
  */
 
 import { sha256 } from "@noble/hashes/sha256";
+import { merkleLeafHash, merkleRootFromPath, MerkleTree } from "./fuse-merkle.js";
 import { canonicalize } from "./canonical.js";
 import type { Attribution, BitGraphProof, SlotAllocation } from "./types.js";
 
@@ -247,7 +248,7 @@ export function parseFusePayload(bytes: Uint8Array): { commitment: Uint8Array; o
 }
 
 // ---------------------------------------------------------------------------
-// Minimal deterministic ustar (POSIX.1-1988) for container/1
+// Minimal deterministic ustar (POSIX.1-1988) for container/1 and container/2
 // ---------------------------------------------------------------------------
 
 const BLOCK = 512;
@@ -260,7 +261,7 @@ function octal(n: number, width: number): Uint8Array {
 }
 
 function ustarHeader(name: string, size: number): Uint8Array {
-  if (size > MAX_ENTRY) throw new RangeError("container/1 entries are limited to 8 GiB");
+  if (size > MAX_ENTRY) throw new RangeError("container entries are limited to 8 GiB");
   const h = new Uint8Array(BLOCK);
   const nameBytes = utf8(name);
   if (nameBytes.length > 100) throw new RangeError("ustar name too long");
@@ -325,7 +326,7 @@ function parseTar(bytes: Uint8Array): TarEntry[] | null {
 // Placement registry
 // ---------------------------------------------------------------------------
 
-export type PlacementId = "trailer/1" | "container/1" | "produced/1" | "set/1";
+export type PlacementId = "trailer/1" | "container/1" | "container/2" | "produced/1" | "set/1" | "set/2";
 
 export interface Located {
   /** The commitment found in the fused bytes. */
@@ -336,6 +337,12 @@ export interface Located {
   originalBytes?: Uint8Array;
 }
 
+/** What a Form A or B placement puts around the original: fused = prefix, original, suffix. */
+export interface FusedFrame {
+  prefix: Uint8Array;
+  suffix: Uint8Array;
+}
+
 export interface Placement {
   readonly id: PlacementId;
   /** A: in-file placement of an existing original; B: container; C: produced artifact. */
@@ -346,6 +353,19 @@ export interface Placement {
   build(input: { original?: Uint8Array; originDigest?: Uint8Array; commitment: Uint8Array }): Uint8Array;
   /** Find the commitment in fused bytes, or null when the marker is absent or malformed. */
   locate(fused: Uint8Array): Located | null;
+  /**
+   * Forms A and B: the bytes around the original, such that
+   * build({original, originDigest, commitment}) is exactly prefix, original,
+   * suffix. A producer that streams the original once can hash the prefix and
+   * the original as they pass and finish with the suffix later.
+   */
+  frame?(input: { originalSize: number; originDigest: Uint8Array; commitment: Uint8Array }): FusedFrame;
+  /**
+   * The prefix when it depends on the original's size alone, so a scanner can
+   * hash it before any slot exists; null when the prefix carries the
+   * commitment (container/1) and the fused digest needs the bytes again.
+   */
+  scanPrefix?(originalSize: number): Uint8Array | null;
 }
 
 const trailer1: Placement = {
@@ -364,6 +384,13 @@ const trailer1: Placement = {
     if (!t.subarray(8, 16).every((b) => b === 0)) return null;
     return { commitment: new Uint8Array(t.subarray(16, 48)), originalBytes: fused.subarray(0, fused.length - TRAILER_LENGTH) };
   },
+  frame({ commitment }) {
+    if (commitment.length !== 32) throw new TypeError("commitment must be 32 bytes");
+    return { prefix: new Uint8Array(0), suffix: concat(utf8(TRAILER_MAGIC), new Uint8Array(8), commitment) };
+  },
+  scanPrefix() {
+    return new Uint8Array(0);
+  },
 };
 
 const container1: Placement = {
@@ -387,6 +414,66 @@ const container1: Placement = {
     if (!bytesEqual(rebuilt, fused)) return null;
     return { commitment: payload.commitment, originDigest: payload.originDigest, originalBytes: o.data };
   },
+  frame({ originalSize, originDigest, commitment }) {
+    const manifest = buildFusePayload(commitment, originDigest);
+    return {
+      prefix: concat(ustarHeader(CONTAINER_MANIFEST_PATH, manifest.length), manifest, new Uint8Array(padTo(manifest.length)), ustarHeader(CONTAINER_ORIGINAL_PATH, originalSize)),
+      suffix: concat(new Uint8Array(padTo(originalSize)), new Uint8Array(BLOCK * 2)),
+    };
+  },
+  scanPrefix() {
+    // The manifest, and so the commitment, comes before the original.
+    return null;
+  },
+};
+
+/**
+ * container/2: the same archive with the original FIRST. Everything before
+ * the original's bytes is its ustar header, which depends on the size alone,
+ * so a scanner that hashes header and original as the file streams by can
+ * finish the fused digest later with the manifest for whatever slot the
+ * set is made under, without reading the file again. Any bytes fit: the
+ * original stays byte-exact inside, and the archive is a plain tar.
+ */
+function buildContainer2(original: Uint8Array, manifest: Uint8Array): Uint8Array {
+  return concat(
+    ustarHeader(CONTAINER_ORIGINAL_PATH, original.length), original, new Uint8Array(padTo(original.length)),
+    ustarHeader(CONTAINER_MANIFEST_PATH, manifest.length), manifest, new Uint8Array(padTo(manifest.length)),
+    new Uint8Array(BLOCK * 2),
+  );
+}
+
+const container2: Placement = {
+  id: "container/2",
+  form: "B",
+  byteExact: true,
+  build({ original, originDigest, commitment }) {
+    if (original === undefined) throw new TypeError("container/2 requires the original bytes");
+    const digest = originDigest ?? sha256(original);
+    return buildContainer2(original, buildFusePayload(commitment, digest));
+  },
+  locate(fused) {
+    const entries = parseTar(fused);
+    if (entries === null || entries.length !== 2) return null;
+    const [o, m] = entries as [TarEntry, TarEntry];
+    if (o.name !== CONTAINER_ORIGINAL_PATH || m.name !== CONTAINER_MANIFEST_PATH) return null;
+    const payload = parseFusePayload(m.data);
+    if (payload === null || payload.originDigest === undefined) return null;
+    // The archive must be the one this module would build: headers included.
+    const rebuilt = buildContainer2(o.data, m.data);
+    if (!bytesEqual(rebuilt, fused)) return null;
+    return { commitment: payload.commitment, originDigest: payload.originDigest, originalBytes: o.data };
+  },
+  frame({ originalSize, originDigest, commitment }) {
+    const manifest = buildFusePayload(commitment, originDigest);
+    return {
+      prefix: ustarHeader(CONTAINER_ORIGINAL_PATH, originalSize),
+      suffix: concat(new Uint8Array(padTo(originalSize)), ustarHeader(CONTAINER_MANIFEST_PATH, manifest.length), manifest, new Uint8Array(padTo(manifest.length)), new Uint8Array(BLOCK * 2)),
+    };
+  },
+  scanPrefix(originalSize) {
+    return ustarHeader(CONTAINER_ORIGINAL_PATH, originalSize);
+  },
 };
 
 const produced1: Placement = {
@@ -407,7 +494,7 @@ const produced1: Placement = {
 };
 
 /** Registered placements in the fixed order a verifier tries them when none is declared. */
-export const PLACEMENTS: readonly Placement[] = Object.freeze([trailer1, container1, produced1]);
+export const PLACEMENTS: readonly Placement[] = Object.freeze([trailer1, container1, container2, produced1]);
 
 // ---------------------------------------------------------------------------
 // Set manifest (placement set/1): N files fused under ONE slot
@@ -481,7 +568,7 @@ export function buildSetManifest(commitment: Uint8Array, members: readonly SetMe
     if (m.artifact.length !== 32) throw new TypeError("member artifact digest must be 32 bytes");
     if (m.origin.length !== 32) throw new TypeError("member origin digest must be 32 bytes");
     if (!PLACEMENT_ID_PATTERN.test(m.placement)) throw new TypeError(`member placement "${m.placement}" is not a placement id`);
-    if (m.placement === SET_PLACEMENT_ID) throw new TypeError("a set cannot list a set as a member");
+    if (m.placement === SET_PLACEMENT_ID || m.placement === SET2_PLACEMENT_ID) throw new TypeError("a set cannot list a set as a member");
     const artifact = bytesToHex(m.artifact);
     if (seen.has(artifact)) throw new TypeError(`duplicate member artifact digest ${artifact}`);
     seen.add(artifact);
@@ -545,7 +632,7 @@ export function parseSetManifest(bytes: Uint8Array): { commitment: Uint8Array; m
     const origin = readDigestField(row["origin"]);
     const placement = row["placement"];
     if (artifact === null || origin === null || typeof placement !== "string") return null;
-    if (!PLACEMENT_ID_PATTERN.test(placement) || placement === SET_PLACEMENT_ID) return null;
+    if (!PLACEMENT_ID_PATTERN.test(placement) || placement === SET_PLACEMENT_ID || placement === SET2_PLACEMENT_ID) return null;
     members.push({ artifact, origin, placement });
   }
   let rebuilt: Uint8Array;
@@ -589,15 +676,225 @@ const set1: Placement = {
   },
 };
 
+// ---------------------------------------------------------------------------
+// Merkle set (placement set/2): N files under ONE slot, any N
+// ---------------------------------------------------------------------------
+//
+// set/1 commits the whole member list, which is what caps it: the list rides
+// in the commit body and in every copy of the proof. set/2 commits the ROOT
+// of a Merkle tree over the same rows, so the committed artifact is a few
+// hundred bytes whatever N is, and a member proves its place with a path of
+// ceil(log2 N) siblings. The floor is unchanged: every member's fused bytes
+// still carry the slot's commitment through its own placement. Membership
+// and floor stay inseparable in verifyFuseMember; what changes is where the
+// list lives (with the producer and the reader that serves it) and what a
+// member carries (its row, its index and its path, see SetMemberProof).
+//
+// Leaves are the canonical row bytes (the same {artifact, origin, placement}
+// row set/1 lists), hashed with the RFC 6962 leaf prefix, in the same strict
+// order as a set/1 manifest: ascending by artifact digest, no duplicates.
+// So one root stands for exactly one member list, and a reader holding the
+// list can rebuild the tree; a reader holding one member needs its path.
+
+export const SET2_PLACEMENT_ID = "set/2" as const;
+
+/** The proof.metadata key under which a member's own evidence (row, index, count, path) may ride, UNSIGNED, beside the root document. */
+export const SET_MEMBER_METADATA_KEY = `${FUSE_PROFILE}/member` as const;
+
+/** The most members one set/2 tree lists. A limit stated plainly, not a design constant: the tree and the paths are fine far beyond it. */
+export const MAX_SET2_MEMBERS = 1_000_000;
+
+/** The root document as JSON: the type of the value under proof.metadata[SET_METADATA_KEY] for a set/2 proof. */
+export interface SetRoot {
+  count: number;
+  placement: typeof SET2_PLACEMENT_ID;
+  root: { algorithm: "sha256"; digest: string };
+  slotCommitment: { algorithm: "sha256"; digest: string };
+  type: typeof FUSE_PROFILE;
+}
+
+/** One member's evidence as JSON: its row, its leaf index, the tree size, and the sibling path from the leaf up. */
+export interface SetMemberProof {
+  count: number;
+  index: number;
+  member: SetManifest["members"][number];
+  path: string[];
+  placement: typeof SET2_PLACEMENT_ID;
+  type: typeof FUSE_PROFILE;
+}
+
+/** The canonical bytes of one row, exactly as a set/1 manifest lists it; the leaf a set/2 tree hashes. */
+export function canonicalSetRow(m: SetMember): Uint8Array {
+  if (m.artifact.length !== 32) throw new TypeError("member artifact digest must be 32 bytes");
+  if (m.origin.length !== 32) throw new TypeError("member origin digest must be 32 bytes");
+  if (!PLACEMENT_ID_PATTERN.test(m.placement) || m.placement === SET_PLACEMENT_ID || m.placement === SET2_PLACEMENT_ID) throw new TypeError(`member placement "${m.placement}" is not a member placement id`);
+  return canonicalize({
+    artifact: { algorithm: "sha256", digest: bytesToHex(m.artifact) },
+    origin: { algorithm: "sha256", digest: bytesToHex(m.origin) },
+    placement: m.placement,
+  } as unknown as BitGraphProof);
+}
+
+/** The leaf hash of one row: SHA-256(0x00, canonical row bytes). */
+export function setLeaf(m: SetMember): Uint8Array {
+  return merkleLeafHash(canonicalSetRow(m));
+}
+
+/**
+ * Order members as a set/2 tree lists them: strictly ascending by artifact
+ * digest, no duplicate artifact. Throws on a duplicate, an empty list, or a
+ * malformed row, like buildSetManifest.
+ */
+export function sortSetMembers(members: readonly SetMember[]): SetMember[] {
+  if (members.length === 0) throw new TypeError("a set lists at least one member");
+  const sorted = [...members].sort((a, b) => {
+    const x = bytesToHex(a.artifact);
+    const y = bytesToHex(b.artifact);
+    return x < y ? -1 : x > y ? 1 : 0;
+  });
+  for (let i = 0; i < sorted.length; i++) {
+    canonicalSetRow(sorted[i]!);
+    if (i > 0 && bytesEqual(sorted[i]!.artifact, sorted[i - 1]!.artifact)) throw new TypeError(`duplicate member artifact digest ${bytesToHex(sorted[i]!.artifact)}`);
+  }
+  return sorted;
+}
+
+/** The tree over a member list, in tree order (sortSetMembers): the sorted rows, their leaf hashes, the root, and every member's path on demand. */
+export function buildSetTree(members: readonly SetMember[]): { sorted: SetMember[]; leaves: Uint8Array[]; root: Uint8Array; tree: MerkleTree } {
+  const sorted = sortSetMembers(members);
+  const leaves = sorted.map(setLeaf);
+  const tree = new MerkleTree(leaves);
+  return { sorted, leaves, root: tree.root, tree };
+}
+
+/** The inclusion path of the member at `index` in tree order. */
+export function setMemberPath(tree: MerkleTree, index: number): Uint8Array[] {
+  return tree.path(index);
+}
+
+/** Build the canonical set/2 root document bytes: the committed artifact. */
+export function buildSetRoot(commitment: Uint8Array, count: number, root: Uint8Array): Uint8Array {
+  if (commitment.length !== 32) throw new TypeError("commitment must be 32 bytes");
+  if (root.length !== 32) throw new TypeError("root must be 32 bytes");
+  if (!Number.isInteger(count) || count < 1 || count > MAX_SET2_MEMBERS) throw new TypeError(`count must be an integer from 1 to ${MAX_SET2_MEMBERS}`);
+  const doc: SetRoot = {
+    count,
+    placement: SET2_PLACEMENT_ID,
+    root: { algorithm: "sha256", digest: bytesToHex(root) },
+    slotCommitment: { algorithm: "sha256", digest: bytesToHex(commitment) },
+    type: FUSE_PROFILE,
+  };
+  return canonicalize(doc as unknown as BitGraphProof);
+}
+
+/** Strict parse of set/2 root document bytes: exactly the five keys, the literals, 32-byte digests, a count in range, byte-equal to its own rebuild. */
+export function parseSetRoot(bytes: Uint8Array): { commitment: Uint8Array; count: number; root: Uint8Array } | null {
+  let text: string;
+  try {
+    text = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
+  } catch {
+    return null;
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return null;
+  }
+  if (!isPlainObject(parsed)) return null;
+  if (Object.keys(parsed).sort().join(",") !== "count,placement,root,slotCommitment,type") return null;
+  if (parsed["type"] !== FUSE_PROFILE || parsed["placement"] !== SET2_PLACEMENT_ID) return null;
+  const count = parsed["count"];
+  if (typeof count !== "number" || !Number.isInteger(count) || count < 1 || count > MAX_SET2_MEMBERS) return null;
+  const commitment = readDigestField(parsed["slotCommitment"]);
+  const root = readDigestField(parsed["root"]);
+  if (commitment === null || root === null) return null;
+  let rebuilt: Uint8Array;
+  try {
+    rebuilt = buildSetRoot(commitment, count, root);
+  } catch {
+    return null;
+  }
+  if (!bytesEqual(rebuilt, bytes)) return null;
+  return { commitment, count, root };
+}
+
+/** Build a member's evidence object (JSON shape) from tree order. */
+export function buildSetMemberProof(member: SetMember, index: number, count: number, path: readonly Uint8Array[]): SetMemberProof {
+  if (!Number.isInteger(index) || !Number.isInteger(count) || count < 1 || index < 0 || index >= count) throw new RangeError("member index out of range");
+  canonicalSetRow(member);
+  return {
+    count,
+    index,
+    member: {
+      artifact: { algorithm: "sha256", digest: bytesToHex(member.artifact) },
+      origin: { algorithm: "sha256", digest: bytesToHex(member.origin) },
+      placement: member.placement,
+    },
+    path: path.map((p) => {
+      if (p.length !== 32) throw new TypeError("a path node is 32 bytes");
+      return bytesToHex(p);
+    }),
+    placement: SET2_PLACEMENT_ID,
+    type: FUSE_PROFILE,
+  };
+}
+
+/** Strict read of a member's evidence from a parsed JSON value: shape, literals, 32-byte hex digests and path nodes, index within count. Null on any deviation. UNBOUND: nothing here touches a root. */
+export function parseSetMemberProof(value: unknown): { member: SetMember; index: number; count: number; path: Uint8Array[] } | null {
+  if (!isPlainObject(value)) return null;
+  if (Object.keys(value).sort().join(",") !== "count,index,member,path,placement,type") return null;
+  if (value["type"] !== FUSE_PROFILE || value["placement"] !== SET2_PLACEMENT_ID) return null;
+  const count = value["count"];
+  const index = value["index"];
+  if (typeof count !== "number" || !Number.isInteger(count) || count < 1 || count > MAX_SET2_MEMBERS) return null;
+  if (typeof index !== "number" || !Number.isInteger(index) || index < 0 || index >= count) return null;
+  const row = value["member"];
+  if (!isPlainObject(row) || Object.keys(row).sort().join(",") !== "artifact,origin,placement") return null;
+  const artifact = readDigestField(row["artifact"]);
+  const origin = readDigestField(row["origin"]);
+  const placement = row["placement"];
+  if (artifact === null || origin === null || typeof placement !== "string") return null;
+  if (!PLACEMENT_ID_PATTERN.test(placement) || placement === SET_PLACEMENT_ID || placement === SET2_PLACEMENT_ID) return null;
+  const list = value["path"];
+  if (!Array.isArray(list)) return null;
+  const path: Uint8Array[] = [];
+  for (const node of list as unknown[]) {
+    if (typeof node !== "string" || !/^[0-9a-f]{64}$/.test(node)) return null;
+    const bytes = hexToBytes(node);
+    if (bytes === null) return null;
+    path.push(bytes);
+  }
+  return { member: { artifact, origin, placement }, index, count, path };
+}
+
+/** Recompute a root from a member's leaf and path; null when the path does not fit. */
+export function setRootFromMember(member: SetMember, index: number, count: number, path: readonly Uint8Array[]): Uint8Array | null {
+  return merkleRootFromPath(setLeaf(member), index, count, path);
+}
+
+const set2: Placement = {
+  id: SET2_PLACEMENT_ID,
+  form: "C",
+  byteExact: false,
+  build() {
+    throw new TypeError("set/2 is built with buildSetRoot(commitment, count, root)");
+  },
+  locate(fused) {
+    const doc = parseSetRoot(fused);
+    return doc === null ? null : { commitment: doc.commitment };
+  },
+};
+
 /**
- * Resolve a placement by id. set/1 resolves here but is NOT in PLACEMENTS:
+ * Resolve a placement by id. set/1 and set/2 resolve here but are NOT in PLACEMENTS:
  * the undeclared scan is for bytes whose placement was not declared, whereas
  * a set manifest is identified by hashing to the signed artifact digest and
  * by its signed title, so the scan order of every existing fixture is
  * literally unchanged.
  */
 export function getPlacement(id: string): Placement | undefined {
-  return [...PLACEMENTS, set1].find((p) => p.id === id);
+  return [...PLACEMENTS, set1, set2].find((p) => p.id === id);
 }
 
 // ---------------------------------------------------------------------------
@@ -612,7 +909,7 @@ export function getPlacement(id: string): Placement | undefined {
  */
 export function fuseAttribution(placement: PlacementId, originDigest?: Uint8Array): Attribution {
   if (originDigest !== undefined && originDigest.length !== 32) throw new TypeError("originDigest must be 32 bytes");
-  if (placement === SET_PLACEMENT_ID && originDigest !== undefined) throw new TypeError("set/1 has no single origin; a set marker carries no origin digest");
+  if ((placement === SET_PLACEMENT_ID || placement === SET2_PLACEMENT_ID) && originDigest !== undefined) throw new TypeError(`${placement} has no single origin; a set marker carries no origin digest`);
   return {
     name: FUSE_ATTRIBUTION_NAME,
     title: placement,

package/src/index.ts

@@ -64,8 +64,11 @@ export {
   hexToBytes,
   bytesEqual,
 } from "./fuse.js";
-export type { PlacementId, Placement, Located, FusePayload, FuseFrame, FuseMarker, MarkerSource, SetMember, SetManifest } from "./fuse.js";
+export type { PlacementId, Placement, Located, FusePayload, FuseFrame, FuseMarker, MarkerSource, SetMember, SetManifest, FusedFrame } from "./fuse.js";
 export { verifyFuse, assembledAfterCommit } from "./fuse-verify.js";
 export type { FuseCategory, FuseSpan, FuseVerifyResult, FuseVerifyOptions } from "./fuse-verify.js";
 export { verifyFuseMember } from "./fuse-member.js";
 export type { FuseMemberCategory, FuseSetEvidence, FuseMemberOptions, FuseMemberResult } from "./fuse-member.js";
+export { SET2_PLACEMENT_ID, SET_MEMBER_METADATA_KEY, MAX_SET2_MEMBERS, canonicalSetRow, setLeaf, sortSetMembers, buildSetTree, setMemberPath, buildSetRoot, parseSetRoot, buildSetMemberProof, parseSetMemberProof, setRootFromMember } from "./fuse.js";
+export type { SetRoot, SetMemberProof } from "./fuse.js";
+export { merkleLeafHash, merkleNodeHash, merkleRoot, merklePath, merkleRootFromPath, MerkleTree } from "./fuse-merkle.js";