Skip to content

Gas City Events Catalog

Purpose: Define the canonical event vocabulary used by Bluefly orchestration within the Gas City 1.4.x supervisor loop.

Upstream: Events reference, Split storage classes

Events represent facts that occurred. They do not contain implementation logic and should not themselves perform remediation.

Taxonomy note: events are cataloged per platform vocabulary, not per Mountain — Mountain/Product/Convoy are separate Bluefly portfolio taxonomy layered on top of Gas City primitives; see gc-catalog.md.

Events are emitted during execution, indexed into high-churn SQLite (<city>/.gc/store/) and OpenTelemetry (gascity-otel), and consumed by Orders (trigger type event) and Formulas (fan-in/fan-out coordination). See gc-orders.md for the event trigger type.

Event field contract

Every event should carry:

Field Purpose
type Namespaced event name (e.g. bead.closed)
id Unique event identifier
timestamp ISO-8601 UTC
source Rig, city, or external system that produced the event
environment production, staging, ci, etc.
correlation_id Links related events across a workflow or incident

GitLab / delivery events

  • gitlab.mr.opened
  • gitlab.mr.updated
  • gitlab.mr.merged
  • gitlab.pipeline.failed
  • gitlab.pipeline.succeeded
  • gitlab.release.tagged
  • deploy.started
  • deploy.completed
  • deploy.failed

Runtime events

  • runtime.unhealthy
  • runtime.recovered
  • service.restart_loop_detected
  • disk.headroom_low
  • city.binding_drifted
  • pack.lock_drifted

Beads / work events

  • bead.created
  • bead.ready
  • bead.claimed
  • bead.blocked
  • bead.closed
  • handoff.created
  • human.approval_required

Session / agent lifecycle events

  • session.started
  • session.stopped
  • session.crashed
  • agent.idle (session pool below min_active_sessions threshold)
  • agent.pool_scaled

Durability events

  • backup.completed
  • backup.failed
  • backup.restore_verified
  • backup.restore_failed

Security / network events

  • security.finding
  • cloudflare.drift_detected
  • certificate.expiring
  • origin.exposure_detected

Composition events

  • pack.updated
  • formula.updated
  • agent.updated
  • rig.added
  • rig.removed
  • catalog.drift_detected

Event & Dispatch Flow

EVENT / TRIGGER
  -> ORDER (event cursor / cron / cooldown)
  -> FORMULA (DAG compilation)
  -> gc sling <agent> <bead>
  -> AGENT / POOL (5-axis execution)
  -> BEAD / RECEIPT (committed to Dolt)

Rules

  • Events must be immutable observations.
  • Events should carry identity, timestamp, environment, source, and correlation identifiers.
  • A remediation request is a bead/order, not an event.
  • Avoid product-specific event names when a stable platform event exists.
  • Do not catalog transient incident identifiers as event types.
  • No personal home paths or workstation absolute paths in this catalog (use $WORKSPACE_ROOT).