From 0dfe4842941af53286b62ef78d6876406c5ed15f Mon Sep 17 00:00:00 2001 From: Santiago Date: Tue, 16 Jun 2026 16:43:03 -0300 Subject: [PATCH 1/4] test(e2e): decouple the devnet round-trip from 01-basic-init MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Split the `trix test` devnet round-trip out of 01-basic-init into its own 04-devnet-roundtrip journey, and schedule it on the beta e2e job only for now. - 01-basic-init becomes the fast, fully offline gate (init → check → build, ~3s); it loses the runtime round-trip and runs on every channel. - 04-devnet-roundtrip carries the round-trip (init → test) with the same xfail on the known `CShell failed to get wallet utxos` signature. It's parked on beta while the trix fix (tx3-lang/trix#123) is unreleased — beta gets that release first, and the xfail auto-promotes there once it ships. Drop it onto stable once the fix is released there. stable journeys: [01, 02, 03]; beta journeys: [02, 03, 04]. Verified both split journeys against the released beta binaries (01 passes offline; 04 xfails on the known signature with the submit half still asserted strictly). Co-Authored-By: Claude Opus 4.8 --- .github/workflows/dx-e2e.yml | 14 ++++---- e2e/README.md | 28 +++++++++------ e2e/journeys/01-basic-init/journey.sh | 29 +++------------ e2e/journeys/04-devnet-roundtrip/journey.sh | 40 +++++++++++++++++++++ skills/add-e2e-journey/SKILL.md | 5 ++- 5 files changed, 74 insertions(+), 42 deletions(-) create mode 100755 e2e/journeys/04-devnet-roundtrip/journey.sh diff --git a/.github/workflows/dx-e2e.yml b/.github/workflows/dx-e2e.yml index e329cc0..fb0cc80 100644 --- a/.github/workflows/dx-e2e.yml +++ b/.github/workflows/dx-e2e.yml @@ -4,11 +4,11 @@ name: DX E2E # (install the channel via tx3up, cache it, run one journey) live in the local # composite action .github/actions/dx-e2e-run. # -# - stable: a comprehensive pass over *every* journey. Edge journeys whose -# `#@ min-tx3c` exceeds stable's tx3c install + skip (green), and auto-run -# once the feature graduates to stable. -# - beta: cherry-picked *edge-feature* journeys only (e.g. 02-lang-tour's -# tuples) — stable already covers everything broadly. +# - stable: the offline scaffold gate + lang-surface journeys. Edge journeys +# whose `#@ min-tx3c` exceeds stable's tx3c install + skip (green), and +# auto-run once the feature graduates to stable. +# - beta: edge-feature journeys (e.g. 02-lang-tour's tuples), plus the devnet +# round-trip (04), parked here for now while its trix fix is unreleased. # # Compat lives in one place: the journey's `#@ min-tx3c` header, enforced by the # runner's skip gate. Native runners only — a DX test must exercise the real @@ -56,7 +56,9 @@ jobs: fail-fast: false matrix: os: [ubuntu-latest, ubuntu-24.04-arm, macos-latest] - journey: [02-lang-tour, 03-lang-edge] # cherry-pick: edge-feature journeys only + # edge-feature journeys + the devnet round-trip, which is parked here for + # now (it's xfail on released channels until the trix fix ships). + journey: [02-lang-tour, 03-lang-edge, 04-devnet-roundtrip] steps: - uses: actions/checkout@v4 - uses: ./.github/actions/dx-e2e-run diff --git a/e2e/README.md b/e2e/README.md index 8506ac7..5771497 100644 --- a/e2e/README.md +++ b/e2e/README.md @@ -19,10 +19,12 @@ e2e/ ├── run.sh # entrypoint: resolve binaries, run journeys, summarize ├── lib/common.sh # logging + fail-fast assertion helpers └── journeys/ - ├── 01-basic-init/journey.sh # init → check → build → test (offline devnet round-trip) - └── 02-lang-tour/ - ├── journey.sh # init → swap in feature-dense main.tx3 → check → build → inspect tir - └── main.tx3 # feature-dense fixture (a copy of the lang's lang_tour example) + ├── 01-basic-init/journey.sh # init → check → build (offline scaffold validation) + ├── 02-lang-tour/ + │ ├── journey.sh # init → swap in feature-dense main.tx3 → check → build → inspect tir + │ └── main.tx3 # feature-dense fixture (a copy of the lang's lang_tour example) + ├── 03-lang-edge/ # newest lang features (functions, operators, tuples, doc-comments) + └── 04-devnet-roundtrip/journey.sh # init → test (real devnet round-trip: trix + tx3c + dolos + cshell) ``` A **journey** is a self-contained script that sources `lib/common.sh` and drives `trix` @@ -34,12 +36,14 @@ The journeys cover complementary axes: | Journey | Covers | Scope | |---------|--------|-------| -| **01-basic-init** | the default scaffold end to end, including a real devnet round-trip (trix + tx3c + dolos + cshell + resolver) | runtime | +| **01-basic-init** | the default scaffold through `init → check → build` — the fast, fully offline gate | compile/lower | | **02-lang-tour** | the breadth of the language surface — env, records/variants, lists/maps/tuples, policies/assets, spread, locals, and the full Cardano construct set — pushed through `check → build → inspect tir` | compile/lower | | **03-lang-edge** | the *newest* language additions — user-defined functions, the `*`/`/` operators, parametric tuples (literals + indexing), and `///` doc-comments — pushed through `check → build → inspect tir` (needs tx3c ≥ 0.22) | compile/lower | +| **04-devnet-roundtrip** | a real devnet round-trip on the default scaffold (`trix test`) — spins a local Dolos devnet, restores cshell wallets, submits the scaffolded transfers, asserts balances; exercises trix + tx3c + dolos + cshell + resolver together | runtime | `02-lang-tour` is compile/lower only: its feature-dense tx references hard-coded UTxOs, mints, -and plutus scripts, so it can't resolve against a fresh devnet (the round-trip lives in 01). +and plutus scripts, so it can't resolve against a fresh devnet (the round-trip lives in +`04-devnet-roundtrip`). ## Channel-aware journeys @@ -112,11 +116,13 @@ stable for CI upload. `.github/workflows/dx-e2e.yml` runs **one job per channel**, each an `{os × journey}` matrix over the native runners (`ubuntu-latest`, `ubuntu-24.04-arm`, `macos-latest`): -- **`stable`** — a comprehensive pass over *every* journey. Edge journeys whose `#@ min-tx3c` - exceeds stable's `tx3c` install and **skip** (green), and start running automatically once the - feature graduates to stable (auto-heal). -- **`beta`** — cherry-picked *edge-feature* journeys (the ones exercising features only on beta, like - `02-lang-tour`'s tuples). Stable already covers everything broadly, so beta stays focused. +- **`stable`** — the offline scaffold gate (`01-basic-init`) plus the lang-surface journeys. Edge + journeys whose `#@ min-tx3c` exceeds stable's `tx3c` install **skip** (green), and start running + automatically once the feature graduates to stable (auto-heal). +- **`beta`** — the *edge-feature* journeys (the ones exercising features only on beta, like + `02-lang-tour`'s tuples), plus `04-devnet-roundtrip`. The devnet round-trip is parked on beta for + now: it's `xfail` on released channels until the trix expect/balance fix ships, and beta gets that + release first. Compat lives in one place — the journey's `#@ min-tx3c` header, enforced by the runner's skip gate — so the workflow needs no per-cell compat config. The shared per-cell steps (install via tx3up, cache diff --git a/e2e/journeys/01-basic-init/journey.sh b/e2e/journeys/01-basic-init/journey.sh index 2dd1bcb..7e4b48f 100755 --- a/e2e/journeys/01-basic-init/journey.sh +++ b/e2e/journeys/01-basic-init/journey.sh @@ -2,19 +2,16 @@ # # Journey 01 — basic init. # -# The canonical "zero to a working transaction" journey on the default scaffold, -# fully offline (no secrets, no live network): scaffold a project, validate it, -# build it, and run -# a real devnet round-trip. The `trix test` step is the integration centerpiece -# — it spins a local Dolos devnet, restores deterministic cshell wallets, submits -# the scaffolded transfer transactions, and asserts the resulting balances — -# exercising trix + tx3c + dolos + cshell + the resolver together. +# The fast, fully offline gate (no secrets, no network beyond the one-time +# install): scaffold the default project, validate it through tx3c, and compile +# it to the Transaction Invocation Interface. The real devnet round-trip lives in +# 04-devnet-roundtrip. # # Run via e2e/run.sh, which provides $TRIX and an isolated working directory. source "${E2E_LIB:?E2E_LIB not set — run this journey via e2e/run.sh}" -journey_begin "01-basic-init" "init → check → build → test (offline devnet round-trip)" +journey_begin "01-basic-init" "init → check → build (offline scaffold validation)" # 1. Scaffold a fresh project and confirm the expected files land. run_cmd "trix init -y — scaffold a new project" "${TRIX}" init -y @@ -32,20 +29,4 @@ assert_output_contains "check passed" run_cmd "trix build — compile to TII" "${TRIX}" build assert_found "TII artifact produced under .tx3/tii" ".tx3/tii" "main.tii" -# 4. Devnet round-trip. The scaffolded transfers must resolve and submit, and -# the final balances must match. The submit half works; the balance-assertion -# half is a *known, tracked toolchain bug*: `trix test`'s expect phase calls -# `cshell wallet utxos "@bob"` with the literal placeholder instead of the -# wallet name `bob` (the transaction path strips the `@`, the expect path in -# trix's commands/expect.rs does not), so cshell errors with the signature -# below. Reproduces on both stable (trix 0.25.1) and beta (0.26.0). Until trix -# strips the `@`, this step is an xfail — it auto-promotes to a hard failure the -# moment the bug is fixed (see xfail_cmd). The submit half is still asserted -# strictly, so a regression there is caught regardless. -xfail_cmd "trix test — devnet round-trip" "CShell failed to get wallet utxos" \ - "${TRIX}" test tests/basic.toml -assert_output_contains "Dolos daemon started" "devnet came up" -assert_output_contains "bob sends 2 ada to alice" "transfer #1 was driven" -assert_output_contains "alice sends 2 ada to bob" "transfer #2 was driven" - journey_end diff --git a/e2e/journeys/04-devnet-roundtrip/journey.sh b/e2e/journeys/04-devnet-roundtrip/journey.sh new file mode 100755 index 0000000..8093106 --- /dev/null +++ b/e2e/journeys/04-devnet-roundtrip/journey.sh @@ -0,0 +1,40 @@ +#!/usr/bin/env bash +# +# Journey 04 — devnet round-trip. +# +# The integration centerpiece, split out of 01-basic-init so the basic gate +# stays fast and offline. Scaffolds the default project and runs a real +# `trix test`: it spins a local Dolos devnet, restores deterministic cshell +# wallets, submits the scaffolded transfers, and asserts the resulting balances +# — exercising trix + tx3c + dolos + cshell + the resolver together. +# +# Scope is runtime (needs a working devnet); no secrets, no live network beyond +# the one-time install. Scheduled on the beta e2e job only for now — see +# .github/workflows/dx-e2e.yml. +# +# Run via e2e/run.sh, which provides $TRIX and an isolated working directory. + +source "${E2E_LIB:?E2E_LIB not set — run this journey via e2e/run.sh}" + +journey_begin "04-devnet-roundtrip" "init → test (real devnet round-trip)" + +# 1. Scaffold a fresh project. `trix test` compiles the TII itself, so no +# separate build step is needed here (01-basic-init covers check/build). +run_cmd "trix init -y — scaffold a new project" "${TRIX}" init -y +assert_exists "tests/basic.toml" "test scenario scaffolded" + +# 2. Devnet round-trip. The scaffolded transfers must resolve and submit, and +# the final balances must match. The submit half works; the balance-assertion +# half is a *known, tracked toolchain bug*: trix test's expect phase called +# `cshell wallet utxos "@bob"` with the literal placeholder instead of the +# wallet name `bob`, so cshell errors with the signature below. Fixed on trix +# main (tx3-lang/trix#123) but not yet in a released channel; until a channel +# ships it this stays an xfail and auto-promotes to a hard failure the moment it +# starts passing (see xfail_cmd). The submit half is asserted strictly regardless. +xfail_cmd "trix test — devnet round-trip" "CShell failed to get wallet utxos" \ + "${TRIX}" test tests/basic.toml +assert_output_contains "Dolos daemon started" "devnet came up" +assert_output_contains "bob sends 2 ada to alice" "transfer #1 was driven" +assert_output_contains "alice sends 2 ada to bob" "transfer #2 was driven" + +journey_end diff --git a/skills/add-e2e-journey/SKILL.md b/skills/add-e2e-journey/SKILL.md index 20dcf0f..308f078 100644 --- a/skills/add-e2e-journey/SKILL.md +++ b/skills/add-e2e-journey/SKILL.md @@ -133,7 +133,10 @@ bash -n e2e/journeys/-/journey.sh # syntax journey to the `stable` job's `journey` list** (the comprehensive pass — below-floor journeys just install and skip via the `#@ min-tx3c` gate). **Also add it to the `beta` job's list only if it exercises a beta-only / edge feature** (`beta` is a focused cherry-pick, not the full suite). -Journeys that need **secrets** (live network) belong in a separate, secrets-gated job. +A journey can also be *parked* on `beta` alone when it depends on a toolchain fix that only beta has +yet (e.g. `04-devnet-roundtrip`, an `xfail` round-trip on released channels until the trix fix ships) +— move it onto `stable` once the fix is released there. Journeys that need **secrets** (live network) +belong in a separate, secrets-gated job. ## Decision Guidelines - **Strict vs xfail**: assert strictly by default. Reach for `xfail_cmd` *only* for a known, From 366c3cc3063d71c38a28281c65e5482213b46335 Mon Sep 17 00:00:00 2001 From: Santiago Date: Tue, 16 Jun 2026 16:47:54 -0300 Subject: [PATCH 2/4] test(e2e): make the devnet round-trip strict, not xfail MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Drop the xfail bracket from 04-devnet-roundtrip — the round-trip is now a strict `run_cmd ... trix test` + `assert_output_contains "Test Passed"`. On released channels (which still carry the bug) the journey now *fails* instead of being tolerated, so the broken state is a real, visible CI failure on the beta job rather than a green xfail. It goes green automatically once the trix fix (tx3-lang/trix#123) ships to a channel. Verified both directions: fails (exit 1) on the released beta binaries; passes strictly against trix main (the fix). Docs + skill updated to say "fails", not "xfail". Co-Authored-By: Claude Opus 4.8 --- .github/workflows/dx-e2e.yml | 8 +++++--- e2e/README.md | 7 ++++--- e2e/journeys/04-devnet-roundtrip/journey.sh | 22 +++++++++++---------- skills/add-e2e-journey/SKILL.md | 4 ++-- 4 files changed, 23 insertions(+), 18 deletions(-) diff --git a/.github/workflows/dx-e2e.yml b/.github/workflows/dx-e2e.yml index fb0cc80..ff4b52b 100644 --- a/.github/workflows/dx-e2e.yml +++ b/.github/workflows/dx-e2e.yml @@ -8,7 +8,9 @@ name: DX E2E # whose `#@ min-tx3c` exceeds stable's tx3c install + skip (green), and # auto-run once the feature graduates to stable. # - beta: edge-feature journeys (e.g. 02-lang-tour's tuples), plus the devnet -# round-trip (04), parked here for now while its trix fix is unreleased. +# round-trip (04). The round-trip currently *fails* on released channels (a +# known, tracked trix bug fixed on main but unreleased) — intentionally red, +# not a tolerated xfail; it goes green once the fix ships to a channel. # # Compat lives in one place: the journey's `#@ min-tx3c` header, enforced by the # runner's skip gate. Native runners only — a DX test must exercise the real @@ -56,8 +58,8 @@ jobs: fail-fast: false matrix: os: [ubuntu-latest, ubuntu-24.04-arm, macos-latest] - # edge-feature journeys + the devnet round-trip, which is parked here for - # now (it's xfail on released channels until the trix fix ships). + # edge-feature journeys + the devnet round-trip. The round-trip fails on + # released channels until the trix fix ships (intentionally red, not xfail). journey: [02-lang-tour, 03-lang-edge, 04-devnet-roundtrip] steps: - uses: actions/checkout@v4 diff --git a/e2e/README.md b/e2e/README.md index 5771497..6467ea1 100644 --- a/e2e/README.md +++ b/e2e/README.md @@ -120,9 +120,10 @@ the native runners (`ubuntu-latest`, `ubuntu-24.04-arm`, `macos-latest`): journeys whose `#@ min-tx3c` exceeds stable's `tx3c` install **skip** (green), and start running automatically once the feature graduates to stable (auto-heal). - **`beta`** — the *edge-feature* journeys (the ones exercising features only on beta, like - `02-lang-tour`'s tuples), plus `04-devnet-roundtrip`. The devnet round-trip is parked on beta for - now: it's `xfail` on released channels until the trix expect/balance fix ships, and beta gets that - release first. + `02-lang-tour`'s tuples), plus `04-devnet-roundtrip`. The devnet round-trip currently **fails** on + released channels — a known, tracked trix bug, fixed on `main` but not yet released. This is + intentional (a real failure, not a tolerated `xfail`); the job goes green once the fix ships to + beta, which gets the release first. Compat lives in one place — the journey's `#@ min-tx3c` header, enforced by the runner's skip gate — so the workflow needs no per-cell compat config. The shared per-cell steps (install via tx3up, cache diff --git a/e2e/journeys/04-devnet-roundtrip/journey.sh b/e2e/journeys/04-devnet-roundtrip/journey.sh index 8093106..a07d910 100755 --- a/e2e/journeys/04-devnet-roundtrip/journey.sh +++ b/e2e/journeys/04-devnet-roundtrip/journey.sh @@ -23,18 +23,20 @@ journey_begin "04-devnet-roundtrip" "init → test (real devnet round-trip)" run_cmd "trix init -y — scaffold a new project" "${TRIX}" init -y assert_exists "tests/basic.toml" "test scenario scaffolded" -# 2. Devnet round-trip. The scaffolded transfers must resolve and submit, and -# the final balances must match. The submit half works; the balance-assertion -# half is a *known, tracked toolchain bug*: trix test's expect phase called -# `cshell wallet utxos "@bob"` with the literal placeholder instead of the -# wallet name `bob`, so cshell errors with the signature below. Fixed on trix -# main (tx3-lang/trix#123) but not yet in a released channel; until a channel -# ships it this stays an xfail and auto-promotes to a hard failure the moment it -# starts passing (see xfail_cmd). The submit half is asserted strictly regardless. -xfail_cmd "trix test — devnet round-trip" "CShell failed to get wallet utxos" \ - "${TRIX}" test tests/basic.toml +# 2. Devnet round-trip: the scaffolded transfers must resolve, submit, and the +# final balances must match — asserted strictly, so the journey fails unless +# `trix test` prints "Test Passed". +# +# NOTE: this currently FAILS on released channels because of a known, tracked +# toolchain bug — trix test's expect phase called `cshell wallet utxos "@bob"` +# with the literal placeholder instead of the wallet name `bob`. Fixed on trix +# main (tx3-lang/trix#123); the journey goes green once that fix ships in a +# channel. Until then the beta e2e job is red here — intentionally, so the broken +# round-trip is a real failure rather than a tolerated xfail. +run_cmd "trix test — devnet round-trip" "${TRIX}" test tests/basic.toml assert_output_contains "Dolos daemon started" "devnet came up" assert_output_contains "bob sends 2 ada to alice" "transfer #1 was driven" assert_output_contains "alice sends 2 ada to bob" "transfer #2 was driven" +assert_output_contains "Test Passed" "balances asserted — round-trip green" journey_end diff --git a/skills/add-e2e-journey/SKILL.md b/skills/add-e2e-journey/SKILL.md index 308f078..797ff1d 100644 --- a/skills/add-e2e-journey/SKILL.md +++ b/skills/add-e2e-journey/SKILL.md @@ -134,8 +134,8 @@ journey to the `stable` job's `journey` list** (the comprehensive pass — below install and skip via the `#@ min-tx3c` gate). **Also add it to the `beta` job's list only if it exercises a beta-only / edge feature** (`beta` is a focused cherry-pick, not the full suite). A journey can also be *parked* on `beta` alone when it depends on a toolchain fix that only beta has -yet (e.g. `04-devnet-roundtrip`, an `xfail` round-trip on released channels until the trix fix ships) -— move it onto `stable` once the fix is released there. Journeys that need **secrets** (live network) +yet (e.g. `04-devnet-roundtrip`, which currently *fails* on released channels until the trix fix +ships — an intentional red, not an `xfail`) — move it onto `stable` once the fix is released there. Journeys that need **secrets** (live network) belong in a separate, secrets-gated job. ## Decision Guidelines From 901acd1a4c7f2ef7d6d3588abfdb7e9d0f3d1b88 Mon Sep 17 00:00:00 2001 From: Santiago Date: Tue, 16 Jun 2026 16:59:40 -0300 Subject: [PATCH 3/4] docs(e2e): make journeys self-documenting; harness-only top README MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Move all journey-specific description out of the top-level e2e/README.md (drop the journey table and the enumerated layout/CI journey lists) and into a README.md inside each journey folder. The top README now describes only the harness, so adding/removing/modifying a journey is self-contained to its folder (+ the workflow's journey list) and never touches it. - e2e/README.md: harness-only — generic layout, no journey table, no named journeys in the channel/CI sections. - journeys/-/README.md: new per-journey docs (what it covers, scope, capability floor, caveats). journey.sh headers slimmed to a one-line pointer; the machine-read `#@ min-tx3c` header stays in journey.sh. - add-e2e-journey skill: scaffold a journey README, and do NOT edit the top README. Co-Authored-By: Claude Opus 4.8 --- e2e/README.md | 81 ++++++++------------- e2e/journeys/01-basic-init/README.md | 9 +++ e2e/journeys/01-basic-init/journey.sh | 8 +- e2e/journeys/02-lang-tour/README.md | 13 ++++ e2e/journeys/02-lang-tour/journey.sh | 18 +---- e2e/journeys/03-lang-edge/README.md | 10 +++ e2e/journeys/03-lang-edge/journey.sh | 12 +-- e2e/journeys/04-devnet-roundtrip/README.md | 18 +++++ e2e/journeys/04-devnet-roundtrip/journey.sh | 25 +------ skills/add-e2e-journey/SKILL.md | 17 +++-- 10 files changed, 97 insertions(+), 114 deletions(-) create mode 100644 e2e/journeys/01-basic-init/README.md create mode 100644 e2e/journeys/02-lang-tour/README.md create mode 100644 e2e/journeys/03-lang-edge/README.md create mode 100644 e2e/journeys/04-devnet-roundtrip/README.md diff --git a/e2e/README.md b/e2e/README.md index 6467ea1..23d3ba2 100644 --- a/e2e/README.md +++ b/e2e/README.md @@ -1,11 +1,10 @@ # DX end-to-end tests These tests validate the **developer experience of the assembled toolchain**: that a -developer who installs a channel and follows the normal journey -(`init → check → build → test`, including a real local devnet round-trip) actually gets a -working result. They exercise the real `trix`, `tx3c`, `dolos`, and `cshell` binaries -together — interop that no single submodule's own tests cover. This is the umbrella's job, -because only it knows the full channel composition (the `manifest-*.json` files) and is where +developer who installs a channel and follows the normal flow (`init → check → build → test`) +actually gets a working result. They exercise the real `trix`, `tx3c`, `dolos`, and `cshell` +binaries together — interop that no single submodule's own tests cover. This is the umbrella's +job, because only it knows the full channel composition (the `manifest-*.json` files) and is where releases are cut. This is deliberately *not* a duplicate of `tooling/trix/tests/e2e/`, which covers `trix init` @@ -16,49 +15,33 @@ helper binaries. ``` e2e/ -├── run.sh # entrypoint: resolve binaries, run journeys, summarize -├── lib/common.sh # logging + fail-fast assertion helpers +├── run.sh # entrypoint: resolve binaries, run journeys, summarize +├── lib/common.sh # logging + fail-fast assertion helpers └── journeys/ - ├── 01-basic-init/journey.sh # init → check → build (offline scaffold validation) - ├── 02-lang-tour/ - │ ├── journey.sh # init → swap in feature-dense main.tx3 → check → build → inspect tir - │ └── main.tx3 # feature-dense fixture (a copy of the lang's lang_tour example) - ├── 03-lang-edge/ # newest lang features (functions, operators, tuples, doc-comments) - └── 04-devnet-roundtrip/journey.sh # init → test (real devnet round-trip: trix + tx3c + dolos + cshell) + └── -/ + ├── journey.sh # the journey script (sources lib/common.sh, drives trix) + ├── README.md # what this journey covers, its scope, and any caveats + └── # optional per-journey fixtures (e.g. a main.tx3) ``` A **journey** is a self-contained script that sources `lib/common.sh` and drives `trix` with the assertion helpers. `run.sh` discovers every `journeys/*/journey.sh`, runs each in an isolated temp working directory, and prints a markdown pass/fail summary, exiting -non-zero if any journey fails. - -The journeys cover complementary axes: - -| Journey | Covers | Scope | -|---------|--------|-------| -| **01-basic-init** | the default scaffold through `init → check → build` — the fast, fully offline gate | compile/lower | -| **02-lang-tour** | the breadth of the language surface — env, records/variants, lists/maps/tuples, policies/assets, spread, locals, and the full Cardano construct set — pushed through `check → build → inspect tir` | compile/lower | -| **03-lang-edge** | the *newest* language additions — user-defined functions, the `*`/`/` operators, parametric tuples (literals + indexing), and `///` doc-comments — pushed through `check → build → inspect tir` (needs tx3c ≥ 0.22) | compile/lower | -| **04-devnet-roundtrip** | a real devnet round-trip on the default scaffold (`trix test`) — spins a local Dolos devnet, restores cshell wallets, submits the scaffolded transfers, asserts balances; exercises trix + tx3c + dolos + cshell + resolver together | runtime | - -`02-lang-tour` is compile/lower only: its feature-dense tx references hard-coded UTxOs, mints, -and plutus scripts, so it can't resolve against a fresh devnet (the round-trip lives in -`04-devnet-roundtrip`). +non-zero if any journey fails. **Each journey documents itself in its own `README.md`** — this +top-level README only describes the harness. ## Channel-aware journeys -A journey's fixture may use language features newer than an older channel's `tx3c` (e.g. -`02-lang-tour` uses tuples, which need tx3c ≥ 0.22 — present on `beta`, not `stable`). A journey -declares its floor with a header comment: +A journey's fixture may use language features newer than an older channel's `tx3c`. A journey +declares the minimum it needs with a header comment in its `journey.sh`: ```sh #@ min-tx3c: 0.22.0 ``` The runner reads the `tx3c` under test and **skips** (does not fail) any journey whose floor isn't -met — `./e2e/run.sh --channel stable` runs `01-basic-init` and skips `02-lang-tour`, exiting 0. -The gate is version-based so it **auto-heals**: when a feature graduates to `stable` (its `tx3c` -bumps past the floor), the journey starts running there with no edit. +met, exiting 0. The gate is version-based so it **auto-heals**: when a feature graduates to an older +channel (its `tx3c` bumps past the floor), the journey starts running there with no edit. ## Which binaries get tested @@ -78,9 +61,9 @@ respects `$HOME` on Unix). CI runners are already ephemeral, so they pass `--no- ## Running locally -Prerequisites: `bash`, `git`, and the toolchain reachable in your chosen mode. The basic -journey needs **no secrets and no network** beyond the one-time install — the devnet round-trip -runs entirely on a local Dolos devnet with deterministic cshell wallets. +Prerequisites: `bash`, `git`, and the toolchain reachable in your chosen mode. No journey needs +secrets or a live network beyond the one-time install — runtime journeys run entirely on a local +Dolos devnet with deterministic cshell wallets. ```sh # Test the toolchain you already have installed: @@ -97,7 +80,7 @@ TX3_CSHELL_PATH=/path/to/cshell \ ./e2e/run.sh --local # Run one journey with live output: -./e2e/run.sh --journey 01-basic-init --verbose +./e2e/run.sh --journey --verbose ``` Install `tx3up` (only needed for `--channel`) with the bootstrap script: @@ -114,16 +97,9 @@ stable for CI upload. ## CI `.github/workflows/dx-e2e.yml` runs **one job per channel**, each an `{os × journey}` matrix over -the native runners (`ubuntu-latest`, `ubuntu-24.04-arm`, `macos-latest`): - -- **`stable`** — the offline scaffold gate (`01-basic-init`) plus the lang-surface journeys. Edge - journeys whose `#@ min-tx3c` exceeds stable's `tx3c` install **skip** (green), and start running - automatically once the feature graduates to stable (auto-heal). -- **`beta`** — the *edge-feature* journeys (the ones exercising features only on beta, like - `02-lang-tour`'s tuples), plus `04-devnet-roundtrip`. The devnet round-trip currently **fails** on - released channels — a known, tracked trix bug, fixed on `main` but not yet released. This is - intentional (a real failure, not a tolerated `xfail`); the job goes green once the fix ships to - beta, which gets the release first. +the native runners (`ubuntu-latest`, `ubuntu-24.04-arm`, `macos-latest`). The `stable` job runs the +broad-coverage journeys; the `beta` job cherry-picks the ones exercising features (or fixes) that +only beta has yet. The per-job journey lists live in the workflow itself. Compat lives in one place — the journey's `#@ min-tx3c` header, enforced by the runner's skip gate — so the workflow needs no per-cell compat config. The shared per-cell steps (install via tx3up, cache @@ -132,15 +108,16 @@ Native runners only: a DX test must validate the real per-platform install, whic would misrepresent (and drop macOS). Triggers: pushes to `main` touching `manifest-*.json` / `e2e/**` / the workflow / the action; a nightly schedule; manual dispatch. -No journey here needs secrets. Future live-network journeys would run in a separate, secrets-gated -job. +Journeys that need secrets (live network) would run in a separate, secrets-gated job. ## Adding a journey See the **`add-e2e-journey` skill** (`skills/add-e2e-journey/SKILL.md`) — the canonical guide for -the journey contract, the `lib/common.sh` helper API, fixtures, and `xfail`. In brief: add a -`journeys/-/journey.sh` that sources `${E2E_LIB}` and drives `"${TRIX}"` with the -assertion helpers, and `run.sh` discovers it automatically. +the journey contract, the `lib/common.sh` helper API, fixtures, and capability gating. In brief: add +a `journeys/-/` directory with a `journey.sh` that sources `${E2E_LIB}` and drives +`"${TRIX}"`, plus a `README.md` describing it, and `run.sh` discovers it automatically. Adding, +removing, or modifying a journey is self-contained to its folder (and the workflow's journey list) — +it should not touch this README. Planned journeys to grow coverage are tracked in [`plans/dx-e2e-journey-roadmap.md`](../plans/dx-e2e-journey-roadmap.md). diff --git a/e2e/journeys/01-basic-init/README.md b/e2e/journeys/01-basic-init/README.md new file mode 100644 index 0000000..3c75f23 --- /dev/null +++ b/e2e/journeys/01-basic-init/README.md @@ -0,0 +1,9 @@ +# 01-basic-init + +The fast, fully offline gate: scaffold the default project (`trix init`), validate it through tx3c +(`trix check`), and compile it to the Transaction Invocation Interface (`trix build`). + +- **Scope:** compile/lower. No devnet, no secrets, no network beyond the one-time install. +- **Channels:** runs everywhere (no `tx3c` floor). + +The real devnet round-trip lives in `04-devnet-roundtrip`. diff --git a/e2e/journeys/01-basic-init/journey.sh b/e2e/journeys/01-basic-init/journey.sh index 7e4b48f..a54e433 100755 --- a/e2e/journeys/01-basic-init/journey.sh +++ b/e2e/journeys/01-basic-init/journey.sh @@ -1,12 +1,6 @@ #!/usr/bin/env bash # -# Journey 01 — basic init. -# -# The fast, fully offline gate (no secrets, no network beyond the one-time -# install): scaffold the default project, validate it through tx3c, and compile -# it to the Transaction Invocation Interface. The real devnet round-trip lives in -# 04-devnet-roundtrip. -# +# Journey 01 — basic init. See README.md for what this covers. # Run via e2e/run.sh, which provides $TRIX and an isolated working directory. source "${E2E_LIB:?E2E_LIB not set — run this journey via e2e/run.sh}" diff --git a/e2e/journeys/02-lang-tour/README.md b/e2e/journeys/02-lang-tour/README.md new file mode 100644 index 0000000..273908a --- /dev/null +++ b/e2e/journeys/02-lang-tour/README.md @@ -0,0 +1,13 @@ +# 02-lang-tour + +Coverage journey: swap the default scaffold's `main.tx3` for a deliberately feature-dense protocol +(`main.tx3` here, a copy of the lang's `lang_tour` example) and push it through the full compile + +lower pipeline (`check → build → inspect tir`). Exercises the breadth of the language surface — env +block, records, variants, lists/maps/tuples, policies & assets, record spread, locals, and the whole +Cardano construct set (mint/burn, collateral, reference, withdrawal, certificates, plutus/native +witnesses, treasury donation, metadata, validity). + +- **Scope:** compile/lower only — the tx references hard-coded UTxOs, mints, and plutus scripts, so it + can't resolve against a fresh devnet (the round-trip lives in `04-devnet-roundtrip`). +- **Fixture:** `main.tx3`. +- **Capability:** tuples need `tx3c >= 0.22` (`#@ min-tx3c: 0.22.0`), so it's skipped on older channels. diff --git a/e2e/journeys/02-lang-tour/journey.sh b/e2e/journeys/02-lang-tour/journey.sh index 855f530..8713b52 100755 --- a/e2e/journeys/02-lang-tour/journey.sh +++ b/e2e/journeys/02-lang-tour/journey.sh @@ -1,24 +1,8 @@ #!/usr/bin/env bash # -# Journey 02 — language tour. -# -# Coverage journey: swap the default scaffold's main.tx3 for a deliberately -# feature-dense protocol (this directory's main.tx3, a copy of the lang's -# lang_tour example) and push it through the full compile + lower pipeline. It -# exercises the breadth of the language surface — env block, records, variants, -# lists/maps/tuples, policies & assets, record spread, locals, and the whole -# Cardano construct set (mint/burn, collateral, reference, withdrawal, the -# certificate forms, plutus/native witnesses, treasury donation, metadata, -# validity) — that the basic-init journey never touches. -# -# Scope is compile/lower only: the tx references hard-coded UTxOs, mints, and -# plutus scripts, so it cannot resolve against a fresh devnet — that's why there -# is no `trix test` step here (the round-trip lives in 01-basic-init). -# +# Journey 02 — language tour. See README.md for what this covers. # Run via e2e/run.sh, which provides $TRIX and an isolated working directory. # -# Capability: tuples (Tuple<…> types, literals, and indexing) require tx3c >= 0.22, -# so this journey is skipped on older channels (e.g. stable's 0.21). #@ min-tx3c: 0.22.0 source "${E2E_LIB:?E2E_LIB not set — run this journey via e2e/run.sh}" diff --git a/e2e/journeys/03-lang-edge/README.md b/e2e/journeys/03-lang-edge/README.md new file mode 100644 index 0000000..362fc2c --- /dev/null +++ b/e2e/journeys/03-lang-edge/README.md @@ -0,0 +1,10 @@ +# 03-lang-edge + +Coverage journey focused on the *newest* language additions, complementing 02-lang-tour's broad +surface: user-defined functions (`fn` with `let`), the `*` and `/` operators, parametric tuples +(`Tuple<…>` types, literals, and indexing), and `///` doc-comments. Swaps in this directory's +`main.tx3` and pushes it through `check → build → inspect tir`. + +- **Scope:** compile/lower only (no devnet round-trip). +- **Fixture:** `main.tx3`. +- **Capability:** needs `tx3c >= 0.22` (`#@ min-tx3c: 0.22.0`); skipped on older channels (e.g. stable's 0.21). diff --git a/e2e/journeys/03-lang-edge/journey.sh b/e2e/journeys/03-lang-edge/journey.sh index 234c773..f594c9f 100755 --- a/e2e/journeys/03-lang-edge/journey.sh +++ b/e2e/journeys/03-lang-edge/journey.sh @@ -1,16 +1,6 @@ #!/usr/bin/env bash # -# Journey 03 — language edge. -# -# Coverage journey focused on the *newest* language-level additions, the -# complement to 02-lang-tour's broad surface: user-defined functions (`fn` with -# `let`), the `*` and `/` operators, parametric tuples (`Tuple<…>` types, -# literals, and indexing), and `///` doc-comments. Swaps in this directory's -# feature-dense main.tx3 and pushes it through compile + lower. -# -# Scope is compile/lower only (no devnet round-trip). These features need -# tx3c >= 0.22, so the journey is skipped on older channels (e.g. stable's 0.21). -# +# Journey 03 — language edge. See README.md for what this covers. # Run via e2e/run.sh, which provides $TRIX and an isolated working directory. # #@ min-tx3c: 0.22.0 diff --git a/e2e/journeys/04-devnet-roundtrip/README.md b/e2e/journeys/04-devnet-roundtrip/README.md new file mode 100644 index 0000000..f430b44 --- /dev/null +++ b/e2e/journeys/04-devnet-roundtrip/README.md @@ -0,0 +1,18 @@ +# 04-devnet-roundtrip + +The integration centerpiece: scaffold the default project and run a real `trix test`. It spins a +local Dolos devnet, restores deterministic cshell wallets, submits the scaffolded transfers, and +asserts the resulting balances — exercising trix + tx3c + dolos + cshell + the resolver together. + +- **Scope:** runtime (needs a working devnet). No secrets, no live network beyond the one-time install. +- **Channels:** runs everywhere (no `tx3c` floor), but the CI workflow currently schedules it on the + **beta** job only. + +## Currently failing on released channels — intentionally + +The balance-assertion phase hits a known, tracked trix bug (the expect path queried the wrong cshell +store, passed the `@bob` placeholder, and parsed a mismatched utxo shape). Fixed on trix `main` +(tx3-lang/trix#123) but not yet in a released channel, so this journey **fails** on released binaries. +The assertion is kept **strict** (not a tolerated `xfail`) so the broken round-trip is a real, +visible failure. It goes green automatically once the fix ships to a channel; at that point add this +journey to the `stable` job too. diff --git a/e2e/journeys/04-devnet-roundtrip/journey.sh b/e2e/journeys/04-devnet-roundtrip/journey.sh index a07d910..d8f4728 100755 --- a/e2e/journeys/04-devnet-roundtrip/journey.sh +++ b/e2e/journeys/04-devnet-roundtrip/journey.sh @@ -1,17 +1,7 @@ #!/usr/bin/env bash # -# Journey 04 — devnet round-trip. -# -# The integration centerpiece, split out of 01-basic-init so the basic gate -# stays fast and offline. Scaffolds the default project and runs a real -# `trix test`: it spins a local Dolos devnet, restores deterministic cshell -# wallets, submits the scaffolded transfers, and asserts the resulting balances -# — exercising trix + tx3c + dolos + cshell + the resolver together. -# -# Scope is runtime (needs a working devnet); no secrets, no live network beyond -# the one-time install. Scheduled on the beta e2e job only for now — see -# .github/workflows/dx-e2e.yml. -# +# Journey 04 — devnet round-trip. See README.md for what this covers (and why +# it currently fails on released channels). # Run via e2e/run.sh, which provides $TRIX and an isolated working directory. source "${E2E_LIB:?E2E_LIB not set — run this journey via e2e/run.sh}" @@ -24,15 +14,8 @@ run_cmd "trix init -y — scaffold a new project" "${TRIX}" init -y assert_exists "tests/basic.toml" "test scenario scaffolded" # 2. Devnet round-trip: the scaffolded transfers must resolve, submit, and the -# final balances must match — asserted strictly, so the journey fails unless -# `trix test` prints "Test Passed". -# -# NOTE: this currently FAILS on released channels because of a known, tracked -# toolchain bug — trix test's expect phase called `cshell wallet utxos "@bob"` -# with the literal placeholder instead of the wallet name `bob`. Fixed on trix -# main (tx3-lang/trix#123); the journey goes green once that fix ships in a -# channel. Until then the beta e2e job is red here — intentionally, so the broken -# round-trip is a real failure rather than a tolerated xfail. +# final balances must match — asserted strictly (must print "Test Passed"). +# This currently fails on released channels (known trix bug; see README.md). run_cmd "trix test — devnet round-trip" "${TRIX}" test tests/basic.toml assert_output_contains "Dolos daemon started" "devnet came up" assert_output_contains "bob sends 2 ada to alice" "transfer #1 was driven" diff --git a/skills/add-e2e-journey/SKILL.md b/skills/add-e2e-journey/SKILL.md index 797ff1d..00ad43f 100644 --- a/skills/add-e2e-journey/SKILL.md +++ b/skills/add-e2e-journey/SKILL.md @@ -75,18 +75,23 @@ round-trip or compile/lower only? This determines the steps and the CI placement ```bash mkdir -p e2e/journeys/- $EDITOR e2e/journeys/-/journey.sh +$EDITOR e2e/journeys/-/README.md # what it covers, scope, caveats chmod +x e2e/journeys/-/journey.sh ``` +Give the journey a `README.md` — that's where *all* journey-specific description lives (what it +covers, its scope, capability floor, and any caveats like a known failure). The top-level +`e2e/README.md` describes only the harness and must not be edited when you add a journey. Keep the +`journey.sh` header to a one-liner that points at the README. + Skeleton (copy, then fill in): ```bash #!/usr/bin/env bash # -# Journey — . -# <1–3 lines: what it covers and its scope (runtime vs compile/lower).> -# +# Journey <NN> — <title>. See README.md for what this covers. # Run via e2e/run.sh, which provides $TRIX and an isolated working directory. # -# Optional — only if the fixture needs a tx3c newer than some channel ships: +# Optional — only if the fixture needs a tx3c newer than some channel ships +# (this header is machine-read by run.sh, so it must live here, not in README): #@ min-tx3c: 0.22.0 source "${E2E_LIB:?E2E_LIB not set — run this journey via e2e/run.sh}" @@ -156,7 +161,7 @@ belong in a separate, secrets-gated job. - The new journey is green **in isolation** (`--journey`) and in the **full suite**. - **Hermetic**: after the run, no stray `dolos` daemon survives (`pgrep -fl 'dolos.*daemon'`) and, for channel mode, `~/.tx3/default` is unchanged (channel mode must never run `tx3up use`). -- Update `e2e/README.md`'s journey table/layout to list the new journey (the table is reference; - the how-to stays here). +- The journey folder has a `README.md` describing it. **Do not edit the top-level `e2e/README.md`** — + it describes only the harness; journey specifics live in the journey folder. - If the journey brackets a new xfail, record the bug in `plans/` and a memory note so its promotion is tracked. From d4cb89df0e7749c5958702ff32639e91d20d7e18 Mon Sep 17 00:00:00 2001 From: Santiago <santiago@carmuega.me> Date: Tue, 16 Jun 2026 17:02:14 -0300 Subject: [PATCH 4/4] docs(e2e): de-stale the journey roadmap MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The roadmap predated 03-lang-edge / 04-devnet-roundtrip, so its planned `03-codegen-consume` / `04-registry` collided with real journeys, it linked the now-deleted findings plan, and it placed the round-trip in 01 (now 04). - Drop fixed `NN-` prefixes from planned journeys — they're themes, numbered at authoring time (next free: 05) — so the roadmap stops colliding with real journeys. - Fix references: round-trip machinery lives in 04-devnet-roundtrip; the trix test fix is merged (tx3-lang/trix#123) but unreleased; each journey ships its own README (no journey table to update); drop the dead findings-plan link. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> --- plans/dx-e2e-journey-roadmap.md | 86 ++++++++++++++++----------------- 1 file changed, 43 insertions(+), 43 deletions(-) diff --git a/plans/dx-e2e-journey-roadmap.md b/plans/dx-e2e-journey-roadmap.md index e3afd80..adbd2a6 100644 --- a/plans/dx-e2e-journey-roadmap.md +++ b/plans/dx-e2e-journey-roadmap.md @@ -1,36 +1,35 @@ # Plan: DX e2e harness — journey roadmap -Status: **open / not started** — the harness ships with `01-basic-init` and -`02-lang-tour`; these are the candidate journeys to grow coverage. +Status: **open / not started** — candidate journeys to grow coverage beyond what +ships today (`01-basic-init` offline gate, `02-lang-tour` + `03-lang-edge` +language coverage, `04-devnet-roundtrip` runtime round-trip). Scope: the `e2e/` harness (new `journeys/<NN>-<name>/`), plus the surfaces each journey exercises — `trix codegen` + an SDK (`sdks/`), the registry (`services/registry`), live TRP endpoints, and the `protocols/` fixtures. -Origin: extracted from `e2e/README.md` so the runnable harness stays a lean -reference and the roadmap lives with the other plans. -Related: [`dx-e2e-findings-followups.md`](./dx-e2e-findings-followups.md) (the -fixes for what the first journeys surfaced), [`e2e/README.md`](../e2e/README.md), -and the `add-e2e-journey` skill (`skills/add-e2e-journey/SKILL.md`) — the -canonical guide for actually authoring a journey. +Related: [`e2e/README.md`](../e2e/README.md) and the `add-e2e-journey` skill +(`skills/add-e2e-journey/SKILL.md`) — the canonical guide for actually authoring a +journey. ## Context -Each journey is a self-contained script that drives the real `trix` binary -through one developer scenario and asserts the outcome; `e2e/run.sh` discovers -`journeys/*/journey.sh` automatically. Today's two cover the *runtime* round-trip -on the default scaffold (`01`) and the *compile/lower* breadth of the language -surface (`02`). The journeys below extend coverage outward along the developer -journey — codegen, registry, live networks, real protocols. They are ordered by -how self-contained they are: `03` needs only a Node toolchain; `06` needs the -`trix test` fix first; `04`/`05` need external infra or secrets and belong in a -separate CI job from the fast, offline `01` gate. - -Author each one with the `add-e2e-journey` skill — it owns the journey contract, -the `lib/common.sh` helper API, fixtures, and `xfail` conventions. This plan only +Each journey is a self-contained folder (`journey.sh` + a `README.md` + optional +fixtures) that drives the real `trix` binary through one developer scenario and +asserts the outcome; `e2e/run.sh` discovers `journeys/*/journey.sh` +automatically. Today's journeys cover the offline scaffold gate (`01`), the +*compile/lower* breadth and edge of the language surface (`02`, `03`), and the +*runtime* devnet round-trip on the default scaffold (`04`). The journeys below +extend coverage outward along the developer path — codegen, registry, live +networks, real protocols. + +The names below are themes, **not** fixed IDs — assign the `<NN>-` prefix when you +author each one (next free number is `05`). Author with the `add-e2e-journey` +skill: it owns the journey contract, the `lib/common.sh` helper API, fixtures, +capability gating, and the per-journey `README.md` convention. This plan only defines *what* each journey should exercise. ## Workstreams -### 3. `03-codegen-consume` — generated client compiles (and invokes) +### codegen-consume — generated client compiles (and invokes) Exercise the `trix codegen` → generated SDK path that nothing in the harness touches yet. Scaffold, `trix codegen --plugin ts-client`, then compile the @@ -42,12 +41,12 @@ project's TII. output dir is populated and `tsc`/build succeeds. This is the cheap, high-value core. - **Phase B (round-trip):** import the generated client in a tiny host script and invoke a tx against the local devnet (or `--skip-submit` to validate unsigned-CBOR - build). Pairs with the `01` devnet machinery. + build). Reuses `04-devnet-roundtrip`'s devnet machinery. - **Deps/CI:** adds a Node toolchain (`actions/setup-node`) — still no secrets, so it - can ride the default matrix once Node is provisioned. Consider a second job to keep - the no-Node `01`/`02` gate minimal. + can ride the matrix once Node is provisioned. Consider a separate job to keep the + no-Node journeys minimal. -### 4. `04-registry` — publish → use → invoke an interface +### registry — publish → use → invoke an interface Exercise the protocol-reuse path: `trix publish` a protocol to a registry, then in a separate consumer project `trix use <scope>/<name>:<ver>` and invoke the interface tx. @@ -59,7 +58,7 @@ separate consumer project `trix use <scope>/<name>:<ver>` and invoke the interfa - **Scope:** registry-dependent; gate it in a job with whatever registry/auth it needs. A reduced first cut can publish to a local registry and `use` it without live OIDC. -### 5. `05-live-network` — preview/preprod invoke (secrets-gated) +### live-network — preview/preprod invoke (secrets-gated) Invoke a real transfer against a live Cardano testnet (preview/preprod) via a Demeter TRP endpoint — the only journey that leaves the local devnet. @@ -71,37 +70,38 @@ TRP endpoint — the only journey that leaves the local devnet. `--profile preview`/`preprod` with funded identities; assert on the submitted tx / resolver response rather than balances (testnet timing). -### 6. `06-protocol-fixture` — a real protocol through `trix test` +### protocol-fixture — a real protocol through `trix test` Run a real protocol from `protocols/<name>/` (each ships `trix.toml` + `main.tx3` + `tests/basic.toml`) through the harness, validating actual third-party protocols against -the channel — not just the scaffold and the lang-tour fixture. +the channel — not just the scaffold and the lang fixtures. -- **Blocked on** the `trix test` expect `@`-prefix fix (workstream 1 of - `dx-e2e-findings-followups.md`) for the round-trip half to pass; until then it can run - `check` + `build` on a protocol fixture (still useful coverage), or bracket the round-trip - as an `xfail` like `01` does. +- **Round-trip dependency:** the `trix test` expect/balance fix is merged + (tx3-lang/trix#123) but not yet in a released channel, so the round-trip half fails on + released binaries — exactly like `04-devnet-roundtrip`. Until a channel ships it, run + `check` + `build` on a protocol fixture (still useful coverage), or keep the round-trip + strict and accept the red (as `04` does). - **Scope:** offline (uses the local devnet); pick a representative protocol (or parametrize over several) and copy it into the journey workdir so the run is hermetic. ## Sequencing -1. `03-codegen-consume` Phase A — most self-contained (Node only), highest coverage/effort +1. `codegen-consume` Phase A — most self-contained (Node only), highest coverage/effort ratio; do first. -2. `06-protocol-fixture` (check/build slice) — cheap once a fixture is chosen; promote its - round-trip when the `trix test` fix lands. -3. `03` Phase B (round-trip) — after Phase A, reuses `01`'s devnet path. -4. `05-live-network` — independent; needs the secrets job wired up (reuse the SDK e2e +2. `protocol-fixture` (check/build slice) — cheap once a fixture is chosen; add the + round-trip when the `trix test` fix releases. +3. `codegen-consume` Phase B (round-trip) — after Phase A, reuses `04`'s devnet path. +4. `live-network` — independent; needs the secrets job wired up (reuse the SDK e2e secrets). Lower urgency, higher value for release confidence. -5. `04-registry` — last; the heaviest infra/auth lift. +5. `registry` — last; the heaviest infra/auth lift. ## Verification - Each journey is green in isolation (`./e2e/run.sh --journey <name> --verbose`) and in the full suite, and passes the `add-e2e-journey` skill's Safety Checks (syntax, hermeticity — no stray `dolos`, no `~/.tx3/default` repoint). -- `03`: generated client dir populated and compiles; (Phase B) tx invokes against devnet. -- `04`: `trix use` resolves the published interface and the interface tx invokes. -- `05`: a real testnet submission succeeds via the Demeter endpoint (secrets present). -- `06`: a `protocols/<name>` fixture passes `check`/`build` (and the round-trip once unblocked). -- `e2e/README.md`'s journey table is updated as each lands; this plan's workstream is checked off. +- `codegen-consume`: generated client dir populated and compiles; (Phase B) tx invokes against devnet. +- `registry`: `trix use` resolves the published interface and the interface tx invokes. +- `live-network`: a real testnet submission succeeds via the Demeter endpoint (secrets present). +- `protocol-fixture`: a `protocols/<name>` fixture passes `check`/`build` (and the round-trip once released). +- Each new journey ships its own `README.md`; this plan's workstream is checked off as it lands.