@amalgm/shell 0.1.125 → 0.1.126

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, pathIsSuspect, CONTENT_REFS_BATCH_OBJECTS, privateEntityResourceId, repositoryIdentityHash, sameRecords, snapshotFromRecords, stableJson, streamCargo, travelingRecords, upload as uploadArtifact, userGroundRecords, GRAPH_HEAD_OPERATION_KIND, } 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, containedRecords, createLocalEntityRecord, createEntityRecordAuthorityPort, convergeUserGround, decodeAcceptedEntityRecord, deriveUploadManifest, createUserGroundEnrollmentPolicy, isRepositoryMetadataEntry, indexRepositoryTerritory, downloadAll as downloadAllArtifacts, encodeEntityRecord, EntityApplyRail, EntityRecordRail, membershipHash, pathIsSuspect, CONTENT_REFS_BATCH_OBJECTS, privateEntityResourceId, repositoryIdentityHash, sameRecords, snapshotFromRecords, stableJson, streamCargo, 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";
@@ -23,6 +23,7 @@ import { applyRepositoryFiles, captureRepository, inspectRepositoryTransportFile
 import { gitEvidenceFingerprint, inspectGitRegistration, sameGitIdentity, } from "./git-registration-host.js";
 import { projectMaterializedGraph } from "./materialized-graph.js";
 import { graphPageIdentities, registryGraphFromSnapshot, } from "./registry-graph.js";
+import { readVerifiedRegistryPage, writeVerifiedRegistryPage, } from "./registry-page-cache.js";
 import { NodeWatchHost, } from "./watching/index.js";
 import { GroundCoordinator } from "./ground-coordination.js";
 import { adoptSnapshotDeliveryBaseline } from "./snapshot-delivery-baseline.js";
@@ -34,17 +35,17 @@ const CARGO_SEGMENT_LOAD_CONCURRENCY = 8;
 /** Storage-object lanes for one download set. Tiny objects use the wide
  * request window, while the separate byte budget narrows large chunks so
  * request concurrency can never silently become an unbounded memory claim. */
-const DIRECT_OBJECT_DOWNLOAD_CONCURRENCY = 128;
+/** Admission is sized to the refs batch law so one same-turn wave coalesces
+ * into one refs frame and the span fetcher merges each pack's members into a
+ * few broad ranged reads. Memory is bounded by the byte laws below, never by
+ * this count. */
+const DIRECT_OBJECT_DOWNLOAD_CONCURRENCY = CONTENT_REFS_BATCH_OBJECTS;
 // Opening one protected object transiently retains the fetched envelope,
 // WebCrypto's ciphertext-with-tag input, and the plaintext. Bound plaintext
 // to two full blocks so those three representations stay below 96 MiB even
 // 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;
@@ -94,6 +95,9 @@ export class UserGroundHost {
     watchDirty = false;
     cloudState = null;
     converged = false;
+    /** Cumulative graph-page reads, reported as diffs on the stages that
+     * materialize roots so the ledger shows what each operation actually read. */
+    graphPageReads = { fetchedPages: 0, fetchedBytes: 0, cachedPages: 0 };
     syncing = null;
     recordRail = null;
     recordStore = null;
@@ -159,7 +163,7 @@ export class UserGroundHost {
                 const local = this.localPort(this.activeIdentity);
                 const result = await convergeUserGround(this.activeIdentity, {
                     sha256Hex,
-                    cloud: this.cloudPort(this.activeIdentity),
+                    cloud: this.cloudPort(this.activeIdentity, { kind: "core" }),
                     local,
                 });
                 await this.resumeWorkspaceAdds(this.activeIdentity);
@@ -302,13 +306,16 @@ export class UserGroundHost {
         });
         const add = {
             sha256Hex,
-            lookupRegistry: async () => {
+            lookupRegistry: async (workspaceId) => {
                 const started = performance.now();
                 this.stage({
                     primitive: "download", stage: "registry-lookup", status: "started",
                 });
+                const pagesBefore = { ...this.graphPageReads };
+                const planeBefore = this.direct.metrics();
                 const resourceId = privateEntityResourceId(identity.userId, sha256Hex);
-                const cloud = await this.cloudPort(identity).lookup(resourceId);
+                const cloud = await this.cloudPort(identity, { kind: "workspace", workspaceId })
+                    .lookup(resourceId);
                 if (!cloud)
                     throw new Error("this user has no cloud entity registry");
                 // The authority's active snapshot is the compact base; Add's active
@@ -322,7 +329,7 @@ export class UserGroundHost {
                 if (deliveryWatermark < cloud.deliveryWatermark) {
                     throw new Error("local delivery cursor is behind the active snapshot watermark");
                 }
-                const snapshot = snapshotFromRecords(recordsAtDeliveryPrefix(cloud.snapshot.records, readAcceptedResults(this.databasePath(identity), resourceId, cloud.deliveryWatermark, deliveryWatermark)));
+                const snapshot = snapshotFromRecords(await this.foldScopedPrefix(cloud.snapshot.records, readAcceptedResults(this.databasePath(identity), resourceId, cloud.deliveryWatermark, deliveryWatermark), workspaceId));
                 const current = {
                     ...cloud,
                     deliveryWatermark,
@@ -334,6 +341,13 @@ export class UserGroundHost {
                     stage: "registry-lookup",
                     status: "completed",
                     durationMs: performance.now() - started,
+                    measurements: {
+                        records: snapshot.records.length,
+                        fetchedPages: this.graphPageReads.fetchedPages - pagesBefore.fetchedPages,
+                        fetchedPageBytes: this.graphPageReads.fetchedBytes - pagesBefore.fetchedBytes,
+                        cachedPages: this.graphPageReads.cachedPages - pagesBefore.cachedPages,
+                        ...physicalPlaneDelta(planeBefore, this.direct.metrics()),
+                    },
                 });
                 return current;
             },
@@ -564,12 +578,29 @@ export class UserGroundHost {
             throw stageError("Watch coverage", error);
         }
         const database = this.databasePath(identity);
-        const hasRegisteredBoundary = (records) => records.some((record) => record.uuid === workspaceId && record.status === "active")
-            && records.some((record) => record.type === "reference"
+        // Both proofs are root-scoped reads: the boundary's own record from
+        // whichever root holds it, and its durable reference from the core root
+        // — the only root references lawfully live in.
+        const hasRegisteredBoundary = async () => {
+            const graph = this.cloudState?.graph;
+            if (!graph)
+                return false;
+            const boundaryRoot = await graph.locate(workspaceId);
+            if (boundaryRoot === null)
+                return false;
+            const boundary = (await graph.recordsFor(boundaryRoot))
+                .find((record) => record.uuid === workspaceId);
+            if (!boundary || boundary.status !== "active")
+                return false;
+            const coreRoot = await this.coreRootId(identity, graph);
+            if (coreRoot === null)
+                return false;
+            return (await graph.recordsFor(coreRoot)).some((record) => record.type === "reference"
                 && record.status === "active"
                 && record.payloadVersion === workspaceId);
+        };
         if (hasRegisteredBoundaryInDatabase(database, workspaceId)
-            && hasRegisteredBoundary(this.cloudState.graph.records())) {
+            && await hasRegisteredBoundary()) {
             // 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
@@ -751,7 +782,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.graph.records())) {
+        if (!(await hasRegisteredBoundary())) {
             throw stageError("cloud graph commit", new Error(`workspace ${workspaceId} or its durable reference is absent from the committed head`));
         }
         return {
@@ -1128,7 +1159,7 @@ export class UserGroundHost {
     cacheDir(identity) {
         return join(liveMachineStateDir(this.userRoot(identity), identity.deviceId), "content");
     }
-    cloudPort(identity) {
+    cloudPort(identity, scope) {
         return {
             lookup: async (resourceId) => {
                 await this.publishPendingSnapshotsBeforeLookup(identity, resourceId);
@@ -1139,7 +1170,8 @@ export class UserGroundHost {
                 }, ["private.resource.ready", "private.resource.missing"]);
                 if (frame.type === "private.resource.missing")
                     return null;
-                const ready = readyFromFrame(frame, await this.materializeRegistry(identity, frame));
+                const graph = this.materializeRegistry(identity, frame);
+                const ready = readyFromFrame(frame, graph, await this.selectScope(identity, graph, scope));
                 this.cloudState = ready.state;
                 return ready.cloud;
             },
@@ -1154,7 +1186,8 @@ export class UserGroundHost {
                     snapshot_checksum: input.checksum,
                     snapshot_bytes: bytes.length,
                 }, ["private.resource.ready"]);
-                const ready = readyFromFrame(frame, await this.materializeRegistry(identity, frame));
+                const graph = this.materializeRegistry(identity, frame);
+                const ready = readyFromFrame(frame, graph, await this.selectScope(identity, graph, scope));
                 const current = ready.cloud;
                 this.cloudState = ready.state;
                 const created = frame.duplicate === false;
@@ -1164,60 +1197,103 @@ 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) {
+    /** The authority's stored snapshot as this machine's graph. A head is held
+     * lazily — no page is read until an operation asks for a root — and every
+     * page this machine already cached is a local read, so an unchanged root
+     * never crosses the network twice. */
+    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`);
+        return registryGraphFromSnapshot(Buffer.from(String(frame.snapshot_b64 || ""), "base64"), (ref) => this.readGraphPage(identity, resourceId, ref), sha256Hex);
+    }
+    /** The records a lookup hands to Live: every root's own record — the
+     * discovery set that proves root uniqueness — plus the full records of
+     * exactly the roots the operation acts on. A records-shaped snapshot is a
+     * first publication's own small graph and travels whole, keeping its
+     * records-shape checksum law intact. */
+    async selectScope(identity, graph, scope) {
+        if (graph.head === null)
+            return graph.recordsShapedSnapshot().records;
+        if (scope.kind === "none")
+            return [];
+        const selected = new Set();
+        const core = await this.coreRootId(identity, graph);
+        if (core)
+            selected.add(core);
+        if (scope.kind === "workspace") {
+            const boundaryRoot = await graph.locate(scope.workspaceId);
+            if (boundaryRoot)
+                selected.add(boundaryRoot);
+        }
+        const records = new Map((await graph.rootRecords())
+            .map((record) => [record.uuid, record]));
+        for (const rootId of selected) {
+            for (const record of await graph.recordsFor(rootId))
+                records.set(record.uuid, record);
+        }
+        return [...records.values()];
+    }
+    /** The account's core root: the one active top-level workspace named by the
+     * account email. Registered-boundary references live only there. */
+    async coreRootId(identity, graph) {
+        const email = identity.userEmail.toLowerCase();
+        const core = (await graph.rootRecords()).find((record) => record.status === "active"
+            && record.parentUUID === null
+            && record.type === "workspace"
+            && record.name.toLowerCase() === email);
+        return core?.uuid ?? null;
+    }
+    /** Fold the committed delivery tail over a root-scoped base without losing
+     * a subtree the tail moved across roots. A container the folded boundary
+     * contains only through delivered results may still file unchanged
+     * descendants under the root that used to hold it, so that root's records
+     * join the base and the fold reruns until no probe widens it. Leaf results
+     * travel whole and never probe. */
+    async foldScopedPrefix(base, accepted, boundaryId) {
+        if (accepted.length === 0)
+            return base;
+        const graph = this.cloudState?.graph;
+        if (!graph)
+            throw new Error("cloud state is unavailable for a registry lookup");
+        const probed = new Set(base.map((record) => record.uuid));
+        let widened = base;
+        for (;;) {
+            const folded = recordsAtDeliveryPrefix(widened, accepted);
+            const probes = containedRecords(folded, boundaryId)
+                .filter((record) => !probed.has(record.uuid)
+                && (record.type === "workspace" || record.type === "folder" || record.type === "repo.git"))
+                .map((record) => record.uuid);
+            if (probes.length === 0)
+                return folded;
+            for (const uuid of probes)
+                probed.add(uuid);
+            const located = await graph.membership(new Set(probes));
+            const merged = new Map(widened.map((record) => [record.uuid, record]));
+            for (const rootId of new Set(located.values())) {
+                for (const record of await graph.recordsFor(rootId)) {
+                    merged.set(record.uuid, record);
+                }
             }
-            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;
+            if (merged.size === widened.length)
+                return folded;
+            widened = [...merged.values()];
+        }
+    }
+    /** Read one graph page by identity: cached pages come off local disk, the
+     * rest are fetched straight from content storage and cached on the way in.
+     * The graph proves every page against its declared identity as it parses,
+     * so this reader only guards the cache against torn copies. */
+    async readGraphPage(identity, resourceId, ref) {
+        const path = join(graphPageCacheDir(this.cacheDir(identity)), `${ref.sha256}.bin`);
+        const cached = readVerifiedRegistryPage(path, ref, sha256Hex);
+        if (cached) {
+            this.graphPageReads.cachedPages += 1;
+            return cached;
+        }
+        const bytes = await retryContent(() => this.direct.fetchObject(resourceId, { kind: "block", sha256: ref.sha256 }), true);
+        writeVerifiedRegistryPage(path, ref, bytes, sha256Hex);
+        this.graphPageReads.fetchedPages += 1;
+        this.graphPageReads.fetchedBytes += bytes.byteLength;
+        return bytes;
     }
     localPort(identity) {
         const userRoot = this.userRoot(identity);
@@ -1604,11 +1680,13 @@ export class UserGroundHost {
         const unique = new Map(wants.map((want) => [want.artifact.contentHash, want]));
         const sole = unique.size === 1 ? [...unique.values()][0]?.artifact : undefined;
         const started = performance.now();
+        const planeBefore = this.direct.metrics();
         let declaredBytes = 0;
         let downloadedBytes = 0;
         let downloadedChunks = 0;
         let reusedChunks = 0;
         let requests = 0;
+        let cacheWriteMs = 0;
         const entityId = trace?.entityId ?? sole?.entityId;
         const identifiers = {
             ...(trace?.workspaceId ? { workspaceId: trace.workspaceId } : {}),
@@ -1673,10 +1751,14 @@ export class UserGroundHost {
                     return fetchObject({ kind: "block", sha256: chunk.sha256 });
                 },
                 putChunk: async (artifact, _manifest, index, bytes) => {
+                    const writeStarted = performance.now();
                     await target(artifact).putChunk(index, bytes);
+                    cacheWriteMs += performance.now() - writeStarted;
                 },
                 sealArtifact: async (artifact) => {
+                    const sealStarted = performance.now();
                     const sealed = await target(artifact).seal();
+                    cacheWriteMs += performance.now() - sealStarted;
                     return { local: sealed, bytes: sealed.bytes, contentHash: sealed.contentHash };
                 },
             }, {
@@ -1704,7 +1786,12 @@ export class UserGroundHost {
                     downloadedBytes,
                     downloadedChunks,
                     reusedChunks,
+                    // `requests` is logical object reads; the plane deltas below are
+                    // the physical facts — actual storage GETs, sealed bytes on the
+                    // wire, refs round-trips, decrypt and cache-write CPU.
                     requests,
+                    ...physicalPlaneDelta(planeBefore, this.direct.metrics()),
+                    cacheWriteMs: Math.round(cacheWriteMs),
                 },
             });
             return content;
@@ -2124,7 +2211,8 @@ export class UserGroundHost {
         // 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));
+            await this.cloudPort(identity, { kind: "none" })
+                .lookup(privateEntityResourceId(identity.userId, sha256Hex));
         }
         const state = this.cloudState;
         if (!state)
@@ -2155,6 +2243,12 @@ export class UserGroundHost {
             leg[`${name}Ms`] = performance.now() - started;
             return value;
         };
+        const timedAsync = async (name, work) => {
+            const started = performance.now();
+            const value = await work();
+            leg[`${name}Ms`] = performance.now() - started;
+            return value;
+        };
         if (trace?.journey === "register") {
             this.stage({
                 primitive: "register",
@@ -2167,7 +2261,7 @@ export class UserGroundHost {
             .map(portableRecord), readGroundRowsForRoots(this.databasePath(identity), "detection_notebook", publicationRootIds)
             .map(portableRecord)));
         const accepted = timed("officialRows", () => readAcceptedResults(this.databasePath(identity), state.resourceId, state.deliveryWatermark, deliveryWatermark));
-        const rebuilt = timed("merge", () => publicationRoots(state.graph, localRecords, accepted));
+        const rebuilt = await timedAsync("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")
@@ -2179,7 +2273,7 @@ export class UserGroundHost {
         // 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 publication = timed("pages", () => state.graph.rebuild(projected));
         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
@@ -5177,7 +5271,7 @@ function recordRootResolver(records) {
  * 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) {
+async function publicationRoots(graph, localRecords, accepted) {
     const rebuilt = new Map();
     const walked = new Map(localRecords
         .filter((record) => record.parentUUID === null)
@@ -5194,9 +5288,16 @@ function publicationRoots(graph, localRecords, accepted) {
         for (const [rootId, records] of walked)
             rebuilt.set(rootId, records);
     }
+    // One page-bounded sweep answers every committed-root question this merge
+    // asks: which root holds each accepted result, and which root still files
+    // each record the walk re-rooted.
+    const located = await graph.membership(new Set([
+        ...accepted.map((result) => result.uuid),
+        ...localRecords.map((record) => record.uuid),
+    ]));
     const overlays = new Map();
     for (const result of accepted) {
-        const rootId = graph.rootOf(result.uuid);
+        const rootId = located.get(result.uuid) ?? null;
         if (rootId === null || walked.has(rootId))
             continue;
         const overlay = overlays.get(rootId);
@@ -5206,7 +5307,8 @@ function publicationRoots(graph, localRecords, accepted) {
             overlays.set(rootId, [result]);
     }
     for (const [rootId, results] of overlays) {
-        const byUuid = new Map(graph.recordsFor(rootId).map((record) => [record.uuid, record]));
+        const byUuid = new Map((await 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
@@ -5219,7 +5321,7 @@ function publicationRoots(graph, localRecords, accepted) {
     if (graph.head === null) {
         for (const rootId of graph.rootIds()) {
             if (!rebuilt.has(rootId))
-                rebuilt.set(rootId, graph.recordsFor(rootId));
+                rebuilt.set(rootId, await graph.recordsFor(rootId));
         }
     }
     // Re-rooting is a move, not a copy: an enclosing Register walks records the
@@ -5228,7 +5330,7 @@ function publicationRoots(graph, localRecords, accepted) {
     // 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);
+        const rootId = located.get(record.uuid) ?? null;
         if (rootId === null || walked.has(rootId))
             continue;
         const gone = vacated.get(rootId);
@@ -5238,7 +5340,7 @@ function publicationRoots(graph, localRecords, accepted) {
             vacated.set(rootId, new Set([record.uuid]));
     }
     for (const [rootId, gone] of vacated) {
-        const held = rebuilt.get(rootId) ?? graph.recordsFor(rootId);
+        const held = rebuilt.get(rootId) ?? await graph.recordsFor(rootId);
         rebuilt.set(rootId, held.filter((record) => !gone.has(record.uuid)));
     }
     return rebuilt;
@@ -5814,13 +5916,15 @@ async function installCloudWorkspace(input) {
         alreadyMaterialized: false,
     };
 }
-function readyFromFrame(frame, graph) {
+/** The authority's ready frame as Live sees it. The snapshot carries only the
+ * records the caller's scope selected — never a flattened whole account. */
+function readyFromFrame(frame, graph, records) {
     const cloud = {
         resourceId: String(frame.resource_id || ""),
         version: Number(frame.head_version),
         deliveryWatermark: Number(frame.delivery_watermark),
         checksum: String(frame.snapshot_checksum || ""),
-        snapshot: graph.snapshot(),
+        snapshot: snapshotFromRecords(records),
         ...(graph.head ? { head: graph.head } : {}),
     };
     return {
@@ -5835,6 +5939,18 @@ function readyFromFrame(frame, graph) {
         },
     };
 }
+/** What one leg physically did on the content plane: the counter movement
+ * between its start and end, ms rounded for the ledger. */
+function physicalPlaneDelta(before, after) {
+    return {
+        rangedGets: after.rangedGets - before.rangedGets,
+        wholeGets: after.wholeGets - before.wholeGets,
+        fetchedSealedBytes: after.fetchedBytes - before.fetchedBytes,
+        refsFrames: after.refsFrames - before.refsFrames,
+        refsMs: Math.round(after.refsMs - before.refsMs),
+        decryptMs: Math.round(after.decryptMs - before.decryptMs),
+    };
+}
 /** Immutable content reads and writes are idempotent. Retry transient wire or
  * authority failures; reads additionally tolerate the brief not-found window
  * between an immutable object acknowledgement and globally visible R2 state. */