feat: add trix use and dependency-aware commands

[scarmuega]

Summary

Makes consuming an existing published protocol a first-class trix workflow.

• trix use <scope>/<name>[:<version>] pulls the OCI artifact from the registry, caches it under .tx3/tii/<scope>/<name>/<version>/, and records a pinned [interfaces.<alias>] entry in trix.toml.
• An external protocol is modelled as an interface, not a dependency: the project's protocol compiles in complete isolation and never ingests one. It is an orthogonal interaction link — a protocol you invoke/codegen/inspect against, consumed via its published TII. No source stitching, no tx3 language changes.
• A single canonical reference grammar (src/refs.rs) drives every protocol/tx string: CLI flags, trix.toml ref values, error messages.

Why "interface" (not "dependency")

A dependency is a build-graph edge — remove it and the build breaks. These protocols are not inputs to the project's build at all; removing every declared one changes zero bytes of output. The relationship lives at the interaction layer, mirroring Solidity (you don't compile a deployed contract, you hold its interface and call it). The artifact trix actually consumes is the TII — the Transaction Invoke Interface.

Normative vs informative: the published main.tii is the only artifact any command consumes. The cached main.tx3/README.md are kept purely as human references — never compiled or treated as authoritative.

Layering

The whole consume operation lives in interfaces::add(config, AddRequest) -> AddOutcome. The command layer (use_cmd::run) only maps Args → AddRequest and AddOutcome → view. interfaces is the single home for this business logic; commands stay thin.

Reference grammar

widget · acme/widget · acme/widget:0.1.0 · transfer · widget::transfer · acme/widget:0.1.0::transfer. A token with / is a registry ref, else an alias; :: separates protocol from tx; a bare tx targets the project. ProtocolRef/TxRef are typed (FromStr/Display/serde); a separate Resolver maps a parsed ref to the project or a declared interface.

trix.toml

[registry]
url = "https://oci.tx3.land"   # optional; defaults to DEFAULT_REGISTRY_URL

[interfaces.widget]
ref    = "acme/widget:0.1.3"   # ProtocolRef::Registry, concrete pinned version
digest = "sha256:..."          # lockfile-style OCI manifest digest

interfaces is #[serde(default, skip_serializing_if = "is_empty")] — existing projects are unaffected and round-trip unchanged.

How commands account for interfaces

The toolchain splits into project-only and consuming commands; interface machinery (validate_interfaces + restore_all) lives only in the consuming set.

• build — strictly project-only: produces the project's own TII and nothing else. Symmetric with check.
• check — strictly project-only: parses/analyzes only the project's main.tx3. An interface's source is the publisher's responsibility; re-analyzing it would only surface diagnostics the consumer cannot act on.
• invoke --from <PROTOCOL_REF> — selects which protocol's TII to invoke against (project's freshly built TII, or the interface's cached main.tii); tx chosen interactively.
• codegen (unstable path only) — one client per protocol from each one's TII.
• inspect tir --tx <TX_REF> — bare tx → project (lowered from the author's source); alias::tx / scope/name:ver::tx → interface, with IR decoded straight out of the normative cached .tii (it carries the encoded TIR per tx). The informative .tx3 is never read.
• publish — behavior unchanged; OCI helpers shared via src/oci.rs.

Principle: the published TII is the contract. Interface source is never recompiled, anywhere.

Cache & restore

Unified layout .tx3/tii/<scope>/<name>/<version>/{main.tx3,main.tii,README.md,metadata.json} — the project's own built TII and every fetched interface share the same tree (project uses [protocol] scope, or local when absent). Version-keyed (project-local + one entry per (scope,name) ⇒ no collisions; content identity guarded by digest). restore_all is a no-op with no interfaces; per entry → Valid (use cache) / Missing (fetch) / Invalid (hard error, trix use --force). The trix.toml digest is the lockfile, verified every restore.

Codegen (interface-aware on the unstable path only)

src/commands/codegen_legacy.rs (default build) is reverted to main verbatim — backward compatibility, single-protocol, unchanged layout. The unstable src/commands/codegen.rs delegates to tx3c codegen --tii, builds the project TII and uses each interface's cached published TII (no recompile). Output layout is unified — always <output_dir>/<name>/ per protocol regardless of interface count (a deliberate one-time break confined to the unstable path).

Key behavior decisions

• trix use requires a registry ref (alias-only rejected at parse); trix.toml rejects alias-only / latest refs (it is a pinned lockfile).
• Missing [registry] falls back to DEFAULT_REGISTRY_URL (oci.tx3.land) so cloned projects with a cached interface work zero-config; registry only contacted on a cache miss.
• No concrete version resolvable → hard error directing at the publisher (no sha256-… pseudo-version leaking into trix.toml/cache).
• Digest mismatch is surfaced directly (no silent refetch past a lockfile disagreement).

Commits

1. feat: add trix use and dependency-aware commands
2. fix: resolve registry URL through a default instead of erroring
3. fix: keep cache dirs version-keyed; drop sha256 pseudo-version fallback
4. refactor(invoke): protocol-only --from, drop no-op tx flag
5. fix: address review correctness/hygiene items
6. refactor: simplify per /simplify review (unify validators, typed CacheStatus)
7. refactor(codegen): move dependency-awareness to the unstable path
8. docs: add the protocol-interfaces design doc
9. refactor(use): move business logic into the module (thin command layer)
10. refactor: move Resolver out of refs into interfaces::resolve
11. refactor: model external protocols as interfaces, not dependencies — rename throughout; build/check strictly project-only; unified .tx3/tii/ layout; inspect tir decodes TIR from the normative .tii; design doc rewritten

Test plan

• src/refs.rs unit tests (grammar round-trip + rejections), convention registry_url unit tests, codegen_targets unit tests (gated unstable)
• tests/e2e/use_command.rs — 11 tests, incl. inspect tir against an interface decoding TIR from a tx3c-generated fixture TII (alias + full-ref forms), digest tamper, alias-only/latest toml rejection, check project-only with a declared interface, no-interfaces-unchanged
• tests/e2e/codegen_deps.rs — #[cfg(feature = "unstable")], unified per-protocol subdir layout with and without interfaces
• Default build/clippy clean; git diff main -- src/commands/{check,codegen_legacy}.rs empty (backward-compat guard)
• cargo build --features unstable + clippy clean; unstable unit + codegen_deps e2e pass
• Existing lib + e2e green (the two pre-existing env-dependent happy_path failures — codegen_generates_bindings_from_fixture, devnet_starts_and_cshell_connects — fail identically on clean main)
• Manual smoke against real oci.tx3.land

Follow-ups (out of scope)

trix publish recording its own interfaces; cache GC for --force repins; discovery commands.

🤖 Generated with Claude Code