@amalgm/shell 0.1.41 → 0.1.42

package/dist/user-ground-host.js

@@ -8,7 +8,8 @@ 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, ensureWorkspaceBinding, 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 {
@@ -290,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)
@@ -317,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
@@ -709,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);
     }
@@ -937,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,
@@ -945,6 +992,7 @@ 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 (
@@ -956,6 +1004,10 @@ function initializeDatabase(file) {
       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));
@@ -970,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);
@@ -986,13 +1049,19 @@ 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`);
 }
@@ -1107,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();
@@ -1126,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();
     }
@@ -1134,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 {
@@ -1149,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(`
@@ -1160,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
@@ -1210,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();
     }
@@ -1233,15 +1378,17 @@ function refreshRevealedRootEvidence(file, workspaceId, absolutePath) {
     const stats = statFingerprint(lstatSync(absolutePath));
     const database = initializeDatabase(file);
     try {
-        const result = database.prepare(`
-      UPDATE entities SET
+        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();
@@ -1364,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);
@@ -1378,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
@@ -1388,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,
@@ -1399,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,
@@ -1413,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,
@@ -1428,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,
@@ -1451,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;
@@ -1476,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,
@@ -1538,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) {
@@ -1561,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);
@@ -1585,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;
@@ -1607,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, {
@@ -1641,6 +1816,7 @@ async function scanRoot(input) {
                 contentVerifiedAtMs = Date.now();
             entries.push({
                 uuid,
+                ...(registeredBoundaryId ? { fixedUUID: registeredBoundaryId } : {}),
                 type,
                 parentUUID,
                 name: child.name,
@@ -1649,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)
@@ -1706,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
@@ -1734,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,
@@ -1789,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 {
@@ -1804,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()) {
@@ -1878,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 })) {
@@ -1889,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();