amadan
docs: nearest-region spec rev 6.1, R9a: app_default knowledge flags
Paul accepted region_known and placement_known (additive; absent knowledge fails closed), with the semantics Astra's plan round 3 judged sound: region_known says the stored region was read (else region, name, source and effective are empty); placement_known says the manifest and fleet placement were read (else reason policy-unreadable). deploy --region needs the first, canary --region the second.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
1 file changed,
+33
−1
docs/superpowers/specs/2026-10-01-nearest-region-default-design.md+33 −1
diff --git a/docs/superpowers/specs/2026-10-01-nearest-region-default-design.md b/docs/superpowers/specs/2026-10-01-nearest-region-default-design.md| index 30ed55727..daf0d9716 100644 |
| --- a/docs/superpowers/specs/2026-10-01-nearest-region-default-design.md |
| +++ b/docs/superpowers/specs/2026-10-01-nearest-region-default-design.md |
| @@ -1,7 +1,7 @@ |
| # Nearest region by default: each app picks its region at creation |
| **Date:** 2026-10-01 |
| -**Revision:** 6. |
| +**Revision:** 6.1. |
| - Rev 1 (7fbc9479) went to Astra (GPT-6, via codex), and the findings are in |
| `CODEX-FINDINGS-NEAREST-REGION-R1.md`. |
| @@ -28,6 +28,10 @@ |
| (`internal/activator/backend_exec.go:1146-1149`). An instance placed there |
| runs with no config, no secrets and no store binding. That was part of the |
| kpmg outage. Changes are marked "(R9)". |
| +- **Rev 6.1 records ruling R9a** (Paul, 2026-10-02): `app_default` gains |
| + `region_known` and `placement_known`. They are additive, and absent |
| + knowledge fails closed. They came out of the implementation plan's review |
| + (Astra plan round 2, finding 3), and §9.3 states their semantics. |
| **Status:** Approved by Paul on 2026-10-02: rev 5, plus the R9 amendment in |
| this revision. The rulings in §3 are Paul's and are not reopened here. |
| @@ -147,6 +151,7 @@ Non-goals, each with a follow-up in §20: |
| | R7 | **The rollback floor is a runbook rule.** It is documented for release notes and the roll recipe, with no outside guard. | §5.7, §17 | |
| | R8 | **Split** (Paul, 2026-10-01). Placement ships on this spec. Latency routing (R6) is sequenced to its own follow-on spec, built to the §13 invariants. | §13, §17 | |
| | R9 | **A box must hold the deployment's secrets key to receive placed instances** (Paul, 2026-10-02). | §6.1, §7, §8.1, §17 | |
| +| R9a | **`app_default` gains `region_known` and `placement_known`** (additive; absent knowledge fails closed) (Paul, 2026-10-02). | §9.3 | |
| | D1 | The app region is stored console-side and set once at creation. The create door fills an empty `req.Region` from it **before** normalization, the allow-list and the armed checks. Existing apps are backfilled to the home, so behaviour does not change. | §5, §7 | |
| | D2 | The guess works in coordinates: timezone to a point, IP to a point through an operator-supplied MaxMind-format `.mmdb` (`CONSOLE_GEOIP_DB`), then the great-circle nearest eligible region. Home when everything fails. | §6 | |
| | D3 | Surfaces: a new-app picker; names and the guess for external pickers; the CLI as R4. | §9, §10, §11 | |
| @@ -781,6 +786,25 @@ The response gains one block: |
| - `edges-unreadable`: `available` is omitted. |
| - An absent manifest is not an error, and no query parameters are added |
| (codex 8). |
| +- **(R9a) Two knowledge flags.** `/regions` always answers 200, so these |
| + say which facts behind `app_default` the console actually read: |
| + - `region_known` is true exactly when the app's stored region was read. |
| + When it is false, `region`, `name`, `source` and `effective` are empty |
| + (never the home's name standing in for an unread value), and |
| + `available` is omitted. |
| + - `placement_known` is true exactly when the app's manifest and its fleet |
| + placement were read. When it is false, `reason` is `policy-unreadable` |
| + and `available` is omitted. |
| + - They separate certainty about the stored region from certainty about |
| + the placement policy, because the two CLI checks need different facts. |
| + - **Absent knowledge fails closed.** A client treats a flag that is false, |
| + or missing from an `app_default` block, as unknown, and refuses the |
| + check that needs it. `deploy --region` needs `region_known`; refused, |
| + it prints C15c. `canary --region` needs `placement_known`; refused, it |
| + prints C30b. |
| + - Both flags are additive. A console too old to send `app_default` at |
| + all is handled as before (§9.6, §11): deploy skips its check, and |
| + canary refuses `--region`. |
| **9.4 `POST /api/cli/apps/{account}/{app}/regions/guess`.** |
| @@ -1530,6 +1554,14 @@ The `docs/site/cli.md`, README and release-note additions (§5.7, §11, §12, |
| Astra raised no open questions in round 4. §18 stands at none. |
| +### Amendment R9a (rev 6.1, Paul 2026-10-02) |
| + |
| +Not a review finding of this spec. Astra's review of the implementation |
| +plan (plan round 2, finding 3) showed that a 200 marked `policy-unreadable` |
| +let the CLI read an unread region as the home. Paul accepted the two flags |
| +that fix it. Astra's plan round 3 judged them sound. §3 (R9a) and §9.3 carry |
| +them, and the copy record gains C15c for deploy's refusal. |
| + |
| ### Amendment R9 (rev 6, Paul 2026-10-02) |
| Not a review finding: a production finding, ruled by Paul. Recorded here so |