@amalgm/shell 0.1.40 → 0.1.42

package/dist/user-ground-host.js

@@ -1,14 +1,15 @@
 import { createHash, randomUUID } from "node:crypto";
-import { existsSync, lstatSync, realpathSync, readFileSync, readdirSync, readlinkSync, rmSync, statSync, symlinkSync, writeFileSync, } from "node:fs";
+import { existsSync, lstatSync, realpathSync, readFileSync, readdirSync, readlinkSync, renameSync, rmSync, statSync, symlinkSync, writeFileSync, } from "node:fs";
 import { open } from "node:fs/promises";
-import { basename, dirname, extname, join, relative, resolve, sep } from "node:path";
+import { basename, dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { buildUserHomeManifest, buildUserManifest, liveMachineStateDir, scopedAmalgmDir, shippedUserHomeDeclaration, } from "@amalgm/core/identity";
 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, 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 { planGroundDetection, reconcileGroundUUIDs, } from "./detection-host.js";
+import { WORKSPACE_UUID as UUID, createFilesRegisterPorts, ensureWorkspaceBinding, ensureWorkspaceReference, pathExists, pathWithin, referenceWorkspaceId, selectKnownRegistrationId, workspaceBindingDir, } from "./files-register-host.js";
 import { applyRepositoryFiles, captureRepository, inspectRepositoryTransportFile, hasGitMarker, } from "./git-repository-host.js";
 import { inspectGitRegistration, } from "./git-registration-host.js";
 import { projectMaterializedGraph } from "./materialized-graph.js";
@@ -21,6 +22,12 @@ const PORTABLE_FIELDS = [
 const SMALL_CONTENT_UPLOAD_CONCURRENCY = 16;
 const FILE_CONTENT_DOWNLOAD_CONCURRENCY = 4;
 const FILE_BATCH_DOWNLOAD_CONCURRENCY = 2;
+const GROUND_ROW_COLUMNS = [
+    "uuid", "resource_id", "root_uuid", "type", "parent_uuid", "name", "status", "version",
+    "payload_version", "transport_version", "relative_path", "absolute_path", "device_number",
+    "inode", "byte_size", "modified_time_ms", "changed_time_ms", "filesystem_mode",
+    "content_verified_at_ms",
+].join(", ");
 /** The production Files port injected into Core. Portable identity remains in
  * Live; this class owns only Node filesystem, SQLite, Watch, and wire effects. */
 export class UserGroundHost {
@@ -57,6 +64,11 @@ export class UserGroundHost {
                     cloud: this.cloudPort(this.activeIdentity),
                     local,
                 });
+                await this.resumeWorkspaceAdds(this.activeIdentity);
+                const watchHealth = this.watchHost.health();
+                if (watchHealth.state !== "healthy") {
+                    throw new Error(`Watch coverage is degraded: ${watchHealth.reason ?? "unknown failure"}`);
+                }
                 const evidence = {
                     userId: result.userId,
                     userEmail: result.userEmail,
@@ -64,9 +76,9 @@ export class UserGroundHost {
                     localRoot: result.localRoot,
                     cloudHead: result.cloudHead,
                     mode: result.mode,
-                    entityCount: result.entityCount,
-                    watcherRoots: result.watcherRoots,
-                    watching: result.watching,
+                    entityCount: readRows(this.databasePath(this.activeIdentity)).length,
+                    watcherRoots: watchHealth.contentHandles,
+                    watching: true,
                 };
                 this.converged = true;
                 return evidence;
@@ -140,18 +152,80 @@ export class UserGroundHost {
                     references: input.references,
                     records: input.records,
                     destinationParent: input.destinationParent,
+                    cloudHead: input.cloudHead,
                     readContent: (artifact) => this.downloadContent(privateEntityResourceId(identity.userId, sha256Hex), this.cacheDir(identity), artifact),
+                    onStage: (stage) => this.options.onWorkspaceAddStage?.({
+                        workspaceId: input.workspace.uuid,
+                        stage,
+                    }),
                 });
-                this.scheduleRescan();
                 return installed;
             },
             coverWorkspace: async ({ workspaceId, baseline }) => {
-                const health = this.ensureWatchers(identity, baseline === "authoritative-install" ? [workspaceId] : []);
+                const pending = readWorkspaceAddIntent(this.databasePath(identity), workspaceId);
+                const health = this.ensureWatchers(identity, pending || baseline === "authoritative-install" ? [workspaceId] : []);
+                assertHealthyWatch(this.watchHost.evidence(), workspaceId);
+                if (pending) {
+                    await this.options.onWorkspaceAddStage?.({ workspaceId, stage: "watching" });
+                    deleteWorkspaceAddIntent(this.databasePath(identity), workspaceId);
+                }
                 return { active: true, roots: health.contentHandles };
             },
         };
         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. */
+    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 selection = workspaceAddSelection(intent);
+            const visibleAcrossBlindInterval = pathExists(intent.destinationPath);
+            const stagedAcrossBlindInterval = pathExists(intent.stagingPath);
+            if (stagedAcrossBlindInterval && readRows(database).some((row) => row.resourceId === intent.resourceId && row.rootUUID === 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),
+                onStage: (stage) => this.options.onWorkspaceAddStage?.({
+                    workspaceId: intent.workspaceId,
+                    stage,
+                }),
+            });
+            this.ensureWatchers(identity, visibleAcrossBlindInterval ? [] : [intent.workspaceId]);
+            assertHealthyWatch(this.watchHost.evidence(), intent.workspaceId);
+            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
      * retry reuses its UUID through filesCommandPorts().register. */
@@ -223,21 +297,21 @@ export class UserGroundHost {
             watch,
         };
     }
-    /** Make every observed filesystem change durable in SQLite, immutable
-     * content storage, and the official cloud head before returning. */
+    /** Prove one finite observation boundary in SQLite, immutable content
+     * storage, and the official cloud head. Rings received during that proof
+     * remain pending and already own their next debounced Detect pass. */
     async flush() {
         if (!this.converged || !this.activeIdentity || !this.cloudState)
             return;
         const identity = this.activeIdentity;
         this.watchHost.suspectAll();
-        this.watchDirty = true;
+        // The complete suspicion above contains everything known at this cutoff.
+        // A native callback after this assignment sets watchDirty again and must
+        // remain a later generation; flush never waits for global Watch silence.
+        this.watchDirty = false;
         await this.syncNow();
         if (!this.closing)
             this.ensureWatchers(identity);
-        await this.flushObservedChanges();
-        if (!this.closing)
-            this.ensureWatchers(identity);
-        await this.flushObservedChanges();
     }
     async syncNow() {
         if (!this.activeIdentity)
@@ -250,20 +324,14 @@ export class UserGroundHost {
         await this.syncing;
     }
     async flushObservedChanges() {
-        while (true) {
-            const dirty = this.watchDirty
-                || this.watchHost.hasPending;
-            this.watchDirty = false;
-            if (dirty) {
-                await this.syncNow();
-                continue;
-            }
-            if (this.syncing) {
-                await this.syncing;
-                continue;
-            }
+        const dirty = this.watchDirty || this.watchHost.hasPending;
+        this.watchDirty = false;
+        if (dirty) {
+            await this.syncNow();
             return;
         }
+        if (this.syncing)
+            await this.syncing;
     }
     async activateRuntimeTunnel(gatewayPort, runtimeToken) {
         // Files convergence and Watch/Detect own ground currency. Advertising an
@@ -607,22 +675,6 @@ export class UserGroundHost {
                 materialized: true,
             });
         }
-        for (const row of readRows(this.databasePath(identity))) {
-            if (row.parentUUID !== null || row.absolutePath === root)
-                continue;
-            const directory = directoryExists(row.absolutePath)
-                ? realpathSync(row.absolutePath)
-                : resolve(row.absolutePath);
-            const prior = wanted.get(directory);
-            if (prior && prior.rootId !== row.rootUUID) {
-                throw new Error(`two logical roots claim the same Watch ground: ${directory}`);
-            }
-            wanted.set(directory, {
-                rootId: row.rootUUID,
-                directory,
-                materialized: directoryExists(directory),
-            });
-        }
         const health = this.watchHost.reconcile([...wanted.values()], {
             authoritativeBaselineRootIds,
         });
@@ -658,37 +710,62 @@ export class UserGroundHost {
             throw new Error("cloud state is unavailable for user-ground Watch");
         const observations = this.watchHost.observations();
         let localRecords;
+        let detection;
+        let acceptedNotebookRows;
+        let notebookRemovals;
         try {
-            localRecords = await scanAndRegister({
+            const scanned = 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])),
+                suspicions: new Map(observations.map((observation) => [observation.directory, observation.suspicion])),
             });
+            localRecords = [...scanned.records];
+            detection = scanned.detection;
+            acceptedNotebookRows = scanned.acceptedNotebookRows;
+            notebookRemovals = scanned.notebookRemovals;
         }
         catch (error) {
             throw pipelineStageError("entity registration", error);
         }
+        const retry = detection.find((plan) => plan.kind === "retry");
+        if (retry?.kind === "retry") {
+            throw pipelineStageError("detection", new Error(retry.reasons.join("; ")));
+        }
+        const detectedRecords = detection.flatMap((plan) => plan.kind === "ready"
+            ? plan.proposals.map((proposal) => ({ mutationId: randomUUID(), proposal }))
+            : []);
+        // The notebook is durable identity evidence, not evidence scoped to only
+        // this Watch generation. A later no-op flush must not erase ground that an
+        // earlier observation proved missing without lifecycle authority.
+        localRecords = recordsRetainingMissingEvidence(localRecords, readDetectionNotebook(this.databasePath(identity))
+            .filter((row) => !notebookRemovals.includes(row.uuid))
+            .map(portableRecord));
         const snapshot = snapshotFromRecords(travelingRecords(mergeMaterializedRoots(state.records, localRecords)));
         const checksum = sha256Hex(stableJson(snapshot));
         if (checksum === state.checksum) {
+            commitDetectedState(this.databasePath(identity), {
+                acceptedNotebookRows,
+                notebookRemovals,
+            });
             this.watchHost.settle(observations);
             return;
         }
-        const database = initializeDatabase(this.databasePath(identity));
-        try {
-            database.prepare(`
-        INSERT INTO cloud_outbox(
-          mutation_id, resource_id, authority_epoch, base_version,
-          snapshot_checksum, snapshot_json, created_at
-        ) VALUES (?, ?, ?, ?, ?, ?, ?)
-      `).run(randomUUID(), state.resourceId, state.authorityEpoch, state.headVersion, checksum, stableJson(snapshot), new Date().toISOString());
-        }
-        finally {
-            database.close();
-        }
+        commitDetectedState(this.databasePath(identity), {
+            acceptedNotebookRows,
+            notebookRemovals,
+            outbox: {
+                mutationId: randomUUID(),
+                resourceId: state.resourceId,
+                authorityEpoch: state.authorityEpoch,
+                baseVersion: state.headVersion,
+                snapshotChecksum: checksum,
+                snapshotJson: stableJson(snapshot),
+                detectedRecordsJson: stableJson(detectedRecords),
+            },
+        });
         await this.drainOutbox(identity);
         this.watchHost.settle(observations);
     }
@@ -886,6 +963,27 @@ function initializeDatabase(file) {
       content_verified_at_ms REAL,
       UNIQUE(resource_id, root_uuid, relative_path)
     );
+    CREATE TABLE IF NOT EXISTS detection_notebook (
+      uuid TEXT PRIMARY KEY,
+      resource_id TEXT NOT NULL,
+      root_uuid TEXT NOT NULL,
+      type TEXT NOT NULL,
+      parent_uuid TEXT,
+      name TEXT NOT NULL,
+      status TEXT NOT NULL,
+      version TEXT NOT NULL,
+      payload_version TEXT,
+      transport_version TEXT,
+      relative_path TEXT NOT NULL,
+      absolute_path TEXT NOT NULL,
+      device_number INTEGER NOT NULL,
+      inode INTEGER NOT NULL,
+      byte_size INTEGER,
+      modified_time_ms REAL,
+      changed_time_ms REAL,
+      filesystem_mode INTEGER,
+      content_verified_at_ms REAL
+    );
     CREATE TABLE IF NOT EXISTS cloud_outbox (
       sequence INTEGER PRIMARY KEY AUTOINCREMENT,
       mutation_id TEXT NOT NULL UNIQUE,
@@ -894,12 +992,22 @@ function initializeDatabase(file) {
       base_version INTEGER NOT NULL,
       snapshot_checksum TEXT NOT NULL,
       snapshot_json TEXT NOT NULL,
+      detected_records_json TEXT NOT NULL DEFAULT '[]',
       created_at TEXT NOT NULL
     );
+    CREATE TABLE IF NOT EXISTS workspace_add_intents (
+      workspace_uuid TEXT PRIMARY KEY,
+      destination_path TEXT NOT NULL UNIQUE,
+      intent_json 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);
+    CREATE INDEX IF NOT EXISTS detection_notebook_by_root_path
+      ON detection_notebook(resource_id, root_uuid, relative_path);
+    CREATE INDEX IF NOT EXISTS detection_notebook_by_physical_identity
+      ON detection_notebook(device_number, inode);
   `);
     const currentEntityColumns = new Set(database.prepare("PRAGMA table_info(entities)").all()
         .map(({ name }) => name));
@@ -914,9 +1022,20 @@ function initializeDatabase(file) {
         if (!currentEntityColumns.has(name))
             database.exec(`ALTER TABLE entities ADD COLUMN ${name} ${type}`);
     }
+    const outboxColumns = new Set(database.prepare("PRAGMA table_info(cloud_outbox)").all()
+        .map(({ name }) => name));
+    if (!outboxColumns.has("detected_records_json")) {
+        database.exec("ALTER TABLE cloud_outbox ADD COLUMN detected_records_json TEXT NOT NULL DEFAULT '[]'");
+    }
+    const notebookCount = database.prepare("SELECT COUNT(*) AS count FROM detection_notebook").get().count;
+    if (notebookCount === 0)
+        database.exec(`
+    INSERT INTO detection_notebook(${GROUND_ROW_COLUMNS})
+    SELECT ${GROUND_ROW_COLUMNS} FROM entities
+  `);
     return database;
 }
-function readRows(file) {
+function readGroundRows(file, table) {
     if (!existsSync(file))
         return [];
     const database = initializeDatabase(file);
@@ -930,13 +1049,125 @@ function readRows(file) {
              byte_size AS byteSize, modified_time_ms AS modifiedTimeMs,
              changed_time_ms AS changedTimeMs, filesystem_mode AS filesystemMode,
              content_verified_at_ms AS contentVerifiedAtMs
-        FROM entities ORDER BY uuid
+        FROM ${table} ORDER BY uuid
     `).all();
     }
     finally {
         database.close();
     }
 }
+function readRows(file) {
+    return readGroundRows(file, "entities");
+}
+function readDetectionNotebook(file) {
+    return readGroundRows(file, "detection_notebook");
+}
+function workspaceAddStagingPath(destinationPath, workspaceId) {
+    return join(dirname(destinationPath), `.amalgm-${workspaceId}.adding`);
+}
+function workspaceAddSelection(intent) {
+    const workspace = intent.records.find((record) => record.uuid === intent.workspaceId);
+    if (!workspace || !["workspace", "folder", "repo.git"].includes(workspace.type)) {
+        throw new Error(`workspace Add intent ${intent.workspaceId} has no materialization boundary`);
+    }
+    const references = intent.references.filter((record) => record.type === "reference"
+        && record.status === "active"
+        && record.payloadVersion === intent.workspaceId);
+    if (references.length !== 1) {
+        throw new Error(`workspace Add intent ${intent.workspaceId} has no unique durable reference`);
+    }
+    return { workspace, reference: references[0] };
+}
+function parseWorkspaceAddIntent(json) {
+    const value = JSON.parse(json);
+    const workspaceId = String(value.workspaceId || "").toLowerCase();
+    const resourceId = String(value.resourceId || "");
+    const cloudHead = String(value.cloudHead || "");
+    const destinationPath = String(value.destinationPath || "");
+    const stagingPath = String(value.stagingPath || "");
+    if (!UUID.test(workspaceId) || !resourceId || !/^[0-9a-f]{64}$/i.test(cloudHead)) {
+        throw new Error("workspace Add intent identity is invalid");
+    }
+    if (!isAbsolute(destinationPath)
+        || stagingPath !== workspaceAddStagingPath(destinationPath, workspaceId)) {
+        throw new Error(`workspace Add intent ${workspaceId} has invalid placement`);
+    }
+    const intent = {
+        workspaceId,
+        resourceId,
+        cloudHead: cloudHead.toLowerCase(),
+        destinationPath,
+        stagingPath,
+        records: snapshotFromRecords(Array.isArray(value.records) ? value.records : []).records,
+        references: snapshotFromRecords(Array.isArray(value.references) ? value.references : []).records,
+    };
+    const { workspace } = workspaceAddSelection(intent);
+    if (basename(destinationPath) !== workspace.name) {
+        throw new Error(`workspace Add intent ${workspaceId} destination differs from its graph`);
+    }
+    return intent;
+}
+function readWorkspaceAddIntent(file, workspaceId) {
+    if (!existsSync(file))
+        return null;
+    const database = initializeDatabase(file);
+    try {
+        const row = database.prepare("SELECT intent_json AS intentJson FROM workspace_add_intents WHERE workspace_uuid = ?").get(workspaceId);
+        return row ? parseWorkspaceAddIntent(row.intentJson) : null;
+    }
+    finally {
+        database.close();
+    }
+}
+function readWorkspaceAddIntents(file) {
+    if (!existsSync(file))
+        return [];
+    const database = initializeDatabase(file);
+    try {
+        return database.prepare("SELECT intent_json AS intentJson FROM workspace_add_intents ORDER BY workspace_uuid").all().map(({ intentJson }) => parseWorkspaceAddIntent(intentJson));
+    }
+    finally {
+        database.close();
+    }
+}
+function persistWorkspaceAddIntent(file, proposed) {
+    const database = initializeDatabase(file);
+    try {
+        let inserted;
+        try {
+            inserted = database.prepare(`
+        INSERT INTO workspace_add_intents(workspace_uuid, destination_path, intent_json)
+        VALUES (?, ?, ?)
+        ON CONFLICT(workspace_uuid) DO NOTHING
+      `).run(proposed.workspaceId, proposed.destinationPath, stableJson(proposed));
+        }
+        catch (error) {
+            const destinationOwner = database.prepare("SELECT workspace_uuid AS workspaceId FROM workspace_add_intents WHERE destination_path = ?").get(proposed.destinationPath);
+            if (destinationOwner) {
+                throw new Error(`workspace Add destination belongs to pending workspace ${destinationOwner.workspaceId}`);
+            }
+            throw error;
+        }
+        if (inserted.changes === 1)
+            return { intent: proposed, created: true };
+        const existing = database.prepare("SELECT intent_json AS intentJson FROM workspace_add_intents WHERE workspace_uuid = ?").get(proposed.workspaceId);
+        if (!existing)
+            throw new Error(`workspace Add intent ${proposed.workspaceId} was not persisted`);
+        return { intent: parseWorkspaceAddIntent(existing.intentJson), created: false };
+    }
+    finally {
+        database.close();
+    }
+}
+function deleteWorkspaceAddIntent(file, workspaceId) {
+    const database = initializeDatabase(file);
+    try {
+        database.prepare("DELETE FROM workspace_add_intents WHERE workspace_uuid = ?").run(workspaceId);
+    }
+    finally {
+        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) {
@@ -945,12 +1176,14 @@ function findKnownEntityId(file, absolutePath, deviceNumber, inode) {
     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}`);
+        if (exact.length > 0) {
+            return selectKnownRegistrationId(absolutePath, exact.map(({ uuid }) => ({ uuid, absolutePath })));
         }
-        return ids[0] ?? null;
+        const physical = database.prepare(`
+      SELECT uuid, absolute_path AS absolutePath
+        FROM entities WHERE device_number = ? AND inode = ?
+    `).all(deviceNumber, inode);
+        return selectKnownRegistrationId(absolutePath, physical);
     }
     finally {
         database.close();
@@ -964,7 +1197,8 @@ function readOutbox(file) {
         return database.prepare(`
       SELECT mutation_id AS mutationId, resource_id AS resourceId,
              authority_epoch AS authorityEpoch, base_version AS baseVersion,
-             snapshot_checksum AS snapshotChecksum, snapshot_json AS snapshotJson
+             snapshot_checksum AS snapshotChecksum, snapshot_json AS snapshotJson,
+             detected_records_json AS detectedRecordsJson
         FROM cloud_outbox ORDER BY sequence
     `).all();
     }
@@ -972,6 +1206,33 @@ function readOutbox(file) {
         database.close();
     }
 }
+/** Record is the SQLite transaction that accepts Detect's exact proposals and
+ * advances the last-verified notebook. Watch may settle only after this
+ * function returns. The existing outbox remains the one journal and queue. */
+function commitDetectedState(file, input) {
+    const database = initializeDatabase(file);
+    try {
+        database.transaction(() => {
+            if (input.outbox) {
+                database.prepare(`
+          INSERT INTO cloud_outbox(
+            mutation_id, resource_id, authority_epoch, base_version,
+            snapshot_checksum, snapshot_json, detected_records_json, created_at
+          ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+        `).run(input.outbox.mutationId, input.outbox.resourceId, input.outbox.authorityEpoch, input.outbox.baseVersion, input.outbox.snapshotChecksum, input.outbox.snapshotJson, input.outbox.detectedRecordsJson, new Date().toISOString());
+            }
+            const remove = database.prepare("DELETE FROM detection_notebook WHERE uuid = ?");
+            for (const uuid of input.notebookRemovals)
+                remove.run(uuid);
+            const upsertNotebook = prepareGroundUpsert(database, "detection_notebook");
+            for (const row of input.acceptedNotebookRows)
+                upsertNotebook.run(...groundRowValues(row));
+        })();
+    }
+    finally {
+        database.close();
+    }
+}
 function deleteOutbox(file, mutationId) {
     const database = initializeDatabase(file);
     try {
@@ -987,7 +1248,63 @@ function portableRecord(row) {
 function portableRecords(file) {
     return readRows(file).map(portableRecord);
 }
-function persistRows(file, identity, resourceId, rootUUID, rows, previousRows = []) {
+function capturedGroundRow(resourceId, rootUUID, row) {
+    return {
+        resourceId,
+        rootUUID,
+        uuid: row.record.uuid,
+        type: row.record.type,
+        parentUUID: row.record.parentUUID,
+        name: row.record.name,
+        status: "active",
+        version: row.record.version,
+        payloadVersion: row.record.payloadVersion,
+        transportVersion: row.record.transportVersion,
+        relativePath: row.relativePath,
+        absolutePath: row.absolutePath,
+        deviceNumber: row.deviceNumber,
+        inode: row.inode,
+        byteSize: row.byteSize,
+        modifiedTimeMs: row.modifiedTimeMs,
+        changedTimeMs: row.changedTimeMs,
+        filesystemMode: row.filesystemMode,
+        contentVerifiedAtMs: row.contentVerifiedAtMs,
+    };
+}
+function groundRowValues(row) {
+    return [
+        row.uuid, row.resourceId, row.rootUUID, row.type, row.parentUUID, row.name, row.status,
+        row.version, row.payloadVersion, row.transportVersion, row.relativePath, row.absolutePath,
+        row.deviceNumber, row.inode, row.byteSize, row.modifiedTimeMs, row.changedTimeMs,
+        row.filesystemMode, row.contentVerifiedAtMs,
+    ];
+}
+function prepareGroundUpsert(database, table) {
+    return database.prepare(`
+    INSERT INTO ${table}(${GROUND_ROW_COLUMNS})
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    ON CONFLICT(uuid) DO UPDATE SET
+      resource_id = excluded.resource_id,
+      root_uuid = excluded.root_uuid,
+      type = excluded.type,
+      parent_uuid = excluded.parent_uuid,
+      name = excluded.name,
+      status = excluded.status,
+      version = excluded.version,
+      payload_version = excluded.payload_version,
+      transport_version = excluded.transport_version,
+      relative_path = excluded.relative_path,
+      absolute_path = excluded.absolute_path,
+      device_number = excluded.device_number,
+      inode = excluded.inode,
+      byte_size = excluded.byte_size,
+      modified_time_ms = excluded.modified_time_ms,
+      changed_time_ms = excluded.changed_time_ms,
+      filesystem_mode = excluded.filesystem_mode,
+      content_verified_at_ms = excluded.content_verified_at_ms
+  `);
+}
+function persistRows(file, identity, resourceId, rootUUID, rows, previousRows = [], options = {}) {
     const database = initializeDatabase(file);
     try {
         const replaceIdentity = database.prepare(`
@@ -998,37 +1315,15 @@ function persistRows(file, identity, resourceId, rootUUID, rows, previousRows =
         user_email = excluded.user_email,
         device_id = excluded.device_id
     `);
-        const upsert = database.prepare(`
-      INSERT INTO entities(
-        uuid, resource_id, root_uuid, type, parent_uuid, name, status, version, payload_version,
-        transport_version, relative_path, absolute_path, device_number, inode
-        , byte_size, modified_time_ms, changed_time_ms, filesystem_mode, content_verified_at_ms
-      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-      ON CONFLICT(uuid) DO UPDATE SET
-        resource_id = excluded.resource_id,
-        root_uuid = excluded.root_uuid,
-        type = excluded.type,
-        parent_uuid = excluded.parent_uuid,
-        name = excluded.name,
-        status = excluded.status,
-        version = excluded.version,
-        payload_version = excluded.payload_version,
-        transport_version = excluded.transport_version,
-        relative_path = excluded.relative_path,
-        absolute_path = excluded.absolute_path,
-        device_number = excluded.device_number,
-        inode = excluded.inode,
-        byte_size = excluded.byte_size,
-        modified_time_ms = excluded.modified_time_ms,
-        changed_time_ms = excluded.changed_time_ms,
-        filesystem_mode = excluded.filesystem_mode,
-        content_verified_at_ms = excluded.content_verified_at_ms
-    `);
+        const upsert = prepareGroundUpsert(database, "entities");
+        const upsertNotebook = prepareGroundUpsert(database, "detection_notebook");
         const remove = database.prepare("DELETE FROM entities WHERE uuid = ? AND resource_id = ? AND root_uuid = ?");
+        const removeNotebook = database.prepare("DELETE FROM detection_notebook WHERE uuid = ? AND resource_id = ? AND root_uuid = ?");
         const previousByUuid = new Map(previousRows.map((row) => [row.uuid, row]));
+        const materializedIds = new Set(database.prepare("SELECT uuid FROM entities").all()
+            .map(({ uuid }) => uuid));
         const currentUuids = new Set(rows.map((row) => row.record.uuid));
-        const changed = rows.filter((row) => {
-            const old = previousByUuid.get(row.record.uuid);
+        const rowChanged = (row, old) => {
             return !old
                 || old.resourceId !== resourceId
                 || old.rootUUID !== rootUUID
@@ -1048,15 +1343,27 @@ function persistRows(file, identity, resourceId, rootUUID, rows, previousRows =
                 || old.changedTimeMs !== row.changedTimeMs
                 || old.filesystemMode !== row.filesystemMode
                 || old.contentVerifiedAtMs !== row.contentVerifiedAtMs;
-        });
+        };
+        const changed = rows.filter((row) => !materializedIds.has(row.record.uuid)
+            || rowChanged(row, previousByUuid.get(row.record.uuid)));
+        const notebookChanged = rows.filter((row) => rowChanged(row, previousByUuid.get(row.record.uuid)));
         const replace = database.transaction(() => {
             replaceIdentity.run(identity.userId, identity.userEmail, identity.deviceId);
             for (const old of previousRows) {
-                if (!currentUuids.has(old.uuid))
+                if (!currentUuids.has(old.uuid)) {
                     remove.run(old.uuid, resourceId, old.rootUUID);
+                    if (options.updateNotebook !== false) {
+                        removeNotebook.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);
+                upsert.run(...groundRowValues(capturedGroundRow(resourceId, rootUUID, row)));
+            if (options.updateNotebook !== false) {
+                for (const row of notebookChanged) {
+                    upsertNotebook.run(...groundRowValues(capturedGroundRow(resourceId, rootUUID, row)));
+                }
+            }
         });
         replace();
     }
@@ -1064,6 +1371,29 @@ function persistRows(file, identity, resourceId, rootUUID, rows, previousRows =
         database.close();
     }
 }
+/** A same-filesystem rename preserves identity and bytes but may advance the
+ * root directory's ctime. Refresh that one derived fingerprint before the
+ * binding makes the committed graph observable. */
+function refreshRevealedRootEvidence(file, workspaceId, absolutePath) {
+    const stats = statFingerprint(lstatSync(absolutePath));
+    const database = initializeDatabase(file);
+    try {
+        const refresh = (table) => database.prepare(`
+      UPDATE ${table} SET
+        device_number = ?, inode = ?, byte_size = ?, modified_time_ms = ?,
+        changed_time_ms = ?, filesystem_mode = ?
+      WHERE uuid = ? AND absolute_path = ?
+    `).run(stats.deviceNumber, stats.inode, stats.byteSize, stats.modifiedTimeMs, stats.changedTimeMs, stats.filesystemMode, workspaceId, absolutePath);
+        const result = refresh("entities");
+        if (result.changes !== 1) {
+            throw new Error(`revealed workspace ${workspaceId} has no committed root row`);
+        }
+        refresh("detection_notebook");
+    }
+    finally {
+        database.close();
+    }
+}
 function assertDatabaseIdentity(file, identity) {
     const database = new Database(file, { readonly: true });
     try {
@@ -1181,7 +1511,9 @@ function materializedWorkspaceBindings(bindingDir) {
 async function scanAndRegister(input) {
     const { identity, userRoot, database, cacheDir, suspicions, onScan } = input;
     const resourceId = privateEntityResourceId(identity.userId, sha256Hex);
-    const existing = readRows(database);
+    const materialized = readRows(database);
+    const notebook = readDetectionNotebook(database);
+    const existing = suspicions ? notebook : materialized;
     const ignoreFile = join(userRoot, ".amalgmignore");
     const policy = createUserGroundEnrollmentPolicy(existsSync(ignoreFile) ? readFileSync(ignoreFile, "utf8") : "");
     const bindingDir = workspaceBindingDir(userRoot, identity.deviceId);
@@ -1195,8 +1527,9 @@ async function scanAndRegister(input) {
     const suspicionFor = (root) => {
         if (!suspicions || !suspicions.has(root))
             return suspicions ? [] : null;
-        return suspicions.get(root);
+        return suspicions.get(root).paths;
     };
+    const observationFor = (root) => suspicions?.get(root);
     const existingCore = existing.find((row) => row.parentUUID === null && row.absolutePath === userRoot && row.type === "workspace");
     const coreUUID = existingCore?.uuid || randomUUID();
     const existingReferenceIds = new Set(existing
@@ -1205,7 +1538,10 @@ async function scanAndRegister(input) {
     const coreSuspicion = suspicionFor(userRoot);
     const missingPortableReference = [...boundRoots.keys()]
         .some((workspaceId) => !existingReferenceIds.has(workspaceId));
-    const deferredRootIds = new Set();
+    const acceptedRecords = [];
+    const acceptedNotebookRows = [];
+    const notebookRemovals = new Set();
+    const detection = [];
     const scan = async (parameters) => {
         const counters = {
             entries: 0,
@@ -1216,6 +1552,14 @@ async function scanAndRegister(input) {
         };
         const started = performance.now();
         const result = await scanRoot({ ...parameters, evidence: counters });
+        if (result.detection)
+            detection.push(result.detection);
+        for (const uuid of result.notebookRemovals)
+            notebookRemovals.add(uuid);
+        if (result.transferable) {
+            acceptedRecords.push(...result.records);
+            acceptedNotebookRows.push(...result.rows.map((row) => capturedGroundRow(parameters.resourceId, parameters.rootUUID, row)));
+        }
         onScan?.({
             rootId: parameters.rootUUID,
             directory: parameters.rootPath,
@@ -1230,7 +1574,7 @@ async function scanAndRegister(input) {
         await new Promise((resolve) => setImmediate(resolve));
         return result;
     };
-    const core = await scan({
+    await scan({
         identity,
         resourceId,
         rootUUID: coreUUID,
@@ -1245,13 +1589,12 @@ async function scanAndRegister(input) {
             ? [...new Set([...coreSuspicion, "workspaces"])]
             : coreSuspicion,
         existingRows: existing.filter((row) => row.rootUUID === coreUUID),
+        suspicion: observationFor(userRoot),
     });
-    if (!core.transferable)
-        deferredRootIds.add(coreUUID);
     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({
+        await scan({
             identity,
             resourceId,
             rootUUID: workspaceId,
@@ -1268,13 +1611,15 @@ async function scanAndRegister(input) {
             suspects: existingWorkspaceRows.length === 0 ? null : suspicionFor(rootPath),
             existingRows: existingWorkspaceRows,
             registeredBoundaries,
+            suspicion: observationFor(rootPath),
         });
-        if (!scanned.transferable)
-            deferredRootIds.add(workspaceId);
     }
-    return readRows(database)
-        .filter((row) => !deferredRootIds.has(row.rootUUID))
-        .map(portableRecord);
+    return {
+        records: acceptedRecords,
+        detection,
+        acceptedNotebookRows,
+        notebookRemovals: [...notebookRemovals],
+    };
 }
 async function scanRoot(input) {
     const { identity, resourceId, rootUUID, rootName, rootPath, rootType, database, cacheDir, policy, bindingDir, suspects = null, evidence, } = input;
@@ -1293,32 +1638,43 @@ async function scanRoot(input) {
         && suspects.length === 0
         && existingRows.length > 0
         && completeRepositoryEvidence) {
+        const rows = existingRows.map((row) => ({
+            record: portableRecord(row),
+            relativePath: row.relativePath,
+            absolutePath: row.absolutePath,
+            deviceNumber: row.deviceNumber,
+            inode: row.inode,
+            byteSize: row.byteSize,
+            modifiedTimeMs: row.modifiedTimeMs,
+            changedTimeMs: row.changedTimeMs,
+            filesystemMode: row.filesystemMode,
+            contentVerifiedAtMs: row.contentVerifiedAtMs,
+        }));
         return {
             records: existingRows.map(portableRecord),
-            rows: existingRows.map((row) => ({
-                record: portableRecord(row),
-                relativePath: row.relativePath,
-                absolutePath: row.absolutePath,
-                deviceNumber: row.deviceNumber,
-                inode: row.inode,
-                byteSize: row.byteSize,
-                modifiedTimeMs: row.modifiedTimeMs,
-                changedTimeMs: row.changedTimeMs,
-                filesystemMode: row.filesystemMode,
-                contentVerifiedAtMs: row.contentVerifiedAtMs,
-            })),
+            rows,
             referenceWorkspaceIds: existingRows
                 .filter((row) => row.type === "reference" && row.payloadVersion && UUID.test(row.payloadVersion))
                 .map((row) => row.payloadVersion),
             transferable: true,
+            notebookRemovals: [],
+            detection: input.suspicion ? planGroundDetection({
+                rootId: rootUUID,
+                suspicion: input.suspicion,
+                before: existingRows.map(portableRecord),
+                after: rows.map((row) => ({ record: row.record, relativePath: row.relativePath })),
+            }) : null,
         };
     }
     const entries = [];
     const referenceWorkspaceIds = new Set();
     const rootStats = lstatSync(rootPath);
+    const priorRootType = existingByPath.get("")?.type;
+    const rootRailChanged = priorRootType !== undefined && priorRootType !== rootType;
     evidence && (evidence.entries += 1);
     entries.push({
         uuid: rootUUID,
+        fixedUUID: rootUUID,
         type: rootType,
         parentUUID: input.rootParentUUID ?? null,
         name: rootName,
@@ -1355,7 +1711,7 @@ async function scanRoot(input) {
     };
     const visit = async (directory, parentUUID, parentType, base = "", activeRepository = parentType === "repo.git"
         ? { root: directory, evidencePaths: repositoryEvidencePaths(directory), evidence: null }
-        : null) => {
+        : null, forceObserve = rootRailChanged) => {
         const children = readdirSync(directory, { withFileTypes: true })
             .sort((left, right) => left.name < right.name ? -1 : left.name > right.name ? 1 : 0);
         for (const child of children) {
@@ -1378,7 +1734,7 @@ async function scanRoot(input) {
             const stableDuringCompleteCatchUp = suspects === null
                 && existing !== undefined
                 && reusableDuringCompleteCatchUp(existing, stats);
-            const observe = existing === undefined
+            const observe = forceObserve || existing === undefined
                 || (suspects === null ? !stableDuringCompleteCatchUp : touchesSuspicion(relativePath));
             if (!observe && suspects === null)
                 evidence && (evidence.metadataReused += 1);
@@ -1402,6 +1758,7 @@ async function scanRoot(input) {
                 : undefined;
             let type;
             let payloadVersion = null;
+            let linkTarget;
             let contentVerifiedAtMs = existing?.contentVerifiedAtMs ?? null;
             if (!observe && existing && !stats.isDirectory()) {
                 type = existing.type;
@@ -1424,7 +1781,8 @@ async function scanRoot(input) {
                     }
                     else {
                         evidence && (evidence.contentReads += 1);
-                        const bytes = Buffer.from(readlinkSync(absolutePath), "utf8");
+                        linkTarget = readlinkSync(absolutePath);
+                        const bytes = Buffer.from(linkTarget, "utf8");
                         payloadVersion = sha256Hex(bytes);
                         if (!activeRepository)
                             immutableWriteArtifact(cacheDir, {
@@ -1458,6 +1816,7 @@ async function scanRoot(input) {
                 contentVerifiedAtMs = Date.now();
             entries.push({
                 uuid,
+                ...(registeredBoundaryId ? { fixedUUID: registeredBoundaryId } : {}),
                 type,
                 parentUUID,
                 name: child.name,
@@ -1466,20 +1825,47 @@ async function scanRoot(input) {
                 payloadVersion,
                 transportVersion: null,
                 contentVerifiedAtMs,
+                ...(linkTarget !== undefined ? { linkTarget } : {}),
                 ...statFingerprint(stats),
             });
             if (stats.isDirectory() && !stats.isSymbolicLink()) {
+                const childRailChanged = existing !== undefined && existing.type !== type;
                 await visit(absolutePath, uuid, type, relativePath, type === "repo.git"
                     ? {
                         root: absolutePath,
                         evidencePaths: repositoryEvidencePaths(absolutePath),
                         evidence: null,
                     }
-                    : activeRepository);
+                    : activeRepository, forceObserve || childRailChanged);
             }
         }
     };
     await visit(rootPath, rootUUID, rootType);
+    const resolvedIdentity = reconcileGroundUUIDs(existingRows.map((row) => ({
+        uuid: row.uuid,
+        type: row.type,
+        relativePath: row.relativePath,
+        deviceNumber: row.deviceNumber,
+        inode: row.inode,
+    })), entries.map((entry) => ({
+        key: entry.relativePath,
+        type: entry.type,
+        relativePath: entry.relativePath,
+        deviceNumber: entry.deviceNumber,
+        inode: entry.inode,
+        ...(entry.fixedUUID ? { fixedUUID: entry.fixedUUID } : {}),
+    })));
+    const resolvedByProvisional = new Map();
+    for (const entry of entries) {
+        const resolved = resolvedIdentity.get(entry.relativePath) ?? entry.uuid;
+        resolvedByProvisional.set(entry.uuid, resolved);
+        entry.uuid = resolved;
+    }
+    for (const entry of entries) {
+        if (entry.parentUUID !== null) {
+            entry.parentUUID = resolvedByProvisional.get(entry.parentUUID) ?? entry.parentUUID;
+        }
+    }
     const children = new Map();
     for (const entry of entries) {
         if (entry.parentUUID === null)
@@ -1523,10 +1909,13 @@ async function scanRoot(input) {
     });
     const persistCurrentRows = () => {
         const rows = rowsFromEntries();
-        persistRows(database, identity, resourceId, rootUUID, rows, existingRows);
+        persistRows(database, identity, resourceId, rootUUID, rows, existingRows, {
+            updateNotebook: input.suspicion === undefined,
+        });
         return rows;
     };
     const repositories = entries.filter((entry) => entry.type === "repo.git");
+    const replayByUuid = new Map();
     const properDescendantOf = (candidate, ancestor) => ancestor === "" ? candidate !== "" : candidate.startsWith(`${ancestor}/`);
     const repositoryOwner = (entry) => repositories
         .filter((repository) => repository.uuid !== entry.uuid
@@ -1551,12 +1940,14 @@ async function scanRoot(input) {
                 repository.transportVersion = priorRow.transportVersion;
             }
             let prior = null;
+            let priorLayout = null;
             if (priorRow?.type === "repo.git" && priorRow.payloadVersion && priorRow.transportVersion) {
                 const priorPath = join(cacheDir, `${priorRow.transportVersion}.bin`);
                 if (existsSync(priorPath)) {
                     try {
                         const layout = inspectRepositoryTransportFile(priorPath);
                         if (layout.stateId === priorRow.payloadVersion) {
+                            priorLayout = layout;
                             prior = {
                                 stateId: priorRow.payloadVersion,
                                 transportVersion: priorRow.transportVersion,
@@ -1606,6 +1997,17 @@ async function scanRoot(input) {
                     contentHash: captured.transportVersion,
                 }, captured.bytes);
             }
+            const currentLayout = inspectRepositoryTransportFile(join(cacheDir, `${captured.transportVersion}.bin`));
+            replayByUuid.set(repository.uuid, {
+                kind: "repo.git",
+                stateId: currentLayout.stateId,
+                cardId: currentLayout.cardId,
+                checkpointId: currentLayout.checkpointId,
+                cardChanged: priorLayout?.cardId !== currentLayout.cardId,
+                checkpointChanged: priorLayout?.checkpointId !== currentLayout.checkpointId,
+                parentTransportVersion: currentLayout.parentTransportVersion,
+                transportVersion: captured.transportVersion,
+            });
         }
     }
     catch {
@@ -1621,14 +2023,90 @@ async function scanRoot(input) {
             rows,
             referenceWorkspaceIds: [...referenceWorkspaceIds],
             transferable: false,
+            notebookRemovals: [],
+            detection: null,
         };
     }
     const rows = persistCurrentRows();
+    const currentUUIDs = new Set(rows.map((row) => row.record.uuid));
+    const notebookRemovals = input.suspicion === undefined ? [] : existingRows
+        .filter((row) => !currentUUIDs.has(row.uuid) && existsSync(row.absolutePath))
+        .map((row) => row.uuid);
+    const before = existingRows.map(portableRecord);
+    const beforeByUuid = new Map(before.map((record) => [record.uuid, record]));
+    const detected = rows.map((row) => {
+        const base = beforeByUuid.get(row.record.uuid) ?? null;
+        const contentChanged = base === null
+            || base.type !== row.record.type
+            || base.payloadVersion !== row.record.payloadVersion
+            || base.transportVersion !== row.record.transportVersion;
+        let replay = { kind: "structure" };
+        if (contentChanged) {
+            switch (row.record.type) {
+                case "file.text":
+                    if (!row.record.payloadVersion)
+                        throw new Error("detected text file has no content head");
+                    replay = {
+                        kind: "file.text",
+                        mode: "snapshot",
+                        basePayloadVersion: base?.payloadVersion && /^[0-9a-f]{64}$/.test(base.payloadVersion)
+                            ? base.payloadVersion
+                            : null,
+                        resultPayloadVersion: row.record.payloadVersion,
+                        delta: null,
+                    };
+                    break;
+                case "file.binary": {
+                    if (!row.record.payloadVersion)
+                        throw new Error("detected binary file has no content head");
+                    const manifest = readCachedManifest(cacheDir, row.record.payloadVersion);
+                    if (manifest) {
+                        replay = {
+                            kind: "file.binary",
+                            resultPayloadVersion: row.record.payloadVersion,
+                            manifest,
+                        };
+                    }
+                    break;
+                }
+                case "link": {
+                    if (!row.record.payloadVersion)
+                        throw new Error("detected link has no content head");
+                    const target = entries.find((entry) => entry.uuid === row.record.uuid)?.linkTarget;
+                    if (target !== undefined) {
+                        replay = {
+                            kind: "link",
+                            resultPayloadVersion: row.record.payloadVersion,
+                            target,
+                        };
+                    }
+                    break;
+                }
+                case "repo.git": {
+                    const repositoryReplay = replayByUuid.get(row.record.uuid);
+                    if (!repositoryReplay)
+                        throw new Error("detected repository has no Card + Checkpoint replay");
+                    replay = repositoryReplay;
+                    break;
+                }
+                default:
+                    break;
+            }
+        }
+        return { record: row.record, relativePath: row.relativePath, replay };
+    });
     return {
         records: rows.map((row) => row.record),
         rows,
         referenceWorkspaceIds: [...referenceWorkspaceIds],
         transferable: true,
+        notebookRemovals,
+        detection: input.suspicion ? planGroundDetection({
+            rootId: rootUUID,
+            suspicion: input.suspicion,
+            before,
+            after: detected,
+        }) : null,
     };
 }
 function portablePaths(records, boundaryUUIDs = new Set()) {
@@ -1695,6 +2173,40 @@ function mergeMaterializedRoots(cloudRecords, localRecords) {
     });
     return [...preserved, ...localRecords];
 }
+/** Filesystem disappearance is evidence, not cloud lifecycle authority. Keep
+ * the last logical records in the outgoing graph while their materialized
+ * rows remain absent, and derive container membership from that honest union. */
+function recordsRetainingMissingEvidence(present, missing) {
+    const byUuid = new Map(present.map((record) => [record.uuid, record]));
+    for (const record of missing) {
+        if (!byUuid.has(record.uuid))
+            byUuid.set(record.uuid, record);
+    }
+    const records = [...byUuid.values()];
+    const activeChildren = new Map();
+    for (const record of records) {
+        if (record.status !== "active" || record.parentUUID === null)
+            continue;
+        const children = activeChildren.get(record.parentUUID) ?? [];
+        children.push(record);
+        activeChildren.set(record.parentUUID, children);
+    }
+    return records.map((record) => {
+        if (record.type !== "workspace" && record.type !== "folder")
+            return record;
+        const payloadVersion = membershipHash(activeChildren.get(record.uuid) ?? [], sha256Hex);
+        return {
+            ...record,
+            version: canonicalVersion({
+                type: record.type,
+                parentUUID: record.parentUUID,
+                name: record.name,
+                status: record.status,
+                payloadVersion,
+            }, sha256Hex),
+        };
+    });
+}
 function clearCoreMaterialization(userRoot) {
     ensurePrivateDir(userRoot);
     for (const entry of readdirSync(userRoot, { withFileTypes: true })) {
@@ -1706,8 +2218,12 @@ function clearCoreMaterialization(userRoot) {
 function deleteRootRows(databasePath, resourceId, rootUUID) {
     const database = initializeDatabase(databasePath);
     try {
-        database.prepare("DELETE FROM entities WHERE resource_id = ? AND root_uuid = ?")
-            .run(resourceId, rootUUID);
+        database.transaction(() => {
+            database.prepare("DELETE FROM entities WHERE resource_id = ? AND root_uuid = ?")
+                .run(resourceId, rootUUID);
+            database.prepare("DELETE FROM detection_notebook WHERE resource_id = ? AND root_uuid = ?")
+                .run(resourceId, rootUUID);
+        })();
     }
     finally {
         database.close();
@@ -2012,94 +2528,171 @@ function installCloudWorkspaceReferences(input) {
     return references;
 }
 async function installCloudWorkspace(input) {
-    const { identity, userRoot, database, cacheDir, bindingDir, resourceId, workspace, reference, references, records, destinationParent, readContent, } = input;
+    const { identity, userRoot, database, cacheDir, bindingDir, resourceId, workspace, reference, references, records, destinationParent, cloudHead, readContent, onStage, } = input;
     const allLocalRows = readRows(database);
     const existingBoundary = allLocalRows.find((row) => row.uuid === workspace.uuid);
     const existing = existingBoundary
         ? descendantRows(allLocalRows, workspace.uuid)
         : [];
+    const pending = readWorkspaceAddIntent(database, workspace.uuid);
     if (existing.length > 0) {
         const root = existing.find((row) => row.uuid === workspace.uuid);
-        if (!root || !pathExists(root.absolutePath)) {
+        if (!root) {
             throw new Error(`local workspace ${workspace.uuid} has unresolved placement`);
         }
+        const expectedRecords = pending?.records ?? records;
         const localRecords = existing.map((row) => Object.fromEntries(PORTABLE_FIELDS.map((field) => [field, row[field]])));
-        if (!sameRecords(travelingRecords(localRecords), records)) {
+        if (!sameRecords(travelingRecords(localRecords), expectedRecords)) {
             throw new Error(`local workspace ${workspace.uuid} differs from its cloud graph`);
         }
+        if (pending && root.absolutePath !== pending.destinationPath) {
+            throw new Error(`workspace ${workspace.uuid} rows differ from its pending destination`);
+        }
+        let revealed = false;
+        if (!pathExists(root.absolutePath)) {
+            if (!pending || !pathExists(pending.stagingPath)) {
+                throw new Error(`local workspace ${workspace.uuid} has unresolved placement`);
+            }
+            renameSync(pending.stagingPath, pending.destinationPath);
+            revealed = true;
+        }
+        else if (pending && pathExists(pending.stagingPath)) {
+            throw new Error(`workspace ${workspace.uuid} has both staged and revealed ground`);
+        }
+        if (pending && pathExists(root.absolutePath)) {
+            refreshRevealedRootEvidence(database, workspace.uuid, root.absolutePath);
+        }
+        if (revealed)
+            await onStage?.("ground-revealed");
+        ensureWorkspaceBinding({
+            bindingDir,
+            workspaceId: workspace.uuid,
+            absolutePath: root.absolutePath,
+        });
+        if (pending)
+            await onStage?.("binding-created");
+        const activeReferences = pending?.references ?? references;
+        const activeSelection = pending ? workspaceAddSelection(pending) : { workspace, reference };
         const installedReferences = installCloudWorkspaceReferences({
             identity,
             userRoot,
             database,
             bindingDir,
             resourceId,
-            workspace,
-            references,
+            workspace: activeSelection.workspace,
+            references: activeReferences,
         });
         return {
             path: root.absolutePath,
             rows: existing.length,
             records: localRecords,
-            reference,
+            reference: activeSelection.reference,
             references: installedReferences,
-            alreadyMaterialized: true,
+            alreadyMaterialized: pending === null,
         };
     }
     const parent = realpathSync(resolve(destinationParent));
     if (!statSync(parent).isDirectory())
         throw new Error("destination must be a directory");
     const destination = join(parent, workspace.name);
+    if (dirname(destination) !== parent || basename(destination) !== workspace.name) {
+        throw new Error("workspace name must be one path segment");
+    }
     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);
     const binding = join(bindingDir, workspace.uuid);
-    if (pathExists(binding))
-        throw new Error(`workspace ${workspace.uuid} already has a local binding`);
-    try {
-        const materialized = await materializeRecords({
-            records,
-            rootPath: destination,
-            boundaryUUID: workspace.uuid,
-            cacheDir,
-            bindingDir,
-            readContent,
-        });
-        const rows = projectMaterializedGraph(materialized.rows, materialized.repositories.map((repository) => ({
-            record: repository.record,
-            identity: repository.state.identity,
-        })), sha256Hex);
-        symlinkSync(destination, binding, "dir");
-        persistRows(database, identity, resourceId, workspace.uuid, rows);
-        const installedReferences = installCloudWorkspaceReferences({
-            identity,
-            userRoot,
-            database,
-            bindingDir,
+    let intent = pending;
+    if (!intent) {
+        const stagingPath = workspaceAddStagingPath(destination, workspace.uuid);
+        if (pathExists(destination))
+            throw new Error(`workspace destination already exists: ${destination}`);
+        if (pathExists(stagingPath))
+            throw new Error(`workspace staging path already exists: ${stagingPath}`);
+        if (pathExists(binding))
+            throw new Error(`workspace ${workspace.uuid} already has a local binding`);
+        for (const bound of materializedWorkspaceBindings(bindingDir)) {
+            if (pathWithin(bound.directory, destination) || pathWithin(destination, bound.directory)) {
+                throw new Error(`files add destination overlaps materialized workspace ${bound.workspaceId}`);
+            }
+        }
+        const written = persistWorkspaceAddIntent(database, {
+            workspaceId: workspace.uuid,
             resourceId,
-            workspace,
-            references,
+            cloudHead,
+            destinationPath: destination,
+            stagingPath,
+            records: snapshotFromRecords(records).records,
+            references: snapshotFromRecords(references).records,
         });
-        return {
-            path: destination,
-            rows: rows.length,
-            records: rows.map((row) => row.record),
-            reference,
-            references: installedReferences,
-            alreadyMaterialized: false,
-        };
+        intent = written.intent;
+        if (written.created)
+            await onStage?.("intent-recorded");
     }
-    catch (error) {
-        deleteRootRows(database, resourceId, workspace.uuid);
-        if (pathExists(binding))
-            rmSync(binding, { force: true });
-        if (pathExists(destination))
-            rmSync(destination, { recursive: true, force: true });
-        throw error;
+    if (intent.destinationPath !== destination) {
+        throw new Error(`workspace ${workspace.uuid} already has a pending Add at ${intent.destinationPath}`);
+    }
+    if (intent.resourceId !== resourceId) {
+        throw new Error(`workspace ${workspace.uuid} Add intent belongs to a different registry`);
+    }
+    if (pathExists(intent.destinationPath)) {
+        throw new Error(`workspace ${workspace.uuid} is visible without committed entity rows`);
+    }
+    if (pathExists(binding)) {
+        throw new Error(`workspace ${workspace.uuid} has a binding without committed entity rows`);
+    }
+    if (pathExists(intent.stagingPath)) {
+        rmSync(intent.stagingPath, { recursive: true, force: true });
     }
+    const selection = workspaceAddSelection(intent);
+    const materialized = await materializeRecords({
+        records: intent.records,
+        rootPath: intent.stagingPath,
+        boundaryUUID: intent.workspaceId,
+        cacheDir,
+        bindingDir,
+        readContent,
+    });
+    const rows = projectMaterializedGraph(materialized.rows, materialized.repositories.map((repository) => ({
+        record: repository.record,
+        identity: repository.state.identity,
+    })), sha256Hex).map((row) => ({
+        ...row,
+        absolutePath: row.relativePath
+            ? join(intent.destinationPath, ...row.relativePath.split("/"))
+            : intent.destinationPath,
+    }));
+    await onStage?.("materialization-verified");
+    persistRows(database, identity, intent.resourceId, intent.workspaceId, rows);
+    await onStage?.("rows-committed");
+    renameSync(intent.stagingPath, intent.destinationPath);
+    refreshRevealedRootEvidence(database, intent.workspaceId, intent.destinationPath);
+    await onStage?.("ground-revealed");
+    ensureWorkspaceBinding({
+        bindingDir,
+        workspaceId: intent.workspaceId,
+        absolutePath: intent.destinationPath,
+    });
+    await onStage?.("binding-created");
+    const installedReferences = installCloudWorkspaceReferences({
+        identity,
+        userRoot,
+        database,
+        bindingDir,
+        resourceId: intent.resourceId,
+        workspace: selection.workspace,
+        references: intent.references,
+    });
+    return {
+        path: intent.destinationPath,
+        rows: rows.length,
+        records: rows.map((row) => row.record),
+        reference: selection.reference,
+        references: installedReferences,
+        alreadyMaterialized: false,
+    };
 }
 function readyFromFrame(frame) {
     const bytes = Buffer.from(String(frame.snapshot_b64 || ""), "base64");