@amalgm/shell 0.1.53 → 0.1.55

package/dist/user-ground-host.js

@@ -3,16 +3,18 @@ import { existsSync, lstatSync, realpathSync, readFileSync, readdirSync, readlin
 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, acceptOutboxRow, canonicalVersion, checkContentManifest, classifyDirectory, classifyFile, classifyRegisteredRoot, createLocalEntityRecord, convergeUserGround, createUserGroundEnrollmentPolicy, isRepositoryMetadataEntry, download as downloadArtifact, decodeAcceptedEntityRecord, decodeLocalEntityRecord, encodeEntityRecord, membershipHash, parseSnapshot, pathIsSuspect, privateEntityResourceId, nextEntitySends, receiveEntityRecord, 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, createLocalEntityRecord, createEntityRecordAuthorityPort, convergeUserGround, createUserGroundEnrollmentPolicy, isRepositoryMetadataEntry, download as downloadArtifact, encodeEntityRecord, EntityApplyRail, EntityRecordRail, 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 { EntityApplyHost } from "./entity-apply-host.js";
+import { EntityRecordSqliteStore } from "./entity-record-store.js";
 import { ContentCacheDownload, captureContentFile, hashContentFile, sealCapturedArtifact, } from "./content-cache-host.js";
 import { decodeContentWireBytes, encodeContentWireBytes } from "./content-wire-codec.js";
 import { exactTextReplay, planGroundDetection, reconcileGroundUUIDs, } from "./detection/portable.js";
 import { NamedDetectRuntime } from "./detection/runtime.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 { canonicalizeGitIdentity, inspectGitRegistration, sameGitIdentity, } from "./git-registration-host.js";
 import { projectMaterializedGraph } from "./materialized-graph.js";
 import { NodeWatchHost, } from "./watching/index.js";
 import { WireClient, WireRequestError } from "./wire-client.js";
@@ -22,9 +24,6 @@ const FILE_BATCH_DOWNLOAD_CONCURRENCY = 2;
 const DETECT_QUIET_MS = 12;
 const DETECT_MAX_DEFERRAL_MS = 75;
 const DETECT_RETRY_MS = 250;
-const RECORD_RETRY_MS = 1_000;
-const RECORD_POLL_MS = 1_000;
-const RECORD_TAIL_LIMIT = 256;
 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",
@@ -44,12 +43,14 @@ export class UserGroundHost {
     cloudState = null;
     converged = false;
     syncing = null;
-    recordSyncing = null;
-    recordSyncTimer = null;
-    recordSyncStopped = false;
+    recordRail = null;
+    recordStore = null;
+    applyRail = null;
+    applyHost = null;
     namedDetect = null;
     coldOperation = false;
     closing = false;
+    groundEffectTail = Promise.resolve();
     port;
     constructor(options) {
         this.options = options;
@@ -90,8 +91,9 @@ export class UserGroundHost {
                     watcherRoots: watchHealth.contentHandles,
                     watching: true,
                 };
+                await this.startRecordRail(this.activeIdentity);
+                await this.startApplyRail(this.activeIdentity);
                 this.converged = true;
-                this.scheduleRecordSync();
                 return evidence;
             },
         };
@@ -151,26 +153,38 @@ export class UserGroundHost {
                 return cloud;
             },
             materializeWorkspace: async (input) => {
-                const installed = await installCloudWorkspace({
-                    identity,
-                    userRoot,
-                    database: this.databasePath(identity),
-                    cacheDir: this.cacheDir(identity),
-                    bindingDir,
-                    resourceId: privateEntityResourceId(identity.userId, sha256Hex),
-                    workspace: input.workspace,
-                    reference: input.reference,
-                    references: input.references,
-                    records: input.records,
-                    destinationParent: input.destinationParent,
-                    cloudHead: input.cloudHead,
-                    readContent: (artifact) => this.downloadContent(privateEntityResourceId(identity.userId, sha256Hex), this.cacheDir(identity), artifact),
-                    onStage: (stage) => this.options.onWorkspaceAddStage?.({
-                        workspaceId: input.workspace.uuid,
-                        stage,
-                    }),
-                });
-                return installed;
+                const release = await this.acquireGroundEffect();
+                try {
+                    const installed = await installCloudWorkspace({
+                        identity,
+                        userRoot,
+                        database: this.databasePath(identity),
+                        cacheDir: this.cacheDir(identity),
+                        bindingDir,
+                        resourceId: privateEntityResourceId(identity.userId, sha256Hex),
+                        workspace: input.workspace,
+                        reference: input.reference,
+                        references: input.references,
+                        records: input.records,
+                        destinationParent: input.destinationParent,
+                        cloudHead: input.cloudHead,
+                        readContent: (artifact) => this.downloadContent(privateEntityResourceId(identity.userId, sha256Hex), this.cacheDir(identity), artifact),
+                        onStage: (stage) => this.options.onWorkspaceAddStage?.({
+                            workspaceId: input.workspace.uuid,
+                            stage,
+                        }),
+                    });
+                    // Add changes both disk and the exact SQLite projection. Open the
+                    // selected root's singular Watch coverage before Detect can observe
+                    // either side of that transaction; the public cover port below
+                    // independently proves the same coverage before clearing intent.
+                    this.ensureWatchers(identity, installed.alreadyMaterialized ? [] : [input.workspace.uuid]);
+                    assertHealthyWatch(this.watchHost.evidence(), input.workspace.uuid);
+                    return installed;
+                }
+                finally {
+                    release();
+                }
             },
             coverWorkspace: async ({ workspaceId, baseline }) => {
                 const pending = readWorkspaceAddIntent(this.databasePath(identity), workspaceId);
@@ -192,37 +206,43 @@ export class UserGroundHost {
         const userRoot = this.userRoot(identity);
         const bindingDir = workspaceBindingDir(userRoot, identity.deviceId);
         for (const intent of readWorkspaceAddIntents(database)) {
-            const selection = workspaceAddSelection(intent);
+            const release = await this.acquireGroundEffect();
             const visibleAcrossBlindInterval = pathExists(intent.destinationPath);
-            const stagedAcrossBlindInterval = pathExists(intent.stagingPath);
-            if (stagedAcrossBlindInterval && readRows(database).some((row) => row.resourceId === intent.resourceId && row.rootUUID === intent.workspaceId)) {
-                // Rows prove that staging was verified before the crash, not that its
-                // bytes remained unchanged while no watcher existed. Return this
-                // private install to the intent-only stage and reproduce it from the
-                // verified immutable cache before making it visible.
-                deleteRootRows(database, intent.resourceId, intent.workspaceId);
+            try {
+                const selection = workspaceAddSelection(intent);
+                const stagedAcrossBlindInterval = pathExists(intent.stagingPath);
+                if (stagedAcrossBlindInterval && readRows(database).some((row) => row.resourceId === intent.resourceId && row.rootUUID === intent.workspaceId)) {
+                    // Rows prove that staging was verified before the crash, not that its
+                    // bytes remained unchanged while no watcher existed. Return this
+                    // private install to the intent-only stage and reproduce it from the
+                    // verified immutable cache before making it visible.
+                    deleteRootRows(database, intent.resourceId, intent.workspaceId);
+                }
+                await installCloudWorkspace({
+                    identity,
+                    userRoot,
+                    database,
+                    cacheDir: this.cacheDir(identity),
+                    bindingDir,
+                    resourceId: intent.resourceId,
+                    workspace: selection.workspace,
+                    reference: selection.reference,
+                    references: intent.references,
+                    records: intent.records,
+                    destinationParent: dirname(intent.destinationPath),
+                    cloudHead: intent.cloudHead,
+                    readContent: (artifact) => this.downloadContent(intent.resourceId, this.cacheDir(identity), artifact),
+                    onStage: (stage) => this.options.onWorkspaceAddStage?.({
+                        workspaceId: intent.workspaceId,
+                        stage,
+                    }),
+                });
+                this.ensureWatchers(identity, visibleAcrossBlindInterval ? [] : [intent.workspaceId]);
+                assertHealthyWatch(this.watchHost.evidence(), intent.workspaceId);
+            }
+            finally {
+                release();
             }
-            await installCloudWorkspace({
-                identity,
-                userRoot,
-                database,
-                cacheDir: this.cacheDir(identity),
-                bindingDir,
-                resourceId: intent.resourceId,
-                workspace: selection.workspace,
-                reference: selection.reference,
-                references: intent.references,
-                records: intent.records,
-                destinationParent: dirname(intent.destinationPath),
-                cloudHead: intent.cloudHead,
-                readContent: (artifact) => this.downloadContent(intent.resourceId, this.cacheDir(identity), artifact),
-                onStage: (stage) => this.options.onWorkspaceAddStage?.({
-                    workspaceId: intent.workspaceId,
-                    stage,
-                }),
-            });
-            this.ensureWatchers(identity, visibleAcrossBlindInterval ? [] : [intent.workspaceId]);
-            assertHealthyWatch(this.watchHost.evidence(), intent.workspaceId);
             if (visibleAcrossBlindInterval) {
                 // Ground that was visible while the runtime was absent may have been
                 // edited after its verified reveal. It is an ordinary startup blind
@@ -261,8 +281,12 @@ export class UserGroundHost {
             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)) {
+        const hasRegisteredBoundary = (records) => records.some((record) => record.uuid === workspaceId && record.status === "active")
+            && records.some((record) => record.type === "reference"
+                && record.status === "active"
+                && record.payloadVersion === workspaceId);
+        if (hasRegisteredBoundary(rows.map(portableRecord))
+            && hasRegisteredBoundary(this.cloudState.records)) {
             this.finishColdOperation();
             return {
                 registered: true,
@@ -274,11 +298,13 @@ export class UserGroundHost {
         // 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;
+        let releaseGround = null;
         try {
             if (this.syncing)
                 await this.syncing;
+            releaseGround = await this.acquireGroundEffect();
+            const observations = this.watchHost.observations();
+            this.watchDirty = false;
             const scanned = await reconcileGround({
                 identity,
                 userRoot: this.userRoot(identity),
@@ -309,6 +335,7 @@ export class UserGroundHost {
             throw stageError("entity registration or cloud publication", error);
         }
         finally {
+            releaseGround?.();
             this.finishColdOperation();
         }
         try {
@@ -320,11 +347,11 @@ export class UserGroundHost {
             throw stageError("Watch coverage", error);
         }
         rows = readRows(this.databasePath(identity));
-        if (!rows.some((row) => row.uuid === workspaceId)) {
-            throw stageError("entity registration", new Error(`workspace ${workspaceId} was not recorded`));
+        if (!hasRegisteredBoundary(rows.map(portableRecord))) {
+            throw stageError("entity registration", new Error(`workspace ${workspaceId} and its durable reference were not recorded`));
         }
-        if (!this.cloudState.records.some((record) => record.uuid === workspaceId)) {
-            throw stageError("cloud graph commit", new Error(`workspace ${workspaceId} is absent from the committed head`));
+        if (!hasRegisteredBoundary(this.cloudState.records)) {
+            throw stageError("cloud graph commit", new Error(`workspace ${workspaceId} or its durable reference is absent from the committed head`));
         }
         return {
             registered: true,
@@ -359,7 +386,8 @@ export class UserGroundHost {
                     throw error;
             }
         } while (!this.watchHost.settled(cutoff));
-        await this.syncRecordsNow();
+        await this.recordRail?.flush();
+        await this.applyRail?.flush();
         if (!this.closing)
             this.ensureWatchers(identity);
     }
@@ -383,31 +411,108 @@ export class UserGroundHost {
         if (this.syncing)
             await this.syncing;
     }
-    scheduleRecordSync(delay = 0) {
-        if (this.closing || this.recordSyncStopped || this.recordSyncTimer)
-            return;
-        this.recordSyncTimer = setTimeout(() => {
-            this.recordSyncTimer = null;
-            void this.syncRecordsNow().then(() => {
-                if (!this.closing && !this.recordSyncStopped)
-                    this.scheduleRecordSync(RECORD_POLL_MS);
-            }).catch(() => {
-                if (!this.closing && !this.recordSyncStopped)
-                    this.scheduleRecordSync(RECORD_RETRY_MS);
-            });
-        }, delay);
-        this.recordSyncTimer.unref();
+    async startRecordRail(identity) {
+        if (!this.cloudState)
+            throw new Error("entity Record rail requires cloud authority");
+        if (this.recordRail || this.recordStore)
+            throw new Error("entity Record rail already started");
+        await this.wire.open();
+        if (this.wire.protocolVersion < 4) {
+            throw new Error("gateway does not support the event-driven entity Record wire");
+        }
+        const store = new EntityRecordSqliteStore(initializeDatabase(this.databasePath(identity)));
+        const authority = createEntityRecordAuthorityPort({
+            request: (frame, acceptedTypes) => this.wire.request({ ...frame }, acceptedTypes),
+            onFrame: (listener) => this.wire.onEvent(listener),
+            onDisconnect: (listener) => this.wire.onDisconnect(listener),
+        });
+        const rail = new EntityRecordRail({
+            authorityId: this.cloudState.resourceId,
+            store,
+            authority,
+            cargo: {
+                ensure: (record) => this.uploadSnapshotContent(identity, record.authorityId, [record.change.result]),
+            },
+            schedule: {
+                schedule(delayMs, callback) {
+                    const timer = setTimeout(callback, delayMs);
+                    timer.unref();
+                    return { cancel: () => clearTimeout(timer) };
+                },
+                random: Math.random,
+            },
+            onInboxCommitted: () => this.applyRail?.recordsAvailable(),
+        });
+        this.recordStore = store;
+        this.recordRail = rail;
+        try {
+            await rail.start();
+        }
+        catch (error) {
+            const stopping = rail.stop();
+            await this.wire.close();
+            await stopping;
+            store.close();
+            this.recordRail = null;
+            this.recordStore = null;
+            throw pipelineStageError("entity record subscribe", error);
+        }
     }
-    async syncRecordsNow() {
-        const identity = this.activeIdentity;
-        if (this.recordSyncStopped || !identity || !this.cloudState)
-            return;
-        if (!this.recordSyncing) {
-            this.recordSyncing = this.syncRecordQueues(identity).finally(() => {
-                this.recordSyncing = null;
-            });
+    async startApplyRail(identity) {
+        if (!this.cloudState)
+            throw new Error("entity Apply rail requires cloud authority");
+        if (this.applyRail || this.applyHost)
+            throw new Error("entity Apply rail already started");
+        let host;
+        host = new EntityApplyHost({
+            databaseFile: this.databasePath(identity),
+            userRoot: this.userRoot(identity),
+            cacheDir: this.cacheDir(identity),
+            bindingDir: workspaceBindingDir(this.userRoot(identity), identity.deviceId),
+            readContent: (artifact) => this.downloadContent(this.cloudState.resourceId, this.cacheDir(identity), artifact),
+            captureLocal: async (intent, plan, position) => {
+                // Apply never suppresses Watch. This explicit whole-root suspicion is
+                // the synchronous proof boundary used only when Apply observed a
+                // save racing its reveal and must make that save durable first.
+                this.watchHost.suspectAll();
+                this.watchDirty = true;
+                await this.syncNow();
+                if (!host.store.hasLocalWorkAfter(intent.authorityId, intent.entityId, intent.throughSequence)) {
+                    throw new Error(`Apply ${position} capture for ${plan.target.type} ${plan.target.name} (${intent.entityId}) produced no durable local record`);
+                }
+            },
+            acquireGround: () => this.acquireGroundEffect(),
+        });
+        const rail = new EntityApplyRail({
+            store: host.store,
+            effects: host.effects,
+            schedule: {
+                schedule(delayMs, callback) {
+                    const timer = setTimeout(callback, delayMs);
+                    timer.unref();
+                    return { cancel: () => clearTimeout(timer) };
+                },
+                random: Math.random,
+            },
+            sha256Hex,
+            now: Date.now,
+            // Path cones and repository territories are wider than one UUID. Until
+            // the host exposes those locks, one serial machine-effect owner is the
+            // only honest concurrency setting.
+            concurrency: 1,
+        });
+        this.applyHost = host;
+        this.applyRail = rail;
+        try {
+            await rail.start();
+        }
+        catch (error) {
+            await rail.stop();
+            host.close();
+            this.applyRail = null;
+            this.applyHost = null;
+            throw pipelineStageError("entity Apply resume", error);
         }
-        await this.recordSyncing;
     }
     async activateRuntimeTunnel(gatewayPort, runtimeToken) {
         // Files convergence and Watch/Detect own ground currency. Advertising an
@@ -416,30 +521,41 @@ export class UserGroundHost {
     }
     async stopRuntimeTunnel() {
         this.wire.configureRuntime({});
-        await this.wire.close();
     }
     async close(options = {}) {
         if (options.catchUp === false) {
             this.closing = true;
-            this.recordSyncStopped = true;
             if (this.rescanTimer)
                 clearTimeout(this.rescanTimer);
             this.rescanTimer = null;
             this.rescanGenerationStartedAt = null;
-            if (this.recordSyncTimer)
-                clearTimeout(this.recordSyncTimer);
-            this.recordSyncTimer = null;
             this.watchHost.close({ catchUp: false });
             this.namedDetect?.close();
             this.namedDetect = null;
+            const applyStopped = this.applyRail?.stop();
+            const recordStopped = this.recordRail?.stop();
             await this.wire.close();
-            await this.recordSyncing?.catch(() => undefined);
+            await applyStopped;
+            await recordStopped;
             // An upload already inside its retry helper may have reopened the wire
-            // after the first close. The stopped flag prevents new queue work; this
+            // after the first close. The stopped rail prevents new queue work; this
             // second close seals that finite in-flight boundary.
             await this.wire.close();
+            this.recordStore?.close();
+            this.recordStore = null;
+            this.recordRail = null;
+            this.applyHost?.close();
+            this.applyHost = null;
+            this.applyRail = null;
             return;
         }
+        await this.recordRail?.flush();
+        await this.applyRail?.flush();
+        const applyStopped = this.applyRail?.stop();
+        await applyStopped;
+        this.applyHost?.close();
+        this.applyHost = null;
+        this.applyRail = null;
         // Command shutdown is the last catch-up boundary. A filesystem callback
         // may still be queued, so watcher silence cannot be used as evidence yet.
         this.watchHost.suspectAll();
@@ -449,20 +565,21 @@ export class UserGroundHost {
             clearTimeout(this.rescanTimer);
         this.rescanTimer = null;
         this.rescanGenerationStartedAt = null;
-        if (this.recordSyncTimer)
-            clearTimeout(this.recordSyncTimer);
-        this.recordSyncTimer = 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();
-        await this.syncRecordsNow();
-        this.recordSyncStopped = true;
+        await this.recordRail?.flush();
         this.namedDetect?.close();
         this.namedDetect = null;
+        const recordStopped = this.recordRail?.stop();
         await this.wire.close();
+        await recordStopped;
+        this.recordStore?.close();
+        this.recordStore = null;
+        this.recordRail = null;
     }
     userRoot(identity) {
         return resolve(scopedAmalgmDir(this.options.amalgmRoot, identity.userEmail));
@@ -781,6 +898,9 @@ export class UserGroundHost {
                 rootId: workspaceId,
                 directory,
                 materialized: true,
+                // Every materialized root has one reserved machine-control subtree.
+                // Apply stages and retains recovery bytes here; Watch never enrolls it.
+                excludedSubtrees: [join(directory, ".amalgm")],
             });
         }
         const health = this.watchHost.reconcile([...wanted.values()], {
@@ -839,7 +959,24 @@ export class UserGroundHost {
             this.scheduleRescan();
         }
     }
+    async acquireGroundEffect() {
+        let release;
+        const held = new Promise((resolve) => { release = resolve; });
+        const preceding = this.groundEffectTail;
+        this.groundEffectTail = preceding.then(() => held);
+        await preceding;
+        return release;
+    }
     async syncLocalChanges(identity) {
+        const release = await this.acquireGroundEffect();
+        try {
+            await this.syncLocalChangesUnlocked(identity);
+        }
+        finally {
+            release();
+        }
+    }
+    async syncLocalChangesUnlocked(identity) {
         if (!this.cloudState)
             throw new Error("cloud state is unavailable for user-ground Watch");
         const observations = this.watchHost.observations();
@@ -868,7 +1005,8 @@ export class UserGroundHost {
                     });
                 }
                 this.watchHost.settle(observations);
-                this.scheduleRecordSync();
+                this.applyRail?.localStateChanged();
+                this.recordRail?.localRecordsAvailable();
                 return;
             }
         }
@@ -900,7 +1038,7 @@ export class UserGroundHost {
             throw pipelineStageError("detection", new Error(retry.reasons.join("; ")));
         }
         const authorityId = this.cloudState.resourceId;
-        const received = readEntityReceiveCursors(this.databasePath(identity), authorityId);
+        const received = this.recordStore?.readEntityCursors(authorityId) ?? new Map();
         const detectedRecords = detection.flatMap((plan) => plan.kind === "ready"
             ? plan.proposals.map((proposal) => ({
                 mutationId: randomUUID(),
@@ -918,91 +1056,8 @@ export class UserGroundHost {
         });
         this.namedDetect?.refreshEnrollmentPolicy();
         this.watchHost.settle(observations);
-        this.scheduleRecordSync();
-    }
-    async syncRecordQueues(identity) {
-        if (this.recordSyncStopped)
-            return;
-        await this.receiveAcceptedRecords();
-        while (!this.recordSyncStopped) {
-            const selected = nextEntitySends(readOutbox(this.databasePath(identity)));
-            if (selected.length === 0)
-                break;
-            const sent = await Promise.allSettled(selected.map(async (row) => {
-                if (this.recordSyncStopped)
-                    return;
-                await this.uploadSnapshotContent(identity, row.record.authorityId, [row.record.change.result]);
-                if (this.recordSyncStopped)
-                    return;
-                const frame = await this.wire.request({
-                    type: "entity.record.submit",
-                    record_json: encodeEntityRecord(row.record),
-                }, ["entity.record.ack"]);
-                const accepted = decodeAcceptedEntityRecord(String(frame.record_json ?? ""));
-                stampOutboxAcceptance(this.databasePath(identity), row, accepted);
-            }));
-            const failed = sent.find((result) => result.status === "rejected");
-            if (failed)
-                throw pipelineStageError("entity record send", failed.reason);
-        }
-        if (!this.recordSyncStopped)
-            await this.receiveAcceptedRecords();
-    }
-    async receiveAcceptedRecords() {
-        const identity = this.activeIdentity;
-        const authorityId = this.cloudState?.resourceId;
-        if (!identity || !authorityId)
-            return;
-        const database = this.databasePath(identity);
-        while (!this.recordSyncStopped) {
-            const after = readAuthorityDeliveryCursor(database, authorityId);
-            const frame = await this.wire.request({
-                type: "entity.record.tail",
-                authority_id: authorityId,
-                after_delivery_sequence: after,
-                limit: RECORD_TAIL_LIMIT,
-            }, ["entity.record.tail-result"]);
-            const deliveries = decodeDeliveredRecords(frame.records);
-            if (this.recordSyncStopped)
-                return;
-            if (deliveries.length === 0)
-                return;
-            for (const delivery of deliveries) {
-                await this.receiveDelivery(database, authorityId, delivery);
-            }
-            if (deliveries.length < RECORD_TAIL_LIMIT)
-                return;
-        }
-    }
-    async receiveDelivery(database, authorityId, delivery) {
-        if (delivery.record.authorityId !== authorityId) {
-            throw new Error(`entity record authority ${delivery.record.authorityId} does not match ${authorityId}`);
-        }
-        let decision = storeReceivedRecord(database, delivery);
-        if (decision.kind === "gap") {
-            const frame = await this.wire.request({
-                type: "entity.record.entity-tail",
-                authority_id: authorityId,
-                entity_id: decision.entityId,
-                after_global_sequence: decision.after,
-                through_global_sequence: decision.received,
-            }, ["entity.record.entity-tail-result"]);
-            const missing = decodeDeliveredRecords(frame.records);
-            if (missing.length === 0) {
-                throw new Error(`entity ${decision.entityId} is missing sequence ${decision.after + 1}`);
-            }
-            for (const record of missing) {
-                decision = storeReceivedRecord(database, record);
-                if (decision.kind === "gap") {
-                    throw new Error(`entity ${decision.entityId} history remained gapped after backfill`);
-                }
-            }
-            decision = storeReceivedRecord(database, delivery);
-            if (decision.kind === "gap") {
-                throw new Error(`entity ${decision.entityId} history did not reach ${decision.received}`);
-            }
-        }
-        advanceAuthorityDeliveryCursor(database, authorityId, delivery.deliverySequence);
+        this.applyRail?.localStateChanged();
+        this.recordRail?.localRecordsAvailable();
     }
     async publishPendingSnapshotsBeforeLookup(identity, resourceId) {
         const pending = readSnapshotPublications(this.databasePath(identity));
@@ -1193,6 +1248,7 @@ function assertHealthyWatch(evidence, rootId) {
 function initializeDatabase(file) {
     ensurePrivateDir(dirname(file));
     const database = new Database(file);
+    database.pragma("busy_timeout = 5000");
     database.pragma("journal_mode = WAL");
     database.pragma("synchronous = FULL");
     database.exec(`
@@ -1481,26 +1537,6 @@ function findKnownEntityId(file, absolutePath, deviceNumber, inode) {
         database.close();
     }
 }
-function readOutbox(file) {
-    if (!existsSync(file))
-        return [];
-    const database = initializeDatabase(file);
-    try {
-        return database.prepare(`
-      SELECT local_sequence AS localSequence, record_json AS recordJson,
-             status, global_sequence AS globalSequence
-        FROM record_outbox WHERE status = 'pending' ORDER BY local_sequence
-    `).all().map((row) => ({
-            localSequence: row.localSequence,
-            record: decodeLocalEntityRecord(row.recordJson),
-            status: "pending",
-            globalSequence: null,
-        }));
-    }
-    finally {
-        database.close();
-    }
-}
 function readSnapshotPublications(file) {
     if (!existsSync(file))
         return [];
@@ -1526,153 +1562,6 @@ function readSnapshotPublications(file) {
         database.close();
     }
 }
-function readEntityReceiveCursor(file, authorityId, entityId) {
-    if (!existsSync(file))
-        return 0;
-    const database = initializeDatabase(file);
-    try {
-        const row = database.prepare(`
-      SELECT received_through AS receivedThrough
-        FROM entity_receive_cursors
-       WHERE authority_id = ? AND entity_id = ?
-    `).get(authorityId, entityId);
-        return row?.receivedThrough ?? 0;
-    }
-    finally {
-        database.close();
-    }
-}
-function readEntityReceiveCursors(file, authorityId) {
-    if (!existsSync(file))
-        return new Map();
-    const database = initializeDatabase(file);
-    try {
-        return new Map(database.prepare(`
-      SELECT entity_id AS entityId, received_through AS receivedThrough
-        FROM entity_receive_cursors WHERE authority_id = ?
-    `).all(authorityId)
-            .map((row) => [row.entityId, row.receivedThrough]));
-    }
-    finally {
-        database.close();
-    }
-}
-function readAuthorityDeliveryCursor(file, authorityId) {
-    if (!existsSync(file))
-        return 0;
-    const database = initializeDatabase(file);
-    try {
-        const row = database.prepare(`
-      SELECT received_through AS receivedThrough
-        FROM authority_delivery_cursors WHERE authority_id = ?
-    `).get(authorityId);
-        return row?.receivedThrough ?? 0;
-    }
-    finally {
-        database.close();
-    }
-}
-function decodeDeliveredRecords(value) {
-    if (!Array.isArray(value))
-        throw new Error("entity record tail did not return a records array");
-    return value.map((item) => {
-        if (item === null || typeof item !== "object") {
-            throw new Error("entity record tail contained a non-record delivery");
-        }
-        const delivered = item;
-        const deliverySequence = Number(delivered.delivery_sequence);
-        if (!Number.isSafeInteger(deliverySequence) || deliverySequence < 1
-            || typeof delivered.record_json !== "string") {
-            throw new Error("entity record delivery has invalid sequence or bytes");
-        }
-        return {
-            deliverySequence,
-            record: decodeAcceptedEntityRecord(delivered.record_json),
-        };
-    });
-}
-function stampOutboxAcceptance(file, row, accepted) {
-    const receipt = acceptOutboxRow(row, accepted);
-    if (receipt.status !== "accepted")
-        throw new Error("authority acknowledgement was not accepted");
-    const database = initializeDatabase(file);
-    try {
-        database.transaction(() => {
-            const updated = database.prepare(`
-        UPDATE record_outbox
-           SET status = 'accepted', global_sequence = ?, accepted_at = ?
-         WHERE mutation_id = ? AND status = 'pending'
-      `).run(accepted.globalSequence, accepted.acceptedAt, accepted.mutationId);
-            if (updated.changes === 1)
-                return;
-            const existing = database.prepare(`
-        SELECT status, global_sequence AS globalSequence
-          FROM record_outbox WHERE mutation_id = ?
-      `).get(accepted.mutationId);
-            if (existing?.status !== "accepted"
-                || existing.globalSequence !== accepted.globalSequence) {
-                throw new Error("outbox acknowledgement did not match its retained row");
-            }
-        })();
-    }
-    finally {
-        database.close();
-    }
-}
-function storeReceivedRecord(file, delivery) {
-    const database = initializeDatabase(file);
-    try {
-        return database.transaction(() => {
-            const cursor = database.prepare(`
-        SELECT authority_id AS authorityId, received_through AS receivedThrough
-          FROM entity_receive_cursors WHERE entity_id = ?
-      `).get(delivery.record.entityId);
-            if (cursor && cursor.authorityId !== delivery.record.authorityId) {
-                throw new Error(`entity ${delivery.record.entityId} cannot change authority channels`);
-            }
-            const existingRow = database.prepare(`
-        SELECT record_json AS recordJson FROM record_inbox
-         WHERE authority_id = ? AND entity_id = ? AND global_sequence = ?
-      `).get(delivery.record.authorityId, delivery.record.entityId, delivery.record.globalSequence);
-            const existing = existingRow
-                ? decodeAcceptedEntityRecord(existingRow.recordJson)
-                : null;
-            const decision = receiveEntityRecord(cursor?.receivedThrough ?? 0, delivery.record, existing);
-            if (decision.kind !== "insert")
-                return decision;
-            database.prepare(`
-        INSERT INTO record_inbox(
-          authority_id, entity_id, global_sequence, delivery_sequence,
-          mutation_id, record_json, received_at
-        ) VALUES (?, ?, ?, ?, ?, ?, ?)
-      `).run(delivery.record.authorityId, delivery.record.entityId, delivery.record.globalSequence, delivery.deliverySequence, delivery.record.mutationId, encodeEntityRecord(delivery.record), Date.now());
-            database.prepare(`
-        INSERT INTO entity_receive_cursors(authority_id, entity_id, received_through)
-        VALUES (?, ?, ?)
-        ON CONFLICT(entity_id) DO UPDATE SET
-          received_through = excluded.received_through
-      `).run(delivery.record.authorityId, delivery.record.entityId, decision.receivedThrough);
-            return decision;
-        })();
-    }
-    finally {
-        database.close();
-    }
-}
-function advanceAuthorityDeliveryCursor(file, authorityId, deliverySequence) {
-    const database = initializeDatabase(file);
-    try {
-        database.prepare(`
-      INSERT INTO authority_delivery_cursors(authority_id, received_through)
-      VALUES (?, ?)
-      ON CONFLICT(authority_id) DO UPDATE SET
-        received_through = MAX(received_through, excluded.received_through)
-    `).run(authorityId, deliverySequence);
-    }
-    finally {
-        database.close();
-    }
-}
 function hasRecordsBeyondSnapshot(file) {
     if (!existsSync(file))
         return false;
@@ -1715,14 +1604,22 @@ function commitDetectedState(file, input) {
             for (const uuid of input.materializedRemovals ?? [])
                 removeMaterialized.run(uuid);
             const upsertMaterialized = prepareGroundUpsert(database, "entities");
+            // A valid graph may move or re-root several UUIDs through one another's
+            // old address slots. Release every changed UUID's old slot first, then
+            // install the complete new projection in this same transaction; row
+            // iteration order must never decide whether an atomic graph is valid.
             for (const row of input.acceptedMaterializedRows ?? []) {
-                upsertMaterialized.run(...groundRowValues(row));
+                removeMaterialized.run(row.uuid);
+            }
+            for (const row of input.acceptedMaterializedRows ?? []) {
+                runGroundUpsert(database, "entities", upsertMaterialized, row);
             }
             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));
+            for (const row of input.acceptedNotebookRows) {
+                runGroundUpsert(database, "detection_notebook", upsertNotebook, row);
+            }
         })();
     }
     finally {
@@ -1850,6 +1747,19 @@ function prepareGroundUpsert(database, table) {
       content_verified_at_ms = excluded.content_verified_at_ms
   `);
 }
+function runGroundUpsert(database, table, statement, row) {
+    try {
+        statement.run(...groundRowValues(row));
+    }
+    catch (error) {
+        const occupant = database.prepare(`
+      SELECT uuid, absolute_path AS absolutePath FROM ${table}
+       WHERE resource_id = ? AND root_uuid = ? AND relative_path = ?
+    `).get(row.resourceId, row.rootUUID, row.relativePath);
+        throw new Error(`${table} projection could not place ${row.uuid} at ${row.rootUUID}:${row.relativePath}; `
+            + `occupied by ${occupant?.uuid ?? "no retained row"} (${occupant?.absolutePath ?? "unknown"})`, { cause: error });
+    }
+}
 function persistRows(file, identity, resourceId, rootUUID, rows, previousRows = [], options = {}) {
     const database = initializeDatabase(file);
     try {
@@ -1864,6 +1774,7 @@ function persistRows(file, identity, resourceId, rootUUID, rows, previousRows =
         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 releaseChangedSlot = database.prepare("DELETE FROM entities WHERE 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()
@@ -1904,10 +1815,13 @@ function persistRows(file, identity, resourceId, rootUUID, rows, previousRows =
                 }
             }
             for (const row of changed)
-                upsert.run(...groundRowValues(capturedGroundRow(resourceId, rootUUID, row)));
+                releaseChangedSlot.run(row.record.uuid);
+            for (const row of changed) {
+                runGroundUpsert(database, "entities", upsert, capturedGroundRow(resourceId, rootUUID, row));
+            }
             if (options.updateNotebook !== false) {
                 for (const row of notebookChanged) {
-                    upsertNotebook.run(...groundRowValues(capturedGroundRow(resourceId, rootUUID, row)));
+                    runGroundUpsert(database, "detection_notebook", upsertNotebook, capturedGroundRow(resourceId, rootUUID, row));
                 }
             }
         });
@@ -2320,6 +2234,11 @@ async function reconcileRoot(input) {
         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) {
+            // Every materialization boundary reserves its root .amalgm/ directory
+            // for machine intents, staging, and recovery. This is structural host
+            // state, never enrollment policy and never an entity.
+            if (base === "" && child.name === ".amalgm")
+                continue;
             if (isRepositoryMetadataEntry(parentType, child.name))
                 continue;
             const relativePath = base ? `${base}/${child.name}` : child.name;
@@ -2535,7 +2454,7 @@ async function reconcileRoot(input) {
         .sort((left, right) => right.relativePath.length - left.relativePath.length)[0] ?? null;
     try {
         for (const repository of repositories) {
-            const repoIdentity = entries
+            let repoIdentity = entries
                 .filter((entry) => repositoryOwner(entry)?.uuid === repository.uuid)
                 .map((entry) => ({
                 path: repository.relativePath
@@ -2598,7 +2517,30 @@ async function reconcileRoot(input) {
                     .sort((left, right) => left.path < right.path ? -1 : left.path > right.path ? 1 : 0)
                 : null;
             evidence && (evidence.repositoryCaptures += 1);
-            const captured = captureRepository(repository.absolutePath, repoIdentity, prior, previousIdentity);
+            let captured = null;
+            let coherent = false;
+            for (let attempt = 0; attempt < 3; attempt += 1) {
+                captured = captureRepository(repository.absolutePath, repoIdentity, prior, previousIdentity);
+                const after = canonicalizeGitIdentity(repoIdentity, inspectGitRegistration(repository.absolutePath));
+                if (sameGitIdentity(after, repoIdentity)) {
+                    coherent = true;
+                    break;
+                }
+                repoIdentity = after;
+            }
+            if (!coherent || !captured) {
+                throw new Error(`repository did not settle during capture: ${repository.absolutePath}`);
+            }
+            for (const identityEntry of repoIdentity) {
+                const entry = entries.find((candidate) => repositoryOwner(candidate)?.uuid === repository.uuid
+                    && (repository.relativePath
+                        ? candidate.relativePath.slice(repository.relativePath.length + 1)
+                        : candidate.relativePath) === identityEntry.path);
+                if (!entry)
+                    continue;
+                entry.type = identityEntry.type;
+                entry.payloadVersion = identityEntry.payloadVersion ?? null;
+            }
             repository.payloadVersion = captured.stateId;
             repository.transportVersion = captured.transportVersion;
             if (captured.bytes) {