Notification system · states gallery
Mock for the durable, pull-based notification queue. A notification is a durable message addressed to a principal: a producer appends a record to that principal's queue in stable storage, and the bell in the global top bar shows the unread count and opens the panel. No push, no sockets — the client polls, and the server-side queue is authoritative. Covers V1 only: levels and categories, the pending queue, aggregation and flood control, conditions vs. events, retention, revision-keyed polling and the producer outbox. Deferred: real-time push, out-of-band delivery (email / mobile / SMS), per-category preferences and muting, multi-action rows, cross-kind digests.
Polling keyed on a per-user revision, never the newest notification ID (§22). Grouping, reading and resolving all change a notification without producing a new ID, so an ID cursor silently misses them — see frame 10.
Bell with its unread badge sits between the divider and the wallet pill. The context bar below carries only the breadcrumb + principal chip.
Same bar skeleton, but the bell is gone and the wallet pill becomes a white Connect button. No principal chip. The anonymous principal is rejected by the service outright (Part VI).
Left to right: no badge at zero (never a grey “0”) · exact count up to 9 · ten or more renders 9+. The header badge, the panel, the Projects page and the Billing page all read the same client-side state — one poller per application (§11), never one per consumer.
Notifications
The category chip is shown here so the mapping is legible during design review; whether it ships as a visible chip or only as an icon-and-grouping signal is a UI call. Categories drive filtering, visual grouping and navigation, and preferences (V2) will key on categories, never on kind strings (§4). Retention never surfaces in the panel — it is housekeeping (frame 09).
| Level | Meaning | Retention |
|---|---|---|
| info | Something happened; no action normally required | Capped |
| success | Something the user or platform started completed | Capped |
| warning | Needs attention but is not yet failing | Persistent |
| error | Something failed | Persistent |
| critical | Failing or approaching failure, where ignoring it may cause interruption or loss | Persistent + eligible for out-of-band delivery later |
Row tints in frame 03 are this field. critical is the only level rendered as a solid fill rather than a tint — it is the one level that may later trigger email / push / SMS, so it must be visually unmistakable.
These names are product vocabulary, not Canic vocabulary, and must not leak into canic-core — Canic knows about Fleets, Components, canisters and identity; it does not know what a marketplace or a vault is.
Login, device and passkey events belong to Internet Identity and are invisible to Toko. access_security covers platform-native events only. The three studio-access events — granted · revoked · restored — sit on one bullet in the catalog rather than being split across the studio and vault entries.
Token #1 is live Token #2 is live becomes 3 tokens are now live Token #3 is live (count 3)
Only pending rows coalesce. Once a user has read a grouped notification a later event starts a new one, rather than silently modifying something already consumed. Timer sweeps are deduped separately, producer-side, per subject per threshold (§5) — not by this service-side grouping rule.
A producer's raw group_key is not globally unique. The effective grouping scope is:
recipient + producer + category + group_key
Billing / alice / billing / low-cycles/project-123
Projects / alice / projects / low-cycles/project-123 ← cannot collide
Grouping additionally requires compatible level semantics. Different levels never merge — which is exactly what makes escalation work (frame 06). Grouping never combines across users, producers, categories, incompatible levels, or unrelated semantic groups.
Per-source cap · proposed N = 5 pending per source“Generation complete — 250,000 tokens”, not 250,000 rows. Future batch features inherit this rule. Schema impact of both mechanisms: count plus last_event_at.
10:00 Project Alpha is low on cycles
10:05 automatic refill succeeds
10:05 producer resolves the notification
11:00 user opens the app and is not warned
about a solved problem
Struck-through, muted treatment is the design-review rendering of a resolved row. In the shipping panel a resolved row simply leaves the pending view; it lives on in bounded history with read_at still null, which is the truthful record.
Resolution is also what makes escalation safe. A producer does not mutate the level of a notification the user may already have read. It resolves its warning and publishes a critical — a new row, a new record. Level is not part of the §25 grouping tuple, but grouping additionally requires compatible level semantics, so the two never merge.
Rendered title and body never re-render after copy changes. A notification is a historical record of what the user was told (§24).
Dedup and re-arm rules are specified per row type, not globally: only cycle runway and insurance review define re-arming. Vendor-end and listing-expiry dedup scopes are still open.
A project does not own a shared inbox. If a project has three admins the Projects producer emits to all three principals; the service sees three recipients and does not know what a project is or why those principals were chosen. A shared project queue would immediately infect the service with membership and domain authorization semantics.
Not eight inter-canister calls (§17). Recipient vectors stay bounded.
Notifications
Nothing waiting. We’ll keep anything that happens here until you’ve seen it.
Notifications
No unread notifications.
The guarantee this empty state is quietly asserting: a user can close the browser, stay away for days, return, and still retrieve every notification that remains pending (§2). Correctness never depends on a websocket, an open tab, or client-side history.
Prefer a simple count cap over a timer-driven TTL subsystem. Pending queue and history are different concepts and are bounded separately.
And if it is ever needed, consume Canic's canonical timer ownership rather than adding a scheduler.
10:00 N17 "Tokens are live", count 1
client receives N17
10:10 another token goes live
service updates N17 → count 2
no newer ID exists, so
poll(since = N17) → nothing
the client never sees the update
NotificationQuery::Poll { known_revision: Option<UserNotificationRevision>, cursor: Option<NotificationCursor>, limit: u16, } Unchanged { revision, unread_count } SnapshotPage { revision, unread_count, notifications, next_cursor }
An unchanged poll is tiny. A changed poll returns the current bounded snapshot. Simpler than maintaining a delta stream, and it needs no client-visible tombstones for read, resolved or regrouped records. The badge count rides along — there is no separate unread-count query.
Exact timings are UX and load tuning, not part of the data contract. Polling is acceptable for V1 because notification reads are query calls, which are free — there is no cycle argument against it.
The header badge, the panel, the Projects page and the Billing page all consume the same client-side state. They do not each poll.
Pagination · every page belongs to one revisionPoll { known_revision: null, cursor: null, limit: 50 }
→ revision 431, first 50 items, next_cursor
If the user's revision changes mid-pagination, the client restarts from the new revision. This avoids snapshot-locking and historical versions. On login the complete pending set must be retrievable; it does not have to arrive in one response.
producer sends first_seq = 101, mutations 101..104
service commits next_expected_seq = 105
a retried batch is recognised as already applied
An inter-canister call can commit successfully even when the producer fails to observe the response. With grouping, a duplicate is worse than a repeated row, because it silently inflates a count: "Your token is live" submitted twice → "2 tokens are live", which is simply wrong.
Retries are exact. A producer never mints a fresh sequence identity because a call timed out, a transport failed, or a response was lost.
Why not (source, event_id)? Both achieve replay safety, but a frontier needs one integer per producer whereas event-ID dedup needs a retained set of seen IDs — and avoiding an unbounded global event-ID table was an explicit goal (§31). The tradeoff: a frontier requires a producer's batches to be ordered. Since each producer owns its outbox and submits sequentially, ordering is free — but a producer needing concurrent unordered submission is the assumption that breaks. The previous gallery specified idempotency on event_id; that is the rejected option.
Producer ──bounded update batch──▶ Notification Service
Invariant: notification ingestion performs no inter-canister authorization or discovery lookup. A producer cannot claim source = billing while actually being Marketplace — source is trusted service metadata, not caller-supplied. Do not route through Root; Root is not a notification router.
Notifications never break the domain operation. “Marketplace sale commits” must never become “Marketplace sale fails because the Notification Service was briefly unavailable.” On the IC there is no rollback across canisters, so the notification is written as its own operation after the triggering action commits.
The previous gallery said “retries 3× on a timer then drops with a log line — no full outbox in V1.” The design requires a durable outbox; the intent is retained and retried until accepted, not dropped.
enum NotificationCommand { ApplyProducerBatch { first_seq: u64, mutations: Vec<NotificationMutation>, }, MarkRead { ids: Vec<NotificationId>, }, MarkReadThrough { revision: UserNotificationRevision, category: Option<NotificationCategory>, }, } enum NotificationMutation { Publish(PublishNotification), Resolve(ResolveNotification), } struct PublishNotification { recipients: Vec<Principal>, level: NotificationLevel, category: NotificationCategory, title: String, body: String, cta: Option<NotificationCta>, group_key: Option<GroupKey>, } // source is absent by design (§19)
MarkReadThrough is revision-aware so a notification arriving after the user viewed the panel is not accidentally marked read — which a naive mark-all-read would do. That is why it replaces the reviewed MarkAllRead { category } (§32).
Read state updates are batched. The client collects read IDs and sends one MarkRead after a short debounce, when the panel closes, or at another suitable boundary — never one update per row.
The previous gallery listed list_notifications, unread_count, mark_read, mark_all_read, dismiss and clear_read as thin wrappers over IcyDB. That endpoint family does not exist in this design.
struct Notification { id: NotificationId, recipient: Principal, level: NotificationLevel, category: NotificationCategory, title: String, body: String, cta: Option<NotificationCta>, created_at: Timestamp, // never mutated last_event_at: Timestamp, // the sort key count: u32, read_at: Option<Timestamp>, resolved_at: Option<Timestamp>, group_key: Option<GroupKey>, source: ProducerIdentity, }
Append-oriented, not strictly immutable. Only aggregation state (count, last_event_at), read state and resolution state may change. A grouped notification reads created_at 10:00, last_event_at 10:37, count 5 — and the feed orders on last_event_at. The previous gallery used occurred_at; the field is last_event_at.
There is no dead actions: [] field in V1 — multi-action rows (Accept / Reject / Retry) are future scope, and the record anticipates an additive optional field when they arrive. An action carries navigation information, never executable instructions.
All strings and vectors carry explicit maximum encoded sizes. No collection is unbounded.
Only currently groupable records need a group entry; once read or resolved it can be removed. The producer frontier is compact — there is no table of every historical producer event. Use the application's existing stable-storage patterns rather than creating another persistence framework.
Event-driven: generator upload complete · batch generate complete · export complete · vendor started / empty (sold out) / ended · claim received on your vendor · sale completed on your listing · you were paid (royalty or beneficiary payout) · cycles low balance / top-up performed · studio access granted · content review outcome · vault and custody (arrangement proposed or amended, continuity events, authenticity challenged or revoked, role changes, project ownership transferred).
Timer-based: vendor about to end (24h / 1h) · cycle runway watchdog 30 / 14 / 3 days · listing about to expire · redemption expiry (7d / 1d) · insurance review required.
Deferred to their own features: auction ended / outbid / won / closing soon (auctions ship after marketplace v1) · buyback offer received and accepted (Phase 2, collectable-cards launch) · dormancy and at-risk warnings.
Each event maps to a level, a category, a title, a body, and a deep link. Internal workflow phases do not become user notifications: prepare / allocate / upload / verify / commit / activate / publish is one line to the user — “Your collection is now live.”
Fleet Coordinator
│ places
▼
Fleet Subnet Root
│ provisions / installs / activates
▼
Notification Service
managed application canister
│
┌──────────────────┼──────────────────┐
Marketplace Billing Projects
└──────── notification batches ───────┘
│
▼
users
Provisioning · Wasm admission · placement · canister lifecycle · Fleet and Component identity · trusted caller binding · Directory publication · cycles · backup/restore · framework diagnostics.
The Notification Service ownsThe notification record · levels · categories · grouping · retention · recipient queues · read state · resolution · poll revision · producer replay state · its application API.
V1 is one Notification Service per Fleet. If it needs to scale, shard by recipient principal — never by subnet, and never by producer. This is not a preference. The per-user revision counter requires exactly one authority per user. Sharding by subnet or producer would scatter one user's notifications across services, and then:
Per-user sharding keeps all four intact, because one shard owns one user's entire queue. The platform already has this pattern — the user hub creates per-user shards — so notifications follow it rather than inventing a second sharding axis. It also answers the push question: a single source of truth per user is what push needs, and push would target the user's shard.
If reliable push ever arrives it becomes an additional delivery path over the same authoritative queue — never a second notification store.
This item is no longer available
The thing this notification pointed to has since been removed. Nothing is wrong with your account — the notification stays in your feed as a record.
The recipient is not a parameter on read operations, which makes Bob → list_pending(Alice) structurally inexpressible rather than merely forbidden. Do not invent a separate notification authentication framework — reuse the protected identity and Directory authority other inter-canister protocols use.
The queue is keyed by the user's stable application principal — the Internet Identity principal, or a wallet principal such as Oisy. Delegation principals are not used anywhere on this platform. A queue keyed by a transient session identity would strand a user's notifications the moment their session changed, which is the exact failure this system exists to prevent. Server-side ownership also means read state follows the user across devices.
recipient · level · category · title · body · action · grouping · producer · time · read state · resolution state
Does notToken · Collection · Project · Studio · Invoice · Vault · Marketplace listing · Cycle refill policy
Those concepts stay with the applications that own them. The service stores and delivers the message it is given, and never queries a producer later to reconstruct one.
Explicit non-goals for V1A distributed event bus · pub/sub infrastructure · Kafka-like topics · websockets · cross-canister streaming · producer fan-out queries · one notification canister per producer · a project queue · permanent audit history · generic telemetry · notification-derived domain policy · arbitrary HTML bodies · centrally stored notification templates · cross-Fleet routing · generic scheduler infrastructure · a new Canic infrastructure role.
8 · “Expired informational”. Rung 2 of the drop ladder has no defined expiry input anywhere in the document (frame 09).
9 · Persistence vs. the ladder. §8 says persistent rows are never evicted under informational pressure; the same section's ladder drops them at the cap. Both cannot hold as written (frame 09).
10 · What the per-source cap counts. §6 reads as per-vendor; source is per-producer. N = 5 is very different under each (frame 05).
11 · Level per event. §5 lists the catalog but assigns no level to any row. The mappings drawn in frames 03 and 07 are proposals.
| Area | 2026-07-16 gallery said | Design document says |
|---|---|---|
| Level field | named severity; all five values named in prose but only three tints drawn (ok / warn / err) | the field is level (§3). Five values are now drawn distinctly, critical as a solid fill |
| Categories | absent | six, closed vocabulary, one per notification (§4) |
| Sort key | occurred_at | last_event_at; created_at never mutated (§24) |
| Coalescing trigger | existing unread row, same kind + subject_ref | existing pending row in the same group: recipient + producer + category + group_key, compatible levels (§6, §25) |
| Replay safety | idempotent creation on event_id | monotonic producer sequence + accepted frontier; event IDs explicitly rejected (§18, §31) |
| Producer failure | retry 3× on a timer, then drop with a log line — “no full outbox in V1” | durable local outbox; intent retained and retried until accepted (§17, §28) |
| Endpoints | list_notifications, unread_count, mark_read, mark_all_read, dismiss, clear_read — thin wrappers over IcyDB | two methods: notification_command, notification_query (§20–§21) |
| Badge source | dedicated unread_count() endpoint | rides along with every Poll response; no separate query (§22) |
| Poll cursor | not specified; feed keyed on rows | per-user revision — never the newest notification ID (§22, correctness issue) |
| Mark all read | plain mark_all_read() | MarkReadThrough { revision, category } (§21, §32) |
| Retention | read rows purge after 7 days; informational expire at ~90 days via expires_at | count caps; a TTL subsystem is disfavoured but not ruled out, and the history cap is an open decision. Retention runs during existing mutations (§8, §27, Part IX·2) |
| Resolution | absent | resolved_at distinct from read_at; escalation by resolve-then-publish (§7) |
| Actions | no CTA on rows | one optional action — label + navigation target (§10) |
| Architecture | “IcyDB entity, stable memory” | managed application service in a Fleet; shard by recipient principal if ever needed (§13, §14) |
| References | “Decision 2/4/5/6”, “ruled 2026-07-21”, R34 / R47 / R54 | section numbers in notification-system-design.md |