hecks 3.9.1 → 3.11.0

data/rust/host/src/checkout.rs

@@ -7,10 +7,6 @@ use sha2::Sha256;
 
 type HmacSha256 = Hmac<Sha256>;
 
-// docs.stripe.com/webhooks#verify-events — 5 minutes, guards against a
-// replayed old payload even against a leaked (not yet rotated) secret.
-const TOLERANCE_SECONDS: i64 = 300;
-
 pub struct SignatureError(pub String);
 
 impl std::fmt::Display for SignatureError {
@@ -22,7 +18,10 @@ impl std::fmt::Display for SignatureError {
 // Signs `<timestamp>.<raw body>`, the exact bytes Stripe sent -- re-serializing
 // the JSON would disagree on whitespace or key order and break every match.
 // `now` is a parameter, not read internally, so a test can hold time fixed.
-pub fn verify_signature(payload: &str, header: &str, secret: &str, now: i64) -> Result<(), SignatureError> {
+// `tolerance_seconds` is the freshness window the Checkout bluebook declares
+// (`WebhookReceipt.tolerance`, read from the IR): it guards against a replayed
+// old payload even against a leaked (not yet rotated) secret.
+pub fn verify_signature(payload: &str, header: &str, secret: &str, now: i64, tolerance_seconds: i64) -> Result<(), SignatureError> {
     let mut timestamp: Option<i64> = None;
     let mut signatures: Vec<&str> = Vec::new();
     for part in header.split(',') {
@@ -39,9 +38,9 @@ pub fn verify_signature(payload: &str, header: &str, secret: &str, now: i64) ->
     if signatures.is_empty() {
         return Err(SignatureError("Stripe-Signature header has no v1= signature".to_string()));
     }
-    if (now - timestamp).abs() > TOLERANCE_SECONDS {
+    if (now - timestamp).abs() > tolerance_seconds {
         return Err(SignatureError(format!(
-            "timestamp {timestamp} is outside the {TOLERANCE_SECONDS}s tolerance (now: {now})"
+            "timestamp {timestamp} is outside the {tolerance_seconds}s tolerance (now: {now})"
         )));
     }
 
@@ -98,11 +97,19 @@ pub struct EmbeddedSession {
     pub client_secret: String,
 }
 
-// 31, not 30: Stripe requires an expiry at least 30 minutes out.
-pub const SESSION_HOLD_SECONDS: i64 = 31 * 60;
+// 31, not 30: Stripe requires an expiry at least 30 minutes out. This floor is a
+// fact about the processor, so it lives here in the adapter; the domain declares
+// only how long a session holds its seat (`CheckoutSession.hold`), and a hold
+// shorter than the floor is raised to it.
+pub const STRIPE_MIN_HOLD_SECONDS: i64 = 31 * 60;
+
+/// The hold actually sent to Stripe for a domain hold of `hold_seconds`.
+pub fn effective_hold_seconds(hold_seconds: i64) -> i64 {
+    hold_seconds.max(STRIPE_MIN_HOLD_SECONDS)
+}
 
-pub fn session_expires_at(now: i64) -> i64 {
-    now + SESSION_HOLD_SECONDS
+pub fn session_expires_at(now: i64, hold_seconds: i64) -> i64 {
+    now + effective_hold_seconds(hold_seconds)
 }
 
 // Errors carry Stripe's message when it refuses, never a secret.
@@ -158,6 +165,8 @@ pub async fn create_checkout_session(
 mod tests {
     use super::*;
 
+    const TOLERANCE_SECONDS: i64 = 300;
+
     fn sign(secret: &str, timestamp: i64, payload: &str) -> String {
         let signed_payload = format!("{timestamp}.{payload}");
         let mut mac = HmacSha256::new_from_slice(secret.as_bytes()).unwrap();
@@ -195,7 +204,7 @@ mod tests {
         let now = 1_700_000_000;
         let header = format!("t={now},v1={}", sign(secret, now, payload));
 
-        assert!(verify_signature(payload, &header, secret, now).is_ok());
+        assert!(verify_signature(payload, &header, secret, now, TOLERANCE_SECONDS).is_ok());
     }
 
     #[test]
@@ -207,7 +216,7 @@ mod tests {
         // Same header, different body — exactly what an attacker
         // intercepting and rewriting the request in transit would send.
         let tampered = r#"{"type":"checkout.session.expired"}"#;
-        assert!(verify_signature(tampered, &header, secret, now).is_err());
+        assert!(verify_signature(tampered, &header, secret, now, TOLERANCE_SECONDS).is_err());
     }
 
     #[test]
@@ -216,7 +225,7 @@ mod tests {
         let now = 1_700_000_000;
         let header = format!("t={now},v1={}", sign("whsec_real", now, payload));
 
-        assert!(verify_signature(payload, &header, "whsec_wrong", now).is_err());
+        assert!(verify_signature(payload, &header, "whsec_wrong", now, TOLERANCE_SECONDS).is_err());
     }
 
     #[test]
@@ -231,7 +240,14 @@ mod tests {
         // to be a separate, independent gate rather than folded into
         // "does the signature verify at all."
         let much_later = signed_at + TOLERANCE_SECONDS + 1;
-        assert!(verify_signature(payload, &header, secret, much_later).is_err());
+        assert!(verify_signature(payload, &header, secret, much_later, TOLERANCE_SECONDS).is_err());
+    }
+
+    #[test]
+    fn a_hold_shorter_than_stripes_floor_is_raised_to_it() {
+        assert_eq!(effective_hold_seconds(1800), STRIPE_MIN_HOLD_SECONDS);
+        assert_eq!(effective_hold_seconds(3600), 3600);
+        assert_eq!(session_expires_at(1_000, 1800), 1_000 + STRIPE_MIN_HOLD_SECONDS);
     }
 
     #[test]
@@ -246,20 +262,20 @@ mod tests {
             sign(new_secret, now, payload)
         );
 
-        assert!(verify_signature(payload, &header, old_secret, now).is_ok());
-        assert!(verify_signature(payload, &header, new_secret, now).is_ok());
+        assert!(verify_signature(payload, &header, old_secret, now, TOLERANCE_SECONDS).is_ok());
+        assert!(verify_signature(payload, &header, new_secret, now, TOLERANCE_SECONDS).is_ok());
     }
 
     #[test]
     fn a_header_with_no_v1_at_all_is_rejected() {
         let now = 1_700_000_000;
         let header = format!("t={now}");
-        assert!(verify_signature("{}", &header, "whsec_test", now).is_err());
+        assert!(verify_signature("{}", &header, "whsec_test", now, TOLERANCE_SECONDS).is_err());
     }
 
     #[test]
     fn a_header_with_no_timestamp_at_all_is_rejected() {
         let header = "v1=deadbeef".to_string();
-        assert!(verify_signature("{}", &header, "whsec_test", 1_700_000_000).is_err());
+        assert!(verify_signature("{}", &header, "whsec_test", 1_700_000_000, TOLERANCE_SECONDS).is_err());
     }
 }

data/rust/host/src/commerce_ir.rs

@@ -20,9 +20,152 @@ pub struct NewsletterProvider {
     pub unsubscribe: String,
     /// Qualified subscribing aggregate, e.g. `Newsletter::Subscriber`.
     pub aggregate: String,
+    /// Subscriber states awaiting the emailed confirm link: the
+    /// `awaiting_confirmation` list of the `newsletter` fact (the lifecycle's
+    /// mark), or [`LEGACY_AWAITING_CONFIRMATION`] when the chapter declares none.
+    pub awaiting_confirmation: Vec<String>,
+    /// Subscriber states that receive each issue: the `receives_issues` list,
+    /// or [`LEGACY_RECEIVES_ISSUES`] when the chapter declares none.
+    pub receives_issues: Vec<String>,
+    /// Subscriber states of someone who has left: the `left` list, or
+    /// [`LEGACY_LEFT`] when the chapter declares none.
+    pub left: Vec<String>,
+    /// Seconds the emailed confirm link stays valid: the `confirm_window` of
+    /// the `newsletter` fact (ADR 0098), or [`LEGACY_CONFIRM_WINDOW_SECS`].
+    pub confirm_window: u64,
+    /// Seconds an emailed unsubscribe link stays valid: the `unsubscribe_window`,
+    /// or [`LEGACY_UNSUBSCRIBE_WINDOW_SECS`].
+    pub unsubscribe_window: u64,
+}
+
+/// LEGACY DEFAULT: how long the emailed confirm link lasts (14 days), used
+/// while the `newsletter` fact carries no `confirm_window`, because the
+/// Newsletter chapter predates ADR 0098 and does not declare
+/// `provides "newsletter", ..., confirm_window: "Subscriber.confirm_window"`.
+/// Delete this (and the fallback in `newsletter_provider`) once every shipped
+/// Newsletter bluebook does.
+pub const LEGACY_CONFIRM_WINDOW_SECS: u64 = 14 * 24 * 60 * 60;
+
+/// LEGACY DEFAULT: how long an emailed unsubscribe link lasts (730 days), used
+/// while the `newsletter` fact carries no `unsubscribe_window` (see
+/// [`LEGACY_CONFIRM_WINDOW_SECS`]).
+pub const LEGACY_UNSUBSCRIBE_WINDOW_SECS: u64 = 730 * 24 * 60 * 60;
+
+/// The whole seconds the fact `fact` lists under `key`: an attribute default
+/// resolved by the exporter (ADR 0098). `None` when the fact omits it.
+fn declared_seconds(fact: &Value, key: &str) -> Option<u64> {
+    fact.get(key)?.as_u64().filter(|seconds| *seconds > 0)
+}
+
+/// The declared seconds for `key`, else `legacy` with a single warning per process.
+fn seconds_or_legacy(fact: &Value, capability: &str, key: &str, legacy: u64, warned: &std::sync::Once) -> u64 {
+    declared_seconds(fact, key).unwrap_or_else(|| {
+        warned.call_once(|| eprintln!("{capability} capability declares no {key}; using built-in default"));
+        legacy
+    })
+}
+
+/// The checkout boundary's windows, read from `ir.json`'s own `checkout` key
+/// (ADR 0098). Always present: a window the chapter does not declare takes its
+/// labelled legacy default.
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct CheckoutWindows {
+    /// Seconds either side of now a signed webhook's timestamp may sit.
+    pub webhook_tolerance: i64,
+    /// Seconds a checkout session holds its seat (before the processor's own
+    /// minimum is applied by the checkout adapter).
+    pub session_hold: i64,
+}
+
+/// LEGACY DEFAULT: the webhook freshness window (5 minutes), used while the
+/// `checkout` fact carries no `webhook_tolerance`, because no shipped Checkout
+/// bluebook declares `provides "checkout", webhook_tolerance: "WebhookReceipt.tolerance"`.
+/// Delete this (and the fallback in `checkout_windows`) once every one does.
+pub const LEGACY_WEBHOOK_TOLERANCE_SECS: i64 = 300;
+
+/// LEGACY DEFAULT: the seat hold of a session (30 minutes), used while the
+/// `checkout` fact carries no `session_hold` (see [`LEGACY_WEBHOOK_TOLERANCE_SECS`]).
+pub const LEGACY_SESSION_HOLD_SECS: i64 = 30 * 60;
+
+/// The checkout windows `domain_ir` declares, each falling back to its legacy default.
+pub fn checkout_windows(domain_ir: &Value) -> CheckoutWindows {
+    static TOLERANCE_WARNED: std::sync::Once = std::sync::Once::new();
+    static HOLD_WARNED: std::sync::Once = std::sync::Once::new();
+    let fact = domain_ir.get("checkout").unwrap_or(&Value::Null);
+    let seconds = |key, legacy: i64, warned| seconds_or_legacy(fact, "checkout", key, legacy as u64, warned) as i64;
+    CheckoutWindows {
+        webhook_tolerance: seconds("webhook_tolerance", LEGACY_WEBHOOK_TOLERANCE_SECS, &TOLERANCE_WARNED),
+        session_hold: seconds("session_hold", LEGACY_SESSION_HOLD_SECS, &HOLD_WARNED),
+    }
+}
+
+/// The checkout windows of the IR this host loaded (legacy defaults without one).
+pub fn checkout_windows_binding() -> CheckoutWindows {
+    checkout_windows(ir().unwrap_or(&Value::Null))
+}
+
+/// The confirm-link and unsubscribe-link windows of the IR this host loaded:
+/// `(confirm, unsubscribe)` seconds, legacy defaults without a `newsletter` fact.
+pub fn newsletter_windows_binding() -> (u64, u64) {
+    ir().and_then(newsletter_provider)
+        .map(|p| (p.confirm_window, p.unsubscribe_window))
+        .unwrap_or((LEGACY_CONFIRM_WINDOW_SECS, LEGACY_UNSUBSCRIBE_WINDOW_SECS))
+}
+
+/// LEGACY DEFAULT: the states a new subscriber waits in, used while the
+/// `newsletter` fact carries no `awaiting_confirmation` list, because the
+/// Newsletter chapter predates the marks and does not declare
+/// `provides "newsletter", ..., awaiting_confirmation: "Subscriber.awaiting_confirmation"`.
+/// Delete this (and the fallback in `newsletter_provider`) once every shipped
+/// Newsletter bluebook does.
+pub const LEGACY_AWAITING_CONFIRMATION: [&str; 1] = ["pending"];
+
+/// LEGACY DEFAULT: the states that receive an issue, used while the
+/// `newsletter` fact carries no `receives_issues` list (see
+/// [`LEGACY_AWAITING_CONFIRMATION`]).
+pub const LEGACY_RECEIVES_ISSUES: [&str; 1] = ["confirmed"];
+
+/// LEGACY DEFAULT: the states of a subscriber who has left, used while the
+/// `newsletter` fact carries no `left` list (see [`LEGACY_AWAITING_CONFIRMATION`]).
+pub const LEGACY_LEFT: [&str; 1] = ["unsubscribed"];
+
+/// The states the `newsletter` fact lists under `key`: a lifecycle mark
+/// resolved by the exporter. `None` when the fact omits it.
+fn declared_states(fact: &Value, key: &str) -> Option<Vec<String>> {
+    let states = fact.get(key)?.as_array()?;
+    Some(states.iter().filter_map(|s| s.as_str().map(String::from)).collect())
+}
+
+/// The declared states for `key`, else `legacy` with a single warning per process.
+fn states_or_legacy(fact: &Value, key: &str, legacy: &[&str], warned: &std::sync::Once) -> Vec<String> {
+    declared_states(fact, key).unwrap_or_else(|| {
+        warned.call_once(|| eprintln!("newsletter capability declares no {key}; using built-in default"));
+        legacy.iter().map(|s| s.to_string()).collect()
+    })
 }
 
 impl NewsletterProvider {
+    /// Whether `status` is a state awaiting confirmation.
+    pub fn is_awaiting_confirmation(&self, status: Option<&str>) -> bool {
+        status.is_some_and(|s| self.awaiting_confirmation.iter().any(|m| m == s))
+    }
+
+    /// Whether `status` is a state that receives issues.
+    pub fn receives_issues(&self, status: Option<&str>) -> bool {
+        status.is_some_and(|s| self.receives_issues.iter().any(|m| m == s))
+    }
+
+    /// Whether `status` is a state of a subscriber who has left.
+    pub fn has_left(&self, status: Option<&str>) -> bool {
+        status.is_some_and(|s| self.left.iter().any(|m| m == s))
+    }
+
+    /// The state a subscriber is reported in when none is recorded yet: the
+    /// first awaiting-confirmation state.
+    pub fn initial_status(&self) -> &str {
+        self.awaiting_confirmation.first().map(String::as_str).unwrap_or("")
+    }
+
     /// The prefix every subscriber's key in a `dispatch::read` `instances`
     /// map starts with, e.g. `Newsletter::Subscriber#`.
     pub fn instance_prefix(&self) -> String {
@@ -49,8 +192,18 @@ pub fn command_declares(domain_ir: &Value, aggregate: &str, command: &str, field
 }
 
 pub fn newsletter_provider(domain_ir: &Value) -> Option<NewsletterProvider> {
+    static AWAITING_WARNED: std::sync::Once = std::sync::Once::new();
+    static RECEIVES_WARNED: std::sync::Once = std::sync::Once::new();
+    static LEFT_WARNED: std::sync::Once = std::sync::Once::new();
+    static CONFIRM_WINDOW_WARNED: std::sync::Once = std::sync::Once::new();
+    static UNSUBSCRIBE_WINDOW_WARNED: std::sync::Once = std::sync::Once::new();
     let fact = domain_ir.get("newsletter")?;
     Some(NewsletterProvider {
+        confirm_window: seconds_or_legacy(fact, "newsletter", "confirm_window", LEGACY_CONFIRM_WINDOW_SECS, &CONFIRM_WINDOW_WARNED),
+        unsubscribe_window: seconds_or_legacy(fact, "newsletter", "unsubscribe_window", LEGACY_UNSUBSCRIBE_WINDOW_SECS, &UNSUBSCRIBE_WINDOW_WARNED),
+        awaiting_confirmation: states_or_legacy(fact, "awaiting_confirmation", &LEGACY_AWAITING_CONFIRMATION, &AWAITING_WARNED),
+        receives_issues: states_or_legacy(fact, "receives_issues", &LEGACY_RECEIVES_ISSUES, &RECEIVES_WARNED),
+        left: states_or_legacy(fact, "left", &LEGACY_LEFT, &LEFT_WARNED),
         provider: fact.get("provider")?.as_str()?.to_string(),
         subscribe: fact.get("subscribe")?.as_str()?.to_string(),
         add_name: fact.get("add_name")?.as_str()?.to_string(),
@@ -108,6 +261,49 @@ pub struct PaymentsProvider {
     pub failed: String,
     /// Qualified paying aggregate, e.g. `Payments::Payment`.
     pub aggregate: String,
+    /// Payment states whose registration still holds a seat: the `holds_seat`
+    /// list of the `payments` fact (the payment lifecycle's mark), or
+    /// [`LEGACY_HOLDS_SEAT`] when the chapter declares none.
+    pub holds_seat: Vec<String>,
+    /// The failure reason a lapsed checkout hold records: the `lapse_reason` of
+    /// the `payments` fact (ADR 0099), or [`LEGACY_LAPSE_REASON`] when the
+    /// chapter declares none.
+    pub lapse_reason: String,
+}
+
+/// LEGACY DEFAULT: the failure reason a lapsed hold records, used while the
+/// `payments` capability fact carries no `lapse_reason` because the Payments
+/// chapter predates `provides "payments", lapse_reason: "Payment.lapse_reason"`.
+/// Delete this (and the fallback in `payments_provider`) once every shipped
+/// Payments bluebook declares it.
+pub const LEGACY_LAPSE_REASON: &str = "checkout_expired";
+
+/// LEGACY DEFAULT: the registration attributes guessed to hold the timestamp, in
+/// order, used while the `registrations` fact carries no `registered_at` because
+/// the chapter predates `provides "registrations", registered_at: "Registration.requested_at"`.
+/// Delete this (and the fallback in `registrations_provider`) once every shipped
+/// bluebook declares it.
+pub const LEGACY_REGISTERED_AT: [&str; 4] = ["created_at", "registered_at", "requested_at", "occurred_at"];
+
+/// LEGACY DEFAULT: the seat-holding payment states used while the `payments`
+/// capability fact carries no `holds_seat` list, because the Payments chapter
+/// predates `mark :holds_seat` and does not declare
+/// `provides "payments", holds_seat: "Payment.holds_seat"`. Delete this (and the
+/// fallback in `payments_provider`) once every shipped Payments bluebook does.
+pub const LEGACY_HOLDS_SEAT: [&str; 4] = ["pending", "succeeded", "refunding", "disputed"];
+
+/// LEGACY DEFAULT: the registration state that gives its seat back, used while the
+/// `registrations` capability fact carries no `frees_seat` list, because the chapter
+/// predates `mark :frees_seat` and does not declare
+/// `provides "registrations", frees_seat: "Registration.frees_seat"`. Delete this (and the
+/// fallback in `registrations_provider`) once every shipped bluebook declares it.
+pub const LEGACY_FREES_SEAT: [&str; 1] = ["archived"];
+
+/// The states the `payments` fact lists under `holds_seat`: the aggregate's
+/// lifecycle mark, resolved by the exporter. `None` when the fact omits it.
+fn declared_holds_seat(fact: &Value) -> Option<Vec<String>> {
+    let states = fact.get("holds_seat")?.as_array()?;
+    Some(states.iter().filter_map(|s| s.as_str().map(String::from)).collect())
 }
 
 impl PaymentsProvider {
@@ -120,12 +316,24 @@ impl PaymentsProvider {
 
 pub fn payments_provider(domain_ir: &Value) -> Option<PaymentsProvider> {
     let fact = domain_ir.get("payments")?;
+    let aggregate = fact.get("aggregate")?.as_str()?.to_string();
+    let holds_seat = declared_holds_seat(fact).unwrap_or_else(|| {
+        static WARNED: std::sync::Once = std::sync::Once::new();
+        WARNED.call_once(|| eprintln!("payments capability declares no holds_seat; using built-in default"));
+        LEGACY_HOLDS_SEAT.iter().map(|s| s.to_string()).collect()
+    });
     Some(PaymentsProvider {
         provider: fact.get("provider")?.as_str()?.to_string(),
         initiate: fact.get("initiate")?.as_str()?.to_string(),
         succeeded: fact.get("succeeded")?.as_str()?.to_string(),
         failed: fact.get("failed")?.as_str()?.to_string(),
-        aggregate: fact.get("aggregate")?.as_str()?.to_string(),
+        aggregate,
+        holds_seat,
+        lapse_reason: fact.get("lapse_reason").and_then(|v| v.as_str()).filter(|v| !v.is_empty()).map(String::from).unwrap_or_else(|| {
+            static WARNED: std::sync::Once = std::sync::Once::new();
+            WARNED.call_once(|| eprintln!("payments capability declares no lapse_reason; using built-in default"));
+            LEGACY_LAPSE_REASON.to_string()
+        }),
     })
 }
 
@@ -143,6 +351,14 @@ pub struct RegistrationsProvider {
     pub event_aggregate: String,
     /// Qualified registration aggregate, e.g. `Studio::Registration`.
     pub registration_aggregate: String,
+    /// The registration attributes that may hold when it was asked for, in the order
+    /// to try them: the one `registered_at` of the `registrations` fact names
+    /// (ADR 0099), or [`LEGACY_REGISTERED_AT`] when the chapter declares none.
+    pub timestamp_keys: Vec<String>,
+    /// Registration states that give their seat back: the `frees_seat` list of the
+    /// `registrations` fact (the registration lifecycle's mark), or [`LEGACY_FREES_SEAT`]
+    /// when the chapter declares none.
+    pub frees_seat: Vec<String>,
 }
 
 impl RegistrationsProvider {
@@ -155,6 +371,8 @@ impl RegistrationsProvider {
             request: format!("{domain}::Registration.Request"),
             event_aggregate: format!("{domain}::Event"),
             registration_aggregate: format!("{domain}::Registration"),
+            timestamp_keys: LEGACY_REGISTERED_AT.iter().map(|k| k.to_string()).collect(),
+            frees_seat: LEGACY_FREES_SEAT.iter().map(|s| s.to_string()).collect(),
         }
     }
 
@@ -177,14 +395,35 @@ impl RegistrationsProvider {
     }
 }
 
+/// The states the `registrations` fact lists under `frees_seat`: the aggregate's lifecycle
+/// mark, resolved by the exporter. `None` when the fact omits it.
+fn declared_frees_seat(fact: &Value) -> Option<Vec<String>> {
+    let states = fact.get("frees_seat")?.as_array()?;
+    Some(states.iter().filter_map(|s| s.as_str().map(String::from)).collect())
+}
+
 pub fn registrations_provider(domain_ir: &Value) -> Option<RegistrationsProvider> {
     let fact = domain_ir.get("registrations")?;
+    let frees_seat = declared_frees_seat(fact).unwrap_or_else(|| {
+        static WARNED: std::sync::Once = std::sync::Once::new();
+        WARNED.call_once(|| eprintln!("registrations capability declares no frees_seat; using built-in default"));
+        LEGACY_FREES_SEAT.iter().map(|s| s.to_string()).collect()
+    });
     Some(RegistrationsProvider {
         provider: fact.get("provider")?.as_str()?.to_string(),
         schedule: fact.get("schedule")?.as_str()?.to_string(),
         request: fact.get("request")?.as_str()?.to_string(),
         event_aggregate: fact.get("event_aggregate")?.as_str()?.to_string(),
         registration_aggregate: fact.get("registration_aggregate")?.as_str()?.to_string(),
+        timestamp_keys: match fact.get("registered_at").and_then(|v| v.as_str()).filter(|v| !v.is_empty()) {
+            Some(declared) => vec![declared.to_string()],
+            None => {
+                static WARNED: std::sync::Once = std::sync::Once::new();
+                WARNED.call_once(|| eprintln!("registrations capability declares no registered_at; using built-in default"));
+                LEGACY_REGISTERED_AT.iter().map(|k| k.to_string()).collect()
+            }
+        },
+        frees_seat,
     })
 }
 
@@ -325,6 +564,84 @@ mod tests {
         assert!(newsletter_provider(&serde_json::json!({ "name": "Pizzas" })).is_none());
     }
 
+    fn newsletter_ir(marks: serde_json::Value) -> Value {
+        let mut fact = serde_json::json!({
+            "provider": "Newsletter",
+            "subscribe": "Newsletter::Subscriber.Subscribe",
+            "add_name": "Newsletter::Subscriber.AddName",
+            "confirm": "Newsletter::Subscriber.Confirm",
+            "unsubscribe": "Newsletter::Subscriber.Unsubscribe",
+            "aggregate": "Newsletter::Subscriber"
+        });
+        for (key, states) in marks.as_object().into_iter().flatten() {
+            fact[key] = states.clone();
+        }
+        serde_json::json!({ "name": "Studio", "newsletter": fact })
+    }
+
+    #[test]
+    fn newsletter_provider_reads_the_marks_from_the_fact() {
+        let ir = newsletter_ir(serde_json::json!({
+            "awaiting_confirmation": ["invited"],
+            "receives_issues": ["active", "vip"],
+            "left": ["gone"]
+        }));
+        let provider = newsletter_provider(&ir).expect("newsletter");
+        assert_eq!(provider.awaiting_confirmation, vec!["invited"]);
+        assert_eq!(provider.receives_issues, vec!["active", "vip"]);
+        assert_eq!(provider.left, vec!["gone"]);
+        assert!(provider.is_awaiting_confirmation(Some("invited")));
+        assert!(!provider.is_awaiting_confirmation(Some("pending")));
+        assert!(provider.receives_issues(Some("vip")));
+        assert!(!provider.receives_issues(Some("confirmed")));
+        assert!(provider.has_left(Some("gone")));
+        assert_eq!(provider.initial_status(), "invited");
+    }
+
+    #[test]
+    fn newsletter_provider_falls_back_to_the_legacy_defaults_without_marks() {
+        let provider = newsletter_provider(&newsletter_ir(serde_json::json!({}))).expect("newsletter");
+        assert_eq!(provider.awaiting_confirmation, LEGACY_AWAITING_CONFIRMATION);
+        assert_eq!(provider.receives_issues, LEGACY_RECEIVES_ISSUES);
+        assert_eq!(provider.left, LEGACY_LEFT);
+        assert!(provider.is_awaiting_confirmation(Some("pending")));
+        assert!(provider.receives_issues(Some("confirmed")));
+        assert!(provider.has_left(Some("unsubscribed")));
+        assert!(!provider.has_left(None));
+        assert_eq!(provider.initial_status(), "pending");
+    }
+
+    #[test]
+    fn newsletter_provider_reads_the_link_windows_from_the_fact() {
+        let ir = newsletter_ir(serde_json::json!({ "confirm_window": 3600, "unsubscribe_window": 7200 }));
+        let provider = newsletter_provider(&ir).expect("newsletter");
+        assert_eq!((provider.confirm_window, provider.unsubscribe_window), (3600, 7200));
+    }
+
+    #[test]
+    fn newsletter_provider_falls_back_to_the_legacy_windows_without_them() {
+        let provider = newsletter_provider(&newsletter_ir(serde_json::json!({}))).expect("newsletter");
+        assert_eq!(provider.confirm_window, LEGACY_CONFIRM_WINDOW_SECS);
+        assert_eq!(provider.unsubscribe_window, LEGACY_UNSUBSCRIBE_WINDOW_SECS);
+        assert_eq!((LEGACY_CONFIRM_WINDOW_SECS, LEGACY_UNSUBSCRIBE_WINDOW_SECS), (1_209_600, 63_072_000));
+    }
+
+    #[test]
+    fn checkout_windows_read_the_fact_and_fall_back_per_window() {
+        let declared = serde_json::json!({ "checkout": { "provider": "Checkout", "webhook_tolerance": 120, "session_hold": 2400 } });
+        assert_eq!(checkout_windows(&declared), CheckoutWindows { webhook_tolerance: 120, session_hold: 2400 });
+        let partial = serde_json::json!({ "checkout": { "provider": "Checkout", "session_hold": 2400 } });
+        assert_eq!(checkout_windows(&partial), CheckoutWindows { webhook_tolerance: LEGACY_WEBHOOK_TOLERANCE_SECS, session_hold: 2400 });
+        let none = checkout_windows(&serde_json::json!({ "name": "Pizzas" }));
+        assert_eq!(none, CheckoutWindows { webhook_tolerance: 300, session_hold: 1800 });
+    }
+
+    #[test]
+    fn a_zero_or_non_numeric_window_is_not_a_declaration() {
+        let ir = serde_json::json!({ "checkout": { "webhook_tolerance": 0, "session_hold": "soon" } });
+        assert_eq!(checkout_windows(&ir), CheckoutWindows { webhook_tolerance: 300, session_hold: 1800 });
+    }
+
     #[test]
     fn newsletter_issues_provider_reads_the_declared_capability() {
         let ir = serde_json::json!({
@@ -365,6 +682,39 @@ mod tests {
         assert!(payments_provider(&serde_json::json!({ "name": "Pizzas" })).is_none());
     }
 
+    fn payments_ir(holds_seat: Option<serde_json::Value>) -> Value {
+        let mut fact = serde_json::json!({
+            "provider": "Payments", "initiate": "Payments::Payment.Initiate",
+            "succeeded": "Payments::Payment.PaymentGateway.Succeeded",
+            "failed": "Payments::Payment.PaymentGateway.Failed", "aggregate": "Payments::Payment"
+        });
+        if let Some(states) = holds_seat {
+            fact["holds_seat"] = states;
+        }
+        serde_json::json!({"name": "Studio", "payments": fact})
+    }
+
+    #[test]
+    fn payments_provider_reads_holds_seat_from_the_fact() {
+        let ir = payments_ir(Some(serde_json::json!(["pending", "paid"])));
+        assert_eq!(declared_holds_seat(&ir["payments"]), Some(vec!["pending".to_string(), "paid".to_string()]));
+        assert_eq!(payments_provider(&ir).expect("payments").holds_seat, vec!["pending", "paid"]);
+    }
+
+    #[test]
+    fn the_checkout_fixture_ir_carries_holds_seat_with_no_fallback() {
+        let ir = fixture_ir();
+        assert_eq!(declared_holds_seat(&ir["payments"]), Some(vec!["pending".to_string(), "succeeded".to_string()]));
+        assert_eq!(fixture_payments().holds_seat, vec!["pending", "succeeded"]);
+    }
+
+    #[test]
+    fn payments_provider_falls_back_to_the_legacy_default_without_holds_seat() {
+        assert_eq!(declared_holds_seat(&payments_ir(None)["payments"]), None);
+        let held = payments_provider(&payments_ir(None)).expect("payments").holds_seat;
+        assert_eq!(held, LEGACY_HOLDS_SEAT);
+    }
+
     #[test]
     fn registrations_provider_reads_the_declared_capability() {
         let provider = registrations_provider(&fixture_ir()).expect("the checkout fixture provides registrations");
@@ -377,7 +727,63 @@ mod tests {
 
     #[test]
     fn the_conventional_registrations_names_match_what_the_fixture_declares() {
-        assert_eq!(registrations_provider(&fixture_ir()), Some(RegistrationsProvider::conventional("CheckoutFixture")));
+        let declared = registrations_provider(&fixture_ir()).expect("registrations");
+        let conventional = RegistrationsProvider {
+            timestamp_keys: declared.timestamp_keys.clone(),
+            frees_seat: declared.frees_seat.clone(),
+            ..RegistrationsProvider::conventional("CheckoutFixture") };
+        assert_eq!(declared, conventional);
+    }
+
+    #[test]
+    fn the_registration_timestamp_is_the_declared_attribute_or_the_legacy_guess() {
+        assert_eq!(registrations_provider(&fixture_ir()).expect("registrations").timestamp_keys, vec!["requested_at"]);
+        let undeclared = serde_json::json!({"registrations": {
+            "provider": "B", "schedule": "B::E.S", "request": "B::R.Q",
+            "event_aggregate": "B::E", "registration_aggregate": "B::R"
+        }});
+        assert_eq!(registrations_provider(&undeclared).expect("registrations").timestamp_keys, LEGACY_REGISTERED_AT);
+    }
+
+    fn registrations_ir(frees_seat: Option<serde_json::Value>) -> Value {
+        let mut fact = serde_json::json!({
+            "provider": "B", "schedule": "B::E.S", "request": "B::R.Q",
+            "event_aggregate": "B::E", "registration_aggregate": "B::R"
+        });
+        if let Some(states) = frees_seat {
+            fact["frees_seat"] = states;
+        }
+        serde_json::json!({"registrations": fact})
+    }
+
+    #[test]
+    fn registrations_provider_reads_frees_seat_from_the_fact() {
+        let ir = registrations_ir(Some(serde_json::json!(["cancelled", "archived"])));
+        assert_eq!(declared_frees_seat(&ir["registrations"]), Some(vec!["cancelled".to_string(), "archived".to_string()]));
+        assert_eq!(registrations_provider(&ir).expect("registrations").frees_seat, vec!["cancelled", "archived"]);
+    }
+
+    #[test]
+    fn the_checkout_fixture_ir_carries_frees_seat_with_no_fallback() {
+        let ir = fixture_ir();
+        assert_eq!(declared_frees_seat(&ir["registrations"]), Some(vec!["archived".to_string(), "cancelled".to_string()]));
+        assert_eq!(registrations_provider(&ir).expect("registrations").frees_seat, vec!["archived", "cancelled"]);
+    }
+
+    #[test]
+    fn registrations_provider_falls_back_to_the_legacy_default_without_frees_seat() {
+        assert_eq!(declared_frees_seat(&registrations_ir(None)["registrations"]), None);
+        let freed = registrations_provider(&registrations_ir(None)).expect("registrations").frees_seat;
+        assert_eq!(freed, LEGACY_FREES_SEAT);
+    }
+
+    #[test]
+    fn the_lapse_reason_is_the_declared_word_or_the_legacy_default() {
+        assert_eq!(fixture_payments().lapse_reason, "checkout_expired");
+        let mut ir = payments_ir(None);
+        assert_eq!(payments_provider(&ir).expect("payments").lapse_reason, LEGACY_LAPSE_REASON);
+        ir["payments"]["lapse_reason"] = serde_json::json!("hold_lapsed");
+        assert_eq!(payments_provider(&ir).expect("payments").lapse_reason, "hold_lapsed");
     }
 
     #[test]