@mikeargento/bitgraph 1.1.1 → 1.2.0

package/src/fuse-cli.ts

@@ -0,0 +1,187 @@
+#!/usr/bin/env node
+// Copyright (c) Mike Argento. All rights reserved. See LICENSE.
+
+/**
+ * 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.
+ *
+ * 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
+ * hazard; this command needs nothing but the repository.
+ *
+ * The raw nonce is never printed. After commit it is public inside the proof.
+ */
+
+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 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]
+      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.
+
+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
+  --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)
+  --api-key <key>        Authorization: Bearer <key>
+
+Exit codes: 0 fused/verified, 1 refused or contradicted, 2 undetermined, 64 usage.
+`;
+
+/** The bounded copy of spec 9.3, verbatim. */
+const COPY_ORIGINAL = "Original recorded\nThese exact original bytes existed no later than the commit.";
+const COPY_FUSED = "Fused artifact created\nThese bytes were assembled after their slot allocation and committed at this position.";
+
+interface Args { command: string; positional: string[]; flags: Map<string, string | true> }
+
+function parseArgs(argv: string[]): Args {
+  const [command = "", ...rest] = argv;
+  const positional: string[] = [];
+  const flags = new Map<string, string | true>();
+  for (let i = 0; i < rest.length; i++) {
+    const a = rest[i]!;
+    if (a.startsWith("--")) {
+      const key = a.slice(2);
+      const next = rest[i + 1];
+      if (next !== undefined && !next.startsWith("--") && key !== "keep") { flags.set(key, next); i++; } else flags.set(key, true);
+    } else positional.push(a);
+  }
+  return { command, positional, flags };
+}
+
+function sanitize(name: string): string {
+  return name.replace(/[\x00-\x1f\x7f/]/g, " ").trim() || "artifact";
+}
+
+function transportFrom(flags: Map<string, string | true>): FuseTransport {
+  const t: FuseTransport = {};
+  const s = (k: string) => { const v = flags.get(k); return typeof v === "string" ? v : undefined; };
+  const baseUrl = s("base-url"); if (baseUrl) t.baseUrl = baseUrl;
+  const allocatePath = s("allocate-path"); if (allocatePath) t.allocatePath = allocatePath;
+  const commitPath = s("commit-path"); if (commitPath) t.commitPath = commitPath;
+  const apiKey = s("api-key"); if (apiKey) t.apiKey = apiKey;
+  return t;
+}
+
+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[] = [];
+  const framePath = join(outDir, `${label}.bitgraph-fuse.json`);
+  await writeFile(framePath, JSON.stringify(frame, null, 2) + "\n");
+  written.push(framePath);
+  if (fused !== undefined && fusedName !== null) {
+    const p = join(outDir, fusedName);
+    await writeFile(p, fused);
+    written.push(p);
+  }
+  return written;
+}
+
+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; }
+  const original = new Uint8Array(await readFile(resolve(file)));
+  const label = sanitize(basename(file));
+  const ext = placement === "trailer/1" ? extname(label) : ".tar";
+  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);
+  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`);
+  return 0;
+}
+
+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);
+  report(r.proof, r.verification.category, r.recovered, originDigest !== undefined);
+  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");
+  process.stdout.write(COPY_FUSED + "\n\n");
+  process.stdout.write(`verification  ${category}\n`);
+  process.stdout.write(`slot          ${c.slotCounter ?? "?"}\n`);
+  process.stdout.write(`commit        ${c.counter ?? "?"}\n`);
+  process.stdout.write(`epoch         ${c.epochId ?? "?"}\n`);
+  process.stdout.write(`artifact      ${proof.artifact.digestB64}\n`);
+  if (proof.attribution?.message) process.stdout.write(`origin        ${proof.attribution.message}\n`);
+  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`);
+}
+
+async function runCheck(args: Args): Promise<number> {
+  const [frameArg, fileArg] = args.positional;
+  if (frameArg === undefined || fileArg === undefined) { process.stderr.write(USAGE); return 64; }
+  const text = await readFile(resolve(frameArg), "utf8");
+  const frame = parseFrame(text);
+  let proof: BitGraphProof;
+  if (frame !== null) proof = frame.proof;
+  else {
+    const parsed = JSON.parse(text) as { version?: unknown };
+    if (parsed?.version !== "bitgraph/1") { process.stderr.write("not a Frame and not a bitgraph/1 proof\n"); return 64; }
+    proof = parsed as unknown as BitGraphProof;
+  }
+  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`);
+  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;
+}
+
+async function main(): Promise<number> {
+  const args = parseArgs(process.argv.slice(2));
+  try {
+    switch (args.command) {
+      case "fuse": return await runFuse(args);
+      case "produce": return await runProduce(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`);
+      return err.code === "tee-restarting" ? 2 : 1;
+    }
+    process.stderr.write(`error: ${err instanceof Error ? err.message : String(err)}\n`);
+    return 1;
+  }
+}
+
+main().then((code) => { process.exitCode = code; });

package/src/fuse.ts

@@ -0,0 +1,356 @@
+// Copyright (c) Mike Argento. All rights reserved. See LICENSE.
+
+/**
+ * fuse(builder, options): the producer interface of the bitgraph-fuse/1
+ * profile (working name; outwardly this is simply BitGraph).
+ *
+ * The four beats, in order, with nothing else in between:
+ *   1. nonce:  allocate a slot; the enclave signs a record that contains no
+ *              artifact data and hands back a nonce that is a bearer ticket
+ *              until it is consumed.
+ *   2. fuse:   hand the COMMITMENT to that record (never the raw nonce) to the
+ *              builder, which writes it into the artifact it is producing and
+ *              returns the finished bytes.
+ *   3. hash:   SHA-256 of the fused bytes.
+ *   4. fill:   commit that digest under the same slot, with the placement id
+ *              and the origin digest in the signed attribution.
+ *
+ * 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
+ * its own.
+ *
+ * Transport: the site's proxy routes by default (POST /api/fuse/allocate and
+ * /api/fuse/commit, behind the anchor-first gate), configurable so a licensee
+ * can point it at a parent directly.
+ */
+
+import { sha256 } from "@noble/hashes/sha256";
+import {
+  buildFrame,
+  bytesToBase64,
+  bytesToHex,
+  computeSlotCommitment,
+  computeSlotRecordHash,
+  fuseAttribution,
+  getPlacement,
+  verifyFuse,
+  base64ToBytes,
+} from "@mikeargento/bitgraph-verify";
+import type { BitGraphProof, FuseFrame, PlacementId, SlotAllocation, FuseVerifyResult } from "@mikeargento/bitgraph-verify";
+
+export type { FuseFrame, PlacementId, SlotAllocation, BitGraphProof } from "@mikeargento/bitgraph-verify";
+
+/** What the builder receives. The raw nonce is deliberately absent. */
+export interface BuilderInput {
+  /** 32-byte commitment to the signed slot record. Write this into the artifact. */
+  commitment: Uint8Array;
+  commitmentHex: string;
+  /** 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. */
+  slot: SlotAllocation;
+}
+
+/** Produces the finished (fused) bytes from the commitment. */
+export type FuseBuilder = (input: BuilderInput) => Uint8Array | Promise<Uint8Array>;
+
+export interface FuseTransport {
+  /** Origin of the commit surface. Default "https://bitgraph.ing". */
+  baseUrl?: string;
+  /** Default "/api/fuse/allocate". A parent-direct licensee uses "/allocate-slot". */
+  allocatePath?: string;
+  /** Default "/api/fuse/commit". A parent-direct licensee uses "/commit". */
+  commitPath?: string;
+  /** Default "/api/proofs/": the by-digest lookup used to recover a lost commit response. */
+  lookupPath?: string;
+  apiKey?: string;
+  fetch?: typeof fetch;
+  /** Per-request timeout. Default 30 s. */
+  timeoutMs?: number;
+  /** Lost-response recovery: how many by-digest reads to attempt, and the wait between them. */
+  recoveryAttempts?: number;
+  recoveryDelayMs?: number;
+}
+
+export interface FuseOptions {
+  /** A registered placement id: "trailer/1", "container/1", or "produced/1". */
+  placement: PlacementId;
+  /** Forms A and B: the original bytes. Never modified. Absent for Form C. */
+  original?: Uint8Array;
+  /** Form C only: a source the produced artifact references, if any. */
+  originDigest?: Uint8Array;
+  /** Filename recorded in the Frame manifest (advisory). */
+  fusedFile?: string | null;
+  /** Return the fused bytes in the result. Default: true for placements that are not byte-exact, false otherwise. */
+  keepFused?: boolean;
+  /** Actor-bound commits: an agency envelope passed through untouched. */
+  agency?: unknown;
+  transport?: FuseTransport;
+}
+
+export interface FuseResult {
+  frame: FuseFrame;
+  proof: BitGraphProof;
+  artifactDigestB64: string;
+  originDigestB64: string | null;
+  /** Present when keepFused is true (or defaulted to true). */
+  fusedBytes?: Uint8Array;
+  /** True when the commit response was lost and the proof was read back by digest. */
+  recovered: boolean;
+  /** The local verification of the returned proof against the fused bytes. Always FUSED_DIRECT on success. */
+  verification: FuseVerifyResult;
+}
+
+export type FuseErrorCode =
+  | "bad-placement"
+  | "bad-input"
+  | "allocate-failed"
+  | "builder-failed"
+  | "commitment-missing"
+  | "commit-refused"
+  | "slot-unavailable"
+  | "tee-restarting"
+  | "network"
+  | "slot-mismatch"
+  | "verification-failed"
+  | "transport";
+
+export class FuseError extends Error {
+  readonly code: FuseErrorCode;
+  readonly status: number | null;
+  constructor(code: FuseErrorCode, message: string, status: number | null = null) {
+    super(message);
+    this.name = "FuseError";
+    this.code = code;
+    this.status = status;
+  }
+}
+
+/** A builder for a registered placement over an existing original (Forms A and B), or for a bare Form C payload. */
+export function builderFor(placement: PlacementId, original?: Uint8Array): FuseBuilder {
+  const p = getPlacement(placement);
+  if (p === undefined) throw new FuseError("bad-placement", `placement "${placement}" is not registered`);
+  return ({ commitment, originDigest }) => {
+    if (original !== undefined) return p.build({ original, originDigest: originDigest ?? sha256(original), commitment });
+    return p.build(originDigest !== undefined ? { originDigest, commitment } : { commitment });
+  };
+}
+
+const DEFAULTS = {
+  baseUrl: "https://bitgraph.ing",
+  allocatePath: "/api/fuse/allocate",
+  commitPath: "/api/fuse/commit",
+  lookupPath: "/api/proofs/",
+  timeoutMs: 30_000,
+  recoveryAttempts: 5,
+  recoveryDelayMs: 1_500,
+} as const;
+
+const B64_32 = /^[A-Za-z0-9+/]{43}=$/;
+const B64_64 = /^[A-Za-z0-9+/]{86}==$/;
+
+function isSlotRecord(x: unknown): x is SlotAllocation {
+  if (x === null || typeof x !== "object" || Array.isArray(x)) return false;
+  const s = x as Record<string, unknown>;
+  return (
+    s.version === "bitgraph/slot/1" &&
+    typeof s.nonceB64 === "string" && B64_32.test(s.nonceB64) &&
+    typeof s.counter === "string" && /^(0|[1-9][0-9]*)$/.test(s.counter) &&
+    typeof s.epochId === "string" && typeof s.publicKeyB64 === "string" &&
+    typeof s.signatureB64 === "string" && B64_64.test(s.signatureB64)
+  );
+}
+
+function toUrlSafe(b64: string): string {
+  return b64.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+async function request(
+  t: Required<Pick<FuseTransport, "baseUrl" | "timeoutMs">> & FuseTransport,
+  path: string,
+  init: { method: "GET" | "POST"; body?: unknown },
+): Promise<{ status: number; json: unknown; headers: Headers }> {
+  const f = t.fetch ?? fetch;
+  const headers: Record<string, string> = {};
+  if (init.body !== undefined) headers["Content-Type"] = "application/json";
+  if (t.apiKey) headers["Authorization"] = `Bearer ${t.apiKey}`;
+  let res: Response;
+  try {
+    res = await f(`${t.baseUrl}${path}`, {
+      method: init.method,
+      headers,
+      ...(init.body !== undefined ? { body: JSON.stringify(init.body) } : {}),
+      signal: AbortSignal.timeout(t.timeoutMs),
+    });
+  } catch (err) {
+    throw new FuseError("network", `request failed: ${err instanceof Error ? err.message : String(err)}`);
+  }
+  const text = await res.text();
+  let json: unknown = null;
+  try { json = text.length > 0 ? JSON.parse(text) : null; } catch { json = text; }
+  return { status: res.status, json, headers: res.headers };
+}
+
+function messageOf(json: unknown, fallback: string): string {
+  return json !== null && typeof json === "object" && typeof (json as { error?: unknown }).error === "string" ? (json as { error: string }).error : fallback;
+}
+
+function codeOf(json: unknown): string | null {
+  return json !== null && typeof json === "object" && typeof (json as { code?: unknown }).code === "string" ? (json as { code: string }).code : null;
+}
+
+/**
+ * Read the proof back by digest after a lost or refused commit: the ONE proof
+ * whose commit.slotHashB64 is the hash of the slot record we hold. Any other
+ * proof of the same digest is a different recording under a different slot.
+ * Never allocates.
+ */
+async function recover(
+  t: Required<Pick<FuseTransport, "baseUrl" | "timeoutMs" | "recoveryAttempts" | "recoveryDelayMs" | "lookupPath">> & FuseTransport,
+  artifactDigestB64: string,
+  slot: SlotAllocation,
+): Promise<BitGraphProof | null> {
+  const expectedSlotHash = bytesToBase64(computeSlotRecordHash(slot));
+  for (let attempt = 0; attempt < t.recoveryAttempts; attempt++) {
+    if (attempt > 0) await sleep(t.recoveryDelayMs);
+    let r: { status: number; json: unknown };
+    try {
+      r = await request(t, `${t.lookupPath}${encodeURIComponent(toUrlSafe(artifactDigestB64))}`, { method: "GET" });
+    } catch {
+      continue;
+    }
+    if (r.status !== 200) continue;
+    const proofs = (r.json as { proofs?: Array<{ proof?: BitGraphProof }> } | null)?.proofs;
+    if (!Array.isArray(proofs)) continue;
+    for (const entry of proofs) {
+      const p = entry?.proof;
+      if (p && p.commit?.slotHashB64 === expectedSlotHash && p.commit?.nonceB64 === slot.nonceB64) return p;
+    }
+  }
+  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
+  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);
+  const slotId = (alloc.json as { slotId?: unknown } | null)?.slotId;
+  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");
+
+  // 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.
+  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`);
+  }
+
+  // 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;
+
+  let proof: BitGraphProof | null = null;
+  let recovered = false;
+  let commit: { status: number; json: unknown } | null = null;
+  try {
+    commit = await request(t, t.commitPath, { method: "POST", body });
+  } catch (err) {
+    // The request may have reached the boundary. Read back before giving up; never allocate again.
+    proof = await recover(t, artifactDigestB64, slot);
+    if (proof === null) throw err;
+    recovered = true;
+  }
+  if (proof === null && commit !== null) {
+    if (commit.status === 200) {
+      const j = commit.json as { proof?: BitGraphProof } | BitGraphProof[] | null;
+      proof = Array.isArray(j) ? (j[0] ?? null) : (j?.proof ?? null);
+      if (proof === null) throw new FuseError("commit-refused", "the commit response carried no proof", 200);
+    } else if (commit.status === 409 && codeOf(commit.json) === "slot-unavailable") {
+      proof = await recover(t, artifactDigestB64, slot);
+      if (proof === null) throw new FuseError("slot-unavailable", messageOf(commit.json, "the slot is no longer available"), 409);
+      recovered = true;
+    } else if (commit.status === 503 && codeOf(commit.json) === "tee-restarting") {
+      proof = await recover(t, artifactDigestB64, slot);
+      if (proof === null) throw new FuseError("tee-restarting", messageOf(commit.json, "the boundary is restarting"), 503);
+      recovered = true;
+    } else {
+      throw new FuseError("commit-refused", messageOf(commit.json, `commit refused (${commit.status})`), commit.status);
+    }
+  }
+  if (proof === null) throw new FuseError("transport", "no proof");
+
+  // Never label as fused a proof under any other slot.
+  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");
+  }
+  // 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") {
+    throw new FuseError("verification-failed", `the returned proof does not verify as fused: ${verification.category}${verification.reason ? ` (${verification.reason})` : ""}`);
+  }
+
+  const frame = buildFrame({
+    proof,
+    placement: placement.id,
+    artifactDigest,
+    ...(originDigest !== undefined ? { originDigest } : {}),
+    fusedFile: options.fusedFile ?? null,
+    ...(placement.form === "C" ? { fusePayload: fused } : {}),
+  });
+  const keep = options.keepFused ?? !placement.byteExact;
+  return {
+    frame,
+    proof,
+    artifactDigestB64,
+    originDigestB64,
+    ...(keep ? { fusedBytes: fused } : {}),
+    recovered,
+    verification,
+  };
+}
+
+/** Decode a standard-base64 digest, for callers holding one as text. */
+export function digestFromBase64(b64: string): Uint8Array {
+  const d = base64ToBytes(b64);
+  if (d === null || d.length !== 32) throw new FuseError("bad-input", "not a 32-byte base64 digest");
+  return d;
+}

package/src/index.ts

@@ -37,6 +37,12 @@ export type { HostCapabilities } from "./host.js";
 // Constructor (write path)
 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 } from "./fuse.js";
+export type { FuseBuilder, BuilderInput, FuseOptions, FuseResult, FuseTransport, FuseErrorCode } from "./fuse.js";
+
 // Policy parsing, hashing, and validation
 export {
   parsePolicy,

package/dist/canonical.d.ts

@@ -1,54 +0,0 @@
-/**
- * bitgraph-core canonical serialization
- *
- * Produces a deterministic, UTF-8 encoded JSON byte sequence from an
- * arbitrary JavaScript value.  The output is used as the signing input
- * for BitGraphProof signatures and must be reproduced identically by any
- * verifier regardless of platform or runtime.
- *
- * Algorithm:
- *   1. Recursively sort object keys lexicographically (Unicode code-point order)
- *   2. Serialize with JSON.stringify (no whitespace)
- *   3. Encode the resulting string as UTF-8
- *
- * Constraints satisfied:
- *   - Deterministic key ordering
- *   - No whitespace variance
- *   - Stable numeric formatting (JSON.stringify uses shortest representation)
- *   - UTF-8 output (TextEncoder default)
- *   - Rejects undefined, functions, and symbols, which have no JSON repr
- *
- * Limitations:
- *   - BigInt is not serializable via JSON.stringify; callers must convert
- *     to string before passing (consistent with the `counter` field type).
- *   - NaN and Infinity serialize as `null` in JSON; callers must validate
- *     numeric fields upstream.
- *   - Object prototype chains are not walked; only own enumerable keys.
- *
- * This module has zero dependencies on other bitgraph-core modules so that it
- * can be used standalone for testing and external verification tooling.
- */
-/**
- * Serialize `obj` to canonical JSON and return UTF-8 encoded bytes.
- *
- * Throws if `obj` contains values that cannot survive a JSON round-trip
- * without information loss (undefined top-level, functions, symbols, BigInt).
- */
-export declare function canonicalize(obj: unknown): Uint8Array;
-/**
- * Serialize `obj` to a canonical JSON string.
- * Exposed for debugging and test assertions.
- */
-export declare function canonicalizeToString(obj: unknown): string;
-/**
- * Compare two Uint8Arrays in constant time.
- *
- * Returns true iff `a` and `b` have the same length and identical contents.
- * Resistance against timing side-channels is important when comparing
- * digests and signatures in the verifier.
- *
- * Note: JavaScript runtimes may still optimize this; a native binding would
- * provide stronger guarantees.  For v0.1 this is a reasonable best-effort.
- */
-export declare function constantTimeEqual(a: Uint8Array, b: Uint8Array): boolean;
-//# sourceMappingURL=canonical.d.ts.map

package/dist/canonical.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"canonical.d.ts","sourceRoot":"","sources":["../src/canonical.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAMH;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,OAAO,GAAG,UAAU,CAGrD;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAEzD;AA2DD;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,UAAU,GAAG,OAAO,CAUvE"}