Orchestrata Ultimate › Plans › refactor-convergence-design

Refactor lanes convergence — LSP + interpreter functions and our AST (design)

Source: plans/refactor-convergence-design.md at 8a2cb42ad · last changed 2026-10-20 · first committed 2026-10-20 · 139 lines.

Prose pending.

Plan text

Refactor lanes convergence — LSP + interpreter functions and our AST (design)

Status: PROPOSED, partially ruled (ADR-0117, Mohamed 2026-10-20 "A": the SPEC-109 engine MOVES to codetools — P-A rescoped to MOVE-109, §6 decision 1 ratified. Decisions 2-3 and the codemod/ctok location remain open. RUL-022: no dispatch executes the open parts until ruled; MOVE-109 carries ADR-0117 as its contract.) Author: coordinator/architect seat, 2026-10-20. All numbers measured this session; §8 is the reproduction ledger. Origin: Mohamed, 2026-10-20, verbatim: "consider the functions of an LSP and the python interpreter for refactoring, can we extract or use such functions with our ast?" — approved scope "a + b": deciding measurements + this design, folded into the queued packets.

1. The short answer

The LSP and interpreter functions are ALREADY extracted — across five surfaces in this repo, two of them real engines (SPEC-109's basedpyright JSON-RPC client, SPEC-110's transactional codemod workspace), one of them the interpreter's own compiler (symtable, inside the toolkit rename). The defect is not extraction; it is convergence and precision: three rename engines with no shared discovery vocabulary, inferred types that are consumed and discarded instead of resolving the KB's fail-closed cases, and two measured resolver-precision gaps (from-import asnames lost; same-bare-name classes silently zero-matching). This design assigns lanes, names the packets that close the gaps by REUSE, and lists what we deliberately do not build.

2. Measured inventory (2026-10-20)

Dependency graph already carries: pyright>=1.1.411, basedpyright>=1.39.9 (pyproject dev group); pyright 1.1.411 + basedpyright + node all runnable in this worktree (measured).

3. Deciding measurements

• M1 — the KB-native typed rename refuses real work. rename --old begin --new begin_probe --kind method --class SessionController (dry-run): resolves the DEF site only, reports 1 BLOCKED receiver (session/event_emitting_session_controller.py:78, undeterminable type), rewrites 0 call sites, refuses --apply (fail-closed, by design). The refusal class is exactly what pyright's inference resolves — SPEC-109 exists because of it (founding incident: the half-applied gw→slot rename, 4 missed Redis slot parsers, 54 test failures).
• M2 — from-import asnames are lost. Live probe (from pathlib import Path as P): serialized as {"names":["Path"],"alias":null}; plain import json as j keeps "alias":"j". Every aliased from-import use is invisible to refs/rename resolution → systematic undercount. Confirms the standing backlog task with a fresh probe.
• M3 — same-bare-name classes silently zero-match. Two PrologBridge classes exist (cxp/prolog_bridge.py:122, infra/prolog_bridge.py:73). rename --kind method --class PrologBridge answered "Would change 0 edit(s)" — no ambiguity error, no disambiguation prompt. Silent-zero is the failure shape SPEC-109's whole design exists to make impossible ("a rename that silently under-applies is indistinguishable from a rename that succeeded").
• M4 — the engines are islands. Wired: lsp_tool (AST approximation), toolkit rename, code_intel. Unwired/deferred: SPEC-109 volk tool (declared), codemod daemon (CLI-only), codemod observability (no producer), AnalysisPass implementations (absent). No shared finding/evidence vocabulary (standing backlog item) — the three rename engines each carry their own refs discovery.
• M5 — SPEC-109 green-proof is owed, not skipped. 13 test modules exist (tests/refactor/rename/: transport, executor, applier, scanner, symbol_rename ×12, tool ×7, ...). The sanctioned-runner proof (run_tests.py tests/refactor/rename/*.py --skip-gates; bare multi-file pytest correctly refused by the RUL-038 cap guard — measured) runs the moment scripts/run_tests.py leaves the T17 run-3 fence. Recording it as owed beats re-running an unrecorded green (RUL-032).
• M6 — inference is available now. pyright 1.1.411 answers in-worktree; the repo already consumes it two ways (LSP server via SPEC-109 client; resolver via check_async_await).

4. Lane architecture (the convergence)

5. Packets (fold into the queued lane — approval "b")

Sequencing: P-C + P-D are precision prerequisites (small); P-A is the headline (turns measured refusals into completed renames); P-B closes a spec gap by reuse. None blocks the current queue (P-RUL039/040, build-order packets, INT-02+) — they slot into the debts/hardening lane.

6. Decisions owed to Mohamed (one recommendation each)

1. Lane split vs single engine. Keep three rename surfaces with the §4 lane rule, or converge on SPEC-109 as the only rename engine (toolkit rename delegates everything)? RULED 2026-10-20 (ADR-0117): lane split stands — and the SPEC-109 lane lives in codetools (engine moves; toolkit KB-native rename stays; codemod txn stays pending its own location ruling).
2. Shared refs vocabulary. The three engines each carry refs discovery; the standing "no shared finding/evidence vocabulary in core/" item is the same defect. Fold a common discovery/evidence protocol into that item's resolution, with ANALYSIS (KB) as the single source? Recommendation: yes, as the vocabulary item's design input — no third parallel model (Phase B unification of ast_models is the precedent).
3. Type-fact persistence (P-E). Persist inferred types into the KB, or keep inference on-demand? Recommendation: defer — measure the refusal residual after P-A lands; persist only if on-demand latency or offline demand proves real. Stale type facts in a KB whose freshness discipline is file-hash-based would be a new lie class.

7. Explicitly NOT doing

• No new refactoring engine, no jedi (basedpyright satisfies the open-source ruling; two consumption modes already exist in-tree).
• No cst_lsp/LibCST dependency in this repo (external codetools surface; format-preservation needs, if they arise, are a codetools lane question).
• No rebuild of SPEC-110 analysis (P-B delegates) and no wiring of the codemod observability producer inside these packets (that stays its own backlog item — SPEC-110 §15 feature, RUL-022 design-first).
• No volk-facing rename exposure beyond P-A's registered tool: high-blast-radius ops keep the coordinator/human review seam the founder incident demands.

8. Evidence ledger (reproduce)

# M1 refusal
.venv/bin/python scripts/serialize_codebase_ast.py rename --old begin --new begin_probe \
  --kind method --class SessionController --source src/orchestrata_ultimate   # dry-run
# M2 asname probe: /tmp/opencode/asname-probe/probe_mod.py + serialize + jq .imports
# M3 ambiguity
.venv/bin/python scripts/serialize_codebase_ast.py symbols --pattern "^PrologBridge$" --kind class
.venv/bin/python scripts/serialize_codebase_ast.py rename --old assertz --new assertz_probe \
  --kind method --class PrologBridge --source src/orchestrata_ultimate        # "0 edit(s)", silent
# M4 wiring: who-imports tools.lsp_tool | refactor.codemod.{server,daemon} | refactor.rename.tool
# M5: pytest-live tests/refactor/rename/ → RUL-038 guard names the sanctioned 13-file invocation
# M6: .venv/bin/pyright --version → 1.1.411; pyproject dev group

Cross-references: plans/rename-engine-design.md (SPEC-109, ratified+spiked), specs/109-rename-engine/, specs/110-codemod-engine/, specs/065-lsp-tool/, backlog items: asname capture, shared finding/evidence vocabulary, SPEC-110 gaps, tool-hardening batch (065), Neo4jSyncer name-index collision (M3's graph-side twin).

Related

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