hecks 3.0.2 → 3.0.4

data/rust/host/src/needs.rs

@@ -0,0 +1,243 @@
+// Facts a command `needs` (ADR 0081): the host answers them before the kernel reads the arguments,
+// the way the Ruby interpreter does in `decode_arguments`. The command's own IR carries
+// `"needs": [{"fact": "now"}]`; a needed fact the caller left out is filled with the clock's
+// answer, a supplied one is kept. The answer is written into the arguments before they are
+// journaled, so a replay re-dispatches the recorded value rather than asking the clock again.
+
+use serde_json::{json, Value};
+use std::sync::atomic::{AtomicI64, Ordering};
+
+/// What answers the `now` fact: epoch seconds, UTC.
+pub trait Clock {
+    fn now_secs(&self) -> i64;
+}
+
+/// The wall clock.
+pub struct SystemClock;
+
+impl Clock for SystemClock {
+    fn now_secs(&self) -> i64 {
+        std::time::SystemTime::now()
+            .duration_since(std::time::UNIX_EPOCH)
+            .map(|d| d.as_secs() as i64)
+            .unwrap_or_default()
+    }
+}
+
+/// A clock that always answers one moment, for tests.
+#[cfg(test)]
+pub struct FixedClock(pub i64);
+
+#[cfg(test)]
+impl Clock for FixedClock {
+    fn now_secs(&self) -> i64 {
+        self.0
+    }
+}
+
+const UNSET: i64 = i64::MIN;
+static OVERRIDE: AtomicI64 = AtomicI64::new(UNSET);
+
+/// Makes the process clock answer `secs` until `clear_fixed_clock`; for tests only.
+#[cfg(test)]
+pub fn set_fixed_clock(secs: i64) {
+    OVERRIDE.store(secs, Ordering::SeqCst);
+}
+
+#[cfg(test)]
+pub fn clear_fixed_clock() {
+    OVERRIDE.store(UNSET, Ordering::SeqCst);
+}
+
+/// The process clock the dispatcher uses: the wall clock unless a test has fixed it.
+pub struct ProcessClock;
+
+impl Clock for ProcessClock {
+    fn now_secs(&self) -> i64 {
+        match OVERRIDE.load(Ordering::SeqCst) {
+            UNSET => SystemClock.now_secs(),
+            fixed => fixed,
+        }
+    }
+}
+
+/// The command's declared needs, each with the type of the attribute of the same name.
+fn declared_needs<'a>(domain_ir: &'a Value, verb: &str) -> Vec<(&'a str, Option<&'a str>)> {
+    let Some((qualified_aggregate, command_name)) = verb.rsplit_once('.') else { return Vec::new() };
+    let aggregate = qualified_aggregate.rsplit("::").next().unwrap_or(qualified_aggregate);
+    let named = |value: &Value, name: &str| value.get("name").and_then(Value::as_str) == Some(name);
+    let list = |value: &'a Value, key: &str| -> Vec<&'a Value> {
+        value.get(key).and_then(Value::as_array).map(|a| a.iter().collect()).unwrap_or_default()
+    };
+    let mut needs = Vec::new();
+    for command in list(domain_ir, "aggregates")
+        .into_iter()
+        .filter(|a| named(a, aggregate))
+        .flat_map(|a| list(a, "commands"))
+        .filter(|c| named(c, command_name))
+    {
+        let attributes = list(command, "attributes");
+        for fact in list(command, "needs").into_iter().filter_map(|n| n.get("fact").and_then(Value::as_str)) {
+            let attribute_type =
+                attributes.iter().find(|a| named(a, fact)).and_then(|a| a.get("type")).and_then(Value::as_str);
+            needs.push((fact, attribute_type));
+        }
+    }
+    needs
+}
+
+/// Every command's needs as the kernel's input `"needs"` reads them: `{ verb: [{fact, type}] }`.
+/// The kernel answers a reaction's command from this (it has no IR of its own), and the same
+/// step's `occurred_at` keeps the answer the same on replay.
+pub fn table(domain_ir: &Value) -> Value {
+    let domain = domain_ir.get("name").and_then(Value::as_str).unwrap_or_default();
+    let mut verbs = serde_json::Map::new();
+    let aggregates = domain_ir.get("aggregates").and_then(Value::as_array).into_iter().flatten();
+    for aggregate in aggregates {
+        let aggregate_name = aggregate.get("name").and_then(Value::as_str).unwrap_or_default();
+        for command in aggregate.get("commands").and_then(Value::as_array).into_iter().flatten() {
+            let command_name = command.get("name").and_then(Value::as_str).unwrap_or_default();
+            let verb = format!("{domain}::{aggregate_name}.{command_name}");
+            let needs: Vec<Value> = declared_needs(domain_ir, &verb)
+                .into_iter()
+                .map(|(fact, attribute_type)| json!({"fact": fact, "type": attribute_type.unwrap_or("")}))
+                .collect();
+            if !needs.is_empty() {
+                verbs.insert(verb, Value::Array(needs));
+            }
+        }
+    }
+    Value::Object(verbs)
+}
+
+/// The facts of a command invocation: the `with` object when the call carries one, else the
+/// flat object itself (the kernel's `CommandInvocation` reads both shapes).
+fn facts_mut(args: &mut Value) -> Option<&mut serde_json::Map<String, Value>> {
+    if args.get("with").is_some_and(Value::is_object) {
+        return args.get_mut("with").and_then(Value::as_object_mut);
+    }
+    args.as_object_mut()
+}
+
+fn answer(fact: &str, attribute_type: Option<&str>, clock: &dyn Clock) -> Option<Value> {
+    match fact {
+        "now" => {
+            let secs = clock.now_secs();
+            Some(if attribute_type == Some("Integer") { json!(secs) } else { json!({ "value": secs }) })
+        }
+        _ => None,
+    }
+}
+
+/// Fills each fact `verb` needs that `args` leaves out, before any gate reads the arguments. A key
+/// the caller supplied (even a null) is kept; a command that needs nothing is untouched.
+pub fn fill_needs(domain_ir: &Value, verb: &str, args: &mut Value, clock: &dyn Clock) {
+    let needs = declared_needs(domain_ir, verb);
+    if needs.is_empty() {
+        return;
+    }
+    let Some(facts) = facts_mut(args) else { return };
+    for (fact, attribute_type) in needs {
+        if facts.contains_key(fact) {
+            continue;
+        }
+        if let Some(value) = answer(fact, attribute_type, clock) {
+            facts.insert(fact.to_string(), value);
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    const LEASE_IR: &str = include_str!("../../src/generated/lease_clock/ir.json");
+
+    fn lease_ir() -> Value {
+        serde_json::from_str(LEASE_IR).unwrap()
+    }
+
+    // A command whose `now` is an Integer attribute, as QualityControl's are.
+    fn integer_ir() -> Value {
+        json!({"name": "Qc", "aggregates": [{"name": "Check", "commands": [
+            {"name": "Run", "attributes": [{"name": "now", "type": "Integer"}], "needs": [{"fact": "now"}]},
+            {"name": "Plain", "attributes": [{"name": "now", "type": "Integer"}], "needs": []}
+        ]}]})
+    }
+
+    fn first_needing(ir: &Value) -> String {
+        ir["aggregates"]
+            .as_array()
+            .unwrap()
+            .iter()
+            .flat_map(|a| {
+                a["commands"].as_array().unwrap().iter().filter(|c| !c["needs"].as_array().unwrap().is_empty()).map(
+                    move |c| format!("{}::{}.{}", ir["name"].as_str().unwrap(), a["name"].as_str().unwrap(), c["name"].as_str().unwrap()),
+                )
+            })
+            .next()
+            .expect("the lease_clock domain declares a command that needs :now")
+    }
+
+    #[test]
+    fn a_needed_fact_the_caller_left_out_is_filled_from_the_clock() {
+        let ir = lease_ir();
+        let mut args = json!({"with": {"holder": "a"}});
+        fill_needs(&ir, &first_needing(&ir), &mut args, &FixedClock(1_700_000_000));
+        assert_eq!(args["with"]["now"], json!({"value": 1_700_000_000}));
+        assert_eq!(args["with"]["holder"], "a");
+    }
+
+    #[test]
+    fn a_flat_invocation_is_filled_at_its_top_level() {
+        let ir = lease_ir();
+        let mut args = json!({"holder": "a"});
+        fill_needs(&ir, &first_needing(&ir), &mut args, &FixedClock(5));
+        assert_eq!(args["now"], json!({"value": 5}));
+    }
+
+    #[test]
+    fn a_value_the_caller_supplied_is_kept() {
+        let ir = lease_ir();
+        let mut args = json!({"with": {"now": {"value": 42}}});
+        fill_needs(&ir, &first_needing(&ir), &mut args, &FixedClock(7));
+        assert_eq!(args["with"]["now"], json!({"value": 42}));
+    }
+
+    #[test]
+    fn a_command_with_no_needs_is_untouched() {
+        let ir = integer_ir();
+        let mut args = json!({"with": {"x": 1}});
+        fill_needs(&ir, "Qc::Check.Plain", &mut args, &FixedClock(7));
+        assert_eq!(args, json!({"with": {"x": 1}}));
+        let mut unknown = json!({"with": {}});
+        fill_needs(&ir, "Qc::Check.Nope", &mut unknown, &FixedClock(7));
+        assert_eq!(unknown, json!({"with": {}}));
+    }
+
+    #[test]
+    fn an_integer_attribute_gets_a_bare_integer_and_an_instant_a_value_object() {
+        let mut integer = json!({"with": {}});
+        fill_needs(&integer_ir(), "Qc::Check.Run", &mut integer, &FixedClock(9));
+        assert_eq!(integer["with"]["now"], json!(9));
+        let ir = lease_ir();
+        let mut instant = json!({"with": {}});
+        fill_needs(&ir, &first_needing(&ir), &mut instant, &FixedClock(9));
+        assert_eq!(instant["with"]["now"], json!({"value": 9}));
+    }
+
+    #[test]
+    fn the_kernel_table_lists_only_commands_that_need_something() {
+        let table = table(&integer_ir());
+        assert_eq!(table, json!({"Qc::Check.Run": [{"fact": "now", "type": "Integer"}]}));
+        assert_eq!(super::table(&json!({"name": "D"})), json!({}));
+    }
+
+    #[test]
+    fn the_process_clock_answers_a_fixed_moment_and_otherwise_the_wall_clock() {
+        set_fixed_clock(123);
+        assert_eq!(ProcessClock.now_secs(), 123);
+        clear_fixed_clock();
+        assert!(ProcessClock.now_secs() > 1_700_000_000);
+    }
+}

data/rust/host/src/resend.rs

@@ -43,7 +43,7 @@ impl Delivery {
 
 /// How email leaves the host: really, through Resend, or logged and dropped.
 pub enum Mailer {
-    Live { http: reqwest::Client, api_key: String, from: String, base_url: String },
+    Live { http: reqwest::Client, api_key: String, from: String, reply_to: Option<String>, base_url: String },
     Mock,
 }
 
@@ -53,6 +53,7 @@ impl Mailer {
     pub fn from_env() -> Result<Option<Mailer>, String> {
         let var = |name: &str| std::env::var(name).unwrap_or_default();
         Self::configured(&var("RESEND_API_KEY"), &var("RESEND_FROM"), &var("RESEND_MOCK"))
+            .map(|mailer| mailer.map(|mailer| mailer.replying_to(&var("RESEND_REPLY_TO"))))
     }
 
     fn configured(api_key: &str, from: &str, mock: &str) -> Result<Option<Mailer>, String> {
@@ -69,7 +70,19 @@ impl Mailer {
     /// A mailer that posts to `base_url` (Resend's API, or a stand-in in tests).
     pub fn live(api_key: &str, from: &str, base_url: &str) -> Mailer {
         let http = reqwest::Client::builder().timeout(TIMEOUT).build().expect("a reqwest client with a timeout always builds");
-        Mailer::Live { http, api_key: api_key.to_string(), from: from.to_string(), base_url: base_url.to_string() }
+        Mailer::Live { http, api_key: api_key.to_string(), from: from.to_string(), reply_to: None, base_url: base_url.to_string() }
+    }
+
+    /// Sets where replies go (`Reply-To`), when the address people reply to is not the one the mail
+    /// is sent from. Blank leaves replies going to the From address. A mock mailer has no replies.
+    pub fn replying_to(self, reply_to: &str) -> Mailer {
+        match self {
+            Mailer::Live { http, api_key, from, base_url, .. } => {
+                let reply_to = (!reply_to.trim().is_empty()).then(|| reply_to.trim().to_string());
+                Mailer::Live { http, api_key, from, reply_to, base_url }
+            }
+            mock => mock,
+        }
     }
 
     #[cfg(test)]
@@ -80,7 +93,7 @@ impl Mailer {
     pub async fn deliver(&self, email: &Email<'_>) -> Delivery {
         match self {
             Mailer::Mock => mock_deliver(email),
-            Mailer::Live { http, api_key, from, base_url } => live_deliver(http, api_key, from, base_url, email).await,
+            Mailer::Live { http, api_key, from, reply_to, base_url } => live_deliver(http, api_key, from, reply_to.as_deref(), base_url, email).await,
         }
     }
 }
@@ -93,8 +106,11 @@ fn mock_deliver(email: &Email<'_>) -> Delivery {
     Delivery::sent(format!("re_{}", uuid::Uuid::new_v4().simple()))
 }
 
-fn payload(from: &str, email: &Email<'_>) -> Value {
+fn payload(from: &str, reply_to: Option<&str>, email: &Email<'_>) -> Value {
     let mut payload = json!({ "from": from, "to": [email.to], "subject": email.subject });
+    if let Some(reply_to) = reply_to {
+        payload["reply_to"] = json!(reply_to);
+    }
     let content_key = if email.body.trim_start().starts_with('<') { "html" } else { "text" };
     payload[content_key] = json!(email.body);
     if let Some(url) = email.unsubscribe_url {
@@ -113,8 +129,8 @@ fn retry_delay(response: &reqwest::Response) -> Duration {
     Duration::from_secs(secs.min(MAX_RETRY_SECS))
 }
 
-async fn live_deliver(http: &reqwest::Client, api_key: &str, from: &str, base_url: &str, email: &Email<'_>) -> Delivery {
-    let body = payload(from, email);
+async fn live_deliver(http: &reqwest::Client, api_key: &str, from: &str, reply_to: Option<&str>, base_url: &str, email: &Email<'_>) -> Delivery {
+    let body = payload(from, reply_to, email);
     for attempt in 1..=MAX_ATTEMPTS {
         let response = match http.post(format!("{base_url}/emails")).bearer_auth(api_key).json(&body).send().await {
             Ok(r) => r,
@@ -225,19 +241,45 @@ mod tests {
 
     #[test]
     fn an_html_body_goes_as_html_and_a_plain_one_as_text() {
-        assert!(payload("f", &email("a@b.com", "  <p>hi</p>")).get("html").is_some());
-        let plain = payload("f", &email("a@b.com", "just a link"));
+        assert!(payload("f", None, &email("a@b.com", "  <p>hi</p>")).get("html").is_some());
+        let plain = payload("f", None, &email("a@b.com", "just a link"));
         assert!(plain.get("text").is_some() && plain.get("html").is_none());
     }
 
     #[test]
     fn the_unsubscribe_url_rides_as_a_list_unsubscribe_header() {
-        let with = payload("f", &email("a@b.com", "x"));
+        let with = payload("f", None, &email("a@b.com", "x"));
         assert_eq!(with["headers"]["List-Unsubscribe"], "<https://example.com/newsletter-unsubscribed.html?email=a%40b.com>");
-        let without = payload("f", &Email { to: "a@b.com", subject: "s", body: "x", unsubscribe_url: None });
+        let without = payload("f", None, &Email { to: "a@b.com", subject: "s", body: "x", unsubscribe_url: None });
         assert!(without.get("headers").is_none());
     }
 
+    #[test]
+    fn a_reply_to_address_rides_in_the_payload_and_is_absent_without_one() {
+        let with = payload("f", Some("lifeadelics@gmail.com"), &email("a@b.com", "x"));
+        assert_eq!(with["reply_to"], "lifeadelics@gmail.com");
+        assert!(payload("f", None, &email("a@b.com", "x")).get("reply_to").is_none());
+    }
+
+    #[test]
+    fn replying_to_trims_the_address_and_a_blank_one_sets_none() {
+        let set = Mailer::live("re_x", "n@mail.example.com", "http://x").replying_to("  me@example.com ");
+        assert!(matches!(&set, Mailer::Live { reply_to: Some(r), .. } if r == "me@example.com"));
+        let blank = Mailer::live("re_x", "n@mail.example.com", "http://x").replying_to("   ");
+        assert!(matches!(&blank, Mailer::Live { reply_to: None, .. }));
+        assert!(Mailer::Mock.replying_to("me@example.com").is_mock(), "a mock mailer has no replies");
+    }
+
+    #[tokio::test]
+    async fn a_live_send_carries_the_reply_to_address_to_resend() {
+        let fake = FakeResend::start(vec![("200 OK", "", r#"{"id":"em_9"}"#)]);
+        let mailer = Mailer::live("re_x", "News <n@mail.example.com>", &fake.base).replying_to("lifeadelics@gmail.com");
+
+        mailer.deliver(&email("a@b.com", "x")).await;
+
+        assert!(fake.requests()[0].contains(r#""reply_to":"lifeadelics@gmail.com""#), "{}", fake.requests()[0]);
+    }
+
     #[test]
     fn the_mock_logs_instead_of_sending_and_bounces_the_test_address() {
         let sent = mock_deliver(&email("a@b.com", "x"));

data/rust/host/src/server.rs

@@ -53,25 +53,29 @@ pub async fn dispatch_body(
         .ok_or("event missing \"verb\"")?
         .to_string();
     let role = body.get("role").and_then(|v| v.as_str()).map(|s| s.to_string());
+    // Who the caller is, for Governance. Honored only where the internal protocol is: from this
+    // host's own peers (`trusts_internal_dispatch`), never from a public caller.
+    let actor_id = body.get("actor_id").and_then(|v| v.as_str()).map(|s| s.to_string());
+    let caller = dispatch::Caller { role: role.as_deref(), actor_id: actor_id.as_deref() };
 
     let outcome = if let Some(to) = body.get("to").cloned() {
         if body.get("args").is_some() {
             return Err("cannot combine to/with with legacy args".into());
         }
         let facts = body.get("with").cloned().unwrap_or_else(|| serde_json::json!({}));
-        dispatch::handle_routed(client, wasm_path, &verb, to, facts, role.as_deref(), config, invoker)
+        dispatch::handle_routed_as(client, wasm_path, &verb, to, facts, caller, config, invoker)
             .await
             .map_err(|e| format!("{e:#}"))?
     } else if let Some(facts) = body.get("with").cloned() {
         if body.get("args").is_some() {
             return Err("cannot combine \"with\" with legacy args".into());
         }
-        dispatch::handle_facts(client, wasm_path, &verb, facts, role.as_deref(), config, invoker)
+        dispatch::handle_facts_as(client, wasm_path, &verb, facts, caller, config, invoker)
             .await
             .map_err(|e| format!("{e:#}"))?
     } else {
         let args = body.get("args").cloned().unwrap_or_else(|| serde_json::json!({}));
-        dispatch::handle(client, wasm_path, &verb, args, role.as_deref(), config, invoker)
+        dispatch::handle_as(client, wasm_path, &verb, args, caller, config, invoker)
             .await
             .map_err(|e| format!("{e:#}"))?
     };

data/rust/host/src/web.rs

@@ -373,10 +373,11 @@ async fn accounts_me_route(domain_ir: &Value, cookies: &HashMap<String, String>,
     }
 }
 
-// GET /members: admitted people as JSON, for a caller holding the
-// account cookie but not the Governance session /admin/members needs.
+// GET /members: admitted people as JSON, for an Admin or Owner holding the
+// account cookie but not the Governance session /admin/members needs. The list
+// is every person's name, email and role, so a plain member does not get it.
 async fn members_route(domain_ir: &Value, cookies: &HashMap<String, String>, secret: &str, client: &Mutex<Client>) -> Value {
-    if let Err(response) = active_session_email(domain_ir, cookies, secret, client).await {
+    if let Err(response) = newsletter_send::require_admin(domain_ir, cookies, secret, client).await {
         return response;
     }
     match auth::all_people(client, domain_ir).await {
@@ -2302,6 +2303,32 @@ mod tests {
         }
     }
 
+    #[tokio::test]
+    async fn members_route_refuses_a_plain_member_with_a_403_and_no_people() {
+        let secret = "s3cret";
+        let (client, domain_ir) = scratch_members_db("hecks_host_web_test_members_route_403").await;
+        client
+            .lock()
+            .await
+            .execute(
+                "INSERT INTO acme_member_head_snapshot_1 (id, ordinal, state) VALUES ($1, 0, $2::jsonb)",
+                &[
+                    &"max@example.com",
+                    &json!({"name": {"value": "Max"}, "email": {"value": "max@example.com"},
+                            "role": {"value": "Member"}, "identity_id": {"value": "id-2"}}),
+                ],
+            )
+            .await
+            .unwrap();
+
+        let response = members_route(&domain_ir, &session_cookies(secret, "max@example.com"), secret, &client).await;
+        assert_eq!(response["statusCode"], 403, "{response:?}");
+        let body = response["body"].as_str().unwrap();
+        for leaked in ["zed@example.com", "amy@example.com", "Zed"] {
+            assert!(!body.contains(leaked), "{leaked:?} leaked to a plain member: {body}");
+        }
+    }
+
     fn session_cookies(secret: &str, email: &str) -> HashMap<String, String> {
         let mut cookies = HashMap::new();
         cookies.insert(auth::account_cookie_name(), auth::account_token(secret, email, 60));
@@ -2808,9 +2835,15 @@ mod tests {
             } else {
                 assert_eq!((add, registrations, disable, enable), (403, 403, 403, 403), "{caller} is refused everywhere");
             }
-            // Listing needs access, not admin: a Member may list, a stranger may not.
+            // Listing is an admin gate too: it carries every person's email and role, so an
+            // Admin or Owner lists, a Member is refused, and a stranger has no session at all.
             let listing = status_of(members_route(&domain_ir, &cookies, secret, &client).await).await;
-            assert_eq!(listing, if caller == "stranger@example.com" { 401 } else { 200 }, "{caller} listing");
+            let expected = match caller {
+                "stranger@example.com" => 401,
+                _ if admits => 200,
+                _ => 403,
+            };
+            assert_eq!(listing, expected, "{caller} listing");
         }
 
         // Anonymous: 401 on every route, before any role is looked at.

data/rust/parser/src/canonical.rs

@@ -1,5 +1,5 @@
 //! Source-body slicing and whitespace collapse, mirroring Ruby's `CanonicalForm`.
-//! Hand-mirrored from projection.json: a third rule there needs a matching rule here.
+//! Hand-mirrored from projection.json: a rule there (collapse_whitespace, replace, scale_call) needs a matching rule here.
 
 /// Slices the raw source between two byte offsets, before any normalisation.
 pub fn slice(source: &str, start: usize, end: usize) -> &str {
@@ -11,7 +11,87 @@ pub fn slice(source: &str, start: usize, end: usize) -> &str {
 pub fn apply(source: &str) -> String {
     let collapsed = map_outside_strings(source, collapse_whitespace);
     let replaced = map_outside_strings(&collapsed, |run| replace_word_boundary(run, ".length", ".size"));
-    replaced.trim().to_string()
+    let scaled = SCALE_CALLS.iter().fold(replaced, |text, (token, seconds)| {
+        map_outside_strings(&text, |run| scale_call(run, token, seconds))
+    });
+    scaled.trim().to_string()
+}
+
+/// The `scale_call` rows of projection.json, in position order: (call name, seconds per unit).
+const SCALE_CALLS: [(&str, &str); 3] = [("days", "86400"), ("hours", "3600"), ("minutes", "60")];
+
+/// Every normalisation row of projection.json as (strategy, source_token, replacement,
+/// boundary, position), in position order; emitted into the IR's expression table.
+pub const TABLE: [(&str, &str, &str, &str, &str); 5] = [
+    ("collapse_whitespace", "", "", "none", "1"),
+    ("replace", ".length", ".size", "word", "2"),
+    ("scale_call", "days", "86400", "word", "3"),
+    ("scale_call", "hours", "3600", "word", "4"),
+    ("scale_call", "minutes", "60", "word", "5"),
+];
+
+/// Folds `token(<whole number>)` into the number times `seconds`, as Ruby's `scale_call` does.
+/// The name must not follow a word character, digit, underscore or dot; spaces inside the
+/// parentheses are allowed; any other argument leaves the call as written.
+fn scale_call(text: &str, token: &str, seconds: &str) -> String {
+    let mut out = String::with_capacity(text.len());
+    let mut i = 0;
+    while i < text.len() {
+        if text[i..].starts_with(token) {
+            let preceded = text[..i]
+                .chars()
+                .next_back()
+                .map_or(false, |c| c.is_alphanumeric() || c == '_' || c == '.');
+            if !preceded {
+                if let Some((digits, len)) = whole_number_call(&text[i + token.len()..]) {
+                    out.push_str(&multiply(digits, seconds));
+                    i += token.len() + len;
+                    continue;
+                }
+            }
+        }
+        let ch = text[i..].chars().next().unwrap();
+        out.push(ch);
+        i += ch.len_utf8();
+    }
+    out
+}
+
+/// Matches `(` spaces digits spaces `)` at the start of `rest`; returns the digits and the
+/// matched length.
+fn whole_number_call(rest: &str) -> Option<(&str, usize)> {
+    let inner = rest.strip_prefix('(')?;
+    let digits_at = inner.len() - inner.trim_start_matches(char::is_whitespace).len();
+    let body = &inner[digits_at..];
+    let digit_len = body.bytes().take_while(|b| b.is_ascii_digit()).count();
+    if digit_len == 0 {
+        return None;
+    }
+    let tail = &body[digit_len..];
+    let close = tail.len() - tail.trim_start_matches(char::is_whitespace).len();
+    tail[close..].strip_prefix(')')?;
+    Some((&body[..digit_len], 1 + digits_at + digit_len + close + 1))
+}
+
+/// Decimal `digits` times the decimal `factor`, as text with no leading zeros (any length).
+fn multiply(digits: &str, factor: &str) -> String {
+    let factor: u32 = factor.parse().expect("scale factor is a whole number");
+    let mut carry = 0u32;
+    let mut out: Vec<u8> = Vec::with_capacity(digits.len() + 6);
+    for d in digits.bytes().rev() {
+        let v = (d - b'0') as u32 * factor + carry;
+        out.push(b'0' + (v % 10) as u8);
+        carry = v / 10;
+    }
+    while carry > 0 {
+        out.push(b'0' + (carry % 10) as u8);
+        carry /= 10;
+    }
+    while out.len() > 1 && out.last() == Some(&b'0') {
+        out.pop();
+    }
+    out.reverse();
+    String::from_utf8(out).unwrap()
 }
 
 /// Applies `transform` to the unquoted runs of `text` and copies quoted runs verbatim;
@@ -104,6 +184,61 @@ mod tests {
         assert_eq!(apply("lengthy"), "lengthy");
     }
 
+    #[test]
+    fn folds_duration_calls_into_seconds() {
+        assert_eq!(apply("days(730)"), "63072000");
+        assert_eq!(apply("days( 1 ) + hours(2) + minutes(15)"), "86400 + 7200 + 900");
+        assert_eq!(
+            apply("x.days(3) workdays(3) days(n) days(1.5)"),
+            "x.days(3) workdays(3) days(n) days(1.5)"
+        );
+        assert_eq!(apply("'days(2)' == days(0)"), "'days(2)' == 0");
+    }
+
+    /// Splits JSON text into its string literals, decoding escapes.
+    fn json_strings(text: &str) -> Vec<String> {
+        let mut out = Vec::new();
+        let mut chars = text.chars();
+        while let Some(c) = chars.next() {
+            if c != '"' {
+                continue;
+            }
+            let mut s = String::new();
+            while let Some(c) = chars.next() {
+                match c {
+                    '"' => break,
+                    '\\' => match chars.next().unwrap() {
+                        'n' => s.push('\n'),
+                        't' => s.push('\t'),
+                        'r' => s.push('\r'),
+                        'u' => {
+                            let hex: String = chars.by_ref().take(4).collect();
+                            s.push(char::from_u32(u32::from_str_radix(&hex, 16).unwrap()).unwrap());
+                        }
+                        other => s.push(other),
+                    },
+                    c => s.push(c),
+                }
+            }
+            out.push(s);
+        }
+        out
+    }
+
+    #[test]
+    fn matches_the_shared_canonical_form_cases() {
+        let path = concat!(env!("CARGO_MANIFEST_DIR"), "/../../spec/fixtures/canonical_form_cases.json");
+        let text = std::fs::read_to_string(path).expect("shared cases file");
+        let strings = json_strings(&text);
+        let start = strings.iter().position(|s| s == "cases").expect("cases key") + 1;
+        let rows: Vec<&[String]> = strings[start..].chunks(4).collect();
+        assert!(!rows.is_empty());
+        for row in rows {
+            assert_eq!((row[0].as_str(), row[2].as_str()), ("source", "canonical"));
+            assert_eq!(apply(&row[1]), row[3], "source {:?}", row[1]);
+        }
+    }
+
     #[test]
     fn slices_the_exact_source_span() {
         let source = "given(\"ok\") { balance >= amount }";