@amalgm/shell 0.1.112 → 0.1.113

package/dist/user-ground-host.js

@@ -3,7 +3,7 @@ import { existsSync, lstatSync, realpathSync, readFileSync, readdirSync, readlin
 import { open, readFile } from "node:fs/promises";
 import { basename, dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { buildUserHomeManifest, buildUserManifest, liveMachineStateDir, scopedAmalgmDir, shippedUserHomeDeclaration, } from "@amalgm/core/identity";
-import { CHUNK_BYTES, CONTENT_CONTRACT, INLINE_CARGO_MAX_BYTES, ENTITY_CLOUD_CONTRACT, ENTITY_CLOUD_SCHEMA_VERSION, artifactForRecord, canonicalVersion, checkContentManifest, classifyDirectory, classifyFile, classifyRegisteredRoot, createLocalEntityRecord, createEntityRecordAuthorityPort, convergeUserGround, decodeAcceptedEntityRecord, deriveUploadManifest, createUserGroundEnrollmentPolicy, isRepositoryMetadataEntry, indexRepositoryTerritory, downloadAll as downloadAllArtifacts, encodeEntityRecord, EntityApplyRail, EntityRecordRail, membershipHash, parseSnapshot, pathIsSuspect, planCargoWaves, PRESIGN_BATCH_OBJECTS, privateEntityResourceId, repositoryIdentityHash, rootReplacementFromRecords, sameRecords, snapshotFromRecords, stableJson, travelingRecords, upload as uploadArtifact, userGroundRecords, } from "@amalgm/live";
+import { CHUNK_BYTES, CONTENT_CONTRACT, INLINE_CARGO_MAX_BYTES, ENTITY_CLOUD_CONTRACT, ENTITY_CLOUD_SCHEMA_VERSION, artifactForRecord, canonicalVersion, checkContentManifest, classifyDirectory, classifyFile, classifyRegisteredRoot, createLocalEntityRecord, createEntityRecordAuthorityPort, convergeUserGround, decodeAcceptedEntityRecord, deriveUploadManifest, createUserGroundEnrollmentPolicy, isRepositoryMetadataEntry, indexRepositoryTerritory, downloadAll as downloadAllArtifacts, encodeEntityRecord, EntityApplyRail, EntityRecordRail, membershipHash, pathIsSuspect, planCargoWaves, PRESIGN_BATCH_OBJECTS, privateEntityResourceId, repositoryIdentityHash, sameRecords, snapshotFromRecords, stableJson, travelingRecords, upload as uploadArtifact, userGroundRecords, GRAPH_HEAD_OPERATION_KIND, } from "@amalgm/live";
 import Database from "better-sqlite3";
 import { atomicCopy, atomicWrite, ensurePrivateDir, ensureUserDir } from "./filesystem.js";
 import { emitFilesStage, } from "./files-observability.js";
@@ -22,9 +22,9 @@ import { WORKSPACE_UUID as UUID, createFilesRegisterPorts, ensureWorkspaceBindin
 import { applyRepositoryFiles, captureRepository, inspectRepositoryTransportFile, hasGitMarker, readCachedRepositoryIdentity, } from "./git-repository-host.js";
 import { gitEvidenceFingerprint, inspectGitRegistration, sameGitIdentity, } from "./git-registration-host.js";
 import { projectMaterializedGraph } from "./materialized-graph.js";
+import { graphPageIdentities, registryGraphFromSnapshot, } from "./registry-graph.js";
 import { NodeWatchHost, } from "./watching/index.js";
 import { GroundCoordinator } from "./ground-coordination.js";
-import { submitMutationOperation } from "./paged-mutation-submit.js";
 import { adoptSnapshotDeliveryBaseline } from "./snapshot-delivery-baseline.js";
 import { WireClient, WireRequestError } from "./wire-client.js";
 /** Cargo waves hold up to 16MiB of payload each; two in flight bounds the
@@ -40,6 +40,10 @@ const DIRECT_OBJECT_DOWNLOAD_CONCURRENCY = 128;
 // on the 1 GiB runtimes used for ordinary Files materialization. Small
 // objects still use the full request-concurrency window.
 const DIRECT_OBJECT_DOWNLOAD_MAX_IN_FLIGHT_BYTES = 2 * CHUNK_BYTES;
+/** Graph pages are at most a few megabytes each and a whole account is a
+ * handful of them, so a narrow lane keeps the cold read fast without holding
+ * the whole graph twice while it assembles. */
+const GRAPH_PAGE_READ_CONCURRENCY = 8;
 const DETECT_QUIET_MS = 12;
 const DETECT_MAX_DEFERRAL_MS = 75;
 const DETECT_RETRY_MS = 250;
@@ -55,13 +59,19 @@ const WALK_CAPTURE_CONCURRENCY = 8;
 const REGISTER_STALE_CAPTURE_ATTEMPTS = 3;
 const DOWNLOAD_CONTENT_RETRY_ATTEMPTS = 3;
 const APPLY_GROUND_WAIT_TIMEOUT_MS = 15_000;
+/** Load a journaled publication for replay. The records whose cargo must
+ * re-upload are already inside the publication's own bytes — its pages, or,
+ * for a row converted from the pre-page journal, the replacement operation
+ * itself — so nothing is stored twice and nothing is re-read from ground. */
 function loadSnapshotPublication(entry) {
-    const snapshotRecords = snapshotFromRecords((JSON.parse(entry.snapshotBlob.toString("utf8")).records ?? [])).records;
     const uploadIds = new Set(entry.uploadUuids);
+    const published = uploadIds.size === 0 ? [] : entry.pages.length > 0
+        ? entry.pages.flatMap((page) => JSON.parse(page.bytes.toString("utf8")))
+        : (JSON.parse(entry.operationBlob.toString("utf8")).records ?? []);
     return {
         ...entry,
-        snapshotRecords,
-        uploadRecords: snapshotRecords.filter((record) => uploadIds.has(record.uuid)),
+        uploadRecords: published.filter((record) => uploadIds.has(record.uuid)),
+        graph: null,
     };
 }
 const GROUND_ROW_COLUMNS = [
@@ -558,7 +568,7 @@ export class UserGroundHost {
                 && record.status === "active"
                 && record.payloadVersion === workspaceId);
         if (hasRegisteredBoundaryInDatabase(database, workspaceId)
-            && hasRegisteredBoundary(this.cloudState.records)) {
+            && hasRegisteredBoundary(this.cloudState.graph.records())) {
             // Already declared — but Register may only return once cargo closure
             // holds under the current content contract. The graph head can be
             // unchanged while a contract cutover moved its cargo namespace, so
@@ -740,7 +750,7 @@ export class UserGroundHost {
         if (!hasRegisteredBoundaryInDatabase(database, workspaceId)) {
             throw stageError("entity registration", new Error(`workspace ${workspaceId} and its durable reference were not recorded`));
         }
-        if (!hasRegisteredBoundary(this.cloudState.records)) {
+        if (!hasRegisteredBoundary(this.cloudState.graph.records())) {
             throw stageError("cloud graph commit", new Error(`workspace ${workspaceId} or its durable reference is absent from the committed head`));
         }
         return {
@@ -822,9 +832,10 @@ export class UserGroundHost {
             throw new Error("entity Record rail already started");
         await this.wire.open();
         // One floor, no per-feature gates: this shell and its gateway release
-        // together, and the gateway ships first. 12 = bounded cold-Register cargo
-        // waves; an older gateway cannot verify and seal that upload frame.
-        if (this.wire.protocolVersion < 12) {
+        // together, and the gateway ships first. 13 = immutable registry graph
+        // pages plus one graph-head commit; an older gateway cannot publish or
+        // resolve that representation.
+        if (this.wire.protocolVersion < 13) {
             throw new Error("gateway speaks an older wire protocol than this shell");
         }
         this.adoptCloudDeliveryBaseline(identity, this.cloudState.deliveryWatermark);
@@ -1096,7 +1107,7 @@ export class UserGroundHost {
                 }, ["private.resource.ready", "private.resource.missing"]);
                 if (frame.type === "private.resource.missing")
                     return null;
-                const ready = readyFromFrame(frame);
+                const ready = readyFromFrame(frame, await this.materializeRegistry(identity, frame));
                 this.cloudState = ready.state;
                 return ready.cloud;
             },
@@ -1111,7 +1122,7 @@ export class UserGroundHost {
                     snapshot_checksum: input.checksum,
                     snapshot_bytes: bytes.length,
                 }, ["private.resource.ready"]);
-                const ready = readyFromFrame(frame);
+                const ready = readyFromFrame(frame, await this.materializeRegistry(identity, frame));
                 const current = ready.cloud;
                 this.cloudState = ready.state;
                 const created = frame.duplicate === false;
@@ -1121,6 +1132,61 @@ export class UserGroundHost {
             },
         };
     }
+    /** The authority's stored snapshot as this machine's graph. A head names
+     * immutable pages, so every page this machine already cached is a local read
+     * and an unchanged root never crosses the network twice. */
+    async materializeRegistry(identity, frame) {
+        const resourceId = String(frame.resource_id || "");
+        return registryGraphFromSnapshot(Buffer.from(String(frame.snapshot_b64 || ""), "base64"), (refs) => this.readGraphPages(identity, resourceId, refs), sha256Hex);
+    }
+    /** Read graph pages by identity: cached pages come off local disk, the rest
+     * are fetched straight from content storage and cached on the way in. Every
+     * page is re-proven against its declared identity before it is kept. */
+    async readGraphPages(identity, resourceId, refs) {
+        const directory = graphPageCacheDir(this.cacheDir(identity));
+        const pages = new Map();
+        const missing = [];
+        for (const ref of new Map(refs.map((ref) => [ref.sha256, ref])).values()) {
+            let cached = null;
+            try {
+                cached = readFileSync(join(directory, `${ref.sha256}.bin`));
+            }
+            catch {
+                cached = null;
+            }
+            // A cache copy of the wrong size is torn evidence, never a page: fetch
+            // the immutable original instead of assembling from it.
+            if (cached && cached.byteLength === ref.bytes)
+                pages.set(ref.sha256, cached);
+            else
+                missing.push(ref);
+        }
+        if (missing.length === 0)
+            return pages;
+        const started = performance.now();
+        let fetchedBytes = 0;
+        await boundedForEach(missing, GRAPH_PAGE_READ_CONCURRENCY, async (ref) => {
+            const bytes = await retryContent(() => this.direct.fetchObject(resourceId, { kind: "block", sha256: ref.sha256 }), true);
+            if (bytes.byteLength !== ref.bytes || sha256Hex(bytes) !== ref.sha256) {
+                throw new Error(`cloud graph page ${ref.sha256} does not match its bytes`);
+            }
+            atomicWrite(join(directory, `${ref.sha256}.bin`), bytes);
+            fetchedBytes += bytes.byteLength;
+            pages.set(ref.sha256, bytes);
+        });
+        this.stage({
+            primitive: "download",
+            stage: "graph-pages",
+            status: "completed",
+            durationMs: performance.now() - started,
+            measurements: {
+                pages: refs.length,
+                fetchedPages: missing.length,
+                fetchedBytes,
+            },
+        });
+        return pages;
+    }
     localPort(identity) {
         const userRoot = this.userRoot(identity);
         const database = this.databasePath(identity);
@@ -1962,14 +2028,6 @@ export class UserGroundHost {
         if (first.resourceId !== resourceId) {
             throw new Error("local snapshot publication belongs to a different user-ground resource");
         }
-        this.cloudState = {
-            resourceId: first.resourceId,
-            authorityEpoch: first.authorityEpoch,
-            headVersion: first.baseVersion,
-            checksum: "",
-            deliveryWatermark: first.deliveryWatermark,
-            records: loadSnapshotPublication(first).snapshotRecords,
-        };
         try {
             await this.publishPendingSnapshots(identity);
         }
@@ -2001,6 +2059,12 @@ export class UserGroundHost {
                 throw error;
         }
         await this.recordRail?.flush();
+        // A replayed publication leaves no graph behind — it only ever journaled
+        // the roots it rebuilt — so the machine re-reads the authority's head
+        // before deriving the next boundary on top of it.
+        if (!this.cloudState) {
+            await this.cloudPort(identity).lookup(privateEntityResourceId(identity.userId, sha256Hex));
+        }
         const state = this.cloudState;
         if (!state)
             throw new Error("cloud state is unavailable for graph publication");
@@ -2038,24 +2102,24 @@ export class UserGroundHost {
                 ...(trace.workspaceId ? { workspaceId: trace.workspaceId } : {}),
             });
         }
-        const officialRecords = timed("officialRows", () => recordsAtDeliveryPrefix(state.records, readAcceptedResults(this.databasePath(identity), state.resourceId, state.deliveryWatermark, deliveryWatermark)));
         const localRecords = timed("groundRows", () => recordsRetainingMissingEvidence(readGroundRowsForRoots(this.databasePath(identity), "entities", publicationRootIds)
             .map(portableRecord), readGroundRowsForRoots(this.databasePath(identity), "detection_notebook", publicationRootIds)
             .map(portableRecord)));
-        const merged = timed("merge", () => mergeMaterializedRoots(officialRecords, localRecords));
-        const traveling = timed("project", () => travelingRecords(merged, sha256Hex));
+        const accepted = timed("officialRows", () => readAcceptedResults(this.databasePath(identity), state.resourceId, state.deliveryWatermark, deliveryWatermark));
+        const rebuilt = timed("merge", () => publicationRoots(state.graph, localRecords, accepted));
+        const projected = timed("project", () => new Map([...rebuilt].map(([rootId, records]) => [rootId, records.length === 0 ? records : travelingRecords(records, sha256Hex)])));
+        const traveling = [...projected.values()].flat();
         const impossibleGitLeaf = traveling.find((record) => (record.type === "file.text" || record.type === "file.binary" || record.type === "link")
             && record.payloadVersion?.startsWith("git:"));
         if (impossibleGitLeaf) {
-            const parent = merged.find((record) => record.uuid === impossibleGitLeaf.parentUUID);
+            const parent = traveling.find((record) => record.uuid === impossibleGitLeaf.parentUUID);
             throw new Error(`repository-owned leaf escaped its rail: ${impossibleGitLeaf.name} parent=${parent?.type ?? "missing"}`);
         }
-        const snapshot = timed("normalize", () => snapshotFromRecords(traveling));
-        // ONE canonical serialization: these exact bytes are the journal blob
-        // and the checksum's input; they are never re-derived or re-parsed on
-        // the in-process path.
-        const snapshotBlob = timed("serialize", () => Buffer.from(stableJson(snapshot), "utf8"));
-        const checksum = timed("checksum", () => sha256Hex(snapshotBlob));
+        // ONE canonical serialization per rebuilt root: the page bytes are the
+        // journal's payload, the upload's payload, and the head's identities.
+        // Untouched roots are not serialized, hashed, or journaled at all.
+        const publication = timed("pages", () => state.graph.rebuild(projected, sha256Hex));
+        const checksum = publication.checksum;
         const localIds = new Set(localRecords.map((record) => record.uuid));
         // Graph membership is never proof of sealed cargo: a record in the cloud
         // graph may name content sealed only under a prior content contract,
@@ -2064,11 +2128,11 @@ export class UserGroundHost {
         // sealed-first upload asks that exact question itself and moves only
         // what is unsealed, so Register always re-establishes cargo closure
         // before returning, even when the graph itself is unchanged.
-        const cargoRecords = snapshot.records.filter((record) => localIds.has(record.uuid) && artifactForRecord(record) !== null);
+        const cargoRecords = traveling.filter((record) => localIds.has(record.uuid) && artifactForRecord(record) !== null);
         if (checksum === state.checksum && deliveryWatermark === state.deliveryWatermark) {
             this.finishPreparation(trace, preparationStarted, leg, {
-                records: snapshot.records.length,
-                snapshotBytes: snapshotBlob.byteLength,
+                rebuiltRoots: rebuilt.size,
+                records: traveling.length,
                 cargoRecords: cargoRecords.length,
                 graphUnchanged: true,
             });
@@ -2085,19 +2149,12 @@ export class UserGroundHost {
             }
             return;
         }
-        const replacement = timed("replacement", () => {
-            const rootIds = localRecords
-                .filter((record) => record.parentUUID === null)
-                .map((record) => record.uuid);
-            const roots = new Set(rootIds);
-            const rootOf = recordRootResolver(snapshot.records);
-            return rootReplacementFromRecords(rootIds, snapshot.records.filter((record) => {
-                const root = rootOf(record);
-                return root !== null && roots.has(root);
-            }));
-        });
-        // The operation's canonical bytes: staged, hashed, and submitted as-is.
-        const operationBlob = timed("operation", () => Buffer.from(stableJson(replacement), "utf8"));
+        // The operation's canonical bytes: journaled and submitted as-is.
+        const operationBlob = timed("operation", () => Buffer.from(stableJson(publication.operation), "utf8"));
+        // Only pages the committed head does not already name still have to be
+        // sealed; a rebuilt root that came out byte-identical costs nothing.
+        const committed = graphPageIdentities(state.graph.head);
+        const fresh = publication.pages.filter((page) => !committed.has(page.ref.sha256));
         const entry = {
             mutationId: randomUUID(),
             resourceId: state.resourceId,
@@ -2105,30 +2162,35 @@ export class UserGroundHost {
             baseVersion: state.headVersion,
             snapshotChecksum: checksum,
             deliveryWatermark,
-            operationKind: replacement.kind,
-            replacementRootIds: replacement.rootIds,
+            operationKind: publication.operation.kind,
+            replacementRootIds: publication.operation.replacedRootIds,
             uploadUuids: cargoRecords.map((record) => record.uuid),
-            snapshotBlob,
             operationBlob,
+            pages: fresh.map((page) => ({
+                sha256: page.ref.sha256,
+                bytes: Buffer.from(page.bytes.buffer, page.bytes.byteOffset, page.bytes.byteLength),
+            })),
             status: "pending",
             submitted: false,
         };
         timed("journal", () => supersedeSnapshotJournal(this.databasePath(identity), entry));
         this.finishPreparation(trace, preparationStarted, leg, {
-            records: snapshot.records.length,
-            snapshotBytes: snapshotBlob.byteLength,
+            rebuiltRoots: rebuilt.size,
+            records: traveling.length,
+            pages: publication.pages.length,
+            freshPages: fresh.length,
+            pageBytes: fresh.reduce((total, page) => total + page.ref.bytes, 0),
             operationBytes: operationBlob.byteLength,
-            operationRoots: replacement.rootIds.length,
             cargoRecords: cargoRecords.length,
             graphUnchanged: false,
         });
-        // Publish the freshly journaled intent directly: the records are already
-        // in memory and the operation bytes already exist — nothing is re-read,
-        // re-parsed, or re-serialized between prepare and the wire.
+        // Publish the freshly journaled intent directly: the pages and the
+        // operation bytes already exist — nothing is re-read, re-parsed, or
+        // re-serialized between prepare and the wire.
         await this.publishLoadedSnapshot(identity, {
             ...entry,
-            snapshotRecords: snapshot.records,
             uploadRecords: cargoRecords,
+            graph: publication.graph,
         }, trace, manifestHints);
     }
     /** Close the graph-preparation stage with every leg it spent, so a slow
@@ -2181,8 +2243,61 @@ export class UserGroundHost {
             await this.publishLoadedSnapshot(identity, loadSnapshotPublication(pending), trace, manifestHints);
         }
     }
+    /** Seal this publication's graph pages. Pages are immutable, content
+     * addressed, and already in memory, so the authority's seal inventory alone
+     * decides what still has to move and whole pages ride cargo waves. The head
+     * may not commit until every page it newly names is sealed. */
+    async uploadGraphPages(resourceId, pages, trace) {
+        if (pages.length === 0)
+            return;
+        const started = performance.now();
+        const sealed = await this.sealedContentHashes(resourceId, pages.map((page) => page.sha256));
+        const unsealed = pages
+            .filter((page) => !sealed.has(page.sha256))
+            .map((page) => ({ page, bytes: page.bytes.byteLength }));
+        let uploadedBytes = 0;
+        await boundedForEach([...planCargoWaves(unsealed)], CARGO_UPLOAD_CONCURRENCY, async (wave) => {
+            const payload = Buffer.concat(wave.items.map((item) => item.page.bytes));
+            const encoded = await encodeContentWireBytes(payload);
+            const frame = await retryContent(() => this.wire.requestBinary({
+                type: "private.entity-content.put-cargo",
+                resource_id: resourceId,
+                // A page is a single-chunk artifact: its identity, its only chunk,
+                // and its bytes are one and the same sha.
+                artifacts: wave.items.map((item) => ({
+                    content_hash: item.page.sha256,
+                    bytes: item.bytes,
+                    chunks: [{ sha256: item.page.sha256, bytes: item.bytes }],
+                })),
+                bytes: payload.byteLength,
+                wire_bytes: encoded.bytes.byteLength,
+                ...(encoded.encoding ? { content_encoding: encoded.encoding } : {}),
+            }, encoded.bytes, ["private.entity-content.stored-cargo"]));
+            const stored = new Set(Array.isArray(frame.sealed) ? frame.sealed.map(String) : []);
+            for (const item of wave.items) {
+                if (!stored.has(item.page.sha256)) {
+                    throw new Error(`content authority did not seal graph page ${item.page.sha256}`);
+                }
+            }
+            uploadedBytes += encoded.bytes.byteLength;
+        });
+        this.stage({
+            primitive: "upload",
+            stage: "graph-pages",
+            status: "completed",
+            ...(trace?.workspaceId ? { workspaceId: trace.workspaceId } : {}),
+            durationMs: performance.now() - started,
+            measurements: {
+                journey: trace?.journey ?? "bootstrap",
+                pages: pages.length,
+                uploadedPages: unsealed.length,
+                uploadedBytes,
+            },
+        });
+    }
     async publishLoadedSnapshot(identity, publication, trace, manifestHints) {
         try {
+            await this.uploadGraphPages(publication.resourceId, publication.pages, trace);
             await this.uploadSnapshotContent(identity, publication.resourceId, publication.uploadRecords, trace, manifestHints);
         }
         catch (error) {
@@ -2218,17 +2333,25 @@ export class UserGroundHost {
             local("markSubmitted", () => markSnapshotJournalSubmitted(this.databasePath(identity), publication.mutationId));
         }
         try {
-            frame = await submitMutationOperation(this.wire, {
-                resourceId: publication.resourceId,
-                authorityEpoch: publication.authorityEpoch,
-                mutationId: publication.mutationId,
-                deviceId: identity.deviceId,
-                baseVersion: publication.baseVersion,
-                contract: ENTITY_CLOUD_CONTRACT,
-                schemaVersion: ENTITY_CLOUD_SCHEMA_VERSION,
-                operationKind: publication.operationKind,
-                deliveryWatermark: publication.deliveryWatermark,
-            }, publication.operationBlob, (leg, durationMs) => { legMs[`${leg}Ms`] = durationMs; });
+            // A head commit names pages instead of carrying records, so it is small
+            // by construction and always travels inline in one frame.
+            const submitStarted = performance.now();
+            frame = await this.wire.request({
+                type: "shared.mutation.submit",
+                envelope: {
+                    resourceId: publication.resourceId,
+                    authorityEpoch: publication.authorityEpoch,
+                    mutationId: publication.mutationId,
+                    deviceId: identity.deviceId,
+                    baseVersion: publication.baseVersion,
+                    contract: ENTITY_CLOUD_CONTRACT,
+                    schemaVersion: ENTITY_CLOUD_SCHEMA_VERSION,
+                    operationKind: publication.operationKind,
+                    deliveryWatermark: publication.deliveryWatermark,
+                    operation: JSON.parse(publication.operationBlob.toString("utf8")),
+                },
+            }, ["shared.mutation.ack"]);
+            legMs.submitMs = performance.now() - submitStarted;
         }
         catch (error) {
             if (trace?.journey === "register") {
@@ -2249,13 +2372,16 @@ export class UserGroundHost {
             }
             throw pipelineStageError("cloud graph commit", error);
         }
-        this.cloudState = {
+        // A replay carries no graph: clearing the state makes the next reader
+        // fetch the authority's own head instead of a graph missing every root
+        // this publication did not rebuild.
+        this.cloudState = publication.graph === null ? null : {
             resourceId: publication.resourceId,
             authorityEpoch: Number(frame.authority_epoch),
             headVersion: Number(frame.version),
             checksum: publication.snapshotChecksum,
             deliveryWatermark: Number(frame.delivery_watermark),
-            records: publication.snapshotRecords,
+            graph: publication.graph,
         };
         local("clearJournal", () => deleteJournalEntry(this.databasePath(identity), publication.mutationId));
         if (trace?.journey === "register") {
@@ -2263,7 +2389,7 @@ export class UserGroundHost {
             // its legs here gives one ledger line the whole story: local journal
             // marks, wire time, gateway assemble/validate, and the database RPC.
             for (const [wire, leg] of [
-                ["assemble_ms", "serverAssembleMs"],
+                ["verify_ms", "serverVerifyMs"],
                 ["validate_ms", "serverValidateMs"],
                 ["database_ms", "serverDatabaseMs"],
             ]) {
@@ -2302,6 +2428,12 @@ function contentCacheFile(cacheDir, contentHash) {
 function manifestCacheFile(cacheDir, contentHash) {
     return join(cacheDir, "manifests", `${contentHash}.json`);
 }
+/** Graph pages are immutable and content-addressed, so they cache exactly like
+ * artifacts do — in their own directory, because they are the registry's own
+ * bytes rather than any entity's cargo. */
+function graphPageCacheDir(cacheDir) {
+    return join(cacheDir, "graph-pages");
+}
 function readCachedManifest(cacheDir, contentHash) {
     try {
         const checked = checkContentManifest(JSON.parse(readFileSync(manifestCacheFile(cacheDir, contentHash), "utf8")), contentHash);
@@ -2375,118 +2507,110 @@ function assertHealthyWatch(evidence, rootId) {
  * file over a dozen times; the file itself is never deleted by the host, so
  * every later open needs only the connection and its pragmas. */
 const migratedDatabases = new Set();
-/** The journal's mutable facts and its immutable payload live in separate
- * tables on purpose: SQLite rewrites a row's entire record — overflow pages
- * included — on any column update, so flipping submitted_at on a row that
- * carried a register-scale snapshot cost a full multi-megabyte rewrite
- * through the WAL at synchronous=FULL (measured ~7.5s of the production
- * cloud-commit stage on the 1-GB machine). The blob row is written exactly
- * once and read only on restart replay; every status transition touches only
- * the small row. */
+/** A publication row holds only what the authority must be told: the small
+ * meta facts and the head-commit operation naming this graph's pages. The
+ * pages themselves are write-once rows in their own table, because a status
+ * transition rewrites its whole row — overflow pages included — through the
+ * WAL at synchronous=FULL, and page bytes must never ride that rewrite. */
 const SNAPSHOT_PUBLICATIONS_SCHEMA = `
     CREATE TABLE IF NOT EXISTS snapshot_publications (
       sequence INTEGER PRIMARY KEY AUTOINCREMENT,
       mutation_id TEXT NOT NULL UNIQUE,
       resource_id TEXT NOT NULL,
       meta_json TEXT NOT NULL,
+      operation_blob BLOB NOT NULL,
       created_at INTEGER NOT NULL,
       status TEXT NOT NULL DEFAULT 'pending' CHECK(status IN ('pending', 'rejected')),
       submitted_at INTEGER
     );
-    CREATE TABLE IF NOT EXISTS snapshot_publication_blobs (
-      mutation_id TEXT PRIMARY KEY,
-      snapshot_blob BLOB NOT NULL,
-      operation_blob BLOB NOT NULL
+    CREATE TABLE IF NOT EXISTS snapshot_publication_pages (
+      mutation_id TEXT NOT NULL,
+      page_index INTEGER NOT NULL,
+      sha256 TEXT NOT NULL,
+      bytes BLOB NOT NULL,
+      PRIMARY KEY (mutation_id, page_index)
     );`;
-/** Converts an old-shape publication journal (one nested publication_json
- * text per row) into the blob journal, atomically, preserving every row's
- * meaning. A pending row may be a submitted mutation whose outcome exists
- * only at the authority — dropping it would violate the retry law that
- * recovers a lost acknowledgement — so conversion is structural: the nested
- * snapshot text becomes the snapshot blob verbatim, the stored replacement
- * becomes the operation blob, and semantic judgment stays where it always
- * was, with the reader (an unlawful row still blocks registration rather
- * than being silently replaced).
+function legacyJournalShape(columns) {
+    if (columns.size === 0)
+        return null;
+    if (columns.has("publication_json"))
+        return "nested-text";
+    if (columns.has("snapshot_blob"))
+        return "row-blobs";
+    // The paged journal and the side-table one both keep only small columns
+    // here; only the paged one names the operation on the row itself.
+    return columns.has("operation_blob") ? null : "split-blobs";
+}
+/** Converts a pre-paged publication journal into the paged one, atomically,
+ * preserving every row's meaning. A pending row may be a submitted mutation
+ * whose outcome exists only at the authority — dropping it would violate the
+ * retry law that recovers a lost acknowledgement — so conversion is
+ * structural: each row keeps its identity, its meta facts, and the exact
+ * operation bytes it would submit, and semantic judgment stays where it
+ * always was, with the reader (an unlawful row still blocks registration
+ * rather than being silently replaced). A converted row rebuilt whole roots
+ * rather than pages, so it carries no page rows; its replayed upload comes
+ * from the records inside its own operation.
  *
  * The transform runs entirely inside SQLite. A production journal row is a
  * register-scale graph serialized three times over — the exact text whose
  * repeated JavaScript materialization blew the 512 MB heap — so no part of
- * it may ever become a JavaScript value here: json_extract lifts the nested
- * snapshot text straight into its blob, and the meta and operation rows are
- * json_object over subtrees, all in engine memory outside the V8 heap.
+ * it may ever become a JavaScript value here: json_extract lifts nested text
+ * straight into its blob and meta rows are json_object over subtrees, all in
+ * engine memory outside the V8 heap. The snapshot blob is simply not carried:
+ * the authority stores the head now, and a replay re-reads it.
  *
  * Tables older than the three-state journal carry no status or submitted_at;
  * their rows were written before the pre-submit durability mark existed, so
  * the only safe reading is "possibly submitted": keep them pending and
  * marked submitted, which replays the same mutation id — always idempotent —
- * and never supersedes. A row whose publication_json does not parse fails
- * the open loudly with the journal intact; nothing is ever deleted on a
- * conversion failure. */
-function convertLegacySnapshotJournal(database, columns) {
+ * and never supersedes. A row whose stored operation does not resolve fails
+ * the open loudly against the NOT NULL law with the journal intact; nothing
+ * is ever deleted on a conversion failure. */
+function convertLegacySnapshotJournal(database, shape, columns) {
+    const metaJson = shape === "nested-text"
+        ? `json_object(
+        'authorityEpoch', json_extract(publication_json, '$.authorityEpoch'),
+        'baseVersion', json_extract(publication_json, '$.baseVersion'),
+        'deliveryWatermark', json_extract(publication_json, '$.deliveryWatermark'),
+        'snapshotChecksum', json_extract(publication_json, '$.snapshotChecksum'),
+        'operationKind', 'entity.roots.replace',
+        'replacementRootIds', json(json_extract(publication_json, '$.replacementRootIds')),
+        'uploadUuids', coalesce((
+          SELECT json_group_array(json_extract(uploaded.value, '$.uuid'))
+            FROM json_each(publication_json, '$.uploadRecords') AS uploaded
+        ), json_array())
+      )`
+        : "meta_json";
+    const operationBlob = {
+        "nested-text": `CAST(json_object(
+        'kind', 'entity.roots.replace',
+        'rootIds', json(json_extract(publication_json, '$.replacementRootIds')),
+        'records', json(json_extract(publication_json, '$.replacementRecords'))
+      ) AS BLOB)`,
+        "row-blobs": "operation_blob",
+        "split-blobs": `(SELECT blobs.operation_blob FROM snapshot_publication_blobs AS blobs
+        WHERE blobs.mutation_id = legacy.mutation_id)`,
+    }[shape];
     database.transaction(() => {
         database.exec("ALTER TABLE snapshot_publications RENAME TO snapshot_publications_legacy");
         database.exec(SNAPSHOT_PUBLICATIONS_SCHEMA);
         database.exec(`
       INSERT INTO snapshot_publications(
-        mutation_id, resource_id, meta_json, created_at, status, submitted_at
+        mutation_id, resource_id, meta_json, operation_blob, created_at, status, submitted_at
       )
       SELECT
         mutation_id,
         resource_id,
-        json_object(
-          'authorityEpoch', json_extract(publication_json, '$.authorityEpoch'),
-          'baseVersion', json_extract(publication_json, '$.baseVersion'),
-          'deliveryWatermark', json_extract(publication_json, '$.deliveryWatermark'),
-          'snapshotChecksum', json_extract(publication_json, '$.snapshotChecksum'),
-          'operationKind', 'entity.roots.replace',
-          'replacementRootIds', json(json_extract(publication_json, '$.replacementRootIds')),
-          'uploadUuids', coalesce((
-            SELECT json_group_array(json_extract(uploaded.value, '$.uuid'))
-              FROM json_each(publication_json, '$.uploadRecords') AS uploaded
-          ), json_array())
-        ),
+        ${metaJson},
+        ${operationBlob},
         created_at,
         ${columns.has("status") ? "CASE status WHEN 'rejected' THEN 'rejected' ELSE 'pending' END" : "'pending'"},
         ${columns.has("submitted_at") ? "submitted_at" : "created_at"}
-      FROM snapshot_publications_legacy ORDER BY sequence
-    `);
-        database.exec(`
-      INSERT INTO snapshot_publication_blobs(mutation_id, snapshot_blob, operation_blob)
-      SELECT
-        mutation_id,
-        CAST(json_extract(publication_json, '$.snapshotJson') AS BLOB),
-        CAST(json_object(
-          'kind', 'entity.roots.replace',
-          'rootIds', json(json_extract(publication_json, '$.replacementRootIds')),
-          'records', json(json_extract(publication_json, '$.replacementRecords'))
-        ) AS BLOB)
-      FROM snapshot_publications_legacy ORDER BY sequence
-    `);
-        database.exec("DROP TABLE snapshot_publications_legacy");
-    })();
-}
-/** Converts the single-table blob journal (blobs stored on the publication
- * row itself) into the split journal, atomically and entirely inside SQLite —
- * the same engine-memory law as the nested-text conversion above. Every
- * field already has its final meaning; the blobs simply move to their
- * write-once table so status transitions stop rewriting them. */
-function splitSnapshotJournalBlobs(database) {
-    database.transaction(() => {
-        database.exec("ALTER TABLE snapshot_publications RENAME TO snapshot_publications_legacy");
-        database.exec(SNAPSHOT_PUBLICATIONS_SCHEMA);
-        database.exec(`
-      INSERT INTO snapshot_publications(
-        mutation_id, resource_id, meta_json, created_at, status, submitted_at
-      )
-      SELECT mutation_id, resource_id, meta_json, created_at, status, submitted_at
-        FROM snapshot_publications_legacy ORDER BY sequence
-    `);
-        database.exec(`
-      INSERT INTO snapshot_publication_blobs(mutation_id, snapshot_blob, operation_blob)
-      SELECT mutation_id, snapshot_blob, operation_blob
-        FROM snapshot_publications_legacy ORDER BY sequence
+      FROM snapshot_publications_legacy AS legacy ORDER BY sequence
     `);
         database.exec("DROP TABLE snapshot_publications_legacy");
+        database.exec("DROP TABLE IF EXISTS snapshot_publication_blobs");
     })();
 }
 /** The single opener and schema-migration entry for a user ground database.
@@ -2505,12 +2629,9 @@ export function initializeDatabase(file) {
     // how this file arrived at this process. One PRAGMA against the in-memory
     // catalog costs nothing next to the connection open itself.
     const publicationColumns = new Set(database.prepare("PRAGMA table_info(snapshot_publications)").all().map(({ name }) => name));
-    if (publicationColumns.has("publication_json")) {
-        convertLegacySnapshotJournal(database, publicationColumns);
-    }
-    else if (publicationColumns.has("snapshot_blob")) {
-        splitSnapshotJournalBlobs(database);
-    }
+    const legacyShape = legacyJournalShape(publicationColumns);
+    if (legacyShape)
+        convertLegacySnapshotJournal(database, legacyShape, publicationColumns);
     if (migratedDatabases.has(file))
         return database;
     database.exec(`
@@ -3086,29 +3207,36 @@ function readSnapshotPublications(file) {
         return [];
     const database = initializeDatabase(file);
     try {
+        const pages = database.prepare(`
+      SELECT mutation_id AS mutationId, sha256, bytes
+        FROM snapshot_publication_pages ORDER BY mutation_id, page_index
+    `).all();
+        const pagesByMutation = new Map();
+        for (const page of pages) {
+            const carried = pagesByMutation.get(page.mutationId) ?? [];
+            carried.push({ sha256: page.sha256, bytes: page.bytes });
+            pagesByMutation.set(page.mutationId, carried);
+        }
         return database.prepare(`
-      SELECT publications.mutation_id AS mutationId,
-             publications.resource_id AS resourceId,
-             publications.meta_json AS metaJson,
-             blobs.snapshot_blob AS snapshotBlob,
-             blobs.operation_blob AS operationBlob,
-             publications.status,
-             publications.submitted_at AS submittedAt
-        FROM snapshot_publications AS publications
-        LEFT JOIN snapshot_publication_blobs AS blobs USING (mutation_id)
-       ORDER BY publications.sequence
+      SELECT mutation_id AS mutationId,
+             resource_id AS resourceId,
+             meta_json AS metaJson,
+             operation_blob AS operationBlob,
+             status,
+             submitted_at AS submittedAt
+        FROM snapshot_publications ORDER BY sequence
     `).all().map((row) => {
-            // A publication without its payload is damage, never a skippable row —
-            // silently dropping it would let a new publication supersede a
-            // submitted mutation whose outcome exists only at the authority.
-            if (!row.snapshotBlob || !row.operationBlob) {
-                throw new Error(`snapshot publication ${row.mutationId} has no journaled payload`);
-            }
             const meta = JSON.parse(row.metaJson);
-            // No lawful publication carries zero roots — rootReplacementFromRecords
-            // refuses them at build time, so a rootless row here is damage.
+            // No lawful publication carries zero roots — a head commit that replaces
+            // nothing would prove nothing — so a rootless row here is damage, never
+            // a skippable row: silently dropping it would let a new publication
+            // supersede a submitted mutation whose outcome exists only at the
+            // authority. `entity.roots.replace` appears only on rows converted from
+            // a pre-paged journal, which no longer produce but must still replay.
             if (!Array.isArray(meta.replacementRootIds) || meta.replacementRootIds.length === 0
-                || !Array.isArray(meta.uploadUuids) || meta.operationKind !== "entity.roots.replace") {
+                || !Array.isArray(meta.uploadUuids)
+                || (meta.operationKind !== GRAPH_HEAD_OPERATION_KIND
+                    && meta.operationKind !== "entity.roots.replace")) {
                 throw new Error(`snapshot publication ${row.mutationId} has no exact root replacement`);
             }
             const deliveryWatermark = Number(meta.deliveryWatermark);
@@ -3122,11 +3250,11 @@ function readSnapshotPublications(file) {
                 baseVersion: Number(meta.baseVersion),
                 deliveryWatermark,
                 snapshotChecksum: String(meta.snapshotChecksum),
-                operationKind: meta.operationKind,
+                operationKind: String(meta.operationKind),
                 replacementRootIds: meta.replacementRootIds.map(String),
                 uploadUuids: meta.uploadUuids.map(String),
-                snapshotBlob: row.snapshotBlob,
                 operationBlob: row.operationBlob,
+                pages: pagesByMutation.get(row.mutationId) ?? [],
                 status: row.status === "rejected" ? "rejected" : "pending",
                 submitted: row.submittedAt !== null,
             };
@@ -3294,7 +3422,7 @@ function supersedeSnapshotJournal(file, entry) {
                 throw new Error("a submitted publication with an unknown outcome must resolve before supersession");
             }
             database.prepare(`
-        DELETE FROM snapshot_publication_blobs WHERE mutation_id IN (
+        DELETE FROM snapshot_publication_pages WHERE mutation_id IN (
           SELECT mutation_id FROM snapshot_publications WHERE resource_id = ?
         )
       `).run(entry.resourceId);
@@ -3302,8 +3430,8 @@ function supersedeSnapshotJournal(file, entry) {
                 .run(entry.resourceId);
             database.prepare(`
         INSERT INTO snapshot_publications(
-          mutation_id, resource_id, meta_json, created_at
-        ) VALUES (?, ?, ?, ?)
+          mutation_id, resource_id, meta_json, operation_blob, created_at
+        ) VALUES (?, ?, ?, ?, ?)
       `).run(entry.mutationId, entry.resourceId, stableJson({
                 authorityEpoch: entry.authorityEpoch,
                 baseVersion: entry.baseVersion,
@@ -3312,11 +3440,12 @@ function supersedeSnapshotJournal(file, entry) {
                 operationKind: entry.operationKind,
                 replacementRootIds: entry.replacementRootIds,
                 uploadUuids: entry.uploadUuids,
-            }), Date.now());
-            database.prepare(`
-        INSERT INTO snapshot_publication_blobs(mutation_id, snapshot_blob, operation_blob)
-        VALUES (?, ?, ?)
-      `).run(entry.mutationId, entry.snapshotBlob, entry.operationBlob);
+            }), entry.operationBlob, Date.now());
+            const insertPage = database.prepare(`
+        INSERT INTO snapshot_publication_pages(mutation_id, page_index, sha256, bytes)
+        VALUES (?, ?, ?, ?)
+      `);
+            entry.pages.forEach((page, index) => insertPage.run(entry.mutationId, index, page.sha256, page.bytes));
         })();
     }
     finally {
@@ -3387,7 +3516,7 @@ function deleteJournalEntry(file, mutationId) {
     const database = initializeDatabase(file);
     try {
         database.transaction(() => {
-            database.prepare("DELETE FROM snapshot_publication_blobs WHERE mutation_id = ?").run(mutationId);
+            database.prepare("DELETE FROM snapshot_publication_pages WHERE mutation_id = ?").run(mutationId);
             database.prepare("DELETE FROM snapshot_publications WHERE mutation_id = ?").run(mutationId);
         })();
     }
@@ -4981,19 +5110,79 @@ function recordRootResolver(records) {
     };
     return rootOf;
 }
-function mergeMaterializedRoots(cloudRecords, localRecords) {
-    const localRoots = new Set(localRecords
+/** The roots one publication rebuilds, each with its complete new records.
+ *
+ * A walked root is rebuilt from its ground alone: materialized ground is the
+ * whole truth for the roots it covers, so nothing of the committed graph
+ * survives underneath one. Any other root the newly delivered authority prefix
+ * touched is rebuilt from the committed graph with those results folded in, so
+ * the published graph never declares a watermark it has not actually applied.
+ * Every root outside this map keeps its committed pages untouched. */
+function publicationRoots(graph, localRecords, accepted) {
+    const rebuilt = new Map();
+    const walked = new Map(localRecords
         .filter((record) => record.parentUUID === null)
-        .map((record) => record.uuid));
-    const localIds = new Set(localRecords.map((record) => record.uuid));
-    const rootOf = recordRootResolver(cloudRecords);
-    const preserved = cloudRecords.filter((record) => {
-        if (localIds.has(record.uuid))
-            return false;
-        const root = rootOf(record);
-        return root === null || !localRoots.has(root);
-    });
-    return [...preserved, ...localRecords];
+        .map((record) => [record.uuid, []]));
+    if (walked.size > 0) {
+        const rootOf = recordRootResolver(localRecords);
+        for (const record of localRecords) {
+            const rootId = rootOf(record);
+            const group = rootId === null ? undefined : walked.get(rootId);
+            if (!group)
+                throw new Error(`walked record ${record.uuid} descends from no walked root`);
+            group.push(record);
+        }
+        for (const [rootId, records] of walked)
+            rebuilt.set(rootId, records);
+    }
+    const overlays = new Map();
+    for (const result of accepted) {
+        const rootId = graph.rootOf(result.uuid);
+        if (rootId === null || walked.has(rootId))
+            continue;
+        const overlay = overlays.get(rootId);
+        if (overlay)
+            overlay.push(result);
+        else
+            overlays.set(rootId, [result]);
+    }
+    for (const [rootId, results] of overlays) {
+        const byUuid = new Map(graph.recordsFor(rootId).map((record) => [record.uuid, record]));
+        for (const result of results)
+            byUuid.set(result.uuid, result);
+        // Entity channels are independently ordered, so container membership is
+        // derived once from the final prefix rather than by arrival order.
+        rebuilt.set(rootId, recordsRetainingMissingEvidence([...byUuid.values()], []));
+    }
+    // A records-shaped authority base carries no page identities, so it can
+    // prove nothing about a root the commit leaves alone: the first head pages
+    // the whole account at once, and never again.
+    if (graph.head === null) {
+        for (const rootId of graph.rootIds()) {
+            if (!rebuilt.has(rootId))
+                rebuilt.set(rootId, graph.recordsFor(rootId));
+        }
+    }
+    // Re-rooting is a move, not a copy: an enclosing Register walks records the
+    // committed graph still files under the root that used to hold them. Every
+    // such root is rebuilt without them, and a root that keeps nothing is left
+    // with no records at all — the rebuild then drops it from the graph.
+    const vacated = new Map();
+    for (const record of localRecords) {
+        const rootId = graph.rootOf(record.uuid);
+        if (rootId === null || walked.has(rootId))
+            continue;
+        const gone = vacated.get(rootId);
+        if (gone)
+            gone.add(record.uuid);
+        else
+            vacated.set(rootId, new Set([record.uuid]));
+    }
+    for (const [rootId, gone] of vacated) {
+        const held = rebuilt.get(rootId) ?? graph.recordsFor(rootId);
+        rebuilt.set(rootId, held.filter((record) => !gone.has(record.uuid)));
+    }
+    return rebuilt;
 }
 /** Filesystem disappearance is evidence, not cloud lifecycle authority. Keep
  * the last logical records in the outgoing graph while their materialized
@@ -5566,14 +5755,14 @@ async function installCloudWorkspace(input) {
         alreadyMaterialized: false,
     };
 }
-function readyFromFrame(frame) {
-    const bytes = Buffer.from(String(frame.snapshot_b64 || ""), "base64");
+function readyFromFrame(frame, graph) {
     const cloud = {
         resourceId: String(frame.resource_id || ""),
         version: Number(frame.head_version),
         deliveryWatermark: Number(frame.delivery_watermark),
         checksum: String(frame.snapshot_checksum || ""),
-        snapshot: parseSnapshot(bytes),
+        snapshot: graph.snapshot(),
+        ...(graph.head ? { head: graph.head } : {}),
     };
     return {
         cloud,
@@ -5583,7 +5772,7 @@ function readyFromFrame(frame) {
             headVersion: cloud.version,
             checksum: cloud.checksum,
             deliveryWatermark: cloud.deliveryWatermark,
-            records: cloud.snapshot.records,
+            graph,
         },
     };
 }