Trusty: provenance library workspace (initial import)

crates/adapters/trusty-memory/Cargo.toml

@@ -0,0 +1,15 @@
+[package]
+name = "trusty-memory"
+version.workspace = true
+edition.workspace = true
+authors.workspace = true
+license.workspace = true
+repository.workspace = true
+rust-version.workspace = true
+description = "In-memory Store backend for Trusty. Reference implementation and test harness."
+
+[dependencies]
+trusty-store = { workspace = true }
+
+[dev-dependencies]
+trusty-store = { workspace = true, features = ["testing"] }

crates/adapters/trusty-memory/src/lib.rs

@@ -0,0 +1,135 @@
+//! In-memory [`Store`](trusty_store::Store) backend for Trusty.
+//!
+//! Reference implementation of the `Store` trait. Intended for tests, fuzzing,
+//! and conformance checks. Not suitable for persistent production use -- all data
+//! is lost when the process exits.
+
+#![deny(clippy::all)]
+
+use std::collections::{BTreeMap, HashMap};
+
+use trusty_store::{
+    KvCrossCheckReport, LastRow, RowInsert, Store, StoreResult, StoredRow, TipRow, TipUpsert,
+};
+
+#[derive(Clone, Default)]
+pub struct MemoryStore {
+    rows: BTreeMap<i64, StoredRow>,
+    next_id: i64,
+    tips_by_chain: HashMap<String, TipRow>,
+    tips_by_entity: HashMap<String, TipRow>,
+}
+
+impl MemoryStore {
+    pub fn new() -> Self {
+        Self::default()
+    }
+}
+
+impl Store for MemoryStore {
+    fn last_row(&self, entity_id: &str) -> StoreResult<Option<LastRow>> {
+        let last = self
+            .rows
+            .values()
+            .rev()
+            .find(|r| r.entity_id == entity_id && r.event_type != "BREAK" && r.row_hash.is_some())
+            .map(|r| LastRow {
+                row_hash: r.row_hash.clone().unwrap(),
+                sequence: r.sequence,
+            });
+        Ok(last)
+    }
+
+    fn insert_row(&mut self, row: &RowInsert) -> StoreResult<i64> {
+        self.next_id += 1;
+        let id = self.next_id;
+        let stored = StoredRow {
+            id,
+            entity_id: row.entity_id.clone(),
+            chain_id: row.chain_id.clone(),
+            event_type: row.event_type.clone(),
+            sequence: row.sequence,
+            prev_hash: row.prev_hash.clone(),
+            row_hash: row.row_hash.clone(),
+            anchor_hash: row.anchor_hash.clone(),
+            raw_payload: row.raw_payload.clone(),
+            detected_at: row.detected_at.clone(),
+            received_at: row.received_at.clone(),
+            source_url: row.source_url.clone(),
+            extraction_method: row.extraction_method.clone(),
+        };
+        self.rows.insert(id, stored);
+        Ok(id)
+    }
+
+    fn iter_chain<'a>(
+        &'a self,
+        entity_id: &str,
+    ) -> StoreResult<Box<dyn Iterator<Item = StoreResult<StoredRow>> + 'a>> {
+        let entity = entity_id.to_string();
+        let iter = self
+            .rows
+            .values()
+            .filter(move |r| r.entity_id == entity)
+            .cloned()
+            .map(Ok);
+        Ok(Box::new(iter))
+    }
+
+    fn get_tip(&self, chain_id: &str) -> StoreResult<Option<TipRow>> {
+        Ok(self.tips_by_chain.get(chain_id).cloned())
+    }
+
+    fn get_tip_for_entity(&self, entity_id: &str) -> StoreResult<Option<TipRow>> {
+        Ok(self.tips_by_entity.get(entity_id).cloned())
+    }
+
+    fn set_tip(&mut self, tip: &TipUpsert) -> StoreResult<()> {
+        let row = TipRow {
+            entity_id: tip.entity_id.clone(),
+            chain_id: tip.chain_id.clone(),
+            current_tip_hash: tip.current_tip_hash.clone(),
+            updated_at: String::new(),
+        };
+        self.tips_by_chain.insert(tip.chain_id.clone(), row.clone());
+        self.tips_by_entity.insert(tip.entity_id.clone(), row);
+        Ok(())
+    }
+
+    fn kv_cross_check(&self) -> StoreResult<KvCrossCheckReport> {
+        let kv1 = self.rows.values().filter(|r| r.row_hash.is_some()).count();
+        let kv2 = self.tips_by_entity.len();
+        let mut mismatches: Vec<String> = Vec::new();
+        for (entity, tip) in &self.tips_by_entity {
+            if let Some(hash) = &tip.current_tip_hash {
+                let found = self.rows.values().any(|r| {
+                    r.row_hash.as_deref() == Some(hash.as_str()) && r.chain_id == tip.chain_id
+                });
+                if !found {
+                    mismatches.push(format!("tip_hash_not_in_rows: {}", entity));
+                }
+            }
+        }
+        Ok(KvCrossCheckReport {
+            ok: mismatches.is_empty(),
+            kv1_total_hashes: kv1,
+            kv2_total_entities: kv2,
+            entities_checked: kv2,
+            mismatches,
+        })
+    }
+
+    fn with_txn(
+        &mut self,
+        f: &mut dyn FnMut(&mut dyn Store) -> StoreResult<()>,
+    ) -> StoreResult<()> {
+        let snap = self.clone();
+        match f(self) {
+            Ok(()) => Ok(()),
+            Err(e) => {
+                *self = snap;
+                Err(e)
+            }
+        }
+    }
+}

crates/adapters/trusty-memory/tests/conformance.rs

@@ -0,0 +1,8 @@
+use trusty_memory::MemoryStore;
+use trusty_store::testing::run_conformance;
+
+#[test]
+fn memory_store_passes_conformance() {
+    let mut store = MemoryStore::new();
+    run_conformance(&mut store);
+}

crates/adapters/trusty-policy-audit/Cargo.toml

@@ -0,0 +1,19 @@
+[package]
+name = "trusty-policy-audit"
+version.workspace = true
+edition.workspace = true
+authors.workspace = true
+license.workspace = true
+repository.workspace = true
+rust-version.workspace = true
+description = "Trusty-backed PolicyAuditor adapter. Routes every PolicyEvent (Allow + Deny) into a trusty append-only chain so the policy decision trail is tamper-evident, replayable, and externally verifiable."
+
+[dependencies]
+trusty-policy = { workspace = true }
+trusty-sqlite = { workspace = true }
+serde = { workspace = true }
+serde_json = { workspace = true }
+
+[dev-dependencies]
+trusty-core = { workspace = true }
+tempfile = "3"

crates/adapters/trusty-policy-audit/src/lib.rs

@@ -0,0 +1,262 @@
+//! Trusty-backed `PolicyAuditor`.
+//!
+//! Closes the policy <-> chain loop: every `PolicyEvent` emitted by
+//! `trusty_policy::PolicyEngine::evaluate` (Allow OR Deny) is appended
+//! to a `Trusty` chain. The `entity_id` of the chain row is the policy
+//! scope (e.g. `agent.executor.v1`), so each registered FSM gets its
+//! own per-entity chain. Tamper-evidence, ordering, and external
+//! verifiability are inherited from `trusty-sqlite`.
+//!
+//! # Why a separate crate
+//!
+//! `trusty-policy` deliberately has no dependency on `trusty-core` /
+//! `trusty-sqlite` (library-not-platform rule). Wiring the two
+//! together lives here so consumers who want only the policy gate
+//! without an audit chain pay nothing.
+//!
+//! # Quickstart
+//!
+//! ```no_run
+//! use trusty_policy::{Fsm, PolicyEngine, ScopeKey, Transition};
+//! use trusty_sqlite::Trusty;
+//! use trusty_core::SecretKey;
+//! use trusty_policy_audit::TrustyAuditor;
+//!
+//! let trusty = Trusty::open_in_memory(SecretKey::new([7u8; 16])).unwrap();
+//! let auditor = TrustyAuditor::new(trusty);
+//!
+//! let scope = ScopeKey::new("agent.executor.v1");
+//! let mut fsm: Fsm<&'static str, &'static str> = Fsm::new("idle");
+//! fsm.allow(Transition::new("idle", "claim", "claimed"));
+//!
+//! let mut engine = PolicyEngine::new(auditor);
+//! engine.register(scope.clone(), fsm).unwrap();
+//! let _ = engine.evaluate(&scope, &"idle", &"claim", Some("agent_001"));
+//! // The chain row for entity_id="agent.executor.v1" now contains
+//! // the PolicyEvent JSON.
+//! ```
+
+#![deny(clippy::all)]
+
+use std::sync::{Arc, Mutex};
+
+use trusty_policy::{PolicyAuditor, PolicyEvent};
+use trusty_sqlite::Trusty;
+
+/// Source-URL marker stamped on every chained policy row. Consumers
+/// can filter by this to separate policy events from other domain
+/// events that may share a chain.
+pub const POLICY_SOURCE_URL: &str = "policy://trusty-policy/event";
+
+/// Extraction-method tag used when calling `Trusty::append_with_method`.
+/// Mirrors the existing trusty convention; consumers reading the chain
+/// can recognize policy rows by `extraction_method = "policy"`.
+pub const POLICY_EXTRACTION_METHOD: &str = "policy";
+
+/// `PolicyAuditor` that appends each `PolicyEvent` to a `Trusty` chain.
+/// The `Trusty` handle is held behind `Arc<Mutex<_>>` so the auditor
+/// is `Send + 'static` (the trait bound `PolicyEngine::new` requires)
+/// while still allowing the caller to share the same chain across
+/// other writers if needed.
+///
+/// On audit failure (rare: disk full, schema corruption) the auditor
+/// stores the most recent error in `last_error` and silently drops
+/// the row. Callers who need hard-stop semantics on audit failure
+/// should poll `last_error()` or wrap with their own checking layer.
+/// We deliberately do NOT panic: a misbehaving audit sink must not
+/// take down the policy engine during a deny path.
+pub struct TrustyAuditor {
+    trusty: Arc<Mutex<Trusty>>,
+    last_error: Arc<Mutex<Option<String>>>,
+}
+
+impl TrustyAuditor {
+    /// Wrap a `Trusty` handle. The auditor takes ownership; if you
+    /// need shared access, build the auditor with [`Self::from_shared`].
+    pub fn new(trusty: Trusty) -> Self {
+        Self {
+            trusty: Arc::new(Mutex::new(trusty)),
+            last_error: Arc::new(Mutex::new(None)),
+        }
+    }
+
+    /// Wrap an already-shared `Trusty` so the same chain can be
+    /// appended-to by other writers.
+    pub fn from_shared(trusty: Arc<Mutex<Trusty>>) -> Self {
+        Self {
+            trusty,
+            last_error: Arc::new(Mutex::new(None)),
+        }
+    }
+
+    /// Most recent audit error, if any. Cleared by [`Self::clear_error`].
+    pub fn last_error(&self) -> Option<String> {
+        self.last_error.lock().ok().and_then(|g| g.clone())
+    }
+
+    pub fn clear_error(&self) {
+        if let Ok(mut g) = self.last_error.lock() {
+            *g = None;
+        }
+    }
+
+    /// Borrow the inner shared handle. Useful for the consumer to
+    /// run integrity / verification queries after the engine has
+    /// emitted events.
+    pub fn shared(&self) -> Arc<Mutex<Trusty>> {
+        Arc::clone(&self.trusty)
+    }
+}
+
+impl PolicyAuditor for TrustyAuditor {
+    fn audit(&mut self, event: &PolicyEvent) {
+        // Serialize the event as JSON. The chain row's `data` column
+        // is the canonical record; downstream verifiers re-parse it.
+        let payload = match serde_json::to_value(event) {
+            Ok(v) => v,
+            Err(e) => {
+                self.record_error(format!("serialize PolicyEvent: {e}"));
+                return;
+            }
+        };
+
+        // entity_id = scope. One chain per FSM scope.
+        let entity_id = event.scope.as_str();
+
+        let mut guard = match self.trusty.lock() {
+            Ok(g) => g,
+            Err(p) => {
+                self.record_error(format!("trusty mutex poisoned: {p}"));
+                return;
+            }
+        };
+
+        if let Err(e) = guard.append_with_method(
+            entity_id,
+            &payload,
+            POLICY_SOURCE_URL,
+            POLICY_EXTRACTION_METHOD,
+        ) {
+            self.record_error(format!("append_with_method: {e}"));
+        }
+    }
+}
+
+impl TrustyAuditor {
+    fn record_error(&self, msg: String) {
+        if let Ok(mut g) = self.last_error.lock() {
+            *g = Some(msg);
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use trusty_core::SecretKey;
+    use trusty_policy::{Fsm, PolicyEngine, ScopeKey, Transition};
+
+    fn key() -> SecretKey {
+        SecretKey::new([7u8; 16])
+    }
+
+    fn pipeline_fsm() -> Fsm<&'static str, &'static str> {
+        let mut f = Fsm::new("idle");
+        f.allow(Transition::new("idle", "claim", "claimed"))
+            .allow(Transition::new("claimed", "execute", "running"))
+            .allow(Transition::new("running", "finish", "done"));
+        f
+    }
+
+    #[test]
+    fn allow_emits_chain_row() {
+        let trusty = Trusty::open_in_memory(key()).unwrap();
+        let auditor = TrustyAuditor::new(trusty);
+        let shared = auditor.shared();
+
+        let scope = ScopeKey::new("agent.executor.v1");
+        let mut engine: PolicyEngine<&'static str, &'static str> = PolicyEngine::new(auditor);
+        engine.register(scope.clone(), pipeline_fsm()).unwrap();
+
+        let r = engine.evaluate(&scope, &"idle", &"claim", Some("agent_001"));
+        assert!(r.is_allow());
+
+        // Read back the chain via the shared handle. raw_payload is
+        // the full envelope; the PolicyEvent JSON lives at .data.
+        let guard = shared.lock().unwrap();
+        let history = guard.history("agent.executor.v1", 100).unwrap();
+        assert_eq!(history.len(), 1, "exactly one chained policy row");
+        let raw = history[0].raw_payload.as_ref().expect("payload present");
+        let envelope: serde_json::Value = serde_json::from_str(raw).unwrap();
+        let payload = &envelope["data"];
+        assert_eq!(payload["scope"], "agent.executor.v1");
+        assert_eq!(payload["from"], "\"idle\"");
+        assert_eq!(payload["action"], "\"claim\"");
+        assert_eq!(payload["actor"], "agent_001");
+        assert!(payload["result"].get("Allow").is_some());
+    }
+
+    #[test]
+    fn deny_also_emits_chain_row() {
+        let trusty = Trusty::open_in_memory(key()).unwrap();
+        let auditor = TrustyAuditor::new(trusty);
+        let shared = auditor.shared();
+
+        let scope = ScopeKey::new("agent.executor.v1");
+        let mut engine: PolicyEngine<&'static str, &'static str> = PolicyEngine::new(auditor);
+        engine.register(scope.clone(), pipeline_fsm()).unwrap();
+
+        // illegal: idle -> finish is undeclared
+        let r = engine.evaluate(&scope, &"idle", &"finish", None);
+        assert!(!r.is_allow());
+
+        let guard = shared.lock().unwrap();
+        let history = guard.history("agent.executor.v1", 100).unwrap();
+        assert_eq!(history.len(), 1, "deny is also chained");
+        let envelope: serde_json::Value =
+            serde_json::from_str(history[0].raw_payload.as_ref().unwrap()).unwrap();
+        assert!(envelope["data"]["result"].get("Deny").is_some());
+    }
+
+    #[test]
+    fn separate_scopes_get_separate_chains() {
+        let trusty = Trusty::open_in_memory(key()).unwrap();
+        let auditor = TrustyAuditor::new(trusty);
+        let shared = auditor.shared();
+
+        let s_exec = ScopeKey::new("agent.executor.v1");
+        let s_audit = ScopeKey::new("agent.auditor.v1");
+
+        let mut engine: PolicyEngine<&'static str, &'static str> = PolicyEngine::new(auditor);
+        engine.register(s_exec.clone(), pipeline_fsm()).unwrap();
+        engine.register(s_audit.clone(), pipeline_fsm()).unwrap();
+
+        let _ = engine.evaluate(&s_exec, &"idle", &"claim", None);
+        let _ = engine.evaluate(&s_audit, &"idle", &"claim", None);
+
+        let guard = shared.lock().unwrap();
+        assert_eq!(guard.history("agent.executor.v1", 100).unwrap().len(), 1);
+        assert_eq!(guard.history("agent.auditor.v1", 100).unwrap().len(), 1);
+    }
+
+    #[test]
+    fn chain_is_tamper_evident() {
+        let trusty = Trusty::open_in_memory(key()).unwrap();
+        let auditor = TrustyAuditor::new(trusty);
+        let shared = auditor.shared();
+
+        let scope = ScopeKey::new("agent.executor.v1");
+        let mut engine: PolicyEngine<&'static str, &'static str> = PolicyEngine::new(auditor);
+        engine.register(scope.clone(), pipeline_fsm()).unwrap();
+
+        let _ = engine.evaluate(&scope, &"idle", &"claim", None);
+        let _ = engine.evaluate(&scope, &"claimed", &"finish", None); // deny
+        let _ = engine.evaluate(&scope, &"claimed", &"execute", None);
+        let _ = engine.evaluate(&scope, &"running", &"finish", None);
+
+        let guard = shared.lock().unwrap();
+        let report = guard.integrity().unwrap();
+        assert!(report.ok, "chain integrity must hold: {:?}", report);
+        assert_eq!(guard.history("agent.executor.v1", 100).unwrap().len(), 4);
+    }
+}

crates/adapters/trusty-policy-conditions/Cargo.toml

@@ -0,0 +1,18 @@
+[package]
+name = "trusty-policy-conditions"
+version.workspace = true
+edition.workspace = true
+authors.workspace = true
+license.workspace = true
+repository.workspace = true
+rust-version.workspace = true
+description = "Lets a declared policy FSM act as a trusty break Condition, so the rules for how data may legally change are authored as data and a deviation records which rule broke."
+
+[dependencies]
+trusty-core = { workspace = true }
+trusty-policy = { workspace = true }
+serde_json = { workspace = true }
+sha2 = { workspace = true }
+
+[dev-dependencies]
+trusty-sqlite = { workspace = true }

crates/adapters/trusty-policy-conditions/src/lib.rs

@@ -0,0 +1,528 @@
+//! Rules for how data may legally change, authored as data.
+//!
+//! # The idea
+//!
+//! Declare the transitions a datum is allowed to make. A compliant
+//! mutation is valid and the chain continues. A deviation records a
+//! **break naming the rule it violated**, and that break is signed,
+//! travels in an exported bundle, and can be acted on by anyone.
+//!
+//! Almost all of this already existed. [`Condition`] evaluates state at
+//! append time, [`BreakReason::PropertyViolated`] already carries a
+//! rule's name, and `export_bundle` always includes BREAK rows.
+//! Chain-break-as-event *was* this design. The one thing missing was
+//! that the rules were compiled in: [`Condition`] is a Rust trait, so a
+//! new rule meant a new build.
+//!
+//! The policy side had already solved that -- [`FsmSpec`] authored in
+//! TOML, guards named as strings, and [`GuardRegistry`] refusing to
+//! build on an unknown name. This crate is the join.
+//!
+//! # Guards see the payload
+//!
+//! The FSM is built over [`ConditionContext`], so a guard receives the
+//! **data being appended**, not just chain metadata. A rule can
+//! therefore be a real predicate over the value -- a threshold, a shape
+//! check, a comparison against the previous row -- rather than only a
+//! statement about the shape of the graph.
+//!
+//! # The envelope
+//!
+//! A row states the transition it is making, under `data.transition`:
+//!
+//! ```json
+//! { "transition": { "from": "draft", "action": "submit", "to": "review" } }
+//! ```
+//!
+//! The condition checks that transition is declared, that any guard on
+//! it passes, and that the stated destination is the one the FSM says it
+//! should be. That last check matters: without it a writer could name a
+//! legal transition and then record an arbitrary destination.
+//!
+//! # Rows that claim no transition
+//!
+//! By default they pass -- this condition judges rows that claim to be
+//! transitions, and a chain usually carries other traffic too.
+//! [`FsmCondition::strict`] reverses that, so an unlabelled row is
+//! itself a violation.
+//!
+//! Which is right depends on whether the chain is dedicated to the
+//! governed process. Getting it wrong in the lenient direction leaves a
+//! hole a writer can walk through by omitting a field, so **strict is
+//! the right default for a chain that governs one thing**, and the
+//! lenient default exists only because most chains do not.
+//!
+//! # The marker crosses the boundary
+//!
+//! A break's reason travels in the exported bundle, so a party holding
+//! only that bundle -- and no secret key, and no access to the machine
+//! that recorded it -- can ask `ProofBundle::stance()` and get one of
+//! three answers: clean, violated (with the rule named), or
+//! unverifiable. That third answer is the point: a bundle that cannot be
+//! checked must not read as clean.
+//!
+//! # One limitation, stated rather than discovered
+//!
+//! **A rule cannot be violated by the first row of a chain.**
+//! Break-as-event seals an existing chain, and at genesis there is
+//! nothing to seal, so the opening row is recorded whatever it claims.
+//! If the opening state must also be governed, check it before the
+//! first append -- the chain will not do it for you.
+//!
+//! # Why this crate and not another
+//!
+//! [`trusty_policy`] is deliberately substrate-free and does not depend
+//! on [`trusty_core`]. Putting this in either would give one of them a
+//! dependency it was designed not to have -- the same split, for the
+//! same reason, as `trusty-policy-audit`.
+
+#![deny(clippy::all)]
+
+use serde_json::Value;
+use trusty_core::conditions::{BreakReason, Condition, ConditionContext, ConditionOutcome};
+use sha2::{Digest, Sha256};
+use trusty_policy::{Fsm, FsmSpec, GuardRegistry, PolicyError};
+
+/// Where the transition envelope lives inside `data`.
+pub const TRANSITION_FIELD: &str = "transition";
+
+/// A declared state machine, acting as a break condition.
+pub struct FsmCondition {
+    fsm: Fsm<String, String, ConditionContext>,
+    rule: String,
+    /// The rule set's content hash, short form, when it was built from a
+    /// spec. Stamped into every break so a violation names the rule AND
+    /// the version of it that produced the verdict.
+    rule_hash: Option<String>,
+    strict: bool,
+}
+
+impl FsmCondition {
+    /// Build from an already-constructed FSM.
+    ///
+    /// `rule` is the name that appears in the recorded break. Make it
+    /// something an operator reading a chain six months later can look
+    /// up -- the whole point of `PropertyViolated` carrying a name is
+    /// that the break says *which* invariant broke.
+    pub fn new(fsm: Fsm<String, String, ConditionContext>, rule: impl Into<String>) -> Self {
+        Self {
+            fsm,
+            rule: rule.into(),
+            rule_hash: None,
+            strict: false,
+        }
+    }
+
+    /// The content hash of a rule set, hex, first 16 characters.
+    ///
+    /// Truncated because it travels inside every break reason and a full
+    /// digest would crowd out the part a human reads. 64 bits is ample
+    /// for telling two rule sets apart; it is not a security boundary,
+    /// since the full canonical form is what gets signed.
+    pub fn hash_of(spec: &FsmSpec) -> Result<String, PolicyError> {
+        let canonical = spec.canonical_json()?;
+        Ok(hex_short(&Sha256::digest(canonical.as_bytes())))
+    }
+
+    /// The rule set version this condition enforces, if it was built
+    /// from a spec.
+    pub fn rule_hash(&self) -> Option<&str> {
+        self.rule_hash.as_deref()
+    }
+
+    /// Build from a TOML spec, with guards resolved by name.
+    ///
+    /// A transition naming a guard the registry does not hold **refuses
+    /// to build**. That refusal is the feature: a policy that silently
+    /// runs without its guard is a policy that is not being enforced,
+    /// and it would look identical to one that is.
+    pub fn from_json(
+        json: &str,
+        registry: &mut GuardRegistry<ConditionContext>,
+        rule: impl Into<String>,
+    ) -> Result<Self, PolicyError> {
+        let spec = FsmSpec::from_json(json)?;
+        let rule_hash = Self::hash_of(&spec)?;
+        let (_scope, fsm) = spec.build_fsm_with_guards(registry)?;
+        let mut built = Self::new(fsm, rule);
+        built.rule_hash = Some(rule_hash);
+        Ok(built)
+    }
+
+    /// Treat a row that claims no transition as a violation.
+    ///
+    /// Correct when the chain is dedicated to the governed process.
+    /// Without it, omitting the envelope is a way around the rule.
+    pub fn strict(mut self) -> Self {
+        self.strict = true;
+        self
+    }
+
+    fn violated(&self, detail: &str) -> ConditionOutcome {
+        // The rule set version rides along, so a reader of the break can
+        // tell WHICH `doc.review` produced it. Without it a rule could be
+        // loosened after the fact and the old marker would still verify
+        // against a rule that no longer says what it said.
+        let name = match &self.rule_hash {
+            Some(h) => format!("{}@{h}", self.rule),
+            None => self.rule.clone(),
+        };
+        ConditionOutcome::Fail(BreakReason::PropertyViolated(format!("{name}:{detail}")))
+    }
+}
+
+/// The declared transition a row claims to be making.
+struct Declared {
+    from: String,
+    action: String,
+    to: String,
+}
+
+fn read_envelope(data: &Value) -> Option<Declared> {
+    let t = data.get(TRANSITION_FIELD)?;
+    Some(Declared {
+        from: t.get("from")?.as_str()?.to_string(),
+        action: t.get("action")?.as_str()?.to_string(),
+        to: t.get("to")?.as_str()?.to_string(),
+    })
+}
+
+impl Condition for FsmCondition {
+    fn name(&self) -> &'static str {
+        "FsmCondition"
+    }
+
+    fn evaluate(&self, ctx: &ConditionContext) -> ConditionOutcome {
+        let Some(declared) = read_envelope(&ctx.data) else {
+            return if self.strict {
+                // Distinguished from a malformed one on purpose: "you
+                // did not say" and "you said something impossible" are
+                // different operator problems.
+                self.violated("no-transition-declared")
+            } else {
+                ConditionOutcome::Pass
+            };
+        };
+
+        // Exclusions first, and they cannot be overridden -- the same
+        // ordering the permission model uses, for the same reason.
+        if let Some(why) = self.fsm.excluded_by(&declared.from, &declared.action) {
+            return self.violated(&format!("excluded:{why}"));
+        }
+
+        let Some(expected) = self.fsm.next_state(&declared.from, &declared.action) else {
+            return self.violated(&format!(
+                "undeclared-transition:{}--{}",
+                declared.from, declared.action
+            ));
+        };
+
+        if let Some(guard) = self.fsm.guard(&declared.from, &declared.action) {
+            if let Err(code) = guard.check(ctx) {
+                return self.violated(&format!("guard-rejected:{code}"));
+            }
+        }
+
+        if *expected != declared.to {
+            // A writer naming a legal transition and then recording a
+            // destination of its own choosing is exactly what this
+            // stops.
+            return self.violated(&format!(
+                "wrong-destination:{}--{}->{} expected {expected}",
+                declared.from, declared.action, declared.to
+            ));
+        }
+
+        ConditionOutcome::Pass
+    }
+}
+
+fn hex_short(digest: &[u8]) -> String {
+    digest.iter().take(8).map(|b| format!("{b:02x}")).collect()
+}
+
+/// The transition envelope, for a writer to embed in its payload.
+pub fn transition(from: &str, action: &str, to: &str) -> Value {
+    serde_json::json!({ TRANSITION_FIELD: { "from": from, "action": action, "to": to } })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    const SPEC: &str = r#"
+{
+  "scope": "doc.review.v1",
+  "initial": "draft",
+  "transitions": [
+    {
+      "from": "draft",
+      "action": "submit",
+      "to": "review"
+    },
+    {
+      "from": "review",
+      "action": "approve",
+      "to": "published",
+      "guard": "big_enough"
+    }
+  ]
+}
+"#;
+
+    pub(super) fn ctx(data: Value) -> ConditionContext {
+        ConditionContext {
+            entity_id: "e".into(),
+            chain_id: "c".into(),
+            sequence: 1,
+            stored_tip_hash: None,
+            computed_hash: None,
+            prev_hash: None,
+            last_sequence: Some(0),
+            source_url: String::new(),
+            extraction_method: "trusty".into(),
+            data,
+        }
+    }
+
+    fn registry() -> GuardRegistry<ConditionContext> {
+        let mut r = GuardRegistry::new();
+        r.insert("big_enough", |c: &ConditionContext| {
+            match c.data.get("size").and_then(Value::as_i64) {
+                Some(n) if n >= 10 => Ok(()),
+                Some(n) => Err(format!("too-small:{n}")),
+                None => Err("no-size".to_string()),
+            }
+        });
+        r
+    }
+
+    fn condition() -> FsmCondition {
+        FsmCondition::from_json(SPEC, &mut registry(), "doc.review").expect("build")
+    }
+
+    /// ConditionOutcome does not derive PartialEq, and adding a derive to
+    /// a core type to suit a test is the wrong direction of dependency.
+    fn passed(outcome: ConditionOutcome) -> bool {
+        matches!(outcome, ConditionOutcome::Pass)
+    }
+
+    fn reason(outcome: ConditionOutcome) -> String {
+        match outcome {
+            ConditionOutcome::Fail(BreakReason::PropertyViolated(r)) => r,
+            other => panic!("expected a property violation, got {other:?}"),
+        }
+    }
+
+    #[test]
+    fn a_declared_transition_passes() {
+        let outcome = condition().evaluate(&ctx(transition("draft", "submit", "review")));
+        assert!(
+            passed(outcome),
+            "a compliant mutation must leave the chain unbroken; that is what \
+             makes a break mean something"
+        );
+    }
+
+    #[test]
+    fn an_undeclared_transition_breaks_the_chain_and_names_the_rule() {
+        let outcome = condition().evaluate(&ctx(transition("draft", "publish", "published")));
+        let r = reason(outcome);
+        assert!(
+            r.starts_with("doc.review@") && r.contains(":undeclared-transition"),
+            "the break must name the rule that broke, or an operator reading \
+             the chain later learns only that something went wrong: {r}"
+        );
+    }
+
+    #[test]
+    fn naming_a_legal_transition_does_not_licence_an_arbitrary_destination() {
+        let outcome = condition().evaluate(&ctx(transition("draft", "submit", "published")));
+        let r = reason(outcome);
+        assert!(
+            r.contains("wrong-destination"),
+            "submit is legal from draft, but it goes to review; without this \
+             check a writer could name a legal transition and then record \
+             wherever it liked: {r}"
+        );
+    }
+
+    #[test]
+    fn a_guard_sees_the_payload_not_just_the_chain_metadata() {
+        let mut small = transition("review", "approve", "published");
+        small["size"] = Value::from(3);
+        let r = reason(condition().evaluate(&ctx(small)));
+        assert!(
+            r.contains("guard-rejected:too-small:3"),
+            "the guard must be able to judge the DATA being appended -- a rule \
+             that can only see chain metadata cannot express most invariants \
+             worth having: {r}"
+        );
+
+        let mut big = transition("review", "approve", "published");
+        big["size"] = Value::from(50);
+        assert!(passed(condition().evaluate(&ctx(big))));
+    }
+
+    #[test]
+    fn a_missing_guard_input_is_a_rejection_not_a_pass() {
+        let r = reason(condition().evaluate(&ctx(transition("review", "approve", "published"))));
+        assert!(
+            r.contains("guard-rejected:no-size"),
+            "absent evidence must not read as a satisfied guard, for the same \
+             reason absent policy is not permission: {r}"
+        );
+    }
+
+    #[test]
+    fn an_unregistered_guard_refuses_to_build() {
+        let mut empty = GuardRegistry::<ConditionContext>::new();
+        let built = FsmCondition::from_json(SPEC, &mut empty, "doc.review");
+        assert!(
+            built.is_err(),
+            "a policy that silently runs without its guard is a policy that is \
+             not being enforced, and it looks identical to one that is"
+        );
+    }
+
+    #[test]
+    fn an_unlabelled_row_passes_by_default_and_fails_under_strict() {
+        let plain = ctx(serde_json::json!({ "temperature": 21 }));
+        assert!(
+            passed(condition().evaluate(&plain)),
+            "most chains carry traffic this condition has no opinion about"
+        );
+
+        let r = reason(condition().strict().evaluate(&plain));
+        assert!(
+            r.contains("no-transition-declared"),
+            "on a chain dedicated to the governed process, omitting the \
+             envelope would otherwise be a way around the rule: {r}"
+        );
+    }
+
+    #[test]
+    fn a_malformed_envelope_is_reported_as_undeclared_not_as_absent() {
+        let half = ctx(serde_json::json!({ TRANSITION_FIELD: { "from": "draft" } }));
+        assert!(
+            passed(condition().evaluate(&half)),
+            "an envelope missing required fields is not a transition claim at \
+             all; under strict it fails, and the two cases are distinguished \
+             because 'you did not say' and 'you said something impossible' are \
+             different operator problems"
+        );
+        let r = reason(condition().strict().evaluate(&half));
+        assert!(r.contains("no-transition-declared"), "{r}");
+    }
+
+    #[test]
+    fn an_exclusion_cannot_be_overridden_by_a_declared_transition() {
+        let mut fsm: Fsm<String, String, ConditionContext> = Fsm::new("draft".to_string());
+        fsm.allow(trusty_policy::Transition::new(
+            "draft".to_string(),
+            "submit".to_string(),
+            "review".to_string(),
+        ));
+        fsm.exclude("submit".to_string(), "frozen-for-audit");
+        let cond = FsmCondition::new(fsm, "doc.review");
+
+        let r = reason(cond.evaluate(&ctx(transition("draft", "submit", "review"))));
+        assert!(
+            r.contains("excluded:frozen-for-audit"),
+            "exclusions are checked before the transition is looked up, so a \
+             declared transition cannot reopen what an exclusion shut -- the \
+             same ordering the permission model uses: {r}"
+        );
+    }
+}
+
+#[cfg(test)]
+mod rule_version_tests {
+    use super::*;
+
+    const NARROW: &str = r#"
+{
+  "scope": "doc.review.v1",
+  "initial": "draft",
+  "transitions": [
+    { "from": "draft", "action": "submit", "to": "review" }
+  ]
+}
+"#;
+
+    const LOOSENED: &str = r#"
+{
+  "scope": "doc.review.v1",
+  "initial": "draft",
+  "transitions": [
+    { "from": "draft", "action": "submit", "to": "review" },
+    { "from": "draft", "action": "publish", "to": "published" }
+  ]
+}
+"#;
+
+    fn built(spec: &str) -> FsmCondition {
+        FsmCondition::from_json(spec, &mut GuardRegistry::new(), "doc.review")
+            .expect("build")
+    }
+
+    #[test]
+    fn loosening_the_rule_changes_the_version_the_break_cites() {
+        let narrow = built(NARROW);
+        let loosened = built(LOOSENED);
+        assert_ne!(
+            narrow.rule_hash(),
+            loosened.rule_hash(),
+            "a rule set that can be widened without changing its version is a \
+             rule set a violation marker cannot honestly cite -- loosen it \
+             after the fact and the old marker still appears to hold"
+        );
+    }
+
+    #[test]
+    fn the_same_rule_set_always_yields_the_same_version() {
+        assert_eq!(
+            built(NARROW).rule_hash(),
+            built(NARROW).rule_hash(),
+            "a version that varied between processes would make every marker \
+             uncomparable, which is worse than having no version at all"
+        );
+    }
+
+    #[test]
+    fn a_hand_built_fsm_has_no_version_rather_than_a_made_up_one() {
+        let mut fsm: Fsm<String, String, ConditionContext> = Fsm::new("draft".to_string());
+        fsm.allow(trusty_policy::Transition::new(
+            "draft".to_string(),
+            "submit".to_string(),
+            "review".to_string(),
+        ));
+        let cond = FsmCondition::new(fsm, "doc.review");
+        assert_eq!(
+            cond.rule_hash(),
+            None,
+            "an FSM assembled in Rust has no canonical document to hash, and \
+             inventing a version for it would be a claim nobody can check"
+        );
+    }
+
+    #[test]
+    fn a_versionless_rule_still_names_itself_in_the_break() {
+        let mut fsm: Fsm<String, String, ConditionContext> = Fsm::new("draft".to_string());
+        fsm.allow(trusty_policy::Transition::new(
+            "draft".to_string(),
+            "submit".to_string(),
+            "review".to_string(),
+        ));
+        let outcome = FsmCondition::new(fsm, "doc.review")
+            .evaluate(&super::tests::ctx(transition("draft", "publish", "gone")));
+        match outcome {
+            ConditionOutcome::Fail(BreakReason::PropertyViolated(r)) => assert!(
+                r.starts_with("doc.review:"),
+                "no version is not the same as no name; the rule must still \
+                 identify itself: {r}"
+            ),
+            other => panic!("expected a violation, got {other:?}"),
+        }
+    }
+}

crates/adapters/trusty-policy-conditions/tests/enforced.rs

@@ -0,0 +1,303 @@
+//! Does a declared rule actually break a real chain?
+//!
+//! The unit tests check the condition's verdict. These check that the
+//! verdict reaches the chain: that a compliant mutation leaves it
+//! unbroken, a deviation records a break, and the break says which rule
+//! broke rather than merely that something did.
+
+use trusty_core::{Ed25519Signer, SecretKey, Stance};
+use trusty_policy::GuardRegistry;
+use trusty_policy_conditions::{transition, FsmCondition};
+use trusty_sqlite::Trusty;
+
+const SPEC: &str = r#"
+{
+  "scope": "doc.review.v1",
+  "initial": "draft",
+  "transitions": [
+    {
+      "from": "draft",
+      "action": "submit",
+      "to": "review"
+    },
+    {
+      "from": "review",
+      "action": "approve",
+      "to": "published",
+      "guard": "big_enough"
+    }
+  ]
+}
+"#;
+
+fn store() -> Trusty {
+    let mut registry = GuardRegistry::new();
+    registry.insert("big_enough", |c: &trusty_core::ConditionContext| {
+        match c.data.get("size").and_then(serde_json::Value::as_i64) {
+            Some(n) if n >= 10 => Ok(()),
+            Some(n) => Err(format!("too-small:{n}")),
+            None => Err("no-size".to_string()),
+        }
+    });
+    let condition =
+        FsmCondition::from_json(SPEC, &mut registry, "doc.review").expect("build the rule");
+
+    // The integrity defaults PLUS the declared rule: a policy rule is an
+    // addition to tamper detection, never a replacement for it.
+    let mut conditions = trusty_core::conditions::default_conditions();
+    conditions.push(Box::new(condition));
+    Trusty::open_in_memory_with_conditions(SecretKey::new([9u8; 16]), conditions)
+        .expect("store")
+}
+
+/// Every recorded break reason, in order.
+///
+/// Read through `breaks_since`, not from the exported bundle: a BREAK
+/// row's reason lives in the `old_value`/`new_value` columns, and
+/// `BundleRow` carries neither. So the reason does **not** travel to a
+/// remote party today -- see the sibling issue on making the marker
+/// actionable across a boundary.
+fn break_reasons(trusty: &Trusty, entity: &str) -> Vec<String> {
+    trusty
+        .breaks_since(entity, None)
+        .expect("breaks")
+        .into_iter()
+        .map(|b| b.break_reason)
+        .collect()
+}
+
+/// Establish the chain with a compliant row.
+///
+/// A rule cannot be violated by the FIRST row of a chain: break-as-event
+/// seals an existing chain, and at genesis there is nothing to seal. So
+/// every test that wants to observe a violation must first give the
+/// chain something to break.
+fn genesis(trusty: &mut Trusty, signer: &Ed25519Signer, entity: &str) {
+    trusty
+        .append_signed(
+            entity,
+            &transition("draft", "submit", "review"),
+            "test://",
+            signer,
+        )
+        .expect("genesis");
+}
+
+#[test]
+fn a_compliant_mutation_leaves_the_chain_unbroken() {
+    let mut trusty = store();
+    let signer = Ed25519Signer::generate();
+
+    trusty
+        .append_signed(
+            "doc:1",
+            &transition("draft", "submit", "review"),
+            "test://",
+            &signer,
+        )
+        .expect("append");
+
+    assert!(
+        break_reasons(&trusty, "doc:1").is_empty(),
+        "a declared transition must pass; if compliant data broke the chain, \
+         a break would stop meaning anything"
+    );
+    assert!(
+        trusty
+            .export_bundle("doc:1", None, None)
+            .expect("export")
+            .verify_public()
+            .continuous,
+        "and the chain must read as continuous"
+    );
+}
+
+#[test]
+fn an_undeclared_mutation_breaks_the_chain_and_the_break_names_the_rule() {
+    let mut trusty = store();
+    let signer = Ed25519Signer::generate();
+
+    trusty
+        .append_signed(
+            "doc:2",
+            &transition("draft", "submit", "review"),
+            "test://",
+            &signer,
+        )
+        .expect("first");
+
+    // draft --publish--> published is not declared anywhere.
+    trusty
+        .append_signed(
+            "doc:2",
+            &transition("draft", "publish", "published"),
+            "test://",
+            &signer,
+        )
+        .expect("second");
+
+    let reasons = break_reasons(&trusty, "doc:2");
+    assert_eq!(
+        reasons.len(),
+        1,
+        "the deviation must be recorded as an event, not rejected silently -- \
+         chain-break-as-event is what makes the violation evidence rather than \
+         an error somebody's log swallowed; got {reasons:?}"
+    );
+    assert!(
+        reasons[0].starts_with("PROPERTY_VIOLATED:doc.review@")
+            && reasons[0].contains(":undeclared-transition"),
+        "the break must carry the rule's name, so an operator reading this \
+         chain in six months learns WHICH invariant broke; got {}",
+        reasons[0]
+    );
+}
+
+#[test]
+fn a_guard_rejection_names_the_guard_and_its_reason() {
+    let mut trusty = store();
+    let signer = Ed25519Signer::generate();
+
+    genesis(&mut trusty, &signer, "doc:3");
+    let mut small = transition("review", "approve", "published");
+    small["size"] = serde_json::Value::from(2);
+    trusty
+        .append_signed("doc:3", &small, "test://", &signer)
+        .expect("append");
+
+    let reasons = break_reasons(&trusty, "doc:3");
+    assert!(
+        reasons
+            .iter()
+            .any(|r| r.contains("guard-rejected:too-small:2")),
+        "a rule over the DATA must be able to break the chain and say what it \
+         saw; a break that only said 'guard failed' would send someone back to \
+         the source to find out which one; got {reasons:?}"
+    );
+}
+
+#[test]
+fn the_marker_crosses_the_boundary_carrying_the_rule_name() {
+    let mut trusty = store();
+    let signer = Ed25519Signer::generate();
+
+    genesis(&mut trusty, &signer, "doc:4");
+    trusty
+        .append_signed(
+            "doc:4",
+            &transition("draft", "publish", "published"),
+            "test://",
+            &signer,
+        )
+        .expect("append");
+
+    // Everything below is what a REMOTE party can do: it holds the
+    // bundle and no secret key, and never talks to the machine that
+    // recorded the break.
+    let bundle = trusty.export_bundle("doc:4", None, None).expect("export");
+
+    let violations = bundle.violations();
+    assert_eq!(
+        violations.len(),
+        1,
+        "the violation must be readable off the bundle alone; a marker only \
+         the writer can read is not something anyone else can act on"
+    );
+    assert_eq!(
+        violations[0]
+            .rule
+            .as_deref()
+            .map(|r| r.split('@').next().unwrap_or(r)),
+        Some("doc.review"),
+        "and it must name the RULE, not merely report that something broke. \
+         Refuse, quarantine or inspect are different decisions and the rule is \
+         what tells them apart; got {:?}",
+        violations[0]
+    );
+
+    match bundle.stance() {
+        Stance::Violated { violations } => {
+            assert_eq!(violations.len(), 1, "one break, one violation")
+        }
+        other => panic!("expected a violation stance, got {other:?}"),
+    }
+    assert!(
+        !bundle.stance().is_clean(),
+        "a datum carrying a signed violation must never be waved through"
+    );
+}
+
+#[test]
+fn a_clean_bundle_reads_as_clean_and_a_tampered_one_does_not() {
+    let mut trusty = store();
+    let signer = Ed25519Signer::generate();
+    genesis(&mut trusty, &signer, "doc:6");
+
+    let clean = trusty.export_bundle("doc:6", None, None).expect("export");
+    assert_eq!(
+        clean.stance(),
+        Stance::Clean,
+        "a compliant chain must read as clean, or the marker means nothing"
+    );
+
+    // The same bundle, edited after export.
+    let mut forged = clean.clone();
+    for row in forged.rows.iter_mut() {
+        if let Some(payload) = row.raw_payload.as_mut() {
+            *payload = payload.replace("submit", "publish");
+        }
+    }
+    match forged.stance() {
+        Stance::Unverifiable { .. } => {}
+        other => panic!(
+            "a bundle that no longer matches its signatures must report \
+             Unverifiable -- counting zero violations and looking spotless is \
+             exactly the failure the third answer exists to prevent; got {other:?}"
+        ),
+    }
+    assert!(
+        !forged.stance().is_clean(),
+        "and unverifiable is not a permit"
+    );
+}
+
+#[test]
+fn a_break_with_no_rule_is_still_reported() {
+    // Tamper detection and sequence gaps are real breaks with no
+    // invariant to name. They must still surface, with rule: None,
+    // rather than being filtered out for lacking a name.
+    let v = trusty_core::Violation {
+        entity_id: "e".into(),
+        chain_id: "c".into(),
+        rule: None,
+        reason: "TAMPER_DETECTED".into(),
+    };
+    assert!(
+        v.rule.is_none() && !v.reason.is_empty(),
+        "a break without a rule name is still a break, and dropping it would \
+         hide the most serious kind"
+    );
+}
+
+#[test]
+fn a_declared_transition_to_the_wrong_destination_still_breaks() {
+    let mut trusty = store();
+    let signer = Ed25519Signer::generate();
+
+    genesis(&mut trusty, &signer, "doc:5");
+    trusty
+        .append_signed(
+            "doc:5",
+            &transition("draft", "submit", "published"),
+            "test://",
+            &signer,
+        )
+        .expect("append");
+
+    let reasons = break_reasons(&trusty, "doc:5");
+    assert!(
+        reasons.iter().any(|r| r.contains("wrong-destination")),
+        "submit is legal from draft, but it goes to review. Without this the \
+         rule would check the move and ignore where it landed; got {reasons:?}"
+    );
+}

crates/adapters/trusty-policy-postgres/Cargo.toml

@@ -0,0 +1,20 @@
+[package]
+name = "trusty-policy-postgres"
+version.workspace = true
+edition.workspace = true
+authors.workspace = true
+license.workspace = true
+repository.workspace = true
+rust-version.workspace = true
+description = "Compiles a trusty-policy Grant into a Postgres row-level-security decision. Grants are rows and the policy is static, so no SQL is ever built from a grant's contents."
+
+[dependencies]
+trusty-policy = { workspace = true }
+postgres = { workspace = true }
+serde_json = { workspace = true }
+sha2 = { workspace = true }
+hex = { workspace = true }
+thiserror = { workspace = true }
+
+[features]
+default = []

crates/adapters/trusty-policy-postgres/examples/emit_ddl.rs

@@ -0,0 +1,78 @@
+//! Print the permission model's schema as a plain `.sql` migration.
+//!
+//! A consumer whose migrations are files rather than a Rust `open()`
+//! call — Supabase, sqlx, plain psql — needs the same DDL as text.
+//! Emitting it from the same constants the library applies is the point:
+//! two hand-maintained copies of an authorisation schema will diverge,
+//! and the divergence will be discovered by something going wrong.
+//!
+//! ```text
+//! cargo run -p trusty-policy-postgres --example emit_ddl > 0001_permission_model.sql
+//! ```
+//!
+//! Pass a table and its scope column to additionally emit the policies
+//! that put that table under enforcement:
+//!
+//! ```text
+//! cargo run -p trusty-policy-postgres --example emit_ddl -- public.calendar resource_scope
+//! ```
+
+use trusty_policy_postgres::permits::DDL_FUNCTIONS;
+use trusty_policy_postgres::schema::{DDL_SCHEMA_VERSION_UPSERT, DDL_V1, SCHEMA_VERSION};
+use trusty_policy_postgres::store::policy_statements;
+
+fn main() {
+    println!("-- Generated by `cargo run -p trusty-policy-postgres --example emit_ddl`.");
+    println!("-- Source of truth is trusty-policy-postgres; edit there, regenerate here.");
+    println!("-- Applying this by hand and by GrantStore::open must agree, so do not");
+    println!("-- edit this file directly.");
+    println!();
+
+    for stmt in DDL_V1 {
+        println!("{};", stmt.trim());
+        println!();
+    }
+
+    for stmt in DDL_FUNCTIONS {
+        println!("{};", stmt.trim());
+        println!();
+    }
+
+    // The library upserts this with a bind parameter; a file has no
+    // parameters, so the version is inlined. It is a constant, not
+    // input.
+    println!(
+        "{};",
+        DDL_SCHEMA_VERSION_UPSERT
+            .trim()
+            .replace("$1", &format!("'{SCHEMA_VERSION}'"))
+    );
+    println!();
+
+    let args: Vec<String> = std::env::args().skip(1).collect();
+    match args.as_slice() {
+        [] => {
+            println!("-- No table given, so no policies were emitted.");
+            println!("-- Installing this schema protects nothing on its own: a table is");
+            println!("-- guarded only once it has ENABLE + FORCE ROW LEVEL SECURITY and the");
+            println!("-- four policies. Re-run with a table and its scope column, e.g.");
+            println!("--   ... --example emit_ddl -- public.calendar resource_scope");
+        }
+        [table, column] => match policy_statements(table, column) {
+            Ok(stmts) => {
+                println!("-- Enforcement for {table}({column}).");
+                for stmt in stmts {
+                    println!("{stmt}");
+                }
+            }
+            Err(e) => {
+                eprintln!("error: {e}");
+                std::process::exit(1);
+            }
+        },
+        _ => {
+            eprintln!("usage: emit_ddl [<schema.table> <scope_column>]");
+            std::process::exit(2);
+        }
+    }
+}

crates/adapters/trusty-policy-postgres/src/lib.rs

@@ -0,0 +1,282 @@
+//! Compiles a [`trusty_policy::Grant`] into a decision Postgres enforces.
+//!
+//! # The problem this exists to solve
+//!
+//! `trusty-policy` decides in Rust. Postgres decides in SQL. When those
+//! two answers disagree, the database wins and nobody is told. The
+//! permission model closes that by making one definition serve both:
+//! a grant *compiles* to a row-level-security policy. [`Tier`] was
+//! defined as the database's four verbs for exactly this reason, so the
+//! compilation needs no translation layer -- and a translation layer is
+//! where the two answers drift apart.
+//!
+//! # Grants are rows; the policy is static
+//!
+//! One `CREATE POLICY` per (table, verb), written once:
+//!
+//! ```sql
+//! CREATE POLICY calendar_read ON calendar FOR SELECT
+//!   USING (trusty_policy.permits(
+//!            current_setting('trusty.subject', true), 'read', resource_scope));
+//! ```
+//!
+//! Issuing a grant is then a parameterized `INSERT`, and revoking one is
+//! an `UPDATE`. **No SQL is ever built from a grant's contents**, so a
+//! scope string can never become syntax. The alternative -- a
+//! `CREATE POLICY` per grant -- would require exactly that, and would
+//! introduce the first dynamic SQL into a workspace where every
+//! statement today is a static literal with `$1` placeholders.
+//!
+//! # What compiles, and what does not
+//!
+//! `scope`, `tier`, `excludes`, `expires_at` and `acts_for` reach the
+//! database. `limits` -- rate, irreversible budget, dead man -- has no
+//! RLS analogue and stays in [`trusty_policy::PolicyEngine`]. That gap
+//! is reported, never silent: see [`CompilationReport`]. A compiler that
+//! quietly drops a rate limit is worse than one that refuses.
+//!
+//! # Why a separate crate
+//!
+//! `trusty-policy` deliberately has no substrate. `CREATE POLICY` and
+//! `current_setting` are Postgres dialect, so putting them in the engine
+//! would give a substrate-free crate a substrate. Same split, and the
+//! same reason, as `trusty-policy-audit`.
+
+#![deny(clippy::all)]
+
+pub mod permits;
+pub mod schema;
+pub mod store;
+
+use sha2::{Digest, Sha256};
+use trusty_policy::{Grant, Tier};
+
+pub use permits::{
+    DDL_ENSURE_PRINCIPAL, DDL_FUNCTIONS, DDL_REINSTATE_PRINCIPAL, DDL_PERMITS, MAX_DELEGATION_DEPTH,
+    SQL_RECONCILE_PRINCIPALS,
+};
+pub use schema::{DDL_V1, SCHEMA_NAME, SCHEMA_VERSION};
+pub use store::{policy_statements, GrantStore, PolicySession, SUBJECT_SETTING};
+
+/// A grant's identity: the SHA-256 of its RFC 8785 canonical JSON, hex
+/// encoded.
+///
+/// Content-addressed on purpose. Issuing the same grant twice is
+/// idempotent rather than duplicative, and the id is precisely the bytes
+/// a signature over the grant would cover -- so the row, the id and the
+/// signed artifact can never disagree about what was granted.
+#[derive(Debug, Clone, PartialEq, Eq, Hash)]
+pub struct GrantId(String);
+
+impl GrantId {
+    /// Derive the id from a grant's canonical form.
+    pub fn of(grant: &Grant) -> Result<Self, PolicyPgError> {
+        let canonical = grant
+            .canonical_json()
+            .map_err(|e| PolicyPgError::Canonicalise(e.to_string()))?;
+        Ok(Self::of_canonical(&canonical))
+    }
+
+    /// Derive the id from canonical JSON that is already in hand.
+    pub fn of_canonical(canonical: &str) -> Self {
+        let digest = Sha256::digest(canonical.as_bytes());
+        Self(hex::encode(digest))
+    }
+
+    pub fn as_str(&self) -> &str {
+        &self.0
+    }
+}
+
+impl std::fmt::Display for GrantId {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.write_str(&self.0)
+    }
+}
+
+/// What a grant carried that the database will not be enforcing.
+///
+/// Returned alongside every issued grant so a caller cannot mistake
+/// partial compilation for total. Every field named here is still
+/// enforced -- by [`trusty_policy::PolicyEngine`], in the application --
+/// but *not* by Postgres, and a caller relying on the database alone
+/// would be relying on something that is not there.
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub struct CompilationReport {
+    /// Names of grant fields that did not reach the database.
+    pub uncompiled: Vec<&'static str>,
+}
+
+impl CompilationReport {
+    /// Build the report for a grant.
+    pub fn of(grant: &Grant) -> Self {
+        let mut uncompiled = Vec::new();
+        if grant.limits.rate_per_min.is_some() {
+            uncompiled.push("limits.rate_per_min");
+        }
+        if grant.limits.irreversible_budget.is_some() {
+            uncompiled.push("limits.irreversible_budget");
+        }
+        if grant.limits.dead_man_secs.is_some() {
+            uncompiled.push("limits.dead_man_secs");
+        }
+        Self { uncompiled }
+    }
+
+    /// True when every field of the grant reached the database, so the
+    /// database alone is a sufficient enforcer of it.
+    pub fn is_total(&self) -> bool {
+        self.uncompiled.is_empty()
+    }
+}
+
+/// The lowercase token a [`Tier`] is stored and compared as.
+///
+/// Distinct from [`Tier::sql_verb`], which gives the SQL keyword. The
+/// two are 1:1 -- that is the whole design -- but they are not the same
+/// string, and conflating them would put `SELECT` in a data column.
+pub fn tier_token(tier: Tier) -> &'static str {
+    match tier {
+        Tier::Read => "read",
+        Tier::Append => "append",
+        Tier::Update => "update",
+        Tier::Delete => "delete",
+    }
+}
+
+#[derive(Debug, thiserror::Error)]
+pub enum PolicyPgError {
+    #[error("postgres: {0}")]
+    Postgres(#[from] postgres::Error),
+    #[error("could not canonicalise the grant: {0}")]
+    Canonicalise(String),
+    #[error(
+        "no relation named {0:?} exists, so enabling row-level security on it \
+         would silently protect nothing"
+    )]
+    UnknownRelation(String),
+    #[error(
+        "no principal named {0:?} is registered, and a key bound to nobody is          a key nothing can revoke"
+    )]
+    UnknownPrincipal(String),
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use trusty_policy::Limits;
+
+    fn grant() -> Grant {
+        Grant {
+            why: Some("Sam's scheduling agent may propose, never book.".into()),
+            subject: "agent:01J".into(),
+            acts_for: Some("user:01H".into()),
+            scope: "board:9f2/calendar".into(),
+            tier: Tier::Append,
+            excludes: vec!["board:9f2/calendar/private".into()],
+            limits: Limits::default(),
+            expires_at: 1_788_000_000,
+        }
+    }
+
+    #[test]
+    fn the_id_is_the_hash_of_the_canonical_form() {
+        let g = grant();
+        let canonical = g.canonical_json().expect("canonical form");
+        assert_eq!(
+            GrantId::of(&g).expect("id"),
+            GrantId::of_canonical(&canonical),
+            "the id must be derivable from the canonical bytes alone, or a \
+             verifier holding only the signed artifact could not name the row"
+        );
+    }
+
+    #[test]
+    fn issuing_the_same_grant_twice_yields_one_id() {
+        assert_eq!(
+            GrantId::of(&grant()).expect("id"),
+            GrantId::of(&grant()).expect("id"),
+            "a content-addressed id makes re-issuing idempotent rather than \
+             quietly accumulating duplicate permissions"
+        );
+    }
+
+    #[test]
+    fn changing_why_changes_the_id() {
+        let mut other = grant();
+        other.why = Some("a different reason entirely".into());
+        assert_ne!(
+            GrantId::of(&grant()).expect("id"),
+            GrantId::of(&other).expect("id"),
+            "the justification is inside the hash, not beside it: a grant \
+             whose stated reason can be edited without changing its identity \
+             is missing the half an auditor asks about"
+        );
+    }
+
+    #[test]
+    fn a_grant_without_limits_compiles_totally() {
+        let report = CompilationReport::of(&grant());
+        assert!(
+            report.is_total(),
+            "with no limits set there is nothing the database cannot express, \
+             so it alone is a sufficient enforcer; got {report:?}"
+        );
+    }
+
+    #[test]
+    fn a_grant_with_limits_reports_them_as_uncompiled() {
+        let mut g = grant();
+        g.limits = Limits {
+            rate_per_min: Some(20),
+            irreversible_budget: Some(0),
+            dead_man_secs: Some(1800),
+        };
+        let report = CompilationReport::of(&g);
+        assert!(
+            !report.is_total(),
+            "a rate limit that reached no enforcer must never look enforced"
+        );
+        assert_eq!(
+            report.uncompiled,
+            vec![
+                "limits.rate_per_min",
+                "limits.irreversible_budget",
+                "limits.dead_man_secs"
+            ],
+            "each unenforceable field must be named, so the caller knows which \
+             enforcement it still owes the gate"
+        );
+    }
+
+    #[test]
+    fn the_stored_token_is_not_the_sql_verb() {
+        assert_eq!(tier_token(Tier::Read), "read");
+        assert_eq!(Tier::Read.sql_verb(), "SELECT");
+        for tier in [Tier::Read, Tier::Append, Tier::Update, Tier::Delete] {
+            assert_ne!(
+                tier_token(tier),
+                tier.sql_verb(),
+                "the data token and the SQL keyword are 1:1 but not identical; \
+                 conflating them would put a SQL keyword in a data column"
+            );
+        }
+    }
+
+    #[test]
+    fn every_tier_has_a_distinct_token() {
+        let tokens: Vec<_> = [Tier::Read, Tier::Append, Tier::Update, Tier::Delete]
+            .into_iter()
+            .map(tier_token)
+            .collect();
+        let mut sorted = tokens.clone();
+        sorted.sort_unstable();
+        sorted.dedup();
+        assert_eq!(
+            sorted.len(),
+            tokens.len(),
+            "two tiers sharing a token would let a grant for one silently \
+             authorise the other"
+        );
+    }
+}

crates/adapters/trusty-policy-postgres/src/permits.rs

@@ -0,0 +1,508 @@
+//! The decision function every row-level-security policy calls.
+//!
+//! This is the compilation target. A `CREATE POLICY` written once per
+//! (table, verb) delegates to [`DDL_PERMITS`], and grants are rows, so
+//! issuing or revoking a permission never touches DDL and no SQL is ever
+//! built from a grant's contents.
+//!
+//! The evaluation order is the permission model's, and the order is
+//! load-bearing rather than incidental:
+//!
+//! 1. **Exclusion wins**, checked first, across *all* of the subject's
+//!    live grants regardless of tier. An exclusion can never be
+//!    overridden by a wider grant -- so it cannot be evaluated after
+//!    coverage, or a second grant would reopen what the first shut.
+//! 2. **Expiry** is wall clock, independent of whether work finished.
+//! 3. **Coverage** -- some live grant's scope contains the resource.
+//! 4. **Tier** matches exactly.
+//! 5. **Delegation intersects**: an agent is never a principal in its
+//!    own right, so the principal it acts for must independently permit
+//!    the same thing.
+//! 6. Anything unmatched, NULL or unreadable is **false**. Absent policy
+//!    is not permission.
+
+/// Scope containment.
+///
+/// `starts_with`, never `LIKE`: a scope containing `%` or `_` would
+/// otherwise widen itself, and the scope string is attacker-influenced
+/// in exactly the deployments this is for.
+pub const DDL_COVERS: &str = r#"
+CREATE OR REPLACE FUNCTION trusty_policy.covers(scope TEXT, resource TEXT)
+RETURNS BOOLEAN
+LANGUAGE sql IMMUTABLE PARALLEL SAFE
+AS $fn$
+    SELECT scope IS NOT NULL
+       AND resource IS NOT NULL
+       AND (resource = scope OR starts_with(resource, scope || '/'))
+$fn$
+"#;
+
+/// How many `acts_for` hops are followed before the answer is refusal.
+///
+/// A delegation cycle -- A acts for B, B acts for A -- would otherwise
+/// recurse until the stack gave out, and a stack overflow inside a
+/// policy predicate is an availability bug in the authorisation path.
+/// Refusing past the bound keeps the failure mode deny-by-default.
+pub const MAX_DELEGATION_DEPTH: i32 = 4;
+
+/// The decision function. `SECURITY DEFINER` with a pinned
+/// `search_path`, so the application role can consult grants without
+/// being able to read or write them directly.
+pub const DDL_PERMITS: &str = r#"
+CREATE OR REPLACE FUNCTION trusty_policy.permits(
+    subject  TEXT,
+    tier     TEXT,
+    resource TEXT,
+    depth    INT DEFAULT 0
+) RETURNS BOOLEAN
+LANGUAGE plpgsql
+STABLE
+SECURITY DEFINER
+SET search_path = trusty_policy, pg_temp
+AS $fn$
+DECLARE
+    g RECORD;
+BEGIN
+    -- Deny by default. An unreadable or missing subject refuses; it
+    -- does not fall back to something wider.
+    IF subject IS NULL OR subject = ''
+       OR tier IS NULL OR resource IS NULL THEN
+        RETURN FALSE;
+    END IF;
+
+    -- A delegation cycle is refused, not followed.
+    IF depth > 4 THEN
+        RETURN FALSE;
+    END IF;
+
+    -- 0. Identity before permission. A grant held by a principal who
+    --    was never registered is a grant to nobody, and one held by a
+    --    revoked principal must stop at once rather than grant by grant
+    --    -- revoking them one at a time is a race with whoever is using
+    --    them. This is what makes "kill the agent's key, the person is
+    --    untouched" true in practice.
+    IF NOT EXISTS (
+        SELECT 1
+        FROM trusty_policy.principal p
+        WHERE p.id = permits.subject
+          AND p.revoked_at IS NULL
+    ) THEN
+        RETURN FALSE;
+    END IF;
+
+    -- 1. Exclusion wins, and is checked before coverage so that a
+    --    second, wider grant cannot reopen what an exclusion shut.
+    --    Deliberately NOT filtered by tier: an exclusion is a statement
+    --    about a resource, not about a verb.
+    IF EXISTS (
+        SELECT 1
+        FROM trusty_policy.permission_grant pgr,
+             LATERAL unnest(pgr.excludes) AS ex(ref)
+        WHERE pgr.subject = permits.subject
+          AND pgr.revoked_at IS NULL
+          AND trusty_policy.covers(ex.ref, permits.resource)
+    ) THEN
+        RETURN FALSE;
+    END IF;
+
+    -- 2, 3, 4. A live grant, unexpired by the wall clock, of exactly
+    --    this tier, whose scope covers the resource.
+    FOR g IN
+        SELECT pgr.acts_for
+        FROM trusty_policy.permission_grant pgr
+        WHERE pgr.subject = permits.subject
+          AND pgr.tier = permits.tier
+          AND pgr.revoked_at IS NULL
+          AND pgr.expires_at > now()
+          AND trusty_policy.covers(pgr.scope, permits.resource)
+    LOOP
+        -- 5. effective = grant(agent) INTERSECT permission(acts_for).
+        --    A grant naming no principal stands on its own.
+        IF g.acts_for IS NULL THEN
+            RETURN TRUE;
+        END IF;
+
+        IF EXISTS (
+            SELECT 1
+            FROM trusty_policy.delegation d
+            WHERE d.agent_id    = permits.subject
+              AND d.acts_for_id = g.acts_for
+              AND d.revoked_at IS NULL
+              AND (d.expires_at IS NULL OR d.expires_at > now())
+        ) AND trusty_policy.permits(
+                  g.acts_for, permits.tier, permits.resource, depth + 1
+              ) THEN
+            RETURN TRUE;
+        END IF;
+    END LOOP;
+
+    -- 6. No matching grant is a refusal.
+    RETURN FALSE;
+END;
+$fn$
+"#;
+
+/// Applied after [`crate::schema::DDL_V1`], in the same transaction.
+pub const DDL_FUNCTIONS: &[&str] = &[
+    DDL_COVERS,
+    DDL_PERMITS,
+    DDL_ENSURE_PRINCIPAL,
+    DDL_REINSTATE_PRINCIPAL,
+];
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn the_decision_function_pins_its_search_path() {
+        assert!(
+            DDL_PERMITS.contains("SET search_path = trusty_policy, pg_temp"),
+            "a SECURITY DEFINER function without a pinned search_path is a \
+             privilege escalation: anyone able to set search_path could shadow \
+             permission_grant with a table of their own"
+        );
+    }
+
+    #[test]
+    fn security_definer_never_appears_without_a_pinned_search_path() {
+        for ddl in DDL_FUNCTIONS {
+            if ddl.contains("SECURITY DEFINER") {
+                assert!(
+                    ddl.contains("SET search_path ="),
+                    "every SECURITY DEFINER function must pin search_path, not \
+                     just the one that happens to be checked above: {ddl}"
+                );
+            }
+        }
+    }
+
+    #[test]
+    fn scope_containment_never_uses_like() {
+        for ddl in DDL_FUNCTIONS {
+            assert!(
+                !ddl.to_uppercase().contains(" LIKE "),
+                "LIKE would let a scope containing % or _ widen itself, and the \
+                 scope string is attacker-influenced: {ddl}"
+            );
+        }
+        assert!(
+            DDL_COVERS.contains("starts_with(resource, scope || '/')"),
+            "containment must be a literal prefix test on a path separator"
+        );
+    }
+
+    #[test]
+    fn a_prefix_that_is_not_a_path_segment_does_not_match() {
+        // covers('a/b', 'a/bc') must be false: 'a/bc' is not inside
+        // 'a/b'. The separator in the concatenation is what enforces it.
+        assert!(
+            DDL_COVERS.contains("scope || '/'"),
+            "without the separator, scope 'a/b' would cover 'a/bcd', silently \
+             granting a sibling resource whose name merely starts the same way"
+        );
+    }
+
+    #[test]
+    fn exclusion_is_evaluated_before_coverage() {
+        let exclusion = DDL_PERMITS
+            .find("unnest(pgr.excludes)")
+            .expect("the exclusion check must exist");
+        let coverage = DDL_PERMITS
+            .find("FOR g IN")
+            .expect("the coverage loop must exist");
+        assert!(
+            exclusion < coverage,
+            "an exclusion checked after coverage could be overridden by a wider \
+             grant, which is exactly what the model forbids"
+        );
+    }
+
+    #[test]
+    fn exclusions_are_not_filtered_by_tier() {
+        let start = DDL_PERMITS
+            .find("unnest(pgr.excludes)")
+            .expect("the exclusion check must exist");
+        let end = DDL_PERMITS[start..]
+            .find("RETURN FALSE")
+            .expect("the exclusion check must refuse")
+            + start;
+        assert!(
+            !DDL_PERMITS[start..end].contains("pgr.tier"),
+            "an exclusion is a statement about a resource, not about a verb; \
+             filtering it by tier would let a read grant expose what a write \
+             grant excluded"
+        );
+    }
+
+
+    #[test]
+    fn an_unregistered_or_revoked_principal_refuses() {
+        assert!(
+            DDL_PERMITS.contains("FROM trusty_policy.principal p"),
+            "a grant whose subject was never registered is a grant to nobody,              and deny-by-default says that refuses"
+        );
+        let start = DDL_PERMITS
+            .find("FROM trusty_policy.principal p")
+            .expect("the principal check must exist");
+        assert!(
+            DDL_PERMITS[start..].starts_with(
+                "FROM trusty_policy.principal p
+        WHERE p.id = permits.subject
+          AND p.revoked_at IS NULL"
+            ),
+            "revoking a principal must stop every grant it holds at once, not              leave them to be revoked one at a time"
+        );
+    }
+
+    #[test]
+    fn identity_is_checked_before_any_grant_is_read() {
+        let identity = DDL_PERMITS
+            .find("FROM trusty_policy.principal p")
+            .expect("the principal check must exist");
+        let exclusion = DDL_PERMITS
+            .find("unnest(pgr.excludes)")
+            .expect("the exclusion check must exist");
+        assert!(
+            identity < exclusion,
+            "asking who someone is before asking what they may do is both              cheaper and the right order to reason about; a revoked principal              should never reach the grant table at all"
+        );
+    }
+
+    #[test]
+    fn a_delegation_cycle_is_refused_rather_than_followed() {
+        assert!(
+            DDL_PERMITS.contains("depth > 4"),
+            "A acts for B and B acts for A would recurse until the stack gave \
+             out, and a stack overflow inside a policy predicate is an \
+             availability bug in the authorisation path"
+        );
+        assert_eq!(
+            MAX_DELEGATION_DEPTH, 4,
+            "the documented bound and the bound in the SQL must agree"
+        );
+    }
+
+    #[test]
+    fn the_delegated_side_is_checked_independently() {
+        assert!(
+            DDL_PERMITS.contains("trusty_policy.permits(\n                  g.acts_for"),
+            "the principal must be asked the same question, not merely looked \
+             up: an agent is never a principal in its own right"
+        );
+    }
+
+    #[test]
+    fn a_revoked_delegation_stops_permitting() {
+        let start = DDL_PERMITS
+            .find("FROM trusty_policy.delegation d")
+            .expect("the delegation lookup must exist");
+        let window = &DDL_PERMITS[start..];
+        assert!(
+            window.contains("d.revoked_at IS NULL"),
+            "revocation must take effect at the decision, not merely be recorded"
+        );
+        assert!(
+            window.contains("d.expires_at IS NULL OR d.expires_at > now()"),
+            "an expired delegation must stop permitting; NULL means no expiry, \
+             which is not the same as expired"
+        );
+    }
+
+    #[test]
+    fn expiry_is_wall_clock_and_revocation_is_immediate() {
+        assert!(
+            DDL_PERMITS.contains("pgr.expires_at > now()"),
+            "expiry is wall clock, independent of whether work finished"
+        );
+        assert!(
+            DDL_PERMITS.contains("pgr.revoked_at IS NULL"),
+            "a revoked grant must stop permitting without any DDL running"
+        );
+    }
+
+    #[test]
+    fn a_null_or_empty_subject_refuses() {
+        assert!(
+            DDL_PERMITS.contains("subject IS NULL OR subject = ''"),
+            "current_setting('trusty.subject', true) returns NULL when unset \
+             and '' in some paths; either must refuse, because absent policy \
+             is not permission"
+        );
+    }
+
+    #[test]
+    fn the_function_is_stable_not_volatile() {
+        assert!(
+            DDL_PERMITS.contains("STABLE"),
+            "a VOLATILE function cannot be used in an RLS predicate efficiently \
+             and would be re-evaluated per row without caching"
+        );
+    }
+
+    #[test]
+    fn nothing_here_is_created_outside_the_trusty_policy_schema() {
+        for ddl in DDL_FUNCTIONS {
+            assert!(
+                ddl.contains("FUNCTION trusty_policy."),
+                "an unqualified function would land in whatever search_path \
+                 happened to be set: {ddl}"
+            );
+        }
+    }
+}
+
+/// Create a principal if missing, and refresh its display name.
+///
+/// The portable half of enrolment. A consumer whose users arrive through
+/// its own auth table hangs a thin trigger on that table and calls this;
+/// the trigger is the consumer's, because only they know which table
+/// their users live in, but the logic is here so both sides cannot
+/// drift.
+///
+/// `SECURITY DEFINER` with a pinned `search_path`, for the same reason
+/// [`DDL_PERMITS`] is: without the pin, anyone able to set `search_path`
+/// could shadow `principal` with a table of their own.
+///
+/// **It does not un-revoke.** An earlier version did, on the reasoning
+/// that re-enrolment is the same decision said again. That reasoning
+/// holds for a person deliberately re-enrolling and fails for an
+/// automated repair job -- and the function cannot tell them apart.
+/// Reconciliation calls this same verb, so un-revoking here meant a
+/// revoked principal whose auth row still existed would be resurrected
+/// by the next backfill, silently undoing a deliberate act. Bringing
+/// someone back is [`DDL_REINSTATE_PRINCIPAL`], which a trigger has no
+/// reason to reach.
+pub const DDL_ENSURE_PRINCIPAL: &str = r#"
+CREATE OR REPLACE FUNCTION trusty_policy.ensure_principal(
+    p_id      TEXT,
+    p_kind    TEXT,
+    p_display TEXT DEFAULT ''
+) RETURNS VOID
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = trusty_policy, pg_temp
+AS $fn$
+BEGIN
+    INSERT INTO trusty_policy.principal (id, kind, display)
+    VALUES (p_id, p_kind, COALESCE(p_display, ''))
+    ON CONFLICT (id) DO UPDATE
+        SET display = EXCLUDED.display;
+END;
+$fn$
+"#;
+
+/// Bring a revoked principal back, deliberately.
+///
+/// Separate from [`DDL_ENSURE_PRINCIPAL`] because "create if missing"
+/// and "bring someone back" are different intentions, and only one of
+/// them should be reachable from a trigger. Revocation is an act someone
+/// may have to justify; undoing it should be equally deliberate, and
+/// equally visible in whatever called it.
+///
+/// Returns whether a revoked principal was actually reinstated, so a
+/// caller reinstating someone already live is told rather than
+/// reassured.
+pub const DDL_REINSTATE_PRINCIPAL: &str = r#"
+CREATE OR REPLACE FUNCTION trusty_policy.reinstate_principal(p_id TEXT)
+RETURNS BOOLEAN
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = trusty_policy, pg_temp
+AS $fn$
+DECLARE
+    changed INT;
+BEGIN
+    UPDATE trusty_policy.principal
+       SET revoked_at = NULL
+     WHERE id = p_id AND revoked_at IS NOT NULL;
+    GET DIAGNOSTICS changed = ROW_COUNT;
+    RETURN changed = 1;
+END;
+$fn$
+"#;
+
+/// Principals that should exist and do not, or exist and are revoked.
+///
+/// **Must always return zero rows.** `permits()` refuses for a subject
+/// that is not a registered live principal, so a missed enrolment is not
+/// degraded access -- it is a total lockout, with nothing in any log
+/// saying why. This is the query that catches it before a person does.
+///
+/// Takes a table and column to reconcile against, so a consumer can
+/// point it at whatever holds its users. Returns the ids that are
+/// missing and the ones that are revoked, separately: they need
+/// different fixes.
+pub const SQL_RECONCILE_PRINCIPALS: &str = r#"
+SELECT src.id,
+       CASE WHEN p.id IS NULL THEN 'missing' ELSE 'revoked' END AS problem
+  FROM (SELECT $1::text[] AS ids) AS _
+  CROSS JOIN LATERAL unnest(_.ids) AS src(id)
+  LEFT JOIN trusty_policy.principal p
+         ON p.id = src.id AND p.revoked_at IS NULL
+ WHERE p.id IS NULL
+"#;
+
+#[cfg(test)]
+mod enrolment_tests {
+    use super::*;
+
+    #[test]
+    fn ensure_principal_pins_its_search_path() {
+        assert!(
+            DDL_ENSURE_PRINCIPAL.contains("SET search_path = trusty_policy, pg_temp"),
+            "a SECURITY DEFINER function without a pinned search_path lets \
+             anyone who can set search_path shadow `principal` with a table of \
+             their own"
+        );
+    }
+
+    #[test]
+    fn enrolment_cannot_resurrect_a_revoked_principal() {
+        assert!(
+            !DDL_ENSURE_PRINCIPAL.contains("revoked_at"),
+            "reconciliation calls this same verb, so un-revoking here would let              a backfill resurrect a principal somebody deliberately revoked --              and permits() refuses a revoked principal, so it would restore              everything at once"
+        );
+    }
+
+    #[test]
+    fn bringing_someone_back_is_a_separate_verb() {
+        assert!(
+            DDL_REINSTATE_PRINCIPAL.contains("revoked_at = NULL"),
+            "there must still be a way back, or revocation is a trapdoor"
+        );
+        assert!(
+            DDL_REINSTATE_PRINCIPAL.contains("revoked_at IS NOT NULL"),
+            "and it must report whether it actually changed anything, so a              caller reinstating someone already live is told rather than              reassured"
+        );
+        assert!(
+            DDL_REINSTATE_PRINCIPAL.contains("SET search_path = trusty_policy, pg_temp"),
+            "a SECURITY DEFINER function without a pinned search_path is a              privilege escalation, and this one can restore authority"
+        );
+    }
+
+    #[test]
+    fn enrolment_is_idempotent() {
+        assert!(
+            DDL_ENSURE_PRINCIPAL.contains("ON CONFLICT (id) DO UPDATE"),
+            "a trigger fires more than once in practice; a second call must \
+             not fail and must not duplicate"
+        );
+    }
+
+    #[test]
+    fn reconciliation_separates_missing_from_revoked() {
+        assert!(
+            SQL_RECONCILE_PRINCIPALS.contains("'missing'")
+                && SQL_RECONCILE_PRINCIPALS.contains("'revoked'"),
+            "the two need different fixes -- one is an enrolment that never \
+             ran, the other a deliberate act somebody may need to justify -- \
+             so a query reporting them alike hides the difference"
+        );
+        assert!(
+            SQL_RECONCILE_PRINCIPALS.contains("revoked_at IS NULL"),
+            "a revoked principal is not a present one as far as permits() is \
+             concerned, so reconciliation must count it as a problem"
+        );
+    }
+}

crates/adapters/trusty-policy-postgres/src/schema.rs

@@ -0,0 +1,312 @@
+//! Schema DDL for the grant store.
+//!
+//! Follows `trusty-postgres`'s idiom exactly: a `&[&str]` of
+//! `CREATE ... IF NOT EXISTS` applied in one transaction on every open,
+//! followed by a `schema_meta` version upsert. There is no migration
+//! runner here and there should not be one -- the consumer's migration
+//! tool owns *its* tables; this owns only the permission model's own.
+//!
+//! Everything lives in its own `trusty_policy` schema so it can never
+//! collide with an application table, and so revoking write access to
+//! the whole schema is one statement.
+
+pub const SCHEMA_VERSION: &str = "1";
+
+/// The Postgres schema every object below lives in.
+pub const SCHEMA_NAME: &str = "trusty_policy";
+
+pub const DDL_V1: &[&str] = &[
+    r#"CREATE SCHEMA IF NOT EXISTS trusty_policy"#,
+    // ----------------------------------------------------------------
+    // principal -- one table, four kinds.
+    //
+    // `id` is TEXT holding the full reference ("agent:01J..."), not a
+    // bare UUID. The permission model's canonical grant JSON carries
+    // subjects in that prefixed form, and `Grant.subject` is a String;
+    // storing a bare uuid would mean parsing the prefix off on every
+    // write and re-attaching it on every read, which is exactly the
+    // translation layer this design exists to avoid.
+    //
+    // The CHECK keeps the prefix honest, so `kind` cannot drift from
+    // what the id claims.
+    // ----------------------------------------------------------------
+    r#"CREATE TABLE IF NOT EXISTS trusty_policy.principal (
+        id          TEXT        PRIMARY KEY,
+        kind        TEXT        NOT NULL CHECK (kind IN ('org','user','agent','program')),
+        display     TEXT        NOT NULL DEFAULT '',
+        created_at  TIMESTAMPTZ NOT NULL DEFAULT now(),
+        -- The `key` edge. Points at trusty's producer registry
+        -- (producer_identity.producer_oid), which is the agent identity
+        -- system; there is not to be a second one. Deliberately no
+        -- foreign key: that table belongs to trusty-postgres, lives in
+        -- another schema, and may not be installed at all. The edge is
+        -- recorded here and resolved through lookup_producer.
+        producer_oid TEXT       UNIQUE,
+        -- Revoking the identity itself, as distinct from revoking any
+        -- one grant. Kills every grant the principal holds at once,
+        -- which is what "kill the agent's key, the person is untouched"
+        -- has to mean in practice.
+        revoked_at  TIMESTAMPTZ,
+        -- What KIND of thing this is, structurally, is `kind`. What kind
+        -- of ORGANISATION it is -- nonprofit, agency, prime, sub -- is
+        -- descriptive and belongs here, not there.
+        --
+        -- Kept apart deliberately. Folded into `kind`, every new
+        -- organisation type becomes a change to permits(), and the
+        -- authorisation function ends up knowing about tax status. The
+        -- CHECK on `kind` is what keeps the two from being conflated by
+        -- accident.
+        org_type    TEXT,
+        CONSTRAINT principal_id_matches_kind CHECK (starts_with(id, kind || ':')),
+        -- Only an org has an org type. A user with one is a modelling
+        -- mistake that would otherwise sit there looking deliberate.
+        CONSTRAINT org_type_only_on_orgs CHECK (org_type IS NULL OR kind = 'org')
+    )"#,
+    // Idempotent columns for an installation that predates them.
+    // CREATE TABLE IF NOT EXISTS silently does nothing when the table is
+    // already there, so a new column needs saying twice.
+    r#"ALTER TABLE trusty_policy.principal
+        ADD COLUMN IF NOT EXISTS producer_oid TEXT"#,
+    r#"ALTER TABLE trusty_policy.principal
+        ADD COLUMN IF NOT EXISTS revoked_at TIMESTAMPTZ"#,
+    r#"ALTER TABLE trusty_policy.principal
+        ADD COLUMN IF NOT EXISTS org_type TEXT"#,
+    r#"CREATE UNIQUE INDEX IF NOT EXISTS idx_principal_producer_oid
+       ON trusty_policy.principal(producer_oid)"#,
+    // ----------------------------------------------------------------
+    // membership -- user belongs to org.
+    // ----------------------------------------------------------------
+    r#"CREATE TABLE IF NOT EXISTS trusty_policy.membership (
+        member_id  TEXT        NOT NULL REFERENCES trusty_policy.principal(id) ON DELETE CASCADE,
+        org_id     TEXT        NOT NULL REFERENCES trusty_policy.principal(id) ON DELETE CASCADE,
+        role       TEXT        NOT NULL DEFAULT '',
+        created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+        PRIMARY KEY (member_id, org_id)
+    )"#,
+    // ----------------------------------------------------------------
+    // delegation -- agent acts for user | org.
+    //
+    // Deliberately NOT cascaded on delete: revoking a delegation is
+    // `revoked_at`, and losing the row would lose the record that the
+    // delegation ever existed. An audit asks "who could act for whom
+    // last March", and a deleted row cannot answer.
+    // ----------------------------------------------------------------
+    r#"CREATE TABLE IF NOT EXISTS trusty_policy.delegation (
+        agent_id    TEXT        NOT NULL REFERENCES trusty_policy.principal(id),
+        acts_for_id TEXT        NOT NULL REFERENCES trusty_policy.principal(id),
+        granted_by  TEXT        REFERENCES trusty_policy.principal(id),
+        granted_at  TIMESTAMPTZ NOT NULL DEFAULT now(),
+        expires_at  TIMESTAMPTZ,
+        revoked_at  TIMESTAMPTZ,
+        PRIMARY KEY (agent_id, acts_for_id)
+    )"#,
+    // ----------------------------------------------------------------
+    // permission_grant -- the grant itself.
+    //
+    // Named `permission_grant`, not `grant`: GRANT is a reserved word in
+    // SQL, and a table that must be double-quoted at every call site is
+    // a footgun waiting for the one place someone forgets.
+    //
+    // `id` is the SHA-256 of `canonical_json`, so a grant's identity IS
+    // its content. Issuing the same grant twice is idempotent, and the
+    // id is exactly what a signature over the grant would cover.
+    //
+    // `canonical_json` is stored verbatim -- RFC 8785 bytes, not a JSONB
+    // column. JSONB renormalises whitespace and key order, which would
+    // destroy the very property the canonical form exists to provide.
+    // Same reasoning that keeps `raw_payload` TEXT in trusty-postgres.
+    // ----------------------------------------------------------------
+    r#"CREATE TABLE IF NOT EXISTS trusty_policy.permission_grant (
+        id             TEXT        PRIMARY KEY,
+        subject        TEXT        NOT NULL,
+        acts_for       TEXT,
+        scope          TEXT        NOT NULL,
+        tier           TEXT        NOT NULL CHECK (tier IN ('read','append','update','delete')),
+        excludes       TEXT[]      NOT NULL DEFAULT '{}',
+        expires_at     TIMESTAMPTZ NOT NULL,
+        why            TEXT,
+        canonical_json TEXT        NOT NULL,
+        issued_at      TIMESTAMPTZ NOT NULL DEFAULT now(),
+        revoked_at     TIMESTAMPTZ
+    )"#,
+    // Every permits() call filters on subject first, then tier.
+    r#"CREATE INDEX IF NOT EXISTS idx_grant_subject_tier
+       ON trusty_policy.permission_grant(subject, tier)"#,
+    // Exclusions are checked across ALL of a subject's grants, including
+    // ones whose tier does not match, so they need their own path in.
+    r#"CREATE INDEX IF NOT EXISTS idx_grant_subject
+       ON trusty_policy.permission_grant(subject)"#,
+    r#"CREATE TABLE IF NOT EXISTS trusty_policy.schema_meta (
+        key   TEXT PRIMARY KEY,
+        value TEXT NOT NULL
+    )"#,
+];
+
+/// Upserts the schema_version row. Runs on every open to declare the
+/// version this build expects. Mirrors `trusty-postgres`.
+pub const DDL_SCHEMA_VERSION_UPSERT: &str = r#"
+    INSERT INTO trusty_policy.schema_meta(key, value) VALUES ('schema_version', $1)
+    ON CONFLICT (key) DO UPDATE SET value = EXCLUDED.value
+"#;
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn every_statement_is_idempotent() {
+        for stmt in DDL_V1 {
+            let upper = stmt.to_uppercase();
+            assert!(
+                upper.contains("IF NOT EXISTS"),
+                "the schema is applied on every open, so a statement without \
+                 IF NOT EXISTS would fail the second time a process starts: {stmt}"
+            );
+        }
+    }
+
+    #[test]
+    fn nothing_is_created_outside_the_trusty_policy_schema() {
+        for stmt in DDL_V1 {
+            if stmt.to_uppercase().starts_with("CREATE SCHEMA") {
+                continue;
+            }
+            assert!(
+                stmt.contains("trusty_policy."),
+                "an unqualified object would land in whatever search_path \
+                 happened to be set, which is not a place to keep permissions: {stmt}"
+            );
+        }
+    }
+
+    #[test]
+    fn the_grant_table_avoids_the_reserved_word() {
+        let ddl = DDL_V1.join("\n").to_uppercase();
+        assert!(
+            !ddl.contains("EXISTS TRUSTY_POLICY.GRANT "),
+            "GRANT is reserved in SQL; the table is permission_grant precisely \
+             so no call site has to remember to double-quote it"
+        );
+    }
+
+    #[test]
+    fn the_canonical_form_is_stored_as_text_not_jsonb() {
+        let ddl = DDL_V1.join("\n");
+        assert!(
+            ddl.contains("canonical_json TEXT"),
+            "JSONB renormalises whitespace and key order, which would destroy \
+             the exact property RFC 8785 canonicalisation exists to give"
+        );
+        assert!(
+            !ddl.to_uppercase().contains("JSONB"),
+            "no column here may be JSONB, for the same reason"
+        );
+    }
+
+    #[test]
+    fn tier_is_constrained_to_the_four_verbs() {
+        let ddl = DDL_V1.join("\n");
+        assert!(
+            ddl.contains("tier IN ('read','append','update','delete')"),
+            "a tier outside the four is a permission nobody can enforce; \
+             the database should refuse to store one"
+        );
+    }
+
+    #[test]
+    fn a_principals_kind_cannot_drift_from_its_id() {
+        let ddl = DDL_V1.join("\n");
+        assert!(
+            ddl.contains("principal_id_matches_kind"),
+            "if kind and the id prefix can disagree, an audit line reading \
+             'agent:...' whose kind says 'user' is unreadable"
+        );
+    }
+
+
+
+    #[test]
+    fn org_type_is_descriptive_and_kind_is_structural() {
+        let ddl = DDL_V1.join("
+");
+        assert!(
+            ddl.contains("org_type"),
+            "an organisation's type is descriptive; folded into `kind` it              would make every new organisation type a change to permits()"
+        );
+        assert!(
+            ddl.contains("kind IN ('org','user','agent','program')"),
+            "and `kind` must stay the closed structural set, or the two              collapse back into one column"
+        );
+        assert!(
+            ddl.contains("org_type_only_on_orgs"),
+            "a user carrying an org type is a modelling mistake that would              otherwise sit there looking deliberate"
+        );
+    }
+
+    #[test]
+    fn permits_never_needs_to_read_org_type() {
+        // Structural, not a runtime check: the decision function selects
+        // its own columns, and org_type is not among them. If it ever
+        // is, authorisation has started depending on what sort of
+        // organisation someone is, which is the coupling this split
+        // exists to prevent.
+        assert!(
+            !crate::permits::DDL_PERMITS.contains("org_type"),
+            "permits() must not read org_type"
+        );
+    }
+
+    #[test]
+    fn the_key_edge_points_at_the_producer_registry() {
+        let ddl = DDL_V1.join("
+");
+        assert!(
+            ddl.contains("producer_oid"),
+            "the third edge -- principal has an ed25519 key -- must be              recorded, and it must point at trusty's producer registry              rather than at a second identity system"
+        );
+        assert!(
+            !ddl.contains("ed25519_pubkey"),
+            "storing the key material here would BE the second identity              system; only the reference to the registry belongs here"
+        );
+    }
+
+    #[test]
+    fn a_principal_can_be_revoked_as_a_whole() {
+        let ddl = DDL_V1.join("
+");
+        assert!(
+            ddl.contains("revoked_at TIMESTAMPTZ"),
+            "killing an agent's key must stop every grant it holds at once;              revoking them one at a time is a race with whoever is using them"
+        );
+    }
+
+    #[test]
+    fn a_column_added_after_v1_is_added_idempotently_too() {
+        let ddl = DDL_V1.join("
+");
+        for col in ["producer_oid", "revoked_at"] {
+            assert!(
+                ddl.contains(&format!("ADD COLUMN IF NOT EXISTS {col}")),
+                "CREATE TABLE IF NOT EXISTS does nothing when the table                  already exists, so a column added later never reaches an                  existing installation unless it is also ALTERed in: {col}"
+            );
+        }
+    }
+
+    #[test]
+    fn a_delegation_is_revoked_not_deleted() {
+        let delegation = DDL_V1
+            .iter()
+            .find(|s| s.contains("trusty_policy.delegation"))
+            .expect("the delegation table must exist");
+        assert!(
+            delegation.contains("revoked_at"),
+            "revocation must be recorded, not effected by deletion"
+        );
+        assert!(
+            !delegation.contains("ON DELETE CASCADE"),
+            "cascading a delegation away would erase the record that it ever \
+             existed, and 'who could act for whom last March' is exactly what \
+             an audit asks"
+        );
+    }
+}

crates/adapters/trusty-policy-postgres/src/store.rs

@@ -0,0 +1,616 @@
+//! Issuing grants, and putting a table under their protection.
+//!
+//! Three things live here:
+//!
+//! - [`GrantStore`] — issue and revoke grants. Both are parameterized
+//!   statements against rows; neither runs DDL.
+//! - [`PolicySession`] — set the subject for one transaction, so a
+//!   policy predicate has someone to ask about.
+//! - [`GrantStore::enforce`] — the one place a table name reaches SQL,
+//!   and the only DDL a consumer runs after install.
+
+use postgres::{Client, NoTls, Transaction};
+use trusty_policy::{Grant, Tier};
+
+use crate::permits::DDL_FUNCTIONS;
+use crate::schema::{DDL_SCHEMA_VERSION_UPSERT, DDL_V1, SCHEMA_VERSION};
+use crate::{tier_token, CompilationReport, GrantId, PolicyPgError};
+
+/// The GUC a policy predicate reads the acting subject from.
+///
+/// Set transaction-locally by [`PolicySession::begin`]. Transaction
+/// local, not session local, so a pooled connection handed to the next
+/// request cannot still be carrying the last one's identity.
+pub const SUBJECT_SETTING: &str = "trusty.subject";
+
+/// Reads and writes grants.
+pub struct GrantStore {
+    client: Client,
+}
+
+impl GrantStore {
+    /// Connect and apply the schema idempotently.
+    pub fn open(conn_str: &str) -> Result<Self, PolicyPgError> {
+        let mut client = Client::connect(conn_str, NoTls)?;
+        apply_schema(&mut client)?;
+        Ok(Self { client })
+    }
+
+    /// Adopt an existing connection, applying the schema to it.
+    pub fn adopt(mut client: Client) -> Result<Self, PolicyPgError> {
+        apply_schema(&mut client)?;
+        Ok(Self { client })
+    }
+
+    pub fn client(&mut self) -> &mut Client {
+        &mut self.client
+    }
+
+    /// Record a grant, and say what about it the database will not be
+    /// enforcing.
+    ///
+    /// Idempotent: the id is the hash of the canonical form, so issuing
+    /// the same grant twice leaves one row rather than two permissions.
+    /// Re-issuing a previously revoked grant un-revokes it, which is the
+    /// same decision said again.
+    pub fn issue(&mut self, grant: &Grant) -> Result<(GrantId, CompilationReport), PolicyPgError> {
+        let canonical = grant
+            .canonical_json()
+            .map_err(|e| PolicyPgError::Canonicalise(e.to_string()))?;
+        let id = GrantId::of_canonical(&canonical);
+        let expires = expires_at_sql(grant.expires_at);
+
+        self.client.execute(
+            "INSERT INTO trusty_policy.permission_grant
+                 (id, subject, acts_for, scope, tier, excludes,
+                  expires_at, why, canonical_json)
+             VALUES ($1, $2, $3, $4, $5, $6, to_timestamp($7), $8, $9)
+             ON CONFLICT (id) DO UPDATE SET revoked_at = NULL",
+            &[
+                &id.as_str(),
+                &grant.subject,
+                &grant.acts_for,
+                &grant.scope,
+                &tier_token(grant.tier),
+                &grant.excludes,
+                &expires,
+                &grant.why,
+                &canonical,
+            ],
+        )?;
+
+        Ok((id, CompilationReport::of(grant)))
+    }
+
+    /// Register a principal, or update its display name.
+    ///
+    /// `kind` must be one of `org`, `user`, `agent`, `program`, and the
+    /// id must carry it as a prefix — `agent:01J...`. The database
+    /// enforces both; this returns the error rather than papering over
+    /// it, because a principal whose kind disagrees with its id makes
+    /// every audit line that mentions it unreadable.
+    ///
+    /// Registering an already-revoked principal reinstates it, which is
+    /// the same decision said again.
+    pub fn register_principal(
+        &mut self,
+        id: &str,
+        kind: &str,
+        display: &str,
+    ) -> Result<(), PolicyPgError> {
+        self.client.execute(
+            "INSERT INTO trusty_policy.principal (id, kind, display)
+             VALUES ($1, $2, $3)
+             ON CONFLICT (id) DO UPDATE
+                 SET display = EXCLUDED.display, revoked_at = NULL",
+            &[&id, &kind, &display],
+        )?;
+        Ok(())
+    }
+
+    /// Record the `key` edge: this principal is that producer.
+    ///
+    /// `producer_oid` refers to trusty's producer registry —
+    /// `register_producer` / `lookup_producer` / `revoke_producer` in
+    /// `trusty-postgres`. That registry is the agent identity system and
+    /// there is not to be a second one, so no key material is stored
+    /// here; only the reference.
+    ///
+    /// There is deliberately no foreign key. `producer_identity` belongs
+    /// to a different crate and schema and may not be installed at all,
+    /// and a policy engine that refuses to start without a chain store
+    /// would be a policy engine with a substrate.
+    pub fn bind_key(&mut self, principal: &str, producer_oid: &str) -> Result<(), PolicyPgError> {
+        let n = self.client.execute(
+            "UPDATE trusty_policy.principal SET producer_oid = $2 WHERE id = $1",
+            &[&principal, &producer_oid],
+        )?;
+        if n == 0 {
+            return Err(PolicyPgError::UnknownPrincipal(principal.to_string()));
+        }
+        Ok(())
+    }
+
+    /// The producer this principal is, if the edge has been recorded.
+    ///
+    /// Resolving it to an actual public key goes through the producer
+    /// registry's own `lookup_producer`. Doing that here would mean
+    /// reimplementing half of it.
+    pub fn producer_oid_of(&mut self, principal: &str) -> Result<Option<String>, PolicyPgError> {
+        let row = self.client.query_opt(
+            "SELECT producer_oid FROM trusty_policy.principal WHERE id = $1",
+            &[&principal],
+        )?;
+        Ok(row.and_then(|r| r.get::<_, Option<String>>(0)))
+    }
+
+    /// Revoke a principal, and with it every grant the principal holds.
+    ///
+    /// This is the blunt instrument, and it is meant to be. Revoking
+    /// grants one at a time is a race with whoever is using them; the
+    /// point of "kill the agent's key, the person is untouched" is that
+    /// one action ends the agent's authority entirely while leaving the
+    /// principal it acted for alone.
+    ///
+    /// The grant rows survive. An audit asks what was permitted last
+    /// March, and a deleted row cannot answer.
+    ///
+    /// Returns whether a live principal was actually revoked.
+    pub fn revoke_principal(&mut self, id: &str) -> Result<bool, PolicyPgError> {
+        let n = self.client.execute(
+            "UPDATE trusty_policy.principal
+                SET revoked_at = now()
+              WHERE id = $1 AND revoked_at IS NULL",
+            &[&id],
+        )?;
+        Ok(n == 1)
+    }
+
+    /// Record that `agent` may act for `acts_for`.
+    ///
+    /// The delegation edge. Without it, an agent's grant naming a
+    /// principal is inert: [`GrantStore::permits`] requires both the
+    /// edge and the principal's own permission.
+    pub fn delegate(&mut self, agent: &str, acts_for: &str) -> Result<(), PolicyPgError> {
+        self.client.execute(
+            "INSERT INTO trusty_policy.delegation (agent_id, acts_for_id)
+             VALUES ($1, $2)
+             ON CONFLICT (agent_id, acts_for_id) DO UPDATE SET revoked_at = NULL",
+            &[&agent, &acts_for],
+        )?;
+        Ok(())
+    }
+
+    /// End a delegation without touching either side's grants.
+    pub fn revoke_delegation(&mut self, agent: &str, acts_for: &str) -> Result<bool, PolicyPgError> {
+        let n = self.client.execute(
+            "UPDATE trusty_policy.delegation SET revoked_at = now()
+              WHERE agent_id = $1 AND acts_for_id = $2 AND revoked_at IS NULL",
+            &[&agent, &acts_for],
+        )?;
+        Ok(n == 1)
+    }
+
+    /// Stop a grant permitting, without running any DDL.
+    ///
+    /// Returns whether a live grant was actually revoked, so a caller
+    /// revoking something already gone is told rather than reassured.
+    /// The row stays: an audit asks what was permitted last March, and a
+    /// deleted row cannot answer.
+    pub fn revoke(&mut self, id: &GrantId) -> Result<bool, PolicyPgError> {
+        let n = self.client.execute(
+            "UPDATE trusty_policy.permission_grant
+                SET revoked_at = now()
+              WHERE id = $1 AND revoked_at IS NULL",
+            &[&id.as_str()],
+        )?;
+        Ok(n == 1)
+    }
+
+    /// Ask the database the same question a policy predicate asks.
+    ///
+    /// For diagnostics and tests. Enforcement does not go through here —
+    /// it goes through the policy — but a caller debugging a refusal
+    /// wants to ask directly rather than infer from an empty result set.
+    pub fn permits(
+        &mut self,
+        subject: &str,
+        tier: Tier,
+        resource: &str,
+    ) -> Result<bool, PolicyPgError> {
+        let row = self.client.query_one(
+            "SELECT trusty_policy.permits($1, $2, $3)",
+            &[&subject, &tier_token(tier), &resource],
+        )?;
+        Ok(row.get::<_, Option<bool>>(0).unwrap_or(false))
+    }
+
+    /// Put one table under grant enforcement.
+    ///
+    /// `scope_column` names the column holding each row's resource
+    /// reference — the value a grant's scope is tested against.
+    ///
+    /// This is the only place an identifier reaches SQL text. It is not
+    /// escaped by hand: the server is asked to resolve and quote it, via
+    /// `to_regclass` and `format('%I')`, and a name that does not
+    /// resolve to a real table is refused rather than quoted. Escaping
+    /// is a thing you can get subtly wrong; existence is not.
+    ///
+    /// Returns the statements executed, so a caller can log or review
+    /// exactly what was applied.
+    pub fn enforce(
+        &mut self,
+        table: &str,
+        scope_column: &str,
+    ) -> Result<Vec<String>, PolicyPgError> {
+        let row = self
+            .client
+            .query_opt(
+                "SELECT format('%I.%I', n.nspname, c.relname),
+                        format('%I', a.attname),
+                        c.relname
+                   FROM pg_class c
+                   JOIN pg_namespace n ON n.oid = c.relnamespace
+                   JOIN pg_attribute a ON a.attrelid = c.oid
+                  WHERE c.oid = to_regclass($1)
+                    AND c.relkind = 'r'
+                    AND a.attname = $2
+                    AND a.attnum > 0
+                    AND NOT a.attisdropped",
+                &[&table, &scope_column],
+            )?
+            .ok_or_else(|| PolicyPgError::UnknownRelation(format!("{table}.{scope_column}")))?;
+
+        let qualified: String = row.get(0);
+        let column: String = row.get(1);
+        let bare: String = row.get(2);
+
+        let mut applied = Vec::new();
+
+        // FORCE is not optional. Plain ENABLE is bypassed by the table
+        // owner, and the owner is who most connections are. Without
+        // FORCE every policy below is decorative.
+        for stmt in [
+            format!("ALTER TABLE {qualified} ENABLE ROW LEVEL SECURITY"),
+            format!("ALTER TABLE {qualified} FORCE ROW LEVEL SECURITY"),
+        ] {
+            self.client.batch_execute(&stmt)?;
+            applied.push(stmt);
+        }
+
+        for tier in [Tier::Read, Tier::Append, Tier::Update, Tier::Delete] {
+            let policy = policy_name(&bare, tier);
+            let quoted: String = self
+                .client
+                .query_one("SELECT format('%I', $1::text)", &[&policy])?
+                .get(0);
+
+            // DROP first so enforce() is idempotent: re-running it after
+            // a definition change must converge, not fail.
+            let drop = format!("DROP POLICY IF EXISTS {quoted} ON {qualified}");
+            self.client.batch_execute(&drop)?;
+            applied.push(drop);
+
+            let create = create_policy_sql(&quoted, &qualified, &column, tier);
+            self.client.batch_execute(&create)?;
+            applied.push(create);
+        }
+
+        Ok(applied)
+    }
+}
+
+/// The four policy statements that put `table` under grant enforcement,
+/// plus the two `ALTER TABLE` lines that make them bite.
+///
+/// Pure: it touches no database and creates nothing. Use it to generate
+/// a migration for a table that does not exist yet, where
+/// [`GrantStore::enforce`] cannot help because it resolves the name
+/// against `pg_class` first.
+///
+/// Because there is no catalogue to resolve against, identifiers are
+/// checked by shape instead, and refused rather than escaped. The output
+/// is SQL text destined for a file a person reviews; that is a good
+/// reason to be strict about it, not a reason to relax.
+pub fn policy_statements(
+    table: &str,
+    scope_column: &str,
+) -> Result<Vec<String>, PolicyPgError> {
+    let qualified = check_identifier(table)?;
+    let column = check_identifier(scope_column)?;
+    let bare = table.rsplit('.').next().unwrap_or(table).to_string();
+
+    let mut out = vec![
+        format!("ALTER TABLE {qualified} ENABLE ROW LEVEL SECURITY;"),
+        format!("ALTER TABLE {qualified} FORCE ROW LEVEL SECURITY;"),
+    ];
+    for tier in [Tier::Read, Tier::Append, Tier::Update, Tier::Delete] {
+        let policy = policy_name(&bare, tier);
+        out.push(format!(
+            "DROP POLICY IF EXISTS {policy} ON {qualified};"
+        ));
+        out.push(format!(
+            "{};",
+            create_policy_sql(&policy, &qualified, &column, tier)
+        ));
+    }
+    Ok(out)
+}
+
+/// Accept an unquoted SQL identifier, optionally schema-qualified.
+///
+/// Deliberately narrow: lowercase ASCII, digits and underscore, not
+/// starting with a digit, at most one dot. Anything else is refused
+/// rather than quoted, because a name needing quotes in a generated
+/// migration is a name worth a human deciding about.
+fn check_identifier(name: &str) -> Result<String, PolicyPgError> {
+    let refuse = || PolicyPgError::UnknownRelation(name.to_string());
+    if name.is_empty() || name.len() > 128 || name.matches('.').count() > 1 {
+        return Err(refuse());
+    }
+    for part in name.split('.') {
+        let mut chars = part.chars();
+        match chars.next() {
+            Some(c) if c.is_ascii_lowercase() || c == '_' => {}
+            _ => return Err(refuse()),
+        }
+        if !chars.all(|c| c.is_ascii_lowercase() || c.is_ascii_digit() || c == '_') {
+            return Err(refuse());
+        }
+    }
+    Ok(name.to_string())
+}
+
+/// The policy statement for one (table, verb).
+///
+/// `INSERT` takes `WITH CHECK` and no `USING`; `DELETE` and `SELECT`
+/// take `USING` and no `WITH CHECK`; `UPDATE` takes both, because a row
+/// may be moved out of a permitted scope as easily as into one. Getting
+/// this wrong is the classic RLS hole — a policy that guards which rows
+/// you may change but not what you may change them into.
+fn create_policy_sql(policy: &str, table: &str, column: &str, tier: Tier) -> String {
+    let predicate = format!(
+        "trusty_policy.permits(current_setting('{SUBJECT_SETTING}', true), '{}', {column})",
+        tier_token(tier)
+    );
+    let verb = tier.sql_verb();
+    match tier {
+        Tier::Append => {
+            format!("CREATE POLICY {policy} ON {table} FOR {verb} WITH CHECK ({predicate})")
+        }
+        Tier::Update => format!(
+            "CREATE POLICY {policy} ON {table} FOR {verb} \
+             USING ({predicate}) WITH CHECK ({predicate})"
+        ),
+        Tier::Read | Tier::Delete => {
+            format!("CREATE POLICY {policy} ON {table} FOR {verb} USING ({predicate})")
+        }
+    }
+}
+
+/// Deterministic policy name for a (table, verb), so re-running
+/// [`GrantStore::enforce`] replaces rather than accumulates.
+fn policy_name(table: &str, tier: Tier) -> String {
+    format!("trusty_{table}_{}", tier_token(tier))
+}
+
+/// Grant expiry crosses as seconds since the epoch and is turned into a
+/// `timestamptz` by `to_timestamp` server-side.
+///
+/// `Grant.expires_at` is an `i64` of unix seconds; the column is
+/// `TIMESTAMPTZ`. Converting in Rust would mean picking a timezone, and
+/// the one thing worse than a wrong expiry is a wrong expiry that looks
+/// right in one region.
+fn expires_at_sql(expires_at: i64) -> f64 {
+    expires_at as f64
+}
+
+fn apply_schema(client: &mut Client) -> Result<(), PolicyPgError> {
+    let mut txn = client.transaction()?;
+    for stmt in DDL_V1 {
+        txn.batch_execute(stmt)?;
+    }
+    for stmt in DDL_FUNCTIONS {
+        txn.batch_execute(stmt)?;
+    }
+    txn.execute(DDL_SCHEMA_VERSION_UPSERT, &[&SCHEMA_VERSION])?;
+    txn.commit()?;
+    Ok(())
+}
+
+/// A transaction carrying the identity of whoever is acting.
+///
+/// Every policy predicate reads `current_setting('trusty.subject')`.
+/// Outside a `PolicySession` that setting is unset, the predicate sees
+/// NULL, and every policy refuses — which is the correct default: code
+/// that forgets to say who it is gets nothing, rather than everything.
+pub struct PolicySession<'a> {
+    txn: Transaction<'a>,
+}
+
+impl<'a> PolicySession<'a> {
+    /// Begin a transaction acting as `subject`.
+    pub fn begin(client: &'a mut Client, subject: &str) -> Result<Self, PolicyPgError> {
+        let mut txn = client.transaction()?;
+        // `true` is is_local: the setting dies with the transaction, so
+        // a pooled connection cannot carry one request's identity into
+        // the next.
+        txn.execute(
+            "SELECT set_config($1, $2, true)",
+            &[&SUBJECT_SETTING, &subject],
+        )?;
+        Ok(Self { txn })
+    }
+
+    pub fn txn(&mut self) -> &mut Transaction<'a> {
+        &mut self.txn
+    }
+
+    pub fn commit(self) -> Result<(), PolicyPgError> {
+        self.txn.commit()?;
+        Ok(())
+    }
+
+    pub fn rollback(self) -> Result<(), PolicyPgError> {
+        self.txn.rollback()?;
+        Ok(())
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn insert_takes_with_check_and_no_using() {
+        let sql = create_policy_sql("p", "t", "scope", Tier::Append);
+        assert!(
+            sql.contains("WITH CHECK") && !sql.contains("USING"),
+            "an INSERT policy has no existing row to test, so USING is not just \
+             redundant, it is rejected by Postgres: {sql}"
+        );
+        assert!(sql.contains("FOR INSERT"), "got {sql}");
+    }
+
+    #[test]
+    fn update_takes_both_using_and_with_check() {
+        let sql = create_policy_sql("p", "t", "scope", Tier::Update);
+        assert!(
+            sql.contains("USING") && sql.contains("WITH CHECK"),
+            "USING alone guards which rows may be changed but not what they may \
+             be changed INTO, so a row could be moved out of a permitted scope. \
+             That is the classic RLS hole: {sql}"
+        );
+    }
+
+    #[test]
+    fn read_and_delete_take_using_and_no_with_check() {
+        for tier in [Tier::Read, Tier::Delete] {
+            let sql = create_policy_sql("p", "t", "scope", tier);
+            assert!(
+                sql.contains("USING") && !sql.contains("WITH CHECK"),
+                "neither reading nor deleting produces a new row to check: {sql}"
+            );
+        }
+    }
+
+    #[test]
+    fn each_policy_asks_about_its_own_tier() {
+        for tier in [Tier::Read, Tier::Append, Tier::Update, Tier::Delete] {
+            let sql = create_policy_sql("p", "t", "scope", tier);
+            assert!(
+                sql.contains(&format!("'{}'", tier_token(tier))),
+                "a policy for one verb asking about another would let a grant \
+                 to read authorise a delete: {sql}"
+            );
+            assert!(
+                sql.contains(&format!("FOR {}", tier.sql_verb())),
+                "the SQL verb and the tier token must stay in step: {sql}"
+            );
+        }
+    }
+
+    #[test]
+    fn the_predicate_reads_the_subject_from_the_transaction() {
+        let sql = create_policy_sql("p", "t", "scope", Tier::Read);
+        assert!(
+            sql.contains("current_setting('trusty.subject', true)"),
+            "the second argument must be `true` (missing_ok), or an unset \
+             subject raises instead of refusing, and an error is not a denial: \
+             {sql}"
+        );
+    }
+
+    #[test]
+    fn an_identifier_that_would_need_quoting_is_refused() {
+        for bad in [
+            "public.\"; DROP TABLE x; --",
+            "public.tab le",
+            "Public.Table",
+            "9lives",
+            "a.b.c",
+            "",
+            "tab'le",
+        ] {
+            assert!(
+                check_identifier(bad).is_err(),
+                "a name needing quotes in a generated migration is a name worth                  a human deciding about, not one worth escaping: {bad:?}"
+            );
+        }
+        assert!(check_identifier("public.calendar_event").is_ok());
+        assert!(check_identifier("calendar").is_ok());
+    }
+
+    #[test]
+    fn generated_statements_force_row_level_security() {
+        let stmts = policy_statements("public.calendar", "resource_scope").expect("emit");
+        assert!(
+            stmts.iter().any(|s| s.contains("FORCE ROW LEVEL SECURITY")),
+            "ENABLE alone is bypassed by the table owner, so a migration              emitting only ENABLE would read as protection and provide none"
+        );
+        assert_eq!(
+            stmts.len(),
+            2 + 4 * 2,
+            "two ALTERs, then a DROP and a CREATE for each of the four verbs"
+        );
+    }
+
+    #[test]
+    fn generated_statements_match_what_enforce_would_run() {
+        let generated = policy_statements("public.calendar", "resource_scope").expect("emit");
+        // enforce() builds the same CREATE POLICY text, minus the
+        // trailing semicolons a file needs. If these ever diverge, a
+        // migration and a live call would mean different things.
+        let direct = create_policy_sql(
+            &policy_name("calendar", Tier::Read),
+            "public.calendar",
+            "resource_scope",
+            Tier::Read,
+        );
+        assert!(
+            generated.iter().any(|s| s.trim_end_matches(';') == direct),
+            "the emitted migration and enforce() must produce the same policy,              or the file a reviewer reads is not the rule the database gets"
+        );
+    }
+
+    #[test]
+    fn policy_names_are_deterministic_per_table_and_verb() {
+        assert_eq!(policy_name("calendar", Tier::Read), "trusty_calendar_read");
+        assert_ne!(
+            policy_name("calendar", Tier::Read),
+            policy_name("calendar", Tier::Delete),
+            "one name per (table, verb) is what makes enforce() converge on \
+             re-run instead of accumulating policies"
+        );
+    }
+
+    #[test]
+    fn a_grants_contents_never_appear_in_policy_sql() {
+        let sql = create_policy_sql("p", "t", "scope", Tier::Read);
+        for grant_shaped in ["board:9f2", "agent:01J", "user:01H"] {
+            assert!(
+                !sql.contains(grant_shaped),
+                "the policy is written once and knows nothing about any \
+                 particular grant; if a grant's contents reached this string, \
+                 a scope could become syntax: {sql}"
+            );
+        }
+    }
+
+    #[test]
+    fn the_subject_setting_is_transaction_local() {
+        // Guards the literal in PolicySession::begin. `false` here would
+        // leave the identity on a pooled connection after the request
+        // that set it had finished.
+        let src = include_str!("store.rs");
+        assert!(
+            src.contains("&[&SUBJECT_SETTING, &subject],"),
+            "set_config must be called with the constant, not an ad-hoc string"
+        );
+        assert!(
+            src.contains("\"SELECT set_config($1, $2, true)\""),
+            "is_local must be true, or a pooled connection carries one \
+             request's identity into the next"
+        );
+    }
+}

crates/adapters/trusty-policy-postgres/tests/integration.rs

@@ -0,0 +1,883 @@
+//! Behavioural tests against a real Postgres.
+//!
+//! Everything in the crate's unit tests asserts properties of SQL
+//! *text*. These assert what the database actually does with it, which
+//! is the only claim worth making about an authorisation boundary.
+//!
+//! Skipped, not failed, when `TRUSTY_POLICY_PG_URL` is unset, so
+//! `cargo test --workspace` stays green on a machine with no database.
+//! Same convention as `trusty-postgres`'s suite.
+//!
+//! ```text
+//! TRUSTY_POLICY_PG_URL=postgresql://postgres:postgres@127.0.0.1:54322/postgres \
+//!   cargo test -p trusty-policy-postgres --test integration
+//! ```
+//!
+//! **The tests act as a non-superuser role.** A superuser bypasses row
+//! level security entirely, so a suite that ran as `postgres` would pass
+//! against a table with no protection at all.
+
+use postgres::Client;
+use trusty_policy::{Grant, Limits, Tier};
+use trusty_policy_postgres::{CompilationReport, GrantId, GrantStore, PolicyPgError};
+
+fn url() -> Option<String> {
+    std::env::var("TRUSTY_POLICY_PG_URL").ok()
+}
+
+/// Serialises the suite against one database.
+///
+/// Every `GrantStore::open` applies the schema, and concurrent
+/// `CREATE OR REPLACE FUNCTION` on the same function collides in
+/// `pg_proc` with "tuple concurrently updated". The tests also create
+/// and drop roles, which are cluster-global however carefully the table
+/// names are scoped.
+///
+/// Taken here rather than left to `--test-threads=1`, because a suite
+/// that is only green when invoked a particular way is one plain
+/// `cargo test` away from looking broken.
+fn db_lock() -> std::sync::MutexGuard<'static, ()> {
+    static LOCK: std::sync::OnceLock<std::sync::Mutex<()>> = std::sync::OnceLock::new();
+    LOCK.get_or_init(|| std::sync::Mutex::new(()))
+        .lock()
+        .unwrap_or_else(|poisoned| poisoned.into_inner())
+}
+
+/// Distinct names per test, so tests neither collide nor depend on
+/// order.
+struct Fixture {
+    table: String,
+    role: String,
+}
+
+impl Fixture {
+    fn new(tag: &str) -> Self {
+        Self {
+            table: format!("rls_probe_{tag}"),
+            role: format!("rls_role_{tag}"),
+        }
+    }
+
+    /// A protected table, a non-superuser role that can reach it, and no
+    /// grants at all.
+    fn set_up(&self, store: &mut GrantStore) -> Vec<String> {
+        let (table, role) = (&self.table, &self.role);
+        let drop_role = drop_role_sql(role);
+        store
+            .client()
+            .batch_execute(&format!(
+                "DROP TABLE IF EXISTS public.{table};
+                 CREATE TABLE public.{table} (
+                     id             SERIAL PRIMARY KEY,
+                     resource_scope TEXT NOT NULL,
+                     note           TEXT NOT NULL
+                 );
+                 INSERT INTO public.{table}(resource_scope, note) VALUES
+                     ('board:9f2/calendar/team',    'visible'),
+                     ('board:9f2/calendar/private', 'excluded'),
+                     ('board:other/calendar',       'someone else');
+                 {drop_role}
+                 CREATE ROLE {role} NOSUPERUSER NOBYPASSRLS;
+                 -- SET ROLE requires membership. Supabase's `postgres` is
+                 -- not a true superuser, so the connecting user has to be
+                 -- granted the role it intends to act as.
+                 GRANT {role} TO CURRENT_USER;
+                 GRANT USAGE ON SCHEMA public TO {role};
+                 GRANT SELECT, INSERT, UPDATE, DELETE ON public.{table} TO {role};
+                 GRANT USAGE, SELECT ON SEQUENCE public.{table}_id_seq TO {role};
+                 GRANT USAGE ON SCHEMA trusty_policy TO {role};"
+            ))
+            .expect("fixture set-up");
+
+        store
+            .enforce(&format!("public.{table}"), "resource_scope")
+            .expect("enforce")
+    }
+
+    fn tear_down(&self, store: &mut GrantStore) {
+        let (table, role) = (&self.table, &self.role);
+        let drop_role = drop_role_sql(role);
+        let _ = store.client().batch_execute(&format!(
+            "DROP TABLE IF EXISTS public.{table};
+             {drop_role}"
+        ));
+        let _ = store
+            .client()
+            .batch_execute("DELETE FROM trusty_policy.permission_grant");
+    }
+
+    /// Read the table the way the application would: as the unprivileged
+    /// role, with a subject set for the transaction only.
+    fn read_as(&self, client: &mut Client, subject: &str) -> Vec<String> {
+        let mut txn = client.transaction().expect("txn");
+        txn.execute(&format!("SET LOCAL ROLE {}", self.role), &[])
+            .expect("assume role");
+        txn.execute(
+            "SELECT set_config('trusty.subject', $1, true)",
+            &[&subject],
+        )
+        .expect("set subject");
+        let rows = txn
+            .query(
+                &format!("SELECT note FROM public.{} ORDER BY id", self.table),
+                &[],
+            )
+            .expect("select");
+        let notes = rows.iter().map(|r| r.get::<_, String>(0)).collect();
+        txn.rollback().expect("rollback");
+        notes
+    }
+}
+
+/// Drop a role only if it exists.
+///
+/// `DROP ROLE IF EXISTS` tolerates absence, but `DROP OWNED BY` does not
+/// -- and the grants a role holds must go before the role can. So both
+/// have to sit behind one existence check rather than relying on
+/// IF EXISTS.
+fn drop_role_sql(role: &str) -> String {
+    format!(
+        "DO $do$ BEGIN
+             IF EXISTS (SELECT 1 FROM pg_roles WHERE rolname = '{role}') THEN
+                 -- In PG16+, ADMIN OPTION on a role is not the same as
+                 -- holding its privileges, and DROP OWNED BY needs the
+                 -- latter. Creating the role is not enough.
+                 EXECUTE 'GRANT {role} TO CURRENT_USER';
+                 EXECUTE 'DROP OWNED BY {role}';
+                 EXECUTE 'DROP ROLE {role}';
+             END IF;
+         END $do$;"
+    )
+}
+
+/// Issue a grant, registering its principals first.
+///
+/// `permits()` refuses for a subject that is not a registered, live
+/// principal — identity before permission — so a test that only issued
+/// a grant would be testing the registration check rather than the rule
+/// it names.
+trait Registering {
+    fn issue_registered(
+        &mut self,
+        grant: &Grant,
+    ) -> Result<(GrantId, CompilationReport), PolicyPgError>;
+}
+
+impl Registering for GrantStore {
+    fn issue_registered(
+        &mut self,
+        grant: &Grant,
+    ) -> Result<(GrantId, CompilationReport), PolicyPgError> {
+        for who in [Some(&grant.subject), grant.acts_for.as_ref()].into_iter().flatten() {
+            let kind = who.split(':').next().unwrap_or("agent");
+            self.register_principal(who, kind, "")?;
+        }
+        self.issue(grant)
+    }
+}
+
+fn grant(subject: &str, scope: &str, tier: Tier) -> Grant {
+    Grant {
+        why: Some("integration fixture".into()),
+        subject: subject.into(),
+        acts_for: None,
+        scope: scope.into(),
+        tier,
+        excludes: Vec::new(),
+        limits: Limits::default(),
+        // Far future; the expiry test overrides this deliberately.
+        expires_at: 4_102_444_800,
+    }
+}
+
+// ---------------------------------------------------------------------
+// The acceptance criterion.
+// ---------------------------------------------------------------------
+
+#[test]
+fn a_read_the_grant_excludes_fails_at_the_database() {
+    let Some(url) = url() else {
+        eprintln!("skipped: TRUSTY_POLICY_PG_URL unset");
+        return;
+    };
+    let _db = db_lock();
+    let mut store = GrantStore::open(&url).expect("open");
+    let fx = Fixture::new("excl");
+    fx.set_up(&mut store);
+
+    let mut g = grant("agent:excl", "board:9f2/calendar", Tier::Read);
+    g.excludes = vec!["board:9f2/calendar/private".into()];
+    store.issue_registered(&g).expect("issue");
+
+    let seen = fx.read_as(store.client(), "agent:excl");
+    fx.tear_down(&mut store);
+
+    assert!(
+        !seen.contains(&"excluded".to_string()),
+        "an excluded resource must be unreadable AT THE DATABASE, not merely \
+         refused by an application check that could be bypassed; saw {seen:?}"
+    );
+}
+
+#[test]
+fn an_exclusion_is_not_overridden_by_a_wider_grant() {
+    let Some(url) = url() else {
+        eprintln!("skipped: TRUSTY_POLICY_PG_URL unset");
+        return;
+    };
+    let _db = db_lock();
+    let mut store = GrantStore::open(&url).expect("open");
+    let fx = Fixture::new("wider");
+    fx.set_up(&mut store);
+
+    let mut narrow = grant("agent:wider", "board:9f2/calendar/team", Tier::Read);
+    narrow.excludes = vec!["board:9f2/calendar/private".into()];
+    store.issue_registered(&narrow).expect("issue narrow");
+
+    // Issued afterwards, covering strictly more, and carrying no
+    // exclusion of its own.
+    let wide = grant("agent:wider", "board:9f2", Tier::Read);
+    store.issue_registered(&wide).expect("issue wide");
+
+    let seen = fx.read_as(store.client(), "agent:wider");
+    fx.tear_down(&mut store);
+
+    assert!(
+        !seen.contains(&"excluded".to_string()),
+        "adding a wider grant later must not reopen what an exclusion shut; \
+         saw {seen:?}"
+    );
+    assert!(
+        seen.contains(&"visible".to_string()),
+        "the wider grant should still permit everything it covers that is not \
+         excluded; saw {seen:?}"
+    );
+}
+
+#[test]
+fn absent_policy_is_not_permission() {
+    let Some(url) = url() else {
+        eprintln!("skipped: TRUSTY_POLICY_PG_URL unset");
+        return;
+    };
+    let _db = db_lock();
+    let mut store = GrantStore::open(&url).expect("open");
+    let fx = Fixture::new("deny");
+    fx.set_up(&mut store);
+
+    let with_no_grant = fx.read_as(store.client(), "agent:nobody");
+    let with_no_subject = fx.read_as(store.client(), "");
+    fx.tear_down(&mut store);
+
+    assert!(
+        with_no_grant.is_empty(),
+        "a subject with no grant must see nothing, not fall back to something \
+         wider; saw {with_no_grant:?}"
+    );
+    assert!(
+        with_no_subject.is_empty(),
+        "code that forgets to say who it is must get nothing rather than \
+         everything; saw {with_no_subject:?}"
+    );
+}
+
+#[test]
+fn a_scope_containing_a_like_metacharacter_does_not_widen_itself() {
+    let Some(url) = url() else {
+        eprintln!("skipped: TRUSTY_POLICY_PG_URL unset");
+        return;
+    };
+    let _db = db_lock();
+    let mut store = GrantStore::open(&url).expect("open");
+    let fx = Fixture::new("meta");
+    fx.set_up(&mut store);
+
+    // Under LIKE semantics '%' matches everything and this would read
+    // the whole table.
+    store
+        .issue(&grant("agent:meta", "%", Tier::Read))
+        .expect("issue");
+    let wildcard = fx.read_as(store.client(), "agent:meta");
+
+    store
+        .issue(&grant("agent:meta2", "board:9f2/calendar/_eam", Tier::Read))
+        .expect("issue");
+    let underscore = fx.read_as(store.client(), "agent:meta2");
+
+    fx.tear_down(&mut store);
+
+    assert!(
+        wildcard.is_empty(),
+        "a scope of '%' is a scope literally named '%', not a wildcard; saw \
+         {wildcard:?}"
+    );
+    assert!(
+        underscore.is_empty(),
+        "'_' must not match an arbitrary character, or a near-miss scope would \
+         silently grant its neighbour; saw {underscore:?}"
+    );
+}
+
+#[test]
+fn a_sibling_whose_name_merely_starts_the_same_is_not_covered() {
+    let Some(url) = url() else {
+        eprintln!("skipped: TRUSTY_POLICY_PG_URL unset");
+        return;
+    };
+    let _db = db_lock();
+    let mut store = GrantStore::open(&url).expect("open");
+    let fx = Fixture::new("sib");
+    fx.set_up(&mut store);
+
+    // 'board:9f2/calendar' must NOT cover 'board:9f2/calendar/team' via a
+    // bare prefix test that ignores the separator -- it does cover it
+    // here, legitimately -- but 'board:o' must not cover 'board:other'.
+    store
+        .issue(&grant("agent:sib", "board:o", Tier::Read))
+        .expect("issue");
+    let seen = fx.read_as(store.client(), "agent:sib");
+    fx.tear_down(&mut store);
+
+    assert!(
+        seen.is_empty(),
+        "containment must break on a path separator; without it, 'board:o' \
+         would grant 'board:other/calendar'; saw {seen:?}"
+    );
+}
+
+#[test]
+fn an_expired_grant_stops_permitting_at_the_wall_clock() {
+    let Some(url) = url() else {
+        eprintln!("skipped: TRUSTY_POLICY_PG_URL unset");
+        return;
+    };
+    let _db = db_lock();
+    let mut store = GrantStore::open(&url).expect("open");
+    let fx = Fixture::new("exp");
+    fx.set_up(&mut store);
+
+    let mut g = grant("agent:exp", "board:9f2/calendar", Tier::Read);
+    g.expires_at = 1_000_000_000; // 2001, comfortably past
+    store.issue_registered(&g).expect("issue");
+
+    let seen = fx.read_as(store.client(), "agent:exp");
+    fx.tear_down(&mut store);
+
+    assert!(
+        seen.is_empty(),
+        "expiry is wall clock and independent of whether work finished; saw \
+         {seen:?}"
+    );
+}
+
+#[test]
+fn revoking_a_grant_takes_effect_without_ddl() {
+    let Some(url) = url() else {
+        eprintln!("skipped: TRUSTY_POLICY_PG_URL unset");
+        return;
+    };
+    let _db = db_lock();
+    let mut store = GrantStore::open(&url).expect("open");
+    let fx = Fixture::new("rev");
+    fx.set_up(&mut store);
+
+    let g = grant("agent:rev", "board:9f2/calendar", Tier::Read);
+    let (id, _) = store.issue_registered(&g).expect("issue");
+    let before = fx.read_as(store.client(), "agent:rev");
+
+    let revoked = store.revoke(&id).expect("revoke");
+    let after = fx.read_as(store.client(), "agent:rev");
+
+    let twice = store.revoke(&id).expect("revoke again");
+    fx.tear_down(&mut store);
+
+    assert!(
+        !before.is_empty(),
+        "the grant must permit something before revocation, or this test \
+         proves nothing"
+    );
+    assert!(revoked, "revoking a live grant must report that it did so");
+    assert!(
+        after.is_empty(),
+        "revocation must take effect at the next decision, with no DDL run; \
+         saw {after:?}"
+    );
+    assert!(
+        !twice,
+        "revoking what is already revoked must report that nothing changed, \
+         rather than reassuring the caller"
+    );
+}
+
+#[test]
+fn an_agent_cannot_exceed_the_principal_it_acts_for() {
+    let Some(url) = url() else {
+        eprintln!("skipped: TRUSTY_POLICY_PG_URL unset");
+        return;
+    };
+    let _db = db_lock();
+    let mut store = GrantStore::open(&url).expect("open");
+    let fx = Fixture::new("deleg");
+    fx.set_up(&mut store);
+
+    store
+        .client()
+        .batch_execute(
+            "INSERT INTO trusty_policy.principal(id, kind) VALUES
+                 ('agent:d1', 'agent'), ('user:d1', 'user')
+             ON CONFLICT DO NOTHING;
+             INSERT INTO trusty_policy.delegation(agent_id, acts_for_id) VALUES
+                 ('agent:d1', 'user:d1')
+             ON CONFLICT DO NOTHING;",
+        )
+        .expect("principals");
+
+    // The agent's own grant is wider than the principal's.
+    let mut wide = grant("agent:d1", "board:9f2", Tier::Read);
+    wide.acts_for = Some("user:d1".into());
+    store.issue_registered(&wide).expect("issue agent");
+    store
+        .issue(&grant("user:d1", "board:9f2/calendar/team", Tier::Read))
+        .expect("issue principal");
+
+    let seen = fx.read_as(store.client(), "agent:d1");
+
+    // Now revoke the delegation and try again.
+    store
+        .client()
+        .batch_execute(
+            "UPDATE trusty_policy.delegation SET revoked_at = now()
+              WHERE agent_id = 'agent:d1'",
+        )
+        .expect("revoke delegation");
+    let after_revoke = fx.read_as(store.client(), "agent:d1");
+
+    store
+        .client()
+        .batch_execute("DELETE FROM trusty_policy.delegation; DELETE FROM trusty_policy.principal")
+        .expect("clean principals");
+    fx.tear_down(&mut store);
+
+    assert_eq!(
+        seen,
+        vec!["visible".to_string()],
+        "the agent must be held to the intersection: its own grant covers \
+         board:9f2 entirely, but the principal only permits the team \
+         calendar; saw {seen:?}"
+    );
+    assert!(
+        after_revoke.is_empty(),
+        "revoking the delegation must stop the agent acting at all, without \
+         touching either grant; saw {after_revoke:?}"
+    );
+}
+
+#[test]
+fn a_grant_for_one_verb_does_not_authorise_another() {
+    let Some(url) = url() else {
+        eprintln!("skipped: TRUSTY_POLICY_PG_URL unset");
+        return;
+    };
+    let _db = db_lock();
+    let mut store = GrantStore::open(&url).expect("open");
+    let fx = Fixture::new("verb");
+    fx.set_up(&mut store);
+
+    // Delete is the most destructive tier. If tiers implied one another
+    // by ordering, this would also confer read.
+    store
+        .issue(&grant("agent:verb", "board:9f2/calendar", Tier::Delete))
+        .expect("issue");
+    let seen = fx.read_as(store.client(), "agent:verb");
+    fx.tear_down(&mut store);
+
+    assert!(
+        seen.is_empty(),
+        "tier maps 1:1 onto the SQL verbs and deny-by-default governs the rest, \
+         so a grant to delete must not silently confer the ability to read \
+         everything deletable; saw {seen:?}"
+    );
+}
+
+#[test]
+fn enforce_is_idempotent_and_forces_row_level_security() {
+    let Some(url) = url() else {
+        eprintln!("skipped: TRUSTY_POLICY_PG_URL unset");
+        return;
+    };
+    let _db = db_lock();
+    let mut store = GrantStore::open(&url).expect("open");
+    let fx = Fixture::new("force");
+    let first = fx.set_up(&mut store);
+
+    // Re-running must converge, not fail on an existing policy.
+    let second = store
+        .enforce(&format!("public.{}", fx.table), "resource_scope")
+        .expect("second enforce");
+
+    let forced: bool = store
+        .client()
+        .query_one(
+            "SELECT relforcerowsecurity FROM pg_class WHERE oid = to_regclass($1)",
+            &[&format!("public.{}", fx.table)],
+        )
+        .expect("pg_class")
+        .get(0);
+    let policies: i64 = store
+        .client()
+        .query_one(
+            "SELECT count(*) FROM pg_policies
+              WHERE schemaname = 'public' AND tablename = $1",
+            &[&fx.table],
+        )
+        .expect("pg_policies")
+        .get(0);
+
+    fx.tear_down(&mut store);
+
+    assert_eq!(first, second, "enforce must be deterministic across runs");
+    assert!(
+        forced,
+        "without FORCE, the table owner bypasses every policy and the \
+         protection is decorative"
+    );
+    assert_eq!(
+        policies, 4,
+        "one policy per verb, replaced rather than accumulated on re-run"
+    );
+}
+
+#[test]
+fn an_unknown_relation_is_refused_rather_than_quoted() {
+    let Some(url) = url() else {
+        eprintln!("skipped: TRUSTY_POLICY_PG_URL unset");
+        return;
+    };
+    let _db = db_lock();
+    let mut store = GrantStore::open(&url).expect("open");
+
+    assert!(
+        store.enforce("public.no_such_table_here", "resource_scope").is_err(),
+        "enabling row level security on a table that does not exist would \
+         silently protect nothing"
+    );
+    assert!(
+        store.enforce("public.no_such_table_here", "'; DROP TABLE x; --").is_err(),
+        "an identifier that does not resolve must be refused, never escaped \
+         and used"
+    );
+}
+
+#[test]
+fn issuing_the_same_grant_twice_leaves_one_row() {
+    let Some(url) = url() else {
+        eprintln!("skipped: TRUSTY_POLICY_PG_URL unset");
+        return;
+    };
+    let _db = db_lock();
+    let mut store = GrantStore::open(&url).expect("open");
+    let g = grant("agent:idem", "board:9f2/calendar", Tier::Read);
+
+    let (first, report) = store.issue_registered(&g).expect("issue");
+    let (second, _) = store.issue_registered(&g).expect("issue again");
+
+    let count: i64 = store
+        .client()
+        .query_one(
+            "SELECT count(*) FROM trusty_policy.permission_grant WHERE subject = $1",
+            &[&"agent:idem"],
+        )
+        .expect("count")
+        .get(0);
+    let _ = store
+        .client()
+        .batch_execute("DELETE FROM trusty_policy.permission_grant");
+
+    assert_eq!(first, second, "identity is content, so it must not vary");
+    assert_eq!(
+        count, 1,
+        "a content-addressed id makes re-issuing idempotent rather than \
+         quietly accumulating duplicate permissions"
+    );
+    assert!(
+        report.is_total(),
+        "this grant sets no limits, so nothing about it went unenforced"
+    );
+}
+
+#[test]
+fn the_stored_canonical_form_reproduces_the_id() {
+    let Some(url) = url() else {
+        eprintln!("skipped: TRUSTY_POLICY_PG_URL unset");
+        return;
+    };
+    let _db = db_lock();
+    let mut store = GrantStore::open(&url).expect("open");
+    let g = grant("agent:canon", "board:9f2/calendar", Tier::Read);
+    let (id, _) = store.issue_registered(&g).expect("issue");
+
+    let stored: String = store
+        .client()
+        .query_one(
+            "SELECT canonical_json FROM trusty_policy.permission_grant WHERE id = $1",
+            &[&id.as_str()],
+        )
+        .expect("select")
+        .get(0);
+    let _ = store
+        .client()
+        .batch_execute("DELETE FROM trusty_policy.permission_grant");
+
+    assert_eq!(
+        GrantId::of_canonical(&stored),
+        id,
+        "the bytes in the row must be the bytes that were hashed, or a \
+         verifier holding the signed grant could not find or check its row"
+    );
+}
+
+#[test]
+fn a_registered_principal_with_no_grant_still_sees_nothing() {
+    let Some(url) = url() else {
+        eprintln!("skipped: TRUSTY_POLICY_PG_URL unset");
+        return;
+    };
+    let _db = db_lock();
+    let mut store = GrantStore::open(&url).expect("open");
+    let fx = Fixture::new("reg");
+    fx.set_up(&mut store);
+
+    // Registration is identity, not permission. Without this test,
+    // `absent_policy_is_not_permission` would pass merely because the
+    // subject was unregistered, and the deny-by-default rule it is named
+    // for would go untested.
+    store
+        .register_principal("agent:registered", "agent", "has an identity, no grant")
+        .expect("register");
+
+    let seen = fx.read_as(store.client(), "agent:registered");
+    fx.tear_down(&mut store);
+
+    assert!(
+        seen.is_empty(),
+        "being someone is not the same as being allowed something; saw {seen:?}"
+    );
+}
+
+#[test]
+fn an_unregistered_principal_refuses_even_holding_a_grant() {
+    let Some(url) = url() else {
+        eprintln!("skipped: TRUSTY_POLICY_PG_URL unset");
+        return;
+    };
+    let _db = db_lock();
+    let mut store = GrantStore::open(&url).expect("open");
+    let fx = Fixture::new("unreg");
+    fx.set_up(&mut store);
+
+    // Issued WITHOUT registering: a grant to nobody.
+    store
+        .issue(&grant("agent:ghost", "board:9f2/calendar", Tier::Read))
+        .expect("issue");
+    let seen = fx.read_as(store.client(), "agent:ghost");
+    fx.tear_down(&mut store);
+
+    assert!(
+        seen.is_empty(),
+        "a grant held by a principal who was never registered is a grant to \
+         nobody, and absent policy is not permission; saw {seen:?}"
+    );
+}
+
+#[test]
+fn revoking_a_principal_stops_every_grant_it_holds_at_once() {
+    let Some(url) = url() else {
+        eprintln!("skipped: TRUSTY_POLICY_PG_URL unset");
+        return;
+    };
+    let _db = db_lock();
+    let mut store = GrantStore::open(&url).expect("open");
+    let fx = Fixture::new("prev");
+    fx.set_up(&mut store);
+
+    // Two separate grants, so this tests the blunt instrument rather
+    // than a single revocation wearing a different hat.
+    store
+        .issue_registered(&grant("agent:doomed", "board:9f2/calendar", Tier::Read))
+        .expect("issue one");
+    store
+        .issue_registered(&grant("agent:doomed", "board:other", Tier::Read))
+        .expect("issue two");
+    let before = fx.read_as(store.client(), "agent:doomed");
+
+    let revoked = store.revoke_principal("agent:doomed").expect("revoke");
+    let after = fx.read_as(store.client(), "agent:doomed");
+    let twice = store.revoke_principal("agent:doomed").expect("revoke again");
+
+    let survivors: i64 = store
+        .client()
+        .query_one(
+            "SELECT count(*) FROM trusty_policy.permission_grant WHERE subject = $1",
+            &[&"agent:doomed"],
+        )
+        .expect("count")
+        .get(0);
+    fx.tear_down(&mut store);
+
+    assert_eq!(
+        before.len(),
+        3,
+        "both grants must permit something first, or this proves nothing; \
+         saw {before:?}"
+    );
+    assert!(revoked, "revoking a live principal must report that it did so");
+    assert!(
+        after.is_empty(),
+        "killing the key must end the agent's authority entirely, not grant \
+         by grant -- revoking them one at a time races whoever is using them; \
+         saw {after:?}"
+    );
+    assert!(!twice, "revoking what is already revoked must report no change");
+    assert_eq!(
+        survivors, 2,
+        "the grant rows must survive revocation; an audit asks what was \
+         permitted last March and a deleted row cannot answer"
+    );
+}
+
+#[test]
+fn revoking_an_agent_leaves_the_principal_it_acted_for_untouched() {
+    let Some(url) = url() else {
+        eprintln!("skipped: TRUSTY_POLICY_PG_URL unset");
+        return;
+    };
+    let _db = db_lock();
+    let mut store = GrantStore::open(&url).expect("open");
+    let fx = Fixture::new("sever");
+    fx.set_up(&mut store);
+
+    let mut agent = grant("agent:s1", "board:9f2", Tier::Read);
+    agent.acts_for = Some("user:s1".into());
+    store.issue_registered(&agent).expect("issue agent");
+    store
+        .issue_registered(&grant("user:s1", "board:9f2/calendar/team", Tier::Read))
+        .expect("issue principal");
+    store.delegate("agent:s1", "user:s1").expect("delegate");
+
+    let agent_before = fx.read_as(store.client(), "agent:s1");
+    store.revoke_principal("agent:s1").expect("revoke agent");
+    let agent_after = fx.read_as(store.client(), "agent:s1");
+    let principal_after = fx.read_as(store.client(), "user:s1");
+
+    store
+        .client()
+        .batch_execute("DELETE FROM trusty_policy.delegation")
+        .expect("clean");
+    fx.tear_down(&mut store);
+
+    assert!(!agent_before.is_empty(), "the agent must start able to act");
+    assert!(
+        agent_after.is_empty(),
+        "killing the agent's key must end its authority; saw {agent_after:?}"
+    );
+    assert_eq!(
+        principal_after,
+        vec!["visible".to_string()],
+        "and the person behind it must be untouched -- that asymmetry is the \
+         entire point of an agent never being a principal in its own right; \
+         saw {principal_after:?}"
+    );
+}
+
+#[test]
+fn the_key_edge_records_a_reference_and_not_a_second_registry() {
+    let Some(url) = url() else {
+        eprintln!("skipped: TRUSTY_POLICY_PG_URL unset");
+        return;
+    };
+    let _db = db_lock();
+    let mut store = GrantStore::open(&url).expect("open");
+
+    store
+        .register_principal("agent:keyed", "agent", "")
+        .expect("register");
+    assert_eq!(
+        store.producer_oid_of("agent:keyed").expect("lookup"),
+        None,
+        "an unbound principal has no producer, and None is not the same as \
+         a producer named empty string"
+    );
+
+    store
+        .bind_key("agent:keyed", "1.3.6.1.4.1.99999.1")
+        .expect("bind");
+    let bound = store.producer_oid_of("agent:keyed").expect("lookup");
+
+    let unknown = store.bind_key("agent:missing", "1.3.6.1.4.1.99999.2");
+
+    let _ = store
+        .client()
+        .batch_execute("DELETE FROM trusty_policy.principal WHERE id = 'agent:keyed'");
+
+    assert_eq!(
+        bound.as_deref(),
+        Some("1.3.6.1.4.1.99999.1"),
+        "the edge must round-trip; resolving it to a public key is the \
+         producer registry's job, not this crate's"
+    );
+    assert!(
+        unknown.is_err(),
+        "a key bound to a principal that does not exist is a key nothing can \
+         revoke, so binding it must fail rather than create a dangling edge"
+    );
+}
+
+#[test]
+fn a_delegation_must_be_recorded_before_an_agent_can_use_it() {
+    let Some(url) = url() else {
+        eprintln!("skipped: TRUSTY_POLICY_PG_URL unset");
+        return;
+    };
+    let _db = db_lock();
+    let mut store = GrantStore::open(&url).expect("open");
+    let fx = Fixture::new("edge");
+    fx.set_up(&mut store);
+
+    let mut agent = grant("agent:e1", "board:9f2/calendar", Tier::Read);
+    agent.acts_for = Some("user:e1".into());
+    store.issue_registered(&agent).expect("issue agent");
+    store
+        .issue_registered(&grant("user:e1", "board:9f2/calendar", Tier::Read))
+        .expect("issue principal");
+
+    // Both grants exist and agree. The edge does not.
+    let without_edge = fx.read_as(store.client(), "agent:e1");
+    store.delegate("agent:e1", "user:e1").expect("delegate");
+    let with_edge = fx.read_as(store.client(), "agent:e1");
+    store
+        .revoke_delegation("agent:e1", "user:e1")
+        .expect("revoke delegation");
+    let after_revoke = fx.read_as(store.client(), "agent:e1");
+
+    store
+        .client()
+        .batch_execute("DELETE FROM trusty_policy.delegation")
+        .expect("clean");
+    fx.tear_down(&mut store);
+
+    assert!(
+        without_edge.is_empty(),
+        "two matching grants are not a delegation; the authority to act for \
+         someone has to be recorded, or it is merely claimed; saw \
+         {without_edge:?}"
+    );
+    assert!(
+        !with_edge.is_empty(),
+        "with the edge recorded, the intersection should permit; saw {with_edge:?}"
+    );
+    assert!(
+        after_revoke.is_empty(),
+        "and withdrawing it must take effect without touching either grant; \
+         saw {after_revoke:?}"
+    );
+}

crates/adapters/trusty-postgres/Cargo.toml

@@ -0,0 +1,27 @@
+[package]
+name = "trusty-postgres"
+version.workspace = true
+edition.workspace = true
+authors.workspace = true
+license.workspace = true
+repository.workspace = true
+rust-version.workspace = true
+description = "PostgreSQL adapter for Trusty. Three-table schema mirroring trusty-sqlite with optional TimescaleDB feature, OID-anchored producer identity, and CHECKPOINT verification primitive."
+
+[dependencies]
+trusty-core = { workspace = true }
+trusty-store = { workspace = true }
+postgres = { workspace = true }
+serde = { workspace = true }
+serde_json = { workspace = true }
+chrono = { workspace = true }
+thiserror = { workspace = true }
+tracing = { workspace = true }
+hex = { workspace = true }
+
+[dev-dependencies]
+trusty-store = { workspace = true, features = ["testing"] }
+
+[features]
+default = []
+timescale = []

crates/adapters/trusty-postgres/src/error.rs

@@ -0,0 +1,39 @@
+use thiserror::Error;
+use trusty_store::StoreError;
+
+#[derive(Debug, Error)]
+pub enum PostgresError {
+    #[error("postgres driver error: {0}")]
+    Driver(#[from] postgres::Error),
+
+    #[error("serialization error: {0}")]
+    Serialization(#[from] serde_json::Error),
+
+    #[error("malformed chain_id: {0}")]
+    MalformedChainId(String),
+
+    #[error("schema migration error: {0}")]
+    Migration(String),
+
+    #[error("integrity violation: {0}")]
+    IntegrityViolation(String),
+
+    #[error("not found: {0}")]
+    NotFound(String),
+
+    #[error("trusty-core error: {0}")]
+    Core(#[from] trusty_core::TrustyError),
+}
+
+pub type PostgresResult<T> = Result<T, PostgresError>;
+
+impl From<PostgresError> for StoreError {
+    fn from(err: PostgresError) -> Self {
+        match err {
+            PostgresError::NotFound(s) => StoreError::NotFound(s),
+            PostgresError::IntegrityViolation(s) => StoreError::IntegrityViolation(s),
+            PostgresError::Serialization(e) => StoreError::Serialization(e.to_string()),
+            other => StoreError::Backend(other.to_string()),
+        }
+    }
+}

crates/adapters/trusty-postgres/src/lib.rs

@@ -0,0 +1,31 @@
+//! PostgreSQL adapter for Trusty.
+//!
+//! Implements the `trusty_store::Store` trait against PostgreSQL 14+ using
+//! the synchronous `postgres` crate. Mirrors the three-table schema of
+//! `trusty-sqlite` (`provenance_envelope`, `hash_index`, `chain_tips`) with
+//! Postgres dialect and adds:
+//! - `chain_checkpoint` table for verification-layer checkpoints (#13).
+//! - `producer_identity` table for OID-anchored producer identity (#14, #22).
+//! - `schema_meta` table for planned schema migration versioning.
+//! - Optional TimescaleDB hypertable on `received_at` via `timescale` feature.
+//!
+//! Design memo: `docs/trusty-postgres-design.md`.
+//!
+//! TCB note: the trusted computing base added by this adapter is Postgres +
+//! libpq + the `postgres` Rust driver. Trusty chain math is backend-agnostic;
+//! v1 byte-shape is preserved by copying `raw_payload` verbatim as `TEXT`
+//! (never `JSONB`, which would normalize whitespace and key order).
+
+#![deny(clippy::all)]
+
+pub mod error;
+pub mod schema;
+pub mod store;
+pub mod trusty;
+
+pub use error::{PostgresError, PostgresResult};
+pub use store::TrustyPostgres;
+pub use trusty::{
+    AnchorInfo, AppendResult, BreakEvent, CheckpointRow, HistoryRow, IntegrityMismatch,
+    IntegrityReport, ProducerIdentity, RevocationRecord, RowSpec, SilentEntity, Trusty,
+};

crates/adapters/trusty-postgres/src/schema.rs

@@ -0,0 +1,144 @@
+//! Schema DDL for trusty-postgres.
+//!
+//! Mirrors the three-table layout of trusty-sqlite (provenance_envelope,
+//! hash_index, chain_tips) in Postgres dialect. Adds chain_checkpoint,
+//! producer_identity, and schema_meta. See docs/trusty-postgres-design.md.
+//!
+//! raw_payload MUST be TEXT, never JSONB -- JSONB normalizes whitespace
+//! and key order, which would break v1 byte-shape verification.
+
+pub const SCHEMA_VERSION: &str = "1";
+
+pub const DDL_V1: &[&str] = &[
+    // ----------------------------------------------------------------
+    // Core three-table schema (mirrors trusty-sqlite).
+    // ----------------------------------------------------------------
+    r#"CREATE TABLE IF NOT EXISTS provenance_envelope (
+        id                BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
+        chain_id          TEXT        NOT NULL,
+        entity_id         TEXT        NOT NULL,
+        event_type        TEXT        NOT NULL,
+        field_name        TEXT,
+        old_value         TEXT,
+        new_value         TEXT,
+        source_url        TEXT        NOT NULL DEFAULT '',
+        detected_at       TEXT        NOT NULL,
+        received_at       TEXT        NOT NULL,
+        extraction_method TEXT        NOT NULL DEFAULT 'trusty',
+        prev_hash         TEXT        NOT NULL,
+        raw_payload       TEXT,
+        row_hash          TEXT,
+        anchor_hash       TEXT,
+        sequence_int      BIGINT      NOT NULL DEFAULT 0
+    )"#,
+    r#"CREATE INDEX IF NOT EXISTS idx_pe_entity ON provenance_envelope(entity_id)"#,
+    r#"CREATE INDEX IF NOT EXISTS idx_pe_chain  ON provenance_envelope(chain_id)"#,
+    r#"CREATE INDEX IF NOT EXISTS idx_pe_entity_chain ON provenance_envelope(entity_id, chain_id)"#,
+    r#"CREATE INDEX IF NOT EXISTS idx_pe_row_hash ON provenance_envelope(row_hash)"#,
+    // Partial index accelerates breaks_since on Postgres (SQLite scans).
+    r#"CREATE INDEX IF NOT EXISTS idx_pe_break ON provenance_envelope(entity_id, detected_at)
+        WHERE event_type = 'BREAK'"#,
+    r#"CREATE TABLE IF NOT EXISTS hash_index (
+        id           BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
+        row_hash     TEXT    NOT NULL UNIQUE,
+        chain_id     TEXT    NOT NULL,
+        sequence_int BIGINT  NOT NULL,
+        entity_id    TEXT    NOT NULL,
+        recorded_at  TEXT    NOT NULL
+    )"#,
+    r#"CREATE INDEX IF NOT EXISTS idx_hi_entity ON hash_index(entity_id)"#,
+    r#"CREATE INDEX IF NOT EXISTS idx_hi_chain  ON hash_index(chain_id)"#,
+    r#"CREATE TABLE IF NOT EXISTS chain_tips (
+        entity_id        TEXT PRIMARY KEY,
+        current_tip_hash TEXT,
+        chain_id         TEXT,
+        tip_state        TEXT NOT NULL DEFAULT 'WARM'
+                          CHECK (tip_state IN ('UNKNOWN','COLD','WARM')),
+        updated_at       TEXT NOT NULL
+    )"#,
+    r#"CREATE INDEX IF NOT EXISTS idx_ct_chain ON chain_tips(chain_id)"#,
+    // ----------------------------------------------------------------
+    // Producer identity (#14, #22) -- OID-anchored. Nullable in the
+    // sense that rows are optional; table always exists.
+    // ----------------------------------------------------------------
+    r#"CREATE TABLE IF NOT EXISTS producer_identity (
+        producer_oid   TEXT PRIMARY KEY,
+        -- Key material in the format `key_format` declares. Named for
+        -- the raw Ed25519 case it was built for; a COSE credential from
+        -- a WebAuthn authenticator lives here too, and key_format is
+        -- what says which. Renaming the column would break every
+        -- existing installation for a cosmetic gain.
+        ed25519_pubkey BYTEA NOT NULL,
+        siphash_key    BYTEA NOT NULL,
+        registered_at  TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+        display_name   TEXT,
+        metadata       JSONB,
+        -- How ed25519_pubkey is encoded, and therefore how a signature
+        -- from it must be checked. A user enrolling through WebAuthn
+        -- registers a COSE key whose signature covers
+        -- authenticatorData || SHA-256(clientDataJSON), NOT the message,
+        -- so it cannot be checked as a bare signature. One column and
+        -- one verifier made that mistake available.
+        key_format     TEXT NOT NULL DEFAULT 'ed25519-raw'
+                       CHECK (key_format IN ('ed25519-raw','cose'))
+    )"#,
+    // Existing installations predate the column; CREATE TABLE IF NOT
+    // EXISTS does nothing for them, so it needs saying twice.
+    r#"ALTER TABLE producer_identity
+        ADD COLUMN IF NOT EXISTS key_format TEXT NOT NULL DEFAULT 'ed25519-raw'"#,
+    // ----------------------------------------------------------------
+    // Producer revocation (memo §6 / learn-LCG-ARCH-06) -- forward-
+    // only revocation per the Cert-Transparency stance: rows signed
+    // BEFORE revoked_at remain verifiable; rows signed AT or AFTER
+    // are rejected. The revocation event itself is also written as a
+    // chain envelope (event_type='REVOCATION') so the act is part of
+    // the audit chain. revocation_row_hash references that envelope.
+    // ----------------------------------------------------------------
+    r#"CREATE TABLE IF NOT EXISTS producer_revocation (
+        producer_oid         TEXT PRIMARY KEY,
+        revoked_at           TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+        revoked_pubkey       BYTEA NOT NULL,
+        reason               TEXT NOT NULL,
+        attested_by_pubkey   BYTEA NOT NULL,
+        revocation_row_hash  TEXT NOT NULL
+    )"#,
+    // ----------------------------------------------------------------
+    // Checkpoints (#13) -- verification-layer only; no row deletion.
+    // ----------------------------------------------------------------
+    r#"CREATE TABLE IF NOT EXISTS chain_checkpoint (
+        id              BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
+        chain_id        TEXT NOT NULL,
+        sequence_int    BIGINT NOT NULL,
+        row_hash        TEXT NOT NULL,
+        checkpoint_at   TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+        attested_by     TEXT NOT NULL,
+        attestation_sig BYTEA NOT NULL,
+        UNIQUE (chain_id, sequence_int)
+    )"#,
+    r#"CREATE INDEX IF NOT EXISTS idx_ckpt_chain ON chain_checkpoint(chain_id)"#,
+    // ----------------------------------------------------------------
+    // Schema meta (planned migration versioning).
+    // ----------------------------------------------------------------
+    r#"CREATE TABLE IF NOT EXISTS schema_meta (
+        key   TEXT PRIMARY KEY,
+        value TEXT NOT NULL
+    )"#,
+];
+
+/// Upserts the schema_version row. Runs on every open to declare the
+/// version this build expects.
+pub const DDL_SCHEMA_VERSION_UPSERT: &str = r#"
+    INSERT INTO schema_meta(key, value) VALUES ('schema_version', $1)
+    ON CONFLICT (key) DO UPDATE SET value = EXCLUDED.value
+"#;
+
+/// TimescaleDB hypertable creation (guarded by the `timescale` feature
+/// flag at the call site). Uses `if_not_exists` so it is idempotent.
+#[cfg(feature = "timescale")]
+pub const DDL_TIMESCALE_HYPERTABLE: &str = r#"
+    SELECT create_hypertable(
+        'provenance_envelope', 'received_at',
+        chunk_time_interval => INTERVAL '7 days',
+        if_not_exists => TRUE
+    )
+"#;

crates/adapters/trusty-postgres/src/store.rs

@@ -0,0 +1,463 @@
+//! `Store` trait implementation for PostgreSQL.
+//!
+//! Uses the synchronous `postgres` crate (libpq-backed, not tokio-postgres)
+//! per the `with_txn` sync-trait decision in docs/trusty-postgres-design.md
+//! section 7. Advisory locks serialize per-entity appends; different entities
+//! run concurrently.
+//!
+//! Interior mutability: the `postgres` crate's `Client::query*` methods
+//! require `&mut Client`, but the `Store` trait exposes several read-only
+//! methods (`last_row`, `iter_chain`, `get_tip`, `get_tip_for_entity`,
+//! `kv_cross_check`) that take `&self`. We wrap `Client` in `RefCell` to
+//! reconcile. This matches how `rusqlite::Connection` provides `&self`
+//! query APIs internally; we just make the bookkeeping explicit.
+//! `RefCell<Client>` is `Send` (not `Sync`), which satisfies the
+//! `Store: Send` bound.
+
+use std::cell::RefCell;
+
+use chrono::SecondsFormat;
+use postgres::{Client, NoTls, Transaction};
+use tracing::instrument;
+use trusty_store::{
+    KvCrossCheckReport, LastRow, RowInsert, Store, StoreError, StoreResult, StoredRow, TipRow,
+    TipUpsert,
+};
+
+use crate::error::PostgresError;
+use crate::schema::{DDL_SCHEMA_VERSION_UPSERT, DDL_V1, SCHEMA_VERSION};
+
+pub struct TrustyPostgres {
+    client: RefCell<Client>,
+}
+
+impl TrustyPostgres {
+    /// Open a connection and apply the v1 schema idempotently. Accepts any
+    /// standard libpq connection string, e.g.
+    /// `host=localhost user=postgres dbname=trusty password=...`.
+    pub fn open(conn_str: &str) -> Result<Self, PostgresError> {
+        let mut client = Client::connect(conn_str, NoTls)?;
+        apply_schema(&mut client)?;
+        Ok(Self {
+            client: RefCell::new(client),
+        })
+    }
+}
+
+fn apply_schema(client: &mut Client) -> Result<(), PostgresError> {
+    let mut txn = client.transaction()?;
+    for stmt in DDL_V1 {
+        txn.batch_execute(stmt)?;
+    }
+    txn.execute(DDL_SCHEMA_VERSION_UPSERT, &[&SCHEMA_VERSION])?;
+    txn.commit()?;
+
+    #[cfg(feature = "timescale")]
+    {
+        use crate::schema::DDL_TIMESCALE_HYPERTABLE;
+        client.batch_execute(DDL_TIMESCALE_HYPERTABLE)?;
+    }
+
+    Ok(())
+}
+
+fn now_iso_micros() -> String {
+    chrono::Utc::now().to_rfc3339_opts(SecondsFormat::Micros, true)
+}
+
+fn backend<E: std::fmt::Display>(e: E) -> StoreError {
+    StoreError::Backend(e.to_string())
+}
+
+// ------------------------------------------------------------
+// Row mapping helpers
+// ------------------------------------------------------------
+
+fn row_to_last(row: &postgres::Row) -> LastRow {
+    LastRow {
+        row_hash: row.get::<_, String>(0),
+        sequence: row.get::<_, i64>(1),
+    }
+}
+
+fn row_to_tip(row: &postgres::Row) -> TipRow {
+    TipRow {
+        entity_id: row.get::<_, String>(0),
+        chain_id: row.get::<_, Option<String>>(1).unwrap_or_default(),
+        current_tip_hash: row.get::<_, Option<String>>(2),
+        updated_at: row.get::<_, String>(3),
+    }
+}
+
+fn row_to_stored(row: &postgres::Row) -> StoredRow {
+    StoredRow {
+        id: row.get::<_, i64>(0),
+        entity_id: row.get::<_, String>(1),
+        chain_id: row.get::<_, String>(2),
+        event_type: row.get::<_, String>(3),
+        sequence: row.get::<_, i64>(4),
+        prev_hash: row.get::<_, String>(5),
+        row_hash: row.get::<_, Option<String>>(6),
+        anchor_hash: row.get::<_, Option<String>>(7),
+        raw_payload: row.get::<_, Option<String>>(8),
+        detected_at: row.get::<_, String>(9),
+        received_at: row.get::<_, String>(10),
+        source_url: row.get::<_, String>(11),
+        extraction_method: row.get::<_, String>(12),
+    }
+}
+
+const SQL_SELECT_LAST_ROW: &str = "
+    SELECT row_hash, sequence_int FROM provenance_envelope
+    WHERE entity_id = $1 AND event_type != 'BREAK' AND row_hash IS NOT NULL
+    ORDER BY id DESC LIMIT 1";
+
+const SQL_SELECT_CHAIN: &str = "
+    SELECT id, entity_id, chain_id, event_type, sequence_int, prev_hash,
+           row_hash, anchor_hash, raw_payload, detected_at, received_at,
+           source_url, extraction_method
+    FROM provenance_envelope
+    WHERE entity_id = $1
+    ORDER BY id ASC";
+
+const SQL_SELECT_TIP_BY_CHAIN: &str = "
+    SELECT entity_id, chain_id, current_tip_hash, updated_at
+    FROM chain_tips WHERE chain_id = $1";
+
+const SQL_SELECT_TIP_BY_ENTITY: &str = "
+    SELECT entity_id, chain_id, current_tip_hash, updated_at
+    FROM chain_tips WHERE entity_id = $1";
+
+const SQL_INSERT_ROW: &str = "
+    INSERT INTO provenance_envelope (
+        chain_id, entity_id, event_type, source_url, detected_at,
+        received_at, extraction_method, prev_hash, raw_payload,
+        row_hash, anchor_hash, sequence_int
+    ) VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11,$12)
+    RETURNING id";
+
+const SQL_INSERT_HASH_INDEX: &str = "
+    INSERT INTO hash_index (row_hash, chain_id, sequence_int, entity_id, recorded_at)
+    VALUES ($1,$2,$3,$4,$5)
+    ON CONFLICT (row_hash) DO NOTHING";
+
+const SQL_UPSERT_TIP: &str = "
+    INSERT INTO chain_tips (entity_id, current_tip_hash, chain_id, updated_at)
+    VALUES ($1, $2, $3, $4)
+    ON CONFLICT (entity_id) DO UPDATE SET
+        current_tip_hash = EXCLUDED.current_tip_hash,
+        chain_id         = EXCLUDED.chain_id,
+        updated_at       = EXCLUDED.updated_at";
+
+// ------------------------------------------------------------
+// Store trait impl
+// ------------------------------------------------------------
+
+impl Store for TrustyPostgres {
+    #[instrument(skip(self), fields(entity_id = %entity_id))]
+    fn last_row(&self, entity_id: &str) -> StoreResult<Option<LastRow>> {
+        let mut client = self.client.borrow_mut();
+        let row = client
+            .query_opt(SQL_SELECT_LAST_ROW, &[&entity_id])
+            .map_err(backend)?;
+        Ok(row.as_ref().map(row_to_last))
+    }
+
+    #[instrument(skip(self, row), fields(entity_id = %row.entity_id, seq = row.sequence))]
+    fn insert_row(&mut self, row: &RowInsert) -> StoreResult<i64> {
+        let client = self.client.get_mut();
+        let id: i64 = client
+            .query_one(
+                SQL_INSERT_ROW,
+                &[
+                    &row.chain_id,
+                    &row.entity_id,
+                    &row.event_type,
+                    &row.source_url,
+                    &row.detected_at,
+                    &row.received_at,
+                    &row.extraction_method,
+                    &row.prev_hash,
+                    &row.raw_payload,
+                    &row.row_hash,
+                    &row.anchor_hash,
+                    &row.sequence,
+                ],
+            )
+            .map_err(backend)?
+            .get(0);
+
+        if let Some(rh) = &row.row_hash {
+            client
+                .execute(
+                    SQL_INSERT_HASH_INDEX,
+                    &[
+                        rh,
+                        &row.chain_id,
+                        &row.sequence,
+                        &row.entity_id,
+                        &row.received_at,
+                    ],
+                )
+                .map_err(backend)?;
+        }
+
+        Ok(id)
+    }
+
+    fn iter_chain<'a>(
+        &'a self,
+        entity_id: &str,
+    ) -> StoreResult<Box<dyn Iterator<Item = StoreResult<StoredRow>> + 'a>> {
+        let mut client = self.client.borrow_mut();
+        let rows = client
+            .query(SQL_SELECT_CHAIN, &[&entity_id])
+            .map_err(backend)?;
+        let mapped: Vec<StoreResult<StoredRow>> =
+            rows.iter().map(|r| Ok(row_to_stored(r))).collect();
+        Ok(Box::new(mapped.into_iter()))
+    }
+
+    fn get_tip(&self, chain_id: &str) -> StoreResult<Option<TipRow>> {
+        let mut client = self.client.borrow_mut();
+        let row = client
+            .query_opt(SQL_SELECT_TIP_BY_CHAIN, &[&chain_id])
+            .map_err(backend)?;
+        Ok(row.as_ref().map(row_to_tip))
+    }
+
+    fn get_tip_for_entity(&self, entity_id: &str) -> StoreResult<Option<TipRow>> {
+        let mut client = self.client.borrow_mut();
+        let row = client
+            .query_opt(SQL_SELECT_TIP_BY_ENTITY, &[&entity_id])
+            .map_err(backend)?;
+        Ok(row.as_ref().map(row_to_tip))
+    }
+
+    #[instrument(skip(self, tip), fields(entity_id = %tip.entity_id, chain_id = %tip.chain_id))]
+    fn set_tip(&mut self, tip: &TipUpsert) -> StoreResult<()> {
+        let client = self.client.get_mut();
+        client
+            .execute(
+                SQL_UPSERT_TIP,
+                &[
+                    &tip.entity_id,
+                    &tip.current_tip_hash,
+                    &tip.chain_id,
+                    &now_iso_micros(),
+                ],
+            )
+            .map_err(backend)?;
+        Ok(())
+    }
+
+    fn kv_cross_check(&self) -> StoreResult<KvCrossCheckReport> {
+        let mut client = self.client.borrow_mut();
+
+        // Count sides.
+        let kv1_total: i64 = client
+            .query_one("SELECT COUNT(*) FROM hash_index", &[])
+            .map_err(backend)?
+            .get(0);
+        let kv2_total: i64 = client
+            .query_one("SELECT COUNT(*) FROM chain_tips", &[])
+            .map_err(backend)?
+            .get(0);
+
+        // Cross-check: every chain_tip's current_tip_hash must exist in hash_index
+        // under the same (entity_id, chain_id).
+        let rows = client
+            .query(
+                "SELECT ct.entity_id, ct.chain_id, ct.current_tip_hash
+                 FROM chain_tips ct
+                 WHERE ct.current_tip_hash IS NOT NULL",
+                &[],
+            )
+            .map_err(backend)?;
+
+        let mut mismatches: Vec<String> = Vec::new();
+        let mut entities_checked = 0usize;
+        for row in rows.iter() {
+            entities_checked += 1;
+            let entity_id: String = row.get(0);
+            let chain_id: Option<String> = row.get(1);
+            let tip_hash: String = row.get(2);
+            let chain_id = chain_id.unwrap_or_default();
+
+            let ok: Option<i64> = client
+                .query_opt(
+                    "SELECT 1 FROM hash_index
+                     WHERE row_hash = $1 AND entity_id = $2 AND chain_id = $3",
+                    &[&tip_hash, &entity_id, &chain_id],
+                )
+                .map_err(backend)?
+                .map(|r| r.get(0));
+            if ok.is_none() {
+                mismatches.push(format!(
+                    "entity={} chain={} tip={} not in hash_index",
+                    entity_id, chain_id, tip_hash
+                ));
+            }
+        }
+
+        Ok(KvCrossCheckReport {
+            ok: mismatches.is_empty(),
+            kv1_total_hashes: kv1_total as usize,
+            kv2_total_entities: kv2_total as usize,
+            entities_checked,
+            mismatches,
+        })
+    }
+
+    #[instrument(skip(self, f))]
+    fn with_txn(
+        &mut self,
+        f: &mut dyn FnMut(&mut dyn Store) -> StoreResult<()>,
+    ) -> StoreResult<()> {
+        let client = self.client.get_mut();
+        let mut txn = client.transaction().map_err(backend)?;
+        let result = {
+            let mut wrapper = TxnStore {
+                txn: RefCell::new(&mut txn),
+            };
+            f(&mut wrapper)
+            // `wrapper` dropped here, releasing the &mut txn borrow.
+        };
+        match result {
+            Ok(()) => txn.commit().map_err(backend),
+            Err(e) => {
+                let _ = txn.rollback();
+                Err(e)
+            }
+        }
+    }
+}
+
+// ------------------------------------------------------------
+// Transaction-scoped Store wrapper (for with_txn)
+//
+// Two lifetimes: 'a is how long this wrapper holds the &mut, 'c is
+// the underlying connection's lifetime (parameter on Transaction).
+// Conflating them (impl<'t> with Transaction<'t>) causes the borrow
+// checker to think the outer Transaction is still borrowed when we
+// try to commit() after f() returns. Splitting them lets the
+// wrapper's lifetime end at scope close while Transaction keeps
+// living on the outer stack frame.
+// ------------------------------------------------------------
+
+struct TxnStore<'t, 'c: 't> {
+    txn: RefCell<&'t mut Transaction<'c>>,
+}
+
+impl<'t, 'c: 't> Store for TxnStore<'t, 'c> {
+    fn last_row(&self, entity_id: &str) -> StoreResult<Option<LastRow>> {
+        let mut txn = self.txn.borrow_mut();
+        let row = txn
+            .query_opt(SQL_SELECT_LAST_ROW, &[&entity_id])
+            .map_err(backend)?;
+        Ok(row.as_ref().map(row_to_last))
+    }
+
+    fn insert_row(&mut self, row: &RowInsert) -> StoreResult<i64> {
+        let mut txn = self.txn.borrow_mut();
+        let id: i64 = txn
+            .query_one(
+                SQL_INSERT_ROW,
+                &[
+                    &row.chain_id,
+                    &row.entity_id,
+                    &row.event_type,
+                    &row.source_url,
+                    &row.detected_at,
+                    &row.received_at,
+                    &row.extraction_method,
+                    &row.prev_hash,
+                    &row.raw_payload,
+                    &row.row_hash,
+                    &row.anchor_hash,
+                    &row.sequence,
+                ],
+            )
+            .map_err(backend)?
+            .get(0);
+        if let Some(rh) = &row.row_hash {
+            txn.execute(
+                SQL_INSERT_HASH_INDEX,
+                &[
+                    rh,
+                    &row.chain_id,
+                    &row.sequence,
+                    &row.entity_id,
+                    &row.received_at,
+                ],
+            )
+            .map_err(backend)?;
+        }
+        Ok(id)
+    }
+
+    fn iter_chain<'a>(
+        &'a self,
+        entity_id: &str,
+    ) -> StoreResult<Box<dyn Iterator<Item = StoreResult<StoredRow>> + 'a>> {
+        let mut txn = self.txn.borrow_mut();
+        let rows = txn
+            .query(SQL_SELECT_CHAIN, &[&entity_id])
+            .map_err(backend)?;
+        let mapped: Vec<StoreResult<StoredRow>> =
+            rows.iter().map(|r| Ok(row_to_stored(r))).collect();
+        Ok(Box::new(mapped.into_iter()))
+    }
+
+    fn get_tip(&self, chain_id: &str) -> StoreResult<Option<TipRow>> {
+        let mut txn = self.txn.borrow_mut();
+        let row = txn
+            .query_opt(SQL_SELECT_TIP_BY_CHAIN, &[&chain_id])
+            .map_err(backend)?;
+        Ok(row.as_ref().map(row_to_tip))
+    }
+
+    fn get_tip_for_entity(&self, entity_id: &str) -> StoreResult<Option<TipRow>> {
+        let mut txn = self.txn.borrow_mut();
+        let row = txn
+            .query_opt(SQL_SELECT_TIP_BY_ENTITY, &[&entity_id])
+            .map_err(backend)?;
+        Ok(row.as_ref().map(row_to_tip))
+    }
+
+    fn set_tip(&mut self, tip: &TipUpsert) -> StoreResult<()> {
+        let mut txn = self.txn.borrow_mut();
+        txn.execute(
+            SQL_UPSERT_TIP,
+            &[
+                &tip.entity_id,
+                &tip.current_tip_hash,
+                &tip.chain_id,
+                &now_iso_micros(),
+            ],
+        )
+        .map_err(backend)?;
+        Ok(())
+    }
+
+    fn kv_cross_check(&self) -> StoreResult<KvCrossCheckReport> {
+        // Inside a txn we skip the cross-check -- the relevant checks happen
+        // at txn commit time via Postgres constraints. Return an OK stub.
+        Ok(KvCrossCheckReport {
+            ok: true,
+            kv1_total_hashes: 0,
+            kv2_total_entities: 0,
+            entities_checked: 0,
+            mismatches: Vec::new(),
+        })
+    }
+
+    fn with_txn(
+        &mut self,
+        _f: &mut dyn FnMut(&mut dyn Store) -> StoreResult<()>,
+    ) -> StoreResult<()> {
+        Err(StoreError::Backend(
+            "nested with_txn on an already-open transaction is not supported".into(),
+        ))
+    }
+}

crates/adapters/trusty-postgres/tests/conformance.rs

@@ -0,0 +1,55 @@
+//! Runs the shared `Store` conformance suite against a live Postgres.
+//!
+//! Gated behind the TRUSTY_PG_URL env var. Set it to a libpq connection
+//! string that points at a disposable test DB, e.g.:
+//!
+//!     TRUSTY_PG_URL="host=localhost user=postgres password=postgres dbname=trusty_test"
+//!     cargo test -p trusty-postgres --test conformance -- --nocapture
+//!
+//! If TRUSTY_PG_URL is not set, the test prints a skip notice and exits
+//! clean. This keeps the default `cargo test --workspace` hermetic.
+
+use trusty_postgres::TrustyPostgres;
+use trusty_store::testing::run_conformance;
+
+const ENV_URL: &str = "TRUSTY_PG_URL";
+
+fn reset_schema(store: &mut TrustyPostgres) {
+    // Drop-and-recreate so the suite starts from a known-empty state.
+    // Done by connecting to the same DB and issuing the drops directly.
+    let url = std::env::var(ENV_URL).expect("TRUSTY_PG_URL must be set");
+    let mut client = postgres::Client::connect(&url, postgres::NoTls).expect("connect");
+    client
+        .batch_execute(
+            "DROP TABLE IF EXISTS chain_checkpoint CASCADE;
+             DROP TABLE IF EXISTS producer_identity CASCADE;
+             DROP TABLE IF EXISTS chain_tips CASCADE;
+             DROP TABLE IF EXISTS hash_index CASCADE;
+             DROP TABLE IF EXISTS provenance_envelope CASCADE;
+             DROP TABLE IF EXISTS schema_meta CASCADE;",
+        )
+        .expect("drop tables");
+    let _ = store; // store gets recreated below
+}
+
+#[test]
+fn postgres_passes_store_conformance() {
+    let url = match std::env::var(ENV_URL) {
+        Ok(v) => v,
+        Err(_) => {
+            eprintln!(
+                "SKIP: set {} to run the conformance suite against a live Postgres",
+                ENV_URL
+            );
+            return;
+        }
+    };
+
+    // Initial open to ensure the tables exist.
+    let mut store = TrustyPostgres::open(&url).expect("open");
+    reset_schema(&mut store);
+    // Re-open so apply_schema runs against a clean DB.
+    let mut store = TrustyPostgres::open(&url).expect("re-open");
+
+    run_conformance(&mut store);
+}

crates/adapters/trusty-postgres/tests/integration.rs

@@ -0,0 +1,705 @@
+//! TRUSTY_PG_URL-gated integration tests for the higher-level
+//! `Trusty` surface on Postgres. Pays down the test debt accumulated
+//! across S16 cycles 4-7 (append_signed, append_batch + advisory
+//! lock, anchor, anchors_since, export_bundle, checkpoint,
+//! latest_checkpoint, verify_since_checkpoint).
+//!
+//! Setup mirrors `tests/conformance.rs`: when TRUSTY_PG_URL is unset
+//! the tests print SKIP and exit clean so `cargo test --workspace`
+//! stays hermetic. Set it to a libpq connection string pointing at a
+//! disposable test DB to actually run them.
+
+use serde_json::json;
+use trusty_core::{Ed25519Signer, ProofBundle, SecretKey, Signer};
+use trusty_postgres::{RowSpec, Trusty};
+
+const ENV_URL: &str = "TRUSTY_PG_URL";
+
+fn maybe_url() -> Option<String> {
+    std::env::var(ENV_URL).ok()
+}
+
+fn drop_tables(url: &str) {
+    let mut client = postgres::Client::connect(url, postgres::NoTls).expect("connect");
+    client
+        .batch_execute(
+            "DROP TABLE IF EXISTS chain_checkpoint CASCADE;
+             DROP TABLE IF EXISTS producer_revocation CASCADE;
+             DROP TABLE IF EXISTS producer_identity CASCADE;
+             DROP TABLE IF EXISTS chain_tips CASCADE;
+             DROP TABLE IF EXISTS hash_index CASCADE;
+             DROP TABLE IF EXISTS provenance_envelope CASCADE;
+             DROP TABLE IF EXISTS schema_meta CASCADE;",
+        )
+        .expect("drop tables");
+}
+
+fn open_clean(url: &str) -> Trusty {
+    drop_tables(url);
+    let key = SecretKey::from_bytes(b"0123456789abcdef").expect("key");
+    Trusty::open(url, key).expect("open Trusty")
+}
+
+fn signer() -> Ed25519Signer {
+    let seed = [9u8; 32];
+    Ed25519Signer::from_secret_bytes(&seed).expect("signer")
+}
+
+fn skip_if_no_url() -> Option<String> {
+    let url = maybe_url();
+    if url.is_none() {
+        eprintln!(
+            "SKIP: set {} to a Postgres connection string to run integration tests",
+            ENV_URL
+        );
+    }
+    url
+}
+
+#[test]
+fn append_signed_writes_v2_payload_and_verifies() {
+    let Some(url) = skip_if_no_url() else { return };
+    let mut t = open_clean(&url);
+    let s = signer();
+
+    let r = t
+        .append_signed("dev1", &json!({"v": 1}), "src", &s)
+        .expect("append_signed");
+    assert!(!r.chain_break);
+    assert_eq!(r.sequence, 0);
+    assert!(r.is_genesis);
+
+    // Payload should be v2 with a populated signature object. Read
+    // raw_payload back from the row directly to confirm.
+    let mut client = postgres::Client::connect(&url, postgres::NoTls).expect("connect");
+    let row = client
+        .query_one(
+            "SELECT raw_payload FROM provenance_envelope
+             WHERE entity_id = $1 ORDER BY id ASC LIMIT 1",
+            &[&"dev1"],
+        )
+        .expect("read row");
+    let raw: String = row.get(0);
+    assert!(raw.contains("\"payload_version\":2"), "raw = {}", raw);
+    assert!(raw.contains("\"alg\":\"ed25519\""), "raw = {}", raw);
+
+    let report = t.verify("dev1").expect("verify");
+    assert!(report.rows_valid, "{:?}", report.errors);
+    assert_eq!(report.row_count, 1);
+}
+
+#[test]
+fn append_batch_is_all_or_nothing_and_advisory_lock_present() {
+    let Some(url) = skip_if_no_url() else { return };
+    let mut t = open_clean(&url);
+
+    let d0 = json!({"v": 0});
+    let d1 = json!({"v": 1});
+    let d2 = json!({"v": 2});
+    let specs = vec![
+        RowSpec {
+            entity_id: "fleet-a",
+            data: &d0,
+            source_url: "src",
+        },
+        RowSpec {
+            entity_id: "fleet-a",
+            data: &d1,
+            source_url: "src",
+        },
+        RowSpec {
+            entity_id: "fleet-b",
+            data: &d2,
+            source_url: "src",
+        },
+    ];
+    let results = t.append_batch(&specs).expect("append_batch");
+    assert_eq!(results.len(), 3);
+    assert!(t.verify("fleet-a").expect("verify a").rows_valid);
+    assert!(t.verify("fleet-b").expect("verify b").rows_valid);
+
+    // Empty batch is a no-op.
+    let empty: Vec<RowSpec> = Vec::new();
+    let none = t.append_batch(&empty).expect("empty batch");
+    assert!(none.is_empty());
+}
+
+#[test]
+fn anchor_and_anchors_since_round_trip() {
+    let Some(url) = skip_if_no_url() else { return };
+    let mut t = open_clean(&url);
+
+    for i in 0..3 {
+        t.append("dev2", &json!({"i": i}), "src").expect("append");
+    }
+
+    let anchor = t.anchor("dev2").expect("anchor").expect("some");
+    assert_eq!(anchor.entity_id, "dev2");
+    assert!(anchor.chain_id.starts_with("chain_dev2_"));
+    assert!(anchor.tip_hash.is_some());
+
+    let entries = t.anchors_since("dev2", None).expect("anchors_since");
+    // Three appends -> three rows -> three anchor commitments.
+    assert_eq!(entries.len(), 3);
+    // Each entry has a distinct sequence and non-empty hash.
+    for (i, e) in entries.iter().enumerate() {
+        assert_eq!(e.sequence, i as i64);
+        assert!(!e.anchor_hash.is_empty());
+    }
+
+    // since-filter uses strict-greater-than on detected_at; a value
+    // beyond all rows yields the empty list.
+    let none = t
+        .anchors_since("dev2", Some("9999-01-01T00:00:00Z"))
+        .expect("anchors_since since=future");
+    assert!(none.is_empty());
+}
+
+#[test]
+fn export_bundle_round_trips_through_proof_bundle_verify() {
+    let Some(url) = skip_if_no_url() else { return };
+    let mut t = open_clean(&url);
+    let key = SecretKey::from_bytes(b"0123456789abcdef").expect("key");
+
+    for i in 0..4 {
+        t.append("dev3", &json!({"i": i}), "src").expect("append");
+    }
+
+    let bundle: ProofBundle = t.export_bundle("dev3", None, None).expect("export_bundle");
+    let report = bundle.verify(&key);
+    assert!(
+        report.rows_valid,
+        "bundle verify failed: {:?}",
+        report.errors
+    );
+    assert_eq!(report.row_count, 4);
+
+    // Sequence-bounded slice still verifies.
+    let slice = t
+        .export_bundle("dev3", Some(1), Some(2))
+        .expect("export_bundle slice");
+    let slice_report = slice.verify(&key);
+    assert!(slice_report.rows_valid, "{:?}", slice_report.errors);
+    assert_eq!(slice_report.row_count, 2);
+}
+
+#[test]
+fn checkpoint_writes_then_latest_returns_it() {
+    let Some(url) = skip_if_no_url() else { return };
+    let mut t = open_clean(&url);
+    let s = signer();
+
+    for i in 0..3 {
+        t.append("dev4", &json!({"i": i}), "src").expect("append");
+    }
+
+    let ckpt = t.checkpoint("dev4", "oid:1.2.3", &s).expect("checkpoint");
+    assert_eq!(ckpt.attested_by, "oid:1.2.3");
+    assert_eq!(ckpt.sequence_int, 2);
+    assert!(!ckpt.row_hash.is_empty());
+    assert!(!ckpt.attestation_sig.is_empty());
+
+    let latest = t
+        .latest_checkpoint(&ckpt.chain_id)
+        .expect("latest_checkpoint")
+        .expect("some");
+    assert_eq!(latest.id, ckpt.id);
+    assert_eq!(latest.sequence_int, ckpt.sequence_int);
+    assert_eq!(latest.row_hash, ckpt.row_hash);
+    assert_eq!(latest.attestation_sig, ckpt.attestation_sig);
+}
+
+#[test]
+fn verify_since_checkpoint_falls_back_when_no_checkpoint() {
+    let Some(url) = skip_if_no_url() else { return };
+    let mut t = open_clean(&url);
+
+    for i in 0..2 {
+        t.append("dev5", &json!({"i": i}), "src").expect("append");
+    }
+
+    // No checkpoint written -> verify_since_checkpoint must return
+    // the same shape as a full verify.
+    let full = t.verify("dev5").expect("verify");
+    let pruned = t.verify_since_checkpoint("dev5").expect("vsc");
+    assert_eq!(full.rows_valid, pruned.rows_valid);
+    assert_eq!(full.row_count, pruned.row_count);
+}
+
+#[test]
+fn verify_since_checkpoint_after_checkpoint_still_passes() {
+    let Some(url) = skip_if_no_url() else { return };
+    let mut t = open_clean(&url);
+    let s = signer();
+
+    // S16 cycle 9: verify_since_checkpoint authenticates the
+    // checkpoint against producer_identity before trusting the
+    // window-prune. Register the attestor first.
+    t.register_producer(
+        "oid:test",
+        &s.public_key_bytes(),
+        b"siphash_key_bytes_16",
+        Some("test attestor"),
+    )
+    .expect("register producer");
+
+    for i in 0..3 {
+        t.append("dev6", &json!({"i": i}), "src").expect("append");
+    }
+    t.checkpoint("dev6", "oid:test", &s).expect("checkpoint");
+    // Append more rows after the checkpoint.
+    for i in 3..5 {
+        t.append("dev6", &json!({"i": i}), "src").expect("append");
+    }
+
+    let report = t.verify_since_checkpoint("dev6").expect("vsc");
+    assert!(report.rows_valid, "{:?}", report.errors);
+    // Verify covers checkpoint.sequence (=2) forward -> rows 2,3,4
+    // -> 3 rows.
+    assert_eq!(report.row_count, 3);
+}
+
+#[test]
+fn producer_identity_register_and_lookup_round_trip() {
+    let Some(url) = skip_if_no_url() else { return };
+    let mut t = open_clean(&url);
+    let s = signer();
+
+    let pk = s.public_key_bytes();
+    t.register_producer("oid:1.2.3", &pk, b"sip-key-1", Some("agent-a"))
+        .expect("register");
+
+    let got = t
+        .lookup_producer("oid:1.2.3")
+        .expect("lookup")
+        .expect("some");
+    assert_eq!(got.producer_oid, "oid:1.2.3");
+    assert_eq!(got.ed25519_pubkey, pk);
+    assert_eq!(got.siphash_key, b"sip-key-1");
+    assert_eq!(got.display_name.as_deref(), Some("agent-a"));
+
+    // Re-register same OID is an UPSERT.
+    let s2 = trusty_core::Ed25519Signer::from_secret_bytes(&[3u8; 32]).expect("s2");
+    let pk2 = s2.public_key_bytes();
+    t.register_producer("oid:1.2.3", &pk2, b"sip-key-2", None)
+        .expect("re-register");
+    let updated = t
+        .lookup_producer("oid:1.2.3")
+        .expect("lookup2")
+        .expect("some");
+    assert_eq!(updated.ed25519_pubkey, pk2);
+    assert_eq!(updated.siphash_key, b"sip-key-2");
+    assert!(updated.display_name.is_none());
+
+    // Unknown OID yields None.
+    assert!(t.lookup_producer("oid:nope").expect("lookup3").is_none());
+}
+
+#[test]
+fn verify_since_checkpoint_rejects_unknown_attestor() {
+    let Some(url) = skip_if_no_url() else { return };
+    let mut t = open_clean(&url);
+    let s = signer();
+
+    // Append rows + write checkpoint WITHOUT registering the
+    // attestor first. The checkpoint row is in the table but
+    // attested_by has no producer_identity row.
+    for i in 0..2 {
+        t.append("dev7", &json!({"i": i}), "src").expect("append");
+    }
+    t.checkpoint("dev7", "oid:ghost", &s)
+        .expect("checkpoint write succeeds (lookup happens at verify)");
+
+    let report = t.verify_since_checkpoint("dev7").expect("vsc");
+    assert!(
+        !report.rows_valid,
+        "expected failure for unregistered attestor"
+    );
+    assert_eq!(report.errors.len(), 1);
+    let detail = match &report.errors[0].kind {
+        trusty_core::VerifyErrorType::SignatureInvalid { detail } => detail.clone(),
+        other => panic!("expected SignatureInvalid, got {:?}", other),
+    };
+    assert!(
+        detail.contains("not in producer_identity"),
+        "detail = {}",
+        detail
+    );
+}
+
+#[test]
+fn verify_with_producer_accepts_signed_rows_by_registered_producer() {
+    let Some(url) = skip_if_no_url() else { return };
+    let mut t = open_clean(&url);
+    let s = signer();
+
+    t.register_producer("oid:test", &s.public_key_bytes(), b"sip-key", None)
+        .expect("register");
+
+    // Three signed rows by the registered producer.
+    for i in 0..3 {
+        t.append_signed("dev-rsa1", &json!({"i": i}), "src", &s)
+            .expect("append_signed");
+    }
+
+    let report = t
+        .verify_with_producer("dev-rsa1", "oid:test")
+        .expect("verify_with_producer");
+    assert!(report.rows_valid, "{:?}", report.errors);
+    assert_eq!(report.row_count, 3);
+}
+
+#[test]
+fn verify_with_producer_rejects_row_signed_by_unauthorized_pubkey() {
+    let Some(url) = skip_if_no_url() else { return };
+    let mut t = open_clean(&url);
+    let registered = signer();
+    let imposter = trusty_core::Ed25519Signer::from_secret_bytes(&[77u8; 32]).expect("imp");
+
+    t.register_producer("oid:test", &registered.public_key_bytes(), b"sip-key", None)
+        .expect("register");
+
+    // Row 0 signed by the registered producer (legitimate).
+    t.append_signed("dev-rsa2", &json!({"i": 0}), "src", &registered)
+        .expect("append_signed legit");
+    // Row 1 signed by the imposter -- chain math still verifies, but
+    // verify_with_producer must flag it because the pk doesn't match
+    // producer_identity for oid:test.
+    t.append_signed("dev-rsa2", &json!({"i": 1}), "src", &imposter)
+        .expect("append_signed imposter");
+
+    let report = t
+        .verify_with_producer("dev-rsa2", "oid:test")
+        .expect("verify_with_producer");
+    assert!(!report.rows_valid, "expected rejection of unauthorized pk");
+    let unauthorized = report
+        .errors
+        .iter()
+        .find(|e| match &e.kind {
+            trusty_core::VerifyErrorType::SignatureInvalid { detail } => {
+                detail.contains("unauthorized pubkey")
+            }
+            _ => false,
+        })
+        .expect("expected an 'unauthorized pubkey' SignatureInvalid");
+    assert_eq!(unauthorized.sequence, 1);
+}
+
+#[test]
+fn verify_with_producer_rejects_row_after_revocation() {
+    let Some(url) = skip_if_no_url() else { return };
+    let mut t = open_clean(&url);
+    let s = signer();
+
+    t.register_producer("oid:test", &s.public_key_bytes(), b"sip-key", None)
+        .expect("register");
+
+    // Revoke FIRST, then append. The row's detected_at will be
+    // strictly greater than revoked_at, so it must reject.
+    t.revoke_producer("oid:test", "compromise", &s)
+        .expect("revoke");
+    std::thread::sleep(std::time::Duration::from_millis(50));
+    t.append_signed("dev-rsa3", &json!({"i": 0}), "src", &s)
+        .expect("append_signed after revoke");
+
+    let report = t
+        .verify_with_producer("dev-rsa3", "oid:test")
+        .expect("verify_with_producer");
+    assert!(!report.rows_valid);
+    let after_rev = report.errors.iter().find(|e| match &e.kind {
+        trusty_core::VerifyErrorType::SignatureInvalid { detail } => {
+            detail.contains("AT or AFTER revocation")
+        }
+        _ => false,
+    });
+    assert!(
+        after_rev.is_some(),
+        "expected post-revocation rejection; errors: {:?}",
+        report.errors
+    );
+}
+
+#[test]
+fn verify_with_producer_accepts_rows_signed_before_revocation() {
+    let Some(url) = skip_if_no_url() else { return };
+    let mut t = open_clean(&url);
+    let s = signer();
+
+    t.register_producer("oid:test", &s.public_key_bytes(), b"sip-key", None)
+        .expect("register");
+
+    // Append FIRST, then revoke. CT stance: past rows stay valid.
+    for i in 0..2 {
+        t.append_signed("dev-rsa4", &json!({"i": i}), "src", &s)
+            .expect("append_signed");
+    }
+    std::thread::sleep(std::time::Duration::from_millis(50));
+    t.revoke_producer("oid:test", "later compromise", &s)
+        .expect("revoke");
+
+    let report = t
+        .verify_with_producer("dev-rsa4", "oid:test")
+        .expect("verify_with_producer");
+    assert!(
+        report.rows_valid,
+        "expected pre-revocation rows to remain valid; errors: {:?}",
+        report.errors
+    );
+    assert_eq!(report.row_count, 2);
+}
+
+#[test]
+fn revoke_producer_round_trip_and_lookup() {
+    let Some(url) = skip_if_no_url() else { return };
+    let mut t = open_clean(&url);
+    let s = signer();
+
+    t.register_producer("oid:test", &s.public_key_bytes(), b"sip-key", None)
+        .expect("register");
+
+    // Not revoked yet.
+    assert!(t.lookup_revocation("oid:test").expect("lookup").is_none());
+
+    // Revoke. Returns RevocationRecord; producer_revocation row exists.
+    let rec = t
+        .revoke_producer("oid:test", "key compromise", &s)
+        .expect("revoke");
+    assert_eq!(rec.producer_oid, "oid:test");
+    assert_eq!(rec.reason, "key compromise");
+    assert_eq!(rec.revoked_pubkey, s.public_key_bytes());
+    assert_eq!(rec.attested_by_pubkey, s.public_key_bytes());
+    assert!(!rec.revocation_row_hash.is_empty());
+
+    // Lookup returns the same record.
+    let got = t
+        .lookup_revocation("oid:test")
+        .expect("lookup")
+        .expect("some");
+    assert_eq!(got.producer_oid, rec.producer_oid);
+    assert_eq!(got.revocation_row_hash, rec.revocation_row_hash);
+
+    // The REVOCATION envelope is on the per-user 'revocations' chain
+    // and verifies via the standard verify path.
+    let report = t.verify("revocations").expect("verify revocations chain");
+    assert!(report.rows_valid, "{:?}", report.errors);
+    assert_eq!(report.row_count, 1);
+
+    // Re-revoking the same OID UPSERTs (single row per OID).
+    let rec2 = t
+        .revoke_producer("oid:test", "second reason", &s)
+        .expect("re-revoke");
+    assert_eq!(rec2.reason, "second reason");
+    // Two REVOCATION envelopes on chain (append-only); one
+    // producer_revocation index row (UPSERT).
+    let report2 = t
+        .verify("revocations")
+        .expect("verify revocations chain v2");
+    assert!(report2.rows_valid);
+    assert_eq!(report2.row_count, 2);
+}
+
+#[test]
+fn revoke_producer_unknown_oid_errors() {
+    let Some(url) = skip_if_no_url() else { return };
+    let mut t = open_clean(&url);
+    let s = signer();
+    let err = t.revoke_producer("oid:ghost", "no such producer", &s);
+    assert!(err.is_err(), "expected NotFound for unregistered OID");
+}
+
+#[test]
+fn verify_since_checkpoint_rejects_revoked_attestor_after_revocation() {
+    let Some(url) = skip_if_no_url() else { return };
+    let mut t = open_clean(&url);
+    let s = signer();
+
+    t.register_producer("oid:test", &s.public_key_bytes(), b"sip-key", None)
+        .expect("register");
+
+    for i in 0..3 {
+        t.append("dev-rev1", &json!({"i": i}), "src")
+            .expect("append");
+    }
+
+    // Revoke FIRST, then write checkpoint. Per CT stance, this
+    // checkpoint's checkpoint_at >= revoked_at, so it must reject.
+    t.revoke_producer("oid:test", "compromise", &s)
+        .expect("revoke");
+    t.checkpoint("dev-rev1", "oid:test", &s)
+        .expect("checkpoint write succeeds (verify happens later)");
+
+    let report = t.verify_since_checkpoint("dev-rev1").expect("vsc");
+    assert!(!report.rows_valid, "expected rejection of revoked attestor");
+    let detail = match &report.errors[0].kind {
+        trusty_core::VerifyErrorType::SignatureInvalid { detail } => detail.clone(),
+        other => panic!("expected SignatureInvalid, got {:?}", other),
+    };
+    assert!(detail.contains("revoked at"), "detail = {}", detail);
+}
+
+#[test]
+fn verify_since_checkpoint_accepts_attestor_revoked_after_checkpoint() {
+    let Some(url) = skip_if_no_url() else { return };
+    let mut t = open_clean(&url);
+    let s = signer();
+
+    t.register_producer("oid:test", &s.public_key_bytes(), b"sip-key", None)
+        .expect("register");
+
+    for i in 0..3 {
+        t.append("dev-rev2", &json!({"i": i}), "src")
+            .expect("append");
+    }
+
+    // Checkpoint FIRST, then revoke. Per CT stance, this checkpoint's
+    // checkpoint_at < revoked_at, so it must still accept.
+    t.checkpoint("dev-rev2", "oid:test", &s)
+        .expect("checkpoint");
+    // Sleep briefly to ensure a strictly-greater revoked_at.
+    std::thread::sleep(std::time::Duration::from_millis(50));
+    t.revoke_producer("oid:test", "later compromise", &s)
+        .expect("revoke");
+
+    let report = t.verify_since_checkpoint("dev-rev2").expect("vsc");
+    assert!(
+        report.rows_valid,
+        "expected past checkpoint to remain valid; errors: {:?}",
+        report.errors
+    );
+}
+
+#[test]
+fn verify_since_checkpoint_rejects_tampered_attestation_sig() {
+    let Some(url) = skip_if_no_url() else { return };
+    let mut t = open_clean(&url);
+    let attestor = signer();
+    let imposter = trusty_core::Ed25519Signer::from_secret_bytes(&[42u8; 32]).expect("imp");
+
+    // Register the *attestor*'s pubkey under the OID, but write the
+    // checkpoint signed by the *imposter*. Sig verification must
+    // fail.
+    t.register_producer(
+        "oid:test",
+        &attestor.public_key_bytes(),
+        b"siphash-key-XYZ",
+        None,
+    )
+    .expect("register");
+
+    for i in 0..2 {
+        t.append("dev8", &json!({"i": i}), "src").expect("append");
+    }
+    t.checkpoint("dev8", "oid:test", &imposter)
+        .expect("checkpoint with imposter signer");
+
+    let report = t.verify_since_checkpoint("dev8").expect("vsc");
+    assert!(!report.rows_valid, "expected failure for tampered sig");
+    let detail = match &report.errors[0].kind {
+        trusty_core::VerifyErrorType::SignatureInvalid { detail } => detail.clone(),
+        other => panic!("expected SignatureInvalid, got {:?}", other),
+    };
+    assert!(
+        detail.contains("attestation_sig invalid"),
+        "detail = {}",
+        detail
+    );
+}
+
+// ---------------------------------------------------------------------
+// Per-entity lock on the single-append path.
+// ---------------------------------------------------------------------
+
+/// Two writers, two connections, one entity, at the same time.
+///
+/// Appending is read-tip, compute, insert, and those three steps are not
+/// atomic. Without a per-entity lock both writers read the same tip and
+/// both build on it, producing two rows that claim the same predecessor
+/// -- a fork in a structure whose whole promise is that there is one
+/// line.
+///
+/// The batch path has held a lock since it was written. The single
+/// path never did; the module header said "add before any multi-writer
+/// deployment", and nothing was enforcing it.
+#[test]
+fn concurrent_appends_to_one_entity_do_not_fork_the_chain() {
+    let Some(url) = maybe_url() else {
+        eprintln!("SKIP: {ENV_URL} unset");
+        return;
+    };
+    let entity = "concurrency-probe";
+
+    // A unique entity per run, so a previous run cannot make this pass
+    // and no cleanup accessor is needed on the public surface.
+    let entity = &format!(
+        "{entity}-{}",
+        std::time::SystemTime::now()
+            .duration_since(std::time::UNIX_EPOCH)
+            .unwrap()
+            .as_nanos()
+    );
+
+    // Apply the schema ONCE. Four threads each running
+    // CREATE TABLE IF NOT EXISTS collide in the catalog with "tuple
+    // concurrently updated" -- a real property of concurrent DDL, and
+    // not what this test is about.
+    {
+        let key = SecretKey::from_bytes(b"0123456789abcdef").expect("key");
+        Trusty::open(&url, key).expect("apply schema");
+    }
+
+    const WRITERS: usize = 4;
+    const EACH: usize = 6;
+
+    let handles: Vec<_> = (0..WRITERS)
+        .map(|w| {
+            let url = url.clone();
+            let entity = entity.clone();
+            std::thread::spawn(move || {
+                let key = SecretKey::from_bytes(b"0123456789abcdef").expect("key");
+                let mut t = Trusty::open(&url, key).expect("open");
+                for i in 0..EACH {
+                    t.append(&entity, &json!({ "writer": w, "i": i }), "test://")
+                        .expect("append");
+                }
+            })
+        })
+        .collect();
+    for h in handles {
+        h.join().expect("writer panicked");
+    }
+
+    let key = SecretKey::from_bytes(b"0123456789abcdef").expect("key");
+    let mut t = Trusty::open(&url, key).expect("open");
+    let bundle = t.export_bundle(entity, None, None).expect("export");
+    let rows: Vec<_> = bundle
+        .rows
+        .iter()
+        .filter(|r| r.event_type != "BREAK")
+        .collect();
+
+    assert_eq!(
+        rows.len(),
+        WRITERS * EACH,
+        "every append must land exactly once"
+    );
+
+    // The real assertion: no two rows may claim the same predecessor.
+    // That is what a lost update looks like from the outside.
+    let mut prevs: Vec<&str> = rows.iter().map(|r| r.prev_hash.as_str()).collect();
+    prevs.sort_unstable();
+    let before = prevs.len();
+    prevs.dedup();
+    assert_eq!(
+        prevs.len(),
+        before,
+        "two rows claim the same prev_hash, so two writers read the same tip \
+         and both built on it -- the chain forked, which is exactly what the \
+         per-entity lock exists to prevent"
+    );
+
+    let report = t.verify(entity).expect("verify");
+    assert!(
+        report.rows_valid,
+        "and the chain must still verify end to end: {report:?}"
+    );
+}

crates/adapters/trusty-sqlite/Cargo.toml

@@ -0,0 +1,22 @@
+[package]
+name = "trusty-sqlite"
+version.workspace = true
+edition.workspace = true
+authors.workspace = true
+license.workspace = true
+repository.workspace = true
+rust-version.workspace = true
+description = "SQLite adapter for Trusty. Three-table schema (provenance_envelope, hash_index, chain_tips) with KV cross-check."
+
+[dependencies]
+trusty-core = { workspace = true }
+trusty-store = { workspace = true }
+rusqlite = { workspace = true }
+serde = { workspace = true }
+serde_json = { workspace = true }
+chrono = { workspace = true }
+thiserror = { workspace = true }
+hex = { workspace = true }
+
+[dev-dependencies]
+trusty-store = { workspace = true, features = ["testing"] }

crates/adapters/trusty-sqlite/examples/bench_append.rs

@@ -0,0 +1,83 @@
+// ============================================================
+// EXAMPLE: bench_append
+// PURPOSE: Measure fsync-amortization speedup of append_batch over
+//          a loop of append() calls on a file-backed SQLite DB.
+//          Intended for ad-hoc inspection, not CI regression
+//          tracking (no criterion / no gate). Prints rows/sec +
+//          speedup ratio.
+//
+// RUN:     cargo run -p trusty-sqlite --release --example bench_append
+//          (release mode matters: debug rusqlite is much slower)
+// ============================================================
+
+use serde_json::json;
+use std::time::Instant;
+use trusty_core::SecretKey;
+use trusty_sqlite::{RowSpec, Trusty};
+
+const N: usize = 1000;
+
+fn tmp_db_path(tag: &str) -> std::path::PathBuf {
+    let mut p = std::env::temp_dir();
+    let nanos = std::time::SystemTime::now()
+        .duration_since(std::time::UNIX_EPOCH)
+        .map(|d| d.as_nanos())
+        .unwrap_or(0);
+    p.push(format!("trusty_bench_{tag}_{nanos}.db"));
+    p
+}
+
+fn key() -> SecretKey {
+    SecretKey::new(*b"0123456789abcdef")
+}
+
+fn bench_single_row(path: &std::path::Path) -> f64 {
+    let mut t = Trusty::open(path, key()).expect("open");
+    // Warmup: one genesis so we are measuring mutations, not first-row setup.
+    t.append("acme", &json!({"warmup": true}), "s")
+        .expect("warmup");
+    let start = Instant::now();
+    for i in 0..N {
+        t.append("acme", &json!({"i": i}), "s").expect("append ok");
+    }
+    let elapsed = start.elapsed().as_secs_f64();
+    N as f64 / elapsed
+}
+
+fn bench_batch(path: &std::path::Path) -> f64 {
+    let mut t = Trusty::open(path, key()).expect("open");
+    t.append("acme", &json!({"warmup": true}), "s")
+        .expect("warmup");
+    let values: Vec<serde_json::Value> = (0..N).map(|i| json!({"i": i})).collect();
+    let specs: Vec<RowSpec> = values
+        .iter()
+        .map(|v| RowSpec {
+            entity_id: "acme",
+            data: v,
+            source_url: "s",
+        })
+        .collect();
+    let start = Instant::now();
+    t.append_batch(&specs).expect("batch ok");
+    let elapsed = start.elapsed().as_secs_f64();
+    N as f64 / elapsed
+}
+
+fn main() {
+    let p1 = tmp_db_path("single");
+    let p2 = tmp_db_path("batch");
+    println!("trusty-sqlite append benchmark (N = {N}, file-backed, WAL + FULL sync)");
+    println!("single-row db : {}", p1.display());
+    println!("batch     db  : {}", p2.display());
+    println!();
+
+    let single_rps = bench_single_row(&p1);
+    let batch_rps = bench_batch(&p2);
+    let speedup = batch_rps / single_rps;
+
+    println!("single-row append : {single_rps:>10.1} rows/sec");
+    println!("append_batch      : {batch_rps:>10.1} rows/sec");
+    println!("speedup           : {speedup:>10.2}x");
+    println!();
+    println!("(cleanup: rm {} {})", p1.display(), p2.display());
+}

crates/adapters/trusty-sqlite/examples/device_signer.rs

@@ -0,0 +1,195 @@
+// ============================================================
+// EXAMPLE: device_signer
+// PURPOSE: Walk the device-signer provisioning pattern end to end.
+//          Enroll -> sign -> rotate -> revoke. Demonstrates how an
+//          application keeps a signer_registry alongside trusty's
+//          chain tables, using a second rusqlite::Connection to
+//          the same file.
+//
+// See `docs/device-signer-provisioning.md` for the conceptual doc.
+//
+// RUN: cargo run -p trusty-sqlite --example device_signer
+// ============================================================
+
+use rusqlite::{params, Connection};
+use serde_json::{json, Value};
+use std::path::PathBuf;
+use trusty_core::{Ed25519Signer, Ed25519Verifier, SecretKey, Signer, Verifier};
+use trusty_sqlite::Trusty;
+
+fn tmp_db_path() -> PathBuf {
+    let mut p = std::env::temp_dir();
+    let nanos = std::time::SystemTime::now()
+        .duration_since(std::time::UNIX_EPOCH)
+        .map(|d| d.as_nanos())
+        .unwrap_or(0);
+    p.push(format!("trusty_device_signer_demo_{nanos}.db"));
+    p
+}
+
+fn now_iso() -> String {
+    chrono::Utc::now().to_rfc3339_opts(chrono::SecondsFormat::Secs, true)
+}
+
+fn init_registry(conn: &Connection) {
+    conn.execute_batch(
+        "CREATE TABLE IF NOT EXISTS signer_registry (
+            device_id   TEXT PRIMARY KEY,
+            public_key  TEXT NOT NULL,
+            enrolled_at TEXT NOT NULL,
+            rotated_at  TEXT,
+            revoked_at  TEXT,
+            note        TEXT
+         );
+         CREATE INDEX IF NOT EXISTS idx_sr_pk ON signer_registry(public_key);",
+    )
+    .expect("registry schema");
+}
+
+fn enroll(conn: &Connection, device_id: &str, pk_hex: &str, note: &str) {
+    conn.execute(
+        "INSERT INTO signer_registry (device_id, public_key, enrolled_at, note)
+         VALUES (?1, ?2, ?3, ?4)",
+        params![device_id, pk_hex, now_iso(), note],
+    )
+    .expect("enroll");
+    println!("  [enrolled]  device={device_id}  pk={pk_hex:.16}...  ({note})");
+}
+
+fn rotate(conn: &Connection, old_device_id: &str, new_device_id: &str, new_pk_hex: &str) {
+    conn.execute(
+        "UPDATE signer_registry SET rotated_at = ?1 WHERE device_id = ?2",
+        params![now_iso(), old_device_id],
+    )
+    .expect("mark rotated");
+    enroll(conn, new_device_id, new_pk_hex, "post-rotation");
+    println!("  [rotated]   {old_device_id} -> {new_device_id}");
+}
+
+fn revoke(conn: &Connection, device_id: &str, reason: &str) {
+    conn.execute(
+        "UPDATE signer_registry SET revoked_at = ?1, note = ?2 WHERE device_id = ?3",
+        params![now_iso(), format!("REVOKED: {reason}"), device_id],
+    )
+    .expect("revoke");
+    println!("  [revoked]   device={device_id}  reason={reason}");
+}
+
+fn trust_status_for_pk(conn: &Connection, pk_hex: &str) -> String {
+    conn.query_row(
+        "SELECT device_id, enrolled_at, rotated_at, revoked_at
+         FROM signer_registry WHERE public_key = ?1",
+        params![pk_hex],
+        |r| {
+            let dev: String = r.get(0)?;
+            let enrolled: String = r.get(1)?;
+            let rotated: Option<String> = r.get(2)?;
+            let revoked: Option<String> = r.get(3)?;
+            Ok(match (rotated, revoked) {
+                (_, Some(rev)) => format!("REVOKED({dev}, at={rev})"),
+                (Some(rot), _) => format!("ROTATED({dev}, at={rot}) -- old-key rows still verify"),
+                _ => format!("ACTIVE({dev}, since={enrolled})"),
+            })
+        },
+    )
+    .unwrap_or_else(|_| "UNKNOWN (pk not in registry)".to_string())
+}
+
+fn sign_and_append(t: &mut Trusty, entity: &str, data: &Value, signer: &Ed25519Signer) {
+    let r = t
+        .append_signed(entity, data, "sensor://demo", signer)
+        .expect("signed append");
+    println!(
+        "  [appended]  seq={} row_hash={:.16}... pk={:.16}...",
+        r.sequence,
+        r.row_hash,
+        hex::encode(signer.public_key_bytes())
+    );
+}
+
+fn main() {
+    let path = tmp_db_path();
+    println!("trusty device-signer provisioning demo");
+    println!("db: {}\n", path.display());
+
+    // Trusty owns one Connection; the app opens a second one for the
+    // registry. WAL mode (set by trusty-sqlite's schema) allows this
+    // cleanly.
+    let mut t = Trusty::open(&path, SecretKey::new(*b"0123456789abcdef")).expect("open trusty");
+    let app_conn = Connection::open(&path).expect("open app conn");
+    init_registry(&app_conn);
+
+    // --- 1. Enroll device_001 -------------------------------------
+    println!("step 1: enroll device_001");
+    let signer_v1 = Ed25519Signer::generate();
+    let pk_v1_hex = hex::encode(signer_v1.public_key_bytes());
+    enroll(&app_conn, "device_001", &pk_v1_hex, "initial enrollment");
+
+    // --- 2. Sign and append with v1 key ---------------------------
+    println!("\nstep 2: append two signed rows with v1 key");
+    sign_and_append(&mut t, "sensor_a", &json!({"temp": 21.4}), &signer_v1);
+    sign_and_append(&mut t, "sensor_a", &json!({"temp": 21.5}), &signer_v1);
+
+    // --- 3. Rotate: new key, new registry entry -------------------
+    println!("\nstep 3: rotate device_001 -> device_001_v2");
+    let signer_v2 = Ed25519Signer::generate();
+    let pk_v2_hex = hex::encode(signer_v2.public_key_bytes());
+    rotate(&app_conn, "device_001", "device_001_v2", &pk_v2_hex);
+
+    // --- 4. Append more rows with v2 key --------------------------
+    println!("\nstep 4: append two more signed rows with v2 key");
+    sign_and_append(&mut t, "sensor_a", &json!({"temp": 21.7}), &signer_v2);
+    sign_and_append(&mut t, "sensor_a", &json!({"temp": 21.9}), &signer_v2);
+
+    // --- 5. Revoke v1 (simulated compromise) ----------------------
+    println!("\nstep 5: simulated compromise of v1 secret, revoke it");
+    revoke(&app_conn, "device_001", "secret leaked from retired device");
+
+    // --- 6. Verify chain: math is still sound ---------------------
+    println!("\nstep 6: chain verify -- cryptography is unaffected by registry policy");
+    let report = t.verify("sensor_a").expect("verify");
+    println!(
+        "  chain verify: ok={} row_count={} (revocation is app-policy, not chain-policy)",
+        report.rows_valid, report.row_count
+    );
+
+    // --- 7. Registry overlay: per-row trust report ----------------
+    println!("\nstep 7: registry-overlay trust report for each chain row");
+    let bundle = t.export_bundle("sensor_a", None, None).expect("bundle");
+    for row in &bundle.rows {
+        if let Some(raw) = &row.raw_payload {
+            let parsed: Value = serde_json::from_str(raw).expect("payload json");
+            let pk_hex = parsed
+                .get("signatures")
+                .and_then(|s| s.as_array())
+                .and_then(|a| a.first())
+                .and_then(|o| o.get("pk"))
+                .and_then(|v| v.as_str());
+            match pk_hex {
+                Some(pk) => {
+                    println!(
+                        "  seq={} event={} -> {}",
+                        row.sequence,
+                        row.event_type,
+                        trust_status_for_pk(&app_conn, pk)
+                    );
+                }
+                None => {
+                    println!(
+                        "  seq={} event={} -> (unsigned v1 row)",
+                        row.sequence, row.event_type
+                    );
+                }
+            }
+        }
+    }
+
+    // --- 8. Sanity: Ed25519Verifier round-trips on an isolated sig
+    println!("\nstep 8: sanity -- Ed25519Verifier on the v2 public key works end-to-end");
+    let msg = b"independent verifier check";
+    let sig = signer_v2.sign(msg);
+    Ed25519Verifier::verify(&signer_v2.public_key_bytes(), msg, &sig).expect("independent verify");
+    println!("  standalone verify: ok");
+
+    println!("\ndone. (cleanup: rm {})", path.display());
+}

crates/adapters/trusty-sqlite/examples/twin_coupling.rs

@@ -0,0 +1,186 @@
+// ============================================================
+// EXAMPLE: twin_coupling
+// PURPOSE: Demonstrate the data-convention pattern for linking a
+//          digital-twin computation row back to the sensor rows
+//          that fed it. Sensor chain and twin chain are independent
+//          trusty entities. The twin row carries a `source_refs`
+//          array in its `data` field so an external verifier can
+//          check the linkage from two ProofBundles alone -- no
+//          extra tables, no schema changes.
+//
+// See `docs/twin-coupling.md` for the conceptual doc.
+//
+// RUN: cargo run -p trusty-sqlite --example twin_coupling
+// ============================================================
+
+use serde_json::{json, Value};
+use std::path::PathBuf;
+use trusty_core::SecretKey;
+use trusty_sqlite::Trusty;
+
+fn tmp_db_path() -> PathBuf {
+    let mut p = std::env::temp_dir();
+    let nanos = std::time::SystemTime::now()
+        .duration_since(std::time::UNIX_EPOCH)
+        .map(|d| d.as_nanos())
+        .unwrap_or(0);
+    p.push(format!("trusty_twin_coupling_demo_{nanos}.db"));
+    p
+}
+
+fn main() {
+    let path = tmp_db_path();
+    println!("trusty twin-coupling demo");
+    println!("db: {}\n", path.display());
+
+    let sip_key = SecretKey::new(*b"0123456789abcdef");
+    let mut t = Trusty::open(&path, sip_key.clone()).expect("open trusty");
+
+    // ----------------------------------------------------------------
+    // step 1: append sensor readings to the sensor chain
+    // ----------------------------------------------------------------
+    println!("step 1: append three sensor readings");
+
+    let r0 = t
+        .append("sensor-001", &json!({"temp_c": 21.1}), "iot://sensor-001")
+        .expect("append r0");
+    println!(
+        "  seq={} chain_id={:.16}... row_hash={}",
+        r0.sequence, r0.chain_id, r0.row_hash
+    );
+
+    let r1 = t
+        .append("sensor-001", &json!({"temp_c": 21.4}), "iot://sensor-001")
+        .expect("append r1");
+    println!(
+        "  seq={} chain_id={:.16}... row_hash={}",
+        r1.sequence, r1.chain_id, r1.row_hash
+    );
+
+    let r2 = t
+        .append("sensor-001", &json!({"temp_c": 21.6}), "iot://sensor-001")
+        .expect("append r2");
+    println!(
+        "  seq={} chain_id={:.16}... row_hash={}",
+        r2.sequence, r2.chain_id, r2.row_hash
+    );
+
+    // ----------------------------------------------------------------
+    // step 2: twin computation cites the three sensor rows by
+    //         chain_id + sequence + row_hash (data convention)
+    // ----------------------------------------------------------------
+    println!("\nstep 2: append twin computation row with source_refs");
+
+    let avg = (21.1_f64 + 21.4 + 21.6) / 3.0;
+    let twin_data = json!({
+        "computation": "rolling_avg_temp_c",
+        "result": (avg * 100.0).round() / 100.0,
+        "source_refs": [
+            {"chain_id": r0.chain_id, "sequence": r0.sequence, "row_hash": r0.row_hash},
+            {"chain_id": r1.chain_id, "sequence": r1.sequence, "row_hash": r1.row_hash},
+            {"chain_id": r2.chain_id, "sequence": r2.sequence, "row_hash": r2.row_hash},
+        ]
+    });
+
+    let tw = t
+        .append("twin-001", &twin_data, "omniverse://twin-001")
+        .expect("append twin");
+    println!("  seq={} row_hash={}", tw.sequence, tw.row_hash);
+
+    // ----------------------------------------------------------------
+    // step 3: verify both chains independently
+    // ----------------------------------------------------------------
+    println!("\nstep 3: verify both chains");
+
+    let sensor_report = t.verify("sensor-001").expect("verify sensor");
+    println!(
+        "  sensor-001: ok={} rows={}",
+        sensor_report.rows_valid, sensor_report.row_count
+    );
+    assert!(sensor_report.rows_valid, "sensor chain verification failed");
+
+    let twin_report = t.verify("twin-001").expect("verify twin");
+    println!(
+        "  twin-001:   ok={} rows={}",
+        twin_report.rows_valid, twin_report.row_count
+    );
+    assert!(twin_report.rows_valid, "twin chain verification failed");
+
+    // ----------------------------------------------------------------
+    // step 4: external-verifier cross-chain check
+    //         Export both ProofBundles; walk twin source_refs and
+    //         confirm each referenced row_hash is present and matches
+    //         in the sensor bundle.
+    // ----------------------------------------------------------------
+    println!("\nstep 4: cross-chain verify from ProofBundles");
+
+    let sensor_bundle = t
+        .export_bundle("sensor-001", None, None)
+        .expect("sensor bundle");
+    let twin_bundle = t
+        .export_bundle("twin-001", None, None)
+        .expect("twin bundle");
+
+    let sensor_verify = sensor_bundle.verify(&sip_key);
+    let twin_verify = twin_bundle.verify(&sip_key);
+    println!(
+        "  sensor bundle verify: ok={} rows={}",
+        sensor_verify.rows_valid, sensor_verify.row_count
+    );
+    println!(
+        "  twin bundle verify:   ok={} rows={}",
+        twin_verify.rows_valid, twin_verify.row_count
+    );
+    assert!(sensor_verify.rows_valid);
+    assert!(twin_verify.rows_valid);
+
+    // Walk twin rows; for each source_ref, confirm the sensor bundle
+    // contains a row at that sequence with a matching row_hash.
+    let mut refs_checked = 0usize;
+    for twin_row in twin_bundle.rows.iter().filter(|r| r.sequence >= 0) {
+        let payload: Value = twin_row
+            .raw_payload
+            .as_ref()
+            .and_then(|p| serde_json::from_str(p).ok())
+            .expect("twin row has no payload");
+
+        let data = payload.get("data").expect("payload has no data");
+        let refs = match data.get("source_refs").and_then(|v| v.as_array()) {
+            Some(r) => r,
+            None => continue,
+        };
+
+        for sr in refs {
+            let ref_chain_id = sr["chain_id"].as_str().expect("chain_id");
+            let ref_seq = sr["sequence"].as_i64().expect("sequence");
+            let ref_hash = sr["row_hash"].as_str().expect("row_hash");
+
+            let matched = sensor_bundle.rows.iter().find(|r| {
+                r.chain_id == ref_chain_id
+                    && r.sequence == ref_seq
+                    && r.row_hash.as_deref() == Some(ref_hash)
+            });
+
+            match matched {
+                Some(m) => {
+                    println!(
+                        "  source_ref ok: seq={} row_hash={} (sensor chain_id={:.16}...)",
+                        m.sequence, ref_hash, ref_chain_id
+                    );
+                    refs_checked += 1;
+                }
+                None => {
+                    panic!(
+                        "source_ref not found in sensor bundle: chain_id={} seq={} row_hash={}",
+                        ref_chain_id, ref_seq, ref_hash
+                    );
+                }
+            }
+        }
+    }
+
+    println!("\n  {refs_checked} source_refs verified across ProofBundles");
+    assert_eq!(refs_checked, 3, "expected 3 source_refs checked");
+
+    println!("\ndone. (cleanup: rm {})", path.display());
+}

crates/adapters/trusty-sqlite/src/error.rs

@@ -0,0 +1,30 @@
+use thiserror::Error;
+
+#[derive(Debug, Error)]
+pub enum SqliteError {
+    #[error("sqlite error: {0}")]
+    Sqlite(#[from] rusqlite::Error),
+    #[error("trusty-core error: {0}")]
+    Core(#[from] trusty_core::TrustyError),
+    #[error("json error: {0}")]
+    Json(#[from] serde_json::Error),
+    #[error("chain tip missing row_hash for entity {0}")]
+    MissingTipHash(String),
+    #[error("malformed chain id: {0}")]
+    MalformedChainId(String),
+    #[error("not found: {0}")]
+    NotFound(String),
+    /// The producer enrolled a credential this path cannot check.
+    ///
+    /// Separate from a failed verification on purpose: a failure invites
+    /// "wrong key, try another", while this says the check itself is the
+    /// wrong one for that credential.
+    #[error("unsupported credential: {0}")]
+    UnsupportedCredential(String),
+    #[error(
+        "store is signed-only: an unsigned append to entity {0} was refused.          Use append_signed / append_with_method_signed."
+    )]
+    UnsignedAppendRefused(String),
+}
+
+pub type SqliteResult<T> = Result<T, SqliteError>;

crates/adapters/trusty-sqlite/src/lib.rs

@@ -0,0 +1,26 @@
+//! SQLite-backed Trusty adapter -- the production storage backend.
+//!
+//! Three-table schema (`provenance_envelope`, `hash_index`, `chain_tips`) with
+//! KV cross-check. Entry point is [`Trusty`], which wraps a rusqlite connection
+//! and exposes the full append / verify / query surface.
+//!
+//! # Key APIs
+//! - [`Trusty::append`] / [`Trusty::append_batch`] -- write records (batch gives ~21x throughput)
+//! - [`Trusty::verify`] -- check chain integrity for an entity
+//! - [`Trusty::breaks_since`] -- poll chain-break events (tamper / gap alerts)
+//! - [`Trusty::export_bundle`] -- package a chain slice as a [`ProofBundle`](trusty_core::ProofBundle) for external verification
+//! - [`Trusty::append_signed`] -- v2 Ed25519-signed append
+
+#![deny(clippy::all)]
+
+pub mod error;
+pub mod schema;
+pub mod sqlite_store;
+pub mod store;
+
+pub use error::{SqliteError, SqliteResult};
+pub use sqlite_store::SqliteStore;
+pub use store::{
+    AnchorInfo, AppendResult, BreakEvent, CheckpointRow, HistoryRow, IntegrityMismatch,
+    IntegrityReport, ProducerIdentity, RevocationRecord, RowSpec, SilentEntity, Trusty,
+};

crates/adapters/trusty-sqlite/src/schema.rs

@@ -0,0 +1,90 @@
+pub const SCHEMA_SQL: &str = r#"
+PRAGMA journal_mode = WAL;
+PRAGMA synchronous  = FULL;
+PRAGMA foreign_keys = ON;
+
+CREATE TABLE IF NOT EXISTS provenance_envelope (
+    id                INTEGER PRIMARY KEY AUTOINCREMENT,
+    chain_id          TEXT    NOT NULL,
+    entity_id         TEXT    NOT NULL,
+    event_type        TEXT    NOT NULL,
+    field_name        TEXT,
+    old_value         TEXT,
+    new_value         TEXT,
+    source_url        TEXT    NOT NULL DEFAULT '',
+    detected_at       TEXT    NOT NULL,
+    extraction_method TEXT    NOT NULL DEFAULT 'trusty',
+    prev_hash         TEXT    NOT NULL,
+    raw_payload       TEXT,
+    row_hash          TEXT,
+    anchor_hash       TEXT,
+    sequence_int      INTEGER NOT NULL DEFAULT 0
+);
+
+CREATE INDEX IF NOT EXISTS idx_pe_entity ON provenance_envelope(entity_id);
+CREATE INDEX IF NOT EXISTS idx_pe_chain  ON provenance_envelope(chain_id);
+CREATE INDEX IF NOT EXISTS idx_pe_entity_chain ON provenance_envelope(entity_id, chain_id);
+CREATE INDEX IF NOT EXISTS idx_pe_row_hash ON provenance_envelope(row_hash);
+
+CREATE TABLE IF NOT EXISTS hash_index (
+    id           INTEGER PRIMARY KEY AUTOINCREMENT,
+    row_hash     TEXT    NOT NULL UNIQUE,
+    chain_id     TEXT    NOT NULL,
+    sequence_int INTEGER NOT NULL,
+    entity_id    TEXT    NOT NULL,
+    recorded_at  TEXT    NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_hi_entity ON hash_index(entity_id);
+CREATE INDEX IF NOT EXISTS idx_hi_chain  ON hash_index(chain_id);
+
+CREATE TABLE IF NOT EXISTS chain_tips (
+    entity_id        TEXT PRIMARY KEY,
+    current_tip_hash TEXT,
+    chain_id         TEXT,
+    updated_at       TEXT NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_ct_chain ON chain_tips(chain_id);
+
+-- Federation primitives mirrored from trusty-postgres (S17 cycle 4).
+-- BLOB replaces BYTEA; TEXT (RFC3339) replaces TIMESTAMPTZ; INTEGER
+-- PK AUTOINCREMENT replaces BIGINT IDENTITY. Timestamps set by
+-- application code via now_iso() (no DEFAULT CURRENT_TIMESTAMP --
+-- format would differ from RFC3339).
+
+CREATE TABLE IF NOT EXISTS producer_identity (
+    producer_oid   TEXT PRIMARY KEY,
+    ed25519_pubkey BLOB NOT NULL,
+    siphash_key    BLOB NOT NULL,
+    registered_at  TEXT NOT NULL,
+    display_name   TEXT,
+    metadata       TEXT,
+    -- See trusty-postgres: a COSE credential cannot be
+    -- checked as a bare signature, and this is what says which.
+    key_format     TEXT NOT NULL DEFAULT 'ed25519-raw'
+                   CHECK (key_format IN ('ed25519-raw','cose'))
+);
+
+CREATE TABLE IF NOT EXISTS producer_revocation (
+    producer_oid         TEXT PRIMARY KEY,
+    revoked_at           TEXT NOT NULL,
+    revoked_pubkey       BLOB NOT NULL,
+    reason               TEXT NOT NULL,
+    attested_by_pubkey   BLOB NOT NULL,
+    revocation_row_hash  TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS chain_checkpoint (
+    id              INTEGER PRIMARY KEY AUTOINCREMENT,
+    chain_id        TEXT NOT NULL,
+    sequence_int    INTEGER NOT NULL,
+    row_hash        TEXT NOT NULL,
+    checkpoint_at   TEXT NOT NULL,
+    attested_by     TEXT NOT NULL,
+    attestation_sig BLOB NOT NULL,
+    UNIQUE (chain_id, sequence_int)
+);
+
+CREATE INDEX IF NOT EXISTS idx_ckpt_chain ON chain_checkpoint(chain_id);
+"#;

crates/adapters/trusty-sqlite/src/sqlite_store.rs

@@ -0,0 +1,315 @@
+// ============================================================
+// MODULE: sqlite_store
+// PURPOSE: Implements `trusty_store::Store` on top of the existing
+//          three-table schema used by the `Trusty` struct. Exposed
+//          so any code that wants a backend-agnostic handle can use
+//          it; `Trusty` itself still holds its own Connection for
+//          now and will be genericized in a follow-up.
+// ============================================================
+
+use rusqlite::{params, Connection, OptionalExtension};
+use std::path::Path;
+
+use trusty_store::{
+    KvCrossCheckReport, LastRow, RowInsert, Store, StoreError, StoreResult, StoredRow, TipRow,
+    TipUpsert,
+};
+
+use crate::error::{SqliteError, SqliteResult};
+use crate::schema;
+
+pub struct SqliteStore {
+    conn: Connection,
+}
+
+impl SqliteStore {
+    pub fn open<P: AsRef<Path>>(path: P) -> SqliteResult<Self> {
+        let conn = Connection::open(path)?;
+        conn.execute_batch(schema::SCHEMA_SQL)?;
+        Ok(Self { conn })
+    }
+
+    pub fn open_in_memory() -> SqliteResult<Self> {
+        let conn = Connection::open_in_memory()?;
+        conn.execute_batch(schema::SCHEMA_SQL)?;
+        Ok(Self { conn })
+    }
+
+    pub fn conn(&self) -> &Connection {
+        &self.conn
+    }
+
+    pub fn conn_mut(&mut self) -> &mut Connection {
+        &mut self.conn
+    }
+}
+
+fn backend<E: std::fmt::Display>(e: E) -> StoreError {
+    StoreError::Backend(e.to_string())
+}
+
+impl Store for SqliteStore {
+    fn last_row(&self, entity_id: &str) -> StoreResult<Option<LastRow>> {
+        let row = self
+            .conn
+            .query_row(
+                "SELECT row_hash, sequence_int FROM provenance_envelope
+                 WHERE entity_id = ? AND event_type != 'BREAK' AND row_hash IS NOT NULL
+                 ORDER BY id DESC LIMIT 1",
+                params![entity_id],
+                |r| {
+                    Ok(LastRow {
+                        row_hash: r.get(0)?,
+                        sequence: r.get(1)?,
+                    })
+                },
+            )
+            .optional()
+            .map_err(backend)?;
+        Ok(row)
+    }
+
+    fn insert_row(&mut self, row: &RowInsert) -> StoreResult<i64> {
+        self.conn
+            .execute(
+                "INSERT INTO provenance_envelope (
+                    chain_id, entity_id, event_type,
+                    field_name, old_value, new_value,
+                    source_url, detected_at, extraction_method,
+                    prev_hash, row_hash, anchor_hash, sequence_int, raw_payload
+                 ) VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?)",
+                params![
+                    row.chain_id,
+                    row.entity_id,
+                    row.event_type,
+                    Option::<&str>::None,
+                    Option::<&str>::None,
+                    Option::<&str>::None,
+                    row.source_url,
+                    row.detected_at,
+                    row.extraction_method,
+                    row.prev_hash,
+                    row.row_hash,
+                    row.anchor_hash,
+                    row.sequence,
+                    row.raw_payload,
+                ],
+            )
+            .map_err(backend)?;
+        let id = self.conn.last_insert_rowid();
+
+        if let Some(hash) = &row.row_hash {
+            self.conn
+                .execute(
+                    "INSERT OR IGNORE INTO hash_index
+                        (row_hash, chain_id, sequence_int, entity_id, recorded_at)
+                     VALUES (?, ?, ?, ?, ?)",
+                    params![
+                        hash,
+                        row.chain_id,
+                        row.sequence,
+                        row.entity_id,
+                        row.received_at,
+                    ],
+                )
+                .map_err(backend)?;
+        }
+
+        Ok(id)
+    }
+
+    fn iter_chain<'a>(
+        &'a self,
+        entity_id: &str,
+    ) -> StoreResult<Box<dyn Iterator<Item = StoreResult<StoredRow>> + 'a>> {
+        let mut stmt = self
+            .conn
+            .prepare(
+                "SELECT id, entity_id, chain_id, event_type, sequence_int, prev_hash,
+                        row_hash, anchor_hash, raw_payload, detected_at, source_url,
+                        extraction_method
+                 FROM provenance_envelope
+                 WHERE entity_id = ?
+                 ORDER BY id ASC",
+            )
+            .map_err(backend)?;
+        let rows: Vec<StoreResult<StoredRow>> = stmt
+            .query_map(params![entity_id], |r| {
+                Ok(StoredRow {
+                    id: r.get(0)?,
+                    entity_id: r.get(1)?,
+                    chain_id: r.get(2)?,
+                    event_type: r.get(3)?,
+                    sequence: r.get(4)?,
+                    prev_hash: r.get(5)?,
+                    row_hash: r.get(6)?,
+                    anchor_hash: r.get(7)?,
+                    raw_payload: r.get(8)?,
+                    detected_at: r.get(9)?,
+                    received_at: String::new(),
+                    source_url: r.get(10)?,
+                    extraction_method: r.get(11)?,
+                })
+            })
+            .map_err(backend)?
+            .map(|r| r.map_err(backend))
+            .collect();
+        Ok(Box::new(rows.into_iter()))
+    }
+
+    fn get_tip(&self, chain_id: &str) -> StoreResult<Option<TipRow>> {
+        let row = self
+            .conn
+            .query_row(
+                "SELECT entity_id, chain_id, current_tip_hash, updated_at
+                 FROM chain_tips WHERE chain_id = ?",
+                params![chain_id],
+                |r| {
+                    Ok(TipRow {
+                        entity_id: r.get(0)?,
+                        chain_id: r.get::<_, Option<String>>(1)?.unwrap_or_default(),
+                        current_tip_hash: r.get(2)?,
+                        updated_at: r.get(3)?,
+                    })
+                },
+            )
+            .optional()
+            .map_err(backend)?;
+        Ok(row)
+    }
+
+    fn get_tip_for_entity(&self, entity_id: &str) -> StoreResult<Option<TipRow>> {
+        let row = self
+            .conn
+            .query_row(
+                "SELECT entity_id, chain_id, current_tip_hash, updated_at
+                 FROM chain_tips WHERE entity_id = ?",
+                params![entity_id],
+                |r| {
+                    Ok(TipRow {
+                        entity_id: r.get(0)?,
+                        chain_id: r.get::<_, Option<String>>(1)?.unwrap_or_default(),
+                        current_tip_hash: r.get(2)?,
+                        updated_at: r.get(3)?,
+                    })
+                },
+            )
+            .optional()
+            .map_err(backend)?;
+        Ok(row)
+    }
+
+    fn set_tip(&mut self, tip: &TipUpsert) -> StoreResult<()> {
+        let updated_at = chrono::Utc::now().to_rfc3339_opts(chrono::SecondsFormat::Micros, true);
+        self.conn
+            .execute(
+                "INSERT INTO chain_tips (entity_id, current_tip_hash, chain_id, updated_at)
+                 VALUES (?, ?, ?, ?)
+                 ON CONFLICT(entity_id) DO UPDATE SET
+                    current_tip_hash = excluded.current_tip_hash,
+                    chain_id         = excluded.chain_id,
+                    updated_at       = excluded.updated_at",
+                params![
+                    tip.entity_id,
+                    tip.current_tip_hash,
+                    tip.chain_id,
+                    updated_at,
+                ],
+            )
+            .map_err(backend)?;
+        Ok(())
+    }
+
+    fn kv_cross_check(&self) -> StoreResult<KvCrossCheckReport> {
+        let kv1_total_hashes: i64 = self
+            .conn
+            .query_row("SELECT COUNT(*) FROM hash_index", [], |r| r.get(0))
+            .map_err(backend)?;
+
+        let mut tips_stmt = self
+            .conn
+            .prepare("SELECT entity_id, current_tip_hash, chain_id FROM chain_tips")
+            .map_err(backend)?;
+        let tip_rows: Vec<(String, Option<String>, Option<String>)> = tips_stmt
+            .query_map([], |r| {
+                Ok((
+                    r.get::<_, String>(0)?,
+                    r.get::<_, Option<String>>(1)?,
+                    r.get::<_, Option<String>>(2)?,
+                ))
+            })
+            .map_err(backend)?
+            .collect::<Result<Vec<_>, _>>()
+            .map_err(backend)?;
+
+        let mut mismatches: Vec<String> = Vec::new();
+        let mut entities_checked: usize = 0;
+        let kv2_total_entities = tip_rows.len();
+
+        for (entity_id, tip_hash, chain_id) in tip_rows {
+            let tip_hash = match tip_hash {
+                Some(h) => h,
+                None => continue,
+            };
+            let located: Option<String> = self
+                .conn
+                .query_row(
+                    "SELECT chain_id FROM hash_index WHERE row_hash = ?",
+                    params![tip_hash],
+                    |r| r.get(0),
+                )
+                .optional()
+                .map_err(backend)?;
+            match located {
+                None => mismatches.push(format!(
+                    "tip_hash_not_in_index: entity={} hash={}",
+                    entity_id, tip_hash
+                )),
+                Some(idx_chain) => {
+                    if Some(idx_chain.as_str()) != chain_id.as_deref() {
+                        mismatches.push(format!(
+                            "chain_id_mismatch: entity={} expected={:?} got={}",
+                            entity_id, chain_id, idx_chain
+                        ));
+                    }
+                }
+            }
+            entities_checked += 1;
+        }
+
+        Ok(KvCrossCheckReport {
+            ok: mismatches.is_empty(),
+            kv1_total_hashes: kv1_total_hashes as usize,
+            kv2_total_entities,
+            entities_checked,
+            mismatches,
+        })
+    }
+
+    fn with_txn(
+        &mut self,
+        f: &mut dyn FnMut(&mut dyn Store) -> StoreResult<()>,
+    ) -> StoreResult<()> {
+        self.conn
+            .execute_batch("BEGIN IMMEDIATE")
+            .map_err(backend)?;
+        match f(self) {
+            Ok(()) => {
+                self.conn.execute_batch("COMMIT").map_err(backend)?;
+                Ok(())
+            }
+            Err(e) => {
+                let _ = self.conn.execute_batch("ROLLBACK");
+                Err(e)
+            }
+        }
+    }
+}
+
+// Allow callers that already hold a SqliteError-returning function
+// to map into StoreError trivially.
+impl From<SqliteError> for StoreError {
+    fn from(e: SqliteError) -> Self {
+        StoreError::Backend(e.to_string())
+    }
+}

crates/adapters/trusty-sqlite/tests/annotation.rs

@@ -0,0 +1,569 @@
+//! Custody annotations across real, separately-owned chains.
+//!
+//! Each node here is a genuinely separate store with its own signing key
+//! and its own chain. Nothing writes to anybody else's, which is the
+//! property the design rests on: a node cannot forge an annotation it did not
+//! perform, because it can only sign its own.
+
+use trusty_core::{
+    Layer,
+    entity_id_for, verify_annotations, Ed25519Signer, Annotation, SecretKey, SourceRef,
+    AnnotationProblem,
+};
+use trusty_sqlite::Trusty;
+
+const TAG: &str = "sha256:d41d8cd9";
+
+/// A node: its own store, its own key, its own chain.
+struct Node {
+    name: String,
+    store: Trusty,
+    signer: Ed25519Signer,
+}
+
+impl Node {
+    fn new(name: &str, seed: u8) -> Self {
+        Self {
+            name: name.to_string(),
+            store: Trusty::open_in_memory(SecretKey::new([seed; 16])).expect("store"),
+            signer: Ed25519Signer::generate(),
+        }
+    }
+
+    /// Record that this node holds the data, and say where it came from.
+    /// Returns the reference a downstream node will cite.
+    fn record(&mut self, from: Option<SourceRef>, note: &str) -> SourceRef {
+        let mut annotation = Annotation::custody(TAG, &self.name).because(note);
+        annotation.received_from = from;
+        let entity = entity_id_for(TAG, &self.name);
+        let appended = self
+            .store
+            .append_signed(
+                &entity,
+                &annotation.to_data(),
+                "custody://test",
+                &self.signer,
+            )
+            .expect("append");
+        let bundle = self.store.export_bundle(&entity, None, None).expect("export");
+        let row = bundle
+            .rows
+            .iter()
+            .find(|r| r.row_hash.as_deref() == Some(appended.row_hash.as_str()))
+            .expect("the row just written must be in the bundle");
+        SourceRef {
+            chain_id: row.chain_id.clone(),
+            sequence: row.sequence,
+            row_hash: appended.row_hash.clone(),
+        }
+    }
+
+    fn bundle(&self) -> trusty_core::ProofBundle {
+        self.store
+            .export_bundle(&entity_id_for(TAG, &self.name), None, None)
+            .expect("export")
+    }
+}
+
+#[test]
+fn a_path_across_three_nodes_reads_in_order() {
+    let mut origin = Node::new("origin", 1);
+    let mut relay = Node::new("relay", 2);
+    let mut sink = Node::new("sink", 3);
+
+    let a = origin.record(None, "produced here");
+    let b = relay.record(Some(a), "forwarded");
+    sink.record(Some(b), "delivered");
+
+    let report = verify_annotations(&[origin.bundle(), relay.bundle(), sink.bundle()], TAG);
+
+    assert!(
+        report.intact(),
+        "three honest nodes must produce a clean path; problems: {:?}",
+        report.problems
+    );
+    assert_eq!(
+        report.custody_line(),
+        vec!["origin", "relay", "sink"],
+        "the order is reconstructed from the links, not from the order the \
+         bundles happened to be passed in"
+    );
+    assert_eq!(report.found, 3);
+}
+
+#[test]
+fn the_order_does_not_depend_on_the_order_bundles_arrive_in() {
+    let mut origin = Node::new("origin", 1);
+    let mut relay = Node::new("relay", 2);
+    let mut sink = Node::new("sink", 3);
+    let a = origin.record(None, "produced here");
+    let b = relay.record(Some(a), "forwarded");
+    sink.record(Some(b), "delivered");
+
+    let shuffled = verify_annotations(&[sink.bundle(), origin.bundle(), relay.bundle()], TAG);
+
+    assert_eq!(
+        shuffled.custody_line(),
+        vec!["origin", "relay", "sink"],
+        "a merge that depended on argument order would be reporting the \
+         caller's filing habits rather than the history"
+    );
+}
+
+#[test]
+fn a_missing_middle_node_is_reported_not_papered_over() {
+    let mut origin = Node::new("origin", 1);
+    let mut relay = Node::new("relay", 2);
+    let mut sink = Node::new("sink", 3);
+
+    let a = origin.record(None, "produced here");
+    let b = relay.record(Some(a), "forwarded");
+    sink.record(Some(b), "delivered");
+
+    // The relay's bundle is withheld -- exactly what a relay that would
+    // rather not be in the record would do.
+    let report = verify_annotations(&[origin.bundle(), sink.bundle()], TAG);
+
+    assert!(
+        !report.intact(),
+        "a gap must not read as a clean history; problems: {:?}",
+        report.problems
+    );
+    assert!(
+        report
+            .problems
+            .iter()
+            .any(|p| matches!(p, AnnotationProblem::DanglingPredecessor { node, .. } if node == "sink")),
+        "the sink cites a row nobody can produce, and that is the finding; \
+         got {:?}",
+        report.problems
+    );
+}
+
+#[test]
+fn a_hop_citing_a_row_that_was_altered_does_not_link() {
+    let mut origin = Node::new("origin", 1);
+    let mut relay = Node::new("relay", 2);
+
+    let a = origin.record(None, "produced here");
+    // The relay cites the right position but the wrong content -- what a
+    // forged provenance claim looks like when the citation is guessed.
+    relay.record(
+        Some(SourceRef {
+            row_hash: "00".repeat(32),
+            ..a
+        }),
+        "claims to have had it from origin",
+    );
+
+    let report = verify_annotations(&[origin.bundle(), relay.bundle()], TAG);
+
+    assert!(
+        report
+            .problems
+            .iter()
+            .any(|p| matches!(p, AnnotationProblem::DanglingPredecessor { .. })),
+        "naming a real position with the wrong hash must not link; the hash \
+         is what makes the citation a citation; got {:?}",
+        report.problems
+    );
+}
+
+#[test]
+fn two_nodes_receiving_from_the_same_hop_is_reported_as_a_fork() {
+    let mut origin = Node::new("origin", 1);
+    let mut left = Node::new("left", 2);
+    let mut right = Node::new("right", 3);
+
+    let a = origin.record(None, "produced here");
+    left.record(Some(a.clone()), "one copy");
+    right.record(Some(a), "another copy");
+
+    let report = verify_annotations(&[origin.bundle(), left.bundle(), right.bundle()], TAG);
+
+    assert!(
+        report
+            .problems
+            .iter()
+            .any(|p| matches!(p, AnnotationProblem::Fork { .. })),
+        "fanning out is legitimate, but a caller expecting a line must be \
+         told it got a tree; got {:?}",
+        report.problems
+    );
+    assert!(
+        !report.intact(),
+        "intact() is the strict reading; a caller who accepts forks reads \
+         problems and decides"
+    );
+}
+
+#[test]
+fn two_claimed_origins_are_reported() {
+    let mut one = Node::new("one", 1);
+    let mut two = Node::new("two", 2);
+    one.record(None, "I made this");
+    two.record(None, "no, I made this");
+
+    let report = verify_annotations(&[one.bundle(), two.bundle()], TAG);
+
+    assert!(
+        report
+            .problems
+            .iter()
+            .any(|p| matches!(p, AnnotationProblem::MultipleOrigins { .. })),
+        "the same data cannot originate twice, and which claim is false is \
+         not something the log can settle -- but it can refuse to pick; got {:?}",
+        report.problems
+    );
+    assert!(report.hops.is_empty(), "with no single origin there is no order");
+}
+
+#[test]
+fn traffic_about_other_data_is_ignored() {
+    let mut origin = Node::new("origin", 1);
+    let mut relay = Node::new("relay", 2);
+
+    // The relay's chain also carries an annotation about something else.
+    let other = Annotation::custody("sha256:something-else", &relay.name);
+    relay
+        .store
+        .append_signed(
+            &entity_id_for(TAG, &relay.name),
+            &other.to_data(),
+            "custody://test",
+            &relay.signer,
+        )
+        .expect("append other");
+
+    let a = origin.record(None, "produced here");
+    relay.record(Some(a), "forwarded");
+
+    let report = verify_annotations(&[origin.bundle(), relay.bundle()], TAG);
+
+    assert!(
+        report.intact(),
+        "a bundle may carry unrelated traffic; problems: {:?}",
+        report.problems
+    );
+    assert_eq!(
+        report.found, 2,
+        "only annotations about the tag asked for count, or a busy node would \
+         appear to have handled everything"
+    );
+}
+
+#[test]
+fn nothing_recorded_is_not_a_clean_history() {
+    let origin = Node::new("origin", 1);
+    let report = verify_annotations(&[origin.bundle()], TAG);
+
+    assert!(
+        !report.intact(),
+        "no records at all must not read as an unbroken chain of custody; \
+         the difference matters most exactly when someone is asking"
+    );
+    assert_eq!(report.found, 0);
+}
+
+#[test]
+fn a_tampered_bundle_takes_no_part_in_the_path() {
+    let mut origin = Node::new("origin", 1);
+    let mut relay = Node::new("relay", 2);
+    let a = origin.record(None, "produced here");
+    relay.record(Some(a), "forwarded");
+
+    // Rewrite what the relay claims it did, after export. The signature
+    // no longer covers it.
+    let mut forged = relay.bundle();
+    for row in forged.rows.iter_mut() {
+        if let Some(payload) = row.raw_payload.as_mut() {
+            *payload = payload.replace("forwarded", "never touched it");
+        }
+    }
+
+    let report = verify_annotations(&[origin.bundle(), forged], TAG);
+
+    assert!(
+        report
+            .problems
+            .iter()
+            .any(|p| matches!(p, AnnotationProblem::BundleUnverified { .. })),
+        "a bundle whose rows no longer match their signatures must be \
+         reported as such; got {:?}",
+        report.problems
+    );
+    assert_eq!(
+        report.found, 1,
+        "and its rows must not contribute hops -- a tidy custody report \
+         built over forged rows is worse than no report at all"
+    );
+    assert!(!report.intact());
+}
+
+#[test]
+fn an_honest_bundle_beside_a_forged_one_still_counts() {
+    let mut origin = Node::new("origin", 1);
+    let mut relay = Node::new("relay", 2);
+    let a = origin.record(None, "produced here");
+    relay.record(Some(a), "forwarded");
+
+    let mut forged = relay.bundle();
+    for row in forged.rows.iter_mut() {
+        if let Some(payload) = row.raw_payload.as_mut() {
+            *payload = payload.replace("forwarded", "never touched it");
+        }
+    }
+    let report = verify_annotations(&[origin.bundle(), forged], TAG);
+
+    // The origin is untouched and still says what it said. One party
+    // lying must not erase another party's honest record.
+    assert_eq!(
+        report.custody_line(),
+        vec!["origin"],
+        "the surviving path is what the verified bundles support, no more \
+         and no less; got {:?}",
+        report.custody_line()
+    );
+}
+
+// ---------------------------------------------------------------------
+// Kinds beyond custody.
+// ---------------------------------------------------------------------
+
+impl Node {
+    /// Record that this node ran a check, and what it concluded.
+    fn checked(&mut self, ok: bool, note: &str) {
+        let annotation = Annotation::integrity(TAG, &self.name, ok)
+            .at_layer(Layer::Device)
+            .because(note);
+        self.store
+            .append_signed(
+                &entity_id_for(TAG, &self.name),
+                &annotation.to_data(),
+                "custody://test",
+                &self.signer,
+            )
+            .expect("append");
+    }
+}
+
+#[test]
+fn a_failed_check_becomes_an_actionable_marker() {
+    let mut origin = Node::new("origin", 1);
+    let mut relay = Node::new("relay", 2);
+
+    let a = origin.record(None, "produced here");
+    relay.record(Some(a), "forwarded");
+    relay.checked(false, "checksum mismatch on receipt");
+
+    let report = verify_annotations(&[origin.bundle(), relay.bundle()], TAG);
+
+    assert_eq!(
+        report.failed_checks().len(),
+        1,
+        "a node that ran a check and found a problem must surface it \
+         separately from structural findings, so a peer can decide to \
+         refuse, quarantine or inspect; got {:?}",
+        report.problems
+    );
+    assert!(
+        !report.intact(),
+        "a datum somebody found wrong must not read as clean"
+    );
+    assert_eq!(
+        report.custody_line(),
+        vec!["origin", "relay"],
+        "the custody path is still readable; a failed check is a finding \
+         about the datum, not a reason to lose the history"
+    );
+}
+
+#[test]
+fn a_passed_check_is_recorded_without_becoming_a_problem() {
+    let mut origin = Node::new("origin", 1);
+    let mut relay = Node::new("relay", 2);
+    let a = origin.record(None, "produced here");
+    relay.record(Some(a), "forwarded");
+    relay.checked(true, "checksum matched");
+
+    let report = verify_annotations(&[origin.bundle(), relay.bundle()], TAG);
+
+    assert!(
+        report.intact(),
+        "a check that passed is evidence in favour, not a finding; \
+         problems: {:?}",
+        report.problems
+    );
+    assert_eq!(
+        report.found, 3,
+        "the passing check must still be counted -- knowing a check RAN is \
+         the difference between verified and merely unexamined"
+    );
+}
+
+#[test]
+fn a_custody_claim_is_not_read_as_a_check_that_passed() {
+    let mut origin = Node::new("origin", 1);
+    origin.record(None, "produced here");
+
+    let report = verify_annotations(&[origin.bundle()], TAG);
+
+    assert!(
+        report.failed_checks().is_empty(),
+        "holding data is not a claim about its correctness"
+    );
+    assert_eq!(
+        report.found, 1,
+        "and it is still an annotation, counted as one"
+    );
+}
+
+#[test]
+fn an_annotation_of_an_unknown_kind_is_reported_not_ignored() {
+    let mut origin = Node::new("origin", 1);
+    origin.record(None, "produced here");
+
+    let mut odd = Annotation::custody(TAG, &origin.name);
+    odd.kind = trusty_core::AnnotationKind::Other("future.kind.v9".into());
+    origin
+        .store
+        .append_signed(
+            &entity_id_for(TAG, &origin.name),
+            &odd.to_data(),
+            "custody://test",
+            &origin.signer,
+        )
+        .expect("append");
+
+    let report = verify_annotations(&[origin.bundle()], TAG);
+
+    assert!(
+        report.problems.iter().any(|p| matches!(
+            p,
+            AnnotationProblem::UnrecognisedKind { kind, .. } if kind == "future.kind.v9"
+        )),
+        "silence would let a future kind carrying a failed check pass an old \
+         verifier unnoticed; got {:?}",
+        report.problems
+    );
+}
+
+#[test]
+fn a_forged_bundle_cannot_erase_a_failed_check() {
+    let mut origin = Node::new("origin", 1);
+    let mut relay = Node::new("relay", 2);
+    let a = origin.record(None, "produced here");
+    relay.record(Some(a), "forwarded");
+    relay.checked(false, "checksum mismatch on receipt");
+
+    // The relay rewrites its own bundle to say the check passed.
+    let mut forged = relay.bundle();
+    for row in forged.rows.iter_mut() {
+        if let Some(payload) = row.raw_payload.as_mut() {
+            *payload = payload.replace("\"satisfied\":false", "\"satisfied\":true");
+        }
+    }
+
+    let report = verify_annotations(&[origin.bundle(), forged], TAG);
+
+    assert!(
+        report.problems.iter().any(|p| matches!(
+            p,
+            AnnotationProblem::BundleUnverified { .. }
+        )),
+        "editing a finding out of your own bundle must break its signature, \
+         not quietly succeed; got {:?}",
+        report.problems
+    );
+    assert!(
+        !report.intact(),
+        "and the result must not read as clean just because the evidence was \
+         removed"
+    );
+}
+
+// ---------------------------------------------------------------------
+// Credential formats. A WebAuthn credential must never be checked as a
+// bare signature.
+// ---------------------------------------------------------------------
+
+#[test]
+fn a_cose_producer_is_refused_by_the_bare_signature_path() {
+    use trusty_core::KeyFormat;
+
+    let mut trusty = Trusty::open_in_memory(SecretKey::new([4u8; 16])).expect("store");
+    let signer = Ed25519Signer::generate();
+    trusty
+        .append_signed("doc", &serde_json::json!({ "v": 1 }), "t://", &signer)
+        .expect("append");
+
+    // A user enrolled through WebAuthn: the credential is a COSE key,
+    // and its signatures cover authenticatorData ||
+    // SHA-256(clientDataJSON) rather than the message.
+    trusty
+        .register_producer_with_format("user:01H", &[0u8; 32], &[0u8; 16], None, KeyFormat::Cose)
+        .expect("enrol");
+
+    let err = trusty
+        .verify_with_producer("doc", "user:01H")
+        .expect_err("must refuse");
+    let msg = err.to_string();
+
+    assert!(
+        msg.contains("clientDataJSON"),
+        "the refusal must explain WHY, or the next person reads it as a wrong          key and loosens the check until it passes: {msg}"
+    );
+    assert!(
+        !msg.contains("verification failed"),
+        "and it must not look like a failed verification -- that confusion is          what the change exists to remove: {msg}"
+    );
+}
+
+#[test]
+fn a_raw_producer_is_still_verified_normally() {
+    use trusty_core::KeyFormat;
+
+    let mut trusty = Trusty::open_in_memory(SecretKey::new([6u8; 16])).expect("store");
+    let signer = Ed25519Signer::generate();
+    trusty
+        .append_signed("doc", &serde_json::json!({ "v": 1 }), "t://", &signer)
+        .expect("append");
+    trusty
+        .register_producer_with_format(
+            "agent:01J",
+            &[0u8; 32],
+            &[0u8; 16],
+            None,
+            KeyFormat::Ed25519Raw,
+        )
+        .expect("enrol");
+
+    // May or may not verify -- the key is a placeholder. What matters is
+    // that it is not REFUSED: the raw path must be untouched, or this
+    // change would have broken every existing producer.
+    match trusty.verify_with_producer("doc", "agent:01J") {
+        Ok(_) => {}
+        Err(e) => assert!(
+            !e.to_string().contains("unsupported credential"),
+            "a raw Ed25519 producer must reach the signature check, not be              turned away before it: {e}"
+        ),
+    }
+}
+
+#[test]
+fn a_producer_enrolled_before_the_column_existed_reads_as_raw() {
+    let mut trusty = Trusty::open_in_memory(SecretKey::new([5u8; 16])).expect("store");
+    trusty
+        .register_producer("agent:old", &[0u8; 32], &[0u8; 16], None)
+        .expect("enrol");
+
+    let found = trusty
+        .lookup_producer("agent:old")
+        .expect("lookup")
+        .expect("row");
+    assert_eq!(
+        found.key_format,
+        trusty_core::KeyFormat::Ed25519Raw,
+        "every credential enrolled before the column existed WAS a raw          Ed25519 key, so the schema default is correct -- applied at write          time, never as a parse fallback"
+    );
+}

crates/adapters/trusty-sqlite/tests/conformance.rs

@@ -0,0 +1,8 @@
+use trusty_sqlite::SqliteStore;
+use trusty_store::testing::run_conformance;
+
+#[test]
+fn sqlite_store_passes_conformance() {
+    let mut store = SqliteStore::open_in_memory().expect("open in-memory sqlite store");
+    run_conformance(&mut store);
+}

crates/adapters/trusty-tokio/Cargo.toml

@@ -0,0 +1,16 @@
+[package]
+name = "trusty-tokio"
+version.workspace = true
+edition.workspace = true
+authors.workspace = true
+license.workspace = true
+repository.workspace = true
+rust-version.workspace = true
+description = "Runs a blocking trusty Store on a tokio runtime's blocking pool, so an async caller does not park a worker thread. An adapter, not a core concern: a runtime is a substrate."
+
+[dependencies]
+trusty-store = { workspace = true }
+tokio = { workspace = true, features = ["rt", "sync"] }
+
+[dev-dependencies]
+tokio = { workspace = true, features = ["rt", "rt-multi-thread", "macros", "time", "sync"] }

crates/adapters/trusty-tokio/src/lib.rs

@@ -0,0 +1,264 @@
+#![deny(clippy::all)]
+
+//! An async face for a blocking [`Store`].
+//!
+//! # Why this is an adapter and not a core concern
+//!
+//! A runtime is a substrate. `trusty-core` touches no filesystem, clock,
+//! thread, socket or process API, and `trusty-store` is four pure
+//! dependencies; putting an optional tokio in either would give a crate
+//! designed to have no platform a platform -- even switched off, it is
+//! in the manifest and in the lockfile.
+//!
+//! So this lives beside `trusty-sqlite` and `trusty-postgres`, named for
+//! its substrate the same way they are. A consumer on async-std, smol,
+//! or no runtime at all pays nothing and is not told tokio is the
+//! answer.
+//!
+//! # What this is, and what it is not
+//!
+//! This is async **ergonomics**, not async **I/O**. Every call still runs
+//! the same blocking code on the same backend; it simply runs it on a
+//! blocking pool instead of on the async runtime's worker threads.
+//! SQLite writes still serialise, one at a time. A genuinely concurrent
+//! backend would be a different adapter, not this one.
+//!
+//! Saying so plainly matters, because the failure this prevents and the
+//! failure it does not prevent look alike from outside.
+//!
+//! # The problem it does solve
+//!
+//! An async runtime has a small pool of worker threads running every
+//! task. A blocking call inside a task **parks a whole worker** for the
+//! duration of a write and its fsync, during which that thread runs
+//! nothing else. Enough concurrent appends and the runtime starves:
+//! tasks with nothing to do with trusty simply stop making progress.
+//!
+//! Distant Star is the consumer this was waiting for -- it is tokio
+//! throughout, and a relay writing a custody annotation does so inside
+//! an async task while it is also moving packets.
+//!
+//! # Two things deliberately do not cross
+//!
+//! [`Store::iter_chain`] returns an iterator borrowing the store, and
+//! [`Store::with_txn`] takes a closure that is not `'static`. Neither can
+//! be sent to another thread, so neither is mirrored here:
+//!
+//! - **`chain_rows`** materialises the chain into a `Vec` instead of
+//!   streaming it. That is a real difference and not a free one -- the
+//!   result is bounded by memory rather than by patience -- so
+//!   [`AsyncStore::chain_rows_bounded`] exists for callers who would
+//!   rather cap it than find out.
+//! - **`with_txn_owned`** takes an owned `FnOnce` that can be moved to
+//!   the blocking pool. Callers return values out of it directly rather
+//!   than capturing outer state by reference, because a reference to
+//!   outer state is exactly what cannot travel.
+
+pub mod pool;
+pub use pool::BlockingPool;
+
+use std::sync::{Arc, Mutex};
+
+use trusty_store::{
+    KvCrossCheckReport, LastRow, RowInsert, Store, StoreError, StoreResult, StoredRow, TipRow,
+    TipUpsert,
+};
+
+/// The async surface. Mirrors [`Store`] where mirroring is possible, and
+/// says so where it is not.
+///
+/// Not dyn-compatible: `async fn` in a trait cannot be. Consumers that
+/// need dynamic dispatch should hold [`BlockingStore`] concretely, or
+/// wrap it themselves.
+#[allow(async_fn_in_trait)]
+pub trait AsyncStore {
+    async fn last_row(&self, entity_id: &str) -> StoreResult<Option<LastRow>>;
+    async fn insert_row(&self, row: RowInsert) -> StoreResult<i64>;
+    async fn get_tip(&self, chain_id: &str) -> StoreResult<Option<TipRow>>;
+    async fn get_tip_for_entity(&self, entity_id: &str) -> StoreResult<Option<TipRow>>;
+    async fn set_tip(&self, tip: TipUpsert) -> StoreResult<()>;
+    async fn kv_cross_check(&self) -> StoreResult<KvCrossCheckReport>;
+
+    /// The whole chain, materialised.
+    ///
+    /// Unlike [`Store::iter_chain`] this cannot stream: the iterator
+    /// borrows the store, and a borrow cannot be sent to a blocking
+    /// thread. Prefer [`AsyncStore::chain_rows_bounded`] on any chain
+    /// whose length is not known.
+    async fn chain_rows(&self, entity_id: &str) -> StoreResult<Vec<StoredRow>>;
+
+    /// At most `limit` rows, and whether more were left behind.
+    ///
+    /// Returning the "there is more" flag rather than silently stopping
+    /// is the whole point: a truncated history that looks complete is
+    /// how a verifier concludes a chain is intact when it has only seen
+    /// the part that is.
+    async fn chain_rows_bounded(
+        &self,
+        entity_id: &str,
+        limit: usize,
+    ) -> StoreResult<(Vec<StoredRow>, bool)>;
+}
+
+/// Runs a blocking [`Store`] on the runtime's blocking pool.
+///
+/// Cloneable and shareable: every clone talks to the same store behind
+/// the same lock, so concurrent callers serialise rather than race. That
+/// is not a limitation this type imposes -- it is the backend's, made
+/// visible instead of hidden.
+pub struct BlockingStore<S: Store + Send + 'static> {
+    inner: Arc<Mutex<S>>,
+}
+
+impl<S: Store + Send + 'static> Clone for BlockingStore<S> {
+    fn clone(&self) -> Self {
+        Self {
+            inner: Arc::clone(&self.inner),
+        }
+    }
+}
+
+impl<S: Store + Send + 'static> BlockingStore<S> {
+    pub fn new(store: S) -> Self {
+        Self {
+            inner: Arc::new(Mutex::new(store)),
+        }
+    }
+
+    /// Take the store back. Fails if any clone is still alive.
+    pub fn into_inner(self) -> Result<S, Self> {
+        match Arc::try_unwrap(self.inner) {
+            Ok(mutex) => Ok(mutex.into_inner().unwrap_or_else(|e| e.into_inner())),
+            Err(inner) => Err(Self { inner }),
+        }
+    }
+
+    /// Run an owned closure against the store on the blocking pool.
+    ///
+    /// The escape hatch for everything this facade does not mirror,
+    /// including transactions. The closure must be `'static` and `Send`,
+    /// which is not a formality: a closure borrowing local state is
+    /// precisely what cannot be moved to another thread.
+    pub async fn with_store<T, F>(&self, f: F) -> StoreResult<T>
+    where
+        F: FnOnce(&mut S) -> StoreResult<T> + Send + 'static,
+        T: Send + 'static,
+    {
+        let inner = Arc::clone(&self.inner);
+        run_blocking(move || {
+            let mut guard = inner.lock().unwrap_or_else(|e| e.into_inner());
+            f(&mut guard)
+        })
+        .await
+    }
+
+    /// A transaction, with its result carried out by value.
+    ///
+    /// [`Store::with_txn`] captures results through outer state because
+    /// its closure cannot return one. Here the closure is owned, so it
+    /// can -- which removes the need for the `Option` dance the blocking
+    /// API requires, and with it the chance of reading the captured slot
+    /// on a path where the transaction rolled back.
+    pub async fn with_txn_owned<T, F>(&self, f: F) -> StoreResult<T>
+    where
+        F: FnOnce(&mut dyn Store) -> StoreResult<T> + Send + 'static,
+        T: Send + 'static,
+    {
+        self.with_store(move |store| {
+            let mut captured: Option<T> = None;
+            let mut once = Some(f);
+            store.with_txn(&mut |txn: &mut dyn Store| {
+                let f = once.take().ok_or_else(|| {
+                    StoreError::Backend(
+                        "the backend invoked the transaction body more than once, which \
+                         this facade cannot support: an owned closure can only run once"
+                            .to_string(),
+                    )
+                })?;
+                captured = Some(f(txn)?);
+                Ok(())
+            })?;
+            captured.ok_or_else(|| {
+                StoreError::Backend(
+                    "the transaction committed without the body having run".to_string(),
+                )
+            })
+        })
+        .await
+    }
+}
+
+/// Hand work to the blocking pool, and turn a panic there into an error
+/// rather than letting it take the caller down.
+///
+/// A panic inside a store operation is a bug, but a bug that unwinds
+/// into an unrelated task is a much harder bug to find than one that
+/// arrives as a `Backend` error at the call site that caused it.
+async fn run_blocking<T, F>(f: F) -> StoreResult<T>
+where
+    F: FnOnce() -> StoreResult<T> + Send + 'static,
+    T: Send + 'static,
+{
+    match tokio::task::spawn_blocking(f).await {
+        Ok(result) => result,
+        Err(join) => Err(StoreError::Backend(format!(
+            "the store operation did not finish: {join}"
+        ))),
+    }
+}
+
+impl<S: Store + Send + 'static> AsyncStore for BlockingStore<S> {
+    async fn last_row(&self, entity_id: &str) -> StoreResult<Option<LastRow>> {
+        let entity_id = entity_id.to_string();
+        self.with_store(move |s| s.last_row(&entity_id)).await
+    }
+
+    async fn insert_row(&self, row: RowInsert) -> StoreResult<i64> {
+        self.with_store(move |s| s.insert_row(&row)).await
+    }
+
+    async fn get_tip(&self, chain_id: &str) -> StoreResult<Option<TipRow>> {
+        let chain_id = chain_id.to_string();
+        self.with_store(move |s| s.get_tip(&chain_id)).await
+    }
+
+    async fn get_tip_for_entity(&self, entity_id: &str) -> StoreResult<Option<TipRow>> {
+        let entity_id = entity_id.to_string();
+        self.with_store(move |s| s.get_tip_for_entity(&entity_id))
+            .await
+    }
+
+    async fn set_tip(&self, tip: TipUpsert) -> StoreResult<()> {
+        self.with_store(move |s| s.set_tip(&tip)).await
+    }
+
+    async fn kv_cross_check(&self) -> StoreResult<KvCrossCheckReport> {
+        self.with_store(|s| s.kv_cross_check()).await
+    }
+
+    async fn chain_rows(&self, entity_id: &str) -> StoreResult<Vec<StoredRow>> {
+        let entity_id = entity_id.to_string();
+        self.with_store(move |s| s.iter_chain(&entity_id)?.collect())
+            .await
+    }
+
+    async fn chain_rows_bounded(
+        &self,
+        entity_id: &str,
+        limit: usize,
+    ) -> StoreResult<(Vec<StoredRow>, bool)> {
+        let entity_id = entity_id.to_string();
+        self.with_store(move |s| {
+            let mut iter = s.iter_chain(&entity_id)?;
+            let mut rows = Vec::new();
+            for row in iter.by_ref().take(limit) {
+                rows.push(row?);
+            }
+            // Asking for one more is how "there is more" is learned
+            // without walking the rest of a chain nobody asked for.
+            let more = iter.next().is_some();
+            Ok((rows, more))
+        })
+        .await
+    }
+}

crates/adapters/trusty-tokio/src/pool.rs

@@ -0,0 +1,282 @@
+//! A pool of stores, so concurrent callers are not queued behind one.
+//!
+//! # Why a pool rather than removing the lock
+//!
+//! [`crate::BlockingStore`] holds one store behind one mutex, so every
+//! caller serialises. That looks like needless queuing to delete, and it
+//! is not: `Store::insert_row(&mut self)` requires exclusive access by
+//! its signature. The mutex is the trait's demand, not this type's
+//! choice.
+//!
+//! Concurrency therefore needs **more stores**, not fewer locks. Each
+//! holds its own connection, so two calls genuinely run at once.
+//!
+//! # The correctness this depends on
+//!
+//! Two connections appending to the same entity would race the chain
+//! tip: appending is read-tip, compute, insert, and those are not
+//! atomic. `trusty-postgres` holds a per-entity advisory lock across
+//! that sequence, so same-entity writers serialise in the database while
+//! different entities proceed in parallel.
+//!
+//! **That lock is a precondition of this type, not a detail.** Before it
+//! existed, the single mutex was the only thing making concurrent
+//! appends safe, and pooling without it would have converted a slowness
+//! into a lost update -- a trade that reads as a performance win in a
+//! diff.
+//!
+//! A backend with no such lock, or one writer per file like SQLite,
+//! should keep using [`crate::BlockingStore`].
+
+use std::sync::atomic::{AtomicUsize, Ordering};
+use std::sync::{Arc, Mutex};
+
+use tokio::sync::Semaphore;
+use trusty_store::{Store, StoreError, StoreResult};
+
+/// Builds a fresh store, each with its own connection.
+pub type Factory<S> = Arc<dyn Fn() -> StoreResult<S> + Send + Sync>;
+
+/// Runs blocking store work across several connections.
+pub struct BlockingPool<S: Store + Send + 'static> {
+    idle: Arc<Mutex<Vec<S>>>,
+    make: Factory<S>,
+    /// Bounds concurrency to the connection budget. Without it, load
+    /// would open connections until the database refused them, and the
+    /// refusal would arrive as a failed append rather than as waiting.
+    permits: Arc<Semaphore>,
+    live: Arc<AtomicUsize>,
+    max: usize,
+}
+
+impl<S: Store + Send + 'static> Clone for BlockingPool<S> {
+    fn clone(&self) -> Self {
+        Self {
+            idle: Arc::clone(&self.idle),
+            make: Arc::clone(&self.make),
+            permits: Arc::clone(&self.permits),
+            live: Arc::clone(&self.live),
+            max: self.max,
+        }
+    }
+}
+
+impl<S: Store + Send + 'static> BlockingPool<S> {
+    /// A pool of at most `max` connections, opened on demand.
+    ///
+    /// Connections are created lazily rather than up front: a pool that
+    /// opens its full budget at startup turns a misconfigured connection
+    /// string into a failure at boot for capacity nobody has asked for
+    /// yet.
+    pub fn new(max: usize, make: impl Fn() -> StoreResult<S> + Send + Sync + 'static) -> Self {
+        let max = max.max(1);
+        Self {
+            idle: Arc::new(Mutex::new(Vec::new())),
+            make: Arc::new(make),
+            permits: Arc::new(Semaphore::new(max)),
+            live: Arc::new(AtomicUsize::new(0)),
+            max,
+        }
+    }
+
+    pub fn capacity(&self) -> usize {
+        self.max
+    }
+
+    /// Connections currently open. Rises to `capacity` under load and
+    /// does not fall; a pool that closed idle connections would pay
+    /// reconnection cost exactly when traffic returned.
+    pub fn open_connections(&self) -> usize {
+        self.live.load(Ordering::SeqCst)
+    }
+
+    /// Run `f` against a store from the pool.
+    ///
+    /// The store is moved into the blocking closure and handed back with
+    /// the result, so ownership never has to be shared and no lock is
+    /// held while the work runs.
+    ///
+    /// A store whose work returned an error is still returned to the
+    /// pool: a failed append usually means a rejected row, not a broken
+    /// connection, and discarding the connection would turn every
+    /// validation error into a reconnect.
+    pub async fn with<T, F>(&self, f: F) -> StoreResult<T>
+    where
+        F: FnOnce(&mut S) -> StoreResult<T> + Send + 'static,
+        T: Send + 'static,
+    {
+        let _permit = self
+            .permits
+            .acquire()
+            .await
+            .map_err(|_| StoreError::Backend("the store pool has been closed".into()))?;
+
+        let mut store = match self.idle.lock().unwrap_or_else(|e| e.into_inner()).pop() {
+            Some(s) => s,
+            None => {
+                let s = (self.make)()?;
+                self.live.fetch_add(1, Ordering::SeqCst);
+                s
+            }
+        };
+
+        let joined = tokio::task::spawn_blocking(move || {
+            let out = f(&mut store);
+            (store, out)
+        })
+        .await;
+
+        match joined {
+            Ok((store, out)) => {
+                self.idle
+                    .lock()
+                    .unwrap_or_else(|e| e.into_inner())
+                    .push(store);
+                out
+            }
+            Err(join) => {
+                // The store went down with the panicking task, so the
+                // connection is gone rather than merely idle.
+                self.live.fetch_sub(1, Ordering::SeqCst);
+                Err(StoreError::Backend(format!(
+                    "the store operation did not finish and its connection was lost: {join}"
+                )))
+            }
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::time::Duration;
+    use trusty_store::{KvCrossCheckReport, LastRow, RowInsert, StoredRow, TipRow, TipUpsert};
+
+    struct Slow {
+        id: usize,
+        delay: Duration,
+    }
+
+    impl Store for Slow {
+        fn last_row(&self, _e: &str) -> StoreResult<Option<LastRow>> {
+            std::thread::sleep(self.delay);
+            Ok(None)
+        }
+        fn insert_row(&mut self, _r: &RowInsert) -> StoreResult<i64> {
+            std::thread::sleep(self.delay);
+            Ok(self.id as i64)
+        }
+        fn iter_chain<'a>(
+            &'a self,
+            _e: &str,
+        ) -> StoreResult<Box<dyn Iterator<Item = StoreResult<StoredRow>> + 'a>> {
+            Ok(Box::new(std::iter::empty()))
+        }
+        fn get_tip(&self, _c: &str) -> StoreResult<Option<TipRow>> {
+            Ok(None)
+        }
+        fn get_tip_for_entity(&self, _e: &str) -> StoreResult<Option<TipRow>> {
+            Ok(None)
+        }
+        fn set_tip(&mut self, _t: &TipUpsert) -> StoreResult<()> {
+            Ok(())
+        }
+        fn kv_cross_check(&self) -> StoreResult<KvCrossCheckReport> {
+            Err(StoreError::Backend("not implemented".into()))
+        }
+        fn with_txn(
+            &mut self,
+            f: &mut dyn FnMut(&mut dyn Store) -> StoreResult<()>,
+        ) -> StoreResult<()> {
+            let mut scratch = Slow {
+                id: self.id,
+                delay: Duration::ZERO,
+            };
+            f(&mut scratch)
+        }
+    }
+
+    fn pool(max: usize, delay_ms: u64) -> BlockingPool<Slow> {
+        let next = Arc::new(AtomicUsize::new(0));
+        BlockingPool::new(max, move || {
+            Ok(Slow {
+                id: next.fetch_add(1, Ordering::SeqCst),
+                delay: Duration::from_millis(delay_ms),
+            })
+        })
+    }
+
+    /// **The claim.** Four slow calls across four connections finish in
+    /// far less than four times one call.
+    #[tokio::test(flavor = "multi_thread", worker_threads = 4)]
+    async fn calls_run_concurrently_rather_than_queueing() {
+        let p = pool(4, 250);
+        let start = std::time::Instant::now();
+        let mut hs = Vec::new();
+        for _ in 0..4 {
+            let p = p.clone();
+            hs.push(tokio::spawn(async move { p.with(|s| s.last_row("e")).await }));
+        }
+        for h in hs {
+            h.await.expect("join").expect("call");
+        }
+        let elapsed = start.elapsed();
+        assert!(
+            elapsed < Duration::from_millis(700),
+            "four 250ms calls on four connections took {elapsed:?}. Serialised \
+             they would take about a second, which is what a single store \
+             behind one mutex does and what this type exists to stop"
+        );
+    }
+
+    #[tokio::test(flavor = "multi_thread", worker_threads = 4)]
+    async fn concurrency_is_bounded_by_the_connection_budget() {
+        let p = pool(2, 60);
+        let mut hs = Vec::new();
+        for _ in 0..8 {
+            let p = p.clone();
+            hs.push(tokio::spawn(async move { p.with(|s| s.last_row("e")).await }));
+        }
+        for h in hs {
+            h.await.expect("join").expect("call");
+        }
+        assert!(
+            p.open_connections() <= 2,
+            "eight callers opened {} connections against a budget of 2. Without \
+             the bound, load opens connections until the database refuses, and \
+             the refusal arrives as a failed append rather than as waiting",
+            p.open_connections()
+        );
+    }
+
+    #[tokio::test]
+    async fn connections_are_reused_not_opened_per_call() {
+        let p = pool(4, 0);
+        for _ in 0..20 {
+            p.with(|s| s.last_row("e")).await.expect("call");
+        }
+        assert_eq!(
+            p.open_connections(),
+            1,
+            "sequential calls must reuse one connection; opening one per call \
+             would make the pool slower than the mutex it replaces"
+        );
+    }
+
+    #[tokio::test]
+    async fn a_failed_call_returns_its_connection_to_the_pool() {
+        let p = pool(2, 0);
+        let _ = p
+            .with(|s| s.kv_cross_check().map(|_| ()))
+            .await
+            .expect_err("this store returns an error for that call");
+        p.with(|s| s.last_row("e")).await.expect("still usable");
+        assert_eq!(
+            p.open_connections(),
+            1,
+            "a failed append usually means a rejected row, not a broken \
+             connection; discarding it would turn every validation error into \
+             a reconnect"
+        );
+    }
+}

crates/adapters/trusty-tokio/tests/runtime.rs

@@ -0,0 +1,280 @@
+//! Does the async facade actually keep the runtime free?
+//!
+//! That is the only claim it makes, so it is the one worth testing.
+//! Everything else here exists because it is a way the facade could be
+//! quietly wrong: a lost value, a swallowed panic, a truncation that
+//! reads as a complete chain.
+
+use std::sync::atomic::{AtomicUsize, Ordering};
+use std::sync::Arc;
+use std::time::Duration;
+
+use trusty_store::{
+    KvCrossCheckReport, LastRow, RowInsert, Store, StoreError, StoreResult, StoredRow, TipRow,
+    TipUpsert,
+};
+use trusty_tokio::{AsyncStore, BlockingStore};
+
+/// A store that is deliberately slow, so blocking is observable.
+struct SlowStore {
+    delay: Duration,
+    rows: usize,
+    inserts: Arc<AtomicUsize>,
+    panic_on_insert: bool,
+}
+
+impl SlowStore {
+    fn new(delay_ms: u64) -> Self {
+        Self {
+            delay: Duration::from_millis(delay_ms),
+            rows: 0,
+            inserts: Arc::new(AtomicUsize::new(0)),
+            panic_on_insert: false,
+        }
+    }
+
+    fn with_rows(mut self, rows: usize) -> Self {
+        self.rows = rows;
+        self
+    }
+}
+
+fn stored_row(sequence: i64) -> StoredRow {
+    StoredRow {
+        id: sequence + 1,
+        entity_id: "e".into(),
+        chain_id: "c".into(),
+        event_type: "MUTATION".into(),
+        sequence,
+        prev_hash: String::new(),
+        row_hash: Some(format!("{sequence:064}")),
+        anchor_hash: None,
+        raw_payload: None,
+        detected_at: String::new(),
+        received_at: String::new(),
+        source_url: String::new(),
+        extraction_method: "trusty".into(),
+    }
+}
+
+impl Store for SlowStore {
+    fn last_row(&self, _entity_id: &str) -> StoreResult<Option<LastRow>> {
+        std::thread::sleep(self.delay);
+        Ok(Some(LastRow {
+            row_hash: "aa".into(),
+            sequence: 7,
+        }))
+    }
+
+    fn insert_row(&mut self, _row: &RowInsert) -> StoreResult<i64> {
+        std::thread::sleep(self.delay);
+        if self.panic_on_insert {
+            panic!("a bug inside a store operation");
+        }
+        Ok(self.inserts.fetch_add(1, Ordering::SeqCst) as i64 + 1)
+    }
+
+    fn iter_chain<'a>(
+        &'a self,
+        _entity_id: &str,
+    ) -> StoreResult<Box<dyn Iterator<Item = StoreResult<StoredRow>> + 'a>> {
+        Ok(Box::new((0..self.rows as i64).map(|i| Ok(stored_row(i)))))
+    }
+
+    fn get_tip(&self, _chain_id: &str) -> StoreResult<Option<TipRow>> {
+        Ok(None)
+    }
+
+    fn get_tip_for_entity(&self, _entity_id: &str) -> StoreResult<Option<TipRow>> {
+        Ok(None)
+    }
+
+    fn set_tip(&mut self, _tip: &TipUpsert) -> StoreResult<()> {
+        Ok(())
+    }
+
+    fn kv_cross_check(&self) -> StoreResult<KvCrossCheckReport> {
+        Err(StoreError::Backend("not implemented for this test".into()))
+    }
+
+    fn with_txn(
+        &mut self,
+        f: &mut dyn FnMut(&mut dyn Store) -> StoreResult<()>,
+    ) -> StoreResult<()> {
+        let mut scratch = SlowStore::new(0);
+        f(&mut scratch)
+    }
+}
+
+fn row_insert() -> RowInsert {
+    RowInsert {
+        entity_id: "e".into(),
+        chain_id: "c".into(),
+        event_type: "MUTATION".into(),
+        sequence: 0,
+        prev_hash: String::new(),
+        row_hash: None,
+        anchor_hash: None,
+        raw_payload: None,
+        detected_at: String::new(),
+        received_at: String::new(),
+        source_url: String::new(),
+        extraction_method: "trusty".into(),
+    }
+}
+
+/// **The claim.** A single-worker runtime, one slow store call, and an
+/// unrelated task that must keep running while it is in flight.
+///
+/// Single-threaded on purpose: with more than one worker the test would
+/// pass even if the call blocked, because another worker would pick the
+/// second task up. One worker is the only configuration where blocking
+/// is fatal and therefore the only one that proves anything.
+#[tokio::test(flavor = "current_thread")]
+async fn a_slow_store_call_does_not_park_the_runtime() {
+    let store = BlockingStore::new(SlowStore::new(300));
+    let ticks = Arc::new(AtomicUsize::new(0));
+
+    let counter = Arc::clone(&ticks);
+    let ticker = tokio::spawn(async move {
+        for _ in 0..20 {
+            tokio::time::sleep(Duration::from_millis(10)).await;
+            counter.fetch_add(1, Ordering::SeqCst);
+        }
+    });
+
+    store.insert_row(row_insert()).await.expect("insert");
+    let progressed = ticks.load(Ordering::SeqCst);
+    ticker.abort();
+
+    assert!(
+        progressed > 5,
+        "the other task must have kept running while the store was busy. \
+         It ticked {progressed} times; blocking the worker would have left \
+         it at or near zero, which is exactly the runtime starvation this \
+         facade exists to prevent"
+    );
+}
+
+#[tokio::test(flavor = "current_thread")]
+async fn concurrent_callers_serialise_rather_than_race() {
+    let store = BlockingStore::new(SlowStore::new(20));
+    let mut handles = Vec::new();
+    for _ in 0..8 {
+        let s = store.clone();
+        handles.push(tokio::spawn(async move { s.insert_row(row_insert()).await }));
+    }
+    let mut ids = Vec::new();
+    for h in handles {
+        ids.push(h.await.expect("join").expect("insert"));
+    }
+    ids.sort_unstable();
+
+    assert_eq!(
+        ids,
+        (1..=8).collect::<Vec<i64>>(),
+        "every caller must get its own row and none may be lost. The \
+         backend serialises writes; that is its property, made visible \
+         here rather than hidden"
+    );
+}
+
+#[tokio::test]
+async fn a_panic_in_the_store_becomes_an_error_not_a_dead_task() {
+    let mut slow = SlowStore::new(0);
+    slow.panic_on_insert = true;
+    let store = BlockingStore::new(slow);
+
+    let result = store.insert_row(row_insert()).await;
+
+    assert!(
+        matches!(result, Err(StoreError::Backend(_))),
+        "a panic inside a store operation is a bug, but one that unwinds \
+         into an unrelated task is far harder to find than one arriving as \
+         an error at the call site that caused it"
+    );
+}
+
+#[tokio::test]
+async fn a_bounded_read_says_when_it_left_something_behind() {
+    let store = BlockingStore::new(SlowStore::new(0).with_rows(10));
+
+    let (rows, more) = store.chain_rows_bounded("e", 4).await.expect("bounded");
+    assert_eq!(rows.len(), 4);
+    assert!(
+        more,
+        "a truncated history that looks complete is how a verifier \
+         concludes a chain is intact having seen only the part that is"
+    );
+
+    let (all, more) = store.chain_rows_bounded("e", 50).await.expect("bounded");
+    assert_eq!(all.len(), 10);
+    assert!(!more, "with nothing left behind it must not claim there is");
+}
+
+#[tokio::test]
+async fn the_whole_chain_can_still_be_read_when_that_is_wanted() {
+    let store = BlockingStore::new(SlowStore::new(0).with_rows(5));
+    let rows = store.chain_rows("e").await.expect("chain");
+    assert_eq!(
+        rows.len(),
+        5,
+        "iter_chain cannot cross a thread boundary, so this materialises \
+         instead of streaming -- but it must still return everything"
+    );
+}
+
+#[tokio::test]
+async fn a_transaction_carries_its_result_out_by_value() {
+    let store = BlockingStore::new(SlowStore::new(0));
+
+    let answer = store
+        .with_txn_owned(|txn| {
+            txn.insert_row(&row_insert())?;
+            Ok("committed".to_string())
+        })
+        .await
+        .expect("txn");
+
+    assert_eq!(
+        answer, "committed",
+        "the blocking with_txn captures results through outer state \
+         because its closure cannot return one; an owned closure can, \
+         which removes the chance of reading a captured slot on a path \
+         where the transaction rolled back"
+    );
+}
+
+#[tokio::test]
+async fn a_failing_transaction_reports_the_failure_not_a_missing_value() {
+    let store = BlockingStore::new(SlowStore::new(0));
+
+    let result: StoreResult<String> = store
+        .with_txn_owned(|_txn| Err(StoreError::Backend("deliberate".into())))
+        .await;
+
+    match result {
+        Err(StoreError::Backend(msg)) => assert_eq!(
+            msg, "deliberate",
+            "the body's own error must survive, not be replaced by a \
+             complaint that no value was produced"
+        ),
+        other => panic!("expected the body's error, got {other:?}"),
+    }
+}
+
+#[tokio::test]
+async fn clones_share_one_store() {
+    let store = BlockingStore::new(SlowStore::new(0));
+    let clone = store.clone();
+
+    store.insert_row(row_insert()).await.expect("first");
+    let second = clone.insert_row(row_insert()).await.expect("second");
+
+    assert_eq!(
+        second, 2,
+        "a clone must talk to the same store, or two halves of an \
+         application would be appending to different chains while \
+         believing they shared one"
+    );
+}