Orchestrata Ultimate › Plans › briefs › component-dag-seed

Component-DAG ontology seed — brief for one qwen3-coder-next run

Source: plans/briefs/component-dag-seed.md at 8a2cb42ad · last changed 2026-10-19 · first committed 2026-10-19 · 135 lines.

Prose pending.

Plan text

Component-DAG ontology seed — brief for one qwen3-coder-next run

DESIGN_WAIVER: none needed — the design exists. Authority: plans/component-fixes-2026-10-19.md §4.2 (the ruled table) and plans/handoff-component-fixes-2026-10-20.md Step A. The ratified ontology already has Component (id = "{project}:{name}") and DEPENDS_ON — do NOT add a node type, do NOT write raw Cypher.

Model-routing note (RUL-037): this brief fences .py files and runs on qwen3-coder-next by Mohamed's explicit session instruction of 2026-10-19 (stated override; M2 guard bridge not landed). The coordinator runs the full verification pass before commit. Workers do not commit.

Goal

One committed seed module that writes the ten-row component DAG of plan §4.2 into the operational graph through ArchitectureWriter ONLY — upsert_component + link_depends_on, nothing else — plus real tests against the TEST fleet graph. The coordinator (not you) later runs it against prod orchkg.

Fence — exactly these two files, create both

scripts/seed_component_dag.py
tests/scripts/test_seed_component_dag.py

No other file created or edited. No commit, no git add. NEVER connect to prod (neo4j://10.53.1.160:7691 / any 10.53.1.* host): your tests run against the test-fleet graph the suite env already resolves (tests.infrastructure.GRAPH_URI, database orchkg on 10.53.2.10). Do not set KG_* env vars anywhere (T2: no os.environ mutation in tests).

Design of scripts/seed_component_dag.py

Follow the house pattern of scripts/sync_architecture_to_graph.py (read it first — importlib-friendly, _load_dotenv(), pure sync function + thin main(argv)):

1. Import the writer from the MONOLITH root (root-venv pattern, same as sync_architecture_to_graph.py): from orchestrata_ultimate.knowledge_graph.architecture_writer import ArchitectureWriter. The component-package copy (packages/knowledge_graph/.../orchestrata_kg/...) is the same API byte-for-byte; scripts/ CLIs run in the root venv where only orchestrata_ultimate is installed.

2. COMPONENT_DAG: a module-level frozen table (tuple of dataclasses or dicts) transcribing plan §4.2 EXACTLY — ten rows, these columns: name, import_name, responsibility, depends_on (tuple of component names), required (bool):

   name	import_name	depends_on	required
   contracts	orchestrata_contracts	—	yes
   governance	orchestrata_governance	contracts	yes
   knowledge_graph	orchestrata_kg	contracts	yes
   kernel	orchestrata_kernel	contracts, governance, knowledge_graph	yes
   session	orchestrata_session	contracts, knowledge_graph, governance	yes
   volks	orchestrata_volks	contracts, kernel, knowledge_graph, governance	yes
   gateway	orchestrata_gateway	contracts, kernel, session, knowledge_graph, governance	yes
   tools	orchestrata_tools	contracts, knowledge_graph, governance	yes
   integration	orchestrata	kernel, gateway, volks, session, knowledge_graph, governance, tools	no
   plugin	(empty string)	gateway, tools, integration	no

   Responsibility strings: copy verbatim from the responsibility column of plans/component-fixes-2026-10-19.md §4.2 (read that file; do not paraphrase).

3. seed_component_dag(writer, project="orchestrata-ultimate") -> dict[str, int] — PURE function, no env reads, no I/O beyond writer calls:

   • Phase 1: for every row, writer.upsert_component(project, name, responsibility=..., required=..., boundary=import_name) — boundary carries the Python import root (documented in the module docstring; the ontology has no import-name property and boundary is the sanctioned free-text field). Do NOT pass compute_platform/protocol — the ruled table does not state them; do not invent.
   • Phase 2 (STRICTLY after all upserts — _edge silently drops edges whose endpoints do not exist yet): for every row, for every dep in depends_on, writer.link_depends_on(from_id, to_id) where the ids are the {project}:{name} strings phase 1 returned. Default kind (do not invent one).
   • Return counts {"components": N, "depends_on": M} computed from the table (10 and 22 for the full table — verify by counting the depends_on tuples: 0+1+1+3+3+4+5+3+7+3 = 30. Use the real count from the table, do not hardcode a wrong number: recount yourself and assert consistency in a test).

4. main(argv: list[str] | None = None) -> int:

   • _load_dotenv() copy the pattern from sync_architecture_to_graph.py (secrets .env then the active ORCHESTRATA_ENV_PROFILE overlay).
   • argparse: --project (default orchestrata-ultimate), --dry-run (print the resolved target — orchestrata_ultimate.core.graph_factory.resolve_uri() + resolve_kg_database() — and the table rows, WITHOUT constructing the writer or touching the graph; exit 0).
   • Non-dry-run: print target URI + database FIRST (the coordinator must see it is prod before writes), construct ArchitectureWriter(), call seed_component_dag, print the counts, writer.close(), return 0. Exceptions propagate (no except: pass — Hard Rule 3); wrap only to add the target-uri context line, re-raise.

5. Traces: this is operational seed tooling — check specs/106-context-semantic-layer/checklists/requirements.md (REQ-106-008 is writer-conformance, not seeding) and conclude per the two-lane rule: if no root-spec REQ genuinely matches, the module stays DELIBERATELY UNTRACED with a docstring line saying so ("two-lane rule, AGENTS.md @traces conventions"). Do NOT cite REQ-119-* — SPEC-119 lives only in packages/knowledge_graph/.realize-out/, and root trace-lint would flag it dangling. No hand-stamped ids.

Design of tests/scripts/test_seed_component_dag.py

Real infrastructure only (AGENTS.md test standards): no mocks/stubs/fakes/monkeypatch/skips, function-scope fixtures, test_id everywhere.

• Load the CLI by path with importlib — copy _load_cli() from tests/scripts/test_sync_architecture_to_graph.py (including the register-before-exec sys.modules note).
• Graph fixture: from tests.infrastructure import GRAPH_URI, GRAPH_USERNAME, GRAPH_PASSWORD, KG_DATABASE; real neo4j.GraphDatabase.driver; build BoltSyncRepository over it and inject into ArchitectureWriter(repo) — mirror tests/knowledge_graph/conftest.py's graph_repo usage (read it).
• Project slug: f"seedtest-{test_id}" (T7). Cleanup fixture: label-bounded MATCH (n:Component) WHERE n.project = $slug DETACH DELETE n (the seed writes ONLY Component nodes and DEPENDS_ON edges between them — DETACH removes the edges; never run a label-less sweep).
• Tests (all against the real test-fleet graph):
  1. table integrity: 10 rows; unique names; every depends_on entry names a row; no self-dependency; required flags match the ruled table (integration=False, plugin=False, rest True); total edge count equals the summed depends_on tuples.
  2. seed writes: after seed_component_dag(writer, project=slug) — 10 Component nodes exist with ids {slug}:{name}, boundary=import_name, required per table; DEPENDS_ON edge count equals the table sum.
  3. the ADR-0112 shape: tools DEPENDS_ON contracts, knowledge_graph, governance — and NOT kernel (read-only query over the test slug's nodes).
  4. idempotency: run seed twice on the same slug — node and edge counts unchanged.
  5. dry-run: main(["--project", slug, "--dry-run"]) returns 0, stdout names all ten components and the resolved target, and ZERO Component nodes exist for the slug afterwards.
  6. main end-to-end (test fleet via the ambient suite env — never set env vars): main(["--project", slug]) returns 0 and the 10 nodes exist; cleanup fixture removes them.
• Coverage (Mohamed 2026-10-19, session priority ruling: FINISHING THE TASK outranks perfect coverage — 90% remains the goal but is a SECOND-PASS item): measure with --cov=scripts --cov-report=term-missing -o addopts="" and report the exact % for scripts/seed_component_dag.py. If below 90%, do NOT pad tests to chase the number: list the uncovered lines and why in your reply — the gap becomes a named second-pass task, executed with the coverage workflow: .venv/bin/python scripts/serialize_codebase_ast.py branches --name <func> --source scripts/seed_component_dag.py to enumerate the untested decision points, then gen-tests --name <func> for per-branch scaffolds, replacing every stub with real assertions. Green, real tests + an honest number is a complete run.

VERIFY (run exactly these, report outputs)

.venv/bin/ruff check scripts/seed_component_dag.py tests/scripts/test_seed_component_dag.py
.venv/bin/black --check scripts/seed_component_dag.py tests/scripts/test_seed_component_dag.py
.venv/bin/pytest tests/scripts/test_seed_component_dag.py -o addopts="" -q --cov=scripts --cov-report=term-missing
grep -c "upsert_component\|link_depends_on" scripts/seed_component_dag.py
grep -n "execute_write\|execute_read\|session.run\|GraphDatabase" scripts/seed_component_dag.py   # must print NOTHING: writer-only

Done

Reply with: the two file paths, the pytest summary line, the coverage % for scripts/seed_component_dag.py, the ruff/black results, confirmation the seed module contains no direct Bolt/Cypher access, and the component/edge counts your table integrity test asserts.

Related

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