hecks 2.8.0 → 3.0.0

data/rust/src/exemplar/reactions.rs

@@ -0,0 +1,88 @@
+// Exemplar shapes that rust/project/reactions.rb slices into generated tables;
+// see mod.rs for how they are used.
+#![allow(dead_code, unused_variables)]
+
+// Carries a `tmpl_` token so Exemplar::LEFTOVER_PLACEHOLDER catches it if a
+// caller forgets to substitute it.
+fn tmpl_body_placeholder() -> crate::kernel::Json {
+    crate::kernel::Json::Null
+}
+
+fn tmpl_with_value_literal_fn_host() {
+    // TMPL:with_value_literal_fn BEGIN
+    fn tmpl_literal_fn() -> crate::kernel::Json { tmpl_body_placeholder() }
+    // TMPL:with_value_literal_fn END
+}
+
+// Literal rows, not a call: `const` context cannot call a non-`const` function.
+// TMPL:policy_table BEGIN
+pub const POLICIES: &[crate::kernel::PolicyRule] = &[
+crate::kernel::PolicyRule { policy_name: "tmpl_policy_name", event_name: "tmpl_event_name", event_qualifier: None, target_verb: "tmpl_target_verb", for_each: None, for_each_key: None, with_spec: &[], where_expr: None },
+];
+// TMPL:policy_table END
+
+// Separate table: nothing here can dispatch a match; rust/host delivers it.
+// Literal rows for the same `const` reason as `policy_table`.
+// TMPL:cross_domain_policy_table BEGIN
+pub const CROSS_DOMAIN_POLICIES: &[crate::kernel::CrossDomainPolicyRule] = &[
+crate::kernel::CrossDomainPolicyRule { policy_name: "tmpl_policy_name", event_name: "tmpl_event_name", event_qualifier: None, target_domain: "tmpl_target_domain", target_verb: "tmpl_target_verb", where_expr: None },
+];
+// TMPL:cross_domain_policy_table END
+
+// Module scope allows only items, so `literal_fns` is zero or more `fn` items, never a call.
+// TMPL:process_manager_table BEGIN
+fn tmpl_literal_fns_placeholder() {}
+
+pub const PROCESS_MANAGERS: &[crate::kernel::ProcessManagerDef] = &[
+    crate::kernel::ProcessManagerDef { name: "tmpl_pm_name", correlates_by: "tmpl_correlates_by", starts_on: "tmpl_starts_on", ends_on: "tmpl_ends_on", initial_state: "tmpl_initial_state", handlers: &[] },
+];
+// TMPL:process_manager_table END
+
+// TMPL:reference_key_table BEGIN
+pub fn reference_key_for_aggregate(qualified_name: &str) -> Option<&'static str> {
+    match qualified_name {
+"tmpl_qualified" => Some("tmpl_key"),
+        _ => None,
+    }
+}
+// TMPL:reference_key_table END
+
+// Read by orchestrate.rs `split_routed_args`.
+// TMPL:creates_table BEGIN
+pub fn command_creates(verb: &str) -> bool {
+    match verb {
+"tmpl_verb" => true,
+        _ => false,
+    }
+}
+// TMPL:creates_table END
+
+// Read by orchestrate.rs `split_routed_args`.
+// TMPL:identity_head_table BEGIN
+pub fn identity_head_for_aggregate(qualified_name: &str) -> Option<&'static str> {
+    match qualified_name {
+"tmpl_qualified" => Some("tmpl_head"),
+        _ => None,
+    }
+}
+// TMPL:identity_head_table END
+
+// Keyed by "Domain::Aggregate.Entity"; entities nested two levels deep never resolve here.
+// TMPL:entity_identity_head_table BEGIN
+pub fn entity_identity_head_for_path(qualified_path: &str) -> Option<&'static str> {
+    match qualified_path {
+"tmpl_qualified" => Some("tmpl_head"),
+        _ => None,
+    }
+}
+// TMPL:entity_identity_head_table END
+
+// Read by orchestrate.rs `split_routed_args`.
+// TMPL:command_attributes_table BEGIN
+pub fn command_attributes_for_verb(verb: &str) -> &'static [&'static str] {
+    match verb {
+"tmpl_verb" => &["tmpl_attr"],
+        _ => &[],
+    }
+}
+// TMPL:command_attributes_table END

data/rust/src/exemplar/read_models.rs

@@ -0,0 +1,48 @@
+// Exemplar shapes for rust/project/read_models.rb's `emit_read_model_table`
+// — see mod.rs's own header. `ReadModelDef`/`ReadModelHead`/`FilteredHead`/
+// `ReferenceField` are real kernel types (`rust/src/kernel/read_model.rs`).
+#![allow(dead_code, unused_variables)]
+
+// `const` context can't call a non-`const` function — the same reason
+// `queries.rs`'s own `QUERIES` table bakes a real struct literal here
+// rather than a placeholder function call: `ReadModelDef { ... }` is
+// exactly as const-evaluable as `QueryDef { ... }` already is, so the
+// placeholder row is a real literal, substituted wholesale.
+//
+// `filtered_heads` holds one `FilteredHead` per many-side head this read
+// model declares where/order_by/offset/limit for (ADR 0055's `on:`) — a
+// single entry, as here, whenever there's exactly one many-side head.
+// TMPL:read_model_table BEGIN
+pub const READ_MODELS: &[crate::kernel::read_model::ReadModelDef] = &[
+crate::kernel::read_model::ReadModelDef {
+    verb: "tmpl_verb",
+    reference_name: Some("tmpl_reference_name"),
+    heads: &[
+        crate::kernel::read_model::ReadModelHead {
+            aggregate: "tmpl_aggregate",
+            as_name: "tmpl_as_name",
+            many: true,
+            is_root: false,
+            reference_fields: &[
+                crate::kernel::read_model::ReferenceField { target_aggregate: "tmpl_target_aggregate", field: "tmpl_field" },
+            ],
+        },
+    ],
+    filtered_heads: &[
+        crate::kernel::read_model::FilteredHead { as_name: "tmpl_as_name", conditions: &[crate::kernel::QueryCondition { field: "tmpl_field", comparator: crate::kernel::query_comparators::QueryComparator::Eq, value: crate::kernel::QueryConditionValue::Literal("tmpl_literal") },], reference_hop_conditions: &[crate::kernel::read_model::ReferenceHopCondition { via_field: "tmpl_via_field", target_aggregate: "tmpl_target_aggregate", through: &[crate::kernel::read_model::HopStep { via_field: "tmpl_via_field", target_aggregate: "tmpl_target_aggregate" }], inner_field: "tmpl_inner_field", inner_comparator: crate::kernel::query_comparators::QueryComparator::Eq, inner_value: crate::kernel::QueryConditionValue::Literal("tmpl_literal") },], order_by: Some(crate::kernel::read_model::ReadModelOrderBy { field: "tmpl_order_field", descending: true, nulls: crate::kernel::query_ordering::NullsMode::Last }), offset: Some(crate::kernel::read_model::ReadModelOffset::Literal(1)), limit: Some(crate::kernel::read_model::ReadModelLimit::Literal(5)) },
+    ],
+    authorization: Some(crate::kernel::named_query::TenantAuth { query_name: "tmpl_query_name", tenant_field: "tmpl_tenant_field", policy: "tmpl_policy" }),
+    group_by: None,
+    count: false,
+    median_field: None,
+    sum_field: None,
+    avg_field: None,
+    min_field: None,
+    max_field: None,
+    percentile_field: None,
+    percentile_at: None,
+    any_field: None,
+    all_field: None,
+},
+];
+// TMPL:read_model_table END

data/rust/src/exemplar/registry.rs

@@ -0,0 +1,166 @@
+// Exemplar shapes for rust/project/registry.rb; see mod.rs.
+// `InMemoryRepository<T>` only needs `T: Clone`, so an `i64` record type suffices.
+#![allow(dead_code, unused_variables)]
+
+// `QUERIES` and `AUTHORIZATION_ASSIGNMENTS` are defined beside `dispatch_by_name` in every
+// generated registry; `check_role_via` needs them. Empty here: only the call shape is proven.
+static QUERIES: &[crate::kernel::QueryDef] = &[];
+static AUTHORIZATION_ASSIGNMENTS: Option<&str> = None;
+
+fn tmpl_role_check_host(store: &TmplStore2, caller_role: Option<&str>, caller_actor_id: Option<&str>) -> Result<(), crate::kernel::Refusal> {
+    // TMPL:role_check BEGIN
+    crate::kernel::check_role_via(Some("TmplRole"), "TmplCommandName", caller_role, caller_actor_id, &*store, QUERIES, AUTHORIZATION_ASSIGNMENTS)?;
+    // TMPL:role_check END
+    Ok(())
+}
+
+struct TmplStore {
+    tmpl_target_mod: crate::kernel::InMemoryRepository<i64>,
+}
+
+struct TmplRefItem {
+    tmpl_element_field: String,
+}
+
+struct TmplRefArgs {
+    tmpl_field: String,
+    tmpl_optional_field: Option<String>,
+    tmpl_list_field: Vec<TmplRefItem>,
+}
+
+fn tmpl_reference_check_required_host(store: &TmplStore, args: &TmplRefArgs) -> Result<(), crate::kernel::Refusal> {
+    // TMPL:reference_check_required BEGIN
+    crate::kernel::check_reference(&store.tmpl_target_mod, &args.tmpl_field, "TmplTarget", "tmpl_heads")?;
+    // TMPL:reference_check_required END
+    Ok(())
+}
+
+fn tmpl_reference_check_optional_host(store: &TmplStore, args: &TmplRefArgs) -> Result<(), crate::kernel::Refusal> {
+    // TMPL:reference_check_optional BEGIN
+    if let Some(v) = &args.tmpl_optional_field { crate::kernel::check_reference(&store.tmpl_target_mod, v, "TmplTarget", "tmpl_heads")?; }
+    // TMPL:reference_check_optional END
+    Ok(())
+}
+
+// One `check_reference` per element of a list argument that `sets` a `has_many` field.
+fn tmpl_reference_check_list_host(store: &TmplStore, args: &TmplRefArgs) -> Result<(), crate::kernel::Refusal> {
+    // TMPL:reference_check_list BEGIN
+    for item in &args.tmpl_list_field { crate::kernel::check_reference(&store.tmpl_target_mod, &item.tmpl_element_field, "TmplTarget", "tmpl_heads")?; }
+    // TMPL:reference_check_list END
+    Ok(())
+}
+
+// `registry_file` — the whole per-domain registry.rs. The variable-arity blocks stay opaque
+// Ruby-built markers; this shape proves the fixed skeleton around them.
+fn tmpl_store_fields_placeholder() -> crate::kernel::InMemoryRepository<i64> {
+    crate::kernel::InMemoryRepository::new()
+}
+fn tmpl_dump_arm_placeholder() {}
+fn tmpl_seed_arm_placeholder() {}
+fn tmpl_query_arm_placeholder() {}
+fn tmpl_scan_each_arm_placeholder() {}
+fn tmpl_dispatch_arm_placeholder() -> Result<Vec<crate::kernel::Event>, crate::kernel::Refusal> {
+    Ok(Vec::new())
+}
+
+// Two `unused_mut` warnings come from this exemplar only: `mut` is needed once real loop
+// bodies replace the placeholders, and an allow would have to sit inside the fence.
+// The generated file header lives outside the fence (a `#![...]` is legal only first in a file).
+// TMPL:registry_file BEGIN
+// `Clone` — a dry run (`cli::run`'s `{"dry_run": …}` step, `cli::serve`'s
+// `snapshot`/`restore`) dispatches against a throwaway copy of the whole
+// store: givens, mutations, ensures all run for real, nothing is kept.
+#[derive(Clone)]
+pub struct TmplStore2 {
+    pub tmpl_field: crate::kernel::InMemoryRepository<i64>,
+}
+
+impl TmplStore2 {
+    pub fn new() -> Self {
+        Self {
+            tmpl_field: tmpl_store_fields_placeholder(),
+        }
+    }
+
+    /// Every aggregate this domain declared, dumped as
+    /// "Domain::Aggregate#id" -> its own to_json() — the exact key
+    /// shape hecks check_conformance's own comparable["instances"]
+    /// builds from Ruby (Fuzzing::Replay.call's own instance key
+    /// format, read directly).
+    pub fn instances(&self) -> Vec<(String, crate::kernel::Json)> {
+        let mut instances = Vec::new();
+tmpl_dump_arm_placeholder();
+        instances
+    }
+
+    /// Seeds a fresh `Store` from a prior `instances()` dump —
+    /// the exact "Domain::Aggregate#id" -> state shape, read
+    /// back instead of written. Not `Result`-returning on a
+    /// non-Object `seed`: an absent/malformed seed just yields
+    /// an empty Store, the same starting point `Store::new()`
+    /// already gives a caller with no prior state to seed from.
+    pub fn from_seed(seed: &crate::kernel::Json) -> Result<Self, crate::kernel::Refusal> {
+        let mut store = Self::new();
+        if let crate::kernel::Json::Object(fields) = seed {
+            for (key, value) in fields {
+tmpl_seed_arm_placeholder();
+            }
+        }
+        Ok(store)
+    }
+}
+
+/// `AggregateScan` — kernel/repository.rs's own trait, given a real
+/// per-aggregate body here: one `if` per aggregate this domain declared,
+/// the same "Domain::Aggregate" prefix `instances()`'s own dump arms
+/// already use, each returning that one aggregate's own (id, to_json())
+/// listing straight off its repository's `entries()`. Falls through to
+/// the trait's own default (`None`) for any prefix that matches none of
+/// them — kernel/cli.rs turns that into a clean "unknown aggregate"
+/// refusal, never a panic. `scan_each` is the same listing borrowed, so a declared query clones
+/// only the rows it keeps; both read the repositories' cached `to_json()` renderings.
+impl crate::kernel::AggregateScan for TmplStore2 {
+    fn scan(&self, aggregate: &str) -> Option<Vec<(String, crate::kernel::Json)>> {
+tmpl_query_arm_placeholder();
+        None
+    }
+
+    fn scan_each(&self, aggregate: &str, visit: &mut dyn FnMut(&str, &crate::kernel::Json)) -> bool {
+tmpl_scan_each_arm_placeholder();
+        false
+    }
+}
+
+pub fn dispatch_by_name(
+    store: &mut TmplStore2,
+    verb: &str,
+    args_json: &crate::kernel::Json,
+    caller_role: Option<&str>,
+    caller_actor_id: Option<&str>,
+    mutations: &mut Vec<crate::kernel::MutationRecord>,
+) -> Result<Vec<crate::kernel::Event>, crate::kernel::Refusal> {
+    match verb {
+"tmpl_verb" => { tmpl_dispatch_arm_placeholder() }
+        other => Err(crate::kernel::Refusal::TypeMismatch(format!("unknown command {other:?}"))),
+    }
+}
+
+/// Ruby's own event payload is `payload: args` — the whole hash the
+/// caller passed to `dispatch`, not filtered to the command's own
+/// declared attributes (an identity-reference argument like
+/// `number:` is not a declared `CreditArgs` field, and still shows
+/// up on `AccountCredited`'s payload). `args.to_json()` inside each
+/// generated `dispatch_*` only ever sees the narrowed, typed args
+/// struct, so it structurally can't reproduce that — this replaces
+/// whatever payload the generated dispatch built with the raw,
+/// unfiltered `args_json` this router itself received, after the
+/// fact, once dispatch has already decided whether to accept it.
+/// Load-bearing for process managers, not just payload fidelity: a
+/// saga leg that forwards `reference: :reference` into `Account.
+/// Debit` (which doesn't declare a `reference` attribute) needs
+/// that field to survive onto `AccountDebited`'s own payload for
+/// `correlates_by` to find it downstream.
+fn stamp_payload(events: Vec<crate::kernel::Event>, args_json: &crate::kernel::Json) -> Vec<crate::kernel::Event> {
+    events.into_iter().map(|e| crate::kernel::Event { payload: args_json.clone(), ..e }).collect()
+}
+// TMPL:registry_file END

data/rust/src/exemplar/types.rs

@@ -0,0 +1,44 @@
+// Exemplar shapes for rust/project/types.rb; see mod.rs.
+// `closed_set_enum` is a one-field closed set (one variant per member); a multi-field closed
+// set is a fixed data table instead.
+#![allow(dead_code, unused_variables)]
+
+// TMPL:closed_set_enum BEGIN
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum TmplKind {
+    // TMPL:closed_set_enum:VARIANT BEGIN
+    TmplMemberA,
+    // TMPL:closed_set_enum:VARIANT END
+}
+// TMPL:closed_set_enum END
+
+// `plain_struct` backs value objects, entities and aggregate records alike; field types
+// arrive already resolved as `TmplFieldType`.
+type TmplFieldType = i64;
+
+// TMPL:plain_struct BEGIN
+#[derive(Debug, Clone, PartialEq)]
+pub struct TmplType {
+    // TMPL:struct_field BEGIN
+    pub tmpl_field: TmplFieldType,
+    // TMPL:struct_field END
+}
+// TMPL:plain_struct END
+
+// `closed_set_table` — a closed set over more than one field: a `plain_struct` glued in Ruby
+// to the `pub const` array, kept as two independently valid pieces.
+struct TmplRow {
+    tmpl_field: i64,
+}
+
+fn tmpl_value_placeholder() -> i64 {
+    0
+}
+
+fn tmpl_row_field_host() -> TmplRow {
+    TmplRow {
+        // TMPL:closed_set_table_row_field BEGIN
+        tmpl_field: tmpl_value_placeholder()
+        // TMPL:closed_set_table_row_field END
+    }
+}

data/rust/src/kernel/attribute_shapes/composite.rs

@@ -0,0 +1,88 @@
+// The `:composite` shape of `Runtime::Value::Coercion::SHAPES`: per-segment dotted-path walking.
+
+use crate::kernel::expr::{eval_error, Field, Value};
+use crate::kernel::Refusal;
+
+/// A scalar (or `Nil`) with segments left resolves to `Nil`, like Ruby's `walk_path`.
+/// This makes `flag.nil?` read as a value instead of a refusal.
+pub fn step<'a>(current: Field<'a>, seg: &str, head: &str) -> Result<Field<'a>, Refusal> {
+    match current {
+        Field::Nested(obj) => obj.field(seg).ok_or_else(|| eval_error(format!("cannot resolve {seg:?} on {head:?}"))),
+        Field::Value(_) => Ok(Field::Value(Value::Nil)),
+    }
+}
+
+/// A path may end on a nested object only if it collapses via `Fielded::as_scalar`.
+pub fn finish(current: Field<'_>, path: &str) -> Result<Value, Refusal> {
+    match current {
+        Field::Value(v) => Ok(v),
+        Field::Nested(obj) => obj.as_scalar().ok_or_else(|| eval_error(format!("{path} resolved to an object, not a scalar"))),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::kernel::expr::Fielded;
+
+    // Hand-built stand-in for a generated composite's `Fielded` impl.
+    struct Customer {
+        status: String,
+    }
+    impl Fielded for Customer {
+        fn field(&self, name: &str) -> Option<Field<'_>> {
+            match name {
+                "status" => Some(Field::Value(Value::Str(self.status.clone()))),
+                _ => None,
+            }
+        }
+    }
+
+    // `Field` derives neither `Debug` nor `PartialEq`; assertions compare the `finish`ed `Value`.
+    fn stepped_value(current: Field<'_>, seg: &str, head: &str) -> Value {
+        finish(step(current, seg, head).unwrap(), "test.path").unwrap()
+    }
+
+    #[test]
+    fn a_further_segment_on_a_bool_scalar_resolves_to_nil_not_a_refusal() {
+        // `.nil?` has no dedicated node, so it arrives as a trailing segment on a resolved scalar.
+        assert_eq!(stepped_value(Field::Value(Value::Bool(true)), "nil?", "previous_sessions"), Value::Nil);
+    }
+
+    #[test]
+    fn this_holds_for_a_false_scalar_too() {
+        assert_eq!(stepped_value(Field::Value(Value::Bool(false)), "nil?", "previous_sessions"), Value::Nil);
+    }
+
+    #[test]
+    fn this_holds_for_every_scalar_shape_not_just_bool() {
+        for value in [Value::Int(0), Value::Float(1.5), Value::Str("x".to_string()), Value::List(3)] {
+            assert_eq!(stepped_value(Field::Value(value.clone()), "nil?", "head"), Value::Nil, "expected Nil for {value:?}");
+        }
+    }
+
+    #[test]
+    fn a_further_segment_on_an_already_nil_value_stays_nil() {
+        // An unset optional field already reads as `Nil` before `step` runs.
+        assert_eq!(stepped_value(Field::Value(Value::Nil), "nil?", "superseded_by"), Value::Nil);
+    }
+
+    #[test]
+    fn a_real_nested_field_still_walks_normally() {
+        let customer = Customer { status: "active".to_string() };
+        assert_eq!(stepped_value(Field::Nested(&customer), "status", "customer"), Value::Str("active".to_string()));
+    }
+
+    #[test]
+    fn an_unknown_nested_field_still_refuses() {
+        // A generated `field()` is exhaustive, so an unknown name is a codegen bug: keep refusing.
+        let customer = Customer { status: "active".to_string() };
+        let stepped = step(Field::Nested(&customer), "not_a_real_field", "customer");
+        assert!(stepped.is_err());
+    }
+
+    #[test]
+    fn finish_unwraps_a_resolved_nil_to_a_plain_value() {
+        assert_eq!(finish(Field::Value(Value::Nil), "previous_sessions.nil?").unwrap(), Value::Nil);
+    }
+}

data/rust/src/kernel/attribute_shapes/list.rs

@@ -0,0 +1,18 @@
+// The `:list` shape of `Runtime::Value::Coercion::SHAPES`.
+// Expressions see a list as its length only (`Value::List(usize)`): just `size` and `empty?`.
+
+use crate::kernel::expr::Value;
+
+pub fn is_empty(v: &Value) -> Option<bool> {
+    match v {
+        Value::List(n) => Some(*n == 0),
+        _ => None,
+    }
+}
+
+pub fn size(v: &Value) -> Option<i64> {
+    match v {
+        Value::List(n) => Some(*n as i64),
+        _ => None,
+    }
+}

data/rust/src/kernel/attribute_shapes/mod.rs

@@ -0,0 +1,44 @@
+// GENERATED by hecks project_kernel_capabilities from Coercion::SHAPES.
+// Do not hand-edit — re-run hecks project_kernel_capabilities instead.
+//
+// Ground truth: Hecks::Runtime::Value::Coercion::SHAPES
+// (lib/hecks/runtime/value/coercion.rb) — the four branches
+// `for_attribute` itself takes, read directly rather than
+// re-derived here.
+
+pub mod scalar;
+pub mod list;
+pub mod optional;
+pub mod composite;
+
+/// One variant per real attribute shape the Ruby
+/// grammar admits, in the order Coercion::SHAPES declares them. Every match
+/// over this enum in the kernel (rust/src/kernel/expr.rs) is written
+/// WITHOUT a wildcard `_ =>` arm — see expr.rs's own header for why:
+/// a wildcard here would let a newly-admitted capability compile
+/// silently into a router that never calls the new file this same
+/// regeneration adds a `pub mod` line for above.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum AttributeShape {
+    Scalar,
+    List,
+    Optional,
+    Composite,
+}
+
+impl AttributeShape {
+    /// The `rust/src/kernel/attribute_shapes/<name>.rs` file this
+    /// variant names — `hecks measure_kernel_coverage`'s own existence
+    /// check reads this, so the file-name spelling here is the ONE
+    /// place that ever needs to change if a name is renamed.
+    pub fn module_name(&self) -> &'static str {
+        match self {
+            AttributeShape::Scalar => "scalar",
+            AttributeShape::List => "list",
+            AttributeShape::Optional => "optional",
+            AttributeShape::Composite => "composite",
+        }
+    }
+
+    pub const ALL: &'static [AttributeShape] = &[AttributeShape::Scalar, AttributeShape::List, AttributeShape::Optional, AttributeShape::Composite];
+}

data/rust/src/kernel/attribute_shapes/optional.rs

@@ -0,0 +1,9 @@
+// The `:optional` shape of `Runtime::Value::Coercion::SHAPES`.
+// `Value::Nil` covers both an unset `optional:` field and a literal `nil`, as in Ruby.
+
+use crate::kernel::expr::Value;
+
+// `nil.to_s == ""`; `None` for anything but `Value::Nil`.
+pub fn to_s(v: &Value) -> Option<Value> {
+    matches!(v, Value::Nil).then(|| Value::Str(String::new()))
+}

data/rust/src/kernel/attribute_shapes/scalar.rs

@@ -0,0 +1,39 @@
+// The `:scalar` shape of `Runtime::Value::Coercion::SHAPES`: `Value::{Str,Int,Float,Bool}`.
+// `List` and `Nil` belong to the other shapes, so every function here returns `None` for them.
+
+use crate::kernel::expr::Value;
+
+// Mirrors `Resolver.numeric`: `Int` and `Float` mix freely; any other `Value` is not a number.
+pub fn numeric(v: &Value) -> Option<f64> {
+    match v {
+        Value::Int(i) => Some(*i as f64),
+        Value::Float(f) => Some(*f),
+        _ => None,
+    }
+}
+
+// `.to_s` on a scalar; `None` for `List`/`Nil`.
+pub fn to_s(v: &Value) -> Option<Value> {
+    match v {
+        Value::Str(s) => Some(Value::Str(s.clone())),
+        Value::Int(i) => Some(Value::Str(i.to_string())),
+        Value::Float(f) => Some(Value::Str(f.to_string())),
+        Value::Bool(b) => Some(Value::Str(b.to_string())),
+        Value::List(_) | Value::Nil | Value::Array(_) => None,
+    }
+}
+
+// Only `Str` has a length; `Int`/`Float`/`Bool` answer `None` so the caller refuses.
+pub fn is_empty(v: &Value) -> Option<bool> {
+    match v {
+        Value::Str(s) => Some(s.is_empty()),
+        _ => None,
+    }
+}
+
+pub fn size(v: &Value) -> Option<i64> {
+    match v {
+        Value::Str(s) => Some(s.chars().count() as i64),
+        _ => None,
+    }
+}