Ops GraphDB Spine TODO

Status: active working memory Date: 2026-05-23

Product naming rule

The product/API word is GraphDB.

FalkorDB is the current GraphDB provider and adapter. It is allowed in implementation names, environment variables, logs, and provider-specific docs, but shared UI, MCP summaries, and high-level API descriptions should say GraphDB so the product does not become vendor-bound.

Immediate TODO

  1. Keep deploy auth repeatable.

    • Local Cloudflare API-token env lives outside the repo.
    • Add a wrapper/runbook so deploys do not depend on stale Wrangler OAuth.
    • Never print token values.

  2. Make the Knowledge Hub GraphDB surface vendor-neutral.

    • Prefer GraphDB labels in status, buttons, MCP summaries, and docs.
    • Keep FalkorDB route aliases and env names as compatibility/provider detail.
    • Add API aliases before removing any existing Falkor-specific endpoint.

  3. Verify the production keepalive and status surface.

    • Manual keepalive already returns GraphDB PING/PONG.
    • Cron trigger is deployed at 0 */12 * * *.
    • Re-check after the next scheduled run.

  4. Classify untracked generated artifacts.

    • File-claim graph artifacts are product output once they compile against @cv/graph.
    • Ignore or remove pure generated scratch only with explicit confidence.
    • Do not disturb unrelated work from other agents.

  5. Pull the backend model forward.

    • Treat this as central, not later polish.
    • Infra is Git/IaC-backed, D1-materialized, provider-enriched, and object-first.
    • Rules are the hidden runtime-editable detector layer.
    • Anomalies are promoted harmful expectation mismatches.
    • Events are meaningful Ops facts, not raw QA/CircleCI/vendor rows.
    • Journal interprets one or more events.
    • GraphDB receives the vendor-neutral nine-hub projection, not raw provider payloads.

Backend object model checklist

  • API first: every canonical hub object must be readable by stable REST routes.
  • MCP second: MCP tools should call the REST object routes instead of rebuilding hub joins.
  • UI third: Ops/Wiki/QA should render the same object shape the API exposes.
  • Object read shape: domain payload, semantic node, semantic edges, node backing, edge backing, and source endpoints.
  • Infra sync must write both domain tables (ops_infra_*) and semantic backing (semantic_nodes, semantic_edges, semantic_backing).
  • Provider APIs stay behind adapters. Provider payloads may become backing evidence; they do not become canonical GraphDB payloads directly.
  • Runtime detector rules stay data-only JSON over normalized adapters. No arbitrary eval, no Worker code editing at runtime.
  • Anomaly promotion requires an expectation anchor: behaviour violation or idea challenge.
  • Event creation requires an origin: anomaly or infra.
  • Journal creation requires at least one interpreted event.
  • QA/CircleCI remains QA evidence and runner state, not a generic Ops event source.

Done in this pass

  • Cloudflare token validated through the API.
  • Ops API version 2005adc3-3cda-4c94-9eb0-527178b31066 promoted to production.
  • Ops API GraphDB keepalive endpoint returned 200 and PONG.
  • Cloudflare scheduled trigger deployed for twice-daily keepalive.
  • Added GraphDB product wording and /hub/graphdb/* API aliases while keeping FalkorDB provider aliases.
  • Added /graph/objects/:kind/:id as the object-first read route.
  • Infra sync now materializes IaC definitions into semantic_nodes, semantic_edges, and semantic_backing in addition to ops_infra_*.
  • /infra/sync now defaults to catalog/semantic materialization without live provider probes, so one operator action does not burn the Worker subrequest limit. Use /infra/sync?probes=1 only for an explicit deep probe pass.
  • /infra/sync?probes=1 now accepts provider, kind, and infra_id filters so operators and agents can deep-probe one safe segment while the full catalog remains materialized.
  • Ops MCP exposes sync_infra probe filters and get_graph_object, so agents can use the same object-first REST readout through MCP.
  • @cv/graph now accepts scope on source-claim nodes, so generated wiki/src/lib/file-claims/*.graph.ts files compile as product artifacts.
  • The file-claim registry now indexes the generated file-claim graphs.
  • Wiki graph dry-run succeeded with 2232 nodes and 23853 edges.
  • wiki/src/routes/api/wiki/librarian.json/+server.ts is product output: it exposes the existing Librarian query path as a stable JSON endpoint.
  • Root-level working-memory/, workers/, and wrangler.toml currently look like legacy cutover/realtime artifacts from the old repo shape. Leave them uncommitted unless a later pass deliberately migrates them into the current wiki/content/working-memory/ or relay/ structure.
Source: wiki/content/working-memory/ops-graphdb-spine-todo.md