Module reference_resolution 

resolve_reference: the Layer-0 deterministic reference resolver from the “unified-verb” draft ADR (Slice 1 — resolver + ring).

Turns a natural-language reference into an id through four ordered stages, never guessing among close candidates:

1. Id-string passthrough. A ref that already looks like a UUID or an 8+ hex-char prefix resolves through the existing by-ID path (KhiveRuntime::resolve_by_id / resolve_prefix_unfiltered) instead of being treated as free text — it must not error just because it arrived through resolve_reference rather than get. Scoped to entity ids only, identically for the full-UUID and prefix forms (matching the ring’s entity-only contract); a note/edge/event id-string is NotFound here, not an error — a caller resolving those uses get.
2. Recently-referenced ring. An exact (case-insensitive) or substring match against this actor’s ring (reference_ring::ReferenceRing).
3. Exact-name storage lookup. A deterministic, case-sensitive match against entities.name in the caller’s namespace (deleted_at IS NULL) — covers any entity that already exists but was never created/get/updated/deleted/merged/linked by this actor in this session, so stage 2’s ring never saw it (#849).
4. Hybrid-search fallback. KhiveRuntime::hybrid_search over the caller’s namespace, ranked by RRF score.

A single candidate clearing the stage’s confidence bar resolves; multiple viable candidates or none never silently pick — they return Ambiguous or NotFound for the caller to disambiguate.

Structs

ReferenceCandidate

A candidate id surfaced when a reference did not resolve outright.

Enums

ReferenceResolution

Outcome of resolve_reference. Never a silent pick among close candidates: Ambiguous always lists what it found instead of guessing.

Functions

resolve_reference

Resolve one natural-language reference for token’s actor.