Wado

Dependency Management — Implementation Plan

This plan sequences the work to make external Wado dependencies (registry and git) usable end to end. It builds on two settled WEPs:

wado publish now works: a component is built, its [package] metadata is embedded, and wkg oci push uploads it as an OCI artifact. The registry can therefore hold packages — but nothing on the consuming side can yet pull one. Closing that loop is the goal.

Current State

Done

Gaps

Guiding Principles

Phases

Phase 0 reshapes the CLI so later phases attach dependency work to the right command. Phases 1–4 then form the critical path to "a registry dependency compiles". Phases 5+ are follow-ups, orderable independently.

Phase 0 — Subcommand split (compile pure, build new)

Establish the primitive/orchestrator boundary before wiring dependencies.

Phase 1 — OCI registry provider

Give resolve real registry data. A published Wado package is a standalone Wasm Component Model artifact (wado publish → wkg oci push): one application/wasm layer under a application/vnd.wasm.config config. So a registry dependency resolves to a prebuilt component, not a Wado source tree — it carries no transitive Wado dependencies and no source entry module.

Phase 2 — Dependency cache + wado fetch

Materialize resolved packages on disk so the compiler can load them.

Phase 3 — Lock file in the build path

Make the build core lock-aware (inherited by run / serve / test / publish). The pure compile primitive stays lock-free.

Phase 4 — Registry/git deps reach the compiler

Wire the resolved graph into the compiler. A registry dependency is a prebuilt CM component, so — unlike a path/source dependency that compiles into the consumer — it is consumed across the Component Model boundary via Wasm CM Component Import (the provider-metadata fast path when the component carries Wado GC-type metadata, else the canonical ABI). This is the key modeling decision Phase 4 must settle: ModuleSource::Dependency { path } today loads Wado source; a prebuilt-component dependency needs its own representation (the cached .wasm + its WIT), distinct from source deps.

Phase 5 — Dependency-editing CLI

The manipulation commands from the CLI WEP.

Phase 6 — Git provider

Designed in detail in the git dependency design: a git dep is a source dependency (compiled in like a path dep), cloned to a ghq-compatible Wado root with per-version git worktrees, wado clean as their GC.

Phase 7 — PubGrub resolver

Replace the single-pass greedy resolver with PubGrub for backtracking and precise conflict errors.

Phase 8 — Remaining WEP surface

Registry Kiln generators

Redesign (Kiln WEP "Protocol revision 3"). Options move from an opaque CBOR list<u8> blob to a typed WIT argument on generate, in each generator's own world. This retires the describe-options mechanism (the options shape is read directly from the generator's component WIT) and the whole options-blob subsystem. The [x] items below under "Add the describe-options export" are superseded — the encoder/decoder/synthesis landed on this branch and are reverted by the redesign (a shallow wound, all within this branch). See the new work list at the end of this subsection.

A Kiln generator can be published (gale is, at ghcr.io/wado-lang/gale/core-kiln-generator), but a project can only consume one from a local path today (example/hello-packages uses module: "../../../package-gale"). Consuming a published generator (module: "wado-lang:gale", a [build-dependencies] registry entry) needs:

Revision 3 typed-options work list

The redesign replaces the options-blob subsystem with typed WIT arguments:

Milestones

Open Questions