@amalgm/shell 0.1.44 → 0.1.46

package/dist/user-ground-host.js

@@ -1,14 +1,16 @@
 import { createHash, randomUUID } from "node:crypto";
-import { existsSync, lstatSync, realpathSync, readFileSync, readdirSync, readlinkSync, renameSync, rmSync, statSync, symlinkSync, writeFileSync, } from "node:fs";
+import { existsSync, lstatSync, realpathSync, readFileSync, readdirSync, readlinkSync, renameSync, rmSync, statSync, symlinkSync, } from "node:fs";
 import { open } from "node:fs/promises";
 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 { CHUNK_BYTES, CONTENT_CONTRACT, ENTITY_CLOUD_CONTRACT, ENTITY_CLOUD_SCHEMA_VERSION, artifactForRecord, canonicalVersion, checkContentManifest, classifyDirectory, classifyFile, classifyRegisteredRoot, convergeUserGround, createUserGroundEnrollmentPolicy, isRepositoryMetadataEntry, download as downloadArtifact, 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 { ContentCacheDownload, captureContentFile, hashContentFile, sealCapturedArtifact, } from "./content-cache-host.js";
 import { decodeContentWireBytes, encodeContentWireBytes } from "./content-wire-codec.js";
-import { planGroundDetection, reconcileGroundUUIDs, } from "./detection-host.js";
+import { exactTextReplay, planGroundDetection, reconcileGroundUUIDs, } from "./detection/portable.js";
+import { NamedDetectRuntime } from "./detection/runtime.js";
+import { decodeMutationOperation, encodeMutationOperation, } from "./detection/journal-codec.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";
@@ -22,6 +24,9 @@ const PORTABLE_FIELDS = [
 const SMALL_CONTENT_UPLOAD_CONCURRENCY = 16;
 const FILE_CONTENT_DOWNLOAD_CONCURRENCY = 4;
 const FILE_BATCH_DOWNLOAD_CONCURRENCY = 2;
+const DETECT_QUIET_MS = 12;
+const DETECT_MAX_DEFERRAL_MS = 75;
+const DETECT_RETRY_MS = 250;
 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",
@@ -36,10 +41,13 @@ export class UserGroundHost {
     watchHost;
     activeIdentity = null;
     rescanTimer = null;
+    rescanGenerationStartedAt = null;
     watchDirty = false;
     cloudState = null;
     converged = false;
     syncing = null;
+    namedDetect = null;
+    coldOperation = false;
     closing = false;
     port;
     constructor(options) {
@@ -65,6 +73,7 @@ export class UserGroundHost {
                     local,
                 });
                 await this.resumeWorkspaceAdds(this.activeIdentity);
+                this.namedDetect ??= new NamedDetectRuntime(this.databasePath(this.activeIdentity), this.cacheDir(this.activeIdentity), this.userRoot(this.activeIdentity));
                 const watchHealth = this.watchHost.health();
                 if (watchHealth.state !== "healthy") {
                     throw new Error(`Watch coverage is degraded: ${watchHealth.reason ?? "unknown failure"}`);
@@ -234,6 +243,11 @@ export class UserGroundHost {
         if (!identity || !this.converged || !this.cloudState) {
             throw new Error("Files register requires a converged authenticated machine");
         }
+        this.coldOperation = true;
+        if (this.rescanTimer)
+            clearTimeout(this.rescanTimer);
+        this.rescanTimer = null;
+        this.rescanGenerationStartedAt = null;
         let watch;
         try {
             this.ensureWatchers(identity);
@@ -241,11 +255,13 @@ export class UserGroundHost {
             assertHealthyWatch(watch, workspaceId);
         }
         catch (error) {
+            this.coldOperation = false;
             throw stageError("Watch coverage", error);
         }
         let rows = readRows(this.databasePath(identity));
         if (rows.some((row) => row.uuid === workspaceId)
             && this.cloudState.records.some((record) => record.uuid === workspaceId)) {
+            this.coldOperation = false;
             return {
                 registered: true,
                 entityCount: descendantRows(rows, workspaceId).length,
@@ -253,20 +269,35 @@ export class UserGroundHost {
                 watch,
             };
         }
-        // Reconcile already made this newly declared root suspicious. Consume
-        // that evidence as-is: registration of one workspace must never widen
-        // uncertainty to every other root on the machine.
+        // Register is a cold declaration, not a filesystem edit. It performs one
+        // complete reconciliation and publishes one graph head; it must not mint
+        // a parallel stream of Detect records for the same initial contents.
+        const observations = this.watchHost.observations();
         this.watchDirty = false;
         try {
-            await this.syncNow();
-            if (!this.cloudState.records.some((record) => record.uuid === workspaceId)) {
-                // A pre-existing scan may have taken its observation before this
-                // declaration. Preserve the declared root as suspicion and give it
-                // one scan of its own. Completion is evidence about this workspace,
-                // never a demand that unrelated live Watch traffic become silent.
-                this.watchDirty = false;
-                await this.syncNow();
+            if (this.syncing)
+                await this.syncing;
+            const scanned = await reconcileGround({
+                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])),
+            });
+            const retry = scanned.detection.find((plan) => plan.kind === "retry");
+            if (retry?.kind === "retry") {
+                throw new Error(retry.reasons.join("; "));
             }
+            commitDetectedState(this.databasePath(identity), {
+                acceptedMaterializedRows: scanned.acceptedMaterializedRows,
+                materializedRemovals: scanned.materializedRemovals,
+                acceptedNotebookRows: scanned.acceptedNotebookRows,
+                notebookRemovals: scanned.notebookRemovals,
+            });
+            this.namedDetect?.refreshEnrollmentPolicy();
+            await this.publishMaterializedSnapshot(identity);
+            this.watchHost.settle(observations);
         }
         catch (error) {
             const failedStage = filesPipelineStage(error);
@@ -275,6 +306,9 @@ export class UserGroundHost {
             }
             throw stageError("entity registration or cloud publication", error);
         }
+        finally {
+            this.coldOperation = false;
+        }
         try {
             this.ensureWatchers(identity);
             watch = this.watchHost.evidence();
@@ -348,7 +382,10 @@ export class UserGroundHost {
             if (this.rescanTimer)
                 clearTimeout(this.rescanTimer);
             this.rescanTimer = null;
+            this.rescanGenerationStartedAt = null;
             this.watchHost.close({ catchUp: false });
+            this.namedDetect?.close();
+            this.namedDetect = null;
             await this.wire.close();
             return;
         }
@@ -360,12 +397,15 @@ export class UserGroundHost {
         if (this.rescanTimer)
             clearTimeout(this.rescanTimer);
         this.rescanTimer = null;
+        this.rescanGenerationStartedAt = null;
         // Full suspicion already contains every callback that could still be
         // queued. Retire physical coverage before the final observation so native
         // backends cannot continuously widen a finite shutdown pass. Changes
         // after this cutoff belong to the next startup blind interval.
         this.watchHost.close();
         await this.flushObservedChanges();
+        this.namedDetect?.close();
+        this.namedDetect = null;
         await this.wire.close();
     }
     userRoot(identity) {
@@ -377,7 +417,7 @@ export class UserGroundHost {
     cloudPort(identity) {
         return {
             lookup: async (resourceId) => {
-                await this.drainOutboxBeforeLookup(identity, resourceId);
+                await this.publishPendingSnapshotsBeforeLookup(identity, resourceId);
                 const frame = await this.wire.request({
                     type: "private.resource.lookup",
                     resource_id: resourceId,
@@ -420,7 +460,21 @@ export class UserGroundHost {
                     return null;
                 if (readRows(database).length === 0)
                     return null;
-                return localValue(identity, userRoot, database);
+                const local = localValue(identity, userRoot, database);
+                if (!hasDetectedChanges(database))
+                    return local;
+                if (!this.cloudState) {
+                    throw new Error("pending local mutations have no accepted cloud baseline");
+                }
+                // The official local projection remains the accepted cloud graph;
+                // Detect's newer materialization is represented exactly once by its
+                // durable journal records. Returning that baseline prevents login
+                // convergence from overwriting saved-local work before Send accepts it.
+                return {
+                    ...local,
+                    records: this.cloudState.records,
+                    pendingMutations: true,
+                };
             },
             initialize: async () => {
                 createDeclaredHome({
@@ -429,7 +483,7 @@ export class UserGroundHost {
                     declaration: this.options.declaration ?? shippedUserHomeDeclaration,
                     now: this.options.now?.() ?? new Date(),
                 });
-                await scanAndRegister({
+                await reconcileGround({
                     identity, userRoot, database, cacheDir,
                     onScan: this.options.onDetectScan,
                 });
@@ -683,17 +737,26 @@ export class UserGroundHost {
         }
         return health;
     }
-    scheduleRescan() {
+    scheduleRescan(retryDelayMs) {
         if (this.closing)
             return;
         this.watchDirty = true;
+        const now = performance.now();
+        this.rescanGenerationStartedAt ??= now;
+        const remaining = Math.max(0, DETECT_MAX_DEFERRAL_MS - (now - this.rescanGenerationStartedAt));
+        const delay = retryDelayMs ?? Math.min(DETECT_QUIET_MS, remaining);
         if (this.rescanTimer)
             clearTimeout(this.rescanTimer);
         this.rescanTimer = setTimeout(() => {
             this.rescanTimer = null;
+            this.rescanGenerationStartedAt = null;
             const identity = this.activeIdentity;
             if (!identity || this.closing)
                 return;
+            if (this.coldOperation) {
+                this.scheduleRescan();
+                return;
+            }
             void this.flushObservedChanges().then(() => {
                 if (this.closing)
                     return;
@@ -704,23 +767,55 @@ export class UserGroundHost {
                 if (this.watchDirty || this.watchHost.hasPending)
                     this.scheduleRescan();
             }).catch(() => {
-                // The durable outbox remains claimable by the next event or resume.
+                // Unsettled or unreadable truth keeps its Watch generation pending.
+                // Retry without requiring another user edit, but never hot-loop on a
+                // persistently unavailable path. A fresh ring replaces this timer
+                // with the ordinary low-latency settle window.
+                if (!this.closing)
+                    this.scheduleRescan(DETECT_RETRY_MS);
             });
-        }, 150);
+        }, delay);
         this.rescanTimer.unref();
     }
     async syncLocalChanges(identity) {
-        await this.drainOutbox(identity);
-        const state = this.cloudState;
-        if (!state)
+        if (!this.cloudState)
             throw new Error("cloud state is unavailable for user-ground Watch");
         const observations = this.watchHost.observations();
-        let localRecords;
+        if (this.namedDetect) {
+            // The named lane is an optimization over the same settled evidence.
+            // Any proof failure occurs before its SQLite transaction and widens to
+            // reconciliation; it must never poison a Watch generation in a timer
+            // rejection that only another filesystem event can revive.
+            const named = await this.namedDetect.detect(observations).catch(() => null);
+            if (named?.handled) {
+                for (const evidence of named.evidence) {
+                    const observation = observations.find((candidate) => candidate.directory === evidence.directory);
+                    this.options.onDetectScan?.({
+                        rootId: observation?.rootId ?? evidence.directory,
+                        directory: evidence.directory,
+                        scope: "paths",
+                        entries: evidence.metadataReads,
+                        metadataReused: evidence.paths - evidence.contentReads,
+                        contentReads: evidence.contentReads,
+                        gitInspections: evidence.gitInspections,
+                        repositoryCaptures: evidence.repositoryCaptures,
+                        durationMs: evidence.durationMs,
+                        plannedRows: evidence.plannedRows,
+                        records: evidence.records,
+                        journalBytes: evidence.journalBytes,
+                    });
+                }
+                this.watchHost.settle(observations);
+                return;
+            }
+        }
         let detection;
+        let acceptedMaterializedRows;
+        let materializedRemovals;
         let acceptedNotebookRows;
         let notebookRemovals;
         try {
-            const scanned = await scanAndRegister({
+            const scanned = await reconcileGround({
                 identity,
                 userRoot: this.userRoot(identity),
                 database: this.databasePath(identity),
@@ -728,8 +823,9 @@ export class UserGroundHost {
                 onScan: this.options.onDetectScan,
                 suspicions: new Map(observations.map((observation) => [observation.directory, observation.suspicion])),
             });
-            localRecords = [...scanned.records];
             detection = scanned.detection;
+            acceptedMaterializedRows = scanned.acceptedMaterializedRows;
+            materializedRemovals = scanned.materializedRemovals;
             acceptedNotebookRows = scanned.acceptedNotebookRows;
             notebookRemovals = scanned.notebookRemovals;
         }
@@ -743,45 +839,24 @@ export class UserGroundHost {
         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;
-        }
         commitDetectedState(this.databasePath(identity), {
+            acceptedMaterializedRows,
+            materializedRemovals,
             acceptedNotebookRows,
             notebookRemovals,
-            outbox: {
-                mutationId: randomUUID(),
-                resourceId: state.resourceId,
-                authorityEpoch: state.authorityEpoch,
-                baseVersion: state.headVersion,
-                snapshotChecksum: checksum,
-                snapshotJson: stableJson(snapshot),
-                detectedRecordsJson: stableJson(detectedRecords),
-            },
+            proposals: detectedRecords,
         });
-        await this.drainOutbox(identity);
+        this.namedDetect?.refreshEnrollmentPolicy();
         this.watchHost.settle(observations);
     }
-    async drainOutboxBeforeLookup(identity, resourceId) {
-        const pending = readOutbox(this.databasePath(identity));
+    async publishPendingSnapshotsBeforeLookup(identity, resourceId) {
+        const pending = readJournal(this.databasePath(identity))
+            .filter((entry) => entry.kind === "entity.snapshot.replace");
         if (pending.length === 0)
             return;
         const first = pending[0];
         if (first.resourceId !== resourceId) {
-            throw new Error("local cloud outbox belongs to a different user-ground resource");
+            throw new Error("local snapshot journal belongs to a different user-ground resource");
         }
         this.cloudState = {
             resourceId: first.resourceId,
@@ -790,10 +865,56 @@ export class UserGroundHost {
             checksum: "",
             records: snapshotFromRecords(JSON.parse(first.snapshotJson).records || []).records,
         };
-        await this.drainOutbox(identity);
+        await this.publishPendingSnapshots(identity);
+    }
+    /** Register is the deliberate cold graph-publication boundary. Ordinary
+     * Watch detection stops at a durable exact record and never rebuilds this
+     * resource snapshot. */
+    async publishMaterializedSnapshot(identity) {
+        const state = this.cloudState;
+        if (!state)
+            throw new Error("cloud state is unavailable for graph publication");
+        const notebook = readDetectionNotebook(this.databasePath(identity));
+        const localRecords = recordsRetainingMissingEvidence(portableRecords(this.databasePath(identity)), notebook.map(portableRecord));
+        const merged = mergeMaterializedRoots(state.records, localRecords);
+        const traveling = travelingRecords(merged);
+        const impossibleGitLeaf = traveling.find((record) => (record.type === "file.text" || record.type === "file.binary" || record.type === "link")
+            && record.payloadVersion?.startsWith("git:"));
+        if (impossibleGitLeaf) {
+            const parent = merged.find((record) => record.uuid === impossibleGitLeaf.parentUUID);
+            throw new Error(`repository-owned leaf escaped its rail: ${impossibleGitLeaf.name} parent=${parent?.type ?? "missing"}`);
+        }
+        const snapshot = snapshotFromRecords(traveling);
+        const snapshotJson = stableJson(snapshot);
+        const checksum = sha256Hex(snapshotJson);
+        if (checksum === state.checksum)
+            return;
+        const pending = readJournal(this.databasePath(identity))
+            .filter((entry) => entry.kind === "entity.snapshot.replace");
+        const identical = pending.find((entry) => entry.resourceId === state.resourceId
+            && entry.snapshotChecksum === checksum);
+        if (identical) {
+            await this.publishPendingSnapshots(identity);
+            return;
+        }
+        if (pending.length > 0) {
+            throw new Error("a different graph snapshot is already pending publication");
+        }
+        appendSnapshotJournal(this.databasePath(identity), {
+            kind: "entity.snapshot.replace",
+            mutationId: randomUUID(),
+            resourceId: state.resourceId,
+            authorityEpoch: state.authorityEpoch,
+            baseVersion: state.headVersion,
+            snapshotChecksum: checksum,
+            snapshotJson,
+        });
+        await this.publishPendingSnapshots(identity);
     }
-    async drainOutbox(identity) {
-        for (const pending of readOutbox(this.databasePath(identity))) {
+    async publishPendingSnapshots(identity) {
+        for (const pending of readJournal(this.databasePath(identity))) {
+            if (pending.kind !== "entity.snapshot.replace")
+                continue;
             const snapshot = snapshotFromRecords(JSON.parse(pending.snapshotJson).records || []);
             const locallyMaterializedIds = new Set(readRows(this.databasePath(identity))
                 .map((row) => row.uuid));
@@ -830,7 +951,7 @@ export class UserGroundHost {
                 checksum: pending.snapshotChecksum,
                 records: snapshot.records,
             };
-            deleteOutbox(this.databasePath(identity), pending.mutationId);
+            deleteJournalEntry(this.databasePath(identity), pending.mutationId);
         }
     }
 }
@@ -910,36 +1031,11 @@ function assertHealthyWatch(evidence, rootId) {
         throw new Error(`Watch coverage is not healthy for workspace ${rootId}: ${evidence.health.reason ?? "incomplete handle evidence"}`);
     }
 }
-function immutableWrite(file, bytes) {
-    ensurePrivateDir(dirname(file));
-    try {
-        writeFileSync(file, bytes, { mode: 0o600, flag: "wx" });
-    }
-    catch (error) {
-        if (error.code !== "EEXIST")
-            throw error;
-        if (!readFileSync(file).equals(Buffer.from(bytes)))
-            throw new Error(`immutable object conflict at ${file}`);
-    }
-}
-function immutableWriteArtifact(cacheDir, artifact, bytes) {
-    const manifest = deriveUploadManifest(artifact, bytes, sha256Hex);
-    immutableWrite(contentCacheFile(cacheDir, artifact.contentHash), bytes);
-    atomicWrite(manifestCacheFile(cacheDir, artifact.contentHash), stableJson(manifest));
-}
 function initializeDatabase(file) {
     ensurePrivateDir(dirname(file));
     const database = new Database(file);
     database.pragma("journal_mode = WAL");
-    database.pragma("synchronous = NORMAL");
-    const entityColumns = database.prepare("PRAGMA table_info(entities)").all();
-    if (entityColumns.length > 0
-        && (!entityColumns.some(({ name }) => name === "resource_id")
-            || !entityColumns.some(({ name }) => name === "root_uuid"))) {
-        // Entity rows are a derived local projection. The pre-multi-root table
-        // cannot represent the new invariant and is rebuilt from cloud/ground.
-        database.exec("DROP TABLE entities");
-    }
+    database.pragma("synchronous = FULL");
     database.exec(`
     CREATE TABLE IF NOT EXISTS ground_identity (
       singleton INTEGER PRIMARY KEY CHECK (singleton = 1),
@@ -990,15 +1086,12 @@ function initializeDatabase(file) {
       filesystem_mode INTEGER,
       content_verified_at_ms REAL
     );
-    CREATE TABLE IF NOT EXISTS cloud_outbox (
+    CREATE TABLE IF NOT EXISTS mutation_journal (
       sequence INTEGER PRIMARY KEY AUTOINCREMENT,
       mutation_id TEXT NOT NULL UNIQUE,
       resource_id TEXT NOT NULL,
-      authority_epoch INTEGER NOT NULL,
-      base_version INTEGER NOT NULL,
-      snapshot_checksum TEXT NOT NULL,
-      snapshot_json TEXT NOT NULL,
-      detected_records_json TEXT NOT NULL DEFAULT '[]',
+      operation_kind TEXT NOT NULL,
+      operation_json TEXT NOT NULL,
       created_at TEXT NOT NULL
     );
     CREATE TABLE IF NOT EXISTS workspace_add_intents (
@@ -1010,34 +1103,18 @@ 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 entities_by_parent_uuid
+      ON entities(parent_uuid);
+    CREATE INDEX IF NOT EXISTS entities_by_root_path
+      ON entities(root_uuid, relative_path);
     CREATE INDEX IF NOT EXISTS detection_notebook_by_root_path
-      ON detection_notebook(resource_id, root_uuid, relative_path);
+      ON detection_notebook(root_uuid, relative_path);
+    CREATE INDEX IF NOT EXISTS detection_notebook_by_absolute_path
+      ON detection_notebook(absolute_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));
-    const fingerprintColumns = [
-        ["byte_size", "INTEGER"],
-        ["modified_time_ms", "REAL"],
-        ["changed_time_ms", "REAL"],
-        ["filesystem_mode", "INTEGER"],
-        ["content_verified_at_ms", "REAL"],
-    ];
-    for (const [name, type] of fingerprintColumns) {
-        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
+    CREATE INDEX IF NOT EXISTS mutation_journal_by_kind
+      ON mutation_journal(operation_kind);
   `);
     return database;
 }
@@ -1195,18 +1272,52 @@ function findKnownEntityId(file, absolutePath, deviceNumber, inode) {
         database.close();
     }
 }
-function readOutbox(file) {
+function readJournal(file) {
     if (!existsSync(file))
         return [];
     const database = initializeDatabase(file);
     try {
         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,
-             detected_records_json AS detectedRecordsJson
-        FROM cloud_outbox ORDER BY sequence
-    `).all();
+             operation_kind AS kind, operation_json AS operationJson
+        FROM mutation_journal ORDER BY sequence
+    `).all().map((row) => {
+            const operation = decodeMutationOperation(row.operationJson);
+            if (row.kind === "entity.snapshot.replace") {
+                return {
+                    kind: row.kind,
+                    mutationId: row.mutationId,
+                    resourceId: row.resourceId,
+                    authorityEpoch: Number(operation.authorityEpoch),
+                    baseVersion: Number(operation.baseVersion),
+                    snapshotChecksum: String(operation.snapshotChecksum),
+                    snapshotJson: String(operation.snapshotJson),
+                };
+            }
+            if (row.kind === "detected.change") {
+                return {
+                    kind: row.kind,
+                    mutationId: row.mutationId,
+                    resourceId: row.resourceId,
+                    proposal: operation.proposal,
+                };
+            }
+            throw new Error(`unknown mutation journal operation: ${String(row.kind)}`);
+        });
+    }
+    finally {
+        database.close();
+    }
+}
+function hasDetectedChanges(file) {
+    if (!existsSync(file))
+        return false;
+    const database = initializeDatabase(file);
+    try {
+        return database.prepare(`
+      SELECT 1 AS present FROM mutation_journal
+       WHERE operation_kind = 'detected.change' LIMIT 1
+    `).get() !== undefined;
     }
     finally {
         database.close();
@@ -1214,20 +1325,28 @@ function readOutbox(file) {
 }
 /** 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 returns. The mutation journal is the one durable 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 append = database.prepare(`
+        INSERT INTO mutation_journal(
+          mutation_id, resource_id, operation_kind, operation_json, created_at
+        ) VALUES (?, ?, ?, ?, ?)
+      `);
+            for (const entry of input.proposals ?? []) {
+                const proposal = entry.proposal;
+                append.run(entry.mutationId, String(proposal.resourceId ?? ""), "detected.change", encodeMutationOperation({ proposal: entry.proposal }), new Date().toISOString());
             }
             const remove = database.prepare("DELETE FROM detection_notebook WHERE uuid = ?");
+            const removeMaterialized = database.prepare("DELETE FROM entities WHERE uuid = ?");
+            for (const uuid of input.materializedRemovals ?? [])
+                removeMaterialized.run(uuid);
+            const upsertMaterialized = prepareGroundUpsert(database, "entities");
+            for (const row of input.acceptedMaterializedRows ?? []) {
+                upsertMaterialized.run(...groundRowValues(row));
+            }
             for (const uuid of input.notebookRemovals)
                 remove.run(uuid);
             const upsertNotebook = prepareGroundUpsert(database, "detection_notebook");
@@ -1239,10 +1358,28 @@ function commitDetectedState(file, input) {
         database.close();
     }
 }
-function deleteOutbox(file, mutationId) {
+function appendSnapshotJournal(file, entry) {
+    const database = initializeDatabase(file);
+    try {
+        database.prepare(`
+      INSERT INTO mutation_journal(
+        mutation_id, resource_id, operation_kind, operation_json, created_at
+      ) VALUES (?, ?, ?, ?, ?)
+    `).run(entry.mutationId, entry.resourceId, entry.kind, stableJson({
+            authorityEpoch: entry.authorityEpoch,
+            baseVersion: entry.baseVersion,
+            snapshotChecksum: entry.snapshotChecksum,
+            snapshotJson: entry.snapshotJson,
+        }), new Date().toISOString());
+    }
+    finally {
+        database.close();
+    }
+}
+function deleteJournalEntry(file, mutationId) {
     const database = initializeDatabase(file);
     try {
-        database.prepare("DELETE FROM cloud_outbox WHERE mutation_id = ?").run(mutationId);
+        database.prepare("DELETE FROM mutation_journal WHERE mutation_id = ?").run(mutationId);
     }
     finally {
         database.close();
@@ -1536,10 +1673,12 @@ function materializedWorkspaceBindings(bindingDir) {
     }
     return bindings.sort((left, right) => left.workspaceId.localeCompare(right.workspaceId));
 }
-async function scanAndRegister(input) {
+async function reconcileGround(input) {
     const { identity, userRoot, database, cacheDir, suspicions, onScan } = input;
     const resourceId = privateEntityResourceId(identity.userId, sha256Hex);
     const materialized = readRows(database);
+    const materializedByUuid = new Map(materialized.map((row) => [row.uuid, row]));
+    const materializedUUIDs = new Set(materializedByUuid.keys());
     const notebook = readDetectionNotebook(database);
     const existing = suspicions ? notebook : materialized;
     const notebookByUuid = new Map(notebook.map((row) => [row.uuid, row]));
@@ -1568,6 +1707,8 @@ async function scanAndRegister(input) {
     const missingPortableReference = [...boundRoots.keys()]
         .some((workspaceId) => !existingReferenceIds.has(workspaceId));
     const acceptedRecords = [];
+    const acceptedMaterializedRows = [];
+    const materializedRemovals = new Set();
     const acceptedNotebookRows = [];
     const notebookRemovals = new Set();
     const detection = [];
@@ -1580,23 +1721,33 @@ async function scanAndRegister(input) {
             repositoryCaptures: 0,
         };
         const started = performance.now();
-        const result = await scanRoot({ ...parameters, evidence: counters });
+        const result = await reconcileRoot({ ...parameters, evidence: counters, materializedUUIDs });
         if (result.detection)
             detection.push(result.detection);
         for (const uuid of result.notebookRemovals) {
             notebookRemovals.add(uuid);
             notebookByUuid.delete(uuid);
         }
-        if (result.transferable) {
-            acceptedRecords.push(...result.records);
-            for (const row of result.rows) {
-                const captured = capturedGroundRow(parameters.resourceId, parameters.rootUUID, row);
+        const currentIds = new Set(result.rows.map((row) => row.record.uuid));
+        for (const prior of materialized.filter((row) => row.resourceId === parameters.resourceId && row.rootUUID === parameters.rootUUID)) {
+            if (!currentIds.has(prior.uuid))
+                materializedRemovals.add(prior.uuid);
+        }
+        for (const row of result.rows) {
+            const captured = capturedGroundRow(parameters.resourceId, parameters.rootUUID, row);
+            if (!sameGroundRow(captured, materializedByUuid.get(captured.uuid))) {
+                acceptedMaterializedRows.push(captured);
+            }
+            if (result.transferable) {
                 if (sameGroundRow(captured, notebookByUuid.get(captured.uuid)))
                     continue;
                 acceptedNotebookRows.push(captured);
                 notebookByUuid.set(captured.uuid, captured);
             }
         }
+        if (result.transferable)
+            acceptedRecords.push(...result.records);
+        const proposals = result.detection?.kind === "ready" ? result.detection.proposals : [];
         onScan?.({
             rootId: parameters.rootUUID,
             directory: parameters.rootPath,
@@ -1605,6 +1756,9 @@ async function scanAndRegister(input) {
                 : parameters.suspects.length === 0 ? "none" : "paths",
             ...counters,
             durationMs: performance.now() - started,
+            plannedRows: proposals.length,
+            records: proposals.length,
+            journalBytes: proposals.reduce((bytes, proposal) => bytes + Buffer.byteLength(encodeMutationOperation({ proposal })), 0),
         });
         // Each root commits its local projection before Detect yields. Native
         // callbacks can therefore preserve new suspicion between large roots.
@@ -1654,12 +1808,21 @@ async function scanAndRegister(input) {
     return {
         records: acceptedRecords,
         detection,
+        acceptedMaterializedRows,
+        materializedRemovals: [...materializedRemovals],
         acceptedNotebookRows,
         notebookRemovals: [...notebookRemovals],
     };
 }
-async function scanRoot(input) {
+async function reconcileRoot(input) {
     const { identity, resourceId, rootUUID, rootName, rootPath, rootType, database, cacheDir, policy, bindingDir, suspects = null, evidence, } = input;
+    const scanSuspects = suspects !== null && rootType === "repo.git"
+        ? [...new Set(suspects.map((path) => {
+                const segments = path.split("/");
+                const marker = segments.indexOf(".git");
+                return marker < 0 ? path : segments.slice(0, marker).join("/");
+            }))].sort()
+        : suspects;
     const existingRows = input.existingRows
         ?? readRows(database).filter((row) => row.resourceId === resourceId && row.rootUUID === rootUUID);
     const existingByPath = new Map(existingRows.flatMap((row) => {
@@ -1709,6 +1872,32 @@ async function scanRoot(input) {
     const priorRootType = existingByPath.get("")?.type;
     const rootRailChanged = priorRootType !== undefined && priorRootType !== rootType;
     evidence && (evidence.entries += 1);
+    if (scanSuspects !== null && rootType === "repo.git") {
+        for (const row of existingRows) {
+            if (row.relativePath === "")
+                continue;
+            if (scanSuspects.some((path) => path !== ""
+                && (row.relativePath === path || row.relativePath.startsWith(`${path}/`))))
+                continue;
+            entries.push({
+                uuid: row.uuid,
+                type: row.type,
+                parentUUID: row.parentUUID,
+                name: row.name,
+                relativePath: row.relativePath,
+                absolutePath: row.absolutePath,
+                payloadVersion: row.payloadVersion,
+                transportVersion: row.transportVersion,
+                deviceNumber: row.deviceNumber,
+                inode: row.inode,
+                byteSize: row.byteSize,
+                modifiedTimeMs: row.modifiedTimeMs,
+                changedTimeMs: row.changedTimeMs,
+                filesystemMode: row.filesystemMode,
+                contentVerifiedAtMs: row.contentVerifiedAtMs,
+            });
+        }
+    }
     entries.push({
         uuid: rootUUID,
         fixedUUID: rootUUID,
@@ -1722,15 +1911,15 @@ async function scanRoot(input) {
         contentVerifiedAtMs: null,
         ...statFingerprint(rootStats),
     });
-    const touchesSuspicion = (path) => suspects === null
-        || pathIsSuspect(path, suspects)
-        || suspects.some((suspect) => suspect.startsWith(`${path}/`));
+    const touchesSuspicion = (path) => scanSuspects === null
+        || pathIsSuspect(path, scanSuspects)
+        || scanSuspects.some((suspect) => suspect.startsWith(`${path}/`));
     const repositoryEvidencePaths = (repository) => {
-        if (suspects === null)
+        if (scanSuspects === null)
             return null;
         const prefix = slashPath(relative(rootPath, repository));
         const paths = [];
-        for (const suspect of suspects) {
+        for (const suspect of scanSuspects) {
             if (suspect === prefix || (prefix && prefix.startsWith(`${suspect}/`)))
                 return null;
             const local = prefix
@@ -1755,6 +1944,9 @@ async function scanRoot(input) {
             if (isRepositoryMetadataEntry(parentType, child.name))
                 continue;
             const relativePath = base ? `${base}/${child.name}` : child.name;
+            if (scanSuspects !== null && rootType === "repo.git"
+                && !forceObserve && !touchesSuspicion(relativePath))
+                continue;
             if (!policy(relativePath))
                 continue;
             const absolutePath = join(directory, child.name);
@@ -1768,12 +1960,12 @@ async function scanRoot(input) {
                 throw new Error(`registered boundary ${absolutePath} conflicts with entity ${existing.uuid}`);
             }
             const uuid = registeredBoundaryId || existing?.uuid || randomUUID();
-            const stableDuringCompleteCatchUp = suspects === null
+            const stableDuringCompleteCatchUp = scanSuspects === null
                 && existing !== undefined
                 && reusableDuringCompleteCatchUp(existing, stats);
             const observe = forceObserve || existing === undefined
-                || (suspects === null ? !stableDuringCompleteCatchUp : touchesSuspicion(relativePath));
-            if (!observe && suspects === null)
+                || (scanSuspects === null ? !stableDuringCompleteCatchUp : touchesSuspicion(relativePath));
+            if (!observe && scanSuspects === null)
                 evidence && (evidence.metadataReused += 1);
             const repositoryPath = activeRepository
                 ? slashPath(relative(activeRepository.root, absolutePath))
@@ -1822,7 +2014,7 @@ async function scanRoot(input) {
                         const bytes = Buffer.from(linkTarget, "utf8");
                         payloadVersion = sha256Hex(bytes);
                         if (!activeRepository)
-                            immutableWriteArtifact(cacheDir, {
+                            sealCapturedArtifact(cacheDir, {
                                 entityId: uuid,
                                 entityType: type,
                                 kind: "link",
@@ -1884,6 +2076,7 @@ async function scanRoot(input) {
         relativePath: row.relativePath,
         deviceNumber: row.deviceNumber,
         inode: row.inode,
+        physicalContinuity: input.materializedUUIDs?.has(row.uuid) ?? true,
     })), entries.map((entry) => ({
         key: entry.relativePath,
         type: entry.type,
@@ -1946,12 +2139,15 @@ async function scanRoot(input) {
     });
     const persistCurrentRows = () => {
         const rows = rowsFromEntries();
-        persistRows(database, identity, resourceId, rootUUID, rows, existingRows, {
-            updateNotebook: input.suspicion === undefined,
-        });
+        if (input.suspicion === undefined) {
+            persistRows(database, identity, resourceId, rootUUID, rows, existingRows);
+        }
         return rows;
     };
-    const repositories = entries.filter((entry) => entry.type === "repo.git");
+    // Nested repository state is an input to its enclosing identity map. Seal
+    // children first so one capture pass is already the fixed point.
+    const repositories = entries.filter((entry) => entry.type === "repo.git")
+        .sort((left, right) => right.relativePath.length - left.relativePath.length);
     const replayByUuid = new Map();
     const properDescendantOf = (candidate, ancestor) => ancestor === "" ? candidate !== "" : candidate.startsWith(`${ancestor}/`);
     const repositoryOwner = (entry) => repositories
@@ -2027,7 +2223,7 @@ async function scanRoot(input) {
             repository.payloadVersion = captured.stateId;
             repository.transportVersion = captured.transportVersion;
             if (captured.bytes) {
-                immutableWriteArtifact(cacheDir, {
+                sealCapturedArtifact(cacheDir, {
                     entityId: repository.uuid,
                     entityType: "repo.git",
                     kind: "git",
@@ -2050,7 +2246,7 @@ async function scanRoot(input) {
     catch {
         // Type and identity are filesystem facts, so they settle locally even
         // when the selected repository rail cannot yet capture its artifact.
-        // Cloud publication remains commit-last because scanAndRegister omits the
+        // Cloud publication remains commit-last because reconciliation omits the
         // complete materialized root until every repository parcel is capturable.
         // Git unavailability is local to this root; Watch and unrelated roots stay
         // live and the next suspicion or resume retries the same ordinary scan.
@@ -2064,15 +2260,58 @@ async function scanRoot(input) {
             detection: null,
         };
     }
-    const rows = persistCurrentRows();
+    let rows = persistCurrentRows();
     const currentUUIDs = new Set(rows.map((row) => row.record.uuid));
+    const retainedMissingRows = input.suspicion === undefined ? [] : existingRows
+        .filter((row) => !currentUUIDs.has(row.uuid) && !existsSync(row.absolutePath));
+    if (retainedMissingRows.length > 0) {
+        // Missing ground changes this machine's materialization evidence, not the
+        // portable entity graph. Keep those identities in the logical membership
+        // used by Record while still removing their materialized SQLite rows.
+        const logicalRecords = [
+            ...rows.map((row) => row.record),
+            ...retainedMissingRows.map(portableRecord),
+        ];
+        const logicalChildren = new Map();
+        for (const record of logicalRecords) {
+            if (record.parentUUID === null || record.status !== "active")
+                continue;
+            const group = logicalChildren.get(record.parentUUID) ?? [];
+            group.push({ uuid: record.uuid, name: record.name });
+            logicalChildren.set(record.parentUUID, group);
+        }
+        rows = rows.map((row) => {
+            if (row.record.type !== "workspace" && row.record.type !== "folder")
+                return row;
+            const version = canonicalVersion({
+                type: row.record.type,
+                parentUUID: row.record.parentUUID,
+                name: row.record.name,
+                status: row.record.status,
+                payloadVersion: membershipHash(logicalChildren.get(row.record.uuid) ?? [], sha256Hex),
+            }, sha256Hex);
+            return version === row.record.version ? row : {
+                ...row,
+                record: { ...row.record, version },
+            };
+        });
+    }
     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 entryByUuid = new Map(entries.map((entry) => [entry.uuid, entry]));
     const detected = rows.map((row) => {
         const base = beforeByUuid.get(row.record.uuid) ?? null;
+        const entry = entryByUuid.get(row.record.uuid);
+        if (row.record.type !== "repo.git" && entry && repositoryOwner(entry)) {
+            return {
+                record: row.record,
+                relativePath: row.relativePath,
+                replay: { kind: "structure" },
+            };
+        }
         const contentChanged = base === null
             || base.type !== row.record.type
             || base.payloadVersion !== row.record.payloadVersion
@@ -2083,15 +2322,25 @@ async function scanRoot(input) {
                 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,
-                    };
+                    {
+                        const resultBytes = readFileSync(contentCacheFile(cacheDir, row.record.payloadVersion));
+                        const baseBytes = base?.payloadVersion
+                            && /^[0-9a-f]{64}$/.test(base.payloadVersion)
+                            && existsSync(contentCacheFile(cacheDir, base.payloadVersion))
+                            ? readFileSync(contentCacheFile(cacheDir, base.payloadVersion))
+                            : null;
+                        replay = exactTextReplay({
+                            entityId: row.record.uuid,
+                            basePayloadVersion: base?.payloadVersion
+                                && /^[0-9a-f]{64}$/.test(base.payloadVersion)
+                                ? base.payloadVersion
+                                : null,
+                            baseBytes,
+                            resultPayloadVersion: row.record.payloadVersion,
+                            resultBytes,
+                            sha256Hex,
+                        });
+                    }
                     break;
                 case "file.binary": {
                     if (!row.record.payloadVersion)
@@ -2131,9 +2380,19 @@ async function scanRoot(input) {
             }
         }
         return { record: row.record, relativePath: row.relativePath, replay };
-    });
+    }).concat(retainedMissingRows.map((row) => ({
+        record: portableRecord(row),
+        relativePath: row.relativePath,
+        replay: { kind: "structure" },
+    })));
+    const plannedBefore = rootType === "repo.git"
+        ? before.filter((record) => record.type === "repo.git")
+        : before;
+    const plannedAfter = rootType === "repo.git"
+        ? detected.filter(({ record }) => record.type === "repo.git")
+        : detected;
     return {
-        records: rows.map((row) => row.record),
+        records: [...rows.map((row) => row.record), ...retainedMissingRows.map(portableRecord)],
         rows,
         referenceWorkspaceIds: [...referenceWorkspaceIds],
         transferable: true,
@@ -2141,8 +2400,8 @@ async function scanRoot(input) {
         detection: input.suspicion ? planGroundDetection({
             rootId: rootUUID,
             suspicion: input.suspicion,
-            before,
-            after: detected,
+            before: plannedBefore,
+            after: plannedAfter,
         }) : null,
     };
 }