ESRA — The Retrieval Pipeline

What happens between an AI client calling esra_{name} and the results coming back.

authenticate → authorize → audit          (platform Runtime, unchanged)
      ↓
resolve effective scope
      ↓
select sources
      ↓
plan searches (per source, concurrently)
      ↓
validate plans          ← nothing unvalidated can reach a provider
      ↓
execute (bounded parallel, parameterized, read-only)
      ↓
normalize → aggregate & deduplicate → rerank → top-K
      ↓
respond

Everything upstream of "resolve effective scope" is the platform's ordinary tool-invocation path. ESRA branches in only after governance authorization and the invocation audit record — so tenant resolution, policy evaluation, audit, metrics and correlation are shared and unchanged.

1. Resolve effective scope

Deterministic, before any model call. Intersects source policy, capability binding, exposure subset and runtime authorization; applies health; computes the effective limits and response modes. Audited as esra.sources.resolve with all four levels.

An empty effective set fails the invocation with ESRA_NO_SOURCES_AVAILABLE.

2. Select sources

Mandatory and policy-forced sources are included unconditionally and are not sent to the model at all. The service LLM only ever chooses among the Optional ones — which keeps the prompt small and bounds the blast radius of a bad selection.

The model receives business metadata only: description, usage and exclusion guidance, domain tags, languages, example prompts, freshness. Never a schema, a relation name, a field, a host or a credential.

Its output is validated against the candidate set. A source id it was not given is dropped and audited as LLM_UNKNOWN_SOURCE_REJECTED — the model cannot widen its own reach.

Fallback: mandatory and policy-forced sources only, with ESRA_SELECTION_FALLBACK.

Selection results are cacheable — keyed on normalized prompt, exposure, configuration version and candidate-set fingerprint, tenant-partitioned, and disabled where retention classification forbids prompt derivatives.

3. Plan searches

One planning call per selected source, concurrently. A single combined call was rejected: it couples unrelated sources' failures and would leak one source's terminology into another's context.

The planner sees the caller's prompt, the source's business description, and for each mapping its business name, description and the {fieldName, isSearchable, isFilterable, allowedOperators} of each field. It plans against a business schema, never a database schema. Provider capabilities are stated explicitly, so it is never asked to guess what the engine supports.

It emits between one and the source's configured MaxQueriesPerSource queries per source (an admin-configurable per-source ceiling, clamped to 1–20, defaulting to 3), each with a strategy (phrase, keyword, synonym, acronym, entity, recent), required/optional/excluded terms, phrases, and structured filters.

Fallback: the mapping's default template — one phrase query over the prompt plus one keyword query over its content words — with ESRA_PLANNING_FALLBACK.

4. Validate

Deterministic and non-bypassable. The validator asserts that the mapping belongs to a selected source; every projected field is returnable and not restricted; every filter field is filterable with a permitted operator; every limit is within policy; the provider supports the strategy; and no term, phrase or filter value contains a statement separator or comment sequence.

This is enforced structurally, not by convention. A provider can only execute a query object that the validator itself constructed — there is no code path that reaches a database without having passed through validation first.

Rejected queries are dropped and audited with a reason code; the invocation continues with what survived, warning ESRA_PLAN_REJECTED.

5. Execute

Concurrent, bounded at four levels (per invocation, per source, per provider, per runtime instance). Each command runs through a resilience pipeline — timeout, transient-only retry, circuit breaker, concurrency limiting — applied per source.

Every command:

• runs in a read-only transaction with a server-side statement timeout and a restricted search path;
• carries every prompt-derived and claim-derived value as a parameter, never as command text;
• resolves relation and field identifiers from configuration by id, quoted by the provider's identifier quoter;
• applies its row cap server-side, not by reading and discarding;
• orders by score descending and record key ascending, so results are stable across executions.

Provider test suites verify this directly: rendering a command from a query built entirely out of injection-style content produces command text byte-identical to the equivalent benign query — proof that untrusted content can only ever end up as data, never as part of the command itself.

Errors are classified into a closed set of sixteen codes before leaving the provider — TIMEOUT, CONNECTION_REFUSED, AUTH_FAILED, RELATION_NOT_FOUND, PERMISSION_DENIED, COLUMN_NOT_INDEXED, TEXT_INDEX_UNAVAILABLE, SYNTAX_ERROR, RESOURCE_EXHAUSTED, CANCELLED, SNAPSHOT_ISOLATION_UNAVAILABLE, HOST_NOT_ALLOWED, SECRET_UNRESOLVED, CONNECTION_TEMPLATE_INVALID, UNKNOWN, CIRCUIT_OPEN. Only CONNECTION_REFUSED, RESOURCE_EXHAUSTED and TIMEOUT are retryable; CIRCUIT_OPEN is deliberately excluded, since the breaker has already made the retry decision for that source. Raw driver text goes to the log and nowhere else.

6. Normalize and aggregate

Per query, over that query's own result set:

normalized = (native − min) / (max − min)          (1.0 when max == min)
weighted   = normalized × priorityWeight × freshnessWeight

Cross-query duplicates keep the highest weighted value and merge provenance. Being found by more than one query is weak positive evidence: +0.02 per extra match, capped at +0.1.

Native provider scores are preserved verbatim in provenance and never compared across sources.

7. Rerank

The model sees the caller's prompt and, per candidate, an opaque resultId, the source name, the title, and truncated fragments. Never record keys, restricted fields, or provider scores — those would anchor it to lexical ranking and defeat the purpose.

Candidates are selected round-robin across sources so one prolific source cannot crowd out a small source's strong matches.

Final ordering is computed by ESRA, not taken from the model's array order:

final = 0.7 × semantic + 0.3 × weighted        (weights configurable per capability)

A candidate the model omitted keeps a null semantic score and ranks below all scored candidates — an omission is evidence of an incomplete response, not of irrelevance.

Fallback: normalized-score ordering, with ESRA_RERANK_FALLBACK.

8. Respond

Top-K selection is deterministic. Field allowlist, then masking, then size cap, then error sanitization.

Status is complete or degraded; degraded always carries at least one warning explaining why.

Document Fetch

Retrieval returns bounded fragments by design. An agent that has found the right document often needs more of it — so each exposure may publish a second tool, esra_{slug}_fetch, that returns a larger portion of one already-surfaced document.

Each result then carries a documentRef: an encrypted, expiring token. Encrypted rather than merely signed, because a record key is itself source-internal data that must not leak through an opaque-looking string.

The token identifies; it never authorizes. On every fetch the full chain re-runs: exposure still published, access policy still admits this caller, source still in scope, field allowlist and masking reapplied, record filter re-evaluated against the current caller's claims. A token minted for one caller and replayed by another yields ESRA_DOCUMENT_NOT_FOUND — not a permission error, which would confirm the record exists.

Fetch is off by default, per exposure. It converts a governed retrieval capability into a document-download API, so it is an explicit decision per audience, bounded by a per-caller hourly character quota, and every call is a first-class audit record.