@feltdb/core 0.4.17 → 0.5.0

package/dist/create/server-source/crates/feltdb-server/src/transaction_idempotency.rs

@@ -0,0 +1,280 @@
+use std::collections::HashMap;
+use std::sync::{Arc, Mutex};
+use serde::{Deserialize, Serialize};
+use sha2::{Digest, Sha256};
+
+/// Durable transaction idempotency: prevents re-execution of already-committed transactions.
+/// Every committed transaction is stored with its result. If the client retries with the
+/// same transaction_id + payload hash, the server returns the original result without re-executing.
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct CommittedTransaction {
+    pub transaction_id: String,
+    pub transaction_hash: String,
+    pub status: TransactionStatus,
+    pub committed_result: serde_json::Value,
+    pub commit_metadata: CommitMetadata,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+pub enum TransactionStatus {
+    #[serde(rename = "COMMITTED")]
+    Committed,
+    #[serde(rename = "CONFLICT")]
+    Conflict,
+    #[serde(rename = "VALIDATION_FAILED")]
+    ValidationFailed,
+    #[serde(rename = "INTERNAL_ERROR")]
+    InternalError,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct CommitMetadata {
+    pub timestamp_ms: u64,
+    pub revision_id: String,
+    pub application_id: String,
+    pub state_before: u64,
+    pub state_after: u64,
+    pub retry_count: usize,
+}
+
+pub struct TransactionIdempotencyStore {
+    // Map: transaction_id -> list of committed transactions (to detect hash mismatches)
+    store: Arc<Mutex<HashMap<String, Vec<CommittedTransaction>>>>,
+    max_per_transaction: usize,
+}
+
+impl TransactionIdempotencyStore {
+    pub fn new(max_per_transaction: usize) -> Self {
+        Self {
+            store: Arc::new(Mutex::new(HashMap::new())),
+            max_per_transaction,
+        }
+    }
+
+    /// Record a committed transaction for idempotency.
+    /// If the same transaction_id is seen again with the same hash, return the original result.
+    /// If the same transaction_id is seen with a different hash, return CONFLICT.
+    pub fn record_committed(
+        &self,
+        transaction_id: String,
+        transaction_hash: String,
+        status: TransactionStatus,
+        result: serde_json::Value,
+        metadata: CommitMetadata,
+    ) {
+        if let Ok(mut store) = self.store.lock() {
+            let tx_id_clone = transaction_id.clone();
+            let committed = CommittedTransaction {
+                transaction_id,
+                transaction_hash,
+                status,
+                committed_result: result,
+                commit_metadata: metadata,
+            };
+
+            store
+                .entry(tx_id_clone.clone())
+                .or_insert_with(Vec::new)
+                .push(committed);
+
+            // Keep only the most recent attempts
+            if let Some(entries) = store.get_mut(&tx_id_clone) {
+                if entries.len() > self.max_per_transaction {
+                    let to_remove = entries.len() - self.max_per_transaction;
+                    entries.drain(0..to_remove);
+                }
+            }
+        }
+    }
+
+    /// Check if a transaction has been seen before.
+    /// Returns:
+    /// - Some(Ok(result)) if same transaction_id + same hash (idempotent replay)
+    /// - Some(Err("CONFLICT")) if same transaction_id + different hash (reuse with different payload)
+    /// - None if this is a new transaction_id
+    pub fn check_idempotent(
+        &self,
+        transaction_id: &str,
+        transaction_hash: &str,
+    ) -> Option<Result<serde_json::Value, String>> {
+        self.store
+            .lock()
+            .ok()
+            .and_then(|store| store.get(transaction_id).map(|entries| entries.clone()))
+            .and_then(|entries| {
+                if entries.is_empty() {
+                    return None;
+                }
+
+                let first_entry = &entries[0];
+
+                // If hashes match, return the original result
+                if first_entry.transaction_hash == transaction_hash {
+                    return Some(Ok(first_entry.committed_result.clone()));
+                }
+
+                // If hashes differ, it's a conflict (transaction ID reused with different payload)
+                Some(Err(format!(
+                    "Transaction ID {} reused with different payload",
+                    transaction_id
+                )))
+            })
+    }
+
+    /// Get all committed transactions for a transaction_id
+    pub fn get_history(&self, transaction_id: &str) -> Vec<CommittedTransaction> {
+        self.store
+            .lock()
+            .ok()
+            .and_then(|store| store.get(transaction_id).cloned())
+            .unwrap_or_default()
+    }
+
+    /// Clear all idempotency records (for testing)
+    pub fn clear(&self) {
+        if let Ok(mut store) = self.store.lock() {
+            store.clear();
+        }
+    }
+
+    /// Get statistics about idempotency store
+    pub fn statistics(&self) -> IdempotencyStatistics {
+        self.store
+            .lock()
+            .ok()
+            .map(|store| {
+                let total_transactions = store.len();
+                let total_entries = store.values().map(|v| v.len()).sum();
+                let replay_protected = store
+                    .values()
+                    .filter(|entries| !entries.is_empty() && entries[0].status == TransactionStatus::Committed)
+                    .count();
+
+                IdempotencyStatistics {
+                    total_transaction_ids: total_transactions,
+                    total_committed_entries: total_entries,
+                    replay_protected_count: replay_protected,
+                }
+            })
+            .unwrap_or_default()
+    }
+}
+
+#[derive(Debug, Clone, Serialize, Default)]
+pub struct IdempotencyStatistics {
+    pub total_transaction_ids: usize,
+    pub total_committed_entries: usize,
+    pub replay_protected_count: usize,
+}
+
+/// Compute a hash of a transaction request for idempotency detection.
+pub fn hash_transaction_request(request: &serde_json::Value) -> String {
+    let mut hasher = Sha256::new();
+    let json_str = serde_json::to_string(request).unwrap_or_default();
+    hasher.update(json_str.as_bytes());
+    format!("{:x}", hasher.finalize())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_idempotency_store_same_hash() {
+        let store = TransactionIdempotencyStore::new(10);
+        let tx_id = "tx-123".to_string();
+        let tx_hash = "hash-abc".to_string();
+        let result = serde_json::json!({ "status": "committed" });
+
+        store.record_committed(
+            tx_id.clone(),
+            tx_hash.clone(),
+            TransactionStatus::Committed,
+            result.clone(),
+            CommitMetadata {
+                timestamp_ms: 1000,
+                revision_id: "rev-1".to_string(),
+                application_id: "app-1".to_string(),
+                state_before: 1,
+                state_after: 2,
+                retry_count: 0,
+            },
+        );
+
+        // First replay should return the same result
+        let replay = store.check_idempotent(&tx_id, &tx_hash);
+        assert!(replay.is_some());
+        assert!(replay.unwrap().is_ok());
+    }
+
+    #[test]
+    fn test_idempotency_store_different_hash() {
+        let store = TransactionIdempotencyStore::new(10);
+        let tx_id = "tx-456".to_string();
+        let tx_hash_1 = "hash-1".to_string();
+        let tx_hash_2 = "hash-2".to_string();
+        let result = serde_json::json!({ "status": "committed" });
+
+        store.record_committed(
+            tx_id.clone(),
+            tx_hash_1.clone(),
+            TransactionStatus::Committed,
+            result,
+            CommitMetadata {
+                timestamp_ms: 1000,
+                revision_id: "rev-1".to_string(),
+                application_id: "app-1".to_string(),
+                state_before: 1,
+                state_after: 2,
+                retry_count: 0,
+            },
+        );
+
+        // Replay with different hash should fail
+        let replay = store.check_idempotent(&tx_id, &tx_hash_2);
+        assert!(replay.is_some());
+        assert!(replay.unwrap().is_err());
+    }
+
+    #[test]
+    fn test_hash_transaction_request() {
+        let request1 = serde_json::json!({ "id": "test", "value": 123 });
+        let request2 = serde_json::json!({ "id": "test", "value": 123 });
+        let request3 = serde_json::json!({ "id": "test", "value": 456 });
+
+        let hash1 = hash_transaction_request(&request1);
+        let hash2 = hash_transaction_request(&request2);
+        let hash3 = hash_transaction_request(&request3);
+
+        assert_eq!(hash1, hash2); // Same content = same hash
+        assert_ne!(hash1, hash3); // Different content = different hash
+    }
+
+    #[test]
+    fn test_idempotency_statistics() {
+        let store = TransactionIdempotencyStore::new(10);
+
+        for i in 0..5 {
+            store.record_committed(
+                format!("tx-{}", i),
+                "hash-abc".to_string(),
+                TransactionStatus::Committed,
+                serde_json::json!({}),
+                CommitMetadata {
+                    timestamp_ms: 1000,
+                    revision_id: "rev-1".to_string(),
+                    application_id: "app-1".to_string(),
+                    state_before: 1,
+                    state_after: 2,
+                    retry_count: 0,
+                },
+            );
+        }
+
+        let stats = store.statistics();
+        assert_eq!(stats.total_transaction_ids, 5);
+        assert_eq!(stats.total_committed_entries, 5);
+        assert_eq!(stats.replay_protected_count, 5);
+    }
+}

package/dist/error-codes.d.ts

@@ -0,0 +1,53 @@
+/**
+ * FeltDB Deterministic Error Codes
+ *
+ * All FeltDB API responses use these semantic error codes.
+ * Never returns empty {} or untyped errors.
+ *
+ * Clients must handle each code appropriately:
+ * - CONFLICT: Retry with backoff (CAS mismatch)
+ * - PRECONDITION_FAILED: Do not retry (validation error)
+ * - TOO_BUSY: Retry with exponential backoff (queue full)
+ * - INTERNAL_ERROR: Log and escalate (server error)
+ */
+/**
+ * Semantic error codes matching HTTP status codes
+ */
+export declare enum FeltDBErrorCode {
+    /** 200: Request succeeded */
+    OK = "OK",
+    /** 409: Version conflict; concurrent writer won; retry intelligently */
+    CONFLICT = "CONFLICT",
+    /** 422: Validation or precondition failed; do not retry */
+    PRECONDITION_FAILED = "PRECONDITION_FAILED",
+    /** 429: Queue depth exceeded; retry with exponential backoff */
+    TOO_BUSY = "TOO_BUSY",
+    /** 500: Unrecoverable server error; audit trail available */
+    INTERNAL_ERROR = "INTERNAL_ERROR"
+}
+/**
+ * Error response structure that all FeltDB APIs must return
+ */
+export interface FeltDBErrorResponse {
+    /** Semantic error code (never empty) */
+    code: FeltDBErrorCode | string;
+    /** Human-readable message explaining what happened */
+    message: string;
+    /** Unique request ID for debugging/auditing */
+    request_id: string;
+    /** Transaction ID if applicable */
+    transaction_id?: string;
+    /** HTTP status code for routing */
+    http_status: number;
+    /** Recovery hint for client ("retry", "fail", "queue", etc.) */
+    recovery_hint?: 'retry_backoff' | 'dont_retry' | 'check_queue_depth' | 'contact_support';
+}
+/**
+ * Determines if a FeltDB error is retryable
+ */
+export declare function isRetryableError(code: FeltDBErrorCode | string): boolean;
+/**
+ * Determines retry strategy based on error code
+ */
+export declare function getRetryStrategy(code: FeltDBErrorCode | string): 'exponential_backoff' | 'linear_backoff' | 'dont_retry';
+//# sourceMappingURL=error-codes.d.ts.map

package/dist/error-codes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-codes.d.ts","sourceRoot":"","sources":["../src/error-codes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH;;GAEG;AACH,oBAAY,eAAe;IACzB,6BAA6B;IAC7B,EAAE,OAAO;IAET,wEAAwE;IACxE,QAAQ,aAAa;IAErB,2DAA2D;IAC3D,mBAAmB,wBAAwB;IAE3C,gEAAgE;IAChE,QAAQ,aAAa;IAErB,6DAA6D;IAC7D,cAAc,mBAAmB;CAClC;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,wCAAwC;IACxC,IAAI,EAAE,eAAe,GAAG,MAAM,CAAC;IAE/B,sDAAsD;IACtD,OAAO,EAAE,MAAM,CAAC;IAEhB,+CAA+C;IAC/C,UAAU,EAAE,MAAM,CAAC;IAEnB,mCAAmC;IACnC,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB,mCAAmC;IACnC,WAAW,EAAE,MAAM,CAAC;IAEpB,gEAAgE;IAChE,aAAa,CAAC,EAAE,eAAe,GAAG,YAAY,GAAG,mBAAmB,GAAG,iBAAiB,CAAC;CAC1F;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,eAAe,GAAG,MAAM,GAAG,OAAO,CAExE;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,eAAe,GAAG,MAAM,GAAG,qBAAqB,GAAG,gBAAgB,GAAG,YAAY,CAQxH"}

package/dist/error-codes.js

@@ -0,0 +1,46 @@
+/**
+ * FeltDB Deterministic Error Codes
+ *
+ * All FeltDB API responses use these semantic error codes.
+ * Never returns empty {} or untyped errors.
+ *
+ * Clients must handle each code appropriately:
+ * - CONFLICT: Retry with backoff (CAS mismatch)
+ * - PRECONDITION_FAILED: Do not retry (validation error)
+ * - TOO_BUSY: Retry with exponential backoff (queue full)
+ * - INTERNAL_ERROR: Log and escalate (server error)
+ */
+/**
+ * Semantic error codes matching HTTP status codes
+ */
+export var FeltDBErrorCode;
+(function (FeltDBErrorCode) {
+    /** 200: Request succeeded */
+    FeltDBErrorCode["OK"] = "OK";
+    /** 409: Version conflict; concurrent writer won; retry intelligently */
+    FeltDBErrorCode["CONFLICT"] = "CONFLICT";
+    /** 422: Validation or precondition failed; do not retry */
+    FeltDBErrorCode["PRECONDITION_FAILED"] = "PRECONDITION_FAILED";
+    /** 429: Queue depth exceeded; retry with exponential backoff */
+    FeltDBErrorCode["TOO_BUSY"] = "TOO_BUSY";
+    /** 500: Unrecoverable server error; audit trail available */
+    FeltDBErrorCode["INTERNAL_ERROR"] = "INTERNAL_ERROR";
+})(FeltDBErrorCode || (FeltDBErrorCode = {}));
+/**
+ * Determines if a FeltDB error is retryable
+ */
+export function isRetryableError(code) {
+    return code === FeltDBErrorCode.CONFLICT || code === FeltDBErrorCode.TOO_BUSY;
+}
+/**
+ * Determines retry strategy based on error code
+ */
+export function getRetryStrategy(code) {
+    if (code === FeltDBErrorCode.CONFLICT) {
+        return 'exponential_backoff';
+    }
+    if (code === FeltDBErrorCode.TOO_BUSY) {
+        return 'exponential_backoff';
+    }
+    return 'dont_retry';
+}

package/dist/feltdb.d.ts

@@ -85,6 +85,10 @@ export interface JsDb {
         updated: boolean;
         currentVersion: number;
     }>;
+    /** Atomic idempotent operation admission: durably admit unique operations. */
+    admitOperation?(input: any): Promise<any>;
+    /** Atomic operation lifecycle transition: versioned conditional state changes. */
+    transitionOperation?(input: any): Promise<any>;
 }
 /**
  * A row stored in the database

package/dist/feltdb.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"feltdb.d.ts","sourceRoot":"","sources":["../src/feltdb.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;GAEG;AACH,MAAM,WAAW,IAAI;IACnB;;OAEG;IACH,UAAU,CAAC,SAAS,EAAE,GAAG,GAAG,GAAG,CAAC;IAEhC;;OAEG;IACH,SAAS,IAAI,GAAG,CAAC;IAEjB;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,GAAG,CAAC;IAE/B;;OAEG;IACH,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,GAAG,CAAC;IAEpC;;OAEG;IACH,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,GAAG,CAAC;IAEvC;;OAEG;IACH,oBAAoB,CAAC,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,GAAG,CAAC;IAEnE;;OAEG;IACH,2BAA2B,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,GAAG,CAAC;IAEpE;;OAEG;IACH,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAEzC;;OAEG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAErC;;OAEG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAEvD,6DAA6D;IAC7D,MAAM,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAExD,qDAAqD;IACrD,MAAM,CAAC,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAEzC,2EAA2E;IAC3E,iBAAiB,CAAC,CAAC,QAAQ,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,IAAI,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,IAAI,CAAC;IAC5F,KAAK,CAAC,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE/B;;OAEG;IACH,sBAAsB,CAAC,UAAU,EAAE,MAAM,GAAG,GAAG,CAAC;IAEhD;;OAEG;IACH,WAAW,IAAI,MAAM,CAAC;IAEtB;;OAEG;IACH,YAAY,IAAI,MAAM,CAAC;IAEvB,0EAA0E;IAC1E,YAAY,CAAC,IAAI,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAEpC,6DAA6D;IAC7D,iBAAiB,CAAC,CAAC,cAAc,EAAE,MAAM,GAAG,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAC/D,uBAAuB,CAAC,CAAC,UAAU,EAAE,GAAG,EAAE,GAAG,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAEhE,oEAAoE;IACpE,WAAW,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,QAAQ,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAExF,kEAAkE;IAClE,GAAG,CAAC,CAAC,MAAM,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,eAAe,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,cAAc,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC9H;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,GAAG,MAAM,CAAC;IACpB,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACpB"}
+{"version":3,"file":"feltdb.d.ts","sourceRoot":"","sources":["../src/feltdb.ts"],"names":[],"mappings":"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"}

package/dist/file-db.d.ts

@@ -1,4 +1,5 @@
 import type { JsDb } from './feltdb.js';
+import type { OperationAdmissionInput, OperationAdmissionResult, OperationTransitionInput, OperationTransitionResult } from './operation-admission.js';
 interface JsResult {
     success: boolean;
     data?: string;
@@ -61,6 +62,8 @@ export declare class FileJsDb implements JsDb {
         inserted: boolean;
         value: string;
     }>;
+    admitOperation(input: OperationAdmissionInput): Promise<OperationAdmissionResult>;
+    transitionOperation(input: OperationTransitionInput): Promise<OperationTransitionResult>;
     cas(params: {
         key: string;
         expectedVersion: number;

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

@@ -1 +1 @@
-{"version":3,"file":"file-db.d.ts","sourceRoot":"","sources":["../src/file-db.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AAmDxC,UAAU,QAAQ;IAChB,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,UAAU,aAAa;IAAG,QAAQ,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,KAAK,GAAG,QAAQ,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE;AAyBrK,qBAAa,QAAS,YAAW,IAAI;IACnC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,KAAK,CAAc;IAC3B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAqB;IAC3C,OAAO,CAAC,MAAM,CAAuB;gBAEzB,IAAI,EAAE,MAAM;IAgCxB,OAAO,CAAC,SAAS;IAiCjB,OAAO,CAAC,eAAe;IAYvB,OAAO,CAAC,YAAY;IAMpB,OAAO,CAAC,WAAW;IAuBnB,OAAO,CAAC,gBAAgB;YAWV,gBAAgB;IA6B9B,OAAO,CAAC,gBAAgB;IAYxB,OAAO,CAAC,SAAS;IAkCjB,OAAO,CAAC,KAAK;IAeb,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,QAAQ;IAa5C,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,QAAQ;IAO5C,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,QAAQ;IAO1B,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,QAAQ;IAW7B,KAAK,CAAC,UAAU,EAAE,MAAM,GAAG,QAAQ;IAQnC,sBAAsB,CAAC,UAAU,EAAE,MAAM,GAAG,QAAQ;IAIpD,UAAU,IAAI,QAAQ;IAItB,SAAS,IAAI,QAAQ;IAiBrB,QAAQ,IAAI,QAAQ;IAIpB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,QAAQ;IAKvC,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,QAAQ;IAK1C,2BAA2B,IAAI,QAAQ;IAIvC,oBAAoB,IAAI,QAAQ;IAIhC,WAAW,IAAI,MAAM;IAIrB,YAAY,IAAI,MAAM;IAItB,YAAY;IAIZ,iBAAiB,CAAC,aAAa,EAAE,MAAM;IAIvC,uBAAuB,CAAC,UAAU,EAAE,aAAa,EAAE;;;;IA0C7C,gBAAgB,CAAC,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,CAAC;IAS7E,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,QAAQ,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAwCtF,GAAG,CAAC,MAAM,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,eAAe,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,cAAc,EAAE,MAAM,CAAA;KAAE,CAAC;IAoCjI,KAAK,IAAI,IAAI;CAId"}
+{"version":3,"file":"file-db.d.ts","sourceRoot":"","sources":["../src/file-db.ts"],"names":[],"mappings":"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"}

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;
@@ -399,6 +400,135 @@ export class FileJsDb {
             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 {
+                admitted: result.inserted,
+                operationId: existingOperation.operationId,
+                operation: existingOperation,
+            };
+        }
+        catch (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) {
         try {
             const parsed = JSON.parse(params.value);

package/dist/index.d.ts

@@ -31,6 +31,9 @@ export * from './file-db.js';
 export * from './flowspec.js';
 export * from './application-manifest.js';
 export * from './state-contract.js';
+export * from './revision-recovery.js';
+export * from './operation-admission.js';
+export * from './error-codes.js';
 export * from './authorization.js';
 export * from './sync-contract.js';
 export * from './workload.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,cAAc,SAAS,CAAC;AACxB,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC;AACpC,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC;AACrC,cAAc,wBAAwB,CAAC;AACvC,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,2BAA2B,CAAC;AAC1C,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,2BAA2B,CAAC;AAC1C,OAAO,EACL,eAAe,EACf,KAAK,OAAO,EACZ,KAAK,SAAS,IAAI,iBAAiB,EACnC,KAAK,QAAQ,IAAI,gBAAgB,GAClC,MAAM,eAAe,CAAC;AAEvB;;GAEG;AACH,cAAc,YAAY,CAAC;AAC3B,cAAc,wBAAwB,CAAC;AACvC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AAEnC;;GAEG;AACH,YAAY,EACV,eAAe,EACf,cAAc,EACd,cAAc,EACd,kBAAkB,EAClB,kBAAkB,GACnB,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,cAAc,SAAS,CAAC;AACxB,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC;AACpC,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC;AACrC,cAAc,wBAAwB,CAAC;AACvC,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,2BAA2B,CAAC;AAC1C,cAAc,qBAAqB,CAAC;AACpC,cAAc,wBAAwB,CAAC;AACvC,cAAc,0BAA0B,CAAC;AACzC,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,2BAA2B,CAAC;AAC1C,OAAO,EACL,eAAe,EACf,KAAK,OAAO,EACZ,KAAK,SAAS,IAAI,iBAAiB,EACnC,KAAK,QAAQ,IAAI,gBAAgB,GAClC,MAAM,eAAe,CAAC;AAEvB;;GAEG;AACH,cAAc,YAAY,CAAC;AAC3B,cAAc,wBAAwB,CAAC;AACvC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AAEnC;;GAEG;AACH,YAAY,EACV,eAAe,EACf,cAAc,EACd,cAAc,EACd,kBAAkB,EAClB,kBAAkB,GACnB,MAAM,SAAS,CAAC"}

package/dist/index.js

@@ -31,6 +31,9 @@ export * from './file-db.js';
 export * from './flowspec.js';
 export * from './application-manifest.js';
 export * from './state-contract.js';
+export * from './revision-recovery.js';
+export * from './operation-admission.js';
+export * from './error-codes.js';
 export * from './authorization.js';
 export * from './sync-contract.js';
 export * from './workload.js';