OpenMind v2 Phase 5: canonical Engineering Knowledge Graph, candidate promotion and Knowledge Bundle 2.0 Draft

[HelloThisWorld]

What this is

Phase 5 of the v2 enterprise knowledge layer: the first canonical graph on top of the Phase 4 candidate plane. Design document: docs/v2/phase-5-knowledge-graph.md. Runtime 1.4.0-dev -> 1.5.0-dev; schema head v0005 -> v0006 (purely additive); .openmind artifact stays frozen at 1.1.0; the new Knowledge Bundle carries its own draft version 2.0.0-draft.1.

What changed

Canonical graph (openmind/knowledge/, migration v0006)

• engineering_entities with logical identity UNIQUE(workspace, entity_type, canonical_key), plus aliases (normalized; collisions reported, never silently attached) and source bindings (workspace-validated, staleness-aware).
• engineering_claims with normalized-statement dedup and verified evidence-quote joins — a quote that is not a substring of the immutable snapshot is rejected. Corrections supersede; nothing rewrites history.
• engineering_relations with closed types (deliberately no depends-on), states explicit/inferred/confirmed/rejected/stale/superseded, active-tuple idempotency, and possibly-related never presented as anything stronger.
• One graph transaction = one monotonic per-workspace Knowledge Revision (allocated inside the transaction; a failed transaction mints nothing). Every governance write records an immutable Human Decision with a caller-supplied actor — identity is never inferred.

Promotion — the only bridge from candidates to canon

• promotion plan / promotion promote (+ relation variants): plan is a deterministic zero-write dry-run; promotion re-checks review status, staleness, evidence verification and endpoint resolution inside the transaction, is idempotent, and has no bypass flags. semantic review confirm still changes candidate metadata only. Conflict candidates cannot be promoted (Phase 6). Classification / revision-status promotions never touch assets.asset_type or asset_revisions.status.

Deterministic projection (graph seed / graph sync)

• Model-free, provider-free: assets -> code-component/configuration/data-model/document/build-definition entities; Java segments -> code-symbols; OpenAPI operations -> interfaces; SQL objects -> database-objects; containment explicit; name-based call edges inferred with ambiguity preserved. Incremental: an unchanged source hash writes nothing and mints no revision. Generic documents never become Requirements; test-source methods never become Test Cases.

Staleness, governance, search

• Indexed incremental reconciliation (hooked after ingest/document commits and worker startup) stales bindings/claims/relations whose revisions moved on — and revives them when sources return. Manual create (evidence required), authority marking, supersede/withdraw, reject/restore, transactional merge (source stays addressable and resolves to its target) and explicit all-or-nothing split.
• Graph search over a separate knowledge_<ws> vector collection with deterministic fusion: exact canonical key > exact alias > exact identifier token > lexical > vector — an exact identifier can never be outranked by similar-looking text. Bounded deterministic expansion, shortest paths with evidence summaries and honest found/no-path/truncated outcomes.

Bundle 2.0 Draft

• openmind bundle export writes a deterministic .openmind-v2/ (JSONL + JSON schemas + SHA-256-hashed manifest); python -m openmind.bundle_verify is a standalone stdlib-only verifier that catches missing endpoints, missing evidence and hash mismatches. No secrets, prompts, provider profiles or absolute paths.

Adapters

• CLI: graph, promotion, entity, claim, relation, bundle groups + knowledge revisions|revision|decisions beside the untouched Phase 3 knowledge search.
• REST: 26 additive routes under /projects/... (graph search lives at /knowledge/graph-search; the Phase 3 POST /knowledge/search is untouched).
• MCP: exactly nine additive read-only tools — 26 existing + 9 = 35, each accounted for by name in tests. Nothing on MCP promotes, creates, merges, changes authority, seeds or exports.

Verification

• Baseline on main: 48/48 core acceptance scripts.
• This branch: python scripts/run_acceptance.py -> 63 passed, 0 failed, 0 skipped (15 new verify_knowledge_* suites, ~360 checks, all registered in the manifest — a missing registration fails the run).
• verify_delete_responsive (local tier): 8/8.
• CI extended: per-suite steps in the Ubuntu full gate, MCP smoke updated to 35 tools, and a cross-platform knowledge smoke (migrate -> seed -> confirm -> promote -> lookups -> path -> bundle export + verify) on Ubuntu/Windows/macOS. No real provider API is called anywhere; candidates in tests come from the Phase 4 mock provider.

Notes for review

• Phase 1-4 data migrates without loss — verify_knowledge_migration builds a real v0005 database, seeds representative rows and migrates it to v0006.
• There is deliberately no FK from graph tables to semantic_candidates: the promoted candidate id is provenance, not ownership, so canonical history can never be cascade-deleted through the Phase 4 tables.
• Six existing suites were updated only for the totals the new phase moves (schema head 6, version 1.5.0-dev, 35 tools, and verify_document_search's canonical-table guard now asserts zero rows rather than zero tables — the tables legitimately exist now, the invariant that candidate association persists nothing canonical is unchanged).
• Honest limitations: graph path is generic reachability, not formal Requirement Traceability (Phase 6); conflict candidates remain unresolved candidates; the Bundle's --knowledge-revision N filters by creation-revision stamps and does not reconstruct point-in-time lifecycle states (stated in the manifest); Bundle 2.0 remains a Draft, not a frozen contract.