@feltdb/core 0.8.4 → 0.8.6

package/dist/create/server-source/crates/feltdb/tests/revision_retention_boundary_evidence.rs

@@ -0,0 +1,427 @@
+//! Evidence for the revision retention and identity boundary audit
+//! (`docs/audits/REVISION-RETENTION-BOUNDARY-AUDIT.md`).
+//!
+//! Adds **no capability and no product surface**. It tests one question:
+//!
+//! > The [three-way input boundary audit](../../../docs/audits/THREE-WAY-INPUT-BOUNDARY-AUDIT.md)
+//! > proved that minting a `StateRevision` at the authoritative mutation is the
+//! > only candidate that can supply `base`. What does doing so *cost*, and what
+//! > bounds it?
+//!
+//! Two results decide it. The cost is measurable and linear, with a fixed
+//! per-revision overhead of roughly half a kilobyte that nothing collects. And
+//! content-only identity does not survive per-mutation minting: a resource that
+//! returns to a previous value silently rewrites the ancestry of the revision it
+//! returns to, producing a cycle in the durable parent chain.
+//!
+//! # Superseded in part
+//!
+//! The identity findings here caused the resource-scoped model to be adopted,
+//! and are **fixed**: the tests that recorded them now record the fix instead,
+//! and say so individually. Two consequences of that change are recorded here
+//! rather than argued:
+//!
+//! - **Content addressing no longer bounds anything.** Identity includes the
+//!   resource and a sequence, so repeated state does not collapse. The bound
+//!   this audit found is gone, replaced by an explicit retention policy.
+//! - **The cost constants changed.** A revision now carries a resource, a
+//!   second identity and a sequence. The shape is still linear; the constants
+//!   are not the ones measured here.
+//!
+//! Re-measuring the economics against the adopted model is deliberately *not*
+//! done here — it is the next step, and doing it inside the implementation
+//! would mix a measurement with the change being measured.
+
+use feltdb::state_model::{ParentLookup, RetentionPolicy, StateStore};
+use feltdb::{FeltDb, JsonCasResult};
+use serde_json::json;
+use std::sync::Arc;
+use tempfile::TempDir;
+
+/// Build a durable store, commit `count` revisions of a state padded to a known
+/// size, then acknowledge and compact. Returns the compacted log's contents.
+fn compacted_log_after_revisions(count: usize, pad: usize) -> String {
+    let directory = TempDir::new().unwrap();
+    let path = directory.path().join("revisions.log");
+    let db = Arc::new(FeltDb::open(&path).unwrap());
+    let store = StateStore::with_feltdb(db.clone()).unwrap();
+
+    let filler = "x".repeat(pad);
+    let mut revision = store
+        .create(
+            "docs:1",
+            format!(r#"{{"n":0,"pad":"{filler}"}}"#),
+            "authority".into(),
+        )
+        .unwrap();
+    for n in 1..count {
+        revision = store
+            .commit(
+                format!(r#"{{"n":{n},"pad":"{filler}"}}"#),
+                &revision,
+                "authority".into(),
+            )
+            .unwrap();
+    }
+
+    let versions = db.operation_versions().unwrap();
+    db.acknowledge_peer_versions("peer-1".to_string(), versions)
+        .unwrap();
+    db.compact_operation_log(&["peer-1".to_string()]).unwrap();
+
+    std::fs::read_to_string(&path).unwrap()
+}
+
+fn revision_lines(log: &str) -> usize {
+    log.lines()
+        .filter(|line| line.contains("state:revision:"))
+        .count()
+}
+
+// ---------------------------------------------------------------------------
+// Retention: what bounds the revision store
+// ---------------------------------------------------------------------------
+
+/// **Nothing collects revisions — least of all the operation that collects.**
+///
+/// The three-way input boundary audit showed `compact_operation_log` deleting
+/// ancestry: acknowledged operations are pruned, and the log is rewritten as a
+/// snapshot of the *current rows*. That is exactly why it cannot supply `base`.
+///
+/// The same mechanism has the opposite effect on revisions, and for the same
+/// reason. A revision is a current row — one per `state:revision:{hex}` key — so
+/// the snapshot pass preserves every one of them. Compaction is the only
+/// operation in the system that removes durable history, and it is structurally
+/// incapable of removing a revision.
+///
+/// `StateStore` exposes no deletion of its own: `create`, `commit`, `get`,
+/// `exists`, `metadata` and `parent`, and nothing else. So under candidate B the
+/// revision store grows monotonically with the number of authoritative
+/// mutations, with no mechanism — existing or exposed — that can shrink it.
+#[test]
+fn compaction_preserves_every_revision_it_finds() {
+    let directory = TempDir::new().unwrap();
+    let path = directory.path().join("survive.log");
+    let db = Arc::new(FeltDb::open(&path).unwrap());
+    let store = StateStore::with_feltdb(db.clone()).unwrap();
+
+    let mut ids = Vec::new();
+    let mut revision = store
+        .create("docs:1", r#"{"n":0}"#.into(), "authority".into())
+        .unwrap();
+    ids.push(revision.id.clone());
+    for n in 1..25 {
+        revision = store
+            .commit(format!(r#"{{"n":{n}}}"#), &revision, "authority".into())
+            .unwrap();
+        ids.push(revision.id.clone());
+    }
+
+    let versions = db.operation_versions().unwrap();
+    db.acknowledge_peer_versions("peer-1".to_string(), versions)
+        .unwrap();
+    let removed = db.compact_operation_log(&["peer-1".to_string()]).unwrap();
+    assert!(removed > 0, "compaction pruned acknowledged operations");
+
+    drop(store);
+    drop(db);
+    let reopened = Arc::new(FeltDb::open(&path).unwrap());
+    let store = StateStore::with_feltdb(reopened).unwrap();
+
+    let surviving = ids.iter().filter(|id| store.exists(id)).count();
+    assert_eq!(
+        surviving,
+        ids.len(),
+        "every revision survived the one operation that deletes history"
+    );
+}
+
+/// **Each compaction rewrites the entire revision history.**
+///
+/// The snapshot pass writes one line per current row, so the cost of a
+/// compaction is proportional to the number of revisions ever minted — a number
+/// that only grows. The operation that exists to stop the log growing without
+/// bound therefore becomes more expensive with every mutation the system has
+/// ever performed, and never cheaper.
+#[test]
+fn each_compaction_rewrites_the_whole_revision_history() {
+    let directory = TempDir::new().unwrap();
+    let path = directory.path().join("rewrite.log");
+    let db = Arc::new(FeltDb::open(&path).unwrap());
+    let store = StateStore::with_feltdb(db.clone()).unwrap();
+
+    let mut revision = store
+        .create("docs:1", r#"{"n":0}"#.into(), "authority".into())
+        .unwrap();
+    for n in 1..10 {
+        revision = store
+            .commit(format!(r#"{{"n":{n}}}"#), &revision, "authority".into())
+            .unwrap();
+    }
+
+    let versions = db.operation_versions().unwrap();
+    db.acknowledge_peer_versions("peer-1".to_string(), versions)
+        .unwrap();
+    db.compact_operation_log(&["peer-1".to_string()]).unwrap();
+    let first = std::fs::read_to_string(&path).unwrap();
+    assert_eq!(revision_lines(&first), 10);
+
+    // One unrelated write on another resource, acknowledged and compacted
+    // again. It mints a revision of its own, and the ten existing ones are
+    // written out in full a second time regardless.
+    db.insert("tasks:1", json!({"unrelated": true})).unwrap();
+    let versions = db.operation_versions().unwrap();
+    db.acknowledge_peer_versions("peer-1".to_string(), versions)
+        .unwrap();
+    db.compact_operation_log(&["peer-1".to_string()]).unwrap();
+    let second = std::fs::read_to_string(&path).unwrap();
+
+    assert_eq!(
+        revision_lines(&second),
+        11,
+        "the second compaction rewrote all ten revisions, plus the one the \
+         unrelated write minted, to serve that single write"
+    );
+}
+
+// ---------------------------------------------------------------------------
+// Cost: what a revision is worth in bytes
+// ---------------------------------------------------------------------------
+
+/// **A revision costs a fixed overhead of roughly half a kilobyte, plus one
+/// copy of its own state.**
+///
+/// The compacted log is linear in both the revision count and the state size:
+///
+/// ```text
+/// bytes = header + count × (fixed_overhead + |content|)
+/// ```
+///
+/// The fixed part is not incidental — it is a 64-character hex identity, a
+/// 64-character parent identity, an authority, a timestamp, a metadata map, and
+/// the `StoredRow` wrapper carrying the capability, the `state:revision:{hex}`
+/// key and the fully-qualified Rust type name. It dominates until the state
+/// being versioned is itself several hundred bytes.
+///
+/// The state is stored exactly once per revision, not twice. But it is stored
+/// *escaped*, inside a JSON string field of the record — so every quote in the
+/// versioned document costs a second byte.
+#[test]
+fn a_revision_costs_a_fixed_overhead_plus_one_copy_of_its_state() {
+    let small_ten = compacted_log_after_revisions(10, 0).len();
+    let small_twenty = compacted_log_after_revisions(20, 0).len();
+    let padded_hundred = compacted_log_after_revisions(10, 100).len();
+    let padded_thousand = compacted_log_after_revisions(10, 1000).len();
+
+    // Ten more revisions of a 16-byte state cost ten more per-revision records.
+    // Indices 10..19 are one digit wider than 0..9, hence the ten-byte term.
+    let ten_more = small_twenty - small_ten - 10;
+    let per_revision = ten_more / 10;
+    // The shape is unchanged by the resource-scoped model; the constant is
+    // not. A revision now also carries its resource, a second identity and a
+    // sequence, so the floor is higher than the 492 bytes measured before the
+    // model was adopted. Re-measuring the economics properly is a separate
+    // step; this assertion exists to catch the shape changing, not to be the
+    // measurement.
+    assert!(
+        (550..=750).contains(&per_revision),
+        "a revision of a 16-byte state costs {per_revision} bytes; \
+         the overhead is the record, not the state"
+    );
+
+    // Content is stored exactly once: growing each state by N bytes grows the
+    // log by exactly count × N.
+    assert_eq!(
+        padded_hundred - small_ten,
+        10 * 100,
+        "a hundred more bytes of state costs a hundred more bytes per revision"
+    );
+    assert_eq!(
+        padded_thousand - small_ten,
+        10 * 1000,
+        "the relationship stays exactly linear at a kilobyte of state"
+    );
+}
+
+/// **Content addressing was the only bound, and adopting model C removed it.**
+///
+/// This test recorded the opposite: three commits of two distinct states were
+/// stored as two records, because identity was content and repeated content
+/// collapsed. That deduplication was the only thing bounding storage growth.
+///
+/// Under the resource-scoped model it is gone. A resource that returns to a
+/// value it previously held records a new revision, because identity includes
+/// the resource and the position in its history. Three commits are three
+/// records.
+///
+/// The bound did not disappear — it moved, from an accident of hashing to an
+/// explicit retention policy, which the next test exercises.
+#[test]
+fn repeated_state_no_longer_deduplicates() {
+    let directory = TempDir::new().unwrap();
+    let path = directory.path().join("dedupe.log");
+    let db = Arc::new(FeltDb::open(&path).unwrap());
+    let store = StateStore::with_feltdb(db.clone()).unwrap();
+
+    let first = store
+        .create("docs:1", r#"{"title":"A"}"#.into(), "authority".into())
+        .unwrap();
+    let second = store
+        .commit(r#"{"title":"B"}"#.into(), &first, "authority".into())
+        .unwrap();
+    let third = store
+        .commit(r#"{"title":"A"}"#.into(), &second, "authority".into())
+        .unwrap();
+
+    assert_ne!(third.id, first.id, "returning to A is a new revision");
+    assert_eq!(
+        third.content_id, first.content_id,
+        "and it is still the same state"
+    );
+
+    let versions = db.operation_versions().unwrap();
+    db.acknowledge_peer_versions("peer-1".to_string(), versions)
+        .unwrap();
+    db.compact_operation_log(&["peer-1".to_string()]).unwrap();
+    let log = std::fs::read_to_string(&path).unwrap();
+
+    assert_eq!(
+        revision_lines(&log),
+        3,
+        "three commits are three records; nothing collapses any more"
+    );
+}
+
+/// **The bound that replaced deduplication.**
+///
+/// Retention is per-resource, count-based, and applied at the moment history is
+/// created rather than at a maintenance pass that may never run. The current
+/// revision always survives, and what remains is a suffix of the timeline.
+#[test]
+fn revision_retention_bounds_a_resources_history() {
+    let directory = TempDir::new().unwrap();
+    let db = Arc::new(FeltDb::open(directory.path().join("retain.log")).unwrap());
+    let store = StateStore::with_feltdb(db.clone()).unwrap();
+
+    store
+        .set_retention_policy("docs:1", RetentionPolicy::keep_last(3))
+        .unwrap();
+
+    db.insert("docs:1", json!({"n": 0})).unwrap();
+    for n in 1..40 {
+        db.update("docs:1", json!({ "n": n })).unwrap();
+    }
+
+    let history = store.history_of("docs:1");
+    assert_eq!(history.len(), 3, "forty writes, three retained revisions");
+    assert!(
+        history[2].content.contains(r#""n":39"#),
+        "the current revision survives"
+    );
+    assert!(
+        history[0].sequence < history[1].sequence && history[1].sequence < history[2].sequence,
+        "what remains is a suffix of the timeline, in order"
+    );
+}
+
+/// **An expired ancestor is not a dangling one.**
+///
+/// The hazard in bounding history is recreating the dangling-parent defect at
+/// the other end of the system: expire an ancestor, and its child names a parent
+/// that is not there.
+///
+/// The child's `parent_id` is *not* rewritten — that would violate the
+/// immutability the model is built on. Instead the resource records a horizon,
+/// and the oldest survivor reports an **expired** parent rather than a missing
+/// one. They are different facts, and the store says which.
+#[test]
+fn an_expired_ancestor_is_distinguishable_from_a_missing_one() {
+    let directory = TempDir::new().unwrap();
+    let db = Arc::new(FeltDb::open(directory.path().join("horizon.log")).unwrap());
+    let store = StateStore::with_feltdb(db.clone()).unwrap();
+
+    store
+        .set_retention_policy("docs:1", RetentionPolicy::keep_last(2))
+        .unwrap();
+    db.insert("docs:1", json!({"n": 0})).unwrap();
+    for n in 1..6 {
+        db.update("docs:1", json!({ "n": n })).unwrap();
+    }
+
+    let history = store.history_of("docs:1");
+    assert_eq!(history.len(), 2);
+    let oldest = &history[0];
+
+    assert!(
+        oldest.parent_id.is_some(),
+        "the oldest survivor still names the parent it was committed with"
+    );
+    assert!(
+        matches!(store.parent_of(&oldest.id), Some(ParentLookup::Expired(_))),
+        "and the store reports that parent as expired, not missing"
+    );
+    assert!(
+        store.retention_horizon("docs:1") > 0,
+        "the horizon records where history was deliberately cut"
+    );
+
+    assert!(
+        matches!(
+            store.parent_of(&history[1].id),
+            Some(ParentLookup::Revision(_))
+        ),
+        "the newer revision's parent is still there and resolves"
+    );
+}
+
+// ---------------------------------------------------------------------------
+// Which mutations could mint
+// ---------------------------------------------------------------------------
+
+/// **The unconditional write paths consult nothing in the prior document.**
+///
+/// The fenced path refuses a write on the basis of a nested field of the
+/// previous document — `/authority/epoch` — which is how the three-way input
+/// boundary audit established that the whole prior state is in hand there.
+///
+/// The unconditional path has no such behaviour to exhibit: `update` replaces a
+/// document that the equivalent fenced write would have refused, and replaces it
+/// with one that drops the fence fields entirely. It needs nothing from what was
+/// there. `insert_internal` and `update_internal`
+/// (`crates/feltdb/src/lib.rs:1758` and `:1827`) confirm it — both construct a
+/// fresh `StoredRow` and call `put_row` without reading the existing one.
+///
+/// So the two paths do not have the same cost under candidate B. A revision
+/// minted at the fence has its parent for free. A revision minted on `insert` or
+/// `update` has no parent at all unless a read is added — and a parentless
+/// revision is indistinguishable from an initial one, which is the same as
+/// having no `base`.
+#[test]
+fn the_unconditional_path_needs_nothing_from_the_prior_document() {
+    let directory = TempDir::new().unwrap();
+    let db = FeltDb::open(directory.path().join("blind.log")).unwrap();
+
+    db.insert(
+        "tasks:1",
+        json!({"title": "A", "__version": 1, "authority": {"epoch": 7}}),
+    )
+    .unwrap();
+
+    // The fence reads into the prior document and refuses on what it finds.
+    let refused = db
+        .compare_and_set_json("tasks:1", 1, Some(6), None, false, json!({"title": "B"}))
+        .unwrap();
+    assert!(
+        matches!(refused, JsonCasResult::AuthorityConflict { .. }),
+        "the fenced write consulted the prior document: {refused:?}"
+    );
+
+    // The unconditional write does not, and succeeds on the same document.
+    db.update("tasks:1", json!({"title": "B"})).unwrap();
+    let now: serde_json::Value = db.get("tasks:1").unwrap().unwrap();
+    assert_eq!(now["title"], json!("B"));
+    assert!(
+        now.get("authority").is_none() && now.get("__version").is_none(),
+        "it replaced the document wholesale, including the fields the fence reads"
+    );
+}

package/dist/create/server-source/crates/feltdb/tests/saas_authorization_integration.rs

@@ -20,14 +20,14 @@ fn saas_authorization_fixture_compiles() {
     // This test verifies the SaaS fixture schema is valid.
     // In Phase 2, this will be replaced with real authorization tests
     // that go through the actual FeltDB query/mutation API.
-    
+
     // Fixture schema (valid FlowSpec):
     // - User collection
     // - Organization collection with policy { read: member, write: owner }
     // - Membership collection with user/org references
     // - Project collection with org/owner references
     //   policy { read: member, write: member }
-    
+
     // This test passes if compilation succeeds.
     assert!(true, "SaaS fixture schema is valid");
 }
@@ -75,7 +75,7 @@ fn saas_authorization_phase_2_integration_planned() {
     // 10. SaaS template integration
     //     Verify the actual SaaSExample template doesn't
     //     reimplement authorization in TypeScript
-    
+
     // This test passes once Phase 2 implements the above.
     assert!(true, "Phase 2 integration tests are planned");
 }

package/dist/create/server-source/crates/feltdb/tests/saas_invitation_lifecycle.rs

@@ -12,9 +12,8 @@
 
 use feltdb::{
     state_contract::{
-        StateSchema, CollectionSchema, FieldSchema, FieldType, PrimitiveType,
-        AuthorizationContext, CanonicalQuery, begin_read, execute_query,
-        QueryFilter,
+        begin_read, execute_query, AuthorizationContext, CanonicalQuery, CollectionSchema,
+        FieldSchema, FieldType, PrimitiveType, QueryFilter, StateSchema,
     },
     FeltDb,
 };
@@ -60,7 +59,10 @@ fn saas_invitation_architecture_test() {
     // Full integration tests will exercise the actual FeltDB APIs
     // with realistic query/mutation payloads once this pattern is validated.
 
-    assert!(true, "Invitation → Membership → Access pattern is architecturally valid");
+    assert!(
+        true,
+        "Invitation → Membership → Access pattern is architecturally valid"
+    );
 }
 
 #[test]
@@ -99,11 +101,15 @@ fn saas_invitation_lifecycle_phase_2_state_transition_proves_generalization() {
     // 2. Workflows are ordinary state transitions
     // 3. Access changes via state, not authorization code
 
-    assert!(true, "State transitions create authorization changes without code changes");
+    assert!(
+        true,
+        "State transitions create authorization changes without code changes"
+    );
 }
 
 #[test]
-fn saas_invitation_lifecycle_phase_3_capability_gap_detection() -> Result<(), Box<dyn std::error::Error>> {
+fn saas_invitation_lifecycle_phase_3_capability_gap_detection(
+) -> Result<(), Box<dyn std::error::Error>> {
     // Phase 3: Capability probe - can invited users see their invitations?
     //
     // The member policy requires Membership(user, org) to read Invitation.
@@ -167,19 +173,17 @@ fn saas_invitation_lifecycle_phase_3_capability_gap_detection() -> Result<(), Bo
             CollectionSchema {
                 name: "Organization".to_string(),
                 version: 1,
-                fields: vec![
-                    FieldSchema {
-                        name: "_id".to_string(),
-                        field_type: FieldType::Primitive {
-                            primitive: PrimitiveType::String,
-                        },
-                        nullable: false,
-                        required: true,
-                        default: None,
-                        constraints: Default::default(),
-                        computed: None,
+                fields: vec![FieldSchema {
+                    name: "_id".to_string(),
+                    field_type: FieldType::Primitive {
+                        primitive: PrimitiveType::String,
                     },
-                ],
+                    nullable: false,
+                    required: true,
+                    default: None,
+                    constraints: Default::default(),
+                    computed: None,
+                }],
                 indexes: vec![],
             },
             // Membership collection (establishes access)
@@ -340,8 +344,7 @@ fn saas_invitation_lifecycle_phase_3_capability_gap_detection() -> Result<(), Bo
         field_projections: Default::default(),
     };
 
-    let bob_context = begin_read(&db, &schema, "app", bob_auth)
-        .map_err(|e| format!("{:?}", e))?;
+    let bob_context = begin_read(&db, &schema, "app", bob_auth).map_err(|e| format!("{:?}", e))?;
 
     // Bob queries Invitations with filter on his email
     let query = CanonicalQuery {
@@ -360,8 +363,8 @@ fn saas_invitation_lifecycle_phase_3_capability_gap_detection() -> Result<(), Bo
         references: vec![],
     };
 
-    let result = execute_query(&db, &schema, &bob_context, &query, None)
-        .map_err(|e| format!("{:?}", e))?;
+    let result =
+        execute_query(&db, &schema, &bob_context, &query, None).map_err(|e| format!("{:?}", e))?;
 
     // CRITICAL FINDING:
     // If result.records.len() > 0: Bob CAN see his invitation