@feltdb/core 0.4.12 → 0.4.14

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

@@ -0,0 +1,264 @@
+use serde::{Deserialize, Serialize};
+use std::fmt;
+
+/// Explicit versioning for all durable formats in FeltDB.
+/// Every component that stores durable state must declare its format version.
+/// Migrations between versions are restartable and preserve causal identity.
+
+/// Current versions for all durable formats
+pub struct FormatVersions {
+    /// State log format: entries, operation encoding, checkpoints
+    pub state_log: u32,
+    /// Checkpoint format: snapshot encoding, metadata
+    pub checkpoint: u32,
+    /// Protocol version: API, peer communication, data encoding
+    pub protocol: u32,
+    /// Membership proposal format
+    pub membership: u32,
+    /// Lease store format
+    pub leases: u32,
+    /// Content store format
+    pub content: u32,
+    /// Backup bundle format
+    pub backup: u32,
+}
+
+impl FormatVersions {
+    /// Current stable format versions
+    pub fn current() -> Self {
+        Self {
+            state_log: 1,
+            checkpoint: 1,
+            protocol: 1,
+            membership: 1,
+            leases: 1,
+            content: 1,
+            backup: 1,
+        }
+    }
+
+    /// Minimum supported versions (defines downgrade compatibility)
+    pub fn minimum_supported() -> Self {
+        Self {
+            state_log: 1,
+            checkpoint: 1,
+            protocol: 1,
+            membership: 1,
+            leases: 1,
+            content: 1,
+            backup: 1,
+        }
+    }
+
+    /// Check if a version is supported
+    pub fn is_supported(&self, current: &FormatVersions) -> bool {
+        let minimum = Self::minimum_supported();
+        self.state_log >= minimum.state_log
+            && self.state_log <= current.state_log
+            && self.checkpoint >= minimum.checkpoint
+            && self.checkpoint <= current.checkpoint
+            && self.protocol >= minimum.protocol
+            && self.protocol <= current.protocol
+            && self.membership >= minimum.membership
+            && self.membership <= current.membership
+            && self.leases >= minimum.leases
+            && self.leases <= current.leases
+            && self.content >= minimum.content
+            && self.content <= current.content
+            && self.backup >= minimum.backup
+            && self.backup <= current.backup
+    }
+}
+
+/// Format version descriptor written to durable files
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct VersionManifest {
+    /// Timestamp when this version was written
+    pub written_at_ms: u64,
+    /// State log format version
+    pub state_log_version: u32,
+    /// Checkpoint format version
+    pub checkpoint_version: u32,
+    /// Protocol version
+    pub protocol_version: u32,
+    /// Membership format version
+    pub membership_version: u32,
+    /// Lease format version
+    pub lease_version: u32,
+    /// Content format version
+    pub content_version: u32,
+}
+
+impl VersionManifest {
+    pub fn current() -> Self {
+        let versions = FormatVersions::current();
+        Self {
+            written_at_ms: std::time::SystemTime::now()
+                .duration_since(std::time::UNIX_EPOCH)
+                .unwrap_or_default()
+                .as_millis() as u64,
+            state_log_version: versions.state_log,
+            checkpoint_version: versions.checkpoint,
+            protocol_version: versions.protocol,
+            membership_version: versions.membership,
+            lease_version: versions.leases,
+            content_version: versions.content,
+        }
+    }
+
+    pub fn to_format_versions(&self) -> FormatVersions {
+        FormatVersions {
+            state_log: self.state_log_version,
+            checkpoint: self.checkpoint_version,
+            protocol: self.protocol_version,
+            membership: self.membership_version,
+            leases: self.lease_version,
+            content: self.content_version,
+            backup: 1, // Backup format is managed separately
+        }
+    }
+}
+
+/// Migration error
+#[derive(Clone, Debug)]
+pub struct MigrationError {
+    pub from_version: u32,
+    pub to_version: u32,
+    pub component: &'static str,
+    pub message: String,
+}
+
+impl fmt::Display for MigrationError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(
+            f,
+            "Migration failed for {}: {} -> {}: {}",
+            self.component, self.from_version, self.to_version, self.message
+        )
+    }
+}
+
+impl std::error::Error for MigrationError {}
+
+/// Migration trait for component-specific upgrade/downgrade logic
+pub trait Migration: Send + Sync {
+    /// Component name (e.g., "state_log", "checkpoint")
+    fn component(&self) -> &'static str;
+
+    /// Source version
+    fn from_version(&self) -> u32;
+
+    /// Target version
+    fn to_version(&self) -> u32;
+
+    /// Upgrade the data. Must be restartable.
+    fn migrate(&self, data: Vec<u8>) -> Result<Vec<u8>, MigrationError>;
+
+    /// Downgrade the data. Must be restartable.
+    fn downgrade(&self, data: Vec<u8>) -> Result<Vec<u8>, MigrationError>;
+}
+
+/// Migration registry
+pub struct MigrationRegistry {
+    upgrades: std::collections::HashMap<(u32, u32), Box<dyn Migration>>,
+    downgrades: std::collections::HashMap<(u32, u32), Box<dyn Migration>>,
+}
+
+impl MigrationRegistry {
+    pub fn new() -> Self {
+        Self {
+            upgrades: std::collections::HashMap::new(),
+            downgrades: std::collections::HashMap::new(),
+        }
+    }
+
+    pub fn register_upgrade(&mut self, migration: Box<dyn Migration>) {
+        self.upgrades.insert(
+            (migration.from_version(), migration.to_version()),
+            migration,
+        );
+    }
+
+    pub fn register_downgrade(&mut self, migration: Box<dyn Migration>) {
+        self.downgrades.insert(
+            (migration.from_version(), migration.to_version()),
+            migration,
+        );
+    }
+
+    pub fn get_upgrade(&self, from: u32, to: u32) -> Option<&Box<dyn Migration>> {
+        self.upgrades.get(&(from, to))
+    }
+
+    pub fn get_downgrade(&self, from: u32, to: u32) -> Option<&Box<dyn Migration>> {
+        self.downgrades.get(&(from, to))
+    }
+}
+
+impl Default for MigrationRegistry {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+/// Compatibility policy
+pub const COMPATIBILITY_POLICY: &str = r#"
+## Format Compatibility Policy
+
+FeltDB follows semantic versioning for format compatibility:
+
+- **Major version bump** (e.g., 1 → 2): Incompatible format change. Requires migration.
+- **Minor version increment within supported range**: Compatible enhancement. No migration required.
+
+### Support Matrix
+
+- **Current version**: all formats at v1
+- **Minimum supported version**: all formats at v1
+- **Rolling upgrade support**: N → N+1 (one version forward)
+- **Rollback support**: N+1 → N (one version backward, within minimum supported range)
+
+### Migration Guarantees
+
+Every migration must satisfy:
+1. **Atomicity**: Format change is atomic (all-or-nothing)
+2. **Restartability**: Migration can be safely interrupted and restarted
+3. **Causal identity**: Operations retain their causal identity and vector clocks
+4. **Content hashing**: SHA-256 hashes of data remain verifiable
+5. **Idempotency**: Running the same migration twice produces identical results
+
+### Unsupported Format Transitions
+
+- Versions below the minimum supported version are rejected before any mutation
+- Multi-step jumps (e.g., v1 → v3) are not supported; use sequential migrations
+- Concurrent format changes are serialized behind a lock
+- Partial/interrupted migrations are detected and rolled back
+
+### Publishing Policy
+
+Format version changes are announced in release notes with:
+- Source and target versions for each component
+- Migration time estimates for capacity envelopes
+- Rollback procedures and recovery guidance
+"#;
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_version_compatibility() {
+        let current = FormatVersions::current();
+        let manifest = VersionManifest::current();
+        let stored = manifest.to_format_versions();
+
+        assert!(stored.is_supported(&current));
+    }
+
+    #[test]
+    fn test_minimum_supported() {
+        let current = FormatVersions::current();
+        let minimum = FormatVersions::minimum_supported();
+
+        assert!(minimum.is_supported(&current));
+    }
+}

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

@@ -0,0 +1,31 @@
+[package]
+name = "feltdb-wasm"
+version.workspace = true
+edition.workspace = true
+
+[lib]
+crate-type = ["cdylib"]
+
+[dependencies]
+feltdb = { path = "../feltdb" }
+wasm-bindgen = "0.2"
+wasm-bindgen-futures = "0.4"
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+serde-wasm-bindgen = "0.4"
+tokio = { version = "1", features = ["sync", "macros", "rt", "time"] }
+js-sys = "0.3"
+sha2 = "0.10"
+web-sys = { version = "0.3", features = ["Window"] }
+
+[target.'cfg(target_arch = "wasm32")'.dependencies]
+getrandom = { version = "0.2", features = ["js"] }
+
+[package.metadata.wasm]
+name = "feltdb"
+
+# CI and customer builds must not depend on downloading Binaryen from GitHub.
+# Rust already emits an optimized release artifact; wasm-opt can be applied in
+# a separately provisioned release environment when desired.
+[package.metadata.wasm-pack.profile.release]
+wasm-opt = false