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.

feat(data): local first soup filter eval (#5774)

Sean Ayebe3d2ca08719
diff --git a/.config/hakari.toml b/.config/hakari.toml
index 30f76c06b5..a8f5aa5f7d 100644
--- a/.config/hakari.toml
+++ b/.config/hakari.toml
@@ -72,10 +72,21 @@ workspace-members = [
# anyhow, either, nom, tracing, thiserror - is contributed by dozens of
# other members anyway, so the deploy dependency layers are unchanged.
"agent_fold",
+ "graphql_soup_filter_input",
+ "item_filters",
+ "item-filter-index",
+ "predicate-index",
+ "filter_ast",
+ "document_sub_type",
+ "model_file_type",
"macro_user_id",
"macro_uuid",
"non_empty",
"cowlike",
+ # soup-filter-projection is intentionally absent: its wasm-facing adapter
+ # disables the native-only default `models` feature, so the crate itself
+ # does not pull workspace-hack into wasm dependency traversal.
+ "soup-filter-cache-adapter",
]
# Xtask extension (the hakari engine ignores this table; `cargo x deps` in
@@ -86,4 +97,4 @@ workspace-members = [
# via cache-wasm; cache-sqlite ships in the Tauri app, not services). They
# must stay wasm-safe and out of the deploy dependency layers — the glob
# keeps future client crates from silently gaining the workspace-hack dep.
-traversal-exclude-globs = ["crates/client/*"]
+traversal-exclude-globs = ["crates/client/*", "crates/soup_filter_cache_adapter*"]
diff --git a/.github/workspace-dep-closures.json b/.github/workspace-dep-closures.json
index e7b7919d29..8396daf1f0 100644
--- a/.github/workspace-dep-closures.json
+++ b/.github/workspace-dep-closures.json
@@ -953,20 +953,93 @@
],
"cache-core": [
"crates/client/cache-core",
- "crates/maybe_send"
+ "crates/maybe_send",
+ "crates/predicate_index"
],
"cache-turso": [
"crates/client/cache-core",
"crates/client/cache-turso",
"crates/client/turso-opfs",
- "crates/maybe_send"
+ "crates/maybe_send",
+ "crates/predicate_index"
],
"cache-wasm": [
+ "crates/activity",
+ "crates/agent",
+ "crates/ai_toolset",
+ "crates/ai_usage",
+ "crates/attachment",
+ "crates/authentication_service_client",
+ "crates/bot_id",
+ "crates/broadcast",
+ "crates/call",
+ "crates/channel_sender",
+ "crates/channels",
"crates/client/cache-core",
"crates/client/cache-turso",
"crates/client/cache-wasm",
"crates/client/turso-opfs",
- "crates/maybe_send"
+ "crates/connection",
+ "crates/connection_gateway_client",
+ "crates/connection_gateway_models",
+ "crates/contacts",
+ "crates/cowlike",
+ "crates/crm",
+ "crates/document_sub_type",
+ "crates/email",
+ "crates/email_utils",
+ "crates/entity_access",
+ "crates/entity_access_db_utils",
+ "crates/entity_access_management",
+ "crates/entity_mutation",
+ "crates/filter_ast",
+ "crates/frecency",
+ "crates/graphql_common",
+ "crates/graphql_soup_filter_input",
+ "crates/invite_email",
+ "crates/item_filter_index",
+ "crates/item_filters",
+ "crates/kafka_util",
+ "crates/last_online_tracker",
+ "crates/macro_auth",
+ "crates/macro_authorization",
+ "crates/macro_aws_config",
+ "crates/macro_env",
+ "crates/macro_env_var",
+ "crates/macro_event_broker",
+ "crates/macro_event_topics",
+ "crates/macro_service_urls",
+ "crates/macro_user_id",
+ "crates/macro_uuid",
+ "crates/maybe_send",
+ "crates/mention_utils",
+ "crates/model",
+ "crates/model-entity",
+ "crates/model-error-response",
+ "crates/model_file_type",
+ "crates/model_notifications",
+ "crates/model_user",
+ "crates/models_bulk_upload",
+ "crates/models_entity_access_management",
+ "crates/models_pagination",
+ "crates/models_permissions",
+ "crates/models_properties",
+ "crates/models_soup",
+ "crates/non_empty",
+ "crates/notification",
+ "crates/predicate_index",
+ "crates/prompt",
+ "crates/properties",
+ "crates/rate_limit",
+ "crates/reminders",
+ "crates/remote_env_var",
+ "crates/share_permission_db_utils",
+ "crates/soup_filter_cache_adapter",
+ "crates/soup_filter_projection",
+ "crates/sqs_worker",
+ "crates/system_properties",
+ "crates/unfurl",
+ "crates/workspace-hack"
],
"cal": [
"crates/analytics_client",
@@ -1482,6 +1555,7 @@
"crates/graphql_permission",
"crates/graphql_properties",
"crates/graphql_soup",
+ "crates/graphql_soup_filter_input",
"crates/invite_email",
"crates/item_filters",
"crates/kafka_util",
@@ -2147,6 +2221,7 @@
"crates/graphql_permission",
"crates/graphql_properties",
"crates/graphql_soup",
+ "crates/graphql_soup_filter_input",
"crates/import",
"crates/invite_email",
"crates/ip_extractor",
@@ -2267,8 +2342,7 @@
"crates/workspace-hack"
],
"document_sub_type": [
- "crates/document_sub_type",
- "crates/workspace-hack"
+ "crates/document_sub_type"
],
"document_text_extractor": [
"crates/agent",
@@ -3165,8 +3239,7 @@
"crates/workspace-hack"
],
"filter_ast": [
- "crates/filter_ast",
- "crates/workspace-hack"
+ "crates/filter_ast"
],
"foreign_entity": [
"crates/agent",
@@ -3520,6 +3593,7 @@
"crates/graphql_entity_mutation",
"crates/graphql_permission",
"crates/graphql_soup",
+ "crates/graphql_soup_filter_input",
"crates/invite_email",
"crates/item_filters",
"crates/kafka_util",
@@ -3769,6 +3843,7 @@
"crates/graphql_email",
"crates/graphql_permission",
"crates/graphql_soup",
+ "crates/graphql_soup_filter_input",
"crates/invite_email",
"crates/item_filters",
"crates/kafka_util",
@@ -3834,6 +3909,28 @@
"crates/unfurl",
"crates/workspace-hack"
],
+ "graphql_soup_filter_input": [
+ "crates/bot_id",
+ "crates/cowlike",
+ "crates/document_sub_type",
+ "crates/filter_ast",
+ "crates/graphql_common",
+ "crates/graphql_soup_filter_input",
+ "crates/item_filters",
+ "crates/macro_auth",
+ "crates/macro_authorization",
+ "crates/macro_env",
+ "crates/macro_env_var",
+ "crates/macro_user_id",
+ "crates/model-entity",
+ "crates/model-error-response",
+ "crates/model_file_type",
+ "crates/model_user",
+ "crates/models_properties",
+ "crates/non_empty",
+ "crates/remote_env_var",
+ "crates/workspace-hack"
+ ],
"image_optimizer": [
"crates/macro_aws_config",
"crates/macro_entrypoint",
@@ -3969,15 +4066,25 @@
"crates/ip_extractor",
"crates/workspace-hack"
],
- "item_filters": [
+ "item-filter-index": [
"crates/cowlike",
"crates/document_sub_type",
"crates/filter_ast",
+ "crates/item_filter_index",
"crates/item_filters",
"crates/macro_user_id",
"crates/model_file_type",
"crates/non_empty",
- "crates/workspace-hack"
+ "crates/predicate_index"
+ ],
+ "item_filters": [
+ "crates/cowlike",
+ "crates/document_sub_type",
+ "crates/filter_ast",
+ "crates/item_filters",
+ "crates/macro_user_id",
+ "crates/model_file_type",
+ "crates/non_empty"
],
"kafka_util": [
"crates/kafka_util",
@@ -4741,8 +4848,7 @@
"crates/workspace-hack"
],
"model_file_type": [
- "crates/model_file_type",
- "crates/workspace-hack"
+ "crates/model_file_type"
],
"model_notifications": [
"crates/ai_toolset",
@@ -5406,6 +5512,9 @@
"crates/remote_env_var",
"crates/workspace-hack"
],
+ "predicate-index": [
+ "crates/predicate_index"
+ ],
"projects": [
"crates/activity",
"crates/agent",
@@ -6399,6 +6508,151 @@
"crates/unfurl",
"crates/workspace-hack"
],
+ "soup-filter-cache-adapter": [
+ "crates/activity",
+ "crates/agent",
+ "crates/ai_toolset",
+ "crates/ai_usage",
+ "crates/attachment",
+ "crates/authentication_service_client",
+ "crates/bot_id",
+ "crates/broadcast",
+ "crates/call",
+ "crates/channel_sender",
+ "crates/channels",
+ "crates/client/cache-core",
+ "crates/connection",
+ "crates/connection_gateway_client",
+ "crates/connection_gateway_models",
+ "crates/contacts",
+ "crates/cowlike",
+ "crates/crm",
+ "crates/document_sub_type",
+ "crates/email",
+ "crates/email_utils",
+ "crates/entity_access",
+ "crates/entity_access_db_utils",
+ "crates/entity_access_management",
+ "crates/entity_mutation",
+ "crates/filter_ast",
+ "crates/frecency",
+ "crates/graphql_common",
+ "crates/graphql_soup_filter_input",
+ "crates/invite_email",
+ "crates/item_filter_index",
+ "crates/item_filters",
+ "crates/kafka_util",
+ "crates/last_online_tracker",
+ "crates/macro_auth",
+ "crates/macro_authorization",
+ "crates/macro_aws_config",
+ "crates/macro_env",
+ "crates/macro_env_var",
+ "crates/macro_event_broker",
+ "crates/macro_event_topics",
+ "crates/macro_service_urls",
+ "crates/macro_user_id",
+ "crates/macro_uuid",
+ "crates/maybe_send",
+ "crates/mention_utils",
+ "crates/model",
+ "crates/model-entity",
+ "crates/model-error-response",
+ "crates/model_file_type",
+ "crates/model_notifications",
+ "crates/model_user",
+ "crates/models_bulk_upload",
+ "crates/models_entity_access_management",
+ "crates/models_pagination",
+ "crates/models_permissions",
+ "crates/models_properties",
+ "crates/models_soup",
+ "crates/non_empty",
+ "crates/notification",
+ "crates/predicate_index",
+ "crates/prompt",
+ "crates/properties",
+ "crates/rate_limit",
+ "crates/reminders",
+ "crates/remote_env_var",
+ "crates/share_permission_db_utils",
+ "crates/soup_filter_cache_adapter",
+ "crates/soup_filter_projection",
+ "crates/sqs_worker",
+ "crates/system_properties",
+ "crates/unfurl",
+ "crates/workspace-hack"
+ ],
+ "soup-filter-projection": [
+ "crates/activity",
+ "crates/agent",
+ "crates/ai_toolset",
+ "crates/ai_usage",
+ "crates/attachment",
+ "crates/authentication_service_client",
+ "crates/bot_id",
+ "crates/broadcast",
+ "crates/call",
+ "crates/channel_sender",
+ "crates/channels",
+ "crates/connection",
+ "crates/connection_gateway_client",
+ "crates/connection_gateway_models",
+ "crates/contacts",
+ "crates/cowlike",
+ "crates/crm",
+ "crates/document_sub_type",
+ "crates/email",
+ "crates/email_utils",
+ "crates/entity_access",
+ "crates/entity_access_db_utils",
+ "crates/entity_access_management",
+ "crates/entity_mutation",
+ "crates/filter_ast",
+ "crates/frecency",
+ "crates/invite_email",
+ "crates/item_filter_index",
+ "crates/item_filters",
+ "crates/kafka_util",
+ "crates/last_online_tracker",
+ "crates/macro_auth",
+ "crates/macro_authorization",
+ "crates/macro_aws_config",
+ "crates/macro_env",
+ "crates/macro_env_var",
+ "crates/macro_event_broker",
+ "crates/macro_event_topics",
+ "crates/macro_service_urls",
+ "crates/macro_user_id",
+ "crates/macro_uuid",
+ "crates/mention_utils",
+ "crates/model",
+ "crates/model-entity",
+ "crates/model-error-response",
+ "crates/model_file_type",
+ "crates/model_notifications",
+ "crates/model_user",
+ "crates/models_bulk_upload",
+ "crates/models_entity_access_management",
+ "crates/models_pagination",
+ "crates/models_permissions",
+ "crates/models_properties",
+ "crates/models_soup",
+ "crates/non_empty",
+ "crates/notification",
+ "crates/predicate_index",
+ "crates/prompt",
+ "crates/properties",
+ "crates/rate_limit",
+ "crates/reminders",
+ "crates/remote_env_var",
+ "crates/share_permission_db_utils",
+ "crates/soup_filter_projection",
+ "crates/sqs_worker",
+ "crates/system_properties",
+ "crates/unfurl",
+ "crates/workspace-hack"
+ ],
"soup_realtime": [
"crates/activity",
"crates/agent",
diff --git a/Cargo.lock b/Cargo.lock
index 539ec7257b..f2f78324e9 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -2805,6 +2805,7 @@ dependencies = [
"maybe_send",
"pollster",
"postcard",
+ "predicate-index",
"serde",
"serde_json",
"sha2 0.10.9",
@@ -2818,6 +2819,7 @@ dependencies = [
"cache-core",
"maybe_send",
"pollster",
+ "predicate-index",
"serde_json",
"tempfile",
"thiserror 2.0.18",
@@ -2828,15 +2830,17 @@ dependencies = [
[[package]]
name = "cache-wasm"
-version = "0.4.2"
+version = "0.6.3"
dependencies = [
"async-lock",
"cache-core",
"cache-turso",
"js-sys",
+ "predicate-index",
"serde",
"serde-wasm-bindgen",
"serde_json",
+ "soup-filter-cache-adapter",
"turso-opfs",
"wasm-bindgen",
"wasm-bindgen-futures",
@@ -5002,7 +5006,6 @@ dependencies = [
"strum 0.27.2",
"thiserror 2.0.18",
"utoipa",
- "workspace-hack",
]
[[package]]
@@ -6126,7 +6129,6 @@ version = "0.1.0"
dependencies = [
"recursion",
"serde",
- "workspace-hack",
]
[[package]]
@@ -6795,6 +6797,7 @@ dependencies = [
"model_user",
"models_properties",
"rootcause",
+ "serde",
"tokio",
"tracing",
"uuid",
@@ -6923,6 +6926,7 @@ dependencies = [
"graphql_common",
"graphql_email",
"graphql_permission",
+ "graphql_soup_filter_input",
"item_filters",
"macro_authorization",
"macro_user_id",
@@ -6942,6 +6946,24 @@ dependencies = [
"workspace-hack",
]
+[[package]]
+name = "graphql_soup_filter_input"
+version = "0.1.0"
+dependencies = [
+ "async-graphql",
+ "chrono",
+ "document_sub_type",
+ "filter_ast",
+ "graphql_common",
+ "item_filters",
+ "macro_user_id",
+ "model_file_type",
+ "serde",
+ "serde_json",
+ "thiserror 2.0.18",
+ "uuid",
+]
+
[[package]]
name = "group"
version = "0.13.0"
@@ -8255,6 +8277,18 @@ version = "1.70.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "a6cb138bb79a146c1bd460005623e142ef0181e3d0219cb493e02f7d08a35695"
+[[package]]
+name = "item-filter-index"
+version = "0.1.0"
+dependencies = [
+ "chrono",
+ "filter_ast",
+ "item_filters",
+ "predicate-index",
+ "thiserror 2.0.18",
+ "uuid",
+]
+
[[package]]
name = "item_filters"
version = "0.1.0"
@@ -8276,7 +8310,6 @@ dependencies = [
"thiserror 2.0.18",
"utoipa",
"uuid",
- "workspace-hack",
]
[[package]]
@@ -10094,7 +10127,6 @@ dependencies = [
"strum 0.27.2",
"thiserror 2.0.18",
"utoipa",
- "workspace-hack",
]
[[package]]
@@ -12004,6 +12036,16 @@ version = "0.1.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "925383efa346730478fb4838dbe9137d2a47675ad789c546d150a6e1dd4ab31c"
+[[package]]
+name = "predicate-index"
+version = "0.1.0"
+dependencies = [
+ "chrono",
+ "serde",
+ "serde_json",
+ "thiserror 2.0.18",
+]
+
[[package]]
name = "predicates"
version = "3.1.4"
@@ -14770,6 +14812,37 @@ dependencies = [
"workspace-hack",
]
+[[package]]
+name = "soup-filter-cache-adapter"
+version = "0.1.0"
+dependencies = [
+ "cache-core",
+ "chrono",
+ "graphql_soup_filter_input",
+ "indexmap 2.14.0",
+ "item-filter-index",
+ "predicate-index",
+ "serde_json",
+ "soup-filter-projection",
+ "thiserror 2.0.18",
+ "uuid",
+]
+
+[[package]]
+name = "soup-filter-projection"
+version = "0.1.0"
+dependencies = [
+ "chrono",
+ "item-filter-index",
+ "macro_user_id",
+ "model_file_type",
+ "models_soup",
+ "predicate-index",
+ "thiserror 2.0.18",
+ "uuid",
+ "workspace-hack",
+]
+
[[package]]
name = "soup_realtime"
version = "0.1.0"
diff --git a/Cargo.toml b/Cargo.toml
index 8bf0686a66..2fdadf6753 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -39,7 +39,9 @@ members = [
"crates/graphql_permission",
"crates/graphql_properties",
"crates/graphql_soup",
+ "crates/graphql_soup_filter_input",
"crates/import",
+ "crates/item_filter_index",
"crates/integration_tests/local_e2e",
"crates/loops_client",
"crates/macro_authorization",
@@ -53,11 +55,14 @@ members = [
"crates/mcp_select",
"crates/pipedream_mcp",
"crates/onboarding",
+ "crates/predicate_index",
"crates/prompt",
"crates/properties_service",
"crates/reminders",
"crates/search_service",
"crates/skills",
+ "crates/soup_filter_cache_adapter",
+ "crates/soup_filter_projection",
"crates/soup_realtime",
"crates/system_skills",
"crates/task_dedup",
diff --git a/apps/web/docs/entity-filter-cache-index-plan.md b/apps/web/docs/entity-filter-cache-index-plan.md
new file mode 100644
index 0000000000..08c410ff57
--- /dev/null
+++ b/apps/web/docs/entity-filter-cache-index-plan.md
@@ -0,0 +1,460 @@
+# Incremental Exact GraphQL Entity-Filter Cache Index Plan
+
+## Objective
+
+Use the browser's Turso/OPFS-backed normalized GraphQL cache to answer a deliberately bounded subset of Soup GraphQL filter-AST requests exactly and efficiently.
+
+The first release is a complete end-to-end implementation of a small, versioned support profile. It is not an incomplete implementation of every `item_filters::ast::EntityFilterAst` literal. If any part of a request is outside the active profile, the complete request uses the authoritative network path.
+
+This is **not** vector similarity search, fuzzy Quick Access search, or Turso FTS. The first profile uses only exact posting lists, ordered integer facts, and bounded SQL set algebra.
+
+## Product gate
+
+Before expanding the index, measure whether users need the browser to answer previously unseen filters. If immediate reuse of previously fetched requests provides sufficient value, prefer a much smaller query-result cache keyed by the canonical GraphQL filter input, sort, and limit.
+
+The predicate index is justified only when arbitrary supported GraphQL ASTs must be evaluated over entities already present in the local cache. The first indexed profile must ship end to end and demonstrate useful hit rate and latency before more filter families are added.
+
+## Confirmed decisions
+
+1. The canonical browser input is the Soup **GraphQL filter AST**, not the REST `ApiEntityFilterAst` body.
+2. The same `GraphqlEntityFilterAst` value is passed to both the GraphQL network request and the browser index request. The local path must not translate or interpret the REST AST.
+3. Exactness applies to completely indexed entities currently present in the identity-scoped local cache. It does not imply that the cache contains the user's complete server corpus.
+4. Support is all-or-network per request. An unsupported literal, partition, Boolean shape, sort, or input version causes network fallback before index execution. Supported leaves must never be applied while unsupported leaves are ignored.
+5. Dirty, missing, incomplete, or forward-incompatible projections cause network fallback. They must never produce an approximate local page.
+6. The first consumer is `useSoupAstItemsQuery`.
+7. The first support profile is `soup-flat-v1`, defined below. Expansion is profile-versioned and driven by measured frontend request shapes.
+8. Browser Turso/OPFS is the only persistence target. `cache-sqlite` and Tauri are out of scope.
+9. The server remains corpus, authorization, and pagination authority. The first local API returns only an initial placeholder page and has no local continuation cursor.
+10. Supported optimistic direct-field updates are durably reprojected as ordered overlays. Deterministic overlays remain locally queryable offline; query-relevant uncertainty falls back until authoritative settlement.
+11. The existing fuzzy Quick Access search remains separate.
+12. Filter semantics remain isolated from cache and storage implementation details.
+
+## Canonical GraphQL AST boundary
+
+Relevant code:
+
+- `crates/graphql_soup/src/inputs.rs` owns the current private `GraphqlEntityFilterAst` input types and conversion into `item_filters::ast::EntityFilterAst`.
+- `apps/web/src/lib/queries/soup/graphql/ast.ts` currently translates legacy frontend `SoupAstBody` REST syntax into the generated GraphQL input shape.
+- `crates/item_filters/src/ast.rs` defines the materialized domain AST used by authoritative Soup filtering.
+- `apps/web/src/lib/queries/soup/items.ts` is the first integration point.
+
+Extract a lightweight, reusable representation of the GraphQL variables shape and its materialization rules. It must be usable by both the GraphQL server adapter and the browser-side `soup-filter-cache-adapter` without depending on Axum or the GraphQL server runtime.
+
+The canonical flow is:
+
+```text
+frontend filter state
+ │
+ ▼
+GraphqlEntityFilterAst input
+ ├────────────────────► GraphQL Soup request
+ │
+ └────────────────────► browser entity-filter request
+ │
+ ▼
+ shared GraphQL-AST materializer
+ │
+ ▼
+ EntityFilterAst
+ │
+ ▼
+ soup-flat-v1 eligibility/compiler
+```
+
+If legacy callers still produce `SoupAstBody`, `apps/web/src/lib/queries/soup/graphql/ast.ts` may translate it once before this split. The exact output object sent as GraphQL variables must also be sent to the local worker.
+
+The local path must not depend on or reproduce:
+
+- REST field names such as `df`, `pid`, or `ca`;
+- REST compound file-association expansion;
+- REST-only email CRM side fields;
+- `ApiEntityFilterAst` conversion;
+- an independent TypeScript filter matcher.
+
+The REST Soup endpoint may retain its adapter independently; it is not an index ingress contract.
+
+## First support profile: `soup-flat-v1`
+
+### Supported Boolean semantics
+
+The profile supports `And`, `Or`, and `Not` without conversion to DNF, but only when every reachable literal and partition is supported. Normal Boolean simplification of `All` and `None` is allowed.
+
+### Supported partitions and literals
+
+Only flat, record-local facts already present in an authoritative Soup item are eligible initially.
+
+| Partition | Supported literals |
+| --- | --- |
+| Document | `Id`, `FileType`, `ProjectId`, `Owner`, `CreatedAt`, `UpdatedAt` |
+| Project | `ProjectId`, `ProjectIdSelf`, `Owner`, `CreatedAt`, `UpdatedAt` |
+| Chat | `ChatId`, `ProjectId`, `Owner`, `CreatedAt`, `UpdatedAt` |
+
+The only supported sort methods are `CreatedAt` and `UpdatedAt`, in either direction, with the normalized record key as a stable tie-breaker.
+
+Before implementation, inspect representative `useSoupAstItemsQuery` requests and record any constant or mechanically injected GraphQL leaves required to make this profile useful. A constant/no-op leaf may be added to `soup-flat-v1` only when its authoritative behavior is unambiguous and needs no projection fact.
+
+### Partition exclusion and nil sentinels
+
+A missing entity tree means the partition is unrestricted. Therefore, a request with a missing tree for an unsupported partition is not locally eligible.
+
+The compiler may recognize positive nil-ID exclusion sentinels for unsupported partitions so normal Soup requests can prove those partitions empty. This recognition must be conservative:
+
+- a direct positive nil-ID leaf is `None` for a partition whose persisted IDs cannot be nil;
+- an `And` with a proven `None` branch is `None` without interpreting the other branch;
+- `Or`, `Not`, or any shape that could include the unsupported partition causes fallback;
+- negated nil semantics must never be simplified to exclusion.
+
+### Explicitly deferred from `soup-flat-v1`
+
+- global properties;
+- calendar events;
+- emails and email views;
+- channels and channel threads;
+- calls;
+- CRM companies and CRM authorization scope;
+- foreign entities and deduplication;
+- reminders and query-time predicates;
+- notification state;
+- importance, task assignment, and CBM/ATM/NC behavior;
+- attendee, participant, mention, transcript, and other relation-backed predicates;
+- substring text matching;
+- `ViewedAt` and `ViewedUpdated` sorting;
+- local cursor pagination;
+- relation-backed or otherwise non-deterministic optimistic projection state.
+
+These are deferred product capabilities, not silently false predicates.
+
+## Required architecture
+
+```text
+ predicate-index
+ minimal generic flat IR
+ ▲ ▲
+ │ │
+ item-filter-index cache-core
+ profile compiler generic lifecycle/query port
+ │ │
+ soup-filter-projection │
+ direct Soup item facts │
+ │ │
+ GraphQL cache-turso
+ │
+ Turso/OPFS
+
+soup-filter-cache-adapter
+ parse the shared GraphQL input, materialize it, run profile eligibility,
+ derive authoritative/optimistic projections, and pass generic IR through
+ cache-wasm to cache-core
+```
+
+### Dependency rules
+
+- `predicate-index` must not depend on `item_filters`, cache crates, GraphQL, or Turso.
+- `item-filter-index` may depend on `item_filters` and `predicate-index`; it must not depend on cache or Turso crates.
+- The shared GraphQL input/materialization module must not depend on Axum. Browser-compatible code must not require the GraphQL server runtime.
+- `soup-filter-projection` owns business-specific direct fact generation and may depend on Soup/domain models and `item-filter-index`; it must not depend on cache or Turso crates.
+- `cache-core` may depend on `predicate-index`; it must not know Soup entity or literal semantics.
+- `cache-turso` persists and executes generic index operations only. It must not know GraphQL typenames, Soup entity types, or filter literals.
+- `soup-filter-cache-adapter` owns browser-side GraphQL Soup materialization, compilation, typename recognition, and projection derivation. It emits only generic predicate/projection IR.
+- `cache-wasm` is a thin browser composition shell. It may link the Soup adapter into the same WASM binary, but cache engine behavior must operate only on generic predicate/projection IR and must not implement Soup policy.
+- Authorization remains server-side. The local index only evaluates projections delivered through an identity-scoped authorized cache.
+
+## Phase 0: Audit request shapes and set success criteria
+
+Before implementation:
+
+1. collect representative GraphQL filter variables produced for `useSoupAstItemsQuery`;
+2. determine the percentage that `soup-flat-v1` can answer;
+3. identify routinely injected constant or nil-sentinel leaves;
+4. set an initial-page latency target and a minimum useful local-hit-rate target;
+5. decide whether cached query-result reuse would meet the product need more cheaply.
+
+Do not expand semantic scope before this audit. Record the support manifest as GraphQL `Type.field` names, not REST wire tokens.
+
+## Phase 1: Share GraphQL input materialization
+
+Extract the GraphQL filter input representation and conversion currently centered in `crates/graphql_soup/src/inputs.rs`.
+
+Requirements:
+
+- preserve the generated GraphQL variables shape exactly;
+- preserve GraphQL-specific enum, ID, RFC3339, one-of, and CRM validation;
+- convert into the same materialized `EntityFilterAst` used by authoritative Soup;
+- bound AST depth, node count, string length, and aggregate value bytes before expensive compilation;
+- use the same conversion in the GraphQL server and browser composition boundary;
+- add round-trip fixtures using actual generated TypeScript GraphQL variables;
+- do not route the browser through `ApiEntityFilterAst`.
+
+## Phase 2: Add the minimal storage-neutral predicate IR
+
+Create or reduce `predicate-index` to the types needed by `soup-flat-v1`:
+
+```rust
+pub enum PredicateExpr {
+ All,
+ None,
+ Exact {
+ attribute: Token,
+ value: ExactValue,
+ },
+ I64Range {
+ attribute: Token,
+ lower: Option<Bound<i64>>,
+ upper: Option<Bound<i64>>,
+ },
+ And(Box<PredicateExpr>, Box<PredicateExpr>),
+ Or(Box<PredicateExpr>, Box<PredicateExpr>),
+ Not(Box<PredicateExpr>),
+}
+
+pub struct IndexDocument {
+ pub profile: Profile,
+ pub partition: Token,
+ pub exact_facts: Vec<ExactFact>,
+ pub integer_facts: Vec<IntegerFact>,
+ pub sort_facts: Vec<IntegerFact>,
+}
+```
+
+Requirements:
+
+- stable collision-free tokens and canonical dynamic values;
+- microsecond-safe UTC timestamp encoding matching PostgreSQL boundaries;
+- a query descriptor containing profile, partition predicates, sort, stable tie-break direction, and limit;
+- no local cursor in the first profile;
+- bounded validation and Boolean simplification without DNF expansion;
+- a pure reference evaluator for compiler and Turso conformance tests.
+
+Do not add text facts, n-grams, correlated groups, query-time values, scope proofs, result stages, or winner-selection machinery before a supported filter requires them.
+
+## Phase 3: Compile only the supported profile
+
+`item-filter-index` owns opaque partition/attribute vocabulary and compiles materialized `EntityFilterAst` into the minimal generic IR.
+
+Compilation must be two-stage:
+
+1. eligibility checks the complete materialized forest, all partitions, sort, and relevant request options;
+2. compilation runs only after eligibility succeeds.
+
+Use a typed outcome such as:
+
+```rust
+pub enum LocalCompileOutcome {
+ Supported(ValidatedIndexQuery),
+ Unsupported(UnsupportedReason),
+}
+```
+
+Malformed or oversized input remains an error. A well-formed GraphQL filter outside `soup-flat-v1` is `Unsupported` and follows the network path; it is not a user-visible error.
+
+Tests must prove that unsupported leaves under `And`, `Or`, and `Not` cannot disappear through simplification unless a supported `None` branch makes the complete partition mathematically empty.
+
+## Phase 4: Generate compact direct-field projections
+
+Generate a versioned generic projection in `soup-filter-cache-adapter` from the direct fields on each authoritative Document, Project, or Chat GraphQL response. Use the same projection policy for authoritative responses and local optimistic updates. Do not build a second relation-hydration subsystem for the first profile.
+
+The projection may contain only the facts required by `soup-flat-v1`:
+
+- identity;
+- direct owner and project/parent identifiers;
+- document file type;
+- created and updated timestamps;
+- created and updated sort facts.
+
+If a proposed fact is not reliably available on the authoritative Soup item, defer that literal or add the value to authoritative Soup hydration. Do not issue an independent set of relation queries merely to increase local filter coverage.
+
+Select the required direct fields in initial Soup, patch, and mutation-effect fragments capable of replacing supported entities. The browser adapter must require every field needed for a complete projection; missing or malformed direct fields mark the record incomplete rather than producing an empty or partial projection.
+
+Do not expose cache projection facts in the server GraphQL schema. Local-first optimistic writes must be able to recalculate the same facts without a server round trip.
+
+## Phase 5: Add generic cache lifecycle boundaries
+
+Add a generic projection interface to `cache-core`, keeping normalized record and projection changes atomic.
+
+Represent at least:
+
+- `Complete`;
+- `Dirty`;
+- `Missing`;
+- `IncompatibleVersion`.
+
+Rules:
+
+- authoritative replacement with a valid projection atomically replaces prior facts;
+- a potentially relevant update without a valid replacement projection removes queryable facts and marks the record dirty;
+- deletion removes the projection;
+- cache clear removes all projections;
+- deterministic optimistic direct-field writes persist ordered replacement, patch, or deletion overlays alongside the mutation queue;
+- uncertain optimistic writes fall back only when their partition/attribute dependencies intersect the query;
+- any dirty, missing, or incompatible record in a queried partition returns `Incomplete`;
+- unsupported compilation fails before entering `cache-core`.
+
+The first release deliberately prefers broad network fallback over trying to prove that a dirty record could not match.
+
+## Phase 6: Add minimal Turso persistence and SQL evaluation
+
+The first schema needs only:
+
+- index documents with normalized record key, profile, partition, and completeness state;
+- exact facts;
+- integer facts;
+- sort facts.
+
+Use compact integer document IDs and foreign-key cascades. Keep record replacement, projection replacement, mutation settlement, deletion, invalidation, and clear atomic.
+
+Do not add text/ngram, correlated-group, scope-proof, or result-stage tables in `soup-flat-v1`.
+
+Lower generic expressions with bounded parameterized SQL:
+
+| Expression | SQL operation |
+| --- | --- |
+| `Exact` | indexed posting lookup |
+| `I64Range` | indexed ordered-range lookup |
+| `And` | `INTERSECT` |
+| `Or` | `UNION` |
+| `Not` | profile/partition universe `EXCEPT` child |
+| `All` | complete profile/partition universe |
+| `None` | empty relation |
+
+The final query must return normalized record keys, order by the requested created/updated sort fact, use a stable record-key tie-breaker, and apply a bounded initial-page limit. It must not decode or scan normalized `records.value` blobs.
+
+The Turso adapter must not advertise an available exact-query capability until SQL evaluation and completeness checks are implemented. Returning an empty page from an unimplemented evaluator is forbidden.
+
+## Phase 7: Integrate the browser API and first consumer
+
+Add a distinct entity-filter index API rather than extending fuzzy Quick Access search.
+
+The request transports:
+
+- the exact `GraphqlEntityFilterAst` variables value used by the network request;
+- supported sort method and direction;
+- initial-page limit.
+
+At the browser boundary:
+
+1. deserialize and validate the shared GraphQL input;
+2. materialize `EntityFilterAst` with the shared GraphQL conversion;
+3. evaluate `soup-flat-v1` eligibility;
+4. compile a generic query;
+5. call `cache-core` and Turso only for supported requests;
+6. materialize returned normalized keys through generated Soup cache fragments.
+
+`useSoupAstItemsQuery` uses a complete local page as immediate placeholder data and still sends the authoritative GraphQL request. On `Unsupported`, `Incomplete`, incompatibility, validation failure, or storage failure, it follows the existing network path without local placeholder data.
+
+The frontend must not rerun a partial TypeScript matcher over index results.
+
+## Phase 8: Verification and product gate
+
+### GraphQL boundary tests
+
+- generated TypeScript GraphQL variables deserialize through the shared Rust input;
+- server and browser materialization produce identical `EntityFilterAst` values;
+- REST-only shapes are rejected by the local GraphQL boundary;
+- ingress bounds reject pathological inputs before compilation.
+
+### Supported semantic differential tests
+
+For every `soup-flat-v1` literal:
+
+- compare authoritative Soup SQL membership with the reference evaluator and Turso;
+- cover true and false cases;
+- cover all four date bounds at equality boundaries;
+- cover nullable project/parent facts under `Not`;
+- cover nested `And`, `Or`, and `Not`;
+- cover positive nil exclusion and negated nil behavior.
+
+### Unsupported fallback tests
+
+- every deferred entity partition causes `Unsupported` unless conservatively proven empty;
+- every deferred literal causes `Unsupported` in all reachable Boolean positions;
+- global properties and unsupported sorts cause fallback;
+- no unsupported request reaches Turso;
+- no supported subset is returned for a partially supported request.
+
+### Generic and cache tests
+
+- reference evaluator and Turso agree over generated flat documents and expressions;
+- `Not` uses only the complete profile/partition universe;
+- ordering and tie-breaking are stable;
+- record and projection writes are atomic;
+- stale facts disappear on replacement;
+- delete and clear cascade;
+- dirty/missing/incompatible and query-relevant uncertain optimistic states fall back;
+- deterministic optimistic create, patch, and delete overlays survive restart and preserve top-N ordering;
+- physical browser-schema reset remains safe.
+
+### Performance and frontend tests
+
+- `EXPLAIN QUERY PLAN` demonstrates posting/range index use;
+- no normalized record blob scan occurs;
+- browser/OPFS latency meets the Phase 0 target;
+- worker transport and local placeholder materialization work end to end;
+- authoritative network data replaces placeholder data correctly;
+- measured supported-request hit rate meets the Phase 0 threshold.
+
+Do not expand the support profile until this gate passes and an actual local page is observable in the consumer.
+
+## Expansion policy
+
+Add one semantic family at a time, advance the projection profile when facts or semantics change, and retain query-level fallback for older or unsupported profiles.
+
+Suggested order:
+
+1. calendar scalar fields;
+2. simple relation-existence facts such as document email-attachment state;
+3. notification facts with explicit invalidation;
+4. global properties;
+5. reminders and captured query time;
+6. substring text facts and n-grams;
+7. channels and calls;
+8. email correlated message groups;
+9. CRM scope and server-minted authorization/completeness proofs;
+10. CRM-email and foreign-entity post-filter deduplication.
+
+Before adding a family, document:
+
+- demonstrated frontend demand;
+- authoritative semantics;
+- required projection facts;
+- whether facts are record-local or relation-backed;
+- invalidation fan-out;
+- new generic IR/storage capability;
+- differential tests;
+- profile compatibility impact.
+
+Do not add a generic capability speculatively before a supported filter needs it.
+
+## Implementation order and revision discipline
+
+Implement in independently verified revisions:
+
+1. GraphQL request-shape audit and checked-in `soup-flat-v1` support manifest;
+2. shared GraphQL input materialization;
+3. minimal predicate IR and reference evaluator;
+4. supported-profile eligibility and compiler;
+5. compact projections derived locally from GraphQL direct fields;
+6. generic cache lifecycle boundary;
+7. minimal Turso schema, maintenance, and SQL evaluation;
+8. browser protocol and `useSoupAstItemsQuery` integration;
+9. differential, WASM, performance, and product gate.
+
+After each successful verification step, follow repository policy and create a Jujutsu revision with `jj desc -m "..." && jj new`.
+
+## Architectural acceptance criteria
+
+- The local request uses the exact GraphQL filter input object also sent to the server.
+- No REST AST parsing or conversion occurs in the browser index path.
+- No TypeScript reimplementation of filter matching semantics exists.
+- A partially supported request never produces a partial local result.
+- No `item_filters` dependency exists in `cache-core` or `cache-turso`.
+- No entity/literal switch exists in cache or Turso code.
+- No business-specific columns or indexes exist in Turso.
+- No relation-hydration projection subsystem is introduced for `soup-flat-v1`.
+- No text, group, proof, dynamic-time, or winner-selection machinery exists before a supported family requires it.
+- Generic cache orchestration lives in `cache-core`.
+- Generic persistence and query execution live in `cache-turso`.
+- `soup-filter-cache-adapter` owns GraphQL Soup transport materialization and business projection policy.
+- Browser cache shell code only wires adapter output into generic cache APIs; no Soup typename, field, literal, or projection vocabulary switch exists there.
+- Dirty or uncertain local state always falls back to the network.
+- Authorization remains server-side; local indexing does not grant access or widen the cached corpus.
+- The first implementation returns a verified local page through `useSoupAstItemsQuery` before semantic expansion begins.
diff --git a/apps/web/docs/soup-flat-v1-support-manifest.md b/apps/web/docs/soup-flat-v1-support-manifest.md
new file mode 100644
index 0000000000..f8d3b98d10
--- /dev/null
+++ b/apps/web/docs/soup-flat-v1-support-manifest.md
@@ -0,0 +1,129 @@
+# `soup-flat-v1` support manifest and request-shape audit
+
+Status: baseline audit for the incremental exact entity-filter cache index.
+
+## Canonical boundary
+
+The index receives the `filters` object from the same generated
+`GraphqlSoupInput.initial` value sent to `Query.soup`. Names below are GraphQL
+`Type.field` names. REST tokens such as `df`, `pid`, and `ca` are not index
+inputs.
+
+Profile: `soup-flat-v1`
+
+Supported request options:
+
+- `SoupInitialInput.sortMethod`: `CREATED_AT`, `UPDATED_AT`;
+- `SoupInitialInput.sortDirection`: `ASC`, `DESC` (omission means `DESC`);
+- initial requests only, with a bounded limit and no cursor;
+- expanded Soup items (the first consumer materializes generated expanded
+ fragments).
+
+Supported partition literals:
+
+- `GraphqlDocumentLiteral.id`
+- `GraphqlDocumentLiteral.fileType`
+- `GraphqlDocumentLiteral.projectId`
+- `GraphqlDocumentLiteral.owner`
+- `GraphqlDocumentLiteral.createdAt`
+- `GraphqlDocumentLiteral.updatedAt`
+- `GraphqlProjectLiteral.projectId`
+- `GraphqlProjectLiteral.projectIdSelf`
+- `GraphqlProjectLiteral.owner`
+- `GraphqlProjectLiteral.createdAt`
+- `GraphqlProjectLiteral.updatedAt`
+- `GraphqlChatLiteral.chatId`
+- `GraphqlChatLiteral.projectId`
+- `GraphqlChatLiteral.owner`
+- `GraphqlChatLiteral.createdAt`
+- `GraphqlChatLiteral.updatedAt`
+
+Every reachable literal may be combined with GraphQL expression fields `and`,
+`or`, and `not`. No unsupported reachable leaf is ignored.
+
+Optimistic Document, Project, and Chat payloads are projected as durable ordered
+replacement, direct-field patch, or deletion overlays. Missing optimistic
+`updatedAt` values use the queue enqueue time provisionally and are replaced by
+the authoritative timestamp on settlement. Query-relevant uncertainty, more
+than 128 distinct optimistically touched records, or a required overfetch above
+the 500-record query bound causes exact network fallback.
+
+## Conservative unsupported-partition exclusion
+
+The frontend's `defineQueryFilters` mechanically excludes unreferenced entity
+partitions with the nil UUID
+`00000000-0000-0000-0000-000000000000`. The profile recognizes only these
+direct positive leaves as impossible persisted IDs:
+
+- `GraphqlCalendarEventLiteral.id`
+- `GraphqlEmailLiteral.threadId`
+- `GraphqlChannelLiteral.channelId`
+- `GraphqlChannelThreadLiteral.threadId`
+- `GraphqlCallLiteral.callId`
+- `GraphqlCrmCompanyLiteral.id`
+- `GraphqlForeignEntityLiteral.id`
+
+A positive nil leaf proves its partition empty. An `and` containing a proven
+empty branch is empty. `or`, `not`, a missing tree, a non-nil value, or another
+literal does not prove exclusion. Omitted reminder filters retain Soup's
+server-defined default of excluding reminders; any present reminder filter is
+unsupported. An absent `propertiesFilter` is unrestricted; a present one is
+unsupported.
+
+## Representative generated requests
+
+The audit generated `GraphqlSoupInput` values through the production
+`compileToAst` -> `makeGraphqlSoupInput` path, rather than hand-writing REST AST
+shapes.
+
+Eligible examples observed in view presets:
+
+- Agents: owned, running, shared, and automations. These use supported Chat
+ direct fields and nil-exclude all unsupported partitions.
+- Folders: owned and all. These use supported Project direct fields and
+ nil-exclude all unsupported partitions.
+- Documents: folders. This preset proves the Document partition empty and uses
+ supported Project fields.
+
+Common fallback causes observed:
+
+- Inbox: notification, importance, email, channel, channel-thread, and foreign
+ entity literals.
+- Mail: the Email partition.
+- Documents and Tasks: subtype, importance, notification, attachment, and
+ property literals.
+- Channels, Calls, Companies, and Reminders: deferred partitions.
+- Search/all: several deferred partitions and document subtype predicates.
+- Agents/skills: currently cannot be translated to GraphQL because the
+ frontend mapper does not support the `SKILL` document subtype.
+
+With current feature-flag defaults, an admin context, and `UPDATED_AT` sort,
+7 of 36 checked-in view-tab preset shapes (19.4%) satisfy the static profile.
+This is a shape baseline, not production traffic or cache-completeness data.
+Runtime instrumentation must measure the actual eligible and complete hit
+rates before expansion.
+
+Direct call sites outside presets are mixed: contact/company email requests,
+recent-channel requests, and channel attachment requests generally fall back;
+dynamic List exact-ID queries can be eligible only when they select Documents,
+Projects, and/or Chats and conservatively exclude every deferred partition.
+
+## Product decision and success gate
+
+A predicate index is justified for the first experiment because filters are
+user-composed and persisted, while the normalized entities are independently
+backfilled. A query-result cache would accelerate only an identical prior
+request and would not answer a newly composed supported filter over those
+records.
+
+Do not expand `soup-flat-v1` unless production measurements show all of:
+
+- at least 15% of initial flat GraphQL Soup requests are statically eligible;
+- at least 60% of eligible requests have a complete local scope;
+- warm OPFS local-page latency is at most 25 ms at p95 and 50 ms at p99;
+- the local placeholder is observable and is replaced by authoritative network
+ data without ordering or membership divergence.
+
+If the first two thresholds are not met, remove or pause the predicate-index
+experiment and evaluate canonical query-result reuse instead of broadening the
+semantic profile.
diff --git a/apps/web/src/features/property/editors/popover/SelectEditor.tsx b/apps/web/src/features/property/editors/popover/SelectEditor.tsx
index 9e85e4ed51..0f367a35f9 100644
--- a/apps/web/src/features/property/editors/popover/SelectEditor.tsx
+++ b/apps/web/src/features/property/editors/popover/SelectEditor.tsx
@@ -3,6 +3,7 @@ import {
useAddPropertyOptionMutation,
usePropertyOptionsQuery,
} from '@queries/properties/options';
+import { usablePropertyOptions } from '@queries/properties/options-data';
import { onMount, Show } from 'solid-js';
import { useProperty } from '../../core/context';
import type { PropertyApiValues, SelectProperty } from '../../types';
@@ -34,10 +35,7 @@ function SelectEditorBody() {
);
const addOptionMutation = useAddPropertyOptionMutation({});
- const options = () =>
- optionsQuery.isLoading || optionsQuery.isError || !optionsQuery.data
- ? []
- : optionsQuery.data;
+ const options = () => usablePropertyOptions(optionsQuery);
const isLoading = () => optionsQuery.isLoading || addOptionMutation.isPending;
@@ -49,7 +47,6 @@ function SelectEditorBody() {
onMount(() => {
editor.initializeSelectedOptions();
- optionsQuery.refetch();
});
const closeAndSave = async () => {
diff --git a/apps/web/src/lib/graphql-cache/exchange/normalized-cache-exchange.test.ts b/apps/web/src/lib/graphql-cache/exchange/normalized-cache-exchange.test.ts
index ee7776146e..4dea3b61c6 100644
--- a/apps/web/src/lib/graphql-cache/exchange/normalized-cache-exchange.test.ts
+++ b/apps/web/src/lib/graphql-cache/exchange/normalized-cache-exchange.test.ts
@@ -267,6 +267,9 @@ function makeFakeHost(): FakeHost {
async search() {
return { documents: [], nextCursor: null };
},
+ async entityFilter() {
+ return { kind: 'unsupported' };
+ },
async writeQuery(args): Promise<WriteResult> {
host.writes.push({
opKey: args.opKey,
@@ -1081,6 +1084,30 @@ describe('normalizedCacheExchange', () => {
]);
});
+ it('emits an affected cache result while an authoritative query remains in flight', async () => {
+ host.scriptRead({ kind: 'hit', data: { status: 'In Review' } });
+ const { ops, results, forwarded, client } = controlledQueryHarness(host);
+ ops.next(makeOp(8, 'cache-and-network'));
+ await tick();
+
+ expect(forwarded).toHaveLength(1);
+ expect(results.map((result) => [result.data, result.stale])).toEqual([
+ [{ status: 'In Review' }, true],
+ ]);
+
+ host.scriptRead({ kind: 'hit', data: { status: 'Completed' } });
+ host.pushAffected([8]);
+ await tick();
+
+ expect(client.reexecuteOperation).not.toHaveBeenCalled();
+ expect(forwarded).toHaveLength(1);
+ expect(host.reads.at(-1)?.priority).toBe('user-visible');
+ expect(results.map((result) => [result.data, result.stale])).toEqual([
+ [{ status: 'In Review' }, true],
+ [{ status: 'Completed' }, true],
+ ]);
+ });
+
it('registers a slow fallback write without a replacement reread', async () => {
let readCount = 0;
host.readQuery = async (args) => {
@@ -1974,7 +2001,7 @@ describe('normalizedCacheExchange', () => {
expect(host.commits).toHaveLength(0);
});
- it('retains a retryable network failure and still returns the error', async () => {
+ it('retains a retryable network failure as a successful local write', async () => {
const error = new CombinedError({
networkError: new Error('offline'),
});
@@ -1992,31 +2019,46 @@ describe('normalizedCacheExchange', () => {
{ transactionId: 'txn-1', error: error.message },
]);
expect(host.rollbacks).toHaveLength(0);
- expect(results[0]?.error).toBe(error);
+ expect(results[0]?.error).toBeUndefined();
+ expect(results[0]?.data).toEqual(optimistic);
expect(optimisticMutationDispositionOf(results[0])).toEqual({
kind: 'queued',
transactionId: 'txn-1',
});
});
- it('reports a later mutation as queued while a deferred head blocks it', async () => {
+ it('accepts later local writes while a deferred offline head blocks the network', async () => {
const error = new CombinedError({
networkError: new Error('offline'),
});
+ const firstOptimistic = {
+ setEntityProperty: { id: 'prop-1', displayName: 'Doing' },
+ };
+ const secondOptimistic = {
+ setEntityProperty: { id: 'prop-1', displayName: 'Completed' },
+ };
const { ops, results, forwarded } = harness(
host,
(op) => (op.kind === 'mutation' ? { error, data: undefined } : {}),
{ shouldRetryMutation: () => true }
);
- ops.next(makeMutationOp(1, optimistic));
+ ops.next(makeMutationOp(1, firstOptimistic));
await tick();
- ops.next(makeMutationOp(2, optimistic));
+ ops.next(makeMutationOp(2, secondOptimistic));
await tick();
expect(host.claims).toEqual(['txn-1']);
expect(forwarded.map((op) => op.key)).toEqual([1]);
+ expect(host.begins.map((begin) => begin.data)).toEqual([
+ firstOptimistic,
+ secondOptimistic,
+ ]);
expect(results).toHaveLength(2);
+ expect(results[0]?.error).toBeUndefined();
+ expect(results[1]?.error).toBeUndefined();
+ expect(results[0]?.data).toEqual(firstOptimistic);
+ expect(results[1]?.data).toEqual(secondOptimistic);
expect(optimisticMutationDispositionOf(results[1])).toEqual({
kind: 'queued',
transactionId: 'txn-2',
diff --git a/apps/web/src/lib/graphql-cache/exchange/normalized-cache-exchange.ts b/apps/web/src/lib/graphql-cache/exchange/normalized-cache-exchange.ts
index a765f730e8..88d085d228 100644
--- a/apps/web/src/lib/graphql-cache/exchange/normalized-cache-exchange.ts
+++ b/apps/web/src/lib/graphql-cache/exchange/normalized-cache-exchange.ts
@@ -384,6 +384,8 @@ export function normalizedCacheExchange(
return ({ forward, client }) => {
/** Operations registered with the host, for push-driven re-execution. */
const activeOps = new Map<number, Operation>();
+ const { source: affectedResults$, next: emitAffectedResult } =
+ makeSubject<OperationResult>();
type RetainedReplacementFallback = {
version: number;
writeArgs: Parameters<CacheHost['writeQuery']>[0];
@@ -555,12 +557,41 @@ export function normalizedCacheExchange(
});
};
+ const emitAffectedWhileNetworkBound = (key: number): void => {
+ const operation = activeOps.get(key);
+ if (!operation) return;
+ void host
+ .readQuery({
+ opKey: operation.key,
+ query: queryText(operation),
+ operationName: operationName(operation),
+ variables: operation.variables as Record<string, unknown> | undefined,
+ priority: 'user-visible',
+ entityResolvers,
+ })
+ .then((read) => {
+ const active = activeOps.get(key);
+ if (read.kind !== 'hit' || !active) return;
+ // Preserve the authoritative request while immediately surfacing the
+ // newer local view. Its eventual result still gets the deferred
+ // cache reread below when it could not register fresh dependencies.
+ emitAffectedResult(cacheResult(active, read.data, true));
+ })
+ .catch((error) => options.onCacheError?.(error, operation));
+ };
+
const unsubscribePush = host.onOpsAffected((opKeys) => {
for (const key of opKeys) {
if (!activeOps.has(key)) continue;
const state = queryState(key);
if (state.networkBoundQueries > 0) {
state.deferredAffected = true;
+ if (
+ !state.replacementFallback &&
+ !state.retainedReplacementFallback
+ ) {
+ emitAffectedWhileNetworkBound(key);
+ }
continue;
}
const registrationOnly = state.completedReplacementFallback;
@@ -1222,7 +1253,12 @@ export function normalizedCacheExchange(
}
}
void unsubscribePush;
- return merge([cacheResults$, mutationPrep$, forwarded$]);
+ return merge([
+ affectedResults$,
+ cacheResults$,
+ mutationPrep$,
+ forwarded$,
+ ]);
};
};
}
diff --git a/apps/web/src/lib/graphql-cache/exchange/optimistic.ts b/apps/web/src/lib/graphql-cache/exchange/optimistic.ts
index 21e1464945..241cea7292 100644
--- a/apps/web/src/lib/graphql-cache/exchange/optimistic.ts
+++ b/apps/web/src/lib/graphql-cache/exchange/optimistic.ts
@@ -135,8 +135,21 @@ export function withOptimisticMutationDisposition(
result: OperationResult,
disposition: OptimisticMutationDispositionMetadata
): OperationResult {
+ const queuedData =
+ disposition.kind === 'queued'
+ ? optimisticContextOf(result.operation)?.optimisticResponse
+ : undefined;
return {
...result,
+ ...(disposition.kind === 'queued'
+ ? {
+ data: queuedData ?? result.data,
+ // A durable queued mutation is an accepted local write. Preserve the
+ // network failure in queue diagnostics, not as a caller-facing error
+ // that would roll back UI state or block the next edit.
+ error: undefined,
+ }
+ : {}),
extensions: {
...result.extensions,
[OPTIMISTIC_MUTATION_DISPOSITION_KEY]: disposition,
diff --git a/apps/web/src/lib/graphql-cache/host/noop-host.ts b/apps/web/src/lib/graphql-cache/host/noop-host.ts
index a03b9f662e..c1599ebe4a 100644
--- a/apps/web/src/lib/graphql-cache/host/noop-host.ts
+++ b/apps/web/src/lib/graphql-cache/host/noop-host.ts
@@ -31,6 +31,9 @@ export function createNoopCacheHost(reason: string): CacheHost {
async search() {
return { documents: [], nextCursor: null };
},
+ async entityFilter() {
+ return { kind: 'unsupported' };
+ },
async writeQuery(): Promise<WriteResult> {
return emptyWriteResult();
},
diff --git a/apps/web/src/lib/graphql-cache/host/tauri-host.ts b/apps/web/src/lib/graphql-cache/host/tauri-host.ts
index a12c435245..ced191945c 100644
--- a/apps/web/src/lib/graphql-cache/host/tauri-host.ts
+++ b/apps/web/src/lib/graphql-cache/host/tauri-host.ts
@@ -187,6 +187,11 @@ export function createTauriCacheHost(options: TauriHostOptions): CacheHost {
});
},
+ async entityFilter() {
+ // The first profile is browser Turso/OPFS-only.
+ return { kind: 'unsupported' };
+ },
+
async writeQuery(args: CacheWriteArgs): Promise<WriteResult> {
await ready;
return await request<WriteResult>('graphql_cache_write', {
diff --git a/apps/web/src/lib/graphql-cache/host/types.ts b/apps/web/src/lib/graphql-cache/host/types.ts
index 0e85c1c793..34edb45e31 100644
--- a/apps/web/src/lib/graphql-cache/host/types.ts
+++ b/apps/web/src/lib/graphql-cache/host/types.ts
@@ -13,6 +13,8 @@ import type {
CacheReadPriority,
ClaimedMutation,
EnqueueOptimisticMutationResult,
+ EntityFilterCacheArgs,
+ EntityFilterCacheResult,
HydrationResult,
MutationClaim,
MutationSettlement,
@@ -88,6 +90,8 @@ export interface CacheHost {
): Promise<SelectedRecordByKeyWire[]>;
/** Searches the compact write-through materialized projection. */
search(args: SearchCacheArgs): Promise<SearchCachePage>;
+ /** Evaluates an exact initial Soup filter page over complete local projections. */
+ entityFilter(args: EntityFilterCacheArgs): Promise<EntityFilterCacheResult>;
writeQuery(args: CacheWriteArgs): Promise<WriteResult>;
/** Stores a query response and returns only fields not marked `@cacheOnly`. */
hydrateQuery(args: Omit<CacheWriteArgs, 'opKey'>): Promise<HydrationResult>;
diff --git a/apps/web/src/lib/graphql-cache/host/worker-host.ts b/apps/web/src/lib/graphql-cache/host/worker-host.ts
index 8742e634fe..6d7c1c839c 100644
--- a/apps/web/src/lib/graphql-cache/host/worker-host.ts
+++ b/apps/web/src/lib/graphql-cache/host/worker-host.ts
@@ -13,6 +13,8 @@ import {
type CacheResponseErrorCode,
type ClaimedMutation,
type EnqueueOptimisticMutationResult,
+ type EntityFilterCacheArgs,
+ type EntityFilterCacheResult,
type HydrationResult,
isCachePush,
isCacheResponse,
@@ -614,6 +616,7 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {
: msg.kind === 'read' ||
msg.kind === 'read-records-by-keys' ||
msg.kind === 'search' ||
+ msg.kind === 'entity-filter' ||
msg.kind === 'inspect-query' ||
msg.kind === 'inspect-query-variants'
? requestTimeoutMs
@@ -805,6 +808,16 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {
})) as SearchCachePage;
},
+ async entityFilter(
+ args: EntityFilterCacheArgs
+ ): Promise<EntityFilterCacheResult> {
+ await ensureInitialized();
+ return (await request({
+ kind: 'entity-filter',
+ request: args,
+ })) as EntityFilterCacheResult;
+ },
+
async writeQuery(args: CacheWriteArgs): Promise<WriteResult> {
if (args.registerDependencies && args.opKey !== undefined) {
activeOpKeys.add(args.opKey);
diff --git a/apps/web/src/lib/graphql-cache/index.ts b/apps/web/src/lib/graphql-cache/index.ts
index dcbbee8f12..9b0a39ce2a 100644
--- a/apps/web/src/lib/graphql-cache/index.ts
+++ b/apps/web/src/lib/graphql-cache/index.ts
@@ -57,6 +57,8 @@ export type {
CacheRequest,
CacheResponse,
EnqueueOptimisticMutationResult,
+ EntityFilterCacheArgs,
+ EntityFilterCacheResult,
InitialMutationClaim,
MutationSettlement,
OptimisticWriteResult,
diff --git a/apps/web/src/lib/graphql-cache/protocol.ts b/apps/web/src/lib/graphql-cache/protocol.ts
index 870d19ebf7..90f985f889 100644
--- a/apps/web/src/lib/graphql-cache/protocol.ts
+++ b/apps/web/src/lib/graphql-cache/protocol.ts
@@ -51,6 +51,19 @@ export type SearchCachePage = {
nextCursor: SearchCursor | null;
};
+/** Exact initial-page request over the canonical GraphQL Soup filter input. */
+export type EntityFilterCacheArgs = {
+ filters: Record<string, unknown>;
+ sortMethod: 'CREATED_AT' | 'UPDATED_AT' | 'VIEWED_AT' | 'VIEWED_UPDATED';
+ sortDirection: 'ASC' | 'DESC';
+ limit: number;
+};
+
+export type EntityFilterCacheResult =
+ | { kind: 'complete'; keys: string[]; optimistic: boolean }
+ | { kind: 'unsupported' }
+ | { kind: 'incomplete' };
+
export type ReadRecordsByKeysArgs = {
/** Serialized generated fragment document. */
document: string;
@@ -404,6 +417,10 @@ export type CacheRequest = { id: number } & (
kind: 'search';
request: SearchCacheArgs & { nowMs: number };
}
+ | {
+ kind: 'entity-filter';
+ request: EntityFilterCacheArgs;
+ }
| {
kind: 'inspect-query';
query: string;
diff --git a/apps/web/src/lib/graphql-cache/telemetry.ts b/apps/web/src/lib/graphql-cache/telemetry.ts
index 46984db72b..ec40b78630 100644
--- a/apps/web/src/lib/graphql-cache/telemetry.ts
+++ b/apps/web/src/lib/graphql-cache/telemetry.ts
@@ -467,7 +467,13 @@ export function operationCategoryForRequest(
): CacheOperationCategory {
return match(request.kind)
.with('init', () => 'initialization' as const)
- .with('read', 'read-records-by-keys', 'search', () => 'read' as const)
+ .with(
+ 'read',
+ 'read-records-by-keys',
+ 'search',
+ 'entity-filter',
+ () => 'read' as const
+ )
.with('write', 'hydrate', () => 'write' as const)
.with(
'enqueue-optimistic-mutation',
diff --git a/apps/web/src/lib/graphql-cache/worker/coordinator-protocol.ts b/apps/web/src/lib/graphql-cache/worker/coordinator-protocol.ts
index 2a01817709..e7813bf73b 100644
--- a/apps/web/src/lib/graphql-cache/worker/coordinator-protocol.ts
+++ b/apps/web/src/lib/graphql-cache/worker/coordinator-protocol.ts
@@ -520,6 +520,25 @@ export function isCacheRequest(value: unknown): value is CacheRequest {
hasOnlyKeys(value, ['id', 'kind', 'request']) &&
isSearchRequest(value.request)
);
+ case 'entity-filter': {
+ const request = value.request;
+ return (
+ hasOnlyKeys(value, ['id', 'kind', 'request']) &&
+ isRecord(request) &&
+ hasOnlyKeys(request, [
+ 'filters',
+ 'sortMethod',
+ 'sortDirection',
+ 'limit',
+ ]) &&
+ isRecord(request.filters) &&
+ ['CREATED_AT', 'UPDATED_AT', 'VIEWED_AT', 'VIEWED_UPDATED'].includes(
+ request.sortMethod as string
+ ) &&
+ (request.sortDirection === 'ASC' || request.sortDirection === 'DESC') &&
+ isValidCacheSearchLimit(request.limit)
+ );
+ }
case 'inspect-query':
return (
hasOnlyKeys(value, [
diff --git a/apps/web/src/lib/graphql-cache/worker/wasm-module.ts b/apps/web/src/lib/graphql-cache/worker/wasm-module.ts
index b0bebc99a3..df389e562c 100644
--- a/apps/web/src/lib/graphql-cache/worker/wasm-module.ts
+++ b/apps/web/src/lib/graphql-cache/worker/wasm-module.ts
@@ -14,6 +14,8 @@ import type {
CachedQueryVariantWire,
ClaimedMutation,
EnqueueOptimisticMutationResult,
+ EntityFilterCacheArgs,
+ EntityFilterCacheResult,
OptimisticLinkPatchWire,
QueryRevalidationWire,
ReadResult,
@@ -78,6 +80,9 @@ export interface CacheEngine {
search(
request: SearchCacheArgs & { nowMs: number }
): Promise<SearchCachePage>;
+ entityFilter(
+ request: EntityFilterCacheArgs
+ ): Promise<EntityFilterCacheResult>;
writeQuery(
context: {
originOpId?: string;
diff --git a/apps/web/src/lib/graphql-cache/worker/worker-core.ts b/apps/web/src/lib/graphql-cache/worker/worker-core.ts
index b0dbb1fd1b..b047ba269d 100644
--- a/apps/web/src/lib/graphql-cache/worker/worker-core.ts
+++ b/apps/web/src/lib/graphql-cache/worker/worker-core.ts
@@ -9,6 +9,7 @@ import type {
CacheRequest,
CacheResponse,
EnqueueOptimisticMutationResult,
+ EntityFilterCacheResult,
HydrationResult,
ReadResult,
SearchCachePage,
@@ -390,6 +391,11 @@ export class CacheWorkerCore {
);
return result;
})
+ .with({ kind: 'entity-filter' }, async (request) => {
+ const result: EntityFilterCacheResult =
+ await this.requireEngine().entityFilter(request.request);
+ return result;
+ })
.with({ kind: 'write' }, async (request) => {
const engine = this.requireEngine();
const result = await engine.writeQuery(
diff --git a/apps/web/src/lib/queries/properties/options-data.ts b/apps/web/src/lib/queries/properties/options-data.ts
new file mode 100644
index 0000000000..b284ce2964
--- /dev/null
+++ b/apps/web/src/lib/queries/properties/options-data.ts
@@ -0,0 +1,14 @@
+import type { PropertyOption } from '@service-properties/generated/schemas/propertyOption';
+
+const EMPTY_OPTIONS: PropertyOption[] = [];
+
+/**
+ * Keeps the last successful option catalog usable when a background refresh
+ * fails offline. Query errors describe freshness, not invalid cached data.
+ */
+export function usablePropertyOptions(query: {
+ data: PropertyOption[] | undefined;
+ isError: boolean;
+}): PropertyOption[] {
+ return query.data ?? EMPTY_OPTIONS;
+}
diff --git a/apps/web/src/lib/queries/properties/options.test.ts b/apps/web/src/lib/queries/properties/options.test.ts
new file mode 100644
index 0000000000..cbe12cf645
--- /dev/null
+++ b/apps/web/src/lib/queries/properties/options.test.ts
@@ -0,0 +1,26 @@
+import type { PropertyOption } from '@service-properties/generated/schemas/propertyOption';
+import { describe, expect, it } from 'vitest';
+import { usablePropertyOptions } from './options-data';
+
+const cachedOption = {
+ id: 'status-in-progress',
+ property_definition_id: 'status',
+ display_order: 1,
+ created_at: '2025-01-01T00:00:00Z',
+ updated_at: '2025-01-01T00:00:00Z',
+ value: { type: 'string', value: 'In Progress' },
+} satisfies PropertyOption;
+
+describe('usablePropertyOptions', () => {
+ it('retains cached options after an offline refresh failure', () => {
+ const cached = [cachedOption];
+
+ expect(usablePropertyOptions({ data: cached, isError: true })).toBe(cached);
+ });
+
+ it('uses a stable empty catalog before any successful load', () => {
+ expect(usablePropertyOptions({ data: undefined, isError: true })).toEqual(
+ []
+ );
+ });
+});
diff --git a/apps/web/src/lib/queries/soup/graphql/ast.ts b/apps/web/src/lib/queries/soup/graphql/ast.ts
index 8cdc986d18..8179767059 100644
--- a/apps/web/src/lib/queries/soup/graphql/ast.ts
+++ b/apps/web/src/lib/queries/soup/graphql/ast.ts
@@ -16,7 +16,7 @@ import type {
GroupedSoupContinuationInput as GraphqlGroupedSoupContinuationInput,
GroupedSoupInput as GraphqlGroupedSoupInput,
GraphqlProjectLiteral as GraphqlProjectLiteralInput,
- GraphqlPropertiesLiteral as GraphqlPropertiesLiteralInput,
+ GraphqlFilterPropertiesLiteral as GraphqlPropertiesLiteralInput,
GraphqlReminderLiteral as GraphqlReminderLiteralInput,
SoupInitialInput as GraphqlSoupInitialInput,
SoupInput as GraphqlSoupInput,
diff --git a/apps/web/src/lib/queries/soup/graphql/grouped-items.ts b/apps/web/src/lib/queries/soup/graphql/grouped-items.ts
index b67843966a..fcee49443e 100644
--- a/apps/web/src/lib/queries/soup/graphql/grouped-items.ts
+++ b/apps/web/src/lib/queries/soup/graphql/grouped-items.ts
@@ -145,6 +145,7 @@ export function createGraphqlGroupedSoupAstItemsQuery(
isLoading: () => query.isLoading,
isFetching: () => query.isFetching,
isFetchingNextPage: () => false,
+ isPlaceholderData: () => false,
hasNextPage: () => false,
fetchNextPage: async () => undefined,
resetToInitialPage: () => undefined,
diff --git a/apps/web/src/lib/queries/soup/graphql/items.test.ts b/apps/web/src/lib/queries/soup/graphql/items.test.ts
index 074b0ab404..667a6d5883 100644
--- a/apps/web/src/lib/queries/soup/graphql/items.test.ts
+++ b/apps/web/src/lib/queries/soup/graphql/items.test.ts
@@ -10,10 +10,14 @@ import { beforeEach, describe, expect, it, vi } from 'vitest';
import { makeSubject } from 'wonka';
const getGraphqlSoupClientMock = vi.hoisted(() => vi.fn());
+const getGraphqlSoupCacheHostMock = vi.hoisted(() => vi.fn());
+const entityFilterMock = vi.hoisted(() => vi.fn());
+const readRecordsByKeysMock = vi.hoisted(() => vi.fn());
const mapGraphqlSoupPageMock = vi.hoisted(() => vi.fn((data) => data));
const mapSoupPageToEntityListMock = vi.hoisted(() =>
vi.fn((page) => page.items)
);
+const makeGraphqlSoupInputMock = vi.hoisted(() => vi.fn());
vi.mock('@macro-inc/observability', () => ({
Telemetry: { error: vi.fn() },
@@ -23,13 +27,20 @@ vi.mock('@queries/storage/instructions-md', () => ({
useInstructionsMdIdQuery: vi.fn(() => ({})),
}));
+vi.mock('@app/lib/graphql-cache', () => ({
+ selectRecords: vi.fn(() => ({})),
+ readRecordsByKeys: readRecordsByKeysMock,
+}));
+
vi.mock('@service-storage/graphql-soup', () => ({
getGraphqlSoupClient: getGraphqlSoupClientMock,
+ getGraphqlSoupCacheHost: getGraphqlSoupCacheHostMock,
+ mapGraphqlSoupItem: vi.fn((item) => item),
mapGraphqlSoupPage: mapGraphqlSoupPageMock,
}));
vi.mock('./ast', () => ({
- makeGraphqlSoupInput: vi.fn(() => ({ initial: { limit: 50 } })),
+ makeGraphqlSoupInput: makeGraphqlSoupInputMock,
}));
vi.mock('../transform-utils', () => ({
@@ -78,6 +89,139 @@ function makeFakeClient(): {
describe('createGraphqlSoupAstItemsQuery', () => {
beforeEach(() => {
vi.clearAllMocks();
+ getGraphqlSoupCacheHostMock.mockReturnValue(undefined);
+ makeGraphqlSoupInputMock.mockReturnValue({
+ initial: { limit: 50, sortMethod: 'UPDATED_AT' },
+ });
+ });
+
+ it('does not run the local filter for the implicit VIEWED_AT sort', () => {
+ const fake = makeFakeClient();
+ getGraphqlSoupClientMock.mockReturnValue(fake.client);
+ getGraphqlSoupCacheHostMock.mockReturnValue({
+ entityFilter: entityFilterMock,
+ onCacheChanged: () => () => undefined,
+ });
+ makeGraphqlSoupInputMock.mockReturnValue({ initial: { limit: 50 } });
+
+ createRoot((dispose) => {
+ createGraphqlSoupAstItemsQuery(
+ () => ({ params: {}, body: {} }) as never,
+ () => ({ enabled: true })
+ );
+
+ expect(fake.executions).toHaveLength(1);
+ expect(entityFilterMock).not.toHaveBeenCalled();
+ dispose();
+ });
+ });
+
+ it('uses a complete local page as placeholder while authoritative network continues', async () => {
+ const fake = makeFakeClient();
+ getGraphqlSoupClientMock.mockReturnValue(fake.client);
+ getGraphqlSoupCacheHostMock.mockReturnValue({
+ entityFilter: entityFilterMock,
+ onCacheChanged: () => () => undefined,
+ });
+ entityFilterMock.mockResolvedValue({
+ kind: 'complete',
+ keys: ['GraphqlSoupDocument:task-1'],
+ optimistic: false,
+ });
+ readRecordsByKeysMock.mockResolvedValue([
+ {
+ recordKey: 'GraphqlSoupDocument:task-1',
+ record: { id: 'task-1', type: 'document', name: 'Local task' },
+ },
+ ]);
+
+ await new Promise<void>((resolve) => {
+ createRoot((dispose) => {
+ const query = createGraphqlSoupAstItemsQuery(
+ () => ({ params: {}, body: {} }) as never,
+ () => ({ enabled: true })
+ );
+
+ expect(fake.executions).toHaveLength(1);
+ void vi
+ .waitFor(() => {
+ expect(query.isPlaceholderData()).toBe(true);
+ expect(query.data()?.entities[0]?.name).toBe('Local task');
+ })
+ .then(() => {
+ fake.executions[0]?.next({
+ items: [{ id: 'task-1', type: 'document', name: 'Network task' }],
+ next_cursor: null,
+ });
+ expect(query.isPlaceholderData()).toBe(false);
+ expect(query.data()?.entities[0]?.name).toBe('Network task');
+ dispose();
+ resolve();
+ });
+ });
+ });
+ expect(entityFilterMock).toHaveBeenCalled();
+ });
+
+ it('keeps an optimistic local page until cache settlement', async () => {
+ const fake = makeFakeClient();
+ getGraphqlSoupClientMock.mockReturnValue(fake.client);
+ let notifyCacheChanged: () => void = () => undefined;
+ getGraphqlSoupCacheHostMock.mockReturnValue({
+ entityFilter: entityFilterMock,
+ onCacheChanged: (callback: () => void) => {
+ notifyCacheChanged = callback;
+ return () => undefined;
+ },
+ });
+ entityFilterMock
+ .mockResolvedValueOnce({
+ kind: 'complete',
+ keys: ['GraphqlSoupDocument:task-1'],
+ optimistic: true,
+ })
+ .mockResolvedValueOnce({
+ kind: 'complete',
+ keys: ['GraphqlSoupDocument:task-1'],
+ optimistic: false,
+ });
+ readRecordsByKeysMock.mockResolvedValue([
+ {
+ recordKey: 'GraphqlSoupDocument:task-1',
+ record: { id: 'task-1', type: 'document', name: 'Optimistic task' },
+ },
+ ]);
+
+ await new Promise<void>((resolve) => {
+ createRoot((dispose) => {
+ const query = createGraphqlSoupAstItemsQuery(
+ () => ({ params: {}, body: {} }) as never,
+ () => ({ enabled: true })
+ );
+
+ void vi
+ .waitFor(() => {
+ expect(query.data()?.entities[0]?.name).toBe('Optimistic task');
+ expect(query.isPlaceholderData()).toBe(true);
+ })
+ .then(async () => {
+ fake.executions[0]?.next({
+ items: [{ id: 'task-1', type: 'document', name: 'Network task' }],
+ next_cursor: null,
+ });
+ expect(query.data()?.entities[0]?.name).toBe('Optimistic task');
+
+ notifyCacheChanged();
+ await vi.waitFor(() => {
+ expect(entityFilterMock).toHaveBeenCalledTimes(2);
+ expect(query.data()?.entities[0]?.name).toBe('Network task');
+ expect(query.isPlaceholderData()).toBe(false);
+ });
+ dispose();
+ resolve();
+ });
+ });
+ });
});
it('retains identical page projections across cache re-executions', () => {
diff --git a/apps/web/src/lib/queries/soup/graphql/items.ts b/apps/web/src/lib/queries/soup/graphql/items.ts
index 193f2ce8e8..8e8ec1c50e 100644
--- a/apps/web/src/lib/queries/soup/graphql/items.ts
+++ b/apps/web/src/lib/queries/soup/graphql/items.ts
@@ -4,21 +4,33 @@
* directly. The public REST/GraphQL facade lives in ../items.ts.
*/
+import { readRecordsByKeys, selectRecords } from '@app/lib/graphql-cache';
import { createUrqlInfiniteQuery } from '@app/lib/urql-solid';
import { Telemetry } from '@macro-inc/observability';
import { useInstructionsMdIdQuery } from '@queries/storage/instructions-md';
import {
SoupDocument,
+ SoupItemFieldsFragmentDoc,
type SoupQuery,
type SoupQueryVariables,
} from '@service-storage/graphql/generated/graphql';
import type { GraphqlSoupInput } from '@service-storage/graphql-soup';
import {
+ getGraphqlSoupCacheHost,
getGraphqlSoupClient,
+ mapGraphqlSoupItem,
mapGraphqlSoupPage,
} from '@service-storage/graphql-soup';
import type { CombinedError } from '@urql/core';
-import { type Accessor, createComputed, createMemo, on } from 'solid-js';
+import {
+ type Accessor,
+ createComputed,
+ createEffect,
+ createMemo,
+ createSignal,
+ on,
+ onCleanup,
+} from 'solid-js';
import type { SoupAstBody, SoupAstItemsData, SoupAstParams } from '../items';
import { mapSoupPageToEntityList } from '../transform-utils';
import { makeGraphqlSoupInput } from './ast';
@@ -43,6 +55,7 @@ export type GraphqlSoupAstItemsQuery = {
isLoading: Accessor<boolean>;
isFetching: Accessor<boolean>;
isFetchingNextPage: Accessor<boolean>;
+ isPlaceholderData: Accessor<boolean>;
hasNextPage: Accessor<boolean>;
fetchNextPage: () => Promise<void>;
/** Discards loaded continuation pages while retaining the initial page. */
@@ -72,6 +85,78 @@ export function createGraphqlSoupAstItemsQuery(
const firstPageInput = createMemo(() => inputForCursor(null));
const isSupported = () => firstPageInput() !== undefined;
+ const [localPlaceholder, setLocalPlaceholder] = createSignal<
+ { data: SoupAstItemsData; optimistic: boolean } | undefined
+ >();
+ const [cacheRevision, setCacheRevision] = createSignal(0);
+ const soupItemSelection = selectRecords(SoupItemFieldsFragmentDoc);
+ let localRequest = 0;
+
+ createEffect(() => {
+ const host = getGraphqlSoupCacheHost();
+ if (!host) return;
+ const unsubscribe = host.onCacheChanged(() => {
+ setCacheRevision((revision) => revision + 1);
+ });
+ onCleanup(unsubscribe);
+ });
+
+ createEffect(() => {
+ cacheRevision();
+ const requestId = ++localRequest;
+ setLocalPlaceholder(undefined);
+ const input = firstPageInput();
+ const queryOptions = options();
+ const host = getGraphqlSoupCacheHost();
+ if (!queryOptions.enabled || !input || !host || !('initial' in input))
+ return;
+ const initial = input.initial;
+ if (!initial) return;
+ const filters = initial.filters ?? {};
+ const sortMethod = initial.sortMethod;
+ if (!sortMethod || sortMethod === 'VIEWED_AT') return;
+ const sortDirection = initial.sortDirection ?? 'DESC';
+ const limit = initial.limit ?? 20;
+
+ void host
+ .entityFilter({ filters, sortMethod, sortDirection, limit })
+ .then(async (result) => {
+ if (result.kind !== 'complete' || requestId !== localRequest) return;
+ const selected = await readRecordsByKeys(
+ host,
+ soupItemSelection,
+ result.keys
+ );
+ if (
+ requestId !== localRequest ||
+ selected.length !== result.keys.length
+ )
+ return;
+ const items = selected.flatMap(({ record }) => {
+ const item = mapGraphqlSoupItem(record);
+ return item ? [item] : [];
+ });
+ if (items.length !== result.keys.length) return;
+ setLocalPlaceholder({
+ optimistic: result.optimistic,
+ data: {
+ entities: mapSoupPageToEntityList(
+ { items, next_cursor: undefined },
+ {
+ instructionsIdQuery,
+ showSupportedForeignEntities:
+ queryOptions.showSupportedForeignEntities,
+ }
+ ),
+ groups: undefined,
+ },
+ });
+ })
+ .catch(() => {
+ // Unsupported, incomplete, validation, and storage failures all use
+ // the already-running authoritative network request.
+ });
+ });
const query = createUrqlInfiniteQuery<
SoupQuery,
@@ -121,13 +206,22 @@ export function createGraphqlSoupAstItemsQuery(
);
return {
- data: () => query.data,
+ data: () => {
+ const local = localPlaceholder();
+ return local?.optimistic ? local.data : (query.data ?? local?.data);
+ },
error,
isSupported,
isEnabled: () => query.isEnabled,
- isLoading: () => query.isLoading,
+ isLoading: () => query.isLoading && localPlaceholder() === undefined,
isFetching: () => query.isFetching,
isFetchingNextPage: () => query.isFetchingNextPage,
+ isPlaceholderData: () => {
+ const local = localPlaceholder();
+ return (
+ local !== undefined && (query.data === undefined || local.optimistic)
+ );
+ },
hasNextPage: () => query.hasNextPage,
fetchNextPage: async () => {
await query.fetchNextPage();
diff --git a/apps/web/src/lib/queries/soup/items.ts b/apps/web/src/lib/queries/soup/items.ts
index 2c4ab5092f..04638683cc 100644
--- a/apps/web/src/lib/queries/soup/items.ts
+++ b/apps/web/src/lib/queries/soup/items.ts
@@ -410,7 +410,9 @@ export function useSoupAstItemsQuery(
: restQuery.isFetching;
},
get isPlaceholderData() {
- return usesGraphql() ? false : restQuery.isPlaceholderData;
+ return usesGraphql()
+ ? activeGraphqlQuery().isPlaceholderData()
+ : restQuery.isPlaceholderData;
},
get isFetchingNextPage() {
return usesGraphql()
diff --git a/apps/web/src/lib/service-clients/service-storage/graphql/generated/graphql.ts b/apps/web/src/lib/service-clients/service-storage/graphql/generated/graphql.ts
index b3bfdbfdc2..7e93770615 100644
--- a/apps/web/src/lib/service-clients/service-storage/graphql/generated/graphql.ts
+++ b/apps/web/src/lib/service-clients/service-storage/graphql/generated/graphql.ts
@@ -62,21 +62,21 @@ export type EntitySharePolicyInput = {
/** The two operands of a recursive `CalendarEventFilterExpr` binary expression. */
export type GraphqlCalendarEventBinaryExpr = {
- /** The left-hand expression. */
+ /** Left expression. */
left: GraphqlCalendarEventExpr;
- /** The right-hand expression. */
+ /** Right expression. */
right: GraphqlCalendarEventExpr;
};
/** A recursive `CalendarEventFilterExpr` filter expression. */
export type GraphqlCalendarEventExpr =
- { /** Matches when both expressions match. */
+ { /** Both expressions must match. */
and: GraphqlCalendarEventBinaryExpr; literal?: never; not?: never; or?: never; }
- | { and?: never; /** Matches a domain-specific literal condition. */
+ | { and?: never; /** Match a literal. */
literal: GraphqlCalendarEventLiteral; not?: never; or?: never; }
- | { and?: never; literal?: never; /** Negates an expression. */
+ | { and?: never; literal?: never; /** Negate an expression. */
not: GraphqlCalendarEventExpr; or?: never; }
- | { and?: never; literal?: never; not?: never; /** Matches when either expression matches. */
+ | { and?: never; literal?: never; not?: never; /** Either expression may match. */
or: GraphqlCalendarEventBinaryExpr; };
/** GraphQL input representing a calendar event literal. */
@@ -100,21 +100,21 @@ export type GraphqlCalendarEventLiteral =
/** The two operands of a recursive `CallFilterExpr` binary expression. */
export type GraphqlCallBinaryExpr = {
- /** The left-hand expression. */
+ /** Left expression. */
left: GraphqlCallExpr;
- /** The right-hand expression. */
+ /** Right expression. */
right: GraphqlCallExpr;
};
/** A recursive `CallFilterExpr` filter expression. */
export type GraphqlCallExpr =
- { /** Matches when both expressions match. */
+ { /** Both expressions must match. */
and: GraphqlCallBinaryExpr; literal?: never; not?: never; or?: never; }
- | { and?: never; /** Matches a domain-specific literal condition. */
+ | { and?: never; /** Match a literal. */
literal: GraphqlCallLiteral; not?: never; or?: never; }
- | { and?: never; literal?: never; /** Negates an expression. */
+ | { and?: never; literal?: never; /** Negate an expression. */
not: GraphqlCallExpr; or?: never; }
- | { and?: never; literal?: never; not?: never; /** Matches when either expression matches. */
+ | { and?: never; literal?: never; not?: never; /** Either expression may match. */
or: GraphqlCallBinaryExpr; };
/** GraphQL input representing the call literal. */
@@ -141,21 +141,21 @@ export type GraphqlCallStatus =
/** The two operands of a recursive `ChannelFilterExpr` binary expression. */
export type GraphqlChannelBinaryExpr = {
- /** The left-hand expression. */
+ /** Left expression. */
left: GraphqlChannelExpr;
- /** The right-hand expression. */
+ /** Right expression. */
right: GraphqlChannelExpr;
};
/** A recursive `ChannelFilterExpr` filter expression. */
export type GraphqlChannelExpr =
- { /** Matches when both expressions match. */
+ { /** Both expressions must match. */
and: GraphqlChannelBinaryExpr; literal?: never; not?: never; or?: never; }
- | { and?: never; /** Matches a domain-specific literal condition. */
+ | { and?: never; /** Match a literal. */
literal: GraphqlChannelLiteral; not?: never; or?: never; }
- | { and?: never; literal?: never; /** Negates an expression. */
+ | { and?: never; literal?: never; /** Negate an expression. */
not: GraphqlChannelExpr; or?: never; }
- | { and?: never; literal?: never; not?: never; /** Matches when either expression matches. */
+ | { and?: never; literal?: never; not?: never; /** Either expression may match. */
or: GraphqlChannelBinaryExpr; };
/** GraphQL input representing the channel literal. */
@@ -189,21 +189,21 @@ export type GraphqlChannelLiteral =
/** The two operands of a recursive `ChannelThreadFilterExpr` binary expression. */
export type GraphqlChannelThreadBinaryExpr = {
- /** The left-hand expression. */
+ /** Left expression. */
left: GraphqlChannelThreadExpr;
- /** The right-hand expression. */
+ /** Right expression. */
right: GraphqlChannelThreadExpr;
};
/** A recursive `ChannelThreadFilterExpr` filter expression. */
export type GraphqlChannelThreadExpr =
- { /** Matches when both expressions match. */
+ { /** Both expressions must match. */
and: GraphqlChannelThreadBinaryExpr; literal?: never; not?: never; or?: never; }
- | { and?: never; /** Matches a domain-specific literal condition. */
+ | { and?: never; /** Match a literal. */
literal: GraphqlChannelThreadLiteral; not?: never; or?: never; }
- | { and?: never; literal?: never; /** Negates an expression. */
+ | { and?: never; literal?: never; /** Negate an expression. */
not: GraphqlChannelThreadExpr; or?: never; }
- | { and?: never; literal?: never; not?: never; /** Matches when either expression matches. */
+ | { and?: never; literal?: never; not?: never; /** Either expression may match. */
or: GraphqlChannelThreadBinaryExpr; };
/** GraphQL input representing the channel thread literal. */
@@ -234,21 +234,21 @@ export type GraphqlChannelTypeFilter =
/** The two operands of a recursive `ChatFilterExpr` binary expression. */
export type GraphqlChatBinaryExpr = {
- /** The left-hand expression. */
+ /** Left expression. */
left: GraphqlChatExpr;
- /** The right-hand expression. */
+ /** Right expression. */
right: GraphqlChatExpr;
};
/** A recursive `ChatFilterExpr` filter expression. */
export type GraphqlChatExpr =
- { /** Matches when both expressions match. */
+ { /** Both expressions must match. */
and: GraphqlChatBinaryExpr; literal?: never; not?: never; or?: never; }
- | { and?: never; /** Matches a domain-specific literal condition. */
+ | { and?: never; /** Match a literal. */
literal: GraphqlChatLiteral; not?: never; or?: never; }
- | { and?: never; literal?: never; /** Negates an expression. */
+ | { and?: never; literal?: never; /** Negate an expression. */
not: GraphqlChatExpr; or?: never; }
- | { and?: never; literal?: never; not?: never; /** Matches when either expression matches. */
+ | { and?: never; literal?: never; not?: never; /** Either expression may match. */
or: GraphqlChatBinaryExpr; };
/** GraphQL input representing the chat literal. */
@@ -283,21 +283,21 @@ export type GraphqlChatRole =
/** The two operands of a recursive `CrmCompanyFilterExpr` binary expression. */
export type GraphqlCrmCompanyBinaryExpr = {
- /** The left-hand expression. */
+ /** Left expression. */
left: GraphqlCrmCompanyExpr;
- /** The right-hand expression. */
+ /** Right expression. */
right: GraphqlCrmCompanyExpr;
};
/** A recursive `CrmCompanyFilterExpr` filter expression. */
export type GraphqlCrmCompanyExpr =
- { /** Matches when both expressions match. */
+ { /** Both expressions must match. */
and: GraphqlCrmCompanyBinaryExpr; literal?: never; not?: never; or?: never; }
- | { and?: never; /** Matches a domain-specific literal condition. */
+ | { and?: never; /** Match a literal. */
literal: GraphqlCrmCompanyLiteral; not?: never; or?: never; }
- | { and?: never; literal?: never; /** Negates an expression. */
+ | { and?: never; literal?: never; /** Negate an expression. */
not: GraphqlCrmCompanyExpr; or?: never; }
- | { and?: never; literal?: never; not?: never; /** Matches when either expression matches. */
+ | { and?: never; literal?: never; not?: never; /** Either expression may match. */
or: GraphqlCrmCompanyBinaryExpr; };
/** GraphQL input representing the crm company literal. */
@@ -327,21 +327,21 @@ export type GraphqlDateLiteral =
/** The two operands of a recursive `DocumentFilterExpr` binary expression. */
export type GraphqlDocumentBinaryExpr = {
- /** The left-hand expression. */
+ /** Left expression. */
left: GraphqlDocumentExpr;
- /** The right-hand expression. */
+ /** Right expression. */
right: GraphqlDocumentExpr;
};
/** A recursive `DocumentFilterExpr` filter expression. */
export type GraphqlDocumentExpr =
- { /** Matches when both expressions match. */
+ { /** Both expressions must match. */
and: GraphqlDocumentBinaryExpr; literal?: never; not?: never; or?: never; }
- | { and?: never; /** Matches a domain-specific literal condition. */
+ | { and?: never; /** Match a literal. */
literal: GraphqlDocumentLiteral; not?: never; or?: never; }
- | { and?: never; literal?: never; /** Negates an expression. */
+ | { and?: never; literal?: never; /** Negate an expression. */
not: GraphqlDocumentExpr; or?: never; }
- | { and?: never; literal?: never; not?: never; /** Matches when either expression matches. */
+ | { and?: never; literal?: never; not?: never; /** Either expression may match. */
or: GraphqlDocumentBinaryExpr; };
/** GraphQL input representing the document literal. */
@@ -384,21 +384,21 @@ export type GraphqlDocumentSubType =
/** The two operands of a recursive `EmailFilterExpr` binary expression. */
export type GraphqlEmailBinaryExpr = {
- /** The left-hand expression. */
+ /** Left expression. */
left: GraphqlEmailExpr;
- /** The right-hand expression. */
+ /** Right expression. */
right: GraphqlEmailExpr;
};
/** A recursive `EmailFilterExpr` filter expression. */
export type GraphqlEmailExpr =
- { /** Matches when both expressions match. */
+ { /** Both expressions must match. */
and: GraphqlEmailBinaryExpr; literal?: never; not?: never; or?: never; }
- | { and?: never; /** Matches a domain-specific literal condition. */
+ | { and?: never; /** Match a literal. */
literal: GraphqlEmailLiteral; not?: never; or?: never; }
- | { and?: never; literal?: never; /** Negates an expression. */
+ | { and?: never; literal?: never; /** Negate an expression. */
not: GraphqlEmailExpr; or?: never; }
- | { and?: never; literal?: never; not?: never; /** Matches when either expression matches. */
+ | { and?: never; literal?: never; not?: never; /** Either expression may match. */
or: GraphqlEmailBinaryExpr; };
/** GraphQL input representing the email filter ast. */
@@ -500,7 +500,7 @@ export type GraphqlEntityFilterAst = {
/** The project filter to apply. */
projectFilter?: GraphqlProjectExpr | null | undefined;
/** The properties filter to apply. */
- propertiesFilter?: GraphqlPropertiesExpr | null | undefined;
+ propertiesFilter?: GraphqlFilterPropertiesExpr | null | undefined;
/** The reminder filter to apply. */
reminderFilter?: GraphqlReminderExpr | null | undefined;
};
@@ -532,6 +532,8 @@ export type GraphqlEntityReferenceInput = {
/** Canonical entity types accepted by cross-entity APIs. */
export type GraphqlEntityType =
+ /** AI coding agent session entity. */
+ | 'AGENT_SESSION'
/** Calendar event entity. */
| 'CALENDAR_EVENT'
/** Call entity. */
@@ -565,23 +567,82 @@ export type GraphqlEntityType =
/** User entity. */
| 'USER';
+/** The two operands of a recursive `PropertiesFilterExpr` binary expression. */
+export type GraphqlFilterPropertiesBinaryExpr = {
+ /** Left expression. */
+ left: GraphqlFilterPropertiesExpr;
+ /** Right expression. */
+ right: GraphqlFilterPropertiesExpr;
+};
+
+/** A recursive `PropertiesFilterExpr` filter expression. */
+export type GraphqlFilterPropertiesExpr =
+ { /** Both expressions must match. */
+ and: GraphqlFilterPropertiesBinaryExpr; literal?: never; not?: never; or?: never; }
+ | { and?: never; /** Match a literal. */
+ literal: GraphqlFilterPropertiesLiteral; not?: never; or?: never; }
+ | { and?: never; literal?: never; /** Negate an expression. */
+ not: GraphqlFilterPropertiesExpr; or?: never; }
+ | { and?: never; literal?: never; not?: never; /** Either expression may match. */
+ or: GraphqlFilterPropertiesBinaryExpr; };
+
+/** GraphQL input for matching a property value on an entity. */
+export type GraphqlFilterPropertiesLiteral = {
+ /** Optional entity type scope for the property match. */
+ entityType?: GraphqlFilterPropertyEntityType | null | undefined;
+ /** Property definition id to match. */
+ propertyDefinitionId: string | number;
+ /** Value to compare against the property. */
+ value: GraphqlFilterPropertyMatchValue;
+};
+
+/** An entity type supported by property filters. */
+export type GraphqlFilterPropertyEntityType =
+ /** Calendar event entity. */
+ | 'CALENDAR_EVENT'
+ /** Call record entity. */
+ | 'CALL_RECORD'
+ /** Channel entity. */
+ | 'CHANNEL'
+ /** Chat entity. */
+ | 'CHAT'
+ /** Company entity. */
+ | 'COMPANY'
+ /** Document entity. */
+ | 'DOCUMENT'
+ /** Project entity. */
+ | 'PROJECT'
+ /** Task entity. */
+ | 'TASK'
+ /** Thread entity. */
+ | 'THREAD'
+ /** User entity. */
+ | 'USER';
+
+/** GraphQL input value used when matching a property. */
+export type GraphqlFilterPropertyMatchValue =
+ { /** Entity reference id to match. */
+ entityRef: string; selectOption?: never; }
+ | { entityRef?: never; /** Select option id to match. */
+ selectOption: string | number; };
+
/** The two operands of a recursive `ForeignEntityFilterExpr` binary expression. */
export type GraphqlForeignEntityBinaryExpr = {
- /** The left-hand expression. */
+ /** Left expression. */
left: GraphqlForeignEntityExpr;
- /** The right-hand expression. */
+ /** Right expression. */
right: GraphqlForeignEntityExpr;
};
/** A recursive `ForeignEntityFilterExpr` filter expression. */
export type GraphqlForeignEntityExpr =
- { /** Matches when both expressions match. */
+ { /** Both expressions must match. */
and: GraphqlForeignEntityBinaryExpr; literal?: never; not?: never; or?: never; }
- | { and?: never; /** Matches a domain-specific literal condition. */
+ | { and?: never; /** Match a literal. */
literal: GraphqlForeignEntityLiteral; not?: never; or?: never; }
- | { and?: never; literal?: never; /** Negates an expression. */
+ | { and?: never; literal?: never; /** Negate an expression. */
not: GraphqlForeignEntityExpr; or?: never; }
- | { and?: never; literal?: never; not?: never; /** Matches when either expression matches. */
+ | { and?: never; literal?: never; not?: never; /** Either expression may match. */
or: GraphqlForeignEntityBinaryExpr; };
/** GraphQL input representing the foreign entity literal. */
@@ -701,21 +762,21 @@ export type GraphqlNotificationDocumentSubType =
/** The two operands of a recursive `ProjectFilterExpr` binary expression. */
export type GraphqlProjectBinaryExpr = {
- /** The left-hand expression. */
+ /** Left expression. */
left: GraphqlProjectExpr;
- /** The right-hand expression. */
+ /** Right expression. */
right: GraphqlProjectExpr;
};
/** A recursive `ProjectFilterExpr` filter expression. */
export type GraphqlProjectExpr =
- { /** Matches when both expressions match. */
+ { /** Both expressions must match. */
and: GraphqlProjectBinaryExpr; literal?: never; not?: never; or?: never; }
- | { and?: never; /** Matches a domain-specific literal condition. */
+ | { and?: never; /** Match a literal. */
literal: GraphqlProjectLiteral; not?: never; or?: never; }
- | { and?: never; literal?: never; /** Negates an expression. */
+ | { and?: never; literal?: never; /** Negate an expression. */
not: GraphqlProjectExpr; or?: never; }
- | { and?: never; literal?: never; not?: never; /** Matches when either expression matches. */
+ | { and?: never; literal?: never; not?: never; /** Either expression may match. */
or: GraphqlProjectBinaryExpr; };
/** GraphQL input representing the project literal. */
@@ -737,35 +798,6 @@ export type GraphqlProjectLiteral =
| { createdAt?: never; importance?: never; notificationDone?: never; notificationSeen?: never; owner?: never; projectId?: never; projectIdSelf?: never; /** The updated at option. */
updatedAt: GraphqlDateLiteral; };
-/** The two operands of a recursive `PropertiesFilterExpr` binary expression. */
-export type GraphqlPropertiesBinaryExpr = {
- /** The left-hand expression. */
- left: GraphqlPropertiesExpr;
- /** The right-hand expression. */
- right: GraphqlPropertiesExpr;
-};
-
-/** A recursive `PropertiesFilterExpr` filter expression. */
-export type GraphqlPropertiesExpr =
- { /** Matches when both expressions match. */
- and: GraphqlPropertiesBinaryExpr; literal?: never; not?: never; or?: never; }
- | { and?: never; /** Matches a domain-specific literal condition. */
- literal: GraphqlPropertiesLiteral; not?: never; or?: never; }
- | { and?: never; literal?: never; /** Negates an expression. */
- not: GraphqlPropertiesExpr; or?: never; }
- | { and?: never; literal?: never; not?: never; /** Matches when either expression matches. */
- or: GraphqlPropertiesBinaryExpr; };
-
-/** GraphQL input for matching a property value on an entity. */
-export type GraphqlPropertiesLiteral = {
- /** Optional entity type scope for the property match. */
- entityType?: GraphqlPropertyEntityType | null | undefined;
- /** Property definition id to match. */
- propertyDefinitionId: string | number;
- /** Value to compare against the property. */
- value: GraphqlPropertyMatchValue;
-};
-
/** A property definition's supported value type. */
export type GraphqlPropertyDataType =
/** Boolean true/false values. */
@@ -810,13 +842,6 @@ export type GraphqlPropertyEntityType =
/** User entity. */
| 'USER';
-/** GraphQL input value used when matching a property. */
-export type GraphqlPropertyMatchValue =
- { /** Entity reference id to match. */
- entityRef: string; selectOption?: never; }
- | { entityRef?: never; /** Select option id to match. */
- selectOption: string | number; };
-
/** Canonical entity type accepted for property targets. */
export type GraphqlPropertyTargetEntityType =
/** Call record target. */
@@ -838,21 +863,21 @@ export type GraphqlPropertyTargetEntityType =
/** The two operands of a recursive `ReminderFilterExpr` binary expression. */
export type GraphqlReminderBinaryExpr = {
- /** The left-hand expression. */
+ /** Left expression. */
left: GraphqlReminderExpr;
- /** The right-hand expression. */
+ /** Right expression. */
right: GraphqlReminderExpr;
};
/** A recursive `ReminderFilterExpr` filter expression. */
export type GraphqlReminderExpr =
- { /** Matches when both expressions match. */
+ { /** Both expressions must match. */
and: GraphqlReminderBinaryExpr; literal?: never; not?: never; or?: never; }
- | { and?: never; /** Matches a domain-specific literal condition. */
+ | { and?: never; /** Match a literal. */
literal: GraphqlReminderLiteral; not?: never; or?: never; }
- | { and?: never; literal?: never; /** Negates an expression. */
+ | { and?: never; literal?: never; /** Negate an expression. */
not: GraphqlReminderExpr; or?: never; }
- | { and?: never; literal?: never; not?: never; /** Matches when either expression matches. */
+ | { and?: never; literal?: never; not?: never; /** Either expression may match. */
or: GraphqlReminderBinaryExpr; };
/** GraphQL input representing the reminder literal. */
diff --git a/crates/client/cache-core/Cargo.toml b/crates/client/cache-core/Cargo.toml
index dce53c09a2..4fdf86cd26 100644
--- a/crates/client/cache-core/Cargo.toml
+++ b/crates/client/cache-core/Cargo.toml
@@ -10,6 +10,7 @@ chrono = { workspace = true }
lru = { workspace = true }
maybe_send = { path = "../../maybe_send" }
postcard = { workspace = true }
+predicate-index = { path = "../../predicate_index" }
serde = { workspace = true }
serde_json = { workspace = true }
sha2 = { workspace = true }
diff --git a/crates/client/cache-core/src/engine.rs b/crates/client/cache-core/src/engine.rs
index 440ecb5075..839baa9a71 100644
--- a/crates/client/cache-core/src/engine.rs
+++ b/crates/client/cache-core/src/engine.rs
@@ -17,6 +17,7 @@ use crate::normalize::{
DependencyCompleteness, NormalizeError, RecordUpdates, normalize, normalize_with_dependencies,
project_hydration_response,
};
+use crate::predicate::{PredicateIndexStorage, PredicateQueryResult, ProjectionMutation};
use crate::query_inspection::{
CachedQueryInstance, CachedQueryVariant, OwnerResolution, QueryInspection,
QueryInspectionError, matches_variable_filters, prepare, recover_variants, resolve_owner,
@@ -37,6 +38,10 @@ use crate::search::{
use crate::store::{QueueDiagnostics, Storage};
use crate::value::{EntityKey, Record, canonical_json};
use lru::LruCache;
+use predicate_index::{
+ IndexDocument, MAX_OPTIMISTIC_RECORDS_PER_QUERY, MAX_QUERY_LIMIT, OptimisticProjectionMutation,
+ RecordKey as PredicateRecordKey, ValidatedIndexQuery, evaluate_reference,
+};
use serde_json::Value as Json;
use std::collections::{BTreeMap, BTreeSet, HashMap};
use std::num::NonZeroUsize;
@@ -69,6 +74,8 @@ pub enum EngineError<S: std::error::Error + 'static> {
id: OptimisticTransactionId,
detail: String,
},
+ #[error("invalid optimistic projection: {0}")]
+ InvalidOptimisticProjection(String),
#[error("storage: {0}")]
Storage(#[source] S),
}
@@ -188,6 +195,7 @@ struct OptimisticLayer {
updates: RecordUpdates,
link_patches: Vec<OptimisticLinkPatch>,
revalidations: Vec<QueryRevalidation>,
+ projection_mutations: Vec<OptimisticProjectionMutation>,
}
/// Reserved storage key holding the identity bound to this cache. The
@@ -337,18 +345,20 @@ impl<S: Storage> Engine<S> {
// Missing query fields after a format wipe are intentionally not
// recreated from stale recipes during hydration.
apply_link_patches(&mut effective, &mut updates, &patches, true)?;
+ let revalidations = deduplicate_revalidations(
+ source.revalidations.iter().cloned().chain(
+ source
+ .link_patches
+ .iter()
+ .map(OptimisticLinkPatch::revalidation),
+ ),
+ );
layers.push(OptimisticLayer {
id: queued.id,
updates,
link_patches: patches,
- revalidations: deduplicate_revalidations(
- source.revalidations.into_iter().chain(
- source
- .link_patches
- .iter()
- .map(OptimisticLinkPatch::revalidation),
- ),
- ),
+ revalidations,
+ projection_mutations: source.projection_mutations,
});
}
Ok(layers)
@@ -907,6 +917,23 @@ impl<S: Storage> Engine<S> {
origin_op: Option<OpId>,
registration: Option<QueryRegistration<'_>>,
input: NetworkWrite<'_>,
+ ) -> Result<WriteResult, EngineError<S::Error>> {
+ self.write_query_with_registration_and_projections(
+ origin_op,
+ registration,
+ input,
+ Vec::new(),
+ )
+ .await
+ }
+
+ /// Normalizes records and atomically applies caller-composed generic projections.
+ pub async fn write_query_with_registration_and_projections(
+ &mut self,
+ origin_op: Option<OpId>,
+ registration: Option<QueryRegistration<'_>>,
+ input: NetworkWrite<'_>,
+ projections: Vec<ProjectionMutation>,
) -> Result<WriteResult, EngineError<S::Error>> {
let NetworkWrite {
query,
@@ -956,7 +983,7 @@ impl<S: Storage> Engine<S> {
candidates.extend(updates.keys().cloned());
let bases_before = self.load_bases(&candidates).await?;
let before = effective_records(&bases_before, &self.optimistic, &candidates);
- let changed = self.persist_updates(updates).await?;
+ let changed = self.persist_updates(updates, projections).await?;
if !self.optimistic.is_empty() {
let queued = self
@@ -1012,6 +1039,27 @@ impl<S: Storage> Engine<S> {
variables: &serde_json::Map<String, Json>,
data: &Json,
identity: Option<&str>,
+ ) -> Result<HydrationWriteResult, EngineError<S::Error>> {
+ self.hydrate_query_with_projections(
+ query,
+ operation_name,
+ variables,
+ data,
+ identity,
+ Vec::new(),
+ )
+ .await
+ }
+
+ /// Hydrates a response while atomically maintaining generic projections.
+ pub async fn hydrate_query_with_projections(
+ &mut self,
+ query: &str,
+ operation_name: Option<&str>,
+ variables: &serde_json::Map<String, Json>,
+ data: &Json,
+ identity: Option<&str>,
+ projections: Vec<ProjectionMutation>,
) -> Result<HydrationWriteResult, EngineError<S::Error>> {
let projected = {
let doc = Self::document(&mut self.docs, query)?;
@@ -1027,7 +1075,18 @@ impl<S: Storage> Engine<S> {
project_hydration_response(op, data)?
};
let write_result = self
- .write_query(None, query, operation_name, variables, data, identity)
+ .write_query_with_registration_and_projections(
+ None,
+ None,
+ NetworkWrite {
+ query,
+ operation_name,
+ variables,
+ data,
+ identity,
+ },
+ projections,
+ )
.await?;
Ok(HydrationWriteResult {
write_result,
@@ -1040,6 +1099,7 @@ impl<S: Storage> Engine<S> {
async fn persist_updates(
&mut self,
updates: RecordUpdates,
+ projections: Vec<ProjectionMutation>,
) -> Result<BTreeSet<EntityKey<'static>>, EngineError<S::Error>> {
// Load current values (hot tier, then storage) so merges detect real
// changes. Merges are staged in a plain map, NOT the LRU: a batch
@@ -1093,7 +1153,7 @@ impl<S: Storage> Engine<S> {
// keeps storage authoritative even if the hot tier evicted them
// between loads).
self.storage
- .put_batch(to_persist.clone())
+ .put_batch_with_projections(to_persist.clone(), projections)
.await
.map_err(EngineError::Storage)?;
self.update_loaded_search_catalogs(&to_persist);
@@ -1107,6 +1167,17 @@ impl<S: Storage> Engine<S> {
&mut self,
origin_op: Option<OpId>,
input: BeginOptimisticWrite<'_>,
+ ) -> Result<(OptimisticTransactionId, WriteResult), EngineError<S::Error>> {
+ self.begin_optimistic_write_with_projections(origin_op, input, Vec::new())
+ .await
+ }
+
+ /// Atomically enqueue an optimistic normalized layer and generic projection overlay.
+ pub async fn begin_optimistic_write_with_projections(
+ &mut self,
+ origin_op: Option<OpId>,
+ input: BeginOptimisticWrite<'_>,
+ projection_mutations: Vec<OptimisticProjectionMutation>,
) -> Result<(OptimisticTransactionId, WriteResult), EngineError<S::Error>> {
let BeginOptimisticWrite {
query,
@@ -1145,10 +1216,16 @@ impl<S: Storage> Engine<S> {
IdentityState::Bound(identity) => Some(identity),
IdentityState::NotHydrated | IdentityState::Missing => None,
};
+ for mutation in &projection_mutations {
+ mutation
+ .validate()
+ .map_err(|error| EngineError::InvalidOptimisticProjection(error.to_string()))?;
+ }
let source = OptimisticSource {
mutation_data: data.clone(),
link_patches: patches.clone(),
revalidations: revalidations.clone(),
+ projection_mutations: projection_mutations.clone(),
};
let id = self
.storage
@@ -1174,6 +1251,7 @@ impl<S: Storage> Engine<S> {
updates,
link_patches: patches,
revalidations,
+ projection_mutations,
});
let after = effective_records(&bases, &self.optimistic, &candidates);
@@ -1206,7 +1284,21 @@ impl<S: Storage> Engine<S> {
input: BeginOptimisticWrite<'_>,
claim: MutationClaimRequest,
) -> Result<EnqueueOptimisticMutationResult<EngineError<S::Error>>, EngineError<S::Error>> {
- let (transaction_id, write_result) = self.begin_optimistic_write(origin_op, input).await?;
+ self.enqueue_optimistic_mutation_with_projections(origin_op, input, claim, Vec::new())
+ .await
+ }
+
+ /// Durably enqueue normalized optimism and a queryable projection overlay.
+ pub async fn enqueue_optimistic_mutation_with_projections(
+ &mut self,
+ origin_op: Option<OpId>,
+ input: BeginOptimisticWrite<'_>,
+ claim: MutationClaimRequest,
+ projection_mutations: Vec<OptimisticProjectionMutation>,
+ ) -> Result<EnqueueOptimisticMutationResult<EngineError<S::Error>>, EngineError<S::Error>> {
+ let (transaction_id, write_result) = self
+ .begin_optimistic_write_with_projections(origin_op, input, projection_mutations)
+ .await?;
let initial_claim = match self.claim_next_mutation(claim).await {
Ok(Some(claimed)) => InitialClaimOutcome::Claimed(Box::new(claimed)),
Ok(None) => InitialClaimOutcome::NotRunnable,
@@ -1263,6 +1355,30 @@ impl<S: Storage> Engine<S> {
operation_name: Option<&str>,
variables: &serde_json::Map<String, Json>,
data: &Json,
+ ) -> Result<WriteResult, EngineError<S::Error>> {
+ self.commit_optimistic_write_with_projections(
+ transaction,
+ claim,
+ query,
+ operation_name,
+ variables,
+ data,
+ Vec::new(),
+ )
+ .await
+ }
+
+ /// Settles an optimistic write with atomic generic projection replacement.
+ #[allow(clippy::too_many_arguments)]
+ pub async fn commit_optimistic_write_with_projections(
+ &mut self,
+ transaction: OptimisticTransactionId,
+ claim: MutationClaimToken,
+ query: &str,
+ operation_name: Option<&str>,
+ variables: &serde_json::Map<String, Json>,
+ data: &Json,
+ projections: Vec<ProjectionMutation>,
) -> Result<WriteResult, EngineError<S::Error>> {
self.hydrate_optimistic().await?;
let index = self
@@ -1292,7 +1408,7 @@ impl<S: Storage> Engine<S> {
let (durable_changed, entries) = stage_updates(&bases, updates);
if !self
.storage
- .complete_mutation(transaction, claim, entries.clone())
+ .complete_mutation_with_projections(transaction, claim, entries.clone(), projections)
.await
.map_err(EngineError::Storage)?
{
@@ -1625,6 +1741,235 @@ impl<S: Storage> Engine<S> {
}
}
+impl<S: PredicateIndexStorage> Engine<S> {
+ /// Atomically persist normalized records and generic projection lifecycle changes.
+ pub async fn put_records_with_projections(
+ &mut self,
+ origin_op: Option<OpId>,
+ entries: Vec<(EntityKey<'static>, Record)>,
+ projections: Vec<ProjectionMutation>,
+ ) -> Result<WriteResult, EngineError<S::Error>> {
+ let mut updates = RecordUpdates::new();
+ for (key, record) in entries {
+ updates.entry(key).or_default().merge(record);
+ }
+ let changed = self.persist_updates(updates, projections).await?;
+ let mut affected_ops = self.deps.ops_for_keys(changed.iter());
+ if let Some(origin_op) = origin_op {
+ affected_ops.remove(&origin_op);
+ }
+ Ok(WriteResult {
+ changed,
+ affected_ops,
+ reset: false,
+ revalidations: Vec::new(),
+ })
+ }
+
+ /// Mark projections incomplete atomically without changing normalized base records.
+ pub async fn mark_projections_incomplete(
+ &mut self,
+ projections: Vec<ProjectionMutation>,
+ ) -> Result<(), EngineError<S::Error>> {
+ self.storage
+ .put_batch_with_projections(Vec::new(), projections)
+ .await
+ .map_err(EngineError::Storage)
+ }
+
+ /// Delete normalized records and generic projections in one storage transaction.
+ pub async fn delete_keys_with_projections(
+ &mut self,
+ keys: &[EntityKey<'static>],
+ projection_keys: &[PredicateRecordKey],
+ ) -> Result<BTreeSet<OpId>, EngineError<S::Error>> {
+ let affected = self.deps.ops_for_keys(keys.iter());
+ self.storage
+ .delete_batch_with_projections(keys, projection_keys)
+ .await
+ .map_err(EngineError::Storage)?;
+ for key in keys {
+ self.hot.pop(key);
+ for catalog in self.search_catalogs.values_mut() {
+ catalog.remove(key);
+ }
+ }
+ Ok(affected)
+ }
+
+ /// Execute a complete generic exact-index query over authoritative and optimistic projections.
+ pub async fn query_predicate_index(
+ &mut self,
+ query: &ValidatedIndexQuery,
+ ) -> Result<PredicateQueryResult, EngineError<S::Error>> {
+ self.hydrate_optimistic().await?;
+ let projection_mutations = self
+ .optimistic
+ .iter()
+ .flat_map(|layer| layer.projection_mutations.iter())
+ .filter(|mutation| query.includes_scope(mutation.profile(), mutation.partition()))
+ .cloned()
+ .collect::<Vec<_>>();
+ if projection_mutations.is_empty() {
+ return self
+ .storage
+ .query_predicate_index(query)
+ .await
+ .map_err(EngineError::Storage);
+ }
+ for mutation in &projection_mutations {
+ mutation
+ .validate()
+ .map_err(|error| EngineError::InvalidOptimisticProjection(error.to_string()))?;
+ }
+ let mut uncertain = BTreeSet::new();
+ for mutation in &projection_mutations {
+ match mutation {
+ OptimisticProjectionMutation::Unknown { record_key, .. }
+ if mutation.makes_query_uncertain(query) =>
+ {
+ uncertain.insert(record_key.clone());
+ }
+ OptimisticProjectionMutation::Replace(document) => {
+ uncertain.remove(&document.record_key);
+ }
+ OptimisticProjectionMutation::Patch { .. } => {}
+ OptimisticProjectionMutation::Delete { record_key, .. } => {
+ uncertain.remove(record_key);
+ }
+ OptimisticProjectionMutation::Unknown { .. } => {}
+ }
+ }
+ if !uncertain.is_empty() {
+ return Ok(PredicateQueryResult::Incomplete);
+ }
+
+ let touched = projection_mutations
+ .iter()
+ .map(|mutation| mutation.record_key().clone())
+ .collect::<BTreeSet<_>>();
+ if touched.len() > MAX_OPTIMISTIC_RECORDS_PER_QUERY {
+ return Ok(PredicateQueryResult::Incomplete);
+ }
+ let requested_limit = usize::from(query.as_query().limit);
+ let expanded_limit = requested_limit.saturating_add(touched.len());
+ if expanded_limit > usize::from(MAX_QUERY_LIMIT) {
+ return Ok(PredicateQueryResult::Incomplete);
+ }
+ let expanded_query = query
+ .with_limit(u16::try_from(expanded_limit).expect("bounded predicate query limit"))
+ .expect("an increased bounded limit preserves query validity");
+ let base_keys = match self
+ .storage
+ .query_predicate_index(&expanded_query)
+ .await
+ .map_err(EngineError::Storage)?
+ {
+ PredicateQueryResult::Complete(keys) | PredicateQueryResult::Optimistic(keys) => keys,
+ PredicateQueryResult::Incomplete => return Ok(PredicateQueryResult::Incomplete),
+ };
+
+ let base_keys = base_keys.into_iter().collect::<BTreeSet<_>>();
+ let mut keys = base_keys.clone();
+ keys.extend(touched.iter().cloned());
+ let keys = keys.into_iter().collect::<Vec<_>>();
+ let loaded = self
+ .storage
+ .get_index_documents(&keys)
+ .await
+ .map_err(EngineError::Storage)?;
+ if loaded.len() != keys.len() {
+ return Ok(PredicateQueryResult::Incomplete);
+ }
+ if keys
+ .iter()
+ .zip(&loaded)
+ .any(|(key, document)| base_keys.contains(key) && document.is_none())
+ {
+ return Ok(PredicateQueryResult::Incomplete);
+ }
+ let mut documents = keys
+ .into_iter()
+ .zip(loaded)
+ .filter_map(|(key, document)| document.map(|document| (key, document)))
+ .collect::<BTreeMap<_, _>>();
+
+ for mutation in projection_mutations {
+ match mutation {
+ OptimisticProjectionMutation::Replace(document) => {
+ documents.insert(document.record_key.clone(), document);
+ }
+ OptimisticProjectionMutation::Patch {
+ record_key,
+ profile,
+ partition,
+ exact,
+ integers,
+ sorts,
+ } => {
+ let Some(document) = documents.get_mut(&record_key) else {
+ return Ok(PredicateQueryResult::Incomplete);
+ };
+ if document.profile != profile || document.partition != partition {
+ return Ok(PredicateQueryResult::Incomplete);
+ }
+ for patch in exact {
+ document
+ .exact_facts
+ .retain(|fact| fact.attribute != patch.attribute);
+ document
+ .exact_facts
+ .extend(patch.values.into_iter().map(|value| {
+ predicate_index::ExactFact {
+ attribute: patch.attribute.clone(),
+ value,
+ }
+ }));
+ }
+ for patch in integers {
+ document
+ .integer_facts
+ .retain(|fact| fact.attribute != patch.attribute);
+ document
+ .integer_facts
+ .extend(patch.values.into_iter().map(|value| {
+ predicate_index::IntegerFact {
+ attribute: patch.attribute.clone(),
+ value,
+ }
+ }));
+ }
+ for fact in sorts {
+ document
+ .sort_facts
+ .retain(|existing| existing.attribute != fact.attribute);
+ document.sort_facts.push(fact);
+ }
+ if document.validate().is_err() {
+ return Ok(PredicateQueryResult::Incomplete);
+ }
+ }
+ OptimisticProjectionMutation::Delete { record_key, .. } => {
+ documents.remove(&record_key);
+ }
+ OptimisticProjectionMutation::Unknown { .. } => {
+ // Query-irrelevant uncertainty was filtered above and does
+ // not alter any known effective facts.
+ }
+ }
+ }
+ Ok(PredicateQueryResult::Optimistic(
+ evaluate_reference(
+ query,
+ &documents.into_values().collect::<Vec<IndexDocument>>(),
+ )
+ .into_iter()
+ .map(|hit| hit.record_key)
+ .collect(),
+ ))
+ }
+}
+
/// Read view over the durable tiers plus the optimistic composition. Uses
/// `peek` (no recency mutation) — recency is refreshed once per read from
/// the dep set.
diff --git a/crates/client/cache-core/src/lib.rs b/crates/client/cache-core/src/lib.rs
index 74bfe43240..947c8fd461 100644
--- a/crates/client/cache-core/src/lib.rs
+++ b/crates/client/cache-core/src/lib.rs
@@ -11,6 +11,7 @@ pub mod entity_resolver;
pub mod link_patch;
pub mod meta;
pub mod normalize;
+pub mod predicate;
pub mod query_inspection;
mod query_path;
pub mod queue;
diff --git a/crates/client/cache-core/src/predicate.rs b/crates/client/cache-core/src/predicate.rs
new file mode 100644
index 0000000000..4a12dc6bf6
--- /dev/null
+++ b/crates/client/cache-core/src/predicate.rs
@@ -0,0 +1,127 @@
+//! Generic predicate-projection lifecycle and exact-query storage port.
+
+use crate::{store::Storage, value::EntityKey};
+use maybe_send::MaybeSend;
+use predicate_index::{IndexDocument, Profile, RecordKey, Token, ValidatedIndexQuery};
+use serde::{Deserialize, Serialize};
+
+/// Why a known projection is not currently safe to query.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub enum ProjectionIncompleteKind {
+ /// An update may have changed indexed facts.
+ Dirty,
+ /// A supported normalized record arrived without its required projection.
+ Missing,
+ /// The record carries a projection version this client cannot interpret.
+ IncompatibleVersion,
+}
+
+/// Persisted projection state for one supported normalized record.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub enum ProjectionState {
+ /// Complete facts that atomically replace all older facts.
+ Complete(IndexDocument),
+ /// Non-queryable state retained with enough generic scope metadata to force fallback.
+ Incomplete {
+ /// Normalized record key.
+ record_key: RecordKey,
+ /// Profile whose local scope is incomplete.
+ profile: Profile,
+ /// Partition whose local scope is incomplete.
+ partition: Token,
+ /// Incompleteness reason.
+ kind: ProjectionIncompleteKind,
+ },
+}
+
+impl ProjectionState {
+ /// Read the normalized record key.
+ pub fn record_key(&self) -> &RecordKey {
+ match self {
+ Self::Complete(document) => &document.record_key,
+ Self::Incomplete { record_key, .. } => record_key,
+ }
+ }
+
+ /// Read the profile.
+ pub fn profile(&self) -> &Profile {
+ match self {
+ Self::Complete(document) => &document.profile,
+ Self::Incomplete { profile, .. } => profile,
+ }
+ }
+
+ /// Read the partition.
+ pub fn partition(&self) -> &Token {
+ match self {
+ Self::Complete(document) => &document.partition,
+ Self::Incomplete { partition, .. } => partition,
+ }
+ }
+}
+
+/// Atomic change to one normalized record's generic projection.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub enum ProjectionMutation {
+ /// Replace all prior facts and mark the record complete.
+ Replace(IndexDocument),
+ /// Remove queryable facts and retain an explicit incomplete marker.
+ MarkIncomplete {
+ /// Normalized record key.
+ record_key: RecordKey,
+ /// Active profile.
+ profile: Profile,
+ /// Entity partition.
+ partition: Token,
+ /// Why local evaluation is unsafe.
+ kind: ProjectionIncompleteKind,
+ },
+ /// Delete projection state for a deleted normalized record.
+ Delete(RecordKey),
+}
+
+impl ProjectionMutation {
+ /// Read the affected normalized record key.
+ pub fn record_key(&self) -> &RecordKey {
+ match self {
+ Self::Replace(document) => &document.record_key,
+ Self::MarkIncomplete { record_key, .. } | Self::Delete(record_key) => record_key,
+ }
+ }
+}
+
+/// Result of exact local index execution.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum PredicateQueryResult {
+ /// Every known authoritative record in the queried profile/partitions was complete.
+ Complete(Vec<RecordKey>),
+ /// Complete effective result including one or more durable optimistic layers.
+ Optimistic(Vec<RecordKey>),
+ /// At least one relevant projection was dirty, missing, or incompatible.
+ Incomplete,
+}
+
+/// Storage capability for atomic normalized-record and generic-projection changes.
+pub trait PredicateIndexStorage: Storage {
+ /// Atomically delete normalized records and their projection state.
+ fn delete_batch_with_projections(
+ &mut self,
+ keys: &[EntityKey<'static>],
+ projection_keys: &[RecordKey],
+ ) -> impl Future<Output = Result<(), Self::Error>> + MaybeSend;
+
+ /// Execute a validated generic query or report an incomplete local scope.
+ fn query_predicate_index(
+ &self,
+ query: &ValidatedIndexQuery,
+ ) -> impl Future<Output = Result<PredicateQueryResult, Self::Error>> + MaybeSend;
+
+ /// Load complete authoritative projections aligned with `keys`.
+ ///
+ /// Incomplete or absent projections are returned as `None`. This is used
+ /// to compose a bounded optimistic overlay without scanning record blobs.
+ fn get_index_documents(
+ &self,
+ keys: &[RecordKey],
+ ) -> impl Future<Output = Result<Vec<Option<IndexDocument>>, Self::Error>> + MaybeSend;
+}
diff --git a/crates/client/cache-core/src/queue.rs b/crates/client/cache-core/src/queue.rs
index 377c73de39..6215deb501 100644
--- a/crates/client/cache-core/src/queue.rs
+++ b/crates/client/cache-core/src/queue.rs
@@ -8,6 +8,7 @@
use crate::link_patch::{OptimisticLinkPatch, QueryRevalidation};
use crate::normalize::RecordUpdates;
use crate::value::canonical_json;
+use predicate_index::OptimisticProjectionMutation;
use serde::{Deserialize, Serialize};
use serde_json::Value as Json;
@@ -65,7 +66,7 @@ impl StoredMutation {
}
/// Current version of the durable optimistic source envelope.
-pub const OPTIMISTIC_SOURCE_VERSION: u8 = 2;
+pub const OPTIMISTIC_SOURCE_VERSION: u8 = 3;
const OPTIMISTIC_SOURCE_ENVELOPE_PREFIX: &str = "@macro-cache/optimistic-source:";
@@ -81,6 +82,9 @@ pub struct OptimisticSource {
/// Revalidations for relevant fields that could not be patched.
#[serde(default)]
pub revalidations: Vec<QueryRevalidation>,
+ /// Ordered generic projection changes composed with this optimistic layer.
+ #[serde(default)]
+ pub projection_mutations: Vec<OptimisticProjectionMutation>,
}
#[derive(Debug, Serialize, Deserialize)]
@@ -92,6 +96,18 @@ struct OptimisticSourceEnvelope {
link_patches: Vec<OptimisticLinkPatch>,
#[serde(default)]
revalidations: Vec<QueryRevalidation>,
+ projection_mutations: Vec<OptimisticProjectionMutation>,
+}
+
+#[derive(Debug, Deserialize)]
+#[serde(deny_unknown_fields, rename_all = "camelCase")]
+struct OptimisticSourceEnvelopeV2 {
+ version: u8,
+ mutation_data: Json,
+ #[serde(default)]
+ link_patches: Vec<OptimisticLinkPatch>,
+ #[serde(default)]
+ revalidations: Vec<QueryRevalidation>,
}
/// Encodes an optimistic source with a reserved prefix and versioned JSON envelope.
@@ -102,6 +118,7 @@ pub fn encode_optimistic_source(source: &OptimisticSource) -> String {
mutation_data: source.mutation_data.clone(),
link_patches: source.link_patches.clone(),
revalidations: source.revalidations.clone(),
+ projection_mutations: source.projection_mutations.clone(),
})
.expect("optimistic source serializes"),
);
@@ -116,21 +133,38 @@ pub fn decode_optimistic_source(value: &str) -> Result<OptimisticSource, String>
mutation_data: serde_json::from_str(value).map_err(|error| error.to_string())?,
link_patches: Vec::new(),
revalidations: Vec::new(),
+ projection_mutations: Vec::new(),
});
};
- let envelope: OptimisticSourceEnvelope =
- serde_json::from_str(envelope).map_err(|error| error.to_string())?;
- if envelope.version != OPTIMISTIC_SOURCE_VERSION {
- return Err(format!(
- "unsupported optimistic source version {}",
- envelope.version
- ));
+ let value: Json = serde_json::from_str(envelope).map_err(|error| error.to_string())?;
+ let version = value
+ .get("version")
+ .and_then(Json::as_u64)
+ .ok_or_else(|| "optimistic source version is missing or invalid".to_string())?;
+ match version {
+ 2 => {
+ let envelope: OptimisticSourceEnvelopeV2 =
+ serde_json::from_value(value).map_err(|error| error.to_string())?;
+ debug_assert_eq!(envelope.version, 2);
+ Ok(OptimisticSource {
+ mutation_data: envelope.mutation_data,
+ link_patches: envelope.link_patches,
+ revalidations: envelope.revalidations,
+ projection_mutations: Vec::new(),
+ })
+ }
+ version if version == u64::from(OPTIMISTIC_SOURCE_VERSION) => {
+ let envelope: OptimisticSourceEnvelope =
+ serde_json::from_value(value).map_err(|error| error.to_string())?;
+ Ok(OptimisticSource {
+ mutation_data: envelope.mutation_data,
+ link_patches: envelope.link_patches,
+ revalidations: envelope.revalidations,
+ projection_mutations: envelope.projection_mutations,
+ })
+ }
+ version => Err(format!("unsupported optimistic source version {version}")),
}
- Ok(OptimisticSource {
- mutation_data: envelope.mutation_data,
- link_patches: envelope.link_patches,
- revalidations: envelope.revalidations,
- })
}
/// One durable optimistic layer paired one-to-one with a queued mutation.
diff --git a/crates/client/cache-core/src/store.rs b/crates/client/cache-core/src/store.rs
index cc9554f24f..f5e5aa2956 100644
--- a/crates/client/cache-core/src/store.rs
+++ b/crates/client/cache-core/src/store.rs
@@ -6,6 +6,9 @@
//! wasm — wasm futures aren't
//! `Send`.
+use crate::predicate::{
+ PredicateIndexStorage, PredicateQueryResult, ProjectionMutation, ProjectionState,
+};
use crate::queue::{
ClaimedMutation, MutationClaimRequest, MutationClaimToken, MutationId, NewQueuedMutation,
QueuedMutation,
@@ -13,6 +16,7 @@ use crate::queue::{
use crate::search::{SearchCursor, SearchDocument, SearchProfile, project_search_documents};
use crate::value::{EntityKey, Record};
use maybe_send::MaybeSend;
+use predicate_index::{IndexDocument, RecordKey as PredicateRecordKey, evaluate_reference};
use std::collections::{BTreeMap, HashMap};
use std::convert::Infallible;
use std::sync::Arc;
@@ -56,6 +60,13 @@ pub trait Storage: MaybeSend {
entries: Vec<(EntityKey<'static>, Record)>,
) -> impl Future<Output = Result<(), Self::Error>> + MaybeSend;
+ /// Atomically upserts records and generic projection lifecycle changes.
+ fn put_batch_with_projections(
+ &mut self,
+ entries: Vec<(EntityKey<'static>, Record)>,
+ projections: Vec<ProjectionMutation>,
+ ) -> impl Future<Output = Result<(), Self::Error>> + MaybeSend;
+
/// Deletes records (absent keys are ignored).
fn delete_batch(
&mut self,
@@ -131,6 +142,15 @@ pub trait Storage: MaybeSend {
entries: Vec<(EntityKey<'static>, Record)>,
) -> impl Future<Output = Result<bool, Self::Error>> + MaybeSend;
+ /// Atomically settles a mutation with real records and projection changes.
+ fn complete_mutation_with_projections(
+ &mut self,
+ id: MutationId,
+ claim: MutationClaimToken,
+ entries: Vec<(EntityKey<'static>, Record)>,
+ projections: Vec<ProjectionMutation>,
+ ) -> impl Future<Output = Result<bool, Self::Error>> + MaybeSend;
+
/// Atomically removes a permanently failed mutation and its optimistic
/// layer. Returns `false` when the claim is stale.
fn discard_mutation(
@@ -149,6 +169,7 @@ pub trait Storage: MaybeSend {
pub struct InMemoryStorage {
records: HashMap<EntityKey<'static>, Record>,
search_documents: HashMap<(SearchProfile, EntityKey<'static>), SearchDocument>,
+ projections: HashMap<PredicateRecordKey, ProjectionState>,
mutations: BTreeMap<
MutationId,
(
@@ -209,6 +230,16 @@ impl Storage for InMemoryStorage {
Ok(())
}
+ async fn put_batch_with_projections(
+ &mut self,
+ entries: Vec<(EntityKey<'static>, Record)>,
+ projections: Vec<ProjectionMutation>,
+ ) -> Result<(), Self::Error> {
+ self.put_batch(entries).await?;
+ apply_in_memory_projection_mutations(&mut self.projections, projections);
+ Ok(())
+ }
+
async fn delete_batch(&mut self, keys: &[EntityKey<'static>]) -> Result<(), Self::Error> {
for key in keys {
self.records.remove(key);
@@ -354,6 +385,17 @@ impl Storage for InMemoryStorage {
id: MutationId,
claim: MutationClaimToken,
entries: Vec<(EntityKey<'static>, Record)>,
+ ) -> Result<bool, Self::Error> {
+ self.complete_mutation_with_projections(id, claim, entries, Vec::new())
+ .await
+ }
+
+ async fn complete_mutation_with_projections(
+ &mut self,
+ id: MutationId,
+ claim: MutationClaimToken,
+ entries: Vec<(EntityKey<'static>, Record)>,
+ projections: Vec<ProjectionMutation>,
) -> Result<bool, Self::Error> {
let Some((mutation, _)) = self.mutations.get(&id) else {
return Ok(false);
@@ -370,6 +412,7 @@ impl Storage for InMemoryStorage {
}
self.records.insert(key, record);
}
+ apply_in_memory_projection_mutations(&mut self.projections, projections);
self.mutations.remove(&id);
Ok(true)
}
@@ -392,11 +435,108 @@ impl Storage for InMemoryStorage {
async fn clear(&mut self) -> Result<(), Self::Error> {
self.records.clear();
self.search_documents.clear();
+ self.projections.clear();
self.mutations.clear();
Ok(())
}
}
+impl PredicateIndexStorage for InMemoryStorage {
+ async fn delete_batch_with_projections(
+ &mut self,
+ keys: &[EntityKey<'static>],
+ projection_keys: &[PredicateRecordKey],
+ ) -> Result<(), Self::Error> {
+ self.delete_batch(keys).await?;
+ for key in projection_keys {
+ self.projections.remove(key);
+ }
+ Ok(())
+ }
+
+ async fn query_predicate_index(
+ &self,
+ query: &predicate_index::ValidatedIndexQuery,
+ ) -> Result<PredicateQueryResult, Self::Error> {
+ let query_descriptor = query.as_query();
+ let queried_partitions = query_descriptor
+ .partitions
+ .iter()
+ .map(|partition| &partition.partition)
+ .collect::<std::collections::HashSet<_>>();
+ if self.projections.values().any(|projection| {
+ projection.profile() == &query_descriptor.profile
+ && queried_partitions.contains(projection.partition())
+ && matches!(projection, ProjectionState::Incomplete { .. })
+ }) {
+ return Ok(PredicateQueryResult::Incomplete);
+ }
+
+ let documents = self
+ .projections
+ .values()
+ .filter_map(|projection| match projection {
+ ProjectionState::Complete(document) => Some(document.clone()),
+ ProjectionState::Incomplete { .. } => None,
+ })
+ .collect::<Vec<IndexDocument>>();
+ Ok(PredicateQueryResult::Complete(
+ evaluate_reference(query, &documents)
+ .into_iter()
+ .map(|hit| hit.record_key)
+ .collect(),
+ ))
+ }
+
+ async fn get_index_documents(
+ &self,
+ keys: &[PredicateRecordKey],
+ ) -> Result<Vec<Option<IndexDocument>>, Self::Error> {
+ Ok(keys
+ .iter()
+ .map(|key| match self.projections.get(key) {
+ Some(ProjectionState::Complete(document)) => Some(document.clone()),
+ Some(ProjectionState::Incomplete { .. }) | None => None,
+ })
+ .collect())
+ }
+}
+
+fn apply_in_memory_projection_mutations(
+ projections: &mut HashMap<PredicateRecordKey, ProjectionState>,
+ mutations: Vec<ProjectionMutation>,
+) {
+ for mutation in mutations {
+ match mutation {
+ ProjectionMutation::Replace(document) => {
+ projections.insert(
+ document.record_key.clone(),
+ ProjectionState::Complete(document),
+ );
+ }
+ ProjectionMutation::MarkIncomplete {
+ record_key,
+ profile,
+ partition,
+ kind,
+ } => {
+ projections.insert(
+ record_key.clone(),
+ ProjectionState::Incomplete {
+ record_key,
+ profile,
+ partition,
+ kind,
+ },
+ );
+ }
+ ProjectionMutation::Delete(record_key) => {
+ projections.remove(&record_key);
+ }
+ }
+ }
+}
+
fn claim_matches(mutation: &crate::queue::StoredMutation, claim: &MutationClaimToken) -> bool {
mutation.lease_owner.as_deref() == Some(&claim.owner)
&& mutation.lease_generation == claim.generation
diff --git a/crates/client/cache-core/tests/mutation_queue.rs b/crates/client/cache-core/tests/mutation_queue.rs
index 82d3ee4757..ea273da7b2 100644
--- a/crates/client/cache-core/tests/mutation_queue.rs
+++ b/crates/client/cache-core/tests/mutation_queue.rs
@@ -5,6 +5,10 @@ use cache_core::queue::{
use cache_core::store::{InMemoryStorage, Storage};
use cache_core::value::{CacheValue, EntityKey, Record};
use pollster::block_on;
+use predicate_index::{
+ ExactAttributePatch, ExactValue, IndexDocument, IntegerAttributePatch, IntegerFact,
+ OptimisticProjectionMutation, Profile, RecordKey, Token,
+};
use serde_json::json;
#[test]
@@ -13,6 +17,36 @@ fn optimistic_source_supports_versioned_and_legacy_json() {
mutation_data: json!({"rename": {"name": "next"}}),
link_patches: Vec::new(),
revalidations: Vec::new(),
+ projection_mutations: vec![
+ OptimisticProjectionMutation::Replace(IndexDocument {
+ record_key: RecordKey::new("GraphqlSoupDocument:doc-1").unwrap(),
+ profile: Profile::new(Token::new("soup-flat-v1").unwrap()),
+ partition: Token::new("document").unwrap(),
+ exact_facts: Vec::new(),
+ integer_facts: Vec::new(),
+ sort_facts: vec![IntegerFact {
+ attribute: Token::new("updated-at").unwrap(),
+ value: 10,
+ }],
+ }),
+ OptimisticProjectionMutation::Patch {
+ record_key: RecordKey::new("GraphqlSoupDocument:doc-2").unwrap(),
+ profile: Profile::new(Token::new("soup-flat-v1").unwrap()),
+ partition: Token::new("document").unwrap(),
+ exact: vec![ExactAttributePatch {
+ attribute: Token::new("owner").unwrap(),
+ values: vec![ExactValue::utf8("user-1").unwrap()],
+ }],
+ integers: vec![IntegerAttributePatch {
+ attribute: Token::new("updated-at").unwrap(),
+ values: vec![20],
+ }],
+ sorts: vec![IntegerFact {
+ attribute: Token::new("updated-at").unwrap(),
+ value: 20,
+ }],
+ },
+ ],
};
assert_eq!(
decode_optimistic_source(&encode_optimistic_source(&source)).unwrap(),
@@ -30,6 +64,23 @@ fn optimistic_source_supports_versioned_and_legacy_json() {
"rename": {"name": "legacy"}
})
);
+
+ let legacy_v2 = decode_optimistic_source(
+ r#"@macro-cache/optimistic-source:{"version":2,"mutationData":{"rename":{"name":"legacy"}},"linkPatches":[],"revalidations":[]}"#,
+ )
+ .unwrap();
+ assert_eq!(
+ legacy_v2.mutation_data,
+ json!({"rename": {"name": "legacy"}})
+ );
+ assert!(legacy_v2.projection_mutations.is_empty());
+ assert!(
+ decode_optimistic_source(
+ r#"@macro-cache/optimistic-source:{"version":2,"mutationData":{},"projectionMutations":[]}"#,
+ )
+ .is_err(),
+ "version 2 must not silently accept a projection overlay"
+ );
}
fn queued(value: &str, created_at_ms: i64) -> NewQueuedMutation {
diff --git a/crates/client/cache-core/tests/optimistic.rs b/crates/client/cache-core/tests/optimistic.rs
index c037cd56da..e65fd95459 100644
--- a/crates/client/cache-core/tests/optimistic.rs
+++ b/crates/client/cache-core/tests/optimistic.rs
@@ -4,6 +4,7 @@
use cache_core::engine::{
BeginOptimisticWrite, Engine, EngineError, InitialClaimOutcome, ReadResult,
};
+use cache_core::predicate::ProjectionMutation;
use cache_core::queue::{
ClaimedMutation, MutationClaimRequest, MutationClaimToken, MutationId, NewQueuedMutation,
QueuedMutation,
@@ -83,6 +84,18 @@ impl Storage for ClaimFailingStorage {
Ok(())
}
+ async fn put_batch_with_projections(
+ &mut self,
+ entries: Vec<(EntityKey<'static>, Record)>,
+ projections: Vec<ProjectionMutation>,
+ ) -> Result<(), Self::Error> {
+ self.inner
+ .put_batch_with_projections(entries, projections)
+ .await
+ .unwrap();
+ Ok(())
+ }
+
async fn delete_batch(&mut self, keys: &[EntityKey<'static>]) -> Result<(), Self::Error> {
self.inner.delete_batch(keys).await.unwrap();
Ok(())
@@ -136,6 +149,20 @@ impl Storage for ClaimFailingStorage {
.unwrap())
}
+ async fn complete_mutation_with_projections(
+ &mut self,
+ id: MutationId,
+ claim: MutationClaimToken,
+ entries: Vec<(EntityKey<'static>, Record)>,
+ projections: Vec<ProjectionMutation>,
+ ) -> Result<bool, Self::Error> {
+ Ok(self
+ .inner
+ .complete_mutation_with_projections(id, claim, entries, projections)
+ .await
+ .unwrap())
+ }
+
async fn discard_mutation(
&mut self,
id: MutationId,
diff --git a/crates/client/cache-core/tests/predicate.rs b/crates/client/cache-core/tests/predicate.rs
new file mode 100644
index 0000000000..37dda5dd9b
--- /dev/null
+++ b/crates/client/cache-core/tests/predicate.rs
@@ -0,0 +1,716 @@
+use cache_core::{
+ engine::{BeginOptimisticWrite, Engine, EngineError},
+ predicate::{PredicateQueryResult, ProjectionIncompleteKind, ProjectionMutation},
+ queue::{MutationClaimRequest, MutationClaimToken, MutationId},
+ store::{InMemoryStorage, Storage},
+ value::{CacheValue, EntityKey, Record},
+};
+use predicate_index::{
+ ExactAttributePatch, ExactFact, ExactValue, IndexDocument, IndexQuery, IntegerAttributePatch,
+ IntegerFact, MAX_OPTIMISTIC_RECORDS_PER_QUERY, MAX_QUERY_LIMIT, OptimisticProjectionMutation,
+ PartitionPredicate, PredicateExpr, Profile, RecordKey, SortDirection, Token,
+ ValidatedIndexQuery,
+};
+
+fn token(value: &str) -> Token {
+ Token::new(value).unwrap()
+}
+
+fn profile() -> Profile {
+ Profile::new(token("soup-flat-v1"))
+}
+
+fn record_key() -> RecordKey {
+ RecordKey::new("GraphqlSoupDocument:doc-1").unwrap()
+}
+
+fn projection(owner: &str) -> IndexDocument {
+ projection_for(record_key(), owner, 10)
+}
+
+fn projection_for(record_key: RecordKey, owner: &str, updated_at: i64) -> IndexDocument {
+ IndexDocument {
+ record_key,
+ profile: profile(),
+ partition: token("document"),
+ exact_facts: vec![ExactFact {
+ attribute: token("owner"),
+ value: ExactValue::utf8(owner).unwrap(),
+ }],
+ integer_facts: vec![],
+ sort_facts: vec![IntegerFact {
+ attribute: token("updated-at"),
+ value: updated_at,
+ }],
+ }
+}
+
+fn query(owner: &str) -> ValidatedIndexQuery {
+ ValidatedIndexQuery::new(IndexQuery {
+ profile: profile(),
+ partitions: vec![PartitionPredicate {
+ partition: token("document"),
+ predicate: PredicateExpr::Exact {
+ attribute: token("owner"),
+ value: ExactValue::utf8(owner).unwrap(),
+ },
+ }],
+ sort_attribute: token("updated-at"),
+ sort_direction: SortDirection::Desc,
+ tie_break_direction: SortDirection::Desc,
+ limit: 20,
+ })
+ .unwrap()
+}
+
+const OPTIMISTIC_MUTATION: &str = r#"
+ mutation SetEntityProperty($input: SetEntityPropertyInput!) {
+ setEntityProperty(input: $input) {
+ id
+ displayName
+ value {
+ __typename
+ ... on GraphqlStringPropertyValue { stringValue: value }
+ }
+ }
+ }
+"#;
+
+fn optimistic_data() -> serde_json::Value {
+ serde_json::json!({
+ "setEntityProperty": {
+ "id": "prop-1",
+ "displayName": "Status",
+ "value": {
+ "__typename": "GraphqlStringPropertyValue",
+ "stringValue": "doing"
+ }
+ }
+ })
+}
+
+fn optimistic_variables() -> serde_json::Map<String, serde_json::Value> {
+ let serde_json::Value::Object(variables) = serde_json::json!({
+ "input": {
+ "entityType": "DOCUMENT",
+ "entityId": "doc-1",
+ "propertyDefinitionId": "def-1",
+ "value": { "string": "doing" }
+ }
+ }) else {
+ unreachable!()
+ };
+ variables
+}
+
+async fn try_begin_with_projection(
+ engine: &mut Engine<InMemoryStorage>,
+ projection_mutations: Vec<OptimisticProjectionMutation>,
+) -> Result<MutationId, EngineError<std::convert::Infallible>> {
+ engine
+ .begin_optimistic_write_with_projections(
+ None,
+ BeginOptimisticWrite {
+ query: OPTIMISTIC_MUTATION,
+ operation_name: Some("SetEntityProperty"),
+ variables: &optimistic_variables(),
+ data: &optimistic_data(),
+ link_patches: &[],
+ revalidations: &[],
+ created_at_ms: 1,
+ },
+ projection_mutations,
+ )
+ .await
+ .map(|result| result.0)
+}
+
+async fn begin_with_projection(
+ engine: &mut Engine<InMemoryStorage>,
+ projection_mutations: Vec<OptimisticProjectionMutation>,
+) -> MutationId {
+ try_begin_with_projection(engine, projection_mutations)
+ .await
+ .unwrap()
+}
+
+#[test]
+fn replacement_removes_stale_facts_and_incomplete_states_fall_back() {
+ pollster::block_on(async {
+ let mut engine = Engine::new(InMemoryStorage::new());
+ let entity_key = EntityKey::entity("GraphqlSoupDocument", &["doc-1"]);
+ engine
+ .put_records_with_projections(
+ None,
+ vec![(entity_key.clone(), Record::default())],
+ vec![ProjectionMutation::Replace(projection("owner-1"))],
+ )
+ .await
+ .unwrap();
+ assert_eq!(
+ engine
+ .query_predicate_index(&query("owner-1"))
+ .await
+ .unwrap(),
+ PredicateQueryResult::Complete(vec![record_key()])
+ );
+
+ engine
+ .put_records_with_projections(
+ None,
+ vec![(entity_key, Record::default())],
+ vec![ProjectionMutation::Replace(projection("owner-2"))],
+ )
+ .await
+ .unwrap();
+ assert_eq!(
+ engine
+ .query_predicate_index(&query("owner-1"))
+ .await
+ .unwrap(),
+ PredicateQueryResult::Complete(vec![])
+ );
+
+ for kind in [
+ ProjectionIncompleteKind::Dirty,
+ ProjectionIncompleteKind::Missing,
+ ProjectionIncompleteKind::IncompatibleVersion,
+ ] {
+ engine
+ .mark_projections_incomplete(vec![ProjectionMutation::MarkIncomplete {
+ record_key: record_key(),
+ profile: profile(),
+ partition: token("document"),
+ kind,
+ }])
+ .await
+ .unwrap();
+ assert_eq!(
+ engine
+ .query_predicate_index(&query("owner-2"))
+ .await
+ .unwrap(),
+ PredicateQueryResult::Incomplete
+ );
+ engine
+ .put_records_with_projections(
+ None,
+ vec![],
+ vec![ProjectionMutation::Replace(projection("owner-2"))],
+ )
+ .await
+ .unwrap();
+ }
+
+ for mutation in [
+ OptimisticProjectionMutation::Patch {
+ record_key: record_key(),
+ profile: profile(),
+ partition: token("document"),
+ exact: vec![
+ ExactAttributePatch {
+ attribute: token("owner"),
+ values: vec![],
+ },
+ ExactAttributePatch {
+ attribute: token("owner"),
+ values: vec![],
+ },
+ ],
+ integers: vec![],
+ sorts: vec![],
+ },
+ OptimisticProjectionMutation::Patch {
+ record_key: record_key(),
+ profile: profile(),
+ partition: token("document"),
+ exact: vec![],
+ integers: vec![
+ IntegerAttributePatch {
+ attribute: token("updated-at"),
+ values: vec![],
+ },
+ IntegerAttributePatch {
+ attribute: token("updated-at"),
+ values: vec![],
+ },
+ ],
+ sorts: vec![],
+ },
+ OptimisticProjectionMutation::Patch {
+ record_key: record_key(),
+ profile: profile(),
+ partition: token("document"),
+ exact: vec![],
+ integers: vec![],
+ sorts: vec![
+ IntegerFact {
+ attribute: token("updated-at"),
+ value: 1,
+ },
+ IntegerFact {
+ attribute: token("updated-at"),
+ value: 2,
+ },
+ ],
+ },
+ ] {
+ assert!(matches!(
+ try_begin_with_projection(&mut engine, vec![mutation]).await,
+ Err(EngineError::InvalidOptimisticProjection(_))
+ ));
+ }
+
+ let mut too_many_engine = Engine::new(InMemoryStorage::new());
+ begin_with_projection(
+ &mut too_many_engine,
+ (0..=MAX_OPTIMISTIC_RECORDS_PER_QUERY)
+ .map(|index| {
+ OptimisticProjectionMutation::Replace(projection_for(
+ RecordKey::new(format!("GraphqlSoupDocument:doc-{index}")).unwrap(),
+ "owner-1",
+ index as i64,
+ ))
+ })
+ .collect(),
+ )
+ .await;
+ assert_eq!(
+ too_many_engine
+ .query_predicate_index(&query("owner-1"))
+ .await
+ .unwrap(),
+ PredicateQueryResult::Incomplete
+ );
+
+ let mut expanded_limit_engine = Engine::new(InMemoryStorage::new());
+ begin_with_projection(
+ &mut expanded_limit_engine,
+ vec![OptimisticProjectionMutation::Replace(projection("owner-1"))],
+ )
+ .await;
+ let mut maximum_query = query("owner-1").as_query().clone();
+ maximum_query.limit = MAX_QUERY_LIMIT;
+ assert_eq!(
+ expanded_limit_engine
+ .query_predicate_index(&ValidatedIndexQuery::new(maximum_query).unwrap())
+ .await
+ .unwrap(),
+ PredicateQueryResult::Incomplete
+ );
+ });
+}
+
+#[test]
+fn direct_projection_writes_merge_partial_records_and_report_real_changes() {
+ pollster::block_on(async {
+ let mut engine = Engine::new(InMemoryStorage::new());
+ let entity_key = EntityKey::entity("GraphqlSoupDocument", &["doc-1"]);
+ let mut base = Record::default();
+ base.fields.insert(
+ "__typename".into(),
+ CacheValue::String("GraphqlSoupDocument".into()),
+ );
+ base.fields
+ .insert("name".into(), CacheValue::String("Document".into()));
+ engine
+ .put_records_with_projections(
+ None,
+ vec![(entity_key.clone(), base)],
+ vec![ProjectionMutation::Replace(projection("owner-1"))],
+ )
+ .await
+ .unwrap();
+
+ let mut partial = Record::default();
+ partial
+ .fields
+ .insert("name".into(), CacheValue::String("Document".into()));
+ let result = engine
+ .put_records_with_projections(
+ None,
+ vec![(entity_key.clone(), partial)],
+ vec![ProjectionMutation::Replace(projection("owner-2"))],
+ )
+ .await
+ .unwrap();
+ assert!(result.changed.is_empty());
+ assert_eq!(
+ engine
+ .query_predicate_index(&query("owner-2"))
+ .await
+ .unwrap(),
+ PredicateQueryResult::Complete(vec![record_key()])
+ );
+ let stored = engine
+ .storage()
+ .get_batch(&[entity_key])
+ .await
+ .unwrap()
+ .pop()
+ .flatten()
+ .unwrap();
+ assert_eq!(
+ stored.fields.get("__typename"),
+ Some(&CacheValue::String("GraphqlSoupDocument".into()))
+ );
+ });
+}
+
+#[test]
+fn optimistic_projection_layers_are_queryable_offline_and_survive_restart() {
+ pollster::block_on(async {
+ let mut engine = Engine::new(InMemoryStorage::new());
+ let entity_key = EntityKey::entity("GraphqlSoupDocument", &["doc-1"]);
+ engine
+ .put_records_with_projections(
+ None,
+ vec![(entity_key, Record::default())],
+ vec![ProjectionMutation::Replace(projection("owner-1"))],
+ )
+ .await
+ .unwrap();
+ begin_with_projection(
+ &mut engine,
+ vec![OptimisticProjectionMutation::Replace(projection("owner-2"))],
+ )
+ .await;
+
+ assert_eq!(
+ engine
+ .query_predicate_index(&query("owner-1"))
+ .await
+ .unwrap(),
+ PredicateQueryResult::Optimistic(vec![])
+ );
+ assert_eq!(
+ engine
+ .query_predicate_index(&query("owner-2"))
+ .await
+ .unwrap(),
+ PredicateQueryResult::Optimistic(vec![record_key()])
+ );
+
+ let storage = engine.into_storage();
+ let mut reopened = Engine::new(storage);
+ assert_eq!(
+ reopened
+ .query_predicate_index(&query("owner-2"))
+ .await
+ .unwrap(),
+ PredicateQueryResult::Optimistic(vec![record_key()])
+ );
+ });
+}
+
+#[test]
+fn optimistic_fact_patches_update_membership_and_sort_facts() {
+ pollster::block_on(async {
+ let mut engine = Engine::new(InMemoryStorage::new());
+ let second_key = RecordKey::new("GraphqlSoupDocument:doc-2").unwrap();
+ engine
+ .put_records_with_projections(
+ None,
+ vec![
+ (
+ EntityKey::entity("GraphqlSoupDocument", &["doc-1"]),
+ Record::default(),
+ ),
+ (
+ EntityKey::entity("GraphqlSoupDocument", &["doc-2"]),
+ Record::default(),
+ ),
+ ],
+ vec![
+ ProjectionMutation::Replace(projection("owner-1")),
+ ProjectionMutation::Replace(projection_for(second_key.clone(), "owner-2", 15)),
+ ],
+ )
+ .await
+ .unwrap();
+ begin_with_projection(
+ &mut engine,
+ vec![OptimisticProjectionMutation::Patch {
+ record_key: record_key(),
+ profile: profile(),
+ partition: token("document"),
+ exact: vec![ExactAttributePatch {
+ attribute: token("owner"),
+ values: vec![ExactValue::utf8("owner-2").unwrap()],
+ }],
+ integers: vec![IntegerAttributePatch {
+ attribute: token("updated-at"),
+ values: vec![20],
+ }],
+ sorts: vec![IntegerFact {
+ attribute: token("updated-at"),
+ value: 20,
+ }],
+ }],
+ )
+ .await;
+
+ assert_eq!(
+ engine
+ .query_predicate_index(&query("owner-1"))
+ .await
+ .unwrap(),
+ PredicateQueryResult::Optimistic(vec![])
+ );
+ assert_eq!(
+ engine
+ .query_predicate_index(&query("owner-2"))
+ .await
+ .unwrap(),
+ PredicateQueryResult::Optimistic(vec![record_key(), second_key])
+ );
+ });
+}
+
+#[test]
+fn optimistic_projection_rolls_back_and_settles_to_authoritative_facts() {
+ pollster::block_on(async {
+ let mut engine = Engine::new(InMemoryStorage::new());
+ let entity_key = EntityKey::entity("GraphqlSoupDocument", &["doc-1"]);
+ engine
+ .put_records_with_projections(
+ None,
+ vec![(entity_key, Record::default())],
+ vec![ProjectionMutation::Replace(projection("owner-1"))],
+ )
+ .await
+ .unwrap();
+ let transaction = begin_with_projection(
+ &mut engine,
+ vec![OptimisticProjectionMutation::Replace(projection("owner-2"))],
+ )
+ .await;
+ let claim = engine
+ .claim_next_mutation(MutationClaimRequest {
+ owner: "runner".to_owned(),
+ now_ms: 1,
+ lease_expires_at_ms: 100,
+ })
+ .await
+ .unwrap()
+ .unwrap();
+ engine
+ .rollback_optimistic_write(
+ transaction,
+ MutationClaimToken {
+ owner: "runner".to_owned(),
+ generation: claim.lease_generation,
+ },
+ )
+ .await
+ .unwrap();
+ assert_eq!(
+ engine
+ .query_predicate_index(&query("owner-1"))
+ .await
+ .unwrap(),
+ PredicateQueryResult::Complete(vec![record_key()])
+ );
+
+ let transaction = begin_with_projection(
+ &mut engine,
+ vec![OptimisticProjectionMutation::Replace(projection("owner-2"))],
+ )
+ .await;
+ let claim = engine
+ .claim_next_mutation(MutationClaimRequest {
+ owner: "runner".to_owned(),
+ now_ms: 101,
+ lease_expires_at_ms: 200,
+ })
+ .await
+ .unwrap()
+ .unwrap();
+ engine
+ .commit_optimistic_write_with_projections(
+ transaction,
+ MutationClaimToken {
+ owner: "runner".to_owned(),
+ generation: claim.lease_generation,
+ },
+ OPTIMISTIC_MUTATION,
+ Some("SetEntityProperty"),
+ &optimistic_variables(),
+ &optimistic_data(),
+ vec![ProjectionMutation::Replace(projection("owner-3"))],
+ )
+ .await
+ .unwrap();
+ assert_eq!(
+ engine
+ .query_predicate_index(&query("owner-3"))
+ .await
+ .unwrap(),
+ PredicateQueryResult::Complete(vec![record_key()])
+ );
+ });
+}
+
+#[test]
+fn optimistic_deletion_overfetches_authoritative_replacement_candidates() {
+ pollster::block_on(async {
+ let mut engine = Engine::new(InMemoryStorage::new());
+ let first = RecordKey::new("GraphqlSoupDocument:doc-1").unwrap();
+ let second = RecordKey::new("GraphqlSoupDocument:doc-2").unwrap();
+ engine
+ .put_records_with_projections(
+ None,
+ vec![
+ (
+ EntityKey::entity("GraphqlSoupDocument", &["doc-1"]),
+ Record::default(),
+ ),
+ (
+ EntityKey::entity("GraphqlSoupDocument", &["doc-2"]),
+ Record::default(),
+ ),
+ ],
+ vec![
+ ProjectionMutation::Replace(projection_for(first.clone(), "owner-1", 30)),
+ ProjectionMutation::Replace(projection_for(second.clone(), "owner-1", 20)),
+ ],
+ )
+ .await
+ .unwrap();
+ let mut one = query("owner-1").as_query().clone();
+ one.limit = 1;
+ let one = ValidatedIndexQuery::new(one).unwrap();
+ assert_eq!(
+ engine.query_predicate_index(&one).await.unwrap(),
+ PredicateQueryResult::Complete(vec![first.clone()])
+ );
+
+ begin_with_projection(
+ &mut engine,
+ vec![OptimisticProjectionMutation::Delete {
+ record_key: first,
+ profile: profile(),
+ partition: token("document"),
+ }],
+ )
+ .await;
+ assert_eq!(
+ engine.query_predicate_index(&one).await.unwrap(),
+ PredicateQueryResult::Optimistic(vec![second])
+ );
+ });
+}
+
+#[test]
+fn optimistic_delete_and_query_scoped_uncertainty_are_composed() {
+ pollster::block_on(async {
+ let mut engine = Engine::new(InMemoryStorage::new());
+ let entity_key = EntityKey::entity("GraphqlSoupDocument", &["doc-1"]);
+ engine
+ .put_records_with_projections(
+ None,
+ vec![(entity_key, Record::default())],
+ vec![ProjectionMutation::Replace(projection("owner-1"))],
+ )
+ .await
+ .unwrap();
+ begin_with_projection(
+ &mut engine,
+ vec![OptimisticProjectionMutation::Unknown {
+ record_key: record_key(),
+ profile: profile(),
+ partition: token("document"),
+ affected_attributes: vec![token("file-type")],
+ }],
+ )
+ .await;
+ assert_eq!(
+ engine
+ .query_predicate_index(&query("owner-1"))
+ .await
+ .unwrap(),
+ PredicateQueryResult::Optimistic(vec![record_key()])
+ );
+
+ begin_with_projection(
+ &mut engine,
+ vec![OptimisticProjectionMutation::Unknown {
+ record_key: record_key(),
+ profile: profile(),
+ partition: token("document"),
+ affected_attributes: vec![token("updated-at")],
+ }],
+ )
+ .await;
+ assert_eq!(
+ engine
+ .query_predicate_index(&query("owner-1"))
+ .await
+ .unwrap(),
+ PredicateQueryResult::Incomplete
+ );
+
+ let mut delete_engine = Engine::new(engine.into_storage());
+ begin_with_projection(
+ &mut delete_engine,
+ vec![OptimisticProjectionMutation::Delete {
+ record_key: record_key(),
+ profile: profile(),
+ partition: token("document"),
+ }],
+ )
+ .await;
+ assert_eq!(
+ delete_engine
+ .query_predicate_index(&query("owner-1"))
+ .await
+ .unwrap(),
+ PredicateQueryResult::Optimistic(vec![])
+ );
+ });
+}
+
+#[test]
+fn delete_and_clear_remove_projection_state() {
+ pollster::block_on(async {
+ let mut engine = Engine::new(InMemoryStorage::new());
+ let entity_key = EntityKey::entity("GraphqlSoupDocument", &["doc-1"]);
+ engine
+ .put_records_with_projections(
+ None,
+ vec![(entity_key.clone(), Record::default())],
+ vec![ProjectionMutation::Replace(projection("owner-1"))],
+ )
+ .await
+ .unwrap();
+ engine
+ .delete_keys_with_projections(&[entity_key], &[record_key()])
+ .await
+ .unwrap();
+ assert_eq!(
+ engine
+ .query_predicate_index(&query("owner-1"))
+ .await
+ .unwrap(),
+ PredicateQueryResult::Complete(vec![])
+ );
+
+ engine
+ .mark_projections_incomplete(vec![ProjectionMutation::MarkIncomplete {
+ record_key: record_key(),
+ profile: profile(),
+ partition: token("document"),
+ kind: ProjectionIncompleteKind::Dirty,
+ }])
+ .await
+ .unwrap();
+ engine.clear().await.unwrap();
+ assert_eq!(
+ engine
+ .query_predicate_index(&query("owner-1"))
+ .await
+ .unwrap(),
+ PredicateQueryResult::Complete(vec![])
+ );
+ });
+}
diff --git a/crates/client/cache-core/tests/query_inspection.rs b/crates/client/cache-core/tests/query_inspection.rs
index b382392d76..03d20a131f 100644
--- a/crates/client/cache-core/tests/query_inspection.rs
+++ b/crates/client/cache-core/tests/query_inspection.rs
@@ -4,6 +4,7 @@ use cache_core::engine::{BeginOptimisticWrite, Engine};
use cache_core::link_patch::{
LinkOperation, LinkPathSegment, ListItemByScalar, OptimisticLinkPatch,
};
+use cache_core::predicate::ProjectionMutation;
use cache_core::query_inspection::{MAX_INSPECTED_VARIANTS, QueryInspection, QueryInspectionError};
use cache_core::queue::{
ClaimedMutation, MutationClaimRequest, MutationClaimToken, MutationId, NewQueuedMutation,
@@ -104,6 +105,16 @@ impl Storage for OwnerOnlyStorage {
self.0.put_batch(entries).await
}
+ async fn put_batch_with_projections(
+ &mut self,
+ entries: Vec<(EntityKey<'static>, Record)>,
+ projections: Vec<ProjectionMutation>,
+ ) -> Result<(), Self::Error> {
+ self.0
+ .put_batch_with_projections(entries, projections)
+ .await
+ }
+
async fn delete_batch(&mut self, keys: &[EntityKey<'static>]) -> Result<(), Self::Error> {
self.0.delete_batch(keys).await
}
@@ -147,6 +158,18 @@ impl Storage for OwnerOnlyStorage {
self.0.complete_mutation(id, claim, entries).await
}
+ async fn complete_mutation_with_projections(
+ &mut self,
+ id: MutationId,
+ claim: MutationClaimToken,
+ entries: Vec<(EntityKey<'static>, Record)>,
+ projections: Vec<ProjectionMutation>,
+ ) -> Result<bool, Self::Error> {
+ self.0
+ .complete_mutation_with_projections(id, claim, entries, projections)
+ .await
+ }
+
async fn discard_mutation(
&mut self,
id: MutationId,
diff --git a/crates/client/cache-turso/Cargo.toml b/crates/client/cache-turso/Cargo.toml
index f23bf59032..dd23da10d2 100644
--- a/crates/client/cache-turso/Cargo.toml
+++ b/crates/client/cache-turso/Cargo.toml
@@ -11,6 +11,7 @@ browser-test-hooks = []
[dependencies]
cache-core = { path = "../cache-core" }
maybe_send = { path = "../../maybe_send" }
+predicate-index = { path = "../../predicate_index" }
thiserror = { workspace = true }
[target.'cfg(target_arch = "wasm32")'.dependencies]
diff --git a/crates/client/cache-turso/src/storage.rs b/crates/client/cache-turso/src/storage.rs
index b7d4d1c5da..8f44e42caf 100644
--- a/crates/client/cache-turso/src/storage.rs
+++ b/crates/client/cache-turso/src/storage.rs
@@ -4,6 +4,9 @@ use crate::{PhysicalResetReason, TursoStorageError};
use cache_core::codec::{
cache_namespace, decode_record, decode_record_updates, encode_record, encode_record_updates,
};
+use cache_core::predicate::{
+ PredicateIndexStorage, PredicateQueryResult, ProjectionIncompleteKind, ProjectionMutation,
+};
use cache_core::queue::{
ClaimedMutation, MutationClaimRequest, MutationClaimToken, MutationId, MutationRequest,
NewQueuedMutation, PersistedOptimisticLayer, QueuedMutation, StoredMutation,
@@ -11,6 +14,11 @@ use cache_core::queue::{
use cache_core::search::{SearchCursor, SearchDocument, SearchProfile, project_search_documents};
use cache_core::store::{QueueDiagnostics, QueueDiagnosticsAvailability, Storage};
use cache_core::value::{EntityKey, Record};
+use predicate_index::{
+ PredicateExpr, Profile, RangeBound, RecordKey as PredicateRecordKey, SortDirection, Token,
+ ValidatedIndexQuery,
+};
+use std::collections::HashMap;
use std::sync::Arc;
use std::sync::atomic::{AtomicU8, Ordering};
use turso_core::{Connection, Numeric, Value};
@@ -32,7 +40,7 @@ use turso_opfs::{
};
/// Frozen storage schema version, independent of cache postcard versions.
-pub const STORAGE_SCHEMA_VERSION: u32 = 6;
+pub const STORAGE_SCHEMA_VERSION: u32 = 7;
/// Coarse outcome of validating a Turso database.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
@@ -43,7 +51,7 @@ pub enum TursoStorageOpenOutcome {
OpenedNew,
}
-const CREATE_SCHEMA: [&str; 7] = [
+const CREATE_SCHEMA: [&str; 16] = [
"CREATE TABLE meta (key TEXT PRIMARY KEY, value TEXT NOT NULL)",
"CREATE TABLE records (__typename TEXT NOT NULL, id TEXT NOT NULL, value BLOB NOT NULL, PRIMARY KEY (__typename, id))",
"CREATE TABLE search_documents (profile TEXT NOT NULL, __typename TEXT NOT NULL, id TEXT NOT NULL, bucket TEXT NOT NULL, search_text TEXT NOT NULL, timestamp_ms INTEGER NOT NULL, source_hash TEXT NOT NULL, PRIMARY KEY (profile, __typename, id))",
@@ -51,6 +59,15 @@ const CREATE_SCHEMA: [&str; 7] = [
"CREATE TABLE mutation_queue (id INTEGER PRIMARY KEY AUTOINCREMENT, query TEXT NOT NULL, operation_name TEXT, variables_json TEXT NOT NULL, identity TEXT, attempt_count INTEGER NOT NULL DEFAULT 0, next_attempt_at_ms INTEGER, lease_owner TEXT, lease_generation INTEGER NOT NULL DEFAULT 0, lease_expires_at_ms INTEGER, last_error TEXT, created_at_ms INTEGER NOT NULL)",
"CREATE INDEX mutation_queue_created_at_ms_idx ON mutation_queue(created_at_ms)",
"CREATE TABLE optimistic_layers (mutation_id INTEGER PRIMARY KEY, optimistic_data_json TEXT NOT NULL, normalized_updates BLOB NOT NULL, FOREIGN KEY (mutation_id) REFERENCES mutation_queue(id) ON DELETE CASCADE)",
+ "CREATE TABLE index_documents (id INTEGER PRIMARY KEY, record_key TEXT NOT NULL, profile TEXT NOT NULL, partition TEXT NOT NULL, state INTEGER NOT NULL)",
+ "CREATE UNIQUE INDEX index_documents_record_key_idx ON index_documents(record_key)",
+ "CREATE INDEX index_documents_scope_idx ON index_documents(profile, partition, state, id)",
+ "CREATE TABLE exact_facts (document_id INTEGER NOT NULL, attribute TEXT NOT NULL, value BLOB NOT NULL, PRIMARY KEY (document_id, attribute, value), FOREIGN KEY (document_id) REFERENCES index_documents(id) ON DELETE CASCADE)",
+ "CREATE INDEX exact_facts_lookup_idx ON exact_facts(attribute, value, document_id)",
+ "CREATE TABLE integer_facts (document_id INTEGER NOT NULL, attribute TEXT NOT NULL, value INTEGER NOT NULL, PRIMARY KEY (document_id, attribute, value), FOREIGN KEY (document_id) REFERENCES index_documents(id) ON DELETE CASCADE)",
+ "CREATE INDEX integer_facts_lookup_idx ON integer_facts(attribute, value, document_id)",
+ "CREATE TABLE sort_facts (document_id INTEGER NOT NULL, attribute TEXT NOT NULL, value INTEGER NOT NULL, PRIMARY KEY (document_id, attribute), FOREIGN KEY (document_id) REFERENCES index_documents(id) ON DELETE CASCADE)",
+ "CREATE INDEX sort_facts_lookup_idx ON sort_facts(attribute, value, document_id)",
];
const RECORD_GET: &str = "SELECT value FROM records WHERE __typename = ?1 AND id = ?2";
const RECORD_UPSERT: &str = "INSERT INTO records (__typename, id, value) VALUES (?1, ?2, ?3) ON CONFLICT (__typename, id) DO UPDATE SET value = excluded.value";
@@ -60,6 +77,20 @@ const SEARCH_UPSERT: &str = "INSERT INTO search_documents (profile, __typename,
const SEARCH_LOAD: &str = "SELECT __typename, id, bucket, search_text, timestamp_ms, source_hash FROM search_documents WHERE profile = ?1";
const SEARCH_BROWSE: &str = "SELECT __typename, id, bucket, search_text, timestamp_ms, source_hash FROM search_documents INDEXED BY search_documents_browse_idx WHERE profile = ?1 AND bucket = ?2 ORDER BY timestamp_ms DESC, __typename ASC, id ASC LIMIT ?3";
const SEARCH_BROWSE_AFTER: &str = "SELECT __typename, id, bucket, search_text, timestamp_ms, source_hash FROM search_documents INDEXED BY search_documents_browse_idx WHERE profile = ?1 AND bucket = ?2 AND (timestamp_ms < ?3 OR (timestamp_ms = ?3 AND (__typename > ?4 OR (__typename = ?4 AND id > ?5)))) ORDER BY timestamp_ms DESC, __typename ASC, id ASC LIMIT ?6";
+const INDEX_DOCUMENT_UPSERT: &str = "INSERT INTO index_documents (record_key, profile, partition, state) VALUES (?1, ?2, ?3, ?4) ON CONFLICT (record_key) DO UPDATE SET profile = excluded.profile, partition = excluded.partition, state = excluded.state RETURNING id";
+const INDEX_DOCUMENT_ID: &str = "SELECT id FROM index_documents WHERE record_key = ?1";
+const INDEX_DOCUMENT_DELETE: &str = "DELETE FROM index_documents WHERE record_key = ?1";
+const INDEX_FACTS_DELETE: [&str; 3] = [
+ "DELETE FROM exact_facts WHERE document_id = ?1",
+ "DELETE FROM integer_facts WHERE document_id = ?1",
+ "DELETE FROM sort_facts WHERE document_id = ?1",
+];
+const EXACT_FACT_INSERT: &str =
+ "INSERT INTO exact_facts (document_id, attribute, value) VALUES (?1, ?2, ?3)";
+const INTEGER_FACT_INSERT: &str =
+ "INSERT INTO integer_facts (document_id, attribute, value) VALUES (?1, ?2, ?3)";
+const SORT_FACT_INSERT: &str =
+ "INSERT INTO sort_facts (document_id, attribute, value) VALUES (?1, ?2, ?3)";
const QUEUE_INSERT: &str = "INSERT INTO mutation_queue (query, operation_name, variables_json, identity, attempt_count, next_attempt_at_ms, lease_owner, lease_generation, lease_expires_at_ms, last_error, created_at_ms) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, ?11)";
const LAYER_INSERT: &str = "INSERT INTO optimistic_layers (mutation_id, optimistic_data_json, normalized_updates) VALUES (?1, ?2, ?3)";
const QUEUE_SELECT: &str = "SELECT m.id, m.query, m.operation_name, m.variables_json, m.identity, m.attempt_count, m.next_attempt_at_ms, m.lease_owner, m.lease_generation, m.lease_expires_at_ms, m.last_error, m.created_at_ms, o.optimistic_data_json, o.normalized_updates FROM mutation_queue AS m LEFT JOIN optimistic_layers AS o ON o.mutation_id = m.id ORDER BY m.id ASC";
@@ -728,6 +759,38 @@ impl Storage for TursoStorage {
self.latch_result(result)
}
+ async fn put_batch_with_projections(
+ &mut self,
+ entries: Vec<(EntityKey<'static>, Record)>,
+ projections: Vec<ProjectionMutation>,
+ ) -> Result<(), Self::Error> {
+ self.require_healthy()?;
+ let result = (|| {
+ let entries = prepare_records(entries)?;
+ let connection = self.connection();
+ driver::write_transaction(&connection, || {
+ let mut statement = driver::prepare(&connection, RECORD_UPSERT)?;
+ for (index, entry) in entries.iter().enumerate() {
+ require_changed(
+ driver::execute_prepared(
+ &mut statement,
+ vec![
+ text(&entry.key.typename),
+ text(&entry.key.id),
+ Value::from_blob(entry.value.clone()),
+ ],
+ )?,
+ 1,
+ )?;
+ self.fault_after(TestFaultSite::Put, index)?;
+ }
+ write_search_documents(&connection, &entries)?;
+ write_projection_mutations(&connection, projections)
+ })
+ })();
+ self.latch_result(result)
+ }
+
async fn delete_batch(&mut self, keys: &[EntityKey<'static>]) -> Result<(), Self::Error> {
self.require_healthy()?;
let result = (|| {
@@ -1010,6 +1073,17 @@ impl Storage for TursoStorage {
id: MutationId,
claim: MutationClaimToken,
entries: Vec<(EntityKey<'static>, Record)>,
+ ) -> Result<bool, Self::Error> {
+ self.complete_mutation_with_projections(id, claim, entries, Vec::new())
+ .await
+ }
+
+ async fn complete_mutation_with_projections(
+ &mut self,
+ id: MutationId,
+ claim: MutationClaimToken,
+ entries: Vec<(EntityKey<'static>, Record)>,
+ projections: Vec<ProjectionMutation>,
) -> Result<bool, Self::Error> {
self.require_healthy()?;
let result = (|| {
@@ -1040,6 +1114,7 @@ impl Storage for TursoStorage {
}
}
write_search_documents(&connection, &entries)?;
+ write_projection_mutations(&connection, projections)?;
require_changed(
driver::execute(
&connection,
@@ -1094,6 +1169,7 @@ impl Storage for TursoStorage {
driver::execute(&connection, "DELETE FROM mutation_queue", Vec::new())?;
self.fault_after(TestFaultSite::Clear, 1)?;
driver::execute(&connection, "DELETE FROM search_documents", Vec::new())?;
+ driver::execute(&connection, "DELETE FROM index_documents", Vec::new())?;
driver::execute(&connection, "DELETE FROM records", Vec::new())?;
self.fault_after(TestFaultSite::Clear, 2)?;
Ok(())
@@ -1103,6 +1179,504 @@ impl Storage for TursoStorage {
}
}
+impl PredicateIndexStorage for TursoStorage {
+ async fn delete_batch_with_projections(
+ &mut self,
+ keys: &[EntityKey<'static>],
+ projection_keys: &[PredicateRecordKey],
+ ) -> Result<(), Self::Error> {
+ self.require_healthy()?;
+ let result = (|| {
+ let keys = keys
+ .iter()
+ .map(RecordKey::from_entity)
+ .collect::<Result<Vec<_>, _>>()?;
+ let connection = self.connection();
+ driver::write_transaction(&connection, || {
+ let mut record_statement = driver::prepare(&connection, RECORD_DELETE)?;
+ let mut search_statement = driver::prepare(&connection, SEARCH_DELETE)?;
+ for key in &keys {
+ let changed = driver::execute_prepared(
+ &mut record_statement,
+ vec![text(&key.typename), text(&key.id)],
+ )?;
+ if !(0..=1).contains(&changed) {
+ return Err(invariant());
+ }
+ driver::execute_prepared(
+ &mut search_statement,
+ vec![text(&key.typename), text(&key.id)],
+ )?;
+ }
+ 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(())
+ })
+ })();
+ self.latch_result(result)
+ }
+
+ async fn query_predicate_index(
+ &self,
+ query: &ValidatedIndexQuery,
+ ) -> Result<PredicateQueryResult, Self::Error> {
+ self.require_healthy()?;
+ let connection = self.connection();
+ let result = driver::read_transaction(&connection, || {
+ if predicate_scope_is_incomplete(&connection, query)? {
+ return Ok(PredicateQueryResult::Incomplete);
+ }
+ let (sql, parameters) = compile_predicate_sql(query);
+ let rows = driver::query(&connection, &sql, parameters)?;
+ let mut keys = Vec::with_capacity(rows.len());
+ for row in rows {
+ if row.len() != 1 {
+ return Err(invariant());
+ }
+ keys.push(
+ PredicateRecordKey::new(required_text(&row, 0)?).map_err(|_| invariant())?,
+ );
+ }
+ Ok(PredicateQueryResult::Complete(keys))
+ });
+ self.latch_result(result)
+ }
+
+ async fn get_index_documents(
+ &self,
+ keys: &[PredicateRecordKey],
+ ) -> Result<Vec<Option<predicate_index::IndexDocument>>, Self::Error> {
+ self.require_healthy()?;
+ let connection = self.connection();
+ let result =
+ driver::read_transaction(&connection, || load_index_documents(&connection, keys));
+ self.latch_result(result)
+ }
+}
+
+fn write_projection_mutations(
+ connection: &Arc<Connection>,
+ projections: Vec<ProjectionMutation>,
+) -> Result<(), TursoStorageError> {
+ for mutation in projections {
+ match mutation {
+ ProjectionMutation::Replace(document) => {
+ document.validate().map_err(|_| invariant())?;
+ let document_id = upsert_index_document(
+ connection,
+ &document.record_key,
+ &document.profile,
+ &document.partition,
+ 0,
+ )?;
+ delete_index_facts(connection, document_id)?;
+ for fact in document.exact_facts {
+ require_changed(
+ driver::execute(
+ connection,
+ EXACT_FACT_INSERT,
+ vec![
+ Value::from_i64(document_id),
+ text(fact.attribute.as_str()),
+ Value::from_blob(fact.value.as_bytes().to_vec()),
+ ],
+ )?,
+ 1,
+ )?;
+ }
+ for fact in document.integer_facts {
+ require_changed(
+ driver::execute(
+ connection,
+ INTEGER_FACT_INSERT,
+ vec![
+ Value::from_i64(document_id),
+ text(fact.attribute.as_str()),
+ Value::from_i64(fact.value),
+ ],
+ )?,
+ 1,
+ )?;
+ }
+ for fact in document.sort_facts {
+ require_changed(
+ driver::execute(
+ connection,
+ SORT_FACT_INSERT,
+ vec![
+ Value::from_i64(document_id),
+ text(fact.attribute.as_str()),
+ Value::from_i64(fact.value),
+ ],
+ )?,
+ 1,
+ )?;
+ }
+ }
+ ProjectionMutation::MarkIncomplete {
+ record_key,
+ profile,
+ partition,
+ kind,
+ } => {
+ let document_id = upsert_index_document(
+ connection,
+ &record_key,
+ &profile,
+ &partition,
+ projection_state_code(kind),
+ )?;
+ delete_index_facts(connection, document_id)?;
+ }
+ ProjectionMutation::Delete(record_key) => {
+ let changed = driver::execute(
+ connection,
+ INDEX_DOCUMENT_DELETE,
+ vec![text(record_key.as_str())],
+ )?;
+ if !(0..=1).contains(&changed) {
+ return Err(invariant());
+ }
+ }
+ }
+ }
+ Ok(())
+}
+
+fn upsert_index_document(
+ connection: &Arc<Connection>,
+ record_key: &PredicateRecordKey,
+ profile: &Profile,
+ partition: &Token,
+ state: i64,
+) -> Result<i64, TursoStorageError> {
+ let rows = driver::query(
+ connection,
+ INDEX_DOCUMENT_UPSERT,
+ vec![
+ text(record_key.as_str()),
+ text(profile.token().as_str()),
+ text(partition.as_str()),
+ Value::from_i64(state),
+ ],
+ )?;
+ match rows.as_slice() {
+ [row] if row.len() == 1 => required_i64(row, 0),
+ _ => Err(invariant()),
+ }
+}
+
+fn delete_index_facts(
+ connection: &Arc<Connection>,
+ document_id: i64,
+) -> Result<(), TursoStorageError> {
+ for sql in INDEX_FACTS_DELETE {
+ let changed = driver::execute(connection, sql, vec![Value::from_i64(document_id)])?;
+ if changed < 0 {
+ return Err(invariant());
+ }
+ }
+ Ok(())
+}
+
+fn projection_state_code(kind: ProjectionIncompleteKind) -> i64 {
+ match kind {
+ ProjectionIncompleteKind::Dirty => 1,
+ ProjectionIncompleteKind::Missing => 2,
+ ProjectionIncompleteKind::IncompatibleVersion => 3,
+ }
+}
+
+fn load_index_documents(
+ connection: &Arc<Connection>,
+ keys: &[PredicateRecordKey],
+) -> Result<Vec<Option<predicate_index::IndexDocument>>, TursoStorageError> {
+ if keys.is_empty() {
+ return Ok(Vec::new());
+ }
+ let placeholders = (1..=keys.len())
+ .map(|index| format!("?{index}"))
+ .collect::<Vec<_>>()
+ .join(", ");
+ let rows = driver::query(
+ connection,
+ &format!(
+ "SELECT id, record_key, profile, partition FROM index_documents WHERE state = 0 AND record_key IN ({placeholders})"
+ ),
+ keys.iter().map(|key| text(key.as_str())).collect(),
+ )?;
+ let mut by_id = HashMap::with_capacity(rows.len());
+ let mut documents = HashMap::with_capacity(rows.len());
+ for row in rows {
+ if row.len() != 4 {
+ return Err(invariant());
+ }
+ let id = required_i64(&row, 0)?;
+ let record_key =
+ PredicateRecordKey::new(required_text(&row, 1)?).map_err(|_| invariant())?;
+ let profile = Profile::new(Token::new(required_text(&row, 2)?).map_err(|_| invariant())?);
+ let partition = Token::new(required_text(&row, 3)?).map_err(|_| invariant())?;
+ by_id.insert(id, record_key.clone());
+ documents.insert(
+ record_key.clone(),
+ predicate_index::IndexDocument {
+ record_key,
+ profile,
+ partition,
+ exact_facts: Vec::new(),
+ integer_facts: Vec::new(),
+ sort_facts: Vec::new(),
+ },
+ );
+ }
+ if by_id.is_empty() {
+ return Ok(vec![None; keys.len()]);
+ }
+
+ let id_placeholders = (1..=by_id.len())
+ .map(|index| format!("?{index}"))
+ .collect::<Vec<_>>()
+ .join(", ");
+ let ids = by_id.keys().copied().collect::<Vec<_>>();
+ let id_parameters = || ids.iter().copied().map(Value::from_i64).collect::<Vec<_>>();
+ for row in driver::query(
+ connection,
+ &format!(
+ "SELECT document_id, attribute, value FROM exact_facts WHERE document_id IN ({id_placeholders})"
+ ),
+ id_parameters(),
+ )? {
+ let record_key = by_id.get(&required_i64(&row, 0)?).ok_or_else(invariant)?;
+ documents
+ .get_mut(record_key)
+ .ok_or_else(invariant)?
+ .exact_facts
+ .push(predicate_index::ExactFact {
+ attribute: Token::new(required_text(&row, 1)?).map_err(|_| invariant())?,
+ value: predicate_index::ExactValue::new(required_blob(&row, 2)?)
+ .map_err(|_| invariant())?,
+ });
+ }
+ for row in driver::query(
+ connection,
+ &format!(
+ "SELECT document_id, attribute, value FROM integer_facts WHERE document_id IN ({id_placeholders})"
+ ),
+ id_parameters(),
+ )? {
+ let record_key = by_id.get(&required_i64(&row, 0)?).ok_or_else(invariant)?;
+ documents
+ .get_mut(record_key)
+ .ok_or_else(invariant)?
+ .integer_facts
+ .push(predicate_index::IntegerFact {
+ attribute: Token::new(required_text(&row, 1)?).map_err(|_| invariant())?,
+ value: required_i64(&row, 2)?,
+ });
+ }
+ for row in driver::query(
+ connection,
+ &format!(
+ "SELECT document_id, attribute, value FROM sort_facts WHERE document_id IN ({id_placeholders})"
+ ),
+ id_parameters(),
+ )? {
+ let record_key = by_id.get(&required_i64(&row, 0)?).ok_or_else(invariant)?;
+ documents
+ .get_mut(record_key)
+ .ok_or_else(invariant)?
+ .sort_facts
+ .push(predicate_index::IntegerFact {
+ attribute: Token::new(required_text(&row, 1)?).map_err(|_| invariant())?,
+ value: required_i64(&row, 2)?,
+ });
+ }
+
+ for document in documents.values() {
+ document.validate().map_err(|_| invariant())?;
+ }
+ Ok(keys.iter().map(|key| documents.get(key).cloned()).collect())
+}
+
+fn predicate_scope_is_incomplete(
+ connection: &Arc<Connection>,
+ query: &ValidatedIndexQuery,
+) -> Result<bool, TursoStorageError> {
+ let descriptor = query.as_query();
+ let clauses = descriptor
+ .partitions
+ .iter()
+ .map(|_| "(profile = ? AND partition = ?)")
+ .collect::<Vec<_>>()
+ .join(" OR ");
+ let sql = format!("SELECT 1 FROM index_documents WHERE state <> 0 AND ({clauses}) LIMIT 1");
+ let mut parameters = Vec::with_capacity(descriptor.partitions.len() * 2);
+ for partition in &descriptor.partitions {
+ parameters.push(text(descriptor.profile.token().as_str()));
+ parameters.push(text(partition.partition.as_str()));
+ }
+ Ok(!driver::query(connection, &sql, parameters)?.is_empty())
+}
+
+fn compile_predicate_sql(query: &ValidatedIndexQuery) -> (String, Vec<Value>) {
+ let descriptor = query.as_query();
+ let mut compiler = SqlPredicateCompiler::default();
+ let roots = descriptor
+ .partitions
+ .iter()
+ .map(|partition| {
+ compiler.compile(
+ &partition.predicate,
+ &descriptor.profile,
+ &partition.partition,
+ )
+ })
+ .collect::<Vec<_>>();
+ let matches = compiler.next_name();
+ let union = roots
+ .iter()
+ .map(|root| format!("SELECT document_id FROM {root}"))
+ .collect::<Vec<_>>()
+ .join(" UNION ");
+ compiler
+ .ctes
+ .push(format!("{matches}(document_id) AS ({union})"));
+ compiler
+ .parameters
+ .push(text(descriptor.sort_attribute.as_str()));
+ compiler
+ .parameters
+ .push(Value::from_i64(i64::from(descriptor.limit)));
+ let sort_direction = match descriptor.sort_direction {
+ SortDirection::Asc => "ASC",
+ SortDirection::Desc => "DESC",
+ };
+ let tie_direction = match descriptor.tie_break_direction {
+ SortDirection::Asc => "ASC",
+ SortDirection::Desc => "DESC",
+ };
+ let sql = format!(
+ "WITH {} SELECT d.record_key FROM {matches} AS m JOIN index_documents AS d ON d.id = m.document_id JOIN sort_facts AS s ON s.document_id = d.id WHERE s.attribute = ? ORDER BY s.value {sort_direction}, d.record_key {tie_direction} LIMIT ?",
+ compiler.ctes.join(", ")
+ );
+ (sql, compiler.parameters)
+}
+
+#[derive(Default)]
+struct SqlPredicateCompiler {
+ ctes: Vec<String>,
+ parameters: Vec<Value>,
+ next_id: usize,
+}
+
+impl SqlPredicateCompiler {
+ fn next_name(&mut self) -> String {
+ let name = format!("expr_{}", self.next_id);
+ self.next_id += 1;
+ name
+ }
+
+ fn compile(&mut self, expr: &PredicateExpr, profile: &Profile, partition: &Token) -> String {
+ match expr {
+ PredicateExpr::All => self.universe(profile, partition),
+ PredicateExpr::None => {
+ let name = self.next_name();
+ self.ctes.push(format!(
+ "{name}(document_id) AS (SELECT id FROM index_documents WHERE 0)"
+ ));
+ name
+ }
+ PredicateExpr::Exact { attribute, value } => {
+ let name = self.next_name();
+ self.parameters.push(text(profile.token().as_str()));
+ self.parameters.push(text(partition.as_str()));
+ self.parameters.push(text(attribute.as_str()));
+ self.parameters
+ .push(Value::from_blob(value.as_bytes().to_vec()));
+ self.ctes.push(format!(
+ "{name}(document_id) AS (SELECT f.document_id FROM exact_facts AS f JOIN index_documents AS d ON d.id = f.document_id WHERE d.profile = ? AND d.partition = ? AND d.state = 0 AND f.attribute = ? AND f.value = ?)"
+ ));
+ name
+ }
+ PredicateExpr::I64Range {
+ attribute,
+ lower,
+ upper,
+ } => {
+ let name = self.next_name();
+ self.parameters.push(text(profile.token().as_str()));
+ self.parameters.push(text(partition.as_str()));
+ self.parameters.push(text(attribute.as_str()));
+ let mut range = String::new();
+ if let Some(bound) = lower {
+ let (operator, value) = sql_bound(*bound, true);
+ range.push_str(&format!(" AND f.value {operator} ?"));
+ self.parameters.push(Value::from_i64(value));
+ }
+ if let Some(bound) = upper {
+ let (operator, value) = sql_bound(*bound, false);
+ range.push_str(&format!(" AND f.value {operator} ?"));
+ self.parameters.push(Value::from_i64(value));
+ }
+ self.ctes.push(format!(
+ "{name}(document_id) AS (SELECT f.document_id FROM integer_facts AS f JOIN index_documents AS d ON d.id = f.document_id WHERE d.profile = ? AND d.partition = ? AND d.state = 0 AND f.attribute = ?{range})"
+ ));
+ name
+ }
+ PredicateExpr::And(left, right) | PredicateExpr::Or(left, right) => {
+ let left = self.compile(left, profile, partition);
+ let right = self.compile(right, profile, partition);
+ let operator = if matches!(expr, PredicateExpr::And(_, _)) {
+ "INTERSECT"
+ } else {
+ "UNION"
+ };
+ let name = self.next_name();
+ self.ctes.push(format!(
+ "{name}(document_id) AS (SELECT document_id FROM {left} {operator} SELECT document_id FROM {right})"
+ ));
+ name
+ }
+ PredicateExpr::Not(expr) => {
+ let universe = self.universe(profile, partition);
+ let child = self.compile(expr, profile, partition);
+ let name = self.next_name();
+ self.ctes.push(format!(
+ "{name}(document_id) AS (SELECT document_id FROM {universe} EXCEPT SELECT document_id FROM {child})"
+ ));
+ name
+ }
+ }
+ }
+
+ fn universe(&mut self, profile: &Profile, partition: &Token) -> String {
+ let name = self.next_name();
+ self.parameters.push(text(profile.token().as_str()));
+ self.parameters.push(text(partition.as_str()));
+ self.ctes.push(format!(
+ "{name}(document_id) AS (SELECT id FROM index_documents WHERE profile = ? AND partition = ? AND state = 0)"
+ ));
+ name
+ }
+}
+
+fn sql_bound(bound: RangeBound, lower: bool) -> (&'static str, i64) {
+ match (lower, bound) {
+ (true, RangeBound::Inclusive(value)) => (">=", value),
+ (true, RangeBound::Exclusive(value)) => (">", value),
+ (false, RangeBound::Inclusive(value)) => ("<=", value),
+ (false, RangeBound::Exclusive(value)) => ("<", value),
+ }
+}
+
fn initialize(
connection: &Arc<Connection>,
scope: &str,
@@ -1171,6 +1745,12 @@ fn initialize(
SEARCH_LOAD,
SEARCH_BROWSE,
SEARCH_BROWSE_AFTER,
+ INDEX_DOCUMENT_UPSERT,
+ INDEX_DOCUMENT_ID,
+ INDEX_DOCUMENT_DELETE,
+ EXACT_FACT_INSERT,
+ INTEGER_FACT_INSERT,
+ SORT_FACT_INSERT,
QUEUE_INSERT,
LAYER_INSERT,
QUEUE_SELECT,
@@ -1182,6 +1762,9 @@ fn initialize(
] {
driver::validate(connection, sql).map_err(TursoStorageError::initialization)?;
}
+ for sql in INDEX_FACTS_DELETE {
+ driver::validate(connection, sql).map_err(TursoStorageError::initialization)?;
+ }
validate_queue_consistency(connection)
}
@@ -1408,6 +1991,116 @@ const OPTIMISTIC_COLUMNS: &[ColumnSpec] = &[
},
];
+const INDEX_DOCUMENT_COLUMNS: &[ColumnSpec] = &[
+ ColumnSpec {
+ name: "id",
+ declared_type: "INTEGER",
+ not_null: false,
+ default_zero: false,
+ primary_key_position: 1,
+ },
+ ColumnSpec {
+ name: "record_key",
+ declared_type: "TEXT",
+ not_null: true,
+ default_zero: false,
+ primary_key_position: 0,
+ },
+ ColumnSpec {
+ name: "profile",
+ declared_type: "TEXT",
+ not_null: true,
+ default_zero: false,
+ primary_key_position: 0,
+ },
+ ColumnSpec {
+ name: "partition",
+ declared_type: "TEXT",
+ not_null: true,
+ default_zero: false,
+ primary_key_position: 0,
+ },
+ ColumnSpec {
+ name: "state",
+ declared_type: "INTEGER",
+ not_null: true,
+ default_zero: false,
+ primary_key_position: 0,
+ },
+];
+
+const EXACT_FACT_COLUMNS: &[ColumnSpec] = &[
+ ColumnSpec {
+ name: "document_id",
+ declared_type: "INTEGER",
+ not_null: true,
+ default_zero: false,
+ primary_key_position: 1,
+ },
+ ColumnSpec {
+ name: "attribute",
+ declared_type: "TEXT",
+ not_null: true,
+ default_zero: false,
+ primary_key_position: 2,
+ },
+ ColumnSpec {
+ name: "value",
+ declared_type: "BLOB",
+ not_null: true,
+ default_zero: false,
+ primary_key_position: 3,
+ },
+];
+
+const INTEGER_FACT_COLUMNS: &[ColumnSpec] = &[
+ ColumnSpec {
+ name: "document_id",
+ declared_type: "INTEGER",
+ not_null: true,
+ default_zero: false,
+ primary_key_position: 1,
+ },
+ ColumnSpec {
+ name: "attribute",
+ declared_type: "TEXT",
+ not_null: true,
+ default_zero: false,
+ primary_key_position: 2,
+ },
+ ColumnSpec {
+ name: "value",
+ declared_type: "INTEGER",
+ not_null: true,
+ default_zero: false,
+ primary_key_position: 3,
+ },
+];
+
+const SORT_FACT_COLUMNS: &[ColumnSpec] = &[
+ ColumnSpec {
+ name: "document_id",
+ declared_type: "INTEGER",
+ not_null: true,
+ default_zero: false,
+ primary_key_position: 1,
+ },
+ ColumnSpec {
+ name: "attribute",
+ declared_type: "TEXT",
+ not_null: true,
+ default_zero: false,
+ primary_key_position: 2,
+ },
+ ColumnSpec {
+ name: "value",
+ declared_type: "INTEGER",
+ not_null: true,
+ default_zero: false,
+ primary_key_position: 0,
+ },
+];
+
fn validate_frozen_schema(connection: &Arc<Connection>) -> Result<(), TursoStorageError> {
validate_allowed_schema_objects(connection)?;
validate_table_columns(connection, "meta", META_COLUMNS)?;
@@ -1415,21 +2108,34 @@ fn validate_frozen_schema(connection: &Arc<Connection>) -> Result<(), TursoStora
validate_table_columns(connection, "search_documents", SEARCH_COLUMNS)?;
validate_table_columns(connection, "mutation_queue", MUTATION_COLUMNS)?;
validate_table_columns(connection, "optimistic_layers", OPTIMISTIC_COLUMNS)?;
+ validate_table_columns(connection, "index_documents", INDEX_DOCUMENT_COLUMNS)?;
+ validate_table_columns(connection, "exact_facts", EXACT_FACT_COLUMNS)?;
+ validate_table_columns(connection, "integer_facts", INTEGER_FACT_COLUMNS)?;
+ validate_table_columns(connection, "sort_facts", SORT_FACT_COLUMNS)?;
validate_table_indexes(connection, "meta", &[(0, "key")])?;
validate_table_indexes(connection, "records", &[(0, "__typename"), (1, "id")])?;
validate_search_indexes(connection)?;
validate_mutation_queue_indexes(connection)?;
validate_table_indexes(connection, "optimistic_layers", &[])?;
+ validate_predicate_indexes(connection)?;
validate_table_constraints(connection, "meta", false)?;
validate_table_constraints(connection, "records", false)?;
validate_table_constraints(connection, "search_documents", false)?;
validate_table_constraints(connection, "mutation_queue", true)?;
validate_table_constraints(connection, "optimistic_layers", false)?;
+ validate_table_constraints(connection, "index_documents", false)?;
+ validate_table_constraints(connection, "exact_facts", false)?;
+ validate_table_constraints(connection, "integer_facts", false)?;
+ validate_table_constraints(connection, "sort_facts", false)?;
validate_no_foreign_keys(connection, "meta")?;
validate_no_foreign_keys(connection, "records")?;
validate_no_foreign_keys(connection, "search_documents")?;
validate_no_foreign_keys(connection, "mutation_queue")?;
- validate_optimistic_foreign_key(connection)
+ validate_no_foreign_keys(connection, "index_documents")?;
+ validate_optimistic_foreign_key(connection)?;
+ validate_fact_foreign_key(connection, "exact_facts")?;
+ validate_fact_foreign_key(connection, "integer_facts")?;
+ validate_fact_foreign_key(connection, "sort_facts")
}
const SQLITE_SEQUENCE_TABLE: &str = "sqlite_sequence";
@@ -1444,16 +2150,28 @@ fn validate_allowed_schema_objects(connection: &Arc<Connection>) -> Result<(), T
)
.map_err(TursoStorageError::initialization)?;
let expected = [
+ "exact_facts",
+ "index_documents",
+ "integer_facts",
"meta",
"mutation_queue",
"optimistic_layers",
"records",
"search_documents",
+ "sort_facts",
+ ];
+ let named_indexes = [
+ "exact_facts_lookup_idx",
+ "index_documents_scope_idx",
+ "integer_facts_lookup_idx",
+ "index_documents_record_key_idx",
+ "mutation_queue_created_at_ms_idx",
+ "search_documents_browse_idx",
+ "sort_facts_lookup_idx",
];
let support = [SQLITE_SEQUENCE_TABLE, TURSO_AUTOINCREMENT_TABLE];
- let mut seen = [false; 5];
- let mut diagnostics_index_seen = false;
- let mut search_index_seen = false;
+ let mut seen = [false; 9];
+ let mut named_index_seen = [false; 7];
let mut support_seen = [false; 2];
for row in rows {
if row.len() != 3 {
@@ -1474,27 +2192,14 @@ fn validate_allowed_schema_objects(connection: &Arc<Connection>) -> Result<(), T
if object_type == "index" && matches!(row.get(2), Some(Value::Null)) {
continue;
}
- if name == "search_documents_browse_idx" {
+ if let Some(position) = named_indexes.iter().position(|expected| *expected == name) {
if object_type != "index"
|| !matches!(row.get(2), Some(Value::Text(_)))
- || search_index_seen
+ || named_index_seen[position]
{
return Err(compatibility());
}
- search_index_seen = true;
- continue;
- }
- if name == "mutation_queue_created_at_ms_idx" {
- if object_type != "index"
- || required_text(&row, 2).ok().as_deref()
- != Some(
- "CREATE INDEX mutation_queue_created_at_ms_idx ON mutation_queue (created_at_ms)",
- )
- || diagnostics_index_seen
- {
- return Err(compatibility());
- }
- diagnostics_index_seen = true;
+ named_index_seen[position] = true;
continue;
}
if let Some(position) = support.iter().position(|expected| *expected == name) {
@@ -1511,8 +2216,7 @@ fn validate_allowed_schema_objects(connection: &Arc<Connection>) -> Result<(), T
return Err(compatibility());
}
if seen.into_iter().all(|present| present)
- && diagnostics_index_seen
- && search_index_seen
+ && named_index_seen.into_iter().all(|present| present)
&& support_seen.into_iter().all(|present| present)
{
Ok(())
@@ -1988,6 +2692,63 @@ fn scan_quoted(
Err(compatibility())
}
+fn validate_predicate_indexes(connection: &Arc<Connection>) -> Result<(), TursoStorageError> {
+ for (table, index, expected_columns) in [
+ (
+ "index_documents",
+ "index_documents_scope_idx",
+ &["profile", "partition", "state", "id"][..],
+ ),
+ (
+ "exact_facts",
+ "exact_facts_lookup_idx",
+ &["attribute", "value", "document_id"][..],
+ ),
+ (
+ "integer_facts",
+ "integer_facts_lookup_idx",
+ &["attribute", "value", "document_id"][..],
+ ),
+ (
+ "sort_facts",
+ "sort_facts_lookup_idx",
+ &["attribute", "value", "document_id"][..],
+ ),
+ ] {
+ let indexes = driver::query(
+ connection,
+ &format!("PRAGMA index_list('{table}')"),
+ Vec::new(),
+ )
+ .map_err(TursoStorageError::initialization)?;
+ if indexes.len() != 2
+ || !indexes
+ .iter()
+ .any(|row| required_text(row, 1).ok().as_deref() == Some(index))
+ {
+ return Err(compatibility());
+ }
+ let columns = driver::query(
+ connection,
+ &format!("PRAGMA index_info('{index}')"),
+ Vec::new(),
+ )
+ .map_err(TursoStorageError::initialization)?;
+ if columns.len() != expected_columns.len()
+ || columns.iter().zip(expected_columns).enumerate().any(
+ |(position, (row, expected))| {
+ row.len() != 3
+ || required_i64(row, 0).ok() != i64::try_from(position).ok()
+ || required_text(row, 2).ok().as_deref() != Some(*expected)
+ },
+ )
+ {
+ return Err(compatibility());
+ }
+ }
+ Ok(())
+}
+
fn validate_no_foreign_keys(
connection: &Arc<Connection>,
table: &str,
@@ -2032,6 +2793,34 @@ fn validate_optimistic_foreign_key(connection: &Arc<Connection>) -> Result<(), T
Ok(())
}
+fn validate_fact_foreign_key(
+ connection: &Arc<Connection>,
+ table: &str,
+) -> Result<(), TursoStorageError> {
+ let rows = driver::query(
+ connection,
+ &format!("PRAGMA foreign_key_list('{}')", table.replace('\'', "''")),
+ Vec::new(),
+ )
+ .map_err(TursoStorageError::initialization)?;
+ let [row] = rows.as_slice() else {
+ return Err(compatibility());
+ };
+ if row.len() != 8
+ || required_i64(row, 0).ok() != Some(0)
+ || required_i64(row, 1).ok() != Some(0)
+ || required_text(row, 2).ok().as_deref() != Some("index_documents")
+ || required_text(row, 3).ok().as_deref() != Some("document_id")
+ || required_text(row, 4).ok().as_deref() != Some("id")
+ || required_text(row, 5).ok().as_deref() != Some("NO ACTION")
+ || required_text(row, 6).ok().as_deref() != Some("CASCADE")
+ || required_text(row, 7).ok().as_deref() != Some("NONE")
+ {
+ return Err(compatibility());
+ }
+ Ok(())
+}
+
fn compatibility() -> TursoStorageError {
TursoStorageError::reset(PhysicalResetReason::Compatibility)
}
diff --git a/crates/client/cache-turso/src/storage/test.rs b/crates/client/cache-turso/src/storage/test.rs
index ac0b20d8d2..b47f3d265f 100644
--- a/crates/client/cache-turso/src/storage/test.rs
+++ b/crates/client/cache-turso/src/storage/test.rs
@@ -1488,6 +1488,55 @@ fn fault_storage(io: Arc<FaultIo>) -> TursoStorage {
}
}
+#[test]
+fn predicate_query_plan_uses_fact_indexes_and_never_scans_record_blobs() {
+ let storage = TursoStorage::open_in_memory("predicate-query-plan").unwrap();
+ let token = |value| Token::new(value).unwrap();
+ let query = ValidatedIndexQuery::new(predicate_index::IndexQuery {
+ profile: Profile::new(token("soup-flat-v1")),
+ partitions: vec![predicate_index::PartitionPredicate {
+ partition: token("document"),
+ predicate: PredicateExpr::And(
+ Box::new(PredicateExpr::Exact {
+ attribute: token("owner"),
+ value: predicate_index::ExactValue::utf8("owner-1").unwrap(),
+ }),
+ Box::new(PredicateExpr::I64Range {
+ attribute: token("updated-at"),
+ lower: Some(RangeBound::Inclusive(10)),
+ upper: None,
+ }),
+ ),
+ }],
+ sort_attribute: token("updated-at"),
+ sort_direction: SortDirection::Desc,
+ tie_break_direction: SortDirection::Desc,
+ limit: 20,
+ })
+ .unwrap();
+ let (sql, parameters) = compile_predicate_sql(&query);
+ let details = driver::query(
+ &storage.connection(),
+ &format!("EXPLAIN QUERY PLAN {sql}"),
+ parameters,
+ )
+ .unwrap()
+ .into_iter()
+ .map(|row| required_text(&row, 3).unwrap())
+ .collect::<Vec<_>>();
+ assert!(
+ details
+ .iter()
+ .any(|detail| detail.contains("exact_facts_lookup_idx"))
+ );
+ assert!(
+ details
+ .iter()
+ .any(|detail| detail.contains("integer_facts_lookup_idx"))
+ );
+ assert!(details.iter().all(|detail| !detail.contains("records")));
+}
+
#[test]
fn injected_memory_io_quota_and_sync_failures_require_reset() {
block_on(async {
diff --git a/crates/client/cache-turso/tests/predicate.rs b/crates/client/cache-turso/tests/predicate.rs
new file mode 100644
index 0000000000..f709db5a57
--- /dev/null
+++ b/crates/client/cache-turso/tests/predicate.rs
@@ -0,0 +1,268 @@
+#![cfg(not(target_arch = "wasm32"))]
+
+use cache_core::{
+ engine::{BeginOptimisticWrite, Engine},
+ predicate::{
+ PredicateIndexStorage, PredicateQueryResult, ProjectionIncompleteKind, ProjectionMutation,
+ },
+ store::Storage,
+ value::{EntityKey, Record},
+};
+use cache_turso::TursoStorage;
+use predicate_index::{
+ ExactFact, ExactValue, IndexDocument, IndexQuery, IntegerFact, OptimisticProjectionMutation,
+ PartitionPredicate, PredicateExpr, Profile, RangeBound, RecordKey, SortDirection, Token,
+ ValidatedIndexQuery, evaluate_reference,
+};
+
+fn token(value: &str) -> Token {
+ Token::new(value).unwrap()
+}
+
+fn profile() -> Profile {
+ Profile::new(token("soup-flat-v1"))
+}
+
+fn document(key: &str, owner: &str, updated_at: i64, project: Option<&str>) -> IndexDocument {
+ let mut exact_facts = vec![ExactFact {
+ attribute: token("owner"),
+ value: ExactValue::utf8(owner).unwrap(),
+ }];
+ if let Some(project) = project {
+ exact_facts.push(ExactFact {
+ attribute: token("project-id"),
+ value: ExactValue::utf8(project).unwrap(),
+ });
+ }
+ IndexDocument {
+ record_key: RecordKey::new(key).unwrap(),
+ profile: profile(),
+ partition: token("document"),
+ exact_facts,
+ integer_facts: vec![IntegerFact {
+ attribute: token("updated-at"),
+ value: updated_at,
+ }],
+ sort_facts: vec![IntegerFact {
+ attribute: token("updated-at"),
+ value: updated_at,
+ }],
+ }
+}
+
+fn query() -> ValidatedIndexQuery {
+ ValidatedIndexQuery::new(IndexQuery {
+ profile: profile(),
+ partitions: vec![PartitionPredicate {
+ partition: token("document"),
+ predicate: PredicateExpr::And(
+ Box::new(PredicateExpr::Exact {
+ attribute: token("owner"),
+ value: ExactValue::utf8("owner-1").unwrap(),
+ }),
+ Box::new(PredicateExpr::And(
+ Box::new(PredicateExpr::I64Range {
+ attribute: token("updated-at"),
+ lower: Some(RangeBound::Inclusive(10)),
+ upper: Some(RangeBound::Exclusive(30)),
+ }),
+ Box::new(PredicateExpr::Not(Box::new(PredicateExpr::Exact {
+ attribute: token("project-id"),
+ value: ExactValue::utf8("excluded").unwrap(),
+ }))),
+ )),
+ ),
+ }],
+ sort_attribute: token("updated-at"),
+ sort_direction: SortDirection::Desc,
+ tie_break_direction: SortDirection::Desc,
+ limit: 20,
+ })
+ .unwrap()
+}
+
+#[test]
+fn turso_matches_reference_and_lifecycle_is_exact() {
+ pollster::block_on(async {
+ let mut storage = TursoStorage::open_in_memory("predicate-conformance").unwrap();
+ let documents = vec![
+ document("GraphqlSoupDocument:1", "owner-1", 10, None),
+ document("GraphqlSoupDocument:2", "owner-1", 20, Some("included")),
+ document("GraphqlSoupDocument:3", "owner-1", 25, Some("excluded")),
+ document("GraphqlSoupDocument:4", "owner-2", 20, None),
+ document("GraphqlSoupDocument:5", "owner-1", 30, None),
+ ];
+ let entries = documents
+ .iter()
+ .map(|document| {
+ let (typename, id) = document.record_key.as_str().split_once(':').unwrap();
+ (EntityKey::entity(typename, &[id]), Record::default())
+ })
+ .collect();
+ storage
+ .put_batch_with_projections(
+ entries,
+ documents
+ .iter()
+ .cloned()
+ .map(ProjectionMutation::Replace)
+ .collect(),
+ )
+ .await
+ .unwrap();
+
+ let repeated_key = documents[0].record_key.clone();
+ assert_eq!(
+ storage
+ .get_index_documents(&[repeated_key.clone(), repeated_key])
+ .await
+ .unwrap()
+ .iter()
+ .filter(|document| document.is_some())
+ .count(),
+ 2
+ );
+
+ let query = query();
+ let expected = evaluate_reference(&query, &documents)
+ .into_iter()
+ .map(|hit| hit.record_key)
+ .collect::<Vec<_>>();
+ assert_eq!(
+ storage.query_predicate_index(&query).await.unwrap(),
+ PredicateQueryResult::Complete(expected)
+ );
+
+ storage
+ .put_batch_with_projections(
+ vec![],
+ vec![ProjectionMutation::Replace(document(
+ "GraphqlSoupDocument:2",
+ "owner-2",
+ 20,
+ None,
+ ))],
+ )
+ .await
+ .unwrap();
+ assert_eq!(
+ storage.query_predicate_index(&query).await.unwrap(),
+ PredicateQueryResult::Complete(vec![RecordKey::new("GraphqlSoupDocument:1").unwrap()])
+ );
+
+ storage
+ .put_batch_with_projections(
+ vec![],
+ vec![ProjectionMutation::MarkIncomplete {
+ record_key: RecordKey::new("GraphqlSoupDocument:2").unwrap(),
+ profile: profile(),
+ partition: token("document"),
+ kind: ProjectionIncompleteKind::Dirty,
+ }],
+ )
+ .await
+ .unwrap();
+ assert_eq!(
+ storage.query_predicate_index(&query).await.unwrap(),
+ PredicateQueryResult::Incomplete
+ );
+
+ storage
+ .delete_batch_with_projections(
+ &[EntityKey::entity("GraphqlSoupDocument", &["2"])],
+ &[RecordKey::new("GraphqlSoupDocument:2").unwrap()],
+ )
+ .await
+ .unwrap();
+ assert_eq!(
+ storage.query_predicate_index(&query).await.unwrap(),
+ PredicateQueryResult::Complete(vec![RecordKey::new("GraphqlSoupDocument:1").unwrap()])
+ );
+
+ storage.clear().await.unwrap();
+ assert_eq!(
+ storage.query_predicate_index(&query).await.unwrap(),
+ PredicateQueryResult::Complete(vec![])
+ );
+ });
+}
+
+#[test]
+fn turso_rehydrates_and_queries_durable_optimistic_projection_layers() {
+ pollster::block_on(async {
+ let storage = TursoStorage::open_in_memory("predicate-optimistic").unwrap();
+ let mut engine = Engine::new(storage);
+ let base = document("GraphqlSoupDocument:1", "owner-1", 10, None);
+ engine
+ .put_records_with_projections(
+ None,
+ vec![(
+ EntityKey::entity("GraphqlSoupDocument", &["1"]),
+ Record::default(),
+ )],
+ vec![ProjectionMutation::Replace(base)],
+ )
+ .await
+ .unwrap();
+ let data = serde_json::json!({
+ "setEntityProperty": {
+ "id": "prop-1",
+ "displayName": "Status",
+ "value": {
+ "__typename": "GraphqlStringPropertyValue",
+ "stringValue": "doing"
+ }
+ }
+ });
+ let serde_json::Value::Object(variables) = serde_json::json!({
+ "input": {
+ "entityType": "DOCUMENT",
+ "entityId": "doc-1",
+ "propertyDefinitionId": "def-1",
+ "value": { "string": "doing" }
+ }
+ }) else {
+ unreachable!()
+ };
+ engine
+ .begin_optimistic_write_with_projections(
+ None,
+ BeginOptimisticWrite {
+ query: r#"
+ mutation SetEntityProperty($input: SetEntityPropertyInput!) {
+ setEntityProperty(input: $input) {
+ id
+ displayName
+ value {
+ __typename
+ ... on GraphqlStringPropertyValue { stringValue: value }
+ }
+ }
+ }
+ "#,
+ operation_name: Some("SetEntityProperty"),
+ variables: &variables,
+ data: &data,
+ link_patches: &[],
+ revalidations: &[],
+ created_at_ms: 1,
+ },
+ vec![OptimisticProjectionMutation::Replace(document(
+ "GraphqlSoupDocument:1",
+ "owner-1",
+ 20,
+ None,
+ ))],
+ )
+ .await
+ .unwrap();
+
+ let mut reopened = Engine::new(engine.into_storage());
+ assert_eq!(
+ reopened.query_predicate_index(&query()).await.unwrap(),
+ PredicateQueryResult::Optimistic(vec![
+ RecordKey::new("GraphqlSoupDocument:1").unwrap()
+ ])
+ );
+ });
+}
diff --git a/crates/client/cache-wasm/Cargo.toml b/crates/client/cache-wasm/Cargo.toml
index b6e91f45a7..8954f9c174 100644
--- a/crates/client/cache-wasm/Cargo.toml
+++ b/crates/client/cache-wasm/Cargo.toml
@@ -2,7 +2,7 @@
edition = "2024"
name = "cache-wasm"
publish = false
-version = "0.4.2"
+version = "0.6.3"
[features]
default = []
@@ -30,6 +30,8 @@ cache-core = { path = "../cache-core" }
[target.'cfg(target_arch = "wasm32")'.dependencies]
async-lock = { workspace = true }
cache-turso = { path = "../cache-turso" }
+predicate-index = { path = "../../predicate_index" }
+soup-filter-cache-adapter = { path = "../../soup_filter_cache_adapter" }
js-sys = { workspace = true }
serde = { workspace = true }
serde-wasm-bindgen = { workspace = true }
diff --git a/crates/client/cache-wasm/src/lib.rs b/crates/client/cache-wasm/src/lib.rs
index f753347600..d3b9f98587 100644
--- a/crates/client/cache-wasm/src/lib.rs
+++ b/crates/client/cache-wasm/src/lib.rs
@@ -1,4 +1,9 @@
-//! wasm-bindgen shell around the cache engine + Turso OPFS storage.
+//! wasm-bindgen shell around the generic cache engine + Turso OPFS storage.
+//!
+//! Soup-specific GraphQL materialization and projection policy live in
+//! `soup-filter-cache-adapter`. This shell links that adapter at the browser
+//! composition edge and passes only generic predicate/projection IR into the
+//! cache engine.
//!
//! Exposes a `CacheEngine` class to the JS worker glue
//! (`apps/web/src/lib/graphql-cache/`). All methods return Promises; the
diff --git a/crates/client/cache-wasm/src/shell.rs b/crates/client/cache-wasm/src/shell.rs
index 8a9e631aef..0bc7990978 100644
--- a/crates/client/cache-wasm/src/shell.rs
+++ b/crates/client/cache-wasm/src/shell.rs
@@ -7,6 +7,7 @@ use cache_core::engine::{
};
use cache_core::entity_resolver::EntityResolver;
use cache_core::link_patch::{OptimisticLinkPatch, QueryRevalidation};
+use cache_core::predicate::PredicateQueryResult;
use cache_core::query_inspection::QueryInspection;
use cache_core::queue::{ClaimedMutation, MutationClaimRequest, MutationClaimToken};
use cache_core::record_selection::RecordSelection;
@@ -17,7 +18,12 @@ use cache_turso::{
PhysicalResetReason, TursoStorage, TursoStorageCloseOutcome, TursoStorageError,
TursoStorageOpenOutcome,
};
+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,
+};
use std::cell::RefCell;
use std::collections::HashMap;
use std::rc::Rc;
@@ -250,6 +256,23 @@ fn unwrap_storage(storage: BrowserStorage) -> TursoStorage {
storage.into_inner()
}
+#[derive(Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+struct JsEntityFilterRequest {
+ filters: serde_json::Value,
+ sort_method: String,
+ sort_direction: String,
+ limit: u16,
+}
+
+#[derive(Serialize)]
+#[serde(tag = "kind", rename_all = "kebab-case")]
+enum JsEntityFilterResult {
+ Complete { keys: Vec<String>, optimistic: bool },
+ Unsupported,
+ Incomplete,
+}
+
struct CacheState {
engine: Option<BrowserEngine>,
scope: String,
@@ -805,6 +828,49 @@ impl CacheEngine {
})
}
+ /// Evaluates one exact `soup-flat-v1` GraphQL filter request.
+ #[wasm_bindgen(js_name = entityFilter)]
+ pub fn entity_filter(&self, request: JsValue) -> js_sys::Promise {
+ let state = self.state.clone();
+ future_to_promise(async move {
+ let mut state = state.lock().await;
+ state.ensure_callable()?;
+ let request: JsEntityFilterRequest =
+ serde_wasm_bindgen::from_value(request).map_err(err_js)?;
+ let outcome = compile_filter_request(
+ request.filters,
+ &request.sort_method,
+ &request.sort_direction,
+ request.limit,
+ )
+ .map_err(err_js)?;
+ let result = match outcome {
+ SoupFilterCompileOutcome::Unsupported => JsEntityFilterResult::Unsupported,
+ SoupFilterCompileOutcome::Supported(query) => {
+ let result = state.engine_mut()?.query_predicate_index(&query).await;
+ match state.engine_result(result)? {
+ PredicateQueryResult::Complete(keys) => JsEntityFilterResult::Complete {
+ keys: keys
+ .into_iter()
+ .map(|key| key.as_str().to_owned())
+ .collect(),
+ optimistic: false,
+ },
+ PredicateQueryResult::Optimistic(keys) => JsEntityFilterResult::Complete {
+ keys: keys
+ .into_iter()
+ .map(|key| key.as_str().to_owned())
+ .collect(),
+ optimistic: true,
+ },
+ PredicateQueryResult::Incomplete => JsEntityFilterResult::Incomplete,
+ }
+ }
+ };
+ to_js(&result)
+ })
+ }
+
/// Normalizes and stores a network response. Resolves to
/// `{changed: string[], affectedOps: string[], reset: boolean}` —
/// `affectedOps` are the registered operation ids (excluding
@@ -837,9 +903,10 @@ impl CacheEngine {
let op_id = ops.borrow_mut().intern(&registration.op_id);
(op_id, registration.entity_resolvers)
});
+ let projections = authoritative_projection_mutations(&data);
let result = state
.engine_mut()?
- .write_query_with_registration(
+ .write_query_with_registration_and_projections(
origin,
registration
.as_ref()
@@ -854,6 +921,7 @@ impl CacheEngine {
data: &data,
identity: identity.as_deref(),
},
+ projections,
)
.await;
let result = state.engine_result(result)?;
@@ -888,14 +956,16 @@ 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 = authoritative_projection_mutations(&data);
let result = state
.engine_mut()?
- .hydrate_query(
+ .hydrate_query_with_projections(
&query,
operation_name.as_deref(),
&variables,
&data,
identity.as_deref(),
+ projections,
)
.await;
let result = state.engine_result(result)?;
@@ -943,6 +1013,7 @@ 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 claim = MutationClaimRequest {
owner: lease_owner,
now_ms: parse_timestamp(now_ms, "claim timestamp")?,
@@ -954,7 +1025,7 @@ impl CacheEngine {
let origin = origin_op_id.map(|name| ops.borrow_mut().intern(&name));
let result = state
.engine_mut()?
- .enqueue_optimistic_mutation(
+ .enqueue_optimistic_mutation_with_projections(
origin,
BeginOptimisticWrite {
query: &query,
@@ -966,6 +1037,7 @@ impl CacheEngine {
created_at_ms,
},
claim,
+ projection_mutations,
)
.await;
let result = state.engine_result(result)?;
@@ -1121,15 +1193,17 @@ impl CacheEngine {
};
let vars = parse_variables(variables)?;
let data: serde_json::Value = serde_wasm_bindgen::from_value(data).map_err(err_js)?;
+ let projections = authoritative_projection_mutations(&data);
let result = state
.engine_mut()?
- .commit_optimistic_write(
+ .commit_optimistic_write_with_projections(
transaction,
claim,
&query,
operation_name.as_deref(),
&vars,
&data,
+ projections,
)
.await;
let result = state.engine_result(result)?;
@@ -1193,6 +1267,14 @@ impl CacheEngine {
future_to_promise(async move {
let mut state = state.lock().await;
state.ensure_callable()?;
+ let projections = dirty_projection_mutations(&keys);
+ if !projections.is_empty() {
+ let result = state
+ .engine_mut()?
+ .mark_projections_incomplete(projections)
+ .await;
+ state.engine_result(result)?;
+ }
let keys: Vec<EntityKey<'static>> =
keys.into_iter().map(|key| EntityKey(key.into())).collect();
let affected = state.engine_mut()?.invalidate_keys(keys.iter());
@@ -1209,9 +1291,16 @@ 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 keys: Vec<EntityKey<'static>> =
keys.into_iter().map(|key| EntityKey(key.into())).collect();
- let result = state.engine_mut()?.delete_keys(&keys).await;
+ let result = state
+ .engine_mut()?
+ .delete_keys_with_projections(&keys, &projection_keys)
+ .await;
let affected = state.engine_result(result)?;
to_js(&ops.borrow().names(affected))
})
diff --git a/crates/client/cache-wasm/src/shell/test.rs b/crates/client/cache-wasm/src/shell/test.rs
index d137e1ad2b..fef6a162b6 100644
--- a/crates/client/cache-wasm/src/shell/test.rs
+++ b/crates/client/cache-wasm/src/shell/test.rs
@@ -40,6 +40,13 @@ fn js(json: serde_json::Value) -> JsValue {
.expect("serialize test value")
}
+fn write_context(origin_op_id: Option<&str>) -> JsValue {
+ js(serde_json::json!({
+ "originOpId": origin_op_id,
+ "registration": null
+ }))
+}
+
fn from_js<T: DeserializeOwned>(value: JsValue) -> T {
serde_wasm_bindgen::from_value(value).expect("deserialize wasm result")
}
@@ -153,7 +160,7 @@ async fn operations_preserve_js_boundary_interner_and_ordering() {
let write: serde_json::Value = from_js(
resolved(engine.write_query(
- Some("tab:writer".into()),
+ write_context(Some("tab:writer")),
QUERY.into(),
Some("Soup".into()),
js(vars.clone()),
@@ -251,7 +258,7 @@ async fn entity_resolvers_cross_the_js_boundary() {
const SCOPE: &str = "cache-wasm-wp07-entity-resolver";
let engine = fresh_engine(SCOPE).await;
resolved(engine.write_query(
- None,
+ write_context(None),
QUERY.into(),
Some("Soup".into()),
js(variables()),
@@ -301,7 +308,7 @@ async fn queue_and_optimistic_layers_survive_preserve_reopen_in_id_order() {
let engine = fresh_engine(SCOPE).await;
let vars = variables();
resolved(engine.write_query(
- None,
+ write_context(None),
PROPERTY_QUERY.into(),
Some("Soup".into()),
js(vars.clone()),
@@ -415,7 +422,7 @@ async fn optimistic_commit_reports_affected_ops_and_rejects_settled_or_malformed
let engine = fresh_engine(SCOPE).await;
let vars = variables();
resolved(engine.write_query(
- None,
+ write_context(None),
PROPERTY_QUERY.into(),
Some("Soup".into()),
js(vars.clone()),
@@ -522,7 +529,7 @@ async fn destroy_recovery_wipes_records_and_queue() {
const SCOPE: &str = "cache-wasm-wp07-destroy";
let engine = fresh_engine(SCOPE).await;
resolved(engine.write_query(
- None,
+ write_context(None),
PROPERTY_QUERY.into(),
Some("Soup".into()),
js(variables()),
@@ -577,7 +584,7 @@ async fn recovery_open_wipes_existing_data_before_opening_fresh_turso() {
const SCOPE: &str = "cache-wasm-wp08-recovery-open";
let engine = fresh_engine(SCOPE).await;
resolved(engine.write_query(
- None,
+ write_context(None),
QUERY.into(),
Some("Soup".into()),
js(variables()),
@@ -654,7 +661,7 @@ async fn incompatible_initialization_resets_and_identity_reset_does_not_latch()
let first_identity: serde_json::Value = from_js(
resolved(engine.write_query(
- None,
+ write_context(None),
QUERY.into(),
Some("Soup".into()),
js(variables()),
@@ -666,7 +673,7 @@ async fn incompatible_initialization_resets_and_identity_reset_does_not_latch()
assert_eq!(first_identity["reset"], false);
let normal_identity_reset: serde_json::Value = from_js(
resolved(engine.write_query(
- None,
+ write_context(None),
QUERY.into(),
Some("Soup".into()),
js(variables()),
@@ -687,7 +694,7 @@ async fn storage_reset_errors_latch_and_block_hot_read_write_and_control_methods
const SCOPE: &str = "cache-wasm-wp07-reset-latch";
let engine = fresh_engine(SCOPE).await;
resolved(engine.write_query(
- None,
+ write_context(None),
QUERY.into(),
Some("Soup".into()),
js(variables()),
@@ -719,7 +726,7 @@ async fn storage_reset_errors_latch_and_block_hot_read_write_and_control_methods
))
.await;
assert_reset_required(engine.write_query(
- None,
+ write_context(None),
QUERY.into(),
Some("Soup".into()),
js(variables()),
@@ -734,7 +741,7 @@ async fn storage_reset_errors_latch_and_block_hot_read_write_and_control_methods
assert_eq!(identity, None);
resolved(engine.write_query(
- None,
+ write_context(None),
PROPERTY_QUERY.into(),
Some("Soup".into()),
js(variables()),
@@ -772,7 +779,7 @@ async fn physical_reset_serializes_recreates_and_preserves_interner_registration
const SCOPE: &str = "cache-wasm-wp07-physical-reset";
let engine = fresh_engine(SCOPE).await;
resolved(engine.write_query(
- None,
+ write_context(None),
PROPERTY_QUERY.into(),
Some("Soup".into()),
js(variables()),
@@ -814,7 +821,7 @@ async fn physical_reset_serializes_recreates_and_preserves_interner_registration
let concurrent = js_sys::Array::new();
concurrent.push(&engine.physical_reset());
concurrent.push(&engine.write_query(
- None,
+ write_context(None),
PROPERTY_QUERY.into(),
Some("Soup".into()),
js(variables()),
@@ -845,7 +852,7 @@ async fn physical_reset_serializes_recreates_and_preserves_interner_registration
assert_eq!(read["kind"], "hit");
let write: serde_json::Value = from_js(
resolved(engine.write_query(
- Some("tab:writer".into()),
+ write_context(Some("tab:writer")),
PROPERTY_QUERY.into(),
Some("Soup".into()),
js(variables()),
@@ -904,7 +911,7 @@ async fn every_method_rejects_after_consuming_close() {
))
.await;
assert_closed(engine.write_query(
- None,
+ write_context(None),
QUERY.into(),
Some("Soup".into()),
js(variables()),
@@ -985,7 +992,7 @@ async fn calls_serialize_and_owner_lock_excludes_a_second_open() {
let writes = js_sys::Array::new();
writes.push(&engine.write_query(
- None,
+ write_context(None),
QUERY.into(),
Some("Soup".into()),
js(variables()),
@@ -993,7 +1000,7 @@ async fn calls_serialize_and_owner_lock_excludes_a_second_open() {
None,
));
writes.push(&engine.write_query(
- None,
+ write_context(None),
QUERY.into(),
Some("Soup".into()),
js(variables()),
diff --git a/crates/client/cache-wasm/src/shell/test_storage.rs b/crates/client/cache-wasm/src/shell/test_storage.rs
index e587b3cb83..c193c1948a 100644
--- a/crates/client/cache-wasm/src/shell/test_storage.rs
+++ b/crates/client/cache-wasm/src/shell/test_storage.rs
@@ -1,3 +1,4 @@
+use cache_core::predicate::{PredicateIndexStorage, PredicateQueryResult, ProjectionMutation};
use cache_core::queue::{
ClaimedMutation, MutationClaimRequest, MutationClaimToken, MutationId, NewQueuedMutation,
QueuedMutation,
@@ -6,6 +7,7 @@ use cache_core::search::{SearchCursor, SearchDocument, SearchProfile};
use cache_core::store::{QueueDiagnostics, Storage};
use cache_core::value::{EntityKey, Record};
use cache_turso::{PhysicalResetReason, TursoStorage, TursoStorageError};
+use predicate_index::{IndexDocument, RecordKey, ValidatedIndexQuery};
use std::sync::atomic::{AtomicU8, Ordering};
#[derive(Clone, Copy)]
@@ -65,6 +67,16 @@ impl Storage for BrowserStorage {
self.inner.put_batch(entries).await
}
+ async fn put_batch_with_projections(
+ &mut self,
+ entries: Vec<(EntityKey<'static>, Record)>,
+ projections: Vec<ProjectionMutation>,
+ ) -> Result<(), Self::Error> {
+ self.inner
+ .put_batch_with_projections(entries, projections)
+ .await
+ }
+
async fn delete_batch(&mut self, keys: &[EntityKey<'static>]) -> Result<(), Self::Error> {
self.inner.delete_batch(keys).await
}
@@ -132,6 +144,18 @@ impl Storage for BrowserStorage {
self.inner.complete_mutation(id, claim, entries).await
}
+ async fn complete_mutation_with_projections(
+ &mut self,
+ id: MutationId,
+ claim: MutationClaimToken,
+ entries: Vec<(EntityKey<'static>, Record)>,
+ projections: Vec<ProjectionMutation>,
+ ) -> Result<bool, Self::Error> {
+ self.inner
+ .complete_mutation_with_projections(id, claim, entries, projections)
+ .await
+ }
+
async fn discard_mutation(
&mut self,
id: MutationId,
@@ -144,3 +168,29 @@ impl Storage for BrowserStorage {
self.inner.clear().await
}
}
+
+impl PredicateIndexStorage for BrowserStorage {
+ async fn delete_batch_with_projections(
+ &mut self,
+ keys: &[EntityKey<'static>],
+ projection_keys: &[RecordKey],
+ ) -> Result<(), Self::Error> {
+ self.inner
+ .delete_batch_with_projections(keys, projection_keys)
+ .await
+ }
+
+ async fn query_predicate_index(
+ &self,
+ query: &ValidatedIndexQuery,
+ ) -> Result<PredicateQueryResult, Self::Error> {
+ self.inner.query_predicate_index(query).await
+ }
+
+ async fn get_index_documents(
+ &self,
+ keys: &[RecordKey],
+ ) -> Result<Vec<Option<IndexDocument>>, Self::Error> {
+ self.inner.get_index_documents(keys).await
+ }
+}
diff --git a/crates/document_sub_type/Cargo.toml b/crates/document_sub_type/Cargo.toml
index f8ad8a0431..9b5227ac66 100644
--- a/crates/document_sub_type/Cargo.toml
+++ b/crates/document_sub_type/Cargo.toml
@@ -4,11 +4,15 @@ name = "document_sub_type"
publish = false
version = "0.1.0"
+[features]
+default = ["schema", "sqlx"]
+schema = ["dep:schemars", "dep:utoipa"]
+sqlx = ["dep:sqlx"]
+
[dependencies]
serde = { workspace = true }
-sqlx = { workspace = true }
+sqlx = { workspace = true, optional = true }
strum = { workspace = true }
thiserror = { workspace = true }
-utoipa = { workspace = true }
-schemars = {workspace = true}
-workspace-hack = { version = "0.1", path = "../workspace-hack" }
+utoipa = { workspace = true, optional = true }
+schemars = { workspace = true, optional = true }
diff --git a/crates/document_sub_type/src/lib.rs b/crates/document_sub_type/src/lib.rs
index 55c1971663..5214cd1214 100644
--- a/crates/document_sub_type/src/lib.rs
+++ b/crates/document_sub_type/src/lib.rs
@@ -1,5 +1,4 @@
//! This crate contains the document sub type enum and various logic for it
-use schemars::JsonSchema;
/// The document sub type enum represents all values of document sub types.
/// These values should match the `document_sub_type_value` table in macrodb.
@@ -9,17 +8,19 @@ use schemars::JsonSchema;
Eq,
PartialEq,
Debug,
- utoipa::ToSchema,
Clone,
Copy,
- sqlx::Type,
strum::EnumString,
strum::Display,
- JsonSchema,
)]
+#[cfg_attr(feature = "schema", derive(utoipa::ToSchema, schemars::JsonSchema))]
+#[cfg_attr(feature = "sqlx", derive(sqlx::Type))]
#[serde(rename_all = "lowercase")]
#[strum(serialize_all = "snake_case")]
-#[sqlx(type_name = "\"document_sub_type_value\"", rename_all = "lowercase")]
+#[cfg_attr(
+ feature = "sqlx",
+ sqlx(type_name = "\"document_sub_type_value\"", rename_all = "lowercase")
+)]
pub enum DocumentSubType {
/// A task document
Task,
diff --git a/crates/filter_ast/Cargo.toml b/crates/filter_ast/Cargo.toml
index 6c74e5cb8d..f31d5a65d6 100644
--- a/crates/filter_ast/Cargo.toml
+++ b/crates/filter_ast/Cargo.toml
@@ -7,4 +7,3 @@ version = "0.1.0"
[dependencies]
recursion = { workspace = true }
serde = { workspace = true }
-workspace-hack = { version = "0.1", path = "../workspace-hack" }
diff --git a/crates/graphql_common/Cargo.toml b/crates/graphql_common/Cargo.toml
index e00e58ef5f..f530752a9f 100644
--- a/crates/graphql_common/Cargo.toml
+++ b/crates/graphql_common/Cargo.toml
@@ -17,6 +17,7 @@ macro_user_id = { path = "../macro_user_id" }
model-entity = { path = "../model-entity" }
models_properties = { path = "../models_properties" }
rootcause = { workspace = true }
+serde = { workspace = true }
tokio = { workspace = true }
tracing = { workspace = true }
uuid = { workspace = true }
diff --git a/crates/graphql_common/src/property_filter.rs b/crates/graphql_common/src/property_filter.rs
index 44820fe09b..c8ead291b5 100644
--- a/crates/graphql_common/src/property_filter.rs
+++ b/crates/graphql_common/src/property_filter.rs
@@ -9,6 +9,7 @@ use filter_ast::Expr;
use item_filters::ast::properties::{
EntityRefId, PropertiesLiteral, PropertyEntityType, PropertyMatchValue,
};
+use serde::{Deserialize, Serialize};
use crate::{IntoFilterExpr, filter_expr_input, parse_id};
@@ -69,7 +70,8 @@ impl GraphqlPropertyMatchValue {
}
/// An entity type supported by the properties domain.
-#[derive(Enum, Copy, Clone, Eq, PartialEq)]
+#[derive(Enum, Debug, Copy, Clone, Eq, PartialEq, Serialize, Deserialize)]
+#[serde(rename_all = "SCREAMING_SNAKE_CASE")]
pub enum GraphqlPropertyEntityType {
/// Calendar event entity.
CalendarEvent,
diff --git a/crates/graphql_soup/Cargo.toml b/crates/graphql_soup/Cargo.toml
index 6abfe2a422..2713972c54 100644
--- a/crates/graphql_soup/Cargo.toml
+++ b/crates/graphql_soup/Cargo.toml
@@ -22,6 +22,7 @@ entity_access = { path = "../entity_access", default-features = false, features
] }
filter_ast = { path = "../filter_ast" }
graphql_common = { path = "../graphql_common" }
+graphql_soup_filter_input = { path = "../graphql_soup_filter_input", features = ["server"] }
graphql_email = { path = "../graphql_email" }
graphql_permission = { path = "../graphql_permission" }
item_filters = { path = "../item_filters" }
diff --git a/crates/graphql_soup/src/inputs.rs b/crates/graphql_soup/src/inputs.rs
index 38598740fe..264d76a770 100644
--- a/crates/graphql_soup/src/inputs.rs
+++ b/crates/graphql_soup/src/inputs.rs
@@ -1,33 +1,8 @@
-use std::str::FromStr;
-
use async_graphql::{Enum, ID};
-use chrono::{DateTime, Utc};
-use document_sub_type::DocumentSubType;
-use filter_ast::Expr;
-use graphql_common::{
- GraphqlPropertiesExpr, GraphqlPropertyEntityType, IntoFilterExpr, filter_expr_input,
- optional_tree, parse_id, parse_macro_user_id,
-};
-use item_filters::{
- CallStatus, SharedEmailFilter,
- ast::{
- CrmScope, EmailFilterAst, EntityFilterAst,
- calendar_event::CalendarEventLiteral,
- call::CallLiteral,
- channel::{ChannelLiteral, ChannelThreadLiteral, ChannelTypeFilter},
- chat::{ChatLiteral, ChatRole},
- crm_company::CrmCompanyLiteral,
- date::DateLiteral,
- document::DocumentLiteral,
- email::{Email, EmailLiteral},
- foreign_entity::ForeignEntityLiteral,
- project::ProjectLiteral,
- properties::PropertyEntityType,
- reminder::ReminderLiteral,
- },
-};
-use macro_user_id::{cowlike::CowLike, email::EmailStr, user_id::MacroUserIdStr};
-use model_file_type::FileType;
+use graphql_common::{GraphqlPropertyEntityType, parse_id};
+use graphql_soup_filter_input::GraphqlEntityFilterAst;
+use item_filters::ast::{EntityFilterAst, properties::PropertyEntityType};
+use macro_user_id::user_id::MacroUserIdStr;
use models_grouping::{GroupByField, GroupingConfig};
use models_pagination::{Base64Str, CursorWithValAndFilter, Query, SimpleSortMethod};
use soup::domain::models::{
@@ -402,820 +377,8 @@ impl GraphqlEmailView {
}
}
-/// GraphQL input mirroring `item_filters::ast::EntityFilterAst`.
-#[derive(async_graphql::InputObject)]
-struct GraphqlEntityFilterAst {
- /// The calendar event filter to apply.
- calendar_event_filter: Option<GraphqlCalendarEventExpr>,
- /// The document filter to apply.
- document_filter: Option<GraphqlDocumentExpr>,
- /// The project filter to apply.
- project_filter: Option<GraphqlProjectExpr>,
- /// The chat filter to apply.
- chat_filter: Option<GraphqlChatExpr>,
- /// The email filter to apply.
- email_filter: Option<GraphqlEmailFilterAst>,
- /// The channel filter to apply.
- channel_filter: Option<GraphqlChannelExpr>,
- /// The channel thread filter to apply.
- channel_thread_filter: Option<GraphqlChannelThreadExpr>,
- /// The call filter to apply.
- call_filter: Option<GraphqlCallExpr>,
- /// The crm company filter to apply.
- crm_company_filter: Option<GraphqlCrmCompanyExpr>,
- /// The foreign entity filter to apply.
- foreign_entity_filter: Option<GraphqlForeignEntityExpr>,
- /// The reminder filter to apply.
- reminder_filter: Option<GraphqlReminderExpr>,
- /// The properties filter to apply.
- properties_filter: Option<GraphqlPropertiesExpr>,
-}
-
-impl GraphqlEntityFilterAst {
- /// Convert this value into the ast representation.
- fn into_ast(self) -> async_graphql::Result<EntityFilterAst> {
- Ok(EntityFilterAst {
- calendar_event_filter: optional_tree(self.calendar_event_filter)?,
- document_filter: optional_tree(self.document_filter)?,
- project_filter: optional_tree(self.project_filter)?,
- chat_filter: optional_tree(self.chat_filter)?,
- email_filter: self
- .email_filter
- .map(GraphqlEmailFilterAst::into_ast)
- .transpose()?
- .unwrap_or_default(),
- channel_filter: optional_tree(self.channel_filter)?,
- channel_thread_filter: optional_tree(self.channel_thread_filter)?,
- call_filter: optional_tree(self.call_filter)?,
- crm_company_filter: optional_tree(self.crm_company_filter)?,
- foreign_entity_filter: optional_tree(self.foreign_entity_filter)?,
- reminder_filter: optional_tree(self.reminder_filter)?,
- properties_filter: optional_tree(self.properties_filter)?,
- })
- }
-}
-
-filter_expr_input!(
- GraphqlCalendarEventExpr,
- GraphqlCalendarEventBinaryExpr,
- GraphqlCalendarEventLiteral,
- CalendarEventLiteral,
- "CalendarEventFilterExpr"
-);
-filter_expr_input!(
- GraphqlDocumentExpr,
- GraphqlDocumentBinaryExpr,
- GraphqlDocumentLiteral,
- DocumentLiteral,
- "DocumentFilterExpr"
-);
-
-/// GraphQL input representing a calendar event literal.
-#[derive(async_graphql::OneofObject)]
-enum GraphqlCalendarEventLiteral {
- /// Canonical event id.
- Id(ID),
- /// Event status.
- Status(String),
- /// Master start must be before this RFC3339 instant.
- StartsBefore(String),
- /// Master end must be after this RFC3339 instant.
- EndsAfter(String),
- /// Attendee email.
- Attendee(String),
- /// Organizer email.
- Organizer(String),
- /// Notification done state for the requester.
- NotificationDone(bool),
- /// Notification seen state for the requester.
- NotificationSeen(bool),
-}
-
-impl IntoFilterExpr<CalendarEventLiteral> for GraphqlCalendarEventLiteral {
- fn into_expr(self) -> async_graphql::Result<Expr<CalendarEventLiteral>> {
- let parse_date = |value: String| {
- DateTime::parse_from_rfc3339(&value)
- .map(|date| date.with_timezone(&Utc))
- .map_err(|error| {
- async_graphql::Error::new(format!(
- "invalid RFC3339 calendar date `{value}`: {error}"
- ))
- })
- };
- Ok(Expr::val(match self {
- Self::Id(id) => CalendarEventLiteral::Id(parse_id(id, "id")?),
- Self::Status(status) => CalendarEventLiteral::Status(status.to_ascii_lowercase()),
- Self::StartsBefore(value) => CalendarEventLiteral::StartsBefore(parse_date(value)?),
- Self::EndsAfter(value) => CalendarEventLiteral::EndsAfter(parse_date(value)?),
- Self::Attendee(email) => CalendarEventLiteral::Attendee(email.to_ascii_lowercase()),
- Self::Organizer(email) => CalendarEventLiteral::Organizer(email.to_ascii_lowercase()),
- Self::NotificationDone(done) => CalendarEventLiteral::NotificationDone(done),
- Self::NotificationSeen(seen) => CalendarEventLiteral::NotificationSeen(seen),
- }))
- }
-}
-filter_expr_input!(
- GraphqlProjectExpr,
- GraphqlProjectBinaryExpr,
- GraphqlProjectLiteral,
- ProjectLiteral,
- "ProjectFilterExpr"
-);
-filter_expr_input!(
- GraphqlChatExpr,
- GraphqlChatBinaryExpr,
- GraphqlChatLiteral,
- ChatLiteral,
- "ChatFilterExpr"
-);
-filter_expr_input!(
- GraphqlEmailExpr,
- GraphqlEmailBinaryExpr,
- GraphqlEmailLiteral,
- EmailLiteral,
- "EmailFilterExpr"
-);
-filter_expr_input!(
- GraphqlChannelExpr,
- GraphqlChannelBinaryExpr,
- GraphqlChannelLiteral,
- ChannelLiteral,
- "ChannelFilterExpr"
-);
-filter_expr_input!(
- GraphqlChannelThreadExpr,
- GraphqlChannelThreadBinaryExpr,
- GraphqlChannelThreadLiteral,
- ChannelThreadLiteral,
- "ChannelThreadFilterExpr"
-);
-filter_expr_input!(
- GraphqlCallExpr,
- GraphqlCallBinaryExpr,
- GraphqlCallLiteral,
- CallLiteral,
- "CallFilterExpr"
-);
-filter_expr_input!(
- GraphqlCrmCompanyExpr,
- GraphqlCrmCompanyBinaryExpr,
- GraphqlCrmCompanyLiteral,
- CrmCompanyLiteral,
- "CrmCompanyFilterExpr"
-);
-filter_expr_input!(
- GraphqlForeignEntityExpr,
- GraphqlForeignEntityBinaryExpr,
- GraphqlForeignEntityLiteral,
- ForeignEntityLiteral,
- "ForeignEntityFilterExpr"
-);
-filter_expr_input!(
- GraphqlReminderExpr,
- GraphqlReminderBinaryExpr,
- GraphqlReminderLiteral,
- ReminderLiteral,
- "ReminderFilterExpr"
-);
-/// GraphQL input representing the email filter ast.
-#[derive(async_graphql::InputObject)]
-struct GraphqlEmailFilterAst {
- /// The tree.
- tree: Option<GraphqlEmailExpr>,
- /// The crm scope.
- crm_scope: Option<GraphqlCrmScope>,
-}
-
-impl GraphqlEmailFilterAst {
- /// Convert this value into the ast representation.
- fn into_ast(self) -> async_graphql::Result<EmailFilterAst> {
- Ok(EmailFilterAst {
- tree: optional_tree(self.tree)?,
- crm_scope: self.crm_scope.map(GraphqlCrmScope::into_ast).transpose()?,
- })
- }
-}
-
-/// GraphQL input representing the crm scope.
-#[derive(async_graphql::OneofObject)]
-enum GraphqlCrmScope {
- /// The domains option.
- Domains(Vec<String>),
- /// The addresses option.
- Addresses(Vec<String>),
-}
-
-impl GraphqlCrmScope {
- /// Convert this value into the ast representation.
- fn into_ast(self) -> async_graphql::Result<CrmScope> {
- match self {
- Self::Domains(domains) if domains.is_empty() => Err(async_graphql::Error::new(
- "CrmScope.domains cannot be empty",
- )),
- Self::Domains(domains) => Ok(CrmScope::Domains(domains)),
- Self::Addresses(addresses) if addresses.is_empty() => Err(async_graphql::Error::new(
- "CrmScope.addresses cannot be empty",
- )),
- Self::Addresses(addresses) => Ok(CrmScope::Addresses(addresses)),
- }
- }
-}
-
-/// GraphQL input representing the date literal.
-#[derive(async_graphql::OneofObject)]
-enum GraphqlDateLiteral {
- /// The gt option.
- Gt(String),
- /// The lt option.
- Lt(String),
- /// The gte option.
- Gte(String),
- /// The lte option.
- Lte(String),
-}
-
-impl GraphqlDateLiteral {
- /// Parse an email address from a GraphQL string value.
- fn parse(value: String) -> async_graphql::Result<DateTime<Utc>> {
- DateTime::parse_from_rfc3339(&value)
- .map(|dt| dt.with_timezone(&Utc))
- .map_err(|err| {
- async_graphql::Error::new(format!("invalid RFC3339 date `{value}`: {err}"))
- })
- }
-
- /// Convert this value into the ast representation.
- fn into_ast(self) -> async_graphql::Result<DateLiteral> {
- Ok(match self {
- Self::Gt(value) => DateLiteral::GreaterThan(Self::parse(value)?),
- Self::Lt(value) => DateLiteral::LessThan(Self::parse(value)?),
- Self::Gte(value) => DateLiteral::GreaterThanOrEqual(Self::parse(value)?),
- Self::Lte(value) => DateLiteral::LessThanOrEqual(Self::parse(value)?),
- })
- }
-}
-
-/// GraphQL input representing the document literal.
-#[derive(async_graphql::OneofObject)]
-enum GraphqlDocumentLiteral {
- /// The file type option.
- FileType(String),
- /// The id option.
- Id(ID),
- /// The project id option.
- ProjectId(ID),
- /// The owner option.
- Owner(String),
- /// The importance option.
- Importance(bool),
- /// The notification done option.
- NotificationDone(bool),
- /// The notification seen option.
- NotificationSeen(bool),
- /// The include cbm atm nc option.
- IncludeCbmAtmNc(bool),
- /// The sub type option.
- SubType(GraphqlDocumentSubType),
- /// The file assoc option.
- FileAssoc(String),
- /// The is email attachment option.
- IsEmailAttachment(bool),
- /// The created at option.
- CreatedAt(GraphqlDateLiteral),
- /// The updated at option.
- UpdatedAt(GraphqlDateLiteral),
-}
-
-impl IntoFilterExpr<DocumentLiteral> for GraphqlDocumentLiteral {
- /// Convert this value into the expr representation.
- fn into_expr(self) -> async_graphql::Result<Expr<DocumentLiteral>> {
- let literal = match self {
- Self::FileAssoc(value) => {
- let (_, file_types) = item_filters::ast::document::parse_to_file_types(&value)
- .map_err(|err| async_graphql::Error::new(err.to_string()))?;
- return file_types
- .map(|file_type| Expr::val(DocumentLiteral::FileType(file_type)))
- .reduce(Expr::or)
- .ok_or_else(|| {
- async_graphql::Error::new("fileAssoc expansion cannot be empty")
- });
- }
- Self::FileType(value) => {
- DocumentLiteral::FileType(FileType::from_str(&value).map_err(|err| {
- async_graphql::Error::new(format!("invalid fileType `{value}`: {err}"))
- })?)
- }
- Self::Id(id) => DocumentLiteral::Id(parse_id(id, "id")?),
- Self::ProjectId(id) => DocumentLiteral::ProjectId(parse_id(id, "projectId")?),
- Self::Owner(owner) => DocumentLiteral::Owner(parse_macro_user_id(owner, "owner")?),
- Self::Importance(importance) => DocumentLiteral::Importance(importance),
- Self::NotificationDone(done) => DocumentLiteral::NotificationDone(done),
- Self::NotificationSeen(seen) => DocumentLiteral::NotificationSeen(seen),
- Self::IncludeCbmAtmNc(include) => DocumentLiteral::IncludeCbmAtmNc(include),
- Self::SubType(sub_type) => DocumentLiteral::SubType(sub_type.into_model()),
- Self::IsEmailAttachment(value) => DocumentLiteral::IsEmailAttachment(value),
- Self::CreatedAt(date) => DocumentLiteral::CreatedAt(date.into_ast()?),
- Self::UpdatedAt(date) => DocumentLiteral::UpdatedAt(date.into_ast()?),
- };
- Ok(Expr::val(literal))
- }
-}
-
-/// GraphQL input representing the document sub type.
-#[derive(Enum, Copy, Clone, Eq, PartialEq)]
-enum GraphqlDocumentSubType {
- /// The task option.
- Task,
- /// The snippet option.
- Snippet,
- /// The skill option.
- Skill,
-}
-
-impl GraphqlDocumentSubType {
- /// Convert this GraphQL subtype into the document-filter model.
- fn into_model(self) -> DocumentSubType {
- match self {
- Self::Task => DocumentSubType::Task,
- Self::Snippet => DocumentSubType::Snippet,
- Self::Skill => DocumentSubType::Skill,
- }
- }
-}
-
-/// GraphQL input representing the project literal.
-#[derive(async_graphql::OneofObject)]
-enum GraphqlProjectLiteral {
- /// The project id option.
- ProjectId(ID),
- /// The project id self option.
- ProjectIdSelf(ID),
- /// The owner option.
- Owner(String),
- /// The importance option.
- Importance(bool),
- /// The notification done option.
- NotificationDone(bool),
- /// The notification seen option.
- NotificationSeen(bool),
- /// The created at option.
- CreatedAt(GraphqlDateLiteral),
- /// The updated at option.
- UpdatedAt(GraphqlDateLiteral),
-}
-
-impl IntoFilterExpr<ProjectLiteral> for GraphqlProjectLiteral {
- /// Convert this value into the expr representation.
- fn into_expr(self) -> async_graphql::Result<Expr<ProjectLiteral>> {
- let literal = match self {
- Self::ProjectId(id) => ProjectLiteral::ProjectId(parse_id(id, "projectId")?),
- Self::ProjectIdSelf(id) => {
- ProjectLiteral::ProjectIdSelf(parse_id(id, "projectIdSelf")?)
- }
- Self::Owner(owner) => ProjectLiteral::Owner(parse_macro_user_id(owner, "owner")?),
- Self::Importance(importance) => ProjectLiteral::Importance(importance),
- Self::NotificationDone(done) => ProjectLiteral::NotificationDone(done),
- Self::NotificationSeen(seen) => ProjectLiteral::NotificationSeen(seen),
- Self::CreatedAt(date) => ProjectLiteral::CreatedAt(date.into_ast()?),
- Self::UpdatedAt(date) => ProjectLiteral::UpdatedAt(date.into_ast()?),
- };
- Ok(Expr::val(literal))
- }
-}
-
-/// GraphQL input representing the chat literal.
-#[derive(async_graphql::OneofObject)]
-enum GraphqlChatLiteral {
- /// The project id option.
- ProjectId(ID),
- /// The role option.
- Role(GraphqlChatRole),
- /// The chat id option.
- ChatId(ID),
- /// The owner option.
- Owner(String),
- /// The importance option.
- Importance(bool),
- /// The notification done option.
- NotificationDone(bool),
- /// The notification seen option.
- NotificationSeen(bool),
- /// The created at option.
- CreatedAt(GraphqlDateLiteral),
- /// The updated at option.
- UpdatedAt(GraphqlDateLiteral),
-}
-
-impl IntoFilterExpr<ChatLiteral> for GraphqlChatLiteral {
- /// Convert this value into the expr representation.
- fn into_expr(self) -> async_graphql::Result<Expr<ChatLiteral>> {
- let literal = match self {
- Self::ProjectId(id) => ChatLiteral::ProjectId(parse_id(id, "projectId")?),
- Self::Role(role) => ChatLiteral::Role(role.into_model()),
- Self::ChatId(id) => ChatLiteral::ChatId(parse_id(id, "chatId")?),
- Self::Owner(owner) => ChatLiteral::Owner(parse_macro_user_id(owner, "owner")?),
- Self::Importance(importance) => ChatLiteral::Importance(importance),
- Self::NotificationDone(done) => ChatLiteral::NotificationDone(done),
- Self::NotificationSeen(seen) => ChatLiteral::NotificationSeen(seen),
- Self::CreatedAt(date) => ChatLiteral::CreatedAt(date.into_ast()?),
- Self::UpdatedAt(date) => ChatLiteral::UpdatedAt(date.into_ast()?),
- };
- Ok(Expr::val(literal))
- }
-}
-
-/// GraphQL input representing the chat role.
-#[derive(Enum, Copy, Clone, Eq, PartialEq)]
-enum GraphqlChatRole {
- /// The user option.
- User,
- /// The system option.
- System,
- /// The assistant option.
- Assistant,
-}
-
-impl GraphqlChatRole {
- /// Convert this GraphQL role into the chat-filter model.
- fn into_model(self) -> ChatRole {
- match self {
- Self::User => ChatRole::User,
- Self::System => ChatRole::System,
- Self::Assistant => ChatRole::Assistant,
- }
- }
-}
-
-/// GraphQL input representing the email literal.
-#[derive(async_graphql::OneofObject)]
-enum GraphqlEmailLiteral {
- /// The sender option.
- Sender(GraphqlEmailValue),
- /// The cc option.
- Cc(GraphqlEmailValue),
- /// The bcc option.
- Bcc(GraphqlEmailValue),
- /// The recipient option.
- Recipient(GraphqlEmailValue),
- /// The thread id option.
- ThreadId(ID),
- /// The owner option.
- Owner(ID),
- /// The project id option.
- ProjectId(String),
- /// The importance option.
- Importance(bool),
- /// The notification done option.
- NotificationDone(bool),
- /// The notification seen option.
- NotificationSeen(bool),
- /// The shared option.
- Shared(GraphqlSharedEmailFilter),
- /// The calendar only option.
- CalendarOnly(bool),
- /// The created at option.
- CreatedAt(GraphqlDateLiteral),
- /// The updated at option.
- UpdatedAt(GraphqlDateLiteral),
-}
-
-impl IntoFilterExpr<EmailLiteral> for GraphqlEmailLiteral {
- /// Convert this value into the expr representation.
- fn into_expr(self) -> async_graphql::Result<Expr<EmailLiteral>> {
- let literal = match self {
- Self::Sender(value) => EmailLiteral::Sender(value.into_ast()?),
- Self::Cc(value) => EmailLiteral::Cc(value.into_ast()?),
- Self::Bcc(value) => EmailLiteral::Bcc(value.into_ast()?),
- Self::Recipient(value) => EmailLiteral::Recipient(value.into_ast()?),
- Self::ThreadId(id) => EmailLiteral::ThreadId(parse_id(id, "threadId")?),
- Self::Owner(id) => EmailLiteral::Owner(parse_id(id, "owner")?),
- Self::ProjectId(id) => EmailLiteral::ProjectId(id),
- Self::Importance(importance) => EmailLiteral::Importance(importance),
- Self::NotificationDone(done) => EmailLiteral::NotificationDone(done),
- Self::NotificationSeen(seen) => EmailLiteral::NotificationSeen(seen),
- Self::Shared(shared) => EmailLiteral::Shared(shared.into_model()),
- Self::CalendarOnly(calendar_only) => EmailLiteral::CalendarOnly(calendar_only),
- Self::CreatedAt(date) => EmailLiteral::CreatedAt(date.into_ast()?),
- Self::UpdatedAt(date) => EmailLiteral::UpdatedAt(date.into_ast()?),
- };
- Ok(Expr::val(literal))
- }
-}
-
-/// GraphQL input representing the email value.
-#[derive(async_graphql::OneofObject)]
-enum GraphqlEmailValue {
- /// The partial option.
- Partial(String),
- /// The complete option.
- Complete(String),
- /// The domain option.
- Domain(String),
-}
-
-impl GraphqlEmailValue {
- /// Convert this value into the ast representation.
- fn into_ast(self) -> async_graphql::Result<Email> {
- Ok(match self {
- Self::Partial(value) => Email::Partial(value),
- Self::Complete(value) => Email::Complete(
- EmailStr::parse_from_str(&value)
- .map(CowLike::into_owned)
- .map_err(|err| {
- async_graphql::Error::new(format!(
- "invalid complete email `{value}`: {err}"
- ))
- })?,
- ),
- Self::Domain(value) => Email::Domain(value),
- })
- }
-}
-
-/// GraphQL input representing the shared email filter.
-#[derive(Enum, Copy, Clone, Eq, PartialEq)]
-enum GraphqlSharedEmailFilter {
- /// The exclude option.
- Exclude,
- /// The include option.
- Include,
- /// The only option.
- Only,
-}
-
-impl GraphqlSharedEmailFilter {
- /// Convert this GraphQL option into the shared-email filter model.
- fn into_model(self) -> SharedEmailFilter {
- match self {
- Self::Exclude => SharedEmailFilter::Exclude,
- Self::Include => SharedEmailFilter::Include,
- Self::Only => SharedEmailFilter::Only,
- }
- }
-}
-
-/// GraphQL input representing the channel literal.
-#[derive(async_graphql::OneofObject)]
-enum GraphqlChannelLiteral {
- /// The thread id option.
- ThreadId(ID),
- /// The mention option.
- Mention(String),
- /// The organization id option.
- OrganizationId(i64),
- /// The team id option.
- TeamId(ID),
- /// The channel id option.
- ChannelId(ID),
- /// The sender option.
- Sender(String),
- /// The channel type option.
- ChannelType(GraphqlChannelTypeFilter),
- /// The importance option.
- Importance(bool),
- /// The is participant option. Filters by whether the requesting user is an
- /// active participant; its presence widens the candidate set to team channels
- /// of the user's teams they have not joined.
- IsParticipant(bool),
- /// The notification done option.
- NotificationDone(bool),
- /// The notification seen option.
- NotificationSeen(bool),
-}
-
-impl IntoFilterExpr<ChannelLiteral> for GraphqlChannelLiteral {
- /// Convert this value into the expr representation.
- fn into_expr(self) -> async_graphql::Result<Expr<ChannelLiteral>> {
- let literal = match self {
- Self::ThreadId(id) => ChannelLiteral::ThreadId(parse_id(id, "threadId")?),
- Self::Mention(mention) => {
- ChannelLiteral::Mention(parse_macro_user_id(mention, "mention")?)
- }
- Self::OrganizationId(id) => ChannelLiteral::OrganizationId(id),
- Self::TeamId(id) => ChannelLiteral::TeamId(parse_id(id, "teamId")?),
- Self::ChannelId(id) => ChannelLiteral::ChannelId(parse_id(id, "channelId")?),
- Self::Sender(sender) => ChannelLiteral::Sender(parse_macro_user_id(sender, "sender")?),
- Self::ChannelType(channel_type) => {
- ChannelLiteral::ChannelType(channel_type.into_model())
- }
- Self::Importance(importance) => ChannelLiteral::Importance(importance),
- Self::IsParticipant(is_participant) => ChannelLiteral::IsParticipant(is_participant),
- Self::NotificationDone(done) => ChannelLiteral::NotificationDone(done),
- Self::NotificationSeen(seen) => ChannelLiteral::NotificationSeen(seen),
- };
- Ok(Expr::val(literal))
- }
-}
-
-/// GraphQL input representing the channel type filter.
-#[derive(Enum, Copy, Clone, Eq, PartialEq)]
-enum GraphqlChannelTypeFilter {
- /// The public option.
- Public,
- /// The private option.
- Private,
- /// The direct message option.
- DirectMessage,
- /// The team option.
- Team,
-}
-
-impl GraphqlChannelTypeFilter {
- /// Convert this GraphQL option into the channel-filter model.
- fn into_model(self) -> ChannelTypeFilter {
- match self {
- Self::Public => ChannelTypeFilter::Public,
- Self::Private => ChannelTypeFilter::Private,
- Self::DirectMessage => ChannelTypeFilter::DirectMessage,
- Self::Team => ChannelTypeFilter::Team,
- }
- }
-}
-
-/// GraphQL input representing the channel thread literal.
-#[derive(async_graphql::OneofObject)]
-enum GraphqlChannelThreadLiteral {
- /// The thread id option.
- ThreadId(ID),
- /// The channel id option.
- ChannelId(ID),
- /// The root sender option.
- RootSender(String),
- /// The participant option.
- Participant(String),
- /// The notification done option.
- NotificationDone(bool),
- /// The notification seen option.
- NotificationSeen(bool),
-}
-
-impl IntoFilterExpr<ChannelThreadLiteral> for GraphqlChannelThreadLiteral {
- /// Convert this value into the expr representation.
- fn into_expr(self) -> async_graphql::Result<Expr<ChannelThreadLiteral>> {
- let literal = match self {
- Self::ThreadId(id) => ChannelThreadLiteral::ThreadId(parse_id(id, "threadId")?),
- Self::ChannelId(id) => ChannelThreadLiteral::ChannelId(parse_id(id, "channelId")?),
- Self::RootSender(sender) => {
- ChannelThreadLiteral::RootSender(parse_macro_user_id(sender, "rootSender")?)
- }
- Self::Participant(participant) => {
- ChannelThreadLiteral::Participant(parse_macro_user_id(participant, "participant")?)
- }
- Self::NotificationDone(done) => ChannelThreadLiteral::NotificationDone(done),
- Self::NotificationSeen(seen) => ChannelThreadLiteral::NotificationSeen(seen),
- };
- Ok(Expr::val(literal))
- }
-}
-
-/// GraphQL input representing the call literal.
-#[derive(async_graphql::OneofObject)]
-enum GraphqlCallLiteral {
- /// The call id option.
- CallId(ID),
- /// The channel id option.
- ChannelId(ID),
- /// The speaker option.
- Speaker(String),
- /// The status option.
- Status(GraphqlCallStatus),
- /// The attended option.
- Attended(bool),
-}
-
-impl IntoFilterExpr<CallLiteral> for GraphqlCallLiteral {
- /// Convert this value into the expr representation.
- fn into_expr(self) -> async_graphql::Result<Expr<CallLiteral>> {
- let literal = match self {
- Self::CallId(id) => CallLiteral::CallId(parse_id(id, "callId")?),
- Self::ChannelId(id) => CallLiteral::ChannelId(parse_id(id, "channelId")?),
- Self::Speaker(speaker) => {
- CallLiteral::Speaker(parse_macro_user_id(speaker, "speaker")?)
- }
- Self::Status(status) => CallLiteral::Status(status.into_model()),
- Self::Attended(attended) => CallLiteral::Attended(attended),
- };
- Ok(Expr::val(literal))
- }
-}
-
-/// GraphQL input representing the call status.
-#[derive(Enum, Copy, Clone, Eq, PartialEq)]
-enum GraphqlCallStatus {
- /// The attended option.
- Attended,
- /// The missed option.
- Missed,
- /// The unattended option.
- Unattended,
-}
-
-impl GraphqlCallStatus {
- /// Convert this GraphQL status into the call-filter model.
- fn into_model(self) -> CallStatus {
- match self {
- Self::Attended => CallStatus::Attended,
- Self::Missed => CallStatus::Missed,
- Self::Unattended => CallStatus::Unattended,
- }
- }
-}
-
-/// GraphQL input representing the reminder literal.
-#[derive(async_graphql::OneofObject)]
-enum GraphqlReminderLiteral {
- /// Opt this query into reminders at all. Reminders are off by default, so
- /// without this (or an `id`/`entity`) Soup omits them entirely — a filter
- /// of only `completed` would otherwise silently match nothing. Must be
- /// `true`; there is no literal for excluding reminders, that is the default.
- Include(bool),
- /// The id option.
- Id(ID),
- /// The referenced entity, as `"{type}:{id}"`.
- Entity(String),
- /// Whether the owner has marked the reminder done.
- Completed(bool),
- /// Whether the reminder has come due and is awaiting its owner.
- Fired(bool),
-}
-
-impl IntoFilterExpr<ReminderLiteral> for GraphqlReminderLiteral {
- /// Convert this value into the expr representation.
- fn into_expr(self) -> async_graphql::Result<Expr<ReminderLiteral>> {
- let literal = match self {
- // `include: false` is the default, not a literal — accepting it
- // would opt the query in, the opposite of what was asked.
- Self::Include(false) => {
- return Err(async_graphql::Error::new(
- "reminder `include` must be true; omit the filter to exclude reminders",
- ));
- }
- Self::Include(true) => ReminderLiteral::Include,
- Self::Id(id) => ReminderLiteral::Id(parse_id(id, "id")?),
- Self::Entity(entity) => ReminderLiteral::Entity(entity),
- Self::Completed(completed) => ReminderLiteral::Completed(completed),
- Self::Fired(fired) => ReminderLiteral::Fired(fired),
- };
- Ok(Expr::val(literal))
- }
-}
-
-/// GraphQL input representing the crm company literal.
-#[derive(async_graphql::OneofObject)]
-enum GraphqlCrmCompanyLiteral {
- /// The id option.
- Id(ID),
- /// The hidden option.
- Hidden(bool),
-}
-
-impl IntoFilterExpr<CrmCompanyLiteral> for GraphqlCrmCompanyLiteral {
- /// Convert this value into the expr representation.
- fn into_expr(self) -> async_graphql::Result<Expr<CrmCompanyLiteral>> {
- let literal = match self {
- Self::Id(id) => CrmCompanyLiteral::Id(parse_id(id, "id")?),
- Self::Hidden(hidden) => CrmCompanyLiteral::Hidden(hidden),
- };
- Ok(Expr::val(literal))
- }
-}
-
-/// GraphQL input representing the foreign entity literal.
-#[derive(async_graphql::OneofObject)]
-enum GraphqlForeignEntityLiteral {
- /// The id option.
- Id(ID),
- /// The foreign entity id option.
- ForeignEntityId(String),
- /// The foreign entity source option.
- ForeignEntitySource(String),
- /// The includes me option.
- IncludesMe(bool),
- /// The notification done option.
- NotificationDone(bool),
- /// The notification seen option.
- NotificationSeen(bool),
-}
-
-impl IntoFilterExpr<ForeignEntityLiteral> for GraphqlForeignEntityLiteral {
- /// Convert this value into the expr representation.
- fn into_expr(self) -> async_graphql::Result<Expr<ForeignEntityLiteral>> {
- let literal = match self {
- Self::Id(id) => ForeignEntityLiteral::Id(parse_id(id, "id")?),
- Self::ForeignEntityId(id) => ForeignEntityLiteral::ForeignEntityId(id),
- Self::ForeignEntitySource(source) => ForeignEntityLiteral::ForeignEntitySource(source),
- Self::IncludesMe(true) => ForeignEntityLiteral::IncludesMe,
- Self::IncludesMe(false) => {
- return Err(async_graphql::Error::new(
- "ForeignEntityLiteral.includesMe must be true",
- ));
- }
- Self::NotificationDone(done) => ForeignEntityLiteral::NotificationDone(done),
- Self::NotificationSeen(seen) => ForeignEntityLiteral::NotificationSeen(seen),
- };
- Ok(Expr::val(literal))
- }
-}
+// Filter input types and their authoritative materialization live in
+// `graphql_soup_filter_input`, shared with the browser cache composition root.
/// GraphQL representation of supported simple Soup sorts.
#[derive(Enum, Copy, Clone, Eq, PartialEq)]
diff --git a/crates/graphql_soup/src/inputs/tests.rs b/crates/graphql_soup/src/inputs/tests.rs
index 76ce2c9175..eae4175d22 100644
--- a/crates/graphql_soup/src/inputs/tests.rs
+++ b/crates/graphql_soup/src/inputs/tests.rs
@@ -1,6 +1,3 @@
-use async_graphql::ID;
-use filter_ast::Expr;
-use item_filters::ast::{chat::ChatLiteral, document::DocumentLiteral};
use macro_user_id::{cowlike::CowLike, user_id::MacroUserIdStr};
use models_pagination::{CursorVal, Query};
@@ -120,33 +117,3 @@ fn maps_grouped_cursor_continuation() {
assert_eq!(request.grouping.group_key.as_deref(), Some("document"));
assert!(matches!(request.cursor, Query::Cursor(_)));
}
-
-#[test]
-fn expands_document_file_assoc() {
- let expr = GraphqlDocumentLiteral::FileAssoc("assoc:pdf".to_owned())
- .into_expr()
- .unwrap();
-
- assert!(matches!(expr, Expr::Literal(DocumentLiteral::FileType(_))));
-}
-
-#[test]
-fn builds_binary_filter_expressions() {
- let expr = GraphqlChatExpr::And(GraphqlChatBinaryExpr {
- left: Box::new(GraphqlChatExpr::Literal(GraphqlChatLiteral::ChatId(ID(
- "00000000-0000-0000-0000-000000000001".to_owned(),
- )))),
- right: Box::new(GraphqlChatExpr::Literal(GraphqlChatLiteral::ChatId(ID(
- "00000000-0000-0000-0000-000000000002".to_owned(),
- )))),
- })
- .into_expr()
- .unwrap();
-
- assert!(matches!(
- expr,
- Expr::And(left, right)
- if matches!(*left, Expr::Literal(ChatLiteral::ChatId(_)))
- && matches!(*right, Expr::Literal(ChatLiteral::ChatId(_)))
- ));
-}
diff --git a/crates/graphql_soup_filter_input/Cargo.toml b/crates/graphql_soup_filter_input/Cargo.toml
new file mode 100644
index 0000000000..e9b44aef35
--- /dev/null
+++ b/crates/graphql_soup_filter_input/Cargo.toml
@@ -0,0 +1,23 @@
+[package]
+edition = "2024"
+name = "graphql_soup_filter_input"
+publish = false
+version = "0.1.0"
+
+[features]
+default = []
+server = ["dep:async-graphql", "dep:graphql_common"]
+
+[dependencies]
+async-graphql = { workspace = true, optional = true }
+chrono = { workspace = true }
+document_sub_type = { path = "../document_sub_type", default-features = false }
+filter_ast = { path = "../filter_ast" }
+graphql_common = { path = "../graphql_common", optional = true }
+item_filters = { path = "../item_filters", default-features = false }
+macro_user_id = { path = "../macro_user_id" }
+model_file_type = { path = "../model_file_type" }
+serde = { workspace = true }
+serde_json = { workspace = true }
+thiserror = { workspace = true }
+uuid = { workspace = true, features = ["js"] }
diff --git a/crates/graphql_soup_filter_input/fixtures/generated-soup-filter.json b/crates/graphql_soup_filter_input/fixtures/generated-soup-filter.json
new file mode 100644
index 0000000000..128504bffb
--- /dev/null
+++ b/crates/graphql_soup_filter_input/fixtures/generated-soup-filter.json
@@ -0,0 +1,24 @@
+{
+ "documentFilter": {
+ "and": {
+ "left": { "literal": { "notificationDone": false } },
+ "right": {
+ "literal": { "updatedAt": { "gte": "2026-01-01T00:00:00.000Z" } }
+ }
+ }
+ },
+ "projectFilter": {
+ "literal": { "projectIdSelf": "00000000-0000-0000-0000-000000000000" }
+ },
+ "chatFilter": {
+ "not": {
+ "literal": { "owner": "macro|[email protected]" }
+ }
+ },
+ "emailFilter": {
+ "tree": { "literal": { "shared": "EXCLUDE" } }
+ },
+ "channelFilter": {
+ "literal": { "channelId": "00000000-0000-0000-0000-000000000000" }
+ }
+}
diff --git a/crates/graphql_soup_filter_input/src/lib.rs b/crates/graphql_soup_filter_input/src/lib.rs
new file mode 100644
index 0000000000..9efbc46fa5
--- /dev/null
+++ b/crates/graphql_soup_filter_input/src/lib.rs
@@ -0,0 +1,1176 @@
+//! Browser-compatible GraphQL Soup filter input materialization.
+//!
+//! This crate owns the GraphQL variables shape and conversion into the
+//! authoritative `item_filters` AST without depending on Axum or a GraphQL
+//! server adapter crate.
+#![deny(missing_docs)]
+
+use std::{str::FromStr, sync::Arc};
+
+#[cfg(feature = "server")]
+use async_graphql::ID;
+#[cfg(feature = "server")]
+use graphql_common::GraphqlPropertyEntityType;
+#[cfg(not(feature = "server"))]
+type ID = String;
+use chrono::{DateTime, Utc};
+use document_sub_type::DocumentSubType;
+use filter_ast::Expr;
+use item_filters::{
+ CallStatus, SharedEmailFilter,
+ ast::{
+ CrmScope, EmailFilterAst, EntityFilterAst,
+ calendar_event::CalendarEventLiteral,
+ call::CallLiteral,
+ channel::{ChannelLiteral, ChannelThreadLiteral, ChannelTypeFilter},
+ chat::{ChatLiteral, ChatRole},
+ crm_company::CrmCompanyLiteral,
+ date::DateLiteral,
+ document::DocumentLiteral,
+ email::{Email, EmailLiteral},
+ foreign_entity::ForeignEntityLiteral,
+ project::ProjectLiteral,
+ properties::{EntityRefId, PropertiesLiteral, PropertyEntityType, PropertyMatchValue},
+ reminder::ReminderLiteral,
+ },
+};
+use macro_user_id::{cowlike::CowLike, email::EmailStr, user_id::MacroUserIdStr};
+use model_file_type::FileType;
+use serde::{Deserialize, Serialize};
+use serde_json::Value;
+use thiserror::Error;
+use uuid::Uuid;
+
+#[cfg(test)]
+mod test;
+
+/// Maximum accepted GraphQL filter expression depth.
+pub const MAX_FILTER_DEPTH: usize = 64;
+/// Maximum accepted JSON values in one GraphQL filter input.
+pub const MAX_FILTER_NODES: usize = 2_048;
+/// Maximum bytes accepted in one string value.
+pub const MAX_FILTER_STRING_BYTES: usize = 16 * 1_024;
+/// Maximum aggregate bytes across string values.
+pub const MAX_FILTER_VALUE_BYTES: usize = 256 * 1_024;
+
+/// Failure to validate, deserialize, or materialize a GraphQL Soup filter.
+#[derive(Debug, Error)]
+pub enum MaterializeError {
+ /// The variables value exceeds a configured ingress bound.
+ #[error("GraphQL Soup filter exceeds ingress bounds: {0}")]
+ Bounds(String),
+ /// The variables value does not have the generated GraphQL input shape.
+ #[error("invalid GraphQL Soup filter input: {0}")]
+ Shape(#[from] serde_json::Error),
+ /// A typed value failed GraphQL-specific domain validation.
+ #[error("invalid GraphQL Soup filter value: {0}")]
+ Conversion(String),
+}
+
+/// Validate and materialize the exact generated GraphQL `filters` variables value.
+pub fn materialize_graphql_filter(value: Value) -> Result<EntityFilterAst, MaterializeError> {
+ validate_json_bounds(&value).map_err(MaterializeError::Bounds)?;
+ serde_json::from_value::<GraphqlEntityFilterAst>(value)?
+ .into_ast_unchecked()
+ .map_err(|error| MaterializeError::Conversion(error.to_string()))
+}
+
+/// Enforce cheap structural bounds before recursive deserialization or compilation.
+fn validate_json_bounds(value: &Value) -> Result<(), String> {
+ let mut stack = vec![(value, 1usize)];
+ let mut nodes = 0usize;
+ let mut value_bytes = 0usize;
+
+ while let Some((value, depth)) = stack.pop() {
+ if depth > MAX_FILTER_DEPTH {
+ return Err(format!("depth exceeds {MAX_FILTER_DEPTH}"));
+ }
+ nodes += 1;
+ if nodes > MAX_FILTER_NODES {
+ return Err(format!("node count exceeds {MAX_FILTER_NODES}"));
+ }
+
+ match value {
+ Value::String(value) => {
+ let len = value.len();
+ if len > MAX_FILTER_STRING_BYTES {
+ return Err(format!("string bytes exceed {MAX_FILTER_STRING_BYTES}"));
+ }
+ value_bytes = value_bytes.saturating_add(len);
+ if value_bytes > MAX_FILTER_VALUE_BYTES {
+ return Err(format!(
+ "aggregate string bytes exceed {MAX_FILTER_VALUE_BYTES}"
+ ));
+ }
+ }
+ Value::Array(values) => {
+ stack.extend(values.iter().map(|value| (value, depth + 1)));
+ }
+ Value::Object(values) => {
+ stack.extend(values.values().map(|value| (value, depth + 1)));
+ }
+ Value::Null | Value::Bool(_) | Value::Number(_) => {}
+ }
+ }
+
+ Ok(())
+}
+
+/// GraphQL-shape or materialization validation failure.
+#[derive(Debug, Error)]
+pub struct InputError(String);
+
+impl InputError {
+ fn new(message: impl Into<String>) -> Self {
+ Self(message.into())
+ }
+}
+
+impl std::fmt::Display for InputError {
+ fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+ formatter.write_str(&self.0)
+ }
+}
+
+type InputResult<T> = Result<T, InputError>;
+
+/// Conversion from a GraphQL filter input tree into a domain filter expression.
+trait IntoFilterExpr<T>: Sized {
+ /// Convert the input into a filter expression.
+ fn into_expr(self) -> InputResult<Expr<T>>;
+}
+
+/// Convert an optional GraphQL expression into the shared tree representation.
+fn optional_tree<I, T>(input: Option<I>) -> InputResult<Option<Arc<Expr<T>>>>
+where
+ I: IntoFilterExpr<T>,
+{
+ input.map(|expr| expr.into_expr().map(Arc::new)).transpose()
+}
+
+/// Parse a GraphQL id as a UUID with a field-specific error.
+fn parse_id(id: ID, field: &str) -> InputResult<Uuid> {
+ let value = id.to_string();
+ Uuid::parse_str(&value)
+ .map_err(|err| InputError::new(format!("invalid {field} UUID `{value}`: {err}")))
+}
+
+/// Parse a Macro user id with a field-specific error.
+fn parse_macro_user_id(value: String, field: &str) -> InputResult<MacroUserIdStr<'static>> {
+ MacroUserIdStr::parse_from_str(&value)
+ .map(CowLike::into_owned)
+ .map_err(|err| InputError::new(format!("invalid {field} `{value}`: {err}")))
+}
+
+/// Define the recursive GraphQL and serde expression shape for one literal family.
+macro_rules! filter_expr_input {
+ ($name:ident, $binary_name:ident, $literal:ty, $target:ty, $type_name:literal) => {
+ #[doc = concat!("The two operands of a recursive `", $type_name, "` binary expression.")]
+ #[cfg_attr(feature = "server", derive(async_graphql::InputObject))]
+ #[derive(Serialize, Deserialize)]
+ #[serde(rename_all = "camelCase")]
+ struct $binary_name {
+ /// Left expression.
+ left: Box<$name>,
+ /// Right expression.
+ right: Box<$name>,
+ }
+
+ #[doc = concat!("A recursive `", $type_name, "` filter expression.")]
+ #[cfg_attr(feature = "server", derive(async_graphql::OneofObject))]
+ #[derive(Serialize, Deserialize)]
+ #[serde(rename_all = "camelCase")]
+ enum $name {
+ /// Both expressions must match.
+ And($binary_name),
+ /// Either expression may match.
+ Or($binary_name),
+ /// Negate an expression.
+ Not(Box<$name>),
+ /// Match a literal.
+ Literal($literal),
+ }
+
+ impl IntoFilterExpr<$target> for $name {
+ fn into_expr(self) -> InputResult<Expr<$target>> {
+ match self {
+ Self::And(exprs) => {
+ Ok(Expr::and(exprs.left.into_expr()?, exprs.right.into_expr()?))
+ }
+ Self::Or(exprs) => {
+ Ok(Expr::or(exprs.left.into_expr()?, exprs.right.into_expr()?))
+ }
+ Self::Not(expr) => expr.into_expr().map(Expr::is_not),
+ Self::Literal(literal) => literal.into_expr(),
+ }
+ }
+ }
+ };
+}
+
+filter_expr_input!(
+ GraphqlFilterPropertiesExpr,
+ GraphqlFilterPropertiesBinaryExpr,
+ GraphqlFilterPropertiesLiteral,
+ PropertiesLiteral,
+ "PropertiesFilterExpr"
+);
+
+/// GraphQL input for matching a property value on an entity.
+#[cfg_attr(feature = "server", derive(async_graphql::InputObject))]
+#[derive(Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+struct GraphqlFilterPropertiesLiteral {
+ /// Property definition id to match.
+ property_definition_id: ID,
+ /// Optional entity type scope for the property match.
+ entity_type: Option<GraphqlPropertyEntityType>,
+ /// Value to compare against the property.
+ value: GraphqlFilterPropertyMatchValue,
+}
+
+impl IntoFilterExpr<PropertiesLiteral> for GraphqlFilterPropertiesLiteral {
+ fn into_expr(self) -> InputResult<Expr<PropertiesLiteral>> {
+ Ok(Expr::val(PropertiesLiteral {
+ property_definition_id: parse_id(self.property_definition_id, "propertyDefinitionId")?,
+ entity_type: self
+ .entity_type
+ .map(PropertyEntityType::try_from)
+ .transpose()
+ .map_err(|entity_type| {
+ InputError::new(format!("unsupported entityType {entity_type:?}"))
+ })?,
+ value: self.value.into_ast()?,
+ }))
+ }
+}
+
+/// GraphQL input value used when matching a property.
+#[cfg_attr(feature = "server", derive(async_graphql::OneofObject))]
+#[derive(Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+enum GraphqlFilterPropertyMatchValue {
+ /// Select option id to match.
+ SelectOption(ID),
+ /// Entity reference id to match.
+ EntityRef(ID),
+}
+
+impl GraphqlFilterPropertyMatchValue {
+ /// Convert this input into the domain representation.
+ fn into_ast(self) -> InputResult<PropertyMatchValue> {
+ Ok(match self {
+ Self::SelectOption(id) => {
+ PropertyMatchValue::SelectOption(parse_id(id, "selectOption")?)
+ }
+ Self::EntityRef(value) => PropertyMatchValue::EntityRef(
+ EntityRefId::new(value.to_string())
+ .map_err(|err| InputError::new(format!("invalid entityRef: {err}")))?,
+ ),
+ })
+ }
+}
+
+/// An entity type supported by property filters in browser-only materialization.
+#[cfg(not(feature = "server"))]
+#[derive(Debug, Copy, Clone, Eq, PartialEq, Serialize, Deserialize)]
+#[serde(rename_all = "SCREAMING_SNAKE_CASE")]
+enum GraphqlPropertyEntityType {
+ /// Calendar event entity.
+ CalendarEvent,
+ /// Call record entity.
+ CallRecord,
+ /// Channel entity.
+ Channel,
+ /// Chat entity.
+ Chat,
+ /// Company entity.
+ Company,
+ /// Document entity.
+ Document,
+ /// Project entity.
+ Project,
+ /// Task entity.
+ Task,
+ /// Thread entity.
+ Thread,
+ /// User entity.
+ User,
+}
+
+#[cfg(not(feature = "server"))]
+impl TryFrom<GraphqlPropertyEntityType> for PropertyEntityType {
+ type Error = GraphqlPropertyEntityType;
+
+ fn try_from(value: GraphqlPropertyEntityType) -> Result<Self, Self::Error> {
+ Ok(match value {
+ GraphqlPropertyEntityType::CalendarEvent => Self::CalendarEvent,
+ GraphqlPropertyEntityType::Channel => Self::Channel,
+ GraphqlPropertyEntityType::Chat => Self::Chat,
+ GraphqlPropertyEntityType::Company => Self::Company,
+ GraphqlPropertyEntityType::Document => Self::Document,
+ GraphqlPropertyEntityType::Project => Self::Project,
+ GraphqlPropertyEntityType::Task => Self::Task,
+ GraphqlPropertyEntityType::Thread => Self::Thread,
+ GraphqlPropertyEntityType::User => Self::User,
+ other @ GraphqlPropertyEntityType::CallRecord => return Err(other),
+ })
+ }
+}
+
+/// GraphQL input mirroring `item_filters::ast::EntityFilterAst`.
+#[cfg_attr(feature = "server", derive(async_graphql::InputObject))]
+#[derive(Serialize, Deserialize)]
+#[serde(deny_unknown_fields, rename_all = "camelCase")]
+pub struct GraphqlEntityFilterAst {
+ /// The calendar event filter to apply.
+ calendar_event_filter: Option<GraphqlCalendarEventExpr>,
+ /// The document filter to apply.
+ document_filter: Option<GraphqlDocumentExpr>,
+ /// The project filter to apply.
+ project_filter: Option<GraphqlProjectExpr>,
+ /// The chat filter to apply.
+ chat_filter: Option<GraphqlChatExpr>,
+ /// The email filter to apply.
+ email_filter: Option<GraphqlEmailFilterAst>,
+ /// The channel filter to apply.
+ channel_filter: Option<GraphqlChannelExpr>,
+ /// The channel thread filter to apply.
+ channel_thread_filter: Option<GraphqlChannelThreadExpr>,
+ /// The call filter to apply.
+ call_filter: Option<GraphqlCallExpr>,
+ /// The crm company filter to apply.
+ crm_company_filter: Option<GraphqlCrmCompanyExpr>,
+ /// The foreign entity filter to apply.
+ foreign_entity_filter: Option<GraphqlForeignEntityExpr>,
+ /// The reminder filter to apply.
+ reminder_filter: Option<GraphqlReminderExpr>,
+ /// The properties filter to apply.
+ properties_filter: Option<GraphqlFilterPropertiesExpr>,
+}
+
+impl GraphqlEntityFilterAst {
+ /// Convert this value into the ast representation.
+ pub fn into_ast(self) -> InputResult<EntityFilterAst> {
+ let value = serde_json::to_value(&self).map_err(|error| {
+ InputError::new(format!("failed to validate GraphQL filter input: {error}"))
+ })?;
+ validate_json_bounds(&value).map_err(InputError::new)?;
+ self.into_ast_unchecked()
+ }
+
+ /// Convert an input whose serialized representation already passed ingress bounds.
+ fn into_ast_unchecked(self) -> InputResult<EntityFilterAst> {
+ Ok(EntityFilterAst {
+ calendar_event_filter: optional_tree(self.calendar_event_filter)?,
+ document_filter: optional_tree(self.document_filter)?,
+ project_filter: optional_tree(self.project_filter)?,
+ chat_filter: optional_tree(self.chat_filter)?,
+ email_filter: self
+ .email_filter
+ .map(GraphqlEmailFilterAst::into_ast)
+ .transpose()?
+ .unwrap_or_default(),
+ channel_filter: optional_tree(self.channel_filter)?,
+ channel_thread_filter: optional_tree(self.channel_thread_filter)?,
+ call_filter: optional_tree(self.call_filter)?,
+ crm_company_filter: optional_tree(self.crm_company_filter)?,
+ foreign_entity_filter: optional_tree(self.foreign_entity_filter)?,
+ reminder_filter: optional_tree(self.reminder_filter)?,
+ properties_filter: optional_tree(self.properties_filter)?,
+ })
+ }
+}
+
+filter_expr_input!(
+ GraphqlCalendarEventExpr,
+ GraphqlCalendarEventBinaryExpr,
+ GraphqlCalendarEventLiteral,
+ CalendarEventLiteral,
+ "CalendarEventFilterExpr"
+);
+filter_expr_input!(
+ GraphqlDocumentExpr,
+ GraphqlDocumentBinaryExpr,
+ GraphqlDocumentLiteral,
+ DocumentLiteral,
+ "DocumentFilterExpr"
+);
+
+/// GraphQL input representing a calendar event literal.
+#[cfg_attr(feature = "server", derive(async_graphql::OneofObject))]
+#[derive(Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+enum GraphqlCalendarEventLiteral {
+ /// Canonical event id.
+ Id(ID),
+ /// Event status.
+ Status(String),
+ /// Master start must be before this RFC3339 instant.
+ StartsBefore(String),
+ /// Master end must be after this RFC3339 instant.
+ EndsAfter(String),
+ /// Attendee email.
+ Attendee(String),
+ /// Organizer email.
+ Organizer(String),
+ /// Notification done state for the requester.
+ NotificationDone(bool),
+ /// Notification seen state for the requester.
+ NotificationSeen(bool),
+}
+
+impl IntoFilterExpr<CalendarEventLiteral> for GraphqlCalendarEventLiteral {
+ fn into_expr(self) -> InputResult<Expr<CalendarEventLiteral>> {
+ let parse_date = |value: String| {
+ DateTime::parse_from_rfc3339(&value)
+ .map(|date| date.with_timezone(&Utc))
+ .map_err(|error| {
+ InputError::new(format!("invalid RFC3339 calendar date `{value}`: {error}"))
+ })
+ };
+ Ok(Expr::val(match self {
+ Self::Id(id) => CalendarEventLiteral::Id(parse_id(id, "id")?),
+ Self::Status(status) => CalendarEventLiteral::Status(status.to_ascii_lowercase()),
+ Self::StartsBefore(value) => CalendarEventLiteral::StartsBefore(parse_date(value)?),
+ Self::EndsAfter(value) => CalendarEventLiteral::EndsAfter(parse_date(value)?),
+ Self::Attendee(email) => CalendarEventLiteral::Attendee(email.to_ascii_lowercase()),
+ Self::Organizer(email) => CalendarEventLiteral::Organizer(email.to_ascii_lowercase()),
+ Self::NotificationDone(done) => CalendarEventLiteral::NotificationDone(done),
+ Self::NotificationSeen(seen) => CalendarEventLiteral::NotificationSeen(seen),
+ }))
+ }
+}
+filter_expr_input!(
+ GraphqlProjectExpr,
+ GraphqlProjectBinaryExpr,
+ GraphqlProjectLiteral,
+ ProjectLiteral,
+ "ProjectFilterExpr"
+);
+filter_expr_input!(
+ GraphqlChatExpr,
+ GraphqlChatBinaryExpr,
+ GraphqlChatLiteral,
+ ChatLiteral,
+ "ChatFilterExpr"
+);
+filter_expr_input!(
+ GraphqlEmailExpr,
+ GraphqlEmailBinaryExpr,
+ GraphqlEmailLiteral,
+ EmailLiteral,
+ "EmailFilterExpr"
+);
+filter_expr_input!(
+ GraphqlChannelExpr,
+ GraphqlChannelBinaryExpr,
+ GraphqlChannelLiteral,
+ ChannelLiteral,
+ "ChannelFilterExpr"
+);
+filter_expr_input!(
+ GraphqlChannelThreadExpr,
+ GraphqlChannelThreadBinaryExpr,
+ GraphqlChannelThreadLiteral,
+ ChannelThreadLiteral,
+ "ChannelThreadFilterExpr"
+);
+filter_expr_input!(
+ GraphqlCallExpr,
+ GraphqlCallBinaryExpr,
+ GraphqlCallLiteral,
+ CallLiteral,
+ "CallFilterExpr"
+);
+filter_expr_input!(
+ GraphqlCrmCompanyExpr,
+ GraphqlCrmCompanyBinaryExpr,
+ GraphqlCrmCompanyLiteral,
+ CrmCompanyLiteral,
+ "CrmCompanyFilterExpr"
+);
+filter_expr_input!(
+ GraphqlForeignEntityExpr,
+ GraphqlForeignEntityBinaryExpr,
+ GraphqlForeignEntityLiteral,
+ ForeignEntityLiteral,
+ "ForeignEntityFilterExpr"
+);
+filter_expr_input!(
+ GraphqlReminderExpr,
+ GraphqlReminderBinaryExpr,
+ GraphqlReminderLiteral,
+ ReminderLiteral,
+ "ReminderFilterExpr"
+);
+/// GraphQL input representing the email filter ast.
+#[cfg_attr(feature = "server", derive(async_graphql::InputObject))]
+#[derive(Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+struct GraphqlEmailFilterAst {
+ /// The tree.
+ tree: Option<GraphqlEmailExpr>,
+ /// The crm scope.
+ crm_scope: Option<GraphqlCrmScope>,
+}
+
+impl GraphqlEmailFilterAst {
+ /// Convert this value into the ast representation.
+ fn into_ast(self) -> InputResult<EmailFilterAst> {
+ Ok(EmailFilterAst {
+ tree: optional_tree(self.tree)?,
+ crm_scope: self.crm_scope.map(GraphqlCrmScope::into_ast).transpose()?,
+ })
+ }
+}
+
+/// GraphQL input representing the crm scope.
+#[cfg_attr(feature = "server", derive(async_graphql::OneofObject))]
+#[derive(Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+enum GraphqlCrmScope {
+ /// The domains option.
+ Domains(Vec<String>),
+ /// The addresses option.
+ Addresses(Vec<String>),
+}
+
+impl GraphqlCrmScope {
+ /// Convert this value into the ast representation.
+ fn into_ast(self) -> InputResult<CrmScope> {
+ match self {
+ Self::Domains(domains) if domains.is_empty() => {
+ Err(InputError::new("CrmScope.domains cannot be empty"))
+ }
+ Self::Domains(domains) => Ok(CrmScope::Domains(domains)),
+ Self::Addresses(addresses) if addresses.is_empty() => {
+ Err(InputError::new("CrmScope.addresses cannot be empty"))
+ }
+ Self::Addresses(addresses) => Ok(CrmScope::Addresses(addresses)),
+ }
+ }
+}
+
+/// GraphQL input representing the date literal.
+#[cfg_attr(feature = "server", derive(async_graphql::OneofObject))]
+#[derive(Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+enum GraphqlDateLiteral {
+ /// The gt option.
+ Gt(String),
+ /// The lt option.
+ Lt(String),
+ /// The gte option.
+ Gte(String),
+ /// The lte option.
+ Lte(String),
+}
+
+impl GraphqlDateLiteral {
+ /// Parse an email address from a GraphQL string value.
+ fn parse(value: String) -> InputResult<DateTime<Utc>> {
+ DateTime::parse_from_rfc3339(&value)
+ .map(|dt| dt.with_timezone(&Utc))
+ .map_err(|err| InputError::new(format!("invalid RFC3339 date `{value}`: {err}")))
+ }
+
+ /// Convert this value into the ast representation.
+ fn into_ast(self) -> InputResult<DateLiteral> {
+ Ok(match self {
+ Self::Gt(value) => DateLiteral::GreaterThan(Self::parse(value)?),
+ Self::Lt(value) => DateLiteral::LessThan(Self::parse(value)?),
+ Self::Gte(value) => DateLiteral::GreaterThanOrEqual(Self::parse(value)?),
+ Self::Lte(value) => DateLiteral::LessThanOrEqual(Self::parse(value)?),
+ })
+ }
+}
+
+/// GraphQL input representing the document literal.
+#[cfg_attr(feature = "server", derive(async_graphql::OneofObject))]
+#[derive(Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+enum GraphqlDocumentLiteral {
+ /// The file type option.
+ FileType(String),
+ /// The id option.
+ Id(ID),
+ /// The project id option.
+ ProjectId(ID),
+ /// The owner option.
+ Owner(String),
+ /// The importance option.
+ Importance(bool),
+ /// The notification done option.
+ NotificationDone(bool),
+ /// The notification seen option.
+ NotificationSeen(bool),
+ /// The include cbm atm nc option.
+ IncludeCbmAtmNc(bool),
+ /// The sub type option.
+ SubType(GraphqlDocumentSubType),
+ /// The file assoc option.
+ FileAssoc(String),
+ /// The is email attachment option.
+ IsEmailAttachment(bool),
+ /// The created at option.
+ CreatedAt(GraphqlDateLiteral),
+ /// The updated at option.
+ UpdatedAt(GraphqlDateLiteral),
+}
+
+impl IntoFilterExpr<DocumentLiteral> for GraphqlDocumentLiteral {
+ /// Convert this value into the expr representation.
+ fn into_expr(self) -> InputResult<Expr<DocumentLiteral>> {
+ let literal = match self {
+ Self::FileAssoc(value) => {
+ let (_, file_types) = item_filters::ast::document::parse_to_file_types(&value)
+ .map_err(|err| InputError::new(err.to_string()))?;
+ return file_types
+ .map(|file_type| Expr::val(DocumentLiteral::FileType(file_type)))
+ .reduce(Expr::or)
+ .ok_or_else(|| InputError::new("fileAssoc expansion cannot be empty"));
+ }
+ Self::FileType(value) => DocumentLiteral::FileType(
+ FileType::from_str(&value)
+ .map_err(|err| InputError::new(format!("invalid fileType `{value}`: {err}")))?,
+ ),
+ Self::Id(id) => DocumentLiteral::Id(parse_id(id, "id")?),
+ Self::ProjectId(id) => DocumentLiteral::ProjectId(parse_id(id, "projectId")?),
+ Self::Owner(owner) => DocumentLiteral::Owner(parse_macro_user_id(owner, "owner")?),
+ Self::Importance(importance) => DocumentLiteral::Importance(importance),
+ Self::NotificationDone(done) => DocumentLiteral::NotificationDone(done),
+ Self::NotificationSeen(seen) => DocumentLiteral::NotificationSeen(seen),
+ Self::IncludeCbmAtmNc(include) => DocumentLiteral::IncludeCbmAtmNc(include),
+ Self::SubType(sub_type) => DocumentLiteral::SubType(sub_type.into_model()),
+ Self::IsEmailAttachment(value) => DocumentLiteral::IsEmailAttachment(value),
+ Self::CreatedAt(date) => DocumentLiteral::CreatedAt(date.into_ast()?),
+ Self::UpdatedAt(date) => DocumentLiteral::UpdatedAt(date.into_ast()?),
+ };
+ Ok(Expr::val(literal))
+ }
+}
+
+/// GraphQL input representing the document sub type.
+#[cfg_attr(feature = "server", derive(async_graphql::Enum))]
+#[derive(Copy, Clone, Eq, PartialEq, Serialize, Deserialize)]
+#[serde(rename_all = "SCREAMING_SNAKE_CASE")]
+enum GraphqlDocumentSubType {
+ /// The task option.
+ Task,
+ /// The snippet option.
+ Snippet,
+ /// The skill option.
+ Skill,
+}
+
+impl GraphqlDocumentSubType {
+ /// Convert this GraphQL subtype into the document-filter model.
+ fn into_model(self) -> DocumentSubType {
+ match self {
+ Self::Task => DocumentSubType::Task,
+ Self::Snippet => DocumentSubType::Snippet,
+ Self::Skill => DocumentSubType::Skill,
+ }
+ }
+}
+
+/// GraphQL input representing the project literal.
+#[cfg_attr(feature = "server", derive(async_graphql::OneofObject))]
+#[derive(Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+enum GraphqlProjectLiteral {
+ /// The project id option.
+ ProjectId(ID),
+ /// The project id self option.
+ ProjectIdSelf(ID),
+ /// The owner option.
+ Owner(String),
+ /// The importance option.
+ Importance(bool),
+ /// The notification done option.
+ NotificationDone(bool),
+ /// The notification seen option.
+ NotificationSeen(bool),
+ /// The created at option.
+ CreatedAt(GraphqlDateLiteral),
+ /// The updated at option.
+ UpdatedAt(GraphqlDateLiteral),
+}
+
+impl IntoFilterExpr<ProjectLiteral> for GraphqlProjectLiteral {
+ /// Convert this value into the expr representation.
+ fn into_expr(self) -> InputResult<Expr<ProjectLiteral>> {
+ let literal = match self {
+ Self::ProjectId(id) => ProjectLiteral::ProjectId(parse_id(id, "projectId")?),
+ Self::ProjectIdSelf(id) => {
+ ProjectLiteral::ProjectIdSelf(parse_id(id, "projectIdSelf")?)
+ }
+ Self::Owner(owner) => ProjectLiteral::Owner(parse_macro_user_id(owner, "owner")?),
+ Self::Importance(importance) => ProjectLiteral::Importance(importance),
+ Self::NotificationDone(done) => ProjectLiteral::NotificationDone(done),
+ Self::NotificationSeen(seen) => ProjectLiteral::NotificationSeen(seen),
+ Self::CreatedAt(date) => ProjectLiteral::CreatedAt(date.into_ast()?),
+ Self::UpdatedAt(date) => ProjectLiteral::UpdatedAt(date.into_ast()?),
+ };
+ Ok(Expr::val(literal))
+ }
+}
+
+/// GraphQL input representing the chat literal.
+#[cfg_attr(feature = "server", derive(async_graphql::OneofObject))]
+#[derive(Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+enum GraphqlChatLiteral {
+ /// The project id option.
+ ProjectId(ID),
+ /// The role option.
+ Role(GraphqlChatRole),
+ /// The chat id option.
+ ChatId(ID),
+ /// The owner option.
+ Owner(String),
+ /// The importance option.
+ Importance(bool),
+ /// The notification done option.
+ NotificationDone(bool),
+ /// The notification seen option.
+ NotificationSeen(bool),
+ /// The created at option.
+ CreatedAt(GraphqlDateLiteral),
+ /// The updated at option.
+ UpdatedAt(GraphqlDateLiteral),
+}
+
+impl IntoFilterExpr<ChatLiteral> for GraphqlChatLiteral {
+ /// Convert this value into the expr representation.
+ fn into_expr(self) -> InputResult<Expr<ChatLiteral>> {
+ let literal = match self {
+ Self::ProjectId(id) => ChatLiteral::ProjectId(parse_id(id, "projectId")?),
+ Self::Role(role) => ChatLiteral::Role(role.into_model()),
+ Self::ChatId(id) => ChatLiteral::ChatId(parse_id(id, "chatId")?),
+ Self::Owner(owner) => ChatLiteral::Owner(parse_macro_user_id(owner, "owner")?),
+ Self::Importance(importance) => ChatLiteral::Importance(importance),
+ Self::NotificationDone(done) => ChatLiteral::NotificationDone(done),
+ Self::NotificationSeen(seen) => ChatLiteral::NotificationSeen(seen),
+ Self::CreatedAt(date) => ChatLiteral::CreatedAt(date.into_ast()?),
+ Self::UpdatedAt(date) => ChatLiteral::UpdatedAt(date.into_ast()?),
+ };
+ Ok(Expr::val(literal))
+ }
+}
+
+/// GraphQL input representing the chat role.
+#[cfg_attr(feature = "server", derive(async_graphql::Enum))]
+#[derive(Copy, Clone, Eq, PartialEq, Serialize, Deserialize)]
+#[serde(rename_all = "SCREAMING_SNAKE_CASE")]
+enum GraphqlChatRole {
+ /// The user option.
+ User,
+ /// The system option.
+ System,
+ /// The assistant option.
+ Assistant,
+}
+
+impl GraphqlChatRole {
+ /// Convert this GraphQL role into the chat-filter model.
+ fn into_model(self) -> ChatRole {
+ match self {
+ Self::User => ChatRole::User,
+ Self::System => ChatRole::System,
+ Self::Assistant => ChatRole::Assistant,
+ }
+ }
+}
+
+/// GraphQL input representing the email literal.
+#[cfg_attr(feature = "server", derive(async_graphql::OneofObject))]
+#[derive(Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+enum GraphqlEmailLiteral {
+ /// The sender option.
+ Sender(GraphqlEmailValue),
+ /// The cc option.
+ Cc(GraphqlEmailValue),
+ /// The bcc option.
+ Bcc(GraphqlEmailValue),
+ /// The recipient option.
+ Recipient(GraphqlEmailValue),
+ /// The thread id option.
+ ThreadId(ID),
+ /// The owner option.
+ Owner(ID),
+ /// The project id option.
+ ProjectId(String),
+ /// The importance option.
+ Importance(bool),
+ /// The notification done option.
+ NotificationDone(bool),
+ /// The notification seen option.
+ NotificationSeen(bool),
+ /// The shared option.
+ Shared(GraphqlSharedEmailFilter),
+ /// The calendar only option.
+ CalendarOnly(bool),
+ /// The created at option.
+ CreatedAt(GraphqlDateLiteral),
+ /// The updated at option.
+ UpdatedAt(GraphqlDateLiteral),
+}
+
+impl IntoFilterExpr<EmailLiteral> for GraphqlEmailLiteral {
+ /// Convert this value into the expr representation.
+ fn into_expr(self) -> InputResult<Expr<EmailLiteral>> {
+ let literal = match self {
+ Self::Sender(value) => EmailLiteral::Sender(value.into_ast()?),
+ Self::Cc(value) => EmailLiteral::Cc(value.into_ast()?),
+ Self::Bcc(value) => EmailLiteral::Bcc(value.into_ast()?),
+ Self::Recipient(value) => EmailLiteral::Recipient(value.into_ast()?),
+ Self::ThreadId(id) => EmailLiteral::ThreadId(parse_id(id, "threadId")?),
+ Self::Owner(id) => EmailLiteral::Owner(parse_id(id, "owner")?),
+ Self::ProjectId(id) => EmailLiteral::ProjectId(id),
+ Self::Importance(importance) => EmailLiteral::Importance(importance),
+ Self::NotificationDone(done) => EmailLiteral::NotificationDone(done),
+ Self::NotificationSeen(seen) => EmailLiteral::NotificationSeen(seen),
+ Self::Shared(shared) => EmailLiteral::Shared(shared.into_model()),
+ Self::CalendarOnly(calendar_only) => EmailLiteral::CalendarOnly(calendar_only),
+ Self::CreatedAt(date) => EmailLiteral::CreatedAt(date.into_ast()?),
+ Self::UpdatedAt(date) => EmailLiteral::UpdatedAt(date.into_ast()?),
+ };
+ Ok(Expr::val(literal))
+ }
+}
+
+/// GraphQL input representing the email value.
+#[cfg_attr(feature = "server", derive(async_graphql::OneofObject))]
+#[derive(Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+enum GraphqlEmailValue {
+ /// The partial option.
+ Partial(String),
+ /// The complete option.
+ Complete(String),
+ /// The domain option.
+ Domain(String),
+}
+
+impl GraphqlEmailValue {
+ /// Convert this value into the ast representation.
+ fn into_ast(self) -> InputResult<Email> {
+ Ok(match self {
+ Self::Partial(value) => Email::Partial(value),
+ Self::Complete(value) => Email::Complete(
+ EmailStr::parse_from_str(&value)
+ .map(CowLike::into_owned)
+ .map_err(|err| {
+ InputError::new(format!("invalid complete email `{value}`: {err}"))
+ })?,
+ ),
+ Self::Domain(value) => Email::Domain(value),
+ })
+ }
+}
+
+/// GraphQL input representing the shared email filter.
+#[cfg_attr(feature = "server", derive(async_graphql::Enum))]
+#[derive(Copy, Clone, Eq, PartialEq, Serialize, Deserialize)]
+#[serde(rename_all = "SCREAMING_SNAKE_CASE")]
+enum GraphqlSharedEmailFilter {
+ /// The exclude option.
+ Exclude,
+ /// The include option.
+ Include,
+ /// The only option.
+ Only,
+}
+
+impl GraphqlSharedEmailFilter {
+ /// Convert this GraphQL option into the shared-email filter model.
+ fn into_model(self) -> SharedEmailFilter {
+ match self {
+ Self::Exclude => SharedEmailFilter::Exclude,
+ Self::Include => SharedEmailFilter::Include,
+ Self::Only => SharedEmailFilter::Only,
+ }
+ }
+}
+
+/// GraphQL input representing the channel literal.
+#[cfg_attr(feature = "server", derive(async_graphql::OneofObject))]
+#[derive(Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+enum GraphqlChannelLiteral {
+ /// The thread id option.
+ ThreadId(ID),
+ /// The mention option.
+ Mention(String),
+ /// The organization id option.
+ OrganizationId(i64),
+ /// The team id option.
+ TeamId(ID),
+ /// The channel id option.
+ ChannelId(ID),
+ /// The sender option.
+ Sender(String),
+ /// The channel type option.
+ ChannelType(GraphqlChannelTypeFilter),
+ /// The importance option.
+ Importance(bool),
+ /// The is participant option. Filters by whether the requesting user is an
+ /// active participant; its presence widens the candidate set to team channels
+ /// of the user's teams they have not joined.
+ IsParticipant(bool),
+ /// The notification done option.
+ NotificationDone(bool),
+ /// The notification seen option.
+ NotificationSeen(bool),
+}
+
+impl IntoFilterExpr<ChannelLiteral> for GraphqlChannelLiteral {
+ /// Convert this value into the expr representation.
+ fn into_expr(self) -> InputResult<Expr<ChannelLiteral>> {
+ let literal = match self {
+ Self::ThreadId(id) => ChannelLiteral::ThreadId(parse_id(id, "threadId")?),
+ Self::Mention(mention) => {
+ ChannelLiteral::Mention(parse_macro_user_id(mention, "mention")?)
+ }
+ Self::OrganizationId(id) => ChannelLiteral::OrganizationId(id),
+ Self::TeamId(id) => ChannelLiteral::TeamId(parse_id(id, "teamId")?),
+ Self::ChannelId(id) => ChannelLiteral::ChannelId(parse_id(id, "channelId")?),
+ Self::Sender(sender) => ChannelLiteral::Sender(parse_macro_user_id(sender, "sender")?),
+ Self::ChannelType(channel_type) => {
+ ChannelLiteral::ChannelType(channel_type.into_model())
+ }
+ Self::Importance(importance) => ChannelLiteral::Importance(importance),
+ Self::IsParticipant(is_participant) => ChannelLiteral::IsParticipant(is_participant),
+ Self::NotificationDone(done) => ChannelLiteral::NotificationDone(done),
+ Self::NotificationSeen(seen) => ChannelLiteral::NotificationSeen(seen),
+ };
+ Ok(Expr::val(literal))
+ }
+}
+
+/// GraphQL input representing the channel type filter.
+#[cfg_attr(feature = "server", derive(async_graphql::Enum))]
+#[derive(Copy, Clone, Eq, PartialEq, Serialize, Deserialize)]
+#[serde(rename_all = "SCREAMING_SNAKE_CASE")]
+enum GraphqlChannelTypeFilter {
+ /// The public option.
+ Public,
+ /// The private option.
+ Private,
+ /// The direct message option.
+ DirectMessage,
+ /// The team option.
+ Team,
+}
+
+impl GraphqlChannelTypeFilter {
+ /// Convert this GraphQL option into the channel-filter model.
+ fn into_model(self) -> ChannelTypeFilter {
+ match self {
+ Self::Public => ChannelTypeFilter::Public,
+ Self::Private => ChannelTypeFilter::Private,
+ Self::DirectMessage => ChannelTypeFilter::DirectMessage,
+ Self::Team => ChannelTypeFilter::Team,
+ }
+ }
+}
+
+/// GraphQL input representing the channel thread literal.
+#[cfg_attr(feature = "server", derive(async_graphql::OneofObject))]
+#[derive(Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+enum GraphqlChannelThreadLiteral {
+ /// The thread id option.
+ ThreadId(ID),
+ /// The channel id option.
+ ChannelId(ID),
+ /// The root sender option.
+ RootSender(String),
+ /// The participant option.
+ Participant(String),
+ /// The notification done option.
+ NotificationDone(bool),
+ /// The notification seen option.
+ NotificationSeen(bool),
+}
+
+impl IntoFilterExpr<ChannelThreadLiteral> for GraphqlChannelThreadLiteral {
+ /// Convert this value into the expr representation.
+ fn into_expr(self) -> InputResult<Expr<ChannelThreadLiteral>> {
+ let literal = match self {
+ Self::ThreadId(id) => ChannelThreadLiteral::ThreadId(parse_id(id, "threadId")?),
+ Self::ChannelId(id) => ChannelThreadLiteral::ChannelId(parse_id(id, "channelId")?),
+ Self::RootSender(sender) => {
+ ChannelThreadLiteral::RootSender(parse_macro_user_id(sender, "rootSender")?)
+ }
+ Self::Participant(participant) => {
+ ChannelThreadLiteral::Participant(parse_macro_user_id(participant, "participant")?)
+ }
+ Self::NotificationDone(done) => ChannelThreadLiteral::NotificationDone(done),
+ Self::NotificationSeen(seen) => ChannelThreadLiteral::NotificationSeen(seen),
+ };
+ Ok(Expr::val(literal))
+ }
+}
+
+/// GraphQL input representing the call literal.
+#[cfg_attr(feature = "server", derive(async_graphql::OneofObject))]
+#[derive(Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+enum GraphqlCallLiteral {
+ /// The call id option.
+ CallId(ID),
+ /// The channel id option.
+ ChannelId(ID),
+ /// The speaker option.
+ Speaker(String),
+ /// The status option.
+ Status(GraphqlCallStatus),
+ /// The attended option.
+ Attended(bool),
+}
+
+impl IntoFilterExpr<CallLiteral> for GraphqlCallLiteral {
+ /// Convert this value into the expr representation.
+ fn into_expr(self) -> InputResult<Expr<CallLiteral>> {
+ let literal = match self {
+ Self::CallId(id) => CallLiteral::CallId(parse_id(id, "callId")?),
+ Self::ChannelId(id) => CallLiteral::ChannelId(parse_id(id, "channelId")?),
+ Self::Speaker(speaker) => {
+ CallLiteral::Speaker(parse_macro_user_id(speaker, "speaker")?)
+ }
+ Self::Status(status) => CallLiteral::Status(status.into_model()),
+ Self::Attended(attended) => CallLiteral::Attended(attended),
+ };
+ Ok(Expr::val(literal))
+ }
+}
+
+/// GraphQL input representing the call status.
+#[cfg_attr(feature = "server", derive(async_graphql::Enum))]
+#[derive(Copy, Clone, Eq, PartialEq, Serialize, Deserialize)]
+#[serde(rename_all = "SCREAMING_SNAKE_CASE")]
+enum GraphqlCallStatus {
+ /// The attended option.
+ Attended,
+ /// The missed option.
+ Missed,
+ /// The unattended option.
+ Unattended,
+}
+
+impl GraphqlCallStatus {
+ /// Convert this GraphQL status into the call-filter model.
+ fn into_model(self) -> CallStatus {
+ match self {
+ Self::Attended => CallStatus::Attended,
+ Self::Missed => CallStatus::Missed,
+ Self::Unattended => CallStatus::Unattended,
+ }
+ }
+}
+
+/// GraphQL input representing the reminder literal.
+#[cfg_attr(feature = "server", derive(async_graphql::OneofObject))]
+#[derive(Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+enum GraphqlReminderLiteral {
+ /// Opt this query into reminders at all. Reminders are off by default, so
+ /// without this (or an `id`/`entity`) Soup omits them entirely — a filter
+ /// of only `completed` would otherwise silently match nothing. Must be
+ /// `true`; there is no literal for excluding reminders, that is the default.
+ Include(bool),
+ /// The id option.
+ Id(ID),
+ /// The referenced entity, as `"{type}:{id}"`.
+ Entity(String),
+ /// Whether the owner has marked the reminder done.
+ Completed(bool),
+ /// Whether the reminder has come due and is awaiting its owner.
+ Fired(bool),
+}
+
+impl IntoFilterExpr<ReminderLiteral> for GraphqlReminderLiteral {
+ /// Convert this value into the expr representation.
+ fn into_expr(self) -> InputResult<Expr<ReminderLiteral>> {
+ let literal = match self {
+ // `include: false` is the default, not a literal — accepting it
+ // would opt the query in, the opposite of what was asked.
+ Self::Include(false) => {
+ return Err(InputError::new(
+ "reminder `include` must be true; omit the filter to exclude reminders",
+ ));
+ }
+ Self::Include(true) => ReminderLiteral::Include,
+ Self::Id(id) => ReminderLiteral::Id(parse_id(id, "id")?),
+ Self::Entity(entity) => ReminderLiteral::Entity(entity),
+ Self::Completed(completed) => ReminderLiteral::Completed(completed),
+ Self::Fired(fired) => ReminderLiteral::Fired(fired),
+ };
+ Ok(Expr::val(literal))
+ }
+}
+
+/// GraphQL input representing the crm company literal.
+#[cfg_attr(feature = "server", derive(async_graphql::OneofObject))]
+#[derive(Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+enum GraphqlCrmCompanyLiteral {
+ /// The id option.
+ Id(ID),
+ /// The hidden option.
+ Hidden(bool),
+}
+
+impl IntoFilterExpr<CrmCompanyLiteral> for GraphqlCrmCompanyLiteral {
+ /// Convert this value into the expr representation.
+ fn into_expr(self) -> InputResult<Expr<CrmCompanyLiteral>> {
+ let literal = match self {
+ Self::Id(id) => CrmCompanyLiteral::Id(parse_id(id, "id")?),
+ Self::Hidden(hidden) => CrmCompanyLiteral::Hidden(hidden),
+ };
+ Ok(Expr::val(literal))
+ }
+}
+
+/// GraphQL input representing the foreign entity literal.
+#[cfg_attr(feature = "server", derive(async_graphql::OneofObject))]
+#[derive(Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+enum GraphqlForeignEntityLiteral {
+ /// The id option.
+ Id(ID),
+ /// The foreign entity id option.
+ ForeignEntityId(String),
+ /// The foreign entity source option.
+ ForeignEntitySource(String),
+ /// The includes me option.
+ IncludesMe(bool),
+ /// The notification done option.
+ NotificationDone(bool),
+ /// The notification seen option.
+ NotificationSeen(bool),
+}
+
+impl IntoFilterExpr<ForeignEntityLiteral> for GraphqlForeignEntityLiteral {
+ /// Convert this value into the expr representation.
+ fn into_expr(self) -> InputResult<Expr<ForeignEntityLiteral>> {
+ let literal = match self {
+ Self::Id(id) => ForeignEntityLiteral::Id(parse_id(id, "id")?),
+ Self::ForeignEntityId(id) => ForeignEntityLiteral::ForeignEntityId(id),
+ Self::ForeignEntitySource(source) => ForeignEntityLiteral::ForeignEntitySource(source),
+ Self::IncludesMe(true) => ForeignEntityLiteral::IncludesMe,
+ Self::IncludesMe(false) => {
+ return Err(InputError::new(
+ "ForeignEntityLiteral.includesMe must be true",
+ ));
+ }
+ Self::NotificationDone(done) => ForeignEntityLiteral::NotificationDone(done),
+ Self::NotificationSeen(seen) => ForeignEntityLiteral::NotificationSeen(seen),
+ };
+ Ok(Expr::val(literal))
+ }
+}
diff --git a/crates/graphql_soup_filter_input/src/test.rs b/crates/graphql_soup_filter_input/src/test.rs
new file mode 100644
index 0000000000..20fd14ceea
--- /dev/null
+++ b/crates/graphql_soup_filter_input/src/test.rs
@@ -0,0 +1,101 @@
+use filter_ast::Expr;
+use item_filters::ast::{chat::ChatLiteral, document::DocumentLiteral};
+use serde_json::{Value, json};
+
+use super::*;
+
+fn generated_filter_fixture() -> Value {
+ serde_json::from_str(include_str!("../fixtures/generated-soup-filter.json")).unwrap()
+}
+
+#[test]
+fn generated_typescript_variables_materialize_authoritative_ast() {
+ let ast = materialize_graphql_filter(generated_filter_fixture()).unwrap();
+
+ assert!(matches!(
+ ast.document_filter.as_deref(),
+ Some(Expr::And(left, right))
+ if matches!(left.as_ref(), Expr::Literal(DocumentLiteral::NotificationDone(false)))
+ && matches!(right.as_ref(), Expr::Literal(DocumentLiteral::UpdatedAt(_)))
+ ));
+ assert!(matches!(
+ ast.chat_filter.as_deref(),
+ Some(Expr::Not(expr))
+ if matches!(expr.as_ref(), Expr::Literal(ChatLiteral::Owner(_)))
+ ));
+ assert!(ast.email_filter.tree.is_some());
+}
+
+#[test]
+fn serde_and_graphql_entrypoints_materialize_identically() {
+ let value = generated_filter_fixture();
+ let from_json = materialize_graphql_filter(value.clone()).unwrap();
+ let input: GraphqlEntityFilterAst = serde_json::from_value(value).unwrap();
+ let from_graphql_type = input.into_ast().unwrap();
+
+ assert_eq!(
+ serde_json::to_value(from_json).unwrap(),
+ serde_json::to_value(from_graphql_type).unwrap()
+ );
+}
+
+#[test]
+fn rejects_rest_ast_shape() {
+ let error = materialize_graphql_filter(json!({
+ "df": { "l": { "id": "00000000-0000-0000-0000-000000000001" } }
+ }))
+ .unwrap_err();
+
+ assert!(matches!(error, MaterializeError::Shape(_)));
+}
+
+#[test]
+fn rejects_pathological_depth_before_materialization() {
+ let mut expression = json!({
+ "literal": { "id": "00000000-0000-0000-0000-000000000001" }
+ });
+ for _ in 0..MAX_FILTER_DEPTH {
+ expression = json!({ "not": expression });
+ }
+
+ let error = materialize_graphql_filter(json!({ "documentFilter": expression })).unwrap_err();
+ assert!(matches!(error, MaterializeError::Bounds(_)));
+}
+
+#[test]
+fn rejects_oversized_strings_before_domain_parsing() {
+ let error = materialize_graphql_filter(json!({
+ "documentFilter": {
+ "literal": { "owner": "x".repeat(MAX_FILTER_STRING_BYTES + 1) }
+ }
+ }))
+ .unwrap_err();
+
+ assert!(matches!(error, MaterializeError::Bounds(_)));
+}
+
+#[test]
+fn property_entity_type_conversion_rejects_unsupported_variants() {
+ let property_filter = |entity_type| {
+ json!({
+ "propertiesFilter": {
+ "literal": {
+ "propertyDefinitionId": "00000000-0000-0000-0000-000000000001",
+ "entityType": entity_type,
+ "value": {
+ "entityRef": "00000000-0000-0000-0000-000000000002"
+ }
+ }
+ }
+ })
+ };
+
+ let error = materialize_graphql_filter(property_filter(json!("CALL_RECORD"))).unwrap_err();
+ assert!(matches!(error, MaterializeError::Conversion(_)));
+
+ let ast = materialize_graphql_filter(property_filter(Value::Null)).unwrap();
+ let Some(Expr::Literal(literal)) = ast.properties_filter.as_deref() else {
+ panic!("expected property literal")
+ };
+ assert!(literal.entity_type.is_none());
+}
diff --git a/crates/item_filter_index/Cargo.toml b/crates/item_filter_index/Cargo.toml
new file mode 100644
index 0000000000..cc6dbbeb26
--- /dev/null
+++ b/crates/item_filter_index/Cargo.toml
@@ -0,0 +1,18 @@
+[package]
+edition = "2024"
+name = "item-filter-index"
+publish = false
+version = "0.1.0"
+
+[dependencies]
+filter_ast = { path = "../filter_ast" }
+item_filters = { path = "../item_filters", default-features = false }
+predicate-index = { path = "../predicate_index" }
+thiserror = { workspace = true }
+uuid = { workspace = true }
+
+[target.'cfg(target_arch = "wasm32")'.dependencies]
+uuid = { workspace = true, features = ["js"] }
+
+[dev-dependencies]
+chrono = { workspace = true }
diff --git a/crates/item_filter_index/src/lib.rs b/crates/item_filter_index/src/lib.rs
new file mode 100644
index 0000000000..b1055e07aa
--- /dev/null
+++ b/crates/item_filter_index/src/lib.rs
@@ -0,0 +1,440 @@
+//! `soup-flat-v1` eligibility and compilation into the generic predicate IR.
+#![deny(missing_docs)]
+
+use filter_ast::Expr;
+use item_filters::ast::{
+ EntityFilterAst,
+ calendar_event::CalendarEventLiteral,
+ call::CallLiteral,
+ channel::{ChannelLiteral, ChannelThreadLiteral},
+ chat::ChatLiteral,
+ crm_company::CrmCompanyLiteral,
+ date::DateLiteral,
+ document::DocumentLiteral,
+ email::EmailLiteral,
+ foreign_entity::ForeignEntityLiteral,
+ project::ProjectLiteral,
+};
+use predicate_index::{
+ ExactValue, IndexQuery, PartitionPredicate, PredicateExpr, RangeBound, SortDirection, Token,
+ ValidatedIndexQuery, ValidationError, utc_timestamp_micros,
+};
+use thiserror::Error;
+use uuid::Uuid;
+
+#[cfg(test)]
+mod test;
+
+/// Stable profile name.
+pub const SOUP_FLAT_V1: &str = "soup-flat-v1";
+
+/// Opaque vocabulary shared with direct Soup projection generation.
+pub mod vocabulary {
+ use predicate_index::{Profile, Token};
+
+ use crate::SOUP_FLAT_V1;
+
+ fn token(value: &str) -> Token {
+ Token::new(value).expect("static item-filter-index token is valid")
+ }
+
+ /// `soup-flat-v1` profile.
+ pub fn profile() -> Profile {
+ Profile::new(token(SOUP_FLAT_V1))
+ }
+
+ /// Document partition.
+ pub fn document_partition() -> Token {
+ token("document")
+ }
+
+ /// Project partition.
+ pub fn project_partition() -> Token {
+ token("project")
+ }
+
+ /// Chat partition.
+ pub fn chat_partition() -> Token {
+ token("chat")
+ }
+
+ /// Record identity attribute.
+ pub fn id() -> Token {
+ token("id")
+ }
+
+ /// Parent/project attribute.
+ pub fn project_id() -> Token {
+ token("project-id")
+ }
+
+ /// Owner attribute.
+ pub fn owner() -> Token {
+ token("owner")
+ }
+
+ /// Document file-type attribute.
+ pub fn file_type() -> Token {
+ token("file-type")
+ }
+
+ /// Creation timestamp and sort attribute.
+ pub fn created_at() -> Token {
+ token("created-at")
+ }
+
+ /// Update timestamp and sort attribute.
+ pub fn updated_at() -> Token {
+ token("updated-at")
+ }
+}
+
+/// Sort methods understood by the local support profile.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum SoupIndexSort {
+ /// Creation timestamp.
+ CreatedAt,
+ /// Update timestamp.
+ UpdatedAt,
+ /// A server sort not supported by `soup-flat-v1`.
+ Unsupported,
+}
+
+/// Complete request options relevant to local eligibility.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct SoupFlatRequest {
+ /// Requested sort.
+ pub sort: SoupIndexSort,
+ /// Requested sort direction.
+ pub direction: SortDirection,
+ /// Initial-page limit.
+ pub limit: u16,
+ /// Whether the request is a continuation.
+ pub has_cursor: bool,
+}
+
+/// Why a well-formed request must use the authoritative network path.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum UnsupportedReason {
+ /// The request includes or fails to exclude a deferred entity partition.
+ Partition(&'static str),
+ /// A supported partition contains a deferred literal.
+ Literal(&'static str),
+ /// A global property predicate is present.
+ GlobalProperties,
+ /// The requested sort is not indexed.
+ Sort,
+ /// Local continuation cursors are not supported.
+ Cursor,
+}
+
+/// Eligibility outcome before compilation.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Eligibility {
+ /// Every request component is supported.
+ Supported,
+ /// The complete request must fall back.
+ Unsupported(UnsupportedReason),
+}
+
+/// Typed compiler outcome used by browser composition.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum LocalCompileOutcome {
+ /// Complete validated generic query.
+ Supported(ValidatedIndexQuery),
+ /// The complete request must use the network path.
+ Unsupported(UnsupportedReason),
+}
+
+/// Malformed or oversized input that cannot be compiled.
+#[derive(Debug, Error, PartialEq, Eq)]
+pub enum CompileError {
+ /// Generic IR validation failed.
+ #[error(transparent)]
+ Validation(#[from] ValidationError),
+}
+
+/// Check the complete materialized forest and request options without compiling leaves.
+pub fn check_soup_flat_v1(ast: &EntityFilterAst, request: SoupFlatRequest) -> Eligibility {
+ if request.has_cursor {
+ return Eligibility::Unsupported(UnsupportedReason::Cursor);
+ }
+ if request.sort == SoupIndexSort::Unsupported {
+ return Eligibility::Unsupported(UnsupportedReason::Sort);
+ }
+ if ast.properties_filter.is_some() {
+ return Eligibility::Unsupported(UnsupportedReason::GlobalProperties);
+ }
+
+ for result in [
+ unsupported_partition(
+ ast.calendar_event_filter.as_deref(),
+ "calendarEvent",
+ |literal| matches!(literal, CalendarEventLiteral::Id(id) if id.is_nil()),
+ ),
+ unsupported_partition(
+ ast.email_filter.tree.as_deref(),
+ "email",
+ |literal| matches!(literal, EmailLiteral::ThreadId(id) if id.is_nil()),
+ ),
+ if ast.email_filter.crm_scope.is_some() {
+ Err(UnsupportedReason::Partition("email"))
+ } else {
+ Ok(())
+ },
+ unsupported_partition(
+ ast.channel_filter.as_deref(),
+ "channel",
+ |literal| matches!(literal, ChannelLiteral::ChannelId(id) if id.is_nil()),
+ ),
+ unsupported_partition(
+ ast.channel_thread_filter.as_deref(),
+ "channelThread",
+ |literal| matches!(literal, ChannelThreadLiteral::ThreadId(id) if id.is_nil()),
+ ),
+ unsupported_partition(
+ ast.call_filter.as_deref(),
+ "call",
+ |literal| matches!(literal, CallLiteral::CallId(id) if id.is_nil()),
+ ),
+ unsupported_partition(
+ ast.crm_company_filter.as_deref(),
+ "crmCompany",
+ |literal| matches!(literal, CrmCompanyLiteral::Id(id) if id.is_nil()),
+ ),
+ unsupported_partition(
+ ast.foreign_entity_filter.as_deref(),
+ "foreignEntity",
+ |literal| matches!(literal, ForeignEntityLiteral::Id(id) if id.is_nil()),
+ ),
+ ] {
+ if let Err(reason) = result {
+ return Eligibility::Unsupported(reason);
+ }
+ }
+
+ // Reminders are uniquely excluded by Soup when their tree is omitted.
+ if ast.reminder_filter.is_some() {
+ return Eligibility::Unsupported(UnsupportedReason::Partition("reminder"));
+ }
+
+ if !supported_expr(ast.document_filter.as_deref(), supported_document_literal) {
+ return Eligibility::Unsupported(UnsupportedReason::Literal("document"));
+ }
+ if !supported_expr(ast.project_filter.as_deref(), supported_project_literal) {
+ return Eligibility::Unsupported(UnsupportedReason::Literal("project"));
+ }
+ if !supported_expr(ast.chat_filter.as_deref(), supported_chat_literal) {
+ return Eligibility::Unsupported(UnsupportedReason::Literal("chat"));
+ }
+
+ Eligibility::Supported
+}
+
+/// Compile a request only after complete-profile eligibility succeeds.
+pub fn compile_soup_flat_v1(
+ ast: &EntityFilterAst,
+ request: SoupFlatRequest,
+) -> Result<LocalCompileOutcome, CompileError> {
+ if let Eligibility::Unsupported(reason) = check_soup_flat_v1(ast, request) {
+ return Ok(LocalCompileOutcome::Unsupported(reason));
+ }
+
+ let sort_attribute = match request.sort {
+ SoupIndexSort::CreatedAt => vocabulary::created_at(),
+ SoupIndexSort::UpdatedAt => vocabulary::updated_at(),
+ SoupIndexSort::Unsupported => unreachable!("eligibility checked sort"),
+ };
+ let query = IndexQuery {
+ profile: vocabulary::profile(),
+ partitions: vec![
+ PartitionPredicate {
+ partition: vocabulary::document_partition(),
+ predicate: compile_expr(ast.document_filter.as_deref(), compile_document_literal)?,
+ },
+ PartitionPredicate {
+ partition: vocabulary::project_partition(),
+ predicate: compile_expr(ast.project_filter.as_deref(), compile_project_literal)?,
+ },
+ PartitionPredicate {
+ partition: vocabulary::chat_partition(),
+ predicate: compile_expr(ast.chat_filter.as_deref(), compile_chat_literal)?,
+ },
+ ],
+ sort_attribute,
+ sort_direction: request.direction,
+ tie_break_direction: request.direction,
+ limit: request.limit,
+ };
+
+ Ok(LocalCompileOutcome::Supported(ValidatedIndexQuery::new(
+ query,
+ )?))
+}
+
+fn unsupported_partition<T>(
+ expr: Option<&Expr<T>>,
+ name: &'static str,
+ is_positive_nil_id: impl Fn(&T) -> bool + Copy,
+) -> Result<(), UnsupportedReason> {
+ match expr {
+ Some(expr) if proves_none(expr, is_positive_nil_id) => Ok(()),
+ Some(_) | None => Err(UnsupportedReason::Partition(name)),
+ }
+}
+
+fn proves_none<T>(expr: &Expr<T>, is_positive_nil_id: impl Fn(&T) -> bool + Copy) -> bool {
+ match expr {
+ Expr::Literal(literal) => is_positive_nil_id(literal),
+ Expr::And(left, right) => {
+ proves_none(left, is_positive_nil_id) || proves_none(right, is_positive_nil_id)
+ }
+ Expr::Or(_, _) | Expr::Not(_) => false,
+ }
+}
+
+fn supported_expr<T>(expr: Option<&Expr<T>>, supported: impl Fn(&T) -> bool + Copy) -> bool {
+ match expr {
+ None => true,
+ Some(Expr::Literal(literal)) => supported(literal),
+ Some(Expr::And(left, right) | Expr::Or(left, right)) => {
+ supported_expr(Some(left), supported) && supported_expr(Some(right), supported)
+ }
+ Some(Expr::Not(expr)) => supported_expr(Some(expr), supported),
+ }
+}
+
+fn supported_document_literal(literal: &DocumentLiteral) -> bool {
+ matches!(
+ literal,
+ DocumentLiteral::Id(_)
+ | DocumentLiteral::FileType(_)
+ | DocumentLiteral::ProjectId(_)
+ | DocumentLiteral::Owner(_)
+ | DocumentLiteral::CreatedAt(_)
+ | DocumentLiteral::UpdatedAt(_)
+ )
+}
+
+fn supported_project_literal(literal: &ProjectLiteral) -> bool {
+ matches!(
+ literal,
+ ProjectLiteral::ProjectId(_)
+ | ProjectLiteral::ProjectIdSelf(_)
+ | ProjectLiteral::Owner(_)
+ | ProjectLiteral::CreatedAt(_)
+ | ProjectLiteral::UpdatedAt(_)
+ )
+}
+
+fn supported_chat_literal(literal: &ChatLiteral) -> bool {
+ matches!(
+ literal,
+ ChatLiteral::ChatId(_)
+ | ChatLiteral::ProjectId(_)
+ | ChatLiteral::Owner(_)
+ | ChatLiteral::CreatedAt(_)
+ | ChatLiteral::UpdatedAt(_)
+ )
+}
+
+fn compile_expr<T>(
+ expr: Option<&Expr<T>>,
+ literal: impl Fn(&T) -> Result<PredicateExpr, CompileError> + Copy,
+) -> Result<PredicateExpr, CompileError> {
+ Ok(match expr {
+ None => PredicateExpr::All,
+ Some(Expr::Literal(value)) => literal(value)?,
+ Some(Expr::And(left, right)) => PredicateExpr::And(
+ Box::new(compile_expr(Some(left), literal)?),
+ Box::new(compile_expr(Some(right), literal)?),
+ ),
+ Some(Expr::Or(left, right)) => PredicateExpr::Or(
+ Box::new(compile_expr(Some(left), literal)?),
+ Box::new(compile_expr(Some(right), literal)?),
+ ),
+ Some(Expr::Not(expr)) => PredicateExpr::Not(Box::new(compile_expr(Some(expr), literal)?)),
+ })
+}
+
+fn compile_document_literal(literal: &DocumentLiteral) -> Result<PredicateExpr, CompileError> {
+ Ok(match literal {
+ DocumentLiteral::Id(id) => exact_uuid(vocabulary::id(), id),
+ DocumentLiteral::FileType(file_type) => {
+ return exact_utf8(vocabulary::file_type(), file_type.to_string());
+ }
+ DocumentLiteral::ProjectId(id) => exact_uuid(vocabulary::project_id(), id),
+ DocumentLiteral::Owner(owner) => {
+ return exact_utf8(vocabulary::owner(), owner.to_string());
+ }
+ DocumentLiteral::CreatedAt(date) => date_expr(vocabulary::created_at(), date),
+ DocumentLiteral::UpdatedAt(date) => date_expr(vocabulary::updated_at(), date),
+ _ => unreachable!("eligibility checked document literal"),
+ })
+}
+
+fn compile_project_literal(literal: &ProjectLiteral) -> Result<PredicateExpr, CompileError> {
+ Ok(match literal {
+ ProjectLiteral::ProjectId(id) => exact_uuid(vocabulary::project_id(), id),
+ ProjectLiteral::ProjectIdSelf(id) => exact_uuid(vocabulary::id(), id),
+ ProjectLiteral::Owner(owner) => {
+ return exact_utf8(vocabulary::owner(), owner.to_string());
+ }
+ ProjectLiteral::CreatedAt(date) => date_expr(vocabulary::created_at(), date),
+ ProjectLiteral::UpdatedAt(date) => date_expr(vocabulary::updated_at(), date),
+ _ => unreachable!("eligibility checked project literal"),
+ })
+}
+
+fn compile_chat_literal(literal: &ChatLiteral) -> Result<PredicateExpr, CompileError> {
+ Ok(match literal {
+ ChatLiteral::ChatId(id) => exact_uuid(vocabulary::id(), id),
+ ChatLiteral::ProjectId(id) => exact_uuid(vocabulary::project_id(), id),
+ ChatLiteral::Owner(owner) => {
+ return exact_utf8(vocabulary::owner(), owner.to_string());
+ }
+ ChatLiteral::CreatedAt(date) => date_expr(vocabulary::created_at(), date),
+ ChatLiteral::UpdatedAt(date) => date_expr(vocabulary::updated_at(), date),
+ _ => unreachable!("eligibility checked chat literal"),
+ })
+}
+
+fn exact_uuid(attribute: Token, value: &Uuid) -> PredicateExpr {
+ PredicateExpr::Exact {
+ attribute,
+ value: ExactValue::new(value.as_bytes()).expect("UUID exact value is bounded"),
+ }
+}
+
+fn exact_utf8(attribute: Token, value: impl AsRef<str>) -> Result<PredicateExpr, CompileError> {
+ Ok(PredicateExpr::Exact {
+ attribute,
+ value: ExactValue::utf8(value)?,
+ })
+}
+
+fn date_expr(attribute: Token, date: &DateLiteral) -> PredicateExpr {
+ let (lower, upper) = match date {
+ DateLiteral::GreaterThan(value) => (
+ Some(RangeBound::Exclusive(utc_timestamp_micros(*value))),
+ None,
+ ),
+ DateLiteral::LessThan(value) => (
+ None,
+ Some(RangeBound::Exclusive(utc_timestamp_micros(*value))),
+ ),
+ DateLiteral::GreaterThanOrEqual(value) => (
+ Some(RangeBound::Inclusive(utc_timestamp_micros(*value))),
+ None,
+ ),
+ DateLiteral::LessThanOrEqual(value) => (
+ None,
+ Some(RangeBound::Inclusive(utc_timestamp_micros(*value))),
+ ),
+ };
+ PredicateExpr::I64Range {
+ attribute,
+ lower,
+ upper,
+ }
+}
diff --git a/crates/item_filter_index/src/test.rs b/crates/item_filter_index/src/test.rs
new file mode 100644
index 0000000000..f548321f08
--- /dev/null
+++ b/crates/item_filter_index/src/test.rs
@@ -0,0 +1,212 @@
+use std::sync::Arc;
+
+use filter_ast::Expr;
+use item_filters::ast::{
+ CrmScope, EntityFilterAst,
+ calendar_event::CalendarEventLiteral,
+ call::CallLiteral,
+ channel::{ChannelLiteral, ChannelThreadLiteral},
+ crm_company::CrmCompanyLiteral,
+ date::DateLiteral,
+ document::DocumentLiteral,
+ email::EmailLiteral,
+ foreign_entity::ForeignEntityLiteral,
+ properties::{PropertiesLiteral, PropertyMatchValue},
+};
+use predicate_index::{PredicateExpr, RangeBound};
+
+use super::*;
+
+fn request() -> SoupFlatRequest {
+ SoupFlatRequest {
+ sort: SoupIndexSort::UpdatedAt,
+ direction: SortDirection::Desc,
+ limit: 20,
+ has_cursor: false,
+ }
+}
+
+fn excluded_deferred_partitions() -> EntityFilterAst {
+ let mut ast = EntityFilterAst::default();
+ ast.calendar_event_filter = Some(Arc::new(Expr::val(CalendarEventLiteral::Id(Uuid::nil()))));
+ ast.email_filter.tree = Some(Arc::new(Expr::val(EmailLiteral::ThreadId(Uuid::nil()))));
+ ast.channel_filter = Some(Arc::new(Expr::val(ChannelLiteral::ChannelId(Uuid::nil()))));
+ ast.channel_thread_filter = Some(Arc::new(Expr::val(ChannelThreadLiteral::ThreadId(
+ Uuid::nil(),
+ ))));
+ ast.call_filter = Some(Arc::new(Expr::val(CallLiteral::CallId(Uuid::nil()))));
+ ast.crm_company_filter = Some(Arc::new(Expr::val(CrmCompanyLiteral::Id(Uuid::nil()))));
+ ast.foreign_entity_filter = Some(Arc::new(Expr::val(ForeignEntityLiteral::Id(Uuid::nil()))));
+ ast
+}
+
+#[test]
+fn compiles_complete_supported_forest_after_eligibility() {
+ let id = Uuid::from_u128(1);
+ let timestamp = chrono::DateTime::parse_from_rfc3339("2026-01-01T00:00:00.123456Z")
+ .unwrap()
+ .to_utc();
+ let mut ast = excluded_deferred_partitions();
+ ast.document_filter = Some(Arc::new(Expr::and(
+ Expr::val(DocumentLiteral::Id(id)),
+ Expr::is_not(Expr::val(DocumentLiteral::UpdatedAt(
+ DateLiteral::LessThan(timestamp),
+ ))),
+ )));
+
+ let LocalCompileOutcome::Supported(query) = compile_soup_flat_v1(&ast, request()).unwrap()
+ else {
+ panic!("supported request fell back")
+ };
+ let document = &query.as_query().partitions[0].predicate;
+ assert!(matches!(
+ document,
+ PredicateExpr::And(left, right)
+ if matches!(left.as_ref(), PredicateExpr::Exact { attribute, value }
+ if attribute == &vocabulary::id() && value.as_bytes() == id.as_bytes())
+ && matches!(right.as_ref(), PredicateExpr::Not(expr)
+ if matches!(expr.as_ref(), PredicateExpr::I64Range {
+ attribute,
+ lower: None,
+ upper: Some(RangeBound::Exclusive(_)),
+ } if attribute == &vocabulary::updated_at()))
+ ));
+}
+
+#[test]
+fn unsupported_supported_partition_literals_never_disappear() {
+ for expression in [
+ Expr::and(
+ Expr::val(DocumentLiteral::Id(Uuid::nil())),
+ Expr::val(DocumentLiteral::Importance(true)),
+ ),
+ Expr::or(
+ Expr::val(DocumentLiteral::Id(Uuid::nil())),
+ Expr::val(DocumentLiteral::Importance(true)),
+ ),
+ Expr::is_not(Expr::val(DocumentLiteral::Importance(true))),
+ ] {
+ let mut ast = excluded_deferred_partitions();
+ ast.document_filter = Some(Arc::new(expression));
+ assert_eq!(
+ compile_soup_flat_v1(&ast, request()).unwrap(),
+ LocalCompileOutcome::Unsupported(UnsupportedReason::Literal("document"))
+ );
+ }
+}
+
+#[test]
+fn unsupported_partition_is_empty_only_for_conservative_positive_nil_shapes() {
+ let unsupported = Expr::val(ChannelLiteral::Importance(true));
+ for (expression, supported) in [
+ (
+ Expr::and(
+ Expr::val(ChannelLiteral::ChannelId(Uuid::nil())),
+ unsupported.clone(),
+ ),
+ true,
+ ),
+ (
+ Expr::or(
+ Expr::val(ChannelLiteral::ChannelId(Uuid::nil())),
+ unsupported.clone(),
+ ),
+ false,
+ ),
+ (
+ Expr::is_not(Expr::val(ChannelLiteral::ChannelId(Uuid::nil()))),
+ false,
+ ),
+ ] {
+ let mut ast = excluded_deferred_partitions();
+ ast.channel_filter = Some(Arc::new(expression));
+ assert_eq!(
+ check_soup_flat_v1(&ast, request()),
+ if supported {
+ Eligibility::Supported
+ } else {
+ Eligibility::Unsupported(UnsupportedReason::Partition("channel"))
+ }
+ );
+ }
+}
+
+#[test]
+fn every_deferred_partition_must_be_proven_empty() {
+ let mut ast = excluded_deferred_partitions();
+ ast.call_filter = None;
+ assert_eq!(
+ check_soup_flat_v1(&ast, request()),
+ Eligibility::Unsupported(UnsupportedReason::Partition("call"))
+ );
+
+ let mut ast = excluded_deferred_partitions();
+ ast.reminder_filter = Some(Arc::new(Expr::val(
+ item_filters::ast::reminder::ReminderLiteral::Include,
+ )));
+ assert_eq!(
+ check_soup_flat_v1(&ast, request()),
+ Eligibility::Unsupported(UnsupportedReason::Partition("reminder"))
+ );
+
+ let mut ast = excluded_deferred_partitions();
+ ast.properties_filter = Some(Arc::new(Expr::val(PropertiesLiteral {
+ property_definition_id: Uuid::nil(),
+ entity_type: None,
+ value: PropertyMatchValue::SelectOption(Uuid::nil()),
+ })));
+ assert_eq!(
+ check_soup_flat_v1(&ast, request()),
+ Eligibility::Unsupported(UnsupportedReason::GlobalProperties)
+ );
+
+ let mut ast = excluded_deferred_partitions();
+ ast.email_filter.tree = None;
+ ast.email_filter.crm_scope = Some(CrmScope::Domains(vec!["example.com".to_owned()]));
+ assert_eq!(
+ check_soup_flat_v1(&ast, request()),
+ Eligibility::Unsupported(UnsupportedReason::Partition("email"))
+ );
+}
+
+#[test]
+fn unsupported_options_fail_before_generic_compilation() {
+ let ast = excluded_deferred_partitions();
+ assert_eq!(
+ compile_soup_flat_v1(
+ &ast,
+ SoupFlatRequest {
+ sort: SoupIndexSort::Unsupported,
+ ..request()
+ }
+ )
+ .unwrap(),
+ LocalCompileOutcome::Unsupported(UnsupportedReason::Sort)
+ );
+ assert_eq!(
+ compile_soup_flat_v1(
+ &ast,
+ SoupFlatRequest {
+ has_cursor: true,
+ ..request()
+ }
+ )
+ .unwrap(),
+ LocalCompileOutcome::Unsupported(UnsupportedReason::Cursor)
+ );
+}
+
+#[test]
+fn invalid_limit_is_a_validation_error_not_unsupported() {
+ let ast = excluded_deferred_partitions();
+ assert_eq!(
+ compile_soup_flat_v1(
+ &ast,
+ SoupFlatRequest {
+ limit: 0,
+ ..request()
+ }
+ ),
+ Err(CompileError::Validation(ValidationError::Limit(0)))
+ );
+}
diff --git a/crates/item_filters/Cargo.toml b/crates/item_filters/Cargo.toml
index b11302eb7c..98fd27de68 100644
--- a/crates/item_filters/Cargo.toml
+++ b/crates/item_filters/Cargo.toml
@@ -5,12 +5,14 @@ publish = false
version = "0.1.0"
[features]
+default = ["native"]
mock = []
+native = ["document_sub_type/default"]
schema = ["dep:schemars", "dep:utoipa"]
[dependencies]
chrono = { workspace = true }
-document_sub_type = { path = "../document_sub_type" }
+document_sub_type = { path = "../document_sub_type", default-features = false }
either = { workspace = true }
filter_ast = { path = "../filter_ast" }
macro_user_id = { path = "../macro_user_id" }
@@ -25,7 +27,6 @@ strum = { workspace = true }
thiserror = { workspace = true }
utoipa = { workspace = true, optional = true }
uuid = { workspace = true }
-workspace-hack = { version = "0.1", path = "../workspace-hack" }
[dev-dependencies]
cool_asserts = "2.0.3"
diff --git a/crates/model_file_type/Cargo.toml b/crates/model_file_type/Cargo.toml
index d5a764ebb0..55bbe32fb9 100644
--- a/crates/model_file_type/Cargo.toml
+++ b/crates/model_file_type/Cargo.toml
@@ -17,4 +17,3 @@ serde_json = { workspace = true }
strum = { workspace = true }
thiserror = { workspace = true }
utoipa = { workspace = true, optional = true }
-workspace-hack = { version = "0.1", path = "../workspace-hack" }
diff --git a/crates/predicate_index/Cargo.toml b/crates/predicate_index/Cargo.toml
new file mode 100644
index 0000000000..dab3b94c31
--- /dev/null
+++ b/crates/predicate_index/Cargo.toml
@@ -0,0 +1,13 @@
+[package]
+edition = "2024"
+name = "predicate-index"
+publish = false
+version = "0.1.0"
+
+[dependencies]
+chrono = { workspace = true }
+serde = { workspace = true }
+thiserror = { workspace = true }
+
+[dev-dependencies]
+serde_json = { workspace = true }
diff --git a/crates/predicate_index/src/lib.rs b/crates/predicate_index/src/lib.rs
new file mode 100644
index 0000000000..adf8eb0b43
--- /dev/null
+++ b/crates/predicate_index/src/lib.rs
@@ -0,0 +1,734 @@
+//! Minimal storage-neutral predicate-index intermediate representation.
+#![deny(missing_docs)]
+
+use std::{cmp::Ordering, collections::HashSet};
+
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Deserializer, Serialize};
+use thiserror::Error;
+
+#[cfg(test)]
+mod test;
+
+/// Maximum expression depth accepted by the generic index.
+pub const MAX_EXPRESSION_DEPTH: usize = 64;
+/// Maximum expression nodes accepted by one query.
+pub const MAX_EXPRESSION_NODES: usize = 2_048;
+/// Maximum query page size.
+pub const MAX_QUERY_LIMIT: u16 = 500;
+/// Maximum bytes in a token.
+pub const MAX_TOKEN_BYTES: usize = 128;
+/// Maximum bytes in an exact value.
+pub const MAX_EXACT_VALUE_BYTES: usize = 16 * 1_024;
+/// Maximum facts in one index document.
+pub const MAX_FACTS_PER_DOCUMENT: usize = 256;
+/// Maximum distinct records whose optimistic projections may be merged into one query.
+pub const MAX_OPTIMISTIC_RECORDS_PER_QUERY: usize = 128;
+
+/// A stable, opaque vocabulary token owned by a profile compiler.
+#[derive(Debug, Clone, PartialEq, Eq, Hash, PartialOrd, Ord, Serialize)]
+#[serde(transparent)]
+pub struct Token(String);
+
+impl<'de> Deserialize<'de> for Token {
+ fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
+ Self::new(String::deserialize(deserializer)?).map_err(serde::de::Error::custom)
+ }
+}
+
+impl Token {
+ /// Construct a validated token.
+ pub fn new(value: impl Into<String>) -> Result<Self, ValidationError> {
+ let value = value.into();
+ let valid_bytes = !value.is_empty()
+ && value.len() <= MAX_TOKEN_BYTES
+ && value
+ .bytes()
+ .all(|byte| byte.is_ascii_alphanumeric() || b"._:-".contains(&byte));
+ if !valid_bytes {
+ return Err(ValidationError::InvalidToken(value));
+ }
+ Ok(Self(value))
+ }
+
+ /// Read the token text.
+ pub fn as_str(&self) -> &str {
+ &self.0
+ }
+}
+
+/// A versioned projection and compiler profile.
+#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
+#[serde(transparent)]
+pub struct Profile(Token);
+
+impl Profile {
+ /// Construct a profile from a validated token.
+ pub fn new(token: Token) -> Self {
+ Self(token)
+ }
+
+ /// Read the profile token.
+ pub fn token(&self) -> &Token {
+ &self.0
+ }
+}
+
+/// A normalized GraphQL cache record key.
+#[derive(Debug, Clone, PartialEq, Eq, Hash, PartialOrd, Ord, Serialize)]
+#[serde(transparent)]
+pub struct RecordKey(String);
+
+impl<'de> Deserialize<'de> for RecordKey {
+ fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
+ Self::new(String::deserialize(deserializer)?).map_err(serde::de::Error::custom)
+ }
+}
+
+impl RecordKey {
+ /// Construct a non-empty bounded normalized record key.
+ pub fn new(value: impl Into<String>) -> Result<Self, ValidationError> {
+ let value = value.into();
+ if value.is_empty() || value.len() > MAX_EXACT_VALUE_BYTES {
+ return Err(ValidationError::InvalidRecordKey);
+ }
+ Ok(Self(value))
+ }
+
+ /// Read the normalized key.
+ pub fn as_str(&self) -> &str {
+ &self.0
+ }
+}
+
+/// Canonical bytes for an exact-match posting value.
+#[derive(Debug, Clone, PartialEq, Eq, Hash, PartialOrd, Ord, Serialize)]
+#[serde(transparent)]
+pub struct ExactValue(Vec<u8>);
+
+impl<'de> Deserialize<'de> for ExactValue {
+ fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
+ Self::new(Vec::<u8>::deserialize(deserializer)?).map_err(serde::de::Error::custom)
+ }
+}
+
+impl ExactValue {
+ /// Construct a bounded exact value.
+ pub fn new(bytes: impl Into<Vec<u8>>) -> Result<Self, ValidationError> {
+ let bytes = bytes.into();
+ if bytes.len() > MAX_EXACT_VALUE_BYTES {
+ return Err(ValidationError::ExactValueTooLarge(bytes.len()));
+ }
+ Ok(Self(bytes))
+ }
+
+ /// Construct a canonical UTF-8 value.
+ pub fn utf8(value: impl AsRef<str>) -> Result<Self, ValidationError> {
+ Self::new(value.as_ref().as_bytes())
+ }
+
+ /// Read the canonical bytes.
+ pub fn as_bytes(&self) -> &[u8] {
+ &self.0
+ }
+}
+
+/// One side of an integer range.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub enum RangeBound {
+ /// Include the bound value.
+ Inclusive(i64),
+ /// Exclude the bound value.
+ Exclusive(i64),
+}
+
+/// A bounded Boolean predicate over generic facts.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub enum PredicateExpr {
+ /// Match every document in the selected profile/partition universe.
+ All,
+ /// Match no documents.
+ None,
+ /// Match an exact posting.
+ Exact {
+ /// Fact vocabulary token.
+ attribute: Token,
+ /// Canonical exact value.
+ value: ExactValue,
+ },
+ /// Match an ordered integer range.
+ I64Range {
+ /// Fact vocabulary token.
+ attribute: Token,
+ /// Optional lower bound.
+ lower: Option<RangeBound>,
+ /// Optional upper bound.
+ upper: Option<RangeBound>,
+ },
+ /// Intersect two result sets.
+ And(Box<Self>, Box<Self>),
+ /// Union two result sets.
+ Or(Box<Self>, Box<Self>),
+ /// Subtract a result set from the profile/partition universe.
+ Not(Box<Self>),
+}
+
+impl PredicateExpr {
+ /// Validate bounds and apply non-expanding Boolean identities.
+ pub fn validate_and_simplify(self) -> Result<Self, ValidationError> {
+ let mut stack = vec![(&self, 1usize)];
+ let mut nodes = 0usize;
+ while let Some((expr, depth)) = stack.pop() {
+ if depth > MAX_EXPRESSION_DEPTH {
+ return Err(ValidationError::ExpressionDepth);
+ }
+ nodes += 1;
+ if nodes > MAX_EXPRESSION_NODES {
+ return Err(ValidationError::ExpressionNodes);
+ }
+ match expr {
+ Self::And(left, right) | Self::Or(left, right) => {
+ stack.push((left, depth + 1));
+ stack.push((right, depth + 1));
+ }
+ Self::Not(expr) => stack.push((expr, depth + 1)),
+ Self::All | Self::None | Self::Exact { .. } | Self::I64Range { .. } => {}
+ }
+ }
+
+ simplify(self)
+ }
+}
+
+/// One exact fact in an index document.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ExactFact {
+ /// Fact vocabulary token.
+ pub attribute: Token,
+ /// Canonical exact value.
+ pub value: ExactValue,
+}
+
+/// One ordered integer fact in an index document.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct IntegerFact {
+ /// Fact vocabulary token.
+ pub attribute: Token,
+ /// Integer value.
+ pub value: i64,
+}
+
+/// Generic projection of one normalized cache record.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct IndexDocument {
+ /// Normalized cache record key.
+ pub record_key: RecordKey,
+ /// Projection profile.
+ pub profile: Profile,
+ /// Entity partition token.
+ pub partition: Token,
+ /// Exact-match facts.
+ pub exact_facts: Vec<ExactFact>,
+ /// Ordered integer facts.
+ pub integer_facts: Vec<IntegerFact>,
+ /// Ordered sort facts.
+ pub sort_facts: Vec<IntegerFact>,
+}
+
+impl IndexDocument {
+ /// Validate bounded fact counts and unique sort attributes.
+ pub fn validate(&self) -> Result<(), ValidationError> {
+ let facts = self.exact_facts.len() + self.integer_facts.len() + self.sort_facts.len();
+ if facts > MAX_FACTS_PER_DOCUMENT {
+ return Err(ValidationError::DocumentFacts);
+ }
+ let mut sort_attributes = HashSet::new();
+ if self
+ .sort_facts
+ .iter()
+ .any(|fact| !sort_attributes.insert(&fact.attribute))
+ {
+ return Err(ValidationError::DuplicateSortFact);
+ }
+ Ok(())
+ }
+
+ /// Evaluate an expression against this document's facts.
+ pub fn matches(&self, expr: &PredicateExpr) -> bool {
+ match expr {
+ PredicateExpr::All => true,
+ PredicateExpr::None => false,
+ PredicateExpr::Exact { attribute, value } => self
+ .exact_facts
+ .iter()
+ .any(|fact| &fact.attribute == attribute && &fact.value == value),
+ PredicateExpr::I64Range {
+ attribute,
+ lower,
+ upper,
+ } => self.integer_facts.iter().any(|fact| {
+ &fact.attribute == attribute
+ && lower.is_none_or(|bound| lower_matches(fact.value, bound))
+ && upper.is_none_or(|bound| upper_matches(fact.value, bound))
+ }),
+ PredicateExpr::And(left, right) => self.matches(left) && self.matches(right),
+ PredicateExpr::Or(left, right) => self.matches(left) || self.matches(right),
+ PredicateExpr::Not(expr) => !self.matches(expr),
+ }
+ }
+}
+
+/// Predicate for one entity partition.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct PartitionPredicate {
+ /// Partition vocabulary token.
+ pub partition: Token,
+ /// Predicate evaluated only inside that partition's universe.
+ pub predicate: PredicateExpr,
+}
+
+/// Ordering direction for a local initial page.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub enum SortDirection {
+ /// Lowest values first.
+ Asc,
+ /// Highest values first.
+ Desc,
+}
+
+/// Unvalidated generic exact-index query descriptor.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct IndexQuery {
+ /// Required profile.
+ pub profile: Profile,
+ /// Complete partition predicates.
+ pub partitions: Vec<PartitionPredicate>,
+ /// Sort-fact attribute.
+ pub sort_attribute: Token,
+ /// Sort direction.
+ pub sort_direction: SortDirection,
+ /// Stable record-key tie-break direction.
+ pub tie_break_direction: SortDirection,
+ /// Bounded initial-page size.
+ pub limit: u16,
+}
+
+/// Validated generic exact-index query.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
+#[serde(transparent)]
+pub struct ValidatedIndexQuery(IndexQuery);
+
+impl<'de> Deserialize<'de> for ValidatedIndexQuery {
+ fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
+ Self::new(IndexQuery::deserialize(deserializer)?).map_err(serde::de::Error::custom)
+ }
+}
+
+impl ValidatedIndexQuery {
+ /// Validate and simplify a query descriptor.
+ pub fn new(mut query: IndexQuery) -> Result<Self, ValidationError> {
+ if query.limit == 0 || query.limit > MAX_QUERY_LIMIT {
+ return Err(ValidationError::Limit(query.limit));
+ }
+ if query.partitions.is_empty() {
+ return Err(ValidationError::NoPartitions);
+ }
+ let mut partitions = HashSet::new();
+ for partition in &mut query.partitions {
+ if !partitions.insert(&partition.partition) {
+ return Err(ValidationError::DuplicatePartition);
+ }
+ partition.predicate = std::mem::replace(&mut partition.predicate, PredicateExpr::None)
+ .validate_and_simplify()?;
+ }
+ Ok(Self(query))
+ }
+
+ /// Access the validated descriptor.
+ pub fn as_query(&self) -> &IndexQuery {
+ &self.0
+ }
+
+ /// Clone this query with a different validated initial-page limit.
+ pub fn with_limit(&self, limit: u16) -> Result<Self, ValidationError> {
+ let mut query = self.0.clone();
+ query.limit = limit;
+ Self::new(query)
+ }
+
+ /// Whether this query can inspect documents in `profile` and `partition`.
+ pub fn includes_scope(&self, profile: &Profile, partition: &Token) -> bool {
+ self.0.profile == *profile
+ && self
+ .0
+ .partitions
+ .iter()
+ .any(|candidate| candidate.partition == *partition)
+ }
+
+ /// Whether this query depends on an attribute in one selected partition.
+ ///
+ /// The sort attribute is always a dependency. Predicate attributes are
+ /// collected without expanding the Boolean expression.
+ pub fn depends_on_attribute(&self, partition: &Token, attribute: &Token) -> bool {
+ let Some(candidate) = self
+ .0
+ .partitions
+ .iter()
+ .find(|candidate| candidate.partition == *partition)
+ else {
+ return false;
+ };
+ self.0.sort_attribute == *attribute
+ || expression_depends_on(&candidate.predicate, attribute)
+ }
+}
+
+/// One ordered optimistic change to a generic projection.
+///
+/// Optimistic changes are layered over authoritative [`IndexDocument`] values;
+/// they never overwrite the authoritative projection needed for rollback.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub enum OptimisticProjectionMutation {
+ /// Replace the effective projection with a complete optimistic document.
+ Replace(IndexDocument),
+ /// Replace selected attributes on the preceding effective projection.
+ Patch {
+ /// Normalized record key.
+ record_key: RecordKey,
+ /// Projection profile.
+ profile: Profile,
+ /// Entity partition.
+ partition: Token,
+ /// Complete replacement values for each exact attribute.
+ exact: Vec<ExactAttributePatch>,
+ /// Complete replacement values for each integer attribute.
+ integers: Vec<IntegerAttributePatch>,
+ /// Replacement values for sort attributes.
+ sorts: Vec<IntegerFact>,
+ },
+ /// Hide the record from the effective local view while retaining its base projection.
+ Delete {
+ /// Normalized record key.
+ record_key: RecordKey,
+ /// Projection profile.
+ profile: Profile,
+ /// Entity partition.
+ partition: Token,
+ },
+ /// The optimistic mutation may change facts that were not deterministically projected.
+ Unknown {
+ /// Normalized record key.
+ record_key: RecordKey,
+ /// Projection profile.
+ profile: Profile,
+ /// Entity partition.
+ partition: Token,
+ /// Potentially changed attributes. Empty means every attribute.
+ affected_attributes: Vec<Token>,
+ },
+}
+
+/// Complete replacement of one exact attribute's values.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ExactAttributePatch {
+ /// Attribute to replace.
+ pub attribute: Token,
+ /// New values. Empty removes the attribute from the effective projection.
+ pub values: Vec<ExactValue>,
+}
+
+/// Complete replacement of one integer attribute's values.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct IntegerAttributePatch {
+ /// Attribute to replace.
+ pub attribute: Token,
+ /// New values. Empty removes the attribute from the effective projection.
+ pub values: Vec<i64>,
+}
+
+impl OptimisticProjectionMutation {
+ /// Validate the optimistic projection payload.
+ pub fn validate(&self) -> Result<(), ValidationError> {
+ let Self::Patch {
+ exact,
+ integers,
+ sorts,
+ ..
+ } = self
+ else {
+ return match self {
+ Self::Replace(document) => document.validate(),
+ Self::Delete { .. } | Self::Unknown { .. } => Ok(()),
+ Self::Patch { .. } => unreachable!(),
+ };
+ };
+
+ let mut attributes = HashSet::new();
+ if exact
+ .iter()
+ .any(|patch| !attributes.insert(&patch.attribute))
+ {
+ return Err(ValidationError::DuplicateExactPatchAttribute);
+ }
+ attributes.clear();
+ if integers
+ .iter()
+ .any(|patch| !attributes.insert(&patch.attribute))
+ {
+ return Err(ValidationError::DuplicateIntegerPatchAttribute);
+ }
+ attributes.clear();
+ if sorts.iter().any(|fact| !attributes.insert(&fact.attribute)) {
+ return Err(ValidationError::DuplicateSortPatchAttribute);
+ }
+ Ok(())
+ }
+
+ /// Read the affected normalized record key.
+ pub fn record_key(&self) -> &RecordKey {
+ match self {
+ Self::Replace(document) => &document.record_key,
+ Self::Patch { record_key, .. }
+ | Self::Delete { record_key, .. }
+ | Self::Unknown { record_key, .. } => record_key,
+ }
+ }
+
+ /// Read the affected profile.
+ pub fn profile(&self) -> &Profile {
+ match self {
+ Self::Replace(document) => &document.profile,
+ Self::Patch { profile, .. }
+ | Self::Delete { profile, .. }
+ | Self::Unknown { profile, .. } => profile,
+ }
+ }
+
+ /// Read the affected partition.
+ pub fn partition(&self) -> &Token {
+ match self {
+ Self::Replace(document) => &document.partition,
+ Self::Patch { partition, .. }
+ | Self::Delete { partition, .. }
+ | Self::Unknown { partition, .. } => partition,
+ }
+ }
+
+ /// Whether uncertainty in this mutation intersects a validated query.
+ pub fn makes_query_uncertain(&self, query: &ValidatedIndexQuery) -> bool {
+ let Self::Unknown {
+ profile,
+ partition,
+ affected_attributes,
+ ..
+ } = self
+ else {
+ return false;
+ };
+ query.includes_scope(profile, partition)
+ && (affected_attributes.is_empty()
+ || affected_attributes
+ .iter()
+ .any(|attribute| query.depends_on_attribute(partition, attribute)))
+ }
+}
+
+/// Validation failure for generic index input.
+#[derive(Debug, Error, PartialEq, Eq)]
+pub enum ValidationError {
+ /// A token is empty, too long, or contains non-portable bytes.
+ #[error("invalid predicate-index token `{0}`")]
+ InvalidToken(String),
+ /// A normalized record key is empty or too large.
+ #[error("invalid normalized record key")]
+ InvalidRecordKey,
+ /// An exact value is too large.
+ #[error("exact value has {0} bytes")]
+ ExactValueTooLarge(usize),
+ /// The expression is too deep.
+ #[error("predicate expression exceeds maximum depth")]
+ ExpressionDepth,
+ /// The expression contains too many nodes.
+ #[error("predicate expression exceeds maximum node count")]
+ ExpressionNodes,
+ /// An integer range is inverted or empty.
+ #[error("invalid integer range")]
+ InvalidRange,
+ /// A document contains too many facts.
+ #[error("index document contains too many facts")]
+ DocumentFacts,
+ /// A document has more than one sort value for an attribute.
+ #[error("duplicate sort fact attribute")]
+ DuplicateSortFact,
+ /// An optimistic patch repeats an exact attribute.
+ #[error("duplicate exact patch attribute")]
+ DuplicateExactPatchAttribute,
+ /// An optimistic patch repeats an integer attribute.
+ #[error("duplicate integer patch attribute")]
+ DuplicateIntegerPatchAttribute,
+ /// An optimistic patch repeats a sort attribute.
+ #[error("duplicate sort patch attribute")]
+ DuplicateSortPatchAttribute,
+ /// A query has no partition universes.
+ #[error("index query has no partitions")]
+ NoPartitions,
+ /// A query repeats a partition.
+ #[error("index query repeats a partition")]
+ DuplicatePartition,
+ /// A query limit is zero or too large.
+ #[error("invalid index query limit {0}")]
+ Limit(u16),
+}
+
+/// Pure reference result used for adapter conformance tests.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ReferenceHit {
+ /// Normalized cache record key.
+ pub record_key: RecordKey,
+ /// Sort value selected by the query.
+ pub sort_value: i64,
+}
+
+/// Evaluate a validated query over generic documents without storage.
+pub fn evaluate_reference(
+ query: &ValidatedIndexQuery,
+ documents: &[IndexDocument],
+) -> Vec<ReferenceHit> {
+ let query = query.as_query();
+ let mut hits = documents
+ .iter()
+ .filter(|document| document.profile == query.profile)
+ .filter_map(|document| {
+ let partition = query
+ .partitions
+ .iter()
+ .find(|partition| partition.partition == document.partition)?;
+ if !document.matches(&partition.predicate) {
+ return None;
+ }
+ let sort_value = document
+ .sort_facts
+ .iter()
+ .find(|fact| fact.attribute == query.sort_attribute)?
+ .value;
+ Some(ReferenceHit {
+ record_key: document.record_key.clone(),
+ sort_value,
+ })
+ })
+ .collect::<Vec<_>>();
+
+ hits.sort_by(|left, right| {
+ directional_cmp(left.sort_value.cmp(&right.sort_value), query.sort_direction).then_with(
+ || {
+ directional_cmp(
+ left.record_key.cmp(&right.record_key),
+ query.tie_break_direction,
+ )
+ },
+ )
+ });
+ hits.truncate(usize::from(query.limit));
+ hits
+}
+
+/// Encode a UTC timestamp as signed Unix microseconds without millisecond loss.
+pub fn utc_timestamp_micros(value: DateTime<Utc>) -> i64 {
+ value.timestamp_micros()
+}
+
+fn expression_depends_on(expr: &PredicateExpr, attribute: &Token) -> bool {
+ match expr {
+ PredicateExpr::Exact {
+ attribute: candidate,
+ ..
+ }
+ | PredicateExpr::I64Range {
+ attribute: candidate,
+ ..
+ } => candidate == attribute,
+ PredicateExpr::And(left, right) | PredicateExpr::Or(left, right) => {
+ expression_depends_on(left, attribute) || expression_depends_on(right, attribute)
+ }
+ PredicateExpr::Not(expr) => expression_depends_on(expr, attribute),
+ PredicateExpr::All | PredicateExpr::None => false,
+ }
+}
+
+fn simplify(expr: PredicateExpr) -> Result<PredicateExpr, ValidationError> {
+ Ok(match expr {
+ PredicateExpr::And(left, right) => match (simplify(*left)?, simplify(*right)?) {
+ (PredicateExpr::None, _) | (_, PredicateExpr::None) => PredicateExpr::None,
+ (PredicateExpr::All, right) => right,
+ (left, PredicateExpr::All) => left,
+ (left, right) => PredicateExpr::And(Box::new(left), Box::new(right)),
+ },
+ PredicateExpr::Or(left, right) => match (simplify(*left)?, simplify(*right)?) {
+ (PredicateExpr::All, _) | (_, PredicateExpr::All) => PredicateExpr::All,
+ (PredicateExpr::None, right) => right,
+ (left, PredicateExpr::None) => left,
+ (left, right) => PredicateExpr::Or(Box::new(left), Box::new(right)),
+ },
+ PredicateExpr::Not(expr) => match simplify(*expr)? {
+ PredicateExpr::All => PredicateExpr::None,
+ PredicateExpr::None => PredicateExpr::All,
+ PredicateExpr::Not(expr) => *expr,
+ expr => PredicateExpr::Not(Box::new(expr)),
+ },
+ PredicateExpr::I64Range {
+ attribute,
+ lower,
+ upper,
+ } => {
+ validate_range(lower, upper)?;
+ PredicateExpr::I64Range {
+ attribute,
+ lower,
+ upper,
+ }
+ }
+ expr @ (PredicateExpr::All | PredicateExpr::None | PredicateExpr::Exact { .. }) => expr,
+ })
+}
+
+fn validate_range(
+ lower: Option<RangeBound>,
+ upper: Option<RangeBound>,
+) -> Result<(), ValidationError> {
+ let Some(lower) = lower else { return Ok(()) };
+ let Some(upper) = upper else { return Ok(()) };
+ let lower_value = match lower {
+ RangeBound::Inclusive(value) | RangeBound::Exclusive(value) => value,
+ };
+ let upper_value = match upper {
+ RangeBound::Inclusive(value) | RangeBound::Exclusive(value) => value,
+ };
+ let non_empty_at_equality =
+ matches!(lower, RangeBound::Inclusive(_)) && matches!(upper, RangeBound::Inclusive(_));
+ if lower_value > upper_value || (lower_value == upper_value && !non_empty_at_equality) {
+ return Err(ValidationError::InvalidRange);
+ }
+ Ok(())
+}
+
+fn lower_matches(value: i64, bound: RangeBound) -> bool {
+ match bound {
+ RangeBound::Inclusive(lower) => value >= lower,
+ RangeBound::Exclusive(lower) => value > lower,
+ }
+}
+
+fn upper_matches(value: i64, bound: RangeBound) -> bool {
+ match bound {
+ RangeBound::Inclusive(upper) => value <= upper,
+ RangeBound::Exclusive(upper) => value < upper,
+ }
+}
+
+fn directional_cmp(ordering: Ordering, direction: SortDirection) -> Ordering {
+ match direction {
+ SortDirection::Asc => ordering,
+ SortDirection::Desc => ordering.reverse(),
+ }
+}
diff --git a/crates/predicate_index/src/test.rs b/crates/predicate_index/src/test.rs
new file mode 100644
index 0000000000..de2c69e980
--- /dev/null
+++ b/crates/predicate_index/src/test.rs
@@ -0,0 +1,239 @@
+use chrono::{TimeZone, Timelike};
+
+use super::*;
+
+fn token(value: &str) -> Token {
+ Token::new(value).unwrap()
+}
+
+fn exact(value: &str) -> ExactValue {
+ ExactValue::utf8(value).unwrap()
+}
+
+fn document(key: &str, owner: &str, updated_at: i64) -> IndexDocument {
+ IndexDocument {
+ record_key: RecordKey::new(key).unwrap(),
+ profile: Profile::new(token("soup-flat-v1")),
+ partition: token("document"),
+ exact_facts: vec![ExactFact {
+ attribute: token("owner"),
+ value: exact(owner),
+ }],
+ integer_facts: vec![IntegerFact {
+ attribute: token("updated-at"),
+ value: updated_at,
+ }],
+ sort_facts: vec![IntegerFact {
+ attribute: token("updated-at"),
+ value: updated_at,
+ }],
+ }
+}
+
+#[test]
+fn simplifies_without_distributing_boolean_expressions() {
+ let leaf = PredicateExpr::Exact {
+ attribute: token("owner"),
+ value: exact("user-1"),
+ };
+ let expression = PredicateExpr::And(
+ Box::new(PredicateExpr::All),
+ Box::new(PredicateExpr::Or(
+ Box::new(PredicateExpr::None),
+ Box::new(PredicateExpr::Not(Box::new(PredicateExpr::Not(Box::new(
+ leaf.clone(),
+ ))))),
+ )),
+ );
+
+ assert_eq!(expression.validate_and_simplify().unwrap(), leaf);
+}
+
+#[test]
+fn validates_all_four_range_boundaries() {
+ let attribute = token("updated-at");
+ let document = document("Document:1", "user-1", 10);
+ for (lower, upper, expected) in [
+ (
+ Some(RangeBound::Inclusive(10)),
+ Some(RangeBound::Inclusive(10)),
+ true,
+ ),
+ (
+ Some(RangeBound::Exclusive(10)),
+ Some(RangeBound::Inclusive(11)),
+ false,
+ ),
+ (
+ Some(RangeBound::Inclusive(9)),
+ Some(RangeBound::Exclusive(10)),
+ false,
+ ),
+ (
+ Some(RangeBound::Exclusive(9)),
+ Some(RangeBound::Exclusive(11)),
+ true,
+ ),
+ ] {
+ let expression = PredicateExpr::I64Range {
+ attribute: attribute.clone(),
+ lower,
+ upper,
+ }
+ .validate_and_simplify()
+ .unwrap();
+ assert_eq!(document.matches(&expression), expected);
+ }
+}
+
+#[test]
+fn missing_fact_is_false_and_not_uses_partition_document_universe() {
+ let document = document("Document:1", "user-1", 10);
+ let missing = PredicateExpr::Exact {
+ attribute: token("project-id"),
+ value: exact("project-1"),
+ };
+
+ assert!(!document.matches(&missing));
+ assert!(document.matches(&PredicateExpr::Not(Box::new(missing))));
+}
+
+#[test]
+fn reference_evaluator_orders_with_stable_tie_breaker_and_limit() {
+ let query = ValidatedIndexQuery::new(IndexQuery {
+ profile: Profile::new(token("soup-flat-v1")),
+ partitions: vec![PartitionPredicate {
+ partition: token("document"),
+ predicate: PredicateExpr::Exact {
+ attribute: token("owner"),
+ value: exact("user-1"),
+ },
+ }],
+ sort_attribute: token("updated-at"),
+ sort_direction: SortDirection::Desc,
+ tie_break_direction: SortDirection::Desc,
+ limit: 2,
+ })
+ .unwrap();
+ let documents = vec![
+ document("Document:1", "user-1", 10),
+ document("Document:3", "user-1", 10),
+ document("Document:2", "user-1", 20),
+ document("Document:4", "user-2", 30),
+ ];
+
+ assert_eq!(
+ evaluate_reference(&query, &documents)
+ .into_iter()
+ .map(|hit| hit.record_key.as_str().to_owned())
+ .collect::<Vec<_>>(),
+ vec!["Document:2", "Document:3"]
+ );
+}
+
+#[test]
+fn preserves_sub_millisecond_timestamp_precision() {
+ let timestamp = Utc
+ .with_ymd_and_hms(2026, 1, 1, 0, 0, 0)
+ .unwrap()
+ .with_nanosecond(123_456_000)
+ .unwrap();
+
+ assert_eq!(utc_timestamp_micros(timestamp) % 1_000_000, 123_456);
+}
+
+#[test]
+fn deserialization_cannot_bypass_validation() {
+ assert!(serde_json::from_str::<Token>(r#""not a token""#).is_err());
+ assert!(
+ serde_json::from_value::<ValidatedIndexQuery>(serde_json::json!({
+ "profile": "soup-flat-v1",
+ "partitions": [{ "partition": "document", "predicate": "All" }],
+ "sort_attribute": "updated-at",
+ "sort_direction": "Asc",
+ "tie_break_direction": "Asc",
+ "limit": 0
+ }))
+ .is_err()
+ );
+
+ let partition = token("document");
+ let profile = Profile::new(token("soup-flat-v1"));
+ let query = ValidatedIndexQuery::new(IndexQuery {
+ profile: profile.clone(),
+ partitions: vec![PartitionPredicate {
+ partition: partition.clone(),
+ predicate: PredicateExpr::Exact {
+ attribute: token("owner"),
+ value: exact("user-1"),
+ },
+ }],
+ sort_attribute: token("updated-at"),
+ sort_direction: SortDirection::Asc,
+ tie_break_direction: SortDirection::Asc,
+ limit: 20,
+ })
+ .unwrap();
+ assert!(query.includes_scope(&profile, &partition));
+ assert!(!query.includes_scope(&profile, &token("project")));
+
+ let unknown = |affected_attributes| OptimisticProjectionMutation::Unknown {
+ record_key: RecordKey::new("Document:1").unwrap(),
+ profile: profile.clone(),
+ partition: partition.clone(),
+ affected_attributes,
+ };
+ assert!(unknown(Vec::new()).makes_query_uncertain(&query));
+ assert!(!unknown(vec![token("file-type")]).makes_query_uncertain(&query));
+
+ let mut too_deep = PredicateExpr::All;
+ for _ in 0..MAX_EXPRESSION_DEPTH {
+ too_deep = PredicateExpr::Not(Box::new(too_deep));
+ }
+ assert_eq!(
+ too_deep.validate_and_simplify(),
+ Err(ValidationError::ExpressionDepth)
+ );
+}
+
+#[test]
+fn rejects_empty_ranges_duplicate_partitions_and_duplicate_sort_facts() {
+ assert_eq!(
+ PredicateExpr::I64Range {
+ attribute: token("updated-at"),
+ lower: Some(RangeBound::Exclusive(10)),
+ upper: Some(RangeBound::Inclusive(10)),
+ }
+ .validate_and_simplify(),
+ Err(ValidationError::InvalidRange)
+ );
+
+ let query = IndexQuery {
+ profile: Profile::new(token("soup-flat-v1")),
+ partitions: vec![
+ PartitionPredicate {
+ partition: token("document"),
+ predicate: PredicateExpr::All,
+ },
+ PartitionPredicate {
+ partition: token("document"),
+ predicate: PredicateExpr::All,
+ },
+ ],
+ sort_attribute: token("updated-at"),
+ sort_direction: SortDirection::Asc,
+ tie_break_direction: SortDirection::Asc,
+ limit: 20,
+ };
+ assert_eq!(
+ ValidatedIndexQuery::new(query),
+ Err(ValidationError::DuplicatePartition)
+ );
+
+ let mut document = document("Document:1", "user-1", 10);
+ document.sort_facts.push(IntegerFact {
+ attribute: token("updated-at"),
+ value: 11,
+ });
+ assert_eq!(document.validate(), Err(ValidationError::DuplicateSortFact));
+}
diff --git a/crates/soup_filter_cache_adapter/Cargo.toml b/crates/soup_filter_cache_adapter/Cargo.toml
new file mode 100644
index 0000000000..f9ca1934e9
--- /dev/null
+++ b/crates/soup_filter_cache_adapter/Cargo.toml
@@ -0,0 +1,17 @@
+[package]
+edition = "2024"
+name = "soup-filter-cache-adapter"
+publish = false
+version = "0.1.0"
+
+[dependencies]
+cache-core = { path = "../client/cache-core" }
+chrono = { workspace = true }
+graphql_soup_filter_input = { path = "../graphql_soup_filter_input" }
+indexmap = { workspace = true }
+item-filter-index = { path = "../item_filter_index" }
+predicate-index = { path = "../predicate_index" }
+serde_json = { workspace = true }
+soup-filter-projection = { path = "../soup_filter_projection", default-features = false }
+thiserror = { workspace = true }
+uuid = { workspace = true }
diff --git a/crates/soup_filter_cache_adapter/src/lib.rs b/crates/soup_filter_cache_adapter/src/lib.rs
new file mode 100644
index 0000000000..3dca3a3252
--- /dev/null
+++ b/crates/soup_filter_cache_adapter/src/lib.rs
@@ -0,0 +1,358 @@
+#![deny(missing_docs)]
+//! Soup-specific browser adapter for the generic predicate-index cache.
+//!
+//! This crate owns the application GraphQL schema and `soup-flat-v1` policy.
+//! Cache crates receive only the generic query and projection IR produced here.
+
+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_v1, vocabulary,
+};
+use predicate_index::{
+ IndexDocument, OptimisticProjectionMutation, RecordKey, SortDirection, Token,
+ ValidatedIndexQuery,
+};
+use soup_filter_projection::{
+ DirectProjectionInput, DirectProjectionPatchInput, SoupFlatEntityKind, patch_direct_fields,
+ project_direct_fields,
+};
+use std::collections::HashMap;
+
+/// Failure to materialize or compile a Soup filter request.
+#[derive(Debug, thiserror::Error)]
+#[error("{0}")]
+pub struct SoupFilterCacheAdapterError(String);
+
+/// Result of compiling a Soup request to generic predicate-index IR.
+#[derive(Debug)]
+pub enum SoupFilterCompileOutcome {
+ /// The request is outside the exact local support profile.
+ Unsupported,
+ /// A validated generic query that the cache can evaluate exactly.
+ Supported(ValidatedIndexQuery),
+}
+
+/// Compile one GraphQL Soup request into generic predicate-index IR.
+pub fn compile_filter_request(
+ filters: serde_json::Value,
+ sort_method: &str,
+ sort_direction: &str,
+ limit: u16,
+) -> Result<SoupFilterCompileOutcome, SoupFilterCacheAdapterError> {
+ let ast = materialize_graphql_filter(filters)
+ .map_err(|error| SoupFilterCacheAdapterError(error.to_string()))?;
+ let sort = match sort_method {
+ "CREATED_AT" => SoupIndexSort::CreatedAt,
+ "UPDATED_AT" => SoupIndexSort::UpdatedAt,
+ _ => SoupIndexSort::Unsupported,
+ };
+ let direction = match sort_direction {
+ "ASC" => SortDirection::Asc,
+ "DESC" => SortDirection::Desc,
+ _ => {
+ return Err(SoupFilterCacheAdapterError(
+ "invalid entity-filter sort direction".to_owned(),
+ ));
+ }
+ };
+ compile_soup_flat_v1(
+ &ast,
+ SoupFlatRequest {
+ sort,
+ direction,
+ limit,
+ has_cursor: false,
+ },
+ )
+ .map_err(|error| SoupFilterCacheAdapterError(error.to_string()))
+ .map(|outcome| match outcome {
+ LocalCompileOutcome::Unsupported(_) => SoupFilterCompileOutcome::Unsupported,
+ LocalCompileOutcome::Supported(query) => SoupFilterCompileOutcome::Supported(query),
+ })
+}
+
+/// Derive authoritative generic projection mutations from a GraphQL response.
+pub fn authoritative_projection_mutations(data: &serde_json::Value) -> Vec<ProjectionMutation> {
+ fn walk(value: &serde_json::Value, mutations: &mut HashMap<String, ProjectionMutation>) {
+ match value {
+ serde_json::Value::Array(values) => {
+ for value in values {
+ walk(value, mutations);
+ }
+ }
+ serde_json::Value::Object(object) => {
+ let typename = object.get("__typename").and_then(|value| value.as_str());
+ let id = object.get("id").and_then(|value| value.as_str());
+ if let (Some(typename), Some(id)) = (typename, id)
+ && let Some(partition) = projection_partition(typename)
+ {
+ let key_text = format!("{typename}:{id}");
+ if let Ok(record_key) = RecordKey::new(key_text.clone()) {
+ let mutation = direct_projection_for_object(
+ record_key.clone(),
+ partition.clone(),
+ object,
+ None,
+ )
+ .map(ProjectionMutation::Replace)
+ .unwrap_or(ProjectionMutation::MarkIncomplete {
+ record_key,
+ profile: vocabulary::profile(),
+ partition,
+ kind: ProjectionIncompleteKind::Dirty,
+ });
+ let replace = matches!(mutation, ProjectionMutation::Replace(_));
+ if replace
+ || !matches!(
+ mutations.get(&key_text),
+ Some(ProjectionMutation::Replace(_))
+ )
+ {
+ mutations.insert(key_text, mutation);
+ }
+ }
+ }
+ for value in object.values() {
+ walk(value, mutations);
+ }
+ }
+ _ => {}
+ }
+ }
+
+ let mut mutations = HashMap::new();
+ walk(data, &mut mutations);
+ mutations.into_values().collect()
+}
+
+/// Derive ordered generic optimistic projection mutations from a GraphQL response.
+pub fn optimistic_projection_mutations(
+ data: &serde_json::Value,
+ created_at_ms: i64,
+) -> Vec<OptimisticProjectionMutation> {
+ fn walk(
+ value: &serde_json::Value,
+ created_at_ms: i64,
+ mutations: &mut IndexMap<String, OptimisticProjectionMutation>,
+ ) {
+ match value {
+ serde_json::Value::Array(values) => {
+ for value in values {
+ walk(value, created_at_ms, mutations);
+ }
+ }
+ serde_json::Value::Object(object) => {
+ if object.get("__typename").and_then(|value| value.as_str())
+ == Some("GraphqlCacheDeletion")
+ && let (Some(typename), Some(id)) = (
+ object
+ .get("graphqlTypeName")
+ .and_then(|value| value.as_str()),
+ object.get("entityId").and_then(|value| value.as_str()),
+ )
+ && let Some(partition) = projection_partition(typename)
+ {
+ let key_text = format!("{typename}:{id}");
+ if let Ok(record_key) = RecordKey::new(key_text.clone()) {
+ mutations.insert(
+ key_text,
+ OptimisticProjectionMutation::Delete {
+ record_key,
+ profile: vocabulary::profile(),
+ partition,
+ },
+ );
+ }
+ }
+
+ let typename = object.get("__typename").and_then(|value| value.as_str());
+ let id = object.get("id").and_then(|value| value.as_str());
+ if let (Some(typename), Some(id)) = (typename, id)
+ && let Some(partition) = projection_partition(typename)
+ {
+ let key_text = format!("{typename}:{id}");
+ if let Ok(record_key) = RecordKey::new(key_text.clone()) {
+ let mutation = optimistic_projection_for_object(
+ record_key.clone(),
+ partition.clone(),
+ object,
+ created_at_ms,
+ )
+ .unwrap_or(OptimisticProjectionMutation::Unknown {
+ record_key,
+ profile: vocabulary::profile(),
+ partition,
+ affected_attributes: Vec::new(),
+ });
+ if !matches!(
+ mutations.get(&key_text),
+ Some(OptimisticProjectionMutation::Delete { .. })
+ ) {
+ mutations.insert(key_text, mutation);
+ }
+ }
+ }
+ for value in object.values() {
+ walk(value, created_at_ms, mutations);
+ }
+ }
+ _ => {}
+ }
+ }
+
+ let mut mutations = IndexMap::new();
+ walk(data, created_at_ms, &mut mutations);
+ mutations.into_values().collect()
+}
+
+/// Mark projections associated with known Soup record keys dirty.
+pub fn dirty_projection_mutations(keys: &[String]) -> Vec<ProjectionMutation> {
+ keys.iter()
+ .filter_map(|key| {
+ let (typename, _) = key.split_once(':')?;
+ let partition = projection_partition(typename)?;
+ Some(ProjectionMutation::MarkIncomplete {
+ record_key: RecordKey::new(key.clone()).ok()?,
+ profile: vocabulary::profile(),
+ partition,
+ kind: ProjectionIncompleteKind::Dirty,
+ })
+ })
+ .collect()
+}
+
+fn direct_projection_for_object(
+ record_key: RecordKey,
+ partition: Token,
+ object: &serde_json::Map<String, serde_json::Value>,
+ updated_at_fallback_ms: Option<i64>,
+) -> Option<IndexDocument> {
+ let kind = projection_kind(&partition)?;
+ let project_field = if kind == SoupFlatEntityKind::Project {
+ "parentId"
+ } else {
+ "projectId"
+ };
+ let updated_at = match object.get("updatedAt") {
+ Some(value) => graphql_timestamp(value)?,
+ None => chrono::DateTime::from_timestamp_millis(updated_at_fallback_ms?)?,
+ };
+ project_direct_fields(DirectProjectionInput {
+ record_key,
+ kind,
+ id: uuid::Uuid::parse_str(object.get("id")?.as_str()?).ok()?,
+ owner: object.get("ownerId")?.as_str()?.to_owned(),
+ project_id: optional_uuid(object.get(project_field)?)?,
+ file_type: if kind == SoupFlatEntityKind::Document {
+ optional_string(object.get("fileType")?)?
+ } else {
+ None
+ },
+ created_at: graphql_timestamp(object.get("createdAt")?)?,
+ updated_at,
+ })
+ .ok()
+}
+
+fn optimistic_projection_for_object(
+ record_key: RecordKey,
+ partition: Token,
+ object: &serde_json::Map<String, serde_json::Value>,
+ created_at_ms: i64,
+) -> Option<OptimisticProjectionMutation> {
+ if let Some(document) = direct_projection_for_object(
+ record_key.clone(),
+ partition.clone(),
+ object,
+ Some(created_at_ms),
+ ) {
+ return Some(OptimisticProjectionMutation::Replace(document));
+ }
+
+ let kind = projection_kind(&partition)?;
+ let project_field = if kind == SoupFlatEntityKind::Project {
+ "parentId"
+ } else {
+ "projectId"
+ };
+ let updated_at = match object.get("updatedAt") {
+ Some(value) => graphql_timestamp(value)?,
+ None => chrono::DateTime::from_timestamp_millis(created_at_ms)?,
+ };
+ patch_direct_fields(DirectProjectionPatchInput {
+ record_key,
+ kind,
+ owner: match object.get("ownerId") {
+ Some(value) => Some(value.as_str()?.to_owned()),
+ None => None,
+ },
+ project_id: match object.get(project_field) {
+ Some(value) => Some(optional_uuid(value)?),
+ None => None,
+ },
+ file_type: if kind == SoupFlatEntityKind::Document {
+ match object.get("fileType") {
+ Some(value) => Some(optional_string(value)?),
+ None => None,
+ }
+ } else {
+ None
+ },
+ created_at: match object.get("createdAt") {
+ Some(value) => Some(graphql_timestamp(value)?),
+ None => None,
+ },
+ updated_at,
+ })
+ .ok()
+}
+
+fn projection_kind(partition: &Token) -> Option<SoupFlatEntityKind> {
+ if partition == &vocabulary::document_partition() {
+ Some(SoupFlatEntityKind::Document)
+ } else if partition == &vocabulary::project_partition() {
+ Some(SoupFlatEntityKind::Project)
+ } else if partition == &vocabulary::chat_partition() {
+ Some(SoupFlatEntityKind::Chat)
+ } else {
+ None
+ }
+}
+
+fn optional_uuid(value: &serde_json::Value) -> Option<Option<uuid::Uuid>> {
+ match value {
+ serde_json::Value::Null => Some(None),
+ serde_json::Value::String(value) => Some(Some(uuid::Uuid::parse_str(value).ok()?)),
+ _ => None,
+ }
+}
+
+fn optional_string(value: &serde_json::Value) -> Option<Option<String>> {
+ match value {
+ serde_json::Value::Null => Some(None),
+ serde_json::Value::String(value) => Some(Some(value.clone())),
+ _ => None,
+ }
+}
+
+fn graphql_timestamp(value: &serde_json::Value) -> Option<chrono::DateTime<chrono::Utc>> {
+ Some(
+ chrono::DateTime::parse_from_rfc3339(value.as_str()?)
+ .ok()?
+ .with_timezone(&chrono::Utc),
+ )
+}
+
+fn projection_partition(typename: &str) -> Option<Token> {
+ match typename {
+ "GraphqlSoupDocument" => Some(vocabulary::document_partition()),
+ "GraphqlSoupProject" => Some(vocabulary::project_partition()),
+ "GraphqlSoupChat" => Some(vocabulary::chat_partition()),
+ _ => None,
+ }
+}
+
+#[cfg(test)]
+mod test;
diff --git a/crates/soup_filter_cache_adapter/src/test.rs b/crates/soup_filter_cache_adapter/src/test.rs
new file mode 100644
index 0000000000..5182855274
--- /dev/null
+++ b/crates/soup_filter_cache_adapter/src/test.rs
@@ -0,0 +1,148 @@
+use super::*;
+
+#[test]
+fn optimistic_soup_payloads_compile_to_durable_projection_layers() {
+ let mutations = optimistic_projection_mutations(
+ &serde_json::json!({
+ "update": {
+ "__typename": "GraphqlSoupDocument",
+ "id": "00000000-0000-0000-0000-000000000001",
+ "projectId": "00000000-0000-0000-0000-000000000002"
+ }
+ }),
+ 123,
+ );
+ assert_eq!(mutations.len(), 1);
+ let OptimisticProjectionMutation::Patch {
+ exact,
+ integers,
+ sorts,
+ ..
+ } = &mutations[0]
+ else {
+ panic!("partial optimistic Soup entity should compile to a patch");
+ };
+ assert!(
+ exact
+ .iter()
+ .any(|patch| patch.attribute == vocabulary::project_id())
+ );
+ assert!(integers.iter().any(|patch| {
+ patch.attribute == vocabulary::updated_at() && patch.values == vec![123_000]
+ }));
+ assert!(
+ sorts
+ .iter()
+ .any(|fact| { fact.attribute == vocabulary::updated_at() && fact.value == 123_000 })
+ );
+
+ let complete = optimistic_projection_mutations(
+ &serde_json::json!({
+ "create": {
+ "__typename": "GraphqlSoupProject",
+ "id": "00000000-0000-0000-0000-000000000003",
+ "ownerId": "user-1",
+ "parentId": null,
+ "createdAt": "2025-01-01T00:00:00.000001Z"
+ }
+ }),
+ 456,
+ );
+ assert!(matches!(
+ complete.as_slice(),
+ [OptimisticProjectionMutation::Replace(_)]
+ ));
+
+ let deletion = optimistic_projection_mutations(
+ &serde_json::json!({
+ "result": [
+ {
+ "__typename": "GraphqlCacheDeletion",
+ "graphqlTypeName": "GraphqlSoupChat",
+ "entityId": "00000000-0000-0000-0000-000000000004"
+ },
+ {
+ "__typename": "GraphqlSoupChat",
+ "id": "00000000-0000-0000-0000-000000000004",
+ "projectId": null
+ }
+ ]
+ }),
+ 789,
+ );
+ assert!(matches!(
+ deletion.as_slice(),
+ [OptimisticProjectionMutation::Delete { .. }]
+ ));
+}
+
+#[test]
+fn optimistic_mutations_keep_first_seen_order_and_deletion_precedence() {
+ let mutations = optimistic_projection_mutations(
+ &serde_json::json!({
+ "result": [
+ {
+ "__typename": "GraphqlSoupChat",
+ "id": "00000000-0000-0000-0000-000000000004",
+ "projectId": null
+ },
+ {
+ "__typename": "GraphqlSoupDocument",
+ "id": "00000000-0000-0000-0000-000000000005",
+ "projectId": null
+ },
+ {
+ "__typename": "GraphqlCacheDeletion",
+ "graphqlTypeName": "GraphqlSoupChat",
+ "entityId": "00000000-0000-0000-0000-000000000004"
+ },
+ {
+ "__typename": "GraphqlSoupChat",
+ "id": "00000000-0000-0000-0000-000000000004",
+ "projectId": "00000000-0000-0000-0000-000000000006"
+ }
+ ]
+ }),
+ 789,
+ );
+
+ assert_eq!(mutations.len(), 2);
+ assert_eq!(
+ mutations[0].record_key().as_str(),
+ "GraphqlSoupChat:00000000-0000-0000-0000-000000000004"
+ );
+ assert!(matches!(
+ mutations[0],
+ OptimisticProjectionMutation::Delete { .. }
+ ));
+ assert_eq!(
+ mutations[1].record_key().as_str(),
+ "GraphqlSoupDocument:00000000-0000-0000-0000-000000000005"
+ );
+}
+
+#[test]
+fn authoritative_direct_fields_do_not_require_a_projection_schema_field() {
+ let mutations = authoritative_projection_mutations(&serde_json::json!({
+ "item": {
+ "__typename": "GraphqlSoupDocument",
+ "id": "00000000-0000-0000-0000-000000000001",
+ "ownerId": "user-1",
+ "projectId": null,
+ "fileType": "md",
+ "createdAt": "2025-01-01T00:00:00.000001Z",
+ "updatedAt": "2025-01-02T00:00:00.000001Z"
+ }
+ }));
+ assert!(matches!(
+ mutations.as_slice(),
+ [ProjectionMutation::Replace(_)]
+ ));
+}
+
+#[test]
+fn invalid_sort_direction_is_rejected_at_the_soup_boundary() {
+ let error = compile_filter_request(serde_json::json!({}), "UPDATED_AT", "SIDEWAYS", 10)
+ .expect_err("invalid direction must not reach the generic cache");
+ assert_eq!(error.to_string(), "invalid entity-filter sort direction");
+}
diff --git a/crates/soup_filter_projection/Cargo.toml b/crates/soup_filter_projection/Cargo.toml
new file mode 100644
index 0000000000..8633486897
--- /dev/null
+++ b/crates/soup_filter_projection/Cargo.toml
@@ -0,0 +1,23 @@
+[package]
+edition = "2024"
+name = "soup-filter-projection"
+publish = false
+version = "0.1.0"
+
+[features]
+# Native-only model adapters. Wasm-facing dependents must disable default features.
+default = ["models"]
+models = ["dep:models_soup", "dep:workspace-hack"]
+
+[dependencies]
+chrono = { workspace = true }
+item-filter-index = { path = "../item_filter_index" }
+model_file_type = { path = "../model_file_type" }
+models_soup = { path = "../models_soup", optional = true }
+predicate-index = { path = "../predicate_index" }
+thiserror = { workspace = true }
+uuid = { workspace = true }
+workspace-hack = { version = "0.1", path = "../workspace-hack", optional = true }
+
+[dev-dependencies]
+macro_user_id = { path = "../macro_user_id" }
diff --git a/crates/soup_filter_projection/src/lib.rs b/crates/soup_filter_projection/src/lib.rs
new file mode 100644
index 0000000000..ab03b10c3f
--- /dev/null
+++ b/crates/soup_filter_projection/src/lib.rs
@@ -0,0 +1,313 @@
+//! Versioned direct-field Soup projections for `soup-flat-v1`.
+#![deny(missing_docs)]
+
+use std::str::FromStr;
+
+use item_filter_index::vocabulary;
+use model_file_type::FileType;
+#[cfg(feature = "models")]
+use models_soup::{chat::SoupChat, document::SoupDocument, item::SoupItem, project::SoupProject};
+use predicate_index::{
+ ExactAttributePatch, ExactFact, ExactValue, IndexDocument, IntegerAttributePatch, IntegerFact,
+ OptimisticProjectionMutation, RecordKey, Token, ValidationError, utc_timestamp_micros,
+};
+use thiserror::Error;
+
+#[cfg(test)]
+mod test;
+
+/// Failure to project an authoritative Soup item.
+#[derive(Debug, Error, PartialEq, Eq)]
+pub enum ProjectionError {
+ /// The authoritative document contained an unknown file-type value.
+ #[error("invalid authoritative Soup document file type `{0}`")]
+ InvalidFileType(String),
+ /// The generic projection violated bounded IR invariants.
+ #[error(transparent)]
+ Validation(#[from] ValidationError),
+}
+
+/// Supported direct-field Soup entity kind.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum SoupFlatEntityKind {
+ /// Document projection.
+ Document,
+ /// Project projection.
+ Project,
+ /// Chat projection.
+ Chat,
+}
+
+impl SoupFlatEntityKind {
+ fn partition(self) -> Token {
+ match self {
+ Self::Document => vocabulary::document_partition(),
+ Self::Project => vocabulary::project_partition(),
+ Self::Chat => vocabulary::chat_partition(),
+ }
+ }
+}
+
+/// Complete direct fields needed to create an optimistic `soup-flat-v1` projection.
+#[derive(Debug, Clone)]
+pub struct DirectProjectionInput {
+ /// Normalized record key.
+ pub record_key: RecordKey,
+ /// Supported Soup entity kind.
+ pub kind: SoupFlatEntityKind,
+ /// Entity UUID.
+ pub id: uuid::Uuid,
+ /// Canonical owner identifier.
+ pub owner: String,
+ /// Project or parent UUID, when present.
+ pub project_id: Option<uuid::Uuid>,
+ /// Document file type, when present. Ignored for other kinds.
+ pub file_type: Option<String>,
+ /// Creation timestamp.
+ pub created_at: chrono::DateTime<chrono::Utc>,
+ /// Effective optimistic update timestamp.
+ pub updated_at: chrono::DateTime<chrono::Utc>,
+}
+
+/// Partial direct fields changed by one optimistic mutation.
+#[derive(Debug, Clone)]
+pub struct DirectProjectionPatchInput {
+ /// Normalized record key.
+ pub record_key: RecordKey,
+ /// Supported Soup entity kind.
+ pub kind: SoupFlatEntityKind,
+ /// Replacement owner when supplied.
+ pub owner: Option<String>,
+ /// Replacement project/parent value. Outer `None` means unchanged.
+ pub project_id: Option<Option<uuid::Uuid>>,
+ /// Replacement document file type. Outer `None` means unchanged.
+ pub file_type: Option<Option<String>>,
+ /// Replacement creation timestamp when supplied.
+ pub created_at: Option<chrono::DateTime<chrono::Utc>>,
+ /// Effective optimistic update timestamp.
+ pub updated_at: chrono::DateTime<chrono::Utc>,
+}
+
+/// Generate a complete optimistic projection from direct Soup fields.
+pub fn project_direct_fields(
+ input: DirectProjectionInput,
+) -> Result<IndexDocument, ProjectionError> {
+ let mut exact_facts = common_exact_facts(input.id, input.owner)?;
+ if let Some(project_id) = input.project_id {
+ exact_facts.push(uuid_fact(vocabulary::project_id(), project_id)?);
+ }
+ if input.kind == SoupFlatEntityKind::Document
+ && let Some(file_type) = input.file_type
+ {
+ let canonical = FileType::from_str(&file_type)
+ .map_err(|_| ProjectionError::InvalidFileType(file_type))?
+ .to_string();
+ exact_facts.push(utf8_fact(vocabulary::file_type(), canonical)?);
+ }
+ projection(
+ input.record_key,
+ input.kind.partition(),
+ exact_facts,
+ input.created_at,
+ input.updated_at,
+ )
+}
+
+/// Generate a generic optimistic patch from partial direct Soup fields.
+pub fn patch_direct_fields(
+ input: DirectProjectionPatchInput,
+) -> Result<OptimisticProjectionMutation, ProjectionError> {
+ let mut exact = Vec::new();
+ if let Some(owner) = input.owner {
+ exact.push(ExactAttributePatch {
+ attribute: vocabulary::owner(),
+ values: vec![ExactValue::utf8(owner)?],
+ });
+ }
+ if let Some(project_id) = input.project_id {
+ exact.push(ExactAttributePatch {
+ attribute: vocabulary::project_id(),
+ values: project_id
+ .map(|project_id| ExactValue::new(project_id.as_bytes()))
+ .transpose()?
+ .into_iter()
+ .collect(),
+ });
+ }
+ if input.kind == SoupFlatEntityKind::Document
+ && let Some(file_type) = input.file_type
+ {
+ let values = file_type
+ .map(|file_type| -> Result<ExactValue, ProjectionError> {
+ let canonical = FileType::from_str(&file_type)
+ .map_err(|_| ProjectionError::InvalidFileType(file_type))?
+ .to_string();
+ Ok(ExactValue::utf8(canonical)?)
+ })
+ .transpose()?
+ .into_iter()
+ .collect();
+ exact.push(ExactAttributePatch {
+ attribute: vocabulary::file_type(),
+ values,
+ });
+ }
+
+ let mut integers = Vec::new();
+ let mut sorts = Vec::new();
+ if let Some(created_at) = input.created_at {
+ let value = utc_timestamp_micros(created_at);
+ integers.push(IntegerAttributePatch {
+ attribute: vocabulary::created_at(),
+ values: vec![value],
+ });
+ sorts.push(IntegerFact {
+ attribute: vocabulary::created_at(),
+ value,
+ });
+ }
+ let updated_at = utc_timestamp_micros(input.updated_at);
+ integers.push(IntegerAttributePatch {
+ attribute: vocabulary::updated_at(),
+ values: vec![updated_at],
+ });
+ sorts.push(IntegerFact {
+ attribute: vocabulary::updated_at(),
+ value: updated_at,
+ });
+
+ Ok(OptimisticProjectionMutation::Patch {
+ record_key: input.record_key,
+ profile: vocabulary::profile(),
+ partition: input.kind.partition(),
+ exact,
+ integers,
+ sorts,
+ })
+}
+
+#[cfg(feature = "models")]
+/// Project a supported authoritative Soup item using a caller-supplied normalized key.
+///
+/// Deferred entity variants return `None` and are never represented as complete
+/// `soup-flat-v1` index documents.
+pub fn project_soup_item<T>(
+ record_key: RecordKey,
+ item: &SoupItem<T>,
+) -> Result<Option<IndexDocument>, ProjectionError> {
+ match item {
+ SoupItem::Document(document) => project_document(record_key, document).map(Some),
+ SoupItem::Project(project) => project_project(record_key, project).map(Some),
+ SoupItem::Chat(chat) => project_chat(record_key, chat).map(Some),
+ SoupItem::EmailThread(_)
+ | SoupItem::Channel(_)
+ | SoupItem::ChannelThread(_)
+ | SoupItem::Call(_)
+ | SoupItem::CalendarEvent(_)
+ | SoupItem::CrmCompany(_)
+ | SoupItem::ForeignEntity(_)
+ | SoupItem::Reminder(_) => Ok(None),
+ }
+}
+
+/// Project direct Document fields required by `soup-flat-v1`.
+#[cfg(feature = "models")]
+pub fn project_document<T>(
+ record_key: RecordKey,
+ document: &SoupDocument<T>,
+) -> Result<IndexDocument, ProjectionError> {
+ project_direct_fields(DirectProjectionInput {
+ record_key,
+ kind: SoupFlatEntityKind::Document,
+ id: document.id,
+ owner: document.owner_id.to_string(),
+ project_id: document.project_id,
+ file_type: document.file_type.clone(),
+ created_at: document.created_at,
+ updated_at: document.updated_at,
+ })
+}
+
+/// Project direct Project fields required by `soup-flat-v1`.
+#[cfg(feature = "models")]
+pub fn project_project<T>(
+ record_key: RecordKey,
+ project: &SoupProject<T>,
+) -> Result<IndexDocument, ProjectionError> {
+ project_direct_fields(DirectProjectionInput {
+ record_key,
+ kind: SoupFlatEntityKind::Project,
+ id: project.id,
+ owner: project.owner_id.to_string(),
+ project_id: project.parent_id,
+ file_type: None,
+ created_at: project.created_at,
+ updated_at: project.updated_at,
+ })
+}
+
+/// Project direct Chat fields required by `soup-flat-v1`.
+#[cfg(feature = "models")]
+pub fn project_chat<T>(
+ record_key: RecordKey,
+ chat: &SoupChat<T>,
+) -> Result<IndexDocument, ProjectionError> {
+ project_direct_fields(DirectProjectionInput {
+ record_key,
+ kind: SoupFlatEntityKind::Chat,
+ id: chat.id,
+ owner: chat.owner_id.to_string(),
+ project_id: chat.project_id,
+ file_type: None,
+ created_at: chat.created_at,
+ updated_at: chat.updated_at,
+ })
+}
+
+fn common_exact_facts(id: uuid::Uuid, owner: String) -> Result<Vec<ExactFact>, ValidationError> {
+ Ok(vec![
+ uuid_fact(vocabulary::id(), id)?,
+ utf8_fact(vocabulary::owner(), owner)?,
+ ])
+}
+
+fn projection(
+ record_key: RecordKey,
+ partition: Token,
+ exact_facts: Vec<ExactFact>,
+ created_at: chrono::DateTime<chrono::Utc>,
+ updated_at: chrono::DateTime<chrono::Utc>,
+) -> Result<IndexDocument, ProjectionError> {
+ let created_at = IntegerFact {
+ attribute: vocabulary::created_at(),
+ value: utc_timestamp_micros(created_at),
+ };
+ let updated_at = IntegerFact {
+ attribute: vocabulary::updated_at(),
+ value: utc_timestamp_micros(updated_at),
+ };
+ let document = IndexDocument {
+ record_key,
+ profile: vocabulary::profile(),
+ partition,
+ exact_facts,
+ integer_facts: vec![created_at.clone(), updated_at.clone()],
+ sort_facts: vec![created_at, updated_at],
+ };
+ document.validate()?;
+ Ok(document)
+}
+
+fn uuid_fact(attribute: Token, value: uuid::Uuid) -> Result<ExactFact, ValidationError> {
+ Ok(ExactFact {
+ attribute,
+ value: ExactValue::new(value.as_bytes())?,
+ })
+}
+
+fn utf8_fact(attribute: Token, value: impl AsRef<str>) -> Result<ExactFact, ValidationError> {
+ Ok(ExactFact {
+ attribute,
+ value: ExactValue::utf8(value)?,
+ })
+}
diff --git a/crates/soup_filter_projection/src/test.rs b/crates/soup_filter_projection/src/test.rs
new file mode 100644
index 0000000000..a9d69109fb
--- /dev/null
+++ b/crates/soup_filter_projection/src/test.rs
@@ -0,0 +1,149 @@
+use chrono::{TimeZone, Utc};
+use macro_user_id::{cowlike::CowLike, user_id::MacroUserIdStr};
+use models_soup::{document::SoupDocument, project::SoupProject};
+use uuid::Uuid;
+
+use super::*;
+
+fn owner() -> MacroUserIdStr<'static> {
+ MacroUserIdStr::parse_from_str("macro|[email protected]")
+ .unwrap()
+ .into_owned()
+}
+
+fn timestamp(micros: u32) -> chrono::DateTime<Utc> {
+ Utc.with_ymd_and_hms(2026, 1, 1, 0, 0, 0).unwrap()
+ + chrono::Duration::microseconds(i64::from(micros))
+}
+
+#[test]
+fn document_projection_contains_only_direct_profile_facts() {
+ let id = Uuid::from_u128(1);
+ let project_id = Uuid::from_u128(2);
+ let document = SoupDocument {
+ id,
+ document_version_id: 3,
+ owner_id: owner(),
+ name: "Document".to_owned(),
+ file_type: Some("md".to_owned()),
+ sha: None,
+ project_id: Some(project_id),
+ branched_from_id: None,
+ branched_from_version_id: None,
+ document_family_id: None,
+ created_at: timestamp(123_456),
+ updated_at: timestamp(654_321),
+ viewed_at: None,
+ sub_type: None,
+ deleted_at: None,
+ extra: (),
+ };
+
+ let projection =
+ project_document(RecordKey::new("GraphqlSoupDocument:1").unwrap(), &document).unwrap();
+
+ assert_eq!(projection.profile, vocabulary::profile());
+ assert_eq!(projection.partition, vocabulary::document_partition());
+ assert_eq!(projection.exact_facts.len(), 4);
+ assert_eq!(projection.integer_facts.len(), 2);
+ assert_eq!(projection.sort_facts.len(), 2);
+ assert_eq!(
+ projection
+ .integer_facts
+ .iter()
+ .find(|fact| fact.attribute == vocabulary::created_at())
+ .unwrap()
+ .value
+ % 1_000_000,
+ 123_456
+ );
+}
+
+#[test]
+fn optimistic_direct_projection_and_patch_share_authoritative_vocabulary() {
+ let key = RecordKey::new("GraphqlSoupDocument:00000000-0000-0000-0000-000000000001").unwrap();
+ let projection = project_direct_fields(DirectProjectionInput {
+ record_key: key.clone(),
+ kind: SoupFlatEntityKind::Document,
+ id: Uuid::from_u128(1),
+ owner: "macro|[email protected]".to_owned(),
+ project_id: None,
+ file_type: Some(".MD".to_owned()),
+ created_at: timestamp(1),
+ updated_at: timestamp(2),
+ })
+ .unwrap();
+ assert!(projection.exact_facts.iter().any(|fact| {
+ fact.attribute == vocabulary::file_type() && fact.value == ExactValue::utf8("md").unwrap()
+ }));
+
+ let patch = patch_direct_fields(DirectProjectionPatchInput {
+ record_key: key,
+ kind: SoupFlatEntityKind::Document,
+ owner: None,
+ project_id: Some(Some(Uuid::from_u128(2))),
+ file_type: Some(None),
+ created_at: None,
+ updated_at: timestamp(3),
+ })
+ .unwrap();
+ let OptimisticProjectionMutation::Patch {
+ exact,
+ integers,
+ sorts,
+ ..
+ } = patch
+ else {
+ panic!("direct field patch must produce generic optimistic patch");
+ };
+ assert!(
+ exact.iter().any(|patch| {
+ patch.attribute == vocabulary::project_id() && patch.values.len() == 1
+ })
+ );
+ assert!(
+ exact
+ .iter()
+ .any(|patch| { patch.attribute == vocabulary::file_type() && patch.values.is_empty() })
+ );
+ assert!(integers.iter().any(|patch| {
+ patch.attribute == vocabulary::updated_at()
+ && patch.values == vec![utc_timestamp_micros(timestamp(3))]
+ }));
+ assert!(sorts.iter().any(|fact| {
+ fact.attribute == vocabulary::updated_at()
+ && fact.value == utc_timestamp_micros(timestamp(3))
+ }));
+}
+
+#[test]
+fn nullable_parent_facts_are_absent_and_not_semantics_remain_exact() {
+ let project = SoupProject {
+ id: Uuid::from_u128(1),
+ name: "Root".to_owned(),
+ owner_id: owner(),
+ parent_id: None,
+ created_at: timestamp(0),
+ updated_at: timestamp(0),
+ viewed_at: None,
+ deleted_at: None,
+ extra: (),
+ };
+ let projection =
+ project_project(RecordKey::new("GraphqlSoupProject:1").unwrap(), &project).unwrap();
+
+ assert!(
+ projection
+ .exact_facts
+ .iter()
+ .all(|fact| fact.attribute != vocabulary::project_id())
+ );
+ assert!(
+ projection.matches(&predicate_index::PredicateExpr::Not(Box::new(
+ predicate_index::PredicateExpr::Exact {
+ attribute: vocabulary::project_id(),
+ value: ExactValue::new(Uuid::from_u128(2).as_bytes()).unwrap(),
+ }
+ )))
+ );
+}
diff --git a/static_assets/schema.graphql b/static_assets/schema.graphql
index 87b8924a5a..ea046b5a76 100644
--- a/static_assets/schema.graphql
+++ b/static_assets/schema.graphql
@@ -425,11 +425,11 @@ The two operands of a recursive `CalendarEventFilterExpr` binary expression.
"""
input GraphqlCalendarEventBinaryExpr {
"""
- The left-hand expression.
+ Left expression.
"""
left: GraphqlCalendarEventExpr!
"""
- The right-hand expression.
+ Right expression.
"""
right: GraphqlCalendarEventExpr!
}
@@ -439,19 +439,19 @@ A recursive `CalendarEventFilterExpr` filter expression.
"""
input GraphqlCalendarEventExpr @oneOf {
"""
- Matches when both expressions match.
+ Both expressions must match.
"""
and: GraphqlCalendarEventBinaryExpr
"""
- Matches when either expression matches.
+ Either expression may match.
"""
or: GraphqlCalendarEventBinaryExpr
"""
- Negates an expression.
+ Negate an expression.
"""
not: GraphqlCalendarEventExpr
"""
- Matches a domain-specific literal condition.
+ Match a literal.
"""
literal: GraphqlCalendarEventLiteral
}
@@ -537,11 +537,11 @@ The two operands of a recursive `CallFilterExpr` binary expression.
"""
input GraphqlCallBinaryExpr {
"""
- The left-hand expression.
+ Left expression.
"""
left: GraphqlCallExpr!
"""
- The right-hand expression.
+ Right expression.
"""
right: GraphqlCallExpr!
}
@@ -551,19 +551,19 @@ A recursive `CallFilterExpr` filter expression.
"""
input GraphqlCallExpr @oneOf {
"""
- Matches when both expressions match.
+ Both expressions must match.
"""
and: GraphqlCallBinaryExpr
"""
- Matches when either expression matches.
+ Either expression may match.
"""
or: GraphqlCallBinaryExpr
"""
- Negates an expression.
+ Negate an expression.
"""
not: GraphqlCallExpr
"""
- Matches a domain-specific literal condition.
+ Match a literal.
"""
literal: GraphqlCallLiteral
}
@@ -665,11 +665,11 @@ The two operands of a recursive `ChannelFilterExpr` binary expression.
"""
input GraphqlChannelBinaryExpr {
"""
- The left-hand expression.
+ Left expression.
"""
left: GraphqlChannelExpr!
"""
- The right-hand expression.
+ Right expression.
"""
right: GraphqlChannelExpr!
}
@@ -679,19 +679,19 @@ A recursive `ChannelFilterExpr` filter expression.
"""
input GraphqlChannelExpr @oneOf {
"""
- Matches when both expressions match.
+ Both expressions must match.
"""
and: GraphqlChannelBinaryExpr
"""
- Matches when either expression matches.
+ Either expression may match.
"""
or: GraphqlChannelBinaryExpr
"""
- Negates an expression.
+ Negate an expression.
"""
not: GraphqlChannelExpr
"""
- Matches a domain-specific literal condition.
+ Match a literal.
"""
literal: GraphqlChannelLiteral
}
@@ -925,11 +925,11 @@ The two operands of a recursive `ChannelThreadFilterExpr` binary expression.
"""
input GraphqlChannelThreadBinaryExpr {
"""
- The left-hand expression.
+ Left expression.
"""
left: GraphqlChannelThreadExpr!
"""
- The right-hand expression.
+ Right expression.
"""
right: GraphqlChannelThreadExpr!
}
@@ -939,19 +939,19 @@ A recursive `ChannelThreadFilterExpr` filter expression.
"""
input GraphqlChannelThreadExpr @oneOf {
"""
- Matches when both expressions match.
+ Both expressions must match.
"""
and: GraphqlChannelThreadBinaryExpr
"""
- Matches when either expression matches.
+ Either expression may match.
"""
or: GraphqlChannelThreadBinaryExpr
"""
- Negates an expression.
+ Negate an expression.
"""
not: GraphqlChannelThreadExpr
"""
- Matches a domain-specific literal condition.
+ Match a literal.
"""
literal: GraphqlChannelThreadLiteral
}
@@ -1023,11 +1023,11 @@ The two operands of a recursive `ChatFilterExpr` binary expression.
"""
input GraphqlChatBinaryExpr {
"""
- The left-hand expression.
+ Left expression.
"""
left: GraphqlChatExpr!
"""
- The right-hand expression.
+ Right expression.
"""
right: GraphqlChatExpr!
}
@@ -1037,19 +1037,19 @@ A recursive `ChatFilterExpr` filter expression.
"""
input GraphqlChatExpr @oneOf {
"""
- Matches when both expressions match.
+ Both expressions must match.
"""
and: GraphqlChatBinaryExpr
"""
- Matches when either expression matches.
+ Either expression may match.
"""
or: GraphqlChatBinaryExpr
"""
- Negates an expression.
+ Negate an expression.
"""
not: GraphqlChatExpr
"""
- Matches a domain-specific literal condition.
+ Match a literal.
"""
literal: GraphqlChatLiteral
}
@@ -1157,11 +1157,11 @@ The two operands of a recursive `CrmCompanyFilterExpr` binary expression.
"""
input GraphqlCrmCompanyBinaryExpr {
"""
- The left-hand expression.
+ Left expression.
"""
left: GraphqlCrmCompanyExpr!
"""
- The right-hand expression.
+ Right expression.
"""
right: GraphqlCrmCompanyExpr!
}
@@ -1171,19 +1171,19 @@ A recursive `CrmCompanyFilterExpr` filter expression.
"""
input GraphqlCrmCompanyExpr @oneOf {
"""
- Matches when both expressions match.
+ Both expressions must match.
"""
and: GraphqlCrmCompanyBinaryExpr
"""
- Matches when either expression matches.
+ Either expression may match.
"""
or: GraphqlCrmCompanyBinaryExpr
"""
- Negates an expression.
+ Negate an expression.
"""
not: GraphqlCrmCompanyExpr
"""
- Matches a domain-specific literal condition.
+ Match a literal.
"""
literal: GraphqlCrmCompanyLiteral
}
@@ -1253,11 +1253,11 @@ The two operands of a recursive `DocumentFilterExpr` binary expression.
"""
input GraphqlDocumentBinaryExpr {
"""
- The left-hand expression.
+ Left expression.
"""
left: GraphqlDocumentExpr!
"""
- The right-hand expression.
+ Right expression.
"""
right: GraphqlDocumentExpr!
}
@@ -1267,19 +1267,19 @@ A recursive `DocumentFilterExpr` filter expression.
"""
input GraphqlDocumentExpr @oneOf {
"""
- Matches when both expressions match.
+ Both expressions must match.
"""
and: GraphqlDocumentBinaryExpr
"""
- Matches when either expression matches.
+ Either expression may match.
"""
or: GraphqlDocumentBinaryExpr
"""
- Negates an expression.
+ Negate an expression.
"""
not: GraphqlDocumentExpr
"""
- Matches a domain-specific literal condition.
+ Match a literal.
"""
literal: GraphqlDocumentLiteral
}
@@ -1419,11 +1419,11 @@ The two operands of a recursive `EmailFilterExpr` binary expression.
"""
input GraphqlEmailBinaryExpr {
"""
- The left-hand expression.
+ Left expression.
"""
left: GraphqlEmailExpr!
"""
- The right-hand expression.
+ Right expression.
"""
right: GraphqlEmailExpr!
}
@@ -1433,19 +1433,19 @@ A recursive `EmailFilterExpr` filter expression.
"""
input GraphqlEmailExpr @oneOf {
"""
- Matches when both expressions match.
+ Both expressions must match.
"""
and: GraphqlEmailBinaryExpr
"""
- Matches when either expression matches.
+ Either expression may match.
"""
or: GraphqlEmailBinaryExpr
"""
- Negates an expression.
+ Negate an expression.
"""
not: GraphqlEmailExpr
"""
- Matches a domain-specific literal condition.
+ Match a literal.
"""
literal: GraphqlEmailLiteral
}
@@ -1769,7 +1769,7 @@ input GraphqlEntityFilterAst {
"""
The properties filter to apply.
"""
- propertiesFilter: GraphqlPropertiesExpr
+ propertiesFilter: GraphqlFilterPropertiesExpr
}
"""
@@ -1947,16 +1947,84 @@ enum GraphqlEntityType {
AGENT_SESSION
}
+"""
+The two operands of a recursive `PropertiesFilterExpr` binary expression.
+"""
+input GraphqlFilterPropertiesBinaryExpr {
+ """
+ Left expression.
+ """
+ left: GraphqlFilterPropertiesExpr!
+ """
+ Right expression.
+ """
+ right: GraphqlFilterPropertiesExpr!
+}
+
+"""
+A recursive `PropertiesFilterExpr` filter expression.
+"""
+input GraphqlFilterPropertiesExpr @oneOf {
+ """
+ Both expressions must match.
+ """
+ and: GraphqlFilterPropertiesBinaryExpr
+ """
+ Either expression may match.
+ """
+ or: GraphqlFilterPropertiesBinaryExpr
+ """
+ Negate an expression.
+ """
+ not: GraphqlFilterPropertiesExpr
+ """
+ Match a literal.
+ """
+ literal: GraphqlFilterPropertiesLiteral
+}
+
+"""
+GraphQL input for matching a property value on an entity.
+"""
+input GraphqlFilterPropertiesLiteral {
+ """
+ Property definition id to match.
+ """
+ propertyDefinitionId: ID!
+ """
+ Optional entity type scope for the property match.
+ """
+ entityType: GraphqlPropertyEntityType
+ """
+ Value to compare against the property.
+ """
+ value: GraphqlFilterPropertyMatchValue!
+}
+
+"""
+GraphQL input value used when matching a property.
+"""
+input GraphqlFilterPropertyMatchValue @oneOf {
+ """
+ Select option id to match.
+ """
+ selectOption: ID
+ """
+ Entity reference id to match.
+ """
+ entityRef: ID
+}
+
"""
The two operands of a recursive `ForeignEntityFilterExpr` binary expression.
"""
input GraphqlForeignEntityBinaryExpr {
"""
- The left-hand expression.
+ Left expression.
"""
left: GraphqlForeignEntityExpr!
"""
- The right-hand expression.
+ Right expression.
"""
right: GraphqlForeignEntityExpr!
}
@@ -1966,19 +2034,19 @@ A recursive `ForeignEntityFilterExpr` filter expression.
"""
input GraphqlForeignEntityExpr @oneOf {
"""
- Matches when both expressions match.
+ Both expressions must match.
"""
and: GraphqlForeignEntityBinaryExpr
"""
- Matches when either expression matches.
+ Either expression may match.
"""
or: GraphqlForeignEntityBinaryExpr
"""
- Negates an expression.
+ Negate an expression.
"""
not: GraphqlForeignEntityExpr
"""
- Matches a domain-specific literal condition.
+ Match a literal.
"""
literal: GraphqlForeignEntityLiteral
}
@@ -2840,11 +2908,11 @@ The two operands of a recursive `ProjectFilterExpr` binary expression.
"""
input GraphqlProjectBinaryExpr {
"""
- The left-hand expression.
+ Left expression.
"""
left: GraphqlProjectExpr!
"""
- The right-hand expression.
+ Right expression.
"""
right: GraphqlProjectExpr!
}
@@ -2854,19 +2922,19 @@ A recursive `ProjectFilterExpr` filter expression.
"""
input GraphqlProjectExpr @oneOf {
"""
- Matches when both expressions match.
+ Both expressions must match.
"""
and: GraphqlProjectBinaryExpr
"""
- Matches when either expression matches.
+ Either expression may match.
"""
or: GraphqlProjectBinaryExpr
"""
- Negates an expression.
+ Negate an expression.
"""
not: GraphqlProjectExpr
"""
- Matches a domain-specific literal condition.
+ Match a literal.
"""
literal: GraphqlProjectLiteral
}
@@ -2909,60 +2977,6 @@ input GraphqlProjectLiteral @oneOf {
updatedAt: GraphqlDateLiteral
}
-"""
-The two operands of a recursive `PropertiesFilterExpr` binary expression.
-"""
-input GraphqlPropertiesBinaryExpr {
- """
- The left-hand expression.
- """
- left: GraphqlPropertiesExpr!
- """
- The right-hand expression.
- """
- right: GraphqlPropertiesExpr!
-}
-
-"""
-A recursive `PropertiesFilterExpr` filter expression.
-"""
-input GraphqlPropertiesExpr @oneOf {
- """
- Matches when both expressions match.
- """
- and: GraphqlPropertiesBinaryExpr
- """
- Matches when either expression matches.
- """
- or: GraphqlPropertiesBinaryExpr
- """
- Negates an expression.
- """
- not: GraphqlPropertiesExpr
- """
- Matches a domain-specific literal condition.
- """
- literal: GraphqlPropertiesLiteral
-}
-
-"""
-GraphQL input for matching a property value on an entity.
-"""
-input GraphqlPropertiesLiteral {
- """
- Property definition id to match.
- """
- propertyDefinitionId: ID!
- """
- Optional entity type scope for the property match.
- """
- entityType: GraphqlPropertyEntityType
- """
- Value to compare against the property.
- """
- value: GraphqlPropertyMatchValue!
-}
-
"""
A property assignment and its current value.
"""
@@ -3111,20 +3125,6 @@ enum GraphqlPropertyEntityType {
USER
}
-"""
-GraphQL input value used when matching a property.
-"""
-input GraphqlPropertyMatchValue @oneOf {
- """
- Select option id to match.
- """
- selectOption: ID
- """
- Entity reference id to match.
- """
- entityRef: String
-}
-
"""
Canonical entity type accepted for property targets.
"""
@@ -3173,11 +3173,11 @@ The two operands of a recursive `ReminderFilterExpr` binary expression.
"""
input GraphqlReminderBinaryExpr {
"""
- The left-hand expression.
+ Left expression.
"""
left: GraphqlReminderExpr!
"""
- The right-hand expression.
+ Right expression.
"""
right: GraphqlReminderExpr!
}
@@ -3187,19 +3187,19 @@ A recursive `ReminderFilterExpr` filter expression.
"""
input GraphqlReminderExpr @oneOf {
"""
- Matches when both expressions match.
+ Both expressions must match.
"""
and: GraphqlReminderBinaryExpr
"""
- Matches when either expression matches.
+ Either expression may match.
"""
or: GraphqlReminderBinaryExpr
"""
- Negates an expression.
+ Negate an expression.
"""
not: GraphqlReminderExpr
"""
- Matches a domain-specific literal condition.
+ Match a literal.
"""
literal: GraphqlReminderLiteral
}