igniter-ledger 0.5.2

data/exe/igniter-store-server

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+warn "igniter-store-server is deprecated; use igniter-ledger-server instead"
+
+load File.expand_path("igniter-ledger-server", __dir__)

data/ext/igniter_store_native/Cargo.toml

@@ -0,0 +1,28 @@
+[package]
+name = "igniter_store_native"
+version = "0.1.0"
+edition = "2021"
+authors = ["Alexander <alexander.s.fokin@gmail.com>"]
+
+[lib]
+name = "igniter_store_native"
+crate-type = ["cdylib"]
+
+[dependencies]
+magnus = "0.7"
+blake3 = "1.5"
+parking_lot = "0.12"
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+rmp-serde = "1.3"
+crc32fast = "1"
+uuid = { version = "1", features = ["v4", "fast-rng"] }
+
+[profile.release]
+lto = true
+codegen-units = 1
+opt-level = 3
+
+[profile.dev]
+opt-level = 0
+debug = true

data/ext/igniter_store_native/extconf.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require "mkmf"
+require "rb_sys/mkmf"
+
+create_rust_makefile("igniter_store_native")

data/ext/igniter_store_native/src/fact.rs

@@ -0,0 +1,303 @@
+use magnus::{
+    r_hash::ForEach, prelude::*, Error, Float as RbFloat, IntoValue, Integer as RbInteger,
+    RArray, RHash, Ruby, Symbol, Value,
+};
+use serde::{Deserialize, Serialize};
+use std::collections::BTreeMap;
+
+/// Pure-Rust representation of an immutable fact.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct FactData {
+    pub id: String,
+    pub store: String,
+    pub key: String,
+    /// Stable-sorted JSON with symbol-tagged strings (":foo" = Ruby :foo).
+    pub value: serde_json::Value,
+    pub value_hash: String,
+    pub causation: Option<String>,
+    /// Wall-clock epoch seconds when the fact was committed (auto-set by store).
+    pub transaction_time: f64,
+    /// Domain time: when the event is asserted to be true in the world (writer-supplied, nullable).
+    pub valid_time: Option<f64>,
+    pub schema_version: i64,
+    /// Typed producer reference: { type:, name:, ... } or nil.
+    pub producer: Option<serde_json::Value>,
+    /// Inline provenance for derived facts: { name:, version:, source_fact_ids:, ... } or nil.
+    pub derivation: Option<serde_json::Value>,
+}
+
+/// Ruby-visible Fact class backed by Rust.
+#[magnus::wrap(class = "Igniter::Store::Fact", free_immediately, size)]
+pub struct Fact(pub FactData);
+
+// ── Class method ─────────────────────────────────────────────────────────────
+
+/// Build a Fact from Ruby arguments (8-arg form used by native.rb build wrapper).
+/// valid_time and schema_version are positional; producer and derivation are Value
+/// so they can accept Ruby nil without a wrapper type.
+pub fn rb_build(
+    store: String,
+    key: String,
+    rb_value: RHash,
+    causation: Option<String>,
+    valid_time_val: Value,
+    schema_version: i64,
+    producer_val: Value,
+    derivation_val: Value,
+) -> Result<Fact, Error> {
+    let json_val = ruby_hash_to_json_sorted(rb_value.as_value());
+    let json_str = serde_json::to_string(&json_val)
+        .map_err(|e| Error::new(magnus::exception::runtime_error(), e.to_string()))?;
+    let value_hash = blake3::hash(json_str.as_bytes()).to_hex().to_string();
+
+    let valid_time = if valid_time_val.is_nil() {
+        None
+    } else {
+        RbFloat::from_value(valid_time_val)
+            .map(|f| Some(f.to_f64()))
+            .unwrap_or_else(|| {
+                RbInteger::from_value(valid_time_val)
+                    .and_then(|i| i.to_i64().ok())
+                    .map(|i| i as f64)
+            })
+    };
+
+    let producer = if producer_val.is_nil() {
+        None
+    } else {
+        Some(ruby_hash_to_json_sorted(producer_val))
+    };
+
+    let derivation = if derivation_val.is_nil() {
+        None
+    } else {
+        Some(ruby_hash_to_json_sorted(derivation_val))
+    };
+
+    Ok(Fact(FactData {
+        id: uuid::Uuid::new_v4().to_string(),
+        store,
+        key,
+        value: json_val,
+        value_hash,
+        causation,
+        transaction_time: current_time(),
+        valid_time,
+        schema_version,
+        producer,
+        derivation,
+    }))
+}
+
+// ── Instance methods ──────────────────────────────────────────────────────────
+
+impl Fact {
+    pub fn rb_id(&self) -> String { self.0.id.clone() }
+    pub fn rb_store(&self) -> String { self.0.store.clone() }
+    pub fn rb_key(&self) -> String { self.0.key.clone() }
+
+    pub fn rb_value(&self) -> Value {
+        let ruby = unsafe { Ruby::get_unchecked() };
+        json_to_ruby_value(&ruby, &self.0.value)
+    }
+
+    pub fn rb_value_hash(&self) -> String { self.0.value_hash.clone() }
+
+    pub fn rb_causation(&self) -> Value {
+        let ruby = unsafe { Ruby::get_unchecked() };
+        match &self.0.causation {
+            Some(s) => s.as_str().into_value_with(&ruby),
+            None    => ruby.qnil().as_value(),
+        }
+    }
+
+    /// Canonical name for when the fact was committed.
+    pub fn rb_transaction_time(&self) -> f64 { self.0.transaction_time }
+
+    /// Canonical name for the domain valid time (nullable).
+    pub fn rb_valid_time(&self) -> Value {
+        let ruby = unsafe { Ruby::get_unchecked() };
+        match self.0.valid_time {
+            Some(v) => v.into_value_with(&ruby),
+            None    => ruby.qnil().as_value(),
+        }
+    }
+
+    /// Backward-compat alias for transaction_time.
+    pub fn rb_timestamp(&self) -> f64 { self.0.transaction_time }
+
+    /// Backward-compat alias for valid_time (returns 0 when nil, matching old term: 0 default).
+    pub fn rb_term(&self) -> f64 { self.0.valid_time.unwrap_or(0.0) }
+
+    pub fn rb_schema_version(&self) -> i64 { self.0.schema_version }
+
+    pub fn rb_producer(&self) -> Value {
+        let ruby = unsafe { Ruby::get_unchecked() };
+        match &self.0.producer {
+            Some(v) => json_to_ruby_value(&ruby, v),
+            None    => ruby.qnil().as_value(),
+        }
+    }
+
+    pub fn rb_derivation(&self) -> Value {
+        let ruby = unsafe { Ruby::get_unchecked() };
+        match &self.0.derivation {
+            Some(v) => json_to_ruby_value(&ruby, v),
+            None    => ruby.qnil().as_value(),
+        }
+    }
+
+    pub fn rb_frozen(&self) -> bool { true }
+
+    pub fn rb_to_h(&self) -> Result<RHash, Error> {
+        let ruby = unsafe { Ruby::get_unchecked() };
+        let h = RHash::new();
+        h.aset(Symbol::new("id"),               self.0.id.as_str())?;
+        h.aset(Symbol::new("store"),            Symbol::new(self.0.store.as_str()))?;
+        h.aset(Symbol::new("key"),              self.0.key.as_str())?;
+        h.aset(Symbol::new("value"),            json_to_ruby_value(&ruby, &self.0.value))?;
+        h.aset(Symbol::new("value_hash"),       self.0.value_hash.as_str())?;
+        match &self.0.causation {
+            Some(s) => h.aset(Symbol::new("causation"), s.as_str())?,
+            None    => h.aset(Symbol::new("causation"), ruby.qnil())?,
+        }
+        h.aset(Symbol::new("transaction_time"), self.0.transaction_time)?;
+        match self.0.valid_time {
+            Some(v) => h.aset(Symbol::new("valid_time"), v)?,
+            None    => h.aset(Symbol::new("valid_time"), ruby.qnil())?,
+        }
+        h.aset(Symbol::new("schema_version"),   self.0.schema_version)?;
+        match &self.0.producer {
+            Some(v) => h.aset(Symbol::new("producer"), json_to_ruby_value(&ruby, v))?,
+            None    => h.aset(Symbol::new("producer"), ruby.qnil())?,
+        }
+        match &self.0.derivation {
+            Some(v) => h.aset(Symbol::new("derivation"), json_to_ruby_value(&ruby, v))?,
+            None    => h.aset(Symbol::new("derivation"), ruby.qnil())?,
+        }
+        Ok(h)
+    }
+
+    pub fn rb_inspect(&self) -> String {
+        format!(
+            "#<Igniter::Store::Fact store={:?} key={:?} hash={}>",
+            self.0.store,
+            self.0.key,
+            &self.0.value_hash[..12]
+        )
+    }
+}
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+pub fn ruby_hash_to_json_sorted(val: Value) -> serde_json::Value {
+    ruby_to_json_inner(val)
+}
+
+fn ruby_to_json_inner(val: Value) -> serde_json::Value {
+    if val.is_nil() {
+        return serde_json::Value::Null;
+    }
+    // Symbol :foo → tagged string ":foo" (preserves round-trip identity)
+    if let Some(sym) = Symbol::from_value(val) {
+        let name = sym.name().unwrap_or_default();
+        return serde_json::Value::String(format!(":{name}"));
+    }
+    // Array
+    if let Some(arr) = RArray::from_value(val) {
+        let len = arr.len();
+        let items: Vec<serde_json::Value> = (0..len)
+            .map(|i| {
+                arr.entry(i as isize)
+                    .map(ruby_to_json_inner)
+                    .unwrap_or(serde_json::Value::Null)
+            })
+            .collect();
+        return serde_json::Value::Array(items);
+    }
+    // Hash — keys sorted via BTreeMap for stable hashing
+    if let Some(hash) = RHash::from_value(val) {
+        let mut map: BTreeMap<String, serde_json::Value> = BTreeMap::new();
+        let _ = hash.foreach(|k: Value, v: Value| {
+            let key = if let Some(sym) = Symbol::from_value(k) {
+                sym.name().unwrap_or_default().to_string()
+            } else if let Ok(s) = String::try_convert(k) {
+                s
+            } else {
+                k.inspect()
+            };
+            map.insert(key, ruby_to_json_inner(v));
+            Ok(ForEach::Continue)
+        });
+        return serde_json::Value::Object(map.into_iter().collect());
+    }
+    // Integer — exact Ruby type check to avoid coercing Float 7.0 → 7
+    if let Some(int) = RbInteger::from_value(val) {
+        if let Ok(n) = int.to_i64() {
+            return serde_json::json!(n);
+        }
+    }
+    // Float — exact Ruby type check
+    if let Some(flt) = RbFloat::from_value(val) {
+        return serde_json::json!(flt.to_f64());
+    }
+    // String
+    if let Ok(s) = String::try_convert(val) {
+        return serde_json::Value::String(s);
+    }
+    // Boolean fallback via inspect
+    match val.inspect().as_str() {
+        "true"  => serde_json::Value::Bool(true),
+        "false" => serde_json::Value::Bool(false),
+        other   => serde_json::Value::String(other.to_string()),
+    }
+}
+
+/// serde_json::Value → Ruby Value.
+/// Strings prefixed with ":" are restored as Ruby Symbols.
+pub fn json_to_ruby_value(ruby: &Ruby, val: &serde_json::Value) -> Value {
+    match val {
+        serde_json::Value::Null => ruby.qnil().as_value(),
+        serde_json::Value::Bool(b) => {
+            if *b { ruby.qtrue().as_value() } else { ruby.qfalse().as_value() }
+        }
+        serde_json::Value::Number(n) => {
+            if let Some(i) = n.as_i64() {
+                i.into_value_with(ruby)
+            } else if let Some(f) = n.as_f64() {
+                f.into_value_with(ruby)
+            } else {
+                ruby.qnil().as_value()
+            }
+        }
+        serde_json::Value::String(s) => {
+            if s.starts_with(':') {
+                Symbol::new(&s[1..]).as_value()
+            } else {
+                s.as_str().into_value_with(ruby)
+            }
+        }
+        serde_json::Value::Array(arr) => {
+            let rb_arr = RArray::new();
+            for item in arr {
+                let _ = rb_arr.push(json_to_ruby_value(ruby, item));
+            }
+            rb_arr.as_value()
+        }
+        serde_json::Value::Object(obj) => {
+            let rb_hash = RHash::new();
+            for (k, v) in obj {
+                let key = Symbol::new(k.as_str()).as_value();
+                let _ = rb_hash.aset(key, json_to_ruby_value(ruby, v));
+            }
+            rb_hash.as_value()
+        }
+    }
+}
+
+fn current_time() -> f64 {
+    std::time::SystemTime::now()
+        .duration_since(std::time::UNIX_EPOCH)
+        .unwrap_or_default()
+        .as_secs_f64()
+}

data/ext/igniter_store_native/src/fact_log.rs

@@ -0,0 +1,180 @@
+use magnus::{prelude::*, Error, IntoValue, RArray, RHash, Ruby, Value};
+use parking_lot::RwLock;
+use std::collections::HashMap;
+
+use crate::fact::{ruby_hash_to_json_sorted, Fact, FactData};
+
+struct FactLogInner {
+    log: Vec<FactData>,
+    by_id: HashMap<String, usize>,
+    /// (store, key) → insertion-ordered indices into `log`
+    by_key: HashMap<(String, String), Vec<usize>>,
+}
+
+impl FactLogInner {
+    fn push(&mut self, data: FactData) {
+        let idx = self.log.len();
+        self.by_id.insert(data.id.clone(), idx);
+        self.by_key
+            .entry((data.store.clone(), data.key.clone()))
+            .or_default()
+            .push(idx);
+        self.log.push(data);
+    }
+}
+
+#[magnus::wrap(class = "Igniter::Store::FactLog", free_immediately, size)]
+pub struct FactLog(RwLock<FactLogInner>);
+
+impl FactLog {
+    pub fn rb_new() -> Self {
+        FactLog(RwLock::new(FactLogInner {
+            log: Vec::new(),
+            by_id: HashMap::new(),
+            by_key: HashMap::new(),
+        }))
+    }
+
+    /// Appends a fact. Returns nil; Ruby wrapper returns the original Fact arg.
+    pub fn rb_append(&self, rb_fact: &Fact) -> Value {
+        self.0.write().push(rb_fact.0.clone());
+        let ruby = unsafe { Ruby::get_unchecked() };
+        ruby.qnil().as_value()
+    }
+
+    /// Replays a fact during WAL restore (no backend write).
+    pub fn rb_replay_fact(&self, rb_fact: &Fact) {
+        self.0.write().push(rb_fact.0.clone());
+    }
+
+    pub fn rb_latest_for_native(
+        &self,
+        store: String,
+        key: String,
+        as_of: Option<f64>,
+    ) -> Value {
+        let ruby = unsafe { Ruby::get_unchecked() };
+        let inner = self.0.read();
+        let k = (store, key);
+        let indices = match inner.by_key.get(&k) {
+            Some(v) => v,
+            None => return ruby.qnil().as_value(),
+        };
+
+        let latest_idx = if let Some(as_of) = as_of {
+            indices
+                .iter()
+                .rev()
+                .find(|&&i| inner.log[i].transaction_time <= as_of)
+                .copied()
+        } else {
+            indices.last().copied()
+        };
+
+        match latest_idx {
+            Some(idx) => {
+                let data = inner.log[idx].clone();
+                drop(inner);
+                Fact(data).into_value_with(&ruby)
+            }
+            None => ruby.qnil().as_value(),
+        }
+    }
+
+    pub fn rb_facts_for_native(
+        &self,
+        store: String,
+        key: Option<String>,
+        since: Option<f64>,
+        as_of: Option<f64>,
+    ) -> Result<RArray, Error> {
+        let ruby = unsafe { Ruby::get_unchecked() };
+        let inner = self.0.read();
+
+        let indices: Vec<usize> = if let Some(ref k) = key {
+            inner
+                .by_key
+                .get(&(store.clone(), k.clone()))
+                .cloned()
+                .unwrap_or_default()
+        } else {
+            (0..inner.log.len())
+                .filter(|&i| inner.log[i].store == store)
+                .collect()
+        };
+
+        let filtered: Vec<FactData> = indices
+            .into_iter()
+            .filter(|&i| {
+                let t = inner.log[i].transaction_time;
+                since.map_or(true, |s| t >= s) && as_of.map_or(true, |a| t <= a)
+            })
+            .map(|i| inner.log[i].clone())
+            .collect();
+
+        drop(inner);
+
+        let arr = RArray::new();
+        for data in filtered {
+            arr.push(Fact(data).into_value_with(&ruby))?;
+        }
+        Ok(arr)
+    }
+
+    pub fn rb_size(&self) -> usize {
+        self.0.read().log.len()
+    }
+
+    /// Returns latest fact per key in `store` whose `value` matches all `filters`.
+    /// `filters` is a Ruby Hash like `{ status: :pending }`.
+    /// Returns the latest fact per key (optionally as of a timestamp).
+    pub fn rb_query_scope_native(
+        &self,
+        store: String,
+        filters: RHash,
+        as_of: Option<f64>,
+    ) -> Result<RArray, Error> {
+        let ruby = unsafe { Ruby::get_unchecked() };
+        let filter_json = ruby_hash_to_json_sorted(filters.as_value());
+
+        let inner = self.0.read();
+
+        let mut results: Vec<FactData> = Vec::new();
+
+        for ((s, _k), indices) in &inner.by_key {
+            if s != &store {
+                continue;
+            }
+            let latest_idx = if let Some(as_of) = as_of {
+                indices
+                    .iter()
+                    .rev()
+                    .find(|&&i| inner.log[i].transaction_time <= as_of)
+                    .copied()
+            } else {
+                indices.last().copied()
+            };
+            if let Some(idx) = latest_idx {
+                if matches_filters(&inner.log[idx].value, &filter_json) {
+                    results.push(inner.log[idx].clone());
+                }
+            }
+        }
+        drop(inner);
+
+        let arr = RArray::new();
+        for data in results {
+            arr.push(Fact(data).into_value_with(&ruby))?;
+        }
+        Ok(arr)
+    }
+}
+
+fn matches_filters(value: &serde_json::Value, filters: &serde_json::Value) -> bool {
+    match (value, filters) {
+        (serde_json::Value::Object(v), serde_json::Value::Object(f)) => {
+            f.iter().all(|(k, fv)| v.get(k).map_or(false, |vv| vv == fv))
+        }
+        _ => false,
+    }
+}

data/ext/igniter_store_native/src/file_backend.rs

@@ -0,0 +1,91 @@
+/// Binary framed WAL.
+///
+/// Record layout:
+///   [4 bytes BE u32: body_len][body_len bytes: rmp-serde body][4 bytes BE u32: CRC32 of body]
+use magnus::{Error, IntoValue, RArray, Ruby};
+use std::cell::RefCell;
+use std::fs::{File, OpenOptions};
+use std::io::{BufWriter, Read, Seek, SeekFrom, Write};
+
+use crate::fact::{Fact, FactData};
+
+struct FileBackendInner {
+    path: String,
+    writer: BufWriter<File>,
+}
+
+#[magnus::wrap(class = "Igniter::Store::FileBackend", free_immediately, size)]
+pub struct FileBackend(RefCell<FileBackendInner>);
+
+impl FileBackend {
+    pub fn rb_new(path: String) -> Result<Self, Error> {
+        let file = OpenOptions::new()
+            .create(true)
+            .append(true)
+            .open(&path)
+            .map_err(|e| Error::new(magnus::exception::runtime_error(), e.to_string()))?;
+        Ok(FileBackend(RefCell::new(FileBackendInner {
+            path,
+            writer: BufWriter::new(file),
+        })))
+    }
+
+    pub fn rb_write_fact(&self, rb_fact: &Fact) -> Result<(), Error> {
+        let body = rmp_serde::to_vec_named(&rb_fact.0)
+            .map_err(|e| Error::new(magnus::exception::runtime_error(), e.to_string()))?;
+        let crc = crc32fast::hash(&body);
+        let mut inner = self.0.borrow_mut();
+        inner.writer.write_all(&(body.len() as u32).to_be_bytes())
+            .and_then(|_| inner.writer.write_all(&body))
+            .and_then(|_| inner.writer.write_all(&crc.to_be_bytes()))
+            .and_then(|_| inner.writer.flush())
+            .map_err(|e| Error::new(magnus::exception::runtime_error(), e.to_string()))
+    }
+
+    pub fn rb_replay(&self) -> Result<RArray, Error> {
+        let ruby = unsafe { Ruby::get_unchecked() };
+        let path = self.0.borrow().path.clone();
+
+        let mut file = File::open(&path)
+            .map_err(|e| Error::new(magnus::exception::runtime_error(), e.to_string()))?;
+        file.seek(SeekFrom::Start(0))
+            .map_err(|e| Error::new(magnus::exception::runtime_error(), e.to_string()))?;
+
+        let arr = RArray::new();
+        loop {
+            let mut len_buf = [0u8; 4];
+            match file.read_exact(&mut len_buf) {
+                Ok(_) => {}
+                Err(e) if e.kind() == std::io::ErrorKind::UnexpectedEof => break,
+                Err(e) => return Err(Error::new(magnus::exception::runtime_error(), e.to_string())),
+            }
+            let body_len = u32::from_be_bytes(len_buf) as usize;
+
+            let mut body = vec![0u8; body_len];
+            if file.read_exact(&mut body).is_err() {
+                break; // truncated record
+            }
+
+            let mut crc_buf = [0u8; 4];
+            if file.read_exact(&mut crc_buf).is_err() {
+                break;
+            }
+            if u32::from_be_bytes(crc_buf) != crc32fast::hash(&body) {
+                break; // corrupted frame
+            }
+
+            let data: FactData = match rmp_serde::from_slice(&body) {
+                Ok(d) => d,
+                Err(_) => continue,
+            };
+
+            arr.push(Fact(data).into_value_with(&ruby))?;
+        }
+        Ok(arr)
+    }
+
+    pub fn rb_close(&self) -> Result<(), Error> {
+        self.0.borrow_mut().writer.flush()
+            .map_err(|e| Error::new(magnus::exception::runtime_error(), e.to_string()))
+    }
+}

data/ext/igniter_store_native/src/lib.rs

@@ -0,0 +1,55 @@
+mod fact;
+mod fact_log;
+mod file_backend;
+
+use magnus::{function, method, prelude::*, Error, Module, Ruby};
+
+use fact::Fact;
+use fact_log::FactLog;
+use file_backend::FileBackend;
+
+#[magnus::init]
+fn init(ruby: &Ruby) -> Result<(), Error> {
+    let igniter = ruby.define_module("Igniter")?;
+    let store_mod = igniter.define_module("Store")?;
+
+    // ── Fact ──────────────────────────────────────────────────────────────────
+    let fact_class = store_mod.define_class("Fact", ruby.class_object())?;
+    fact_class.define_singleton_method("_native_build", function!(fact::rb_build, 8))?;
+    fact_class.define_method("id",               method!(Fact::rb_id, 0))?;
+    fact_class.define_method("store",            method!(Fact::rb_store, 0))?;
+    fact_class.define_method("key",              method!(Fact::rb_key, 0))?;
+    fact_class.define_method("value",            method!(Fact::rb_value, 0))?;
+    fact_class.define_method("value_hash",       method!(Fact::rb_value_hash, 0))?;
+    fact_class.define_method("causation",        method!(Fact::rb_causation, 0))?;
+    fact_class.define_method("transaction_time", method!(Fact::rb_transaction_time, 0))?;
+    fact_class.define_method("valid_time",       method!(Fact::rb_valid_time, 0))?;
+    fact_class.define_method("producer",         method!(Fact::rb_producer, 0))?;
+    fact_class.define_method("derivation",       method!(Fact::rb_derivation, 0))?;
+    fact_class.define_method("schema_version",   method!(Fact::rb_schema_version, 0))?;
+    fact_class.define_method("to_h",             method!(Fact::rb_to_h, 0))?;
+    fact_class.define_method("inspect",          method!(Fact::rb_inspect, 0))?;
+    fact_class.define_method("frozen?",          method!(Fact::rb_frozen, 0))?;
+    // Backward-compat aliases (removed after callers migrate)
+    fact_class.define_method("timestamp",        method!(Fact::rb_timestamp, 0))?;
+    fact_class.define_method("term",             method!(Fact::rb_term, 0))?;
+
+    // ── FactLog ───────────────────────────────────────────────────────────────
+    let log_class = store_mod.define_class("FactLog", ruby.class_object())?;
+    log_class.define_singleton_method("new", function!(FactLog::rb_new, 0))?;
+    log_class.define_method("_native_append",      method!(FactLog::rb_append, 1))?;
+    log_class.define_method("replay",              method!(FactLog::rb_replay_fact, 1))?;
+    log_class.define_method("latest_for_native",   method!(FactLog::rb_latest_for_native, 3))?;
+    log_class.define_method("facts_for_native",       method!(FactLog::rb_facts_for_native, 4))?;
+    log_class.define_method("query_scope_native",     method!(FactLog::rb_query_scope_native, 3))?;
+    log_class.define_method("size",                   method!(FactLog::rb_size, 0))?;
+
+    // ── FileBackend ───────────────────────────────────────────────────────────
+    let fb_class = store_mod.define_class("FileBackend", ruby.class_object())?;
+    fb_class.define_singleton_method("new",   function!(FileBackend::rb_new, 1))?;
+    fb_class.define_method("write_fact",      method!(FileBackend::rb_write_fact, 1))?;
+    fb_class.define_method("replay",          method!(FileBackend::rb_replay, 0))?;
+    fb_class.define_method("close",           method!(FileBackend::rb_close, 0))?;
+
+    Ok(())
+}

data/lib/igniter/ledger.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require_relative "store"
+
+module Igniter
+  Ledger = Store unless const_defined?(:Ledger)
+end