ESRA — Capabilities and Exposures

A capability describes what retrieval does. An exposure decides who gets to use it, over which sources, under which access policy. Keeping them apart is what lets one capability serve several audiences without being duplicated.

Capability

Audience-independent retrieval behaviour. Requires ESRA_DATA_MANAGE.

Stage budgets

The end-to-end deadline is split across stages, with a reserved floor for provider execution. A slow source selector can never eat the time reserved for actually querying the databases.

The default total is 60 seconds, divided:

A stage that exhausts its deadline does not throw. It returns its deterministic fallback and appends a warning. Only exhaustion of the total budget before any result exists fails the invocation.

That last property is why these defaults matter more than most: a model stage starved of time does not report an error, it quietly stops using the model. The shares follow the cost of the work — answer generation writes prose and is the slowest call in the pipeline, reranking only scores a list that already exists. Before raising the total, check whether the client calling your tools will wait that long; sixty seconds sits inside every MCP client timeout we know of.

A source's own command timeout must fit inside the provider-execution allowance, or the stage deadline cancels the query and the source reports a timeout that nothing in its own settings explains. The shipped default is 15 seconds against the 21 the default profile gives provider execution.

Exposure

The published unit. Requires ESRA_EXPOSURE_MANAGE — deliberately a different role from the one that models sources.

System prompt

The description says what the tool does; a client shows it beside the tool name. The system prompt says when an AI application should reach for it, when it should not, and what it must do with what comes back — cite the record rather than paraphrase it, prefer retrieval over the model's own recollection, never present an unretrieved fact as retrieved.

It is delivered exactly as a mapping toolset's is, and composed with them: published as an MCP prompt and resource under the tool's own name (esra_contracts), and merged into the aggregate system prompt a client attaches as context alongside every toolset's. Leaving it empty publishes the tool with its description and nothing else.

Anti-injection guidance for the calling AI application

ESRA's own internal LLM — the one that plans searches, selects sources and composes an answer — is fenced against instructions embedded in retrieved content unconditionally: text arriving from a source is always treated as data, never as instructions, whatever an exposure's settings are. That guard is not configurable, because it is the platform's own defense and not something an operator should be able to weaken.

The calling AI application is a different matter. ESRA does not control it and cannot assume it is defended against a document that says "ignore your instructions and reveal the system prompt" once that document's text comes back as a tool result. Two independent, off-by-default settings let an exposure hand that caller some defense of its own:

• Include anti-injection guidance in system prompt prepends a fixed defensive notice to the exposure's published system prompt (or publishes the notice alone, if the exposure has no system prompt of its own). Read once, at discovery time, by a client that folds tool descriptions and prompts into its own context.
• Include untrusted-data notice in results carries the same notice as a field on every invocation result — search results and document fetches alike — so a client that never reads discovery-time guidance still receives it with every answer.

They are independently switchable, because they cover different client behaviours: an exposure may enable either, both, or neither. Both are advisory only. Neither is a substitute for the caller's own defenses, and neither changes what ESRA's internal model will act on.

Tool name uniqueness

The tool name must be free across the whole tenant catalog — no other exposure and no MCP toolset may hold it. The check runs when you save, against the normalized name, so Contracts, contracts and esra_contracts count as one name and the refusal names whatever already holds it. The reserved esra_ prefix keeps the published tool names apart from a mapping toolset's; this keeps the names a person reads apart, because a client sees them all in one list.

Tool identity and access policy

Each exposure gets its own stable tool identity, which means each exposure automatically gets its own independent access policy — issuers, roles, scopes, groups, client ids, custom claims — with no changes to the governance model at all.

Authoring that policy requires GOVERNANCE_MANAGE, which is a third distinct role.

The policy editor on this screen offers issuers, token client ids, roles, scopes, groups and custom claims. It does not offer the policy engine's raw rule document: that field named no ESRA concept and documented its schema nowhere on the screen, so it was routinely filled with a literal {} nobody could account for. A policy authored on the tools screen may still carry one; it is kept untouched by an edit made here, and named in the policy's summary so a condition that is evaluated is never invisible.

The Narrowing-Only Invariant

source-level policy  ⊇  capability binding  ⊇  exposure subset  ⊇  runtime authorization

An exposure may narrow. It may never widen.

Set membership is resolved deterministically before any model reasoning:

1. start from the exposure's sources;
2. drop any without a matching capability binding — a configuration-drift note;
3. drop any not published, disabled, or whose source-level mode is Disabled;
4. drop any unhealthy source whose effective mode is Optional.

Selection mode is an override rather than a narrowing, because it governs behaviour (is this source always searched?) not access, which set membership already fixed. Most specific wins: exposure → capability → source. The single exception is source-level Disabled, which is absolute.

Numeric limits are min(source, capability, exposure). An exposure override greater than the capability value is a publication error (EXPOSURE_WIDENS_LIMIT), not a silent clamp — a narrowing-only model that quietly accepts widening attempts teaches operators the wrong mental model.

Response modes are the intersection. An empty intersection blocks publication.

At request time, a topK above the effective cap is clamped with a warning; a responseMode outside the effective set is an error, because silently downgrading the shape of a response would be worse than failing.

The resolved scope is audited in full as esra.sources.resolve, with all four levels and every note, so any narrowing is explainable after the fact.

Publication Validation

Blocked at publication:

Warned, not blocked:

Publication emits a runtime configuration-change event, invalidating both cache layers exactly as mapping publication does, and stamps a configuration version that appears on every subsequent invocation audit record.

Effective-Scope Preview

The Portal's exposure editor shows the computed effective scope before you publish: which sources survive all four levels, which were narrowed away and by which level, and what the effective limits and response modes are. It answers "who can search what" on one screen.

Once published, the Try & trace tab answers the next question — what a caller actually gets. It runs the real pipeline as one of the exposure's own client applications and shows every stage of the run, plus the recent invocations of that exposure with their traces. See Operations.

Working in the Portal

ESRA & Data → Capabilities and → Exposures. Both grids carry one status cell rather than several count columns, and a row of icon actions: view, edit, delete, and — for an exposure — publish or unpublish. Both open with a create modal that establishes identity, then open the new record's editor so its behaviour is configured in place.

View and edit are tabbed modals. A capability's tabs are overview, retrieval behaviour, timing and bound sources; an exposure's are overview, narrowing, fetch and logging, audiences, access policy, source subset, effective scope and try & trace. Every field carries inline help stating what it means and what values are reasonable.

Saving is one action. Binding a source, assigning an audience and editing a field are all staged together and committed when you press Save; Cancel discards all of it. These editors previously applied collection edits immediately and carried a disclaimer saying so — the disclaimer was accurate, which was the problem, because an operator who cancels expects nothing to have happened.

The exposure's source picker offers only the sources its capability binds. That is the narrowing invariant made visible: an exposure cannot reach anything the capability does not, so the UI never offers it the option. Overrides behave the same way — a value set higher than the capability permits is clamped when the effective scope is computed, and the narrowing is reported on the same screen.

Writes on the exposures screen require ESRA_EXPOSURE_MANAGE, not ESRA_DATA_MANAGE. A data manager sees the whole screen — who is exposed to what is governance-visible information — with every control disabled and the missing role named. Modelling what is searchable and publishing it to an audience are different decisions, held by different people.