@amalgm/shell 0.1.110 → 0.1.111

package/dist/paged-mutation-submit.d.ts

@@ -9,8 +9,10 @@ type Frame = Record<string, unknown> & {
 };
 /** Publishes one mutation operation of any size as ONE atomic commit.
  *
- * A small operation travels inline in the submit frame, byte-identical to
- * the pre-paging wire. A larger one stages as byte pages of its canonical
+ * The operation arrives as its canonical UTF-8 bytes, serialized exactly
+ * once by the caller — this function never re-serializes a graph. A small
+ * operation travels inline in the submit frame, byte-identical to the
+ * pre-paging wire. A larger one stages as byte pages of its canonical
  * JSON, then submits a reference the gateway assembles into the same commit
  * path — transport pages, the operation never does. Every attempt stages
  * afresh, so a replay after a lost acknowledgement or dropped connection is
@@ -22,5 +24,5 @@ type Frame = Record<string, unknown> & {
  * bridge — the gateway reassembles the whole graph and the database journals
  * it as one large operation; the eventual endpoint is immutable graph pages
  * with a small atomically-committed graph-head pointer. */
-export declare function submitMutationOperation(wire: Pick<WireClient, "request" | "requestBinary">, envelope: Record<string, unknown>, operation: unknown): Promise<Frame>;
+export declare function submitMutationOperation(wire: Pick<WireClient, "request" | "requestBinary">, envelope: Record<string, unknown>, operation: Buffer, onLeg?: (leg: "stage" | "submit", durationMs: number) => void): Promise<Frame>;
 export {};

package/dist/paged-mutation-submit.js

@@ -6,8 +6,10 @@ export const MAX_INLINE_OPERATION_BYTES = 8 * 1024 * 1024;
 export const MUTATION_PAGE_BYTES = 4 * 1024 * 1024;
 /** Publishes one mutation operation of any size as ONE atomic commit.
  *
- * A small operation travels inline in the submit frame, byte-identical to
- * the pre-paging wire. A larger one stages as byte pages of its canonical
+ * The operation arrives as its canonical UTF-8 bytes, serialized exactly
+ * once by the caller — this function never re-serializes a graph. A small
+ * operation travels inline in the submit frame, byte-identical to the
+ * pre-paging wire. A larger one stages as byte pages of its canonical
  * JSON, then submits a reference the gateway assembles into the same commit
  * path — transport pages, the operation never does. Every attempt stages
  * afresh, so a replay after a lost acknowledgement or dropped connection is
@@ -19,13 +21,16 @@ export const MUTATION_PAGE_BYTES = 4 * 1024 * 1024;
  * bridge — the gateway reassembles the whole graph and the database journals
  * it as one large operation; the eventual endpoint is immutable graph pages
  * with a small atomically-committed graph-head pointer. */
-export async function submitMutationOperation(wire, envelope, operation) {
-    const canonical = Buffer.from(JSON.stringify(operation), "utf8");
+export async function submitMutationOperation(wire, envelope, operation, onLeg) {
+    const canonical = operation;
+    const started = performance.now();
     if (canonical.byteLength <= MAX_INLINE_OPERATION_BYTES) {
-        return wire.request({
+        const frame = await wire.request({
             type: "shared.mutation.submit",
-            envelope: { ...envelope, operation },
+            envelope: { ...envelope, operation: JSON.parse(canonical.toString("utf8")) },
         }, ["shared.mutation.ack"]);
+        onLeg?.("submit", performance.now() - started);
+        return frame;
     }
     const staged = {
         page_count: Math.ceil(canonical.byteLength / MUTATION_PAGE_BYTES),
@@ -43,10 +48,14 @@ export async function submitMutationOperation(wire, envelope, operation) {
             bytes: page.byteLength,
         }, page, ["shared.mutation.staged"]);
     }
-    return wire.request({
+    const submitStarted = performance.now();
+    onLeg?.("stage", submitStarted - started);
+    const frame = await wire.request({
         type: "shared.mutation.submit",
         envelope,
         staged,
     }, ["shared.mutation.ack"]);
+    onLeg?.("submit", performance.now() - submitStarted);
+    return frame;
 }
 //# sourceMappingURL=paged-mutation-submit.js.map

package/dist/paged-mutation-submit.js.map

@@ -1 +1 @@
-{"version":3,"file":"paged-mutation-submit.js","sourceRoot":"","sources":["../src/paged-mutation-submit.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAIzC;0EAC0E;AAC1E,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC;AAE1D,+EAA+E;AAC/E,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC;AAInD;;;;;;;;;;;;;;2DAc2D;AAC3D,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAC3C,IAAmD,EACnD,QAAiC,EACjC,SAAkB;IAElB,MAAM,SAAS,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC,CAAC;IACjE,IAAI,SAAS,CAAC,UAAU,IAAI,0BAA0B,EAAE,CAAC;QACvD,OAAO,IAAI,CAAC,OAAO,CAAC;YAClB,IAAI,EAAE,wBAAwB;YAC9B,QAAQ,EAAE,EAAE,GAAG,QAAQ,EAAE,SAAS,EAAE;SACrC,EAAE,CAAC,qBAAqB,CAAC,CAAC,CAAC;IAC9B,CAAC;IACD,MAAM,MAAM,GAAG;QACb,UAAU,EAAE,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,UAAU,GAAG,mBAAmB,CAAC;QACjE,eAAe,EAAE,SAAS,CAAC,UAAU;QACrC,gBAAgB,EAAE,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;KACvE,CAAC;IACF,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC,UAAU,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;QAC1D,MAAM,IAAI,GAAG,SAAS,CAAC,QAAQ,CAC7B,KAAK,GAAG,mBAAmB,EAC3B,IAAI,CAAC,GAAG,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,GAAG,mBAAmB,EAAE,SAAS,CAAC,UAAU,CAAC,CAClE,CAAC;QACF,MAAM,IAAI,CAAC,aAAa,CAAC;YACvB,IAAI,EAAE,uBAAuB;YAC7B,WAAW,EAAE,QAAQ,CAAC,UAAU;YAChC,WAAW,EAAE,QAAQ,CAAC,UAAU;YAChC,UAAU,EAAE,KAAK;YACjB,GAAG,MAAM;YACT,KAAK,EAAE,IAAI,CAAC,UAAU;SACvB,EAAE,IAAI,EAAE,CAAC,wBAAwB,CAAC,CAAC,CAAC;IACvC,CAAC;IACD,OAAO,IAAI,CAAC,OAAO,CAAC;QAClB,IAAI,EAAE,wBAAwB;QAC9B,QAAQ;QACR,MAAM;KACP,EAAE,CAAC,qBAAqB,CAAC,CAAC,CAAC;AAC9B,CAAC"}
+{"version":3,"file":"paged-mutation-submit.js","sourceRoot":"","sources":["../src/paged-mutation-submit.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAIzC;0EAC0E;AAC1E,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC;AAE1D,+EAA+E;AAC/E,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC;AAInD;;;;;;;;;;;;;;;;2DAgB2D;AAC3D,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAC3C,IAAmD,EACnD,QAAiC,EACjC,SAAiB,EACjB,KAA6D;IAE7D,MAAM,SAAS,GAAG,SAAS,CAAC;IAC5B,MAAM,OAAO,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;IAClC,IAAI,SAAS,CAAC,UAAU,IAAI,0BAA0B,EAAE,CAAC;QACvD,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC;YAC/B,IAAI,EAAE,wBAAwB;YAC9B,QAAQ,EAAE,EAAE,GAAG,QAAQ,EAAE,SAAS,EAAE,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,EAAE;SAC7E,EAAE,CAAC,qBAAqB,CAAC,CAAC,CAAC;QAC5B,KAAK,EAAE,CAAC,QAAQ,EAAE,WAAW,CAAC,GAAG,EAAE,GAAG,OAAO,CAAC,CAAC;QAC/C,OAAO,KAAK,CAAC;IACf,CAAC;IACD,MAAM,MAAM,GAAG;QACb,UAAU,EAAE,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,UAAU,GAAG,mBAAmB,CAAC;QACjE,eAAe,EAAE,SAAS,CAAC,UAAU;QACrC,gBAAgB,EAAE,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;KACvE,CAAC;IACF,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC,UAAU,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;QAC1D,MAAM,IAAI,GAAG,SAAS,CAAC,QAAQ,CAC7B,KAAK,GAAG,mBAAmB,EAC3B,IAAI,CAAC,GAAG,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,GAAG,mBAAmB,EAAE,SAAS,CAAC,UAAU,CAAC,CAClE,CAAC;QACF,MAAM,IAAI,CAAC,aAAa,CAAC;YACvB,IAAI,EAAE,uBAAuB;YAC7B,WAAW,EAAE,QAAQ,CAAC,UAAU;YAChC,WAAW,EAAE,QAAQ,CAAC,UAAU;YAChC,UAAU,EAAE,KAAK;YACjB,GAAG,MAAM;YACT,KAAK,EAAE,IAAI,CAAC,UAAU;SACvB,EAAE,IAAI,EAAE,CAAC,wBAAwB,CAAC,CAAC,CAAC;IACvC,CAAC;IACD,MAAM,aAAa,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;IACxC,KAAK,EAAE,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,CAAC;IAC1C,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC;QAC/B,IAAI,EAAE,wBAAwB;QAC9B,QAAQ;QACR,MAAM;KACP,EAAE,CAAC,qBAAqB,CAAC,CAAC,CAAC;IAC5B,KAAK,EAAE,CAAC,QAAQ,EAAE,WAAW,CAAC,GAAG,EAAE,GAAG,aAAa,CAAC,CAAC;IACrD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/user-ground-host.d.ts

@@ -1,5 +1,6 @@
 import { type UserGroundPort, type UserHomeDeclaration } from "@amalgm/core/identity";
 import { type EntityType, type FilesAddPorts, type FilesRegisterPorts, type UserGroundIdentity } from "@amalgm/live";
+import Database from "better-sqlite3";
 import { type FilesStageObserver } from "./files-observability.js";
 import { type EntityApplyStageEvidence } from "./entity-apply-host.js";
 import { type OpenNativeWatch, type WatchCoverageEvidence, type WatchHealth } from "./watching/index.js";
@@ -184,5 +185,11 @@ export declare class UserGroundHost {
      * frames; the answer is the only permission to skip an upload. */
     private sealedContentHashes;
     private publishPendingSnapshots;
+    private publishLoadedSnapshot;
 }
+/** The single opener and schema-migration entry for a user ground database.
+ * Exported so the upgrade path is provable in isolation — the journal
+ * conversion law test opens a legacy file through this exact entry inside a
+ * heap-capped child process. */
+export declare function initializeDatabase(file: string): Database.Database;
 export {};

package/dist/user-ground-host.js

@@ -55,6 +55,15 @@ 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;
+function loadSnapshotPublication(entry) {
+    const snapshotRecords = snapshotFromRecords((JSON.parse(entry.snapshotBlob.toString("utf8")).records ?? [])).records;
+    const uploadIds = new Set(entry.uploadUuids);
+    return {
+        ...entry,
+        snapshotRecords,
+        uploadRecords: snapshotRecords.filter((record) => uploadIds.has(record.uuid)),
+    };
+}
 const GROUND_ROW_COLUMNS = [
     "uuid", "resource_id", "root_uuid", "type", "parent_uuid", "name", "status", "version",
     "payload_version", "transport_version", "relative_path", "absolute_path", "device_number",
@@ -1939,7 +1948,7 @@ export class UserGroundHost {
             headVersion: first.baseVersion,
             checksum: "",
             deliveryWatermark: first.deliveryWatermark,
-            records: snapshotFromRecords(JSON.parse(first.snapshotJson).records || []).records,
+            records: loadSnapshotPublication(first).snapshotRecords,
         };
         try {
             await this.publishPendingSnapshots(identity);
@@ -2003,32 +2012,27 @@ export class UserGroundHost {
             throw new Error(`repository-owned leaf escaped its rail: ${impossibleGitLeaf.name} parent=${parent?.type ?? "missing"}`);
         }
         const snapshot = snapshotFromRecords(traveling);
-        const snapshotJson = stableJson(snapshot);
-        const checksum = sha256Hex(snapshotJson);
+        // 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 = Buffer.from(stableJson(snapshot), "utf8");
+        const checksum = sha256Hex(snapshotBlob);
         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,
         // whose namespace the current readers never touch. Only the authority's
-        // (resource, hash, contract) seal evidence may skip an upload — and the
-        // question is asked even when the graph itself is unchanged, so Register
-        // always re-establishes cargo closure before returning.
-        const cargo = snapshot.records.flatMap((record) => {
-            if (!localIds.has(record.uuid))
-                return [];
-            const artifact = artifactForRecord(record);
-            return artifact ? [{ record, contentHash: artifact.contentHash }] : [];
-        });
-        const sealedArtifacts = await this.sealedContentHashes(state.resourceId, [...new Set(cargo.map((entry) => entry.contentHash))]);
-        const uploadRecords = cargo
-            .filter((entry) => !sealedArtifacts.has(entry.contentHash))
-            .map((entry) => entry.record);
+        // (resource, hash, contract) seal evidence may skip an upload — the
+        // 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);
         if (checksum === state.checksum && deliveryWatermark === state.deliveryWatermark) {
             // The graph is already committed; only cargo can be missing. Repair
             // uploads need no journal row — a crash simply re-runs the same
             // repair on the next Register.
-            if (uploadRecords.length > 0) {
+            if (cargoRecords.length > 0) {
                 try {
-                    await this.uploadSnapshotContent(identity, state.resourceId, uploadRecords, trace, manifestHints);
+                    await this.uploadSnapshotContent(identity, state.resourceId, cargoRecords, trace, manifestHints);
                 }
                 catch (error) {
                     throw pipelineStageError("cloud upload", error);
@@ -2046,20 +2050,32 @@ export class UserGroundHost {
             return root !== null && replacementRoots.has(root);
         });
         const replacement = rootReplacementFromRecords(replacementRootIds, replacementRecords);
-        supersedeSnapshotJournal(this.databasePath(identity), {
+        // The operation's canonical bytes: staged, hashed, and submitted as-is.
+        const operationBlob = Buffer.from(stableJson(replacement), "utf8");
+        const entry = {
             mutationId: randomUUID(),
             resourceId: state.resourceId,
             authorityEpoch: state.authorityEpoch,
             baseVersion: state.headVersion,
             snapshotChecksum: checksum,
-            snapshotJson,
             deliveryWatermark,
-            uploadRecords,
+            operationKind: replacement.kind,
             replacementRootIds: replacement.rootIds,
-            replacementRecords: replacement.records,
+            uploadUuids: cargoRecords.map((record) => record.uuid),
+            snapshotBlob,
+            operationBlob,
             status: "pending",
-        });
-        await this.publishPendingSnapshots(identity, trace, manifestHints);
+            submitted: false,
+        };
+        supersedeSnapshotJournal(this.databasePath(identity), entry);
+        // 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.
+        await this.publishLoadedSnapshot(identity, {
+            ...entry,
+            snapshotRecords: snapshot.records,
+            uploadRecords: cargoRecords,
+        }, trace, manifestHints);
     }
     /** Which of these heads does the authority hold sealed under the current
      * content contract? Batched so a whole workspace costs a handful of
@@ -2091,88 +2107,94 @@ export class UserGroundHost {
             // snapshot superseding it can publish this resource again.
             if (pending.status === "rejected")
                 continue;
-            const snapshot = snapshotFromRecords(JSON.parse(pending.snapshotJson).records || []);
-            const replacement = rootReplacementFromRecords(pending.replacementRootIds, pending.replacementRecords);
-            try {
-                await this.uploadSnapshotContent(identity, pending.resourceId, pending.uploadRecords, trace, manifestHints);
-            }
-            catch (error) {
-                // An unsubmitted pending row is a local intent the authority has
-                // never seen. When its captured ground moved before upload, the
-                // intent is simply stale: delete it and let the caller re-derive
-                // one from current ground. A submitted row never lands here — its
-                // upload sealed completely before the first submit frame left.
-                if (staleCapture(error) && !pending.submitted) {
-                    deleteJournalEntry(this.databasePath(identity), pending.mutationId);
-                }
-                throw pipelineStageError("cloud upload", error);
-            }
-            let frame;
-            const graphCommitStarted = performance.now();
-            if (trace?.journey === "register") {
-                this.stage({
-                    primitive: "register",
-                    stage: "cloud-graph-commit",
-                    status: "started",
-                    ...(trace.workspaceId ? { workspaceId: trace.workspaceId } : {}),
-                    ...(trace.mutationId ? { mutationId: trace.mutationId } : {}),
-                });
-            }
-            if (!pending.submitted) {
-                markSnapshotJournalSubmitted(this.databasePath(identity), pending.mutationId);
-            }
-            try {
-                frame = await submitMutationOperation(this.wire, {
-                    resourceId: pending.resourceId,
-                    authorityEpoch: pending.authorityEpoch,
-                    mutationId: pending.mutationId,
-                    deviceId: identity.deviceId,
-                    baseVersion: pending.baseVersion,
-                    contract: ENTITY_CLOUD_CONTRACT,
-                    schemaVersion: ENTITY_CLOUD_SCHEMA_VERSION,
-                    operationKind: replacement.kind,
-                    deliveryWatermark: pending.deliveryWatermark,
-                }, replacement);
-            }
-            catch (error) {
-                if (trace?.journey === "register") {
-                    this.stage({
-                        primitive: "register",
-                        stage: "cloud-graph-commit",
-                        status: "failed",
-                        ...(trace.workspaceId ? { workspaceId: trace.workspaceId } : {}),
-                        durationMs: performance.now() - graphCommitStarted,
-                    });
-                }
-                // A non-retryable error frame is the authority's answer: this exact
-                // mutation is refused forever. Settle the row so it is never
-                // replayed and a newer snapshot may supersede it. Every other
-                // failure leaves the outcome unknown and the row pending.
-                if (error instanceof WireRequestError && error.retryable === false) {
-                    markSnapshotJournalRejected(this.databasePath(identity), pending.mutationId);
-                }
-                throw pipelineStageError("cloud graph commit", error);
+            await this.publishLoadedSnapshot(identity, loadSnapshotPublication(pending), trace, manifestHints);
+        }
+    }
+    async publishLoadedSnapshot(identity, publication, trace, manifestHints) {
+        try {
+            await this.uploadSnapshotContent(identity, publication.resourceId, publication.uploadRecords, trace, manifestHints);
+        }
+        catch (error) {
+            // An unsubmitted pending row is a local intent the authority has
+            // never seen. When its captured ground moved before upload, the
+            // intent is simply stale: delete it and let the caller re-derive
+            // one from current ground. A submitted row never lands here — its
+            // upload sealed completely before the first submit frame left.
+            if (staleCapture(error) && !publication.submitted) {
+                deleteJournalEntry(this.databasePath(identity), publication.mutationId);
             }
+            throw pipelineStageError("cloud upload", error);
+        }
+        let frame;
+        const graphCommitStarted = performance.now();
+        if (trace?.journey === "register") {
+            this.stage({
+                primitive: "register",
+                stage: "cloud-graph-commit",
+                status: "started",
+                ...(trace.workspaceId ? { workspaceId: trace.workspaceId } : {}),
+                ...(trace.mutationId ? { mutationId: trace.mutationId } : {}),
+            });
+        }
+        if (!publication.submitted) {
+            markSnapshotJournalSubmitted(this.databasePath(identity), publication.mutationId);
+        }
+        const legMs = {};
+        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; });
+        }
+        catch (error) {
             if (trace?.journey === "register") {
                 this.stage({
                     primitive: "register",
                     stage: "cloud-graph-commit",
-                    status: "completed",
+                    status: "failed",
                     ...(trace.workspaceId ? { workspaceId: trace.workspaceId } : {}),
                     durationMs: performance.now() - graphCommitStarted,
-                    measurements: { version: Number(frame.version) },
                 });
             }
-            this.cloudState = {
-                resourceId: pending.resourceId,
-                authorityEpoch: Number(frame.authority_epoch),
-                headVersion: Number(frame.version),
-                checksum: pending.snapshotChecksum,
-                deliveryWatermark: Number(frame.delivery_watermark),
-                records: snapshot.records,
-            };
-            deleteJournalEntry(this.databasePath(identity), pending.mutationId);
+            // A non-retryable error frame is the authority's answer: this exact
+            // mutation is refused forever. Settle the row so it is never
+            // replayed and a newer snapshot may supersede it. Every other
+            // failure leaves the outcome unknown and the row pending.
+            if (error instanceof WireRequestError && error.retryable === false) {
+                markSnapshotJournalRejected(this.databasePath(identity), publication.mutationId);
+            }
+            throw pipelineStageError("cloud graph commit", error);
         }
+        if (trace?.journey === "register") {
+            this.stage({
+                primitive: "register",
+                stage: "cloud-graph-commit",
+                status: "completed",
+                ...(trace.workspaceId ? { workspaceId: trace.workspaceId } : {}),
+                durationMs: performance.now() - graphCommitStarted,
+                measurements: {
+                    version: Number(frame.version),
+                    operationBytes: publication.operationBlob.byteLength,
+                    ...legMs,
+                },
+            });
+        }
+        this.cloudState = {
+            resourceId: publication.resourceId,
+            authorityEpoch: Number(frame.authority_epoch),
+            headVersion: Number(frame.version),
+            checksum: publication.snapshotChecksum,
+            deliveryWatermark: Number(frame.delivery_watermark),
+            records: publication.snapshotRecords,
+        };
+        deleteJournalEntry(this.databasePath(identity), publication.mutationId);
     }
 }
 const sha256Hex = (input) => createHash("sha256").update(input).digest("hex");
@@ -2264,12 +2286,99 @@ 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();
-function initializeDatabase(file) {
+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,
+      snapshot_blob BLOB 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
+    );`;
+/** 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).
+ *
+ * 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.
+ *
+ * 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) {
+    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, snapshot_blob, 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())
+        ),
+        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),
+        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("DROP TABLE snapshot_publications_legacy");
+    })();
+}
+/** The single opener and schema-migration entry for a user ground database.
+ * Exported so the upgrade path is provable in isolation — the journal
+ * conversion law test opens a legacy file through this exact entry inside a
+ * heap-capped child process. */
+export function initializeDatabase(file) {
     ensurePrivateDir(dirname(file));
     const database = new Database(file);
     database.pragma("busy_timeout = 5000");
     database.pragma("journal_mode = WAL");
     database.pragma("synchronous = FULL");
+    // The legacy probe runs on every open, before the migration memo: a journal
+    // row may be a submitted publication whose outcome exists only at the
+    // authority, so an old-shape table must convert — never drop — no matter
+    // 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);
+    }
     if (migratedDatabases.has(file))
         return database;
     database.exec(`
@@ -2361,15 +2470,7 @@ function initializeDatabase(file) {
       authority_id TEXT PRIMARY KEY,
       delivery_sequence INTEGER NOT NULL CHECK(delivery_sequence >= 0)
     );
-    CREATE TABLE IF NOT EXISTS snapshot_publications (
-      sequence INTEGER PRIMARY KEY AUTOINCREMENT,
-      mutation_id TEXT NOT NULL UNIQUE,
-      resource_id TEXT NOT NULL,
-      publication_json TEXT NOT NULL,
-      created_at INTEGER NOT NULL,
-      status TEXT NOT NULL DEFAULT 'pending' CHECK(status IN ('pending', 'rejected')),
-      submitted_at INTEGER
-    );
+    ${SNAPSHOT_PUBLICATIONS_SCHEMA}
     CREATE TABLE IF NOT EXISTS workspace_add_intents (
       workspace_uuid TEXT PRIMARY KEY,
       destination_path TEXT NOT NULL UNIQUE,
@@ -2405,13 +2506,6 @@ function initializeDatabase(file) {
     if (!inboxColumns.has("resolved_at")) {
         database.exec("ALTER TABLE record_inbox ADD COLUMN resolved_at INTEGER");
     }
-    const publicationColumns = new Set(database.prepare("PRAGMA table_info(snapshot_publications)").all().map(({ name }) => name));
-    if (!publicationColumns.has("status")) {
-        database.exec("ALTER TABLE snapshot_publications ADD COLUMN status TEXT NOT NULL DEFAULT 'pending' CHECK(status IN ('pending', 'rejected'))");
-    }
-    if (!publicationColumns.has("submitted_at")) {
-        database.exec("ALTER TABLE snapshot_publications ADD COLUMN submitted_at INTEGER");
-    }
     database.exec("DROP INDEX IF EXISTS record_inbox_delivery");
     database.exec("DROP TABLE IF EXISTS mutation_journal");
     migratedDatabases.add(file);
@@ -2862,33 +2956,34 @@ function readSnapshotPublications(file) {
     try {
         return database.prepare(`
       SELECT mutation_id AS mutationId, resource_id AS resourceId,
-             publication_json AS publicationJson, status,
+             meta_json AS metaJson, snapshot_blob AS snapshotBlob,
+             operation_blob AS operationBlob, status,
              submitted_at AS submittedAt
         FROM snapshot_publications ORDER BY sequence
     `).all().map((row) => {
-            const publication = JSON.parse(row.publicationJson);
-            if (!Array.isArray(publication.uploadRecords)) {
-                throw new Error(`snapshot publication ${row.mutationId} has no exact upload subset`);
-            }
-            if (!Array.isArray(publication.replacementRootIds)
-                || !Array.isArray(publication.replacementRecords)) {
+            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.
+            if (!Array.isArray(meta.replacementRootIds) || meta.replacementRootIds.length === 0
+                || !Array.isArray(meta.uploadUuids) || meta.operationKind !== "entity.roots.replace") {
                 throw new Error(`snapshot publication ${row.mutationId} has no exact root replacement`);
             }
-            const deliveryWatermark = Number(publication.deliveryWatermark);
+            const deliveryWatermark = Number(meta.deliveryWatermark);
             if (!Number.isSafeInteger(deliveryWatermark) || deliveryWatermark < 0) {
                 throw new Error(`snapshot publication ${row.mutationId} has no delivery watermark`);
             }
             return {
                 mutationId: row.mutationId,
                 resourceId: row.resourceId,
-                authorityEpoch: Number(publication.authorityEpoch),
-                baseVersion: Number(publication.baseVersion),
+                authorityEpoch: Number(meta.authorityEpoch),
+                baseVersion: Number(meta.baseVersion),
                 deliveryWatermark,
-                snapshotChecksum: String(publication.snapshotChecksum),
-                snapshotJson: String(publication.snapshotJson),
-                uploadRecords: snapshotFromRecords(publication.uploadRecords).records,
-                replacementRootIds: publication.replacementRootIds.map(String),
-                replacementRecords: snapshotFromRecords(publication.replacementRecords).records,
+                snapshotChecksum: String(meta.snapshotChecksum),
+                operationKind: meta.operationKind,
+                replacementRootIds: meta.replacementRootIds.map(String),
+                uploadUuids: meta.uploadUuids.map(String),
+                snapshotBlob: row.snapshotBlob,
+                operationBlob: row.operationBlob,
                 status: row.status === "rejected" ? "rejected" : "pending",
                 submitted: row.submittedAt !== null,
             };
@@ -3059,18 +3154,17 @@ function supersedeSnapshotJournal(file, entry) {
                 .run(entry.resourceId);
             database.prepare(`
         INSERT INTO snapshot_publications(
-          mutation_id, resource_id, publication_json, created_at
-        ) VALUES (?, ?, ?, ?)
+          mutation_id, resource_id, meta_json, snapshot_blob, operation_blob, created_at
+        ) VALUES (?, ?, ?, ?, ?, ?)
       `).run(entry.mutationId, entry.resourceId, stableJson({
                 authorityEpoch: entry.authorityEpoch,
                 baseVersion: entry.baseVersion,
                 deliveryWatermark: entry.deliveryWatermark,
                 snapshotChecksum: entry.snapshotChecksum,
-                snapshotJson: entry.snapshotJson,
-                uploadRecords: entry.uploadRecords,
+                operationKind: entry.operationKind,
                 replacementRootIds: entry.replacementRootIds,
-                replacementRecords: entry.replacementRecords,
-            }), Date.now());
+                uploadUuids: entry.uploadUuids,
+            }), entry.snapshotBlob, entry.operationBlob, Date.now());
         })();
     }
     finally {