com.brick-byte/footnote

Footnote

Claim-level provenance for AI over business data. Every number in an answer traces back to the rows that produced it — clickable at read time, exportable for an auditor, and tamper-evident.

An MCP server, a provenance store, and a demo UI showing what the combination looks like.

npm install
npm run demo      # http://localhost:4711
npm test          # 25 tests, including the invariants below

Node 22.5+ required (uses the built-in node:sqlite, so there is no database to install).

Postgres is opt-in. The same schema, seed and query set run against it, and the same suite has to pass on both:

npm run db:up     # Postgres 17 in Docker, seeded from migrations/001_init.sql
npm run test:pg   # the identical 25 tests, against Postgres
npm run demo:pg   # the demo, against Postgres

---

The problem

Language models produce plausible continuations, not true ones. Point one at a business database and it will confidently report a number that no query produced — and the fabricated figure is indistinguishable from the real one, because both come out of the same machinery.

The usual answers don't hold up here. Uncertainty signals catch the fuzzy cases, not the fluent ones. A verifier built from the same model can confirm a fabrication as easily as catch it. And in finance, inventory or procurement, "the model said so" is not an answer anyone can act on.

What does work is structural: never let the model produce the number.

The architecture

  question
     │
     ▼
  model ──────────► picks an operation from a catalog and supplies typed args
     │                (it cannot write SQL, cannot invent an operation)
     ▼
  contract layer ─► validates params, resolves entities against the database,
     │                rejects anything that does not exist
     ▼
  deterministic ──► executes the query; SQL does all aggregation
  core                returns values + the evidence behind each one
     │
     ▼
  provenance ─────► appends a hash-chained record, server-side,
  store               where the model cannot influence it
     │
     ▼
  host UI ────────► fills slots from structured output and renders each
                      claim as a clickable citation

The model handles translation and phrasing — the two things it is reliable at. Numbers come from the system of record.

What it enforces

These are tests, not guidelines. npm test fails if any of them breaks.

No number is generated. Values are copied verbatim from an operation's structured output into template slots. A test asserts every monetary figure in an answer is covered by a claim with evidence behind it, and that the stated total equals the sum of the records it cites.

Entities are validated before any query runs. A fabricated customer produces a recoverable error listing real alternatives — not a silent empty result the model narrates around.

Aggregation happens in SQL. The model chooses which aggregation to run, never what it equals.

Empty results are handled in code. This is the single biggest fabrication trigger: hand a model an empty result set mid-sentence and it invents something to finish the sentence. Operations set an explicit emptyReason instead.

Unroutable questions are refused. "What will revenue be next quarter?" maps to no operation, so no answer is produced. Refusal is a first-class outcome, not a failure.

Provenance is written server-side. The model never reports its own provenance. Provenance that depends on the model choosing to cite is worthless.

The log is tamper-evident. Each record carries the hash of its predecessor. npm run verify walks the chain and reports the first record that was modified after it was written.

Interpretations, not just figures

The harder case is judgement. "Bergmann is at risk" is a conclusion with no row to check it against — and an ungrounded interpretation is more dangerous than an ungrounded number, because it reads as insight and survives review.

The answer here states the conclusion and then lays out each premise as a separately cited fact:

Bergmann Logistik GmbH shows two independent risk signals.
This is an interpretation — the underlying facts are:

  · 43.805,00 € overdue across 4 invoices, oldest 104 days past due
  · 2 open support tickets, 1 high severity
  · agreed payment terms of 30 days, account owned by Ana Kovač

The conclusion is the model's. Every fact above is a record you can open.

A human can disagree with the reasoning while trusting the inputs.

Provenance record format

{
  "id": "…", "sequence": 1, "timestamp": "2026-08-14T09:12:04.000Z",
  "actor": { "id": "zoran", "role": "controller" },
  "question": "How much does Bergmann owe?",
  "answer": "Bergmann Logistik GmbH is 43.805,00 € overdue across 4 invoices…",

  // Each claim indexes a span of the answer and names its evidence.
  "claims": [
    {
      "text": "43.805,00 €",
      "span": { "start": 25, "end": 36 },
      "evidenceIds": ["invoice:8812", "invoice:8834", "invoice:8901", "invoice:8977"],
      "origin": "structured"        // never "generated" for a value
    }
  ],

  // The query, so the result is reproducible.
  "operations": [
    { "name": "getOverdueInvoices",
      "arguments": { "customer": "Bergmann", "asOfDate": "2026-08-14" },
      "query": { "sql": "SELECT …", "params": ["2026-08-14", 4471, "2026-08-14"] },
      "durationMs": 0.42 }
  ],

  // Field values, not just IDs — the export stands alone if the source moves on.
  "evidence": [
    { "id": "invoice:8812", "type": "invoice", "recordId": "8812",
      "uri": "erp://invoice/8812",
      "fields": { "number": "INV-2026-8812", "due_on": "2026-05-02",
                  "outstanding": "18.450,00 €", "days_overdue": 104 } }
  ],

  "previousHash": "0000…", "hash": "9aa2ba…"
}

origin is the field that matters. structured means the value was copied from an operation's output. generated means a model produced it — which for a number is exactly what this project exists to prevent.

MCP details

The server uses the parts of the protocol that carry this work:

Feature	Use
inputSchema	The model gets a typed catalog, not a query language
structuredContent	Values return as validated JSON beside the prose, so figures never have to survive a round trip through generated tokens
resource_link	Every record touched comes back as an erp:// URI — the deep-link primitive behind a clickable citation
annotations.audience	Record links are marked user-facing
_meta	Carries the provenance record ID and hash so a host can fetch the full trace
isError	A fabricated entity is a recoverable tool error the model can correct, not a protocol failure

What MCP does not give you, and what this repo adds: nothing in the protocol binds this claim to that evidence. The protocol hands you links; the claim-to-evidence mapping and its rendering live in the host. That binding is the actual product.

Run standalone over stdio:

npm run mcp

// claude_desktop_config.json
{ "mcpServers": {
    "footnote": {
      "command": "npx",
      "args": ["-y", "@brick-byte/footnote"],
      "env": {
        "PROVENANCE_DB": "/path/to/provenance.db",
        "PROVENANCE_ACTOR": "your-name",
        // Omit for the built-in SQLite sample data.
        "DATABASE_URL": "postgres://user:pass@localhost:5432/erp"
      }
    } } }

From a clone, before the package is published:

{ "mcpServers": {
    "footnote": {
      "command": "npx",
      "args": ["tsx", "--experimental-sqlite", "/path/to/footnote/src/mcp-server.ts"],
      "env": { "PROVENANCE_DB": "/path/to/provenance.db", "PROVENANCE_ACTOR": "your-name" }
    } } }

Try these in the demo

Question	What it shows
How much does Bergmann owe?	Every figure clickable to the invoice behind it
Is Bergmann Logistik at risk?	An interpretation with separately cited premises
Show me the receivables aging	Portfolio aggregation, computed in SQL
How much does Acme Corporation owe?	Fabricated entity → refusal with real alternatives
What will revenue be next quarter?	Unroutable → refusal rather than improvisation

Toggle "show what this looks like when the model produces the numbers itself" for the contrast: identical formatting, fluent prose, every figure wrong, nothing in the output marking which.

Layout

migrations/001_init.sql  schema + seed, shared by both backends and Docker
src/database.ts     the Db seam — SqliteDb and PostgresDb behind one interface
src/db.ts           opens the ERP database, applies the migration
src/operations.ts   the catalog — the model's entire callable surface
src/compose.ts      slot-filling; claims and spans are emitted here
src/provenance.ts   append-only hash-chained store, export, verification
src/mcp-server.ts   MCP server over stdio
src/web.ts          demo host application
src/verify.ts       npm run verify / npm run export
test/run.ts         25 tests covering the invariants above, on both backends
docker-compose.yml  Postgres 17, seeded from the same migration

Only operations.ts writes ERP SQL, in one dialect, with ? placeholders. PostgresDb rewrites those to $1..$n, and the single expression that genuinely differs between the engines — whole days between two dates, julianday() on SQLite, date subtraction on Postgres — is named daysBetween on the Db interface rather than inlined. That is the one place a port can silently change a number, so it is isolated and the suite asserts the same day counts on both.

Status and limits

v0, and honest about scope.

• You cannot add provenance to someone else's AI. If the answer comes from SAP Joule or Dynamics Copilot, you have no access to their retrieval pipeline or rendering. This approach applies to AI layers you build yourself over business data.
• Vendor citations exist but stop short. As of August 2026, SAP, Microsoft, NetSuite and Salesforce all ship citations that resolve to knowledge content — help articles, PDFs, documentation. None ships a general mechanism binding a figure to the transaction behind it. Numeric answers are the weakest link everywhere.
• The demo's intent routing is deliberately naive keyword matching, so the project runs with no API key. In a real deployment the model emits the tool call and this code still fills the slots. The architecture is the point, not the routing.
• Writes are out of scope. In an ERP a fabricated read is embarrassing; a fabricated write corrupts a ledger. Writes belong behind a proposal → validation → confirmation flow.
• Retention, access control, and a real deep-link resolver for a specific ERP are the last mile — and the last mile is where the actual product lives.

Prior art worth knowing

• OpenTelemetry GenAI semantic conventions — spans for GenAI clients and MCP. Early; stops well above record-level provenance.
• OpenLineage — dataset and job lineage. Same idea one layer down, for tables rather than claims.
• LLM observability — Langfuse, LangSmith, Arize, Datadog. Tracing for engineers debugging apps, not provenance for the person reading the answer.

License

MIT.