@feltdb/core 0.4.20 → 0.5.0

package/README.md

@@ -75,6 +75,175 @@ 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 { RevisionRecoveryInput } from '@feltdb/core';
+
+const recovery = await db.recoverApplicationRevision({
+  from_revision: 'rev-corrupted-123',
+  to_revision: 'rev-clean-122',
+  expected_current_revision: 'rev-corrupted-123',
+  authorization: { 
+    level: 'ELEVATED',
+    reason: 'Database corruption detected during backup validation',
+    approval_id: 'approval-789'
+  }
+});
+
+// Result includes immutable audit trail
+console.log(recovery.audit_record);
+// The corrupt revision is permanently marked untrusted
+```
+
+### 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.0';
 function prompt(question) {
     const rl = readline.createInterface({
         input: process.stdin,

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.0';
 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-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;

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

@@ -0,0 +1,381 @@
+use std::sync::{Arc, Mutex};
+use std::time::{Instant, SystemTime};
+use serde::{Deserialize, Serialize};
+use uuid::Uuid;
+
+/// Request lifecycle telemetry: captures all timing and context for every /v1/ request.
+/// This is the production correctness contract for managed FeltDB concurrency.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct RequestTelemetry {
+    pub request_id: String,
+    pub transaction_id: Option<String>,
+    pub application_id: String,
+    pub revision_id: String,
+
+    // Timing breakdown (milliseconds)
+    pub queue_wait_ms: u64,
+    pub lock_wait_ms: u64,
+    pub execution_ms: u64,
+    pub persistence_ms: u64,
+    pub total_ms: u64,
+
+    // Contention signals
+    pub lock_name: String,
+    pub queue_depth: usize,
+    pub max_queue_depth: usize,
+
+    // Cancellation state
+    pub deadline_ms: Option<u64>,
+    pub cancelled: bool,
+
+    // HTTP response
+    pub http_status: u16,
+    pub feltdb_code: String,
+    pub error_message: Option<String>,
+
+    // Resource tracking
+    pub orphaned_tasks: usize,
+    pub timestamp_ms: u64,
+}
+
+impl RequestTelemetry {
+    pub fn new(application_id: String, revision_id: String) -> Self {
+        let now = SystemTime::now()
+            .duration_since(SystemTime::UNIX_EPOCH)
+            .unwrap_or_default()
+            .as_millis() as u64;
+
+        Self {
+            request_id: Uuid::new_v4().to_string(),
+            transaction_id: None,
+            application_id,
+            revision_id,
+            queue_wait_ms: 0,
+            lock_wait_ms: 0,
+            execution_ms: 0,
+            persistence_ms: 0,
+            total_ms: 0,
+            lock_name: String::new(),
+            queue_depth: 0,
+            max_queue_depth: 0,
+            deadline_ms: None,
+            cancelled: false,
+            http_status: 200,
+            feltdb_code: "OK".to_string(),
+            error_message: None,
+            orphaned_tasks: 0,
+            timestamp_ms: now,
+        }
+    }
+
+    pub fn with_transaction_id(mut self, tx_id: String) -> Self {
+        self.transaction_id = Some(tx_id);
+        self
+    }
+}
+
+/// Request telemetry store: thread-safe collection of all request measurements.
+/// Enables production diagnostics without external observability dependency.
+pub struct RequestTelemetryStore {
+    records: Arc<Mutex<Vec<RequestTelemetry>>>,
+    max_capacity: usize,
+}
+
+impl RequestTelemetryStore {
+    pub fn new(max_capacity: usize) -> Self {
+        Self {
+            records: Arc::new(Mutex::new(Vec::with_capacity(max_capacity))),
+            max_capacity,
+        }
+    }
+
+    pub fn record(&self, telemetry: RequestTelemetry) {
+        if let Ok(mut records) = self.records.lock() {
+            records.push(telemetry);
+            // Keep only the most recent records
+            if records.len() > self.max_capacity {
+                let to_remove = records.len() - self.max_capacity;
+                records.drain(0..to_remove);
+            }
+        }
+    }
+
+    pub fn all(&self) -> Vec<RequestTelemetry> {
+        self.records
+            .lock()
+            .map(|r| r.clone())
+            .unwrap_or_default()
+    }
+
+    pub fn recent(&self, count: usize) -> Vec<RequestTelemetry> {
+        self.records
+            .lock()
+            .map(|r| {
+                let start = if r.len() > count { r.len() - count } else { 0 };
+                r[start..].to_vec()
+            })
+            .unwrap_or_default()
+    }
+
+    pub fn by_transaction_id(&self, tx_id: &str) -> Vec<RequestTelemetry> {
+        self.records
+            .lock()
+            .map(|r| r.iter().filter(|t| t.transaction_id.as_deref() == Some(tx_id)).cloned().collect())
+            .unwrap_or_default()
+    }
+
+    pub fn statistics(&self) -> TelemetryStatistics {
+        if let Ok(records) = self.records.lock() {
+            let mut stats = TelemetryStatistics::default();
+            let mut total_latencies = Vec::new();
+            let mut queue_waits = Vec::new();
+            let mut lock_waits = Vec::new();
+            let mut execution_times = Vec::new();
+            let mut persistence_times = Vec::new();
+
+            for telemetry in records.iter() {
+                total_latencies.push(telemetry.total_ms);
+                queue_waits.push(telemetry.queue_wait_ms);
+                lock_waits.push(telemetry.lock_wait_ms);
+                execution_times.push(telemetry.execution_ms);
+                persistence_times.push(telemetry.persistence_ms);
+                stats.total_requests += 1;
+                stats.max_queue_depth = stats.max_queue_depth.max(telemetry.max_queue_depth);
+                stats.total_orphaned_tasks += telemetry.orphaned_tasks;
+
+                match telemetry.http_status {
+                    200..=299 => stats.successful_requests += 1,
+                    400..=499 => stats.client_errors += 1,
+                    500..=599 => stats.server_errors += 1,
+                    _ => {}
+                }
+
+                if telemetry.cancelled {
+                    stats.cancelled_requests += 1;
+                }
+
+                if telemetry.feltdb_code == "CONFLICT" {
+                    stats.conflicts += 1;
+                } else if telemetry.feltdb_code == "TOO_BUSY" {
+                    stats.too_busy_count += 1;
+                }
+            }
+
+            // Calculate percentiles
+            if !total_latencies.is_empty() {
+                total_latencies.sort();
+                stats.latency_p50_ms = calculate_percentile(&total_latencies, 50);
+                stats.latency_p95_ms = calculate_percentile(&total_latencies, 95);
+                stats.latency_p99_ms = calculate_percentile(&total_latencies, 99);
+                stats.latency_max_ms = *total_latencies.last().unwrap_or(&0);
+            }
+
+            if !queue_waits.is_empty() {
+                queue_waits.sort();
+                stats.queue_wait_p99_ms = calculate_percentile(&queue_waits, 99);
+                stats.queue_wait_max_ms = *queue_waits.last().unwrap_or(&0);
+            }
+
+            if !lock_waits.is_empty() {
+                lock_waits.sort();
+                stats.lock_wait_p99_ms = calculate_percentile(&lock_waits, 99);
+                stats.lock_wait_max_ms = *lock_waits.last().unwrap_or(&0);
+            }
+
+            if !execution_times.is_empty() {
+                stats.execution_p99_ms = calculate_percentile(&execution_times, 99);
+            }
+
+            if !persistence_times.is_empty() {
+                stats.persistence_p99_ms = calculate_percentile(&persistence_times, 99);
+            }
+
+            stats
+        } else {
+            TelemetryStatistics::default()
+        }
+    }
+
+    pub fn clear(&self) {
+        if let Ok(mut records) = self.records.lock() {
+            records.clear();
+        }
+    }
+}
+
+#[derive(Debug, Clone, Serialize, Default)]
+pub struct TelemetryStatistics {
+    pub total_requests: usize,
+    pub successful_requests: usize,
+    pub client_errors: usize,
+    pub server_errors: usize,
+    pub cancelled_requests: usize,
+    pub conflicts: usize,
+    pub too_busy_count: usize,
+
+    pub latency_p50_ms: u64,
+    pub latency_p95_ms: u64,
+    pub latency_p99_ms: u64,
+    pub latency_max_ms: u64,
+
+    pub queue_wait_p99_ms: u64,
+    pub queue_wait_max_ms: u64,
+
+    pub lock_wait_p99_ms: u64,
+    pub lock_wait_max_ms: u64,
+
+    pub execution_p99_ms: u64,
+    pub persistence_p99_ms: u64,
+
+    pub max_queue_depth: usize,
+    pub total_orphaned_tasks: usize,
+}
+
+fn calculate_percentile(sorted: &[u64], percentile: u32) -> u64 {
+    if sorted.is_empty() {
+        return 0;
+    }
+    let index = ((sorted.len() as u32 * percentile / 100).max(1) - 1) as usize;
+    sorted[index.min(sorted.len() - 1)]
+}
+
+/// Request lifecycle timer: tracks all phases of request execution.
+pub struct RequestTimer {
+    start: Instant,
+    queue_start: Option<Instant>,
+    lock_start: Option<Instant>,
+    execution_start: Option<Instant>,
+    persistence_start: Option<Instant>,
+}
+
+impl RequestTimer {
+    pub fn new() -> Self {
+        Self {
+            start: Instant::now(),
+            queue_start: None,
+            lock_start: None,
+            execution_start: None,
+            persistence_start: None,
+        }
+    }
+
+    pub fn begin_queue_wait(&mut self) {
+        self.queue_start = Some(Instant::now());
+    }
+
+    pub fn end_queue_wait(&mut self) -> u64 {
+        self.queue_start
+            .take()
+            .map(|s| s.elapsed().as_millis() as u64)
+            .unwrap_or(0)
+    }
+
+    pub fn begin_lock_wait(&mut self) {
+        self.lock_start = Some(Instant::now());
+    }
+
+    pub fn end_lock_wait(&mut self) -> u64 {
+        self.lock_start
+            .take()
+            .map(|s| s.elapsed().as_millis() as u64)
+            .unwrap_or(0)
+    }
+
+    pub fn begin_execution(&mut self) {
+        self.execution_start = Some(Instant::now());
+    }
+
+    pub fn end_execution(&mut self) -> u64 {
+        self.execution_start
+            .take()
+            .map(|s| s.elapsed().as_millis() as u64)
+            .unwrap_or(0)
+    }
+
+    pub fn begin_persistence(&mut self) {
+        self.persistence_start = Some(Instant::now());
+    }
+
+    pub fn end_persistence(&mut self) -> u64 {
+        self.persistence_start
+            .take()
+            .map(|s| s.elapsed().as_millis() as u64)
+            .unwrap_or(0)
+    }
+
+    pub fn total_elapsed(&self) -> u64 {
+        self.start.elapsed().as_millis() as u64
+    }
+}
+
+impl Default for RequestTimer {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_telemetry_creation() {
+        let telemetry = RequestTelemetry::new("app-1".to_string(), "rev-1".to_string());
+        assert!(!telemetry.request_id.is_empty());
+        assert_eq!(telemetry.application_id, "app-1");
+        assert_eq!(telemetry.revision_id, "rev-1");
+    }
+
+    #[test]
+    fn test_telemetry_store() {
+        let store = RequestTelemetryStore::new(100);
+        let mut telemetry = RequestTelemetry::new("app".to_string(), "rev".to_string());
+        telemetry.total_ms = 50;
+        telemetry.http_status = 200;
+
+        store.record(telemetry.clone());
+        let all = store.all();
+        assert_eq!(all.len(), 1);
+        assert_eq!(all[0].total_ms, 50);
+    }
+
+    #[test]
+    fn test_timer_lifecycle() {
+        let mut timer = RequestTimer::new();
+
+        timer.begin_queue_wait();
+        std::thread::sleep(Duration::from_millis(10));
+        let queue_ms = timer.end_queue_wait();
+        assert!(queue_ms >= 10);
+
+        timer.begin_lock_wait();
+        std::thread::sleep(Duration::from_millis(5));
+        let lock_ms = timer.end_lock_wait();
+        assert!(lock_ms >= 5);
+
+        let total = timer.total_elapsed();
+        assert!(total >= 15);
+    }
+
+    #[test]
+    fn test_statistics_calculation() {
+        let store = RequestTelemetryStore::new(1000);
+
+        // Record 101 requests with increasing latency
+        for i in 0..101 {
+            let mut telemetry = RequestTelemetry::new("app".to_string(), "rev".to_string());
+            telemetry.total_ms = (i * 10) as u64; // 0, 10, 20, ..., 1000
+            telemetry.http_status = if i % 10 == 0 { 409 } else { 200 };
+            if i % 10 == 0 {
+                telemetry.feltdb_code = "CONFLICT".to_string();
+            }
+            store.record(telemetry);
+        }
+
+        let stats = store.statistics();
+        assert_eq!(stats.total_requests, 101);
+        assert!(stats.latency_p50_ms > 0);
+        assert!(stats.latency_p99_ms > stats.latency_p50_ms);
+        assert_eq!(stats.conflicts, 11);
+    }
+}