Skip to content
oto
Menu
Overview
IntroductionConceptsArchitectureContributingReleasing
Design
oto — System Design ProposalDomain Research: Prometheus Alertmanager + Slackoto — Red-Team Memooto — SCOPE BOUNDARY (the doctrine)oto — BINDING SPECIFICATION v1
ADRs
0001 — PostgreSQL is the sole datastore; River is the job queue0002 — `internal/<domain>/{api,service,repository,domain}` with three model sets0003 — Alert, AlertOccurrence and AlertEvent are three distinct entities0004 — oto owns alert identity; Alertmanager's fingerprint is recomputed, not trusted0005 — A durable group key, and the AlertGroup generation owns the Slack thread0006 — The Alertmanager API v2 reconciler is mandatory, not optional0007 — Webhook response contract: 202 or 503. Never 4xx, never 429.0008 — Slack: `chat.update` in place is primary; threads are secondary; one colour attachment0009 — Rule definitions are snapshotted and versioned at fire time0010 — Server-Sent Events with durable resume, not WebSocket0011 — Validation is seven layers with two opposite trust models0012 — Pastel product chrome, saturated colour reserved exclusively for state0013 — oto is alert-first: the Flight Recorder Test defines the scope boundary0014 — Postgres is the only store; no TSDB or column store in v10015 — No stream processor; River in Postgres is the pipeline0016 — Cluster context arrives via MCP, on demand; never the Kubernetes event firehose0017 — Alertmanager-style matchers, not CEL; and a filter AST that keeps the door open0018 — Slack distribution: a customer-built internal app, credentials in config0019 — MIT licence0020 — Broadcast the transitions that must be seen0021 — Correctness and testing strategy0022 — Length-prefixed identity pre-images0023 — Terminal thread states are decided first, and the send is three phases0024 — Retention defaults, what each boundary destroys, and cold storage0025 — The alert list resolves rule snapshots in a batch, not per row0026 — `refire_grace` and the flap thresholds, derived from a real rule corpus0027 — Delivery drills: a synthetic alert through the real pipeline, and the mark that keeps it out of the numbers0028 — Non-urgency motion: one-shot events, honest activity loops, and nothing else0029 — Type and radius scales, read off the product rather than drawn for it0030 — Tier A repainted as Washi & Ink / Konshi Sutra; accent moves to beni0031 — Sharp corners and higher-contrast grid lines within Washi & Ink; colours unchanged0032 — Dark-theme accent moves from beni to plum-blossom blue-and-white; light untouched0033 — The alert filters are a toolbar above the table, not a panel in the rail0034 — Notifications is a destination, and the record it keeps is readable0035 — Decorative ink as a masked wash: one primitive, four motifs, and the placements it is refused0036 — AlertOccurrence becomes AlertCase, and `case` is argued against FR-1 by name0037 — A Wording is Liquid, and the structure around it stays oto's0038 — The group key is derived from the alert's own labels0039 — Group close stays activity-driven0040 — A Case is `open` or `closed`, and it is never reopened0041 — The Alert/Case allocation, and the one rule that decides it0042 — Storm damping is removed, because the defence was built before its object0043 — The Slack action row renders five elements, and the fifth is the snooze pair0044 — A count condition is a silence the operator asked for, and `below_threshold` is how oto says so0045 — A Case is a conversation, and one Slack thread per alert is the accepted cost0046 — Corners round again: ADR 0031's radius override is reversed0047 — A channel answers to a connection, and Slack gets two scopes back0048 — A Wording is spelled by its channel, and the marks in between are oto's0049 — A Wording is selected by its own clause, not by a route0050 — A NotificationTemplate is one whole message, and its policy says which one0051 — A `raw` template owns the whole message, and a template may carry its replies0052 — An Incident is drawn over Cases, and its response is handed off0053 — An Investigator reads, proposes, and never decides delivery0054 — A Remedy earns the write path0055 — An incident-tool integration is data or a bridge, never code inside oto0056 — A Case the upstream stopped speaking about expires, and says why
Setup
Configuration referenceReaching an incident tool: the envelope, a mapping, or a bridgeInvestigatorsRemediesConnecting oto to SlackThe live Slack verification runTuning otoConnecting oto to VictoriaMetrics (vmalert)The generic webhook and `oto.notification.v1`
Runbooks
oto runbooksAlert search — optional partial/substring matching on alert namesoto_clock_skew_secondsoto_delivery_claim_lost_totaloto_ingest_accepted_totaloto_ingest_alerts_totaloto_ingest_duplicate_totaloto_ingest_duration_secondsoto_ingest_fingerprint_mismatch_totaloto_ingest_process_duration_secondsoto_ingest_rejected_totaloto_ingest_shed_totaloto_job_duration_secondsoto_job_queue_depthoto_jobs_dead_totaloto_jobs_enqueued_totaloto_jobs_failed_totaloto_jobs_panics_totaloto_jobs_snoozed_totaloto_jobs_started_totaloto_jobs_succeeded_totaloto_jobs_unknown_version_totaloto_render_invalid_totaloto_slack_unknown_action_totaloto_stream_connectionsoto_stream_events_coalesced_totaloto_stream_events_dropped_totaloto_stream_events_fetched_totaloto_stream_events_published_totaloto_stream_fetch_errors_totaloto_stream_listener_reconnects_totaloto_stream_notify_malformed_totaloto_stream_notify_received_totaloto_stream_poll_recovered_totaloto_stream_resync_totaloto_thread_gap_recovered_totaloto_thread_head_wait_secondsoto_thread_order_decisions_total

0032 — Dark-theme accent moves from beni to plum-blossom blue-and-white; light untouched

Status: Accepted · 2026-08-16 · amends the dark-theme accent clause of ADR 0030; the light theme’s beni crimson-pink, both themes’ neutrals, and every Tier B token are unchanged

Context

Section titled “Context”

The owner asked for the dark theme’s accent to move from beni crimson-pink to a “plum blossom blue and white” combination — the sometsuke (blue-and-white porcelain) register: white ume blossoms against a deep indigo ground, which is also literally what Konshi Sutra’s dark background already is. Scoped to dark only; Washi & Ink’s light-theme beni accent (#B5305C) is untouched.

This is the same kind of decision ADR 0012 and ADR 0030 made — pick a hue for the scarce Tier A accent — with a materially worse hand of cards. ADR 0012’s periwinkle and ADR 0030’s beni both landed ≥25° from every Tier B state hue. A genuine blue accent cannot: Tier B already owns both ends of the blue lane — info at ~214° and suppressed at ~252° — leaving only a 41°-wide gap between them. The best a blue accent can do is sit at the midpoint, ~233°, which is ~19° from each neighbour. Every other accent this system has shipped cleared ≥25°; this one cannot, because the colour family the owner asked for is the one Tier B has boxed in on both sides.

Decision

Section titled “Decision”

Dark accent moves to #949DE0, hue ~233°, accepting the ~19° gap as a deliberate, documented exception rather than reopening the request. -hover moves to #CDD4EA — pale, low-chroma, the “white” half of the combination, so hovering an accent element visibly pales toward blossom-white rather than just darkening/lightening the same hue. -fill (#141734) and -border (#465291) are a dark blue wash and a mid blue-white border, for badge-style and outlined uses of the accent. --oto-focus follows --oto-accent, as it always has.

Both measured pairs clear their 4.5:1 obligation with a normal margin — --oto-accent on --oto-surface is 5.7:1, --oto-text-inverse on --oto-accent is 6.5:1 — comparable to every prior accent’s margin. The risk here is not contrast; it is that a user can, at a glance, mistake the accent for the info or suppressed state badge, which is exactly the harm ADR 0012’s “chrome never uses a state hue” rule exists to prevent. Two things limit that risk in practice: info and suppressed are always rendered as a four-token badge (fill + border + text + icon, per §M.2), never as a bare swatch, so context disambiguates them from an accent used on a link, button or focus ring; and U1 already requires state to carry ≥2 non-colour channels (icon, text label), so no state reading depends on colour alone.

Light theme is unaffected: --oto-accent stays #B5305C (beni), because the owner’s request and the reasoning above are dark-only.

Consequences

Section titled “Consequences”
  • --oto-accent/-hover/-fill/-border/-focus change in the dark theme only. Light theme, both themes’ neutrals, all Tier B state tokens, and the chart ramp are byte-identical to what ADR 0030 and ADR 0031 shipped.
  • §M.5’s two measured accent rows were recomputed against the new hex and both still clear 4.5:1. contrast.test.ts and tokens.test.ts were run green before this landed.
  • This is the first accent in the system’s history shipped with a hue gap tighter than 25° from a Tier B state. That is a conscious exception, not a new precedent — the next accent change should not treat ~19° as an acceptable target, only as what a “true blue” costs specifically, given where info and suppressed already sit.
  • If the info/suppressed badge-vs-accent ambiguity turns out to matter in practice (an axe/user report, not a hypothetical), the cheapest fix is moving info’s hue rather than the accent’s — but that is a Tier B change gated by its own contrast obligations and is out of scope here.

Alternatives rejected

Section titled “Alternatives rejected”
  • A teal/cyan accent (~180°), as ADR 0031’s reverted first pass used. Would have cleared ≥30° from every state hue, comfortably inside precedent — but is not blue, and does not read as sometsuke plum-blossom blue-and-white, which is what was asked for.
  • Push the hue further from info toward suppressed, or vice versa. Rejected: 233° is the midpoint and therefore already the best available compromise; moving either direction only trades one collision risk for the other, worse.
  • Desaturate toward an achromatic blue-gray to reduce collision risk. Rejected: a properly desaturated “blue” reads as slate, not as sometsuke cobalt — it would solve the hue-adjacency problem by quietly deleting the colour the owner asked to see.