@feltdb/core 0.8.2 → 0.8.3

package/dist/create/package-versions.js

@@ -1,4 +1,4 @@
 // One release train keeps generated applications installable. The repository
 // validation script checks these values against every workspace manifest.
-export const FELTDB_PACKAGE_VERSION = '0.8.2';
+export const FELTDB_PACKAGE_VERSION = '0.8.3';
 export const feltdbPackageRange = `^${FELTDB_PACKAGE_VERSION}`;

package/dist/file-db.d.ts

@@ -25,6 +25,7 @@ export declare class FileJsDb implements JsDb {
     private readonly origin;
     private readonly peers;
     private lockFd;
+    private lockToken;
     private readonly applied;
     constructor(path: string);
     private loadState;
@@ -34,6 +35,10 @@ export declare class FileJsDb implements JsDb {
     private cleanupStaleLock;
     private acquireLockAsync;
     private releaseLockAsync;
+    private ownsLock;
+    private acquireLockSync;
+    private withMutationLock;
+    private refresh;
     private saveState;
     private event;
     /**
@@ -64,21 +69,9 @@ export declare class FileJsDb implements JsDb {
     instance_id(): string;
     get_sequence(): number;
     /**
-     * The file runtime declines revision validation, and this is the honest answer
-     * rather than a missing feature.
-     *
-     * A shared directory has no serialization authority over its writers.
-     * `insert`, `update`, `delete`, and `commit_transaction` do not take the
-     * cross-process lock, and publication is a whole-snapshot rename, so two
-     * processes writing the same directory lose data. `state.sequence` therefore
-     * cannot distinguish "one writer committed 50" from "two writers committed 50
-     * each and one snapshot won" — it produces a plausible but false answer,
-     * which is worse than producing none.
-     *
-     * Measured in tools/cli/test/file-runtime-concurrency.test.mjs and analysed in
-     * docs/architecture/freshness-revision-investigation.md. Making this runtime
-     * revision-capable requires fixing lock discipline and publication together;
-     * advertising `refresh` is correct until then, not a placeholder.
+     * The file runtime uses explicit refresh validation. Cross-process mutations
+     * are serialized and reads reload the committed snapshot, but the public read
+     * contract does not yet return a scoped revision alongside its value.
      */
     freshness(): FreshnessCapability;
     audit_events(): PortableEvent[];

package/dist/file-db.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"file-db.d.ts","sourceRoot":"","sources":["../src/file-db.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"file-db.d.ts","sourceRoot":"","sources":["../src/file-db.ts"],"names":[],"mappings":"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"}

package/dist/file-db.js

@@ -21,6 +21,7 @@ export class FileJsDb {
     origin;
     peers = new Set();
     lockFd = null;
+    lockToken = null;
     applied = new Set();
     constructor(path) {
         const nodePath = getPathSync();
@@ -105,11 +106,25 @@ export class FileJsDb {
             }
             const stat = nodeFs.statSync(this.lockPath);
             const ageMs = Date.now() - stat.mtimeMs;
-            // Lock is stale if it's older than 5 seconds
-            if (ageMs > STALE_LOCK_THRESHOLD_MS) {
-                return true;
+            if (ageMs <= STALE_LOCK_THRESHOLD_MS)
+                return false;
+            try {
+                const owner = JSON.parse(nodeFs.readFileSync(this.lockPath, 'utf8'));
+                if (typeof owner.pid === 'number') {
+                    try {
+                        process.kill(owner.pid, 0);
+                        return false;
+                    }
+                    catch (error) {
+                        return error?.code === 'ESRCH';
+                    }
+                }
             }
-            return false;
+            catch {
+                // Legacy locks did not contain ownership metadata. Their age is the
+                // only recovery signal available.
+            }
+            return true;
         }
         catch {
             return false;
@@ -134,9 +149,13 @@ export class FileJsDb {
         this.cleanupStaleLock();
         for (let attempt = 0; attempt < maxRetries; attempt++) {
             try {
+                const token = `${process.pid}:${Date.now()}:${Math.random().toString(36).slice(2)}`;
                 const fd = nodeFs.openSync(this.lockPath, 'wx', 0o600);
+                nodeFs.writeFileSync(fd, JSON.stringify({ pid: process.pid, token }));
+                nodeFs.fsyncSync(fd);
                 nodeFs.closeSync(fd);
                 this.lockFd = 1;
+                this.lockToken = token;
                 return;
             }
             catch (err) {
@@ -156,7 +175,7 @@ export class FileJsDb {
     releaseLockAsync() {
         const nodeFs = getFsSync();
         try {
-            if (nodeFs.existsSync(this.lockPath)) {
+            if (nodeFs.existsSync(this.lockPath) && this.ownsLock()) {
                 nodeFs.unlinkSync(this.lockPath);
             }
         }
@@ -164,6 +183,59 @@ export class FileJsDb {
             console.warn('Error releasing lock:', err);
         }
         this.lockFd = null;
+        this.lockToken = null;
+    }
+    ownsLock() {
+        if (!this.lockToken)
+            return false;
+        try {
+            const owner = JSON.parse(getFsSync().readFileSync(this.lockPath, 'utf8'));
+            return owner.token === this.lockToken;
+        }
+        catch {
+            return false;
+        }
+    }
+    acquireLockSync() {
+        const nodeFs = getFsSync();
+        this.cleanupStaleLock();
+        for (let attempt = 0; attempt < 1000; attempt += 1) {
+            try {
+                const token = `${process.pid}:${Date.now()}:${Math.random().toString(36).slice(2)}`;
+                const fd = nodeFs.openSync(this.lockPath, 'wx', 0o600);
+                nodeFs.writeFileSync(fd, JSON.stringify({ pid: process.pid, token }));
+                nodeFs.fsyncSync(fd);
+                nodeFs.closeSync(fd);
+                this.lockFd = 1;
+                this.lockToken = token;
+                return;
+            }
+            catch (error) {
+                if (error?.code !== 'EEXIST' || attempt === 999)
+                    throw error;
+                if (attempt % 10 === 0)
+                    this.cleanupStaleLock();
+                Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 5);
+            }
+        }
+    }
+    withMutationLock(operation) {
+        this.acquireLockSync();
+        try {
+            this.refresh();
+            return operation();
+        }
+        finally {
+            this.releaseLockAsync();
+        }
+    }
+    refresh() {
+        this.state = this.loadState();
+        this.peers.clear();
+        this.restorePeers();
+        this.applied.clear();
+        for (const transactionId of this.state.applied_transactions ?? [])
+            this.applied.add(transactionId);
     }
     saveState() {
         const nodeFs = getFsSync();
@@ -187,7 +259,7 @@ export class FileJsDb {
             };
             const content = JSON.stringify(snapshot, null, 2);
             // Write to temporary file
-            const tempPath = this.statePath + '.tmp';
+            const tempPath = `${this.statePath}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
             const handle = nodeFs.openSync(tempPath, 'w');
             try {
                 nodeFs.writeFileSync(handle, content, 'utf-8');
@@ -246,96 +318,120 @@ export class FileJsDb {
      * adopted in memory, so a failed write cannot leave memory ahead of disk.
      */
     async commit_transaction(request) {
-        const before = this.state.sequence;
-        const plan = decideTransaction(request, {
-            exists: key => key in this.state.rows,
-            hasApplied: transactionId => this.applied.has(transactionId),
-            read: key => this.state.rows[key],
-        });
-        if (plan.kind === 'duplicate') {
-            return embeddedResult(request, true, before, this.state.sequence);
-        }
-        if (plan.kind === 'reject') {
-            throw new EmbeddedTransactionRejected(plan.reason);
-        }
-        // Build the post-transaction state without touching the live one.
-        const rows = { ...this.state.rows };
-        const events = [...this.state.events];
-        let sequence = this.state.sequence;
-        const timestamp = Date.now();
-        for (const mutation of plan.mutations) {
-            sequence += 1;
-            if (mutation.value === undefined) {
-                delete rows[mutation.key];
+        await this.acquireLockAsync();
+        try {
+            this.refresh();
+            const before = this.state.sequence;
+            const plan = decideTransaction(request, {
+                exists: key => key in this.state.rows,
+                hasApplied: transactionId => this.applied.has(transactionId),
+                read: key => this.state.rows[key],
+            });
+            if (plan.kind === 'duplicate')
+                return embeddedResult(request, true, before, this.state.sequence);
+            if (plan.kind === 'reject')
+                throw new EmbeddedTransactionRejected(plan.reason);
+            // Build the post-transaction state without touching the live one.
+            const rows = { ...this.state.rows };
+            const events = [...this.state.events];
+            let sequence = this.state.sequence;
+            const timestamp = Date.now();
+            for (const mutation of plan.mutations) {
+                sequence += 1;
+                if (mutation.value === undefined) {
+                    delete rows[mutation.key];
+                }
+                else {
+                    rows[mutation.key] = mutation.value;
+                }
+                events.push({
+                    sequence,
+                    collection: mutation.collection,
+                    key: mutation.key,
+                    type: mutation.value === undefined ? 'delete' : 'put',
+                    value: mutation.value,
+                    timestamp,
+                    origin: this.origin,
+                    id: `${this.origin}:${timestamp}:${sequence}`,
+                });
             }
-            else {
-                rows[mutation.key] = mutation.value;
+            const previous = this.state;
+            this.state = { ...this.state, rows, events, sequence };
+            // The transaction id has to be part of the snapshot being written, not
+            // added after it. Recording it afterwards would leave a committed
+            // transaction whose identity did not survive a restart, and redelivery
+            // would then apply it a second time.
+            this.applied.add(request.transactionId);
+            try {
+                this.saveState();
             }
-            events.push({
-                sequence,
-                collection: mutation.collection,
-                key: mutation.key,
-                type: mutation.value === undefined ? 'delete' : 'put',
-                value: mutation.value,
-                timestamp,
-                origin: this.origin,
-                id: `${this.origin}:${timestamp}:${sequence}`,
-            });
-        }
-        const previous = this.state;
-        this.state = { ...this.state, rows, events, sequence };
-        // The transaction id has to be part of the snapshot being written, not
-        // added after it. Recording it afterwards would leave a committed
-        // transaction whose identity did not survive a restart, and redelivery
-        // would then apply it a second time.
-        this.applied.add(request.transactionId);
-        try {
-            this.saveState();
+            catch (error) {
+                // The commit did not become durable, so it must not be visible either.
+                this.state = previous;
+                this.applied.delete(request.transactionId);
+                throw error;
+            }
+            return embeddedResult(request, false, before, sequence);
         }
-        catch (error) {
-            // The commit did not become durable, so it must not be visible either.
-            this.state = previous;
-            this.applied.delete(request.transactionId);
-            throw error;
+        finally {
+            this.releaseLockAsync();
         }
-        return embeddedResult(request, false, before, sequence);
     }
     insert(key, value) {
         try {
             const parsed = JSON.parse(value);
-            this.state.rows[key] = parsed;
-            const collection = key.split(':')[0];
-            this.event(collection, key, 'put', parsed);
-            this.saveState();
-            return { success: true, data: key };
+            return this.withMutationLock(() => {
+                this.state.rows[key] = parsed;
+                const collection = key.split(':')[0];
+                this.event(collection, key, 'put', parsed);
+                this.saveState();
+                return { success: true, data: key };
+            });
         }
         catch (error) {
             return { success: false, error: String(error) };
         }
     }
     update(key, value) {
-        if (!(key in this.state.rows)) {
-            return { success: false, error: `Record ${key} not found` };
+        try {
+            const parsed = JSON.parse(value);
+            return this.withMutationLock(() => {
+                if (!(key in this.state.rows))
+                    return { success: false, error: `Record ${key} not found` };
+                this.state.rows[key] = parsed;
+                this.event(key.split(':')[0], key, 'put', parsed);
+                this.saveState();
+                return { success: true, data: key };
+            });
+        }
+        catch (error) {
+            return { success: false, error: String(error) };
         }
-        return this.insert(key, value);
     }
     get(key) {
+        this.refresh();
         const value = this.state.rows[key];
         return value === undefined
             ? { success: true }
             : { success: true, data: JSON.stringify(value) };
     }
     delete(key) {
-        if (!(key in this.state.rows)) {
-            return { success: false, error: `Record ${key} not found` };
+        try {
+            return this.withMutationLock(() => {
+                if (!(key in this.state.rows))
+                    return { success: false, error: `Record ${key} not found` };
+                delete this.state.rows[key];
+                this.event(key.split(':')[0], key, 'delete');
+                this.saveState();
+                return { success: true, data: key };
+            });
+        }
+        catch (error) {
+            return { success: false, error: String(error) };
         }
-        delete this.state.rows[key];
-        const collection = key.split(':')[0];
-        this.event(collection, key, 'delete');
-        this.saveState();
-        return { success: true, data: key };
     }
     query(capability) {
+        this.refresh();
         const prefix = `${capability}:`;
         const values = Object.entries(this.state.rows)
             .filter(([key]) => key.startsWith(prefix))
@@ -349,6 +445,7 @@ export class FileJsDb {
         return { success: false, error: 'Raw operations are unavailable in the file runtime' };
     }
     sync_info() {
+        this.refresh();
         return {
             success: true,
             data: JSON.stringify({
@@ -368,12 +465,10 @@ export class FileJsDb {
         return { success: true };
     }
     add_sync_peer(peerId) {
-        this.peers.add(peerId);
-        return { success: true };
+        return this.withMutationLock(() => { this.peers.add(peerId); this.saveState(); return { success: true }; });
     }
     remove_sync_peer(peerId) {
-        this.peers.delete(peerId);
-        return { success: true };
+        return this.withMutationLock(() => { this.peers.delete(peerId); this.saveState(); return { success: true }; });
     }
     acknowledge_peer_operations() {
         return { success: true };
@@ -385,83 +480,82 @@ export class FileJsDb {
         return this.origin;
     }
     get_sequence() {
+        this.refresh();
         return this.state.sequence;
     }
     /**
-     * The file runtime declines revision validation, and this is the honest answer
-     * rather than a missing feature.
-     *
-     * A shared directory has no serialization authority over its writers.
-     * `insert`, `update`, `delete`, and `commit_transaction` do not take the
-     * cross-process lock, and publication is a whole-snapshot rename, so two
-     * processes writing the same directory lose data. `state.sequence` therefore
-     * cannot distinguish "one writer committed 50" from "two writers committed 50
-     * each and one snapshot won" — it produces a plausible but false answer,
-     * which is worse than producing none.
-     *
-     * Measured in tools/cli/test/file-runtime-concurrency.test.mjs and analysed in
-     * docs/architecture/freshness-revision-investigation.md. Making this runtime
-     * revision-capable requires fixing lock discipline and publication together;
-     * advertising `refresh` is correct until then, not a placeholder.
+     * The file runtime uses explicit refresh validation. Cross-process mutations
+     * are serialized and reads reload the committed snapshot, but the public read
+     * contract does not yet return a scoped revision alongside its value.
      */
     freshness() {
         return {
             domain: 'multi-process-file',
             validation: 'refresh',
             invalidation: false,
-            reason: 'a shared directory has no serialization authority over its writers, '
-                + 'so state.sequence cannot be an authoritative revision',
+            reason: 'reads refresh from the serialized file authority; the public read '
+                + 'contract does not yet expose a scoped revision token',
         };
     }
     audit_events() {
+        this.refresh();
         return [...this.state.events];
     }
     export_operations(sinceSequence) {
+        this.refresh();
         return this.state.events.filter(event => event.sequence > sinceSequence);
     }
     apply_remote_operations(operations) {
-        let applied = 0;
-        let ignored = 0;
-        for (const operation of operations) {
-            // Skip if we've already applied this operation
-            if (this.state.events.some(event => event.id === operation.id)) {
-                ignored++;
-                continue;
-            }
-            // Find the current state of this key
-            const current = [...this.state.events].reverse().find(event => event.key === operation.key);
-            // Use lamport-clock-style ordering: timestamp, then origin, then id
-            const incomingOrder = `${String(operation.timestamp).padStart(16, '0')}:${operation.origin}:${operation.id}`;
-            const currentOrder = current ? `${String(current.timestamp).padStart(16, '0')}:${current.origin}:${current.id}` : '';
-            this.state.sequence += 1;
-            this.state.events.push({ ...operation, sequence: this.state.sequence });
-            // Apply if incoming is newer
-            if (incomingOrder >= currentOrder) {
-                if (operation.type === 'delete') {
-                    delete this.state.rows[operation.key];
+        return this.withMutationLock(() => {
+            let applied = 0;
+            let ignored = 0;
+            for (const operation of operations) {
+                // Skip if we've already applied this operation
+                if (this.state.events.some(event => event.id === operation.id)) {
+                    ignored++;
+                    continue;
+                }
+                // Find the current state of this key
+                const current = [...this.state.events].reverse().find(event => event.key === operation.key);
+                // Use lamport-clock-style ordering: timestamp, then origin, then id
+                const incomingOrder = `${String(operation.timestamp).padStart(16, '0')}:${operation.origin}:${operation.id}`;
+                const currentOrder = current ? `${String(current.timestamp).padStart(16, '0')}:${current.origin}:${current.id}` : '';
+                this.state.sequence += 1;
+                this.state.events.push({ ...operation, sequence: this.state.sequence });
+                // Apply if incoming is newer
+                if (incomingOrder >= currentOrder) {
+                    if (operation.type === 'delete') {
+                        delete this.state.rows[operation.key];
+                    }
+                    else {
+                        this.state.rows[operation.key] = operation.value;
+                    }
+                    applied++;
                 }
                 else {
-                    this.state.rows[operation.key] = operation.value;
+                    ignored++;
                 }
-                applied++;
             }
-            else {
-                ignored++;
+            // Save state after applying remote operations
+            if (applied > 0) {
+                this.saveState();
             }
-        }
-        // Save state after applying remote operations
-        if (applied > 0) {
-            this.saveState();
-        }
-        return { applied, ignored };
+            return { applied, ignored };
+        });
     }
     async allocateSequence(params) {
-        const key = `${params.scope}:${params.scopeId}`;
-        const current = this.state.sequences[key] ?? 0;
-        const next = current + 1;
-        this.state.sequences[key] = next;
-        this.saveState();
-        return next;
+        await this.acquireLockAsync();
+        try {
+            this.refresh();
+            const key = `${params.scope}:${params.scopeId}`;
+            const next = (this.state.sequences[key] ?? 0) + 1;
+            this.state.sequences[key] = next;
+            this.saveState();
+            return next;
+        }
+        finally {
+            this.releaseLockAsync();
+        }
     }
     async putIfAbsent(key, value) {
         const nodeFs = getFsSync();
@@ -524,10 +618,17 @@ export class FileJsDb {
         const operationIdKey = `op-id:${operationId}`;
         const operationValue = JSON.stringify(durableOperation);
         try {
-            const result = await this.putIfAbsent(idempotencyKey, operationValue);
-            // Also store by operationId for direct lookups
+            await this.acquireLockAsync();
+            this.refresh();
+            const present = this.state.rows[idempotencyKey];
+            const result = present === undefined
+                ? { inserted: true, value: operationValue }
+                : { inserted: false, value: JSON.stringify(present) };
             if (result.inserted) {
+                this.state.rows[idempotencyKey] = durableOperation;
                 this.state.rows[operationIdKey] = durableOperation;
+                this.event('operation', idempotencyKey, 'put', durableOperation);
+                this.event('op-id', operationIdKey, 'put', durableOperation);
                 this.saveState();
             }
             // Parse the existing or newly inserted operation
@@ -548,6 +649,9 @@ export class FileJsDb {
         catch (error) {
             throw new Error(`Operation admission failed: ${error}`);
         }
+        finally {
+            this.releaseLockAsync();
+        }
     }
     async transitionOperation(input) {
         // Validate input
@@ -722,7 +826,7 @@ export class FileJsDb {
         }
     }
     close() {
-        // Ensure final state is persisted
-        this.saveState();
+        // Mutations are durable before they return. Closing a stale handle must
+        // never rewrite authority state produced by another process.
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@feltdb/core",
-  "version": "0.8.2",
+  "version": "0.8.3",
   "description": "FeltDB Core - Application-facing database with Browser, Local, and Server runtimes. Durable state, reactive APIs.",
   "license": "MIT",
   "type": "module",