amadan
docs: nearest-region spec rev 6.2, instance_domain on app_default
Paul approved instance_domain (2026-10-03): additive, read-only, the authoritative hostname suffix canary --region's preflight reads its own record under, with the PUT's answer checked against the preflight. Also records R9a's consequence for pooled and fleet apps (Astra plan round 4, finding 1): effective stays empty with the stored region unread, so canary --region needs both flags.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
1 file changed,
+45
−4
docs/superpowers/specs/2026-10-01-nearest-region-default-design.md+45 −4
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 daf0d9716..0d00ae227 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.1. |
| +**Revision:** 6.2. |
| - Rev 1 (7fbc9479) went to Astra (GPT-6, via codex), and the findings are in |
| `CODEX-FINDINGS-NEAREST-REGION-R1.md`. |
| @@ -32,6 +32,14 @@ |
| `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. |
| +- **Rev 6.2 records `instance_domain`** (Paul approved it on 2026-10-03): |
| + an additive, read-only field of `app_default`, the authoritative hostname |
| + suffix `canary --region` reads its own record under before any write |
| + (§9.3). It came out of Astra's plan round 3 (finding 1), and her round 4 |
| + judged it sound. Rev 6.2 also writes down a consequence of R9a that round |
| + 4 found (finding 1): with the stored region unread, `effective` is empty |
| + even for a pooled or fleet-placed app, so `canary --region` needs both |
| + flags. |
| **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. |
| @@ -762,7 +770,9 @@ The response gains one block: |
| "app_default": { |
| "region": "uk", "name": "UK · London", "source": "timezone", |
| "effective": "uk", |
| - "available": false, "reason": "absent" |
| + "available": false, "reason": "absent", |
| + "region_known": true, "placement_known": true, |
| + "instance_domain": "bab.oncarlos.com" |
| } |
| ``` |
| @@ -797,14 +807,36 @@ The response gains one block: |
| 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. |
| + - The R9a emptiness holds whatever the placement says: for a pooled or |
| + fleet-placed app whose stored region was not read, `effective` is still |
| + empty and `available` still omitted, and `reason` (`pooled`, `fleet`) |
| + is the only placement fact stated (rev 6.2, Astra plan round 4, |
| + finding 1). |
| - **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. |
| + it prints C15c. `canary --region` needs `placement_known` and, because |
| + its fleet check reads `effective`, `region_known` too (rev 6.2); |
| + 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`. |
| +- **(rev 6.2) `instance_domain`.** Additive and read-only: the domain the |
| + app's instance hosts take, so a client can name an instance's host before |
| + writing anything. It is the manifest's `domain` when a manifest exists, |
| + else the domain the instances-manifest PUT would stamp |
| + (`<sqid>.<PLATFORM_APPS_DOMAIN>`), and it is omitted when the manifest is |
| + unreadable or the console has no valid apps domain. |
| + - It is the authoritative hostname suffix for `canary --region`'s |
| + preflight: the CLI builds `<name>.<app>.<instance_domain>` and reads that |
| + one record (`GET …/instances/{host}`) before any write, because the |
| + capped instance list skips records it cannot read. A 404 means no |
| + canary yet; any other failure, or no `instance_domain`, refuses with |
| + C30c. |
| + - The CLI then checks the instances-manifest PUT's answer against the |
| + preflight: the host built from the domain that PUT returns must equal |
| + the host it read. If it does not, it stops with C30c before writing any |
| + record. |
| **9.4 `POST /api/cli/apps/{account}/{app}/regions/guess`.** |
| @@ -1554,6 +1586,15 @@ 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 rev 6.2 (`instance_domain`, Paul 2026-10-03) |
| + |
| +Not a review finding of this spec. Astra's plan round 3 (finding 1) showed |
| +that `canary --region`, deciding from the capped instance list, could miss |
| +an existing canary and write. The plan answered with `instance_domain` and a |
| +single-record read. Astra's plan round 4 judged it sound, including the |
| +check of the PUT's answer against the preflight, and Paul approved it. §9.3 |
| +carries it, with the round-4 consequence of R9a for pooled and fleet apps. |
| + |
| ### Amendment R9a (rev 6.1, Paul 2026-10-02) |
| Not a review finding of this spec. Astra's review of the implementation |