Orchestrata Ultimate › Plans › kg-schema-gaps
KG Schema Gaps — SPEC-008 (audit + remediation plan)
Source: plans/kg-schema-gaps.md at 8a2cb42ad · last changed 2026-07-27 · first committed 2026-07-05 · 41 lines.
Prose pending.
Plan text
KG Schema Gaps — SPEC-008 (audit + remediation plan)
Source: read-only subsystem map (this session). Scope = SPEC-008 Neo4j KG only.
SPEC-105 is out of scope here — it is the separate orchestrata_ultimate/domaingen/
module (OWL/Turtle → domain code + SHACL constraints.ttl + Stardog SPARQL). All 50
REQ-105-* are [x] and covered by tests/domaingen/test_domaingen.py. Do NOT conflate its
SHACL NodeShapes / Stardog with the Neo4j schema.
Structural root cause: split-brain schema
Two divergent definitions of the KG vocabulary exist:
knowledge_graph/types_enums.py—NodeType/RelationshipTypeenums (vestigial: the semanticNodeTypemembers are never used;RelationshipTypereferenced only twice).knowledge_graph/schema.py—LABEL_*/REL_*string constants = the REAL Neo4j vocabulary (DDL,get_node_label, all writers/queries). A prior "W5" pass added the semantic layer here but never back-ported it to the enums.ensure_schema(neo4j_client.py:122-133) correctly applies CONSTRAINTS/INDEXES/FULLTEXT.
Ranked gaps
| # | Item | Where | REQ | Type | Size | Decision? |
|---|---|---|---|---|---|---|
| 1 | Task node type missing everywhereLABEL_TASK (re-exported from canonical_schema), NodeType.TASK, task_id uniqueness constraint (schema.py:172) and task_status index (schema.py:202) all landed. |
schema.py, types_enums.py | FR-001 / REQ-008-006 | resolved | — | no |
| 2 | ~10 provenance edges defined but ZERO writers — OWNS, OWNED_BY, PART_OF, REQUIRES, WORKED_ON, WORKED_ON_BY, MADE_BY, ASSIGNED_TO, SUPERSEDES, DERIVED_FROM; Component node never written, so query_engine.volk_work_context (query_engine.py:201, queries (v)-[:OWNS]->(c:Component)) is always empty |
schema.py:91-101 | FR-002 | unwired | M–L | yes — where do writers live + what populates Component? |
| 3 | Rel types missing under any name: WORKED_ON_BY, REQUIRES, OWNED_BY, WORKED_ON |
schema.py:61-101 | FR-002 | missing-type | S | no |
| 4 | types_enums.py NodeType/RelationshipType now carry Task/Component/Volk + the semantic rels, re-exporting canonical_schema values (single source of truth) with drift-lock tests in test_types_enums.py; landed c980f8af. This ruling is binding — do not re-open reconcile-vs-retire. |
types_enums.py | FR-001/002 | resolved | — | decided: reconcile |
| 5 | Task-in-progress + true component-ownership reusable query not runnable (spec's flagship Cypher) | spec.md:333-338 | FR-004/US-003 | missing-query | S (after 1–3) | no |
| 6 | HAS_FUNCTION spec-name absent (impl uses HAS_METHOD); MADE_BY only as reverse MADE |
schema.py:81,97 vs cql:194 | FR-002 | naming | S | yes — rename vs add alias |
| 7 | Session uniqueness constraint absent — deferred ("W5b"), and test_schema.py:85 asserts its ABSENCE |
schema.py:120-121 | FR-003 | missing-constraint | S–M | yes — needs Session-key canonicalisation |
| 8 | Volk MERGE-key divergence (alias vs name vs volk_id) → duplicate unconstrained Volk nodes |
harness/history.py:163, harness/reporting.py:353, kernel/audit/writers.py:296 vs pipeline_kg.py:140 | NFR-004 / REQ-008-023 | integrity | S | relates to the K3 volk_id/agent_id divergence |
| 9 | tests/knowledge_graph/test_schema_completeness.py + test_canonical_schema_completeness.py pin the node/rel sets; drift-locks in test_types_enums.py. |
test_schema_completeness.py | Success #1 | resolved | — | no |
Suggested execution order (Opus designs, Sonnet builds)
- Low-risk, no-decision first:
#9#1(both RESOLVED — see table), #3 missing rel constants, #6 addHAS_FUNCTIONas the spec name (alias, keepHAS_METHODwriters). Each a clean build. - Decision-gated: #2 (wire provenance writers / populate Component — behavioural, needs the write-site design),
#4(DECIDED + DONE: reconcile via canonical_schema re-export — binding ruling, do not re-open), #7 (Session constraint — needs key canonicalisation + flip the test). - Integrity: #8 Volk MERGE-key — converge on one key (
alias); ties into the K3 memory volk_id/agent_id divergence.
Present + fine: code-structure layer (File/Class/Function/Predicate/Rule + DEFINES/CALLS/
INHERITS/IMPORTS/HAS_METHOD), the wired provenance sub-layer (Volk/Intent/PipelineRun/Artifact/
Decision + MADE/APPLIES_TO/GENERATED_BY/EXECUTED_BY/TRIGGERED/HAS_SESSION/JUSTIFIED_BY),
SearchEngine, QueryEngine.multi_hop/run_provenance/volk_work_context, DDL application.