trusted-knowledge-graph

A knowledge layer a lawyer can act on and an AI can stand on. A legal-shaped estate, a graph anchored to systems of record rather than scraped out of text, and one resolver that decides what a given person may see before any evidence is assembled — and writes down what it decided.

  SYSTEMS OF RECORD      R2RML       THE GRAPH            THE RESOLVER               WHO ASKS

  practice mgmt ─┐                 spine: matters,      1 plan  2 terms  3 route    demo screens,
  CRM            ├─► mappings/ ─►  clients, people      4 bind                      one per person
  HR             ┘                 + facts with         5 DECIDE ◄── OPA ◄── barriers.yaml
                                     their lineage      6 passages ◄── index        Claude Code,
  documents ──► extraction ──────►                      7 compose or refuse  ◄───── one MCP server
                                                              │                     per person
                                                              ▼
                                                  one hash-chained record per request

Everything below runs, make gate passes, and every number comes from a report the run wrote. Extraction and the vector path's answers and verdicts are Claude (claude-opus-5-5, low effort), committed as fixtures — the demo needs no key and no network.

make build && make up-stores && make load && make policy   # first run
make up          # the resolver, a start page and one demo screen per person — make web-links
make demo        # the scenes, asked as the personas, through the resolver
make reports     # eval, leak, glossary, audit and extraction reports from a fresh record
make gate        # the deploy gate — non-zero on any failure

Honesty statement

Written before the numbers, and it stays at the top.

• No real firm, no real person, no real client, no real matter. The estate is invented and generated deterministically from config/estate.yaml. Nothing here is legal advice or a statement about any organisation.
• This is not production experience. It is a pattern, implemented and measured.
• Laptop scale. Around 400 matters and 772 documents — not 1.2 million. No throughput claim, no cost claim, no latency claim is made anywhere.
• Identity is asserted, not federated. Each persona's MCP container holds a key and mints a short-lived assertion; the resolver verifies it. In the design this is the OAuth on-behalf-of flow against a real identity provider. This is the one place the lab is weaker than the architecture it demonstrates, and anyone who can read secrets/ can be anyone. (ADR 0011)
• Claude is not in the barrier suite. The suite asks through the same HTTP boundary Claude uses, as each person; it does not test what a language model says about the answer. That the boundary holds is measured. That a model reports it faithfully was observed, not measured.
• The hash chain is tamper-evident, not tamper-proof, and it cannot show that its tail was cut. make verify-audit prints the head hash so it can be held elsewhere. (ADR 0012)
• Apache Jena Fuseki and OPA are lab choices. OPA is the component the design names; Fuseki is a real quad store rather than an embedded library. Neither is a recommendation for any particular production estate.
• Do not expose this stack to a network. Every port binds to loopback, and the stores have no authentication because they are not reachable.
• The documents are template-written, from the estate. Their prose is more regular than a firm's, so extraction scores are an upper bound; the method is what transfers.
• Two verdicts are a model's. The vector path's answers are composed by Claude and graded by Claude against a truth computed from the estate; both are committed with their reasons. Leaks are counted mechanically and need no judge.
• A presigned link is a bearer token for five minutes. Anyone its holder forwards it to can open it until it expires.
• Authored AI-assisted, with the design record in docs/decisions/ leading the code, as in the sibling labs.

What it shows

The same question, two people

Mara, a partner, asks whether the firm has advised a Dutch fund manager on an AFM investigation since 2021, who led it and what the outcome was. She gets five matters, each citing the system it came from — two outcomes confirmed, one unconfirmed and saying so, and two matters with no outcome, because none was recorded and the answer does not invent one. Sanne, screened from one of those matters, asks the identical question and gets four, and is told one matter and one derived fact were withheld under rule B-03, with its owner and the date it was set.

Three refusals, and why each is the right one.

Sanne asks	Outcome	Why
Who led M-2022-0117?	refused	direct: the matter is behind B-03
Who has led the most AFM investigations?	refused-aggregate	a count over a set she cannot see in full is wrong in a way she could not detect
What expertise is recorded for Mara?	one fact of two	the other names no matter — it was derived from one, and lineage decides

The third is the case the design exists for. The withheld fact is about a person, not a matter; only its lineage, over prov:wasDerivedFrom+, connects it to the restricted matter — and that is enough.

Decide, then retrieve. The resolver asks the graph which matters and derived graphs a question would reach, asks OPA which of those this person may see, and only then runs the query — bound to the permitted set. The query that produces evidence cannot name a denied matter. Nothing is filtered afterwards. (ADR 0009)

One rule file, checked against the firm's own records. config/barriers.yaml is the only place an access rule is written. It compiles to the data OPA evaluates, and the compiler refuses to write a policy when a rule and the practice-management system's restriction records disagree. Insiders are referenced from the matter team, never copied. (ADR 0007)

Disclosure is a policy decision with an owner. Whether a screened person is told that something was withheld is disclosure: in barriers.yaml — both modes are implemented, and the caller cannot choose. A refusal is itself a one-bit disclosure; that is stated, not discovered. (ADR 0010)

Words are not the model's to interpret

"Active client" means four different things to four owners — a client with an open matter (the practice groups), invoiced in the last year (Finance), in the CRM with a relationship partner (BD), ever acted for (Risk, because a conflict check needs former clients). Four numbers. resolve_term("active client") returns all four with their owners and counts; a question that names the term without choosing a reading is refused at the router, with the readings listed back. Asked through Claude Code, the model does what the refusal tells it: shows the readings and asks which one. (ADR 0015)

Words fill slots, not guesses. "AIFM" resolves to the fund-manager client type; "AFM investigation" to a regulatory investigation in the Netherlands — with the caveat, in its definition, that the lab records jurisdiction, not the regulator. An answer records which glossary terms it rests on, and their owners.

Reuse by mapping. The firm's practice areas and matter types are mapped to SALI LMSS with SKOS relations that say how close each is — none is an exact match. The subset is imported from a pinned commit, and the namespace was read from the release rather than assumed: it is http://lmss.sali.org/, not the https://sali.org/ one would guess. (ADR 0016, reports/glossary.md)

Every answer says how it was routed. graph · index · hybrid · refuse, with the reason. If the index is not reachable, a question that needs passages is refused and says so. (ADR 0017)

Documents, the index, and what a document cites

Documents with a gold set. 772 documents — engagement letters, advice memos, closing letters, and thirty knowledge notes — written from the ground truth, rendered to PDF and read back, each recording the facts it was generated to carry. Outcomes exist only in closing letters and in the notes that cite them, as in a firm. That manifest is what extraction is scored against (ADR 0020).

Two enforcement points, one policy file. The PDFs sit in a document store with one user and policy per person, compiled from the same barriers.yaml as OPA's data. The graph refuses the fact; the store refuses the bytes, on its own policy. Every citation carries a link that opens the PDF, signed with the asking person's own credentials for five minutes — and a link Sanne signs herself for a walled document returns 403. OPA and the store agree on every person × document pair (ADR 0021).

The index is filtered inside the query. One passage per document, BM25 and embeddings, with the permitted matters inside both clauses; passages() needs the permit. The index does hold document text — the graph holds none, the index holds permission-trimmed passages, the store holds the bytes (ADR 0022).

The comparison — against the baseline a firm would actually run. With no filter at all, asked "what was the outcome of the AFM investigation into Rhine Capital Partners?", the vector path returns the closing letter of the matter Sanne is screened from, first. That is a weak baseline: a DMS already filters by matter, and with a document-level ACL those leaks go away — no document in the corpus mentioned another matter. So the corpus has what a firm's does: knowledge notes, filed on an open matter, citing a walled matter's file number, client and outcome. The DMS opens the note, because it sits on an open matter, and a document-level ACL passes it. Asked "what precedent do we have on AFM settlements for fund managers?", the vector path behind a document-level ACL put a walled matter's outcome in front of the model on 16 of 16 questions; with no filter, 16 of 16; the resolver, 0 of 16.

A document inherits the matters it cites. A note's extracted graph is derived from every matter it cites, so its facts — and the note — are walled wherever any cited matter is. The index stores every matter a passage depends on and the resolver's filter needs all of them permitted (terms_set, inside both clauses); CQ-10 does not list, link or pass a note citing a matter the person cannot see, and counts it as withheld by lineage. The document store is left as a DMS is: it does not know what a document cites, and the leak report says so — the store is weaker than the graph on 15 documents; the gate fails only if the graph is ever broader (ADR 0028).

The record and the boundary

Every request writes one line to audit/decisions.jsonl, once, at completion, answered or refused, chained by hash. The audit log of a barrier system is itself confidential: a record saying Sanne was denied M-2022-0117 would tell its reader what the barrier hides. So denied identifiers are salted hashes in every field — including the slot she typed — and free text is not logged at all. explain(trace) reads the stored record: the live explanation and the later one are the same object. (ADR 0013)

The record has its own access model. OPA decides who may read it, from a rule in barriers.yaml: Risk & Compliance, nobody else. Risk resolves the salted hashes and answers the three questions — who has ever been shown anything derived from M-2022-0117, what did Sanne see, why was that trace refused — and gets the same grounds Sanne was shown at the time, from the same record. Risk sees no matter content, and Risk's own reads go into the same chain. (ADR 0018, reports/audit.md)

The boundary. One MCP server per person, started as that person, holding only that person's key, on a network where the resolver is the only other service. No tool takes a persona. There is no document() tool. passages() needs the permit ask() issued, to the same person.

Holding it to account

The battery and the gate. Thirty-four questions with known answers, computed from the estate rather than the graph, asked both ways and scored four ways — correct, refused, confidently wrong, leaked (ADR 0025). make gate holds the policy, the suite, the two enforcement points, the record and the eval to a baseline, and exits non-zero on any failure (ADR 0026).

Review. tkg review list|confirm|reject — through the resolver, as the reviewer, on the record. A review is its own graph derived from the fact's, so it is walled wherever the fact is; answers stop asserting a rejected fact.

An open decision: aggregates over walls. Refusing an aggregate over a set you cannot fully see is right for "who has the most AFM experience". For a firm-wide count it means nobody gets an answer: every lawyer in the lab is walled from something the Finance and Risk readings of "active client" count, so both are refused for all three of them. In a real firm, with hundreds of need-to-know matters, every firm-wide metric would be. The options and their side channels are in ADR 0019 — an open decision, for the firm, not the lab.

What was cut — text-to-SPARQL, OPA's log as a second stream, the Ontop test, Splink, the public corpus, the HTML workbench — is listed with what each costs in ADR 0024.

The numbers

From reports/eval.md — thirty-four questions, both paths:

path	correct	refused	confidently wrong	leaked
graph-grounded, through the resolver	34	0	0	0
vector, behind a document-level ACL	10	2	9	13
vector, no filter (retrieval only)	—	—	—	13

The vector path's leaks are counted mechanically — passages placed in its context from a walled matter, or from a document citing one — and need no judge; its other verdicts are Claude's, graded against a truth computed from the estate, with reasons, in data/fixtures/eval-vector.jsonl. Five of the graph path's answers are right but incomplete: outcomes no document or partner recorded, which the answer does not invent.

From reports/extraction.md — 772 documents, extraction scored against the manifest, subject included:

confidence ≥	precision	recall
0.5	0.96	0.98
0.9	1.00	0.86

Outcomes: precision 1.00, recall 1.00. Citations (citesMatter): precision 1.00, recall 1.00 — which is why the walls around the notes held: lineage is only as good as the citations extraction finds. The misses that remain are real ones: 50 clients named as the CRM spells them stay unlinked — identity resolution is cut (ADR 0024) — and the model infers a jurisdiction from the regulator's name at low confidence, which the document never states. The documents are template-written, so read these as an upper bound. The first three runs of this report found the gold set wrong, not the model: templates that stated a fact the manifest did not credit, and one that was credited with a fact it did not state. The manifest now records exactly what each document says.

From reports/leak.md, generated by make leak:

questions asked — every rule × every persona × direct / second hop / lineage / aggregate / documents, precedent notes, the glossary path, passages	250
… where the persona is denied the matter	64
leaked	0
wrong refusals, including over-refusals of matters the persona may see	0
doors behaving — the permit, and the record only Risk may read	19 / 19
audit records checked for a denied identifier in clear, including Risk's own reads	254 — 0 found
person × document checks, the graph against the document store	3,860 — 0 where the graph is broader
… documents citing a walled matter that the store opens and the graph withholds	15 (a finding)
walled documents fetched with the walled person's own credentials	15 — all refused

Who should be denied is computed from barriers.yaml and the systems of record directly, bypassing both the policy compiler and OPA. That independence was checked by breaking it: with Sanne's screen removed from the compiled policy only, the suite reported six leaks, two wrong refusals and fourteen clear-text identifiers in the log — a check run by hand, not a committed test. An earlier version read the compiled policy for its expectations — and passed the tampered one, because it agreed with itself.

What the first Claude Code session found. A persona's description, returned by whoami(), named the matter she is screened from. The suite had never looked at whoami(). It does now, and the description no longer does.

Principles

• The systems of record are a database, not CSV exports, so the spine is built by declarative R2RML over live tables, read through a role that cannot write back.
• SHACL is the load contract. A load that violates the shapes does not land — including the rule that no literal exceeds 500 characters, because the graph holds assertions and identifiers, never document content. The shapes also refuse a fact without a source, confidence and review state, and a derived graph without lineage.
• The model does not write SPARQL. Questions are templates bound to competency questions, and every template declares every graph it touches.
• The mess is in the data, on purpose: the same organisation spelled differently in the practice-management system and the CRM, and colleagues sharing a family name.

Running it on a Docker host

The lab is deployed by hand to a Docker host, and nothing on it is exposed: every port binds to the host's loopback. There is no CI; the gate is a command.

ssh host 'git clone https://github.com/fps4/trusted-knowledge-graph && cd trusted-knowledge-graph \
  && make build && make up-stores && make load && make policy'
ssh -L 8480:127.0.0.1:8480 host      # the resolver, if you want it from here

Claude Code stays on your machine. The MCP container — and the persona's key — stay on the host, reached over ssh:

make mcp-configs HOST=host           # writes mcp/<persona>.json locally
claude --strict-mcp-config --mcp-config mcp/sanne.json

Using it from Claude Code

make init writes one MCP config per person, for a stack on the same machine. One session, one person:

claude --strict-mcp-config --mcp-config mcp/sanne.json

A single .mcp.json listing everyone would give one session every person's tools at once, which is exactly the boundary the demo is about — so there isn't one.

The demo UI

One screen per person — web-mara, web-sanne, web-kim, web-risk — each a container holding only that person's key, on the network where the resolver is the only other service. No login and no switcher: the window is the person. A static start page on :3100 introduces the lab, its architecture and decisions, and links to each screen. make up starts them all; make web-links HOST=<host> prints the tunnel and the URLs:

ssh -N -L 3100:127.0.0.1:3100 -L 3101:127.0.0.1:3101 -L 3102:127.0.0.1:3102 \
       -L 3103:127.0.0.1:3103 -L 3104:127.0.0.1:3104 -L 9100:127.0.0.1:9100 host
# Start http://127.0.0.1:3100 · Mara :3101 · Sanne :3102 · Kim :3103 · Risk :3104

9100 is the document store: the PDF links are signed by the resolver, with the person's own credentials, for that address — there is no route in the UI that fetches a document.

• Chat — Claude through the Anthropic API (claude-opus-5-5, low effort), with the MCP server's tools and instructions. Needs ANTHROPIC_API_KEY in .env.
• Guided — pick a competency question, fill its slots, look words up in the glossary, ask. No model, no key.
• Inspector, for the selected answer: Trace (route and why, terms and their owners, template, slots, policy version, trace id) · Explain (the rule, owner, date, file; blocked directly vs by lineage) · Sources (PDFs, and passages under the answer's permit) · Lineage (fact graph → document → matter; told facts → who told them; spine → system of record and its mapping) · Record (the same grounds, read back from the chain).
• Risk's screen opens on the record: who was shown anything from a matter, what a person saw, one trace in full — and whether the chain is intact, with its head hash.

Why it is built this way, and what it does not change about ADR 0011: ADR 0027.

Layout

config/estate.yaml	the whole synthetic firm, including the deliberate mess
config/barriers.yaml	the only place an access rule is written — owner, dates, disclosure
config/people.yaml	who can ask; what they are comes from HR, not from here
config/asserted.yaml	facts told by a named partner, each with its lineage
config/audit.yaml	what the record keeps, hashes, omits, and for how long
config/glossary.yaml	business terms, owners, readings, what an ambiguous term gets
config/sali-mapping.yaml	the firm's vocabularies against SALI LMSS, pinned
config/relations.yaml	who owns each relation, and whether it states the present or a date
vocab/	the imported SALI subset, with provenance — docs/sources.md is the register
config/battery.yaml	thirty-four questions, each with how its truth is computed
data/fixtures/	the documents and their manifest, the extraction, the vector path's answers and verdicts
sql/, mappings/	the systems of record, and R2RML over them
ontology/	a small OWL profile, and the shapes that gate every load
policy/access.rego	the policy — hand-written, with opa test cases
build/opa/data.json	the policy's data, compiled from barriers.yaml — generated
src/tkg/resolver/	the seven steps, and the HTTP API they sit behind
src/tkg/access/	compiler, lineage, OPA client, permit
src/tkg/audit/	the chained writer, salted hashes, verification
src/tkg/mcp/	one MCP server per person
src/tkg/semantic/	templates, the glossary resolver, the router
src/tkg/dms.py, src/tkg/index.py	the document store and the index
src/tkg/ingest/	estate, documents, extraction, linking, the load pipeline
src/tkg/eval/	the barrier suite, the battery, truth, extraction scoring
web/, docker/web/	the demo screen — one container per person, Next.js, a BFF that calls the resolver as that person
web/landing/	the static start page, About, and Architecture & decisions
reports/	eval.md, leak.md, glossary.md, audit.md, baseline.json — generated, never typed
docs/decisions/	twenty-eight ADRs, written before the code they justify — one still open

MIT.