Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
Notification state cutover
Implementation and local verification are complete. The migration has been applied to local development/test databases only; production rollout remains an explicit, coordinated operation.
Model and agreed semantics
user_notification.state is a non-null PostgreSQL notification_state enum:
unseen | seen | done, defaulting to unseen.
| Operation | Unseen | Seen | Done |
|---|---|---|---|
| Mark seen | Seen | Seen | Done |
| Mark done | Done | Done | Done |
| Reopen / undo done | Unseen | Seen | Seen |
Transitions are atomic and idempotent. A late mark-seen never reopens done.
seen_at / API viewed_at are retained historical metadata, not a second source
of lifecycle state. Marking seen preserves an existing timestamp. Completing or
reopening does not fabricate a view timestamp. Sent and deleted status remain separate.
Backfill includes soft-deleted rows and gives done precedence:
- Legacy
done = truebecomes done, even whenseen_atis null. - Otherwise, a recorded view becomes seen.
- Otherwise, the notification is unseen.
Contracts and filters
- REST rows, realtime patches, and AI tool results expose lowercase
state. - GraphQL notifications expose
state: NotificationState!(UNSEEN,SEEN,DONE). - HTTP list queries accept comma-separated states, e.g.
?states=unseen,seen. Omission defaults to active;?states=explicitly selects all states. - AI ListNotifications takes a state array, with the same default and empty semantics.
- Item ASTs use
NotificationState(NotificationState)instead of boolean literals. Filter DTOs usenotification_filters: { states: [...] }. Empty means no restriction. Legacy boolean DTO fields are rejected rather than silently ignored. - Exact seen excludes done. Active means exists unseen OR exists seen, not NOT exists done: entities can have several notifications in different states.
- Separate AND literals can be witnessed by different notifications. Foreign entities preserve arbitrary pure notification AND/OR/NOT expressions using the eight possible sets of present states. Their pre-existing restriction on mixed metadata/notification OR/NOT subtrees remains fail-closed.
- Notification state selections are deduplicated before AST expansion, bounding a DTO's state union to three leaves. Candidate gates push OR/NOT only when the complete subtree is supported; unsupported branches are never silently removed.
- Email read/unread is independent:
EmailLiteral::Read(bool)/EmailFilters.is_read. Email inbox visibility is also independent of user notifications.
Both frontend AST compilers translate existing persisted UI ...Seen / ...Done
filter intent into state selections. Normalized caches reset when the GraphQL schema
hash changes. cache-wasm was bumped to 0.6.7 so version-gated dev builds rebuild too.
Opaque Soup cursors also embed the filter AST. Pre-cutover cursors containing boolean
ns values or the removed nd literal are intentionally incompatible: clients must
refresh and restart pagination during the coordinated cutover. Do not add a boolean
fallback to the canonical state enum: legacy ns: true can match both seen and done,
so mapping it to exact seen would silently change the query. Retaining old cursors
would require a separate, versioned expression-level translator.
Frontend and SDK behavior
- Notification badges, row predicates, and read markers use state, not timestamps.
- Realtime patch decoding requires a valid state. The metadata fallback cannot admit an invalid or missing lifecycle state.
- Active/history query partitions remain distinct when applying patches, inserting notifications, or restoring undo snapshots. Undo snapshots restore as seen, including snapshots originally taken while the notification was unseen.
- Local state overlays protect against stale fetches and late mutation failures. Rollbacks are conditional on the specific overlay they installed; an older failure cannot roll back a newer acknowledgment or done action.
- The generic GraphQL scalar cache optimistically writes only unconditional Done. Seen/reopen are conditional operations, so their scalar state and historical timestamp await authoritative replies. View-local overlays still provide optimistic feedback; this avoids guessing a Seen patch that could reopen Done on another surface.
- Soup restoration recognizes state unions and respects the arriving notification's exact state. It does not mistake a negated or mixed-OR constraint for an active-only view.
- SDK
state()is authoritative; convenienceseen()/done()are derived from it. SDK list options support exact state selections.
Verification completed
- Migration up/down round trips for all four legacy combinations, including deleted rows and invalid done/unseen rows, plus defaults and enum/not-null constraints.
- Complete persisted transition matrix, retries, concurrent seen/done requests, user isolation, digest exclusion, and original-timestamp retention.
- Exact-state, union, negation, multiple-witness, optimized/fallback, and email read/state independence tests across notification and entity repositories.
- Affected backend, GraphQL schema-composition, projection, SDK, and cache-core suites.
- Root SQLx preparation and offline service builds; generated metadata is checked in. Static SQL uses checked macros; dynamic AST SQL binds values and uses trusted fragments.
- Wasm filter materialization and a rebuilt versioned browser cache.
- Regenerated GraphQL SDL/documents/cache schema, relevant OpenAPI clients, SDK clients, and cognition AI-tool schemas.
- Full frontend typecheck and generated-cache-schema check.
- Full frontend suite after rebasing and fixing PR review findings: 4,499 passed, one pre-existing todo, across 493 test files. CI's exact TypeScript command also passes.
- Review regressions cover mixed Inbox state selections, inbox-scoped cache keys with sibling state constraints, and untracked optimistic rollback snapshots. The new regression tests failed before the fixes and pass afterward.
- Biome checks on tracked frontend source. Ignored browser-test build bundles can make
an unrestricted local
biome checkreport diagnostics on minified generated JS. - Local EXPLAIN plans use the foreign-entity source index, per-user notification covering index, and notification ordering index. This is not a production-volume benchmark.
Browser verification
A dedicated notifstate stack (--port-base 24000, no Doppler) was used, not hosted dev.
The static app is at http://localhost:24009/app/; a separate local GraphQL-enabled
Vite session on port 3007 used the same backend.
With a new local account and its onboarding notification, both transports were exercised:
- Opening the unseen notification produced seen and cleared the unread badge.
emarked it done and removed it from the active inbox.Ctrl+Zrestored it as seen, without an unread badge.- Repeated reads, done, and undo retained the exact original viewing timestamp.
- A delayed seen request against done left both state and timestamp unchanged.
- Unread filtering hid the restored seen row; Read filtering showed it.
Coordinated production rollout
- Prepare the new backend/frontend artifacts, including a fresh wasm build. Assess production backfill size and index-build time, and take the appropriate backup.
- Quiesce old writers and drain old-format queued notification/realtime envelopes.
Do not replay old-format envelopes into new consumers without explicit handling.
Stop old readers/writers before the migration drops
done. - Apply the generated
user_notification_statemigration during the cutover window. Do not deploy this migration independently of the corresponding application change. - Start the new services/consumers and require clients to refresh onto the new bundle. This is intentionally not a rolling-compatible protocol change.
- Check state counts, unchanged historical timestamps, active/history lists, read/done/ undo behavior, and query plans with production statistics.
Rollback is coordinated too: stop state-based code before applying the down migration and restoring the old binaries. The down migration derives the old boolean from current state and preserves timestamps; it cannot recover pre-cutover state/history. In particular, seen rows without a recorded view cannot be represented exactly in the old model.