@feltdb/core 0.5.0 → 0.5.1

package/README.md

@@ -142,22 +142,32 @@ Terminal states (`completed`, `failed`, `cancelled`) cannot be transitioned from
 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'
-  }
+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 immutable audit trail
-console.log(recovery.audit_record);
-// The corrupt revision is permanently marked untrusted
+// 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

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.5.0';
+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":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AAIxC,OAAO,KAAK,EAAE,WAAW,EAAc,MAAM,kBAAkB,CAAC;AAEhE,MAAM,MAAM,SAAS,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC;AAChD,MAAM,MAAM,UAAU,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,EAAE,KAAK,IAAI,CAAC;AAEjD;;;;;GAKG;AACH,qBAAa,UAAU,CAAC,CAAC;IACvB,OAAO,CAAC,EAAE,CAAO;IACjB,OAAO,CAAC,IAAI,CAAS;IACrB,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,SAAS,CAA6B;IAC9C,OAAO,CAAC,KAAK,CAAW;IACxB,OAAO,CAAC,WAAW,CAAiC;IACpD,OAAO,CAAC,MAAM,CAA8B;IAC5C,OAAO,CAAC,QAAQ,CAAuB;IACvC,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,oBAAoB,CAA8B;IAC1D,OAAO,CAAC,gBAAgB,CAA6B;IACrD,OAAO,CAAC,kBAAkB,CAA6B;IACvD,OAAO,CAAC,YAAY,CAAoC;IACxD,OAAO,CAAC,UAAU,CAAa;IAC/B,OAAO,CAAC,aAAa,CAAS;gBAElB,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,EAAE,UAAU,CAAC,CAAC,CAAC;IAmBpF;;OAEG;YACW,oBAAoB;IAalC;;;OAGG;IACG,GAAG,IAAI,OAAO,CAAC,CAAC,EAAE,CAAC;IAKzB,0DAA0D;IACpD,IAAI,CAAC,KAAK,GAAE,OAAO,CAAC,CAAC,CAAM,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC;IAQhD;;;;;OAKG;IACH,WAAW,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI;IAWtC;;OAEG;IACH,WAAW,IAAI,WAAW,EAAE;IAI5B;;;OAGG;IACG,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC;IAYrC;;OAEG;IACG,eAAe,IAAI,OAAO,CAAC,OAAO,CAAC;IAazC;;OAEG;IACG,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;IAajD;;;OAGG;IACH,KAAK,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC;IAO7C;;OAEG;IACG,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IA4BrE;;OAEG;IACG,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IA8BrE;;OAEG;IACG,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA2BhD;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC;IAK9B;;OAEG;IACG,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAKnD;;;;;;OAMG;IACG,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC;QAAE,QAAQ,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,CAAC,CAAA;KAAE,CAAC;IAmClG;;;OAGG;IACH,SAAS,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,MAAM,IAAI;IA6CxE,mEAAmE;IACnE,KAAK,IAAI,IAAI;IASb;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAgC/B;AAED;;GAEG;AACH,qBAAa,YAAY,CAAC,MAAM,EAAE,KAAK;IACrC,OAAO,CAAC,QAAQ,CAAO;IACvB,OAAO,CAAC,OAAO,CAAO;IACtB,OAAO,CAAC,eAAe,CAAS;IAChC,OAAO,CAAC,UAAU,CAAoC;gBAGpD,QAAQ,EAAE,IAAI,EACd,OAAO,EAAE,IAAI,EACb,eAAe,EAAE,MAAM,EACvB,UAAU,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,MAAM,GAAG,MAAM;IAQ/C;;OAEG;IACG,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,KAAK,EAAE,CAAC;CAoBxD"}
+{"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.5.0';
+export const FELTDB_PACKAGE_VERSION = '0.5.1';
 export const feltdbPackageRange = `^${FELTDB_PACKAGE_VERSION}`;

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)"
+        );
     }
 }