​

Event Bus

Last verified against code: 2026-03-01

​

Summary

​

Key Concepts

• Event: A single immutable record of something that happened. Struct with Seq (monotonically increasing uint64), Type (dotted string like bead.created), Ts (time.Time), Actor (who did it), Subject (what was affected), Message (human-readable description), and Payload (optional json.RawMessage for structured data). Defined in internal/events/events.go.
• Provider: The full read/write interface for event backends. Embeds Recorder for writing and adds List, LatestSeq, Watch, and Close. Implementations: FileRecorder (built-in JSONL file), Fake (in-memory test double), FailFake (error-returning test double), and exec.Provider (user-supplied script). Defined in internal/events/events.go.
• Recorder: The write-only sub-interface. Contains a single method Record(Event) that is best-effort: errors are logged to stderr, never returned to callers. Used by subsystems that only need to emit events. Defined in internal/events/events.go.
• Watcher: A cursor that yields events one at a time. Created by Provider.Watch(ctx, afterSeq). Blocks on Next() until a new event arrives, the context is canceled, or the watcher is closed. Defined in internal/events/events.go.
• Filter: A query predicate for List and ReadFiltered. Supports filtering by Type (exact match), Actor (exact match), Since (time.Time lower bound), and AfterSeq (uint64 sequence cursor). Zero-valued fields are ignored. Multiple non-zero fields are ANDed. Defined in internal/events/reader.go.
• Discard: A sentinel Recorder that silently drops all events. Used when event recording is unwanted (e.g., certain test scenarios). Defined in internal/events/events.go.

​

Architecture

                     events.Provider (interface)
                    /        |          \
                   /         |           \
           FileRecorder    Fake        exec.Provider
          (JSONL file)   (in-memory)  (user script)

  Recorder (sub-interface: write-only)
      |
  Discard (no-op sentinel)

1. GC_EVENTS env var (highest priority)
2. [events].provider in city.toml
3. Default: file-backed JSONL at .gc/events.jsonl

​

Data Flow

Record(Event{Type, Actor, Subject, Message, Payload})
  --> provider assigns Seq (monotonically increasing)
  --> provider fills Ts if zero (time.Now())
  --> provider writes one JSON line to .gc/events.jsonl (FileRecorder)
  --> errors logged to stderr, never returned (best-effort)

List(Filter{Type, Actor, Since, AfterSeq})
  --> reads all events from .gc/events.jsonl
  --> applies filter predicates (AND semantics)
  --> returns matching events as []Event

LatestSeq()
  --> scans file for highest Seq value
  --> returns 0 if empty or missing

Watch(ctx, afterSeq)
  --> returns a Watcher positioned after afterSeq
  --> Watcher.Next() blocks until new event arrives
  --> context cancellation unblocks Next() with ctx.Err()

Watch(ctx, afterSeq=5)
  --> creates fileWatcher{path, afterSeq=5, poll=250ms}

Next() loop:
  1. Drain internal buffer (previously fetched events)
  2. Check context (return ctx.Err() if canceled)
  3. ReadFrom(path, byteOffset) to get new events since last read
  4. Filter to events with Seq > afterSeq
  5. Buffer matching events, drain on next iteration
  6. If no new events, sleep 250ms and retry

Watch(ctx, afterSeq=5)
  --> creates fakeWatcher{fake, afterSeq=5, ctx}

Next() loop:
  1. Scan in-memory Events slice under mutex
  2. Return first event with Seq > afterSeq
  3. If none found, block on select:
     - ctx.Done() --> return ctx.Err()
     - fake.notify channel --> new event recorded, retry

​

Key Types

• Event (internal/events/events.go) — The immutable event record. JSON-tagged for JSONL serialization. Payload uses json.RawMessage for arbitrary structured data and is omitted from JSON output when nil.
• Provider (internal/events/events.go) — The full read/write interface. Embeds Recorder and adds List, LatestSeq, Watch, Close.
• Recorder (internal/events/events.go) — The write-only sub-interface. Single method Record(Event) with best-effort semantics.
• Filter (internal/events/reader.go) — Query predicate for List and ReadFiltered. Zero values are ignored; non-zero fields are ANDed.
• FileRecorder (internal/events/recorder.go) — Production implementation. Appends JSONL to .gc/events.jsonl with O_APPEND for cross-process safety and a sync.Mutex for in-process serialization.

​

Invariants

1. Seq is monotonically increasing. For any two events recorded by the same provider, the later event has a strictly greater Seq.
2. Seq is unique. No two events share the same Seq value, even under concurrent recording.
3. Seq is auto-filled by the provider. Callers do not set Seq; the provider assigns it on Record.
4. Ts is auto-filled when zero. If the caller provides a zero Ts, the provider fills it with the current time. An explicit non-zero Ts is preserved.
5. Record is best-effort. Recording errors are logged to stderr but never returned to callers. The caller’s operation must not fail because event recording failed.
6. Events are immutable once recorded. There is no Update or Delete operation. The append-only log only grows.
7. List with empty Filter returns all events. A zero-valued Filter matches everything.
8. Filter fields are ANDed. When multiple Filter fields are non-zero, an event must match all of them to be included.
9. LatestSeq returns 0 for an empty provider. Missing file, empty file, or no events all return (0, nil).
10. Watch(ctx, afterSeq) yields only events with Seq > afterSeq. Existing events at or before afterSeq are never returned.
11. Watch.Next() blocks until an event arrives or the context is canceled. Context cancellation returns context.Canceled or context.DeadlineExceeded.
12. Malformed lines are skipped. ReadAll, ReadFiltered, and ReadFrom silently skip lines that fail JSON unmarshalling. This handles partial writes from crashes.
13. Missing file returns nil, not error. ReadAll and ReadLatestSeq return (nil, nil) and (0, nil) respectively for nonexistent files.
14. FileRecorder resumes Seq across restarts. NewFileRecorder scans the existing file to find the maximum Seq, so new events continue monotonically even after a process restart.
15. Payload is omitted from JSON when nil. The omitempty tag ensures events without payloads produce compact JSON lines.

​

Interactions

​

Code Map

​

Event Type Constants

​

Configuration

[events]
provider = ""   # "" (default: file JSONL), "fake", "fail", or "exec:/path/to/script"

​

Storage Format

{"seq":1,"type":"controller.started","ts":"2026-03-01T10:00:00Z","actor":"gc"}
{"seq":2,"type":"agent.started","ts":"2026-03-01T10:00:01Z","actor":"gc","subject":"worker-1","message":"agent started successfully"}
{"seq":3,"type":"bead.created","ts":"2026-03-01T10:00:05Z","actor":"human","subject":"gc-42","payload":{"title":"Fix bug","labels":["urgent"]}}

• Append-only writes — new events are appended without reading or rewriting the file
• Crash resilience — partial writes (truncated last line) are skipped by readers
• Incremental reads — ReadFrom(path, byteOffset) reads only new data from a known position
• Cross-process safety — O_APPEND flag ensures atomic appends at the OS level

​

Exec Provider Wire Protocol

​

Testing

​

Known Limitations

• FileRecorder Watch uses polling, not inotify. The fileWatcher polls the JSONL file every 250ms via ReadFrom. This adds up to 250ms latency for event delivery and uses CPU for polling. A future optimization could use fsnotify to wake on file changes. The Fake provider uses channel-based notification for zero-latency delivery in tests.
• No event retention or rotation. The JSONL file grows without bound. There is no built-in log rotation, retention policy, or compaction. For long-running cities, manual truncation or external log rotation is needed.
• ReadFiltered scans the entire file. Every List call reads all events from disk and filters in memory. There are no indexes. This is acceptable at current scale but will degrade with very large event logs. ReadFrom with byte offsets provides incremental reading for the Watch path.
• No event schema validation. Event types are string constants with no runtime validation. Recording an event with a misspelled type succeeds silently.
• Filter does not support Subject. The Filter struct supports Type, Actor, Since, and AfterSeq but not Subject. Filtering by subject requires post-filtering in the caller.
• Exec provider Watch is subprocess-lifetime-bound. The exec watcher reads from a long-running subprocess’s stdout. If the subprocess exits, the watcher reports an error rather than reconnecting.

​

See Also

• Architecture glossary — authoritative definitions of event bus, order, gate, and other terms used in this document
• Health Patrol architecture — how the controller reconciliation loop records agent lifecycle events on every tick
• Bead Store architecture — the other Layer 0-1 primitive; events and beads together provide persistence + observation
• Config architecture — how [events].provider is resolved and how progressive activation works
• TESTING.md — testing philosophy and tier boundaries for the conformance suite approach
• CLAUDE.md — design principles including “Event Bus is the universal observation substrate” (layering invariant 3)