@amalgm/shell 0.1.163 → 0.1.164-main.34182745507

package/examinations/fixtures/private-wire-authority.js

@@ -0,0 +1,1065 @@
+import assert from "node:assert/strict";
+import { createCipheriv, createHash, createHmac, randomBytes } from "node:crypto";
+import { createServer } from "node:http";
+import { inflateRawSync } from "node:zlib";
+
+import { WebSocket, WebSocketServer } from "ws";
+import {
+  acceptEntityRecord,
+  decodeInlineCargo,
+  decodeLocalEntityRecord,
+  encodeEntityRecord,
+  parseGraphHead,
+  parseGraphPage,
+  proveRootPagination,
+  recordsByRoot,
+  sameRootPages,
+  GRAPH_HEAD_KIND,
+  GRAPH_HEAD_OPERATION_KIND,
+  PROTECTED_ENVELOPE_FORMAT,
+  PROTECTED_ENVELOPE_MAGIC,
+  rootReplacementFromRecords,
+  snapshotFromRecords,
+  stableJson,
+} from "@amalgm/live";
+import { decodeBinaryFrame } from "../../dist/wire-binary.js";
+
+const sha256 = (bytes) => createHash("sha256").update(bytes).digest("hex");
+
+/** The fake plays both the gateway (key handoff, URL signing) and content
+ * storage (HTTP GET of sealed envelopes) with the production key law:
+ * per-resource key = HMAC(master, resource:id:contract). */
+const CONTENT_MASTER_KEY = Buffer.from("aa".repeat(32), "hex");
+const RESOURCE_CONTRACT = "amalgm-entity-registry@3";
+
+function resourceContentKey(resourceId) {
+  return createHmac("sha256", CONTENT_MASTER_KEY)
+    .update(`resource:${resourceId}:${RESOURCE_CONTRACT}`)
+    .digest();
+}
+
+/** Seal exactly the envelope the production gateway stores: AES-256-GCM with
+ * the AAD binding resource, contract, and purpose. Shell must refuse anything
+ * sealed under a different binding. */
+function sealContentEnvelope(resourceId, data) {
+  const iv = randomBytes(12);
+  const cipher = createCipheriv("aes-256-gcm", resourceContentKey(resourceId), iv);
+  cipher.setAAD(Buffer.from(
+    `${PROTECTED_ENVELOPE_FORMAT}:${resourceId}:${RESOURCE_CONTRACT}:entity-content`,
+    "utf8",
+  ));
+  const sealed = Buffer.concat([cipher.update(data), cipher.final()]);
+  return Buffer.concat([
+    Buffer.from(PROTECTED_ENVELOPE_MAGIC, "ascii"),
+    iv,
+    cipher.getAuthTag(),
+    sealed,
+  ]);
+}
+
+/** Shared test authority for the exact private-resource/content/mutation
+ * frames used by the production host. It also serves the direct content
+ * plane: refs answer where each sealed envelope lives — a byte range of an
+ * immutable cargo pack, or a standalone object URL — and this server answers
+ * the bytes the way content storage would, Range slices included. Additional
+ * HTTP behavior may be composed on the same server by supplying a request
+ * listener. */
+export function createPrivateWireAuthority({
+  token = "test-tunnel-token",
+  protocolVersion = 17,
+  onRequest,
+  contentPutDelayMs = 0,
+  contentPutFailures = 0,
+  contentPutFailureRetryable = true,
+  contentPutGate,
+} = {}) {
+  const contentFetches = [];
+  let activeContentFetchGate = null;
+  const serveDirectContent = async (request, response) => {
+    const [, , resourceId, kind, sha] = request.url.split("/").map(decodeURIComponent);
+    contentFetches.push({ resourceId, kind, sha256: sha });
+    const admitted = activeContentFetchGate
+      ? activeContentFetchGate({ resourceId, kind, sha256: sha })
+      : Promise.resolve();
+    try {
+      await admitted;
+    } catch {
+      response.statusCode = 503;
+      response.end();
+      return;
+    }
+    const entry = kind === "manifest"
+      ? findContent(content, { resource_id: resourceId, content_hash: sha, kind: "manifest" })
+      : findContent(content, { resource_id: resourceId, kind: "chunk", sha256: sha });
+    if (!entry) {
+      response.statusCode = 404;
+      response.end();
+      return;
+    }
+    response.statusCode = 200;
+    response.end(sealContentEnvelope(resourceId, entry.data));
+  };
+  /** Immutable pack serving: one stored byte string per cargo segment, sliced
+   * by Range exactly as content storage would. Fetch logs and the fetch gate
+   * see the pack read, not its members — that is what storage observes. */
+  const serveDirectPack = async (request, response) => {
+    const [, , resourceId, packId] = request.url.split("/").map(decodeURIComponent);
+    const range = request.headers.range;
+    contentFetches.push({ resourceId, kind: "pack", sha256: packId, range });
+    const admitted = activeContentFetchGate
+      ? activeContentFetchGate({ resourceId, kind: "pack", sha256: packId })
+      : Promise.resolve();
+    try {
+      await admitted;
+    } catch {
+      response.statusCode = 503;
+      response.end();
+      return;
+    }
+    const pack = packs.get(packId);
+    if (!pack) {
+      response.statusCode = 404;
+      response.end();
+      return;
+    }
+    const bounds = range ? /^bytes=(\d+)-(\d+)$/.exec(range) : null;
+    if (bounds) {
+      response.statusCode = 206;
+      response.end(pack.subarray(Number(bounds[1]), Number(bounds[2]) + 1));
+      return;
+    }
+    response.statusCode = 200;
+    response.end(pack);
+  };
+  const server = createServer((request, response) => {
+    if (request.url?.startsWith("/direct-content/")) {
+      void serveDirectContent(request, response);
+      return;
+    }
+    if (request.url?.startsWith("/direct-pack/")) {
+      void serveDirectPack(request, response);
+      return;
+    }
+    if (onRequest) {
+      onRequest(request, response);
+      return;
+    }
+    response.statusCode = 404;
+    response.end();
+  });
+  const sockets = new WebSocketServer({ server });
+  let current = null;
+  const content = new Map();
+  // The pack law: each cargo segment is durable as ONE immutable byte string
+  // (chunk envelopes in artifact order, manifest envelopes at the tail) and
+  // every member keeps its identity as a byte range in the location index.
+  const packs = new Map();
+  const packLocations = new Map();
+  let contentPutsInFlight = 0;
+  let maxContentPutsInFlight = 0;
+  let contentPutAttempts = 0;
+  // Every put attempt's content hash, and the hashes the committed graph
+  // claims as pages. Pages ride the same content plane as file cargo, so
+  // separating the two is the only way to ask whether the FILES moved.
+  const putAttemptHashes = [];
+  const graphPageHashes = new Set();
+  const contentInventories = [];
+  const contentSealQueries = [];
+  let onContentSealQuery = null;
+  const contentPutBatches = [];
+  const contentCargoSegments = [];
+  const contentKeyRequests = [];
+  const contentRefs = [];
+  let binaryContentPuts = 0;
+  let inlineCargoSubmits = 0;
+  // Arrival-order ledger for the transfer ordering laws: every content
+  // frame must reach the authority before the graph head that would make
+  // its records visible. Head submits are named so tests can anchor on them.
+  const frameOrder = [];
+  let remainingContentPutFailures = contentPutFailures;
+  let contentFailureRetryable = contentPutFailureRetryable;
+  let rejectMutationSubmits = false;
+  let remainingMutationSubmitFailures = 0;
+  let dropMutationAcks = 0;
+  const committedMutationAcks = new Map();
+  let deliverySequence = 0;
+  const entityRecords = [];
+  const entityHeads = new Map();
+  const entityDedup = new Map();
+  const graphMutations = [];
+  const entitySubscriptions = new Map();
+  let entitySubscribeRequests = 0;
+  sockets.on("connection", (socket, request) => {
+    assert.equal(request.headers.authorization, `Bearer ${token}`);
+    entitySubscriptions.set(socket, new Set());
+    socket.once("close", () => {
+      entitySubscriptions.delete(socket);
+    });
+    socket.on("message", (data, isBinary) => {
+      const frame = isBinary
+        ? (() => {
+          const decoded = decodeBinaryFrame(data);
+          return { ...decoded.frame, data_bin: decoded.bytes };
+        })()
+        : JSON.parse(data.toString("utf8"));
+      if (frame.type === "private.entity-content.put"
+        || frame.type === "private.entity-content.put-blocks"
+        || frame.type === "private.entity-content.put-cargo") {
+        frameOrder.push(frame.type);
+      } else if (frame.type === "shared.mutation.submit") {
+        frameOrder.push(frame.envelope?.operationKind === GRAPH_HEAD_OPERATION_KIND
+          ? "graph-head.submit"
+          : frame.type);
+      }
+      if (frame.type === "hello") {
+        socket.send(JSON.stringify({ type: "hello_ack", protocol_version: protocolVersion }));
+      } else if (frame.type === "private.resource.lookup") {
+        socket.send(JSON.stringify(current ? ready(frame.request_id, current, true) : {
+          type: "private.resource.missing",
+          request_id: frame.request_id,
+          resource_id: frame.resource_id,
+          contract: frame.contract,
+        }));
+      } else if (frame.type === "private.resource.ensure") {
+        const duplicate = current !== null;
+        if (!current) current = {
+          resourceId: frame.resource_id,
+          checksum: frame.snapshot_checksum,
+          snapshotB64: frame.snapshot_b64,
+          rootRecords: recordsByRoot(JSON.parse(
+            Buffer.from(frame.snapshot_b64, "base64").toString("utf8"),
+          ).records),
+          version: 0,
+          deliveryWatermark: 0,
+          authorityEpoch: 1,
+        };
+        socket.send(JSON.stringify(ready(frame.request_id, current, duplicate)));
+      } else if (frame.type === "private.entity-content.inventory") {
+        contentInventories.push({ ...frame });
+        const manifestKey = contentKey({
+          ...frame, kind: "manifest", part_index: 0, sha256: "",
+        });
+        const complete = content.has(manifestKey);
+        const missing = complete ? [] : frame.chunks.flatMap((chunk, index) => (
+          content.has(contentKey({
+            ...frame, kind: "chunk", part_index: index, sha256: chunk.sha256,
+          })) ? [] : [index]
+        ));
+        socket.send(JSON.stringify({
+          type: "private.entity-content.inventory-result",
+          request_id: frame.request_id,
+          content_hash: frame.content_hash,
+          complete,
+          missing,
+        }));
+      } else if (frame.type === "private.entity-content.put") {
+        // The seal frame: a manifest may only bind blocks the authority
+        // already holds, so a partial artifact can never become visible.
+        assert.equal(isBinary, true, "immutable content travels as a binary WebSocket frame");
+        assert.equal(frame.data_bin instanceof Uint8Array, true);
+        binaryContentPuts += 1;
+        contentPutAttempts += 1;
+        putAttemptHashes.push(String(frame.sha256));
+        if (remainingContentPutFailures > 0) {
+          remainingContentPutFailures -= 1;
+          socket.send(JSON.stringify({
+            type: "shared.error",
+            request_id: frame.request_id,
+            code: "shared_realtime_internal_error",
+            message: "transient object authority failure",
+            status: 503,
+            retryable: contentFailureRetryable,
+          }));
+          return;
+        }
+        contentPutsInFlight += 1;
+        maxContentPutsInFlight = Math.max(maxContentPutsInFlight, contentPutsInFlight);
+        const store = () => {
+          const data = Buffer.from(frame.data_bin);
+          assert.equal(sha256(data), frame.sha256, "a manifest seal proves its own digest");
+          const manifest = JSON.parse(data.toString("utf8"));
+          assert.equal(manifest.contentHash, frame.content_hash);
+          const absent = manifest.chunks.find((chunk) => !findContent(content, {
+            resource_id: frame.resource_id,
+            kind: "chunk",
+            sha256: chunk.sha256,
+          }));
+          if (absent) {
+            socket.send(JSON.stringify({
+              type: "shared.error",
+              request_id: frame.request_id,
+              code: "entity_content_incomplete",
+              message: `manifest names absent block ${absent.sha256}`,
+              status: 409,
+              retryable: true,
+            }));
+            contentPutsInFlight -= 1;
+            return;
+          }
+          content.set(contentKey(frame), {
+            sha256: frame.sha256,
+            bytes: frame.bytes,
+            data,
+          });
+          socket.send(JSON.stringify({
+            type: "private.entity-content.stored",
+            request_id: frame.request_id,
+            content_hash: frame.content_hash,
+            bytes: frame.bytes,
+            verify_ms: 2,
+            store_ms: 3,
+            seal_ms: 4,
+          }));
+          contentPutsInFlight -= 1;
+        };
+        const admitted = contentPutGate ? contentPutGate() : Promise.resolve();
+        void admitted.then(() => {
+          if (contentPutDelayMs > 0) setTimeout(store, contentPutDelayMs);
+          else store();
+        });
+      } else if (frame.type === "private.entity-content.put-blocks") {
+        // Provisional blocks addressed by their own digests: durable at
+        // once, bound to no artifact until some manifest seals over them.
+        assert.equal(isBinary, true, "block waves use the binary WebSocket rail");
+        assert.equal(frame.data_bin instanceof Uint8Array, true);
+        binaryContentPuts += 1;
+        contentPutBatches.push({ ...frame, data_bin: undefined });
+        contentPutAttempts += frame.blocks.length;
+        putAttemptHashes.push(...frame.blocks.map((block) => String(block.sha256)));
+        if (remainingContentPutFailures > 0) {
+          remainingContentPutFailures -= 1;
+          socket.send(JSON.stringify({
+            type: "shared.error",
+            request_id: frame.request_id,
+            code: "shared_realtime_internal_error",
+            message: "transient object authority failure",
+            status: 503,
+            retryable: contentFailureRetryable,
+          }));
+          return;
+        }
+        contentPutsInFlight += 1;
+        maxContentPutsInFlight = Math.max(maxContentPutsInFlight, contentPutsInFlight);
+        const decodedBatch = decodeWireBatch(frame);
+        const store = () => {
+          let offset = 0;
+          for (const block of frame.blocks) {
+            const bytes = Buffer.from(decodedBatch.subarray(offset, offset + block.bytes));
+            assert.equal(sha256(bytes), block.sha256, "a block wave is refused whole when a digest lies");
+            content.set(contentKey({ ...frame, kind: "chunk", sha256: block.sha256 }), {
+              sha256: block.sha256,
+              bytes: block.bytes,
+              data: bytes,
+            });
+            offset += block.bytes;
+          }
+          assert.equal(offset, frame.bytes, "block bytes cover the declared payload");
+          socket.send(JSON.stringify({
+            type: "private.entity-content.stored-blocks",
+            request_id: frame.request_id,
+            blocks: frame.blocks.length,
+            bytes: frame.bytes,
+            verify_ms: 2,
+            store_ms: 3,
+          }));
+          contentPutsInFlight -= 1;
+        };
+        const admitted = contentPutGate ? contentPutGate() : Promise.resolve();
+        void admitted.then(() => {
+          if (contentPutDelayMs > 0) setTimeout(store, contentPutDelayMs);
+          else store();
+        });
+      } else if (frame.type === "private.entity-content.put-cargo") {
+        assert.equal(isBinary, true, "cargo segments use the binary WebSocket rail");
+        assert.equal(frame.data_bin instanceof Uint8Array, true);
+        binaryContentPuts += 1;
+        contentCargoSegments.push({ ...frame, data_bin: undefined });
+        // One attempt per object the segment makes durable: every chunk plus
+        // each artifact's manifest — parity with the per-frame put rails.
+        contentPutAttempts += frame.artifacts
+          .reduce((total, artifact) => total + artifact.chunks.length + 1, 0);
+        for (const artifact of frame.artifacts) {
+          putAttemptHashes.push(String(artifact.content_hash));
+          putAttemptHashes.push(...artifact.chunks.map((chunk) => String(chunk.sha256)));
+        }
+        if (remainingContentPutFailures > 0) {
+          remainingContentPutFailures -= 1;
+          socket.send(JSON.stringify({
+            type: "shared.error",
+            request_id: frame.request_id,
+            code: "shared_realtime_internal_error",
+            message: "transient object authority failure",
+            status: 503,
+            retryable: contentFailureRetryable,
+          }));
+          return;
+        }
+        contentPutsInFlight += 1;
+        maxContentPutsInFlight = Math.max(maxContentPutsInFlight, contentPutsInFlight);
+        const decodedCargo = decodeWireBatch(frame);
+        const store = () => {
+          const packEntries = [];
+          let offset = 0;
+          for (const artifact of frame.artifacts) {
+            for (const chunk of artifact.chunks) {
+              const bytes = Buffer.from(decodedCargo.subarray(offset, offset + chunk.bytes));
+              content.set(contentKey({ ...frame, kind: "chunk", sha256: chunk.sha256 }), {
+                sha256: chunk.sha256,
+                bytes: chunk.bytes,
+                data: bytes,
+              });
+              packEntries.push({
+                kind: "block",
+                sha256: chunk.sha256,
+                envelope: sealContentEnvelope(frame.resource_id, bytes),
+              });
+              offset += chunk.bytes;
+            }
+          }
+          for (const artifact of frame.artifacts) {
+            const manifest = Buffer.from(JSON.stringify({
+              bytes: artifact.bytes,
+              chunks: artifact.chunks.map((chunk) => ({ bytes: chunk.bytes, sha256: chunk.sha256 })),
+              contentHash: artifact.content_hash,
+              contract: "amalgm-entity-content@4",
+            }), "utf8");
+            content.set(contentKey({ ...frame, kind: "manifest", content_hash: artifact.content_hash }), {
+              bytes: manifest.length,
+              data: manifest,
+            });
+            packEntries.push({
+              kind: "manifest",
+              sha256: artifact.content_hash,
+              envelope: sealContentEnvelope(frame.resource_id, manifest),
+            });
+          }
+          assert.equal(offset, frame.bytes, "cargo chunk bytes cover the declared payload");
+          // One immutable pack per segment; locations insert first-wins,
+          // exactly like the production ignore-duplicates index.
+          const packId = `pack-${packs.size}`;
+          let packOffset = 0;
+          for (const entry of packEntries) {
+            const key = `${frame.resource_id}:${entry.kind}:${entry.sha256}`;
+            if (!packLocations.has(key)) {
+              packLocations.set(key, { pack: packId, offset: packOffset, length: entry.envelope.length });
+            }
+            packOffset += entry.envelope.length;
+          }
+          packs.set(packId, Buffer.concat(packEntries.map((entry) => entry.envelope)));
+          // Distinct fixed timings so tests can prove the host folds every
+          // acknowledgement's gateway legs into its ledger, per segment.
+          socket.send(JSON.stringify({
+            type: "private.entity-content.stored-cargo",
+            request_id: frame.request_id,
+            sealed: frame.artifacts.map((artifact) => artifact.content_hash),
+            bytes: frame.bytes,
+            verify_ms: 2,
+            store_ms: 3,
+            seal_ms: 4,
+          }));
+          contentPutsInFlight -= 1;
+        };
+        const admitted = contentPutGate ? contentPutGate() : Promise.resolve();
+        void admitted.then(() => {
+          if (contentPutDelayMs > 0) setTimeout(store, contentPutDelayMs);
+          else store();
+        });
+      } else if (frame.type === "private.entity-content.sealed") {
+        // Seal evidence under the current contract: a manifest in this
+        // store. The upload planner trusts this answer alone — never graph
+        // membership — so a cutover wipe forces re-upload.
+        contentSealQueries.push({ ...frame });
+        // The seal query is the first upload frame — after capture, before
+        // any source byte is read. Tests hook it to move the ground inside
+        // exactly that window.
+        onContentSealQuery?.(frame);
+        socket.send(JSON.stringify({
+          type: "private.entity-content.sealed-result",
+          request_id: frame.request_id,
+          sealed: frame.content_hashes.filter((hash) => findContent(content, {
+            resource_id: frame.resource_id,
+            content_hash: hash,
+            kind: "manifest",
+          })),
+          // Placement, per the production axiom: a manifest location row
+          // proves the artifact's whole packed closure, because put-cargo
+          // records every location before sealing.
+          packed: frame.content_hashes.filter((hash) =>
+            packLocations.has(`${frame.resource_id}:manifest:${hash}`)),
+        }));
+      } else if (frame.type === "private.entity-content.key") {
+        contentKeyRequests.push({ ...frame });
+        socket.send(JSON.stringify({
+          type: "private.entity-content.key-material",
+          request_id: frame.request_id,
+          resource_id: frame.resource_id,
+          contract: RESOURCE_CONTRACT,
+          key_hex: resourceContentKey(frame.resource_id).toString("hex"),
+        }));
+      } else if (frame.type === "private.entity-content.refs") {
+        // Where each object's sealed envelope lives: packed objects answer
+        // their pack's URL (signed once per batch, however many members)
+        // plus the byte range; objects with no location row answer a
+        // standalone whole-object URL.
+        contentRefs.push({ ...frame });
+        const port = server.address().port;
+        const urls = [];
+        const urlIndex = new Map();
+        const indexOf = (path) => {
+          let index = urlIndex.get(path);
+          if (index === undefined) {
+            index = urls.length;
+            urlIndex.set(path, index);
+            urls.push(`http://127.0.0.1:${port}${path}`);
+          }
+          return index;
+        };
+        const refs = frame.objects.map((object) => {
+          const packed = packLocations.get(`${frame.resource_id}:${object.kind}:${object.sha256}`);
+          if (packed) {
+            return {
+              url: indexOf(`/direct-pack/${encodeURIComponent(frame.resource_id)}/${packed.pack}`),
+              offset: packed.offset,
+              length: packed.length,
+            };
+          }
+          return {
+            url: indexOf([
+              "/direct-content",
+              encodeURIComponent(frame.resource_id),
+              object.kind,
+              object.sha256,
+            ].join("/")),
+          };
+        });
+        socket.send(JSON.stringify({
+          type: "private.entity-content.refs-result",
+          request_id: frame.request_id,
+          resource_id: frame.resource_id,
+          urls,
+          refs,
+          expires_in_seconds: 300,
+        }));
+      } else if (frame.type === "shared.mutation.submit") {
+        if (rejectMutationSubmits) {
+          socket.send(JSON.stringify({
+            type: "shared.error",
+            request_id: frame.request_id,
+            code: "shared_realtime_internal_error",
+            message: "synthetic graph commit failure",
+            status: 503,
+            retryable: false,
+          }));
+          return;
+        }
+        if (remainingMutationSubmitFailures > 0) {
+          remainingMutationSubmitFailures -= 1;
+          socket.send(JSON.stringify({
+            type: "shared.error",
+            request_id: frame.request_id,
+            code: "shared_database_serialization_failure",
+            message: "synthetic transient graph commit failure",
+            status: 503,
+            retryable: true,
+          }));
+          return;
+        }
+        const envelope = frame.envelope;
+        // Every operation travels inline now: a graph head names pages instead
+        // of carrying records, so it is small by construction.
+        assert.ok(
+          Buffer.byteLength(JSON.stringify(envelope.operation), "utf8") <= 8 * 1024 * 1024,
+          "an inline operation obeys the per-message law",
+        );
+        // The production commit RPC is idempotent on mutation_id: a replayed
+        // known mutation returns its original acknowledgement as a duplicate
+        // instead of committing twice.
+        const committed = committedMutationAcks.get(envelope.mutationId);
+        if (committed) {
+          socket.send(JSON.stringify({
+            ...committed,
+            request_id: frame.request_id,
+            duplicate: true,
+          }));
+          return;
+        }
+        assert.equal(envelope.baseVersion, current.version);
+        assert.equal(envelope.authorityEpoch, current.authorityEpoch);
+        assert.equal(envelope.deliveryWatermark, deliverySequence,
+          "a graph publication names the complete current delivery prefix");
+        graphMutations.push(envelope);
+        const base = Buffer.from(current.snapshotB64, "base64");
+        const baseIsHead = base.toString("utf8", 0, 128).includes(`"kind":"${GRAPH_HEAD_KIND}"`);
+        let snapshotBytes;
+        let rootRecords;
+        if (envelope.operationKind === GRAPH_HEAD_OPERATION_KIND) {
+          const committed = commitGraphHead(envelope, base, baseIsHead, current.rootRecords, content, sha256);
+          for (const root of committed.head.roots) {
+            for (const page of root.pages) graphPageHashes.add(String(page.sha256));
+          }
+          snapshotBytes = Buffer.from(stableJson(committed.head), "utf8");
+          rootRecords = committed.rootRecords;
+        } else if (envelope.operationKind === "entity.roots.replace") {
+          // The transition tail only: once a head is committed, the records
+          // shape can never return, so a late root replacement is refused
+          // rather than folded into a graph it cannot describe.
+          assert.equal(baseIsHead, false,
+            "a root replacement may not follow a committed graph head");
+          const replacement = rootReplacementFromRecords(
+            envelope.operation.rootIds,
+            envelope.operation.records,
+          );
+          const prior = snapshotFromRecords(JSON.parse(base.toString("utf8")).records);
+          const records = new Map(prior.records.map((record) => [record.uuid, record]));
+          const roots = new Set(replacement.rootIds);
+          const rootMemo = new Map();
+          const rootOf = (record) => {
+            if (rootMemo.has(record.uuid)) return rootMemo.get(record.uuid);
+            const root = record.parentUUID === null ? record.uuid : rootOf(records.get(record.parentUUID));
+            rootMemo.set(record.uuid, root);
+            return root;
+          };
+          const priorRoots = prior.records.map((record) => [record.uuid, rootOf(record)]);
+          for (const [uuid, root] of priorRoots) {
+            if (roots.has(root)) records.delete(uuid);
+          }
+          for (const record of replacement.records) records.set(record.uuid, record);
+          const folded = snapshotFromRecords([...records.values()]);
+          snapshotBytes = Buffer.from(JSON.stringify(folded));
+          rootRecords = recordsByRoot(folded.records);
+        } else {
+          assert.fail(`unsupported fake entity graph operation ${envelope.operationKind}`);
+        }
+        current = {
+          ...current,
+          snapshotB64: snapshotBytes.toString("base64"),
+          checksum: sha256(snapshotBytes),
+          rootRecords,
+          version: current.version + 1,
+          deliveryWatermark: envelope.deliveryWatermark,
+        };
+        const ack = {
+          type: "shared.mutation.ack",
+          request_id: frame.request_id,
+          resource_id: current.resourceId,
+          mutation_id: envelope.mutationId,
+          version: current.version,
+          authority_epoch: current.authorityEpoch,
+          committed_at: new Date().toISOString(),
+          delivery_watermark: current.deliveryWatermark,
+          duplicate: false,
+        };
+        committedMutationAcks.set(envelope.mutationId, ack);
+        if (dropMutationAcks > 0) {
+          // The commit landed; the acknowledgement is lost with the socket.
+          dropMutationAcks -= 1;
+          socket.close(1011, "synthetic acknowledgement loss");
+          return;
+        }
+        socket.send(JSON.stringify(ack));
+      } else if (frame.type === "entity.record.submit") {
+        const submitted = decodeLocalEntityRecord(frame.record_json);
+        assert.equal(submitted.authorityId, current.resourceId);
+        if (frame.cargo !== undefined) {
+          inlineCargoSubmits += 1;
+          const cargo = decodeInlineCargo(
+            frame.cargo,
+            frame.data_bin,
+            new Set(submitted.change.cargo.map((item) => item.contentHash)),
+            sha256,
+          );
+          for (const item of cargo) {
+            item.blocks.forEach((block, index) => {
+              content.set(contentKey({
+                resource_id: submitted.authorityId,
+                kind: "chunk",
+                sha256: item.manifest.chunks[index].sha256,
+              }), {
+                sha256: item.manifest.chunks[index].sha256,
+                bytes: block.byteLength,
+                data: Buffer.from(block),
+              });
+            });
+            const manifestBytes = Buffer.from(stableJson(item.manifest), "utf8");
+            content.set(contentKey({
+              resource_id: submitted.authorityId,
+              content_hash: item.manifest.contentHash,
+              kind: "manifest",
+            }), {
+              sha256: sha256(manifestBytes),
+              bytes: manifestBytes.byteLength,
+              data: manifestBytes,
+            });
+          }
+        }
+        // Cargo-before-record, exactly as the production authority enforces
+        // it: every cargo head must be sealed before the record is accepted.
+        const unsealed = submitted.change.cargo.find((item) => !findContent(content, {
+          resource_id: submitted.authorityId,
+          content_hash: item.contentHash,
+          kind: "manifest",
+        }));
+        if (unsealed) {
+          socket.send(JSON.stringify({
+            type: "shared.error",
+            request_id: frame.request_id,
+            code: "entity_record_cargo_missing",
+            message: "entity record cargo is incomplete",
+            status: 409,
+            retryable: true,
+          }));
+          return;
+        }
+        const key = `${submitted.entityId}\u0000${submitted.mutationId}`;
+        const decision = acceptEntityRecord({
+          submitted,
+          existing: entityDedup.get(key) ?? null,
+          headSequence: entityHeads.get(submitted.entityId) ?? 0,
+          actorId: "test-user",
+          originDeviceId: "test-computer",
+          acceptedAt: Date.now(),
+        });
+        if (decision.kind === "append") {
+          deliverySequence += 1;
+          entityHeads.set(submitted.entityId, decision.record.globalSequence);
+          entityDedup.set(key, decision.record);
+          entityRecords.push({ delivery_sequence: deliverySequence, record: decision.record });
+          for (const [peer, authorities] of entitySubscriptions) {
+            if (authorities.has(submitted.authorityId) && peer.readyState === WebSocket.OPEN) {
+              peer.send(JSON.stringify({
+                type: "entity.record.available",
+                authority_id: submitted.authorityId,
+              }));
+            }
+          }
+        }
+        socket.send(JSON.stringify({
+          type: "entity.record.ack",
+          request_id: frame.request_id,
+          record_json: encodeEntityRecord(decision.record),
+          duplicate: decision.kind === "duplicate",
+        }));
+      } else if (frame.type === "entity.record.subscribe") {
+        entitySubscribeRequests += 1;
+        entitySubscriptions.get(socket).add(frame.authority_id);
+        const records = entityRecords
+          .filter((item) => item.record.authorityId === frame.authority_id
+            && item.delivery_sequence > frame.after_delivery_sequence)
+          .slice(0, frame.limit)
+          .map((item) => ({
+            delivery_sequence: item.delivery_sequence,
+            record_json: encodeEntityRecord(item.record),
+          }));
+        socket.send(JSON.stringify({
+          type: "entity.record.subscribed",
+          request_id: frame.request_id,
+          records,
+        }));
+      } else if (frame.type === "entity.record.backfill") {
+        const records = entityRecords
+          .filter((item) => item.record.authorityId === frame.authority_id
+            && item.record.entityId === frame.entity_id
+            && item.record.globalSequence > frame.after_global_sequence
+            && item.record.globalSequence <= frame.through_global_sequence)
+          .sort((left, right) => left.record.globalSequence - right.record.globalSequence)
+          .map((item) => ({
+            delivery_sequence: item.delivery_sequence,
+            record_json: encodeEntityRecord(item.record),
+          }));
+        socket.send(JSON.stringify({
+          type: "entity.record.backfill-result",
+          request_id: frame.request_id,
+          records,
+        }));
+      }
+    });
+  });
+  return {
+    server,
+    sockets,
+    get current() { return current; },
+    /** Every accepted entity record, in acceptance order. */
+    get entityRecords() { return entityRecords.map((item) => item.record); },
+    get contentCount() { return content.size; },
+    get contentBytes() {
+      return [...content.values()].reduce((total, value) => total + value.data.length, 0);
+    },
+    contentArtifact(contentHash) {
+      if (!current) return null;
+      const manifest = findContent(content, {
+        resource_id: current.resourceId,
+        content_hash: contentHash,
+        kind: "manifest",
+      });
+      if (!manifest) return null;
+      const declaration = JSON.parse(manifest.data.toString("utf8"));
+      return Buffer.concat(declaration.chunks.map((chunk) => {
+        const found = findContent(content, {
+          resource_id: current.resourceId,
+          content_hash: contentHash,
+          kind: "chunk",
+          sha256: chunk.sha256,
+        });
+        if (!found) throw new Error(`missing fake authority block ${chunk.sha256}`);
+        return found.data;
+      }));
+    },
+    get contentPutAttempts() { return contentPutAttempts; },
+    /** Put attempts that moved file cargo. A graph that changed always seals
+     * new pages, so only this number answers whether the FILES moved. */
+    get cargoPutAttempts() {
+      return putAttemptHashes.filter((sha256) => !graphPageHashes.has(sha256)).length;
+    },
+    failNextContentPuts(count = 1, retryable = false) {
+      remainingContentPutFailures = count;
+      contentFailureRetryable = retryable;
+    },
+    setContentFetchGate(gate) {
+      activeContentFetchGate = gate ?? null;
+    },
+    rejectMutationSubmits(reject) {
+      rejectMutationSubmits = reject;
+    },
+    interceptContentSealQueries(handler) {
+      onContentSealQuery = handler;
+    },
+    failNextMutationSubmits(count = 1) {
+      remainingMutationSubmitFailures = count;
+    },
+    dropNextMutationAcks(count = 1) {
+      dropMutationAcks = count;
+    },
+    get contentInventories() { return [...contentInventories]; },
+    get contentSealQueries() { return [...contentSealQueries]; },
+    /** Simulate a content-contract cutover: the cloud graph keeps every
+     * record, but no cargo remains sealed under the current contract. The
+     * graph's own pages survive — they are what the authority stores, not
+     * cargo it seals on a machine's behalf. */
+    wipeSealedContent() {
+      for (const key of content.keys()) {
+        const [, second, third] = key.split(":");
+        if (graphPageHashes.has(second) || graphPageHashes.has(third)) continue;
+        content.delete(key);
+      }
+      // The pack index answers downloads; a wiped seal must not leave a
+      // location row resolving cargo the contract no longer holds.
+      for (const key of packLocations.keys()) {
+        const [, , sha] = key.split(":");
+        if (graphPageHashes.has(sha)) continue;
+        packLocations.delete(key);
+      }
+    },
+    /** Fabricate legacy standalone placement: the artifact is sealed — its
+     * manifest and block exist and downloads serve them as standalone
+     * objects — but no pack location rows exist, so the seal inventory
+     * answers sealed-but-not-packed. This is exactly what pre-pack uploads
+     * and inline Send cargo left behind. Small artifacts are single-chunk
+     * by construction (one chunk holds anything up to the chunk cap). */
+    adoptStandaloneArtifact(bytes) {
+      if (!current) throw new Error("no resource is registered yet");
+      const data = Buffer.from(bytes);
+      const contentHash = sha256(data);
+      content.set(contentKey({
+        resource_id: current.resourceId,
+        kind: "chunk",
+        sha256: contentHash,
+      }), { sha256: contentHash, bytes: data.length, data });
+      const manifest = Buffer.from(JSON.stringify({
+        bytes: data.length,
+        chunks: [{ bytes: data.length, sha256: contentHash }],
+        contentHash,
+        contract: "amalgm-entity-content@4",
+      }), "utf8");
+      content.set(contentKey({
+        resource_id: current.resourceId,
+        kind: "manifest",
+        content_hash: contentHash,
+      }), { bytes: manifest.length, data: manifest });
+      return contentHash;
+    },
+    /** Remove only physical location rows for one sealed artifact. Its
+     * immutable manifest and blocks remain readable as standalone objects. */
+    makeArtifactStandalone(contentHash) {
+      if (!current) throw new Error("no resource is registered yet");
+      const manifest = findContent(content, {
+        resource_id: current.resourceId,
+        content_hash: contentHash,
+        kind: "manifest",
+      });
+      if (!manifest) throw new Error(`no sealed manifest ${contentHash}`);
+      const declaration = JSON.parse(manifest.data.toString("utf8"));
+      packLocations.delete(`${current.resourceId}:manifest:${contentHash}`);
+      for (const chunk of declaration.chunks) {
+        packLocations.delete(`${current.resourceId}:block:${chunk.sha256}`);
+      }
+    },
+    /** Move one sealed artifact's whole closure into a new immutable pack.
+     * This models a legal standalone-to-pack placement convergence while a
+     * reader still holds refs from the earlier physical plan. */
+    moveArtifactToPack(contentHash) {
+      if (!current) throw new Error("no resource is registered yet");
+      const manifest = findContent(content, {
+        resource_id: current.resourceId,
+        content_hash: contentHash,
+        kind: "manifest",
+      });
+      if (!manifest) throw new Error(`no sealed manifest ${contentHash}`);
+      const declaration = JSON.parse(manifest.data.toString("utf8"));
+      const entries = declaration.chunks.map((chunk) => {
+        const found = findContent(content, {
+          resource_id: current.resourceId,
+          kind: "chunk",
+          sha256: chunk.sha256,
+        });
+        if (!found) throw new Error(`no sealed block ${chunk.sha256}`);
+        return {
+          kind: "block",
+          sha256: chunk.sha256,
+          envelope: sealContentEnvelope(current.resourceId, found.data),
+        };
+      });
+      entries.push({
+        kind: "manifest",
+        sha256: contentHash,
+        envelope: sealContentEnvelope(current.resourceId, manifest.data),
+      });
+      const packId = `moved-pack-${packs.size}`;
+      let offset = 0;
+      for (const entry of entries) {
+        packLocations.set(`${current.resourceId}:${entry.kind}:${entry.sha256}`, {
+          pack: packId,
+          offset,
+          length: entry.envelope.length,
+        });
+        offset += entry.envelope.length;
+      }
+      packs.set(packId, Buffer.concat(entries.map((entry) => entry.envelope)));
+      return packId;
+    },
+    get contentPutBatches() { return [...contentPutBatches]; },
+    get contentCargoSegments() { return [...contentCargoSegments]; },
+    get contentKeyRequests() { return [...contentKeyRequests]; },
+    get contentRefs() { return [...contentRefs]; },
+    get contentFetches() { return [...contentFetches]; },
+    get contentPacks() { return new Map(packs); },
+    get binaryContentPuts() { return binaryContentPuts; },
+    get inlineCargoSubmits() { return inlineCargoSubmits; },
+    /** Content and head frames in the exact order they arrived. */
+    get frameOrder() { return [...frameOrder]; },
+    get maxContentPutsInFlight() { return maxContentPutsInFlight; },
+    get entityRecords() {
+      return entityRecords.map((item) => ({
+        deliverySequence: item.delivery_sequence,
+        record: item.record,
+      }));
+    },
+    get entitySubscribeRequests() { return entitySubscribeRequests; },
+    get graphMutations() { return [...graphMutations]; },
+    /** Every record of the committed registry graph. A head commit names its
+     * roots as immutable pages, so this is what the authority actually holds
+     * after assembling them — the honest replacement for reading records out
+     * of an operation that no longer carries any. */
+    get graphRecords() {
+      return current ? [...current.rootRecords.values()].flat() : [];
+    },
+  };
+}
+
+function ready(requestId, current, duplicate) {
+  return {
+    type: "private.resource.ready",
+    request_id: requestId,
+    resource_id: current.resourceId,
+    authority_epoch: current.authorityEpoch,
+    head_version: current.version,
+    snapshot_version: current.version,
+    snapshot_checksum: current.checksum,
+    delivery_watermark: current.deliveryWatermark,
+    snapshot_b64: current.snapshotB64,
+    contract: "amalgm-entity-registry@3",
+    schema_version: 1,
+    duplicate,
+  };
+}
+
+/** Prove one graph-head commit the way the gateway does, and answer the head
+ * that becomes the stored snapshot. Every root the head keeps unchanged must
+ * carry the committed head's exact page list — the structural proof the
+ * publisher folded on the base it claims — every base root the head drops
+ * must be declared replaced, and every replaced root's pages must be sealed,
+ * readable, and re-prove their own identity and subtree laws. A records-shape
+ * base carries no page identities, so the first head must replace every root. */
+function commitGraphHead(envelope, base, baseIsHead, baseRecords, content, sha256Hex) {
+  const { head, replacedRootIds } = envelope.operation;
+  const replaced = new Set(replacedRootIds);
+  const basePages = new Map();
+  if (baseIsHead) {
+    for (const root of parseGraphHead(base).roots) basePages.set(root.rootId, root.pages);
+  } else {
+    for (const record of JSON.parse(base.toString("utf8")).records) {
+      if (record.parentUUID === null) basePages.set(record.uuid, null);
+    }
+  }
+  const headRoots = new Set(head.roots.map((root) => root.rootId));
+  for (const rootId of basePages.keys()) {
+    assert.ok(headRoots.has(rootId) || replaced.has(rootId),
+      `graph head drops root ${rootId} without replacing it`);
+  }
+  const rootRecords = new Map();
+  for (const root of head.roots) {
+    if (!replaced.has(root.rootId)) {
+      const pages = basePages.get(root.rootId);
+      assert.ok(pages != null,
+        `graph head root ${root.rootId} must be replaced: the base does not carry its pages`);
+      assert.ok(sameRootPages(pages, root.pages),
+        `graph head root ${root.rootId} pages do not match the committed head`);
+      rootRecords.set(root.rootId, baseRecords.get(root.rootId) ?? []);
+      continue;
+    }
+    const bytes = root.pages.map((page) => {
+      assert.ok(
+        findContent(content, {
+          resource_id: envelope.resourceId,
+          content_hash: page.sha256,
+          kind: "manifest",
+        }),
+        `graph page ${page.sha256} is not sealed`,
+      );
+      const block = findContent(content, {
+        resource_id: envelope.resourceId, kind: "chunk", sha256: page.sha256,
+      });
+      assert.ok(block, `graph page ${page.sha256} is sealed but unreadable`);
+      return block.data;
+    });
+    const assembled = root.pages.flatMap((page, index) =>
+      parseGraphPage(page, bytes[index], sha256Hex));
+    rootRecords.set(
+      root.rootId,
+      proveRootPagination(root.rootId, assembled, root.pages, sha256Hex),
+    );
+  }
+  return { head, rootRecords };
+}
+
+function contentKey(frame) {
+  if (frame.kind === "chunk") {
+    return [frame.resource_id, "block", frame.sha256].join(":");
+  }
+  return [frame.resource_id, frame.content_hash, "manifest"].join(":");
+}
+
+function findContent(content, frame) {
+  return content.get(contentKey(frame));
+}
+
+function decodeWireBatch(frame) {
+  const wireBytes = Buffer.from(frame.data_bin);
+  assert.equal(wireBytes.byteLength, frame.wire_bytes ?? frame.bytes);
+  const decoded = frame.content_encoding === undefined
+    ? wireBytes
+    : frame.content_encoding === "deflate-raw"
+      ? inflateRawSync(wireBytes, { maxOutputLength: frame.bytes })
+      : assert.fail(`unknown content encoding ${frame.content_encoding}`);
+  assert.equal(decoded.byteLength, frame.bytes);
+  return decoded;
+}