---
kind: task
slug: notification-inbox-foundation
title: Build notification persistence and inbox API
plan_slug: workspace-communications
epic_slug: unified-notifications
status: ready
priority: P1
tenant_id: global
owner: unassigned
cursor_todo_id: null
updated_at: "2026-09-25"
---

# Task summary

Create the durable, recipient-scoped notification substrate and query/mutation API for a unified inbox.

## Description

Add notifications and delivery-attempt tables with polymorphic source/target metadata and safe deep links. Preserve domain state in its originating tables; notifications are projections for a recipient. Add workspace-scoped procedures for pagination, unread counts, mark-read, mark-all-read, and archive.

## Subtasks

- [ ] Add `notifications` and `notification_deliveries` schemas and generated migration.
- [ ] Define validated categories, actor/source/target contracts, and deduplication keys.
- [ ] Add recipient-scoped inbox procedures and indexes for unread queries.
- [ ] Add isolation, deduplication, and concurrent mark-read tests.

## Owner or assignee

`unassigned`

## Status

`ready`

## Estimation

`M`

## Acceptance criteria

- [ ] Each notification belongs to one workspace and recipient.
- [ ] Duplicate source events cannot create duplicate recipient notifications.
- [ ] Read/archive operations are idempotent and safe across devices.
- [ ] Deep links are generated from typed internal targets, not arbitrary untrusted URLs.
- [ ] `pnpm lint && pnpm type-check && pnpm test` pass.

## Links to related Epic / Plan

- Epic: `./Epic-unified-notifications.md`
- Plan: `../Plan-workspace-communications.md`