@amalgm/shell 0.1.74 → 0.1.75

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",
@@ -332,7 +339,11 @@ export class UserGroundHost {
         const userRoot = this.userRoot(identity);
         const bindingDir = workspaceBindingDir(userRoot, identity.deviceId);
         for (const intent of readWorkspaceAddIntents(database)) {
-            const release = await this.acquireGroundEffect();
+            const release = await this.acquireGroundScope([
+                intent.destinationPath,
+                intent.stagingPath,
+                userRoot,
+            ]);
             const visibleAcrossBlindInterval = pathExists(intent.destinationPath);
             try {
                 const selection = workspaceAddSelection(intent);
@@ -445,9 +456,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 +472,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 +692,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({
@@ -717,9 +747,11 @@ 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.
+            // 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 +1343,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 +1400,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 +1456,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 +1497,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 +1555,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 +1563,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 +2077,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 +2133,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 +2680,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 +2745,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 +2875,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
@@ -2970,6 +3096,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 +3123,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))