@feltdb/core 0.4.11 → 0.4.13

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

@@ -0,0 +1,23 @@
+[package]
+name = "feltdb-server"
+version.workspace = true
+edition.workspace = true
+
+[dependencies]
+axum = { version = "0.8", features = ["json", "tokio"] }
+async-stream = "0.3"
+argon2 = "0.5"
+password-hash = "0.5"
+base64 = "0.22"
+feltdb = { path = "../feltdb" }
+futures-core = "0.3"
+rand = "0.8"
+ring = "0.17"
+reqwest = { version = "0.12", default-features = false, features = ["blocking", "json", "rustls-tls"] }
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+sha2 = "0.10"
+tokio = { version = "1", features = ["macros", "net", "rt-multi-thread", "signal", "time"] }
+tower-http = { version = "0.6", features = ["cors", "limit", "trace"] }
+tracing = "0.1"
+tracing-subscriber = { version = "0.3", features = ["env-filter"] }

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

@@ -0,0 +1,79 @@
+# FeltDB Server
+
+This crate is the first network adapter over the canonical `feltdb` runtime. It does not own a
+second state store: every HTTP mutation calls `FeltDb::insert`, `FeltDb::update`, or
+`FeltDb::delete`, producing the same operations, vector-clock updates, durable log entries, and
+reactive events as an embedded mutation.
+
+Run it with:
+
+```sh
+cargo run -p feltdb-server -- \
+  --host 127.0.0.1 \
+  --port 7700 \
+  --namespace my-app \
+  --data ./data/feltdb.log
+```
+
+For a customer-facing process, create a namespace-bound key and enable authentication:
+
+```sh
+cargo run -p feltdb-server -- keys create \
+  --keys ./data/api-keys.json \
+  --name application \
+  --namespace my-app \
+  --scope state:read,state:write,events:read
+
+cargo run -p feltdb-server -- \
+  --namespace my-app \
+  --data ./data/feltdb.log \
+  --keys ./data/api-keys.json \
+  --auth
+```
+
+The secret is printed once; only its Argon2 hash is stored. Send it as
+`Authorization: Bearer <key>`. Use `keys list` to inspect safe key metadata and
+`keys revoke --id <id>` to revoke a key. Restart a running server after changing its key file.
+
+Implemented in this slice:
+
+- `GET /health`
+- `GET /runtime`
+- collection list/create/get/update/delete endpoints
+- `GET /events` as a server-sent event stream
+- durable, hashed API keys with namespace and `state:read`, `state:write`, or `events:read` scopes
+- `GET /metrics` request, authorization, state, and event counters
+- authenticated `POST /sync/pull` and `POST /sync/push` operation exchange
+- durable, transitive operation history with content-hash verification, deduplication, and gap rejection
+
+Peer credentials should be separate from application credentials and use the `sync:read` and
+`sync:write` scopes. Pull requests contain the caller's per-origin `versions` map. Push requests
+contain the target `namespace` and operations returned by pull. This version-vector exchange
+preserves original operation identity through relays instead of translating replicated writes into
+new local mutations.
+
+To maintain a continuous bidirectional session, configure one or more peers and provide the peer
+key through an environment variable (never a command-line argument):
+
+```sh
+export FELTDB_PEER_TOKEN='fdb_live_...'
+feltdb-server --namespace my-app --peer https://peer-a.example --peer https://peer-b.example
+```
+
+Each session pulls and pushes missing operations, advertises the successfully contacted peer to the
+runtime registry, and retries failures with exponential backoff capped at 30 seconds. The polling
+interval defaults to two seconds and can be changed with `--sync-interval-ms`.
+
+Successful pushes durably persist the remote peer's per-origin acknowledgement vector. Once every
+configured peer acknowledges an operation, compaction atomically replaces that history with a
+content-hashed state snapshot. A pristine peer bootstraps from `GET /sync/snapshot`, installs the
+snapshot's state and causal high-water marks, then resumes ordinary operation exchange without
+replaying pruned history or encountering sequence gaps. Nodes with independent local history are
+never overwritten by snapshot bootstrap.
+- `FeltDB-Protocol` compatibility rejection
+- 1 MiB request limit, identifier validation, graceful shutdown, and structured HTTP tracing
+- durable deletion tombstones that survive process restart
+
+The runtime discovery response explicitly marks acquisition, remote capabilities, workflows,
+agents, and provenance as unavailable until those systems are connected to this same operation
+boundary. The server must never advertise simulated functionality as healthy.

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

@@ -0,0 +1,73 @@
+use std::sync::{atomic::AtomicU64, Arc};
+use std::path::PathBuf;
+
+use feltdb::{
+    FeltDb,
+    application::ApplicationStore,
+    authorization::{GrantSigner, GrantStore},
+    sync_contract::SyncStore,
+    workload::WorkloadStore,
+    worker_mesh::WorkerMeshStore,
+    application_runtime::RuntimeStore,
+};
+use crate::{
+    artifacts::ArtifactStore,
+    audit::AuditLog,
+    auth::KeyStore,
+    causal::CausalStore,
+    cluster::ClusterStore,
+    connections::ConnectionStore,
+    content::ContentStore,
+    identity::IdentityStore,
+    leases::LeaseStore,
+    metrics::Metrics,
+    portable_bundle::BundleStore,
+    principals::PrincipalStore,
+    providers::ProviderStore,
+    releases::ReleaseStore,
+    sessions::SessionVerifier,
+    tenancy::TenancyStore,
+    application_contract::ApplicationContractStore,
+    clock::LeaseClock,
+};
+
+#[derive(Clone)]
+pub struct AppState {
+    pub db: FeltDb,
+    pub namespace: Arc<str>,
+    pub ids: Arc<AtomicU64>,
+    pub auth_enabled: bool,
+    pub keys: KeyStore,
+    pub metrics: Metrics,
+    pub cluster: ClusterStore,
+    pub audit: AuditLog,
+    pub peer_client: reqwest::Client,
+    pub peer_token: Option<Arc<str>>,
+    pub lifecycle_lock: Arc<tokio::sync::Mutex<()>>,
+    pub worker_enabled: bool,
+    pub leases: LeaseStore,
+    pub content: ContentStore,
+    pub artifacts: ArtifactStore,
+    pub bundles: BundleStore,
+    pub releases: ReleaseStore,
+    pub causal: CausalStore,
+    pub providers: ProviderStore,
+    pub contracts: ApplicationContractStore,
+    pub advertise_url: Option<Arc<str>>,
+    pub lease_clock: LeaseClock,
+    pub backup_barrier: Arc<tokio::sync::RwLock<()>>,
+    pub backup_artifacts: Arc<Vec<(String, PathBuf)>>,
+    pub tenancy: TenancyStore,
+    pub sessions: SessionVerifier,
+    pub principals: PrincipalStore,
+    pub connections: ConnectionStore,
+    pub identities: IdentityStore,
+    pub applications: ApplicationStore,
+    pub runtimes: RuntimeStore,
+    pub grant_signer: GrantSigner,
+    pub grants: Arc<std::sync::Mutex<GrantStore>>,
+    pub sync: Arc<std::sync::Mutex<SyncStore>>,
+    pub workloads: Arc<std::sync::Mutex<WorkloadStore>>,
+    pub mesh: Arc<std::sync::Mutex<WorkerMeshStore>>,
+    pub readiness_probe: Arc<PathBuf>,
+}

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

@@ -0,0 +1,425 @@
+use rand::{distributions::Alphanumeric, Rng};
+use serde::{Deserialize, Serialize};
+use serde_json::Value;
+use std::{
+    collections::BTreeMap,
+    fs,
+    path::PathBuf,
+    sync::{Arc, RwLock},
+    time::{SystemTime, UNIX_EPOCH},
+};
+fn now() -> u64 {
+    SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .unwrap_or_default()
+        .as_secs()
+}
+fn id(p: &str) -> String {
+    format!(
+        "{p}_{}",
+        rand::thread_rng()
+            .sample_iter(&Alphanumeric)
+            .take(18)
+            .map(char::from)
+            .collect::<String>()
+    )
+}
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "SCREAMING_SNAKE_CASE")]
+pub enum EvidenceSourceType {
+    User,
+    ApplicationState,
+    ExistingSchema,
+    Connection,
+    Artifact,
+    Document,
+    Provider,
+    Agent,
+    Workload,
+    AiInference,
+    SystemRule,
+    ImportedData,
+}
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ContractEvidence {
+    pub evidence_id: String,
+    pub source: String,
+    pub source_type: EvidenceSourceType,
+    pub statement: String,
+    pub contract_paths: Vec<String>,
+    pub confidence: f32,
+    pub authority: String,
+    pub provenance: Value,
+    pub timestamp: u64,
+    pub supporting_refs: Vec<String>,
+    pub contradicting_refs: Vec<String>,
+}
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "SCREAMING_SNAKE_CASE")]
+pub enum GapType {
+    Missing,
+    Ambiguous,
+    Contradictory,
+    Unauthorized,
+    Unsupported,
+    Unvalidated,
+    DependencyMissing,
+    ProviderMissing,
+}
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ContractGap {
+    pub contract_path: String,
+    pub gap_type: GapType,
+    pub severity: String,
+    pub blocking: bool,
+    pub confidence: f32,
+    pub evidence_required: Vec<String>,
+    pub suggested_questions: Vec<String>,
+    pub candidate_resolutions: Vec<Value>,
+    pub affected_paths: Vec<String>,
+}
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ContractAssertion {
+    pub value: Value,
+    pub confidence: f32,
+    pub evidence_refs: Vec<String>,
+    pub required: bool,
+    pub validated: bool,
+}
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ApplicationContract {
+    pub contract_id: String,
+    pub application_id: String,
+    pub base_revision: Option<String>,
+    pub contract_revision: u64,
+    pub status: String,
+    pub assertions: BTreeMap<String, ContractAssertion>,
+    pub evidence: Vec<ContractEvidence>,
+    pub gaps: Vec<ContractGap>,
+    pub created_at: u64,
+    pub updated_at: u64,
+}
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ContractChange {
+    pub path: String,
+    pub value: Value,
+    pub confidence: f32,
+    pub required: bool,
+}
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ContractPatch {
+    pub patch_id: Option<String>,
+    pub base_revision: u64,
+    pub changes: Vec<ContractChange>,
+    pub evidence: Vec<ContractEvidence>,
+    pub affected_paths: Vec<String>,
+    pub confidence_delta: f32,
+    pub risks: Vec<String>,
+    pub provenance: Value,
+}
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ContractReadiness {
+    pub status: String,
+    pub readiness: f32,
+    pub blocking_gaps: usize,
+    pub gaps: Vec<ContractGap>,
+    pub confidence: BTreeMap<String, f32>,
+    pub next_action: String,
+}
+#[derive(Default, Serialize, Deserialize)]
+struct Records {
+    contracts: BTreeMap<String, ApplicationContract>,
+}
+#[derive(Clone)]
+pub struct ApplicationContractStore {
+    path: PathBuf,
+    records: Arc<RwLock<Records>>,
+}
+impl ApplicationContractStore {
+    pub fn load(path: impl Into<PathBuf>) -> Result<Self, String> {
+        let path = path.into();
+        let records = if path.exists() {
+            serde_json::from_slice(&fs::read(&path).map_err(|e| e.to_string())?)
+                .map_err(|e| e.to_string())?
+        } else {
+            Records::default()
+        };
+        Ok(Self {
+            path,
+            records: Arc::new(RwLock::new(records)),
+        })
+    }
+    fn persist(&self, r: &Records) -> Result<(), String> {
+        if let Some(p) = self.path.parent() {
+            fs::create_dir_all(p).map_err(|e| e.to_string())?
+        }
+        fs::write(
+            &self.path,
+            serde_json::to_vec_pretty(r).map_err(|e| e.to_string())?,
+        )
+        .map_err(|e| e.to_string())
+    }
+    pub fn get(&self, a: &str) -> Result<ApplicationContract, String> {
+        self.records
+            .read()
+            .map_err(|_| "contract lock poisoned")?
+            .contracts
+            .get(a)
+            .cloned()
+            .ok_or("contract not found".into())
+    }
+    pub fn evaluate(
+        &self,
+        a: &str,
+        outcome: &str,
+        actor: &str,
+    ) -> Result<ApplicationContract, String> {
+        let mut r = self.records.write().map_err(|_| "contract lock poisoned")?;
+        let t = now();
+        let e = ContractEvidence {
+            evidence_id: id("evidence"),
+            source: actor.into(),
+            source_type: EvidenceSourceType::User,
+            statement: outcome.into(),
+            contract_paths: vec!["outcome".into()],
+            confidence: 0.99,
+            authority: "subject".into(),
+            provenance: serde_json::json!({"actor":actor}),
+            timestamp: t,
+            supporting_refs: vec![],
+            contradicting_refs: vec![],
+        };
+        let mut assertions = BTreeMap::new();
+        assertions.insert(
+            "outcome".into(),
+            ContractAssertion {
+                value: Value::String(outcome.into()),
+                confidence: 0.99,
+                evidence_refs: vec![e.evidence_id.clone()],
+                required: true,
+                validated: true,
+            },
+        );
+        let mut c = ApplicationContract {
+            contract_id: id("contract"),
+            application_id: a.into(),
+            base_revision: None,
+            contract_revision: 1,
+            status: "INCOMPLETE".into(),
+            assertions,
+            evidence: vec![e],
+            gaps: vec![],
+            created_at: t,
+            updated_at: t,
+        };
+        Self::recompute(&mut c);
+        r.contracts.insert(a.into(), c.clone());
+        self.persist(&r)?;
+        Ok(c)
+    }
+    pub fn apply_patch(&self, a: &str, p: ContractPatch) -> Result<ApplicationContract, String> {
+        let mut r = self.records.write().map_err(|_| "contract lock poisoned")?;
+        let c = r.contracts.get_mut(a).ok_or("contract not found")?;
+        if p.base_revision != c.contract_revision {
+            return Err("stale contract patch".into());
+        }
+        if p.risks.iter().any(|x| x == "destructive")
+            && !p
+                .provenance
+                .get("approved")
+                .and_then(Value::as_bool)
+                .unwrap_or(false)
+        {
+            return Err("destructive patch requires explicit approval".into());
+        }
+        for x in p.changes {
+            if x.path.trim().is_empty() || !(0.0..=1.0).contains(&x.confidence) {
+                return Err("invalid contract change".into());
+            }
+            if let Some(old) = c.assertions.get(&x.path) {
+                if old.value != x.value && old.confidence > 0.8 && x.confidence > 0.8 {
+                    c.gaps.push(ContractGap {
+                        contract_path: x.path.clone(),
+                        gap_type: GapType::Contradictory,
+                        severity: "high".into(),
+                        blocking: true,
+                        confidence: x.confidence,
+                        evidence_required: vec!["user resolution".into()],
+                        suggested_questions: vec![format!("Which value should {} use?", x.path)],
+                        candidate_resolutions: vec![old.value.clone(), x.value.clone()],
+                        affected_paths: vec![x.path.clone()],
+                    });
+                    continue;
+                }
+            }
+            c.assertions.insert(
+                x.path,
+                ContractAssertion {
+                    value: x.value,
+                    confidence: x.confidence,
+                    evidence_refs: p.evidence.iter().map(|e| e.evidence_id.clone()).collect(),
+                    required: x.required,
+                    validated: true,
+                },
+            );
+        }
+        c.evidence.extend(p.evidence);
+        c.contract_revision += 1;
+        c.updated_at = now();
+        Self::recompute(c);
+        let out = c.clone();
+        self.persist(&r)?;
+        Ok(out)
+    }
+    fn recompute(c: &mut ApplicationContract) {
+        c.gaps.retain(|g| g.gap_type == GapType::Contradictory);
+        for p in ["outcome", "actors", "entities", "actions", "permissions"] {
+            if !c.assertions.contains_key(p) {
+                c.gaps.push(ContractGap {
+                    contract_path: p.into(),
+                    gap_type: GapType::Missing,
+                    severity: "high".into(),
+                    blocking: true,
+                    confidence: 0.0,
+                    evidence_required: vec!["contract evidence".into()],
+                    suggested_questions: vec![match p {
+                        "actors" => "Who will use this application, and what roles do they have?".into(),
+                        "entities" => "What information or records should the application keep track of?".into(),
+                        "actions" => "What should people be able to do with those records?".into(),
+                        "permissions" => "Who can view, create, edit, delete, or administer this information?".into(),
+                        _ => format!("What should FeltDB understand about {p}?"),
+                    }],
+                    candidate_resolutions: vec![],
+                    affected_paths: vec![p.into()],
+                })
+            }
+        }
+        c.status = Self::readiness_for(c).status
+    }
+    pub fn readiness(&self, a: &str) -> Result<ContractReadiness, String> {
+        Ok(Self::readiness_for(&self.get(a)?))
+    }
+    pub fn next_question(&self, a: &str) -> Result<Option<ContractGap>, String> {
+        let contract = self.get(a)?;
+        Ok(contract
+            .gaps
+            .into_iter()
+            .filter(|gap| gap.blocking)
+            .min_by(|left, right| {
+                left.confidence
+                    .partial_cmp(&right.confidence)
+                    .unwrap_or(std::cmp::Ordering::Equal)
+            }))
+    }
+    pub fn end_session(&self, a: &str, actor: &str) -> Result<ApplicationContract, String> {
+        let mut records = self.records.write().map_err(|_| "contract lock poisoned")?;
+        let contract = records.contracts.get_mut(a).ok_or("contract not found")?;
+        contract.status = "MANUALLY_ENDED".into();
+        contract.updated_at = now();
+        contract.evidence.push(ContractEvidence {
+            evidence_id: id("evidence"),
+            source: actor.into(),
+            source_type: EvidenceSourceType::User,
+            statement: "User ended contract completion; compose only evidenced assertions".into(),
+            contract_paths: vec![],
+            confidence: 1.0,
+            authority: "subject".into(),
+            provenance: serde_json::json!({"escape_hatch":true}),
+            timestamp: now(),
+            supporting_refs: vec![],
+            contradicting_refs: vec![],
+        });
+        let result = contract.clone();
+        self.persist(&records)?;
+        Ok(result)
+    }
+    pub fn construction_input(&self, a: &str) -> Result<BTreeMap<String, Value>, String> {
+        let contract = self.get(a)?;
+        if contract.status != "READY" && contract.status != "MANUALLY_ENDED" {
+            return Err("contract completion is still active".into());
+        }
+        Ok(contract
+            .assertions
+            .into_iter()
+            .filter(|(_, assertion)| assertion.validated && !assertion.evidence_refs.is_empty())
+            .map(|(path, assertion)| (path, assertion.value))
+            .collect())
+    }
+    fn readiness_for(c: &ApplicationContract) -> ContractReadiness {
+        let confidence = c
+            .assertions
+            .iter()
+            .map(|(p, a)| (p.clone(), a.confidence))
+            .collect::<BTreeMap<_, _>>();
+        let readiness = if confidence.is_empty() {
+            0.0
+        } else {
+            confidence.values().sum::<f32>() / confidence.len() as f32
+        };
+        let blocking = c.gaps.iter().filter(|g| g.blocking).count();
+        ContractReadiness {
+            status: if blocking > 0 {
+                "INCOMPLETE"
+            } else if readiness >= 0.75 {
+                "READY"
+            } else {
+                "UNDERSTOOD"
+            }
+            .into(),
+            readiness,
+            blocking_gaps: blocking,
+            gaps: c.gaps.clone(),
+            confidence,
+            next_action: if blocking > 0 { "CLARIFY" } else { "COMPOSE" }.into(),
+        }
+    }
+}
+#[cfg(test)]
+mod tests {
+    use super::*;
+    #[test]
+    fn contradiction_blocks() {
+        let s = ApplicationContractStore::load(
+            std::env::temp_dir().join(format!("contract-{}.json", now())),
+        )
+        .unwrap();
+        s.evaluate("a", "Recruit", "u").unwrap();
+        let p = ContractPatch {
+            patch_id: None,
+            base_revision: 1,
+            changes: vec![ContractChange {
+                path: "outcome".into(),
+                value: Value::String("Sell".into()),
+                confidence: 0.95,
+                required: true,
+            }],
+            evidence: vec![],
+            affected_paths: vec![],
+            confidence_delta: 0.0,
+            risks: vec![],
+            provenance: serde_json::json!({}),
+        };
+        assert!(s
+            .apply_patch("a", p)
+            .unwrap()
+            .gaps
+            .iter()
+            .any(|g| g.gap_type == GapType::Contradictory));
+    }
+    #[test]
+    fn manual_end_constructs_only_evidenced_assertions() {
+        let store = ApplicationContractStore::load(
+            std::env::temp_dir().join(format!("contract-end-{}.json", now())),
+        )
+        .unwrap();
+        store
+            .evaluate("app", "Track approved work", "user")
+            .unwrap();
+        assert!(store.construction_input("app").is_err());
+        store.end_session("app", "user").unwrap();
+        let input = store.construction_input("app").unwrap();
+        assert_eq!(input.len(), 1);
+        assert!(input.contains_key("outcome"));
+        assert!(!input.contains_key("entities"));
+    }
+}