hecks 4.0.0 → 6.0.0

data/rust/host/src/{journal.rs → store/journal_sql.rs}

@@ -1,10 +1,12 @@
 //! Flat, domain-agnostic journal of every command this domain has ever
 //! accepted, replayed in full on each invocation rather than filtered (ADR 0018).
 
+pub use crate::journal::*;
 use anyhow::Context;
 use sha2::{Digest, Sha256};
 use tokio_postgres::{Client, GenericClient};
 
+/// Creates the journal, snapshot, saga and dead-letter tables a domain's journal needs, if absent.
 pub async fn ensure_schema(client: &Client) -> anyhow::Result<()> {
     client
         .batch_execute(
@@ -150,16 +152,6 @@ pub async fn load_steps_after<C: GenericClient>(
         .collect())
 }
 
-/// The kernel's cached "instances" output as of `ordinal`, used to skip a
-/// full replay from empty state.
-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,
-}
-
 /// The domain's cached snapshot, if one has ever been written. `None`
 /// before the first accepted command, when there's nothing to seed from yet.
 pub async fn load_snapshot<C: GenericClient>(client: &C) -> anyhow::Result<Option<Snapshot>> {
@@ -209,21 +201,17 @@ pub async fn save_snapshot<C: GenericClient>(
     Ok(())
 }
 
-/// One live saga/process-manager instance, as stored in `hecks_lambda_sagas`.
-pub struct SagaRow {
-    pub process_manager: String,
-    pub correlation: String,
-    pub state: String,
-    pub memory: serde_json::Value,
-    pub completed_compensations: serde_json::Value,
-}
-
 /// Every live saga instance for this domain, read once per invocation to
 /// seed the kernel's in-memory `sagas` map.
+///
+/// Ordered by key in byte order (`COLLATE "C"`), which is the order the memory store keeps its
+/// sagas in: the kernel echoes the sagas back in the order it was given them, so a table scan in
+/// heap order would make one command answer differently from one store to the next.
 pub async fn load_sagas<C: GenericClient>(client: &C) -> anyhow::Result<Vec<SagaRow>> {
     let rows = client
         .query(
-            "SELECT process_manager, correlation, state, memory, completed_compensations FROM hecks_lambda_sagas",
+            "SELECT process_manager, correlation, state, memory, completed_compensations FROM hecks_lambda_sagas \
+             ORDER BY process_manager COLLATE \"C\", correlation COLLATE \"C\"",
             &[],
         )
         .await?;
@@ -276,85 +264,12 @@ pub async fn delete_saga<C: GenericClient>(
     Ok(())
 }
 
-/// 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>>,
-}
-
-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.
-fn storage_name(qualified_aggregate: &str) -> String {
-    let short = qualified_aggregate
-        .rsplit("::")
-        .next()
-        .unwrap_or(qualified_aggregate);
-    snake(short)
-}
-
 /// Quotes a Postgres identifier `PG::Connection.quote_ident`-style —
 /// needed since table names can't be bound as query parameters.
 pub fn quote_ident(name: &str) -> String {
     format!("\"{}\"", name.replace('"', "\"\""))
 }
 
-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.
-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(crate) 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)
-}
-
-fn head_snapshot_table(domain: &str, qualified_aggregate: &str, era: i32) -> String {
-    qualified_name(
-        domain,
-        &format!(
-            "{}_head_snapshot_{}",
-            storage_name(qualified_aggregate),
-            era
-        ),
-    )
-}
-
 /// The highest era ordinal on file for `domain`, not a bare existence
 /// check — `hecks_eras` is append-only, so a stale checkout still has a row.
 pub async fn current_era(client: &Client, domain: &str) -> anyhow::Result<Option<i32>> {
@@ -367,15 +282,6 @@ pub async fn current_era(client: &Client, domain: &str) -> anyhow::Result<Option
     Ok(rows.first().map(|row| row.get(0)))
 }
 
-/// 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,
-}
-
 /// Mirrors `PostgresEra#append`'s two-step write: journal insert, then a
 /// head-snapshot upsert that never regresses on a stale/reordered write.
 pub async fn append_lineage_mutation<C: GenericClient>(
@@ -455,14 +361,8 @@ pub async fn append_lineage_mutation<C: GenericClient>(
     Ok(())
 }
 
-// Not wired into dispatch::handle's replay seed — overlaying translated
-// head state onto raw replayed steps would cause false "AlreadyExists" refusals.
-pub(crate) fn head_view(domain: &str, storage_name: &str) -> String {
-    qualified_name(domain, &format!("{storage_name}_head"))
-}
-
-/// Every row for one lineage-capable aggregate, already translated to its
-/// current shape (reads the same head view Ruby's `Adapters::Postgres` does).
+/// Every row for one lineage-capable aggregate in id byte order (the order Memory keeps),
+/// already translated to its current shape (the head view Ruby's `Adapters::Postgres` reads).
 pub async fn read_lineage_head_all<C: GenericClient>(
     client: &C,
     domain: &str,
@@ -471,7 +371,7 @@ pub async fn read_lineage_head_all<C: GenericClient>(
     let rows = client
         .query(
             &format!(
-                "SELECT id, state FROM {}",
+                "SELECT id, state FROM {} ORDER BY id COLLATE \"C\"",
                 quote_ident(&head_view(domain, storage_name))
             ),
             &[],
@@ -502,22 +402,12 @@ pub async fn read_lineage_head_by_id<C: GenericClient>(
     Ok(row.map(|r| r.get(0)))
 }
 
-/// One row of `hecks_eras`, mirroring era_store.rb's `eras` shape.
-#[derive(Debug, Clone)]
-pub struct HeldEra {
-    pub ordinal: i32,
-    pub hash: Option<String>,
-    pub label: Option<String>,
-    pub held_text: String,
-    pub watermark: Option<i64>,
-}
-
 /// Every held era for `domain`, each verified against its own digest — an
 /// edited `held_text` refuses loudly instead of silently reporting no drift.
 pub async fn held_eras<C: GenericClient>(client: &C, domain: &str) -> anyhow::Result<Vec<HeldEra>> {
     let rows = client
         .query(
-            "SELECT ordinal, hash, label, held_text, watermark, held_digest FROM hecks_eras \
+            "SELECT ordinal, label, held_text, watermark, held_digest FROM hecks_eras \
              WHERE domain = $1 ORDER BY ordinal",
             &[&domain],
         )
@@ -542,9 +432,7 @@ pub async fn held_eras<C: GenericClient>(client: &C, domain: &str) -> anyhow::Re
 
             Ok(HeldEra {
                 ordinal,
-                hash: row.get("hash"),
                 label: row.get("label"),
-                held_text,
                 watermark: row.get("watermark"),
             })
         })
@@ -611,6 +499,7 @@ mod lineage_tests {
             domain: "Ledger".to_string(),
             era: Some(2),
             mirrored: None,
+            seal_every: None,
         };
         let accepted = append_lineage_mutation(
             &client,
@@ -633,6 +522,7 @@ mod lineage_tests {
             domain: "Ledger".to_string(),
             era: Some(1),
             mirrored: None,
+            seal_every: None,
         };
         let refused = append_lineage_mutation(
             &client,
@@ -808,6 +698,7 @@ mod lineage_tests {
             domain: "Fixtures".to_string(),
             era: Some(1),
             mirrored: None,
+            seal_every: None,
         };
         client
             .batch_execute("CREATE TABLE IF NOT EXISTS hecks_journal_fixtures (ordinal bigserial PRIMARY KEY, era int NOT NULL, aggregate text NOT NULL, aggregate_id text NOT NULL, operation text NOT NULL, state jsonb)")
@@ -886,7 +777,7 @@ mod lineage_tests {
             &client,
             "ReviewOnFreeze",
             "Compliance",
-            "Compliance::AccountFreezeReview.Open",
+            "Compliance::Review.Open",
             &serde_json::json!({ "number": { "value": "acct-1" } }),
             "ResourceNotFoundException: function not found",
             3,
@@ -911,7 +802,7 @@ mod lineage_tests {
         let attempts: i32 = row.get(5);
         assert_eq!(policy, "ReviewOnFreeze");
         assert_eq!(target_domain, "Compliance");
-        assert_eq!(target_verb, "Compliance::AccountFreezeReview.Open");
+        assert_eq!(target_verb, "Compliance::Review.Open");
         assert_eq!(
             payload,
             serde_json::json!({ "number": { "value": "acct-1" } })
@@ -929,7 +820,10 @@ mod naming_vector_tests {
     // spec/fixtures/naming_vectors.json is asserted by spec/naming_vectors_spec.rb against
     // Naming.snake and Lineage#qualified_name, so a drift in either runtime fails a test.
     fn vectors() -> Value {
-        serde_json::from_str(include_str!("../../../spec/fixtures/naming_vectors.json")).unwrap()
+        serde_json::from_str(include_str!(
+            "../../../../spec/fixtures/naming_vectors.json"
+        ))
+        .unwrap()
     }
 
     fn table(section: &str) -> Vec<Value> {

data/rust/host/src/{mint.rs → store/mint.rs}

@@ -1,7 +1,7 @@
 //! Mints Postgres eras, porting `lib/hecks/adapters/driven/postgres_era/
 //! lineage/*.rb`'s SQL verbatim; this crate has no bluebook parser (ADR 0012).
 
-use crate::journal::quote_ident;
+use super::journal_sql::quote_ident;
 use crate::reference_transform;
 use crate::reference_validate;
 use crate::storage_shape;
@@ -11,7 +11,7 @@ use sha2::{Digest, Sha256};
 use tokio_postgres::GenericClient;
 
 fn journal_table(domain: &str) -> String {
-    format!("hecks_journal_{}", crate::journal::snake(domain))
+    format!("hecks_journal_{}", super::journal_sql::snake(domain))
 }
 
 fn sequence(domain: &str) -> String {
@@ -25,15 +25,15 @@ fn partition(domain: &str, era: i32) -> String {
 // Domain-qualified: two domains whose aggregate names snake_case to the
 // same storage_name would otherwise collide on the same relations (docs/decisions/0059).
 fn head_snapshot(domain: &str, storage_name: &str, era: i32) -> String {
-    crate::journal::qualified_name(domain, &format!("{storage_name}_head_snapshot_{era}"))
+    super::journal_sql::qualified_name(domain, &format!("{storage_name}_head_snapshot_{era}"))
 }
 
 fn matview(domain: &str, storage_name: &str, era: i32, label: &str) -> String {
-    crate::journal::qualified_name(domain, &format!("{storage_name}_lineage_{era}_{label}"))
+    super::journal_sql::qualified_name(domain, &format!("{storage_name}_lineage_{era}_{label}"))
 }
 
 fn head_view(domain: &str, storage_name: &str) -> String {
-    crate::journal::qualified_name(domain, &format!("{storage_name}_head"))
+    super::journal_sql::qualified_name(domain, &format!("{storage_name}_head"))
 }
 
 fn text_literal(text: &str) -> String {
@@ -175,7 +175,7 @@ impl BootDecision {
 }
 
 /// `held` must already be in ordinal order (as `journal::held_eras` returns it).
-pub fn decide_boot_action(held: &[crate::journal::HeldEra], my_label: &str) -> BootDecision {
+pub fn decide_boot_action(held: &[super::journal_sql::HeldEra], my_label: &str) -> BootDecision {
     if let Some(matching) = held
         .iter()
         .find(|held_era| held_era.label.as_deref() == Some(my_label))
@@ -688,7 +688,7 @@ fn names_by_era(current_name: &str, edges: &[&Edge]) -> (Vec<String>, Vec<String
     }
     let storage = current
         .iter()
-        .map(|name| crate::journal::snake(name))
+        .map(|name| super::journal_sql::snake(name))
         .collect();
     (current, storage)
 }
@@ -1337,7 +1337,7 @@ async fn mint_era_body<C: GenericClient>(
         anyhow::bail!("era {ordinal} of {domain} is already minted — nothing to do");
     }
 
-    let watermark = crate::journal::last_ordinal(client, domain).await?;
+    let watermark = super::journal_sql::last_ordinal(client, domain).await?;
     let digest = format!("{:x}", Sha256::digest(held_text.as_bytes()));
     client
         .execute(
@@ -1351,7 +1351,7 @@ async fn mint_era_body<C: GenericClient>(
 
     // Every held era's watermark, for `ancestor_tail_sql`'s cut — includes
     // the row just inserted, which bounds era `ordinal - 1`'s tail read.
-    let held = crate::journal::held_eras(client, domain).await?;
+    let held = super::journal_sql::held_eras(client, domain).await?;
     let watermarks: std::collections::HashMap<i32, Option<i64>> = held
         .iter()
         .map(|era| (era.ordinal, era.watermark))
@@ -1618,8 +1618,8 @@ mod tests {
             "state is nullable, for a delete tombstone"
         );
     }
+    use super::super::journal_sql as journal;
     use super::*;
-    use crate::journal;
     use tokio_postgres::NoTls;
 
     fn rule(name: &str, was: Option<&str>, expression: &str) -> EdgeAggregate {
@@ -1699,9 +1699,7 @@ mod tests {
     fn held(ordinal: i32, label: Option<&str>) -> journal::HeldEra {
         journal::HeldEra {
             ordinal,
-            hash: label.map(|_| "irrelevant".to_string()),
             label: label.map(str::to_string),
-            held_text: String::new(),
             watermark: None,
         }
     }
@@ -1848,6 +1846,7 @@ mod tests {
             domain: domain.to_string(),
             era: Some(1),
             mirrored: None,
+            seal_every: None,
         };
         journal::append_lineage_mutation(
             &client,
@@ -2610,6 +2609,7 @@ mod tests {
                 domain: domain.to_string(),
                 era: Some(1),
                 mirrored: None,
+                seal_every: None,
             };
             journal::append_lineage_mutation(
                 client,