feat(notifications): versioned notification contract and a delivery outbox

[arg1998]

First of the five notification PRs (N0 of the plan). It lays the foundations that Telegram, Discord and ntfy build on:

• a versioned message contract;
• producers that emit it;
• a delivery outbox in SQLite with retries and a circuit breaker;
• schema v5.

No external channel can be configured yet. With none configured, the only change you can see is that in-app notifications follow what they announce.

Before / after

Surface	Before	After
An attention request or vault confirmation you settle (or that times out, or is cancelled)	The notification kept reading "agent blocked, lease frozen" forever	Same row, same place in the list, with an outcome pill: resolved (green), expired, closed (cancelled). A toast still on screen closes.
A recovered degradation	Nothing	Its system.degraded notification moves to resolved
GET /api/v1/notifications, WS notifications	14 fields	+kind, category, severity, state, revision, thread. Additive; old fields and in-app behaviour unchanged.
Text copied into a notification (the agent's attention reason, page URL, error codes)	Stored verbatim	Goes through the Redactor (registered secrets and credential patterns); URLs lose their query strings. A real leak path is closed.
Delivery seam	NotificationChannel.send(dto), fire-and-forget, never called	Widened port (capabilities, send/edit/delete returning platform refs), the in-app inbox on it, a transactional outbox for external channels
Database	schema v4	schema v5 (0005-notification-outbox, compatible: true). Notifications gain 7 columns, backfilled from facts only; message_json stays NULL for old rows. New tables: notification_channels, notification_deliveries, notification_channel_messages.
browserhive purge on a database from an older schema	—	Skips the tables it does not have. It would otherwise have failed once v5 tables were listed.

How it works

• Contract (@browserhive/contracts/notifications, D-32):

  • NotificationMessage with schema: 1 and full-state revisions;
  • blocks built from a tiny inline AST, never markdown;
  • act and open actions;
  • entities and privacy;
  • snake_case on the wire (D-05).

  The JSON Schema is generated into docs/reference/notification-message.schema.json and checked by gen:docs --check.

• Producers (pure, table-driven):

  • Each draft carries kind, severity, state, thread and its message content.
  • revisionFor turns attention.resolved, vault.confirm.resolved and system.recovered into revisions of the thread's notification.
  • A growing tool-error group is a silent revision.
  • Nothing is ever authored by an agent.

• Pure steps:

  • scrubMessage (redaction, and clipping to the contract limits);
  • restrictContent (counts < titles < full);
  • degrade(message, capabilities): tables → lists, images dropped or linked, act → open fallback, button cap, plain text, truncation with "… Open in BrowserHive";
  • routing: categories, minimum severity, session globs, harness, quiet hours in an IANA zone (DST-safe), TTL.

• Outbox (D-34): a notification change and its notification_deliveries rows commit in one transaction. NotificationOutbox drains them:

  • Coalescing: a job renders the current state, and older revisions become superseded.
  • Edits are spaced at least 3 s apart.
  • Retries use exponential backoff with jitter and honour retry_after. A job is dead after 8 attempts or 24 h.
  • Jobs left sending are recovered at start.
  • The circuit breaker opens after 5 consecutive failures. It sets the channel to broken and produces an in-app-only channel.broken notification. There is no degradation: the loop is cut by kind, and a test proves it.
  • Backlog collapse: more than 20 pending info sends become the newest one, with a "you missed N" note.
  • A TTL sweeper over expires_at.
  • The worker runs, and arms its timer, only while a channel exists.

• Registry: ChannelRegistry merges dashboard rows with startup channels. Startup channels are projected read-only, and a name clash is CONFIG_INVALID. It builds adapters through per-kind factories, and none are registered yet. Secrets are env var names only.

• Startup catch-up: a request settled while nothing listened (orphan recovery at start, or a shutdown) revises its notification after the reconcile. I found this gap during real verification.

• OTel:

  • browserhive.notifications.deliveries{channel_kind,status};
  • a notification.deliver span per platform call.

Spec (committed first)

• D-16 and D-25 are rewritten.
• New decisions D-32 to D-39, each with an Implementation line (N0/N1/N2):
  • contract ownership and versioning; agents never author notifications;
  • no hosted infrastructure, bring your own credentials, secrets as env names only;
  • outbox semantics;
  • TTL performed by BrowserHive, with the Telegram 48 h note;
  • screenshots opt-in, vault screenshots before the fill;
  • publicUrl;
  • Discord webhook or bot;
  • startup channels CLI-only and read-only.
• Spec 03: §4.8/§6.6, §7 (v5 DDL, backfill, retention classes, ports), §9 rewritten (producer table, contract, channels and registry, outbox). The reserved-table list no longer names notification_channels.
• Other specs:
  • 01: seams;
  • 02: no notify tool;
  • 04: outcome pill, toast close;
  • 05: layer placement;
  • 08 §5.7: the --notificationChannel flag-only grammar, specified for N1;
  • 09: tests;
  • 10: span, metric, redaction, no degradation for channels.

Verification

• Local gate:
  • bun run check: exit 0. 2763 server tests and 344 dashboard tests; openapi, docs and db-types are fresh.
  • test:goldens, build and package:check: exit 0.
  • test:integration: 67 pass.
  • e2e, replicated as in CI: 9 passed, 1 skipped.
• New suites:
  • message/producers;
  • degrade + content levels;
  • routing (quiet hours across DST);
  • outbox (19 cases, including the loop test);
  • registry;
  • service revisions and the startup catch-up;
  • redaction property: a seeded generator, 1 000 cases. It checks that a registered sentinel never reaches message_json, the in-app row or payload, the channel delivery or the delivery log. It found a real bug: an oversized field made the contract parse throw and would have lost the notification. That is fixed by clipping, plus a safe fallback.
  • v4→v5 migration backfill, compatibility-window reads and CHECKs;
  • a conformance suite run against both the SQLite repositories and the in-memory doubles;
  • the full path on real SQLite;
  • retention of outbox history.
• Real run (scratch data dir, port 9951):
  1. origin/main (0.1.3, schema v4), built in a second worktree, produced real notifications over MCP: two tool-error groups, attention requests resolved or rejected from the REST API, and one cancelled.
  2. The v5 build on the same dir wrote the v4 backup and migrated 4 → 5.
  3. The backfill, read back read-only:
     • resolved/rejected requests → resolved;
     • the cancelled one → final;
     • tool groups → open, with thread tool-errors:<session>;
     • message_json NULL.
  4. The dashboard renders the old rows with pills.
  5. New traffic on v5 (every row read back from the DB):
     • a tool-error group ends at revision 3, with a silent message rev 3;
     • an attention request is resolved → rev 2, resolved, "Resolved by admin after 2 s", no actions;
     • 2 lease reaps (--sessionLease 1m) → session.reaped;
     • no notification_deliveries rows while no channel exists.
  6. I killed the daemon with an attention request pending and restarted it. The orphan recovery rejected the request, then notifications caught up revised=1 moved the notification to rev 2, resolved, "Rejected after 55 s".
  7. I added two channel rows to the stopped scratch DB (a telegram channel with no adapter yet, and a paused discord channel) and generated errors. Every change wrote outbox rows in the same transaction: send/edit jobs, suppressed with no_adapter or channel_paused.
  8. purge --dryRun of the v4 backup with the v5 binary lists its tables without error.
• Screenshots: the Notifications page and the bell at 1440 and 768 px, light and dark, after the migration and after the new traffic. I reviewed them all: outcome pills, closed for the cancelled request, nothing for crashes or open rows.

Known and not done

• macOS and Windows integration are known-failing (macOS: integration tests are flaky (timeouts, then Chromium killed) #23, Windows: integration failures #2); I did not investigate them here.
• No platform adapter, publicUrl, channels page or --notificationChannel parser: those are N1. The flag is fully specified in spec 08 §5.7.
• Act buttons are carried in the contract, but nothing executes them until N2 (command tokens).

Follow-ups for N1

• Adapters: Telegram, Discord webhook, ntfy, webhook. Register one factory per kind in buildOps({ channelFactories }).
• publicUrl through the LinkBuilder port.
• The --notificationChannel parser, handing StartupNotificationChannel[] to ChannelRegistry.load().
• The channel API and the dashboard page.
• Screenshots.
• notify-live.yml.

The handoff document lists every seam.

Contract change: schema v5 (migration 0005-notification-outbox, compatible: true, so min_reader_version stays 1); fixture v5.db, golden schema-v5.json; v1–v4.db still upgrade to head and match a fresh install. OpenAPI: Notification gains 6 required response fields (additive). New public JSON Schema docs/reference/notification-message.schema.json (NotificationMessage schema 1), and a new contracts subpath @browserhive/contracts/notifications. WS payloads: the same 6 fields on notification.*. The MCP tool surface is unchanged.