KAVACHKAVACH
v2.0.1

Ontology Synchronization

Ontology synchronization projects existing Kavach governance domain objects into the kavach.governance ontology graph. Domain repositories and services remain the systems of record.

Overview

The synchronization layer is one-way: domain objects are projected into the ontology graph for lineage, provenance, and future traversal workflows. Synchronizers never talk directly to Neo4j — all graph writes go through OntologyService, which preserves relationship validation and idempotency.

Synchronization Contract

Every synchronizer implements:

python
class OntologySynchronizer:
    def synchronize(entity) -> SynchronizationResult
    def delete(entity) -> SynchronizationResult
    def resynchronize(entity_id: str) -> SynchronizationResult

SynchronizationResult includes synchronized entity IDs, relationship IDs, archived entity IDs, errors, duration, failure count, retry count, and entity/relationship counters.

Synchronizers

Registry synchronizers:

  • PromptOntologySynchronizer
  • ModelOntologySynchronizer
  • DatasetOntologySynchronizer

These create logical asset entities, version entities, actor provenance, and version relationships: HAS_VERSION, VERSION_OF, CREATED_BY, OWNED_BY, and SUPERSEDES.

Experiment synchronizers:

  • ExperimentOntologySynchronizer
  • CandidateOntologySynchronizer

These create experiments, candidates, provider nodes, ownership relationships, and candidate USES links to prompt/model/dataset versions.

Evaluation synchronizers:

  • EvaluationRunOntologySynchronizer
  • EvaluationResultOntologySynchronizer

These create evaluation runs, results, provider nodes, metric nodes, artifact nodes, and evidence relationships including EXECUTES, PRODUCES, HAS_METRIC, HAS_ARTIFACT, and EVALUATED_BY.

Operational synchronizers:

  • JobOntologySynchronizer
  • MCPAuditOntologySynchronizer
  • WorkflowExecutionOntologySynchronizer
  • ReplayOntologySynchronizer

Governance synchronizers:

  • GovernanceDecisionOntologySynchronizer
  • GovernanceInsightOntologySynchronizer
  • GovernanceReportOntologySynchronizer
  • DriftOntologySynchronizer

Reconciliation

DiffBasedOntologyReconciler is the primary reconciliation engine. It builds the expected ontology projection from domain repositories, fingerprints the semantic projection, loads the current graph snapshot, and repairs only detected drift.

KAVACH / governed event stream
ontology / reconciliationevent order
  1. 01
    build expected projection

    Domain repositories produce the authoritative semantic graph shape.

  2. 02
    fingerprint semantic state

    Entity and relationship hashes ignore timestamps and sync metadata.

  3. 03
    compare graph snapshot

    The reconciler skips matching projections and isolates semantic drift.

  4. 04
    repair only the diff

    Synchronizers update missing or changed entities and relationships.

governed outcome

IN SYNC

Systems of record preserved · semantic drift repaired · graph traversal ready

The reconciliation workflow:

  1. Build expected projection with ProjectionBuilder.
  2. Compute projection_hash for semantic entity state.
  3. Compute relationship_set_hash for the unordered relationship set.
  4. Load the current graph projection snapshot.
  5. Skip projections with matching stored hashes.
  6. Update missing projection metadata when semantic state already matches.
  7. Run the synchronizer only when entities or relationships have semantic drift.

Fingerprints ignore timestamps, synchronization metadata, and implementation details. Relationship order does not affect relationship_set_hash.

Event-Driven Synchronization

Event-driven synchronization records ontology work as durable events and lets a background worker process those events asynchronously. Domain services publish events after authoritative state changes, but remain unaware of Neo4j.

text
Domain service -> OntologySyncEventPublisher -> event repository
event repository -> OntologySynchronizationWorker -> DiffBasedOntologyReconciler

Supported statuses: PENDING, PROCESSING, COMPLETED, FAILED, DEAD_LETTER, and CANCELLED.

REST monitoring endpoints:

  • GET /api/v1/ontology/synchronization/events
  • GET /api/v1/ontology/synchronization/events/[event_id]
  • POST /api/v1/ontology/synchronization/events/[event_id]/retry
  • POST /api/v1/ontology/synchronization/events/[event_id]/cancel
  • GET /api/v1/ontology/synchronization/events/metrics

Deletion Strategy

Synchronizers do not hard-delete ontology entities. delete(entity) marks the projected entity lifecycle as ARCHIVED, records archival metadata, and preserves historical relationships. Physical cleanup remains an explicit orphan cleanup concern outside ontology synchronization.

Running Tests

bash
# Unit tests
uv run pytest tests/unit/ontology_sync

# With foundation ontology tests
uv run pytest tests/unit/ontology_sync tests/unit/ontology

# Neo4j integration tests
export KAVACH_RUN_NEO4J_TESTS=true
uv run pytest tests/integration/ontology_sync