Knowledge Hub Control Plane

Status: MVP runtime wired into Wiki, QA, Ops, and QA/Ops MCP Date: 2026-05-22

The right-edge Hub control is not a decorative Git/GraphDB badge. It is the operator view over the persistence control plane for write-capable perspective surfaces.

Contract

The order stays fixed:

  1. API first
  2. MCP second
  3. UI third

Every surface should expose the same shape:

GET  /hub/status
POST /hub/checkpoint
POST /hub/graphdb/verify
POST /hub/graphdb/sync
POST /hub/graphdb/keepalive

The /hub/falkor/* routes remain compatibility aliases for the current FalkorDB provider adapter.

SvelteKit UI apps may proxy those routes through same-origin /api/hub/* endpoints, but the durable contract belongs to the API worker wherever that surface has an API worker.

Write Path

The intended write path is:

human or agent action -> API typed operation -> product DB -> materialized graph -> Git checkpoint for file-backed artefacts

DB rows are the live operational truth for writes. Git is the durable source or checkpoint archive for file-backed artefacts: Wiki Markdown, QA behaviour/suite sources, Ops runbooks, incident notes, and graph annotations. GraphDB is a rebuildable materialized graph projection, not the source of truth.

Admin Boundary

Auth is outside this runtime. Wiki, QA, Ops, MCP, and future admin callers should be treated as already authenticated once they reach these APIs. Inside that boundary the system is a trusted DMZ: no per-route fake auth, no permission theatre, and no special restrictions justified by auth being "out of scope".

That does not remove the need for typed operations, validation, audit rows, and deterministic side effects. Those are product and operations constraints, not security boundaries. A broader Git or GraphDB admin capability should still land API first, then MCP, then UI, with D1 audit evidence before external effects.

Current MVP Runtime

  • QA API exposes /v1/hub/status, /v1/hub/checkpoint, /v1/hub/graphdb/verify, and /v1/hub/graphdb/sync, with FalkorDB aliases.
  • Ops API exposes /hub/status, /hub/checkpoint, /hub/graphdb/verify, and /hub/graphdb/sync; Ops also owns /hub/graphdb/keepalive for the scheduled near-zero-load GraphDB provider PING, with FalkorDB aliases.
  • Wiki exposes same-origin /api/hub/* endpoints backed by the same shared runtime and the main CareerVector D1 binding.
  • QA MCP and Ops MCP expose get_knowledge_hub_status plus run_knowledge_hub_action.
  • The shared HeaderBar Hub control reads the status endpoint and enables Git checkpoint, GraphDB verify, and GraphDB sync only when the backing secrets and bindings are present.

The MVP action set is intentionally small and deterministic. Git checkpoints write one fixed runtime JSON file per perspective under wiki/content/working-memory/knowledge-hub-runtime/. GraphDB sync writes the Hub runtime event/implementation nodes and their relationship; broader graph rebuilds still belong to the graph pipeline. This is the first typed surface, not the final permission model.

Graph metadata edits follow the same rule. The live write is a D1 overlay row; POST /api/wiki/graph/metadata/flush reads the backing Git file, checks the overlay's base source hash, writes supported file-backed claims back into that file, and marks those rows flushed. The first supported writers are Markdown frontmatter, inline @graph blocks, and QA suite YAML comments. Typed .graph.ts projection modules and DB-backed QA/Ops rows stay pending until their dedicated writers exist.

Runtime Executors

Git checkpoint uses the GitHub Contents API. That keeps it API-first and avoids running local git inside a Cloudflare Worker. Each checkpoint records a D1 event first, writes the fixed JSON artifact, then records the resulting commit metadata back into D1.

GraphDB verify and sync use the Worker TCP socket runtime through node:net under nodejs_compat. The current worker speaks RESP directly to FalkorDB for the small typed Hub graph operations. Failed remote operations are also recorded in D1 so the header can stay honest.

The keepalive path is intentionally not a graph operation. The Ops API scheduled worker runs it twice daily and sends only Redis PING; it records a tiny D1 row for audit if D1 is available. Wiki and QA do not schedule their own keepalives, so the GraphDB provider receives one protective nudge per 12 hours, not per surface.

Source: wiki/content/working-memory/knowledge-hub-control-plane.md