Retrieval Context Provenance Auditor — reference implementation

Status: released under MIT. This is the reference implementation of the public behaviour specification at https://github.com/SweetKenneth/shpbl-spec-retrieval-auditor. It was written fresh from that specification, then cleared an exact-file IP surface review and an explicit MIT implementation grant naming that reviewed file set.

What it answers

After an agent makes a bad decision: which retrieved documents caused it, and were any of them poisoned, stale, or newly introduced?

It records the retrieval supply chain — source → chunk → transformation → context → decision — and afterwards reports influence ranking, lineage, transformation fidelity, advisory source trust and retirement, co-influence correlation, and retrieval schema drift.

It never performs retrieval, never ranks documents for an agent at query time, and never blocks a decision.

Related MCP server: Agent Audit Trail MCP Server

Tool surface (MCP, stdio, zero dependencies)

Install and run

Prerequisites: Bun 1.1+ (or Node 22+ with a TypeScript loader). No install step is required beyond the clone, because there are no runtime dependencies.

git clone https://github.com/SweetKenneth/shpbl-retrieval-auditor.git
cd shpbl-retrieval-auditor
bun install                    # dev types only
bun test                       # conformance suite
bun run scripts/symbol-scan.ts # build-failing forbidden-symbol scan
bun src/mcp-server.ts          # MCP server: newline-delimited JSON-RPC 2.0 on stdin/stdout

MCP configuration

{
  "mcpServers": {
    "shpbl-retrieval-auditor": {
      "command": "bun",
      "args": ["/absolute/path/to/shpbl-retrieval-auditor/src/mcp-server.ts"]
    }
  }
}

Outputs

Every tool returns JSON: lineage graphs, ranked influence with an explicit unexplained residual, advisory trust and retirement recommendations with their basis, drift findings, and a payload-free hash-linked audit export. A worked poisoned-source example is in examples/.

Boundaries held by construction

• Digest-only. Raw document, chunk, query and decision text is never accepted, stored or exported. Non-digest values are rejected as E_INPUT and never echoed back.

• Attribution honesty. Influence plus unexplained sums to exactly 1.0. The product never claims a complete explanation, because it observes assembly and observation evidence, not model reasoning.

• Advisory trust. A distrusted source is annotated, never withheld or removed.

• No egress. No network symbol, no ambient filesystem write, no process execution — enforced by a build-failing scan.

• Clean-room trust layer. Source trust and retirement are implemented from the public specification's properties T1–T10 only, and verified against those properties — never against output equality with any private implementation.

Verification

31 conformance tests, 6,415 assertions: specification properties P1–P11 and trust properties T1–T10, plus every §7 failure mode. Randomised checks use a seeded generator, so runs are reproducible.

Provenance

SHPBL discovers the invention; this package implements it from a written specification. See PROVENANCE.md.

Known limitations

• Influence attribution observes context assembly and observation evidence, not model reasoning. The reported unexplained residual is the honest share it cannot account for, and it is never suppressed.

• Source trust is advisory. The product annotates a distrusted source; it does not withhold, remove or block retrieval, and it never performs retrieval itself.

• Because only digests and declared metadata are accepted, the auditor can prove which recorded material a decision used, but it cannot recover the original document text — that remains with the operator's own systems.

• The hash-linked audit export detects edits to what was recorded; it cannot prove that a retrieval was recorded at all. External anchoring of the head digest is the operator's responsibility.

Tenable status

Submitted to the Tenable CyberAgents Exchange for review on September 11, 2026. Submission does not imply review, approval, certification, validation, endorsement, or acceptance by Tenable.

SHPBL Agent Evidence series

Independently installable, interoperable at the evidence-record boundary:

• shpbl-action-ledger — agent action evidence ledger

• shpbl-handoff-attestor — cross-agent handoff attestation

• shpbl-drift-sentinel — agent behaviour drift detection

• shpbl-retrieval-auditor — retrieval context provenance

• shpbl-canary-chain — synthetic canary evidence chain

Licence

MIT — Copyright (c) 2026 Kenneth E. Sweet Jr. See LICENSE.