test: E2E documentation + supporting tests (#15, draft)

[paolino]

Refs #15. Draft.

Summary

End-to-end tests for harvest's spend protocol, delivered first as executable documentation (per the user's directive: "what counts for me is E2E as documentation") and second as a regression gate. The full narrative of how a voucher spend works end-to-end lives at the top of offchain/test/DevnetSpendSpec.hs — reading that module top-to-bottom is the recommended path for a new contributor.

Shape of this PR

Landed and green

• Spec-driven artefacts under specs/002-e2e-tests/: spec, plan, research, data model, contract (canonical 106-byte signed_data layout), quickstart, tasks. The whole feature was driven through /speckit.
• DevnetSpendSpec.hs module header = the E2E narrative. Six numbered phases from "coalition runs a devnet" to "node accepts or rejects". Every scenario has an inline paragraph explaining the threat model it defends against in plain English.
• Byte-layout cross-check (SignedDataLayoutSpec.hs, 8 cases): parses the fixture's 106-byte signed_data and asserts each of the five bound fields (txid, ix, acceptor_ax, acceptor_ay, d) matches what the Node-side signer claims to have set. If the JS signer and the Aiken validator ever disagree on the byte layout, this test fails deterministically, in milliseconds.
• Ed25519 independent verifier (Ed25519Spec.hs, 4 cases, FR-003): verifies the fixture's (customer_pubkey, signed_data, customer_signature) using the verifyDSIGN primitive re-exported by cardano-node-clients PR #65. Positive + flipped-byte negative both pass, proving the Node-produced bytes are byte-compatible with what the Plutus builtin will consume.
• Pre-existing Groth16Spec / E2ESpec path fixes: those tests were silently skipped in CI (the old check wrapper compiled the binary but never ran it). Now that the wrapper executes via nix run, their hardcoded relative paths needed to use Fixtures.fixturesDir instead.
• CI (.github/workflows/ci.yml): splits into derivation-backed checks (via nix build — library, groth16-ffi, circuit, circuit-tests, aiken-check — their tests run during the build phase) and shell-app checks (via nix run — unit-tests, lint — which must be executed). Ensures regressions in the test suite actually fail CI.
• Fixture discovery: HARVEST_FIXTURES_DIR env var wired through nix/checks.nix so the test binary finds fixtures in the nix-store sandbox.

Test status

31 examples, 0 failures, 5 pending

The five pending scenarios are the devnet execution of the golden path (T021) and the four negatives (T030–T033). They are clearly named and each carries its threat-model explanation inline.

Deferred to a follow-up

The devnet bracket from cardano-node-clients:devnet is consumable but needs a fixture-signing affordance before the golden path can actually submit: the fixture's signed_data is bound to a zero txid (placeholder), and a real devnet tx consumes a real TxOutRef, so the test has to re-sign signed_data at runtime with sk_c and a live txid. That needs signDSIGN re-exported from Cardano.Node.Client.E2E.Setup — a one-line upstream patch analogous to the verifyDSIGN one that already landed in cardano-node-clients PR #65.

Rather than bundling a second upstream patch into an already-substantial PR, this is left as the natural next follow-up. The narrative and supporting tests deliver the documentation value now; the devnet execution is additive.

Changes guided tour

offchain/test/DevnetSpendSpec.hs

The docstring is ~70 lines and walks the reader through every phase of a spend. Each it block title names a defended invariant in the protocol's vocabulary (e.g. "defends against customer-key substitution") rather than an implementation assertion.

offchain/test/SignedDataLayout.hs

Single Haskell authority for the 106-byte layout. Offsets as named constants, decoder that errors clearly on wrong-size inputs. Mirrors specs/002-e2e-tests/contracts/signed-data-layout.md.

offchain/test/Fixtures.hs

Loads proof, VK, public signals, customer bundle, and applied-script hex into a single SpendBundle record. No parallel fixture copies; reads directly from the authoritative JSON/hex files.

nix/checks.nix, flake.nix

unit-tests is now a writeShellApplication that prepends cardano-node to PATH, sets HARVEST_FIXTURES_DIR, exports LD_LIBRARY_PATH for the groth16-ffi library, and execs the test binary. cardano-node input is pinned to the same version (10.7.0) that cardano-node-clients itself tests against — no drift.

.github/workflows/ci.yml

nix build for derivation-backed checks + nix run for shell-app checks. The lint job is folded into the main build-gate since it's cheap and there's no parallelism benefit to keeping it separate.

Local CI

All checks green locally:

• nix build .#checks.x86_64-linux.library
• nix build .#checks.x86_64-linux.groth16-ffi
• nix build .#checks.x86_64-linux.circuit
• nix build .#checks.x86_64-linux.circuit-tests
• nix build .#checks.x86_64-linux.aiken-check
• nix run .#checks.x86_64-linux.unit-tests → 31 examples, 0 failures, 5 pending
• nix run .#checks.x86_64-linux.lint → no hints

Test plan

• CI green on GitHub (validates the nix run workflow end-to-end).
• Read DevnetSpendSpec.hs top-to-bottom — does it actually teach a reader how a harvest spend works? Feedback on phrasing or missing steps is welcome.
• Read specs/002-e2e-tests/spec.md and contracts/signed-data-layout.md and confirm they match the implementation.
• Decide whether the 5 pending devnet scenarios land as a follow-up PR (recommended — they need another upstream signDSIGN re-export) or whether this slice merges and the follow-up issues unblock separately.