amadan
db-region-forward: review brief for an independent Astra pass
Fixes the approved direction and the run transport ruling as not open to re-argument, points the reviewer at the code each decision rests on, and asks ten questions led by sandbox isolation, prefix derivation and replay.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
1 file changed,
+140
−0
docs/superpowers/specs/CODEX-REVIEW-BRIEF-DB-REGION-FORWARD.md+140 −0
CI passed — run details
CI log
=== gate ===
.amadan/test-gate.sh
=== launchctx (0 s)
ok amadan.net/carlos/platform.git/launchctx 0.012s
? amadan.net/carlos/platform.git/launchctx/controlname [no test files]
? amadan.net/carlos/platform.git/launchctx/wireid [no test files]
=== vet (18 s)
=== gofmt (0 s)
gofmt -l .: clean
=== rest (169 s)
? github.com/carlosframework/platform/cmd/changelog [no test files]
ok github.com/carlosframework/platform/cmd/console 3.839s
ok github.com/carlosframework/platform/cmd/moveprobe 11.990s
ok github.com/carlosframework/platform/cmd/zddprobe 0.741s
ok github.com/carlosframework/platform/internal/activator 61.025s
ok github.com/carlosframework/platform/internal/agentsock 0.042s
ok github.com/carlosframework/platform/internal/alerting 0.017s
ok github.com/carlosframework/platform/internal/analytics 0.033s
ok github.com/carlosframework/platform/internal/appconfig 2.958s
ok github.com/carlosframework/platform/internal/apperr 0.166s
ok github.com/carlosframework/platform/internal/applog 0.250s
ok github.com/carlosframework/platform/internal/awsinv 0.019s
ok github.com/carlosframework/platform/internal/boxchoice 0.015s
ok github.com/carlosframework/platform/internal/boxid 0.767s
? github.com/carlosframework/platform/internal/boxid/boxidtest [no test files]
? github.com/carlosframework/platform/internal/boxid/internal/signtest [no test files]
ok github.com/carlosframework/platform/internal/boxvolumes 0.014s
ok github.com/carlosframework/platform/internal/caps 0.021s
ok github.com/carlosframework/platform/internal/certwarm 0.008s
ok github.com/carlosframework/platform/internal/cgroup 0.813s
ok github.com/carlosframework/platform/internal/changelog 0.585s
ok github.com/carlosframework/platform/internal/claimactivation 1.323s
ok github.com/carlosframework/platform/internal/clamd 0.060s
? github.com/carlosframework/platform/internal/cliflag [no test files]
? github.com/carlosframework/platform/internal/controlname [no test files]
? github.com/carlosframework/platform/internal/controlsock [no test files]
ok github.com/carlosframework/platform/internal/dbdoor 6.042s
ok github.com/carlosframework/platform/internal/dbdoor/dbdoortest 0.020s
ok github.com/carlosframework/platform/internal/dbverify 0.008s
ok github.com/carlosframework/platform/internal/dnsrec 0.007s
ok github.com/carlosframework/platform/internal/docsite 0.015s
ok github.com/carlosframework/platform/internal/domains 3.038s
ok github.com/carlosframework/platform/internal/doorkey 0.013s
ok github.com/carlosframework/platform/internal/economics 0.009s
ok github.com/carlosframework/platform/internal/edge 46.165s
? github.com/carlosframework/platform/internal/edgeproof [no test files]
ok github.com/carlosframework/platform/internal/edgesfile 0.015s
ok github.com/carlosframework/platform/internal/fleetapi 0.160s
ok github.com/carlosframework/platform/internal/gate 1.660s
ok github.com/carlosframework/platform/internal/genselect 0.034s
ok github.com/carlosframework/platform/internal/geo 0.015s
ok github.com/carlosframework/platform/internal/geoip 0.048s
ok github.com/carlosframework/platform/internal/historyreadback 0.250s
ok github.com/carlosframework/platform/internal/host 139.787s
ok github.com/carlosframework/platform/internal/hostactors 5.643s
ok github.com/carlosframework/platform/internal/hostactors/awsmembership 0.014s
ok github.com/carlosframework/platform/internal/hostbox 2.982s
ok github.com/carlosframework/platform/internal/hostclaim 0.851s
ok github.com/carlosframework/platform/internal/hostenv 0.013s
ok github.com/carlosframework/platform/internal/hostevidence 0.014s
ok github.com/carlosframework/platform/internal/hostexec 5.483s
ok github.com/carlosframework/platform/internal/hostfence 0.038s
ok github.com/carlosframework/platform/internal/hostfiles 10.392s
ok github.com/carlosframework/platform/internal/hostfloor 0.021s
ok github.com/carlosframework/platform/internal/hostguard 1.071s
ok github.com/carlosframework/platform/internal/hostops 2.066s
? github.com/carlosframework/platform/internal/hostops/fencerelease [no test files]
ok github.com/carlosframework/platform/internal/hostops/internal/fencerelease 0.013s
ok github.com/carlosframework/platform/internal/hostquarantine 0.014s
ok github.com/carlosframework/platform/internal/hostrelocate 0.680s
ok github.com/carlosframework/platform/internal/hostresolve 0.206s
ok github.com/carlosframework/platform/internal/hostwrite 0.013s
ok github.com/carlosframework/platform/internal/infraview 0.014s
ok github.com/carlosframework/platform/internal/instancectl 5.227s
ok github.com/carlosframework/platform/internal/instanceexec 2.802s
ok github.com/carlosframework/platform/internal/instancefs 0.022s
ok github.com/carlosframework/platform/internal/instancekey 0.002s
ok github.com/carlosframework/platform/internal/instanceupdates 0.025s
ok github.com/carlosframework/platform/internal/layout 1.871s
ok github.com/carlosframework/platform/internal/lbhealth 0.017s
ok github.com/carlosframework/platform/internal/lease 10.210s
ok github.com/carlosframework/platform/internal/lease/leasetest 0.645s
ok github.com/carlosframework/platform/internal/ledger 0.038s
ok github.com/carlosframework/platform/internal/mail 0.261s
ok github.com/carlosframework/platform/internal/maintenance 0.082s
ok github.com/carlosframework/platform/internal/maintenanceexec 5.577s
ok github.com/carlosframework/platform/internal/maintenanceguard 0.160s
ok github.com/carlosframework/platform/internal/metrics 0.005s
ok github.com/carlosframework/platform/internal/moves 22.831s
ok github.com/carlosframework/platform/internal/moves/archive 1.036s
ok github.com/carlosframework/platform/internal/objstore 0.321s
ok github.com/carlosframework/platform/internal/ops 0.216s
ok github.com/carlosframework/platform/internal/park 0.272s
ok github.com/carlosframework/platform/internal/plans 0.015s
ok github.com/carlosframework/platform/internal/privatefile 0.004s
ok github.com/carlosframework/platform/internal/provision 23.667s
ok github.com/carlosframework/platform/internal/publicrelease 0.010s
? github.com/carlosframework/platform/internal/regionname [no test files]
ok github.com/carlosframework/platform/internal/registry 5.687s
ok github.com/carlosframework/platform/internal/relay 7.226s
ok github.com/carlosframework/platform/internal/release 26.777s
ok github.com/carlosframework/platform/internal/rollout 3.827s
ok github.com/carlosframework/platform/internal/rolloutwords 0.006s
ok github.com/carlosframework/platform/internal/rootaws 0.009s
ok github.com/carlosframework/platform/internal/rootparticipation 0.065s
ok github.com/carlosframework/platform/internal/rootstate 0.026s
ok github.com/carlosframework/platform/internal/runs 0.578s
ok github.com/carlosframework/platform/internal/s3compat 0.005s
ok github.com/carlosframework/platform/internal/safefile 0.004s
ok github.com/carlosframework/platform/internal/schedule 2.702s
ok github.com/carlosframework/platform/internal/seeds 0.013s
ok github.com/carlosframework/platform/internal/sim/engines 2.677s
ok github.com/carlosframework/platform/internal/sim/hostlife 12.565s
ok github.com/carlosframework/platform/internal/sim/litestreamfacts 4.535s
ok github.com/carlosframework/platform/internal/status 0.073s
ok github.com/carlosframework/platform/internal/steering 0.009s
ok github.com/carlosframework/platform/internal/stopevidence 0.302s
ok github.com/carlosframework/platform/internal/svcrole 0.003s
ok github.com/carlosframework/platform/internal/telemetry 0.004s
ok github.com/carlosframework/platform/internal/termfence 0.004s
ok github.com/carlosframework/platform/internal/tunnelclient 0.007s
ok github.com/carlosframework/platform/internal/unixdial 0.007s
ok github.com/carlosframework/platform/internal/updatewords 0.005s
ok github.com/carlosframework/platform/internal/usage 0.007s
ok github.com/carlosframework/platform/internal/version 0.002s
ok github.com/carlosframework/platform/internal/vet 1.753s
=== internal_console@0 (79 s)
ok github.com/carlosframework/platform/internal/console 77.686s
=== internal_console@1 (35 s)
ok github.com/carlosframework/platform/internal/console 33.840s
=== internal_console@2 (43 s)
ok github.com/carlosframework/platform/internal/console 41.356s
=== internal_console@3 (37 s)
ok github.com/carlosframework/platform/internal/console 35.428s
=== internal_console@4 (39 s)
ok github.com/carlosframework/platform/internal/console 37.208s
=== internal_console@5 (40 s)
ok github.com/carlosframework/platform/internal/console 38.275s
=== internal_console@6 (42 s)
ok github.com/carlosframework/platform/internal/console 40.995s
=== internal_console@7 (43 s)
ok github.com/carlosframework/platform/internal/console 41.441s
=== root@0 (34 s)
ok github.com/carlosframework/platform 32.807s
=== root@1 (45 s)
ok github.com/carlosframework/platform 43.481s
=== root@2 (42 s)
ok github.com/carlosframework/platform 40.868s
=== cross ===
--- shard 0 of 5 ---
cross-compiling darwin/arm64
--- shard 1 of 5 ---
cross-compiling darwin/amd64
--- shard 2 of 5 ---
cross-compiling linux/arm64
linux/arm64 carlos binary: 50069666 bytes (ceiling 52000000)
--- shard 3 of 5 ---
cross-compiling windows/amd64
--- shard 4 of 5 ---
cross-compiling windows/arm64
=== minio-contract ===
minio contract: arm64, minio RELEASE.2025-09-07T16-13-09Z, mc RELEASE.2025-08-13T08-35-41Z
minio: downloading https://github.com/minio/minio/releases/download/RELEASE.2025-09-07T16-13-09Z/minio.linux-arm64.RELEASE.2025-09-07T16-13-09Z
minio: downloaded, digest verified
mc: downloading https://github.com/minio/mc/releases/download/RELEASE.2025-08-13T08-35-41Z/mc.linux-arm64.RELEASE.2025-08-13T08-35-41Z
mc: downloaded, digest verified
minio healthy on 127.0.0.1:20999
Added `local` successfully.
Bucket created successfully `local/contract-bucket`.
Bucket created successfully `local/denied-bucket`.
Created policy `contract-only` successfully.
Added user `scopeduser` successfully.
Attached Policies: [contract-only]
To User: scopeduser
buckets and scoped user ready
=== RUN TestDeliveredContractMinio
=== RUN TestDeliveredContractMinio/put
=== RUN TestDeliveredContractMinio/get_round-trips_the_body
=== RUN TestDeliveredContractMinio/list_shows_the_key
=== RUN TestDeliveredContractMinio/head_and_list_agree_on_the_version
=== RUN TestDeliveredContractMinio/the_app_cannot_tag_its_own_object
=== RUN TestDeliveredContractMinio/the_app_cannot_tag_its_own_object/not_by_PutObjectTagging
=== RUN TestDeliveredContractMinio/the_app_cannot_tag_its_own_object/and_not_by_x-amz-tagging_on_upload
=== RUN TestDeliveredContractMinio/the_app_cannot_tag_by_any_other_route
=== RUN TestDeliveredContractMinio/the_app_cannot_tag_by_any_other_route/not_by_CreateMultipartUpload
=== RUN TestDeliveredContractMinio/the_app_cannot_tag_by_any_other_route/not_by_CopyObject_with_a_REPLACE_tagging_directive
=== RUN TestDeliveredContractMinio/the_app_cannot_tag_by_any_other_route/but_multipart_itself_is_allowed
=== RUN TestDeliveredContractMinio/the_app_cannot_tag_by_any_other_route/and_copy_itself_is_allowed
=== RUN TestDeliveredContractMinio/the_app_cannot_tag_by_any_other_route/a_POST-policy_forged_tag_with_a_matching_version_is_still_not_a_verdict
=== RUN TestDeliveredContractMinio/the_app_cannot_tag_by_any_other_route/and_an_ordinary_tagged-with-something-else_upload_is_allowed
=== RUN TestDeliveredContractMinio/delete_removes_it
=== RUN TestDeliveredContractMinio/cross-bucket_denial
--- PASS: TestDeliveredContractMinio (0.02s)
--- PASS: TestDeliveredContractMinio/put (0.00s)
--- PASS: TestDeliveredContractMinio/get_round-trips_the_body (0.00s)
--- PASS: TestDeliveredContractMinio/list_shows_the_key (0.00s)
--- PASS: TestDeliveredContractMinio/head_and_list_agree_on_the_version (0.00s)
--- PASS: TestDeliveredContractMinio/the_app_cannot_tag_its_own_object (0.00s)
--- PASS: TestDeliveredContractMinio/the_app_cannot_tag_its_own_object/not_by_PutObjectTagging (0.00s)
--- PASS: TestDeliveredContractMinio/the_app_cannot_tag_its_own_object/and_not_by_x-amz-tagging_on_upload (0.00s)
--- PASS: TestDeliveredContractMinio/the_app_cannot_tag_by_any_other_route (0.01s)
--- PASS: TestDeliveredContractMinio/the_app_cannot_tag_by_any_other_route/not_by_CreateMultipartUpload (0.00s)
--- PASS: TestDeliveredContractMinio/the_app_cannot_tag_by_any_other_route/not_by_CopyObject_with_a_REPLACE_tagging_directive (0.00s)
--- PASS: TestDeliveredContractMinio/the_app_cannot_tag_by_any_other_route/but_multipart_itself_is_allowed (0.00s)
--- PASS: TestDeliveredContractMinio/the_app_cannot_tag_by_any_other_route/and_copy_itself_is_allowed (0.00s)
--- PASS: TestDeliveredContractMinio/the_app_cannot_tag_by_any_other_route/a_POST-policy_forged_tag_with_a_matching_version_is_still_not_a_verdict (0.00s)
--- PASS: TestDeliveredContractMinio/the_app_cannot_tag_by_any_other_route/and_an_ordinary_tagged-with-something-else_upload_is_allowed (0.00s)
--- PASS: TestDeliveredContractMinio/delete_removes_it (0.00s)
--- PASS: TestDeliveredContractMinio/cross-bucket_denial (0.00s)
PASS
ok github.com/carlosframework/platform/internal/objstore 0.025s
=== RUN TestT4StorageProbeMinio
2026/10/22 11:10:53 moves: T4: STORE: list: operation error S3: ListObjectsV2, https response error StatusCode: 403, RequestID: 18E0D58D0951D3CC, HostID: 7c420053e0fbcd7f41653fdd92ffa2802c903d05303b1aa15adc2e8bb65d183f, api error SignatureDoesNotMatch: The request signature we calculated does not match the signature you provided. Check your key and signing method.
--- PASS: TestT4StorageProbeMinio (0.01s)
PASS
ok github.com/carlosframework/platform/internal/host 0.023s
minio contract: PASS
diff --git a/docs/superpowers/specs/CODEX-REVIEW-BRIEF-DB-REGION-FORWARD.md b/docs/superpowers/specs/CODEX-REVIEW-BRIEF-DB-REGION-FORWARD.md| new file mode 100644 |
| index 000000000..738d00eb5 |
| --- /dev/null |
| +++ b/docs/superpowers/specs/CODEX-REVIEW-BRIEF-DB-REGION-FORWARD.md |
| @@ -0,0 +1,140 @@ |
| +# Review brief: `carlos db` reads for instances in another region |
| + |
| +You are an independent second reader of one design spec for the CARLOS |
| +platform (this repository). Read it cold and adversarially. Nothing is built |
| +yet; you are reviewing the design against the code on `main`. |
| + |
| +**Spec:** `docs/superpowers/specs/2026-10-22-db-region-forward-design.md`, |
| +at the commit named in the prompt. Read `AGENTS.md` first. |
| + |
| +## Fixed rulings: do not re-argue them |
| + |
| +The product owner approved this direction: |
| + |
| +- the console forwards a db read to a box in the region where the data |
| + lives; |
| +- that box reads its own region's replica, runs the read-only operation |
| + there, and returns only the result; |
| +- the console never reads another region's bucket; |
| +- there is no console per region. |
| + |
| +The `carlos run` spec's ruling also holds: the console never connects to a |
| +box, and output travels as objects in the deployment bucket. |
| + |
| +Do not propose alternatives to these (a console per region, an IAM grant |
| +that lets the console read other regions, a direct console-to-box |
| +connection). Report only: |
| + |
| +- a mechanism that **fails to honour** a ruling; |
| +- a mechanism that breaks something else in the platform; |
| +- a mechanism that cannot be built as described against `main`. |
| + |
| +The spec's own decisions (§4, D1 to D8) are open to challenge. Its open |
| +questions (§16) are for the product owner; comment on them only where the |
| +spec's answer is unsafe. |
| + |
| +## What to check |
| + |
| +Check against the code, not the spec's description of it. Cite `file:line` |
| +for every claim about existing code. These are the places that matter. |
| + |
| +**The db door and the CLI:** |
| + |
| +- `internal/console/apidb.go`: `resolveReplica`, `dbGate`, |
| + `resolveDBSource`, `dbClassRefusal`, `listReplicaLevel`, the stream bounds; |
| +- `internal/console/apidbclaim.go`: why the claim door stays refused; |
| +- `db.go`: `runQueryContext`, `checkQuerySQL`, `dbRestoreError`, |
| + `dbQueryStatus`; |
| +- `internal/dbdoor/`: `plan.go` (`PlanRestore`), `restore.go` |
| + (`RestoreAsOf`, the `--at` path), `client.go`; |
| +- `internal/lease/endpoint.go`: `ReadReplicaClient`, the root-credential |
| + branch of `newReplicaClientForUID`. |
| + |
| +**The transport the spec copies:** |
| + |
| +- `internal/runs/runs.go`, `store.go`; `internal/console/apiruns.go`, |
| + `apirunsfollow.go`, `runsweep.go`; `internal/host/runs.go`; |
| +- `internal/release/rootenvelope.go` and `hostretry.go`: the signed-request |
| + precedent; |
| +- `internal/appconfig/crypto.go`: the sealing construction the spec reuses. |
| + |
| +**Boxes, capability and sandbox:** |
| + |
| +- `internal/host/edgesfile.go` (capabilities), `movesoffline.go` and |
| + `movesoffline_stage.go` (how a capability is tied to an armed worker); |
| +- `internal/edgesfile/snapshot.go`: `ReadLiveSnapshot`, `Draining`, `Fresh`; |
| +- `internal/host/claimunit_template.go`, `bootstrap.go` (`tmpfilesConf`, |
| + socket ownership), and wherever `ensureSystemUnits` installs units; |
| +- `internal/activator/backend_unit.go`: how `carlos-app@` units and their |
| + sockets are started without root. |
| + |
| +**IAM and infrastructure:** |
| + |
| +- `infra/modules/region-host/main.tf`: `host_buckets`; |
| +- carlosframework/carloku-infrastructure `region-uk.tf` and `region-ie.tf` |
| + (on GitHub): which bucket each box role reaches, and the module refs. |
| + |
| +**Census:** |
| + |
| +- `internal/provision/plan14_root_reads_test.go`, |
| + `plan9_b8_census_test.go`, `moves_offline_census_test.go`; |
| +- `docs/superpowers/notes/census-proposal-moves-offline-precopy.md` for how |
| + an overlay is proposed and ruled. |
| + |
| +## Questions worth your time |
| + |
| +1. **Isolation.** Can the member's SQL, or a crafted replica, reach anything |
| + but its own copy? Check the worker unit in §8.3 option by option against |
| + what `DynamicUser`, `PrivateNetwork`, `TemporaryFileSystem`, |
| + `PrivateTmp` and `Accept=yes` actually do. Check every SQLite path that |
| + opens a file (ATTACH, `VACUUM INTO`, extensions, temp files, `immutable`) |
| + with modernc.org/sqlite v1.55.0. Can the worker reach the metadata |
| + service, the box role, `/data`, `/etc/carlos` or another tenant's files? |
| +2. **The prefix.** Is there any path where a request field, rather than the |
| + fresh record and the box's own config, picks the bucket, prefix, host or |
| + level? Is the incarnation check placed so a host recreated between |
| + request and read cannot be read under the old request? |
| +3. **Forgery and replay.** Is the root envelope bound tightly enough |
| + (purpose, id, region, issued_at)? Can any other root-signed payload be |
| + read as a db-read request, or the reverse? Does the seen set plus the |
| + 60 s window close a second run of one request? Does sealing really make |
| + a replay harmless? |
| +4. **Election and expiry.** Can two boxes both run one read? Can the |
| + console's expiry and a late box both believe they own `picked`? Can a |
| + result land before its last chunk, or a chunk after the result? |
| +5. **Cleanup and disk.** On every exit path (done, failed, cancel, CLI gone, |
| + agent restart, `kill -9`, box reboot, console restart), what is left in |
| + the deployment bucket and on the box? Is the disk floor enough on a 60 GiB |
| + box that also stages versions? Can the unacked window deadlock? |
| +6. **Parity.** Will the forwarded `--at` stop at the same transaction as the |
| + in-region door for the same replica and time, given the second |
| + truncation of `LastModified`? Will the forwarded output be byte-identical |
| + to the in-region output across CLI and box versions? |
| +7. **Mixed fleet.** Walk §9.2 and §11.2. Can a box publish `db-read-1` |
| + without an armed worker? What does a host-claim console, a console with |
| + a scoped key, or a console with `CARLOS_DB_FORWARD` unset answer? |
| +8. **Census and build.** Are §13's classifications right for the root-read |
| + scan as it is actually written (it matches `Open`, `Query`, |
| + `QueryContext` and more across all production packages)? Does the worker |
| + code cross-compile for darwin and windows as described? |
| +9. **Provider boundary.** Does anything in the design need AWS to work on a |
| + MinIO deployment with one store per region? |
| +10. **Missing pieces.** Anything the spec relies on that does not exist, or |
| + exists in a different shape. |
| + |
| +## Output |
| + |
| +A numbered list of findings. Each one gives: |
| + |
| +- **severity:** P1 breaks a ruling, crosses a tenant, or exposes box |
| + credentials; P2 is wrong behaviour; P3 is clarity or a gap; |
| +- the spec section; |
| +- the code evidence, with `file:line`; |
| +- a concrete fix. |
| + |
| +Then a one-line verdict: accept, or revise. Do not rewrite the spec. No |
| +praise. |
| + |
| +On a later round you will be given your earlier findings files. Start with a |
| +disposition table (finding: fixed, declined with an acceptable reason, or not |
| +fixed), then give only new findings. |