@mikeargento/bitgraph 1.10.1 → 1.12.0

package/src/fuse.ts

@@ -1,6 +1,16 @@
 // Copyright (c) Argento Computing Inc. All rights reserved. See LICENSE.
 
 /**
+ * fuseTree(members, options): the producer of every NEW BitGraph since
+ * 2026-10-03 (tree/1). One position, one Merkle tree of 1 to N files; a
+ * single file is a tree of one. Each file is a 65-byte leaf (placement code,
+ * committed digest, origin digest); the committed artifact is the 84-byte
+ * root document; the signed attribution is bitgraph-fuse/2 with title
+ * "tree/1" and the spec's hash as its message. tree/1 needs the floor the
+ * allocation returns (enclave v9 and later): without it nothing is made.
+ * fuse() and fuseSet() below are superseded by it and kept so code that
+ * imports them keeps working; what they made stays readable.
+ *
  * fuse(builder, options): the producer interface of the bitgraph-fuse/1
  * profile (working name; outwardly this is simply BitGraph).
  *
@@ -63,8 +73,21 @@ import {
   verifyFuse,
   verifyFuseMember,
   base64ToBytes,
+  buildTree,
+  buildTreeMemberEvidence,
+  buildTreeRootDocument,
+  currentTreeSpecHash,
+  leafCodeOf,
+  LEAF_AS_IS,
+  MAX_TREE_LEAVES,
+  readTreeMetadata,
+  TREE_METADATA_KEY,
+  treeAttribution,
+  treeRootFromMember,
+  verifyTreeMember,
+  MAX_CONTAINER_ENTRY_BYTES,
 } from "@mikeargento/bitgraph-verify";
-import type { BitGraphProof, FuseFrame, FuseMemberResult, FuseVerifyResult, Located, Placement, PlacementId, SetManifest, SetMember, SetMemberProof, SetRoot, SlotAllocation } from "@mikeargento/bitgraph-verify";
+import type { BitGraphProof, FuseFrame, FuseMemberResult, FuseVerifyResult, Located, MerkleTree, Placement, PlacementId, SetManifest, SetMember, SetMemberProof, SetRoot, SlotAllocation, TreeLeaf, TreeMemberEvidence, TreeVerifyResult } from "@mikeargento/bitgraph-verify";
 
 /**
  * SHA-256 over bytes: the platform's native hasher when one is present
@@ -94,15 +117,36 @@ export interface AnchorMark {
   blockHash: string;
 }
 
+/** The Base floor an enclave v10 allocation hands back: the one it signs at commit as commit.slotFloor. */
+export interface BaseFloorMark {
+  chain: "base";
+  evmChainId: 8453;
+  blockNumber: number;
+  blockHash: string;
+  blockTimestamp: number;
+}
+
+/** Either floor an allocation can return. A Base floor makes a fuse/3 commitment, an Ethereum anchor a fuse/2 one. */
+export type FloorMark = AnchorMark | BaseFloorMark;
+
+export function isBaseFloorMark(x: unknown): x is BaseFloorMark {
+  if (x === null || typeof x !== "object" || Array.isArray(x)) return false;
+  const a = x as Record<string, unknown>;
+  return a.chain === "base" && a.evmChainId === 8453
+    && typeof a.blockNumber === "number" && Number.isSafeInteger(a.blockNumber) && a.blockNumber > 0
+    && typeof a.blockHash === "string" && /^0x[0-9a-f]{64}$/.test(a.blockHash)
+    && typeof a.blockTimestamp === "number" && Number.isSafeInteger(a.blockTimestamp);
+}
+
 /** What the builder receives. The raw nonce is deliberately absent. */
 export interface BuilderInput {
-  /** 32-byte commitment to the signed slot record (bitgraph-fuse/2 also binds the floor block). Write this into the artifact. */
+  /** 32-byte commitment to the signed slot record (fuse/2 and fuse/3 also bind the floor block). Write this into the artifact. */
   commitment: Uint8Array;
   commitmentHex: string;
-  /** Which commitment this is: 2 when the boundary returned its floor anchor (enclave v9 and later), else 1. */
-  fuseVersion: 1 | 2;
-  /** The floor bound into a fuse/2 commitment, when there is one. */
-  floor?: AnchorMark;
+  /** Which commitment this is: 3 for a Base floor (enclave v10), 2 for an Ethereum floor anchor (v9), else 1. */
+  fuseVersion: 1 | 2 | 3;
+  /** The floor bound into the commitment, when there is one. */
+  floor?: FloorMark;
   /** The origin digest, when the fused artifact names a source. */
   originDigest?: Uint8Array;
   /** The signed slot record, for producers that want to embed its fields. Contains the nonce: do not copy it into the artifact. */
@@ -172,7 +216,9 @@ export type FuseErrorCode =
   | "network"
   | "slot-mismatch"
   | "verification-failed"
-  | "transport";
+  | "transport"
+  /** tree/1 only: the allocation returned no floor anchor (a boundary before enclave v9), so no tree/1 commitment can be made. */
+  | "floor-missing";
 
 export class FuseError extends Error {
   readonly code: FuseErrorCode;
@@ -343,11 +389,12 @@ function isAnchorMark(x: unknown): x is AnchorMark {
 
 /**
  * 1. nonce. The signed slot record from the boundary; it must sit on the
- * anchored chain. Since enclave v9 the response also carries the floor anchor
- * the boundary will sign at commit; with it the producer makes a
- * bitgraph-fuse/2 commitment, without it a fuse/1 one.
+ * anchored chain. The response also carries the floor the boundary will sign
+ * at commit: a Base block since enclave v10 (a fuse/3 commitment), an Ethereum
+ * anchor on v9 (fuse/2); without one the producer makes a fuse/1 commitment.
+ * A response carrying both is refused: a proof has one floor.
  */
-async function allocateSlot(t: BoundTransport): Promise<{ slot: SlotAllocation; anchor: AnchorMark | null }> {
+async function allocateSlot(t: BoundTransport): Promise<{ slot: SlotAllocation; anchor: FloorMark | null }> {
   const alloc = await request(t, t.allocatePath, { method: "POST", body: {} });
   if (alloc.status === 503 && codeOf(alloc.json) === "tee-restarting") throw new FuseError("tee-restarting", messageOf(alloc.json, "the boundary is restarting"), 503);
   if (alloc.status !== 200) throw new FuseError("allocate-failed", messageOf(alloc.json, `allocation failed (${alloc.status})`), alloc.status);
@@ -356,7 +403,11 @@ async function allocateSlot(t: BoundTransport): Promise<{ slot: SlotAllocation;
   if (!isSlotRecord(slot) || slotId !== slot.nonceB64) throw new FuseError("allocate-failed", "the allocation response is not a slot record", alloc.status);
   if (slot.chainId !== "bitgraph:main") throw new FuseError("allocate-failed", "the slot is not on the anchored chain; a fused floor needs bitgraph:main");
   const anchorRaw = (alloc.json as { anchor?: unknown } | null)?.anchor;
-  return { slot, anchor: isAnchorMark(anchorRaw) ? anchorRaw : null };
+  const floorRaw = (alloc.json as { floor?: unknown } | null)?.floor;
+  const eth = isAnchorMark(anchorRaw) ? anchorRaw : null;
+  const base = isBaseFloorMark(floorRaw) ? floorRaw : null;
+  if (eth && base) throw new FuseError("allocate-failed", "the allocation returned two floors (an Ethereum anchor and a Base block); a proof has one, so nothing was bound");
+  return { slot, anchor: base ?? eth };
 }
 
 /**
@@ -368,7 +419,12 @@ function requireCommitment(placement: Placement, fused: Uint8Array, commitment:
   const located = placement.locate(fused);
   if (located === null || bytesToHex(located.commitment) !== bytesToHex(commitment)) {
     const label = member !== null ? `member ${member}: ` : "";
-    throw new FuseError("commitment-missing", `${label}the fused bytes do not carry the ${placement.id} commitment; nothing was committed and the slot will expire`, null, member);
+    // A container is located only when its archive, the original inside it
+    // (hashed against the origin it declares) and the commitment all hold.
+    const what = placement.form === "B"
+      ? `are not a valid ${placement.id} carrying this position's commitment: the archive, the original inside it or the commitment does not hold`
+      : `do not carry the ${placement.id} commitment`;
+    throw new FuseError("commitment-missing", `${label}the fused bytes ${what}; nothing was committed and the slot will expire`, null, member);
   }
   return located;
 }
@@ -420,6 +476,9 @@ async function commitUnderSlot(t: BoundTransport, body: Record<string, unknown>,
  * Allocate, fuse, hash, fill. Returns the Frame with the unchanged proof, or
  * throws a FuseError; it never returns an ordinary recording in place of a
  * fused one.
+ *
+ * Superseded by fuseTree (tree/1, 2026-10-03): a new BitGraph of one file is
+ * a tree of one. Kept so code that imports it keeps working.
  */
 export async function fuse(builder: FuseBuilder, options: FuseOptions): Promise<FuseResult> {
   const placement = getPlacement(options.placement);
@@ -459,7 +518,8 @@ export async function fuse(builder: FuseBuilder, options: FuseOptions): Promise<
     chainId: "bitgraph:main",
     attribution,
     // fuse/2: the boundary checks the bound floor against its ledger before spending the slot.
-    ...(version === 2 ? { anchor } : {}),
+    // fuse/3: the bound Base floor, so the boundary can check it is the one it handed out.
+    ...(version === 2 ? { anchor } : version === 3 ? { floor: anchor } : {}),
   };
   if (options.agency !== undefined) body.agency = options.agency;
   const { proof, recovered } = await commitUnderSlot(t, body, artifactDigestB64, slot);
@@ -510,10 +570,10 @@ export type SetMemberPlacement = "trailer/1" | "container/1" | "container/2";
 
 /** What a hashed member's fused digest is computed for: the held slot and its commitment. */
 export interface FusedDigestInput {
-  /** Which commitment this is: 2 when the boundary returned its floor anchor, else 1. */
-  fuseVersion: 1 | 2;
-  /** The floor bound into a fuse/2 commitment, when there is one. */
-  floor?: AnchorMark;
+  /** Which commitment this is: 3 for a Base floor, 2 for an Ethereum floor anchor, else 1. */
+  fuseVersion: 1 | 2 | 3;
+  /** The floor bound into the commitment, when there is one. */
+  floor?: FloorMark;
   commitment: Uint8Array;
   commitmentHex: string;
   slot: SlotAllocation;
@@ -681,6 +741,9 @@ export interface FuseSetResult {
  * allocates a second slot. Members may be given as bytes, as a loader read
  * one at a time after the slot is held, or as a digest the caller finishes
  * itself; one set may mix them.
+ *
+ * Superseded by fuseTree (tree/1, 2026-10-03): N files are one tree under one
+ * position. Kept so code that imports it keeps working.
  */
 export async function fuseSet(members: readonly FuseSetMember[], options: FuseSetOptions = {}): Promise<FuseSetResult> {
   // 0. validate, before any request. A refusal here burns nothing.
@@ -851,7 +914,7 @@ export async function fuseSet(members: readonly FuseSetMember[], options: FuseSe
     chainId: "bitgraph:main",
     attribution: fuseAttribution(setKind === "set/1" ? SET_PLACEMENT_ID_LOCAL : SET2_PLACEMENT_ID, undefined, version),
     metadata: { [SET_METADATA_KEY]: manifest },
-    ...(version === 2 ? { anchor } : {}),
+    ...(version === 2 ? { anchor } : version === 3 ? { floor: anchor } : {}),
   };
   if (options.agency !== undefined) body.agency = options.agency;
   report("commit", 0, 1);
@@ -954,6 +1017,445 @@ export async function fuseSet(members: readonly FuseSetMember[], options: FuseSe
   };
 }
 
+// ---------------------------------------------------------------------------
+// tree/1: every BitGraph is a Merkle tree under one position (2026-10-03)
+// ---------------------------------------------------------------------------
+
+/** How a file goes into a tree: as is (0x00), or placed into committed bytes that carry the commitment. */
+export type TreeMemberPlacement = "as-is" | SetMemberPlacement;
+
+/**
+ * The placement a file takes in a tree, from its size and its first bytes
+ * (every magic number placementForBytes reads sits in the first 16): trailer/1
+ * for the formats that ignore trailing bytes, container/2 for everything else,
+ * except that a file too large for a ustar entry (MAX_CONTAINER_ENTRY_BYTES,
+ * 8 GiB - 1, SPEC 7.3) takes trailer/1 whatever its bytes: the committed
+ * bytes are virtual, so a trailer costs the file nothing. Never as is: that
+ * is the user's choice, and no producer decides it by size (SPEC 7.5, 8.1).
+ */
+export function treePlacementFor(size: number, head: Uint8Array): "trailer/1" | "container/2" {
+  return size > MAX_CONTAINER_ENTRY_BYTES ? "trailer/1" : placementForBytes(head);
+}
+
+/** A tree member given as bytes: hashed, placed (unless as is), checked and hashed again by the core. */
+export interface FuseTreeBytesMember {
+  original: Uint8Array;
+  /** Default: treePlacementFor(original.length, original). As is is asked for by name, never by size. */
+  placement?: TreeMemberPlacement;
+  /** Unsigned and informational: the owner's export lists it beside the leaf. */
+  name?: string;
+  /** Placed members only. Default: the placement's own build. The locate and origin guards run regardless. */
+  builder?: FuseBuilder;
+}
+
+/** A placed member read only when it is its turn, after the slot is held, and checked against its named digest. */
+export interface FuseTreeLoadedMember {
+  load: () => Promise<Uint8Array> | Uint8Array;
+  originDigest: Uint8Array;
+  placement: SetMemberPlacement;
+  name?: string;
+  builder?: FuseBuilder;
+}
+
+/**
+ * A placed member whose committed digest the caller finishes itself for the
+ * held commitment (a scanner's saved hash state finished with the placement's
+ * suffix). The core never sees its bytes.
+ */
+export interface FuseTreeHashedMember {
+  originDigest: Uint8Array;
+  placement: SetMemberPlacement;
+  fusedDigest: (input: FusedDigestInput) => Promise<Uint8Array> | Uint8Array;
+  name?: string;
+}
+
+/** A file that goes in as is, given by its digest alone: nothing is read, placed or loaded. */
+export interface FuseTreeAsIsMember {
+  originDigest: Uint8Array;
+  placement: "as-is";
+  name?: string;
+}
+
+export type FuseTreeMember = FuseTreeBytesMember | FuseTreeLoadedMember | FuseTreeHashedMember | FuseTreeAsIsMember;
+
+/** Progress, in fuseSet's phases: hash (before any request), fuse (each leaf, after the slot is held), tree, commit, verify (only with verifyMembers). */
+export type FuseTreeProgress = FuseSetProgress;
+
+export interface FuseTreeOptions {
+  /** Return each member's committed bytes (for as is, the original itself) when they passed through the core. Default false: they are virtual, rebuilt from the original and the proof. */
+  keepCommitted?: boolean;
+  /**
+   * Run verifyTreeMember over every member's committed bytes after the
+   * commit and return each verdict. Default false: every member's leaf is
+   * bound to the returned proof by its path to the verified root, which
+   * reads no bytes. A hashed member, or an as-is member given by its digest,
+   * has no bytes here and is refused before any request.
+   */
+  verifyMembers?: boolean;
+  /** Called as the tree advances. A throw inside it is ignored: a progress hook never changes the outcome. */
+  onProgress?: (progress: FuseTreeProgress) => void;
+  /** Actor-bound commits: an agency envelope passed through untouched. */
+  agency?: unknown;
+  transport?: FuseTransport;
+}
+
+export interface FuseTreeMemberResult {
+  /** The caller's index into members. */
+  index: number;
+  /** The member's leaf in the sorted tree: its evidence's index. */
+  leafIndex: number;
+  placement: TreeMemberPlacement;
+  /** The leaf's placement code: 0x00 as is, 0x01 trailer/1, 0x02 container/1, 0x03 container/2. */
+  code: number;
+  originDigestB64: string;
+  /** SHA-256 of the committed bytes: the leaf's artifact. For as is, the file's own digest. */
+  artifactDigestB64: string;
+  name: string | null;
+  /** Present only with keepCommitted, for a member whose bytes passed through the core (never a hashed member, nor an as-is member given by its digest). */
+  committedBytes?: Uint8Array;
+  /** Present only with verifyMembers: the verifier's verdict on the committed bytes, TREE_MEMBER_DIRECT (TREE_MEMBER_AS_IS for as is) on success. */
+  verification?: TreeVerifyResult;
+}
+
+export interface FuseTreeResult {
+  proof: BitGraphProof;
+  /** The committed artifact: the 84-byte root document. Its SHA-256 is the signed digest; every export carries it. */
+  rootDocument: Uint8Array;
+  /** SHA-256 of rootDocument, standard base64; equals proof.artifact.digestB64. */
+  artifactDigestB64: string;
+  count: number;
+  /** The tree's root, lowercase hex. */
+  rootHex: string;
+  /** commitment/2 or /3, which every placed member's committed bytes carry. committedBytesFor(member.code, original, commitment) rebuilds them. */
+  commitment: Uint8Array;
+  /** The floor block the commitment binds, as the proof signs it (commit.slotAnchor or commit.slotFloor). */
+  floor: FloorMark;
+  /** The spec hash the signed attribution pins, standard base64. */
+  specHashB64: string;
+  /** Every leaf, in tree order (strictly ascending artifact digest). */
+  leaves: TreeLeaf[];
+  /** The tree over those leaves: tree.path(k) is leaf k's path. */
+  tree: MerkleTree;
+  /** In the caller's order. */
+  members: FuseTreeMemberResult[];
+  /** A member's evidence (TreeMemberEvidence JSON) by the caller's index, built on demand so a large tree holds no path it is not asked for. */
+  memberEvidence: (index: number) => TreeMemberEvidence;
+  /** True when the commit response was lost and the proof was read back by the root document's digest. */
+  recovered: boolean;
+  /** True only when the proof's metadata carries this root document. Absent is normal for a boundary that drops metadata; exports carry the document either way. */
+  rootDocumentEchoed: boolean;
+  /** verifyTreeMember over the proof and the root document: TREE_ROOT_VALID on success. */
+  verification: TreeVerifyResult;
+}
+
+function compareDigests(a: Uint8Array, b: Uint8Array): number {
+  for (let i = 0; i < a.length && i < b.length; i++) if (a[i] !== b[i]) return a[i]! - b[i]!;
+  return a.length - b.length;
+}
+
+/** The index of the leaf with this artifact digest in a sorted list, or -1. */
+function leafIndexOf(sorted: readonly TreeLeaf[], artifact: Uint8Array): number {
+  let lo = 0;
+  let hi = sorted.length - 1;
+  while (lo <= hi) {
+    const mid = (lo + hi) >>> 1;
+    const c = compareDigests(sorted[mid]!.artifact, artifact);
+    if (c === 0) return mid;
+    if (c < 0) lo = mid + 1;
+    else hi = mid - 1;
+  }
+  return -1;
+}
+
+/**
+ * Make ONE tree/1 BitGraph of 1 to N files: allocate one slot, take its floor,
+ * make every member's leaf under commitment/2, build the tree and its root
+ * document, commit the document's digest under the same slot with the spec
+ * pinned in the signed attribution, and verify what comes back before
+ * returning it. Throws a FuseError otherwise; it never commits a partial
+ * tree, never allocates a second slot, and never makes a tree without the
+ * floor. Members may be bytes, a loader read after the slot is held, a digest
+ * the caller finishes from a saved hash state, or (for as is) a digest alone;
+ * one tree may mix them.
+ */
+export async function fuseTree(members: readonly FuseTreeMember[], options: FuseTreeOptions = {}): Promise<FuseTreeResult> {
+  // 0. validate, before any request. A refusal here burns nothing.
+  if (!Array.isArray(members) || members.length === 0) throw new FuseError("bad-input", "a tree lists at least one member");
+  if (members.length > MAX_TREE_LEAVES) throw new FuseError("bad-input", `a tree lists at most ${MAX_TREE_LEAVES} members (got ${members.length})`);
+  const keep = options.keepCommitted === true;
+  const verifyMembers = options.verifyMembers === true;
+  let specHash: Uint8Array;
+  try {
+    specHash = currentTreeSpecHash();
+  } catch (err) {
+    throw new FuseError("bad-input", `no tree/1 spec hash to pin: ${err instanceof Error ? err.message : String(err)}`);
+  }
+  type Kind = "bytes" | "loaded" | "hashed" | "as-is";
+  interface Checked {
+    kind: Kind;
+    id: TreeMemberPlacement;
+    code: number;
+    /** The registered placement; null for as is. */
+    placement: Placement | null;
+    originDigest: Uint8Array;
+    name: string | null;
+    original: Uint8Array | null;
+    load: (() => Promise<Uint8Array> | Uint8Array) | null;
+    builder: FuseBuilder | null;
+    fusedDigest: ((input: FusedDigestInput) => Promise<Uint8Array> | Uint8Array) | null;
+  }
+  const checked: Checked[] = [];
+  const seen = new Map<string, number>();
+  const report = (phase: FuseTreeProgress["phase"], done: number, total: number) => {
+    if (options.onProgress === undefined) return;
+    try {
+      options.onProgress({ phase, done, total });
+    } catch {
+      // a progress hook never changes the outcome
+    }
+  };
+  const bad = (i: number, message: string) => new FuseError("bad-input", `member ${i}: ${message}`, null, i);
+  const shapes = 'original must be a Uint8Array, or load or fusedDigest a function, or placement "as-is" with an originDigest';
+  interface Loose { original?: unknown; load?: unknown; fusedDigest?: unknown; placement?: unknown; originDigest?: unknown; name?: unknown; builder?: unknown }
+  for (let i = 0; i < members.length; i++) {
+    // A null, undefined or missing element is refused like any other member without bytes, a loader or a digest.
+    const m = members[i] as Loose | null | undefined;
+    if (m === null || m === undefined || typeof m !== "object") throw bad(i, shapes);
+    const kind: Kind | null = m.original instanceof Uint8Array ? "bytes" : typeof m.load === "function" ? "loaded" : typeof m.fusedDigest === "function" ? "hashed" : m.placement === "as-is" ? "as-is" : null;
+    if (kind === null) throw bad(i, shapes);
+    if (kind !== "bytes" && m.placement === undefined) throw bad(i, `a ${kind} member names its placement`);
+    if (m.placement !== undefined && typeof m.placement !== "string") throw bad(i, "placement must be a string");
+    const original = kind === "bytes" ? (m.original as Uint8Array) : null;
+    const id = m.placement !== undefined ? (m.placement as string) : treePlacementFor(original!.length, original!);
+    const code = leafCodeOf(id);
+    if (code === null) {
+      if (getPlacement(id) === undefined) throw new FuseError("bad-placement", `member ${i}: placement "${id}" is not registered`, null, i);
+      throw bad(i, `${id} is not a tree placement; a tree holds as-is, trailer/1, container/1 and container/2 members`);
+    }
+    if ((kind === "loaded" || kind === "hashed") && code === LEAF_AS_IS) throw bad(i, `an as-is member is given by its bytes or its originDigest alone; a ${kind} member is placed`);
+    if (m.name !== undefined && typeof m.name !== "string") throw bad(i, "name must be a string");
+    if (m.builder !== undefined && typeof m.builder !== "function") throw bad(i, "builder must be a function");
+    if (code === LEAF_AS_IS && m.builder !== undefined) throw bad(i, "an as-is member takes no builder: nothing is placed in it");
+    if (kind !== "bytes" && !(m.originDigest instanceof Uint8Array && m.originDigest.length === 32)) throw bad(i, `${kind === "as-is" ? "an as-is" : `a ${kind}`} member names its originDigest, 32 bytes`);
+    if (verifyMembers && (kind === "hashed" || kind === "as-is")) throw bad(i, `${kind === "as-is" ? "an as-is member given by its digest" : "a hashed member"} cannot be verified in full; pass its bytes or drop verifyMembers`);
+    const originDigest = original !== null ? await digest(original) : (m.originDigest as Uint8Array);
+    // The same original under the same placement makes the same leaf, which a tree lists once.
+    const key = `${code}:${bytesToHex(originDigest)}`;
+    const j = seen.get(key);
+    if (j !== undefined) {
+      throw new FuseError("bad-input", `members ${j} and ${i} are the same original under the same placement (${id}) and would make the same leaf; a tree lists each leaf once`, null, i);
+    }
+    seen.set(key, i);
+    checked.push({
+      kind,
+      id: id as TreeMemberPlacement,
+      code,
+      placement: code === LEAF_AS_IS ? null : getPlacement(id)!,
+      originDigest,
+      name: typeof m.name === "string" ? m.name : null,
+      original,
+      load: kind === "loaded" ? (m.load as Checked["load"]) : null,
+      builder: (kind === "bytes" || kind === "loaded") && m.builder !== undefined ? (m.builder as FuseBuilder) : null,
+      fusedDigest: kind === "hashed" ? (m.fusedDigest as Checked["fusedDigest"]) : null,
+    });
+    report("hash", i + 1, members.length);
+  }
+  const t: BoundTransport = { ...DEFAULTS, ...(options.transport ?? {}) };
+
+  // 1. nonce: one slot for the whole tree, and the floor it binds.
+  const { slot, anchor } = await allocateSlot(t);
+  if (anchor === null) {
+    throw new FuseError("floor-missing", "the allocation returned no floor, so no tree/1 commitment can be made (tree/1 binds the floor block: bitgraph-fuse/2 or /3, enclave v9 and later); nothing was committed and the position will expire");
+  }
+  const { commitment, version } = producerCommitment(slot, anchor);
+  if (version === 1) throw new FuseError("floor-missing", "the floor could not be bound into the commitment; nothing was committed and the position will expire");
+  // The spec follows the floor: SPEC v1 defines tree/1 under fuse/2, SPEC v2 under fuse/3.
+  try {
+    specHash = currentTreeSpecHash(version);
+  } catch (err) {
+    throw new FuseError("bad-input", `no tree/1 spec hash to pin for bitgraph-fuse/${version}: ${err instanceof Error ? err.message : String(err)}; nothing was committed and the position will expire`);
+  }
+  const commitmentHex = bytesToHex(commitment);
+  const expiring = "nothing was committed and the slot will expire";
+
+  // 2. leaves: every member's under the one commitment. Committed bytes are
+  //    virtual: each is built, checked, hashed and released in turn, held only
+  //    for a caller who keeps them or asks the full verifier to read them.
+  const leaves: TreeLeaf[] = [];
+  const held: (Uint8Array | null)[] = [];
+  for (let i = 0; i < checked.length; i++) {
+    const c = checked[i]!;
+    let artifact: Uint8Array;
+    let bytes: Uint8Array | null = null;
+    if (c.code === LEAF_AS_IS) {
+      // As is: the file is its own committed bytes and its digest its artifact.
+      artifact = c.originDigest;
+      if (c.original !== null && (keep || verifyMembers)) bytes = c.original;
+    } else if (c.kind === "hashed") {
+      let d: unknown;
+      try {
+        d = await c.fusedDigest!({ commitment, commitmentHex, fuseVersion: version, floor: anchor, slot });
+      } catch (err) {
+        throw new FuseError("builder-failed", `member ${i}: fusedDigest threw: ${err instanceof Error ? err.message : String(err)}; ${expiring}`, null, i);
+      }
+      if (!(d instanceof Uint8Array) || d.length !== 32) throw new FuseError("builder-failed", `member ${i}: fusedDigest must return a 32-byte digest; ${expiring}`, null, i);
+      artifact = d;
+    } else {
+      let original: Uint8Array;
+      if (c.kind === "loaded") {
+        let loaded: unknown;
+        try {
+          loaded = await c.load!();
+        } catch (err) {
+          throw new FuseError("load-failed", `member ${i}: load threw: ${err instanceof Error ? err.message : String(err)}; ${expiring}`, null, i);
+        }
+        if (!(loaded instanceof Uint8Array)) throw new FuseError("load-failed", `member ${i}: load must return a Uint8Array; ${expiring}`, null, i);
+        original = loaded;
+        if (!bytesEqual(await digest(original), c.originDigest)) throw new FuseError("bad-input", `member ${i}: originDigest is not the SHA-256 of the loaded bytes; ${expiring}`, null, i);
+      } else {
+        original = c.original!;
+      }
+      const builder = c.builder ?? builderFor(c.id as PlacementId, original);
+      let committed: Uint8Array;
+      try {
+        committed = await builder({ commitment, commitmentHex, fuseVersion: version, floor: anchor, originDigest: c.originDigest, slot });
+      } catch (err) {
+        throw new FuseError("builder-failed", `member ${i}: the builder threw: ${err instanceof Error ? err.message : String(err)}; ${expiring}`, null, i);
+      }
+      if (!(committed instanceof Uint8Array)) throw new FuseError("builder-failed", `member ${i}: the builder must return a Uint8Array; ${expiring}`, null, i);
+      const located = requireCommitment(c.placement!, committed, commitment, i);
+      // The leaf's origin must be the origin the bytes embed (declared, and
+      // carried byte for byte), else the member would verify INVALID_ORIGIN
+      // after the slot is spent; the same two checks fuseSet runs.
+      const declared = located.originDigest;
+      const carried = located.originalBytes;
+      if ((declared !== undefined && !bytesEqual(declared, c.originDigest)) || (carried !== undefined && !bytesEqual(carried, original))) {
+        throw new FuseError("builder-failed", `member ${i}: the committed bytes embed an origin that is not the member's original; ${expiring}`, null, i);
+      }
+      artifact = await digest(committed);
+      if (keep || verifyMembers) bytes = committed;
+    }
+    leaves.push({ placement: c.code, artifact, origin: c.originDigest });
+    held.push(bytes);
+    report("fuse", i + 1, checked.length);
+  }
+
+  // 3. hash: the tree, and the root document that is the committed artifact.
+  report("tree", 0, 1);
+  let built: ReturnType<typeof buildTree>;
+  try {
+    built = buildTree(leaves);
+  } catch (err) {
+    throw new FuseError("bad-input", `the tree could not be built: ${err instanceof Error ? err.message : String(err)}; ${expiring}`);
+  }
+  const count = built.sorted.length;
+  const rootDocument = buildTreeRootDocument(commitment, count, built.root);
+  report("tree", 1, 1);
+  const artifactDigestB64 = bytesToBase64(await digest(rootDocument));
+  const specHashB64 = bytesToBase64(specHash);
+
+  // 4. fill: one commit; the root document rides as unsigned metadata, bound by its hash.
+  const body: Record<string, unknown> = {
+    digests: [{ digestB64: artifactDigestB64, hashAlg: "sha256" }],
+    slotId: slot.nonceB64,
+    slot,
+    chainId: "bitgraph:main",
+    attribution: treeAttribution(specHash),
+    metadata: { [TREE_METADATA_KEY]: bytesToHex(rootDocument) },
+    // fuse/2: the boundary checks the bound floor against its ledger before spending the slot.
+    // fuse/3: the bound Base floor, so the boundary can check it is the one it handed out.
+    ...(version === 2 ? { anchor } : { floor: anchor }),
+  };
+  if (options.agency !== undefined) body.agency = options.agency;
+  report("commit", 0, 1);
+  const { proof, recovered } = await commitUnderSlot(t, body, artifactDigestB64, slot);
+  report("commit", 1, 1);
+
+  // A reader verifies the proof before it is called a tree: the signature,
+  // fuse/2 and a known spec, the commitment recomputed from the proof's own
+  // slot record and signed floor, and this root document under the signed
+  // digest. The explicit document is used, so no verdict rests on the echo.
+  const verification = await verifyTreeMember({ proof, rootDocument });
+  if (verification.category !== "TREE_ROOT_VALID") {
+    throw new FuseError("verification-failed", `the returned proof does not verify as this tree: ${verification.category} (${verification.reason})`);
+  }
+  if (proof.attribution?.message !== specHashB64) {
+    throw new FuseError("verification-failed", "the returned proof pins a different spec than the one sent");
+  }
+  // The echo is unsigned and advisory: absent is normal, different is a rewrite.
+  let rootDocumentEchoed = false;
+  if (proof.metadata?.[TREE_METADATA_KEY] !== undefined) {
+    const echoed = readTreeMetadata(proof);
+    if (echoed === null || !bytesEqual(echoed, rootDocument)) {
+      throw new FuseError("verification-failed", `the returned proof echoes a root document under metadata["${TREE_METADATA_KEY}"] that differs from the committed one`);
+    }
+    rootDocumentEchoed = true;
+  }
+  // The floor the proof signs: a Base block (fuse/3) or an Ethereum anchor (fuse/2).
+  const floor: FloorMark = proof.commit.slotFloor ? { ...proof.commit.slotFloor } : proof.commit.slotAnchor!;
+
+  // Every member is bound to the verified root by its own path (the
+  // verifier's check, run here once per member); no member's bytes are read
+  // again. With verifyMembers the full verifier reads the committed bytes too.
+  const results: FuseTreeMemberResult[] = [];
+  for (let i = 0; i < checked.length; i++) {
+    const c = checked[i]!;
+    const leaf = leaves[i]!;
+    const k = leafIndexOf(built.sorted, leaf.artifact);
+    const listed = k >= 0 ? built.sorted[k] : undefined;
+    if (listed === undefined || listed.placement !== leaf.placement || !bytesEqual(listed.origin, leaf.origin)) {
+      throw new FuseError("verification-failed", `member ${i}: the committed tree does not list this member's leaf`, null, i);
+    }
+    const path = built.tree.path(k);
+    const reached = treeRootFromMember(listed, k, count, path);
+    if (reached === null || !bytesEqual(reached, built.root)) throw new FuseError("verification-failed", `member ${i}: its path does not recompute the committed root`, null, i);
+    let memberVerification: TreeVerifyResult | undefined;
+    if (verifyMembers) {
+      const want = c.code === LEAF_AS_IS ? "TREE_MEMBER_AS_IS" : "TREE_MEMBER_DIRECT";
+      const v = await verifyTreeMember({ proof, rootDocument, member: buildTreeMemberEvidence(listed, k, count, path), bytes: held[i]!, proofAlreadyVerified: true });
+      if (v.category !== want || v.member?.index !== k) {
+        throw new FuseError("verification-failed", `member ${i}: the returned proof does not verify this member: ${v.category} (${v.reason})`, null, i);
+      }
+      memberVerification = v;
+      report("verify", i + 1, checked.length);
+    }
+    const kept = held[i];
+    results.push({
+      index: i,
+      leafIndex: k,
+      placement: c.id,
+      code: c.code,
+      originDigestB64: bytesToBase64(c.originDigest),
+      artifactDigestB64: bytesToBase64(leaf.artifact),
+      name: c.name,
+      ...(keep && kept !== null && kept !== undefined ? { committedBytes: kept } : {}),
+      ...(memberVerification !== undefined ? { verification: memberVerification } : {}),
+    });
+  }
+  const memberEvidence = (index: number): TreeMemberEvidence => {
+    const r = results[index];
+    if (r === undefined) throw new RangeError(`no member ${index}`);
+    return buildTreeMemberEvidence(built.sorted[r.leafIndex]!, r.leafIndex, count, built.tree.path(r.leafIndex));
+  };
+  return {
+    proof,
+    rootDocument,
+    artifactDigestB64,
+    count,
+    rootHex: bytesToHex(built.root),
+    commitment,
+    floor: "chain" in floor ? { ...floor } : { counter: floor.counter, blockNumber: floor.blockNumber, blockHash: floor.blockHash },
+    specHashB64,
+    leaves: built.sorted,
+    tree: built.tree,
+    members: results,
+    memberEvidence,
+    recovered,
+    rootDocumentEchoed,
+    verification,
+  };
+}
+
 /** Decode a standard-base64 digest, for callers holding one as text. */
 export function digestFromBase64(b64: string): Uint8Array {
   const d = base64ToBytes(b64);