Converge source-language workflows on an explicit provider boundary

[Teakowa]

Parent: #242
Protocol contract: wrightkit/language-provider-protocol#16

Goal

Converge Wright's source-language product workflows on one explicit, entry-based provider boundary: Wright identifies the user-selected source target and language, then delegates language-specific project discovery and semantics to the owning implementation.

The boundary supports raw Workshop in-process and OPY through LPP without making Wright understand OPY project structure or exposing LPP transport/document mechanics to the product layer.

Context

The source languages have different real source/project models:

• Raw Workshop is a single-source format. It has no language-level multi-file project model.
• OverPy owns #!mainFile, #!include, preprocessing, macros, and the resulting source closure.
• DEL/OSTW owns file/directory project discovery, ds.toml, imports, and its source closure.

Wright must not invent a generic workspace scanner or preload every source-language document. The product-level question is: what source target did the user select, and which language owner should handle it?

For CLI invocation, relative paths are resolved from the current working directory. The source-language owner, not Wright, determines the effective project entry/root and dependent source closure according to that language's rules.

Approved design

wright <command> <path>
        |
        v
resolve user input from cwd
        |
detect/select source language
        |
        +-- Workshop --> in-process workshop-rs
        |
        +-- OPY -------> LPP adapter --> opy-rs provider
        |
        `-- DEL/OSTW --> future provider --> deltin-rs

Wright product boundary

The Wright-owned seam carries only the product information needed to invoke a source implementation:

• source language;
• user-selected entry path or source target;
• invocation context needed to resolve that target, with the CLI current working directory as the default base for relative paths.

It does not expose provider process lifecycle, DocumentSet, provider AST/HIR/WIR, or a Wright-owned project/module graph.

Language-owner behavior

• Workshop: Wright reads the selected Workshop source and uses workshop-rs in-process. No project discovery or provider process is required.
• OPY: Wright passes the selected OPY entry to the OPY provider. opy-rs owns #!mainFile, includes, preprocessing/macros, project/source closure, source diagnostics, provenance, and compilation.
• DEL/OSTW: when provider-backed delivery is introduced later, deltin-rs owns file/directory project discovery, ds.toml, imports, and project/source closure. DEL is not an implementation target for Make Wright CLI CI-ready for real Workshop and OverPy projects #242.

Wright must not infer an OPY/DEL project root merely from the CLI working directory and must not recursively collect source-language files as a substitute for owner project loading.

LPP adapter boundary

LPP remains the process/wire contract, not the Wright product model. The adapter translates the entry-based Wright request into the owner-published LPP entry/project-loading contract from language-provider-protocol#16, and translates provider results back into Wright-owned outcomes.

Wright must not recreate the previous client-supplied full-DocumentSet project-loading model for provider-backed OPY. Unsaved editor overlays, generalized workspace synchronization, and other LSP-oriented document-state machinery remain deferred until a real language-service requirement needs them.

Result boundary

The seam preserves three distinct result classes:

1. source-language diagnostics produced by the language owner;
2. provider/process failures represented as structured machine-readable failures;
3. Wright-owned lint/analyze findings produced from canonical Workshop semantic evidence.

Provider-backed OPY compilation returns canonical Workshop output and the source/provenance information available through the approved owner/protocol contract. Wright may parse/validate canonical Workshop data with its direct workshop-rs dependency, but it must not consume OPY-internal AST/HIR or recreate OPY semantics.

Source file identity and source locations must survive the boundary sufficiently for diagnostics and truthful provenance. When canonical evidence cannot be mapped to authored OPY, Wright must represent it as unmapped/generated/canonical evidence rather than fabricate a source location. Wire-specific document versions and UTF-16/LSP coordinate details remain adapter/protocol concerns rather than product concepts.

Scope

• Maintain the smallest Wright-owned entry-based source-provider seam used by check, compile, and the canonical handoff for lint / analyze.
• Make provider selection/injection explicit in the relevant driver/language-service path; prohibit silent source-language fallback from provider-backed OPY workflows.
• Keep raw Workshop on the direct in-process workshop-rs path.
• Adapt the LPP client/runtime behind the product seam rather than exposing LPP request/session types to product workflows.
• Consume the owner-published LPP entry/project-loading contract; do not add Wright-side OPY project loading.
• Preserve owner diagnostics, structured provider failures, source identity, and truthful provenance required by Make Wright CLI CI-ready for real Workshop and OverPy projects #242.

Non-goals

• A generic Wright workspace/module graph shared across languages.
• Wright-side recursive OPY/DEL source discovery.
• Moving OPY, DEL/OSTW, or Workshop semantics into Wright.
• Exposing provider AST/HIR/WIR to Wright product code.
• General LSP document synchronization, unsaved overlays, or editor workspace state in this milestone.
• Designing provider distribution, caching, or downloads owned by Design lightweight first-party language provider distribution and lazy loading #240/Bootstrap and resolve the first-party OPY provider #244.
• A generic plugin ABI, dependency system, or marketplace.
• Implementing DEL/OSTW provider delivery in Make Wright CLI CI-ready for real Workshop and OverPy projects #242.
• Unrelated Wright crate/API cleanup.

Acceptance criteria

• wright <command> <relative-path> resolves user input relative to the invocation cwd; an explicit/absolute path works without requiring execution from the project directory.
• Wright delegates project/root/source-closure discovery to the source-language owner rather than deriving it from cwd or scanning source files itself.
• Raw Workshop remains a single-source, in-process workshop-rs workflow with no provider/network requirement.
• Provider-backed OPY receives the selected entry target through the LPP entry/project-loading contract and opy-rs remains responsible for #!mainFile, includes, preprocessing/macros, source closure, diagnostics, provenance, and compiler behavior.
• An LPP-backed OPY implementation is selected through the Wright product seam with no silent fallback to static Wright OPY semantics.
• LPP transport/document/session details are contained in the adapter and do not become Wright product concepts.
• Provider/process failures are structurally distinct from source diagnostics.
• Provider-backed OPY can supply canonical Workshop output plus sufficient truthful provenance for the Make Wright CLI CI-ready for real Workshop and OverPy projects #242 lint/analyze workflow where mapping is supported, without exposing OPY-internal IR or duplicating OPY semantics in Wright.
• Unmappable canonical/generated evidence is explicit rather than assigned fabricated OPY source locations.
• Existing unaffected CLI and machine-readable contracts remain regression-green.
• Independent ablation confirms that the product seam and canonical/provenance handoff exercised by the real-project workflow are required.

Dependencies / ownership

• Parent: Make Wright CLI CI-ready for real Workshop and OverPy projects #242.
• Design lightweight first-party language provider distribution and lazy loading #240/Bootstrap and resolve the first-party OPY provider #244 own provider distribution/resolution/bootstrap only.
• Run real OPY check and compile workflows through the first-party provider #245 proves the provider-backed real OPY check / compile product path.
• Preserve Wright lint and analyze semantics across the OPY provider boundary #246 proves the canonical semantic/provenance handoff for Wright-owned lint / analyze.
• wright: CLI target resolution, language selection, product seam/adapters, canonical lint/analyze orchestration.
• language-provider-protocol#16: entry/project-loading process/wire contract; any additional wire change requires new concrete workflow evidence.
• opy-rs: OPY project discovery, #!mainFile, includes/preprocessing/macros, semantics, diagnostics/provenance, compiler/provider implementation.
• deltin-rs: DEL/OSTW project discovery/import semantics and future provider implementation.
• workshop-rs: canonical Workshop semantics and Wright's direct in-process Workshop core.

[Teakowa]

Current reality update (2026-09-03): the approved Wright-owned entry-based SourceProvider seam is on main and still preserves the intended ownership boundary: Wright carries language + selected entry + cwd, while OPY project discovery (#!mainFile, includes, preprocessing/macros, source closure) remains owner-side.

The production cutover is not complete. Ordinary CLI workflows still construct a native CompilerSession; provider-backed real OPY workflows remain the work of #245/#246. Existing source-provider tests inject a recording provider and prove the seam/handoff, but they are not production CLI evidence.

Keep #243 open until the concrete LPP/production CLI path is exercised end to end by #245/#246, including provider failures and provenance behavior. No generic Wright workspace scanner/module graph is required.

[Teakowa]

Current reality (2026-09-05): the entry-based seam and production OPY check / compile path are now exercised, and the protocol-side entry-loading gap has been resolved by language-provider-protocol#16.

PR #252 proves the user-selected entry reaches the first-party provider without Wright reconstructing the OPY project loader, and its entry-forwarding ablation fails the pinned real-project checks closed. That satisfies the check/compile side of this boundary.

Keep #243 open only for the remaining result-boundary acceptance owned by #246: Wright lint / analyze still need a demonstrated canonical semantic/provenance handoff with truthful mapped or explicitly unmapped evidence. The body has been updated to consume the existing LPP entry contract rather than describing a future conditional protocol extension.