# Nearest region by default: each app picks its region at creation **Date:** 2026-10-01 **Revision:** 6.2. - Rev 1 (7fbc9479) went to Astra (GPT-6, via codex), and the findings are in `CODEX-FINDINGS-NEAREST-REGION-R1.md`. - Rev 2 (bd4ed0c4) went back, and the findings are in `CODEX-FINDINGS-NEAREST-REGION-R2.md`. - Rev 3 (8e59f598) went back again, and the findings are in `CODEX-FINDINGS-NEAREST-REGION-R3.md`. - Every finding of all three rounds was checked against the code and accepted. Changes are marked "(codex N)", "(codex R2-N)" and "(codex R3-N)", and §21 records each disposition. - Rev 3 folded in Paul's answers to rev 2's questions as rulings R5 to R7. - **Rev 4 moves latency routing (R6) into a follow-on spec**, because the existing steering converger is not safe to arm (§13). That spec gets invariants to meet, and placement ships first. - Rev 4.1 records Paul's ruling on that split as R8 and removes the question. - Rev 5 answers Astra's round 4 (`CODEX-FINDINGS-NEAREST-REGION-R4.md`): three P2s, marked "(codex R4-N)". Astra's round 5 found nothing new; Paul approved rev 5 on 2026-10-02. - **Rev 6 is an amendment Paul approved on 2026-10-02, ruling R9**, after a production finding: only the Ireland box holds `CARLOS_SECRETS_KEY`. On the UK, US and AU boxes the config loops log "config sync loop disabled: CARLOS_SECRETS_KEY not set" (`internal/host/agent.go:881-886`), and a wake treats a missing `.config.env` as empty (`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. - **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. **Discussion:** not yet filed on amadan. Latency routing depends on amadan #169. **Builds on:** - #329, the armed-placement gate - #346, the home region's name (`CONSOLE_HOME_REGION`) - the customer-fleets placement column - #162, replica placements - #175/#331, instance moves - the multi-region steering converger (`internal/steering`) ## 1. The problem, as found On 2026-10-01 the Ireland box carried 116 of the flagship's 116 non-static instances and reached 91% disk. Overnight, one customer's three instances crash-looped for 4h18m on a full disk. Nothing chose Ireland. Nothing chose anything. Every create path ends at one door, and that door's default is the home box: - The instance create door, `handleAPIInstanceCreate` (`internal/console/apiinstances.go:608`), trims `req.Region` and hands it to `homeRegionIn` (`apiinstances.go:772`; the function is at `internal/console/apiinstancemove.go:136`). The home's name normalizes to `""`, and `""` is the unconstrained record only the home box mints. - The new-app page (`internal/console/templates/app_new.html`) asks for a name and nothing else. The Instances tab's Placement section (`templates/app_instances.html:60-78`) offers "Shared fleet" or one of the account's own fleets, which is a different axis. - `carlos deploy` creates an app only through `offerCreateApp` (`deploy.go:513`, call at `:536`), and sends no region. Its only instance write is the static platform host (`mintPlatformHost`, `deploy.go:850`, create at `:858`), which sends `""`. - `carlos canary` creates its host at `canary.go:407` with region `""`. - Only `carlos instances create --region` (`instances_cli.go:293`, sent at `:322`) chooses, and only when a person remembers to. External signup paths (titogo, Managed Jelly) hold instance-role tokens and send no region. And nothing is steered. Latency routing exists (`internal/steering`), but it is armed nowhere, because no deployment sets `CARLOS_STEERING_ZONE_ID` (amadan #169). Every instance host therefore resolves through the deployment's static DNS. On the flagship that is one `*.oncarlos.com` record pointing at the Ireland EIP, served by DNSimple. The Route53 copy of the zone is staged and is not yet authoritative (carloku-infrastructure `dns.tf` and `dns53.tf`). What exists to build on: - **Placement codes** are bare (`ie`, `uk`, `au`): `CARLOS_REGION` verbatim. - **Place names**: the only one anywhere is `STATUS_BOX_REGION`, operator free text for the public status page (`internal/host/agent.go:88-92`). - **The edges file**: every box publishes its AWS region and its placement code there (`internal/host/edgesfile.go:155-176`). The region comes from `edgesFileRegion` (`:537`), which honours a `CARLOS_AWS_REGION` override. - **What the console already reads**: both of those, through `edgesFilePlacementView` (`internal/console/instancesplacement.go:35-55`) and `servedBy.Region` (`:25-28`). - **Capability**: `placements` and `armedPlacements` (`instancesplacement.go:173`, `:207`) say which codes can host. - **The regions endpoint**: `GET /api/cli/apps/{account}/{app}/regions` (`internal/console/apiregions.go:31-55`) returns codes, `armed` and `"default": HomeRegion`, and reads no manifest. There is no geolocation of any kind. ## 2. Goals and non-goals Goals: - A new app gets a region at creation, preselected from a guess of where its creator is. Its new instances start there unless told otherwise. - A new instance placed outside the home is reached through the nearest edge, not through the home's (R6). The follow-on spec for Phase L delivers this goal, against the invariants in §13. - The guess is generic: any deployment, any set of AWS regions. - The guess can never name a region the create door would refuse, or one no box would mint (codex 1, codex R2-1). - Existing apps, older CLIs and external callers that send nothing behave exactly as today. **Done** has two stages: - **This spec** is done when new apps get regions and new instances follow them. - **The work as a whole** (R5, R6) is done when the follow-on spec has made latency routing safe to arm, and #169 is armed. Existing apps keep their region. Relieving Ireland of the instances it already holds is the instance-move work (#175/#331), not this spec. Non-goals, each with a follow-up in §20: - Arming DNS steering and changing the converger. This is Phase L, the follow-on spec (§13). - Moving existing instances. - Changing an existing app's region (R5). - A browser instance-create form. - Sidecars following the app's region. - Pool-aware candidates. - Box sizing and disk alerts. - An account-level default (R1). ## 3. Rulings (Paul, 2026-10-01) | # | Ruling | Where this spec spends it | | --- | --- | --- | | R1 | Region is both latency and placement, chosen **per app**. Each app picks its region at creation, preselected from a location guess. No account-level default. | §5, §8.1, §13 | | R2 | The app's region is the **default** for new instances. It can be overridden per instance (picker or `--region`), subject to the manifest `Regions` allow-list and the armed/hosting check. | §7 | | R3 | Guess **timezone first**. Fall back to IP geolocation when the timezone is UTC, `Etc/*` or otherwise unmappable. | §6 | | R4 | The CLI guesses too. `carlos deploy` creating an app sends its timezone, the console resolves it, and the CLI prints one line ("Region: UK · London (from your timezone). Use --region to choose another."). No prompt. `--region` overrides everywhere. `carlos instances create` defaults to the app's region. | §11 | | R5 | **Done = new apps only, plus moves.** Existing apps keep their region. Relieving Ireland comes from instance moves. An owner-only verb to change an existing app's region is out of scope (a follow-up). | §2, §20 | | R6 | **Latency routing is in scope** for non-home instances, not placement alone. | §13: its invariants and gates, delivered by the follow-on spec | | 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 | | D4 | Place names come from one platform-shipped AWS-region table, used everywhere and reconciled with `STATUS_BOX_REGION`. | §14 | ## 4. The shape, in one paragraph The console's `apps` row gains two columns: - `region`, in the record's own vocabulary, where `""` is the home; - `region_source`, one word saying how it was picked. Both app-create doors resolve a region before the row is written. The order is an explicit choice, then the creator's timezone, then the request's IP (through the optional GeoIP database), then the home. Resolving means finding the great-circle nearest region whose boxes have positively said they can mint an ordinary instance. From then on, an instance create that names no region gets the app's region, and that value meets every check an explicit one meets. An **app-derived** value additionally needs that positive eligibility, while an explicit one keeps today's gate (codex R3-6). Latency routing for non-home instances (R6) is specified as invariants (§13) and delivered by a follow-on spec. Until that lands, this spec writes nothing to DNS and stamps nothing. Existing rows read `""`, which is what they have always meant. Nothing writes a non-home app region until the operator turns the feature on, and the console will not turn it on without a named home. ## 5. Data model ### 5.1 Columns **(decision) Two columns, appended to the ALTER list in `migrate`** (`internal/console/store.go:91`, list ending `:386`): ```sql ALTER TABLE apps ADD COLUMN region TEXT NOT NULL DEFAULT ''; ALTER TABLE apps ADD COLUMN region_source TEXT NOT NULL DEFAULT ''; ``` - `region` is a placement code in the **record vocabulary**: `""` is the deployment's home, exactly as on a `provision.Record` (#346). A choice of the home's name is normalized with `homeRegionIn` before storing, and displays use `homeRegionOut` (`apiinstancemove.go:143`). - `region_source` is `chosen`, `timezone`, `ip`, `default`, or `""` (the row predates this feature). It is a label for people and logs, and nothing branches on it. **Nothing else is stored**: not the timezone, not the IP, not a coordinate. ### 5.2 The rebuild trap `migrateAppsKey` (`store.go:472`) rebuilds `apps` with a fixed column list (`:487-505`) and runs **after** the ALTER list. On a database not yet rebuilt, the new columns would be added and then dropped by the rebuild's `INSERT … SELECT`, and every later read of `region` would fail. **Both columns go into `apps_new`'s DDL and the INSERT's column list in the same change.** This is the rule the comment at `:499-503` already records for `placement`, `control_plane` and `build_probe`. ### 5.3 Written with the row **(decision) The region rides the INSERT that claims the name.** - A new `CreateAppInRegion(accountID, app, createdBy, region, source, now)` carries both columns. - `CreateAppIn` (`store.go:1349`) becomes a call to it with `("", "")`, so `CreateApp` (`:1342`) is unchanged. - `claimApp` (`internal/console/server.go:3466`) gains a `regionReq` parameter (§5.5). This departs from the placement precedent on purpose. `SetAppPlacement` after `CreateAppIn` (`server.go:3550-3567`) is best-effort, because `carlos apps place` can repair it. An app region has no repair verb (R5), so a failed second write would leave the app at the home for good, silently. Rename (`store.go:1791`) and transfer (`:1709`) update the same row, so the region survives both. The legacy owners backfill (`:665`) inserts defaults, which mean the home. ### 5.4 Backfill **(decision) The column default is the backfill.** Every existing row reads `""`/`""`. `""` is the record vocabulary's home, so the door's fill (§7) turns `""` into `""` and nothing changes, byte for byte. Writing the home's code instead would be worse on every count: - It would gain nothing, because `homeRegionIn` normalizes it back to `""`. - It would be impossible where `CONSOLE_HOME_REGION` is unset. - It would freeze the home as of migration day, where `""` follows the home as records already do. The backfill is idempotent by construction: the ALTERs swallow "duplicate column", and there is no one-shot `PRAGMA user_version` step. ### 5.5 Explicit choice versus guess, and adoption (codex 2, codex R2-3, codex R2-5) `claimApp` receives a request-local struct, not a resolved region: ```go type regionReq struct { explicit string // a person's choice: a code or the home's name; "" = none tz string // a hint ip net.IP // from s.clientIP, set only for a person's request } ``` **Only `explicit` is a choice.** The guess is resolved inside `claimApp`, after it knows whether this is an adoption, so no caller can pass a guess off as a choice. `ip` comes from `s.clientIP` (`internal/console/authcli.go:876`). `claimApp` has no `*http.Request`, and its `addr` argument is the audit actor (`apicli.go:349`), not a network address (codex R2-5). Both callers fill `ip` before the call. It lives only for that call, and is never logged or stored. **(decision) Adoption never changes an existing app's region by guessing.** An owner claiming a name whose objects already exist (`adoptingExistingApp`, `server.go:3502`, `:3545`) is restoring an app that probably has instances at the home. An adoption stores `""` with source `default` unless `explicit` is set. A guess, however it was computed and whatever the form displayed, is discarded. The browser form keeps the two apart without trusting any label. The preselected option's value is `@auto`, which is outside the placement-code grammar (`^[a-z0-9-]{0,16}$`, `provision.go:688`). A deployment with a region, or a home, named `auto` therefore still works (codex R2-3). Only a region code is `explicit` (§10). The CLI sends `region` only for `--region`, and sends `timezone` separately (§9.1). ### 5.6 The switch and the named home (codex 3, codex 4) **(decision) Non-home app regions are written only when both of these hold:** - `CONSOLE_APP_REGIONS=on` (new; off by default); - `CONSOLE_HOME_REGION` is set. If the switch is on and the home is unnamed, the console logs that once at startup and behaves as if the switch were off. Without a named home, `""` is the only way to say "home", and `""` also means "no preference". No request could then choose the home over a non-home app default. A named home makes `"region": ""` an explicit choice at every door. While the switch is effectively off: - Every new app gets `""`/`default`. An explicit non-home `region` on app create is not stored, and the response shows what was (§9.1). - The new-app picker is hidden. - The guess endpoint (§9.4) still answers, because a per-instance guess for titogo writes nothing to the app row. - **The door's fill still runs.** Turning the switch off stops new promises. It never breaks the ones already made. ### 5.7 Mixed versions and rollback (codex 4, R7) The console owns its SQLite database, so one database is served by one console at a time. Mixed versions therefore means a rollback, or a roll that has not yet reached a deployment's console. A console older than this feature ignores the columns, so after a rollback it would land a no-region create for a `uk` app at the home. **(decision, under R7) The rule:** 1. **Roll the read side first.** The first release carries the migration, the fill, the endpoints and the UI, with the switch off. Every app row is then `""`, so the release can be rolled back freely. 2. **The switch is the feature's rollback lever.** It is turned on only after that release has run cleanly. Turning it off stops new non-home values and keeps the fill. 3. **Once any app holds a non-home region, the binary rollback floor is the first region-aware release.** This is a runbook rule (R7), with no outside guard. It is written in three places: - the README's "Releasing the platform" section (`README.md:227`); - that release's notes; - the console roll recipe in `carlosframework/carloku-infrastructure`. Rolling below the floor is out of policy. If it happens anyway, no-region creates land at the home, as they do today. Nothing is lost. 4. **On roll-forward, the console logs possible placement discrepancies** (codex R2-6). For each app with a non-home region, it lists records that carry an empty region and were created after the app. Records that never inherit the app default are excluded: static, addr-backed, replica, pooled and fleet-placed. Those are the shapes §7 leaves unfilled. A deliberate home override also produces an empty region, and the record keeps no provenance, so the list is a set of candidates for a person to review, not a detection of rollback damage. The runbook records the rollback interval, so the review can be narrowed to records created inside it. CLIs mix freely in both directions (§9.6). ## 6. Resolving a region ### 6.1 Candidates and eligibility (codex R2-1) **(decision) One function, `regionCandidates(ctx, policy)`, in `instancesplacement.go`, built from the same edges-file read `placements` uses.** Each candidate is `{code, awsRegion, eligible}`. **Eligibility is positive and per box.** `Hosting` checks reachability and the activator, but not whether a box will mint an *ordinary* instance: - A box with `CARLOS_POOLS` set serves the shared pool only if the list names it (`poolServed`, `internal/provision/reconcile.go:1339`). - A box with `CARLOS_INBOUND=none` refuses every routed instance (`reconcile.go:925`). Neither fact is in the edges file today. **(decision) Each box publishes two additive fields** in `edgesFile` (`internal/host/edgesfile.go:155-176`): - `serves_shared_pool`: `poolServed(cfg.Pools, "")`; - `accepts_inbound`: `cfg.Inbound != InboundNone`. **Both are computed from the very `provision.ReconcileConfig` the reconcile pass uses**, which `provisionTickConfig` builds (`internal/host/agent.go:2030`). They are never re-parsed from the environment (codex R3-3). That parser drops empty elements, so `CARLOS_POOLS=,tito` is `["tito"]` and does **not** serve the shared pool. The box publishes `false` for it. A box that should serve both the shared pool and a named one needs a parser change with its own tenancy tests, which is not part of this spec. They follow `hibernation_configured`'s precedent: not `omitempty`, so absent means "unknown" and false means "no". This is the one box-side change in this spec. It is purely additive, and old readers ignore it. A code is **eligible** when at least one reachable box publishing it has `hibernation_configured`, `serves_shared_pool` and `accepts_inbound` all **positively true**. Unknown is not yes here. That is the reverse of `placements`' generosity, and deliberately so: that generosity is right for an explicit request, which a person made and can see refused. It is wrong for an automatic one. Until boxes roll with the fields, no coded region is eligible. The guess then picks only the home, so the feature cannot outrun the box roll. **The secrets key (R9).** An exec instance's config, secrets and store binding reach it only through `.config.env`, which the agent renders only when the box holds `CARLOS_SECRETS_KEY` (`agent.go:881-886`, `:1812`). A wake treats a missing file as empty (`backend_exec.go:1146-1149`), so a box without the key runs a placed instance with nothing, silently. Eligibility therefore gains a fourth fact. - **What a box publishes.** One more edges-file field, `secrets_key_fp`: the fingerprint of the public half of the box's `CARLOS_SECRETS_KEY`, never the key. The name, its place beside `placement` and `data_bucket`, and its shape (additive, `omitempty`, absent when the box holds no key or a key that does not parse) are the move-any-app spec's (`2026-10-02-move-any-app-design.md` §6, on `design-moves-any-region` at e41c4fef). Both features read one field. - **The format**, which that spec names but does not fix, is fixed here for both: `"sha256:"` followed by the lowercase hex SHA-256 of the public key's uncompressed SEC1 bytes (`(*ecdh.PublicKey).Bytes()`, 65 bytes for P-256). Those are exactly the bytes `CARLOS_SECRETS_PUBKEY` base64-decodes to, so a box (from its private key) and the console (from the public key) compute the same string. One helper, `appconfig.KeyFingerprint`, is the only code that renders it. The move-any-app spec should cite it rather than define a second one. - **What the console expects.** The console learns the deployment's fingerprint from its own `CARLOS_SECRETS_PUBKEY` (`Config.SecretsPub`, `cmd/console/main.go:467-490`). That is the key the CLI seals config to, so it is by definition the one a box must be able to open. The move-any-app spec's console makes the same choice. The console never learns the fingerprint from a box: a "majority of boxes" or "the home box" rule would certify whatever key happened to be widespread, including a wrong one. With `CARLOS_SECRETS_PUBKEY` unset, the console cannot judge. It logs that once at startup, and no coded region is eligible for automatic placement. - **The rule.** A code is eligible only if at least one box that meets the other three facts also publishes a `secrets_key_fp` equal to the console's. The home stays exempt, as it is from every eligibility fact: it is where every legacy create already lands, and on the flagship it is the one box that holds the key. - **The reason word.** A code that fails only this fact reports `no-secrets-key`, between `not-hosting` and `not-eligible` in the order of checks (§9.3, C16). Candidate rules: - **Coded regions**: boxes whose `Placement` passes `provision.ValidRegion`. Fleet codes (`fleet/`) fail on the `/`. - **The home**: boxes that publish no placement, or the home's name, and have a dial address. The home is exempt from the positive check, because it is where every legacy create already lands. `handleAPIRegions` already treats it as always armed (`apiregions.go:42-47`). - **AWS region**: the `Region` of the eligible boxes behind the code. If they disagree, the most common wins, ties go to the lexically smallest, and the disagreement is logged once. - **Policy**, read with `provision.GetManifest` directly (codex 6). This is never `instanceManifest`, which answers 409 or 502 for the caller (`apiinstances.go:117`). - *absent*: no allow-list and no pool. - *known*: candidates pass through `instanceRegionAllowed` (`apiinstances.go:1797`) on the **normalized** code. **A pooled manifest yields no candidates and no guess** (codex 1). - *unreadable*: no guess, and an explicit error at the guess endpoint. - **Fleet placement** (codex R4-1). The instance guess endpoint (§9.4) resolves `appPlacement` (`internal/console/fleets.go:479`) first. **A fleet-placed app gets `"guess": null`**, because the door replaces any submitted region with the fleet (`apiinstances.go:798`), so a guess could only mislead a picker. A failed placement read is an explicit error there (C27), never an unrestricted guess. App-creation inference (§5.5) is unaffected: it chooses the stored app region, which stays dormant while the app is placed. - **Read failure** (codex R2-2): the listing failing is distinct from "no file publishes a placement". `readEdgesFiles` (`instancesplacement.go:83`) swallows the first today. A new `readEdgesFilesStrict` returns the error. Candidates built after a failed read are the home alone, if the policy admits it (§6.4), and the door treats the failure as unconfirmed (§7). ### 6.2 Points A point is a latitude and longitude held in memory for one request. **Timezone.** *(decision)* A new package, `internal/geo`, embeds three files from one IANA tzdata release: - `zone.tab`, one row per country and zone, with ISO 6709 coordinates; - a link table generated from tzdata's `Link` lines; - a `VERSION` stamp. `zone.tab` is used rather than `zone1970.tab` because browsers report names that `zone1970.tab` has merged away. For example, `Europe/Amsterdam` has its own row in `zone.tab` and none in `zone1970.tab`. The links matter because Chrome reports `Asia/Calcutta` where Firefox reports `Asia/Kolkata`. Go's `time/tzdata` carries no coordinates, so it cannot be the source. The files are **kept current** by `scripts/update-tzgeo.sh `, which fetches the release from `data.iana.org`, checks its signature, and rewrites the three files. Running it is a release-checklist step. A stale table only misses zone names newer than it, and those fall through to IP. Lookup: 1. A shape check: at most 64 bytes, one to three `/`-separated segments of `[A-Za-z0-9_+-]`. 2. Unmappable by rule: `""`, `Local`, `UTC`, `UCT`, `GMT`, `Universal`, `Zulu`, `Factory` and all of `Etc/`. 3. Links, at most 4 hops. 4. `zone.tab`, case-insensitive. A miss at any step makes the timezone unmappable. **IP.** *(decision)* `CONSOLE_GEOIP_DB` names an operator-supplied `.mmdb`. It is read in `cmd/console/main.go` beside `CONSOLE_HOME_REGION` (`main.go:278`) into a new `Config.GeoIP`. - **Recommended source**: DB-IP Lite (CC BY 4.0). Its attribution appears on the page that uses it (C24) and in the README. MaxMind GeoLite2 also works, under its EULA's conditions, which include attribution and keeping the data updated. The operator owns that compliance. - **Unset**: the IP fallback is off, which is the default. - **Unopenable**: logged once, the fallback is off, and **the console still starts**. - **Lifecycle**: the file is opened once and memory-mapped. Replacing it is an atomic rename plus a console restart. - **Lookup**: the `location` field, else `country.iso_code`, else `registered_country.iso_code`, through country points. A lookup error is a miss, logged at most once a minute. - **Never looked up**: loopback, private, link-local, CGNAT and unspecified addresses. The reader is `github.com/oschwald/maxminddb-golang` (ISC), pinned to a reviewed version. The tests use pinned fixtures from MaxMind's `MaxMind-DB` test data (MIT or Apache-2.0). **Country points.** *(decision)* These come from the same `zone.tab`, not a second dataset. - A one-row country uses its row. - A multi-row country uses a shipped override naming its principal zone: `US` → `America/New_York`, `AU` → `Australia/Sydney`, `CA` → `America/Toronto`, `RU` → `Europe/Moscow`, `BR` → `America/Sao_Paulo`, `CN` → `Asia/Shanghai`, and so on. - A test fails when a tzdata refresh gives a country a second row with no override. **Whose IP.** The client IP from `s.clientIP` reaches the guess only for a person's request (§5.5). A service or app principal is a server, so it gets the IP step only by sending an address in the guess body (§9.4). ### 6.3 Nearest Each eligible candidate's AWS region maps to a point through the region table (§14). Distance is haversine (mean Earth radius 6371.0088 km), rounded to whole kilometres. - A candidate with no point is left out and logged once per code. - **If the home has no point, the guess is `default`.** - **Ties** go to the home, then to the lexically smallest code. - An ineligible candidate is never picked. ### 6.4 Order ``` explicit region (validated as in §8.1) → "chosen" else timezone gives a point → nearest → "timezone" else IP gives a point → nearest → "ip" else home → "default" ``` **The guess invariant** (codex R3-4): every non-null guess, including every fallback to the home, passes the same normalized policy predicate the door applies (`instanceRegionAllowed` on the `homeRegionIn` form). The steps run in this order: 1. Filter candidates by policy (§6.1). 2. Pick the nearest among the filtered candidates that have a point. 3. If the home has no point, or nothing maps, the fallback is the home, **but only if the home is itself a filtered candidate**. 4. Otherwise the answer is `"guess": null`. So a manifest that allows only `uk`, with the home's coordinates missing, gives `uk` when the hint maps and `null` when it does not, never the home. There is also no guess when the policy is pooled or unreadable. ### 6.5 Logged, and not logged (codex 8) - One line per app creation: `console: app region /: ()`. - Once per process: an unusable `CONSOLE_GEOIP_DB`; a code with no point; boxes disagreeing on a code's AWS region. **The timezone, the IP and any coordinate never reach a URL, a log line, an audit row, a response body or the database.** They travel only in POST bodies. The canonical-host redirect copies the whole query string into its `Location` header and its HTML (`server.go:1306`, `:1326`). A 308 on a POST keeps the body out of both. ## 7. The instance create door **(decision) The fill, replacing `apiinstances.go:772`:** ```go raw := strings.TrimSpace(req.Region) regionFrom := "" if raw != "" { regionFrom = "request" } if raw == "" && placed == "" && m.Pool == "" && strings.TrimSpace(req.Role) == "" && (provision.Record{Kind: strings.TrimSpace(req.Kind), Addrs: req.Addrs}).DerivesPaths() { appRegion, _, err := s.store.AppRegion(acct.ID, app) if err != nil { // log; 502 C20 } if appRegion != "" { raw, regionFrom = appRegion, "app" } } region := s.homeRegionIn(raw) ``` **Where it sits.** After `appPlacement` (`apiinstances.go:763`), and before `checkReplicaCreate` (`:781`), the allow-list (`:799`) and the armed gate (`:827`). **Every check an explicit region meets, a defaulted one meets too** (R2). An explicit home name is non-empty, so it never triggers the fill, and `homeRegionIn` then turns it into `""`. That is the override that always exists once §5.6 holds (codex 3). Each condition earns its place: | condition | why the default stays out | | --- | --- | | request names a region | an explicit choice wins (R2) | | `placed != ""` | a fleet placement already governs every instance's region (`:785`) | | `m.Pool != ""` | a defaulted region with no box serving the pool mints nowhere | | `req.Role != ""` | a replica must name its placement; filling it would turn "role replica needs a placement" (`:578-581`) into a silent acceptance | | not `DerivesPaths()` | only a socket-backed instance has a process and data that region places | | store read fails | refused, as the placement read above it is (`:764-768`) | **An app-derived region needs positive eligibility** (codex R2-2). The armed gate goes dormant when no file publishes a placement (`:848`). That dormancy stays for explicit requests and for the legacy home default. For `regionFrom == "app"` it does not apply. The door reads the edges files strictly (§6.1) and refuses in three cases: - **The read failed**: a 503 with C28. The region could not be confirmed, which is different from "absent". - **No eligible box publishes the code**: C16, naming `absent`, `not-hosting`, `no-secrets-key` (R9) or `not-eligible`. This covers the last box in a region being retired, and every box losing its placement code. - **The allow-list excludes it**: C17. The armed gate's own checks then run as before. *(decision)* **A failing defaulted region is refused, not quietly replaced by the home.** The way out is always an explicit region, the home's name included, and `app_default` (§9.3) and the Instances tab (§10) show the refusal before anyone tries (codex 7). *(decision)* **A defaulted home whose region is in its own `replicas` set is refused** (C26). Explicit requests keep today's behaviour. *(decision, R9)* **An explicit request into a region whose boxes provably lack the deployment's secrets key is refused** (C31, 400), for a socket-backed instance (`DerivesPaths`) and for a replica. Static and addr-backed records need no config on the box and are unaffected. - **What "provably" means.** The console's `CARLOS_SECRETS_PUBKEY` is set, and every reachable, hosting box publishing the code is a **current writer** (it publishes `accepts_inbound`, which the same box release adds and which is never omitted). Among those boxes, none publishes a matching `secrets_key_fp`. A current writer that publishes no fingerprint holds no key, because the field is omitted exactly then. - **Unknown keeps today's behaviour.** An old writer, or a console with no `CARLOS_SECRETS_PUBKEY`, cannot prove a mismatch, so the request proceeds as it would today. Roll order therefore never refuses a working region. - **Why refuse, and not keep today's behaviour.** The record this would write is an instance that starts, answers health checks, and runs with no config, no secrets and no store, which is the kpmg outage. It belongs with the existing "reachable but cannot host" refusal (`apiinstances.go:827-852`, #110). That one also refuses an explicit request the box would accept but could never serve. A person who named the region learns why at the door, not from a broken app. **Response.** `apiRecordView` (`apiinstances.go:535`) gains two fields that sit outside the record, like `PrivateStoreBucket`: - `region_from`: `request`, `app` or `fleet`, omitted for the home default; - `region_name` (§14). ## 8. Every create path ### 8.1 Where an app is created | path | file:line | change | | --- | --- | --- | | New-app form, GET | `handleNewAppForm`, `server.go:3586`; `app_new.html` | picker with an `@auto` option (§10), when the switch is on and two or more regions are eligible | | New-app form, POST | `handleNewApp`, `server.go:3607`; claim at `:3626` | `region` is `@auto` or a code; `tz` from a hidden field; `ip` from `s.clientIP`; builds `regionReq` (§5.5) | | CLI API create | `handleAPICreateApp`, `internal/console/apicli.go:330`; body at `:359`; claim at `:415`; response at `:461` | takes `region` and `timezone`; `ip` from `s.clientIP` for a person; returns `region`, `region_name`, `region_source` and `regions_available` | | The claim | `claimApp`, `server.go:3466`; insert at `:3550` | takes `regionReq`; resolves once it knows whether this is an adoption; `CreateAppInRegion` (§5.3) | | `carlos apps create` | `runAppsCreate`, `apps.go:442`; call at `:497`; print at `:502` | `--region`; sends the timezone; prints the region line (§11) | | `carlos deploy` onboarding | `offerCreateApp`, `deploy.go:513`, reached from `runDeploy` at `:113`; call at `:536`; print at `:540` | `--region`; sends the timezone; prints the region line | | CLI client | `apiSession.createApp`, `apimode.go:994`; `apiCreateAppResult`, `:958` | two `omitempty` fields in, four tolerant fields out | | Legacy owners backfill | `BackfillOpsMemberships`, `store.go:623`; insert at `:665` | none: the defaults mean the home | *(decision)* An explicit region at app create is validated the way the instance door validates one: 1. `ValidRegion`. 2. Armed and hosting, unless the gate is dormant. 3. Not provably missing the secrets key (R9, the same rule as §7), refused with C31. 4. The home's name is accepted through `homeRegionIn`. Refusals list what would pass (C18, C19, C31). There is no allow-list yet, because there is no manifest yet. A fleet `place` and a `region` may both be sent, and both are stored (§12). ### 8.2 Where an instance is created | path | file:line | today | change | | --- | --- | --- | --- | | The door | `handleAPIInstanceCreate`, `apiinstances.go:608`; region at `:772` | `""` means the home | the fill and eligibility (§7) | | `carlos instances create` | `instances_cli.go:322` | sends `--region` or `""` | help text; prints `region_name` (§11) | | `carlos canary` | `canary.go:407` | sends `""` | the door fills the app's region; a new `--region`, with the existing-canary rule (§11) | | `carlos deploy` static host | `mintPlatformHost`, `deploy.go:858` | static, `""` | none | | First-route domain attach | `internal/console/domainattach.go:178` | static, no region | none | | External callers (titogo, jam) | `POST …/instances`, `internal/console/authcli.go:613` | usually `""` | follow the app's region; can ask for a guess (§9.4) | | Sidecar create | `handleAPISidecarCreate`, `internal/console/apisidecars.go:257` | `""` or explicit | none (§12) | ## 9. API changes All changes are additive: new request fields are optional and new response fields can be ignored. `readJSON` is not strict (`authcli.go:932-947`), so an old console ignores the new request fields instead of refusing them. **9.1 `POST /api/cli/apps/{account}/new`.** The request gains two optional fields: - `region`: an explicit choice, as a code or the home's name; - `timezone`: a hint, used only when there is no `region`, and never stored. The response gains these fields, echoing what was **stored**: ```json {"region": "uk", "region_name": "UK · London", "region_source": "timezone", "regions_available": 3} ``` - `regions_available` counts eligible candidates. - With the switch off, an explicit non-home `region` is answered with the home and `default`, and the CLI says so (C13b). **9.2 `POST /api/cli/apps/{account}/{app}/instances`.** The request is unchanged and behaviour follows §7. The response gains `region_from` and `region_name`. **9.3 `GET /api/cli/apps/{account}/{app}/regions`.** The gate, the role (`authcli.go:586`) and the legacy fields are unchanged (codex 6): - `regions` is still the observed topology, unfiltered. - `default` is still `HomeRegion`. - Each entry gains `aws_region` and `name`. The response gains one block: ```json "app_default": { "region": "uk", "name": "UK · London", "source": "timezone", "effective": "uk", "available": false, "reason": "absent", "region_known": true, "placement_known": true, "instance_domain": "bab.oncarlos.com" } ``` - `region` is the app's **stored** region under its name, always. It is the only field `deploy --region` compares against (codex R2-4). - `effective` is where a create that names no region actually lands: - the stored region; - the home, for an app with no region of its own or a pooled app; - the fleet placement itself (`fleet/acme`), for a fleet-placed app, never the platform home (codex R2-4). - `available` and `reason` describe `effective`: - `absent`: the code is reported even though `regions` does not list it (codex 7); - `not-hosting`; - `no-secrets-key` (R9, §6.1); - `not-eligible` (§6.1); - `not-allowed`; - `pooled`; - `fleet`: `available` is omitted, because the fleet's own rail decides; - `policy-unreadable`: `available` is omitted; - `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. - 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` 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 (`.`), 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 `..` 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`.** - Same gate and role as §9.3. - The body is `{"tz": "...", "ip": "..."}`, both optional. A person's request with no `ip` uses its own address, and a service principal's never does. - The answer is `{"guess": {"code", "name", "source"}}` or `{"guess": null}`. It is `null` for a pooled or fleet-placed app (§6.1) (codex R4-1). - An unreadable manifest, or an unreadable fleet placement, gets a 502 with C27. - It writes nothing. **9.5 Browser: `POST /a/{sqid}/apps/new/region`.** - A form body with `csrf` and `tz`. - Gated by session through `s.account`. - Returns `{"code", "name", "source"}`. - Writes nothing. - `new` is a reserved app name (`server.go:1150`). **9.6 Compatibility and mixed versions.** | client | console | result | | --- | --- | --- | | old CLI | new | No `timezone` is sent, so IP for a person, then home. Never an error. | | new CLI | old | The response has no `region`. The CLI prints nothing, or C13a if `--region` was given. | | new CLI | new, switch off | The app goes to the home. With `--region`, C13b. | | titogo, unchanged | new | Creates follow the app's region, which for every existing app is the home. `default` is unchanged. | | any | rolled back below the floor | R7: no-region creates land at the home, and roll-forward lists the possible discrepancies (§5.7). | ## 10. Console UI **New-app page** (`app_new.html`), when the switch is on and two or more regions are eligible: - **The picker.** A `