Skip to content

Gas City Cities and Topology Catalog

Purpose: Catalog Bluefly cities and their expected source/runtime topology without embedding machine-local drift as authority.

Upstream: Beads topology, Managed-city endpoints, Split storage classes

Declarative SoR (BluCity): deploy/oracle/beads-topology.yaml in blueflyio/blu/blucity

Taxonomy boundary (read first)

A City is the local/root Pack plus deployment details (pack.toml + city.toml). It is not a seventh Gas City primitive. The six primitives are Agent (5-axis configured), Bead, Formula (v2 DAG), Rig (on-demand/pinned), Pack, and Event. See gc-catalog.md.

Mountain, Product, and Project are not Gas City primitives — they are Bluefly portfolio taxonomy. See gc-catalog.md.

City is the term most likely to be confused with Mountain — both can read as "the whole thing" at a glance. They are not interchangeable:

  • City = the deployed local/root Pack plus city.toml runtime/deployment layer (one city, blucity, today).
  • Mountain = a durable Bluefly portfolio/program domain (e.g. AMCS, DevOps) — organizational taxonomy, not a deployment.

BluCity is the City itself. It is not a Rig (see gc-rigs.md — "BluCity must not register itself as a rig"), not a Convoy, and not merely a member of the BLU Mountain in the sense of "just another project." Treat BluCity as the platform Mountains' work runs on, not as portfolio content.

Canonical city

City Purpose Source authority
blucity Bluefly execution and orchestration city blueflyio/blu/blucity + blueflyio/blu/blucity-packs

Environment projections & Split Storage

A city has distinct storage and environment layers:

  • High-Churn Infrastructure (SQLite): Resides at <city>/.gc/store/ (and $WORKSPACE_ROOT/.gc/store/), isolating ephemeral execution state, session queues, and graph caches.
  • Durable Work Graph (Dolt): Relational/versioned store on the shared Dolt server for durable Beads tickets, decisions, and receipts.
  • On-Demand Rigs: Provisioned via gc rig add --git-url, avoiding permanent local checkouts of the full 136+ repository estate.
  • Runtime Authority: Oracle production is the sole production runtime authority; developer workstations use dynamic $WORKSPACE_ROOT/.gc/site.toml for task-scoped worktrees.
ORACLE_ONLY_RUNTIME = YES (CURRENT contract)
MAC = SOURCE / WORKTREE / GITLAB / CI ONLY

Required topology fields

Every city record should document:

  • city_name
  • source_repository
  • pack_root
  • required_rigs
  • required_pack_imports
  • beads_authority
  • dolt_endpoint_contract
  • environment_binding_strategy
  • self_bind_allowed = false unless explicitly justified
  • acceptance_formula
  • witness_claim_template

Native bind lifecycle (do not reinvent)

beads-topology.yaml (declarative)
  -> gitlab_components / gc-site-bind
  -> gc beads city use-external
       pins city to city_canonical + host/port/user on the shared Dolt
  -> gc rig set-endpoint --inherit
       each rig inherits the city endpoint (no rig-local Dolt)
  -> managed .beads/dolt-server.port mirrors reconciled/removed for city_canonical
  -> gc start
Layer Owner
Topology declaration BluCity
Projection gc-site-bind
Semantics Gas City
Host Dolt server IaC
High-churn storage SQLite at <city>/.gc/store

Forbidden substitutes: custom endpoint binders, custom metadata sync scripts, Mac gc start as Oracle proof.

BluCity current contract (MODEL_B)

Expected production work-graph authority:

  • endpoint: 127.0.0.1:3308
  • database: hq (city)
  • endpoint origin (live): city_canonical
  • BluCity must consume the external authoritative store rather than initialize a separate managed hq
  • managed_city means the city owns Dolt lifecycle (gc start / gc stop). It is not a "pre-bind portable source" synonym.
  • live Oracle bind is city_canonical (externally managed Dolt). Tracked Git managed_city on portable .beads/config.yaml is a packaging fact, not a redefinition of the upstream origin.
  • Workstation task environments connect against site-bound instances ($WORKSPACE_ROOT/.gc/site.toml).

Expected rig behavior:

  • portable city source declares required rigs in city.toml (identity only)
  • machine-local .gc/site.toml binds paths dynamically ($WORKSPACE_ROOT)
  • BluCity must not bind itself as a rig
  • clones/rigs use governed on-demand bootstrap (gc rig add --git-url)
  • each rig keeps a declared logical dolt_database (not flattened to hq)

Database provisioning vs endpoint bind (CURRENT)

Source: deploy/oracle/beads-topology.yaml comments in blueflyio/blu/blucity (release/v0.1.x). 14 external rigs declared (city HQ not counted as a rig).

Concern Status label Note
Shared endpoint bind (city_canonical @ :3308) PROVEN (tag v0.1.6 pipeline) gc-site-bind PASS
Rig endpoint inheritance PROVEN 14 rigs inherit
gc-site-bind dolt_database projection NOT YET Topology matrix is intent; site-bind does NOT currently project dolt_database values into rig metadata
Rig logical database availability OPEN DATABASE_NOT_FOUND observed for several scopes; per-rig .beads/metadata.json must match the canonical dolt_database
Topology name vs opened name OPEN MODEL_B long names in topology; some opens used short/prefix names (legacy)
blucity-packs schema / dirty dependencies OPEN (separate blocker) not a missing-DB class

Provisioning ownership (do not invent scripts):

EXISTING_LEDGER  -> Beads-native bootstrap/recovery (bd bootstrap --dry-run first)
NEW_SCOPE        -> Gas City/Beads native init on the shared server
Dolt             -> substrate, not topology authority

Runtime-state rule

This catalog records the contract, not transient live status.

Live counts, listener PIDs, incident state, and deployment acceptance belong in Fact Boards / Beads receipts / pipeline logs.