BHANUJBHANUJ
v1.2.2

Operate Neo4j Synchronization

Use Studio to check whether the relationship graph is up to date and safely retry a failed update.

What You Will Do

You will start the local stack, seed governance data into Neo4j, inspect its synchronization events in Studio, and follow the safe retry workflow for a dead-letter event. The graph stays a projection throughout: it never replaces the authoritative control-plane data.

Start and Seed

Set `AI_GOVERNANCE_AUTO_SEED_DEMO_DATA=true` to enable startup demo seeding. The demo seed uses stable identifiers, so normal restarts refresh the demo records rather than accumulating duplicates.

bash
AI_GOVERNANCE_AUTO_SEED_DEMO_DATA=true
./servers.sh

The scripts initialize the Neo4j schema automatically. Re-running the seed is intentional: synchronization uses idempotent upserts, so existing graph entities and relationships are reconciled rather than duplicated.

Inspect the Projection

  1. Open Studio and go to Home.
  2. Confirm the Neo4j Graph Store reports healthy connectivity and live counts.
  3. Open Sync Events.
  4. Select an event to see its entity, event type, retry count, timestamps, failure context, payload, and reconciliation metadata.

A completed event means its expected semantic projection has converged. It does not imply the graph is a source of truth; it is still derived from the domain repositories.

Recover an Event

If an event reaches DEAD_LETTER, first read the failure context. Typical causes include malformed source data or a relationship that is not permitted by the ontology contract. Correct that cause before retrying.

  1. Select the dead-letter event in Sync Events.
  2. Expand technical details only when the summary is not enough.
  3. Fix the underlying data or contract issue.
  4. Choose Retry event.
  5. Refresh and confirm the status becomes COMPLETED.

The retry is explicit and auditable. The worker re-runs diff-based reconciliation, which upserts the projection and repairs only drift rather than duplicating graph records.

Verify the Result

Run the smoke test when you need an end-to-end confirmation outside Studio:

bash
uv run python smoke_tests/smoke_neo4j_evaluation_result_sync.py

For deeper operational guidance, including schema initialization, direct read-only Cypher checks, soft deletes, and integration tests, continue to Neo4j Operations.