hecks 5.0.0 → 6.0.0

data/rust/host/src/api.rs

@@ -4,17 +4,16 @@
 use crate::auth::Session;
 use crate::dispatch;
 use crate::host::Host;
-use crate::journal::LineageConfig;
 use crate::presentation;
 use crate::presentation_write;
+use crate::store::journal_sql::LineageConfig;
+use crate::store::Store;
 use crate::ui_schema;
 use crate::web::{percent_decode, respond};
 use serde_json::{json, Map, Value};
 use std::cmp::Ordering;
 use std::collections::HashMap;
 use std::path::Path;
-use tokio::sync::Mutex;
-use tokio_postgres::Client;
 
 /// Every `/api/...` request, answered. `session` is `None` only in tests —
 /// `web::route` runs `auth_gate` first in production — but it stays an
@@ -30,7 +29,7 @@ pub async fn route(
     host: Host<'_>,
 ) -> Value {
     let Host {
-        client,
+        store,
         wasm_path,
         config,
         ..
@@ -41,25 +40,35 @@ pub async fn route(
         // The whole UI, derived: nav, columns, field shapes, transitions,
         // create forms. Read fresh every call so a Settings-screen save is
         // visible on the app's very next request.
-        ("GET", "/api/ui-schema") => match presentation::load(client, wasm_path, config).await {
+        ("GET", "/api/ui-schema") => match presentation::load(store, wasm_path, config).await {
             Ok(presentation) => ok(&ui_schema::build(domain_ir, &presentation)),
             Err(e) => internal_error(&e.to_string()),
         },
 
         // Structural facts only, no presentation opinion: aggregates,
         // lifecycle states, queries.
-        ("GET", "/api/schema") => match presentation::load(client, wasm_path, config).await {
+        ("GET", "/api/schema") => match presentation::load(store, wasm_path, config).await {
             Ok(presentation) => ok(&ui_schema::schema(domain_ir, &presentation)),
             Err(e) => internal_error(&e.to_string()),
         },
 
         // Read fresh every call, never memoized, for the same reason.
-        ("GET", "/api/presentation") => match presentation::load(client, wasm_path, config).await {
+        ("GET", "/api/presentation") => match presentation::load(store, wasm_path, config).await {
             Ok(presentation) => ok(&presentation),
             Err(e) => internal_error(&e.to_string()),
         },
 
-        ("PUT", "/api/presentation") => presentation_save(domain_ir, raw_body, host).await,
+        // The config names collection keys, identity strategies and preconditions, and its
+        // ConsoleSettings commands dispatch as the host itself, so only an admin may save it.
+        ("PUT", "/api/presentation") => {
+            if !session
+                .and_then(|session| session.role.as_deref())
+                .is_some_and(crate::auth::is_admin_role)
+            {
+                return refusal(403, "Forbidden", "admins only");
+            }
+            presentation_save(domain_ir, raw_body, host).await
+        }
 
         // Collection routes (`/api/:coll[/:id]`), matched last so `:coll`
         // doesn't swallow `me`/`schema`. Segments are percent-decoded: a
@@ -75,16 +84,23 @@ pub async fn route(
 
             match (method, segments.as_slice()) {
                 ("GET", [collection]) => {
-                    collection_index(domain_ir, collection, query, client, wasm_path, config).await
+                    collection_index(domain_ir, collection, query, store, wasm_path, config).await
                 }
                 ("GET", [collection, id]) => {
-                    record_show(domain_ir, collection, id, client, wasm_path, config).await
+                    record_show(domain_ir, collection, id, store, wasm_path, config).await
                 }
                 ("POST", [collection]) => {
-                    collection_create(domain_ir, collection, raw_body, host).await
+                    let caller = crate::auth::caller(session);
+                    let preview = crate::validation::requested(query);
+                    collection_create(domain_ir, collection, raw_body, caller, preview, host).await
                 }
                 ("POST", [collection, id, command]) => {
-                    command_route(domain_ir, collection, id, command, raw_body, host).await
+                    let caller = crate::auth::caller(session);
+                    let preview = crate::validation::requested(query);
+                    command_route(
+                        domain_ir, collection, id, command, raw_body, caller, preview, host,
+                    )
+                    .await
                 }
                 _ => not_found(&format!("no API route for {method} {path}")),
             }
@@ -99,11 +115,11 @@ async fn collection_index(
     domain_ir: &Value,
     collection: &str,
     params: &HashMap<String, String>,
-    client: &Mutex<Client>,
+    store: &Store,
     wasm_path: &Path,
     lineage: &LineageConfig,
 ) -> Value {
-    let config = match presentation::load(client, wasm_path, lineage).await {
+    let config = match presentation::load(store, wasm_path, lineage).await {
         Ok(config) => config,
         Err(e) => return internal_error(&e.to_string()),
     };
@@ -119,11 +135,11 @@ async fn collection_index(
     let named = wanted.and_then(|name| find_query(aggregate, name));
     if let Some(named) = named {
         if let Some(args) = query_args_from_params(aggregate, named, params) {
-            return named_query_rows(domain_ir, aggregate, named, args, client, wasm_path).await;
+            return named_query_rows(domain_ir, aggregate, named, args, store, wasm_path).await;
         }
     }
 
-    let mut records = match read_records(domain_ir, aggregate, client, wasm_path).await {
+    let mut records = match read_records(domain_ir, aggregate, store, wasm_path).await {
         Ok(records) => records,
         Err(refusal) => return refusal,
     };
@@ -145,11 +161,11 @@ async fn record_show(
     domain_ir: &Value,
     collection: &str,
     id: &str,
-    client: &Mutex<Client>,
+    store: &Store,
     wasm_path: &Path,
     lineage: &LineageConfig,
 ) -> Value {
-    let config = match presentation::load(client, wasm_path, lineage).await {
+    let config = match presentation::load(store, wasm_path, lineage).await {
         Ok(config) => config,
         Err(e) => return internal_error(&e.to_string()),
     };
@@ -157,7 +173,7 @@ async fn record_show(
         Ok(aggregate) => aggregate,
         Err(refusal) => return refusal,
     };
-    let records = match read_records(domain_ir, aggregate, client, wasm_path).await {
+    let records = match read_records(domain_ir, aggregate, store, wasm_path).await {
         Ok(records) => records,
         Err(refusal) => return refusal,
     };
@@ -198,10 +214,10 @@ fn find_query<'a>(aggregate: &'a Value, name: &str) -> Option<&'a Value> {
 async fn read_records(
     domain_ir: &Value,
     aggregate: &Value,
-    client: &Mutex<Client>,
+    store: &Store,
     wasm_path: &Path,
 ) -> Result<Vec<(String, Value)>, Value> {
-    let result = dispatch::read(client, wasm_path)
+    let result = dispatch::read(store, wasm_path)
         .await
         .map_err(|e| internal_error(&format!("{e:#}")))?;
     let prefix = format!(
@@ -239,7 +255,7 @@ async fn named_query_rows(
     aggregate: &Value,
     named: &Value,
     args: Value,
-    client: &Mutex<Client>,
+    store: &Store,
     wasm_path: &Path,
 ) -> Value {
     let question = format!(
@@ -248,7 +264,7 @@ async fn named_query_rows(
         ui_schema::agg_name(aggregate),
         named.get("name").and_then(|v| v.as_str()).unwrap_or("")
     );
-    let result = match dispatch::query(client, wasm_path, &question, args).await {
+    let result = match dispatch::query_request(store, wasm_path, &question, args).await {
         Ok(result) => result,
         Err(e) => return internal_error(&format!("{e:#}")),
     };
@@ -328,15 +344,17 @@ async fn collection_create(
     domain_ir: &Value,
     collection: &str,
     raw_body: &str,
+    caller: dispatch::Caller<'_>,
+    preview: bool,
     host: Host<'_>,
 ) -> Value {
     let Host {
-        client,
+        store,
         wasm_path,
         config,
         ..
     } = host;
-    let presentation = match presentation::load(client, wasm_path, config).await {
+    let presentation = match presentation::load(store, wasm_path, config).await {
         Ok(presentation) => presentation,
         Err(e) => return internal_error(&e.to_string()),
     };
@@ -356,22 +374,15 @@ async fn collection_create(
         return not_found(&format!("{name} declares no creating command"));
     };
 
-    let records = match read_records(domain_ir, aggregate, client, wasm_path).await {
+    let records = match read_records(domain_ir, aggregate, store, wasm_path).await {
         Ok(records) => records,
         Err(refusal) => return refusal,
     };
     if let Err(refusal) = apply_identity(&presentation, aggregate, &mut args, records.len()) {
         return refusal;
     }
-    if let Err(refusal) = check_preconditions(
-        domain_ir,
-        &presentation,
-        aggregate,
-        &args,
-        client,
-        wasm_path,
-    )
-    .await
+    if let Err(refusal) =
+        check_preconditions(domain_ir, &presentation, aggregate, &args, store, wasm_path).await
     {
         return refusal;
     }
@@ -381,7 +392,10 @@ async fn collection_create(
         domain_name(domain_ir),
         command_name(creating)
     );
-    let outcome = match dispatch::handle_facts(host, &verb, args, None).await {
+    if preview {
+        return preview_answer(host, &verb, dispatch::facts_invocation(args), caller).await;
+    }
+    let outcome = match dispatch::handle_facts_request(host, &verb, args, caller).await {
         Ok(outcome) => outcome,
         Err(e) => return internal_error(&format!("{e:#}")),
     };
@@ -398,21 +412,24 @@ async fn collection_create(
 /// `POST /api/:coll/:id/:command` — a command against an existing record.
 /// Order matters: find the record first (404), then the command (404),
 /// then dispatch — the Ruby engine's own order.
+#[allow(clippy::too_many_arguments)]
 async fn command_route(
     domain_ir: &Value,
     collection: &str,
     id: &str,
     command: &str,
     raw_body: &str,
+    caller: dispatch::Caller<'_>,
+    preview: bool,
     host: Host<'_>,
 ) -> Value {
     let Host {
-        client,
+        store,
         wasm_path,
         config,
         ..
     } = host;
-    let presentation = match presentation::load(client, wasm_path, config).await {
+    let presentation = match presentation::load(store, wasm_path, config).await {
         Ok(presentation) => presentation,
         Err(e) => return internal_error(&e.to_string()),
     };
@@ -421,7 +438,7 @@ async fn command_route(
         Err(refusal) => return refusal,
     };
     let name = ui_schema::agg_name(aggregate);
-    let records = match read_records(domain_ir, aggregate, client, wasm_path).await {
+    let records = match read_records(domain_ir, aggregate, store, wasm_path).await {
         Ok(records) => records,
         Err(refusal) => return refusal,
     };
@@ -441,7 +458,12 @@ async fn command_route(
         domain_name(domain_ir),
         command_name(declared)
     );
-    let outcome = match dispatch::handle_routed(host, &verb, json!(id), args, None).await {
+    if preview {
+        let invocation = dispatch::routed_invocation(json!(id), args);
+        return preview_answer(host, &verb, invocation, caller).await;
+    }
+    let outcome = match dispatch::handle_routed_request(host, &verb, json!(id), args, caller).await
+    {
         Ok(outcome) => outcome,
         Err(e) => return internal_error(&format!("{e:#}")),
     };
@@ -451,6 +473,24 @@ async fn command_route(
     created_record(domain_ir, aggregate, &outcome.result, id)
 }
 
+/// What a preview of `verb` answers: the client envelope, with 200 whether or not the command would
+/// be refused. A malformed invocation or a failure to run is a `500`, as a real dispatch's is.
+async fn preview_answer(
+    host: Host<'_>,
+    verb: &str,
+    invocation: anyhow::Result<Value>,
+    caller: dispatch::Caller<'_>,
+) -> Value {
+    let invocation = match invocation {
+        Ok(invocation) => invocation,
+        Err(e) => return internal_error(&format!("{e:#}")),
+    };
+    match dispatch::preview_request(host, verb, invocation, caller).await {
+        Ok(outcome) => ok(&crate::validation::answer(&outcome.result)),
+        Err(e) => internal_error(&format!("{e:#}")),
+    }
+}
+
 /// Every command except the creating one, which is reached only through
 /// `POST /api/:coll`. Matched against the snake_cased name
 /// `/api/ui-schema` hands the client, not the declared name itself.
@@ -674,7 +714,7 @@ async fn check_preconditions(
     presentation: &Value,
     aggregate: &Value,
     args: &Value,
-    client: &Mutex<Client>,
+    store: &Store,
     wasm_path: &Path,
 ) -> Result<(), Value> {
     let name = ui_schema::agg_name(aggregate);
@@ -689,7 +729,7 @@ async fn check_preconditions(
         return Ok(());
     }
 
-    let instances = dispatch::read(client, wasm_path)
+    let instances = dispatch::read(store, wasm_path)
         .await
         .map_err(|e| internal_error(&format!("{e:#}")))?;
     let instances = instances
@@ -933,7 +973,7 @@ fn me(session: Option<&Session>) -> Value {
 /// `PUT /api/presentation` — the whole config replaced at once, validated
 /// against this domain's live shape, answered with the reloaded config.
 /// 200 on save; 400 `MalformedBody`; 422 `Malformed` or a domain refusal;
-/// 501 when this host's kernel carries no ConsoleSettings chapter.
+/// 501 when this host's kernel carries no ConsoleSettings bluebook.
 async fn presentation_save(domain_ir: &Value, raw_body: &str, host: Host<'_>) -> Value {
     let submitted = match parsed_body(raw_body) {
         Ok(submitted) => submitted,
@@ -954,10 +994,10 @@ async fn presentation_save(domain_ir: &Value, raw_body: &str, host: Host<'_>) ->
 }
 
 // Fires only for a domain whose kernel genuinely has no ConsoleSettings
-// chapter; names the decision outstanding rather than 404-ing as if the
+// bluebook; names the decision outstanding rather than 404-ing as if the
 // route never existed.
 const PRESENTATION_WRITE_REFUSAL: &str =
-    "this host's kernel carries no ConsoleSettings chapter, so it has no StateStyle/Collection/Overview \
+    "this host's kernel carries no ConsoleSettings bluebook, so it has no StateStyle/Collection/Overview \
      commands to dispatch, and writing the rows behind its back would skip the invariants those commands \
      enforce. Attach it with `attaches \"ConsoleSettings\"` in this domain's own .hecksagon and \
      rebuild the kernel, or save from the Ruby console engine instead.";
@@ -991,6 +1031,8 @@ pub(crate) fn refusal(status: u16, error: &str, message: &str) -> Value {
 #[cfg(test)]
 mod tests {
     use super::*;
+    #[allow(unused_imports)]
+    use crate::store::StoreFixtures;
 
     fn session() -> Session {
         Session {
@@ -1703,7 +1745,7 @@ mod tests {
         .expect("valid IR")
     }
 
-    /// A fixture whose `.wasm` carries a ConsoleSettings chapter, the
+    /// A fixture whose `.wasm` carries a ConsoleSettings bluebook, the
     /// premise `PUT /api/presentation` needs.
     fn console_fixture() -> (std::path::PathBuf, Value) {
         let dist = std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("../dist");
@@ -1727,25 +1769,13 @@ mod tests {
 
     #[tokio::test]
     async fn the_presentation_config_is_saved_and_read_back_through_the_kernels_own_commands() {
-        let client = crate::dispatch::tests::scratch_db("rust_host_api_presentation_save").await;
-        crate::dispatch::tests::provision_lineage(
-            &*client.lock().await,
-            "CheckoutFixture",
-            1,
-            &[
-                "Event",
-                "Registration",
-                "StateStyle",
-                "Collection",
-                "Overview",
-            ],
-        )
-        .await;
+        let client = crate::dispatch_tests::tests::memory_store();
         let (wasm, ir) = console_fixture();
         let lineage = LineageConfig {
             domain: "CheckoutFixture".to_string(),
-            era: Some(1),
+            era: None,
             mirrored: None,
+            seal_every: None,
         };
         let invoker = crate::lambda_client::NeverInvoker;
 
@@ -1789,7 +1819,7 @@ mod tests {
         // app.rb returns `json(PresentationConfig.load)` after a save.
         assert_eq!(stored["states"]["Event"]["open"]["tone"], "good");
         assert_eq!(stored["states"]["Event"]["open"]["attention"], json!(true));
-        // A field this chapter does not model individually still
+        // A field this bluebook does not model individually still
         // round-trips, through `extra_json`.
         assert_eq!(
             stored["states"]["Event"]["open"]["label"],
@@ -1843,26 +1873,13 @@ mod tests {
 
     #[tokio::test]
     async fn a_config_that_breaks_a_rule_refuses_422_malformed_and_writes_nothing() {
-        let client =
-            crate::dispatch::tests::scratch_db("rust_host_api_presentation_malformed").await;
-        crate::dispatch::tests::provision_lineage(
-            &*client.lock().await,
-            "CheckoutFixture",
-            1,
-            &[
-                "Event",
-                "Registration",
-                "StateStyle",
-                "Collection",
-                "Overview",
-            ],
-        )
-        .await;
+        let client = crate::dispatch_tests::tests::memory_store();
         let (wasm, ir) = console_fixture();
         let lineage = LineageConfig {
             domain: "CheckoutFixture".to_string(),
-            era: Some(1),
+            era: None,
             mirrored: None,
+            seal_every: None,
         };
         let invoker = crate::lambda_client::NeverInvoker;
 
@@ -1894,20 +1911,13 @@ mod tests {
 
     #[tokio::test]
     async fn a_body_that_is_not_json_at_all_is_a_400_before_anything_is_validated() {
-        let client =
-            crate::dispatch::tests::scratch_db("rust_host_api_presentation_bad_body").await;
-        crate::dispatch::tests::provision_lineage(
-            &*client.lock().await,
-            "CheckoutFixture",
-            1,
-            &["Event"],
-        )
-        .await;
+        let client = crate::dispatch_tests::tests::memory_store();
         let (wasm, ir) = console_fixture();
         let lineage = LineageConfig {
             domain: "CheckoutFixture".to_string(),
-            era: Some(1),
+            era: None,
             mirrored: None,
+            seal_every: None,
         };
 
         let refused = presentation_save(
@@ -1926,25 +1936,18 @@ mod tests {
         assert_eq!(body(&refused)["error"], "MalformedBody");
     }
 
-    /// Banking's kernel carries no ConsoleSettings chapter, and this
+    /// Banking's kernel carries no ConsoleSettings bluebook, and this
     /// asks the kernel rather than inferring it from anything else.
     #[tokio::test]
-    async fn a_host_whose_kernel_has_no_console_settings_chapter_still_refuses_501() {
-        let client =
-            crate::dispatch::tests::scratch_db("rust_host_api_presentation_no_chapter").await;
-        crate::dispatch::tests::provision_lineage(
-            &*client.lock().await,
-            "Banking",
-            1,
-            &["Customer"],
-        )
-        .await;
-        let wasm = crate::dispatch::tests::wasm_path();
+    async fn a_host_whose_kernel_has_no_console_settings_bluebook_still_refuses_501() {
+        let client = crate::dispatch_tests::tests::memory_store();
+        let wasm = crate::dispatch_tests::tests::wasm_path();
         let ir = banking_ir();
         let lineage = LineageConfig {
             domain: "Banking".to_string(),
-            era: Some(1),
+            era: None,
             mirrored: None,
+            seal_every: None,
         };
 
         let refused = presentation_save(
@@ -1972,24 +1975,25 @@ mod tests {
 
     #[tokio::test]
     async fn a_record_is_created_then_commanded_then_read_back_through_the_api_routes() {
-        let client = crate::dispatch::tests::scratch_db("rust_host_api_write_routes").await;
-        crate::dispatch::tests::provision_lineage(
+        let client = crate::dispatch_tests::tests::scratch_db("rust_host_api_write_routes").await;
+        crate::dispatch_tests::tests::provision_lineage(
             &*client.lock().await,
             "Banking",
             1,
             &["Customer"],
         )
         .await;
-        let wasm = crate::dispatch::tests::wasm_path();
+        let wasm = crate::dispatch_tests::tests::wasm_path();
         let ir = banking_ir();
         let lineage = LineageConfig {
             domain: "Banking".to_string(),
             era: Some(1),
             mirrored: None,
+            seal_every: None,
         };
         let invoker = crate::lambda_client::NeverInvoker;
 
-        let created = collection_create(&ir, "customers", r#"{"reference":{"value":"CUST-9001"},"name":{"given":"Ada","family":"Lovelace"},"email":{"address":"ada@example.com"}}"#, Host::new(&client, &wasm, &lineage, &invoker))
+        let created = collection_create(&ir, "customers", r#"{"reference":{"value":"CUST-9001"},"name":{"given":"Ada","family":"Lovelace"},"email":{"address":"ada@example.com"}}"#, dispatch::Caller::default(), false, Host::new(&client, &wasm, &lineage, &invoker))
         .await;
 
         assert_eq!(created["statusCode"], 200, "{created}");
@@ -2012,6 +2016,8 @@ mod tests {
             "CUST-9001",
             "suspend",
             r#"{"standing":{"value":"watch"}}"#,
+            dispatch::Caller::default(),
+            false,
             Host::new(&client, &wasm, &lineage, &invoker),
         )
         .await;
@@ -2028,6 +2034,8 @@ mod tests {
             "CUST-9001",
             "suspend",
             r#"{"standing":{"value":"watch"}}"#,
+            dispatch::Caller::default(),
+            false,
             Host::new(&client, &wasm, &lineage, &invoker),
         )
         .await;
@@ -2054,6 +2062,8 @@ mod tests {
             "CUST-9001",
             "nope",
             "",
+            dispatch::Caller::default(),
+            false,
             Host::new(&client, &wasm, &lineage, &invoker),
         )
         .await;
@@ -2069,6 +2079,8 @@ mod tests {
             "ghost",
             "suspend",
             "",
+            dispatch::Caller::default(),
+            false,
             Host::new(&client, &wasm, &lineage, &invoker),
         )
         .await;
@@ -2079,6 +2091,134 @@ mod tests {
         );
     }
 
+    fn signed_in(role: &str) -> Session {
+        Session {
+            identity_id: String::new(),
+            role: Some(role.to_string()),
+            ..session()
+        }
+    }
+
+    // A signed-in caller's role reaches the kernel, so a command the role may not run is refused
+    // the way the internal protocol refuses it.
+    #[tokio::test]
+    async fn a_write_route_dispatches_as_the_signed_in_caller_and_refuses_a_role_the_command_does_not_declare(
+    ) {
+        let client = crate::dispatch_tests::tests::scratch_db("rust_host_api_write_roles").await;
+        crate::dispatch_tests::tests::provision_lineage(
+            &*client.lock().await,
+            "Banking",
+            1,
+            &["Customer"],
+        )
+        .await;
+        let wasm = crate::dispatch_tests::tests::wasm_path();
+        let ir = banking_ir();
+        let lineage = LineageConfig {
+            domain: "Banking".to_string(),
+            era: Some(1),
+            mirrored: None,
+            seal_every: None,
+        };
+        let invoker = crate::lambda_client::NeverInvoker;
+        let post = |path: &'static str, body: &'static str, session: Session| {
+            let (client, wasm, ir, lineage, invoker) = (&client, &wasm, &ir, &lineage, &invoker);
+            async move {
+                let host = Host::new(client, wasm, lineage, invoker);
+                route(
+                    ir,
+                    "POST",
+                    path,
+                    &HashMap::new(),
+                    body,
+                    Some(&session),
+                    host,
+                )
+                .await
+            }
+        };
+        let customer = r#"{"reference":{"value":"CUST-9101"},"name":{"given":"Ada","family":"Lovelace"},"email":{"address":"ada@example.com"}}"#;
+
+        let teller = post("/api/customers", customer, signed_in("Teller")).await;
+        assert_eq!(teller["statusCode"], 422, "{teller}");
+        assert_eq!(body(&teller)["error"], "Unauthorized");
+
+        let clerk = post("/api/customers", customer, signed_in("Branch clerk")).await;
+        assert_eq!(clerk["statusCode"], 200, "{clerk}");
+
+        let suspend = r#"{"standing":{"value":"watch"}}"#;
+        let by_clerk = post(
+            "/api/customers/CUST-9101/suspend",
+            suspend,
+            signed_in("Branch clerk"),
+        )
+        .await;
+        assert_eq!(by_clerk["statusCode"], 422, "{by_clerk}");
+        assert_eq!(body(&by_clerk)["error"], "Unauthorized");
+    }
+
+    // The presentation config rewrites collection keys, identity strategies and preconditions, so
+    // only an admin may save it.
+    #[tokio::test]
+    async fn only_an_admin_may_save_the_presentation_config() {
+        let client = crate::dispatch_tests::tests::memory_store();
+        let (wasm, ir) = console_fixture();
+        let lineage = LineageConfig {
+            domain: "CheckoutFixture".to_string(),
+            era: None,
+            mirrored: None,
+            seal_every: None,
+        };
+        let invoker = crate::lambda_client::NeverInvoker;
+        let submitted = every_state_styled().to_string();
+        let put = |session: Option<Session>| {
+            let (client, wasm, ir, lineage, invoker) = (&client, &wasm, &ir, &lineage, &invoker);
+            let submitted = submitted.clone();
+            async move {
+                let host = Host::new(client, wasm, lineage, invoker);
+                let path = "/api/presentation";
+                route(
+                    ir,
+                    "PUT",
+                    path,
+                    &HashMap::new(),
+                    &submitted,
+                    session.as_ref(),
+                    host,
+                )
+                .await
+            }
+        };
+
+        let refused = [
+            ("no session", None),
+            ("a member", Some(signed_in("Member"))),
+            ("no role", Some(session_without_role())),
+        ];
+        for (who, session) in refused {
+            let response = put(session).await;
+            assert_eq!(response["statusCode"], 403, "{who}: {response}");
+        }
+        assert_eq!(
+            presentation::load(&client, &wasm, &lineage)
+                .await
+                .expect("a config"),
+            json!({"states": {}, "collections": {}, "overview": {}}),
+            "a refused save writes nothing"
+        );
+        for admin in ["Admin", "Owner"] {
+            let response = put(Some(signed_in(admin))).await;
+            assert_eq!(response["statusCode"], 200, "{admin}: {response}");
+        }
+    }
+
+    fn session_without_role() -> Session {
+        Session {
+            role: None,
+            ..session()
+        }
+    }
+
     #[test]
     fn the_presentation_write_route_refuses_in_its_own_words() {
         let response = not_implemented(PRESENTATION_WRITE_REFUSAL);
@@ -2092,6 +2232,77 @@ mod tests {
             "the refusal has to name what is missing: {response}"
         );
     }
+
+    // `?dry_run=1`: the same routes answer whether the command would be accepted, and keep nothing.
+    #[tokio::test]
+    async fn a_preview_through_the_api_routes_answers_the_envelope_and_keeps_nothing() {
+        let client = crate::dispatch_tests::tests::scratch_db("rust_host_api_preview_routes").await;
+        crate::dispatch_tests::tests::provision_lineage(
+            &*client.lock().await,
+            "Banking",
+            1,
+            &["Customer"],
+        )
+        .await;
+        let wasm = crate::dispatch_tests::tests::wasm_path();
+        let ir = banking_ir();
+        let lineage = LineageConfig {
+            domain: "Banking".to_string(),
+            era: Some(1),
+            mirrored: None,
+            seal_every: None,
+        };
+        let invoker = crate::lambda_client::NeverInvoker;
+        let host = || Host::new(&client, &wasm, &lineage, &invoker);
+        let ada = |reference: &str| {
+            format!(
+                r#"{{"reference":{{"value":"{reference}"}},"name":{{"given":"Ada","family":"Lovelace"}},"email":{{"address":"ada@example.com"}}}}"#
+            )
+        };
+        let caller = dispatch::Caller::default;
+
+        collection_create(&ir, "customers", &ada("CUST-9101"), caller(), false, host()).await;
+
+        let accepted =
+            collection_create(&ir, "customers", &ada("CUST-9102"), caller(), true, host()).await;
+        assert_eq!(accepted["statusCode"], 200, "{accepted}");
+        assert_eq!(body(&accepted), json!({ "ok": true, "refusals": [] }));
+        let absent = record_show(&ir, "customers", "CUST-9102", &client, &wasm, &lineage).await;
+        assert_eq!(
+            absent["statusCode"], 404,
+            "the preview kept a record: {absent}"
+        );
+
+        let duplicate =
+            collection_create(&ir, "customers", &ada("CUST-9101"), caller(), true, host()).await;
+        assert_eq!(duplicate["statusCode"], 200, "{duplicate}");
+        assert_eq!(body(&duplicate)["ok"], false);
+        assert_eq!(body(&duplicate)["refusals"][0]["refusal"], "AlreadyExists");
+
+        let suspend = r#"{"standing":{"value":"watch"}}"#;
+        let routed = command_route(
+            &ir,
+            "customers",
+            "CUST-9101",
+            "suspend",
+            suspend,
+            caller(),
+            true,
+            host(),
+        )
+        .await;
+        assert_eq!(
+            body(&routed),
+            json!({ "ok": true, "refusals": [] }),
+            "{routed}"
+        );
+        let shown = record_show(&ir, "customers", "CUST-9101", &client, &wasm, &lineage).await;
+        assert_ne!(
+            body(&shown)["status"],
+            "suspended",
+            "the preview suspended the customer"
+        );
+    }
 }
 
 #[cfg(test)]