Implementation Plan: Knowledge Graph Runtime

Provide a live, versioned semantic memory layer (KGS) that stores semantic artifacts and projections, supports deterministic snapshots, and powers runtime queries for agents, compilers, and UI shells.

Provenance & Traceability

Architectural Decisions (ADRs)

ADR ID	Decision Title	Impact on This Plan
ADR-004	Semantic Core Formalization	KGS is an explicit projection of the semantic core (no “magic” inference).
ADR-006	Knowledge Layer Implementation	Defines graph-first querying and storage concerns.

Product Requirements (PRDs)

PRD ID	Requirement Title	Satisfied By (SDS)	Acceptance Criteria
PRD-006	Semantic Context for AI	SDS-003	KGS query returns stable, structured context.
PRD-007	Dynamic Knowledge Discovery	SDS-003	Graph queries and snapshots work across versions.

Software Design Specifications (SDS)

SDS ID	Service/Component	Bounded Context	SEA-DSL Spec File	Implementation Status
SDS-003	Knowledge Graph Service	`semantic-core`	N/A	MVP (doc)

Provenance Chain

graph TD
  ADR4[ADR-004: Semantic Core] --> PRD6[PRD-006: Semantic Context for AI]
  ADR6[ADR-006: Knowledge Layer] --> PRD7[PRD-007: Knowledge Discovery]
  PRD6 --> SDS3[SDS-003: Knowledge Graph Service]
  PRD7 --> SDS3

Architecture and Design

Design Principles Applied

Isomorphism: KGS state must be derivable from semantic inputs + applied change sets.
Invariants: Snapshot IDs are immutable; identical inputs yield identical snapshots.
Idempotency: Applying the same change set twice is safe (dedup by change-set ID/hash).

Dependency Justification

Updated 2025-12-30: Added specific dependencies from gap analysis section 1.1 (Knowledge Graph & Reasoning).

Dependency	Type	Version	NPM/PyPI Package	Justification	ADR/SDS Reference
Oxigraph	Rust Binary / Python	`0.4.x`	`oxigraph` (Rust), `pyoxigraph` (Python)	Production-grade RDF triple store with built-in SPARQL 1.1 engine. Preferred for performance.	ADR-006, SDS-003
RDFLib	Python Library	`7.1.x`	`rdflib`	Fallback RDF store for development/testing; SPARQL support.	ADR-006, SDS-003
Comunica	Node.js Library	`3.x`	`@comunica/query-sparql`	Execute SPARQL queries in Node.js for TypeScript adapters.	SDS-003
pySHACL	Python Library	`0.29.x`	`pyshacl`	Validate knowledge graph integrity against SHACL shape constraints.	SDS-003
OWL-RL	Python Library	`7.1.x`	`owlrl`	Enable logical inference over OWL ontologies (RDF reasoning).	ADR-006

Installation Commands

# Python dependencies (in pyproject.toml)
pip install pyoxigraph rdflib pyshacl owlrl

# Node.js dependencies (in package.json)
pnpm add @comunica/query-sparql

Port/Adapter Architecture

// Knowledge Graph Port (abstracts Oxigraph/RDFLib/Comunica)
interface KnowledgeGraphPort {
  querySparql(query: string): Promise<SparqlResult>;
  validateShacl(shapeUri: string, dataGraph: string): Promise<ValidationReport>;
  inferOwl(ontologyUri: string): Promise<InferenceResult>;
}

Expected Filetree

/
├── docs/specs/semantic-core/sds/003-knowledge-graph-service.md
├── tools/**                               # compilers + schema gates
└── libs/<ctx>/**/src/gen/**               # generated runtime-facing code

Proposed Cycles

Cycle	Branch	Wave	Files Modified	Files Created	Specs Implemented
C1A	`cycle/p002-c1a-kgs-contracts`	1	`docs/specs/semantic-core/sds/003-knowledge-graph-service.md`	—	SDS-003 (API & snapshot contract)
C1B	`cycle/p002-c1b-snapshot-model`	1	`docs/specs/shared/sds/001-sea-data-model-schemas.md` (if needed)	—	Snapshot + change-set schema
C2A	`cycle/p002-c2a-kgs-projections`	2	`tools/*` (projection scripts)	—	Deterministic projection & query helpers

Task Breakdown

Wave 1 (Parallel)

C1A: Specify the KGS snapshot + query contract precisely
- Implements: SDS-003 API behaviors, snapshot immutability, query surface
- Satisfies: PRD-006, PRD-007
- Files: docs/specs/semantic-core/sds/003-knowledge-graph-service.md
C1B: Ensure schemas can represent KGS snapshots + change sets
- Implements: Data model primitives needed for versioning and provenance
- Satisfies: PRD-007 (versioned discovery)
- Files: docs/specs/shared/sds/001-sea-data-model-schemas.md (only if changes required)

Wave 2 (Depends on Wave 1)

C2A: Add deterministic projection helpers (KGS → snapshot → queryable views)
- Implements: Deterministic, schema-validated projection utilities
- Satisfies: PRD-006 (stable context production)
- Files: tools/ast_to_ir.py, tools/ir_to_manifest.py (as needed), plus any new tooling under tools/

Validation & Verification

Spec Validation

Validate references in docs/specs/shared/reference/009-traceability-matrix.md for PRD-006/007 → SDS-003.

Implementation Validation

Snapshot creation is deterministic (same change set input → same snapshot hash/id)
Query outputs are stable and schema-valid for representative workloads

Open Questions

What is the canonical snapshot identifier format: UUID, content hash, or hybrid? Content hash (ifl:snap:a3b8c9d2…)
What is the minimum query surface required for “context for AI” (SPARQL only, or also a constrained query DSL)? Constrained DSL + SPARQL escape hatch
Do we need workspace isolation/merge semantics in MVP, or is that deferred to a later plan? Defer (single KG in MVP)

Risks & Mitigation

Risk	Likelihood	Impact	Mitigation Strategy
Premature “reasoning” in KGS leads to non-determinism	Medium	High	Prefer SPARQL-first, materialized projections, and explicit rules (SDS-003).
Snapshot/versioning grows too complex early	Medium	Medium	Start with immutable snapshots + linear history; add merges later.

Rollback Strategy

If versioning is too heavy, revert to “single snapshot per commit” while retaining deterministic IDs.

Reference Documents

Traceability Matrix

Linked Specifications

Type	ID	Document
SDS	SDS-003	`docs/specs/semantic-core/sds/003-knowledge-graph-service.md`