geth/docs/dogfood-checklist.md

# 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.

Create one evidence directory per run and keep raw JSON, command transcripts,
and relevant redacted logs there. Do not store bearer tokens, private keys, or
unencrypted backup contents in the evidence directory. A run is reviewable only
when its evidence can be tied to the matrix and sign-off records below.

## Evidence Log

Copy this table for each attempt. Use ISO 8601 timestamps and paths or issue
links that another reviewer can open.

| Field | Machine A | Machine B |
| --- | --- | --- |
| Run ID | `<YYYYMMDD-sequence>` | `<same run ID>` |
| Started at | `<timestamp>` | `<timestamp>` |
| Platform/architecture | `<value>` | `<value>` |
| geth version/commit | `<value>` | `<value>` |
| Install method/artifact checksum | `<value>` | `<value>` |
| Fresh `GETH_HOME` | `<path or identifier>` | `<path or identifier>` |
| Command transcript | `<path or link>` | `<path or link>` |
| JSON and log evidence | `<path or link>` | `<path or link>` |
| Result | `pass` / `fail` / `incomplete` | `pass` / `fail` / `incomplete` |

Record each failed or skipped step separately:

| Timestamp | Machine | Step | Result | Evidence | Follow-up |
| --- | --- | --- | --- | --- | --- |
| `<timestamp>` | `A` / `B` | `<section and command>` | `<result>` | `<path or link>` | `<issue or action>` |

## 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 <request-id> --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 kv set prefs theme dark
geth document create notes
geth document set notes '{"purpose":"dogfood"}'
geth cas add README.md
geth pipe listen ops
geth auth grant <worker-node-id> resource:kv:prefs kv.read --signing-key ~/.ssh/id_ed25519 --grant-id dogfood-kv-read
geth auth grant <worker-node-id> resource:document:notes document.read --signing-key ~/.ssh/id_ed25519 --grant-id dogfood-document-read
geth auth grant <worker-node-id> resource:cas:local cas.fetch --signing-key ~/.ssh/id_ed25519 --grant-id dogfood-cas-fetch
geth auth grant <worker-node-id> resource:pipe:ops pipe.connect --signing-key ~/.ssh/id_ed25519 --grant-id dogfood-pipe-connect
geth auth grant <worker-node-id> 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 kv get prefs theme
geth document sync owner notes
geth document get notes
geth cas fetch owner <hash>
geth pipe send ops "dogfood" --node owner
geth sync now owner
geth sync status --json
```

Back on Machine A, verify the pipe payload:

```sh
geth pipe recv ops
```

Verify the SSH proxy with a bounded OpenSSH probe from Machine B. Replace
`<ssh-user>` with an account accepted by Machine A's local SSH service:

```sh
ssh -o BatchMode=yes -o ConnectTimeout=10 \
  -o 'ProxyCommand=geth ssh proxy owner' \
  <ssh-user>@owner true
```

An authentication failure after the SSH handshake is sufficient to prove byte
transport when Machine A intentionally has no matching SSH credential; record
the verbose `ssh -v` transcript. A timeout or geth authorization error is not a
successful proxy check.

Acceptance:

- `[ ]` Auth sync imports the expected grants.
- `[ ]` KV sync imports `prefs` and Machine B reads `theme=dark`.
- `[ ]` Document sync imports the `{"purpose":"dogfood"}` state.
- `[ ]` CAS fetch retrieves the expected blob.
- `[ ]` Pipe send reaches the Machine A listener and `pipe recv` returns the
  exact payload.
- `[ ]` The bounded SSH probe reaches Machine A's SSH handshake 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.

| Role | Name | Timestamp | Run ID | Result |
| --- | --- | --- | --- | --- |
| Operator A | `<name>` | `<timestamp>` | `<run ID>` | `<result>` |
| Operator B | `<name>` | `<timestamp>` | `<run ID>` | `<result>` |
| Reviewer | `<name>` | `<timestamp>` | `<run ID>` | `approved` / `rejected` |