@feltdb/core 0.4.16 → 0.4.20

package/dist/file-db.js

@@ -1,3 +1,4 @@
+import { validateOperationAdmissionInput, operationsConflict, generateOperationId, validateTransitionInput, isValidTransition, isTerminalStatus, isIdempotentTerminalTransition, } from './operation-admission.js';
 import { createRequire } from 'module';
 // Create a require function for use in ESM context
 let requireFunc = null;
@@ -46,6 +47,7 @@ function getPathSync() {
 export class FileJsDb {
     constructor(path) {
         this.peers = new Set();
+        this.lockFd = null;
         const nodePath = getPathSync();
         const nodeFs = getFsSync();
         // Normalize and resolve the path to prevent directory traversal
@@ -56,12 +58,15 @@ export class FileJsDb {
         }
         this.dataPath = resolvedPath;
         this.statePath = nodePath.join(this.dataPath, 'state.json');
+        this.lockPath = nodePath.join(this.dataPath, 'state.lock');
         // Create directory if it doesn't exist
         if (!nodeFs.existsSync(this.dataPath)) {
             nodeFs.mkdirSync(this.dataPath, { recursive: true });
         }
         // Generate stable instance ID based on path
         this.origin = `file:${this.dataPath}`;
+        // Clean up any stale locks from previous crashes on startup
+        this.cleanupStaleLock();
         // Load or initialize state
         this.state = this.loadState();
         this.restorePeers();
@@ -111,6 +116,75 @@ export class FileJsDb {
             this.peers.add(peer);
         }
     }
+    isStalelock() {
+        const nodeFs = getFsSync();
+        const STALE_LOCK_THRESHOLD_MS = 5000;
+        try {
+            if (!nodeFs.existsSync(this.lockPath)) {
+                return false;
+            }
+            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;
+            }
+            return false;
+        }
+        catch {
+            return false;
+        }
+    }
+    cleanupStaleLock() {
+        const nodeFs = getFsSync();
+        try {
+            if (this.isStalelock()) {
+                nodeFs.unlinkSync(this.lockPath);
+            }
+        }
+        catch (err) {
+            console.warn('Failed to clean up stale lock:', err);
+        }
+    }
+    async acquireLockAsync() {
+        const nodeFs = getFsSync();
+        const maxRetries = 1000;
+        const retryDelayMs = 5;
+        // Attempt to clean up any stale locks before trying to acquire
+        this.cleanupStaleLock();
+        for (let attempt = 0; attempt < maxRetries; attempt++) {
+            try {
+                const fd = nodeFs.openSync(this.lockPath, 'wx', 0o600);
+                nodeFs.closeSync(fd);
+                this.lockFd = 1;
+                return;
+            }
+            catch (err) {
+                if (err.code === 'EEXIST' && attempt < maxRetries - 1) {
+                    // After a few attempts, check if the lock is stale
+                    if (attempt % 10 === 0) {
+                        this.cleanupStaleLock();
+                    }
+                    await new Promise(resolve => setTimeout(resolve, retryDelayMs));
+                    continue;
+                }
+                throw new Error(`Failed to acquire lock: ${err.message}`);
+            }
+        }
+        throw new Error(`Failed to acquire lock after ${maxRetries} attempts`);
+    }
+    releaseLockAsync() {
+        const nodeFs = getFsSync();
+        try {
+            if (nodeFs.existsSync(this.lockPath)) {
+                nodeFs.unlinkSync(this.lockPath);
+            }
+        }
+        catch (err) {
+            console.warn('Error releasing lock:', err);
+        }
+        this.lockFd = null;
+    }
     saveState() {
         const nodeFs = getFsSync();
         try {
@@ -292,29 +366,167 @@ export class FileJsDb {
         return next;
     }
     async putIfAbsent(key, value) {
+        const nodeFs = getFsSync();
         try {
-            const parsed = JSON.parse(value);
-            // Check if key exists (atomic read within single-state persistence)
-            if (key in this.state.rows) {
-                // Already exists, return the existing value
-                const existing = this.state.rows[key];
+            await this.acquireLockAsync();
+            try {
+                const parsed = JSON.parse(value);
+                // Reload state from disk to ensure we have the latest
+                this.state = this.loadState();
+                // Check if key exists (atomic read within lock boundary)
+                if (key in this.state.rows) {
+                    // Already exists, return the existing value
+                    const existing = this.state.rows[key];
+                    return {
+                        inserted: false,
+                        value: JSON.stringify(existing)
+                    };
+                }
+                // Key doesn't exist, insert it atomically within lock
+                this.state.rows[key] = parsed;
+                const collection = key.split(':')[0];
+                this.event(collection, key, 'put', parsed);
+                this.saveState();
                 return {
-                    inserted: false,
-                    value: JSON.stringify(existing)
+                    inserted: true,
+                    value: value
                 };
             }
-            // Key doesn't exist, insert it atomically
-            this.state.rows[key] = parsed;
-            const collection = key.split(':')[0];
-            this.event(collection, key, 'put', parsed);
-            this.saveState();
+            finally {
+                this.releaseLockAsync();
+            }
+        }
+        catch (error) {
+            throw new Error(`putIfAbsent failed: ${error}`);
+        }
+    }
+    async admitOperation(input) {
+        // Validate input
+        const validation = validateOperationAdmissionInput(input);
+        if (!validation.valid) {
+            throw new Error(`Operation admission validation failed: ${validation.error}`);
+        }
+        // Generate operation ID for this admission attempt
+        const operationId = generateOperationId();
+        // Create durable operation record
+        const durableOperation = {
+            operationId,
+            idempotencyKey: input.idempotencyKey,
+            kind: input.kind,
+            status: 'accepted',
+            version: 0,
+            createdAt: Date.now(),
+            operationFingerprint: input.operationFingerprint,
+            metadata: input.metadata,
+        };
+        // Use putIfAbsent to atomically store the operation
+        // Key format: "operation:{idempotencyKey}" for idempotency lookup
+        // Key format: "op-id:{operationId}" for direct operation lookup
+        const idempotencyKey = `operation:${input.idempotencyKey}`;
+        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
+            if (result.inserted) {
+                this.state.rows[operationIdKey] = durableOperation;
+                this.saveState();
+            }
+            // Parse the existing or newly inserted operation
+            const existingOperation = JSON.parse(result.value);
+            // Check for conflicts if operation already existed
+            if (!result.inserted) {
+                const conflict = operationsConflict(existingOperation, input);
+                if (conflict) {
+                    throw new Error(conflict.message);
+                }
+            }
             return {
-                inserted: true,
-                value: value
+                admitted: result.inserted,
+                operationId: existingOperation.operationId,
+                operation: existingOperation,
             };
         }
         catch (error) {
-            throw new Error(`putIfAbsent failed: ${error}`);
+            throw new Error(`Operation admission failed: ${error}`);
+        }
+    }
+    async transitionOperation(input) {
+        // Validate input
+        const validation = validateTransitionInput(input);
+        if (!validation.valid) {
+            throw new Error(`Transition validation failed: ${validation.error}`);
+        }
+        try {
+            await this.acquireLockAsync();
+            try {
+                // Reload state from disk to ensure we have latest
+                this.state = this.loadState();
+                // Look up operation by its operationId
+                const operationIdKey = `op-id:${input.operationId}`;
+                // Get current operation state
+                if (!(operationIdKey in this.state.rows)) {
+                    throw new Error(`Operation ${input.operationId} not found`);
+                }
+                const currentOperation = this.state.rows[operationIdKey];
+                // Check if version matches (CAS)
+                if (currentOperation.version !== input.expectedVersion) {
+                    return {
+                        transitioned: false,
+                        reason: 'VERSION_CONFLICT',
+                        operation: currentOperation,
+                    };
+                }
+                // Check if transition is legal
+                if (!isValidTransition(currentOperation.status, input.to)) {
+                    return {
+                        transitioned: false,
+                        reason: 'INVALID_TRANSITION',
+                        operation: currentOperation,
+                    };
+                }
+                // If transitioning to terminal state, check for idempotent re-entry
+                if (isTerminalStatus(input.to) && isTerminalStatus(currentOperation.status)) {
+                    if (isIdempotentTerminalTransition(currentOperation, input.resultSnapshot, input.error)) {
+                        return {
+                            transitioned: false,
+                            reason: 'VERSION_CONFLICT', // Treat as version conflict (already transitioned)
+                            operation: currentOperation,
+                        };
+                    }
+                    // Different result data = conflict
+                    throw new Error(`Terminal state conflict: operation already in ${currentOperation.status} with different result`);
+                }
+                // Perform the transition
+                const transitionedOperation = {
+                    ...currentOperation,
+                    status: input.to,
+                    version: currentOperation.version + 1,
+                    completedAt: isTerminalStatus(input.to) ? Date.now() : currentOperation.completedAt,
+                    startedAt: input.to === 'executing' ? Date.now() : currentOperation.startedAt,
+                    resultSnapshot: input.resultSnapshot ?? currentOperation.resultSnapshot,
+                    error: input.error ?? currentOperation.error,
+                };
+                // Persist the transition atomically within lock (update both indices)
+                this.state.rows[operationIdKey] = transitionedOperation;
+                const idempotencyIndexKey = `operation:${currentOperation.idempotencyKey}`;
+                if (idempotencyIndexKey in this.state.rows) {
+                    this.state.rows[idempotencyIndexKey] = transitionedOperation;
+                }
+                const collection = operationIdKey.split(':')[0];
+                this.event(collection, operationIdKey, 'put', transitionedOperation);
+                this.saveState();
+                return {
+                    transitioned: true,
+                    operation: transitionedOperation,
+                };
+            }
+            finally {
+                this.releaseLockAsync();
+            }
+        }
+        catch (error) {
+            throw new Error(`Transition failed: ${error}`);
         }
     }
     async cas(params) {

package/dist/operation-admission.d.ts

@@ -0,0 +1,141 @@
+/**
+ * Atomic Idempotent Operation Admission
+ *
+ * Defines the durable operation admission contract for FeltDB.
+ * Guarantees: exactly one operation identity per idempotency key,
+ * atomic durability, and convergence across concurrent callers.
+ */
+/**
+ * Input contract for admitting a durable operation
+ */
+export interface OperationAdmissionInput {
+    /** Unique idempotency key supplied by caller */
+    idempotencyKey: string;
+    /** Operation kind (e.g., "execution", "coordination", "verification") */
+    kind: string;
+    /** Optional immutable operation fingerprint for conflict detection */
+    operationFingerprint?: string;
+    /** Caller-supplied metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Operation lifecycle status
+ */
+export type OperationStatus = 'accepted' | 'executing' | 'completed' | 'failed' | 'cancelled';
+/**
+ * Durable operation record with versioned lifecycle
+ */
+export interface DurableOperation {
+    /** FeltDB-generated operation identity (ULIDv7 or similar) */
+    operationId: string;
+    /** Caller's idempotency key */
+    idempotencyKey: string;
+    /** Operation kind (immutable) */
+    kind: string;
+    /** Current operation status in lifecycle */
+    status: OperationStatus;
+    /** Version number (increments by 1 on each successful transition) */
+    version: number;
+    /** Timestamp when operation was admitted */
+    createdAt: number;
+    /** Timestamp when execution started */
+    startedAt?: number;
+    /** Timestamp when operation terminal state reached */
+    completedAt?: number;
+    /** Operation fingerprint for conflict detection */
+    operationFingerprint?: string;
+    /** Caller metadata */
+    metadata?: Record<string, unknown>;
+    /** Result/outcome for terminal states */
+    resultSnapshot?: unknown;
+    /** Error message for failed operations */
+    error?: string;
+}
+/**
+ * Result of an operation admission attempt
+ */
+export interface OperationAdmissionResult {
+    /** True if this caller admitted the operation; false if it already existed */
+    admitted: boolean;
+    /** FeltDB-generated operation identity (same for all callers with same idempotencyKey) */
+    operationId: string;
+    /** The durable operation record */
+    operation: DurableOperation;
+}
+/**
+ * Conflict error when idempotency key is reused with different operation semantics
+ */
+export interface IdempotencyConflictError {
+    code: 'IDEMPOTENCY_CONFLICT';
+    idempotencyKey: string;
+    existingKind: string;
+    requestedKind: string;
+    existingFingerprint?: string;
+    requestedFingerprint?: string;
+    message: string;
+}
+/**
+ * Input for atomic operation lifecycle transition
+ */
+export interface OperationTransitionInput {
+    /** Operation ID to transition */
+    operationId: string;
+    /** Expected current version (for CAS) */
+    expectedVersion: number;
+    /** Target status after transition */
+    to: OperationStatus;
+    /** Result data for terminal states */
+    resultSnapshot?: unknown;
+    /** Error message for failed operations */
+    error?: string;
+    /** Metadata for the transition event */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Result of a transition attempt
+ */
+export interface OperationTransitionResult {
+    /** True if transition succeeded */
+    transitioned: boolean;
+    /** Reason for failure (if transitioned = false) */
+    reason?: 'VERSION_CONFLICT' | 'INVALID_TRANSITION' | 'NOT_FOUND';
+    /** Current operation state (after transition or at rejection) */
+    operation: DurableOperation;
+}
+/**
+ * Validates operation admission inputs
+ */
+export declare function validateOperationAdmissionInput(input: OperationAdmissionInput): {
+    valid: boolean;
+    error?: string;
+};
+/**
+ * Checks if two operations conflict based on immutable semantics
+ */
+export declare function operationsConflict(existing: DurableOperation, requested: OperationAdmissionInput): IdempotencyConflictError | null;
+/**
+ * Generates a stable operation ID
+ * In production, use ULIDv7 for sortability and distributed uniqueness
+ */
+export declare function generateOperationId(): string;
+/**
+ * Validates that a transition is legal according to the state machine
+ */
+export declare function isValidTransition(fromStatus: OperationStatus, toStatus: OperationStatus): boolean;
+/**
+ * Checks if a status is a terminal state
+ */
+export declare function isTerminalStatus(status: OperationStatus): boolean;
+/**
+ * Validates transition input
+ */
+export declare function validateTransitionInput(input: OperationTransitionInput): {
+    valid: boolean;
+    error?: string;
+};
+/**
+ * Checks if a terminal transition is idempotent
+ * (same result data means it's the same transition, not a new one)
+ */
+export declare function isIdempotentTerminalTransition(existingOp: DurableOperation, requestedResult?: unknown, requestedError?: string): boolean;
+//# sourceMappingURL=operation-admission.d.ts.map

package/dist/operation-admission.d.ts.map

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

package/dist/operation-admission.js

@@ -0,0 +1,135 @@
+/**
+ * Atomic Idempotent Operation Admission
+ *
+ * Defines the durable operation admission contract for FeltDB.
+ * Guarantees: exactly one operation identity per idempotency key,
+ * atomic durability, and convergence across concurrent callers.
+ */
+/**
+ * Validates operation admission inputs
+ */
+export function validateOperationAdmissionInput(input) {
+    if (!input.idempotencyKey || typeof input.idempotencyKey !== 'string') {
+        return { valid: false, error: 'idempotencyKey must be a non-empty string' };
+    }
+    if (!input.kind || typeof input.kind !== 'string') {
+        return { valid: false, error: 'kind must be a non-empty string' };
+    }
+    if (input.idempotencyKey.length > 255) {
+        return { valid: false, error: 'idempotencyKey must be <= 255 characters' };
+    }
+    if (input.kind.length > 64) {
+        return { valid: false, error: 'kind must be <= 64 characters' };
+    }
+    if (input.operationFingerprint && input.operationFingerprint.length > 255) {
+        return { valid: false, error: 'operationFingerprint must be <= 255 characters' };
+    }
+    return { valid: true };
+}
+/**
+ * Checks if two operations conflict based on immutable semantics
+ */
+export function operationsConflict(existing, requested) {
+    // Same idempotencyKey must have same kind
+    if (existing.kind !== requested.kind) {
+        return {
+            code: 'IDEMPOTENCY_CONFLICT',
+            idempotencyKey: existing.idempotencyKey,
+            existingKind: existing.kind,
+            requestedKind: requested.kind,
+            message: `Operation kind mismatch for idempotencyKey "${existing.idempotencyKey}": existing="${existing.kind}", requested="${requested.kind}"`,
+        };
+    }
+    // If fingerprint is supplied, it must match
+    if (requested.operationFingerprint) {
+        if (existing.operationFingerprint !== requested.operationFingerprint) {
+            return {
+                code: 'IDEMPOTENCY_CONFLICT',
+                idempotencyKey: existing.idempotencyKey,
+                existingKind: existing.kind,
+                requestedKind: requested.kind,
+                existingFingerprint: existing.operationFingerprint,
+                requestedFingerprint: requested.operationFingerprint,
+                message: `Operation fingerprint mismatch for idempotencyKey "${existing.idempotencyKey}": existing="${existing.operationFingerprint}", requested="${requested.operationFingerprint}"`,
+            };
+        }
+    }
+    return null;
+}
+/**
+ * Generates a stable operation ID
+ * In production, use ULIDv7 for sortability and distributed uniqueness
+ */
+export function generateOperationId() {
+    // Format: timestamp (13 bytes) + random (12 bytes) = 25 chars
+    // For now, use a simple format; consider switching to proper ULID
+    const timestamp = Date.now();
+    const random = Math.random().toString(36).substring(2, 15) +
+        Math.random().toString(36).substring(2, 15);
+    return `op-${timestamp}-${random}`;
+}
+/**
+ * Legal state transitions in the operation lifecycle
+ *
+ * Invariant: Each successful transition increments version by exactly 1.
+ * Terminal states (completed, failed, cancelled) have no outgoing transitions.
+ */
+const LEGAL_TRANSITIONS = {
+    accepted: ['executing', 'cancelled'],
+    executing: ['completed', 'failed', 'cancelled'],
+    completed: [], // Terminal: no transitions allowed
+    failed: [], // Terminal: no transitions allowed
+    cancelled: [], // Terminal: no transitions allowed
+};
+/**
+ * Validates that a transition is legal according to the state machine
+ */
+export function isValidTransition(fromStatus, toStatus) {
+    const allowedTargets = LEGAL_TRANSITIONS[fromStatus] || [];
+    return allowedTargets.includes(toStatus);
+}
+/**
+ * Checks if a status is a terminal state
+ */
+export function isTerminalStatus(status) {
+    return ['completed', 'failed', 'cancelled'].includes(status);
+}
+/**
+ * Validates transition input
+ */
+export function validateTransitionInput(input) {
+    if (!input.operationId || typeof input.operationId !== 'string') {
+        return { valid: false, error: 'operationId must be a non-empty string' };
+    }
+    if (typeof input.expectedVersion !== 'number' || input.expectedVersion < 0) {
+        return { valid: false, error: 'expectedVersion must be a non-negative number' };
+    }
+    if (!input.to || typeof input.to !== 'string') {
+        return { valid: false, error: 'to must specify a target status' };
+    }
+    const validStatuses = ['accepted', 'executing', 'completed', 'failed', 'cancelled'];
+    if (!validStatuses.includes(input.to)) {
+        return { valid: false, error: `to must be one of: ${validStatuses.join(', ')}` };
+    }
+    return { valid: true };
+}
+/**
+ * Checks if a terminal transition is idempotent
+ * (same result data means it's the same transition, not a new one)
+ */
+export function isIdempotentTerminalTransition(existingOp, requestedResult, requestedError) {
+    // If operation is already in terminal state
+    if (!isTerminalStatus(existingOp.status)) {
+        return false; // Not a terminal op
+    }
+    // For completed operations, check result
+    if (existingOp.status === 'completed') {
+        return JSON.stringify(existingOp.resultSnapshot) === JSON.stringify(requestedResult);
+    }
+    // For failed operations, check error message
+    if (existingOp.status === 'failed') {
+        return existingOp.error === requestedError;
+    }
+    // For cancelled operations, idempotent
+    return true;
+}