@mikeargento/bitgraph 1.5.0 → 1.7.0

package/src/__tests__/fuse-set-sdk.test.ts

@@ -32,8 +32,8 @@ import {
 import type { BitGraphProof, SlotAllocation, Attribution, SetMember, SetManifest } from "@mikeargento/bitgraph-verify";
 import { makeKey, signBody, b64, utf8 } from "./audit-fixtures.js";
 import type { ManualKey } from "./audit-fixtures.js";
-import { fuse, fuseSet, builderFor, placementForBytes, fusedNamesFor, FuseError, MAX_SET_MEMBERS, digest } from "../fuse.js";
-import type { FuseSetProgress } from "../fuse.js";
+import { fuse, fuseSet, builderFor, placementForBytes, fusedNamesFor, FuseError, MAX_SET_MEMBERS, digest, trailerBytesFor } from "../fuse.js";
+import type { FuseSetProgress, FuseSetBytesMember, FuseSetLoadedMember, FuseSetHashedMember, FusedDigestInput } from "../fuse.js";
 import type { FuseSetMember } from "../fuse.js";
 
 const FIX = fileURLToPath(new URL("../../src/__tests__/fuse-fixtures/", import.meta.url));
@@ -48,7 +48,7 @@ const unrelated = utf8("a file nobody recorded\n");
 // The phase-1 fixtures fuse original.txt as trailer/1 and image.png as
 // container/1, so these members declare those placements; the by-bytes
 // default (placementForBytes) is asserted on its own in test 3.
-const two = (): FuseSetMember[] => [{ original, placement: "trailer/1" }, { original: png, placement: "container/1" }];
+const two = (): FuseSetBytesMember[] => [{ original, placement: "trailer/1" }, { original: png, placement: "container/1" }];
 
 // ---------------------------------------------------------------------------
 // Local signer: slots and proofs minted from a received commit body
@@ -160,9 +160,9 @@ const toUrlSafe = (s: string) => s.replace(/\+/g, "-").replace(/\//g, "_").repla
 interface Oracle { commitment: Uint8Array; fused: Uint8Array[]; rows: SetMember[]; manifest: Uint8Array; digestB64: string; sorted: SetMember[] }
 
 /** The commitment from the slot, each member built by its placement, the canonical manifest and its digest. */
-function oracle(slot: SlotAllocation, members: readonly FuseSetMember[]): Oracle {
+function oracle(slot: SlotAllocation, members: readonly FuseSetBytesMember[]): Oracle {
   const commitment = computeSlotCommitment(slot);
-  const placementOf = (m: FuseSetMember) => m.placement ?? placementForBytes(m.original);
+  const placementOf = (m: FuseSetBytesMember) => m.placement ?? placementForBytes(m.original);
   const fused = members.map((m) => getPlacement(placementOf(m))!.build({ original: m.original, commitment }));
   const rows = members.map((m, i) => ({ artifact: sha256(fused[i]!), origin: sha256(m.original), placement: placementOf(m) }));
   const manifest = buildSetManifest(commitment, rows);
@@ -259,7 +259,7 @@ describe("fuseSet(): one slot, N files, the manifest as the artifact", () => {
     // The by-bytes default: PNG is trailer-safe, plain text goes into a container.
     const d = await fuseSet([{ original: png }, { original }], { transport: honest(key, slot).transport });
     assert.deepEqual(d.members.map((m) => m.placement), [placementForBytes(png), placementForBytes(original)]);
-    assert.deepEqual(d.members.map((m) => m.placement), ["trailer/1", "container/1"]);
+    assert.deepEqual(d.members.map((m) => m.placement), ["trailer/1", "container/2"]);
   });
 
   test("4. each original rebuilds its member (SET_MEMBER_FROM_ORIGIN); with the echo stripped and no explicit bytes nothing is bound", async () => {
@@ -336,7 +336,7 @@ describe("fuseSet(): a bad member burns the slot and commits nothing", () => {
   test("9. bytes that carry the commitment but embed another member's origin are builder-failed naming the member and the origin", async () => {
     const { calls, transport } = honest(key, slot);
     // Two trailer/1 members; member 1's builder hands back member 0's fused bytes, which carry c but embed member 0's original.
-    const members: FuseSetMember[] = [{ original, placement: "trailer/1" }, { original: note, placement: "trailer/1" }];
+    const members: FuseSetBytesMember[] = [{ original, placement: "trailer/1" }, { original: note, placement: "trailer/1" }];
     members[1]!.builder = ({ commitment }) => getPlacement("trailer/1")!.build({ original, commitment });
     await assert.rejects(fuseSet(members, { transport }), (e: FuseError) => e.code === "builder-failed" && /member 1/.test(e.message) && /origin/.test(e.message) && e.member === 1);
     assert.equal(commits(calls).length, 0);
@@ -345,14 +345,14 @@ describe("fuseSet(): a bad member burns the slot and commits nothing", () => {
 
   test("9b. container/1: bytes that declare the member's origin digest but carry other bytes are builder-failed naming the member; no commit", async () => {
     const { calls, transport } = honest(key, slot);
-    const members: FuseSetMember[] = [{ original, placement: "trailer/1" }, { original: png, placement: "container/1" }];
+    const members: FuseSetBytesMember[] = [{ original, placement: "trailer/1" }, { original: png, placement: "container/1" }];
     // The payload names png's digest (so the declared origin matches) while the tar carries other bytes.
     members[1]!.builder = ({ commitment, originDigest }) => getPlacement("container/1")!.build({ original: utf8("not the member's original\n"), originDigest: originDigest!, commitment });
     await assert.rejects(fuseSet(members, { transport }), (e: FuseError) => e.code === "builder-failed" && /^member 1/.test(e.message) && /origin/.test(e.message) && e.member === 1);
     assert.equal(commits(calls).length, 0, "nothing was committed");
     assert.equal(allocates(calls).length, 1);
     // The mirror: a payload declaring another digest over the member's own bytes is refused the same way.
-    const declared: FuseSetMember[] = [{ original, placement: "trailer/1" }, { original: png, placement: "container/1" }];
+    const declared: FuseSetBytesMember[] = [{ original, placement: "trailer/1" }, { original: png, placement: "container/1" }];
     declared[1]!.builder = ({ commitment }) => getPlacement("container/1")!.build({ original: png, originDigest: sha256(unrelated), commitment });
     const b = honest(key, slot);
     await assert.rejects(fuseSet(declared, { transport: b.transport }), (e: FuseError) => e.code === "builder-failed" && e.member === 1);
@@ -698,3 +698,111 @@ describe("fuseSet(): hashing and progress", () => {
     assert.equal(calls, 8, "every report was attempted");
   });
 });
+
+describe("fuseSet(): loaded and hashed members", () => {
+  /** The trailer/1 member finished from a hasher state, as a scanner does: hash the original once, keep the state, add the trailer later. */
+  const savedState = (bytes: Uint8Array) => { const h = sha256.create(); h.update(bytes); return h; };
+  const finish = (h: ReturnType<typeof sha256.create>, trailer: Uint8Array) => { const c = h.clone(); c.update(trailer); return c.digest(); };
+
+  test("30. trailerBytesFor is the placement's own suffix: original followed by it hashes to the trailer/1 build, and a saved state finished with it agrees", () => {
+    const commitment = computeSlotCommitment(slot);
+    const t = trailerBytesFor(commitment);
+    assert.equal(t.length, 48);
+    assert.deepEqual(t.subarray(0, 8), utf8("BGFUSE01"));
+    assert.deepEqual(t.subarray(8, 16), new Uint8Array(8));
+    assert.deepEqual(t.subarray(16), commitment);
+    for (const o of [original, png, note, new Uint8Array(0), new Uint8Array(55).fill(1), new Uint8Array(64).fill(2), new Uint8Array(1_000_003).fill(3)]) {
+      const built = getPlacement("trailer/1")!.build({ original: o, commitment });
+      assert.deepEqual(built.subarray(o.length), t, `suffix for ${o.length} bytes`);
+      assert.deepEqual(finish(savedState(o), t), sha256(built), `finished state for ${o.length} bytes`);
+    }
+    assert.throws(() => trailerBytesFor(new Uint8Array(31)), (e: FuseError) => e.code === "bad-input");
+  });
+
+  test("31. a loaded member is read once, after the slot is held, checked against its named digest, and released unless kept", async () => {
+    const { calls, transport } = honest(key, slot);
+    const order: string[] = [];
+    const wrapped = { ...transport, fetch: async (url: string, init?: RequestInit) => { order.push(new URL(url).pathname); return (transport.fetch as (u: string, i?: RequestInit) => Promise<Response>)(url, init); } } as unknown as typeof transport;
+    let loads = 0;
+    const loaded: FuseSetLoadedMember = { load: async () => { loads++; order.push("load"); return original; }, originDigest: sha256(original), placement: "trailer/1", name: "photo.jpg" };
+    const r = await fuseSet([loaded, { original: png, placement: "container/1" }], { transport: wrapped });
+    assert.equal(loads, 1);
+    assert.ok(order.indexOf("load") > order.indexOf("/api/fuse/allocate"), "read after the slot is held");
+    assert.ok(order.indexOf("load") < order.indexOf("/api/fuse/commit"), "read before the commit");
+    const o = oracle(slot, [{ original, placement: "trailer/1" }, { original: png, placement: "container/1" }]);
+    assert.equal(r.members[0]!.artifactDigestB64, bytesToBase64(o.rows[0]!.artifact));
+    assert.equal(r.members[0]!.originDigestB64, bytesToBase64(sha256(original)));
+    assert.equal(r.members[0]!.fusedName, fusedNamesFor("photo.jpg", "trailer/1").fusedName);
+    assert.ok(!("fusedBytes" in r.members[0]!));
+    assert.equal(commits(calls).length, 1);
+    const kept = await fuseSet([{ ...loaded }], { transport: honest(key, slot).transport, keepFused: true });
+    assert.deepEqual(kept.members[0]!.fusedBytes, getPlacement("trailer/1")!.build({ original, commitment: computeSlotCommitment(slot) }));
+    // A wrong named digest burns the slot and commits nothing.
+    const bad = honest(key, slot);
+    await assert.rejects(fuseSet([{ load: () => original, originDigest: sha256(unrelated), placement: "trailer/1" }], { transport: bad.transport }), (e: FuseError) => e.code === "bad-input" && /^member 0: originDigest is not the SHA-256 of the loaded bytes/.test(e.message) && e.member === 0);
+    assert.equal(commits(bad.calls).length, 0);
+    assert.equal(allocates(bad.calls).length, 1);
+    // A loader that throws, or returns something other than bytes, is load-failed naming the member.
+    const thrown = honest(key, slot);
+    await assert.rejects(fuseSet([{ load: () => { throw new Error("gone"); }, originDigest: sha256(original), placement: "trailer/1" }], { transport: thrown.transport }), (e: FuseError) => e.code === "load-failed" && /^member 0: load threw: gone/.test(e.message) && e.member === 0);
+    assert.equal(commits(thrown.calls).length, 0);
+    await assert.rejects(fuseSet([{ original, placement: "trailer/1" }, { load: (() => "text") as never, originDigest: sha256(original), placement: "container/1" }], { transport: honest(key, slot).transport }), (e: FuseError) => e.code === "load-failed" && /^member 1: load must return a Uint8Array/.test(e.message) && e.member === 1);
+    // Without a placement or a digest nothing is requested.
+    const quiet = honest(key, slot);
+    await assert.rejects(fuseSet([{ load: () => original, originDigest: sha256(original) } as never], { transport: quiet.transport }), (e: FuseError) => e.code === "bad-input" && /^member 0: a loaded member names its placement/.test(e.message));
+    await assert.rejects(fuseSet([{ load: () => original, placement: "trailer/1" } as never], { transport: quiet.transport }), (e: FuseError) => e.code === "bad-input" && /^member 0: a loaded member names its originDigest/.test(e.message));
+    assert.equal(quiet.calls.length, 0);
+  });
+
+  test("32. a hashed member answers its fused digest for the held commitment and never shows its bytes; the row is what the real verifier finds", async () => {
+    const { calls, transport } = honest(key, slot);
+    const inputs: FusedDigestInput[] = [];
+    const state = savedState(original);
+    const hashed: FuseSetHashedMember = {
+      originDigest: sha256(original),
+      placement: "trailer/1",
+      name: "photo.jpg",
+      fusedDigest: (input) => { inputs.push(input); return finish(state, trailerBytesFor(input.commitment)); },
+    };
+    const r = await fuseSet([hashed, { original: png, placement: "container/1" }, { load: () => note, originDigest: sha256(note), placement: "container/1" }], { transport, keepFused: true });
+    assert.equal(inputs.length, 1);
+    const commitment = computeSlotCommitment(slot);
+    assert.deepEqual(inputs[0]!.commitment, commitment);
+    assert.equal(inputs[0]!.commitmentHex, bytesToHex(commitment));
+    assert.equal(inputs[0]!.slot.nonceB64, slot.nonceB64);
+    const built = getPlacement("trailer/1")!.build({ original, commitment });
+    assert.equal(r.members[0]!.artifactDigestB64, bytesToBase64(sha256(built)), "the row is the hash of the placement's build");
+    assert.ok(!("fusedBytes" in r.members[0]!), "nothing to keep for a hashed member");
+    assert.ok("fusedBytes" in r.members[1]! && "fusedBytes" in r.members[2]!, "bytes and loaded members are kept");
+    assert.equal(r.members.length, 3);
+    assert.equal(r.manifest.members.length, 3);
+    assert.equal(commits(calls).length, 1);
+    // The real verifier reads the member from the bytes a reader would build, and from its original.
+    const direct = await verifyFuseMember({ proof: r.proof, bytes: built, manifest: r.manifestBytes });
+    assert.equal(direct.category, "SET_MEMBER_DIRECT", direct.reason ?? "");
+    assert.equal(direct.set!.member!.index, r.members[0]!.manifestIndex);
+    const fromOrigin = await verifyFuseMember({ proof: r.proof, bytes: original, manifest: r.manifestBytes });
+    assert.equal(fromOrigin.category, "SET_MEMBER_FROM_ORIGIN", fromOrigin.reason ?? "");
+    // verifyMembers refuses a hashed member before any request; a throwing or short answer is builder-failed naming the member.
+    const quiet = honest(key, slot);
+    await assert.rejects(fuseSet([hashed], { transport: quiet.transport, verifyMembers: true }), (e: FuseError) => e.code === "bad-input" && /^member 0: a hashed member cannot be verified in full/.test(e.message) && e.member === 0);
+    assert.equal(quiet.calls.length, 0);
+    const throwing = honest(key, slot);
+    await assert.rejects(fuseSet([{ ...hashed, fusedDigest: () => { throw new Error("no state"); } }], { transport: throwing.transport }), (e: FuseError) => e.code === "builder-failed" && /^member 0: fusedDigest threw: no state/.test(e.message) && e.member === 0);
+    assert.equal(commits(throwing.calls).length, 0);
+    await assert.rejects(fuseSet([{ ...hashed, fusedDigest: () => new Uint8Array(31) }], { transport: honest(key, slot).transport }), (e: FuseError) => e.code === "builder-failed" && /^member 0: fusedDigest must return a 32-byte digest/.test(e.message));
+    // The same original as a hashed member and as a bytes member under one placement is the duplicate it always was.
+    await assert.rejects(fuseSet([hashed, { original, placement: "trailer/1" }], { transport: honest(key, slot).transport }), (e: FuseError) => e.code === "bad-input" && /^members 0 and 1 are the same original/.test(e.message));
+  });
+
+  test("33. progress counts every shape: hash before the slot for all three, fuse after it, one commit", async () => {
+    const seen: FuseSetProgress[] = [];
+    const state = savedState(original);
+    await fuseSet([
+      { originDigest: sha256(original), placement: "trailer/1", fusedDigest: ({ commitment }) => finish(state, trailerBytesFor(commitment)) },
+      { load: () => note, originDigest: sha256(note), placement: "container/1" },
+      { original: png, placement: "container/1" },
+    ], { transport: honest(key, slot).transport, onProgress: (p) => seen.push({ ...p }) });
+    assert.deepEqual(seen.map((p) => `${p.phase} ${p.done}/${p.total}`), ["hash 1/3", "hash 2/3", "hash 3/3", "fuse 1/3", "fuse 2/3", "fuse 3/3", "commit 0/1", "commit 1/1"]);
+  });
+});

package/src/__tests__/fuse-set.test.ts

@@ -352,7 +352,7 @@ describe("codec: parseSetManifest", () => {
 
 describe("registry and metadata", () => {
   test("13. PLACEMENTS is unchanged; set/1 resolves through getPlacement as Form C, not byte-exact, locate-only", () => {
-    assert.deepEqual(PLACEMENTS.map((p) => p.id), ["trailer/1", "container/1", "produced/1"]);
+    assert.deepEqual(PLACEMENTS.map((p) => p.id), ["trailer/1", "container/1", "container/2", "produced/1"]);
     const set1 = getPlacement("set/1")!;
     assert.ok(set1);
     assert.equal(set1.id, SET_PLACEMENT_ID);

package/src/fuse-cli.ts

@@ -28,7 +28,7 @@ import type { FuseTransport } from "./fuse.js";
 
 const USAGE = `bitgraph-fuse: BitGraph producer harness (profile bitgraph-fuse/1, working name)
 
-  bitgraph-fuse fuse <file> --placement trailer/1|container/1 [options]
+  bitgraph-fuse fuse <file> --placement trailer/1|container/1|container/2 [options]
       Form A or B over an existing file. The file is never modified.
   bitgraph-fuse produce [--origin <file>] [options]
       Form C: a canonical payload naming an optional source.
@@ -104,7 +104,7 @@ async function writeOutputs(outDir: string, label: string, frame: unknown, fused
 async function runFuse(args: Args): Promise<number> {
   const file = args.positional[0];
   const placement = args.flags.get("placement");
-  if (file === undefined || (placement !== "trailer/1" && placement !== "container/1")) { process.stderr.write(USAGE); return 64; }
+  if (file === undefined || (placement !== "trailer/1" && placement !== "container/1" && placement !== "container/2")) { process.stderr.write(USAGE); return 64; }
   const original = new Uint8Array(await readFile(resolve(file)));
   const label = sanitize(basename(file));
   const ext = placement === "trailer/1" ? extname(label) : ".tar";

package/src/fuse.ts

@@ -49,6 +49,8 @@ import {
   parseSetManifest,
   readSetMetadata,
   SET_METADATA_KEY,
+  TRAILER_LENGTH,
+  TRAILER_MAGIC,
   verifyFuse,
   verifyFuseMember,
   base64ToBytes,
@@ -153,6 +155,7 @@ export type FuseErrorCode =
   | "bad-input"
   | "allocate-failed"
   | "builder-failed"
+  | "load-failed"
   | "commitment-missing"
   | "commit-refused"
   | "slot-unavailable"
@@ -183,12 +186,14 @@ export class FuseError extends Error {
  * safe only where decoders stop at an end marker or read by declared sizes:
  * JPEG (EOI), PNG (IEND), GIF (0x3B), TIFF and the TIFF-based raws such as
  * DNG, CR2, NEF, ARW (offset tables), BMP and RIFF containers such as WebP,
- * WAV, AVI (declared sizes). Everything else goes into `container/1`, a tar
- * that carries the original untouched: PDF, ZIP-based documents, ISO base
+ * WAV, AVI (declared sizes). Everything else goes into `container/2`, a tar
+ * that carries the original untouched and FIRST, so a scanner can hash it
+ * once and finish the fused digest later: PDF, ZIP-based documents, ISO base
  * media video and images, Matroska, MP3, structured and plain text, and any
- * format not recognised here.
+ * format not recognised here. Artifacts made under `container/1` (the
+ * manifest first) stay readable; nothing new is made under it.
  */
-export function placementForBytes(bytes: Uint8Array): "trailer/1" | "container/1" {
+export function placementForBytes(bytes: Uint8Array): "trailer/1" | "container/2" {
   const at = (sig: number[], offset = 0): boolean => bytes.length >= offset + sig.length && sig.every((v, i) => bytes[offset + i] === v);
   const trailerSafe =
     at([0xff, 0xd8, 0xff]) || // JPEG
@@ -197,7 +202,7 @@ export function placementForBytes(bytes: Uint8Array): "trailer/1" | "container/1
     at([0x49, 0x49, 0x2a, 0x00]) || at([0x4d, 0x4d, 0x00, 0x2a]) || // TIFF, DNG, CR2, NEF, ARW
     (at([0x42, 0x4d]) && bytes.length >= 14) || // BMP
     (at([0x52, 0x49, 0x46, 0x46]) && bytes.length >= 12); // RIFF: WebP, WAV, AVI
-  return trailerSafe ? "trailer/1" : "container/1";
+  return trailerSafe ? "trailer/1" : "container/2";
 }
 
 /** Names for a fused artifact and its Frame, from the original's name. */
@@ -206,7 +211,7 @@ export function fusedNamesFor(originalName: string, placement: PlacementId): { f
   const stem = dot > 0 ? originalName.slice(0, dot) : originalName;
   const ext = dot > 0 ? originalName.slice(dot) : "";
   return {
-    fusedName: placement === "trailer/1" ? `${stem}.fused${ext}` : placement === "container/1" ? `${stem}.fused.tar` : `${stem}.produced.json`,
+    fusedName: placement === "trailer/1" ? `${stem}.fused${ext}` : placement.startsWith("container/") ? `${stem}.fused.tar` : `${stem}.produced.json`,
     frameName: `${originalName}.bitgraph-fuse.json`,
   };
 }
@@ -476,9 +481,20 @@ export async function fuse(builder: FuseBuilder, options: FuseOptions): Promise<
 export const MAX_SET_MEMBERS = 2000;
 
 /** The placements a set member takes: Forms A and B, one original per member. */
-export type SetMemberPlacement = "trailer/1" | "container/1";
+export type SetMemberPlacement = "trailer/1" | "container/1" | "container/2";
 
-export interface FuseSetMember {
+/** What a hashed member's fused digest is computed for: the held slot and its commitment. */
+export interface FusedDigestInput {
+  commitment: Uint8Array;
+  commitmentHex: string;
+  slot: SlotAllocation;
+}
+
+/**
+ * A member given as bytes. The core hashes the original, builds the fused
+ * bytes under the slot's commitment, checks them, and hashes them.
+ */
+export interface FuseSetBytesMember {
   /** The original bytes. Never modified. */
   original: Uint8Array;
   /** Default: placementForBytes(original). */
@@ -489,10 +505,62 @@ export interface FuseSetMember {
   builder?: FuseBuilder;
 }
 
+/**
+ * A member whose bytes are read only when it is that member's turn, after
+ * the slot is held, and released once hashed: one member's bytes in memory
+ * at a time, however large the set. Nothing can be read before allocation
+ * without reading twice, so the caller names the placement and the origin
+ * digest up front; the digest is checked against the loaded bytes, and the
+ * byte guards run as for a bytes member.
+ */
+export interface FuseSetLoadedMember {
+  load: () => Promise<Uint8Array> | Uint8Array;
+  originDigest: Uint8Array;
+  placement: SetMemberPlacement;
+  /** Advisory; feeds fusedNamesFor. */
+  name?: string;
+  /** Default: builderFor(placement, bytes). The locate and origin guards run regardless. */
+  builder?: FuseBuilder;
+}
+
+/**
+ * A member the caller hashes itself: it answers the fused digest for the
+ * held slot's commitment. For trailer/1 that is a hash state saved after
+ * the original and finished with trailerBytesFor(commitment), so the bytes
+ * are read once, when they are scanned, and never again. The core never
+ * sees this member's bytes: no byte guard runs, keepFused returns nothing
+ * for it, and verifyMembers refuses it before any request. Its row is bound
+ * to the committed manifest by digest like every other.
+ */
+export interface FuseSetHashedMember {
+  originDigest: Uint8Array;
+  placement: SetMemberPlacement;
+  fusedDigest: (input: FusedDigestInput) => Promise<Uint8Array> | Uint8Array;
+  /** Advisory; feeds fusedNamesFor. */
+  name?: string;
+}
+
+export type FuseSetMember = FuseSetBytesMember | FuseSetLoadedMember | FuseSetHashedMember;
+
+/**
+ * The 48 bytes trailer/1 appends after the original: the magic, eight
+ * reserved zero bytes, the commitment. A hasher whose state was saved after
+ * the original finishes with these and holds the member's fused digest
+ * without reading the original again. A test pins them against the
+ * placement's own build.
+ */
+export function trailerBytesFor(commitment: Uint8Array): Uint8Array {
+  if (!(commitment instanceof Uint8Array) || commitment.length !== 32) throw new FuseError("bad-input", "a slot commitment is 32 bytes");
+  const out = new Uint8Array(TRAILER_LENGTH);
+  out.set(new TextEncoder().encode(TRAILER_MAGIC), 0);
+  out.set(commitment, TRAILER_LENGTH - 32);
+  return out;
+}
+
 export interface FuseSetProgress {
   /**
-   * "hash": origin digests, one per member, before any request.
-   * "fuse": each member built and its fused digest taken, after the slot is held.
+   * "hash": each member checked before any request (a bytes member's origin digest is taken here).
+   * "fuse": each member's fused digest taken, after the slot is held.
    * "commit": 0 of 1 before the request, 1 of 1 when the proof is back.
    * "verify": only with verifyMembers, one per member.
    */
@@ -502,7 +570,7 @@ export interface FuseSetProgress {
 }
 
 export interface FuseSetOptions {
-  /** Return each member's fused bytes. Default false: they are virtual, rebuilt from the original and the proof. */
+  /** Return each member's fused bytes. Default false: they are virtual, rebuilt from the original and the proof. A hashed member has none to return. */
   keepFused?: boolean;
   /**
    * Run the full verifier (verifyFuseMember) over every member's fused bytes
@@ -510,7 +578,8 @@ export interface FuseSetOptions {
    * false: every member is bound to the returned proof by digest, its row in
    * the committed manifest, which is itself verified FUSED_DIRECT; that is
    * linear and reads no bytes. The full pass re-hashes every member with the
-   * verifier's own hasher and grows with the square of the member count.
+   * verifier's own hasher and grows with the square of the member count. A
+   * set with a hashed member refuses it before any request.
    */
   verifyMembers?: boolean;
   /** Called as the set advances. A throw inside it is ignored: a progress hook never changes the outcome. */
@@ -533,7 +602,7 @@ export interface FuseSetMemberResult {
   fusedName: string | null;
   /** Advisory; no Frame is written for a set member this phase. */
   frameName: string | null;
-  /** Present only when keepFused is true. */
+  /** Present only when keepFused is true and the member's bytes passed through the core (never for a hashed member). */
   fusedBytes?: Uint8Array;
   /** Present only with verifyMembers: the verifier's own verdict against this member's fused bytes. Always SET_MEMBER_DIRECT on success, with set.manifestSource "argument". */
   verification?: FuseMemberResult;
@@ -562,13 +631,28 @@ export interface FuseSetResult {
  * Allocate once, fuse every member with the one commitment, hash the set
  * manifest, fill the slot with it. Returns the proof with the manifest bytes
  * beside it, or throws a FuseError; it never commits a partial set and never
- * allocates a second slot.
+ * 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.
  */
 export async function fuseSet(members: readonly FuseSetMember[], options: FuseSetOptions = {}): Promise<FuseSetResult> {
   // 0. validate, before any request. A refusal here burns nothing.
   if (!Array.isArray(members) || members.length === 0) throw new FuseError("bad-input", "a set lists at least one member");
   if (members.length > MAX_SET_MEMBERS) throw new FuseError("bad-input", `a set lists at most ${MAX_SET_MEMBERS} members (got ${members.length})`);
-  interface Checked { placement: Placement; id: SetMemberPlacement; original: Uint8Array; originDigest: Uint8Array; name: string | null; builder: FuseBuilder }
+  const keep = options.keepFused === true;
+  const verifyMembers = options.verifyMembers === true;
+  type Kind = "bytes" | "loaded" | "hashed";
+  interface Checked {
+    kind: Kind;
+    placement: Placement;
+    id: SetMemberPlacement;
+    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: FuseSetProgress["phase"], done: number, total: number) => {
@@ -579,17 +663,23 @@ export async function fuseSet(members: readonly FuseSetMember[], options: FuseSe
       // a progress hook never changes the outcome
     }
   };
+  const bad = (i: number, message: string) => new FuseError("bad-input", `member ${i}: ${message}`, null, i);
   for (let i = 0; i < members.length; i++) {
-    const m = members[i];
-    // A null, undefined or missing element is refused like any other member without original bytes.
-    if (m === null || typeof m !== "object" || !(m.original instanceof Uint8Array)) throw new FuseError("bad-input", `member ${i}: original must be a Uint8Array`, null, i);
-    const id = m.placement ?? placementForBytes(m.original);
+    const m = members[i] as Partial<FuseSetBytesMember & FuseSetLoadedMember & FuseSetHashedMember> | null | undefined;
+    // A null, undefined or missing element is refused like any other member without bytes, a loader or a digest.
+    if (m === null || typeof m !== "object") throw bad(i, "original must be a Uint8Array, or load or fusedDigest a function");
+    const kind: Kind | null = m.original instanceof Uint8Array ? "bytes" : typeof m.load === "function" ? "loaded" : typeof m.fusedDigest === "function" ? "hashed" : null;
+    if (kind === null) throw bad(i, "original must be a Uint8Array, or load or fusedDigest a function");
+    if (kind !== "bytes" && m.placement === undefined) throw bad(i, `a ${kind} member names its placement`);
+    const id = m.placement ?? placementForBytes(m.original as Uint8Array);
     const placement = getPlacement(id);
     if (placement === undefined) throw new FuseError("bad-placement", `member ${i}: placement "${id}" is not registered`, null, i);
-    if (placement.form === "C") throw new FuseError("bad-input", `member ${i}: ${id} takes no original; a set holds trailer/1 and container/1 members only`, null, i);
-    if (m.name !== undefined && typeof m.name !== "string") throw new FuseError("bad-input", `member ${i}: name must be a string`, null, i);
-    if (m.builder !== undefined && typeof m.builder !== "function") throw new FuseError("bad-input", `member ${i}: builder must be a function`, null, i);
-    const originDigest = await digest(m.original);
+    if (placement.form === "C") throw bad(i, `${id} takes no original; a set holds trailer/1, container/1 and container/2 members only`);
+    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 (kind !== "bytes" && !(m.originDigest instanceof Uint8Array && m.originDigest.length === 32)) throw bad(i, `a ${kind} member names its originDigest, 32 bytes`);
+    if (kind === "hashed" && verifyMembers) throw bad(i, "a hashed member cannot be verified in full; pass its bytes or drop verifyMembers");
+    const originDigest = kind === "bytes" ? await digest(m.original as Uint8Array) : (m.originDigest as Uint8Array);
     // The same original under the same placement fuses to the same bytes, which one manifest lists once.
     const key = `${id}:${bytesToHex(originDigest)}`;
     const j = seen.get(key);
@@ -597,7 +687,17 @@ export async function fuseSet(members: readonly FuseSetMember[], options: FuseSe
       throw new FuseError("bad-input", `members ${j} and ${i} are the same original under the same placement (${id}) and would fuse to the same bytes; a set lists each fused artifact once`, null, i);
     }
     seen.set(key, i);
-    checked.push({ placement, id, original: m.original, originDigest, name: m.name ?? null, builder: m.builder ?? builderFor(id, m.original) });
+    checked.push({
+      kind,
+      placement,
+      id,
+      originDigest,
+      name: m.name ?? null,
+      original: kind === "bytes" ? (m.original as Uint8Array) : null,
+      load: kind === "loaded" ? (m.load as Checked["load"]) : null,
+      builder: kind !== "hashed" && 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 ?? {}) };
@@ -605,41 +705,72 @@ export async function fuseSet(members: readonly FuseSetMember[], options: FuseSe
   // 1. nonce: one slot for the whole set
   const slot = await allocateSlot(t);
 
-  // 2. fuse: the commitment once, every member's bytes carrying it. The slot
-  //    is held and its TTL is running; a throw here burns it but commits nothing.
+  // 2. fuse: the commitment once, every member's digest under it. The slot
+  //    is held and its TTL is running; a throw here burns it but commits
+  //    nothing. A member's fused bytes are virtual: each is built, hashed
+  //    and released in turn, so memory holds one member's bytes at a time.
+  //    They are held only for a caller who keeps them or asks the full
+  //    verifier to read them.
   const commitment = computeSlotCommitment(slot);
   const commitmentHex = bytesToHex(commitment);
-  const keep = options.keepFused === true;
-  const verifyMembers = options.verifyMembers === true;
-  // A member's fused bytes are virtual: each is built, hashed and released in
-  // turn, so memory holds the originals and one fused copy. They are held only
-  // for a caller who keeps them or asks the full verifier to read them.
   const fusedBytes: (Uint8Array | null)[] = [];
   const rows: SetMember[] = [];
+  const expiring = "nothing was committed and the slot will expire";
   for (let i = 0; i < checked.length; i++) {
     const c = checked[i]!;
-    let fused: Uint8Array;
-    try {
-      fused = await c.builder({ commitment, commitmentHex, originDigest: c.originDigest, slot });
-    } catch (err) {
-      throw new FuseError("builder-failed", `member ${i}: the builder threw: ${err instanceof Error ? err.message : String(err)}`, null, i);
-    }
-    if (!(fused instanceof Uint8Array)) throw new FuseError("builder-failed", `member ${i}: the builder must return a Uint8Array`, null, i);
-    const located = requireCommitment(c.placement, fused, commitment, i);
-    // The row's origin must be the origin the bytes embed, else the member
-    // would verify INVALID_ORIGIN_ATTRIBUTION after the slot is spent. Both
-    // facts are checked when both are present: the digest the bytes declare
-    // (container/1's payload) and the bytes they carry, compared byte for
-    // byte with the member's original rather than hashed again, so a builder
-    // cannot pack other bytes under the member's digest and leave a member no
-    // original rebuilds.
-    const declared = located.originDigest;
-    const carried = located.originalBytes;
-    if ((declared !== undefined && !bytesEqual(declared, c.originDigest)) || (carried !== undefined && !bytesEqual(carried, c.original))) {
-      throw new FuseError("builder-failed", `member ${i}: the fused bytes embed an origin that is not the member's original; nothing was committed and the slot will expire`, null, i);
+    let artifact: Uint8Array;
+    let held: Uint8Array | null = null;
+    if (c.kind === "hashed") {
+      let d: unknown;
+      try {
+        d = await c.fusedDigest!({ commitment, commitmentHex, 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;
+        // The digest the caller named is the row's origin; it must be these bytes' own.
+        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, original);
+      let fused: Uint8Array;
+      try {
+        fused = await builder({ commitment, commitmentHex, originDigest: c.originDigest, slot });
+      } catch (err) {
+        throw new FuseError("builder-failed", `member ${i}: the builder threw: ${err instanceof Error ? err.message : String(err)}`, null, i);
+      }
+      if (!(fused instanceof Uint8Array)) throw new FuseError("builder-failed", `member ${i}: the builder must return a Uint8Array`, null, i);
+      const located = requireCommitment(c.placement, fused, commitment, i);
+      // The row's origin must be the origin the bytes embed, else the member
+      // would verify INVALID_ORIGIN_ATTRIBUTION after the slot is spent. Both
+      // facts are checked when both are present: the digest the bytes declare
+      // (container/1's payload) and the bytes they carry, compared byte for
+      // byte with the member's original rather than hashed again, so a builder
+      // cannot pack other bytes under the member's digest and leave a member no
+      // original rebuilds.
+      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 fused bytes embed an origin that is not the member's original; ${expiring}`, null, i);
+      }
+      artifact = await digest(fused);
+      if (keep || verifyMembers) held = fused;
     }
-    rows.push({ artifact: await digest(fused), origin: c.originDigest, placement: c.id });
-    fusedBytes.push(keep || verifyMembers ? fused : null);
+    rows.push({ artifact, origin: c.originDigest, placement: c.id });
+    fusedBytes.push(held);
     report("fuse", i + 1, checked.length);
   }
 
@@ -648,7 +779,7 @@ export async function fuseSet(members: readonly FuseSetMember[], options: FuseSe
   try {
     manifestBytes = buildSetManifest(commitment, rows);
   } catch (err) {
-    throw new FuseError("bad-input", `the set manifest could not be built: ${err instanceof Error ? err.message : String(err)}; nothing was committed and the slot will expire`);
+    throw new FuseError("bad-input", `the set manifest could not be built: ${err instanceof Error ? err.message : String(err)}; ${expiring}`);
   }
   const artifactDigestB64 = bytesToBase64(await digest(manifestBytes));
   const manifest = JSON.parse(new TextDecoder().decode(manifestBytes)) as SetManifest;
@@ -712,6 +843,7 @@ export async function fuseSet(members: readonly FuseSetMember[], options: FuseSe
       report("verify", i + 1, checked.length);
     }
     const names = c.name !== null ? fusedNamesFor(c.name, c.id) : null;
+    const held = fusedBytes[i];
     results.push({
       index: i,
       manifestIndex: k,
@@ -720,7 +852,7 @@ export async function fuseSet(members: readonly FuseSetMember[], options: FuseSe
       artifactDigestB64: memberArtifactB64,
       fusedName: names?.fusedName ?? null,
       frameName: names?.frameName ?? null,
-      ...(keep ? { fusedBytes: fusedBytes[i]! } : {}),
+      ...(keep && held !== null ? { fusedBytes: held } : {}),
       ...(verification !== undefined ? { verification } : {}),
     });
   }

package/src/index.ts

@@ -40,9 +40,9 @@ export { Constructor } from "./constructor.js";
 // The producer profile over the primitive (working name Fuse): allocate a
 // slot, write a commitment to it into the artifact, hash, commit under the
 // same slot. The resulting proof is ordinary bitgraph/1.
-export { fuse, fuseSet, MAX_SET_MEMBERS, builderFor, FuseError, digestFromBase64, placementForBytes, fusedNamesFor } from "./fuse.js";
+export { fuse, fuseSet, MAX_SET_MEMBERS, trailerBytesFor, builderFor, FuseError, digestFromBase64, placementForBytes, fusedNamesFor } from "./fuse.js";
 export type { FuseBuilder, BuilderInput, FuseOptions, FuseResult, FuseTransport, FuseErrorCode } from "./fuse.js";
-export type { FuseSetMember, SetMemberPlacement, FuseSetOptions, FuseSetProgress, FuseSetMemberResult, FuseSetResult } from "./fuse.js";
+export type { FuseSetMember, FuseSetBytesMember, FuseSetLoadedMember, FuseSetHashedMember, FusedDigestInput, SetMemberPlacement, FuseSetOptions, FuseSetProgress, FuseSetMemberResult, FuseSetResult } from "./fuse.js";
 // The verify-package types those results are made of, so the core entry names everything it returns.
 export type { FuseFrame, PlacementId, SetManifest, FuseMemberResult, FuseVerifyResult } from "@mikeargento/bitgraph-verify";