feat(notifications): an in-app inbox for mentions, replies, tasks and shares by christianhuening · Pull Request #23 · opendefensecloud/knot

christianhuening · 2026-09-07T16:51:33Z

An @mention in a comment used to fire a pg_notify('comment_mentions', …) that no process in the codebase ever listened for, into an MSG_MENTION WebSocket frame the frontend had reserved and never received. Mentioning a colleague did nothing they would ever see, and KnotProvider.ts had said so in a comment since June.

Five events now write to a notifications table, read through an Inbox in the sidebar with an unread badge, a dropdown, and a /notifications page: mentions, replies in threads you're part of, task assignment, overdue tasks, and documents shared with you.

Design notes

Delivery is a 30-second poll, plus refetch on window focus. Deliberately no push channel: an inbox has to reach you when you have no document open, and the doc WebSocket is keyed by doc_id, so it can't. The reserved MSG_MENTION plumbing is deleted rather than completed. SSE can replace polling later behind the same API and schema.
Idempotency is a unique index on (user_id, dedupe_key) with ON CONFLICT DO NOTHING, not application logic. That's what lets the overdue sweep run on every replica with no leader election.
task_assigned's dedupe key is content-addressed (sha256(text)), because doc_tasks.id is "<doc_id>:<item_index>" and every reindex rewrites it — an id-keyed notification would re-fire for every assignee each time anyone reordered a checklist.
The table is an outbox. emailed_at exists and nothing writes it, so an email transport can be added without a migration.
Reads re-check ACLs. A notification can outlive access to its document; the list handler re-checks effective_role and filters, never 403s.

Also fixed

Members whose display name contains a space could never be mentioned in a comment. The server matched @(\w+) against display names, so @Christian Hüning captured Christian, matched nobody, and silently notified no one. The picker now sends the user ids it resolved, unioned with the regex fallback for names typed by hand. The comment edit path is not covered — it has no picker.

Accepted limitations (documented in the spec)

Self-assignment isn't suppressed when you assign yourself a task by typing. The guard needs an actor and the live-edit path has none: WS updates persist with by_user_id: None and the reindex channel carries only a document id. Threading identity through the collaborative hot path wouldn't clearly be correct anyway — under co-editing, several people may have edited between reindexes.
Two checklist items with identical text assigned to the same person notify once, a direct consequence of content-addressing. Both still appear on /tasks.

Known follow-ups, not addressed here

Editing an assigned checklist item spams its assignee. The reindexer flushes every 2s, so each intermediate text hashes to a fresh key and emits a fresh unread row — roughly 15 notifications for 30s of rewording. Pre-existing, but exempting task_assigned from retention (needed to stop pruning resurrecting old assignments) removed the ceiling that bounded it. Worth fixing before this reaches users.
The sweep's 7-day floor has no test — deleting the line leaves all four sweep tests green.
Spec §2's key table says <due date> for task_due where the code binds the sweep date; §4's prose is right.
The seed migration covers unchecked tasks only, so re-opening a task that was checked at upgrade emits one stale notification.

Upgrade safety

A second migration adds a CHECK on kind and pre-seeds already-read task_assigned dedupe rows for currently-assigned tasks, so an existing deployment doesn't get a burst covering its entire historical backlog on first reindex. The SQL and Rust dedupe keys were verified byte-identical against live Postgres 18, including 2-, 3- and 4-byte UTF-8.

Testing

cargo nextest 373/373 · clippy -D warnings · cargo fmt --check · tsc · eslint · vitest 169/169. New e2e notifications.spec.ts passes: it mentions "Mara Jade", a name the server's regex physically cannot resolve, so the test passing is the proof that the picker sent a real user id.

Design: docs/superpowers/specs/2026-09-06-notifications-inbox-design.md

🤖 Generated with Claude Code

Closes the "Plan 19.5 — Mention push bridge" deferral by widening it: an @mention that only reaches you while you already have the document open is not worth the wire, so delivery is per-user rather than per-doc and the reserved MSG_MENTION plumbing goes away instead of getting finished. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

14 tasks, TDD throughout. Two spec amendments fell out of writing it: a trait object cannot join the caller's transaction, so request-path emits are at-most-once after commit (task_assigned is the exception and writes inside the reindex transaction); and comment bodies render as plain text, so mention identity travels as an explicit id list rather than the editor's knot://user/<uuid> sentinel. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Idempotency lives in the notifications_dedupe unique index rather than in application logic, so concurrent emits from several replicas converge on one row without coordination. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

…unread_count cap Remove set_ages_for_test and hard_delete_doc_for_test from the production store type; the same SQL now runs directly against store.pool() from the test file. Also add an assertion that unread_count's LIMIT actually clips the result, not just bounds it from above. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>