docs(handoff): machine-switch handoff report 2026-06-05

Session summary, branch inventory, push instructions, v1.1.8 follow-ups, and pickup-on-new-machine smoke commands. Main is at v1.1.7 (5cbb6ca); seven minor releases shipped this session via the dispatch-and-review workflow. Read this first on the new machine.
2026-06-05 07:12:06 +02:00
1 changed files with 382 additions and 0 deletions
--- a/HANDOFF.md
+++ b/HANDOFF.md
@@ -0,0 +1,382 @@
+# Handoff — 2026-06-05
+
+Machine-switch handoff. This document is the entry point for picking up
+PiCloud work on a different machine. It captures session state, what
+shipped, what's queued, and how to continue.
+
+---
+
+## TL;DR
+
+- **`main` is at v1.1.7** — seven minor releases (v1.1.1 → v1.1.7)
+  shipped this session via the dispatch-and-review workflow.
+- Working tree is clean.
+- Next release is **v1.1.8** (User Management). A draft dispatch prompt
+  is sketched in §6 below; ready to send to a dev agent.
+- One dev Postgres container (`picloud-postgres-1` on port 15432) is
+  still running on the source machine — tear it down with
+  `docker compose down -v` before the source machine goes offline.
+
+---
+
+## How to resume on the new machine
+
+```sh
+git clone https://git.mc02.dev/fabi/PiCloud.git
+cd PiCloud
+git checkout main
+git log --oneline -10        # should show v1.1.7 reviewer commit at HEAD
+docker compose up -d          # local Postgres for DB-gated tests
+export DATABASE_URL='postgres://picloud:picloud@127.0.0.1:5432/picloud'
+cargo test --workspace -- --test-threads=2
+```
+
+If you're starting from this branch (`handoff/2026-06-05`), it points at
+the same `main` HEAD with this `HANDOFF.md` added; merge or just read it
+and continue work on `main`.
+
+For the master encryption key needed by v1.1.7+ secrets:
+
+```sh
+export PICLOUD_SECRET_KEY="$(openssl rand -base64 32)"
+# OR, for dev only:
+export PICLOUD_DEV_MODE=true
+```
+
+The dev fallback uses a deterministic key (`SHA-256` of a hardcoded
+string) — fine for local testing, fatal for any real deployment.
+
+---
+
+## Session summary: v1.1.1 → v1.1.7
+
+All seven minor releases completed in one session via the dispatch
+workflow you set up: I draft a prompt, you dispatch it to a fresh
+agent in another session, the agent implements and writes `HANDBACK.md`,
+you bounce the report back to me, I audit the branch and write
+`REVIEW.md` with a verdict, you bounce-back-for-fixes-if-needed, and on
+approve I fast-forward merge into `main`.
+
+| Release | Capability | Iterations | Status |
+|---|---|---|---|
+| **v1.1.1** | Storage & Events (KV + triggers framework + outbox + dispatcher + NATS-style sync HTTP + dead-letter table + dashboard surface) | 1 | ✅ merged |
+| **v1.1.2** | Documents (`docs::*` SDK + query DSL + `docs:*` triggers) | 2 | ✅ merged (iteration 2 fixed a fmt diff) |
+| **v1.1.3** | Modules (`scripts.kind` + `PicloudModuleResolver` + AST caches + `script_imports`) | 1 | ✅ merged |
+| **v1.1.4** | Outbound HTTP & Scheduled Tasks (`http::*` with SSRF deny-list + cron triggers) | 1 | ✅ merged |
+| **v1.1.5** | Files & Pub/Sub (filesystem-backed blobs + `pubsub::publish_durable` + first CI workflow) | 1 | ✅ merged |
+| **v1.1.6** | Realtime Channels & Client Library (SSE + topics + HMAC subscriber tokens + `@picloud/client@1.0.0`) | 1 | ✅ merged |
+| **v1.1.7** | Configuration & Email (encrypted secrets + outbound/inbound email + dead-letter handler fix) | 1 | ✅ merged |
+
+**Versioning state on `main`:**
+- Workspace `1.1.7`
+- SDK schema `1.8`
+- Dashboard `0.13.0`
+- `@picloud/client` `1.0.0`
+- Migrations applied through `0025`
+
+**Test counts at HEAD:** `cargo test --workspace --test-threads=2` with
+`DATABASE_URL` set → **617 passed / 0 failed**. The `--test-threads=2`
+is required on shared dev Postgres (~9 concurrent `build_app`s
+otherwise exhaust connections); CI's dedicated Postgres doesn't hit
+this.
+
+---
+
+## Branches on this machine
+
+### v1.1.x feature branches (all merged into main, kept locally for traceability)
+
+| Branch | HEAD | What it contains |
+|---|---|---|
+| `feat/v1.1.1-storage-and-events` | `2796f36` | v1.1.1 work + HANDBACK + REVIEW |
+| `feat/v1.1.2-documents` | `5bbbc26` | v1.1.2 work (2 iterations) + HANDBACK + REVIEW |
+| `feat/v1.1.3-modules` | `6f17259` | v1.1.3 work + HANDBACK + REVIEW |
+| `feat/v1.1.4-http-cron` | `03d03ea` | v1.1.4 work + HANDBACK + REVIEW |
+| `feat/v1.1.5-files-pubsub` | `d064681` | v1.1.5 work + HANDBACK + REVIEW |
+| `feat/v1.1.6-realtime-client` | `64ad978` | v1.1.6 work + HANDBACK + REVIEW |
+| `feat/v1.1.7-secrets-email` | `5cbb6ca` | v1.1.7 work + HANDBACK + REVIEW |
+
+All seven HEADs are reachable from `main` (fast-forward merges). Keeping
+the branches makes it easy to inspect the per-release commit slice
+without git log filtering.
+
+### Older branches predating this session (state uncertain)
+
+These appeared in `git branch` at session start and weren't touched by
+v1.1.x work. I don't know which are abandoned, in-flight, or already
+merged under different names. **On the new machine, decide for each:**
+
+| Branch | Last commit | Tracking |
+|---|---|---|
+| `chore/ui-hardening` | `b42e273 fix(test): admin_is_implicit_app_admin uses force=true on app delete` | local-only |
+| `feat/app-members` | `e6fc6e6 test(picloud): close two app_members test gaps` | local-only |
+| `feat/cli` | `5d08974 style(cli): re-fmt one stray format! line in the integration test` | tracks `origin/feat/cli` (up to date) |
+| `feat/multi-app-scoping` | `a393f11 feat(dashboard): auto-slug app names and infer route host kind from input` | tracks `origin/feat/multi-app-scoping` (ahead 3) |
+| `feat/users-and-keys-ui` | `6eb32a7 feat(dashboard): adopt ActionMenu for user row actions` | local-only |
+| `feat/users-authz` | `2aab92a style: cargo fmt across Phase 3.5 changes` | local-only |
+| `test/cli-journeys` | `e4851b3 test(cli): extract shared Fixture into tests/common` | tracks `origin/test/cli-journeys` (up to date) |
+| `test/frontend-e2e` | `ec3c768 test(dashboard): add full-stack integration specs` | local-only |
+
+**Push these if you want them mirrored on the new machine** — see §3
+below for the push commands. If any are obsolete, delete them locally
+before resuming.
+
+---
+
+## §3 — Push instructions
+
+Push was denied in this session (sandbox restriction). Run these on the
+source machine to mirror state to `origin`:
+
+```sh
+# 1. The v1.1.x releases on main (55 commits)
+git push origin main
+
+# 2. The seven v1.1.x feature branches (preserves per-release history)
+git push origin feat/v1.1.1-storage-and-events
+git push origin feat/v1.1.2-documents
+git push origin feat/v1.1.3-modules
+git push origin feat/v1.1.4-http-cron
+git push origin feat/v1.1.5-files-pubsub
+git push origin feat/v1.1.6-realtime-client
+git push origin feat/v1.1.7-secrets-email
+
+# 3. This handoff branch
+git push -u origin handoff/2026-06-05
+
+# 4. OPTIONAL — push the older branches you want on the new machine
+#    (decide per-branch; some may be abandoned)
+git push origin chore/ui-hardening
+git push origin feat/app-members
+git push origin feat/multi-app-scoping     # ahead 3 of remote
+git push origin feat/users-and-keys-ui
+git push origin feat/users-authz
+git push origin test/frontend-e2e
+```
+
+After pushing, on the new machine: `git fetch --all` brings everything
+down. `git checkout main` puts you at v1.1.7 HEAD.
+
+---
+
+## §4 — Workflow context (read before dispatching v1.1.8)
+
+The dispatch-and-review workflow you've been using:
+
+1. **You ask me to draft the dispatch prompt** for the next release.
+2. **I draft the prompt** based on:
+   - The roadmap in [`docs/v1.1.x-design-notes.md` §7](docs/v1.1.x-design-notes.md)
+   - Three or so follow-ups identified in the prior release's REVIEW.md
+   - Discipline lessons carried forward from prior retros
+3. **You dispatch the prompt to a fresh agent in another session** —
+   that agent gets no prior conversation context; the prompt + the
+   docs it points at are everything they have.
+4. **The agent implements + writes `HANDBACK.md`** at the repo root,
+   then stops.
+5. **You bounce the HANDBACK back to me.**
+6. **I audit the branch and write `REVIEW.md`** with a verdict
+   (`APPROVE` or `NEEDS CHANGES`).
+7. **If `NEEDS CHANGES`:** you bounce the REVIEW back to the agent;
+   they iterate; back to step 5.
+8. **If `APPROVE`:** I fast-forward merge the branch into `main` and
+   pause for your next instruction.
+
+What's worked well across seven releases:
+
+- The discipline reminders compound. Each release's retro identifies
+  one small habit the agent dropped (§8 attestation hand-counting,
+  silent prompt-default deviations, brief-internal contradictions
+  silently reinterpreted, clippy run without `--all-targets`); the
+  next release's prompt explicitly addresses it. By v1.1.7 the agent
+  was catching their own latent findings without prompting.
+- Explicit "deviations beyond the brief" sections in HANDBACK make
+  audits fast — every meaningful judgment call is in one place.
+- The "this is the deferrable piece under scope pressure" clause in
+  big releases (v1.1.6 client lib, v1.1.7 inbound email) gave the
+  agent a clean escape hatch they never actually needed but worked
+  as intended.
+- Latent findings discovered during implementation (v1.1.3 cross-app
+  trigger gap, v1.1.4 SSRF literal-IP bypass, v1.1.6 dead_letter
+  handler never firing, v1.1.7 clippy regression at v1.1.6 HEAD) all
+  surfaced honestly rather than being silently worked around.
+
+What to do differently in v1.1.8:
+
+- **Walk through each code example in the prompt** before sending. v1.1.4
+  brief said `(url, opts)` but its example was `http::post(url, body)` —
+  the agent had to fix it during implementation. v1.1.7 brief sketched
+  `TriggerEvent::DeadLetter` field names that didn't match the actual
+  variant. Both flagged correctly, but pre-resolution saves agent
+  effort.
+- **Pin the clippy gate**: `cargo clean` before `cargo clippy
+  --all-targets` to defeat incremental-cache false-greens. See v1.1.7
+  REVIEW §3.3 for context.
+
+---
+
+## §5 — Pending follow-ups for v1.1.8
+
+From the v1.1.7 REVIEW.md, three load-bearing items to fold into the
+v1.1.8 dispatch prompt:
+
+### 5.1 Drop the plaintext `realtime_signing_key` column
+
+The v1.1.7 phase-2 commitment. v1.1.7 added NULL-able encrypted columns
+ DROP NOT NULL on the plaintext column; the startup task encrypts
+existing rows. v1.1.8 drops the plaintext column entirely.
+
+**Pre-flight check:** scan for any remaining non-NULL rows on the
+plaintext column. If found, run the encryption migration before the
+drop. If the v1.1.7 startup task ran on the operator's deploy, all
+rows should already be encrypted.
+
+**CHANGELOG must note** that v1.1.8 requires v1.1.7 to have been
+applied first. No skipping versions.
+
+### 5.2 Clippy `--all-targets` discipline refinement
+
+The v1.1.7 audit caught a real regression: four warnings predated
+v1.1.7 that the v1.1.6 audit reported as clippy-green. Likely cause:
+cargo's incremental cache leaving test binaries unchecked.
+
+v1.1.8 prompt should require either:
+- `cargo clean` before `cargo clippy --all-targets`, OR
+- Explicit verification that the clippy output includes `Checking`
+  lines for test crates.
+
+CI's `.github/workflows/ci.yml` (added in v1.1.5) might also benefit
+from a clippy-cache-check step.
+
+### 5.3 `auth_mode = 'session'` for realtime subscriber tokens
+
+v1.1.7's CHECK constraint on `topics.auth_mode` only allows
+`('public', 'token')`. v1.1.8's `users::*` work needs to:
+- Extend the CHECK to include `'session'`.
+- Add a session-token validator alongside the existing HMAC validator
+  behind the unchanged `RealtimeAuthority` trait.
+
+The trait shape from v1.1.6 already supports this — natural extension.
+
+---
+
+## §6 — Draft v1.1.8 dispatch prompt outline
+
+Not the full prompt — just the scope sketch so you can ask me to expand
+it on the new machine.
+
+**v1.1.8 — User Management (`users::*`)**
+
+Core scope:
+- `users::create / get / find / update / delete / list` SDK
+- Password hashing (argon2id)
+- `users` table per-app
+- Sessions: `users::login(email, password)` → returns a session token;
+  `users::verify(session_token)` returns the user or `()`
+- Sessions table with TTL + revocation
+- Email verification flow (uses v1.1.7 email::send)
+- Password reset flow (uses v1.1.7 email::send + tokens)
+- Invitations (admin creates an invite → email link → user accepts +
+  sets password)
+- Roles: per-app role assignments on users
+- `Capability::AppUsersRead/Write/Admin` mapped to existing scopes
+- Dashboard: Users tab on app detail page (list, invite, role-edit)
+
+Follow-ups from v1.1.7 retro (fold in):
+- Drop plaintext `realtime_signing_key` column (phase-2)
+- Clippy `--all-targets` discipline refinement
+- `auth_mode = 'session'` for realtime subscriber tokens (uses v1.1.8
+  sessions)
+
+Out of scope:
+- OAuth providers (defer to v1.2+)
+- 2FA / MFA (defer to v1.2+)
+- SSO / SAML (defer)
+- Password policy customization (defer; ship with sensible default)
+- User-to-user messaging (defer; userland)
+
+Ask me to expand this into a full prompt when you're ready.
+
+---
+
+## §7 — Environmental notes
+
+- **Dev Postgres container** `picloud-postgres-1` (port 15432) was
+  running at session end on the source machine. The v1.1.5/v1.1.6/
+  v1.1.7 agents started it for live DB-gated tests. **Tear down with
+  `docker compose down -v` before the source machine goes offline**
+  if you want a clean state.
+- **`PICLOUD_SECRET_KEY`** is required for v1.1.7+ to start. Pick one
+  with `openssl rand -base64 32` for production; use
+  `PICLOUD_DEV_MODE=true` (no master key needed) for local
+  development. The dev key is deterministic so secrets persist across
+  restarts in dev.
+- **CI workflow** lives at [`.github/workflows/ci.yml`](.github/workflows/ci.yml)
+  (added in v1.1.5). Runs fmt + clippy + `cargo test --workspace`
+  against a `postgres:15` service, plus dashboard `npm run check`.
+  When you push to `main` or open a PR, CI will run. **First push
+  after this handoff will exercise it for the first time on real
+  workload — watch the run.**
+
+---
+
+## §8 — Key documents for orientation
+
+- **[`CLAUDE.md`](CLAUDE.md)** — project conventions. Read first.
+- **[`serverless_cloud_blueprint.md`](serverless_cloud_blueprint.md)** —
+  the authoritative architecture document.
+- **[`docs/sdk-shape.md`](docs/sdk-shape.md)** — SDK conventions every
+  v1.1.x service follows.
+- **[`docs/v1.1.x-design-notes.md`](docs/v1.1.x-design-notes.md)** —
+  the in-flight-decisions document. Sections §1–§6 contain the
+  "Decided 2026-06-01" annotations from the design conversation that
+  preceded this session; §7 holds the v1.1.x roadmap; §1–4 are
+  candidates for pruning (their decisions shipped in v1.1.1).
+- **[`docs/versioning.md`](docs/versioning.md)** — patch-bump policy
+  under the post-1.0 expansion-phase carve-out.
+- **[`docs/git-workflow.md`](docs/git-workflow.md)** — trunk-based
+  workflow conventions.
+- **[`CHANGELOG.md`](CHANGELOG.md)** — release notes for v1.1.1 onward.
+  v1.1.7's entry includes the retroactive dead_letter security note.
+
+Per-release artifacts on `main`:
+- `HANDBACK.md` at repo root — currently holds the v1.1.7 agent's
+  handback. Overwritten each release.
+- `REVIEW.md` at repo root — currently holds the v1.1.7 reviewer's
+  audit. Overwritten each release.
+
+If you want the full per-release HANDBACK + REVIEW history, the seven
+`feat/v1.1.x-*` branches preserve them (each branch's `HEAD~1`
+contains the HANDBACK and `HEAD` contains the REVIEW for that release).
+
+---
+
+## §9 — Quick smoke after resuming
+
+After cloning + setting up the new machine:
+
+```sh
+# Basic gates
+cargo fmt --all -- --check
+cargo clippy --all-targets --all-features -- -D warnings
+cargo test --workspace
+
+# DB-gated (needs Postgres)
+docker compose up -d
+export DATABASE_URL='postgres://picloud:picloud@127.0.0.1:5432/picloud'
+export PICLOUD_DEV_MODE=true
+cargo test --workspace --test-threads=2
+
+# Dashboard
+cd dashboard && npm install && npm run check
+
+# Client library
+cd clients/typescript && npm install && npm run lint && npm run test && npm run build
+```
+
+If all green: machine is ready. Resume v1.1.8 work by asking me for
+the full dispatch prompt.
+
+---
+
+**Handoff written 2026-06-05.** Main HEAD: `5cbb6ca` (v1.1.7 reviewer
+APPROVE).