Skip to content

ADR-0022: Bluefly Runtime Architecture — Gas City as Foundation

Renumbered 2026-08-05 (hq-90y.2.1): originally filed as adr-0001-bluefly-runtime-gas-city-foundation.md, which collided with the pre-existing, unrelated ADR-0001-establish-governance-repo.md (Status: Superseded, superseded by ADR-0006). Content and decision unchanged — identity only.

Field Value
Status Accepted
Date 2026-07-17
Author Thomas Scola
Approver Thomas Scola
Scope Platform-wide — all Bluefly runtime code

Context

Bluefly.io builds an agent platform that orchestrates AI workloads across Drupal, Kubernetes, Docker, and bare-metal infrastructure. The platform requires a composable runtime that can manage agents, sessions, orders, and event-driven workflows without coupling to any single operational model.

Gas City is a full-stack operational application originally built to demonstrate orchestration patterns. Gas City is the SDK extracted from Gas City — the reusable orchestration substrate that encodes the core primitives without the opinionated role taxonomy or workflow conventions.

Early Bluefly documentation described Gas City as the "architectural parent" of the platform. This was incorrect. Gas City is a sibling application, not a dependency. Both Gas City and Bluefly are consumers of Gas City.

This ADR corrects the architectural record and establishes the permanent layering.

Decision

Bluefly adopts Gas City as the foundational orchestration SDK.

Gas City is treated as an optional imported pack that provides one opinionated operational model. Bluefly does not depend on Gas City, inherit its role taxonomy, or require its conventions.

Layering

┌─────────────────────────────────────┐
│         Bluefly Products            │
│  (OSSA, DUADP, ContractPlane, …)   │
└──────────────┬──────────────────────┘
               │
┌──────────────▼──────────────────────┐
│      Bluefly Platform Model         │
│  (Missions, Factories, Capabilities,│
│   Deployments, Workers, Authorities,│
│   Governance)                       │
└──────────────┬──────────────────────┘
               │  compiles to
┌──────────────▼──────────────────────┐
│          Gas City SDK               │
│  (Packs, Agents, Orders, Formulas,  │
│   Sessions, Beads, Events)          │
└──────────────┬──────────────────────┘
               │
┌──────────────▼──────────────────────┐
│  OpenClaw / Nexu / Providers /      │
│  Controller                         │
└──────────────┬──────────────────────┘
               │
┌──────────────▼──────────────────────┐
│  Docker / Kubernetes / tmux / SSH   │
└─────────────────────────────────────┘

Gas City exists alongside this stack as a peer consumer of Gas City:

┌─────────────────────┐
│   GasCity Pack      │
└─────────┬───────────┘
          │
┌─────────▼───────────┐
│    Gas City SDK     │
└─────────────────────┘

Gas City is not above Gas City. It is not a required intermediary.

Consequences

Domain Model Compilation

Bluefly defines its own domain model. These domain concepts compile into Gas City primitives — they do not inherit from or extend Gas City conventions.

Bluefly Domain Concept Compiles To (Gas City Primitive)
Mission Pack
Factory Agent (with Orders)
Capability Formula
Deployment Session
Worker Agent
Authority (governance layer, no direct primitive)
Governance (policy layer, no direct primitive)

SDK Infrastructure vs. Pack Conventions

The following components belong to the Gas City SDK layer — they are infrastructure, not Gas City workflow:

  • Controller: Owns SDK infrastructure behavior (session lifecycle, event routing, provider management). The Controller is a Gas City concept.
  • OpenClaw: Execution engine, gateways, remote workers, networking, capabilities, transports. OpenClaw is infrastructure — it is not Gas City workflow.
  • Nexu: Must ask "Which Pack am I executing?" — not "Am I a Polecat?" Nexu dispatches to packs generically; it does not hardcode Gas City roles.
  • Providers: Pluggable capability backends. SDK infrastructure.

The following are Gas City pack conventions, not SDK concepts:

  • Mayor, Polecat, Deacon: Role taxonomy specific to Gas City's operational model. Bluefly does not use these roles.
  • Gas City workflow patterns: Opinionated sequences defined by the Gas City pack. Bluefly defines its own workflows.

What Changes

  1. Code that references Gas City roles must not appear in Bluefly platform modules. If a Bluefly module references Mayor, Polecat, or Deacon, it is coupled to the wrong layer.
  2. Bluefly products compile to Gas City, never to Gas City. The compilation target is Packs, Agents, Orders, Formulas, Sessions, Beads, Events — not Gas City's workflow graph.
  3. Gas City may be imported as a pack for demonstrations, reference implementations, or backward compatibility. It is never a required dependency.
  4. Documentation must reflect the correct layering. Any document that describes Gas City as Bluefly's "parent," "foundation," or "control plane" is incorrect and must be updated.

What Does Not Change

  • Gas City SDK remains the orchestration substrate. Its primitives are stable.
  • OpenClaw remains the infrastructure layer beneath Gas City.
  • Bluefly's higher-level products (OSSA, DUADP, ContractPlane) remain above the Bluefly Platform Model.

Compliance

All new Bluefly runtime code must:

  1. Import from gas-city SDK packages, not from gas-town pack packages.
  2. Define domain concepts in Bluefly's own model (Mission, Factory, Capability, etc.).
  3. Compile those concepts to Gas City primitives at the boundary.
  4. Never hardcode Gas City role names (Mayor, Polecat, Deacon) in platform-level code.

Existing code that violates these rules must be identified and migrated. See the terminology migration list (companion document).

References

  • Gas City SDK upstream documentation (gascityhall)
  • Bluefly Constitution (Factory Operating Model)
  • Workstream 0: Repository Authority Convergence
  • ADR-0023: Repository Authority Model

Amendment — ADR-0026 Scope Clarification

Effective: ADR-0026 acceptance
Amended by: Thomas Scola, 2026-09-04
Does not change: platform-code prohibition (lines under "SDK Infrastructure vs. Pack Conventions" remain fully in force)

The prohibition on Gas City role names in "Consequences → SDK Infrastructure vs. Pack Conventions" applies to Bluefly-authored platform/SDK code — including Bluefly-authored packs, modules, libraries, and product code. Platform code must not hardcode or depend on Gas City role names. It does not prohibit importing the official upstream Gas City pack as deployment configuration.

It does not prohibit a Bluefly-operated city from importing and configuring the official upstream Gas City pack. When a city imports that pack, the resulting configured agents (Mayor, Witness, Refinery, Deacon, Polecat) are Gas City configuration, not a Gas City runtime. Seeing those role names in city.toml, pack.toml, or a Gas City agent session is correct and expected.

The semantic distinction this amendment makes explicit:

Layer Gas City role names Status
Bluefly platform/SDK code Must not appear Unchanged — still prohibited
City deployment configuration May appear as imported pack config Permitted — see ADR-0026

Seeing gt, a Gas City store, a Gas City supervisor, or path-derived identity (~/gt/…) at runtime is a defect. Seeing a configured mayor or polecat session in a Gas City city is not.

See ADR-0026 for the full decision.