@amalgm/shell 0.1.36 → 0.1.38

package/dist/runtime-command-host.d.ts

@@ -13,4 +13,4 @@ export declare function publishRuntimeCommands(input: RuntimeCommandPublication)
 /** Remove only the discovery document owned by this exact runtime token. */
 export declare function unpublishRuntimeCommands(input: RuntimeCommandPublication): void;
 /** Call the one running Files runtime. The CLI owns no Files effects. */
-export declare function callRuntimeCommand(input: RuntimeCommandAddress, path: "/entities/add" | "/entities/watch", body: Record<string, unknown>): Promise<Record<string, unknown>>;
+export declare function callRuntimeCommand(input: RuntimeCommandAddress, path: "/entities/register" | "/entities/add", body: Record<string, unknown>): Promise<Record<string, unknown>>;

package/dist/runtime-command-host.js

@@ -41,6 +41,7 @@ export async function callRuntimeCommand(input, path, body) {
             headers: {
                 "content-type": "application/json",
                 "x-amalgm-runtime-token": token,
+                "connection": "close",
             },
             body: JSON.stringify(body),
         });

package/dist/runtime-command-host.js.map

@@ -1 +1 @@
-{"version":3,"file":"runtime-command-host.js","sourceRoot":"","sources":["../src/runtime-command-host.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"runtime-command-host.js","sourceRoot":"","sources":["../src/runtime-command-host.ts"],"names":[],"mappings":"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"}

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

@@ -82,6 +82,15 @@ export declare class UserGroundHost {
         readonly register: FilesRegisterPorts;
         readonly add: FilesAddPorts;
     };
+    /** 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. */
+    completeWorkspaceRegistration(workspaceId: string): Promise<{
+        readonly registered: true;
+        readonly entityCount: number;
+        readonly cloudHead: string;
+        readonly watch: WatchCoverageEvidence;
+    }>;
     /** Make every observed filesystem change durable in SQLite, immutable
      * content storage, and the official cloud head before returning. */
     flush(): Promise<void>;

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,65 @@ 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");
+        }
+        try {
+            this.ensureWatchers(identity);
+            assertHealthyWatch(this.watchHost.evidence(), workspaceId);
+        }
+        catch (error) {
+            throw stageError("Watch coverage", error);
+        }
+        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);
+        }
+        let watch;
+        try {
+            this.ensureWatchers(identity);
+            watch = this.watchHost.evidence();
+            assertHealthyWatch(watch, workspaceId);
+        }
+        catch (error) {
+            throw stageError("Watch coverage", error);
+        }
+        const 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() {
@@ -194,9 +254,9 @@ export class UserGroundHost {
         }
     }
     async activateRuntimeTunnel(gatewayPort, runtimeToken) {
-        await this.flush();
-        this.wire.configureRuntime({ gatewayPort, runtimeToken });
-        await this.wire.open();
+        // Files convergence and Watch/Detect own ground currency. Advertising an
+        // HTTP tunnel must never trigger or wait for a second filesystem pass.
+        await this.wire.advertiseRuntime({ gatewayPort, runtimeToken });
     }
     async stopRuntimeTunnel() {
         this.wire.configureRuntime({});
@@ -220,16 +280,16 @@ export class UserGroundHost {
         if (this.rescanTimer)
             clearTimeout(this.rescanTimer);
         this.rescanTimer = null;
-        await this.flushObservedChanges();
+        // Full suspicion already contains every callback that could still be
+        // queued. Retire physical coverage before the final observation so native
+        // backends cannot continuously widen a finite shutdown pass. Changes
+        // after this cutoff belong to the next startup blind interval.
         this.watchHost.close();
-        if (this.rescanTimer)
-            clearTimeout(this.rescanTimer);
-        this.rescanTimer = null;
         await this.flushObservedChanges();
         await this.wire.close();
     }
     userRoot(identity) {
-        return scopedAmalgmDir(this.options.amalgmRoot, identity.userEmail);
+        return resolve(scopedAmalgmDir(this.options.amalgmRoot, identity.userEmail));
     }
     cacheDir(identity) {
         return join(liveMachineStateDir(this.userRoot(identity), identity.deviceId), "content");
@@ -585,14 +645,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 +700,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 +762,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 +811,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 +884,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 +925,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 +1041,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 +1107,6 @@ function createDeclaredHome(input) {
         }
     }
 }
-function fileType(bytes) {
-    return classifyFile({ binary: bytes.includes(0) });
-}
 function slashPath(path) {
     return path.split(sep).join("/");
 }
@@ -1041,8 +1173,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 +1203,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 +1236,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 +1264,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 +1308,7 @@ function scanRoot(input) {
     entries.push({
         uuid: rootUUID,
         type: rootType,
-        parentUUID: null,
+        parentUUID: input.rootParentUUID ?? null,
         name: rootName,
         relativePath: "",
         absolutePath: rootPath,
@@ -1207,7 +1341,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 +1356,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 +1434,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 +1457,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 +1467,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 +1619,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 +1631,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 +1669,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 +1786,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 +1799,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 +1963,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 +1999,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 +2011,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,