Vendor-Neutral Knowledge Architecture

Status: working memory Date: 2026-05-23

Purpose

CareerVector needs one shared knowledge system that Wiki, QA, Ops, Status, and JobCache can all use without coupling the graph to Axiom, CircleCI, Cloudflare, GitHub, Pulumi, or any future provider.

The rule is simple:

Vendor APIs feed normalized evidence. They do not define the graph.

Layer Model

human/agent/API action
  -> typed domain operation
  -> domain source store
  -> semantic claim/backing ledger in D1
  -> GraphDB projection
  -> API/MCP/UI graph reads

For external systems:

vendor API
  -> connector adapter
  -> normalized observation/backing
  -> domain mapper/rule
  -> event/anomaly/infra/journal/qa object
  -> semantic claim/backing ledger
  -> GraphDB projection

Responsibilities

Domain Source Stores

Domain stores own payload truth:

  • Wiki Markdown owns durable ideas, behaviours, journal notes, runbooks, and file-backed explanations.
  • QA D1 owns behaviours, suites, tests, test catalog, dispatches, runs, and quality evidence.
  • Ops D1 owns infra objects, internal events, anomalies, rules, operator actions, provider observations, and normalized status snapshots.
  • Git owns file-backed artefacts and checkpointed source truth.
  • R2 owns larger raw evidence snapshots and artifacts when they are too large or too vendor-shaped for D1.

Connector Adapters

Connectors are the only place provider APIs leak in.

Examples:

  • Axiom connector emits normalized log/metric/trace observations.
  • Cloudflare connector emits normalized runtime, quota, binding, D1/R2, Worker, and AI Gateway observations.
  • CircleCI connector emits QA run, job, workflow, runner, and artifact evidence.
  • Pulumi connector emits desired/deployed infra observations and drift signals.
  • GitHub connector emits commit, branch, release, and workflow context.

No UI, MCP tool, rule, graph query, or GraphDB projection should know Axiom APL, Cloudflare GraphQL shape, CircleCI response shape, or Pulumi internals.

Normalized Observations

Provider data enters as provider-neutral observations before it becomes a CareerVector hub object.

Useful common fields:

  • observation_id
  • provider
  • connector
  • source_kind: log, metric, trace, cost, quota, deploy, runtime_status, ci_run, iac_state, artifact, manual
  • subject_ref: internal object candidate, if known
  • external_ref: provider ID/URL/query reference
  • observed_at_ms
  • valid_from_ms
  • valid_to_ms
  • severity
  • summary
  • content_hash
  • raw_ref: R2 URI, provider URL, or compact D1 payload reference
  • schema_version

Observations are not graph nodes by default. They back graph nodes and edges.

Semantic Claim Ledger

D1 semantic_nodes, semantic_edges, and semantic_backing should be treated as a claim ledger, not as the graph database.

It answers:

  • Which internal hub node exists?
  • Which sanctioned edge claim exists?
  • Which file, DB row, provider observation, or generated artifact backs it?
  • Which API/MCP/user/system wrote it?
  • Has it been projected to GraphDB and/or checkpointed to Git?

It should not grow into a traversal engine.

GraphDB Projection

The configured GraphDB provider receives only the internal graph. Today that provider is FalkorDB through the RESP/Cypher adapter, but the graph contract is CareerVector-owned:

  • hub kinds: idea, behaviour, implementation, suite, test, anomaly, infra, event, journal
  • sanctioned relations: IMPLEMENTS, REALIZES, VERIFIES, BELONGS_TO, CHECKS, VIOLATES, CHALLENGES, RAISES, SUPPORTS, CONSTRAINS, EXPLAINS, INTERPRETS, TOUCHES, RELATES_TO
  • compact properties needed for graph reads
  • backing summaries and source references, not raw vendor payloads

GraphDB should answer graph questions:

  • What is connected to this object?
  • Which paths explain this object?
  • Which behaviours/tests/infra are nearby?
  • Which anomalies cluster around the same expectation?
  • Which graph objects match this text or future embedding query?

Vendor-Neutral ID Rule

Internal node IDs should describe CareerVector meaning, not provider identity.

Good:

  • infra:worker:careervector-ops-api
  • infra:d1:careervector
  • event:deploy:careervector-ops-api:2026-05-23
  • anomaly:quota-pressure:cloudflare-workers:2026-05

Bad:

  • axiom:dataset:cv_telemetry
  • cloudflare:account:abcd
  • circleci:workflow:uuid

Provider IDs belong in backing rows and observation records. That way replacing Axiom with another event/log provider changes the connector and observation mapper, not GraphDB node identity or edge semantics.

Event, Anomaly, And Infra Boundary

Raw provider rows are not CareerVector events.

An internal event is a meaningful operational fact accepted by our domain: deploy happened, migration ran, quota warning crossed threshold, incident started, recovery action executed, provider outage affected us.

An internal anomaly is a judgement that observed behaviour mismatches an expected idea or behaviour.

An internal infra object is the substrate or capability that supports or constrains implementations.

Provider observations can back all three, but they do not replace them.

Runtime-Editable Rules

Rules should operate on normalized observations and internal objects, not raw vendor payloads.

Initial rule shape should be constrained and data-driven:

  • match observation/provider/source_kind/severity/subject
  • threshold numeric fields
  • require time windows and debounce
  • map output to event, anomaly, or infra update
  • attach backing automatically

Avoid arbitrary runtime code until the audit/replay story is strong.

Object View API

Every important object should have one object-view endpoint that composes:

  • domain payload
  • semantic node
  • GraphDB neighborhood
  • backing records
  • provider observation summaries
  • Git/file refs
  • QA coverage
  • related events/anomalies/journal entries
  • sync/projection status

This keeps GraphDB compact. The full object view is an API composition, not a giant GraphDB node property bag.

Operational Safeguards

  • Every external write goes through D1 first, then Git/GraphDB/provider side effects.
  • Every projector write is idempotent.
  • Every sync has status, last error, retry count, and projection version.
  • Deletions are tombstones first; projection cleanup follows.
  • GraphDB outage must not block API writes.
  • Provider outage must not invent healthy state; mark stale/degraded.
  • Secrets and raw PII never enter GraphDB properties.
  • Large raw payloads go to R2 with hashes; D1 stores compact indexes.
  • Connector tests use golden normalized fixtures so replacing a vendor does not rewrite graph tests.

Product Shape

The user-facing products remain simple:

  • Wiki explains and edits file-backed knowledge.
  • QA owns behaviour, suites, tests, dispatches, and quality evidence.
  • Ops owns infra, internal events, anomalies, rules, and operational response.
  • Status publishes a sanitized trust readout.
  • JobCache remains a sibling product with its own depth and summary connector.

They are not separate graphs. They are different operating views over one vendor-neutral knowledge spine.

Source: wiki/content/working-memory/vendor-neutral-knowledge-architecture.md