Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

Seanaye/feat/notification filter projections (#6320)

Sean Ayeb9552ee1a78a
diff --git a/Cargo.lock b/Cargo.lock
index 79464fa288..4b080b53ae 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -3004,7 +3004,7 @@ dependencies = [
[[package]]
name = "cache-wasm"
-version = "0.6.7"
+version = "0.6.8"
dependencies = [
"async-lock",
"cache-core",
diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/notification-projection-harness.ts b/apps/web/src/lib/graphql-cache/worker/browser-test/notification-projection-harness.ts
new file mode 100644
index 0000000000..da507f3ea8
--- /dev/null
+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/notification-projection-harness.ts
@@ -0,0 +1,245 @@
+import { createWorkerCacheHost } from '../../host/worker-host';
+
+const node = document.querySelector<HTMLElement>('#result');
+if (!node) throw new Error('missing result node');
+const host = createWorkerCacheHost({
+ scope: `notification-projection-${crypto.randomUUID()}`,
+ requestTimeoutMs: 30_000,
+});
+const projectId = '00000000-0000-0000-0000-000000000001';
+const ids = [
+ '00000000-0000-0000-0000-000000000011',
+ '00000000-0000-0000-0000-000000000012',
+];
+const nil = '00000000-0000-0000-0000-000000000000';
+const snapshotQuery = `query Snapshot {
+ user { id soup(input: { initial: { limit: 20 } }) { items {
+ __typename id cacheProjection
+ notifications { id entityId entityType state }
+ ... on GraphqlSoupProject { ownerId parentId createdAt updatedAt }
+ } } }
+}`;
+const updateQuery = `mutation Update($input: UpdateNotificationsInput!) {
+ updateNotifications(input: $input) { id entityId entityType state }
+}`;
+const notification = (id: string, state: string) => ({
+ __typename: 'GraphqlNotification',
+ id,
+ entityId: projectId,
+ entityType: 'PROJECT',
+ state,
+});
+const unhydratedNotifications = ['DOCUMENT', 'PROJECT', 'CHAT'].map(
+ (entityType, index) => ({
+ ...notification(`00000000-0000-0000-0000-00000000002${index}`, 'UNSEEN'),
+ entityType,
+ entityId: '00000000-0000-0000-0000-000000000099',
+ })
+);
+const filters = (state: string) => ({
+ calendarEventFilter: { literal: { id: nil } },
+ documentFilter: { literal: { id: nil } },
+ projectFilter: { literal: { notificationState: state } },
+ chatFilter: { literal: { chatId: nil } },
+ emailFilter: { tree: { literal: { threadId: nil } } },
+ channelFilter: { literal: { channelId: nil } },
+ channelThreadFilter: { literal: { threadId: nil } },
+ callFilter: { literal: { callId: nil } },
+ crmCompanyFilter: { literal: { id: nil } },
+ foreignEntityFilter: { literal: { id: nil } },
+});
+const report: string[] = [];
+async function expectCount(label: string, state: string, expected: number) {
+ const result = await host.entityFilter({
+ filters: filters(state),
+ sortMethod: 'UPDATED_AT',
+ sortDirection: 'DESC',
+ limit: 20,
+ });
+ if (result.kind !== 'complete' || result.keys.length !== expected) {
+ throw new Error(`${label}: ${JSON.stringify(result)}`);
+ }
+ report.push(`${label}: ${expected}`);
+ if (node) node.textContent = report.join('\n');
+}
+const variables = (id: string, operation: string) => ({
+ input: { notificationIds: [id], operation },
+});
+const authority = (id: string, state: string) =>
+ host.writeQuery({
+ query: updateQuery,
+ variables: variables(id, 'MARK_DONE'),
+ data: { updateNotifications: [notification(id, state)] },
+ });
+const snapshot = (
+ identity = 'notification-projection-viewer',
+ entityId = projectId
+) => ({
+ query: snapshotQuery,
+ identity,
+ data: {
+ user: {
+ id: identity,
+ soup: {
+ items: [
+ {
+ __typename: 'GraphqlSoupProject',
+ id: entityId,
+ cacheProjection: null,
+ ownerId: 'macro|[email protected]',
+ parentId: null,
+ createdAt: '2025-01-01T00:00:00Z',
+ updatedAt: '2025-01-02T00:00:00Z',
+ notifications: [
+ ...ids.map((id) => ({ ...notification(id, 'UNSEEN'), entityId })),
+ ...unhydratedNotifications,
+ ],
+ },
+ ],
+ },
+ },
+ },
+});
+const seed = () => host.writeQuery(snapshot());
+const markDone = (id: string) =>
+ host.enqueueOptimisticMutation(
+ {
+ query: updateQuery,
+ variables: variables(id, 'MARK_DONE'),
+ uuid: crypto.randomUUID(),
+ data: {
+ updateNotifications: [
+ { __typename: 'GraphqlNotification', id, state: 'DONE' },
+ ],
+ },
+ },
+ {
+ owner: 'notification-test',
+ nowMs: Date.now(),
+ leaseExpiresAtMs: Date.now() + 60_000,
+ }
+ );
+
+try {
+ await seed();
+ await expectCount('Secondary edges preserve local filtering', 'UNSEEN', 1);
+ for (const row of unhydratedNotifications) {
+ await host.writeQuery({
+ query: updateQuery,
+ variables: variables(row.id, 'MARK_SEEN'),
+ data: { updateNotifications: [{ ...row, state: 'SEEN' }] },
+ });
+ await expectCount(`Unhydrated ${row.entityType} inbox update`, 'UNSEEN', 1);
+ const pending = await markDone(row.id);
+ if (pending.initialClaim.kind !== 'claimed')
+ throw new Error('unhydrated-parent mutation not claimed');
+ await expectCount(`Unhydrated ${row.entityType} optimism`, 'UNSEEN', 1);
+ await host.rollbackOptimisticWrite(
+ pending.transactionId,
+ {
+ owner: 'notification-test',
+ generation: pending.initialClaim.mutation.leaseGeneration,
+ },
+ 'intentional unhydrated-parent rollback'
+ );
+ await host.deleteRecords([`GraphqlNotification:${row.id}`]);
+ await expectCount(`Unhydrated ${row.entityType} deletion`, 'UNSEEN', 1);
+ }
+ const first = await markDone(ids[0]);
+ if (first.initialClaim.kind !== 'claimed')
+ throw new Error('first mutation not claimed');
+ await expectCount('One of two notifications done', 'UNSEEN', 1);
+ const second = await markDone(ids[1]);
+ await expectCount('Both notifications optimistically done', 'UNSEEN', 0);
+ await seed();
+ await expectCount('Refetch preserves both pending edits', 'UNSEEN', 0);
+ await host.rollbackOptimisticWrite(
+ first.transactionId,
+ {
+ owner: 'notification-test',
+ generation: first.initialClaim.mutation.leaseGeneration,
+ },
+ 'intentional test rollback'
+ );
+ await expectCount('Rollback restores only first notification', 'UNSEEN', 1);
+ const claim = await host.claimNextMutation(
+ 'notification-test',
+ Date.now(),
+ Date.now() + 60_000
+ );
+ if (!claim) throw new Error('second mutation not claimable');
+ await host.commitOptimisticWrite(
+ second.transactionId,
+ {
+ owner: 'notification-test',
+ generation: claim.leaseGeneration,
+ },
+ {
+ query: updateQuery,
+ variables: variables(ids[1], 'MARK_DONE'),
+ data: { updateNotifications: [notification(ids[1], 'DONE')] },
+ }
+ );
+ await authority(ids[0], 'SEEN');
+ await expectCount(
+ 'Authoritative seen removes unseen membership',
+ 'UNSEEN',
+ 0
+ );
+ await expectCount('Authoritative seen adds seen membership', 'SEEN', 1);
+ await authority(ids[0], 'DONE');
+ await expectCount('Done removes last seen contribution', 'SEEN', 0);
+ await authority(ids[1], 'SEEN');
+ await expectCount('Reopen inserts an active contribution', 'SEEN', 1);
+ await host.deleteRecords([`GraphqlNotification:${ids[1]}`]);
+ await expectCount('Deletion removes active contribution', 'SEEN', 0);
+ const done = await host.entityFilter({
+ filters: filters('DONE'),
+ sortMethod: 'UPDATED_AT',
+ sortDirection: 'DESC',
+ limit: 20,
+ });
+ if (done.kind !== 'unsupported') throw new Error('DONE must fall back');
+ report.push('DONE: network-only');
+ // Reused notification IDs must not carry old-parent removals across viewers.
+ // A complete snapshot establishes only the new viewer's parent projection.
+ await host.writeQuery(
+ snapshot('write-viewer', '00000000-0000-0000-0000-000000000002')
+ );
+ await expectCount(
+ 'Write identity switch discards old associations',
+ 'UNSEEN',
+ 1
+ );
+ await host.hydrateQuery(
+ snapshot('hydrate-viewer', '00000000-0000-0000-0000-000000000003')
+ );
+ await expectCount(
+ 'Hydration identity switch discards old associations',
+ 'UNSEEN',
+ 1
+ );
+ await host.writeQuery({
+ query: updateQuery,
+ identity: 'id-only-viewer',
+ variables: variables(ids[0], 'MARK_DONE'),
+ data: {
+ updateNotifications: [
+ { __typename: 'GraphqlNotification', id: ids[0], state: 'DONE' },
+ ],
+ },
+ });
+ await expectCount(
+ 'Identity-only notification cannot inherit a parent',
+ 'UNSEEN',
+ 0
+ );
+ node.dataset.status = 'passed';
+ node.textContent = report.join('\n');
+} catch (error) {
+ node.dataset.status = 'failed';
+ node.textContent = `${report.join('\n')}\n${String(error)}`;
+} finally {
+ await host.clear();
+ host.dispose();
+}
diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/notification-projection.browser.e2e.ts b/apps/web/src/lib/graphql-cache/worker/browser-test/notification-projection.browser.e2e.ts
new file mode 100644
index 0000000000..2a37369098
--- /dev/null
+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/notification-projection.browser.e2e.ts
@@ -0,0 +1,35 @@
+import { expect, test } from '@playwright/test';
+
+test('notification state memberships survive optimistic rollback and authoritative changes', async ({
+ page,
+}) => {
+ await page.goto('/notification-projection.html');
+ await expect(page.locator('#result')).toHaveAttribute(
+ 'data-status',
+ 'passed',
+ { timeout: 60_000 }
+ );
+ await expect(page.locator('#result')).toContainText(
+ 'Secondary edges preserve local filtering: 1'
+ );
+ for (const kind of ['DOCUMENT', 'PROJECT', 'CHAT']) {
+ for (const operation of ['inbox update', 'optimism', 'deletion']) {
+ await expect(page.locator('#result')).toContainText(
+ `Unhydrated ${kind} ${operation}: 1`
+ );
+ }
+ }
+ await expect(page.locator('#result')).toContainText(
+ 'Rollback restores only first notification: 1'
+ );
+ await expect(page.locator('#result')).toContainText('DONE: network-only');
+ await expect(page.locator('#result')).toContainText(
+ 'Write identity switch discards old associations: 1'
+ );
+ await expect(page.locator('#result')).toContainText(
+ 'Hydration identity switch discards old associations: 1'
+ );
+ await expect(page.locator('#result')).toContainText(
+ 'Identity-only notification cannot inherit a parent: 0'
+ );
+});
diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/notification-projection.html b/apps/web/src/lib/graphql-cache/worker/browser-test/notification-projection.html
new file mode 100644
index 0000000000..b30ec16e6f
--- /dev/null
+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/notification-projection.html
@@ -0,0 +1,10 @@
+<!doctype html>
+<html lang="en">
+ <head><meta charset="utf-8"><title>Notification filter projection</title></head>
+ <body>
+ <h1>Notification filter projection</h1>
+ <p>Production worker/WASM, isolated OPFS cache. No backend requests.</p>
+ <pre id="result" data-status="running">Running…</pre>
+ <script type="module" src="./notification-projection-harness.ts"></script>
+ </body>
+</html>
diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/playwright.config.ts b/apps/web/src/lib/graphql-cache/worker/browser-test/playwright.config.ts
index 9b4051eaaa..5654213125 100644
--- a/apps/web/src/lib/graphql-cache/worker/browser-test/playwright.config.ts
+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/playwright.config.ts
@@ -9,6 +9,7 @@ export default defineConfig({
testMatch: [
'coordinator.browser.e2e.ts',
'cache-wasm-packaging.browser.e2e.ts',
+ 'notification-projection.browser.e2e.ts',
],
timeout: 90_000,
fullyParallel: false,
diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/vite.config.ts b/apps/web/src/lib/graphql-cache/worker/browser-test/vite.config.ts
index 221807ddf0..1fc69165d7 100644
--- a/apps/web/src/lib/graphql-cache/worker/browser-test/vite.config.ts
+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/vite.config.ts
@@ -49,6 +49,7 @@ export default defineConfig(({ command }) => ({
'cache-lifecycle.html',
'graphql-soup-rollout.html',
'cache-recovery.html',
+ 'notification-projection.html',
].map((name) => [name.replace('.html', ''), resolve(directory, name)])
),
},
diff --git a/apps/web/src/lib/queries/soup/backfill.test.tsx b/apps/web/src/lib/queries/soup/backfill.test.tsx
index 02549e72a2..890ef1996e 100644
--- a/apps/web/src/lib/queries/soup/backfill.test.tsx
+++ b/apps/web/src/lib/queries/soup/backfill.test.tsx
@@ -393,7 +393,7 @@ describe('runSoupBackfills', () => {
it('restarts from the beginning when the cache generation is replaced', async () => {
localStorage.setItem(
- 'graphql-soup-backfill:v8:user-1:core-entities',
+ 'graphql-soup-backfill:v9:user-1:core-entities',
JSON.stringify({
userId: 'user-1',
nextCursor: 'stale-cursor',
diff --git a/apps/web/src/lib/queries/soup/backfill.ts b/apps/web/src/lib/queries/soup/backfill.ts
index 7975772386..b378d79e67 100644
--- a/apps/web/src/lib/queries/soup/backfill.ts
+++ b/apps/web/src/lib/queries/soup/backfill.ts
@@ -22,7 +22,7 @@ import { createEffect, createSignal, onCleanup } from 'solid-js';
// Bump when a default backfill input or completion guarantee changes so
// persisted cursors cannot retain an older hydration contract.
-const BACKFILL_VERSION = 8;
+const BACKFILL_VERSION = 9;
const PAGE_LIMIT = 100;
// Five threads × twenty messages reaches the backend's 100-message cap.
const EMAIL_CONTENT_PAGE_LIMIT = 5;
diff --git a/crates/client/cache-core/src/codec.rs b/crates/client/cache-core/src/codec.rs
index 3dc2a5d28a..fb06dca717 100644
--- a/crates/client/cache-core/src/codec.rs
+++ b/crates/client/cache-core/src/codec.rs
@@ -14,7 +14,7 @@ use thiserror::Error;
/// Bump when the stored representation of [`Record`]/[`CacheValue`]
/// (or anything else persisted) changes incompatibly.
-pub const CACHE_FORMAT_VERSION: u32 = 2;
+pub const CACHE_FORMAT_VERSION: u32 = 3;
/// Bump when a GraphQL schema change makes existing normalized records unsafe.
///
@@ -141,7 +141,7 @@ mod tests {
fn namespace_uses_schema_compatibility_epoch_not_schema_hash() {
assert_eq!(
cache_namespace("client-token-1"),
- "graphql-cache:client-token-1:s2:v2"
+ "graphql-cache:client-token-1:s2:v3"
);
}
}
diff --git a/crates/client/cache-core/src/engine.rs b/crates/client/cache-core/src/engine.rs
index 6547176388..b0d4fcf0a7 100644
--- a/crates/client/cache-core/src/engine.rs
+++ b/crates/client/cache-core/src/engine.rs
@@ -26,7 +26,7 @@ use crate::predicate::reconciliation::{
use crate::predicate::{
OptimisticShadowReconciliation, OptimisticUpsertReconciliation, PredicateIndexStorage,
PredicateQueryResult, ProjectionMutation, ProjectionMutationLayer, ProjectionState,
- StagedOptimisticProjection, StagedOptimisticProjectionOwner,
+ StagedOptimisticProjection, StagedOptimisticProjectionOwner, apply_authoritative_exact_members,
apply_authoritative_projection_mutations, apply_authoritative_projection_patch,
compose_effective_optimistic_projection,
};
@@ -1758,6 +1758,23 @@ impl<S: Storage> Engine<S> {
ProjectionMutation::Delete(record_key) => {
authoritative.insert(record_key.clone(), None);
}
+ ProjectionMutation::PatchExact {
+ record_key,
+ profile,
+ partition,
+ remove,
+ insert,
+ } => {
+ let state = apply_authoritative_exact_members(
+ authoritative.get(record_key).and_then(Option::as_ref),
+ record_key,
+ profile,
+ partition,
+ remove,
+ insert,
+ );
+ authoritative.insert(record_key.clone(), Some(state));
+ }
}
}
let remaining_layers = self
@@ -2400,11 +2417,28 @@ impl<S: PredicateIndexStorage> Engine<S> {
&mut self,
keys: &[EntityKey<'static>],
projection_keys: &[PredicateRecordKey],
+ ) -> Result<Revisioned<BTreeSet<OpId>>, EngineError<S::Error>> {
+ self.delete_keys_with_projection_changes(
+ keys,
+ projection_keys
+ .iter()
+ .cloned()
+ .map(ProjectionMutation::Delete)
+ .collect(),
+ )
+ .await
+ }
+
+ /// Atomically delete records and update projections that depend on them.
+ pub async fn delete_keys_with_projection_changes(
+ &mut self,
+ keys: &[EntityKey<'static>],
+ projections: Vec<ProjectionMutation>,
) -> Result<Revisioned<BTreeSet<OpId>>, EngineError<S::Error>> {
self.ensure_revision_can_advance()?;
let affected = self.deps.ops_for_keys(keys.iter());
self.storage
- .delete_batch_with_projections(keys, projection_keys)
+ .delete_batch_with_projection_changes(keys, projections)
.await
.map_err(EngineError::Storage)?;
for key in keys {
diff --git a/crates/client/cache-core/src/predicate.rs b/crates/client/cache-core/src/predicate.rs
index 5cfc11229f..d13d368368 100644
--- a/crates/client/cache-core/src/predicate.rs
+++ b/crates/client/cache-core/src/predicate.rs
@@ -2,6 +2,9 @@
pub mod reconciliation;
+#[cfg(test)]
+mod test;
+
use crate::{
queue::{MutationId, MutationQueueSnapshot},
store::Storage,
@@ -10,9 +13,10 @@ use crate::{
use maybe_send::MaybeSend;
pub use predicate_index::ProjectionIncompleteKind;
use predicate_index::{
- EffectiveOptimisticProjection, ExactAttributePatch, IndexDocument, IntegerAttributePatch,
- IntegerFact, OptimisticProjectionMutation, OptimisticProjectionState, OptimisticUncertainty,
- PendingOptimisticProjection, Profile, RecordKey, Token, ValidatedIndexQuery, ValidationError,
+ EffectiveOptimisticProjection, ExactAttributePatch, ExactFact, IndexDocument,
+ IntegerAttributePatch, IntegerFact, OptimisticProjectionMutation, OptimisticProjectionState,
+ OptimisticUncertainty, PendingOptimisticProjection, Profile, RecordKey, Token,
+ ValidatedIndexQuery, ValidationError,
};
use serde::{Deserialize, Serialize};
use std::collections::{BTreeSet, HashMap};
@@ -370,6 +374,41 @@ fn apply_projection_mutation(
.chain(sorts.iter().map(|fact| fact.attribute.clone())),
);
}
+ OptimisticProjectionMutation::PatchExact {
+ record_key,
+ profile,
+ partition,
+ remove,
+ insert,
+ } => {
+ let Some(OptimisticProjectionState::Complete(document)) = state else {
+ *state = Some(OptimisticProjectionState::Incomplete {
+ record_key: record_key.clone(),
+ profile: profile.clone(),
+ partition: partition.clone(),
+ kind: ProjectionIncompleteKind::Missing,
+ });
+ return Ok(());
+ };
+ if document.profile != *profile || document.partition != *partition {
+ *state = Some(OptimisticProjectionState::Incomplete {
+ record_key: record_key.clone(),
+ profile: profile.clone(),
+ partition: partition.clone(),
+ kind: ProjectionIncompleteKind::Missing,
+ });
+ return Ok(());
+ }
+ // A member edit cannot establish completeness for an uncertain set.
+ if patch_exact_members(document, remove, insert).is_err() {
+ *state = Some(OptimisticProjectionState::Incomplete {
+ record_key: record_key.clone(),
+ profile: profile.clone(),
+ partition: partition.clone(),
+ kind: ProjectionIncompleteKind::Dirty,
+ });
+ }
+ }
OptimisticProjectionMutation::Delete {
record_key,
profile,
@@ -526,6 +565,48 @@ pub fn apply_authoritative_projection_patch(
}
}
+fn patch_exact_members(
+ document: &mut IndexDocument,
+ remove: &[ExactFact],
+ insert: &[ExactFact],
+) -> Result<(), ValidationError> {
+ document.exact_facts.retain(|fact| !remove.contains(fact));
+ document.exact_facts.extend_from_slice(insert);
+ document.canonicalize();
+ document.validate()
+}
+
+/// Apply individual set-member edits without claiming a missing base is complete.
+pub fn apply_authoritative_exact_members(
+ current: Option<&ProjectionState>,
+ record_key: &RecordKey,
+ profile: &Profile,
+ partition: &Token,
+ remove: &[ExactFact],
+ insert: &[ExactFact],
+) -> ProjectionState {
+ let mut state = apply_authoritative_projection_patch(
+ current,
+ record_key,
+ profile,
+ partition,
+ &[],
+ &[],
+ &[],
+ );
+ if let ProjectionState::Complete(document) = &mut state
+ && patch_exact_members(document, remove, insert).is_err()
+ {
+ state = ProjectionState::Incomplete {
+ record_key: record_key.clone(),
+ profile: profile.clone(),
+ partition: partition.clone(),
+ kind: ProjectionIncompleteKind::Dirty,
+ };
+ }
+ state
+}
+
/// Atomic change to one normalized record's generic projection.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub enum ProjectionMutation {
@@ -559,6 +640,19 @@ pub enum ProjectionMutation {
},
/// Delete projection state for a deleted normalized record.
Delete(RecordKey),
+ /// Edit individual exact-set members while preserving other contributors.
+ PatchExact {
+ /// Normalized record key.
+ record_key: RecordKey,
+ /// Projection profile.
+ profile: Profile,
+ /// Entity partition.
+ partition: Token,
+ /// Members to remove before inserting replacements.
+ remove: Vec<ExactFact>,
+ /// Members to insert idempotently.
+ insert: Vec<ExactFact>,
+ },
}
impl ProjectionMutation {
@@ -568,6 +662,7 @@ impl ProjectionMutation {
Self::Replace(document) => &document.record_key,
Self::Patch { record_key, .. }
| Self::MarkIncomplete { record_key, .. }
+ | Self::PatchExact { record_key, .. }
| Self::Delete(record_key) => record_key,
}
}
@@ -618,6 +713,20 @@ pub fn apply_authoritative_projection_mutations(
kind: *kind,
}),
ProjectionMutation::Delete(_) => None,
+ ProjectionMutation::PatchExact {
+ record_key,
+ profile,
+ partition,
+ remove,
+ insert,
+ } => Some(apply_authoritative_exact_members(
+ states.get(record_key),
+ record_key,
+ profile,
+ partition,
+ remove,
+ insert,
+ )),
};
if let Some(state) = state {
states.insert(key, state);
@@ -647,6 +756,13 @@ pub trait PredicateIndexStorage: Storage {
projection_keys: &[RecordKey],
) -> impl Future<Output = Result<(), Self::Error>> + MaybeSend;
+ /// Atomically delete records and apply dependent projection changes.
+ fn delete_batch_with_projection_changes(
+ &mut self,
+ keys: &[EntityKey<'static>],
+ projections: Vec<ProjectionMutation>,
+ ) -> impl Future<Output = Result<(), Self::Error>> + MaybeSend;
+
/// Reconcile bounded server membership with complete local candidates.
/// Unlike an exact query, unrelated incomplete projections do not block it.
fn reconcile_predicate_index(
diff --git a/crates/client/cache-core/src/predicate/test.rs b/crates/client/cache-core/src/predicate/test.rs
new file mode 100644
index 0000000000..d757a879af
--- /dev/null
+++ b/crates/client/cache-core/src/predicate/test.rs
@@ -0,0 +1,103 @@
+use super::*;
+use predicate_index::{ExactFact, ExactValue};
+
+fn token(value: &str) -> Token {
+ Token::new(value).unwrap()
+}
+fn fact(value: &str) -> ExactFact {
+ ExactFact {
+ attribute: token("members"),
+ value: ExactValue::utf8(value).unwrap(),
+ }
+}
+fn document() -> IndexDocument {
+ IndexDocument {
+ record_key: RecordKey::new("Entity:1").unwrap(),
+ profile: Profile::new(token("p1")),
+ partition: token("entity"),
+ exact_facts: vec![fact("a"), fact("b")],
+ integer_facts: vec![],
+ sort_facts: vec![],
+ }
+}
+fn edit(document: &IndexDocument) -> OptimisticProjectionMutation {
+ OptimisticProjectionMutation::PatchExact {
+ record_key: document.record_key.clone(),
+ profile: document.profile.clone(),
+ partition: document.partition.clone(),
+ remove: vec![fact("a")],
+ insert: vec![fact("c")],
+ }
+}
+
+#[test]
+fn member_edits_are_idempotent_and_preserve_unknown_coverage() {
+ let doc = document();
+ let base = ProjectionState::Complete(doc.clone());
+ let mutations = [
+ OptimisticProjectionMutation::Unknown {
+ record_key: doc.record_key.clone(),
+ profile: doc.profile.clone(),
+ partition: doc.partition.clone(),
+ affected_attributes: vec![token("members")],
+ },
+ edit(&doc),
+ edit(&doc),
+ ];
+ let projection = compose_effective_optimistic_projection(
+ &doc.record_key,
+ Some(&base),
+ &[ProjectionMutationLayer {
+ owner: 1,
+ mutations: &mutations,
+ }],
+ )
+ .unwrap()
+ .unwrap();
+ assert!(projection.uncertainty.affects(&token("members")));
+ let OptimisticProjectionState::Complete(document) = projection.state else {
+ panic!("complete base retained")
+ };
+ assert_eq!(document.exact_facts, vec![fact("b"), fact("c")]);
+ let missing = apply_authoritative_exact_members(
+ None,
+ &doc.record_key,
+ &doc.profile,
+ &doc.partition,
+ &[],
+ &[fact("a")],
+ );
+ assert!(matches!(missing, ProjectionState::Incomplete { .. }));
+}
+
+#[test]
+fn member_growth_beyond_budget_is_incomplete_not_an_enqueue_failure() {
+ let mut doc = document();
+ doc.exact_facts = (0..predicate_index::MAX_FACTS_PER_DOCUMENT)
+ .map(|i| fact(&i.to_string()))
+ .collect();
+ let mutation = OptimisticProjectionMutation::PatchExact {
+ record_key: doc.record_key.clone(),
+ profile: doc.profile.clone(),
+ partition: doc.partition.clone(),
+ remove: vec![],
+ insert: vec![fact("new")],
+ };
+ let projection = compose_effective_optimistic_projection(
+ &doc.record_key,
+ Some(&ProjectionState::Complete(doc.clone())),
+ &[ProjectionMutationLayer {
+ owner: 1,
+ mutations: &[mutation],
+ }],
+ )
+ .unwrap()
+ .unwrap();
+ assert!(matches!(
+ projection.state,
+ OptimisticProjectionState::Incomplete {
+ kind: ProjectionIncompleteKind::Dirty,
+ ..
+ }
+ ));
+}
diff --git a/crates/client/cache-core/src/store.rs b/crates/client/cache-core/src/store.rs
index 7106f06e61..32ee256714 100644
--- a/crates/client/cache-core/src/store.rs
+++ b/crates/client/cache-core/src/store.rs
@@ -306,6 +306,41 @@ impl InMemoryStorage {
self.records.is_empty()
}
+ fn rebase_projections(&mut self, keys: &[PredicateRecordKey]) {
+ let sources = self
+ .mutations
+ .iter()
+ .map(|(id, row)| {
+ (
+ *id,
+ crate::queue::decode_optimistic_source(&row.optimistic.optimistic_data_json)
+ .expect("valid queued source"),
+ )
+ })
+ .collect::<Vec<_>>();
+ let layers = sources
+ .iter()
+ .map(
+ |(owner, source)| crate::predicate::ProjectionMutationLayer {
+ owner: *owner,
+ mutations: &source.projection_mutations,
+ },
+ )
+ .collect::<Vec<_>>();
+ for key in keys {
+ self.optimistic_projections.remove(key);
+ if let Some(shadow) = crate::predicate::compose_effective_optimistic_projection(
+ key,
+ self.projections.get(key),
+ &layers,
+ )
+ .expect("valid projection layers")
+ {
+ self.optimistic_projections.insert(key.clone(), shadow);
+ }
+ }
+ }
+
/// Number of normalized-record get calls (test diagnostics).
pub fn record_get_count(&self) -> usize {
self.record_get_count.load(Ordering::Relaxed)
@@ -352,7 +387,12 @@ impl Storage for InMemoryStorage {
projections: Vec<ProjectionMutation>,
) -> Result<(), Self::Error> {
self.put_batch(entries).await?;
+ let keys = projections
+ .iter()
+ .map(|mutation| mutation.record_key().clone())
+ .collect::<Vec<_>>();
apply_in_memory_projection_mutations(&mut self.projections, projections);
+ self.rebase_projections(&keys);
Ok(())
}
@@ -802,12 +842,26 @@ impl PredicateIndexStorage for InMemoryStorage {
&mut self,
keys: &[EntityKey<'static>],
projection_keys: &[PredicateRecordKey],
+ ) -> Result<(), Self::Error> {
+ self.delete_batch_with_projection_changes(
+ keys,
+ projection_keys
+ .iter()
+ .cloned()
+ .map(ProjectionMutation::Delete)
+ .collect(),
+ )
+ .await
+ }
+
+ async fn delete_batch_with_projection_changes(
+ &mut self,
+ keys: &[EntityKey<'static>],
+ projections: Vec<ProjectionMutation>,
) -> Result<(), Self::Error> {
self.delete_batch(keys).await?;
- for key in projection_keys {
- self.projections.remove(key);
- }
- Ok(())
+ self.put_batch_with_projections(Vec::new(), projections)
+ .await
}
async fn query_predicate_index(
diff --git a/crates/client/cache-turso/src/storage.rs b/crates/client/cache-turso/src/storage.rs
index c472c1b184..f25d62d8e7 100644
--- a/crates/client/cache-turso/src/storage.rs
+++ b/crates/client/cache-turso/src/storage.rs
@@ -1478,6 +1478,22 @@ impl PredicateIndexStorage for TursoStorage {
&mut self,
keys: &[EntityKey<'static>],
projection_keys: &[PredicateRecordKey],
+ ) -> Result<(), Self::Error> {
+ self.delete_batch_with_projection_changes(
+ keys,
+ projection_keys
+ .iter()
+ .cloned()
+ .map(ProjectionMutation::Delete)
+ .collect(),
+ )
+ .await
+ }
+
+ async fn delete_batch_with_projection_changes(
+ &mut self,
+ keys: &[EntityKey<'static>],
+ projections: Vec<ProjectionMutation>,
) -> Result<(), Self::Error> {
self.require_healthy()?;
let result = (|| {
@@ -1505,17 +1521,7 @@ impl PredicateIndexStorage for TursoStorage {
key,
)?;
}
- for key in projection_keys {
- let changed = driver::execute(
- &connection,
- INDEX_DOCUMENT_DELETE,
- vec![text(key.as_str())],
- )?;
- if !(0..=1).contains(&changed) {
- return Err(invariant());
- }
- }
- Ok(())
+ write_projection_mutations(&connection, projections)
})
})();
self.latch_result(result)
@@ -1809,10 +1815,52 @@ fn write_projection_mutations(
.filter_map(|(key, state)| state.map(|state| (key, state)))
.collect::<HashMap<_, _>>();
- for mutation in &mutations {
- let key = mutation.record_key().clone();
- apply_authoritative_projection_mutations(&mut states, std::slice::from_ref(mutation));
- write_projection_state(connection, &key, states.get(&key))?;
+ apply_authoritative_projection_mutations(&mut states, &mutations);
+ // A snapshot can include many child contributions to the same parent.
+ // Preserve mutation order in memory, but persist each final state only once.
+ for key in &keys {
+ write_projection_state(connection, key, states.get(key))?;
+ }
+ if !keys.is_empty() {
+ // Network snapshots and realtime writes must rebase pending member edits
+ // in the same transaction, not leave a shadow based on older authority.
+ let sources = driver::query(connection, QUEUE_SELECT, Vec::new())?
+ .into_iter()
+ .map(|row| {
+ let row = parse_queue_row(&row)?;
+ let source = cache_core::queue::decode_optimistic_source(
+ &row.optimistic.ok_or_else(invariant)?.optimistic_data_json,
+ )
+ .map_err(|_| invariant())?;
+ Ok((row.id, source))
+ })
+ .collect::<Result<Vec<_>, TursoStorageError>>()?;
+ let layers = sources
+ .iter()
+ .map(
+ |(owner, source)| cache_core::predicate::ProjectionMutationLayer {
+ owner: *owner,
+ mutations: &source.projection_mutations,
+ },
+ )
+ .collect::<Vec<_>>();
+ for key in keys {
+ delete_optimistic_projection(connection, &key)?;
+ if let Some(shadow) = cache_core::predicate::compose_effective_optimistic_projection(
+ &key,
+ states.get(&key),
+ &layers,
+ )
+ .map_err(|_| invariant())?
+ {
+ insert_optimistic_projection(
+ connection,
+ mutation_id_to_sql(shadow.owner)?,
+ shadow.state,
+ shadow.uncertainty,
+ )?;
+ }
+ }
}
Ok(())
}
@@ -2579,6 +2627,18 @@ impl SqlPredicateCompiler {
));
name
}
+ PredicateExpr::ExactExists { attribute } => {
+ let name = self.next_name();
+ for _ in 0..2 {
+ self.parameters.push(text(profile.token().as_str()));
+ self.parameters.push(text(partition.as_str()));
+ self.parameters.push(text(attribute.as_str()));
+ }
+ self.ctes.push(format!(
+ "{name}(source, document_id) AS (SELECT 0, f.document_id FROM exact_facts AS f JOIN effective_documents AS d ON d.source = 0 AND d.document_id = f.document_id WHERE d.profile = ? AND d.partition = ? AND f.attribute = ? UNION SELECT 1, f.document_id FROM optimistic_exact_facts AS f JOIN effective_documents AS d ON d.source = 1 AND d.document_id = f.document_id WHERE d.profile = ? AND d.partition = ? AND f.attribute = ?)"
+ ));
+ name
+ }
PredicateExpr::I64Range {
attribute,
lower,
diff --git a/crates/client/cache-wasm/Cargo.toml b/crates/client/cache-wasm/Cargo.toml
index 307b922072..389ff59ee4 100644
--- a/crates/client/cache-wasm/Cargo.toml
+++ b/crates/client/cache-wasm/Cargo.toml
@@ -2,8 +2,8 @@
edition = "2024"
name = "cache-wasm"
publish = false
-# Rebuild dev caches for the notification-state schema and filter vocabulary.
-version = "0.6.7"
+# Rebuild dev caches for active-notification projection membership.
+version = "0.6.8"
[features]
default = []
diff --git a/crates/client/cache-wasm/src/shell.rs b/crates/client/cache-wasm/src/shell.rs
index 2ba3bdad8d..f7c3ad717a 100644
--- a/crates/client/cache-wasm/src/shell.rs
+++ b/crates/client/cache-wasm/src/shell.rs
@@ -25,7 +25,8 @@ use predicate_index::RecordKey;
use serde::{Deserialize, Serialize};
use soup_filter_cache_adapter::{
SoupFilterCompileOutcome, authoritative_projection_mutations, compile_filter_request,
- dirty_projection_mutations, optimistic_projection_mutations,
+ dirty_projection_mutations, notification_deletion_updates, notification_projection_updates,
+ optimistic_notification_updates, optimistic_projection_mutations,
};
use std::cell::RefCell;
use std::collections::HashMap;
@@ -445,6 +446,17 @@ impl CacheState {
.expect("callable cache state contains an engine"))
}
+ /// Keep stored notification associations out of writes that will reset the
+ /// cache. The engine still owns the identity reset and operation invalidation.
+ async fn can_reuse_stored_identity(&mut self, identity: Option<&str>) -> Result<bool, JsValue> {
+ let Some(observed) = identity else {
+ return Ok(true);
+ };
+ let result = self.engine_mut()?.current_identity().await;
+ let bound = self.engine_result(result)?;
+ Ok(bound.as_deref().is_none_or(|bound| bound == observed))
+ }
+
fn engine_result<T>(
&mut self,
result: Result<T, EngineError<TursoStorageError>>,
@@ -1108,9 +1120,22 @@ impl CacheEngine {
let op_id = ops.borrow_mut().intern(&registration.op_id);
(op_id, registration.entity_resolvers)
});
- let projections =
+ let mut projections =
authoritative_projection_mutations(&query, operation_name.as_deref(), &data)
.map_err(err_js)?;
+ if state.can_reuse_stored_identity(identity.as_deref()).await? {
+ projections.extend(
+ notification_projection_updates(
+ state.engine_mut()?.storage(),
+ &query,
+ operation_name.as_deref(),
+ &vars,
+ &data,
+ )
+ .await
+ .map_err(err_js)?,
+ );
+ }
let result = state
.engine_mut()?
.write_query_with_registration_and_projections(
@@ -1154,9 +1179,22 @@ impl CacheEngine {
state.ensure_callable()?;
let variables = parse_variables(variables)?;
let data: serde_json::Value = serde_wasm_bindgen::from_value(data).map_err(err_js)?;
- let projections =
+ let mut projections =
authoritative_projection_mutations(&query, operation_name.as_deref(), &data)
.map_err(err_js)?;
+ if state.can_reuse_stored_identity(identity.as_deref()).await? {
+ projections.extend(
+ notification_projection_updates(
+ state.engine_mut()?.storage(),
+ &query,
+ operation_name.as_deref(),
+ &variables,
+ &data,
+ )
+ .await
+ .map_err(err_js)?,
+ );
+ }
let result = state
.engine_mut()?
.hydrate_query_with_projections(
@@ -1216,7 +1254,21 @@ impl CacheEngine {
let link_patches: Vec<OptimisticLinkPatch> = parse_vec(link_patches)?;
let revalidations: Vec<QueryRevalidation> = parse_vec(revalidations)?;
let created_at_ms = parse_timestamp(created_at_ms, "enqueue timestamp")?;
- let projection_mutations = optimistic_projection_mutations(&data, created_at_ms);
+ let mut projection_mutations = optimistic_projection_mutations(&data, created_at_ms);
+ projection_mutations.extend(
+ optimistic_notification_updates(
+ notification_projection_updates(
+ state.engine_mut()?.storage(),
+ &query,
+ operation_name.as_deref(),
+ &vars,
+ &data,
+ )
+ .await
+ .map_err(err_js)?,
+ )
+ .map_err(err_js)?,
+ );
let claim = MutationClaimRequest {
owner: lease_owner,
now_ms: parse_timestamp(now_ms, "claim timestamp")?,
@@ -1410,9 +1462,20 @@ impl CacheEngine {
};
let vars = parse_variables(variables)?;
let data: serde_json::Value = serde_wasm_bindgen::from_value(data).map_err(err_js)?;
- let projections =
+ let mut projections =
authoritative_projection_mutations(&query, operation_name.as_deref(), &data)
.map_err(err_js)?;
+ projections.extend(
+ notification_projection_updates(
+ state.engine_mut()?.storage(),
+ &query,
+ operation_name.as_deref(),
+ &vars,
+ &data,
+ )
+ .await
+ .map_err(err_js)?,
+ );
let result = state
.engine_mut()?
.commit_optimistic_write_with_projections_outcome(
@@ -1492,7 +1555,12 @@ impl CacheEngine {
future_to_promise(async move {
let mut state = state.lock().await;
state.ensure_callable()?;
- let projections = dirty_projection_mutations(&keys);
+ let mut projections = dirty_projection_mutations(&keys);
+ projections.extend(
+ notification_deletion_updates(state.engine_mut()?.storage(), &keys, true)
+ .await
+ .map_err(err_js)?,
+ );
let keys: Vec<EntityKey<'static>> =
keys.into_iter().map(|key| EntityKey(key.into())).collect();
let result = state
@@ -1516,15 +1584,20 @@ impl CacheEngine {
future_to_promise(async move {
let mut state = state.lock().await;
state.ensure_callable()?;
- let projection_keys = keys
- .iter()
- .filter_map(|key| RecordKey::new(key.clone()).ok())
- .collect::<Vec<_>>();
+ let mut projections =
+ notification_deletion_updates(state.engine_mut()?.storage(), &keys, false)
+ .await
+ .map_err(err_js)?;
+ projections.extend(
+ keys.iter()
+ .filter_map(|key| RecordKey::new(key.clone()).ok())
+ .map(cache_core::predicate::ProjectionMutation::Delete),
+ );
let keys: Vec<EntityKey<'static>> =
keys.into_iter().map(|key| EntityKey(key.into())).collect();
let result = state
.engine_mut()?
- .delete_keys_with_projections(&keys, &projection_keys)
+ .delete_keys_with_projection_changes(&keys, projections)
.await;
let affected = state.engine_result(result)?;
to_js(&JsAffectedOperationsResult {
diff --git a/crates/client/cache-wasm/src/shell/test.rs b/crates/client/cache-wasm/src/shell/test.rs
index 31c257b487..28d0771128 100644
--- a/crates/client/cache-wasm/src/shell/test.rs
+++ b/crates/client/cache-wasm/src/shell/test.rs
@@ -70,6 +70,7 @@ const SOUP_WITH_PROJECTION_QUERY: &str = r#"query SoupWithProjection($input: Sou
__typename
id
cacheProjection @cacheOnly
+ notifications { id entityId entityType state }
displayName
... on GraphqlSoupDocument {
ownerId
@@ -93,6 +94,7 @@ const SOUP_BACKFILL_WITH_PROJECTION_QUERY: &str = r#"query SoupBackfill($input:
__typename
id
cacheProjection @cacheOnly
+ notifications { id entityId entityType state }
displayName
... on GraphqlSoupDocument {
ownerId
@@ -115,6 +117,7 @@ const SOUP_UPDATES_WITH_PROJECTION_SUBSCRIPTION: &str = r#"subscription SoupUpda
__typename
id
cacheProjection @cacheOnly
+ notifications { id entityId entityType state }
displayName
... on GraphqlSoupDocument {
ownerId
@@ -359,6 +362,7 @@ fn projected_document_item_with_facts(
serde_json::json!({
"__typename": "GraphqlSoupDocument",
"id": document_id,
+ "notifications": [],
"cacheProjection": v3_document_supplement(
document_id,
is_email_attachment,
diff --git a/crates/client/cache-wasm/src/shell/test_storage.rs b/crates/client/cache-wasm/src/shell/test_storage.rs
index 750d1775c4..b09e50584f 100644
--- a/crates/client/cache-wasm/src/shell/test_storage.rs
+++ b/crates/client/cache-wasm/src/shell/test_storage.rs
@@ -233,6 +233,16 @@ impl PredicateIndexStorage for BrowserStorage {
.await
}
+ async fn delete_batch_with_projection_changes(
+ &mut self,
+ keys: &[EntityKey<'static>],
+ projections: Vec<ProjectionMutation>,
+ ) -> Result<(), Self::Error> {
+ self.inner
+ .delete_batch_with_projection_changes(keys, projections)
+ .await
+ }
+
async fn query_predicate_index(
&self,
query: &ValidatedIndexQuery,
diff --git a/crates/item_filter_index/src/lib.rs b/crates/item_filter_index/src/lib.rs
index 3404e8f32e..bf0070c6e7 100644
--- a/crates/item_filter_index/src/lib.rs
+++ b/crates/item_filter_index/src/lib.rs
@@ -32,6 +32,8 @@ pub const SOUP_FLAT_V1: &str = "soup-flat-v1";
pub const SOUP_FLAT_V2: &str = "soup-flat-v2";
/// Stable server-minted profile containing viewer-relative task facts.
pub const SOUP_FLAT_V3: &str = "soup-flat-v3";
+/// Browser-composed profile with complete active-notification membership.
+pub const SOUP_FLAT_V4: &str = "soup-flat-v4";
// Keep this lightweight crate wasm-compatible instead of depending on the
// native `system_properties` crate. A native test locks this stable UUID to
@@ -63,6 +65,21 @@ pub mod vocabulary {
Profile::new(token(SOUP_FLAT_V3))
}
+ /// Browser-composed active-notification profile.
+ pub fn profile_v4() -> Profile {
+ Profile::new(token(super::SOUP_FLAT_V4))
+ }
+
+ /// IDs of unseen notifications for the viewer and primary entity.
+ pub fn notification_unseen() -> Token {
+ token("notification-unseen")
+ }
+
+ /// IDs of seen, still-active notifications for the viewer and primary entity.
+ pub fn notification_seen() -> Token {
+ token("notification-seen")
+ }
+
/// Document partition.
pub fn document_partition() -> Token {
token("document")
@@ -196,17 +213,17 @@ pub enum CompileError {
/// Check the complete materialized forest against the direct-field v1 profile.
pub fn check_soup_flat_v1(ast: &EntityFilterAst, request: SoupFlatRequest) -> Eligibility {
- check_soup_flat(ast, request, supported_document_literal_v1, false)
+ check_soup_flat(ast, request, supported_document_literal_v1, false, false)
}
/// Check the complete materialized forest against the server-minted v2 profile.
pub fn check_soup_flat_v2(ast: &EntityFilterAst, request: SoupFlatRequest) -> Eligibility {
- check_soup_flat(ast, request, supported_document_literal_v2, false)
+ check_soup_flat(ast, request, supported_document_literal_v2, false, false)
}
/// Check the complete materialized forest against the server-minted v3 profile.
pub fn check_soup_flat_v3(ast: &EntityFilterAst, request: SoupFlatRequest) -> Eligibility {
- check_soup_flat(ast, request, supported_document_literal_v3, true)
+ check_soup_flat(ast, request, supported_document_literal_v3, true, false)
}
fn check_soup_flat(
@@ -214,6 +231,7 @@ fn check_soup_flat(
request: SoupFlatRequest,
supported_document_literal: impl Fn(&DocumentLiteral) -> bool + Copy,
supports_status_properties: bool,
+ supports_notifications: bool,
) -> Eligibility {
if request.has_cursor {
return Eligibility::Unsupported(UnsupportedReason::Cursor);
@@ -310,10 +328,18 @@ fn check_soup_flat(
{
return Eligibility::Unsupported(UnsupportedReason::Literal("document"));
}
- if !supported_expr(ast.project_filter.as_deref(), supported_project_literal) {
+ if !supported_expr(ast.project_filter.as_deref(), |lit| {
+ supported_project_literal(lit)
+ || (supports_notifications
+ && matches!(lit, ProjectLiteral::NotificationState(state) if active_notification_state(state)))
+ }) {
return Eligibility::Unsupported(UnsupportedReason::Literal("project"));
}
- if !supported_expr(ast.chat_filter.as_deref(), supported_chat_literal) {
+ if !supported_expr(ast.chat_filter.as_deref(), |lit| {
+ supported_chat_literal(lit)
+ || (supports_notifications
+ && matches!(lit, ChatLiteral::NotificationState(state) if active_notification_state(state)))
+ }) {
return Eligibility::Unsupported(UnsupportedReason::Literal("chat"));
}
@@ -332,6 +358,7 @@ pub fn compile_soup_flat_v1(
supported_document_literal_v1,
compile_document_literal_v1,
None,
+ false,
)
}
@@ -347,6 +374,7 @@ pub fn compile_soup_flat_v2(
supported_document_literal_v2,
compile_document_literal_v2,
None,
+ false,
)
}
@@ -362,9 +390,52 @@ pub fn compile_soup_flat_v3(
supported_document_literal_v3,
compile_document_literal_v3,
Some(compile_status_property_literal),
+ false,
+ )
+}
+
+/// Compile exact UNSEEN/SEEN notification predicates in addition to v3 literals.
+/// DONE is intentionally unsupported: the active edge contains no done history.
+pub fn compile_soup_flat_v4(
+ ast: &EntityFilterAst,
+ request: SoupFlatRequest,
+) -> Result<LocalCompileOutcome, CompileError> {
+ compile_soup_flat(
+ ast,
+ request,
+ vocabulary::profile_v4(),
+ |lit| {
+ supported_document_literal_v3(lit)
+ || matches!(lit, DocumentLiteral::NotificationState(state) if active_notification_state(state))
+ },
+ |lit| match lit {
+ DocumentLiteral::NotificationState(state) => Ok(notification_state_expr(state)),
+ _ => compile_document_literal_v3(lit),
+ },
+ Some(compile_status_property_literal),
+ true,
)
}
+fn active_notification_state(state: &item_filters::NotificationState) -> bool {
+ matches!(
+ state,
+ item_filters::NotificationState::Unseen | item_filters::NotificationState::Seen
+ )
+}
+
+fn notification_state_expr(state: &item_filters::NotificationState) -> PredicateExpr {
+ PredicateExpr::ExactExists {
+ attribute: match state {
+ item_filters::NotificationState::Unseen => vocabulary::notification_unseen(),
+ item_filters::NotificationState::Seen => vocabulary::notification_seen(),
+ item_filters::NotificationState::Done => {
+ unreachable!("eligibility excludes done history")
+ }
+ },
+ }
+}
+
type PropertyLiteralCompiler = fn(&PropertiesLiteral) -> Result<PredicateExpr, CompileError>;
fn compile_soup_flat(
@@ -374,12 +445,14 @@ fn compile_soup_flat(
supported_document_literal: impl Fn(&DocumentLiteral) -> bool + Copy,
compile_document_literal: impl Fn(&DocumentLiteral) -> Result<PredicateExpr, CompileError> + Copy,
compile_properties_literal: Option<PropertyLiteralCompiler>,
+ supports_notifications: bool,
) -> Result<LocalCompileOutcome, CompileError> {
if let Eligibility::Unsupported(reason) = check_soup_flat(
ast,
request,
supported_document_literal,
compile_properties_literal.is_some(),
+ supports_notifications,
) {
return Ok(LocalCompileOutcome::Unsupported(reason));
}
@@ -412,11 +485,21 @@ fn compile_soup_flat(
},
PartitionPredicate {
partition: vocabulary::project_partition(),
- predicate: compile_expr(ast.project_filter.as_deref(), compile_project_literal)?,
+ predicate: compile_expr(ast.project_filter.as_deref(), |lit| match lit {
+ ProjectLiteral::NotificationState(state) if supports_notifications => {
+ Ok(notification_state_expr(state))
+ }
+ _ => compile_project_literal(lit),
+ })?,
},
PartitionPredicate {
partition: vocabulary::chat_partition(),
- predicate: compile_expr(ast.chat_filter.as_deref(), compile_chat_literal)?,
+ predicate: compile_expr(ast.chat_filter.as_deref(), |lit| match lit {
+ ChatLiteral::NotificationState(state) if supports_notifications => {
+ Ok(notification_state_expr(state))
+ }
+ _ => compile_chat_literal(lit),
+ })?,
},
],
sort_attribute,
diff --git a/crates/macro_tower_layers/src/test.rs b/crates/macro_tower_layers/src/test.rs
index edbe59c8b8..e3d20f9c6a 100644
--- a/crates/macro_tower_layers/src/test.rs
+++ b/crates/macro_tower_layers/src/test.rs
@@ -15,6 +15,7 @@ use tracing::{
#[derive(Default)]
struct CapturedTracing {
event_levels: Mutex<Vec<Level>>,
+ warning_fields: Mutex<Vec<HashMap<String, String>>>,
span_level: Mutex<Option<Level>>,
span_target: Mutex<Option<String>>,
declared_span_fields: Mutex<HashSet<String>>,
@@ -91,6 +92,11 @@ impl tracing::Subscriber for TracingCapture {
.lock()
.unwrap()
.push(*event.metadata().level());
+ if *event.metadata().level() == Level::WARN {
+ let mut fields = HashMap::new();
+ event.record(&mut FieldCapture(&mut fields));
+ self.captured.warning_fields.lock().unwrap().push(fields);
+ }
}
fn enter(&self, _span: &tracing::span::Id) {}
@@ -231,22 +237,34 @@ fn server_error_emits_only_failure_event() {
assert_eq!(fields.get("otel.status_code").unwrap(), "\"ERROR\"");
}
-#[tokio::test]
+#[tokio::test(start_paused = true)]
async fn starvation_detector_warns_when_runtime_blocked() {
let (subscriber, captured) = TracingCapture::new();
let _guard = set_default(subscriber);
spawn_starvation_detector(Duration::from_millis(10));
- // Let the detector initialize, consume its first tick, and enter the timing loop
- tokio::time::sleep(Duration::from_millis(15)).await;
+ // Poll the detector so it consumes its immediate tick and starts waiting.
+ tokio::task::yield_now().await;
+ assert_eq!(captured.event_count(Level::WARN), 0);
- // Block the runtime thread — simulates starvation
- std::thread::sleep(Duration::from_millis(50));
+ // Jump past multiple ticks without polling the detector in between. Unlike
+ // real sleeps, this models exactly one stalled interval regardless of CI load.
+ tokio::time::advance(Duration::from_millis(50)).await;
+ tokio::task::yield_now().await;
- // Let the detector observe the delay and emit the warning
- tokio::time::sleep(Duration::from_millis(15)).await;
+ assert_eq!(captured.event_count(Level::WARN), 1);
+ {
+ let warnings = captured.warning_fields.lock().unwrap();
+ let fields = &warnings[0];
+ assert_eq!(fields.get("expected_ms").unwrap(), "10");
+ assert_eq!(fields.get("actual_ms").unwrap(), "50");
+ assert_eq!(fields.get("delay_ms").unwrap(), "40");
+ }
+ // The next on-time tick must not emit another starvation warning.
+ tokio::time::advance(Duration::from_millis(10)).await;
+ tokio::task::yield_now().await;
assert_eq!(captured.event_count(Level::WARN), 1);
}
diff --git a/crates/predicate_index/src/lib.rs b/crates/predicate_index/src/lib.rs
index c1ce919bc0..ea8a4153da 100644
--- a/crates/predicate_index/src/lib.rs
+++ b/crates/predicate_index/src/lib.rs
@@ -174,6 +174,11 @@ pub enum PredicateExpr {
Or(Box<Self>, Box<Self>),
/// Subtract a result set from the profile/partition universe.
Not(Box<Self>),
+ /// Match at least one value of an exact attribute.
+ ExactExists {
+ /// Fact vocabulary token.
+ attribute: Token,
+ },
}
impl PredicateExpr {
@@ -195,7 +200,11 @@ impl PredicateExpr {
stack.push((right, depth + 1));
}
Self::Not(expr) => stack.push((expr, depth + 1)),
- Self::All | Self::None | Self::Exact { .. } | Self::I64Range { .. } => {}
+ Self::All
+ | Self::None
+ | Self::Exact { .. }
+ | Self::I64Range { .. }
+ | Self::ExactExists { .. } => {}
}
}
@@ -274,6 +283,10 @@ impl IndexDocument {
.exact_facts
.iter()
.any(|fact| &fact.attribute == attribute && &fact.value == value),
+ PredicateExpr::ExactExists { attribute } => self
+ .exact_facts
+ .iter()
+ .any(|fact| &fact.attribute == attribute),
PredicateExpr::I64Range {
attribute,
lower,
@@ -624,6 +637,19 @@ pub enum OptimisticProjectionMutation {
/// Potentially changed attributes. Empty means every attribute.
affected_attributes: Vec<Token>,
},
+ /// Edit individual set members without replacing other contributors.
+ PatchExact {
+ /// Normalized record key.
+ record_key: RecordKey,
+ /// Projection profile.
+ profile: Profile,
+ /// Entity partition.
+ partition: Token,
+ /// Members to remove before inserting replacements.
+ remove: Vec<ExactFact>,
+ /// Members to insert (idempotently).
+ insert: Vec<ExactFact>,
+ },
}
/// Complete replacement of one exact attribute's values.
@@ -657,6 +683,13 @@ impl OptimisticProjectionMutation {
return match self {
Self::Replace(document) => document.validate(),
Self::Delete { .. } | Self::Unknown { .. } => Ok(()),
+ Self::PatchExact { remove, insert, .. } => {
+ if remove.len() + insert.len() > MAX_FACTS_PER_DOCUMENT {
+ Err(ValidationError::DocumentFacts)
+ } else {
+ Ok(())
+ }
+ }
Self::Patch { .. } => unreachable!(),
};
};
@@ -688,7 +721,8 @@ impl OptimisticProjectionMutation {
Self::Replace(document) => &document.record_key,
Self::Patch { record_key, .. }
| Self::Delete { record_key, .. }
- | Self::Unknown { record_key, .. } => record_key,
+ | Self::Unknown { record_key, .. }
+ | Self::PatchExact { record_key, .. } => record_key,
}
}
@@ -698,7 +732,8 @@ impl OptimisticProjectionMutation {
Self::Replace(document) => &document.profile,
Self::Patch { profile, .. }
| Self::Delete { profile, .. }
- | Self::Unknown { profile, .. } => profile,
+ | Self::Unknown { profile, .. }
+ | Self::PatchExact { profile, .. } => profile,
}
}
@@ -708,7 +743,8 @@ impl OptimisticProjectionMutation {
Self::Replace(document) => &document.partition,
Self::Patch { partition, .. }
| Self::Delete { partition, .. }
- | Self::Unknown { partition, .. } => partition,
+ | Self::Unknown { partition, .. }
+ | Self::PatchExact { partition, .. } => partition,
}
}
@@ -847,6 +883,9 @@ fn expression_depends_on(expr: &PredicateExpr, attribute: &Token) -> bool {
| PredicateExpr::I64Range {
attribute: candidate,
..
+ }
+ | PredicateExpr::ExactExists {
+ attribute: candidate,
} => candidate == attribute,
PredicateExpr::And(left, right) | PredicateExpr::Or(left, right) => {
expression_depends_on(left, attribute) || expression_depends_on(right, attribute)
@@ -858,7 +897,9 @@ fn expression_depends_on(expr: &PredicateExpr, attribute: &Token) -> bool {
fn collect_expression_attributes(expr: &PredicateExpr, attributes: &mut BTreeSet<Token>) {
match expr {
- PredicateExpr::Exact { attribute, .. } | PredicateExpr::I64Range { attribute, .. } => {
+ PredicateExpr::Exact { attribute, .. }
+ | PredicateExpr::I64Range { attribute, .. }
+ | PredicateExpr::ExactExists { attribute } => {
attributes.insert(attribute.clone());
}
PredicateExpr::And(left, right) | PredicateExpr::Or(left, right) => {
@@ -902,7 +943,10 @@ fn simplify(expr: PredicateExpr) -> Result<PredicateExpr, ValidationError> {
upper,
}
}
- expr @ (PredicateExpr::All | PredicateExpr::None | PredicateExpr::Exact { .. }) => expr,
+ expr @ (PredicateExpr::All
+ | PredicateExpr::None
+ | PredicateExpr::Exact { .. }
+ | PredicateExpr::ExactExists { .. }) => expr,
})
}
diff --git a/crates/soup_filter_cache_adapter/src/lib.rs b/crates/soup_filter_cache_adapter/src/lib.rs
index 8ab29d2337..5fc10ae94f 100644
--- a/crates/soup_filter_cache_adapter/src/lib.rs
+++ b/crates/soup_filter_cache_adapter/src/lib.rs
@@ -10,7 +10,7 @@ use cache_core::predicate::{ProjectionIncompleteKind, ProjectionMutation};
use graphql_soup_filter_input::materialize_graphql_filter;
use indexmap::IndexMap;
use item_filter_index::{
- LocalCompileOutcome, SoupFlatRequest, SoupIndexSort, compile_soup_flat_v3, vocabulary,
+ LocalCompileOutcome, SoupFlatRequest, SoupIndexSort, compile_soup_flat_v4, vocabulary,
};
use predicate_index::{
ExactAttributePatch, ExactValue, IndexDocument, OptimisticProjectionMutation, RecordKey,
@@ -23,6 +23,11 @@ use soup_filter_projection::{
};
use std::collections::HashSet;
+mod notifications;
+pub use notifications::{
+ notification_deletion_updates, notification_projection_updates, optimistic_notification_updates,
+};
+
/// Failure to materialize or compile a Soup filter request.
#[derive(Debug, thiserror::Error)]
#[error("{0}")]
@@ -60,7 +65,7 @@ pub fn compile_filter_request(
));
}
};
- compile_soup_flat_v3(
+ compile_soup_flat_v4(
&ast,
SoupFlatRequest {
sort,
@@ -101,12 +106,13 @@ pub fn reconciliation_baseline_entry(
///
/// Document supplements are decoded only where `cacheProjection` is selected
/// for the surrounding entity and are merged with direct fields from that same
-/// object. A selected null or missing Document supplement marks v3 incomplete;
-/// selected null values on direct-only Projects and Chats are expected. Payloads
-/// that omit the field become bounded v3 direct-field patches, preserving
-/// server-owned facts from an existing complete projection. A payload without
-/// direct projection fields emits an empty patch so an existing v3 projection is
-/// retained while a missing base becomes explicitly incomplete.
+/// object. The immutable v3 Document supplement is composed with the complete
+/// active-notification edge into the browser's v4 profile. Selected null values
+/// on Projects and Chats are expected; missing notification snapshots cannot
+/// establish v4 completeness. Payloads omitting `cacheProjection` become bounded
+/// v4 patches, preserving server-owned facts and any unselected notification
+/// membership from an existing complete projection. A missing base remains
+/// explicitly incomplete.
pub fn authoritative_projection_mutations(
query: &str,
operation_name: Option<&str>,
@@ -144,7 +150,7 @@ pub fn authoritative_projection_mutations(
let has_incomplete_projection = has_unbound_incomplete_entity
|| mutations
.values()
- .any(|mutation| matches!(mutation, ProjectionMutation::MarkIncomplete { profile, .. } if profile == &vocabulary::profile_v3()));
+ .any(|mutation| matches!(mutation, ProjectionMutation::MarkIncomplete { profile, .. } if profile == &vocabulary::profile_v4()));
if operation_name.is_some_and(|name| name.starts_with("SoupBackfill"))
&& has_incomplete_projection
{
@@ -170,6 +176,11 @@ fn walk_authoritative_object(
collect_applicable_fields(selections, concrete_type, &mut fields);
if let Some(partition) = projection_partition(concrete_type) {
+ let mut projection_object = object.clone();
+ projection_object.remove("notifications");
+ if let Some(snapshot) = notifications::selected_snapshot(object, &fields) {
+ projection_object.insert("notifications".into(), snapshot);
+ }
let mut projection_fields = fields
.iter()
.copied()
@@ -190,15 +201,15 @@ fn walk_authoritative_object(
if let Some((key_text, record_key)) = normalized_key {
let kind = projection_kind(&partition).expect("supported partition has a kind");
let mutation = if projection_fields.is_empty() {
- match authoritative_v3_patch_for_object(
+ match authoritative_v4_patch_for_object(
record_key.clone(),
partition.clone(),
- object,
+ &projection_object,
) {
Ok(mutation) => Some(mutation),
Err(()) => Some(ProjectionMutation::MarkIncomplete {
record_key,
- profile: vocabulary::profile_v3(),
+ profile: vocabulary::profile_v4(),
partition,
kind: ProjectionIncompleteKind::Dirty,
}),
@@ -207,21 +218,21 @@ fn walk_authoritative_object(
Some(selected_document_projection_for_object(
record_key,
partition,
- object,
+ &projection_object,
&projection_fields,
))
} else {
Some(
- complete_v3_projection_for_object(
+ complete_v4_projection_for_object(
record_key.clone(),
partition.clone(),
- object,
+ &projection_object,
None,
)
.map(ProjectionMutation::Replace)
.unwrap_or(ProjectionMutation::MarkIncomplete {
record_key,
- profile: vocabulary::profile_v3(),
+ profile: vocabulary::profile_v4(),
partition,
kind: ProjectionIncompleteKind::IncompatibleVersion,
}),
@@ -306,7 +317,7 @@ fn selected_document_projection_for_object(
) -> ProjectionMutation {
let incomplete = |kind| ProjectionMutation::MarkIncomplete {
record_key: record_key.clone(),
- profile: vocabulary::profile_v3(),
+ profile: vocabulary::profile_v4(),
partition: partition.clone(),
kind,
};
@@ -339,7 +350,7 @@ fn selected_document_projection_for_object(
{
return incomplete(ProjectionIncompleteKind::IncompatibleVersion);
}
- complete_v3_projection_for_object(
+ complete_v4_projection_for_object(
record_key.clone(),
partition.clone(),
object,
@@ -367,6 +378,33 @@ fn insert_authoritative_mutation(
return;
}
+ if let (
+ Some(ProjectionMutation::Patch {
+ exact: prior_exact,
+ integers: prior_integers,
+ sorts: prior_sorts,
+ ..
+ }),
+ ProjectionMutation::Patch {
+ exact,
+ integers,
+ sorts,
+ ..
+ },
+ ) = (mutations.get_mut(&key), &mutation)
+ {
+ prior_exact.retain(|prior| !exact.iter().any(|next| next.attribute == prior.attribute));
+ prior_exact.extend(exact.iter().cloned());
+ prior_integers.retain(|prior| {
+ !integers
+ .iter()
+ .any(|next| next.attribute == prior.attribute)
+ });
+ prior_integers.extend(integers.iter().cloned());
+ prior_sorts.retain(|prior| !sorts.iter().any(|next| next.attribute == prior.attribute));
+ prior_sorts.extend(sorts.iter().cloned());
+ return;
+ }
let existing_is_replace = matches!(mutations.get(&key), Some(ProjectionMutation::Replace(_)));
if matches!(mutation, ProjectionMutation::Replace(_)) || !existing_is_replace {
mutations.insert(key, mutation);
@@ -406,7 +444,7 @@ pub fn optimistic_projection_mutations(
key_text,
OptimisticProjectionMutation::Delete {
record_key,
- profile: vocabulary::profile_v3(),
+ profile: vocabulary::profile_v4(),
partition,
},
);
@@ -428,7 +466,7 @@ pub fn optimistic_projection_mutations(
)
.unwrap_or(OptimisticProjectionMutation::Unknown {
record_key,
- profile: vocabulary::profile_v3(),
+ profile: vocabulary::profile_v4(),
partition,
affected_attributes: Vec::new(),
});
@@ -461,7 +499,7 @@ pub fn dirty_projection_mutations(keys: &[String]) -> Vec<ProjectionMutation> {
let partition = projection_partition(typename)?;
Some(ProjectionMutation::MarkIncomplete {
record_key: RecordKey::new(key.clone()).ok()?,
- profile: vocabulary::profile_v3(),
+ profile: vocabulary::profile_v4(),
partition,
kind: ProjectionIncompleteKind::Dirty,
})
@@ -501,7 +539,7 @@ fn direct_projection_input_for_object(
})
}
-fn complete_v3_projection_for_object(
+fn complete_v4_projection_for_object(
record_key: RecordKey,
partition: Token,
object: &serde_json::Map<String, serde_json::Value>,
@@ -514,10 +552,11 @@ fn complete_v3_projection_for_object(
} else {
None
};
- compose_soup_flat_v3(input, sub_type, supplement).map_err(|_| ())
+ let document = compose_soup_flat_v3(input, sub_type, supplement).map_err(|_| ())?;
+ notifications::compose_active_notifications(document, object)
}
-fn authoritative_v3_patch_for_object(
+fn authoritative_v4_patch_for_object(
record_key: RecordKey,
partition: Token,
object: &serde_json::Map<String, serde_json::Value>,
@@ -533,10 +572,10 @@ fn authoritative_v3_patch_for_object(
.any(|field| object.contains_key(*field))
|| (kind == SoupFlatEntityKind::Document
&& (object.contains_key("fileType") || object.contains_key("subType")));
- if !has_direct_patch {
+ if !has_direct_patch && !object.contains_key("notifications") {
return Ok(ProjectionMutation::Patch {
record_key,
- profile: vocabulary::profile_v3(),
+ profile: vocabulary::profile_v4(),
partition,
exact: Vec::new(),
integers: Vec::new(),
@@ -591,9 +630,12 @@ fn authoritative_v3_patch_for_object(
values: document_sub_type_values(value)?,
});
}
+ if object.contains_key("notifications") {
+ exact.extend(notifications::snapshot_patches(&record_key, object)?);
+ }
Ok(ProjectionMutation::Patch {
record_key,
- profile: vocabulary::profile_v3(),
+ profile: vocabulary::profile_v4(),
partition,
exact,
integers,
@@ -638,8 +680,9 @@ fn optimistic_projection_for_object(
object,
Some(created_at_ms),
)
+ && let Ok(document) = compose_soup_flat_v3(input, None, None)
+ && let Ok(document) = notifications::compose_active_notifications(document, object)
{
- let document = compose_soup_flat_v3(input, None, None).ok()?;
return Some(OptimisticProjectionMutation::Replace(document));
}
@@ -695,9 +738,12 @@ fn optimistic_projection_for_object(
values: document_sub_type_values(value).ok()?,
});
}
+ if object.contains_key("notifications") {
+ exact.extend(notifications::snapshot_patches(&record_key, object).ok()?);
+ }
Some(OptimisticProjectionMutation::Patch {
record_key,
- profile: vocabulary::profile_v3(),
+ profile: vocabulary::profile_v4(),
partition,
exact,
integers,
diff --git a/crates/soup_filter_cache_adapter/src/notifications.rs b/crates/soup_filter_cache_adapter/src/notifications.rs
new file mode 100644
index 0000000000..c27ea38730
--- /dev/null
+++ b/crates/soup_filter_cache_adapter/src/notifications.rs
@@ -0,0 +1,428 @@
+//! Notification contributions derived from GraphQL state, never viewing timestamps.
+
+use super::*;
+use cache_core::{
+ normalize::normalize,
+ predicate::ProjectionState,
+ store::Storage,
+ value::{CacheValue, EntityKey, Record},
+};
+use predicate_index::ExactFact;
+
+#[cfg(all(test, not(target_arch = "wasm32")))]
+mod test;
+
+/// Resolve edge and child aliases from the actual selection, not arbitrary payload fields.
+pub(super) fn selected_snapshot(
+ object: &serde_json::Map<String, serde_json::Value>,
+ fields: &[&FieldNode],
+) -> Option<serde_json::Value> {
+ let mut selected = None;
+ for field in fields.iter().filter(|field| field.name == "notifications") {
+ let value = match object
+ .get(&field.response_key)
+ .and_then(serde_json::Value::as_array)
+ {
+ Some(values) => {
+ let mut child_fields = Vec::new();
+ collect_applicable_fields(
+ &field.selection_set,
+ "GraphqlNotification",
+ &mut child_fields,
+ );
+ serde_json::Value::Array(
+ values
+ .iter()
+ .map(|value| {
+ let Some(object) = value.as_object() else {
+ return serde_json::Value::Null;
+ };
+ let mut canonical = serde_json::Map::new();
+ for field in &child_fields {
+ if let Some(value) = object.get(&field.response_key)
+ && canonical
+ .insert(field.name.clone(), value.clone())
+ .is_some_and(|old| old != *value)
+ {
+ return serde_json::Value::Null;
+ }
+ }
+ serde_json::Value::Object(canonical)
+ })
+ .collect(),
+ )
+ }
+ None => serde_json::Value::Null,
+ };
+ if selected.as_ref().is_some_and(|previous| previous != &value) {
+ return Some(serde_json::Value::Null);
+ }
+ selected = Some(value);
+ }
+ selected
+}
+
+/// Complete active-edge snapshot. Empty is authoritative; omitted or malformed is unknown.
+pub(super) fn compose_active_notifications(
+ mut document: IndexDocument,
+ object: &serde_json::Map<String, serde_json::Value>,
+) -> Result<IndexDocument, ()> {
+ document
+ .exact_facts
+ .extend(snapshot_facts(&document.record_key, object)?);
+ document.profile = vocabulary::profile_v4();
+ document.canonicalize();
+ soup_filter_projection::validate_soup_flat_v4(&document).map_err(|_| ())?;
+ Ok(document)
+}
+
+pub(super) fn snapshot_patches(
+ key: &RecordKey,
+ object: &serde_json::Map<String, serde_json::Value>,
+) -> Result<Vec<ExactAttributePatch>, ()> {
+ let facts = snapshot_facts(key, object)?;
+ Ok([
+ vocabulary::notification_unseen(),
+ vocabulary::notification_seen(),
+ ]
+ .into_iter()
+ .map(|attribute| ExactAttributePatch {
+ values: facts
+ .iter()
+ .filter(|fact| fact.attribute == attribute)
+ .map(|fact| fact.value.clone())
+ .collect(),
+ attribute,
+ })
+ .collect())
+}
+
+fn snapshot_facts(
+ key: &RecordKey,
+ object: &serde_json::Map<String, serde_json::Value>,
+) -> Result<Vec<ExactFact>, ()> {
+ let notifications = object
+ .get("notifications")
+ .and_then(serde_json::Value::as_array)
+ .ok_or(())?;
+ let (typename, id) = key.as_str().split_once(':').ok_or(())?;
+ let entity_type = match typename {
+ "GraphqlSoupDocument" => "DOCUMENT",
+ "GraphqlSoupProject" => "PROJECT",
+ "GraphqlSoupChat" => "CHAT",
+ _ => return Err(()),
+ };
+ let mut states = std::collections::BTreeMap::new();
+ for notification in notifications {
+ let notification = notification.as_object().ok_or(())?;
+ // The display edge also contains secondary-entity matches; Soup's SQL
+ // predicate for these three partitions only uses primary association.
+ let primary_id = notification
+ .get("entityId")
+ .and_then(serde_json::Value::as_str)
+ .ok_or(())?;
+ let primary_type = notification
+ .get("entityType")
+ .and_then(serde_json::Value::as_str)
+ .ok_or(())?;
+ if primary_id != id || primary_type != entity_type {
+ continue;
+ }
+ let notification_id = uuid::Uuid::parse_str(
+ notification
+ .get("id")
+ .and_then(serde_json::Value::as_str)
+ .ok_or(())?,
+ )
+ .map_err(|_| ())?;
+ let state = notification
+ .get("state")
+ .and_then(serde_json::Value::as_str)
+ .ok_or(())?;
+ if !matches!(state, "UNSEEN" | "SEEN" | "DONE") {
+ return Err(());
+ }
+ if states
+ .insert(notification_id, state)
+ .is_some_and(|previous| previous != state)
+ {
+ return Err(());
+ }
+ }
+ let mut facts = Vec::new();
+ for (id, state) in states {
+ if let Some(attribute) = state_attribute(state)? {
+ facts.push(member(attribute, id));
+ }
+ }
+ Ok(facts)
+}
+
+fn state_attribute(state: &str) -> Result<Option<Token>, ()> {
+ match state {
+ "UNSEEN" => Ok(Some(vocabulary::notification_unseen())),
+ "SEEN" => Ok(Some(vocabulary::notification_seen())),
+ "DONE" => Ok(None),
+ _ => Err(()),
+ }
+}
+
+fn member(attribute: Token, id: uuid::Uuid) -> ExactFact {
+ ExactFact {
+ attribute,
+ value: ExactValue::new(id.as_bytes()).expect("UUID is bounded"),
+ }
+}
+
+fn association(record: &Record) -> Option<(RecordKey, Token)> {
+ let CacheValue::String(id) = record.fields.get("entityId")? else {
+ return None;
+ };
+ let CacheValue::String(kind) = record.fields.get("entityType")? else {
+ return None;
+ };
+ let typename = match kind.as_str() {
+ "DOCUMENT" => "GraphqlSoupDocument",
+ "PROJECT" => "GraphqlSoupProject",
+ "CHAT" => "GraphqlSoupChat",
+ _ => return None,
+ };
+ uuid::Uuid::parse_str(id).ok()?;
+ Some((
+ RecordKey::new(format!("{typename}:{id}")).ok()?,
+ projection_partition(typename)?,
+ ))
+}
+
+fn change(
+ record_key: RecordKey,
+ partition: Token,
+ id: uuid::Uuid,
+ state: Option<&str>,
+) -> ProjectionMutation {
+ let remove = vec![
+ member(vocabulary::notification_unseen(), id),
+ member(vocabulary::notification_seen(), id),
+ ];
+ let attribute = state.map(state_attribute).transpose();
+ match attribute {
+ Ok(attribute) => ProjectionMutation::PatchExact {
+ record_key,
+ partition,
+ profile: vocabulary::profile_v4(),
+ remove,
+ insert: attribute
+ .flatten()
+ .map(|attribute| member(attribute, id))
+ .into_iter()
+ .collect(),
+ },
+ Err(()) => ProjectionMutation::MarkIncomplete {
+ record_key,
+ partition,
+ profile: vocabulary::profile_v4(),
+ kind: ProjectionIncompleteKind::Dirty,
+ },
+ }
+}
+
+/// Notification identity alone does not establish the parent's projection coverage.
+/// Inbox rows and secondary edges can refer to parents outside the hydrated set;
+/// emitting a patch or invalidation for them would introduce an incomplete marker
+/// and force unrelated local lists to fall back. Full snapshots establish coverage
+/// independently, including when they arrive in the same write as these rows.
+async fn retain_complete_parents<S: Storage>(
+ storage: &S,
+ mutations: Vec<ProjectionMutation>,
+) -> Result<Vec<ProjectionMutation>, SoupFilterCacheAdapterError> {
+ if mutations.is_empty() {
+ return Ok(mutations);
+ }
+ let keys = mutations
+ .iter()
+ .map(|mutation| mutation.record_key().clone())
+ .collect::<std::collections::BTreeSet<_>>()
+ .into_iter()
+ .collect::<Vec<_>>();
+ let states = storage
+ .load_projection_states(&keys)
+ .await
+ .map_err(|e| SoupFilterCacheAdapterError(e.to_string()))?;
+ let states = keys.into_iter().zip(states).collect::<IndexMap<_, _>>();
+ Ok(mutations
+ .into_iter()
+ .filter(|mutation| {
+ let (ProjectionMutation::PatchExact {
+ record_key,
+ profile,
+ partition,
+ ..
+ }
+ | ProjectionMutation::MarkIncomplete {
+ record_key,
+ profile,
+ partition,
+ ..
+ }) = mutation
+ else {
+ unreachable!("notification updates are member edits or invalidation")
+ };
+ matches!(
+ states.get(record_key),
+ Some(Some(ProjectionState::Complete(document)))
+ if document.record_key == *record_key
+ && document.profile == *profile
+ && document.partition == *partition
+ )
+ })
+ .collect())
+}
+
+/// Derive per-notification set edits for complete same-profile parents, resolving
+/// ID-only patches against durable normalized identity. No aggregate snapshot is
+/// stored in an optimistic layer: replay edits only this notification's
+/// contribution, even after another layer fails.
+pub async fn notification_projection_updates<S: Storage>(
+ storage: &S,
+ query: &str,
+ operation_name: Option<&str>,
+ variables: &serde_json::Map<String, serde_json::Value>,
+ data: &serde_json::Value,
+) -> Result<Vec<ProjectionMutation>, SoupFilterCacheAdapterError> {
+ let document =
+ Document::parse(query).map_err(|e| SoupFilterCacheAdapterError(e.to_string()))?;
+ let operation = document
+ .operation(operation_name)
+ .map_err(|e| SoupFilterCacheAdapterError(e.to_string()))?;
+ let updates = normalize(operation, variables, data)
+ .map_err(|e| SoupFilterCacheAdapterError(e.to_string()))?;
+ let updates = updates
+ .into_iter()
+ .filter(|(key, record)| {
+ key.as_ref().starts_with("GraphqlNotification:") && record.fields.contains_key("state")
+ })
+ .collect::<Vec<_>>();
+ let keys = updates
+ .iter()
+ .map(|(key, _)| key.clone())
+ .collect::<Vec<_>>();
+ if keys.is_empty() {
+ return Ok(Vec::new());
+ }
+ let bases = storage
+ .get_batch(&keys)
+ .await
+ .map_err(|e| SoupFilterCacheAdapterError(e.to_string()))?;
+ let mut mutations = Vec::new();
+ for ((key, update), base) in updates.into_iter().zip(bases) {
+ let Some(id) = key
+ .as_ref()
+ .strip_prefix("GraphqlNotification:")
+ .and_then(|id| uuid::Uuid::parse_str(id).ok())
+ else {
+ continue;
+ };
+ let mut record = base.unwrap_or_default();
+ let previous = association(&record);
+ record.merge(update);
+ let next = association(&record);
+ if previous != next
+ && let Some((key, partition)) = previous
+ {
+ mutations.push(change(key, partition, id, None));
+ }
+ if let Some((key, partition)) = next {
+ let state = match record.fields.get("state") {
+ Some(CacheValue::String(state)) => state.as_str(),
+ _ => "",
+ };
+ mutations.push(change(key, partition, id, Some(state)));
+ }
+ }
+ retain_complete_parents(storage, mutations).await
+}
+
+/// Convert deterministic notification contributions into durable optimistic edits.
+///
+/// Returns an error for mutations other than member edits or invalidation.
+pub fn optimistic_notification_updates(
+ updates: Vec<ProjectionMutation>,
+) -> Result<Vec<OptimisticProjectionMutation>, SoupFilterCacheAdapterError> {
+ updates
+ .into_iter()
+ .map(|update| match update {
+ ProjectionMutation::PatchExact {
+ record_key,
+ profile,
+ partition,
+ remove,
+ insert,
+ } => Ok(OptimisticProjectionMutation::PatchExact {
+ record_key,
+ profile,
+ partition,
+ remove,
+ insert,
+ }),
+ ProjectionMutation::MarkIncomplete {
+ record_key,
+ profile,
+ partition,
+ ..
+ } => Ok(OptimisticProjectionMutation::Unknown {
+ record_key,
+ profile,
+ partition,
+ affected_attributes: vec![
+ vocabulary::notification_unseen(),
+ vocabulary::notification_seen(),
+ ],
+ }),
+ ProjectionMutation::Replace(_)
+ | ProjectionMutation::Patch { .. }
+ | ProjectionMutation::Delete(_) => Err(SoupFilterCacheAdapterError(
+ "notification updates must be member edits or invalidation".to_owned(),
+ )),
+ })
+ .collect()
+}
+
+/// Resolve complete parent projections for notification deletion/invalidation
+/// before deleting the normalized notification records.
+pub async fn notification_deletion_updates<S: Storage>(
+ storage: &S,
+ keys: &[String],
+ invalidate: bool,
+) -> Result<Vec<ProjectionMutation>, SoupFilterCacheAdapterError> {
+ let keys = keys
+ .iter()
+ .filter(|key| key.starts_with("GraphqlNotification:"))
+ .map(|key| EntityKey(key.clone().into()))
+ .collect::<Vec<_>>();
+ if keys.is_empty() {
+ return Ok(Vec::new());
+ }
+ let records = storage
+ .get_batch(&keys)
+ .await
+ .map_err(|e| SoupFilterCacheAdapterError(e.to_string()))?;
+ let mutations = keys
+ .into_iter()
+ .zip(records)
+ .filter_map(|(key, record)| {
+ let (parent, partition) = association(&record?)?;
+ if invalidate {
+ return Some(ProjectionMutation::MarkIncomplete {
+ record_key: parent,
+ profile: vocabulary::profile_v4(),
+ partition,
+ kind: ProjectionIncompleteKind::Dirty,
+ });
+ }
+ let id =
+ uuid::Uuid::parse_str(key.as_ref().strip_prefix("GraphqlNotification:")?).ok()?;
+ Some(change(parent, partition, id, None))
+ })
+ .collect();
+ retain_complete_parents(storage, mutations).await
+}
diff --git a/crates/soup_filter_cache_adapter/src/notifications/test.rs b/crates/soup_filter_cache_adapter/src/notifications/test.rs
new file mode 100644
index 0000000000..091f962252
--- /dev/null
+++ b/crates/soup_filter_cache_adapter/src/notifications/test.rs
@@ -0,0 +1,697 @@
+use super::*;
+use cache_core::{
+ engine::{BeginOptimisticWrite, Engine, NetworkWrite},
+ predicate::{PredicateIndexStorage, PredicateQueryResult, ProjectionState},
+ queue::{MutationClaimRequest, MutationClaimToken},
+ store::InMemoryStorage,
+};
+use predicate_index::{
+ IndexQuery, PartitionPredicate, PredicateExpr, SortDirection, ValidatedIndexQuery,
+};
+use serde_json::{Value, json};
+use soup_filter_projection::{SoupCacheProjectionSupplement, encode_cache_projection_supplement};
+
+const D: &str = "00000000-0000-0000-0000-000000000001";
+const A: &str = "00000000-0000-0000-0000-000000000011";
+const B: &str = "00000000-0000-0000-0000-000000000012";
+const C: &str = "00000000-0000-0000-0000-000000000013";
+const SNAPSHOT: &str = r#"query Snapshot { user { id soup(input: { initial: { limit: 20 } }) { items { __typename id cacheProjection notifications { id entityId entityType state } ... on GraphqlSoupDocument { ownerId projectId fileType subType { __typename } createdAt updatedAt } } } } }"#;
+const UPDATE: &str = r#"mutation Update($input: UpdateNotificationsInput!) { updateNotifications(input: $input) { id entityId entityType state } }"#;
+
+fn notification(id: &str, state: &str) -> Value {
+ json!({"__typename":"GraphqlNotification", "id":id, "entityType":"DOCUMENT", "entityId":D, "state":state})
+}
+fn snapshot(notifications: Vec<Value>) -> Value {
+ let capsule = encode_cache_projection_supplement(&SoupCacheProjectionSupplement::document(
+ RecordKey::new(format!("GraphqlSoupDocument:{D}")).unwrap(),
+ false,
+ true,
+ vec![],
+ ))
+ .unwrap();
+ json!({"user":{"id":"macro|[email protected]", "soup":{"items":[{"__typename":"GraphqlSoupDocument", "id":D, "cacheProjection":capsule, "ownerId":"macro|[email protected]", "projectId":null, "fileType":"md", "subType":null, "createdAt":"2025-01-01T00:00:00Z", "updatedAt":"2025-01-02T00:00:00Z", "notifications":notifications}]}}})
+}
+fn variables() -> serde_json::Map<String, Value> {
+ json!({"input":{"notificationIds":[A], "operation":"MARK_DONE"}})
+ .as_object()
+ .unwrap()
+ .clone()
+}
+async fn write<S: Storage>(engine: &mut Engine<S>, query: &str, data: &Value) {
+ let vars = variables();
+ let mut projections = authoritative_projection_mutations(query, None, data).unwrap();
+ projections.extend(
+ notification_projection_updates(engine.storage(), query, None, &vars, data)
+ .await
+ .unwrap(),
+ );
+ engine
+ .write_query_with_registration_and_projections(
+ None,
+ None,
+ NetworkWrite {
+ query,
+ operation_name: None,
+ variables: &vars,
+ data,
+ identity: Some("viewer"),
+ },
+ projections,
+ )
+ .await
+ .unwrap();
+}
+fn query(predicate: PredicateExpr) -> ValidatedIndexQuery {
+ ValidatedIndexQuery::new(IndexQuery {
+ profile: vocabulary::profile_v4(),
+ partitions: vec![PartitionPredicate {
+ partition: vocabulary::document_partition(),
+ predicate,
+ }],
+ sort_attribute: vocabulary::updated_at(),
+ sort_direction: SortDirection::Desc,
+ tie_break_direction: SortDirection::Desc,
+ limit: 20,
+ })
+ .unwrap()
+}
+fn unseen() -> PredicateExpr {
+ PredicateExpr::ExactExists {
+ attribute: vocabulary::notification_unseen(),
+ }
+}
+fn seen() -> PredicateExpr {
+ PredicateExpr::ExactExists {
+ attribute: vocabulary::notification_seen(),
+ }
+}
+async fn matches<S: PredicateIndexStorage>(
+ engine: &mut Engine<S>,
+ predicate: PredicateExpr,
+) -> bool {
+ let result = engine
+ .query_predicate_index(&query(predicate))
+ .await
+ .unwrap()
+ .value;
+ match result {
+ PredicateQueryResult::Complete(keys) | PredicateQueryResult::Optimistic(keys) => {
+ !keys.is_empty()
+ }
+ other => panic!("unexpected {other:?}"),
+ }
+}
+async fn mark_done<S: Storage>(engine: &mut Engine<S>, id: &str, uuid: &str) -> u64 {
+ let data = json!({"updateNotifications":[{"__typename":"GraphqlNotification", "id":id, "state":"DONE"}]});
+ let vars = variables();
+ let updates = optimistic_notification_updates(
+ notification_projection_updates(engine.storage(), UPDATE, None, &vars, &data)
+ .await
+ .unwrap(),
+ )
+ .unwrap();
+ assert_eq!(updates.len(), 1);
+ engine
+ .begin_optimistic_write_with_projections(
+ None,
+ BeginOptimisticWrite {
+ uuid,
+ query: UPDATE,
+ operation_name: None,
+ variables: &vars,
+ data: &data,
+ link_patches: &[],
+ revalidations: &[],
+ created_at_ms: 1,
+ },
+ updates,
+ )
+ .await
+ .unwrap()
+ .0
+}
+async fn claim<S: Storage>(engine: &mut Engine<S>, expected: u64) -> MutationClaimToken {
+ let claimed = engine
+ .claim_next_mutation(MutationClaimRequest {
+ owner: "test".into(),
+ now_ms: 1,
+ lease_expires_at_ms: 1000,
+ })
+ .await
+ .unwrap()
+ .unwrap();
+ assert_eq!(claimed.queued.id, expected);
+ MutationClaimToken {
+ owner: "test".into(),
+ generation: claimed.lease_generation,
+ }
+}
+
+async fn lifecycle<S: PredicateIndexStorage>(storage: S) {
+ let mut engine = Engine::new(storage);
+ write(
+ &mut engine,
+ SNAPSHOT,
+ &snapshot(vec![notification(A, "UNSEEN"), notification(B, "UNSEEN")]),
+ )
+ .await;
+ assert!(matches(&mut engine, unseen()).await);
+ assert!(!matches(&mut engine, seen()).await);
+ let first = mark_done(&mut engine, A, "00000000-0000-0000-0000-000000000101").await;
+ assert!(matches(&mut engine, unseen()).await);
+ let second = mark_done(&mut engine, B, "00000000-0000-0000-0000-000000000102").await;
+ assert!(!matches(&mut engine, unseen()).await);
+ // Durable reopen restores both independent member edits.
+ let mut engine = Engine::new(engine.into_storage());
+ assert!(!matches(&mut engine, unseen()).await);
+ let token = claim(&mut engine, first).await;
+ engine
+ .rollback_optimistic_write(first, token)
+ .await
+ .unwrap();
+ assert!(
+ matches(&mut engine, unseen()).await,
+ "A restored while B remains done"
+ );
+ // Realtime changes authority underneath B's pending member removal.
+ write(
+ &mut engine,
+ UPDATE,
+ &json!({"updateNotifications":[notification(A,"SEEN")]}),
+ )
+ .await;
+ assert!(!matches(&mut engine, unseen()).await);
+ assert!(matches(&mut engine, seen()).await);
+ // New notification was never a member of the original display edge.
+ write(
+ &mut engine,
+ UPDATE,
+ &json!({"updateNotifications":[notification(C,"UNSEEN")]}),
+ )
+ .await;
+ assert!(
+ matches(
+ &mut engine,
+ PredicateExpr::And(Box::new(unseen()), Box::new(seen()))
+ )
+ .await
+ );
+ // Refetch must preserve B's pending mark-done, not restore stale membership.
+ write(
+ &mut engine,
+ SNAPSHOT,
+ &snapshot(vec![
+ notification(A, "SEEN"),
+ notification(B, "UNSEEN"),
+ notification(C, "UNSEEN"),
+ ]),
+ )
+ .await;
+ let token = claim(&mut engine, second).await;
+ let data = json!({"updateNotifications":[notification(B,"DONE")]});
+ let projections =
+ notification_projection_updates(engine.storage(), UPDATE, None, &variables(), &data)
+ .await
+ .unwrap();
+ engine
+ .commit_optimistic_write_with_projections(
+ second,
+ token,
+ UPDATE,
+ None,
+ &variables(),
+ &data,
+ projections,
+ )
+ .await
+ .unwrap();
+ let key = format!("GraphqlNotification:{C}");
+ let projections =
+ notification_deletion_updates(engine.storage(), std::slice::from_ref(&key), false)
+ .await
+ .unwrap();
+ engine
+ .delete_keys_with_projection_changes(&[EntityKey(key.into())], projections)
+ .await
+ .unwrap();
+ assert!(!matches(&mut engine, unseen()).await);
+ // Active-edge refresh omits done B. Reopen must insert B without that edge link.
+ write(
+ &mut engine,
+ SNAPSHOT,
+ &snapshot(vec![notification(A, "SEEN")]),
+ )
+ .await;
+ write(
+ &mut engine,
+ UPDATE,
+ &json!({"updateNotifications":[notification(A,"DONE")]}),
+ )
+ .await;
+ assert!(!matches(&mut engine, seen()).await);
+ write(
+ &mut engine,
+ UPDATE,
+ &json!({"updateNotifications":[notification(B,"SEEN")]}),
+ )
+ .await;
+ assert!(matches(&mut engine, seen()).await);
+ assert!(matches(&mut engine, PredicateExpr::Not(Box::new(unseen()))).await);
+ // A different viewer cannot inherit notification facts or pending layers.
+ engine
+ .write_query(
+ None,
+ SNAPSHOT,
+ None,
+ &variables(),
+ &snapshot(vec![]),
+ Some("other-viewer"),
+ )
+ .await
+ .unwrap();
+ assert!(!matches(&mut engine, seen()).await);
+}
+
+#[test]
+fn member_lifecycle_in_memory() {
+ pollster::block_on(lifecycle(InMemoryStorage::new()));
+}
+#[test]
+fn member_lifecycle_real_turso() {
+ pollster::block_on(async {
+ lifecycle(cache_turso::TursoStorage::open_in_memory("notification-members").unwrap()).await
+ });
+}
+
+async fn unhydrated_parents<S: PredicateIndexStorage>(storage: S) {
+ let mut engine = Engine::new(storage);
+ let local_query = ValidatedIndexQuery::new(IndexQuery {
+ profile: vocabulary::profile_v4(),
+ partitions: [
+ vocabulary::document_partition(),
+ vocabulary::project_partition(),
+ vocabulary::chat_partition(),
+ ]
+ .into_iter()
+ .map(|partition| PartitionPredicate {
+ partition,
+ predicate: PredicateExpr::All,
+ })
+ .collect(),
+ sort_attribute: vocabulary::updated_at(),
+ sort_direction: SortDirection::Desc,
+ tie_break_direction: SortDirection::Desc,
+ limit: 20,
+ })
+ .unwrap();
+ let hydrated_key = RecordKey::new(format!("GraphqlSoupDocument:{D}")).unwrap();
+ for (kind, typename) in [
+ ("DOCUMENT", "GraphqlSoupDocument"),
+ ("PROJECT", "GraphqlSoupProject"),
+ ("CHAT", "GraphqlSoupChat"),
+ ] {
+ let parent_key = RecordKey::new(format!("{typename}:{B}")).unwrap();
+ let mut secondary = notification(A, "UNSEEN");
+ secondary["entityId"] = json!(B);
+ secondary["entityType"] = json!(kind);
+ // The display edge hydrates D, not this notification's primary parent.
+ write(&mut engine, SNAPSHOT, &snapshot(vec![secondary.clone()])).await;
+ assert_eq!(
+ engine
+ .query_predicate_index(&local_query)
+ .await
+ .unwrap()
+ .value,
+ PredicateQueryResult::Complete(vec![hydrated_key.clone()]),
+ "secondary {kind} must not force unrelated lists to fall back"
+ );
+ assert!(!matches(&mut engine, unseen()).await);
+
+ // A mixed inbox response must still patch hydrated primary parents.
+ write(
+ &mut engine,
+ UPDATE,
+ &json!({"updateNotifications":[secondary.clone(), notification(C, "SEEN")]}),
+ )
+ .await;
+ assert!(matches(&mut engine, seen()).await);
+ assert!(!matches(&mut engine, unseen()).await);
+ for state in ["DONE", "UNSEEN", "INVALID"] {
+ let data = json!({"updateNotifications":[{"__typename":"GraphqlNotification", "id":A, "state":state}]});
+ let updates = notification_projection_updates(
+ engine.storage(),
+ UPDATE,
+ None,
+ &variables(),
+ &data,
+ )
+ .await
+ .unwrap();
+ assert!(updates.is_empty(), "ID-only {kind} update: {state}");
+ assert!(optimistic_notification_updates(updates).unwrap().is_empty());
+ write(&mut engine, UPDATE, &data).await;
+ }
+ let keys = vec![format!("GraphqlNotification:{A}")];
+ for invalidate in [false, true] {
+ assert!(
+ notification_deletion_updates(engine.storage(), &keys, invalidate)
+ .await
+ .unwrap()
+ .is_empty(),
+ "deletion/invalidation must not introduce {kind} projection state"
+ );
+ }
+ assert_eq!(
+ engine
+ .storage()
+ .load_projection_states(&[parent_key])
+ .await
+ .unwrap(),
+ vec![None]
+ );
+ // Identity is retained: reassociation can add to and remove from D,
+ // without introducing a projection for the unhydrated next parent.
+ write(
+ &mut engine,
+ UPDATE,
+ &json!({"updateNotifications":[notification(A, "UNSEEN")]}),
+ )
+ .await;
+ assert!(matches(&mut engine, unseen()).await);
+ write(
+ &mut engine,
+ UPDATE,
+ &json!({"updateNotifications":[secondary]}),
+ )
+ .await;
+ assert!(!matches(&mut engine, unseen()).await);
+ assert!(matches(&mut engine, seen()).await);
+ let mut reopened = Engine::new(engine.into_storage());
+ assert_eq!(
+ reopened
+ .query_predicate_index(&local_query)
+ .await
+ .unwrap()
+ .value,
+ PredicateQueryResult::Complete(vec![hydrated_key.clone()])
+ );
+ engine = reopened;
+ }
+}
+
+#[test]
+fn unhydrated_notification_parents_in_memory() {
+ pollster::block_on(unhydrated_parents(InMemoryStorage::new()));
+}
+
+#[test]
+fn unhydrated_notification_parents_real_turso() {
+ pollster::block_on(async {
+ unhydrated_parents(
+ cache_turso::TursoStorage::open_in_memory("unhydrated-notification-parents").unwrap(),
+ )
+ .await
+ });
+}
+
+async fn nonmatching_parent_projections<S: Storage>(mut storage: S) {
+ let mutations = authoritative_projection_mutations(SNAPSHOT, None, &snapshot(vec![])).unwrap();
+ let [ProjectionMutation::Replace(document)] = mutations.as_slice() else {
+ panic!("complete base")
+ };
+ let mut old_profile = document.clone();
+ old_profile.profile = vocabulary::profile_v3();
+ let mut wrong_partition = document.clone();
+ wrong_partition.partition = vocabulary::project_partition();
+ let mut bases = vec![
+ ProjectionMutation::Replace(old_profile),
+ ProjectionMutation::Replace(wrong_partition),
+ ];
+ bases.extend(
+ [
+ ProjectionIncompleteKind::Missing,
+ ProjectionIncompleteKind::Dirty,
+ ProjectionIncompleteKind::IncompatibleVersion,
+ ]
+ .into_iter()
+ .map(|kind| ProjectionMutation::MarkIncomplete {
+ record_key: document.record_key.clone(),
+ profile: document.profile.clone(),
+ partition: document.partition.clone(),
+ kind,
+ }),
+ );
+ for base in bases {
+ storage
+ .put_batch_with_projections(vec![], vec![base])
+ .await
+ .unwrap();
+ let before = storage
+ .load_projection_states(std::slice::from_ref(&document.record_key))
+ .await
+ .unwrap();
+ let mut engine = Engine::new(storage);
+ write(
+ &mut engine,
+ UPDATE,
+ &json!({"updateNotifications":[notification(A, "UNSEEN")]}),
+ )
+ .await;
+ let keys = vec![format!("GraphqlNotification:{A}")];
+ for invalidate in [false, true] {
+ assert!(
+ notification_deletion_updates(engine.storage(), &keys, invalidate)
+ .await
+ .unwrap()
+ .is_empty()
+ );
+ }
+ assert_eq!(
+ engine
+ .storage()
+ .load_projection_states(std::slice::from_ref(&document.record_key))
+ .await
+ .unwrap(),
+ before,
+ "notification rows must neither promote incomplete parents nor overwrite other profiles/partitions"
+ );
+ storage = engine.into_storage();
+ }
+}
+
+#[test]
+fn nonmatching_notification_parent_projections_in_memory() {
+ pollster::block_on(nonmatching_parent_projections(InMemoryStorage::new()));
+}
+
+#[test]
+fn nonmatching_notification_parent_projections_real_turso() {
+ pollster::block_on(async {
+ nonmatching_parent_projections(
+ cache_turso::TursoStorage::open_in_memory("nonmatching-notification-parents").unwrap(),
+ )
+ .await
+ });
+}
+
+#[test]
+fn optimistic_notification_conversion_preserves_member_edits_and_invalidation() {
+ let key = RecordKey::new(format!("GraphqlSoupDocument:{D}")).unwrap();
+ let partition = vocabulary::document_partition();
+ let id = uuid::Uuid::parse_str(A).unwrap();
+ assert!(optimistic_notification_updates(vec![]).unwrap().is_empty());
+ assert_eq!(
+ optimistic_notification_updates(vec![
+ change(key.clone(), partition.clone(), id, Some("SEEN")),
+ change(key.clone(), partition.clone(), id, Some("INVALID")),
+ ])
+ .unwrap(),
+ vec![
+ OptimisticProjectionMutation::PatchExact {
+ record_key: key.clone(),
+ profile: vocabulary::profile_v4(),
+ partition: partition.clone(),
+ remove: vec![
+ member(vocabulary::notification_unseen(), id),
+ member(vocabulary::notification_seen(), id),
+ ],
+ insert: vec![member(vocabulary::notification_seen(), id)],
+ },
+ OptimisticProjectionMutation::Unknown {
+ record_key: key,
+ profile: vocabulary::profile_v4(),
+ partition,
+ affected_attributes: vec![
+ vocabulary::notification_unseen(),
+ vocabulary::notification_seen(),
+ ],
+ },
+ ]
+ );
+}
+
+#[test]
+fn optimistic_notification_conversion_rejects_unsupported_mutations() {
+ let mutations = authoritative_projection_mutations(SNAPSHOT, None, &snapshot(vec![])).unwrap();
+ let [ProjectionMutation::Replace(document)] = mutations.as_slice() else {
+ panic!("complete snapshot")
+ };
+ for unsupported in [
+ ProjectionMutation::Replace(document.clone()),
+ ProjectionMutation::Patch {
+ record_key: document.record_key.clone(),
+ profile: document.profile.clone(),
+ partition: document.partition.clone(),
+ exact: vec![],
+ integers: vec![],
+ sorts: vec![],
+ },
+ ProjectionMutation::Delete(document.record_key.clone()),
+ ] {
+ // A supported prefix must not hide an unsupported mutation in the batch.
+ let supported = change(
+ document.record_key.clone(),
+ document.partition.clone(),
+ uuid::Uuid::parse_str(A).unwrap(),
+ Some("DONE"),
+ );
+ let error = optimistic_notification_updates(vec![supported, unsupported]).unwrap_err();
+ assert_eq!(
+ error.to_string(),
+ "notification updates must be member edits or invalidation"
+ );
+ }
+}
+
+#[test]
+fn snapshot_completeness_aliases_primary_scope_and_bounds() {
+ let data = snapshot(vec![notification(A, "UNSEEN"), notification(B, "SEEN")]);
+ let mutations = authoritative_projection_mutations(SNAPSHOT, None, &data).unwrap();
+ let [ProjectionMutation::Replace(document)] = mutations.as_slice() else {
+ panic!("complete snapshot")
+ };
+ assert!(document.matches(&unseen()) && document.matches(&seen()));
+ for missing in ["state", "entityId", "entityType", "id"] {
+ let mut data = data.clone();
+ data["user"]["soup"]["items"][0]["notifications"][0]
+ .as_object_mut()
+ .unwrap()
+ .remove(missing);
+ assert!(matches!(
+ authoritative_projection_mutations(SNAPSHOT, None, &data)
+ .unwrap()
+ .as_slice(),
+ [ProjectionMutation::MarkIncomplete { .. }]
+ ));
+ }
+ let mut omitted = data.clone();
+ omitted["user"]["soup"]["items"][0]
+ .as_object_mut()
+ .unwrap()
+ .remove("notifications");
+ assert!(matches!(
+ authoritative_projection_mutations(SNAPSHOT, None, &omitted)
+ .unwrap()
+ .as_slice(),
+ [ProjectionMutation::MarkIncomplete { .. }]
+ ));
+ let mut secondary = notification(A, "UNSEEN");
+ secondary["entityId"] = json!(B);
+ let mutations =
+ authoritative_projection_mutations(SNAPSHOT, None, &snapshot(vec![secondary])).unwrap();
+ let [ProjectionMutation::Replace(document)] = mutations.as_slice() else {
+ panic!("complete secondary edge")
+ };
+ assert!(!document.matches(&unseen()));
+ let alias_query = SNAPSHOT.replace(
+ "notifications { id entityId entityType state }",
+ "notifs: notifications { id entityId entityType lifecycle: state }",
+ );
+ let mut alias_data = data.clone();
+ let entity = alias_data["user"]["soup"]["items"][0]
+ .as_object_mut()
+ .unwrap();
+ let mut rows = entity.remove("notifications").unwrap();
+ for row in rows.as_array_mut().unwrap() {
+ let row = row.as_object_mut().unwrap();
+ let state = row.remove("state").unwrap();
+ row.insert("lifecycle".into(), state);
+ }
+ entity.insert("notifs".into(), rows);
+ assert_eq!(
+ authoritative_projection_mutations(alias_query.as_str(), None, &alias_data).unwrap(),
+ authoritative_projection_mutations(SNAPSHOT, None, &data).unwrap()
+ );
+ let too_many = (1..=256)
+ .map(|n| notification(&uuid::Uuid::from_u128(n + 1000).to_string(), "UNSEEN"))
+ .collect();
+ assert!(matches!(
+ authoritative_projection_mutations(SNAPSHOT, None, &snapshot(too_many))
+ .unwrap()
+ .as_slice(),
+ [ProjectionMutation::MarkIncomplete { .. }]
+ ));
+}
+
+#[test]
+fn compiler_supports_active_states_for_each_indexed_partition_but_rejects_done() {
+ let nil = uuid::Uuid::nil().to_string();
+ let base = json!({
+ "calendarEventFilter":{"literal":{"id":nil}},
+ "documentFilter":{"literal":{"id":nil}},
+ "projectFilter":{"literal":{"projectIdSelf":nil}},
+ "chatFilter":{"literal":{"chatId":nil}},
+ "emailFilter":{"tree":{"literal":{"threadId":nil}}},
+ "channelFilter":{"literal":{"channelId":nil}},
+ "channelThreadFilter":{"literal":{"threadId":nil}},
+ "callFilter":{"literal":{"callId":nil}},
+ "crmCompanyFilter":{"literal":{"id":nil}},
+ "foreignEntityFilter":{"literal":{"id":nil}}
+ });
+ for field in ["documentFilter", "projectFilter", "chatFilter"] {
+ for state in ["UNSEEN", "SEEN", "DONE"] {
+ for negated in [false, true] {
+ let mut filters = base.clone();
+ let expr = json!({"literal":{"notificationState":state}});
+ filters[field] = if negated { json!({"not":expr}) } else { expr };
+ let outcome = compile_filter_request(filters, "UPDATED_AT", "DESC", 20).unwrap();
+ assert_eq!(
+ matches!(outcome, SoupFilterCompileOutcome::Supported(_)),
+ state != "DONE",
+ "{field} {state} not={negated}"
+ );
+ }
+ }
+ }
+}
+
+#[test]
+fn seen_and_reopen_identity_only_optimism_do_not_guess_state() {
+ pollster::block_on(async {
+ let mut engine = Engine::new(InMemoryStorage::new());
+ write(
+ &mut engine,
+ SNAPSHOT,
+ &snapshot(vec![notification(A, "UNSEEN")]),
+ )
+ .await;
+ let data = json!({"updateNotifications":[{"__typename":"GraphqlNotification","id":A}]});
+ assert!(
+ notification_projection_updates(engine.storage(), UPDATE, None, &variables(), &data)
+ .await
+ .unwrap()
+ .is_empty()
+ );
+ let keys = vec![format!("GraphqlNotification:{A}")];
+ let updates = notification_deletion_updates(engine.storage(), &keys, true)
+ .await
+ .unwrap();
+ engine.mark_projections_incomplete(updates).await.unwrap();
+ let state = engine
+ .storage()
+ .load_projection_states(&[RecordKey::new(format!("GraphqlSoupDocument:{D}")).unwrap()])
+ .await
+ .unwrap();
+ assert!(matches!(state[0], Some(ProjectionState::Incomplete { .. })));
+ });
+}
diff --git a/crates/soup_filter_cache_adapter/src/test.rs b/crates/soup_filter_cache_adapter/src/test.rs
index 8e1190a1b3..d8f2d5341f 100644
--- a/crates/soup_filter_cache_adapter/src/test.rs
+++ b/crates/soup_filter_cache_adapter/src/test.rs
@@ -1,7 +1,7 @@
use serde::Deserialize;
use soup_filter_projection::{
SoupCacheProjectionSupplement, decode_cache_projection_supplement,
- encode_cache_projection_supplement, validate_soup_flat_v3,
+ encode_cache_projection_supplement, validate_soup_flat_v4,
};
use std::collections::BTreeMap;
@@ -30,7 +30,7 @@ fn optimistic_soup_payloads_compile_to_durable_projection_layers() {
else {
panic!("partial optimistic Soup entity should compile to a patch");
};
- assert_eq!(profile, &vocabulary::profile_v3());
+ assert_eq!(profile, &vocabulary::profile_v4());
assert!(
exact
.iter()
@@ -63,7 +63,7 @@ fn optimistic_soup_payloads_compile_to_durable_projection_layers() {
else {
panic!("a document create without server facts must patch, not claim completeness");
};
- assert_eq!(profile, &vocabulary::profile_v3());
+ assert_eq!(profile, &vocabulary::profile_v4());
assert!(
exact
.iter()
@@ -79,6 +79,7 @@ fn optimistic_soup_payloads_compile_to_durable_projection_layers() {
&serde_json::json!({
"create": {
"__typename": "GraphqlSoupProject",
+ "notifications": [],
"id": "00000000-0000-0000-0000-000000000003",
"ownerId": "user-1",
"parentId": null,
@@ -88,9 +89,9 @@ fn optimistic_soup_payloads_compile_to_durable_projection_layers() {
456,
);
let [OptimisticProjectionMutation::Replace(complete)] = complete.as_slice() else {
- panic!("a project optimistic create has every required v3 fact");
+ panic!("a project optimistic create has every required v4 fact");
};
- assert_eq!(complete.profile, vocabulary::profile_v3());
+ assert_eq!(complete.profile, vocabulary::profile_v4());
let deletion = optimistic_projection_mutations(
&serde_json::json!({
@@ -161,7 +162,7 @@ fn optimistic_mutations_keep_first_seen_order_and_deletion_precedence() {
}
#[test]
-fn authoritative_direct_fields_without_projection_schema_field_become_v3_patch() {
+fn authoritative_direct_fields_without_projection_schema_field_become_v4_patch() {
let query = r#"query LegacySoup {
user {
soup(input: { limit: 1 }) {
@@ -202,12 +203,12 @@ fn authoritative_direct_fields_without_projection_schema_field_become_v3_patch()
assert!(matches!(
mutations.as_slice(),
[ProjectionMutation::Patch { profile, .. }]
- if profile == &vocabulary::profile_v3()
+ if profile == &vocabulary::profile_v4()
));
}
#[test]
-fn partial_queries_preserve_v3_authority_and_mark_missing_v3() {
+fn partial_queries_preserve_v4_authority_and_mark_missing_v4() {
let id = "00000000-0000-0000-0000-000000000001";
let base_mutations = authoritative_projection_mutations(
SUPPLEMENT_SUBSCRIPTION,
@@ -220,7 +221,7 @@ fn partial_queries_preserve_v3_authority_and_mark_missing_v3() {
)
.unwrap();
let [ProjectionMutation::Replace(base)] = base_mutations.as_slice() else {
- panic!("complete Soup data must hydrate v3 authority");
+ panic!("complete Soup data must hydrate v4 authority");
};
let base = base.clone();
let key = base.record_key.clone();
@@ -262,10 +263,11 @@ fn partial_queries_preserve_v3_authority_and_mark_missing_v3() {
},
] = mutations.as_slice()
else {
- panic!("a projection-less partial query must produce a bounded v3 patch");
+ panic!("a projection-less partial query must produce a bounded v4 patch");
};
- assert_eq!(profile, &vocabulary::profile_v3());
- assert!(exact.is_empty());
+ assert_eq!(profile, &vocabulary::profile_v4());
+ assert_eq!(exact.len(), 2);
+ assert!(exact.iter().all(|patch| patch.values.is_empty()));
assert!(integers.is_empty());
assert!(sorts.is_empty());
@@ -287,7 +289,7 @@ fn partial_queries_preserve_v3_authority_and_mark_missing_v3() {
profile,
kind: ProjectionIncompleteKind::Missing,
..
- }) if profile == &vocabulary::profile_v3()
+ }) if profile == &vocabulary::profile_v4()
));
}
@@ -382,6 +384,7 @@ const SUPPLEMENT_SUBSCRIPTION: &str = r#"subscription Supplement {
__typename
id
cacheProjection @cacheOnly
+ notifications { id entityId entityType state }
... on GraphqlSoupDocument {
ownerId
projectId
@@ -402,6 +405,7 @@ const SUPPLEMENT_BACKFILL: &str = r#"query SoupBackfill {
__typename
id
cacheProjection @cacheOnly
+ notifications { id entityId entityType state }
... on GraphqlSoupDocument {
ownerId
projectId
@@ -443,6 +447,7 @@ fn selected_document(
"__typename": "GraphqlSoupDocument",
"id": id,
"cacheProjection": cache_projection,
+ "notifications": [],
"ownerId": "macro|[email protected]",
"projectId": null,
"fileType": "md",
@@ -478,7 +483,7 @@ fn selected_document_supplement_composes_direct_and_server_owned_facts() {
let [ProjectionMutation::Replace(document)] = mutations.as_slice() else {
panic!("a valid selected supplement and direct fields must replace authority");
};
- assert_eq!(document.profile, vocabulary::profile_v3());
+ assert_eq!(document.profile, vocabulary::profile_v4());
assert_eq!(document.partition, vocabulary::document_partition());
assert!(document.exact_facts.iter().any(|fact| {
fact.attribute == vocabulary::owner()
@@ -584,12 +589,13 @@ fn document_subtype_postings_are_composed_from_graphql_typenames() {
}
#[test]
-fn selected_project_and_chat_null_supplements_are_valid_direct_only_v3_hydration() {
+fn selected_project_and_chat_null_supplements_are_valid_direct_only_v4_hydration() {
let query = r#"query SoupBackfill {
user { soup(input: { initial: { limit: 2 } }) { items {
__typename
id
cacheProjection @cacheOnly
+ notifications { id entityId entityType state }
... on GraphqlSoupProject { ownerId parentId createdAt updatedAt }
... on GraphqlSoupChat { ownerId projectId createdAt updatedAt }
} } }
@@ -603,6 +609,7 @@ fn selected_project_and_chat_null_supplements_are_valid_direct_only_v3_hydration
"__typename": "GraphqlSoupProject",
"id": "00000000-0000-0000-0000-000000000010",
"cacheProjection": null,
+ "notifications": [],
"ownerId": "macro|[email protected]",
"parentId": null,
"createdAt": "2025-01-01T00:00:00Z",
@@ -612,6 +619,7 @@ fn selected_project_and_chat_null_supplements_are_valid_direct_only_v3_hydration
"__typename": "GraphqlSoupChat",
"id": "00000000-0000-0000-0000-000000000011",
"cacheProjection": null,
+ "notifications": [],
"ownerId": "macro|[email protected]",
"projectId": null,
"createdAt": "2025-01-01T00:00:00Z",
@@ -626,7 +634,7 @@ fn selected_project_and_chat_null_supplements_are_valid_direct_only_v3_hydration
let ProjectionMutation::Replace(document) = mutation else {
panic!("direct-only entity must produce a complete replacement");
};
- validate_soup_flat_v3(document).unwrap();
+ validate_soup_flat_v4(document).unwrap();
assert_ne!(document.partition, vocabulary::document_partition());
}
}
@@ -672,7 +680,7 @@ fn missing_malformed_or_mismatched_document_supplements_remain_incomplete() {
matches!(
mutations.as_slice(),
[ProjectionMutation::MarkIncomplete { profile, kind, .. }]
- if profile == &vocabulary::profile_v3() && *kind == expected_kind
+ if profile == &vocabulary::profile_v4() && *kind == expected_kind
),
"{name}: {mutations:?}"
);
@@ -729,7 +737,7 @@ fn backfill_rejects_invalid_supplements_and_missing_direct_document_fields() {
}
#[test]
-fn partial_mutation_payloads_patch_v3_without_fabricating_server_facts() {
+fn partial_mutation_payloads_patch_v4_without_fabricating_server_facts() {
let query = r#"mutation PartialRename($inputs: [RenameEntityInput!]!) {
renameEntities(inputs: $inputs) {
results {
@@ -788,9 +796,9 @@ fn partial_mutation_payloads_patch_v3_without_fabricating_server_facts() {
},
] = mutations.as_slice()
else {
- panic!("partial authoritative entity must produce one v3 patch");
+ panic!("partial authoritative entity must produce one v4 patch");
};
- assert_eq!(profile, &vocabulary::profile_v3());
+ assert_eq!(profile, &vocabulary::profile_v4());
assert!(
exact
.iter()
@@ -933,9 +941,9 @@ fn production_documents_presets_compile_for_created_and_updated_sorts() {
)
.unwrap_or_else(|error| panic!("{name} should materialize: {error}"));
let SoupFilterCompileOutcome::Supported(query) = outcome else {
- panic!("{name} must be soup-flat-v3 eligible");
+ panic!("{name} must be soup-flat-v4 eligible");
};
- assert_eq!(query.as_query().profile, vocabulary::profile_v3(), "{name}");
+ assert_eq!(query.as_query().profile, vocabulary::profile_v4(), "{name}");
assert_eq!(query.as_query().sort_attribute, sort_attribute, "{name}");
assert_eq!(query.as_query().sort_direction, direction, "{name}");
assert_eq!(query.as_query().tie_break_direction, direction, "{name}");
@@ -996,9 +1004,9 @@ fn production_my_tasks_importance_and_status_filter_compiles_locally() {
let SoupFilterCompileOutcome::Supported(query) =
compile_filter_request(filters, "UPDATED_AT", "DESC", 100).unwrap()
else {
- panic!("production My Tasks filter must use the local v3 profile");
+ panic!("production My Tasks filter must use the local v4 profile");
};
- assert_eq!(query.as_query().profile, vocabulary::profile_v3());
+ assert_eq!(query.as_query().profile, vocabulary::profile_v4());
let document = &query.as_query().partitions[0].predicate;
assert!(format!("{document:?}").contains("importance"));
assert!(format!("{document:?}").contains("task-status-option"));
@@ -1039,7 +1047,7 @@ fn differential_document(
}
IndexDocument {
record_key: RecordKey::new(format!("GraphqlSoupDocument:{id}")).unwrap(),
- profile: vocabulary::profile_v3(),
+ profile: vocabulary::profile_v4(),
partition: vocabulary::document_partition(),
exact_facts,
integer_facts: vec![
@@ -1221,7 +1229,7 @@ fn production_documents_membership_matches_postgres_fixture_reference_and_real_t
}
#[test]
-fn production_documents_presets_support_importance_in_v3() {
+fn production_documents_presets_support_importance_in_v4() {
let with_unsupported_sibling = serde_json::json!({
"and": {
"left": { "literal": { "isEmailAttachment": false } },
@@ -1235,9 +1243,9 @@ fn production_documents_presets_support_importance_in_v3() {
100,
)
.unwrap() else {
- panic!("importance must compile in soup-flat-v3");
+ panic!("importance must compile in soup-flat-v4");
};
- assert_eq!(query.as_query().profile, vocabulary::profile_v3());
+ assert_eq!(query.as_query().profile, vocabulary::profile_v4());
}
#[derive(Debug, Deserialize)]
diff --git a/crates/soup_filter_projection/src/lib.rs b/crates/soup_filter_projection/src/lib.rs
index f3f0066df1..78e9d6cb89 100644
--- a/crates/soup_filter_projection/src/lib.rs
+++ b/crates/soup_filter_projection/src/lib.rs
@@ -19,7 +19,9 @@ use thiserror::Error;
mod profile;
mod wire;
-pub use profile::{ProfileValidationError, validate_soup_flat_v2, validate_soup_flat_v3};
+pub use profile::{
+ ProfileValidationError, validate_soup_flat_v2, validate_soup_flat_v3, validate_soup_flat_v4,
+};
pub use wire::{
MAX_SOUP_CACHE_PROJECTION_BYTES, MAX_SOUP_CACHE_PROJECTION_ENCODED_BYTES,
SOUP_CACHE_PROJECTION_WIRE_VERSION, SOUP_CACHE_PROJECTION_WIRE_VERSION_V1,
diff --git a/crates/soup_filter_projection/src/profile.rs b/crates/soup_filter_projection/src/profile.rs
index d0f3d64428..fd3d900611 100644
--- a/crates/soup_filter_projection/src/profile.rs
+++ b/crates/soup_filter_projection/src/profile.rs
@@ -43,6 +43,7 @@ pub enum ProfileValidationError {
enum ProfileVersion {
V2,
V3,
+ V4,
}
#[derive(Clone, Copy, PartialEq, Eq)]
@@ -64,6 +65,11 @@ pub fn validate_soup_flat_v3(document: &IndexDocument) -> Result<(), ProfileVali
validate_soup_flat(document, ProfileVersion::V3)
}
+/// Validate a browser-composed profile with complete active-notification ID sets.
+pub fn validate_soup_flat_v4(document: &IndexDocument) -> Result<(), ProfileValidationError> {
+ validate_soup_flat(document, ProfileVersion::V4)
+}
+
fn validate_soup_flat(
document: &IndexDocument,
version: ProfileVersion,
@@ -72,6 +78,7 @@ fn validate_soup_flat(
let expected_profile = match version {
ProfileVersion::V2 => vocabulary::profile_v2(),
ProfileVersion::V3 => vocabulary::profile_v3(),
+ ProfileVersion::V4 => vocabulary::profile_v4(),
};
if document.profile != expected_profile {
return Err(ProfileValidationError::UnsupportedProfile(
@@ -146,7 +153,7 @@ fn validate_exact_facts(
if !matches!(value, [0] | [1]) {
return Err(ProfileValidationError::InvalidValue("email-attachment"));
}
- } else if version == ProfileVersion::V3
+ } else if matches!(version, ProfileVersion::V3 | ProfileVersion::V4)
&& attribute == &vocabulary::importance()
&& kind == PartitionKind::Document
{
@@ -154,7 +161,7 @@ fn validate_exact_facts(
if !matches!(value, [0] | [1]) {
return Err(ProfileValidationError::InvalidValue("importance"));
}
- } else if version == ProfileVersion::V3
+ } else if matches!(version, ProfileVersion::V3 | ProfileVersion::V4)
&& attribute == &vocabulary::task_status_option()
&& kind == PartitionKind::Document
{
@@ -162,6 +169,21 @@ fn validate_exact_facts(
if value.len() != 16 {
return Err(ProfileValidationError::InvalidValue("task-status-option"));
}
+ } else if version == ProfileVersion::V4
+ && (attribute == &vocabulary::notification_unseen()
+ || attribute == &vocabulary::notification_seen())
+ {
+ if value.len() != 16 {
+ return Err(ProfileValidationError::InvalidValue("notification-id"));
+ }
+ if facts.iter().any(|other| {
+ other.value == fact.value
+ && other.attribute != *attribute
+ && (other.attribute == vocabulary::notification_seen()
+ || other.attribute == vocabulary::notification_unseen())
+ }) {
+ return Err(ProfileValidationError::InvalidValue("notification-state"));
+ }
} else {
return Err(unexpected("exact", attribute));
}
@@ -175,7 +197,7 @@ fn validate_exact_facts(
match kind {
PartitionKind::Document => {
require_one("email-attachment", email_attachment)?;
- if version == ProfileVersion::V3 {
+ if matches!(version, ProfileVersion::V3 | ProfileVersion::V4) {
require_one("importance", importance)?;
if status_options > crate::MAX_TASK_STATUS_OPTION_IDS {
return Err(ProfileValidationError::TooManyValues("task-status-option"));
diff --git a/docs/AGENT_GUIDE/surfaces.md b/docs/AGENT_GUIDE/surfaces.md
index b37d4488c4..ac273e08e4 100644
--- a/docs/AGENT_GUIDE/surfaces.md
+++ b/docs/AGENT_GUIDE/surfaces.md
@@ -22,6 +22,21 @@ Changing filters or resetting the cache discards prior reconciliation evidence.
lists, unsupported filters/sorts, and native/non-cache transports keep their existing
network behavior.
+For Documents (including Tasks), Projects, and Chats, exact `UNSEEN`/`SEEN`
+notification filters also reconcile locally with created/updated timestamp sorts.
+Marking a notification done removes only that notification's contribution immediately;
+other active notifications can keep the entity in the list. Seen/reopen operations
+update filter membership on the authoritative reply, not from a guessed optimistic
+state. Rollback restores only the failed operation's contribution. `DONE` predicates,
+other entity partitions, and notified-at sorting still use the network path.
+
+Notification facts use the existing active-only GraphQL edge and primary entity
+association. Missing/partial or over-budget snapshots remain incomplete, never an
+empty notification set; display metadata decoding omissions remain a best-effort
+limitation. The v4 projection tracks individual notification IDs, bounded by the
+shared 256-fact per-entity budget. This cache-format upgrade resets old cached data
+and pending cache mutations, and the bumped backfill checkpoint rebuilds projections.
+
Realtime Soup batches coalesce repeated entity IDs (including entity type), keeping
that entity's last operation in the batch. Emitted `SoupUpdated` items are non-null.
If viewer-scoped hydration finds no item, the backend logs and omits that update;