amadan
plans: edge protection plan 1, request records and reference codes
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
1 file changed,
+813
−0
docs/superpowers/plans/2026-10-24-edge-protection-1-request-records.md+813 −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 (174 s)
? github.com/carlosframework/platform/cmd/changelog [no test files]
ok github.com/carlosframework/platform/cmd/console 3.888s
ok github.com/carlosframework/platform/cmd/moveprobe 11.933s
ok github.com/carlosframework/platform/cmd/zddprobe 0.766s
ok github.com/carlosframework/platform/internal/activator 58.976s
ok github.com/carlosframework/platform/internal/agentsock 0.028s
ok github.com/carlosframework/platform/internal/alerting 0.009s
ok github.com/carlosframework/platform/internal/analytics 0.040s
ok github.com/carlosframework/platform/internal/appconfig 3.034s
ok github.com/carlosframework/platform/internal/apperr 0.130s
ok github.com/carlosframework/platform/internal/applog 0.215s
ok github.com/carlosframework/platform/internal/awsinv 0.006s
ok github.com/carlosframework/platform/internal/boxchoice 0.008s
ok github.com/carlosframework/platform/internal/boxid 0.829s
? 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.011s
ok github.com/carlosframework/platform/internal/caps 0.019s
ok github.com/carlosframework/platform/internal/certwarm 0.011s
ok github.com/carlosframework/platform/internal/cgroup 0.787s
ok github.com/carlosframework/platform/internal/changelog 0.574s
ok github.com/carlosframework/platform/internal/claimactivation 1.229s
ok github.com/carlosframework/platform/internal/clamd 0.062s
? 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 7.802s
ok github.com/carlosframework/platform/internal/dbdoor/dbdoortest 0.021s
ok github.com/carlosframework/platform/internal/dbquery 0.009s
ok github.com/carlosframework/platform/internal/dbreads 2.140s
? github.com/carlosframework/platform/internal/dbreads/dbreadstest [no test files]
ok github.com/carlosframework/platform/internal/dbverify 0.008s
ok github.com/carlosframework/platform/internal/dnsrec 0.009s
ok github.com/carlosframework/platform/internal/docsite 0.017s
ok github.com/carlosframework/platform/internal/domains 2.766s
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 45.495s
? github.com/carlosframework/platform/internal/edgeproof [no test files]
ok github.com/carlosframework/platform/internal/edgesfile 0.008s
ok github.com/carlosframework/platform/internal/fleetapi 0.135s
ok github.com/carlosframework/platform/internal/gate 1.654s
ok github.com/carlosframework/platform/internal/genselect 0.014s
ok github.com/carlosframework/platform/internal/geo 0.016s
ok github.com/carlosframework/platform/internal/geoip 0.031s
ok github.com/carlosframework/platform/internal/historyreadback 0.161s
ok github.com/carlosframework/platform/internal/host 145.030s
ok github.com/carlosframework/platform/internal/hostactors 6.102s
ok github.com/carlosframework/platform/internal/hostactors/awsmembership 0.022s
ok github.com/carlosframework/platform/internal/hostbox 3.158s
ok github.com/carlosframework/platform/internal/hostclaim 0.856s
ok github.com/carlosframework/platform/internal/hostenv 0.023s
ok github.com/carlosframework/platform/internal/hostevidence 0.021s
ok github.com/carlosframework/platform/internal/hostexec 5.372s
ok github.com/carlosframework/platform/internal/hostfence 0.036s
ok github.com/carlosframework/platform/internal/hostfiles 10.308s
ok github.com/carlosframework/platform/internal/hostfloor 0.023s
ok github.com/carlosframework/platform/internal/hostguard 1.068s
ok github.com/carlosframework/platform/internal/hostops 2.096s
? github.com/carlosframework/platform/internal/hostops/fencerelease [no test files]
ok github.com/carlosframework/platform/internal/hostops/internal/fencerelease 0.019s
ok github.com/carlosframework/platform/internal/hostquarantine 0.021s
ok github.com/carlosframework/platform/internal/hostrelocate 0.642s
ok github.com/carlosframework/platform/internal/hostresolve 0.251s
ok github.com/carlosframework/platform/internal/hostwrite 0.021s
ok github.com/carlosframework/platform/internal/infraview 0.021s
ok github.com/carlosframework/platform/internal/instancectl 5.268s
ok github.com/carlosframework/platform/internal/instanceexec 2.849s
ok github.com/carlosframework/platform/internal/instancefs 0.024s
ok github.com/carlosframework/platform/internal/instancekey 0.019s
ok github.com/carlosframework/platform/internal/instanceupdates 0.026s
ok github.com/carlosframework/platform/internal/layout 1.888s
ok github.com/carlosframework/platform/internal/lbhealth 0.023s
ok github.com/carlosframework/platform/internal/lease 10.419s
ok github.com/carlosframework/platform/internal/lease/leasetest 0.625s
ok github.com/carlosframework/platform/internal/ledger 0.043s
ok github.com/carlosframework/platform/internal/mail 0.243s
ok github.com/carlosframework/platform/internal/maintenance 0.096s
ok github.com/carlosframework/platform/internal/maintenanceexec 5.542s
ok github.com/carlosframework/platform/internal/maintenanceguard 0.116s
ok github.com/carlosframework/platform/internal/metrics 0.005s
ok github.com/carlosframework/platform/internal/moves 22.733s
ok github.com/carlosframework/platform/internal/moves/archive 1.029s
ok github.com/carlosframework/platform/internal/objstore 0.361s
ok github.com/carlosframework/platform/internal/ops 0.235s
ok github.com/carlosframework/platform/internal/park 0.283s
ok github.com/carlosframework/platform/internal/plans 0.007s
ok github.com/carlosframework/platform/internal/privatefile 0.008s
ok github.com/carlosframework/platform/internal/provision 24.241s
ok github.com/carlosframework/platform/internal/publicrelease 0.008s
? github.com/carlosframework/platform/internal/regionname [no test files]
ok github.com/carlosframework/platform/internal/registry 5.617s
ok github.com/carlosframework/platform/internal/relay 7.246s
ok github.com/carlosframework/platform/internal/release 26.567s
ok github.com/carlosframework/platform/internal/rollout 3.814s
ok github.com/carlosframework/platform/internal/rolloutwords 0.006s
ok github.com/carlosframework/platform/internal/rootaws 0.008s
ok github.com/carlosframework/platform/internal/rootparticipation 0.067s
ok github.com/carlosframework/platform/internal/rootstate 0.030s
ok github.com/carlosframework/platform/internal/runs 0.576s
ok github.com/carlosframework/platform/internal/s3compat 0.007s
ok github.com/carlosframework/platform/internal/safefile 0.005s
ok github.com/carlosframework/platform/internal/schedule 2.662s
ok github.com/carlosframework/platform/internal/seeds 0.012s
ok github.com/carlosframework/platform/internal/sim/engines 2.612s
ok github.com/carlosframework/platform/internal/sim/hostlife 11.799s
ok github.com/carlosframework/platform/internal/sim/litestreamfacts 4.214s
ok github.com/carlosframework/platform/internal/status 0.098s
ok github.com/carlosframework/platform/internal/steering 0.008s
ok github.com/carlosframework/platform/internal/stopevidence 0.341s
ok github.com/carlosframework/platform/internal/svcrole 0.002s
ok github.com/carlosframework/platform/internal/telemetry 0.004s
ok github.com/carlosframework/platform/internal/termfence 0.006s
ok github.com/carlosframework/platform/internal/tunnelclient 0.005s
ok github.com/carlosframework/platform/internal/unixdial 0.002s
ok github.com/carlosframework/platform/internal/updatewords 0.007s
ok github.com/carlosframework/platform/internal/usage 0.007s
ok github.com/carlosframework/platform/internal/version 0.006s
ok github.com/carlosframework/platform/internal/vet 1.688s
=== internal_console@0 (80 s)
ok github.com/carlosframework/platform/internal/console 77.882s
=== internal_console@1 (44 s)
ok github.com/carlosframework/platform/internal/console 42.352s
=== internal_console@2 (42 s)
ok github.com/carlosframework/platform/internal/console 39.770s
=== internal_console@3 (42 s)
ok github.com/carlosframework/platform/internal/console 40.457s
=== internal_console@4 (43 s)
ok github.com/carlosframework/platform/internal/console 40.887s
=== internal_console@5 (42 s)
ok github.com/carlosframework/platform/internal/console 40.360s
=== internal_console@6 (38 s)
ok github.com/carlosframework/platform/internal/console 35.825s
=== internal_console@7 (48 s)
ok github.com/carlosframework/platform/internal/console 46.108s
=== root@0 (110 s)
ok github.com/carlosframework/platform 107.993s
=== root@1 (83 s)
ok github.com/carlosframework/platform 81.518s
=== root@2 (93 s)
ok github.com/carlosframework/platform 90.788s
=== 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: 50659490 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.024s
=== RUN TestT4StorageProbeMinio
2026/10/24 21:49:13 moves: T4: STORE: list: operation error S3: ListObjectsV2, https response error StatusCode: 403, RequestID: 18E1958B9A306E00, 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
=== RUN TestS3StoreMinioContract
=== RUN TestS3StoreMinioContract/conditional_get_and_etag_listing
=== RUN TestS3StoreMinioContract/bump_through_every_mutation_path
--- PASS: TestS3StoreMinioContract (0.03s)
--- PASS: TestS3StoreMinioContract/conditional_get_and_etag_listing (0.01s)
--- PASS: TestS3StoreMinioContract/bump_through_every_mutation_path (0.02s)
PASS
ok github.com/carlosframework/platform/internal/release 0.031s
Bucket created successfully `local/dbf-deploy`.
Bucket created successfully `local/dbf-data-ie`.
Bucket created successfully `local/dbf-data-uk`.
local/dbf-deploy versioning is enabled
Created policy `dbf-console` successfully.
Created policy `dbf-ukbox` successfully.
Added user `dbfconsole` successfully.
Added user `dbfukbox` successfully.
Attached Policies: [dbf-console]
To User: dbfconsole
Attached Policies: [dbf-ukbox]
To User: dbfukbox
=== RUN TestDBForwardMinio
2026/10/24 21:49:15 INFO replica sync system=store db=source.db replica=file txid.replica=0000000000000000 txid.db=0000000000000001
2026/10/24 21:49:15 INFO ltx file uploaded system=store db=source.db replica=file level=0 minTXID=0000000000000001 maxTXID=0000000000000001 size=720
2026/10/24 21:49:15 INFO replica sync system=store db=source.db replica=file txid.replica=0000000000000001 txid.db=0000000000000001
2026/10/24 21:49:15 INFO replica sync system=store db=source.db replica=file txid.replica=0000000000000001 txid.db=0000000000000002
2026/10/24 21:49:15 INFO ltx file uploaded system=store db=source.db replica=file level=0 minTXID=0000000000000002 maxTXID=0000000000000002 size=370
2026/10/24 21:49:15 INFO replica sync system=store db=source.db replica=file txid.replica=0000000000000002 txid.db=0000000000000002
2026/10/24 21:49:15 INFO replica sync system=store db=source.db replica=file txid.replica=0000000000000002 txid.db=0000000000000003
2026/10/24 21:49:15 INFO ltx file uploaded system=store db=source.db replica=file level=0 minTXID=0000000000000003 maxTXID=0000000000000003 size=454
2026/10/24 21:49:15 INFO replica sync system=store db=source.db replica=file txid.replica=0000000000000003 txid.db=0000000000000003
2026/10/24 21:49:15 INFO replica sync system=store db=source.db replica=file txid.replica=0000000000000000 txid.db=0000000000000001
2026/10/24 21:49:15 INFO ltx file uploaded system=store db=source.db replica=file level=0 minTXID=0000000000000001 maxTXID=0000000000000001 size=720
2026/10/24 21:49:15 INFO replica sync system=store db=source.db replica=file txid.replica=0000000000000001 txid.db=0000000000000001
2026/10/24 21:49:15 console: CARLOS_SECRETS_PUBKEY is unset, so no region outside the home can be chosen automatically
2026/10/24 21:49:15 console: could not notify member@example.com of a CLI token issue: keymail: lookup member@example.com: keymail: GET /api/federation/lookup?addr=member%40example.com&from=console%40127.0.0.1%3A38855: could not determine target mailbox
agent.go:135: dbreads: dbr_vxsncouxjhxhx6q6c6ovnwnjvm: planned 3 files (1544 bytes) and restored to 3 in 10ms
agent.go:135: dbreads: dbr_vxsncouxjhxhx6q6c6ovnwnjvm: output 5 bytes in 1 confirmed chunks in 1ms
2026/10/24 21:49:16 console: db read dbr_vxsncouxjhxhx6q6c6ovnwnjvm: relayed 1 chunks (102 bytes) in 1.004s, ended done
agent.go:135: dbreads: dbr_vt6kml7kafqmyr5q2gnghsnnk4: planned 1 files (720 bytes) and restored to 1 in 8ms
agent.go:135: dbreads: dbr_vt6kml7kafqmyr5q2gnghsnnk4: output 5 bytes in 1 confirmed chunks in 1ms
2026/10/24 21:49:18 console: db read dbr_vt6kml7kafqmyr5q2gnghsnnk4: relayed 1 chunks (102 bytes) in 1.004s, ended done
agent.go:135: dbreads: dbr_5a7eklqq4bbisnmituc2lbvkue: planned 3 files (1544 bytes) and held through 3 in 9ms
agent.go:135: dbreads: dbr_5a7eklqq4bbisnmituc2lbvkue: output 1544 bytes in 1 confirmed chunks in 1ms
2026/10/24 21:49:19 console: db read dbr_5a7eklqq4bbisnmituc2lbvkue: relayed 1 chunks (1641 bytes) in 1.004s, ended done
=== RUN TestDBForwardMinio/by_disconnect
=== NAME TestDBForwardMinio
agent.go:135: dbreads: dbr_brti7levjkzx47pfqn6wlrxlzm: planned 3 files (1544 bytes) and restored to 3 in 9ms
2026/10/24 21:49:19 console: db read dbr_brti7levjkzx47pfqn6wlrxlzm: relayed 0 chunks (0 bytes) in 31ms, ended client gone
agent.go:135: dbreads: dbr_brti7levjkzx47pfqn6wlrxlzm: output 5 bytes in 1 confirmed chunks in 3ms
=== RUN TestDBForwardMinio/by_timeout
=== NAME TestDBForwardMinio
agent.go:135: dbreads: dbr_nvmhk5kkvlkmk475lgueo7eprm: planned 3 files (1544 bytes) and restored to 3 in 10ms
2026/10/24 21:49:39 console: db read dbr_nvmhk5kkvlkmk475lgueo7eprm: relayed 0 chunks (0 bytes) in 19.845s, ended no-result
agent.go:135: dbreads: dbr_nvmhk5kkvlkmk475lgueo7eprm: output 5 bytes in 1 confirmed chunks in 19.825s
--- PASS: TestDBForwardMinio (23.20s)
--- PASS: TestDBForwardMinio/by_disconnect (0.14s)
--- PASS: TestDBForwardMinio/by_timeout (19.95s)
PASS
ok github.com/carlosframework/platform/internal/console 23.218s
minio contract: PASS
diff --git a/docs/superpowers/plans/2026-10-24-edge-protection-1-request-records.md b/docs/superpowers/plans/2026-10-24-edge-protection-1-request-records.md| new file mode 100644 |
| index 000000000..55b0dfcab |
| --- /dev/null |
| +++ b/docs/superpowers/plans/2026-10-24-edge-protection-1-request-records.md |
| @@ -0,0 +1,813 @@ |
| +# Edge protection Plan 1: request records and reference codes |
| + |
| +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. |
| + |
| +**Goal:** The edge writes per-app request records (sampled not-found responses, per-minute counts including wakes, and the record API later plans use for blocks and watches), shipped through `carlos logs -stream edge`, plus self-describing reference codes the console can decode and verify. |
| + |
| +**Architecture:** A new pure package `internal/reqrec` owns redaction, classification, reference codes and an in-memory `Recorder` that samples and counts. The edge calls the recorder from its existing observer defer in `ServeHTTP`; the agent wires the recorder to the existing `applog.Sink` through a new `Sink.Edge` producer with its own rate budget, and flushes minute counts on a ticker. The console gains one API endpoint that decodes a code and finds its record. |
| + |
| +**Tech Stack:** Go standard library (`crypto/hmac`, `crypto/sha256`, `encoding/base32`, `net/netip`); existing `internal/applog`, `internal/edge`, `internal/activator`, `internal/host`, `internal/console`. |
| + |
| +**Spec:** `docs/superpowers/specs/2026-10-24-edge-request-protection-design.md` (§7, §8 step 1). Read it before Task 1. |
| + |
| +## Global Constraints |
| + |
| +- Provider-neutral: no AWS SDK or cloud service in any new code (spec §4 anti-goals). |
| +- Never store passwords, tokens, cookie values or full client addresses; no storage write per request (spec §4, §7). |
| +- Client key is `clientIP(r)` truncated to /32 IPv4, /64 IPv6, the same key as #358; never a client-set header. |
| +- Stored client address is truncated to /24 IPv4, /48 IPv6, plus a keyed hash of the client key (spec §7). |
| +- High-entropy runs (24 or more base64 or hex characters) are masked in every stored path, query value and fragment; fragments are truncated to 64 bytes (spec §7). |
| +- Retention is the logs family's existing 7 days (`logshipMaxAge`); see the spec amendment in Task 4. |
| +- Reference codes carry rule, tier, time and box, sealed with the mesh key under their own label (spec §7). |
| +- `CARLOS_EDGE_RECORDS=off` in the agent's environment disables the whole feature (operator kill switch). |
| +- Imports only flow host → edge, activator → edge; `internal/reqrec` imports nothing from edge, host or console. |
| +- `gofmt -l .` clean. Cross-builds must pass (CI builds darwin and windows); nothing here is Linux-only. |
| +- Locally run only the touched packages' tests with `-run`; CI runs the full suite. Leave `GOCACHE` at its default. |
| +- If CI fails `TestPlan14RootReadCensus`, follow AGENTS.md "The census: an approval, not a decision". |
| +- No new user-facing copy in this plan: API error strings are diagnostics. The CLI verb that explains a code arrives with Plan 2, through copy review. |
| + |
| +## Review Focus |
| + |
| +1. A real help-article slug (`/en/articles/how-do-i-access-the-admin-pane-2023`) must survive masking unchanged, while a 32-character hex token in the same position is masked. Test in Task 1. |
| +2. An IPv4-mapped IPv6 address (`::ffff:203.0.113.7`) must be keyed and truncated as IPv4, or one visitor gets two keys. Test in Task 1. |
| +3. A flood of 10,000 404s in a minute on one app must produce at most 60 not-found records plus one minute record that counts the rest as dropped, and must not crowd the app's own log lines out of the sink's rate budget. Tests in Tasks 3 and 4. |
| +4. A request that reached this box over the tunnel must not be recorded twice. Test in Task 5. |
| +5. A code pasted back in upper case, with dashes or surrounding spaces, must still decode. Test in Task 2. |
| + |
| +--- |
| + |
| +### Task 1: Redaction and classification |
| + |
| +**Files:** |
| +- Create: `internal/reqrec/redact.go`, `internal/reqrec/classify.go` |
| +- Test: `internal/reqrec/redact_test.go`, `internal/reqrec/classify_test.go` |
| + |
| +**Interfaces:** |
| +- Produces: |
| + - `const MaskToken = "[masked]"`, `const MaxPath = 512`, `const MaxQueryNames = 256`, `const MaxFragment = 64` |
| + - `func MaskPath(p string) string` |
| + - `func QueryNames(rawQuery string) string` |
| + - `type Source string` with `SourcePath`, `SourceQuery`, `SourceHeader`, `SourceBody`, `SourceCookie` |
| + - `func Fragment(src Source, name, value string) (string, bool)` |
| + - `func IsSecretName(name string) bool` |
| + - `func UAFamily(ua string) string` |
| + - `func ClientKey(ip string) string` |
| + - `func ClientPrefix(ip string) string` |
| + - `func ClientHash(salt []byte, key string) string` |
| + |
| +- [ ] **Step 1: Write the failing tests** |
| + |
| +```go |
| +func TestMaskPath(t *testing.T) { |
| + cases := map[string]string{ |
| + "/en/articles/how-do-i-access-the-admin-pane-2023": "/en/articles/how-do-i-access-the-admin-pane-2023", |
| + "/reset/3f9a0c1d2e4b5a6978877665544332211": "/reset/[masked]", |
| + "/assets/admin/application-0123456789abcdef0123456789abcdef.js": "/assets/admin/application-[masked].js", |
| + "/i/eyJhbGciOiJIUzI1NiJ9xQ2w9pLmNb7Ks4Ua/x.png": "/i/[masked]/x.png", |
| + "/wp-login.php": "/wp-login.php", |
| + "/short1234abcd": "/short1234abcd", |
| + } |
| + for in, want := range cases { |
| + if got := MaskPath(in); got != want { |
| + t.Errorf("MaskPath(%q) = %q, want %q", in, got, want) |
| + } |
| + } |
| + long := "/" + strings.Repeat("a/", 600) |
| + if got := MaskPath(long); len(got) > MaxPath || !utf8.ValidString(got) { |
| + t.Errorf("long path not truncated to a valid string of at most %d bytes", MaxPath) |
| + } |
| + if got := MaskPath("/\xff\xfe/x"); !utf8.ValidString(got) { |
| + t.Errorf("invalid UTF-8 survived: %q", got) |
| + } |
| +} |
| + |
| +func TestQueryNames(t *testing.T) { |
| + if got := QueryNames("q=reports'+UNION+ALL&page=2&q=x&token=abc"); got != "q,page,token" { |
| + t.Errorf("got %q", got) |
| + } |
| + if got := QueryNames(""); got != "" { |
| + t.Errorf("got %q", got) |
| + } |
| + many := strings.Repeat("abcdefgh=1&", 2000) |
| + if got := QueryNames(many); len(got) > MaxQueryNames { |
| + t.Errorf("not capped: %d bytes", len(got)) |
| + } |
| +} |
| + |
| +func TestFragment(t *testing.T) { |
| + if _, ok := Fragment(SourceCookie, "sid", "x"); ok { |
| + t.Error("cookie fragment kept") |
| + } |
| + if _, ok := Fragment(SourceHeader, "Authorization", "Bearer x"); ok { |
| + t.Error("authorization kept") |
| + } |
| + if _, ok := Fragment(SourceHeader, "X-Api-Key", "x"); ok { |
| + t.Error("header off the safe list kept") |
| + } |
| + if _, ok := Fragment(SourceQuery, "reset_token", "x"); ok { |
| + t.Error("secret-named parameter kept") |
| + } |
| + got, ok := Fragment(SourceQuery, "q", "reports' UNION ALL SELECT "+strings.Repeat("N", 100)) |
| + if !ok || len(got) > MaxFragment || !strings.HasPrefix(got, "reports' UNION ALL SELECT") { |
| + t.Errorf("query fragment = %q, %v", got, ok) |
| + } |
| + if got, ok := Fragment(SourceHeader, "User-Agent", "sqlmap/1.7"); !ok || got != "sqlmap/1.7" { |
| + t.Errorf("user-agent fragment = %q, %v", got, ok) |
| + } |
| +} |
| + |
| +func TestUAFamily(t *testing.T) { |
| + cases := map[string]string{ |
| + "": "empty", |
| + "Mozilla/5.0 zgrab/0.x": "scanner", |
| + "Expanse, a Palo Alto Networks company, searches across the global IPv4 space": "scanner", |
| + "curl/8.7.1": "tool", |
| + "python-requests/2.31": "tool", |
| + "Go-http-client/1.1": "tool", |
| + "Mozilla/5.0 (compatible; AhrefsBot/7.0; +http://ahrefs.com/robot/)": "crawler", |
| + "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/130.0 Safari/537.36": "browser", |
| + "SomethingElse/1.0": "other", |
| + } |
| + for ua, want := range cases { |
| + if got := UAFamily(ua); got != want { |
| + t.Errorf("UAFamily(%q) = %q, want %q", ua, got, want) |
| + } |
| + } |
| +} |
| + |
| +func TestClientKeyAndPrefix(t *testing.T) { |
| + cases := []struct{ ip, key, prefix string }{ |
| + {"203.0.113.7", "203.0.113.7/32", "203.0.113.0/24"}, |
| + {"::ffff:203.0.113.7", "203.0.113.7/32", "203.0.113.0/24"}, |
| + {"2001:db8:1234:5678:9abc::1", "2001:db8:1234:5678::/64", "2001:db8:1234::/48"}, |
| + {"not-an-ip", "", ""}, |
| + } |
| + for _, c := range cases { |
| + if got := ClientKey(c.ip); got != c.key { |
| + t.Errorf("ClientKey(%q) = %q, want %q", c.ip, got, c.key) |
| + } |
| + if got := ClientPrefix(c.ip); got != c.prefix { |
| + t.Errorf("ClientPrefix(%q) = %q, want %q", c.ip, got, c.prefix) |
| + } |
| + } |
| +} |
| + |
| +func TestClientHash(t *testing.T) { |
| + salt := bytes.Repeat([]byte{7}, 32) |
| + a, b := ClientHash(salt, "203.0.113.7/32"), ClientHash(salt, "203.0.113.8/32") |
| + if len(a) != 12 || a == b || a != ClientHash(salt, "203.0.113.7/32") { |
| + t.Errorf("hash not stable, distinct and 12 hex: %q %q", a, b) |
| + } |
| + if ClientHash(nil, "203.0.113.7/32") != "" || ClientHash(salt, "") != "" { |
| + t.Error("nil salt or empty key must give an empty hash") |
| + } |
| +} |
| +``` |
| + |
| +- [ ] **Step 2: Run the tests to verify they fail** |
| + |
| +Run: `go test ./internal/reqrec/ -run 'TestMaskPath|TestQueryNames|TestFragment|TestUAFamily|TestClientKeyAndPrefix|TestClientHash'` |
| +Expected: FAIL to compile (undefined: MaskPath …). |
| + |
| +- [ ] **Step 3: Implement `redact.go`** |
| + |
| +- A maskable run is a maximal run of `[A-Za-z0-9+=]` of length ≥ 24 that contains at least one letter and one digit, or a run of `[0-9a-fA-F]` of length ≥ 24. Runs are split at `-`, `_`, `.`, `/` and every other character, which is what keeps hyphenated slugs intact. |
| +- `MaskPath` replaces invalid UTF-8 with U+FFFD, masks runs, then truncates to `MaxPath` bytes on a rune boundary. |
| +- `QueryNames` takes names in first-seen order, de-duplicated, each passed through the run mask, and drops whole names that would cross `MaxQueryNames` bytes. Parse leniently: split on `&` and `;`, and `url.QueryUnescape` with the raw name kept on error. |
| +- `IsSecretName` is a case-insensitive substring match against `password`, `passwd`, `pwd`, `token`, `secret`, `key`, `session`, `auth`, `sig`, `signature`, `credential`, `otp`, `code`. |
| +- `Fragment` behaves like this: |
| + - Cookie fragments are always omitted. |
| + - Header fragments are kept only for `User-Agent`, `Referer`, `Content-Type`, `Accept`, `Accept-Language` and `Accept-Encoding` (case-insensitive). |
| + - Query and body fragments are omitted when `IsSecretName(name)`. |
| + - Path fragments are always kept. |
| + - A kept value is run-masked and truncated to `MaxFragment` bytes on a rune boundary. |
| + |
| +- [ ] **Step 4: Implement `classify.go`** |
| + |
| +- `UAFamily` checks in this order: empty, scanner, tool, crawler, browser, other. |
| + - Scanner markers: `zgrab`, `masscan`, `nuclei`, `sqlmap`, `nikto`, `nmap`, `censys`, `expanse`, `go web pentest`, `libredtail`, `httpx`, `wpscan`, `gobuster`, `dirbuster`, `ffuf`, `software security research`. |
| + - Tool markers: `curl/`, `wget/`, `python-requests`, `python-urllib`, `aiohttp`, `go-http-client`, `okhttp`, `java/`, `libwww`, `node-fetch`, `axios/`, `httpclient`, `scrapy`, `postmanruntime`, `insomnia`. |
| + - Crawler markers: `bot`, `crawler`, `spider`, `slurp`, `facebookexternalhit`, `ahrefs`, `semrush`, `bytespider`, `yandex`, `baiduspider`, `pingdom`, `uptimerobot`, `statuscake`, `lighthouse`, `pagespeed`. |
| + - Browser: contains `Mozilla/5.0` and one of `Chrome/`, `Safari/`, `Firefox/`, `Edg/`. |
| + - All matching is case-insensitive substring. |
| +- `ClientKey` and `ClientPrefix` use `netip.ParseAddr` and then `Unmap()`, returning `netip.Prefix` strings: the key is /32 or /64, the prefix /24 or /48. |
| +- `ClientHash` is the first 12 hex characters of HMAC-SHA256(salt, key). |
| + |
| +- [ ] **Step 5: Run the tests to verify they pass** |
| + |
| +Run: `go test ./internal/reqrec/ -run 'TestMaskPath|TestQueryNames|TestFragment|TestUAFamily|TestClientKeyAndPrefix|TestClientHash'` |
| +Expected: PASS |
| + |
| +- [ ] **Step 6: Commit** |
| + |
| +```bash |
| +git add internal/reqrec |
| +git commit -m "reqrec: redaction and classification for edge request records" |
| +``` |
| + |
| +### Task 2: Reference codes |
| + |
| +**Files:** |
| +- Create: `internal/reqrec/ref.go` |
| +- Test: `internal/reqrec/ref_test.go` |
| +- Modify: `docs/superpowers/specs/2026-10-24-edge-request-protection-design.md` (§7 reference-code bullet) |
| + |
| +**Interfaces:** |
| +- Produces: |
| + - `type Tier uint8` with `TierNone`, `TierHard`, `TierProbe`, `TierAttack`, `TierTenant`, `TierBurst`, `TierChallenge` (values 0 to 6, in that order), and `func (t Tier) String() string` returning `"none"`, `"hard"`, `"probe"`, `"attack"`, `"tenant"`, `"burst"`, `"challenge"` |
| + - `type Ref struct { At time.Time; Tier Tier; RuleHash uint32; BoxHash uint16; Sealed, Verified bool }` |
| + - `func RuleHash(ruleID string) uint32` |
| + - `func BoxHash(box string) uint16` |
| + - `func NewRef(at time.Time, tier Tier, ruleID, box string, key []byte) string` |
| + - `func ParseRef(code string, keys ...[]byte) (Ref, error)` |
| + - `var ErrBadRef = errors.New("reqrec: malformed reference code")`, `var ErrForgedRef = errors.New("reqrec: reference code seal does not verify")` |
| + |
| +**Layout (20 bytes, then Crockford base32, lower case, no padding: 32 characters):** |
| + |
| +| Bytes | Content | |
| +|---|---| |
| +| 0 | high nibble version `1`; low nibble flags, bit 0 = sealed | |
| +| 1-4 | Unix minutes, uint32 big-endian | |
| +| 5 | tier | |
| +| 6-9 | `RuleHash`: first 4 bytes of SHA-256(`"carlos-edge-rule\n"` + ruleID) | |
| +| 10-11 | `BoxHash`: first 2 bytes of SHA-256(`"carlos-edge-box\n"` + box) | |
| +| 12-14 | random nonce (`crypto/rand`) | |
| +| 15-19 | first 5 bytes of HMAC-SHA256(key, `"carlos-edge-ref\n"` + bytes 0-14); zero when unsealed | |
| + |
| +The alphabet is `0123456789abcdefghjkmnpqrstvwxyz`. `NewRef` with a nil or empty key writes an unsealed code. |
| + |
| +`ParseRef` lower-cases the input, strips spaces and `-`, and maps `o` to `0` and `i`/`l` to `1`. It then: |
| +- rejects a wrong length or version with `ErrBadRef`; |
| +- for a sealed code with at least one key given, verifies against each key in turn, setting `Verified` on a match and returning `ErrForgedRef` when none matches; |
| +- for a sealed code with no keys given, decodes with `Verified=false`. |
| + |
| +- [ ] **Step 1: Write the failing tests** |
| + |
| +```go |
| +func TestRefRoundTrip(t *testing.T) { |
| + key := bytes.Repeat([]byte{1}, 32) |
| + at := time.Date(2026, 10, 24, 21, 7, 31, 0, time.UTC) |
| + code := NewRef(at, TierProbe, "wp-login", "box-ie-1", key) |
| + if len(code) != 32 { |
| + t.Fatalf("len = %d", len(code)) |
| + } |
| + r, err := ParseRef(code, key) |
| + if err != nil || !r.Sealed || !r.Verified || r.Tier != TierProbe || |
| + r.RuleHash != RuleHash("wp-login") || r.BoxHash != BoxHash("box-ie-1") || |
| + !r.At.Equal(at.Truncate(time.Minute)) { |
| + t.Fatalf("got %+v, %v", r, err) |
| + } |
| + if a, b := NewRef(at, TierProbe, "wp-login", "box-ie-1", key), NewRef(at, TierProbe, "wp-login", "box-ie-1", key); a == b { |
| + t.Error("two codes for the same block must differ (nonce)") |
| + } |
| +} |
| + |
| +func TestRefPastedBack(t *testing.T) { |
| + key := bytes.Repeat([]byte{1}, 32) |
| + code := NewRef(time.Now(), TierHard, "dotenv", "b", key) |
| + messy := " " + strings.ToUpper(code[:8]+"-"+code[8:16]+"-"+code[16:]) + " " |
| + if _, err := ParseRef(messy, key); err != nil { |
| + t.Fatalf("pasted code rejected: %v", err) |
| + } |
| +} |
| + |
| +func TestRefSealing(t *testing.T) { |
| + key, other := bytes.Repeat([]byte{1}, 32), bytes.Repeat([]byte{2}, 32) |
| + code := NewRef(time.Now(), TierHard, "dotenv", "b", key) |
| + if _, err := ParseRef(code, other); !errors.Is(err, ErrForgedRef) { |
| + t.Errorf("wrong key: err = %v", err) |
| + } |
| + if r, err := ParseRef(code, other, key); err != nil || !r.Verified { |
| + t.Errorf("rotation (current, next): %+v %v", r, err) |
| + } |
| + if r, err := ParseRef(code); err != nil || !r.Sealed || r.Verified { |
| + t.Errorf("no keys: %+v %v", r, err) |
| + } |
| + unsealed := NewRef(time.Now(), TierHard, "dotenv", "b", nil) |
| + if r, err := ParseRef(unsealed, key); err != nil || r.Sealed || r.Verified { |
| + t.Errorf("unsealed: %+v %v", r, err) |
| + } |
| + if _, err := ParseRef("not-a-code"); !errors.Is(err, ErrBadRef) { |
| + t.Errorf("garbage: %v", err) |
| + } |
| +} |
| +``` |
| + |
| +- [ ] **Step 2: Run the tests to verify they fail** |
| + |
| +Run: `go test ./internal/reqrec/ -run 'TestRef'` |
| +Expected: FAIL to compile. |
| + |
| +- [ ] **Step 3: Implement `ref.go`** to the layout above. Use `hmac.Equal` for the comparison. |
| + |
| +- [ ] **Step 4: Run the tests to verify they pass** |
| + |
| +Run: `go test ./internal/reqrec/ -run 'TestRef'` |
| +Expected: PASS |
| + |
| +- [ ] **Step 5: Amend the spec.** In §7's "A block stays explainable" bullet, add: "Codes are sealed with the deployment's mesh key (`control/edge-mesh-key`, `edgeproof.LoadKeys`) under the label `carlos-edge-ref`. A box without the key (no deployment store, or a fleet box the store door refuses it to) writes unsealed codes, which the console decodes and marks unverified. The box is carried as a 2-byte hash." |
| + |
| +- [ ] **Step 6: Commit** |
| + |
| +```bash |
| +git add internal/reqrec docs/superpowers/specs/2026-10-24-edge-request-protection-design.md |
| +git commit -m "reqrec: self-describing, sealed reference codes" |
| +``` |
| + |
| +### Task 3: The Recorder (sampling and minute counts) |
| + |
| +**Files:** |
| +- Create: `internal/reqrec/recorder.go` |
| +- Test: `internal/reqrec/recorder_test.go` |
| + |
| +**Interfaces:** |
| +- Consumes: Task 1 helpers, and `Tier` from Task 2. |
| +- Produces: |
| + - `type Sink interface { Edge(acct, app, host, level, msg string, fields map[string]string) }` |
| + - `type Kind string` with `KindNotFound = "notfound"`, `KindBlock = "block"`, `KindWatch = "watch"`, `KindMinute = "minute"` |
| + - `type Response struct { Acct, App, Host, Method, Path, RawQuery, UA, ClientIP, Country string; Status int; Woke, WokeKnown bool; When time.Time }` |
| + - `type Match struct { Response; Kind Kind; Tier Tier; RuleID, Fragment, Ref string }`. `Fragment` arrives already passed through `reqrec.Fragment` by the caller. |
| + - `const NotFoundPerMin = 60`, `const MatchPerMin = 300` (per app per minute) |
| + - `type Recorder struct` (unexported fields) |
| + - `func NewRecorder(sink Sink, salt func(day string) []byte, now func() time.Time) *Recorder`. `day` is `YYYY-MM-DD` UTC. The recorder caches the salt per day and calls `salt` at most once per day. |
| + - `func (r *Recorder) Response(x Response)` |
| + - `func (r *Recorder) Match(m Match)` |
| + - `func (r *Recorder) Flush(now time.Time)` |
| + |
| +**Record shapes** (all values decimal or plain strings): |
| + |
| +- **Not-found and match records:** |
| + - Fields: `kind`, `method`, `path` (`MaskPath`), `qnames` (`QueryNames`), `ua` (`UAFamily`), `country`, `client` (`ClientPrefix`), `cid` (`ClientHash` of `ClientKey`), `status`. |
| + - `woke` is `"1"` or `"0"`, and omitted when `!WokeKnown`. |
| + - Match records add `ref`, `tier` (`Tier.String()`), `rule` and `frag` (omitted when empty). |
| + - Level is `warn` for block and `info` otherwise. |
| + - Msg is `"404 GET <path>"` for not-found, and `"<kind> <tier> <rule> <METHOD> <path>"` for a match. |
| +- **Minute records** (one per app per completed UTC minute with any count, level `info`, msg `"minute <RFC3339 minute>"`): |
| + - Fields: `kind=minute`, `minute` (RFC3339), `s2xx`, `s3xx`, `s4xx`, `s404`, `s5xx`, `wakes`, `wakes404`, `block`, `watch`, `dropped_notfound`, `dropped_match`. |
| + - `s4xx` excludes 404s. `wakes404` counts responses that were both a 404 and caused a wake. |
| + |
| +- [ ] **Step 1: Write the failing tests** |
| + |
| +```go |
| +type memSink struct{ recs []map[string]string; msgs, levels []string } |
| +func (m *memSink) Edge(acct, app, host, level, msg string, f map[string]string) { |
| + m.recs, m.msgs, m.levels = append(m.recs, f), append(m.msgs, msg), append(m.levels, level) |
| +} |
| + |
| +func TestRecorderNotFoundSampledAndCounted(t *testing.T) { |
| + now := time.Date(2026, 10, 24, 21, 7, 0, 0, time.UTC) |
| + s := &memSink{} |
| + r := NewRecorder(s, func(string) []byte { return bytes.Repeat([]byte{7}, 32) }, func() time.Time { return now }) |
| + for i := 0; i < 10000; i++ { |
| + r.Response(Response{Acct: "a1", App: "shop", Host: "shop.example.com", Method: "GET", |
| + Path: "/wp-login.php", UA: "curl/8.7.1", ClientIP: "203.0.113.7", Status: 404, Woke: i == 0, WokeKnown: true, When: now}) |
| + } |
| + r.Response(Response{Acct: "a1", App: "shop", Method: "GET", Path: "/", Status: 200, WokeKnown: true, When: now}) |
| + r.Flush(now.Add(time.Minute)) |
| + var notfound, minute int |
| + for _, f := range s.recs { |
| + switch f["kind"] { |
| + case "notfound": |
| + notfound++ |
| + if f["client"] != "203.0.113.0/24" || f["ua"] != "tool" || f["status"] != "404" || len(f["cid"]) != 12 { |
| + t.Fatalf("bad notfound fields %v", f) |
| + } |
| + case "minute": |
| + minute++ |
| + if f["s404"] != "10000" || f["s2xx"] != "1" || f["wakes"] != "1" || f["wakes404"] != "1" || f["dropped_notfound"] != "9940" { |
| + t.Fatalf("bad minute %v", f) |
| + } |
| + } |
| + } |
| + if notfound != NotFoundPerMin || minute != 1 { |
| + t.Fatalf("notfound=%d minute=%d", notfound, minute) |
| + } |
| +} |
| + |
| +func TestRecorderMatchRecordsAndCap(t *testing.T) { |
| + now := time.Date(2026, 10, 24, 21, 7, 0, 0, time.UTC) |
| + s := &memSink{} |
| + r := NewRecorder(s, nil, func() time.Time { return now }) |
| + m := Match{Response: Response{Acct: "a1", App: "shop", Method: "GET", Path: "/.env", Status: 404, When: now}, |
| + Kind: KindBlock, Tier: TierHard, RuleID: "dotenv", Ref: "ref1"} |
| + for i := 0; i < MatchPerMin+5; i++ { |
| + r.Match(m) |
| + } |
| + r.Flush(now.Add(time.Minute)) |
| + first := s.recs[0] |
| + if first["kind"] != "block" || first["tier"] != "hard" || first["rule"] != "dotenv" || first["ref"] != "ref1" || s.levels[0] != "warn" { |
| + t.Fatalf("bad match record %v level %s", first, s.levels[0]) |
| + } |
| + if _, ok := first["woke"]; ok { |
| + t.Error("woke written while unknown") |
| + } |
| + if first["cid"] != "" { |
| + t.Error("cid written without a salt") |
| + } |
| + last := s.recs[len(s.recs)-1] |
| + if last["kind"] != "minute" || last["block"] != fmt.Sprint(MatchPerMin+5) || last["dropped_match"] != "5" { |
| + t.Fatalf("bad minute %v", last) |
| + } |
| +} |
| + |
| +func TestRecorderFlushOnlyCompletedMinutes(t *testing.T) { |
| + now := time.Date(2026, 10, 24, 21, 7, 30, 0, time.UTC) |
| + s := &memSink{} |
| + r := NewRecorder(s, nil, func() time.Time { return now }) |
| + r.Response(Response{Acct: "a1", App: "shop", Status: 200, When: now}) |
| + r.Flush(now) // minute 21:07 not complete |
| + if len(s.recs) != 0 { |
| + t.Fatal("flushed an open minute") |
| + } |
| + r.Flush(now.Add(31 * time.Second)) |
| + if len(s.recs) != 1 || s.recs[0]["minute"] != "2026-10-24T21:07:00Z" { |
| + t.Fatalf("got %v", s.recs) |
| + } |
| +} |
| +``` |
| + |
| +- [ ] **Step 2: Run the tests to verify they fail** |
| + |
| +Run: `go test ./internal/reqrec/ -run 'TestRecorder'` |
| +Expected: FAIL to compile. |
| + |
| +- [ ] **Step 3: Implement `recorder.go`** |
| + |
| +- One mutex. Counters are keyed by `(acct, app, minute)`, where the minute is `x.When.UTC().Truncate(time.Minute)`. |
| +- Sampling caps are per `(acct, app, minute)`: not-found records stop at `NotFoundPerMin` and match records at `MatchPerMin`. Beyond the cap, increment the matching `dropped_*` counter. |
| +- Record emission calls `sink.Edge` outside the mutex. Collect under the lock, then emit. |
| +- `Flush` emits and forgets every minute strictly before `now.UTC().Truncate(time.Minute)`, in time order. |
| +- A nil `Recorder` must be safe to call: every method returns at once. |
| + |
| +- [ ] **Step 4: Run the tests to verify they pass** |
| + |
| +Run: `go test ./internal/reqrec/ -run 'TestRecorder'` |
| +Expected: PASS |
| + |
| +- [ ] **Step 5: Commit** |
| + |
| +```bash |
| +git add internal/reqrec |
| +git commit -m "reqrec: Recorder samples not-found and match records, counts per minute" |
| +``` |
| + |
| +### Task 4: `applog.Sink.Edge` with its own budget |
| + |
| +**Files:** |
| +- Modify: `internal/applog/sink.go`: the `Sink` struct, `appBuf`, `append`, `Drain` and `recCost` callers |
| +- Test: `internal/applog/sink_edge_test.go` |
| +- Modify: `docs/superpowers/specs/2026-10-24-edge-request-protection-design.md` (§7 "Shipping" bullet) |
| + |
| +**Interfaces:** |
| +- Produces: |
| + - `func (s *Sink) Edge(acct, app, host, level, msg string, fields map[string]string)`. This satisfies `reqrec.Sink`. |
| + - New exported fields `EdgeRatePerMin float64` (default 256 KiB) and `EdgeBurst float64` (default 1 MiB), set in `NewSink`. |
| + |
| +**Behaviour:** |
| +- Records go to `StreamEdge`. |
| +- Cost is `recCost(msg)` plus the sum of `len(k)+len(v)` over fields. The ring accounting in `append` and the eviction loop must use the same cost for each record, so compute cost from the record (`func costOf(r Record) int`, counting fields only when `r.Stream == StreamEdge`, so app and platform budgets don't change). |
| +- The rate bucket is separate from `App`'s: per app, `edgeTokens` and `edgeLastRef`. Rejections count into `edgeDropped`. |
| +- `Drain` appends one synthetic record per app with `edgeDropped > 0`: `Stream: StreamEdge`, `Level: LevelWarn`, `Msg: "dropped %d edge record(s) (rate cap)"`, `Fields: {"kind":"dropped","n":"<n>"}`. `IsDropNotice` stays false for it, so Availability is unaffected. |
| +- `Edge` does not poke `notify`: records ride the 10-second ship tick. |
| + |
| +- [ ] **Step 1: Write the failing tests** |
| + |
| +```go |
| +func TestSinkEdgeOwnBudget(t *testing.T) { |
| + now := time.Date(2026, 10, 24, 21, 0, 0, 0, time.UTC) |
| + s := NewSink("box1", func() time.Time { return now }) |
| + s.EdgeBurst, s.EdgeRatePerMin = 4096, 0 |
| + f := map[string]string{"kind": "notfound", "path": strings.Repeat("p", 900)} |
| + for i := 0; i < 100; i++ { |
| + s.Edge("a1", "shop", "shop.example.com", LevelInfo, "404 GET /x", f) |
| + } |
| + s.App("a1", "shop", "shop.example.com", "app line still lands") |
| + recs := s.Drain()[AppKey{"a1", "shop"}] |
| + var edge, app, notice int |
| + for _, r := range recs { |
| + switch { |
| + case r.Stream == StreamEdge && r.Fields["kind"] == "dropped": |
| + notice++ |
| + if r.Fields["n"] == "" || r.Level != LevelWarn { |
| + t.Fatalf("bad notice %+v", r) |
| + } |
| + case r.Stream == StreamEdge: |
| + edge++ |
| + case r.Stream == StreamApp: |
| + app++ |
| + } |
| + } |
| + if edge == 0 || edge >= 100 || app != 1 || notice != 1 { |
| + t.Fatalf("edge=%d app=%d notice=%d", edge, app, notice) |
| + } |
| +} |
| + |
| +func TestSinkEdgeFieldsCountAgainstRing(t *testing.T) { |
| + s := NewSink("box1", time.Now) |
| + s.MaxBytesPerApp, s.EdgeBurst, s.EdgeRatePerMin = 2000, 1<<20, 1<<20 |
| + big := map[string]string{"path": strings.Repeat("p", 900)} |
| + for i := 0; i < 10; i++ { |
| + s.Edge("a1", "shop", "h", LevelInfo, "m", big) |
| + } |
| + if n := len(s.Drain()[AppKey{"a1", "shop"}]); n > 3 { |
| + t.Fatalf("ring held %d records of ~1KB in 2000 bytes", n) |
| + } |
| +} |
| +``` |
| + |
| +- [ ] **Step 2: Run the tests to verify they fail** |
| + |
| +Run: `go test ./internal/applog/ -run 'TestSinkEdge'` |
| +Expected: FAIL to compile (`s.Edge` undefined). |
| + |
| +- [ ] **Step 3: Implement `Sink.Edge`, `costOf` and the `Drain` notice as described above.** |
| + |
| +- [ ] **Step 4: Run the applog tests** |
| + |
| +Run: `go test ./internal/applog/` |
| +Expected: PASS (existing tests unchanged). |
| + |
| +- [ ] **Step 5: Amend the spec.** In §7's "Shipping" bullet, replace "*My call:* 14 days' retention." with "Retention is the logs family's 7 days (`logshipMaxAge`, `internal/host/logship.go`), changed at plan time from 14 because retention is per family and the calibration report can read two 7-day windows. Edge records have their own rate budget in the sink so they never crowd out the app's own lines." |
| + |
| +- [ ] **Step 6: Commit** |
| + |
| +```bash |
| +git add internal/applog docs/superpowers/specs/2026-10-24-edge-request-protection-design.md |
| +git commit -m "applog: Sink.Edge producer for edge request records, own rate budget" |
| +``` |
| + |
| +### Task 5: Edge wiring and wake attribution |
| + |
| +**Files:** |
| +- Create: `internal/edge/reqrecords.go` |
| +- Modify: `internal/edge/answered.go` (add `woke bool` to `outcome`; add `MarkWoke`) |
| +- Modify: `internal/edge/edge.go`: the `Edge` struct (an `atomic.Pointer` field like `analyticsMeter`), and the observer defer at about line 1678 |
| +- Modify: `internal/activator/activator.go`, `Service.begin` at about line 1512 (call `edge.MarkWoke` for the request that starts the wake) |
| +- Test: `internal/edge/reqrecords_test.go`, `internal/activator/activator_test.go` (one new test) |
| + |
| +**Interfaces:** |
| +- Consumes: `reqrec.Response`, `reqrec.Match`, `reqrec.NewRef`, `reqrec.Fragment`, `reqrec.Kind`, `reqrec.Tier`. |
| +- Produces: |
| + - `type RequestRecorder interface { Response(reqrec.Response); Match(reqrec.Match) }` |
| + - `func (e *Edge) EnableRequestRecords(rec RequestRecorder)`. Nil turns it off. Store it behind a pointer wrapper as `EnableAnalytics` does, so a typed nil is never stored. |
| + - `func MarkWoke(r *http.Request)`. It is a no-op when `r` carries no outcome. |
| + - `func (e *Edge) observeRecords(rt registry.Route, viaTunnel bool, r *http.Request, ob *countingWriter, out *outcome)` |
| + - `func (e *Edge) recordMatch(rt registry.Route, r *http.Request, kind reqrec.Kind, tier reqrec.Tier, ruleID, frag string, status int) string`. It returns the reference code. Plan 2 calls it from its block and watch paths. |
| + |
| +**Behaviour:** |
| +- `observeRecords` runs in the existing observer defer, after `observeAnalytics`, for every route kind the defer covers. |
| +- It skips `fromTunnel(r.Context())`, the same once-only rule as `observeAnalytics`. The sending edge of a mesh hop never reaches the defer because it has no route row. |
| +- `WokeKnown` is `!viaTunnel`. |
| +- `Country` comes from `geoAnswerFrom(r.Context())`, and `ClientIP` from `clientIP(r)`. |
| +- `recordMatch` takes its key from `e.homes.Load()`'s `meshKeys()` (current key; nil-safe when `homes` is nil), builds the code with `reqrec.NewRef(time.Now(), tier, ruleID, e.box, key)`, calls `Match`, and returns the code even when recording is off. |
| + |
| +- [ ] **Step 1: Write the failing edge tests** |
| + |
| +```go |
| +type memRecorder struct{ resp []reqrec.Response; match []reqrec.Match } |
| +func (m *memRecorder) Response(x reqrec.Response) { m.resp = append(m.resp, x) } |
| +func (m *memRecorder) Match(x reqrec.Match) { m.match = append(m.match, x) } |
| + |
| +func TestRecordsSeeAppNotFound(t *testing.T) { |
| + e := edgeWithBackend(t, http.NotFoundHandler()) |
| + rec := &memRecorder{} |
| + e.EnableRequestRecords(rec) |
| + req := httptest.NewRequest("GET", "http://shop.example.com/wp-login.php?x=1", nil) |
| + e.ServeHTTP(httptest.NewRecorder(), req) |
| + if len(rec.resp) != 1 || rec.resp[0].Status != 404 || rec.resp[0].Path != "/wp-login.php" || rec.resp[0].RawQuery != "x=1" || !rec.resp[0].WokeKnown { |
| + t.Fatalf("got %+v", rec.resp) |
| + } |
| +} |
| + |
| +func TestRecordsSkipTunnelDelivered(t *testing.T) { |
| + e := edgeWithBackend(t, http.NotFoundHandler()) |
| + rec := &memRecorder{} |
| + e.EnableRequestRecords(rec) |
| + h := tunnelclient.Mark(e) |
| + h.ServeHTTP(httptest.NewRecorder(), httptest.NewRequest("GET", "http://shop.example.com/x", nil)) |
| + if len(rec.resp) != 0 { |
| + t.Fatalf("tunnel-delivered request recorded %d times", len(rec.resp)) |
| + } |
| +} |
| + |
| +func TestRecordMatchReturnsSealedCode(t *testing.T) { |
| + e, _, key := proofEdge(t, true) |
| + rec := &memRecorder{} |
| + e.EnableRequestRecords(rec) |
| + rt := registry.Route{Host: "shop.example.com", App: "shop"} |
| + code := e.recordMatch(rt, httptest.NewRequest("GET", "http://shop.example.com/.env", nil), reqrec.KindBlock, reqrec.TierHard, "dotenv", "", 404) |
| + r, err := reqrec.ParseRef(code, key) |
| + if err != nil || !r.Verified || len(rec.match) != 1 || rec.match[0].Ref != code { |
| + t.Fatalf("code %q: %+v %v; matches %d", code, r, err, len(rec.match)) |
| + } |
| +} |
| + |
| +func TestEnableRequestRecordsNil(t *testing.T) { |
| + e := edgeWithBackend(t, http.NotFoundHandler()) |
| + var typed *memRecorder |
| + e.EnableRequestRecords(typed) // typed nil must not panic on the serving path |
| + e.EnableRequestRecords(nil) |
| + e.ServeHTTP(httptest.NewRecorder(), httptest.NewRequest("GET", "http://shop.example.com/x", nil)) |
| +} |
| +``` |
| + |
| +Check `edgeWithBackend`'s route host and `proofEdge`'s key return value (`compress_test.go:372`, `forwardproof_test.go:30`). Adjust the host string, or use `proofEdge`'s route, if they differ. Keep the assertions. |
| + |
| +In `TestEnableRequestRecordsNil`, declare `var typed *reqrec.Recorder` (not `*memRecorder`). `*reqrec.Recorder` methods are nil-safe (Task 3), so a typed nil stored by mistake is harmless; `EnableRequestRecords(nil)` turns recording off. |
| + |
| +- [ ] **Step 2: Write the failing activator test** in `internal/activator/activator_test.go`, next to the existing first-wake tests. Two concurrent requests to an asleep instance through `edge.WithAnswerFlag`-style outcomes: the first request's outcome reports woke and the second's does not. Expose the read side for tests as `func Woke(r *http.Request) bool` in `answered.go`, alongside `MarkWoke`. |
| + |
| +- [ ] **Step 3: Run the tests to verify they fail** |
| + |
| +Run: `go test ./internal/edge/ -run 'TestRecords|TestRecordMatch|TestEnableRequestRecords' && go test ./internal/activator/ -run 'Woke'` |
| +Expected: FAIL to compile. |
| + |
| +- [ ] **Step 4: Implement.** `reqrecords.go` holds the recorder field accessors, `observeRecords` and `recordMatch`. Add `MarkWoke` and `Woke` to `answered.go`. Call `edge.MarkWoke(r)` in `Service.begin` on the branch that starts `go a.wake(e)`. If `begin` doesn't receive the request, thread `r` through from `ServeHTTP`; no other behaviour changes. Set `Woke: out.woke` in `observeRecords`. |
| + |
| +- [ ] **Step 5: Run the tests to verify they pass** |
| + |
| +Run: `go test ./internal/edge/ -run 'TestRecords|TestRecordMatch|TestEnableRequestRecords|TestAnalytics' && go test ./internal/activator/ -run 'Woke|Wake'` |
| +Expected: PASS |
| + |
| +- [ ] **Step 6: Commit** |
| + |
| +```bash |
| +git add internal/edge internal/activator |
| +git commit -m "edge: request records from the observer defer; activator marks the waking request" |
| +``` |
| + |
| +### Task 6: Agent wiring and the minute flush |
| + |
| +**Files:** |
| +- Create: `internal/host/reqrec_loop.go` |
| +- Modify: `internal/host/agent.go`, in the ready hook at about lines 941-956, next to `EnableAnalytics` |
| +- Test: `internal/host/reqrec_loop_test.go` |
| + |
| +**Interfaces:** |
| +- Consumes: `reqrec.NewRecorder`, `(*applog.Sink).Edge`, `(*edge.Edge).EnableRequestRecords`, `analytics.DaySalt(dir, date string) ([]byte, error)`. |
| +- Produces: |
| + - `func newRequestRecorder(sink *applog.Sink, saltDir string, getenv func(string) string) *reqrec.Recorder`. It returns nil when `sink == nil` or `getenv("CARLOS_EDGE_RECORDS") == "off"`. |
| + - `func reqrecLoop(rec *reqrec.Recorder, tick <-chan time.Time)`. It calls `rec.Flush(t)` for each tick and returns when `tick` closes. Production passes `time.NewTicker(time.Minute).C`. |
| + |
| +**Behaviour:** |
| +- The salt function wraps `analytics.DaySalt(saltDir, day)` and returns nil on error. `saltDir` is the same `dataDir()` that `analytics.NewMeter` gets at `agent.go:954`, so the visitor salt and the record salt are the same per-day file, never shipped. |
| +- In the ready hook: `if rec := newRequestRecorder(logSink, dataDir(), os.Getenv); rec != nil { e.EnableRequestRecords(rec); go reqrecLoop(rec, time.NewTicker(time.Minute).C) }`. |
| + |
| +- [ ] **Step 1: Write the failing tests** |
| + |
| +```go |
| +func TestNewRequestRecorderGates(t *testing.T) { |
| + sink := applog.NewSink("box1", time.Now) |
| + on := func(string) string { return "" } |
| + off := func(k string) string { if k == "CARLOS_EDGE_RECORDS" { return "off" }; return "" } |
| + if newRequestRecorder(nil, t.TempDir(), on) != nil { |
| + t.Error("nil sink must give nil recorder") |
| + } |
| + if newRequestRecorder(sink, t.TempDir(), off) != nil { |
| + t.Error("kill switch ignored") |
| + } |
| + if newRequestRecorder(sink, t.TempDir(), on) == nil { |
| + t.Error("recorder missing") |
| + } |
| +} |
| + |
| +func TestReqrecLoopFlushesToSink(t *testing.T) { |
| + sink := applog.NewSink("box1", time.Now) |
| + rec := newRequestRecorder(sink, t.TempDir(), func(string) string { return "" }) |
| + at := time.Now().UTC().Add(-2 * time.Minute) |
| + rec.Response(reqrec.Response{Acct: "a1", App: "shop", Status: 404, Method: "GET", Path: "/x", ClientIP: "203.0.113.7", When: at}) |
| + tick := make(chan time.Time, 1) |
| + tick <- time.Now() |
| + close(tick) |
| + reqrecLoop(rec, tick) |
| + recs := sink.Drain()[applog.AppKey{Acct: "a1", App: "shop"}] |
| + var kinds []string |
| + for _, r := range recs { |
| + kinds = append(kinds, r.Fields["kind"]) |
| + if r.Stream != applog.StreamEdge { |
| + t.Fatalf("stream %q", r.Stream) |
| + } |
| + } |
| + if !slices.Contains(kinds, "notfound") || !slices.Contains(kinds, "minute") { |
| + t.Fatalf("kinds %v", kinds) |
| + } |
| + for _, r := range recs { |
| + if r.Fields["kind"] == "notfound" && len(r.Fields["cid"]) != 12 { |
| + t.Fatalf("salt not wired: %v", r.Fields) |
| + } |
| + } |
| +} |
| +``` |
| + |
| +- [ ] **Step 2: Run the tests to verify they fail** |
| + |
| +Run: `go test ./internal/host/ -run 'TestNewRequestRecorderGates|TestReqrecLoopFlushesToSink'` |
| +Expected: FAIL to compile. |
| + |
| +- [ ] **Step 3: Implement `reqrec_loop.go` and the ready-hook lines.** |
| + |
| +- [ ] **Step 4: Run the tests to verify they pass, and cross-build** |
| + |
| +Run: `go test ./internal/host/ -run 'TestNewRequestRecorderGates|TestReqrecLoopFlushesToSink' && GOOS=darwin go build ./... && GOOS=windows go build ./...` |
| +Expected: PASS, and both builds succeed. |
| + |
| +- [ ] **Step 5: Commit** |
| + |
| +```bash |
| +git add internal/host |
| +git commit -m "host: wire edge request records to the log sink, flush minute counts" |
| +``` |
| + |
| +### Task 7: Console endpoint that explains a reference code |
| + |
| +**Files:** |
| +- Create: `internal/console/apiedgeref.go` |
| +- Modify: `internal/console/authcli.go`, next to the logs route at line 675 |
| +- Test: `internal/console/apiedgeref_test.go` |
| + |
| +**Interfaces:** |
| +- Consumes: `reqrec.ParseRef`, `s.edgeProofKeys(ctx) (current, next []byte)`, `applog.ReadWindow`, `applog.Filter`, `s.instanceGate`. |
| +- Produces: |
| + - Route `GET /api/cli/apps/{account}/{app}/edge-refs/{code}`, registered with `s.cliRoute(..., svcrole.Allow(svcrole.Instance, svcrole.Operate), s.handleAPIEdgeRef)`. That is the same gate as logs, so only the app's members and its own tokens can read. |
| + - `func (s *Server) handleAPIEdgeRef(w http.ResponseWriter, r *http.Request)` |
| + - JSON response type `apiEdgeRef struct { Code string `json:"code"`; Verified bool `json:"verified"`; At time.Time `json:"at"`; Tier string `json:"tier"`; RuleHash string `json:"rule_hash"`; Record *applog.Record `json:"record"` }`. `RuleHash` is 8 lower-case hex characters. `Record` is nil when no record is found. |
| + |
| +**Behaviour:** |
| +- Parse with both mesh keys, passing only the non-nil ones. |
| +- `ErrBadRef` and `ErrForgedRef` both answer 404 with the same body as every other instance-gate miss. A forged code reveals nothing. |
| +- Look the record up with `applog.ReadWindow(ctx, s.cfg.Releases, acct.Sqid, app, applog.Filter{Since: at.Add(-time.Minute), Until: at.Add(2*time.Minute), Stream: applog.StreamEdge, Fields: map[string]string{"ref": <canonical code>}}, 1000)`. The canonical code is the lower-case, dash-free form. |
| + |
| +- [ ] **Step 1: Write the failing tests.** Model the setup on the existing `handleAPILogs` tests; find them with `grep -n handleAPILogs internal/console/*_test.go`, and seed a chunk into the test store with `applog.EncodeChunk` at the `applog.ChunkKey` the shipper writes. Cases: |
| + - `TestEdgeRefFound`: a sealed code with a seeded record. Expect 200, `verified:true`, `tier:"probe"`, and `record.Fields["ref"] == code`. |
| + - `TestEdgeRefRecordGone`: a sealed code with no record. Expect 200, `record:null`, the tier present, and `at` truncated to the minute. |
| + - `TestEdgeRefForged`: a code sealed with another key. Expect 404. |
| + - `TestEdgeRefOtherAccount`: a principal from another account. Expect 404. |
| + - `TestEdgeRefPastedUpper`: an upper-case code with dashes. Expect 200. |
| + |
| +- [ ] **Step 2: Run the tests to verify they fail** |
| + |
| +Run: `go test ./internal/console/ -run 'TestEdgeRef'` |
| +Expected: FAIL (route not registered, so 404 or a compile error). |
| + |
| +- [ ] **Step 3: Implement the handler and the route.** |
| + |
| +- [ ] **Step 4: Run the tests to verify they pass** |
| + |
| +Run: `go test ./internal/console/ -run 'TestEdgeRef|TestAPILogs'` |
| +Expected: PASS |
| + |
| +- [ ] **Step 5: Commit** |
| + |
| +```bash |
| +git add internal/console |
| +git commit -m "console: explain an edge reference code from its seal and its record" |
| +``` |
| + |
| +### Task 8: End-to-end check through the real wiring |
| + |
| +**Files:** |
| +- Test: `internal/host/reqrec_e2e_test.go` |
| + |
| +**Interfaces:** |
| +- Consumes: everything above. This test goes through the production wiring, not fixtures: [[production-wired-witnesses]] in the team's memory records 11+ defects that fixtures hid. |
| + |
| +- [ ] **Step 1: Write the test.** |
| + 1. Build a real `applog.Sink` and `newRequestRecorder` against it. |
| + 2. Build an edge with `edgeWithBackend`-style routing in this package, or reuse the agent's own edge constructor if a test helper exists (`grep -n 'func .*testAgentEdge\|RunWithActivatorReady' internal/host/*_test.go`), and call `EnableRequestRecords`. |
| + 3. Serve one request for `/reset/3f9a0c1d2e4b5a6978877665544332211` first, so it is inside the sample, then 70 for `/wp-login.php` (a backend that 404s both). Flush with a tick a minute later. |
| + 4. Drain the sink and assert: |
| + - exactly 60 not-found records (the cap); |
| + - one minute record with `s404 == "71"` and `dropped_notfound == "11"`; |
| + - no record contains the raw token `3f9a0c1d2e4b5a6978877665544332211` in any field or message. |
| + 5. Encode with `applog.EncodeChunk`, decode with `DecodeChunk`, and assert the records survive unchanged. |
| + |
| +- [ ] **Step 2: Run it** |
| + |
| +Run: `go test ./internal/host/ -run 'TestRequestRecordsEndToEnd'` |
| +Expected: PASS |
| + |
| +- [ ] **Step 3: Run every touched package once, then gofmt** |
| + |
| +Run: `go test ./internal/reqrec/ ./internal/applog/ ./internal/edge/ ./internal/activator/ ./internal/host/ ./internal/console/ -run 'TestMaskPath|TestQueryNames|TestFragment|TestUAFamily|TestClient|TestRef|TestRecorder|TestSinkEdge|TestRecords|TestRecordMatch|TestEnableRequestRecords|Woke|TestNewRequestRecorderGates|TestReqrecLoop|TestEdgeRef|TestRequestRecordsEndToEnd' && gofmt -l .` |
| +Expected: PASS, and no files listed. |
| + |
| +- [ ] **Step 4: Commit and push; CI runs the full suite** |
| + |
| +```bash |
| +git add internal/host |
| +git commit -m "host: request records end-to-end through the real sink and recorder" |
| +git push origin <branch> |
| +``` |
| + |
| +Then `amadan ci status -branch <branch>` until it reports passed. |
| + |
| +## Not in this plan |
| + |
| +These come from the spec and belong to later plans: |
| +- Blocking anything. |
| +- The probe catalogue. |
| +- Reference codes in responses. |
| +- The CLI verb that explains a code (Plan 2, with copy review). |
| +- Console UI. |
| +- Recording the upstream status of watched matches during calibration (Plan 2; `Response.Status` already carries it). |
| +- Quieting the replica-sync logging that limits journald retention (separate small change). |