create-feltdb 0.4.20 → 0.5.1

package/dist/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/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/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/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/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/server-source/crates/feltdb-server/src/main.rs

@@ -40,8 +40,8 @@ use feltdb::{
         authorize as authorize_resource, AuthorizationRequest as ResourceAuthorizationRequest,
         Grant, GrantSigner, GrantStore, Subject as GrantSubject,
     },
-    policy_evaluation::{Actor, PolicyContext, PolicyEvaluator, PolicySubject},
     cardinality_endpoint::{CardinalityContext, CardinalityDiagnosticResponse},
+    policy_evaluation::{Actor, PolicyContext, PolicyEvaluator, PolicySubject},
     state_contract::{
         begin_read, compare_schemas, execute_query as execute_state_query, execute_transaction,
         schema_from_revision, validate_schema, AuthorizationContext, CanonicalQuery, QueryFilter,
@@ -76,7 +76,7 @@ use feltdb_server::{
     connections::{ConnectionProvider, ConnectionStatus, ConnectionStore, SecretReference},
     content::ContentStore,
     identity::IdentityStore,
-    key_management::{list_keys, create_key, revoke_key},
+    key_management::{create_key, list_keys, revoke_key},
     key_provider::provider_from_environment,
     leases::LeaseStore,
     metrics::Metrics,
@@ -103,7 +103,9 @@ struct ApiError(StatusCode, String);
 
 impl IntoResponse for ApiError {
     fn into_response(self) -> Response {
-        (self.0, Json(json!({ "error": self.1 }))).into_response()
+        let body =
+            serde_json::from_str::<Value>(&self.1).unwrap_or_else(|_| json!({ "error": self.1 }));
+        (self.0, Json(body)).into_response()
     }
 }
 
@@ -2027,9 +2029,10 @@ fn is_platform_owner(principal: &Principal) -> bool {
         .any(|owner| !owner.is_empty() && owner == identity)
 }
 fn require_platform_owner(principal: &Principal) -> Result<(), ApiError> {
-    is_platform_owner(principal)
-        .then_some(())
-        .ok_or(ApiError(StatusCode::FORBIDDEN, "platform owner access required".into()))
+    is_platform_owner(principal).then_some(()).ok_or(ApiError(
+        StatusCode::FORBIDDEN,
+        "platform owner access required".into(),
+    ))
 }
 async fn platform_access(Extension(principal): Extension<Principal>) -> Json<Value> {
     let platform_role = is_platform_owner(&principal).then_some("super_owner");
@@ -2365,7 +2368,11 @@ async fn evaluate_application_contract(
 ) -> Result<Json<Value>, ApiError> {
     Ok(Json(json!(state
         .contracts
-        .evaluate(&user_contract_key(&principal, &id), &input.outcome, &principal.key_id)
+        .evaluate(
+            &user_contract_key(&principal, &id),
+            &input.outcome,
+            &principal.key_id
+        )
         .map_err(control_error)?)))
 }
 async fn patch_application_contract(
@@ -2384,7 +2391,10 @@ async fn application_contract_gaps(
     Extension(principal): Extension<Principal>,
     Path(id): Path<String>,
 ) -> Result<Json<Value>, ApiError> {
-    let c = state.contracts.get(&user_contract_key(&principal, &id)).map_err(control_error)?;
+    let c = state
+        .contracts
+        .get(&user_contract_key(&principal, &id))
+        .map_err(control_error)?;
     Ok(Json(json!({"gaps":c.gaps})))
 }
 async fn application_contract_readiness(
@@ -4495,12 +4505,7 @@ async fn run_runtime_action(
         schema_version: contract.state.schema.schema_version,
         state_namespace: Some(contract.environment.state_namespace.clone()),
         causal_parent: None,
-        authorization: state_authorization(
-            &principal,
-            &contract,
-            &definition.collection,
-            "write",
-        ),
+        authorization: state_authorization(&principal, &contract, &definition.collection, "write"),
         operations: vec![TransactionOperation {
             kind,
             collection: definition.collection.clone(),
@@ -4603,12 +4608,7 @@ async fn run_runtime_query(
         &state.db,
         &contract.state.schema,
         &contract.environment.state_namespace,
-        state_authorization(
-            &principal,
-            &contract,
-            &definition.collection,
-            "read",
-        ),
+        state_authorization(&principal, &contract, &definition.collection, "read"),
     )
     .map_err(state_contract_error)?;
 
@@ -4712,7 +4712,7 @@ fn state_authorization(
     principal: &Principal,
     contract: &ApplicationRuntimeContract,
     collection: &str,
-    operation: &str,  // "read" or "write"
+    operation: &str, // "read" or "write"
 ) -> AuthorizationContext {
     let subject = format!("{}:{}", principal.subject_type, principal.key_id);
 
@@ -4888,12 +4888,7 @@ async fn execute_canonical_query(
         &state.db,
         &contract.state.schema,
         &contract.environment.state_namespace,
-        state_authorization(
-            &principal,
-            &contract,
-            &input.query.collection,
-            "read",
-        ),
+        state_authorization(&principal, &contract, &input.query.collection, "read"),
     )
     .map_err(state_contract_error)?;
 
@@ -4905,8 +4900,14 @@ async fn execute_canonical_query(
         .find(|p| p.resource == input.query.collection)
         .and_then(|p| p.read.as_ref().and_then(|s| PolicySubject::from_str(s)));
 
-    let result = execute_state_query(&state.db, &contract.state.schema, &context, &input.query, read_policy)
-        .map_err(state_contract_error)?;
+    let result = execute_state_query(
+        &state.db,
+        &contract.state.schema,
+        &context,
+        &input.query,
+        read_policy,
+    )
+    .map_err(state_contract_error)?;
     audit(
         &state,
         &principal.key_id,
@@ -4917,6 +4918,156 @@ async fn execute_canonical_query(
     );
     Ok(Json(json!(result)))
 }
+
+#[derive(serde::Deserialize)]
+struct RevisionRecoveryRequest {
+    #[serde(rename = "applicationId")]
+    application_id: String,
+    #[serde(rename = "targetRevision")]
+    target_revision: String,
+    #[serde(rename = "expectedCurrentRevision")]
+    expected_current_revision: String,
+    authorization: String,
+    actor: String,
+    reason: String,
+    #[serde(default)]
+    environment: Option<String>,
+    #[serde(default)]
+    #[serde(rename = "recoveryId")]
+    recovery_id: Option<String>,
+}
+
+#[derive(serde::Serialize, serde::Deserialize)]
+struct RevisionRecoveryResponse {
+    success: bool,
+    #[serde(rename = "pointerMoved")]
+    pointer_moved: bool,
+    #[serde(rename = "sourceMarkedUntrusted")]
+    source_marked_untrusted: bool,
+    #[serde(rename = "auditDurable")]
+    audit_durable: bool,
+    #[serde(rename = "recoveryId")]
+    recovery_id: String,
+    #[serde(rename = "targetRevision")]
+    target_revision: String,
+    #[serde(rename = "currentRevision")]
+    current_revision: String,
+    audit: serde_json::Value,
+}
+
+fn revision_recovery_error(
+    status: StatusCode,
+    code: &str,
+    message: String,
+    request_id: &str,
+    transaction_id: &str,
+) -> ApiError {
+    ApiError(
+        status,
+        json!({"code":code,"message":message,"request_id":request_id,
+        "transaction_id":transaction_id,"http_status":status.as_u16()})
+        .to_string(),
+    )
+}
+
+async fn execute_revision_recovery(
+    State(state): State<AppState>,
+    Extension(principal): Extension<Principal>,
+    Json(input): Json<RevisionRecoveryRequest>,
+) -> Result<Json<RevisionRecoveryResponse>, ApiError> {
+    let request_id = uuid::Uuid::new_v4().to_string();
+    let transaction_id = input
+        .recovery_id
+        .clone()
+        .unwrap_or_else(|| uuid::Uuid::new_v4().to_string());
+
+    // Validate authorization level
+    let auth_level = input.authorization.as_str();
+
+    if !["ELEVATED", "ADMIN", "EMERGENCY"].contains(&auth_level) {
+        return Err(revision_recovery_error(
+            StatusCode::FORBIDDEN,
+            "PERMISSION_DENIED",
+            "Recovery requires ELEVATED, ADMIN, or EMERGENCY authorization".into(),
+            &request_id,
+            &transaction_id,
+        ));
+    }
+
+    // Validate input
+    if input.reason.len() < 10 {
+        return Err(revision_recovery_error(
+            StatusCode::UNPROCESSABLE_ENTITY,
+            "PRECONDITION_FAILED",
+            "Recovery reason must be at least 10 characters".into(),
+            &request_id,
+            &transaction_id,
+        ));
+    }
+
+    let recovery_id = transaction_id.clone();
+    let environment = input
+        .environment
+        .unwrap_or_else(|| "production".to_string());
+    let tenant = application_scope(
+        &state,
+        &principal.key_id,
+        &input.application_id,
+        "application:revision:promote",
+    )?;
+    let recovery = state
+        .applications
+        .recover_environment_pointer(
+            &tenant,
+            &input.application_id,
+            &environment,
+            &input.expected_current_revision,
+            &input.target_revision,
+            &input.actor,
+            &input.reason,
+            auth_level,
+            &recovery_id,
+        )
+        .map_err(|message| {
+            let (status, code) = if message.starts_with("expected_revision_mismatch")
+                || message == "recovery_id_conflict"
+            {
+                (StatusCode::CONFLICT, "CONFLICT")
+            } else if message.contains("not found") {
+                (StatusCode::NOT_FOUND, "PRECONDITION_FAILED")
+            } else if message.contains("integrity") || message.contains("untrusted") {
+                (StatusCode::UNPROCESSABLE_ENTITY, "VALIDATION_FAILED")
+            } else {
+                (StatusCode::SERVICE_UNAVAILABLE, "STORAGE_FAILURE")
+            };
+            revision_recovery_error(status, code, message, &request_id, &transaction_id)
+        })?;
+
+    // Build response
+    let response = RevisionRecoveryResponse {
+        success: true,
+        pointer_moved: true,
+        source_marked_untrusted: true,
+        audit_durable: true,
+        recovery_id: recovery_id.clone(),
+        target_revision: recovery.target_revision.clone(),
+        current_revision: recovery.target_revision.clone(),
+        audit: json!(recovery),
+    };
+
+    // Audit log
+    audit(
+        &state,
+        &principal.key_id,
+        "revision.recover",
+        &recovery_id,
+        "allowed",
+        200,
+    );
+
+    Ok(Json(response))
+}
+
 async fn execute_canonical_transaction(
     State(state): State<AppState>,
     Extension(principal): Extension<Principal>,
@@ -4942,24 +5093,27 @@ async fn execute_canonical_transaction(
     input.transaction.state_namespace = Some(contract.environment.state_namespace.clone());
     // For transactions with operations, use the first operation's collection for policy evaluation
     // Multi-collection transactions will still be checked at the operation level in execute_transaction
-    let collection = input.transaction.operations
+    let collection = input
+        .transaction
+        .operations
         .first()
         .map(|op| op.collection.clone())
         .unwrap_or_default();
-    input.transaction.authorization = state_authorization(
-        &principal,
-        &contract,
-        &collection,
-        "write",
-    );
+    input.transaction.authorization =
+        state_authorization(&principal, &contract, &collection, "write");
     let write_policy = contract
         .policies
         .definitions
         .iter()
         .find(|p| p.resource == collection)
         .and_then(|p| p.write.as_ref().and_then(|s| PolicySubject::from_str(s)));
-    let result = execute_transaction(&state.db, &contract.state.schema, &input.transaction, write_policy)
-        .map_err(state_contract_error)?;
+    let result = execute_transaction(
+        &state.db,
+        &contract.state.schema,
+        &input.transaction,
+        write_policy,
+    )
+    .map_err(state_contract_error)?;
     audit(
         &state,
         &principal.key_id,
@@ -4975,13 +5129,19 @@ async fn get_cardinality_diagnostic(
     State(state): State<AppState>,
     Path(pattern): Path<String>,
 ) -> Result<Json<CardinalityDiagnosticResponse>, ApiError> {
-    let all_cardinalities = state.db.list_cardinalities()
+    let all_cardinalities = state
+        .db
+        .list_cardinalities()
         .map_err(|e| ApiError(StatusCode::INTERNAL_SERVER_ERROR, e.to_string()))?;
 
-    let actual_rows = state.db.diagnostic_row_count(&pattern)
+    let actual_rows = state
+        .db
+        .diagnostic_row_count(&pattern)
         .map_err(|e| ApiError(StatusCode::INTERNAL_SERVER_ERROR, e.to_string()))?;
 
-    let persisted_capability_keys = state.db.diagnostic_capability_keys(&pattern)
+    let persisted_capability_keys = state
+        .db
+        .diagnostic_capability_keys(&pattern)
         .map_err(|e| ApiError(StatusCode::INTERNAL_SERVER_ERROR, e.to_string()))?;
 
     let matching_keys: Vec<_> = all_cardinalities
@@ -4992,10 +5152,7 @@ async fn get_cardinality_diagnostic(
 
     let cardinality_map_keys: Vec<String> = matching_keys.iter().map(|(k, _)| k.clone()).collect();
 
-    let maintained = matching_keys
-        .iter()
-        .map(|(_, v)| v)
-        .sum::<u64>();
+    let maintained = matching_keys.iter().map(|(_, v)| v).sum::<u64>();
 
     let now_ms = std::time::SystemTime::now()
         .duration_since(std::time::UNIX_EPOCH)
@@ -5752,6 +5909,10 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
             "/v1/transactions",
             axum::routing::post(execute_canonical_transaction),
         )
+        .route(
+            "/v1/revision/recover",
+            axum::routing::post(execute_revision_recovery),
+        )
         .route(
             "/debug/cardinality/{pattern}",
             get(get_cardinality_diagnostic),

package/dist/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);
+    }
+}

package/dist/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/package.json

@@ -2,7 +2,7 @@
   "name": "create-feltdb",
   "private": false,
   "description": "Create a new FeltDB application with one command",
-  "version": "0.4.20",
+  "version": "0.5.1",
   "license": "MIT",
   "bin": {
     "create-feltdb": "bin/create-feltdb.js"