Module unit_signature 

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.

Structs

CapabilityOpSignature

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).

CapabilitySignature

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.

FnSignature

[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).

HandlerSignature

[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.

MethodTableSignature

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).

ParamSignature

[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).

StoreFieldSignature

[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.

UnitId

[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.

UnitSignature

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).

Enums

HandlerKindSignature

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.

ProtocolSignature

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.

Functions

unit_signature_for

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).