From 251bcf36c3c178b0fc04f7f1b2b6143cdef2a8cc Mon Sep 17 00:00:00 2001 From: Eric Wendland Date: Sun, 5 Jul 2026 23:52:58 +0200 Subject: [PATCH] docs: add dogfood evidence checklist --- docs/dogfood-checklist.md | 188 +++++++++++++++++++++++++++ docs/production-readiness-roadmap.md | 14 +- 2 files changed, 198 insertions(+), 4 deletions(-) create mode 100644 docs/dogfood-checklist.md diff --git a/docs/dogfood-checklist.md b/docs/dogfood-checklist.md new file mode 100644 index 0000000..13223c4 --- /dev/null +++ b/docs/dogfood-checklist.md @@ -0,0 +1,188 @@ +# Two-Machine Dogfood Checklist + +This checklist is the pre-deployment evidence gate for using `geth` as a base +layer for scripts, infrastructure automation, and other projects. Complete it +on two real machines before the first broader deployment. Do not mark the Phase +10 roadmap item complete until every checkbox here has a date, platform, geth +version or commit, and evidence note. + +## Test Matrix + +- `[ ]` Machine A platform, architecture, geth version/commit, and install + method recorded. +- `[ ]` Machine B platform, architecture, geth version/commit, and install + method recorded. +- `[ ]` Both machines use fresh `GETH_HOME` directories. +- `[ ]` Any skipped item has an explicit reason and follow-up issue. + +## Fresh Install And Owner Init + +On Machine A: + +```sh +geth init --admin-key ~/.ssh/id_ed25519.pub --signing-key ~/.ssh/id_ed25519 --node-name owner +geth daemon service install --start +geth wait daemon --timeout-ms 30000 +geth status --json +geth doctor --json +geth peer export --out /tmp/owner.peer.json +``` + +Acceptance: + +- `[ ]` User-level service starts without privileged service-manager mutation. +- `[ ]` `geth wait daemon` succeeds. +- `[ ]` `geth status --json` reports a node ID, agent ID, store status `ok`, + and Iroh endpoint status. +- `[ ]` `geth doctor --json` is actionable and has no unexplained failures. +- `[ ]` The exported peer card contains the current owner node ID and endpoint. + +## Enrollment And Peer Exchange + +Move `/tmp/owner.peer.json` to Machine B. + +On Machine B: + +```sh +geth init +geth peer import /tmp/owner.peer.json +geth node enroll request --node-name worker --out /tmp/worker-enrollment.json +geth node enroll submit owner --path /tmp/worker-enrollment.json +``` + +On Machine A: + +```sh +geth node enroll list --status pending +geth node enroll approve --signing-key ~/.ssh/id_ed25519 +geth peer export --out /tmp/owner-approved.peer.json +``` + +On Machine B: + +```sh +geth node enroll sync owner +geth keychain status --json +geth wait peer owner --timeout-ms 30000 +``` + +Acceptance: + +- `[ ]` Machine B imports Machine A as an untrusted peer candidate. +- `[ ]` Enrollment request submission reaches Machine A over Iroh. +- `[ ]` Machine A approval records signed keychain/auth operations. +- `[ ]` Machine B sync imports only valid signed operations. +- `[ ]` `geth wait peer owner` succeeds after enrollment. + +## Grants And Positive Sync Paths + +On Machine A: + +```sh +geth kv create prefs +geth document create notes +geth cas add README.md +geth pipe listen ops +geth auth grant resource:kv:prefs kv.read --signing-key ~/.ssh/id_ed25519 --grant-id dogfood-kv-read +geth auth grant resource:document:notes document.read --signing-key ~/.ssh/id_ed25519 --grant-id dogfood-document-read +geth auth grant resource:cas:local cas.fetch --signing-key ~/.ssh/id_ed25519 --grant-id dogfood-cas-fetch +geth auth grant resource:pipe:ops pipe.connect --signing-key ~/.ssh/id_ed25519 --grant-id dogfood-pipe-connect +geth auth grant resource:ssh-proxy:local ssh_proxy.connect --signing-key ~/.ssh/id_ed25519 --grant-id dogfood-ssh-proxy +``` + +On Machine B: + +```sh +geth auth sync owner +geth kv sync owner prefs +geth document sync owner notes +geth cas fetch owner +geth pipe send ops "dogfood" --node owner +geth ssh proxy owner +geth sync now owner +geth sync status --json +``` + +Acceptance: + +- `[ ]` Auth sync imports the expected grants. +- `[ ]` KV sync imports `prefs`. +- `[ ]` Document sync imports `notes`. +- `[ ]` CAS fetch retrieves the expected blob. +- `[ ]` Pipe send reaches the Machine A daemon-lifetime listener. +- `[ ]` SSH proxy opens only after `ssh_proxy.connect` is granted. +- `[ ]` `geth sync status --json` reports healthy or intentionally skipped + streams with actionable `next_action` values. + +## Denied Remote Operations + +On Machine B, attempt at least one operation without a matching grant: + +```sh +geth kv sync owner missing-or-denied +geth pipe listen denied --node owner +geth ssh admin-shell owner status +``` + +Acceptance: + +- `[ ]` Denied operations return stable JSON or text errors with recovery + hints. +- `[ ]` Machine A state does not mutate after denied operations. +- `[ ]` Machine A logs include command/resource/capability fields without + bearer tokens or private material. + +## Backup, Restore, Restart, And Doctor + +On Machine A: + +```sh +geth backup create --out /tmp/geth-backup +geth daemon service stop +geth daemon service start +geth wait daemon --timeout-ms 30000 +geth doctor --json +``` + +On a separate validation home: + +```sh +geth backup restore /tmp/geth-backup --target-home /tmp/geth-restore +GETH_HOME=/tmp/geth-restore geth doctor --json +``` + +Acceptance: + +- `[ ]` Backup excludes private SSH admin keys. +- `[ ]` Restore writes to the validation home without mutating the original + home. +- `[ ]` Service restart preserves identity, peer cards, resources, and sync + cursors. +- `[ ]` Intentionally broken setups produce actionable `geth doctor --json` + output. + +## Upgrade Evidence + +For every tagged pre-release after the first: + +```sh +geth --version +geth status --json +geth doctor --json +``` + +Acceptance: + +- `[ ]` Previous tagged pre-release homes migrate forward. +- `[ ]` Store schema, config, keychain/auth logs, CAS metadata, and peer cards + survive upgrade. +- `[ ]` Rollback expectations in `docs/release-support-policy.md` match the + observed behavior. + +## Sign-Off + +- `[ ]` All commands above match the current README and CLI help. +- `[ ]` Evidence is attached for Machine A. +- `[ ]` Evidence is attached for Machine B. +- `[ ]` Phase 10 in `docs/production-readiness-roadmap.md` is marked complete + only after the real-machine evidence is reviewed. diff --git a/docs/production-readiness-roadmap.md b/docs/production-readiness-roadmap.md index daea695..65e4605 100644 --- a/docs/production-readiness-roadmap.md +++ b/docs/production-readiness-roadmap.md @@ -329,6 +329,11 @@ Goal: make first deployment the start of a controlled compatibility story. Goal: prove the system works as an actual base layer before broader use. +Use [`dogfood-checklist.md`](dogfood-checklist.md) to record command output, +platform/version details, and evidence for this gate. This phase cannot be +marked complete from local unit or integration tests alone; it requires two real +machines and tagged pre-release upgrade evidence. + - `[ ]` Complete two-machine dogfood checklist. Acceptance criteria: - `[ ]` Fresh install works on at least two real machines. @@ -344,11 +349,12 @@ Goal: prove the system works as an actual base layer before broader use. ## Working Order 1. `[x]` Finish Phase 0. -2. `[~]` Refactor `geth-node` into daemon subsystems. +2. `[x]` Refactor `geth-node` into daemon subsystems. 3. `[x]` Add stable contract and golden JSON tests. 4. `[x]` Harden store migrations and backup. 5. `[x]` Complete security-boundary test coverage. 6. `[x]` Replace prototype private CAS cryptography. -7. `[ ]` Add fault-injection sync tests. -8. `[ ]` Improve automation commands and JSON errors. -9. `[ ]` Add operational health, doctor, and release gates. +7. `[x]` Add fault-injection sync tests. +8. `[x]` Improve automation commands and JSON errors. +9. `[x]` Add operational health, doctor, and release gates. +10. `[ ]` Complete the two-machine dogfood gate.