@amalgm/shell 0.1.74 → 0.1.76

package/dist/user-ground-host.js

@@ -21,6 +21,7 @@ import { applyRepositoryFiles, captureRepository, inspectRepositoryTransportFile
 import { inspectGitRegistration, sameGitIdentity, } from "./git-registration-host.js";
 import { projectMaterializedGraph } from "./materialized-graph.js";
 import { NodeWatchHost, } from "./watching/index.js";
+import { GroundCoordinator } from "./ground-coordination.js";
 import { WireClient, WireRequestError } from "./wire-client.js";
 const SMALL_CONTENT_UPLOAD_CONCURRENCY = 16;
 const FILE_CONTENT_DOWNLOAD_CONCURRENCY = 4;
@@ -28,6 +29,9 @@ const FILE_BATCH_DOWNLOAD_CONCURRENCY = 2;
 const DETECT_QUIET_MS = 12;
 const DETECT_MAX_DEFERRAL_MS = 75;
 const DETECT_RETRY_MS = 250;
+/** A Detect walk yields the event loop this often so Send, Receive, and
+ * Apply progress during a large reconciliation instead of queueing behind it. */
+const DETECT_WALK_YIELD_ENTRIES = 256;
 const DOWNLOAD_CONTENT_RETRY_ATTEMPTS = 3;
 const APPLY_GROUND_WAIT_TIMEOUT_MS = 15_000;
 const GROUND_ROW_COLUMNS = [
@@ -56,7 +60,10 @@ export class UserGroundHost {
     namedDetect = null;
     coldOperation = false;
     closing = false;
-    groundEffectTail = Promise.resolve();
+    /** Visible-ground effects coordinate by address cone: Detect passes hold
+     * the roots they observe, Apply holds its target addresses, Register and
+     * Add hold the ground they materialize. Unrelated cones never wait. */
+    ground = new GroundCoordinator();
     port;
     constructor(options) {
         this.options = options;
@@ -245,7 +252,7 @@ export class UserGroundHost {
                     status: "started",
                     workspaceId: input.workspace.uuid,
                 });
-                const release = await this.acquireGroundEffect();
+                const release = await this.acquireGroundScope(workspaceAddCones(input.destinationParent, input.workspace, userRoot));
                 this.stage({
                     primitive: "download",
                     stage: "ground-wait",
@@ -326,62 +333,85 @@ export class UserGroundHost {
         return { register, add };
     }
     /** Resume the same host effect used by the SDK command before readiness.
-     * Staged ground has no binding, so recovery cannot race Watch or Detect. */
+     * Staged ground has no binding, so recovery cannot race Watch or Detect.
+     * Each intent is one workspace's durable responsibility, not the machine's:
+     * an intent that cannot be satisfied now is reported and stays durable for
+     * the next start or an explicit re-Add, while readiness proceeds. */
     async resumeWorkspaceAdds(identity) {
-        const database = this.databasePath(identity);
-        const userRoot = this.userRoot(identity);
-        const bindingDir = workspaceBindingDir(userRoot, identity.deviceId);
-        for (const intent of readWorkspaceAddIntents(database)) {
-            const release = await this.acquireGroundEffect();
-            const visibleAcrossBlindInterval = pathExists(intent.destinationPath);
+        for (const intent of readWorkspaceAddIntents(this.databasePath(identity))) {
             try {
-                const selection = workspaceAddSelection(intent);
-                const stagedAcrossBlindInterval = pathExists(intent.stagingPath);
-                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.
-                    deleteRootRows(database, intent.resourceId, intent.workspaceId);
-                }
-                await installCloudWorkspace({
-                    identity,
-                    userRoot,
-                    database,
-                    cacheDir: this.cacheDir(identity),
-                    bindingDir,
-                    resourceId: intent.resourceId,
-                    workspace: selection.workspace,
-                    reference: selection.reference,
-                    references: intent.references,
-                    records: intent.records,
-                    destinationParent: dirname(intent.destinationPath),
-                    cloudHead: intent.cloudHead,
-                    readContent: (artifact) => this.downloadContent(intent.resourceId, this.cacheDir(identity), artifact, 10, { journey: "add", workspaceId: intent.workspaceId }),
-                    onStage: (stage) => this.options.onWorkspaceAddStage?.({
-                        workspaceId: intent.workspaceId,
-                        stage,
-                    }),
-                });
-                this.ensureWatchers(identity, visibleAcrossBlindInterval ? [] : [intent.workspaceId]);
-                assertHealthyWatch(this.watchHost.evidence(), intent.workspaceId);
+                await this.resumeWorkspaceAdd(identity, intent);
             }
-            finally {
-                release();
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                this.stage({
+                    primitive: "download",
+                    stage: "add-resume",
+                    status: "failed",
+                    workspaceId: intent.workspaceId,
+                    measurements: { error: message },
+                });
+                this.options.onApplyError?.(new Error(`workspace Add ${intent.workspaceId} could not resume and stays pending: ${message}`, { cause: error }));
             }
-            if (visibleAcrossBlindInterval) {
-                // Ground that was visible while the runtime was absent may have been
-                // edited after its verified reveal. It is an ordinary startup blind
-                // interval, so Watch must retain complete suspicion and Detect must
-                // settle it before the Add responsibility can be cleared.
-                await this.flushObservedChanges();
+        }
+    }
+    async resumeWorkspaceAdd(identity, intent) {
+        const database = this.databasePath(identity);
+        const userRoot = this.userRoot(identity);
+        const bindingDir = workspaceBindingDir(userRoot, identity.deviceId);
+        const release = await this.acquireGroundScope([
+            intent.destinationPath,
+            intent.stagingPath,
+            userRoot,
+        ]);
+        const visibleAcrossBlindInterval = pathExists(intent.destinationPath);
+        try {
+            const selection = workspaceAddSelection(intent);
+            const stagedAcrossBlindInterval = pathExists(intent.stagingPath);
+            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.
+                deleteRootRows(database, intent.resourceId, intent.workspaceId);
             }
-            await this.options.onWorkspaceAddStage?.({
-                workspaceId: intent.workspaceId,
-                stage: "watching",
+            await installCloudWorkspace({
+                identity,
+                userRoot,
+                database,
+                cacheDir: this.cacheDir(identity),
+                bindingDir,
+                resourceId: intent.resourceId,
+                workspace: selection.workspace,
+                reference: selection.reference,
+                references: intent.references,
+                records: intent.records,
+                destinationParent: dirname(intent.destinationPath),
+                cloudHead: intent.cloudHead,
+                readContent: (artifact) => this.downloadContent(intent.resourceId, this.cacheDir(identity), artifact, 10, { journey: "add", workspaceId: intent.workspaceId }),
+                onStage: (stage) => this.options.onWorkspaceAddStage?.({
+                    workspaceId: intent.workspaceId,
+                    stage,
+                }),
             });
-            deleteWorkspaceAddIntent(database, intent.workspaceId);
+            this.ensureWatchers(identity, visibleAcrossBlindInterval ? [] : [intent.workspaceId]);
+            assertHealthyWatch(this.watchHost.evidence(), intent.workspaceId);
         }
+        finally {
+            release();
+        }
+        if (visibleAcrossBlindInterval) {
+            // Ground that was visible while the runtime was absent may have been
+            // edited after its verified reveal. It is an ordinary startup blind
+            // interval, so Watch must retain complete suspicion and Detect must
+            // settle it before the Add responsibility can be cleared.
+            await this.flushObservedChanges();
+        }
+        await this.options.onWorkspaceAddStage?.({
+            workspaceId: intent.workspaceId,
+            stage: "watching",
+        });
+        deleteWorkspaceAddIntent(database, intent.workspaceId);
     }
     /** Finish the user-visible register journey inside the one persistent Files
      * owner. The declaration remains durable if any later stage fails, and a
@@ -445,9 +475,15 @@ export class UserGroundHost {
             this.stage({
                 primitive: "register", stage: "ground-wait", status: "started", workspaceId,
             });
+            const contentOwner = watch.roots.find((root) => root.rootId === workspaceId)?.contentOwner;
+            if (!contentOwner) {
+                throw new Error(`registered workspace ${workspaceId} has no content coverage owner`);
+            }
             if (this.syncing)
                 await this.syncing;
-            releaseGround = await this.acquireGroundEffect();
+            // Registration reconciles the declared coverage family and core
+            // reference ground; unrelated roots keep detecting and applying.
+            releaseGround = await this.acquireGroundScope([contentOwner, this.userRoot(identity)]);
             this.stage({
                 primitive: "register",
                 stage: "ground-wait",
@@ -455,10 +491,6 @@ export class UserGroundHost {
                 workspaceId,
                 durationMs: performance.now() - groundWaitStarted,
             });
-            const contentOwner = watch.roots.find((root) => root.rootId === workspaceId)?.contentOwner;
-            if (!contentOwner) {
-                throw new Error(`registered workspace ${workspaceId} has no content coverage owner`);
-            }
             const observations = this.watchHost.observations().filter((observation) => observation.directory === this.userRoot(identity)
                 || pathWithin(contentOwner, observation.directory));
             this.watchDirty = false;
@@ -679,17 +711,34 @@ export class UserGroundHost {
             bindingDir: workspaceBindingDir(this.userRoot(identity), identity.deviceId),
             readContent: (artifact) => this.downloadContent(this.cloudState.resourceId, this.cacheDir(identity), artifact, DOWNLOAD_CONTENT_RETRY_ATTEMPTS, { journey: "apply" }),
             captureLocal: async (intent, plan, position) => {
-                // Apply never suppresses Watch. This explicit whole-root suspicion is
-                // the synchronous proof boundary used only when Apply observed a
-                // save racing its reveal and must make that save durable first.
-                this.watchHost.suspectAll();
+                // Apply never suppresses Watch. This explicit named suspicion is the
+                // synchronous proof boundary used only when Apply observed a save
+                // racing its reveal and must make that save durable first. It rings
+                // exactly the addresses Apply compared, so the proof costs one named
+                // Detect lane, not a walk of every root.
+                let addresses = [];
+                try {
+                    addresses = host.applyAddresses(intent, plan);
+                }
+                catch {
+                    // Without an address the whole plan is suspect below.
+                }
+                if (addresses.length === 0)
+                    this.watchHost.suspectAll();
+                for (const address of addresses)
+                    this.watchHost.suspect(address);
                 this.watchDirty = true;
-                await this.syncNow();
+                // A pass already queued may have frozen its observations before this
+                // ring; keep proving until the generation that holds it has settled.
+                const cutoff = this.watchHost.observations();
+                do {
+                    await this.syncNow();
+                } while (!this.closing && !this.watchHost.settled(cutoff));
                 if (!host.store.hasLocalWorkAfter(intent.authorityId, intent.entityId, intent.throughSequence)) {
                     throw new Error(`Apply ${position} capture for ${plan.target.type} ${plan.target.name} (${intent.entityId}) produced no durable local record`);
                 }
             },
-            acquireGround: () => this.acquireGroundEffect(APPLY_GROUND_WAIT_TIMEOUT_MS),
+            acquireGround: (cones) => this.acquireGroundScope(cones, APPLY_GROUND_WAIT_TIMEOUT_MS),
             onStage: (evidence) => {
                 this.options.onApplyStage?.(evidence);
                 this.stage({
@@ -716,10 +765,23 @@ export class UserGroundHost {
             },
             sha256Hex,
             now: Date.now,
-            onBackgroundError: (error) => this.options.onApplyError?.(error),
-            // Path cones and repository territories are wider than one UUID. Until
-            // the host exposes those locks, one serial machine-effect owner is the
-            // only honest concurrency setting.
+            // A failed Apply lane is one entity's outcome; the rail keeps every
+            // other lane moving and retries this one. Surface it as evidence so a
+            // persistently failing entity is visible rather than silent.
+            onBackgroundError: (error) => {
+                this.options.onApplyError?.(error);
+                this.stage({
+                    primitive: "apply",
+                    stage: "lane",
+                    status: "failed",
+                    measurements: { error: error instanceof Error ? error.message : String(error) },
+                });
+            },
+            // The host now coordinates by address cone, so Apply's final guard waits
+            // only for effects on its own addresses. The rail itself still drains
+            // one entity at a time: parallel private preparation multiplies content
+            // fetches per connection and has not been certified against the
+            // gateway's content lane. Raise deliberately, with that proof.
             concurrency: 1,
         });
         this.applyHost = host;
@@ -1311,54 +1373,56 @@ export class UserGroundHost {
             this.scheduleRescan();
         }
     }
-    async acquireGroundEffect(timeoutMs) {
-        let release;
-        const held = new Promise((resolve) => { release = resolve; });
-        const preceding = this.groundEffectTail;
-        this.groundEffectTail = preceding.then(() => held);
-        let released = false;
-        const releaseOnce = () => {
-            if (released)
-                return;
-            released = true;
-            release();
-        };
-        if (timeoutMs === undefined) {
-            await preceding;
-            return releaseOnce;
-        }
-        if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1) {
-            // This queued slot has not become active. Let it pass through as soon as
-            // the preceding owner finishes so invalid input cannot poison the tail.
-            void preceding.then(releaseOnce, releaseOnce);
-            throw new Error("ground-effect wait timeout must be a positive integer");
-        }
-        let timeout = null;
-        try {
-            await Promise.race([
-                preceding,
-                new Promise((_resolve, reject) => {
-                    timeout = setTimeout(() => reject(new Error(`ground-effect wait exceeded ${timeoutMs}ms`)), timeoutMs);
-                }),
-            ]);
-            return releaseOnce;
-        }
-        catch (error) {
-            // The timed-out waiter still owns one FIFO slot. Automatically release
-            // that slot when it reaches the front; otherwise one timeout would block
-            // every later filesystem effect forever.
-            void preceding.then(releaseOnce, releaseOnce);
-            throw error;
-        }
-        finally {
-            if (timeout)
-                clearTimeout(timeout);
-        }
+    acquireGroundScope(cones, timeoutMs) {
+        return this.ground.acquire(cones, timeoutMs === undefined ? {} : { timeoutMs });
     }
     async syncLocalChanges(identity) {
+        if (!this.cloudState)
+            throw new Error("cloud state is unavailable for user-ground Watch");
+        const userRoot = this.userRoot(identity);
+        const repair = registrationRepairGround(this.databasePath(identity), userRoot, identity.deviceId);
+        if (repair.core || repair.emptyRoots.length > 0) {
+            // A durable binding is registration evidence even if the native event
+            // that created it was lost across a crash. Rebuild coverage first, then
+            // express that uncertainty through Watch like every other Detect input.
+            // These are ambiguous recovery facts, so each affected root is wholly
+            // suspect; unrelated roots remain untouched.
+            this.ensureWatchers(identity);
+            if (repair.core)
+                this.watchHost.suspect(userRoot);
+            for (const root of repair.emptyRoots)
+                this.watchHost.suspect(root);
+        }
+        // Detect is per root. A root without pending suspicion has nothing to
+        // prove and never enters a pass: it costs no walk, no notebook plan, no
+        // repository inspection, and no ground coordination. Only rung roots are
+        // observed, and each rung root is proved on its own lane before any root
+        // widens to reconciliation. Rings after this snapshot own the next pass.
+        const observations = this.watchHost.observations();
+        const pending = observations.filter(({ suspicion }) => suspicion.paths === null || suspicion.paths.length > 0);
+        // An idle root's generation is already proved; settling it keeps every
+        // root's settled generation current without any filesystem work.
+        this.watchHost.settle(observations.filter((observation) => !pending.includes(observation)));
+        if (pending.length === 0) {
+            this.stage({
+                primitive: "detect",
+                stage: "pass",
+                status: "completed",
+                durationMs: 0,
+                measurements: { lane: "idle", roots: 0, records: 0 },
+            });
+            return;
+        }
+        const cones = new Set(pending.map((observation) => observation.directory));
+        const coreScan = cones.has(userRoot);
         const waitStarted = performance.now();
-        this.stage({ primitive: "detect", stage: "ground-wait", status: "started" });
-        const release = await this.acquireGroundEffect();
+        this.stage({
+            primitive: "detect",
+            stage: "ground-wait",
+            status: "started",
+            measurements: { roots: pending.length },
+        });
+        const release = await this.acquireGroundScope([...cones]);
         this.stage({
             primitive: "detect",
             stage: "ground-wait",
@@ -1366,39 +1430,50 @@ export class UserGroundHost {
             durationMs: performance.now() - waitStarted,
         });
         try {
-            await this.syncLocalChangesUnlocked(identity);
+            await this.syncLocalChangesUnlocked(identity, pending, coreScan);
         }
         finally {
             release();
         }
     }
-    async syncLocalChangesUnlocked(identity) {
+    async syncLocalChangesUnlocked(identity, pending, coreScan) {
         if (!this.cloudState)
             throw new Error("cloud state is unavailable for user-ground Watch");
-        const observations = this.watchHost.observations();
         const passStarted = performance.now();
         this.stage({
             primitive: "detect",
             stage: "pass",
             status: "started",
             measurements: {
-                roots: observations.length,
-                completeRoots: observations.filter(({ suspicion }) => suspicion.paths === null).length,
-                namedPaths: observations.reduce((count, { suspicion }) => count + (suspicion.paths?.length ?? 0), 0),
+                roots: pending.length,
+                completeRoots: pending.filter(({ suspicion }) => suspicion.paths === null).length,
+                namedPaths: pending.reduce((count, { suspicion }) => count + (suspicion.paths?.length ?? 0), 0),
             },
         });
-        let widenedRoots = new Set();
-        if (this.namedDetect) {
+        const reconcileSuspicions = new Map();
+        const reconcileObservations = [];
+        let namedRoots = 0;
+        let namedRecords = 0;
+        let unsettled = false;
+        for (const observation of pending) {
+            if (observation.suspicion.paths === null || !this.namedDetect) {
+                reconcileSuspicions.set(observation.directory, observation.suspicion);
+                reconcileObservations.push(observation);
+                continue;
+            }
             // The named lane is an optimization over the same settled evidence.
-            // Any proof failure occurs before its SQLite transaction and widens to
-            // reconciliation; it must never poison a Watch generation in a timer
-            // rejection that only another filesystem event can revive.
-            const named = await this.namedDetect.detect(observations).catch(() => null);
+            // Any proof failure occurs before its SQLite transaction and widens
+            // only this root to reconciliation; it must never poison a Watch
+            // generation in a timer rejection that only another event can revive.
+            const named = await this.namedDetect.detect([observation]).catch(() => null);
+            if (named?.unsettled) {
+                unsettled = true;
+                continue;
+            }
             if (named?.handled) {
                 for (const evidence of named.evidence) {
-                    const observation = observations.find((candidate) => candidate.directory === evidence.directory);
                     this.reportDetectScan({
-                        rootId: observation?.rootId ?? evidence.directory,
+                        rootId: observation.rootId,
                         directory: evidence.directory,
                         scope: "paths",
                         entries: evidence.metadataReads,
@@ -1411,24 +1486,34 @@ export class UserGroundHost {
                         records: evidence.records,
                         recordBytes: evidence.recordBytes,
                     });
+                    namedRecords += evidence.records;
                 }
-                this.watchHost.settle(observations);
-                this.applyRail?.localStateChanged();
-                this.recordRail?.localRecordsAvailable();
-                this.stage({
-                    primitive: "detect",
-                    stage: "pass",
-                    status: "completed",
-                    durationMs: performance.now() - passStarted,
-                    measurements: {
-                        lane: "named",
-                        roots: named.evidence.length,
-                        records: named.evidence.reduce((count, evidence) => count + evidence.records, 0),
-                    },
-                });
-                return;
+                namedRoots += 1;
+                // This root's truth is durable; its generation settles now so a later
+                // failure in another root's reconciliation cannot make it re-prove.
+                this.watchHost.settle([observation]);
+                continue;
             }
-            widenedRoots = new Set(named?.widenedRoots ?? []);
+            const widened = named?.widenedRoots?.includes(observation.directory) === true;
+            reconcileSuspicions.set(observation.directory, widened ? { ...observation.suspicion, paths: null } : observation.suspicion);
+            reconcileObservations.push(observation);
+        }
+        if (namedRoots > 0) {
+            this.applyRail?.localStateChanged();
+            this.recordRail?.localRecordsAvailable();
+        }
+        if (reconcileObservations.length === 0) {
+            this.stage({
+                primitive: "detect",
+                stage: "pass",
+                status: "completed",
+                durationMs: performance.now() - passStarted,
+                measurements: { lane: "named", roots: namedRoots, records: namedRecords },
+            });
+            if (unsettled) {
+                throw pipelineStageError("detection", new Error("repository control operation is unsettled"));
+            }
+            return;
         }
         let detection;
         let acceptedMaterializedRows;
@@ -1442,9 +1527,8 @@ export class UserGroundHost {
                 database: this.databasePath(identity),
                 cacheDir: this.cacheDir(identity),
                 onScan: (evidence) => this.reportDetectScan(evidence),
-                suspicions: new Map(observations.map((observation) => [observation.directory, widenedRoots.has(observation.directory)
-                        ? { ...observation.suspicion, paths: null }
-                        : observation.suspicion])),
+                suspicions: reconcileSuspicions,
+                coreScan,
             });
             detection = scanned.detection;
             acceptedMaterializedRows = scanned.acceptedMaterializedRows;
@@ -1501,7 +1585,7 @@ export class UserGroundHost {
             }
         }
         this.namedDetect?.refreshEnrollmentPolicy();
-        this.watchHost.settle(observations);
+        this.watchHost.settle(reconcileObservations);
         this.applyRail?.localStateChanged();
         this.recordRail?.localRecordsAvailable();
         this.stage({
@@ -1509,8 +1593,16 @@ export class UserGroundHost {
             stage: "pass",
             status: "completed",
             durationMs: performance.now() - passStarted,
-            measurements: { lane: "reconciliation", records: detectedRecords.length },
+            measurements: {
+                lane: "reconciliation",
+                roots: reconcileObservations.length,
+                namedRoots,
+                records: detectedRecords.length + namedRecords,
+            },
         });
+        if (unsettled) {
+            throw pipelineStageError("detection", new Error("repository control operation is unsettled"));
+        }
     }
     async publishPendingSnapshotsBeforeLookup(identity, resourceId) {
         const pending = readSnapshotPublications(this.databasePath(identity));
@@ -2015,6 +2107,41 @@ function countDescendantRows(file, rootUUID) {
         database.close();
     }
 }
+/** Recovery facts created before Watch could prove registration: a binding
+ * whose portable reference is absent from the notebook, or a bound root that
+ * has never produced a local entity row. They pull only those exact roots
+ * into the next Detect pass. */
+function registrationRepairGround(file, userRoot, deviceId) {
+    const bindings = materializedWorkspaceBindings(workspaceBindingDir(userRoot, deviceId));
+    if (bindings.length === 0)
+        return { core: false, emptyRoots: [] };
+    if (!existsSync(file)) {
+        return { core: true, emptyRoots: bindings.map(({ directory }) => directory) };
+    }
+    const core = readGroundRootAtPath(file, "detection_notebook", userRoot);
+    if (!core) {
+        return { core: true, emptyRoots: bindings.map(({ directory }) => directory) };
+    }
+    const database = initializeDatabase(file);
+    try {
+        const referenced = new Set(database.prepare(`
+      SELECT payload_version AS payloadVersion FROM detection_notebook
+       WHERE root_uuid = ? AND type = 'reference' AND status = 'active'
+         AND payload_version IS NOT NULL
+    `).all(core.uuid).map((row) => row.payloadVersion));
+        const hasRows = database.prepare(`
+      SELECT 1 AS present FROM entities WHERE root_uuid = ? LIMIT 1
+    `);
+        return {
+            core: bindings.some(({ workspaceId }) => !referenced.has(workspaceId)),
+            emptyRoots: bindings.filter(({ workspaceId }) => !hasRows.get(workspaceId))
+                .map(({ directory }) => directory),
+        };
+    }
+    finally {
+        database.close();
+    }
+}
 function readGroundUUIDs(file, table, rootUUIDs) {
     if (!existsSync(file))
         return new Set();
@@ -2036,6 +2163,20 @@ function readGroundUUIDs(file, table, rootUUIDs) {
         database.close();
     }
 }
+/** The ground an Add materialization touches: its destination, its sibling
+ * staging directory, and core ground where the binding and reference live.
+ * An unresolvable parent still names itself; the install reports the error. */
+function workspaceAddCones(destinationParent, workspace, userRoot) {
+    let parent = resolve(destinationParent);
+    try {
+        parent = realpathSync(parent);
+    }
+    catch {
+        // Reported by installCloudWorkspace with its exact error.
+    }
+    const destination = join(parent, workspace.name);
+    return [destination, workspaceAddStagingPath(destination, workspace.uuid), userRoot];
+}
 function workspaceAddStagingPath(destinationPath, workspaceId) {
     return join(dirname(destinationPath), `.amalgm-${workspaceId}.adding`);
 }
@@ -2569,6 +2710,11 @@ function createDeclaredHome(input) {
         }
     }
 }
+/** One macrotask turn: pending I/O, timers, and wire frames run before the
+ * caller resumes. */
+function yieldEventLoop() {
+    return new Promise((resolve) => setImmediate(resolve));
+}
 function slashPath(path) {
     return path.split(sep).join("/");
 }
@@ -2629,7 +2775,7 @@ function materializedWorkspaceBindings(bindingDir) {
     return bindings.sort((left, right) => left.workspaceId.localeCompare(right.workspaceId));
 }
 async function reconcileGround(input) {
-    const { identity, userRoot, database, cacheDir, suspicions, registrationWorkspaceId, onScan, } = input;
+    const { identity, userRoot, database, cacheDir, suspicions, coreScan, registrationWorkspaceId, onScan, } = input;
     const resourceId = privateEntityResourceId(identity.userId, sha256Hex);
     const bindingDir = workspaceBindingDir(userRoot, identity.deviceId);
     const boundRootEntries = materializedWorkspaceBindings(bindingDir);
@@ -2759,30 +2905,40 @@ async function reconcileGround(input) {
         });
         // Each root commits its local projection before Detect yields. Native
         // callbacks can therefore preserve new suspicion between large roots.
-        await new Promise((resolve) => setImmediate(resolve));
+        await yieldEventLoop();
         return result;
     };
-    await scan({
-        identity,
-        resourceId,
-        rootUUID: coreUUID,
-        rootName: identity.userEmail,
-        rootPath: userRoot,
-        rootType: "workspace",
-        database,
-        cacheDir,
-        policy,
-        bindingDir,
-        suspects: missingPortableReference && coreSuspicion !== null
-            ? [...new Set([...coreSuspicion, "workspaces"])]
-            : coreSuspicion,
-        existingRows: existing.filter((row) => row.rootUUID === coreUUID),
-        suspicion: observationFor(userRoot),
-    });
+    // A Watch pass names exactly the roots it observed. A root outside that
+    // observation has nothing to prove and is not scanned, planned, or
+    // inspected; its rows stay as they are. Only two facts can still pull an
+    // unobserved root in: core ground missing a portable reference for a
+    // binding, and a bound root that has never produced a row.
+    const observed = (root) => !suspicions || suspicions.has(root);
+    if (observed(userRoot) || (missingPortableReference && coreScan !== false)) {
+        await scan({
+            identity,
+            resourceId,
+            rootUUID: coreUUID,
+            rootName: identity.userEmail,
+            rootPath: userRoot,
+            rootType: "workspace",
+            database,
+            cacheDir,
+            policy,
+            bindingDir,
+            suspects: missingPortableReference && coreSuspicion !== null
+                ? [...new Set([...coreSuspicion, "workspaces"])]
+                : coreSuspicion,
+            existingRows: existing.filter((row) => row.rootUUID === coreUUID),
+            suspicion: observationFor(userRoot),
+        });
+    }
     const physicalRoots = registrationOwner ? [registrationOwner] : outerBoundRoots;
     for (const { workspaceId, directory: rootPath } of physicalRoots) {
         const existingRoot = existingByUuid.get(workspaceId);
         const existingWorkspaceRows = existingByOutermostRoot.get(workspaceId) || [];
+        if (!observed(rootPath) && existingWorkspaceRows.length > 0)
+            continue;
         const registeredPath = registrationBoundary
             && registrationOwner?.workspaceId === workspaceId
             && registrationBoundary.workspaceId !== workspaceId
@@ -2823,14 +2979,21 @@ async function reconcileGround(input) {
 }
 async function reconcileRoot(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.flatMap((row) => {
+    // Prior rows reach this scan from every binding this root encloses. A row's
+    // stored relativePath is relative to the root that last committed it, which
+    // is a different frame when an enclosing boundary was just registered
+    // (child/README.md is stored as "README.md" under the child root). Address
+    // every prior row in this scan's frame before anything compares it with an
+    // observed entry; absolutePath is the only coordinate both frames share.
+    const existingRows = (input.existingRows
+        ?? readRows(database).filter((row) => row.resourceId === resourceId && row.rootUUID === rootUUID))
+        .flatMap((row) => {
         if (!pathWithin(rootPath, row.absolutePath))
             return [];
-        const local = slashPath(relative(rootPath, row.absolutePath));
-        return [[local, row]];
-    }));
+        const relativePath = slashPath(relative(rootPath, row.absolutePath));
+        return [relativePath === row.relativePath ? row : { ...row, relativePath }];
+    });
+    const existingByPath = new Map(existingRows.map((row) => [row.relativePath, row]));
     const registeredBoundaries = input.registeredBoundaries ?? new Map();
     if (suspects !== null
         && suspects.length === 0
@@ -2970,6 +3133,7 @@ async function reconcileRoot(input) {
         }
         return [...new Set(paths)].sort();
     };
+    let visitedEntries = 0;
     const visit = async (directory, parentUUID, parentType, base = "", activeRepository = parentType === "repo.git"
         ? {
             root: directory,
@@ -2996,6 +3160,11 @@ async function reconcileRoot(input) {
             const absolutePath = join(directory, child.name);
             const stats = lstatSync(absolutePath);
             evidence && (evidence.entries += 1);
+            // The walk is synchronous metadata work. Yield periodically so the
+            // wire, Receive, and Apply keep running while a large root is proved.
+            // A Watch ring during the yield remains a later generation.
+            if (++visitedEntries % DETECT_WALK_YIELD_ENTRIES === 0)
+                await yieldEventLoop();
             const existing = existingByPath.get(relativePath);
             const registeredBoundaryId = stats.isDirectory()
                 ? registeredBoundaries.get(resolve(absolutePath))
@@ -3994,6 +4163,19 @@ async function installCloudWorkspace(input) {
             alreadyMaterialized: pending === null,
         };
     }
+    // One machine materializes each UUID in exactly one place. The selected
+    // closure may enclose a boundary this machine already added elsewhere; a
+    // fresh install would re-root those rows under the new destination while
+    // the old binding stayed bound and watched over ground with no rows, and
+    // the next Detect pass there would mint a second identity for every file.
+    const selectedUUIDs = new Set(records.map((record) => record.uuid));
+    const enclosedElsewhere = allLocalRows.filter((row) => row.uuid !== workspace.uuid && selectedUUIDs.has(row.uuid));
+    if (enclosedElsewhere.length > 0) {
+        const roots = [...new Set(enclosedElsewhere.map((row) => row.rootUUID))]
+            .map((rootUUID) => allLocalRows.find((row) => row.uuid === rootUUID)?.absolutePath ?? rootUUID);
+        throw new Error(`files add: workspace ${workspace.uuid} encloses ${enclosedElsewhere.length} entities already `
+            + `materialized on this machine under ${roots.join(", ")}; remove that materialization first`);
+    }
     const parent = realpathSync(resolve(destinationParent));
     if (!statSync(parent).isDirectory())
         throw new Error("destination must be a directory");