@amalgm/shell 0.1.125 → 0.1.127

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";
@@ -11,7 +11,8 @@ import { EntityApplyHost, } from "./entity-apply-host.js";
 import { EntityRecordSqliteStore } from "./entity-record-store.js";
 import { observeEntityRecordPorts } from "./entity-record-observability.js";
 import { indexRowsByOutermostRoot } from "./ground-root-index.js";
-import { ContentCacheDownloadSet, captureContentFile, hashContentFile, pruneSettledContentCache, sealCapturedArtifact, } from "./content-cache-host.js";
+import { ContentCacheDownloadSet, captureContentFile, hasSealedContent, hashContentFile, pruneSettledContentCache, sealCapturedArtifact, } from "./content-cache-host.js";
+import { StagedContentSet, addStagingEvidenceDir, clearAddStagingEvidence, } from "./workspace-add-staging.js";
 import { DirectContentPlane } from "./content-direct.js";
 import { encodeContentWireBytes } from "./content-wire-codec.js";
 import { exactTextReplay, planGroundDetection, reconcileGroundUUIDs, } from "./detection/portable.js";
@@ -23,6 +24,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 +36,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 +96,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 +164,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 +307,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 +330,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 +342,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;
             },
@@ -369,7 +384,7 @@ export class UserGroundHost {
                         destinationParent: input.destinationParent,
                         cloudHead: input.cloudHead,
                         deliveryWatermark: input.deliveryWatermark,
-                        readContent: (artifacts) => this.downloadContentSet(privateEntityResourceId(identity.userId, sha256Hex), this.cacheDir(identity), artifacts.map((artifact) => ({ artifact })), 10, { journey: "add", workspaceId: input.workspace.uuid }),
+                        readContent: (artifacts, staged) => this.downloadContentSet(privateEntityResourceId(identity.userId, sha256Hex), this.cacheDir(identity), artifacts.map((artifact) => ({ artifact })), 10, { journey: "add", workspaceId: input.workspace.uuid }, staged),
                         adoptMaterialization: (rootUUID) => {
                             const settled = this.adoptCloudDeliveryBaseline(identity, input.deliveryWatermark, rootUUID);
                             this.applyRail?.recordsAvailable();
@@ -478,8 +493,9 @@ export class UserGroundHost {
             if (stagedAcrossBlindInterval && hasRootRows(database, intent.resourceId, intent.workspaceId)) {
                 // Rows prove that staging was verified before the crash, not that its
                 // bytes remained unchanged while no watcher existed. Return this
-                // private install to the intent-only stage and reproduce it from the
-                // verified immutable cache before making it visible.
+                // private install to the intent-only stage; the retried install keeps
+                // the staged bytes but re-proves every retained chunk against its
+                // manifest before anything becomes visible.
                 deleteRootRows(database, intent.resourceId, intent.workspaceId);
             }
             await installCloudWorkspace({
@@ -496,7 +512,7 @@ export class UserGroundHost {
                 destinationParent: dirname(intent.destinationPath),
                 cloudHead: intent.cloudHead,
                 deliveryWatermark: intent.deliveryWatermark,
-                readContent: (artifacts) => this.downloadContentSet(intent.resourceId, this.cacheDir(identity), artifacts.map((artifact) => ({ artifact })), 10, { journey: "add", workspaceId: intent.workspaceId }),
+                readContent: (artifacts, staged) => this.downloadContentSet(intent.resourceId, this.cacheDir(identity), artifacts.map((artifact) => ({ artifact })), 10, { journey: "add", workspaceId: intent.workspaceId }, staged),
                 adoptMaterialization: (rootUUID) => {
                     this.adoptCloudDeliveryBaseline(identity, intent.deliveryWatermark, rootUUID);
                     this.applyRail?.recordsAvailable();
@@ -564,12 +580,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 +784,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 +1161,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 +1172,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 +1188,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 +1199,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);
@@ -1600,15 +1678,18 @@ export class UserGroundHost {
      * manifests and blocks alike — shares one wide lane bound, so no artifact
      * serializes behind another's plan or seal. Each object is still its own
      * storage request. A lone artifact is a set of one. */
-    async downloadContentSet(resourceId, cacheDir, wants, retryAttempts = 10, trace) {
+    async downloadContentSet(resourceId, cacheDir, wants, retryAttempts = 10, trace, staged) {
         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;
+        let stagedArtifacts = 0;
         const entityId = trace?.entityId ?? sole?.entityId;
         const identifiers = {
             ...(trace?.workspaceId ? { workspaceId: trace.workspaceId } : {}),
@@ -1628,6 +1709,7 @@ export class UserGroundHost {
             },
         });
         const downloads = new ContentCacheDownloadSet(cacheDir);
+        const stagedSet = staged ? new StagedContentSet(staged.evidenceDir) : null;
         const targets = new Map();
         const target = (artifact) => {
             const found = targets.get(artifact.contentHash);
@@ -1662,7 +1744,18 @@ export class UserGroundHost {
                             throw new Error(checked.error);
                         return checked.value;
                     })();
-                    targets.set(artifact.contentHash, downloads.target(artifact, manifest));
+                    // An Add stages ordinary files directly at their hidden final
+                    // destination — except content this machine already holds sealed,
+                    // which stays on the cache rail so a warm re-Add remains a local
+                    // clone instead of a fresh download.
+                    const stagedPaths = stagedSet && staged?.destinations.get(artifact.contentHash);
+                    if (stagedPaths && !hasSealedContent(cacheDir, artifact.contentHash, manifest.bytes)) {
+                        stagedArtifacts += 1;
+                        targets.set(artifact.contentHash, stagedSet.target(artifact, manifest, stagedPaths));
+                    }
+                    else {
+                        targets.set(artifact.contentHash, downloads.target(artifact, manifest));
+                    }
                     return manifest;
                 },
                 hasChunk: async (artifact, _manifest, index) => target(artifact).hasChunk(index),
@@ -1673,10 +1766,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 +1801,15 @@ 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 local-write CPU.
+                    // `cacheWriteMs` is all local placement time, cache and staged
+                    // rails alike; `stagedArtifacts` counts single-write placements.
                     requests,
+                    ...physicalPlaneDelta(planeBefore, this.direct.metrics()),
+                    cacheWriteMs: Math.round(cacheWriteMs),
+                    ...(stagedArtifacts > 0 ? { stagedArtifacts } : {}),
                 },
             });
             return content;
@@ -1728,6 +1833,7 @@ export class UserGroundHost {
         finally {
             await Promise.all([...targets.values()].map((open) => open.close()));
             downloads.close();
+            stagedSet?.close();
         }
     }
     async downloadContent(resourceId, cacheDir, artifact, retryAttempts = 10, trace, knownManifest) {
@@ -2124,7 +2230,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 +2262,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 +2280,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 +2292,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 +5290,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 +5307,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 +5326,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 +5340,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 +5349,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 +5359,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;
@@ -5336,9 +5457,17 @@ function installCloudGround(input) {
     })();
 }
 async function materializeRecords(input) {
-    const { records, rootPath, cacheDir, bindingDir, readContent } = input;
+    const { records, rootPath, cacheDir, bindingDir, staged, readContent } = input;
     const repositories = [];
     const repositoriesByUuid = new Map();
+    const paths = portablePaths(records, input.boundaryUUID ? new Set([input.boundaryUUID]) : new Set());
+    const destinationOf = (relativePath) => {
+        const destination = relativePath ? join(rootPath, ...relativePath.split("/")) : rootPath;
+        if (!pathWithin(rootPath, destination)) {
+            throw new Error(`cloud entity path escapes its workspace: ${relativePath}`);
+        }
+        return destination;
+    };
     // One download set covers everything the wire owes this add up front:
     // every ordinary file artifact and every repository transport head, side
     // by side under one wide object bound. Only transport parents — links a
@@ -5346,6 +5475,7 @@ async function materializeRecords(input) {
     // round is again one set across every chain. Disk application below keeps
     // its ordered, validated walk.
     const wanted = new Map();
+    const stagedDestinations = staged ? new Map() : null;
     const repositoryHeads = [];
     for (const record of records) {
         if (record.type === "repo.git") {
@@ -5360,11 +5490,30 @@ async function materializeRecords(input) {
         }
         else if (["file.text", "file.binary", "link"].includes(record.type)) {
             const artifact = artifactForRecord(record);
-            if (artifact)
-                wanted.set(artifact.contentHash, artifact);
+            if (!artifact)
+                continue;
+            wanted.set(artifact.contentHash, artifact);
+            // Links and repository transports keep the cache rail: a link's
+            // small payload is verified there and becomes a symlink, and a
+            // transport is never its final worktree. Ordinary file bytes are
+            // the cold Add's mass, and they land exactly once.
+            if (stagedDestinations && record.type !== "link") {
+                const destination = destinationOf(paths.get(record.uuid));
+                const list = stagedDestinations.get(artifact.contentHash) ?? [];
+                list.push(destination);
+                stagedDestinations.set(artifact.contentHash, list);
+            }
         }
     }
-    const fileContent = await readContent([...wanted.values()]);
+    if (stagedDestinations) {
+        // A deterministic primary destination keeps resume evidence valid: the
+        // same first path receives the stream on every attempt.
+        for (const list of stagedDestinations.values())
+            list.sort();
+    }
+    const fileContent = await readContent([...wanted.values()], staged && stagedDestinations
+        ? { evidenceDir: staged.evidenceDir, destinations: stagedDestinations }
+        : undefined);
     const repositoryChains = new Map();
     const walking = repositoryHeads.map(({ record, artifact }) => {
         const local = fileContent.get(artifact.contentHash);
@@ -5418,7 +5567,6 @@ async function materializeRecords(input) {
         repositories.push(repository);
         repositoriesByUuid.set(record.uuid, repository);
     };
-    const paths = portablePaths(records, input.boundaryUUID ? new Set([input.boundaryUUID]) : new Set());
     const recordsByUuid = new Map(records.map((record) => [record.uuid, record]));
     const repositoryOwner = (record) => {
         let parentUUID = record.parentUUID;
@@ -5456,29 +5604,59 @@ async function materializeRecords(input) {
         return leftPath.split("/").length - rightPath.split("/").length
             || (leftPath < rightPath ? -1 : leftPath > rightPath ? 1 : 0);
     });
+    // Staged mode walks ground that may be retained from an interrupted Add:
+    // files were already re-proven by the download, directories are lawful
+    // skeleton, and symlinks and repositories are recreated. Existence alone
+    // therefore no longer proves a record collision — the walk's own claims
+    // do, case- and normalization-folded because filesystems merge such
+    // names into one physical path.
+    const claimed = staged ? new Set() : null;
+    const claim = (relativePath) => {
+        if (!claimed || relativePath === "")
+            return;
+        const key = relativePath.normalize("NFC").toLowerCase();
+        if (claimed.has(key)) {
+            throw new Error(`cloud materialization conflicts with ${relativePath}`);
+        }
+        claimed.add(key);
+    };
     for (const record of ordered) {
         const relativePath = paths.get(record.uuid);
-        const destination = relativePath ? join(rootPath, ...relativePath.split("/")) : rootPath;
-        if (!pathWithin(rootPath, destination)) {
-            throw new Error(`cloud entity path escapes its workspace: ${relativePath}`);
-        }
+        const destination = destinationOf(relativePath);
+        claim(relativePath);
         if (relativePath === "") {
-            if (record.type === "repo.git")
+            if (record.type === "repo.git") {
+                if (staged && pathExists(destination)) {
+                    rmSync(destination, { recursive: true, force: true });
+                }
                 await materializeRepository(record, destination);
-            else
+            }
+            else {
                 ensureUserDir(destination);
+            }
         }
         else if (record.type === "folder") {
-            if (pathExists(destination)) {
+            if (!pathExists(destination)) {
+                ensureUserDir(destination);
+            }
+            else if (!staged || repositoryOwner(record)) {
                 assertRepositoryBoundaryPath(record, relativePath, destination);
             }
             else {
-                ensureUserDir(destination);
+                const stats = lstatSync(destination);
+                if (!stats.isDirectory() || stats.isSymbolicLink()) {
+                    throw new Error(`cloud materialization conflicts with ${relativePath}`);
+                }
             }
         }
         else if (record.type === "repo.git") {
             if (pathExists(destination)) {
-                assertRepositoryBoundaryPath(record, relativePath, destination);
+                if (!staged || repositoryOwner(record)) {
+                    assertRepositoryBoundaryPath(record, relativePath, destination);
+                }
+                else {
+                    rmSync(destination, { recursive: true, force: true });
+                }
             }
             await materializeRepository(record, destination);
         }
@@ -5486,8 +5664,11 @@ async function materializeRecords(input) {
             if (!record.payloadVersion || !UUID.test(record.payloadVersion)) {
                 throw new Error(`cloud reference ${record.uuid} has no workspace identity`);
             }
-            if (pathExists(destination))
+            if (staged)
+                rmSync(destination, { force: true });
+            else if (pathExists(destination)) {
                 throw new Error(`cloud materialization conflicts with ${relativePath}`);
+            }
             ensureUserDir(dirname(destination));
             const binding = join(bindingDir, record.payloadVersion.toLowerCase());
             symlinkSync(relative(dirname(destination), binding), destination);
@@ -5495,21 +5676,41 @@ async function materializeRecords(input) {
         else if (["file.text", "file.binary", "link"].includes(record.type)) {
             if (!record.payloadVersion)
                 throw new Error(`cloud leaf ${record.uuid} has no content head`);
-            if (pathExists(destination))
-                throw new Error(`cloud materialization conflicts with ${relativePath}`);
             const artifact = artifactForRecord(record);
             if (!artifact)
                 throw new Error(`cloud leaf ${record.uuid} has no transfer artifact`);
             const local = fileContent.get(artifact.contentHash);
             if (!local)
                 throw new Error(`cloud leaf ${record.uuid} content was not downloaded`);
-            ensureUserDir(dirname(destination));
-            if (record.type === "link")
+            if (record.type === "link") {
+                if (staged)
+                    rmSync(destination, { force: true });
+                else if (pathExists(destination)) {
+                    throw new Error(`cloud materialization conflicts with ${relativePath}`);
+                }
+                ensureUserDir(dirname(destination));
                 symlinkSync(readFileSync(local.file, "utf8"), destination);
-            // Mode is not portable state: a fresh user file gets 0644, the same
-            // default Apply gives a fresh target, never the cache's private 0600.
-            else
+            }
+            else if (staged && pathWithin(rootPath, local.file)) {
+                // The download already wrote, proved, and fsynced these bytes at
+                // their destination — the single-write law. The walk only proves
+                // the placement still stands.
+                const stats = lstatSync(destination);
+                if (!stats.isFile() || stats.isSymbolicLink() || stats.size !== local.bytes) {
+                    throw new Error(`cloud content ${local.contentHash} is corrupt`);
+                }
+            }
+            else {
+                if (staged)
+                    rmSync(destination, { force: true });
+                else if (pathExists(destination)) {
+                    throw new Error(`cloud materialization conflicts with ${relativePath}`);
+                }
+                ensureUserDir(dirname(destination));
+                // Mode is not portable state: a fresh user file gets 0644, the same
+                // default Apply gives a fresh target, never the cache's private 0600.
                 atomicCopy(local.file, destination, 0o644);
+            }
         }
         else {
             throw new Error(`materialization for ${record.type} requires its dedicated adapter`);
@@ -5654,6 +5855,7 @@ async function installCloudWorkspace(input) {
                 throw new Error(`local workspace ${workspace.uuid} has unresolved placement`);
             }
             renameSync(pending.stagingPath, pending.destinationPath);
+            clearAddStagingEvidence(database, workspace.uuid);
             revealed = true;
         }
         else if (pending && pathExists(pending.stagingPath)) {
@@ -5661,6 +5863,7 @@ async function installCloudWorkspace(input) {
         }
         if (pending && pathExists(root.absolutePath)) {
             refreshRevealedRootEvidence(database, workspace.uuid, root.absolutePath);
+            clearAddStagingEvidence(database, workspace.uuid);
         }
         if (revealed)
             await onStage?.("ground-revealed");
@@ -5762,9 +5965,9 @@ async function installCloudWorkspace(input) {
     if (pathExists(binding)) {
         throw new Error(`workspace ${workspace.uuid} has a binding without committed entity rows`);
     }
-    if (pathExists(intent.stagingPath)) {
-        rmSync(intent.stagingPath, { recursive: true, force: true });
-    }
+    // Staging retained from an interrupted Add is deliberately kept: the
+    // staged download re-proves every retained chunk against its manifest and
+    // downloads only the gaps. Unverified staged bytes are never trusted.
     const selection = workspaceAddSelection(intent);
     const materialized = await materializeRecords({
         records: intent.records,
@@ -5772,6 +5975,7 @@ async function installCloudWorkspace(input) {
         boundaryUUID: intent.workspaceId,
         cacheDir,
         bindingDir,
+        staged: { evidenceDir: addStagingEvidenceDir(database, intent.workspaceId) },
         readContent,
     });
     const rows = projectMaterializedGraph(materialized.rows, materialized.repositories.map((repository) => ({
@@ -5788,6 +5992,7 @@ async function installCloudWorkspace(input) {
     input.adoptMaterialization(intent.workspaceId);
     await onStage?.("rows-committed");
     renameSync(intent.stagingPath, intent.destinationPath);
+    clearAddStagingEvidence(database, intent.workspaceId);
     refreshRevealedRootEvidence(database, intent.workspaceId, intent.destinationPath);
     await onStage?.("ground-revealed");
     ensureWorkspaceBinding({
@@ -5814,13 +6019,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 +6042,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. */