STD-GC-003: MAC CLIENT VS ORACLE CANONICAL CITY ARCHITECTURE¶

Status: APPROVED & BINDING
Authority: Thomas / Gas City Topology Architecture Contract
Applies To: Mac Workstations, Oracle Runtime Infrastructure, Gas City CLI Contexts

1. Prime Directive¶

MAC WORKSTATION                        ORACLE INFRASTRUCTURE
─────────────────────────              ───────────────────────────────
~/.gc/contexts.toml                    /opt/bluefly/blucity/
  oracle -> https://city.blutown.ai      city.toml
  city   -> blucity                      .gc/site.toml
NO registered Cities                     Canonical Supervisor
NO local Dolt (0)                        Canonical Dolt (127.0.0.1:3308)
NO local Supervisor (0)                  Canonical Sessions & Rigs

Oracle is the ONE Canonical City: Supervisor, Rigs, Sessions, and Dolt authority (127.0.0.1:3308) reside exclusively on Oracle at /opt/bluefly/blucity.
Mac is a PURE Client: The Mac hosts source checkouts, binaries, and ~/.gc/contexts.toml. It does not run a local City, local supervisor, or local Dolt server.

2. Target Resolution & Safety Model¶

Gas City CLI target resolution ranks discoverable local Cities higher than sticky default remote contexts.

To prevent a local checkout from hijacking gc commands: 1. MAC_REGISTERED_CITIES = 0: Do NOT run gc register for BluCity or DropCity on the Mac. 2. LOCAL_CITY_SUPERVISOR_AUTHORITY = 0: Do NOT start or troubleshoot a Mac supervisor for BluCity. 3. Explicit Context Execution: Use gc --context oracle <command> for remote operations.

3. Diagnostic & Error Classification¶

Error Code	Root Cause Category	Action Required
502 Bad Gateway	Proxy / route / controller / network failure	Fix `https://city.blutown.ai` route / Tailscale ingress
401 Unauthorized	Missing or invalid write grant / auth	Check `--grant-command` / token minting

Do NOT mutate grant_command while the endpoint returns 502. Resolve endpoint routing first.

4. Verification & Health Protocol¶

Mac Client Verification:

gc context show oracle
gc --context oracle events

Full City Health Verification:
```
ssh bluefly-platform "cd /opt/bluefly/blucity && gc doctor"
```
Do NOT run bare gc doctor on the Mac as an acceptance test for City health.