Gateway Module — `knowledge-graph/`

1. Purpose

The knowledge-graph/ module (AK-347) stores temporal subject–predicate–object triples about entities — location, employment, affiliation, role, family, temporal, financial facts — with validity intervals (valid_from/valid_to) so a fact can be soft-closed ("invalidated") rather than deleted, preserving history. It is an internal repository surfaced two ways: (1) as position 10 of createContextLayer, where it enriches RAG context assembly with entity facts; (2) via the MCP kg_* tools. Its own Express router exists in the source tree but is not mounted in the production app (see §3). It also ships a vault scanner that can derive triples from vault-note frontmatter + wikilinks.

2. File Inventory

3. Public API Surface

REST Endpoints

No live HTTP surface in production. routes.ts defines a createKGRouter with six handlers (POST /add, PUT /invalidate, POST /query, POST /timeline, GET /predicates, GET /stats) — but createKGRouter is never imported or mounted in server/index.ts. Only createKGRepository is imported (line 44) and passed as position 10 of createContextLayer (line 497). The router is exercised only by test/knowledge-graph-routes.test.ts, which mounts it on a standalone test app. These routes do not answer on the live gateway.

MCP Tools

The knowledge graph's write/read surface reaches clients through the MCP server (mcp/index.ts), which exposes eight tools (four semantic + four _raw twins), each with D4 admission constraints (.max(256) length cap, control-char strip, predicate regex):

DIVERGENCE (flagged, HIGH — see §9): the MCP tools gatewayFetch to /api/knowledge-graph/*, but that prefix has no router mounted in index.ts. As statically read, these MCP tools would 404 against the production gateway. Not runtime-verified in this audit — flagged for Phase 2 triage.

4. Internal API

• createKGRepository(db): KGRepository — addTriple, invalidate, queryEntity, timeline, getPredicates, stats, deleteBySource, getSubjects. This is the live surface (consumed by createContextLayer position 10 for entity enrichment during RAG assembly — see test/context-kg-enrichment.test.ts).
• vault-scanner.ts: createVaultScanner, generateTriples, parseFrontmatter, extractWikilinks, VaultScanResult/VaultScanner interfaces.

5. Background Services

None wired. The vault scanner is invocable but not scheduled or called from index.ts.

6. Data Contracts

• Enums: PredicateCategory (location/employment/affiliation/role/family/temporal/financial/custom), Confidence (high/medium/low), ObjectType (entity/literal), LinkType (6 values — shared with cross-references).
• AddTripleInputSchema (subject/predicate/object/object_type + optional validity/confidence/source), InvalidateTripleInputSchema (by id OR by subject+predicate+object), QueryEntityInputSchema (entity, as_of, predicate, limit ≤200), TimelineInputSchema, RebuildInputSchema.
• KGTriple, KGPredicate (with bidirectional + inverse_predicate).

7. Dependencies

• Gateway modules consumed: shared/ (formatZodError, used only by the unmounted router); consumed by context/ (position 10). types.ts is also imported by the cross-references/ module.
• External libraries: better-sqlite3, express (router only), zod.
• Environment variables: VAULT_ROOT (vault scanner, when invoked).

8. Test Coverage

9. Known Limitations

• Unmounted router / MCP path mismatch (HIGH): createKGRouter is not mounted in index.ts, yet the MCP kg_* tools fetch /api/knowledge-graph/*. Either the router must be mounted or the tools re-pointed. The routes.ts + its 19-case test are effectively dead relative to production. Flag for triage.
• createVaultScanner is unwired dead code: coverage (lcov.info) shows FNDA:0 — never invoked in tests or index.ts; referenced only in depmap.yaml. The vault→triple ingest path exists but nothing drives it.
• The live surface is read-only enrichment (context assembly); no production write path to the KG exists today unless the router is mounted.

10. Change History