SIGN IN SIGN UP

engine: error catalog and the event stream

Adds the two things every later package depends on.

internal/errors makes catalog.yaml the single source of truth for the user
facing error surface: 69 codes across 15 areas, each with a cause, a next step
that names an action, a documentation slug, a retryable flag, and the exit code
it maps to. tools/errgen generates the Go constants and the reference page from
it, and validates the catalog on the way: codes must match their area, prose
must not use an em dash or tell the reader to contact support, and every exit
code must be in the published registry. Generated output is committed so a
contributor who skips the generator gets a red gate rather than silent drift.

internal/events is the single observability stream. The dashboard, the pull
request comment, JSON output, the NDJSON log, and the control plane are views
over it rather than five reporting paths that diverge. Events carry a monotonic
sequence per environment so consumers can detect a gap.

The load bearing property is that no sink can block the engine. Each sink gets
its own bounded queue and goroutine; a slow or dead one drops events and
increments a counter the dashboard shows. A preview environment that stalls
because a log file is on a full disk is a worse failure than a missing log
line, and the tests hold that line: twenty thousand emits into a permanently
stuck sink must all return.

Failure paths covered:
  a stuck sink blocks the engine: TestBus_EmitNeverBlocksOnAStuckSink
  a sink panics: TestBus_ASinkThatPanicsDoesNotTakeTheEngineWithIt
  a sink errors: TestBus_ASinkThatErrorsIsCountedNotPropagated
  duplicate sequence under contention: TestBus_ConcurrentEmittersAreSafe
  close discards queued events: TestBus_ClosingDrainsQueuedEvents
  the log volume disappears: TestFileSink_DisablesItselfWhenTheLogDirectoryDisappears
  a crash truncates the last line: TestReader_SkipsAMalformedTrailingLine
  rotated files replay out of order: TestFileSink_RotatesAndReplaysAcrossFilesOldestFirst
  an unknown error code panics: TestLookup_UnknownCodeDoesNotPanic
  a missing message field renders a hole: TestCoded_UnknownPlaceholderIsLeftVisible

Coverage: errors 100 percent, events 93.9 percent against a 90 percent floor.
Signed-off-by: Vir Sanghavi <Virrsanghavi@gmail.com>
V
Vir Sanghavi committed
7c292fcd58259acf9af88488850c142def726044
Parent: 01e62f1