feat(testnet): events-capture framework + EXPECTED_EVENTS for testnet-main + lifecycle-testnet-verify

[AquiGorka]

Summary

Adds a small framework that asserts the WebSocket event surfaces of provider-platform (/api/v1/providers/:pp/events/ws) and network-dashboard-platform (/api/v1/network/ws) against a strict-order, strict-value declaration inlined at the top of each testnet flow script.

Two scripts produce events in the canonical testnet/run-all.sh runner — testnet/main.ts (suite 1, payment flow) and lifecycle/testnet-verify.ts (suite 3, UC2 governance). Each script now declares an EXPECTED_EVENTS const at the top. The harness subscribes to both WS surfaces before the script's chain interactions, runs the script's exported main() in-process, tails for EVENTS_CAPTURE_TAIL_MS (default 5000), then diffs captured against expected and writes a structured run report.

Suite 2 and suite 4 (OTEL trace verifiers) stay as-is — they do no chain ops, so there's nothing to capture.

Cross-PR dependency — read this first

This PR depends on Moonlight-Protocol/network-dashboard-platform#5. That PR refactors network-dashboard-platform from hourly periodic resync to event-driven topology + back-fill on adoption, which is what makes council_formed (the first network event in both scripts' EXPECTED_EVENTS) fire deterministically. The local-stack smoke in this PR was validated against that refactor; without it, the network-side assertion would still fail on the first event.

Merge order: n-d-p#5 first, then this.

What's in this PR

• testnet/events-capture/types.ts — shared types + the ALWAYS_SKIP_FIELDS set (deep-stripped from both expected and captured before equality check). Covers ts, id, occurredAt, ledger, bundleId/bundleIds, txHash/txId, contract-id family, councilName (timestamp-embedded literal in both scripts), reason (free-form error.message at the producer site).
• testnet/events-capture/subscribe.ts — per-PP + network-wide WS clients. Per-PP polls GET /api/v1/dashboard/pp/list until the operator's PP appears in the DB, then upgrades with Sec-WebSocket-Protocol: bearer.<jwt>. Network is public, snapshot frame is dropped (PM-acked: state-at-connect-time depends on prior runs), every subsequent LiveFrame is captured. Uses Deno's built-in WebSocket — no new dep.
• testnet/events-capture/assert.ts — strict-order, strict-value diff with the always-skip set deep-stripped. Returns a structured per-index per-subscriber result; one subscriber failing doesn't mark another as failing.
• testnet/events-capture/report.ts — stdout summary (PASS line per subscriber, or full mismatch diff with expected/captured per index) + JSON dump under runs/<run-id>/report.json. runs/ is gitignored.
• testnet/events-capture/harness.ts — CLI orchestrator. Derives the operator/alice/bob keypairs from MASTER_SECRET (matching the scripts' own deriveKeypair(ROLES.PP / ROLES.ALICE / ROLES.BOB, 0)), acquires the dashboard JWT, opens both subscribers, dynamic-imports the script module, runs main(), tails, closes, asserts, writes report, exits 0/1/2.
• testnet/main.ts and lifecycle/testnet-verify.ts — inlined EXPECTED_EVENTS. Each script's main() is now exported and the bottom-of-file invocation is guarded with if (import.meta.main) so direct deno run still works.
• testnet/run-all.sh and testnet/run-local.sh — suites 1 + 3 now invoke the harness instead of run-tempo.sh / direct deno run. run-local.sh exports defaults for NETWORK_DASHBOARD_PLATFORM_URL and MASTER_SECRET when not set by the caller.

EXPECTED_EVENTS values were derived from Phase 0 audit + Phase 3 smoke

• Per-PP: 12 events per script. weight values come from the bundle-operation counts in lib/client/{deposit,send,withdraw}.ts × the mempool defaults (MEMPOOL_EXPENSIVE_OP_WEIGHT=10 × MEMPOOL_CHEAP_OP_WEIGHT=1). amount strings come from the deposit / send / withdraw amount + fee math; entityName / jurisdictions / depositorAddress / recipientAddress from the script's literals + the MASTER_SECRET-derived keypairs.
• Network: 5 events per script. The processRawEventBatch dedup in network-dashboard-platform drops channel_bundle whenever the tx also produced channel_deposit or channel_settlement, so the visible sequence is council_formed → provider_added → channel_deposit → channel_bundle (send) → channel_settlement. Validated empirically in the Phase 3 smoke (after the n-d-p refactor lands).

Test plan

• deno fmt --check over the changed files (testnet/events-capture/, testnet/main.ts, lifecycle/testnet-verify.ts, testnet/run-all.sh, testnet/run-local.sh) — clean.
• deno lint over the same set — clean. (Repo-wide deno lint surfaces ~23 pre-existing problems in unrelated files such as setup-pp.ts:35 and playwright/tests/full-flow.spec.ts:44. Same out-of-PR-scope situation as the prior PR's pre-existing test debt.)
• Local-stack smoke against the harness invocation for both scripts:

  testnet-main             — perPp: 12/12  network: 5/5  PASS
  lifecycle-testnet-verify — perPp: 12/12  network: 5/5  PASS
  

  Run artifacts: testnet/events-capture/runs/testnet-main-2026-06-05T16-31-48-970Z/report.json and testnet/events-capture/runs/lifecycle-testnet-verify-2026-06-05T16-33-57-529Z/report.json. No testnet RPC / contract / signer was touched — outbound calls only to localhost:8000 (Stellar quickstart), localhost:4015 (council), localhost:4010 (provider), localhost:4035 (network-dashboard).
• Reviewer pass on the EXPECTED_EVENTS field selections (which keys are strict-asserted vs deep-stripped — see ALWAYS_SKIP_FIELDS in types.ts).
• Reviewer pass on the harness's per-PP open loop (GET /api/v1/dashboard/pp/list because no single-PP GET endpoint exists today).