@amalgm/shell 0.1.52 → 0.1.54

package/dist/user-ground-host.js

@@ -3,9 +3,10 @@ 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, 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 { 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";
@@ -22,9 +23,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,9 +42,8 @@ export class UserGroundHost {
     cloudState = null;
     converged = false;
     syncing = null;
-    recordSyncing = null;
-    recordSyncTimer = null;
-    recordSyncStopped = false;
+    recordRail = null;
+    recordStore = null;
     namedDetect = null;
     coldOperation = false;
     closing = false;
@@ -90,8 +87,8 @@ export class UserGroundHost {
                     watcherRoots: watchHealth.contentHandles,
                     watching: true,
                 };
+                await this.startRecordRail(this.activeIdentity);
                 this.converged = true;
-                this.scheduleRecordSync();
                 return evidence;
             },
         };
@@ -341,12 +338,25 @@ export class UserGroundHost {
             return;
         const identity = this.activeIdentity;
         this.watchHost.suspectAll();
+        const cutoff = this.watchHost.observations();
         // The complete suspicion above contains everything known at this cutoff.
         // A native callback after this assignment sets watchDirty again and must
         // remain a later generation; flush never waits for global Watch silence.
         this.watchDirty = false;
-        await this.syncNow();
-        await this.syncRecordsNow();
+        do {
+            const joinedEarlierGeneration = this.syncing !== null;
+            try {
+                await this.syncNow();
+            }
+            catch (error) {
+                // A job that was already in flight froze older observations. Its
+                // success or failure cannot prove this flush's later cutoff; the next
+                // pass owns that proof. A pass started here still fails honestly.
+                if (!joinedEarlierGeneration)
+                    throw error;
+            }
+        } while (!this.watchHost.settled(cutoff));
+        await this.recordRail?.flush();
         if (!this.closing)
             this.ensureWatchers(identity);
     }
@@ -370,31 +380,51 @@ 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 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 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,
+            },
+        });
+        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);
         }
-        await this.recordSyncing;
     }
     async activateRuntimeTunnel(gatewayPort, runtimeToken) {
         // Files convergence and Watch/Detect own ground currency. Advertising an
@@ -403,28 +433,27 @@ 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 recordStopped = this.recordRail?.stop();
             await this.wire.close();
-            await this.recordSyncing?.catch(() => undefined);
+            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;
             return;
         }
         // Command shutdown is the last catch-up boundary. A filesystem callback
@@ -436,20 +465,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));
@@ -855,7 +885,7 @@ export class UserGroundHost {
                     });
                 }
                 this.watchHost.settle(observations);
-                this.scheduleRecordSync();
+                this.recordRail?.localRecordsAvailable();
                 return;
             }
         }
@@ -887,7 +917,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(),
@@ -905,91 +935,7 @@ 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.recordRail?.localRecordsAvailable();
     }
     async publishPendingSnapshotsBeforeLookup(identity, resourceId) {
         const pending = readSnapshotPublications(this.databasePath(identity));
@@ -1180,6 +1126,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(`
@@ -1468,26 +1415,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 [];
@@ -1513,153 +1440,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;