Orchestrata Ultimate › Plans › component-fixes-2026-10-19

Plan and design — component fixes after the 2026-10-19 analysis

Source: plans/component-fixes-2026-10-19.md at 8a2cb42ad · last changed 2026-10-19 · first committed 2026-10-19 · 130 lines.

Prose pending.

Plan text

Plan and design — component fixes after the 2026-10-19 analysis

Status: executing. Coordinator: this session. Workers do the edits. No new ruling is minted here. The Accepted ADRs below are the contract.

Source report: reports/project-analysis-2026-10-19.md.

1. What is already ruled

Mohamed, 2026-10-19, verbatim "all", recorded in:

R1 (memory still says tools are not a package) is a documentation correction of a stale memory against Accepted ADR-0107. It is not a new decision. R6 (count the RAG corpus before any re-embed) is a measurement, not a code change. R8 (do not re-run the suite to decorate a report) is a process rule. This plan does not re-run the suite and does not re-embed.

2. Model choice

Python edits go to sonnet through packages/design-scripts/dispatch/dispatch.py. RUL-037 still says that until M2 is in force, a brief whose files fence lists a .py file goes to sonnet, because DeepSeek and Qwen do not run the Claude hooks. M2 is not recorded as landed. The user allowed another model; the project rule picks sonnet for Python.

Non-Python ontology prose goes to deepseek-pro (deepseek/deepseek-v4-pro via the dispatch executor, or the OpenCode subagent on openrouter/deepseek/deepseek-v4-pro-0813). It does not edit .py files.

3. Measured path correction (not a new ruling)

ADR-0114 lists packages/kg/src. That directory does not exist. The package on disk is packages/knowledge_graph/src, import name orchestrata_kg. The decision sentence is "one root per component package's src dir". Implementation uses the directories that exist. The Accepted ADR body is not edited. A superseding ADR is owed only if Mohamed wants the listed path corrected in the register.

Roots to append, after the existing set, primary root unchanged:

packages/contracts/src
packages/governance/src
packages/knowledge_graph/src
packages/kernel/src
packages/session/src
packages/volks/src
packages/gateway/src
packages/tools/src

packages/integration/src is not added. It has no Python. ADR-0113 says it joins when it lands.

The walker skips a directory that contains pyproject.toml. That is why packages is not one root. Each src dir above is not itself a distribution root in the walker's sense: the pyproject.toml sits in the parent. Confirmed by ADR-0114's own mechanism note. Do not add packages/<name> (the distribution root). Add packages/<name>/src.

4. Design — what each fix changes

4.1 Graph: this worktree becomes visible (ADR-0114)

env/ast-roots.env is the one declaration the snapshot and the live sync both read. First root stays src/orchestrata_ultimate, so existing bare module ids do not move. Later roots are prefixed with their directory name, which the serializer already does. Component modules will appear as packages.kernel.src.orchestrata_kernel.… and the same shape for the other seven.

After the declaration is on disk and scripts/gen_level0.py --check is not this packet's job, the coordinator — not the worker — runs a project-scoped sync of slug orchestrata-ultimate against prod orchkg (KG_ROUTING_URI from env/prod.env, database orchkg). The sync merges that project. It does not delete other project slugs. Then traces and specs:

• scripts/sync_ast_to_graph.py full with the declared roots, project orchestrata-ultimate
• scripts/sync_traces_to_graph.py pointed at orchkg, if that entrypoint accepts the new roots; if it does not, the gap is a follow-up brief, not a silent empty count
• verify, read-only: a module path containing orchestrata_contracts returns at least one row; Spec count > 0; Requirement count > 0

If the prod main does not complete a Bolt handshake, the sync is not claimed. The test fleet (10.53.2.10, database orchkg) is not a substitute for the graph agents read.

4.2 Ontology

No new node type. The ratified architecture ontology already has Component (id = "{project}:{name}") and DEPENDS_ON. This worktree's components are those nodes, project slug orchestrata-ultimate.

required=no on integration is the ontology saying the node exists as a design component and is not yet a running one. It is not permission to skip building it.

The prose home is the knowledge-wiki page projects/orchestrata-ultimate/component-dag.md, plus this plan. The graph home is ArchitectureWriter.upsert_component and link_depends_on. A worker writes a committed seed module that calls those two methods from the table above and nothing else. The coordinator runs it after review. The worker does not open a Bolt connection to prod during the edit.

4.3 Documentation

scripts/gen_level0.py is the only writer of docs/LEVEL0.md. The identity block stops saying the mission is "porting ~122K LOC into one package". It says:

• Orchestrata is an agent orchestration engine. Intent enters through Concierge. Specialist volks each get an LLM, context, and a persona. The graph is context. Redis is events and queues. Prolog computes what can be computed.
• This checkout holds the components refactor (packages/<name>/) beside the monolith (src/orchestrata_ultimate/). Cut-over has not happened.
• origin/master at 0faca7a7 (prod deployed 2026-10-19T11:41:39Z) is a backup-and-deploy of the in-progress tree, ADR-0113. Cut-over remains: integration passes the fleet tier, old src/orchestrata_ultimate/* removed, one merge, /opt/orchestrata ships from that tree.

The generated file is regenerated by running the script. It is not hand-edited.

~/.claude/projects/-home-mohamed-workspace-orchestrata-ultimate/memory/components-replaces-ultimate.md still says tools are not a package. That sentence is stale against ADR-0107. The replacement sentence: tools landed as packages/tools (orchestrata_tools) by ADR-0107; codetools remains the separate toolbox for diagram, AST, and the script migration; consumers of the landed tools package depend on it as a component, and ADR-0112 removes its kernel imports.

4.4 Tools seams (ADR-0112) — packet P3, not started in the same edit as P1

Two call sites, already measured:

• schedule_cron_tool.py imports orchestrata_kernel.core.redis_factory.create_async_redis. The factory already accepts an injected client. Add redis_factory: RedisFactory | None. Default constructs redis.asyncio.Redis from the host, port, and db the tool already requires. redis is already a declared tools dependency.
• search.py imports EmbeddingService and constructs it bare. Add embedding: EmbeddingPort | None. Default is a real hash-projection implementation in tools, not a fake and not a kernel import.

New protocols, contracts only, TYPE_CHECKING for any Redis type, no new third-party runtime dependency on contracts:

• orchestrata_contracts.protocols.redis_factory.RedisFactory
• orchestrata_contracts.protocols.embedding_port.EmbeddingPort with compute_embedding, cosine_similarity, and search as ADR-0112 specifies

packages/tools/pyproject.toml drops orchestrata-kernel. Parity allow-lists drop orchestrata_kernel. Kernel supplies the canonical implementations at integration boot, not by import.

4.5 Integration — sized, not swarmed

ADR-0113 says L1 builds now. The design already splits it into INT-01..INT-25, max 400 LOC, INT-01 first (SPEC-125 delta and the release scaffold). This plan does not dispatch "build integration". P4, after P3 verifies, is INT-01 only: package init, release pyproject.toml with component pins and console scripts, no residue reopened in the eight packages. Later increments are separate briefs. Waiting for a perfect lift before any wiring is the rejected alternative.

5. Packet order

Workers do not commit. The coordinator verifies the brief's checks, then dispatch.py commit with an explicit file list. No --no-verify. No push.

6. Out of scope

• Re-running the test suite to fill totals=null (RUL-032).
• A semantic re-embed. The corpus count is UNKNOWN because the prod main stopped answering a Bolt handshake during the analysis. Count first, on a healthy main, before any ingest. ADR-0109's 500-row bound stays.
• Editing Accepted ADR bodies, including the packages/kg/src typo.
• Removing src/orchestrata_ultimate. That is cut-over, and cut-over has not been reached.
• New node types in the ontology.

Related

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