@feltdb/core 0.4.20 → 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/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';

package/dist/revision-recovery.d.ts

@@ -0,0 +1,162 @@
+/**
+ * Revision Recovery: Audited Recovery from Invalid Historical Revisions
+ *
+ * Provides mechanisms to safely recover from corrupt/invalid historical revisions
+ * under strict safety constraints and comprehensive audit trail requirements.
+ */
+/**
+ * Authorization level required for revision recovery operations
+ */
+export type RecoveryAuthorization = 'ELEVATED' | 'ADMIN' | 'EMERGENCY';
+/**
+ * Compatibility classification for manifest changes
+ */
+export type CompatibilityClassification = 'COMPATIBLE' | 'WARNING' | 'INCOMPATIBLE';
+/**
+ * Recovery mode indicating what was approved
+ */
+export type RecoveryMode = 'SAFE_COMPATIBLE' | 'WARNING_APPROVED' | 'DESTRUCTIVE_APPROVED';
+/**
+ * Input for recovering an application revision
+ */
+export interface RevisionRecoveryInput {
+    /** Application ID being recovered */
+    applicationId: string;
+    /** Current revision that is invalid/corrupt (must match actual current) */
+    expectedCurrentRevision: string;
+    /** Target revision to promote to (must be valid and integrity-checked) */
+    targetRevision: string;
+    /** Elevated authorization level required */
+    authorization: RecoveryAuthorization;
+    /** Actor (user/service) approving recovery */
+    actor: string;
+    /** Explicit reason for recovery */
+    reason: string;
+    /** Environment being recovered */
+    environment?: string;
+    /** Allow destructive schema changes if compatibility check requires it */
+    allowDestructiveChange?: boolean;
+    /** Explicit reason for approving destructive changes (required if allowDestructiveChange=true) */
+    destructiveChangeReason?: string;
+    /** Idempotency key for recovery operation */
+    recoveryId?: string;
+}
+/**
+ * Audit record for a completed revision recovery
+ */
+export interface RevisionRecoveryAudit {
+    /** Unique audit record ID */
+    auditId: string;
+    /** Application being recovered */
+    applicationId: string;
+    /** Source (corrupt) revision being abandoned */
+    sourceRevision: string;
+    /** Recomputed hash of source revision (for verification) */
+    sourceRevisionHash: string;
+    /** Target revision being promoted to */
+    targetRevision: string;
+    /** Hash of target revision */
+    targetRevisionHash: string;
+    /** Hash of previous audit record in chain (for immutability) */
+    previousAuditHash?: string;
+    /** Hash of this audit record */
+    auditHash: string;
+    /** Actor who approved recovery */
+    approvedBy: string;
+    /** Recovery reason provided */
+    reason: string;
+    /** Authorization level that was required */
+    authorizationLevel: RecoveryAuthorization;
+    /** Mode of recovery (what was approved) */
+    recoveryMode: RecoveryMode;
+    /** Compatibility classification from diff analysis */
+    compatibilityClassification: CompatibilityClassification;
+    /** Detailed compatibility issues found (if any) */
+    compatibilityIssues?: string[];
+    /** Destructive change approval reason (if applicable) */
+    destructiveChangeReason?: string;
+    /** Timestamp of recovery */
+    recoveredAt: number;
+    /** Idempotency key for the recovery operation */
+    recoveryId: string;
+    /** Status of recovery operation */
+    status: 'COMPLETED' | 'PARTIAL' | 'ROLLED_BACK';
+    /** Marker indicating source revision must never be moved back to */
+    markedUntrustedUntilRevision: string;
+}
+/**
+ * Result of a revision recovery attempt
+ */
+export interface RevisionRecoveryResult {
+    /** Whether recovery succeeded */
+    success: boolean;
+    /** Error code if recovery failed */
+    errorCode?: 'PERMISSION_DENIED' | 'CONFLICT' | 'INCOMPATIBLE_SCHEMA' | 'CORRUPT_REVISION_UNMOVABLE' | 'STORAGE_FAILURE' | 'VALIDATION_FAILED';
+    /** Human-readable error message */
+    errorMessage?: string;
+    /** Audit record created (present if recovery succeeds or partially completes) */
+    audit?: RevisionRecoveryAudit;
+    /** Current revision pointer after recovery attempt */
+    currentRevision: string;
+    /** Whether audit record was durable persisted */
+    auditDurable: boolean;
+    /** Pointer was successfully moved to target */
+    pointerMoved: boolean;
+    /** Source revision was marked untrusted */
+    sourceMarkedUntrusted: boolean;
+}
+/**
+ * Revision state tracking for corrupt/untrusted revisions
+ */
+export interface RevisionState {
+    /** Revision ID */
+    revisionId: string;
+    /** Whether revision is valid/trusted */
+    trusted: boolean;
+    /** Marker: any revision equal to or before this cannot be promoted to */
+    untrustedUntilRevision?: string;
+    /** Reason revision was marked untrusted (if applicable) */
+    untrustedReason?: string;
+    /** Timestamp when marked untrusted */
+    markedUntrustedAt?: number;
+    /** Reference to recovery audit that marked it untrusted */
+    recoveryAuditId?: string;
+}
+/**
+ * Compatibility check result
+ */
+export interface CompatibilityCheckResult {
+    /** Overall compatibility classification */
+    classification: CompatibilityClassification;
+    /** List of specific issues or warnings found */
+    issues: Array<{
+        category: 'SCHEMA_CHANGE' | 'DATA_LOSS' | 'REFERENCE_BREAKING' | 'INDEX_REMOVAL';
+        severity: 'WARNING' | 'INCOMPATIBLE';
+        detail: string;
+    }>;
+    /** Whether any data loss would occur */
+    causesDataLoss: boolean;
+    /** Whether this is a breaking change */
+    isBreakingChange: boolean;
+    /** Recommended action */
+    recommendation: string;
+}
+/**
+ * Validates revision recovery input
+ */
+export declare function validateRevisionRecoveryInput(input: RevisionRecoveryInput): {
+    valid: boolean;
+    error?: string;
+};
+/**
+ * Generates cryptographic hash for audit record chain
+ */
+export declare function generateAuditHash(data: Record<string, unknown>, previousHash?: string): string;
+/**
+ * Checks if a revision pointer transition would violate untrust markers
+ */
+export declare function wouldViolateUntrustworthiness(fromRevision: string, toRevision: string, revisionStates: Map<string, RevisionState>): {
+    violates: boolean;
+    reason?: string;
+};
+//# sourceMappingURL=revision-recovery.d.ts.map

package/dist/revision-recovery.d.ts.map

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

package/dist/revision-recovery.js

@@ -0,0 +1,69 @@
+/**
+ * Revision Recovery: Audited Recovery from Invalid Historical Revisions
+ *
+ * Provides mechanisms to safely recover from corrupt/invalid historical revisions
+ * under strict safety constraints and comprehensive audit trail requirements.
+ */
+/**
+ * Validates revision recovery input
+ */
+export function validateRevisionRecoveryInput(input) {
+    if (!input.applicationId || typeof input.applicationId !== 'string') {
+        return { valid: false, error: 'applicationId must be a non-empty string' };
+    }
+    if (!input.expectedCurrentRevision || typeof input.expectedCurrentRevision !== 'string') {
+        return { valid: false, error: 'expectedCurrentRevision must be a non-empty string' };
+    }
+    if (!input.targetRevision || typeof input.targetRevision !== 'string') {
+        return { valid: false, error: 'targetRevision must be a non-empty string' };
+    }
+    if (!input.authorization || !['ELEVATED', 'ADMIN', 'EMERGENCY'].includes(input.authorization)) {
+        return { valid: false, error: 'authorization must be ELEVATED, ADMIN, or EMERGENCY' };
+    }
+    if (!input.actor || typeof input.actor !== 'string') {
+        return { valid: false, error: 'actor must be a non-empty string' };
+    }
+    if (!input.reason || typeof input.reason !== 'string' || input.reason.length < 10) {
+        return { valid: false, error: 'reason must be a string with at least 10 characters' };
+    }
+    if (input.expectedCurrentRevision === input.targetRevision) {
+        return { valid: false, error: 'expectedCurrentRevision and targetRevision must be different' };
+    }
+    if (input.allowDestructiveChange === true) {
+        if (!input.destructiveChangeReason || typeof input.destructiveChangeReason !== 'string' || input.destructiveChangeReason.length < 10) {
+            return { valid: false, error: 'destructiveChangeReason must be provided and at least 10 characters when allowDestructiveChange=true' };
+        }
+    }
+    return { valid: true };
+}
+/**
+ * Generates cryptographic hash for audit record chain
+ */
+export function generateAuditHash(data, previousHash) {
+    // In production, use SHA-256 or similar
+    // For now, use a simple hash based on JSON serialization
+    const payload = JSON.stringify({ ...data, previousHash });
+    // Use Buffer for Node.js, or btoa for browser environments
+    const encoded = typeof btoa !== 'undefined'
+        ? btoa(payload)
+        : Buffer.from(payload).toString('base64');
+    return encoded.substring(0, 64);
+}
+/**
+ * Checks if a revision pointer transition would violate untrust markers
+ */
+export function wouldViolateUntrustworthiness(fromRevision, toRevision, revisionStates) {
+    const state = revisionStates.get(fromRevision);
+    if (!state || !state.untrustedUntilRevision) {
+        return { violates: false };
+    }
+    // Check if trying to move back to or through an untrusted revision
+    // This is a simplified check; production would need proper revision ordering
+    if (toRevision === state.untrustedUntilRevision || state.untrustedUntilRevision === fromRevision) {
+        return {
+            violates: true,
+            reason: `Revision ${fromRevision} is marked untrusted and cannot be moved back to`,
+        };
+    }
+    return { violates: false };
+}

package/dist/state-contract.d.ts

@@ -1,3 +1,4 @@
+import { RevisionRecoveryInput, RevisionRecoveryResult } from './revision-recovery';
 /** Transport types for the Rust-owned FeltDB state contract. */
 export type PrimitiveType = 'string' | 'integer' | 'number' | 'boolean' | 'timestamp' | 'date' | 'time' | 'json' | 'uuid' | 'decimal' | 'money' | 'bigint' | 'email' | 'url' | 'phone' | 'binary' | 'file' | 'geo_point' | 'object';
 export type FieldType = {
@@ -174,6 +175,7 @@ export declare class StateContractClient {
         transactionId?: string;
         causalParent?: number;
     }): Promise<TransactionResult>;
+    recoverApplicationRevision(input: RevisionRecoveryInput): Promise<RevisionRecoveryResult>;
 }
 export {};
 //# sourceMappingURL=state-contract.d.ts.map