@feltdb/core 0.4.20 → 0.5.1

package/README.md

@@ -75,6 +75,185 @@ Browser mutations resolve after their IndexedDB transaction commits. The
 durable change journal replays after reload and coordinates live collections
 across tabs through `BroadcastChannel` when available.
 
+## Durable Operation Management
+
+FeltDB provides atomic operation admission and lifecycle management for systems that need to survive process crashes with guaranteed identity stability.
+
+### Admit Operations (with atomic identity)
+
+Guarantee: **exactly-once operation identity** across process crashes and concurrent callers.
+
+```typescript
+import { OperationAdmissionInput, DurableOperation } from '@feltdb/core';
+
+const db = createFeltDB({ namespace: 'my-app', path: './state' });
+
+const result = await db.admitOperation({
+  idempotencyKey: 'payment-123',
+  kind: 'payment-processing',
+  metadata: { amount: 99.99, currency: 'USD' }
+});
+
+// Same idempotencyKey always returns same operationId
+console.log(result.operationId);  // 'op-xxx-yyy' (stable)
+console.log(result.admitted);      // true if this caller admitted it, false if already existed
+```
+
+### Transition Operations (atomic lifecycle)
+
+Guarantee: **all-or-nothing state transitions** with version-based Compare-And-Set semantics.
+
+```typescript
+import { OperationTransitionInput } from '@feltdb/core';
+
+const transition = await db.transitionOperation({
+  operationId: 'op-xxx-yyy',
+  expectedVersion: 0,
+  to: 'executing',
+  metadata: { started_at: Date.now() }
+});
+
+if (transition.transitioned) {
+  // We won the transition race
+  console.log('Now executing...');
+  
+  // Do work...
+  
+  // Complete the operation
+  await db.transitionOperation({
+    operationId: 'op-xxx-yyy',
+    expectedVersion: 1,
+    to: 'completed',
+    resultSnapshot: { paymentId: 'pay-456', timestamp: Date.now() }
+  });
+} else if (transition.reason === 'VERSION_CONFLICT') {
+  // Another process already transitioned this operation
+  console.log('Conflict - another process is handling this');
+  console.log('Current status:', transition.operation.status);
+}
+```
+
+Operation lifecycle: `accepted` → `executing` → (`completed` | `failed` | `cancelled`)
+
+Terminal states (`completed`, `failed`, `cancelled`) cannot be transitioned from.
+
+### Recover Revisions (audited recovery from corruption)
+
+Guarantee: **audit trail with permanent untrust markers**, no silent rollback.
+
+```typescript
+import { StateContractClient, RevisionRecoveryInput } from '@feltdb/core';
+
+const client = new StateContractClient({
+  applicationId: 'my-app',
+  revisionId: 'rev-clean-122',
+  environment: 'staging'
+});
+
+const recovery = await client.recoverApplicationRevision({
+  applicationId: 'my-app',
+  expectedCurrentRevision: 'rev-corrupted-123',
+  targetRevision: 'rev-clean-122',
+  authorization: 'ELEVATED',
+  actor: 'sherpa-admission',
+  reason: 'Replace corrupt historical revision',
+  environment: 'staging',
+  recoveryId: 'sherpa-staging-recovery-v1'
+});
+
+// Result includes:
+// - pointerMoved: Environment pointer moved to valid revision
+// - sourceMarkedUntrusted: Corrupt revision permanently marked untrusted
+// - auditDurable: Immutable audit trail persisted
+console.log(recovery.pointerMoved);        // true
+console.log(recovery.sourceMarkedUntrusted);  // true
+console.log(recovery.auditDurable);        // true
+```
+
+### Operation Types
+
+```typescript
+import {
+  OperationAdmissionInput,
+  OperationAdmissionResult,
+  DurableOperation,
+  OperationStatus,
+  OperationTransitionInput,
+  OperationTransitionResult,
+} from '@feltdb/core';
+```
+
+## Error Semantics
+
+All FeltDB APIs return **deterministic, semantic error codes** (never empty `{}`).
+
+### Error Codes
+
+```typescript
+import { FeltDBErrorCode } from '@feltdb/core';
+
+try {
+  await db.transitionOperation({ ... });
+} catch (error) {
+  const felt_error = error.feltdb_error;
+  
+  switch (felt_error.code) {
+    case FeltDBErrorCode.CONFLICT:
+      // Version mismatch; another process won the race
+      // → Retry with exponential backoff
+      console.log('Conflict; retrying...');
+      break;
+    
+    case FeltDBErrorCode.PRECONDITION_FAILED:
+      // Validation or precondition error
+      // → Do not retry; fix the input
+      console.log('Validation error:', felt_error.message);
+      break;
+    
+    case FeltDBErrorCode.TOO_BUSY:
+      // Queue depth exceeded
+      // → Retry with exponential backoff
+      console.log('Server busy; retrying...');
+      break;
+    
+    case FeltDBErrorCode.INTERNAL_ERROR:
+      // Server error
+      // → Log and escalate; audit trail in request_id
+      console.log('Server error:', felt_error.request_id);
+      break;
+  }
+}
+```
+
+### Error Response Structure
+
+```typescript
+import { FeltDBErrorResponse } from '@feltdb/core';
+
+interface FeltDBErrorResponse {
+  code: FeltDBErrorCode | string;           // Semantic code (CONFLICT, PRECONDITION_FAILED, etc.)
+  message: string;                          // Human-readable message
+  request_id: string;                       // Unique ID for debugging
+  transaction_id?: string;                  // If applicable
+  http_status: number;                      // HTTP status for routing
+  recovery_hint?: 'retry_backoff' | 'dont_retry' | 'check_queue_depth' | 'contact_support';
+}
+```
+
+### Error Handling Utilities
+
+```typescript
+import { isRetryableError, getRetryStrategy } from '@feltdb/core';
+
+// Check if error should be retried
+if (isRetryableError(error.feltdb_error.code)) {
+  const strategy = getRetryStrategy(error.feltdb_error.code);
+  if (strategy === 'exponential_backoff') {
+    // Wait with exponential backoff before retry
+  }
+}
+```
+
 ## Concurrency Model
 
 FeltDB 0.4.3 uses a **single-writer, multi-reader** model:

package/dist/cli/index.js

@@ -23,7 +23,7 @@ import * as path from 'path';
 import * as readline from 'readline';
 import { getClient } from './api-client.js';
 import { loadFeltDBConfig, createDefaultConfig, validateModel, } from './config.js';
-const VERSION = '0.4.20';
+const VERSION = '0.5.1';
 function prompt(question) {
     const rl = readline.createInterface({
         input: process.stdin,

package/dist/collection.d.ts

@@ -11,6 +11,20 @@ import type { JsDb } from './feltdb.js';
 import type { IndexConfig } from './index-types.js';
 export type Predicate<T> = (item: T) => boolean;
 export type Subscriber<T> = (items: T[]) => void;
+/**
+ * Result of an atomic version-checked update operation.
+ * Represents either a successful commit or a version conflict.
+ */
+export interface UpdateIfVersionResult<T> {
+    /** Whether the update succeeded */
+    updated: boolean;
+    /** The updated item with new __version (only if updated=true) */
+    item?: T & {
+        __version: number;
+    };
+    /** Current version if update failed due to version mismatch */
+    currentVersion?: number;
+}
 /**
  * A live collection that automatically updates when underlying data changes.
  * Represents application state, not a one-time query result.
@@ -76,12 +90,43 @@ export declare class Collection<T> {
     where(predicate: Predicate<T>): Collection<T>;
     /**
      * Insert a new record into this collection.
+     * Automatically initializes __version to 1 for durable atomic transitions.
      */
     insert(data: Partial<T>, id?: string | number): Promise<string>;
     /**
      * Update a record in this collection.
      */
     update(id: string | number, changes: Partial<T>): Promise<void>;
+    /**
+     * Atomically update a record only if its version matches the expected version.
+     *
+     * Provides Compare-And-Set semantics for durable state transitions.
+     * The version check and update happen atomically at the backend boundary,
+     * ensuring exactly one writer succeeds when multiple writers race.
+     *
+     * @param id Record identifier
+     * @param expectedVersion The version you observed when you read this record
+     * @param updates Fields to update (does not include __version; version is auto-incremented)
+     * @returns UpdateIfVersionResult with either the updated item or conflict info
+     *
+     * @example
+     * // Read the current state
+     * const handoff = await handoffs.get(handoffId);
+     *
+     * // Try to accept it atomically
+     * const result = await handoffs.updateIfVersion(
+     *   handoffId,
+     *   handoff.__version,
+     *   { status: "accepted", acceptedAt: new Date().toISOString() }
+     * );
+     *
+     * if (result.updated) {
+     *   console.log('Accepted at version', result.item.__version);
+     * } else {
+     *   console.log('Conflict - another writer won at version', result.currentVersion);
+     * }
+     */
+    updateIfVersion(id: string | number, expectedVersion: number, updates: Partial<T>): Promise<UpdateIfVersionResult<T>>;
     /**
      * Delete a record from this collection.
      */

package/dist/collection.d.ts.map

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

package/dist/collection.js

@@ -153,12 +153,13 @@ export class Collection {
     }
     /**
      * Insert a new record into this collection.
+     * Automatically initializes __version to 1 for durable atomic transitions.
      */
     async insert(data, id) {
         const recordId = id ?? `${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
         const key = `${this.name}:${recordId}`;
         const stored = typeof data === 'object' && data !== null
-            ? { ...data, id: recordId }
+            ? { ...data, id: recordId, __version: 1 }
             : data;
         const result = await this.db.insert(key, JSON.stringify(stored));
         if (!result.success) {
@@ -205,6 +206,87 @@ export class Collection {
         const graph = getReactiveDependencyGraph();
         await graph.emitChange(this.name, change);
     }
+    /**
+     * Atomically update a record only if its version matches the expected version.
+     *
+     * Provides Compare-And-Set semantics for durable state transitions.
+     * The version check and update happen atomically at the backend boundary,
+     * ensuring exactly one writer succeeds when multiple writers race.
+     *
+     * @param id Record identifier
+     * @param expectedVersion The version you observed when you read this record
+     * @param updates Fields to update (does not include __version; version is auto-incremented)
+     * @returns UpdateIfVersionResult with either the updated item or conflict info
+     *
+     * @example
+     * // Read the current state
+     * const handoff = await handoffs.get(handoffId);
+     *
+     * // Try to accept it atomically
+     * const result = await handoffs.updateIfVersion(
+     *   handoffId,
+     *   handoff.__version,
+     *   { status: "accepted", acceptedAt: new Date().toISOString() }
+     * );
+     *
+     * if (result.updated) {
+     *   console.log('Accepted at version', result.item.__version);
+     * } else {
+     *   console.log('Conflict - another writer won at version', result.currentVersion);
+     * }
+     */
+    async updateIfVersion(id, expectedVersion, updates) {
+        const current = await this.get(id);
+        if (!current) {
+            throw new Error(`Record ${id} not found`);
+        }
+        const currentVersion = current.__version ?? 1;
+        if (currentVersion !== expectedVersion) {
+            return {
+                updated: false,
+                currentVersion,
+            };
+        }
+        // Prepare updated record with incremented version
+        // User updates should not include __version
+        const cleanUpdates = { ...updates };
+        delete cleanUpdates.__version;
+        const newVersion = currentVersion + 1;
+        const updated = { ...current, ...cleanUpdates, __version: newVersion };
+        const key = `${this.name}:${id}`;
+        // Use CAS for atomic version-checked update
+        if (!this.db.cas) {
+            throw new Error(`updateIfVersion is not supported by this FeltDB runtime. ` +
+                `Only FileJsDb (Node.js) and HTTP/Server backends support atomic version-checked updates.`);
+        }
+        const casResult = await this.db.cas({
+            key,
+            expectedVersion: currentVersion,
+            value: JSON.stringify(updated),
+        });
+        if (!casResult.updated) {
+            // Another writer won the race
+            return {
+                updated: false,
+                currentVersion: casResult.currentVersion,
+            };
+        }
+        // Update indexes
+        this.indexBackend.updateRecord(String(id), current, updated);
+        // Emit change through reactive dependency graph
+        const change = {
+            type: 'update',
+            key,
+            value: updated,
+            timestamp: Date.now(),
+        };
+        const graph = getReactiveDependencyGraph();
+        await graph.emitChange(this.name, change);
+        return {
+            updated: true,
+            item: updated,
+        };
+    }
     /**
      * Delete a record from this collection.
      */

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.4.20';
+export const FELTDB_PACKAGE_VERSION = '0.5.1';
 export const feltdbPackageRange = `^${FELTDB_PACKAGE_VERSION}`;

package/dist/create/server-source/Cargo.lock

@@ -524,6 +524,7 @@ dependencies = [
  "tower-http",
  "tracing",
  "tracing-subscriber",
+ "uuid",
 ]
 
 [[package]]
@@ -1904,6 +1905,17 @@ version = "1.0.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b6c140620e7ffbb22c2dee59cafe6084a59b5ffc27a8859a5f0d494b5d52b6be"
 
+[[package]]
+name = "uuid"
+version = "1.25.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f053576934f05a761a402421fbbe3d425d9366f75f978806a037b3ca481abecc"
+dependencies = [
+ "getrandom 0.4.3",
+ "js-sys",
+ "wasm-bindgen",
+]
+
 [[package]]
 name = "valuable"
 version = "0.1.1"

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

@@ -959,6 +959,18 @@ pub struct RevisionAuditEvent {
     pub diff_hash: Option<String>,
 }
 #[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct RevisionRecovery {
+    pub recovery_id: String,
+    pub application_id: String,
+    pub environment: String,
+    pub source_revision: String,
+    pub target_revision: String,
+    pub approved_by: String,
+    pub reason: String,
+    pub authorization_level: String,
+    pub recovered_at: u64,
+}
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
 #[serde(rename_all = "SCREAMING_SNAKE_CASE")]
 pub enum ChangeSafety {
     Safe,
@@ -1099,6 +1111,10 @@ struct RevisionRecords {
     previews: Vec<ApplicationPreview>,
     environment_pointers: BTreeMap<String, BTreeMap<String, String>>,
     audit: Vec<RevisionAuditEvent>,
+    #[serde(default)]
+    untrusted_revisions: BTreeMap<String, BTreeMap<String, String>>,
+    #[serde(default)]
+    recoveries: Vec<RevisionRecovery>,
 }
 #[derive(Clone)]
 pub struct ApplicationStore {
@@ -1462,6 +1478,15 @@ impl ApplicationStore {
             })
             .ok_or("revision not found")?
             .clone();
+        if r.untrusted_revisions
+            .get(app)
+            .is_some_and(|values| values.contains_key(&revision.revision_id))
+        {
+            return Err("revision is permanently untrusted".into());
+        }
+        if manifest_hash(&revision.manifest)? != revision.manifest_hash {
+            return Err("revision integrity check failed".into());
+        }
         if !revision
             .manifest
             .environments
@@ -1536,6 +1561,108 @@ impl ApplicationStore {
         Ok(promotion)
     }
 
+    #[allow(clippy::too_many_arguments)]
+    pub fn recover_environment_pointer(
+        &self,
+        tenant: &str,
+        app: &str,
+        environment: &str,
+        expected_current_revision: &str,
+        target_revision: &str,
+        actor: &str,
+        reason: &str,
+        authorization_level: &str,
+        recovery_id: &str,
+    ) -> Result<RevisionRecovery, String> {
+        let mut records = self
+            .records
+            .write()
+            .map_err(|_| "application store lock poisoned")?;
+        if let Some(existing) = records
+            .recoveries
+            .iter()
+            .find(|value| value.recovery_id == recovery_id)
+        {
+            if existing.application_id == app
+                && existing.environment == environment
+                && existing.source_revision == expected_current_revision
+                && existing.target_revision == target_revision
+            {
+                return Ok(existing.clone());
+            }
+            return Err("recovery_id_conflict".into());
+        }
+        let current = records
+            .environment_pointers
+            .get(app)
+            .and_then(|values| values.get(environment))
+            .cloned()
+            .unwrap_or_default();
+        if current != expected_current_revision {
+            return Err(format!("expected_revision_mismatch:{current}"));
+        }
+        let target = records
+            .revisions
+            .iter()
+            .find(|value| {
+                value.tenant_id == tenant
+                    && value.application_id == app
+                    && (value.revision_id == target_revision
+                        || value.revision_number.to_string() == target_revision)
+            })
+            .ok_or("target revision not found")?
+            .clone();
+        if manifest_hash(&target.manifest)? != target.manifest_hash {
+            return Err("target revision integrity check failed".into());
+        }
+        if records
+            .untrusted_revisions
+            .get(app)
+            .is_some_and(|values| values.contains_key(&target.revision_id))
+        {
+            return Err("target revision is permanently untrusted".into());
+        }
+        let recovery = RevisionRecovery {
+            recovery_id: recovery_id.into(),
+            application_id: app.into(),
+            environment: environment.into(),
+            source_revision: expected_current_revision.into(),
+            target_revision: target.revision_id.clone(),
+            approved_by: actor.into(),
+            reason: reason.into(),
+            authorization_level: authorization_level.into(),
+            recovered_at: now(),
+        };
+        records
+            .untrusted_revisions
+            .entry(app.into())
+            .or_default()
+            .insert(expected_current_revision.into(), recovery_id.into());
+        records
+            .environment_pointers
+            .entry(app.into())
+            .or_default()
+            .insert(environment.into(), target.revision_id.clone());
+        records.recoveries.push(recovery.clone());
+        Self::event(
+            &mut records,
+            "application.revision.recovered",
+            tenant,
+            app,
+            actor,
+            Some(&target),
+            Some(expected_current_revision.into()),
+        );
+        if let Some(event) = records.audit.last_mut() {
+            event.environment = Some(environment.into());
+            event.from_revision = Some(expected_current_revision.into());
+            event.to_revision = Some(target.revision_id);
+            event.correlation_id = recovery_id.into();
+        }
+        self.persist(&records)?;
+        Ok(recovery)
+    }
+
     pub fn history(&self, tenant: &str, app: &str, environment: &str) -> Vec<RevisionPromotion> {
         self.records
             .read()
@@ -2148,6 +2275,41 @@ mod tests {
         assert_eq!(s.pointers("a")["production"], r2.revision_id);
         assert_eq!(s.history("t", "a", "production").len(), 2);
     }
+
+    #[test]
+    fn recovery_is_atomic_idempotent_durable_and_permanently_untrusts_source() {
+        let s = store("revision-recovery");
+        let d = s.create_draft("t", "a", "App", "owner", None).unwrap();
+        let corrupt = s.commit("t", "a", &d.draft_id, "owner").unwrap();
+        s.move_environment_pointer("t", "a", &corrupt.revision_id, "staging", None,
+            "owner", "initial", true, false).unwrap();
+        let d = s.create_draft("t", "a", "App", "owner", Some(&corrupt.revision_id)).unwrap();
+        let clean = s.commit("t", "a", &d.draft_id, "owner").unwrap();
+
+        // Historical source corruption must not prevent recovery away from it.
+        {
+            let mut records = s.records.write().unwrap();
+            records.revisions.iter_mut().find(|value| value.revision_id == corrupt.revision_id)
+                .unwrap().manifest.metadata.name = "corrupted without updating its integrity hash".into();
+            s.persist(&records).unwrap();
+        }
+        let recovered = s.recover_environment_pointer("t", "a", "staging", &corrupt.revision_id,
+            &clean.revision_id, "sherpa", "Replace corrupt historical revision", "ELEVATED",
+            "recovery-1").unwrap();
+        assert_eq!(recovered.target_revision, clean.revision_id);
+        assert_eq!(s.recover_environment_pointer("t", "a", "staging", &corrupt.revision_id,
+            &clean.revision_id, "sherpa", "Replace corrupt historical revision", "ELEVATED",
+            "recovery-1").unwrap(), recovered);
+        assert!(s.move_environment_pointer("t", "a", &corrupt.revision_id, "staging",
+            Some(&clean.revision_id), "owner", "rollback", true, true).unwrap_err()
+            .contains("untrusted"));
+
+        let reloaded = ApplicationStore::load(s.path.clone()).unwrap();
+        assert_eq!(reloaded.pointers("a")["staging"], clean.revision_id);
+        let records = reloaded.records.read().unwrap();
+        assert_eq!(records.recoveries.len(), 1);
+        assert!(records.untrusted_revisions["a"].contains_key(&corrupt.revision_id));
+    }
     #[test]
     fn preview_remains_bound_when_production_moves() {
         let s = store("preview-bound");
@@ -2280,7 +2442,11 @@ mod tests {
         });
 
         let report = validate_manifest(&manifest, "tenant", "app", None);
-        assert!(report.valid, "Policy with authenticated subject should be valid: {:?}", report.issues);
+        assert!(
+            report.valid,
+            "Policy with authenticated subject should be valid: {:?}",
+            report.issues
+        );
     }
 
     #[test]
@@ -2295,7 +2461,11 @@ mod tests {
         });
 
         let report = validate_manifest(&manifest, "tenant", "app", None);
-        assert!(report.valid, "Policy with owner subject should be valid: {:?}", report.issues);
+        assert!(
+            report.valid,
+            "Policy with owner subject should be valid: {:?}",
+            report.issues
+        );
     }
 
     #[test]
@@ -2310,12 +2480,14 @@ mod tests {
         });
 
         let report = validate_manifest(&manifest, "tenant", "app", None);
-        assert!(!report.valid, "Policy with unknown subject should be invalid");
         assert!(
-            report.issues.iter().any(|i|
-                i.path.contains("BadPolicy") && i.path.contains("read") &&
-                i.message.contains("invalid policy subject")
-            ),
+            !report.valid,
+            "Policy with unknown subject should be invalid"
+        );
+        assert!(
+            report.issues.iter().any(|i| i.path.contains("BadPolicy")
+                && i.path.contains("read")
+                && i.message.contains("invalid policy subject")),
             "Should have error about invalid policy subject"
         );
     }
@@ -2332,6 +2504,9 @@ mod tests {
         });
 
         let report = validate_manifest(&manifest, "tenant", "app", None);
-        assert!(report.valid, "Policy without subjects should be valid (backward compatible)");
+        assert!(
+            report.valid,
+            "Policy without subjects should be valid (backward compatible)"
+        );
     }
 }

package/dist/create/server-source/crates/feltdb-server/Cargo.toml

@@ -21,3 +21,4 @@ tokio = { version = "1", features = ["macros", "net", "rt-multi-thread", "signal
 tower-http = { version = "0.6", features = ["cors", "limit", "trace"] }
 tracing = "0.1"
 tracing-subscriber = { version = "0.3", features = ["env-filter"] }
+uuid = { version = "1.6", features = ["v4"] }

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

@@ -20,6 +20,8 @@ pub mod portable_bundle;
 pub mod principals;
 pub mod providers;
 pub mod releases;
+pub mod request_telemetry;
 pub mod sessions;
 pub mod tenancy;
+pub mod transaction_idempotency;
 pub mod versions;