@amalgm/shell 0.1.126 → 0.1.128

package/dist/user-ground-host.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";
@@ -383,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();
@@ -492,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({
@@ -510,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();
@@ -1676,7 +1678,7 @@ 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();
@@ -1687,6 +1689,7 @@ export class UserGroundHost {
         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 } : {}),
@@ -1706,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);
@@ -1740,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),
@@ -1788,10 +1803,13 @@ export class UserGroundHost {
                     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.
+                    // 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;
@@ -1815,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) {
@@ -5438,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
@@ -5448,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") {
@@ -5462,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);
@@ -5520,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;
@@ -5558,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);
         }
@@ -5588,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);
@@ -5597,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`);
@@ -5756,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)) {
@@ -5763,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");
@@ -5864,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,
@@ -5874,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) => ({
@@ -5890,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({