bynk_check/

unit_signature.rs

//! P8.1 (#1512): `UnitId` and `UnitSignature` — the load-bearing types this
//! whole phase's firewall (R3.14) is stated in terms of. `UnitSignature`
//! projects a [`UnitTable`] into design notes §15's four required-annotation
//! categories — cross-context types, fn signatures (free functions and
//! methods), handler signatures plus storage, capability sets — with every
//! body/body-adjacent field excluded ([DECISION B],
//! `design/tracks/incrementality.md` §3.4/Q4) rather than merely ignored by
//! the comparison: `body`/`requires`/`ensures` never reach [`FnSignature`],
//! `body` never reaches [`HandlerSignature`], `init`/`annotations` never
//! reach [`StoreFieldSignature`] — the type system, not a comparison
//! function's own discipline, makes "no body reachable from `UnitSignature`"
//! a fact.
//!
//! Stability is proved by comparing [`UnitSignature::canonical`], not the raw
//! struct: every included fragment still carries its own `Span` (`Ident`,
//! `Param`, every `TypeRef` variant, `TypeDecl`'s own `trivia`/
//! `documentation`), and editing a body shifts every later declaration's own
//! spans in the same file (the byte-offset cascade PR #1509's bot review
//! caught one level up, in `UnitSignature`'s own design). [DECISION C]
//! extends `contract.rs`'s `canon_type`/`service_normal_form` (ADR 0200) —
//! already a span-free canonical rendering, proven correct by
//! `contract_hash.rs`'s own no-false-positive fixture — to reach the new
//! signature shapes here, rather than inventing a second erasure scheme.
//!
//! **The R3.14 firewall has two directions, and this module is responsible
//! for both**: a body edit must not move [`UnitSignature::canonical`] (the
//! exclusions above), and a genuine signature edit MUST move it — a false
//! "unchanged" verdict silently skips recomputing every downstream
//! consumer, the more expensive failure mode for an incrementality firewall.
//! PR #1517's own bot review caught three real gaps on the second direction
//! before this module first merged: [`HandlerKind`] was dropped entirely
//! (so renaming an HTTP route or changing `on GET` to `on POST` didn't move
//! the form), methods never reached [`UnitSignature`] at all (`UnitTable.fns`
//! only holds free functions — `FnName::Method` is filed under
//! `UnitTable.methods` instead, `symbols.rs:596-619`), and a `capability`
//! declaration's own operation signatures (`CapabilityDecl.ops`, itself
//! already body-free — "signature only; no body", `ast.rs:564`) were never
//! projected, so retyping a capability op left every consumer's own
//! `UnitSignature` unchanged even though its compiled contract with that
//! capability's provider did change. All three are fixed here; see each
//! type's own doc comment for what closed the gap.
//!
//! **Deliberately still excluded, named explicitly so a future reviewer
//! doesn't have to re-derive it:** `ProviderDecl.provider_name` (an internal
//! selector used only in tests/config to pick an implementation — never part
//! of a `Cap.op(...)` call site, so it carries no information a consumer's
//! own compile depends on) and handler-position annotations (`@cache`, …,
//! `Handler.annotations: Vec<Annotation>`) — an `AnnotationArg.value` is an
//! arbitrary `Expr`, and canonicalising `Expr` the way `canon_type` already
//! does for `TypeRef` is real, unscoped work this slice does not take on;
//! flagged for whichever future slice needs it, the same "flag for the slice
//! that will actually pin it" discipline this phase has applied throughout.
//! `ServiceProtocol::Events`'s own `pattern`/`schema_dispatch` fields (the
//! structural payload filter and `via schema(N)` clause) are captured only
//! as "present or absent", not rendered field-by-field, for the same
//! Expr/pattern-canonicalisation reason — narrower than ideal, but strictly
//! better than the pre-fix state where the whole protocol was invisible.
//!
//! [`unit_signature_for`]'s only caller is `tests/unit_signature_stability.rs`
//! (P8.2), and that is deliberate: this module is R3.14's own *proof* — the
//! firewall stated as a type and checked by a test — not a production path.
//! Phase 8's two structural consumers-to-be (`ProjectGraph`, P8.3, and the
//! `DefId`-keyed `Body`/`TypeOf` queries, P8.5) were built beside it and
//! deleted on 2 September 2026 (#1537, ADR in that PR's pending file): nothing
//! called them and no scheduler existed to. This module stays because
//! R3.15's trigger (#1523 — keystroke-to-diagnostic latency *attributed by
//! level*) presupposes a unit level to attribute to; the gated
//! `incremental_query_types` probe certifies it is present and its
//! stability test exists.

use std::collections::{BTreeMap, BTreeSet, HashMap};
use std::sync::Arc;

use bynk_syntax::ast::{CapRef, Handler, HandlerKind, Param, ServiceProtocol, TypeDecl, TypeRef};

use crate::symbols::UnitTable;

/// [DECISION A]: a stable, hashable identity for a unit, reusing the
/// unit-name `String` every `UnitTable`/`combined_types_for` caller already
/// keys on today, rather than introducing a fresh interned-integer scheme —
/// no `index_vec` crate (or hand-rolled equivalent) exists anywhere in this
/// codebase, confirmed by grep. `UnitSignature` only needs `UnitId` to be a
/// stable, hashable, comparable identity for R3.14's own proof; it does not
/// need to be dense or `IndexVec`-compatible. P8.3 resolved the fork this
/// left open by adapting `ProjectGraph` to the string-keyed `UnitId` (ADR
/// 0415); that graph was deleted by #1537, so if R3.15's trigger ever fires,
/// ADR 0415's recorded shape is what a rebuild adapts to — this type stays
/// a string newtype either way.
#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub struct UnitId(pub String);

/// [DECISION B]: [`Param`], body-free (it already is — kept as its own type
/// only so [`FnSignature`]/[`HandlerSignature`] don't reach back into
/// `bynk-syntax::ast::Param` and risk a future field being added there and
/// silently flowing through unexamined).
#[derive(Debug, Clone)]
pub struct ParamSignature {
    pub name: String,
    pub type_ref: TypeRef,
}

fn param_signatures(params: &[Param]) -> Vec<ParamSignature> {
    params
        .iter()
        .map(|p| ParamSignature {
            name: p.name.name.clone(),
            type_ref: p.type_ref.clone(),
        })
        .collect()
}

/// [DECISION B]: [`bynk_syntax::ast::FnDecl`], body-free. Excludes `body`,
/// `requires`, `ensures` (all body-adjacent — `requires`/`ensures` scope over
/// parameters and the result but are not part of design notes §15's own
/// required-annotation list, per Q4) and `documentation`. Used for both free
/// functions ([`UnitSignature::fns`]) and methods ([`UnitSignature::methods`]).
#[derive(Debug, Clone)]
pub struct FnSignature {
    pub type_params: Vec<String>,
    pub name: String,
    pub params: Vec<ParamSignature>,
    pub return_type: TypeRef,
    pub has_self: bool,
}

fn fn_signature(name: &str, decl: &bynk_syntax::ast::FnDecl) -> FnSignature {
    FnSignature {
        type_params: decl
            .type_params
            .iter()
            .map(|tp| tp.name.name.clone())
            .collect(),
        name: name.to_string(),
        params: param_signatures(&decl.params),
        return_type: decl.return_type.clone(),
        has_self: decl.has_self,
    }
}

/// The `instance`/`statics` split PR #1517's bot review found missing
/// entirely: `UnitTable.fns` (what [`UnitSignature::fns`] projects) only
/// ever holds `FnName::Free` entries — `FnName::Method` is filed under
/// `UnitTable.methods: HashMap<String, MethodTable>` instead
/// (`symbols.rs:596-619`), keyed by the attached type's name, with instance
/// and static methods in their own sub-maps (mirroring
/// [`crate::resolver::MethodTable`]'s own shape exactly, rather than
/// flattening into one map keyed by method name alone — an instance and a
/// static method can share a name for the same type without colliding in
/// `MethodTable` itself, so flattening here would silently drop one).
#[derive(Debug, Clone, Default)]
pub struct MethodTableSignature {
    pub instance: BTreeMap<String, FnSignature>,
    pub statics: BTreeMap<String, FnSignature>,
}

/// A closed, body-free mirror of [`HandlerKind`] — every field `HandlerKind`
/// itself carries (`HttpMethod`, a route/cron-expression `String`) is already
/// a plain value with nothing body-adjacent to exclude. PR #1517's own bot
/// review: dropping this entirely let two handlers with the same params and
/// return type but different HTTP methods or routes canonicalise identically
/// — renaming a route is not a body edit, and R3.14's own firewall must
/// treat it as a real signature change.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum HandlerKindSignature {
    Call,
    Http { method: String, path: String },
    Cron { expr: String },
    Message,
    Open,
    Close,
    Event,
}

fn handler_kind_signature(k: &HandlerKind) -> HandlerKindSignature {
    match k {
        HandlerKind::Call => HandlerKindSignature::Call,
        HandlerKind::Http { method, path } => HandlerKindSignature::Http {
            method: method.as_str().to_string(),
            path: path.clone(),
        },
        HandlerKind::Cron { expr } => HandlerKindSignature::Cron { expr: expr.clone() },
        HandlerKind::Message => HandlerKindSignature::Message,
        HandlerKind::Open => HandlerKindSignature::Open,
        HandlerKind::Close => HandlerKindSignature::Close,
        HandlerKind::Event => HandlerKindSignature::Event,
    }
}

/// [DECISION B]: [`Handler`], body-free. Excludes `body`, `by_clause` (an
/// actor binder, resolved at the call boundary rather than part of the
/// wire-visible shape), `annotations` (see this module's own doc comment —
/// deferred, needs `Expr` canonicalisation) and `documentation`. `given` is
/// kept — it's this handler's own slice of the capability-set category.
/// `kind` is kept (see [`HandlerKindSignature`]) — dropping it was PR
/// #1517's own bot review finding #1.
#[derive(Debug, Clone)]
pub struct HandlerSignature {
    pub kind: HandlerKindSignature,
    pub method_name: Option<String>,
    pub params: Vec<ParamSignature>,
    pub return_type: TypeRef,
    pub given: Vec<String>,
}

fn handler_signature(h: &Handler) -> HandlerSignature {
    HandlerSignature {
        kind: handler_kind_signature(&h.kind),
        method_name: h.method_name.as_ref().map(|i| i.name.clone()),
        params: param_signatures(&h.params),
        return_type: h.return_type.clone(),
        given: cap_ref_names(&h.given),
    }
}

/// [DECISION B]: [`bynk_syntax::ast::StoreField`], body-free. Excludes `init`
/// and `annotations` (both body-adjacent per Q4 — annotations govern the
/// field's own storage behaviour, not its externally-relevant shape) and
/// `documentation`.
#[derive(Debug, Clone)]
pub struct StoreFieldSignature {
    pub name: String,
    pub kind_head: String,
    pub kind_args: Vec<TypeRef>,
}

/// A body-free mirror of [`bynk_syntax::ast::CapabilityOp`] — already
/// "signature only; no body" in its own doc comment (`ast.rs:564`), so
/// nothing here needs excluding beyond `documentation`/`span`/`trivia`.
/// Added by PR #1517's own bot review (finding #3): a `capability`
/// declaration's own ops are the abstract signature every consumer compiles
/// its `Cap.op(...)` call sites against, not `ProviderDecl.ops` (which carry
/// a real `body: Block` each — a provider's own implementation, correctly
/// excluded, same as any other body).
#[derive(Debug, Clone)]
pub struct CapabilityOpSignature {
    pub name: String,
    pub type_params: Vec<String>,
    pub params: Vec<ParamSignature>,
    pub return_type: TypeRef,
}

/// The capability-set category (design notes §15's fourth): what a unit
/// exports (`table.exported_capabilities`, already plain strings), what a
/// unit itself declares (`table.capabilities`'s own op signatures — added by
/// PR #1517's own bot review), and what each provider/service declares it
/// needs (`given`/`default_given`). Every `CapRef` collapses to its rendered
/// name (`context.capability`, or bare `capability` when local) — its own
/// `Span` is dropped, matching every other category's span-erasure
/// discipline.
#[derive(Debug, Clone, Default)]
pub struct CapabilitySignature {
    pub exported: BTreeSet<String>,
    /// Keyed by capability name (`table.capabilities`).
    pub declared: BTreeMap<String, Vec<CapabilityOpSignature>>,
    /// Keyed by the implemented capability's own name (`ProviderDecl.capability`).
    pub provider_given: BTreeMap<String, Vec<String>>,
    /// Keyed by service name (`ServiceDecl.default_given`).
    pub service_given: BTreeMap<String, Vec<String>>,
}

/// A `CapRef`'s canonical name: `context.capability` when cross-context,
/// bare `capability` when local. Spans are dropped — matching every other
/// category's span-erasure discipline.
fn cap_ref_name(c: &CapRef) -> String {
    match &c.context {
        Some(q) => format!("{}.{}", q.joined(), c.key()),
        None => c.key().to_string(),
    }
}

fn cap_ref_names(refs: &[CapRef]) -> Vec<String> {
    refs.iter().map(cap_ref_name).collect()
}

/// A body-free mirror of [`ServiceProtocol`] — added by PR #1517's own bot
/// review ("worth a look"): `from http` vs. `from queue(...)` vs.
/// `from websocket(...)` changes a service's entire external surface, and
/// nothing about that fact is a body or body-adjacent to a handler. `Events`'
/// own `pattern`/`schema_dispatch` are collapsed to `bool` presence (see this
/// module's own doc comment for why — deferred `Expr`/pattern
/// canonicalisation) rather than dropped outright.
///
/// No `PartialEq`/`Eq` derive: `TypeRef` (used by `WebSocket`/`Events`) does
/// not implement either — compare through [`crate::contract::canon_unit_signature`]'s
/// own rendering, the same "compare the canonical form" posture
/// [`UnitSignature`] itself takes.
#[derive(Debug, Clone)]
pub enum ProtocolSignature {
    Call,
    Http,
    Cron,
    Queue {
        name: String,
    },
    WebSocket {
        in_type: TypeRef,
        out_type: TypeRef,
    },
    Events {
        event_type: TypeRef,
        has_pattern: bool,
        has_schema_dispatch: bool,
    },
}

fn protocol_signature(p: &ServiceProtocol) -> ProtocolSignature {
    match p {
        ServiceProtocol::Call => ProtocolSignature::Call,
        ServiceProtocol::Http => ProtocolSignature::Http,
        ServiceProtocol::Cron => ProtocolSignature::Cron,
        ServiceProtocol::Queue { name } => ProtocolSignature::Queue { name: name.clone() },
        ServiceProtocol::WebSocket { in_type, out_type } => ProtocolSignature::WebSocket {
            in_type: in_type.clone(),
            out_type: out_type.clone(),
        },
        ServiceProtocol::Events {
            event_type,
            pattern,
            schema_dispatch,
        } => ProtocolSignature::Events {
            event_type: event_type.clone(),
            has_pattern: pattern.is_some(),
            has_schema_dispatch: schema_dispatch.is_some(),
        },
    }
}

/// P8.1 (#1512): a unit's stable signature — everything about it that must
/// survive an edit inside a function/handler body untouched (R3.14, the
/// phase's firewall).
///
/// Deliberately does not derive `PartialEq`: two signatures compare equal
/// through [`UnitSignature::canonical`] ([DECISION C]), not by structural
/// equality on the raw fields — the same "compare the canonical form, not
/// the raw AST value" shape `contract_hash.rs`'s own fixture already trusts
/// for ADR 0200. Comparing the raw struct would reintroduce exactly the
/// span-instability this type exists to erase.
#[derive(Debug, Clone)]
pub struct UnitSignature {
    pub id: UnitId,
    /// `combined_types_for`'s own output, reused unchanged ([DECISION A] of
    /// ADR 0412, Q1) — the cross-context-types category.
    pub combined_types: HashMap<String, Arc<TypeDecl>>,
    /// Free functions only — keyed by `FnName`'s own rendered form, matching
    /// `UnitTable.fns`'s own key. Methods live in [`Self::methods`] instead
    /// (see [`MethodTableSignature`]'s own doc comment for why).
    pub fns: BTreeMap<String, FnSignature>,
    /// Keyed by the attached type's name, matching `UnitTable.methods`.
    pub methods: BTreeMap<String, MethodTableSignature>,
    /// Keyed by owning service name; each maps to its handlers in
    /// declaration order. Kept separate from [`Self::agent_handlers`] (PR
    /// #1517's own bot review, lower-priority item): a flat shared namespace
    /// let a `service Foo`'s handlers be silently overwritten by an
    /// `agent Foo`'s own handlers, and the rendering couldn't distinguish
    /// the two owners either.
    pub service_handlers: BTreeMap<String, Vec<HandlerSignature>>,
    /// Keyed by owning agent name.
    pub agent_handlers: BTreeMap<String, Vec<HandlerSignature>>,
    /// Keyed by service name (`ServiceDecl.protocol`).
    pub service_protocols: BTreeMap<String, ProtocolSignature>,
    /// Keyed by owning agent name; `UnitTable.services`/`.providers` carry no
    /// store fields of their own.
    pub store_fields: BTreeMap<String, Vec<StoreFieldSignature>>,
    pub capabilities: CapabilitySignature,
}

/// Builds a [`UnitSignature`] for `name` from `table`, reusing `combined_types`
/// (typically a fresh `combined_types_for(name, ..)` call, mirrored here as a
/// parameter rather than recomputed so a caller building both alongside each
/// other pays for one traversal, not two).
///
/// Every category below is a direct, field-by-field projection off
/// `UnitTable`'s own real shapes — see this module's own doc comment and
/// `design/tracks/incrementality.md` §3.4 (Q4) for which fields are excluded
/// and why.
pub fn unit_signature_for(
    name: &str,
    table: &UnitTable,
    combined_types: HashMap<String, Arc<TypeDecl>>,
) -> UnitSignature {
    let fns = table
        .fns
        .iter()
        .map(|(fname, decl)| (fname.clone(), fn_signature(fname, decl)))
        .collect();

    let methods = table
        .methods
        .iter()
        .map(|(type_name, mt)| {
            let sig = MethodTableSignature {
                instance: mt
                    .instance
                    .iter()
                    .map(|(mname, decl)| (mname.clone(), fn_signature(mname, decl)))
                    .collect(),
                statics: mt
                    .statics
                    .iter()
                    .map(|(mname, decl)| (mname.clone(), fn_signature(mname, decl)))
                    .collect(),
            };
            (type_name.clone(), sig)
        })
        .collect();

    let mut service_handlers: BTreeMap<String, Vec<HandlerSignature>> = BTreeMap::new();
    let mut service_protocols: BTreeMap<String, ProtocolSignature> = BTreeMap::new();
    for (sname, sdecl) in &table.services {
        service_handlers.insert(
            sname.clone(),
            sdecl.handlers.iter().map(handler_signature).collect(),
        );
        service_protocols.insert(sname.clone(), protocol_signature(&sdecl.protocol));
    }

    let mut agent_handlers: BTreeMap<String, Vec<HandlerSignature>> = BTreeMap::new();
    let mut store_fields: BTreeMap<String, Vec<StoreFieldSignature>> = BTreeMap::new();
    for (aname, adecl) in &table.agents {
        agent_handlers.insert(
            aname.clone(),
            adecl.handlers.iter().map(handler_signature).collect(),
        );
        store_fields.insert(
            aname.clone(),
            adecl
                .store_fields
                .iter()
                .map(|f| StoreFieldSignature {
                    name: f.name.name.clone(),
                    kind_head: f.kind.head.name.clone(),
                    kind_args: f.kind.args.clone(),
                })
                .collect(),
        );
    }

    let declared: BTreeMap<String, Vec<CapabilityOpSignature>> = table
        .capabilities
        .iter()
        .map(|(cname, cdecl)| {
            let ops = cdecl
                .ops
                .iter()
                .map(|op| CapabilityOpSignature {
                    name: op.name.name.clone(),
                    type_params: op
                        .type_params
                        .iter()
                        .map(|tp| tp.name.name.clone())
                        .collect(),
                    params: param_signatures(&op.params),
                    return_type: op.return_type.clone(),
                })
                .collect();
            (cname.clone(), ops)
        })
        .collect();

    let mut provider_given: BTreeMap<String, Vec<String>> = BTreeMap::new();
    for pdecl in table.providers.values() {
        provider_given.insert(pdecl.capability.name.clone(), cap_ref_names(&pdecl.given));
    }

    let mut service_given: BTreeMap<String, Vec<String>> = BTreeMap::new();
    for (sname, sdecl) in &table.services {
        service_given.insert(sname.clone(), cap_ref_names(&sdecl.default_given));
    }

    UnitSignature {
        id: UnitId(name.to_string()),
        combined_types,
        fns,
        methods,
        service_handlers,
        agent_handlers,
        service_protocols,
        store_fields,
        capabilities: CapabilitySignature {
            exported: table.exported_capabilities.iter().cloned().collect(),
            declared,
            provider_given,
            service_given,
        },
    }
}

impl UnitSignature {
    /// [DECISION C]: the canonical, span-free rendering R3.14's own proof
    /// compares (`unit_signature_before.canonical() ==
    /// unit_signature_after.canonical()`), never the raw struct. Delegates
    /// every fragment through `contract.rs`'s canonical renderers so this
    /// type and `service_contract_hash` cannot silently diverge on what
    /// "the same type" means.
    pub fn canonical(&self) -> String {
        crate::contract::canon_unit_signature(self)
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use std::path::PathBuf;

    use bynk_project::{ParsedFile, UnitKind};
    use bynk_syntax::ast::SourceUnit;

    use crate::symbols::{build_unit_table, combined_types_for};

    fn parsed(source_path: &str, src: &str) -> ParsedFile {
        let tokens = bynk_syntax::lexer::tokenize(src).expect("lex");
        let unit = bynk_syntax::parser::parse_unit(&tokens, src).expect("parse");
        let kind = match &unit {
            SourceUnit::Commons(_) => UnitKind::Commons,
            SourceUnit::Context(_) => UnitKind::Context,
            SourceUnit::Suite(_) | SourceUnit::Adapter(_) => unreachable!("fixture only"),
        };
        ParsedFile::new(
            PathBuf::from(source_path),
            PathBuf::from(source_path),
            None,
            src.to_string(),
            unit,
            kind,
            false,
        )
    }

    const SHARED_SRC: &str = r#"commons demo.shared

type Widget = {
  id: String,
}
"#;

    const CONTEXT_SRC: &str = r#"context demo.svc

uses demo.shared

exports capability { Notifier }

fn double(x: Int) -> Int {
  x * 2
}

capability Notifier {
  fn ping(seed: Int) -> Effect[Int]
}

provides Notifier = StubNotifier {
  fn ping(seed: Int) -> Effect[Int] {
    Effect.pure(seed + 1)
  }
}

agent Counter {
  key id: String

  store count: Cell[Int]

  on call increment() -> Effect[Int] {
    count := count + 1
    Effect.pure(count)
  }
}

service api from http {
  on GET("/widgets/:id") (id: String) -> Effect[HttpResult[Widget]] by Visitor given Notifier {
    Ok(Widget { id: id })
  }
}
"#;

    fn build_signature() -> UnitSignature {
        let shared = parsed("demo/shared.bynk", SHARED_SRC);
        let context = parsed("demo/svc.bynk", CONTEXT_SRC);

        let mut errors = Vec::new();
        let shared_table = build_unit_table(
            "demo.shared",
            UnitKind::Commons,
            &[0],
            &[shared],
            &mut errors,
        );
        let context_table =
            build_unit_table("demo.svc", UnitKind::Context, &[0], &[context], &mut errors);
        assert!(errors.is_empty(), "fixture must parse cleanly: {errors:?}");

        let mut unit_tables = HashMap::new();
        unit_tables.insert("demo.shared".to_string(), shared_table);
        unit_tables.insert("demo.svc".to_string(), context_table.clone());
        let mut unit_uses = HashMap::new();
        unit_uses.insert("demo.svc".to_string(), vec!["demo.shared".to_string()]);

        let combined = combined_types_for("demo.svc", &unit_tables, &unit_uses);
        unit_signature_for("demo.svc", &context_table, combined)
    }

    /// P8.1 (#1512), the issue's own "Done when": builds a `UnitSignature`
    /// for a fixture unit carrying a function (`double`), a handler in both
    /// a service (`api`'s `GET` route) and an agent (`Counter`'s
    /// `increment`), a `store` field (`Counter.count`) and a cross-context
    /// type reference (`Widget`, reached via `uses demo.shared`) — every
    /// category [DECISION B]'s field list names — and proves the
    /// field-exclusion list is complete for all of them.
    ///
    /// The exclusion itself is a **compile-time fact, not a runtime
    /// assertion**, per [DECISION B]: `FnSignature`/`HandlerSignature`/
    /// `StoreFieldSignature` have no `body`/`requires`/`ensures`/`init`/
    /// `annotations` field to hold one — this test's real job is proving the
    /// builder actually reaches every category on real parsed source (a
    /// hand-assembled AST fixture could hide a field the builder silently
    /// skips), and asserting the shape that *does* survive is exactly the
    /// externally-relevant one.
    #[test]
    fn unit_signature_excludes_every_body_and_body_adjacent_field() {
        let sig = build_signature();

        assert_eq!(sig.id, UnitId("demo.svc".to_string()));

        // Cross-context type reference: `Widget` reached only through `uses`.
        assert!(sig.combined_types.contains_key("Widget"));

        // Fn signature.
        let f = sig.fns.get("double").expect("double must be projected");
        assert_eq!(f.params.len(), 1);
        assert_eq!(f.params[0].name, "x");

        // Service handler, including its own `given` and `kind`.
        let api_handlers = sig
            .service_handlers
            .get("api")
            .expect("api's handler must be projected");
        assert_eq!(api_handlers.len(), 1);
        assert_eq!(api_handlers[0].given, vec!["Notifier".to_string()]);
        assert_eq!(
            api_handlers[0].kind,
            HandlerKindSignature::Http {
                method: "GET".to_string(),
                path: "/widgets/:id".to_string(),
            }
        );

        // Service protocol.
        assert!(matches!(
            sig.service_protocols.get("api"),
            Some(ProtocolSignature::Http)
        ));

        // Agent handler and store field.
        let agent_handlers = sig
            .agent_handlers
            .get("Counter")
            .expect("Counter's handler must be projected");
        assert_eq!(agent_handlers.len(), 1);
        assert_eq!(agent_handlers[0].method_name.as_deref(), Some("increment"));

        let store = sig
            .store_fields
            .get("Counter")
            .expect("store field must be projected");
        assert_eq!(store.len(), 1);
        assert_eq!(store[0].name, "count");
        assert_eq!(store[0].kind_head, "Cell");

        // Capability-set category: what's exported, what's declared, and what
        // a provider needs.
        assert!(sig.capabilities.exported.contains("Notifier"));
        let ops = sig
            .capabilities
            .declared
            .get("Notifier")
            .expect("Notifier's own op signatures must be projected");
        assert_eq!(ops.len(), 1);
        assert_eq!(ops[0].name, "ping");
        assert_eq!(
            sig.capabilities.provider_given.get("Notifier"),
            Some(&Vec::<String>::new())
        );

        // The canonical rendering must actually run over every category above
        // without panicking, and must be deterministic.
        let rendered = sig.canonical();
        assert_eq!(rendered, sig.canonical());
        assert!(rendered.contains("double"));
        assert!(rendered.contains("Widget"));
        assert!(rendered.contains("count"));
        assert!(rendered.contains("Notifier"));
        assert!(rendered.contains("ping"));
    }

    /// PR #1517's own bot review: every assertion in the fixture above is
    /// positive ("this category got projected"), which cannot fail for a
    /// signature-changing edit the canonical form fails to notice. These
    /// four mutations are the other direction of R3.14's own firewall — each
    /// is a real signature change (never a body edit) and each must move
    /// `canonical()`, closing the review's three material findings (dropped
    /// `HandlerKind`, missing methods — covered by the `double`/capability-op
    /// assertions above plus the route/method/protocol mutations below — and
    /// missing capability-op signatures). The service/agent handler
    /// namespace collision (the review's lower-priority item) is closed
    /// structurally instead, by [`UnitSignature`] now keeping
    /// `service_handlers`/`agent_handlers` as separate fields — the same
    /// "make it a compile-time fact, not a runtime assertion" posture
    /// [DECISION B] already established for body-field exclusion.
    #[test]
    fn a_genuine_signature_edit_always_changes_the_canonical_form() {
        let base = build_signature().canonical();

        let renamed_route = CONTEXT_SRC.replacen("/widgets/:id", "/things/:id", 1);
        assert_ne!(base, signature_for_context(&renamed_route), "route rename");

        let different_method = CONTEXT_SRC.replacen("on GET(", "on POST(", 1);
        assert_ne!(
            base,
            signature_for_context(&different_method),
            "GET -> POST"
        );

        let retyped_cap_op = CONTEXT_SRC.replacen(
            "fn ping(seed: Int) -> Effect[Int]",
            "fn ping(seed: String) -> Effect[Int]",
            1,
        );
        assert_ne!(
            base,
            signature_for_context(&retyped_cap_op),
            "capability op retyped"
        );

        // The queue protocol requires `on message`, not `on GET`, so a real
        // `from queue(...)` fixture would need its own handler shape; the
        // protocol tag itself is checked directly at the `ServiceProtocol`
        // projection level instead of through a full re-parse.
        assert_ne!(
            crate::contract::canon_unit_signature(&with_protocol(ServiceProtocol::Queue {
                name: "q".to_string()
            })),
            crate::contract::canon_unit_signature(&with_protocol(ServiceProtocol::Http)),
            "http -> queue"
        );
    }

    fn signature_for_context(context_src: &str) -> String {
        let shared = parsed("demo/shared.bynk", SHARED_SRC);
        let context = parsed("demo/svc.bynk", context_src);

        let mut errors = Vec::new();
        let shared_table = build_unit_table(
            "demo.shared",
            UnitKind::Commons,
            &[0],
            &[shared],
            &mut errors,
        );
        let context_table =
            build_unit_table("demo.svc", UnitKind::Context, &[0], &[context], &mut errors);
        assert!(
            errors.is_empty(),
            "mutated fixture must still parse cleanly: {errors:?}"
        );

        let mut unit_tables = HashMap::new();
        unit_tables.insert("demo.shared".to_string(), shared_table);
        unit_tables.insert("demo.svc".to_string(), context_table.clone());
        let mut unit_uses = HashMap::new();
        unit_uses.insert("demo.svc".to_string(), vec!["demo.shared".to_string()]);

        let combined = combined_types_for("demo.svc", &unit_tables, &unit_uses);
        unit_signature_for("demo.svc", &context_table, combined).canonical()
    }

    fn with_protocol(protocol: ServiceProtocol) -> UnitSignature {
        let mut sig = build_signature();
        sig.service_protocols
            .insert("api".to_string(), protocol_signature(&protocol));
        sig
    }
}