@feltdb/core 0.12.1 → 0.12.2

package/dist/create/cli.js

@@ -362,13 +362,13 @@ Learn more: https://github.com/rkendel1/feltdb`);
             }
         }
         else {
-            console.log('Project is ready. Start the application with:');
+            console.log('Project is ready. Start it with:');
             console.log(`  cd ${projectName}`);
             if (!shouldInstall)
                 console.log('  npm install');
-            console.log('  npm run dev');
-            console.log('Start FeltDB development tooling separately with:');
             console.log('  npm run feltdb:dev');
+            console.log('This starts the application, the development authority, and Studio together.');
+            console.log('Do not also run npm run dev: that second copy is not managed by FeltDB.');
         }
     }
     catch (error) {

package/dist/create/create.js

@@ -196,6 +196,12 @@ ${hasAgents ? `  agent WorkspaceAssistant {
         tsconfig.compilerOptions.types = ['vite/client'];
     }
     fs.writeFileSync(path.join(projectDir, 'tsconfig.json'), JSON.stringify(tsconfig, null, 2));
+    // Browsers do not expose VITE_* through process.env, so a local database must be handed its
+    // namespace explicitly; otherwise it opens the shared `default` store and `feltdb dev` cannot
+    // recognise the application. A managed (remote) runtime resolves its target from its URL.
+    const createDatabaseCall = runtime === 'managed'
+        ? 'createFeltDB()'
+        : `createFeltDB({ namespace: import.meta.env.VITE_FELTDB_NAMESPACE || ${JSON.stringify(applicationName)} })`;
     // Create main application files
     const feltdbTs = `import { configureDevelopmentRuntimeBridge, createFeltDB } from '@feltdb/core';
 
@@ -209,7 +215,7 @@ configureDevelopmentRuntimeBridge({
   applicationUrl: import.meta.env.VITE_FELTDB_APPLICATION_URL,
 });
 
-export const db = createFeltDB();
+export const db = ${createDatabaseCall};
 
 // Collections
 export const projects = db.collection('Project');
@@ -1193,7 +1199,7 @@ root.render(
             }
             fs.writeFileSync(path.join(projectDir, 'feltdb.flow'), fs.readFileSync(path.join(canonicalTemplate, 'feltdb.flow'), 'utf8').replace('app FeltDBStarter', `app ${appName}`));
             const databasePath = path.join(srcDir, 'feltdb.ts');
-            fs.writeFileSync(databasePath, fs.readFileSync(databasePath, 'utf8').replace(/export const managedRuntime[\s\S]*?\n\} : \{ namespace: import\.meta\.env\.VITE_FELTDB_NAMESPACE \|\| 'feltdb-starter', browser: true \}\);/, `export const managedRuntime = ${runtime === 'managed'};\nexport const db = createFeltDB();`));
+            fs.writeFileSync(databasePath, fs.readFileSync(databasePath, 'utf8').replace(/export const managedRuntime[\s\S]*?\n\} : \{ namespace: import\.meta\.env\.VITE_FELTDB_NAMESPACE \|\| 'feltdb-starter', browser: true \}\);/, `export const managedRuntime = ${runtime === 'managed'};\nexport const db = ${createDatabaseCall};`));
         }
     }
     else {
@@ -1558,22 +1564,17 @@ A FeltDB Workspace application demonstrating local-first database capabilities.
 
 ## Quick Start
 
-Start the application:
+Start everything:
 
 \`\`\`bash
 npm install
-npm run dev
-\`\`\`
-
-The application will be available at http://localhost:5173 (or your configured port).
-
-In a second terminal, start FeltDB authority, pairing, and Studio and attach it
-to the application explicitly:
-
-\`\`\`bash
 npm run feltdb:dev
 \`\`\`
 
+\`feltdb dev\` starts the application, the development authority, pairing, and Studio together
+and prints the address of each. Do not also run \`npm run dev\`: that second copy is not
+managed by FeltDB, so Studio cannot see it.
+
 ## FeltDB Workspace Showcase
 
 This application demonstrates core FeltDB capabilities:
@@ -1698,17 +1699,14 @@ Never expose \`FELTDB_MANAGED_CONTROL_API_KEY\` or \`FELTDB_TOKEN\` through a \`
 
 ## Development
 
-### Start Development Server
-\`\`\`bash
-npm run dev
-\`\`\`
-
-### Start FeltDB Development Tooling
-
+### Start the Development Environment
 \`\`\`bash
 npm run feltdb:dev
 \`\`\`
 
+This runs the application (\`npm run dev\` under FeltDB's management), the development authority,
+and Studio. Running \`npm run dev\` yourself starts an unmanaged second copy.
+
 ### Build for Production
 \`\`\`bash
 npm run build

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.12.1';
+export const FELTDB_PACKAGE_VERSION = '0.12.2';
 export const feltdbPackageRange = `^${FELTDB_PACKAGE_VERSION}`;

package/dist/create/server-source/Cargo.lock

@@ -494,13 +494,14 @@ checksum = "da7c62ceae207dd37ea5b845da6a0696c799f85e97da1ab5b7910be3c1c80223"
 
 [[package]]
 name = "feltdb"
-version = "0.2.0"
+version = "0.2.1"
 dependencies = [
  "async-stream",
  "async-trait",
  "bincode",
  "criterion",
  "ed25519-dalek",
+ "feltdb",
  "rand 0.8.7",
  "serde",
  "serde_json",
@@ -510,15 +511,29 @@ dependencies = [
  "wasmi",
 ]
 
+[[package]]
+name = "feltdb-client"
+version = "0.2.1"
+dependencies = [
+ "feltdb",
+ "reqwest",
+ "serde",
+ "serde_json",
+ "tokio",
+ "tokio-rustls",
+ "uuid",
+]
+
 [[package]]
 name = "feltdb-server"
-version = "0.2.0"
+version = "0.2.1"
 dependencies = [
  "argon2",
  "async-stream",
  "axum",
  "base64",
  "feltdb",
+ "feltdb-client",
  "futures-core",
  "hmac",
  "password-hash",
@@ -537,7 +552,7 @@ dependencies = [
 
 [[package]]
 name = "feltdb-wasm"
-version = "0.2.0"
+version = "0.2.1"
 dependencies = [
  "feltdb",
  "getrandom 0.2.17",

package/dist/create/server-source/Cargo.toml

@@ -1,16 +1,18 @@
 [workspace]
-members = ["crates/feltdb", "crates/feltdb-server", "crates/feltdb-wasm"]
+members = ["crates/feltdb", "crates/feltdb-client", "crates/feltdb-server", "crates/feltdb-wasm"]
 # The deterministic contracts' WASM implementations are their own
 # dependency-free workspaces: they are only ever built for
 # wasm32-unknown-unknown, and a second implementation that inherited this
 # workspace's dependencies would stop being an independent one.
 exclude = [
+    "crates/feltdb-public-api-check",
     "crates/feltdb-trigger-contract-wasm",
     "crates/feltdb-state-diff-contract-wasm",
     "crates/feltdb-state-conflict-contract-wasm",
+    "crates/feltdb-agent-transition-contract-wasm",
 ]
 resolver = "2"
 
 [workspace.package]
-version = "0.2.0"
+version = "0.2.1"
 edition = "2021"

package/dist/create/server-source/crates/feltdb/Cargo.toml

@@ -2,6 +2,23 @@
 name = "feltdb"
 version.workspace = true
 edition.workspace = true
+# The oldest toolchain CI builds and tests this workspace with (.github/workflows/ci.yml).
+rust-version = "1.96"
+description = "Embedded durable state store: an append-only log with atomic multi-record transactions, version-conditional writes, and idempotent retries"
+license = "MIT"
+repository = "https://github.com/rkendel1/flow_db"
+readme = "README.md"
+keywords = ["database", "embedded", "transactions", "durable", "idempotency"]
+categories = ["database-implementations", "data-structures"]
+# The integration tests and benches read repository files by path (docs, sibling crates) and
+# cannot run from a packaged copy, so they stay in the repository.
+exclude = ["tests/", "benches/", "target/"]
+
+[features]
+default = []
+# Implementation, fault-injection and diagnostic modules. Not part of the supported API: no
+# compatibility promise covers anything this exposes. The workspace's own crates enable it.
+unstable-internals = []
 
 [dependencies]
 serde = { version = "1", features = ["derive"] }
@@ -18,6 +35,9 @@ bincode = "1"
 tokio = { version = "1", features = ["net", "io-util", "rt-multi-thread"] }
 
 [dev-dependencies]
+# The integration tests and benches exercise internals, so they build the crate with them. Packages
+# that want only the supported API depend on `feltdb` without the feature.
+feltdb = { path = ".", features = ["unstable-internals"] }
 criterion = { version = "0.5", features = ["html_reports"] }
 sha2 = "0.10"
 tempfile = "3"

package/dist/create/server-source/crates/feltdb/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FeltDB Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/create/server-source/crates/feltdb/README.md

@@ -0,0 +1,75 @@
+# feltdb
+
+An embedded, durable state store for Rust. Records live in an append-only log on local disk. Several
+records can change in one atomic transaction, a write can be conditional on the version you read, and a
+transaction can carry an identity so that a retry after an uncertain outcome is recognized instead of
+applied twice.
+
+```toml
+[dependencies]
+feltdb = "0.2"
+serde_json = "1"
+```
+
+```rust
+use feltdb::{FeltDb, FlowError};
+use serde_json::json;
+
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let db = FeltDb::open("app.db")?;
+
+    // Create only if absent. A second create is refused in a way you can branch on.
+    db.insert_if_absent("orders:o-1", json!({ "status": "pending" }))?;
+    assert!(matches!(
+        db.insert_if_absent("orders:o-1", json!({})),
+        Err(FlowError::PreconditionFailed(_))
+    ));
+    Ok(())
+}
+```
+
+The crate documentation on docs.rs has a longer, tested example covering atomic transactions and safe
+retries.
+
+## What you can rely on
+
+- Acknowledged writes and committed transaction ids survive closing and reopening the database, and a
+  process kill.
+- An interrupted, unacknowledged append is discarded on open and reported; its retry is treated as a
+  first use.
+- A transaction id names one payload. Reusing an id with a different payload hash fails with
+  `FlowError::TransactionIdPayloadMismatch` and writes nothing.
+
+## What is not promised
+
+- **Power-loss durability is unproven.** A flush hands bytes to the operating system; it does not force
+  them to stable storage. What survives a power cut depends on the filesystem, mount options and the
+  drive. See the repository's
+  [crash durability](https://github.com/rkendel1/flow_db/blob/main/docs/architecture/crash-durability.md)
+  note.
+- **Only the supported API is covered by semver.** While the version is `0.x`, a breaking change to a
+  supported item is a minor-version bump. Everything behind the `unstable-internals` feature (fault
+  injection, diagnostics, implementation modules) carries no promise at all; do not enable it in
+  application code. The supported surface is listed in
+  [the Rust API contract](https://github.com/rkendel1/flow_db/blob/main/docs/reference/feltdb-rust-api.md).
+- Plain `insert`, `update` and `delete` are unconditional: `insert` replaces, `update` of a missing key
+  creates it, `delete` of a missing key succeeds. Use `insert_if_absent` or `compare_and_set_json` when
+  you need a guard.
+
+## Targets
+
+Built and tested on native targets. `wasm32-wasip1` compiles. `wasm32-unknown-unknown` compiles only if
+your crate enables `getrandom`'s `js` feature.
+
+## Binaries
+
+The package also builds `feltdb-authority`, `feltdb-authority-client` and `feltdb_node`, the process
+authority and its client. `cargo install feltdb` installs them. Most applications want only the library.
+
+## Minimum Rust version
+
+1.96, the oldest toolchain the project's CI builds and tests with.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

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

@@ -0,0 +1,320 @@
+//! Durable agent state: the production implementation of
+//! [`crate::agent_transition_contract`].
+//!
+//! This module contains **no lifecycle logic**. Every rule about who may do
+//! what, when, and on what evidence lives in the contract; this module only
+//! performs the five steps the contract's documentation requires of a caller:
+//!
+//! ```text
+//!   1. read the records the operation names, with their versions
+//!   2. take the authority's time
+//!   3. ask the contract to decide
+//!   4. commit its writes and guards in one guarded transaction
+//!   5. report success only if that commit succeeded
+//! ```
+//!
+//! Step 4 is what makes step 3 true. A decision was valid for the records read
+//! in step 1; the commit carries a precondition for each of them, so if any
+//! record changed in between, nothing is written. Lease expiry is judged twice,
+//! both times on the authority's clock: by the contract at decision time, and by
+//! the transaction (`expected_lease_id`) at commit time.
+//!
+//! # Retries
+//!
+//! A lost race is [`AgentStateError::Conflict`], reported, never retried here.
+//! A caller that wants to try again calls [`AgentState::apply`] again, which
+//! re-reads current state and asks the contract again. The same writes are
+//! never resent.
+
+use crate::agent_transition_contract::{
+    evaluate, AgentTransitionInput, Decision, ErrorCode, Expect, Guard, Observation, Operation,
+    Records, Stored, Write, AGENT_TRANSITION_CONTRACT_ID, AGENT_TRANSITION_CONTRACT_VERSION,
+    HANDOFF_COLLECTION, INTENT_COLLECTION, TASK_COLLECTION,
+};
+use crate::{AtomicMutation, FeltDb, FlowError, PreconditionFailure, RecordPrecondition};
+use serde_json::Value;
+use std::sync::Arc;
+
+/// The time source decisions are made against.
+///
+/// Production uses [`FeltDb::authority_time_ms`]. A test may inject its own to
+/// drive the contract through a lifecycle without sleeping. The commit-time
+/// lease predicate always uses the authority's real clock.
+pub trait AuthorityClock: Send + Sync {
+    fn now_ms(&self) -> u64;
+}
+
+struct DatabaseClock(FeltDb);
+
+impl AuthorityClock for DatabaseClock {
+    fn now_ms(&self) -> u64 {
+        self.0.authority_time_ms()
+    }
+}
+
+#[derive(Debug)]
+pub enum AgentStateError {
+    /// The contract refused the operation. Nothing was written.
+    Refused(ErrorCode),
+    /// The decision was valid when made, but a record it depended on changed
+    /// before the commit. Nothing was written. Re-read and decide again.
+    Conflict(PreconditionFailure),
+    /// The store failed. Whether anything was written is the store's report.
+    Storage(FlowError),
+}
+
+impl std::fmt::Display for AgentStateError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Self::Refused(code) => write!(f, "{}", code.as_str()),
+            Self::Conflict(failure) => write!(f, "CONFLICT: {failure}"),
+            Self::Storage(error) => write!(f, "STORAGE: {error}"),
+        }
+    }
+}
+
+impl std::error::Error for AgentStateError {}
+
+/// A record the commit wrote, with the version it now has.
+#[derive(Debug, Clone, PartialEq)]
+pub struct Written {
+    pub collection: String,
+    pub id: String,
+    pub version: u64,
+}
+
+#[derive(Debug, Clone, PartialEq)]
+pub enum Applied {
+    Committed(Vec<Written>),
+    /// A recognized repeat: nothing changed, and nothing needed to.
+    Noop,
+}
+
+/// A decision, with nothing yet committed.
+#[derive(Debug, Clone)]
+pub struct Prepared {
+    decision: Decision,
+}
+
+impl Prepared {
+    pub fn decision(&self) -> &Decision {
+        &self.decision
+    }
+}
+
+#[derive(Clone)]
+pub struct AgentState {
+    db: FeltDb,
+    clock: Arc<dyn AuthorityClock>,
+}
+
+fn key(collection: &str, id: &str) -> String {
+    format!("{collection}:{id}")
+}
+
+impl AgentState {
+    pub fn new(db: FeltDb) -> Self {
+        let clock = Arc::new(DatabaseClock(db.clone()));
+        Self { db, clock }
+    }
+
+    pub fn with_clock(db: FeltDb, clock: Arc<dyn AuthorityClock>) -> Self {
+        Self { db, clock }
+    }
+
+    /// One record and its authority version, or `None`.
+    ///
+    /// The version is the document's `__version`, defaulting to 1 where the
+    /// record was never written under a version precondition: the same reading
+    /// the transaction's precondition makes.
+    pub fn read(
+        &self,
+        collection: &str,
+        id: &str,
+    ) -> Result<Option<(u64, Value)>, AgentStateError> {
+        let Some(mut value) = self
+            .db
+            .get_value(&key(collection, id))
+            .map_err(AgentStateError::Storage)?
+        else {
+            return Ok(None);
+        };
+        let version = value.get("__version").and_then(Value::as_u64).unwrap_or(1);
+        if let Some(object) = value.as_object_mut() {
+            object.remove("__version");
+        }
+        Ok(Some((version, value)))
+    }
+
+    fn stored<T: serde::de::DeserializeOwned>(
+        &self,
+        collection: &str,
+        id: &str,
+    ) -> Result<Option<Stored<T>>, AgentStateError> {
+        match self.read(collection, id)? {
+            None => Ok(None),
+            Some((version, value)) => match serde_json::from_value(value) {
+                Ok(value) => Ok(Some(Stored { value, version })),
+                // Stored state that does not parse is not decided around.
+                Err(_) => Err(AgentStateError::Refused(ErrorCode::ContractInputInvalid)),
+            },
+        }
+    }
+
+    /// Step 1: read exactly the records the operation names.
+    fn gather(&self, op: &Operation) -> Result<Records, AgentStateError> {
+        let mut records = Records::default();
+        if let Some(handoff_id) = &op.handoff_id {
+            records.handoff = self.stored(HANDOFF_COLLECTION, handoff_id)?;
+        }
+        let task_id = op
+            .task_id
+            .clone()
+            .or_else(|| records.handoff.as_ref().map(|h| h.value.task_id.clone()));
+        if let Some(task_id) = &task_id {
+            records.task = self.stored(TASK_COLLECTION, task_id)?;
+            if let Some(key_) = &op.idempotency_key {
+                records.intent = self.stored(INTENT_COLLECTION, &format!("{task_id}~{key_}"))?;
+            }
+        }
+        if matches!(
+            op.op.as_str(),
+            "checkpoint" | "record_outcome" | "reconcile"
+        ) {
+            let mut seen = Vec::new();
+            for reference in op.evidence.iter().flatten().filter(|r| r.kind == "record") {
+                let (collection, id) = (
+                    reference.collection.clone().unwrap_or_default(),
+                    reference.id.clone().unwrap_or_default(),
+                );
+                if let Some((version, _)) = self.read(&collection, &id)? {
+                    // A record cited twice is observed once; the contract refuses
+                    // the duplicate citation.
+                    if !seen
+                        .iter()
+                        .any(|o: &Observation| o.collection == collection && o.id == id)
+                    {
+                        seen.push(Observation {
+                            collection,
+                            id,
+                            version,
+                        });
+                    }
+                }
+            }
+            records.evidence = Some(seen);
+        }
+        Ok(records)
+    }
+
+    /// Steps 1 to 3. Reads, takes the authority's time and decides. Writes
+    /// nothing.
+    pub fn prepare(&self, operation: &Operation) -> Result<Prepared, AgentStateError> {
+        let records = self.gather(operation)?;
+        let input = AgentTransitionInput {
+            contract: AGENT_TRANSITION_CONTRACT_ID.to_string(),
+            now_ms: self.clock.now_ms(),
+            operation: operation.clone(),
+            records,
+            version: AGENT_TRANSITION_CONTRACT_VERSION,
+        };
+        evaluate(&input)
+            .map(|decision| Prepared { decision })
+            .map_err(AgentStateError::Refused)
+    }
+
+    /// Steps 4 and 5: one guarded transaction carrying every write and guard
+    /// the contract returned, each with the precondition it attached.
+    ///
+    /// Nothing is retried. A fresh transaction id is used per call, so a failed
+    /// precondition never consumes an id and a repeated call is a new decision's
+    /// commit, not a replay.
+    pub fn commit(&self, prepared: &Prepared) -> Result<Applied, AgentStateError> {
+        let (writes, guards) = match &prepared.decision {
+            Decision::Noop => return Ok(Applied::Noop),
+            Decision::Commit { writes, guards } => (writes, guards),
+        };
+        let mut preconditions: Vec<RecordPrecondition> = Vec::new();
+        let mut mutations: Vec<AtomicMutation> = Vec::new();
+        for Write {
+            collection,
+            id,
+            expect,
+            value,
+        } in writes
+        {
+            preconditions.push(precondition(collection, id, expect));
+            mutations.push(AtomicMutation {
+                capability: (*collection).to_string(),
+                key: key(collection, id),
+                value: Some(value.clone()),
+            });
+        }
+        for Guard {
+            collection,
+            id,
+            version,
+            lease_id,
+        } in guards
+        {
+            preconditions.push(precondition(
+                collection,
+                id,
+                &Expect::Version {
+                    version: *version,
+                    lease_id: lease_id.clone(),
+                },
+            ));
+        }
+        let transaction_id = format!("agent-state-{:032x}", rand::random::<u128>());
+        match self.db.apply_atomic_transaction_guarded(
+            &transaction_id,
+            None,
+            None,
+            &[],
+            &preconditions,
+            &mutations,
+            None,
+        ) {
+            Ok(_) => Ok(Applied::Committed(
+                writes
+                    .iter()
+                    .map(|w| Written {
+                        collection: w.collection.to_string(),
+                        id: w.id.clone(),
+                        version: match &w.expect {
+                            Expect::Absent => 1,
+                            Expect::Version { version, .. } => version + 1,
+                        },
+                    })
+                    .collect(),
+            )),
+            Err(FlowError::PreconditionFailed(failure)) => Err(AgentStateError::Conflict(*failure)),
+            Err(other) => Err(AgentStateError::Storage(other)),
+        }
+    }
+
+    /// Decide and commit.
+    pub fn apply(&self, operation: &Operation) -> Result<Applied, AgentStateError> {
+        self.commit(&self.prepare(operation)?)
+    }
+}
+
+fn precondition(collection: &str, id: &str, expect: &Expect) -> RecordPrecondition {
+    let base = RecordPrecondition {
+        capability: collection.to_string(),
+        key: key(collection, id),
+        ..Default::default()
+    };
+    match expect {
+        Expect::Absent => RecordPrecondition {
+            require_absent: true,
+            ..base
+        },
+        Expect::Version { version, lease_id } => RecordPrecondition {
+            expected_version: Some(*version),
+            expected_lease_id: lease_id.clone(),
+            ..base
+        },
+    }
+}