Repository navigation
Description
Goal
Establish an evidence-backed current-reality map of Wright's workspace and crate boundaries, then define the smallest durable Wright-owned product/tooling layer model that should guide later implementation work.
This issue is an architecture/current-reality audit. It does not itself move, merge, delete, or rewrite production code.
Context
Wright currently spans multiple crates for core/result contracts, IR/integration types, analysis, orchestration, language adapters, provider/LPP integration, product surfaces, transforms, benchmarks, and consumer support. Some boundaries represent durable responsibilities; others may be historical or migration-era seams.
The audit must distinguish current implementation reality from intended architecture. Current reality comes from Cargo dependency edges, public APIs, concrete consumers, source layout, tests, CI, provider integrations, and product workflows. Current architecture contracts live under docs/architecture/; ADRs record decision history rather than proving current implementation state.
Existing issues such as #155, #182, and #243 already own cutover-dependent removals or provider/source-language convergence. This audit may identify those boundaries as transitional or drifted, but must not bypass their dependencies by treating structural cleanup as authority to complete them.
Scope
- Map every Wright workspace crate to its current public APIs, dependency edges, concrete consumers, runtime/product role, and repository ownership constraints.
- Classify each boundary as one or more of:
- durable Wright-owned product/tooling responsibility;
- transitional/cutover-dependent boundary;
- support/test/benchmark fixture rather than architecture layer;
- consolidation/removal candidate requiring a separate executable Issue.
- Identify pass-through layers, re-export-only seams, duplicate representations, one-off abstractions, overlapping responsibilities, and dependencies whose continued separation lacks a concrete contract or consumer.
- Establish the intended dependency direction between retained Wright-owned responsibilities without introducing a target crate count.
- Record where current implementation reality conflicts with the current architecture contract, including legacy source-language or canonical Workshop ownership that remains temporarily present in Wright.
- Distinguish changes that can be implemented independently from changes deferred to existing cutover/provider/source-owner Issues.
- Update the current architecture contract only if the audit changes a durable intended boundary or dependency invariant.
- Create separately reviewable follow-up Issues for code changes only after dependency/consumer evidence establishes their scope and ownership.
Non-goals
- Moving, merging, deleting, or rewriting production code in this Issue.
- Continuing the real-project/provider integration milestone under Make Wright CLI CI-ready for real Workshop and OverPy projects #242/Converge source-language workflows on an explicit provider boundary #243/Run real OPY check and compile workflows through the first-party provider #245/Preserve Wright lint and analyze semantics across the OPY provider boundary #246.
- Removing
wright-opy,wright-ostw,wright-ir, or another source adapter/representation solely because its long-term ownership is external; cutover-dependent removals remain owned by their existing Issues. - Moving OPY, DEL/OSTW, or canonical Workshop semantics into Wright.
- Introducing a generic service/container/plugin/framework layer.
- Redesigning Wright public product APIs without a concrete consumer requirement.
- Mechanical crate-count, file-count, line-count, or dependency-count targets.
- Unrelated product features, CLI polish, release work, or lint-rule expansion.
Acceptance criteria
- Every current workspace crate is mapped to concrete responsibilities, direct dependency edges, and real consumers or support roles.
- Every boundary is classified as durable, transitional, support-only, or a separately actionable consolidation/removal candidate, with evidence for the classification.
- Overlap among core/result, IR/integration, language, driver/orchestration, consumer, transform, analyzer, LPP, and source-adapter responsibilities is explicitly identified rather than inferred from crate names.
- The intended Wright-owned dependency direction is documented and aligned with repository ownership: Wright does not become a second OPY, DEL/OSTW, or canonical Workshop semantic owner.
- Cutover-dependent findings are routed to their owning Issues instead of being silently absorbed into structural cleanup.
- Independently actionable code changes discovered by the audit are represented by separate executable Issues with explicit scope, ownership, preserved contracts, and verification evidence.
docs/architecture/is updated only where the audit changes a durable current contract; ADRs are added only when a durable architectural choice requires rationale/history.- Completing this Issue requires no production-code modification.
Metadata
Metadata
Assignees
Labels
Type
Projects
- StatusShow more project fieldsDone
Activity
[-]Rationalize Wright crate boundaries around product and tooling ownership[/-][+]Audit Wright crate boundaries around product and tooling ownership[/+]e54-bot commentedon Sep 7, 2026
Audit status
Read-only current-reality audit completed against
ae5c92998ecfeb220c9aa5436c5c0ef36a1dad98(remotemain, checked 2026-09-07). All 13 workspace crates were inspected. This is an evidence/classification result, not approval to consolidate crates, completion of provider cutover, or closure of this issue.The clean local checkout was
d66fee19483d4ec2d054de33dfee121f2854ea80. Comparing it with the remote commit showed changes only toAGENTS.mdand architecture/document routing; production sources, Cargo files, tests and CI are identical. Current architecture documents were read directly from the audited Git objects. No checkout, branch, source, test, documentation, Cargo or issue-body changes were made. An independent read-only reviewer challenged boundary necessity and consumer claims.1. Current reality
Workspace, dependencies and consumers
All packages have
publish = false. This establishes the current distribution policy, not absence of Git/path consumers or freedom to break the declared embedding API. Release packaging includeswrightandwright-lsp;wright-serveandwright-toolare real source-tree binary targets but are not copied into those release archives.wright-benchandwright-consumerare support targets. See workspace manifest, embedding contract, and release packaging.In the following map, short names mean
wright-<name>. N means a declared normal workspace dependency; D means a declared dev-dependency. These are manifest edges, not assertions that every edge has a caller. The later cleanup findings identify unused edges.hirparses/validates/dumps the serializedwright/opy-hirprotocol and converts it to internal HIR;providerexports a synchronous check trait, error and diagnostic/span/severity/status types;signaturesonly re-exports the canonical owner trait. This is not the product result/envelope home.hir::parse_str -> to_ir; analyzer'swright-toolbinary also uses that path. Driver'sWorkshopProviderimplements the core check trait; driver diagnosticstatususes its type. Language and OPY declare core without source references.core/tests/{hir_ingest,ir_convert,ir_lower}.rs, analyzer legacy-input process tests, driver Workshop-provider tests; OSTW declares a dev edge without references. Mixed transitional HIR boundary + live Wright diagnostic/integration responsibility; not removable wholesale. API bridge raw providerarena/error/format/idsare forwarding shims toworkshop-rs. Canonical WIR is consumed fromworkshop_rs::wir, not independently implemented here.wright-toolinvoke lowering through core conversion. Analyzer, language, driver and transform use canonical infrastructure through the shims. Core consumes the HIR. OPY and OSTW declare IR edges but have no Rust references to it.ir/tests/models.rs, core conversion/lowering tests and analyzer protocol fixtures. Transitional, explicitly in #155; live legacy input prevents declaring it dead. API lowering driver dispatchSemanticServicerequest/response API; also thewright-toolJSON-lines executable.tests/{analysis,cfg,registry,semantic_index,service,workshop_integration}.rs; CLI dev-dep supports product assertions. Durable Wright analysis/query responsibility, with transitional binary ingress/dependencies. API tool executable driver serviceCompilerSession, input/config, diagnostics,Envelopeand result types, tool service, validated edit transactions/rename, progress, source-provider integration, OPY provider resolution and raw Workshop adapter. This is the actualwright-result/v1andwright-embedding/v1facade.wright-serveinvoke session/tool APIs; language reuses edit validation/rename; bench and consumer exercise the same facade.tests/{driver,service,edit,convert,workshop_contract,workshop_provider,workshop_signature_context,source_provider,lpp,provider_edit}.rs; external-process mock-provider CI. Durable product integration/facade, containing transitional source paths. API results editswright: command/config selection, presentation and CI/JSON rendering, completion, self-update and provider-update UX. Additional binarywright-servemaps JSON-lines/JSON-RPC to driver ToolService. No library target.wright_driver::Profile. User-facing process consumers are CLI/CI/install workflows.tests/{cli,serve,diagnostics_schema,update,workshop_real_projects}.rs, scenario/CLI/distribution gates. Durable product/runtime surface, not semantic ownership. dispatch serveopy_rs::compile_with_overlay_outcomethen ownerCompiler::compile_hir. It does not itself contain OPY lowering.cargo test -p wright-opytherefore must not be mistaken for a local adapter regression suite; substantive callers are tested in driver/language/product suites. Its reconstruction fixtures are also concretely consumed bydriver/tests/convert.rsandcli/tests/cli.rs, so fixture-only directories are not automatically dead. Transitional static adapter, #155 after #245/#246. entire adapterdiag,lexer,Project/FileRecord/ResolvedImport,OstwOutcome/SemanticOutcomeand compile-with-overlay functions.compatibility/ostw/infrastructure is separate evidence ownership under #182. Currently required native integration adapter; historical projection boundary is transitional/revisable. No DEL provider cutover or whole-crate removal follows from this audit. entire adapterProfile,run,Pass,PassStats/PassResult,FoldConstants. Pipeline validates WIR before/after mutation;offselects no passes,compat/aggressivecurrently select constant folding.Profile. OSTW's dev edge has no caller.tests/pipeline.rsand pipeline unit tests; driver/profile and benchmark workflows. Wright-owned profile/validation orchestration responsibility; crate consolidation candidate is conditional, not authorized. Semantics inside folding require the ownership qualification below. pipeline foldingwright-benchand uploads its report; release gate also runs the harness. Support/benchmark only, with a concrete separate executable role. harness benchmark CIrun_consumer/workflow library plus binary exercise compile/check/analyze/query and validated edits using the driver facade.tests/consumer.rsdrives the workflow; separate Cargo dependency set demonstrates use without direct IR/implementation imports. Support/test only, useful boundary evidence. manifest workflowDocument/DocumentStore, UTF-16 editor positions/ranges,LanguageService, diagnostics/hover/locations/completion/rename/tokens and analysis result types. Compiles source via static adapters, builds semantic index/findings, delegates transaction validation to driver.Analysisexposes OPY error/file types, and OSTW errors are converted to OPY-shaped errors.tests/{service,overlay,cross_file,perf}.rs; LSP protocol tests. Durable editor-neutral responsibility, transitional source coupling; necessity of a separate Cargo crate is unknown. API implementationlsp-typesand editor-neutral service results. No library API.tests/lsp.rs, native distribution smoke. Durable runtime/protocol boundary; a separate executable does not logically mandate a separate Cargo package. server packagingJsonRpcClient/ClientConfig/ClientPhase,ChildProcess, registry/configuration, negotiatedLanguageProvider/StdioLanguageProvider, typed LPP requests/results/capabilities and structured failures; stdio lifecycle/framing/correlation/timeouts.tests/{unit,mock_provider}.rs; driver LPP/provider-edit suites; CI builds a pinned externallanguage-provider-protocolmock. Durable Wright client/runtime responsibility; the protocol repository owns the wire contract. API provider trait CIFor completeness, the direct non-workspace package edges in the crate manifests are:
These are declared edges, including unused residue. Root owner pins are
workshop-rs = 0.1.18,opy-rs = 0.1.18, anddeltin-rs = 0.1.2. This is a direct-edge audit, not a claim that their transitive dependency graphs or release cadences are equivalent. Every row is grounded in its crate Cargo.toml.Runtime paths and ownership drift
The product cutover is partial, not absent. CLI
check/compilepassprovider_workflow = true; OPY selection then usesSourceBackend::Provider. Ordinarylint/analyze/inspect/convertpass false and retain native dispatch unless an explicit provider path selects it.SessionConfig::default()is still native. Provider sessions resolve/initialize the OPY process and pass an LPP entry, while raw Workshop usesworkshop-rsin-process. CLI session dispatch source adapterLegacy source semantics remain executable in Wright. Protocol input and the explicitly selected
WRIGHT_ADAPTER_PATHroute parse the serialized OPY HIR in core, convert to Wright IR, and lower inside Wright.wright-tool --programrepeats this ingress independently of driver. This directly differs from the owner contract and integration contract; it is Remove residual static OPY implementation after provider cutover #155 cutover residue, not a durable Wright compiler layer. The native adapter itself delegates semantics toopy-rs; do not confuse its ownercompile_hircall with the separate Wright-owned legacy lowerer. bridge path fallback toolEditor integration is not source-neutral today. LanguageService compiles through OPY/OSTW adapters, dispatches on source token kinds, consults OPY manifest shapes, and stores OPY error/file types for both languages. In particular,
ostw_error_to_opyis a second diagnostic projection, not a neutral owner result. Some token presentation is legitimately Wright/editor work; this evidence does not prove every token switch is an illicit parser. It does show that the shared-service/owner-input intent is not fully realized. Any replacement must preserve owner provenance and edit refusal; do not move source semantics into a new Wright language module. language implementationThree provider abstractions overlap without being interchangeable:
core::provider::LanguageProvider: synchronous single-document check, implemented by raw WorkshopProvider and called by session Workshop diagnostics.driver::SourceProvider: selected-entry check/compile, product diagnostics, canonical Workshop text and provenance;LppSourceProvideris its production adapter.lpp::LanguageProvider: negotiated/session-oriented document and entry operations, compile/query/rename/edit-validation/reconstruction and structured transport failures.Their similar names/check operations are not proof that a universal provider trait is justified. Keep Converge source-language workflows on an explicit provider boundary #243's entry product boundary separate from process/wire concerns. Generic
ToolRequestand provider-edit request APIs currently containwright_lpp::DocumentSet/Position; this is a remaining product/wire coupling, not proof that the Converge source-language workflows on an explicit provider boundary #243 OPY entry path itself exposes those mechanics. Mutation/editor convergence remains Wire provider-driven mutation through Wright product surfaces #156 and the existing owner chain. core provider source provider tool API provider edit APIRepresentation duplication has different causes. Serialized OPY HIR in core plus internal OPY HIR/lowering in IR are transitional source-owner duplication. IR infrastructure re-exports and core signatures are forwarding paths with one owner type identity, not duplicate WIR implementations. Diagnostic/span families in core, driver, language and LPP have different contracts: driver uses 1-based source coordinates, language/LPP use editor/wire coordinates, and driver adds origin/stage/result framing. Those mappings cannot be deleted on name similarity. Core's
Statusalso appears in driver serialization. Provider artifacts are currently onlySourceProvenance::Unmapped; their generated spans are not authored OPY locations. types diagnostics editor coordinates provenanceTransform ownership needs a narrower decision than “move/keep crate”. Wright can own profile selection, validated transformation orchestration and product metrics.
FoldConstantsalso encodes arithmetic, boolean domination and Workshop call-name rewrites locally. Current evidence does not establish whether every such rule is a justified Wright transformation over owner semantics or a duplicated canonical/source semantic rule. Therefore no promotion of those rules to durable Wright semantic ownership, owner migration, or crate deletion is authorized here. Merely being a WIR pass or matching old OverPy output does not settle ownership. implementationThe current
docs/architecture/files establish responsibilities and dependency direction, not a mandatory crate inventory. Most differences above are implementation drift from that intent, not a reason to rewrite the intent. No new durable ownership contract is proposed by this audit.Evidence limits from CI
The CI run on the identical-code checkout passed Rust quality, OPY/OSTW integration, LPP integration, Workshop real projects, CLI/scenarios and benchmark jobs, but the overall run failed on macOS install.sh and Windows WinGet distribution jobs. This audit did not rerun builds/tests or reproduce those failures. The current main Release-please success is not a product-test result.
LPP CI explicitly supplies
LPP_MOCK_PROVIDERfrom a pinned protocol repository and runs client/driver/provider-edit suites; that is real protocol-consumer evidence, not proof of all real OPY project semantics. Adapter-only Cargo test commands likewise do not establish language completeness. LPP CI2. Architecture classification and non-mutating ablation
Retain the responsibility before deciding the packaging.
wright_drivercheckout embedding surface and breaks the driver-only consumer fixture. Retain this reusable facade/dependency entry. Its internal module split is revisable.wright-toolanalysis consumers reach through product orchestration, provider resolution and static source adapters. The existing downward analysis dependency and separate tool executable give concrete isolation evidence. Retain the current boundary; do not infer an external adopter forwright-toolfrom its tests.lsp-types. One observed production consumer is insufficient to establish an independent embedding requirement. Retain the responsibility/current layout; separate-crate necessity is unknown, especially while source/provider/edit contracts are unresolved.Thus durable product responsibilities are retained without freezing today's crate count. No unconditional whole-crate removal is established. Forwarding-only modules are identified, and small unnecessary edges are separately actionable below.
3. Intended dependency direction
These directions specify responsibilities and isolation; they do not optimize for a target number of crates.
4. Deferred work owned by existing issues
5. Executable follow-ups with already bounded scope
No follow-up issues were created, as requested. These are scopes suitable for separate executable issues, not changes performed or permission to bundle migration work.
Remove unused non-OPY manifest edges. Source/test scans found no references, includes, macro use or build scripts consuming
wright-language -> wright-core,wright-ostw -> wright-ir, or OSTW's dev edges towright-core/wright-opy/wright-transform/serde_json/sha2. Cut only those unused declarations; preserve all runtime code, public types, owner dependencies and compatibility artifacts. Risk: internal dependency/feature-unification change, so verify affected all-target builds/tests and workspace quality gates; restore/reclassify any edge shown to supply a required feature. No claim is made that removing a manifest edge alone removes a package transitively. OPY's analogous unused edges are recorded in the inventory but left to Remove residual static OPY implementation after provider cutover #155 to avoid splitting its cutover scope.Have CLI/bench use the existing driver Profile export. Change their
wright_transform::Profileimports/references towright_driver::Profileand remove those two direct transform manifest edges. Driver already exports the identical type; no profile values, pipeline, serialized metrics or CLI behavior should change. Verify CLI profile/result tests and benchmark harness build/execution. This reduces direct consumer knowledge without introducing a wrapper or requiring transform consolidation.The transform-as-driver-module observation is not an executable follow-up yet: external/API use and rule ownership must be settled first. Likewise, do not turn a signatures re-export observation into an independently scheduled #155 bypass. Any later whole-crate cut requires its own consumer/contract acceptance evidence.
6. Unknowns / decisions intentionally not made
publish=falsedoes not exclude Git/path consumers. No public API removal is authorized on that basis.Teakowa commentedon Sep 7, 2026
Architect review: the audit is accepted as the current-reality/architecture result for #265.
The audit establishes the crate/consumer/dependency map, distinguishes durable responsibilities from transitional/support boundaries, preserves the existing repository ownership model, and correctly leaves unresolved packaging questions (notably whole-crate
wright-transform,wright-language, andwright-lppconsolidation) as unknown rather than converting them into implementation work.Two independently bounded implementation follow-ups were created from the evidence:
Cutover-dependent findings remain with #155/#182/#243 and their dependency chains. No durable architecture contract changed, so no
docs/architecture/or ADR update is required by this audit.With the audit recorded and actionable findings routed to separate Issues, #265's acceptance contract is complete.