create-feltdb 0.10.0 → 0.11.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.10.0';
+export const FELTDB_PACKAGE_VERSION = '0.11.1';
 export const feltdbPackageRange = `^${FELTDB_PACKAGE_VERSION}`;

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

@@ -287,12 +287,12 @@ use std::any::type_name;
 use std::collections::hash_map::DefaultHasher;
 use std::collections::{BTreeMap, BTreeSet, HashMap, HashSet, VecDeque};
 use std::fmt::{Display, Formatter};
-use std::fs::{self, OpenOptions};
+use std::fs::{self, File, OpenOptions};
 use std::hash::{Hash, Hasher};
 use std::io::{BufRead, BufReader, Write};
 use std::ops::Bound::{Excluded, Unbounded};
 use std::path::{Path, PathBuf};
-use std::sync::{Arc, Mutex};
+use std::sync::{Arc, Mutex, OnceLock, Weak};
 use std::time::{SystemTime, UNIX_EPOCH};
 use tokio::sync::broadcast;
 
@@ -369,8 +369,17 @@ impl From<String> for FlowError {
 pub struct FeltDb {
     inner: Arc<Mutex<Inner>>,
     event_tx: broadcast::Sender<ChangeEvent>,
+    _ownership: Arc<File>,
 }
 
+struct OpenDatabase {
+    inner: Weak<Mutex<Inner>>,
+    event_tx: broadcast::Sender<ChangeEvent>,
+    ownership: Weak<File>,
+}
+
+static OPEN_DATABASES: OnceLock<Mutex<HashMap<PathBuf, OpenDatabase>>> = OnceLock::new();
+
 #[derive(Default)]
 #[allow(dead_code)] // Reserved runtime subsystems are initialized before their public APIs land.
 struct Inner {
@@ -1968,7 +1977,56 @@ struct RetentionRecord {
 
 impl FeltDb {
     pub fn open<P: AsRef<Path>>(path: P) -> Result<Self> {
-        let path = path.as_ref().to_path_buf();
+        let requested_path = path.as_ref();
+        let parent = requested_path
+            .parent()
+            .filter(|parent| !parent.as_os_str().is_empty())
+            .unwrap_or_else(|| Path::new("."));
+        fs::create_dir_all(parent)?;
+        let path = if requested_path.exists() {
+            fs::canonicalize(requested_path)?
+        } else {
+            let file_name = requested_path.file_name().ok_or_else(|| {
+                std::io::Error::new(
+                    std::io::ErrorKind::InvalidInput,
+                    "FeltDB database path has no file name",
+                )
+            })?;
+            fs::canonicalize(parent)?.join(file_name)
+        };
+
+        let databases = OPEN_DATABASES.get_or_init(|| Mutex::new(HashMap::new()));
+        let mut databases = databases.lock().expect("open database registry poisoned");
+        if let Some(open) = databases.get(&path) {
+            if let (Some(inner), Some(ownership)) =
+                (open.inner.upgrade(), open.ownership.upgrade())
+            {
+                return Ok(Self {
+                    inner,
+                    event_tx: open.event_tx.clone(),
+                    _ownership: ownership,
+                });
+            }
+        }
+        databases.remove(&path);
+
+        let mut ownership_path = path.as_os_str().to_os_string();
+        ownership_path.push(".lock");
+        let ownership = OpenOptions::new()
+            .create(true)
+            .read(true)
+            .write(true)
+            .open(PathBuf::from(ownership_path))?;
+        ownership.try_lock().map_err(|error| match error {
+            std::fs::TryLockError::WouldBlock => std::io::Error::new(
+                std::io::ErrorKind::WouldBlock,
+                format!(
+                    "FeltDB database {} is already owned by another process",
+                    path.display()
+                ),
+            ),
+            std::fs::TryLockError::Error(error) => error,
+        })?;
 
         // Fail closed. The format is decided before any record is interpreted
         // and before anything is written, so a database this build does not
@@ -1981,9 +2039,6 @@ impl FeltDb {
             FormatCompatibility::Compatible(format) => format,
         };
 
-        if let Some(parent) = path.parent() {
-            fs::create_dir_all(parent)?;
-        }
         if !path.exists() {
             let mut file = OpenOptions::new().create(true).append(true).open(&path)?;
             // A new database states its format in its first record, so it never
@@ -2019,10 +2074,20 @@ impl FeltDb {
 
         let (event_tx, _) = broadcast::channel(1024);
 
-        Ok(Self {
+        let database = Self {
             inner: Arc::new(Mutex::new(inner)),
             event_tx,
-        })
+            _ownership: Arc::new(ownership),
+        };
+        databases.insert(
+            path,
+            OpenDatabase {
+                inner: Arc::downgrade(&database.inner),
+                event_tx: database.event_tx.clone(),
+                ownership: Arc::downgrade(&database._ownership),
+            },
+        );
+        Ok(database)
     }
 
     /// Write a self-contained durable backup artifact.
@@ -2264,10 +2329,21 @@ impl FeltDb {
             .map(|(cap, _)| cap)
             .unwrap_or("default")
             .to_string();
-        self.insert_internal(capability, key.to_string(), value)?;
+        self.insert_internal(capability, key.to_string(), value, false)?;
         Ok(())
     }
 
+    /// Insert only if the logical record is absent, deciding presence under the
+    /// same lock that appends the operation and mints its first revision.
+    pub fn insert_if_absent<T: Serialize>(&self, key: &str, value: T) -> Result<()> {
+        let capability = key
+            .split_once(':')
+            .map(|(cap, _)| cap)
+            .unwrap_or("default")
+            .to_string();
+        self.insert_internal(capability, key.to_string(), value, true)
+    }
+
     /// Update an existing record with vector clock tracking
     pub fn update<T: Serialize>(&self, key: &str, value: T) -> Result<()> {
         let capability = key
@@ -2480,7 +2556,7 @@ impl FeltDb {
         }
 
         // Authorized: apply mutation
-        self.insert_internal(capability, key.to_string(), value)?;
+        self.insert_internal(capability, key.to_string(), value, false)?;
         Ok(())
     }
 
@@ -3195,6 +3271,7 @@ impl FeltDb {
         capability: String,
         key: String,
         value: T,
+        require_absent: bool,
     ) -> Result<()> {
         let rust_type = type_name::<T>().to_string();
         let value_json = serde_json::to_value(value)?;
@@ -3216,6 +3293,21 @@ impl FeltDb {
         {
             let mut inner = self.state();
 
+            if require_absent
+                && inner
+                    .rows
+                    .get(&capability)
+                    .and_then(|bucket| bucket.get(&key))
+                    .is_some()
+            {
+                return Err(FlowError::PreconditionFailed(Box::new(
+                    PreconditionFailure::Present {
+                        collection: capability,
+                        key,
+                    },
+                )));
+            }
+
             // Increment sequence number
             inner.sequence += 1;
 
@@ -4497,7 +4589,7 @@ impl Capability {
             key
         };
         self.db
-            .insert_internal(self.name.clone(), key.clone(), value)?;
+            .insert_internal(self.name.clone(), key.clone(), value, false)?;
         Ok(key)
     }
 
@@ -4507,7 +4599,8 @@ impl Capability {
         } else {
             format!("{}:{key}", self.name)
         };
-        self.db.insert_internal(self.name.clone(), full_key, value)
+        self.db
+            .insert_internal(self.name.clone(), full_key, value, false)
     }
 
     pub fn update<T: Serialize>(&self, key: &str, value: T) -> Result<()> {

package/dist/server-source/crates/feltdb/tests/local_process_ownership.rs

@@ -0,0 +1,69 @@
+use std::process::Command;
+
+use feltdb::{AtomicMutation, FeltDb};
+use serde_json::json;
+use tempfile::TempDir;
+
+const CHILD_ENV: &str = "FELTDB_OWNERSHIP_CHILD";
+const PATH_ENV: &str = "FELTDB_OWNERSHIP_PATH";
+const EXPECT_LOCKED_ENV: &str = "FELTDB_EXPECT_LOCKED";
+
+#[test]
+fn ownership_child() {
+    if std::env::var_os(CHILD_ENV).is_none() {
+        return;
+    }
+    let path = std::env::var(PATH_ENV).unwrap();
+    let expect_locked = std::env::var_os(EXPECT_LOCKED_ENV).is_some();
+    match FeltDb::open(path) {
+        Ok(database) => {
+            assert!(!expect_locked, "a second owner opened the database");
+            let mutation = AtomicMutation {
+                capability: "probe".into(),
+                key: "probe:child".into(),
+                value: Some(json!({ "owner": "child" })),
+            };
+            database
+                .apply_atomic_transaction("child", None, &[], &[mutation], None)
+                .unwrap();
+        }
+        Err(error) => {
+            assert!(expect_locked, "an unowned database failed to open: {error}");
+            assert!(error.to_string().contains("already owned"));
+        }
+    }
+}
+
+fn child(path: &std::path::Path, expect_locked: bool) -> std::process::ExitStatus {
+    let mut command = Command::new(std::env::current_exe().unwrap());
+    command
+        .arg("--exact")
+        .arg("ownership_child")
+        .arg("--nocapture")
+        .env(CHILD_ENV, "1")
+        .env(PATH_ENV, path);
+    if expect_locked {
+        command.env(EXPECT_LOCKED_ENV, "1");
+    }
+    command.status().unwrap()
+}
+
+#[test]
+fn another_process_cannot_read_write_or_transact_while_owned() {
+    let directory = TempDir::new().unwrap();
+    let path = directory.path().join("shared.db");
+    let _owner = FeltDb::open(&path).unwrap();
+    assert!(child(&path, true).success());
+}
+
+#[test]
+fn ownership_is_released_when_the_process_exits() {
+    let directory = TempDir::new().unwrap();
+    let path = directory.path().join("shared.db");
+    assert!(child(&path, false).success());
+    let database = FeltDb::open(path).unwrap();
+    assert_eq!(
+        database.get::<serde_json::Value>("probe:child").unwrap(),
+        Some(json!({ "owner": "child" }))
+    );
+}

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

@@ -203,7 +203,7 @@ fn each_compaction_rewrites_the_whole_revision_history() {
 /// The compacted log is linear in both the revision count and the state size:
 ///
 /// ```text
-/// bytes = header + count × (fixed_overhead + 2 × |content|)
+/// bytes ≈ header + count × (fixed_overhead + 2 × |content|)
 /// ```
 ///
 /// The fixed part is not incidental — it is a 64-character hex identity, a
@@ -218,10 +218,11 @@ fn each_compaction_rewrites_the_whole_revision_history() {
 /// design.
 #[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_ten_log = compacted_log_after_revisions(10, 0);
+    let small_ten = small_ten_log.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();
+    let padded_hundred_log = compacted_log_after_revisions(10, 100);
+    let padded_thousand_log = compacted_log_after_revisions(10, 1000);
 
     // 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.
@@ -239,17 +240,31 @@ fn a_revision_costs_a_fixed_overhead_plus_one_copy_of_its_state() {
     );
 
     // Content is represented in both the revision and its canonical
-    // transaction attribution: growing each state by N bytes grows the log by
-    // exactly count × 2N.
+    // transaction attribution. Count those copies directly instead of
+    // requiring unrelated encoded metadata to have byte-for-byte identical
+    // size across platforms and runs.
     assert_eq!(
-        padded_hundred - small_ten,
-        10 * 2 * 100,
-        "state appears in the revision and canonical transaction attribution"
+        padded_hundred_log.matches("x".repeat(100).as_str()).count(),
+        10 * 2,
+        "each state appears in its revision and canonical transaction attribution"
     );
     assert_eq!(
-        padded_thousand - small_ten,
-        10 * 2 * 1000,
-        "the relationship stays exactly linear at a kilobyte of state"
+        padded_thousand_log
+            .matches("x".repeat(1000).as_str())
+            .count(),
+        10 * 2,
+        "the two-copy relationship remains direct at a kilobyte of state"
+    );
+
+    let hundred_growth = padded_hundred_log.len() - small_ten;
+    let thousand_growth = padded_thousand_log.len() - small_ten;
+    assert!(
+        hundred_growth.abs_diff(10 * 2 * 100) <= 100,
+        "the measured 100-byte content term was {hundred_growth} bytes"
+    );
+    assert!(
+        thousand_growth.abs_diff(10 * 2 * 1000) <= 1_000,
+        "the measured 1,000-byte content term was {thousand_growth} bytes"
     );
 }
 

package/dist/server-source/crates/feltdb-server/src/main.rs

@@ -13536,17 +13536,19 @@ async fn create_record(
         .take()
         .unwrap_or_else(|| state.ids.fetch_add(1, Ordering::Relaxed).to_string());
     let key = record_key(&collection, &id)?;
-    if state.db.get_value(&key)?.is_some() {
-        return Err(ApiError(
-            StatusCode::CONFLICT,
-            "record already exists".to_string(),
-        ));
-    }
     record
         .value
         .insert("id".to_string(), Value::String(id.clone()));
     let value = Value::Object(record.value);
-    state.db.insert(&key, &value)?;
+    state
+        .db
+        .insert_if_absent(&key, &value)
+        .map_err(|error| match error {
+            FlowError::PreconditionFailed(_) => {
+                ApiError(StatusCode::CONFLICT, "record already exists".to_string())
+            }
+            other => ApiError(StatusCode::CONFLICT, other.to_string()),
+        })?;
     Ok((
         StatusCode::CREATED,
         Json(RecordResponse {
@@ -14700,7 +14702,7 @@ async fn control_plane_record_provenance(
         "attribution": {
             "actor": transactions.first().and_then(|attribution| attribution.subject.clone()),
             "authority": row.operation.as_ref().map(|operation| operation.instance_id.clone()),
-            "source": if transactions.first().is_some() { "transaction" } else if row.operation.is_some() { "authority" } else { "unknown" },
+            "source": if capability == collection && row.operation.is_some() { "authority" } else if transactions.first().is_some() { "transaction" } else if row.operation.is_some() { "authority" } else { "unknown" },
         },
     })))
 }

package/package.json

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