> ## Documentation Index
> Fetch the complete documentation index at: https://docs.visiqlabs.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Retrieval Governance
> Retrieval-facet governance inside the visiq() harness. Governs what your AI agents can see at runtime.
Retrieval governance controls what your agents can **see**. Every retrieved document is evaluated against your rules before it reaches the agent's context window — allow, redact, deny, or escalate per document. There is no additional code beyond the `visiq()` call shown in the [Quickstart](/quickstart).
***
## How retrieval governance works
When `visiq()` wraps your agent, it instruments every retriever it finds. The flow:
1. Agent calls a retriever tool (e.g., `search_knowledge` with query `"Q3 revenue"`)
2. The retriever fetches raw results from the vector store
3. Each returned document is evaluated in-process against a locally cached rule bundle
4. **Allow** — document enters the context window unchanged
5. **Redact** — sensitive fields and patterns are masked before the agent sees the document
6. **Deny** — document is silently suppressed; the agent never sees it
7. **Escalate** — the access is recorded for human review; retrieval is synchronous (it can't pause on a human), so the rule chooses whether the document passes through or comes back masked in the meantime
No error is thrown for denied documents — suppression is a normal policy outcome. If every document is denied, the retriever returns an empty array.
Evaluation is local: the SDK evaluates against a cached rule bundle refreshed in the background (roughly every 5 seconds, with `ETag`/`304` caching), so there is no network round-trip in the retrieval hot path. On a cold start with no bundle loaded yet, the mode envelope decides: an agent **confirmed in `enforce`** that has lost its bundle stays fail-closed — nothing leaks while rules are unknown — while a **never-confirmed** agent runs `monitor` (monitor-until-confirmed), observing without suppressing. Retrieval's no-match default stays `deny` (the data-protection floor) wherever enforcement is active.
***
## How retrievers are detected
The harness checks three structural patterns on each object it walks:
| Pattern | Match condition | What gets instrumented |
| ------------------------- | ----------------------------------- | ------------------------------------------------------------ |
| LangChain `BaseRetriever` | `tool._getRelevantDocuments` exists | `_getRelevantDocuments()` wrapped |
| Generic retriever | `tool.retrieve` exists | `retrieve()` wrapped |
| Nested retriever | `tool.retriever` is an object | Recurses into `.retriever` and re-applies the above patterns |
### Retriever-backed tools
Many frameworks wrap the retriever inside a tool function. The harness recognizes a retriever-backed tool structurally (a reachable `.retriever` property) or by name — names containing `retriev`, or search/knowledge-style names that carry no mutation verb (`knowledge_base_update` is treated as an action tool, not a retriever). Two cases follow:
* **Retriever reachable** — the backing retriever is instrumented directly, so every document is evaluated with its own metadata (`classification`, `data_categories`, …) before the tool joins the results into a string. Full per-document fidelity.
* **Retriever hidden in a closure** — LangChain's `createRetrieverTool` captures the retriever in a closure and returns one joined string. The harness wraps the tool's function and filters that string as a single blob: always-on secret detection, pattern masking, and whole-result rules still apply, but rules keyed on per-document metadata cannot fire on a metadata-less string. The SDK logs a one-time console warning for each such tool. For full per-document governance, pass the retriever to `visiq()` directly or use a tool that returns a `Document[]`.
A tool that both retrieves and mutates (e.g. `retrieve_and_archive`) is a hybrid: one decision tagged `['retrieval', 'action']` governs both legs — the action side gates the call itself, the retrieval side filters what comes back.
Retrieval governance is not LangChain-only. On execute-based frameworks — Vercel AI SDK, Mastra, OpenAI Agents SDK, LlamaIndex, VoltAgent — the same `visiq()` call filters tool results through the retrieval facet.
***
## Always-on secret detection
Even with zero authored rules, retrieved content passes a deterministic value-shape floor that masks sensitive values by shape, wherever they appear: private keys, JWTs, cloud and vendor API keys (AWS, GitHub, Slack, Stripe, Google, LLM providers), bearer tokens, connection strings with inline passwords, checksum-validated card numbers and IBANs, SSNs, tax IDs, and email addresses. Detectors with a larger false-positive surface (phone numbers, IP addresses, MAC addresses, bank routing codes) are available opt-in. Manage detectors under **Settings → Organization → Security** in the [dashboard](https://app.visiqlabs.com).
***
## Key concepts
Policies over document metadata, trust tiers, and surfaces. Author in natural language, in the visual condition builder, or as policy source directly.
Every tenant is seeded a curated catalog of 29 default rules combining each agent's trust tier (`tier1` highest trust → `tier3` restricted) with its business function: agents that need a data category get it, medium-trust access escalates or is masked, and agents with no need-to-know never see raw values.
Mask SSNs, credentials, and account numbers inside permitted documents. The agent sees the structure but not the sensitive values.
Decisions — action and retrieval alike — emit record envelopes with asynchronous Ed25519-signed receipts (retrieval envelopes require artifact signing to be enabled for your organization). Tamper-evident proof for compliance audits.
***
## Agent modes
Governance mode is set **per agent**, is server-authoritative, and is controlled from the **Harness → Agents** page in the dashboard — not from SDK config:
| Mode | Behavior |
| --------- | ----------------------------------------------------------------------------------------------------------- |
| `monitor` | Evaluate and record every decision but never block or mask — observe-only. The default for every new agent. |
| `enforce` | Apply per-document decisions — deny, redact, and escalate per policy. |
| `off` | Bypass retrieval governance entirely — all documents pass through. |
Agents the harness sees for the first time are auto-provisioned in `monitor` mode, so instrumenting an agent never disrupts it. Watch its decision telemetry, tune your rules, then flip that one agent to `enforce` — no config change or redeploy required.
Monitor-first rollout is the intended adoption path: you see exactly what would have been denied, redacted, or escalated before any of it is enforced.
***
## Operations of one rule engine
Action governance and retrieval governance are not two systems — they are the **same rule engine** evaluating one event against the **operations** it carries. An event is tagged with an `operations[]` set (`action`, `retrieval`, `delegation` — a hybrid read-then-write tool carries `['retrieval', 'action']`), and a rule applies to whatever operations it targets, emitting an outcome from one shared vocabulary. The operations differ only in where the harness intercepts.
| Dimension | Action operation | Retrieval operation |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------ |
| **Governs** | What agents can **do** (tool calls) | What agents can **see** (retrieved context) |
| **Interception** | Wrapped tool dispatch methods (`invoke`, `call`, `_call`) — framework callbacks are audit-only because they cannot block | Wrapped retriever methods (`_getRelevantDocuments`, `retrieve`) plus tool-result filtering |
| **Outcomes** (one shared vocabulary) | permit / deny / approval\_required / mask | allow / deny / redact / escalate |
| **Audit** | Record envelopes with signed receipts, plus the human-approval queue | Record envelopes with signed receipts, plus a per-document audit log |
Every operation is evaluated by the same engine — they activate together from a single `visiq()` call.
***
## Next steps
The rule model: policy format, trust tiers, surfaces, and masking.
Tamper-evident audit trail with Ed25519 signatures.
Suspend one rule during an incident — bounded, audited, auto-expiring.
REST API for rules, receipts, and the audit log.