RFC: replace remaining LangGraph assumptions with Wiii-native orchestration runtime

[meiiie]

Objective

Define and execute a controlled path to remove remaining LangGraph assumptions from Wiii and converge on a Wiii-native orchestration runtime.

This is intentionally an RFC / architecture control issue, not a one-shot deletion ticket. Wiii is already moving toward WiiiRunner, but the remaining work must preserve chat stability, streaming semantics, memory continuity, tool routing, checkpoint behavior, and CI governance.

Why Now

• Wiii's current behavior has been unstable enough that incremental patching around old graph assumptions is no longer sufficient.
• PR chore: harden GitHub security gates #126 introduces merge gates and review governance so a deeper runtime migration can happen safely across multiple agents.
• Existing cleanup issues [Ops]: complete Phase 1 LangGraph runtime-shell purge #93, [Ops]: remove retired LangGraph graph/checkpointer shims #97, and chore(test): clean up deprecated test_sprint54_graph_streaming mocks (Phase 3 of LangGraph purge) #101 address specific shim/test cleanup, but not the full target architecture and migration contract.

Proposed Target Direction

• Treat WiiiRunner or its successor as the only active orchestration entrypoint.
• Keep provider access behind a Wiii-owned provider/runtime abstraction rather than framework-bound graph nodes.
• Make state transitions explicit: input processing, routing, memory retrieval/update, tool execution, synthesis, streaming, and persistence.
• Preserve public API contracts while internals are replaced behind feature flags or compatibility shells.
• Avoid broad deletion until test parity and rollback criteria are written.

Required Design Deliverables

• Current pipeline map from API -> orchestrator -> runner/agents -> provider/tools -> persistence/streaming.
• Inventory of remaining langgraph, get_multi_agent_graph*, graph/checkpointer/shim imports and tests.
• Target orchestration contract: state model, node/step interface, event stream schema, error semantics, checkpoint/session model.
• Provider abstraction plan aligned with multi-provider goals: Gemini/OpenAI/OpenRouter/Ollama/Zhipu and future providers.
• Migration sequence with PR boundaries small enough for multi-agent ownership.
• Rollback plan for each phase.

Suggested Phases

1. Merge governance baseline (chore: harden GitHub security gates #126) and stabilize security backlog (security(deps): remediate high Dependabot alerts in desktop/Tauri stack #127, security(secrets): rotate and resolve historical OpenRouter secret-scanning alerts #128).
2. Complete active LangGraph shim cleanup ([Ops]: complete Phase 1 LangGraph runtime-shell purge #93, [Ops]: remove retired LangGraph graph/checkpointer shims #97, chore(test): clean up deprecated test_sprint54_graph_streaming mocks (Phase 3 of LangGraph purge) #101) only after CI is green.
3. Add a runtime inventory report documenting every remaining graph dependency.
4. Define Wiii-native orchestration interfaces and golden tests before deleting implementation.
5. Move one lane at a time: direct -> memory -> tutor/RAG -> tool loop -> streaming/checkpoint.
6. Remove final compatibility shells only after parity tests pass.

Acceptance Criteria

• A reviewed architecture document exists before destructive deletion starts.
• Each migration PR has an owned path list and exact verification commands.
• No PR mixes broad dependency upgrades, secret rotation, and orchestration refactor.
• CI Gate Summary stays required throughout the migration.
• Wiii can still chat on FE after each phase.

Related Work

• [Ops]: complete Phase 1 LangGraph runtime-shell purge #93 Phase 1 runtime-shell purge
• [Ops]: remove retired LangGraph graph/checkpointer shims #97 Phase 2 graph/checkpointer shim removal
• chore(test): clean up deprecated test_sprint54_graph_streaming mocks (Phase 3 of LangGraph purge) #101 Phase 3 deprecated graph mock cleanup
• Harden GitHub security gates and multi-agent merge governance #123 / chore: harden GitHub security gates #126 GitHub governance hardening
• security(deps): remediate high Dependabot alerts in desktop/Tauri stack #127 high dependency security remediation
• security(secrets): rotate and resolve historical OpenRouter secret-scanning alerts #128 OpenRouter secret rotation

[meiiie]

Architecture follow-up:

• Opened PR docs: define Wiii-native orchestration RFC #141 with a Wiii-native orchestration RFC.
• The PR intentionally does not delete LangGraph residue yet; it documents current runtime truth, target contracts, provider runtime direction, phased migration, rollback gates, FE chat smoke requirements, and multi-agent ownership boundaries.
• security(deps): remediate high Dependabot alerts in desktop/Tauri stack #127 is closed for high dependency alerts.
• security(secrets): rotate and resolve historical OpenRouter secret-scanning alerts #128 remains a separate external provider operation; PR security: harden OpenRouter env template #140 handles repo-safe template hardening but does not falsely mark OpenRouter keys revoked.

Recommended next implementation after PR #141 review: create Phase 1 inventory issue/PR that classifies every remaining graph-shaped reference before any destructive deletion.

[meiiie]

Migration control update:

• PR docs: define Wiii-native orchestration RFC #141 has been rebased onto latest main after security: harden OpenRouter env template #140 merged; checks are rerunning and CodeRabbit will be retried after its cooldown.
• [Ops]: complete Phase 1 LangGraph runtime-shell purge #93 Phase 1 runtime-shell purge was verified against current code and closed as completed.
• [Ops]: remove retired LangGraph graph/checkpointer shims #97 Phase 2 graph/checkpointer shim removal was verified against current code and closed as completed.
• chore(test): clean up deprecated test_sprint54_graph_streaming mocks (Phase 3 of LangGraph purge) #101 remains the next concrete cleanup track: port or retire deprecated get_multi_agent_graph* test mocks.
• security(secrets): rotate and resolve historical OpenRouter secret-scanning alerts #128 was reopened for state accuracy because GitHub secret-scanning alerts Feature/semantic memory v0.3 #1 and docs: update documentation for Gemini 2.5 Flash fix and v2.8 release #2 are still open even though repository-side remediation has merged.

Current recommended implementation sequence after #141 merges: handle #101 as the next narrowly scoped PR, then update stale architecture docs that still describe LangGraph/checkpointer tables as active runtime.

[meiiie]

Follow-up docs cleanup opened: #143 aligns canonical architecture docs and active runtime docstrings with WiiiRunner instead of retired LangGraph/StateGraph wording. Verification completed locally: \git diff --check\ and Python \py_compile\ on touched modules. Scope is docs/docstrings only; no runtime behavior changes.