Signature Kernel

Semantic Signature Kernel

The one authority for what a callable is, how two types are compared, and what order semantic composites are published in. Every signature set, every intersection/union reduction, and every deterministic ordering decision in the session crate comes from here; there is no second signature producer and no per-consumer ordering rule.

Normative contract: docs/arch/signature-kernel.md (revision 4.1, byte-locked by docs/evidence/signature-kernel/manifest.json). Where this skill and the contract disagree, the contract wins.

1. Module map

crates/verter_type_engine/src/signature_kernel/ (crate-private; its single consumer is project_semantic_dispatch/signature_discovery.rs):

Ordering and composite reduction live beside the kernel, in the dispatch crate:

2. Ordered reduction is ONE pair of queries

Union and intersection construction is closed over exactly two query keys and exactly two crate-private builders:

SemanticQueryKey::ReduceUnion { members, nullability }      → build_reduce_union
SemanticQueryKey::ReduceIntersection { input, purpose, ctx } → build_reduce_intersection
        ↓                                                           ↓
canonical_algebra::intern_ordered_union          canonical_algebra::intern_ordered_intersection

Both builders perform recursive same-kind flattening, the lattice absorption laws, literal subsumption on unions, structural T | T = T / T & T = T through compare_structural, and proven-disjoint scalar collapse to never — an undecided relation is never guessed. Both thread CanonicalEvidence to deposit_canonical_evidence; an incomplete comparison sets cache_suppress (ReturnOnly, never a warm canonical result).

A union is built under an explicit NullabilityPolicy — strictNullChecks as construction input. Erased (the option off) drops null / undefined beside any other member, as the checker's getUnionType does, and a nullable-only list becomes null if it names null, else undefined. The policy is family identity on ReduceUnion and is recorded on the canonical stamp (CompositeOriginCategory::Canonical(NullabilityPolicy)), so the two settings never share a memo entry, a node, or the pre-seal skip. Intersections run the strict algebra.

ProjectSemanticDispatch::intern_normalized_union_or_intersection is the dispatch-level funnel every flow/meta-resolve/locator producer reaches these through; its unions run the strict algebra. The flow-return evaluator, which answers under its function's own project policy, constructs through intern_normalized_union with the frame's policy instead. Two composite constructions are deliberately outside the funnel, both CompositeList::ordered_carrier mints, and both for the same reason — an ordered carrier is an authored sequence, not a commutative intersection, and routing it through the reducer would change the origin category and therefore node identity:

1. same-name method overload groups (walk.rs, build.rs);
2. a possibly-callable member-value intersection (walk.rs merge_value_nodes_recursive). Call resolution over an intersection tries arms in declaration order, so a commutative sort would break overload precedence. The classification (value_may_contribute_call_signatures) fails CLOSED on anything undecidable from the graph alone, and callable merging itself belongs to SignaturesOfType → signature_kernel::discovery::intersection_signatures, never to a local concatenation of signature nodes (§15).

An interface/class declaration body with heritage is a third construction outside the funnel, the CompositeList::heritage mint (§6, rule 8): it is a declaration, not a commutative intersection, and is never re-decided.

Retired spellings. NormalizeUnion, NormalizeIntersection, SemanticMeet, canonical_intersection, build_normalize_union and UnionSelected are retired names. Each is an entry in RETIRED_SYMBOLS (crates/verter_session/tests/cases/g_misc0/no_legacy_walker.rs), enforced by retired_symbols_absent_from_production_source. Re-introducing one resurrects a second composite-construction authority beside the ordered reduction pair, which is exactly how two producers start ordering arms differently.

3. Determinism: VerterStableV1

StableKey::cmp compares (fingerprint, exact) — the FNV-1a hash of the exact key bytes FIRST, the exact bytes only on collision. Consequences worth keeping in mind:

• Canonical union member order is fingerprint order, not authored order and not lexicographic order. Extract<'a'|'b'|'c', 'a'|'b'> renders "b" | "a".
• An authored-order display pin in an older test is an arena-id-sort coincidence (arena id == lowering order), not a contract.
• intern_ordered_union interns with ORDER-SENSITIVE identity (CompositeMembers::eq compares the member slice), so [a,b] and [b,a] are distinct nodes — there is no set-collision first-wins there.

Every SemanticNodeData variant has a VerterStableV1 encoding. The registration table STABLE_KEY_TABLE in crates/verter_session/tests/cases/g_block/semantic_determinism_matrix.rs enumerates the live variant set exactly (guard: stable_key_table_enumerates_every_semantic_node_data_category) and carries a residual column naming, per variant, any identity input the encoder currently approximates rather than consumes.

4. Epoch-safe storage and the lifetime contract

• Handles are epoch-qualified. A handle minted in a retired epoch is rejected, not silently re-read (stale_epoch_handle_is_rejected).
• replace_epoch() installs a new graph epoch. A reader pinned before the replacement finishes against its epoch (old_pinned_reader_finishes_against_its_epoch, pinned_view_reads_substitution_after_epoch_replacement).
• Live readers are roots until drop (live_readers_are_roots_until_drop, live_reader_count_includes_pinned_retired_epoch).
• Retained results outlive an epoch replacement until drained (retained_results_outlive_epoch_replacement_until_drained).
• Interning rejects stale embedded handles across a replacement (intern_rejects_stale_embedded_handles_across_epoch_replacement), and a result lookup MISS never publishes (lookup_result_does_not_publish_on_miss).

The kernel store does not own the process byte budget: aggregate retention is SemanticRetentionAccount (see /type-cache-architecture → Aggregate retention account). A retained parse snapshot is a Pinned charge — charged unconditionally, never refused.

Semantic identity records are owned by their handles

Intersection recipes, semantic contexts, order domains and the large family-key payloads (RelateMemoKey, ResolveCallKey) are NOT ordinals into process-owned tables. semantic_query_memo/intern_table.rs owns the substrate:

• Interned<T> is one owning Arc pointer. IntersectionInputId, SemanticContextId and OrderDomainId wrap one; they are Clone, not Copy, and expose the value (recipe(), context()) — there is no as_u32, no lookup_*, and no raw slot number another index could also mint.
• Each kind declares itself with intern_domain!, which gives it a private WeakInternTable reached as InternDomain::index(). The index only DEDUPLICATES (digest → Weak); it owns no record. A record's destructor forgets its entry, and a surviving collision bucket and the index both shrink their backing capacity once drained.
• Identity is exact value equality behind the digest: equal handles share a record, or match digest AND value. A digest collision never aliases.
• Retained children: a record owns exactly what its value owns. An OrderedSteps recipe's EvaluateSubgroup recipes are its only same-kind children; a held parent keeps them valid. A kind with same-kind children overrides InternDomain::take_children, so a released chain is reclaimed iteratively — nesting depth never becomes destructor stack depth, including when a step slice is still watched by a Weak (the children are handed to the worklist by clone before the slice is released).
• IntersectionInputId's Debug prints the recipe digest and top-level shape only; a nested subgroup is never expanded, so formatting a key is O(1) in nesting depth and sharing.
• WeakInternTable::occupancy / IdentityIndexSnapshot::capture are the always-compiled lifetime counts (records, digests, digest-map and spilled collision capacity), surfaced as HostRetentionSnapshot::identity_indexes.
• Walk recipe operands only through IntersectionInputRef::for_each_operand: iterative, and each distinct subgroup recipe is walked once however many parents share it (the family release sweep runs it under the memo lock).
• Lock discipline: never drop something that can destroy a same-kind record while holding that kind's index lock.
• SemanticContextId::production() is the one permanent record. SemanticPolicySetId is the policy set's own value (SemanticPolicySet::id()), so it needs no table.