@amalgm/shell 0.1.37 → 0.1.39

package/dist/user-ground-host.js

@@ -6,7 +6,7 @@ import { buildUserHomeManifest, buildUserManifest, liveMachineStateDir, scopedAm
 import { CHUNK_BYTES, CONTENT_CONTRACT, ENTITY_CLOUD_CONTRACT, ENTITY_CLOUD_SCHEMA_VERSION, artifactForRecord, canonicalVersion, checkContentManifest, classifyDirectory, classifyFile, classifyRegisteredRoot, convergeUserGround, createUserGroundEnrollmentPolicy, isRepositoryMetadataEntry, download as downloadArtifact, deriveUploadManifest, membershipHash, parseSnapshot, pathIsSuspect, privateEntityResourceId, sameRecords, snapshotFromRecords, stableJson, travelingRecords, upload as uploadArtifact, userGroundRecords, } from "@amalgm/live";
 import Database from "better-sqlite3";
 import { atomicCopy, atomicWrite, ensurePrivateDir } from "./filesystem.js";
-import { ContentCacheDownload, hashContentFile } from "./content-cache-host.js";
+import { ContentCacheDownload, captureContentFile, hashContentFile, } from "./content-cache-host.js";
 import { decodeContentWireBytes, encodeContentWireBytes } from "./content-wire-codec.js";
 import { WORKSPACE_UUID as UUID, createFilesRegisterPorts, ensureWorkspaceReference, pathExists, pathWithin, referenceWorkspaceId, workspaceBindingDir, } from "./files-register-host.js";
 import { applyRepositoryFiles, captureRepository, inspectRepositoryTransportFile, hasGitMarker, } from "./git-repository-host.js";
@@ -117,6 +117,7 @@ export class UserGroundHost {
             userRoot,
             deviceId: identity.deviceId,
             onReferenceDeclared: () => this.scheduleRescan(),
+            findKnownWorkspaceId: ({ absolutePath, deviceNumber, inode }) => findKnownEntityId(this.databasePath(identity), absolutePath, deviceNumber, inode),
         });
         const add = {
             lookupRegistry: async () => {
@@ -151,6 +152,76 @@ export class UserGroundHost {
         };
         return { register, add };
     }
+    /** Finish the user-visible register journey inside the one persistent Files
+     * owner. The declaration remains durable if any later stage fails, and a
+     * retry reuses its UUID through filesCommandPorts().register. */
+    async completeWorkspaceRegistration(workspaceId) {
+        const identity = this.activeIdentity;
+        if (!identity || !this.converged || !this.cloudState) {
+            throw new Error("Files register requires a converged authenticated machine");
+        }
+        let watch;
+        try {
+            this.ensureWatchers(identity);
+            watch = this.watchHost.evidence();
+            assertHealthyWatch(watch, workspaceId);
+        }
+        catch (error) {
+            throw stageError("Watch coverage", error);
+        }
+        let rows = readRows(this.databasePath(identity));
+        if (rows.some((row) => row.uuid === workspaceId)
+            && this.cloudState.records.some((record) => record.uuid === workspaceId)) {
+            return {
+                registered: true,
+                entityCount: descendantRows(rows, workspaceId).length,
+                cloudHead: this.cloudState.checksum,
+                watch,
+            };
+        }
+        this.watchHost.suspectAll();
+        this.watchDirty = false;
+        try {
+            await this.syncNow();
+            if (!this.cloudState.records.some((record) => record.uuid === workspaceId)) {
+                // A pre-existing scan may have taken its observation before this
+                // declaration. Preserve the declared root as suspicion and give it
+                // one scan of its own. Completion is evidence about this workspace,
+                // never a demand that unrelated live Watch traffic become silent.
+                this.watchHost.suspectAll();
+                this.watchDirty = false;
+                await this.syncNow();
+            }
+        }
+        catch (error) {
+            const failedStage = filesPipelineStage(error);
+            if (failedStage) {
+                throw stageError(failedStage, error.cause ?? error);
+            }
+            throw stageError("entity registration or cloud publication", error);
+        }
+        try {
+            this.ensureWatchers(identity);
+            watch = this.watchHost.evidence();
+            assertHealthyWatch(watch, workspaceId);
+        }
+        catch (error) {
+            throw stageError("Watch coverage", error);
+        }
+        rows = readRows(this.databasePath(identity));
+        if (!rows.some((row) => row.uuid === workspaceId)) {
+            throw stageError("entity registration", new Error(`workspace ${workspaceId} was not recorded`));
+        }
+        if (!this.cloudState.records.some((record) => record.uuid === workspaceId)) {
+            throw stageError("cloud graph commit", new Error(`workspace ${workspaceId} is absent from the committed head`));
+        }
+        return {
+            registered: true,
+            entityCount: descendantRows(rows, workspaceId).length,
+            cloudHead: this.cloudState.checksum,
+            watch,
+        };
+    }
     /** Make every observed filesystem change durable in SQLite, immutable
      * content storage, and the official cloud head before returning. */
     async flush() {
@@ -585,14 +656,20 @@ export class UserGroundHost {
         if (!state)
             throw new Error("cloud state is unavailable for user-ground Watch");
         const observations = this.watchHost.observations();
-        const localRecords = await scanAndRegister({
-            identity,
-            userRoot: this.userRoot(identity),
-            database: this.databasePath(identity),
-            cacheDir: this.cacheDir(identity),
-            onScan: this.options.onDetectScan,
-            suspicions: new Map(observations.map((observation) => [observation.directory, observation.suspicion.paths])),
-        });
+        let localRecords;
+        try {
+            localRecords = await scanAndRegister({
+                identity,
+                userRoot: this.userRoot(identity),
+                database: this.databasePath(identity),
+                cacheDir: this.cacheDir(identity),
+                onScan: this.options.onDetectScan,
+                suspicions: new Map(observations.map((observation) => [observation.directory, observation.suspicion.paths])),
+            });
+        }
+        catch (error) {
+            throw pipelineStageError("entity registration", error);
+        }
         const snapshot = snapshotFromRecords(travelingRecords(mergeMaterializedRoots(state.records, localRecords)));
         const checksum = sha256Hex(stableJson(snapshot));
         if (checksum === state.checksum) {
@@ -634,24 +711,34 @@ export class UserGroundHost {
     async drainOutbox(identity) {
         for (const pending of readOutbox(this.databasePath(identity))) {
             const snapshot = snapshotFromRecords(JSON.parse(pending.snapshotJson).records || []);
-            const localRootIds = new Set(readRows(this.databasePath(identity))
-                .filter((row) => row.parentUUID === null)
-                .map((row) => row.rootUUID));
-            await this.uploadSnapshotContent(identity, pending.resourceId, recordsWithinRoots(snapshot.records, localRootIds));
-            const frame = await this.wire.request({
-                type: "shared.mutation.submit",
-                envelope: {
-                    resourceId: pending.resourceId,
-                    authorityEpoch: pending.authorityEpoch,
-                    mutationId: pending.mutationId,
-                    deviceId: identity.deviceId,
-                    baseVersion: pending.baseVersion,
-                    contract: ENTITY_CLOUD_CONTRACT,
-                    schemaVersion: ENTITY_CLOUD_SCHEMA_VERSION,
-                    operationKind: "entity.snapshot.replace",
-                    operation: { kind: "entity.snapshot.replace", snapshot },
-                },
-            }, ["shared.mutation.ack"]);
+            const locallyMaterializedIds = new Set(readRows(this.databasePath(identity))
+                .map((row) => row.uuid));
+            try {
+                await this.uploadSnapshotContent(identity, pending.resourceId, snapshot.records.filter((record) => locallyMaterializedIds.has(record.uuid)));
+            }
+            catch (error) {
+                throw pipelineStageError("cloud upload", error);
+            }
+            let frame;
+            try {
+                frame = await this.wire.request({
+                    type: "shared.mutation.submit",
+                    envelope: {
+                        resourceId: pending.resourceId,
+                        authorityEpoch: pending.authorityEpoch,
+                        mutationId: pending.mutationId,
+                        deviceId: identity.deviceId,
+                        baseVersion: pending.baseVersion,
+                        contract: ENTITY_CLOUD_CONTRACT,
+                        schemaVersion: ENTITY_CLOUD_SCHEMA_VERSION,
+                        operationKind: "entity.snapshot.replace",
+                        operation: { kind: "entity.snapshot.replace", snapshot },
+                    },
+                }, ["shared.mutation.ack"]);
+            }
+            catch (error) {
+                throw pipelineStageError("cloud graph commit", error);
+            }
             this.cloudState = {
                 resourceId: pending.resourceId,
                 authorityEpoch: Number(frame.authority_epoch),
@@ -686,12 +773,48 @@ function normalizedIdentity(identity) {
         deviceId: String(identity.deviceId).trim(),
     };
 }
+function stageError(stage, error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return Object.assign(new Error(`Files register failed during ${stage}: ${message}`), {
+        code: `files_register_${stage.toLowerCase().replaceAll(/[^a-z0-9]+/g, "_")}`,
+        cause: error,
+    });
+}
+function pipelineStageError(stage, error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return Object.assign(new Error(`Files pipeline failed during ${stage}: ${message}`), {
+        code: `files_pipeline_${stage.toLowerCase().replaceAll(/[^a-z0-9]+/g, "_")}`,
+        filesStage: stage,
+        cause: error,
+    });
+}
+function filesPipelineStage(error) {
+    const stage = error instanceof Error
+        ? error.filesStage
+        : null;
+    return typeof stage === "string" && stage ? stage : null;
+}
+function descendantRows(rows, rootUUID) {
+    const included = new Set([rootUUID]);
+    let changed = true;
+    while (changed) {
+        changed = false;
+        for (const row of rows) {
+            if (row.parentUUID !== null && included.has(row.parentUUID) && !included.has(row.uuid)) {
+                included.add(row.uuid);
+                changed = true;
+            }
+        }
+    }
+    return rows.filter((row) => included.has(row.uuid));
+}
 function assertHealthyWatch(evidence, rootId) {
     const root = evidence.roots.find((candidate) => candidate.rootId === rootId);
     const content = root?.contentOwner
         ? evidence.content.find((candidate) => candidate.directory === root.contentOwner)
         : undefined;
-    const address = root?.contentOwner
+    const ownsContent = root?.contentOwner === root?.directory;
+    const address = ownsContent
         ? evidence.addresses.find((candidate) => candidate.rootIds.includes(rootId))
         : undefined;
     if (evidence.health.state !== "healthy"
@@ -699,7 +822,7 @@ function assertHealthyWatch(evidence, rootId) {
         || evidence.health.addressHandles !== evidence.addresses.length
         || !root?.materialized
         || !content?.rootIds.includes(rootId)
-        || !address) {
+        || (ownsContent && !address)) {
         throw new Error(`Watch coverage is not healthy for workspace ${rootId}: ${evidence.health.reason ?? "incomplete handle evidence"}`);
     }
 }
@@ -772,6 +895,10 @@ function initializeDatabase(file) {
       snapshot_json TEXT NOT NULL,
       created_at TEXT NOT NULL
     );
+    CREATE INDEX IF NOT EXISTS entities_by_absolute_path
+      ON entities(absolute_path);
+    CREATE INDEX IF NOT EXISTS entities_by_physical_identity
+      ON entities(device_number, inode);
   `);
     const currentEntityColumns = new Set(database.prepare("PRAGMA table_info(entities)").all()
         .map(({ name }) => name));
@@ -809,6 +936,25 @@ function readRows(file) {
         database.close();
     }
 }
+/** Register identity lookup is indexed and bounded: the command never walks
+ * the complete entity table merely to discover that a directory is known. */
+function findKnownEntityId(file, absolutePath, deviceNumber, inode) {
+    if (!existsSync(file))
+        return null;
+    const database = initializeDatabase(file);
+    try {
+        const exact = database.prepare("SELECT uuid FROM entities WHERE absolute_path = ? LIMIT 2").all(absolutePath);
+        const physical = exact.length > 0 ? exact : database.prepare("SELECT uuid FROM entities WHERE device_number = ? AND inode = ? LIMIT 2").all(deviceNumber, inode);
+        const ids = [...new Set(physical.map(({ uuid }) => uuid))];
+        if (ids.length > 1) {
+            throw new Error(`entity graph has ambiguous identity for ${absolutePath}`);
+        }
+        return ids[0] ?? null;
+    }
+    finally {
+        database.close();
+    }
+}
 function readOutbox(file) {
     if (!existsSync(file))
         return [];
@@ -906,7 +1052,7 @@ function persistRows(file, identity, resourceId, rootUUID, rows, previousRows =
             replaceIdentity.run(identity.userId, identity.userEmail, identity.deviceId);
             for (const old of previousRows) {
                 if (!currentUuids.has(old.uuid))
-                    remove.run(old.uuid, resourceId, rootUUID);
+                    remove.run(old.uuid, resourceId, old.rootUUID);
             }
             for (const row of changed)
                 upsert.run(row.record.uuid, resourceId, rootUUID, row.record.type, row.record.parentUUID, row.record.name, row.record.status, row.record.version, row.record.payloadVersion, row.record.transportVersion, row.relativePath, row.absolutePath, row.deviceNumber, row.inode, row.byteSize, row.modifiedTimeMs, row.changedTimeMs, row.filesystemMode, row.contentVerifiedAtMs);
@@ -972,9 +1118,6 @@ function createDeclaredHome(input) {
         }
     }
 }
-function fileType(bytes) {
-    return classifyFile({ binary: bytes.includes(0) });
-}
 function slashPath(path) {
     return path.split(sep).join("/");
 }
@@ -1041,8 +1184,13 @@ async function scanAndRegister(input) {
     const ignoreFile = join(userRoot, ".amalgmignore");
     const policy = createUserGroundEnrollmentPolicy(existsSync(ignoreFile) ? readFileSync(ignoreFile, "utf8") : "");
     const bindingDir = workspaceBindingDir(userRoot, identity.deviceId);
-    const boundRoots = new Map(materializedWorkspaceBindings(bindingDir)
+    const boundRootEntries = materializedWorkspaceBindings(bindingDir);
+    const boundRoots = new Map(boundRootEntries
         .map(({ workspaceId, directory }) => [workspaceId, directory]));
+    const outerBoundRoots = boundRootEntries.filter((candidate) => !boundRootEntries.some((other) => other.workspaceId !== candidate.workspaceId
+        && pathWithin(other.directory, candidate.directory)));
+    const registeredBoundaries = new Map(boundRootEntries
+        .map(({ workspaceId, directory }) => [resolve(directory), workspaceId]));
     const suspicionFor = (root) => {
         if (!suspicions || !suspicions.has(root))
             return suspicions ? [] : null;
@@ -1066,7 +1214,7 @@ async function scanAndRegister(input) {
             repositoryCaptures: 0,
         };
         const started = performance.now();
-        const result = scanRoot({ ...parameters, evidence: counters });
+        const result = await scanRoot({ ...parameters, evidence: counters });
         onScan?.({
             rootId: parameters.rootUUID,
             directory: parameters.rootPath,
@@ -1099,35 +1247,26 @@ async function scanAndRegister(input) {
     });
     if (!core.transferable)
         deferredRootIds.add(coreUUID);
-    const targetRoots = new Set(core.referenceWorkspaceIds);
-    for (const row of existing) {
-        if (row.parentUUID === null && row.uuid !== coreUUID)
-            targetRoots.add(row.uuid);
-    }
-    for (const workspaceId of boundRoots.keys())
-        targetRoots.add(workspaceId);
-    for (const workspaceId of targetRoots) {
-        const rootPath = boundRoots.get(workspaceId);
-        if (!rootPath) {
-            // Missing external ground is undecided. Preserve its last witnessed rows
-            // so a move can be rescued; absence is never permission to delete it.
-            continue;
-        }
-        const existingRoot = existing.find((row) => row.uuid === workspaceId && row.parentUUID === null);
-        const existingWorkspaceRows = existing.filter((row) => row.rootUUID === workspaceId);
+    for (const { workspaceId, directory: rootPath } of outerBoundRoots) {
+        const existingRoot = existing.find((row) => row.uuid === workspaceId);
+        const existingWorkspaceRows = existing.filter((row) => row.resourceId === resourceId && pathWithin(rootPath, row.absolutePath));
         const scanned = await scan({
             identity,
             resourceId,
             rootUUID: workspaceId,
             rootName: existingRoot?.name || basename(rootPath),
             rootPath,
-            rootType: classifyRegisteredRoot({ repository: hasGitMarker(rootPath) }),
+            rootType: existingRoot?.parentUUID
+                ? classifyDirectory({ repository: hasGitMarker(rootPath) })
+                : classifyRegisteredRoot({ repository: hasGitMarker(rootPath) }),
+            rootParentUUID: existingRoot?.parentUUID ?? null,
             database,
             cacheDir,
             policy: () => true,
             bindingDir,
             suspects: existingWorkspaceRows.length === 0 ? null : suspicionFor(rootPath),
             existingRows: existingWorkspaceRows,
+            registeredBoundaries,
         });
         if (!scanned.transferable)
             deferredRootIds.add(workspaceId);
@@ -1136,11 +1275,17 @@ async function scanAndRegister(input) {
         .filter((row) => !deferredRootIds.has(row.rootUUID))
         .map(portableRecord);
 }
-function scanRoot(input) {
+async function scanRoot(input) {
     const { identity, resourceId, rootUUID, rootName, rootPath, rootType, database, cacheDir, policy, bindingDir, suspects = null, evidence, } = input;
-    const existingRows = (input.existingRows ?? readRows(database))
-        .filter((row) => row.resourceId === resourceId && row.rootUUID === rootUUID);
-    const existingByPath = new Map(existingRows.map((row) => [row.relativePath, row]));
+    const existingRows = input.existingRows
+        ?? readRows(database).filter((row) => row.resourceId === resourceId && row.rootUUID === rootUUID);
+    const existingByPath = new Map(existingRows.flatMap((row) => {
+        if (!pathWithin(rootPath, row.absolutePath))
+            return [];
+        const local = slashPath(relative(rootPath, row.absolutePath));
+        return [[local, row]];
+    }));
+    const registeredBoundaries = input.registeredBoundaries ?? new Map();
     const completeRepositoryEvidence = existingRows.every((row) => row.type !== "repo.git"
         || (Boolean(row.payloadVersion) && Boolean(row.transportVersion)));
     if (suspects !== null
@@ -1174,7 +1319,7 @@ function scanRoot(input) {
     entries.push({
         uuid: rootUUID,
         type: rootType,
-        parentUUID: null,
+        parentUUID: input.rootParentUUID ?? null,
         name: rootName,
         relativePath: "",
         absolutePath: rootPath,
@@ -1207,7 +1352,7 @@ function scanRoot(input) {
         }
         return [...new Set(paths)].sort();
     };
-    const visit = (directory, parentUUID, parentType, base = "", activeRepository = parentType === "repo.git"
+    const visit = async (directory, parentUUID, parentType, base = "", activeRepository = parentType === "repo.git"
         ? { root: directory, evidencePaths: repositoryEvidencePaths(directory), evidence: null }
         : null) => {
         const children = readdirSync(directory, { withFileTypes: true })
@@ -1222,7 +1367,13 @@ function scanRoot(input) {
             const stats = lstatSync(absolutePath);
             evidence && (evidence.entries += 1);
             const existing = existingByPath.get(relativePath);
-            const uuid = existing?.uuid || randomUUID();
+            const registeredBoundaryId = stats.isDirectory()
+                ? registeredBoundaries.get(resolve(absolutePath))
+                : undefined;
+            if (registeredBoundaryId && existing && existing.uuid !== registeredBoundaryId) {
+                throw new Error(`registered boundary ${absolutePath} conflicts with entity ${existing.uuid}`);
+            }
+            const uuid = registeredBoundaryId || existing?.uuid || randomUUID();
             const stableDuringCompleteCatchUp = suspects === null
                 && existing !== undefined
                 && reusableDuringCompleteCatchUp(existing, stats);
@@ -1294,16 +1445,9 @@ function scanRoot(input) {
                 }
                 else {
                     evidence && (evidence.contentReads += 1);
-                    const bytes = readFileSync(absolutePath);
-                    type = fileType(bytes);
-                    payloadVersion = sha256Hex(bytes);
-                    if (!activeRepository)
-                        immutableWriteArtifact(cacheDir, {
-                            entityId: uuid,
-                            entityType: type,
-                            kind: "file",
-                            contentHash: payloadVersion,
-                        }, bytes);
+                    const captured = await captureContentFile(absolutePath, stats, activeRepository ? null : cacheDir);
+                    type = classifyFile({ binary: captured.binary });
+                    payloadVersion = captured.contentHash;
                 }
             }
             else {
@@ -1324,7 +1468,7 @@ function scanRoot(input) {
                 ...statFingerprint(stats),
             });
             if (stats.isDirectory() && !stats.isSymbolicLink()) {
-                visit(absolutePath, uuid, type, relativePath, type === "repo.git"
+                await visit(absolutePath, uuid, type, relativePath, type === "repo.git"
                     ? {
                         root: absolutePath,
                         evidencePaths: repositoryEvidencePaths(absolutePath),
@@ -1334,7 +1478,7 @@ function scanRoot(input) {
             }
         }
     };
-    visit(rootPath, rootUUID, rootType);
+    await visit(rootPath, rootUUID, rootType);
     const children = new Map();
     for (const entry of entries) {
         if (entry.parentUUID === null)
@@ -1486,7 +1630,7 @@ function scanRoot(input) {
         transferable: true,
     };
 }
-function portablePaths(records) {
+function portablePaths(records, boundaryUUIDs = new Set()) {
     const byUuid = new Map(records.map((record) => [record.uuid, record]));
     const memo = new Map();
     const resolving = new Set();
@@ -1498,7 +1642,7 @@ function portablePaths(records) {
             throw new Error("cloud user-ground graph has a parent cycle");
         resolving.add(record.uuid);
         let path = "";
-        if (record.parentUUID !== null) {
+        if (!boundaryUUIDs.has(record.uuid) && record.parentUUID !== null) {
             const parent = byUuid.get(record.parentUUID);
             if (!parent)
                 throw new Error(`cloud entity ${record.uuid} has no parent`);
@@ -1536,22 +1680,15 @@ function recordRootResolver(records) {
     };
     return rootOf;
 }
-/** Select the records whose root is authored by this machine. A full cloud
- * snapshot also carries untouched cloud-only sibling roots; preserving their
- * rows never means this machine owns or must re-upload their bytes. */
-function recordsWithinRoots(records, rootIds) {
-    const rootOf = recordRootResolver(records);
-    return records.filter((record) => {
-        const root = rootOf(record);
-        return root !== null && rootIds.has(root);
-    });
-}
 function mergeMaterializedRoots(cloudRecords, localRecords) {
     const localRoots = new Set(localRecords
         .filter((record) => record.parentUUID === null)
         .map((record) => record.uuid));
+    const localIds = new Set(localRecords.map((record) => record.uuid));
     const rootOf = recordRootResolver(cloudRecords);
     const preserved = cloudRecords.filter((record) => {
+        if (localIds.has(record.uuid))
+            return false;
         const root = rootOf(record);
         return root === null || !localRoots.has(root);
     });
@@ -1660,7 +1797,7 @@ async function materializeRecords(input) {
         const applied = await applyRepositoryFiles(destination, chain);
         repositories.push({ record, state: applied });
     };
-    const paths = portablePaths(records);
+    const paths = portablePaths(records, input.boundaryUUID ? new Set([input.boundaryUUID]) : new Set());
     const ordered = [...records].sort((left, right) => {
         const leftPath = paths.get(left.uuid);
         const rightPath = paths.get(right.uuid);
@@ -1673,7 +1810,7 @@ async function materializeRecords(input) {
         if (!pathWithin(rootPath, destination)) {
             throw new Error(`cloud entity path escapes its workspace: ${relativePath}`);
         }
-        if (record.parentUUID === null) {
+        if (relativePath === "") {
             if (record.type === "repo.git")
                 await materializeRepository(record, destination);
             else
@@ -1837,7 +1974,11 @@ function installCloudWorkspaceReferences(input) {
 }
 async function installCloudWorkspace(input) {
     const { identity, userRoot, database, cacheDir, bindingDir, resourceId, workspace, reference, references, records, destinationParent, readContent, } = input;
-    const existing = readRows(database).filter((row) => row.rootUUID === workspace.uuid);
+    const allLocalRows = readRows(database);
+    const existingBoundary = allLocalRows.find((row) => row.uuid === workspace.uuid);
+    const existing = existingBoundary
+        ? descendantRows(allLocalRows, workspace.uuid)
+        : [];
     if (existing.length > 0) {
         const root = existing.find((row) => row.uuid === workspace.uuid);
         if (!root || !pathExists(root.absolutePath)) {
@@ -1869,6 +2010,10 @@ async function installCloudWorkspace(input) {
     if (!statSync(parent).isDirectory())
         throw new Error("destination must be a directory");
     const destination = join(parent, workspace.name);
+    const canonicalUserRoot = realpathSync(userRoot);
+    if (pathWithin(canonicalUserRoot, destination) || pathWithin(destination, canonicalUserRoot)) {
+        throw new Error("files add destination must be outside the Amalgm user ground");
+    }
     if (pathExists(destination))
         throw new Error(`workspace destination already exists: ${destination}`);
     ensurePrivateDir(bindingDir);
@@ -1877,7 +2022,12 @@ async function installCloudWorkspace(input) {
         throw new Error(`workspace ${workspace.uuid} already has a local binding`);
     try {
         const materialized = await materializeRecords({
-            records, rootPath: destination, cacheDir, bindingDir, readContent,
+            records,
+            rootPath: destination,
+            boundaryUUID: workspace.uuid,
+            cacheDir,
+            bindingDir,
+            readContent,
         });
         const rows = projectMaterializedGraph(materialized.rows, materialized.repositories.map((repository) => ({
             record: repository.record,