Orchestrata Ultimate › Plans › briefs › p-archsync-table-correction

P-ARCHSYNC — correct the self-described-architecture table to current doctrine — brief for one qwen3-coder-next run

Source: plans/briefs/p-archsync-table-correction.md at 8a2cb42ad · last changed 2026-10-19 · first committed 2026-10-19 · 99 lines.

Prose pending.

Plan text

P-ARCHSYNC — correct the self-described-architecture table to current doctrine — brief for one qwen3-coder-next run

Authority: Mohamed 2026-10-19 verbatim "we are not using neo4j models get confused make this clear" + the coordinator's P-ARCHSYNC task (session 272). The script scripts/sync_architecture_to_graph.py re-syncs its COMPONENTS table into prod orchkg on every SessionStart hook run — its stale rows actively teach agents a wrong architecture. This packet corrects the table and adds a scoped retirement mechanism for the graph node the corrected table no longer writes.

Model-routing note (RUL-037): .py-fenced brief on qwen3-coder-next by Mohamed's explicit session instruction (stated override; M2 not landed). Coordinator verifies before commit and runs the prod graph step himself. Workers do not commit and never touch prod (10.53.1.*).

Fence — exactly these two files

scripts/sync_architecture_to_graph.py
tests/scripts/test_sync_architecture_to_graph.py

Read both fully first (AST toolkit: source sync_architecture_to_graph --source scripts/sync_architecture_to_graph.py --residue for the module tables; the test file has ~14 neo4j-related assertions to update). No other file. No commit, no git add, no prod connection, no full-suite runs.

Measured doctrine (the correction targets — do not invent beyond these)

1. The graph engine is orchgraph — Mohamed's Memgraph 3.11 fork, HA cluster (coordinators + main/ replica), Bolt protocol, orchkg database; the Memgraph semantic twin lives in the memgraph database on the same cluster. Neo4j is NOT used: containers destroyed 2026-07-27 (AGENTS.md § Graph Sync Engine; env keys NEO4J_* retired). The neo4j:// URI scheme and the Python neo4j driver package are Bolt-client naming only.
2. Kernel is REQUIRED — Hard Rule 7 (AGENTS.md): the kernel "must be started AND gRPC-verified for a test run to be valid... never re-flip the kernel to optional". The table's required: False on Kernel contradicts it.
3. grpcio is retired (2026-08-07, AGENTS.md § Test Standards): the kernel transport is the cxpt direct transport on port 50053; "Gateway connects via gRPC" phrasing is stale. The PipelineKernelClient fallback remains (production resilience path).

Changes

A. COMPONENTS table (the five-row module-level list)

• Neo4j row → orchgraph row: "name": "orchgraph"; protocol "Bolt (port 7687)"; compute_platform "Incus HA cluster (orchgraph — Memgraph 3.11 fork: coordinators + main/replica)"; responsibility "Operational knowledge graph (orchkg database): code structure, specs/requirements, sessions, audit trail, architecture ontology. The Memgraph semantic twin lives in the 'memgraph' database on the same cluster. Neo4j was retired 2026-07-27; the neo4j:// scheme and the Python neo4j driver are Bolt-client naming only."; required True; invariants/protocols unchanged (["Never hardcode service IPs"], []).
• Kernel row: required False → True; responsibility phrasing "Connects via gRPC" → the cxpt direct transport ("Gateway connects via the cxpt direct transport (grpcio retired 2026-08-07); falls back to in-process PipelineKernelClient when unreachable" — keep the rest of the sentence's content).
• Gateway row: responsibility "Connects to kernel via gRPC." → "Connects to the out-of-process kernel via the cxpt direct transport (grpcio retired 2026-08-07)."
• Invariants list: the invariant string "gRPC kernel is out-of-process" (in ARCHITECTURE/CONSTRAINTS and in the Kernel/Gateway rows' invariants) → "kernel is out-of-process (cxpt direct transport)". Constraint nodes MERGE on name, so the renamed invariant creates a NEW Constraint node and orphans the old one — handle it in section B's retirement (retire the Constraint by the same mechanism, id {project}:gRPC kernel is out-of-process... check how upsert_constraint keys the id before choosing the retirement target; report what you measured).
• Every other row (VizInt UI, Redis) and all non-stale text: unchanged. Do not restructure the script.

B. Scoped retirement flag (the deletion Mohamed authorized, mechanism-scoped)

Add --retire-legacy <LABEL>:<id> (repeatable) to the parser: DETACH DELETE one node by label + canonical id, project-scoped safety: refuse any id not starting with orchestrata-ultimate:; print the target and the pre-delete property snapshot; exit non-zero if the node does not exist (loud, never silent). This is the ONLY delete path in the script; it goes through the writer's repository (writer._write or the documented public seam if one exists — measure and report which you used; do NOT add a delete method to ArchitectureWriter, that file is outside the fence). Default runs (no flag, and the SessionStart hook) NEVER delete anything. Document in the module docstring: the hook keeps writing the corrected table; --retire-legacy is coordinator-run, one-shot, per authorized correction (Mohamed 2026-10-19).

C. Tests (same fence)

• Update every assertion that names "Neo4j" / required=False on Kernel / the gRPC invariant string to the corrected table (the test file mirrors the table — find them all: grep -n -i neo4j gives ~14).
• New tests for --retire-legacy, real graph (test fleet via the file's existing fixtures), test_id-scoped nodes: (1) refuses a non-orchestrata-ultimate: id; (2) exits non-zero on a missing node; (3) deletes exactly the named node + its edges (create a throwaway Component under a test slug via the writer, retire it, assert gone); (4) a default sync() run deletes nothing (counts before/after).
• Standards: no mocks/monkeypatch/skips, function-scope fixtures, cleanup by test slug (follow the file's existing patterns).

VERIFY (run exactly; report outputs verbatim)

.venv/bin/ruff check scripts/sync_architecture_to_graph.py tests/scripts/test_sync_architecture_to_graph.py
.venv/bin/black --check scripts/sync_architecture_to_graph.py tests/scripts/test_sync_architecture_to_graph.py
.venv/bin/pytest tests/scripts/test_sync_architecture_to_graph.py -o addopts="" -q
grep -c -i '"Neo4j"' scripts/sync_architecture_to_graph.py            # expect 0 (the responsibility sentence may mention Neo4j as retired — table NAME must not)
grep -n "required.*False" scripts/sync_architecture_to_graph.py | grep -i kernel   # expect NOTHING
.venv/bin/python scripts/sync_architecture_to_graph.py --help | grep -A2 retire

Coverage: measure honestly (--cov=scripts --cov-report=term-missing | grep sync_architecture_to_graph), report the number and any gap as a named second-pass item (session priority: finishing outranks perfect 90).

Done

Reply with: the diff summary per change (A/B/C), the constraint-id retirement target you measured, which writer seam the retirement uses, the VERIFY outputs verbatim, the coverage number, and anything you could not execute faithfully, named.

Related

• Plans
• Orchestrata Ultimate — project index
• Workflow
• Tasks