README.md
Acceptance runbooks
Runnable end-to-end checks against prod. Each doc: purpose, preconditions, steps, expected observations, pass criteria, cleanup, pitfalls. They change prod state (VMs, contracts, tokens): run only with the lead's go, announce on atirc first, release everything you rent.
| id | name | what it proves | hosts | how long | last pass |
|---|---|---|---|---|---|
| 0001 | k8s: account modes, pause, one VM per host | localRepo + oauthQr bidders, per-component suspend, tenant k3s 0 -> 3 -> 0 nodes, one VM per host, typed settings, ACC34 | gateway, local, hat-9, hat-7 | ~45 min | rc159, 2026-11-01 (hat-7, local, hat-9 nodes) |
| 0002 | ssh gateway, per-user OAuth | ssh <handle>@socialweb.computer atirc agent run <name> rents as the user, agent joins, revoke before release on disconnect / cap, restart survival | gateway (ssh gw), any bidder | ~3 min + session | rc158, 2026-11-01 (revoke before terminate) |
| 0003 | CLI ssh over WebRTC (ACC34) | CLI requester rents per host, ssh over WebRTC fresh + restarted kcp, no plaintext signaling | local, hat-9, hat-7 | ~3 min / host | rc158, 2026-11-01 (all hosts) |
| 0004 | atirc agent in a VM (plan 0035) | leased mint at RFP, guest.agentStart starts the unit, nick joins, revoke before vm.terminated | any bidder, atirc | ~3 min | rc158 CLI, 2026-11-01 (alice) |
| 0005 | guest requester R2, association (plan 0036) | contract-scoped association lets R2 rent a nested VM, grandchild agent, outer release cascades, all tokens revoked, record deleted | 2 bidders, atirc | ~10 min | rc159, 2026-11-01 (tree revoked in order) |
| 0006 | rc rollout checks + compat smoke | every component on rcN, Ready / SignedIn / 0 ERROR / host empty, unchanged page + CLI still work | all | ~5-15 min | rc158, 2026-11-01 |
| 0007 | bidder-side VM termination (ops) | operator delete ends an orphan cleanly: released, vm.terminated pinned, leased tokens dead, host empty | one bidder | ~1 min | rc158, 2026-11-01 |
| 0008 | host observer verification | per-host watcher protocol: CONFIRMED after rollout, VM timeline, vm.terminated pin, orphan check | each bidder | continuous | rc158, 2026-11-01 (hat-7, hat-9 watchers) |
| 0009 | wasm browser page | A1-A7: suite, boot + sign-in, VM lifecycle, Held-reload restore, upgrade load, compat smoke, /chat | browser, bidders | ~5 min / test | page-rc143 vs rc158, 2026-11-01; deno from the page on rc159 |
| 0010 | iOS app, embedded kcp | A1-A6: market sign-in + persistence, launch / agentStart / join, revoke before terminated, cross-restart release, presence, perf | simulator / device, bidders | ~5 min / test | simulator, 2026-10-31 (not re-run on rc158/rc159) |
| 0011 | atirc | repo + deploy gates, token lifecycle gates for every path, pipes, /chat, lease death | irc.fedfork.com | ~10 min | 2026-11-01 (atirc v0.1.0-5a8dfa2) |
| 0012 | Infra quickstart | kubectl apply of every examples/infra file: VM ssh, tenant k8s node + pod, Deno sandbox stdout, agent VM refused before its RFP locally (.local handle; join on prod, 0013), release | own market network (+ prod for the agent join) | ~15 min | main ec97f78e local, 2026-11-01 |
| 0013 | Mixed prod on a user-configured bidder | run requester / install requester with a real account, mixed-prod.yaml pinned to one bidder under the default policies and both vouches: VM ssh, Deno stdout, agent join, restart keeps Held, delete revokes before vm.terminated; the gateway part waits on plan 0039 C | a user-configured bidder, irc.fedfork.com | ~20 min | rc159 (A, C) and rc160 CLI (B), 2026-11-01 |
0011 is a copy; the source is the atirc repo (git@tangled.org:did:plc:vtad4w7ujsvz7t6o6iuvmhjq,
docs/acceptance/0001-atirc.md @ ec0d088).
Shared rules
- Announce before, post done after:
<nick> -> all: <test> now; hold VM tests/... done; tests may resume - One driver per account at a time (alice, hat, bob); owner-held VMs are never touched
- Policies:
bidder-tangled-vouchon every prod bidder,requester-tangled-vouchon requesters; neveropenunless the owner sets it - Evidence comes from three sides: requester log, host watcher (0008), atirc-dev (
revocations.ndjson) - Token order: revoke strictly before
vm.terminated; the lease kills it anyway once termination exists - No secrets anywhere: no tokens, passwords, cookies, sign-in URLs, creds file contents; creds files stay mode 0600 and are read only inside the one signing command
- A workaround is reported as one; the run is re-done without it before the item counts as passed
Which runbook for which change
| Change | Run |
|---|---|
| any rc to prod | 0006, 0008 (watchers), then the runbooks of the changed area |
| bidder market / policy code | 0003 on all hosts, 0006 compat, 0001 before a milestone |
| ssh gateway / per-user requester | 0002 (side port first, then 22) |
| requester mint / revoke / lease | 0004, 0011 section 3, 0009 A3 |
| association / guest requester | 0005 |
| page build | 0009 A1-A6 on dev, then A3 + A6 on prod |
| Infra / EphemeralInfra, examples, quickstart-local / quickstart-prod | 0012 |
| run requester / install requester, agent identity, bidder compute kinds or operator sign-in | 0013 |
| iOS app / pkg/embedded | 0010 |
| OAuth role scope | re-sign every OAuth identity first (0001 section 9 note, 0006), then 0003 hat-7 |