hecks 4.0.0 → 6.0.0

data/rust/host/{src → core/src}/host.rs

@@ -2,27 +2,26 @@
 
 use crate::journal::LineageConfig;
 use crate::lambda_client::LambdaInvoker;
+use crate::store::Store;
 use std::path::{Path, PathBuf};
 use std::sync::Arc;
-use tokio::sync::Mutex;
-use tokio_postgres::Client;
 
 /// The server's own shared handles, when a host is built from them.
 #[derive(Clone, Copy)]
 struct Shared<'a> {
-    client: &'a Arc<Mutex<Client>>,
+    store: &'a Arc<Store>,
     wasm_path: &'a Arc<PathBuf>,
     config: &'a Arc<LineageConfig>,
     invoker: &'a Arc<dyn LambdaInvoker>,
 }
 
-/// The journal connection, the compiled domain module, the lineage it runs under, and the
+/// The journal store, the compiled domain module, the lineage it runs under, and the
 /// invoker that delivers a policy's cross-domain reactions. Borrowed from the server's state (or
 /// a test's fixtures) for the length of one call, so it is `Copy`.
 #[derive(Clone, Copy)]
 pub struct Host<'a> {
-    /// The one Postgres connection; its mutex serializes every write onto it.
-    pub client: &'a Mutex<Client>,
+    /// Where the domain's journal, snapshot and sagas live.
+    pub store: &'a Store,
     pub wasm_path: &'a Path,
     pub config: &'a LineageConfig,
     pub invoker: &'a dyn LambdaInvoker,
@@ -33,13 +32,13 @@ impl<'a> Host<'a> {
     /// A host over borrowed pieces. It cannot outlive the call, so work that must outlast the
     /// response stays inline.
     pub fn new(
-        client: &'a Mutex<Client>,
+        store: &'a Store,
         wasm_path: &'a Path,
         config: &'a LineageConfig,
         invoker: &'a dyn LambdaInvoker,
     ) -> Self {
         Self {
-            client,
+            store,
             wasm_path,
             config,
             invoker,
@@ -49,18 +48,18 @@ impl<'a> Host<'a> {
 
     /// A host over the server's own `Arc`s, from which `detach` can hand work an owned copy.
     pub fn shared(
-        client: &'a Arc<Mutex<Client>>,
+        store: &'a Arc<Store>,
         wasm_path: &'a Arc<PathBuf>,
         config: &'a Arc<LineageConfig>,
         invoker: &'a Arc<dyn LambdaInvoker>,
     ) -> Self {
         Self {
-            client,
+            store,
             wasm_path,
             config,
             invoker: invoker.as_ref(),
             shared: Some(Shared {
-                client,
+                store,
                 wasm_path,
                 config,
                 invoker,
@@ -72,7 +71,7 @@ impl<'a> Host<'a> {
     /// from borrows and so cannot be detached.
     pub fn detach(&self) -> Option<OwnedHost> {
         self.shared.map(|shared| OwnedHost {
-            client: Arc::clone(shared.client),
+            store: Arc::clone(shared.store),
             wasm_path: Arc::clone(shared.wasm_path),
             config: Arc::clone(shared.config),
             invoker: Arc::clone(shared.invoker),
@@ -82,7 +81,7 @@ impl<'a> Host<'a> {
 
 /// A `Host` that owns its handles, for work spawned past the end of a request.
 pub struct OwnedHost {
-    client: Arc<Mutex<Client>>,
+    store: Arc<Store>,
     wasm_path: Arc<PathBuf>,
     config: Arc<LineageConfig>,
     invoker: Arc<dyn LambdaInvoker>,
@@ -91,7 +90,7 @@ pub struct OwnedHost {
 impl OwnedHost {
     pub fn host(&self) -> Host<'_> {
         Host::new(
-            &self.client,
+            &self.store,
             &self.wasm_path,
             &self.config,
             self.invoker.as_ref(),

data/rust/host/{src → core/src}/ir.rs

@@ -1,17 +1,43 @@
-// The IR sidecar, loaded once from `HECKS_IR_PATH`: this crate has no path
-// dependency on the kernel crate that embeds the same JSON as `IR_JSON`.
+// The IR sidecar, installed once by boot from the file `HECKS_IR_PATH` names: this crate has no
+// path dependency on the kernel crate that embeds the same JSON as `IR_JSON`.
 
 use serde_json::Value;
 use std::sync::OnceLock;
 
+static IR: OnceLock<Option<Value>> = OnceLock::new();
+static SCHEMAS: OnceLock<Option<Value>> = OnceLock::new();
+
+/// The JSON Schema of the command `Aggregate/Command`, from the `schemas.json` the build writes
+/// beside the IR; `None` when no schemas were installed or the command has none.
+pub fn command_schema(aggregate: &str, command: &str) -> Option<&'static Value> {
+    SCHEMAS
+        .get()
+        .and_then(Option::as_ref)?
+        .get(format!("{aggregate}/{command}"))
+}
+
+/// Reads the schemas file beside the IR file at `ir_path` (`<name>.ir.json` -> `<name>.schemas.json`);
+/// a missing or unreadable file installs none, and a command then has no schema to serve.
+pub fn install_schemas(ir_path: Option<&str>) {
+    SCHEMAS.get_or_init(|| {
+        let path = ir_path?.strip_suffix(".ir.json")?.to_string() + ".schemas.json";
+        serde_json::from_str(&std::fs::read_to_string(path).ok()?).ok()
+    });
+}
+
+/// The domain's IR, or `None` when nothing has been installed or the installed file was missing,
+/// unreadable or not JSON.
 pub fn ir() -> Option<&'static Value> {
-    static IR: OnceLock<Option<Value>> = OnceLock::new();
+    IR.get().and_then(Option::as_ref)
+}
+
+/// Reads and parses the IR file at `path` for [`ir`] to answer; `None` installs no IR. Only the
+/// first call has an effect, so the IR is fixed for the life of the process.
+pub fn install(path: Option<&str>) {
     IR.get_or_init(|| {
-        let path = std::env::var("HECKS_IR_PATH").ok()?;
-        let text = std::fs::read_to_string(path).ok()?;
+        let text = std::fs::read_to_string(path?).ok()?;
         serde_json::from_str(&text).ok()
-    })
-    .as_ref()
+    });
 }
 
 /// Aggregates bound to a lineage-capable adapter, as `(qualified_name,
@@ -61,13 +87,29 @@ pub fn persistence_adapters(domain_ir: &Value) -> Vec<(String, String)> {
 /// The only persistence adapters `rust/host` has a real backend for — see
 /// `refuse_unsupported_persistence_adapters` below. Must list the same names
 /// as [`BACKENDS`] (a test holds them together).
-pub const SUPPORTED_PERSISTENCE_ADAPTERS: &[&str] = &["Postgres", "PostgresEra"];
+pub const SUPPORTED_PERSISTENCE_ADAPTERS: &[&str] = &["Postgres", "PostgresEra", "Memory"];
+
+/// The environment variable that lets the host boot on the Memory store, which keeps nothing
+/// across a restart and so is for local runs and tests only.
+pub const ALLOW_MEMORY_STORE: &str = "HECKS_ALLOW_MEMORY_STORE";
 
 /// What serves a bound adapter inside this host.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum Backend {
     /// The one `tokio_postgres` engine (journal tables, era heads).
     TokioPostgres,
+    /// Process memory: a journal that lives and dies with the process.
+    Memory,
+}
+
+impl Backend {
+    /// The name used in refusals.
+    pub const fn name(self) -> &'static str {
+        match self {
+            Self::TokioPostgres => "Postgres",
+            Self::Memory => "Memory",
+        }
+    }
 }
 
 /// The host's implemented backends, adapter name -> backend. A future backend
@@ -75,6 +117,7 @@ pub enum Backend {
 pub const BACKENDS: &[(&str, Backend)] = &[
     ("Postgres", Backend::TokioPostgres),
     ("PostgresEra", Backend::TokioPostgres),
+    ("Memory", Backend::Memory),
 ];
 
 /// The backend that serves `adapter`, if the host has one.
@@ -116,7 +159,29 @@ pub fn adapter_declarations(
     Some(Ok(declared))
 }
 
-/// The chapter this domain's role checks resolve against, read from
+/// Whether the adapter the IR binds `aggregate` to declares `provides capability`: the host's
+/// reading of Ruby's `Registry#adapter_provides?`. False when the aggregate is unbound, its
+/// adapter is undeclared, or the IR predates the `adapters` key.
+pub fn adapter_provides(domain_ir: &Value, aggregate: &str, capability: &str) -> bool {
+    let bound = domain_ir
+        .pointer("/persistence/aggregates")
+        .and_then(Value::as_array)
+        .and_then(|rows| {
+            rows.iter()
+                .find(|row| row.get("name").and_then(Value::as_str) == Some(aggregate))
+        })
+        .and_then(|row| row.get("adapter").and_then(Value::as_str));
+    let Some(Some(Ok(declared))) = bound.map(|_| adapter_declarations(domain_ir)) else {
+        return false;
+    };
+    bound
+        .and_then(|name| declared.get(name))
+        .and_then(|adapter| adapter.get("provides"))
+        .and_then(Value::as_array)
+        .is_some_and(|names| names.iter().any(|name| name.as_str() == Some(capability)))
+}
+
+/// The bluebook this domain's role checks resolve against, read from
 /// `ir.json`'s own `authorization` key. `None` when nothing provides it.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct AuthorizationProvider {
@@ -125,6 +190,10 @@ pub struct AuthorizationProvider {
     /// Qualified aggregate holding the assignments, e.g.
     /// `Governance::RoleAssignment` — instance keys start `<this>#`.
     pub assignment_aggregate: String,
+    /// Qualified query answering the assignments one actor holds right now, e.g.
+    /// `Governance::RoleAssignment.LiveAssignmentsForActor`; the bluebook decides what live
+    /// means. `None` when the IR predates it, which holds no role.
+    pub live_assignments: Option<String>,
 }
 
 pub fn authorization_provider(domain_ir: &Value) -> Option<AuthorizationProvider> {
@@ -132,14 +201,18 @@ pub fn authorization_provider(domain_ir: &Value) -> Option<AuthorizationProvider
     Some(AuthorizationProvider {
         grant: fact.get("grant")?.as_str()?.to_string(),
         assignment_aggregate: fact.get("assignment_aggregate")?.as_str()?.to_string(),
+        live_assignments: fact
+            .get("live_assignments")
+            .and_then(Value::as_str)
+            .map(str::to_string),
     })
 }
 
-/// The chapter that answers "who may sign in", read from `ir.json`'s own
+/// The bluebook that answers "who may sign in", read from `ir.json`'s own
 /// `membership` key. `None` when nothing provides `"membership"`.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct MembershipProvider {
-    /// Chapter name, e.g. `Membership`.
+    /// Bluebook name, e.g. `Membership`.
     pub provider: String,
     /// Qualified aggregate, e.g. `Membership::Person`.
     pub aggregate: String,
@@ -166,12 +239,12 @@ pub fn membership_provider(domain_ir: &Value) -> Option<MembershipProvider> {
     })
 }
 
-/// The chapter that answers "who is this authenticated pair", read from
+/// The bluebook that answers "who is this authenticated pair", read from
 /// `ir.json`'s own `identity` key. `None` when nothing provides `"identity"`.
 /// Link's reference field must stay `identity` — never `identity_id`, never `to:`.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct IdentityProvider {
-    /// Chapter name, e.g. `Identity`.
+    /// Bluebook name, e.g. `Identity`.
     pub provider: String,
     /// Qualified register command, e.g. `Identity::Identity.Register`.
     pub register: String,
@@ -316,6 +389,54 @@ pub fn refuse_unsupported_persistence_adapters(domain_ir: &Value) -> Result<(),
     ))
 }
 
+/// Picks the one backend this domain's journal lives on, or says why it cannot boot.
+///
+/// 1. Every adapter must be one the host serves (see
+///    [`refuse_unsupported_persistence_adapters`]).
+/// 2. All the domain's aggregates must resolve to the same backend: a domain keeps one journal.
+/// 3. The Memory backend needs `allow_memory`, because it is for local runs and tests.
+///
+/// Both backends hold eras and head rows, so lineage-capable aggregates and Google sign-in boot on
+/// either.
+///
+/// An IR with no persistence bindings (an older one) boots on Postgres, as it always did.
+pub fn select_backend(domain_ir: &Value, allow_memory: bool) -> Result<Backend, String> {
+    refuse_unsupported_persistence_adapters(domain_ir)?;
+    let backend = single_backend(domain_ir)?;
+    if backend == Backend::Memory && !allow_memory {
+        return Err(format!(
+            "this domain binds the Memory store, which keeps nothing across a restart and is for \
+             local runs and tests only; set {ALLOW_MEMORY_STORE}=1 to boot on it, or bind a \
+             durable store"
+        ));
+    }
+    Ok(backend)
+}
+
+fn single_backend(domain_ir: &Value) -> Result<Backend, String> {
+    let bindings = persistence_adapters(domain_ir);
+    let backends: std::collections::BTreeSet<&str> = bindings
+        .iter()
+        .filter_map(|(_, adapter)| backend_for(adapter))
+        .map(Backend::name)
+        .collect();
+    if backends.len() > 1 {
+        let bound: Vec<String> = bindings
+            .iter()
+            .map(|(aggregate, adapter)| format!("{aggregate} (persisted_by {adapter:?})"))
+            .collect();
+        return Err(format!(
+            "this domain binds aggregates to different stores ({}); rust/host keeps one journal \
+             per domain, on one backend, so bind every aggregate to the same store",
+            bound.join(", ")
+        ));
+    }
+    Ok(bindings
+        .first()
+        .and_then(|(_, adapter)| backend_for(adapter))
+        .unwrap_or(Backend::TokioPostgres))
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -347,7 +468,7 @@ mod tests {
     }
 
     #[test]
-    fn mirrored_aggregates_is_just_the_capable_ones_when_no_chapter_provides_membership() {
+    fn mirrored_aggregates_is_just_the_capable_ones_when_no_bluebook_provides_membership() {
         let ir = serde_json::json!({
             "name": "Shop",
             "lineage": { "capable_aggregates": [{ "name": "Order", "storage_name": "order" }] }
@@ -520,6 +641,26 @@ mod tests {
         ir
     }
 
+    #[test]
+    fn adapter_provides_reads_the_bound_adapters_capabilities() {
+        let ir = with_adapters(
+            bound(&[("Ledger::Entry", "Postgres"), ("Ledger::Note", "Memory")]),
+            serde_json::json!([
+                {"name": "Postgres", "provides": ["set_transform"]},
+                {"name": "Memory"}
+            ]),
+        );
+        assert!(adapter_provides(&ir, "Ledger::Entry", "set_transform"));
+        assert!(!adapter_provides(&ir, "Ledger::Entry", "teleport"));
+        assert!(!adapter_provides(&ir, "Ledger::Note", "set_transform"));
+        assert!(!adapter_provides(&ir, "Ledger::Ghost", "set_transform"));
+        assert!(!adapter_provides(
+            &bound(&[("Ledger::Entry", "Postgres")]),
+            "Ledger::Entry",
+            "set_transform"
+        ));
+    }
+
     #[test]
     fn backend_table_matches_the_supported_names() {
         let names: Vec<&str> = BACKENDS.iter().map(|(n, _)| *n).collect();
@@ -592,8 +733,76 @@ mod tests {
             assert!(err.contains("\"adapters\""), "{err}");
         }
     }
-}
 
-#[cfg(test)]
-#[path = "boundary_fuzz/ir.rs"]
-mod boundary_fuzz;
+    fn memory_domain() -> Value {
+        with_adapters(
+            bound(&[("A", "Memory"), ("B", "Memory")]),
+            serde_json::json!([{"name": "Memory", "port": "persistence"}]),
+        )
+    }
+
+    #[test]
+    fn a_domain_with_no_persistence_bindings_boots_on_postgres() {
+        let ir = serde_json::json!({ "name": "Pizzas" });
+        assert_eq!(select_backend(&ir, false), Ok(Backend::TokioPostgres));
+    }
+
+    #[test]
+    fn postgres_and_postgres_era_are_one_backend() {
+        let ir = bound(&[("A", "Postgres"), ("B", "PostgresEra")]);
+        assert_eq!(select_backend(&ir, false), Ok(Backend::TokioPostgres));
+    }
+
+    #[test]
+    fn a_domain_binding_different_stores_is_refused() {
+        let err = select_backend(&bound(&[("A", "Postgres"), ("B", "Memory")]), true).unwrap_err();
+        assert!(err.contains("different stores"), "{err}");
+        assert!(err.contains("A (persisted_by \"Postgres\")"), "{err}");
+        assert!(err.contains("B (persisted_by \"Memory\")"), "{err}");
+    }
+
+    #[test]
+    fn memory_is_refused_unless_the_opt_in_is_set() {
+        let err = select_backend(&memory_domain(), false).unwrap_err();
+        assert!(err.contains("local runs and tests only"), "{err}");
+        assert!(err.contains(ALLOW_MEMORY_STORE), "{err}");
+    }
+
+    #[test]
+    fn memory_boots_with_the_opt_in() {
+        assert_eq!(select_backend(&memory_domain(), true), Ok(Backend::Memory));
+    }
+
+    #[test]
+    fn lineage_capable_aggregates_boot_on_memory() {
+        let mut ir = memory_domain();
+        ir["name"] = serde_json::json!("Shop");
+        ir["lineage"] = serde_json::json!({
+            "capable_aggregates": [{ "name": "Order", "storage_name": "order" }]
+        });
+        assert_eq!(select_backend(&ir, true), Ok(Backend::Memory));
+    }
+
+    #[test]
+    fn a_membership_aggregate_boots_on_memory() {
+        let mut ir = memory_domain();
+        ir["membership"] =
+            serde_json::json!({ "provider": "Membership", "aggregate": "Membership::Person" });
+        assert_eq!(select_backend(&ir, true), Ok(Backend::Memory));
+    }
+
+    #[test]
+    fn lineage_on_postgres_boots() {
+        let mut ir = bound(&[("A", "PostgresEra")]);
+        ir["lineage"] = serde_json::json!({
+            "capable_aggregates": [{ "name": "A", "storage_name": "a" }]
+        });
+        assert_eq!(select_backend(&ir, false), Ok(Backend::TokioPostgres));
+    }
+
+    #[test]
+    fn an_unsupported_adapter_is_still_refused_before_a_backend_is_chosen() {
+        let err = select_backend(&bound(&[("A", "Heki")]), true).unwrap_err();
+        assert!(err.starts_with("rust/host only has a backend"), "{err}");
+    }
+}

data/rust/host/core/src/journal.rs

@@ -0,0 +1,126 @@
+//! The journal's data and names: what a domain's journal rows look like and how its relations are
+//! named. Free of any driver; the SQL that reads and writes them is `store::journal_sql`.
+
+use sha2::{Digest, Sha256};
+
+/// The kernel's cached "instances" output as of `ordinal`, which lets a replay skip the steps
+/// before it.
+#[derive(Clone)]
+pub struct Snapshot {
+    pub ordinal: i64,
+    pub seed: serde_json::Value,
+    /// One-time latch: false only for a snapshot written before saga
+    /// durability shipped, never a live signal about current saga state.
+    pub sagas_backfilled: bool,
+}
+
+/// One live saga/process-manager instance, as stored in `hecks_lambda_sagas`.
+#[derive(Clone)]
+pub struct SagaRow {
+    pub process_manager: String,
+    pub correlation: String,
+    pub state: String,
+    pub memory: serde_json::Value,
+    pub completed_compensations: serde_json::Value,
+}
+
+/// Which domain journal this binary writes as, and which era. Read from
+/// `HECKS_DOMAIN`/main.rs's boot-time mint decision, never computed here.
+pub struct LineageConfig {
+    pub domain: String,
+    /// `None` when lineage isn't provisioned for this domain (ADR 0034).
+    pub era: Option<i32>,
+    /// Aggregates mirrored into era-shaped head snapshots; `None` means all.
+    pub mirrored: Option<std::collections::BTreeSet<String>>,
+    /// How many lineage rows a commit lets build up past the last ledger seal before it seals
+    /// (`ledger::seal_due`); `None` leaves sealing to the operator tools.
+    pub seal_every: Option<i64>,
+}
+
+impl LineageConfig {
+    /// Whether `qualified_aggregate` is mirrored into the era-shaped head
+    /// snapshots.
+    pub fn mirrors(&self, qualified_aggregate: &str) -> bool {
+        self.mirrored
+            .as_ref()
+            .is_none_or(|capable| capable.contains(qualified_aggregate))
+    }
+}
+
+// `Naming.snake` is the one shared port (rust/codegen/src/hecks_naming.rs); the host reaches it
+// through here so both runtimes derive the same storage names.
+pub use crate::hecks_naming::snake;
+
+/// `aggregate.storage_name` ported from ir/aggregate.rb — demodulizes a
+/// qualified name like `"Banking::Customer"` to `"Customer"` before snaking it.
+pub fn storage_name(qualified_aggregate: &str) -> String {
+    let short = qualified_aggregate
+        .rsplit("::")
+        .next()
+        .unwrap_or(qualified_aggregate);
+    snake(short)
+}
+
+pub fn journal_table(domain: &str) -> String {
+    format!("hecks_journal_{}", snake(domain))
+}
+
+/// Postgres's NAMEDATALEN-1 limit — an identifier over this length is
+/// silently truncated, never refused, so two overlong names sharing a
+/// prefix would otherwise collide.
+pub const POSTGRES_IDENTIFIER_LIMIT: usize = 63;
+
+/// Same algorithm as `Lineage#qualified_name` (lineage.rb): 63-byte limit,
+/// SHA256 suffix over the full name, a cut that never splits a character, domain-qualified so
+/// two domains' storage names can't collide (ADR 0059).
+pub fn qualified_name(domain: &str, suffix: &str) -> String {
+    let full = format!("{}_{}", snake(domain), suffix);
+    if full.len() <= POSTGRES_IDENTIFIER_LIMIT {
+        return full;
+    }
+
+    let digest = format!("{:x}", Sha256::digest(full.as_bytes()));
+    let digest = &digest[0..8];
+    let mut keep = POSTGRES_IDENTIFIER_LIMIT - digest.len() - 1;
+    // Cut at the longest prefix of whole characters that fits, as the Ruby side does.
+    while !full.is_char_boundary(keep) {
+        keep -= 1;
+    }
+    format!("{}_{}", &full[0..keep], digest)
+}
+
+/// The era-shaped snapshot table of one aggregate's head at `era`.
+pub fn head_snapshot_table(domain: &str, qualified_aggregate: &str, era: i32) -> String {
+    qualified_name(
+        domain,
+        &format!(
+            "{}_head_snapshot_{}",
+            storage_name(qualified_aggregate),
+            era
+        ),
+    )
+}
+
+/// One `MutationRecord` from the kernel's JSON output, parsed generically
+/// since rust/host never links the kernel crate directly (ADR 0012).
+pub struct Mutation<'a> {
+    pub aggregate: &'a str,
+    pub id: &'a str,
+    pub operation: &'a str,
+    pub state: &'a serde_json::Value,
+}
+
+// Not wired into dispatch::handle's replay seed — overlaying translated
+// head state onto raw replayed steps would cause false "AlreadyExists" refusals.
+/// The head view of one aggregate, qualified by its domain (ADR 0059).
+pub fn head_view(domain: &str, storage_name: &str) -> String {
+    qualified_name(domain, &format!("{storage_name}_head"))
+}
+
+/// One row of `hecks_eras`, mirroring era_store.rb's `eras` shape.
+#[derive(Debug, Clone)]
+pub struct HeldEra {
+    pub ordinal: i32,
+    pub label: Option<String>,
+    pub watermark: Option<i64>,
+}