[M9] Toolchain API and agent platform

[Teakowa]

Goal

Expose Wright as reusable infrastructure for other projects, automation systems, and coding agents through stable toolchain APIs built on the same compiler/session and semantic services as the CLI.

M9 turns Wright from a standalone tool into a platform that other tools can embed without scraping CLI text or depending on internal IR layout.

Scope

• Stabilize a Rust embedding API for project loading, compile/check/analyze/query workflows.
• Evolve the existing read-only semantic service into a project/session-aware structured tool API.
• Provide structured semantic operations for rules, symbols, references, usage, CFGs, findings, target metadata, and compilation results.
• Add agent-oriented queries where they have demonstrated value, such as callers/dependencies, rule inspection, variable tracing, and cost estimation.
• Define safe source-edit/refactoring contracts only where evidence justifies mutation; avoid exposing raw mutable IR as a public compatibility surface.
• Keep transport/protocol adapters thin and optional.
• Allow CLI, agent harnesses, and future LSP integrations to reuse the same owned toolchain contracts.

M9 sub-issues

• [M9] Stabilize Rust embedding API over compiler/session workflows #56
• [M9] Evolve structured tool API into project/session-aware service #57
• [M9] Add agent-oriented semantic queries and cost inspection #58
• [M9] Define safe source edit and refactoring contracts #59
• [M9] Add thin transport adapters for structured tool consumers #60
• [M9] Validate external consumer integrations and API versioning #61
• [M9] Validate toolchain/agent platform and rebaseline M10 #62 — acceptance/re-evaluation gate before M10

Architecture

                Wright Toolchain API
                        │
          ┌─────────────┼─────────────┐
          ▼             ▼             ▼
         CLI        agent adapters   other tools
                        │
                  MCP / JSON-RPC /
                  stdio as adapters

No single agent protocol is the architecture.

Non-goals

• Coupling Wright core to Claude Code, Codex, Pi, OpenCode, MCP, or another specific harness.
• Browser/editor extensions.
• Publishing raw mutable arena/AST internals as a stable API.

Exit criteria

• External projects can load and inspect supported Wright projects/programs through stable owned APIs.
• Agent/tool consumers can obtain structured semantic results without parsing source text or human CLI output.
• Transport-specific adapters remain separable from compiler/analyzer core contracts.
• API stability/versioning expectations are explicit.
• [M9] Validate toolchain/agent platform and rebaseline M10 #62 validates external-consumer evidence and rebaselines M10 before language-service work begins.

Planning note

M9 sub-issues are provisional until #55 completes. #62 is a hard re-evaluation gate; M10 should be revised if the actual post-v1 toolchain boundaries differ from current assumptions.

[Teakowa]

Milestone complete: sub-issues #56–#61 and gate #62 are closed with embedding/transport/consumer evidence (commits 03115d9, 58a9dde); see the gate writeup.