Module retrieve 

Compound deterministic grounding retrieval (decided retrieve, ADR-113) — a port of src/asdecided/services/retrieve.py and src/asdecided/services/scope.py / scope_paths.py (the scope-binding channel) from the grounding-retrieval-surface branch (oracle 0.1.dev55+gf2091befd). The ADR-033 response budget (serialization + truncation) lives in crate::budget.

Landmines reproduced here:

• Excerpts are Python character slices (content[:share]), over the file’s text read with universal newlines (\r\n/\r → \n); an unreadable or non-UTF-8 file contributes an empty excerpt.
• Payload/provenance key ORDER is Python dict insertion order: items are id, type, title, status, path, excerpt, provenance; provenance keys in first-set order (channels first, then whichever of matching_entry, superseded, evidence was set first).
• Scope binding matches scope._entry_covers: segment-aware globs compiled exactly like _glob_to_regex (*/? within a segment, ** across, **/ zero-or-more whole segments, [...] classes, .-collapse and ..-rejection in path normalisation).

Structs

GoverningDecision

One governing decision (GoverningDecision — the fields retrieve and decided decisions-for read).

ScopeLookupResult

ScopeLookupResult — the decisions governing a queried path. query is the POSIX repo-relative form when the path lies inside the repository, else the raw stripped input; an outside-repository or ungoverned path is a valid empty answer, never an error (REQ-004).

ScopeRow

One live decision’s declared ## Applies To scope (ScopeRow).

Constants

DEFAULT_TOP_K

Functions

decisions_for_path

decided.services.scope.decisions_for_path(directory, path, recursive) — the CLI face of the scope lookup. Byte-identical to the derived-cache path (governing_decisions) for the same corpus and path; recursive threads the CLI’s --top-level through the corpus walk (the MCP find_decisions path mode always walks recursively).

decisions_for_path_with_rows

decisions_for_path over ALREADY-DERIVED scope rows (ADR-103): the read-model arm of the MCP find_decisions path mode, byte-identical to the fresh walk for the same corpus state.

find_decisions_path_payload

find_decisions path mode (MCP surface): the ScopeLookupResult.to_dict() payload — {schema_version, query, in_repository, decisions} — for the live decisions whose declared ## Applies To scope governs path. Additive wrapper over the same scope internals retrieve_grounding uses (scope_rows_from_items / normalize_query / entry_covers), byte-identical to decided.services.derived_cache.governing_decisions(...).to_dict().

retrieve_grounding

retrieve_grounding(directory, task, scope, top_k, budget, live_only) — the contract-shaped payload, pre-serialization (budget::serialize caps it).

retrieve_grounding_from_derived

Grounding over an already-derived mutation-window snapshot. Only matched, governing, and successor paths are read from disk for status/excerpts; the corpus itself is never walked or parsed again.

retrieve_grounding_from_store

Grounding over the immutable mmap store. Search uses postings, path lookup uses the persisted path map, and only the relationship/scope projections required by grounding are decoded.

scope_lookup_value

ScopeLookupResult.to_dict() — {schema_version, query, in_repository, decisions} in Python dict insertion order.

scope_rows_from_items

_scope_rows_from_corpus(entries) — live decisions with declared scope.