@mikeargento/bitgraph 1.3.0 → 1.4.0

package/src/fuse-cli.ts

@@ -5,8 +5,11 @@
  * bitgraph-fuse: the internal harness (spec 9.2), as a command rather than a
  * page. Exercises Forms A, B and C end to end through fuse(), writes the
  * Frame (and the fused bytes when they must be kept), and prints the bounded
- * copy of spec 9.3. `check` runs verifyFuse over a Frame (or bare proof)
- * and a file, so both verification paths can be exercised from a shell.
+ * copy of spec 9.3. `set` runs fuseSet() over N files under one slot and
+ * writes the proof beside the manifest bytes. `check` runs verifyFuse over a
+ * Frame (or bare proof) and a file, or verifyFuseMember when the proof is a
+ * set proof and the file is not its manifest, so every verification path can
+ * be exercised from a shell.
  *
  * Not a product surface. The site has no /fuse page: a page would make the
  * website build depend on packages that are not published, which is a deploy
@@ -18,9 +21,9 @@
 import { readFile, writeFile, mkdir } from "node:fs/promises";
 import { basename, extname, join, resolve } from "node:path";
 import { sha256 } from "@noble/hashes/sha256";
-import { parseFrame, verifyFuse, bytesToBase64 } from "@mikeargento/bitgraph-verify";
-import type { BitGraphProof, PlacementId } from "@mikeargento/bitgraph-verify";
-import { fuse, builderFor, FuseError } from "./fuse.js";
+import { parseFrame, verifyFuse, verifyFuseMember, bytesToBase64 } from "@mikeargento/bitgraph-verify";
+import type { BitGraphProof, PlacementId, FuseVerifyResult, FuseMemberResult } from "@mikeargento/bitgraph-verify";
+import { fuse, fuseSet, builderFor, placementForBytes, fusedNamesFor, FuseError } from "./fuse.js";
 import type { FuseTransport } from "./fuse.js";
 
 const USAGE = `bitgraph-fuse: BitGraph producer harness (profile bitgraph-fuse/1, working name)
@@ -29,12 +32,14 @@ const USAGE = `bitgraph-fuse: BitGraph producer harness (profile bitgraph-fuse/1
       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.
-  bitgraph-fuse check <frame-or-proof.json> <file> [--max-positions N]
-      Verify a Frame (or bare proof) against the fused bytes or the original.
+  bitgraph-fuse set <file>... [options]
+      N files under one slot; the committed artifact is the set manifest. The files are never modified.
+  bitgraph-fuse check <frame-or-proof.json> <file> [--manifest <set.manifest.json>] [--max-positions N]
+      Verify a Frame (or bare proof) against the fused bytes or the original; a set proof against a member or its original.
 
-Options for fuse and produce:
-  --out <dir>            where to write the Frame and fused bytes (default: .)
-  --keep                 also write the fused bytes for byte-exact placements
+Options for fuse, produce and set:
+  --out <dir>            where to write the Frame (for set: set.proof.json and set.manifest.json) and fused bytes (default: .)
+  --keep                 also write the fused bytes for byte-exact placements (set: inputs need distinct names)
   --base-url <url>       commit surface (default https://bitgraph.ing)
   --allocate-path <p>    default /api/fuse/allocate (parent-direct: /allocate-slot)
   --commit-path <p>      default /api/fuse/commit   (parent-direct: /commit)
@@ -78,6 +83,10 @@ function transportFrom(flags: Map<string, string | true>): FuseTransport {
   return t;
 }
 
+function outDirOf(args: Args): string {
+  return resolve(typeof args.flags.get("out") === "string" ? (args.flags.get("out") as string) : ".");
+}
+
 async function writeOutputs(outDir: string, label: string, frame: unknown, fusedName: string | null, fused: Uint8Array | undefined): Promise<string[]> {
   await mkdir(outDir, { recursive: true });
   const written: string[] = [];
@@ -102,8 +111,7 @@ async function runFuse(args: Args): Promise<number> {
   const fusedName = `${label.slice(0, label.length - extname(label).length)}.fused${ext}`;
   const keep = args.flags.get("keep") === true;
   const r = await fuse(builderFor(placement as PlacementId, original), { placement: placement as PlacementId, original, fusedFile: fusedName, keepFused: keep, transport: transportFrom(args.flags) });
-  const outDir = resolve(typeof args.flags.get("out") === "string" ? (args.flags.get("out") as string) : ".");
-  const written = await writeOutputs(outDir, label, r.frame, keep ? fusedName : null, r.fusedBytes);
+  const written = await writeOutputs(outDirOf(args), label, r.frame, keep ? fusedName : null, r.fusedBytes);
   report(r.proof, r.verification.category, r.recovered, true);
   process.stdout.write(`\nwrote:\n${written.map((w) => "  " + w).join("\n")}\n`);
   if (!keep) process.stdout.write(`\nThe fused bytes were not kept (${placement} is byte-exact: any verifier rebuilds them from the original and the proof). Pass --keep to write them.\n`);
@@ -114,13 +122,56 @@ async function runProduce(args: Args): Promise<number> {
   const originPath = args.flags.get("origin");
   const originDigest = typeof originPath === "string" ? sha256(new Uint8Array(await readFile(resolve(originPath)))) : undefined;
   const r = await fuse(builderFor("produced/1"), { placement: "produced/1", ...(originDigest !== undefined ? { originDigest } : {}), fusedFile: "produced.json", transport: transportFrom(args.flags) });
-  const outDir = resolve(typeof args.flags.get("out") === "string" ? (args.flags.get("out") as string) : ".");
-  const written = await writeOutputs(outDir, "produced", r.frame, "produced.json", r.fusedBytes);
+  const written = await writeOutputs(outDirOf(args), "produced", r.frame, "produced.json", r.fusedBytes);
   report(r.proof, r.verification.category, r.recovered, originDigest !== undefined);
   process.stdout.write(`\nwrote:\n${written.map((w) => "  " + w).join("\n")}\n`);
   return 0;
 }
 
+/** N files under one slot. Writes the proof and the manifest bytes exactly (they are the committed artifact, so `check` can hash them as it). */
+async function runSet(args: Args): Promise<number> {
+  if (args.positional.length === 0) { process.stderr.write(USAGE); return 64; }
+  const keep = args.flags.get("keep") === true;
+  const members = [];
+  for (const file of args.positional) {
+    const original = new Uint8Array(await readFile(resolve(file)));
+    members.push({ original, placement: placementForBytes(original), name: sanitize(basename(file)) });
+  }
+  // Under --keep every member's fused bytes go to a file named from its own
+  // name and placement; two inputs that would share that name are refused
+  // here, before any allocation, rather than one silently overwriting the other.
+  if (keep) {
+    const seen = new Map<string, number>();
+    for (const [i, m] of members.entries()) {
+      const { fusedName } = fusedNamesFor(m.name, m.placement);
+      const j = seen.get(fusedName);
+      if (j !== undefined) { process.stderr.write(`set --keep: members ${j} and ${i} would both be written as ${fusedName}; give the files distinct names\n`); return 64; }
+      seen.set(fusedName, i);
+    }
+  }
+  const r = await fuseSet(members, { keepFused: keep, transport: transportFrom(args.flags) });
+  const outDir = outDirOf(args);
+  await mkdir(outDir, { recursive: true });
+  const written: string[] = [];
+  const proofPath = join(outDir, "set.proof.json");
+  await writeFile(proofPath, JSON.stringify(r.proof, null, 2) + "\n");
+  written.push(proofPath);
+  const manifestPath = join(outDir, "set.manifest.json");
+  await writeFile(manifestPath, r.manifestBytes);
+  written.push(manifestPath);
+  for (const m of r.members) {
+    if (m.fusedBytes === undefined || m.fusedName === null) continue;
+    const p = join(outDir, m.fusedName);
+    await writeFile(p, m.fusedBytes);
+    written.push(p);
+  }
+  report(r.proof, r.verification.category, r.recovered, false);
+  for (const m of r.members) process.stdout.write(`member ${m.index}  row ${m.manifestIndex}  ${m.placement}  ${m.verification.category}  ${m.fusedName ?? ""}\n`);
+  if (!r.manifestEchoed) process.stdout.write(`note  the proof does not carry the manifest; keep set.manifest.json beside it\n`);
+  process.stdout.write(`\nwrote:\n${written.map((w) => "  " + w).join("\n")}\n`);
+  return 0;
+}
+
 function report(proof: BitGraphProof, category: string, recovered: boolean, hasOrigin: boolean): void {
   const c = proof.commit;
   if (hasOrigin) process.stdout.write(COPY_ORIGINAL + "\n\n");
@@ -134,6 +185,22 @@ function report(proof: BitGraphProof, category: string, recovered: boolean, hasO
   if (recovered) process.stdout.write(`note          the commit response was lost; the proof was read back by digest and matched on the held slot\n`);
 }
 
+/** The verdict lines shared by both verifiers; the `set` line appears only for a member verdict. */
+function printVerdict(r: FuseVerifyResult | FuseMemberResult): void {
+  process.stdout.write(`category      ${r.category}\n`);
+  process.stdout.write(`proof         ${r.proof.valid ? "valid" : `invalid: ${r.proof.reason ?? ""}`}\n`);
+  process.stdout.write(`file digest   ${r.fileDigestB64}\n`);
+  process.stdout.write(`artifact      ${r.artifactDigestB64}\n`);
+  if (r.originDigestB64) process.stdout.write(`origin        ${r.originDigestB64}\n`);
+  if (r.placement) process.stdout.write(`placement     ${r.placement}\n`);
+  if (r.span) process.stdout.write(`span          slot ${r.span.slotCounter} to commit ${r.span.commitCounter} (${r.span.positions} positions)\n`);
+  if (r.policy.maxPositions !== null) process.stdout.write(`span policy   ${r.policy.spanExceeded ? "EXCEEDED" : "within"} ${r.policy.maxPositions} positions\n`);
+  if ("set" in r && r.set?.member) process.stdout.write(`set           member ${r.set.member.index + 1} of ${r.set.memberCount}\n`);
+  if (r.reason) process.stdout.write(`reason        ${r.reason}\n`);
+  for (const s of r.statements) process.stdout.write(`\n${s}\n`);
+  process.stdout.write(`\nfloor         computed by the Player from anchors in a bundle (bitgraph-play check); not available here\n`);
+}
+
 async function runCheck(args: Args): Promise<number> {
   const [frameArg, fileArg] = args.positional;
   if (frameArg === undefined || fileArg === undefined) { process.stderr.write(USAGE); return 64; }
@@ -148,18 +215,20 @@ async function runCheck(args: Args): Promise<number> {
   }
   const bytes = new Uint8Array(await readFile(resolve(fileArg)));
   const max = args.flags.get("max-positions");
-  const r = await verifyFuse({ proof, bytes, frame, ...(typeof max === "string" ? { maxPositions: BigInt(max) } : {}) });
-  process.stdout.write(`category      ${r.category}\n`);
-  process.stdout.write(`proof         ${r.proof.valid ? "valid" : `invalid: ${r.proof.reason ?? ""}`}\n`);
-  process.stdout.write(`file digest   ${r.fileDigestB64}\n`);
-  process.stdout.write(`artifact      ${r.artifactDigestB64}\n`);
-  if (r.originDigestB64) process.stdout.write(`origin        ${r.originDigestB64}\n`);
-  if (r.placement) process.stdout.write(`placement     ${r.placement}\n`);
-  if (r.span) process.stdout.write(`span          slot ${r.span.slotCounter} to commit ${r.span.commitCounter} (${r.span.positions} positions)\n`);
-  if (r.policy.maxPositions !== null) process.stdout.write(`span policy   ${r.policy.spanExceeded ? "EXCEEDED" : "within"} ${r.policy.maxPositions} positions\n`);
-  if (r.reason) process.stdout.write(`reason        ${r.reason}\n`);
-  for (const s of r.statements) process.stdout.write(`\n${s}\n`);
-  process.stdout.write(`\nfloor         computed by the Player from anchors in a bundle (bitgraph-play check); not available here\n`);
+  const policy = typeof max === "string" ? { maxPositions: BigInt(max) } : {};
+  // A set proof and a file that is not its manifest: the member verifier answers.
+  const a = proof.attribution;
+  if (a?.name === "bitgraph-fuse/1" && a.title === "set/1" && bytesToBase64(sha256(bytes)) !== proof.artifact.digestB64) {
+    const manifestArg = args.flags.get("manifest");
+    const manifest = typeof manifestArg === "string" ? new Uint8Array(await readFile(resolve(manifestArg))) : undefined;
+    const r = await verifyFuseMember({ proof, bytes, ...(manifest !== undefined ? { manifest } : {}), ...policy });
+    printVerdict(r);
+    if (r.category === "SET_MEMBER_DIRECT" || r.category === "SET_MEMBER_FROM_ORIGIN") return r.policy.spanExceeded ? 1 : 0;
+    if (r.category === "UNDETERMINED_PLACEMENT" || r.category === "NO_MATCH") return 2;
+    return 1;
+  }
+  const r = await verifyFuse({ proof, bytes, frame, ...policy });
+  printVerdict(r);
   if (r.category === "RECORDED" || r.category === "FUSED_DIRECT" || r.category === "FUSED_FROM_ORIGIN") return r.policy.spanExceeded ? 1 : 0;
   if (r.category === "UNDETERMINED_PLACEMENT" || r.category === "NO_MATCH") return 2;
   return 1;
@@ -171,12 +240,13 @@ async function main(): Promise<number> {
     switch (args.command) {
       case "fuse": return await runFuse(args);
       case "produce": return await runProduce(args);
+      case "set": return await runSet(args);
       case "check": return await runCheck(args);
       default: process.stderr.write(USAGE); return 64;
     }
   } catch (err) {
     if (err instanceof FuseError) {
-      process.stderr.write(`no fused proof was completed (${err.code}${err.status !== null ? `, ${err.status}` : ""}): ${err.message}\n`);
+      process.stderr.write(`no fused proof was completed (${err.code}${err.status !== null ? `, ${err.status}` : ""}${err.member !== null ? `, member ${err.member}` : ""}): ${err.message}\n`);
       return err.code === "tee-restarting" ? 2 : 1;
     }
     process.stderr.write(`error: ${err instanceof Error ? err.message : String(err)}\n`);

package/src/fuse.ts

@@ -15,6 +15,16 @@
  *   4. fill:   commit that digest under the same slot, with the placement id
  *              and the origin digest in the signed attribution.
  *
+ * fuseSet(members, options): the same four beats for N files under ONE slot.
+ * The commitment is computed once and written into every member by that
+ * member's own placement; the committed artifact is the canonical set
+ * manifest (placement set/1, built by the verify package); the signed title
+ * is "set/1" with no origin, because a set has no single origin; the parsed
+ * manifest rides along as unsigned metadata. Nothing is committed unless
+ * every member's bytes carry the commitment and embed its own origin, and no
+ * proof is returned unless the manifest verifies FUSED_DIRECT and every
+ * member SET_MEMBER_DIRECT against the explicit manifest bytes.
+ *
  * What this module never does: write the nonce anywhere but process memory,
  * put it in a message, or fall back to an ordinary recording when the fused
  * commit fails. A failure is reported as a failure and the slot expires on
@@ -28,18 +38,34 @@
 import { sha256 } from "@noble/hashes/sha256";
 import {
   buildFrame,
+  buildSetManifest,
+  bytesEqual,
   bytesToBase64,
   bytesToHex,
   computeSlotCommitment,
   computeSlotRecordHash,
   fuseAttribution,
   getPlacement,
+  readSetMetadata,
+  SET_METADATA_KEY,
   verifyFuse,
+  verifyFuseMember,
   base64ToBytes,
 } from "@mikeargento/bitgraph-verify";
-import type { BitGraphProof, FuseFrame, PlacementId, SlotAllocation, FuseVerifyResult } from "@mikeargento/bitgraph-verify";
+import type {
+  BitGraphProof,
+  FuseFrame,
+  FuseMemberResult,
+  FuseVerifyResult,
+  Located,
+  Placement,
+  PlacementId,
+  SetManifest,
+  SetMember,
+  SlotAllocation,
+} from "@mikeargento/bitgraph-verify";
 
-export type { FuseFrame, PlacementId, SlotAllocation, BitGraphProof } from "@mikeargento/bitgraph-verify";
+export type { FuseFrame, PlacementId, SlotAllocation, BitGraphProof, SetManifest, FuseMemberResult, FuseVerifyResult } from "@mikeargento/bitgraph-verify";
 
 /** What the builder receives. The raw nonce is deliberately absent. */
 export interface BuilderInput {
@@ -119,11 +145,14 @@ export type FuseErrorCode =
 export class FuseError extends Error {
   readonly code: FuseErrorCode;
   readonly status: number | null;
-  constructor(code: FuseErrorCode, message: string, status: number | null = null) {
+  /** The caller's 0-based index into a set's members when the failure is one member's; null otherwise. fuse() never sets it. */
+  readonly member: number | null;
+  constructor(code: FuseErrorCode, message: string, status: number | null = null, member: number | null = null) {
     super(message);
     this.name = "FuseError";
     this.code = code;
     this.status = status;
+    this.member = member;
   }
 }
 
@@ -181,6 +210,9 @@ const DEFAULTS = {
   recoveryDelayMs: 1_500,
 } as const;
 
+/** A transport with every default filled in: what the beats below take. */
+type BoundTransport = Required<Pick<FuseTransport, keyof typeof DEFAULTS>> & FuseTransport;
+
 const B64_32 = /^[A-Za-z0-9+/]{43}=$/;
 const B64_64 = /^[A-Za-z0-9+/]{86}==$/;
 
@@ -267,23 +299,8 @@ async function recover(
   return null;
 }
 
-/**
- * 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.
- */
-export async function fuse(builder: FuseBuilder, options: FuseOptions): Promise<FuseResult> {
-  const placement = getPlacement(options.placement);
-  if (placement === undefined) throw new FuseError("bad-placement", `placement "${options.placement}" is not registered`);
-  if (placement.form !== "C" && options.original === undefined) throw new FuseError("bad-input", `${placement.id} needs the original bytes`);
-  if (placement.form === "C" && options.original !== undefined) throw new FuseError("bad-input", "produced/1 takes no original; pass originDigest to name a source");
-  if (options.originDigest !== undefined && options.originDigest.length !== 32) throw new FuseError("bad-input", "originDigest must be 32 bytes");
-
-  const t = { ...DEFAULTS, ...(options.transport ?? {}) };
-  const originDigest = options.original !== undefined ? sha256(options.original) : options.originDigest;
-  const originDigestB64 = originDigest !== undefined ? bytesToBase64(originDigest) : null;
-
-  // 1. nonce
+/** 1. nonce. The signed slot record from the boundary; it must sit on the anchored chain. */
+async function allocateSlot(t: BoundTransport): Promise<SlotAllocation> {
   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);
@@ -291,37 +308,29 @@ export async function fuse(builder: FuseBuilder, options: FuseOptions): Promise<
   const slot = (alloc.json as { slot?: unknown } | null)?.slot;
   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");
+  return slot;
+}
 
-  // 2. fuse
-  const commitment = computeSlotCommitment(slot);
-  let fused: Uint8Array;
-  try {
-    fused = await builder({ commitment, commitmentHex: bytesToHex(commitment), ...(originDigest !== undefined ? { originDigest } : {}), slot });
-  } catch (err) {
-    throw new FuseError("builder-failed", `the builder threw: ${err instanceof Error ? err.message : String(err)}`);
-  }
-  if (!(fused instanceof Uint8Array)) throw new FuseError("builder-failed", "the builder must return a Uint8Array");
-  // Fail closed: never commit bytes that do not carry the commitment.
+/**
+ * Fail closed: never commit bytes that do not carry the commitment. Returns
+ * what the placement located, for any further check. `member` names the
+ * set member the bytes belong to; null for a single fused artifact.
+ */
+function requireCommitment(placement: Placement, fused: Uint8Array, commitment: Uint8Array, member: number | null = null): Located {
   const located = placement.locate(fused);
   if (located === null || bytesToHex(located.commitment) !== bytesToHex(commitment)) {
-    throw new FuseError("commitment-missing", `the fused bytes do not carry the ${placement.id} commitment; nothing was committed and the slot will expire`);
+    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);
   }
+  return located;
+}
 
-  // 3. hash
-  const artifactDigest = sha256(fused);
-  const artifactDigestB64 = bytesToBase64(artifactDigest);
-
-  // 4. fill
-  const attribution = fuseAttribution(placement.id, originDigest);
-  const body: Record<string, unknown> = {
-    digests: [{ digestB64: artifactDigestB64, hashAlg: "sha256" }],
-    slotId: slot.nonceB64,
-    slot,
-    chainId: "bitgraph:main",
-    attribution,
-  };
-  if (options.agency !== undefined) body.agency = options.agency;
-
+/**
+ * 4. fill. Commit under the held slot; on a lost or refused response read
+ * back by digest and match the slot record; never allocate again; refuse a
+ * proof under any other slot.
+ */
+async function commitUnderSlot(t: BoundTransport, body: Record<string, unknown>, artifactDigestB64: string, slot: SlotAllocation): Promise<{ proof: BitGraphProof; recovered: boolean }> {
   let proof: BitGraphProof | null = null;
   let recovered = false;
   let commit: { status: number; json: unknown } | null = null;
@@ -356,6 +365,55 @@ export async function fuse(builder: FuseBuilder, options: FuseOptions): Promise<
   if (proof.slotAllocation?.nonceB64 !== slot.nonceB64 || proof.commit?.nonceB64 !== slot.nonceB64) {
     throw new FuseError("slot-mismatch", "the boundary returned a proof under a different slot; nothing is labelled fused");
   }
+  return { proof, recovered };
+}
+
+/**
+ * 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.
+ */
+export async function fuse(builder: FuseBuilder, options: FuseOptions): Promise<FuseResult> {
+  const placement = getPlacement(options.placement);
+  if (placement === undefined) throw new FuseError("bad-placement", `placement "${options.placement}" is not registered`);
+  if (placement.form !== "C" && options.original === undefined) throw new FuseError("bad-input", `${placement.id} needs the original bytes`);
+  if (placement.form === "C" && options.original !== undefined) throw new FuseError("bad-input", "produced/1 takes no original; pass originDigest to name a source");
+  if (options.originDigest !== undefined && options.originDigest.length !== 32) throw new FuseError("bad-input", "originDigest must be 32 bytes");
+
+  const t: BoundTransport = { ...DEFAULTS, ...(options.transport ?? {}) };
+  const originDigest = options.original !== undefined ? sha256(options.original) : options.originDigest;
+  const originDigestB64 = originDigest !== undefined ? bytesToBase64(originDigest) : null;
+
+  // 1. nonce
+  const slot = await allocateSlot(t);
+
+  // 2. fuse
+  const commitment = computeSlotCommitment(slot);
+  let fused: Uint8Array;
+  try {
+    fused = await builder({ commitment, commitmentHex: bytesToHex(commitment), ...(originDigest !== undefined ? { originDigest } : {}), slot });
+  } catch (err) {
+    throw new FuseError("builder-failed", `the builder threw: ${err instanceof Error ? err.message : String(err)}`);
+  }
+  if (!(fused instanceof Uint8Array)) throw new FuseError("builder-failed", "the builder must return a Uint8Array");
+  requireCommitment(placement, fused, commitment);
+
+  // 3. hash
+  const artifactDigest = sha256(fused);
+  const artifactDigestB64 = bytesToBase64(artifactDigest);
+
+  // 4. fill
+  const attribution = fuseAttribution(placement.id, originDigest);
+  const body: Record<string, unknown> = {
+    digests: [{ digestB64: artifactDigestB64, hashAlg: "sha256" }],
+    slotId: slot.nonceB64,
+    slot,
+    chainId: "bitgraph:main",
+    attribution,
+  };
+  if (options.agency !== undefined) body.agency = options.agency;
+  const { proof, recovered } = await commitUnderSlot(t, body, artifactDigestB64, slot);
+
   // A minted proof is verified by a reader before it is called a proof.
   const verification = await verifyFuse({ proof, bytes: fused });
   if (verification.category !== "FUSED_DIRECT") {
@@ -382,6 +440,224 @@ export async function fuse(builder: FuseBuilder, options: FuseOptions): Promise<
   };
 }
 
+// ---------------------------------------------------------------------------
+// Sets: N files fused under ONE slot
+// ---------------------------------------------------------------------------
+
+/**
+ * The most members one set takes. Measured: one canonical row is 246 bytes
+ * (container/1, the longest id this phase), so 2000 rows is 492,174 bytes.
+ * The parent refuses raw bodies over 1 MB (server.ts:249), which would land
+ * AFTER allocation and burn the slot. Half the cap is left for the slot
+ * record, an agency envelope, and future longer placement ids. 4000 rows
+ * (984 KB) leaves 63 KB and is refused; 10000 rows (2.4 MB) cannot pass at
+ * all. A test pins the budget.
+ */
+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 interface FuseSetMember {
+  /** The original bytes. Never modified. */
+  original: Uint8Array;
+  /** Default: placementForBytes(original). */
+  placement?: SetMemberPlacement;
+  /** Advisory; feeds fusedNamesFor. */
+  name?: string;
+  /** Default: builderFor(placement, original). The locate and origin guards run regardless. */
+  builder?: FuseBuilder;
+}
+
+export interface FuseSetOptions {
+  /** Return each member's fused bytes. Default false: they are virtual, rebuilt from the original and the proof. */
+  keepFused?: boolean;
+  /** Actor-bound commits: an agency envelope passed through untouched. */
+  agency?: unknown;
+  transport?: FuseTransport;
+}
+
+export interface FuseSetMemberResult {
+  /** The caller's index into members. */
+  index: number;
+  /** The row's position in the sorted manifest; equals verification.set.member.index. */
+  manifestIndex: number;
+  placement: SetMemberPlacement;
+  originDigestB64: string;
+  /** SHA-256 of the member's fused bytes; the row's artifact. */
+  artifactDigestB64: string;
+  /** fusedNamesFor(name, placement); null when the member has no name. */
+  fusedName: string | null;
+  /** Advisory; no Frame is written for a set member this phase. */
+  frameName: string | null;
+  /** Present only when keepFused is true. */
+  fusedBytes?: Uint8Array;
+  /** The local verification of the returned proof against this member's fused bytes. Always SET_MEMBER_DIRECT on success, with set.manifestSource "argument". */
+  verification: FuseMemberResult;
+}
+
+export interface FuseSetResult {
+  proof: BitGraphProof;
+  /** The committed artifact. Keep it beside the proof. */
+  manifestBytes: Uint8Array;
+  /** JSON.parse of manifestBytes; the exact object sent under metadata. */
+  manifest: SetManifest;
+  /** SHA-256 of manifestBytes; equals proof.artifact.digestB64. */
+  artifactDigestB64: string;
+  slotCommitmentB64: string;
+  /** In the caller's order. */
+  members: FuseSetMemberResult[];
+  /** True when the commit response was lost and the proof was read back by the manifest digest. */
+  recovered: boolean;
+  /** True only when readSetMetadata(proof) is byte-equal to manifestBytes. */
+  manifestEchoed: boolean;
+  /** verifyFuse over manifestBytes. Always FUSED_DIRECT under "set/1" on success. */
+  verification: FuseVerifyResult;
+}
+
+/**
+ * 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.
+ */
+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 checked: Checked[] = [];
+  const seen = new Map<string, number>();
+  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 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 = sha256(m.original);
+    // 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);
+    if (j !== undefined) {
+      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) });
+  }
+  const t: BoundTransport = { ...DEFAULTS, ...(options.transport ?? {}) };
+
+  // 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.
+  const commitment = computeSlotCommitment(slot);
+  const commitmentHex = bytesToHex(commitment);
+  const fusedBytes: Uint8Array[] = [];
+  const rows: SetMember[] = [];
+  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, 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 !== undefined ? sha256(located.originalBytes) : undefined;
+    if ((declared !== undefined && !bytesEqual(declared, c.originDigest)) || (carried !== undefined && !bytesEqual(carried, c.originDigest))) {
+      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);
+    }
+    fusedBytes.push(fused);
+    rows.push({ artifact: sha256(fused), origin: c.originDigest, placement: c.id });
+  }
+
+  // 3. hash: the canonical manifest is the artifact
+  let manifestBytes: Uint8Array;
+  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`);
+  }
+  const artifactDigestB64 = bytesToBase64(sha256(manifestBytes));
+  const manifest = JSON.parse(new TextDecoder().decode(manifestBytes)) as SetManifest;
+
+  // 4. fill: one commit, the parsed manifest riding along as unsigned metadata
+  const body: Record<string, unknown> = {
+    digests: [{ digestB64: artifactDigestB64, hashAlg: "sha256" }],
+    slotId: slot.nonceB64,
+    slot,
+    chainId: "bitgraph:main",
+    attribution: fuseAttribution("set/1"),
+    metadata: { [SET_METADATA_KEY]: manifest },
+  };
+  if (options.agency !== undefined) body.agency = options.agency;
+  const { proof, recovered } = await commitUnderSlot(t, body, artifactDigestB64, slot);
+
+  // The manifest is verified by a reader before the proof is called a set proof.
+  const verification = await verifyFuse({ proof, bytes: manifestBytes });
+  if (verification.category !== "FUSED_DIRECT" || verification.placement !== "set/1") {
+    throw new FuseError("verification-failed", `the returned proof does not verify as a set: ${verification.category}${verification.reason ? ` (${verification.reason})` : ""}`);
+  }
+  // The echo is unsigned and advisory. Absent is normal: no production
+  // boundary returns it today (the site proxy does not forward metadata and
+  // the enclave's commitDigest action drops it); differing means a boundary
+  // rewrote the response.
+  const echoed = readSetMetadata(proof);
+  if (echoed !== null && !bytesEqual(echoed, manifestBytes)) {
+    throw new FuseError("verification-failed", `the returned proof echoes a set manifest under metadata["${SET_METADATA_KEY}"] that differs from the committed one`);
+  }
+  const manifestEchoed = echoed !== null;
+  // Every member against the explicit manifest bytes, so no verdict depends on the echo.
+  const keep = options.keepFused === true;
+  const results: FuseSetMemberResult[] = [];
+  for (let i = 0; i < checked.length; i++) {
+    const c = checked[i]!;
+    const fused = fusedBytes[i]!;
+    const memberArtifactB64 = bytesToBase64(rows[i]!.artifact);
+    const v = await verifyFuseMember({ proof, bytes: fused, manifest: manifestBytes });
+    const member = v.set?.member ?? null;
+    if (v.category !== "SET_MEMBER_DIRECT" || member === null || member.fusedDigestB64 !== memberArtifactB64) {
+      throw new FuseError("verification-failed", `member ${i}: the returned proof does not verify this member: ${v.category}${v.reason ? ` (${v.reason})` : ""}`, null, i);
+    }
+    const names = c.name !== null ? fusedNamesFor(c.name, c.id) : null;
+    results.push({
+      index: i,
+      manifestIndex: member.index,
+      placement: c.id,
+      originDigestB64: bytesToBase64(c.originDigest),
+      artifactDigestB64: memberArtifactB64,
+      fusedName: names?.fusedName ?? null,
+      frameName: names?.frameName ?? null,
+      ...(keep ? { fusedBytes: fused } : {}),
+      verification: v,
+    });
+  }
+  return {
+    proof,
+    manifestBytes,
+    manifest,
+    artifactDigestB64,
+    slotCommitmentB64: bytesToBase64(commitment),
+    members: results,
+    recovered,
+    manifestEchoed,
+    verification,
+  };
+}
+
 /** Decode a standard-base64 digest, for callers holding one as text. */
 export function digestFromBase64(b64: string): Uint8Array {
   const d = base64ToBytes(b64);

package/src/index.ts

@@ -40,8 +40,11 @@ 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, builderFor, FuseError, digestFromBase64, placementForBytes, fusedNamesFor } from "./fuse.js";
+export { fuse, fuseSet, MAX_SET_MEMBERS, builderFor, FuseError, digestFromBase64, placementForBytes, fusedNamesFor } from "./fuse.js";
 export type { FuseBuilder, BuilderInput, FuseOptions, FuseResult, FuseTransport, FuseErrorCode } from "./fuse.js";
+export type { FuseSetMember, SetMemberPlacement, FuseSetOptions, 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";
 
 // Policy parsing, hashing, and validation
 export {