amadan
design: verify actual canary activation before building fixture writer
1 file changed,
+13
−3
docs/superpowers/specs/2026-09-07-canary-fixture-bootstrap.md+13 −3
CI cancelled — superseded by a newer push — run details
Intent
Human
READ-ONLY focused Fable DESIGN re-review; no edits/deploys/secret reads. Isolated repo /home/paulca/amadan.net/oficina/sheets-core/.claude/worktrees/overnight-fixture exact HEADc5ebba3 (parent1aca44c). Read previous REQUEST CHANGES /tmp/sheets-bootstrap-fable-review.json and changed docs/superpowers/specs/2026-09-07-canary-fixture-bootstrap.md. Revision2 adds distinct fixture-release stamp and negative equality assertions; exact synthetic nondelivering SMTP host/from/port plus empty inherited credentials verified by root, same LoadAuthEnv, no POST/signin; schema-derived emptiness, import-graph exclusion, path/session/idempotency/teardown tests and fail-closed wake note. Root must still verify actual resolved DB path and supported environment credential-empty semantics BEFORE implementation/deployment guards finalize; no environment mutation claimed. APPROVE or REQUEST CHANGES for design only, focus remaining blockers, not independent tabs/atomic/watermark reviews. No fixture code yet.
diff --git a/docs/superpowers/specs/2026-09-07-canary-fixture-bootstrap.md b/docs/superpowers/specs/2026-09-07-canary-fixture-bootstrap.md| index 1cd62ef..dd90ead 100644 |
| --- a/docs/superpowers/specs/2026-09-07-canary-fixture-bootstrap.md |
| +++ b/docs/superpowers/specs/2026-09-07-canary-fixture-bootstrap.md |
| @@ -1,6 +1,6 @@ |
| # Isolated Sheets canary session fixture |
| -Status: revision 2 proposed fallback; Fable 5.1 (claude-fable-5-1) requested changes at 1aca44c, incorporated below for re-review. Isolated branch test/canary-session-fixture, Amadan discussion 21. Do not deploy yet. Normal SMTP-based sign-in remains preferred and root has asked the user about a controlled mailbox. This design is only for testing unchanged session validation and editor behavior if that mailbox is unavailable. |
| +Status: revision 3; Fable 5.1 (claude-fable-5-1) approved revision 2 at c5ebba3. The runtime-path preflight evidence amendment below requires focused review before implementation. Isolated branch test/canary-session-fixture, Amadan discussion 21. Do not deploy yet. Normal SMTP-based sign-in remains preferred and root has asked the user about a controlled mailbox. This design is only for testing unchanged session validation and editor behavior if that mailbox is unavailable. |
| ## Target and boundary |
| @@ -13,15 +13,25 @@ Use a temporary reviewed bootstrap binary on this isolated instance, then replac |
| - Compile the single expected HTTPS origin and canary hostname into the bootstrap. Require SHEETS_ORIGIN to equal that origin exactly (scheme/host, no wildcard or suffix match). |
| - Require a one-use fixture run ID in a dedicated canary environment variable, and require it to equal the run ID compiled into this bootstrap build. It is a scope guard, not an authentication mechanism. |
| - Require SHEETS_OWNERS to equal exactly the synthetic owner address, with no additional addresses. Validate the key formats normally and require root's fresh-key provisioning record; do not compare against or obtain production key values. |
| -- The supported target is the platform exec-child contract: ExecBackend.Start invokes the binary with --socket <route.Socket> --db <route.DBPath or DataDir/host.db>. Read both through rastrillo.Resolve, not by parsing HTTP Host. The observed canary socket is exactly /run/carlos/overnight-sheets.bds.oncarlos.com.sock. The expected default database is /data/overnight-sheets.bds.oncarlos.com.db (platform DataDir defaults to /data). Root must confirm that resolved DB path from the route/activation configuration before building. Compile the confirmed absolute DB and socket paths, and reject any different path even if its basename matches. |
| +- The supported target is the platform exec-child contract: ExecBackend.Start invokes the binary with --socket <route.Socket> --db <route.DBPath or DataDir/host.db>. Read both through rastrillo.Resolve, not by parsing HTTP Host. The observed canary socket is exactly /run/carlos/overnight-sheets.bds.oncarlos.com.sock. The expected default database is /data/overnight-sheets.bds.oncarlos.com.db (platform DataDir defaults to /data). The control-plane API does not expose the resolved runtime DB path. Source defaults are not runtime evidence. Use the preflight-only binary below to obtain the actual exec-child argv before building a writer with a compiled exact DB path. Compile the confirmed absolute DB and socket paths, and reject any different path even if its basename matches. |
| - Validate both exact cleaned absolute paths and exact host-derived basenames. Reject parent traversal, a symlink database file, or a resolved parent directory outside the compiled expected root. For a fresh nonexistent DB, resolve/check the existing parent directory before opening it; after opening, confirm the path still identifies the expected file. Do not derive the expected paths from fixture-supplied environment values. If the deployment uses a non-default DataDir, review and compile that one actual absolute path rather than accepting arbitrary directories. |
| - STATE_DIRECTORY is not required for this exec-child shape. If present, it must not contradict the confirmed runtime paths, but its absence alone is not a failure. Supporting a systemd unit-backed shape later requires a separate explicit guard variant, not a basename-only fallback. |
| - Before deployment, root verifies the control-plane route has this exact host, named environment and canary-only channel. Runtime path/origin guards complement that check; neither a release name nor an HTTP Host header alone establishes isolation. |
| - Refuse bootstrap if any app content or member/grant/session row already exists. This is a fresh-fixture tool, not a repair or reset tool. Enumerate all application/framework user tables from sqlite_master and require them empty, except the existing migration ledger and the one exact idempotent sessions row. Exclude only SQLite internal tables and the exact framework migration-ledger name. Test that this enumeration covers every table BootSchema creates (currently 12 Sheets tables plus sessions, auth_links and auth_sessions). Existing migration ledger rows alone are harmless. Never clear tables to make the precondition pass. |
| +## Read-only activation preflight |
| + |
| +Root has confirmed the named environment supports explicit empty values and configured the synthetic SMTP values below; default app configuration remains untouched. The route API exposes the exact canary socket, channel and environment but not its resolved DB path. A separate preflight-only command closes that evidence gap before a writer is built. |
| + |
| +Build cmd/sheets-fixture-preflight with a clean-tree fixture-preflight-release target and a unique <sha>-fixture-preflight-<runID> stamp. It contains no database-open, migration, seed, socket-listen or filesystem-probing path. It validates the compiled exact origin, synthetic owner, one-use run ID, SMTP settings and key formats against the actual child environment. This catches an unexpected box-local .env override without opening or printing that file or any secret value. A mismatch refuses with a fixed guard code. It parses the activation args, rejects relative/unclean DB paths before Resolve could join them, requires the exact known canary socket and exact canary DB basename, and refuses addr/LISTEN_FDS or other unsupported shapes. |
| + |
| +After these guards pass, report only the preflight stamp, validated canary DB argument and socket argument to the operator log, then exit. No file or socket is opened, no database is materialized, no environment changes, no HTTP route is served, and no app assertion runs. Root reads only this instance's supported logs and records that one observed path. The activation may report unsuccessful readiness because preflight deliberately exits without serving; that expected result is not a failed candidate test. Repeated activation only repeats the same guarded read-only observation. |
| + |
| +Root reviews the observed absolute path and confirms it is this canary's path. Compile that exact DB path into a different startup-only writer binary. It retains all symlink/parent/empty-database/transaction/session guards below. There is no env flag that turns the permissive path-observer into a writer. Candidate and writer never learn their expected DB paths from caller-controlled fixture environment. Remove the preflight channel reference when promoting the writer. Test that preflight cannot create a DB or socket and that its package has no database/migration/seed dependencies; the candidate import-graph gate excludes both fixture commands/packages. No generic shell, directory listing or path probing across tenants is part of this sequence. |
| + |
| ## Candidate boot and transport isolation |
| -Before building or deploying, root configures the named canary environment with CARLOS_SMTP_HOST=smtp-fixture.invalid, CARLOS_SMTP_FROM=oficina-fixture@example.test and CARLOS_SMTP_PORT=587. CARLOS_SMTP_USER and CARLOS_SMTP_PASS must be explicitly empty in the resolved child environment; root verifies supported named-environment semantics suppress any inherited credentials. These are synthetic nondelivering values, not a usable SMTP service. The candidate requires nonempty host/from to boot at a non-loopback origin even when session fixtures bypass email delivery. Bootstrap calls the same sheets.LoadAuthEnv as the normal candidate and validates this exact synthetic transport configuration. Never POST /signin during fixture assertions; local browser tests must intercept/fail any attempted sign-in POST. Normal GET /signin as a redirect destination remains valid. Email delivery remains untested. Root confirms exact resolved database path and transport binding before bootstrap implementation/deployment guards are finalized. |
| +Before building or deploying, root configures the named canary environment with CARLOS_SMTP_HOST=smtp-fixture.invalid, CARLOS_SMTP_FROM=oficina-fixture@example.test and CARLOS_SMTP_PORT=587. CARLOS_SMTP_USER and CARLOS_SMTP_PASS must be explicitly empty in the resolved child environment; root verifies supported named-environment semantics suppress any inherited credentials. These are synthetic nondelivering values, not a usable SMTP service. The candidate requires nonempty host/from to boot at a non-loopback origin even when session fixtures bypass email delivery. Bootstrap calls the same sheets.LoadAuthEnv as the normal candidate and validates this exact synthetic transport configuration. Never POST /signin during fixture assertions; local browser tests must intercept/fail any attempted sign-in POST. Normal GET /signin as a redirect destination remains valid. Email delivery remains untested. The read-only preflight verifies actual resolved child transport values; root confirms the observed database path before the writer implementation/deployment guards are finalized. |
| ## Session material and initialization |