Design lightweight first-party language provider distribution and lazy loading

[Teakowa]

Parent milestone: #242

Goal

Decouple Wright's release cadence from faster-moving first-party source-language implementations by distributing them as independently released LPP provider executables that Wright can resolve, install lazily, and reuse locally.

For #242, OPY is the only provider implementation target. workshop-rs remains Wright's direct build-time canonical Workshop dependency, and DEL/OSTW is a future consumer only after the OPY path is proven on real projects.

Context

Wright currently links source-language implementations directly, so ordinary owner-side releases can force Wright dependency churn even when Wright's product/tooling layer has not changed.

LPP already provides the process boundary. This issue owns only the smallest first-party distribution and local resolution layer needed to make that process boundary practical. It must not become a package manager, registry ecosystem, plugin framework, or project dependency system.

The intended ownership is:

wright
├─ workshop-rs            direct stable canonical core
└─ provider resolver
   └─ local executable
      └─ LPP client
         └─ opy-provider  released by opy-rs

Source entry/project semantics are defined by #243 and the language owner, not by the distribution layer.

Approved design

Distribution source

First-party OPY provider binaries are published by wrightkit/opy-rs through GitHub Releases. Wright does not maintain a separate provider registry service or package index.

A release provides a deterministic target-specific provider archive and integrity checksum for each supported Wright target. The archive contains the provider executable and only packaging metadata required to unpack/install it.

Distribution metadata must not duplicate runtime language capabilities, LPP protocol negotiation, source-language dependencies, or workshop-rs compatibility. Those remain owner/runtime concerns and are negotiated through LPP where applicable.

Resolution precedence

When an OPY workflow requires a provider, Wright resolves it in this order:

1. explicitly configured local provider executable;
2. already installed active first-party OPY provider;
3. lazy bootstrap of the latest stable first-party OPY provider from the owner GitHub Release.

Raw Workshop workflows and unrelated Wright commands never resolve, download, or spawn the OPY provider.

The resolved result is a local executable path handed to the existing LPP runtime / ProviderRegistry; #240 does not introduce a second provider runtime.

Local installation state

Use a small per-user, versioned provider store with one active version pointer, conceptually:

<wright-data>/providers/opy/
├─ <version>/<target>/opy-provider
└─ active

The versioned directory and active pointer exist only to support atomic installation/update, offline reuse, and preservation of the previous working provider if an update fails. They are not a project lockfile or dependency graph.

No provider state is written into the user's source project.

Lazy bootstrap

On first OPY use when no explicit or installed provider exists:

1. resolve the latest stable opy-rs provider release for the current supported target;
2. download to temporary storage;
3. verify the published SHA-256 checksum;
4. unpack/install into a versioned temporary/final location;
5. activate only after the complete artifact has been verified and installed successfully.

A failed or partial download/install never becomes active. Offline/missing-provider failures are explicit and must not silently fall back to Wright's old static OPY implementation.

Updates

Normal wright check/compile/lint/analyze invocations do not contact GitHub merely to check for newer provider versions.

Provider updates are explicit, e.g. a dedicated wright provider update opy-style action. This keeps ordinary CI runs deterministic/offline-friendly while still allowing opy-rs to release independently from Wright.

The exact CLI spelling may follow Wright's existing command conventions during implementation; the contract is that routine source commands do not perform automatic update polling.

Product integration boundary

#240 ends once it resolves a verified local OPY provider executable. #243 owns how Wright passes the user-selected OPY entry/path through the LPP adapter and how owner diagnostics/canonical Workshop output/provenance return to Wright.

opy-rs remains responsible for #!mainFile, includes, preprocessing/macros, project/source closure, semantics, diagnostics/provenance, and compiler behavior. Distribution must not require Wright to discover OPY project files.

Scope

• Define and implement first-party OPY provider release artifact naming/selection for supported Wright targets.
• Resolve explicit local providers and installed first-party providers.
• Lazily bootstrap a missing first-party OPY provider from opy-rs GitHub Releases.
• Verify downloaded artifacts and activate installs atomically.
• Reuse installed providers offline.
• Provide an explicit update path without automatic update polling on normal source commands.
• Feed the resolved executable into the existing Wright LPP runtime / ProviderRegistry.
• Support migration from the static OPY integration to the Converge source-language workflows on an explicit provider boundary #243 provider-backed product path.
• Validate the design against a pinned Bastion or Overwatch-AI-PVE workflow before generalizing it.

Non-goals

• No npm/crates.io-style registry or package index.
• No dependency solver or transitive provider dependency graph.
• No wright.lock or project-level provider lockfile/state.
• No generic plugin ABI or dynamic-library/FFI framework.
• No provider marketplace or third-party discovery service.
• No runtime/dynamic replacement for Wright's direct workshop-rs dependency.
• No periodic/TTL provider update checks during normal source commands.
• No LPP redesign for downloading, version selection, or installation.
• No OPY/DEL semantics or project discovery in Wright.
• No DEL/OSTW provider implementation in Make Wright CLI CI-ready for real Workshop and OverPy projects #242.
• No speculative distribution abstraction for future provider ecosystems.

Acceptance criteria

• Ordinary opy-rs implementation/provider releases do not require a Wright release.
• workshop-rs remains Wright's direct stable canonical Workshop dependency.
• opy-rs owns and publishes the first-party OPY provider artifact.
• Wright resolves an OPY provider through explicit local configuration, installed active provider, or lazy first-use bootstrap, in that precedence order.
• Raw Workshop and unrelated workflows perform no OPY provider network or process work.
• A downloaded provider is verified before activation; failed/partial installs cannot become active.
• An installed provider can be reused with no network access.
• Missing provider/offline/bootstrap failures are explicit and do not silently select the static OPY implementation.
• Normal source commands do not poll for updates; provider update is an explicit action.
• Distribution metadata does not duplicate LPP runtime capability/protocol negotiation.
• Provider resolution produces a local executable consumed by the existing LPP runtime / ProviderRegistry rather than introducing another execution abstraction.
• No project-level lockfile, registry/index service, dependency solver, or provider dependency graph is introduced.
• A pinned Bastion or Overwatch-AI-PVE workflow validates lazy install plus provider-backed execution before the pattern is copied to DEL/OSTW.
• Independent design ablation confirms that versioned local storage, active selection state, artifact integrity metadata, and any other retained distribution state are required by the approved OPY workflow.

Dependencies / ownership

• Parent milestone: Make Wright CLI CI-ready for real Workshop and OverPy projects #242.
• Converge source-language workflows on an explicit provider boundary #243 owns the entry-based Wright product/provider boundary and source/project handoff.
• wright: provider resolution, bootstrap, local installation/update state, and integration with the existing LPP client.
• opy-rs: OPY provider executable and GitHub Release artifacts.
• language-provider-protocol: process/wire contract only; no distribution ownership.
• workshop-rs: canonical Workshop semantic core used directly by Wright and independently by source-language implementations.
• deltin-rs: future DEL/OSTW provider owner after OPY evidence.

Readiness

Design direction is resolved and implementation can proceed. Keep the first implementation OPY-specific and small; generalize only after the pinned real-project workflow demonstrates a repeated need.

[Teakowa]

Current reality update (2026-09-03): the distribution/resolution design is implemented structurally, but the consumable distribution acceptance evidence is not complete.

Wright's first-party OPY resolver is on main, and opy-rs now contains the provider release workflow. However, opy-rs/releases/latest is still v0.1.12 with no provider assets, so a clean Wright install cannot lazy-bootstrap opy-provider from the real GitHub Release surface yet.

Keep this issue open until the first provider-enabled OPY release is published and the clean-install resolution path is independently rerun against the observed archive/checksum. wrightkit/opy-rs#169 is the current release vehicle. The design itself does not need to be reopened or generalized into a registry/package-manager abstraction.

[Teakowa]

Dependency-boundary clarification from current main: Wright still pins workshop-rs = 0.1.11, opy-rs = 0.1.5, and opy-compiler = 0.1.5, while current opy-rs 0.1.13 pins workshop-rs = 0.1.16. Do not advance the milestone by bumping Wright's static opy-rs dependency; that would recreate the build-time dependency churn this issue exists to remove (and may split canonical workshop-rs types across versions).

The next product integration should consume the independently released opy-provider through LPP. The legacy direct wright-opy dependency may remain only where an existing non-source workflow still requires it during migration, but OPY check/compile/lint/analyze must stop using it before #240/#245 are considered complete. A later removal or providerization of the remaining Workshop→OPY reconstruction dependency should be based on its actual product requirement rather than blocking the current real-project source workflow.