Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
TypeScript agentaiai-agentsall-in-onecrmcrm-systememaillinearmcpmessagingnotesnotionofficerustslackslack-alternativestartupstartup-toolstypescriptworkspace
Seanaye/feat/turso backed cache (#5686)
Sean Ayea581dfb26a7a
diff --git a/.github/workflows/deploy_on_push.yml b/.github/workflows/deploy_on_push.ymlindex ea7bd50d12..543172ff84 100644--- a/.github/workflows/deploy_on_push.yml+++ b/.github/workflows/deploy_on_push.yml@@ -23,7 +23,7 @@ jobs:diff: |-cloud-storage: ./Cargo.toml ./Cargo.lock ./Cross.toml ./clippy.toml ./deny.toml ./rust-toolchain.toml ./.cargo/** ./.config/** ./.sqlx/** ./crates/** ./services/** ./tooling/xtask/** ./tooling/just/** ./tooling/scripts/** ./static_assets/** ./docker/** ./nix/** ./nix-support/** ./infra/** ./.github/workflows/deploy_on_push.yml ./.github/workflows/deploy_all_services.yml ./.github/actions/deploy-cloud-storage-pulumi/** ./.github/actions/setup-nix/** ./.github/actions/teardown-nix/** ./.github/actions/migrate-cloud-storage-db/** ./.github/scripts/build-cloud-storage-lambdas-nix.sh ./.github/services-config.json ./.github/workspace-dep-closures.json ./flake.nix ./flake.locksync-service: ./services/sync-service/** ./crates/macro_sync_service_jwt/** ./Cargo.toml ./Cargo.lock ./rust-toolchain.toml ./.github/workflows/deploy_on_push.yml ./.github/workflows/deploy_sync_service.yml- web-app: ./infra/stacks/web-app/** ./.github/workflows/deploy_on_push.yml ./.github/workflows/deploy_web_app.yml ./package.json ./bun.lock ./apps/web/** ./packages/** ./crates/client/cache-core/** ./crates/client/cache-idb/** ./crates/client/cache-wasm/** ./static_assets/schema.graphql ./Cargo.toml ./Cargo.lock ./rust-toolchain.toml+ web-app: ./infra/stacks/web-app/** ./.github/workflows/deploy_on_push.yml ./.github/workflows/deploy_web_app.yml ./package.json ./bun.lock ./apps/web/** ./packages/** ./crates/client/cache-core/** ./crates/client/cache-turso/** ./crates/client/cache-wasm/** ./crates/client/turso-opfs/** ./static_assets/schema.graphql ./Cargo.toml ./Cargo.lock ./rust-toolchain.tomldeploy-cloud-storage:needs:- check-to-deploydiff --git a/.github/workflows/deploy_preview.yml b/.github/workflows/deploy_preview.ymlindex bb4975a2a6..9cb651a2d2 100644--- a/.github/workflows/deploy_preview.yml+++ b/.github/workflows/deploy_preview.yml@@ -14,8 +14,9 @@ env:- apps/web/**- packages/**- crates/client/cache-core/**- - crates/client/cache-idb/**+ - crates/client/cache-turso/**- crates/client/cache-wasm/**+ - crates/client/turso-opfs/**- static_assets/schema.graphql- Cargo.toml- Cargo.lockdiff --git a/.github/workflows/web-app-check-main.yml b/.github/workflows/web-app-check-main.ymlindex 71c4475d10..83122ff172 100644--- a/.github/workflows/web-app-check-main.yml+++ b/.github/workflows/web-app-check-main.yml@@ -30,8 +30,9 @@ jobs:- 'apps/web/**'- 'packages/**'- 'crates/client/cache-core/**'- - 'crates/client/cache-idb/**'+ - 'crates/client/cache-turso/**'- 'crates/client/cache-wasm/**'+ - 'crates/client/turso-opfs/**'- 'static_assets/schema.graphql'- 'Cargo.toml'- 'Cargo.lock'diff --git a/.github/workspace-dep-closures.json b/.github/workspace-dep-closures.jsonindex 3381836510..6ba1324ea3 100644--- a/.github/workspace-dep-closures.json+++ b/.github/workspace-dep-closures.json@@ -593,20 +593,22 @@"crates/client/cache-core","crates/maybe_send"],- "cache-idb": [+ "cache-sqlite": ["crates/client/cache-core",- "crates/client/cache-idb",+ "crates/client/cache-sqlite","crates/maybe_send"],- "cache-sqlite": [+ "cache-turso": ["crates/client/cache-core",- "crates/client/cache-sqlite",+ "crates/client/cache-turso",+ "crates/client/turso-opfs","crates/maybe_send"],"cache-wasm": ["crates/client/cache-core",- "crates/client/cache-idb",+ "crates/client/cache-turso","crates/client/cache-wasm",+ "crates/client/turso-opfs","crates/maybe_send"],"cal": [@@ -6329,6 +6331,9 @@"crates/unfurl","crates/workspace-hack"],+ "turso-opfs": [+ "crates/client/turso-opfs"+ ],"unfurl": ["crates/unfurl","crates/workspace-hack"diff --git a/Cargo.lock b/Cargo.lockindex 371a5d6554..7ec14480c9 100644--- a/Cargo.lock+++ b/Cargo.lock@@ -48,6 +48,16 @@ dependencies = ["generic-array",]+[[package]]+name = "aegis"+version = "0.9.8"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "78412fa53e6da95324e8902c3641b3ff32ab45258582ea997eb9169c68ffa219"+dependencies = [+ "cc",+ "softaes",+]+[[package]]name = "aes"version = "0.8.4"@@ -410,6 +420,12 @@ version = "0.2.21"source = "registry+https://github.com/rust-lang/crates.io-index"checksum = "683d7910e743518b0e34f1186f92494becacb047c7b6bf616c96772180fef923"+[[package]]+name = "allocator-api2"+version = "0.4.0"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "c880a97d28a3681c0267bd29cff89621202715b065127cd445fa0f0fe0aa2880"+[[package]]name = "ammonia"version = "4.1.4"@@ -522,6 +538,22 @@ dependencies = ["workspace-hack",]+[[package]]+name = "antithesis_sdk"+version = "0.2.9"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "08410fcac93669a476c006cd6c4512ac1e2b30fd117231a5d55d8a2c76599b82"+dependencies = [+ "libc",+ "libloading",+ "linkme",+ "once_cell",+ "rand 0.8.6",+ "rustc_version_runtime",+ "serde",+ "serde_json",+]+[[package]]name = "anyhow"version = "1.0.103"@@ -587,6 +619,15 @@ dependencies = ["derive_arbitrary",]+[[package]]+name = "arc-swap"+version = "1.9.2"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "c049c0be4daef0b145cb3555416b3b8ef5b7888a38aea1a3a155801fe7b0810b"+dependencies = [+ "rustversion",+]+[[package]]name = "arcstr"version = "1.2.0"@@ -615,6 +656,26 @@ dependencies = ["yansi",]+[[package]]+name = "aristo"+version = "0.4.1"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "fcdeefa800110050103e2459a2f8dbdbd560ad046e30f1f87e24ce19c2cb8bde"+dependencies = [+ "aristo-macros",+]++[[package]]+name = "aristo-macros"+version = "0.4.1"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "d64a66d21a80182b35b1741997a6d2456911f54b7eb1918aa4e2382fc205268d"+dependencies = [+ "proc-macro2",+ "quote",+ "syn 2.0.117",+]+[[package]]name = "arrayvec"version = "0.5.2"@@ -706,6 +767,12 @@ dependencies = ["serde_json",]+[[package]]+name = "assoc"+version = "0.1.3"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "bfdc70193dadb9d7287fa4b633f15f90c876915b31f6af17da307fc59c9859a8"+[[package]]name = "async-channel"version = "1.9.0"@@ -2127,6 +2194,19 @@ dependencies = ["bitflags 1.3.2",]+[[package]]+name = "bigdecimal"+version = "0.4.10"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "4d6867f1565b3aad85681f1015055b087fcfd840d6aeee6eee7f2da317603695"+dependencies = [+ "autocfg",+ "libm",+ "num-bigint",+ "num-integer",+ "num-traits",+]+[[package]]name = "bindgen"version = "0.71.1"@@ -2201,6 +2281,18 @@ dependencies = ["no_std_io2",]+[[package]]+name = "bitvec"+version = "1.1.1"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "ddcec3d12c579d40898fe0a9a358a803c23e9c52ca3c425707f81c9436211837"+dependencies = [+ "funty",+ "radium",+ "tap",+ "wyz",+]+[[package]]name = "block-buffer"version = "0.10.4"@@ -2340,6 +2432,15 @@ dependencies = ["workspace-hack",]+[[package]]+name = "branches"+version = "0.4.5"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "b8fba76cd916045514e3064707df9ed5282b94419444c2753a6c62ecaf458e56"+dependencies = [+ "rustc_version",+]+[[package]]name = "broadcast"version = "0.1.0"@@ -2388,6 +2489,20 @@ name = "bytemuck"version = "1.25.0"source = "registry+https://github.com/rust-lang/crates.io-index"checksum = "c8efb64bd706a16a1bdde310ae86b351e4d21550d98d056f22f8a7f7a2183fec"+dependencies = [+ "bytemuck_derive",+]++[[package]]+name = "bytemuck_derive"+version = "1.12.0"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "fc0e56a716f1e132ff6bf4bdac1c944a3fcdc1cae65f70a4a2a1ac3b401d2d1f"+dependencies = [+ "proc-macro2",+ "quote",+ "syn 3.0.3",+][[package]]name = "byteorder"@@ -2457,42 +2572,44 @@ dependencies = [][[package]]-name = "cache-idb"+name = "cache-sqlite"version = "0.1.0"dependencies = ["cache-core",- "idb",- "js-sys",+ "pollster",+ "rusqlite","serde_json",+ "tempfile","thiserror 2.0.18",- "wasm-bindgen",- "wasm-bindgen-test",- "web-sys",][[package]]-name = "cache-sqlite"+name = "cache-turso"version = "0.1.0"dependencies = ["cache-core",+ "cache-sqlite",+ "maybe_send","pollster",- "rusqlite","serde_json",- "tempfile","thiserror 2.0.18",+ "turso-opfs",+ "turso_core",+ "wasm-bindgen-test",][[package]]name = "cache-wasm"-version = "0.3.2"+version = "0.4.0"dependencies = ["async-lock","cache-core",- "cache-idb",+ "cache-turso","js-sys","serde","serde-wasm-bindgen","serde_json",+ "turso-opfs","wasm-bindgen","wasm-bindgen-futures","wasm-bindgen-test",@@ -2755,6 +2872,12 @@ version = "0.2.1"source = "registry+https://github.com/rust-lang/crates.io-index"checksum = "613afe47fcd5fac7ccf1db93babcb082c5994d996f20b8b159f2ad1658eb5724"+[[package]]+name = "cfg_block"+version = "0.1.1"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "18758054972164c3264f7c8386f5fc6da6114cb46b619fd365d4e3b2dc3ae487"+[[package]]name = "chacha20"version = "0.10.0"@@ -3593,6 +3716,15 @@ version = "0.4.0"source = "registry+https://github.com/rust-lang/crates.io-index"checksum = "338089f42c427b86394a5ee60ff321da23a5c89c9d89514c829687b26359fcff"+[[package]]+name = "crc32c"+version = "0.6.8"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "3a47af21622d091a8f0fb295b88bc886ac74efcc613efc19f5d0b21de5c89e47"+dependencies = [+ "rustc_version",+]+[[package]]name = "crc32fast"version = "1.5.0"@@ -5640,6 +5772,17 @@ dependencies = ["ascii_utils",]+[[package]]+name = "fastbloom"+version = "0.14.1"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "4e7f34442dbe69c60fe8eaf58a8cafff81a1f278816d8ab4db255b3bef4ac3c4"+dependencies = [+ "getrandom 0.3.4",+ "libm",+ "siphasher 1.0.3",+]+[[package]]name = "fastrand"version = "1.9.0"@@ -5863,6 +6006,12 @@ version = "1.3.0"source = "registry+https://github.com/rust-lang/crates.io-index"checksum = "42703706b716c37f96a77aea830392ad231f44c9e9a67872fa5548707e11b11c"+[[package]]+name = "funty"+version = "2.0.0"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "e6d5a32815ae3f33302d95fdcb2ce17862f8c65363dcfd29360480ba1001fc9c"+[[package]]name = "fusionauth"version = "0.1.0"@@ -6171,11 +6320,13 @@ source = "registry+https://github.com/rust-lang/crates.io-index"checksum = "0de51e6874e94e7bf76d726fc5d13ba782deca734ff60d5bb2fb2607c7406555"dependencies = ["cfg-if",+ "js-sys","libc","r-efi 6.0.0","rand_core 0.10.1","wasip2","wasip3",+ "wasm-bindgen",][[package]]@@ -6700,7 +6851,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"checksum = "e5274423e17b7c9fc20b6e7e208532f9b19825d82dfd615708b70edd83df41f1"dependencies = ["ahash",- "allocator-api2",+ "allocator-api2 0.2.21",][[package]]@@ -6709,7 +6860,7 @@ version = "0.15.5"source = "registry+https://github.com/rust-lang/crates.io-index"checksum = "9229cfe53dfd69f0609a49f65461bd93001ea1ef889cd5529dd176593f5338a1"dependencies = [- "allocator-api2",+ "allocator-api2 0.2.21","equivalent","foldhash 0.1.5",]@@ -6720,7 +6871,7 @@ version = "0.16.1"source = "registry+https://github.com/rust-lang/crates.io-index"checksum = "841d1cc9bed7f9236f321df977030373f4a4163ae1a7dbfe1a51a2c1a51d9100"dependencies = [- "allocator-api2",+ "allocator-api2 0.2.21","equivalent","foldhash 0.2.0",]@@ -6731,7 +6882,7 @@ version = "0.17.1"source = "registry+https://github.com/rust-lang/crates.io-index"checksum = "ed5909b6e89a2db4456e54cd5f673791d7eca6732202bbf2a9cc504fe2f9b84a"dependencies = [- "allocator-api2",+ "allocator-api2 0.2.21","equivalent","foldhash 0.2.0",]@@ -7281,6 +7432,31 @@ dependencies = ["cc",]+[[package]]+name = "icu_collator"+version = "2.2.1"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "8bbdf98e5e0aa827770acee171ebb568aaab975a36b56afdb5fd0e2f525750bb"+dependencies = [+ "icu_collator_data",+ "icu_collections",+ "icu_locale",+ "icu_locale_core",+ "icu_normalizer",+ "icu_properties",+ "icu_provider",+ "smallvec",+ "utf16_iter",+ "utf8_iter",+ "zerovec",+]++[[package]]+name = "icu_collator_data"+version = "2.2.0"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "038ed8e5817f2059c2f3efb0945ba78d060d3d25e8f1a1bea5139f821a21a2f0"+[[package]]name = "icu_collections"version = "2.2.0"@@ -7295,6 +7471,21 @@ dependencies = ["zerovec",]+[[package]]+name = "icu_locale"+version = "2.2.0"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "d5a396343c7208121dc86e35623d3dfe19814a7613cfd14964994cdc9c9a2e26"+dependencies = [+ "icu_collections",+ "icu_locale_core",+ "icu_locale_data",+ "icu_provider",+ "potential_utf",+ "tinystr",+ "zerovec",+]+[[package]]name = "icu_locale_core"version = "2.2.0"@@ -7303,11 +7494,18 @@ checksum = "92219b62b3e2b4d88ac5119f8904c10f8f61bf7e95b640d25ba3075e6cac2c29"dependencies = ["displaydoc","litemap",+ "serde","tinystr","writeable","zerovec",]+[[package]]+name = "icu_locale_data"+version = "2.2.0"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "d5fdcc9ac77c6d74ff5cf6e65ef3181d6af32003b16fce3a77fb451d2f695993"+[[package]]name = "icu_normalizer"version = "2.2.0"@@ -7319,6 +7517,9 @@ dependencies = ["icu_properties","icu_provider","smallvec",+ "utf16_iter",+ "utf8_iter",+ "write16","zerovec",]@@ -7356,6 +7557,8 @@ checksum = "139c4cf31c8b5f33d7e199446eff9c1e02decfc2f0eec2c8d71f65befa45b421"dependencies = ["displaydoc","icu_locale_core",+ "serde",+ "stable_deref_trait","writeable","yoke","zerofrom",@@ -7369,28 +7572,13 @@ version = "2.3.0"source = "registry+https://github.com/rust-lang/crates.io-index"checksum = "3d3067d79b975e8844ca9eb072e16b31c3c1c36928edf9c6789548c524d0d954"-[[package]]-name = "idb"-version = "0.6.5"-source = "registry+https://github.com/rust-lang/crates.io-index"-checksum = "6554f394e990a1af530a528a7fdcad6e01b29cb1b990f89df3ffd62cf15f7828"-dependencies = [- "indexmap 2.14.0",- "js-sys",- "num-traits",- "thiserror 2.0.18",- "tokio",- "wasm-bindgen",- "web-sys",-]-[[package]]name = "iddqd"version = "0.3.18"source = "registry+https://github.com/rust-lang/crates.io-index"checksum = "616230c7d641ef971a3a5bfcc654c6b7524ab9c9fb665693c6a397dba9a14aca"dependencies = [- "allocator-api2",+ "allocator-api2 0.2.21","equivalent","foldhash 0.2.0","hashbrown 0.16.1",@@ -7708,6 +7896,15 @@ dependencies = ["syn 2.0.117",]+[[package]]+name = "intrusive-collections"+version = "0.9.7"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "189d0897e4cbe8c75efedf3502c18c887b05046e59d28404d4d8e46cbc4d1e86"+dependencies = [+ "memoffset",+]+[[package]]name = "invite_email"version = "0.1.0"@@ -8265,6 +8462,26 @@ dependencies = ["vcpkg",]+[[package]]+name = "linkme"+version = "0.3.37"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "3045e122bd98aef8ec3ad58ce84f0791f64e70163d1a02710af4aa11a4d54cc5"+dependencies = [+ "linkme-impl",+]++[[package]]+name = "linkme-impl"+version = "0.3.37"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "77060ebe535362c3da75682cd17b0431017b6e7c5661e714fc69a7ad017d1301"+dependencies = [+ "proc-macro2",+ "quote",+ "syn 3.0.3",+]+[[package]]name = "linux-raw-sys"version = "0.4.15"@@ -9279,6 +9496,15 @@ version = "2.8.0"source = "registry+https://github.com/rust-lang/crates.io-index"checksum = "f8ca58f447f06ed17d5fc4043ce1b10dd205e060fb3ce5b979b8ed8e59ff3f79"+[[package]]+name = "memoffset"+version = "0.9.1"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "488016bfae457b036d996092f6cb448677611ce4449e970ceaf42695203f218a"+dependencies = [+ "autocfg",+]+[[package]]name = "memory"version = "0.1.0"@@ -9366,6 +9592,28 @@ dependencies = ["syn 2.0.117",]+[[package]]+name = "miette"+version = "7.6.0"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "5f98efec8807c63c752b5bd61f862c165c115b0a35685bdcfd9238c7aeb592b7"+dependencies = [+ "cfg-if",+ "miette-derive",+ "unicode-width 0.1.14",+]++[[package]]+name = "miette-derive"+version = "7.6.0"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "db5b29714e950dbb20d5e6f74f9dcec4edbcc1067bb7f8ed198c097b8c1a818b"+dependencies = [+ "proc-macro2",+ "quote",+ "syn 2.0.117",+]+[[package]]name = "mime"version = "0.3.17"@@ -10845,6 +11093,15 @@ dependencies = ["sha2 0.10.9",]+[[package]]+name = "pack1"+version = "1.1.0"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "e3b7bb0ecf2e447b1f20ee94ee79ef6eed1e9d4b3c36ce1903b9dea3bf205523"+dependencies = [+ "bytemuck",+]+[[package]]name = "parking"version = "2.2.1"@@ -11429,6 +11686,8 @@ version = "0.1.5"source = "registry+https://github.com/rust-lang/crates.io-index"checksum = "0103b1cef7ec0cf76490e969665504990193874ea05c85ff9bab8b911d0a0564"dependencies = [+ "serde_core",+ "writeable","zerovec",]@@ -11923,6 +12182,12 @@ version = "6.0.0"source = "registry+https://github.com/rust-lang/crates.io-index"checksum = "f8dcc9c7d52a811697d2151c701e0d08956f92b0e24136cf4cf27b57a6a0d9bf"+[[package]]+name = "radium"+version = "0.7.0"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "dc33ff2d4973d518d823d61aa239014831e521c75da58e3df4840d3f47749d09"+[[package]]name = "rand"version = "0.7.3"@@ -12040,6 +12305,15 @@ dependencies = ["rand_core 0.5.1",]+[[package]]+name = "rand_pcg"+version = "0.3.1"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "59cad018caf63deb318e5a4586d99a24424a364f40f1e5778c29aca23f4fc73e"+dependencies = [+ "rand_core 0.6.4",+]+[[package]]name = "rand_xorshift"version = "0.4.0"@@ -12058,6 +12332,15 @@ dependencies = ["rand_core 0.6.4",]+[[package]]+name = "rapidhash"+version = "4.5.1"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "5da7e78a036ce858e8d55b7e7dc8ba3a88b78350fd2155d3591bbd966b58589e"+dependencies = [+ "rustversion",+]+[[package]]name = "rate_limit"version = "0.1.0"@@ -12628,6 +12911,16 @@ dependencies = ["syn 2.0.117",]+[[package]]+name = "roaring"+version = "0.11.4"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "1dedc5658c6ecb3bdb5ef5f3295bb9253f42dcf3fd1402c03f6b1f7659c3c4a9"+dependencies = [+ "bytemuck",+ "byteorder",+]+[[package]]name = "roles_and_permissions"version = "0.1.0"@@ -12787,6 +13080,16 @@ dependencies = ["semver",]+[[package]]+name = "rustc_version_runtime"+version = "0.3.0"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "2dd18cd2bae1820af0b6ad5e54f4a51d0f3fcc53b05f845675074efcc7af071d"+dependencies = [+ "rustc_version",+ "semver",+]+[[package]]name = "rustix"version = "0.38.44"@@ -13858,6 +14161,26 @@ version = "1.3.0"source = "registry+https://github.com/rust-lang/crates.io-index"checksum = "0fda2ff0d084019ba4d7c6f371c95d8fd75ce3524c3cb8fb653a3023f6323e64"+[[package]]+name = "shuttle"+version = "0.8.1"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "2ab17edba38d63047f46780cf7360acf7467fec2c048928689a5c1dd1c2b4e31"+dependencies = [+ "assoc",+ "bitvec",+ "cfg-if",+ "generator",+ "hex",+ "owo-colors",+ "rand 0.8.6",+ "rand_core 0.6.4",+ "rand_pcg",+ "scoped-tls",+ "smallvec",+ "tracing",+]+[[package]]name = "signal-hook"version = "0.3.18"@@ -13942,6 +14265,15 @@ dependencies = ["time",]+[[package]]+name = "simsimd"+version = "6.5.16"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "f4fb3bc3cdce07a7d7d4caa4c54f8aa967f6be41690482b54b24100a2253fa70"+dependencies = [+ "cc",+]+[[package]]name = "siphasher"version = "0.3.11"@@ -14070,6 +14402,12 @@ dependencies = ["windows-sys 0.61.2",]+[[package]]+name = "softaes"+version = "0.1.5"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "45e14297decde697ddf377c25752aead0927d5cfc89c2684d2af96901a4ceeea"+[[package]]name = "soup"version = "0.1.0"@@ -14616,6 +14954,15 @@ version = "0.11.1"source = "registry+https://github.com/rust-lang/crates.io-index"checksum = "7da8b5736845d9f2fcb837ea5d9e2628564b3b043a70948a3f0b778838c5fb4f"+[[package]]+name = "strum"+version = "0.26.3"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "8fec0f0aef304996cf250b31b5a10dee7980c85da9d759361292b8bca5a18f06"+dependencies = [+ "strum_macros 0.26.4",+]+[[package]]name = "strum"version = "0.27.2"@@ -14634,6 +14981,19 @@ dependencies = ["strum_macros 0.28.0",]+[[package]]+name = "strum_macros"+version = "0.26.4"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "4c6bee85a5a24955dc440386795aa378cd9cf82acd5f764469152d2270e581be"+dependencies = [+ "heck 0.5.0",+ "proc-macro2",+ "quote",+ "rustversion",+ "syn 2.0.117",+]+[[package]]name = "strum_macros"version = "0.27.2"@@ -14836,6 +15196,12 @@ version = "0.2.0"source = "registry+https://github.com/rust-lang/crates.io-index"checksum = "7b2093cf4c8eb1e67749a6762251bc9cd836b6fc171623bd0a9d324d37af2417"+[[package]]+name = "tap"+version = "1.0.1"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "55937e1799185b12863d447f42597ed69d9928686b8d88a1df17376a097d8369"+[[package]]name = "target-lexicon"version = "0.13.5"@@ -15099,6 +15465,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"checksum = "c8323304221c2a851516f22236c5722a72eaa19749016521d6dff0824447d96d"dependencies = ["displaydoc",+ "serde_core","zerovec",]@@ -15631,6 +15998,123 @@ dependencies = ["url",]+[[package]]+name = "turso-opfs"+version = "0.1.0"+dependencies = [+ "js-sys",+ "turso_core",+ "wasm-bindgen",+ "wasm-bindgen-futures",+ "wasm-bindgen-test",+ "web-sys",+]++[[package]]+name = "turso_core"+version = "0.8.0-pre.3"+source = "git+https://github.com/seanaye/turso?rev=be9acfe9e5e6efb17911af84047e4855cace53a3#be9acfe9e5e6efb17911af84047e4855cace53a3"+dependencies = [+ "aegis",+ "aes",+ "aes-gcm",+ "allocator-api2 0.4.0",+ "antithesis_sdk",+ "arc-swap",+ "aristo",+ "bigdecimal",+ "bitflags 2.11.1",+ "branches",+ "bumpalo",+ "bytemuck",+ "cfg_aliases",+ "cfg_block",+ "chrono",+ "crc32c",+ "crossbeam-epoch",+ "crossbeam-utils",+ "either",+ "fallible-iterator 0.3.0",+ "fastbloom",+ "getrandom 0.2.17",+ "getrandom 0.3.4",+ "hex",+ "icu_collator",+ "icu_locale",+ "intrusive-collections",+ "libc",+ "libloading",+ "libm",+ "loom",+ "miette",+ "num-bigint",+ "num-traits",+ "pack1",+ "parking_lot",+ "pastey 0.2.3",+ "polling",+ "rand 0.9.4",+ "rapidhash",+ "regex",+ "regex-syntax",+ "roaring",+ "rustc-hash 2.1.2",+ "rustix 1.1.4",+ "ryu",+ "serde_json",+ "shuttle",+ "simdutf8",+ "simsimd",+ "smallvec",+ "strum 0.26.3",+ "strum_macros 0.26.4",+ "tempfile",+ "thiserror 2.0.18",+ "tracing",+ "tracing-subscriber",+ "turso_ext",+ "turso_macros",+ "turso_parser",+ "twox-hash",+ "uncased",+ "uuid",+ "windows-sys 0.61.2",+]++[[package]]+name = "turso_ext"+version = "0.8.0-pre.3"+source = "git+https://github.com/seanaye/turso?rev=be9acfe9e5e6efb17911af84047e4855cace53a3#be9acfe9e5e6efb17911af84047e4855cace53a3"+dependencies = [+ "chrono",+ "getrandom 0.4.2",+ "turso_macros",+]++[[package]]+name = "turso_macros"+version = "0.8.0-pre.3"+source = "git+https://github.com/seanaye/turso?rev=be9acfe9e5e6efb17911af84047e4855cace53a3#be9acfe9e5e6efb17911af84047e4855cace53a3"+dependencies = [+ "proc-macro2",+ "quote",+ "syn 2.0.117",+]++[[package]]+name = "turso_parser"+version = "0.8.0-pre.3"+source = "git+https://github.com/seanaye/turso?rev=be9acfe9e5e6efb17911af84047e4855cace53a3#be9acfe9e5e6efb17911af84047e4855cace53a3"+dependencies = [+ "bitflags 2.11.1",+ "memchr",+ "miette",+ "strum 0.26.3",+ "strum_macros 0.26.4",+ "thiserror 2.0.18",+ "turso_macros",+]+[[package]]name = "twox-hash"version = "2.1.2"@@ -15664,6 +16148,15 @@ version = "0.1.4"source = "registry+https://github.com/rust-lang/crates.io-index"checksum = "eaea85b334db583fe3274d12b4cd1880032beab409c0d774be044d4480ab9a94"+[[package]]+name = "uncased"+version = "0.9.10"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "e1b88fcfe09e89d3866a5c11019378088af2d24c3fbd4f0543f96b479ec90697"+dependencies = [+ "version_check",+]+[[package]]name = "unfurl"version = "0.1.0"@@ -15923,6 +16416,12 @@ version = "0.7.6"source = "registry+https://github.com/rust-lang/crates.io-index"checksum = "09cc8ee72d2a9becf2f2febe0205bbed8fc6615b7cb429ad062dc7b7ddd036a9"+[[package]]+name = "utf16_iter"+version = "1.0.5"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "c8232dd3cdaed5356e0f716d285e4b40b932ac434100fe9b7e0e8e935b9e6246"+[[package]]name = "utf16string"version = "0.2.0"@@ -17131,12 +17630,27 @@ dependencies = ["zeroize",]+[[package]]+name = "write16"+version = "1.0.0"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "d1890f4022759daae28ed4fe62859b1236caebfc61ede2f63ed4e695f3f6d936"+[[package]]name = "writeable"version = "0.6.3"source = "registry+https://github.com/rust-lang/crates.io-index"checksum = "1ffae5123b2d3fc086436f8834ae3ab053a283cfac8fe0a0b8eaae044768a4c4"+[[package]]+name = "wyz"+version = "0.5.1"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "05f360fc0b24296329c78fda852a1e9ae82de9cf7b27dae4b7f62f118f77b9ed"+dependencies = [+ "tap",+]+[[package]]name = "xmlparser"version = "0.13.6"@@ -17383,6 +17897,7 @@ dependencies = ["displaydoc","yoke","zerofrom",+ "zerovec",][[package]]@@ -17391,6 +17906,7 @@ version = "0.11.6"source = "registry+https://github.com/rust-lang/crates.io-index"checksum = "90f911cbc359ab6af17377d242225f4d75119aec87ea711a880987b18cd7b239"dependencies = [+ "serde","yoke","zerofrom","zerovec-derive",diff --git a/Cargo.toml b/Cargo.tomlindex 5fdb8927a8..47f8738e38 100644--- a/Cargo.toml+++ b/Cargo.toml@@ -13,9 +13,10 @@ members = ["crates/calendar_events","crates/channel_bots","crates/client/cache-core",- "crates/client/cache-idb","crates/client/cache-sqlite",+ "crates/client/cache-turso","crates/client/cache-wasm",+ "crates/client/turso-opfs","crates/complete_graph","crates/cowlike","crates/crm",@@ -207,6 +208,7 @@ pdfium-render = { version = "0.8.37", default-features = false, features = [] }pgvector = { version = "0.4", features = ["postgres", "sqlx"] }postcard = { version = "1", features = ["use-std"] }+pollster = "0.4"quote = "1"rand = "0.9.0"# uses vendored to fix lambda builds failing.@@ -267,6 +269,9 @@ tracing = "0.1.44"tracing-opentelemetry = "0.32.1"tracing-subscriber = { version = "0.3.22", features = ["env-filter", "json"] }tracing-tree = "0.4.0"+# Exact remotely available Turso fork revision approved by the browser cache G0.+# Its source tree is identical to the locally verified cf7de761 revision.+turso_core = { git = "https://github.com/seanaye/turso", rev = "be9acfe9e5e6efb17911af84047e4855cace53a3", default-features = false }tungstenite = { version = "0.28", features = ["url"] }unsynn = "0.3"urlencoding = "2.1.3"@@ -283,6 +288,8 @@ wiremock = "0.6.5"# anything older than 0.2.123, so keep this floor above that.wasm-bindgen = "0.2.123"wasm-bindgen-futures = "0.4"+wasm-bindgen-test = "0.3"+web-sys = "0.3"web-time = "1.1.0"worker = "0.8.1"# this is pinned to match axum 0.7.9 dependency requirementsdiff --git a/apps/web/.gitignore b/apps/web/.gitignoreindex 2210b6754a..34629f871d 100644--- a/apps/web/.gitignore+++ b/apps/web/.gitignore@@ -47,6 +47,7 @@ CodeSignTool/**/build**/.build**/dist+**/.dist-production**/*.tsbuildinfodiff --git a/apps/web/justfile b/apps/web/justfileindex e19ce3ead7..85ce579b8c 100644--- a/apps/web/justfile+++ b/apps/web/justfile@@ -65,18 +65,23 @@ node_heap := "--max-old-space-size=6144"build-dev: build-cache-wasmMODE=development NODE_ENV=production NODE_OPTIONS="{{node_heap}}" bun run --bun build+ bun scripts/cache-wasm/cli.ts package-dist --dist distbuild-staging: build-cache-wasmMODE=staging NODE_ENV=production NODE_OPTIONS="{{node_heap}}" bun run --bun build+ bun scripts/cache-wasm/cli.ts package-dist --dist distbuild-prod: build-cache-wasmMODE=production NODE_ENV=production NODE_OPTIONS="{{node_heap}}" bun run --bun build+ bun scripts/cache-wasm/cli.ts package-dist --dist dist# Tauri build hook (run automatically via beforeBuildCommand) — not meant to be run directly[private]build-tauri: build-cache-wasmprintf production > tauri/src-tauri/.macro-tauri-envMODE=production NODE_ENV=production NODE_OPTIONS="{{node_heap}}" bun run --bun build+ bun scripts/cache-wasm/cli.ts package-dist --dist dist+ bun scripts/cache-wasm/cli.ts remove-sidecar --dist dist# Build the bundle, zip it, and install it at# tooling/native_app_server/app-archive.zip for the bundle@@ -87,7 +92,7 @@ dist-archive: build-prodset -euo pipefailTARGET="$(cd {{ justfile_directory() }}/../../tooling/native_app_server && pwd)/app-archive.zip"rm -f "$TARGET"- (cd dist && zip -qr "$TARGET" .)+ (cd dist && zip -qr "$TARGET" . -x '*cache_wasm_bg*.wasm.br')echo "Archive: $TARGET"bundle-smoke-server *ARGS:@@ -163,6 +168,27 @@ cycles-ci:build-cache-wasm:wasm-pack build {{justfile_directory()}}/../../crates/client/cache-wasm --target web --release --out-dir {{justfile_directory()}}/src/lib/graphql-cache/wasm+# Build the production browser harness served by Vite preview.+build-cache-wasm-browser-production: build-cache-wasm build-cache-wasm-browser-test-hooks+ bunx --bun vite build --config src/lib/graphql-cache/worker/browser-test/vite.config.ts+ bun scripts/cache-wasm/cli.ts package-dist --dist src/lib/graphql-cache/worker/browser-test/.dist-production++# Build the separate destructive-hook WASM used only by cache recovery tests.+# Its distinct name keeps it outside the one-production-cache-WASM deploy gate.+[private]+build-cache-wasm-browser-test-hooks:+ wasm-pack build {{justfile_directory()}}/../../crates/client/cache-wasm \+ --target web --release \+ --out-name cache_wasm_browser_test_hooks \+ --out-dir {{justfile_directory()}}/src/lib/graphql-cache/wasm-browser-test \+ --features browser-test-hooks++# Exercise development and production asset URLs, lazy election, MIME,+# fresh-scope startup, DB-ready, first-ready, and linear-memory budgets.+test-cache-wasm-browser:+ bunx --bun playwright test --config src/lib/graphql-cache/worker/browser-test/playwright.config.ts --project chromium --project firefox+ bunx --bun playwright test --config src/lib/graphql-cache/worker/browser-test/playwright.production.config.ts --project chromium-production --project firefox-production+# Local profiling build: retain Rust symbols and DWARF source locations so an# exported Firefox profile can be symbolicated back to Rust files and lines.# This overwrites the gitignored release wasm package and is intentionally notdiff --git a/apps/web/scripts/cache-wasm/budgets.ts b/apps/web/scripts/cache-wasm/budgets.tsnew file mode 100644index 0000000000..9082c9a93a--- /dev/null+++ b/apps/web/scripts/cache-wasm/budgets.ts@@ -0,0 +1,5 @@+export const CACHE_WASM_BUDGETS = {+ browserReadyP95Ms: 3_000,+ hostFirstReadyP95Ms: 5_000,+ linearMemoryBytes: 32 * 1024 * 1024,+} as const;diff --git a/apps/web/scripts/cache-wasm/cli.ts b/apps/web/scripts/cache-wasm/cli.tsnew file mode 100755index 0000000000..17639f8970--- /dev/null+++ b/apps/web/scripts/cache-wasm/cli.ts@@ -0,0 +1,79 @@+#!/usr/bin/env bun++import { readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';+import { basename, join, resolve } from 'node:path';+import {+ brotliCompressSync,+ brotliDecompressSync,+ constants as zlibConstants,+} from 'node:zlib';++function argument(name: string, fallback?: string): string {+ const index = process.argv.indexOf(name);+ const value = index >= 0 ? process.argv[index + 1] : fallback;+ if (!value) throw new Error(`missing ${name}`);+ return value;+}++function walkFiles(directory: string): string[] {+ return readdirSync(directory, { withFileTypes: true }).flatMap((entry) => {+ const path = join(directory, entry.name);+ return entry.isDirectory() ? walkFiles(path) : [path];+ });+}++function oneMatchingFile(distPath: string, pattern: RegExp): string {+ const matches = walkFiles(distPath).filter((path) =>+ pattern.test(basename(path))+ );+ if (matches.length !== 1) {+ throw new Error(+ `expected one cache WASM artifact in ${distPath}, found ${matches.length}`+ );+ }+ return matches[0];+}++const distPath = resolve(+ argument('--dist', resolve(import.meta.dirname, '../../dist'))+);+const command = process.argv[2];++switch (command) {+ case 'package-dist': {+ const wasmPath = oneMatchingFile(+ distPath,+ /^cache_wasm_bg(?:-[\w-]+)?\.wasm$/+ );+ const raw = readFileSync(wasmPath);+ const compressed = brotliCompressSync(raw, {+ params: {+ [zlibConstants.BROTLI_PARAM_MODE]: zlibConstants.BROTLI_MODE_GENERIC,+ [zlibConstants.BROTLI_PARAM_QUALITY]: 11,+ [zlibConstants.BROTLI_PARAM_SIZE_HINT]: raw.byteLength,+ },+ });+ if (!brotliDecompressSync(compressed).equals(raw)) {+ throw new Error(+ 'Brotli sidecar does not decompress to the raw cache WASM'+ );+ }+ const sidecarPath = `${wasmPath}.br`;+ writeFileSync(sidecarPath, compressed);+ process.stdout.write(`${sidecarPath}\n`);+ break;+ }+ case 'remove-sidecar': {+ const sidecarPath = oneMatchingFile(+ distPath,+ /^cache_wasm_bg(?:-[\w-]+)?\.wasm\.br$/+ );+ rmSync(sidecarPath);+ process.stdout.write(`${sidecarPath}\n`);+ break;+ }+ default:+ throw new Error(+ 'usage: cli.ts <package-dist|remove-sidecar> --dist <directory>'+ );+}diff --git a/apps/web/scripts/cache-wasm/precompressed-preview-server.mjs b/apps/web/scripts/cache-wasm/precompressed-preview-server.mjsnew file mode 100644index 0000000000..1f6323c76a--- /dev/null+++ b/apps/web/scripts/cache-wasm/precompressed-preview-server.mjs@@ -0,0 +1,76 @@+#!/usr/bin/env node++import { createServer } from 'node:http';+import { existsSync, readFileSync, statSync } from 'node:fs';+import { basename, extname, resolve, sep } from 'node:path';++const dist = resolve(process.argv[2] ?? 'dist');+const port = Number(process.env.PORT ?? 4189);+if (!Number.isSafeInteger(port) || port <= 0) {+ throw new Error(`invalid PORT: ${process.env.PORT}`);+}+if (!existsSync(dist) || !statSync(dist).isDirectory()) {+ throw new Error(`production browser dist is missing: ${dist}`);+}++const contentTypes = new Map([+ ['.html', 'text/html; charset=utf-8'],+ ['.css', 'text/css; charset=utf-8'],+ ['.js', 'text/javascript; charset=utf-8'],+ ['.map', 'application/json; charset=utf-8'],+ ['.json', 'application/json; charset=utf-8'],+ ['.svg', 'image/svg+xml; charset=utf-8'],+ ['.png', 'image/png'],+ ['.ico', 'image/x-icon'],+ ['.woff2', 'font/woff2'],+ ['.wasm', 'application/wasm'],+]);++createServer((request, response) => {+ const url = new URL(request.url ?? '/', `http://${request.headers.host}`);+ if (url.pathname === '/app') {+ response.writeHead(302, { location: '/app/' });+ response.end();+ return;+ }+ if (!url.pathname.startsWith('/app/')) {+ response.writeHead(404).end('not found');+ return;+ }+ let relativePath;+ try {+ relativePath = decodeURIComponent(url.pathname.slice('/app/'.length));+ } catch {+ response.writeHead(400).end('invalid path encoding');+ return;+ }+ const requestedPath = resolve(dist, relativePath || 'index.html');+ if (+ requestedPath !== dist &&+ !requestedPath.startsWith(`${dist}${sep}`)+ ) {+ response.writeHead(400).end('invalid path');+ return;+ }+ const isWasm = extname(requestedPath) === '.wasm';+ const isCacheWasm =+ isWasm && /^cache_wasm_bg(?:-[\w-]+)?\.wasm$/.test(basename(requestedPath));+ const bodyPath = isCacheWasm ? `${requestedPath}.br` : requestedPath;+ if (!existsSync(bodyPath) || !statSync(bodyPath).isFile()) {+ response.writeHead(404).end('not found');+ return;+ }+ const body = readFileSync(bodyPath);+ const headers = {+ 'content-type': contentTypes.get(extname(requestedPath)) ?? 'application/octet-stream',+ 'content-length': String(body.byteLength),+ 'cache-control': 'public, max-age=31536000, immutable',+ ...(isCacheWasm ? { 'content-encoding': 'br' } : {}),+ };+ response.writeHead(200, headers);+ response.end(request.method === 'HEAD' ? undefined : body);+}).listen(port, '127.0.0.1', () => {+ process.stdout.write(+ `precompressed cache WASM preview listening at http://127.0.0.1:${port}/app/\n`+ );+});diff --git a/apps/web/scripts/cache-wasm/prune-old-brotli-from-s3.sh b/apps/web/scripts/cache-wasm/prune-old-brotli-from-s3.shnew file mode 100755index 0000000000..3a753ccbdb--- /dev/null+++ b/apps/web/scripts/cache-wasm/prune-old-brotli-from-s3.sh@@ -0,0 +1,69 @@+#!/usr/bin/env bash+# Prune prior cache WASM objects only after every publication step succeeds.+set -euo pipefail++if [ "$#" -lt 2 ] || [ "$#" -gt 3 ]; then+ echo "usage: prune-old-brotli-from-s3.sh <dist-root> <s3-prefix> [retention-days]" >&2+ exit 2+fi++dist_root=$1+s3_prefix=${2%/}+retention_days=${3:-7}+if ! [[ "$retention_days" =~ ^[1-9][0-9]*$ ]]; then+ echo "retention days must be a positive integer" >&2+ exit 2+fi++raw_files=()+while IFS= read -r -d '' path; do+ raw_files+=("$path")+done < <(find "$dist_root" -type f -name 'cache_wasm_bg*.wasm' -print0)+if [ "${#raw_files[@]}" -ne 1 ]; then+ echo "expected one raw cache WASM; found ${#raw_files[@]}" >&2+ exit 1+fi+raw=${raw_files[0]}+relative_key=${raw#"${dist_root%/}"/}+if [ "$relative_key" = "$raw" ]; then+ echo "cache WASM is not contained by dist root" >&2+ exit 1+fi++s3_location=${s3_prefix#s3://}+if [ "$s3_location" = "$s3_prefix" ]; then+ echo "S3 prefix must start with s3://" >&2+ exit 2+fi+bucket=${s3_location%%/*}+if [ -z "$bucket" ]; then+ echo "S3 prefix must include a bucket" >&2+ exit 2+fi+if [[ "$s3_location" == */* ]]; then+ prefix=${s3_location#*/}+else+ prefix=''+fi+current_key=${prefix:+$prefix/}$relative_key+cutoff=$(date -u -d "$retention_days days ago" '+%Y-%m-%dT%H:%M:%SZ')+list_args=(s3api list-objects-v2 --bucket "$bucket")+if [ -n "$prefix" ]; then+ list_args+=(--prefix "$prefix/")+fi+list_args+=(+ --query "Contents[?LastModified<=\`$cutoff\`].Key"+ --output text+)++# Immutable hashed URLs can remain in recently served pages after a deploy.+# Preserve the current object and every generation inside the retention window;+# remove only matching cache WASM keys whose S3 LastModified is older.+while IFS= read -r key; do+ [ -n "$key" ] || continue+ [ "$key" != "None" ] || continue+ [ "$key" != "$current_key" ] || continue+ case "$key" in+ *cache_wasm_bg*.wasm) aws s3 rm "s3://$bucket/$key" ;;+ esac+done < <(aws "${list_args[@]}" | tr '\t' '\n')diff --git a/apps/web/scripts/cache-wasm/upload-brotli-to-s3.sh b/apps/web/scripts/cache-wasm/upload-brotli-to-s3.shnew file mode 100755index 0000000000..08eb6bd0ed--- /dev/null+++ b/apps/web/scripts/cache-wasm/upload-brotli-to-s3.sh@@ -0,0 +1,52 @@+#!/usr/bin/env bash+# Upload the precompressed cache WASM bytes at the original .wasm key. The+# caller's generic sync must exclude both cache_wasm_bg*.wasm and *.wasm.br.+set -euo pipefail++if [ "$#" -lt 2 ] || [ "$#" -gt 3 ]; then+ echo "usage: upload-brotli-to-s3.sh <dist-root> <s3-prefix> [acl]" >&2+ exit 2+fi++dist_root=$1+s3_prefix=${2%/}+acl=${3:-}+raw_files=()+while IFS= read -r -d '' path; do+ raw_files+=("$path")+done < <(find "$dist_root" -type f -name 'cache_wasm_bg*.wasm' -print0)+sidecars=()+while IFS= read -r -d '' path; do+ sidecars+=("$path")+done < <(find "$dist_root" -type f -name 'cache_wasm_bg*.wasm.br' -print0)+if [ "${#raw_files[@]}" -ne 1 ] || [ "${#sidecars[@]}" -ne 1 ]; then+ echo "expected one raw cache WASM and one Brotli sidecar; found ${#raw_files[@]} raw / ${#sidecars[@]} sidecar" >&2+ exit 1+fi+raw=${raw_files[0]}+sidecar=${sidecars[0]}+if [ "$sidecar" != "$raw.br" ]; then+ echo "cache WASM sidecar is not adjacent to its raw artifact" >&2+ exit 1+fi+if ! brotli --decompress --stdout "$sidecar" | cmp --silent - "$raw"; then+ echo "cache WASM sidecar does not decompress to the raw artifact" >&2+ exit 1+fi+relative_key=${raw#"${dist_root%/}"/}+if [ "$relative_key" = "$raw" ]; then+ echo "cache WASM is not contained by dist root" >&2+ exit 1+fi+args=(+ s3 cp "$sidecar" "$s3_prefix/$relative_key"+ --content-type application/wasm+ --content-encoding br+ --cache-control 'public, max-age=31536000, immutable'+)+if [ -n "$acl" ]; then+ args+=(--acl "$acl")+fi+# Pruning is intentionally a separate post-publication operation. A failure in+# this upload or any later generic/index publish step must retain prior keys.+aws "${args[@]}"diff --git a/apps/web/scripts/cache-wasm/upload-brotli-to-s3.test.ts b/apps/web/scripts/cache-wasm/upload-brotli-to-s3.test.tsnew file mode 100644index 0000000000..815d029484--- /dev/null+++ b/apps/web/scripts/cache-wasm/upload-brotli-to-s3.test.ts@@ -0,0 +1,211 @@+import { spawnSync } from 'node:child_process';+import {+ chmodSync,+ mkdirSync,+ mkdtempSync,+ readFileSync,+ rmSync,+ writeFileSync,+} from 'node:fs';+import { tmpdir } from 'node:os';+import { join, resolve } from 'node:path';+import { brotliCompressSync } from 'node:zlib';+import { afterEach, describe, expect, it } from 'vitest';++const temporaryDirectories: string[] = [];+afterEach(() => {+ for (const directory of temporaryDirectories.splice(0)) {+ rmSync(directory, { recursive: true, force: true });+ }+});++describe('cache WASM S3 upload', () => {+ it('production generic sync excludes cache raw/sidecar but not unrelated WASM', () => {+ const infrastructure = readFileSync(+ resolve(import.meta.dirname, '../../../../infra/stacks/web-app/index.ts'),+ 'utf8'+ );+ expect(infrastructure).toContain(+ '--exclude "*cache_wasm_bg*.wasm" --exclude "*cache_wasm_bg*.wasm.br"'+ );+ expect(infrastructure).not.toContain('--exclude "*.wasm"');+ const uploadIndex = infrastructure.indexOf('upload-brotli-to-s3.sh');+ const syncIndex = infrastructure.indexOf('aws s3 sync ./output');+ const indexPublishIndex = infrastructure.indexOf(+ 'index-html-object-metadata-command'+ );+ const pruneIndex = infrastructure.indexOf(+ 'prune-old-brotli-from-s3.sh'+ );+ expect(uploadIndex).toBeLessThan(syncIndex);+ expect(syncIndex).toBeLessThan(indexPublishIndex);+ expect(indexPublishIndex).toBeLessThan(pruneIndex);+ expect(infrastructure.slice(uploadIndex, syncIndex)).toContain('&&');+ expect(infrastructure).toContain(+ 'dependsOn: [webAppAssets, syncAssetsCommand]'+ );+ expect(infrastructure).toContain(+ 'dependsOn: [indexHtmlObjectMetadataCommand]'+ );+ });++ it('keeps sidecars in web delivery but excludes them from native/OTA packaging', () => {+ const webJustfile = readFileSync(+ resolve(import.meta.dirname, '../../justfile'),+ 'utf8'+ );+ expect(webJustfile).toMatch(+ /build-tauri:[\s\S]*package-dist --dist dist\n\s+bun scripts\/cache-wasm\/cli\.ts remove-sidecar --dist dist/+ );+ expect(webJustfile).toContain(+ `zip -qr "$TARGET" . -x '*cache_wasm_bg*.wasm.br'`+ );++ const infrastructure = readFileSync(+ resolve(import.meta.dirname, '../../../../infra/stacks/web-app/index.ts'),+ 'utf8'+ );+ expect(infrastructure).toContain(+ `find ${'${shellQuote(appArchiveOutputPath)}'} -type f -name 'cache_wasm_bg*.wasm.br' -delete`+ );+ expect(infrastructure).toContain('--exclude "app-archive/*"');+ });++ it('uploads only sidecar bytes at the original WASM key with exact metadata', () => {+ const directory = mkdtempSync(join(tmpdir(), 'cache-wasm-upload-'));+ temporaryDirectories.push(directory);+ const dist = join(directory, 'dist');+ const assets = join(dist, 'assets');+ const bin = join(directory, 'bin');+ mkdirSync(assets, { recursive: true });+ mkdirSync(bin);+ const raw = Buffer.from('cache wasm'.repeat(1_000));+ const unrelated = Buffer.from('leave me alone');+ const rawPath = join(assets, 'cache_wasm_bg-hash.wasm');+ const sidecarPath = `${rawPath}.br`;+ const unrelatedPath = join(assets, 'other.wasm');+ writeFileSync(rawPath, raw);+ writeFileSync(sidecarPath, brotliCompressSync(raw));+ writeFileSync(unrelatedPath, unrelated);+ const argumentsPath = join(directory, 'aws-arguments.txt');+ const fakeAws = join(bin, 'aws');+ writeFileSync(+ fakeAws,+ `#!/usr/bin/env bash\nprintf '%s\\n' CALL "$@" >> ${JSON.stringify(argumentsPath)}\nif [ "\${FAIL_CP:-}" = true ] && [ "\${2:-}" = cp ]; then exit 42; fi\n`+ );+ chmodSync(fakeAws, 0o755);++ const script = resolve(import.meta.dirname, 'upload-brotli-to-s3.sh');+ const result = spawnSync(+ 'bash',+ [script, dist, 's3://example/app', 'public-read'],+ {+ encoding: 'utf8',+ env: { ...process.env, PATH: `${bin}:${process.env.PATH}` },+ }+ );++ expect(result.stderr).toBe('');+ expect(result.status).toBe(0);+ expect(readFileSync(argumentsPath, 'utf8').trim().split('\n')).toEqual([+ 'CALL',+ 's3',+ 'cp',+ sidecarPath,+ 's3://example/app/assets/cache_wasm_bg-hash.wasm',+ '--content-type',+ 'application/wasm',+ '--content-encoding',+ 'br',+ '--cache-control',+ 'public, max-age=31536000, immutable',+ '--acl',+ 'public-read',+ ]);+ expect(readFileSync(rawPath)).toEqual(raw);+ expect(readFileSync(unrelatedPath)).toEqual(unrelated);+ });++ it('prunes only old cache objects in its separate post-publication step', () => {+ const directory = mkdtempSync(join(tmpdir(), 'cache-wasm-prune-'));+ temporaryDirectories.push(directory);+ const dist = join(directory, 'dist');+ const assets = join(dist, 'assets');+ const bin = join(directory, 'bin');+ mkdirSync(assets, { recursive: true });+ mkdirSync(bin);+ writeFileSync(join(assets, 'cache_wasm_bg-current.wasm'), 'current');+ const argumentsPath = join(directory, 'aws-arguments.txt');+ const fakeAws = join(bin, 'aws');+ writeFileSync(+ fakeAws,+ `#!/usr/bin/env bash\nprintf '%s\\n' CALL "$@" >> ${JSON.stringify(argumentsPath)}\nif [ "\${1:-}" = s3api ]; then printf '%s\\n' app/assets/cache_wasm_bg-old.wasm app/assets/cache_wasm_bg-current.wasm; fi\n`+ );+ chmodSync(fakeAws, 0o755);++ const result = spawnSync(+ 'bash',+ [+ resolve(import.meta.dirname, 'prune-old-brotli-from-s3.sh'),+ dist,+ 's3://example/app',+ ],+ {+ encoding: 'utf8',+ env: { ...process.env, PATH: `${bin}:${process.env.PATH}` },+ }+ );+ expect(result.status).toBe(0);+ const calls = readFileSync(argumentsPath, 'utf8');+ expect(calls).toContain(+ 'CALL\ns3api\nlist-objects-v2\n--bucket\nexample\n--prefix\napp/\n'+ );+ expect(calls).toContain(+ 'CALL\ns3\nrm\ns3://example/app/assets/cache_wasm_bg-old.wasm\n'+ );+ expect(calls).not.toContain(+ 'rm\ns3://example/app/assets/cache_wasm_bg-current.wasm'+ );+ });++ it('does not invoke pruning when the current upload fails', () => {+ const directory = mkdtempSync(join(tmpdir(), 'cache-wasm-upload-fail-'));+ temporaryDirectories.push(directory);+ const dist = join(directory, 'dist');+ const assets = join(dist, 'assets');+ const bin = join(directory, 'bin');+ mkdirSync(assets, { recursive: true });+ mkdirSync(bin);+ const rawPath = join(assets, 'cache_wasm_bg-current.wasm');+ writeFileSync(rawPath, Buffer.from('current cache wasm'.repeat(100)));+ writeFileSync(+ `${rawPath}.br`,+ brotliCompressSync(readFileSync(rawPath))+ );+ const argumentsPath = join(directory, 'aws-arguments.txt');+ const fakeAws = join(bin, 'aws');+ writeFileSync(+ fakeAws,+ `#!/usr/bin/env bash\nprintf '%s\\n' CALL "$@" >> ${JSON.stringify(argumentsPath)}\nif [ "\${2:-}" = cp ]; then exit 42; fi\n`+ );+ chmodSync(fakeAws, 0o755);++ const result = spawnSync(+ 'bash',+ [+ resolve(import.meta.dirname, 'upload-brotli-to-s3.sh'),+ dist,+ 's3://example/app',+ ],+ {+ encoding: 'utf8',+ env: { ...process.env, PATH: `${bin}:${process.env.PATH}` },+ }+ );++ expect(result.status).toBe(42);+ const calls = readFileSync(argumentsPath, 'utf8');+ expect(calls).toContain('\ns3\ncp\n');+ expect(calls).not.toContain('\nrm\n');+ });+});diff --git a/apps/web/scripts/preview/deploy.ts b/apps/web/scripts/preview/deploy.tsindex 884ce62590..71fc27bd29 100644--- a/apps/web/scripts/preview/deploy.ts+++ b/apps/web/scripts/preview/deploy.ts@@ -10,12 +10,43 @@* AWS credentials must be configured (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, or AWS profile)*/-import { execSync } from 'node:child_process';+import { execFileSync, execSync } from 'node:child_process';import { existsSync } from 'node:fs';import { resolve } from 'node:path';+import { fileURLToPath } from 'node:url';+const SCRIPT_DIRECTORY = fileURLToPath(new URL('.', import.meta.url));const PREVIEW_BUCKET = 'macro-preview-assets-dev';-const DIST_PATH = resolve(import.meta.dir, '../../dist');+const DIST_PATH = resolve(SCRIPT_DIRECTORY, '../../dist');+const CACHE_WASM_UPLOAD_SCRIPT = resolve(+ SCRIPT_DIRECTORY,+ '../cache-wasm/upload-brotli-to-s3.sh'+);+const CACHE_WASM_PRUNE_SCRIPT = resolve(+ SCRIPT_DIRECTORY,+ '../cache-wasm/prune-old-brotli-from-s3.sh'+);++export function previewSyncArguments(+ previewId: string,+ distPath = DIST_PATH+): string[] {+ return [+ 's3',+ 'sync',+ `${distPath}/`,+ `s3://${PREVIEW_BUCKET}/${previewId}/app/`,+ '--delete',+ '--cache-control',+ 'public, max-age=31536000, immutable',+ '--exclude',+ 'index.html',+ '--exclude',+ '*cache_wasm_bg*.wasm',+ '--exclude',+ '*cache_wasm_bg*.wasm.br',+ ];+}function parseArgs(): { previewId: string; skipBuild: boolean } {const args = process.argv.slice(2);@@ -65,32 +96,47 @@ function build(): void {});}+type PreviewCommandRunner = (+ executable: string,+ argumentsList: readonly string[]+) => void;++export function publishPreviewAssets(+ previewId: string,+ distPath = DIST_PATH,+ run: PreviewCommandRunner = (executable, argumentsList) => {+ execFileSync(executable, [...argumentsList], { stdio: 'inherit' });+ }+): void {+ const s3Prefix = `s3://${PREVIEW_BUCKET}/${previewId}/app`;+ run('bash', [CACHE_WASM_UPLOAD_SCRIPT, distPath, s3Prefix]);+ run('aws', previewSyncArguments(previewId, distPath));+ run('aws', [+ 's3',+ 'cp',+ `${distPath}/index.html`,+ `${s3Prefix}/index.html`,+ '--cache-control',+ 'no-cache, no-store, must-revalidate',+ ]);+ run('bash', [CACHE_WASM_PRUNE_SCRIPT, distPath, s3Prefix]);+}+function deploy(previewId: string): void {validateBucket(PREVIEW_BUCKET);if (!existsSync(DIST_PATH)) {console.error(`ERROR: Build output not found at ${DIST_PATH}`);- console.error('Run with --skip-build=false or build first with: bun run build:dev');+ console.error(+ 'Run with --skip-build=false or build first with: bun run build:dev'+ );process.exit(1);}console.log(`\nDeploying to s3://${PREVIEW_BUCKET}/${previewId}/app/\n`);- // Sync all files except index.html with immutable cache- execSync(- `aws s3 sync ${DIST_PATH}/ s3://${PREVIEW_BUCKET}/${previewId}/app/ ` +- `--delete ` +- `--cache-control "public, max-age=31536000, immutable" ` +- `--exclude "index.html"`,- { stdio: 'inherit' }- );-- // Upload index.html with no-cache- execSync(- `aws s3 cp ${DIST_PATH}/index.html s3://${PREVIEW_BUCKET}/${previewId}/app/index.html ` +- `--cache-control "no-cache, no-store, must-revalidate"`,- { stdio: 'inherit' }- );+ // Upload current bytes, publish assets/index, and only then prune old keys.+ publishPreviewAssets(previewId);const previewUrl = `https://${previewId}.preview.macro.com`;console.log(`\nPreview deployed: ${previewUrl}\n`);@@ -108,14 +154,13 @@ function cleanup(previewId: string): void {console.log('\nCleanup complete\n');}-// Main-const { previewId, skipBuild } = parseArgs();+if (import.meta.main) {+ const { previewId, skipBuild } = parseArgs();-if (process.argv.includes('--cleanup')) {- cleanup(previewId);-} else {- if (!skipBuild) {- build();+ if (process.argv.includes('--cleanup')) {+ cleanup(previewId);+ } else {+ if (!skipBuild) build();+ deploy(previewId);}- deploy(previewId);}diff --git a/apps/web/scripts/preview/preview.test.ts b/apps/web/scripts/preview/preview.test.tsindex e54bbd881c..c2870bff3d 100644--- a/apps/web/scripts/preview/preview.test.ts+++ b/apps/web/scripts/preview/preview.test.ts@@ -1,4 +1,5 @@import { describe, expect, it } from 'vitest';+import { previewSyncArguments, publishPreviewAssets } from './deploy';import {extractPreviewIdFromBody,generatePreviewId,@@ -34,7 +35,8 @@ describe('buildCommentBody', () => {describe('extractPreviewIdFromBody', () => {it('extracts preview id from url without path', () => {- const body = '**Preview:** [https://my-feature-abc123.preview.macro.com](...)';+ const body =+ '**Preview:** [https://my-feature-abc123.preview.macro.com](...)';expect(extractPreviewIdFromBody(body)).toBe('my-feature-abc123');});@@ -73,7 +75,8 @@ describe('generatePreviewId', () => {});it('truncates long branch names to 30 chars', () => {- const longBranch = 'this-is-a-very-long-branch-name-that-exceeds-thirty-chars';+ const longBranch =+ 'this-is-a-very-long-branch-name-that-exceeds-thirty-chars';const id = generatePreviewId(longBranch);const prefixWithoutNanoid = id.slice(0, -7);expect(prefixWithoutNanoid.length).toBeLessThanOrEqual(30);@@ -91,6 +94,51 @@ describe('generatePreviewId', () => {});});+describe('preview cache WASM deployment', () => {+ it('excludes only cache WASM raw/sidecar from generic sync', () => {+ const argumentsList = previewSyncArguments('preview-id', '/tmp/dist');+ expect(argumentsList).toContain('*cache_wasm_bg*.wasm');+ expect(argumentsList).toContain('*cache_wasm_bg*.wasm.br');+ expect(argumentsList).not.toContain('*.wasm');+ expect(argumentsList).not.toContain('*.wasm.br');+ });++ it('publishes current WASM, assets, and index before pruning', () => {+ const calls: string[][] = [];+ publishPreviewAssets('preview-id', '/tmp/dist', (executable, args) => {+ calls.push([executable, ...args]);+ });+ expect(calls.map((call) => call[0])).toEqual([+ 'bash',+ 'aws',+ 'aws',+ 'bash',+ ]);+ expect(calls[0].join(' ')).toContain('upload-brotli-to-s3.sh');+ expect(calls[1].slice(0, 3)).toEqual(['aws', 's3', 'sync']);+ expect(calls[2].slice(0, 3)).toEqual(['aws', 's3', 'cp']);+ expect(calls[3].join(' ')).toContain('prune-old-brotli-from-s3.sh');+ });++ it.each([1, 2])(+ 'does not prune when publication step %i fails',+ (failedCall) => {+ const calls: string[][] = [];+ expect(() =>+ publishPreviewAssets('preview-id', '/tmp/dist', (executable, args) => {+ calls.push([executable, ...args]);+ if (calls.length - 1 === failedCall) throw new Error('publish failed');+ })+ ).toThrow('publish failed');+ expect(+ calls.some((call) =>+ call.join(' ').includes('prune-old-brotli-from-s3.sh')+ )+ ).toBe(false);+ }+ );+});+describe('roundtrip: build url then extract id', () => {it('extracts same id from generated comment', () => {const originalId = 'my-feature-abc123';diff --git a/apps/web/src/lib/core/constant/featureFlags.ts b/apps/web/src/lib/core/constant/featureFlags.tsindex 64b2d01a6a..6acb7f6d1c 100644--- a/apps/web/src/lib/core/constant/featureFlags.ts+++ b/apps/web/src/lib/core/constant/featureFlags.ts@@ -484,6 +484,24 @@ export const ENABLE_GRAPHQL_SOUP_OVERRIDE = getFeatureFlagOverride('ENABLE_GRAPHQL_SOUP');+const parseBooleanOverride = (value: unknown): boolean | undefined =>+ value === 'true' ? true : value === 'false' ? false : undefined;++/** Browser-only Turso/OPFS cache rollout. Production defaults off. */+export const ENABLE_BROWSER_TURSO_CACHE_FLAG = 'enable-browser-turso-cache';+const BROWSER_TURSO_CACHE_ENV = import.meta.env.VITE_ENABLE_BROWSER_TURSO_CACHE;+export const ENABLE_BROWSER_TURSO_CACHE_OVERRIDE = parseBooleanOverride(+ BROWSER_TURSO_CACHE_ENV+);++/** Independent emergency stop. Any true env/PostHog source wins. */+export const DISABLE_BROWSER_TURSO_CACHE_FLAG = 'disable-browser-turso-cache';+const DISABLE_BROWSER_TURSO_CACHE_ENV = import.meta.env+ .VITE_DISABLE_BROWSER_TURSO_CACHE;+export const DISABLE_BROWSER_TURSO_CACHE_OVERRIDE = parseBooleanOverride(+ DISABLE_BROWSER_TURSO_CACHE_ENV+);+/*** Non-reactive check for imperative call sites (e.g. the soup GraphQL* client's normalized-cache gate). Env override first (dev), else the samediff --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.tsindex 163067b531..c9330f4169 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@@ -18,12 +18,13 @@ import {subscribe,} from 'wonka';import type { CacheHost } from '../host/types';-import type {- ClaimedMutation,- EnqueueOptimisticMutationResult,- MutationClaim,- ReadResult,- WriteResult,+import {+ ADMITTED_ENQUEUE_UNCERTAIN_ERROR_CODE,+ type ClaimedMutation,+ type EnqueueOptimisticMutationResult,+ type MutationClaim,+ type ReadResult,+ type WriteResult,} from '../protocol';import { entityFromArgument } from './entity-resolvers';import {@@ -479,6 +480,38 @@ function harness(return { ops, results, forwarded, client };}+function controlledQueryHarness(+ host: CacheHost,+ options: NormalizedCacheExchangeOptions = {}+) {+ const ops = makeSubject<Operation>();+ const network = makeSubject<OperationResult>();+ const forwarded: Operation[] = [];+ const results: OperationResult[] = [];+ const client = {+ reexecuteOperation: vi.fn((operation: Operation) => ops.next(operation)),+ } as unknown as Client;+ const forward = (ops$: Source<Operation>): Source<OperationResult> => {+ pipe(+ ops$,+ subscribe((operation) => forwarded.push(operation))+ );+ return network.source;+ };+ pipe(+ normalizedCacheExchange(+ host,+ options+ )({+ forward,+ client,+ dispatchDebug: () => undefined,+ })(ops.source),+ subscribe((result) => results.push(result))+ );+ return { ops, network, forwarded, results, client };+}+const tick = () => new Promise((resolve) => setTimeout(resolve, 10));describe('normalizedCacheExchange', () => {@@ -957,6 +990,347 @@ describe('normalizedCacheExchange', () => {]);});+ it('defers replacement reread behind a slow successful fallback network request', async () => {+ let readCount = 0;+ host.readQuery = async (args) => {+ host.reads.push({ opKey: args.opKey, query: args.query });+ readCount += 1;+ if (readCount === 1) {+ throw Object.assign(new Error('old owner lost'), {+ errorCode: 'owner-epoch-lost',+ });+ }+ return { kind: 'miss' };+ };+ const { ops, network, forwarded, client } = controlledQueryHarness(host);+ ops.next(makeOp(41));+ await tick();+ expect(forwarded).toHaveLength(1);++ host.pushAffected([41]);+ expect(client.reexecuteOperation).not.toHaveBeenCalled();+ network.next({+ operation: forwarded[0]!,+ data: { from: 'slow-network' },+ error: undefined,+ extensions: undefined,+ stale: false,+ hasNext: false,+ });+ await tick();++ expect(forwarded).toHaveLength(1);+ expect(client.reexecuteOperation).not.toHaveBeenCalled();+ expect(host.writes).toHaveLength(1);+ expect(host.reads).toHaveLength(2);+ });++ it('restores a fast successful fallback after replacement without another API request', async () => {+ let readCount = 0;+ let cached: unknown;+ host.readQuery = async (args) => {+ host.reads.push({+ opKey: args.opKey,+ query: args.query,+ variables: args.variables,+ priority: args.priority,+ entityResolvers: args.entityResolvers,+ });+ readCount += 1;+ if (readCount === 1) {+ throw Object.assign(new Error('old owner lost'), {+ errorCode: 'owner-epoch-lost',+ });+ }+ return cached === undefined+ ? { kind: 'miss' }+ : { kind: 'hit', data: cached };+ };+ host.writeQuery = vi+ .fn()+ .mockRejectedValueOnce(new Error('replacement init not ready'))+ .mockImplementationOnce(async (args) => {+ cached = args.data;+ return { changed: [], affectedOps: [], reset: false };+ });+ const { ops, network, forwarded, results, client } = controlledQueryHarness(+ host,+ ENTITY_RESOLVER_OPTIONS+ );+ ops.next(makeOp(42));+ await tick();+ network.next({+ operation: forwarded[0]!,+ data: { from: 'fast-network' },+ error: undefined,+ extensions: undefined,+ stale: false,+ hasNext: false,+ });+ await tick();+ expect(host.writeQuery).toHaveBeenCalledOnce();++ host.pushAffected([42]);+ await tick();++ expect(host.writeQuery).toHaveBeenCalledTimes(2);+ expect(host.writeQuery).toHaveBeenLastCalledWith(+ expect.objectContaining({+ opKey: 42,+ data: { from: 'fast-network' },+ entityResolvers: EXPECTED_ENTITY_RESOLVERS,+ })+ );+ expect(cached).toEqual({ from: 'fast-network' });+ expect(host.reads).toHaveLength(2);+ expect(host.reads[1]).toEqual(+ expect.objectContaining({+ opKey: 42,+ variables: { input: { limit: 2 } },+ entityResolvers: EXPECTED_ENTITY_RESOLVERS,+ })+ );+ expect(client.reexecuteOperation).not.toHaveBeenCalled();+ expect(forwarded).toHaveLength(1);+ expect(results).toHaveLength(1);+ });++ it('serializes a replacement notification during write and preserves payload after retry failure', async () => {+ let readCount = 0;+ host.readQuery = async (args) => {+ host.reads.push({ opKey: args.opKey, query: args.query });+ readCount += 1;+ if (readCount === 1) {+ throw Object.assign(new Error('old owner lost'), {+ errorCode: 'owner-epoch-lost',+ });+ }+ return { kind: 'hit', data: { from: 'network' } };+ };+ let rejectInitialWrite!: (error: Error) => void;+ const initialWrite = new Promise<never>((_resolve, reject) => {+ rejectInitialWrite = reject;+ });+ host.writeQuery = vi+ .fn()+ .mockImplementationOnce(async () => await initialWrite)+ .mockRejectedValueOnce(new Error('replacement failed while writing'))+ .mockResolvedValueOnce({ changed: [], affectedOps: [], reset: false });+ const { ops, network, forwarded, client } = controlledQueryHarness(host);+ ops.next(makeOp(43));+ await tick();+ network.next({+ operation: forwarded[0]!,+ data: { from: 'network' },+ error: undefined,+ extensions: undefined,+ stale: false,+ hasNext: false,+ });+ await vi.waitFor(() => expect(host.writeQuery).toHaveBeenCalledOnce());++ host.pushAffected([43]);+ rejectInitialWrite(new Error('old write failed'));+ await vi.waitFor(() => expect(host.writeQuery).toHaveBeenCalledTimes(2));+ await tick();+ expect(host.reads).toHaveLength(1);++ host.pushAffected([43]);+ await vi.waitFor(() => expect(host.writeQuery).toHaveBeenCalledTimes(3));+ await vi.waitFor(() => expect(host.reads).toHaveLength(2));++ expect(client.reexecuteOperation).not.toHaveBeenCalled();+ expect(forwarded).toHaveLength(1);+ });++ it('invalidates retained fallback A before newer network result B writes', async () => {+ let readCount = 0;+ let writeCount = 0;+ let cached: unknown;+ host.readQuery = async (args) => {+ host.reads.push({+ opKey: args.opKey,+ query: args.query,+ variables: args.variables,+ entityResolvers: args.entityResolvers,+ });+ readCount += 1;+ if (readCount === 1) {+ throw Object.assign(new Error('old owner lost'), {+ errorCode: 'owner-epoch-lost',+ });+ }+ return { kind: 'hit', data: cached };+ };+ host.writeQuery = vi.fn(async (args) => {+ writeCount += 1;+ if (writeCount === 1) throw new Error('initial A write failed');+ if (writeCount === 2) throw new Error('replacement A write failed');+ cached = args.data;+ return { changed: [], affectedOps: [], reset: false };+ });+ const { ops, network, forwarded, client } = controlledQueryHarness(+ host,+ ENTITY_RESOLVER_OPTIONS+ );+ const fallbackA = makeOp(46);+ ops.next(fallbackA);+ await tick();+ network.next({+ operation: forwarded[0]!,+ data: { version: 'A' },+ error: undefined,+ extensions: undefined,+ stale: false,+ hasNext: false,+ });+ await tick();+ host.pushAffected([46]);+ await vi.waitFor(() => expect(host.writeQuery).toHaveBeenCalledTimes(2));+ await tick();++ const newerB = makeOp(46, 'network-only');+ ops.next(newerB);+ await vi.waitFor(() =>+ expect(forwarded.filter(({ kind }) => kind === 'query')).toHaveLength(2)+ );+ network.next({+ operation: forwarded.findLast(({ kind }) => kind === 'query')!,+ data: { version: 'B' },+ error: undefined,+ extensions: undefined,+ stale: false,+ hasNext: false,+ });+ await vi.waitFor(() => expect(host.writeQuery).toHaveBeenCalledTimes(3));+ await vi.waitFor(() => expect(host.reads).toHaveLength(2));+ expect(cached).toEqual({ version: 'B' });+ expect(host.reads[1]?.entityResolvers).toEqual(EXPECTED_ENTITY_RESOLVERS);++ host.pushAffected([46]);+ await tick();+ expect(client.reexecuteOperation).toHaveBeenCalledOnce();+ expect(host.reads).toHaveLength(3);+ expect(host.writeQuery).toHaveBeenCalledTimes(3);+ expect(cached).toEqual({ version: 'B' });+ expect(forwarded.filter(({ kind }) => kind === 'query')).toHaveLength(2);++ ops.next(teardownOf(newerB));+ await tick();+ host.pushAffected([46]);+ await tick();+ expect(host.writeQuery).toHaveBeenCalledTimes(3);+ expect(cached).toEqual({ version: 'B' });+ });++ it('clears registration-only context before a later ordinary cache miss', async () => {+ let readCount = 0;+ host.readQuery = async (args) => {+ host.reads.push({ opKey: args.opKey, query: args.query });+ readCount += 1;+ if (readCount === 1) {+ throw Object.assign(new Error('old owner lost'), {+ errorCode: 'owner-epoch-lost',+ });+ }+ return { kind: 'miss' };+ };+ const { ops, network, forwarded, client } = controlledQueryHarness(host);+ ops.next(makeOp(44));+ await tick();+ network.next({+ operation: forwarded[0]!,+ data: undefined,+ error: undefined,+ extensions: undefined,+ stale: false,+ hasNext: false,+ });+ await tick();++ host.pushAffected([44]);+ await tick();+ expect(client.reexecuteOperation).toHaveBeenCalledOnce();+ expect(+ vi.mocked(client.reexecuteOperation).mock.calls[0]?.[0]?.context+ .normalizedCacheReplacementRegistrationOnly+ ).toBe(true);+ expect(host.reads).toHaveLength(2);+ expect(forwarded).toHaveLength(1);++ host.pushAffected([44]);+ await tick();+ expect(client.reexecuteOperation).toHaveBeenCalledTimes(2);+ expect(+ vi.mocked(client.reexecuteOperation).mock.calls[1]?.[0]?.context+ .normalizedCacheReplacementRegistrationOnly+ ).toBe(false);+ expect(host.reads).toHaveLength(3);+ expect(forwarded).toHaveLength(2);+ });++ it('drops retained replacement payload on teardown', async () => {+ host.readQuery = async (args) => {+ host.reads.push({ opKey: args.opKey, query: args.query });+ throw Object.assign(new Error('old owner lost'), {+ errorCode: 'owner-epoch-lost',+ });+ };+ host.writeQuery = vi+ .fn()+ .mockRejectedValue(new Error('replacement init not ready'));+ const { ops, network, forwarded, client } = controlledQueryHarness(host);+ const op = makeOp(45);+ ops.next(op);+ await tick();+ network.next({+ operation: forwarded[0]!,+ data: { from: 'network' },+ error: undefined,+ extensions: undefined,+ stale: false,+ hasNext: false,+ });+ await tick();++ ops.next(teardownOf(op));+ await tick();+ host.pushAffected([45]);+ await tick();++ expect(host.writeQuery).toHaveBeenCalledOnce();+ expect(host.reads).toHaveLength(1);+ expect(client.reexecuteOperation).not.toHaveBeenCalled();+ expect(forwarded).toHaveLength(2);+ expect(forwarded[1]?.kind).toBe('teardown');+ });++ it('reexecutes an old rejected cache-only read without forwarding the API', async () => {+ let readCount = 0;+ host.readQuery = async (args) => {+ host.reads.push({ opKey: args.opKey, query: args.query });+ readCount += 1;+ if (readCount === 1) {+ throw Object.assign(new Error('old owner lost'), {+ errorCode: 'owner-epoch-lost',+ });+ }+ return { kind: 'miss' };+ };+ const { ops, forwarded, client } = controlledQueryHarness(host);+ ops.next(makeOp(44, 'cache-only'));+ await tick();++ host.pushAffected([44]);+ await tick();++ expect(client.reexecuteOperation).toHaveBeenCalledOnce();+ const reissued = vi.mocked(client.reexecuteOperation).mock.calls[0]?.[0];+ expect(reissued?.context.requestPolicy).toBe('cache-only');+ expect(forwarded).toHaveLength(0);+ expect(host.reads).toHaveLength(2);+ });+it('teardown unregisters the op with the host and stops re-execution', async () => {const { ops, client } = harness(host);const op = makeOp(7);@@ -1041,6 +1415,133 @@ describe('normalizedCacheExchange', () => {expect(results[0]?.data).toEqual({ from: 'network' });});+ it('does not forward an admitted enqueue rejected by pagehide uncertainty', async () => {+ host.enqueueOptimisticMutation = vi.fn().mockRejectedValue(+ Object.assign(new Error('pagehide abruptly disposed the host'), {+ errorCode: ADMITTED_ENQUEUE_UNCERTAIN_ERROR_CODE,+ })+ );+ const { ops, results, forwarded } = harness(host);++ ops.next(makeMutationOp(1, optimistic));+ await tick();++ expect(forwarded).toHaveLength(0);+ expect(results).toHaveLength(1);+ expect(results[0]?.error?.networkError).toMatchObject({+ errorCode: 'admitted-enqueue-uncertain',+ });+ });++ it('keeps a standby enqueue off the API while graceful disposal waits for its response', async () => {+ const enqueue = host.enqueueOptimisticMutation.bind(host);+ let releaseResponse!: () => void;+ const responseGate = new Promise<void>((resolve) => {+ releaseResponse = resolve;+ });+ host.enqueueOptimisticMutation = async (args, claim) => {+ await responseGate;+ return {+ ...(await enqueue(args, claim)),+ initialClaim: { kind: 'not-runnable' },+ };+ };+ const { ops, results, forwarded } = harness(host);++ ops.next(makeMutationOp(1, optimistic));+ await tick();+ host.dispose();+ expect(forwarded).toHaveLength(0);+ expect(results).toHaveLength(0);+ releaseResponse();+ await tick();++ expect(forwarded).toHaveLength(0);+ expect(optimisticMutationDispositionOf(results[0])).toEqual({+ kind: 'queued',+ transactionId: 'txn-1',+ });+ });++ it('does not forward when graceful disposal sees transport failure while waiting', async () => {+ let rejectResponse!: (error: Error) => void;+ host.enqueueOptimisticMutation = vi.fn(+ async () =>+ await new Promise<EnqueueOptimisticMutationResult>(+ (_resolve, reject) => {+ rejectResponse = reject;+ }+ )+ );+ const { ops, results, forwarded } = harness(host);+ ops.next(makeMutationOp(1, optimistic));+ await tick();+ host.dispose();+ expect(forwarded).toHaveLength(0);++ rejectResponse(+ Object.assign(new Error('transport failed during graceful wait'), {+ errorCode: ADMITTED_ENQUEUE_UNCERTAIN_ERROR_CODE,+ })+ );+ await tick();++ expect(forwarded).toHaveLength(0);+ expect(results[0]?.error?.networkError).toMatchObject({+ errorCode: 'admitted-enqueue-uncertain',+ });+ });++ it('does not forward or retry an admitted enqueue after multi-tab transport uncertainty', async () => {+ const oldScopeQueue: unknown[] = [];+ const enqueueAttempts = vi.fn(+ async (args: Parameters<CacheHost['enqueueOptimisticMutation']>[0]) => {+ // A second tab could observe this durable side effect even though this+ // tab lost the SharedWorker response immediately afterward.+ oldScopeQueue.push(args.data);+ throw Object.assign(new Error('old-scope transport failed'), {+ errorCode: ADMITTED_ENQUEUE_UNCERTAIN_ERROR_CODE,+ });+ }+ );+ host.enqueueOptimisticMutation = enqueueAttempts;+ const secondTabObservedQueue = (): unknown[] => [...oldScopeQueue];+ const onCacheError = vi.fn();+ const { ops, results, forwarded } = harness(host, undefined, {+ onCacheError,+ });+ const base = makeMutationOp(1, optimistic);+ const operation = makeOperation(base.kind, base, {+ ...base.context,+ normalizedCacheOptimistic: {+ optimisticResponse: optimistic,+ linkPatches: [+ {+ query: 'query CachedList { cachedList { id } }',+ variablesJson: '{}',+ path: [{ field: 'cachedList' }],+ operation: { kind: 'remove', entityKey: 'Item:1' },+ },+ ],+ revalidations: [],+ },+ });++ ops.next(operation);+ await tick();++ expect(secondTabObservedQueue()).toEqual([optimistic]);+ expect(enqueueAttempts).toHaveBeenCalledOnce();+ expect(forwarded).toHaveLength(0);+ expect(results).toHaveLength(1);+ expect(results[0]?.data).toBeUndefined();+ expect(results[0]?.error?.networkError).toMatchObject({+ message: 'old-scope transport failed',+ errorCode: 'admitted-enqueue-uncertain',+ });+ expect(onCacheError).toHaveBeenCalledOnce();+ });+it('replays an older returned claim and reports the new caller as queued', async () => {host.seedQueued({query: stringifyDocument(MUTATION),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.tsindex a18dab2440..4f48e612a7 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@@ -26,11 +26,13 @@* - Without one: forwarded normally; successful responses are normalized* through the standard write path so dependent cached queries update.*- * Cache failures are never fatal: any host error degrades to the network.+ * Cache failures normally degrade to the network. An admitted optimistic+ * enqueue with an unfenced transport outcome emits an error instead, because+ * forwarding could duplicate a side effect already durable in the old scope.*/import {- type CombinedError,+ CombinedError,type Exchange,makeOperation,type Operation,@@ -58,10 +60,12 @@ import {tap,} from 'wonka';import type { CacheHost } from '../host/types';-import type {- ClaimedMutation,- EnqueueOptimisticMutationResult,- QueryRevalidationWire,+import {+ type ClaimedMutation,+ type EnqueueOptimisticMutationResult,+ isAdmittedEnqueueUncertainError,+ isOwnerEpochLostError,+ type QueryRevalidationWire,} from '../protocol';import {compileEntityResolvers,@@ -82,6 +86,9 @@ import {const QUEUE_ATTEMPT_CONTEXT_KEY = 'normalizedCacheQueueAttempt';/** Marks dependency-pushed reads as latency-sensitive worker work. */const AFFECTED_READ_CONTEXT_KEY = 'normalizedCacheAffectedRead';+/** Prevents a post-network dependency refresh from forwarding the API again. */+const REPLACEMENT_REGISTRATION_ONLY_CONTEXT_KEY =+ 'normalizedCacheReplacementRegistrationOnly';const QUEUE_REQUEST_TIMEOUT_MS = 60_000;const QUEUE_LEASE_MS = 5 * 60_000;const EMPTY_QUEUE_POLL_MS = 30_000;@@ -269,6 +276,17 @@ function operationCacheEffects(data: unknown): CacheEffect[] {);}+function uncertainEnqueueResult(op: Operation, error: Error): OperationResult {+ return {+ operation: op,+ data: undefined,+ error: new CombinedError({ networkError: error }),+ extensions: undefined,+ stale: false,+ hasNext: false,+ };+}+function queuedMutationResult(op: Operation,transactionId: string@@ -289,7 +307,7 @@ function queuedMutationResult(export interface NormalizedCacheExchangeOptions {/** Schema-typed singular entity relations derived from field arguments. */entityResolvers?: EntityResolverConfig;- /** Called when a cache read/write fails (diagnostics; flow already degraded to network). */+ /** Called when cache work fails; the operation may degrade or emit uncertainty. */onCacheError?: (error: unknown, op: Operation) => void;/*** Extracts the session identity (e.g. viewer id, `data.user.id`) from a@@ -322,20 +340,200 @@ export function normalizedCacheExchange(* later optimistic entity writes can affect the active operation.*/const dependencyRefreshOps = new Set<number>();+ type RetainedReplacementFallback = {+ version: number;+ writeArgs: Parameters<CacheHost['writeQuery']>[0];+ readyPending: boolean;+ recovering: boolean;+ invalidated: boolean;+ recoveryPromise?: Promise<void>;+ };+ type QueryState = {+ networkBoundQueries: number;+ replacementFallback: boolean;+ deferredAffected: boolean;+ completedReplacementFallback: boolean;+ networkRegistrationSatisfied: boolean;+ retainedReplacementFallback?: RetainedReplacementFallback;+ networkResultVersion: number;+ queryResultTurn?: Promise<void>;+ };+ const queryStates = new Map<number, QueryState>();+ const queryState = (key: number): QueryState => {+ let state = queryStates.get(key);+ if (!state) {+ state = {+ networkBoundQueries: 0,+ replacementFallback: false,+ deferredAffected: false,+ completedReplacementFallback: false,+ networkRegistrationSatisfied: false,+ networkResultVersion: 0,+ };+ queryStates.set(key, state);+ }+ return state;+ };++ const acquireQueryResultTurn = async (key: number): Promise<() => void> => {+ const state = queryState(key);+ const previous = state.queryResultTurn ?? Promise.resolve();+ let release!: () => void;+ const current = new Promise<void>((resolve) => {+ release = resolve;+ });+ state.queryResultTurn = current;+ await previous;+ return () => {+ release();+ if (+ queryStates.get(key) === state &&+ state.queryResultTurn === current+ ) {+ state.queryResultTurn = undefined;+ }+ };+ };++ const invalidateOlderRetainedFallback = async (+ key: number,+ version: number+ ): Promise<void> => {+ while (true) {+ const state = queryStates.get(key);+ const retained = state?.retainedReplacementFallback;+ if (!state || !retained || retained.version >= version) return;+ retained.invalidated = true;+ retained.readyPending = false;+ if (retained.recoveryPromise) {+ // Keep the exact in-flight candidate addressable until its cache+ // attempt settles; the newer result must write strictly after it.+ await retained.recoveryPromise;+ }+ if (state.retainedReplacementFallback === retained) {+ state.retainedReplacementFallback = undefined;+ }+ }+ };++ const reexecuteAffected = (key: number, registrationOnly = false): void => {+ const op = activeOps.get(key);+ if (!op) return;+ client.reexecuteOperation(+ makeOperation(op.kind, op, {+ ...op.context,+ requestPolicy:+ op.context.requestPolicy === 'cache-only'+ ? 'cache-only'+ : 'cache-first',+ [AFFECTED_READ_CONTEXT_KEY]: true,+ // activeOps observes every reissued operation. Explicitly clear the+ // one-shot marker so a later ordinary invalidation can reach the API.+ [REPLACEMENT_REGISTRATION_ONLY_CONTEXT_KEY]: registrationOnly,+ })+ );+ };++ const recoverRetainedReplacementFallback = (key: number): void => {+ const state = queryStates.get(key);+ const retained = state?.retainedReplacementFallback;+ if (!state || !retained || retained.invalidated || !activeOps.has(key))+ return;+ retained.readyPending = true;+ if (retained.recovering || state.networkBoundQueries > 0) return;+ retained.recovering = true;+ const recovery = (async () => {+ while (+ queryStates.get(key) === state &&+ state.retainedReplacementFallback === retained &&+ !retained.invalidated &&+ retained.readyPending+ ) {+ retained.readyPending = false;+ try {+ await host.writeQuery(retained.writeArgs);+ if (+ queryStates.get(key) !== state ||+ state.retainedReplacementFallback !== retained ||+ retained.invalidated ||+ !activeOps.has(key)+ ) {+ return;+ }+ // Register the complete normalized dependency set directly. This+ // cannot enqueue another API request or replay the old cache RPC.+ await host.readQuery({+ opKey: retained.writeArgs.opKey,+ query: retained.writeArgs.query,+ operationName: retained.writeArgs.operationName,+ variables: retained.writeArgs.variables,+ entityResolvers: retained.writeArgs.entityResolvers,+ });+ if (+ queryStates.get(key) !== state ||+ state.retainedReplacementFallback !== retained ||+ retained.invalidated+ ) {+ return;+ }+ state.retainedReplacementFallback = undefined;+ dependencyRefreshOps.delete(key);+ state.replacementFallback = false;+ state.deferredAffected = false;+ state.completedReplacementFallback = false;+ state.networkRegistrationSatisfied = false;+ return;+ } catch (error) {+ if (+ queryStates.get(key) !== state ||+ state.retainedReplacementFallback !== retained ||+ retained.invalidated+ ) {+ return;+ }+ const active = activeOps.get(key);+ if (active) options.onCacheError?.(error, active);+ // Preserve the successful payload for a later replacement-ready+ // notification. A notification received during this attempt sets+ // readyPending and safely drives exactly one subsequent attempt.+ }+ }+ })().catch(() => undefined);+ retained.recoveryPromise = recovery;+ void recovery.then(() => {+ if (retained.recoveryPromise === recovery) {+ retained.recoveryPromise = undefined;+ }+ if (+ queryStates.get(key) !== state ||+ state.retainedReplacementFallback !== retained+ )+ return;+ retained.recovering = false;+ if (retained.invalidated) {+ state.retainedReplacementFallback = undefined;+ } else if (retained.readyPending) {+ recoverRetainedReplacementFallback(key);+ }+ });+ };const unsubscribePush = host.onOpsAffected((opKeys) => {for (const key of opKeys) {- const op = activeOps.get(key);- if (!op) continue;- // Re-read from cache; do not stampede the network (graphcache does- // the same downgrade on dependency-driven re-execution).- client.reexecuteOperation(- makeOperation(op.kind, op, {- ...op.context,- requestPolicy: 'cache-first',- [AFFECTED_READ_CONTEXT_KEY]: true,- })- );+ if (!activeOps.has(key)) continue;+ const state = queryState(key);+ if (state.networkBoundQueries > 0) {+ state.deferredAffected = true;+ continue;+ }+ const registrationOnly = state.completedReplacementFallback;+ state.completedReplacementFallback = false;+ state.replacementFallback = false;+ if (state.retainedReplacementFallback) {+ recoverRetainedReplacementFallback(key);+ continue;+ }+ reexecuteAffected(key, registrationOnly);}});@@ -345,6 +543,44 @@ export function normalizedCacheExchange(// Async cache reads re-inject network-bound operations here.const { source: forwardQueue$, next: enqueueForward } =makeSubject<Operation>();++ const enqueueQueryForward = (op: Operation): void => {+ queryState(op.key).networkBoundQueries += 1;+ enqueueForward(op);+ };++ const finishNetworkQuery = (+ key: number,+ replacementRegistrationSatisfied: boolean+ ): void => {+ const state = queryState(key);+ const remaining = state.networkBoundQueries - 1;+ if (remaining > 0) {+ state.networkBoundQueries = remaining;+ return;+ }+ state.networkBoundQueries = 0;+ const deferred = state.deferredAffected;+ state.deferredAffected = false;+ const replacementFallback = state.replacementFallback;+ state.replacementFallback = false;+ if (deferred) {+ state.completedReplacementFallback = false;+ if (!replacementRegistrationSatisfied) {+ if (state.retainedReplacementFallback) {+ recoverRetainedReplacementFallback(key);+ } else {+ reexecuteAffected(key, true);+ }+ }+ } else if (replacementFallback) {+ // A fast fallback completed before replacement initialization. The+ // later affected notification must register cache dependencies but+ // must not issue the API request a second time.+ state.completedReplacementFallback = true;+ }+ };+const queueOwner = `exchange:${host.clientId}`;const liveQueuedOps = new Map<string,@@ -511,7 +747,7 @@ export function normalizedCacheExchange(const policy = op.context.requestPolicy;if (policy === 'network-only') {dependencyRefreshOps.add(op.key);- enqueueForward(op);+ enqueueQueryForward(op);return undefined;}try {@@ -528,7 +764,7 @@ export function normalizedCacheExchange(});if (read.kind === 'hit') {const stale = policy === 'cache-and-network';- if (stale) enqueueForward(op);+ if (stale) enqueueQueryForward(op);return cacheResult(op, read.data, stale);}if (policy === 'cache-only') {@@ -537,13 +773,19 @@ export function normalizedCacheExchange(dependencyRefreshOps.add(op.key);} catch (error) {options.onCacheError?.(error, op);+ if (isOwnerEpochLostError(error)) {+ queryState(op.key).replacementFallback = true;+ }// `cache-only` must never touch the network, even when the cache// itself fails — degrade to an empty result instead.if (policy === 'cache-only') {return cacheResult(op, undefined, false);}}- enqueueForward(op);+ if (op.context[REPLACEMENT_REGISTRATION_ONLY_CONTEXT_KEY] === true) {+ return undefined;+ }+ enqueueQueryForward(op);return undefined;}@@ -583,15 +825,19 @@ export function normalizedCacheExchange(try {enqueue = await host.enqueueOptimisticMutation(args, claim);} catch (error) {+ options.onCacheError?.(error, op);+ if (isAdmittedEnqueueUncertainError(error)) {+ // The old-scope queue may already contain the side effect. It is+ // unsafe to forward or retry without a coordinator fence.+ return uncertainEnqueueResult(op, error);+ }// A cached bin/page may disappear between inspect and enqueue. Do// not expose a partial relation move: retain entity optimism and// the post-success revalidation descriptors instead.if (args.linkPatches.length === 0) {- options.onCacheError?.(error, op);enqueueForward(op);return undefined;}- options.onCacheError?.(error, op);try {enqueue = await host.enqueueOptimisticMutation({@@ -610,6 +856,9 @@ export function normalizedCacheExchange();} catch (fallbackError) {options.onCacheError?.(fallbackError, op);+ if (isAdmittedEnqueueUncertainError(fallbackError)) {+ return uncertainEnqueueResult(op, fallbackError);+ }enqueueForward(op);return undefined;}@@ -692,28 +941,74 @@ export function normalizedCacheExchange(subscriptionEffectChains.delete(op.key);}}- } else if (op.kind === 'query' && result.data != null) {+ } else if (op.kind === 'query') {+ const releaseTurn = await acquireQueryResultTurn(op.key);try {- const args = {- opKey: op.key,- query: queryText(op),- operationName: operationName(op),- variables: op.variables as Record<string, unknown> | undefined,- entityResolvers,- };- await host.writeQuery({- ...args,- data: result.data,- identity: options.extractIdentity?.(result.data),- });- if (dependencyRefreshOps.delete(op.key) && activeOps.has(op.key)) {- // A miss only records dependencies reached before the missing- // record. Re-read the now-populated query to register its full- // entity graph for push-driven optimistic updates.- await host.readQuery(args);+ const state = queryState(op.key);+ const resultVersion = state.networkResultVersion + 1;+ state.networkResultVersion = resultVersion;+ // Every newer result supersedes an older retained payload, even an+ // error or intermediate streamed result with no cache write.+ await invalidateOlderRetainedFallback(op.key, resultVersion);+ if (result.data != null) {+ const readArgs = {+ opKey: op.key,+ query: queryText(op),+ operationName: operationName(op),+ variables: op.variables as Record<string, unknown> | undefined,+ entityResolvers,+ };+ const writeArgs = {+ ...readArgs,+ data: result.data,+ identity: options.extractIdentity?.(result.data),+ };+ const retained: RetainedReplacementFallback | undefined =+ result.error === undefined &&+ result.hasNext !== true &&+ activeOps.has(op.key) &&+ state.replacementFallback+ ? {+ version: resultVersion,+ writeArgs,+ readyPending: false,+ recovering: false,+ invalidated: false,+ }+ : undefined;+ if (retained) {+ // Install before the first write: replacement-ready pushes can+ // arrive synchronously while the cache attempt is settling.+ state.retainedReplacementFallback = retained;+ }+ try {+ await host.writeQuery(writeArgs);+ if (+ activeOps.has(op.key) &&+ (dependencyRefreshOps.has(op.key) || state.deferredAffected)+ ) {+ // A miss or replacement fallback needs one successful read+ // on the current generation after network write-through.+ await host.readQuery(readArgs);+ dependencyRefreshOps.delete(op.key);+ state.networkRegistrationSatisfied = true;+ }+ if (state.retainedReplacementFallback === retained) {+ state.retainedReplacementFallback = undefined;+ }+ } catch (error) {+ options.onCacheError?.(error, op);+ }}- } catch (error) {- options.onCacheError?.(error, op);+ if (result.hasNext !== true) {+ dependencyRefreshOps.delete(op.key);+ const registrationSatisfied = state.networkRegistrationSatisfied;+ state.networkRegistrationSatisfied = false;+ finishNetworkQuery(op.key, registrationSatisfied);+ }+ } finally {+ if (!activeOps.has(op.key)) queryStates.delete(op.key);+ releaseTurn();}} else if (op.kind === 'mutation') {const attempt = queueAttemptOf(op);@@ -852,6 +1147,7 @@ export function normalizedCacheExchange(if (op.kind === 'teardown') {activeOps.delete(op.key);dependencyRefreshOps.delete(op.key);+ queryStates.delete(op.key);host.teardown(op.key).catch(() => undefined);}})diff --git a/apps/web/src/lib/graphql-cache/host/types.ts b/apps/web/src/lib/graphql-cache/host/types.tsindex 8e2f2ac8b4..e9125f5ad1 100644--- a/apps/web/src/lib/graphql-cache/host/types.ts+++ b/apps/web/src/lib/graphql-cache/host/types.ts@@ -1,7 +1,8 @@/*** Transport-agnostic cache host interface consumed by the urql exchange and* imperative writers (websocket handlers). Implementations:- * - worker-host.ts: browser (SharedWorker + wasm engine, or no-op fallback)+ * - worker-host.ts: browser (SharedWorker coordinator + elected WASM engine,+ * or no-op fallback)* - tauri-host.ts (Phase 3b): Tauri IPC to the native engine*/@@ -72,7 +73,7 @@ export interface InitialMutationClaimArgs {export interface CacheHost {/** Stable id of this context; used to namespace operation ids. */readonly clientId: string;- /** True for the storage-free fallback used without SharedWorker support. */+ /** True for the storage-free fallback when browser cache APIs are unsupported. */readonly disabled?: boolean;readQuery(args: CacheReadArgs): Promise<ReadResult>;diff --git a/apps/web/src/lib/graphql-cache/host/worker-host.integration.test.ts b/apps/web/src/lib/graphql-cache/host/worker-host.integration.test.tsnew file mode 100644index 0000000000..ce2a6a4e4a--- /dev/null+++ b/apps/web/src/lib/graphql-cache/host/worker-host.integration.test.ts@@ -0,0 +1,617 @@+import {+ type Client,+ gql,+ makeOperation,+ type Operation,+ type OperationResult,+} from '@urql/core';+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';+import { makeSubject, pipe, type Source, subscribe } from 'wonka';+import { normalizedCacheExchange } from '../exchange/normalized-cache-exchange';+import type { CacheRequest, CacheResponse } from '../protocol';+import { installCacheEngineWorker } from '../worker/cache-engine-runtime';+import {+ type CoordinatorMessagePort,+ CoordinatorRouter,+} from '../worker/coordinator-router';+import type { CacheHost } from './types';+import { createWorkerCacheHost } from './worker-host';++const PAGEHIDE_MUTATION = gql`+ mutation HoldPagehide {+ holdPagehide+ }+`;+const STANDBY_MUTATION = gql`+ mutation HoldStandby {+ holdStandby+ }+`;+const RETIREMENT_FAILURE_MUTATION = gql`+ mutation HoldRetirementFailure {+ holdRetirementFailure+ }+`;++function exchangeHarness(host: CacheHost, operation: Operation) {+ const operations = makeSubject<Operation>();+ const network = makeSubject<OperationResult>();+ const forwarded: Operation[] = [];+ const results: OperationResult[] = [];+ const client = { reexecuteOperation: vi.fn() } as unknown as Client;+ const forward = (source: Source<Operation>): Source<OperationResult> => {+ pipe(+ source,+ subscribe((forwardedOperation) => forwarded.push(forwardedOperation))+ );+ return network.source;+ };+ pipe(+ normalizedCacheExchange(host)({+ forward,+ client,+ dispatchDebug: () => undefined,+ })(operations.source),+ subscribe((result) => results.push(result))+ );+ operations.next(operation);+ return { forwarded, results };+}++function optimisticMutation(key: number, query: Operation['query']): Operation {+ return makeOperation('mutation', { key, query, variables: {} }, {+ requestPolicy: 'cache-first',+ url: 'http://integration.test',+ suspense: false,+ normalizedCacheOptimistic: {+ optimisticResponse: { held: true },+ },+ } as never);+}++class LinkedMessagePort {+ peer: LinkedMessagePort | undefined;+ onmessage: ((event: MessageEvent<unknown>) => void) | null = null;+ onmessageerror: (() => void) | null = null;+ closed = false;++ postMessage(message: unknown, transfer: Transferable[] = []): void {+ const peer = this.peer;+ if (this.closed || !peer || peer.closed) return;+ queueMicrotask(() => {+ if (peer.closed) return;+ peer.onmessage?.({+ data: message,+ ports: transfer,+ } as unknown as MessageEvent);+ });+ }++ start(): void {}++ close(): void {+ this.closed = true;+ }+}++class LinkedMessageChannel {+ readonly port1 = new LinkedMessagePort();+ readonly port2 = new LinkedMessagePort();++ constructor() {+ this.port1.peer = this.port2;+ this.port2.peer = this.port1;+ }+}++type RuntimeLog = {+ epoch: number;+ kind: CacheRequest['kind'] | 'drain';+ id?: number;+ query?: string;+};++type Deferred = { promise: Promise<void>; resolve: () => void };+const deferred = (): Deferred => {+ let resolve!: () => void;+ const promise = new Promise<void>((settle) => {+ resolve = settle;+ });+ return { promise, resolve };+};++class IntegrationCore {+ constructor(+ private readonly epoch: number,+ private readonly logs: RuntimeLog[],+ private readonly activationGates: Map<number, Promise<void>>,+ private readonly hostInitGates: Map<number, Promise<void>>,+ private readonly enqueueGates: Map<string, Promise<void>>+ ) {}++ addPort(): void {}++ async handleRequest(+ port: { postMessage(message: unknown): void },+ request: CacheRequest+ ): Promise<void> {+ this.logs.push({+ epoch: this.epoch,+ kind: request.kind,+ id: request.id,+ query: 'query' in request ? request.query : undefined,+ });+ if (request.kind === 'init') {+ const gate =+ request.id === 0+ ? this.activationGates.get(this.epoch)+ : this.hostInitGates.get(this.epoch);+ if (gate) await gate;+ }+ if (request.kind === 'read' && request.query.includes('Slow')) {+ await new Promise<void>(() => undefined);+ return;+ }+ if (request.kind === 'enqueue-optimistic-mutation') {+ const gate = this.enqueueGates.get(request.operationName ?? '');+ if (gate) await gate;+ }+ let result: unknown = null;+ if (request.kind === 'read') result = { kind: 'miss' };+ if (request.kind === 'enqueue-optimistic-mutation') {+ result = {+ transactionId: `integration-${request.id}`,+ changed: [],+ affectedOps: [],+ reset: false,+ initialClaim: { kind: 'not-runnable' },+ };+ }+ const response: CacheResponse = { id: request.id, ok: true, result };+ port.postMessage(response);+ }++ async drain(): Promise<void> {+ this.logs.push({ epoch: this.epoch, kind: 'drain' });+ }+}++class IntegrationWorkerScope {+ onmessage: ((event: MessageEvent<unknown>) => void) | null = null;+ closed = false;++ close(): void {+ this.closed = true;+ }+}++class IntegrationDedicatedWorker {+ onerror: ((this: AbstractWorker, event: ErrorEvent) => unknown) | null = null;+ onmessageerror: ((this: Worker, event: MessageEvent) => unknown) | null =+ null;+ readonly scope = new IntegrationWorkerScope();+ terminated = false;++ constructor(+ readonly epoch: number,+ logs: RuntimeLog[],+ activationGates: Map<number, Promise<void>>,+ hostInitGates: Map<number, Promise<void>>,+ enqueueGates: Map<string, Promise<void>>+ ) {+ installCacheEngineWorker({+ scope: this.scope,+ createCore: () =>+ new IntegrationCore(+ epoch,+ logs,+ activationGates,+ hostInitGates,+ enqueueGates+ ),+ ownerLockIsHeld: async () => true,+ });+ }++ postMessage(message: unknown, transfer: Transferable[]): void {+ this.scope.onmessage?.({+ data: message,+ ports: transfer,+ } as unknown as MessageEvent);+ }++ terminate(): void {+ this.terminated = true;+ }++ fail(message: string): void {+ this.onerror?.call(+ {} as AbstractWorker,+ { message, preventDefault: vi.fn() } as unknown as ErrorEvent+ );+ }+}++class IntegrationSharedWorker {+ onerror: ((this: AbstractWorker, event: ErrorEvent) => unknown) | null = null;+ readonly port: LinkedMessagePort;++ constructor(router: CoordinatorRouter) {+ const channel = new LinkedMessageChannel();+ this.port = channel.port1;+ router.connect(channel.port2 as unknown as CoordinatorMessagePort);+ }++ fail(message: string): void {+ this.onerror?.call(+ {} as AbstractWorker,+ { message, preventDefault: vi.fn() } as unknown as ErrorEvent+ );+ }+}++describe('worker CacheHost coordinator integration', () => {+ const logs: RuntimeLog[] = [];+ const dedicatedWorkers: IntegrationDedicatedWorker[] = [];+ const sharedWorkers: IntegrationSharedWorker[] = [];+ const activationGates = new Map<number, Promise<void>>();+ const hostInitGates = new Map<number, Promise<void>>();+ const enqueueGates = new Map<string, Promise<void>>();++ beforeEach(() => {+ localStorage.clear();+ logs.length = 0;+ dedicatedWorkers.length = 0;+ sharedWorkers.length = 0;+ activationGates.clear();+ hostInitGates.clear();+ enqueueGates.clear();+ const router = new CoordinatorRouter({+ verifyTabLockHeld: async () => true,+ watchTabLock: () => () => undefined,+ });+ vi.stubGlobal('MessageChannel', LinkedMessageChannel);+ vi.stubGlobal(+ 'SharedWorker',+ class {+ onerror: IntegrationSharedWorker['onerror'] = null;+ readonly port: LinkedMessagePort;++ constructor() {+ const worker = new IntegrationSharedWorker(router);+ sharedWorkers.push(worker);+ this.port = worker.port;+ Object.defineProperty(this, 'onerror', {+ get: () => worker.onerror,+ set: (value) => {+ worker.onerror = value;+ },+ });+ }+ }+ );+ vi.stubGlobal(+ 'Worker',+ class {+ readonly delegate: IntegrationDedicatedWorker;++ constructor(_url: URL, options?: WorkerOptions) {+ const epoch = Number(options?.name?.split(':').at(-1));+ this.delegate = new IntegrationDedicatedWorker(+ epoch,+ logs,+ activationGates,+ hostInitGates,+ enqueueGates+ );+ dedicatedWorkers.push(this.delegate);+ }++ get onerror(): IntegrationDedicatedWorker['onerror'] {+ return this.delegate.onerror;+ }++ set onerror(value: IntegrationDedicatedWorker['onerror']) {+ this.delegate.onerror = value;+ }++ get onmessageerror(): IntegrationDedicatedWorker['onmessageerror'] {+ return this.delegate.onmessageerror;+ }++ set onmessageerror(value: IntegrationDedicatedWorker['onmessageerror'],) {+ this.delegate.onmessageerror = value;+ }++ postMessage(message: unknown, transfer: Transferable[]): void {+ this.delegate.postMessage(message, transfer);+ }++ terminate(): void {+ this.delegate.terminate();+ }+ }+ );+ vi.stubGlobal('navigator', {+ locks: {+ request: async (+ name: string,+ _options: LockOptions,+ callback: (lock: Lock | null) => unknown+ ) => await callback({ name, mode: 'exclusive' } as Lock),+ },+ storage: { getDirectory: vi.fn() },+ });+ });++ afterEach(() => {+ vi.unstubAllGlobals();+ vi.restoreAllMocks();+ });++ it('registers, replaces without replay or duplicate reread, and retires gracefully', async () => {+ const host = createWorkerCacheHost({+ scope: 'integration-scope',+ requestTimeoutMs: 1_000,+ });+ const order: string[] = [];+ let replacementRead: Promise<unknown> | undefined;+ host.onOpsAffected((keys) => {+ order.push(`affected:${keys.join(',')}`);+ replacementRead = host.readQuery({+ opKey: keys[0],+ query: 'query Replacement { replacement }',+ });+ });++ expect(sharedWorkers).toHaveLength(0);+ expect(dedicatedWorkers).toHaveLength(0);++ await expect(+ host.readQuery({ query: 'query Warm { warm }' })+ ).resolves.toEqual({ kind: 'miss' });+ await Promise.all([+ host.readQuery({ opKey: 7, query: 'query RegisteredSeven { seven }' }),+ host.readQuery({ opKey: 9, query: 'query RegisteredNine { nine }' }),+ ]);+ expect(sharedWorkers).toHaveLength(1);+ expect(dedicatedWorkers.map((worker) => worker.epoch)).toEqual([1]);++ const slowRead = host.readQuery({+ opKey: 7,+ query: 'query Slow { slow }',+ });+ const slowRejected = expect(slowRead).rejects.toMatchObject({+ errorCode: 'owner-epoch-lost',+ });+ void slowRead.catch(() => order.push('old-request-rejected'));+ await vi.waitFor(() =>+ expect(+ logs.filter(+ ({ epoch, query }) => epoch === 1 && query?.includes('Slow')+ )+ ).toHaveLength(1)+ );++ dedicatedWorkers[0]?.fail('integration engine loss');+ await slowRejected;+ await vi.waitFor(() => expect(order).toContain('affected:7,9'));+ await vi.waitFor(() => expect(replacementRead).toBeDefined());+ await expect(replacementRead).resolves.toEqual({ kind: 'miss' });++ expect(order).toEqual(['old-request-rejected', 'affected:7,9']);+ expect(dedicatedWorkers.map((worker) => worker.epoch)).toEqual([1, 2]);+ expect(dedicatedWorkers[0]?.terminated).toBe(true);+ expect(logs.filter(({ query }) => query?.includes('Slow'))).toHaveLength(1);+ expect(+ logs.filter(+ ({ epoch, kind, id }) => epoch === 2 && kind === 'init' && id !== 0+ )+ ).toHaveLength(1);+ expect(+ logs.filter(+ ({ epoch, query }) =>+ epoch === 2 && query === 'query Replacement { replacement }'+ )+ ).toHaveLength(1);++ host.dispose();+ await vi.waitFor(() => expect(dedicatedWorkers[1]?.terminated).toBe(true));+ expect(logs).toContainEqual({ epoch: 2, kind: 'drain' });+ expect(sharedWorkers[0]?.port.closed).toBe(true);+ });++ it('does not duplicate reads queued before or joined during replacement init', async () => {+ const activationGate = deferred();+ const hostInitGate = deferred();+ activationGates.set(2, activationGate.promise);+ hostInitGates.set(2, hostInitGate.promise);+ const host = createWorkerCacheHost({+ scope: 'integration-scope',+ requestTimeoutMs: 1_000,+ });+ const affected: number[][] = [];+ let replacementRead: Promise<unknown> | undefined;+ host.onOpsAffected((keys) => {+ affected.push(keys);+ replacementRead = host.readQuery({+ opKey: keys[0],+ query: 'query UntouchedReplacement { ten }',+ });+ });+ await Promise.all(+ [8, 9, 10].map((opKey) =>+ host.readQuery({+ opKey,+ query: `query Registered${opKey} { value${opKey} }`,+ })+ )+ );++ // No request from this host is in flight when the owner is lost, so the+ // host remains ready while the coordinator enters resetting/activating.+ dedicatedWorkers[0]?.fail('integration engine loss');+ await vi.waitFor(() =>+ expect(dedicatedWorkers.map(({ epoch }) => epoch)).toEqual([1, 2])+ );+ const queuedBefore = host.readQuery({+ opKey: 8,+ query: 'query QueuedBefore { eight }',+ });+ expect(+ logs.filter(+ ({ epoch, query }) => epoch === 2 && query?.includes('QueuedBefore')+ )+ ).toHaveLength(0);+ activationGate.resolve();+ await vi.waitFor(() =>+ expect(+ logs.filter(+ ({ epoch, kind, id }) => epoch === 2 && kind === 'init' && id !== 0+ )+ ).toHaveLength(1)+ );++ const joinedDuring = host.readQuery({+ opKey: 9,+ query: 'query JoinedDuring { nine }',+ });+ hostInitGate.resolve();+ await expect(queuedBefore).resolves.toEqual({ kind: 'miss' });+ await expect(joinedDuring).resolves.toEqual({ kind: 'miss' });+ await vi.waitFor(() => expect(affected).toEqual([[10]]));+ await vi.waitFor(() => expect(replacementRead).toBeDefined());+ await expect(replacementRead).resolves.toEqual({ kind: 'miss' });++ expect(+ logs.filter(+ ({ epoch, query }) => epoch === 2 && query?.includes('QueuedBefore')+ )+ ).toHaveLength(1);+ expect(+ logs.filter(+ ({ epoch, query }) => epoch === 2 && query?.includes('JoinedDuring')+ )+ ).toHaveLength(1);+ expect(+ logs.filter(+ ({ epoch, query }) =>+ epoch === 2 && query?.includes('UntouchedReplacement')+ )+ ).toHaveLength(1);+ host.dispose();+ });++ it('keeps API forwarding at zero when pagehide abandons an admitted enqueue', async () => {+ const gate = deferred();+ enqueueGates.set('HoldPagehide', gate.promise);+ localStorage.setItem('graphql-cache:scope', 'integration-scope');+ const host = createWorkerCacheHost({ scope: 'integration-scope' });+ const { forwarded, results } = exchangeHarness(+ host,+ optimisticMutation(101, PAGEHIDE_MUTATION)+ );+ await vi.waitFor(() =>+ expect(+ logs.filter(+ ({ kind, query }) =>+ kind === 'enqueue-optimistic-mutation' &&+ query?.includes('HoldPagehide')+ )+ ).toHaveLength(1)+ );++ dispatchEvent(new Event('pagehide'));+ await vi.waitFor(() => expect(results).toHaveLength(1));++ expect(forwarded).toHaveLength(0);+ expect(results[0]?.error?.networkError).toMatchObject({+ errorCode: 'admitted-enqueue-uncertain',+ });+ await vi.waitFor(() =>+ expect(localStorage.getItem('graphql-cache:scope')).toBe(+ 'quarantine:integration-scope'+ )+ );+ });++ it('keeps a standby connected until its admitted enqueue response settles', async () => {+ const owner = createWorkerCacheHost({ scope: 'integration-scope' });+ await owner.readQuery({ query: 'query OwnerWarm { ownerWarm }' });+ const gate = deferred();+ enqueueGates.set('HoldStandby', gate.promise);+ const standby = createWorkerCacheHost({ scope: 'integration-scope' });+ const { forwarded, results } = exchangeHarness(+ standby,+ optimisticMutation(102, STANDBY_MUTATION)+ );+ await vi.waitFor(() =>+ expect(+ logs.filter(+ ({ kind, query }) =>+ kind === 'enqueue-optimistic-mutation' &&+ query?.includes('HoldStandby')+ )+ ).toHaveLength(1)+ );++ standby.dispose();+ expect(sharedWorkers[1]?.port.closed).toBe(false);+ gate.resolve();+ await vi.waitFor(() => expect(results).toHaveLength(1));+ await vi.waitFor(() => expect(sharedWorkers[1]?.port.closed).toBe(true));++ expect(forwarded).toHaveLength(0);+ expect(results[0]?.error).toBeUndefined();+ owner.dispose();+ await vi.waitFor(() => expect(dedicatedWorkers[0]?.terminated).toBe(true));+ });++ it('keeps API forwarding at zero when standby retirement transport fails', async () => {+ const owner = createWorkerCacheHost({ scope: 'integration-scope' });+ await owner.readQuery({ query: 'query OwnerWarm { ownerWarm }' });+ const gate = deferred();+ enqueueGates.set('HoldRetirementFailure', gate.promise);+ localStorage.setItem('graphql-cache:scope', 'integration-scope');+ const initializationErrors: string[] = [];+ const standby = createWorkerCacheHost({+ scope: 'integration-scope',+ onInitializationError: (error) =>+ initializationErrors.push(error.message),+ });+ const { forwarded, results } = exchangeHarness(+ standby,+ optimisticMutation(103, RETIREMENT_FAILURE_MUTATION)+ );+ await vi.waitFor(() =>+ expect(+ logs.filter(+ ({ kind, query }) =>+ kind === 'enqueue-optimistic-mutation' &&+ query?.includes('HoldRetirementFailure')+ )+ ).toHaveLength(1)+ );++ standby.dispose();+ expect(sharedWorkers[1]?.port.closed).toBe(false);+ sharedWorkers[1]?.fail('standby SharedWorker failed during retirement');+ await vi.waitFor(() => expect(results).toHaveLength(1));++ expect(forwarded).toHaveLength(0);+ expect(results[0]?.error?.networkError).toMatchObject({+ errorCode: 'admitted-enqueue-uncertain',+ });+ await vi.waitFor(() => {+ expect(localStorage.getItem('graphql-cache:scope')).toBe(+ 'quarantine:integration-scope'+ );+ expect(initializationErrors).toEqual([+ 'standby SharedWorker failed during retirement',+ ]);+ });+ gate.resolve();+ owner.dispose();+ await vi.waitFor(() => expect(dedicatedWorkers[0]?.terminated).toBe(true));+ });+});diff --git a/apps/web/src/lib/graphql-cache/host/worker-host.test.ts b/apps/web/src/lib/graphql-cache/host/worker-host.test.tsindex 7f23711400..637fd8e14b 100644--- a/apps/web/src/lib/graphql-cache/host/worker-host.test.ts+++ b/apps/web/src/lib/graphql-cache/host/worker-host.test.ts@@ -1,17 +1,181 @@-import { afterEach, describe, expect, it, vi } from 'vitest';+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';+import type {+ CacheRequest,+ CacheResponseErrorCode,+ WorkerMessage,+ WriteResult,+} from '../protocol';+import type {+ CacheCoordinatorPageAdapter,+ CacheCoordinatorPageAdapterOptions,+ PageAdapterDisposeOptions,+} from '../worker/coordinator-page-adapter';++const adapterFactory = vi.hoisted(() => vi.fn());++vi.mock('../worker/coordinator-page-adapter', () => ({+ createCacheCoordinatorPageAdapter: adapterFactory,+}));+import { createWorkerCacheHost } from './worker-host';+const CLIENT_ID = '00000000-0000-4000-8000-000000000007';+const EMPTY_WRITE: WriteResult = {+ changed: [],+ affectedOps: [],+ reset: false,+};++function responseFor(request: CacheRequest): unknown {+ switch (request.kind) {+ case 'read':+ return { kind: 'miss' };+ case 'read-records':+ return { records: [], nextCursor: null };+ case 'write':+ case 'commit-optimistic-write':+ case 'rollback-optimistic-write':+ return EMPTY_WRITE;+ case 'enqueue-optimistic-mutation':+ return {+ ...EMPTY_WRITE,+ transactionId: '1',+ initialClaim: { kind: 'not-runnable' },+ };+ case 'inspect-query':+ case 'inspect-query-variants':+ return [];+ case 'claim-next-mutation':+ return undefined;+ case 'invalidate':+ case 'delete-records':+ return request.keys;+ case 'init':+ case 'defer-optimistic-write':+ case 'teardown':+ case 'clear':+ return null;+ }+}++class FakePageAdapter {+ onmessage: ((event: MessageEvent<WorkerMessage>) => void) | null = null;+ readonly requests: CacheRequest[] = [];+ readonly ignoredKinds = new Set<CacheRequest['kind']>();+ readonly errors = new Map<CacheRequest['kind'], string>();+ readonly dispose = vi.fn(+ async (_options: PageAdapterDisposeOptions = {}): Promise<void> => {}+ );++ constructor(readonly options: CacheCoordinatorPageAdapterOptions) {}++ postMessage(request: CacheRequest): void {+ this.requests.push(request);+ if (this.ignoredKinds.has(request.kind)) return;+ const error = this.errors.get(request.kind);+ queueMicrotask(() => {+ if (error === undefined) this.respond(request.id, responseFor(request));+ else this.reject(request.id, error);+ });+ }++ respond(id: number, result: unknown): void {+ this.emit({ id, ok: true, result });+ }++ reject(id: number, error: string, errorCode?: CacheResponseErrorCode): void {+ this.emit({+ id,+ ok: false,+ error,+ ...(errorCode === undefined ? {} : { errorCode }),+ });+ }++ push(message: WorkerMessage | unknown): void {+ this.emit(message as WorkerMessage);+ }++ replace(ownerEpoch: number): void {+ this.options.onEngineReplaced?.(ownerEpoch);+ }++ protocolError(error: Error): void {+ this.options.onProtocolError?.(error);+ }++ terminalError(error: Error): void {+ this.options.onTerminalError?.(error);+ }++ private emit(message: WorkerMessage): void {+ this.onmessage?.({ data: message } as MessageEvent<WorkerMessage>);+ }+}++let lastAdapter: FakePageAdapter | undefined;+let configureAdapter: (adapter: FakePageAdapter) => void;+let sharedWorkerConstructor: ReturnType<typeof vi.fn>;+let dedicatedWorkerConstructor: ReturnType<typeof vi.fn>;+let indexedDbDelete: ReturnType<typeof vi.fn>;++function stubSupportedBrowser(): void {+ sharedWorkerConstructor = vi.fn();+ dedicatedWorkerConstructor = vi.fn();+ vi.stubGlobal('SharedWorker', sharedWorkerConstructor);+ vi.stubGlobal('Worker', dedicatedWorkerConstructor);+ vi.stubGlobal('MessageChannel', vi.fn());+ indexedDbDelete = vi.fn(() => ({+ onblocked: null,+ onerror: null,+ onsuccess: null,+ }));+ vi.stubGlobal('indexedDB', { deleteDatabase: indexedDbDelete });+ vi.stubGlobal('navigator', {+ locks: {+ request: vi.fn(+ async (+ name: string,+ _options: LockOptions,+ callback: (lock: Lock | null) => unknown+ ) => await callback({ name, mode: 'exclusive' } as Lock)+ ),+ },+ storage: { getDirectory: vi.fn() },+ });+}++function requireAdapter(): FakePageAdapter {+ if (!lastAdapter) throw new Error('page adapter was not constructed');+ return lastAdapter;+}+describe('createWorkerCacheHost', () => {+ beforeEach(() => {+ localStorage.clear();+ stubSupportedBrowser();+ vi.spyOn(crypto, 'randomUUID').mockReturnValue(CLIENT_ID);+ lastAdapter = undefined;+ configureAdapter = () => undefined;+ adapterFactory.mockReset();+ adapterFactory.mockImplementation(+ (options: CacheCoordinatorPageAdapterOptions) => {+ const fake = new FakePageAdapter(options);+ configureAdapter(fake);+ lastAdapter = fake;+ return fake as unknown as CacheCoordinatorPageAdapter;+ }+ );+ });+afterEach(() => {vi.useRealTimers();vi.unstubAllGlobals();vi.restoreAllMocks();});- it('uses a storage-free no-op host when SharedWorker is unavailable', async () => {- const worker = vi.fn();+ it('uses a storage-free no-op host when a required capability is unavailable', async () => {vi.stubGlobal('SharedWorker', undefined);- vi.stubGlobal('Worker', worker);const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});const host = createWorkerCacheHost({ scope: 'scope-1' });@@ -19,243 +183,378 @@ describe('createWorkerCacheHost', () => {expect(warn).toHaveBeenCalledWith('[graphql-cache] disabled: SharedWorker is not supported by this browser');- expect(worker).not.toHaveBeenCalled();+ expect(adapterFactory).not.toHaveBeenCalled();+ expect(dedicatedWorkerConstructor).not.toHaveBeenCalled();+ expect(indexedDbDelete).not.toHaveBeenCalled();expect(host.disabled).toBe(true);await expect(host.readQuery({ query: '{ x }' })).resolves.toEqual({kind: 'miss',});await expect(host.writeQuery({ query: '{ x }', data: { x: 1 } })- ).resolves.toEqual({ changed: [], affectedOps: [], reset: false });- await expect(- host.readRecords({- document: 'fragment Item on GraphqlSoupItem { id }',- fragmentName: 'Item',- limit: 20,- })- ).resolves.toEqual({ records: [], nextCursor: null });+ ).resolves.toEqual(EMPTY_WRITE);});- it('round-trips generated query inspection through the worker protocol', async () => {- const requests: unknown[] = [];- const variants = [{ variables: { input: { initial: { limit: 20 } } } }];- const instances = variants.map((variant) => ({- ...variant,- value: { bins: [] },- }));- class FakeSharedWorker {- port = {- onmessage: null as ((event: MessageEvent) => void) | null,- start() {},- close() {},- postMessage: (request: { id?: number; kind: string }) => {- requests.push(request);- if (request.id === undefined) return;- queueMicrotask(() => {- this.port.onmessage?.({- data: {- id: request.id,- ok: true,- result:- request.kind === 'inspect-query'- ? instances- : request.kind === 'inspect-query-variants'- ? variants- : null,- },- } as MessageEvent);- });- },- };- }- vi.stubGlobal('SharedWorker', FakeSharedWorker);+ it('uses the no-op host when OPFS is unavailable', () => {+ vi.stubGlobal('navigator', {+ locks: { request: vi.fn() },+ storage: {},+ });+ const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});+const host = createWorkerCacheHost({ scope: 'scope-1' });- const variantRequest = {- query:- 'query Views($input: GroupedSoupInput!) { user { groupSoup(input: $input) { bins { key } } } }',- operationName: 'Views',- path: [{ field: 'user' }, { field: 'groupSoup' }],- };- const request = {- ...variantRequest,- variableFilters: [- { input: { initial: { groupBy: { field: 'PROPERTY' } } } },- ],- };- await expect(host.inspectQueryVariants(variantRequest)).resolves.toEqual(- variants+ expect(host.disabled).toBe(true);+ expect(warn).toHaveBeenCalledWith(+ '[graphql-cache] disabled: OPFS is not supported by this browser');- expect(requests).toContainEqual(- expect.objectContaining({- kind: 'inspect-query-variants',- ...variantRequest,- })+ expect(adapterFactory).not.toHaveBeenCalled();+ });++ it('does not false-gate worker-only sync access handle capability', async () => {+ vi.stubGlobal('FileSystemFileHandle', undefined);+ vi.stubGlobal('FileSystemSyncAccessHandle', undefined);+ configureAdapter = (fake) => {+ fake.errors.set('init', 'sync access handles unavailable in engine');+ };+ const onInitializationError = vi.fn();+ const host = createWorkerCacheHost({+ scope: 'scope-1',+ onInitializationError,+ });++ expect(host.disabled).not.toBe(true);+ await expect(host.clear()).rejects.toThrow(+ 'sync access handles unavailable in engine');+ expect(adapterFactory).toHaveBeenCalledOnce();+ expect(onInitializationError).toHaveBeenCalledOnce();+ });++ it('samples origin storage pressure periodically and clears the timer on dispose', async () => {+ vi.useFakeTimers({ toFake: ['setInterval', 'clearInterval'] });+ const estimate = vi.fn(async () => ({ usage: 25, quota: 100 }));+ vi.stubGlobal('navigator', {+ ...(navigator as unknown as Record<string, unknown>),+ storage: {+ getDirectory: vi.fn(),+ estimate,+ persisted: vi.fn(async () => true),+ },+ });+ const observations: Array<Record<string, unknown>> = [];+ const host = createWorkerCacheHost({+ scope: 'scope-1',+ storageHealthIntervalMs: 1_000,+ telemetry: {+ record: (observation) => observations.push(observation),+ flush: vi.fn(),+ },+ });++ await host.readQuery({ query: 'query Ready { value }' });+ await Promise.resolve();+ expect(estimate).toHaveBeenCalledOnce();+ await vi.advanceTimersByTimeAsync(2_000);+ expect(estimate).toHaveBeenCalledTimes(3);++ host.dispose();+ await vi.advanceTimersByTimeAsync(2_000);+ expect(estimate).toHaveBeenCalledTimes(3);expect(- requests.find(- (candidate) =>- (candidate as { kind?: string }).kind === 'inspect-query-variants'+ observations.filter(+ (observation) =>+ observation.name === 'graphql_cache.origin_storage_pressure')- ).not.toHaveProperty('variableFilters');- await expect(host.inspectQuery(request)).resolves.toEqual(instances);- expect(requests).toContainEqual(- expect.objectContaining({ kind: 'inspect-query', ...request })+ ).toHaveLength(3);+ });++ it('constructs the coordinator adapter and starts cutover cleanup lazily on first RPC', async () => {+ const host = createWorkerCacheHost({ scope: 'lazy-scope' });+ host.onOpsAffected(() => undefined);++ expect(adapterFactory).not.toHaveBeenCalled();+ expect(sharedWorkerConstructor).not.toHaveBeenCalled();+ expect(dedicatedWorkerConstructor).not.toHaveBeenCalled();+ expect(indexedDbDelete).not.toHaveBeenCalled();++ const read = host.readQuery({ query: '{ x }' });+ expect(adapterFactory).toHaveBeenCalledOnce();+ expect(indexedDbDelete).toHaveBeenCalledOnce();+ expect(indexedDbDelete).toHaveBeenCalledWith('graphql-cache:lazy-scope');+ expect(adapterFactory).toHaveBeenCalledWith(+ expect.objectContaining({ scope: 'lazy-scope' }));+ await expect(read).resolves.toEqual({ kind: 'miss' });+ await host.clear();+ expect(requireAdapter().requests.map((request) => request.kind)).toEqual([+ 'init',+ 'read',+ 'clear',+ ]);+ expect(indexedDbDelete).toHaveBeenCalledOnce();host.dispose();});- it('forwards user-visible read priority to the worker', async () => {- const requests: Array<{ id?: number; kind: string; priority?: string }> =- [];- class FakeSharedWorker {- port = {- onmessage: null as ((event: MessageEvent) => void) | null,- start() {},- close() {},- postMessage: (request: {- id?: number;- kind: string;- priority?: string;- }) => {- requests.push(request);- if (request.id === undefined) return;- queueMicrotask(() => {- this.port.onmessage?.({- data: {- id: request.id,- ok: true,- result:- request.kind === 'read'- ? { kind: 'hit', data: { soup: true } }- : null,- },- } as MessageEvent);- });- },- };- }- vi.stubGlobal('SharedWorker', FakeSharedWorker);- const host = createWorkerCacheHost({ scope: 'scope-1' });- const entityResolvers = [- {- parentType: 'GraphqlUser',- fieldName: 'emailThread',- targetType: 'GraphqlSoupEmailThread',- argumentPath: ['input', 'threadId'],- },- ];+ it('preserves the complete CacheHost RPC surface, request ids, and call order', async () => {+ const host = createWorkerCacheHost({ scope: 'scope-1', hotCapacity: 42 });+ const claim = { owner: 'runner', generation: 'generation-1' };- await expect(+ const results = await Promise.all([host.readQuery({opKey: 7,- query: 'query GroupSoup { groupSoup }',+ query: 'query Read { user { id } }',priority: 'user-visible',- entityResolvers,- })- ).resolves.toEqual({ kind: 'hit', data: { soup: true } });- expect(requests).toContainEqual(+ entityResolvers: [+ {+ parentType: 'GraphqlUser',+ fieldName: 'emailThread',+ targetType: 'GraphqlSoupEmailThread',+ argumentPath: ['input', 'threadId'],+ },+ ],+ }),+ host.readRecords({+ document: 'fragment Item on GraphqlSoupItem { id }',+ fragmentName: 'Item',+ cursor: 'cursor-1',+ limit: 20,+ }),+ host.writeQuery({+ opKey: 8,+ query: 'query Read { user { id } }',+ data: { user: { id: 'user-1' } },+ identity: 'user-1',+ }),+ host.enqueueOptimisticMutation(+ {+ opKey: 9,+ query: 'mutation Rename { rename { id } }',+ data: { rename: { id: 'doc-1' } },+ },+ { owner: 'runner', nowMs: 100, leaseExpiresAtMs: 1_100 }+ ),+ host.inspectQueryVariants({+ query: 'query Views { views }',+ path: [{ field: 'views' }],+ }),+ host.inspectQuery({+ query: 'query Views { views }',+ path: [{ field: 'views' }],+ variableFilters: [{ input: { limit: 20 } }],+ }),+ host.claimNextMutation('runner', 200, 1_200),+ host.deferOptimisticWrite('1', claim, 2_000, 'offline'),+ host.commitOptimisticWrite('1', claim, {+ query: 'mutation Rename { rename { id } }',+ data: { rename: { id: 'doc-1' } },+ }),+ host.rollbackOptimisticWrite('2', claim, 'denied'),+ host.invalidate(['User:1']),+ host.deleteRecords(['Document:1']),+ host.teardown(7),+ host.clear(),+ ]);++ const requests = requireAdapter().requests;+ expect(requests.map(({ id, kind }) => [id, kind])).toEqual([+ [1, 'init'],+ [2, 'read'],+ [3, 'read-records'],+ [4, 'write'],+ [5, 'enqueue-optimistic-mutation'],+ [6, 'inspect-query-variants'],+ [7, 'inspect-query'],+ [8, 'claim-next-mutation'],+ [9, 'defer-optimistic-write'],+ [10, 'commit-optimistic-write'],+ [11, 'rollback-optimistic-write'],+ [12, 'invalidate'],+ [13, 'delete-records'],+ [14, 'teardown'],+ [15, 'clear'],+ ]);+ expect(requests[0]).toEqual({+ id: 1,+ kind: 'init',+ scope: 'scope-1',+ hotCapacity: 42,+ });+ expect(requests[1]).toEqual(expect.objectContaining({- kind: 'read',+ opId: `${CLIENT_ID}:7`,priority: 'user-visible',- entityResolvers,+ entityResolvers: [+ expect.objectContaining({+ parentType: 'GraphqlUser',+ fieldName: 'emailThread',+ }),+ ],}));+ expect(requests[3]).toEqual(+ expect.objectContaining({ originOpId: `${CLIENT_ID}:8` })+ );+ expect(requests[4]).toEqual(+ expect.objectContaining({+ originOpId: `${CLIENT_ID}:9`,+ owner: 'runner',+ createdAtMs: 100,+ nowMs: 100,+ leaseExpiresAtMs: 1_100,+ })+ );+ expect(requests[13]).toEqual({+ id: 14,+ kind: 'teardown',+ opId: `${CLIENT_ID}:7`,+ });+ expect(results[0]).toEqual({ kind: 'miss' });+ expect(results[3]).toEqual(expect.objectContaining({ transactionId: '1' }));host.dispose();});- it('delivers queued mutation settlements pushed by the worker', async () => {- let push: (message: unknown) => void = () => {- throw new Error('worker not initialized');- };- class FakeSharedWorker {- port = {- onmessage: null as ((event: MessageEvent) => void) | null,- start() {},- close() {},- postMessage: (request: { id?: number }) => {- if (request.id === undefined) return;- queueMicrotask(() => {- this.port.onmessage?.({- data: { id: request.id, ok: true, result: null },- } as MessageEvent);- });- },- };+ it('bounds hung registration/init before admitting reads or mutations', async () => {+ vi.useFakeTimers();+ configureAdapter = (fake) => fake.ignoredKinds.add('init');+ const onInitializationError = vi.fn();+ const host = createWorkerCacheHost({+ scope: 'scope-1',+ requestTimeoutMs: 100,+ initializationTimeoutMs: 10,+ onInitializationError,+ });- constructor() {- push = (message) =>- this.port.onmessage?.({ data: message } as MessageEvent);- }- }- vi.stubGlobal('SharedWorker', FakeSharedWorker);+ const read = host.readQuery({ opKey: 4, query: 'query Read { user }' });+ const mutation = host.enqueueOptimisticMutation(+ { query: 'mutation Update { update }', data: { update: true } },+ { owner: 'runner', nowMs: 1, leaseExpiresAtMs: 101 }+ );+ const readRejected = expect(read).rejects.toThrow(+ 'cache worker timeout: init'+ );+ const mutationRejected = expect(mutation).rejects.toThrow(+ 'cache worker timeout: init'+ );++ await vi.advanceTimersByTimeAsync(11);+ await Promise.all([readRejected, mutationRejected]);++ const adapter = requireAdapter();+ expect(adapter.requests.map(({ id, kind }) => [id, kind])).toEqual([+ [1, 'init'],+ ]);+ expect(adapter.dispose).toHaveBeenCalledWith({ graceful: false });+ expect(onInitializationError).toHaveBeenCalledOnce();+ expect(vi.getTimerCount()).toBe(0);+ });++ it('recovers typed initial epoch loss with fresh init handshakes only', async () => {+ configureAdapter = (fake) => fake.ignoredKinds.add('init');+ const onInitializationError = vi.fn();+ const host = createWorkerCacheHost({+ scope: 'scope-1',+ onInitializationError,+ });+ const affected: number[][] = [];+ host.onOpsAffected((keys) => affected.push(keys));++ const read = host.readQuery({ opKey: 44, query: 'query Read { user }' });+ const mutation = host.enqueueOptimisticMutation(+ { query: 'mutation Update { update }', data: { update: true } },+ { owner: 'runner', nowMs: 1, leaseExpiresAtMs: 101 }+ );+ const readRejected = expect(read).rejects.toMatchObject({+ message: 'owner epoch 1 was lost',+ errorCode: 'owner-epoch-lost',+ });+ const mutationRejected = expect(mutation).rejects.toMatchObject({+ message: 'owner epoch 1 was lost',+ errorCode: 'owner-epoch-lost',+ });+ const adapter = requireAdapter();+ adapter.reject(1, 'owner epoch 1 was lost', 'owner-epoch-lost');+ await Promise.all([readRejected, mutationRejected]);++ adapter.replace(2);+ expect(adapter.requests.map(({ id, kind }) => [id, kind])).toEqual([+ [1, 'init'],+ [2, 'init'],+ ]);+ expect(affected).toEqual([]);+ adapter.reject(2, 'owner epoch 2 was lost', 'owner-epoch-lost');+ await Promise.resolve();++ adapter.replace(3);+ expect(adapter.requests.map(({ id, kind }) => [id, kind])).toEqual([+ [1, 'init'],+ [2, 'init'],+ [3, 'init'],+ ]);+ expect(affected).toEqual([]);+ adapter.respond(3, null);+ await vi.waitFor(() =>+ expect(+ adapter.requests.filter(({ kind }) => kind === 'init')+ ).toHaveLength(3)+ );+ expect(affected).toEqual([]);++ expect(+ adapter.requests.filter(+ (request) =>+ request.kind === 'read' ||+ request.kind === 'enqueue-optimistic-mutation'+ )+ ).toEqual([]);+ expect(onInitializationError).not.toHaveBeenCalled();+ host.dispose();+ });++ it('suppresses replacement notification while an original init is queued', async () => {+ configureAdapter = (fake) => fake.ignoredKinds.add('init');const host = createWorkerCacheHost({ scope: 'scope-1' });- const seen: unknown[] = [];- host.onMutationSettled((settlement) => seen.push(settlement));- const settlement = {- transactionId: '12',- status: 'committed' as const,- };+ const affected: number[][] = [];+ host.onOpsAffected((keys) => affected.push(keys));- push({ kind: 'mutation-settled', settlement });+ const read = host.readQuery({ opKey: 5, query: 'query Read { user }' });+ const adapter = requireAdapter();+ adapter.replace(2);+ adapter.respond(1, null);+ await expect(read).resolves.toEqual({ kind: 'miss' });- expect(seen).toEqual([settlement]);+ expect(affected).toEqual([]);+ expect(adapter.requests.map(({ id, kind }) => [id, kind])).toEqual([+ [1, 'init'],+ [2, 'read'],+ ]);host.dispose();});- it('times out reads without timing out durable mutations', async () => {+ it('times out read-only RPC without timing out or replaying mutations', async () => {vi.useFakeTimers();- const requests: Array<{ id?: number; kind: string }> = [];- let respond: (id: number, result: unknown) => void = () => {- throw new Error('worker not initialized');+ configureAdapter = (fake) => {+ fake.ignoredKinds.add('read');+ fake.ignoredKinds.add('enqueue-optimistic-mutation');};- class FakeSharedWorker {- port = {- onmessage: null as ((event: MessageEvent) => void) | null,- start() {},- close() {},- postMessage: (request: { id?: number; kind: string }) => {- requests.push(request);- if (request.id === undefined) return;- if (request.kind === 'init') {- queueMicrotask(() =>- this.port.onmessage?.({- data: { id: request.id, ok: true, result: null },- } as MessageEvent)- );- }- },- };-- constructor() {- respond = (id, result) =>- this.port.onmessage?.({- data: { id, ok: true, result },- } as MessageEvent);- }- }- vi.stubGlobal('SharedWorker', FakeSharedWorker);const host = createWorkerCacheHost({scope: 'scope-1',requestTimeoutMs: 10,});- const readResult = expect(- host.readQuery({ query: 'query Read { user { id } }' })- ).rejects.toThrow('cache worker timeout: read');- const mutationResult = host.enqueueOptimisticMutation(+ const read = host.readQuery({ query: 'query Read { user { id } }' });+ const mutation = host.enqueueOptimisticMutation({query: 'mutation Rename { rename { id } }',data: { rename: { id: 'doc-1' } },},- {- owner: 'runner-1',- nowMs: 123,- leaseExpiresAtMs: 1_123,- }+ { owner: 'runner', nowMs: 123, leaseExpiresAtMs: 1_123 }+ );+ const readResult = expect(read).rejects.toThrow(+ 'cache worker timeout: read');let mutationSettled = false;- void mutationResult.then(+ void mutation.then(() => {mutationSettled = true;},@@ -267,50 +566,647 @@ describe('createWorkerCacheHost', () => {await vi.advanceTimersByTimeAsync(11);await readResult;expect(mutationSettled).toBe(false);+ const adapter = requireAdapter();expect(- requests.filter(+ adapter.requests.filter((request) => request.kind === 'enqueue-optimistic-mutation')).toHaveLength(1);- const mutationRequest = requests.find(+ const mutationRequest = adapter.requests.find((request) => request.kind === 'enqueue-optimistic-mutation');- expect(mutationRequest).toEqual(- expect.objectContaining({- owner: 'runner-1',- nowMs: 123,- createdAtMs: 123,- leaseExpiresAtMs: 1_123,- })- );- expect(mutationRequest?.id).toBeTypeOf('number');- const result = {+ adapter.respond(mutationRequest?.id as number, {+ ...EMPTY_WRITE,transactionId: '1',- changed: [],- affectedOps: [],- reset: false,- initialClaim: { kind: 'not-runnable' as const },+ initialClaim: { kind: 'not-runnable' },+ });+ await expect(mutation).resolves.toEqual(+ expect.objectContaining({ transactionId: '1' })+ );+ expect(+ adapter.requests.filter(+ (request) => request.kind === 'enqueue-optimistic-mutation'+ )+ ).toHaveLength(1);+ host.dispose();+ });++ it('rejects old-epoch requests and never replays reads or durable mutations', async () => {+ configureAdapter = (fake) => {+ fake.ignoredKinds.add('read');+ fake.ignoredKinds.add('enqueue-optimistic-mutation');};- respond(mutationRequest?.id as number, result);- await expect(mutationResult).resolves.toEqual(result);+ const host = createWorkerCacheHost({ scope: 'scope-1' });+ const affected: number[][] = [];+ host.onOpsAffected((keys) => affected.push(keys));+ await host.clear();++ const read = host.readQuery({ opKey: 44, query: 'query Read { user }' });+ const mutation = host.enqueueOptimisticMutation(+ { query: 'mutation Update { update }', data: { update: true } },+ { owner: 'runner', nowMs: 1, leaseExpiresAtMs: 101 }+ );+ const readRejected = expect(read).rejects.toThrow('owner epoch 1 was lost');+ const mutationRejected = expect(mutation).rejects.toThrow(+ 'owner epoch 1 was lost'+ );+ const adapter = requireAdapter();+ await vi.waitFor(() =>+ expect(+ adapter.requests.filter(+ (request) =>+ request.kind === 'read' ||+ request.kind === 'enqueue-optimistic-mutation'+ )+ ).toHaveLength(2)+ );+ const oldEpochRequests = adapter.requests.filter(+ (request) =>+ request.kind === 'read' ||+ request.kind === 'enqueue-optimistic-mutation'+ );+ for (const request of oldEpochRequests) {+ adapter.reject(request.id, 'owner epoch 1 was lost', 'owner-epoch-lost');+ }+ await Promise.all([readRejected, mutationRejected]);++ adapter.replace(2);+ await vi.waitFor(() =>+ expect(+ adapter.requests.filter(({ kind }) => kind === 'init')+ ).toHaveLength(2)+ );+ expect(affected).toEqual([]);++ expect(+ adapter.requests.filter((request) => request.kind === 'init')+ ).toHaveLength(2);+ expect(+ adapter.requests.filter(+ (request) =>+ request.kind === 'read' ||+ request.kind === 'enqueue-optimistic-mutation'+ )+ ).toEqual(oldEpochRequests);host.dispose();});- it('falls back to no-op when SharedWorker initialization throws', () => {- vi.stubGlobal(- 'SharedWorker',- vi.fn(function () {- throw new Error('blocked');- })+ it('notifies a successfully registered key whose old-epoch reread was rejected', async () => {+ const host = createWorkerCacheHost({ scope: 'scope-1' });+ const affected: number[][] = [];+ host.onOpsAffected((keys) => affected.push(keys));+ await host.clear();+ await Promise.all([+ host.readQuery({ opKey: 7, query: 'query Seven { seven }' }),+ host.readQuery({ opKey: 9, query: 'query Nine { nine }' }),+ ]);+ const adapter = requireAdapter();+ adapter.ignoredKinds.add('read');++ const reread = host.readQuery({+ opKey: 7,+ query: 'query SlowSeven { seven }',+ });+ await vi.waitFor(() =>+ expect(+ adapter.requests.filter(+ (request) =>+ request.kind === 'read' && request.query.includes('SlowSeven')+ )+ ).toHaveLength(1));- const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});+ const request = adapter.requests.find(+ (candidate) =>+ candidate.kind === 'read' && candidate.query.includes('SlowSeven')+ );+ adapter.reject(+ request?.id as number,+ 'owner epoch 1 was lost',+ 'owner-epoch-lost'+ );+ await expect(reread).rejects.toMatchObject({+ errorCode: 'owner-epoch-lost',+ });+ adapter.replace(2);+ await vi.waitFor(() => expect(affected).toEqual([[7, 9]]));+ expect(+ adapter.requests.filter(+ (candidate) =>+ candidate.kind === 'read' && candidate.query.includes('SlowSeven')+ )+ ).toHaveLength(1);+ host.dispose();+ });++ it('notifies only registered active operations and deduplicates replacement epochs', async () => {const host = createWorkerCacheHost({ scope: 'scope-1' });+ const affected: number[][] = [];+ const unsubscribe = host.onOpsAffected((keys) => affected.push(keys));+ await host.clear();- expect(host.disabled).toBe(true);- expect(warn).toHaveBeenCalledWith(- '[graphql-cache] disabled: SharedWorker could not be initialized'+ await Promise.all([+ host.readQuery({ opKey: 7, query: 'query Seven { seven }' }),+ host.readQuery({ opKey: 9, query: 'query Nine { nine }' }),+ host.readQuery({ query: 'query Untracked { untracked }' }),+ ]);+ const adapter = requireAdapter();+ adapter.replace(2);+ await vi.waitFor(() => expect(affected).toEqual([[7, 9]]));++ await host.teardown(7);+ await host.readQuery({ opKey: 9, query: 'query NineAgain { nine }' });+ adapter.replace(2);+ adapter.replace(1);+ adapter.replace(3);+ adapter.replace(3);+ await vi.waitFor(() => expect(affected).toEqual([[7, 9], [9]]));++ await Promise.all([+ host.readQuery({ opKey: 9, query: 'query NineThird { nine }' }),+ host.readQuery({ opKey: 7, query: 'query SevenAgain { seven }' }),+ ]);+ adapter.replace(4);+ await vi.waitFor(() => expect(affected).toEqual([[7, 9], [9], [9, 7]]));+ unsubscribe();++ expect(affected).toEqual([[7, 9], [9], [9, 7]]);+ host.dispose();+ });++ it('strictly filters pushes to the exact client operation prefix', async () => {+ const host = createWorkerCacheHost({ scope: 'scope-1' });+ const affected: number[][] = [];+ const cacheChanges = vi.fn();+ const settlements: unknown[] = [];+ host.onOpsAffected((keys) => affected.push(keys));+ host.onCacheChanged(cacheChanges);+ host.onMutationSettled((settlement) => settlements.push(settlement));+ await host.clear();++ const adapter = requireAdapter();+ adapter.push({+ kind: 'ops-affected',+ opIds: [+ `${CLIENT_ID}:7`,+ `${CLIENT_ID}:7`,+ `foreign:${CLIENT_ID}:8`,+ `${CLIENT_ID}0:9`,+ `${CLIENT_ID}:1e3`,+ `${CLIENT_ID}:0x10`,+ `${CLIENT_ID}:NaN`,+ `${CLIENT_ID}:9007199254740992`,+ `${CLIENT_ID}:007`,+ `${CLIENT_ID}:-0`,+ `${CLIENT_ID}:not-a-number`,+ `${CLIENT_ID}:`,+ `${CLIENT_ID}:12`,+ ],+ keys: ['User:1'],+ });+ adapter.push({ kind: 'ops-affected', opIds: [7], keys: [] });+ adapter.push({ kind: 'cache-changed' });+ adapter.push({+ kind: 'mutation-settled',+ settlement: { transactionId: '3', status: 'committed' },+ });++ expect(affected).toEqual([[7, 12]]);+ expect(cacheChanges).toHaveBeenCalledOnce();+ expect(settlements).toEqual([{ transactionId: '3', status: 'committed' }]);+ host.dispose();+ });++ it('reports initialization failure once, settles callers, and closes transport', async () => {+ vi.useFakeTimers();+ configureAdapter = (fake) => {+ fake.errors.set('init', 'OPFS initialization failed');+ };+ const onInitializationError = vi.fn();+ const host = createWorkerCacheHost({+ scope: 'scope-1',+ requestTimeoutMs: 10,+ onInitializationError,+ });++ const read = host.readQuery({ query: 'query Read { user }' });+ const write = host.writeQuery({+ query: 'query Read { user }',+ data: { user: null },+ });+ const readRejected = expect(read).rejects.toThrow(+ 'OPFS initialization failed'+ );+ const writeRejected = expect(write).rejects.toThrow(+ 'OPFS initialization failed'+ );+ await vi.runAllTimersAsync();+ await Promise.all([readRejected, writeRejected]);++ const adapter = requireAdapter();+ adapter.protocolError(new Error('late coordinator error'));+ adapter.reject(1, 'late initialization response');++ expect(onInitializationError).toHaveBeenCalledOnce();+ expect(onInitializationError).toHaveBeenCalledWith(+ expect.objectContaining({ message: 'OPFS initialization failed' })+ );+ expect(adapter.dispose).toHaveBeenCalledOnce();+ expect(adapter.dispose).toHaveBeenCalledWith({ graceful: false });+ expect(vi.getTimerCount()).toBe(0);+ host.dispose();+ expect(adapter.dispose).toHaveBeenCalledOnce();+ });++ it('terminal transport failure quarantines scope and rejects admitted mutations once', async () => {+ configureAdapter = (fake) => {+ fake.ignoredKinds.add('enqueue-optimistic-mutation');+ };+ localStorage.setItem('graphql-cache:scope', 'scope-1');+ const onInitializationError = vi.fn();+ const host = createWorkerCacheHost({+ scope: 'scope-1',+ onInitializationError,+ });+ const affected = vi.fn();+ host.onOpsAffected(affected);+ await host.clear();+ const adapter = requireAdapter();+ const mutation = host.enqueueOptimisticMutation(+ { query: 'mutation Update { update }', data: { update: true } },+ { owner: 'runner', nowMs: 1, leaseExpiresAtMs: 101 }+ );+ const mutationRejected = expect(mutation).rejects.toMatchObject({+ message: expect.stringContaining('coordinator MessagePort messageerror'),+ errorCode: 'admitted-enqueue-uncertain',+ });+ await vi.waitFor(() =>+ expect(+ adapter.requests.filter(+ (request) => request.kind === 'enqueue-optimistic-mutation'+ )+ ).toHaveLength(1)+ );++ adapter.terminalError(new Error('coordinator MessagePort messageerror'));+ await mutationRejected;+ adapter.terminalError(new Error('duplicate terminal callback'));+ adapter.replace(2);++ expect(onInitializationError).toHaveBeenCalledOnce();+ expect(adapter.dispose).toHaveBeenCalledOnce();+ expect(adapter.dispose).toHaveBeenCalledWith({ graceful: false });+ expect(localStorage.getItem('graphql-cache:scope')).toBe(+ 'quarantine:scope-1'+ );+ expect(affected).not.toHaveBeenCalled();+ expect(+ adapter.requests.filter(+ (request) => request.kind === 'enqueue-optimistic-mutation'+ )+ ).toHaveLength(1);+ await expect(host.clear()).rejects.toThrow(+ 'coordinator MessagePort messageerror'+ );+ });++ it('quarantines transport scope before invoking the product failure callback', async () => {+ let runLock!: () => Promise<void>;+ vi.stubGlobal('navigator', {+ locks: {+ request: vi.fn(+ <T>(+ _name: string,+ _options: LockOptions,+ callback: (lock: Lock | null) => T | PromiseLike<T>+ ) =>+ new Promise<T>((resolve, reject) => {+ runLock = async () => {+ try {+ resolve(+ await callback({+ name: 'graphql-cache:scope-storage',+ mode: 'exclusive',+ } as Lock)+ );+ } catch (error) {+ reject(error);+ }+ };+ })+ ),+ },+ storage: { getDirectory: vi.fn() },+ });+ localStorage.setItem('graphql-cache:scope', 'scope-1');+ const callbackScopes: Array<string | null> = [];+ const host = createWorkerCacheHost({+ scope: 'scope-1',+ onInitializationError: () => {+ callbackScopes.push(localStorage.getItem('graphql-cache:scope'));+ },+ });+ await host.clear();++ requireAdapter().terminalError(new Error('transport failed'));+ expect(callbackScopes).toEqual([]);+ expect(localStorage.getItem('graphql-cache:scope')).toBe('scope-1');+ await runLock();+ await vi.waitFor(() =>+ expect(callbackScopes).toEqual(['quarantine:scope-1'])+ );+ });++ it('converges same-scope failures and ignores stale or disposed host quarantine', async () => {+ const adapters: FakePageAdapter[] = [];+ adapterFactory.mockImplementation(+ (adapterOptions: CacheCoordinatorPageAdapterOptions) => {+ const fake = new FakePageAdapter(adapterOptions);+ adapters.push(fake);+ return fake as unknown as CacheCoordinatorPageAdapter;+ }+ );+ localStorage.setItem('graphql-cache:scope', 'shared-old');+ const firstError = vi.fn();+ const secondError = vi.fn();+ const first = createWorkerCacheHost({+ scope: 'shared-old',+ onInitializationError: firstError,+ });+ const second = createWorkerCacheHost({+ scope: 'shared-old',+ onInitializationError: secondError,+ });+ await Promise.all([first.clear(), second.clear()]);++ adapters[0]?.terminalError(new Error('first tab transport failed'));+ expect(localStorage.getItem('graphql-cache:scope')).toBe(+ 'quarantine:shared-old'+ );+ adapters[1]?.terminalError(new Error('second tab transport failed'));+ expect(localStorage.getItem('graphql-cache:scope')).toBe(+ 'quarantine:shared-old'+ );+ await vi.waitFor(() => {+ expect(firstError).toHaveBeenCalledOnce();+ expect(secondError).toHaveBeenCalledOnce();+ });++ const staleError = vi.fn();+ const stale = createWorkerCacheHost({+ scope: 'shared-old',+ onInitializationError: staleError,+ });+ await stale.clear();+ localStorage.setItem('graphql-cache:scope', 'new-healthy-scope');+ adapters[2]?.terminalError(new Error('late stale transport failed'));+ expect(localStorage.getItem('graphql-cache:scope')).toBe(+ 'new-healthy-scope'+ );++ const disposedError = vi.fn();+ const disposed = createWorkerCacheHost({+ scope: 'shared-old',+ onInitializationError: disposedError,+ });+ await disposed.clear();+ disposed.dispose();+ adapters[3]?.terminalError(new Error('late disposed callback'));+ expect(localStorage.getItem('graphql-cache:scope')).toBe(+ 'new-healthy-scope'+ );+ expect(disposedError).not.toHaveBeenCalled();+ });++ it('reports a lazy adapter-construction failure without leaking a transport', async () => {+ adapterFactory.mockImplementationOnce(() => {+ throw new Error('SharedWorker construction failed');+ });+ const onInitializationError = vi.fn();+ const host = createWorkerCacheHost({+ scope: 'scope-1',+ onInitializationError,+ });++ expect(adapterFactory).not.toHaveBeenCalled();+ await expect(host.clear()).rejects.toThrow(+ 'SharedWorker construction failed'+ );++ expect(adapterFactory).toHaveBeenCalledOnce();+ expect(onInitializationError).toHaveBeenCalledOnce();+ expect(lastAdapter).toBeUndefined();+ host.dispose();+ });++ it('disposes explicitly with graceful idempotence and drains pending mutation responses', async () => {+ configureAdapter = (fake) => {+ fake.ignoredKinds.add('enqueue-optimistic-mutation');+ };+ const host = createWorkerCacheHost({ scope: 'scope-1' });+ await host.clear();+ const adapter = requireAdapter();+ let finishDrain: (() => void) | undefined;+ const draining = new Promise<void>((resolve) => {+ finishDrain = resolve;+ });+ adapter.dispose.mockImplementationOnce(async () => await draining);+ const mutation = host.enqueueOptimisticMutation(+ { query: 'mutation Update { update }', data: { update: true } },+ { owner: 'runner', nowMs: 1, leaseExpiresAtMs: 101 }+ );+ await vi.waitFor(() =>+ expect(+ adapter.requests.filter(+ (request) => request.kind === 'enqueue-optimistic-mutation'+ )+ ).toHaveLength(1)+ );+ const mutationRequest = adapter.requests.find(+ (request) => request.kind === 'enqueue-optimistic-mutation'+ );++ host.dispose();+ host.dispose();+ expect(adapter.dispose).not.toHaveBeenCalled();+ adapter.respond(mutationRequest?.id as number, {+ ...EMPTY_WRITE,+ transactionId: '4',+ initialClaim: { kind: 'not-runnable' },+ });++ await expect(mutation).resolves.toEqual(+ expect.objectContaining({ transactionId: '4' })+ );+ finishDrain?.();+ await draining;+ expect(adapter.dispose).toHaveBeenCalledOnce();+ expect(adapter.dispose).toHaveBeenCalledWith({ graceful: true });+ await expect(host.clear()).rejects.toThrow(+ 'cache worker host was disposed'+ );+ });++ it('keeps pagehide armed until graceful adapter retirement resolves', async () => {+ const host = createWorkerCacheHost({ scope: 'scope-1' });+ await host.clear();+ const adapter = requireAdapter();+ let finishRetirement!: () => void;+ const retirement = new Promise<void>((resolve) => {+ finishRetirement = resolve;+ });+ adapter.dispose.mockImplementationOnce(async () => await retirement);++ host.dispose();+ expect(adapter.dispose).toHaveBeenCalledWith({ graceful: true });+ dispatchEvent(new Event('pagehide'));++ expect(adapter.dispose).toHaveBeenNthCalledWith(2, { graceful: false });+ finishRetirement();+ await retirement;+ await expect(host.clear()).rejects.toThrow(+ 'cache worker host was disposed'+ );+ });++ it('quarantines and reports transport failure during adapter retirement', async () => {+ localStorage.setItem('graphql-cache:scope', 'scope-1');+ const onInitializationError = vi.fn();+ const host = createWorkerCacheHost({+ scope: 'scope-1',+ onInitializationError,+ });+ await host.clear();+ const adapter = requireAdapter();+ let finishRetirement!: () => void;+ const retirement = new Promise<void>((resolve) => {+ finishRetirement = resolve;+ });+ adapter.dispose.mockImplementationOnce(async () => await retirement);++ host.dispose();+ adapter.terminalError(new Error('SharedWorker failed during retirement'));++ expect(adapter.dispose).toHaveBeenNthCalledWith(2, { graceful: false });+ await vi.waitFor(() => {+ expect(localStorage.getItem('graphql-cache:scope')).toBe(+ 'quarantine:scope-1'+ );+ expect(onInitializationError).toHaveBeenCalledOnce();+ });+ finishRetirement();+ await retirement;+ });++ it('waits for existing read timeout before gracefully disconnecting a requester', async () => {+ vi.useFakeTimers();+ configureAdapter = (fake) => fake.ignoredKinds.add('read');+ const host = createWorkerCacheHost({+ scope: 'scope-1',+ requestTimeoutMs: 10,+ });+ await host.clear();+ const adapter = requireAdapter();+ const read = host.readQuery({ query: 'query Slow { slow }' });+ const readOutcome = read.then(+ () => undefined,+ (error: unknown) => error+ );+ await Promise.resolve();+ expect(adapter.requests.filter(({ kind }) => kind === 'read')).toHaveLength(+ 1+ );++ host.dispose();+ expect(adapter.dispose).not.toHaveBeenCalled();+ await vi.advanceTimersByTimeAsync(11);+ await expect(readOutcome).resolves.toMatchObject({+ message: 'cache worker timeout: read',+ });++ expect(adapter.dispose).toHaveBeenCalledOnce();+ expect(adapter.dispose).toHaveBeenCalledWith({ graceful: true });+ });++ it('preserves transport uncertainty when graceful disposal is already draining admitted work', async () => {+ configureAdapter = (fake) => {+ fake.ignoredKinds.add('enqueue-optimistic-mutation');+ };+ localStorage.setItem('graphql-cache:scope', 'scope-1');+ const onInitializationError = vi.fn();+ const host = createWorkerCacheHost({+ scope: 'scope-1',+ onInitializationError,+ });+ await host.clear();+ const adapter = requireAdapter();+ let finishDrain!: () => void;+ const draining = new Promise<void>((resolve) => {+ finishDrain = resolve;+ });+ adapter.dispose.mockImplementationOnce(async () => await draining);+ const mutation = host.enqueueOptimisticMutation(+ { query: 'mutation Update { update }', data: { update: true } },+ { owner: 'runner', nowMs: 1, leaseExpiresAtMs: 101 }+ );+ await vi.waitFor(() =>+ expect(+ adapter.requests.filter(+ ({ kind }) => kind === 'enqueue-optimistic-mutation'+ )+ ).toHaveLength(1)+ );++ host.dispose();+ adapter.terminalError(new Error('transport failed during drain'));+ await expect(mutation).rejects.toMatchObject({+ errorCode: 'admitted-enqueue-uncertain',+ });++ expect(localStorage.getItem('graphql-cache:scope')).toBe(+ 'quarantine:scope-1'+ );+ expect(onInitializationError).toHaveBeenCalledOnce();+ finishDrain();+ await draining;+ });++ it('treats pagehide as uncertain for an admitted enqueue and quarantines its scope', async () => {+ configureAdapter = (fake) => {+ fake.ignoredKinds.add('enqueue-optimistic-mutation');+ };+ localStorage.setItem('graphql-cache:scope', 'scope-1');+ const host = createWorkerCacheHost({ scope: 'scope-1' });+ await host.clear();+ const adapter = requireAdapter();+ const mutation = host.enqueueOptimisticMutation(+ { query: 'mutation Update { update }', data: { update: true } },+ { owner: 'runner', nowMs: 1, leaseExpiresAtMs: 101 }+ );+ const rejected = expect(mutation).rejects.toMatchObject({+ message: expect.stringContaining('abruptly disposed'),+ errorCode: 'admitted-enqueue-uncertain',+ });+ await vi.waitFor(() =>+ expect(+ adapter.requests.filter(+ ({ kind }) => kind === 'enqueue-optimistic-mutation'+ )+ ).toHaveLength(1)+ );++ host.dispose();+ expect(adapter.dispose).not.toHaveBeenCalled();+ dispatchEvent(new Event('pagehide'));+ await rejected;++ expect(adapter.dispose).toHaveBeenCalledOnce();+ expect(adapter.dispose).toHaveBeenCalledWith({ graceful: false });+ await vi.waitFor(() =>+ expect(localStorage.getItem('graphql-cache:scope')).toBe(+ 'quarantine:scope-1'+ ));});});diff --git a/apps/web/src/lib/graphql-cache/host/worker-host.ts b/apps/web/src/lib/graphql-cache/host/worker-host.tsindex 70c23bead6..e7de02b2fe 100644--- a/apps/web/src/lib/graphql-cache/host/worker-host.ts+++ b/apps/web/src/lib/graphql-cache/host/worker-host.ts@@ -1,18 +1,23 @@/**- * Browser CacheHost: talks to the single cache engine in a SharedWorker.- * Platforms without SharedWorker support receive a storage-free no-op host.+ * Browser CacheHost: routes cache RPC through the SharedWorker coordinator to+ * the currently elected dedicated cache engine. Unsupported browsers receive+ * a storage-free no-op host.*/+import { deleteLegacyNormalizedCacheIdb } from '../legacy-idb-cleanup';import {+ ADMITTED_ENQUEUE_UNCERTAIN_ERROR_CODE,type CachedQueryInstanceWire,type CachedQueryVariantWire,- type CacheNotice,type CacheRequest,+ type CacheResponseErrorCode,type ClaimedMutation,type EnqueueOptimisticMutationResult,isCachePush,+ isCacheResponse,type MutationClaim,type MutationSettlement,+ OWNER_EPOCH_LOST_ERROR_CODE,type ReadRecordsArgs,type ReadResult,type SelectedRecordPageWire,@@ -20,6 +25,20 @@ import {type WorkerMessage,type WriteResult,} from '../protocol';+import { quarantineCacheScope } from '../scope';+import {+ type CacheRolloutCohort,+ type CacheTelemetryRecorderLike,+ type CacheTelemetrySink,+ classifyCacheError,+ isolateCacheTelemetry,+ operationCategoryForRequest,+} from '../telemetry';+import { createPageCacheTelemetry } from '../telemetry-relay';+import {+ type CacheCoordinatorPageAdapter,+ createCacheCoordinatorPageAdapter,+} from '../worker/coordinator-page-adapter';import { createNoopCacheHost } from './noop-host';import type {CacheHost,@@ -34,9 +53,22 @@ import type {type Pending = {resolve: (value: unknown) => void;reject: (error: Error) => void;+ kind: CacheRequest['kind'];+ opKey?: number;+ admitted: boolean;+ startedAt: number;timer?: ReturnType<typeof setTimeout>;};+type HostState =+ | 'idle'+ | 'initializing'+ | 'awaiting-replacement'+ | 'ready'+ | 'disposing'+ | 'failed'+ | 'disposed';+/** `Omit` that distributes over union members. */type DistributiveOmit<T, K extends PropertyKey> = T extends unknown? Omit<T, K>@@ -51,19 +83,105 @@ export interface WorkerHostOptions {* operation that may already have completed durably.*/requestTimeoutMs?: number;- /** Reports an asynchronous durable-storage initialization failure. */+ /**+ * Registration/initialization timeout in ms. Defaults to requestTimeoutMs,+ * so callers cannot hang before a read-only request timer can start.+ */+ initializationTimeoutMs?: number;+ /** Reports terminal initialization or coordinator-transport failure. */onInitializationError?: (error: Error) => void;+ /** Allowlisted rollout cohort attached to browser-cache telemetry. */+ rolloutCohort?: CacheRolloutCohort;+ /** Injectable recorder for deterministic tests or alternate exporters. */+ telemetry?: CacheTelemetryRecorderLike;+ /** Injectable final sink; defaults to anonymous OpenTelemetry spans. */+ telemetrySink?: CacheTelemetrySink;+ /** Test seams for bounded origin-storage-pressure sampling. */+ storageHealthIntervalMs?: number;+ setInterval?: typeof globalThis.setInterval;+ clearInterval?: typeof globalThis.clearInterval;}const DEFAULT_REQUEST_TIMEOUT_MS = 10_000;+const DEFAULT_STORAGE_HEALTH_INTERVAL_MS = 5 * 60_000;+const MIN_STORAGE_HEALTH_INTERVAL_MS = 1_000;+const MAX_STORAGE_HEALTH_INTERVAL_MS = 15 * 60_000;-export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {+function unsupportedBrowserReason(): string | undefined {if (typeof SharedWorker !== 'function') {- return createNoopCacheHost('SharedWorker is not supported by this browser');+ return 'SharedWorker is not supported by this browser';+ }+ if (typeof Worker !== 'function') {+ return 'DedicatedWorker is not supported by this browser';+ }+ if (typeof MessageChannel !== 'function') {+ return 'MessageChannel is not supported by this browser';+ }+ if (+ typeof navigator === 'undefined' ||+ !navigator.locks ||+ typeof navigator.locks.request !== 'function'+ ) {+ return 'Web Locks are not supported by this browser';+ }+ if (+ !navigator.storage ||+ typeof navigator.storage.getDirectory !== 'function'+ ) {+ return 'OPFS is not supported by this browser';+ }+ // Do not probe createSyncAccessHandle here: Chromium and Firefox expose it+ // only inside DedicatedWorker. Engine initialization reports that async+ // capability failure through the normal terminal-init path.+ return undefined;+}++const asError = (error: unknown): Error =>+ error instanceof Error ? error : new Error(String(error));++class CacheResponseError extends Error {+ constructor(+ message: string,+ readonly errorCode?: CacheResponseErrorCode+ ) {+ super(message);+ this.name = 'CacheResponseError';+ }+}++const isOwnerEpochLoss = (error: unknown): error is CacheResponseError =>+ error instanceof CacheResponseError &&+ error.errorCode === OWNER_EPOCH_LOST_ERROR_CODE;++export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {+ const pageTelemetry = options.telemetry+ ? undefined+ : createPageCacheTelemetry({+ rolloutCohort: options.rolloutCohort ?? 'unknown',+ sink: options.telemetrySink,+ });+ const telemetry = isolateCacheTelemetry(+ options.telemetry ?? pageTelemetry?.recorder+ );+ const now = (): number => globalThis.performance?.now() ?? Date.now();+ const unsupportedReason = unsupportedBrowserReason();+ if (unsupportedReason) {+ telemetry?.record({+ name: 'graphql_cache.host_ready',+ operationCategory: 'initialization',+ outcome: 'error',+ errorCode: 'unsupported',+ });+ telemetry?.flush();+ return createNoopCacheHost(unsupportedReason);}const clientId = crypto.randomUUID();const pending = new Map<number, Pending>();+ const activeOpKeys = new Set<number>();+ const registeredOpKeys = new Set<number>();+ const lostRegisteredOpKeys = new Set<number>();+ const replacementReadOpKeys = new Set<number>();const affectedSubscribers = new Set<(opKeys: number[]) => void>();const cacheChangeSubscribers = new Set<() => void>();const settlementSubscribers = new Set<@@ -71,10 +189,53 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {>();const requestTimeoutMs =options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;+ const initializationTimeoutMs =+ options.initializationTimeoutMs ?? requestTimeoutMs;let nextRequestId = 1;-- let post: (msg: CacheRequest) => void;- let dispose: () => void;+ let state: HostState = 'idle';+ let initialization: Promise<void> | undefined;+ let initializationError: Error | undefined;+ let replacementError: CacheResponseError | undefined;+ let recoveryInProgress = false;+ let latestReplacementEpoch = 0;+ let failureReported = false;+ let terminalFailureHandled = false;+ let adapter: CacheCoordinatorPageAdapter | undefined;+ let adapterDisposePromise: Promise<void> | undefined;+ let adapterDisposeWasGraceful = false;+ let adapterDisposalStarted = false;+ let disposalMode: 'graceful' | 'abrupt' | undefined;+ let pagehideRegistered = false;+ let legacyIdbDeletionStarted = false;+ let telemetryRelayStarted = false;+ let telemetryFinished = false;+ let initializationStartedAt = 0;+ let storageHealthTimer: ReturnType<typeof setInterval> | undefined;+ const setIntervalFn =+ options.setInterval ?? globalThis.setInterval.bind(globalThis);+ const clearIntervalFn =+ options.clearInterval ?? globalThis.clearInterval.bind(globalThis);+ const storageHealthIntervalMs = Math.min(+ Math.max(+ options.storageHealthIntervalMs ?? DEFAULT_STORAGE_HEALTH_INTERVAL_MS,+ MIN_STORAGE_HEALTH_INTERVAL_MS+ ),+ MAX_STORAGE_HEALTH_INTERVAL_MS+ );++ const recordRequestOutcome = (+ entry: Pending,+ outcome: 'success' | 'error',+ error?: unknown+ ): void => {+ telemetry?.record({+ name: 'graphql_cache.host_request',+ operationCategory: operationCategoryForRequest({ kind: entry.kind }),+ outcome,+ errorCode: outcome === 'error' ? classifyCacheError(error) : 'none',+ durationMs: now() - entry.startedAt,+ });+ };const onMessage = (event: MessageEvent<WorkerMessage>) => {const msg = event.data;@@ -88,89 +249,506 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {return;}const prefix = `${clientId}:`;- const opKeys = msg.opIds- .filter((id) => id.startsWith(prefix))- .map((id) => Number(id.slice(prefix.length)))- .filter((n) => Number.isFinite(n));+ const opKeys = [+ ...new Set(+ msg.opIds.flatMap((id) => {+ if (!id.startsWith(prefix)) return [];+ const suffix = id.slice(prefix.length);+ const opKey = Number(suffix);+ return Number.isSafeInteger(opKey) && String(opKey) === suffix+ ? [opKey]+ : [];+ })+ ),+ ];if (opKeys.length > 0) {for (const cb of affectedSubscribers) cb(opKeys);}return;}+ if (!isCacheResponse(msg)) return;const entry = pending.get(msg.id);if (!entry) return;+ if (!msg.ok) {+ const error = new CacheResponseError(msg.error, msg.errorCode);+ if (isOwnerEpochLoss(error)) observeOwnerEpochLoss(error);+ pending.delete(msg.id);+ if (entry.timer !== undefined) clearTimeout(entry.timer);+ recordRequestOutcome(entry, 'error', error);+ entry.reject(error);+ finishGracefulDisposeIfDrained();+ return;+ }pending.delete(msg.id);if (entry.timer !== undefined) clearTimeout(entry.timer);- if (msg.ok) {- entry.resolve(msg.result);- } else {- entry.reject(new Error(msg.error));+ if (+ entry.kind === 'read' &&+ entry.opKey !== undefined &&+ activeOpKeys.has(entry.opKey)+ ) {+ registeredOpKeys.add(entry.opKey);}+ recordRequestOutcome(entry, 'success');+ entry.resolve(msg.result);+ finishGracefulDisposeIfDrained();};- let worker: SharedWorker;- try {- worker = new SharedWorker(- new URL('../worker/cache.shared-worker.ts', import.meta.url),- { type: 'module', name: `graphql-cache:${options.scope}` }+ function beginRecoveryGeneration(): void {+ if (recoveryInProgress) return;+ recoveryInProgress = true;+ lostRegisteredOpKeys.clear();+ for (const opKey of registeredOpKeys) lostRegisteredOpKeys.add(opKey);+ registeredOpKeys.clear();+ }++ function markPendingReads(target: Set<number>): void {+ for (const entry of pending.values()) {+ if (entry.kind === 'read' && entry.opKey !== undefined) {+ target.add(entry.opKey);+ }+ }+ }++ function emitAffectedKeys(opKeys: number[]): void {+ if (opKeys.length === 0) return;+ for (const cb of affectedSubscribers) cb(opKeys);+ }++ function onEngineReplaced(ownerEpoch: number): void {+ if (state === 'failed' || state === 'disposing' || state === 'disposed') {+ return;+ }+ if (ownerEpoch <= latestReplacementEpoch) return;+ latestReplacementEpoch = ownerEpoch;+ // Initial readiness completes the already-running first handshake.+ if (state === 'initializing' && !recoveryInProgress) return;+ if (state === 'ready') {+ beginRecoveryGeneration();+ // No old response put this host into recovery. Requests still pending at+ // replacement broadcast were queued by the coordinator while resetting+ // and will be routed exactly once to this replacement generation.+ markPendingReads(replacementReadOpKeys);+ }+ if (state !== 'ready' && state !== 'awaiting-replacement') return;+ void startInitialization().catch(() => undefined);+ }++ function observeOwnerEpochLoss(error: CacheResponseError): void {+ if (state === 'failed' || state === 'disposing' || state === 'disposed') {+ return;+ }+ beginRecoveryGeneration();+ // A rejected old-epoch read may have registered dependencies before its+ // response was lost. It belongs to the lost generation, not replacement.+ markPendingReads(lostRegisteredOpKeys);+ replacementError = error;+ initialization = undefined;+ state = 'awaiting-replacement';+ }++ function unregisterPagehide(): void {+ if (!pagehideRegistered || typeof removeEventListener !== 'function') {+ return;+ }+ removeEventListener('pagehide', onPagehide);+ pagehideRegistered = false;+ }++ function registerPagehide(): void {+ if (pagehideRegistered || typeof addEventListener !== 'function') return;+ pagehideRegistered = true;+ addEventListener('pagehide', onPagehide, { once: true });+ }++ function getAdapter(): CacheCoordinatorPageAdapter {+ if (adapter) return adapter;+ if (!telemetryRelayStarted) {+ telemetryRelayStarted = true;+ pageTelemetry?.relay.start();+ }+ const created = createCacheCoordinatorPageAdapter({+ scope: options.scope,+ hotCapacity: options.hotCapacity,+ onEngineReplaced,+ onTerminalError: failTransport,+ telemetry,+ });+ created.onmessage = onMessage;+ adapter = created;+ registerPagehide();+ return created;+ }++ function startLegacyIdbDeletion(): void {+ if (legacyIdbDeletionStarted) return;+ legacyIdbDeletionStarted = true;+ // Cutover cleanup must never delay cache startup or any cache RPC.+ void deleteLegacyNormalizedCacheIdb(options.scope);+ }++ function rejectPending(error: Error, transportUncertain = false): void {+ const entries = [...pending.values()];+ pending.clear();+ for (const entry of entries) {+ if (entry.timer !== undefined) clearTimeout(entry.timer);+ recordRequestOutcome(entry, 'error', error);+ if (+ transportUncertain &&+ entry.admitted &&+ entry.kind === 'enqueue-optimistic-mutation'+ ) {+ entry.reject(+ new CacheResponseError(+ `${error.message}: admitted optimistic enqueue outcome is uncertain`,+ ADMITTED_ENQUEUE_UNCERTAIN_ERROR_CODE+ )+ );+ } else {+ entry.reject(error);+ }+ }+ }++ function disposeAdapter(graceful: boolean): Promise<void> {+ if (adapterDisposePromise) {+ if (!graceful && adapterDisposeWasGraceful && adapter) {+ adapterDisposeWasGraceful = false;+ try {+ // A pagehide during graceful retirement must reach the adapter so it+ // can terminate and close instead of memoizing the old mode.+ void adapter.dispose({ graceful: false });+ } catch {+ // The original disposal promise still owns final settlement.+ }+ }+ return adapterDisposePromise;+ }+ if (!adapter) return Promise.resolve();+ adapterDisposeWasGraceful = graceful;+ try {+ adapterDisposePromise = adapter+ .dispose({ graceful })+ .catch(() => undefined);+ } catch {+ // The host is already closed and cannot safely retry disposal.+ adapterDisposePromise = Promise.resolve();+ }+ return adapterDisposePromise;+ }++ function clearSubscribers(): void {+ affectedSubscribers.clear();+ cacheChangeSubscribers.clear();+ settlementSubscribers.clear();+ }++ function reportFailure(error: Error): void {+ if (failureReported) return;+ failureReported = true;+ options.onInitializationError?.(error);+ }++ function failInitialization(error: Error): void {+ if (state === 'failed' || state === 'disposed' || state === 'ready') return;+ telemetry?.record({+ name: 'graphql_cache.host_ready',+ operationCategory: 'initialization',+ outcome: 'error',+ errorCode: classifyCacheError(error),+ durationMs:+ initializationStartedAt > 0 ? now() - initializationStartedAt : 0,+ });+ state = 'failed';+ initialization = undefined;+ initializationError = error;+ rejectPending(error);+ clearSubscribers();+ unregisterPagehide();+ void disposeAdapter(false).then(finishTelemetry);+ reportFailure(error);+ }++ function hasAdmittedEnqueue(): boolean {+ return [...pending.values()].some(+ (entry) => entry.admitted && entry.kind === 'enqueue-optimistic-mutation');- worker.port.onmessage = onMessage;- worker.port.start();- } catch {- return createNoopCacheHost('SharedWorker could not be initialized');- }- post = (msg) => worker.port.postMessage(msg);- dispose = () => {- // Tell the SharedWorker to drop our port — there is no platform- // disconnect event, and stale ports would otherwise accumulate.- const notice: CacheNotice = { kind: 'disconnect' };- worker.port.postMessage(notice);- worker.port.close();- };+ }++ function failTransport(error: Error): void {+ if (terminalFailureHandled) return;+ stopStorageHealthSampling();+ const admittedWorkIsUncertain = [...pending.values()].some(+ (entry) => entry.admitted+ );+ if (state === 'disposed' && !admittedWorkIsUncertain) return;+ terminalFailureHandled = true;+ state = 'failed';+ initialization = undefined;+ initializationError = error;+ rejectPending(error, true);+ clearSubscribers();+ unregisterPagehide();+ void disposeAdapter(false).then(finishTelemetry);+ // Product failure handling may immediately construct another host. Make+ // the matching old scope unreachable before invoking that callback.+ void quarantineCacheScope(options.scope).then(() => {+ try {+ reportFailure(error);+ } catch {+ // Failure reporting cannot reopen or invalidate completed quarantine.+ }+ });+ }++ function stopStorageHealthSampling(): void {+ if (storageHealthTimer === undefined) return;+ clearIntervalFn(storageHealthTimer);+ storageHealthTimer = undefined;+ }++ function finishTelemetry(): void {+ if (telemetryFinished) return;+ stopStorageHealthSampling();+ telemetryFinished = true;+ telemetry?.flush();+ pageTelemetry?.relay.dispose();+ }++ function startAdapterDisposal(graceful: boolean): void {+ if (adapterDisposalStarted) {+ if (!graceful) void disposeAdapter(false);+ return;+ }+ adapterDisposalStarted = true;+ void disposeAdapter(graceful).then(() => {+ if (state !== 'disposing') return;+ state = 'disposed';+ unregisterPagehide();+ finishTelemetry();+ });+ }++ function finishGracefulDisposeIfDrained(): void {+ if (+ state !== 'disposing' ||+ disposalMode !== 'graceful' ||+ pending.size > 0+ ) {+ return;+ }+ startAdapterDisposal(true);+ }++ function disposeHost(graceful: boolean): void {+ stopStorageHealthSampling();+ if (state === 'disposed') return;+ if (state === 'disposing') {+ if (graceful || disposalMode === 'abrupt') return;+ disposalMode = 'abrupt';+ const quarantine = hasAdmittedEnqueue();+ clearSubscribers();+ if (quarantine) void quarantineCacheScope(options.scope);+ rejectPending(new Error('cache worker host was abruptly disposed'), true);+ startAdapterDisposal(false);+ return;+ }+ if (graceful && state === 'ready') {+ // Stop admission first, but keep the requester/standby connected until+ // every already-admitted RPC has a response or its existing read timer.+ // Mutations deliberately have no arbitrary disposal timeout.+ state = 'disposing';+ disposalMode = 'graceful';+ clearSubscribers();+ // Keep pagehide armed through coordinator retirement so an abrupt close+ // can still terminate the adapter's in-progress graceful drain.+ finishGracefulDisposeIfDrained();+ return;+ }++ const quarantine = hasAdmittedEnqueue();+ state = 'disposing';+ disposalMode = 'abrupt';+ clearSubscribers();+ if (quarantine) void quarantineCacheScope(options.scope);+ rejectPending(new Error('cache worker host was abruptly disposed'), true);+ startAdapterDisposal(false);+ }- // Best-effort cleanup when the page goes away (bfcache-safe: a restored- // page gets a fresh host on next use anyway).- if (typeof addEventListener === 'function') {- addEventListener('pagehide', dispose, { once: true });+ function onPagehide(): void {+ disposeHost(false);}function request(- msg: DistributiveOmit<CacheRequest, 'id'>+ msg: DistributiveOmit<CacheRequest, 'id'>,+ opKey?: number): Promise<unknown> {+ if (state === 'failed') {+ return Promise.reject(+ initializationError ?? new Error('cache worker initialization failed')+ );+ }+ if (state === 'disposing' || state === 'disposed') {+ return Promise.reject(new Error('cache worker host was disposed'));+ }+const id = nextRequestId++;return new Promise((resolve, reject) => {- const entry: Pending = { resolve, reject };- if (- msg.kind === 'read' ||- msg.kind === 'read-records' ||- msg.kind === 'inspect-query' ||- msg.kind === 'inspect-query-variants'- ) {+ const entry: Pending = {+ resolve,+ reject,+ kind: msg.kind,+ opKey,+ admitted: false,+ startedAt: now(),+ };+ const timeoutMs =+ msg.kind === 'init'+ ? initializationTimeoutMs+ : msg.kind === 'read' ||+ msg.kind === 'read-records' ||+ msg.kind === 'inspect-query' ||+ msg.kind === 'inspect-query-variants'+ ? requestTimeoutMs+ : undefined;+ if (timeoutMs !== undefined) {entry.timer = setTimeout(() => {if (pending.delete(id)) {- reject(new Error(`cache worker timeout: ${msg.kind}`));+ const error = new Error(`cache worker timeout: ${msg.kind}`);+ recordRequestOutcome(entry, 'error', error);+ reject(error);+ finishGracefulDisposeIfDrained();}- }, requestTimeoutMs);+ }, timeoutMs);}pending.set(id, entry);- post({ ...msg, id } as CacheRequest);+ try {+ getAdapter().postMessage({ ...msg, id } as CacheRequest);+ // The first accepted coordinator send is the browser Turso host's+ // actual lazy start. Only then begin fire-and-forget legacy cleanup.+ startLegacyIdbDeletion();+ if (pending.has(id)) entry.admitted = true;+ } catch (error) {+ if (pending.delete(id) && entry.timer !== undefined) {+ clearTimeout(entry.timer);+ }+ const requestError = asError(error);+ recordRequestOutcome(entry, 'error', requestError);+ reject(requestError);+ }});}- const ready = request({- kind: 'init',- scope: options.scope,- hotCapacity: options.hotCapacity,- });- void (async () => {+ async function observeStorageHealth(): Promise<void> {try {- await ready;+ const storage = navigator.storage;+ const [estimate, persisted] = await Promise.all([+ storage.estimate(),+ typeof storage.persisted === 'function'+ ? storage.persisted()+ : Promise.resolve(undefined),+ ]);+ const usageBytes = estimate.usage;+ const quotaBytes = estimate.quota;+ telemetry?.record({+ name: 'graphql_cache.origin_storage_pressure',+ operationCategory: 'storage',+ outcome: 'success',+ persistence:+ persisted === true+ ? 'granted'+ : persisted === false+ ? 'denied'+ : 'unknown',+ usageBytes,+ quotaBytes,+ ratio:+ usageBytes !== undefined && quotaBytes !== undefined && quotaBytes > 0+ ? usageBytes / quotaBytes+ : undefined,+ });} catch (error) {- options.onInitializationError?.(- error instanceof Error ? error : new Error(String(error))+ telemetry?.record({+ name: 'graphql_cache.origin_storage_pressure',+ operationCategory: 'storage',+ outcome: 'error',+ errorCode: classifyCacheError(error),+ persistence: 'unknown',+ });+ }+ }++ function startStorageHealthSampling(): void {+ void observeStorageHealth();+ storageHealthTimer ??= setIntervalFn(() => {+ void observeStorageHealth();+ }, storageHealthIntervalMs);+ }++ function startInitialization(): Promise<void> {+ state = 'initializing';+ replacementError = undefined;+ initializationStartedAt = now();+ const handshake = request({+ kind: 'init',+ scope: options.scope,+ hotCapacity: options.hotCapacity,+ }).then(+ () => {+ if (state !== 'initializing') return;+ state = 'ready';+ initialization = undefined;+ telemetry?.record({+ name: 'graphql_cache.host_ready',+ operationCategory: 'initialization',+ outcome: 'success',+ errorCode: 'none',+ durationMs: now() - initializationStartedAt,+ });+ startStorageHealthSampling();+ if (recoveryInProgress) {+ const opKeys = [...lostRegisteredOpKeys].filter(+ (opKey) =>+ activeOpKeys.has(opKey) && !replacementReadOpKeys.has(opKey)+ );+ recoveryInProgress = false;+ lostRegisteredOpKeys.clear();+ replacementReadOpKeys.clear();+ emitAffectedKeys(opKeys);+ }+ },+ (error: unknown) => {+ const initializationFailure = asError(error);+ initialization = undefined;+ if (isOwnerEpochLoss(initializationFailure)) {+ observeOwnerEpochLoss(initializationFailure);+ } else {+ failInitialization(initializationFailure);+ }+ throw initializationFailure;+ }+ );+ initialization = handshake;+ return handshake;+ }++ function ensureInitialized(): Promise<void> {+ if (state === 'ready') return Promise.resolve();+ if (state === 'initializing' && initialization) return initialization;+ if (state === 'awaiting-replacement') {+ return Promise.reject(+ replacementError ?? new Error('cache worker is awaiting replacement')+ );+ }+ if (state === 'failed') {+ return Promise.reject(+ initializationError ?? new Error('cache worker initialization failed'));}- })();+ if (state === 'disposing' || state === 'disposed') {+ return Promise.reject(new Error('cache worker host was disposed'));+ }+ return startInitialization();+ }const opId = (opKey: number) => `${clientId}:${opKey}`;@@ -178,21 +756,28 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {clientId,async readQuery(args: CacheReadArgs): Promise<ReadResult> {- await ready;- return (await request({- kind: 'read',- opId: args.opKey === undefined ? undefined : opId(args.opKey),- query: args.query,- operationName: args.operationName,- variables: args.variables,- priority: args.priority,- entityResolvers: args.entityResolvers,- })) as ReadResult;+ if (args.opKey !== undefined) {+ activeOpKeys.add(args.opKey);+ if (recoveryInProgress) replacementReadOpKeys.add(args.opKey);+ }+ await ensureInitialized();+ return (await request(+ {+ kind: 'read',+ opId: args.opKey === undefined ? undefined : opId(args.opKey),+ query: args.query,+ operationName: args.operationName,+ variables: args.variables,+ priority: args.priority,+ entityResolvers: args.entityResolvers,+ },+ args.opKey+ )) as ReadResult;},async readRecords(args: ReadRecordsArgs): Promise<SelectedRecordPageWire> {const limit = validateRecordSelectionLimit(args.limit);- await ready;+ await ensureInitialized();return (await request({kind: 'read-records',document: args.document,@@ -203,7 +788,7 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {},async writeQuery(args: CacheWriteArgs): Promise<WriteResult> {- await ready;+ await ensureInitialized();return (await request({kind: 'write',originOpId: args.opKey === undefined ? undefined : opId(args.opKey),@@ -219,7 +804,7 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {args: EnqueueOptimisticMutationArgs,claim: InitialMutationClaimArgs): Promise<EnqueueOptimisticMutationResult> {- await ready;+ await ensureInitialized();return (await request({kind: 'enqueue-optimistic-mutation',originOpId: args.opKey === undefined ? undefined : opId(args.opKey),@@ -239,7 +824,7 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {async inspectQueryVariants(args: InspectQueryVariantsArgs): Promise<CachedQueryVariantWire[]> {- await ready;+ await ensureInitialized();return (await request({kind: 'inspect-query-variants',query: args.query,@@ -251,7 +836,7 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {async inspectQuery(args: InspectQueryArgs): Promise<CachedQueryInstanceWire[]> {- await ready;+ await ensureInitialized();return (await request({kind: 'inspect-query',query: args.query,@@ -266,7 +851,7 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {nowMs: number,leaseExpiresAtMs: number): Promise<ClaimedMutation | undefined> {- await ready;+ await ensureInitialized();return (await request({kind: 'claim-next-mutation',owner,@@ -281,7 +866,7 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {nextAttemptAtMs: number,error: string): Promise<void> {- await ready;+ await ensureInitialized();await request({kind: 'defer-optimistic-write',transactionId,@@ -297,7 +882,7 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {claim: MutationClaim,args: CacheWriteArgs): Promise<WriteResult> {- await ready;+ await ensureInitialized();return (await request({kind: 'commit-optimistic-write',transactionId,@@ -315,7 +900,7 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {claim: MutationClaim,error: string): Promise<WriteResult> {- await ready;+ await ensureInitialized();return (await request({kind: 'rollback-optimistic-write',transactionId,@@ -326,23 +911,34 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {},async invalidate(keys: string[]): Promise<string[]> {- await ready;+ await ensureInitialized();return (await request({ kind: 'invalidate', keys })) as string[];},async deleteRecords(keys: string[]): Promise<string[]> {- await ready;+ await ensureInitialized();return (await request({ kind: 'delete-records', keys })) as string[];},async teardown(opKey: number): Promise<void> {- await ready;+ activeOpKeys.delete(opKey);+ registeredOpKeys.delete(opKey);+ lostRegisteredOpKeys.delete(opKey);+ replacementReadOpKeys.delete(opKey);+ await ensureInitialized();await request({ kind: 'teardown', opId: opId(opKey) });},async clear(): Promise<void> {- await ready;+ await ensureInitialized();await request({ kind: 'clear' });+ telemetry?.record({+ name: 'graphql_cache.logical_reset',+ operationCategory: 'lifecycle',+ outcome: 'success',+ errorCode: 'none',+ resetReason: 'explicit-clear',+ });},onOpsAffected(cb: (opKeys: number[]) => void): () => void {@@ -363,10 +959,7 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {},dispose() {- affectedSubscribers.clear();- cacheChangeSubscribers.clear();- settlementSubscribers.clear();- dispose();+ disposeHost(true);},};}diff --git a/apps/web/src/lib/graphql-cache/legacy-idb-cleanup.test.ts b/apps/web/src/lib/graphql-cache/legacy-idb-cleanup.test.tsnew file mode 100644index 0000000000..f8d3cc1ffa--- /dev/null+++ b/apps/web/src/lib/graphql-cache/legacy-idb-cleanup.test.ts@@ -0,0 +1,132 @@+import { afterEach, describe, expect, it, vi } from 'vitest';+import { deleteLegacyNormalizedCacheIdb } from './legacy-idb-cleanup';++type MutableDeleteRequest = Pick<+ IDBOpenDBRequest,+ 'onblocked' | 'onerror' | 'onsuccess'+>;++function deleteRequest(): MutableDeleteRequest {+ return {+ onblocked: null,+ onerror: null,+ onsuccess: null,+ };+}++function dispatch(+ request: MutableDeleteRequest,+ kind: 'blocked' | 'error' | 'success'+): ReturnType<typeof vi.fn> {+ const preventDefault = vi.fn();+ const event = { type: kind, preventDefault } as unknown as Event;+ const handler =+ kind === 'blocked'+ ? request.onblocked+ : kind === 'error'+ ? request.onerror+ : request.onsuccess;+ handler?.call(request as IDBOpenDBRequest, event);+ return preventDefault;+}++describe('deleteLegacyNormalizedCacheIdb', () => {+ afterEach(() => {+ vi.unstubAllGlobals();+ vi.restoreAllMocks();+ });++ it('deletes only the exact former database name without opening or enumerating IDB', async () => {+ const request = deleteRequest();+ const deleteDatabase = vi.fn(() => request);+ const open = vi.fn();+ const databases = vi.fn();+ vi.stubGlobal('indexedDB', { deleteDatabase, open, databases });++ const attempt = deleteLegacyNormalizedCacheIdb('scope:s1:v2');++ expect(deleteDatabase).toHaveBeenCalledOnce();+ expect(deleteDatabase).toHaveBeenCalledWith('graphql-cache:scope:s1:v2');+ expect(open).not.toHaveBeenCalled();+ expect(databases).not.toHaveBeenCalled();+ expect(deleteDatabase).not.toHaveBeenCalledWith(+ 'unrelated-idb:scope:s1:v2'+ );+ dispatch(request, 'success');+ await expect(attempt).resolves.toBeUndefined();+ });++ it('settles on blocked while allowing the same request to complete later', async () => {+ const request = deleteRequest();+ vi.stubGlobal('indexedDB', {+ deleteDatabase: vi.fn(() => request),+ });+ const attempt = deleteLegacyNormalizedCacheIdb('blocked-scope');++ expect(dispatch(request, 'blocked')).not.toHaveBeenCalled();+ await expect(attempt).resolves.toBeUndefined();++ expect(() => dispatch(request, 'success')).not.toThrow();+ const preventDefault = dispatch(request, 'error');+ expect(preventDefault).toHaveBeenCalledOnce();+ });++ it('settles and suppresses an IndexedDB request error', async () => {+ const request = deleteRequest();+ vi.stubGlobal('indexedDB', {+ deleteDatabase: vi.fn(() => request),+ });+ const attempt = deleteLegacyNormalizedCacheIdb('error-scope');++ const preventDefault = dispatch(request, 'error');++ expect(preventDefault).toHaveBeenCalledOnce();+ await expect(attempt).resolves.toBeUndefined();+ });++ it.each([+ ['missing API', undefined],+ [+ 'synchronous deletion failure',+ {+ deleteDatabase: vi.fn(() => {+ throw new DOMException('denied', 'SecurityError');+ }),+ },+ ],+ ])('settles when IndexedDB is unavailable: %s', async (label, factory) => {+ vi.stubGlobal('indexedDB', factory);++ await expect(+ deleteLegacyNormalizedCacheIdb(`unavailable-${label}`)+ ).resolves.toBeUndefined();+ });++ it('attempts deletion once per scope for the module session', async () => {+ const firstRequest = deleteRequest();+ const secondRequest = deleteRequest();+ const deleteDatabase = vi+ .fn()+ .mockReturnValueOnce(firstRequest)+ .mockReturnValueOnce(secondRequest);+ vi.stubGlobal('indexedDB', { deleteDatabase });++ const first = deleteLegacyNormalizedCacheIdb('same-scope');+ const duplicate = deleteLegacyNormalizedCacheIdb('same-scope');+ expect(duplicate).toBe(first);+ expect(deleteDatabase).toHaveBeenCalledOnce();+ dispatch(firstRequest, 'success');+ await first;++ await deleteLegacyNormalizedCacheIdb('same-scope');+ expect(deleteDatabase).toHaveBeenCalledOnce();++ const other = deleteLegacyNormalizedCacheIdb('other-scope');+ expect(deleteDatabase).toHaveBeenNthCalledWith(+ 2,+ 'graphql-cache:other-scope'+ );+ dispatch(secondRequest, 'success');+ await other;+ });+});diff --git a/apps/web/src/lib/graphql-cache/legacy-idb-cleanup.ts b/apps/web/src/lib/graphql-cache/legacy-idb-cleanup.tsnew file mode 100644index 0000000000..89e9a8d61b--- /dev/null+++ b/apps/web/src/lib/graphql-cache/legacy-idb-cleanup.ts@@ -0,0 +1,43 @@+/**+ * Best-effort removal of the normalized cache's former IndexedDB database.+ *+ * Cutover never opens, enumerates, or migrates the old database. A blocked+ * deletion settles immediately for callers while the browser remains free to+ * complete the same request after an old tab releases its connection.+ */++const deletionAttempts = new Map<string, Promise<void>>();++/** Deletes exactly the former `graphql-cache:<scope>` database once per page session. */+export function deleteLegacyNormalizedCacheIdb(scope: string): Promise<void> {+ const existing = deletionAttempts.get(scope);+ if (existing) return existing;++ const attempt = new Promise<void>((resolve) => {+ try {+ const factory = globalThis.indexedDB;+ if (!factory || typeof factory.deleteDatabase !== 'function') {+ resolve();+ return;+ }++ const request = factory.deleteDatabase(`graphql-cache:${scope}`);+ let settled = false;+ const settle = (event: Event): void => {+ // Keep this handler installed after `blocked`: the same request can+ // later fail, and preventing its error avoids an uncaught global event.+ if (event.type === 'error') event.preventDefault();+ if (settled) return;+ settled = true;+ resolve();+ };+ request.onsuccess = settle;+ request.onerror = settle;+ request.onblocked = settle;+ } catch {+ resolve();+ }+ });+ deletionAttempts.set(scope, attempt);+ return attempt;+}diff --git a/apps/web/src/lib/graphql-cache/lifecycle.test.ts b/apps/web/src/lib/graphql-cache/lifecycle.test.tsindex f25180ddf5..0f2664e866 100644--- a/apps/web/src/lib/graphql-cache/lifecycle.test.ts+++ b/apps/web/src/lib/graphql-cache/lifecycle.test.ts@@ -1,4 +1,4 @@-import { beforeEach, describe, expect, it, vi } from 'vitest';+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';import type { CacheHost } from './host/types';function hostWithClear(clear: () => Promise<void>): CacheHost {@@ -12,6 +12,10 @@ describe('clearRegisteredCaches', () => {vi.resetModules();});+ afterEach(() => {+ vi.unstubAllGlobals();+ });+it('preserves the scope when every cache clears', async () => {localStorage.setItem('graphql-cache:scope', 'current-scope');const clear = vi.fn().mockResolvedValue(undefined);@@ -26,6 +30,51 @@ describe('clearRegisteredCaches', () => {expect(localStorage.getItem('graphql-cache:scope')).toBe('current-scope');});+ it('awaits the serialized scope rotation before logout clearing resolves', async () => {+ localStorage.setItem('graphql-cache:scope', 'current-scope');+ vi.spyOn(crypto, 'randomUUID').mockReturnValue(+ '00000000-0000-4000-8000-000000000002'+ );+ let enterLock!: () => void;+ const lockGate = new Promise<void>((resolve) => {+ enterLock = resolve;+ });+ vi.stubGlobal('navigator', {+ locks: {+ request: vi.fn(+ async (+ name: string,+ _options: LockOptions,+ callback: (lock: Lock | null) => unknown+ ) => {+ await lockGate;+ return await callback({ name, mode: 'exclusive' } as Lock);+ }+ ),+ },+ });+ const { clearRegisteredCaches, registerCacheHost } = await import(+ './lifecycle'+ );+ registerCacheHost(+ hostWithClear(async () => await Promise.reject(new Error('wipe failed')))+ );+ let settled = false;++ const clearing = clearRegisteredCaches().then(() => {+ settled = true;+ });+ await Promise.resolve();+ expect(settled).toBe(false);+ expect(localStorage.getItem('graphql-cache:scope')).toBe('current-scope');+ enterLock();+ await clearing;++ expect(localStorage.getItem('graphql-cache:scope')).toBe(+ '00000000-0000-4000-8000-000000000002'+ );+ });+it('rotates the scope after attempting every clear when one fails', async () => {localStorage.setItem('graphql-cache:scope', 'current-scope');vi.spyOn(crypto, 'randomUUID').mockReturnValue(diff --git a/apps/web/src/lib/graphql-cache/lifecycle.ts b/apps/web/src/lib/graphql-cache/lifecycle.tsindex 30cbe78196..c4c6ee31e1 100644--- a/apps/web/src/lib/graphql-cache/lifecycle.ts+++ b/apps/web/src/lib/graphql-cache/lifecycle.ts@@ -9,12 +9,12 @@ export function registerCacheHost(host: CacheHost): () => void {return () => hosts.delete(host);}-/** Best-effort wipe of records and queued user intent during logout. */+/** Best-effort reset of each active cache database during logout. */export async function clearRegisteredCaches(): Promise<void> {const results = await Promise.allSettled([...hosts].map((host) => host.clear()));if (results.some((result) => result.status === 'rejected')) {- rotateCacheScope();+ await rotateCacheScope();}}diff --git a/apps/web/src/lib/graphql-cache/protocol.test.ts b/apps/web/src/lib/graphql-cache/protocol.test.tsindex e974760404..de01eafe18 100644--- a/apps/web/src/lib/graphql-cache/protocol.test.ts+++ b/apps/web/src/lib/graphql-cache/protocol.test.ts@@ -1,5 +1,8 @@import { describe, expect, it } from 'vitest';import {+ isCachePush,+ isCacheResponse,+ isWorkerMessage,MAX_RECORD_SELECTION_PAGE_SIZE,validateRecordSelectionLimit,} from './protocol';@@ -25,3 +28,66 @@ describe('validateRecordSelectionLimit', () => {);});});++describe('cache worker message validators', () => {+ it('accepts exact responses and every typed push', () => {+ const values = [+ { id: 1, ok: true, result: { kind: 'miss' } },+ { id: 2, ok: false, error: 'failed' },+ {+ id: 3,+ ok: false,+ error: 'old owner failed',+ errorCode: 'owner-epoch-lost',+ },+ {+ id: 4,+ ok: false,+ error: 'enqueue response uncertain',+ errorCode: 'admitted-enqueue-uncertain',+ },+ { kind: 'ops-affected', opIds: ['client:7'], keys: ['User:1'] },+ { kind: 'cache-changed' },+ {+ kind: 'mutation-settled',+ settlement: { transactionId: '3', status: 'committed' },+ },+ {+ kind: 'mutation-settled',+ settlement: {+ transactionId: '4',+ status: 'permanently-failed',+ error: 'denied',+ },+ },+ ];++ expect(values.map(isWorkerMessage)).toEqual(values.map(() => true));+ expect(isCacheResponse(values[0])).toBe(true);+ expect(isCachePush(values[4])).toBe(true);+ });++ it.each([+ null,+ [],+ 'push',+ 7,+ { id: -1, ok: true, result: null },+ { id: 1, ok: true },+ { id: 1, ok: false, error: 'failed', extra: true },+ { id: 1, ok: false, error: 'failed', errorCode: 'future-code' },+ { kind: 'ops-affected', opIds: [7], keys: [] },+ { kind: 'ops-affected', opIds: [], keys: [], extra: true },+ { kind: 'cache-changed', keys: [] },+ {+ kind: 'mutation-settled',+ settlement: { transactionId: '3', status: 'committed', error: 'extra' },+ },+ {+ kind: 'mutation-settled',+ settlement: { transactionId: '4', status: 'permanently-failed' },+ },+ ])('rejects malformed or extended worker message %#', (value) => {+ expect(isWorkerMessage(value)).toBe(false);+ });+});diff --git a/apps/web/src/lib/graphql-cache/protocol.ts b/apps/web/src/lib/graphql-cache/protocol.tsindex dd0ada45ec..f6b079a9ff 100644--- a/apps/web/src/lib/graphql-cache/protocol.ts+++ b/apps/web/src/lib/graphql-cache/protocol.ts@@ -4,8 +4,9 @@ import type { EntityResolverWire } from './exchange/entity-resolvers';* Wire protocol between page contexts and the cache worker (the `CacheHost`* RPC from the design doc, apps/web/docs/graphql-normalized-cache-plan.md §4).*- * The browser topology is one SharedWorker engine serving many page ports.- * Platforms without SharedWorker support use a storage-free no-op host.+ * The browser topology routes page ports through a SharedWorker coordinator+ * to one elected DedicatedWorker engine. Platforms missing the required+ * coordinator capabilities use a storage-free no-op host.** Operation ids are strings of the form `"{clientId}:{urqlOperationKey}"` so* one shared engine can track operations from many tabs without collisions.@@ -282,23 +283,27 @@ export type CacheRequest = { id: number } & (| { kind: 'clear' });-export type CacheResponse =- | { id: number; ok: true; result: unknown }- | { id: number; ok: false; error: string };+/** Stable machine-readable cache RPC rejection codes. */+export type CacheResponseErrorCode =+ | 'owner-epoch-lost'+ | 'admitted-enqueue-uncertain';-/**- * Fire-and-forget notice from a client to the worker (no id/response).- * `disconnect` lets a SharedWorker drop the sender's port — there is no- * platform event for client disconnection, so hosts send this on dispose- * and pagehide.- */-export type CacheNotice = { kind: 'disconnect' };+/** Old-owner work was rejected after fenced engine loss and was not replayed. */+export const OWNER_EPOCH_LOST_ERROR_CODE: CacheResponseErrorCode =+ 'owner-epoch-lost';-export function isCacheNotice(- msg: CacheRequest | CacheNotice-): msg is CacheNotice {- return msg.kind === 'disconnect';-}+/** An enqueue send was admitted before its unfenced transport became uncertain. */+export const ADMITTED_ENQUEUE_UNCERTAIN_ERROR_CODE: CacheResponseErrorCode =+ 'admitted-enqueue-uncertain';++export type CacheResponse =+ | { id: number; ok: true; result: unknown }+ | {+ id: number;+ ok: false;+ error: string;+ errorCode?: CacheResponseErrorCode;+ };/*** Pushed (not request/response) messages from worker to its client(s):@@ -317,6 +322,100 @@ export type CachePush =export type WorkerMessage = CacheResponse | CachePush;-export function isCachePush(msg: WorkerMessage): msg is CachePush {- return 'kind' in msg;+type UnknownWireRecord = Record<string, unknown>;++const isWireRecord = (value: unknown): value is UnknownWireRecord =>+ typeof value === 'object' && value !== null && !Array.isArray(value);++const hasOnlyWireKeys = (+ value: UnknownWireRecord,+ keys: readonly string[]+): boolean => Object.keys(value).every((key) => keys.includes(key));++const isWireStringArray = (value: unknown): value is string[] =>+ Array.isArray(value) && value.every((item) => typeof item === 'string');++/** Strictly validates a machine-readable cache response error code. */+export const isCacheResponseErrorCode = (+ value: unknown+): value is CacheResponseErrorCode =>+ value === OWNER_EPOCH_LOST_ERROR_CODE ||+ value === ADMITTED_ENQUEUE_UNCERTAIN_ERROR_CODE;++/** Identifies a coordinator-fenced rejection from a lost owner epoch. */+export const isOwnerEpochLostError = (+ value: unknown+): value is Error & { errorCode: 'owner-epoch-lost' } =>+ value instanceof Error &&+ 'errorCode' in value &&+ value.errorCode === OWNER_EPOCH_LOST_ERROR_CODE;++/** Identifies the host-only uncertainty result for an admitted enqueue send. */+export const isAdmittedEnqueueUncertainError = (+ value: unknown+): value is Error & { errorCode: 'admitted-enqueue-uncertain' } =>+ value instanceof Error &&+ 'errorCode' in value &&+ value.errorCode === ADMITTED_ENQUEUE_UNCERTAIN_ERROR_CODE;++/** Strictly validates a cache response received across a host boundary. */+export function isCacheResponse(value: unknown): value is CacheResponse {+ if (+ !isWireRecord(value) ||+ !Number.isSafeInteger(value.id) ||+ (value.id as number) < 0+ ) {+ return false;+ }+ if (value.ok === true) {+ return (+ hasOnlyWireKeys(value, ['id', 'ok', 'result']) &&+ Object.hasOwn(value, 'result')+ );+ }+ return (+ value.ok === false &&+ hasOnlyWireKeys(value, ['id', 'ok', 'error', 'errorCode']) &&+ typeof value.error === 'string' &&+ (value.errorCode === undefined || isCacheResponseErrorCode(value.errorCode))+ );}++/** Strictly validates a pushed cache notification. */+export function isCachePush(value: unknown): value is CachePush {+ if (!isWireRecord(value)) return false;+ switch (value.kind) {+ case 'ops-affected':+ return (+ hasOnlyWireKeys(value, ['kind', 'opIds', 'keys']) &&+ isWireStringArray(value.opIds) &&+ isWireStringArray(value.keys)+ );+ case 'cache-changed':+ return hasOnlyWireKeys(value, ['kind']);+ case 'mutation-settled': {+ const settlement = value.settlement;+ if (+ !hasOnlyWireKeys(value, ['kind', 'settlement']) ||+ !isWireRecord(settlement) ||+ typeof settlement.transactionId !== 'string'+ ) {+ return false;+ }+ if (settlement.status === 'committed') {+ return hasOnlyWireKeys(settlement, ['transactionId', 'status']);+ }+ return (+ settlement.status === 'permanently-failed' &&+ hasOnlyWireKeys(settlement, ['transactionId', 'status', 'error']) &&+ typeof settlement.error === 'string'+ );+ }+ default:+ return false;+ }+}++/** Strictly validates any response or push delivered to a cache host. */+export const isWorkerMessage = (value: unknown): value is WorkerMessage =>+ isCacheResponse(value) || isCachePush(value);diff --git a/apps/web/src/lib/graphql-cache/rollout-observability.ts b/apps/web/src/lib/graphql-cache/rollout-observability.tsnew file mode 100644index 0000000000..b8133b291e--- /dev/null+++ b/apps/web/src/lib/graphql-cache/rollout-observability.ts@@ -0,0 +1,28 @@+import { isTauri } from '@core/util/platform';+import { getBrowserTursoCacheRolloutDecision } from './rollout';+import { createPageCacheTelemetry } from './telemetry-relay';++/** Records the navigation control/treatment point without starting cache I/O. */+export function recordBrowserTursoCacheNavigation(): void {+ if (isTauri()) return;+ try {+ const decision = getBrowserTursoCacheRolloutDecision();+ const navigation = performance.getEntriesByType('navigation')[0] as+ | PerformanceNavigationTiming+ | undefined;+ const pageTelemetry = createPageCacheTelemetry({+ rolloutCohort: decision.cohort,+ });+ pageTelemetry.recorder.record({+ name: 'graphql_cache.navigation',+ operationCategory: 'navigation',+ outcome: 'success',+ errorCode: 'none',+ durationMs: navigation?.duration ?? 0,+ });+ pageTelemetry.recorder.flush();+ pageTelemetry.relay.dispose();+ } catch {+ // Navigation telemetry is observational and must never delay rendering.+ }+}diff --git a/apps/web/src/lib/graphql-cache/rollout-policy.test.ts b/apps/web/src/lib/graphql-cache/rollout-policy.test.tsnew file mode 100644index 0000000000..4683377ba2--- /dev/null+++ b/apps/web/src/lib/graphql-cache/rollout-policy.test.ts@@ -0,0 +1,101 @@+import { describe, expect, it } from 'vitest';+import {+ type BooleanFlag,+ resolveBrowserTursoCacheRollout,+} from './rollout-policy';++const values: BooleanFlag[] = [undefined, false, true];++describe('browser Turso cache rollout policy', () => {+ it('is exhaustive: kill wins, explicit enable override is next, undefined fails closed', () => {+ for (const enableEnvOverride of values) {+ for (const disableEnvOverride of values) {+ for (const posthogEnable of values) {+ for (const posthogDisable of values) {+ const decision = resolveBrowserTursoCacheRollout({+ isTauri: false,+ graphqlTransportEnabled: true,+ enableEnvOverride,+ disableEnvOverride,+ posthogEnable,+ posthogDisable,+ });+ const killed =+ disableEnvOverride === true || posthogDisable === true;+ const expected = killed+ ? false+ : enableEnvOverride !== undefined+ ? enableEnvOverride+ : posthogEnable === true;+ expect(+ decision.enabled,+ JSON.stringify({+ enableEnvOverride,+ disableEnvOverride,+ posthogEnable,+ posthogDisable,+ })+ ).toBe(expected);+ if (killed) expect(decision.reason).toBe('emergency-disabled');+ }+ }+ }+ }+ });++ it('keeps production-style undefined flags off', () => {+ expect(+ resolveBrowserTursoCacheRollout({+ isTauri: false,+ graphqlTransportEnabled: true,+ enableEnvOverride: undefined,+ disableEnvOverride: undefined,+ posthogEnable: undefined,+ posthogDisable: undefined,+ })+ ).toEqual({+ enabled: false,+ cohort: 'control',+ reason: 'not-enabled',+ nativeCacheUnchanged: false,+ });+ });++ it('does not enable a cache when the existing GraphQL transport is disabled', () => {+ expect(+ resolveBrowserTursoCacheRollout({+ isTauri: false,+ graphqlTransportEnabled: false,+ enableEnvOverride: true,+ disableEnvOverride: false,+ posthogEnable: true,+ posthogDisable: false,+ })+ ).toMatchObject({+ enabled: false,+ reason: 'graphql-transport-disabled',+ });+ });++ it.each([false, true])(+ 'leaves Tauri native cache behavior equal to GraphQL transport=%s',+ (graphqlTransportEnabled) => {+ expect(+ resolveBrowserTursoCacheRollout({+ isTauri: true,+ graphqlTransportEnabled,+ // Even contradictory browser values are irrelevant on native.+ enableEnvOverride: !graphqlTransportEnabled,+ disableEnvOverride: true,+ posthogEnable: !graphqlTransportEnabled,+ posthogDisable: true,+ })+ ).toEqual({+ enabled: graphqlTransportEnabled,+ cohort: 'unknown',+ reason: 'tauri-native-unchanged',+ nativeCacheUnchanged: true,+ });+ }+ );+});diff --git a/apps/web/src/lib/graphql-cache/rollout-policy.ts b/apps/web/src/lib/graphql-cache/rollout-policy.tsnew file mode 100644index 0000000000..4311335164--- /dev/null+++ b/apps/web/src/lib/graphql-cache/rollout-policy.ts@@ -0,0 +1,82 @@+import type { CacheRolloutCohort } from './telemetry';++export type BooleanFlag = boolean | undefined;++export type BrowserTursoCacheRolloutInput = {+ isTauri: boolean;+ graphqlTransportEnabled: boolean;+ enableEnvOverride: BooleanFlag;+ disableEnvOverride: BooleanFlag;+ posthogEnable: BooleanFlag;+ posthogDisable: BooleanFlag;+};++export type BrowserTursoCacheRolloutDecision = {+ enabled: boolean;+ cohort: CacheRolloutCohort;+ reason:+ | 'tauri-native-unchanged'+ | 'graphql-transport-disabled'+ | 'emergency-disabled'+ | 'env-enabled'+ | 'posthog-enabled'+ | 'not-enabled';+ /** Whether the caller must retain the existing native cache path. */+ nativeCacheUnchanged: boolean;+};++/**+ * Pure cache rollout policy. The emergency flag is intentionally independent from the+ * rollout flag and any true kill source wins. Undefined PostHog values fail+ * closed. Tauri returns before browser policy is considered.+ */+export function resolveBrowserTursoCacheRollout(+ input: BrowserTursoCacheRolloutInput+): BrowserTursoCacheRolloutDecision {+ if (input.isTauri) {+ return {+ enabled: input.graphqlTransportEnabled,+ cohort: 'unknown',+ reason: 'tauri-native-unchanged',+ nativeCacheUnchanged: true,+ };+ }+ if (!input.graphqlTransportEnabled) {+ return {+ enabled: false,+ cohort: 'control',+ reason: 'graphql-transport-disabled',+ nativeCacheUnchanged: false,+ };+ }+ if (input.disableEnvOverride === true || input.posthogDisable === true) {+ return {+ enabled: false,+ cohort: 'control',+ reason: 'emergency-disabled',+ nativeCacheUnchanged: false,+ };+ }+ if (input.enableEnvOverride !== undefined) {+ return {+ enabled: input.enableEnvOverride,+ cohort: input.enableEnvOverride ? 'override' : 'control',+ reason: input.enableEnvOverride ? 'env-enabled' : 'not-enabled',+ nativeCacheUnchanged: false,+ };+ }+ if (input.posthogEnable === true) {+ return {+ enabled: true,+ cohort: 'treatment',+ reason: 'posthog-enabled',+ nativeCacheUnchanged: false,+ };+ }+ return {+ enabled: false,+ cohort: 'control',+ reason: 'not-enabled',+ nativeCacheUnchanged: false,+ };+}diff --git a/apps/web/src/lib/graphql-cache/rollout.test.ts b/apps/web/src/lib/graphql-cache/rollout.test.tsnew file mode 100644index 0000000000..d9d6540770--- /dev/null+++ b/apps/web/src/lib/graphql-cache/rollout.test.ts@@ -0,0 +1,82 @@+import { beforeEach, describe, expect, it, vi } from 'vitest';++const mocks = vi.hoisted(() => ({+ isTauri: vi.fn(() => false),+ graphqlEnabled: vi.fn(() => true),+ isFeatureEnabled: vi.fn<(flag: string) => boolean | undefined>(),+}));++vi.mock('@core/util/platform', () => ({ isTauri: mocks.isTauri }));+vi.mock('@core/constant/featureFlags', () => ({+ ENABLE_GRAPHQL_SOUP: mocks.graphqlEnabled,+ ENABLE_BROWSER_TURSO_CACHE_FLAG: 'enable-browser-turso-cache',+ DISABLE_BROWSER_TURSO_CACHE_FLAG: 'disable-browser-turso-cache',+ ENABLE_BROWSER_TURSO_CACHE_OVERRIDE: undefined,+ DISABLE_BROWSER_TURSO_CACHE_OVERRIDE: undefined,+}));+vi.mock('@app/lib/analytics', () => ({+ analytics: {+ posthog: {+ isFeatureEnabled: mocks.isFeatureEnabled,+ },+ },+}));++import { getBrowserTursoCacheRolloutDecision } from './rollout';++describe('browser Turso cache production gate', () => {+ beforeEach(() => {+ vi.clearAllMocks();+ mocks.isTauri.mockReturnValue(false);+ mocks.graphqlEnabled.mockReturnValue(true);+ mocks.isFeatureEnabled.mockReturnValue(undefined);+ });++ it('fails closed while PostHog flags are undefined', () => {+ expect(getBrowserTursoCacheRolloutDecision()).toMatchObject({+ enabled: false,+ cohort: 'control',+ reason: 'not-enabled',+ });+ });++ it('uses a Boolean PostHog rollout and lets the independent kill win', () => {+ mocks.isFeatureEnabled.mockImplementation(+ (flag) => flag === 'enable-browser-turso-cache'+ );+ expect(getBrowserTursoCacheRolloutDecision().enabled).toBe(true);++ mocks.isFeatureEnabled.mockReturnValue(true);+ expect(getBrowserTursoCacheRolloutDecision()).toMatchObject({+ enabled: false,+ reason: 'emergency-disabled',+ });+ });++ it('does not read browser PostHog flags or subscribe on Tauri', () => {+ mocks.isTauri.mockReturnValue(true);+ mocks.graphqlEnabled.mockReturnValue(true);+ mocks.isFeatureEnabled.mockImplementation(() => {+ throw new Error('browser flag touched on Tauri');+ });++ expect(getBrowserTursoCacheRolloutDecision()).toMatchObject({+ enabled: true,+ nativeCacheUnchanged: true,+ });+ expect(mocks.isFeatureEnabled).not.toHaveBeenCalled();+ });++ it('imports without constructing browser workers', async () => {+ const WorkerConstructor = vi.fn(() => {+ throw new Error('worker must stay lazy');+ });+ vi.stubGlobal('Worker', WorkerConstructor);+ vi.stubGlobal('SharedWorker', WorkerConstructor);++ await import('./worker/coordinator-page-adapter');++ expect(WorkerConstructor).not.toHaveBeenCalled();+ vi.unstubAllGlobals();+ });+});diff --git a/apps/web/src/lib/graphql-cache/rollout.ts b/apps/web/src/lib/graphql-cache/rollout.tsnew file mode 100644index 0000000000..de649a4b77--- /dev/null+++ b/apps/web/src/lib/graphql-cache/rollout.ts@@ -0,0 +1,44 @@+import { analytics } from '@app/lib/analytics';+import {+ DISABLE_BROWSER_TURSO_CACHE_FLAG,+ DISABLE_BROWSER_TURSO_CACHE_OVERRIDE,+ ENABLE_BROWSER_TURSO_CACHE_FLAG,+ ENABLE_BROWSER_TURSO_CACHE_OVERRIDE,+ ENABLE_GRAPHQL_SOUP,+} from '@core/constant/featureFlags';+import { isTauri } from '@core/util/platform';+import {+ type BrowserTursoCacheRolloutDecision,+ resolveBrowserTursoCacheRollout,+} from './rollout-policy';++/** Resolves the current gate without constructing a browser cache resource. */+export function getBrowserTursoCacheRolloutDecision(): BrowserTursoCacheRolloutDecision {+ const native = isTauri();+ const graphqlTransportEnabled = ENABLE_GRAPHQL_SOUP();+ if (native) {+ // Do not touch browser rollout flags on Tauri. Besides preserving behavior,+ // this keeps native startup independent from PostHog browser-cache state.+ return resolveBrowserTursoCacheRollout({+ isTauri: true,+ graphqlTransportEnabled,+ enableEnvOverride: undefined,+ disableEnvOverride: undefined,+ posthogEnable: undefined,+ posthogDisable: undefined,+ });+ }++ return resolveBrowserTursoCacheRollout({+ isTauri: false,+ graphqlTransportEnabled,+ enableEnvOverride: ENABLE_BROWSER_TURSO_CACHE_OVERRIDE,+ disableEnvOverride: DISABLE_BROWSER_TURSO_CACHE_OVERRIDE,+ posthogEnable: analytics.posthog.isFeatureEnabled(+ ENABLE_BROWSER_TURSO_CACHE_FLAG+ ),+ posthogDisable: analytics.posthog.isFeatureEnabled(+ DISABLE_BROWSER_TURSO_CACHE_FLAG+ ),+ });+}diff --git a/apps/web/src/lib/graphql-cache/scope.test.ts b/apps/web/src/lib/graphql-cache/scope.test.tsnew file mode 100644index 0000000000..222d0487d2--- /dev/null+++ b/apps/web/src/lib/graphql-cache/scope.test.ts@@ -0,0 +1,110 @@+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';+import { quarantineCacheScope, rotateCacheScope } from './scope';++const STORAGE_KEY = 'graphql-cache:scope';++type LockRequest = {+ run: () => Promise<void>;+};++function controlledLockManager(): {+ lockManager: Pick<LockManager, 'request'>;+ requests: LockRequest[];+} {+ const requests: LockRequest[] = [];+ const lockManager = {+ request: vi.fn(+ <T>(+ _name: string,+ _options: LockOptions,+ callback: (lock: Lock | null) => T | PromiseLike<T>+ ): Promise<T> =>+ new Promise<T>((resolve, reject) => {+ requests.push({+ run: async () => {+ try {+ resolve(+ await callback({+ name: 'graphql-cache:scope-storage',+ mode: 'exclusive',+ } as Lock)+ );+ } catch (error) {+ reject(error);+ }+ },+ });+ })+ ),+ } as unknown as Pick<LockManager, 'request'>;+ return { lockManager, requests };+}++describe('serialized cache scope replacement', () => {+ beforeEach(() => {+ localStorage.clear();+ });++ afterEach(() => {+ vi.unstubAllGlobals();+ vi.restoreAllMocks();+ });++ it('falls back synchronously only when Web Locks are unavailable', async () => {+ vi.stubGlobal('navigator', {});+ localStorage.setItem(STORAGE_KEY, 'old-scope');++ await expect(quarantineCacheScope('old-scope')).resolves.toBe(+ 'quarantine:old-scope'+ );+ expect(localStorage.getItem(STORAGE_KEY)).toBe('quarantine:old-scope');+ });++ it('does not use an unsafe fallback when an advertised lock fails', async () => {+ vi.stubGlobal('navigator', {+ locks: { request: vi.fn().mockRejectedValue(new Error('lock failed')) },+ });+ localStorage.setItem(STORAGE_KEY, 'old-scope');++ await expect(quarantineCacheScope('old-scope')).resolves.toBeUndefined();+ expect(localStorage.getItem(STORAGE_KEY)).toBe('old-scope');+ });++ it('serializes a stale S1 quarantine behind an S2 rotation', async () => {+ const { lockManager, requests } = controlledLockManager();+ vi.stubGlobal('navigator', { locks: lockManager });+ vi.spyOn(crypto, 'randomUUID').mockReturnValue(+ '22222222-2222-4222-8222-222222222222'+ );+ localStorage.setItem(STORAGE_KEY, 'scope-1');++ const staleQuarantine = quarantineCacheScope('scope-1');+ const rotateToScope2 = rotateCacheScope();+ expect(requests).toHaveLength(2);+ await requests[1]?.run();+ await expect(rotateToScope2).resolves.toBe(+ '22222222-2222-4222-8222-222222222222'+ );+ await requests[0]?.run();+ await expect(staleQuarantine).resolves.toBeUndefined();++ expect(localStorage.getItem(STORAGE_KEY)).toBe(+ '22222222-2222-4222-8222-222222222222'+ );+ });++ it('converges serialized failures that observed the same S1 scope', async () => {+ const { lockManager, requests } = controlledLockManager();+ vi.stubGlobal('navigator', { locks: lockManager });+ localStorage.setItem(STORAGE_KEY, 'scope-1');++ const first = quarantineCacheScope('scope-1');+ const second = quarantineCacheScope('scope-1');+ await requests[0]?.run();+ await requests[1]?.run();++ await expect(first).resolves.toBe('quarantine:scope-1');+ await expect(second).resolves.toBe('quarantine:scope-1');+ expect(localStorage.getItem(STORAGE_KEY)).toBe('quarantine:scope-1');+ });+});diff --git a/apps/web/src/lib/graphql-cache/scope.ts b/apps/web/src/lib/graphql-cache/scope.tsindex 8a901cd7a8..8290b8d53f 100644--- a/apps/web/src/lib/graphql-cache/scope.ts+++ b/apps/web/src/lib/graphql-cache/scope.ts@@ -1,32 +1,95 @@/**- * Cache scope: an anonymous, client-generated uuid naming the local cache- * storage (IndexedDB database). Deliberately NOT derived from user identity:+ * Cache scope: an anonymous, client-generated token naming the local Turso+ * cache in OPFS. Deliberately NOT derived from user identity:** - construction is synchronous and works offline (no identity waterfall);- * - no PII leaks into enumerable storage metadata (database names);+ * - no PII leaks into enumerable storage metadata (OPFS filenames);* - user↔cache consistency is enforced *inside* the cache by the identity* witness (`QueryRoot.user.id` observed on every write): a response for a* different user than the one bound to the cache wipes and rebinds it* (silent restart). See the design doc and cache-core `identity_witness`.*- * The uuid is stable for the browser profile; identity changes normally rotate- * the cache *contents*. A failed logout wipe rotates the scope as a quarantine.+ * The scope is stable for the browser profile and maps to one Turso/OPFS+ * database identity. Identity changes reset that database's contents. Scope+ * replacement is serialized across tabs so a stale transport failure cannot+ * overwrite a newer logout rotation.*/const SCOPE_STORAGE_KEY = 'graphql-cache:scope';+const SCOPE_STORAGE_LOCK = 'graphql-cache:scope-storage';+const quarantineScopeFor = (scope: string): string => `quarantine:${scope}`;-/** Quarantines a cache whose durable logout wipe could not be confirmed. */-export function rotateCacheScope(): void {- const scope = crypto.randomUUID();+type ScopeStorageAction = () => string | undefined;++/** Serializes scope compare/set whenever Web Locks are supported. */+async function withScopeStorageLock(+ action: ScopeStorageAction+): Promise<string | undefined> {+ let locks: LockManager | undefined;try {- localStorage.setItem(SCOPE_STORAGE_KEY, scope);+ locks = typeof navigator === 'undefined' ? undefined : navigator.locks;} catch {+ return undefined;+ }+ if (!locks || typeof locks.request !== 'function') {try {- localStorage.removeItem(SCOPE_STORAGE_KEY);+ return action();} catch {- // Inaccessible storage already makes the current scope session-only.+ return undefined;}}+ try {+ return await locks.request(SCOPE_STORAGE_LOCK, { mode: 'exclusive' }, () =>+ action()+ );+ } catch {+ // Never perform an unserialized fallback on a platform advertising locks.+ return undefined;+ }+}++/**+ * Conditionally quarantines one uncertain transport scope.+ *+ * Simultaneous failures for the same scope converge on one deterministic+ * replacement. The compare and set run under the same cross-tab lock as+ * logout rotation, so a stale host cannot overwrite a newer unrelated scope.+ */+export async function quarantineCacheScope(+ expectedScope: string+): Promise<string | undefined> {+ const replacement = quarantineScopeFor(expectedScope);+ return await withScopeStorageLock(() => {+ try {+ const current = localStorage.getItem(SCOPE_STORAGE_KEY);+ if (current === expectedScope) {+ localStorage.setItem(SCOPE_STORAGE_KEY, replacement);+ return replacement;+ }+ return current === replacement ? replacement : undefined;+ } catch {+ // Without a trustworthy compare, retaining the persisted value is safer.+ return undefined;+ }+ });+}++/** Quarantines a cache whose durable logout wipe could not be confirmed. */+export async function rotateCacheScope(): Promise<string | undefined> {+ return await withScopeStorageLock(() => {+ try {+ const scope = crypto.randomUUID();+ localStorage.setItem(SCOPE_STORAGE_KEY, scope);+ return scope;+ } catch {+ try {+ localStorage.removeItem(SCOPE_STORAGE_KEY);+ } catch {+ // Inaccessible storage already makes the current scope session-only.+ }+ return undefined;+ }+ });}export function getOrCreateCacheScope(): string {diff --git a/apps/web/src/lib/graphql-cache/telemetry-otel.test.ts b/apps/web/src/lib/graphql-cache/telemetry-otel.test.tsnew file mode 100644index 0000000000..4420345ba6--- /dev/null+++ b/apps/web/src/lib/graphql-cache/telemetry-otel.test.ts@@ -0,0 +1,72 @@+import { beforeEach, describe, expect, it, vi } from 'vitest';++const span = vi.hoisted(() => ({ setAttr: vi.fn(), end: vi.fn() }));+const anonymousSpan = vi.hoisted(() => vi.fn(() => span));++vi.mock('@macro-inc/observability', () => ({+ Telemetry: { anonymousSpan },+}));++import { createOtelCacheTelemetrySink } from './telemetry-otel';++describe('cache OpenTelemetry sink', () => {+ beforeEach(() => {+ vi.clearAllMocks();+ });++ it('uses anonymous fixed-name spans and only schema attributes', () => {+ createOtelCacheTelemetrySink().emit({+ browserFamily: 'firefox',+ browserVersion: '151',+ appVersion: '0.1',+ backend: 'turso-wasm-opfs',+ rolloutCohort: 'treatment',+ name: 'graphql_cache.transaction',+ operationCategory: 'transaction',+ outcome: 'error',+ errorCode: 'opfs-quota',+ openOutcome: 'reset-corrupt',+ queueDiagnosticsAvailability: 'available',+ resetAttempt: 'wipe-before-open',+ queueDepth: 4,+ oldestAgeMs: 25,+ durationMs: 12,+ });++ expect(anonymousSpan).toHaveBeenCalledWith('graphql_cache.transaction');+ expect(Object.fromEntries(span.setAttr.mock.calls)).toEqual({+ 'cache.browser_family': 'firefox',+ 'cache.browser_version': '151',+ 'cache.app_version': '0.1',+ 'cache.backend': 'turso-wasm-opfs',+ 'cache.rollout_cohort': 'treatment',+ 'cache.operation_category': 'transaction',+ 'cache.outcome': 'error',+ 'cache.error_code': 'opfs-quota',+ 'cache.open_outcome': 'reset-corrupt',+ 'cache.queue_diagnostics_availability': 'available',+ 'cache.reset_attempt': 'wipe-before-open',+ 'cache.duration_ms': 12,+ 'cache.queue_depth': 4,+ 'cache.oldest_age_ms': 25,+ });+ expect(span.end).toHaveBeenCalledOnce();+ });++ it('isolates Telemetry failures', () => {+ anonymousSpan.mockImplementationOnce(() => {+ throw new Error('provider unavailable');+ });+ expect(() =>+ createOtelCacheTelemetrySink().emit({+ browserFamily: 'other',+ browserVersion: 'unknown',+ appVersion: 'unknown',+ backend: 'turso-wasm-opfs',+ rolloutCohort: 'unknown',+ name: 'graphql_cache.db_ready',+ operationCategory: 'initialization',+ })+ ).not.toThrow();+ });+});diff --git a/apps/web/src/lib/graphql-cache/telemetry-otel.ts b/apps/web/src/lib/graphql-cache/telemetry-otel.tsnew file mode 100644index 0000000000..2c5ec32d01--- /dev/null+++ b/apps/web/src/lib/graphql-cache/telemetry-otel.ts@@ -0,0 +1,82 @@+import { Telemetry } from '@macro-inc/observability';+import type { CacheTelemetryEnvelope, CacheTelemetrySink } from './telemetry';++/**+ * Privacy-safe OpenTelemetry adapter. It uses the anonymous span API so the+ * browser provider cannot enrich cache metrics with `usr.id`.+ */+export function createOtelCacheTelemetrySink(): CacheTelemetrySink {+ return {+ emit(event: CacheTelemetryEnvelope): void {+ try {+ const span = Telemetry.anonymousSpan(event.name);+ span.setAttr('cache.browser_family', event.browserFamily);+ span.setAttr('cache.browser_version', event.browserVersion);+ span.setAttr('cache.app_version', event.appVersion);+ span.setAttr('cache.backend', event.backend);+ span.setAttr('cache.rollout_cohort', event.rolloutCohort);+ span.setAttr('cache.operation_category', event.operationCategory);+ if (event.aggregatedEventName !== undefined) {+ span.setAttr(+ 'cache.aggregated_event_name',+ event.aggregatedEventName+ );+ }+ if (event.outcome !== undefined) {+ span.setAttr('cache.outcome', event.outcome);+ }+ if (event.errorCode !== undefined) {+ span.setAttr('cache.error_code', event.errorCode);+ }+ if (event.resetReason !== undefined) {+ span.setAttr('cache.reset_reason', event.resetReason);+ }+ if (event.ownerEvent !== undefined) {+ span.setAttr('cache.owner_event', event.ownerEvent);+ }+ if (event.persistence !== undefined) {+ span.setAttr('cache.persistence', event.persistence);+ }+ if (event.openOutcome !== undefined) {+ span.setAttr('cache.open_outcome', event.openOutcome);+ }+ if (event.queueDiagnosticsAvailability !== undefined) {+ span.setAttr(+ 'cache.queue_diagnostics_availability',+ event.queueDiagnosticsAvailability+ );+ }+ if (event.resetAttempt !== undefined) {+ span.setAttr('cache.reset_attempt', event.resetAttempt);+ }+ if (event.durationMs !== undefined) {+ span.setAttr('cache.duration_ms', event.durationMs);+ }+ if (event.bytes !== undefined) span.setAttr('cache.bytes', event.bytes);+ if (event.highWaterBytes !== undefined) {+ span.setAttr('cache.high_water_bytes', event.highWaterBytes);+ }+ if (event.usageBytes !== undefined) {+ span.setAttr('cache.usage_bytes', event.usageBytes);+ }+ if (event.quotaBytes !== undefined) {+ span.setAttr('cache.quota_bytes', event.quotaBytes);+ }+ if (event.ratio !== undefined) span.setAttr('cache.ratio', event.ratio);+ if (event.count !== undefined) span.setAttr('cache.count', event.count);+ if (event.sampleRate !== undefined) {+ span.setAttr('cache.sample_rate', event.sampleRate);+ }+ if (event.queueDepth !== undefined) {+ span.setAttr('cache.queue_depth', event.queueDepth);+ }+ if (event.oldestAgeMs !== undefined) {+ span.setAttr('cache.oldest_age_ms', event.oldestAgeMs);+ }+ span.end();+ } catch {+ // OTel availability and exporter failures never affect cache behavior.+ }+ },+ };+}diff --git a/apps/web/src/lib/graphql-cache/telemetry-relay.test.ts b/apps/web/src/lib/graphql-cache/telemetry-relay.test.tsnew file mode 100644index 0000000000..b6f00962e7--- /dev/null+++ b/apps/web/src/lib/graphql-cache/telemetry-relay.test.ts@@ -0,0 +1,119 @@+import { describe, expect, it, vi } from 'vitest';+import {+ browserCacheTelemetryContext,+ type CacheTelemetryEnvelope,+ CacheTelemetryReporter,+} from './telemetry';+import {+ CacheTelemetryRelay,+ createPageCacheTelemetry,+} from './telemetry-relay';++class FakeChannel {+ onmessage: ((event: MessageEvent<unknown>) => void) | null = null;+ onmessageerror: (() => void) | null = null;+ closed = false;+ postMessage(): void {}+ close(): void {+ this.closed = true;+ }+ receive(data: unknown): void {+ this.onmessage?.({ data } as MessageEvent<unknown>);+ }+}++describe('cache telemetry worker relay', () => {+ it('uses one scope-free reporter lock and forwards only validated observations', async () => {+ const channel = new FakeChannel();+ const events: CacheTelemetryEnvelope[] = [];+ let lockName = '';+ let lockCallback: ((lock: Lock | null) => Promise<void> | void) | undefined;+ const lockManager = {+ request: vi.fn(+ async (+ name: string,+ _options: LockOptions,+ callback: (lock: Lock | null) => Promise<void> | void+ ) => {+ lockName = name;+ lockCallback = callback;+ }+ ),+ } as unknown as Pick<LockManager, 'request'>;+ const { relay } = createPageCacheTelemetry({+ rolloutCohort: 'treatment',+ sink: { emit: (event) => events.push(event) },+ relay: {+ createChannel: () => channel as unknown as BroadcastChannel,+ lockManager,+ },+ });++ relay.start();+ await Promise.resolve();+ expect(lockName).toBe('macro:graphql-cache-telemetry-reporter:v1');+ const leadership = lockCallback?.({+ name: lockName,+ mode: 'exclusive',+ } as Lock);+ await Promise.resolve();+ channel.receive({+ name: 'graphql_cache.owner',+ operationCategory: 'lifecycle',+ ownerEvent: 'elected',+ scope: 'must-not-pass',+ });+ channel.receive({+ name: 'graphql_cache.owner',+ operationCategory: 'lifecycle',+ ownerEvent: 'elected',+ });++ expect(events).toHaveLength(1);+ expect(events[0]).toMatchObject({+ rolloutCohort: 'unknown',+ appVersion: 'unknown',+ });+ expect(JSON.stringify(events)).not.toContain('must-not-pass');+ relay.dispose();+ await leadership;+ expect(channel.closed).toBe(true);+ });++ it('isolates channel failures', () => {+ const relay = new CacheTelemetryRelay(+ new CacheTelemetryReporter(browserCacheTelemetryContext('unknown'), {+ emit: () => undefined,+ }),+ {+ createChannel: () => {+ throw new Error('channel unavailable');+ },+ }+ );++ expect(() => relay.start()).not.toThrow();+ expect(() => relay.dispose()).not.toThrow();+ });++ it('isolates lock failures after creating the channel', () => {+ const channel = new FakeChannel();+ const relay = new CacheTelemetryRelay(+ new CacheTelemetryReporter(browserCacheTelemetryContext('unknown'), {+ emit: () => undefined,+ }),+ {+ createChannel: () => channel as unknown as BroadcastChannel,+ lockManager: {+ request: () => {+ throw new Error('lock unavailable');+ },+ } as unknown as Pick<LockManager, 'request'>,+ }+ );++ expect(() => relay.start()).not.toThrow();+ expect(() => relay.dispose()).not.toThrow();+ expect(channel.closed).toBe(true);+ });+});diff --git a/apps/web/src/lib/graphql-cache/telemetry-relay.ts b/apps/web/src/lib/graphql-cache/telemetry-relay.tsnew file mode 100644index 0000000000..b5d7517c62--- /dev/null+++ b/apps/web/src/lib/graphql-cache/telemetry-relay.ts@@ -0,0 +1,157 @@+import {+ browserCacheTelemetryContext,+ type CacheRolloutCohort,+ CacheTelemetryRecorder,+ type CacheTelemetryRecorderLike,+ CacheTelemetryReporter,+ type CacheTelemetrySink,+ isCacheTelemetryObservation,+} from './telemetry';+import { createOtelCacheTelemetrySink } from './telemetry-otel';++const CACHE_TELEMETRY_CHANNEL = 'macro:graphql-cache-telemetry:v1';+const CACHE_TELEMETRY_REPORTER_LOCK =+ 'macro:graphql-cache-telemetry-reporter:v1';++type BroadcastChannelLike = Pick<+ BroadcastChannel,+ 'postMessage' | 'close' | 'onmessage' | 'onmessageerror'+>;++export interface CacheTelemetryRelayOptions {+ createChannel?: (name: string) => BroadcastChannelLike;+ lockManager?: Pick<LockManager, 'request'>;+}++/**+ * Relays typed worker observations through exactly one live browser page.+ * Leadership is a fixed, scope-free Web Lock; no cache or identity key crosses+ * the telemetry channel.+ */+export class CacheTelemetryRelay {+ private channel: BroadcastChannelLike | undefined;+ private abortController: AbortController | undefined;+ private releaseLeadership: (() => void) | undefined;+ private leader = false;+ private started = false;+ private disposed = false;++ constructor(+ private readonly reporter: CacheTelemetryReporter,+ private readonly options: CacheTelemetryRelayOptions = {}+ ) {}++ start(): void {+ if (this.started || this.disposed) return;+ this.started = true;+ try {+ const createChannel =+ this.options.createChannel ??+ ((name: string) => new BroadcastChannel(name));+ this.channel = createChannel(CACHE_TELEMETRY_CHANNEL);+ this.channel.onmessage = (event: MessageEvent<unknown>) => {+ if (this.leader && isCacheTelemetryObservation(event.data)) {+ this.reporter.emit(event.data);+ }+ };+ this.channel.onmessageerror = () => undefined;+ } catch {+ this.channel = undefined;+ return;+ }++ const locks =+ this.options.lockManager ??+ (typeof navigator === 'undefined' ? undefined : navigator.locks);+ if (!locks) return;+ const abortController = new AbortController();+ this.abortController = abortController;+ const held = new Promise<void>((resolve) => {+ this.releaseLeadership = resolve;+ });+ try {+ void locks+ .request(+ CACHE_TELEMETRY_REPORTER_LOCK,+ { mode: 'exclusive', signal: abortController.signal },+ async (lock) => {+ if (!lock || this.disposed) return;+ this.leader = true;+ try {+ await held;+ } finally {+ this.leader = false;+ }+ }+ )+ .catch(() => undefined);+ } catch {+ // A relay failure only drops worker-originated telemetry.+ }+ }++ dispose(): void {+ if (this.disposed) return;+ this.disposed = true;+ this.leader = false;+ try {+ this.releaseLeadership?.();+ this.abortController?.abort();+ if (this.channel) {+ this.channel.onmessage = null;+ this.channel.onmessageerror = null;+ this.channel.close();+ }+ } catch {+ // Lifecycle cleanup remains best-effort and exception-isolated.+ }+ this.channel = undefined;+ }+}++/** Page recorder + worker relay, backed by anonymous OpenTelemetry spans. */+export function createPageCacheTelemetry(options: {+ rolloutCohort: CacheRolloutCohort;+ sink?: CacheTelemetrySink;+ relay?: CacheTelemetryRelayOptions;+}): {+ recorder: CacheTelemetryRecorderLike;+ relay: CacheTelemetryRelay;+} {+ const sink = options.sink ?? createOtelCacheTelemetrySink();+ const pageReporter = new CacheTelemetryReporter(+ browserCacheTelemetryContext(options.rolloutCohort),+ sink+ );+ // Worker observations carry no activation context over the scope-free+ // channel, so they must never inherit whichever page won relay leadership.+ const workerReporter = new CacheTelemetryReporter(+ {+ ...browserCacheTelemetryContext('unknown'),+ appVersion: 'unknown',+ },+ sink+ );+ return {+ recorder: new CacheTelemetryRecorder(pageReporter),+ relay: new CacheTelemetryRelay(workerReporter, options.relay),+ };+}++let workerRecorder: CacheTelemetryRecorderLike | undefined;+let workerChannel: BroadcastChannelLike | undefined;++/** Lazy worker recorder. Constructing/importing it creates no worker/channel. */+export function workerCacheTelemetry(): CacheTelemetryRecorderLike {+ workerRecorder ??= new CacheTelemetryRecorder({+ emit(observation): void {+ try {+ workerChannel ??= new BroadcastChannel(CACHE_TELEMETRY_CHANNEL);+ workerChannel.postMessage(observation);+ } catch {+ // Missing/failed BroadcastChannel only drops this observation.+ }+ },+ });+ return workerRecorder;+}diff --git a/apps/web/src/lib/graphql-cache/telemetry.test.ts b/apps/web/src/lib/graphql-cache/telemetry.test.tsnew file mode 100644index 0000000000..192a9bb8fa--- /dev/null+++ b/apps/web/src/lib/graphql-cache/telemetry.test.ts@@ -0,0 +1,380 @@+import { describe, expect, it } from 'vitest';+import {+ browserCacheTelemetryContext,+ type CacheTelemetryEnvelope,+ type CacheTelemetryObservation,+ CacheTelemetryRecorder,+ CacheTelemetryReporter,+ classifyCacheError,+ isCacheTelemetryObservation,+ isolateCacheTelemetry,+ operationCategoryForRequest,+ resetReasonForError,+} from './telemetry';++describe('cache telemetry privacy contract', () => {+ it('exports only fixed names, classifications, measurements, and allowlisted dimensions', () => {+ const events: CacheTelemetryEnvelope[] = [];+ const reporter = new CacheTelemetryReporter(+ browserCacheTelemetryContext(+ 'treatment',+ 'Mozilla/5.0 Firefox/151.0 secret-user-fragment',+ '0.1.0+abc123'+ ),+ { emit: (event) => events.push(event) }+ );+ const hostile = {+ name: 'graphql_cache.host_request',+ operationCategory: 'read',+ outcome: 'hit',+ durationMs: 4,+ scope: 'scope-secret',+ entityId: 'doc-secret',+ userId: 'user-secret',+ query: 'query Secret { document(id: "doc-secret") { id } }',+ variables: { token: 'secret-token' },+ result: { private: true },+ } as unknown as CacheTelemetryObservation;++ reporter.emit(hostile);++ expect(events).toEqual([+ {+ browserFamily: 'firefox',+ browserVersion: '151',+ appVersion: '0.1',+ backend: 'turso-wasm-opfs',+ rolloutCohort: 'treatment',+ name: 'graphql_cache.host_request',+ operationCategory: 'read',+ outcome: 'hit',+ durationMs: 4,+ },+ ]);+ const serialized = JSON.stringify(events);+ for (const forbidden of [+ 'scope-secret',+ 'doc-secret',+ 'user-secret',+ 'query Secret',+ 'secret-token',+ 'private',+ ]) {+ expect(serialized).not.toContain(forbidden);+ }+ });++ it('exports queue diagnostics and open outcomes without IDs or payloads', () => {+ const events: CacheTelemetryEnvelope[] = [];+ const reporter = new CacheTelemetryReporter(+ browserCacheTelemetryContext('treatment'),+ { emit: (event) => events.push(event) }+ );+ reporter.emit({+ name: 'graphql_cache.queue_diagnostics',+ operationCategory: 'queue',+ outcome: 'success',+ errorCode: 'none',+ openOutcome: 'reset-corrupt',+ queueDiagnosticsAvailability: 'available',+ resetAttempt: 'wipe-before-open',+ queueDepth: 3,+ oldestAgeMs: 42,+ scope: 'private-scope',+ mutationId: 'private-mutation',+ query: 'mutation Private { private }',+ } as unknown as CacheTelemetryObservation);++ expect(events).toEqual([+ expect.objectContaining({+ name: 'graphql_cache.queue_diagnostics',+ openOutcome: 'reset-corrupt',+ queueDiagnosticsAvailability: 'available',+ resetAttempt: 'wipe-before-open',+ queueDepth: 3,+ oldestAgeMs: 42,+ }),+ ]);+ expect(JSON.stringify(events)).not.toMatch(+ /private-scope|private-mutation|mutation Private/+ );+ });++ it('rejects relay payloads with unknown fields or ad-hoc names', () => {+ expect(+ isCacheTelemetryObservation({+ name: 'graphql_cache.read',+ operationCategory: 'read',+ outcome: 'miss',+ })+ ).toBe(true);+ expect(+ isCacheTelemetryObservation({+ name: 'graphql_cache.read',+ operationCategory: 'read',+ query: '{ secret }',+ })+ ).toBe(false);+ expect(+ isCacheTelemetryObservation({+ name: 'graphql_cache.dynamic.secret',+ operationCategory: 'read',+ })+ ).toBe(false);+ });++ it('uses a payload-free exhaustive error taxonomy', () => {+ expect(classifyCacheError(new Error('OPFS quota full: doc-123'))).toBe(+ 'opfs-quota'+ );+ expect(classifyCacheError(new Error('owner epoch 3 was lost'))).toBe(+ 'owner-lost'+ );+ expect(classifyCacheError(new Error('corrupt postcard for User:1'))).toBe(+ 'integrity'+ );+ expect(resetReasonForError(new Error('namespace mismatch: private'))).toBe(+ 'namespace-mismatch'+ );+ expect(classifyCacheError({ private: 'not stringified' })).toBe('unknown');+ });++ it('maps every request kind to an allowlisted operation category', () => {+ const cases = {+ init: 'initialization',+ read: 'read',+ 'read-records': 'read',+ write: 'write',+ 'enqueue-optimistic-mutation': 'transaction',+ 'inspect-query-variants': 'inspection',+ 'inspect-query': 'inspection',+ 'claim-next-mutation': 'transaction',+ 'defer-optimistic-write': 'transaction',+ 'commit-optimistic-write': 'transaction',+ 'rollback-optimistic-write': 'transaction',+ invalidate: 'invalidation',+ 'delete-records': 'invalidation',+ teardown: 'lifecycle',+ clear: 'lifecycle',+ } as const;++ for (const [kind, expected] of Object.entries(cases)) {+ expect(operationCategoryForRequest({ kind } as never)).toBe(expected);+ }+ });+});++describe('cache telemetry sampling and failure isolation', () => {+ it('uses weighted aggregates, independent event sampling, and unsampled errors', () => {+ const observations: CacheTelemetryObservation[] = [];+ const recorder = new CacheTelemetryRecorder(+ { emit: (event) => observations.push(event) },+ 10,+ 100+ );+ recorder.record({+ name: 'graphql_cache.read',+ operationCategory: 'read',+ outcome: 'hit',+ durationMs: 10,+ count: 2,+ });+ recorder.record({+ name: 'graphql_cache.read',+ operationCategory: 'read',+ outcome: 'hit',+ durationMs: 20,+ count: 3,+ });+ for (let index = 0; index < 10; index++) {+ for (const outcome of ['hit', 'miss'] as const) {+ recorder.record({+ name: 'graphql_cache.read',+ operationCategory: 'read',+ outcome,+ durationMs: index,+ });+ }+ }+ recorder.record({+ name: 'graphql_cache.transaction',+ operationCategory: 'transaction',+ outcome: 'error',+ errorCode: 'opfs-io',+ });+ recorder.flush();++ const hitAggregate = observations.find(+ (event) =>+ event.name === 'graphql_cache.aggregate' && event.outcome === 'hit'+ );+ expect(hitAggregate).toMatchObject({+ aggregatedEventName: 'graphql_cache.read',+ count: 15,+ durationMs: 8.333333333333334,+ sampleRate: 1,+ });+ expect(+ observations.filter(+ (event) =>+ event.name === 'graphql_cache.read' && event.sampleRate === 10+ )+ ).toHaveLength(2);+ expect(+ observations.find((event) => event.name === 'graphql_cache.transaction')+ ).toMatchObject({ outcome: 'error', sampleRate: 1 });+ expect(+ observations.filter(+ (event) =>+ event.name === 'graphql_cache.aggregate' &&+ event.aggregatedEventName === 'graphql_cache.transaction'+ )+ ).toEqual([]);+ });++ it('flushes matching pending successes before each raw error', () => {+ const observations: CacheTelemetryObservation[] = [];+ const recorder = new CacheTelemetryRecorder({+ emit: (event) => observations.push(event),+ });+ for (let index = 0; index < 149; index++) {+ recorder.record({+ name: 'graphql_cache.transaction',+ operationCategory: 'transaction',+ outcome: 'success',+ });+ }+ for (let index = 0; index < 2; index++) {+ recorder.record({+ name: 'graphql_cache.transaction',+ operationCategory: 'transaction',+ outcome: 'error',+ errorCode: 'opfs-io',+ });+ }++ const aggregates = observations.filter(+ (event) =>+ event.name === 'graphql_cache.aggregate' &&+ event.aggregatedEventName === 'graphql_cache.transaction'+ );+ expect(+ aggregates.reduce((total, event) => total + (event.count ?? 0), 0)+ ).toBe(149);+ const firstErrorIndex = observations.findIndex(+ (event) =>+ event.name === 'graphql_cache.transaction' && event.outcome === 'error'+ );+ expect(observations[firstErrorIndex - 1]).toMatchObject({+ name: 'graphql_cache.aggregate',+ count: 49,+ });+ expect(+ observations.filter(+ (event) =>+ event.name === 'graphql_cache.transaction' &&+ event.outcome === 'error' &&+ event.sampleRate === 1+ )+ ).toHaveLength(2);+ });++ it('never lets a throwing sink or injected recorder change the caller outcome', () => {+ const recorder = new CacheTelemetryRecorder({+ emit: () => {+ throw new Error('exporter secret failure');+ },+ });+ const reporter = new CacheTelemetryReporter(+ browserCacheTelemetryContext('unknown'),+ {+ emit: () => {+ throw new Error('otel down');+ },+ }+ );++ expect(() =>+ recorder.record({+ name: 'graphql_cache.db_ready',+ operationCategory: 'initialization',+ outcome: 'success',+ })+ ).not.toThrow();+ expect(() =>+ reporter.emit({+ name: 'graphql_cache.reset_wipe',+ operationCategory: 'storage',+ outcome: 'error',+ })+ ).not.toThrow();+ expect(() => recorder.flush()).not.toThrow();++ const injected = isolateCacheTelemetry({+ record: () => {+ throw new Error('injected record failed');+ },+ flush: () => {+ throw new Error('injected flush failed');+ },+ });+ expect(() =>+ injected.record({+ name: 'graphql_cache.owner',+ operationCategory: 'lifecycle',+ })+ ).not.toThrow();+ expect(() => injected.flush()).not.toThrow();+ });++ it('bounds invalid numbers and unsafe runtime dimensions', () => {+ const events: CacheTelemetryEnvelope[] = [];+ const reporter = new CacheTelemetryReporter(+ browserCacheTelemetryContext(+ 'override',+ 'Mozilla/5.0 Chrome/145.0.7632.6',+ '[email protected]/private'+ ),+ { emit: (event) => events.push(event) }+ );+ reporter.emit({+ name: 'graphql_cache.origin_storage_pressure',+ operationCategory: 'storage',+ usageBytes: -1,+ quotaBytes: Number.POSITIVE_INFINITY,+ ratio: 7,+ });++ expect(events[0]).toMatchObject({+ browserFamily: 'chromium',+ browserVersion: '145',+ appVersion: 'unknown',+ ratio: 1,+ });+ expect(events[0]).not.toHaveProperty('usageBytes');+ expect(events[0]).not.toHaveProperty('quotaBytes');++ const hostileContextEvents: CacheTelemetryEnvelope[] = [];+ new CacheTelemetryReporter(+ {+ browserFamily: 'private-user' as never,+ browserVersion: '151.0 user-secret',+ appVersion: '[email protected]',+ backend: 'private-backend' as never,+ rolloutCohort: 'private-cohort' as never,+ },+ { emit: (event) => hostileContextEvents.push(event) }+ ).emit({+ name: 'graphql_cache.owner',+ operationCategory: 'lifecycle',+ });+ expect(hostileContextEvents[0]).toMatchObject({+ browserFamily: 'other',+ browserVersion: 'unknown',+ appVersion: 'unknown',+ backend: 'turso-wasm-opfs',+ rolloutCohort: 'unknown',+ });+ expect(JSON.stringify(hostileContextEvents)).not.toContain('private');+ });+});diff --git a/apps/web/src/lib/graphql-cache/telemetry.ts b/apps/web/src/lib/graphql-cache/telemetry.tsnew file mode 100644index 0000000000..b0d94111d3--- /dev/null+++ b/apps/web/src/lib/graphql-cache/telemetry.ts@@ -0,0 +1,620 @@+import { match } from 'ts-pattern';+import type { CacheRequest } from './protocol';++/** Fixed cache telemetry names. Dashboards must not accept ad-hoc names. */+export const CACHE_TELEMETRY_EVENT_NAMES = [+ 'graphql_cache.wasm_download',+ 'graphql_cache.wasm_compile',+ 'graphql_cache.wasm_instantiate',+ 'graphql_cache.schema_init',+ 'graphql_cache.db_ready',+ 'graphql_cache.host_ready',+ 'graphql_cache.host_request',+ 'graphql_cache.coordinator_request',+ 'graphql_cache.engine_request',+ 'graphql_cache.transaction',+ 'graphql_cache.read',+ 'graphql_cache.owner',+ 'graphql_cache.stale_drop',+ 'graphql_cache.lock_wait',+ 'graphql_cache.storage_reset_required',+ 'graphql_cache.logical_reset',+ 'graphql_cache.reset_wipe',+ 'graphql_cache.origin_storage_pressure',+ 'graphql_cache.linear_memory',+ 'graphql_cache.queue_diagnostics',+ 'graphql_cache.navigation',+ 'graphql_cache.aggregate',+] as const;++export type CacheTelemetryEventName =+ (typeof CACHE_TELEMETRY_EVENT_NAMES)[number];++export const CACHE_OPERATION_CATEGORIES = [+ 'initialization',+ 'read',+ 'write',+ 'transaction',+ 'queue',+ 'inspection',+ 'invalidation',+ 'lifecycle',+ 'storage',+ 'navigation',+ 'unknown',+] as const;+export type CacheOperationCategory =+ (typeof CACHE_OPERATION_CATEGORIES)[number];++export const CACHE_TELEMETRY_OUTCOMES = [+ 'success',+ 'error',+ 'hit',+ 'miss',+ 'graceful',+ 'abrupt',+ 'granted',+ 'denied',+ 'unknown',+] as const;+export type CacheTelemetryOutcome = (typeof CACHE_TELEMETRY_OUTCOMES)[number];++export const CACHE_OPEN_OUTCOMES = [+ 'opened-existing',+ 'opened-new',+ 'reset-incompatible',+ 'reset-corrupt',+ 'reset-storage-uncertain',+] as const;+export type CacheOpenOutcome = (typeof CACHE_OPEN_OUTCOMES)[number];++export const CACHE_QUEUE_DIAGNOSTICS_AVAILABILITY = [+ 'available',+ 'unavailable',+] as const;+export type CacheQueueDiagnosticsAvailability =+ (typeof CACHE_QUEUE_DIAGNOSTICS_AVAILABILITY)[number];++/** Payload-free, bounded error classes shared by all cache layers. */+export const CACHE_ERROR_CODES = [+ 'none',+ 'unsupported',+ 'timeout',+ 'wasm-download',+ 'wasm-compile',+ 'wasm-instantiate',+ 'schema',+ 'integrity',+ 'opfs-unavailable',+ 'opfs-quota',+ 'opfs-io',+ 'lock',+ 'owner-lost',+ 'protocol',+ 'transport',+ 'storage-reset',+ 'initialization',+ 'unknown',+] as const;+export type CacheErrorCode = (typeof CACHE_ERROR_CODES)[number];++export const CACHE_RESET_REASONS = [+ 'explicit-clear',+ 'identity-change',+ 'namespace-mismatch',+ 'integrity-failure',+ 'storage-reset-required',+ 'abrupt-owner-loss',+ 'storage-eviction',+ 'quota-failure',+ 'unknown',+] as const;+export type CacheResetReason = (typeof CACHE_RESET_REASONS)[number];++export const CACHE_OWNER_EVENTS = [+ 'elected',+ 'activated',+ 'graceful-drain-started',+ 'graceful-drain-completed',+ 'abrupt-loss',+ 'replacement',+ 'multiple-owner-detected',+] as const;+export type CacheOwnerEvent = (typeof CACHE_OWNER_EVENTS)[number];++export const CACHE_ROLLOUT_COHORTS = [+ 'control',+ 'treatment',+ 'override',+ 'unknown',+] as const;+export type CacheRolloutCohort = (typeof CACHE_ROLLOUT_COHORTS)[number];++export type CacheTelemetryObservation = {+ name: CacheTelemetryEventName;+ /** Original fixed event name represented by an aggregate envelope. */+ aggregatedEventName?: CacheTelemetryEventName;+ operationCategory: CacheOperationCategory;+ outcome?: CacheTelemetryOutcome;+ errorCode?: CacheErrorCode;+ resetReason?: CacheResetReason;+ ownerEvent?: CacheOwnerEvent;+ persistence?: 'granted' | 'denied' | 'unknown';+ openOutcome?: CacheOpenOutcome;+ queueDiagnosticsAvailability?: CacheQueueDiagnosticsAvailability;+ resetAttempt?: 'wipe-before-open';+ durationMs?: number;+ bytes?: number;+ highWaterBytes?: number;+ usageBytes?: number;+ quotaBytes?: number;+ ratio?: number;+ count?: number;+ sampleRate?: number;+ queueDepth?: number;+ oldestAgeMs?: number;+};++/** The only cohort/browser/backend dimensions permitted on exported events. */+export type CacheTelemetryContext = {+ browserFamily: 'chromium' | 'firefox' | 'safari' | 'other';+ browserVersion: string;+ appVersion: string;+ backend: 'turso-wasm-opfs';+ rolloutCohort: CacheRolloutCohort;+};++export type CacheTelemetryEnvelope = Readonly<+ CacheTelemetryContext & CacheTelemetryObservation+>;++export interface CacheTelemetryObservationSink {+ emit(observation: CacheTelemetryObservation): void;+}++export interface CacheTelemetrySink {+ emit(event: CacheTelemetryEnvelope): void;+}++export interface CacheTelemetryRecorderLike {+ record(observation: CacheTelemetryObservation): void;+ flush(): void;+}++const HIGH_VOLUME_NAMES = new Set<CacheTelemetryEventName>([+ 'graphql_cache.host_request',+ 'graphql_cache.coordinator_request',+ 'graphql_cache.engine_request',+ 'graphql_cache.transaction',+ 'graphql_cache.read',+]);++const boundedNumber = (+ value: number | undefined,+ maximum = Number.MAX_SAFE_INTEGER+): number | undefined =>+ value !== undefined && Number.isFinite(value) && value >= 0+ ? Math.min(value, maximum)+ : undefined;++function sanitizeObservation(+ input: CacheTelemetryObservation+): CacheTelemetryObservation | undefined {+ if (!CACHE_TELEMETRY_EVENT_NAMES.includes(input.name)) return;+ if (!CACHE_OPERATION_CATEGORIES.includes(input.operationCategory)) return;++ return {+ name: input.name,+ ...(input.name === 'graphql_cache.aggregate' &&+ input.aggregatedEventName !== undefined &&+ HIGH_VOLUME_NAMES.has(input.aggregatedEventName)+ ? { aggregatedEventName: input.aggregatedEventName }+ : {}),+ operationCategory: input.operationCategory,+ ...(input.outcome !== undefined &&+ CACHE_TELEMETRY_OUTCOMES.includes(input.outcome)+ ? { outcome: input.outcome }+ : {}),+ ...(input.errorCode !== undefined &&+ CACHE_ERROR_CODES.includes(input.errorCode)+ ? { errorCode: input.errorCode }+ : {}),+ ...(input.resetReason !== undefined &&+ CACHE_RESET_REASONS.includes(input.resetReason)+ ? { resetReason: input.resetReason }+ : {}),+ ...(input.ownerEvent !== undefined &&+ CACHE_OWNER_EVENTS.includes(input.ownerEvent)+ ? { ownerEvent: input.ownerEvent }+ : {}),+ ...(input.persistence === 'granted' ||+ input.persistence === 'denied' ||+ input.persistence === 'unknown'+ ? { persistence: input.persistence }+ : {}),+ ...(input.openOutcome !== undefined &&+ CACHE_OPEN_OUTCOMES.includes(input.openOutcome)+ ? { openOutcome: input.openOutcome }+ : {}),+ ...(input.queueDiagnosticsAvailability !== undefined &&+ CACHE_QUEUE_DIAGNOSTICS_AVAILABILITY.includes(+ input.queueDiagnosticsAvailability+ )+ ? {+ queueDiagnosticsAvailability: input.queueDiagnosticsAvailability,+ }+ : {}),+ ...(input.resetAttempt === 'wipe-before-open'+ ? { resetAttempt: input.resetAttempt }+ : {}),+ ...(boundedNumber(input.durationMs, 3_600_000) !== undefined+ ? { durationMs: boundedNumber(input.durationMs, 3_600_000) }+ : {}),+ ...(boundedNumber(input.bytes) !== undefined+ ? { bytes: boundedNumber(input.bytes) }+ : {}),+ ...(boundedNumber(input.highWaterBytes) !== undefined+ ? { highWaterBytes: boundedNumber(input.highWaterBytes) }+ : {}),+ ...(boundedNumber(input.usageBytes) !== undefined+ ? { usageBytes: boundedNumber(input.usageBytes) }+ : {}),+ ...(boundedNumber(input.quotaBytes) !== undefined+ ? { quotaBytes: boundedNumber(input.quotaBytes) }+ : {}),+ ...(boundedNumber(input.ratio, 1) !== undefined+ ? { ratio: boundedNumber(input.ratio, 1) }+ : {}),+ ...(boundedNumber(input.count) !== undefined+ ? { count: boundedNumber(input.count) }+ : {}),+ ...(boundedNumber(input.sampleRate) !== undefined+ ? { sampleRate: boundedNumber(input.sampleRate) }+ : {}),+ ...(boundedNumber(input.queueDepth) !== undefined+ ? { queueDepth: boundedNumber(input.queueDepth) }+ : {}),+ ...(boundedNumber(input.oldestAgeMs, 31_536_000_000) !== undefined+ ? { oldestAgeMs: boundedNumber(input.oldestAgeMs, 31_536_000_000) }+ : {}),+ };+}++type Aggregate = {+ template: CacheTelemetryObservation;+ count: number;+ totalDurationMs: number;+};++/**+ * Exception-isolated recorder. High-volume successes are counted in bounded+ * aggregates and sampled; every error remains individually visible.+ */+export class CacheTelemetryRecorder implements CacheTelemetryRecorderLike {+ private readonly sampleSequences = new Map<string, number>();+ private readonly aggregates = new Map<string, Aggregate>();++ constructor(+ private readonly sink: CacheTelemetryObservationSink,+ private readonly sampleRate = 100,+ private readonly aggregateEvery = 50+ ) {}++ record(input: CacheTelemetryObservation): void {+ try {+ const observation = sanitizeObservation(input);+ if (!observation) return;+ if (!HIGH_VOLUME_NAMES.has(observation.name)) {+ this.safeEmit(observation);+ return;+ }+ const isError =+ observation.outcome === 'error' ||+ observation.errorCode === 'owner-lost';+ if (isError) {+ // Make the denominator current before the raw error is observable.+ // Matching successes remain counted exactly once in aggregates.+ this.flushMatchingSuccesses(observation);+ this.safeEmit({ ...observation, sampleRate: 1 });+ return;+ }++ const key = JSON.stringify([+ observation.name,+ observation.operationCategory,+ observation.outcome ?? 'unknown',+ observation.errorCode ?? 'none',+ ]);+ const aggregate = this.aggregates.get(key) ?? {+ template: observation,+ count: 0,+ totalDurationMs: 0,+ };+ const weight = observation.count ?? 1;+ aggregate.count += weight;+ aggregate.totalDurationMs += (observation.durationMs ?? 0) * weight;+ this.aggregates.set(key, aggregate);+ if (aggregate.count >= this.aggregateEvery) this.flushOne(key, aggregate);++ const sampleSequence = (this.sampleSequences.get(key) ?? 0) + 1;+ this.sampleSequences.set(key, sampleSequence);+ const mustEmit =+ this.sampleRate <= 1 || sampleSequence % this.sampleRate === 0;+ if (mustEmit) {+ this.safeEmit({+ ...observation,+ sampleRate: this.sampleRate,+ });+ }+ } catch {+ // Telemetry is deliberately unable to affect cache correctness.+ }+ }++ flush(): void {+ try {+ for (const [key, aggregate] of this.aggregates) {+ this.flushOne(key, aggregate);+ }+ } catch {+ // A broken sink must not escape lifecycle cleanup.+ }+ }++ private flushMatchingSuccesses(error: CacheTelemetryObservation): void {+ for (const [key, aggregate] of this.aggregates) {+ if (aggregate.template.name === error.name) {+ this.flushOne(key, aggregate);+ }+ }+ }++ private flushOne(key: string, aggregate: Aggregate): void {+ this.aggregates.delete(key);+ const durationMs =+ aggregate.count > 0+ ? aggregate.totalDurationMs / aggregate.count+ : undefined;+ this.safeEmit({+ name: 'graphql_cache.aggregate',+ aggregatedEventName: aggregate.template.name,+ operationCategory: aggregate.template.operationCategory,+ outcome: aggregate.template.outcome,+ errorCode: aggregate.template.errorCode,+ count: aggregate.count,+ durationMs,+ sampleRate: 1,+ });+ }++ private safeEmit(observation: CacheTelemetryObservation): void {+ try {+ this.sink.emit(observation);+ } catch {+ // Failure isolation is part of the telemetry contract.+ }+ }+}++/** Adds allowlisted runtime dimensions and strips every unknown property. */+export class CacheTelemetryReporter implements CacheTelemetryObservationSink {+ private readonly context: CacheTelemetryContext;++ constructor(+ context: CacheTelemetryContext,+ private readonly sink: CacheTelemetrySink+ ) {+ this.context = {+ browserFamily: ['chromium', 'firefox', 'safari', 'other'].includes(+ context.browserFamily+ )+ ? context.browserFamily+ : 'other',+ browserVersion: /^\d{1,3}$/.test(context.browserVersion)+ ? context.browserVersion+ : 'unknown',+ appVersion: /^\d+\.\d+$/.test(context.appVersion)+ ? context.appVersion.slice(0, 16)+ : 'unknown',+ backend: 'turso-wasm-opfs',+ rolloutCohort: CACHE_ROLLOUT_COHORTS.includes(context.rolloutCohort)+ ? context.rolloutCohort+ : 'unknown',+ };+ }++ emit(input: CacheTelemetryObservation): void {+ try {+ const observation = sanitizeObservation(input);+ if (!observation) return;+ this.sink.emit(Object.freeze({ ...this.context, ...observation }));+ } catch {+ // Export failure cannot change request, transaction, or lifecycle state.+ }+ }+}++export const NOOP_CACHE_TELEMETRY: CacheTelemetryRecorderLike = Object.freeze({+ record: () => undefined,+ flush: () => undefined,+});++/** Wraps even an untrusted injected recorder in the correctness firewall. */+export function isolateCacheTelemetry(+ recorder: CacheTelemetryRecorderLike | undefined+): CacheTelemetryRecorderLike {+ if (!recorder) return NOOP_CACHE_TELEMETRY;+ return {+ record(observation): void {+ try {+ recorder.record(observation);+ } catch {+ // Injected sinks have the same failure-isolation contract as OTel.+ }+ },+ flush(): void {+ try {+ recorder.flush();+ } catch {+ // Cleanup remains independent from exporter behavior.+ }+ },+ };+}++export function operationCategoryForRequest(+ request: Pick<CacheRequest, 'kind'>+): CacheOperationCategory {+ return match(request.kind)+ .with('init', () => 'initialization' as const)+ .with('read', 'read-records', () => 'read' as const)+ .with('write', () => 'write' as const)+ .with(+ 'enqueue-optimistic-mutation',+ 'claim-next-mutation',+ 'defer-optimistic-write',+ 'commit-optimistic-write',+ 'rollback-optimistic-write',+ () => 'transaction' as const+ )+ .with(+ 'inspect-query',+ 'inspect-query-variants',+ () => 'inspection' as const+ )+ .with('invalidate', 'delete-records', () => 'invalidation' as const)+ .with('teardown', 'clear', () => 'lifecycle' as const)+ .exhaustive();+}++export function isStorageTransactionRequest(+ request: Pick<CacheRequest, 'kind'>+): boolean {+ return [+ 'write',+ 'enqueue-optimistic-mutation',+ 'claim-next-mutation',+ 'defer-optimistic-write',+ 'commit-optimistic-write',+ 'rollback-optimistic-write',+ 'invalidate',+ 'delete-records',+ 'clear',+ ].includes(request.kind);+}++/** Classifies an error without retaining or exporting its message. */+export function classifyCacheError(error: unknown): CacheErrorCode {+ const message =+ error instanceof Error+ ? error.message.toLowerCase()+ : typeof error === 'string'+ ? error.toLowerCase()+ : '';+ if (message.includes('timeout')) return 'timeout';+ if (message.includes('quota') || /\bfull\b/.test(message))+ return 'opfs-quota';+ if (message.includes('opfs') && message.includes('unavailable')) {+ return 'opfs-unavailable';+ }+ if (message.includes('opfs') || message.includes('wal')) return 'opfs-io';+ if (message.includes('lock')) return 'lock';+ if (message.includes('owner epoch') || message.includes('owner-lost')) {+ return 'owner-lost';+ }+ if (message.includes('protocol') || message.includes('envelope')) {+ return 'protocol';+ }+ if (message.includes('transport') || message.includes('messageport')) {+ return 'transport';+ }+ if (message.includes('schema') || message.includes('namespace')) {+ return 'schema';+ }+ if (message.includes('integrity') || message.includes('corrupt')) {+ return 'integrity';+ }+ if (message.includes('reset required')) return 'storage-reset';+ if (message.includes('wasm')) return 'wasm-instantiate';+ if (message.includes('initializ') || message.includes('open')) {+ return 'initialization';+ }+ return 'unknown';+}++export function resetReasonForError(error: unknown): CacheResetReason {+ const code = classifyCacheError(error);+ if (code === 'opfs-quota') return 'quota-failure';+ if (code === 'integrity') return 'integrity-failure';+ if (code === 'schema') return 'namespace-mismatch';+ if (code === 'owner-lost') return 'abrupt-owner-loss';+ return 'storage-reset-required';+}++export function browserCacheTelemetryContext(+ rolloutCohort: CacheRolloutCohort,+ userAgent = typeof navigator === 'undefined' ? '' : navigator.userAgent,+ appVersion = import.meta.env.__APP_VERSION__ ?? 'unknown'+): CacheTelemetryContext {+ const firefox = /Firefox\/(\d+(?:\.\d+)*)/i.exec(userAgent);+ const chromium = /(?:Chrome|Chromium)\/(\d+(?:\.\d+)*)/i.exec(userAgent);+ const safari =+ /Safari\//i.test(userAgent) && !chromium+ ? /Version\/(\d+(?:\.\d+)*)/i.exec(userAgent)+ : null;+ const match = firefox ?? chromium ?? safari;+ const browserFamily = firefox+ ? 'firefox'+ : chromium+ ? 'chromium'+ : safari+ ? 'safari'+ : 'other';+ const safeVersion = match?.[1]?.split('.')[0] ?? 'unknown';+ const appRelease = /^(\d+)\.(\d+)/.exec(appVersion);+ const safeAppVersion = appRelease+ ? `${appRelease[1]}.${appRelease[2]}`.slice(0, 16)+ : 'unknown';+ return {+ browserFamily,+ browserVersion: safeVersion,+ appVersion: safeAppVersion,+ backend: 'turso-wasm-opfs',+ rolloutCohort: CACHE_ROLLOUT_COHORTS.includes(rolloutCohort)+ ? rolloutCohort+ : 'unknown',+ };+}++export function isCacheTelemetryObservation(+ value: unknown+): value is CacheTelemetryObservation {+ if (typeof value !== 'object' || value === null) return false;+ const candidate = sanitizeObservation(value as CacheTelemetryObservation);+ if (!candidate) return false;+ return Object.keys(value).every((key) =>+ [+ 'name',+ 'aggregatedEventName',+ 'operationCategory',+ 'outcome',+ 'errorCode',+ 'resetReason',+ 'ownerEvent',+ 'persistence',+ 'openOutcome',+ 'queueDiagnosticsAvailability',+ 'resetAttempt',+ 'durationMs',+ 'bytes',+ 'highWaterBytes',+ 'usageBytes',+ 'quotaBytes',+ 'ratio',+ 'count',+ 'sampleRate',+ 'queueDepth',+ 'oldestAgeMs',+ ].includes(key)+ );+}diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/browser-test-wasm-module.ts b/apps/web/src/lib/graphql-cache/worker/browser-test/browser-test-wasm-module.tsnew file mode 100644index 0000000000..56c112c02f--- /dev/null+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/browser-test-wasm-module.ts@@ -0,0 +1,42 @@+type BrowserTestCacheWasmModule = {+ default(input?: { module_or_path?: unknown }): Promise<unknown>;+ browserTestMakeNamespaceIncompatible(scope: string): Promise<void>;+ browserTestCorruptQueuePayload(scope: string): Promise<void>;+};++let modulePromise:+ | Promise<{ module: BrowserTestCacheWasmModule; wasmUrl: string }>+ | undefined;++/** Loads the separate feature-gated destructive-hook artifact for tests only. */+export function loadBrowserTestCacheWasm(): Promise<{+ module: BrowserTestCacheWasmModule;+ wasmUrl: string;+}> {+ if (modulePromise) return modulePromise;+ const initialization = (async () => {+ const glueUrl = new URL(+ '../../wasm-browser-test/cache_wasm_browser_test_hooks.js',+ import.meta.url+ ).href;+ const wasmUrl = new URL(+ '../../wasm-browser-test/cache_wasm_browser_test_hooks_bg.wasm',+ import.meta.url+ ).href;+ const module = (await import(+ /* @vite-ignore */ glueUrl+ )) as BrowserTestCacheWasmModule;+ const response = await fetch(wasmUrl);+ if (!response.ok) {+ throw new Error(`browser-test WASM returned HTTP ${response.status}`);+ }+ const compiled = await WebAssembly.compile(await response.arrayBuffer());+ await module.default({ module_or_path: compiled });+ return { module, wasmUrl };+ })();+ modulePromise = initialization;+ void initialization.catch(() => {+ if (modulePromise === initialization) modulePromise = undefined;+ });+ return initialization;+}diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/browser-wire.ts b/apps/web/src/lib/graphql-cache/worker/browser-test/browser-wire.tsnew file mode 100644index 0000000000..06f7101e87--- /dev/null+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/browser-wire.ts@@ -0,0 +1,44 @@+export type BrowserHarnessCommand =+ | { kind: 'write'; commandId: string; value: string }+ | { kind: 'read'; commandId: string }+ | { kind: 'slow-read'; commandId: string }+ | { kind: 'graceful-close'; commandId: string }+ | { kind: 'crash-worker'; commandId: string }+ | { kind: 'release-liveness-lock'; commandId: string }+ | {+ kind: 'stale-response';+ commandId: string;+ ownerEpoch: number;+ routeId: number;+ };++export type BrowserHarnessEnvelope =+ | {+ source: 'harness';+ targetTabId: string;+ command: BrowserHarnessCommand;+ }+ | {+ source: 'tab';+ tabId: string;+ event:+ | { kind: 'adapter-created' }+ | { kind: 'registered' }+ | { kind: 'worker-created'; ownerEpoch: number }+ | { kind: 'worker-terminated'; ownerEpoch: number; reason: string }+ | { kind: 'engine-replaced'; ownerEpoch: number }+ | { kind: 'cache-push'; pushKind: string }+ | {+ kind: 'command-result';+ commandId: string;+ ok: true;+ result?: unknown;+ }+ | {+ kind: 'command-result';+ commandId: string;+ ok: false;+ error: string;+ }+ | { kind: 'protocol-error'; error: string };+ };diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/cache-lifecycle-harness.ts b/apps/web/src/lib/graphql-cache/worker/browser-test/cache-lifecycle-harness.tsnew file mode 100644index 0000000000..70d3118fd2--- /dev/null+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/cache-lifecycle-harness.ts@@ -0,0 +1,253 @@+import type { CacheHost } from '../../host/types';+import { createWorkerCacheHost } from '../../host/worker-host';+import { clearRegisteredCaches, registerCacheHost } from '../../lifecycle';++const result = document.querySelector<HTMLElement>('#result');+if (!result) throw new Error('missing Cache result node');++const parameters = new URLSearchParams(location.search);+const treatment = parameters.get('treatment') === 'true';+const scope =+ parameters.get('scope') ?? `cache-lifecycle-${crypto.randomUUID()}`;+const NativeWorker = globalThis.Worker;+const NativeSharedWorker = globalThis.SharedWorker;+const engineWorkers: Worker[] = [];+const constructedWorkerUrls: string[] = [];+globalThis.Worker = new Proxy(NativeWorker, {+ construct(target, args: ConstructorParameters<typeof Worker>) {+ const worker = Reflect.construct(target, args) as Worker;+ if (args[1]?.name?.startsWith('graphql-cache-engine:')) {+ engineWorkers.push(worker);+ constructedWorkerUrls.push(String(args[0]));+ }+ return worker;+ },+});+globalThis.SharedWorker = new Proxy(NativeSharedWorker, {+ construct(target, args: ConstructorParameters<typeof SharedWorker>) {+ constructedWorkerUrls.push(String(args[0]));+ return Reflect.construct(target, args) as SharedWorker;+ },+});+let owner: CacheHost | undefined;+let standby: CacheHost | undefined;+let unregisterOwner: (() => void) | undefined;+let hostConstructionCount = 0;++const query = (+ operationName: string+) => `query ${operationName}($input: SoupInput!) {+ user {+ id+ soup(input: $input) {+ nextCursor+ items { __typename id }+ }+ }+}`;+const variables = (limit: number) => ({ input: { limit } });+const data = (identity: string, value: string) => ({+ user: {+ id: identity,+ soup: {+ nextCursor: null,+ items: [{ __typename: 'GraphqlSoupDocument', id: value }],+ },+ },+});++function requireOwner(): CacheHost {+ if (!owner) throw new Error('Cache cache host is not started');+ return owner;+}++async function read(host: CacheHost, limit: number, name: string) {+ return await host.readQuery({+ query: query(name),+ operationName: name,+ variables: variables(limit),+ });+}++async function startOwner(registerForLogout = false): Promise<void> {+ if (!treatment) {+ throw new Error('Cache control/default-off cannot activate cache');+ }+ if (owner) return;+ hostConstructionCount += 1;+ owner = createWorkerCacheHost({+ scope,+ requestTimeoutMs: 20_000,+ initializationTimeoutMs: 20_000,+ rolloutCohort: 'treatment',+ });+ if (registerForLogout) unregisterOwner = registerCacheHost(owner);+ await read(owner, 1, 'CacheLifecycleQuery');+}++const api = {+ scope,+ rolloutMode(): 'control' | 'treatment' {+ return treatment ? 'treatment' : 'control';+ },+ hostConstructionCount(): number {+ return hostConstructionCount;+ },+ constructedWorkerUrls(): string[] {+ return [...constructedWorkerUrls];+ },+ engineWorkerCount(): number {+ return engineWorkers.length;+ },+ navigationDurationMs(): number {+ return (+ (+ performance.getEntriesByType('navigation')[0] as+ | PerformanceNavigationTiming+ | undefined+ )?.duration ?? 0+ );+ },+ async start(): Promise<void> {+ await startOwner();+ if (standby) return;+ hostConstructionCount += 1;+ standby = createWorkerCacheHost({+ scope,+ requestTimeoutMs: 20_000,+ initializationTimeoutMs: 20_000,+ rolloutCohort: 'treatment',+ });+ await read(standby, 1, 'CacheLifecycleQuery');+ },+ async startSingle(): Promise<void> {+ await startOwner();+ },+ async startLogoutHost(): Promise<void> {+ await startOwner(true);+ },+ async write(+ value: string,+ identity = 'cache-lifecycle-user',+ limit = 1+ ): Promise<void> {+ const host = requireOwner();+ await host.writeQuery({+ query: query('CacheLifecycleQuery'),+ operationName: 'CacheLifecycleQuery',+ variables: variables(limit),+ data: data(identity, value),+ identity,+ });+ },+ async read(limit = 1): Promise<unknown> {+ return await read(requireOwner(), limit, 'CacheLifecycleQuery');+ },+ async logoutReset(limit = 1): Promise<unknown> {+ if (!unregisterOwner) {+ throw new Error('Cache logout host is not registered');+ }+ await clearRegisteredCaches();+ return await read(requireOwner(), limit, 'CacheLifecycleQuery');+ },+ async closeSamePageStandbyHost(): Promise<{+ ownerRead: unknown;+ engineWorkerCount: number;+ }> {+ if (!standby) throw new Error('Cache standby is not started');+ standby.dispose();+ standby = undefined;+ return {+ ownerRead: await read(requireOwner(), 1, 'CacheLifecycleQuery'),+ engineWorkerCount: engineWorkers.length,+ };+ },+ async startStandby(): Promise<void> {+ if (!treatment) throw new Error('Cache control cannot start standby');+ if (standby) return;+ hostConstructionCount += 1;+ standby = createWorkerCacheHost({+ scope,+ requestTimeoutMs: 20_000,+ initializationTimeoutMs: 20_000,+ rolloutCohort: 'treatment',+ });+ await read(standby, 1, 'CacheLifecycleQuery');+ },+ async cleanOwnerHandoff(): Promise<unknown> {+ if (!standby) throw new Error('Cache standby is not started');+ const retiring = requireOwner();+ const replacement = standby;+ standby = undefined;+ retiring.dispose();+ owner = replacement;+ return await read(replacement, 1, 'CacheLifecycleQuery');+ },+ async identityReset(): Promise<{ old: unknown; current: unknown }> {+ const host = requireOwner();+ await host.writeQuery({+ query: query('CacheLifecycleQuery'),+ operationName: 'CacheLifecycleQuery',+ variables: variables(1),+ data: data('cache-lifecycle-user-a', 'identity-a'),+ identity: 'cache-lifecycle-user-a',+ });+ await host.writeQuery({+ query: query('CacheLifecycleQuery'),+ operationName: 'CacheLifecycleQuery',+ variables: variables(2),+ data: data('cache-lifecycle-user-b', 'identity-b'),+ identity: 'cache-lifecycle-user-b',+ });+ return {+ old: await read(host, 1, 'CacheLifecycleQuery'),+ current: await read(host, 2, 'CacheLifecycleQuery'),+ };+ },+ async abruptOwnerLoss(): Promise<{+ oldRequestRejected: boolean;+ replacement: unknown;+ }> {+ const host = requireOwner();+ await api.write('abrupt-must-wipe', 'cache-lifecycle-user-b', 3);+ const currentWorker = engineWorkers.at(-1);+ if (!currentWorker) throw new Error('missing elected Cache engine worker');+ currentWorker.terminate();+ const oldRequestRejected = await read(host, 3, 'CacheLifecycleQuery').then(+ () => false,+ () => true+ );+ const deadline = performance.now() + 20_000;+ for (;;) {+ try {+ const replacement = await read(host, 3, 'CacheLifecycleQuery');+ return { oldRequestRejected, replacement };+ } catch (error) {+ if (performance.now() >= deadline) throw error;+ await new Promise<void>((resolve) => setTimeout(resolve, 50));+ }+ }+ },+ dispose(): void {+ unregisterOwner?.();+ unregisterOwner = undefined;+ owner?.dispose();+ standby?.dispose();+ owner = undefined;+ standby = undefined;+ },+};++declare global {+ interface Window {+ cacheLifecycleHarness: typeof api;+ }+}++window.cacheLifecycleHarness = api;+result.dataset.status = 'ready';+result.dataset.rollout = treatment ? 'treatment' : 'control';+result.textContent = JSON.stringify({+ scopeFreeTelemetry: true,+ rollout: result.dataset.rollout,+});diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/cache-lifecycle.browser.e2e.ts b/apps/web/src/lib/graphql-cache/worker/browser-test/cache-lifecycle.browser.e2e.tsnew file mode 100644index 0000000000..9e123d941b--- /dev/null+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/cache-lifecycle.browser.e2e.ts@@ -0,0 +1,537 @@+import { basename } from 'node:path';+import { expect, test } from '@playwright/test';++const harnessPath = (projectName: string): string =>+ projectName.includes('production')+ ? '/app/cache-lifecycle.html'+ : '/cache-lifecycle.html';++const isHit = (value: unknown): boolean =>+ typeof value === 'object' &&+ value !== null &&+ (value as { kind?: unknown }).kind === 'hit';++const isMiss = (value: unknown): boolean =>+ typeof value === 'object' &&+ value !== null &&+ (value as { kind?: unknown }).kind === 'miss';++test.describe.configure({ mode: 'serial' });++const cacheResources = (urls: string[]) => ({+ wasm: [+ ...new Set(+ urls.filter((url) => /cache_wasm_bg(?:-[\w-]+)?\.wasm(?:\?|$)/.test(url))+ ),+ ],+ engine: [+ ...new Set(urls.filter((url) => /cache\.engine-worker[^/]*\.js/.test(url))),+ ],+ coordinator: [+ ...new Set(+ urls.filter((url) =>+ /cache\.coordinator\.shared-worker[^/]*\.js/.test(url)+ )+ ),+ ],+});++test('Cache exact host stays navigation-lazy, preserves offline handoff, resets identity, and wipes abrupt loss', async ({+ context,+ page,+}, testInfo) => {+ const requestedUrls: string[] = [];+ const browserErrors: string[] = [];+ const failedResponses: string[] = [];+ const failedRequests: string[] = [];+ context.on('request', (request) => requestedUrls.push(request.url()));+ context.on('requestfailed', (request) => {+ failedRequests.push(+ `${request.failure()?.errorText ?? 'failed'} ${request.url()}`+ );+ });+ context.on('response', (response) => {+ if (response.status() >= 400) {+ failedResponses.push(`${response.status()} ${response.url()}`);+ }+ });+ page.on('console', (message) => {+ if (message.type() === 'error') {+ browserErrors.push(+ `${message.text()} @ ${message.location().url || 'unknown'}`+ );+ }+ });+ page.on('pageerror', (error) => browserErrors.push(error.message));++ const path = harnessPath(testInfo.project.name);+ await page.goto(path);+ await expect(page.locator('#result')).toHaveAttribute('data-status', 'ready');+ await expect(page.locator('#result')).toHaveAttribute(+ 'data-rollout',+ 'control'+ );+ expect(+ await page.evaluate(() => ({+ mode: window.cacheLifecycleHarness.rolloutMode(),+ hostCount: window.cacheLifecycleHarness.hostConstructionCount(),+ workerCount: window.cacheLifecycleHarness.constructedWorkerUrls().length,+ }))+ ).toEqual({ mode: 'control', hostCount: 0, workerCount: 0 });+ expect(cacheResources(requestedUrls)).toEqual({+ wasm: [],+ engine: [],+ coordinator: [],+ });++ const scope = `cache-lifecycle-playwright-${crypto.randomUUID()}`;+ await page.goto(`${path}?treatment=true&scope=${encodeURIComponent(scope)}`);+ await expect(page.locator('#result')).toHaveAttribute('data-status', 'ready');+ await expect(page.locator('#result')).toHaveAttribute(+ 'data-rollout',+ 'treatment'+ );+ expect(+ await page.evaluate(() =>+ window.cacheLifecycleHarness.hostConstructionCount()+ )+ ).toBe(0);+ const beforeFirstUse = cacheResources([+ ...requestedUrls,+ ...(await page.evaluate(() =>+ window.cacheLifecycleHarness.constructedWorkerUrls()+ )),+ ]);+ expect(beforeFirstUse.wasm).toEqual([]);+ expect(beforeFirstUse.engine).toEqual([]);+ expect(beforeFirstUse.coordinator).toEqual([]);++ await page.evaluate(() => window.cacheLifecycleHarness.start());+ await expect+ .poll(() => cacheResources(requestedUrls).wasm.length, { timeout: 30_000 })+ .toBe(1);+ const afterFirstUse = cacheResources([+ ...requestedUrls,+ ...(await page.evaluate(() =>+ window.cacheLifecycleHarness.constructedWorkerUrls()+ )),+ ]);+ expect(afterFirstUse.engine).toHaveLength(1);+ expect(afterFirstUse.coordinator).toHaveLength(1);++ await page.evaluate(() =>+ window.cacheLifecycleHarness.write(+ 'offline-preserved',+ 'cache-lifecycle-offline-user'+ )+ );+ const standbyClose = await page.evaluate(() =>+ window.cacheLifecycleHarness.closeSamePageStandbyHost()+ );+ expect(isHit(standbyClose.ownerRead)).toBe(true);+ expect(standbyClose.engineWorkerCount).toBe(1);+ await page.evaluate(() => window.cacheLifecycleHarness.startStandby());+ await context.setOffline(true);+ const offlineHandoff = await page.evaluate(() =>+ window.cacheLifecycleHarness.cleanOwnerHandoff()+ );+ expect(isHit(offlineHandoff)).toBe(true);+ await context.setOffline(false);++ const identity = await page.evaluate(() =>+ window.cacheLifecycleHarness.identityReset()+ );+ expect(isMiss(identity.old)).toBe(true);+ expect(isHit(identity.current)).toBe(true);++ const abrupt = await page.evaluate(() =>+ window.cacheLifecycleHarness.abruptOwnerLoss()+ );+ expect(abrupt.oldRequestRejected).toBe(true);+ expect(isMiss(abrupt.replacement)).toBe(true);++ const isolation = await page.evaluate(() => ({+ crossOriginIsolated: globalThis.crossOriginIsolated,+ sharedArrayBufferCreated:+ typeof globalThis.SharedArrayBuffer === 'function' &&+ globalThis.crossOriginIsolated,+ }));+ expect(isolation).toEqual({+ crossOriginIsolated: false,+ sharedArrayBufferCreated: false,+ });+ expect({ browserErrors, failedResponses, failedRequests }).toEqual({+ browserErrors: [],+ failedResponses: [],+ failedRequests: [],+ });++ const resources = cacheResources([+ ...requestedUrls,+ ...(await page.evaluate(() =>+ window.cacheLifecycleHarness.constructedWorkerUrls()+ )),+ ]);+ const mode = testInfo.project.name.includes('production')+ ? 'production'+ : 'development';+ if (mode === 'production') {+ expect(resources.wasm).toHaveLength(1);+ expect(basename(new URL(resources.wasm[0]!).pathname)).toMatch(+ /^cache_wasm_bg-[\w-]+\.wasm$/+ );+ expect(resources.engine.every((url) => url.includes('/app/'))).toBe(true);+ expect(resources.coordinator.every((url) => url.includes('/app/'))).toBe(+ true+ );+ }++ await page.evaluate(() => window.cacheLifecycleHarness.dispose());+});++test('Cache real standby tab close preserves the same active engine', async ({+ context,+ page,+}, testInfo) => {+ test.skip(+ !testInfo.project.name.includes('production'),+ 'Cache rollout evidence requires the production bundle'+ );+ const scope = `cache-lifecycle-standby-tab-${crypto.randomUUID()}`;+ const path = `${harnessPath(testInfo.project.name)}?treatment=true&scope=${encodeURIComponent(scope)}`;+ await page.goto(path);+ await expect(page.locator('#result')).toHaveAttribute('data-status', 'ready');+ await page.evaluate(() => window.cacheLifecycleHarness.startSingle());+ expect(+ await page.evaluate(() => window.cacheLifecycleHarness.engineWorkerCount())+ ).toBe(1);+ const ownerWorkerUrls = await page.evaluate(() =>+ window.cacheLifecycleHarness.constructedWorkerUrls()+ );+ await page.evaluate(() =>+ window.cacheLifecycleHarness.write('real-standby-preserved')+ );++ const standbyPage = await context.newPage();+ await standbyPage.goto(path);+ await expect(standbyPage.locator('#result')).toHaveAttribute(+ 'data-status',+ 'ready'+ );+ await standbyPage.evaluate(() => window.cacheLifecycleHarness.startSingle());+ expect(+ await standbyPage.evaluate(() =>+ window.cacheLifecycleHarness.engineWorkerCount()+ )+ ).toBe(0);+ expect(+ await standbyPage.evaluate(() => window.cacheLifecycleHarness.read())+ ).toMatchObject({+ kind: 'hit',+ data: {+ user: {+ soup: { items: [{ id: 'real-standby-preserved' }] },+ },+ },+ });++ await standbyPage.close();+ await page.evaluate(() =>+ window.cacheLifecycleHarness.write('owner-after-real-standby-close')+ );+ expect(+ await page.evaluate(() => window.cacheLifecycleHarness.read())+ ).toMatchObject({+ kind: 'hit',+ data: {+ user: {+ soup: { items: [{ id: 'owner-after-real-standby-close' }] },+ },+ },+ });+ expect(+ await page.evaluate(() => window.cacheLifecycleHarness.engineWorkerCount())+ ).toBe(1);+ expect(+ await page.evaluate(() =>+ window.cacheLifecycleHarness.constructedWorkerUrls()+ )+ ).toEqual(ownerWorkerUrls);+ await page.evaluate(() => window.cacheLifecycleHarness.dispose());+});++test('Cache actual logout cache lifecycle wipes the registered production host', async ({+ page,+}, testInfo) => {+ test.skip(+ !testInfo.project.name.includes('production'),+ 'Cache rollout evidence requires the production bundle'+ );+ const scope = `cache-lifecycle-logout-${crypto.randomUUID()}`;+ const path = `${harnessPath(testInfo.project.name)}?treatment=true&scope=${encodeURIComponent(scope)}`;+ await page.goto(path);+ await expect(page.locator('#result')).toHaveAttribute('data-status', 'ready');+ await page.evaluate(() => window.cacheLifecycleHarness.startLogoutHost());+ await page.evaluate(() =>+ window.cacheLifecycleHarness.write('logout-must-wipe')+ );+ expect(+ isHit(await page.evaluate(() => window.cacheLifecycleHarness.read()))+ ).toBe(true);+ expect(+ isMiss(+ await page.evaluate(() => window.cacheLifecycleHarness.logoutReset())+ )+ ).toBe(true);+ await page.evaluate(() => window.cacheLifecycleHarness.write('post-logout'));+ expect(+ isHit(await page.evaluate(() => window.cacheLifecycleHarness.read()))+ ).toBe(true);+ await page.evaluate(() => window.cacheLifecycleHarness.dispose());+});++test('Cache actual GraphQL Soup selector stays default-off without browser cache resources', async ({+ page,+}, testInfo) => {+ test.skip(+ !testInfo.project.name.includes('production'),+ 'Cache rollout evidence requires the production bundle'+ );+ const requestedUrls: string[] = [];+ page.on('request', (request) => requestedUrls.push(request.url()));+ await page.goto(+ testInfo.project.name.includes('production')+ ? '/app/graphql-soup-rollout.html'+ : '/graphql-soup-rollout.html'+ );+ await expect(page.locator('#result')).toHaveAttribute('data-status', 'ready');+ const result = await page.evaluate(() =>+ window.graphqlSoupRolloutHarness.resolveDefaultOff()+ );+ expect(result).toEqual({+ cacheEnabled: false,+ cacheHostPresent: false,+ resources: { workerUrls: [], sharedWorkerUrls: [] },+ });+ expect(cacheResources(requestedUrls)).toEqual({+ wasm: [],+ engine: [],+ coordinator: [],+ });+});++test('Cache actual PostHog treatment override is lazy and kill applies on navigation', async ({+ page,+}, testInfo) => {+ test.skip(+ !testInfo.project.name.includes('production'),+ 'Cache rollout evidence requires the production bundle'+ );+ const requestedUrls: string[] = [];+ page.on('request', (request) => requestedUrls.push(request.url()));+ const posthogRequests = () =>+ requestedUrls.filter((url) => {+ const parsed = new URL(url);+ return (+ parsed.hostname.includes('posthog') ||+ parsed.pathname.includes('/__cache-rollout-posthog-disabled') ||+ parsed.pathname.includes('/i/ph/')+ );+ });+ const path = '/app/graphql-soup-rollout.html';+ await page.goto(path);+ await expect(page.locator('#result')).toHaveAttribute('data-status', 'ready');+ const treatment = await page.evaluate(() =>+ window.graphqlSoupRolloutHarness.tryTreatment()+ );+ expect(+ treatment.overrideApplied,+ 'the required supported PostHog override must be available'+ ).toBe(true);+ if (!treatment.overrideApplied) {+ throw new Error('required PostHog treatment override was unavailable');+ }++ expect(treatment.lazyBeforeRead).toBe(true);+ expect(treatment.readKind).toBe('miss');+ expect(treatment.samePageKillLatched).toBe(true);+ expect(treatment.posthogBeforeSendCalls).toBe(0);+ expect(treatment.resources.workerUrls).toHaveLength(1);+ expect(treatment.resources.workerUrls[0]).toMatch(+ /cache\.engine-worker-[A-Za-z0-9_-]+\.js$/+ );+ expect(treatment.resources.sharedWorkerUrls).toHaveLength(1);+ expect(treatment.resources.sharedWorkerUrls[0]).toMatch(+ /cache\.coordinator\.shared-worker-[A-Za-z0-9_-]+\.js$/+ );+ expect(cacheResources(requestedUrls).wasm).toHaveLength(1);+ expect(posthogRequests()).toEqual([]);++ const requestCountBeforeNavigation = requestedUrls.length;+ await page.goto(path);+ await expect(page.locator('#result')).toHaveAttribute('data-status', 'ready');+ const afterNavigation = await page.evaluate(() =>+ window.graphqlSoupRolloutHarness.resolveAfterNavigationKill()+ );+ expect(afterNavigation).toEqual({+ cacheEnabled: false,+ cacheHostPresent: false,+ posthogBeforeSendCalls: 0,+ resources: { workerUrls: [], sharedWorkerUrls: [] },+ });+ expect(+ cacheResources(requestedUrls.slice(requestCountBeforeNavigation))+ ).toEqual({ wasm: [], engine: [], coordinator: [] });+ expect(posthogRequests()).toEqual([]);+});++test('Cache terminates each admitted mutating RPC before core without replay', async ({+ context,+ page,+}, testInfo) => {+ test.skip(+ !testInfo.project.name.includes('production'),+ 'Cache fault evidence requires the production bundle'+ );+ testInfo.setTimeout(360_000);+ const requestedUrls: string[] = [];+ context.on('request', (request) => requestedUrls.push(request.url()));+ await page.goto('/app/cache-recovery.html');+ await expect(page.locator('#result')).toHaveAttribute('data-status', 'ready');+ const kinds = await page.evaluate(+ () => window.cacheRecoveryHarness.mutatingRequestKinds+ );+ expect(kinds).toEqual([+ 'write',+ 'enqueue-optimistic-mutation',+ 'claim-next-mutation',+ 'defer-optimistic-write',+ 'commit-optimistic-write',+ 'rollback-optimistic-write',+ 'invalidate',+ 'delete-records',+ 'clear',+ ]);+ const results = [];+ for (const kind of kinds) {+ results.push(+ await page.evaluate(+ async (requestKind) =>+ await window.cacheRecoveryHarness.runFaultKind(requestKind),+ kind+ )+ );+ }+ for (const result of results) {+ expect(result).toMatchObject({+ actualDedicatedWorkerTerminated: true,+ requestAdmittedBeforeCore: true,+ midSqlExecutionClaimed: false,+ oldRequestRejected: true,+ replacementRecordsEmpty: true,+ replacementQueueEmpty: true,+ mutationAdmissionCount: 1,+ unexpectedReplacementMutatingAdmissionCount: 0,+ replacementAdmissionBarrierObserved: true,+ resetPhaseSequence: [+ 'graphql_cache.storage_reset_required',+ 'graphql_cache.logical_reset',+ 'graphql_cache.reset_wipe',+ ],+ exactProductionTursoWasm: true,+ queueTelemetryObserved: true,+ performanceMemoryAvailable: false,+ userAgentSpecificMemoryAvailable: false,+ });+ }+ expect(cacheResources(requestedUrls).wasm).toHaveLength(1);+ expect(cacheResources(requestedUrls).engine).toHaveLength(1);+});++test('Cache lock-safe incompatible namespace and corrupt queue payload recover exactly once', async ({+ context,+ page,+}, testInfo) => {+ test.skip(+ !testInfo.project.name.includes('production'),+ 'Cache recovery evidence requires the production bundle'+ );+ testInfo.setTimeout(180_000);+ const requestedUrls: string[] = [];+ context.on('request', (request) => requestedUrls.push(request.url()));+ await page.goto('/app/cache-recovery.html');+ await expect(page.locator('#result')).toHaveAttribute('data-status', 'ready');+ const recoveryHookUrls = new Set<string>();+ for (const [kind, openOutcome] of [+ ['incompatible-namespace', 'reset-incompatible'],+ ['corrupt-queue-payload', 'reset-corrupt'],+ ] as const) {+ const result = await page.evaluate(+ async (recoveryKind) =>+ await window.cacheRecoveryHarness.runRecoveryKind(recoveryKind),+ kind+ );+ expect(result).toMatchObject({+ kind,+ gracefulCloseBeforeMutation: true,+ separateFeatureGatedBrowserTestArtifact: true,+ productionArtifactDebugExportsAbsent: true,+ browserTestWasmUrl: expect.stringMatching(+ /cache_wasm_browser_test_hooks_bg-[A-Za-z0-9_-]+\.wasm$/+ ),+ browserTestWorkerOnlyControl: true,+ productionCoordinatorProtocolUnchanged: true,+ openOutcome,+ recordsWiped: true,+ durableQueueWiped: true,+ usableAfterReset: true,+ storageResetRequiredCount: 1,+ logicalResetCount: 1,+ resetWipeCount: 1,+ queueTelemetryObserved: true,+ });+ recoveryHookUrls.add(result.browserTestWasmUrl);+ }+ expect(recoveryHookUrls.size).toBe(1);+ const [recoveryHookUrl] = [...recoveryHookUrls];+ if (!recoveryHookUrl) throw new Error('missing recovery-hook WASM URL');+ const hookResponse = await context.request.get(recoveryHookUrl);+ expect(hookResponse.ok()).toBe(true);+ expect(cacheResources(requestedUrls).wasm).toHaveLength(1);+ expect(cacheResources(requestedUrls).engine).toHaveLength(1);+});++test('Cache Chromium storage eviction reopens empty without fabricated Firefox coverage', async ({+ context,+ page,+}, testInfo) => {+ test.skip(+ !testInfo.project.name.startsWith('chromium'),+ 'Chromium CDP is the only local storage-eviction control available'+ );+ const path = harnessPath(testInfo.project.name);+ const scope = `cache-lifecycle-eviction-${crypto.randomUUID()}`;+ await page.goto(`${path}?treatment=true&scope=${encodeURIComponent(scope)}`);+ await expect(page.locator('#result')).toHaveAttribute('data-status', 'ready');+ await page.evaluate(async () => {+ await window.cacheLifecycleHarness.start();+ await window.cacheLifecycleHarness.write(+ 'evict-me',+ 'cache-lifecycle-eviction-user'+ );+ window.cacheLifecycleHarness.dispose();+ });+ await page.waitForTimeout(1_000);++ const cdp = await context.newCDPSession(page);+ await cdp.send('Storage.clearDataForOrigin', {+ origin: new URL(page.url()).origin,+ storageTypes: 'file_systems',+ });+ const reopened = await page.evaluate(async () => {+ await window.cacheLifecycleHarness.start();+ return await window.cacheLifecycleHarness.read();+ });+ expect(isMiss(reopened)).toBe(true);+ await page.evaluate(() => window.cacheLifecycleHarness.dispose());+});diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/cache-lifecycle.html b/apps/web/src/lib/graphql-cache/worker/browser-test/cache-lifecycle.htmlnew file mode 100644index 0000000000..988046255f--- /dev/null+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/cache-lifecycle.html@@ -0,0 +1,13 @@+<!doctype html>+<html lang="en">+ <head>+ <meta charset="UTF-8" />+ <meta name="viewport" content="width=device-width, initial-scale=1.0" />+ <link rel="icon" href="data:," />+ <title>Cache exact cache lifecycle harness</title>+ </head>+ <body>+ <main id="result" data-status="loading">loading</main>+ <script type="module" src="./cache-lifecycle-harness.ts"></script>+ </body>+</html>diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/cache-recovery-harness.ts b/apps/web/src/lib/graphql-cache/worker/browser-test/cache-recovery-harness.tsnew file mode 100644index 0000000000..a954dc7a78--- /dev/null+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/cache-recovery-harness.ts@@ -0,0 +1,709 @@+import type { CacheRequest } from '../../protocol';+import type {+ ProductionCacheRequestWithoutId,+ ProductionHarnessCommand,+ ProductionHarnessEnvelope,+} from './production-browser-wire';++const resultElement = document.querySelector<HTMLElement>('#result');+if (!resultElement) throw new Error('missing Cache internal result element');++export const CACHE_MUTATING_REQUEST_KINDS = [+ 'write',+ 'enqueue-optimistic-mutation',+ 'claim-next-mutation',+ 'defer-optimistic-write',+ 'commit-optimistic-write',+ 'rollback-optimistic-write',+ 'invalidate',+ 'delete-records',+ 'clear',+] as const satisfies readonly CacheRequest['kind'][];++type MutatingRequestKind = (typeof CACHE_MUTATING_REQUEST_KINDS)[number];+type RecoveryKind = 'incompatible-namespace' | 'corrupt-queue-payload';+type CommandWithoutId = ProductionHarnessCommand extends infer Command+ ? Command extends ProductionHarnessCommand+ ? Omit<Command, 'commandId'>+ : never+ : never;++type RuntimeTelemetry = {+ kind: string;+ tabId?: string;+ ownerEpoch?: number;+ requestId?: number;+ requestKind?: string;+ databaseAction?: string;+ performanceMemoryAvailable?: boolean;+ userAgentSpecificMemoryAvailable?: boolean;+ admissionBarrier?: boolean;+ fatalCode?: string;+};++type QueueTelemetry = {+ name?: string;+ openOutcome?: string;+ queueDepth?: number;+ oldestAgeMs?: number;+};++const QUERY = `query Soup($input: SoupInput!) {+ user {+ id+ soup(input: $input) {+ nextCursor+ items { __typename id }+ }+ }+}`;+const MUTATION = `mutation SetEntityProperty($input: SetEntityPropertyInput!) {+ setEntityProperty(input: $input) { id displayName }+}`;+const VARIABLES = { input: { limit: 1 } };+const MUTATION_VARIABLES = {+ input: {+ entityType: 'DOCUMENT',+ entityId: 'doc-1',+ propertyDefinitionId: 'def-1',+ value: { string: 'x' },+ },+};++const assert: (condition: unknown, message: string) => asserts condition = (+ condition,+ message+) => {+ if (!condition) throw new Error(message);+};++const waitUntil = async (+ description: string,+ predicate: () => boolean,+ timeoutMs = 30_000+): Promise<void> => {+ const started = performance.now();+ while (!predicate()) {+ if (performance.now() - started > timeoutMs) {+ throw new Error(`timed out waiting for ${description}`);+ }+ await new Promise<void>((resolve) => setTimeout(resolve, 20));+ }+};++class ProductionSession {+ readonly runtimeTelemetry: RuntimeTelemetry[] = [];+ readonly cacheTelemetry: QueueTelemetry[] = [];+ private readonly tabs = new Map<string, HTMLIFrameElement>();+ private readonly registered = new Set<string>();+ private readonly pending = new Map<+ string,+ {+ resolve: (value: unknown) => void;+ reject: (error: Error) => void;+ timer: ReturnType<typeof setTimeout>;+ }+ >();+ private readonly tabChannel: BroadcastChannel;+ private readonly runtimeChannel: BroadcastChannel;+ private readonly cacheTelemetryChannel = new BroadcastChannel(+ 'macro:graphql-cache-telemetry:v1'+ );++ constructor(readonly scope: string) {+ this.tabChannel = new BroadcastChannel(+ `graphql-cache-wp08-production-tabs:${scope}`+ );+ this.runtimeChannel = new BroadcastChannel(+ `graphql-cache-wp08-production:${scope}`+ );+ this.tabChannel.onmessage = (+ event: MessageEvent<ProductionHarnessEnvelope>+ ) => {+ const envelope = event.data;+ if (envelope.source !== 'tab') return;+ switch (envelope.event.kind) {+ case 'registered':+ this.registered.add(envelope.tabId);+ break;+ case 'command-result': {+ const pending = this.pending.get(envelope.event.commandId);+ if (!pending) return;+ this.pending.delete(envelope.event.commandId);+ clearTimeout(pending.timer);+ if (envelope.event.ok) pending.resolve(envelope.event.result);+ else pending.reject(new Error(envelope.event.error));+ break;+ }+ case 'protocol-error':+ throw new Error(envelope.event.error);+ }+ };+ this.runtimeChannel.onmessage = (event: MessageEvent<RuntimeTelemetry>) => {+ this.runtimeTelemetry.push(event.data);+ };+ this.cacheTelemetryChannel.onmessage = (+ event: MessageEvent<QueueTelemetry>+ ) => {+ this.cacheTelemetry.push(event.data);+ };+ }++ async openTab(tabId: string): Promise<void> {+ const readyBefore = this.runtimeTelemetry.filter(+ (event) => event.kind === 'ready'+ ).length;+ const url = new URL('./production-tab.html', location.href);+ url.searchParams.set('scope', this.scope);+ url.searchParams.set('tabId', tabId);+ const frame = document.createElement('iframe');+ frame.name = `${this.scope}:${tabId}`;+ frame.src = url.href;+ frame.hidden = true;+ document.body.append(frame);+ this.tabs.set(tabId, frame);+ await waitUntil(`${tabId} registration`, () => this.registered.has(tabId));+ await waitUntil(+ `${tabId} engine ready`,+ () =>+ this.runtimeTelemetry.filter((event) => event.kind === 'ready').length >+ readyBefore+ );+ }++ command(tabId: string, command: CommandWithoutId): Promise<unknown> {+ const commandId = crypto.randomUUID();+ const result = new Promise<unknown>((resolve, reject) => {+ const timer = setTimeout(() => {+ this.pending.delete(commandId);+ reject(new Error(`production command timed out: ${command.kind}`));+ }, 30_000);+ this.pending.set(commandId, { resolve, reject, timer });+ });+ this.tabChannel.postMessage({+ source: 'harness',+ targetTabId: tabId,+ command: { ...command, commandId } as ProductionHarnessCommand,+ } satisfies ProductionHarnessEnvelope);+ return result;+ }++ async gracefulClose(tabId: string): Promise<void> {+ const drainedBefore = this.runtimeTelemetry.filter(+ (event) => event.kind === 'drained'+ ).length;+ await this.command(tabId, { kind: 'graceful-close' });+ await waitUntil(+ `${tabId} graceful drain`,+ () =>+ this.runtimeTelemetry.filter((event) => event.kind === 'drained')+ .length > drainedBefore+ );+ this.tabs.get(tabId)?.remove();+ this.tabs.delete(tabId);+ }++ close(): void {+ for (const frame of this.tabs.values()) frame.remove();+ for (const pending of this.pending.values()) {+ clearTimeout(pending.timer);+ pending.reject(new Error('production session closed'));+ }+ this.pending.clear();+ this.tabChannel.close();+ this.runtimeChannel.close();+ this.cacheTelemetryChannel.close();+ }+}++const writeRequest = (value: string): ProductionCacheRequestWithoutId => ({+ kind: 'write',+ query: QUERY,+ operationName: 'Soup',+ variables: VARIABLES,+ data: {+ user: {+ id: 'cache-recovery-user',+ soup: {+ nextCursor: null,+ items: [{ __typename: 'GraphqlSoupDocument', id: value }],+ },+ },+ },+ identity: 'cache-recovery-identity',+});++const enqueueRequest = (+ owner: string,+ createdAtMs: number+): ProductionCacheRequestWithoutId => ({+ kind: 'enqueue-optimistic-mutation',+ query: MUTATION,+ operationName: 'SetEntityProperty',+ variables: MUTATION_VARIABLES,+ data: {+ setEntityProperty: { id: 'prop-1', displayName: 'Optimistic' },+ },+ createdAtMs,+ owner,+ nowMs: createdAtMs,+ leaseExpiresAtMs: createdAtMs + 1_000,+});++type SeededMutation = {+ transactionId: string;+ leaseOwner: string;+ leaseGeneration: string;+};++function seededMutation(value: unknown, owner: string): SeededMutation {+ assert(typeof value === 'object' && value !== null, 'missing enqueue result');+ const result = value as {+ transactionId?: unknown;+ initialClaim?: {+ kind?: unknown;+ mutation?: { leaseGeneration?: unknown };+ };+ };+ assert(typeof result.transactionId === 'string', 'missing transaction id');+ assert(+ result.initialClaim?.kind === 'claimed',+ 'seed mutation was not claimed'+ );+ assert(+ typeof result.initialClaim.mutation?.leaseGeneration === 'string',+ 'missing lease generation'+ );+ return {+ transactionId: result.transactionId,+ leaseOwner: owner,+ leaseGeneration: result.initialClaim.mutation.leaseGeneration,+ };+}++const blockedRequest = (+ kind: MutatingRequestKind,+ seed: SeededMutation+): ProductionCacheRequestWithoutId => {+ switch (kind) {+ case 'write':+ return writeRequest('blocked-write');+ case 'enqueue-optimistic-mutation':+ return enqueueRequest('blocked-enqueue-owner', 20);+ case 'claim-next-mutation':+ return {+ kind,+ owner: 'blocked-claim-owner',+ nowMs: 2_000,+ leaseExpiresAtMs: 3_000,+ };+ case 'defer-optimistic-write':+ return {+ kind,+ ...seed,+ nextAttemptAtMs: 5_000,+ error: 'browser-test-retry',+ };+ case 'commit-optimistic-write':+ return {+ kind,+ ...seed,+ query: MUTATION,+ operationName: 'SetEntityProperty',+ variables: MUTATION_VARIABLES,+ data: {+ setEntityProperty: { id: 'prop-1', displayName: 'Committed' },+ },+ };+ case 'rollback-optimistic-write':+ return { kind, ...seed, error: 'browser-test-permanent' };+ case 'invalidate':+ case 'delete-records':+ return { kind, keys: ['GraphqlSoupDocument:seed-record'] };+ case 'clear':+ return { kind };+ }+};++const isMiss = (value: unknown): boolean =>+ typeof value === 'object' &&+ value !== null &&+ (value as { kind?: unknown }).kind === 'miss';++const isHit = (value: unknown): boolean =>+ typeof value === 'object' &&+ value !== null &&+ (value as { kind?: unknown }).kind === 'hit';++const admissionBarrierRequest = (): ProductionCacheRequestWithoutId => ({+ kind: 'read',+ query: QUERY.replace('query Soup', 'query CacheAdmissionBarrier'),+ operationName: 'CacheAdmissionBarrier',+ variables: VARIABLES,+});++async function runFaultKind(kind: MutatingRequestKind) {+ assert(+ CACHE_MUTATING_REQUEST_KINDS.includes(kind),+ `unsupported mutating request kind ${kind}`+ );+ const session = new ProductionSession(+ `cache-recovery-fault-${kind}-${crypto.randomUUID()}`+ );+ try {+ await session.openTab('fault-tab');+ await session.command('fault-tab', {+ kind: 'request',+ request: writeRequest('seed-record'),+ });+ const owner = `seed-owner-${kind}`;+ const seed = seededMutation(+ await session.command('fault-tab', {+ kind: 'request',+ request: enqueueRequest(owner, 10),+ }),+ owner+ );+ await session.command('fault-tab', {+ kind: 'arm-mutation-block',+ requestKind: kind,+ });+ await waitUntil('mutation block arm proof', () =>+ session.runtimeTelemetry.some(+ (event) =>+ event.kind === 'mutation-block-armed' && event.requestKind === kind+ )+ );+ const armIndex = session.runtimeTelemetry.findIndex(+ (event) =>+ event.kind === 'mutation-block-armed' && event.requestKind === kind+ );+ const oldRequest = session+ .command('fault-tab', {+ kind: 'request',+ request: blockedRequest(kind, seed),+ })+ .then(+ () => ({ rejected: false, error: '' }),+ (error: unknown) => ({+ rejected: true,+ error: error instanceof Error ? error.message : String(error),+ })+ );+ await waitUntil('request admitted and blocked before core', () =>+ session.runtimeTelemetry.some(+ (event) =>+ event.kind === 'request-blocked-before-core' &&+ event.requestKind === kind+ )+ );+ const blocked = session.runtimeTelemetry.find(+ (event) =>+ event.kind === 'request-blocked-before-core' &&+ event.requestKind === kind+ );+ assert(blocked?.requestId !== undefined, 'missing blocked request id');+ const readyBefore = session.runtimeTelemetry.filter(+ (event) => event.kind === 'ready'+ ).length;+ const telemetryBeforeLoss = session.cacheTelemetry.length;+ await session.command('fault-tab', { kind: 'terminate-worker' });+ const old = await oldRequest;+ assert(old.rejected, 'old admitted request did not reject');+ await waitUntil(+ 'replacement ready after actual worker termination',+ () =>+ session.runtimeTelemetry.filter((event) => event.kind === 'ready')+ .length > readyBefore+ );+ const replacementReadyIndex = session.runtimeTelemetry.findLastIndex(+ (event) => event.kind === 'ready'+ );+ assert(replacementReadyIndex > armIndex, 'missing replacement ready index');+ await session.command('fault-tab', {+ kind: 'request',+ request: admissionBarrierRequest(),+ });+ await waitUntil('replacement request-admission barrier', () =>+ session.runtimeTelemetry+ .slice(replacementReadyIndex + 1)+ .some((event) => event.admissionBarrier === true)+ );+ const barrierIndex = session.runtimeTelemetry.findIndex(+ (event, index) =>+ index > replacementReadyIndex && event.admissionBarrier === true+ );+ assert(barrierIndex > replacementReadyIndex, 'missing admission barrier');+ const mutationAdmissions = session.runtimeTelemetry+ .slice(armIndex, replacementReadyIndex + 1)+ .filter(+ (event) =>+ event.kind === 'request-admitted' && event.requestKind === kind+ );+ assert(mutationAdmissions.length === 1, 'mutating request was replayed');+ assert(+ mutationAdmissions[0]?.requestId === blocked.requestId,+ 'blocked admission proof did not identify the routed request'+ );+ const mutatingKinds = new Set<string>(CACHE_MUTATING_REQUEST_KINDS);+ const unexpectedReplacementMutatingAdmissions = session.runtimeTelemetry+ .slice(replacementReadyIndex + 1, barrierIndex + 1)+ .filter(+ (event) =>+ event.kind === 'request-admitted' &&+ mutatingKinds.has(String(event.requestKind))+ );+ assert(+ unexpectedReplacementMutatingAdmissions.length === 0,+ 'replacement admitted unexpected replayed mutation work'+ );++ const replacementRead = await session.command('fault-tab', {+ kind: 'request',+ request: {+ kind: 'read',+ query: QUERY,+ operationName: 'Soup',+ variables: VARIABLES,+ },+ });+ const replacementClaim = await session.command('fault-tab', {+ kind: 'request',+ request: {+ kind: 'claim-next-mutation',+ owner: 'replacement-probe',+ nowMs: 10_000,+ leaseExpiresAtMs: 11_000,+ },+ });+ assert(isMiss(replacementRead), 'replacement retained a durable record');+ assert(+ replacementClaim === undefined || replacementClaim === null,+ 'replacement retained the durable queue'+ );+ const ready = session.runtimeTelemetry+ .filter((event) => event.kind === 'ready')+ .at(-1);+ await waitUntil('authoritative reset phase sequence', () =>+ session.cacheTelemetry+ .slice(telemetryBeforeLoss)+ .some((event) => event.name === 'graphql_cache.reset_wipe')+ );+ const resetTelemetry = session.cacheTelemetry.slice(telemetryBeforeLoss);+ const resetPhaseSequence = resetTelemetry+ .filter((event) =>+ [+ 'graphql_cache.storage_reset_required',+ 'graphql_cache.logical_reset',+ 'graphql_cache.reset_wipe',+ ].includes(String(event.name))+ )+ .map((event) => event.name);+ assert(+ JSON.stringify(resetPhaseSequence) ===+ JSON.stringify([+ 'graphql_cache.storage_reset_required',+ 'graphql_cache.logical_reset',+ 'graphql_cache.reset_wipe',+ ]),+ `unexpected reset phase sequence ${JSON.stringify(resetPhaseSequence)}`+ );+ await session.gracefulClose('fault-tab');+ return {+ kind,+ actualDedicatedWorkerTerminated: true,+ requestAdmittedBeforeCore: true,+ midSqlExecutionClaimed: false,+ oldRequestRejected: old.rejected,+ replacementRecordsEmpty: true,+ replacementQueueEmpty: true,+ mutationAdmissionCount: mutationAdmissions.length,+ unexpectedReplacementMutatingAdmissionCount:+ unexpectedReplacementMutatingAdmissions.length,+ replacementAdmissionBarrierObserved: true,+ resetPhaseSequence,+ exactProductionTursoWasm: true,+ performanceMemoryAvailable: ready?.performanceMemoryAvailable ?? false,+ userAgentSpecificMemoryAvailable:+ ready?.userAgentSpecificMemoryAvailable ?? false,+ queueTelemetryObserved: session.cacheTelemetry.some(+ (event) =>+ event.name === 'graphql_cache.queue_diagnostics' &&+ event.queueDepth === 0+ ),+ };+ } finally {+ session.close();+ }+}++async function applyStorageMutation(+ scope: string,+ kind: RecoveryKind+): Promise<string> {+ const worker = new Worker(+ new URL('./production-cache.storage-control-worker.ts', import.meta.url),+ { type: 'module', name: `cache-recovery-storage-control:${kind}` }+ );+ try {+ return await new Promise<string>((resolve, reject) => {+ const timeout = setTimeout(+ () => reject(new Error('storage-control worker timed out')),+ 30_000+ );+ worker.onmessage = (+ event: MessageEvent<{+ id: number;+ ok: boolean;+ wasmUrl?: string;+ error?: string;+ }>+ ) => {+ if (event.data.id !== 1) return;+ clearTimeout(timeout);+ if (event.data.ok && event.data.wasmUrl) resolve(event.data.wasmUrl);+ else reject(new Error(event.data.error ?? 'storage-control failed'));+ };+ worker.onerror = (event) => {+ clearTimeout(timeout);+ reject(new Error(event.message));+ };+ worker.postMessage({ id: 1, scope, kind });+ });+ } finally {+ worker.terminate();+ }+}++async function runRecoveryKind(kind: RecoveryKind) {+ const scope = `cache-recovery-${kind}-${crypto.randomUUID()}`;+ const session = new ProductionSession(scope);+ try {+ await session.openTab('before-corruption');+ await session.command('before-corruption', {+ kind: 'request',+ request: writeRequest('must-reset'),+ });+ await session.command('before-corruption', {+ kind: 'request',+ request: enqueueRequest('recovery-seed-owner', 10),+ });+ await session.gracefulClose('before-corruption');+ const browserTestWasmUrl = await applyStorageMutation(scope, kind);+ const telemetryBeforeReopen = session.cacheTelemetry.length;+ await session.openTab('after-corruption');+ await waitUntil('recovery outcome and authoritative wipe telemetry', () => {+ const events = session.cacheTelemetry.slice(telemetryBeforeReopen);+ return (+ events.some((event) =>+ String(event.openOutcome).startsWith('reset-')+ ) && events.some((event) => event.name === 'graphql_cache.reset_wipe')+ );+ });+ const replacementTelemetry = session.cacheTelemetry.slice(+ telemetryBeforeReopen+ );+ const expectedOutcome =+ kind === 'incompatible-namespace'+ ? 'reset-incompatible'+ : 'reset-corrupt';+ const replacementRead = await session.command('after-corruption', {+ kind: 'request',+ request: {+ kind: 'read',+ query: QUERY,+ operationName: 'Soup',+ variables: VARIABLES,+ },+ });+ const replacementClaim = await session.command('after-corruption', {+ kind: 'request',+ request: {+ kind: 'claim-next-mutation',+ owner: 'recovery-probe',+ nowMs: 10_000,+ leaseExpiresAtMs: 11_000,+ },+ });+ assert(isMiss(replacementRead), 'recovery retained a durable record');+ assert(+ replacementClaim === undefined || replacementClaim === null,+ 'recovery retained the durable queue'+ );+ await session.command('after-corruption', {+ kind: 'request',+ request: writeRequest('usable-after-reset'),+ });+ const usableRead = await session.command('after-corruption', {+ kind: 'request',+ request: {+ kind: 'read',+ query: QUERY,+ operationName: 'Soup',+ variables: VARIABLES,+ },+ });+ assert(isHit(usableRead), 'recovered cache was not usable');+ const phaseCount = (name: string): number =>+ replacementTelemetry.filter((event) => event.name === name).length;+ assert(+ replacementTelemetry.some(+ (event) => event.openOutcome === expectedOutcome+ ),+ `missing ${expectedOutcome} telemetry`+ );+ for (const phase of [+ 'graphql_cache.storage_reset_required',+ 'graphql_cache.logical_reset',+ 'graphql_cache.reset_wipe',+ ]) {+ assert(phaseCount(phase) === 1, `${phase} was not emitted exactly once`);+ }+ await session.gracefulClose('after-corruption');+ return {+ kind,+ gracefulCloseBeforeMutation: true,+ separateFeatureGatedBrowserTestArtifact: true,+ productionArtifactDebugExportsAbsent: true,+ browserTestWasmUrl,+ browserTestWorkerOnlyControl: true,+ productionCoordinatorProtocolUnchanged: true,+ openOutcome: expectedOutcome,+ recordsWiped: true,+ durableQueueWiped: true,+ usableAfterReset: true,+ storageResetRequiredCount: phaseCount(+ 'graphql_cache.storage_reset_required'+ ),+ logicalResetCount: phaseCount('graphql_cache.logical_reset'),+ resetWipeCount: phaseCount('graphql_cache.reset_wipe'),+ queueTelemetryObserved: replacementTelemetry.some(+ (event) =>+ event.name === 'graphql_cache.queue_diagnostics' &&+ event.queueDepth === 0+ ),+ };+ } finally {+ session.close();+ }+}++const api = {+ mutatingRequestKinds: CACHE_MUTATING_REQUEST_KINDS,+ runFaultKind,+ runRecoveryKind,+};++declare global {+ interface Window {+ cacheRecoveryHarness: typeof api;+ }+}++window.cacheRecoveryHarness = api;+resultElement.dataset.status = 'ready';+resultElement.textContent = JSON.stringify({+ productionInertHooks: true,+ publicCoordinatorProtocolUnchanged: true,+ mutatingRequestKinds: CACHE_MUTATING_REQUEST_KINDS,+});diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/cache-recovery.html b/apps/web/src/lib/graphql-cache/worker/browser-test/cache-recovery.htmlnew file mode 100644index 0000000000..e4d2d7abdf--- /dev/null+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/cache-recovery.html@@ -0,0 +1,8 @@+<!doctype html>+<html lang="en">+ <head><meta charset="UTF-8" /><title>Cache internal browser harness</title></head>+ <body>+ <pre id="result" data-status="loading"></pre>+ <script type="module" src="./cache-recovery-harness.ts"></script>+ </body>+</html>diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/cache-wasm-packaging.browser.e2e.ts b/apps/web/src/lib/graphql-cache/worker/browser-test/cache-wasm-packaging.browser.e2e.tsnew file mode 100644index 0000000000..60118316e5--- /dev/null+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/cache-wasm-packaging.browser.e2e.ts@@ -0,0 +1,262 @@+import { expect, type Page, test } from '@playwright/test';+import { CACHE_WASM_BUDGETS } from '../../../../../scripts/cache-wasm/budgets';+import type { CacheWasmPerformanceSample } from './performance-harness';++type CacheWasmBrowserSample = CacheWasmPerformanceSample & {+ browser: 'chromium' | 'firefox';+ wasmUrl: string;+};++const percentile95 = (values: number[]): number =>+ [...values].sort((left, right) => left - right)[+ Math.ceil(values.length * 0.95) - 1+ ]!;++const SAMPLE_COUNT = 5;+const isProductionProject = (projectName: string): boolean =>+ projectName.includes('production');+const harnessPath = (projectName: string, page: string): string =>+ isProductionProject(projectName) ? `/app/${page}` : `/${page}`;++async function fetchedWasmEvidence(+ page: Page,+ wasmUrl: string+): Promise<{+ contentType: string | null;+ contentEncoding: string | null;+ validModule: boolean;+ sha256: string;+}> {+ return await page.evaluate(async (url) => {+ const response = await fetch(url);+ const bytes = await response.arrayBuffer();+ const [module, digest] = await Promise.all([+ WebAssembly.compile(bytes),+ crypto.subtle.digest('SHA-256', bytes),+ ]);+ return {+ contentType: response.headers.get('content-type'),+ contentEncoding: response.headers.get('content-encoding'),+ validModule: module instanceof WebAssembly.Module,+ sha256: [...new Uint8Array(digest)]+ .map((byte) => byte.toString(16).padStart(2, '0'))+ .join(''),+ };+ }, wasmUrl);+}++test('exact production CacheHost reaches the exact engine URL without a wrapper', async ({+ context,+ page,+}, testInfo) => {+ const requests: string[] = [];+ const wasmResponses: string[] = [];+ context.on('request', (request) => requests.push(request.url()));+ context.on('response', (response) => {+ if (new URL(response.url()).pathname.endsWith('.wasm')) {+ wasmResponses.push(response.url());+ }+ });++ await page.goto(+ harnessPath(testInfo.project.name, 'exact-production-host.html')+ );+ const result = page.locator('#result');+ await expect(result).toHaveAttribute('data-status', 'passed', {+ timeout: 30_000,+ });+ const report = JSON.parse((await result.textContent()) ?? '') as {+ sharedWorkerConstructions: number;+ dedicatedWorkerConstructions: number;+ engineWorkerUrl: string;+ crossOriginIsolated: boolean;+ sharedArrayBufferAvailable: boolean;+ };+ expect(report).toMatchObject({+ sharedWorkerConstructions: 1,+ dedicatedWorkerConstructions: 1,+ crossOriginIsolated: false,+ sharedArrayBufferAvailable: false,+ });+ expect(report.engineWorkerUrl).toContain('cache.engine-worker');+ expect(report.engineWorkerUrl).not.toContain('instrumented-cache');+ expect(+ requests.filter((url) => url.includes('instrumented-cache.engine-worker'))+ ).toEqual([]);+ expect(+ requests.filter((url) => url.includes('cache.engine-worker'))+ ).toHaveLength(1);+ expect(wasmResponses).toHaveLength(1);+ const served = await fetchedWasmEvidence(page, wasmResponses[0]);+ expect(served).toEqual({+ contentType: expect.stringContaining('application/wasm'),+ contentEncoding: isProductionProject(testInfo.project.name) ? 'br' : null,+ validModule: true,+ sha256: expect.stringMatching(/^[a-f0-9]{64}$/),+ });+});++test('combined cache WASM stays lazy and meets fresh-scope startup budgets', async ({+ context,+ page,+}, testInfo) => {+ const requests: string[] = [];+ const wasmResponses: string[] = [];+ const browserName = testInfo.project.name.includes('firefox')+ ? 'firefox'+ : 'chromium';+ context.on('request', (request) => requests.push(request.url()));+ context.on('response', (response) => {+ if (new URL(response.url()).pathname.endsWith('.wasm')) {+ wasmResponses.push(response.url());+ }+ });++ await page.goto(harnessPath(testInfo.project.name, 'performance.html'));+ await expect(page.locator('#result')).toHaveAttribute('data-status', 'idle');+ await page.waitForTimeout(250);+ expect(+ requests.filter((url) => {+ const parsed = new URL(url);+ if (parsed.pathname.includes('cache_wasm')) return true;+ const enginePath =+ /(?:cache[.-]engine-worker|instrumented-cache\.engine-worker)/.test(+ parsed.pathname+ );+ // Vite dev loads a tiny `?worker&url` URL-export module eagerly; it does+ // not fetch or execute the worker script (`?worker_file`) or WASM.+ return (+ enginePath &&+ (!parsed.searchParams.has('worker') ||+ parsed.searchParams.has('worker_file'))+ );+ })+ ).toEqual([]);++ const samples: CacheWasmBrowserSample[] = [];+ for (let index = 0; index < SAMPLE_COUNT; index++) {+ const responseCountBefore = wasmResponses.length;+ let measurement: CacheWasmPerformanceSample;+ try {+ measurement = await page.evaluate(async () => {+ const run = (+ window as typeof window & {+ runCacheWasmPerformanceSample(): Promise<CacheWasmPerformanceSample>;+ }+ ).runCacheWasmPerformanceSample;+ return await run();+ });+ } catch (error) {+ throw new Error(+ `${error instanceof Error ? error.message : String(error)}\nrequests:\n${requests.join('\n')}`+ );+ }+ const sampleWasmResponses = wasmResponses.slice(responseCountBefore);+ expect(sampleWasmResponses).toHaveLength(1);+ expect(measurement.wasmFetchCount).toBe(sampleWasmResponses.length);+ expect(measurement.wasmSha256).toMatch(/^[a-f0-9]{64}$/);+ samples.push({+ ...measurement,+ browser: browserName,+ wasmUrl: sampleWasmResponses[0],+ });+ }++ const mode = samples[0].mode;+ const production = mode === 'production';+ expect(production).toBe(isProductionProject(testInfo.project.name));+ expect(samples).toHaveLength(SAMPLE_COUNT);+ for (const sample of samples) {+ expect(sample).toMatchObject({+ mode,+ sharedWorkerConstructions: 1,+ dedicatedWorkerConstructions: 1,+ nestedWorkerConstructions: 0,+ ownerEpochs: [1],+ crossOriginIsolated: false,+ sharedArrayBufferAvailable: false,+ });+ expect(sample.linearMemoryBytes).toBeLessThanOrEqual(+ CACHE_WASM_BUDGETS.linearMemoryBytes+ );+ expect(sample.productionEngineUrl).not.toBe(sample.instrumentedEngineUrl);+ }++ const sharedWorkerUrls = [+ ...new Set(samples.map((sample) => sample.sharedWorkerUrl)),+ ];+ const productionEngineUrls = [+ ...new Set(samples.map((sample) => sample.productionEngineUrl)),+ ];+ const instrumentedEngineUrls = [+ ...new Set(samples.map((sample) => sample.instrumentedEngineUrl)),+ ];+ const wasmUrls = [...new Set(samples.map((sample) => sample.wasmUrl))];+ expect(sharedWorkerUrls).toHaveLength(1);+ expect(productionEngineUrls).toHaveLength(1);+ expect(instrumentedEngineUrls).toHaveLength(1);+ expect(wasmUrls).toHaveLength(1);+ if (mode === 'development') {+ expect(sharedWorkerUrls[0]).toContain(+ '/src/lib/graphql-cache/worker/cache.coordinator.shared-worker.ts'+ );+ expect(productionEngineUrls[0]).toContain(+ '/src/lib/graphql-cache/worker/cache.engine-worker.ts'+ );+ expect(instrumentedEngineUrls[0]).toContain(+ '/instrumented-cache.engine-worker.ts'+ );+ } else {+ expect(sharedWorkerUrls[0]).toMatch(+ /\/app\/assets\/cache\.coordinator\.shared-worker-[\w-]+\.js$/+ );+ expect(productionEngineUrls[0]).toMatch(+ /\/app\/assets\/cache\.engine-worker-[\w-]+\.js$/+ );+ expect(instrumentedEngineUrls[0]).toMatch(+ /\/app\/assets\/instrumented-cache\.engine-worker-[\w-]+\.js$/+ );+ expect(wasmUrls[0]).toMatch(/\/app\/assets\/cache_wasm_bg-[\w-]+\.wasm$/);+ }++ const browserReadyP95Ms = percentile95(+ samples.map((sample) => sample.browserReadyMs)+ );+ const hostFirstReadyP95Ms = percentile95(+ samples.map((sample) => sample.hostFirstReadyMs)+ );+ expect(browserReadyP95Ms).toBeLessThanOrEqual(+ CACHE_WASM_BUDGETS.browserReadyP95Ms+ );+ expect(hostFirstReadyP95Ms).toBeLessThanOrEqual(+ CACHE_WASM_BUDGETS.hostFirstReadyP95Ms+ );+ // The instrumented engine clones and hashes each actual decoded runtime+ // response, so artifact binding adds no second WASM request.+ expect(wasmResponses).toHaveLength(SAMPLE_COUNT);+ const wasmHashes = [...new Set(samples.map((sample) => sample.wasmSha256))];+ expect(wasmHashes).toHaveLength(1);++ if (production) {+ for (const workerUrl of [+ sharedWorkerUrls[0],+ productionEngineUrls[0],+ instrumentedEngineUrls[0],+ ]) {+ const evidence = await page.evaluate(async (mapUrl) => {+ const response = await fetch(mapUrl);+ const value = (await response.json()) as { sources?: unknown };+ return {+ ok: response.ok,+ contentType: response.headers.get('content-type'),+ hasSources: Array.isArray(value.sources) && value.sources.length > 0,+ };+ }, `${workerUrl}.map`);+ expect(evidence).toEqual({+ ok: true,+ contentType: expect.stringContaining('application/json'),+ hasSources: true,+ });+ }+ }+});diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/coordinator.browser.e2e.ts b/apps/web/src/lib/graphql-cache/worker/browser-test/coordinator.browser.e2e.tsnew file mode 100644index 0000000000..b1aa8898e8--- /dev/null+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/coordinator.browser.e2e.ts@@ -0,0 +1,216 @@+import { expect, test } from '@playwright/test';++const harnessPath = (projectName: string, path = ''): string =>+ projectName.includes('production') ? `/app/${path}` : `/${path}`;++test('three pages fence graceful, abrupt, stale, and worker-only ownership', async ({+ context,+ page,+}, testInfo) => {+ const browserErrors: string[] = [];+ const watch = (candidate: typeof page): void => {+ candidate.on('console', (message) => {+ if (message.type() === 'error') browserErrors.push(message.text());+ });+ candidate.on('pageerror', (error) => browserErrors.push(error.message));+ };+ watch(page);+ context.on('page', watch);++ await page.goto(harnessPath(testInfo.project.name));+ const result = page.locator('#result');+ await expect(result).toHaveAttribute('data-status', 'passed', {+ timeout: 40_000,+ });+ const report = JSON.parse((await result.textContent()) ?? '') as {+ passed: boolean;+ openedTabs: number;+ ownerEpochs: number[];+ maxWorkersPerEpoch: number;+ noEagerWorker: boolean;+ collidingRequestIdsRewritten: boolean;+ gracefulPreserved: boolean;+ abruptRejectedInflight: boolean;+ abruptWiped: boolean;+ workerOnlyPageStayedAlive: boolean;+ workerOnlyWiped: boolean;+ livenessPageStayedAlive: boolean;+ livenessTerminationReason: string;+ livenessWiped: boolean;+ staleMessageDrops: number;+ staleMessagePortResponseDropped: boolean;+ pushReachedAllTabs: boolean;+ ownerLockContentionEpochs: number[];+ engineReplacedEpochs: number[];+ protocolErrors: string[];+ };++ expect(report).toMatchObject({+ passed: true,+ openedTabs: 3,+ ownerEpochs: [1, 2, 3, 4],+ maxWorkersPerEpoch: 1,+ noEagerWorker: true,+ collidingRequestIdsRewritten: true,+ gracefulPreserved: true,+ abruptRejectedInflight: true,+ abruptWiped: true,+ workerOnlyPageStayedAlive: true,+ workerOnlyWiped: true,+ livenessPageStayedAlive: true,+ livenessTerminationReason: 'tab liveness lock was released',+ livenessWiped: true,+ staleMessageDrops: 1,+ staleMessagePortResponseDropped: true,+ pushReachedAllTabs: true,+ ownerLockContentionEpochs: [1, 2, 3, 4],+ engineReplacedEpochs: [2, 3, 4],+ protocolErrors: [],+ });+ expect(browserErrors).toEqual([]);+});++test('production CacheHost performs fresh init and active reread after owner loss', async ({+ context,+ page,+}, testInfo) => {+ const browserErrors: string[] = [];+ const watch = (candidate: typeof page): void => {+ candidate.on('console', (message) => {+ if (message.type() === 'error') browserErrors.push(message.text());+ });+ candidate.on('pageerror', (error) => browserErrors.push(error.message));+ };+ watch(page);+ context.on('page', watch);++ await page.goto(harnessPath(testInfo.project.name, 'host.html'));+ const result = page.locator('#result');+ await expect(result).toHaveAttribute('data-status', 'passed', {+ timeout: 60_000,+ });+ const report = JSON.parse((await result.textContent()) ?? '') as {+ passed: boolean;+ noEagerConstructor: boolean;+ requestOrder: Array<[number, number, string]>;+ oldEpochRejectedBeforeReplacement: boolean;+ oldRequestReplayCount: number;+ replacementActiveKeys: number[][];+ replacementReadCompleted: boolean;+ gracefulDrained: boolean;+ terminatedEpochs: number[];+ sharedPortClosed: boolean;+ initializationErrors: string[];+ };++ expect(report).toEqual({+ passed: true,+ noEagerConstructor: true,+ requestOrder: [+ [1, 1, 'init'],+ [1, 2, 'read'],+ [1, 3, 'read'],+ [1, 4, 'read'],+ [2, 5, 'init'],+ [2, 6, 'read'],+ ],+ oldEpochRejectedBeforeReplacement: true,+ oldRequestReplayCount: 1,+ replacementActiveKeys: [[7, 9]],+ replacementReadCompleted: true,+ gracefulDrained: true,+ terminatedEpochs: [1, 2],+ sharedPortClosed: true,+ initializationErrors: [],+ });+ expect(browserErrors).toEqual([]);+});++test('direct cutover lazily deletes only the former normalized-cache IDB', async ({+ page,+}, testInfo) => {+ const browserErrors: string[] = [];+ page.on('console', (message) => {+ if (message.type() === 'error') browserErrors.push(message.text());+ });+ page.on('pageerror', (error) => browserErrors.push(error.message));++ await page.goto(harnessPath(testInfo.project.name, 'cutover.html'));+ const result = page.locator('#result');+ await expect(result).toHaveAttribute('data-status', 'passed', {+ timeout: 60_000,+ });+ const report = JSON.parse((await result.textContent()) ?? '') as {+ passed: boolean;+ noEagerDeletion: boolean;+ deletionRequestedOnFirstUse: boolean;+ blockedDeletionDidNotBlockHost: boolean;+ legacyDeletionCompletedLater: boolean;+ unrelatedIdbPreserved: boolean;+ };++ expect(report).toEqual({+ passed: true,+ noEagerDeletion: true,+ deletionRequestedOnFirstUse: true,+ blockedDeletionDidNotBlockHost: true,+ legacyDeletionCompletedLater: true,+ unrelatedIdbPreserved: true,+ });+ expect(browserErrors).toEqual([]);+});++test('production cache-wasm Turso engine preserves graceful data and atomically recovers abrupt loss', async ({+ context,+ page,+}, testInfo) => {+ const browserErrors: string[] = [];+ const watch = (candidate: typeof page): void => {+ candidate.on('console', (message) => {+ if (message.type() === 'error') browserErrors.push(message.text());+ });+ candidate.on('pageerror', (error) => browserErrors.push(error.message));+ };+ watch(page);+ context.on('page', watch);++ await page.goto(harnessPath(testInfo.project.name, 'production.html'));+ const result = page.locator('#result');+ await expect(result).toHaveAttribute('data-status', 'passed', {+ timeout: 60_000,+ });+ const report = JSON.parse((await result.textContent()) ?? '') as {+ passed: boolean;+ realTursoDataPreservedGracefully: boolean;+ gracefulCloseReleasedOwnerLock: boolean;+ gracefulReplacementWaitedForPhysicalLock: boolean;+ gracefulPendingOwnerLockRequests: number;+ abruptInflightRejected: boolean;+ abruptRequestReplayCount: number;+ abruptOwnerPageStayedAlive: boolean;+ recoveryReplacementWaitedForPhysicalLock: boolean;+ recoveryPendingOwnerLockRequests: number;+ atomicRecoveryOpenWipedToMiss: boolean;+ recoveryDatabaseAction: string;+ ownerEpochs: number[];+ protocolErrors: string[];+ };++ expect(report).toEqual({+ passed: true,+ realTursoDataPreservedGracefully: true,+ gracefulCloseReleasedOwnerLock: true,+ gracefulReplacementWaitedForPhysicalLock: true,+ gracefulPendingOwnerLockRequests: 1,+ abruptInflightRejected: true,+ abruptRequestReplayCount: 1,+ abruptOwnerPageStayedAlive: true,+ recoveryReplacementWaitedForPhysicalLock: true,+ recoveryPendingOwnerLockRequests: 1,+ atomicRecoveryOpenWipedToMiss: true,+ recoveryDatabaseAction: 'wipe-before-open',+ ownerEpochs: [1, 2, 3],+ protocolErrors: [],+ });+ expect(browserErrors).toEqual([]);+});diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/cutover-harness.ts b/apps/web/src/lib/graphql-cache/worker/browser-test/cutover-harness.tsnew file mode 100644index 0000000000..909f444f27--- /dev/null+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/cutover-harness.ts@@ -0,0 +1,129 @@+import { createWorkerCacheHost } from '../../host/worker-host';++const resultNode = document.querySelector('#result');+if (!(resultNode instanceof HTMLElement))+ throw new Error('missing result node');++const scope = `wp10-cutover-${crypto.randomUUID()}`;+const legacyName = `graphql-cache:${scope}`;+const unrelatedName = `unrelated-idb:${scope}`;+const STORE = 'records';+const MARKER_KEY = 'keep';+const MARKER_VALUE = 'unrelated-data';++const openDatabase = (+ name: string,+ initialize?: (database: IDBDatabase) => void+): Promise<IDBDatabase> =>+ new Promise((resolve, reject) => {+ const request = indexedDB.open(name, 1);+ request.onupgradeneeded = () => initialize?.(request.result);+ request.onsuccess = () => resolve(request.result);+ request.onerror = () =>+ reject(request.error ?? new Error('IDB open failed'));+ });++const writeMarker = (database: IDBDatabase): Promise<void> =>+ new Promise((resolve, reject) => {+ const transaction = database.transaction(STORE, 'readwrite');+ transaction.objectStore(STORE).put(MARKER_VALUE, MARKER_KEY);+ transaction.oncomplete = () => resolve();+ transaction.onerror = () =>+ reject(transaction.error ?? new Error('IDB marker write failed'));+ transaction.onabort = transaction.onerror;+ });++const readMarker = (database: IDBDatabase): Promise<unknown> =>+ new Promise((resolve, reject) => {+ const request = database+ .transaction(STORE, 'readonly')+ .objectStore(STORE)+ .get(MARKER_KEY);+ request.onsuccess = () => resolve(request.result);+ request.onerror = () =>+ reject(request.error ?? new Error('IDB marker read failed'));+ });++const databaseExists = async (name: string): Promise<boolean> =>+ (await indexedDB.databases()).some((database) => database.name === name);++const waitUntil = async (+ label: string,+ predicate: () => boolean | Promise<boolean>,+ timeoutMs = 20_000+): Promise<void> => {+ const deadline = performance.now() + timeoutMs;+ while (!(await predicate())) {+ if (performance.now() >= deadline) throw new Error(`${label} timed out`);+ await new Promise((resolve) => setTimeout(resolve, 10));+ }+};++const deleteDatabase = (name: string): Promise<void> =>+ new Promise((resolve) => {+ const request = indexedDB.deleteDatabase(name);+ request.onsuccess = () => resolve();+ request.onerror = () => resolve();+ request.onblocked = () => resolve();+ });++const report: Record<string, unknown> = {+ passed: false,+ noEagerDeletion: false,+ deletionRequestedOnFirstUse: false,+ blockedDeletionDidNotBlockHost: false,+ legacyDeletionCompletedLater: false,+ unrelatedIdbPreserved: false,+};++let legacy: IDBDatabase | undefined;+let unrelated: IDBDatabase | undefined;+try {+ legacy = await openDatabase(legacyName, (database) => {+ database.createObjectStore(STORE);+ });+ unrelated = await openDatabase(unrelatedName, (database) => {+ database.createObjectStore(STORE);+ });+ await writeMarker(unrelated);++ let legacyVersionChange = false;+ legacy.onversionchange = () => {+ legacyVersionChange = true;+ // Deliberately remain open so the cutover request reaches `blocked`.+ };++ const host = createWorkerCacheHost({ scope, requestTimeoutMs: 20_000 });+ await new Promise((resolve) => setTimeout(resolve, 0));+ report.noEagerDeletion = !legacyVersionChange;++ await host.clear();+ report.deletionRequestedOnFirstUse = legacyVersionChange;+ report.blockedDeletionDidNotBlockHost = await databaseExists(legacyName);++ legacy.close();+ legacy = undefined;+ await waitUntil(+ 'legacy normalized cache deletion',+ async () => !(await databaseExists(legacyName))+ );+ report.legacyDeletionCompletedLater = true;+ report.unrelatedIdbPreserved =+ (await databaseExists(unrelatedName)) &&+ (await readMarker(unrelated)) === MARKER_VALUE;++ host.dispose();+ report.passed = Object.entries(report)+ .filter(([key]) => key !== 'passed')+ .every(([, value]) => value === true);+} catch (error) {+ report.error = error instanceof Error ? error.message : String(error);+} finally {+ legacy?.close();+ unrelated?.close();+ await deleteDatabase(legacyName);+ await deleteDatabase(unrelatedName);+}++resultNode.dataset.status = report.passed ? 'passed' : 'failed';+resultNode.textContent = JSON.stringify(report);diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/cutover.html b/apps/web/src/lib/graphql-cache/worker/browser-test/cutover.htmlnew file mode 100644index 0000000000..da5270ab02--- /dev/null+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/cutover.html@@ -0,0 +1,13 @@+<!doctype html>+<html lang="en">+ <head>+ <meta charset="UTF-8" />+ <meta name="viewport" content="width=device-width, initial-scale=1.0" />+ <link rel="icon" href="data:," />+ <title>WP-10 normalized cache IDB cutover harness</title>+ </head>+ <body>+ <pre id="result" data-status="running">running</pre>+ <script type="module" src="./cutover-harness.ts"></script>+ </body>+</html>diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/exact-production-host-harness.ts b/apps/web/src/lib/graphql-cache/worker/browser-test/exact-production-host-harness.tsnew file mode 100644index 0000000000..012f1a7ff3--- /dev/null+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/exact-production-host-harness.ts@@ -0,0 +1,67 @@+import { createWorkerCacheHost } from '../../host/worker-host';++const resultElement = document.querySelector<HTMLElement>('#result');+if (!resultElement) throw new Error('missing result element');++const NativeWorker = globalThis.Worker;+const NativeSharedWorker = globalThis.SharedWorker;+let sharedWorkerConstructions = 0;+let dedicatedWorkerConstructions = 0;+let engineWorkerUrl = '';+globalThis.SharedWorker = new Proxy(NativeSharedWorker, {+ construct(target, argumentsList) {+ sharedWorkerConstructions++;+ return Reflect.construct(target, argumentsList);+ },+});+globalThis.Worker = new Proxy(NativeWorker, {+ construct(target, argumentsList) {+ const [url, options] = argumentsList as ConstructorParameters<+ typeof Worker+ >;+ if (options?.name?.startsWith('graphql-cache-engine:')) {+ dedicatedWorkerConstructions++;+ engineWorkerUrl = String(url);+ }+ return Reflect.construct(target, argumentsList);+ },+});++const scope = `cache-exact-production-${crypto.randomUUID()}`;+const host = createWorkerCacheHost({+ scope,+ requestTimeoutMs: 15_000,+ initializationTimeoutMs: 15_000,+});++try {+ await host.readQuery({+ opKey: 1,+ query: `query CacheExactProduction($input: SoupInput!) {+ user {+ id+ soup(input: $input) {+ nextCursor+ items { __typename id }+ }+ }+ }`,+ operationName: 'CacheExactProduction',+ variables: { input: { limit: 1 } },+ });+ resultElement.textContent = JSON.stringify({+ sharedWorkerConstructions,+ dedicatedWorkerConstructions,+ engineWorkerUrl,+ crossOriginIsolated: globalThis.crossOriginIsolated,+ sharedArrayBufferAvailable:+ typeof globalThis.SharedArrayBuffer === 'function',+ });+ resultElement.dataset.status = 'passed';+} catch (error) {+ resultElement.textContent =+ error instanceof Error ? (error.stack ?? error.message) : String(error);+ resultElement.dataset.status = 'failed';+} finally {+ host.dispose();+}diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/exact-production-host.html b/apps/web/src/lib/graphql-cache/worker/browser-test/exact-production-host.htmlnew file mode 100644index 0000000000..92d6d1137e--- /dev/null+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/exact-production-host.html@@ -0,0 +1,12 @@+<!doctype html>+<html lang="en">+ <head>+ <meta charset="UTF-8" />+ <meta name="viewport" content="width=device-width, initial-scale=1.0" />+ <title>Exact production cache host smoke</title>+ </head>+ <body>+ <pre id="result" data-status="running"></pre>+ <script type="module" src="./exact-production-host-harness.ts"></script>+ </body>+</html>diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/fake-cache.engine-worker.ts b/apps/web/src/lib/graphql-cache/worker/browser-test/fake-cache.engine-worker.tsnew file mode 100644index 0000000000..be7852b2b4--- /dev/null+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/fake-cache.engine-worker.ts@@ -0,0 +1,323 @@+/// <reference lib="webworker" />++import type { CacheRequest, CacheResponse } from '../../protocol';+import {+ CACHE_COORDINATOR_PROTOCOL_VERSION,+ type CoordinatorToEngineEnvelope,+ type EngineToCoordinatorEnvelope,+ type PageToEngineEnvelope,+ validateCoordinatorToEngineEnvelope,+ validatePageToEngineEnvelope,+} from '../coordinator-protocol';++declare const self: DedicatedWorkerGlobalScope;++const withVersion = <T extends { coordinatorVersion: 1 }>(+ value: T extends unknown ? Omit<T, 'coordinatorVersion'> : never+): T =>+ ({+ coordinatorVersion: CACHE_COORDINATOR_PROTOCOL_VERSION,+ ...value,+ }) as unknown as T;++const databaseName = (scope: string): string =>+ `graphql-cache-wp08-browser:${scope}`;++const openDatabase = async (scope: string): Promise<IDBDatabase> =>+ await new Promise((resolve, reject) => {+ const request = indexedDB.open(databaseName(scope), 1);+ request.onupgradeneeded = () => {+ if (!request.result.objectStoreNames.contains('records')) {+ request.result.createObjectStore('records');+ }+ };+ request.onsuccess = () => resolve(request.result);+ request.onerror = () => reject(request.error ?? new Error('open failed'));+ });++const deleteDatabase = async (scope: string): Promise<void> =>+ await new Promise((resolve, reject) => {+ const request = indexedDB.deleteDatabase(databaseName(scope));+ request.onsuccess = () => resolve();+ request.onerror = () => reject(request.error ?? new Error('delete failed'));+ request.onblocked = () => reject(new Error('delete blocked'));+ });++const put = async (database: IDBDatabase, value: unknown): Promise<void> =>+ await new Promise((resolve, reject) => {+ const transaction = database.transaction('records', 'readwrite');+ transaction.objectStore('records').put(value, 'root');+ transaction.oncomplete = () => resolve();+ transaction.onerror = () =>+ reject(transaction.error ?? new Error('put failed'));+ });++const get = async (database: IDBDatabase): Promise<unknown | undefined> =>+ await new Promise((resolve, reject) => {+ const transaction = database.transaction('records', 'readonly');+ const request = transaction.objectStore('records').get('root');+ request.onsuccess = () => resolve(request.result);+ request.onerror = () => reject(request.error ?? new Error('get failed'));+ });++const clear = async (database: IDBDatabase): Promise<void> =>+ await new Promise((resolve, reject) => {+ const transaction = database.transaction('records', 'readwrite');+ transaction.objectStore('records').clear();+ transaction.oncomplete = () => resolve();+ transaction.onerror = () =>+ reject(transaction.error ?? new Error('clear failed'));+ });++const delay = async (milliseconds: number): Promise<void> =>+ await new Promise((resolve) => setTimeout(resolve, milliseconds));++let controlPort: MessagePort | undefined;+let activationValue: PageToEngineEnvelope | undefined;+let telemetry: BroadcastChannel | undefined;+let ignoreHeartbeats = false;++const sendStaleResponse = (ownerEpoch: number, routeId: number): void => {+ controlPort?.postMessage(+ withVersion<EngineToCoordinatorEnvelope>({+ kind: 'engine-response',+ ownerEpoch,+ routeId,+ response: { id: routeId, ok: true, result: 'stale-must-not-escape' },+ })+ );+};++const execute = async (+ database: IDBDatabase,+ request: CacheRequest+): Promise<CacheResponse> => {+ if (request.kind === 'read' && request.query.includes('Slow')) {+ await delay(10_000);+ }+ switch (request.kind) {+ case 'init':+ return { id: request.id, ok: true, result: null };+ case 'write':+ await put(database, request.data);+ return {+ id: request.id,+ ok: true,+ result: { changed: ['ROOT_QUERY'], affectedOps: [], reset: false },+ };+ case 'read': {+ const value = await get(database);+ return {+ id: request.id,+ ok: true,+ result:+ value === undefined ? { kind: 'miss' } : { kind: 'hit', data: value },+ };+ }+ case 'clear':+ await clear(database);+ return { id: request.id, ok: true, result: null };+ default:+ return {+ id: request.id,+ ok: false,+ error: `fake engine does not implement ${request.kind}`,+ };+ }+};++async function activate(+ activation: PageToEngineEnvelope,+ port: MessagePort+): Promise<void> {+ activationValue = activation;+ controlPort = port;+ telemetry = new BroadcastChannel(`graphql-cache-wp08:${activation.scope}`);+ await navigator.locks.request(+ activation.ownerLockName,+ { mode: 'exclusive' },+ async (lock) => {+ if (!lock) throw new Error('owner lock was not acquired');+ telemetry?.postMessage({+ kind: 'lock-acquired',+ tabId: activation.tabId,+ ownerEpoch: activation.ownerEpoch,+ });+ let database: IDBDatabase | undefined;+ let queue = Promise.resolve();+ let draining = false;+ let requestShutdown: (() => void) | undefined;+ const shutdown = new Promise<void>((resolve) => {+ requestShutdown = resolve;+ });+ try {+ if (activation.databaseAction === 'wipe-before-open') {+ telemetry?.postMessage({+ kind: 'wipe-started',+ ownerEpoch: activation.ownerEpoch,+ });+ await deleteDatabase(activation.scope);+ telemetry?.postMessage({+ kind: 'wipe-completed',+ ownerEpoch: activation.ownerEpoch,+ });+ }+ database = await openDatabase(activation.scope);+ const activeDatabase = database;+ port.onmessage = (event: MessageEvent<unknown>) => {+ const parsed = validateCoordinatorToEngineEnvelope(event.data);+ if (!parsed.ok) return;+ const message: CoordinatorToEngineEnvelope = parsed.value;+ if (message.ownerEpoch !== activation.ownerEpoch) return;+ switch (message.kind) {+ case 'heartbeat':+ if (!ignoreHeartbeats) {+ port.postMessage(+ withVersion<EngineToCoordinatorEnvelope>({+ kind: 'heartbeat-ack',+ ownerEpoch: activation.ownerEpoch,+ heartbeatId: message.heartbeatId,+ })+ );+ }+ break;+ case 'drain-engine':+ if (draining) return;+ draining = true;+ void queue.finally(() => requestShutdown?.());+ break;+ case 'engine-request':+ if (draining) return;+ telemetry?.postMessage({+ kind: 'request-started',+ tabId: activation.tabId,+ ownerEpoch: activation.ownerEpoch,+ routeId: message.routeId,+ requestKind: message.request.kind,+ requestId: message.request.id,+ slow:+ message.request.kind === 'read' &&+ message.request.query.includes('Slow'),+ });+ queue = queue.then(async () => {+ let response: CacheResponse;+ try {+ response = await execute(activeDatabase, message.request);+ } catch (error) {+ response = {+ id: message.request.id,+ ok: false,+ error:+ error instanceof Error ? error.message : String(error),+ };+ }+ port.postMessage(+ withVersion<EngineToCoordinatorEnvelope>({+ kind: 'engine-response',+ ownerEpoch: activation.ownerEpoch,+ routeId: message.routeId,+ response,+ })+ );+ if (+ response.ok &&+ (message.request.kind === 'write' ||+ message.request.kind === 'clear')+ ) {+ port.postMessage(+ withVersion<EngineToCoordinatorEnvelope>({+ kind: 'engine-push',+ ownerEpoch: activation.ownerEpoch,+ push: { kind: 'cache-changed' },+ })+ );+ }+ });+ break;+ }+ };+ port.start();+ port.postMessage(+ withVersion<EngineToCoordinatorEnvelope>({+ kind: 'engine-ready',+ tabId: activation.tabId,+ ownerEpoch: activation.ownerEpoch,+ ownerLockName: activation.ownerLockName,+ ownerLockHeld: true,+ databaseActionProof:+ activation.databaseAction === 'wipe-before-open'+ ? 'wiped-before-open'+ : 'opened-existing',+ openOutcome:+ activation.databaseAction === 'wipe-before-open'+ ? 'reset-storage-uncertain'+ : 'opened-existing',+ })+ );+ telemetry?.postMessage({+ kind: 'ready',+ tabId: activation.tabId,+ ownerEpoch: activation.ownerEpoch,+ });++ await shutdown;+ await queue;+ database.close();+ database = undefined;+ port.postMessage(+ withVersion<EngineToCoordinatorEnvelope>({+ kind: 'engine-drained',+ tabId: activation.tabId,+ ownerEpoch: activation.ownerEpoch,+ })+ );+ } finally {+ database?.close();+ telemetry?.postMessage({+ kind: 'lock-releasing',+ tabId: activation.tabId,+ ownerEpoch: activation.ownerEpoch,+ });+ }+ }+ );+ port.close();+ telemetry?.close();+ self.close();+}++self.onmessage = (event: MessageEvent<unknown>) => {+ if (+ typeof event.data === 'object' &&+ event.data !== null &&+ 'testKind' in event.data+ ) {+ const control = event.data as {+ testKind: string;+ ownerEpoch?: number;+ routeId?: number;+ };+ if (control.testKind === 'crash') {+ setTimeout(() => {+ throw new Error('harness-induced worker-only failure');+ });+ } else if (+ control.testKind === 'stale-response' &&+ control.ownerEpoch !== undefined &&+ control.routeId !== undefined+ ) {+ sendStaleResponse(control.ownerEpoch, control.routeId);+ } else if (control.testKind === 'hang-heartbeats') {+ ignoreHeartbeats = true;+ }+ return;+ }++ const parsed = validatePageToEngineEnvelope(event.data);+ const port = event.ports[0];+ if (!parsed.ok || !port || activationValue) {+ port?.close();+ return;+ }+ void activate(parsed.value, port);+};diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/fake-coordinator.shared-worker.ts b/apps/web/src/lib/graphql-cache/worker/browser-test/fake-coordinator.shared-worker.tsnew file mode 100644index 0000000000..1c54c1c56d--- /dev/null+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/fake-coordinator.shared-worker.ts@@ -0,0 +1,24 @@+/// <reference lib="webworker" />++import { CoordinatorRouter } from '../coordinator-router';++declare const self: SharedWorkerGlobalScope;++const router = new CoordinatorRouter();+let telemetry: BroadcastChannel | undefined;++self.onconnect = (event: MessageEvent) => {+ const port = event.ports[0];+ if (port) router.connect(port);+};++setInterval(() => {+ const snapshot = router.snapshot();+ if (!snapshot) return;+ telemetry ??= new BroadcastChannel(`graphql-cache-wp08:${snapshot.scope}`);+ telemetry.postMessage({+ kind: 'coordinator-snapshot',+ ownerEpoch: snapshot.ownerEpoch,+ snapshot,+ });+}, 100);diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/graphql-soup-rollout-harness.ts b/apps/web/src/lib/graphql-cache/worker/browser-test/graphql-soup-rollout-harness.tsnew file mode 100644index 0000000000..04f0dd74e6--- /dev/null+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/graphql-soup-rollout-harness.ts@@ -0,0 +1,191 @@+export {};++const result = document.querySelector<HTMLElement>('#result');+if (!result) throw new Error('missing Cache GraphQL Soup result node');++const NativeWorker = globalThis.Worker;+const NativeSharedWorker = globalThis.SharedWorker;+const workerUrls: string[] = [];+const sharedWorkerUrls: string[] = [];++globalThis.Worker = new Proxy(NativeWorker, {+ construct(target, args: ConstructorParameters<typeof Worker>) {+ workerUrls.push(String(args[0]));+ return Reflect.construct(target, args) as Worker;+ },+});+globalThis.SharedWorker = new Proxy(NativeSharedWorker, {+ construct(target, args: ConstructorParameters<typeof SharedWorker>) {+ sharedWorkerUrls.push(String(args[0]));+ return Reflect.construct(target, args) as SharedWorker;+ },+});++const resources = () => ({+ workerUrls: [...workerUrls],+ sharedWorkerUrls: [...sharedWorkerUrls],+});++const loadSoup = async () =>+ await import('../../../service-clients/service-storage/graphql-soup');++let posthogBeforeSendCalls = 0;++async function initializeLocalPosthog() {+ const { analytics } = await import('@app/lib/analytics');+ if (!analytics.posthog.config.token) {+ const disabledApiHost = `${location.origin}/__cache-rollout-posthog-disabled`;+ analytics.posthog.init('phc_cache_rollout_local_test', {+ api_host: disabledApiHost,+ flags_api_host: disabledApiHost,+ autocapture: false,+ rageclick: false,+ capture_pageview: false,+ capture_pageleave: false,+ capture_performance: false,+ capture_dead_clicks: false,+ capture_exceptions: false,+ capture_heatmaps: false,+ disable_session_recording: true,+ enable_recording_console_log: false,+ disable_persistence: true,+ persistence: 'memory',+ disable_external_dependency_loading: true,+ disable_surveys: true,+ disable_surveys_automatic_display: true,+ disable_product_tours: true,+ disable_conversations: true,+ disable_web_experiments: true,+ advanced_disable_flags: true,+ advanced_disable_feature_flags_on_first_load: true,+ advanced_disable_toolbar_metrics: true,+ request_batching: false,+ opt_out_capturing_by_default: true,+ opt_out_persistence_by_default: true,+ person_profiles: 'never',+ save_campaign_params: false,+ save_referrer: false,+ before_send: () => {+ posthogBeforeSendCalls += 1;+ return null;+ },+ loaded: (posthog) => posthog.opt_out_capturing(),+ });+ }+ return analytics;+}++function overrideRolloutFlags(+ analytics: Awaited<ReturnType<typeof initializeLocalPosthog>>,+ disabled: boolean+): void {+ analytics.posthog.featureFlags.overrideFeatureFlags({+ flags: {+ 'enable-graphql-soup': true,+ 'enable-browser-turso-cache': true,+ 'disable-browser-turso-cache': disabled,+ },+ suppressWarning: true,+ });+}++const api = {+ resources,+ async resolveDefaultOff(): Promise<{+ cacheEnabled: boolean;+ cacheHostPresent: boolean;+ resources: ReturnType<typeof resources>;+ }> {+ const soup = await loadSoup();+ soup.getGraphqlSoupClient();+ return {+ cacheEnabled: soup.graphqlCacheEnabled(),+ cacheHostPresent: soup.getGraphqlCacheHost() !== undefined,+ resources: resources(),+ };+ },+ async tryTreatment(): Promise<+ | {+ overrideApplied: false;+ blocker: 'posthog-override-unavailable';+ posthogBeforeSendCalls: number;+ resources: ReturnType<typeof resources>;+ }+ | {+ overrideApplied: true;+ lazyBeforeRead: boolean;+ readKind: string;+ samePageKillLatched: boolean;+ posthogBeforeSendCalls: number;+ resources: ReturnType<typeof resources>;+ }+ > {+ const analytics = await initializeLocalPosthog();+ overrideRolloutFlags(analytics, false);+ const overrideApplied =+ analytics.posthog.isFeatureEnabled('enable-graphql-soup') === true &&+ analytics.posthog.isFeatureEnabled('enable-browser-turso-cache') ===+ true &&+ analytics.posthog.isFeatureEnabled('disable-browser-turso-cache') ===+ false;+ if (!overrideApplied) {+ return {+ overrideApplied: false,+ blocker: 'posthog-override-unavailable',+ posthogBeforeSendCalls,+ resources: resources(),+ };+ }++ const soup = await loadSoup();+ const client = soup.getGraphqlSoupClient();+ const host = soup.getGraphqlCacheHost();+ if (!host) throw new Error('PostHog treatment did not create cache host');+ const lazyBeforeRead =+ workerUrls.length === 0 && sharedWorkerUrls.length === 0;+ const read = await host.readQuery({+ query: 'query CacheRolloutSelector { __typename }',+ operationName: 'CacheRolloutSelector',+ });++ overrideRolloutFlags(analytics, true);+ const samePageKillLatched =+ soup.getGraphqlSoupClient() === client &&+ soup.getGraphqlCacheHost() === host;+ return {+ overrideApplied: true,+ lazyBeforeRead,+ readKind: read.kind,+ samePageKillLatched,+ posthogBeforeSendCalls,+ resources: resources(),+ };+ },+ async resolveAfterNavigationKill(): Promise<{+ cacheEnabled: boolean;+ cacheHostPresent: boolean;+ posthogBeforeSendCalls: number;+ resources: ReturnType<typeof resources>;+ }> {+ const analytics = await initializeLocalPosthog();+ overrideRolloutFlags(analytics, true);+ const soup = await loadSoup();+ soup.getGraphqlSoupClient();+ return {+ cacheEnabled: soup.graphqlCacheEnabled(),+ cacheHostPresent: soup.getGraphqlCacheHost() !== undefined,+ posthogBeforeSendCalls,+ resources: resources(),+ };+ },+};++declare global {+ interface Window {+ graphqlSoupRolloutHarness: typeof api;+ }+}++window.graphqlSoupRolloutHarness = api;+result.dataset.status = 'ready';+result.textContent = JSON.stringify({ actualGraphqlSoupPath: true });diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/graphql-soup-rollout.html b/apps/web/src/lib/graphql-cache/worker/browser-test/graphql-soup-rollout.htmlnew file mode 100644index 0000000000..0ab5fb8e08--- /dev/null+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/graphql-soup-rollout.html@@ -0,0 +1,13 @@+<!doctype html>+<html lang="en">+ <head>+ <meta charset="UTF-8" />+ <meta name="viewport" content="width=device-width, initial-scale=1.0" />+ <link rel="icon" href="data:," />+ <title>Cache production GraphQL Soup selector harness</title>+ </head>+ <body>+ <main id="result" data-status="loading">loading</main>+ <script type="module" src="./graphql-soup-rollout-harness.ts"></script>+ </body>+</html>diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/harness.ts b/apps/web/src/lib/graphql-cache/worker/browser-test/harness.tsnew file mode 100644index 0000000000..691d1f4ed3--- /dev/null+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/harness.ts@@ -0,0 +1,408 @@+import { databaseOwnerLockName } from '../coordinator-protocol';+import type {+ BrowserHarnessCommand,+ BrowserHarnessEnvelope,+} from './browser-wire';++const resultElement = document.querySelector<HTMLElement>('#result');+if (!resultElement) throw new Error('missing result element');++type CommandWithoutId = BrowserHarnessCommand extends infer Command+ ? Command extends BrowserHarnessCommand+ ? Omit<Command, 'commandId'>+ : never+ : never;++type EngineTelemetry = {+ kind: string;+ tabId?: string;+ ownerEpoch: number;+ routeId?: number;+ requestKind?: string;+ requestId?: number;+ slow?: boolean;+ snapshot?: { staleMessageDrops?: number };+};++const waitUntil = async (+ description: string,+ predicate: () => boolean,+ timeoutMs = 20_000+): Promise<void> => {+ const started = performance.now();+ while (!predicate()) {+ if (performance.now() - started > timeoutMs) {+ throw new Error(`timed out waiting for ${description}`);+ }+ await new Promise<void>((resolve) => setTimeout(resolve, 20));+ }+};++const assert: (condition: unknown, message: string) => asserts condition = (+ condition,+ message+) => {+ if (!condition) throw new Error(message);+};++const run = async (): Promise<Record<string, unknown>> => {+ const scope = `wp08-${crypto.randomUUID()}`;+ const tabChannel = new BroadcastChannel(`graphql-cache-wp08-tabs:${scope}`);+ const telemetryChannel = new BroadcastChannel(`graphql-cache-wp08:${scope}`);+ const tabIds = ['tab-a', 'tab-b', 'tab-c'] as const;+ const popups = new Map<string, Window>();+ const registered = new Set<string>();+ const adapterCreated = new Set<string>();+ const eventOrder = new Map<string, string[]>();+ const workers: Array<{ tabId: string; ownerEpoch: number }> = [];+ const terminated: Array<{+ tabId: string;+ ownerEpoch: number;+ reason: string;+ }> = [];+ const replacements = new Set<number>();+ const pushes = new Map<string, number>();+ const telemetry: EngineTelemetry[] = [];+ const pendingCommands = new Map<+ string,+ {+ resolve: (value: unknown) => void;+ reject: (error: Error) => void;+ timer: ReturnType<typeof setTimeout>;+ }+ >();+ const protocolErrors: string[] = [];++ const remember = (tabId: string, kind: string): void => {+ const events = eventOrder.get(tabId) ?? [];+ events.push(kind);+ eventOrder.set(tabId, events);+ };++ tabChannel.onmessage = (event: MessageEvent<BrowserHarnessEnvelope>) => {+ const envelope = event.data;+ if (envelope.source !== 'tab') return;+ const tabEvent = envelope.event;+ remember(envelope.tabId, tabEvent.kind);+ switch (tabEvent.kind) {+ case 'adapter-created':+ adapterCreated.add(envelope.tabId);+ break;+ case 'registered':+ registered.add(envelope.tabId);+ break;+ case 'worker-created':+ workers.push({+ tabId: envelope.tabId,+ ownerEpoch: tabEvent.ownerEpoch,+ });+ break;+ case 'worker-terminated':+ terminated.push({+ tabId: envelope.tabId,+ ownerEpoch: tabEvent.ownerEpoch,+ reason: tabEvent.reason,+ });+ break;+ case 'engine-replaced':+ replacements.add(tabEvent.ownerEpoch);+ break;+ case 'cache-push':+ pushes.set(envelope.tabId, (pushes.get(envelope.tabId) ?? 0) + 1);+ break;+ case 'protocol-error':+ protocolErrors.push(tabEvent.error);+ break;+ case 'command-result': {+ const pending = pendingCommands.get(tabEvent.commandId);+ if (!pending) return;+ pendingCommands.delete(tabEvent.commandId);+ clearTimeout(pending.timer);+ if (tabEvent.ok) pending.resolve(tabEvent.result);+ else pending.reject(new Error(tabEvent.error));+ break;+ }+ }+ };+ telemetryChannel.onmessage = (event: MessageEvent<EngineTelemetry>) => {+ telemetry.push(event.data);+ };++ const command = async (+ targetTabId: string,+ value: CommandWithoutId+ ): Promise<unknown> => {+ const commandId = crypto.randomUUID();+ const result = new Promise<unknown>((resolve, reject) => {+ const timer = setTimeout(() => {+ pendingCommands.delete(commandId);+ reject(new Error(`command timed out: ${value.kind}`));+ }, 20_000);+ pendingCommands.set(commandId, { resolve, reject, timer });+ });+ tabChannel.postMessage({+ source: 'harness',+ targetTabId,+ command: { ...value, commandId } as BrowserHarnessCommand,+ } satisfies BrowserHarnessEnvelope);+ return await result;+ };++ const latestOwner = (minimumEpoch = 0) =>+ workers.toReversed().find((worker) => worker.ownerEpoch >= minimumEpoch);++ const ownerLockName = (): string | undefined => {+ if (!latestOwner()) return;+ return databaseOwnerLockName(scope);+ };++ const verifyOwnerLock = async (ownerEpoch: number): Promise<void> => {+ const lockName = ownerLockName();+ assert(lockName, 'missing owner lock name');+ const locks = await navigator.locks.query();+ const held = locks.held?.filter((lock) => lock.name === lockName) ?? [];+ assert(+ held.length === 1,+ `epoch ${ownerEpoch} did not hold one owner lock`+ );+ const unavailable = await navigator.locks.request(+ lockName,+ { mode: 'exclusive', ifAvailable: true },+ (lock) => lock === null+ );+ assert(unavailable, `epoch ${ownerEpoch} owner lock was not exclusive`);+ };++ for (const tabId of tabIds) {+ const url = new URL('./tab.html', location.href);+ url.searchParams.set('scope', scope);+ url.searchParams.set('tabId', tabId);+ const popup = window.open(url, `${scope}:${tabId}`);+ if (!popup) throw new Error(`popup blocked for ${tabId}`);+ popups.set(tabId, popup);+ }++ await waitUntil('three adapters', () => adapterCreated.size === 3);+ await waitUntil('three registrations', () => registered.size === 3);+ await waitUntil('epoch 1 ready', () =>+ telemetry.some((event) => event.kind === 'ready' && event.ownerEpoch === 1)+ );+ assert(workers.length === 1, 'standby page eagerly created a worker');+ for (const tabId of tabIds) {+ assert(+ eventOrder.get(tabId)?.[0] === 'adapter-created',+ `${tabId} created a worker before its lazy adapter`+ );+ }+ await waitUntil(+ 'three colliding init requests',+ () =>+ telemetry.filter(+ (event) =>+ event.kind === 'request-started' && event.requestKind === 'init'+ ).length >= 3+ );+ const routedInitIds = new Set(+ telemetry+ .filter(+ (event) =>+ event.kind === 'request-started' && event.requestKind === 'init'+ )+ .map((event) => event.requestId)+ );+ assert(+ routedInitIds.size === 3,+ 'colliding tab request ids were not rewritten'+ );+ await verifyOwnerLock(1);++ const first = latestOwner(1);+ assert(first, 'missing epoch 1 owner');+ const firstStandbys = tabIds.filter((tabId) => tabId !== first.tabId);+ await command(firstStandbys[0]!, { kind: 'write', value: 'preserved' });+ await waitUntil('cache push fanout', () =>+ tabIds.every((tabId) => (pushes.get(tabId) ?? 0) > 0)+ );+ expectHit(await command(firstStandbys[1]!, { kind: 'read' }), 'preserved');++ await command(first.tabId, { kind: 'graceful-close' });+ await waitUntil('epoch 2 ready', () =>+ telemetry.some((event) => event.kind === 'ready' && event.ownerEpoch === 2)+ );+ const second = latestOwner(2);+ assert(second, 'missing epoch 2 owner');+ assert(second.tabId !== first.tabId, 'graceful handoff reused retiring tab');+ await verifyOwnerLock(2);+ expectHit(await command(second.tabId, { kind: 'read' }), 'preserved');++ await command(second.tabId, { kind: 'write', value: 'must-wipe' });+ const requester = tabIds.find(+ (tabId) => tabId !== first.tabId && tabId !== second.tabId+ );+ assert(requester, 'missing abrupt-loss requester');+ const slow = command(requester, { kind: 'slow-read' }).then(+ () => '',+ (error: unknown) => (error instanceof Error ? error.message : String(error))+ );+ await waitUntil('slow route start', () =>+ telemetry.some(+ (event) =>+ event.kind === 'request-started' &&+ event.ownerEpoch === 2 &&+ event.slow === true+ )+ );+ const oldRoute = telemetry.find(+ (event) =>+ event.kind === 'request-started' &&+ event.ownerEpoch === 2 &&+ event.slow === true+ );+ assert(oldRoute?.routeId, 'missing old route id');+ const secondPage = popups.get(second.tabId);+ assert(secondPage && !secondPage.closed, 'abrupt owner page closed early');+ await command(second.tabId, { kind: 'crash-worker' });+ await waitUntil('epoch 2 worker termination', () =>+ terminated.some((event) => event.ownerEpoch === 2)+ );+ const abruptError = await slow;+ assert(+ abruptError.includes('owner epoch 2 was lost'),+ 'old route was not rejected'+ );+ assert(!secondPage.closed, 'worker-only failure closed its page');+ try {+ await waitUntil(+ 'epoch 3 wipe and ready',+ () =>+ telemetry.some(+ (event) => event.kind === 'wipe-completed' && event.ownerEpoch === 3+ ) &&+ telemetry.some(+ (event) => event.kind === 'ready' && event.ownerEpoch === 3+ )+ );+ } catch (error) {+ const locks = await navigator.locks.query();+ throw new Error(+ `${error instanceof Error ? error.message : String(error)}; workers=${JSON.stringify(workers)}; telemetry=${JSON.stringify(telemetry.slice(-20))}; events=${JSON.stringify(Object.fromEntries(eventOrder))}; locks=${JSON.stringify(locks)}; protocol=${JSON.stringify(protocolErrors)}`+ );+ }+ const third = latestOwner(3);+ assert(third, 'missing epoch 3 owner');+ await verifyOwnerLock(3);+ expectMiss(await command(third.tabId, { kind: 'read' }));++ await command(third.tabId, {+ kind: 'stale-response',+ ownerEpoch: 3,+ routeId: oldRoute.routeId,+ });+ await waitUntil('coordinator stale-message telemetry', () =>+ telemetry.some(+ (event) =>+ event.kind === 'coordinator-snapshot' &&+ (event.snapshot?.staleMessageDrops ?? 0) > 0+ )+ );+ expectMiss(await command(third.tabId, { kind: 'read' }));++ await command(third.tabId, { kind: 'write', value: 'liveness-wipe' });+ const thirdPage = popups.get(third.tabId);+ assert(thirdPage && !thirdPage.closed, 'liveness owner page closed early');+ await command(third.tabId, { kind: 'release-liveness-lock' });+ await waitUntil('epoch 3 liveness termination', () =>+ terminated.some(+ (event) =>+ event.ownerEpoch === 3 &&+ event.reason === 'tab liveness lock was released'+ )+ );+ assert(!thirdPage.closed, 'liveness lock release closed its page');+ await waitUntil(+ 'epoch 4 wipe and ready',+ () =>+ telemetry.some(+ (event) => event.kind === 'wipe-completed' && event.ownerEpoch === 4+ ) &&+ telemetry.some(+ (event) => event.kind === 'ready' && event.ownerEpoch === 4+ )+ );+ const fourth = latestOwner(4);+ assert(fourth, 'missing epoch 4 owner');+ await verifyOwnerLock(4);+ expectMiss(await command(fourth.tabId, { kind: 'read' }));++ const result = {+ passed: true,+ openedTabs: 3,+ ownerEpochs: workers.map((worker) => worker.ownerEpoch),+ ownerTabs: workers.map((worker) => worker.tabId),+ maxWorkersPerEpoch: Math.max(+ ...workers.map(+ ({ ownerEpoch }) =>+ workers.filter((worker) => worker.ownerEpoch === ownerEpoch).length+ )+ ),+ noEagerWorker: true,+ collidingRequestIdsRewritten: true,+ gracefulPreserved: true,+ abruptRejectedInflight: abruptError.includes('owner epoch 2 was lost'),+ abruptWiped: true,+ workerOnlyPageStayedAlive: !secondPage.closed,+ workerOnlyWiped: true,+ livenessPageStayedAlive: !thirdPage.closed,+ livenessTerminationReason: terminated.find(+ (event) => event.ownerEpoch === 3+ )?.reason,+ livenessWiped: true,+ staleMessageDrops: Math.max(+ 0,+ ...telemetry.map((event) => event.snapshot?.staleMessageDrops ?? 0)+ ),+ staleMessagePortResponseDropped: telemetry.some(+ (event) => (event.snapshot?.staleMessageDrops ?? 0) > 0+ ),+ pushReachedAllTabs: tabIds.every((tabId) => (pushes.get(tabId) ?? 0) > 0),+ ownerLockContentionEpochs: [1, 2, 3, 4],+ engineReplacedEpochs: [...replacements].toSorted(),+ protocolErrors,+ };++ for (const popup of popups.values()) popup.close();+ tabChannel.close();+ telemetryChannel.close();+ return result;+};++function expectHit(value: unknown, expected: string): void {+ assert(+ typeof value === 'object' &&+ value !== null &&+ (value as { kind?: unknown }).kind === 'hit' &&+ (value as { data?: { value?: unknown } }).data?.value === expected,+ `expected cache hit ${expected}`+ );+}++function expectMiss(value: unknown): void {+ assert(+ typeof value === 'object' &&+ value !== null &&+ (value as { kind?: unknown }).kind === 'miss',+ 'expected cache miss'+ );+}++void run().then(+ (result) => {+ resultElement.dataset.status = 'passed';+ resultElement.textContent = JSON.stringify(result, null, 2);+ },+ (error: unknown) => {+ resultElement.dataset.status = 'failed';+ resultElement.textContent =+ error instanceof Error ? (error.stack ?? error.message) : String(error);+ }+);diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/host-harness.ts b/apps/web/src/lib/graphql-cache/worker/browser-test/host-harness.tsnew file mode 100644index 0000000000..658e44597e--- /dev/null+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/host-harness.ts@@ -0,0 +1,223 @@+import { createWorkerCacheHost } from '../../host/worker-host';+import productionCacheWorkerUrl from './production-cache.engine-worker.ts?worker&url';++const resultNode = document.querySelector('#result');+if (!(resultNode instanceof HTMLElement))+ throw new Error('missing result node');++const scope = `wp09-host-${crypto.randomUUID()}`;+const telemetry = new BroadcastChannel(+ `graphql-cache-wp08-production:${scope}`+);+type TelemetryEvent = {+ kind: string;+ ownerEpoch: number;+ requestId?: number;+ requestKind?: string;+ slow?: boolean;+};+const telemetryEvents: TelemetryEvent[] = [];+telemetry.onmessage = (event: MessageEvent<TelemetryEvent>) => {+ telemetryEvents.push(event.data);+};++const waitUntil = async (+ label: string,+ predicate: () => boolean,+ timeoutMs = 20_000+): Promise<void> => {+ const deadline = performance.now() + timeoutMs;+ while (!predicate()) {+ if (performance.now() >= deadline) throw new Error(`${label} timed out`);+ await new Promise((resolve) => setTimeout(resolve, 10));+ }+};++const nativeWorker = globalThis.Worker;+const nativeSharedWorker = globalThis.SharedWorker;+const engineWorkers: Worker[] = [];+const terminatedEpochs: number[] = [];+let sharedWorkerConstructions = 0;+let sharedPortClosed = false;++const workerProxy = new Proxy(nativeWorker, {+ construct(_target, args: ConstructorParameters<typeof Worker>) {+ const [url, options] = args;+ const epoch = Number(options?.name?.split(':').at(-1));+ const worker = options?.name?.startsWith('graphql-cache-engine:')+ ? new nativeWorker(productionCacheWorkerUrl, options)+ : new nativeWorker(url, options);+ if (options?.name?.startsWith('graphql-cache-engine:')) {+ engineWorkers.push(worker);+ const terminate = worker.terminate.bind(worker);+ worker.terminate = () => {+ terminatedEpochs.push(epoch);+ terminate();+ };+ }+ return worker;+ },+});+globalThis.Worker = workerProxy;++const sharedWorkerProxy = new Proxy(nativeSharedWorker, {+ construct(_target, args: ConstructorParameters<typeof SharedWorker>) {+ sharedWorkerConstructions += 1;+ const worker = new nativeSharedWorker(...args);+ const close = worker.port.close.bind(worker.port);+ worker.port.close = () => {+ sharedPortClosed = true;+ close();+ };+ return worker;+ },+});+globalThis.SharedWorker = sharedWorkerProxy;++const QUERY = `query Soup($input: SoupInput!) {+ user {+ id+ soup(input: $input) {+ nextCursor+ items {+ __typename+ id+ }+ }+ }+}`;+const SLOW_QUERY = QUERY.replace('query Soup', 'query Slow');+const VARIABLES = { input: { limit: 1 } };++const report: Record<string, unknown> = {+ passed: false,+ noEagerConstructor: false,+ requestOrder: [],+ oldEpochRejectedBeforeReplacement: false,+ oldRequestReplayCount: 0,+ replacementActiveKeys: [],+ replacementReadCompleted: false,+ gracefulDrained: false,+ terminatedEpochs,+ sharedPortClosed: false,+ initializationErrors: [],+};++try {+ const initializationErrors: string[] = [];+ const host = createWorkerCacheHost({+ scope,+ requestTimeoutMs: 10_000,+ onInitializationError: (error) => initializationErrors.push(error.message),+ });+ report.noEagerConstructor =+ sharedWorkerConstructions === 0 && engineWorkers.length === 0;++ const order: string[] = [];+ const replacementActiveKeys: number[][] = [];+ let replacementRead: Promise<unknown> | undefined;+ host.onOpsAffected((keys) => {+ order.push('active-notified');+ replacementActiveKeys.push(keys);+ replacementRead ??= host.readQuery({+ opKey: keys[0],+ query: QUERY,+ operationName: 'Soup',+ variables: VARIABLES,+ });+ });++ await Promise.all([+ host.readQuery({+ opKey: 7,+ query: QUERY,+ operationName: 'Soup',+ variables: VARIABLES,+ }),+ host.readQuery({+ opKey: 9,+ query: QUERY,+ operationName: 'Soup',+ variables: VARIABLES,+ }),+ ]);+ const slowRead = host.readQuery({+ opKey: 7,+ query: SLOW_QUERY,+ operationName: 'Slow',+ variables: VARIABLES,+ });+ const slowOutcome = slowRead.then(+ () => undefined,+ (error: unknown) => {+ order.push('old-request-rejected');+ return error;+ }+ );+ await waitUntil('slow request admission', () =>+ telemetryEvents.some((event) => event.slow === true)+ );++ engineWorkers[0]?.postMessage({ testKind: 'crash' });+ const oldError = (await slowOutcome) as+ | (Error & { errorCode?: string })+ | undefined;+ await waitUntil('replacement active notification', () =>+ order.includes('active-notified')+ );+ await waitUntil('replacement read creation', () => replacementRead != null);+ await replacementRead;++ const routedRequests = telemetryEvents.filter(+ (event) => event.kind === 'request-admitted'+ );+ report.requestOrder = routedRequests.map((event) => [+ event.ownerEpoch,+ event.requestId,+ event.requestKind,+ ]);+ report.oldEpochRejectedBeforeReplacement =+ oldError?.errorCode === 'owner-epoch-lost' &&+ order.join(',') === 'old-request-rejected,active-notified';+ report.oldRequestReplayCount = routedRequests.filter(+ (event) => event.slow === true+ ).length;+ report.replacementActiveKeys = replacementActiveKeys;+ report.replacementReadCompleted = routedRequests.some(+ (event) =>+ event.ownerEpoch === 2 &&+ event.requestKind === 'read' &&+ event.slow === false+ );++ host.dispose();+ await waitUntil('graceful engine drain', () =>+ telemetryEvents.some(+ (event) => event.kind === 'drained' && event.ownerEpoch === 2+ )+ );+ await waitUntil('graceful worker termination', () =>+ terminatedEpochs.includes(2)+ );+ await waitUntil('coordinator port close', () => sharedPortClosed);++ report.gracefulDrained = true;+ report.sharedPortClosed = sharedPortClosed;+ report.initializationErrors = initializationErrors;+ report.passed =+ report.noEagerConstructor === true &&+ report.oldEpochRejectedBeforeReplacement === true &&+ report.oldRequestReplayCount === 1 &&+ JSON.stringify(replacementActiveKeys) === JSON.stringify([[7, 9]]) &&+ report.replacementReadCompleted === true &&+ report.gracefulDrained === true &&+ sharedPortClosed &&+ JSON.stringify(terminatedEpochs) === JSON.stringify([1, 2]) &&+ initializationErrors.length === 0;+} catch (error) {+ report.error = error instanceof Error ? error.message : String(error);+}++resultNode.dataset.status = report.passed ? 'passed' : 'failed';+resultNode.textContent = JSON.stringify(report);+telemetry.close();diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/host.html b/apps/web/src/lib/graphql-cache/worker/browser-test/host.htmlnew file mode 100644index 0000000000..9814da04d4--- /dev/null+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/host.html@@ -0,0 +1,13 @@+<!doctype html>+<html lang="en">+ <head>+ <meta charset="UTF-8" />+ <meta name="viewport" content="width=device-width, initial-scale=1.0" />+ <link rel="icon" href="data:," />+ <title>WP-09 CacheHost coordinator browser test</title>+ </head>+ <body>+ <pre id="result" data-status="running"></pre>+ <script type="module" src="./host-harness.ts"></script>+ </body>+</html>diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/index.html b/apps/web/src/lib/graphql-cache/worker/browser-test/index.htmlnew file mode 100644index 0000000000..e9a7f7cd1a--- /dev/null+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/index.html@@ -0,0 +1,12 @@+<!doctype html>+<html lang="en">+ <head>+ <meta charset="UTF-8" />+ <link rel="icon" href="data:," />+ <title>WP-08 production coordinator browser harness</title>+ </head>+ <body>+ <pre id="result" data-status="running">running</pre>+ <script type="module" src="./harness.ts"></script>+ </body>+</html>diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/instrumented-cache.engine-worker.ts b/apps/web/src/lib/graphql-cache/worker/browser-test/instrumented-cache.engine-worker.tsnew file mode 100644index 0000000000..7d3de96f36--- /dev/null+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/instrumented-cache.engine-worker.ts@@ -0,0 +1,95 @@+/// <reference lib="webworker" />++import type { CacheEngineRuntimeEvent } from '../cache-engine-runtime';++let channel: BroadcastChannel | undefined;+let activationStartedAt = 0;+let nestedWorkerConstructions = 0;+let wasmFetchCount = 0;+let wasmSha256: Promise<string> | undefined;+const nativeFetch: typeof fetch = globalThis.fetch.bind(globalThis);+globalThis.fetch = async (...argumentsList: Parameters<typeof fetch>) => {+ const response = await nativeFetch(...argumentsList);+ const input = argumentsList[0];+ const requestUrl =+ typeof input === 'string'+ ? input+ : input instanceof URL+ ? input.href+ : input.url;+ if (/\/cache_wasm_bg(?:-[\w-]+)?\.wasm(?:[?#]|$)/.test(requestUrl)) {+ wasmFetchCount++;+ wasmSha256 = response+ .clone()+ .arrayBuffer()+ .then(async (bytes) => {+ const digest = await crypto.subtle.digest('SHA-256', bytes);+ return [...new Uint8Array(digest)]+ .map((byte) => byte.toString(16).padStart(2, '0'))+ .join('');+ });+ }+ return response;+};++const WorkerConstructor = globalThis.Worker;+if (typeof WorkerConstructor === 'function') {+ globalThis.Worker = new Proxy(WorkerConstructor, {+ construct() {+ nestedWorkerConstructions++;+ throw new Error('nested cache worker construction is forbidden');+ },+ });+}++const report = async (event: CacheEngineRuntimeEvent): Promise<void> => {+ channel ??= new BroadcastChannel(+ `graphql-cache-performance:${event.activation.scope}`+ );+ if (event.kind === 'activation-started') {+ activationStartedAt = performance.now();+ channel.postMessage({+ kind: 'activation-started',+ ownerEpoch: event.activation.ownerEpoch,+ });+ }+ if (event.kind === 'ready') {+ const { cacheWasmLinearMemoryBytes } = await import('../wasm-module');+ if (!wasmSha256) {+ throw new Error('cache WASM fetch was not observed before DB readiness');+ }+ channel.postMessage({+ kind: 'database-ready',+ ownerEpoch: event.activation.ownerEpoch,+ workerActivationMs: performance.now() - activationStartedAt,+ linearMemoryBytes: cacheWasmLinearMemoryBytes(),+ wasmFetchCount,+ wasmSha256: await wasmSha256,+ nestedWorkerConstructions,+ crossOriginIsolated: globalThis.crossOriginIsolated,+ sharedArrayBufferAvailable:+ typeof globalThis.SharedArrayBuffer === 'function',+ });+ }+};++// Install interception before evaluating any production runtime module so a+// future static-import constructor cannot run outside this measurement guard.+// Top-level-await permits activation delivery during the dynamic import, so+// buffer those envelopes until the production runtime owns `onmessage`.+const bufferedActivationEvents: MessageEvent<unknown>[] = [];+globalThis.onmessage = (event: MessageEvent<unknown>) => {+ bufferedActivationEvents.push(event);+};+const { installCacheEngineWorker } = await import('../cache-engine-runtime');+installCacheEngineWorker({+ hooks: {+ onEvent: (event) => {+ void report(event);+ },+ },+});+const runtimeOnMessage = globalThis.onmessage;+for (const event of bufferedActivationEvents) {+ runtimeOnMessage?.call(globalThis, event);+}diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/performance-harness.ts b/apps/web/src/lib/graphql-cache/worker/browser-test/performance-harness.tsnew file mode 100644index 0000000000..f2219b0176--- /dev/null+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/performance-harness.ts@@ -0,0 +1,209 @@+import { createWorkerCacheHost } from '../../host/worker-host';+import instrumentedEngineWorkerUrl from './instrumented-cache.engine-worker.ts?worker&url';++const resultElement = document.querySelector<HTMLElement>('#result');+if (!resultElement) throw new Error('missing result element');++declare const __CACHE_WASM_BUILD_MODE__: 'development' | 'production';++type WorkerObservation = {+ kind: 'shared' | 'dedicated';+ requestedUrl: string;+ actualUrl: string;+};+let workerObserver: ((observation: WorkerObservation) => void) | undefined;+let workerErrorObserver: ((error: Error) => void) | undefined;+const NativeWorker = globalThis.Worker;+const NativeSharedWorker = globalThis.SharedWorker;+globalThis.Worker = new Proxy(NativeWorker, {+ construct(target, argumentsList) {+ const [requestedUrl, options] = argumentsList as ConstructorParameters<+ typeof Worker+ >;+ const isCacheEngine = options?.name?.startsWith('graphql-cache-engine:');+ const actualUrl = isCacheEngine+ ? instrumentedEngineWorkerUrl+ : requestedUrl;+ workerObserver?.({+ kind: 'dedicated',+ requestedUrl: String(requestedUrl),+ actualUrl: new URL(String(actualUrl), location.href).href,+ });+ const worker = Reflect.construct(target, [actualUrl, options]);+ worker.addEventListener('error', (event: ErrorEvent) => {+ workerErrorObserver?.(+ new Error(event.message || 'instrumented engine worker failed')+ );+ });+ worker.addEventListener('messageerror', () => {+ workerErrorObserver?.(+ new Error('instrumented engine worker emitted messageerror')+ );+ });+ return worker;+ },+});+globalThis.SharedWorker = new Proxy(NativeSharedWorker, {+ construct(target, argumentsList) {+ workerObserver?.({+ kind: 'shared',+ requestedUrl: String(argumentsList[0]),+ actualUrl: String(argumentsList[0]),+ });+ return Reflect.construct(target, argumentsList);+ },+});++type WorkerTelemetry =+ | { kind: 'activation-started'; ownerEpoch: number }+ | {+ kind: 'database-ready';+ ownerEpoch: number;+ workerActivationMs: number;+ linearMemoryBytes: number;+ wasmFetchCount: number;+ wasmSha256: string;+ nestedWorkerConstructions: number;+ crossOriginIsolated: boolean;+ sharedArrayBufferAvailable: boolean;+ };++export interface CacheWasmPerformanceSample {+ mode: 'development' | 'production';+ activationMs: number;+ browserReadyMs: number;+ hostFirstReadyMs: number;+ workerActivationMs: number;+ linearMemoryBytes: number;+ sharedWorkerConstructions: number;+ dedicatedWorkerConstructions: number;+ nestedWorkerConstructions: number;+ wasmFetchCount: number;+ wasmSha256: string;+ ownerEpochs: number[];+ crossOriginIsolated: boolean;+ sharedArrayBufferAvailable: boolean;+ sharedWorkerUrl: string;+ productionEngineUrl: string;+ instrumentedEngineUrl: string;+}++const waitFor = <T>(+ description: string,+ install: (resolve: (value: T) => void, reject: (error: Error) => void) => void+): Promise<T> =>+ new Promise<T>((resolve, reject) => {+ const timer = setTimeout(+ () => reject(new Error(`${description} timed out`)),+ 15_000+ );+ install(+ (value) => {+ clearTimeout(timer);+ resolve(value);+ },+ (error) => {+ clearTimeout(timer);+ reject(error);+ }+ );+ });++const QUERY = `query CachePerformance($input: SoupInput!) {+ user {+ id+ soup(input: $input) {+ nextCursor+ items {+ __typename+ id+ }+ }+ }+}`;++async function runMeasurement(): Promise<CacheWasmPerformanceSample> {+ const scope = `cache-performance-${crypto.randomUUID()}`;+ const started = performance.now();+ let activationMs = 0;+ let sharedWorkerConstructions = 0;+ let dedicatedWorkerConstructions = 0;+ let sharedWorkerUrl = '';+ let productionEngineUrl = '';+ let actualInstrumentedEngineUrl = '';+ const ownerEpochs = new Set<number>();+ workerObserver = ({ kind, requestedUrl, actualUrl }) => {+ if (kind === 'shared') {+ sharedWorkerConstructions++;+ sharedWorkerUrl = requestedUrl;+ } else {+ dedicatedWorkerConstructions++;+ productionEngineUrl = requestedUrl;+ actualInstrumentedEngineUrl = actualUrl;+ }+ };+ const telemetryChannel = new BroadcastChannel(+ `graphql-cache-performance:${scope}`+ );+ let rejectDatabaseReady: ((error: Error) => void) | undefined;+ const databaseReady = waitFor<+ Extract<WorkerTelemetry, { kind: 'database-ready' }> & {+ browserReadyMs: number;+ }+ >('cache database ready', (resolve, reject) => {+ rejectDatabaseReady = reject;+ telemetryChannel.onmessage = (event: MessageEvent<WorkerTelemetry>) => {+ ownerEpochs.add(event.data.ownerEpoch);+ if (event.data.kind === 'activation-started') {+ activationMs = performance.now() - started;+ return;+ }+ resolve({+ ...event.data,+ browserReadyMs: performance.now() - started,+ });+ };+ });+ workerErrorObserver = (error) => rejectDatabaseReady?.(error);+ const host = createWorkerCacheHost({+ scope,+ requestTimeoutMs: 15_000,+ initializationTimeoutMs: 15_000,+ onInitializationError: (error) => rejectDatabaseReady?.(error),+ });+ const firstReady = host.readQuery({+ opKey: 1,+ query: QUERY,+ operationName: 'CachePerformance',+ variables: { input: { limit: 1 } },+ });+ const [ready] = await Promise.all([databaseReady, firstReady]);+ const hostFirstReadyMs = performance.now() - started;+ host.dispose();+ telemetryChannel.close();+ workerObserver = undefined;+ workerErrorObserver = undefined;+ return {+ mode: __CACHE_WASM_BUILD_MODE__,+ activationMs,+ browserReadyMs: ready.browserReadyMs,+ hostFirstReadyMs,+ workerActivationMs: ready.workerActivationMs,+ linearMemoryBytes: ready.linearMemoryBytes,+ sharedWorkerConstructions,+ dedicatedWorkerConstructions,+ nestedWorkerConstructions: ready.nestedWorkerConstructions,+ wasmFetchCount: ready.wasmFetchCount,+ wasmSha256: ready.wasmSha256,+ ownerEpochs: [...ownerEpochs].sort((left, right) => left - right),+ crossOriginIsolated: ready.crossOriginIsolated,+ sharedArrayBufferAvailable: ready.sharedArrayBufferAvailable,+ sharedWorkerUrl,+ productionEngineUrl,+ instrumentedEngineUrl: actualInstrumentedEngineUrl,+ };+}++Object.assign(window, { runCacheWasmPerformanceSample: runMeasurement });+resultElement.dataset.status = 'idle';+resultElement.textContent = JSON.stringify({ mode: __CACHE_WASM_BUILD_MODE__ });diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/performance.html b/apps/web/src/lib/graphql-cache/worker/browser-test/performance.htmlnew file mode 100644index 0000000000..04f05d4995--- /dev/null+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/performance.html@@ -0,0 +1,12 @@+<!doctype html>+<html lang="en">+ <head>+ <meta charset="UTF-8" />+ <link rel="icon" href="data:," />+ <title>Cache performance cache WASM packaging measurement</title>+ </head>+ <body>+ <pre id="result" data-status="loading">loading</pre>+ <script type="module" src="./performance-harness.ts"></script>+ </body>+</html>diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/playwright.config.ts b/apps/web/src/lib/graphql-cache/worker/browser-test/playwright.config.tsnew file mode 100644index 0000000000..9b4051eaaa--- /dev/null+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/playwright.config.ts@@ -0,0 +1,48 @@+import { fileURLToPath } from 'node:url';+import { defineConfig, devices } from '@playwright/test';++const directory = fileURLToPath(new URL('.', import.meta.url));+const webDirectory = fileURLToPath(new URL('../../../../../', import.meta.url));++export default defineConfig({+ testDir: directory,+ testMatch: [+ 'coordinator.browser.e2e.ts',+ 'cache-wasm-packaging.browser.e2e.ts',+ ],+ timeout: 90_000,+ fullyParallel: false,+ workers: 1,+ reporter: 'line',+ use: {+ baseURL: 'http://127.0.0.1:4188',+ headless: true,+ },+ webServer: {+ command: `just build-cache-wasm && bunx --bun vite --config ${JSON.stringify(`${directory}/vite.config.ts`)}`,+ cwd: webDirectory,+ url: 'http://127.0.0.1:4188',+ reuseExistingServer: false,+ timeout: 180_000,+ },+ projects: [+ {+ name: 'chromium',+ use: {+ ...devices['Desktop Chrome'],+ launchOptions: {+ executablePath: process.env.PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH,+ },+ },+ },+ {+ name: 'firefox',+ use: {+ ...devices['Desktop Firefox'],+ launchOptions: {+ executablePath: process.env.PLAYWRIGHT_FIREFOX_EXECUTABLE_PATH,+ },+ },+ },+ ],+});diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/playwright.production.config.ts b/apps/web/src/lib/graphql-cache/worker/browser-test/playwright.production.config.tsnew file mode 100644index 0000000000..d072dc6beb--- /dev/null+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/playwright.production.config.ts@@ -0,0 +1,50 @@+import { fileURLToPath } from 'node:url';+import { defineConfig } from '@playwright/test';++const directory = fileURLToPath(new URL('.', import.meta.url));+const webDirectory = fileURLToPath(new URL('../../../../../', import.meta.url));++export default defineConfig({+ testDir: directory,+ testMatch: [+ 'coordinator.browser.e2e.ts',+ 'cache-wasm-packaging.browser.e2e.ts',+ 'cache-lifecycle.browser.e2e.ts',+ ],+ timeout: 90_000,+ fullyParallel: false,+ workers: 1,+ reporter: 'line',+ use: {+ baseURL: 'http://127.0.0.1:4189/app/',+ headless: true,+ },+ webServer: {+ command:+ 'just build-cache-wasm-browser-production && node scripts/cache-wasm/precompressed-preview-server.mjs src/lib/graphql-cache/worker/browser-test/.dist-production',+ cwd: webDirectory,+ url: 'http://127.0.0.1:4189/app/',+ reuseExistingServer: false,+ timeout: 180_000,+ },+ projects: [+ {+ name: 'chromium-production',+ use: {+ browserName: 'chromium',+ launchOptions: {+ executablePath: process.env.PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH,+ },+ },+ },+ {+ name: 'firefox-production',+ use: {+ browserName: 'firefox',+ launchOptions: {+ executablePath: process.env.PLAYWRIGHT_FIREFOX_EXECUTABLE_PATH,+ },+ },+ },+ ],+});diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/production-browser-wire.ts b/apps/web/src/lib/graphql-cache/worker/browser-test/production-browser-wire.tsnew file mode 100644index 0000000000..bce3d68b6a--- /dev/null+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/production-browser-wire.ts@@ -0,0 +1,53 @@+import type { CacheRequest } from '../../protocol';++export type ProductionCacheRequestWithoutId = CacheRequest extends infer Request+ ? Request extends CacheRequest+ ? Omit<Request, 'id'>+ : never+ : never;++export type ProductionHarnessCommand =+ | { kind: 'write'; commandId: string; value: string }+ | { kind: 'read'; commandId: string }+ | { kind: 'slow-read'; commandId: string }+ | { kind: 'graceful-close'; commandId: string }+ | { kind: 'crash-worker'; commandId: string }+ | {+ kind: 'arm-mutation-block';+ commandId: string;+ requestKind: CacheRequest['kind'];+ }+ | {+ kind: 'request';+ commandId: string;+ request: ProductionCacheRequestWithoutId;+ }+ | { kind: 'terminate-worker'; commandId: string };++export type ProductionHarnessEnvelope =+ | {+ source: 'harness';+ targetTabId: string;+ command: ProductionHarnessCommand;+ }+ | {+ source: 'tab';+ tabId: string;+ event:+ | { kind: 'registered' }+ | { kind: 'worker-created'; ownerEpoch: number }+ | { kind: 'worker-terminated'; ownerEpoch: number; reason: string }+ | {+ kind: 'command-result';+ commandId: string;+ ok: true;+ result?: unknown;+ }+ | {+ kind: 'command-result';+ commandId: string;+ ok: false;+ error: string;+ }+ | { kind: 'protocol-error'; error: string };+ };diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/production-cache.engine-worker.ts b/apps/web/src/lib/graphql-cache/worker/browser-test/production-cache.engine-worker.tsnew file mode 100644index 0000000000..65298ffbf3--- /dev/null+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/production-cache.engine-worker.ts@@ -0,0 +1,119 @@+/// <reference lib="webworker" />++import type { CacheRequest } from '../../protocol';+import {+ type CacheEngineRuntimeEvent,+ installCacheEngineWorker,+} from '../cache-engine-runtime';++const BLOCKABLE_MUTATION_KINDS = [+ 'write',+ 'enqueue-optimistic-mutation',+ 'claim-next-mutation',+ 'defer-optimistic-write',+ 'commit-optimistic-write',+ 'rollback-optimistic-write',+ 'invalidate',+ 'delete-records',+ 'clear',+] as const satisfies readonly CacheRequest['kind'][];++type BlockableMutationKind = (typeof BLOCKABLE_MUTATION_KINDS)[number];++let telemetry: BroadcastChannel | undefined;+let activeScope: string | undefined;+let armedMutationKind: BlockableMutationKind | undefined;+const testChannel = (scope: string): BroadcastChannel => {+ telemetry ??= new BroadcastChannel(`graphql-cache-wp08-production:${scope}`);+ return telemetry;+};+const report = (event: CacheEngineRuntimeEvent): void => {+ activeScope = event.activation.scope;+ const workerPerformance = globalThis.performance as Performance & {+ memory?: unknown;+ measureUserAgentSpecificMemory?: unknown;+ };+ testChannel(event.activation.scope).postMessage({+ kind: event.kind,+ tabId: event.activation.tabId,+ ownerEpoch: event.activation.ownerEpoch,+ databaseAction: event.activation.databaseAction,+ requestId: event.kind === 'request-admitted' ? event.request.id : undefined,+ requestKind:+ event.kind === 'request-admitted' ? event.request.kind : undefined,+ slow:+ event.kind === 'request-admitted' &&+ event.request.kind === 'read' &&+ event.request.query.includes('Slow'),+ admissionBarrier:+ event.kind === 'request-admitted' &&+ event.request.kind === 'read' &&+ event.request.query.includes('CacheAdmissionBarrier'),+ reason: event.kind === 'fatal' ? event.reason : undefined,+ fatalCode: event.kind === 'fatal' ? event.fatalCode : undefined,+ performanceMemoryAvailable:+ event.kind === 'ready' && workerPerformance.memory !== undefined,+ userAgentSpecificMemoryAvailable:+ event.kind === 'ready' &&+ typeof workerPerformance.measureUserAgentSpecificMemory === 'function',+ });+};++const blockInjectedRequest = async (request: CacheRequest): Promise<void> => {+ if (request.kind === 'read' && request.query.includes('Slow')) {+ await new Promise<void>(() => {});+ }+ if (request.kind === armedMutationKind) {+ armedMutationKind = undefined;+ if (!activeScope) throw new Error('test hook has no active scope');+ testChannel(activeScope).postMessage({+ kind: 'request-blocked-before-core',+ requestId: request.id,+ requestKind: request.kind,+ });+ await new Promise<void>(() => {});+ }+};++installCacheEngineWorker({+ hooks: {+ beforeRequest: blockInjectedRequest,+ onEvent: report,+ },+});++const runtimeOnMessage = self.onmessage;+self.onmessage = (event: MessageEvent<unknown>) => {+ if (+ typeof event.data === 'object' &&+ event.data !== null &&+ 'testKind' in event.data &&+ event.data.testKind === 'crash'+ ) {+ setTimeout(() => {+ throw new Error('production harness induced worker crash');+ });+ return;+ }+ if (+ typeof event.data === 'object' &&+ event.data !== null &&+ 'testKind' in event.data &&+ event.data.testKind === 'arm-mutation-block' &&+ 'requestKind' in event.data &&+ typeof event.data.requestKind === 'string' &&+ (BLOCKABLE_MUTATION_KINDS as readonly string[]).includes(+ event.data.requestKind+ )+ ) {+ armedMutationKind = event.data.requestKind as BlockableMutationKind;+ if (activeScope) {+ testChannel(activeScope).postMessage({+ kind: 'mutation-block-armed',+ requestKind: armedMutationKind,+ });+ }+ return;+ }+ runtimeOnMessage?.call(self, event);+};diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/production-cache.storage-control-worker.ts b/apps/web/src/lib/graphql-cache/worker/browser-test/production-cache.storage-control-worker.tsnew file mode 100644index 0000000000..dd6fb414a1--- /dev/null+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/production-cache.storage-control-worker.ts@@ -0,0 +1,42 @@+/// <reference lib="webworker" />++import { match } from 'ts-pattern';+import { loadBrowserTestCacheWasm } from './browser-test-wasm-module';++type StorageControlRequest = {+ id: number;+ scope: string;+ kind: 'incompatible-namespace' | 'corrupt-queue-payload';+};++type StorageControlResponse =+ | { id: number; ok: true; wasmUrl: string }+ | { id: number; ok: false; error: string };++const worker = self as unknown as DedicatedWorkerGlobalScope;++worker.onmessage = (event: MessageEvent<StorageControlRequest>) => {+ const request = event.data;+ void (async () => {+ const { module, wasmUrl } = await loadBrowserTestCacheWasm();+ await match(request)+ .with({ kind: 'incompatible-namespace' }, ({ scope }) =>+ module.browserTestMakeNamespaceIncompatible(scope)+ )+ .with({ kind: 'corrupt-queue-payload' }, ({ scope }) =>+ module.browserTestCorruptQueuePayload(scope)+ )+ .exhaustive();+ worker.postMessage({+ id: request.id,+ ok: true,+ wasmUrl,+ } satisfies StorageControlResponse);+ })().catch((error: unknown) => {+ worker.postMessage({+ id: request.id,+ ok: false,+ error: error instanceof Error ? error.message : String(error),+ } satisfies StorageControlResponse);+ });+};diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/production-harness.ts b/apps/web/src/lib/graphql-cache/worker/browser-test/production-harness.tsnew file mode 100644index 0000000000..bd9af4ece7--- /dev/null+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/production-harness.ts@@ -0,0 +1,374 @@+import { databaseOwnerLockName } from '../coordinator-protocol';+import type {+ ProductionHarnessCommand,+ ProductionHarnessEnvelope,+} from './production-browser-wire';++const resultElement = document.querySelector<HTMLElement>('#result');+if (!resultElement) throw new Error('missing result element');++type CommandWithoutId = ProductionHarnessCommand extends infer Command+ ? Command extends ProductionHarnessCommand+ ? Omit<Command, 'commandId'>+ : never+ : never;++type RuntimeTelemetry = {+ kind: string;+ tabId: string;+ ownerEpoch: number;+ databaseAction: 'open-existing' | 'wipe-before-open';+ requestId?: number;+ requestKind?: string;+ slow?: boolean;+ reason?: string;+};++const assert: (condition: unknown, message: string) => asserts condition = (+ condition,+ message+) => {+ if (!condition) throw new Error(message);+};++const waitUntil = async (+ description: string,+ predicate: () => boolean | Promise<boolean>,+ timeoutMs = 30_000+): Promise<void> => {+ const started = performance.now();+ while (!(await predicate())) {+ if (performance.now() - started > timeoutMs) {+ throw new Error(`timed out waiting for ${description}`);+ }+ await new Promise<void>((resolve) => setTimeout(resolve, 20));+ }+};++const run = async (): Promise<Record<string, unknown>> => {+ const scope = `wp08-production-${crypto.randomUUID()}`;+ const tabIds = ['production-a', 'production-b', 'production-c'] as const;+ const tabChannel = new BroadcastChannel(+ `graphql-cache-wp08-production-tabs:${scope}`+ );+ const telemetryChannel = new BroadcastChannel(+ `graphql-cache-wp08-production:${scope}`+ );+ const popups = new Map<string, Window>();+ const registered = new Set<string>();+ const workers: Array<{ tabId: string; ownerEpoch: number }> = [];+ const terminated: Array<{+ tabId: string;+ ownerEpoch: number;+ reason: string;+ }> = [];+ const telemetry: RuntimeTelemetry[] = [];+ const protocolErrors: string[] = [];+ const pendingCommands = new Map<+ string,+ {+ resolve: (value: unknown) => void;+ reject: (error: Error) => void;+ timer: ReturnType<typeof setTimeout>;+ }+ >();++ tabChannel.onmessage = (event: MessageEvent<ProductionHarnessEnvelope>) => {+ const message = event.data;+ if (message.source !== 'tab') return;+ switch (message.event.kind) {+ case 'registered':+ registered.add(message.tabId);+ break;+ case 'worker-created':+ workers.push({+ tabId: message.tabId,+ ownerEpoch: message.event.ownerEpoch,+ });+ break;+ case 'worker-terminated':+ terminated.push({+ tabId: message.tabId,+ ownerEpoch: message.event.ownerEpoch,+ reason: message.event.reason,+ });+ break;+ case 'protocol-error':+ protocolErrors.push(message.event.error);+ break;+ case 'command-result': {+ const pending = pendingCommands.get(message.event.commandId);+ if (!pending) return;+ pendingCommands.delete(message.event.commandId);+ clearTimeout(pending.timer);+ if (message.event.ok) pending.resolve(message.event.result);+ else pending.reject(new Error(message.event.error));+ break;+ }+ }+ };+ telemetryChannel.onmessage = (event: MessageEvent<RuntimeTelemetry>) => {+ telemetry.push(event.data);+ };++ const command = async (+ targetTabId: string,+ value: CommandWithoutId+ ): Promise<unknown> => {+ const commandId = crypto.randomUUID();+ const result = new Promise<unknown>((resolve, reject) => {+ const timer = setTimeout(() => {+ pendingCommands.delete(commandId);+ reject(new Error(`production command timed out: ${value.kind}`));+ }, 30_000);+ pendingCommands.set(commandId, { resolve, reject, timer });+ });+ tabChannel.postMessage({+ source: 'harness',+ targetTabId,+ command: { ...value, commandId } as ProductionHarnessCommand,+ } satisfies ProductionHarnessEnvelope);+ return await result;+ };++ const latestOwner = (minimumEpoch = 0) =>+ workers.toReversed().find((worker) => worker.ownerEpoch >= minimumEpoch);++ const ownerLockName = databaseOwnerLockName(scope);+ const queueOwnerLockContender = () => {+ let release!: () => void;+ let markAcquired!: () => void;+ const acquired = new Promise<void>((resolve) => {+ markAcquired = resolve;+ });+ const heldUntilReleased = new Promise<void>((resolve) => {+ release = resolve;+ });+ const completed = navigator.locks.request(+ ownerLockName,+ { mode: 'exclusive' },+ async (lock) => {+ assert(lock, 'production lock contender did not acquire the lock');+ markAcquired();+ await heldUntilReleased;+ }+ );+ return { acquired, release, completed };+ };+ const waitForPendingReplacementLock = async (+ description: string+ ): Promise<{ held: number; pending: number }> => {+ let evidence = { held: 0, pending: 0 };+ await waitUntil(description, async () => {+ const snapshot = await navigator.locks.query();+ evidence = {+ held:+ snapshot.held?.filter((lock) => lock.name === ownerLockName).length ??+ 0,+ pending:+ snapshot.pending?.filter((lock) => lock.name === ownerLockName)+ .length ?? 0,+ };+ return evidence.held === 1 && evidence.pending === 1;+ });+ return evidence;+ };++ for (const tabId of tabIds) {+ const url = new URL('./production-tab.html', location.href);+ url.searchParams.set('scope', scope);+ url.searchParams.set('tabId', tabId);+ const popup = window.open(url, `${scope}:${tabId}`);+ if (!popup) throw new Error(`popup blocked for ${tabId}`);+ popups.set(tabId, popup);+ }++ await waitUntil(+ 'three production registrations',+ () => registered.size === 3+ );+ await waitUntil('production epoch 1 ready', () =>+ telemetry.some((event) => event.kind === 'ready' && event.ownerEpoch === 1)+ );+ const first = latestOwner(1);+ assert(first, 'missing production epoch 1 owner');+ const firstStandby = tabIds.find((tabId) => tabId !== first.tabId);+ assert(firstStandby, 'missing production standby');++ await command(firstStandby, { kind: 'write', value: 'real-preserved' });+ expectProductionHit(+ await command(firstStandby, { kind: 'read' }),+ 'real-preserved'+ );++ const gracefulLock = queueOwnerLockContender();+ const graceful = command(first.tabId, { kind: 'graceful-close' });+ await gracefulLock.acquired;+ await graceful;+ await waitUntil('production epoch 1 drained', () =>+ telemetry.some(+ (event) => event.kind === 'drained' && event.ownerEpoch === 1+ )+ );+ await waitUntil('production epoch 2 activation', () =>+ telemetry.some(+ (event) => event.kind === 'activation-started' && event.ownerEpoch === 2+ )+ );+ const gracefulLockEvidence = await waitForPendingReplacementLock(+ 'epoch 2 exact owner lock request to become pending'+ );+ const gracefulWaitedForPhysicalLock = !telemetry.some(+ (event) => event.kind === 'ready' && event.ownerEpoch === 2+ );+ assert(+ gracefulWaitedForPhysicalLock,+ 'graceful replacement bypassed the held physical owner lock'+ );+ gracefulLock.release();+ await gracefulLock.completed;+ await waitUntil('production epoch 2 ready', () =>+ telemetry.some((event) => event.kind === 'ready' && event.ownerEpoch === 2)+ );+ const second = latestOwner(2);+ assert(second, 'missing production epoch 2 owner');+ expectProductionHit(+ await command(second.tabId, { kind: 'read' }),+ 'real-preserved'+ );++ await command(second.tabId, { kind: 'write', value: 'real-must-wipe' });+ expectProductionHit(+ await command(second.tabId, { kind: 'read' }),+ 'real-must-wipe'+ );+ const requester = tabIds.find(+ (tabId) => tabId !== first.tabId && tabId !== second.tabId+ );+ assert(requester, 'missing production abrupt requester');+ const slow = command(requester, { kind: 'slow-read' }).then(+ () => '',+ (error: unknown) => (error instanceof Error ? error.message : String(error))+ );+ await waitUntil('production slow request admission', () =>+ telemetry.some(+ (event) =>+ event.kind === 'request-admitted' &&+ event.ownerEpoch === 2 &&+ event.slow === true+ )+ );++ const abruptLock = queueOwnerLockContender();+ const secondPage = popups.get(second.tabId);+ assert(+ secondPage && !secondPage.closed,+ 'production owner page closed early'+ );+ await command(second.tabId, { kind: 'crash-worker' });+ const abruptError = await slow;+ assert(+ abruptError.includes('owner epoch 2 was lost'),+ 'production in-flight request was not rejected on abrupt loss'+ );+ await abruptLock.acquired;+ await waitUntil('production epoch 3 recovery activation', () =>+ telemetry.some(+ (event) => event.kind === 'activation-started' && event.ownerEpoch === 3+ )+ );+ const recoveryLockEvidence = await waitForPendingReplacementLock(+ 'epoch 3 exact owner lock request to become pending'+ );+ const recoveryWaitedForPhysicalLock = !telemetry.some(+ (event) => event.kind === 'ready' && event.ownerEpoch === 3+ );+ assert(+ recoveryWaitedForPhysicalLock,+ 'recovery replacement bypassed the held physical owner lock'+ );+ abruptLock.release();+ await abruptLock.completed;+ await waitUntil('production epoch 3 recovery ready', () =>+ telemetry.some((event) => event.kind === 'ready' && event.ownerEpoch === 3)+ );+ const third = latestOwner(3);+ assert(third, 'missing production epoch 3 owner');+ expectProductionMiss(await command(third.tabId, { kind: 'read' }));++ const slowAdmissions = telemetry.filter(+ (event) => event.kind === 'request-admitted' && event.slow === true+ );+ assert(slowAdmissions.length === 1, 'abrupt in-flight request was replayed');+ assert(!secondPage.closed, 'production worker crash closed its owner page');+ assert(+ terminated.some(+ (event) =>+ event.ownerEpoch === 2 &&+ event.reason.includes('production harness induced worker crash')+ ),+ 'production worker crash reason was not attributed'+ );+ assert(protocolErrors.length === 0, 'production coordinator protocol error');++ const result = {+ passed: true,+ realTursoDataPreservedGracefully: true,+ gracefulCloseReleasedOwnerLock: telemetry.some(+ (event) => event.kind === 'drained' && event.ownerEpoch === 1+ ),+ gracefulReplacementWaitedForPhysicalLock: gracefulWaitedForPhysicalLock,+ gracefulPendingOwnerLockRequests: gracefulLockEvidence.pending,+ abruptInflightRejected: abruptError.includes('owner epoch 2 was lost'),+ abruptRequestReplayCount: slowAdmissions.length,+ abruptOwnerPageStayedAlive: !secondPage.closed,+ recoveryReplacementWaitedForPhysicalLock: recoveryWaitedForPhysicalLock,+ recoveryPendingOwnerLockRequests: recoveryLockEvidence.pending,+ atomicRecoveryOpenWipedToMiss: true,+ recoveryDatabaseAction: telemetry.find(+ (event) => event.kind === 'ready' && event.ownerEpoch === 3+ )?.databaseAction,+ ownerEpochs: workers.map((worker) => worker.ownerEpoch),+ protocolErrors,+ };++ for (const popup of popups.values()) popup.close();+ tabChannel.close();+ telemetryChannel.close();+ return result;+};++function expectProductionHit(value: unknown, expected: string): void {+ assert(+ typeof value === 'object' &&+ value !== null &&+ (value as { kind?: unknown }).kind === 'hit' &&+ (+ value as {+ data?: { user?: { soup?: { items?: Array<{ id?: unknown }> } } };+ }+ ).data?.user?.soup?.items?.[0]?.id === expected,+ `expected production cache hit ${expected}`+ );+}++function expectProductionMiss(value: unknown): void {+ assert(+ typeof value === 'object' &&+ value !== null &&+ (value as { kind?: unknown }).kind === 'miss',+ 'expected production cache miss'+ );+}++void run().then(+ (result) => {+ resultElement.dataset.status = 'passed';+ resultElement.textContent = JSON.stringify(result, null, 2);+ },+ (error: unknown) => {+ resultElement.dataset.status = 'failed';+ resultElement.textContent =+ error instanceof Error ? (error.stack ?? error.message) : String(error);+ }+);diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/production-tab.html b/apps/web/src/lib/graphql-cache/worker/browser-test/production-tab.htmlnew file mode 100644index 0000000000..38297ff4e2--- /dev/null+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/production-tab.html@@ -0,0 +1,12 @@+<!doctype html>+<html lang="en">+ <head>+ <meta charset="UTF-8" />+ <link rel="icon" href="data:," />+ <title>WP-08 production Turso coordinator tab</title>+ </head>+ <body>+ <p>WP-08 production Turso coordinator tab</p>+ <script type="module" src="./production-tab.ts"></script>+ </body>+</html>diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/production-tab.ts b/apps/web/src/lib/graphql-cache/worker/browser-test/production-tab.tsnew file mode 100644index 0000000000..1b90e367d5--- /dev/null+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/production-tab.ts@@ -0,0 +1,217 @@+import { match } from 'ts-pattern';+import type { CacheRequest, CacheResponse } from '../../protocol';+import {+ createCacheCoordinatorPageAdapter,+ type DedicatedWorkerLike,+} from '../coordinator-page-adapter';+import type {+ ProductionHarnessCommand,+ ProductionHarnessEnvelope,+} from './production-browser-wire';++const parameters = new URLSearchParams(location.search);+const tabId = parameters.get('tabId') ?? '';+const scope = parameters.get('scope') ?? '';+if (!tabId || !scope) throw new Error('missing production harness parameters');++const QUERY = `query Soup($input: SoupInput!) {+ user {+ id+ soup(input: $input) {+ nextCursor+ items {+ __typename+ id+ }+ }+ }+}`;+const SLOW_QUERY = QUERY.replace('query Soup', 'query Slow');+const VARIABLES = { input: { limit: 1 } };++const channel = new BroadcastChannel(+ `graphql-cache-wp08-production-tabs:${scope}`+);+const report = (+ event: Extract<ProductionHarnessEnvelope, { source: 'tab' }>['event']+): void => {+ channel.postMessage({+ source: 'tab',+ tabId,+ event,+ } satisfies ProductionHarnessEnvelope);+};++let nextRequestId = 1;+let currentWorker: DedicatedWorkerLike | undefined;+const pending = new Map<number, (response: CacheResponse) => void>();++const adapter = createCacheCoordinatorPageAdapter({+ scope,+ tabId,+ createDedicatedWorker: (_workerScope, ownerEpoch) =>+ new Worker(+ new URL('./production-cache.engine-worker.ts', import.meta.url),+ {+ type: 'module',+ name: `graphql-cache-wp08-production:${scope}:${ownerEpoch}`,+ }+ ),+ onWorkerCreated: (worker, ownerEpoch) => {+ currentWorker = worker;+ report({ kind: 'worker-created', ownerEpoch });+ },+ onWorkerTerminated: (ownerEpoch, reason) => {+ currentWorker = undefined;+ report({ kind: 'worker-terminated', ownerEpoch, reason });+ },+ onProtocolError: (error) => {+ report({ kind: 'protocol-error', error: error.message });+ },+});++adapter.onmessage = (event) => {+ const message = event.data;+ if ('kind' in message) return;+ const resolve = pending.get(message.id);+ if (!resolve) return;+ pending.delete(message.id);+ resolve(message);+};++type CacheRequestWithoutId = CacheRequest extends infer Request+ ? Request extends CacheRequest+ ? Omit<Request, 'id'>+ : never+ : never;++const sendRequest = async (+ commandId: string,+ request: CacheRequestWithoutId+): Promise<void> => {+ const id = nextRequestId++;+ const response = new Promise<CacheResponse>((resolve) => {+ pending.set(id, resolve);+ });+ adapter.postMessage({ ...request, id } as CacheRequest);+ const result = await response;+ if (result.ok) {+ report({+ kind: 'command-result',+ commandId,+ ok: true,+ result: result.result,+ });+ } else {+ report({+ kind: 'command-result',+ commandId,+ ok: false,+ error: result.error,+ });+ }+};++const handleCommand = (command: ProductionHarnessCommand): void => {+ match(command)+ .with({ kind: 'write' }, (value) => {+ void sendRequest(value.commandId, {+ kind: 'write',+ query: QUERY,+ operationName: 'Soup',+ variables: VARIABLES,+ data: {+ user: {+ id: 'production-user',+ soup: {+ nextCursor: null,+ items: [{ __typename: 'GraphqlSoupDocument', id: value.value }],+ },+ },+ },+ identity: 'production-test-user',+ });+ })+ .with({ kind: 'read' }, (value) => {+ void sendRequest(value.commandId, {+ kind: 'read',+ query: QUERY,+ operationName: 'Soup',+ variables: VARIABLES,+ });+ })+ .with({ kind: 'slow-read' }, (value) => {+ void sendRequest(value.commandId, {+ kind: 'read',+ query: SLOW_QUERY,+ operationName: 'Slow',+ variables: VARIABLES,+ });+ })+ .with({ kind: 'graceful-close' }, (value) => {+ void adapter.dispose({ graceful: true }).then(() => {+ report({+ kind: 'command-result',+ commandId: value.commandId,+ ok: true,+ });+ setTimeout(() => window.close());+ });+ })+ .with({ kind: 'crash-worker' }, (value) => {+ if (!currentWorker) {+ report({+ kind: 'command-result',+ commandId: value.commandId,+ ok: false,+ error: 'tab has no production worker',+ });+ return;+ }+ currentWorker.postMessage({ testKind: 'crash' }, []);+ report({ kind: 'command-result', commandId: value.commandId, ok: true });+ })+ .with({ kind: 'arm-mutation-block' }, (value) => {+ if (!currentWorker) {+ report({+ kind: 'command-result',+ commandId: value.commandId,+ ok: false,+ error: 'tab has no production worker',+ });+ return;+ }+ currentWorker.postMessage(+ { testKind: 'arm-mutation-block', requestKind: value.requestKind },+ []+ );+ report({ kind: 'command-result', commandId: value.commandId, ok: true });+ })+ .with({ kind: 'request' }, (value) => {+ void sendRequest(value.commandId, value.request);+ })+ .with({ kind: 'terminate-worker' }, (value) => {+ if (!currentWorker) {+ report({+ kind: 'command-result',+ commandId: value.commandId,+ ok: false,+ error: 'tab has no production worker',+ });+ return;+ }+ currentWorker.terminate();+ report({ kind: 'command-result', commandId: value.commandId, ok: true });+ })+ .exhaustive();+};++channel.onmessage = (event: MessageEvent<ProductionHarnessEnvelope>) => {+ const message = event.data;+ if (message.source === 'harness' && message.targetTabId === tabId) {+ handleCommand(message.command);+ }+};++adapter.postMessage({ id: nextRequestId++, kind: 'init', scope });+void adapter.start().then(() => report({ kind: 'registered' }));diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/production.html b/apps/web/src/lib/graphql-cache/worker/browser-test/production.htmlnew file mode 100644index 0000000000..b8d1ee8a85--- /dev/null+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/production.html@@ -0,0 +1,12 @@+<!doctype html>+<html lang="en">+ <head>+ <meta charset="UTF-8" />+ <link rel="icon" href="data:," />+ <title>WP-08 production Turso coordinator harness</title>+ </head>+ <body>+ <pre id="result" data-status="running">running</pre>+ <script type="module" src="./production-harness.ts"></script>+ </body>+</html>diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/tab.html b/apps/web/src/lib/graphql-cache/worker/browser-test/tab.htmlnew file mode 100644index 0000000000..26200ebe37--- /dev/null+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/tab.html@@ -0,0 +1,12 @@+<!doctype html>+<html lang="en">+ <head>+ <meta charset="UTF-8" />+ <link rel="icon" href="data:," />+ <title>WP-08 coordinator tab</title>+ </head>+ <body>+ <p>WP-08 coordinator tab</p>+ <script type="module" src="./tab.ts"></script>+ </body>+</html>diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/tab.ts b/apps/web/src/lib/graphql-cache/worker/browser-test/tab.tsnew file mode 100644index 0000000000..3cc93fbde2--- /dev/null+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/tab.ts@@ -0,0 +1,215 @@+import { match } from 'ts-pattern';+import type { CacheRequest, CacheResponse } from '../../protocol';+import {+ createCacheCoordinatorPageAdapter,+ type DedicatedWorkerLike,+} from '../coordinator-page-adapter';+import type {+ BrowserHarnessCommand,+ BrowserHarnessEnvelope,+} from './browser-wire';++const parameters = new URLSearchParams(location.search);+const tabId = parameters.get('tabId') ?? '';+const scope = parameters.get('scope') ?? '';+if (!tabId || !scope) throw new Error('missing browser harness parameters');++const channel = new BroadcastChannel(`graphql-cache-wp08-tabs:${scope}`);+const report = (+ event: Extract<BrowserHarnessEnvelope, { source: 'tab' }>['event']+): void => {+ channel.postMessage({+ source: 'tab',+ tabId,+ event,+ } satisfies BrowserHarnessEnvelope);+};++let releaseLivenessLock!: () => void;+const releaseLivenessSignal = new Promise<void>((resolve) => {+ releaseLivenessLock = resolve;+});+const lockManager = {+ request: ((+ lockName: string,+ options: LockOptions,+ callback: (lock: Lock | null) => unknown+ ) =>+ navigator.locks.request(lockName, options, async (lock) => {+ // The harness intentionally releases liveness early and discards a+ // callback result that no caller consumes.+ await Promise.race([+ Promise.resolve(callback(lock)),+ releaseLivenessSignal,+ ]);+ })) as LockManager['request'],+};++let nextRequestId = 1;+let currentWorker: DedicatedWorkerLike | undefined;+const pending = new Map<+ number,+ { commandId: string; resolve: (response: CacheResponse) => void }+>();++const adapter = createCacheCoordinatorPageAdapter({+ scope,+ tabId,+ createSharedWorker: (workerScope) =>+ new SharedWorker(+ new URL('./fake-coordinator.shared-worker.ts', import.meta.url),+ {+ type: 'module',+ name: `graphql-cache-wp08-coordinator:${workerScope}`,+ }+ ),+ lockManager,+ createDedicatedWorker: (_scope, ownerEpoch) =>+ new Worker(new URL('./fake-cache.engine-worker.ts', import.meta.url), {+ type: 'module',+ name: `graphql-cache-wp08-fake:${scope}:${ownerEpoch}`,+ }),+ onWorkerCreated: (worker, ownerEpoch) => {+ currentWorker = worker;+ report({ kind: 'worker-created', ownerEpoch });+ },+ onWorkerTerminated: (ownerEpoch, reason) => {+ currentWorker = undefined;+ report({ kind: 'worker-terminated', ownerEpoch, reason });+ },+ onEngineReplaced: (ownerEpoch) => {+ report({ kind: 'engine-replaced', ownerEpoch });+ },+ onProtocolError: (error) => {+ report({ kind: 'protocol-error', error: error.message });+ },+});+report({ kind: 'adapter-created' });++adapter.onmessage = (event) => {+ const message = event.data;+ if ('kind' in message) {+ report({ kind: 'cache-push', pushKind: message.kind });+ return;+ }+ const waiter = pending.get(message.id);+ if (!waiter) return;+ pending.delete(message.id);+ waiter.resolve(message);+};++type CacheRequestWithoutId = CacheRequest extends infer Request+ ? Request extends CacheRequest+ ? Omit<Request, 'id'>+ : never+ : never;++const sendRequest = async (+ commandId: string,+ request: CacheRequestWithoutId+): Promise<void> => {+ const id = nextRequestId++;+ const response = new Promise<CacheResponse>((resolve) => {+ pending.set(id, { commandId, resolve });+ });+ adapter.postMessage({ ...request, id } as CacheRequest);+ const result = await response;+ if (result.ok) {+ report({+ kind: 'command-result',+ commandId,+ ok: true,+ result: result.result,+ });+ } else {+ report({+ kind: 'command-result',+ commandId,+ ok: false,+ error: result.error,+ });+ }+};++const handleCommand = (command: BrowserHarnessCommand): void => {+ match(command)+ .with({ kind: 'write' }, (value) => {+ void sendRequest(value.commandId, {+ kind: 'write',+ query: 'query Value { value }',+ data: { value: value.value },+ });+ })+ .with({ kind: 'read' }, (value) => {+ void sendRequest(value.commandId, {+ kind: 'read',+ query: 'query Value { value }',+ });+ })+ .with({ kind: 'slow-read' }, (value) => {+ void sendRequest(value.commandId, {+ kind: 'read',+ query: 'query Slow { value }',+ });+ })+ .with({ kind: 'graceful-close' }, (value) => {+ void adapter.dispose({ graceful: true }).then(() => {+ report({+ kind: 'command-result',+ commandId: value.commandId,+ ok: true,+ });+ setTimeout(() => window.close());+ });+ })+ .with({ kind: 'crash-worker' }, (value) => {+ if (!currentWorker) {+ report({+ kind: 'command-result',+ commandId: value.commandId,+ ok: false,+ error: 'tab has no worker',+ });+ return;+ }+ currentWorker.postMessage({ testKind: 'crash' }, []);+ report({ kind: 'command-result', commandId: value.commandId, ok: true });+ })+ .with({ kind: 'release-liveness-lock' }, (value) => {+ releaseLivenessLock();+ report({ kind: 'command-result', commandId: value.commandId, ok: true });+ })+ .with({ kind: 'stale-response' }, (value) => {+ if (!currentWorker) {+ report({+ kind: 'command-result',+ commandId: value.commandId,+ ok: false,+ error: 'tab has no worker',+ });+ return;+ }+ currentWorker.postMessage(+ {+ testKind: 'stale-response',+ ownerEpoch: value.ownerEpoch,+ routeId: value.routeId,+ },+ []+ );+ report({ kind: 'command-result', commandId: value.commandId, ok: true });+ })+ .exhaustive();+};++channel.onmessage = (event: MessageEvent<BrowserHarnessEnvelope>) => {+ const message = event.data;+ if (message.source === 'harness' && message.targetTabId === tabId) {+ handleCommand(message.command);+ }+};++// First cache use starts liveness registration. Every page deliberately uses+// request id 1, proving the coordinator must rewrite ids before engine routing.+adapter.postMessage({ id: nextRequestId++, kind: 'init', scope });+void adapter.start().then(() => report({ kind: 'registered' }));diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/vite.config.ts b/apps/web/src/lib/graphql-cache/worker/browser-test/vite.config.tsnew file mode 100644index 0000000000..221807ddf0--- /dev/null+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/vite.config.ts@@ -0,0 +1,56 @@+import { resolve } from 'node:path';+import { fileURLToPath } from 'node:url';+import { defineConfig } from 'vite';+import tsconfigPaths from 'vite-tsconfig-paths';++const directory = fileURLToPath(new URL('.', import.meta.url));++export default defineConfig(({ command }) => ({+ root: directory,+ base: command === 'build' ? '/app/' : '/',+ plugins: [+ tsconfigPaths({+ projects: [resolve(directory, '../../../../../tsconfig.json')],+ }),+ ],+ define: {+ __CACHE_WASM_BUILD_MODE__: JSON.stringify(+ command === 'build' ? 'production' : 'development'+ ),+ },+ server: {+ host: '127.0.0.1',+ port: 4188,+ strictPort: true,+ },+ preview: {+ host: '127.0.0.1',+ port: 4189,+ strictPort: true,+ },+ worker: { format: 'es' },+ build: {+ target: 'esnext',+ outDir: resolve(directory, '.dist-production'),+ emptyOutDir: true,+ sourcemap: true,+ assetsInlineLimit: 0,+ rollupOptions: {+ input: Object.fromEntries(+ [+ 'index.html',+ 'host.html',+ 'cutover.html',+ 'production.html',+ 'production-tab.html',+ 'tab.html',+ 'performance.html',+ 'exact-production-host.html',+ 'cache-lifecycle.html',+ 'graphql-soup-rollout.html',+ 'cache-recovery.html',+ ].map((name) => [name.replace('.html', ''), resolve(directory, name)])+ ),+ },+ },+}));diff --git a/apps/web/src/lib/graphql-cache/worker/cache-engine-runtime.test.ts b/apps/web/src/lib/graphql-cache/worker/cache-engine-runtime.test.tsnew file mode 100644index 0000000000..90ad4b5b4b--- /dev/null+++ b/apps/web/src/lib/graphql-cache/worker/cache-engine-runtime.test.ts@@ -0,0 +1,742 @@+import { describe, expect, it, vi } from 'vitest';+import type { CacheRequest } from '../protocol';+import {+ type CacheEngineRuntimeOptions,+ installCacheEngineWorker,+} from './cache-engine-runtime';+import {+ CACHE_COORDINATOR_PROTOCOL_VERSION,+ databaseOwnerLockName,+ type PageToEngineEnvelope,+} from './coordinator-protocol';+import {+ type CoordinatorMessagePort,+ CoordinatorRouter,+} from './coordinator-router';+import type { CacheWorkerCoreOptions } from './worker-core';++class FakePort {+ readonly messages: unknown[] = [];+ closed = false;+ started = false;+ onmessage: ((event: MessageEvent<unknown>) => void) | null = null;+ onmessageerror: (() => void) | null = null;++ postMessage(message: unknown): void {+ this.messages.push(message);+ }++ close(): void {+ this.closed = true;+ }++ start(): void {+ this.started = true;+ }++ receive(message: unknown): void {+ this.onmessage?.({ data: message, ports: [] } as unknown as MessageEvent);+ }+}++class FakeWorkerScope {+ closed = false;+ onmessage: ((event: MessageEvent<unknown>) => void) | null = null;++ close(): void {+ this.closed = true;+ }++ activate(+ activation: PageToEngineEnvelope,+ port: FakePort | MessagePort+ ): void {+ this.onmessage?.({+ data: activation,+ ports: [port as MessagePort],+ } as unknown as MessageEvent);+ }+}++const version = {+ coordinatorVersion: CACHE_COORDINATOR_PROTOCOL_VERSION,+} as const;++const activation = (+ databaseAction: 'open-existing' | 'wipe-before-open' = 'open-existing'+): PageToEngineEnvelope => ({+ ...version,+ kind: 'activate-engine',+ scope: 'scope',+ tabId: 'tab-a',+ ownerEpoch: 7,+ databaseAction,+ ownerLockName: 'owner-lock',+ hotCapacity: 11,+});++const messagesOfKind = <T extends string>(port: FakePort, kind: T) =>+ port.messages.filter(+ (message): message is Record<string, unknown> & { kind: T } =>+ typeof message === 'object' &&+ message !== null &&+ (message as { kind?: unknown }).kind === kind+ );++const registerTab = async (+ router: CoordinatorRouter,+ port: FakePort,+ tabId: string+): Promise<void> => {+ await router.handleTabMessage(port as CoordinatorMessagePort, {+ ...version,+ kind: 'register-tab',+ scope: 'scope',+ tabId,+ livenessLockName: `graphql-cache-tab:scope:${tabId}`,+ });+};++const attachRuntime = async (+ router: CoordinatorRouter,+ tabPort: FakePort,+ tabId: string,+ ownerEpoch: number,+ databaseAction: 'open-existing' | 'wipe-before-open',+ createCore: NonNullable<CacheEngineRuntimeOptions['createCore']>,+ outbound?: unknown[]+): Promise<{ channel: MessageChannel; scope: FakeWorkerScope }> => {+ const channel = new MessageChannel();+ if (outbound) {+ const postMessage = channel.port2.postMessage.bind(channel.port2);+ channel.port2.postMessage = ((message: unknown) => {+ outbound.push(message);+ postMessage(message);+ }) as MessagePort['postMessage'];+ }+ await router.handleTabMessage(+ tabPort as CoordinatorMessagePort,+ {+ ...version,+ kind: 'attach-engine-port',+ tabId,+ ownerEpoch,+ },+ [channel.port1]+ );+ const scope = new FakeWorkerScope();+ installCacheEngineWorker({+ scope,+ ownerLockIsHeld: async () => true,+ createCore,+ });+ scope.activate(+ {+ ...version,+ kind: 'activate-engine',+ scope: 'scope',+ tabId,+ ownerEpoch,+ databaseAction,+ ownerLockName: databaseOwnerLockName('scope'),+ },+ channel.port2+ );+ await vi.waitFor(() =>+ expect(router.snapshot()?.state).toMatchObject({+ kind: 'active',+ tabId,+ ownerEpoch,+ })+ );+ return { channel, scope };+};++const cacheResponses = (port: FakePort) =>+ messagesOfKind(port, 'cache-message').map(+ (message) => message.message as Record<string, unknown>+ );++describe('cache engine worker runtime', () => {+ it('selects atomic recovery-open and only proves wipe after initialization', async () => {+ const scope = new FakeWorkerScope();+ const direct = new FakePort();+ let coreOptions: CacheWorkerCoreOptions | undefined;+ const handleRequest = vi.fn(+ async (+ port: { postMessage(message: unknown): void },+ request: CacheRequest+ ) => {+ expect(request).toMatchObject({+ kind: 'init',+ scope: 'scope',+ hotCapacity: 11,+ });+ port.postMessage({ id: request.id, ok: true, result: null });+ }+ );+ installCacheEngineWorker({+ scope,+ ownerLockIsHeld: async () => true,+ createCore: (options) => {+ coreOptions = options;+ return {+ addPort: vi.fn(),+ handleRequest,+ drain: vi.fn(),+ };+ },+ });++ scope.activate(activation('wipe-before-open'), direct);+ await vi.waitFor(() =>+ expect(messagesOfKind(direct, 'engine-ready')).toHaveLength(1)+ );++ expect(coreOptions?.recoveryOpen).toBe(true);+ expect(messagesOfKind(direct, 'engine-ready')[0]).toMatchObject({+ tabId: 'tab-a',+ ownerEpoch: 7,+ databaseActionProof: 'wiped-before-open',+ });+ });++ it('throttles runtime linear memory, emits cached queue state, and drains high-water values', async () => {+ const scope = new FakeWorkerScope();+ const direct = new FakePort();+ const observations: Array<Record<string, unknown>> = [];+ const recordCachedQueueDiagnostics = vi.fn();+ let now = 0;+ let memoryBytes = 10;+ installCacheEngineWorker({+ scope,+ now: () => now,+ readLinearMemoryBytes: () => memoryBytes,+ memoryTelemetryIntervalMs: 60_000,+ ownerLockIsHeld: async () => true,+ telemetry: {+ record: (observation) => observations.push(observation),+ flush: vi.fn(),+ },+ createCore: () => ({+ addPort: vi.fn(),+ drain: vi.fn(),+ recordCachedQueueDiagnostics,+ handleRequest: async (port, request) => {+ port.postMessage({ id: request.id, ok: true, result: null });+ },+ }),+ });+ scope.activate(activation(), direct);+ await vi.waitFor(() =>+ expect(messagesOfKind(direct, 'engine-ready')).toHaveLength(1)+ );++ direct.receive({+ ...version,+ kind: 'heartbeat',+ ownerEpoch: 7,+ heartbeatId: 1,+ });+ now = 60_000;+ memoryBytes = 20;+ direct.receive({+ ...version,+ kind: 'heartbeat',+ ownerEpoch: 7,+ heartbeatId: 2,+ });+ memoryBytes = 15;+ direct.receive({+ ...version,+ kind: 'drain-engine',+ ownerEpoch: 7,+ });+ await vi.waitFor(() =>+ expect(messagesOfKind(direct, 'engine-drained')).toHaveLength(1)+ );++ expect(recordCachedQueueDiagnostics).toHaveBeenCalledTimes(2);+ expect(+ observations.filter(+ (observation) => observation.name === 'graphql_cache.linear_memory'+ )+ ).toEqual([+ expect.objectContaining({ bytes: 10, highWaterBytes: 10 }),+ expect.objectContaining({ bytes: 20, highWaterBytes: 20 }),+ expect.objectContaining({ bytes: 15, highWaterBytes: 20 }),+ ]);+ });++ it('fatals instead of forwarding a core-emitted coordinator-only error code', async () => {+ const scope = new FakeWorkerScope();+ const direct = new FakePort();+ installCacheEngineWorker({+ scope,+ ownerLockIsHeld: async () => true,+ createCore: () => ({+ addPort: vi.fn(),+ drain: vi.fn(),+ handleRequest: async (port, request) => {+ if (request.kind === 'init') {+ port.postMessage({ id: request.id, ok: true, result: null });+ return;+ }+ port.postMessage({+ id: request.id,+ ok: false,+ error: 'forged topology loss',+ errorCode: 'owner-epoch-lost',+ });+ },+ }),+ });+ scope.activate(activation(), direct);+ await vi.waitFor(() =>+ expect(messagesOfKind(direct, 'engine-ready')).toHaveLength(1)+ );++ direct.receive({+ ...version,+ kind: 'engine-request',+ ownerEpoch: 7,+ routeId: 1,+ request: { id: 1, kind: 'clear' },+ });+ await vi.waitFor(() =>+ expect(messagesOfKind(direct, 'engine-fatal')).toHaveLength(1)+ );++ expect(messagesOfKind(direct, 'engine-response')).toHaveLength(0);+ expect(messagesOfKind(direct, 'engine-fatal')[0]).toMatchObject({+ reason: 'CacheWorkerCore emitted a coordinator-only cache error code',+ fatalCode: 'runtime-failure',+ });+ });++ it('keeps an earlier injected admission ahead of drain and response ordering', async () => {+ const scope = new FakeWorkerScope();+ const direct = new FakePort();+ const order: string[] = [];+ let releaseHook!: () => void;+ const hookBlocker = new Promise<void>((resolve) => {+ releaseHook = resolve;+ });+ const handleRequest = vi.fn(+ async (+ port: { postMessage(message: unknown): void },+ request: CacheRequest+ ) => {+ if (request.kind === 'init') {+ port.postMessage({ id: request.id, ok: true, result: null });+ return;+ }+ order.push('request');+ port.postMessage({+ id: request.id,+ ok: true,+ result: { kind: 'miss' },+ });+ }+ );+ const drain = vi.fn(async () => {+ order.push('drain');+ });+ installCacheEngineWorker({+ scope,+ ownerLockIsHeld: async () => true,+ hooks: {+ beforeRequest: async (request) => {+ if (request.kind === 'read') await hookBlocker;+ },+ },+ createCore: () => ({ addPort: vi.fn(), handleRequest, drain }),+ });+ scope.activate(activation(), direct);+ await vi.waitFor(() =>+ expect(messagesOfKind(direct, 'engine-ready')).toHaveLength(1)+ );++ direct.receive({+ ...version,+ kind: 'engine-request',+ ownerEpoch: 7,+ routeId: 23,+ request: { id: 23, kind: 'read', query: 'query Slow { value }' },+ });+ direct.receive({+ ...version,+ kind: 'drain-engine',+ ownerEpoch: 7,+ });+ await Promise.resolve();+ expect(drain).not.toHaveBeenCalled();++ releaseHook();+ await vi.waitFor(() =>+ expect(messagesOfKind(direct, 'engine-drained')).toHaveLength(1)+ );++ expect(order).toEqual(['request', 'drain']);+ expect(+ direct.messages+ .filter(+ (message) =>+ typeof message === 'object' &&+ message !== null &&+ ['engine-response', 'engine-drained'].includes(+ String((message as { kind?: unknown }).kind)+ )+ )+ .map((message) => (message as { kind: string }).kind)+ ).toEqual(['engine-response', 'engine-drained']);+ expect(direct.closed).toBe(true);+ expect(scope.closed).toBe(true);+ });++ it('does not replay a completed mutation or leak its stale response and push after owner loss', async () => {+ const router = new CoordinatorRouter({+ verifyTabLockHeld: async () => true,+ watchTabLock: () => () => {},+ });+ const tabA = new FakePort();+ const tabB = new FakePort();+ await registerTab(router, tabA, 'tab-a');+ await registerTab(router, tabB, 'tab-b');++ let effectCount = 0;+ let markEffectStarted!: () => void;+ const effectStarted = new Promise<void>((resolve) => {+ markEffectStarted = resolve;+ });+ let releaseOldOutput!: () => void;+ const oldOutputBlocked = new Promise<void>((resolve) => {+ releaseOldOutput = resolve;+ });+ let markOldOutputPosted!: () => void;+ const oldOutputPosted = new Promise<void>((resolve) => {+ markOldOutputPosted = resolve;+ });+ const oldRuntime = await attachRuntime(+ router,+ tabA,+ 'tab-a',+ 1,+ 'open-existing',+ () => ({+ addPort: vi.fn(),+ drain: vi.fn(),+ handleRequest: async (port, request) => {+ if (request.kind === 'init') {+ port.postMessage({ id: request.id, ok: true, result: null });+ return;+ }+ if (request.kind !== 'clear') return;+ effectCount += 1;+ markEffectStarted();+ await oldOutputBlocked;+ port.postMessage({ id: request.id, ok: true, result: null });+ port.postMessage({ kind: 'cache-changed' });+ markOldOutputPosted();+ },+ })+ );++ await router.handleTabMessage(tabB as CoordinatorMessagePort, {+ ...version,+ kind: 'cache-request',+ tabId: 'tab-b',+ request: { id: 41, kind: 'clear' },+ });+ await effectStarted;+ expect(effectCount).toBe(1);+ expect(router.snapshot()?.inFlightRequestCount).toBe(1);++ await router.handleTabMessage(tabA as CoordinatorMessagePort, {+ ...version,+ kind: 'engine-lost',+ tabId: 'tab-a',+ ownerEpoch: 1,+ reason: 'injected owner failure after durable mutation',+ });+ await vi.waitFor(() =>+ expect(router.snapshot()?.state).toMatchObject({+ kind: 'activating',+ tabId: 'tab-b',+ ownerEpoch: 2,+ databaseAction: 'wipe-before-open',+ })+ );+ expect(cacheResponses(tabB)).toContainEqual({+ id: 41,+ ok: false,+ error: expect.stringContaining('owner epoch 1 was lost'),+ errorCode: 'owner-epoch-lost',+ });++ const replacementRequests: string[] = [];+ const replacementRuntime = await attachRuntime(+ router,+ tabB,+ 'tab-b',+ 2,+ 'wipe-before-open',+ () => ({+ addPort: vi.fn(),+ drain: vi.fn(),+ handleRequest: async (port, request) => {+ if (request.kind === 'init') {+ port.postMessage({ id: request.id, ok: true, result: null });+ return;+ }+ replacementRequests.push(request.kind);+ },+ })+ );++ releaseOldOutput();+ await oldOutputPosted;++ expect(effectCount).toBe(1);+ expect(replacementRequests).toEqual([]);+ expect(+ [...cacheResponses(tabA), ...cacheResponses(tabB)].filter(+ (message) => message.kind === 'cache-changed'+ )+ ).toEqual([]);+ expect(router.snapshot()?.state).toMatchObject({+ kind: 'active',+ ownerEpoch: 2,+ });++ oldRuntime.channel.port1.close();+ oldRuntime.channel.port2.close();+ replacementRuntime.channel.port1.close();+ replacementRuntime.channel.port2.close();+ });++ it('emits one authoritative reset sequence across live fatal and recovery replacement', async () => {+ const observations: Array<Record<string, unknown>> = [];+ const router = new CoordinatorRouter({+ verifyTabLockHeld: async () => true,+ watchTabLock: () => () => {},+ telemetry: {+ record: (observation) => observations.push(observation),+ flush: vi.fn(),+ },+ });+ const tabA = new FakePort();+ const tabB = new FakePort();+ await registerTab(router, tabA, 'tab-a');+ await registerTab(router, tabB, 'tab-b');++ const outbound: unknown[] = [];+ let markResetRequestStarted!: () => void;+ const resetRequestStarted = new Promise<void>((resolve) => {+ markResetRequestStarted = resolve;+ });+ let triggerReset!: () => void;+ const resetBlocked = new Promise<void>((resolve) => {+ triggerReset = resolve;+ });+ const runtime = await attachRuntime(+ router,+ tabA,+ 'tab-a',+ 1,+ 'open-existing',+ (options) => ({+ addPort: vi.fn(),+ drain: vi.fn(),+ handleRequest: async (port, request) => {+ if (request.kind === 'init') {+ port.postMessage({ id: request.id, ok: true, result: null });+ return;+ }+ if (request.kind === 'read') return;+ if (request.kind !== 'clear') return;+ markResetRequestStarted();+ await resetBlocked;+ options.onStorageResetRequired?.(+ Object.assign(new Error('storage reset'), {+ cacheStorageResetRequired: true as const,+ })+ );+ port.postMessage({+ id: request.id,+ ok: false,+ error: 'ordinary request error after reset marker',+ });+ },+ }),+ outbound+ );++ await router.handleTabMessage(tabB as CoordinatorMessagePort, {+ ...version,+ kind: 'cache-request',+ tabId: 'tab-b',+ request: { id: 51, kind: 'read', query: 'query Pending { value }' },+ });+ await vi.waitFor(() =>+ expect(router.snapshot()?.inFlightRequestCount).toBe(1)+ );+ await router.handleTabMessage(tabB as CoordinatorMessagePort, {+ ...version,+ kind: 'cache-request',+ tabId: 'tab-b',+ request: { id: 52, kind: 'clear' },+ });+ await resetRequestStarted;+ expect(router.snapshot()?.inFlightRequestCount).toBe(2);++ triggerReset();+ await vi.waitFor(() =>+ expect(router.snapshot()?.state).toMatchObject({+ kind: 'activating',+ ownerEpoch: 2,+ databaseAction: 'wipe-before-open',+ })+ );+ await vi.waitFor(() =>+ expect(+ outbound.filter(+ (message) =>+ typeof message === 'object' &&+ message !== null &&+ ['engine-fatal', 'engine-response'].includes(+ String((message as { kind?: unknown }).kind)+ )+ )+ ).toHaveLength(2)+ );++ const fatalAndResponse = outbound+ .filter(+ (message) =>+ typeof message === 'object' &&+ message !== null &&+ ['engine-fatal', 'engine-response'].includes(+ String((message as { kind?: unknown }).kind)+ )+ )+ .map((message) => (message as { kind: string }).kind);+ expect(fatalAndResponse).toEqual(['engine-fatal', 'engine-response']);+ expect(outbound).toContainEqual(+ expect.objectContaining({+ kind: 'engine-fatal',+ fatalCode: 'storage-reset-required',+ })+ );+ expect(router.snapshot()?.inFlightRequestCount).toBe(0);+ expect(cacheResponses(tabB)).toEqual(+ expect.arrayContaining([+ expect.objectContaining({+ id: 51,+ ok: false,+ error: expect.stringContaining(+ 'cache storage requested physical reset'+ ),+ }),+ expect.objectContaining({+ id: 52,+ ok: false,+ error: expect.stringContaining(+ 'cache storage requested physical reset'+ ),+ }),+ ])+ );+ expect(cacheResponses(tabB)).not.toContainEqual(+ expect.objectContaining({+ error: 'ordinary request error after reset marker',+ })+ );++ const replacementRuntime = await attachRuntime(+ router,+ tabB,+ 'tab-b',+ 2,+ 'wipe-before-open',+ (options) => ({+ addPort: vi.fn(),+ drain: vi.fn(),+ handleRequest: async (port, request) => {+ if (request.kind === 'init') {+ options.onInitializationOutcome?.('reset-storage-uncertain');+ port.postMessage({ id: request.id, ok: true, result: null });+ }+ },+ })+ );+ expect(+ observations+ .filter((observation) =>+ [+ 'graphql_cache.storage_reset_required',+ 'graphql_cache.logical_reset',+ 'graphql_cache.reset_wipe',+ ].includes(String(observation.name))+ )+ .map((observation) => observation.name)+ ).toEqual([+ 'graphql_cache.storage_reset_required',+ 'graphql_cache.logical_reset',+ 'graphql_cache.reset_wipe',+ ]);+ expect(+ observations.filter(+ (observation) =>+ observation.name === 'graphql_cache.storage_reset_required'+ )+ ).toHaveLength(1);++ runtime.channel.port1.close();+ runtime.channel.port2.close();+ replacementRuntime.channel.port1.close();+ replacementRuntime.channel.port2.close();+ });++ it('reports a fatal error for a valid envelope with the wrong owner epoch', async () => {+ const scope = new FakeWorkerScope();+ const direct = new FakePort();+ const handleRequest = vi.fn(+ async (+ port: { postMessage(message: unknown): void },+ request: CacheRequest+ ) => {+ port.postMessage({ id: request.id, ok: true, result: null });+ }+ );+ installCacheEngineWorker({+ scope,+ ownerLockIsHeld: async () => true,+ createCore: () => ({+ addPort: vi.fn(),+ handleRequest,+ drain: vi.fn(),+ }),+ });+ scope.activate(activation(), direct);+ await vi.waitFor(() =>+ expect(messagesOfKind(direct, 'engine-ready')).toHaveLength(1)+ );++ direct.receive({+ ...version,+ kind: 'heartbeat',+ ownerEpoch: 8,+ heartbeatId: 1,+ });++ expect(messagesOfKind(direct, 'engine-fatal')).toContainEqual(+ expect.objectContaining({+ tabId: 'tab-a',+ ownerEpoch: 7,+ reason: 'coordinator envelope owner epoch does not match activation',+ })+ );+ expect(messagesOfKind(direct, 'heartbeat-ack')).toHaveLength(0);+ });+});diff --git a/apps/web/src/lib/graphql-cache/worker/cache-engine-runtime.ts b/apps/web/src/lib/graphql-cache/worker/cache-engine-runtime.tsnew file mode 100644index 0000000000..c91d57954c--- /dev/null+++ b/apps/web/src/lib/graphql-cache/worker/cache-engine-runtime.ts@@ -0,0 +1,392 @@+/// <reference lib="webworker" />++import type { CacheRequest, CacheResponse } from '../protocol';+import {+ type CacheTelemetryRecorderLike,+ classifyCacheError,+ isolateCacheTelemetry,+} from '../telemetry';+import { workerCacheTelemetry } from '../telemetry-relay';+import {+ CACHE_COORDINATOR_PROTOCOL_VERSION,+ type CoordinatorToEngineEnvelope,+ type EngineFatalCode,+ type EngineOpenOutcome,+ type EngineToCoordinatorEnvelope,+ isCachePush,+ isCacheResponse,+ type PageToEngineEnvelope,+ validateCoordinatorToEngineEnvelope,+ validatePageToEngineEnvelope,+} from './coordinator-protocol';+import { cacheWasmLinearMemoryBytes } from './wasm-module';+import { CacheWorkerCore, type CacheWorkerCoreOptions } from './worker-core';++export type CacheEngineRuntimeEvent =+ | { kind: 'activation-started'; activation: PageToEngineEnvelope }+ | {+ kind: 'request-admitted';+ activation: PageToEngineEnvelope;+ request: CacheRequest;+ }+ | { kind: 'ready'; activation: PageToEngineEnvelope }+ | { kind: 'drained'; activation: PageToEngineEnvelope }+ | {+ kind: 'fatal';+ activation: PageToEngineEnvelope;+ reason: string;+ fatalCode: EngineFatalCode;+ };++export interface CacheEngineRuntimeHooks {+ beforeRequest?: (+ request: CacheRequest,+ activation: PageToEngineEnvelope+ ) => void | Promise<void>;+ onEvent?: (event: CacheEngineRuntimeEvent) => void;+}++interface CacheWorkerCoreLike {+ addPort(port: { postMessage(message: unknown): void }): void;+ handleRequest(+ port: { postMessage(message: unknown): void },+ request: CacheRequest+ ): Promise<void>;+ drain(): Promise<void>;+ recordCachedQueueDiagnostics?(): void;+}++interface DedicatedWorkerScopeLike {+ onmessage: ((event: MessageEvent<unknown>) => void) | null;+ close(): void;+}++export interface CacheEngineRuntimeOptions {+ scope?: DedicatedWorkerScopeLike;+ hooks?: CacheEngineRuntimeHooks;+ createCore?: (options: CacheWorkerCoreOptions) => CacheWorkerCoreLike;+ ownerLockIsHeld?: (ownerLockName: string) => Promise<boolean>;+ telemetry?: CacheTelemetryRecorderLike;+ /** Injectable clock/memory source for throttling tests. */+ now?: () => number;+ readLinearMemoryBytes?: () => number;+ memoryTelemetryIntervalMs?: number;+}++const withVersion = <T extends { coordinatorVersion: 1 }>(+ value: T extends unknown ? Omit<T, 'coordinatorVersion'> : never+): T =>+ ({+ coordinatorVersion: CACHE_COORDINATOR_PROTOCOL_VERSION,+ ...value,+ }) as unknown as T;++const errorMessage = (error: unknown): string =>+ error instanceof Error ? error.message : String(error);++async function initializeCore(+ core: CacheWorkerCoreLike,+ activation: PageToEngineEnvelope+): Promise<void> {+ let response: CacheResponse | undefined;+ await core.handleRequest(+ {+ postMessage(message: unknown) {+ if (isCacheResponse(message)) response = message;+ },+ },+ {+ id: 0,+ kind: 'init',+ scope: activation.scope,+ hotCapacity: activation.hotCapacity,+ }+ );+ if (!response || !response.ok) {+ throw new Error(+ response && !response.ok+ ? response.error+ : 'cache engine initialization returned no response'+ );+ }+}++async function defaultOwnerLockIsHeld(ownerLockName: string): Promise<boolean> {+ const snapshot = await navigator.locks.query();+ return Boolean(+ snapshot.held?.some(+ (lock) => lock.name === ownerLockName && lock.mode === 'exclusive'+ )+ );+}++async function activate(+ activation: PageToEngineEnvelope,+ directPort: MessagePort,+ workerScope: DedicatedWorkerScopeLike,+ options: CacheEngineRuntimeOptions+): Promise<void> {+ const hooks = options.hooks;+ const telemetry = isolateCacheTelemetry(+ options.telemetry ?? workerCacheTelemetry()+ );+ const now =+ options.now ?? (() => globalThis.performance?.now() ?? Date.now());+ const activationStartedAt = now();+ const readLinearMemoryBytes =+ options.readLinearMemoryBytes ?? cacheWasmLinearMemoryBytes;+ const memoryTelemetryIntervalMs = options.memoryTelemetryIntervalMs ?? 60_000;+ let lastMemoryTelemetryAt = Number.NEGATIVE_INFINITY;+ let linearMemoryHighWaterBytes = 0;+ const recordLinearMemory = (force: boolean): void => {+ const observedAt = now();+ if (+ !force &&+ observedAt - lastMemoryTelemetryAt < memoryTelemetryIntervalMs+ ) {+ return;+ }+ try {+ const bytes = readLinearMemoryBytes();+ linearMemoryHighWaterBytes = Math.max(linearMemoryHighWaterBytes, bytes);+ lastMemoryTelemetryAt = observedAt;+ telemetry.record({+ name: 'graphql_cache.linear_memory',+ operationCategory: 'storage',+ outcome: 'success',+ bytes,+ highWaterBytes: linearMemoryHighWaterBytes,+ });+ } catch {+ // A missing memory export only drops this observation.+ }+ };+ const emitEvent = (event: CacheEngineRuntimeEvent): void => {+ try {+ hooks?.onEvent?.(event);+ } catch {+ // Observation hooks are never part of the ownership protocol.+ }+ };+ emitEvent({ kind: 'activation-started', activation });+ let failed = false;+ let initializationOpenOutcome: EngineOpenOutcome =+ activation.databaseAction === 'wipe-before-open'+ ? 'reset-storage-uncertain'+ : 'opened-existing';+ let draining = false;+ const pendingAdmissions = new Set<Promise<void>>();+ const post = (message: EngineToCoordinatorEnvelope): void => {+ directPort.postMessage(message);+ };+ const fatal = (+ reason: string,+ fatalCode: EngineFatalCode = 'runtime-failure'+ ): void => {+ if (failed) return;+ failed = true;+ emitEvent({ kind: 'fatal', activation, reason, fatalCode });+ post(+ withVersion<EngineToCoordinatorEnvelope>({+ kind: 'engine-fatal',+ tabId: activation.tabId,+ ownerEpoch: activation.ownerEpoch,+ reason,+ fatalCode,+ })+ );+ };++ const createCore =+ options.createCore ??+ ((coreOptions: CacheWorkerCoreOptions) => new CacheWorkerCore(coreOptions));+ const core = createCore({+ recoveryOpen: activation.databaseAction === 'wipe-before-open',+ onStorageResetRequired: () => {+ fatal('cache storage requested physical reset', 'storage-reset-required');+ },+ onInitializationOutcome: (outcome) => {+ initializationOpenOutcome = outcome;+ },+ telemetry,+ });+ const enginePort = {+ postMessage(message: unknown): void {+ if (isCacheResponse(message)) {+ if (!message.ok && message.errorCode !== undefined) {+ fatal('CacheWorkerCore emitted a coordinator-only cache error code');+ return;+ }+ post(+ withVersion<EngineToCoordinatorEnvelope>({+ kind: 'engine-response',+ ownerEpoch: activation.ownerEpoch,+ routeId: message.id,+ response: message,+ })+ );+ return;+ }+ if (isCachePush(message)) {+ post(+ withVersion<EngineToCoordinatorEnvelope>({+ kind: 'engine-push',+ ownerEpoch: activation.ownerEpoch,+ push: message,+ })+ );+ return;+ }+ fatal('CacheWorkerCore emitted an invalid cache message');+ },+ };++ const admitRequest = (request: CacheRequest): void => {+ emitEvent({ kind: 'request-admitted', activation, request });+ if (!hooks?.beforeRequest) {+ void core.handleRequest(enginePort, request);+ return;+ }+ const admission = Promise.resolve(hooks.beforeRequest(request, activation))+ .then(async () => {+ if (!failed) await core.handleRequest(enginePort, request);+ })+ .catch((error: unknown) => {+ fatal(`engine request hook failed: ${errorMessage(error)}`);+ });+ pendingAdmissions.add(admission);+ void admission.finally(() => pendingAdmissions.delete(admission));+ };++ directPort.onmessage = (event: MessageEvent<unknown>) => {+ const parsed = validateCoordinatorToEngineEnvelope(event.data);+ if (!parsed.ok) {+ fatal(`invalid coordinator envelope: ${parsed.error}`);+ return;+ }+ const message: CoordinatorToEngineEnvelope = parsed.value;+ if (failed) return;+ if (message.ownerEpoch !== activation.ownerEpoch) {+ fatal('coordinator envelope owner epoch does not match activation');+ return;+ }+ switch (message.kind) {+ case 'engine-request':+ if (draining) {+ fatal('coordinator routed a request after drain began');+ return;+ }+ admitRequest(message.request);+ break;+ case 'drain-engine':+ if (draining) return;+ draining = true;+ void (async () => {+ await Promise.all(pendingAdmissions);+ await core.drain();+ recordLinearMemory(true);+ emitEvent({ kind: 'drained', activation });+ telemetry.flush();+ post(+ withVersion<EngineToCoordinatorEnvelope>({+ kind: 'engine-drained',+ tabId: activation.tabId,+ ownerEpoch: activation.ownerEpoch,+ })+ );+ directPort.close();+ workerScope.close();+ })().catch((error: unknown) =>+ fatal(`engine drain failed: ${errorMessage(error)}`)+ );+ break;+ case 'heartbeat':+ recordLinearMemory(false);+ core.recordCachedQueueDiagnostics?.();+ post(+ withVersion<EngineToCoordinatorEnvelope>({+ kind: 'heartbeat-ack',+ ownerEpoch: activation.ownerEpoch,+ heartbeatId: message.heartbeatId,+ })+ );+ break;+ }+ };+ directPort.onmessageerror = () => {+ fatal('coordinator direct MessagePort messageerror');+ };+ directPort.start();++ try {+ await initializeCore(core, activation);+ if (failed) return;+ const ownerLockIsHeld = options.ownerLockIsHeld ?? defaultOwnerLockIsHeld;+ if (!(await ownerLockIsHeld(activation.ownerLockName))) {+ throw new Error('cache engine does not hold its physical owner Web Lock');+ }+ core.addPort(enginePort);+ recordLinearMemory(true);+ post(+ withVersion<EngineToCoordinatorEnvelope>({+ kind: 'engine-ready',+ tabId: activation.tabId,+ ownerEpoch: activation.ownerEpoch,+ ownerLockName: activation.ownerLockName,+ ownerLockHeld: true,+ databaseActionProof: initializationOpenOutcome.startsWith('reset-')+ ? 'wiped-before-open'+ : 'opened-existing',+ openOutcome: initializationOpenOutcome,+ })+ );+ emitEvent({ kind: 'ready', activation });+ telemetry.record({+ name: 'graphql_cache.db_ready',+ operationCategory: 'initialization',+ outcome: 'success',+ errorCode: 'none',+ durationMs: now() - activationStartedAt,+ });+ } catch (error) {+ telemetry.record({+ name: 'graphql_cache.db_ready',+ operationCategory: 'initialization',+ outcome: 'error',+ errorCode: classifyCacheError(error),+ durationMs: now() - activationStartedAt,+ });+ telemetry.flush();+ post(+ withVersion<EngineToCoordinatorEnvelope>({+ kind: 'activation-failed',+ tabId: activation.tabId,+ ownerEpoch: activation.ownerEpoch,+ reason: errorMessage(error),+ failureCode:+ activation.databaseAction === 'wipe-before-open'+ ? 'recovery-open-failed'+ : 'initialization-failed',+ })+ );+ }+}++/** Installs the production dedicated-worker transport around CacheWorkerCore. */+export function installCacheEngineWorker(+ options: CacheEngineRuntimeOptions = {}+): void {+ const workerScope =+ options.scope ?? (self as unknown as DedicatedWorkerScopeLike);+ let activated = false;+ workerScope.onmessage = (event: MessageEvent<unknown>) => {+ const parsed = validatePageToEngineEnvelope(event.data);+ const directPort = event.ports[0];+ if (!parsed.ok || event.ports.length !== 1 || !directPort || activated) {+ for (const port of event.ports) port.close();+ return;+ }+ activated = true;+ void activate(parsed.value, directPort, workerScope, options);+ };+}diff --git a/apps/web/src/lib/graphql-cache/worker/cache.coordinator.shared-worker.ts b/apps/web/src/lib/graphql-cache/worker/cache.coordinator.shared-worker.tsnew file mode 100644index 0000000000..05dbcb7816--- /dev/null+++ b/apps/web/src/lib/graphql-cache/worker/cache.coordinator.shared-worker.ts@@ -0,0 +1,12 @@+/// <reference lib="webworker" />++import { CoordinatorRouter } from './coordinator-router';++declare const self: SharedWorkerGlobalScope;++const router = new CoordinatorRouter();++self.onconnect = (event: MessageEvent) => {+ const port = event.ports[0];+ if (port) router.connect(port);+};diff --git a/apps/web/src/lib/graphql-cache/worker/cache.engine-worker.ts b/apps/web/src/lib/graphql-cache/worker/cache.engine-worker.tsnew file mode 100644index 0000000000..02ae2afba8--- /dev/null+++ b/apps/web/src/lib/graphql-cache/worker/cache.engine-worker.ts@@ -0,0 +1,5 @@+/// <reference lib="webworker" />++import { installCacheEngineWorker } from './cache-engine-runtime';++installCacheEngineWorker();diff --git a/apps/web/src/lib/graphql-cache/worker/cache.shared-worker.ts b/apps/web/src/lib/graphql-cache/worker/cache.shared-worker.tsdeleted file mode 100644index 214c08f031..0000000000--- a/apps/web/src/lib/graphql-cache/worker/cache.shared-worker.ts+++ /dev/null@@ -1,31 +0,0 @@-/**- * SharedWorker entry: one engine shared by every tab (preferred topology).- */--import {- type CacheNotice,- type CacheRequest,- isCacheNotice,-} from '../protocol';-import { CacheWorkerCore } from './worker-core';--declare const self: SharedWorkerGlobalScope;--const core = new CacheWorkerCore();--self.onconnect = (event: MessageEvent) => {- const port = event.ports[0];- if (!port) return;- core.addPort(port);- port.onmessage = (msg: MessageEvent<CacheRequest | CacheNotice>) => {- // Clients announce disconnection (dispose/pagehide) — there is no- // platform event for it, and unpruned ports would accumulate.- if (isCacheNotice(msg.data)) {- core.removePort(port);- port.close();- return;- }- void core.handleRequest(port, msg.data);- };- port.start();-};diff --git a/apps/web/src/lib/graphql-cache/worker/coordinator-core.test.ts b/apps/web/src/lib/graphql-cache/worker/coordinator-core.test.tsnew file mode 100644index 0000000000..6124feb29d--- /dev/null+++ b/apps/web/src/lib/graphql-cache/worker/coordinator-core.test.ts@@ -0,0 +1,342 @@+import { describe, expect, it } from 'vitest';+import { type CoordinatorAction, CoordinatorCore } from './coordinator-core';+import type { DatabaseActionProof } from './coordinator-protocol';++const OWNER_LOCK = 'physical-owner-lock';++const action = <K extends CoordinatorAction['kind']>(+ actions: CoordinatorAction[],+ kind: K+): Extract<CoordinatorAction, { kind: K }> => {+ const found = actions.find((candidate) => candidate.kind === kind);+ if (!found) throw new Error(`missing ${kind}`);+ return found as Extract<CoordinatorAction, { kind: K }>;+};++const ready = (+ core: CoordinatorCore,+ tabId: string,+ ownerEpoch: number,+ databaseActionProof: DatabaseActionProof+): CoordinatorAction[] =>+ core.engineReady({+ tabId,+ ownerEpoch,+ ownerLockName: OWNER_LOCK,+ expectedOwnerLockName: OWNER_LOCK,+ ownerLockHeld: true,+ databaseActionProof,+ openOutcome:+ databaseActionProof === 'wiped-before-open'+ ? 'reset-storage-uncertain'+ : 'opened-existing',+ });++const init = (id: number) => ({ id, kind: 'init', scope: 'scope' }) as const;++const clear = (id: number) => ({ id, kind: 'clear' }) as const;++describe('CoordinatorCore', () => {+ it('covers waiting, activating, active, draining, and graceful reactivation', () => {+ const core = new CoordinatorCore('scope');+ expect(core.state).toEqual({+ kind: 'waiting-for-tab',+ nextDatabaseAction: 'open-existing',+ });++ expect(core.registerTab('tab-a')).toEqual([+ {+ kind: 'elect-owner',+ tabId: 'tab-a',+ ownerEpoch: 1,+ databaseAction: 'open-existing',+ },+ ]);+ core.registerTab('tab-b');+ core.registerTab('tab-c');+ expect(core.snapshot()).toMatchObject({+ state: { kind: 'activating', tabId: 'tab-a', ownerEpoch: 1 },+ activeOwnerCount: 0,+ tabIds: ['tab-a', 'tab-b', 'tab-c'],+ });++ core.request('tab-c', init(1));+ expect(core.snapshot().queuedRequestCount).toBe(1);+ const activation = ready(core, 'tab-a', 1, 'opened-existing');+ expect(action(activation, 'route-request')).toMatchObject({+ requesterTabId: 'tab-c',+ ownerTabId: 'tab-a',+ ownerEpoch: 1,+ request: { id: 1, kind: 'init' },+ });+ expect(core.snapshot().activeOwnerCount).toBe(1);++ expect(core.beginGracefulDeparture('tab-a', 1)).toEqual([+ { kind: 'drain-owner', tabId: 'tab-a', ownerEpoch: 1 },+ ]);+ expect(core.state.kind).toBe('draining');+ const handoff = core.engineDrained('tab-a', 1);+ expect(action(handoff, 'retire-tab')).toEqual({+ kind: 'retire-tab',+ tabId: 'tab-a',+ ownerEpoch: 1,+ });+ expect(action(handoff, 'elect-owner')).toEqual({+ kind: 'elect-owner',+ tabId: 'tab-b',+ ownerEpoch: 2,+ databaseAction: 'open-existing',+ });+ expect(ready(core, 'tab-b', 2, 'opened-existing')).toContainEqual({+ kind: 'broadcast-engine-replaced',+ ownerEpoch: 2,+ });+ });++ it('rejects unregistered and retiring-tab requests', () => {+ const core = new CoordinatorCore('scope');+ expect(core.request('missing', clear(1))).toEqual([+ expect.objectContaining({+ kind: 'reject-request',+ tabId: 'missing',+ requestId: 1,+ error: 'requester tab is not registered',+ }),+ ]);++ core.registerTab('tab-a');+ ready(core, 'tab-a', 1, 'opened-existing');+ core.beginGracefulDeparture('tab-a', 1);+ expect(core.request('tab-a', clear(2))).toEqual([+ expect.objectContaining({+ kind: 'reject-request',+ tabId: 'tab-a',+ requestId: 2,+ error: 'requester tab is retiring',+ }),+ ]);+ });++ it('rewrites colliding per-tab request ids into unique routes and restores them', () => {+ const core = new CoordinatorCore('scope');+ core.registerTab('tab-a');+ core.registerTab('tab-b');+ core.registerTab('tab-c');+ ready(core, 'tab-a', 1, 'opened-existing');++ const first = action(core.request('tab-b', clear(7)), 'route-request');+ const second = action(core.request('tab-c', clear(7)), 'route-request');+ expect(first.routeId).not.toBe(second.routeId);+ expect(first.request.id).toBe(first.routeId);+ expect(second.request.id).toBe(second.routeId);++ expect(+ core.engineResponse(1, second.routeId, {+ id: second.routeId,+ ok: true,+ result: 'second',+ })+ ).toEqual([+ {+ kind: 'deliver-response',+ tabId: 'tab-c',+ response: { id: 7, ok: true, result: 'second' },+ },+ ]);+ expect(+ core.engineResponse(1, first.routeId, {+ id: first.routeId,+ ok: true,+ result: 'first',+ })+ ).toEqual([+ {+ kind: 'deliver-response',+ tabId: 'tab-b',+ response: { id: 7, ok: true, result: 'first' },+ },+ ]);+ });++ it('continues routing earlier responses and pushes while draining, then queues later work', () => {+ const core = new CoordinatorCore('scope');+ core.registerTab('tab-a');+ core.registerTab('tab-b');+ ready(core, 'tab-a', 1, 'opened-existing');+ const routed = action(core.request('tab-b', clear(4)), 'route-request');++ core.beginGracefulDeparture('tab-a', 1);+ expect(core.request('tab-b', clear(5))).toEqual([]);+ expect(core.snapshot().queuedRequestCount).toBe(1);+ expect(core.enginePush(1, { kind: 'cache-changed' })).toEqual([+ { kind: 'broadcast-push', push: { kind: 'cache-changed' } },+ ]);+ expect(+ core.engineResponse(1, routed.routeId, {+ id: routed.routeId,+ ok: true,+ result: null,+ })+ ).toContainEqual({+ kind: 'deliver-response',+ tabId: 'tab-b',+ response: { id: 4, ok: true, result: null },+ });++ core.engineDrained('tab-a', 1);+ const activation = ready(core, 'tab-b', 2, 'opened-existing');+ expect(action(activation, 'route-request')).toMatchObject({+ requesterTabId: 'tab-b',+ ownerEpoch: 2,+ request: { kind: 'clear' },+ });+ });++ it('rejects old-epoch inflight work without replay and requires wipe proof', () => {+ const core = new CoordinatorCore('scope');+ core.registerTab('tab-a');+ core.registerTab('tab-b');+ ready(core, 'tab-a', 1, 'opened-existing');+ const old = action(core.request('tab-b', clear(9)), 'route-request');++ const loss = core.ownerLost('tab-a', 1, 'worker failed');+ expect(loss).toContainEqual({+ kind: 'reject-request',+ tabId: 'tab-b',+ requestId: 9,+ error: 'owner epoch 1 was lost: worker failed',+ errorCode: 'owner-epoch-lost',+ });+ expect(core.state).toEqual({+ kind: 'resetting-after-loss',+ previousTabId: 'tab-a',+ previousEpoch: 1,+ nextEpoch: 2,+ reason: 'worker failed',+ });+ expect(action(core.resumeAfterLoss(), 'elect-owner')).toMatchObject({+ tabId: 'tab-b',+ ownerEpoch: 2,+ databaseAction: 'wipe-before-open',+ });+ expect(ready(core, 'tab-b', 2, 'wiped-before-open')).toContainEqual({+ kind: 'broadcast-engine-replaced',+ ownerEpoch: 2,+ });++ expect(+ core.engineResponse(1, old.routeId, {+ id: old.routeId,+ ok: true,+ result: 'stale',+ })+ ).toEqual([+ {+ kind: 'drop-stale-engine-message',+ ownerEpoch: 1,+ routeId: old.routeId,+ reason: 'stale-epoch',+ },+ ]);+ expect(core.snapshot().staleMessageDrops).toBe(1);+ });++ it('drops unknown current routes and old-epoch pushes', () => {+ const core = new CoordinatorCore('scope');+ core.registerTab('tab-a');+ ready(core, 'tab-a', 1, 'opened-existing');++ expect(+ core.engineResponse(1, 77, { id: 77, ok: true, result: null })+ ).toContainEqual(+ expect.objectContaining({+ kind: 'drop-stale-engine-message',+ reason: 'unknown-route',+ })+ );+ expect(core.enginePush(0, { kind: 'cache-changed' })).toContainEqual(+ expect.objectContaining({+ kind: 'drop-stale-engine-message',+ reason: 'stale-epoch',+ })+ );+ });++ it('uses standby liveness loss without failover and owner liveness loss with wipe', () => {+ const core = new CoordinatorCore('scope');+ core.registerTab('tab-a');+ core.registerTab('tab-b');+ core.registerTab('tab-c');+ ready(core, 'tab-a', 1, 'opened-existing');++ expect(core.tabLost('tab-c')).toEqual([+ { kind: 'drop-tab', tabId: 'tab-c' },+ ]);+ expect(core.state).toEqual({+ kind: 'active',+ tabId: 'tab-a',+ ownerEpoch: 1,+ });+ expect(core.tabLost('tab-a')).toContainEqual({+ kind: 'schedule-reset-activation',+ });+ expect(action(core.resumeAfterLoss(), 'elect-owner')).toMatchObject({+ tabId: 'tab-b',+ ownerEpoch: 2,+ databaseAction: 'wipe-before-open',+ });+ });++ it('rejects wrong physical-lock and reset proofs without activating', () => {+ const core = new CoordinatorCore('scope');+ core.registerTab('tab-a');+ core.registerTab('tab-b');++ const wrongLock = core.engineReady({+ tabId: 'tab-a',+ ownerEpoch: 1,+ ownerLockName: 'wrong',+ expectedOwnerLockName: OWNER_LOCK,+ ownerLockHeld: true,+ databaseActionProof: 'opened-existing',+ openOutcome: 'opened-existing',+ });+ expect(action(wrongLock, 'protocol-violation').error).toContain(+ 'wrong physical owner lock'+ );+ core.resumeAfterLoss();+ const wrongProof = core.engineReady({+ tabId: 'tab-b',+ ownerEpoch: 2,+ ownerLockName: OWNER_LOCK,+ expectedOwnerLockName: OWNER_LOCK,+ ownerLockHeld: true,+ databaseActionProof: 'opened-existing',+ openOutcome: 'reset-storage-uncertain',+ });+ expect(action(wrongProof, 'protocol-violation').error).toContain(+ 'does not match open outcome'+ );+ expect(core.snapshot().activeOwnerCount).toBe(0);+ });++ it('retains wipe-before-open while no replacement tab is available', () => {+ const core = new CoordinatorCore('scope');+ core.registerTab('tab-a');+ ready(core, 'tab-a', 1, 'opened-existing');+ core.tabLost('tab-a');+ expect(core.resumeAfterLoss()).toEqual([]);+ expect(core.state).toEqual({+ kind: 'waiting-for-tab',+ nextDatabaseAction: 'wipe-before-open',+ });+ expect(core.registerTab('tab-b')).toEqual([+ {+ kind: 'elect-owner',+ tabId: 'tab-b',+ ownerEpoch: 2,+ databaseAction: 'wipe-before-open',+ },+ ]);+ });+});diff --git a/apps/web/src/lib/graphql-cache/worker/coordinator-core.ts b/apps/web/src/lib/graphql-cache/worker/coordinator-core.tsnew file mode 100644index 0000000000..317d97064b--- /dev/null+++ b/apps/web/src/lib/graphql-cache/worker/coordinator-core.ts@@ -0,0 +1,546 @@+import {+ type CachePush,+ type CacheRequest,+ type CacheResponse,+ type CacheResponseErrorCode,+ OWNER_EPOCH_LOST_ERROR_CODE,+} from '../protocol';+import type {+ DatabaseAction,+ DatabaseActionProof,+ EngineOpenOutcome,+ OwnerEpoch,+ RouteId,+} from './coordinator-protocol';++export type CoordinatorState =+ | { kind: 'waiting-for-tab'; nextDatabaseAction: DatabaseAction }+ | {+ kind: 'activating';+ tabId: string;+ ownerEpoch: OwnerEpoch;+ databaseAction: DatabaseAction;+ }+ | { kind: 'active'; tabId: string; ownerEpoch: OwnerEpoch }+ | { kind: 'draining'; tabId: string; ownerEpoch: OwnerEpoch }+ | {+ kind: 'resetting-after-loss';+ previousTabId: string;+ previousEpoch: OwnerEpoch;+ nextEpoch: OwnerEpoch;+ reason: string;+ };++export type CoordinatorSnapshot = {+ scope: string;+ state: CoordinatorState;+ tabIds: string[];+ ownerEpoch: OwnerEpoch;+ queuedRequestCount: number;+ inFlightRequestCount: number;+ staleMessageDrops: number;+ protocolViolations: number;+ activeOwnerCount: 0 | 1;+};++type QueuedRequest = {+ tabId: string;+ request: CacheRequest;+};++type InFlightRequest = QueuedRequest & {+ routeId: RouteId;+ ownerEpoch: OwnerEpoch;+};++export type CoordinatorAction =+ | {+ kind: 'elect-owner';+ tabId: string;+ ownerEpoch: OwnerEpoch;+ databaseAction: DatabaseAction;+ }+ | {+ kind: 'route-request';+ ownerTabId: string;+ requesterTabId: string;+ ownerEpoch: OwnerEpoch;+ routeId: RouteId;+ request: CacheRequest;+ }+ | { kind: 'deliver-response'; tabId: string; response: CacheResponse }+ | { kind: 'broadcast-push'; push: CachePush }+ | {+ kind: 'reject-request';+ tabId: string;+ requestId: number;+ error: string;+ errorCode?: CacheResponseErrorCode;+ }+ | { kind: 'drain-owner'; tabId: string; ownerEpoch: OwnerEpoch }+ | { kind: 'close-engine-route'; tabId: string; ownerEpoch: OwnerEpoch }+ | { kind: 'drop-tab'; tabId: string }+ | { kind: 'retire-tab'; tabId: string; ownerEpoch: OwnerEpoch }+ | { kind: 'schedule-reset-activation' }+ | { kind: 'broadcast-engine-replaced'; ownerEpoch: OwnerEpoch }+ | {+ kind: 'drop-stale-engine-message';+ ownerEpoch: OwnerEpoch;+ routeId?: RouteId;+ reason: 'stale-epoch' | 'unknown-route' | 'inactive-engine';+ }+ | { kind: 'protocol-violation'; error: string };++export type EngineReady = {+ tabId: string;+ ownerEpoch: OwnerEpoch;+ ownerLockName: string;+ expectedOwnerLockName: string;+ ownerLockHeld: true;+ databaseActionProof: DatabaseActionProof;+ openOutcome: EngineOpenOutcome;+};++const proofFor = (outcome: EngineOpenOutcome): DatabaseActionProof =>+ outcome.startsWith('reset-') ? 'wiped-before-open' : 'opened-existing';++/** Pure election, epoch, routing, drain, and abrupt-loss state machine. */+export class CoordinatorCore {+ private stateValue: CoordinatorState = {+ kind: 'waiting-for-tab',+ nextDatabaseAction: 'open-existing',+ };+ private readonly tabs: string[] = [];+ private readonly retiringTabs = new Set<string>();+ private readonly queuedRequests: QueuedRequest[] = [];+ private readonly inFlight = new Map<RouteId, InFlightRequest>();+ private currentEpoch = 0;+ private nextRouteId = 1;+ private staleMessageDrops = 0;+ private protocolViolations = 0;++ constructor(readonly scope: string) {+ if (scope.length === 0) throw new Error('scope must not be empty');+ }++ get state(): CoordinatorState {+ return { ...this.stateValue };+ }++ snapshot(): CoordinatorSnapshot {+ return {+ scope: this.scope,+ state: this.state,+ tabIds: [...this.tabs],+ ownerEpoch: this.currentEpoch,+ queuedRequestCount: this.queuedRequests.length,+ inFlightRequestCount: this.inFlight.size,+ staleMessageDrops: this.staleMessageDrops,+ protocolViolations: this.protocolViolations,+ activeOwnerCount: this.stateValue.kind === 'active' ? 1 : 0,+ };+ }++ registerTab(tabId: string): CoordinatorAction[] {+ if (this.tabs.includes(tabId)) return [];+ this.tabs.push(tabId);+ if (this.stateValue.kind !== 'waiting-for-tab') return [];+ return this.activateNext(this.stateValue.nextDatabaseAction);+ }++ request(tabId: string, request: CacheRequest): CoordinatorAction[] {+ if (!this.tabs.includes(tabId)) {+ return [+ this.reject(tabId, request.id, 'requester tab is not registered'),+ ];+ }+ if (this.retiringTabs.has(tabId)) {+ return [this.reject(tabId, request.id, 'requester tab is retiring')];+ }++ const queued = { tabId, request };+ if (this.stateValue.kind !== 'active') {+ this.queuedRequests.push(queued);+ return [];+ }+ return [this.route(queued, this.stateValue)];+ }++ engineReady(ready: EngineReady): CoordinatorAction[] {+ const state = this.stateValue;+ if (+ state.kind !== 'activating' ||+ state.tabId !== ready.tabId ||+ state.ownerEpoch !== ready.ownerEpoch+ ) {+ return this.recordProtocolViolation(+ `unexpected engine-ready from ${ready.tabId} at epoch ${ready.ownerEpoch}`+ );+ }++ let error: string | undefined;+ if (!ready.ownerLockHeld) {+ error = 'engine became ready without the exclusive owner lock';+ } else if (ready.ownerLockName !== ready.expectedOwnerLockName) {+ error = 'engine reported the wrong physical owner lock';+ } else if (ready.databaseActionProof !== proofFor(ready.openOutcome)) {+ error = `engine proof does not match open outcome ${ready.openOutcome}`;+ }+ if (error) {+ return [+ ...this.recordProtocolViolation(error),+ ...this.transitionToAbruptLoss(state.tabId, state.ownerEpoch, error),+ ];+ }++ this.stateValue = {+ kind: 'active',+ tabId: state.tabId,+ ownerEpoch: state.ownerEpoch,+ };+ const actions: CoordinatorAction[] = [];+ if (state.ownerEpoch > 1) {+ actions.push({+ kind: 'broadcast-engine-replaced',+ ownerEpoch: state.ownerEpoch,+ });+ }+ while (this.queuedRequests.length > 0) {+ const queued = this.queuedRequests.shift();+ if (queued && this.tabs.includes(queued.tabId)) {+ actions.push(this.route(queued, this.stateValue));+ }+ }+ this.assertInvariants();+ return actions;+ }++ engineResponse(+ ownerEpoch: OwnerEpoch,+ routeId: RouteId,+ response: CacheResponse+ ): CoordinatorAction[] {+ if (!this.acceptsEngineMessages(ownerEpoch)) {+ return [this.dropStale(ownerEpoch, routeId, 'stale-epoch')];+ }+ const request = this.inFlight.get(routeId);+ if (!request || request.ownerEpoch !== ownerEpoch) {+ return [this.dropStale(ownerEpoch, routeId, 'unknown-route')];+ }++ this.inFlight.delete(routeId);+ return [+ {+ kind: 'deliver-response',+ tabId: request.tabId,+ response: { ...response, id: request.request.id },+ },+ ];+ }++ enginePush(ownerEpoch: OwnerEpoch, push: CachePush): CoordinatorAction[] {+ if (!this.acceptsEngineMessages(ownerEpoch)) {+ return [this.dropStale(ownerEpoch, undefined, 'stale-epoch')];+ }+ return [{ kind: 'broadcast-push', push }];+ }++ beginGracefulDeparture(+ tabId: string,+ ownerEpoch: OwnerEpoch+ ): CoordinatorAction[] {+ const state = this.stateValue;+ if (+ state.kind !== 'active' ||+ state.tabId !== tabId ||+ state.ownerEpoch !== ownerEpoch+ ) {+ return this.recordProtocolViolation(+ `unexpected graceful departure from ${tabId} at epoch ${ownerEpoch}`+ );+ }+ this.retiringTabs.add(tabId);+ this.stateValue = { kind: 'draining', tabId, ownerEpoch };+ return [{ kind: 'drain-owner', tabId, ownerEpoch }];+ }++ engineDrained(tabId: string, ownerEpoch: OwnerEpoch): CoordinatorAction[] {+ const state = this.stateValue;+ if (+ state.kind !== 'draining' ||+ state.tabId !== tabId ||+ state.ownerEpoch !== ownerEpoch+ ) {+ return this.recordProtocolViolation(+ `unexpected engine-drained from ${tabId} at epoch ${ownerEpoch}`+ );+ }++ const actions = this.rejectEpochRequests(+ ownerEpoch,+ 'engine drained before delivering its response'+ );+ this.removeTabRecord(tabId);+ this.retiringTabs.delete(tabId);+ actions.push(+ { kind: 'close-engine-route', tabId, ownerEpoch },+ { kind: 'retire-tab', tabId, ownerEpoch }+ );+ this.stateValue = {+ kind: 'waiting-for-tab',+ nextDatabaseAction: 'open-existing',+ };+ actions.push(...this.activateNext('open-existing'));+ this.assertInvariants();+ return actions;+ }++ ownerLost(+ tabId: string,+ ownerEpoch: OwnerEpoch,+ reason: string+ ): CoordinatorAction[] {+ return this.transitionToAbruptLoss(tabId, ownerEpoch, reason);+ }++ tabLost(+ tabId: string,+ reason = 'tab liveness lock was released'+ ): CoordinatorAction[] {+ if (!this.tabs.includes(tabId)) return [];+ const state = this.stateValue;+ const wasOwner =+ (state.kind === 'active' ||+ state.kind === 'activating' ||+ state.kind === 'draining') &&+ state.tabId === tabId;++ const actions: CoordinatorAction[] = [{ kind: 'drop-tab', tabId }];+ if (wasOwner) {+ actions.push(+ ...this.transitionToAbruptLoss(tabId, state.ownerEpoch, reason)+ );+ }+ this.removeTabRecord(tabId);+ this.retiringTabs.delete(tabId);+ this.assertInvariants();+ return actions;+ }++ resumeAfterLoss(): CoordinatorAction[] {+ const state = this.stateValue;+ if (state.kind !== 'resetting-after-loss') return [];+ const candidate = this.chooseCandidate(state.previousTabId);+ if (!candidate) {+ this.stateValue = {+ kind: 'waiting-for-tab',+ nextDatabaseAction: 'wipe-before-open',+ };+ return [];+ }+ this.currentEpoch = state.nextEpoch;+ this.stateValue = {+ kind: 'activating',+ tabId: candidate,+ ownerEpoch: state.nextEpoch,+ databaseAction: 'wipe-before-open',+ };+ return [+ {+ kind: 'elect-owner',+ tabId: candidate,+ ownerEpoch: state.nextEpoch,+ databaseAction: 'wipe-before-open',+ },+ ];+ }++ expectsEngine(tabId: string, ownerEpoch: OwnerEpoch): boolean {+ return (+ this.stateValue.kind === 'activating' &&+ this.stateValue.tabId === tabId &&+ this.stateValue.ownerEpoch === ownerEpoch+ );+ }++ private transitionToAbruptLoss(+ tabId: string,+ ownerEpoch: OwnerEpoch,+ reason: string+ ): CoordinatorAction[] {+ const state = this.stateValue;+ if (+ (state.kind !== 'active' &&+ state.kind !== 'activating' &&+ state.kind !== 'draining') ||+ state.tabId !== tabId ||+ state.ownerEpoch !== ownerEpoch+ ) {+ return [];+ }++ const actions = this.rejectEpochRequests(+ ownerEpoch,+ `owner epoch ${ownerEpoch} was lost: ${reason}`,+ OWNER_EPOCH_LOST_ERROR_CODE+ );+ actions.push(+ { kind: 'close-engine-route', tabId, ownerEpoch },+ { kind: 'schedule-reset-activation' }+ );+ this.stateValue = {+ kind: 'resetting-after-loss',+ previousTabId: tabId,+ previousEpoch: ownerEpoch,+ nextEpoch: this.currentEpoch + 1,+ reason,+ };+ this.assertInvariants();+ return actions;+ }++ private rejectEpochRequests(+ ownerEpoch: OwnerEpoch,+ error: string,+ errorCode?: CacheResponseErrorCode+ ): CoordinatorAction[] {+ const actions: CoordinatorAction[] = [];+ for (const [routeId, request] of this.inFlight) {+ if (request.ownerEpoch !== ownerEpoch) continue;+ this.inFlight.delete(routeId);+ actions.push(+ this.reject(request.tabId, request.request.id, error, errorCode)+ );+ }+ return actions;+ }++ private activateNext(databaseAction: DatabaseAction): CoordinatorAction[] {+ const candidate = this.chooseCandidate();+ if (!candidate) {+ this.stateValue = {+ kind: 'waiting-for-tab',+ nextDatabaseAction: databaseAction,+ };+ return [];+ }+ this.currentEpoch += 1;+ this.stateValue = {+ kind: 'activating',+ tabId: candidate,+ ownerEpoch: this.currentEpoch,+ databaseAction,+ };+ return [+ {+ kind: 'elect-owner',+ tabId: candidate,+ ownerEpoch: this.currentEpoch,+ databaseAction,+ },+ ];+ }++ private chooseCandidate(avoid?: string): string | undefined {+ const eligible = this.tabs.filter((tabId) => !this.retiringTabs.has(tabId));+ return eligible.find((tabId) => tabId !== avoid) ?? eligible[0];+ }++ private route(+ queued: QueuedRequest,+ state: Extract<CoordinatorState, { kind: 'active' }>+ ): Extract<CoordinatorAction, { kind: 'route-request' }> {+ if (!Number.isSafeInteger(this.nextRouteId)) {+ throw new Error('coordinator route id space exhausted');+ }+ const routeId = this.nextRouteId++;+ this.inFlight.set(routeId, {+ ...queued,+ routeId,+ ownerEpoch: state.ownerEpoch,+ });+ return {+ kind: 'route-request',+ ownerTabId: state.tabId,+ requesterTabId: queued.tabId,+ ownerEpoch: state.ownerEpoch,+ routeId,+ request: { ...queued.request, id: routeId },+ };+ }++ private removeTabRecord(tabId: string): void {+ const index = this.tabs.indexOf(tabId);+ if (index >= 0) this.tabs.splice(index, 1);+ for (let index = this.queuedRequests.length - 1; index >= 0; index -= 1) {+ if (this.queuedRequests[index]?.tabId === tabId) {+ this.queuedRequests.splice(index, 1);+ }+ }+ for (const [routeId, request] of this.inFlight) {+ if (request.tabId === tabId) this.inFlight.delete(routeId);+ }+ }++ private acceptsEngineMessages(ownerEpoch: OwnerEpoch): boolean {+ return (+ (this.stateValue.kind === 'active' ||+ this.stateValue.kind === 'draining') &&+ this.stateValue.ownerEpoch === ownerEpoch+ );+ }++ private reject(+ tabId: string,+ requestId: number,+ error: string,+ errorCode?: CacheResponseErrorCode+ ): Extract<CoordinatorAction, { kind: 'reject-request' }> {+ return {+ kind: 'reject-request',+ tabId,+ requestId,+ error,+ ...(errorCode === undefined ? {} : { errorCode }),+ };+ }++ private dropStale(+ ownerEpoch: OwnerEpoch,+ routeId: RouteId | undefined,+ reason: Extract<+ CoordinatorAction,+ { kind: 'drop-stale-engine-message' }+ >['reason']+ ): Extract<CoordinatorAction, { kind: 'drop-stale-engine-message' }> {+ this.staleMessageDrops += 1;+ return {+ kind: 'drop-stale-engine-message',+ ownerEpoch,+ routeId,+ reason,+ };+ }++ private recordProtocolViolation(error: string): CoordinatorAction[] {+ this.protocolViolations += 1;+ return [{ kind: 'protocol-violation', error }];+ }++ private assertInvariants(): void {+ if (+ this.stateValue.kind !== 'active' &&+ this.stateValue.kind !== 'draining'+ ) {+ if (this.inFlight.size > 0) {+ throw new Error('invariant: requests are in flight without an owner');+ }+ return;+ }+ for (const request of this.inFlight.values()) {+ if (request.ownerEpoch !== this.stateValue.ownerEpoch) {+ throw new Error('invariant: in-flight request has a stale owner epoch');+ }+ }+ }+}diff --git a/apps/web/src/lib/graphql-cache/worker/coordinator-page-adapter.test.ts b/apps/web/src/lib/graphql-cache/worker/coordinator-page-adapter.test.tsnew file mode 100644index 0000000000..e2ab0ca6c4--- /dev/null+++ b/apps/web/src/lib/graphql-cache/worker/coordinator-page-adapter.test.ts@@ -0,0 +1,838 @@+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';+import {+ createCacheCoordinatorPageAdapter,+ type DedicatedWorkerLike,+ type SharedWorkerLike,+} from './coordinator-page-adapter';+import { CACHE_COORDINATOR_PROTOCOL_VERSION } from './coordinator-protocol';++class FakeCoordinatorPort {+ readonly messages: Array<{ message: unknown; transfer: Transferable[] }> = [];+ onmessage: ((event: MessageEvent<unknown>) => void) | null = null;+ onmessageerror: (() => void) | null = null;+ closed = false;+ readonly events: string[] = [];+ readonly throwKinds = new Set<string>();++ postMessage(message: unknown, transfer: Transferable[] = []): void {+ const kind = String((message as { kind?: unknown }).kind);+ this.events.push(`post:${kind}`);+ if (this.throwKinds.has(kind)) throw new Error(`${kind} send failed`);+ this.messages.push({ message, transfer });+ }++ start(): void {}++ close(): void {+ this.closed = true;+ this.events.push('close');+ }++ receive(message: unknown): void {+ this.onmessage?.({ data: message } as MessageEvent);+ }+}++class FakeTransferPort {+ onmessage = null;+ onmessageerror = null;+ closed = false;+ postMessage(): void {}+ start(): void {}+ close(): void {+ this.closed = true;+ }+}++class FakeMessageChannel {+ static readonly instances: FakeMessageChannel[] = [];+ port1 = new FakeTransferPort();+ port2 = new FakeTransferPort();++ constructor() {+ FakeMessageChannel.instances.push(this);+ }+}++class FakeWorker implements DedicatedWorkerLike {+ onerror: DedicatedWorkerLike['onerror'] = null;+ onmessageerror: DedicatedWorkerLike['onmessageerror'] = null;+ readonly messages: Array<{ message: unknown; transfer: Transferable[] }> = [];+ terminated = false;+ throwOnPost = false;++ postMessage(message: unknown, transfer: Transferable[]): void {+ if (this.throwOnPost) throw new Error('activate-engine send failed');+ this.messages.push({ message, transfer });+ }++ terminate(): void {+ this.terminated = true;+ }+}++const version = {+ coordinatorVersion: CACHE_COORDINATOR_PROTOCOL_VERSION,+} as const;++const heldLockManager = (events: string[] = []) =>+ ({+ request: vi.fn(+ async (+ name: string,+ _options: LockOptions,+ callback: (lock: Lock | null) => unknown+ ) => {+ events.push(`lock:${name}`);+ return await callback({ name, mode: 'exclusive' } as Lock);+ }+ ),+ }) as unknown as Pick<LockManager, 'request'>;++const election = (ownerEpoch: number) => ({+ ...version,+ kind: 'become-owner',+ scope: 'scope',+ tabId: 'tab-a',+ ownerEpoch,+ databaseAction:+ ownerEpoch === 1+ ? ('open-existing' as const)+ : ('wipe-before-open' as const),+ ownerLockName: 'physical-lock',+});++describe('CacheCoordinatorPageAdapter', () => {+ beforeEach(() => {+ FakeMessageChannel.instances.length = 0;+ vi.stubGlobal('MessageChannel', FakeMessageChannel);+ });++ afterEach(() => {+ vi.useRealTimers();+ vi.unstubAllGlobals();+ vi.restoreAllMocks();+ });++ it('is construction-safe, creates SharedWorker on first use, and DedicatedWorker only on election', async () => {+ const events: string[] = [];+ const coordinatorPort = new FakeCoordinatorPort();+ const sharedFactory = vi.fn(() => {+ events.push('shared-worker');+ return { port: coordinatorPort as unknown as MessagePort };+ });+ const dedicatedFactory = vi.fn(() => new FakeWorker());+ const adapter = createCacheCoordinatorPageAdapter({+ scope: 'scope',+ tabId: 'tab-a',+ lockManager: heldLockManager(events),+ createSharedWorker: sharedFactory,+ createDedicatedWorker: dedicatedFactory,+ });++ expect(events).toEqual([]);+ expect(sharedFactory).not.toHaveBeenCalled();+ expect(dedicatedFactory).not.toHaveBeenCalled();++ adapter.postMessage({ id: 1, kind: 'clear' });+ await vi.waitFor(() => expect(sharedFactory).toHaveBeenCalledOnce());+ expect(events).toEqual([+ 'lock:graphql-cache-tab:scope:tab-a',+ 'shared-worker',+ ]);+ expect(dedicatedFactory).not.toHaveBeenCalled();+ expect(+ (coordinatorPort.messages[0]!.message as { kind?: string }).kind+ ).toBe('register-tab');++ coordinatorPort.receive({ ...version, kind: 'registered', tabId: 'tab-a' });+ expect(+ coordinatorPort.messages.some(+ ({ message }) => (message as { kind?: string }).kind === 'cache-request'+ )+ ).toBe(true);+ expect(dedicatedFactory).not.toHaveBeenCalled();++ coordinatorPort.receive(election(1));+ expect(dedicatedFactory).toHaveBeenCalledOnce();+ const attach = coordinatorPort.messages.find(+ ({ message }) =>+ (message as { kind?: string }).kind === 'attach-engine-port'+ );+ expect(attach?.transfer).toHaveLength(1);+ });++ it('terminates and clears a failed worker before reporting owner loss', async () => {+ const order: string[] = [];+ const coordinatorPort = new FakeCoordinatorPort();+ const worker = new FakeWorker();+ worker.terminate = () => {+ worker.terminated = true;+ order.push('terminated');+ };+ coordinatorPort.postMessage = (message, transfer = []) => {+ coordinatorPort.messages.push({ message, transfer });+ if ((message as { kind?: string }).kind === 'engine-lost') {+ order.push('loss-reported');+ }+ };+ const adapter = createCacheCoordinatorPageAdapter({+ scope: 'scope',+ tabId: 'tab-a',+ lockManager: heldLockManager(),+ createSharedWorker: () => ({+ port: coordinatorPort as unknown as MessagePort,+ }),+ createDedicatedWorker: () => worker,+ });+ const started = adapter.start();+ await vi.waitFor(() => expect(coordinatorPort.messages).toHaveLength(1));+ coordinatorPort.receive({ ...version, kind: 'registered', tabId: 'tab-a' });+ await started;+ coordinatorPort.receive(election(1));++ worker.onerror?.call(+ {} as AbstractWorker,+ {+ message: 'worker crashed',+ preventDefault: vi.fn(),+ } as unknown as ErrorEvent+ );++ expect(order).toEqual(['terminated', 'loss-reported']);+ expect(worker.terminated).toBe(true);+ expect(coordinatorPort.messages).toContainEqual(+ expect.objectContaining({+ message: expect.objectContaining({+ kind: 'engine-lost',+ ownerEpoch: 1,+ reason: 'worker crashed',+ }),+ })+ );+ });++ it('accepts same-page replacement only after the failed worker was cleared', async () => {+ const coordinatorPort = new FakeCoordinatorPort();+ const workers = [new FakeWorker(), new FakeWorker()];+ const dedicatedFactory = vi.fn(() => workers.shift() as FakeWorker);+ const adapter = createCacheCoordinatorPageAdapter({+ scope: 'scope',+ tabId: 'tab-a',+ lockManager: heldLockManager(),+ createSharedWorker: () => ({+ port: coordinatorPort as unknown as MessagePort,+ }),+ createDedicatedWorker: dedicatedFactory,+ });+ const started = adapter.start();+ await vi.waitFor(() => expect(coordinatorPort.messages).toHaveLength(1));+ coordinatorPort.receive({ ...version, kind: 'registered', tabId: 'tab-a' });+ await started;+ coordinatorPort.receive(election(1));+ coordinatorPort.receive({+ ...version,+ kind: 'terminate-engine',+ tabId: 'tab-a',+ ownerEpoch: 1,+ reason: 'heartbeat timeout',+ });+ coordinatorPort.receive(election(2));++ expect(dedicatedFactory).toHaveBeenCalledTimes(2);+ });++ it('forwards validated cache messages and closes on malformed envelopes', async () => {+ const coordinatorPort = new FakeCoordinatorPort();+ const terminalErrors: string[] = [];+ const adapter = createCacheCoordinatorPageAdapter({+ scope: 'scope',+ tabId: 'tab-a',+ lockManager: heldLockManager(),+ createSharedWorker: () => ({+ port: coordinatorPort as unknown as MessagePort,+ }),+ createDedicatedWorker: () => new FakeWorker(),+ onTerminalError: (error) => terminalErrors.push(error.message),+ });+ const messages: unknown[] = [];+ adapter.onmessage = (event) => messages.push(event.data);+ const started = adapter.start();+ await vi.waitFor(() => expect(coordinatorPort.messages).toHaveLength(1));+ coordinatorPort.receive({ ...version, kind: 'registered', tabId: 'tab-a' });+ await started;++ coordinatorPort.receive({+ ...version,+ kind: 'cache-message',+ message: { id: 8, ok: true, result: 'ok' },+ });+ coordinatorPort.receive({+ ...version,+ kind: 'cache-message',+ message: { id: 'bad', ok: true, result: 'ignored' },+ });++ expect(messages).toEqual([{ id: 8, ok: true, result: 'ok' }]);+ expect(terminalErrors).toEqual([+ 'invalid cache-message coordinator envelope',+ ]);+ expect(coordinatorPort.closed).toBe(true);+ });++ it('settles queued RPC and does not retry construction after startup fails', async () => {+ const sharedFactory = vi.fn(() => {+ throw new Error('coordinator construction failed');+ });+ const terminalErrors: string[] = [];+ const messages: unknown[] = [];+ const adapter = createCacheCoordinatorPageAdapter({+ scope: 'scope',+ tabId: 'tab-a',+ lockManager: heldLockManager(),+ createSharedWorker: sharedFactory,+ createDedicatedWorker: () => new FakeWorker(),+ onTerminalError: (error) => terminalErrors.push(error.message),+ });+ adapter.onmessage = (event) => messages.push(event.data);++ adapter.postMessage({ id: 1, kind: 'clear' });+ await vi.waitFor(() => expect(messages).toHaveLength(1));+ adapter.postMessage({ id: 2, kind: 'clear' });++ expect(sharedFactory).toHaveBeenCalledOnce();+ expect(messages).toEqual([+ { id: 1, ok: false, error: 'coordinator construction failed' },+ { id: 2, ok: false, error: 'page adapter is closed' },+ ]);+ expect(terminalErrors).toEqual(['coordinator construction failed']);+ });++ it('keeps registered coordinator protocol diagnostics advisory', async () => {+ const coordinatorPort = new FakeCoordinatorPort();+ const protocolErrors: string[] = [];+ const terminalErrors: string[] = [];+ const adapter = createCacheCoordinatorPageAdapter({+ scope: 'scope',+ tabId: 'tab-a',+ lockManager: heldLockManager(),+ createSharedWorker: () => ({+ port: coordinatorPort as unknown as MessagePort,+ }),+ createDedicatedWorker: () => new FakeWorker(),+ onProtocolError: (error) => protocolErrors.push(error.message),+ onTerminalError: (error) => terminalErrors.push(error.message),+ });+ const started = adapter.start();+ await vi.waitFor(() => expect(coordinatorPort.messages).toHaveLength(1));+ coordinatorPort.receive({ ...version, kind: 'registered', tabId: 'tab-a' });+ await started;++ coordinatorPort.receive({+ ...version,+ kind: 'protocol-error',+ error: 'another tab sent a stale envelope',+ });++ expect(protocolErrors).toEqual(['another tab sent a stale envelope']);+ expect(terminalErrors).toEqual([]);+ expect(coordinatorPort.closed).toBe(false);+ await adapter.dispose();+ });++ it('terminates an owned engine before closing a failed SharedWorker transport', async () => {+ const order: string[] = [];+ const coordinatorPort = new FakeCoordinatorPort();+ coordinatorPort.close = () => {+ coordinatorPort.closed = true;+ order.push('coordinator-closed');+ };+ const sharedWorker: SharedWorkerLike = {+ port: coordinatorPort as unknown as MessagePort,+ onerror: null,+ };+ const worker = new FakeWorker();+ worker.terminate = () => {+ worker.terminated = true;+ order.push('engine-terminated');+ };+ const terminalErrors: string[] = [];+ const livenessReleased = vi.fn();+ const lockManager = {+ request: vi.fn(+ async (+ name: string,+ _options: LockOptions,+ callback: (lock: Lock | null) => unknown+ ) => {+ await callback({ name, mode: 'exclusive' } as Lock);+ livenessReleased();+ }+ ),+ } as unknown as Pick<LockManager, 'request'>;+ const adapter = createCacheCoordinatorPageAdapter({+ scope: 'scope',+ tabId: 'tab-a',+ lockManager,+ createSharedWorker: () => sharedWorker,+ createDedicatedWorker: () => worker,+ onTerminalError: (error) => {+ terminalErrors.push(error.message);+ order.push('terminal-reported');+ },+ });+ const started = adapter.start();+ await vi.waitFor(() => expect(coordinatorPort.messages).toHaveLength(1));+ coordinatorPort.receive({ ...version, kind: 'registered', tabId: 'tab-a' });+ await started;+ coordinatorPort.receive(election(1));++ sharedWorker.onerror?.call(+ {} as AbstractWorker,+ {+ message: 'SharedWorker crashed',+ preventDefault: vi.fn(),+ } as unknown as ErrorEvent+ );++ expect(order).toEqual([+ 'engine-terminated',+ 'coordinator-closed',+ 'terminal-reported',+ ]);+ expect(terminalErrors).toEqual(['SharedWorker crashed']);+ await vi.waitFor(() => expect(livenessReleased).toHaveBeenCalledOnce());+ });++ it('closes a standby transport on MessagePort messageerror exactly once', async () => {+ const coordinatorPort = new FakeCoordinatorPort();+ const terminalErrors: string[] = [];+ const dedicatedFactory = vi.fn(() => new FakeWorker());+ const adapter = createCacheCoordinatorPageAdapter({+ scope: 'scope',+ tabId: 'tab-a',+ lockManager: heldLockManager(),+ createSharedWorker: () => ({+ port: coordinatorPort as unknown as MessagePort,+ }),+ createDedicatedWorker: dedicatedFactory,+ onTerminalError: (error) => terminalErrors.push(error.message),+ });+ const started = adapter.start();+ await vi.waitFor(() => expect(coordinatorPort.messages).toHaveLength(1));+ coordinatorPort.receive({ ...version, kind: 'registered', tabId: 'tab-a' });+ await started;++ coordinatorPort.onmessageerror?.();+ coordinatorPort.onmessageerror?.();++ expect(dedicatedFactory).not.toHaveBeenCalled();+ expect(coordinatorPort.closed).toBe(true);+ expect(terminalErrors).toEqual(['coordinator MessagePort messageerror']);+ });++ it.each(['register-tab', 'cache-request'] as const)(+ 'terminal-fails exactly once when %s send throws',+ async (throwKind) => {+ const coordinatorPort = new FakeCoordinatorPort();+ coordinatorPort.throwKinds.add(throwKind);+ const terminalErrors: string[] = [];+ const adapter = createCacheCoordinatorPageAdapter({+ scope: 'scope',+ tabId: 'tab-a',+ lockManager: heldLockManager(),+ createSharedWorker: () => ({+ port: coordinatorPort as unknown as MessagePort,+ }),+ createDedicatedWorker: () => new FakeWorker(),+ onTerminalError: (error) => terminalErrors.push(error.message),+ });+ const messages: unknown[] = [];+ adapter.onmessage = (event) => messages.push(event.data);++ if (throwKind === 'cache-request') {+ const started = adapter.start();+ await vi.waitFor(() =>+ expect(coordinatorPort.messages).toHaveLength(1)+ );+ coordinatorPort.receive({+ ...version,+ kind: 'registered',+ tabId: 'tab-a',+ });+ await started;+ adapter.postMessage({ id: 1, kind: 'clear' });+ } else {+ adapter.postMessage({ id: 1, kind: 'clear' });+ await expect(adapter.start()).rejects.toThrow(+ 'register-tab send failed'+ );+ expect(messages).toEqual([+ { id: 1, ok: false, error: 'register-tab send failed' },+ ]);+ }++ await vi.waitFor(() => expect(terminalErrors).toHaveLength(1));+ coordinatorPort.onmessageerror?.();+ expect(terminalErrors).toEqual([`${throwKind} send failed`]);+ expect(coordinatorPort.closed).toBe(true);+ await adapter.dispose();+ }+ );++ it.each(['attach-engine-port', 'activate-engine'] as const)(+ 'closes untransferred channels and the worker when %s send throws',+ async (throwKind) => {+ const coordinatorPort = new FakeCoordinatorPort();+ const worker = new FakeWorker();+ if (throwKind === 'attach-engine-port') {+ coordinatorPort.throwKinds.add(throwKind);+ } else {+ worker.throwOnPost = true;+ }+ const terminalErrors: string[] = [];+ const adapter = createCacheCoordinatorPageAdapter({+ scope: 'scope',+ tabId: 'tab-a',+ lockManager: heldLockManager(),+ createSharedWorker: () => ({+ port: coordinatorPort as unknown as MessagePort,+ }),+ createDedicatedWorker: () => worker,+ onTerminalError: (error) => terminalErrors.push(error.message),+ });+ const started = adapter.start();+ await vi.waitFor(() => expect(coordinatorPort.messages).toHaveLength(1));+ coordinatorPort.receive({+ ...version,+ kind: 'registered',+ tabId: 'tab-a',+ });+ await started;+ coordinatorPort.receive(election(1));++ await vi.waitFor(() => expect(terminalErrors).toHaveLength(1));+ const channel = FakeMessageChannel.instances[0];+ expect(worker.terminated).toBe(true);+ expect(channel?.port2.closed).toBe(true);+ expect(channel?.port1.closed).toBe(throwKind === 'attach-engine-port');+ expect(coordinatorPort.closed).toBe(true);+ expect(terminalErrors[0]).toContain(`${throwKind} send failed`);+ }+ );++ it('terminal-fails after terminating an engine when owner-loss reporting throws', async () => {+ const coordinatorPort = new FakeCoordinatorPort();+ coordinatorPort.throwKinds.add('engine-lost');+ const worker = new FakeWorker();+ const terminalErrors: string[] = [];+ const adapter = createCacheCoordinatorPageAdapter({+ scope: 'scope',+ tabId: 'tab-a',+ lockManager: heldLockManager(),+ createSharedWorker: () => ({+ port: coordinatorPort as unknown as MessagePort,+ }),+ createDedicatedWorker: () => worker,+ onTerminalError: (error) => terminalErrors.push(error.message),+ });+ const started = adapter.start();+ await vi.waitFor(() => expect(coordinatorPort.messages).toHaveLength(1));+ coordinatorPort.receive({ ...version, kind: 'registered', tabId: 'tab-a' });+ await started;+ coordinatorPort.receive(election(1));++ worker.onerror?.call(+ {} as AbstractWorker,+ {+ message: 'engine crashed',+ preventDefault: vi.fn(),+ } as unknown as ErrorEvent+ );++ expect(worker.terminated).toBe(true);+ expect(coordinatorPort.closed).toBe(true);+ expect(terminalErrors).toEqual(['engine-lost send failed']);+ });++ it.each([+ { graceful: true, throwKind: 'graceful-departure' },+ { graceful: false, throwKind: 'disconnect-tab' },+ ])(+ 'settles $graceful disposal when $throwKind send throws',+ async ({ graceful, throwKind }) => {+ const coordinatorPort = new FakeCoordinatorPort();+ const worker = new FakeWorker();+ const terminalErrors: string[] = [];+ const adapter = createCacheCoordinatorPageAdapter({+ scope: 'scope',+ tabId: 'tab-a',+ lockManager: heldLockManager(),+ createSharedWorker: () => ({+ port: coordinatorPort as unknown as MessagePort,+ }),+ createDedicatedWorker: () => worker,+ onTerminalError: (error) => terminalErrors.push(error.message),+ });+ const started = adapter.start();+ await vi.waitFor(() => expect(coordinatorPort.messages).toHaveLength(1));+ coordinatorPort.receive({+ ...version,+ kind: 'registered',+ tabId: 'tab-a',+ });+ await started;+ coordinatorPort.receive(election(1));+ coordinatorPort.throwKinds.add(throwKind);++ await adapter.dispose({ graceful });++ expect(worker.terminated).toBe(true);+ expect(coordinatorPort.closed).toBe(true);+ expect(terminalErrors).toEqual([`${throwKind} send failed`]);+ }+ );++ it('settles graceful timeout when disconnect reporting throws', async () => {+ vi.useFakeTimers();+ const coordinatorPort = new FakeCoordinatorPort();+ const worker = new FakeWorker();+ const terminalErrors: string[] = [];+ const adapter = createCacheCoordinatorPageAdapter({+ scope: 'scope',+ tabId: 'tab-a',+ lockManager: heldLockManager(),+ createSharedWorker: () => ({+ port: coordinatorPort as unknown as MessagePort,+ }),+ createDedicatedWorker: () => worker,+ gracefulTimeoutMs: 10,+ onTerminalError: (error) => terminalErrors.push(error.message),+ });+ const started = adapter.start();+ await vi.waitFor(() => expect(coordinatorPort.messages).toHaveLength(1));+ coordinatorPort.receive({ ...version, kind: 'registered', tabId: 'tab-a' });+ await started;+ coordinatorPort.receive(election(1));+ coordinatorPort.throwKinds.add('disconnect-tab');++ const disposed = adapter.dispose({ graceful: true });+ await vi.advanceTimersByTimeAsync(11);+ await disposed;++ expect(worker.terminated).toBe(true);+ expect(coordinatorPort.closed).toBe(true);+ expect(terminalErrors).toEqual(['disconnect-tab send failed']);+ });++ it('rejects startup and queued RPC when disposed during lock acquisition', async () => {+ let allowLock!: () => void;+ const lockGate = new Promise<void>((resolve) => {+ allowLock = resolve;+ });+ const terminalErrors: string[] = [];+ const messages: unknown[] = [];+ const lockManager = {+ request: vi.fn(+ async (+ name: string,+ _options: LockOptions,+ callback: (lock: Lock | null) => unknown+ ) => {+ await lockGate;+ await callback({ name, mode: 'exclusive' } as Lock);+ throw new Error('late lock-manager rejection');+ }+ ),+ } as unknown as Pick<LockManager, 'request'>;+ const adapter = createCacheCoordinatorPageAdapter({+ scope: 'scope',+ tabId: 'tab-a',+ lockManager,+ createSharedWorker: vi.fn(),+ createDedicatedWorker: () => new FakeWorker(),+ onTerminalError: (error) => terminalErrors.push(error.message),+ });+ adapter.onmessage = (event) => messages.push(event.data);+ adapter.postMessage({ id: 1, kind: 'clear' });+ const started = adapter.start();++ await adapter.dispose();+ await expect(started).rejects.toThrow(+ 'page adapter was disposed during startup'+ );+ expect(messages).toEqual([+ {+ id: 1,+ ok: false,+ error: 'page adapter was disposed during startup',+ },+ ]);+ allowLock();+ await Promise.resolve();+ await Promise.resolve();++ expect(terminalErrors).toEqual([]);+ await expect(adapter.start()).rejects.toThrow('page adapter is closed');+ });++ it('rejects stale elections and deduplicates replacement epochs monotonically', async () => {+ const coordinatorPort = new FakeCoordinatorPort();+ const firstWorker = new FakeWorker();+ const workers = [firstWorker, new FakeWorker()];+ const dedicatedFactory = vi.fn(() => workers.shift() as FakeWorker);+ const replacements: number[] = [];+ const terminalErrors: string[] = [];+ const adapter = createCacheCoordinatorPageAdapter({+ scope: 'scope',+ tabId: 'tab-a',+ lockManager: heldLockManager(),+ createSharedWorker: () => ({+ port: coordinatorPort as unknown as MessagePort,+ }),+ createDedicatedWorker: dedicatedFactory,+ onEngineReplaced: (epoch) => replacements.push(epoch),+ onTerminalError: (error) => terminalErrors.push(error.message),+ });+ const started = adapter.start();+ await vi.waitFor(() => expect(coordinatorPort.messages).toHaveLength(1));+ coordinatorPort.receive({ ...version, kind: 'registered', tabId: 'tab-a' });+ await started;+ coordinatorPort.receive(election(1));+ coordinatorPort.receive({+ ...version,+ kind: 'engine-replaced',+ ownerEpoch: 1,+ });+ coordinatorPort.receive({+ ...version,+ kind: 'engine-replaced',+ ownerEpoch: 1,+ });+ coordinatorPort.receive({+ ...version,+ kind: 'terminate-engine',+ tabId: 'tab-a',+ ownerEpoch: 1,+ reason: 'lost',+ });+ coordinatorPort.receive(election(1));++ expect(replacements).toEqual([1]);+ expect(dedicatedFactory).toHaveBeenCalledOnce();+ expect(firstWorker.messages).toHaveLength(1);+ expect(firstWorker.messages[0]?.message).toMatchObject({+ kind: 'activate-engine',+ ownerEpoch: 1,+ });+ expect(workers).toHaveLength(1);+ expect(coordinatorPort.closed).toBe(true);+ expect(terminalErrors).toEqual([+ 'coordinator elected stale or duplicate owner epoch 1',+ ]);+ });++ it('escalates an owner graceful drain to abrupt disposal on pagehide', async () => {+ const coordinatorPort = new FakeCoordinatorPort();+ const worker = new FakeWorker();+ const adapter = createCacheCoordinatorPageAdapter({+ scope: 'scope',+ tabId: 'tab-a',+ lockManager: heldLockManager(),+ createSharedWorker: () => ({+ port: coordinatorPort as unknown as MessagePort,+ }),+ createDedicatedWorker: () => worker,+ });+ const started = adapter.start();+ await vi.waitFor(() => expect(coordinatorPort.messages).toHaveLength(1));+ coordinatorPort.receive({ ...version, kind: 'registered', tabId: 'tab-a' });+ await started;+ coordinatorPort.receive(election(1));++ const graceful = adapter.dispose({ graceful: true });+ expect(worker.terminated).toBe(false);+ const abrupt = adapter.dispose({ graceful: false });+ expect(abrupt).toBe(graceful);+ await abrupt;++ expect(worker.terminated).toBe(true);+ expect(coordinatorPort.closed).toBe(true);+ expect(+ coordinatorPort.events.filter((event) => event === 'post:disconnect-tab')+ ).toHaveLength(1);+ });++ it('terminal-fails when the owned engine crashes during graceful drain', async () => {+ const coordinatorPort = new FakeCoordinatorPort();+ const worker = new FakeWorker();+ const terminalErrors: string[] = [];+ const adapter = createCacheCoordinatorPageAdapter({+ scope: 'scope',+ tabId: 'tab-a',+ lockManager: heldLockManager(),+ createSharedWorker: () => ({+ port: coordinatorPort as unknown as MessagePort,+ }),+ createDedicatedWorker: () => worker,+ onTerminalError: (error) => terminalErrors.push(error.message),+ });+ const started = adapter.start();+ await vi.waitFor(() => expect(coordinatorPort.messages).toHaveLength(1));+ coordinatorPort.receive({ ...version, kind: 'registered', tabId: 'tab-a' });+ await started;+ coordinatorPort.receive(election(1));++ const disposed = adapter.dispose({ graceful: true });+ worker.onerror?.call(+ {} as AbstractWorker,+ {+ message: 'engine failed while draining',+ preventDefault: vi.fn(),+ } as unknown as ErrorEvent+ );+ await disposed;++ expect(worker.terminated).toBe(true);+ expect(coordinatorPort.closed).toBe(true);+ expect(terminalErrors).toEqual(['engine failed while draining']);+ });++ it('keeps the worker alive through graceful drain and terminates after retire-complete', async () => {+ vi.useFakeTimers();+ const coordinatorPort = new FakeCoordinatorPort();+ const worker = new FakeWorker();+ const adapter = createCacheCoordinatorPageAdapter({+ scope: 'scope',+ tabId: 'tab-a',+ lockManager: heldLockManager(),+ createSharedWorker: () => ({+ port: coordinatorPort as unknown as MessagePort,+ }),+ createDedicatedWorker: () => worker,+ });+ const started = adapter.start();+ await vi.waitFor(() => expect(coordinatorPort.messages).toHaveLength(1));+ coordinatorPort.receive({ ...version, kind: 'registered', tabId: 'tab-a' });+ await started;+ coordinatorPort.receive(election(1));++ const disposed = adapter.dispose({ graceful: true });+ expect(worker.terminated).toBe(false);+ expect(coordinatorPort.messages).toContainEqual(+ expect.objectContaining({+ message: expect.objectContaining({ kind: 'graceful-departure' }),+ })+ );+ coordinatorPort.receive({+ ...version,+ kind: 'retire-complete',+ tabId: 'tab-a',+ ownerEpoch: 1,+ });+ await disposed;++ expect(worker.terminated).toBe(true);+ expect(coordinatorPort.closed).toBe(true);+ });+});diff --git a/apps/web/src/lib/graphql-cache/worker/coordinator-page-adapter.ts b/apps/web/src/lib/graphql-cache/worker/coordinator-page-adapter.tsnew file mode 100644index 0000000000..7e5b36de67--- /dev/null+++ b/apps/web/src/lib/graphql-cache/worker/coordinator-page-adapter.ts@@ -0,0 +1,747 @@+import type { CacheRequest, WorkerMessage } from '../protocol';+import {+ type CacheTelemetryRecorderLike,+ classifyCacheError,+ isolateCacheTelemetry,+} from '../telemetry';+import {+ CACHE_COORDINATOR_PROTOCOL_VERSION,+ type CoordinatorToTabEnvelope,+ isCacheRequest,+ type PageToEngineEnvelope,+ type TabToCoordinatorEnvelope,+ tabLivenessLockName,+ validateCoordinatorToTabEnvelope,+} from './coordinator-protocol';++export interface SharedWorkerLike {+ readonly port: MessagePort;+ onerror?: ((this: AbstractWorker, event: ErrorEvent) => unknown) | null;+}++export interface DedicatedWorkerLike {+ onerror: ((this: AbstractWorker, event: ErrorEvent) => unknown) | null;+ onmessageerror: ((this: Worker, event: MessageEvent) => unknown) | null;+ postMessage(message: unknown, transfer: Transferable[]): void;+ terminate(): void;+}++export interface CacheCoordinatorPageAdapterOptions {+ scope: string;+ hotCapacity?: number;+ tabId?: string;+ createSharedWorker?: (scope: string) => SharedWorkerLike;+ createDedicatedWorker?: (+ scope: string,+ ownerEpoch: number+ ) => DedicatedWorkerLike;+ lockManager?: Pick<LockManager, 'request'>;+ onEngineReplaced?: (ownerEpoch: number) => void;+ onOwnerChanged?: (ownerEpoch: number | undefined) => void;+ onWorkerCreated?: (worker: DedicatedWorkerLike, ownerEpoch: number) => void;+ onWorkerTerminated?: (ownerEpoch: number, reason: string) => void;+ /** Advisory coordinator diagnostic after successful registration. */+ onProtocolError?: (error: Error) => void;+ /** Fatal SharedWorker/MessagePort/envelope failure after resources close. */+ onTerminalError?: (error: Error) => void;+ gracefulTimeoutMs?: number;+ /** Privacy-safe lifecycle recorder supplied by the browser host. */+ telemetry?: CacheTelemetryRecorderLike;+}++export interface PageAdapterDisposeOptions {+ graceful?: boolean;+}++const DEFAULT_GRACEFUL_TIMEOUT_MS = 10_000;++const withVersion = <T extends { coordinatorVersion: 1 }>(+ value: T extends unknown ? Omit<T, 'coordinatorVersion'> : never+): T =>+ ({+ coordinatorVersion: CACHE_COORDINATOR_PROTOCOL_VERSION,+ ...value,+ }) as unknown as T;++const defaultSharedWorkerFactory = (scope: string): SharedWorkerLike =>+ new SharedWorker(+ new URL('./cache.coordinator.shared-worker.ts', import.meta.url),+ { type: 'module', name: `graphql-cache-coordinator:${scope}` }+ );++const defaultDedicatedWorkerFactory = (+ scope: string,+ ownerEpoch: number+): DedicatedWorkerLike =>+ new Worker(new URL('./cache.engine-worker.ts', import.meta.url), {+ type: 'module',+ name: `graphql-cache-engine:${scope}:${ownerEpoch}`,+ });++/**+ * Import-safe page endpoint for the browser coordinator topology.+ * SharedWorker creation starts on first use; DedicatedWorker creation starts+ * only after a current-epoch election.+ */+export class CacheCoordinatorPageAdapter {+ readonly tabId: string;+ onmessage: ((event: MessageEvent<WorkerMessage>) => void) | null = null;++ private readonly createSharedWorker: (scope: string) => SharedWorkerLike;+ private readonly createDedicatedWorker: (+ scope: string,+ ownerEpoch: number+ ) => DedicatedWorkerLike;+ private readonly lockManager: Pick<LockManager, 'request'> | undefined;+ private readonly gracefulTimeoutMs: number;+ private sharedWorker: SharedWorkerLike | undefined;+ private engineWorker: DedicatedWorkerLike | undefined;+ private ownerEpoch: number | undefined;+ private registered = false;+ private startPromise: Promise<void> | undefined;+ private resolveRegistration: (() => void) | undefined;+ private rejectRegistration: ((error: Error) => void) | undefined;+ private readonly queuedRequests: CacheRequest[] = [];+ private releaseLivenessLock: (() => void) | undefined;+ private disposePromise: Promise<void> | undefined;+ private resolveDispose: (() => void) | undefined;+ private gracefulTimeout: ReturnType<typeof setTimeout> | undefined;+ private disposeMode: 'graceful' | 'abrupt' | undefined;+ private pagehideRegistered = false;+ private terminalErrorReported = false;+ private readonly terminatedOwnerEpochs = new Set<number>();+ private highestOwnerEpochSeen = 0;+ private latestEngineReplacedEpoch = 0;+ private closed = false;+ private readonly telemetry: CacheTelemetryRecorderLike;+ private readonly now = (): number =>+ globalThis.performance?.now() ?? Date.now();++ constructor(private readonly options: CacheCoordinatorPageAdapterOptions) {+ if (!options.scope) throw new Error('cache coordinator scope is required');+ if (+ options.hotCapacity !== undefined &&+ (!Number.isSafeInteger(options.hotCapacity) || options.hotCapacity <= 0)+ ) {+ throw new Error('hot capacity must be a positive integer');+ }+ this.tabId = options.tabId ?? crypto.randomUUID();+ this.createSharedWorker =+ options.createSharedWorker ?? defaultSharedWorkerFactory;+ this.createDedicatedWorker =+ options.createDedicatedWorker ?? defaultDedicatedWorkerFactory;+ this.lockManager = options.lockManager;+ this.gracefulTimeoutMs =+ options.gracefulTimeoutMs ?? DEFAULT_GRACEFUL_TIMEOUT_MS;+ this.telemetry = isolateCacheTelemetry(options.telemetry);+ }++ /** Acquires tab liveness and registers without constructing an engine. */+ start(): Promise<void> {+ if (this.closed) return Promise.reject(new Error('page adapter is closed'));+ if (this.startPromise) return this.startPromise;+ this.startPromise = new Promise<void>((resolve, reject) => {+ this.resolveRegistration = resolve;+ this.rejectRegistration = reject;+ });+ void this.connect().catch((error: unknown) => {+ // Explicit disposal can settle start while lock acquisition is pending.+ // A later lock-manager rejection belongs to that closed attempt.+ if (this.closed) return;+ this.failTerminal(+ error instanceof Error ? error : new Error(String(error))+ );+ });+ return this.startPromise;+ }++ /** Queues unchanged cache RPC until registration and engine readiness. */+ postMessage(request: CacheRequest): void {+ if (!isCacheRequest(request)) {+ const error = new Error('invalid cache request');+ this.options.onProtocolError?.(error);+ if (+ typeof (request as { id?: unknown })?.id === 'number' &&+ Number.isSafeInteger((request as { id: number }).id)+ ) {+ this.emit({+ id: (request as { id: number }).id,+ ok: false,+ error: error.message,+ });+ }+ return;+ }+ if (this.closed) {+ this.emit({ id: request.id, ok: false, error: 'page adapter is closed' });+ return;+ }+ if (!this.registered) {+ this.queuedRequests.push(request);+ void this.start().catch(() => undefined);+ return;+ }+ this.postCoordinator(+ withVersion<TabToCoordinatorEnvelope>({+ kind: 'cache-request',+ tabId: this.tabId,+ request,+ })+ );+ }++ /** Gracefully drains an owned engine, or immediately drops a standby tab. */+ dispose(options: PageAdapterDisposeOptions = {}): Promise<void> {+ const graceful = options.graceful === true;+ if (this.disposePromise) {+ if (!graceful && this.disposeMode === 'graceful' && !this.closed) {+ this.disposeMode = 'abrupt';+ this.abortDispose('pagehide interrupted graceful page disposal');+ }+ return this.disposePromise;+ }+ this.disposePromise = new Promise<void>((resolve) => {+ this.resolveDispose = resolve;+ });+ if (this.closed) {+ this.settleDispose();+ return this.disposePromise;+ }+ if (!this.sharedWorker) {+ this.disposeMode = 'abrupt';+ this.closed = true;+ this.registered = false;+ const error = new Error('page adapter was disposed during startup');+ this.rejectStartAndQueued(error);+ this.releaseLiveness();+ this.settleDispose();+ return this.disposePromise;+ }++ if (graceful && this.ownerEpoch !== undefined) {+ this.disposeMode = 'graceful';+ const ownerEpoch = this.ownerEpoch;+ if (+ !this.postCoordinator(+ withVersion<TabToCoordinatorEnvelope>({+ kind: 'graceful-departure',+ tabId: this.tabId,+ ownerEpoch,+ })+ )+ ) {+ return this.disposePromise;+ }+ this.gracefulTimeout = setTimeout(() => {+ this.gracefulTimeout = undefined;+ if (this.closed) return;+ this.terminateEngine(ownerEpoch, 'graceful drain timed out', false);+ if (this.closed) return;+ this.postCoordinator(+ withVersion<TabToCoordinatorEnvelope>({+ kind: 'disconnect-tab',+ tabId: this.tabId,+ reason: 'graceful page disposal timed out',+ })+ );+ if (!this.closed) {+ this.failTerminal(new Error('graceful engine drain timed out'));+ }+ }, this.gracefulTimeoutMs);+ } else {+ this.disposeMode = 'abrupt';+ this.abortDispose('page disposed without graceful drain');+ }+ return this.disposePromise;+ }++ private abortDispose(reason: string): void {+ this.clearGracefulTimeout();+ if (this.ownerEpoch !== undefined) {+ this.terminateEngine(this.ownerEpoch, reason, false);+ }+ if (!this.closed) {+ this.postCoordinator(+ withVersion<TabToCoordinatorEnvelope>({+ kind: 'disconnect-tab',+ tabId: this.tabId,+ reason,+ })+ );+ }+ this.finishDispose();+ }++ private async connect(): Promise<void> {+ const lockManager = this.lockManager ?? navigator.locks;+ if (+ typeof SharedWorker !== 'function' &&+ this.options.createSharedWorker === undefined+ ) {+ throw new Error('SharedWorker is unavailable');+ }+ if (+ typeof Worker !== 'function' &&+ this.options.createDedicatedWorker === undefined+ ) {+ throw new Error('DedicatedWorker is unavailable');+ }+ if (typeof MessageChannel !== 'function') {+ throw new Error('MessageChannel is unavailable');+ }+ if (!lockManager) throw new Error('Web Locks are unavailable');++ const livenessLockName = tabLivenessLockName(+ this.options.scope,+ this.tabId+ );+ const lockStartedAt = this.now();+ let acquired: (() => void) | undefined;+ let acquisitionFailed: ((error: Error) => void) | undefined;+ const acquiredPromise = new Promise<void>((resolve, reject) => {+ acquired = resolve;+ acquisitionFailed = reject;+ });+ const heldUntilReleased = new Promise<void>((resolve) => {+ this.releaseLivenessLock = resolve;+ });+ void lockManager+ .request(livenessLockName, { mode: 'exclusive' }, async (lock) => {+ if (!lock) {+ acquisitionFailed?.(new Error('tab liveness lock was not acquired'));+ return;+ }+ acquired?.();+ await heldUntilReleased;+ })+ .catch((error: unknown) => {+ acquisitionFailed?.(+ error instanceof Error ? error : new Error(String(error))+ );+ });+ try {+ await acquiredPromise;+ } catch (error) {+ this.telemetry.record({+ name: 'graphql_cache.lock_wait',+ operationCategory: 'lifecycle',+ outcome: 'error',+ errorCode: classifyCacheError(error),+ durationMs: this.now() - lockStartedAt,+ });+ throw error;+ }+ this.telemetry.record({+ name: 'graphql_cache.lock_wait',+ operationCategory: 'lifecycle',+ outcome: 'success',+ errorCode: 'none',+ durationMs: this.now() - lockStartedAt,+ });+ if (this.closed) return;++ const worker = this.createSharedWorker(this.options.scope);+ this.sharedWorker = worker;+ worker.onerror = (event) => {+ event.preventDefault();+ this.failTerminal(+ new Error(event.message || 'SharedWorker transport error')+ );+ };+ worker.port.onmessage = (event: MessageEvent<unknown>) => {+ const transferredPorts = event.ports ?? [];+ if (transferredPorts.length > 0) {+ for (const port of transferredPorts) this.closePort(port);+ this.failTerminal(+ new Error('coordinator envelope transferred an unexpected port')+ );+ return;+ }+ try {+ this.handleCoordinatorMessage(event.data);+ } catch (error) {+ this.failTerminal(+ error instanceof Error ? error : new Error(String(error))+ );+ }+ };+ worker.port.onmessageerror = () => {+ this.failTerminal(new Error('coordinator MessagePort messageerror'));+ };+ worker.port.start();+ this.postCoordinator(+ withVersion<TabToCoordinatorEnvelope>({+ kind: 'register-tab',+ scope: this.options.scope,+ tabId: this.tabId,+ livenessLockName,+ hotCapacity: this.options.hotCapacity,+ })+ );+ }++ private handleCoordinatorMessage(rawMessage: unknown): void {+ const parsed = validateCoordinatorToTabEnvelope(rawMessage);+ if (!parsed.ok) {+ this.failTerminal(new Error(parsed.error));+ return;+ }+ const message = parsed.value;+ switch (message.kind) {+ case 'registered':+ if (message.tabId !== this.tabId || this.registered) {+ this.failTerminal(+ new Error('invalid coordinator registration acknowledgement')+ );+ return;+ }+ this.registered = true;+ this.resolveRegistration?.();+ this.resolveRegistration = undefined;+ this.rejectRegistration = undefined;+ this.registerPagehide();+ for (const request of this.queuedRequests.splice(0)) {+ this.postMessage(request);+ }+ break;+ case 'become-owner':+ if (+ message.tabId !== this.tabId ||+ message.scope !== this.options.scope+ ) {+ this.failTerminal(+ new Error('coordinator elected the wrong page or scope')+ );+ return;+ }+ if (+ message.ownerEpoch <= this.highestOwnerEpochSeen ||+ this.terminatedOwnerEpochs.has(message.ownerEpoch)+ ) {+ this.failTerminal(+ new Error(+ `coordinator elected stale or duplicate owner epoch ${message.ownerEpoch}`+ )+ );+ return;+ }+ this.highestOwnerEpochSeen = message.ownerEpoch;+ this.spawnEngine(message);+ break;+ case 'cache-message':+ this.emit(message.message);+ break;+ case 'terminate-engine':+ if (message.tabId !== this.tabId) {+ this.failTerminal(new Error('coordinator terminated the wrong page'));+ return;+ }+ if (+ !this.terminateEngine(message.ownerEpoch, message.reason, false) &&+ !this.terminatedOwnerEpochs.has(message.ownerEpoch)+ ) {+ this.failTerminal(+ new Error('coordinator terminated an unknown owner epoch')+ );+ }+ break;+ case 'retire-complete':+ if (+ message.tabId !== this.tabId ||+ !this.terminateEngine(+ message.ownerEpoch,+ 'graceful engine retirement completed',+ false+ )+ ) {+ this.failTerminal(+ new Error('coordinator retired the wrong page or owner epoch')+ );+ return;+ }+ this.finishDispose();+ break;+ case 'engine-replaced':+ if (message.ownerEpoch <= this.latestEngineReplacedEpoch) return;+ this.latestEngineReplacedEpoch = message.ownerEpoch;+ this.highestOwnerEpochSeen = Math.max(+ this.highestOwnerEpochSeen,+ message.ownerEpoch+ );+ this.options.onEngineReplaced?.(message.ownerEpoch);+ break;+ case 'protocol-error': {+ const error = new Error(message.error);+ if (!this.registered) this.failTerminal(error);+ else this.options.onProtocolError?.(error);+ break;+ }+ }+ }++ private spawnEngine(+ election: Extract<CoordinatorToTabEnvelope, { kind: 'become-owner' }>+ ): void {+ if (this.engineWorker || this.ownerEpoch !== undefined) {+ this.failTerminal(+ new Error('coordinator elected a page that already owns an engine')+ );+ return;+ }+ const worker = this.createDedicatedWorker(+ this.options.scope,+ election.ownerEpoch+ );+ this.engineWorker = worker;+ this.ownerEpoch = election.ownerEpoch;+ this.options.onOwnerChanged?.(election.ownerEpoch);+ this.options.onWorkerCreated?.(worker, election.ownerEpoch);++ worker.onerror = (event) => {+ event.preventDefault();+ const reason = event.message || 'dedicated engine worker error';+ const failedDuringDrain = this.disposeMode === 'graceful';+ this.terminateEngine(election.ownerEpoch, reason, !failedDuringDrain);+ if (failedDuringDrain && !this.closed) {+ this.failTerminal(new Error(reason));+ }+ };+ worker.onmessageerror = () => {+ const reason = 'dedicated engine worker messageerror';+ const failedDuringDrain = this.disposeMode === 'graceful';+ this.terminateEngine(election.ownerEpoch, reason, !failedDuringDrain);+ if (failedDuringDrain && !this.closed) {+ this.failTerminal(new Error(reason));+ }+ };++ const directChannel = new MessageChannel();+ if (+ !this.postCoordinator(+ withVersion<TabToCoordinatorEnvelope>({+ kind: 'attach-engine-port',+ tabId: this.tabId,+ ownerEpoch: election.ownerEpoch,+ }),+ [directChannel.port1],+ [directChannel.port1]+ )+ ) {+ this.closePort(directChannel.port2);+ return;+ }+ try {+ worker.postMessage(+ withVersion<PageToEngineEnvelope>({+ kind: 'activate-engine',+ scope: election.scope,+ tabId: this.tabId,+ ownerEpoch: election.ownerEpoch,+ databaseAction: election.databaseAction,+ ownerLockName: election.ownerLockName,+ hotCapacity: election.hotCapacity,+ }),+ [directChannel.port2]+ );+ } catch (error) {+ this.closePort(directChannel.port2);+ this.failTerminal(+ error instanceof Error ? error : new Error(String(error))+ );+ }+ }++ private terminateEngine(+ ownerEpoch: number,+ reason: string,+ reportLoss: boolean+ ): boolean {+ if (!this.engineWorker || this.ownerEpoch !== ownerEpoch) return false;+ const worker = this.engineWorker;+ let cleanupError: Error | undefined;+ try {+ worker.onerror = null;+ } catch (error) {+ cleanupError = error instanceof Error ? error : new Error(String(error));+ }+ try {+ worker.onmessageerror = null;+ } catch (error) {+ cleanupError ??=+ error instanceof Error ? error : new Error(String(error));+ }+ try {+ worker.terminate();+ } catch (error) {+ cleanupError ??=+ error instanceof Error ? error : new Error(String(error));+ }+ this.terminatedOwnerEpochs.add(ownerEpoch);+ this.engineWorker = undefined;+ this.ownerEpoch = undefined;+ try {+ this.options.onOwnerChanged?.(undefined);+ this.options.onWorkerTerminated?.(ownerEpoch, reason);+ } catch (error) {+ cleanupError ??=+ error instanceof Error ? error : new Error(String(error));+ }+ if (cleanupError) {+ this.failTerminal(cleanupError);+ } else if (reportLoss && this.sharedWorker && !this.closed) {+ this.postCoordinator(+ withVersion<TabToCoordinatorEnvelope>({+ kind: 'engine-lost',+ tabId: this.tabId,+ ownerEpoch,+ reason,+ })+ );+ }+ return true;+ }++ private emit(message: WorkerMessage): void {+ this.onmessage?.({ data: message } as MessageEvent<WorkerMessage>);+ }++ private postCoordinator(+ message: TabToCoordinatorEnvelope,+ transfer: Transferable[] = [],+ untransferredPorts: MessagePort[] = []+ ): boolean {+ const port = this.sharedWorker?.port;+ if (!port) {+ for (const untransferredPort of untransferredPorts) {+ this.closePort(untransferredPort);+ }+ if (!this.closed) {+ this.failTerminal(new Error('coordinator MessagePort is unavailable'));+ }+ return false;+ }+ try {+ port.postMessage(message, transfer);+ return true;+ } catch (error) {+ for (const untransferredPort of untransferredPorts) {+ this.closePort(untransferredPort);+ }+ this.failTerminal(+ error instanceof Error ? error : new Error(String(error))+ );+ return false;+ }+ }++ private registerPagehide(): void {+ if (this.pagehideRegistered || typeof addEventListener !== 'function') {+ return;+ }+ this.pagehideRegistered = true;+ addEventListener(+ 'pagehide',+ () => {+ void this.dispose({ graceful: false });+ },+ { once: true }+ );+ }++ private failTerminal(error: Error): void {+ if (this.terminalErrorReported) return;+ this.terminalErrorReported = true;+ this.closed = true;+ this.registered = false;+ this.clearGracefulTimeout();+ if (this.ownerEpoch !== undefined) {+ this.terminateEngine(this.ownerEpoch, error.message, false);+ }+ this.closeCoordinatorPort();+ this.releaseLiveness();+ this.rejectStartAndQueued(error);+ this.settleDispose();+ try {+ this.options.onTerminalError?.(error);+ } catch {+ // Terminal cleanup is complete; observers cannot reopen the transport.+ }+ }++ private finishDispose(): void {+ this.closed = true;+ this.registered = false;+ this.clearGracefulTimeout();+ this.closeCoordinatorPort();+ this.releaseLiveness();+ this.rejectStartAndQueued(new Error('page adapter was disposed'));+ this.settleDispose();+ }++ private rejectStartAndQueued(error: Error): void {+ this.rejectRegistration?.(error);+ this.rejectRegistration = undefined;+ this.resolveRegistration = undefined;+ for (const request of this.queuedRequests.splice(0)) {+ try {+ this.emit({ id: request.id, ok: false, error: error.message });+ } catch {+ // One consumer callback cannot prevent settlement of later requests.+ }+ }+ }++ private closeCoordinatorPort(): void {+ const worker = this.sharedWorker;+ this.sharedWorker = undefined;+ if (!worker) return;+ try {+ worker.onerror = null;+ } catch {+ // Continue closing the port even if a test double rejects detachment.+ }+ try {+ worker.port.onmessage = null;+ worker.port.onmessageerror = null;+ } catch {+ // Continue closing even if a test double rejects handler detachment.+ }+ this.closePort(worker.port);+ }++ private closePort(port: Pick<MessagePort, 'close'>): void {+ try {+ port.close();+ } catch {+ // Closing is best-effort after ownership has already been abandoned.+ }+ }++ private clearGracefulTimeout(): void {+ if (this.gracefulTimeout === undefined) return;+ clearTimeout(this.gracefulTimeout);+ this.gracefulTimeout = undefined;+ }++ private settleDispose(): void {+ this.resolveDispose?.();+ this.resolveDispose = undefined;+ }++ private releaseLiveness(): void {+ const release = this.releaseLivenessLock;+ this.releaseLivenessLock = undefined;+ try {+ release?.();+ } catch {+ // Promise resolvers do not throw, but cleanup must remain exception-safe.+ }+ }+}++/** Creates a lazy, import-safe page coordinator endpoint. */+export function createCacheCoordinatorPageAdapter(+ options: CacheCoordinatorPageAdapterOptions+): CacheCoordinatorPageAdapter {+ return new CacheCoordinatorPageAdapter(options);+}diff --git a/apps/web/src/lib/graphql-cache/worker/coordinator-protocol.test.ts b/apps/web/src/lib/graphql-cache/worker/coordinator-protocol.test.tsnew file mode 100644index 0000000000..4996822461--- /dev/null+++ b/apps/web/src/lib/graphql-cache/worker/coordinator-protocol.test.ts@@ -0,0 +1,277 @@+import { describe, expect, it } from 'vitest';+import {+ CACHE_COORDINATOR_PROTOCOL_VERSION,+ databaseOwnerLockName,+ isCachePush,+ isCacheRequest,+ isCacheResponse,+ validateCoordinatorToEngineEnvelope,+ validateCoordinatorToTabEnvelope,+ validateEngineToCoordinatorEnvelope,+ validatePageToEngineEnvelope,+ validateTabToCoordinatorEnvelope,+} from './coordinator-protocol';++const version = {+ coordinatorVersion: CACHE_COORDINATOR_PROTOCOL_VERSION,+} as const;++describe('coordinator runtime protocol', () => {+ it('validates unchanged cache RPC and rejects unknown fields or kinds', () => {+ expect(isCacheRequest({ id: 0, kind: 'clear' })).toBe(true);+ expect(isCacheRequest({ id: 1, kind: 'read', query: '{ x }' })).toBe(true);+ expect(isCacheRequest({ id: 1, kind: 'clear', surprise: true })).toBe(+ false+ );+ expect(isCacheRequest({ id: 1, kind: 'future-kind' })).toBe(false);+ expect(isCacheResponse({ id: 3, ok: true, result: undefined })).toBe(true);+ expect(isCacheResponse({ id: 3, ok: false, error: 'failed' })).toBe(true);+ expect(+ isCacheResponse({+ id: 3,+ ok: false,+ error: 'failed',+ errorCode: 'owner-epoch-lost',+ })+ ).toBe(true);+ expect(+ isCacheResponse({+ id: 3,+ ok: false,+ error: 'failed',+ errorCode: 'future-code',+ })+ ).toBe(false);+ expect(isCacheResponse({ id: 3, ok: false, error: 4 })).toBe(false);+ expect(isCachePush({ kind: 'cache-changed' })).toBe(true);+ expect(+ isCachePush({+ kind: 'mutation-settled',+ settlement: { transactionId: '1', status: 'committed' },+ })+ ).toBe(true);+ });++ it.each([+ {+ ...version,+ kind: 'register-tab',+ scope: 'scope',+ tabId: 'tab',+ livenessLockName: 'graphql-cache-tab:scope:tab',+ },+ {+ ...version,+ kind: 'cache-request',+ tabId: 'tab',+ request: { id: 1, kind: 'clear' },+ },+ {+ ...version,+ kind: 'attach-engine-port',+ tabId: 'tab',+ ownerEpoch: 1,+ },+ {+ ...version,+ kind: 'graceful-departure',+ tabId: 'tab',+ ownerEpoch: 1,+ },+ {+ ...version,+ kind: 'engine-lost',+ tabId: 'tab',+ ownerEpoch: 1,+ reason: 'failed',+ },+ {+ ...version,+ kind: 'disconnect-tab',+ tabId: 'tab',+ reason: 'closed',+ },+ ])('accepts tab envelope $kind', (message) => {+ expect(validateTabToCoordinatorEnvelope(message)).toEqual({+ ok: true,+ value: message,+ });+ });++ it.each([+ { ...version, kind: 'registered', tabId: 'tab' },+ {+ ...version,+ kind: 'become-owner',+ scope: 'scope',+ tabId: 'tab',+ ownerEpoch: 1,+ databaseAction: 'open-existing',+ ownerLockName: 'owner-lock',+ },+ {+ ...version,+ kind: 'cache-message',+ message: { id: 1, ok: true, result: null },+ },+ {+ ...version,+ kind: 'terminate-engine',+ tabId: 'tab',+ ownerEpoch: 1,+ reason: 'failed',+ },+ {+ ...version,+ kind: 'retire-complete',+ tabId: 'tab',+ ownerEpoch: 1,+ },+ { ...version, kind: 'engine-replaced', ownerEpoch: 2 },+ { ...version, kind: 'protocol-error', error: 'bad envelope' },+ ])('accepts coordinator-to-tab envelope $kind', (message) => {+ expect(validateCoordinatorToTabEnvelope(message).ok).toBe(true);+ });++ it('validates activation and both direct-port directions', () => {+ expect(+ validatePageToEngineEnvelope({+ ...version,+ kind: 'activate-engine',+ scope: 'scope',+ tabId: 'tab',+ ownerEpoch: 1,+ databaseAction: 'wipe-before-open',+ ownerLockName: 'owner-lock',+ }).ok+ ).toBe(true);+ expect(+ validateCoordinatorToEngineEnvelope({+ ...version,+ kind: 'engine-request',+ ownerEpoch: 1,+ routeId: 7,+ request: { id: 7, kind: 'clear' },+ }).ok+ ).toBe(true);+ expect(+ validateCoordinatorToEngineEnvelope({+ ...version,+ kind: 'engine-request',+ ownerEpoch: 1,+ routeId: 7,+ request: { id: 6, kind: 'clear' },+ }).ok+ ).toBe(false);+ expect(+ validateEngineToCoordinatorEnvelope({+ ...version,+ kind: 'engine-ready',+ tabId: 'tab',+ ownerEpoch: 1,+ ownerLockName: 'owner-lock',+ ownerLockHeld: true,+ databaseActionProof: 'wiped-before-open',+ openOutcome: 'reset-storage-uncertain',+ }).ok+ ).toBe(true);+ expect(+ validateEngineToCoordinatorEnvelope({+ ...version,+ kind: 'engine-ready',+ tabId: 'tab',+ ownerEpoch: 1,+ ownerLockName: 'owner-lock',+ ownerLockHeld: false,+ databaseActionProof: 'wiped-before-open',+ openOutcome: 'reset-storage-uncertain',+ }).ok+ ).toBe(false);+ expect(+ validateEngineToCoordinatorEnvelope({+ ...version,+ kind: 'engine-fatal',+ tabId: 'tab',+ ownerEpoch: 1,+ reason: 'reset',+ fatalCode: 'storage-reset-required',+ }).ok+ ).toBe(true);+ expect(+ validateEngineToCoordinatorEnvelope({+ ...version,+ kind: 'activation-failed',+ tabId: 'tab',+ ownerEpoch: 1,+ reason: 'open failed',+ failureCode: 'recovery-open-failed',+ }).ok+ ).toBe(true);+ expect(+ validateEngineToCoordinatorEnvelope({+ ...version,+ kind: 'engine-response',+ ownerEpoch: 1,+ routeId: 7,+ response: {+ id: 7,+ ok: false,+ error: 'forged topology loss',+ errorCode: 'owner-epoch-lost',+ },+ }).ok+ ).toBe(false);+ });++ it('rejects missing versions, non-positive epochs, extra fields, and malformed nested payloads', () => {+ expect(+ validateTabToCoordinatorEnvelope({+ kind: 'register-tab',+ scope: 'scope',+ tabId: 'tab',+ livenessLockName: 'lock',+ }).ok+ ).toBe(false);+ expect(+ validateCoordinatorToTabEnvelope({+ ...version,+ kind: 'engine-replaced',+ ownerEpoch: 0,+ }).ok+ ).toBe(false);+ expect(+ validateCoordinatorToTabEnvelope({+ coordinatorVersion: CACHE_COORDINATOR_PROTOCOL_VERSION + 1,+ kind: 'engine-replaced',+ ownerEpoch: 1,+ }).ok+ ).toBe(false);+ expect(+ validateEngineToCoordinatorEnvelope({+ ...version,+ kind: 'heartbeat-ack',+ ownerEpoch: 1,+ heartbeatId: 1,+ extra: true,+ }).ok+ ).toBe(false);+ expect(+ validateCoordinatorToEngineEnvelope({+ ...version,+ kind: 'engine-request',+ ownerEpoch: 1,+ routeId: 1,+ request: { id: 1, kind: 'unknown' },+ }).ok+ ).toBe(false);+ });++ it('derives the exact UTF-8 canonical turso-opfs lock name', () => {+ expect(databaseOwnerLockName('scope')).toBe(+ 'macro:turso-opfs:v1:19:graphql-cache:scope'+ );+ expect(databaseOwnerLockName('é')).toBe(+ 'macro:turso-opfs:v1:16:graphql-cache:é'+ );+ });+});diff --git a/apps/web/src/lib/graphql-cache/worker/coordinator-protocol.ts b/apps/web/src/lib/graphql-cache/worker/coordinator-protocol.tsnew file mode 100644index 0000000000..d1114fc7ea--- /dev/null+++ b/apps/web/src/lib/graphql-cache/worker/coordinator-protocol.ts@@ -0,0 +1,897 @@+import {+ type CachePush,+ type CacheRequest,+ type CacheResponse,+ isCachePush,+ isCacheResponse,+ isWorkerMessage,+ type WorkerMessage,+} from '../protocol';++export { isCachePush, isCacheResponse, isWorkerMessage };++/** Version of the topology envelope around the unchanged cache RPC. */+export const CACHE_COORDINATOR_PROTOCOL_VERSION = 1 as const;++export type OwnerEpoch = number;+export type RouteId = number;+export type DatabaseAction = 'open-existing' | 'wipe-before-open';+export type DatabaseActionProof = 'opened-existing' | 'wiped-before-open';+export type EngineOpenOutcome =+ | 'opened-existing'+ | 'opened-new'+ | 'reset-incompatible'+ | 'reset-corrupt'+ | 'reset-storage-uncertain';+export type EngineFatalCode = 'storage-reset-required' | 'runtime-failure';+export type ActivationFailureCode =+ | 'initialization-failed'+ | 'recovery-open-failed';++export type TabToCoordinatorEnvelope =+ | {+ coordinatorVersion: 1;+ kind: 'register-tab';+ scope: string;+ tabId: string;+ livenessLockName: string;+ hotCapacity?: number;+ }+ | {+ coordinatorVersion: 1;+ kind: 'cache-request';+ tabId: string;+ request: CacheRequest;+ }+ | {+ coordinatorVersion: 1;+ kind: 'attach-engine-port';+ tabId: string;+ ownerEpoch: OwnerEpoch;+ }+ | {+ coordinatorVersion: 1;+ kind: 'graceful-departure';+ tabId: string;+ ownerEpoch: OwnerEpoch;+ }+ | {+ coordinatorVersion: 1;+ kind: 'engine-lost';+ tabId: string;+ ownerEpoch: OwnerEpoch;+ reason: string;+ }+ | {+ coordinatorVersion: 1;+ kind: 'disconnect-tab';+ tabId: string;+ reason: string;+ };++export type CoordinatorToTabEnvelope =+ | {+ coordinatorVersion: 1;+ kind: 'registered';+ tabId: string;+ }+ | {+ coordinatorVersion: 1;+ kind: 'become-owner';+ scope: string;+ tabId: string;+ ownerEpoch: OwnerEpoch;+ databaseAction: DatabaseAction;+ ownerLockName: string;+ hotCapacity?: number;+ }+ | {+ coordinatorVersion: 1;+ kind: 'cache-message';+ message: WorkerMessage;+ }+ | {+ coordinatorVersion: 1;+ kind: 'terminate-engine';+ tabId: string;+ ownerEpoch: OwnerEpoch;+ reason: string;+ }+ | {+ coordinatorVersion: 1;+ kind: 'retire-complete';+ tabId: string;+ ownerEpoch: OwnerEpoch;+ }+ | {+ coordinatorVersion: 1;+ kind: 'engine-replaced';+ ownerEpoch: OwnerEpoch;+ }+ | {+ coordinatorVersion: 1;+ kind: 'protocol-error';+ error: string;+ };++export type PageToEngineEnvelope = {+ coordinatorVersion: 1;+ kind: 'activate-engine';+ scope: string;+ tabId: string;+ ownerEpoch: OwnerEpoch;+ databaseAction: DatabaseAction;+ ownerLockName: string;+ hotCapacity?: number;+};++export type CoordinatorToEngineEnvelope =+ | {+ coordinatorVersion: 1;+ kind: 'engine-request';+ ownerEpoch: OwnerEpoch;+ routeId: RouteId;+ request: CacheRequest;+ }+ | {+ coordinatorVersion: 1;+ kind: 'drain-engine';+ ownerEpoch: OwnerEpoch;+ }+ | {+ coordinatorVersion: 1;+ kind: 'heartbeat';+ ownerEpoch: OwnerEpoch;+ heartbeatId: number;+ };++export type EngineToCoordinatorEnvelope =+ | {+ coordinatorVersion: 1;+ kind: 'engine-ready';+ tabId: string;+ ownerEpoch: OwnerEpoch;+ ownerLockName: string;+ ownerLockHeld: true;+ databaseActionProof: DatabaseActionProof;+ openOutcome: EngineOpenOutcome;+ }+ | {+ coordinatorVersion: 1;+ kind: 'engine-response';+ ownerEpoch: OwnerEpoch;+ routeId: RouteId;+ response: CacheResponse;+ }+ | {+ coordinatorVersion: 1;+ kind: 'engine-push';+ ownerEpoch: OwnerEpoch;+ push: CachePush;+ }+ | {+ coordinatorVersion: 1;+ kind: 'engine-drained';+ tabId: string;+ ownerEpoch: OwnerEpoch;+ }+ | {+ coordinatorVersion: 1;+ kind: 'engine-fatal';+ tabId: string;+ ownerEpoch: OwnerEpoch;+ reason: string;+ fatalCode: EngineFatalCode;+ }+ | {+ coordinatorVersion: 1;+ kind: 'activation-failed';+ tabId: string;+ ownerEpoch: OwnerEpoch;+ reason: string;+ failureCode: ActivationFailureCode;+ }+ | {+ coordinatorVersion: 1;+ kind: 'heartbeat-ack';+ ownerEpoch: OwnerEpoch;+ heartbeatId: number;+ };++export type EnvelopeValidation<T> =+ | { ok: true; value: T }+ | { ok: false; error: string };++type UnknownRecord = Record<string, unknown>;++const fail = <T>(error: string): EnvelopeValidation<T> => ({+ ok: false,+ error,+});++const pass = <T>(value: T): EnvelopeValidation<T> => ({ ok: true, value });++const isRecord = (value: unknown): value is UnknownRecord =>+ typeof value === 'object' && value !== null && !Array.isArray(value);++const isString = (value: unknown): value is string => typeof value === 'string';++const isNonEmptyString = (value: unknown): value is string =>+ isString(value) && value.length > 0;++const isOptionalString = (value: unknown): value is string | undefined =>+ value === undefined || isString(value);++const isSafeNonNegativeInteger = (value: unknown): value is number =>+ Number.isSafeInteger(value) && (value as number) >= 0;++const isPositiveInteger = (value: unknown): value is number =>+ Number.isSafeInteger(value) && (value as number) > 0;++const isOptionalPositiveInteger = (+ value: unknown+): value is number | undefined =>+ value === undefined || isPositiveInteger(value);++const isStringArray = (value: unknown): value is string[] =>+ Array.isArray(value) && value.every(isString);++const hasOwn = (record: UnknownRecord, key: string): boolean =>+ Object.hasOwn(record, key);++const hasOnlyKeys = (record: UnknownRecord, keys: readonly string[]): boolean =>+ Object.keys(record).every((key) => keys.includes(key));++const hasVersion = (record: UnknownRecord): boolean =>+ record.coordinatorVersion === CACHE_COORDINATOR_PROTOCOL_VERSION;++const isDatabaseAction = (value: unknown): value is DatabaseAction =>+ value === 'open-existing' || value === 'wipe-before-open';++const isDatabaseActionProof = (value: unknown): value is DatabaseActionProof =>+ value === 'opened-existing' || value === 'wiped-before-open';++const isEngineOpenOutcome = (value: unknown): value is EngineOpenOutcome =>+ typeof value === 'string' &&+ [+ 'opened-existing',+ 'opened-new',+ 'reset-incompatible',+ 'reset-corrupt',+ 'reset-storage-uncertain',+ ].includes(value);++const isEngineFatalCode = (value: unknown): value is EngineFatalCode =>+ value === 'storage-reset-required' || value === 'runtime-failure';++const isActivationFailureCode = (+ value: unknown+): value is ActivationFailureCode =>+ value === 'initialization-failed' || value === 'recovery-open-failed';++const isOptionalRecord = (+ value: unknown+): value is Record<string, unknown> | undefined =>+ value === undefined || isRecord(value);++const isPath = (value: unknown): boolean =>+ Array.isArray(value) &&+ value.every(+ (segment) =>+ isRecord(segment) &&+ hasOnlyKeys(segment, ['field']) &&+ isString(segment.field)+ );++const isEntityResolvers = (value: unknown): boolean =>+ value === undefined ||+ (Array.isArray(value) &&+ value.every(+ (resolver) =>+ isRecord(resolver) &&+ isString(resolver.parentType) &&+ isString(resolver.fieldName) &&+ isString(resolver.targetType) &&+ isStringArray(resolver.argumentPath)+ ));++const commonRequest = (record: UnknownRecord): boolean =>+ isSafeNonNegativeInteger(record.id) && isNonEmptyString(record.kind);++/** Strictly validates a cache RPC request nested in a coordinator envelope. */+export function isCacheRequest(value: unknown): value is CacheRequest {+ if (!isRecord(value) || !commonRequest(value)) return false;+ switch (value.kind) {+ case 'init':+ return (+ hasOnlyKeys(value, ['id', 'kind', 'scope', 'hotCapacity']) &&+ isNonEmptyString(value.scope) &&+ isOptionalPositiveInteger(value.hotCapacity)+ );+ case 'read':+ return (+ hasOnlyKeys(value, [+ 'id',+ 'kind',+ 'opId',+ 'query',+ 'operationName',+ 'variables',+ 'priority',+ 'entityResolvers',+ ]) &&+ isOptionalString(value.opId) &&+ isString(value.query) &&+ isOptionalString(value.operationName) &&+ isOptionalRecord(value.variables) &&+ (value.priority === undefined || value.priority === 'user-visible') &&+ isEntityResolvers(value.entityResolvers)+ );+ case 'write':+ return (+ hasOnlyKeys(value, [+ 'id',+ 'kind',+ 'originOpId',+ 'query',+ 'operationName',+ 'variables',+ 'data',+ 'identity',+ ]) &&+ isOptionalString(value.originOpId) &&+ isString(value.query) &&+ isOptionalString(value.operationName) &&+ isOptionalRecord(value.variables) &&+ hasOwn(value, 'data') &&+ isOptionalString(value.identity)+ );+ case 'enqueue-optimistic-mutation':+ return (+ hasOnlyKeys(value, [+ 'id',+ 'kind',+ 'originOpId',+ 'query',+ 'operationName',+ 'variables',+ 'data',+ 'linkPatches',+ 'revalidations',+ 'createdAtMs',+ 'owner',+ 'nowMs',+ 'leaseExpiresAtMs',+ ]) &&+ isOptionalString(value.originOpId) &&+ isString(value.query) &&+ isOptionalString(value.operationName) &&+ isOptionalRecord(value.variables) &&+ hasOwn(value, 'data') &&+ (value.linkPatches === undefined || Array.isArray(value.linkPatches)) &&+ (value.revalidations === undefined ||+ Array.isArray(value.revalidations)) &&+ isSafeNonNegativeInteger(value.createdAtMs) &&+ isString(value.owner) &&+ isSafeNonNegativeInteger(value.nowMs) &&+ isSafeNonNegativeInteger(value.leaseExpiresAtMs)+ );+ case 'claim-next-mutation':+ return (+ hasOnlyKeys(value, [+ 'id',+ 'kind',+ 'owner',+ 'nowMs',+ 'leaseExpiresAtMs',+ ]) &&+ isString(value.owner) &&+ isSafeNonNegativeInteger(value.nowMs) &&+ isSafeNonNegativeInteger(value.leaseExpiresAtMs)+ );+ case 'defer-optimistic-write':+ return (+ hasOnlyKeys(value, [+ 'id',+ 'kind',+ 'transactionId',+ 'leaseOwner',+ 'leaseGeneration',+ 'nextAttemptAtMs',+ 'error',+ ]) &&+ isString(value.transactionId) &&+ isString(value.leaseOwner) &&+ isString(value.leaseGeneration) &&+ isSafeNonNegativeInteger(value.nextAttemptAtMs) &&+ isString(value.error)+ );+ case 'commit-optimistic-write':+ return (+ hasOnlyKeys(value, [+ 'id',+ 'kind',+ 'transactionId',+ 'leaseOwner',+ 'leaseGeneration',+ 'query',+ 'operationName',+ 'variables',+ 'data',+ ]) &&+ isString(value.transactionId) &&+ isString(value.leaseOwner) &&+ isString(value.leaseGeneration) &&+ isString(value.query) &&+ isOptionalString(value.operationName) &&+ isOptionalRecord(value.variables) &&+ hasOwn(value, 'data')+ );+ case 'rollback-optimistic-write':+ return (+ hasOnlyKeys(value, [+ 'id',+ 'kind',+ 'transactionId',+ 'leaseOwner',+ 'leaseGeneration',+ 'error',+ ]) &&+ isString(value.transactionId) &&+ isString(value.leaseOwner) &&+ isString(value.leaseGeneration) &&+ isString(value.error)+ );+ case 'read-records':+ return (+ hasOnlyKeys(value, [+ 'id',+ 'kind',+ 'document',+ 'fragmentName',+ 'cursor',+ 'limit',+ ]) &&+ isString(value.document) &&+ isString(value.fragmentName) &&+ isOptionalString(value.cursor) &&+ isPositiveInteger(value.limit)+ );+ case 'inspect-query':+ return (+ hasOnlyKeys(value, [+ 'id',+ 'kind',+ 'query',+ 'operationName',+ 'path',+ 'variableFilters',+ ]) &&+ isString(value.query) &&+ isOptionalString(value.operationName) &&+ isPath(value.path) &&+ (value.variableFilters === undefined ||+ (Array.isArray(value.variableFilters) &&+ value.variableFilters.every(isRecord)))+ );+ case 'inspect-query-variants':+ return (+ hasOnlyKeys(value, ['id', 'kind', 'query', 'operationName', 'path']) &&+ isString(value.query) &&+ isOptionalString(value.operationName) &&+ isPath(value.path)+ );+ case 'teardown':+ return hasOnlyKeys(value, ['id', 'kind', 'opId']) && isString(value.opId);+ case 'invalidate':+ case 'delete-records':+ return (+ hasOnlyKeys(value, ['id', 'kind', 'keys']) && isStringArray(value.keys)+ );+ case 'clear':+ return hasOnlyKeys(value, ['id', 'kind']);+ default:+ return false;+ }+}++/** Validates an untrusted page-to-coordinator message. */+export function validateTabToCoordinatorEnvelope(+ value: unknown+): EnvelopeValidation<TabToCoordinatorEnvelope> {+ if (!isRecord(value) || !hasVersion(value) || !isString(value.kind)) {+ return fail('invalid coordinator envelope header');+ }+ const base =+ value.coordinatorVersion === CACHE_COORDINATOR_PROTOCOL_VERSION &&+ isNonEmptyString(value.tabId);+ if (!base) return fail('invalid coordinator tab identity');++ switch (value.kind) {+ case 'register-tab':+ if (+ hasOnlyKeys(value, [+ 'coordinatorVersion',+ 'kind',+ 'scope',+ 'tabId',+ 'livenessLockName',+ 'hotCapacity',+ ]) &&+ isNonEmptyString(value.scope) &&+ isNonEmptyString(value.livenessLockName) &&+ isOptionalPositiveInteger(value.hotCapacity)+ ) {+ return pass(value as TabToCoordinatorEnvelope);+ }+ break;+ case 'cache-request':+ if (+ hasOnlyKeys(value, [+ 'coordinatorVersion',+ 'kind',+ 'tabId',+ 'request',+ ]) &&+ isCacheRequest(value.request)+ ) {+ return pass(value as TabToCoordinatorEnvelope);+ }+ break;+ case 'attach-engine-port':+ case 'graceful-departure':+ if (+ hasOnlyKeys(value, [+ 'coordinatorVersion',+ 'kind',+ 'tabId',+ 'ownerEpoch',+ ]) &&+ isPositiveInteger(value.ownerEpoch)+ ) {+ return pass(value as TabToCoordinatorEnvelope);+ }+ break;+ case 'engine-lost':+ if (+ hasOnlyKeys(value, [+ 'coordinatorVersion',+ 'kind',+ 'tabId',+ 'ownerEpoch',+ 'reason',+ ]) &&+ isPositiveInteger(value.ownerEpoch) &&+ isNonEmptyString(value.reason)+ ) {+ return pass(value as TabToCoordinatorEnvelope);+ }+ break;+ case 'disconnect-tab':+ if (+ hasOnlyKeys(value, ['coordinatorVersion', 'kind', 'tabId', 'reason']) &&+ isNonEmptyString(value.reason)+ ) {+ return pass(value as TabToCoordinatorEnvelope);+ }+ break;+ }+ return fail(`invalid ${value.kind} coordinator envelope`);+}++/** Validates an untrusted coordinator-to-page message. */+export function validateCoordinatorToTabEnvelope(+ value: unknown+): EnvelopeValidation<CoordinatorToTabEnvelope> {+ if (!isRecord(value) || !hasVersion(value) || !isString(value.kind)) {+ return fail('invalid coordinator envelope header');+ }+ switch (value.kind) {+ case 'registered':+ if (+ hasOnlyKeys(value, ['coordinatorVersion', 'kind', 'tabId']) &&+ isNonEmptyString(value.tabId)+ ) {+ return pass(value as CoordinatorToTabEnvelope);+ }+ break;+ case 'become-owner':+ if (+ hasOnlyKeys(value, [+ 'coordinatorVersion',+ 'kind',+ 'scope',+ 'tabId',+ 'ownerEpoch',+ 'databaseAction',+ 'ownerLockName',+ 'hotCapacity',+ ]) &&+ isNonEmptyString(value.scope) &&+ isNonEmptyString(value.tabId) &&+ isPositiveInteger(value.ownerEpoch) &&+ isDatabaseAction(value.databaseAction) &&+ isNonEmptyString(value.ownerLockName) &&+ isOptionalPositiveInteger(value.hotCapacity)+ ) {+ return pass(value as CoordinatorToTabEnvelope);+ }+ break;+ case 'cache-message':+ if (+ hasOnlyKeys(value, ['coordinatorVersion', 'kind', 'message']) &&+ isWorkerMessage(value.message)+ ) {+ return pass(value as CoordinatorToTabEnvelope);+ }+ break;+ case 'terminate-engine':+ if (+ hasOnlyKeys(value, [+ 'coordinatorVersion',+ 'kind',+ 'tabId',+ 'ownerEpoch',+ 'reason',+ ]) &&+ isNonEmptyString(value.tabId) &&+ isPositiveInteger(value.ownerEpoch) &&+ isNonEmptyString(value.reason)+ ) {+ return pass(value as CoordinatorToTabEnvelope);+ }+ break;+ case 'retire-complete':+ if (+ hasOnlyKeys(value, [+ 'coordinatorVersion',+ 'kind',+ 'tabId',+ 'ownerEpoch',+ ]) &&+ isNonEmptyString(value.tabId) &&+ isPositiveInteger(value.ownerEpoch)+ ) {+ return pass(value as CoordinatorToTabEnvelope);+ }+ break;+ case 'engine-replaced':+ if (+ hasOnlyKeys(value, ['coordinatorVersion', 'kind', 'ownerEpoch']) &&+ isPositiveInteger(value.ownerEpoch)+ ) {+ return pass(value as CoordinatorToTabEnvelope);+ }+ break;+ case 'protocol-error':+ if (+ hasOnlyKeys(value, ['coordinatorVersion', 'kind', 'error']) &&+ isNonEmptyString(value.error)+ ) {+ return pass(value as CoordinatorToTabEnvelope);+ }+ break;+ }+ return fail(`invalid ${value.kind} coordinator envelope`);+}++/** Validates the page's one-time DedicatedWorker activation message. */+export function validatePageToEngineEnvelope(+ value: unknown+): EnvelopeValidation<PageToEngineEnvelope> {+ if (+ isRecord(value) &&+ hasVersion(value) &&+ value.kind === 'activate-engine' &&+ hasOnlyKeys(value, [+ 'coordinatorVersion',+ 'kind',+ 'scope',+ 'tabId',+ 'ownerEpoch',+ 'databaseAction',+ 'ownerLockName',+ 'hotCapacity',+ ]) &&+ isNonEmptyString(value.scope) &&+ isNonEmptyString(value.tabId) &&+ isPositiveInteger(value.ownerEpoch) &&+ isDatabaseAction(value.databaseAction) &&+ isNonEmptyString(value.ownerLockName) &&+ isOptionalPositiveInteger(value.hotCapacity)+ ) {+ return pass(value as PageToEngineEnvelope);+ }+ return fail('invalid activate-engine envelope');+}++/** Validates an untrusted coordinator-to-engine direct-port message. */+export function validateCoordinatorToEngineEnvelope(+ value: unknown+): EnvelopeValidation<CoordinatorToEngineEnvelope> {+ if (!isRecord(value) || !hasVersion(value) || !isString(value.kind)) {+ return fail('invalid coordinator envelope header');+ }+ switch (value.kind) {+ case 'engine-request':+ if (+ hasOnlyKeys(value, [+ 'coordinatorVersion',+ 'kind',+ 'ownerEpoch',+ 'routeId',+ 'request',+ ]) &&+ isPositiveInteger(value.ownerEpoch) &&+ isPositiveInteger(value.routeId) &&+ isCacheRequest(value.request) &&+ value.request.id === value.routeId+ ) {+ return pass(value as CoordinatorToEngineEnvelope);+ }+ break;+ case 'drain-engine':+ if (+ hasOnlyKeys(value, ['coordinatorVersion', 'kind', 'ownerEpoch']) &&+ isPositiveInteger(value.ownerEpoch)+ ) {+ return pass(value as CoordinatorToEngineEnvelope);+ }+ break;+ case 'heartbeat':+ if (+ hasOnlyKeys(value, [+ 'coordinatorVersion',+ 'kind',+ 'ownerEpoch',+ 'heartbeatId',+ ]) &&+ isPositiveInteger(value.ownerEpoch) &&+ isPositiveInteger(value.heartbeatId)+ ) {+ return pass(value as CoordinatorToEngineEnvelope);+ }+ break;+ }+ return fail(`invalid ${value.kind} coordinator envelope`);+}++/** Validates an untrusted engine-to-coordinator direct-port message. */+export function validateEngineToCoordinatorEnvelope(+ value: unknown+): EnvelopeValidation<EngineToCoordinatorEnvelope> {+ if (!isRecord(value) || !hasVersion(value) || !isString(value.kind)) {+ return fail('invalid coordinator envelope header');+ }+ switch (value.kind) {+ case 'engine-ready':+ if (+ hasOnlyKeys(value, [+ 'coordinatorVersion',+ 'kind',+ 'tabId',+ 'ownerEpoch',+ 'ownerLockName',+ 'ownerLockHeld',+ 'databaseActionProof',+ 'openOutcome',+ ]) &&+ isNonEmptyString(value.tabId) &&+ isPositiveInteger(value.ownerEpoch) &&+ isNonEmptyString(value.ownerLockName) &&+ value.ownerLockHeld === true &&+ isDatabaseActionProof(value.databaseActionProof) &&+ isEngineOpenOutcome(value.openOutcome)+ ) {+ return pass(value as EngineToCoordinatorEnvelope);+ }+ break;+ case 'engine-response':+ if (+ hasOnlyKeys(value, [+ 'coordinatorVersion',+ 'kind',+ 'ownerEpoch',+ 'routeId',+ 'response',+ ]) &&+ isPositiveInteger(value.ownerEpoch) &&+ isPositiveInteger(value.routeId) &&+ isCacheResponse(value.response) &&+ (value.response.ok || value.response.errorCode === undefined) &&+ value.response.id === value.routeId+ ) {+ return pass(value as EngineToCoordinatorEnvelope);+ }+ break;+ case 'engine-push':+ if (+ hasOnlyKeys(value, [+ 'coordinatorVersion',+ 'kind',+ 'ownerEpoch',+ 'push',+ ]) &&+ isPositiveInteger(value.ownerEpoch) &&+ isCachePush(value.push)+ ) {+ return pass(value as EngineToCoordinatorEnvelope);+ }+ break;+ case 'engine-drained':+ if (+ hasOnlyKeys(value, [+ 'coordinatorVersion',+ 'kind',+ 'tabId',+ 'ownerEpoch',+ ]) &&+ isNonEmptyString(value.tabId) &&+ isPositiveInteger(value.ownerEpoch)+ ) {+ return pass(value as EngineToCoordinatorEnvelope);+ }+ break;+ case 'engine-fatal':+ if (+ hasOnlyKeys(value, [+ 'coordinatorVersion',+ 'kind',+ 'tabId',+ 'ownerEpoch',+ 'reason',+ 'fatalCode',+ ]) &&+ isNonEmptyString(value.tabId) &&+ isPositiveInteger(value.ownerEpoch) &&+ isNonEmptyString(value.reason) &&+ isEngineFatalCode(value.fatalCode)+ ) {+ return pass(value as EngineToCoordinatorEnvelope);+ }+ break;+ case 'activation-failed':+ if (+ hasOnlyKeys(value, [+ 'coordinatorVersion',+ 'kind',+ 'tabId',+ 'ownerEpoch',+ 'reason',+ 'failureCode',+ ]) &&+ isNonEmptyString(value.tabId) &&+ isPositiveInteger(value.ownerEpoch) &&+ isNonEmptyString(value.reason) &&+ isActivationFailureCode(value.failureCode)+ ) {+ return pass(value as EngineToCoordinatorEnvelope);+ }+ break;+ case 'heartbeat-ack':+ if (+ hasOnlyKeys(value, [+ 'coordinatorVersion',+ 'kind',+ 'ownerEpoch',+ 'heartbeatId',+ ]) &&+ isPositiveInteger(value.ownerEpoch) &&+ isPositiveInteger(value.heartbeatId)+ ) {+ return pass(value as EngineToCoordinatorEnvelope);+ }+ break;+ }+ return fail(`invalid ${value.kind} coordinator envelope`);+}++export const tabLivenessLockName = (scope: string, tabId: string): string =>+ `graphql-cache-tab:${scope}:${tabId}`;++/** Mirrors turso-opfs's canonical lock derivation without exposing a new lock. */+export function databaseOwnerLockName(scope: string): string {+ const databaseIdentity = `graphql-cache:${scope}`;+ const byteLength = new TextEncoder().encode(databaseIdentity).byteLength;+ return `macro:turso-opfs:v1:${byteLength}:${databaseIdentity}`;+}diff --git a/apps/web/src/lib/graphql-cache/worker/coordinator-router.test.ts b/apps/web/src/lib/graphql-cache/worker/coordinator-router.test.tsnew file mode 100644index 0000000000..bb7bd6cf54--- /dev/null+++ b/apps/web/src/lib/graphql-cache/worker/coordinator-router.test.ts@@ -0,0 +1,779 @@+import { afterEach, describe, expect, it, vi } from 'vitest';+import {+ CACHE_COORDINATOR_PROTOCOL_VERSION,+ databaseOwnerLockName,+} from './coordinator-protocol';+import {+ type CoordinatorMessagePort,+ CoordinatorRouter,+} from './coordinator-router';++class FakePort {+ readonly messages: unknown[] = [];+ readonly events: string[] = [];+ closed = false;+ started = false;+ onmessage: ((event: MessageEvent<unknown>) => void) | null = null;+ onmessageerror: (() => void) | null = null;++ postMessage(message: unknown): void {+ this.messages.push(message);+ this.events.push(+ `post:${String((message as { kind?: unknown })?.kind ?? 'unknown')}`+ );+ }++ close(): void {+ this.closed = true;+ this.events.push('close');+ }++ start(): void {+ this.started = true;+ }++ receive(message: unknown): void {+ this.onmessage?.({ data: message, ports: [] } as unknown as MessageEvent);+ }+}++const version = {+ coordinatorVersion: CACHE_COORDINATOR_PROTOCOL_VERSION,+} as const;++const register = async (+ router: CoordinatorRouter,+ port: FakePort,+ tabId: string+): Promise<void> => {+ await router.handleTabMessage(port as CoordinatorMessagePort, {+ ...version,+ kind: 'register-tab',+ scope: 'scope',+ tabId,+ livenessLockName: `graphql-cache-tab:scope:${tabId}`,+ });+};++const attach = async (+ router: CoordinatorRouter,+ tabPort: FakePort,+ tabId: string,+ ownerEpoch: number,+ enginePort: FakePort+): Promise<void> => {+ await router.handleTabMessage(+ tabPort as CoordinatorMessagePort,+ {+ ...version,+ kind: 'attach-engine-port',+ tabId,+ ownerEpoch,+ },+ [enginePort as unknown as MessagePort]+ );+};++const ready = (+ enginePort: FakePort,+ tabId: string,+ ownerEpoch: number,+ proof: 'opened-existing' | 'wiped-before-open'+): void => {+ enginePort.receive({+ ...version,+ kind: 'engine-ready',+ tabId,+ ownerEpoch,+ ownerLockName: databaseOwnerLockName('scope'),+ ownerLockHeld: true,+ databaseActionProof: proof,+ openOutcome:+ proof === 'wiped-before-open'+ ? 'reset-storage-uncertain'+ : 'opened-existing',+ });+};++const messagesOfKind = <T extends string>(port: FakePort, kind: T) =>+ port.messages.filter(+ (message): message is Record<string, unknown> & { kind: T } =>+ typeof message === 'object' &&+ message !== null &&+ (message as { kind?: unknown }).kind === kind+ );++describe('CoordinatorRouter', () => {+ afterEach(() => {+ vi.useRealTimers();+ });++ it('reports recovery reset success only after ready proof and failure on activation failure', async () => {+ const observations: Array<Record<string, unknown>> = [];+ const setupRecovery = async () => {+ const router = new CoordinatorRouter({+ verifyTabLockHeld: async () => true,+ watchTabLock: () => () => {},+ telemetry: {+ record: (observation) => observations.push(observation),+ flush: vi.fn(),+ },+ });+ const tabA = new FakePort();+ const tabB = new FakePort();+ const engineA = new FakePort();+ await register(router, tabA, 'tab-a');+ await register(router, tabB, 'tab-b');+ await attach(router, tabA, 'tab-a', 1, engineA);+ ready(engineA, 'tab-a', 1, 'opened-existing');+ await router.handleTabMessage(tabA as CoordinatorMessagePort, {+ ...version,+ kind: 'engine-lost',+ tabId: 'tab-a',+ ownerEpoch: 1,+ reason: 'injected abrupt loss',+ });+ expect(router.snapshot()?.state).toMatchObject({+ kind: 'activating',+ ownerEpoch: 2,+ databaseAction: 'wipe-before-open',+ });+ expect(+ observations.filter(+ (observation) => observation.name === 'graphql_cache.reset_wipe'+ )+ ).toEqual([]);+ return { router, tabB };+ };++ const successful = await setupRecovery();+ const successfulEngine = new FakePort();+ await attach(+ successful.router,+ successful.tabB,+ 'tab-b',+ 2,+ successfulEngine+ );+ ready(successfulEngine, 'tab-b', 2, 'wiped-before-open');+ expect(+ observations.filter(+ (observation) => observation.name === 'graphql_cache.reset_wipe'+ )+ ).toEqual([+ expect.objectContaining({+ outcome: 'success',+ resetReason: 'abrupt-owner-loss',+ }),+ ]);++ observations.length = 0;+ const failed = await setupRecovery();+ const failedEngine = new FakePort();+ await attach(failed.router, failed.tabB, 'tab-b', 2, failedEngine);+ failedEngine.receive({+ ...version,+ kind: 'activation-failed',+ tabId: 'tab-b',+ ownerEpoch: 2,+ reason: 'OPFS recovery open failed',+ failureCode: 'recovery-open-failed',+ });+ expect(+ observations.filter(+ (observation) => observation.name === 'graphql_cache.reset_wipe'+ )+ ).toEqual([+ expect.objectContaining({+ outcome: 'error',+ resetReason: 'abrupt-owner-loss',+ }),+ ]);+ });++ it('registers only after independent liveness-lock contention succeeds', async () => {+ let releaseVerification: ((held: boolean) => void) | undefined;+ const verification = new Promise<boolean>((resolve) => {+ releaseVerification = resolve;+ });+ const router = new CoordinatorRouter({+ verifyTabLockHeld: () => verification,+ watchTabLock: () => () => {},+ });+ const port = new FakePort();++ const registration = register(router, port, 'tab-a');+ expect(port.messages).toEqual([]);+ expect(router.snapshot()).toBeUndefined();+ releaseVerification?.(true);+ await registration;++ expect(messagesOfKind(port, 'registered')).toHaveLength(1);+ expect(messagesOfKind(port, 'become-owner')).toContainEqual(+ expect.objectContaining({+ tabId: 'tab-a',+ ownerEpoch: 1,+ databaseAction: 'open-existing',+ })+ );+ });++ it('cancels an exact pending registration on MessagePort messageerror', async () => {+ let finishVerification!: (held: boolean) => void;+ const verification = new Promise<boolean>((resolve) => {+ finishVerification = resolve;+ });+ const router = new CoordinatorRouter({+ verifyTabLockHeld: () => verification,+ watchTabLock: () => () => {},+ });+ const stalePort = new FakePort();+ router.connect(stalePort as CoordinatorMessagePort);+ stalePort.receive({+ ...version,+ kind: 'register-tab',+ scope: 'scope',+ tabId: 'stale-tab',+ livenessLockName: 'graphql-cache-tab:scope:stale-tab',+ });++ stalePort.onmessageerror?.();+ finishVerification(true);+ await vi.waitFor(() => expect(stalePort.closed).toBe(true));+ await Promise.resolve();++ expect(messagesOfKind(stalePort, 'registered')).toHaveLength(0);+ expect(messagesOfKind(stalePort, 'become-owner')).toHaveLength(0);+ expect(router.snapshot()).toBeUndefined();++ const livePort = new FakePort();+ await register(router, livePort, 'live-tab');+ expect(messagesOfKind(livePort, 'become-owner')).toContainEqual(+ expect.objectContaining({ tabId: 'live-tab', ownerEpoch: 1 })+ );+ expect(router.snapshot()?.tabIds).toEqual(['live-tab']);+ });++ it('rejects registration when the page does not already hold its lock', async () => {+ const router = new CoordinatorRouter({+ verifyTabLockHeld: async () => false,+ watchTabLock: () => () => {},+ });+ const port = new FakePort();++ await register(router, port, 'tab-a');++ expect(port.closed).toBe(true);+ expect(messagesOfKind(port, 'protocol-error')).toContainEqual(+ expect.objectContaining({+ error: 'tab registration requires an already-held liveness lock',+ })+ );+ expect(router.snapshot()).toBeUndefined();+ });++ it('routes colliding tab ids through unique engine ids, restores responses, and fans pushes', async () => {+ const router = new CoordinatorRouter({+ verifyTabLockHeld: async () => true,+ watchTabLock: () => () => {},+ });+ const tabA = new FakePort();+ const tabB = new FakePort();+ const tabC = new FakePort();+ await register(router, tabA, 'tab-a');+ await register(router, tabB, 'tab-b');+ await register(router, tabC, 'tab-c');+ const engine = new FakePort();+ await attach(router, tabA, 'tab-a', 1, engine);+ ready(engine, 'tab-a', 1, 'opened-existing');++ await router.handleTabMessage(tabB as CoordinatorMessagePort, {+ ...version,+ kind: 'cache-request',+ tabId: 'tab-b',+ request: { id: 4, kind: 'clear' },+ });+ await router.handleTabMessage(tabC as CoordinatorMessagePort, {+ ...version,+ kind: 'cache-request',+ tabId: 'tab-c',+ request: { id: 4, kind: 'clear' },+ });+ const routes = messagesOfKind(engine, 'engine-request');+ expect(routes).toHaveLength(2);+ const first = routes[0]!;+ expect(first.routeId).not.toBe(routes[1]?.routeId);+ expect((first.request as { id: number }).id).toBe(first.routeId);++ const second = routes[1] as unknown as { routeId: number };+ engine.receive({+ ...version,+ kind: 'engine-response',+ ownerEpoch: 1,+ routeId: second.routeId,+ response: { id: second.routeId, ok: true, result: 'tab-c' },+ });+ expect(messagesOfKind(tabC, 'cache-message')).toContainEqual(+ expect.objectContaining({+ message: { id: 4, ok: true, result: 'tab-c' },+ })+ );++ engine.receive({+ ...version,+ kind: 'engine-push',+ ownerEpoch: 1,+ push: { kind: 'cache-changed' },+ });+ for (const tab of [tabA, tabB, tabC]) {+ expect(messagesOfKind(tab, 'cache-message')).toContainEqual(+ expect.objectContaining({ message: { kind: 'cache-changed' } })+ );+ }+ });++ it('orders drain after earlier routes and elects open-existing only after drained', async () => {+ const router = new CoordinatorRouter({+ verifyTabLockHeld: async () => true,+ watchTabLock: () => () => {},+ });+ const tabA = new FakePort();+ const tabB = new FakePort();+ await register(router, tabA, 'tab-a');+ await register(router, tabB, 'tab-b');+ const engine = new FakePort();+ await attach(router, tabA, 'tab-a', 1, engine);+ ready(engine, 'tab-a', 1, 'opened-existing');+ await router.handleTabMessage(tabB as CoordinatorMessagePort, {+ ...version,+ kind: 'cache-request',+ tabId: 'tab-b',+ request: { id: 1, kind: 'clear' },+ });+ await router.handleTabMessage(tabA as CoordinatorMessagePort, {+ ...version,+ kind: 'graceful-departure',+ tabId: 'tab-a',+ ownerEpoch: 1,+ });++ expect(+ engine.messages+ .slice(-2)+ .map((message) => (message as { kind: string }).kind)+ ).toEqual(['engine-request', 'drain-engine']);+ expect(messagesOfKind(tabB, 'become-owner')).toHaveLength(0);+ const route = messagesOfKind(engine, 'engine-request')[0] as unknown as {+ routeId: number;+ };+ engine.receive({+ ...version,+ kind: 'engine-response',+ ownerEpoch: 1,+ routeId: route.routeId,+ response: { id: route.routeId, ok: true, result: null },+ });+ engine.receive({+ ...version,+ kind: 'engine-drained',+ tabId: 'tab-a',+ ownerEpoch: 1,+ });++ expect(messagesOfKind(tabB, 'become-owner')).toContainEqual(+ expect.objectContaining({+ ownerEpoch: 2,+ databaseAction: 'open-existing',+ })+ );+ expect(tabA.closed).toBe(true);+ });++ it('counts an unknown response with the current direct-route tuple as stale', async () => {+ const router = new CoordinatorRouter({+ verifyTabLockHeld: async () => true,+ watchTabLock: () => () => {},+ });+ const tabA = new FakePort();+ await register(router, tabA, 'tab-a');+ const engine = new FakePort();+ await attach(router, tabA, 'tab-a', 1, engine);+ ready(engine, 'tab-a', 1, 'opened-existing');++ engine.receive({+ ...version,+ kind: 'engine-response',+ ownerEpoch: 1,+ routeId: 999,+ response: { id: 999, ok: true, result: 'stale' },+ });++ expect(router.snapshot()?.staleMessageDrops).toBe(1);+ expect(router.snapshot()?.state).toMatchObject({+ kind: 'active',+ ownerEpoch: 1,+ });+ expect(messagesOfKind(tabA, 'terminate-engine')).toHaveLength(0);+ });++ it('uses activation and heartbeat watchdogs to terminate and wipe', async () => {+ vi.useFakeTimers();+ const router = new CoordinatorRouter({+ activationTimeoutMs: 10,+ heartbeatIntervalMs: 5,+ heartbeatTimeoutMs: 7,+ verifyTabLockHeld: async () => true,+ watchTabLock: () => () => {},+ });+ const tabA = new FakePort();+ const tabB = new FakePort();+ await register(router, tabA, 'tab-a');+ await register(router, tabB, 'tab-b');++ await vi.advanceTimersByTimeAsync(11);+ expect(messagesOfKind(tabA, 'terminate-engine')).toContainEqual(+ expect.objectContaining({+ ownerEpoch: 1,+ reason: 'engine activation watchdog timed out',+ })+ );+ expect(messagesOfKind(tabB, 'become-owner')).toContainEqual(+ expect.objectContaining({+ ownerEpoch: 2,+ databaseAction: 'wipe-before-open',+ })+ );++ const engine = new FakePort();+ await attach(router, tabB, 'tab-b', 2, engine);+ ready(engine, 'tab-b', 2, 'wiped-before-open');+ await vi.advanceTimersByTimeAsync(6);+ expect(messagesOfKind(engine, 'heartbeat')).toHaveLength(1);+ await vi.advanceTimersByTimeAsync(8);+ expect(messagesOfKind(tabB, 'terminate-engine')).toContainEqual(+ expect.objectContaining({+ ownerEpoch: 2,+ reason: 'engine heartbeat watchdog timed out',+ })+ );+ expect(router.snapshot()?.state.kind).toBe('activating');+ expect(router.snapshot()?.ownerEpoch).toBe(3);+ });++ it('accepts heartbeat acknowledgements and rearms the watchdog', async () => {+ vi.useFakeTimers();+ const router = new CoordinatorRouter({+ heartbeatIntervalMs: 5,+ heartbeatTimeoutMs: 7,+ verifyTabLockHeld: async () => true,+ watchTabLock: () => () => {},+ });+ const tab = new FakePort();+ await register(router, tab, 'tab-a');+ const engine = new FakePort();+ await attach(router, tab, 'tab-a', 1, engine);+ ready(engine, 'tab-a', 1, 'opened-existing');++ await vi.advanceTimersByTimeAsync(5);+ const ping = messagesOfKind(engine, 'heartbeat')[0] as unknown as {+ heartbeatId: number;+ };+ engine.receive({+ ...version,+ kind: 'heartbeat-ack',+ ownerEpoch: 1,+ heartbeatId: ping.heartbeatId,+ });+ await vi.advanceTimersByTimeAsync(6);++ expect(messagesOfKind(tab, 'terminate-engine')).toHaveLength(0);+ expect(messagesOfKind(engine, 'heartbeat')).toHaveLength(2);+ });++ it('uses liveness watcher release as the correctness path', async () => {+ const releases = new Map<string, () => void>();+ const cancels: string[] = [];+ const router = new CoordinatorRouter({+ verifyTabLockHeld: async () => true,+ watchTabLock: (lockName, onReleased) => {+ releases.set(lockName, onReleased);+ return () => cancels.push(lockName);+ },+ });+ const tabA = new FakePort();+ const tabB = new FakePort();+ const tabC = new FakePort();+ await register(router, tabA, 'tab-a');+ await register(router, tabB, 'tab-b');+ await register(router, tabC, 'tab-c');+ const engine = new FakePort();+ await attach(router, tabA, 'tab-a', 1, engine);+ ready(engine, 'tab-a', 1, 'opened-existing');++ releases.get('graphql-cache-tab:scope:tab-b')?.();+ expect(router.snapshot()?.state).toMatchObject({+ kind: 'active',+ tabId: 'tab-a',+ });+ releases.get('graphql-cache-tab:scope:tab-a')?.();+ await Promise.resolve();++ expect(messagesOfKind(tabA, 'terminate-engine')).toContainEqual(+ expect.objectContaining({+ ownerEpoch: 1,+ reason: 'tab liveness lock was released',+ })+ );+ expect(tabA.events.indexOf('post:terminate-engine')).toBeLessThan(+ tabA.events.indexOf('close')+ );+ expect(router.snapshot()?.state).toMatchObject({+ kind: 'activating',+ ownerEpoch: 2,+ databaseAction: 'wipe-before-open',+ });+ expect(cancels).toEqual(+ expect.arrayContaining([+ 'graphql-cache-tab:scope:tab-a',+ 'graphql-cache-tab:scope:tab-b',+ ])+ );+ });++ it('removes a gracefully retiring owner before liveness-loss re-election', async () => {+ const releases = new Map<string, () => void>();+ const router = new CoordinatorRouter({+ verifyTabLockHeld: async () => true,+ watchTabLock: (lockName, onReleased) => {+ releases.set(lockName, onReleased);+ return () => undefined;+ },+ });+ const tabA = new FakePort();+ const tabB = new FakePort();+ await register(router, tabA, 'tab-a');+ await register(router, tabB, 'tab-b');+ const engine = new FakePort();+ await attach(router, tabA, 'tab-a', 1, engine);+ ready(engine, 'tab-a', 1, 'opened-existing');++ await router.handleTabMessage(tabA as CoordinatorMessagePort, {+ ...version,+ kind: 'graceful-departure',+ tabId: 'tab-a',+ ownerEpoch: 1,+ });+ releases.get('graphql-cache-tab:scope:tab-a')?.();+ await Promise.resolve();++ expect(router.snapshot()?.tabIds).toEqual(['tab-b']);+ expect(router.snapshot()?.state).toMatchObject({+ kind: 'activating',+ tabId: 'tab-b',+ ownerEpoch: 2,+ databaseAction: 'wipe-before-open',+ });+ });++ it('terminates a live owner before dropping a MessagePort on messageerror', async () => {+ const router = new CoordinatorRouter({+ verifyTabLockHeld: async () => true,+ watchTabLock: () => () => {},+ });+ const tabA = new FakePort();+ const tabB = new FakePort();+ router.connect(tabA as CoordinatorMessagePort);+ tabA.receive({+ ...version,+ kind: 'register-tab',+ scope: 'scope',+ tabId: 'tab-a',+ livenessLockName: 'graphql-cache-tab:scope:tab-a',+ });+ await vi.waitFor(() =>+ expect(messagesOfKind(tabA, 'registered')).toHaveLength(1)+ );+ await register(router, tabB, 'tab-b');+ const engine = new FakePort();+ await attach(router, tabA, 'tab-a', 1, engine);+ ready(engine, 'tab-a', 1, 'opened-existing');++ tabA.onmessageerror?.();+ await Promise.resolve();++ expect(messagesOfKind(tabA, 'terminate-engine')).toContainEqual(+ expect.objectContaining({+ ownerEpoch: 1,+ reason: 'tab MessagePort messageerror',+ })+ );+ expect(tabA.events.indexOf('post:terminate-engine')).toBeLessThan(+ tabA.events.indexOf('close')+ );+ expect(router.snapshot()?.state).toMatchObject({+ kind: 'activating',+ ownerEpoch: 2,+ databaseAction: 'wipe-before-open',+ });+ });++ it('fails the current owner on an engine envelope route-tuple mismatch', async () => {+ const router = new CoordinatorRouter({+ verifyTabLockHeld: async () => true,+ watchTabLock: () => () => {},+ });+ const tabA = new FakePort();+ const tabB = new FakePort();+ await register(router, tabA, 'tab-a');+ await register(router, tabB, 'tab-b');+ const engine = new FakePort();+ await attach(router, tabA, 'tab-a', 1, engine);+ ready(engine, 'tab-a', 1, 'opened-existing');++ engine.receive({+ ...version,+ kind: 'engine-drained',+ tabId: 'different-tab',+ ownerEpoch: 1,+ });+ await Promise.resolve();++ expect(messagesOfKind(tabA, 'terminate-engine')).toContainEqual(+ expect.objectContaining({+ ownerEpoch: 1,+ reason: 'engine envelope owner tuple does not match its direct route',+ })+ );+ expect(router.snapshot()?.state).toMatchObject({+ kind: 'activating',+ ownerEpoch: 2,+ databaseAction: 'wipe-before-open',+ });+ });++ it('fences an engine-originated topology error code instead of forwarding it', async () => {+ const router = new CoordinatorRouter({+ verifyTabLockHeld: async () => true,+ watchTabLock: () => () => {},+ });+ const tabA = new FakePort();+ const tabB = new FakePort();+ await register(router, tabA, 'tab-a');+ await register(router, tabB, 'tab-b');+ const engine = new FakePort();+ await attach(router, tabA, 'tab-a', 1, engine);+ ready(engine, 'tab-a', 1, 'opened-existing');+ await router.handleTabMessage(tabB as CoordinatorMessagePort, {+ ...version,+ kind: 'cache-request',+ tabId: 'tab-b',+ request: { id: 8, kind: 'clear' },+ });+ const route = messagesOfKind(engine, 'engine-request')[0] as unknown as {+ routeId: number;+ };++ // Enter through the router's direct engine port. Its strict envelope+ // validation must fence the owner; this is not merely a runtime unit path.+ engine.receive({+ ...version,+ kind: 'engine-response',+ ownerEpoch: 1,+ routeId: route.routeId,+ response: {+ id: route.routeId,+ ok: false,+ error: 'forged topology loss',+ errorCode: 'owner-epoch-lost',+ },+ });+ await Promise.resolve();++ expect(messagesOfKind(tabB, 'cache-message')).toContainEqual(+ expect.objectContaining({+ message: expect.objectContaining({+ id: 8,+ ok: false,+ error: expect.stringContaining('invalid engine envelope'),+ errorCode: 'owner-epoch-lost',+ }),+ })+ );+ expect(messagesOfKind(tabB, 'cache-message')).not.toContainEqual(+ expect.objectContaining({+ message: expect.objectContaining({ error: 'forged topology loss' }),+ })+ );+ expect(messagesOfKind(tabA, 'terminate-engine')).toContainEqual(+ expect.objectContaining({+ ownerEpoch: 1,+ reason: expect.stringContaining('invalid engine envelope'),+ })+ );+ expect(router.snapshot()?.state).toMatchObject({+ kind: 'activating',+ ownerEpoch: 2,+ databaseAction: 'wipe-before-open',+ });+ });++ it('fails instead of clearing watchdogs for unexpected current engine-drained', async () => {+ const router = new CoordinatorRouter({+ verifyTabLockHeld: async () => true,+ watchTabLock: () => () => {},+ });+ const tabA = new FakePort();+ const tabB = new FakePort();+ await register(router, tabA, 'tab-a');+ await register(router, tabB, 'tab-b');+ const engine = new FakePort();+ await attach(router, tabA, 'tab-a', 1, engine);+ ready(engine, 'tab-a', 1, 'opened-existing');++ engine.receive({+ ...version,+ kind: 'engine-drained',+ tabId: 'tab-a',+ ownerEpoch: 1,+ });+ await Promise.resolve();++ expect(messagesOfKind(tabA, 'terminate-engine')).toContainEqual(+ expect.objectContaining({+ reason: 'unexpected engine-drained from current direct route',+ })+ );+ expect(router.snapshot()?.state).toMatchObject({+ kind: 'activating',+ ownerEpoch: 2,+ databaseAction: 'wipe-before-open',+ });+ });++ it('treats malformed current-engine messages as uncertain owner loss', async () => {+ const router = new CoordinatorRouter({+ verifyTabLockHeld: async () => true,+ watchTabLock: () => () => {},+ });+ const tabA = new FakePort();+ const tabB = new FakePort();+ await register(router, tabA, 'tab-a');+ await register(router, tabB, 'tab-b');+ const engine = new FakePort();+ await attach(router, tabA, 'tab-a', 1, engine);++ engine.receive({ kind: 'engine-ready', ownerEpoch: 1 });+ await Promise.resolve();++ expect(messagesOfKind(tabA, 'terminate-engine')).toContainEqual(+ expect.objectContaining({+ reason: expect.stringContaining('invalid engine envelope'),+ })+ );+ expect(router.snapshot()?.state).toMatchObject({+ kind: 'activating',+ ownerEpoch: 2,+ databaseAction: 'wipe-before-open',+ });+ });+});diff --git a/apps/web/src/lib/graphql-cache/worker/coordinator-router.ts b/apps/web/src/lib/graphql-cache/worker/coordinator-router.tsnew file mode 100644index 0000000000..f0c6e83c65--- /dev/null+++ b/apps/web/src/lib/graphql-cache/worker/coordinator-router.ts@@ -0,0 +1,1130 @@+import type { CacheResponse } from '../protocol';+import {+ type CacheResetReason,+ type CacheTelemetryRecorderLike,+ classifyCacheError,+ isolateCacheTelemetry,+ NOOP_CACHE_TELEMETRY,+ operationCategoryForRequest,+} from '../telemetry';+import { workerCacheTelemetry } from '../telemetry-relay';+import {+ type CoordinatorAction,+ CoordinatorCore,+ type CoordinatorSnapshot,+} from './coordinator-core';+import {+ type ActivationFailureCode,+ CACHE_COORDINATOR_PROTOCOL_VERSION,+ type CoordinatorToEngineEnvelope,+ type CoordinatorToTabEnvelope,+ databaseOwnerLockName,+ type EngineFatalCode,+ type EngineOpenOutcome,+ type TabToCoordinatorEnvelope,+ tabLivenessLockName,+ validateEngineToCoordinatorEnvelope,+ validateTabToCoordinatorEnvelope,+} from './coordinator-protocol';++export type CoordinatorMessagePort = Pick<+ MessagePort,+ 'postMessage' | 'close' | 'start' | 'onmessage' | 'onmessageerror'+>;++export type CancelLivenessWatch = () => void;++export interface CoordinatorRouterOptions {+ activationTimeoutMs?: number;+ heartbeatIntervalMs?: number;+ heartbeatTimeoutMs?: number;+ verifyTabLockHeld?: (lockName: string) => Promise<boolean>;+ watchTabLock?: (+ lockName: string,+ onReleased: () => void+ ) => CancelLivenessWatch;+ setTimeout?: typeof globalThis.setTimeout;+ clearTimeout?: typeof globalThis.clearTimeout;+ queueMicrotask?: typeof globalThis.queueMicrotask;+ telemetry?: CacheTelemetryRecorderLike;+}++type TabConnection = {+ port: CoordinatorMessagePort;+ cancelLivenessWatch: CancelLivenessWatch;+};++type PendingRegistration = { cancelled: boolean };++type EngineRoute = {+ tabId: string;+ ownerEpoch: number;+ port: CoordinatorMessagePort;+};++const DEFAULT_ACTIVATION_TIMEOUT_MS = 20_000;+const DEFAULT_HEARTBEAT_INTERVAL_MS = 2_000;+const DEFAULT_HEARTBEAT_TIMEOUT_MS = 5_000;++const resetReasonForOpenOutcome = (+ outcome: EngineOpenOutcome+): CacheResetReason => {+ switch (outcome) {+ case 'reset-incompatible':+ return 'namespace-mismatch';+ case 'reset-corrupt':+ return 'integrity-failure';+ case 'reset-storage-uncertain':+ return 'storage-reset-required';+ case 'opened-existing':+ case 'opened-new':+ return 'unknown';+ }+};++type WithoutVersion<T> = T extends unknown+ ? Omit<T, 'coordinatorVersion'>+ : never;++const envelope = <T extends { coordinatorVersion: 1 }>(+ value: WithoutVersion<T>+): T =>+ ({+ coordinatorVersion: CACHE_COORDINATOR_PROTOCOL_VERSION,+ ...value,+ }) as unknown as T;++/** Independently checks that registration cannot acquire the page-held lock. */+export async function verifyTabLivenessLockHeld(+ lockName: string+): Promise<boolean> {+ return await navigator.locks.request(+ lockName,+ { mode: 'exclusive', ifAvailable: true },+ (lock) => lock === null+ );+}++/** Waits for the page's liveness lock to be released or abandoned. */+export function watchTabLivenessLock(+ lockName: string,+ onReleased: () => void+): CancelLivenessWatch {+ const abortController = new AbortController();+ void navigator.locks+ .request(+ lockName,+ { mode: 'exclusive', signal: abortController.signal },+ (lock) => {+ if (lock) onReleased();+ }+ )+ .catch((error: unknown) => {+ if (+ !abortController.signal.aborted &&+ (!(error instanceof DOMException) || error.name !== 'AbortError')+ ) {+ console.error('[graphql-cache] tab liveness watch failed');+ }+ });+ return () => abortController.abort();+}++/** SharedWorker adapter around the deterministic coordinator state machine. */+export class CoordinatorRouter {+ private coreValue: CoordinatorCore | undefined;+ private hotCapacity: number | undefined;+ private readonly tabs = new Map<string, TabConnection>();+ private readonly portTabs = new Map<CoordinatorMessagePort, string>();+ private readonly pendingRegistrations = new Map<+ CoordinatorMessagePort,+ PendingRegistration+ >();+ private engineRoute: EngineRoute | undefined;+ private activationTimer: ReturnType<typeof setTimeout> | undefined;+ private heartbeatIntervalTimer: ReturnType<typeof setTimeout> | undefined;+ private heartbeatTimeoutTimer: ReturnType<typeof setTimeout> | undefined;+ private nextHeartbeatId = 1;+ private pendingHeartbeat:+ | { ownerEpoch: number; heartbeatId: number }+ | undefined;++ private readonly activationTimeoutMs: number;+ private readonly heartbeatIntervalMs: number;+ private readonly heartbeatTimeoutMs: number;+ private readonly verifyTabLockHeld: (lockName: string) => Promise<boolean>;+ private readonly watchTabLock: (+ lockName: string,+ onReleased: () => void+ ) => CancelLivenessWatch;+ private readonly setTimeoutFn: typeof globalThis.setTimeout;+ private readonly clearTimeoutFn: typeof globalThis.clearTimeout;+ private readonly queueMicrotaskFn: typeof globalThis.queueMicrotask;+ private readonly telemetry: CacheTelemetryRecorderLike;+ private readonly routeStarted = new Map<+ number,+ {+ startedAt: number;+ ownerEpoch: number;+ category: ReturnType<typeof operationCategoryForRequest>;+ }+ >();+ private readonly activationStarted = new Map<number, number>();+ private readonly pendingRecoveryResetEpochs = new Map<+ number,+ CacheResetReason+ >();+ private nextRecoveryResetReason: CacheResetReason | undefined;+ private readonly resetRequiredEpochs = new Set<number>();+ private readonly now = (): number =>+ globalThis.performance?.now() ?? Date.now();++ constructor(options: CoordinatorRouterOptions = {}) {+ this.activationTimeoutMs =+ options.activationTimeoutMs ?? DEFAULT_ACTIVATION_TIMEOUT_MS;+ this.heartbeatIntervalMs =+ options.heartbeatIntervalMs ?? DEFAULT_HEARTBEAT_INTERVAL_MS;+ this.heartbeatTimeoutMs =+ options.heartbeatTimeoutMs ?? DEFAULT_HEARTBEAT_TIMEOUT_MS;+ this.verifyTabLockHeld =+ options.verifyTabLockHeld ?? verifyTabLivenessLockHeld;+ this.watchTabLock = options.watchTabLock ?? watchTabLivenessLock;+ this.setTimeoutFn =+ options.setTimeout ?? globalThis.setTimeout.bind(globalThis);+ this.clearTimeoutFn =+ options.clearTimeout ?? globalThis.clearTimeout.bind(globalThis);+ this.queueMicrotaskFn =+ options.queueMicrotask ?? globalThis.queueMicrotask.bind(globalThis);+ this.telemetry = isolateCacheTelemetry(+ options.telemetry ??+ (typeof window === 'undefined'+ ? workerCacheTelemetry()+ : NOOP_CACHE_TELEMETRY)+ );+ }++ get core(): CoordinatorCore | undefined {+ return this.coreValue;+ }++ snapshot(): CoordinatorSnapshot | undefined {+ return this.coreValue?.snapshot();+ }++ connect(port: CoordinatorMessagePort): void {+ port.onmessage = (event: MessageEvent<unknown>) => {+ void this.handleTabMessage(port, event.data, event.ports);+ };+ port.onmessageerror = () => {+ const tabId = this.portTabs.get(port);+ if (tabId) {+ this.loseTab(tabId, 'tab MessagePort messageerror');+ return;+ }+ const registration = this.pendingRegistrations.get(port);+ if (registration) {+ registration.cancelled = true;+ if (this.pendingRegistrations.get(port) === registration) {+ this.pendingRegistrations.delete(port);+ }+ }+ port.close();+ };+ port.start();+ }++ async handleTabMessage(+ port: CoordinatorMessagePort,+ rawMessage: unknown,+ transferredPorts: readonly MessagePort[] = []+ ): Promise<void> {+ const parsed = validateTabToCoordinatorEnvelope(rawMessage);+ if (!parsed.ok) {+ this.postProtocolError(port, parsed.error);+ return;+ }+ const message = parsed.value;+ const expectedPortCount = message.kind === 'attach-engine-port' ? 1 : 0;+ if (transferredPorts.length !== expectedPortCount) {+ for (const transferredPort of transferredPorts) transferredPort.close();+ const tabId = this.portTabs.get(port);+ if (message.kind === 'attach-engine-port' && tabId) {+ this.failOwner(+ tabId,+ message.ownerEpoch,+ 'engine attachment transferred the wrong number of ports'+ );+ } else {+ this.postProtocolError(+ port,+ 'coordinator envelope transferred unexpected ports'+ );+ }+ return;+ }+ if (message.kind === 'register-tab') {+ await this.register(port, message);+ return;+ }++ const tabId = this.portTabs.get(port);+ if (!tabId) {+ this.postProtocolError(port, 'message arrived before tab registration');+ return;+ }+ if (message.tabId !== tabId) {+ this.postProtocolError(+ port,+ 'message tab id does not match the registered port'+ );+ return;+ }+ const core = this.coreValue;+ if (!core) {+ this.postProtocolError(port, 'coordinator is not initialized');+ return;+ }++ switch (message.kind) {+ case 'cache-request':+ this.applyActions(core.request(tabId, message.request));+ break;+ case 'attach-engine-port':+ this.attachEnginePort(tabId, message.ownerEpoch, transferredPorts[0]);+ break;+ case 'graceful-departure':+ this.applyActions(+ core.beginGracefulDeparture(tabId, message.ownerEpoch)+ );+ break;+ case 'engine-lost':+ this.failOwner(tabId, message.ownerEpoch, message.reason);+ break;+ case 'disconnect-tab':+ this.loseTab(tabId, message.reason);+ break;+ }+ }++ private async register(+ port: CoordinatorMessagePort,+ message: Extract<TabToCoordinatorEnvelope, { kind: 'register-tab' }>+ ): Promise<void> {+ if (this.portTabs.has(port) || this.pendingRegistrations.has(port)) {+ this.postProtocolError(port, 'MessagePort already registered');+ return;+ }+ if (this.tabs.has(message.tabId)) {+ this.postProtocolError(port, 'tab id is already registered');+ port.close();+ return;+ }+ const expectedLockName = tabLivenessLockName(message.scope, message.tabId);+ if (message.livenessLockName !== expectedLockName) {+ this.postProtocolError(+ port,+ 'tab registered without the expected liveness-lock name'+ );+ port.close();+ return;+ }+ if (this.coreValue && this.coreValue.scope !== message.scope) {+ this.postProtocolError(port, 'coordinator scope mismatch');+ port.close();+ return;+ }+ if (this.coreValue && this.hotCapacity !== message.hotCapacity) {+ this.postProtocolError(port, 'coordinator hot-capacity mismatch');+ port.close();+ return;+ }++ const registration: PendingRegistration = { cancelled: false };+ this.pendingRegistrations.set(port, registration);+ let lockHeld = false;+ try {+ lockHeld = await this.verifyTabLockHeld(message.livenessLockName);+ } catch {+ if (+ registration.cancelled ||+ this.pendingRegistrations.get(port) !== registration+ ) {+ return;+ }+ this.pendingRegistrations.delete(port);+ this.postProtocolError(port, 'tab liveness-lock verification failed');+ port.close();+ return;+ }+ if (+ registration.cancelled ||+ this.pendingRegistrations.get(port) !== registration+ ) {+ return;+ }+ this.pendingRegistrations.delete(port);+ if (!lockHeld) {+ this.postProtocolError(+ port,+ 'tab registration requires an already-held liveness lock'+ );+ port.close();+ return;+ }+ // Recheck after the asynchronous lock probe so concurrent registrations+ // cannot race a duplicate tab or mismatched first scope into the router.+ if (this.portTabs.has(port) || this.tabs.has(message.tabId)) {+ this.postProtocolError(port, 'tab registration raced another port');+ port.close();+ return;+ }+ if (+ this.coreValue &&+ (this.coreValue.scope !== message.scope ||+ this.hotCapacity !== message.hotCapacity)+ ) {+ this.postProtocolError(port, 'coordinator registration raced a mismatch');+ port.close();+ return;+ }++ if (!this.coreValue) {+ this.coreValue = new CoordinatorCore(message.scope);+ this.hotCapacity = message.hotCapacity;+ }+ let connection: TabConnection;+ const cancelLivenessWatch = this.watchTabLock(+ message.livenessLockName,+ () => {+ const current = this.tabs.get(message.tabId);+ if (current && current === connection) {+ this.loseTab(message.tabId, 'tab liveness lock was released');+ }+ }+ );+ connection = { port, cancelLivenessWatch };+ this.tabs.set(message.tabId, connection);+ this.portTabs.set(port, message.tabId);+ this.postToTab(+ message.tabId,+ envelope<CoordinatorToTabEnvelope>({+ kind: 'registered',+ tabId: message.tabId,+ })+ );+ this.applyActions(this.coreValue.registerTab(message.tabId));+ }++ private attachEnginePort(+ tabId: string,+ ownerEpoch: number,+ transferredPort: MessagePort | undefined+ ): void {+ const core = this.coreValue;+ if (+ !core?.expectsEngine(tabId, ownerEpoch) ||+ !transferredPort ||+ this.engineRoute+ ) {+ transferredPort?.close();+ if (core?.expectsEngine(tabId, ownerEpoch)) {+ this.failOwner(tabId, ownerEpoch, 'invalid direct engine attachment');+ } else {+ this.postProtocolError(+ this.tabs.get(tabId)?.port,+ `stale engine port for epoch ${ownerEpoch}`+ );+ }+ return;+ }++ const route: EngineRoute = {+ tabId,+ ownerEpoch,+ port: transferredPort,+ };+ this.engineRoute = route;+ transferredPort.onmessage = (event: MessageEvent<unknown>) => {+ if (this.engineRoute !== route) return;+ if (event.ports.length > 0) {+ for (const port of event.ports) port.close();+ this.failOwner(+ tabId,+ ownerEpoch,+ 'engine envelope transferred an unexpected port'+ );+ return;+ }+ this.handleEngineMessage(route, event.data);+ };+ transferredPort.onmessageerror = () => {+ if (this.engineRoute === route) {+ this.failOwner(tabId, ownerEpoch, 'engine MessagePort messageerror');+ }+ };+ transferredPort.start();+ }++ private handleEngineMessage(route: EngineRoute, rawMessage: unknown): void {+ const parsed = validateEngineToCoordinatorEnvelope(rawMessage);+ if (!parsed.ok) {+ this.failOwner(+ route.tabId,+ route.ownerEpoch,+ `invalid engine envelope: ${parsed.error}`+ );+ return;+ }+ const message = parsed.value;+ const core = this.coreValue;+ if (!core) return;+ if (+ message.ownerEpoch !== route.ownerEpoch ||+ ('tabId' in message && message.tabId !== route.tabId)+ ) {+ this.failOwner(+ route.tabId,+ route.ownerEpoch,+ 'engine envelope owner tuple does not match its direct route'+ );+ return;+ }++ switch (message.kind) {+ case 'engine-ready': {+ const actions = core.engineReady({+ ...message,+ expectedOwnerLockName: databaseOwnerLockName(core.scope),+ });+ const violated = actions.some(+ (action) => action.kind === 'protocol-violation'+ );+ this.applyActions(actions);+ if (violated) {+ if (this.isCurrentOwner(route.tabId, route.ownerEpoch)) {+ this.failOwner(+ route.tabId,+ route.ownerEpoch,+ 'engine readiness proof was rejected'+ );+ } else {+ this.postTerminateEngine(+ route.tabId,+ route.ownerEpoch,+ 'engine readiness proof was rejected'+ );+ }+ break;+ }+ if (+ core.state.kind === 'active' &&+ core.state.ownerEpoch === message.ownerEpoch+ ) {+ const recoveryResetReason = this.pendingRecoveryResetEpochs.get(+ message.ownerEpoch+ );+ if (recoveryResetReason !== undefined) {+ this.pendingRecoveryResetEpochs.delete(message.ownerEpoch);+ this.recordLogicalResetAndWipe(+ recoveryResetReason,+ message.openOutcome+ );+ } else if (message.openOutcome.startsWith('reset-')) {+ const resetReason = resetReasonForOpenOutcome(message.openOutcome);+ this.recordStorageResetRequired(+ message.ownerEpoch,+ resetReason,+ message.openOutcome+ );+ this.recordLogicalResetAndWipe(+ resetReason,+ message.openOutcome,+ false+ );+ }+ const startedAt = this.activationStarted.get(message.ownerEpoch);+ this.activationStarted.delete(message.ownerEpoch);+ this.telemetry.record({+ name: 'graphql_cache.owner',+ operationCategory: 'lifecycle',+ outcome: 'success',+ ownerEvent: 'activated',+ durationMs:+ startedAt === undefined ? undefined : this.now() - startedAt,+ });+ this.clearActivationTimer();+ this.scheduleHeartbeat(message.ownerEpoch);+ }+ break;+ }+ case 'engine-response': {+ const timing = this.routeStarted.get(message.routeId);+ this.routeStarted.delete(message.routeId);+ if (timing) {+ this.telemetry.record({+ name: 'graphql_cache.coordinator_request',+ operationCategory: timing.category,+ outcome: message.response.ok ? 'success' : 'error',+ errorCode: message.response.ok+ ? 'none'+ : classifyCacheError(message.response.error),+ durationMs: this.now() - timing.startedAt,+ });+ }+ this.applyActions(+ core.engineResponse(+ message.ownerEpoch,+ message.routeId,+ message.response+ )+ );+ break;+ }+ case 'engine-push':+ this.applyActions(core.enginePush(message.ownerEpoch, message.push));+ break;+ case 'engine-drained': {+ const actions = core.engineDrained(message.tabId, message.ownerEpoch);+ if (actions.some((action) => action.kind === 'protocol-violation')) {+ this.applyActions(actions);+ this.failOwner(+ route.tabId,+ route.ownerEpoch,+ 'unexpected engine-drained from current direct route'+ );+ break;+ }+ this.telemetry.record({+ name: 'graphql_cache.owner',+ operationCategory: 'lifecycle',+ outcome: 'graceful',+ ownerEvent: 'graceful-drain-completed',+ });+ this.applyActions(actions);+ break;+ }+ case 'engine-fatal':+ this.failOwner(+ message.tabId,+ message.ownerEpoch,+ message.reason,+ message.fatalCode+ );+ break;+ case 'activation-failed':+ this.failOwner(+ message.tabId,+ message.ownerEpoch,+ message.reason,+ undefined,+ message.failureCode+ );+ break;+ case 'heartbeat-ack':+ this.acceptHeartbeat(message.ownerEpoch, message.heartbeatId);+ break;+ }+ }++ private applyActions(actions: CoordinatorAction[]): void {+ const core = this.coreValue;+ if (!core) return;+ for (const action of actions) {+ switch (action.kind) {+ case 'elect-owner':+ this.clearEngineWatchdogs();+ this.activationStarted.set(action.ownerEpoch, this.now());+ this.telemetry.record({+ name: 'graphql_cache.owner',+ operationCategory: 'lifecycle',+ outcome: 'success',+ ownerEvent: 'elected',+ });+ if (action.databaseAction === 'wipe-before-open') {+ this.pendingRecoveryResetEpochs.set(+ action.ownerEpoch,+ this.nextRecoveryResetReason ?? 'abrupt-owner-loss'+ );+ this.nextRecoveryResetReason = undefined;+ }+ this.postToTab(+ action.tabId,+ envelope<CoordinatorToTabEnvelope>({+ kind: 'become-owner',+ scope: core.scope,+ tabId: action.tabId,+ ownerEpoch: action.ownerEpoch,+ databaseAction: action.databaseAction,+ ownerLockName: databaseOwnerLockName(core.scope),+ hotCapacity: this.hotCapacity,+ })+ );+ this.activationTimer = this.setTimeoutFn(() => {+ this.failOwner(+ action.tabId,+ action.ownerEpoch,+ 'engine activation watchdog timed out'+ );+ }, this.activationTimeoutMs);+ break;+ case 'route-request': {+ this.routeStarted.set(action.routeId, {+ startedAt: this.now(),+ ownerEpoch: action.ownerEpoch,+ category: operationCategoryForRequest(action.request),+ });+ const route = this.engineRoute;+ if (+ !route ||+ route.tabId !== action.ownerTabId ||+ route.ownerEpoch !== action.ownerEpoch+ ) {+ this.failOwner(+ action.ownerTabId,+ action.ownerEpoch,+ 'direct engine MessagePort is missing'+ );+ break;+ }+ route.port.postMessage(+ envelope<CoordinatorToEngineEnvelope>({+ kind: 'engine-request',+ ownerEpoch: action.ownerEpoch,+ routeId: action.routeId,+ request: action.request,+ })+ );+ break;+ }+ case 'deliver-response':+ this.postCacheResponse(action.tabId, action.response);+ break;+ case 'broadcast-push':+ this.broadcast(+ envelope<CoordinatorToTabEnvelope>({+ kind: 'cache-message',+ message: action.push,+ })+ );+ break;+ case 'reject-request':+ this.postCacheResponse(action.tabId, {+ id: action.requestId,+ ok: false,+ error: action.error,+ ...(action.errorCode === undefined+ ? {}+ : { errorCode: action.errorCode }),+ });+ break;+ case 'drain-owner': {+ this.telemetry.record({+ name: 'graphql_cache.owner',+ operationCategory: 'lifecycle',+ outcome: 'graceful',+ ownerEvent: 'graceful-drain-started',+ });+ this.clearHeartbeatTimers();+ const route = this.engineRoute;+ if (+ !route ||+ route.tabId !== action.tabId ||+ route.ownerEpoch !== action.ownerEpoch+ ) {+ this.failOwner(+ action.tabId,+ action.ownerEpoch,+ 'direct engine MessagePort disappeared before drain'+ );+ break;+ }+ route.port.postMessage(+ envelope<CoordinatorToEngineEnvelope>({+ kind: 'drain-engine',+ ownerEpoch: action.ownerEpoch,+ })+ );+ break;+ }+ case 'close-engine-route':+ this.clearEngineWatchdogs();+ if (+ this.engineRoute?.tabId === action.tabId &&+ this.engineRoute.ownerEpoch === action.ownerEpoch+ ) {+ this.engineRoute.port.close();+ this.engineRoute = undefined;+ }+ break;+ case 'drop-tab':+ this.removeTabConnection(action.tabId);+ break;+ case 'retire-tab':+ this.postToTab(+ action.tabId,+ envelope<CoordinatorToTabEnvelope>({+ kind: 'retire-complete',+ tabId: action.tabId,+ ownerEpoch: action.ownerEpoch,+ })+ );+ this.removeTabConnection(action.tabId);+ break;+ case 'schedule-reset-activation':+ this.queueMicrotaskFn(() => {+ if (this.coreValue) {+ this.applyActions(this.coreValue.resumeAfterLoss());+ }+ });+ break;+ case 'broadcast-engine-replaced':+ this.telemetry.record({+ name: 'graphql_cache.owner',+ operationCategory: 'lifecycle',+ outcome: 'success',+ ownerEvent: 'replacement',+ });+ this.broadcast(+ envelope<CoordinatorToTabEnvelope>({+ kind: 'engine-replaced',+ ownerEpoch: action.ownerEpoch,+ })+ );+ break;+ case 'drop-stale-engine-message':+ this.telemetry.record({+ name: 'graphql_cache.stale_drop',+ operationCategory: 'lifecycle',+ outcome: 'success',+ errorCode: 'owner-lost',+ count: 1,+ });+ break;+ case 'protocol-violation':+ this.telemetry.record({+ name: 'graphql_cache.owner',+ operationCategory: 'lifecycle',+ outcome: 'error',+ ownerEvent:+ action.error.includes('already owns') ||+ action.error.includes('multiple owner')+ ? 'multiple-owner-detected'+ : undefined,+ errorCode: 'protocol',+ });+ this.broadcast(+ envelope<CoordinatorToTabEnvelope>({+ kind: 'protocol-error',+ error: action.error,+ })+ );+ break;+ }+ }+ }++ private failOwner(+ tabId: string,+ ownerEpoch: number,+ reason: string,+ fatalCode?: EngineFatalCode,+ failureCode?: ActivationFailureCode+ ): void {+ const core = this.coreValue;+ if (!core) return;+ const actions = core.ownerLost(tabId, ownerEpoch, reason);+ if (actions.length === 0) return;+ this.activationStarted.delete(ownerEpoch);+ const pendingReason = this.recordPendingResetFailure(+ ownerEpoch,+ reason,+ failureCode+ );+ const resetReason =+ pendingReason ??+ (fatalCode === 'storage-reset-required'+ ? 'storage-reset-required'+ : 'abrupt-owner-loss');+ this.nextRecoveryResetReason = resetReason;+ if (pendingReason === undefined) {+ this.recordStorageResetRequired(ownerEpoch, resetReason);+ }+ this.telemetry.record({+ name: 'graphql_cache.owner',+ operationCategory: 'lifecycle',+ outcome: 'abrupt',+ ownerEvent: 'abrupt-loss',+ errorCode:+ fatalCode === 'storage-reset-required'+ ? 'storage-reset'+ : classifyCacheError(reason),+ });+ for (const [routeId, timing] of this.routeStarted) {+ if (timing.ownerEpoch !== ownerEpoch) continue;+ this.routeStarted.delete(routeId);+ this.telemetry.record({+ name: 'graphql_cache.coordinator_request',+ operationCategory: timing.category,+ outcome: 'error',+ errorCode: 'owner-lost',+ durationMs: this.now() - timing.startedAt,+ });+ }+ this.postTerminateEngine(tabId, ownerEpoch, reason);+ this.clearEngineWatchdogs();+ this.applyActions(actions);+ }++ private loseTab(tabId: string, reason: string): void {+ const core = this.coreValue;+ if (!core) return;+ const state = core.state;+ if (+ state.kind !== 'waiting-for-tab' &&+ state.kind !== 'resetting-after-loss' &&+ state.tabId === tabId+ ) {+ this.activationStarted.delete(state.ownerEpoch);+ const pendingReason = this.recordPendingResetFailure(+ state.ownerEpoch,+ reason+ );+ const resetReason = pendingReason ?? 'abrupt-owner-loss';+ this.nextRecoveryResetReason = resetReason;+ if (pendingReason === undefined) {+ this.recordStorageResetRequired(state.ownerEpoch, resetReason);+ }+ this.telemetry.record({+ name: 'graphql_cache.owner',+ operationCategory: 'lifecycle',+ outcome: 'abrupt',+ ownerEvent: 'abrupt-loss',+ errorCode: classifyCacheError(reason),+ });+ for (const [routeId, timing] of this.routeStarted) {+ if (timing.ownerEpoch !== state.ownerEpoch) continue;+ this.routeStarted.delete(routeId);+ this.telemetry.record({+ name: 'graphql_cache.coordinator_request',+ operationCategory: timing.category,+ outcome: 'error',+ errorCode: 'owner-lost',+ durationMs: this.now() - timing.startedAt,+ });+ }+ // The page may still be alive after a liveness or MessagePort failure.+ // Tell it to kill the orphanable DedicatedWorker before dropping its port.+ this.postTerminateEngine(tabId, state.ownerEpoch, reason);+ this.clearEngineWatchdogs();+ }+ this.applyActions(core.tabLost(tabId, reason));+ }++ private recordStorageResetRequired(+ ownerEpoch: number,+ resetReason: CacheResetReason,+ openOutcome?: EngineOpenOutcome+ ): void {+ if (this.resetRequiredEpochs.has(ownerEpoch)) return;+ this.resetRequiredEpochs.add(ownerEpoch);+ this.telemetry.record({+ name: 'graphql_cache.storage_reset_required',+ operationCategory: 'storage',+ outcome: 'error',+ errorCode:+ resetReason === 'namespace-mismatch'+ ? 'schema'+ : resetReason === 'integrity-failure'+ ? 'integrity'+ : 'storage-reset',+ resetReason,+ openOutcome,+ });+ }++ private recordLogicalResetAndWipe(+ resetReason: CacheResetReason,+ openOutcome: EngineOpenOutcome,+ coordinatorWipe = true+ ): void {+ this.telemetry.record({+ name: 'graphql_cache.logical_reset',+ operationCategory: 'storage',+ outcome: 'success',+ errorCode: 'none',+ resetReason,+ openOutcome,+ });+ this.telemetry.record({+ name: 'graphql_cache.reset_wipe',+ operationCategory: 'storage',+ outcome: 'success',+ errorCode: 'none',+ resetReason,+ openOutcome,+ ...(coordinatorWipe ? { resetAttempt: 'wipe-before-open' as const } : {}),+ });+ }++ private recordPendingResetFailure(+ ownerEpoch: number,+ reason: string,+ failureCode?: ActivationFailureCode+ ): CacheResetReason | undefined {+ const resetReason = this.pendingRecoveryResetEpochs.get(ownerEpoch);+ if (resetReason === undefined) return;+ this.pendingRecoveryResetEpochs.delete(ownerEpoch);+ this.telemetry.record({+ name: 'graphql_cache.reset_wipe',+ operationCategory: 'storage',+ outcome: 'error',+ errorCode:+ failureCode === 'recovery-open-failed'+ ? 'storage-reset'+ : classifyCacheError(reason),+ resetReason,+ resetAttempt: 'wipe-before-open',+ });+ return resetReason;+ }++ private isCurrentOwner(tabId: string, ownerEpoch: number): boolean {+ const state = this.coreValue?.state;+ return Boolean(+ state &&+ state.kind !== 'waiting-for-tab' &&+ state.kind !== 'resetting-after-loss' &&+ state.tabId === tabId &&+ state.ownerEpoch === ownerEpoch+ );+ }++ private postTerminateEngine(+ tabId: string,+ ownerEpoch: number,+ reason: string+ ): void {+ this.postToTab(+ tabId,+ envelope<CoordinatorToTabEnvelope>({+ kind: 'terminate-engine',+ tabId,+ ownerEpoch,+ reason,+ })+ );+ }++ private postCacheResponse(tabId: string, response: CacheResponse): void {+ this.postToTab(+ tabId,+ envelope<CoordinatorToTabEnvelope>({+ kind: 'cache-message',+ message: response,+ })+ );+ }++ private postToTab(tabId: string, message: CoordinatorToTabEnvelope): void {+ this.tabs.get(tabId)?.port.postMessage(message);+ }++ private broadcast(message: CoordinatorToTabEnvelope): void {+ for (const connection of this.tabs.values()) {+ connection.port.postMessage(message);+ }+ }++ private postProtocolError(+ port: CoordinatorMessagePort | undefined,+ error: string+ ): void {+ port?.postMessage(+ envelope<CoordinatorToTabEnvelope>({ kind: 'protocol-error', error })+ );+ }++ private removeTabConnection(tabId: string): void {+ const connection = this.tabs.get(tabId);+ if (!connection) return;+ this.tabs.delete(tabId);+ this.portTabs.delete(connection.port);+ connection.cancelLivenessWatch();+ connection.port.close();+ }++ private scheduleHeartbeat(ownerEpoch: number): void {+ this.clearHeartbeatTimers();+ this.heartbeatIntervalTimer = this.setTimeoutFn(() => {+ const route = this.engineRoute;+ const state = this.coreValue?.state;+ if (+ !route ||+ state?.kind !== 'active' ||+ state.ownerEpoch !== ownerEpoch+ ) {+ return;+ }+ const heartbeatId = this.nextHeartbeatId++;+ this.pendingHeartbeat = { ownerEpoch, heartbeatId };+ route.port.postMessage(+ envelope<CoordinatorToEngineEnvelope>({+ kind: 'heartbeat',+ ownerEpoch,+ heartbeatId,+ })+ );+ this.heartbeatTimeoutTimer = this.setTimeoutFn(() => {+ if (+ this.pendingHeartbeat?.ownerEpoch === ownerEpoch &&+ this.pendingHeartbeat.heartbeatId === heartbeatId+ ) {+ this.failOwner(+ route.tabId,+ ownerEpoch,+ 'engine heartbeat watchdog timed out'+ );+ }+ }, this.heartbeatTimeoutMs);+ }, this.heartbeatIntervalMs);+ }++ private acceptHeartbeat(ownerEpoch: number, heartbeatId: number): void {+ if (+ this.pendingHeartbeat?.ownerEpoch !== ownerEpoch ||+ this.pendingHeartbeat.heartbeatId !== heartbeatId+ ) {+ return;+ }+ if (this.heartbeatTimeoutTimer !== undefined) {+ this.clearTimeoutFn(this.heartbeatTimeoutTimer);+ this.heartbeatTimeoutTimer = undefined;+ }+ this.pendingHeartbeat = undefined;+ this.scheduleHeartbeat(ownerEpoch);+ }++ private clearActivationTimer(): void {+ if (this.activationTimer !== undefined) {+ this.clearTimeoutFn(this.activationTimer);+ this.activationTimer = undefined;+ }+ }++ private clearHeartbeatTimers(): void {+ if (this.heartbeatIntervalTimer !== undefined) {+ this.clearTimeoutFn(this.heartbeatIntervalTimer);+ this.heartbeatIntervalTimer = undefined;+ }+ if (this.heartbeatTimeoutTimer !== undefined) {+ this.clearTimeoutFn(this.heartbeatTimeoutTimer);+ this.heartbeatTimeoutTimer = undefined;+ }+ this.pendingHeartbeat = undefined;+ }++ private clearEngineWatchdogs(): void {+ this.clearActivationTimer();+ this.clearHeartbeatTimers();+ }+}diff --git a/apps/web/src/lib/graphql-cache/worker/wasm-module.ts b/apps/web/src/lib/graphql-cache/worker/wasm-module.tsindex 8c92128444..ce5f14f701 100644--- a/apps/web/src/lib/graphql-cache/worker/wasm-module.ts+++ b/apps/web/src/lib/graphql-cache/worker/wasm-module.ts@@ -21,9 +21,43 @@ import type {SelectedRecordPageWire,WriteResult,} from '../protocol';+import { workerCacheTelemetry } from '../telemetry-relay';++/** Stable, payload-free marker latched on reset-required WASM errors. */+export interface CacheStorageResetRequiredError extends Error {+ readonly cacheStorageResetRequired: true;+}++export type CacheOpenOutcome =+ | 'opened-existing'+ | 'opened-new'+ | 'reset-incompatible'+ | 'reset-corrupt'+ | 'reset-storage-uncertain';++export type CacheQueueDiagnostics =+ | {+ availability: 'available';+ /** Decimal strings preserve Rust integer precision across wasm-bindgen. */+ depth: string;+ oldestCreatedAtMs: string | null;+ }+ | {+ /** Compatibility engines must never masquerade as an empty queue. */+ availability: 'unavailable';+ depth: null;+ oldestCreatedAtMs: null;+ };++export interface CacheOpenResult {+ engine: CacheEngine;+ outcome: CacheOpenOutcome;+}export interface CacheEngine {boundIdentity(): Promise<string | null>;+ /** Optional for compatibility engines; absence means unavailable. */+ queueDiagnostics?(): Promise<CacheQueueDiagnostics>;readQuery(opId: string | undefined,query: string,@@ -99,33 +133,140 @@ export interface CacheEngine {deleteKeys(keys: string[]): Promise<string[]>;teardownOperation(opId: string): Promise<void>;clear(): Promise<void>;- /** Close the IndexedDB connection; call before destroyCache. */+ /** Reset/recreate OPFS; concurrent calls wait for the fresh engine. */+ physicalReset(): Promise<void>;+ /** Gracefully close Turso/OPFS and release the owner lock. */close(): Promise<void>;}export interface CacheWasmModule {default: (input?: { module_or_path?: unknown }) => Promise<unknown>;openCache(scope: string, hotCapacity?: number): Promise<CacheEngine>;+ /** Additive open API with a coarse, payload-free recovery outcome. */+ openCacheWithOutcome?(+ scope: string,+ hotCapacity?: number+ ): Promise<CacheOpenResult>;+ /** Atomically wipes before Turso open while retaining one OPFS owner lock. */+ openCacheForRecovery(+ scope: string,+ hotCapacity?: number+ ): Promise<CacheEngine>;+ /** Additive recovery-open API with its coarse wipe outcome. */+ openCacheForRecoveryWithOutcome?(+ scope: string,+ hotCapacity?: number+ ): Promise<CacheOpenResult>;destroyCache(scope: string): Promise<void>;schemaHash(): string;}let modulePromise: Promise<CacheWasmModule> | undefined;+let wasmMemory: WebAssembly.Memory | undefined;++/** Returns the combined module's current unshared linear-memory allocation. */+export function cacheWasmLinearMemoryBytes(): number {+ if (!wasmMemory) throw new Error('cache WASM memory is not initialized');+ return wasmMemory.buffer.byteLength;+}/** Loads and initializes the wasm module exactly once per worker context. */export function loadCacheWasm(): Promise<CacheWasmModule> {if (!modulePromise) {- modulePromise = (async () => {+ const initialization = (async () => {+ const telemetry = workerCacheTelemetry();+ const now = (): number => globalThis.performance?.now() ?? Date.now();const url = new URL('../wasm/cache_wasm.js', import.meta.url).href;const mod = (await import(/* @vite-ignore */ url)) as CacheWasmModule;// Resolve the wasm binary explicitly: vite copies the generated JS as// an opaque asset, so its internal relative `cache_wasm_bg.wasm` URL// would 404 in production. This `new URL` pattern is statically- // analyzable, so vite emits the binary as an asset and rewrites it.+ // analyzable, so vite emits exactly one lazy hashed binary. Explicit+ // fetch/compile keeps download, compile, and instantiate separately observable.const wasmUrl = new URL('../wasm/cache_wasm_bg.wasm', import.meta.url);- await mod.default({ module_or_path: wasmUrl });- return mod;+ const downloadStartedAt = now();+ let bytes: ArrayBuffer;+ try {+ const response = await fetch(wasmUrl);+ if (!response.ok) {+ throw new Error(+ `cache WASM download returned HTTP ${response.status}`+ );+ }+ bytes = await response.arrayBuffer();+ telemetry.record({+ name: 'graphql_cache.wasm_download',+ operationCategory: 'initialization',+ outcome: 'success',+ errorCode: 'none',+ durationMs: now() - downloadStartedAt,+ bytes: bytes.byteLength,+ });+ } catch (error) {+ telemetry.record({+ name: 'graphql_cache.wasm_download',+ operationCategory: 'initialization',+ outcome: 'error',+ errorCode: 'wasm-download',+ durationMs: now() - downloadStartedAt,+ });+ throw error;+ }++ const compileStartedAt = now();+ let compiled: WebAssembly.Module;+ try {+ compiled = await WebAssembly.compile(bytes);+ telemetry.record({+ name: 'graphql_cache.wasm_compile',+ operationCategory: 'initialization',+ outcome: 'success',+ errorCode: 'none',+ durationMs: now() - compileStartedAt,+ });+ } catch (error) {+ telemetry.record({+ name: 'graphql_cache.wasm_compile',+ operationCategory: 'initialization',+ outcome: 'error',+ errorCode: 'wasm-compile',+ durationMs: now() - compileStartedAt,+ });+ throw error;+ }++ const instantiateStartedAt = now();+ try {+ const exports = (await mod.default({ module_or_path: compiled })) as {+ memory?: WebAssembly.Memory;+ };+ if (!(exports.memory instanceof WebAssembly.Memory)) {+ throw new Error('cache WASM did not export its linear memory');+ }+ wasmMemory = exports.memory;+ telemetry.record({+ name: 'graphql_cache.wasm_instantiate',+ operationCategory: 'initialization',+ outcome: 'success',+ errorCode: 'none',+ durationMs: now() - instantiateStartedAt,+ });+ return mod;+ } catch (error) {+ telemetry.record({+ name: 'graphql_cache.wasm_instantiate',+ operationCategory: 'initialization',+ outcome: 'error',+ errorCode: 'wasm-instantiate',+ durationMs: now() - instantiateStartedAt,+ });+ throw error;+ }})();+ modulePromise = initialization;+ void initialization.catch(() => {+ if (modulePromise === initialization) modulePromise = undefined;+ });}return modulePromise;}diff --git a/apps/web/src/lib/graphql-cache/worker/worker-core.test.ts b/apps/web/src/lib/graphql-cache/worker/worker-core.test.tsindex 3a2b429151..3138363657 100644--- a/apps/web/src/lib/graphql-cache/worker/worker-core.test.ts+++ b/apps/web/src/lib/graphql-cache/worker/worker-core.test.ts@@ -1,4 +1,4 @@-import { beforeEach, describe, expect, it, vi } from 'vitest';+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';const loadCacheWasmMock = vi.hoisted(() => vi.fn());@@ -12,6 +12,10 @@ describe('CacheWorkerCore', () => {vi.clearAllMocks();});+ afterEach(() => {+ vi.useRealTimers();+ });+it('dispatches read-records to the wasm engine', async () => {const page: SelectedRecordPageWire = {records: [{ id: 'item-1' }],@@ -315,8 +319,8 @@ describe('CacheWorkerCore', () => {'read:client:group-soup','read:client:child',]);- // Two read RPCs for the same active operation require one wasm call, so- // the full denormalization and its IndexedDB get_batch work run once.+ // Two read RPCs for the same active operation require one WASM call, so+ // the full denormalization and its storage batch read run once.expect(readQuery.mock.calls.filter(([opId]) => opId === 'client:group-soup')).toHaveLength(1);@@ -586,4 +590,571 @@ describe('CacheWorkerCore', () => {expect(messages).toContainEqual({ kind: 'cache-changed' });});++ it('drains earlier request responses before consuming close and rejects later admission', async () => {+ const order: string[] = [];+ let releaseRead!: () => void;+ let markReadStarted!: () => void;+ const readStarted = new Promise<void>((resolve) => {+ markReadStarted = resolve;+ });+ const blocker = new Promise<void>((resolve) => {+ releaseRead = resolve;+ });+ const readQuery = vi.fn(async () => {+ order.push('read:start');+ markReadStarted();+ await blocker;+ order.push('read:done');+ return { kind: 'miss' as const };+ });+ const close = vi.fn(async () => {+ order.push('close');+ });+ loadCacheWasmMock.mockResolvedValue({+ openCache: vi.fn().mockResolvedValue({ readQuery, close }),+ });+ const messages: unknown[] = [];+ const port = {+ postMessage: (message: unknown) => {+ messages.push(message);+ if ((message as { id?: number }).id === 2) order.push('response');+ },+ };+ const core = new CacheWorkerCore();+ await core.handleRequest(port, {+ id: 1,+ kind: 'init',+ scope: 'scope-1',+ });++ const read = core.handleRequest(port, {+ id: 2,+ kind: 'read',+ query: 'query Read { value }',+ });+ await readStarted;+ const drain = core.drain();+ await core.handleRequest(port, {+ id: 3,+ kind: 'clear',+ });+ expect(messages).toContainEqual({+ id: 3,+ ok: false,+ error: 'cache engine is draining',+ });+ expect(close).not.toHaveBeenCalled();++ releaseRead();+ await Promise.all([read, drain]);+ expect(order).toEqual(['read:start', 'read:done', 'response', 'close']);+ });++ it('uses atomic recovery-open instead of opening before a reset', async () => {+ const openCache = vi.fn();+ const openCacheForRecovery = vi.fn().mockResolvedValue({});+ loadCacheWasmMock.mockResolvedValue({+ openCache,+ openCacheForRecovery,+ });+ const messages: unknown[] = [];+ const core = new CacheWorkerCore({ recoveryOpen: true });++ await core.handleRequest(+ { postMessage: (message: unknown) => messages.push(message) },+ { id: 1, kind: 'init', scope: 'scope-1', hotCapacity: 17 }+ );++ expect(openCache).not.toHaveBeenCalled();+ expect(openCacheForRecovery).toHaveBeenCalledWith('scope-1', 17);+ expect(messages).toEqual([{ id: 1, ok: true, result: null }]);+ });++ it('rejects repeated init scope and exact optional capacity mismatches', async () => {+ const openCache = vi.fn().mockResolvedValue({});+ loadCacheWasmMock.mockResolvedValue({ openCache });+ const messages: unknown[] = [];+ const port = { postMessage: (message: unknown) => messages.push(message) };+ const core = new CacheWorkerCore();++ await core.handleRequest(port, {+ id: 1,+ kind: 'init',+ scope: 'scope-1',+ });+ await core.handleRequest(port, {+ id: 2,+ kind: 'init',+ scope: 'scope-1',+ });+ await core.handleRequest(port, {+ id: 3,+ kind: 'init',+ scope: 'scope-2',+ });+ await core.handleRequest(port, {+ id: 4,+ kind: 'init',+ scope: 'scope-1',+ hotCapacity: 1,+ });++ expect(openCache).toHaveBeenCalledOnce();+ expect(messages).toEqual([+ { id: 1, ok: true, result: null },+ { id: 2, ok: true, result: null },+ {+ id: 3,+ ok: false,+ error:+ 'cache worker already initialized for scope scope-1, got scope-2',+ },+ {+ id: 4,+ ok: false,+ error:+ 'cache worker already initialized with hot capacity undefined, got 1',+ },+ ]);++ const capacityMessages: unknown[] = [];+ const capacityCore = new CacheWorkerCore();+ await capacityCore.handleRequest(+ { postMessage: (message: unknown) => capacityMessages.push(message) },+ { id: 5, kind: 'init', scope: 'scope-1', hotCapacity: 2 }+ );+ await capacityCore.handleRequest(+ { postMessage: (message: unknown) => capacityMessages.push(message) },+ { id: 6, kind: 'init', scope: 'scope-1' }+ );+ expect(capacityMessages.at(-1)).toEqual({+ id: 6,+ ok: false,+ error:+ 'cache worker already initialized with hot capacity 2, got undefined',+ });+ });++ it('refreshes queue diagnostics only at bounded checkpoints and recalculates cached age on heartbeat/drain', async () => {+ let monotonicNow = 0;+ let wallClockNow = 1_000;+ const queueDiagnostics = vi.fn().mockResolvedValue({+ availability: 'available',+ depth: '2',+ oldestCreatedAtMs: '900',+ });+ const close = vi.fn().mockResolvedValue(undefined);+ const writeQuery = vi.fn().mockResolvedValue({+ changed: [],+ affectedOps: [],+ reset: false,+ });+ loadCacheWasmMock.mockResolvedValue({+ openCacheWithOutcome: vi.fn().mockResolvedValue({+ engine: { queueDiagnostics, close, writeQuery },+ outcome: 'opened-new',+ }),+ });+ const observations: Array<Record<string, unknown>> = [];+ const core = new CacheWorkerCore({+ monotonicNow: () => monotonicNow,+ wallClockNow: () => wallClockNow,+ queueDiagnosticsIntervalMs: 60_000,+ telemetry: {+ record: (observation) => observations.push(observation),+ flush: vi.fn(),+ },+ });+ const port = { postMessage: vi.fn() };+ await core.handleRequest(port, { id: 1, kind: 'init', scope: 'scope-1' });+ monotonicNow = 1;+ await core.handleRequest(port, {+ id: 2,+ kind: 'write',+ query: 'query Read { value }',+ data: { value: true },+ });+ await Promise.resolve();+ expect(queueDiagnostics).toHaveBeenCalledTimes(1);++ wallClockNow = 1_500;+ core.recordCachedQueueDiagnostics();+ expect(queueDiagnostics).toHaveBeenCalledTimes(1);+ monotonicNow = 60_001;+ await core.handleRequest(port, {+ id: 3,+ kind: 'write',+ query: 'query Read { value }',+ data: { value: false },+ });+ await vi.waitFor(() =>+ expect(+ observations.filter(+ (observation) =>+ observation.name === 'graphql_cache.queue_diagnostics' &&+ observation.outcome === 'success'+ )+ ).toHaveLength(3)+ );+ wallClockNow = 2_000;+ await core.drain();+ expect(queueDiagnostics).toHaveBeenCalledTimes(2);+ expect(+ observations+ .filter(+ (observation) =>+ observation.name === 'graphql_cache.queue_diagnostics' &&+ observation.outcome === 'success'+ )+ .map(({ queueDepth, oldestAgeMs, queueDiagnosticsAvailability }) => ({+ queueDepth,+ oldestAgeMs,+ queueDiagnosticsAvailability,+ }))+ ).toEqual([+ {+ queueDepth: 2,+ oldestAgeMs: 100,+ queueDiagnosticsAvailability: 'available',+ },+ {+ queueDepth: 2,+ oldestAgeMs: 600,+ queueDiagnosticsAvailability: 'available',+ },+ {+ queueDepth: 2,+ oldestAgeMs: 600,+ queueDiagnosticsAvailability: 'available',+ },+ {+ queueDepth: 2,+ oldestAgeMs: 1_100,+ queueDiagnosticsAvailability: 'available',+ },+ ]);+ });++ it('marks compatibility diagnostics unavailable instead of authoritative empty', async () => {+ loadCacheWasmMock.mockResolvedValue({+ openCache: vi.fn().mockResolvedValue({ close: vi.fn() }),+ });+ const observations: Array<Record<string, unknown>> = [];+ const core = new CacheWorkerCore({+ telemetry: {+ record: (observation) => observations.push(observation),+ flush: vi.fn(),+ },+ });+ await core.handleRequest(+ { postMessage: vi.fn() },+ { id: 1, kind: 'init', scope: 'compatibility' }+ );+ expect(observations).toContainEqual(+ expect.objectContaining({+ name: 'graphql_cache.queue_diagnostics',+ outcome: 'success',+ queueDiagnosticsAvailability: 'unavailable',+ })+ );+ expect(observations).not.toContainEqual(+ expect.objectContaining({+ name: 'graphql_cache.queue_diagnostics',+ queueDepth: 0,+ })+ );+ });++ it('serializes a hanging refresh away from correctness and bounds it without changing results', async () => {+ vi.useFakeTimers();+ let monotonicNow = 0;+ const queueDiagnostics = vi+ .fn()+ .mockResolvedValueOnce({+ availability: 'available',+ depth: '1',+ oldestCreatedAtMs: '10',+ })+ .mockImplementation(() => new Promise(() => {}));+ const readQuery = vi.fn().mockResolvedValue({ kind: 'miss' });+ const writeQuery = vi.fn().mockResolvedValue({+ changed: [],+ affectedOps: [],+ reset: false,+ });+ loadCacheWasmMock.mockResolvedValue({+ openCache: vi.fn().mockResolvedValue({+ queueDiagnostics,+ readQuery,+ writeQuery,+ close: vi.fn(),+ }),+ });+ const observations: Array<Record<string, unknown>> = [];+ const port = { postMessage: vi.fn() };+ const core = new CacheWorkerCore({+ monotonicNow: () => monotonicNow,+ queueDiagnosticsIntervalMs: 0,+ queueDiagnosticsTimeoutMs: 20,+ telemetry: {+ record: (observation) => observations.push(observation),+ flush: vi.fn(),+ },+ });+ await core.handleRequest(port, { id: 1, kind: 'init', scope: 'scope' });+ monotonicNow = 1;+ await core.handleRequest(port, {+ id: 2,+ kind: 'write',+ query: 'query Read { value }',+ data: { value: true },+ });+ await vi.waitFor(() => expect(queueDiagnostics).toHaveBeenCalledTimes(2));+ const read = core.handleRequest(port, {+ id: 3,+ kind: 'read',+ query: 'query Read { value }',+ });+ expect(readQuery).not.toHaveBeenCalled();+ await vi.advanceTimersByTimeAsync(20);+ await read;+ expect(readQuery).toHaveBeenCalledOnce();+ expect(port.postMessage).toHaveBeenCalledWith({+ id: 3,+ ok: true,+ result: { kind: 'miss' },+ });+ expect(observations).toContainEqual(+ expect.objectContaining({+ name: 'graphql_cache.queue_diagnostics',+ outcome: 'error',+ errorCode: 'timeout',+ })+ );+ });++ it('keeps the latest snapshot after diagnostic errors and cancels hangs before drain', async () => {+ const resetError = Object.assign(new Error('diagnostic reset marker'), {+ cacheStorageResetRequired: true as const,+ });+ const queueDiagnostics = vi+ .fn()+ .mockResolvedValueOnce({+ availability: 'available',+ depth: '3',+ oldestCreatedAtMs: '100',+ })+ .mockRejectedValueOnce(resetError)+ .mockImplementation(() => new Promise(() => {}));+ const writeQuery = vi.fn().mockResolvedValue({+ changed: [],+ affectedOps: [],+ reset: false,+ });+ const close = vi.fn().mockResolvedValue(undefined);+ loadCacheWasmMock.mockResolvedValue({+ openCache: vi.fn().mockResolvedValue({+ queueDiagnostics,+ writeQuery,+ close,+ }),+ });+ const onStorageResetRequired = vi.fn();+ const observations: Array<Record<string, unknown>> = [];+ const core = new CacheWorkerCore({+ queueDiagnosticsIntervalMs: 0,+ queueDiagnosticsTimeoutMs: 30_000,+ wallClockNow: () => 200,+ onStorageResetRequired,+ telemetry: {+ record: (observation) => observations.push(observation),+ flush: vi.fn(),+ },+ });+ const port = { postMessage: vi.fn() };+ await core.handleRequest(port, { id: 1, kind: 'init', scope: 'scope' });+ await core.handleRequest(port, {+ id: 2,+ kind: 'write',+ query: 'query Read { value }',+ data: { value: true },+ });+ await vi.waitFor(() =>+ expect(observations).toContainEqual(+ expect.objectContaining({+ name: 'graphql_cache.queue_diagnostics',+ outcome: 'error',+ })+ )+ );+ core.recordCachedQueueDiagnostics();+ expect(onStorageResetRequired).not.toHaveBeenCalled();+ expect(observations).toContainEqual(+ expect.objectContaining({+ name: 'graphql_cache.queue_diagnostics',+ outcome: 'error',+ })+ );+ expect(observations.at(-1)).toMatchObject({+ name: 'graphql_cache.queue_diagnostics',+ outcome: 'success',+ queueDiagnosticsAvailability: 'available',+ queueDepth: 3,+ oldestAgeMs: 100,+ });++ await core.handleRequest(port, {+ id: 3,+ kind: 'write',+ query: 'query Read { value }',+ data: { value: false },+ });+ await vi.waitFor(() => expect(queueDiagnostics).toHaveBeenCalledTimes(3));+ await expect(core.drain()).resolves.toBeUndefined();+ expect(close).toHaveBeenCalledOnce();+ expect(onStorageResetRequired).not.toHaveBeenCalled();+ });++ it('reports the initialization outcome but leaves every reset phase to the coordinator', async () => {+ const observations: Array<Record<string, unknown>> = [];+ loadCacheWasmMock.mockResolvedValue({+ openCacheWithOutcome: vi.fn().mockResolvedValue({+ engine: {+ queueDiagnostics: vi.fn().mockResolvedValue({+ availability: 'available',+ depth: '0',+ oldestCreatedAtMs: null,+ }),+ },+ outcome: 'reset-corrupt',+ }),+ });+ const onInitializationOutcome = vi.fn();+ const core = new CacheWorkerCore({+ onInitializationOutcome,+ telemetry: {+ record: (observation) => observations.push(observation),+ flush: vi.fn(),+ },+ });+ await core.handleRequest(+ { postMessage: vi.fn() },+ { id: 1, kind: 'init', scope: 'scope-1' }+ );++ expect(onInitializationOutcome).toHaveBeenCalledOnce();+ expect(onInitializationOutcome).toHaveBeenCalledWith('reset-corrupt');+ expect(+ observations.filter((observation) =>+ [+ 'graphql_cache.storage_reset_required',+ 'graphql_cache.logical_reset',+ 'graphql_cache.reset_wipe',+ ].includes(String(observation.name))+ )+ ).toEqual([]);+ expect(observations).toContainEqual(+ expect.objectContaining({+ name: 'graphql_cache.schema_init',+ openOutcome: 'reset-corrupt',+ })+ );+ });++ it('leaves recovery-open wipe authority with the coordinator', async () => {+ const observations: Array<Record<string, unknown>> = [];+ loadCacheWasmMock.mockResolvedValue({+ openCacheForRecoveryWithOutcome: vi.fn().mockResolvedValue({+ engine: {+ queueDiagnostics: vi.fn().mockResolvedValue({+ availability: 'available',+ depth: '0',+ oldestCreatedAtMs: null,+ }),+ },+ outcome: 'reset-storage-uncertain',+ }),+ });+ const onInitializationOutcome = vi.fn();+ const core = new CacheWorkerCore({+ recoveryOpen: true,+ onInitializationOutcome,+ telemetry: {+ record: (observation) => observations.push(observation),+ flush: vi.fn(),+ },+ });+ await core.handleRequest(+ { postMessage: vi.fn() },+ { id: 1, kind: 'init', scope: 'scope-1' }+ );+ expect(onInitializationOutcome).toHaveBeenCalledWith(+ 'reset-storage-uncertain'+ );+ expect(+ observations.filter((observation) =>+ [+ 'graphql_cache.storage_reset_required',+ 'graphql_cache.logical_reset',+ 'graphql_cache.reset_wipe',+ ].includes(String(observation.name))+ )+ ).toEqual([]);+ });++ it('reports a latched storage-reset marker once before returning failures', async () => {+ const resetError = Object.assign(+ new Error('cache storage reset required'),+ {+ cacheStorageResetRequired: true as const,+ }+ );+ const readQuery = vi.fn().mockRejectedValue(resetError);+ loadCacheWasmMock.mockResolvedValue({+ openCache: vi.fn().mockResolvedValue({ readQuery }),+ });+ const onStorageResetRequired = vi.fn();+ const observations: Array<Record<string, unknown>> = [];+ const messages: unknown[] = [];+ const port = { postMessage: (message: unknown) => messages.push(message) };+ const core = new CacheWorkerCore({+ onStorageResetRequired,+ telemetry: {+ record: (observation) => observations.push(observation),+ flush: vi.fn(),+ },+ });+ await core.handleRequest(port, {+ id: 1,+ kind: 'init',+ scope: 'scope-1',+ });++ await core.handleRequest(port, {+ id: 2,+ kind: 'read',+ query: 'query Read { value }',+ });+ await core.handleRequest(port, {+ id: 3,+ kind: 'read',+ query: 'query ReadAgain { value }',+ });++ expect(onStorageResetRequired).toHaveBeenCalledTimes(1);+ expect(onStorageResetRequired).toHaveBeenCalledWith(resetError);+ expect(+ observations.filter((observation) =>+ [+ 'graphql_cache.storage_reset_required',+ 'graphql_cache.reset_wipe',+ ].includes(String(observation.name))+ )+ ).toEqual([]);+ expect(messages.slice(-2)).toEqual([+ { id: 2, ok: false, error: 'cache storage reset required' },+ { id: 3, ok: false, error: 'cache storage reset required' },+ ]);+ });});diff --git a/apps/web/src/lib/graphql-cache/worker/worker-core.ts b/apps/web/src/lib/graphql-cache/worker/worker-core.tsindex 5b0160b5ee..502a72d888 100644--- a/apps/web/src/lib/graphql-cache/worker/worker-core.ts+++ b/apps/web/src/lib/graphql-cache/worker/worker-core.ts@@ -1,6 +1,6 @@/**- * SharedWorker core: owns the browser's single wasm engine, serves the RPC- * protocol to page ports, and fans out invalidations.+ * Dedicated engine-worker core: owns the elected browser WASM engine, serves+ * coordinator-routed RPCs, and fans out invalidations.*/import { match } from 'ts-pattern';@@ -13,7 +13,18 @@ import type {SelectedRecordPageWire,WriteResult,} from '../protocol';-import { type CacheEngine, loadCacheWasm } from './wasm-module';+import {+ type CacheTelemetryRecorderLike,+ classifyCacheError,+ isolateCacheTelemetry,+ isStorageTransactionRequest,+ operationCategoryForRequest,+} from '../telemetry';+import {+ type CacheEngine,+ type CacheOpenOutcome,+ loadCacheWasm,+} from './wasm-module';type PortLike = {postMessage(msg: unknown): void;@@ -31,6 +42,21 @@ type QueuedEngineRequest = {waiters: RequestWaiter[];};+export interface CacheWorkerCoreOptions {+ /** Atomically recovery-wipes before any Turso open during initialization. */+ recoveryOpen?: boolean;+ /** Called once when WASM latches a reset-required storage failure. */+ onStorageResetRequired?: (error: Error) => void;+ /** Reports the bounded open outcome to the coordinator transport. */+ onInitializationOutcome?: (outcome: CacheOpenOutcome) => void;+ telemetry?: CacheTelemetryRecorderLike;+ /** Injectable clocks and cadence for payload-free diagnostics tests. */+ monotonicNow?: () => number;+ wallClockNow?: () => number;+ queueDiagnosticsIntervalMs?: number;+ queueDiagnosticsTimeoutMs?: number;+}+const NORMAL_READ_PRIORITY = 0;const USER_VISIBLE_READ_PRIORITY = 1;const CACHE_WRITE_PRIORITY = 2;@@ -83,7 +109,33 @@ export class CacheWorkerCore {/** Serializes engine calls while allowing safe read prioritization. */private readonly queue: QueuedEngineRequest[] = [];private running = false;+ private acceptingRequests = true;+ private activeRequestHandlers = 0;+ private readonly drainWaiters = new Set<() => void>();+ private resetRequiredReported = false;+ private hotCapacity: number | undefined;private readonly ports = new Set<PortLike>();+ private readonly telemetry: CacheTelemetryRecorderLike;+ private readonly now: () => number;+ private readonly wallClockNow: () => number;+ private readonly queueDiagnosticsIntervalMs: number;+ private readonly queueDiagnosticsTimeoutMs: number;+ private lastQueueDiagnosticsAt = Number.NEGATIVE_INFINITY;+ private latestQueueDiagnostics:+ | { depth: number; oldestCreatedAtMs?: number }+ | undefined;+ private cancelQueueDiagnostics: (() => void) | undefined;++ constructor(private readonly options: CacheWorkerCoreOptions = {}) {+ this.telemetry = isolateCacheTelemetry(options.telemetry);+ this.now =+ options.monotonicNow ??+ (() => globalThis.performance?.now() ?? Date.now());+ this.wallClockNow = options.wallClockNow ?? (() => Date.now());+ this.queueDiagnosticsIntervalMs =+ options.queueDiagnosticsIntervalMs ?? 60_000;+ this.queueDiagnosticsTimeoutMs = options.queueDiagnosticsTimeoutMs ?? 250;+ }addPort(port: PortLike): void {this.ports.add(port);@@ -95,15 +147,127 @@ export class CacheWorkerCore {async handleRequest(port: PortLike, request: CacheRequest): Promise<void> {const respond = (response: CacheResponse) => port.postMessage(response);+ const startedAt = this.now();+ const category = operationCategoryForRequest(request);+ if (!this.acceptingRequests) {+ this.telemetry.record({+ name: 'graphql_cache.engine_request',+ operationCategory: category,+ outcome: 'error',+ errorCode: 'owner-lost',+ durationMs: this.now() - startedAt,+ });+ respond({+ id: request.id,+ ok: false,+ error: 'cache engine is draining',+ });+ return;+ }++ this.activeRequestHandlers += 1;try {const result = await this.enqueue(request);+ const durationMs = this.now() - startedAt;+ this.telemetry.record({+ name: 'graphql_cache.engine_request',+ operationCategory: category,+ outcome: 'success',+ errorCode: 'none',+ durationMs,+ });+ if (isStorageTransactionRequest(request)) {+ this.telemetry.record({+ name: 'graphql_cache.transaction',+ operationCategory: category,+ outcome: 'success',+ errorCode: 'none',+ durationMs,+ });+ }+ if (+ request.kind === 'write' &&+ typeof result === 'object' &&+ result !== null &&+ 'reset' in result &&+ result.reset === true+ ) {+ this.telemetry.record({+ name: 'graphql_cache.logical_reset',+ operationCategory: 'storage',+ outcome: 'success',+ errorCode: 'none',+ resetReason: 'identity-change',+ });+ }+ if (request.kind === 'read') {+ this.telemetry.record({+ name: 'graphql_cache.read',+ operationCategory: 'read',+ outcome:+ typeof result === 'object' &&+ result !== null &&+ 'kind' in result &&+ result.kind === 'hit'+ ? 'hit'+ : 'miss',+ durationMs,+ });+ }respond({ id: request.id, ok: true, result });} catch (error) {+ const durationMs = this.now() - startedAt;+ const errorCode = classifyCacheError(error);+ this.telemetry.record({+ name: 'graphql_cache.engine_request',+ operationCategory: category,+ outcome: 'error',+ errorCode,+ durationMs,+ });+ if (isStorageTransactionRequest(request)) {+ this.telemetry.record({+ name: 'graphql_cache.transaction',+ operationCategory: category,+ outcome: 'error',+ errorCode,+ durationMs,+ });+ }+ this.reportResetRequired(error);respond({id: request.id,ok: false,error: error instanceof Error ? error.message : String(error),});+ } finally {+ this.activeRequestHandlers -= 1;+ this.resolveDrainWaitersIfIdle();+ }+ }++ /** Stops admission, drains every earlier request/response, then closes OPFS. */+ async drain(): Promise<void> {+ this.acceptingRequests = false;+ // A best-effort observation may never delay correctness teardown.+ this.cancelQueueDiagnostics?.();+ if (+ this.activeRequestHandlers > 0 ||+ this.running ||+ this.queue.length > 0+ ) {+ await new Promise<void>((resolve) => this.drainWaiters.add(resolve));+ }+ if (this.initPromise) await this.initPromise.catch(() => undefined);+ const engine = this.engine;+ if (!engine) return;+ this.recordCachedQueueDiagnostics();+ this.engine = undefined;+ try {+ await engine.close();+ } catch (error) {+ this.reportResetRequired(error);+ throw error;}}@@ -129,7 +293,7 @@ export class CacheWorkerCore {if (duplicate) {duplicate.priority = Math.max(duplicate.priority, priority);duplicate.waiters.push({ resolve, reject });- this.drain();+ this.drainQueue();return;}}@@ -140,7 +304,7 @@ export class CacheWorkerCore {readSignature: signature,waiters: [{ resolve, reject }],});- this.drain();+ this.drainQueue();});}@@ -149,7 +313,7 @@ export class CacheWorkerCore {* Cache-view writes retain FIFO order with each other; overlapping reads* may observe the newer state, which is linearizable and avoids stale work.*/- private drain(): void {+ private drainQueue(): void {if (this.running || this.queue.length === 0) return;let segmentEnd = this.queue.findIndex((queued) =>@@ -173,8 +337,12 @@ export class CacheWorkerCore {this.running = true;void this.dispatch(queued.request).then(- (result) => {+ async (result) => {+ // Resolve the cache result before the bounded observation checkpoint.for (const waiter of queued.waiters) waiter.resolve(result);+ if (isStorageTransactionRequest(queued.request)) {+ await this.refreshQueueDiagnostics(false);+ }},(error) => {for (const waiter of queued.waiters) waiter.reject(error);@@ -182,7 +350,8 @@ export class CacheWorkerCore {).finally(() => {this.running = false;- this.drain();+ this.drainQueue();+ this.resolveDrainWaitersIfIdle();});}@@ -359,26 +528,237 @@ export class CacheWorkerCore {.exhaustive();}+ /** Emits the latest successful snapshot without touching storage. */+ recordCachedQueueDiagnostics(): void {+ const snapshot = this.latestQueueDiagnostics;+ this.telemetry.record({+ name: 'graphql_cache.queue_diagnostics',+ operationCategory: 'queue',+ outcome: 'success',+ errorCode: 'none',+ queueDiagnosticsAvailability: snapshot ? 'available' : 'unavailable',+ ...(snapshot+ ? {+ queueDepth: snapshot.depth,+ oldestAgeMs:+ snapshot.oldestCreatedAtMs === undefined+ ? 0+ : Math.max(0, this.wallClockNow() - snapshot.oldestCreatedAtMs),+ }+ : {}),+ });+ }++ /** Refreshes diagnostics only at serialized initialization/mutation checkpoints. */+ private async refreshQueueDiagnostics(force: boolean): Promise<void> {+ const observedAt = this.now();+ if (+ !force &&+ observedAt - this.lastQueueDiagnosticsAt < this.queueDiagnosticsIntervalMs+ ) {+ return;+ }+ this.lastQueueDiagnosticsAt = observedAt;+ const engine = this.engine;+ if (!engine || typeof engine.queueDiagnostics !== 'function') {+ this.recordCachedQueueDiagnostics();+ return;+ }++ const queueDiagnostics = engine.queueDiagnostics.bind(engine);+ let cancel!: () => void;+ const cancelled = new Promise<{ kind: 'cancelled' }>((resolve) => {+ cancel = () => resolve({ kind: 'cancelled' });+ });+ this.cancelQueueDiagnostics = cancel;+ const attempt = Promise.resolve()+ .then(() => queueDiagnostics())+ .then(+ (value) => ({ kind: 'result' as const, value }),+ (error: unknown) => ({ kind: 'error' as const, error })+ );+ let timeout: ReturnType<typeof setTimeout> | undefined;+ const timedOut = new Promise<{ kind: 'timeout' }>((resolve) => {+ timeout = setTimeout(+ () => resolve({ kind: 'timeout' }),+ this.queueDiagnosticsTimeoutMs+ );+ });++ try {+ const outcome = await Promise.race([attempt, timedOut, cancelled]);+ if (outcome.kind === 'cancelled') return;+ if (outcome.kind === 'timeout') {+ this.telemetry.record({+ name: 'graphql_cache.queue_diagnostics',+ operationCategory: 'queue',+ outcome: 'error',+ errorCode: 'timeout',+ queueDiagnosticsAvailability: this.latestQueueDiagnostics+ ? 'available'+ : 'unavailable',+ });+ return;+ }+ if (outcome.kind === 'error') {+ this.telemetry.record({+ name: 'graphql_cache.queue_diagnostics',+ operationCategory: 'queue',+ outcome: 'error',+ errorCode: classifyCacheError(outcome.error),+ queueDiagnosticsAvailability: this.latestQueueDiagnostics+ ? 'available'+ : 'unavailable',+ });+ return;+ }+ if (outcome.value.availability === 'unavailable') {+ this.recordCachedQueueDiagnostics();+ return;+ }++ const maxSafe = BigInt(Number.MAX_SAFE_INTEGER);+ const depthInteger = BigInt(outcome.value.depth);+ const oldestInteger =+ outcome.value.oldestCreatedAtMs === null+ ? undefined+ : BigInt(outcome.value.oldestCreatedAtMs);+ this.latestQueueDiagnostics = {+ depth: Number(+ depthInteger < 0n+ ? 0n+ : depthInteger > maxSafe+ ? maxSafe+ : depthInteger+ ),+ ...(oldestInteger === undefined+ ? {}+ : {+ oldestCreatedAtMs: Number(+ oldestInteger > maxSafe+ ? maxSafe+ : oldestInteger < -maxSafe+ ? -maxSafe+ : oldestInteger+ ),+ }),+ };+ this.recordCachedQueueDiagnostics();+ } catch (error) {+ // Parsing a malformed diagnostic is an observation failure only.+ this.telemetry.record({+ name: 'graphql_cache.queue_diagnostics',+ operationCategory: 'queue',+ outcome: 'error',+ errorCode: classifyCacheError(error),+ queueDiagnosticsAvailability: this.latestQueueDiagnostics+ ? 'available'+ : 'unavailable',+ });+ } finally {+ if (timeout !== undefined) clearTimeout(timeout);+ if (this.cancelQueueDiagnostics === cancel) {+ this.cancelQueueDiagnostics = undefined;+ }+ }+ }+private async init(scope: string, hotCapacity?: number): Promise<void> {if (this.initPromise) {- // Subsequent tabs connecting to the SharedWorker re-init idempotently.+ // Subsequent page clients routed to this elected engine re-init idempotently.await this.initPromise;if (this.scope !== scope) {throw new Error(`cache worker already initialized for scope ${this.scope}, got ${scope}`);}+ if (this.hotCapacity !== hotCapacity) {+ throw new Error(+ `cache worker already initialized with hot capacity ${String(this.hotCapacity)}, got ${String(hotCapacity)}`+ );+ }return;}this.scope = scope;+ this.hotCapacity = hotCapacity;this.initPromise = (async () => {const wasm = await loadCacheWasm();- this.engine = await wasm.openCache(scope, hotCapacity);+ const schemaStartedAt = this.now();+ try {+ let openOutcome: CacheOpenOutcome;+ if (this.options.recoveryOpen) {+ if (wasm.openCacheForRecoveryWithOutcome) {+ const opened = await wasm.openCacheForRecoveryWithOutcome(+ scope,+ hotCapacity+ );+ this.engine = opened.engine;+ openOutcome = opened.outcome;+ } else {+ this.engine = await wasm.openCacheForRecovery(scope, hotCapacity);+ openOutcome = 'reset-storage-uncertain';+ }+ } else if (wasm.openCacheWithOutcome) {+ const opened = await wasm.openCacheWithOutcome(scope, hotCapacity);+ this.engine = opened.engine;+ openOutcome = opened.outcome;+ } else {+ this.engine = await wasm.openCache(scope, hotCapacity);+ openOutcome = 'opened-existing';+ }+ this.options.onInitializationOutcome?.(openOutcome);+ this.telemetry.record({+ name: 'graphql_cache.schema_init',+ operationCategory: 'initialization',+ outcome: 'success',+ errorCode: 'none',+ openOutcome,+ durationMs: this.now() - schemaStartedAt,+ });+ await this.refreshQueueDiagnostics(true);+ } catch (error) {+ this.telemetry.record({+ name: 'graphql_cache.schema_init',+ operationCategory: 'initialization',+ outcome: 'error',+ errorCode: classifyCacheError(error),+ durationMs: this.now() - schemaStartedAt,+ });+ throw error;+ }})();await this.initPromise;}- /** Notifies every page connected to this shared engine. */+ private reportResetRequired(error: unknown): void {+ if (+ this.resetRequiredReported ||+ (typeof error !== 'object' && typeof error !== 'function') ||+ error === null ||+ !('cacheStorageResetRequired' in error) ||+ error.cacheStorageResetRequired !== true+ ) {+ return;+ }+ this.resetRequiredReported = true;+ this.options.onStorageResetRequired?.(+ error instanceof Error ? error : new Error('cache storage reset required')+ );+ }++ private resolveDrainWaitersIfIdle(): void {+ if (+ this.activeRequestHandlers > 0 ||+ this.running ||+ this.queue.length > 0+ ) {+ return;+ }+ for (const resolve of this.drainWaiters) resolve();+ this.drainWaiters.clear();+ }++ /** Notifies every page routed to this elected engine. */private fanOut(result: WriteResult, cacheChanged: boolean): void {if (result.affectedOps.length > 0) {this.push({diff --git a/apps/web/src/lib/service-clients/service-storage/graphql-soup.test.ts b/apps/web/src/lib/service-clients/service-storage/graphql-soup.test.tsnew file mode 100644index 0000000000..be28946d24--- /dev/null+++ b/apps/web/src/lib/service-clients/service-storage/graphql-soup.test.ts@@ -0,0 +1,207 @@+import type { BrowserTursoCacheRolloutDecision } from '@graphql-cache/rollout-policy';+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';++const mocks = vi.hoisted(() => {+ let enabled = true;+ let graphqlEnabled = true;+ let tauri = false;+ let releaseApi: (() => void) | undefined;+ let markApiStarted: (() => void) | undefined;+ const apiStarted = () =>+ new Promise<void>((resolve) => {+ markApiStarted = resolve;+ });+ let queuedMutationCount = 0;+ const host = {+ disabled: false,+ dispose: vi.fn(),+ enqueueOptimisticMutation: vi.fn(async () => {+ queuedMutationCount += 1;+ return { transactionId: 'tx-1' };+ }),+ commitOptimisticWrite: vi.fn(async () => {+ queuedMutationCount -= 1;+ return {+ changed: [],+ affectedOps: [],+ reset: false,+ revalidations: [],+ };+ }),+ };+ const apiCall = vi.fn(async () => {+ markApiStarted?.();+ await new Promise<void>((resolve) => {+ releaseApi = resolve;+ });+ return { data: { committed: true } };+ });+ const plainClient = { kind: 'plain' };+ return {+ get enabled() {+ return enabled;+ },+ set enabled(value: boolean) {+ enabled = value;+ },+ get graphqlEnabled() {+ return graphqlEnabled;+ },+ set graphqlEnabled(value: boolean) {+ graphqlEnabled = value;+ },+ get tauri() {+ return tauri;+ },+ set tauri(value: boolean) {+ tauri = value;+ },+ host,+ apiCall,+ apiStarted,+ releaseApi: () => releaseApi?.(),+ resetQueue: () => {+ queuedMutationCount = 0;+ },+ queueDepth: () => queuedMutationCount,+ plainClient,+ createWorkerCacheHost: vi.fn(() => host),+ createTauriCacheHost: vi.fn(() => host),+ };+});++vi.mock('@core/constant/featureFlags', () => ({+ ENABLE_BEARER_TOKEN_AUTH: false,+}));+vi.mock('@core/constant/servers', () => ({+ SERVER_HOSTS: { 'document-storage-service': 'http://dss.test' },+}));+vi.mock('@core/util/fetchWithToken', () => ({ fetchToken: vi.fn() }));+vi.mock('@core/util/platform', () => ({ isTauri: () => mocks.tauri }));+vi.mock('@core/util/platformFetch', () => ({ platformFetch: vi.fn() }));+vi.mock('@graphql-cache/rollout', () => ({+ getBrowserTursoCacheRolloutDecision:+ (): BrowserTursoCacheRolloutDecision => ({+ enabled: mocks.tauri ? mocks.graphqlEnabled : mocks.enabled,+ cohort: mocks.tauri ? 'unknown' : 'treatment',+ reason: mocks.tauri ? 'tauri-native-unchanged' : 'posthog-enabled',+ nativeCacheUnchanged: mocks.tauri,+ }),+}));+vi.mock('@graphql-cache/index', () => ({+ createWorkerCacheHost: mocks.createWorkerCacheHost,+ createTauriCacheHost: mocks.createTauriCacheHost,+ entityFromArgument: () => () => undefined,+}));+vi.mock('@graphql-cache/lifecycle', () => ({+ registerCacheHost: () => () => undefined,+}));+vi.mock('@graphql-cache/scope', () => ({+ getOrCreateCacheScope: () => 'anonymous-scope',+}));+vi.mock('@graphql-cache/exchange/normalized-cache-exchange', () => ({+ normalizedCacheExchange: (host: unknown) => ({ kind: 'cache', host }),+}));+vi.mock('@service-auth/fetch', () => ({ getMacroApiToken: vi.fn() }));+vi.mock('graphql', () => ({ print: () => 'mutation Test' }));+vi.mock('graphql-ws', () => ({+ createClient: () => ({ subscribe: vi.fn(), dispose: vi.fn() }),+}));+vi.mock('./graphql/generated/graphql', () => ({+ GroupSoupDocument: {},+ SoupDocument: {},+}));+vi.mock('./graphql-soup-websocket', () => ({+ SOUP_GRAPHQL_WEBSOCKET_RETRY_ATTEMPTS: 0,+ shouldRetryGraphqlSoupWebSocket: () => false,+ createGraphqlSoupWebSocketUrlResolver: () => () => 'ws://dss.test',+ createGraphqlSoupSubscriptionsLifecycle: () => ({+ replace: vi.fn(),+ dispose: vi.fn(),+ }),+}));+vi.mock('@urql/core', () => ({+ fetchExchange: { kind: 'fetch' },+ subscriptionExchange: () => ({ kind: 'subscription' }),+ createClient: (options: {+ exchanges: Array<{ kind?: string; host?: typeof mocks.host }>;+ }) => {+ const cacheExchange = options.exchanges.find(+ ({ kind }) => kind === 'cache'+ );+ if (!cacheExchange?.host) return mocks.plainClient;+ const host = cacheExchange.host;+ return {+ kind: 'cached',+ mutation: () => ({+ toPromise: async () => {+ await host.enqueueOptimisticMutation();+ const response = await mocks.apiCall();+ await host.commitOptimisticWrite();+ return response;+ },+ }),+ };+ },+}));++describe('GraphQL Soup browser cache session gate', () => {+ beforeEach(() => {+ vi.resetModules();+ vi.clearAllMocks();+ mocks.enabled = true;+ mocks.graphqlEnabled = true;+ mocks.tauri = false;+ mocks.resetQueue();+ });++ afterEach(() => {+ vi.unstubAllGlobals();+ });++ it('latches an activated client through a flag change until navigation', async () => {+ const apiStarted = mocks.apiStarted();+ const soup = await import('./graphql-soup');+ const client = soup.getGraphqlSoupClient() as unknown as {+ mutation(): { toPromise(): Promise<unknown> };+ };+ const mutation = client.mutation().toPromise();+ await apiStarted;++ mocks.enabled = false;+ expect(soup.getGraphqlSoupClient()).toBe(client);+ expect(soup.graphqlCacheEnabled()).toBe(true);+ expect(mocks.queueDepth()).toBe(1);+ expect(mocks.host.dispose).not.toHaveBeenCalled();++ mocks.releaseApi();+ await expect(mutation).resolves.toEqual({ data: { committed: true } });+ expect(mocks.apiCall).toHaveBeenCalledOnce();+ expect(mocks.host.enqueueOptimisticMutation).toHaveBeenCalledOnce();+ expect(mocks.host.commitOptimisticWrite).toHaveBeenCalledOnce();+ expect(mocks.queueDepth()).toBe(0);+ expect(mocks.host.dispose).not.toHaveBeenCalled();+ });++ it('imports and uses the native path without constructing browser workers', async () => {+ const WorkerConstructor = vi.fn(() => {+ throw new Error('browser worker must not be constructed on Tauri');+ });+ vi.stubGlobal('Worker', WorkerConstructor);+ vi.stubGlobal('SharedWorker', WorkerConstructor);+ mocks.tauri = true;+ mocks.enabled = false;++ const soup = await import('./graphql-soup');+ const nativeClient = soup.getGraphqlSoupClient();+ mocks.graphqlEnabled = false;++ expect(soup.graphqlCacheEnabled()).toBe(false);+ expect(soup.getGraphqlSoupClient()).toBe(mocks.plainClient);+ expect(nativeClient).not.toBe(mocks.plainClient);+ expect(mocks.host.dispose).not.toHaveBeenCalled();+ expect(mocks.createTauriCacheHost).toHaveBeenCalledOnce();+ expect(mocks.createWorkerCacheHost).not.toHaveBeenCalled();+ expect(WorkerConstructor).not.toHaveBeenCalled();+ });+});diff --git a/apps/web/src/lib/service-clients/service-storage/graphql-soup.ts b/apps/web/src/lib/service-clients/service-storage/graphql-soup.tsindex a2abe57751..8d28646a7e 100644--- a/apps/web/src/lib/service-clients/service-storage/graphql-soup.ts+++ b/apps/web/src/lib/service-clients/service-storage/graphql-soup.ts@@ -1,7 +1,4 @@-import {- ENABLE_BEARER_TOKEN_AUTH,- ENABLE_GRAPHQL_SOUP,-} from '@core/constant/featureFlags';+import { ENABLE_BEARER_TOKEN_AUTH } from '@core/constant/featureFlags';import { SERVER_HOSTS } from '@core/constant/servers';import { fetchToken } from '@core/util/fetchWithToken';import { isTauri } from '@core/util/platform';@@ -14,6 +11,7 @@ import {entityFromArgument,} from '@graphql-cache/index';import { registerCacheHost } from '@graphql-cache/lifecycle';+import { getBrowserTursoCacheRolloutDecision } from '@graphql-cache/rollout';import { getOrCreateCacheScope } from '@graphql-cache/scope';import { getMacroApiToken } from '@service-auth/fetch';import type { ApiUserNotification } from '@service-notification/generated/schemas/apiUserNotification';@@ -121,11 +119,27 @@ const graphqlSoupClient = createClient({* process (graphql_cache_plugin).*/export function graphqlCacheEnabled(): boolean {- return ENABLE_GRAPHQL_SOUP();+ if (!isTauri() && browserCacheClientActivated) return true;+ return getBrowserTursoCacheRolloutDecision().enabled;}let cachedClient: Client | undefined;let cachedCacheHost: CacheHost | undefined;+let cachedCacheCleanup: (() => void) | undefined;+let browserCacheClientActivated = false;++function fallbackAfterInitializationFailure(): void {+ const cleanup = cachedCacheCleanup;+ cachedCacheCleanup = undefined;+ cachedCacheHost = undefined;+ cachedClient = graphqlSoupClient;+ browserCacheClientActivated = false;+ try {+ cleanup?.();+ } catch {+ // Initialization-failure cleanup cannot alter GraphQL transport fallback.+ }+}/** Returns the persistent normalized-cache host after client initialization. */export function getGraphqlCacheHost(): CacheHost | undefined {@@ -141,20 +155,29 @@ export function getGraphqlCacheHost(): CacheHost | undefined {* Any failure falls back to the plain fetch client for the session.*/export function getGraphqlSoupClient(): Client {- if (!graphqlCacheEnabled()) return graphqlSoupClient;- cachedClient ??= (() => {+ const native = isTauri();+ // Only the browser Turso client is session-latched. Tauri keeps the prior+ // dynamic GraphQL transport behavior and can return to the plain client when+ // ENABLE_GRAPHQL_SOUP changes without constructing a browser resource.+ if (!native && browserCacheClientActivated && cachedClient)+ return cachedClient;+ const rollout = getBrowserTursoCacheRolloutDecision();+ if (!rollout.enabled) return graphqlSoupClient;+ if (cachedClient) return cachedClient;+ cachedClient = (() => {let host: CacheHost | undefined;let websocketClient: GraphqlWsClient | undefined;let unregisterHost: () => void = () => undefined;const subscriptionsLifecycle = createGraphqlSoupSubscriptionsLifecycle();- const onInitializationError = (error: Error) => {- if (!host || cachedCacheHost !== host) return;+ const cleanup = () => {unregisterHost();- host.dispose();+ host?.dispose();subscriptionsLifecycle.dispose();if (websocketClient) void websocketClient.dispose();- cachedCacheHost = undefined;- cachedClient = graphqlSoupClient;+ };+ const onInitializationError = (error: Error) => {+ if (!host || cachedCacheHost !== host) return;+ fallbackAfterInitializationFailure();console.warn('graphql cache async init failed; using uncached client',error@@ -162,9 +185,13 @@ export function getGraphqlSoupClient(): Client {};try {const scope = getOrCreateCacheScope();- host = isTauri()+ host = native? createTauriCacheHost({ scope, onInitializationError })- : createWorkerCacheHost({ scope, onInitializationError });+ : createWorkerCacheHost({+ scope,+ onInitializationError,+ rolloutCohort: rollout.cohort,+ });const resolveWebSocketUrl = createGraphqlSoupWebSocketUrlResolver({dssHost,bearerTokenAuth: ENABLE_BEARER_TOKEN_AUTH,@@ -232,13 +259,13 @@ export function getGraphqlSoupClient(): Client {cachedCacheHost = host;unregisterHost = registerCacheHost(host);subscriptionsLifecycle.replace(client, host);+ cachedCacheCleanup = cleanup;+ browserCacheClientActivated = !native;return client;} catch (error) {- unregisterHost();- host?.dispose();- subscriptionsLifecycle.dispose();- if (websocketClient) void websocketClient.dispose();+ cleanup();cachedCacheHost = undefined;+ cachedCacheCleanup = undefined;console.warn('graphql cache init failed; using uncached client', error);return graphqlSoupClient;}diff --git a/apps/web/src/observability/browser.ts b/apps/web/src/observability/browser.tsindex c48bd531e4..6eb7e53be9 100644--- a/apps/web/src/observability/browser.ts+++ b/apps/web/src/observability/browser.ts@@ -1,3 +1,4 @@+import { recordBrowserTursoCacheNavigation } from '@graphql-cache/rollout-observability';import { Telemetry } from '@macro-inc/observability';import { createWebTracingProvider } from '@macro-inc/observability/web';// This static import loads the zone.js Promise patch before application modules run.@@ -62,6 +63,7 @@ export async function initializeBrowserObservability(): Promise<void> {tracingProvider: (resource, getUserId) =>createWebTracingProvider(telemetryConfig, resource, getUserId),});+ recordBrowserTursoCacheNavigation();window.addEventListener('pagehide', () => void Telemetry.flush());window.addEventListener('error', (event) => {diff --git a/apps/web/src/vite-env.d.ts b/apps/web/src/vite-env.d.tsindex ec21d7d642..2205896d6a 100644--- a/apps/web/src/vite-env.d.ts+++ b/apps/web/src/vite-env.d.ts@@ -10,6 +10,8 @@ interface ImportMetaEnv {readonly VITE_OTEL_ENV?: string;readonly VITE_ENABLE_BROWSER_OTEL?: string;readonly VITE_ENABLE_REMINDERS?: string;+ readonly VITE_ENABLE_BROWSER_TURSO_CACHE?: string;+ readonly VITE_DISABLE_BROWSER_TURSO_CACHE?: string;}interface ImportMeta {diff --git a/apps/web/tauri/graphql_cache_plugin/Cargo.toml b/apps/web/tauri/graphql_cache_plugin/Cargo.tomlindex 7cb76958ad..7df20cfd00 100644--- a/apps/web/tauri/graphql_cache_plugin/Cargo.toml+++ b/apps/web/tauri/graphql_cache_plugin/Cargo.toml@@ -13,5 +13,5 @@ tokio = { workspace = true, features = ["sync"] }tracing = { workspace = true }[dev-dependencies]-pollster = "0.4"+pollster = { workspace = true }tempfile = "3"diff --git a/crates/client/README.md b/crates/client/README.mdindex 7d473c604b..8c43b7afcf 100644--- a/crates/client/README.md+++ b/crates/client/README.md@@ -9,8 +9,9 @@ Normalized GraphQL cache with disk-backed persistence for urql. Design doc:|---|---|| `cache-core` | Pure engine: normalize/denormalize, LRU hot tier, dependency index, durable ordered optimistic-mutation queue, async `Storage` trait || `cache-sqlite` | `Storage` over SQLite — Tauri native host |-| `cache-idb` | `Storage` over IndexedDB via the `idb` crate — browser wasm host (wasm32-only; empty shell elsewhere) |-| `cache-wasm` | wasm-bindgen shell exposing the engine to the browser worker glue (`apps/web/src/lib/graphql-cache/`) |+| `cache-turso` | `Storage` over Turso core — browser WASM host |+| `turso-opfs` | Browser OPFS `IO`/`File` adapter for the dedicated Turso engine worker |+| `cache-wasm` | wasm-bindgen shell combining the engine, Turso storage, and OPFS adapter for browser worker glue (`apps/web/src/lib/graphql-cache/`) |The Tauri host lives in the tauri workspace (it needs the patched tauri forkpinned there): `apps/web/tauri/graphql_cache_plugin`, path-depending on@@ -20,23 +21,59 @@ Tauri's Linux desktop stack needs its WebKitGTK/DBus system libraries).## Tests-From the repository root (these crates are workspace members; use-`SQLX_OFFLINE=true` as usual):+Run from the repository root:```sh-SQLX_OFFLINE=true cargo test -p cache-core -p cache-sqlite # native-cargo check --target wasm32-unknown-unknown -p cache-idb -p cache-wasm --all-targets-wasm-pack test --headless --chrome crates/client/cache-idb # browser tests (IDB backend)+cargo test -p cache-core -p cache-sqlite -p cache-turso -p turso-opfs+cargo check --target wasm32-unknown-unknown -p cache-turso -p turso-opfs -p cache-wasm --all-targets+wasm-pack test --headless --chrome crates/client/cache-turso+wasm-pack test --headless --chrome crates/client/turso-opfs```NixOS note: wasm-pack downloads a dynamically-linked chromedriver that won't-run. Work around by invoking the runner directly with a nix chromedriver:+run. Work around by resolving the cached runner whose reported version matches+the workspace's `wasm-bindgen`, then invoke it with a Nix chromedriver:```sh-cd crates/client/cache-idb-CARGO_TARGET_WASM32_UNKNOWN_UNKNOWN_RUNNER=~/.cache/.wasm-pack/wasm-bindgen-*/wasm-bindgen-test-runner \-CHROMEDRIVER=$(command -v chromedriver || echo /nix/store/*undetected-chromedriver*/bin/undetected-chromedriver) \-WASM_BINDGEN_TEST_ONLY_WEB=1 cargo test --target wasm32-unknown-unknown+wasm_bindgen_version=$(+ cargo tree -p cache-turso --target wasm32-unknown-unknown -i wasm-bindgen --prefix none |+ sed -n 's/^wasm-bindgen v//p' |+ head -n 1+)+runner=+for candidate in "$(command -v wasm-bindgen-test-runner || true)" \+ "$HOME"/.cache/.wasm-pack/wasm-bindgen-*/wasm-bindgen-test-runner; do+ [ -x "$candidate" ] || continue+ [ "$("$candidate" --version)" = "wasm-bindgen-test-runner $wasm_bindgen_version" ] || continue+ runner=$candidate+ break+done+test -x "$runner" || {+ echo "no wasm-bindgen-test-runner matching $wasm_bindgen_version" >&2+ exit 1+}++chromedriver=$(command -v chromedriver || true)+if [ -z "$chromedriver" ]; then+ for candidate in /nix/store/*chromedriver*/bin/chromedriver \+ /nix/store/*chromedriver*/bin/undetected-chromedriver; do+ [ -x "$candidate" ] || continue+ chromedriver=$candidate+ break+ done+fi+test -x "$chromedriver" || {+ echo 'no Nix chromedriver found' >&2+ exit 1+}++CARGO_TARGET_WASM32_UNKNOWN_UNKNOWN_RUNNER="$runner" \+CHROMEDRIVER="$chromedriver" \+WASM_BINDGEN_TEST_ONLY_WEB=1 cargo test --target wasm32-unknown-unknown -p cache-turso++CARGO_TARGET_WASM32_UNKNOWN_UNKNOWN_RUNNER="$runner" \+CHROMEDRIVER="$chromedriver" \+WASM_BINDGEN_TEST_ONLY_WEB=1 cargo test --target wasm32-unknown-unknown -p turso-opfs --lib```## Key policydiff --git a/crates/client/cache-core/Cargo.toml b/crates/client/cache-core/Cargo.tomlindex e4449f1cc7..1b39980c57 100644--- a/crates/client/cache-core/Cargo.toml+++ b/crates/client/cache-core/Cargo.toml@@ -19,4 +19,4 @@ apollo-compiler = { workspace = true }sha2 = { workspace = true }[dev-dependencies]-pollster = "0.4"+pollster = { workspace = true }diff --git a/crates/client/cache-core/src/codec.rs b/crates/client/cache-core/src/codec.rsindex 38e75261d8..71d9757fa4 100644--- a/crates/client/cache-core/src/codec.rs+++ b/crates/client/cache-core/src/codec.rs@@ -1,8 +1,10 @@-//! Binary record codec shared by all persistent backends (IndexedDB,-//! SQLite). Records are stored as postcard bytes; the cache namespace embeds-//! [`CACHE_FORMAT_VERSION`] and [`CACHE_SCHEMA_COMPATIBILITY_EPOCH`]. Additive-//! GraphQL schema changes keep existing records, while incompatible schema or-//! record-format changes start a fresh cache.+//! Binary record codec shared by all persistent backends (browser Turso and+//! native SQLite). Records are stored as postcard bytes; the logical namespace+//! embeds [`CACHE_FORMAT_VERSION`] and [`CACHE_SCHEMA_COMPATIBILITY_EPOCH`].+//! A healthy, graceful browser reopen with matching versions preserves records,+//! queued mutations, and optimistic layers. A compatibility/format mismatch or+//! abrupt/uncertain browser owner loss physically resets the database and+//! discards all three.use crate::normalize::RecordUpdates;use crate::queue::{PersistedOptimisticLayer, StoredMutation};@@ -75,8 +77,10 @@ pub fn decode_record_updates(bytes: &[u8]) -> Result<RecordUpdates, CodecError>decode(bytes)}-/// Canonical database/namespace name for a cache instance.-/// `scope` identifies the user/workspace (host-provided).+/// Canonical logical namespace for a cache instance.+///+/// `scope` is an anonymous, client-generated token supplied by the host. It is+/// neither user nor workspace identity.pub fn cache_namespace(scope: &str) -> String {format!("graphql-cache:{scope}:s{CACHE_SCHEMA_COMPATIBILITY_EPOCH}:v{CACHE_FORMAT_VERSION}")}@@ -84,9 +88,11 @@ pub fn cache_namespace(scope: &str) -> String {/// Stable physical database name for a cache scope.////// Unlike [`cache_namespace`], this deliberately excludes the schema-/// compatibility epoch and cache format version. Normalized records are-/// disposable on version changes, while queued mutations represent user intent-/// and must remain discoverable.+/// compatibility epoch and cache format version so the browser can acquire the+/// same main/WAL paths and validate their metadata. Only a healthy, graceful+/// close and compatible reopen preserves those files. A compatibility/format+/// mismatch or abrupt/uncertain owner loss physically resets both files,+/// discarding every row, including queued mutations and optimistic layers.pub fn cache_database_name(scope: &str) -> String {format!("graphql-cache:{scope}")}@@ -133,6 +139,9 @@ mod tests {#[test]fn namespace_uses_schema_compatibility_epoch_not_schema_hash() {- assert_eq!(cache_namespace("user-1"), "graphql-cache:user-1:s1:v2");+ assert_eq!(+ cache_namespace("client-token-1"),+ "graphql-cache:client-token-1:s1:v2"+ );}}diff --git a/crates/client/cache-core/src/engine.rs b/crates/client/cache-core/src/engine.rsindex 6bed2745d4..8046a817a6 100644--- a/crates/client/cache-core/src/engine.rs+++ b/crates/client/cache-core/src/engine.rs@@ -27,7 +27,7 @@ use crate::queue::{use crate::record_selection::{RecordCursor, RecordSelection, RecordSelectionError, SelectedRecordPage, validate_limit,};-use crate::store::Storage;+use crate::store::{QueueDiagnostics, Storage};use crate::value::{EntityKey, Record, canonical_json};use lru::LruCache;use serde_json::Value as Json;@@ -1309,12 +1309,28 @@ impl<S: Storage> Engine<S> {self.deps.active_ops()}- /// Access to the underlying storage (hosts need it for lifecycle- /// operations like closing connections before database deletion).+ /// Returns payload-free durable mutation queue diagnostics.+ pub async fn queue_diagnostics(&self) -> Result<QueueDiagnostics, EngineError<S::Error>> {+ self.storage+ .queue_diagnostics()+ .await+ .map_err(EngineError::Storage)+ }++ /// Access to the underlying storage for non-consuming diagnostics.pub fn storage(&self) -> &S {&self.storage}+ /// Consumes the engine and returns its owned storage.+ ///+ /// Hosts must use this transition for storage lifecycles that require+ /// exclusive ownership, such as proving that a browser database connection+ /// is closed before preserving or physically resetting its OPFS files.+ pub fn into_storage(self) -> S {+ self.storage+ }+/// Memoized document parse. Takes the map (not `&mut self`) so callers/// can keep the returned borrow while using other engine fields.fn document<'d>(diff --git a/crates/client/cache-core/src/store.rs b/crates/client/cache-core/src/store.rsindex 8cc65b46f3..546dfc064a 100644--- a/crates/client/cache-core/src/store.rs+++ b/crates/client/cache-core/src/store.rs@@ -1,9 +1,9 @@//! Storage abstraction: the cold tier behind the in-memory hot tier.//!-//! Implementations: in-memory (tests, Phase 1), IndexedDB via the `idb`-//! crate (browser, Phase 2), SQLite (Tauri native, Phase 2). Futures are-//! [`MaybeSend`]: `Send` on native targets (so hosts can drive the engine-//! from a multi-threaded runtime), unbounded on wasm — wasm futures aren't+//! Implementations: in-memory (tests), Turso over OPFS (browser), and SQLite+//! (Tauri native). Futures are [`MaybeSend`]: `Send` on native targets (so+//! hosts can drive the engine from a multi-threaded runtime), unbounded on+//! wasm — wasm futures aren't//! `Send`.use crate::queue::{@@ -15,6 +15,27 @@ use maybe_send::MaybeSend;use std::collections::{BTreeMap, HashMap};use std::convert::Infallible;+/// Whether a storage implementation can provide queue diagnostics.+#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]+pub enum QueueDiagnosticsAvailability {+ /// This compatibility implementation has no authoritative diagnostics.+ #[default]+ Unavailable,+ /// The depth and oldest timestamp were read from authoritative storage.+ Available,+}++/// Payload-free durable mutation queue diagnostics.+#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]+pub struct QueueDiagnostics {+ /// Whether the numeric snapshot is authoritative.+ pub availability: QueueDiagnosticsAvailability,+ /// Number of durable mutations waiting for settlement.+ pub depth: u64,+ /// Oldest durable enqueue timestamp, or `None` when the queue is empty.+ pub oldest_created_at_ms: Option<i64>,+}+/// Async KV over normalized records. Batch-oriented by design: the engine/// issues one `get_batch` per denormalization round, never per record.pub trait Storage: MaybeSend {@@ -58,6 +79,17 @@ pub trait Storage: MaybeSend {&self,) -> impl Future<Output = Result<Vec<QueuedMutation>, Self::Error>> + MaybeSend;+ /// Returns only queue depth and the oldest enqueue timestamp.+ ///+ /// The default preserves source compatibility for external storage+ /// implementations and explicitly reports diagnostics as unavailable.+ /// Production backends override it with an authoritative aggregate query.+ fn queue_diagnostics(+ &self,+ ) -> impl Future<Output = Result<QueueDiagnostics, Self::Error>> + MaybeSend {+ async { Ok(QueueDiagnostics::default()) }+ }+/// Claims the oldest mutation when it is runnable and not actively leased./// Later mutations are never skipped.fn claim_next_mutation(@@ -200,6 +232,18 @@ impl Storage for InMemoryStorage {.collect())}+ async fn queue_diagnostics(&self) -> Result<QueueDiagnostics, Self::Error> {+ Ok(QueueDiagnostics {+ availability: QueueDiagnosticsAvailability::Available,+ depth: self.mutations.len() as u64,+ oldest_created_at_ms: self+ .mutations+ .values()+ .map(|(mutation, _)| mutation.created_at_ms)+ .min(),+ })+ }+async fn claim_next_mutation(&mut self,request: MutationClaimRequest,diff --git a/crates/client/cache-core/tests/engine.rs b/crates/client/cache-core/tests/engine.rsindex f36c58fb79..2ce86e0c99 100644--- a/crates/client/cache-core/tests/engine.rs+++ b/crates/client/cache-core/tests/engine.rs@@ -95,6 +95,13 @@ fn page_for_user(user: &str, names: &[(&str, &str)]) -> Json {})}+#[test]+fn consuming_engine_returns_exclusively_owned_storage() {+ let engine = Engine::new(InMemoryStorage::new());+ let storage: InMemoryStorage = engine.into_storage();+ assert!(storage.is_empty());+}+#[test]fn miss_then_write_then_hit() {block_on(async {diff --git a/crates/client/cache-core/tests/mutation_queue.rs b/crates/client/cache-core/tests/mutation_queue.rsindex ba9e696108..82d3ee4757 100644--- a/crates/client/cache-core/tests/mutation_queue.rs+++ b/crates/client/cache-core/tests/mutation_queue.rs@@ -54,6 +54,64 @@ fn queued(value: &str, created_at_ms: i64) -> NewQueuedMutation {}}+#[test]+fn queue_diagnostics_are_payload_free_and_track_oldest() {+ block_on(async {+ let mut storage = InMemoryStorage::new();+ assert_eq!(+ storage.queue_diagnostics().await.unwrap(),+ cache_core::store::QueueDiagnostics {+ availability: cache_core::store::QueueDiagnosticsAvailability::Available,+ depth: 0,+ oldest_created_at_ms: None,+ }+ );+ let first = storage+ .enqueue_mutation(queued("secret-a", 42))+ .await+ .unwrap();+ storage+ .enqueue_mutation(queued("secret-b", 21))+ .await+ .unwrap();+ assert_eq!(+ storage.queue_diagnostics().await.unwrap(),+ cache_core::store::QueueDiagnostics {+ availability: cache_core::store::QueueDiagnosticsAvailability::Available,+ depth: 2,+ oldest_created_at_ms: Some(21),+ }+ );+ let claimed = storage+ .claim_next_mutation(MutationClaimRequest {+ owner: "runner".into(),+ now_ms: 100,+ lease_expires_at_ms: 200,+ })+ .await+ .unwrap()+ .unwrap();+ storage+ .discard_mutation(+ first,+ MutationClaimToken {+ owner: "runner".into(),+ generation: claimed.lease_generation,+ },+ )+ .await+ .unwrap();+ assert_eq!(+ storage.queue_diagnostics().await.unwrap(),+ cache_core::store::QueueDiagnostics {+ availability: cache_core::store::QueueDiagnosticsAvailability::Available,+ depth: 1,+ oldest_created_at_ms: Some(21),+ }+ );+ });+}+#[test]fn queue_claim_retry_and_settlement_are_ordered() {block_on(async {diff --git a/crates/client/cache-core/tests/optimistic.rs b/crates/client/cache-core/tests/optimistic.rsindex 0d9f335c18..f836816d83 100644--- a/crates/client/cache-core/tests/optimistic.rs+++ b/crates/client/cache-core/tests/optimistic.rs@@ -475,7 +475,13 @@ fn enqueue_does_not_skip_a_leased_or_deferred_head() {#[test]fn claim_failure_after_enqueue_preserves_one_durable_visible_mutation() {block_on(async {- let mut engine = Engine::new(ClaimFailingStorage::new());+ let compatibility_storage = ClaimFailingStorage::new();+ assert_eq!(+ compatibility_storage.queue_diagnostics().await.unwrap(),+ cache_core::store::QueueDiagnostics::default(),+ "the compatibility default must be explicitly unavailable"+ );+ let mut engine = Engine::new(compatibility_storage);engine.write_query(None,diff --git a/crates/client/cache-idb/Cargo.toml b/crates/client/cache-idb/Cargo.tomldeleted file mode 100644index fc7fb90ba6..0000000000--- a/crates/client/cache-idb/Cargo.toml+++ /dev/null@@ -1,27 +0,0 @@-[package]-edition = "2024"-name = "cache-idb"-publish = false-version = "0.1.0"--# wasm32-only implementation; the crate compiles to an empty shell on other-# targets so plain `cargo test` at the workspace root stays green.--[dependencies]-cache-core = { path = "../cache-core" }-thiserror = { workspace = true }--[target.'cfg(target_arch = "wasm32")'.dependencies]-idb = "0.6"-js-sys = "0.3"-wasm-bindgen = "0.2"-web-sys = { version = "0.3", features = [- "Event",- "EventTarget",- "IdbDatabase",- "console",-] }--[target.'cfg(target_arch = "wasm32")'.dev-dependencies]-serde_json = { workspace = true }-wasm-bindgen-test = "0.3"diff --git a/crates/client/cache-idb/src/idb_storage.rs b/crates/client/cache-idb/src/idb_storage.rsdeleted file mode 100644index b631f50d32..0000000000--- a/crates/client/cache-idb/src/idb_storage.rs+++ /dev/null@@ -1,545 +0,0 @@-use cache_core::codec::{- CodecError, cache_database_name, cache_namespace, decode_optimistic_layer, decode_record,- decode_stored_mutation, encode_optimistic_layer, encode_record, encode_stored_mutation,-};-use cache_core::queue::{- ClaimedMutation, MutationClaimRequest, MutationClaimToken, MutationId, NewQueuedMutation,- QueuedMutation,-};-use cache_core::store::Storage;-use cache_core::value::{EntityKey, Record};-use idb::{- CursorDirection, Database, DatabaseEvent, Factory, KeyRange, ObjectStoreParams, Query,- TransactionMode,-};-use thiserror::Error;-use wasm_bindgen::{JsCast, JsValue};--const META_STORE: &str = "meta";-const RECORDS_STORE: &str = "records";-const MUTATION_QUEUE_STORE: &str = "mutation_queue";-const OPTIMISTIC_LAYERS_STORE: &str = "optimistic_layers";-const DB_VERSION: u32 = 1;-const SCOPE_META_KEY: &str = "scope";-const NAMESPACE_META_KEY: &str = "namespace";--#[derive(Debug, Error)]-pub enum IdbStorageError {- #[error("indexeddb: {0}")]- Idb(#[from] idb::Error),- #[error(transparent)]- Codec(#[from] CodecError),- #[error("stored value is not a Uint8Array")]- NotBytes,- #[error("stored metadata is not a string")]- NotString,- #[error("mutation queue key is not a safe positive integer")]- InvalidMutationId,- #[error("mutation queue and optimistic layer stores are inconsistent")]- InconsistentQueue,-}--pub struct IdbStorage {- db: Database,-}--fn bytes_to_js(bytes: &[u8]) -> JsValue {- js_sys::Uint8Array::from(bytes).into()-}--fn bytes_from_js(value: JsValue) -> Result<Vec<u8>, IdbStorageError> {- let bytes: js_sys::Uint8Array = value.dyn_into().map_err(|_| IdbStorageError::NotBytes)?;- Ok(bytes.to_vec())-}--fn mutation_id_from_js(value: &JsValue) -> Result<MutationId, IdbStorageError> {- const MAX_SAFE_INTEGER: f64 = 9_007_199_254_740_991.0;- let Some(number) = value.as_f64() else {- return Err(IdbStorageError::InvalidMutationId);- };- if !(1.0..=MAX_SAFE_INTEGER).contains(&number) || number.fract() != 0.0 {- return Err(IdbStorageError::InvalidMutationId);- }- Ok(number as MutationId)-}--fn mutation_id_to_js(id: MutationId) -> Result<JsValue, IdbStorageError> {- const MAX_SAFE_INTEGER: MutationId = 9_007_199_254_740_991;- if id == 0 || id > MAX_SAFE_INTEGER {- return Err(IdbStorageError::InvalidMutationId);- }- Ok(JsValue::from_f64(id as f64))-}--fn claim_matches(mutation: &cache_core::queue::StoredMutation, claim: &MutationClaimToken) -> bool {- mutation.lease_owner.as_deref() == Some(&claim.owner)- && mutation.lease_generation == claim.generation-}--impl IdbStorage {- /// Opens the cache database for `scope` and initializes all stores.- /// Compatibility-epoch or cache-format changes clear only disposable- /// records; a scope change also clears queued user intent.- pub async fn open(scope: &str) -> Result<Self, IdbStorageError> {- let name = cache_database_name(scope);- let factory = Factory::new()?;- let mut request = factory.open(&name, Some(DB_VERSION))?;- request.on_upgrade_needed(|event| {- let database = event.database().expect("upgrade event has database");- let existing = database.store_names();- for (name, params) in [- (META_STORE, ObjectStoreParams::new()),- (RECORDS_STORE, ObjectStoreParams::new()),- (MUTATION_QUEUE_STORE, {- let mut params = ObjectStoreParams::new();- params.auto_increment(true);- params- }),- (OPTIMISTIC_LAYERS_STORE, ObjectStoreParams::new()),- ] {- if !existing.iter().any(|store| store == name) {- database- .create_object_store(name, params)- .unwrap_or_else(|_| panic!("create {name} object store"));- }- }- });- let mut db = request.await?;- // Close immediately when another context needs this database gone or- // upgraded (delete/upgrade requests block while connections are- // open); without this, `destroy` from another tab can hang forever.- db.on_version_change(|event: web_sys::Event| {- if let Some(target) = event.target()- && let Ok(db) = wasm_bindgen::JsCast::dyn_into::<web_sys::IdbDatabase>(target)- {- db.close();- }- });- let mut storage = IdbStorage { db };- storage.initialize_namespace(scope).await?;- Ok(storage)- }-- async fn initialize_namespace(&mut self, scope: &str) -> Result<(), IdbStorageError> {- let tx = self.db.transaction(- &[- META_STORE,- RECORDS_STORE,- MUTATION_QUEUE_STORE,- OPTIMISTIC_LAYERS_STORE,- ],- TransactionMode::ReadWrite,- )?;- let meta = tx.object_store(META_STORE)?;- let scope_request = meta.get(JsValue::from_str(SCOPE_META_KEY))?;- let namespace_request = meta.get(JsValue::from_str(NAMESPACE_META_KEY))?;- let stored_scope = scope_request- .await?- .map(|value| value.as_string().ok_or(IdbStorageError::NotString))- .transpose()?;- let stored_namespace = namespace_request- .await?- .map(|value| value.as_string().ok_or(IdbStorageError::NotString))- .transpose()?;- let expected_namespace = cache_namespace(scope);-- if stored_scope.as_deref() != Some(scope) {- tx.object_store(OPTIMISTIC_LAYERS_STORE)?.clear()?;- tx.object_store(MUTATION_QUEUE_STORE)?.clear()?;- tx.object_store(RECORDS_STORE)?.clear()?;- } else if stored_namespace.as_deref() != Some(expected_namespace.as_str()) {- tx.object_store(RECORDS_STORE)?.clear()?;- }- meta.put(- &JsValue::from_str(scope),- Some(&JsValue::from_str(SCOPE_META_KEY)),- )?;- meta.put(- &JsValue::from_str(&expected_namespace),- Some(&JsValue::from_str(NAMESPACE_META_KEY)),- )?;- tx.commit()?.await?;- Ok(())- }-- /// Deletes the database for `scope` (logout / stale-namespace cleanup).- ///- /// Connections opened by [`Self::open`] auto-close on `versionchange`,- /// so this does not block on our own live handles. A `blocked` event- /// (foreign connection without that handler) is logged for diagnosis- /// instead of hanging silently.- pub async fn destroy(scope: &str) -> Result<(), IdbStorageError> {- let factory = Factory::new()?;- let mut request = factory.delete(&cache_database_name(scope))?;- request.on_blocked(|_| {- web_sys::console::warn_1(- &"graphql-cache: database deletion blocked by an open connection".into(),- );- });- request.await?;- Ok(())- }-- /// Closes the underlying connection. Subsequent operations on this- /// storage will fail; call right before dropping/destroying.- pub fn close(&self) {- self.db.close();- }-}--impl Storage for IdbStorage {- type Error = IdbStorageError;-- async fn get_batch(&self, keys: &[EntityKey<'_>]) -> Result<Vec<Option<Record>>, Self::Error> {- let tx = self- .db- .transaction(&[RECORDS_STORE], TransactionMode::ReadOnly)?;- let store = tx.object_store(RECORDS_STORE)?;-- // Dispatch all gets first (they execute concurrently within the- // transaction), then await in order.- let mut requests = Vec::with_capacity(keys.len());- for key in keys {- requests.push(store.get(JsValue::from_str(key.0.as_ref()))?);- }- let mut out = Vec::with_capacity(keys.len());- for request in requests {- let value = request.await?;- out.push(match value {- None => None,- Some(js) => Some(decode_record(&bytes_from_js(js)?)?),- });- }- Ok(out)- }-- async fn put_batch(- &mut self,- entries: Vec<(EntityKey<'static>, Record)>,- ) -> Result<(), Self::Error> {- let tx = self- .db- .transaction(&[RECORDS_STORE], TransactionMode::ReadWrite)?;- let store = tx.object_store(RECORDS_STORE)?;- for (key, record) in &entries {- let bytes = encode_record(record);- store.put(- &bytes_to_js(&bytes),- Some(&JsValue::from_str(key.0.as_ref())),- )?;- }- // Committing the transaction is what makes the batch atomic.- tx.commit()?.await?;- Ok(())- }-- async fn delete_batch(&mut self, keys: &[EntityKey<'static>]) -> Result<(), Self::Error> {- let tx = self- .db- .transaction(&[RECORDS_STORE], TransactionMode::ReadWrite)?;- let store = tx.object_store(RECORDS_STORE)?;- for key in keys {- store.delete(JsValue::from_str(key.0.as_ref()))?;- }- tx.commit()?.await?;- Ok(())- }-- async fn scan_records(- &self,- type_names: &[String],- after: Option<&EntityKey<'static>>,- limit: usize,- ) -> Result<Vec<(EntityKey<'static>, Record)>, Self::Error> {- if type_names.is_empty() || limit == 0 {- return Ok(Vec::new());- }-- let mut type_names = type_names.to_vec();- type_names.sort();- type_names.dedup();- let mut records = Vec::with_capacity(limit);- for type_name in type_names {- if records.len() == limit {- break;- }- let prefix = format!("{type_name}:");- let upper = format!("{type_name};");- if after.is_some_and(|after| after.0.as_ref() >= upper.as_str()) {- continue;- }- let (lower, lower_open) = match after {- Some(after) if after.0.as_ref() >= prefix.as_str() => (after.0.as_ref(), true),- _ => (prefix.as_str(), false),- };- let range = KeyRange::bound(- &JsValue::from_str(lower),- &JsValue::from_str(&upper),- Some(lower_open),- Some(true),- )?;- let tx = self- .db- .transaction(&[RECORDS_STORE], TransactionMode::ReadOnly)?;- let store = tx.object_store(RECORDS_STORE)?;- let Some(cursor) = store- .open_cursor(Some(Query::from(range)), Some(CursorDirection::Next))?- .await?- else {- continue;- };- let mut cursor = cursor.into_managed();- while records.len() < limit {- let Some(key) = cursor.key()? else {- break;- };- let Some(value) = cursor.value()? else {- break;- };- let key = key.as_string().ok_or(IdbStorageError::NotString)?;- records.push((- EntityKey(key.into()),- decode_record(&bytes_from_js(value)?)?,- ));- cursor.next(None).await?;- }- }- Ok(records)- }-- async fn enqueue_mutation(- &mut self,- entry: NewQueuedMutation,- ) -> Result<MutationId, Self::Error> {- let tx = self.db.transaction(- &[MUTATION_QUEUE_STORE, OPTIMISTIC_LAYERS_STORE],- TransactionMode::ReadWrite,- )?;- let queue = tx.object_store(MUTATION_QUEUE_STORE)?;- let mutation_bytes = encode_stored_mutation(&entry.mutation);- let generated_key = queue.add(&bytes_to_js(&mutation_bytes), None)?.await?;- let id = mutation_id_from_js(&generated_key)?;- let optimistic_bytes = encode_optimistic_layer(&entry.optimistic);- tx.object_store(OPTIMISTIC_LAYERS_STORE)?- .put(&bytes_to_js(&optimistic_bytes), Some(&generated_key))?;- tx.commit()?.await?;- Ok(id)- }-- async fn load_mutation_queue(&self) -> Result<Vec<QueuedMutation>, Self::Error> {- let tx = self.db.transaction(- &[MUTATION_QUEUE_STORE, OPTIMISTIC_LAYERS_STORE],- TransactionMode::ReadOnly,- )?;- let queue = tx.object_store(MUTATION_QUEUE_STORE)?;- let optimistic = tx.object_store(OPTIMISTIC_LAYERS_STORE)?;- let queue_keys_request = queue.get_all_keys(None, None)?;- let queue_values_request = queue.get_all(None, None)?;- let optimistic_keys_request = optimistic.get_all_keys(None, None)?;- let optimistic_values_request = optimistic.get_all(None, None)?;-- let queue_keys = queue_keys_request.await?;- let queue_values = queue_values_request.await?;- let optimistic_keys = optimistic_keys_request.await?;- let optimistic_values = optimistic_values_request.await?;- if queue_keys.len() != queue_values.len()- || queue_keys.len() != optimistic_keys.len()- || queue_keys.len() != optimistic_values.len()- {- return Err(IdbStorageError::InconsistentQueue);- }-- let mut out = Vec::with_capacity(queue_keys.len());- for (((queue_key, mutation), optimistic_key), layer) in queue_keys- .into_iter()- .zip(queue_values)- .zip(optimistic_keys)- .zip(optimistic_values)- {- let id = mutation_id_from_js(&queue_key)?;- if mutation_id_from_js(&optimistic_key)? != id {- return Err(IdbStorageError::InconsistentQueue);- }- out.push(QueuedMutation {- id,- mutation: decode_stored_mutation(&bytes_from_js(mutation)?)?,- optimistic: decode_optimistic_layer(&bytes_from_js(layer)?)?,- });- }- Ok(out)- }-- async fn claim_next_mutation(- &mut self,- request: MutationClaimRequest,- ) -> Result<Option<ClaimedMutation>, Self::Error> {- let tx = self.db.transaction(- &[MUTATION_QUEUE_STORE, OPTIMISTIC_LAYERS_STORE],- TransactionMode::ReadWrite,- )?;- let queue = tx.object_store(MUTATION_QUEUE_STORE)?;- let optimistic = tx.object_store(OPTIMISTIC_LAYERS_STORE)?;- let queue_keys_request = queue.get_all_keys(None, Some(1))?;- let queue_values_request = queue.get_all(None, Some(1))?;- let optimistic_keys_request = optimistic.get_all_keys(None, Some(1))?;- let optimistic_values_request = optimistic.get_all(None, Some(1))?;- let queue_keys = queue_keys_request.await?;- let queue_values = queue_values_request.await?;- let optimistic_keys = optimistic_keys_request.await?;- let optimistic_values = optimistic_values_request.await?;-- if queue_keys.is_empty() {- if !queue_values.is_empty()- || !optimistic_keys.is_empty()- || !optimistic_values.is_empty()- {- return Err(IdbStorageError::InconsistentQueue);- }- tx.commit()?.await?;- return Ok(None);- }- if queue_keys.len() != 1- || queue_values.len() != 1- || optimistic_keys.len() != 1- || optimistic_values.len() != 1- {- return Err(IdbStorageError::InconsistentQueue);- }- let key = &queue_keys[0];- let id = mutation_id_from_js(key)?;- if mutation_id_from_js(&optimistic_keys[0])? != id {- return Err(IdbStorageError::InconsistentQueue);- }- let mut mutation = decode_stored_mutation(&bytes_from_js(queue_values[0].clone())?)?;- if mutation- .next_attempt_at_ms- .is_some_and(|next| next > request.now_ms)- || mutation- .lease_expires_at_ms- .is_some_and(|expiry| expiry > request.now_ms)- {- tx.commit()?.await?;- return Ok(None);- }-- mutation.attempt_count = mutation.attempt_count.saturating_add(1);- mutation.lease_generation = mutation.lease_generation.saturating_add(1);- mutation.lease_owner = Some(request.owner);- mutation.lease_expires_at_ms = Some(request.lease_expires_at_ms);- mutation.next_attempt_at_ms = None;- let generation = mutation.lease_generation;- queue.put(&bytes_to_js(&encode_stored_mutation(&mutation)), Some(key))?;- let layer = decode_optimistic_layer(&bytes_from_js(optimistic_values[0].clone())?)?;- tx.commit()?.await?;- Ok(Some(ClaimedMutation {- queued: QueuedMutation {- id,- mutation,- optimistic: layer,- },- lease_generation: generation,- }))- }-- async fn defer_mutation(- &mut self,- id: MutationId,- claim: MutationClaimToken,- next_attempt_at_ms: i64,- error: String,- ) -> Result<bool, Self::Error> {- let key = mutation_id_to_js(id)?;- let tx = self- .db- .transaction(&[MUTATION_QUEUE_STORE], TransactionMode::ReadWrite)?;- let queue = tx.object_store(MUTATION_QUEUE_STORE)?;- let Some(value) = queue.get(key.clone())?.await? else {- tx.commit()?.await?;- return Ok(false);- };- let mut mutation = decode_stored_mutation(&bytes_from_js(value)?)?;- if !claim_matches(&mutation, &claim) {- tx.commit()?.await?;- return Ok(false);- }- mutation.next_attempt_at_ms = Some(next_attempt_at_ms);- mutation.last_error = Some(error);- mutation.lease_owner = None;- mutation.lease_expires_at_ms = None;- queue.put(&bytes_to_js(&encode_stored_mutation(&mutation)), Some(&key))?;- tx.commit()?.await?;- Ok(true)- }-- async fn complete_mutation(- &mut self,- id: MutationId,- claim: MutationClaimToken,- entries: Vec<(EntityKey<'static>, Record)>,- ) -> Result<bool, Self::Error> {- let key = mutation_id_to_js(id)?;- let tx = self.db.transaction(- &[RECORDS_STORE, MUTATION_QUEUE_STORE, OPTIMISTIC_LAYERS_STORE],- TransactionMode::ReadWrite,- )?;- let queue = tx.object_store(MUTATION_QUEUE_STORE)?;- let Some(value) = queue.get(key.clone())?.await? else {- tx.commit()?.await?;- return Ok(false);- };- let mutation = decode_stored_mutation(&bytes_from_js(value)?)?;- if !claim_matches(&mutation, &claim) {- tx.commit()?.await?;- return Ok(false);- }- let records = tx.object_store(RECORDS_STORE)?;- for (record_key, record) in &entries {- records.put(- &bytes_to_js(&encode_record(record)),- Some(&JsValue::from_str(record_key.0.as_ref())),- )?;- }- queue.delete(key.clone())?;- tx.object_store(OPTIMISTIC_LAYERS_STORE)?.delete(key)?;- tx.commit()?.await?;- Ok(true)- }-- async fn discard_mutation(- &mut self,- id: MutationId,- claim: MutationClaimToken,- ) -> Result<bool, Self::Error> {- let key = mutation_id_to_js(id)?;- let tx = self.db.transaction(- &[MUTATION_QUEUE_STORE, OPTIMISTIC_LAYERS_STORE],- TransactionMode::ReadWrite,- )?;- let queue = tx.object_store(MUTATION_QUEUE_STORE)?;- let Some(value) = queue.get(key.clone())?.await? else {- tx.commit()?.await?;- return Ok(false);- };- let mutation = decode_stored_mutation(&bytes_from_js(value)?)?;- if !claim_matches(&mutation, &claim) {- tx.commit()?.await?;- return Ok(false);- }- queue.delete(key.clone())?;- tx.object_store(OPTIMISTIC_LAYERS_STORE)?.delete(key)?;- tx.commit()?.await?;- Ok(true)- }-- async fn clear(&mut self) -> Result<(), Self::Error> {- let tx = self.db.transaction(- &[RECORDS_STORE, MUTATION_QUEUE_STORE, OPTIMISTIC_LAYERS_STORE],- TransactionMode::ReadWrite,- )?;- tx.object_store(OPTIMISTIC_LAYERS_STORE)?.clear()?;- tx.object_store(MUTATION_QUEUE_STORE)?.clear()?;- tx.object_store(RECORDS_STORE)?.clear()?;- tx.commit()?.await?;- Ok(())- }-}diff --git a/crates/client/cache-idb/src/lib.rs b/crates/client/cache-idb/src/lib.rsdeleted file mode 100644index f652989e74..0000000000--- a/crates/client/cache-idb/src/lib.rs+++ /dev/null@@ -1,18 +0,0 @@-//! IndexedDB [`Storage`](cache_core::store::Storage) backend for the browser-//! host (wasm module in a SharedWorker / dedicated worker).-//!-//! One stable IndexedDB database per cache scope. Disposable normalized-//! records are versioned by schema compatibility epoch and cache format,-//! while queued mutations and their optimistic layers remain discoverable-//! across incompatible record-schema changes.-//! Postcard payloads are stored in indexable record envelopes whose `value`-//! property is a `Uint8Array`.-//!-//! wasm32-only; on other targets this crate is an empty shell so workspace-//! `cargo test` stays green.--#[cfg(target_arch = "wasm32")]-mod idb_storage;--#[cfg(target_arch = "wasm32")]-pub use idb_storage::{IdbStorage, IdbStorageError};diff --git a/crates/client/cache-idb/tests/web.rs b/crates/client/cache-idb/tests/web.rsdeleted file mode 100644index e728fedc54..0000000000--- a/crates/client/cache-idb/tests/web.rs+++ /dev/null@@ -1,205 +0,0 @@-//! Browser tests for the IndexedDB backend. Run with:-//! `wasm-pack test --headless --chrome cache-idb`-//! (or `--firefox`). Not part of native `cargo test`.--#![cfg(target_arch = "wasm32")]--use cache_core::engine::{Engine, ReadResult};-use cache_core::queue::{- MutationClaimRequest, MutationClaimToken, MutationRequest, NewQueuedMutation,- PersistedOptimisticLayer, StoredMutation,-};-use cache_core::record_selection::RecordSelection;-use cache_core::store::Storage;-use cache_core::value::{CacheValue, EntityKey, Record};-use cache_idb::IdbStorage;-use wasm_bindgen_test::*;--wasm_bindgen_test_configure!(run_in_browser);--fn record(name: &str) -> Record {- let mut r = Record::default();- r.fields- .insert("name".into(), CacheValue::String(name.into()));- r-}--fn key(s: &str) -> EntityKey<'static> {- EntityKey(s.to_string().into())-}--fn queued(name: &str) -> NewQueuedMutation {- NewQueuedMutation {- mutation: StoredMutation::new(- MutationRequest {- query: "mutation Rename { rename { id } }".into(),- operation_name: Some("Rename".into()),- variables_json: format!(r#"{{"name":"{name}"}}"#),- identity: Some("user-1".into()),- },- 10,- ),- optimistic: PersistedOptimisticLayer {- optimistic_data_json: format!(r#"{{"rename":{{"name":"{name}"}}}}"#),- normalized_updates: [(key("A:1"), record(name))].into(),- },- }-}--#[wasm_bindgen_test]-async fn put_get_delete_roundtrip() {- IdbStorage::destroy("test-rt").await.unwrap();- let mut s = IdbStorage::open("test-rt").await.unwrap();-- s.put_batch(vec![(key("A:1"), record("a")), (key("B:2"), record("b"))])- .await- .unwrap();-- let got = s- .get_batch(&[key("A:1"), key("C:3"), key("B:2")])- .await- .unwrap();- assert_eq!(got[0].as_ref().unwrap(), &record("a"));- assert!(got[1].is_none());- assert_eq!(got[2].as_ref().unwrap(), &record("b"));-- s.put_batch(vec![(key("A:1"), record("a2"))]).await.unwrap();- let got = s.get_batch(&[key("A:1")]).await.unwrap();- assert_eq!(got[0].as_ref().unwrap(), &record("a2"));-- s.delete_batch(&[key("A:1")]).await.unwrap();- assert!(s.get_batch(&[key("A:1")]).await.unwrap()[0].is_none());-- s.clear().await.unwrap();- assert!(s.get_batch(&[key("B:2")]).await.unwrap()[0].is_none());-}--#[wasm_bindgen_test]-async fn scans_selected_record_types_in_key_order() {- let scope = "test-record-scan";- IdbStorage::destroy(scope).await.unwrap();- let mut storage = IdbStorage::open(scope).await.unwrap();- storage- .put_batch(vec![- (key("TypeB:2"), record("b2")),- (key("Other:1"), record("other")),- (key("TypeA:2"), record("a2")),- (key("TypeA:1"), record("a1")),- ])- .await- .unwrap();-- let first = storage- .scan_records(&["TypeB".into(), "TypeA".into()], None, 2)- .await- .unwrap();- assert_eq!(- first- .iter()- .map(|(key, _)| key.0.as_ref())- .collect::<Vec<_>>(),- vec!["TypeA:1", "TypeA:2"]- );- let second = storage- .scan_records(&["TypeA".into(), "TypeB".into()], Some(&first[1].0), 2)- .await- .unwrap();- assert_eq!(- second- .iter()- .map(|(key, _)| key.0.as_ref())- .collect::<Vec<_>>(),- vec!["TypeB:2"]- );-}--#[wasm_bindgen_test]-async fn persists_across_reopen() {- IdbStorage::destroy("test-persist").await.unwrap();- let mut s = IdbStorage::open("test-persist").await.unwrap();- s.put_batch(vec![(key("A:1"), record("a"))]).await.unwrap();- s.close();-- let s = IdbStorage::open("test-persist").await.unwrap();- let got = s.get_batch(&[key("A:1")]).await.unwrap();- assert_eq!(got[0].as_ref().unwrap(), &record("a"));-}--#[wasm_bindgen_test]-async fn mutation_queue_persists_and_settles_atomically() {- IdbStorage::destroy("test-queue").await.unwrap();- let mut storage = IdbStorage::open("test-queue").await.unwrap();- let id = storage- .enqueue_mutation(queued("optimistic"))- .await- .unwrap();- storage.close();-- let mut storage = IdbStorage::open("test-queue").await.unwrap();- let loaded = storage.load_mutation_queue().await.unwrap();- assert_eq!(loaded.len(), 1);- assert_eq!(loaded[0].id, id);- let claimed = storage- .claim_next_mutation(MutationClaimRequest {- owner: "runner".into(),- now_ms: 20,- lease_expires_at_ms: 100,- })- .await- .unwrap()- .unwrap();- assert!(- storage- .complete_mutation(- id,- MutationClaimToken {- owner: "runner".into(),- generation: claimed.lease_generation,- },- vec![(key("A:1"), record("server"))],- )- .await- .unwrap()- );- assert!(storage.load_mutation_queue().await.unwrap().is_empty());- assert_eq!(- storage.get_batch(&[key("A:1")]).await.unwrap()[0],- Some(record("server"))- );-}--#[wasm_bindgen_test]-async fn engine_over_idb() {- IdbStorage::destroy("test-engine").await.unwrap();- let storage = IdbStorage::open("test-engine").await.unwrap();- let mut engine = Engine::new(storage);-- let query = r#"query Soup($input: SoupInput!) {- user { id soup(input: $input) { nextCursor items { __typename id } } }- }"#;- let serde_json::Value::Object(vars) = serde_json::json!({"input": {"limit": 1}}) else {- unreachable!()- };- let data = serde_json::json!({- "user": { "id": "user-1", "soup": { "nextCursor": null, "items": [{"__typename": "GraphqlSoupDocument", "id": "doc-1"}] } }- });-- engine- .write_query(None, query, Some("Soup"), &vars, &data, None)- .await- .unwrap();- let ReadResult::Hit { data: cached } = engine- .read_query(None, query, Some("Soup"), &vars)- .await- .unwrap()- else {- panic!("expected hit");- };- assert_eq!(cached, data);-- let selection =- RecordSelection::parse("fragment Item on GraphqlSoupDocument { id }", "Item").unwrap();- let page = engine.read_records(&selection, None, 10).await.unwrap();- assert_eq!(page.records, vec![serde_json::json!({"id": "doc-1"})]);- assert!(page.next_cursor.is_none());-}diff --git a/crates/client/cache-sqlite/Cargo.toml b/crates/client/cache-sqlite/Cargo.tomlindex eb622ac86f..5f3ed89f1d 100644--- a/crates/client/cache-sqlite/Cargo.toml+++ b/crates/client/cache-sqlite/Cargo.toml@@ -12,6 +12,6 @@ rusqlite = { version = "0.32", features = ["bundled"] }thiserror = { workspace = true }[dev-dependencies]-pollster = "0.4"+pollster = { workspace = true }serde_json = { workspace = true }tempfile = "3"diff --git a/crates/client/cache-sqlite/src/lib.rs b/crates/client/cache-sqlite/src/lib.rsindex eca2898c30..bfc49d5e90 100644--- a/crates/client/cache-sqlite/src/lib.rs+++ b/crates/client/cache-sqlite/src/lib.rs@@ -20,7 +20,7 @@ use cache_core::queue::{ClaimedMutation, MutationClaimRequest, MutationClaimToken, MutationId, MutationRequest,NewQueuedMutation, PersistedOptimisticLayer, QueuedMutation, StoredMutation,};-use cache_core::store::Storage;+use cache_core::store::{QueueDiagnostics, QueueDiagnosticsAvailability, Storage};use cache_core::value::{EntityKey, Record};use rusqlite::{Connection, OptionalExtension, Transaction, params, params_from_iter};use std::path::Path;@@ -89,6 +89,8 @@ impl SqliteStorage {last_error TEXT,created_at_ms INTEGER NOT NULL);+ CREATE INDEX IF NOT EXISTS mutation_queue_created_at_ms_idx+ ON mutation_queue(created_at_ms);CREATE TABLE IF NOT EXISTS optimistic_layers (mutation_id INTEGER PRIMARY KEY,optimistic_data_json TEXT NOT NULL,@@ -388,6 +390,27 @@ impl Storage for SqliteStorage {Ok(out)}+ async fn queue_diagnostics(&self) -> Result<QueueDiagnostics, Self::Error> {+ let (depth, oldest_created_at_ms): (i64, Option<i64>) = self.conn().query_row(+ "SELECT COUNT(*), MIN(created_at_ms) FROM mutation_queue",+ [],+ |row| Ok((row.get(0)?, row.get(1)?)),+ )?;+ let depth = u64::try_from(depth).map_err(|_| {+ SqliteStorageError::QueueInvariant("negative mutation queue depth".to_string())+ })?;+ if (depth == 0) != oldest_created_at_ms.is_none() {+ return Err(SqliteStorageError::QueueInvariant(+ "queue depth and oldest timestamp disagree".to_string(),+ ));+ }+ Ok(QueueDiagnostics {+ availability: QueueDiagnosticsAvailability::Available,+ depth,+ oldest_created_at_ms,+ })+ }+async fn claim_next_mutation(&mut self,request: MutationClaimRequest,@@ -598,6 +621,75 @@ mod tests {});}+ #[test]+ fn queue_diagnostics_return_only_depth_and_oldest_timestamp() {+ block_on(async {+ let storage = SqliteStorage::open_in_memory("user-1").unwrap();+ assert_eq!(+ storage.queue_diagnostics().await.unwrap(),+ QueueDiagnostics {+ availability: QueueDiagnosticsAvailability::Available,+ depth: 0,+ oldest_created_at_ms: None,+ }+ );+ storage+ .conn()+ .execute(+ "INSERT INTO mutation_queue (query, variables_json, created_at_ms) VALUES ('mutation A { a }', '{}', 9), ('mutation B { b }', '{}', 4)",+ [],+ )+ .unwrap();+ assert_eq!(+ storage.queue_diagnostics().await.unwrap(),+ QueueDiagnostics {+ availability: QueueDiagnosticsAvailability::Available,+ depth: 2,+ oldest_created_at_ms: Some(4),+ }+ );+ });+ }++ #[test]+ fn queue_diagnostics_query_uses_covering_index_at_scale() {+ block_on(async {+ let storage = SqliteStorage::open_in_memory("queue-plan").unwrap();+ storage+ .conn()+ .execute(+ "WITH RECURSIVE values_to_insert(value) AS (VALUES(1) UNION ALL SELECT value + 1 FROM values_to_insert WHERE value < 10000) INSERT INTO mutation_queue (query, variables_json, created_at_ms) SELECT 'mutation Scale { scale }', '{}', 10001 - value FROM values_to_insert",+ [],+ )+ .unwrap();+ let details = {+ let conn = storage.conn();+ let mut plan = conn+ .prepare(+ "EXPLAIN QUERY PLAN SELECT COUNT(*), MIN(created_at_ms) FROM mutation_queue",+ )+ .unwrap();+ plan.query_map([], |row| row.get::<_, String>(3))+ .unwrap()+ .collect::<Result<Vec<_>, _>>()+ .unwrap()+ .join(" ")+ };+ assert!(+ details.contains("mutation_queue_created_at_ms_idx"),+ "diagnostics query did not use the timestamp index: {details}"+ );+ assert_eq!(+ storage.queue_diagnostics().await.unwrap(),+ QueueDiagnostics {+ availability: QueueDiagnosticsAvailability::Available,+ depth: 10_000,+ oldest_created_at_ms: Some(1),+ }+ );+ });+ }+#[test]fn scans_selected_record_types_in_key_order() {block_on(async {diff --git a/crates/client/cache-turso/Cargo.toml b/crates/client/cache-turso/Cargo.tomlnew file mode 100644index 0000000000..9d6888af4a--- /dev/null+++ b/crates/client/cache-turso/Cargo.toml@@ -0,0 +1,31 @@+[package]+edition = "2024"+name = "cache-turso"+publish = false+version = "0.1.0"++[features]+default = []+browser-test-hooks = []++[dependencies]+cache-core = { path = "../cache-core" }+maybe_send = { path = "../../maybe_send" }+thiserror = { workspace = true }++[target.'cfg(target_arch = "wasm32")'.dependencies]+turso-opfs = { path = "../turso-opfs" }+turso_core = { workspace = true, features = ["fs", "pure-rust-crypto", "uuid"] }++[target.'cfg(not(target_arch = "wasm32"))'.dependencies]+turso_core = { workspace = true, features = ["fs", "pure-rust-crypto", "uuid"] }++[dev-dependencies]+pollster = { workspace = true }+serde_json = { workspace = true }++[target.'cfg(not(target_arch = "wasm32"))'.dev-dependencies]+cache-sqlite = { path = "../cache-sqlite" }++[target.'cfg(target_arch = "wasm32")'.dev-dependencies]+wasm-bindgen-test = { workspace = true }diff --git a/crates/client/cache-turso/src/driver.rs b/crates/client/cache-turso/src/driver.rsnew file mode 100644index 0000000000..3c621b9efa--- /dev/null+++ b/crates/client/cache-turso/src/driver.rs@@ -0,0 +1,324 @@+use crate::{PhysicalResetReason, TursoStorageError};+use std::num::NonZeroUsize;+use std::sync::Arc;+use turso_core::{Connection, LimboError, Statement, StepResult, Value};++pub(crate) type Values = Vec<Value>;+pub(crate) type Rows = Vec<Values>;++struct RunFailure {+ error: TursoStorageError,+ execution_completed: bool,+ cleanup_failed: bool,+}++impl RunFailure {+ fn execution(error: TursoStorageError) -> Self {+ Self {+ error,+ execution_completed: false,+ cleanup_failed: false,+ }+ }++ fn cleanup(execution_completed: bool) -> Self {+ Self {+ error: TursoStorageError::reset(PhysicalResetReason::TransactionOutcomeUncertain),+ execution_completed,+ cleanup_failed: true,+ }+ }+}++pub(crate) fn prepare(+ connection: &Arc<Connection>,+ sql: &str,+) -> Result<Statement, TursoStorageError> {+ connection.prepare(sql).map_err(TursoStorageError::turso)+}++pub(crate) fn validate(connection: &Arc<Connection>, sql: &str) -> Result<(), TursoStorageError> {+ let mut statement = prepare(connection, sql)?;+ checked_reset(&mut statement)?;+ statement.clear_bindings();+ Ok(())+}++pub(crate) fn execute(+ connection: &Arc<Connection>,+ sql: &str,+ values: Values,+) -> Result<i64, TursoStorageError> {+ let mut statement = prepare(connection, sql)?;+ execute_prepared(&mut statement, values)+}++pub(crate) fn query(+ connection: &Arc<Connection>,+ sql: &str,+ values: Values,+) -> Result<Rows, TursoStorageError> {+ let mut statement = prepare(connection, sql)?;+ query_prepared(&mut statement, values)+}++pub(crate) fn execute_prepared(+ statement: &mut Statement,+ values: Values,+) -> Result<i64, TursoStorageError> {+ execute_prepared_detailed(statement, values).map_err(|failure| failure.error)+}++fn execute_prepared_detailed(statement: &mut Statement, values: Values) -> Result<i64, RunFailure> {+ let (rows, changed) = run_prepared(statement, values)?;+ if rows.is_empty() {+ Ok(changed)+ } else {+ Err(RunFailure::execution(TursoStorageError::Database))+ }+}++pub(crate) fn query_prepared(+ statement: &mut Statement,+ values: Values,+) -> Result<Rows, TursoStorageError> {+ run_prepared(statement, values)+ .map(|(rows, _)| rows)+ .map_err(|failure| failure.error)+}++fn run_prepared(statement: &mut Statement, values: Values) -> Result<(Rows, i64), RunFailure> {+ let execution = (|| {+ if statement.parameters_count() != values.len() {+ return Err(TursoStorageError::Database);+ }+ for (offset, value) in values.into_iter().enumerate() {+ let index = NonZeroUsize::new(offset + 1).ok_or(TursoStorageError::Database)?;+ statement+ .bind_at(index, value)+ .map_err(TursoStorageError::turso)?;+ }++ let mut rows = Vec::new();+ loop {+ // The pinned Turso revision completes this rollback without+ // producing rollback-owned File work. Native fault tests use this+ // private scheduler hook to exercise a failure from the rollback's+ // StepResult::IO/IO::step polling boundary without manufacturing a+ // completion or describing a post-success error as completion-delivered.+ #[cfg(all(test, not(target_arch = "wasm32")))]+ let forced_control_io = take_forced_control_io();+ #[cfg(any(not(test), target_arch = "wasm32"))]+ let forced_control_io = false;+ let step = if forced_control_io {+ StepResult::IO+ } else {+ statement.step().map_err(TursoStorageError::turso)?+ };+ match step {+ StepResult::Done => break,+ StepResult::Row => {+ let row = statement+ .row()+ .ok_or_else(|| TursoStorageError::reset(PhysicalResetReason::Corruption))?;+ rows.push(row.get_values().cloned().collect());+ }+ StepResult::IO => {+ #[cfg(all(test, not(target_arch = "wasm32")))]+ record_control_io();+ statement._io().step().map_err(TursoStorageError::turso)?+ }+ StepResult::Yield => statement._io().step().map_err(TursoStorageError::turso)?,+ StepResult::Busy => return Err(TursoStorageError::turso(LimboError::Busy)),+ StepResult::Interrupt => {+ return Err(TursoStorageError::turso(LimboError::Interrupt));+ }+ }+ }+ Ok((rows, statement.n_change()))+ })();++ // Turso has no separate public finalize call. A checked reset releases the+ // active VM state and I/O before reuse or drop; dropping then releases the+ // prepared statement itself. Any reset failure makes that cleanup and any+ // surrounding transaction unusable, regardless of the underlying class.+ let reset = checked_reset(statement);+ statement.clear_bindings();+ match (execution, reset) {+ (Ok(value), Ok(())) => Ok(value),+ (Err(error), Ok(())) => Err(RunFailure::execution(error)),+ (execution, Err(_)) => Err(RunFailure::cleanup(execution.is_ok())),+ }+}++fn checked_reset(statement: &mut Statement) -> Result<(), TursoStorageError> {+ let reset = statement+ .reset()+ .map_err(|_| TursoStorageError::reset(PhysicalResetReason::TransactionOutcomeUncertain));+ #[cfg(all(test, not(target_arch = "wasm32")))]+ if take_reset_failure(statement.get_sql()) {+ return Err(TursoStorageError::reset(+ PhysicalResetReason::TransactionOutcomeUncertain,+ ));+ }+ reset+}++pub(crate) fn read_transaction<T>(+ connection: &Arc<Connection>,+ operation: impl FnOnce() -> Result<T, TursoStorageError>,+) -> Result<T, TursoStorageError> {+ transaction(connection, "BEGIN", operation)+}++pub(crate) fn write_transaction<T>(+ connection: &Arc<Connection>,+ operation: impl FnOnce() -> Result<T, TursoStorageError>,+) -> Result<T, TursoStorageError> {+ transaction(connection, "BEGIN IMMEDIATE", operation)+}++fn transaction<T>(+ connection: &Arc<Connection>,+ begin_sql: &str,+ operation: impl FnOnce() -> Result<T, TursoStorageError>,+) -> Result<T, TursoStorageError> {+ let begin = execute_control(connection, begin_sql, TestControlPhase::Begin);+ if let Err(failure) = begin {+ if failure.execution_completed && failure.cleanup_failed {+ let _ = execute_control(connection, "ROLLBACK", TestControlPhase::Rollback);+ }+ return Err(failure.error);+ }++ match operation() {+ Ok(value) => match execute_control(connection, "COMMIT", TestControlPhase::Commit) {+ Ok(_) => Ok(value),+ Err(_) => {+ let _ = execute_control(connection, "ROLLBACK", TestControlPhase::Rollback);+ Err(TursoStorageError::reset(+ PhysicalResetReason::TransactionOutcomeUncertain,+ ))+ }+ },+ Err(error) => match execute_control(connection, "ROLLBACK", TestControlPhase::Rollback) {+ Ok(_) => Err(error),+ Err(_) => Err(TursoStorageError::reset(+ PhysicalResetReason::TransactionOutcomeUncertain,+ )),+ },+ }+}++fn execute_control(+ connection: &Arc<Connection>,+ sql: &str,+ phase: TestControlPhase,+) -> Result<i64, RunFailure> {+ #[cfg(all(test, not(target_arch = "wasm32")))]+ record_control_phase(phase);+ #[cfg(all(test, not(target_arch = "wasm32")))]+ let _phase_guard = TestControlPhaseGuard::enter(phase);+ #[cfg(any(not(test), target_arch = "wasm32"))]+ let _ = phase;+ let mut statement = prepare(connection, sql).map_err(RunFailure::execution)?;+ execute_prepared_detailed(&mut statement, Vec::new())+}++#[derive(Clone, Copy, Debug, PartialEq, Eq)]+pub(crate) enum TestControlPhase {+ Begin,+ Commit,+ Rollback,+}++#[cfg(all(test, not(target_arch = "wasm32")))]+thread_local! {+ static RESET_FAILURE_SQL: std::cell::RefCell<Option<String>> = const { std::cell::RefCell::new(None) };+ static CURRENT_CONTROL_PHASE: std::cell::Cell<Option<TestControlPhase>> = const { std::cell::Cell::new(None) };+ static CONTROL_TRACE: std::cell::RefCell<Vec<TestControlPhase>> = const { std::cell::RefCell::new(Vec::new()) };+ static CONTROL_IO_TRACE: std::cell::RefCell<Vec<TestControlPhase>> = const { std::cell::RefCell::new(Vec::new()) };+ static FORCE_CONTROL_IO: std::cell::Cell<bool> = const { std::cell::Cell::new(false) };+}++#[cfg(all(test, not(target_arch = "wasm32")))]+struct TestControlPhaseGuard {+ previous: Option<TestControlPhase>,+}++#[cfg(all(test, not(target_arch = "wasm32")))]+impl TestControlPhaseGuard {+ fn enter(phase: TestControlPhase) -> Self {+ let previous = CURRENT_CONTROL_PHASE.with(|current| current.replace(Some(phase)));+ Self { previous }+ }+}++#[cfg(all(test, not(target_arch = "wasm32")))]+impl Drop for TestControlPhaseGuard {+ fn drop(&mut self) {+ CURRENT_CONTROL_PHASE.with(|current| current.set(self.previous));+ }+}++#[cfg(all(test, not(target_arch = "wasm32")))]+fn take_reset_failure(sql: &str) -> bool {+ RESET_FAILURE_SQL.with(|fault| {+ if fault.borrow().as_deref() == Some(sql) {+ fault.borrow_mut().take();+ true+ } else {+ false+ }+ })+}++#[cfg(all(test, not(target_arch = "wasm32")))]+fn record_control_phase(phase: TestControlPhase) {+ CONTROL_TRACE.with(|trace| trace.borrow_mut().push(phase));+}++#[cfg(all(test, not(target_arch = "wasm32")))]+fn take_forced_control_io() -> bool {+ current_test_control_phase() == Some(TestControlPhase::Rollback)+ && FORCE_CONTROL_IO.with(|forced| forced.replace(false))+}++#[cfg(all(test, not(target_arch = "wasm32")))]+fn record_control_io() {+ if let Some(phase) = current_test_control_phase() {+ CONTROL_IO_TRACE.with(|trace| trace.borrow_mut().push(phase));+ }+}++#[cfg(all(test, not(target_arch = "wasm32")))]+pub(crate) fn current_test_control_phase() -> Option<TestControlPhase> {+ CURRENT_CONTROL_PHASE.with(std::cell::Cell::get)+}++#[cfg(all(test, not(target_arch = "wasm32")))]+pub(crate) fn arm_reset_failure(sql: &str) {+ RESET_FAILURE_SQL.with(|fault| *fault.borrow_mut() = Some(sql.to_owned()));+}++#[cfg(all(test, not(target_arch = "wasm32")))]+pub(crate) fn arm_rollback_control_io() {+ FORCE_CONTROL_IO.with(|forced| forced.set(true));+}++#[cfg(all(test, not(target_arch = "wasm32")))]+pub(crate) fn clear_control_trace() {+ CONTROL_TRACE.with(|trace| trace.borrow_mut().clear());+ CONTROL_IO_TRACE.with(|trace| trace.borrow_mut().clear());+ FORCE_CONTROL_IO.with(|forced| forced.set(false));+}++#[cfg(all(test, not(target_arch = "wasm32")))]+pub(crate) fn take_control_trace() -> Vec<TestControlPhase> {+ CONTROL_TRACE.with(|trace| std::mem::take(&mut *trace.borrow_mut()))+}++#[cfg(all(test, not(target_arch = "wasm32")))]+pub(crate) fn take_control_io_trace() -> Vec<TestControlPhase> {+ CONTROL_IO_TRACE.with(|trace| std::mem::take(&mut *trace.borrow_mut()))+}diff --git a/crates/client/cache-turso/src/error.rs b/crates/client/cache-turso/src/error.rsnew file mode 100644index 0000000000..ea0733e840--- /dev/null+++ b/crates/client/cache-turso/src/error.rs@@ -0,0 +1,129 @@+use std::io::ErrorKind;+use thiserror::Error;+use turso_core::{CompletionError, LimboError};++/// The reason an open browser cache must be physically replaced.+#[derive(Clone, Copy, Debug, PartialEq, Eq, Error)]+pub enum PhysicalResetReason {+ /// The database or one of its checked rows is structurally corrupt.+ #[error("corrupt local database")]+ Corruption,+ /// A postcard payload failed the shared cache codec.+ #[error("corrupt cache payload")]+ Codec,+ /// Queue, key, numeric, or relational state violated the frozen schema contract.+ #[error("invalid durable cache state")]+ Invariant,+ /// The browser storage quota is full.+ #[error("browser storage is full")]+ StorageFull,+ /// A commit, rollback, or statement cleanup left transaction durability uncertain.+ #[error("transaction outcome is uncertain")]+ TransactionOutcomeUncertain,+ /// A storage I/O operation failed or returned an unexpected completion state.+ #[error("storage I/O is uncertain")]+ Io,+ /// Required schema or metadata is missing or incompatible.+ #[error("storage compatibility mismatch")]+ Compatibility,+ /// The approved integrity check did not return its sole success row.+ #[error("storage integrity check failed")]+ Integrity,+}++impl PhysicalResetReason {+ pub(crate) const fn latch_code(self) -> u8 {+ match self {+ Self::Corruption => 1,+ Self::Codec => 2,+ Self::Invariant => 3,+ Self::StorageFull => 4,+ Self::TransactionOutcomeUncertain => 5,+ Self::Io => 6,+ Self::Compatibility => 7,+ Self::Integrity => 8,+ }+ }++ pub(crate) const fn from_latch_code(code: u8) -> Option<Self> {+ match code {+ 1 => Some(Self::Corruption),+ 2 => Some(Self::Codec),+ 3 => Some(Self::Invariant),+ 4 => Some(Self::StorageFull),+ 5 => Some(Self::TransactionOutcomeUncertain),+ 6 => Some(Self::Io),+ 7 => Some(Self::Compatibility),+ 8 => Some(Self::Integrity),+ _ => None,+ }+ }+}++/// Errors produced by the Turso storage backend.+///+/// Errors deliberately contain no entity keys, cache scope, GraphQL text,+/// variables, record bytes, or mutation payloads.+#[derive(Clone, Copy, Debug, PartialEq, Eq, Error)]+pub enum TursoStorageError {+ /// A caller supplied a value outside the checked storage contract.+ #[error("invalid storage input")]+ InvalidInput,+ /// A deterministic database operation failed without an uncertain commit outcome.+ #[error("Turso database operation failed")]+ Database,+ /// The disposable physical database must be closed and replaced.+ #[error("physical cache reset required: {0}")]+ PhysicalResetRequired(PhysicalResetReason),+}++impl TursoStorageError {+ /// Returns whether the current physical database must not be reused.+ pub const fn requires_physical_reset(&self) -> bool {+ matches!(self, Self::PhysicalResetRequired(_))+ }++ /// Returns the physical-reset reason, when replacement is required.+ pub const fn physical_reset_reason(&self) -> Option<PhysicalResetReason> {+ match self {+ Self::PhysicalResetRequired(reason) => Some(*reason),+ Self::InvalidInput | Self::Database => None,+ }+ }++ pub(crate) const fn reset(reason: PhysicalResetReason) -> Self {+ Self::PhysicalResetRequired(reason)+ }++ pub(crate) fn turso(error: LimboError) -> Self {+ match error {+ LimboError::Corrupt(_)+ | LimboError::NotADB+ | LimboError::InvalidColumnType+ | LimboError::InvalidBlobSize(_)+ | LimboError::Page1NotAlloc => Self::reset(PhysicalResetReason::Corruption),+ LimboError::DatabaseFull(_)+ | LimboError::CompletionError(CompletionError::IOError(ErrorKind::StorageFull, _)) => {+ Self::reset(PhysicalResetReason::StorageFull)+ }+ LimboError::CompletionError(+ CompletionError::DecryptionError { .. }+ | CompletionError::PageCodecError { .. }+ | CompletionError::ShortRead { .. }+ | CompletionError::ShortReadWalFrame { .. }+ | CompletionError::WalFramePageMismatch { .. }+ | CompletionError::ChecksumMismatch { .. }+ | CompletionError::ChecksumNotEnabled,+ ) => Self::reset(PhysicalResetReason::Corruption),+ LimboError::CompletionError(_) => Self::reset(PhysicalResetReason::Io),+ _ => Self::Database,+ }+ }++ pub(crate) const fn initialization(self) -> Self {+ match self {+ Self::PhysicalResetRequired(_) => self,+ Self::InvalidInput | Self::Database => Self::reset(PhysicalResetReason::Compatibility),+ }+ }+}diff --git a/crates/client/cache-turso/src/key.rs b/crates/client/cache-turso/src/key.rsnew file mode 100644index 0000000000..17362c375d--- /dev/null+++ b/crates/client/cache-turso/src/key.rs@@ -0,0 +1,65 @@+use crate::{PhysicalResetReason, TursoStorageError};+use cache_core::value::{EntityKey, ROOT_QUERY};+use std::borrow::Cow;++#[derive(Clone, Debug, PartialEq, Eq)]+pub(crate) struct RecordKey {+ pub(crate) typename: String,+ pub(crate) id: String,+}++impl RecordKey {+ pub(crate) fn from_entity(key: &EntityKey<'_>) -> Result<Self, TursoStorageError> {+ let value = key.as_ref();+ let parsed = if value == ROOT_QUERY {+ Self {+ typename: ROOT_QUERY.to_owned(),+ id: String::new(),+ }+ } else {+ let (typename, id) = value+ .split_once(':')+ .ok_or(TursoStorageError::InvalidInput)?;+ if typename.is_empty() {+ return Err(TursoStorageError::InvalidInput);+ }+ Self {+ typename: typename.to_owned(),+ id: id.to_owned(),+ }+ };+ if parsed.canonical_string()? != value {+ return Err(TursoStorageError::InvalidInput);+ }+ Ok(parsed)+ }++ pub(crate) fn into_entity(self) -> Result<EntityKey<'static>, TursoStorageError> {+ let canonical = self.canonical_string_from_row()?;+ let reparsed = Self::from_entity(&EntityKey(Cow::Borrowed(&canonical)))+ .map_err(|_| TursoStorageError::reset(PhysicalResetReason::Corruption))?;+ if reparsed != self {+ return Err(TursoStorageError::reset(PhysicalResetReason::Corruption));+ }+ Ok(EntityKey(Cow::Owned(canonical)))+ }++ fn canonical_string(&self) -> Result<String, TursoStorageError> {+ if self.typename.is_empty() {+ return Err(TursoStorageError::InvalidInput);+ }+ if self.typename == ROOT_QUERY && self.id.is_empty() {+ Ok(ROOT_QUERY.to_owned())+ } else {+ Ok(format!("{}:{}", self.typename, self.id))+ }+ }++ fn canonical_string_from_row(&self) -> Result<String, TursoStorageError> {+ self.canonical_string()+ .map_err(|_| TursoStorageError::reset(PhysicalResetReason::Corruption))+ }+}++#[cfg(test)]+mod test;diff --git a/crates/client/cache-turso/src/key/test.rs b/crates/client/cache-turso/src/key/test.rsnew file mode 100644index 0000000000..bfc2278225--- /dev/null+++ b/crates/client/cache-turso/src/key/test.rs@@ -0,0 +1,41 @@+use super::*;++#[test]+fn checked_entity_key_round_trips() {+ for value in [+ // ROOT_QUERY is the only key accepted without a typename/id separator;+ // ROOT_QUERY: remains invalid, while ordinary typenames may have empty IDs.+ "ROOT_QUERY",+ "GraphqlSoupDocument:doc-1",+ "GraphqlSoupDocument:tenant:doc-1",+ "__meta:identity",+ "Thing:",+ ] {+ let entity = EntityKey(Cow::Borrowed(value));+ let pair = RecordKey::from_entity(&entity).unwrap();+ assert_eq!(pair.into_entity().unwrap().as_ref(), value);+ }+}++#[test]+fn invalid_entity_keys_and_sql_pairs_are_rejected() {+ for value in ["", "Thing", ":id", "ROOT_QUERY:"] {+ assert!(RecordKey::from_entity(&EntityKey(Cow::Borrowed(value))).is_err());+ }+ let empty_typename = RecordKey {+ typename: String::new(),+ id: "id".into(),+ };+ assert!(+ empty_typename+ .into_entity()+ .unwrap_err()+ .requires_physical_reset()+ );++ let root_query = RecordKey {+ typename: "ROOT_QUERY".into(),+ id: String::new(),+ };+ assert_eq!(root_query.into_entity().unwrap().as_ref(), "ROOT_QUERY");+}diff --git a/crates/client/cache-turso/src/lib.rs b/crates/client/cache-turso/src/lib.rsnew file mode 100644index 0000000000..0784814675--- /dev/null+++ b/crates/client/cache-turso/src/lib.rs@@ -0,0 +1,28 @@+//! Production Turso storage adapter for the normalized GraphQL cache.+//!+//! The adapter implements every [`cache_core::store::Storage`] operation with+//! the frozen compound-key schema, checked postcard payloads, strict-head+//! mutation leasing, and immediate write transactions. Incompatible or+//! uncertain disposable state is classified for physical reset; it is never+//! migrated, copied, logged, or redirected to a fallback backend.++#![deny(missing_docs)]+#![forbid(unsafe_code)]++mod driver;+mod error;+mod key;+mod storage;++pub use error::{PhysicalResetReason, TursoStorageError};+pub use storage::{+ BROWSER_STORAGE_SCHEMA_VERSION, TursoStorage, TursoStorageCloseOutcome, TursoStorageOpenOutcome,+};++#[cfg(not(target_arch = "wasm32"))]+pub use storage::TursoMemoryDatabase;+#[cfg(target_arch = "wasm32")]+pub use storage::{+ HealthyTursoStorageClosed, ResetRequiredTursoStorageClosed, TursoStorageCloseFailure,+ TursoStorageOpenFailure, TursoStorageResetFailure,+};diff --git a/crates/client/cache-turso/src/storage.rs b/crates/client/cache-turso/src/storage.rsnew file mode 100644index 0000000000..b0a1091e29--- /dev/null+++ b/crates/client/cache-turso/src/storage.rs@@ -0,0 +1,2141 @@+use crate::driver;+use crate::key::RecordKey;+use crate::{PhysicalResetReason, TursoStorageError};+use cache_core::codec::{+ cache_namespace, decode_record, decode_record_updates, encode_record, encode_record_updates,+};+use cache_core::queue::{+ ClaimedMutation, MutationClaimRequest, MutationClaimToken, MutationId, MutationRequest,+ NewQueuedMutation, PersistedOptimisticLayer, QueuedMutation, StoredMutation,+};+use cache_core::store::{QueueDiagnostics, QueueDiagnosticsAvailability, Storage};+use cache_core::value::{EntityKey, Record};+use std::sync::Arc;+use std::sync::atomic::{AtomicU8, Ordering};+use turso_core::{Connection, Numeric, Value};++#[cfg(not(target_arch = "wasm32"))]+use std::sync::Mutex;+#[cfg(not(target_arch = "wasm32"))]+use std::sync::atomic::AtomicU64;+#[cfg(not(target_arch = "wasm32"))]+use turso_core::{Database, IO, MemoryIO, OpenOptions, SqliteDialect};+#[cfg(target_arch = "wasm32")]+use turso_opfs::{+ CloseFailure, ClosedSession, ConnectedOpfsSession, OpenDisposition, OpfsError, OpfsOwner,+ ResetFailure,+};++/// Frozen browser-storage schema version, independent of cache postcard versions.+pub const BROWSER_STORAGE_SCHEMA_VERSION: u32 = 2;++/// Coarse outcome of validating an OPFS Turso session.+#[derive(Clone, Copy, Debug, PartialEq, Eq)]+pub enum TursoStorageOpenOutcome {+ /// Existing compatible storage was validated and preserved.+ OpenedExisting,+ /// A fresh physical database was initialized.+ OpenedNew,+}++const CREATE_SCHEMA: [&str; 5] = [+ "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 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)",+];+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";+const RECORD_DELETE: &str = "DELETE FROM records WHERE __typename = ?1 AND id = ?2";+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";+const QUEUE_HEAD_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 LIMIT 1";+const ORPHAN_LAYER_SELECT: &str = "SELECT o.mutation_id FROM optimistic_layers AS o LEFT JOIN mutation_queue AS m ON m.id = o.mutation_id WHERE m.id IS NULL LIMIT 1";+const ANY_LAYER_SELECT: &str = "SELECT mutation_id FROM optimistic_layers LIMIT 1";+const CLAIM_SELECT: &str = "SELECT lease_owner, lease_generation FROM mutation_queue WHERE id = ?1";+const REQUIRE_LAYER_SELECT: &str = "SELECT 1 FROM optimistic_layers WHERE mutation_id = ?1";+const QUEUE_DIAGNOSTICS_SELECT: &str = "SELECT COUNT(*), MIN(created_at_ms) FROM mutation_queue";++/// Turso-backed implementation of [`Storage`].+///+/// On `wasm32` this value owns the consuming+/// `turso_opfs::ConnectedOpfsSession` capability. It must be consumed with+/// [`Self::try_close`] before OPFS preservation or reset.+/// Native builds own a Turso `MemoryIO` database solely for conformance tests.+pub struct TursoStorage {+ health: AtomicU8,+ #[cfg(target_arch = "wasm32")]+ session: ConnectedOpfsSession,+ #[cfg(not(target_arch = "wasm32"))]+ database: Arc<Database>,+ #[cfg(not(target_arch = "wasm32"))]+ connection: Arc<Connection>,+ #[cfg(all(test, not(target_arch = "wasm32")))]+ fault: Mutex<Option<TestFault>>,+}++impl std::fmt::Debug for TursoStorage {+ fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {+ formatter+ .debug_struct("TursoStorage")+ .finish_non_exhaustive()+ }+}++#[cfg(target_arch = "wasm32")]+impl TursoStorage {+ /// Validates or initializes an already connected, OPFS-owned Turso session.+ ///+ /// Initialization failure exposes only a consuming physical-reset+ /// transition. It never exposes the connected or closed OPFS capability,+ /// so incompatible files cannot be preserved accidentally.+ pub fn from_opfs_session(+ session: ConnectedOpfsSession,+ scope: &str,+ ) -> Result<Self, TursoStorageOpenFailure> {+ Self::from_opfs_session_with_outcome(session, scope).map(|(storage, _)| storage)+ }++ /// Validates or initializes an OPFS session and returns its coarse outcome.+ pub fn from_opfs_session_with_outcome(+ session: ConnectedOpfsSession,+ scope: &str,+ ) -> Result<(Self, TursoStorageOpenOutcome), TursoStorageOpenFailure> {+ let fresh = session.disposition() == OpenDisposition::Fresh;+ let connection = session.connection();+ let result = initialize(&connection, scope, fresh);+ drop(connection);+ match result {+ Ok(()) => Ok((+ Self {+ health: AtomicU8::new(0),+ session,+ },+ if fresh {+ TursoStorageOpenOutcome::OpenedNew+ } else {+ TursoStorageOpenOutcome::OpenedExisting+ },+ )),+ Err(error) => Err(TursoStorageOpenFailure { error, session }),+ }+ }++ /// Browser-test-artifact-only helper used by the storage-control worker.+ #[cfg(feature = "browser-test-hooks")]+ #[doc(hidden)]+ pub fn browser_test_make_namespace_incompatible(&mut self) -> Result<(), TursoStorageError> {+ self.require_healthy()?;+ let connection = self.connection();+ self.latch_result(driver::write_transaction(&connection, || {+ require_changed(+ driver::execute(+ &connection,+ "UPDATE meta SET value = 'browser-test-incompatible' WHERE key = 'namespace'",+ Vec::new(),+ )?,+ 1,+ )+ }))+ }++ /// Browser-test-artifact-only helper that writes an invalid queue payload.+ #[cfg(feature = "browser-test-hooks")]+ #[doc(hidden)]+ pub fn browser_test_corrupt_queue_payload(&mut self) -> Result<(), TursoStorageError> {+ self.require_healthy()?;+ let connection = self.connection();+ self.latch_result(driver::write_transaction(&connection, || {+ require_changed(+ driver::execute(+ &connection,+ QUEUE_INSERT,+ vec![+ text("mutation BrowserTestCorrupt { __typename }"),+ Value::Null,+ text("{}"),+ Value::Null,+ Value::from_i64(0),+ Value::Null,+ Value::Null,+ Value::from_i64(0),+ Value::Null,+ Value::Null,+ Value::from_i64(1),+ ],+ )?,+ 1,+ )?;+ let id = mutation_id_from_row(connection.last_insert_rowid())?;+ require_changed(+ driver::execute(+ &connection,+ LAYER_INSERT,+ vec![+ Value::from_i64(mutation_id_to_sql(id)?),+ text("{}"),+ Value::from_blob(vec![0xff]),+ ],+ )?,+ 1,+ )+ }))+ }++ /// Consumes storage and closes Turso into a health-typed OPFS capability.+ ///+ /// Healthy storage may subsequently be preserved or reset. A latched+ /// reset-required storage returns a capability that exposes reset only.+ /// Close failure exposes no recoverable session and requires replacing the+ /// worker before a recovery wipe.+ pub fn try_close(self) -> Result<TursoStorageCloseOutcome, TursoStorageCloseFailure> {+ let reason = self.latched_reason();+ let closed = self+ .session+ .try_close()+ .map_err(TursoStorageCloseFailure::new)?;+ Ok(match reason {+ Some(reason) => {+ TursoStorageCloseOutcome::ResetRequired(ResetRequiredTursoStorageClosed {+ reason,+ closed,+ })+ }+ None => TursoStorageCloseOutcome::Healthy(HealthyTursoStorageClosed { closed }),+ })+ }++ fn connection(&self) -> Arc<Connection> {+ self.session.connection()+ }+}++/// Result of consuming and gracefully closing a browser Turso storage.+#[cfg(target_arch = "wasm32")]+#[derive(Debug)]+pub enum TursoStorageCloseOutcome {+ /// The database remained healthy and may be preserved or reset.+ Healthy(HealthyTursoStorageClosed),+ /// A reset-required reason was latched, so preservation is unavailable.+ ResetRequired(ResetRequiredTursoStorageClosed),+}++/// Closed healthy browser storage that may be preserved or reset.+#[cfg(target_arch = "wasm32")]+#[derive(Debug)]+pub struct HealthyTursoStorageClosed {+ closed: ClosedSession,+}++#[cfg(target_arch = "wasm32")]+impl HealthyTursoStorageClosed {+ /// Preserves the healthy main/WAL pair and returns its still-locked owner.+ pub fn preserve(self) -> Result<OpfsOwner, OpfsError> {+ self.closed.preserve()+ }++ /// Physically resets the healthy main/WAL pair.+ pub async fn reset(self) -> Result<OpfsOwner, TursoStorageResetFailure> {+ self.closed+ .reset()+ .await+ .map_err(TursoStorageResetFailure::from_reset)+ }+}++/// Closed reset-required browser storage that cannot be preserved.+#[cfg(target_arch = "wasm32")]+#[derive(Debug)]+pub struct ResetRequiredTursoStorageClosed {+ reason: PhysicalResetReason,+ closed: ClosedSession,+}++#[cfg(target_arch = "wasm32")]+impl ResetRequiredTursoStorageClosed {+ /// Returns the first reset-required reason latched by this storage.+ pub fn reason(&self) -> PhysicalResetReason {+ self.reason+ }++ /// Physically resets the unhealthy main/WAL pair.+ pub async fn reset(self) -> Result<OpfsOwner, TursoStorageResetFailure> {+ self.closed+ .reset()+ .await+ .map_err(TursoStorageResetFailure::from_reset)+ }+}++/// A browser close failure that exposes no reusable session capability.+///+/// The worker-local OPFS owner is either already poisoned or becomes poisoned+/// when the retained internal session is dropped. Recovery requires worker+/// replacement followed by the owner's recovery wipe.+#[cfg(target_arch = "wasm32")]+#[derive(Debug)]+pub struct TursoStorageCloseFailure {+ failure: CloseFailure,+}++#[cfg(target_arch = "wasm32")]+impl TursoStorageCloseFailure {+ fn new(failure: CloseFailure) -> Self {+ Self { failure }+ }++ /// Returns the payload-free OPFS error classification.+ pub fn error(&self) -> &OpfsError {+ self.failure.error()+ }++ /// Returns that recovery requires replacing the poisoned worker.+ pub const fn requires_worker_replacement(&self) -> bool {+ true+ }+}++#[cfg(target_arch = "wasm32")]+impl std::fmt::Display for TursoStorageCloseFailure {+ fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {+ self.failure.fmt(formatter)+ }+}++#[cfg(target_arch = "wasm32")]+impl std::error::Error for TursoStorageCloseFailure {+ fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {+ Some(&self.failure)+ }+}++/// A browser reset transition failure that requires worker replacement.+#[cfg(target_arch = "wasm32")]+#[derive(Debug)]+pub struct TursoStorageResetFailure {+ failure: TursoStorageResetFailureInner,+}++#[cfg(target_arch = "wasm32")]+#[derive(Debug)]+enum TursoStorageResetFailureInner {+ Close(CloseFailure),+ Reset(ResetFailure),+}++#[cfg(target_arch = "wasm32")]+impl TursoStorageResetFailure {+ fn from_close(failure: CloseFailure) -> Self {+ Self {+ failure: TursoStorageResetFailureInner::Close(failure),+ }+ }++ fn from_reset(failure: ResetFailure) -> Self {+ Self {+ failure: TursoStorageResetFailureInner::Reset(failure),+ }+ }++ /// Returns the payload-free OPFS error classification.+ pub fn error(&self) -> &OpfsError {+ match &self.failure {+ TursoStorageResetFailureInner::Close(failure) => failure.error(),+ TursoStorageResetFailureInner::Reset(failure) => failure.error(),+ }+ }++ /// Returns that recovery requires replacing the poisoned worker.+ pub const fn requires_worker_replacement(&self) -> bool {+ true+ }+}++#[cfg(target_arch = "wasm32")]+impl std::fmt::Display for TursoStorageResetFailure {+ fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {+ match &self.failure {+ TursoStorageResetFailureInner::Close(failure) => failure.fmt(formatter),+ TursoStorageResetFailureInner::Reset(failure) => failure.fmt(formatter),+ }+ }+}++#[cfg(target_arch = "wasm32")]+impl std::error::Error for TursoStorageResetFailure {+ fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {+ match &self.failure {+ TursoStorageResetFailureInner::Close(failure) => Some(failure),+ TursoStorageResetFailureInner::Reset(failure) => Some(failure),+ }+ }+}++/// A WASM initialization failure that permits only physical reset.+#[cfg(target_arch = "wasm32")]+pub struct TursoStorageOpenFailure {+ error: TursoStorageError,+ session: ConnectedOpfsSession,+}++#[cfg(target_arch = "wasm32")]+impl TursoStorageOpenFailure {+ /// Returns the payload-free storage classification.+ pub fn error(&self) -> TursoStorageError {+ self.error+ }++ /// Consumes a non-reset failure, closes Turso, and preserves main and WAL.+ ///+ /// This accessor must only be used when [`Self::error`] does not require a+ /// physical reset. A close failure poisons the worker-local owner.+ pub fn preserve(self) -> Result<OpfsOwner, OpfsError> {+ let closed = self+ .session+ .try_close()+ .map_err(|failure| failure.error().clone())?;+ closed.preserve()+ }++ /// Consumes the failure, closes Turso, and physically resets main and WAL.+ ///+ /// Neither the connected nor closed session is exposed. Close/reset failure+ /// requires worker replacement before recovery.+ pub async fn reset(self) -> Result<OpfsOwner, TursoStorageResetFailure> {+ let closed = self+ .session+ .try_close()+ .map_err(TursoStorageResetFailure::from_close)?;+ closed+ .reset()+ .await+ .map_err(TursoStorageResetFailure::from_reset)+ }+}++#[cfg(target_arch = "wasm32")]+impl std::fmt::Debug for TursoStorageOpenFailure {+ fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {+ formatter+ .debug_struct("TursoStorageOpenFailure")+ .field("error", &self.error)+ .finish_non_exhaustive()+ }+}++#[cfg(target_arch = "wasm32")]+impl std::fmt::Display for TursoStorageOpenFailure {+ fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {+ self.error.fmt(formatter)+ }+}++#[cfg(target_arch = "wasm32")]+impl std::error::Error for TursoStorageOpenFailure {}++/// Reopenable Turso `MemoryIO` database used by native conformance tests.+#[cfg(not(target_arch = "wasm32"))]+pub struct TursoMemoryDatabase {+ path: String,+ state: Mutex<MemoryDatabaseState>,+}++#[cfg(not(target_arch = "wasm32"))]+struct MemoryDatabaseState {+ io: Arc<MemoryIO>,+ initialized: bool,+}++#[cfg(not(target_arch = "wasm32"))]+impl TursoMemoryDatabase {+ /// Creates an isolated, initially fresh in-memory physical database.+ pub fn new(database_path: impl Into<String>) -> Self {+ Self {+ path: database_path.into(),+ state: Mutex::new(MemoryDatabaseState {+ io: Arc::new(MemoryIO::new()),+ initialized: false,+ }),+ }+ }++ /// Opens and initializes or validates this in-memory database for `scope`.+ pub fn open(&self, scope: &str) -> Result<TursoStorage, TursoStorageError> {+ let (io, fresh) = {+ let state = self.state.lock().unwrap_or_else(|error| error.into_inner());+ (state.io.clone(), !state.initialized)+ };+ let io_trait: Arc<dyn IO> = io;+ let database = Database::open(+ io_trait,+ &self.path,+ OpenOptions::new(Arc::new(SqliteDialect)),+ )+ .map_err(TursoStorageError::turso)+ .map_err(|error| if fresh { error } else { error.initialization() })?;+ let connection = database+ .connect()+ .map_err(TursoStorageError::turso)+ .map_err(|error| if fresh { error } else { error.initialization() })?;+ if let Err(error) = initialize(&connection, scope, fresh) {+ if connection.close().is_err() {+ return Err(TursoStorageError::reset(+ PhysicalResetReason::TransactionOutcomeUncertain,+ ));+ }+ return Err(error);+ }+ if fresh {+ self.state+ .lock()+ .unwrap_or_else(|error| error.into_inner())+ .initialized = true;+ }+ Ok(TursoStorage {+ health: AtomicU8::new(0),+ database,+ connection,+ #[cfg(all(test, not(target_arch = "wasm32")))]+ fault: Mutex::new(None),+ })+ }++ /// Replaces the complete in-memory main/WAL store with a fresh one.+ ///+ /// Callers must first consume and close every storage opened from this+ /// database. This models the owner-level physical reset used by OPFS.+ pub fn physical_reset(&self) {+ let mut state = self.state.lock().unwrap_or_else(|error| error.into_inner());+ state.io = Arc::new(MemoryIO::new());+ state.initialized = false;+ }+}++/// Health-typed result of consuming a native conformance-test storage.+#[cfg(not(target_arch = "wasm32"))]+#[derive(Clone, Copy, Debug, PartialEq, Eq)]+pub enum TursoStorageCloseOutcome {+ /// The native test database remained healthy.+ Healthy,+ /// The native test database must be physically replaced before reopening.+ ResetRequired(PhysicalResetReason),+}++#[cfg(not(target_arch = "wasm32"))]+impl TursoStorage {+ /// Opens a one-use isolated Turso `MemoryIO` database.+ pub fn open_in_memory(scope: &str) -> Result<Self, TursoStorageError> {+ static NEXT_MEMORY_DATABASE: AtomicU64 = AtomicU64::new(1);+ let id = NEXT_MEMORY_DATABASE.fetch_add(1, Ordering::Relaxed);+ TursoMemoryDatabase::new(format!("cache-turso-memory-{id}.db")).open(scope)+ }++ /// Consumes and explicitly closes the native Turso connection.+ pub fn try_close(self) -> Result<TursoStorageCloseOutcome, TursoStorageError> {+ let reason = self.latched_reason();+ self.connection.close().map_err(|_| {+ TursoStorageError::reset(PhysicalResetReason::TransactionOutcomeUncertain)+ })?;+ drop(self.connection);+ drop(self.database);+ Ok(match reason {+ Some(reason) => TursoStorageCloseOutcome::ResetRequired(reason),+ None => TursoStorageCloseOutcome::Healthy,+ })+ }++ fn connection(&self) -> Arc<Connection> {+ self.connection.clone()+ }+}++impl TursoStorage {+ fn latched_reason(&self) -> Option<PhysicalResetReason> {+ let code = self.health.load(Ordering::Acquire);+ PhysicalResetReason::from_latch_code(code)+ .or_else(|| (code != 0).then_some(PhysicalResetReason::TransactionOutcomeUncertain))+ }++ fn require_healthy(&self) -> Result<(), TursoStorageError> {+ self.latched_reason()+ .map_or(Ok(()), |reason| Err(TursoStorageError::reset(reason)))+ }++ fn latch_result<T>(+ &self,+ result: Result<T, TursoStorageError>,+ ) -> Result<T, TursoStorageError> {+ match result {+ Err(TursoStorageError::PhysicalResetRequired(reason)) => {+ let _ = self.health.compare_exchange(+ 0,+ reason.latch_code(),+ Ordering::AcqRel,+ Ordering::Acquire,+ );+ Err(TursoStorageError::reset(reason))+ }+ result => result,+ }+ }+}++impl Storage for TursoStorage {+ type Error = TursoStorageError;++ async fn get_batch(&self, keys: &[EntityKey<'_>]) -> Result<Vec<Option<Record>>, Self::Error> {+ self.require_healthy()?;+ let result = (|| {+ let keys = keys+ .iter()+ .map(RecordKey::from_entity)+ .collect::<Result<Vec<_>, _>>()?;+ if keys.is_empty() {+ return Ok(Vec::new());+ }+ let connection = self.connection();+ driver::read_transaction(&connection, || {+ let mut statement = driver::prepare(&connection, RECORD_GET)?;+ let mut records = Vec::with_capacity(keys.len());+ for key in &keys {+ let rows = driver::query_prepared(+ &mut statement,+ vec![text(&key.typename), text(&key.id)],+ )?;+ match rows.as_slice() {+ [] => records.push(None),+ [row] => {+ records.push(Some(decode_record(&required_blob(row, 0)?).map_err(+ |_| TursoStorageError::reset(PhysicalResetReason::Codec),+ )?))+ }+ _ => return Err(invariant()),+ }+ }+ Ok(records)+ })+ })();+ self.latch_result(result)+ }++ async fn put_batch(+ &mut self,+ entries: Vec<(EntityKey<'static>, Record)>,+ ) -> Result<(), Self::Error> {+ self.require_healthy()?;+ let result = (|| {+ let entries = prepare_records(entries)?;+ if entries.is_empty() {+ return Ok(());+ }+ let connection = self.connection();+ driver::write_transaction(&connection, || {+ let mut statement = driver::prepare(&connection, RECORD_UPSERT)?;+ for (index, entry) in entries.iter().enumerate() {+ let changed = driver::execute_prepared(+ &mut statement,+ vec![+ text(&entry.key.typename),+ text(&entry.key.id),+ Value::from_blob(entry.value.clone()),+ ],+ )?;+ require_changed(changed, 1)?;+ self.fault_after(TestFaultSite::Put, index)?;+ }+ Ok(())+ })+ })();+ self.latch_result(result)+ }++ async fn delete_batch(&mut self, keys: &[EntityKey<'static>]) -> Result<(), Self::Error> {+ self.require_healthy()?;+ let result = (|| {+ let keys = keys+ .iter()+ .map(RecordKey::from_entity)+ .collect::<Result<Vec<_>, _>>()?;+ if keys.is_empty() {+ return Ok(());+ }+ let connection = self.connection();+ driver::write_transaction(&connection, || {+ let mut statement = driver::prepare(&connection, RECORD_DELETE)?;+ for (index, key) in keys.iter().enumerate() {+ let changed = driver::execute_prepared(+ &mut statement,+ vec![text(&key.typename), text(&key.id)],+ )?;+ if !(0..=1).contains(&changed) {+ return Err(invariant());+ }+ self.fault_after(TestFaultSite::Delete, index)?;+ }+ Ok(())+ })+ })();+ self.latch_result(result)+ }++ async fn scan_records(+ &self,+ type_names: &[String],+ after: Option<&EntityKey<'static>>,+ limit: usize,+ ) -> Result<Vec<(EntityKey<'static>, Record)>, Self::Error> {+ self.require_healthy()?;+ let result = (|| {+ if type_names.is_empty() || limit == 0 {+ return Ok(Vec::new());+ }+ let mut type_names = type_names.to_vec();+ type_names.sort();+ type_names.dedup();+ let after = after+ .map(|key| RecordKey::from_entity(key).map(|_| key.as_ref().to_owned()))+ .transpose()?;+ let limit = i64::try_from(limit).map_err(|_| TursoStorageError::InvalidInput)?;++ let mut sql =+ String::from("SELECT __typename, id, value FROM records WHERE __typename IN (");+ for index in 0..type_names.len() {+ if index != 0 {+ sql.push_str(", ");+ }+ sql.push('?');+ sql.push_str(&(index + 1).to_string());+ }+ sql.push_str(") AND NOT (__typename = 'ROOT_QUERY' AND id = '')");+ let mut values = type_names+ .iter()+ .map(|value| text(value))+ .collect::<Vec<_>>();+ if let Some(after) = after {+ let cursor_index = values.len() + 1;+ sql.push_str(" AND ((__typename || ':' || id) COLLATE BINARY) > ?");+ sql.push_str(&cursor_index.to_string());+ values.push(text(&after));+ }+ let limit_index = values.len() + 1;+ sql.push_str(" ORDER BY (__typename || ':' || id) COLLATE BINARY ASC LIMIT ?");+ sql.push_str(&limit_index.to_string());+ values.push(Value::from_i64(limit));++ let connection = self.connection();+ let rows = driver::query(&connection, &sql, values)?;+ rows.into_iter()+ .map(|row| {+ let key = RecordKey {+ typename: required_text(&row, 0)?,+ id: required_text(&row, 1)?,+ }+ .into_entity()?;+ let record = decode_record(&required_blob(&row, 2)?)+ .map_err(|_| TursoStorageError::reset(PhysicalResetReason::Codec))?;+ Ok((key, record))+ })+ .collect()+ })();+ self.latch_result(result)+ }++ async fn enqueue_mutation(+ &mut self,+ entry: NewQueuedMutation,+ ) -> Result<MutationId, Self::Error> {+ self.require_healthy()?;+ let result = (|| {+ let mutation_values = mutation_values(&entry.mutation)?;+ let updates = encode_record_updates(&entry.optimistic.normalized_updates);+ let connection = self.connection();+ driver::write_transaction(&connection, || {+ require_changed(+ driver::execute(&connection, QUEUE_INSERT, mutation_values)?,+ 1,+ )?;+ self.fault_after(TestFaultSite::Enqueue, 0)?;+ let id = mutation_id_from_row(connection.last_insert_rowid())?;+ require_changed(+ driver::execute(+ &connection,+ LAYER_INSERT,+ vec![+ Value::from_i64(mutation_id_to_sql(id)?),+ text(&entry.optimistic.optimistic_data_json),+ Value::from_blob(updates),+ ],+ )?,+ 1,+ )?;+ Ok(id)+ })+ })();+ self.latch_result(result)+ }++ async fn load_mutation_queue(&self) -> Result<Vec<QueuedMutation>, Self::Error> {+ self.require_healthy()?;+ let result = {+ let connection = self.connection();+ driver::read_transaction(&connection, || {+ let rows = driver::query(&connection, QUEUE_SELECT, Vec::new())?;+ let mut queue = Vec::with_capacity(rows.len());+ for row in rows {+ let parsed = parse_queue_row(&row)?;+ let optimistic = parsed.optimistic.ok_or_else(invariant)?;+ queue.push(QueuedMutation {+ id: parsed.id,+ mutation: parsed.mutation,+ optimistic,+ });+ }+ if !driver::query(&connection, ORPHAN_LAYER_SELECT, Vec::new())?.is_empty() {+ return Err(invariant());+ }+ Ok(queue)+ })+ };+ self.latch_result(result)+ }++ async fn queue_diagnostics(&self) -> Result<QueueDiagnostics, Self::Error> {+ self.require_healthy()?;+ // Diagnostics are deliberately outside a transaction and outside the+ // health latch. A failed observation must never alter cache recovery.+ self.fault_after(TestFaultSite::Diagnostics, 0)?;+ let connection = self.connection();+ let rows = driver::query(&connection, QUEUE_DIAGNOSTICS_SELECT, Vec::new())?;+ let [row] = rows.as_slice() else {+ return Err(invariant());+ };+ if row.len() != 2 {+ return Err(invariant());+ }+ let depth = u64::try_from(required_i64(row, 0)?).map_err(|_| invariant())?;+ let oldest_created_at_ms = nullable_i64(row, 1)?;+ if (depth == 0) != oldest_created_at_ms.is_none() {+ return Err(invariant());+ }+ Ok(QueueDiagnostics {+ availability: QueueDiagnosticsAvailability::Available,+ depth,+ oldest_created_at_ms,+ })+ }++ async fn claim_next_mutation(+ &mut self,+ request: MutationClaimRequest,+ ) -> Result<Option<ClaimedMutation>, Self::Error> {+ self.require_healthy()?;+ let result = {+ let connection = self.connection();+ driver::write_transaction(&connection, || {+ let rows = driver::query(&connection, QUEUE_HEAD_SELECT, Vec::new())?;+ let Some(row) = rows.first() else {+ if !driver::query(&connection, ANY_LAYER_SELECT, Vec::new())?.is_empty() {+ return Err(invariant());+ }+ return Ok(None);+ };+ if rows.len() != 1 {+ return Err(invariant());+ }+ let mut parsed = parse_queue_row(row)?;+ let optimistic = parsed.optimistic.take().ok_or_else(invariant)?;+ if parsed+ .mutation+ .next_attempt_at_ms+ .is_some_and(|next| next > request.now_ms)+ || parsed+ .mutation+ .lease_expires_at_ms+ .is_some_and(|expiry| expiry > request.now_ms)+ {+ return Ok(None);+ }++ parsed.mutation.attempt_count = parsed.mutation.attempt_count.saturating_add(1);+ parsed.mutation.lease_generation =+ parsed.mutation.lease_generation.saturating_add(1);+ let generation =+ generation_to_sql(parsed.mutation.lease_generation).map_err(|_| invariant())?;+ parsed.mutation.next_attempt_at_ms = None;+ parsed.mutation.lease_owner = Some(request.owner.clone());+ parsed.mutation.lease_expires_at_ms = Some(request.lease_expires_at_ms);+ require_changed(+ driver::execute(+ &connection,+ "UPDATE mutation_queue SET attempt_count = ?2, next_attempt_at_ms = NULL, lease_owner = ?3, lease_generation = ?4, lease_expires_at_ms = ?5 WHERE id = ?1",+ vec![+ Value::from_i64(mutation_id_to_sql(parsed.id)?),+ Value::from_i64(i64::from(parsed.mutation.attempt_count)),+ text(&request.owner),+ Value::from_i64(generation),+ Value::from_i64(request.lease_expires_at_ms),+ ],+ )?,+ 1,+ )?;+ Ok(Some(ClaimedMutation {+ queued: QueuedMutation {+ id: parsed.id,+ mutation: parsed.mutation,+ optimistic,+ },+ lease_generation: u64::try_from(generation).map_err(|_| invariant())?,+ }))+ })+ };+ self.latch_result(result)+ }++ async fn defer_mutation(+ &mut self,+ id: MutationId,+ claim: MutationClaimToken,+ next_attempt_at_ms: i64,+ error: String,+ ) -> Result<bool, Self::Error> {+ self.require_healthy()?;+ let result = (|| {+ let id = mutation_id_to_sql(id)?;+ let generation = generation_to_sql(claim.generation)?;+ let connection = self.connection();+ driver::write_transaction(&connection, || {+ let changed = driver::execute(+ &connection,+ "UPDATE mutation_queue SET next_attempt_at_ms = ?4, lease_owner = NULL, lease_expires_at_ms = NULL, last_error = ?5 WHERE id = ?1 AND lease_owner = ?2 AND lease_generation = ?3",+ vec![+ Value::from_i64(id),+ text(&claim.owner),+ Value::from_i64(generation),+ Value::from_i64(next_attempt_at_ms),+ text(&error),+ ],+ )?;+ changed_to_bool(changed)+ })+ })();+ self.latch_result(result)+ }++ async fn complete_mutation(+ &mut self,+ id: MutationId,+ claim: MutationClaimToken,+ entries: Vec<(EntityKey<'static>, Record)>,+ ) -> Result<bool, Self::Error> {+ self.require_healthy()?;+ let result = (|| {+ let sql_id = mutation_id_to_sql(id)?;+ generation_to_sql(claim.generation)?;+ let entries = prepare_records(entries)?;+ let connection = self.connection();+ driver::write_transaction(&connection, || {+ if !claim_is_current(&connection, sql_id, &claim)? {+ return Ok(false);+ }+ require_layer(&connection, sql_id)?;+ {+ 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::Complete, index)?;+ }+ }+ require_changed(+ driver::execute(+ &connection,+ "DELETE FROM mutation_queue WHERE id = ?1",+ vec![Value::from_i64(sql_id)],+ )?,+ 1,+ )?;+ Ok(true)+ })+ })();+ self.latch_result(result)+ }++ async fn discard_mutation(+ &mut self,+ id: MutationId,+ claim: MutationClaimToken,+ ) -> Result<bool, Self::Error> {+ self.require_healthy()?;+ let result = (|| {+ let sql_id = mutation_id_to_sql(id)?;+ generation_to_sql(claim.generation)?;+ let connection = self.connection();+ driver::write_transaction(&connection, || {+ if !claim_is_current(&connection, sql_id, &claim)? {+ return Ok(false);+ }+ require_layer(&connection, sql_id)?;+ require_changed(+ driver::execute(+ &connection,+ "DELETE FROM mutation_queue WHERE id = ?1",+ vec![Value::from_i64(sql_id)],+ )?,+ 1,+ )?;+ self.fault_after(TestFaultSite::Discard, 0)?;+ Ok(true)+ })+ })();+ self.latch_result(result)+ }++ async fn clear(&mut self) -> Result<(), Self::Error> {+ self.require_healthy()?;+ let result = {+ let connection = self.connection();+ driver::write_transaction(&connection, || {+ driver::execute(&connection, "DELETE FROM optimistic_layers", Vec::new())?;+ self.fault_after(TestFaultSite::Clear, 0)?;+ driver::execute(&connection, "DELETE FROM mutation_queue", Vec::new())?;+ self.fault_after(TestFaultSite::Clear, 1)?;+ driver::execute(&connection, "DELETE FROM records", Vec::new())?;+ self.fault_after(TestFaultSite::Clear, 2)?;+ Ok(())+ })+ };+ self.latch_result(result)+ }+}++fn initialize(+ connection: &Arc<Connection>,+ scope: &str,+ fresh: bool,+) -> Result<(), TursoStorageError> {+ enable_foreign_keys(connection).map_err(TursoStorageError::initialization)?;+ if fresh {+ driver::write_transaction(connection, || {+ for sql in CREATE_SCHEMA {+ driver::execute(connection, sql, Vec::new())?;+ }+ driver::execute(+ connection,+ "INSERT INTO meta (key, value) VALUES ('scope', ?1)",+ vec![text(scope)],+ )?;+ driver::execute(+ connection,+ "INSERT INTO meta (key, value) VALUES ('namespace', ?1)",+ vec![text(&cache_namespace(scope))],+ )?;+ driver::execute(+ connection,+ "INSERT INTO meta (key, value) VALUES ('storage_schema_version', ?1)",+ vec![text(&BROWSER_STORAGE_SCHEMA_VERSION.to_string())],+ )?;+ Ok(())+ })+ .map_err(TursoStorageError::initialization)?;+ enable_foreign_keys(connection).map_err(TursoStorageError::initialization)?;+ validate_frozen_schema(connection)?;+ return Ok(());+ }++ validate_quick_check(connection)?;+ validate_frozen_schema(connection)?;+ let metadata = driver::query(+ connection,+ "SELECT key, value FROM meta WHERE key IN ('scope', 'namespace', 'storage_schema_version') ORDER BY key ASC",+ Vec::new(),+ )+ .map_err(TursoStorageError::initialization)?;+ let expected = [+ ("namespace", cache_namespace(scope)),+ ("scope", scope.to_owned()),+ (+ "storage_schema_version",+ BROWSER_STORAGE_SCHEMA_VERSION.to_string(),+ ),+ ];+ if metadata.len() != expected.len() {+ return Err(TursoStorageError::reset(PhysicalResetReason::Compatibility));+ }+ for (row, (expected_key, expected_value)) in metadata.iter().zip(expected) {+ let key = required_text(row, 0)+ .map_err(|_| TursoStorageError::reset(PhysicalResetReason::Compatibility))?;+ let value = required_text(row, 1)+ .map_err(|_| TursoStorageError::reset(PhysicalResetReason::Compatibility))?;+ if key != expected_key || value != expected_value {+ return Err(TursoStorageError::reset(PhysicalResetReason::Compatibility));+ }+ }+ for sql in [+ RECORD_GET,+ RECORD_UPSERT,+ RECORD_DELETE,+ QUEUE_INSERT,+ LAYER_INSERT,+ QUEUE_SELECT,+ QUEUE_HEAD_SELECT,+ ORPHAN_LAYER_SELECT,+ CLAIM_SELECT,+ REQUIRE_LAYER_SELECT,+ QUEUE_DIAGNOSTICS_SELECT,+ ] {+ driver::validate(connection, sql).map_err(TursoStorageError::initialization)?;+ }+ validate_queue_consistency(connection)+}++fn enable_foreign_keys(connection: &Arc<Connection>) -> Result<(), TursoStorageError> {+ driver::execute(connection, "PRAGMA foreign_keys = ON", Vec::new())?;+ let rows = driver::query(connection, "PRAGMA foreign_keys", Vec::new())?;+ if rows.len() == 1 && required_i64(&rows[0], 0)? == 1 {+ Ok(())+ } else {+ Err(TursoStorageError::reset(PhysicalResetReason::Invariant))+ }+}++#[derive(Clone, Copy)]+struct ColumnSpec {+ name: &'static str,+ declared_type: &'static str,+ not_null: bool,+ default_zero: bool,+ primary_key_position: i64,+}++const META_COLUMNS: &[ColumnSpec] = &[+ ColumnSpec {+ name: "key",+ declared_type: "TEXT",+ not_null: false,+ default_zero: false,+ primary_key_position: 1,+ },+ ColumnSpec {+ name: "value",+ declared_type: "TEXT",+ not_null: true,+ default_zero: false,+ primary_key_position: 0,+ },+];++const RECORD_COLUMNS: &[ColumnSpec] = &[+ ColumnSpec {+ name: "__typename",+ declared_type: "TEXT",+ not_null: true,+ default_zero: false,+ primary_key_position: 1,+ },+ ColumnSpec {+ name: "id",+ 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: 0,+ },+];++const MUTATION_COLUMNS: &[ColumnSpec] = &[+ ColumnSpec {+ name: "id",+ declared_type: "INTEGER",+ not_null: false,+ default_zero: false,+ primary_key_position: 1,+ },+ ColumnSpec {+ name: "query",+ declared_type: "TEXT",+ not_null: true,+ default_zero: false,+ primary_key_position: 0,+ },+ ColumnSpec {+ name: "operation_name",+ declared_type: "TEXT",+ not_null: false,+ default_zero: false,+ primary_key_position: 0,+ },+ ColumnSpec {+ name: "variables_json",+ declared_type: "TEXT",+ not_null: true,+ default_zero: false,+ primary_key_position: 0,+ },+ ColumnSpec {+ name: "identity",+ declared_type: "TEXT",+ not_null: false,+ default_zero: false,+ primary_key_position: 0,+ },+ ColumnSpec {+ name: "attempt_count",+ declared_type: "INTEGER",+ not_null: true,+ default_zero: true,+ primary_key_position: 0,+ },+ ColumnSpec {+ name: "next_attempt_at_ms",+ declared_type: "INTEGER",+ not_null: false,+ default_zero: false,+ primary_key_position: 0,+ },+ ColumnSpec {+ name: "lease_owner",+ declared_type: "TEXT",+ not_null: false,+ default_zero: false,+ primary_key_position: 0,+ },+ ColumnSpec {+ name: "lease_generation",+ declared_type: "INTEGER",+ not_null: true,+ default_zero: true,+ primary_key_position: 0,+ },+ ColumnSpec {+ name: "lease_expires_at_ms",+ declared_type: "INTEGER",+ not_null: false,+ default_zero: false,+ primary_key_position: 0,+ },+ ColumnSpec {+ name: "last_error",+ declared_type: "TEXT",+ not_null: false,+ default_zero: false,+ primary_key_position: 0,+ },+ ColumnSpec {+ name: "created_at_ms",+ declared_type: "INTEGER",+ not_null: true,+ default_zero: false,+ primary_key_position: 0,+ },+];++const OPTIMISTIC_COLUMNS: &[ColumnSpec] = &[+ ColumnSpec {+ name: "mutation_id",+ declared_type: "INTEGER",+ not_null: false,+ default_zero: false,+ primary_key_position: 1,+ },+ ColumnSpec {+ name: "optimistic_data_json",+ declared_type: "TEXT",+ not_null: true,+ default_zero: false,+ primary_key_position: 0,+ },+ ColumnSpec {+ name: "normalized_updates",+ declared_type: "BLOB",+ 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)?;+ validate_table_columns(connection, "records", RECORD_COLUMNS)?;+ validate_table_columns(connection, "mutation_queue", MUTATION_COLUMNS)?;+ validate_table_columns(connection, "optimistic_layers", OPTIMISTIC_COLUMNS)?;+ validate_table_indexes(connection, "meta", &[(0, "key")])?;+ validate_table_indexes(connection, "records", &[(0, "__typename"), (1, "id")])?;+ validate_mutation_queue_indexes(connection)?;+ validate_table_indexes(connection, "optimistic_layers", &[])?;+ validate_table_constraints(connection, "meta", false)?;+ validate_table_constraints(connection, "records", false)?;+ validate_table_constraints(connection, "mutation_queue", true)?;+ validate_table_constraints(connection, "optimistic_layers", false)?;+ validate_no_foreign_keys(connection, "meta")?;+ validate_no_foreign_keys(connection, "records")?;+ validate_no_foreign_keys(connection, "mutation_queue")?;+ validate_optimistic_foreign_key(connection)+}++const SQLITE_SEQUENCE_TABLE: &str = "sqlite_sequence";+const TURSO_AUTOINCREMENT_TABLE: &str =+ "__turso_internal_seq___turso_internal_autoincrement_mutation_queue";++fn validate_allowed_schema_objects(connection: &Arc<Connection>) -> Result<(), TursoStorageError> {+ let rows = driver::query(+ connection,+ "SELECT type, name, sql FROM sqlite_schema ORDER BY type ASC, name ASC",+ Vec::new(),+ )+ .map_err(TursoStorageError::initialization)?;+ let expected = ["meta", "mutation_queue", "optimistic_layers", "records"];+ let support = [SQLITE_SEQUENCE_TABLE, TURSO_AUTOINCREMENT_TABLE];+ let mut seen = [false; 4];+ let mut diagnostics_index_seen = false;+ let mut support_seen = [false; 2];+ for row in rows {+ if row.len() != 3 {+ return Err(compatibility());+ }+ let object_type = required_text(&row, 0).map_err(|_| compatibility())?;+ let name = required_text(&row, 1).map_err(|_| compatibility())?;+ if let Some(position) = expected.iter().position(|expected| *expected == name) {+ if object_type != "table"+ || !matches!(row.get(2), Some(Value::Text(_)))+ || seen[position]+ {+ return Err(compatibility());+ }+ seen[position] = true;+ continue;+ }+ if object_type == "index" && matches!(row.get(2), Some(Value::Null)) {+ 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;+ continue;+ }+ if let Some(position) = support.iter().position(|expected| *expected == name) {+ if object_type != "table"+ || !matches!(row.get(2), Some(Value::Text(_)))+ || support_seen[position]+ {+ return Err(compatibility());+ }+ validate_support_table(connection, &name, position)?;+ support_seen[position] = true;+ continue;+ }+ return Err(compatibility());+ }+ if seen.into_iter().all(|present| present)+ && diagnostics_index_seen+ && support_seen.into_iter().all(|present| present)+ {+ Ok(())+ } else {+ Err(compatibility())+ }+}++fn validate_support_table(+ connection: &Arc<Connection>,+ table: &str,+ support_position: usize,+) -> Result<(), TursoStorageError> {+ let escaped = table.replace('\'', "''");+ let rows = driver::query(+ connection,+ &format!("PRAGMA table_xinfo('{escaped}')"),+ Vec::new(),+ )+ .map_err(TursoStorageError::initialization)?;+ let sqlite_sequence = [("name", "", 0, 0), ("seq", "", 0, 0)];+ let turso_autoincrement = [+ ("value", "INTEGER", 0, 1),+ ("is_called", "INTEGER", 0, 0),+ ("start", "INTEGER", 0, 0),+ ("inc", "INTEGER", 0, 0),+ ("min", "INTEGER", 0, 0),+ ("max", "INTEGER", 0, 0),+ ("cycle", "INTEGER", 0, 0),+ ];+ let expected: &[_] = match support_position {+ 0 => &sqlite_sequence,+ 1 => &turso_autoincrement,+ _ => return Err(compatibility()),+ };+ if rows.len() != expected.len() {+ return Err(compatibility());+ }+ for (position, (row, (expected_name, expected_type, expected_not_null, expected_pk))) in+ rows.iter().zip(expected).enumerate()+ {+ if row.len() != 7+ || required_i64(row, 0).ok() != i64::try_from(position).ok()+ || required_text(row, 1).ok().as_deref() != Some(*expected_name)+ || required_text(row, 2).ok().as_deref() != Some(*expected_type)+ || required_i64(row, 3).ok() != Some(*expected_not_null)+ || !matches!(row.get(4), Some(Value::Null))+ || required_i64(row, 5).ok() != Some(*expected_pk)+ || required_i64(row, 6).ok() != Some(0)+ {+ return Err(compatibility());+ }+ }+ if !driver::query(+ connection,+ &format!("PRAGMA index_list('{escaped}')"),+ Vec::new(),+ )+ .map_err(TursoStorageError::initialization)?+ .is_empty()+ || !driver::query(+ connection,+ &format!("PRAGMA foreign_key_list('{escaped}')"),+ Vec::new(),+ )+ .map_err(TursoStorageError::initialization)?+ .is_empty()+ {+ return Err(compatibility());+ }+ Ok(())+}++fn validate_table_columns(+ connection: &Arc<Connection>,+ table: &str,+ expected: &[ColumnSpec],+) -> Result<(), TursoStorageError> {+ let sql = format!("PRAGMA table_xinfo('{table}')");+ let rows =+ driver::query(connection, &sql, Vec::new()).map_err(TursoStorageError::initialization)?;+ if rows.len() != expected.len() {+ return Err(compatibility());+ }+ for (position, (row, expected)) in rows.iter().zip(expected).enumerate() {+ if row.len() != 7+ || required_i64(row, 0).ok() != i64::try_from(position).ok()+ || required_text(row, 1).ok().as_deref() != Some(expected.name)+ || required_text(row, 2)+ .ok()+ .is_none_or(|value| value.trim().to_ascii_uppercase() != expected.declared_type)+ || required_i64(row, 3).ok() != Some(i64::from(expected.not_null))+ || !default_matches(row.get(4), expected.default_zero)+ || required_i64(row, 5).ok() != Some(expected.primary_key_position)+ || required_i64(row, 6).ok() != Some(0)+ {+ return Err(compatibility());+ }+ }+ Ok(())+}++fn default_matches(value: Option<&Value>, expected_zero: bool) -> bool {+ match (value, expected_zero) {+ (Some(Value::Null), false) => true,+ (Some(Value::Text(value)), true) => {+ value.as_str().chars().all(|character| {+ character == '0'+ || character == '('+ || character == ')'+ || character.is_whitespace()+ }) && value.as_str().contains('0')+ }+ (Some(Value::Numeric(Numeric::Integer(0))), true) => true,+ _ => false,+ }+}++fn validate_mutation_queue_indexes(connection: &Arc<Connection>) -> Result<(), TursoStorageError> {+ let rows = driver::query(+ connection,+ "PRAGMA index_list('mutation_queue')",+ Vec::new(),+ )+ .map_err(TursoStorageError::initialization)?;+ let [row] = rows.as_slice() else {+ return Err(compatibility());+ };+ if row.len() != 5+ || required_i64(row, 0).ok() != Some(0)+ || required_text(row, 1).ok().as_deref() != Some("mutation_queue_created_at_ms_idx")+ || required_i64(row, 2).ok() != Some(0)+ || required_text(row, 3).ok().as_deref() != Some("c")+ || required_i64(row, 4).ok() != Some(0)+ {+ return Err(compatibility());+ }+ let index_rows = driver::query(+ connection,+ "PRAGMA index_xinfo('mutation_queue_created_at_ms_idx')",+ Vec::new(),+ )+ .map_err(TursoStorageError::initialization)?;+ let [created_at, rowid] = index_rows.as_slice() else {+ return Err(compatibility());+ };+ if created_at.len() != 6+ || required_i64(created_at, 0).ok() != Some(0)+ || required_i64(created_at, 1).ok() != Some(11)+ || required_text(created_at, 2).ok().as_deref() != Some("created_at_ms")+ || required_i64(created_at, 3).ok() != Some(0)+ || required_text(created_at, 4).ok().as_deref() != Some("BINARY")+ || required_i64(created_at, 5).ok() != Some(1)+ || rowid.len() != 6+ || required_i64(rowid, 0).ok() != Some(1)+ || required_i64(rowid, 1).ok() != Some(-1)+ || !rowid.get(2).is_some_and(|value| {+ matches!(value, Value::Null)+ || matches!(value, Value::Text(text) if text.as_str().is_empty())+ })+ || required_i64(rowid, 3).ok() != Some(0)+ || required_text(rowid, 4).ok().as_deref() != Some("BINARY")+ || required_i64(rowid, 5).ok() != Some(0)+ {+ return Err(compatibility());+ }+ Ok(())+}++fn validate_table_indexes(+ connection: &Arc<Connection>,+ table: &str,+ expected_key_columns: &[(i64, &str)],+) -> Result<(), TursoStorageError> {+ let rows = driver::query(+ connection,+ &format!("PRAGMA index_list('{}')", table.replace('\'', "''")),+ Vec::new(),+ )+ .map_err(TursoStorageError::initialization)?;+ let expected_index_count = usize::from(!expected_key_columns.is_empty());+ if rows.len() != expected_index_count {+ return Err(compatibility());+ }+ let Some(row) = rows.first() else {+ return Ok(());+ };+ if row.len() != 5+ || required_i64(row, 0).ok() != Some(0)+ || required_i64(row, 2).ok() != Some(1)+ || required_text(row, 3).ok().as_deref() != Some("pk")+ || required_i64(row, 4).ok() != Some(0)+ {+ return Err(compatibility());+ }+ let index_name = required_text(row, 1).map_err(|_| compatibility())?;+ let index_rows = driver::query(+ connection,+ &format!("PRAGMA index_xinfo('{}')", index_name.replace('\'', "''")),+ Vec::new(),+ )+ .map_err(TursoStorageError::initialization)?;+ if index_rows.len() != expected_key_columns.len() + 1 {+ return Err(compatibility());+ }+ for (sequence, (row, (expected_column_id, expected_name))) in+ index_rows.iter().zip(expected_key_columns).enumerate()+ {+ if row.len() != 6+ || required_i64(row, 0).ok() != i64::try_from(sequence).ok()+ || required_i64(row, 1).ok() != Some(*expected_column_id)+ || required_text(row, 2).ok().as_deref() != Some(*expected_name)+ || required_i64(row, 3).ok() != Some(0)+ || required_text(row, 4).ok().as_deref() != Some("BINARY")+ || required_i64(row, 5).ok() != Some(1)+ {+ return Err(compatibility());+ }+ }+ let Some(rowid) = index_rows.last() else {+ return Err(compatibility());+ };+ if rowid.len() != 6+ || required_i64(rowid, 0).ok() != i64::try_from(expected_key_columns.len()).ok()+ || required_i64(rowid, 1).ok() != Some(-1)+ || !rowid.get(2).is_some_and(|value| {+ matches!(value, Value::Null)+ || matches!(value, Value::Text(text) if text.as_str().is_empty())+ })+ || required_i64(rowid, 3).ok() != Some(0)+ || required_text(rowid, 4).ok().as_deref() != Some("BINARY")+ || required_i64(rowid, 5).ok() != Some(0)+ {+ return Err(compatibility());+ }+ Ok(())+}++#[derive(Debug, PartialEq, Eq)]+enum SchemaToken {+ Word(String),+ QuotedIdentifier,+ StringLiteral,+ Symbol,+}++impl SchemaToken {+ fn is_keyword(&self, expected: &str) -> bool {+ matches!(self, Self::Word(word) if word == expected)+ }+}++fn validate_table_constraints(+ connection: &Arc<Connection>,+ table: &str,+ expects_autoincrement: bool,+) -> Result<(), TursoStorageError> {+ let rows = driver::query(+ connection,+ "SELECT sql FROM sqlite_schema WHERE type = 'table' AND name = ?1",+ vec![text(table)],+ )+ .map_err(TursoStorageError::initialization)?;+ let [row] = rows.as_slice() else {+ return Err(compatibility());+ };+ if row.len() != 1 {+ return Err(compatibility());+ }+ let sql = required_text(row, 0).map_err(|_| compatibility())?;+ let tokens = lex_schema(&sql)?;+ if has_forbidden_table_syntax(&tokens) {+ return Err(compatibility());+ }+ let autoincrement_count = tokens+ .iter()+ .filter(|token| token.is_keyword("autoincrement"))+ .count();+ if !expects_autoincrement {+ return (autoincrement_count == 0)+ .then_some(())+ .ok_or_else(compatibility);+ }+ let declaration_count = tokens+ .windows(4)+ .filter(|window| {+ window[0].is_keyword("integer")+ && window[1].is_keyword("primary")+ && window[2].is_keyword("key")+ && window[3].is_keyword("autoincrement")+ })+ .count();+ if autoincrement_count == 1 && declaration_count == 1 {+ Ok(())+ } else {+ Err(compatibility())+ }+}++fn has_forbidden_table_syntax(tokens: &[SchemaToken]) -> bool {+ ["as", "check", "collate", "generated", "unique"]+ .into_iter()+ .any(|keyword| tokens.iter().any(|token| token.is_keyword(keyword)))+}++fn lex_schema(sql: &str) -> Result<Vec<SchemaToken>, TursoStorageError> {+ let characters = sql.chars().collect::<Vec<_>>();+ let mut tokens = Vec::new();+ let mut index = 0;+ while index < characters.len() {+ let character = characters[index];+ if character.is_whitespace() {+ index += 1;+ continue;+ }+ if character == '-' && characters.get(index + 1) == Some(&'-') {+ index += 2;+ while index < characters.len() && !matches!(characters[index], '\n' | '\r') {+ index += 1;+ }+ continue;+ }+ if character == '/' && characters.get(index + 1) == Some(&'*') {+ index += 2;+ let mut closed = false;+ while index + 1 < characters.len() {+ if characters[index] == '*' && characters[index + 1] == '/' {+ index += 2;+ closed = true;+ break;+ }+ index += 1;+ }+ if !closed {+ return Err(compatibility());+ }+ continue;+ }+ if character == '\'' {+ index = scan_quoted(&characters, index + 1, '\'')?;+ tokens.push(SchemaToken::StringLiteral);+ continue;+ }+ if matches!(character, '"' | '`') {+ index = scan_quoted(&characters, index + 1, character)?;+ tokens.push(SchemaToken::QuotedIdentifier);+ continue;+ }+ if character == '[' {+ index += 1;+ while index < characters.len() && characters[index] != ']' {+ index += 1;+ }+ if index == characters.len() {+ return Err(compatibility());+ }+ index += 1;+ tokens.push(SchemaToken::QuotedIdentifier);+ continue;+ }+ if character.is_alphabetic() || character == '_' {+ let start = index;+ index += 1;+ while index < characters.len()+ && (characters[index].is_alphanumeric() || matches!(characters[index], '_' | '$'))+ {+ index += 1;+ }+ tokens.push(SchemaToken::Word(+ characters[start..index]+ .iter()+ .collect::<String>()+ .to_lowercase(),+ ));+ continue;+ }+ tokens.push(SchemaToken::Symbol);+ index += 1;+ }+ Ok(tokens)+}++fn scan_quoted(+ characters: &[char],+ mut index: usize,+ delimiter: char,+) -> Result<usize, TursoStorageError> {+ while index < characters.len() {+ if characters[index] == delimiter {+ if characters.get(index + 1) == Some(&delimiter) {+ index += 2;+ continue;+ }+ return Ok(index + 1);+ }+ index += 1;+ }+ Err(compatibility())+}++fn validate_no_foreign_keys(+ connection: &Arc<Connection>,+ table: &str,+) -> Result<(), TursoStorageError> {+ let escaped = table.replace('\'', "''");+ if driver::query(+ connection,+ &format!("PRAGMA foreign_key_list('{escaped}')"),+ Vec::new(),+ )+ .map_err(TursoStorageError::initialization)?+ .is_empty()+ {+ Ok(())+ } else {+ Err(compatibility())+ }+}++fn validate_optimistic_foreign_key(connection: &Arc<Connection>) -> Result<(), TursoStorageError> {+ let rows = driver::query(+ connection,+ "PRAGMA foreign_key_list('optimistic_layers')",+ 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("mutation_queue")+ || required_text(row, 3).ok().as_deref() != Some("mutation_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)+}++fn validate_quick_check(connection: &Arc<Connection>) -> Result<(), TursoStorageError> {+ let rows = driver::query(connection, "PRAGMA quick_check", Vec::new())+ .map_err(TursoStorageError::initialization)?;+ validate_quick_check_rows(&rows)+}++fn validate_quick_check_rows(rows: &[Vec<Value>]) -> Result<(), TursoStorageError> {+ if rows.len() == 1+ && rows[0].len() == 1+ && required_text(&rows[0], 0).ok().as_deref() == Some("ok")+ {+ Ok(())+ } else {+ Err(TursoStorageError::reset(PhysicalResetReason::Integrity))+ }+}++fn validate_queue_consistency(connection: &Arc<Connection>) -> Result<(), TursoStorageError> {+ let queue = driver::query(connection, QUEUE_SELECT, Vec::new())+ .map_err(TursoStorageError::initialization)?;+ for row in queue {+ if parse_queue_row(&row)?.optimistic.is_none() {+ return Err(invariant());+ }+ }+ if driver::query(connection, ORPHAN_LAYER_SELECT, Vec::new())+ .map_err(TursoStorageError::initialization)?+ .is_empty()+ {+ Ok(())+ } else {+ Err(invariant())+ }+}++struct EncodedRecord {+ key: RecordKey,+ value: Vec<u8>,+}++fn prepare_records(+ entries: Vec<(EntityKey<'static>, Record)>,+) -> Result<Vec<EncodedRecord>, TursoStorageError> {+ entries+ .into_iter()+ .map(|(key, record)| {+ Ok(EncodedRecord {+ key: RecordKey::from_entity(&key)?,+ value: encode_record(&record),+ })+ })+ .collect()+}++fn mutation_values(mutation: &StoredMutation) -> Result<Vec<Value>, TursoStorageError> {+ Ok(vec![+ text(&mutation.request.query),+ optional_text(mutation.request.operation_name.as_deref()),+ text(&mutation.request.variables_json),+ optional_text(mutation.request.identity.as_deref()),+ Value::from_i64(i64::from(mutation.attempt_count)),+ optional_i64(mutation.next_attempt_at_ms),+ optional_text(mutation.lease_owner.as_deref()),+ Value::from_i64(generation_to_sql(mutation.lease_generation)?),+ optional_i64(mutation.lease_expires_at_ms),+ optional_text(mutation.last_error.as_deref()),+ Value::from_i64(mutation.created_at_ms),+ ])+}++struct ParsedQueueRow {+ id: MutationId,+ mutation: StoredMutation,+ optimistic: Option<PersistedOptimisticLayer>,+}++fn parse_queue_row(row: &[Value]) -> Result<ParsedQueueRow, TursoStorageError> {+ if row.len() != 14 {+ return Err(invariant());+ }+ let optimistic = match (&row[12], &row[13]) {+ (Value::Null, Value::Null) => None,+ (Value::Null, _) | (_, Value::Null) => return Err(invariant()),+ _ => Some(PersistedOptimisticLayer {+ optimistic_data_json: required_text(row, 12)?,+ normalized_updates: decode_record_updates(&required_blob(row, 13)?)+ .map_err(|_| TursoStorageError::reset(PhysicalResetReason::Codec))?,+ }),+ };+ Ok(ParsedQueueRow {+ id: mutation_id_from_row(required_i64(row, 0)?)?,+ mutation: StoredMutation {+ request: MutationRequest {+ query: required_text(row, 1)?,+ operation_name: nullable_text(row, 2)?,+ variables_json: required_text(row, 3)?,+ identity: nullable_text(row, 4)?,+ },+ attempt_count: u32::try_from(required_i64(row, 5)?).map_err(|_| invariant())?,+ next_attempt_at_ms: nullable_i64(row, 6)?,+ lease_owner: nullable_text(row, 7)?,+ lease_generation: u64::try_from(required_i64(row, 8)?).map_err(|_| invariant())?,+ lease_expires_at_ms: nullable_i64(row, 9)?,+ last_error: nullable_text(row, 10)?,+ created_at_ms: required_i64(row, 11)?,+ },+ optimistic,+ })+}++fn claim_is_current(+ connection: &Arc<Connection>,+ id: i64,+ claim: &MutationClaimToken,+) -> Result<bool, TursoStorageError> {+ let rows = driver::query(connection, CLAIM_SELECT, vec![Value::from_i64(id)])?;+ match rows.as_slice() {+ [] => Ok(false),+ [row] => Ok(+ nullable_text(row, 0)?.as_deref() == Some(claim.owner.as_str())+ && u64::try_from(required_i64(row, 1)?).map_err(|_| invariant())?+ == claim.generation,+ ),+ _ => Err(invariant()),+ }+}++fn require_layer(connection: &Arc<Connection>, id: i64) -> Result<(), TursoStorageError> {+ let rows = driver::query(connection, REQUIRE_LAYER_SELECT, vec![Value::from_i64(id)])?;+ if rows.len() == 1 && required_i64(&rows[0], 0)? == 1 {+ Ok(())+ } else {+ Err(invariant())+ }+}++fn mutation_id_from_row(value: i64) -> Result<MutationId, TursoStorageError> {+ if value <= 0 {+ Err(invariant())+ } else {+ u64::try_from(value).map_err(|_| invariant())+ }+}++fn mutation_id_to_sql(value: MutationId) -> Result<i64, TursoStorageError> {+ let value = i64::try_from(value).map_err(|_| TursoStorageError::InvalidInput)?;+ if value > 0 {+ Ok(value)+ } else {+ Err(TursoStorageError::InvalidInput)+ }+}++fn generation_to_sql(value: u64) -> Result<i64, TursoStorageError> {+ i64::try_from(value).map_err(|_| TursoStorageError::InvalidInput)+}++fn text(value: &str) -> Value {+ Value::from_text(value.to_owned())+}++fn optional_text(value: Option<&str>) -> Value {+ value.map_or(Value::Null, text)+}++fn optional_i64(value: Option<i64>) -> Value {+ value.map_or(Value::Null, Value::from_i64)+}++fn required_value(row: &[Value], index: usize) -> Result<&Value, TursoStorageError> {+ row.get(index)+ .ok_or_else(|| TursoStorageError::reset(PhysicalResetReason::Corruption))+}++fn required_text(row: &[Value], index: usize) -> Result<String, TursoStorageError> {+ match required_value(row, index)? {+ Value::Text(value) => Ok(value.as_str().to_owned()),+ _ => Err(TursoStorageError::reset(PhysicalResetReason::Corruption)),+ }+}++fn nullable_text(row: &[Value], index: usize) -> Result<Option<String>, TursoStorageError> {+ match required_value(row, index)? {+ Value::Null => Ok(None),+ Value::Text(value) => Ok(Some(value.as_str().to_owned())),+ _ => Err(TursoStorageError::reset(PhysicalResetReason::Corruption)),+ }+}++fn required_blob(row: &[Value], index: usize) -> Result<Vec<u8>, TursoStorageError> {+ match required_value(row, index)? {+ Value::Blob(value) => Ok(value.to_vec()),+ _ => Err(TursoStorageError::reset(PhysicalResetReason::Corruption)),+ }+}++fn required_i64(row: &[Value], index: usize) -> Result<i64, TursoStorageError> {+ match required_value(row, index)? {+ Value::Numeric(Numeric::Integer(value)) => Ok(*value),+ _ => Err(TursoStorageError::reset(PhysicalResetReason::Corruption)),+ }+}++fn nullable_i64(row: &[Value], index: usize) -> Result<Option<i64>, TursoStorageError> {+ match required_value(row, index)? {+ Value::Null => Ok(None),+ Value::Numeric(Numeric::Integer(value)) => Ok(Some(*value)),+ _ => Err(TursoStorageError::reset(PhysicalResetReason::Corruption)),+ }+}++fn require_changed(changed: i64, expected: i64) -> Result<(), TursoStorageError> {+ if changed == expected {+ Ok(())+ } else {+ Err(invariant())+ }+}++fn changed_to_bool(changed: i64) -> Result<bool, TursoStorageError> {+ match changed {+ 0 => Ok(false),+ 1 => Ok(true),+ _ => Err(invariant()),+ }+}++fn invariant() -> TursoStorageError {+ TursoStorageError::reset(PhysicalResetReason::Invariant)+}++#[derive(Clone, Copy)]+enum TestFaultSite {+ Diagnostics,+ Put,+ Delete,+ Enqueue,+ Complete,+ Discard,+ Clear,+}++impl TursoStorage {+ fn fault_after(&self, site: TestFaultSite, index: usize) -> Result<(), TursoStorageError> {+ #[cfg(all(test, not(target_arch = "wasm32")))]+ {+ let mut fault = self.fault.lock().unwrap_or_else(|error| error.into_inner());+ if let Some((fault_state, fault_code)) = fault+ .as_ref()+ .and_then(|fault| fault.rollback_io_step_at(site, index))+ {+ fault_state.store(fault_code, Ordering::SeqCst);+ *fault = None;+ // This pinned Turso rollback emits no File completion after+ // this operation failure. Force its IO::step polling boundary+ // instead; no successful or unrelated completion is repurposed.+ driver::arm_rollback_control_io();+ return Err(TursoStorageError::Database);+ }+ if let Some(error) = fault.as_ref().and_then(|fault| fault.error_at(site, index)) {+ *fault = None;+ return Err(error);+ }+ }+ #[cfg(any(not(test), target_arch = "wasm32"))]+ let _ = (site, index);+ Ok(())+ }+}++#[cfg(all(test, not(target_arch = "wasm32")))]+#[derive(Clone)]+enum TestFault {+ After {+ site: TestFaultSite,+ index: usize,+ },+ ResetAfter {+ site: TestFaultSite,+ index: usize,+ reason: PhysicalResetReason,+ },+ RollbackIoStepAfter {+ site: TestFaultSite,+ index: usize,+ fault_state: Arc<AtomicU8>,+ fault_code: u8,+ },+}++#[cfg(all(test, not(target_arch = "wasm32")))]+impl TestFault {+ fn error_at(&self, site: TestFaultSite, index: usize) -> Option<TursoStorageError> {+ let (expected_site, expected_index, error) = match self {+ Self::After { site, index } => (site, index, TursoStorageError::Database),+ Self::ResetAfter {+ site,+ index,+ reason,+ } => (site, index, TursoStorageError::reset(*reason)),+ Self::RollbackIoStepAfter { .. } => return None,+ };+ (std::mem::discriminant(expected_site) == std::mem::discriminant(&site)+ && *expected_index == index)+ .then_some(error)+ }++ fn rollback_io_step_at(+ &self,+ site: TestFaultSite,+ index: usize,+ ) -> Option<(Arc<AtomicU8>, u8)> {+ let Self::RollbackIoStepAfter {+ site: expected_site,+ index: expected_index,+ fault_state,+ fault_code,+ } = self+ else {+ return None;+ };+ (std::mem::discriminant(expected_site) == std::mem::discriminant(&site)+ && *expected_index == index)+ .then(|| (fault_state.clone(), *fault_code))+ }+}++#[cfg(all(test, not(target_arch = "wasm32")))]+impl TursoStorage {+ fn arm_fault(&self, fault: TestFault) {+ *self.fault.lock().unwrap_or_else(|error| error.into_inner()) = Some(fault);+ }+}++#[cfg(all(test, target_arch = "wasm32"))]+mod browser_test;+#[cfg(all(test, not(target_arch = "wasm32")))]+mod test;diff --git a/crates/client/cache-turso/src/storage/browser_test.rs b/crates/client/cache-turso/src/storage/browser_test.rsnew file mode 100644index 0000000000..cf236c3486--- /dev/null+++ b/crates/client/cache-turso/src/storage/browser_test.rs@@ -0,0 +1,67 @@+use super::*;+use cache_core::store::Storage;+use cache_core::value::EntityKey;+use turso_opfs::{OpenResult, OpfsOwner};+use wasm_bindgen_test::*;++wasm_bindgen_test_configure!(run_in_dedicated_worker);++fn key(value: &str) -> EntityKey<'static> {+ EntityKey(value.to_owned().into())+}++#[wasm_bindgen_test(async)]+async fn runtime_corruption_closes_reset_only_and_replacement_is_empty() {+ let owner = OpfsOwner::acquire("cache-turso-wp06-runtime-reset.db")+ .await+ .unwrap()+ .recovery_wipe()+ .await+ .unwrap();+ let OpenResult::Ready(session) = owner.open().await.unwrap() else {+ panic!("recovery wipe must produce a complete fresh pair")+ };+ let storage =+ TursoStorage::from_opfs_session(session.connect().unwrap(), "runtime-reset").unwrap();+ driver::execute(+ &storage.connection(),+ RECORD_UPSERT,+ vec![text("Thing"), text("1"), Value::from_blob(vec![0xff])],+ )+ .unwrap();+ assert_eq!(+ storage+ .get_batch(&[key("Thing:1")])+ .await+ .unwrap_err()+ .physical_reset_reason(),+ Some(PhysicalResetReason::Codec)+ );+ assert_eq!(+ storage+ .load_mutation_queue()+ .await+ .unwrap_err()+ .physical_reset_reason(),+ Some(PhysicalResetReason::Codec)+ );++ let TursoStorageCloseOutcome::ResetRequired(closed) = storage.try_close().unwrap() else {+ panic!("runtime corruption must make preservation unavailable")+ };+ assert_eq!(closed.reason(), PhysicalResetReason::Codec);+ let owner = closed.reset().await.unwrap();+ let OpenResult::Ready(session) = owner.open().await.unwrap() else {+ panic!("physical reset must recreate a complete pair")+ };+ let replacement =+ TursoStorage::from_opfs_session(session.connect().unwrap(), "runtime-reset").unwrap();+ assert_eq!(+ replacement.get_batch(&[key("Thing:1")]).await.unwrap(),+ vec![None]+ );+ let TursoStorageCloseOutcome::Healthy(closed) = replacement.try_close().unwrap() else {+ panic!("fresh replacement must be healthy")+ };+ closed.preserve().unwrap().release().await.unwrap();+}diff --git a/crates/client/cache-turso/src/storage/test.rs b/crates/client/cache-turso/src/storage/test.rsnew file mode 100644index 0000000000..bfa2449309--- /dev/null+++ b/crates/client/cache-turso/src/storage/test.rs@@ -0,0 +1,1409 @@+use super::*;+use cache_core::normalize::RecordUpdates;+use pollster::block_on;+use std::sync::atomic::{AtomicU8, Ordering};+use turso_core::io::{FileId, FileSyncType};+use turso_core::{+ Buffer, Clock, Completion, CompletionError, File, IO, LimboError, MemoryIO, MonotonicInstant,+ OpenFlags, WallClockInstant,+};++fn key(value: &str) -> EntityKey<'static> {+ EntityKey(value.to_owned().into())+}++fn record(value: &str) -> Record {+ let mut record = Record::default();+ record.fields.insert(+ "value".into(),+ cache_core::value::CacheValue::String(value.into()),+ );+ record+}++fn queued(label: &str) -> NewQueuedMutation {+ NewQueuedMutation {+ mutation: StoredMutation::new(+ MutationRequest {+ query: format!("mutation {label} {{ update {{ id }} }}"),+ operation_name: Some(label.into()),+ variables_json: "{}".into(),+ identity: Some("identity".into()),+ },+ 1,+ ),+ optimistic: PersistedOptimisticLayer {+ optimistic_data_json: "{}".into(),+ normalized_updates: RecordUpdates::default(),+ },+ }+}++fn token(owner: &str, generation: u64) -> MutationClaimToken {+ MutationClaimToken {+ owner: owner.into(),+ generation,+ }+}++fn raw_execute(storage: &TursoStorage, sql: &str, values: Vec<Value>) -> i64 {+ driver::execute(&storage.connection(), sql, values).unwrap()+}++fn raw_scalar(storage: &TursoStorage, sql: &str) -> i64 {+ let rows = driver::query(&storage.connection(), sql, Vec::new()).unwrap();+ required_i64(&rows[0], 0).unwrap()+}++fn expect_reset_reason<T>(result: Result<T, TursoStorageError>, expected: PhysicalResetReason) {+ let Err(error) = result else {+ panic!("reset-required operation unexpectedly succeeded")+ };+ assert_eq!(error.physical_reset_reason(), Some(expected));+}++async fn expect_every_storage_method_latched(+ storage: &mut TursoStorage,+ expected: PhysicalResetReason,+) {+ expect_reset_reason(storage.get_batch(&[key("Thing:1")]).await, expected);+ expect_reset_reason(+ storage+ .put_batch(vec![(key("Thing:2"), record("blocked"))])+ .await,+ expected,+ );+ expect_reset_reason(storage.delete_batch(&[key("Thing:1")]).await, expected);+ expect_reset_reason(+ storage.scan_records(&["Thing".into()], None, 1).await,+ expected,+ );+ expect_reset_reason(storage.enqueue_mutation(queued("Blocked")).await, expected);+ expect_reset_reason(storage.load_mutation_queue().await, expected);+ expect_reset_reason(storage.queue_diagnostics().await, expected);+ expect_reset_reason(+ storage+ .claim_next_mutation(MutationClaimRequest {+ owner: "blocked".into(),+ now_ms: 1,+ lease_expires_at_ms: 2,+ })+ .await,+ expected,+ );+ expect_reset_reason(+ storage+ .defer_mutation(1, token("blocked", 1), 2, "blocked".into())+ .await,+ expected,+ );+ expect_reset_reason(+ storage+ .complete_mutation(1, token("blocked", 1), Vec::new())+ .await,+ expected,+ );+ expect_reset_reason(+ storage.discard_mutation(1, token("blocked", 1)).await,+ expected,+ );+ expect_reset_reason(storage.clear().await, expected);+}++#[test]+fn queue_diagnostics_use_one_payload_free_aggregate_query() {+ block_on(async {+ let mut storage = TursoStorage::open_in_memory("queue-diagnostics").unwrap();+ assert_eq!(+ storage.queue_diagnostics().await.unwrap(),+ QueueDiagnostics {+ availability: QueueDiagnosticsAvailability::Available,+ depth: 0,+ oldest_created_at_ms: None,+ }+ );+ let first = storage.enqueue_mutation(queued("First")).await.unwrap();+ let second = storage.enqueue_mutation(queued("Second")).await.unwrap();+ raw_execute(+ &storage,+ "UPDATE mutation_queue SET created_at_ms = ?2 WHERE id = ?1",+ vec![+ Value::from_i64(mutation_id_to_sql(first).unwrap()),+ Value::from_i64(10),+ ],+ );+ raw_execute(+ &storage,+ "UPDATE mutation_queue SET created_at_ms = ?2 WHERE id = ?1",+ vec![+ Value::from_i64(mutation_id_to_sql(second).unwrap()),+ Value::from_i64(20),+ ],+ );+ assert_eq!(+ storage.queue_diagnostics().await.unwrap(),+ QueueDiagnostics {+ availability: QueueDiagnosticsAvailability::Available,+ depth: 2,+ oldest_created_at_ms: Some(10),+ }+ );+ });+}++#[test]+fn queue_diagnostics_use_the_created_at_covering_index_at_scale() {+ block_on(async {+ let storage = TursoStorage::open_in_memory("queue-diagnostics-plan").unwrap();+ raw_execute(+ &storage,+ "WITH RECURSIVE values_to_insert(value) AS (VALUES(1) UNION ALL SELECT value + 1 FROM values_to_insert WHERE value < 10000) INSERT INTO mutation_queue (query, variables_json, created_at_ms) SELECT 'mutation Scale { scale }', '{}', 10001 - value FROM values_to_insert",+ Vec::new(),+ );+ let plan = driver::query(+ &storage.connection(),+ &format!("EXPLAIN QUERY PLAN {QUEUE_DIAGNOSTICS_SELECT}"),+ Vec::new(),+ )+ .unwrap();+ let details = plan+ .iter()+ .filter_map(|row| required_text(row, 3).ok())+ .collect::<Vec<_>>()+ .join(" ");+ assert!(+ details.contains("mutation_queue_created_at_ms_idx"),+ "diagnostics query did not use the covering timestamp index: {details}"+ );+ assert_eq!(+ storage.queue_diagnostics().await.unwrap(),+ QueueDiagnostics {+ availability: QueueDiagnosticsAvailability::Available,+ depth: 10_000,+ oldest_created_at_ms: Some(1),+ }+ );+ });+}++#[test]+fn queue_diagnostics_failure_never_latches_storage_health() {+ block_on(async {+ let mut storage = TursoStorage::open_in_memory("queue-diagnostics-health").unwrap();+ storage.arm_fault(TestFault::ResetAfter {+ site: TestFaultSite::Diagnostics,+ index: 0,+ reason: PhysicalResetReason::Io,+ });+ assert_eq!(+ storage+ .queue_diagnostics()+ .await+ .unwrap_err()+ .physical_reset_reason(),+ Some(PhysicalResetReason::Io)+ );+ storage+ .enqueue_mutation(queued("StillHealthy"))+ .await+ .unwrap();+ assert_eq!(storage.queue_diagnostics().await.unwrap().depth, 1);+ assert_eq!(+ storage.try_close().unwrap(),+ TursoStorageCloseOutcome::Healthy+ );+ });+}++#[test]+fn fresh_schema_metadata_foreign_keys_quick_check_and_cascade_are_real() {+ block_on(async {+ let mut storage = TursoStorage::open_in_memory("schema-scope").unwrap();+ assert_eq!(raw_scalar(&storage, "PRAGMA foreign_keys"), 1);+ let quick = driver::query(&storage.connection(), "PRAGMA quick_check", Vec::new()).unwrap();+ assert_eq!(quick.len(), 1);+ assert_eq!(required_text(&quick[0], 0).unwrap(), "ok");+ assert_eq!(raw_scalar(&storage, "SELECT COUNT(*) FROM meta"), 3);++ let violation = driver::execute(+ &storage.connection(),+ LAYER_INSERT,+ vec![Value::from_i64(999), text("{}"), Value::from_blob(vec![0])],+ )+ .unwrap_err();+ assert!(!violation.requires_physical_reset());+ assert_eq!(raw_scalar(&storage, "PRAGMA foreign_keys"), 1);++ let id = storage.enqueue_mutation(queued("Cascade")).await.unwrap();+ let claimed = storage+ .claim_next_mutation(MutationClaimRequest {+ owner: "runner".into(),+ now_ms: 1,+ lease_expires_at_ms: 10,+ })+ .await+ .unwrap()+ .unwrap();+ assert!(+ storage+ .discard_mutation(id, token("runner", claimed.lease_generation))+ .await+ .unwrap()+ );+ assert_eq!(+ raw_scalar(&storage, "SELECT COUNT(*) FROM optimistic_layers"),+ 0+ );+ });+}++#[test]+fn quick_check_requires_exactly_one_ok_text_row() {+ assert!(validate_quick_check_rows(&[vec![text("ok")]]).is_ok());+ for rows in [+ Vec::new(),+ vec![vec![text("corrupt")]],+ vec![vec![text("ok")], vec![text("ok")]],+ vec![vec![text("ok"), text("extra")]],+ vec![vec![Value::from_i64(1)]],+ ] {+ assert_eq!(+ validate_quick_check_rows(&rows)+ .unwrap_err()+ .physical_reset_reason(),+ Some(PhysicalResetReason::Integrity)+ );+ }+}++#[test]+fn every_metadata_mismatch_and_missing_schema_requests_physical_reset() {+ block_on(async {+ for (name, sql) in [+ (+ "namespace",+ "UPDATE meta SET value = 'wrong' WHERE key = 'namespace'",+ ),+ (+ "scope",+ "UPDATE meta SET value = 'wrong' WHERE key = 'scope'",+ ),+ (+ "version",+ "UPDATE meta SET value = '999' WHERE key = 'storage_schema_version'",+ ),+ ("missing", "DELETE FROM meta WHERE key = 'namespace'"),+ ("schema", "DROP TABLE records"),+ (+ "queue-diagnostics-index",+ "DROP INDEX mutation_queue_created_at_ms_idx",+ ),+ ] {+ let database = TursoMemoryDatabase::new(format!("mismatch-{name}.db"));+ let storage = database.open("scope").unwrap();+ raw_execute(&storage, sql, Vec::new());+ storage.try_close().unwrap();+ let error = database.open("scope").unwrap_err();+ assert!(error.requires_physical_reset(), "case {name}: {error}");+ assert_eq!(+ error.physical_reset_reason(),+ Some(PhysicalResetReason::Compatibility)+ );+ }++ let database = TursoMemoryDatabase::new("scope-mismatch-reset.db");+ let mut storage = database.open("scope-a").unwrap();+ storage+ .put_batch(vec![(key("Thing:1"), record("value"))])+ .await+ .unwrap();+ storage.enqueue_mutation(queued("Queued")).await.unwrap();+ storage.try_close().unwrap();+ assert!(+ database+ .open("scope-b")+ .unwrap_err()+ .requires_physical_reset()+ );+ database.physical_reset();+ let storage = database.open("scope-b").unwrap();+ assert_eq!(+ storage.get_batch(&[key("Thing:1")]).await.unwrap(),+ vec![None]+ );+ assert!(storage.load_mutation_queue().await.unwrap().is_empty());+ });+}++#[test]+fn semantically_equivalent_schema_formatting_is_accepted_on_reopen() {+ let database = TursoMemoryDatabase::new("semantic-schema-formatting.db");+ let storage = database.open("scope").unwrap();+ for sql in [+ "DROP TABLE optimistic_layers",+ "DROP TABLE mutation_queue",+ "DROP TABLE records",+ r#"create table [records] (+ [__typename] text not null,+ `id` text not null,+ 'value' blob not null,+ -- UNIQUE(value), CHECK(id), and COLLATE NOCASE are only comment text.+ primary key ([__typename], `id`)+ )"#,+ r#"create table 'mutation_queue' (+ 'id' integer /* AUTOINCREMENT UNIQUE CHECK COLLATE */ primary key autoincrement,+ "query" text not null,+ [operation_name] text,+ `variables_json` text not null,+ "identity" text,+ "attempt_count" integer default ( ( 0 ) ) not null,+ "next_attempt_at_ms" integer,+ "lease_owner" text,+ "lease_generation" integer default ((0)) not null,+ "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)",+ r#"create table `optimistic_layers` (+ `mutation_id` integer primary key,+ [optimistic_data_json] text not null,+ 'normalized_updates' blob not null,+ /* A string-like quoted identifier containing 'UNIQUE CHECK COLLATE'. */+ foreign key (`mutation_id`) references 'mutation_queue' ('id') on delete cascade+ )"#,+ ] {+ raw_execute(&storage, sql, Vec::new());+ }+ assert_eq!(+ storage.try_close().unwrap(),+ TursoStorageCloseOutcome::Healthy+ );+ let mut reopened = database.open("scope").unwrap();+ block_on(async {+ let first = reopened.enqueue_mutation(queued("First")).await.unwrap();+ let claimed = reopened+ .claim_next_mutation(MutationClaimRequest {+ owner: "runner".into(),+ now_ms: 1,+ lease_expires_at_ms: 2,+ })+ .await+ .unwrap()+ .unwrap();+ assert!(+ reopened+ .discard_mutation(first, token("runner", claimed.lease_generation))+ .await+ .unwrap()+ );+ assert!(reopened.enqueue_mutation(queued("Second")).await.unwrap() > first);+ });+ assert_eq!(+ reopened.try_close().unwrap(),+ TursoStorageCloseOutcome::Healthy+ );+}++#[test]+fn generated_column_forms_are_rejected_by_the_schema_lexer() {+ for sql in [+ "CREATE TABLE records (value TEXT GENERATED ALWAYS AS (id))",+ "CREATE TABLE records (value TEXT AS (id))",+ ] {+ let tokens = lex_schema(sql).unwrap();+ assert!(has_forbidden_table_syntax(&tokens), "SQL: {sql}");+ }+}++#[test]+fn every_malformed_frozen_schema_constraint_requests_reset_on_reopen() {+ let cases = vec![+ (+ "meta-primary-key",+ vec![+ "DROP TABLE meta",+ "CREATE TABLE meta (key TEXT, value TEXT NOT NULL)",+ ],+ ),+ (+ "meta-extra-foreign-key",+ vec![+ "DROP TABLE meta",+ "CREATE TABLE meta (key TEXT PRIMARY KEY, value TEXT NOT NULL, FOREIGN KEY (value) REFERENCES records(id))",+ ],+ ),+ (+ "records-column-type",+ vec![+ "DROP TABLE records",+ "CREATE TABLE records (__typename TEXT NOT NULL, id INTEGER NOT NULL, value BLOB NOT NULL, PRIMARY KEY (__typename, id))",+ ],+ ),+ (+ "records-primary-key",+ vec![+ "DROP TABLE records",+ "CREATE TABLE records (__typename TEXT NOT NULL, id TEXT NOT NULL, value BLOB NOT NULL)",+ ],+ ),+ (+ "records-primary-key-order",+ vec![+ "DROP TABLE records",+ "CREATE TABLE records (__typename TEXT NOT NULL, id TEXT NOT NULL, value BLOB NOT NULL, PRIMARY KEY (id, __typename))",+ ],+ ),+ (+ "records-not-null",+ vec![+ "DROP TABLE records",+ "CREATE TABLE records (__typename TEXT NOT NULL, id TEXT NOT NULL, value BLOB, PRIMARY KEY (__typename, id))",+ ],+ ),+ (+ "records-extra-column",+ vec![+ "DROP TABLE records",+ "CREATE TABLE records (__typename TEXT NOT NULL, id TEXT NOT NULL, value BLOB NOT NULL, extra TEXT, PRIMARY KEY (__typename, id))",+ ],+ ),+ (+ "records-extra-foreign-key",+ vec![+ "DROP TABLE records",+ "CREATE TABLE records (__typename TEXT NOT NULL, id TEXT NOT NULL, value BLOB NOT NULL, PRIMARY KEY (__typename, id), FOREIGN KEY (value) REFERENCES meta(key))",+ ],+ ),+ (+ "records-unique-constraint",+ vec![+ "DROP TABLE records",+ "CREATE TABLE records (__typename TEXT NOT NULL, id TEXT NOT NULL, value BLOB NOT NULL, PRIMARY KEY (__typename, id), UNIQUE (value))",+ ],+ ),+ (+ "records-check-constraint",+ vec![+ "DROP TABLE records",+ "CREATE TABLE records (__typename TEXT NOT NULL, id TEXT NOT NULL CHECK (id <> ''), value BLOB NOT NULL, PRIMARY KEY (__typename, id))",+ ],+ ),+ (+ "records-collation",+ vec![+ "DROP TABLE records",+ "CREATE TABLE records (__typename TEXT NOT NULL, id TEXT COLLATE NOCASE NOT NULL, value BLOB NOT NULL, PRIMARY KEY (__typename, id))",+ ],+ ),+ (+ "queue-autoincrement",+ vec![+ "DROP TABLE optimistic_layers",+ "DROP TABLE mutation_queue",+ "CREATE TABLE mutation_queue (id INTEGER PRIMARY KEY, 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_SCHEMA[3],+ ],+ ),+ (+ "queue-extra-foreign-key",+ vec![+ "DROP TABLE optimistic_layers",+ "DROP TABLE mutation_queue",+ "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, FOREIGN KEY (identity) REFERENCES meta(key))",+ CREATE_SCHEMA[3],+ ],+ ),+ (+ "queue-not-null",+ vec![+ "DROP TABLE optimistic_layers",+ "DROP TABLE mutation_queue",+ "CREATE TABLE mutation_queue (id INTEGER PRIMARY KEY AUTOINCREMENT, query TEXT, 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_SCHEMA[3],+ ],+ ),+ (+ "queue-default",+ vec![+ "DROP TABLE optimistic_layers",+ "DROP TABLE mutation_queue",+ "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 1, 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_SCHEMA[3],+ ],+ ),+ (+ "optimistic-primary-key",+ vec![+ "DROP TABLE optimistic_layers",+ "CREATE TABLE optimistic_layers (mutation_id INTEGER, optimistic_data_json TEXT NOT NULL, normalized_updates BLOB NOT NULL, FOREIGN KEY (mutation_id) REFERENCES mutation_queue(id) ON DELETE CASCADE)",+ ],+ ),+ (+ "optimistic-foreign-key",+ vec![+ "DROP TABLE optimistic_layers",+ "CREATE TABLE optimistic_layers (mutation_id INTEGER PRIMARY KEY, optimistic_data_json TEXT NOT NULL, normalized_updates BLOB NOT NULL)",+ ],+ ),+ (+ "optimistic-foreign-key-parent",+ vec![+ "DROP TABLE optimistic_layers",+ "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 records(id) ON DELETE CASCADE)",+ ],+ ),+ (+ "optimistic-foreign-key-from",+ vec![+ "DROP TABLE optimistic_layers",+ "CREATE TABLE optimistic_layers (mutation_id INTEGER PRIMARY KEY, optimistic_data_json TEXT NOT NULL, normalized_updates BLOB NOT NULL, FOREIGN KEY (optimistic_data_json) REFERENCES mutation_queue(id) ON DELETE CASCADE)",+ ],+ ),+ (+ "optimistic-foreign-key-to",+ vec![+ "DROP TABLE optimistic_layers",+ "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(query) ON DELETE CASCADE)",+ ],+ ),+ (+ "optimistic-cascade",+ vec![+ "DROP TABLE optimistic_layers",+ "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))",+ ],+ ),+ (+ "unexpected-table",+ vec!["CREATE TABLE unexpected_object (id INTEGER)"],+ ),+ (+ "unexpected-sequence-shaped-table",+ vec![+ "CREATE TABLE unexpected_sequence (value INTEGER PRIMARY KEY, is_called INTEGER, start INTEGER, inc INTEGER, min INTEGER, max INTEGER, cycle INTEGER)",+ ],+ ),+ (+ "unexpected-sqlite-sequence-shaped-table",+ vec!["CREATE TABLE unexpected_sqlite_sequence (name, seq)"],+ ),+ (+ "unexpected-index",+ vec!["CREATE INDEX records_value_index ON records(value)"],+ ),+ (+ "unexpected-unique-index",+ vec!["CREATE UNIQUE INDEX records_value_unique ON records(value)"],+ ),+ (+ "unexpected-partial-index",+ vec!["CREATE INDEX records_value_partial ON records(value) WHERE id <> ''"],+ ),+ ];++ for (name, statements) in cases {+ let database = TursoMemoryDatabase::new(format!("malformed-{name}.db"));+ let storage = database.open("scope").unwrap();+ for sql in statements {+ raw_execute(&storage, sql, Vec::new());+ }+ assert_eq!(+ storage.try_close().unwrap(),+ TursoStorageCloseOutcome::Healthy+ );+ let error = database.open("scope").unwrap_err();+ assert_eq!(+ error.physical_reset_reason(),+ Some(PhysicalResetReason::Compatibility),+ "case {name}: {error}"+ );+ database.physical_reset();+ }+}++#[test]+fn corrupt_keys_blobs_queue_relationships_and_numerics_request_reset() {+ block_on(async {+ let storage = TursoStorage::open_in_memory("corrupt-record").unwrap();+ raw_execute(+ &storage,+ RECORD_UPSERT,+ vec![text("Thing"), text("1"), Value::from_blob(vec![0xff, 0x00])],+ );+ let error = storage.get_batch(&[key("Thing:1")]).await.unwrap_err();+ assert_eq!(+ error.physical_reset_reason(),+ Some(PhysicalResetReason::Codec)+ );++ let storage = TursoStorage::open_in_memory("corrupt-key").unwrap();+ raw_execute(+ &storage,+ RECORD_UPSERT,+ vec![+ text(""),+ text("id"),+ Value::from_blob(encode_record(&record("valid"))),+ ],+ );+ let error = storage+ .scan_records(&[String::new()], None, 10)+ .await+ .unwrap_err();+ assert_eq!(+ error.physical_reset_reason(),+ Some(PhysicalResetReason::Corruption)+ );++ let storage = TursoStorage::open_in_memory("missing-layer").unwrap();+ raw_execute(+ &storage,+ "INSERT INTO mutation_queue (query, variables_json, created_at_ms) VALUES (?1, ?2, ?3)",+ vec![+ text("mutation Missing { x }"),+ text("{}"),+ Value::from_i64(0),+ ],+ );+ assert_eq!(+ storage+ .load_mutation_queue()+ .await+ .unwrap_err()+ .physical_reset_reason(),+ Some(PhysicalResetReason::Invariant)+ );++ let storage = TursoStorage::open_in_memory("orphan-layer").unwrap();+ raw_execute(&storage, "PRAGMA foreign_keys = OFF", Vec::new());+ raw_execute(+ &storage,+ LAYER_INSERT,+ vec![+ Value::from_i64(999),+ text("{}"),+ Value::from_blob(encode_record_updates(&RecordUpdates::default())),+ ],+ );+ raw_execute(&storage, "PRAGMA foreign_keys = ON", Vec::new());+ assert_eq!(raw_scalar(&storage, "PRAGMA foreign_keys"), 1);+ assert_eq!(+ storage+ .load_mutation_queue()+ .await+ .unwrap_err()+ .physical_reset_reason(),+ Some(PhysicalResetReason::Invariant)+ );++ let mut storage = TursoStorage::open_in_memory("corrupt-updates").unwrap();+ let id = storage.enqueue_mutation(queued("Corrupt")).await.unwrap();+ raw_execute(+ &storage,+ "UPDATE optimistic_layers SET normalized_updates = ?2 WHERE mutation_id = ?1",+ vec![+ Value::from_i64(mutation_id_to_sql(id).unwrap()),+ Value::from_blob(vec![0xff]),+ ],+ );+ assert_eq!(+ storage+ .load_mutation_queue()+ .await+ .unwrap_err()+ .physical_reset_reason(),+ Some(PhysicalResetReason::Codec)+ );++ for (name, column, value) in [+ ("negative-attempt", "attempt_count", -1),+ ("large-attempt", "attempt_count", i64::from(u32::MAX) + 1),+ ("negative-generation", "lease_generation", -1),+ ] {+ let mut storage = TursoStorage::open_in_memory(name).unwrap();+ let id = storage.enqueue_mutation(queued(name)).await.unwrap();+ raw_execute(+ &storage,+ &format!("UPDATE mutation_queue SET {column} = ?2 WHERE id = ?1"),+ vec![+ Value::from_i64(mutation_id_to_sql(id).unwrap()),+ Value::from_i64(value),+ ],+ );+ assert_eq!(+ storage+ .load_mutation_queue()+ .await+ .unwrap_err()+ .physical_reset_reason(),+ Some(PhysicalResetReason::Invariant)+ );+ }++ for invalid_id in [0, -1] {+ let storage =+ TursoStorage::open_in_memory(&format!("invalid-id-{invalid_id}")).unwrap();+ raw_execute(+ &storage,+ "INSERT INTO mutation_queue (id, query, variables_json, created_at_ms) VALUES (?1, ?2, ?3, ?4)",+ vec![+ Value::from_i64(invalid_id),+ text("mutation Invalid { x }"),+ text("{}"),+ Value::from_i64(0),+ ],+ );+ raw_execute(+ &storage,+ LAYER_INSERT,+ vec![+ Value::from_i64(invalid_id),+ text("{}"),+ Value::from_blob(encode_record_updates(&RecordUpdates::default())),+ ],+ );+ assert_eq!(+ storage+ .load_mutation_queue()+ .await+ .unwrap_err()+ .physical_reset_reason(),+ Some(PhysicalResetReason::Invariant)+ );+ }++ let mut storage = TursoStorage::open_in_memory("generation-overflow").unwrap();+ let id = storage+ .enqueue_mutation(queued("GenerationOverflow"))+ .await+ .unwrap();+ raw_execute(+ &storage,+ "UPDATE mutation_queue SET lease_generation = ?2 WHERE id = ?1",+ vec![+ Value::from_i64(mutation_id_to_sql(id).unwrap()),+ Value::from_i64(i64::MAX),+ ],+ );+ assert_eq!(+ storage+ .claim_next_mutation(MutationClaimRequest {+ owner: "runner".into(),+ now_ms: 1,+ lease_expires_at_ms: 2,+ })+ .await+ .unwrap_err()+ .physical_reset_reason(),+ Some(PhysicalResetReason::Invariant)+ );+ });+}++#[test]+fn reset_health_latch_blocks_every_method_without_touching_turso() {+ block_on(async {+ let mut storage = TursoStorage::open_in_memory("health-latch").unwrap();+ raw_execute(+ &storage,+ RECORD_UPSERT,+ vec![text("Thing"), text("1"), Value::from_blob(vec![0xff])],+ );+ expect_reset_reason(+ storage.get_batch(&[key("Thing:1")]).await,+ PhysicalResetReason::Codec,+ );++ driver::clear_control_trace();+ driver::arm_reset_failure(RECORD_GET);+ expect_every_storage_method_latched(&mut storage, PhysicalResetReason::Codec).await;+ assert!(driver::take_control_trace().is_empty());+ assert_eq!(+ storage.try_close().unwrap(),+ TursoStorageCloseOutcome::ResetRequired(PhysicalResetReason::Codec)+ );++ // The reset fault remains armed, proving the latched get did not even+ // prepare/reset its Turso statement.+ let probe = TursoStorage::open_in_memory("health-latch-probe").unwrap();+ expect_reset_reason(+ probe.get_batch(&[key("Thing:1")]).await,+ PhysicalResetReason::TransactionOutcomeUncertain,+ );+ assert_eq!(+ probe.try_close().unwrap(),+ TursoStorageCloseOutcome::ResetRequired(+ PhysicalResetReason::TransactionOutcomeUncertain+ )+ );+ });+}++#[test]+fn statement_cleanup_failures_are_uncertain_and_begin_cleanup_attempts_rollback() {+ block_on(async {+ for (name, sql) in [+ ("begin-reset", "BEGIN IMMEDIATE"),+ ("write-reset", RECORD_UPSERT),+ ] {+ let database = TursoMemoryDatabase::new(format!("{name}.db"));+ let mut storage = database.open("scope").unwrap();+ driver::clear_control_trace();+ driver::arm_reset_failure(sql);+ expect_reset_reason(+ storage+ .put_batch(vec![(key("Thing:1"), record("value"))])+ .await,+ PhysicalResetReason::TransactionOutcomeUncertain,+ );+ assert_eq!(+ driver::take_control_trace(),+ vec![+ driver::TestControlPhase::Begin,+ driver::TestControlPhase::Rollback,+ ],+ "case {name}"+ );++ driver::clear_control_trace();+ expect_reset_reason(+ storage.get_batch(&[key("Thing:1")]).await,+ PhysicalResetReason::TransactionOutcomeUncertain,+ );+ assert!(driver::take_control_trace().is_empty(), "case {name}");+ assert_eq!(+ storage.try_close().unwrap(),+ TursoStorageCloseOutcome::ResetRequired(+ PhysicalResetReason::TransactionOutcomeUncertain+ )+ );+ database.physical_reset();+ let replacement = database.open("scope").unwrap();+ assert_eq!(+ replacement.get_batch(&[key("Thing:1")]).await.unwrap(),+ vec![None]+ );+ assert_eq!(+ replacement.try_close().unwrap(),+ TursoStorageCloseOutcome::Healthy+ );+ }+ });+}++#[test]+fn completion_delivered_commit_failure_is_exact_and_not_reusable() {+ block_on(async {+ let io = FaultIo::new();+ let mut storage = fault_storage(io.clone());+ io.arm(IoFault::CommitCompletion);+ driver::clear_control_trace();+ expect_reset_reason(+ storage+ .put_batch(vec![(key("Thing:1"), record("value"))])+ .await,+ PhysicalResetReason::TransactionOutcomeUncertain,+ );+ assert!(io.is_clear(), "COMMIT did not observe its File completion");+ assert_eq!(+ driver::take_control_trace(),+ vec![+ driver::TestControlPhase::Begin,+ driver::TestControlPhase::Commit,+ driver::TestControlPhase::Rollback,+ ]+ );+ assert!(+ driver::take_control_io_trace().is_empty(),+ "the COMMIT Statement must observe the delivered completion directly"+ );++ driver::clear_control_trace();+ expect_reset_reason(+ storage.get_batch(&[key("Thing:1")]).await,+ PhysicalResetReason::TransactionOutcomeUncertain,+ );+ assert!(driver::take_control_trace().is_empty());+ assert!(driver::take_control_io_trace().is_empty());+ assert_eq!(+ storage.try_close().unwrap(),+ TursoStorageCloseOutcome::ResetRequired(+ PhysicalResetReason::TransactionOutcomeUncertain+ )+ );+ });+}++#[test]+fn rollback_io_step_polling_failure_is_exact_and_not_reusable() {+ block_on(async {+ let io = FaultIo::new();+ let mut storage = fault_storage(io.clone());+ storage.arm_fault(TestFault::RollbackIoStepAfter {+ site: TestFaultSite::Put,+ index: 0,+ fault_state: io.fault.clone(),+ fault_code: IoFault::RollbackIoStep as u8,+ });+ driver::clear_control_trace();+ expect_reset_reason(+ storage+ .put_batch(vec![(key("Thing:1"), record("value"))])+ .await,+ PhysicalResetReason::TransactionOutcomeUncertain,+ );+ assert!(io.is_clear(), "ROLLBACK did not poll the injected IO error");+ assert_eq!(+ driver::take_control_trace(),+ vec![+ driver::TestControlPhase::Begin,+ driver::TestControlPhase::Rollback,+ ]+ );+ assert_eq!(+ driver::take_control_io_trace(),+ vec![driver::TestControlPhase::Rollback]+ );++ driver::clear_control_trace();+ expect_reset_reason(+ storage.get_batch(&[key("Thing:1")]).await,+ PhysicalResetReason::TransactionOutcomeUncertain,+ );+ assert!(driver::take_control_trace().is_empty());+ assert!(driver::take_control_io_trace().is_empty());+ assert_eq!(+ storage.try_close().unwrap(),+ TursoStorageCloseOutcome::ResetRequired(+ PhysicalResetReason::TransactionOutcomeUncertain+ )+ );++ let replacement = fault_storage(FaultIo::new());+ assert_eq!(+ replacement.get_batch(&[key("Thing:1")]).await.unwrap(),+ vec![None]+ );+ assert!(replacement.load_mutation_queue().await.unwrap().is_empty());+ assert_eq!(+ replacement.try_close().unwrap(),+ TursoStorageCloseOutcome::Healthy+ );+ });+}++#[test]+fn operation_reset_classes_survive_successful_rollback_and_latching() {+ block_on(async {+ for reason in [PhysicalResetReason::StorageFull, PhysicalResetReason::Io] {+ let mut storage = TursoStorage::open_in_memory("preserved-reset-class").unwrap();+ storage.arm_fault(TestFault::ResetAfter {+ site: TestFaultSite::Put,+ index: 0,+ reason,+ });+ expect_reset_reason(+ storage+ .put_batch(vec![(key("Thing:1"), record("value"))])+ .await,+ reason,+ );+ expect_reset_reason(storage.get_batch(&[key("Thing:1")]).await, reason);+ assert_eq!(+ storage.try_close().unwrap(),+ TursoStorageCloseOutcome::ResetRequired(reason)+ );+ }+ });+}++#[test]+fn injected_statement_failures_roll_back_every_storage_boundary() {+ block_on(async {+ let mut storage = TursoStorage::open_in_memory("atomic-put").unwrap();+ storage.arm_fault(TestFault::After {+ site: TestFaultSite::Put,+ index: 0,+ });+ storage+ .put_batch(vec![+ (key("Thing:1"), record("one")),+ (key("Thing:2"), record("two")),+ ])+ .await+ .unwrap_err();+ assert_eq!(+ storage+ .get_batch(&[key("Thing:1"), key("Thing:2")])+ .await+ .unwrap(),+ vec![None, None]+ );++ storage+ .put_batch(vec![+ (key("Thing:1"), record("one")),+ (key("Thing:2"), record("two")),+ ])+ .await+ .unwrap();+ storage.arm_fault(TestFault::After {+ site: TestFaultSite::Delete,+ index: 0,+ });+ storage+ .delete_batch(&[key("Thing:1"), key("Thing:2")])+ .await+ .unwrap_err();+ assert_eq!(+ storage+ .get_batch(&[key("Thing:1"), key("Thing:2")])+ .await+ .unwrap(),+ vec![Some(record("one")), Some(record("two"))]+ );++ storage.arm_fault(TestFault::After {+ site: TestFaultSite::Enqueue,+ index: 0,+ });+ storage+ .enqueue_mutation(queued("Atomic"))+ .await+ .unwrap_err();+ assert!(storage.load_mutation_queue().await.unwrap().is_empty());++ let id = storage.enqueue_mutation(queued("Complete")).await.unwrap();+ let claimed = storage+ .claim_next_mutation(MutationClaimRequest {+ owner: "runner".into(),+ now_ms: 1,+ lease_expires_at_ms: 10,+ })+ .await+ .unwrap()+ .unwrap();+ storage.arm_fault(TestFault::After {+ site: TestFaultSite::Complete,+ index: 0,+ });+ storage+ .complete_mutation(+ id,+ token("runner", claimed.lease_generation),+ vec![+ (key("Result:1"), record("one")),+ (key("Result:2"), record("two")),+ ],+ )+ .await+ .unwrap_err();+ assert_eq!(+ storage+ .get_batch(&[key("Result:1"), key("Result:2")])+ .await+ .unwrap(),+ vec![None, None]+ );+ assert_eq!(storage.load_mutation_queue().await.unwrap().len(), 1);++ storage.arm_fault(TestFault::After {+ site: TestFaultSite::Discard,+ index: 0,+ });+ storage+ .discard_mutation(id, token("runner", claimed.lease_generation))+ .await+ .unwrap_err();+ assert_eq!(storage.load_mutation_queue().await.unwrap().len(), 1);++ storage.arm_fault(TestFault::After {+ site: TestFaultSite::Clear,+ index: 0,+ });+ storage.clear().await.unwrap_err();+ assert_eq!(storage.load_mutation_queue().await.unwrap().len(), 1);+ assert_eq!(+ storage.get_batch(&[key("Thing:1")]).await.unwrap(),+ vec![Some(record("one"))]+ );+ });+}++#[test]+fn corruption_quota_io_and_uncertain_transactions_have_payload_free_classes() {+ assert_eq!(+ TursoStorageError::turso(LimboError::Corrupt("secret payload".into()))+ .physical_reset_reason(),+ Some(PhysicalResetReason::Corruption)+ );+ assert_eq!(+ TursoStorageError::turso(LimboError::DatabaseFull("secret payload".into()))+ .physical_reset_reason(),+ Some(PhysicalResetReason::StorageFull)+ );+ assert_eq!(+ TursoStorageError::turso(LimboError::CompletionError(CompletionError::IOError(+ std::io::ErrorKind::StorageFull,+ "write",+ )))+ .physical_reset_reason(),+ Some(PhysicalResetReason::StorageFull)+ );+ assert_eq!(+ TursoStorageError::turso(LimboError::CompletionError(CompletionError::IOError(+ std::io::ErrorKind::Other,+ "sync",+ )))+ .physical_reset_reason(),+ Some(PhysicalResetReason::Io)+ );+ let error = TursoStorageError::reset(PhysicalResetReason::TransactionOutcomeUncertain);+ assert!(!error.to_string().contains("secret"));+}++#[derive(Clone, Copy)]+#[repr(u8)]+enum IoFault {+ None = 0,+ StorageFull = 1,+ Sync = 2,+ CommitCompletion = 3,+ RollbackIoStep = 4,+}++struct FaultIo {+ inner: MemoryIO,+ fault: Arc<AtomicU8>,+}++impl FaultIo {+ fn new() -> Arc<Self> {+ Arc::new(Self {+ inner: MemoryIO::new(),+ fault: Arc::new(AtomicU8::new(IoFault::None as u8)),+ })+ }++ fn arm(&self, fault: IoFault) {+ self.fault.store(fault as u8, Ordering::SeqCst);+ }++ fn take(&self, fault: IoFault) -> bool {+ self.fault+ .compare_exchange(+ fault as u8,+ IoFault::None as u8,+ Ordering::SeqCst,+ Ordering::SeqCst,+ )+ .is_ok()+ }++ fn is_clear(&self) -> bool {+ self.fault.load(Ordering::SeqCst) == IoFault::None as u8+ }+}++impl Clock for FaultIo {+ fn current_time_monotonic(&self) -> MonotonicInstant {+ self.inner.current_time_monotonic()+ }++ fn current_time_wall_clock(&self) -> WallClockInstant {+ self.inner.current_time_wall_clock()+ }+}++impl IO for FaultIo {+ fn open_file(+ &self,+ path: &str,+ flags: OpenFlags,+ direct: bool,+ ) -> turso_core::Result<Arc<dyn File>> {+ Ok(Arc::new(FaultFile {+ fault: self.fault.clone(),+ inner: self.inner.open_file(path, flags, direct)?,+ }))+ }++ fn remove_file(&self, path: &str) -> turso_core::Result<()> {+ self.inner.remove_file(path)+ }++ fn file_id(&self, path: &str) -> turso_core::Result<FileId> {+ self.inner.file_id(path)+ }++ fn supports_shared_wal_coordination(&self) -> bool {+ false+ }++ fn step(&self) -> turso_core::Result<()> {+ if driver::current_test_control_phase() == Some(driver::TestControlPhase::Rollback)+ && self.take(IoFault::RollbackIoStep)+ {+ return Err(CompletionError::IOError(+ std::io::ErrorKind::Other,+ "rollback IO::step polling",+ )+ .into());+ }+ self.inner.step()+ }+}++struct FaultFile {+ fault: Arc<AtomicU8>,+ inner: Arc<dyn File>,+}++impl FaultFile {+ fn take(&self, fault: IoFault) -> bool {+ self.fault+ .compare_exchange(+ fault as u8,+ IoFault::None as u8,+ Ordering::SeqCst,+ Ordering::SeqCst,+ )+ .is_ok()+ }++ fn deliver_commit_completion_error(&self, completion: &Completion) -> bool {+ if driver::current_test_control_phase() != Some(driver::TestControlPhase::Commit)+ || !self.take(IoFault::CommitCompletion)+ {+ return false;+ }+ // Deliver the failure through the File completion before returning;+ // the COMMIT Statement observes that completion directly. This is not+ // an IO::step error and no successful operation is later reclassified.+ completion.error(CompletionError::IOError(+ std::io::ErrorKind::Other,+ "commit completion delivery",+ ));+ true+ }+}++impl File for FaultFile {+ fn lock_file(&self, exclusive: bool) -> turso_core::Result<()> {+ self.inner.lock_file(exclusive)+ }++ fn unlock_file(&self) -> turso_core::Result<()> {+ self.inner.unlock_file()+ }++ fn pread(&self, pos: u64, completion: Completion) -> turso_core::Result<Completion> {+ self.inner.pread(pos, completion)+ }++ fn pwrite(+ &self,+ pos: u64,+ buffer: Arc<Buffer>,+ completion: Completion,+ ) -> turso_core::Result<Completion> {+ if self.deliver_commit_completion_error(&completion) {+ return Ok(completion);+ }+ if self.take(IoFault::StorageFull) {+ return Err(CompletionError::IOError(std::io::ErrorKind::StorageFull, "write").into());+ }+ self.inner.pwrite(pos, buffer, completion)+ }++ fn pwritev(+ &self,+ pos: u64,+ buffers: Vec<Arc<Buffer>>,+ completion: Completion,+ ) -> turso_core::Result<Completion> {+ if self.deliver_commit_completion_error(&completion) {+ return Ok(completion);+ }+ if self.take(IoFault::StorageFull) {+ return Err(CompletionError::IOError(std::io::ErrorKind::StorageFull, "writev").into());+ }+ self.inner.pwritev(pos, buffers, completion)+ }++ fn sync(+ &self,+ completion: Completion,+ sync_type: FileSyncType,+ ) -> turso_core::Result<Completion> {+ if self.deliver_commit_completion_error(&completion) {+ return Ok(completion);+ }+ if self.take(IoFault::Sync) {+ return Err(CompletionError::IOError(std::io::ErrorKind::Other, "sync").into());+ }+ self.inner.sync(completion, sync_type)+ }++ fn size(&self) -> turso_core::Result<u64> {+ self.inner.size()+ }++ fn truncate(&self, len: u64, completion: Completion) -> turso_core::Result<Completion> {+ if self.deliver_commit_completion_error(&completion) {+ return Ok(completion);+ }+ self.inner.truncate(len, completion)+ }++ fn has_hole(&self, pos: usize, len: usize) -> turso_core::Result<bool> {+ self.inner.has_hole(pos, len)+ }++ fn punch_hole(&self, pos: usize, len: usize) -> turso_core::Result<()> {+ self.inner.punch_hole(pos, len)+ }+}++fn fault_storage(io: Arc<FaultIo>) -> TursoStorage {+ static NEXT_FAULT_DATABASE: AtomicU64 = AtomicU64::new(1);+ let id = NEXT_FAULT_DATABASE.fetch_add(1, Ordering::Relaxed);+ let path = format!("fault-{id}.db");+ let io_trait: Arc<dyn IO> = io;+ let database =+ Database::open(io_trait, &path, OpenOptions::new(Arc::new(SqliteDialect))).unwrap();+ let connection = database.connect().unwrap();+ initialize(&connection, "fault-scope", true).unwrap();+ TursoStorage {+ health: AtomicU8::new(0),+ database,+ connection,+ fault: Mutex::new(None),+ }+}++#[test]+fn injected_memory_io_quota_and_sync_failures_require_reset() {+ block_on(async {+ for fault in [IoFault::StorageFull, IoFault::Sync] {+ // Both injected file failures are reached while COMMIT is in+ // flight, so the transaction outcome class takes precedence.+ let expected = PhysicalResetReason::TransactionOutcomeUncertain;+ let io = FaultIo::new();+ let mut storage = fault_storage(io.clone());+ io.arm(fault);+ expect_reset_reason(+ storage+ .put_batch(vec![(key("Thing:1"), record("value"))])+ .await,+ expected,+ );+ expect_reset_reason(storage.get_batch(&[key("Thing:1")]).await, expected);+ assert_eq!(+ storage.try_close().unwrap(),+ TursoStorageCloseOutcome::ResetRequired(expected)+ );+ }+ });+}diff --git a/crates/client/cache-turso/tests/engine_turso.rs b/crates/client/cache-turso/tests/engine_turso.rsnew file mode 100644index 0000000000..1147712a1d--- /dev/null+++ b/crates/client/cache-turso/tests/engine_turso.rs@@ -0,0 +1,356 @@+#![cfg(not(target_arch = "wasm32"))]++use cache_core::engine::{BeginOptimisticWrite, Engine, ReadResult};+use cache_core::queue::{MutationClaimRequest, MutationClaimToken};+use cache_core::record_selection::RecordSelection;+use cache_core::store::Storage;+use cache_core::value::{CacheValue, EntityKey, Record};+use cache_turso::{TursoMemoryDatabase, TursoStorage, TursoStorageCloseOutcome};+use pollster::block_on;+use serde_json::{Value as Json, json};++const QUERY: &str = r#"+query Soup($input: SoupInput!) {+ user {+ id+ soup(input: $input) {+ items {+ __typename+ id+ ... on GraphqlSoupDocument {+ properties {+ id+ displayName+ value {+ __typename+ ... on GraphqlStringPropertyValue { stringValue: value }+ }+ }+ }+ }+ nextCursor+ }+ }+}+"#;++const MUTATION: &str = r#"+mutation SetEntityProperty($input: SetEntityPropertyInput!) {+ setEntityProperty(input: $input) {+ id+ displayName+ value {+ __typename+ ... on GraphqlStringPropertyValue { stringValue: value }+ }+ }+}+"#;++fn query_vars() -> serde_json::Map<String, Json> {+ let Json::Object(values) = json!({"input": {"limit": 10}}) else {+ unreachable!()+ };+ values+}++fn mutation_vars(value: &str) -> serde_json::Map<String, Json> {+ let Json::Object(values) = json!({"input": {+ "entityType": "DOCUMENT",+ "entityId": "doc-1",+ "propertyDefinitionId": "definition-1",+ "value": {"string": value}+ }}) else {+ unreachable!()+ };+ values+}++fn page(display_name: &str, value: &str, user: &str) -> Json {+ json!({"user": {"id": user, "soup": {+ "items": [{+ "__typename": "GraphqlSoupDocument",+ "id": "doc-1",+ "properties": [{+ "id": "property-1",+ "displayName": display_name,+ "value": {+ "__typename": "GraphqlStringPropertyValue",+ "stringValue": value+ }+ }]+ }],+ "nextCursor": null+ }}})+}++fn mutation_response(display_name: &str, value: &str) -> Json {+ json!({"setEntityProperty": {+ "id": "property-1",+ "displayName": display_name,+ "value": {+ "__typename": "GraphqlStringPropertyValue",+ "stringValue": value+ }+ }})+}++async fn read_value(engine: &mut Engine<TursoStorage>) -> (String, String) {+ let ReadResult::Hit { data } = engine+ .read_query(None, QUERY, Some("Soup"), &query_vars())+ .await+ .unwrap()+ else {+ panic!("expected Turso-backed hit")+ };+ let property = &data["user"]["soup"]["items"][0]["properties"][0];+ (+ property["displayName"].as_str().unwrap().to_owned(),+ property["value"]["stringValue"]+ .as_str()+ .unwrap()+ .to_owned(),+ )+}++#[test]+fn query_identity_cold_tier_selection_and_clear_run_over_turso() {+ block_on(async {+ let storage = TursoStorage::open_in_memory("engine-query").unwrap();+ let mut engine = Engine::with_capacity(storage, 1);+ let original = page("Status", "todo", "user-1");+ engine+ .write_query(+ Some(1),+ QUERY,+ Some("Soup"),+ &query_vars(),+ &original,+ Some("user-1"),+ )+ .await+ .unwrap();+ assert_eq!(+ engine.current_identity().await.unwrap().as_deref(),+ Some("user-1")+ );+ assert_eq!(+ read_value(&mut engine).await,+ ("Status".into(), "todo".into())+ );++ let selection = RecordSelection::parse(+ "fragment Property on GraphqlProperty { id displayName }",+ "Property",+ )+ .unwrap();+ let selected = engine.read_records(&selection, None, 10).await.unwrap();+ assert_eq!(+ selected.records,+ vec![json!({"id": "property-1", "displayName": "Status"})]+ );++ let reset = engine+ .write_query(+ Some(2),+ QUERY,+ Some("Soup"),+ &query_vars(),+ &page("Other", "done", "user-2"),+ Some("user-2"),+ )+ .await+ .unwrap();+ assert!(reset.reset);+ assert_eq!(+ engine.current_identity().await.unwrap().as_deref(),+ Some("user-2")+ );+ engine.clear().await.unwrap();+ assert!(matches!(+ engine+ .read_query(None, QUERY, Some("Soup"), &query_vars())+ .await+ .unwrap(),+ ReadResult::Miss+ ));+ });+}++#[test]+fn optimistic_hydration_retry_complete_and_reopen_run_over_turso() {+ block_on(async {+ let database = TursoMemoryDatabase::new("engine-optimistic-reopen.db");+ let mut engine = Engine::new(database.open("engine-optimistic").unwrap());+ engine+ .write_query(+ None,+ QUERY,+ Some("Soup"),+ &query_vars(),+ &page("Status", "todo", "user-1"),+ Some("user-1"),+ )+ .await+ .unwrap();+ let (mutation_id, _) = engine+ .begin_optimistic_write(+ None,+ BeginOptimisticWrite {+ query: MUTATION,+ operation_name: Some("SetEntityProperty"),+ variables: &mutation_vars("doing"),+ data: &mutation_response("Status", "doing"),+ link_patches: &[],+ revalidations: &[],+ created_at_ms: 10,+ },+ )+ .await+ .unwrap();+ assert_eq!(read_value(&mut engine).await.1, "doing");+ assert_eq!(+ engine.into_storage().try_close().unwrap(),+ TursoStorageCloseOutcome::Healthy+ );++ let mut reopened = Engine::new(database.open("engine-optimistic").unwrap());+ assert_eq!(read_value(&mut reopened).await.1, "doing");+ let first_claim = reopened+ .claim_next_mutation(MutationClaimRequest {+ owner: "runner-a".into(),+ now_ms: 20,+ lease_expires_at_ms: 100,+ })+ .await+ .unwrap()+ .unwrap();+ reopened+ .defer_optimistic_write(+ mutation_id,+ MutationClaimToken {+ owner: "runner-a".into(),+ generation: first_claim.lease_generation,+ },+ 200,+ "offline".into(),+ )+ .await+ .unwrap();+ assert!(+ reopened+ .claim_next_mutation(MutationClaimRequest {+ owner: "runner-b".into(),+ now_ms: 199,+ lease_expires_at_ms: 300,+ })+ .await+ .unwrap()+ .is_none()+ );+ let second_claim = reopened+ .claim_next_mutation(MutationClaimRequest {+ owner: "runner-b".into(),+ now_ms: 200,+ lease_expires_at_ms: 300,+ })+ .await+ .unwrap()+ .unwrap();+ reopened+ .commit_optimistic_write(+ mutation_id,+ MutationClaimToken {+ owner: "runner-b".into(),+ generation: second_claim.lease_generation,+ },+ MUTATION,+ Some("SetEntityProperty"),+ &mutation_vars("done"),+ &mutation_response("Status (server)", "done"),+ )+ .await+ .unwrap();+ assert_eq!(+ read_value(&mut reopened).await,+ ("Status (server)".into(), "done".into())+ );+ assert!(+ reopened+ .storage()+ .load_mutation_queue()+ .await+ .unwrap()+ .is_empty()+ );+ assert_eq!(+ reopened.into_storage().try_close().unwrap(),+ TursoStorageCloseOutcome::Healthy+ );+ });+}++#[test]+fn optimistic_discard_restores_durable_base_over_turso() {+ block_on(async {+ let storage = TursoStorage::open_in_memory("engine-discard").unwrap();+ let mut engine = Engine::new(storage);+ engine+ .write_query(+ None,+ QUERY,+ Some("Soup"),+ &query_vars(),+ &page("Status", "todo", "user-1"),+ None,+ )+ .await+ .unwrap();+ let (mutation_id, _) = engine+ .begin_optimistic_write(+ None,+ BeginOptimisticWrite {+ query: MUTATION,+ operation_name: Some("SetEntityProperty"),+ variables: &mutation_vars("bad"),+ data: &mutation_response("Status", "bad"),+ link_patches: &[],+ revalidations: &[],+ created_at_ms: 1,+ },+ )+ .await+ .unwrap();+ let claimed = engine+ .claim_next_mutation(MutationClaimRequest {+ owner: "runner".into(),+ now_ms: 2,+ lease_expires_at_ms: 100,+ })+ .await+ .unwrap()+ .unwrap();+ engine+ .rollback_optimistic_write(+ mutation_id,+ MutationClaimToken {+ owner: "runner".into(),+ generation: claimed.lease_generation,+ },+ )+ .await+ .unwrap();+ assert_eq!(read_value(&mut engine).await.1, "todo");++ let records = engine+ .storage()+ .get_batch(&[EntityKey("GraphqlProperty:property-1".into())])+ .await+ .unwrap();+ let record: &Record = records[0].as_ref().unwrap();+ let CacheValue::Object(value) = record.fields.get("value").unwrap() else {+ panic!("property value object")+ };+ assert_eq!(value.get("value"), Some(&CacheValue::String("todo".into())));+ });+}diff --git a/crates/client/cache-turso/tests/shared_conformance.rs b/crates/client/cache-turso/tests/shared_conformance.rsnew file mode 100644index 0000000000..c3eb8c233e--- /dev/null+++ b/crates/client/cache-turso/tests/shared_conformance.rs@@ -0,0 +1,697 @@+#![cfg(not(target_arch = "wasm32"))]++use cache_core::normalize::RecordUpdates;+use cache_core::queue::{+ MutationClaimRequest, MutationClaimToken, MutationRequest, NewQueuedMutation,+ PersistedOptimisticLayer, StoredMutation,+};+use cache_core::store::{InMemoryStorage, Storage};+use cache_core::value::{CacheValue, EntityKey, Record};+use cache_sqlite::SqliteStorage;+use cache_turso::{TursoMemoryDatabase, TursoStorage, TursoStorageCloseOutcome};+use pollster::block_on;+use std::path::PathBuf;+use std::sync::atomic::{AtomicU64, Ordering};++trait BackendFactory: Sized {+ type Backend: Storage;++ fn create() -> (Self, Self::Backend);+ fn reopen(&mut self, storage: Self::Backend) -> Self::Backend;+ fn finish(self, storage: Self::Backend);+}++struct InMemoryFactory;++impl BackendFactory for InMemoryFactory {+ type Backend = InMemoryStorage;++ fn create() -> (Self, Self::Backend) {+ (Self, InMemoryStorage::new())+ }++ fn reopen(&mut self, storage: Self::Backend) -> Self::Backend {+ storage+ }++ fn finish(self, _: Self::Backend) {}+}++struct SqliteFactory {+ path: PathBuf,+}++impl BackendFactory for SqliteFactory {+ type Backend = SqliteStorage;++ fn create() -> (Self, Self::Backend) {+ static NEXT_DATABASE: AtomicU64 = AtomicU64::new(1);+ let id = NEXT_DATABASE.fetch_add(1, Ordering::Relaxed);+ let path = std::env::temp_dir().join(format!(+ "cache-turso-shared-conformance-{}-{id}.db",+ std::process::id()+ ));+ let _ = std::fs::remove_file(&path);+ let storage = SqliteStorage::open(&path, "shared-conformance").unwrap();+ (Self { path }, storage)+ }++ fn reopen(&mut self, storage: Self::Backend) -> Self::Backend {+ drop(storage);+ SqliteStorage::open(&self.path, "shared-conformance").unwrap()+ }++ fn finish(self, storage: Self::Backend) {+ drop(storage);+ std::fs::remove_file(self.path).unwrap();+ }+}++struct TursoFactory {+ database: TursoMemoryDatabase,+}++impl BackendFactory for TursoFactory {+ type Backend = TursoStorage;++ fn create() -> (Self, Self::Backend) {+ let database = TursoMemoryDatabase::new("shared-conformance.db");+ let storage = database.open("shared-conformance").unwrap();+ (Self { database }, storage)+ }++ fn reopen(&mut self, storage: Self::Backend) -> Self::Backend {+ assert_eq!(+ storage.try_close().unwrap(),+ TursoStorageCloseOutcome::Healthy+ );+ self.database.open("shared-conformance").unwrap()+ }++ fn finish(self, storage: Self::Backend) {+ assert_eq!(+ storage.try_close().unwrap(),+ TursoStorageCloseOutcome::Healthy+ );+ }+}++fn key(value: &str) -> EntityKey<'static> {+ EntityKey(value.to_owned().into())+}++fn record(value: &str) -> Record {+ let mut record = Record::default();+ record+ .fields+ .insert("value".into(), CacheValue::String(value.into()));+ record+}++fn queued(label: &str) -> NewQueuedMutation {+ NewQueuedMutation {+ mutation: StoredMutation::new(+ MutationRequest {+ query: format!("mutation {label} {{ update {{ id }} }}"),+ operation_name: Some(label.into()),+ variables_json: "{}".into(),+ identity: None,+ },+ 1,+ ),+ optimistic: PersistedOptimisticLayer {+ optimistic_data_json: "{}".into(),+ normalized_updates: RecordUpdates::default(),+ },+ }+}++fn fully_populated_queued() -> NewQueuedMutation {+ NewQueuedMutation {+ mutation: StoredMutation {+ request: MutationRequest {+ query: "mutation Full($id: ID!) { update(id: $id) { id } }".into(),+ operation_name: Some("Full".into()),+ variables_json: r#"{"id":"full"}"#.into(),+ identity: Some("identity-witness".into()),+ },+ attempt_count: 7,+ next_attempt_at_ms: Some(-2),+ lease_owner: Some("expired-owner".into()),+ lease_generation: 11,+ lease_expires_at_ms: Some(-1),+ last_error: Some("previous retry".into()),+ created_at_ms: -3,+ },+ optimistic: PersistedOptimisticLayer {+ optimistic_data_json: r#"{"update":{"id":"full"}}"#.into(),+ normalized_updates: RecordUpdates::from([(+ key("Optimistic:full"),+ record("optimistic-full"),+ )]),+ },+ }+}++fn token(owner: &str, generation: u64) -> MutationClaimToken {+ MutationClaimToken {+ owner: owner.into(),+ generation,+ }+}++fn claim_request(owner: &str, now_ms: i64, lease_expires_at_ms: i64) -> MutationClaimRequest {+ MutationClaimRequest {+ owner: owner.into(),+ now_ms,+ lease_expires_at_ms,+ }+}++async fn scan_keys<S: Storage>(+ storage: &S,+ type_names: &[String],+ after: Option<&EntityKey<'static>>,+ limit: usize,+) -> Vec<String> {+ storage+ .scan_records(type_names, after, limit)+ .await+ .unwrap()+ .into_iter()+ .map(|(key, _)| key.as_ref().to_owned())+ .collect()+}++async fn record_contract<S: Storage>(storage: &mut S) {+ storage+ .put_batch(vec![+ (key("ROOT_QUERY"), record("root")),+ (key("__meta:identity"), record("meta")),+ (key("Thing:"), record("empty-id")),+ (key("Type:9"), record("type-9")),+ (key("Type0:1"), record("type0-1")),+ (key("Other:1"), record("other")),+ (key("Type:0"), record("type-0")),+ (key("Type0:0"), record("type0-first")),+ (key("Type:a"), record("type-a")),+ (key("Type:a:colon"), record("colon-id")),+ (key("Type:a:colon:again"), record("multiple-colon-id")),+ (key("Type0:0"), record("type0-last")),+ ])+ .await+ .unwrap();++ let aligned = storage+ .get_batch(&[+ key("Missing:leading"),+ key("ROOT_QUERY"),+ key("__meta:identity"),+ key("Thing:"),+ key("Type:a:colon:again"),+ key("Missing:middle"),+ key("Type0:0"),+ key("Type0:0"),+ key("Missing:trailing"),+ ])+ .await+ .unwrap();+ assert_eq!(+ aligned,+ vec![+ None,+ Some(record("root")),+ Some(record("meta")),+ Some(record("empty-id")),+ Some(record("multiple-colon-id")),+ None,+ Some(record("type0-last")),+ Some(record("type0-last")),+ None,+ ]+ );++ let names = ["Type".to_owned(), "Type0".to_owned(), "Type".to_owned()];+ let mut rust_sorted = [+ key("Type:9"),+ key("Type0:1"),+ key("Type:0"),+ key("Type0:0"),+ key("Type:a"),+ key("Type:a:colon"),+ key("Type:a:colon:again"),+ ];+ rust_sorted.sort();+ let expected = rust_sorted+ .iter()+ .map(|key| key.as_ref().to_owned())+ .collect::<Vec<_>>();+ assert!(scan_keys(storage, &[], None, 10).await.is_empty());+ assert!(scan_keys(storage, &names, None, 0).await.is_empty());+ assert_eq!(scan_keys(storage, &names, None, 10).await, expected);+ assert_eq!(+ scan_keys(storage, &names, Some(&key("A:0")), 10).await,+ expected+ );+ assert_eq!(+ scan_keys(storage, &names, Some(&key("Type0:0")), 10).await,+ [+ "Type0:1",+ "Type:0",+ "Type:9",+ "Type:a",+ "Type:a:colon",+ "Type:a:colon:again",+ ]+ );+ assert_eq!(+ scan_keys(storage, &names, Some(&key("Type0:0z")), 10).await,+ [+ "Type0:1",+ "Type:0",+ "Type:9",+ "Type:a",+ "Type:a:colon",+ "Type:a:colon:again",+ ]+ );+ assert_eq!(+ scan_keys(storage, &names, Some(&key("Type0:1")), 10).await,+ [+ "Type:0",+ "Type:9",+ "Type:a",+ "Type:a:colon",+ "Type:a:colon:again",+ ]+ );+ assert_eq!(+ scan_keys(storage, &names, Some(&key("Type0:zz")), 10).await,+ [+ "Type:0",+ "Type:9",+ "Type:a",+ "Type:a:colon",+ "Type:a:colon:again",+ ]+ );+ assert_eq!(+ scan_keys(storage, &names, Some(&key("Type:0")), 1).await,+ ["Type:9"]+ );+ assert_eq!(+ scan_keys(storage, &names, Some(&key("Type:9")), 10).await,+ ["Type:a", "Type:a:colon", "Type:a:colon:again"]+ );+ assert_eq!(+ scan_keys(storage, &names, Some(&key("Type:a")), 10).await,+ ["Type:a:colon", "Type:a:colon:again"]+ );+ assert_eq!(+ scan_keys(storage, &names, Some(&key("Type:a:colon")), 10).await,+ ["Type:a:colon:again"]+ );+ assert!(+ scan_keys(storage, &names, Some(&key("Type:a:colon:again")), 10,)+ .await+ .is_empty()+ );+ assert!(+ scan_keys(storage, &names, Some(&key("Z:9")), 10)+ .await+ .is_empty()+ );++ for limit in [1, 2] {+ let mut cursor = None;+ let mut paged = Vec::new();+ loop {+ let page = storage+ .scan_records(&names, cursor.as_ref(), limit)+ .await+ .unwrap();+ assert!(page.len() <= limit);+ let Some((last, _)) = page.last() else {+ break;+ };+ cursor = Some(last.clone());+ paged.extend(page.into_iter().map(|(key, _)| key.as_ref().to_owned()));+ }+ assert_eq!(paged, expected);+ }++ storage+ .delete_batch(&[key("Missing:delete"), key("Type:a"), key("Type:a")])+ .await+ .unwrap();+ assert_eq!(storage.get_batch(&[key("Type:a")]).await.unwrap(), [None]);+ storage.delete_batch(&[]).await.unwrap();+ storage+ .put_batch(vec![(key("Type:a"), record("restored"))])+ .await+ .unwrap();+}++async fn reopen_contract<F: BackendFactory>(+ factory: &mut F,+ mut storage: F::Backend,+) -> F::Backend {+ let first_entry = fully_populated_queued();+ let second_entry = queued("ReopenSecond");+ let first = storage.enqueue_mutation(first_entry.clone()).await.unwrap();+ let second = storage+ .enqueue_mutation(second_entry.clone())+ .await+ .unwrap();+ assert!(second > first);++ let mut storage = factory.reopen(storage);+ assert_eq!(+ storage+ .get_batch(&[key("ROOT_QUERY"), key("Type:9"), key("Type:a:colon:again"),])+ .await+ .unwrap(),+ [+ Some(record("root")),+ Some(record("type-9")),+ Some(record("multiple-colon-id")),+ ]+ );+ let loaded = storage.load_mutation_queue().await.unwrap();+ assert_eq!(+ loaded.iter().map(|entry| entry.id).collect::<Vec<_>>(),+ [first, second]+ );+ assert_eq!(loaded[0].mutation, first_entry.mutation);+ assert_eq!(loaded[0].optimistic, first_entry.optimistic);+ assert_eq!(loaded[1].mutation, second_entry.mutation);+ assert_eq!(loaded[1].optimistic, second_entry.optimistic);++ let first_claim = storage+ .claim_next_mutation(claim_request("reopen-first", 0, 1))+ .await+ .unwrap()+ .unwrap();+ assert_eq!(first_claim.queued.mutation.attempt_count, 8);+ assert_eq!(first_claim.lease_generation, 12);+ assert!(+ storage+ .discard_mutation(first, token("reopen-first", 12))+ .await+ .unwrap()+ );+ let second_claim = storage+ .claim_next_mutation(claim_request("reopen-second", 0, 1))+ .await+ .unwrap()+ .unwrap();+ assert_eq!(second_claim.queued.id, second);+ assert!(+ storage+ .discard_mutation(+ second,+ token("reopen-second", second_claim.lease_generation),+ )+ .await+ .unwrap()+ );+ assert!(storage.load_mutation_queue().await.unwrap().is_empty());+ assert_eq!(+ storage.get_batch(&[key("Type:9")]).await.unwrap(),+ [Some(record("type-9"))],+ "discard must not change existing records"+ );+ storage+}++async fn queue_contract<S: Storage>(storage: &mut S) {+ assert!(storage.load_mutation_queue().await.unwrap().is_empty());+ assert_eq!(+ storage.queue_diagnostics().await.unwrap(),+ cache_core::store::QueueDiagnostics {+ availability: cache_core::store::QueueDiagnosticsAvailability::Available,+ depth: 0,+ oldest_created_at_ms: None,+ }+ );+ assert!(+ storage+ .claim_next_mutation(claim_request("empty", 0, 1))+ .await+ .unwrap()+ .is_none()+ );++ let absent = token("absent", 1);+ assert!(+ !storage+ .defer_mutation(999, absent.clone(), 2, "absent".into())+ .await+ .unwrap()+ );+ assert!(+ !storage+ .complete_mutation(999, absent.clone(), Vec::new())+ .await+ .unwrap()+ );+ assert!(!storage.discard_mutation(999, absent).await.unwrap());++ let first = storage.enqueue_mutation(queued("First")).await.unwrap();+ let second = storage.enqueue_mutation(queued("Second")).await.unwrap();+ assert!(second > first);+ assert_eq!(+ storage.queue_diagnostics().await.unwrap(),+ cache_core::store::QueueDiagnostics {+ availability: cache_core::store::QueueDiagnosticsAvailability::Available,+ depth: 2,+ oldest_created_at_ms: Some(1),+ }+ );+ let first_claim = storage+ .claim_next_mutation(claim_request("runner-a", 1, 10))+ .await+ .unwrap()+ .unwrap();+ assert_eq!(first_claim.queued.id, first);+ assert_eq!(first_claim.queued.mutation.attempt_count, 1);+ assert_eq!(first_claim.lease_generation, 1);+ assert!(+ storage+ .claim_next_mutation(claim_request("runner-b", 9, 20))+ .await+ .unwrap()+ .is_none(),+ "a leased strict head must block the second row"+ );+ let expired_reclaim = storage+ .claim_next_mutation(claim_request("runner-b", 10, 15))+ .await+ .unwrap()+ .unwrap();+ assert_eq!(expired_reclaim.queued.id, first);+ assert_eq!(expired_reclaim.queued.mutation.attempt_count, 2);+ assert_eq!(expired_reclaim.lease_generation, 2);+ assert!(+ !storage+ .defer_mutation(+ first,+ token("runner-a", first_claim.lease_generation),+ 20,+ "stale".into(),+ )+ .await+ .unwrap()+ );+ assert!(+ !storage+ .discard_mutation(first, token("runner-a", first_claim.lease_generation))+ .await+ .unwrap()+ );+ assert!(+ storage+ .defer_mutation(+ first,+ token("runner-b", expired_reclaim.lease_generation),+ 20,+ "retry".into(),+ )+ .await+ .unwrap()+ );+ let deferred = storage.load_mutation_queue().await.unwrap();+ assert_eq!(deferred.len(), 2);+ assert_eq!(deferred[0].id, first);+ assert_eq!(deferred[0].mutation.attempt_count, 2);+ assert_eq!(deferred[0].mutation.next_attempt_at_ms, Some(20));+ assert_eq!(deferred[0].mutation.lease_owner, None);+ assert_eq!(deferred[0].mutation.lease_expires_at_ms, None);+ assert_eq!(deferred[0].mutation.lease_generation, 2);+ assert_eq!(deferred[0].mutation.last_error.as_deref(), Some("retry"));+ assert!(+ storage+ .claim_next_mutation(claim_request("runner-c", 19, 30))+ .await+ .unwrap()+ .is_none(),+ "a deferred strict head must block the second row"+ );++ let retry_claim = storage+ .claim_next_mutation(claim_request("runner-c", 20, 30))+ .await+ .unwrap()+ .unwrap();+ assert_eq!(retry_claim.queued.id, first);+ assert_eq!(retry_claim.queued.mutation.attempt_count, 3);+ assert_eq!(retry_claim.lease_generation, 3);+ assert!(+ !storage+ .discard_mutation(first, token("runner-b", expired_reclaim.lease_generation))+ .await+ .unwrap()+ );+ assert!(+ storage+ .discard_mutation(first, token("runner-c", retry_claim.lease_generation))+ .await+ .unwrap()+ );++ let second_claim = storage+ .claim_next_mutation(claim_request("runner-d", 20, 25))+ .await+ .unwrap()+ .unwrap();+ assert_eq!(second_claim.queued.id, second);+ assert_eq!(second_claim.queued.mutation.attempt_count, 1);+ assert!(+ storage+ .defer_mutation(+ second,+ token("runner-d", second_claim.lease_generation),+ 30,+ "second retry".into(),+ )+ .await+ .unwrap()+ );+ assert!(+ storage+ .claim_next_mutation(claim_request("runner-e", 29, 40))+ .await+ .unwrap()+ .is_none()+ );+ let second_retry = storage+ .claim_next_mutation(claim_request("runner-e", 30, 40))+ .await+ .unwrap()+ .unwrap();+ assert_eq!(second_retry.queued.id, second);+ assert_eq!(second_retry.queued.mutation.attempt_count, 2);+ assert!(+ !storage+ .complete_mutation(+ second,+ token("runner-d", second_claim.lease_generation),+ vec![(key("Result:stale"), record("must-not-write"))],+ )+ .await+ .unwrap()+ );+ assert_eq!(+ storage.get_batch(&[key("Result:stale")]).await.unwrap(),+ [None]+ );+ assert!(+ storage+ .complete_mutation(+ second,+ token("runner-e", second_retry.lease_generation),+ vec![(key("Result:complete"), record("committed"))],+ )+ .await+ .unwrap()+ );+ assert_eq!(+ storage.get_batch(&[key("Result:complete")]).await.unwrap(),+ [Some(record("committed"))]+ );+ assert!(storage.load_mutation_queue().await.unwrap().is_empty());+ assert!(+ storage+ .claim_next_mutation(claim_request("empty-again", 40, 50))+ .await+ .unwrap()+ .is_none()+ );+}++async fn clear_contract<S: Storage>(storage: &mut S) {+ let before_clear = storage.enqueue_mutation(queued("Clear")).await.unwrap();+ storage.clear().await.unwrap();+ assert!(storage.load_mutation_queue().await.unwrap().is_empty());+ assert_eq!(+ storage+ .get_batch(&[+ key("ROOT_QUERY"),+ key("__meta:identity"),+ key("Thing:"),+ key("Type0:0"),+ key("Type:9"),+ key("Other:1"),+ key("Result:complete"),+ ])+ .await+ .unwrap(),+ [None, None, None, None, None, None, None]+ );+ assert!(+ storage+ .claim_next_mutation(claim_request("after-clear", 50, 60))+ .await+ .unwrap()+ .is_none()+ );+ let after_clear = storage+ .enqueue_mutation(queued("AfterClear"))+ .await+ .unwrap();+ assert!(after_clear > before_clear);+ storage.clear().await.unwrap();+ assert!(storage.load_mutation_queue().await.unwrap().is_empty());+}++async fn common_contract<F: BackendFactory>(+ factory: &mut F,+ mut storage: F::Backend,+) -> F::Backend {+ record_contract(&mut storage).await;+ let mut storage = reopen_contract(factory, storage).await;+ queue_contract(&mut storage).await;+ clear_contract(&mut storage).await;+ storage+}++fn run<F: BackendFactory>() {+ let (mut factory, storage) = F::create();+ let storage = block_on(common_contract(&mut factory, storage));+ factory.finish(storage);+}++#[test]+fn in_memory_storage_satisfies_shared_contract() {+ run::<InMemoryFactory>();+}++#[test]+fn sqlite_storage_satisfies_shared_contract() {+ run::<SqliteFactory>();+}++#[test]+fn turso_storage_satisfies_shared_contract() {+ run::<TursoFactory>();+}diff --git a/crates/client/cache-turso/tests/storage_conformance.rs b/crates/client/cache-turso/tests/storage_conformance.rsnew file mode 100644index 0000000000..8d0fc73afe--- /dev/null+++ b/crates/client/cache-turso/tests/storage_conformance.rs@@ -0,0 +1,515 @@+#![cfg(not(target_arch = "wasm32"))]++use cache_core::meta::TYPES;+use cache_core::normalize::RecordUpdates;+use cache_core::queue::{+ MutationClaimRequest, MutationClaimToken, MutationRequest, NewQueuedMutation,+ PersistedOptimisticLayer, StoredMutation,+};+use cache_core::store::Storage;+use cache_core::value::{CacheValue, EntityKey, Record};+use cache_turso::{TursoMemoryDatabase, TursoStorage};+use pollster::block_on;++fn key(value: &str) -> EntityKey<'static> {+ EntityKey(value.to_owned().into())+}++fn record(value: &str) -> Record {+ let mut record = Record::default();+ record+ .fields+ .insert("value".into(), CacheValue::String(value.into()));+ record+}++fn queued(label: &str, created_at_ms: i64) -> NewQueuedMutation {+ let mut update = Record::default();+ update+ .fields+ .insert("value".into(), CacheValue::String(label.into()));+ NewQueuedMutation {+ mutation: StoredMutation {+ request: MutationRequest {+ query: format!("mutation {label} {{ update {{ id }} }}"),+ operation_name: Some(label.into()),+ variables_json: format!(r#"{{"label":"{label}"}}"#),+ identity: Some("identity-witness".into()),+ },+ attempt_count: 7,+ next_attempt_at_ms: None,+ lease_owner: None,+ lease_generation: 11,+ lease_expires_at_ms: None,+ last_error: Some("previous retry".into()),+ created_at_ms,+ },+ optimistic: PersistedOptimisticLayer {+ optimistic_data_json: format!(r#"{{"update":{{"label":"{label}"}}}}"#),+ normalized_updates: RecordUpdates::from([(key("Thing:1"), update)]),+ },+ }+}++fn claim(owner: &str, generation: u64) -> MutationClaimToken {+ MutationClaimToken {+ owner: owner.into(),+ generation,+ }+}++#[test]+fn compound_keys_batches_duplicates_and_checked_inputs_conform() {+ block_on(async {+ let mut storage = TursoStorage::open_in_memory("scope-batches").unwrap();+ let valid = [+ "ROOT_QUERY",+ "GraphqlSoupDocument:doc-1",+ "GraphqlSoupDocument:tenant:doc-1",+ "__meta:identity",+ "Thing:",+ ];+ storage+ .put_batch(+ valid+ .iter()+ .enumerate()+ .map(|(index, value)| (key(value), record(&index.to_string())))+ .collect(),+ )+ .await+ .unwrap();++ let requested = [+ key("Missing:leading"),+ key(valid[1]),+ key("Missing:middle"),+ key(valid[1]),+ key(valid[4]),+ key("Missing:trailing"),+ ];+ let values = storage.get_batch(&requested).await.unwrap();+ assert_eq!(values.len(), requested.len());+ assert!(values[0].is_none());+ assert_eq!(values[1], Some(record("1")));+ assert!(values[2].is_none());+ assert_eq!(values[3], values[1]);+ assert_eq!(values[4], Some(record("4")));+ assert!(values[5].is_none());++ storage+ .put_batch(vec![+ (key("Duplicate:1"), record("first")),+ (key("Duplicate:1"), record("last")),+ ])+ .await+ .unwrap();+ assert_eq!(+ storage.get_batch(&[key("Duplicate:1")]).await.unwrap(),+ vec![Some(record("last"))]+ );+ storage+ .delete_batch(&[+ key("Missing:delete"),+ key("Duplicate:1"),+ key("Duplicate:1"),+ ])+ .await+ .unwrap();+ assert_eq!(+ storage.get_batch(&[key("Duplicate:1")]).await.unwrap(),+ vec![None]+ );++ for invalid in ["", "Colonless", ":id", "ROOT_QUERY:"] {+ let error = storage+ .put_batch(vec![(key(invalid), record("invalid"))])+ .await+ .unwrap_err();+ assert!(!error.requires_physical_reset());+ }+ storage.try_close().unwrap();+ });+}++#[test]+fn canonical_binary_scan_has_global_exclusive_cursor_and_dynamic_in() {+ block_on(async {+ let mut storage = TursoStorage::open_in_memory("scope-scan").unwrap();+ let values = [+ "ROOT_QUERY",+ "Type:9",+ "Type0:1",+ "Type:a:colon",+ "Type:tenant:item",+ "Other:1",+ "__meta:identity",+ ];+ storage+ .put_batch(+ values+ .iter()+ .map(|value| (key(value), record(value)))+ .collect(),+ )+ .await+ .unwrap();++ assert!(+ storage+ .scan_records(&[], None, 10)+ .await+ .unwrap()+ .is_empty()+ );+ assert!(+ storage+ .scan_records(&["Type".into()], None, 0)+ .await+ .unwrap()+ .is_empty()+ );+ let names = ["Type0".into(), "Type".into(), "Type".into()];+ let expected = ["Type0:1", "Type:9", "Type:a:colon", "Type:tenant:item"];+ let all = storage.scan_records(&names, None, 20).await.unwrap();+ assert_eq!(+ all.iter().map(|(key, _)| key.as_ref()).collect::<Vec<_>>(),+ expected+ );++ let mut cursor = None;+ let mut paged = Vec::new();+ loop {+ let page = storage+ .scan_records(&names, cursor.as_ref(), 1)+ .await+ .unwrap();+ let Some((last, _)) = page.last() else {+ break;+ };+ cursor = Some(last.clone());+ paged.extend(page.into_iter().map(|(key, _)| key));+ }+ assert_eq!(+ paged.iter().map(EntityKey::as_ref).collect::<Vec<_>>(),+ expected+ );+ assert!(+ storage+ .scan_records(&names, Some(&key("Unselected:zz")), 2)+ .await+ .unwrap()+ .is_empty()+ );++ let maximum_types = TYPES+ .iter()+ .map(|metadata| metadata.name.to_owned())+ .collect::<Vec<_>>();+ storage+ .scan_records(&maximum_types, None, usize::MAX.min(i64::MAX as usize))+ .await+ .unwrap();+ storage.try_close().unwrap();+ });+}++#[test]+fn queue_preserves_every_field_order_and_reopen_state() {+ block_on(async {+ let database = TursoMemoryDatabase::new("queue-reopen.db");+ let mut storage = database.open("scope-queue-reopen").unwrap();+ let mut first_entry = queued("First", 100);+ first_entry.mutation.next_attempt_at_ms = Some(150);+ first_entry.mutation.lease_owner = Some("reopen-owner".into());+ first_entry.mutation.lease_expires_at_ms = Some(175);+ let second_entry = NewQueuedMutation {+ mutation: StoredMutation::new(+ MutationRequest {+ query: "mutation Second { update { id } }".into(),+ operation_name: None,+ variables_json: "{}".into(),+ identity: None,+ },+ -20,+ ),+ optimistic: PersistedOptimisticLayer {+ optimistic_data_json: "null".into(),+ normalized_updates: RecordUpdates::default(),+ },+ };+ let first = storage.enqueue_mutation(first_entry.clone()).await.unwrap();+ let second = storage+ .enqueue_mutation(second_entry.clone())+ .await+ .unwrap();+ assert!(first > 0 && second > first);+ storage.try_close().unwrap();++ let storage = database.open("scope-queue-reopen").unwrap();+ let loaded = storage.load_mutation_queue().await.unwrap();+ assert_eq!(+ loaded.iter().map(|entry| entry.id).collect::<Vec<_>>(),+ vec![first, second]+ );+ assert_eq!(loaded[0].mutation, first_entry.mutation);+ assert_eq!(loaded[0].optimistic, first_entry.optimistic);+ assert_eq!(loaded[1].mutation, second_entry.mutation);+ assert_eq!(loaded[1].optimistic, second_entry.optimistic);+ storage.try_close().unwrap();+ });+}++#[test]+fn strict_head_retries_leases_and_fences_conform() {+ block_on(async {+ let mut storage = TursoStorage::open_in_memory("scope-leases").unwrap();+ let mut first_entry = queued("First", 1);+ first_entry.mutation.attempt_count = 0;+ first_entry.mutation.lease_generation = 0;+ first_entry.mutation.last_error = None;+ first_entry.mutation.next_attempt_at_ms = Some(100);+ let mut second_entry = queued("Second", 2);+ second_entry.mutation.attempt_count = 0;+ second_entry.mutation.lease_generation = 0;+ second_entry.mutation.last_error = None;+ let first = storage.enqueue_mutation(first_entry).await.unwrap();+ let second = storage.enqueue_mutation(second_entry).await.unwrap();++ assert!(+ storage+ .claim_next_mutation(MutationClaimRequest {+ owner: "runner-a".into(),+ now_ms: 99,+ lease_expires_at_ms: 150,+ })+ .await+ .unwrap()+ .is_none()+ );+ let first_claim = storage+ .claim_next_mutation(MutationClaimRequest {+ owner: "runner-a".into(),+ now_ms: 100,+ lease_expires_at_ms: 150,+ })+ .await+ .unwrap()+ .unwrap();+ assert_eq!(first_claim.queued.id, first);+ assert_eq!(first_claim.queued.mutation.attempt_count, 1);+ assert_eq!(first_claim.lease_generation, 1);+ assert!(+ storage+ .claim_next_mutation(MutationClaimRequest {+ owner: "runner-b".into(),+ now_ms: 149,+ lease_expires_at_ms: 200,+ })+ .await+ .unwrap()+ .is_none()+ );++ let reclaimed = storage+ .claim_next_mutation(MutationClaimRequest {+ owner: "runner-b".into(),+ now_ms: 150,+ lease_expires_at_ms: 250,+ })+ .await+ .unwrap()+ .unwrap();+ assert_eq!(reclaimed.queued.id, first);+ assert_eq!(reclaimed.queued.mutation.attempt_count, 2);+ assert_eq!(reclaimed.lease_generation, 2);+ assert!(+ !storage+ .defer_mutation(first, claim("runner-a", 1), 300, "stale".into())+ .await+ .unwrap()+ );+ assert!(+ storage+ .defer_mutation(first, claim("runner-b", 2), 300, "offline".into())+ .await+ .unwrap()+ );+ let deferred = storage.load_mutation_queue().await.unwrap();+ assert_eq!(deferred[0].mutation.next_attempt_at_ms, Some(300));+ assert_eq!(deferred[0].mutation.lease_owner, None);+ assert_eq!(deferred[0].mutation.lease_expires_at_ms, None);+ assert_eq!(deferred[0].mutation.lease_generation, 2);+ assert_eq!(deferred[0].mutation.last_error.as_deref(), Some("offline"));+ assert!(+ storage+ .claim_next_mutation(MutationClaimRequest {+ owner: "runner-c".into(),+ now_ms: 299,+ lease_expires_at_ms: 400,+ })+ .await+ .unwrap()+ .is_none()+ );+ let third_claim = storage+ .claim_next_mutation(MutationClaimRequest {+ owner: "runner-c".into(),+ now_ms: 300,+ lease_expires_at_ms: 400,+ })+ .await+ .unwrap()+ .unwrap();+ assert_eq!(third_claim.lease_generation, 3);+ assert!(+ !storage+ .discard_mutation(first, claim("runner-b", 2))+ .await+ .unwrap()+ );+ assert!(+ storage+ .discard_mutation(first, claim("runner-c", 3))+ .await+ .unwrap()+ );+ let next = storage+ .claim_next_mutation(MutationClaimRequest {+ owner: "runner-d".into(),+ now_ms: 300,+ lease_expires_at_ms: 500,+ })+ .await+ .unwrap()+ .unwrap();+ assert_eq!(next.queued.id, second);+ storage.try_close().unwrap();+ });+}++#[test]+fn complete_discard_clear_and_non_reused_ids_are_atomic_semantics() {+ block_on(async {+ let mut storage = TursoStorage::open_in_memory("scope-settlement").unwrap();+ let first = storage+ .enqueue_mutation(queued("Complete", 1))+ .await+ .unwrap();+ let first_claim = storage+ .claim_next_mutation(MutationClaimRequest {+ owner: "runner".into(),+ now_ms: 1,+ lease_expires_at_ms: 100,+ })+ .await+ .unwrap()+ .unwrap();+ assert!(+ !storage+ .complete_mutation(+ first,+ claim("stale", first_claim.lease_generation),+ vec![(key("Result:stale"), record("must-not-write"))],+ )+ .await+ .unwrap()+ );+ assert_eq!(+ storage.get_batch(&[key("Result:stale")]).await.unwrap(),+ vec![None]+ );+ assert!(+ storage+ .complete_mutation(+ first,+ claim("runner", first_claim.lease_generation),+ vec![+ (key("Result:1"), record("first")),+ (key("Result:1"), record("last")),+ ],+ )+ .await+ .unwrap()+ );+ assert_eq!(+ storage.get_batch(&[key("Result:1")]).await.unwrap(),+ vec![Some(record("last"))]+ );+ assert!(storage.load_mutation_queue().await.unwrap().is_empty());++ let discarded = storage+ .enqueue_mutation(queued("Discard", 2))+ .await+ .unwrap();+ let discard_claim = storage+ .claim_next_mutation(MutationClaimRequest {+ owner: "discarder".into(),+ now_ms: 2,+ lease_expires_at_ms: 100,+ })+ .await+ .unwrap()+ .unwrap();+ assert!(+ storage+ .discard_mutation(+ discarded,+ claim("discarder", discard_claim.lease_generation),+ )+ .await+ .unwrap()+ );+ assert_eq!(+ storage.get_batch(&[key("Result:1")]).await.unwrap(),+ vec![Some(record("last"))]+ );++ let before_clear = storage+ .enqueue_mutation(queued("BeforeClear", 3))+ .await+ .unwrap();+ storage.clear().await.unwrap();+ assert!(storage.load_mutation_queue().await.unwrap().is_empty());+ assert_eq!(+ storage.get_batch(&[key("Result:1")]).await.unwrap(),+ vec![None]+ );+ let after_clear = storage+ .enqueue_mutation(queued("AfterClear", 4))+ .await+ .unwrap();+ assert!(after_clear > before_clear);+ storage.try_close().unwrap();+ });+}++#[test]+fn checked_rust_queue_values_are_rejected_before_transactions() {+ block_on(async {+ let mut storage = TursoStorage::open_in_memory("scope-numerics").unwrap();+ let mut oversized = queued("Oversized", 1);+ oversized.mutation.lease_generation = u64::MAX;+ assert!(+ !storage+ .enqueue_mutation(oversized)+ .await+ .unwrap_err()+ .requires_physical_reset()+ );+ assert!(+ !storage+ .discard_mutation(+ u64::MAX,+ MutationClaimToken {+ owner: "runner".into(),+ generation: 0,+ },+ )+ .await+ .unwrap_err()+ .requires_physical_reset()+ );+ storage.try_close().unwrap();+ });+}diff --git a/crates/client/cache-turso/tests/web.rs b/crates/client/cache-turso/tests/web.rsnew file mode 100644index 0000000000..fa825a500f--- /dev/null+++ b/crates/client/cache-turso/tests/web.rs@@ -0,0 +1,217 @@+#![cfg(target_arch = "wasm32")]++use cache_core::engine::{Engine, ReadResult};+use cache_core::normalize::RecordUpdates;+use cache_core::queue::{+ MutationRequest, NewQueuedMutation, PersistedOptimisticLayer, StoredMutation,+};+use cache_core::store::Storage;+use cache_core::value::{CacheValue, EntityKey, Record};+use cache_turso::{HealthyTursoStorageClosed, TursoStorage, TursoStorageCloseOutcome};+use turso_opfs::{OpenResult, OpfsOwner};+use wasm_bindgen_test::*;++wasm_bindgen_test_configure!(run_in_dedicated_worker);++fn key(value: &str) -> EntityKey<'static> {+ EntityKey(value.to_owned().into())+}++fn record(value: &str) -> Record {+ let mut record = Record::default();+ record+ .fields+ .insert("value".into(), CacheValue::String(value.into()));+ record+}++fn healthy_close(outcome: TursoStorageCloseOutcome) -> HealthyTursoStorageClosed {+ let TursoStorageCloseOutcome::Healthy(closed) = outcome else {+ panic!("healthy browser storage unexpectedly required reset")+ };+ closed+}++fn queued() -> NewQueuedMutation {+ NewQueuedMutation {+ mutation: StoredMutation::new(+ MutationRequest {+ query: "mutation Browser { update { id } }".into(),+ operation_name: Some("Browser".into()),+ variables_json: "{}".into(),+ identity: None,+ },+ 1,+ ),+ optimistic: PersistedOptimisticLayer {+ optimistic_data_json: "{}".into(),+ normalized_updates: RecordUpdates::default(),+ },+ }+}++const ENGINE_QUERY: &str = r#"+query BrowserEngine {+ user {+ id+ }+}+"#;++fn engine_data() -> serde_json::Value {+ serde_json::json!({"user": {"id": "browser-user"}})+}++#[wasm_bindgen_test(async)]+async fn real_engine_over_opfs_consumes_storage_for_preserve_and_reset() {+ let owner = OpfsOwner::acquire("cache-turso-wp06-engine.db")+ .await+ .unwrap()+ .recovery_wipe()+ .await+ .unwrap();+ let OpenResult::Ready(session) = owner.open().await.unwrap() else {+ panic!("recovery wipe must produce a complete fresh pair")+ };+ let storage =+ TursoStorage::from_opfs_session(session.connect().unwrap(), "engine-scope").unwrap();+ let mut engine = Engine::new(storage);+ engine+ .write_query(+ None,+ ENGINE_QUERY,+ Some("BrowserEngine"),+ &serde_json::Map::new(),+ &engine_data(),+ None,+ )+ .await+ .unwrap();+ let owner = healthy_close(engine.into_storage().try_close().unwrap())+ .preserve()+ .unwrap();++ let OpenResult::Ready(session) = owner.open().await.unwrap() else {+ panic!("preserved engine database must reopen")+ };+ let storage =+ TursoStorage::from_opfs_session(session.connect().unwrap(), "engine-scope").unwrap();+ let mut engine = Engine::new(storage);+ let ReadResult::Hit { data } = engine+ .read_query(+ None,+ ENGINE_QUERY,+ Some("BrowserEngine"),+ &serde_json::Map::new(),+ )+ .await+ .unwrap()+ else {+ panic!("reopened OPFS engine must read its durable record")+ };+ assert_eq!(data, engine_data());+ let owner = healthy_close(engine.into_storage().try_close().unwrap())+ .reset()+ .await+ .unwrap();++ let OpenResult::Ready(session) = owner.open().await.unwrap() else {+ panic!("reset engine database must reopen fresh")+ };+ let storage =+ TursoStorage::from_opfs_session(session.connect().unwrap(), "engine-scope").unwrap();+ let mut replacement = Engine::new(storage);+ assert!(matches!(+ replacement+ .read_query(+ None,+ ENGINE_QUERY,+ Some("BrowserEngine"),+ &serde_json::Map::new(),+ )+ .await+ .unwrap(),+ ReadResult::Miss+ ));+ healthy_close(replacement.into_storage().try_close().unwrap())+ .preserve()+ .unwrap()+ .release()+ .await+ .unwrap();+}++#[wasm_bindgen_test(async)]+async fn incompatible_opfs_initialization_exposes_reset_only_and_cannot_preserve() {+ let owner = OpfsOwner::acquire("cache-turso-wp06-browser.db")+ .await+ .unwrap()+ .recovery_wipe()+ .await+ .unwrap();+ let OpenResult::Ready(session) = owner.open().await.unwrap() else {+ panic!("recovery wipe must produce a complete fresh pair")+ };+ let mut storage =+ TursoStorage::from_opfs_session(session.connect().unwrap(), "browser-scope").unwrap();+ storage+ .put_batch(vec![+ (key("ROOT_QUERY"), record("root")),+ (key("Type0:1"), record("prefix")),+ (key("Type:9"), record("ordinary")),+ ])+ .await+ .unwrap();+ let mutation_id = storage.enqueue_mutation(queued()).await.unwrap();+ let owner = healthy_close(storage.try_close().unwrap())+ .preserve()+ .unwrap();++ let OpenResult::Ready(session) = owner.open().await.unwrap() else {+ panic!("preserved complete pair must reopen")+ };+ let storage =+ TursoStorage::from_opfs_session(session.connect().unwrap(), "browser-scope").unwrap();+ assert_eq!(+ storage+ .scan_records(&["Type".into(), "Type0".into()], None, 10)+ .await+ .unwrap()+ .into_iter()+ .map(|(key, _)| key.as_ref().to_owned())+ .collect::<Vec<_>>(),+ vec!["Type0:1", "Type:9"]+ );+ assert_eq!(+ storage.load_mutation_queue().await.unwrap()[0].id,+ mutation_id+ );++ let owner = healthy_close(storage.try_close().unwrap())+ .preserve()+ .unwrap();+ let OpenResult::Ready(session) = owner.open().await.unwrap() else {+ panic!("preserved complete pair must reopen for compatibility validation")+ };+ let failure =+ TursoStorage::from_opfs_session(session.connect().unwrap(), "wrong-browser-scope")+ .unwrap_err();+ assert!(failure.error().requires_physical_reset());+ let owner = failure.reset().await.unwrap();+ let OpenResult::Ready(session) = owner.open().await.unwrap() else {+ panic!("physical reset must recreate a complete fresh pair")+ };+ let storage =+ TursoStorage::from_opfs_session(session.connect().unwrap(), "browser-scope").unwrap();+ assert!(storage.load_mutation_queue().await.unwrap().is_empty());+ assert_eq!(+ storage.get_batch(&[key("Type:9")]).await.unwrap(),+ vec![None]+ );+ healthy_close(storage.try_close().unwrap())+ .preserve()+ .unwrap()+ .release()+ .await+ .unwrap();+}diff --git a/crates/client/cache-wasm/Cargo.toml b/crates/client/cache-wasm/Cargo.tomlindex 8405d0bb76..799c1722d9 100644--- a/crates/client/cache-wasm/Cargo.toml+++ b/crates/client/cache-wasm/Cargo.toml@@ -2,7 +2,11 @@edition = "2024"name = "cache-wasm"publish = false-version = "0.3.2"+version = "0.4.0"++[features]+default = []+browser-test-hooks = ["cache-turso/browser-test-hooks"][lib]crate-type = ["cdylib", "rlib"]@@ -17,22 +21,22 @@ wasm-opt = falsedemangle-name-section = truedwarf-debug-info = true-# Browser-only wasm-bindgen shell around the engine + IDB storage. Like-# cache-idb, it compiles to an empty shell off-wasm so workspace `cargo test`-# stays green.+# Browser-only wasm-bindgen shell around the engine + Turso OPFS storage. It+# compiles to an empty shell off-wasm so workspace `cargo test` stays green.[dependencies]cache-core = { path = "../cache-core" }[target.'cfg(target_arch = "wasm32")'.dependencies]async-lock = { workspace = true }-cache-idb = { path = "../cache-idb" }+cache-turso = { path = "../cache-turso" }js-sys = { workspace = true }serde = { workspace = true }serde-wasm-bindgen = { workspace = true }serde_json = { workspace = true }+turso-opfs = { path = "../turso-opfs" }wasm-bindgen = { workspace = true }wasm-bindgen-futures = { workspace = true }[target.'cfg(target_arch = "wasm32")'.dev-dependencies]-wasm-bindgen-test = "0.3"+wasm-bindgen-test = { workspace = true }diff --git a/crates/client/cache-wasm/src/lib.rs b/crates/client/cache-wasm/src/lib.rsindex db23b1f3d5..f753347600 100644--- a/crates/client/cache-wasm/src/lib.rs+++ b/crates/client/cache-wasm/src/lib.rs@@ -1,4 +1,4 @@-//! wasm-bindgen shell around the cache engine + IndexedDB storage.+//! wasm-bindgen shell around the cache engine + Turso OPFS storage.//!//! Exposes a `CacheEngine` class to the JS worker glue//! (`apps/web/src/lib/graphql-cache/`). All methods return Promises; thediff --git a/crates/client/cache-wasm/src/shell.rs b/crates/client/cache-wasm/src/shell.rsindex 01083e203b..eb7bcfc3b6 100644--- a/crates/client/cache-wasm/src/shell.rs+++ b/crates/client/cache-wasm/src/shell.rs@@ -1,20 +1,36 @@use async_lock::Mutex;+use cache_core::codec::cache_database_name;use cache_core::deps::OpId;-use cache_core::engine::{BeginOptimisticWrite, Engine, InitialClaimOutcome, ReadResult};+use cache_core::engine::{+ BeginOptimisticWrite, Engine, EngineError, InitialClaimOutcome, ReadResult,+};use cache_core::entity_resolver::EntityResolver;use cache_core::link_patch::{OptimisticLinkPatch, QueryRevalidation};use cache_core::query_inspection::QueryInspection;use cache_core::queue::{ClaimedMutation, MutationClaimRequest, MutationClaimToken};use cache_core::record_selection::{RecordCursor, RecordSelection};+use cache_core::store::QueueDiagnosticsAvailability;use cache_core::value::EntityKey;-use cache_idb::IdbStorage;+use cache_turso::{+ PhysicalResetReason, TursoStorage, TursoStorageCloseOutcome, TursoStorageError,+ TursoStorageOpenOutcome,+};use serde::{Deserialize, Serialize};use std::cell::RefCell;use std::collections::HashMap;use std::rc::Rc;+use turso_opfs::{OpenResult, OpfsOwner};use wasm_bindgen::prelude::*;use wasm_bindgen_futures::future_to_promise;+#[cfg(test)]+mod test;+#[cfg(test)]+mod test_storage;++#[cfg(test)]+use test_storage::{BrowserStorage, TestStorageFault};+/// Interns host-side string operation ids to engine `u64` ids.#[derive(Default)]struct OpInterner {@@ -55,6 +71,49 @@ enum JsReadResult {Miss,}+#[derive(Clone, Copy, Debug, PartialEq, Eq)]+enum CacheOpenOutcome {+ OpenedExisting,+ OpenedNew,+ ResetIncompatible,+ ResetCorrupt,+ ResetStorageUncertain,+}++impl CacheOpenOutcome {+ const fn as_str(self) -> &'static str {+ match self {+ Self::OpenedExisting => "opened-existing",+ Self::OpenedNew => "opened-new",+ Self::ResetIncompatible => "reset-incompatible",+ Self::ResetCorrupt => "reset-corrupt",+ Self::ResetStorageUncertain => "reset-storage-uncertain",+ }+ }+}++impl From<TursoStorageOpenOutcome> for CacheOpenOutcome {+ fn from(outcome: TursoStorageOpenOutcome) -> Self {+ match outcome {+ TursoStorageOpenOutcome::OpenedExisting => Self::OpenedExisting,+ TursoStorageOpenOutcome::OpenedNew => Self::OpenedNew,+ }+ }+}++fn recovery_outcome(reason: PhysicalResetReason) -> CacheOpenOutcome {+ match reason {+ PhysicalResetReason::Compatibility => CacheOpenOutcome::ResetIncompatible,+ PhysicalResetReason::Corruption+ | PhysicalResetReason::Codec+ | PhysicalResetReason::Invariant+ | PhysicalResetReason::Integrity => CacheOpenOutcome::ResetCorrupt,+ PhysicalResetReason::StorageFull+ | PhysicalResetReason::TransactionOutcomeUncertain+ | PhysicalResetReason::Io => CacheOpenOutcome::ResetStorageUncertain,+ }+}+#[derive(Serialize)]#[serde(rename_all = "camelCase")]struct JsWriteResult {@@ -140,36 +199,355 @@ fn parse_timestamp(value: f64, label: &str) -> Result<i64, JsValue> {Ok(value as i64)}+#[cfg(not(test))]+type BrowserStorage = TursoStorage;+type BrowserEngine = Engine<BrowserStorage>;++#[cfg(not(test))]+fn wrap_storage(storage: TursoStorage) -> BrowserStorage {+ storage+}++#[cfg(test)]+fn wrap_storage(storage: TursoStorage) -> BrowserStorage {+ BrowserStorage::new(storage)+}++#[cfg(not(test))]+fn unwrap_storage(storage: BrowserStorage) -> TursoStorage {+ storage+}++#[cfg(test)]+fn unwrap_storage(storage: BrowserStorage) -> TursoStorage {+ storage.into_inner()+}++struct CacheState {+ engine: Option<BrowserEngine>,+ scope: String,+ hot_capacity: Option<u32>,+ reset_required: bool,+}++impl CacheState {+ fn ensure_callable(&self) -> Result<(), JsValue> {+ if self.reset_required {+ Err(reset_required_js_error())+ } else if self.engine.is_none() {+ Err(closed_js_error())+ } else {+ Ok(())+ }+ }++ fn engine_mut(&mut self) -> Result<&mut BrowserEngine, JsValue> {+ self.ensure_callable()?;+ Ok(self+ .engine+ .as_mut()+ .expect("callable cache state contains an engine"))+ }++ fn engine_result<T>(+ &mut self,+ result: Result<T, EngineError<TursoStorageError>>,+ ) -> Result<T, JsValue> {+ result.map_err(|error| self.engine_error(error))+ }++ fn engine_error(&mut self, error: EngineError<TursoStorageError>) -> JsValue {+ if engine_error_requires_reset(&error) {+ self.reset_required = true;+ reset_required_js_error()+ } else {+ err_js(error)+ }+ }+}+#[wasm_bindgen]pub struct CacheEngine {- engine: Rc<Mutex<Engine<IdbStorage>>>,+ state: Rc<Mutex<CacheState>>,ops: Rc<RefCell<OpInterner>>,}-/// Opens (or creates) the cache for `scope`. The physical database is selected-/// by [`cache_core::codec::cache_database_name`] from `scope` alone; the schema-/// compatibility epoch and format version are record-compatibility inputs.-#[wasm_bindgen(js_name = openCache)]-pub async fn open_cache(scope: String, hot_capacity: Option<u32>) -> Result<CacheEngine, JsError> {- let storage = IdbStorage::open(&scope)- .await- .map_err(|e| JsError::new(&e.to_string()))?;- let engine = match hot_capacity {- Some(cap) => Engine::with_capacity(storage, cap as usize),+fn database_identity(scope: &str) -> String {+ cache_database_name(scope)+}++fn build_engine(storage: TursoStorage, hot_capacity: Option<u32>) -> BrowserEngine {+ let storage = wrap_storage(storage);+ match hot_capacity {+ Some(capacity) => Engine::with_capacity(storage, capacity as usize),None => Engine::new(storage),+ }+}++fn validate_hot_capacity(hot_capacity: Option<u32>) -> Result<(), JsValue> {+ if hot_capacity == Some(0) {+ Err(err_js("hot capacity must be greater than zero"))+ } else {+ Ok(())+ }+}++async fn open_owner(owner: OpfsOwner) -> Result<OpenResult, JsValue> {+ match owner.open().await {+ Ok(opened) => Ok(opened),+ Err(failure) => {+ let error = err_js(&failure);+ if let Some(owner) = failure.into_owner() {+ owner.release().await.map_err(err_js)?;+ }+ Err(error)+ }+ }+}++struct OpenedStorage {+ storage: TursoStorage,+ outcome: CacheOpenOutcome,+}++async fn open_storage(scope: &str, owner: OpfsOwner) -> Result<OpenedStorage, JsValue> {+ let (owner, reset_outcome) = match open_owner(owner).await? {+ OpenResult::Ready(session) => {+ let connected = session.connect().map_err(err_js)?;+ match TursoStorage::from_opfs_session_with_outcome(connected, scope) {+ Ok((storage, outcome)) => {+ return Ok(OpenedStorage {+ storage,+ outcome: outcome.into(),+ });+ }+ Err(failure) => {+ let error = failure.error();+ if !error.requires_physical_reset() {+ let owner = failure.preserve().map_err(err_js)?;+ owner.release().await.map_err(err_js)?;+ return Err(err_js(error));+ }+ let outcome = recovery_outcome(+ error+ .physical_reset_reason()+ .expect("reset-required error has a reset reason"),+ );+ (failure.reset().await.map_err(err_js)?, outcome)+ }+ }+ }+ OpenResult::ResetRequired(session) => (+ session.reset().await.map_err(err_js)?,+ CacheOpenOutcome::ResetStorageUncertain,+ ),};- Ok(CacheEngine {- engine: Rc::new(Mutex::new(engine)),- ops: Rc::new(RefCell::new(OpInterner::default())),- })++ match open_owner(owner).await? {+ OpenResult::Ready(session) => {+ let connected = session.connect().map_err(err_js)?;+ match TursoStorage::from_opfs_session(connected, scope) {+ Ok(storage) => Ok(OpenedStorage {+ storage,+ outcome: reset_outcome,+ }),+ Err(failure) => {+ let reset_required = failure.error().requires_physical_reset();+ let owner = failure.reset().await.map_err(err_js)?;+ owner.release().await.map_err(err_js)?;+ Err(if reset_required {+ reset_required_js_error()+ } else {+ err_js("cache storage initialization failed")+ })+ }+ }+ }+ OpenResult::ResetRequired(session) => {+ let owner = session.reset().await.map_err(err_js)?;+ owner.release().await.map_err(err_js)?;+ Err(reset_required_js_error())+ }+ }+}++async fn acquire_storage(scope: &str, recovery_wipe: bool) -> Result<OpenedStorage, JsValue> {+ let owner = OpfsOwner::acquire(&database_identity(scope))+ .await+ .map_err(err_js)?;+ let owner = if recovery_wipe {+ owner.recovery_wipe().await.map_err(err_js)?+ } else {+ owner+ };+ let mut opened = open_storage(scope, owner).await?;+ if recovery_wipe {+ opened.outcome = CacheOpenOutcome::ResetStorageUncertain;+ }+ Ok(opened)+}++async fn open_cache_inner(+ scope: String,+ hot_capacity: Option<u32>,+ recovery_wipe: bool,+) -> Result<(CacheEngine, CacheOpenOutcome), JsValue> {+ validate_hot_capacity(hot_capacity)?;+ let OpenedStorage { storage, outcome } = acquire_storage(&scope, recovery_wipe).await?;+ Ok((+ CacheEngine {+ state: Rc::new(Mutex::new(CacheState {+ engine: Some(build_engine(storage, hot_capacity)),+ scope,+ hot_capacity,+ reset_required: false,+ })),+ ops: Rc::new(RefCell::new(OpInterner::default())),+ },+ outcome,+ ))+}++fn cache_open_result(engine: CacheEngine, outcome: CacheOpenOutcome) -> Result<JsValue, JsValue> {+ let result = js_sys::Object::new();+ js_sys::Reflect::set(+ &result,+ &JsValue::from_str("engine"),+ &JsValue::from(engine),+ )?;+ js_sys::Reflect::set(+ &result,+ &JsValue::from_str("outcome"),+ &JsValue::from_str(outcome.as_str()),+ )?;+ Ok(result.into())+}++/// Opens (or creates) the cache for `scope` after acquiring its exclusive OPFS+/// owner lock. The physical identity is derived from `scope` alone; disposable+/// incomplete or incompatible files are reset and reopened before returning.+#[wasm_bindgen(js_name = openCache)]+pub async fn open_cache(scope: String, hot_capacity: Option<u32>) -> Result<CacheEngine, JsValue> {+ open_cache_inner(scope, hot_capacity, false)+ .await+ .map(|(engine, _)| engine)}-/// Deletes the cache database for `scope` (logout).+/// Additive open API returning the engine and payload-free recovery outcome.+#[wasm_bindgen(js_name = openCacheWithOutcome)]+pub async fn open_cache_with_outcome(+ scope: String,+ hot_capacity: Option<u32>,+) -> Result<JsValue, JsValue> {+ let (engine, outcome) = open_cache_inner(scope, hot_capacity, false).await?;+ cache_open_result(engine, outcome)+}++/// Acquires the canonical owner once, recovery-wipes before any Turso open,+/// then opens a fresh cache while continuously retaining that same owner lock.+#[wasm_bindgen(js_name = openCacheForRecovery)]+pub async fn open_cache_for_recovery(+ scope: String,+ hot_capacity: Option<u32>,+) -> Result<CacheEngine, JsValue> {+ open_cache_inner(scope, hot_capacity, true)+ .await+ .map(|(engine, _)| engine)+}++/// Additive recovery-open API returning the engine and coarse wipe outcome.+#[wasm_bindgen(js_name = openCacheForRecoveryWithOutcome)]+pub async fn open_cache_for_recovery_with_outcome(+ scope: String,+ hot_capacity: Option<u32>,+) -> Result<JsValue, JsValue> {+ let (engine, outcome) = open_cache_inner(scope, hot_capacity, true).await?;+ cache_open_result(engine, outcome)+}++/// Recovery-wipes and recreates the cache database for `scope` while holding+/// the same exclusive OPFS owner lock used by [`openCache`](open_cache).#[wasm_bindgen(js_name = destroyCache)]-pub async fn destroy_cache(scope: String) -> Result<(), JsError> {- IdbStorage::destroy(&scope)+pub async fn destroy_cache(scope: String) -> Result<(), JsValue> {+ OpfsOwner::acquire(&database_identity(&scope))+ .await+ .map_err(err_js)?+ .recovery_wipe()+ .await+ .map_err(err_js)?+ .release().await- .map_err(|e| JsError::new(&e.to_string()))+ .map_err(err_js)+}++#[cfg(feature = "browser-test-hooks")]+enum BrowserTestStorageMutation {+ IncompatibleNamespace,+ CorruptQueuePayload,+}++#[cfg(feature = "browser-test-hooks")]+async fn browser_test_mutate_closed_storage(+ scope: String,+ mutation: BrowserTestStorageMutation,+) -> Result<(), JsValue> {+ let owner = OpfsOwner::acquire(&database_identity(&scope))+ .await+ .map_err(err_js)?;+ let session = match open_owner(owner).await? {+ OpenResult::Ready(session) => session,+ OpenResult::ResetRequired(session) => {+ let owner = session.reset().await.map_err(err_js)?;+ owner.release().await.map_err(err_js)?;+ return Err(err_js("browser-test storage was already reset-required"));+ }+ };+ let connected = session.connect().map_err(err_js)?;+ let mut storage = match TursoStorage::from_opfs_session(connected, &scope) {+ Ok(storage) => storage,+ Err(failure) => {+ let owner = failure.reset().await.map_err(err_js)?;+ owner.release().await.map_err(err_js)?;+ return Err(err_js("browser-test storage validation failed"));+ }+ };+ match mutation {+ BrowserTestStorageMutation::IncompatibleNamespace => {+ storage.browser_test_make_namespace_incompatible()+ }+ BrowserTestStorageMutation::CorruptQueuePayload => {+ storage.browser_test_corrupt_queue_payload()+ }+ }+ .map_err(err_js)?;+ match storage.try_close().map_err(err_js)? {+ TursoStorageCloseOutcome::Healthy(closed) => closed+ .preserve()+ .map_err(err_js)?+ .release()+ .await+ .map_err(err_js),+ TursoStorageCloseOutcome::ResetRequired(closed) => {+ let owner = closed.reset().await.map_err(err_js)?;+ owner.release().await.map_err(err_js)?;+ Err(err_js("browser-test mutation unexpectedly required reset"))+ }+ }+}++/// Test-artifact-only incompatible-namespace hook.+#[cfg(feature = "browser-test-hooks")]+#[wasm_bindgen(js_name = browserTestMakeNamespaceIncompatible)]+pub async fn browser_test_make_namespace_incompatible(scope: String) -> Result<(), JsValue> {+ browser_test_mutate_closed_storage(scope, BrowserTestStorageMutation::IncompatibleNamespace)+ .await+}++/// Test-artifact-only corrupt-queue hook.+#[cfg(feature = "browser-test-hooks")]+#[wasm_bindgen(js_name = browserTestCorruptQueuePayload)]+pub async fn browser_test_corrupt_queue_payload(scope: String) -> Result<(), JsValue> {+ browser_test_mutate_closed_storage(scope, BrowserTestStorageMutation::CorruptQueuePayload).await}/// Schema hash baked into this build (build diagnostics).@@ -184,11 +562,35 @@ fn to_js<T: Serialize>(value: &T) -> Result<JsValue, JsValue> {.map_err(|e| JsValue::from_str(&e.to_string()))}-/// All rejections surface as real `Error` objects (consistent-/// `instanceof Error` / `.message` behavior with the `JsError`-returning-/// functions like `openCache`).-fn err_js(e: impl std::fmt::Display) -> JsValue {- js_sys::Error::new(&e.to_string()).into()+const RESET_REQUIRED_MARKER: &str = "cacheStorageResetRequired";+const RESET_REQUIRED_MESSAGE: &str = "cache storage reset required";++/// All rejections surface as real `Error` objects with consistent+/// `instanceof Error` and `.message` behavior.+fn err_js(error: impl std::fmt::Display) -> JsValue {+ js_sys::Error::new(&error.to_string()).into()+}++fn closed_js_error() -> JsValue {+ err_js("cache engine is closed")+}++fn reset_required_js_error() -> JsValue {+ let error = js_sys::Error::new(RESET_REQUIRED_MESSAGE);+ js_sys::Reflect::set(+ error.as_ref(),+ &JsValue::from_str(RESET_REQUIRED_MARKER),+ &JsValue::TRUE,+ )+ .expect("new JavaScript Error accepts the reset marker");+ error.into()+}++fn engine_error_requires_reset(error: &EngineError<TursoStorageError>) -> bool {+ matches!(+ error,+ EngineError::Storage(storage_error) if storage_error.requires_physical_reset()+ )}fn parse_variables(@@ -233,20 +635,77 @@ fn parse_query_inspection(})}+async fn close_storage(storage: BrowserStorage, force_reset: bool) -> Result<OpfsOwner, JsValue> {+ match unwrap_storage(storage).try_close().map_err(err_js)? {+ TursoStorageCloseOutcome::Healthy(closed) if force_reset => {+ closed.reset().await.map_err(err_js)+ }+ TursoStorageCloseOutcome::Healthy(closed) => closed.preserve().map_err(err_js),+ TursoStorageCloseOutcome::ResetRequired(closed) => closed.reset().await.map_err(err_js),+ }+}+#[wasm_bindgen]impl CacheEngine {+ /// Returns payload-free durable mutation queue diagnostics.+ #[wasm_bindgen(js_name = queueDiagnostics)]+ pub fn queue_diagnostics(&self) -> js_sys::Promise {+ let state = self.state.clone();+ future_to_promise(async move {+ let mut state = state.lock().await;+ // Observation failures bypass `engine_result`: diagnostics never+ // latch reset-required state or alter the engine lifecycle.+ let diagnostics = state+ .engine_mut()?+ .queue_diagnostics()+ .await+ .map_err(err_js)?;+ let value = js_sys::Object::new();+ let available = diagnostics.availability == QueueDiagnosticsAvailability::Available;+ js_sys::Reflect::set(+ &value,+ &JsValue::from_str("availability"),+ &JsValue::from_str(if available {+ "available"+ } else {+ "unavailable"+ }),+ )?;+ js_sys::Reflect::set(+ &value,+ &JsValue::from_str("depth"),+ &if available {+ JsValue::from_str(&diagnostics.depth.to_string())+ } else {+ JsValue::NULL+ },+ )?;+ js_sys::Reflect::set(+ &value,+ &JsValue::from_str("oldestCreatedAtMs"),+ &if available {+ diagnostics+ .oldest_created_at_ms+ .map_or(JsValue::NULL, |timestamp| {+ JsValue::from_str(×tamp.to_string())+ })+ } else {+ JsValue::NULL+ },+ )?;+ Ok(value.into())+ })+ }+/// Returns the opaque identity bound to this cache, or `null` when no/// identity-bearing response has been stored yet.#[wasm_bindgen(js_name = boundIdentity)]pub fn bound_identity(&self) -> js_sys::Promise {- let engine = self.engine.clone();+ let state = self.state.clone();future_to_promise(async move {- let identity = engine- .lock()- .await- .current_identity()- .await- .map_err(err_js)?;+ let mut state = state.lock().await;+ let result = state.engine_mut()?.current_identity().await;+ let identity = state.engine_result(result)?;to_js(&identity)})}@@ -263,14 +722,16 @@ impl CacheEngine {variables: JsValue,entity_resolvers: JsValue,) -> js_sys::Promise {- let engine = self.engine.clone();+ let state = self.state.clone();let ops = self.ops.clone();future_to_promise(async move {+ let mut state = state.lock().await;+ state.ensure_callable()?;let vars = parse_variables(variables)?;let entity_resolvers: Vec<EntityResolver> = parse_vec(entity_resolvers)?;let op = op_id.map(|name| ops.borrow_mut().intern(&name));- let mut engine = engine.lock().await;- let result = engine+ let result = state+ .engine_mut()?.read_query_with_entity_resolvers(op,&query,@@ -278,8 +739,8 @@ impl CacheEngine {&vars,&entity_resolvers,)- .await- .map_err(err_js)?;+ .await;+ let result = state.engine_result(result)?;to_js(&match result {ReadResult::Hit { data } => JsReadResult::Hit { data },ReadResult::Miss => JsReadResult::Miss,@@ -296,16 +757,17 @@ impl CacheEngine {cursor: JsValue,limit: u32,) -> js_sys::Promise {- let engine = self.engine.clone();+ let state = self.state.clone();future_to_promise(async move {+ let mut state = state.lock().await;+ state.ensure_callable()?;let selection = RecordSelection::parse(&document, &fragment_name).map_err(err_js)?;let cursor = parse_record_cursor(cursor)?;- let page = engine- .lock()- .await+ let result = state+ .engine_mut()?.read_records(&selection, cursor.as_ref(), limit as usize)- .await- .map_err(err_js)?;+ .await;+ let page = state.engine_result(result)?;to_js(&page)})}@@ -326,14 +788,16 @@ impl CacheEngine {data: JsValue,identity: Option<String>,) -> js_sys::Promise {- let engine = self.engine.clone();+ let state = self.state.clone();let ops = self.ops.clone();future_to_promise(async move {+ let mut state = state.lock().await;+ state.ensure_callable()?;let vars = parse_variables(variables)?;let data: serde_json::Value = serde_wasm_bindgen::from_value(data).map_err(err_js)?;let origin = origin_op_id.map(|name| ops.borrow_mut().intern(&name));- let mut engine = engine.lock().await;- let result = engine+ let result = state+ .engine_mut()?.write_query(origin,&query,@@ -342,8 +806,8 @@ impl CacheEngine {&data,identity.as_deref(),)- .await- .map_err(err_js)?;+ .await;+ let result = state.engine_result(result)?;to_js(&JsWriteResult {changed: result.changed@@ -376,9 +840,11 @@ impl CacheEngine {now_ms: f64,lease_expires_at_ms: f64,) -> js_sys::Promise {- let engine = self.engine.clone();+ let state = self.state.clone();let ops = self.ops.clone();future_to_promise(async move {+ let mut state = state.lock().await;+ state.ensure_callable()?;let vars = parse_variables(variables)?;let data: serde_json::Value = serde_wasm_bindgen::from_value(data).map_err(err_js)?;let link_patches: Vec<OptimisticLinkPatch> = parse_vec(link_patches)?;@@ -393,8 +859,8 @@ impl CacheEngine {)?,};let origin = origin_op_id.map(|name| ops.borrow_mut().intern(&name));- let mut engine = engine.lock().await;- let result = engine+ let result = state+ .engine_mut()?.enqueue_optimistic_mutation(origin,BeginOptimisticWrite {@@ -408,13 +874,16 @@ impl CacheEngine {},claim,)- .await- .map_err(err_js)?;+ .await;+ let result = state.engine_result(result)?;let initial_claim = match result.initial_claim {InitialClaimOutcome::Claimed(claimed) => JsInitialMutationClaim::Claimed {mutation: JsClaimedMutation::try_from(*claimed)?,},InitialClaimOutcome::NotRunnable => JsInitialMutationClaim::NotRunnable,+ InitialClaimOutcome::Failed(error) if engine_error_requires_reset(&error) => {+ return Err(state.engine_error(error));+ }InitialClaimOutcome::Failed(error) => JsInitialMutationClaim::Failed {error: error.to_string(),},@@ -443,15 +912,16 @@ impl CacheEngine {operation_name: Option<String>,path: JsValue,) -> js_sys::Promise {- let engine = self.engine.clone();+ let state = self.state.clone();future_to_promise(async move {+ let mut state = state.lock().await;+ state.ensure_callable()?;let inspection = parse_query_inspection(query, operation_name, path, Vec::new())?;- let variants = engine- .lock()- .await+ let result = state+ .engine_mut()?.inspect_query_variants(&inspection)- .await- .map_err(err_js)?;+ .await;+ let variants = state.engine_result(result)?;to_js(&variants)})}@@ -465,16 +935,14 @@ impl CacheEngine {path: JsValue,variable_filters: JsValue,) -> js_sys::Promise {- let engine = self.engine.clone();+ let state = self.state.clone();future_to_promise(async move {+ let mut state = state.lock().await;+ state.ensure_callable()?;let variable_filters = parse_vec(variable_filters)?;let inspection = parse_query_inspection(query, operation_name, path, variable_filters)?;- let instances = engine- .lock()- .await- .inspect_query(&inspection)- .await- .map_err(err_js)?;+ let result = state.engine_mut()?.inspect_query(&inspection).await;+ let instances = state.engine_result(result)?;to_js(&instances)})}@@ -487,8 +955,10 @@ impl CacheEngine {now_ms: f64,lease_expires_at_ms: f64,) -> js_sys::Promise {- let engine = self.engine.clone();+ let state = self.state.clone();future_to_promise(async move {+ let mut state = state.lock().await;+ state.ensure_callable()?;let request = MutationClaimRequest {owner,now_ms: parse_timestamp(now_ms, "claim timestamp")?,@@ -497,12 +967,8 @@ impl CacheEngine {"lease expiration timestamp",)?,};- let claimed = engine- .lock()- .await- .claim_next_mutation(request)- .await- .map_err(err_js)?;+ let result = state.engine_mut()?.claim_next_mutation(request).await;+ let claimed = state.engine_result(result)?;to_js(&claimed.map(JsClaimedMutation::try_from).transpose()?)})}@@ -517,24 +983,21 @@ impl CacheEngine {next_attempt_at_ms: f64,error: String,) -> js_sys::Promise {- let engine = self.engine.clone();+ let state = self.state.clone();future_to_promise(async move {+ let mut state = state.lock().await;+ state.ensure_callable()?;let transaction = parse_transaction_id(&transaction_id)?;let claim = MutationClaimToken {owner: lease_owner,generation: parse_u64(&lease_generation, "lease generation")?,};- engine- .lock()- .await- .defer_optimistic_write(- transaction,- claim,- parse_timestamp(next_attempt_at_ms, "next attempt timestamp")?,- error,- )- .await- .map_err(err_js)?;+ let next_attempt_at_ms = parse_timestamp(next_attempt_at_ms, "next attempt timestamp")?;+ let result = state+ .engine_mut()?+ .defer_optimistic_write(transaction, claim, next_attempt_at_ms, error)+ .await;+ state.engine_result(result)?;Ok(JsValue::UNDEFINED)})}@@ -542,6 +1005,7 @@ impl CacheEngine {/// Atomically replaces a claimed optimistic layer with the real network/// response and removes it from the durable queue.#[wasm_bindgen(js_name = commitOptimisticWrite)]+ #[allow(clippy::too_many_arguments)]pub fn commit_optimistic_write(&self,transaction_id: String,@@ -552,9 +1016,11 @@ impl CacheEngine {variables: JsValue,data: JsValue,) -> js_sys::Promise {- let engine = self.engine.clone();+ let state = self.state.clone();let ops = self.ops.clone();future_to_promise(async move {+ let mut state = state.lock().await;+ state.ensure_callable()?;let transaction = parse_transaction_id(&transaction_id)?;let claim = MutationClaimToken {owner: lease_owner,@@ -562,8 +1028,8 @@ impl CacheEngine {};let vars = parse_variables(variables)?;let data: serde_json::Value = serde_wasm_bindgen::from_value(data).map_err(err_js)?;- let mut engine = engine.lock().await;- let result = engine+ let result = state+ .engine_mut()?.commit_optimistic_write(transaction,claim,@@ -572,8 +1038,8 @@ impl CacheEngine {&vars,&data,)- .await- .map_err(err_js)?;+ .await;+ let result = state.engine_result(result)?;to_js(&JsWriteResult {changed: result.changed@@ -596,19 +1062,21 @@ impl CacheEngine {lease_owner: String,lease_generation: String,) -> js_sys::Promise {- let engine = self.engine.clone();+ let state = self.state.clone();let ops = self.ops.clone();future_to_promise(async move {+ let mut state = state.lock().await;+ state.ensure_callable()?;let transaction = parse_transaction_id(&transaction_id)?;let claim = MutationClaimToken {owner: lease_owner,generation: parse_u64(&lease_generation, "lease generation")?,};- let mut engine = engine.lock().await;- let result = engine+ let result = state+ .engine_mut()?.rollback_optimistic_write(transaction, claim)- .await- .map_err(err_js)?;+ .await;+ let result = state.engine_result(result)?;to_js(&JsWriteResult {changed: result.changed@@ -627,32 +1095,31 @@ impl CacheEngine {/// operation ids.#[wasm_bindgen(js_name = invalidateKeys)]pub fn invalidate_keys(&self, keys: Vec<String>) -> js_sys::Promise {- let engine = self.engine.clone();+ let state = self.state.clone();let ops = self.ops.clone();future_to_promise(async move {+ let mut state = state.lock().await;+ state.ensure_callable()?;let keys: Vec<EntityKey<'static>> =keys.into_iter().map(|key| EntityKey(key.into())).collect();- let mut engine = engine.lock().await;- let affected = engine.invalidate_keys(keys.iter());+ let affected = state.engine_mut()?.invalidate_keys(keys.iter());to_js(&ops.borrow().names(affected))})}- /// Deletes stale records from memory and IndexedDB after a server-side+ /// Deletes stale records from memory and Turso after a server-side/// mutation and resolves to affected local operation ids.#[wasm_bindgen(js_name = deleteKeys)]pub fn delete_keys(&self, keys: Vec<String>) -> js_sys::Promise {- let engine = self.engine.clone();+ let state = self.state.clone();let ops = self.ops.clone();future_to_promise(async move {+ let mut state = state.lock().await;+ state.ensure_callable()?;let keys: Vec<EntityKey<'static>> =keys.into_iter().map(|key| EntityKey(key.into())).collect();- let affected = engine- .lock()- .await- .delete_keys(&keys)- .await- .map_err(err_js)?;+ let result = state.engine_mut()?.delete_keys(&keys).await;+ let affected = state.engine_result(result)?;to_js(&ops.borrow().names(affected))})}@@ -661,15 +1128,12 @@ impl CacheEngine {/// queue and returns locally affected operations.#[wasm_bindgen(js_name = refreshOptimisticQueue)]pub fn refresh_optimistic_queue(&self) -> js_sys::Promise {- let engine = self.engine.clone();+ let state = self.state.clone();let ops = self.ops.clone();future_to_promise(async move {- let result = engine- .lock()- .await- .refresh_optimistic_queue()- .await- .map_err(err_js)?;+ let mut state = state.lock().await;+ let result = state.engine_mut()?.refresh_optimistic_queue().await;+ let result = state.engine_result(result)?;to_js(&JsWriteResult {changed: result.changed@@ -688,10 +1152,11 @@ impl CacheEngine {/// and resolves to every local operation id (all must re-execute).#[wasm_bindgen(js_name = externalReset)]pub fn external_reset(&self) -> js_sys::Promise {- let engine = self.engine.clone();+ let state = self.state.clone();let ops = self.ops.clone();future_to_promise(async move {- let affected = engine.lock().await.external_reset();+ let mut state = state.lock().await;+ let affected = state.engine_mut()?.external_reset();to_js(&ops.borrow().names(affected))})}@@ -699,34 +1164,106 @@ impl CacheEngine {/// Unregisters an operation (urql teardown).#[wasm_bindgen(js_name = teardownOperation)]pub fn teardown_operation(&self, op_id: String) -> js_sys::Promise {- let engine = self.engine.clone();+ let state = self.state.clone();let ops = self.ops.clone();future_to_promise(async move {- let removed = ops.borrow_mut().remove(&op_id);- if let Some(id) = removed {- engine.lock().await.teardown_operation(id);+ let mut state = state.lock().await;+ let engine = state.engine_mut()?;+ if let Some(id) = ops.borrow_mut().remove(&op_id) {+ engine.teardown_operation(id);}Ok(JsValue::UNDEFINED)})}- /// Drops all cached state (logout, corruption rebuild).+ /// Drops all cached state, including the durable mutation queue.pub fn clear(&self) -> js_sys::Promise {- let engine = self.engine.clone();+ let state = self.state.clone();future_to_promise(async move {- engine.lock().await.clear().await.map_err(err_js)?;+ let mut state = state.lock().await;+ let result = state.engine_mut()?.clear().await;+ state.engine_result(result)?;Ok(JsValue::UNDEFINED)})}- /// Closes the underlying IndexedDB connection. Call before- /// [`destroyCache`](destroy_cache) — database deletion blocks while- /// connections are open. The engine is unusable afterwards.+ /// Physically resets and recreates this instance's OPFS database while+ /// retaining the exclusive owner lock. The instance remains usable after+ /// the fresh engine has been installed.+ #[wasm_bindgen(js_name = physicalReset)]+ pub fn physical_reset(&self) -> js_sys::Promise {+ let state = self.state.clone();+ future_to_promise(async move {+ let mut state = state.lock().await;+ let engine = state.engine.take().ok_or_else(|| {+ if state.reset_required {+ err_js("cache engine requires worker replacement")+ } else {+ closed_js_error()+ }+ })?;+ let scope = state.scope.clone();+ let hot_capacity = state.hot_capacity;+ let owner = match close_storage(engine.into_storage(), true).await {+ Ok(owner) => owner,+ Err(error) => {+ state.reset_required = true;+ return Err(error);+ }+ };+ let storage = match open_storage(&scope, owner).await {+ Ok(opened) => opened.storage,+ Err(error) => {+ state.reset_required = true;+ return Err(error);+ }+ };+ state.engine = Some(build_engine(storage, hot_capacity));+ state.reset_required = false;+ Ok(JsValue::UNDEFINED)+ })+ }++ /// Consumes the engine, closes Turso and all OPFS handles, then preserves a+ /// healthy database or resets a latched-unhealthy database before releasing+ /// the exclusive owner lock. Every later instance method rejects.pub fn close(&self) -> js_sys::Promise {- let engine = self.engine.clone();+ let state = self.state.clone();future_to_promise(async move {- engine.lock().await.storage().close();+ let mut state = state.lock().await;+ let engine = state.engine.take().ok_or_else(|| {+ if state.reset_required {+ err_js("cache engine requires worker replacement")+ } else {+ closed_js_error()+ }+ })?;+ let owner = match close_storage(engine.into_storage(), state.reset_required).await {+ Ok(owner) => owner,+ Err(error) => {+ state.reset_required = true;+ return Err(error);+ }+ };+ if let Err(error) = owner.release().await {+ state.reset_required = true;+ return Err(err_js(error));+ }+ state.reset_required = false;Ok(JsValue::UNDEFINED)})}}++#[cfg(test)]+impl CacheEngine {+ async fn arm_storage_fault(&self, fault: TestStorageFault) {+ let state = self.state.lock().await;+ state+ .engine+ .as_ref()+ .expect("test cache contains an engine")+ .storage()+ .arm(fault);+ }+}diff --git a/crates/client/cache-wasm/src/shell/test.rs b/crates/client/cache-wasm/src/shell/test.rsnew file mode 100644index 0000000000..c190b0c1ac--- /dev/null+++ b/crates/client/cache-wasm/src/shell/test.rs@@ -0,0 +1,1014 @@+use super::*;+use serde::de::DeserializeOwned;+use wasm_bindgen_futures::JsFuture;+use wasm_bindgen_test::*;++wasm_bindgen_test_configure!(run_in_dedicated_worker);++const QUERY: &str = r#"query Soup($input: SoupInput!) {+ user {+ id+ soup(input: $input) {+ nextCursor+ items {+ __typename+ id+ }+ }+ }+}"#;++const PROPERTY_QUERY: &str = r#"query Soup($input: SoupInput!) {+ user { id soup(input: $input) { nextCursor items {+ __typename+ id+ ... on GraphqlSoupDocument { properties { id displayName } }+ } } }+}"#;++const PROPERTY_MUTATION: &str = r#"mutation SetEntityProperty($input: SetEntityPropertyInput!) {+ setEntityProperty(input: $input) { id displayName }+}"#;++const RECORD_FRAGMENT: &str = r#"fragment CachedDocument on GraphqlSoupDocument {+ id+}"#;++fn js(json: serde_json::Value) -> JsValue {+ use serde::Serialize;+ json.serialize(&serde_wasm_bindgen::Serializer::json_compatible())+ .expect("serialize test value")+}++fn from_js<T: DeserializeOwned>(value: JsValue) -> T {+ serde_wasm_bindgen::from_value(value).expect("deserialize wasm result")+}++async fn resolved(promise: js_sys::Promise) -> JsValue {+ JsFuture::from(promise).await.expect("promise resolves")+}++async fn assert_closed(promise: js_sys::Promise) {+ let error = JsFuture::from(promise)+ .await+ .expect_err("closed method rejects");+ let message = js_sys::Reflect::get(&error, &JsValue::from_str("message"))+ .expect("Error.message")+ .as_string()+ .expect("message is a string");+ assert_eq!(message, "cache engine is closed");+}++async fn assert_reset_required(promise: js_sys::Promise) {+ let error = JsFuture::from(promise)+ .await+ .expect_err("reset-required method rejects");+ assert!(error.is_instance_of::<js_sys::Error>());+ assert_eq!(+ js_sys::Reflect::get(&error, &JsValue::from_str(RESET_REQUIRED_MARKER))+ .expect("reset marker")+ .as_bool(),+ Some(true)+ );+ let message = js_sys::Reflect::get(&error, &JsValue::from_str("message"))+ .expect("Error.message")+ .as_string()+ .expect("message is a string");+ assert_eq!(message, RESET_REQUIRED_MESSAGE);+}++fn variables() -> serde_json::Value {+ serde_json::json!({"input": {"limit": 1}})+}++fn soup_data(document_id: &str) -> serde_json::Value {+ serde_json::json!({+ "user": {+ "id": "user-1",+ "soup": {+ "nextCursor": null,+ "items": [{+ "__typename": "GraphqlSoupDocument",+ "id": document_id+ }]+ }+ }+ })+}++fn property_base() -> serde_json::Value {+ property_data("Status")+}++fn property_data(display_name: &str) -> serde_json::Value {+ serde_json::json!({+ "user": { "id": "user-1", "soup": { "nextCursor": null, "items": [{+ "__typename": "GraphqlSoupDocument",+ "id": "doc-1",+ "properties": [{ "id": "prop-1", "displayName": display_name }]+ }] } }+ })+}++fn mutation_variables() -> serde_json::Value {+ serde_json::json!({"input": {+ "entityType": "DOCUMENT",+ "entityId": "doc-1",+ "propertyDefinitionId": "def-1",+ "value": { "string": "x" }+ }})+}++async fn fresh_engine(scope: &str) -> CacheEngine {+ destroy_cache(scope.into())+ .await+ .expect("wipe test database");+ open_cache(scope.into(), None).await.expect("open cache")+}++async fn close_and_destroy(engine: &CacheEngine, scope: &str) {+ resolved(engine.close()).await;+ destroy_cache(scope.into()).await.expect("destroy cache");+}++#[wasm_bindgen_test(async)]+async fn operations_preserve_js_boundary_interner_and_ordering() {+ const SCOPE: &str = "cache-wasm-wp07-operations";+ let engine = fresh_engine(SCOPE).await;+ let vars = variables();++ for operation in ["tab:z", "tab:a"] {+ let read: serde_json::Value = from_js(+ resolved(engine.read_query(+ Some(operation.into()),+ QUERY.into(),+ Some("Soup".into()),+ js(vars.clone()),+ JsValue::UNDEFINED,+ ))+ .await,+ );+ assert_eq!(read["kind"], "miss");+ }++ let write: serde_json::Value = from_js(+ resolved(engine.write_query(+ Some("tab:writer".into()),+ QUERY.into(),+ Some("Soup".into()),+ js(vars.clone()),+ js(soup_data("doc-1")),+ Some("user-1".into()),+ ))+ .await,+ );+ assert_eq!(write["affectedOps"], serde_json::json!(["tab:z", "tab:a"]));+ assert_eq!(write["reset"], false);++ let identity: Option<String> = from_js(resolved(engine.bound_identity()).await);+ assert_eq!(identity.as_deref(), Some("user-1"));++ let variants: serde_json::Value = from_js(+ resolved(engine.inspect_query_variants(+ QUERY.into(),+ Some("Soup".into()),+ js(serde_json::json!([{"field": "user"}, {"field": "soup"}])),+ ))+ .await,+ );+ assert_eq!(variants[0]["variables"], vars);+ assert!(variants[0].get("value").is_none());++ let inspected: serde_json::Value = from_js(+ resolved(engine.inspect_query(+ QUERY.into(),+ Some("Soup".into()),+ js(serde_json::json!([{"field": "user"}, {"field": "soup"}])),+ js(serde_json::json!([])),+ ))+ .await,+ );+ assert_eq!(inspected[0]["variables"], vars);+ assert_eq!(inspected[0]["value"], soup_data("doc-1")["user"]["soup"]);++ let read: serde_json::Value = from_js(+ resolved(engine.read_query(+ Some("tab:z".into()),+ QUERY.into(),+ Some("Soup".into()),+ js(vars.clone()),+ JsValue::UNDEFINED,+ ))+ .await,+ );+ assert_eq!(read["kind"], "hit");+ assert_eq!(read["data"], soup_data("doc-1"));+ let read: serde_json::Value = from_js(+ resolved(engine.read_query(+ Some("tab:a".into()),+ QUERY.into(),+ Some("Soup".into()),+ js(vars.clone()),+ JsValue::UNDEFINED,+ ))+ .await,+ );+ assert_eq!(read["kind"], "hit");++ let affected: Vec<String> =+ from_js(resolved(engine.invalidate_keys(vec!["GraphqlSoupDocument:doc-1".into()])).await);+ assert_eq!(affected, ["tab:z", "tab:a"]);++ resolved(engine.delete_keys(vec!["GraphqlSoupDocument:doc-1".into()])).await;+ let read: serde_json::Value = from_js(+ resolved(engine.read_query(+ Some("tab:z".into()),+ QUERY.into(),+ Some("Soup".into()),+ js(vars),+ JsValue::UNDEFINED,+ ))+ .await,+ );+ assert_eq!(read["kind"], "miss");++ close_and_destroy(&engine, SCOPE).await;+}++#[wasm_bindgen_test(async)]+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,+ QUERY.into(),+ Some("Soup".into()),+ js(variables()),+ js(serde_json::json!({+ "user": {+ "id": "user-1",+ "soup": {+ "nextCursor": null,+ "items": [{+ "__typename": "GraphqlSoupEmailThread",+ "id": "thread-1"+ }]+ }+ }+ })),+ None,+ ))+ .await;++ let direct_query = r#"query Email($input: EmailThreadInput!) {+ user { id emailThread(input: $input) { __typename id } }+ }"#;+ let result: serde_json::Value = from_js(+ resolved(engine.read_query(+ Some("tab:entity".into()),+ direct_query.into(),+ Some("Email".into()),+ js(serde_json::json!({"input": {"threadId": "thread-1"}})),+ js(serde_json::json!([{+ "parentType": "GraphqlUser",+ "fieldName": "emailThread",+ "targetType": "GraphqlSoupEmailThread",+ "argumentPath": ["input", "threadId"]+ }])),+ ))+ .await,+ );+ assert_eq!(result["kind"], "hit");+ assert_eq!(result["data"]["user"]["emailThread"]["id"], "thread-1");++ close_and_destroy(&engine, SCOPE).await;+}++#[wasm_bindgen_test(async)]+async fn queue_and_optimistic_layers_survive_preserve_reopen_in_id_order() {+ const SCOPE: &str = "cache-wasm-wp07-queue-reopen";+ let engine = fresh_engine(SCOPE).await;+ let vars = variables();+ resolved(engine.write_query(+ None,+ PROPERTY_QUERY.into(),+ Some("Soup".into()),+ js(vars.clone()),+ js(property_base()),+ None,+ ))+ .await;++ let first: serde_json::Value = from_js(+ resolved(engine.enqueue_optimistic_mutation(+ None,+ PROPERTY_MUTATION.into(),+ Some("SetEntityProperty".into()),+ js(mutation_variables()),+ js(serde_json::json!({+ "setEntityProperty": { "id": "prop-1", "displayName": "First" }+ })),+ JsValue::UNDEFINED,+ JsValue::UNDEFINED,+ 1.0,+ "first-owner".into(),+ 0.0,+ 50.0,+ ))+ .await,+ );+ assert_eq!(first["initialClaim"]["kind"], "claimed");++ let second: serde_json::Value = from_js(+ resolved(engine.enqueue_optimistic_mutation(+ None,+ PROPERTY_MUTATION.into(),+ Some("SetEntityProperty".into()),+ js(mutation_variables()),+ js(serde_json::json!({+ "setEntityProperty": { "id": "prop-1", "displayName": "Second" }+ })),+ JsValue::UNDEFINED,+ JsValue::UNDEFINED,+ 2.0,+ "second-owner".into(),+ 0.0,+ 50.0,+ ))+ .await,+ );+ assert_eq!(second["initialClaim"]["kind"], "not-runnable");+ let first_id = first["transactionId"].as_str().unwrap().to_owned();+ let second_id = second["transactionId"].as_str().unwrap().to_owned();++ resolved(engine.close()).await;+ let reopened = open_cache(SCOPE.into(), None)+ .await+ .expect("reopen preserved cache");+ let optimistic: serde_json::Value = from_js(+ resolved(reopened.read_query(+ Some("tab:queue".into()),+ PROPERTY_QUERY.into(),+ Some("Soup".into()),+ js(vars.clone()),+ JsValue::UNDEFINED,+ ))+ .await,+ );+ assert_eq!(+ optimistic["data"]["user"]["soup"]["items"][0]["properties"][0]["displayName"],+ "Second"+ );++ let first_claim: serde_json::Value =+ from_js(resolved(reopened.claim_next_mutation("reopener".into(), 50.0, 100.0)).await);+ assert_eq!(first_claim["transactionId"], first_id);+ resolved(reopened.rollback_optimistic_write(+ first_id,+ "reopener".into(),+ first_claim["leaseGeneration"].as_str().unwrap().into(),+ ))+ .await;++ let second_claim: serde_json::Value =+ from_js(resolved(reopened.claim_next_mutation("reopener".into(), 50.0, 100.0)).await);+ assert_eq!(second_claim["transactionId"], second_id);+ resolved(reopened.rollback_optimistic_write(+ second_id,+ "reopener".into(),+ second_claim["leaseGeneration"].as_str().unwrap().into(),+ ))+ .await;++ let base: serde_json::Value = from_js(+ resolved(reopened.read_query(+ Some("tab:queue".into()),+ PROPERTY_QUERY.into(),+ Some("Soup".into()),+ js(vars),+ JsValue::UNDEFINED,+ ))+ .await,+ );+ assert_eq!(+ base["data"]["user"]["soup"]["items"][0]["properties"][0]["displayName"],+ "Status"+ );++ close_and_destroy(&reopened, SCOPE).await;+}++#[wasm_bindgen_test(async)]+async fn optimistic_commit_reports_affected_ops_and_rejects_settled_or_malformed_ids() {+ const SCOPE: &str = "cache-wasm-wp07-optimistic-commit";+ let engine = fresh_engine(SCOPE).await;+ let vars = variables();+ resolved(engine.write_query(+ None,+ PROPERTY_QUERY.into(),+ Some("Soup".into()),+ js(vars.clone()),+ js(property_base()),+ None,+ ))+ .await;+ resolved(engine.read_query(+ Some("tab:optimistic".into()),+ PROPERTY_QUERY.into(),+ Some("Soup".into()),+ js(vars.clone()),+ JsValue::UNDEFINED,+ ))+ .await;++ let enqueue: serde_json::Value = from_js(+ resolved(engine.enqueue_optimistic_mutation(+ None,+ PROPERTY_MUTATION.into(),+ Some("SetEntityProperty".into()),+ js(mutation_variables()),+ js(serde_json::json!({+ "setEntityProperty": { "id": "prop-1", "displayName": "Stage" }+ })),+ JsValue::UNDEFINED,+ JsValue::UNDEFINED,+ 123.0,+ "runner".into(),+ 10.0,+ 1_000.0,+ ))+ .await,+ );+ let transaction_id = enqueue["transactionId"].as_str().unwrap().to_owned();+ let generation = enqueue["initialClaim"]["mutation"]["leaseGeneration"]+ .as_str()+ .unwrap()+ .to_owned();+ assert_eq!(+ enqueue["affectedOps"],+ serde_json::json!(["tab:optimistic"])+ );++ let commit: serde_json::Value = from_js(+ resolved(engine.commit_optimistic_write(+ transaction_id.clone(),+ "runner".into(),+ generation.clone(),+ PROPERTY_MUTATION.into(),+ Some("SetEntityProperty".into()),+ js(mutation_variables()),+ js(serde_json::json!({+ "setEntityProperty": { "id": "prop-1", "displayName": "Stage!" }+ })),+ ))+ .await,+ );+ assert_eq!(+ commit["changed"],+ serde_json::json!(["GraphqlProperty:prop-1"])+ );+ assert_eq!(commit["affectedOps"], serde_json::json!(["tab:optimistic"]));++ let read: serde_json::Value = from_js(+ resolved(engine.read_query(+ Some("tab:optimistic".into()),+ PROPERTY_QUERY.into(),+ Some("Soup".into()),+ js(vars),+ JsValue::UNDEFINED,+ ))+ .await,+ );+ assert_eq!(+ read["data"]["user"]["soup"]["items"][0]["properties"][0]["displayName"],+ "Stage!"+ );++ assert!(+ JsFuture::from(engine.rollback_optimistic_write(+ transaction_id,+ "runner".into(),+ generation,+ ))+ .await+ .is_err()+ );+ assert!(+ JsFuture::from(engine.rollback_optimistic_write(+ "not-a-number".into(),+ "runner".into(),+ "1".into(),+ ))+ .await+ .is_err()+ );++ close_and_destroy(&engine, SCOPE).await;+}++#[wasm_bindgen_test(async)]+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,+ PROPERTY_QUERY.into(),+ Some("Soup".into()),+ js(variables()),+ js(property_base()),+ Some("user-1".into()),+ ))+ .await;+ resolved(engine.enqueue_optimistic_mutation(+ None,+ PROPERTY_MUTATION.into(),+ Some("SetEntityProperty".into()),+ js(mutation_variables()),+ js(serde_json::json!({+ "setEntityProperty": { "id": "prop-1", "displayName": "Queued" }+ })),+ JsValue::UNDEFINED,+ JsValue::UNDEFINED,+ 1.0,+ "destroy-owner".into(),+ 0.0,+ 100.0,+ ))+ .await;+ resolved(engine.close()).await;++ destroy_cache(SCOPE.into()).await.expect("recovery wipe");+ let replacement = open_cache(SCOPE.into(), None)+ .await+ .expect("open replacement");+ let read: serde_json::Value = from_js(+ resolved(replacement.read_query(+ None,+ QUERY.into(),+ Some("Soup".into()),+ js(variables()),+ JsValue::UNDEFINED,+ ))+ .await,+ );+ assert_eq!(read["kind"], "miss");+ let identity: Option<String> = from_js(resolved(replacement.bound_identity()).await);+ assert_eq!(identity, None);+ let claimed =+ resolved(replacement.claim_next_mutation("replacement".into(), 100.0, 200.0)).await;+ assert!(claimed.is_undefined() || claimed.is_null());++ close_and_destroy(&replacement, SCOPE).await;+}++#[wasm_bindgen_test(async)]+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,+ QUERY.into(),+ Some("Soup".into()),+ js(variables()),+ js(soup_data("must-be-wiped")),+ Some("user-1".into()),+ ))+ .await;+ resolved(engine.close()).await;++ let replacement = open_cache_for_recovery(SCOPE.into(), None)+ .await+ .expect("atomic recovery open");+ let read: serde_json::Value = from_js(+ resolved(replacement.read_query(+ None,+ QUERY.into(),+ Some("Soup".into()),+ js(variables()),+ JsValue::UNDEFINED,+ ))+ .await,+ );+ assert_eq!(read["kind"], "miss");+ let identity: Option<String> = from_js(resolved(replacement.bound_identity()).await);+ assert_eq!(identity, None);++ close_and_destroy(&replacement, SCOPE).await;+}++#[wasm_bindgen_test(async)]+async fn incompatible_initialization_resets_and_identity_reset_does_not_latch() {+ const SCOPE: &str = "cache-wasm-wp07-resets";+ let owner = OpfsOwner::acquire(&database_identity(SCOPE))+ .await+ .expect("acquire incompatible database")+ .recovery_wipe()+ .await+ .expect("start incompatible database fresh");+ let OpenResult::Ready(session) = owner.open().await.expect("open incompatible database") else {+ panic!("recovery wipe creates a complete pair")+ };+ let incompatible = TursoStorage::from_opfs_session(+ session.connect().expect("connect incompatible database"),+ "different-scope",+ )+ .expect("initialize incompatible metadata");+ let TursoStorageCloseOutcome::Healthy(closed) = incompatible+ .try_close()+ .expect("close incompatible database")+ else {+ panic!("new incompatible database is otherwise healthy")+ };+ closed+ .preserve()+ .expect("preserve incompatible metadata")+ .release()+ .await+ .expect("release incompatible owner");++ let engine = open_cache(SCOPE.into(), None)+ .await+ .expect("incompatible initialization is reset and reopened");+ let read: serde_json::Value = from_js(+ resolved(engine.read_query(+ None,+ QUERY.into(),+ Some("Soup".into()),+ js(variables()),+ JsValue::UNDEFINED,+ ))+ .await,+ );+ assert_eq!(read["kind"], "miss");++ let first_identity: serde_json::Value = from_js(+ resolved(engine.write_query(+ None,+ QUERY.into(),+ Some("Soup".into()),+ js(variables()),+ js(soup_data("identity-a")),+ Some("identity-a".into()),+ ))+ .await,+ );+ assert_eq!(first_identity["reset"], false);+ let normal_identity_reset: serde_json::Value = from_js(+ resolved(engine.write_query(+ None,+ QUERY.into(),+ Some("Soup".into()),+ js(variables()),+ js(soup_data("identity-b")),+ Some("identity-b".into()),+ ))+ .await,+ );+ assert_eq!(normal_identity_reset["reset"], true);+ let identity: Option<String> = from_js(resolved(engine.bound_identity()).await);+ assert_eq!(identity.as_deref(), Some("identity-b"));++ close_and_destroy(&engine, SCOPE).await;+}++#[wasm_bindgen_test(async)]+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,+ QUERY.into(),+ Some("Soup".into()),+ js(variables()),+ js(soup_data("reset-latch")),+ Some("identity".into()),+ ))+ .await;+ resolved(engine.invalidate_keys(vec!["GraphqlSoupDocument:reset-latch".into()])).await;+ engine.arm_storage_fault(TestStorageFault::GetBatch).await;++ assert_reset_required(engine.read_query(+ Some("tab:latched".into()),+ QUERY.into(),+ Some("Soup".into()),+ js(variables()),+ JsValue::UNDEFINED,+ ))+ .await;+ assert_reset_required(engine.bound_identity()).await;+ assert_reset_required(engine.invalidate_keys(vec!["GraphqlSoupDocument:any".into()])).await;+ assert_reset_required(engine.external_reset()).await;+ assert_reset_required(engine.teardown_operation("tab:latched".into())).await;+ assert_reset_required(engine.read_query(+ None,+ QUERY.into(),+ Some("Soup".into()),+ JsValue::from_str("malformed variables must not mask the latch"),+ JsValue::UNDEFINED,+ ))+ .await;+ assert_reset_required(engine.write_query(+ None,+ QUERY.into(),+ Some("Soup".into()),+ js(variables()),+ js(soup_data("blocked")),+ None,+ ))+ .await;+ assert_reset_required(engine.clear()).await;++ resolved(engine.physical_reset()).await;+ let identity: Option<String> = from_js(resolved(engine.bound_identity()).await);+ assert_eq!(identity, None);++ resolved(engine.write_query(+ None,+ PROPERTY_QUERY.into(),+ Some("Soup".into()),+ js(variables()),+ js(property_base()),+ None,+ ))+ .await;+ engine+ .arm_storage_fault(TestStorageFault::ClaimNextMutation)+ .await;+ assert_reset_required(engine.enqueue_optimistic_mutation(+ None,+ PROPERTY_MUTATION.into(),+ Some("SetEntityProperty".into()),+ js(mutation_variables()),+ js(serde_json::json!({+ "setEntityProperty": { "id": "prop-1", "displayName": "Nested" }+ })),+ JsValue::UNDEFINED,+ JsValue::UNDEFINED,+ 1.0,+ "nested-owner".into(),+ 0.0,+ 100.0,+ ))+ .await;+ assert_reset_required(engine.bound_identity()).await;++ resolved(engine.physical_reset()).await;+ close_and_destroy(&engine, SCOPE).await;+}++#[wasm_bindgen_test(async)]+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,+ PROPERTY_QUERY.into(),+ Some("Soup".into()),+ js(variables()),+ js(property_base()),+ None,+ ))+ .await;+ resolved(engine.read_query(+ Some("tab:retained".into()),+ PROPERTY_QUERY.into(),+ Some("Soup".into()),+ js(variables()),+ JsValue::UNDEFINED,+ ))+ .await;+ let retained_id = *engine+ .ops+ .borrow()+ .by_name+ .get("tab:retained")+ .expect("operation is interned before reset");+ resolved(engine.enqueue_optimistic_mutation(+ None,+ PROPERTY_MUTATION.into(),+ Some("SetEntityProperty".into()),+ js(mutation_variables()),+ js(serde_json::json!({+ "setEntityProperty": { "id": "prop-1", "displayName": "Queued" }+ })),+ JsValue::UNDEFINED,+ JsValue::UNDEFINED,+ 1.0,+ "reset-owner".into(),+ 0.0,+ 100.0,+ ))+ .await;++ let concurrent = js_sys::Array::new();+ concurrent.push(&engine.physical_reset());+ concurrent.push(&engine.write_query(+ None,+ PROPERTY_QUERY.into(),+ Some("Soup".into()),+ js(variables()),+ js(property_base()),+ None,+ ));+ JsFuture::from(js_sys::Promise::all(&concurrent))+ .await+ .expect("concurrent call waits for physical reset and uses the replacement");++ assert_eq!(+ engine.ops.borrow().by_name.get("tab:retained"),+ Some(&retained_id)+ );+ let claimed = resolved(engine.claim_next_mutation("replacement".into(), 100.0, 200.0)).await;+ assert!(claimed.is_undefined() || claimed.is_null());++ let read: serde_json::Value = from_js(+ resolved(engine.read_query(+ Some("tab:retained".into()),+ PROPERTY_QUERY.into(),+ Some("Soup".into()),+ js(variables()),+ JsValue::UNDEFINED,+ ))+ .await,+ );+ assert_eq!(read["kind"], "hit");+ let write: serde_json::Value = from_js(+ resolved(engine.write_query(+ Some("tab:writer".into()),+ PROPERTY_QUERY.into(),+ Some("Soup".into()),+ js(variables()),+ js(property_data("Updated")),+ None,+ ))+ .await,+ );+ assert_eq!(write["affectedOps"], serde_json::json!(["tab:retained"]));++ close_and_destroy(&engine, SCOPE).await;+}++#[wasm_bindgen_test(async)]+async fn zero_hot_capacity_rejects_before_opfs_and_does_not_leak_the_lock() {+ const SCOPE: &str = "cache-wasm-wp07-zero-capacity";+ destroy_cache(SCOPE.into())+ .await+ .expect("clean capacity test");+ let error = match open_cache(SCOPE.into(), Some(0)).await {+ Ok(_) => panic!("zero capacity must reject"),+ Err(error) => error,+ };+ assert!(error.is_instance_of::<js_sys::Error>());+ let message = js_sys::Reflect::get(&error, &JsValue::from_str("message"))+ .unwrap()+ .as_string()+ .unwrap();+ assert_eq!(message, "hot capacity must be greater than zero");++ let engine = open_cache(SCOPE.into(), Some(1))+ .await+ .expect("valid open succeeds after rejected capacity");+ close_and_destroy(&engine, SCOPE).await;+}++#[wasm_bindgen_test(async)]+async fn every_method_rejects_after_consuming_close() {+ const SCOPE: &str = "cache-wasm-wp07-closed";+ let engine = fresh_engine(SCOPE).await;+ resolved(engine.close()).await;++ assert_closed(engine.bound_identity()).await;+ assert_closed(engine.read_query(+ None,+ QUERY.into(),+ Some("Soup".into()),+ js(variables()),+ JsValue::UNDEFINED,+ ))+ .await;+ assert_closed(engine.read_records(+ RECORD_FRAGMENT.into(),+ "CachedDocument".into(),+ JsValue::UNDEFINED,+ 1,+ ))+ .await;+ assert_closed(engine.write_query(+ None,+ QUERY.into(),+ Some("Soup".into()),+ js(variables()),+ js(soup_data("closed")),+ None,+ ))+ .await;+ assert_closed(engine.enqueue_optimistic_mutation(+ None,+ PROPERTY_MUTATION.into(),+ Some("SetEntityProperty".into()),+ js(mutation_variables()),+ js(serde_json::json!({+ "setEntityProperty": { "id": "prop-1", "displayName": "Closed" }+ })),+ JsValue::UNDEFINED,+ JsValue::UNDEFINED,+ 1.0,+ "closed".into(),+ 1.0,+ 2.0,+ ))+ .await;+ assert_closed(engine.inspect_query_variants(+ QUERY.into(),+ Some("Soup".into()),+ js(serde_json::json!([{"field": "user"}, {"field": "soup"}])),+ ))+ .await;+ assert_closed(engine.inspect_query(+ QUERY.into(),+ Some("Soup".into()),+ js(serde_json::json!([{"field": "user"}, {"field": "soup"}])),+ js(serde_json::json!([])),+ ))+ .await;+ assert_closed(engine.claim_next_mutation("closed".into(), 1.0, 2.0)).await;+ assert_closed(engine.defer_optimistic_write(+ "1".into(),+ "closed".into(),+ "1".into(),+ 2.0,+ "closed".into(),+ ))+ .await;+ assert_closed(engine.commit_optimistic_write(+ "1".into(),+ "closed".into(),+ "1".into(),+ PROPERTY_MUTATION.into(),+ Some("SetEntityProperty".into()),+ js(mutation_variables()),+ js(serde_json::json!({+ "setEntityProperty": { "id": "prop-1", "displayName": "Closed" }+ })),+ ))+ .await;+ assert_closed(engine.rollback_optimistic_write("1".into(), "closed".into(), "1".into())).await;+ assert_closed(engine.invalidate_keys(vec!["GraphqlSoupDocument:1".into()])).await;+ assert_closed(engine.delete_keys(vec!["GraphqlSoupDocument:1".into()])).await;+ assert_closed(engine.refresh_optimistic_queue()).await;+ assert_closed(engine.external_reset()).await;+ assert_closed(engine.teardown_operation("closed:1".into())).await;+ assert_closed(engine.clear()).await;+ assert_closed(engine.physical_reset()).await;+ assert_closed(engine.close()).await;++ destroy_cache(SCOPE.into())+ .await+ .expect("destroy closed cache");+}++#[wasm_bindgen_test(async)]+async fn calls_serialize_and_owner_lock_excludes_a_second_open() {+ const SCOPE: &str = "cache-wasm-wp07-serialization-lock";+ let engine = fresh_engine(SCOPE).await;+ assert!(open_cache(SCOPE.into(), None).await.is_err());++ let writes = js_sys::Array::new();+ writes.push(&engine.write_query(+ None,+ QUERY.into(),+ Some("Soup".into()),+ js(variables()),+ js(soup_data("first")),+ None,+ ));+ writes.push(&engine.write_query(+ None,+ QUERY.into(),+ Some("Soup".into()),+ js(variables()),+ js(soup_data("second")),+ None,+ ));+ JsFuture::from(js_sys::Promise::all(&writes))+ .await+ .expect("overlapping calls serialize without reentrancy");++ let read: serde_json::Value = from_js(+ resolved(engine.read_query(+ None,+ QUERY.into(),+ Some("Soup".into()),+ js(variables()),+ JsValue::UNDEFINED,+ ))+ .await,+ );+ assert_eq!(read["data"], soup_data("second"));++ resolved(engine.close()).await;+ let reopened = open_cache(SCOPE.into(), None)+ .await+ .expect("close releases owner lock");+ close_and_destroy(&reopened, SCOPE).await;+}diff --git a/crates/client/cache-wasm/src/shell/test_storage.rs b/crates/client/cache-wasm/src/shell/test_storage.rsnew file mode 100644index 0000000000..dc4428b7a9--- /dev/null+++ b/crates/client/cache-wasm/src/shell/test_storage.rs@@ -0,0 +1,135 @@+use cache_core::queue::{+ ClaimedMutation, MutationClaimRequest, MutationClaimToken, MutationId, NewQueuedMutation,+ QueuedMutation,+};+use cache_core::store::{QueueDiagnostics, Storage};+use cache_core::value::{EntityKey, Record};+use cache_turso::{PhysicalResetReason, TursoStorage, TursoStorageError};+use std::sync::atomic::{AtomicU8, Ordering};++#[derive(Clone, Copy)]+pub(super) enum TestStorageFault {+ GetBatch = 1,+ ClaimNextMutation = 2,+}++pub(super) struct BrowserStorage {+ inner: TursoStorage,+ fault: AtomicU8,+}++impl BrowserStorage {+ pub(super) fn new(inner: TursoStorage) -> Self {+ Self {+ inner,+ fault: AtomicU8::new(0),+ }+ }++ pub(super) fn into_inner(self) -> TursoStorage {+ self.inner+ }++ pub(super) fn arm(&self, fault: TestStorageFault) {+ self.fault.store(fault as u8, Ordering::Release);+ }++ fn take(&self, fault: TestStorageFault) -> Result<(), TursoStorageError> {+ if self+ .fault+ .compare_exchange(fault as u8, 0, Ordering::AcqRel, Ordering::Acquire)+ .is_ok()+ {+ Err(TursoStorageError::PhysicalResetRequired(+ PhysicalResetReason::Codec,+ ))+ } else {+ Ok(())+ }+ }+}++impl Storage for BrowserStorage {+ type Error = TursoStorageError;++ async fn get_batch(&self, keys: &[EntityKey<'_>]) -> Result<Vec<Option<Record>>, Self::Error> {+ self.take(TestStorageFault::GetBatch)?;+ self.inner.get_batch(keys).await+ }++ async fn put_batch(+ &mut self,+ entries: Vec<(EntityKey<'static>, Record)>,+ ) -> Result<(), Self::Error> {+ self.inner.put_batch(entries).await+ }++ async fn delete_batch(&mut self, keys: &[EntityKey<'static>]) -> Result<(), Self::Error> {+ self.inner.delete_batch(keys).await+ }++ async fn scan_records(+ &self,+ type_names: &[String],+ after: Option<&EntityKey<'static>>,+ limit: usize,+ ) -> Result<Vec<(EntityKey<'static>, Record)>, Self::Error> {+ self.inner.scan_records(type_names, after, limit).await+ }++ async fn enqueue_mutation(+ &mut self,+ entry: NewQueuedMutation,+ ) -> Result<MutationId, Self::Error> {+ self.inner.enqueue_mutation(entry).await+ }++ async fn load_mutation_queue(&self) -> Result<Vec<QueuedMutation>, Self::Error> {+ self.inner.load_mutation_queue().await+ }++ async fn queue_diagnostics(&self) -> Result<QueueDiagnostics, Self::Error> {+ self.inner.queue_diagnostics().await+ }++ async fn claim_next_mutation(+ &mut self,+ request: MutationClaimRequest,+ ) -> Result<Option<ClaimedMutation>, Self::Error> {+ self.take(TestStorageFault::ClaimNextMutation)?;+ self.inner.claim_next_mutation(request).await+ }++ async fn defer_mutation(+ &mut self,+ id: MutationId,+ claim: MutationClaimToken,+ next_attempt_at_ms: i64,+ error: String,+ ) -> Result<bool, Self::Error> {+ self.inner+ .defer_mutation(id, claim, next_attempt_at_ms, error)+ .await+ }++ async fn complete_mutation(+ &mut self,+ id: MutationId,+ claim: MutationClaimToken,+ entries: Vec<(EntityKey<'static>, Record)>,+ ) -> Result<bool, Self::Error> {+ self.inner.complete_mutation(id, claim, entries).await+ }++ async fn discard_mutation(+ &mut self,+ id: MutationId,+ claim: MutationClaimToken,+ ) -> Result<bool, Self::Error> {+ self.inner.discard_mutation(id, claim).await+ }++ async fn clear(&mut self) -> Result<(), Self::Error> {+ self.inner.clear().await+ }+}diff --git a/crates/client/cache-wasm/tests/web.rs b/crates/client/cache-wasm/tests/web.rsdeleted file mode 100644index efd6a5f867..0000000000--- a/crates/client/cache-wasm/tests/web.rs+++ /dev/null@@ -1,361 +0,0 @@-//! Browser tests for the wasm shell (JsValue boundary + async mutex).-//! Run like cache-idb's tests (see workspace README).--#![cfg(target_arch = "wasm32")]--use cache_wasm::{destroy_cache, open_cache};-use wasm_bindgen::JsValue;-use wasm_bindgen_futures::JsFuture;-use wasm_bindgen_test::*;--wasm_bindgen_test_configure!(run_in_browser);--const QUERY: &str = r#"query Soup($input: SoupInput!) {- user {- id- soup(input: $input) {- nextCursor- items {- __typename- id- }- }- }-}"#;--fn js(json: serde_json::Value) -> JsValue {- use serde::Serialize;- json.serialize(&serde_wasm_bindgen::Serializer::json_compatible())- .unwrap()-}--#[wasm_bindgen_test]-async fn write_then_read_through_js_boundary() {- destroy_cache("wasm-shell-test".into()).await.unwrap();- let engine = open_cache("wasm-shell-test".into(), None).await.unwrap();-- let vars = serde_json::json!({"input": {"limit": 1}});- let data = serde_json::json!({- "user": {- "id": "user-1",- "soup": {- "nextCursor": null,- "items": [{ "__typename": "GraphqlSoupDocument", "id": "doc-1" }]- }- }- });-- // Miss first.- let read = JsFuture::from(engine.read_query(- Some("tab1:1".into()),- QUERY.into(),- Some("Soup".into()),- js(vars.clone()),- JsValue::UNDEFINED,- ))- .await- .unwrap();- let read: serde_json::Value = serde_wasm_bindgen::from_value(read).unwrap();- assert_eq!(read["kind"], "miss");-- // Write via op 2 (tagged with the viewer identity), expect op 1- // affected (registered on the miss).- let write = JsFuture::from(engine.write_query(- Some("tab1:2".into()),- QUERY.into(),- Some("Soup".into()),- js(vars.clone()),- js(data.clone()),- Some("user-1".into()),- ))- .await- .unwrap();- let write: serde_json::Value = serde_wasm_bindgen::from_value(write).unwrap();- assert!(!write["changed"].as_array().unwrap().is_empty());- assert_eq!(write["affectedOps"], serde_json::json!(["tab1:1"]));- assert_eq!(write["reset"], serde_json::json!(false));-- let identity = JsFuture::from(engine.bound_identity()).await.unwrap();- let identity: Option<String> = serde_wasm_bindgen::from_value(identity).unwrap();- assert_eq!(identity.as_deref(), Some("user-1"));-- // Hit now; data is a plain JS object round-tripped exactly.- let read = JsFuture::from(engine.read_query(- Some("tab1:1".into()),- QUERY.into(),- Some("Soup".into()),- js(vars.clone()),- JsValue::UNDEFINED,- ))- .await- .unwrap();- let read: serde_json::Value = serde_wasm_bindgen::from_value(read).unwrap();- assert_eq!(read["kind"], "hit");- assert_eq!(read["data"], data);-- // Variables-only inspection crosses the wasm boundary without- // materializing the selected value.- let variants = JsFuture::from(engine.inspect_query_variants(- QUERY.into(),- Some("Soup".into()),- js(serde_json::json!([{"field": "user"}, {"field": "soup"}])),- ))- .await- .unwrap();- let variants: serde_json::Value = serde_wasm_bindgen::from_value(variants).unwrap();- assert_eq!(variants[0]["variables"], vars);- assert!(variants[0].get("value").is_none());-- // Full generated-query inspection also materializes the selected value.- let inspected = JsFuture::from(engine.inspect_query(- QUERY.into(),- Some("Soup".into()),- js(serde_json::json!([{"field": "user"}, {"field": "soup"}])),- js(serde_json::json!([])),- ))- .await- .unwrap();- let inspected: serde_json::Value = serde_wasm_bindgen::from_value(inspected).unwrap();- assert_eq!(inspected[0]["variables"], vars);- assert_eq!(inspected[0]["value"], data["user"]["soup"]);-- // Cross-instance invalidation path: evict + report local dependents.- let affected =- JsFuture::from(engine.invalidate_keys(vec!["GraphqlSoupDocument:doc-1".to_string()]))- .await- .unwrap();- let affected: Vec<String> = serde_wasm_bindgen::from_value(affected).unwrap();- assert_eq!(affected, vec!["tab1:1".to_string()]);-- // External invalidation keeps the shared cold-tier record, while local- // mutation invalidation removes it from both tiers.- let read = JsFuture::from(engine.read_query(- Some("tab1:1".into()),- QUERY.into(),- Some("Soup".into()),- js(vars.clone()),- JsValue::UNDEFINED,- ))- .await- .unwrap();- let read: serde_json::Value = serde_wasm_bindgen::from_value(read).unwrap();- assert_eq!(read["kind"], "hit");-- JsFuture::from(engine.delete_keys(vec!["GraphqlSoupDocument:doc-1".to_string()]))- .await- .unwrap();- let read = JsFuture::from(engine.read_query(- Some("tab1:1".into()),- QUERY.into(),- Some("Soup".into()),- js(vars),- JsValue::UNDEFINED,- ))- .await- .unwrap();- let read: serde_json::Value = serde_wasm_bindgen::from_value(read).unwrap();- assert_eq!(read["kind"], "miss");-- // Lifecycle: close the connection, then deletion completes (would hang- // on a live connection without versionchange auto-close).- JsFuture::from(engine.close()).await.unwrap();- destroy_cache("wasm-shell-test".into()).await.unwrap();-}--#[wasm_bindgen_test]-async fn entity_resolvers_cross_the_js_boundary() {- destroy_cache("wasm-shell-entity-resolver".into())- .await- .unwrap();- let engine = open_cache("wasm-shell-entity-resolver".into(), None)- .await- .unwrap();- let soup_variables = serde_json::json!({"input": {"limit": 1}});- JsFuture::from(engine.write_query(- None,- QUERY.into(),- Some("Soup".into()),- js(soup_variables),- js(serde_json::json!({- "user": {- "id": "user-1",- "soup": {- "nextCursor": null,- "items": [{- "__typename": "GraphqlSoupEmailThread",- "id": "thread-1"- }]- }- }- })),- None,- ))- .await- .unwrap();-- let direct_query = r#"query Email($input: EmailThreadInput!) {- user { id emailThread(input: $input) { __typename id } }- }"#;- let result = JsFuture::from(engine.read_query(- Some("tab1:entity".into()),- direct_query.into(),- Some("Email".into()),- js(serde_json::json!({"input": {"threadId": "thread-1"}})),- js(serde_json::json!([{- "parentType": "GraphqlUser",- "fieldName": "emailThread",- "targetType": "GraphqlSoupEmailThread",- "argumentPath": ["input", "threadId"]- }])),- ))- .await- .unwrap();- let result: serde_json::Value = serde_wasm_bindgen::from_value(result).unwrap();- assert_eq!(result["kind"], "hit");- assert_eq!(result["data"]["user"]["emailThread"]["id"], "thread-1");-- JsFuture::from(engine.close()).await.unwrap();- destroy_cache("wasm-shell-entity-resolver".into())- .await- .unwrap();-}--const PROPERTY_QUERY: &str = r#"query Soup($input: SoupInput!) {- user { id soup(input: $input) { nextCursor items {- __typename- id- ... on GraphqlSoupDocument { properties { id displayName } }- } } }-}"#;--const PROPERTY_MUTATION: &str = r#"mutation SetEntityProperty($input: SetEntityPropertyInput!) {- setEntityProperty(input: $input) { id displayName }-}"#;--#[wasm_bindgen_test]-async fn optimistic_write_round_trip() {- destroy_cache("wasm-shell-optimistic".into()).await.unwrap();- let engine = open_cache("wasm-shell-optimistic".into(), None)- .await- .unwrap();-- let vars = serde_json::json!({"input": {"limit": 1}});- let base = serde_json::json!({- "user": { "id": "user-1", "soup": { "nextCursor": null, "items": [{- "__typename": "GraphqlSoupDocument",- "id": "doc-1",- "properties": [{ "id": "prop-1", "displayName": "Status" }]- }] } }- });- JsFuture::from(engine.write_query(- None,- PROPERTY_QUERY.into(),- Some("Soup".into()),- js(vars.clone()),- js(base),- None,- ))- .await- .unwrap();- // Register op 1 against the property record.- let read = JsFuture::from(engine.read_query(- Some("tab1:1".into()),- PROPERTY_QUERY.into(),- Some("Soup".into()),- js(vars.clone()),- JsValue::UNDEFINED,- ))- .await- .unwrap();- let read: serde_json::Value = serde_wasm_bindgen::from_value(read).unwrap();- assert_eq!(read["kind"], "hit");-- let mutation_vars = serde_json::json!({"input": {- "entityType": "DOCUMENT",- "entityId": "doc-1",- "propertyDefinitionId": "def-1",- "value": { "string": "x" }- }});-- // Enqueue: op 1 is affected and the strict head is already claimed.- let enqueue = JsFuture::from(engine.enqueue_optimistic_mutation(- None,- PROPERTY_MUTATION.into(),- Some("SetEntityProperty".into()),- js(mutation_vars.clone()),- js(serde_json::json!({ "setEntityProperty": { "id": "prop-1", "displayName": "Stage" } })),- JsValue::UNDEFINED,- JsValue::UNDEFINED,- 123.0,- "runner".into(),- 10.0,- 1_000.0,- ))- .await- .unwrap();- let enqueue: serde_json::Value = serde_wasm_bindgen::from_value(enqueue).unwrap();- let txn = enqueue["transactionId"].as_str().unwrap().to_string();- assert_eq!(enqueue["affectedOps"], serde_json::json!(["tab1:1"]));- assert_eq!(- enqueue["changed"],- serde_json::json!(["GraphqlProperty:prop-1"])- );- assert_eq!(enqueue["initialClaim"]["kind"], "claimed");- assert_eq!(enqueue["initialClaim"]["mutation"]["transactionId"], txn);-- // The optimistic layer is visible through reads.- let read = JsFuture::from(engine.read_query(- Some("tab1:1".into()),- PROPERTY_QUERY.into(),- Some("Soup".into()),- js(vars.clone()),- JsValue::UNDEFINED,- ))- .await- .unwrap();- let read: serde_json::Value = serde_wasm_bindgen::from_value(read).unwrap();- assert_eq!(- read["data"]["user"]["soup"]["items"][0]["properties"][0]["displayName"],- serde_json::json!("Stage")- );-- let generation = enqueue["initialClaim"]["mutation"]["leaseGeneration"]- .as_str()- .unwrap()- .to_string();-- // Commit with the real response; the layer flushes durably.- let commit = JsFuture::from(engine.commit_optimistic_write(- txn.clone(),- "runner".into(),- generation.clone(),- PROPERTY_MUTATION.into(),- Some("SetEntityProperty".into()),- js(mutation_vars.clone()),- js(serde_json::json!({ "setEntityProperty": { "id": "prop-1", "displayName": "Stage!" } })),- ))- .await- .unwrap();- let commit: serde_json::Value = serde_wasm_bindgen::from_value(commit).unwrap();- assert_eq!(- commit["changed"],- serde_json::json!(["GraphqlProperty:prop-1"])- );- assert_eq!(commit["affectedOps"], serde_json::json!(["tab1:1"]));-- // Settled transactions reject further commits/rollbacks.- let err =- JsFuture::from(engine.rollback_optimistic_write(txn, "runner".into(), generation)).await;- assert!(err.is_err());- // Malformed ids reject too.- let err = JsFuture::from(engine.rollback_optimistic_write(- "not-a-number".into(),- "runner".into(),- "1".into(),- ))- .await;- assert!(err.is_err());-- JsFuture::from(engine.close()).await.unwrap();- destroy_cache("wasm-shell-optimistic".into()).await.unwrap();-}diff --git a/crates/client/turso-opfs/Cargo.toml b/crates/client/turso-opfs/Cargo.tomlnew file mode 100644index 0000000000..545129891d--- /dev/null+++ b/crates/client/turso-opfs/Cargo.toml@@ -0,0 +1,33 @@+[package]+edition = "2024"+name = "turso-opfs"+publish = false+version = "0.1.0"++# Production code is wasm32-only. The target-independent lifecycle machine is+# compiled natively only for its unit tests.++[target.'cfg(target_arch = "wasm32")'.dependencies]+js-sys = { workspace = true }+turso_core = { workspace = true, features = ["fs", "uuid"] }+wasm-bindgen = { workspace = true }+wasm-bindgen-futures = { workspace = true }+web-sys = { workspace = true, features = [+ "AbortController",+ "AbortSignal",+ "DedicatedWorkerGlobalScope",+ "DomException",+ "FileSystemDirectoryHandle",+ "FileSystemFileHandle",+ "FileSystemGetDirectoryOptions",+ "FileSystemGetFileOptions",+ "FileSystemReadWriteOptions",+ "FileSystemRemoveOptions",+ "FileSystemSyncAccessHandle",+ "StorageManager",+ "WorkerGlobalScope",+ "WorkerNavigator",+] }++[target.'cfg(target_arch = "wasm32")'.dev-dependencies]+wasm-bindgen-test = { workspace = true }diff --git a/crates/client/turso-opfs/README.md b/crates/client/turso-opfs/README.mdnew file mode 100644index 0000000000..187874d610--- /dev/null+++ b/crates/client/turso-opfs/README.md@@ -0,0 +1,60 @@+# turso-opfs++Browser-only Turso `Clock`/`IO`/`File` adapter for DedicatedWorker-owned OPFS.++## Ownership and recovery boundary++`OpfsOwner::acquire(database_identity)` validates one direct-child canonical+identity (reserving the `-wal` suffix) and derives both the exclusive Web Lock+name and main/WAL paths from it. There are no independent scope/path inputs or+main-as-WAL aliases that could map the same files to different locks. `open()`+accepts no path argument. The lock remains held+through Turso use, consuming close, preserve/reset, and idle ownership, and is+released only by `OpfsOwner::release()`.++`OpfsSession::connect()` constructs the approved Turso dialect/options and+private OPFS storage internally. Callers must never invoke `Connection::close`+directly; `ConnectedOpfsSession::try_close()` exclusively owns and proves that+transition. Turso open/connect failures poison and require worker replacement+followed by a fresh lock acquisition and `recovery_wipe()`.++The crate tests physical lock contention in its real DedicatedWorker. Actual+cross-worker termination/restart orchestration remains a WP-08 coordinator+harness responsibility: terminating a worker causes the browser to release its+Web Lock and worker-local JavaScript handles, after which the replacement worker+must acquire the same canonical database lock and call `recovery_wipe()` when the+coordinator selected wipe-before-open. Local tests do not claim cross-worker+termination proof.++## Repeatable verification++Run from the repository root:++```bash+cargo fmt -p turso-opfs -- --check+cargo test -p turso-opfs+cargo clippy -p turso-opfs --all-targets -- -D warnings+cargo check --target wasm32-unknown-unknown -p turso-opfs --all-targets+cargo clippy --target wasm32-unknown-unknown -p turso-opfs --all-targets -- -D warnings++# Each command compiles and runs the same #[wasm_bindgen_test] in a real+# DedicatedWorker with that browser's OPFS and Web Locks implementations.+wasm-pack test --headless --chrome crates/client/turso-opfs+wasm-pack test --headless --firefox crates/client/turso-opfs+```++On NixOS, `wasm-pack`'s downloaded WebDrivers may not have a runnable ELF+interpreter. Use the wasm-bindgen test runner with Nix-provided drivers instead:++```bash+CARGO_TARGET_WASM32_UNKNOWN_UNKNOWN_RUNNER=wasm-bindgen-test-runner \+CHROMEDRIVER=/path/to/nix/chromedriver \+WASM_BINDGEN_TEST_ONLY_WEB=1 \+cargo test --target wasm32-unknown-unknown -p turso-opfs --lib -- --nocapture++PATH=/path/to/nix/firefox:$PATH \+CARGO_TARGET_WASM32_UNKNOWN_UNKNOWN_RUNNER=wasm-bindgen-test-runner \+GECKODRIVER=/path/to/nix/geckodriver \+WASM_BINDGEN_TEST_ONLY_WEB=1 \+cargo test --target wasm32-unknown-unknown -p turso-opfs --lib -- --nocapture+```diff --git a/crates/client/turso-opfs/src/browser.rs b/crates/client/turso-opfs/src/browser.rsnew file mode 100644index 0000000000..2aa8d74461--- /dev/null+++ b/crates/client/turso-opfs/src/browser.rs@@ -0,0 +1,2265 @@+//! `wasm32` DedicatedWorker OPFS implementation.++use crate::state::{+ CloseToken, FileRole, HandleId, Machine, OwnerId, Paths, SessionId, StateError, StateErrorKind,+};+use js_sys::{Function, Object, Promise, Reflect};+use std::{+ cell::RefCell,+ collections::HashMap,+ fmt,+ io::ErrorKind,+ sync::{+ Arc,+ atomic::{AtomicU64, Ordering},+ },+};+use turso_core::{+ Buffer, Clock, Completion, CompletionError, Connection, Database, File, IO, LimboError,+ MonotonicInstant, OpenFlags, OpenOptions, SqliteDialect, WallClockInstant,+ io::{FileId, FileSyncType},+};+use wasm_bindgen::{JsCast, JsValue, closure::Closure, prelude::wasm_bindgen};+use wasm_bindgen_futures::JsFuture;+use web_sys::{+ AbortController, DedicatedWorkerGlobalScope, DomException, FileSystemDirectoryHandle,+ FileSystemFileHandle, FileSystemGetFileOptions, FileSystemReadWriteOptions,+ FileSystemRemoveOptions, FileSystemSyncAccessHandle,+};++#[cfg(test)]+mod test;++const MAX_SAFE_INTEGER: u64 = 9_007_199_254_740_991;++#[wasm_bindgen]+extern "C" {+ #[wasm_bindgen(js_namespace = performance, js_name = now)]+ fn performance_now() -> f64;+}++/// Stable, payload-free error categories produced by the OPFS adapter.+#[derive(Clone, Copy, Debug, PartialEq, Eq)]+pub enum OpfsErrorKind {+ /// The database filename is not an approved direct OPFS child name.+ InvalidName,+ /// Acquiring, validating, or releasing the canonical database Web Lock failed.+ Lock,+ /// The caller does not own the worker-local adapter.+ Ownership,+ /// A stale session, handle, or one-use close token was used.+ Lifecycle,+ /// A callback attempted to enter OPFS while another operation was active.+ Reentrant,+ /// Turso, I/O, or file references still exist at close time.+ ActiveReferences,+ /// Opening, connecting, or gracefully closing Turso failed.+ Turso,+ /// Opening or registering a sync access handle failed.+ Open,+ /// Reading an OPFS file failed.+ Read,+ /// Writing an OPFS file failed.+ Write,+ /// Flushing an OPFS file failed.+ Flush,+ /// Truncating an OPFS file failed.+ Truncate,+ /// Reading an OPFS file size failed.+ Size,+ /// Closing a sync access handle was uncertain.+ Close,+ /// Asynchronously removing a closed OPFS path failed.+ Remove,+ /// Asynchronously recreating a removed OPFS path failed.+ Recreate,+ /// Browser storage reported that its quota was full.+ StorageFull,+ /// The worker-local session is poisoned and cannot be reused.+ Poisoned,+ /// Turso requested a synchronous operation that this adapter forbids.+ Unsupported,+}++/// A payload-free OPFS adapter error.+#[derive(Clone, Debug, PartialEq, Eq)]+pub struct OpfsError {+ kind: OpfsErrorKind,+ message: String,+}++impl OpfsError {+ fn new(kind: OpfsErrorKind, message: impl Into<String>) -> Self {+ Self {+ kind,+ message: message.into(),+ }+ }++ /// Returns the stable error category.+ pub fn kind(&self) -> OpfsErrorKind {+ self.kind+ }+}++impl fmt::Display for OpfsError {+ fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {+ formatter.write_str(&self.message)+ }+}++impl std::error::Error for OpfsError {}++/// Whether a complete pre-opened main/WAL pair was fresh or existing.+#[derive(Clone, Copy, Debug, PartialEq, Eq)]+pub enum OpenDisposition {+ /// Neither path existed, or this pair was freshly recreated by reset/wipe.+ Fresh,+ /// Both approved paths already existed.+ Existing,+}++/// Result of physically pre-opening the identity-bound main/WAL pair.+#[derive(Debug)]+pub enum OpenResult {+ /// Both paths form a complete pair and may be connected to Turso.+ Ready(OpfsSession),+ /// Exactly one path pre-existed; only physical reset is permitted.+ ResetRequired(ResetRequiredSession),+}++/// Exclusive canonical-database ownership backed by a held Web Lock.+#[derive(Debug)]+pub struct OpfsOwner {+ id: OwnerId,+ paths: Paths,+ lock_name: String,+ fresh: bool,+ armed: bool,+}++impl OpfsOwner {+ /// Acquires and holds this canonical database identity's exclusive Web Lock.+ ///+ /// The single validated identity derives both the physical main/WAL names+ /// and the Web Lock name, so the same files cannot be opened under a+ /// different lock. [`Self::open`] accepts no alternate path. The lock is+ /// held across open, Turso use, close, preserve/reset, and idle ownership.+ pub async fn acquire(database_identity: &str) -> Result<Self, OpfsError> {+ let paths = approved_paths(database_identity)?;+ let lock_name = owner_lock_name(database_identity);+ let id = acquire_database_lock(database_identity, &lock_name).await?;+ Ok(Self {+ id,+ paths,+ lock_name,+ fresh: false,+ armed: true,+ })+ }++ /// Returns the canonical database identity bound into this owner.+ pub fn database_path(&self) -> &str {+ self.paths.get(FileRole::Main)+ }++ /// Returns the exact exclusive Web Lock name held by this owner.+ pub fn lock_name(&self) -> &str {+ &self.lock_name+ }++ /// Physically wipes and recreates both approved paths before any open.+ ///+ /// This is the recovery path after abrupt worker loss or a pre-open entry+ /// conflict. It recursively removes only the two direct, validated child+ /// names. Cancellation or any partial remove/recreate failure poisons the+ /// owner; a poisoned worker must be replaced.+ pub async fn recovery_wipe(mut self) -> Result<Self, WipeFailure> {+ REGISTRY+ .with(|registry| {+ registry+ .borrow_mut()+ .machine+ .start_wipe(self.id, self.paths.clone())+ })+ .map_err(state_error)+ .map_err(WipeFailure::new)?;+ self.armed = false;+ let mut guard = AsyncPoisonGuard::new(+ self.id,+ "recovery wipe cancelled or failed after entering Wiping",+ );+ reset_paths(&self.paths, true)+ .await+ .map_err(WipeFailure::new)?;+ REGISTRY+ .with(|registry| registry.borrow_mut().machine.finish_wipe(self.id))+ .map_err(state_error)+ .map_err(WipeFailure::new)?;+ guard.disarm();+ self.fresh = true;+ self.armed = true;+ Ok(self)+ }++ /// Pre-opens exactly this owner's bound main and WAL paths.+ ///+ /// A one-sided pre-existing pair returns [`OpenResult::ResetRequired`], a+ /// type that exposes no Turso I/O and can only be physically reset.+ pub async fn open(mut self) -> Result<OpenResult, OpenFailure> {+ let paths = self.paths.clone();+ let session = match REGISTRY.with(|registry| {+ registry+ .borrow_mut()+ .machine+ .start_open(self.id, paths.clone())+ }) {+ Ok(session) => session,+ Err(error) => return Err(open_failure_after_cleanup(state_error(error), self)),+ };++ let root = match worker_root().await {+ Ok(root) => root,+ Err(error) => {+ let adapter_error = js_error(OpfsErrorKind::Open, "OPFS root open", &error);+ cleanup_failed_open(self.id, session, &adapter_error);+ return Err(open_failure_after_cleanup(adapter_error, self));+ }+ };++ let mut created = [false; 2];+ for role in FileRole::ALL {+ #[cfg(test)]+ if take_open_failure(role) {+ let error = OpfsError::new(OpfsErrorKind::Open, "injected OPFS pre-open failure");+ cleanup_failed_open(self.id, session, &error);+ return Err(open_failure_after_cleanup(error, self));+ }++ let (handle, was_created) = match open_sync_handle(&root, paths.get(role)).await {+ Ok(value) => value,+ Err(error) => {+ let adapter_error =+ js_error(OpfsErrorKind::Open, "OPFS sync handle open", &error);+ cleanup_failed_open(self.id, session, &adapter_error);+ return Err(open_failure_after_cleanup(adapter_error, self));+ }+ };+ created[role.index()] = was_created;++ let handle_id = match REGISTRY.with(|registry| {+ registry+ .borrow_mut()+ .machine+ .register(self.id, session, role)+ }) {+ Ok(handle_id) => handle_id,+ Err(error) => {+ let adapter_error = state_error(error);+ let current_closed = close_sync_handle(&handle).is_ok();+ cleanup_failed_open(self.id, session, &adapter_error);+ if !current_closed {+ poison(self.id, "unregistered sync handle close was uncertain");+ }+ return Err(open_failure_after_cleanup(adapter_error, self));+ }+ };+ REGISTRY.with(|registry| {+ registry+ .borrow_mut()+ .handles+ .insert(handle_id, RegisteredHandle { role, handle });+ });+ }++ let reset_only = created[0] != created[1];+ if let Err(error) = REGISTRY.with(|registry| {+ registry+ .borrow_mut()+ .machine+ .activate(self.id, session, reset_only)+ }) {+ let adapter_error = state_error(error);+ cleanup_failed_open(self.id, session, &adapter_error);+ return Err(open_failure_after_cleanup(adapter_error, self));+ }++ let disposition = if self.fresh || created == [true, true] {+ OpenDisposition::Fresh+ } else {+ OpenDisposition::Existing+ };+ self.armed = false;+ if reset_only {+ return Ok(OpenResult::ResetRequired(ResetRequiredSession {+ owner: self.id,+ session,+ paths,+ armed: true,+ }));+ }++ let references = Arc::new(SessionReferences);+ let io = Arc::new(OpfsIo {+ owner: self.id,+ session,+ references: references.clone(),+ last_monotonic_nanos: AtomicU64::new(0),+ });+ Ok(OpenResult::Ready(OpfsSession {+ owner: self.id,+ session,+ paths,+ disposition,+ io,+ references,+ armed: true,+ }))+ }++ /// Releases the idle owner and then proves its physical Web Lock request+ /// completed. Cancellation after release begins poisons the registry.+ pub async fn release(mut self) -> Result<(), OpfsError> {+ self.armed = false;+ let mut guard = AsyncPoisonGuard::new(+ self.id,+ "owner lock release cancelled before completion proof",+ );+ release_database_lock(self.id).await?;+ REGISTRY+ .with(|registry| registry.borrow_mut().machine.release_owner(self.id))+ .map_err(state_error)?;+ guard.disarm();+ Ok(())+ }+}++impl Drop for OpfsOwner {+ fn drop(&mut self) {+ if self.armed {+ poison(self.id, "armed OPFS owner dropped without explicit release");+ begin_database_lock_release(self.id);+ }+ }+}++/// A failure while asynchronously pre-opening main and WAL.+#[derive(Debug)]+pub struct OpenFailure {+ error: OpfsError,+ owner: Option<OpfsOwner>,+}++impl OpenFailure {+ fn recoverable(error: OpfsError, owner: OpfsOwner) -> Self {+ Self {+ error,+ owner: Some(owner),+ }+ }++ fn poisoned(error: OpfsError) -> Self {+ Self { error, owner: None }+ }++ /// Returns the classified adapter error.+ pub fn error(&self) -> &OpfsError {+ &self.error+ }++ /// Returns the idle owner only when partial-open cleanup was certain.+ pub fn into_owner(mut self) -> Option<OpfsOwner> {+ self.owner.take()+ }+}++impl fmt::Display for OpenFailure {+ fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {+ self.error.fmt(formatter)+ }+}++impl std::error::Error for OpenFailure {}++/// A complete, identity-bound main/WAL session not yet connected to Turso.+#[derive(Debug)]+pub struct OpfsSession {+ owner: OwnerId,+ session: SessionId,+ paths: Paths,+ disposition: OpenDisposition,+ io: Arc<OpfsIo>,+ references: Arc<SessionReferences>,+ armed: bool,+}++impl OpfsSession {+ /// Returns the approved main database filename.+ pub fn database_path(&self) -> &str {+ self.paths.get(FileRole::Main)+ }++ /// Returns the approved WAL filename.+ pub fn wal_path(&self) -> &str {+ self.paths.get(FileRole::Wal)+ }++ /// Reports whether this complete pair was fresh or existing.+ pub fn disposition(&self) -> OpenDisposition {+ self.disposition+ }++ /// Opens exactly one production Turso database and connection bound to+ /// this session's private I/O object.+ ///+ /// The adapter constructs the approved `SqliteDialect` and default Turso+ /// options internally. Neither raw options, the database, nor raw I/O is+ /// exposed. Any Turso open/storage/connect failure poisons the session;+ /// recovery requires worker replacement and a new owner recovery wipe.+ pub fn connect(mut self) -> Result<ConnectedOpfsSession, ConnectFailure> {+ let options = OpenOptions::new(Arc::new(SqliteDialect));+ let database =+ match open_turso_database(self.io.clone(), self.paths.get(FileRole::Main), options) {+ Ok(database) => database,+ Err(error) => {+ self.armed = false;+ poison(+ self.owner,+ "Turso open/storage failure made session health uncertain",+ );+ return Err(ConnectFailure::poisoned(turso_error("open", error)));+ }+ };+ let connection = match connect_turso_database(&database) {+ Ok(connection) => connection,+ Err(error) => {+ drop(database);+ self.armed = false;+ poison(+ self.owner,+ "Turso connection failure made session health uncertain",+ );+ return Err(ConnectFailure::poisoned(turso_error("connect", error)));+ }+ };+ if let Err(error) = REGISTRY.with(|registry| {+ registry+ .borrow_mut()+ .machine+ .bind_connection(self.owner, self.session)+ }) {+ let _ = connection.close();+ drop(connection);+ drop(database);+ self.armed = false;+ poison(+ self.owner,+ "connection binding did not match the OPFS session",+ );+ return Err(ConnectFailure::poisoned(state_error(error)));+ }+ self.armed = false;+ Ok(ConnectedOpfsSession {+ owner: self.owner,+ session: self.session,+ paths: self.paths.clone(),+ disposition: self.disposition,+ io: self.io.clone(),+ references: self.references.clone(),+ database: Some(database),+ connection: Some(connection),+ armed: true,+ })+ }+}++impl Drop for OpfsSession {+ fn drop(&mut self) {+ if self.armed {+ poison(+ self.owner,+ "ready OPFS session dropped without creating and closing its Turso connection",+ );+ }+ }+}++/// Failure while creating the session's sole production Turso connection.+#[derive(Debug)]+pub struct ConnectFailure {+ error: OpfsError,+}++impl ConnectFailure {+ fn poisoned(error: OpfsError) -> Self {+ Self { error }+ }++ /// Returns the classified adapter error.+ pub fn error(&self) -> &OpfsError {+ &self.error+ }+}++impl fmt::Display for ConnectFailure {+ fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {+ self.error.fmt(formatter)+ }+}++impl std::error::Error for ConnectFailure {}++/// Session owning the sole production Turso database and connection.+pub struct ConnectedOpfsSession {+ owner: OwnerId,+ session: SessionId,+ paths: Paths,+ disposition: OpenDisposition,+ io: Arc<OpfsIo>,+ references: Arc<SessionReferences>,+ database: Option<Arc<Database>>,+ connection: Option<Arc<Connection>>,+ armed: bool,+}++impl fmt::Debug for ConnectedOpfsSession {+ fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {+ formatter+ .debug_struct("ConnectedOpfsSession")+ .field("owner", &self.owner)+ .field("session", &self.session)+ .field("paths", &self.paths)+ .field("disposition", &self.disposition)+ .field("armed", &self.armed)+ .finish_non_exhaustive()+ }+}++impl ConnectedOpfsSession {+ /// Returns the approved main database filename.+ pub fn database_path(&self) -> &str {+ self.paths.get(FileRole::Main)+ }++ /// Returns whether this complete pair was fresh or existing.+ pub fn disposition(&self) -> OpenDisposition {+ self.disposition+ }++ /// Clones the sole production connection for application use.+ ///+ /// Callers must never invoke `Connection::close` directly. All clones and+ /// statements must be dropped before [`Self::try_close`], which exclusively+ /// owns the close transition and its success proof.+ pub fn connection(&self) -> Arc<Connection> {+ self.connection+ .as_ref()+ .expect("armed connected session always owns its connection")+ .clone()+ }++ /// Consumes the session, calls its bound `Connection::close`, verifies the+ /// close succeeded, drops Turso ownership, proves no Database/IO/File+ /// references remain, and only then closes the JavaScript handles.+ pub fn try_close(mut self) -> Result<ClosedSession, CloseFailure> {+ let connection = self+ .connection+ .as_ref()+ .expect("armed connected session always owns its connection");+ if connection.is_closed() {+ self.armed = false;+ poison(+ self.owner,+ "bound Turso connection was closed outside the adapter transition",+ );+ return Err(CloseFailure::poisoned(OpfsError::new(+ OpfsErrorKind::Turso,+ "bound Turso connection was already closed; session poisoned",+ )));+ }+ if Arc::strong_count(connection) != 1 {+ return Err(CloseFailure::recoverable(+ OpfsError::new(+ OpfsErrorKind::ActiveReferences,+ "connection clones or statements remain before graceful close",+ ),+ self,+ ));+ }++ if let Err(error) = close_turso_connection(connection) {+ self.armed = false;+ poison(self.owner, "session-bound Turso Connection::close failed");+ return Err(CloseFailure::poisoned(turso_error("close", error)));+ }+ if let Err(error) = REGISTRY.with(|registry| {+ registry+ .borrow_mut()+ .machine+ .record_connection_close(self.owner, self.session)+ }) {+ self.armed = false;+ poison(+ self.owner,+ "Turso close proof did not match the OPFS session",+ );+ return Err(CloseFailure::poisoned(state_error(error)));+ }++ drop(self.connection.take());+ drop(self.database.take());+ if Arc::strong_count(&self.io) != 1 || Arc::strong_count(&self.references) != 2 {+ self.armed = false;+ poison(+ self.owner,+ "Turso close succeeded but Database/IO/File references remained",+ );+ return Err(CloseFailure::poisoned(OpfsError::new(+ OpfsErrorKind::ActiveReferences,+ "references remained after the session-bound Turso close",+ )));+ }++ self.armed = false;+ close_session_handles(self.owner, self.session, false).map_err(CloseFailure::poisoned)+ }+}++impl Drop for ConnectedOpfsSession {+ fn drop(&mut self) {+ if self.armed {+ poison(+ self.owner,+ "connected OPFS session dropped without adapter-driven Turso close",+ );+ }+ }+}++/// A one-sided main/WAL pair that can only be physically reset.+#[derive(Debug)]+pub struct ResetRequiredSession {+ owner: OwnerId,+ session: SessionId,+ paths: Paths,+ armed: bool,+}++impl ResetRequiredSession {+ /// Returns the approved main database filename requiring reset.+ pub fn database_path(&self) -> &str {+ self.paths.get(FileRole::Main)+ }++ /// Closes the unexposed handles, deletes/recreates both paths, and returns+ /// the still-locked idle owner. No raw I/O or Turso connection is exposed.+ pub async fn reset(mut self) -> Result<OpfsOwner, ResetFailure> {+ self.armed = false;+ let closed =+ close_session_handles(self.owner, self.session, true).map_err(ResetFailure::new)?;+ closed.reset().await+ }+}++impl Drop for ResetRequiredSession {+ fn drop(&mut self) {+ if self.armed {+ poison(+ self.owner,+ "reset-only incomplete pair dropped without physical reset",+ );+ }+ }+}++/// Failure while proving connection ownership or closing Turso/OPFS.+#[derive(Debug)]+pub struct CloseFailure {+ error: OpfsError,+ session: Option<ConnectedOpfsSession>,+}++impl CloseFailure {+ fn recoverable(error: OpfsError, session: ConnectedOpfsSession) -> Self {+ Self {+ error,+ session: Some(session),+ }+ }++ fn poisoned(error: OpfsError) -> Self {+ Self {+ error,+ session: None,+ }+ }++ /// Returns the classified adapter error.+ pub fn error(&self) -> &OpfsError {+ &self.error+ }++ /// Returns the connected session only before `Connection::close` ran.+ pub fn into_session(mut self) -> Option<ConnectedOpfsSession> {+ self.session.take()+ }+}++impl fmt::Display for CloseFailure {+ fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {+ self.error.fmt(formatter)+ }+}++impl std::error::Error for CloseFailure {}++/// A one-use token proving Turso resources and JavaScript handles are closed.+#[derive(Debug)]+pub struct ClosedSession {+ owner: OwnerId,+ token: CloseToken,+ armed: bool,+}++impl ClosedSession {+ /// Consumes this token without deleting files and returns an idle owner.+ pub fn preserve(mut self) -> Result<OpfsOwner, OpfsError> {+ let binding = owner_binding(self.owner)?;+ let result = REGISTRY.with(|registry| {+ registry+ .borrow_mut()+ .machine+ .preserve(self.owner, self.token)+ });+ // An invalid token is consumed without a Drop-side state mutation; the+ // checked transition itself is the sole operation and is mutation-free.+ self.armed = false;+ result.map_err(state_error)?;+ Ok(binding.into_owner(self.owner, false))+ }++ /// Consumes this token, asynchronously deletes and recreates main and WAL,+ /// and returns an idle owner that marks the next matching open as fresh.+ ///+ /// Synchronous [`IO::remove_file`] is never used. Any removal, recreation,+ /// or unexpected-state failure poisons the worker-local session.+ pub async fn reset(mut self) -> Result<OpfsOwner, ResetFailure> {+ let binding = owner_binding(self.owner).map_err(ResetFailure::new)?;+ let start = REGISTRY.with(|registry| {+ registry+ .borrow_mut()+ .machine+ .start_reset(self.owner, self.token)+ });+ // As with preserve, invalid/consumed tokens are rejected without a+ // Drop-side transition or mutation of the checked state.+ self.armed = false;+ let paths = start.map_err(state_error).map_err(ResetFailure::new)?;+ let mut guard = AsyncPoisonGuard::new(+ self.owner,+ "reset cancelled or failed after entering Resetting",+ );++ reset_paths(&paths, false)+ .await+ .map_err(ResetFailure::new)?;+ REGISTRY+ .with(|registry| {+ registry+ .borrow_mut()+ .machine+ .finish_reset(self.owner, self.token)+ })+ .map_err(state_error)+ .map_err(ResetFailure::new)?;+ guard.disarm();+ Ok(binding.into_owner(self.owner, true))+ }+}++impl Drop for ClosedSession {+ fn drop(&mut self) {+ if self.armed {+ poison(+ self.owner,+ "closed-session token dropped without preserve or reset",+ );+ }+ }+}++/// A reset failure; the worker-local session is poisoned and not reusable.+#[derive(Clone, Debug)]+pub struct ResetFailure {+ error: OpfsError,+}++impl ResetFailure {+ fn new(error: OpfsError) -> Self {+ Self { error }+ }++ /// Returns the classified adapter error.+ pub fn error(&self) -> &OpfsError {+ &self.error+ }+}++impl fmt::Display for ResetFailure {+ fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {+ self.error.fmt(formatter)+ }+}++impl std::error::Error for ResetFailure {}++/// A recovery-wipe failure; the worker-local owner is poisoned.+#[derive(Clone, Debug)]+pub struct WipeFailure {+ error: OpfsError,+}++impl WipeFailure {+ fn new(error: OpfsError) -> Self {+ Self { error }+ }++ /// Returns the classified adapter error.+ pub fn error(&self) -> &OpfsError {+ &self.error+ }+}++impl fmt::Display for WipeFailure {+ fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {+ self.error.fmt(formatter)+ }+}++impl std::error::Error for WipeFailure {}++#[derive(Debug)]+struct AsyncPoisonGuard {+ owner: OwnerId,+ reason: &'static str,+ armed: bool,+}++impl AsyncPoisonGuard {+ fn new(owner: OwnerId, reason: &'static str) -> Self {+ Self {+ owner,+ reason,+ armed: true,+ }+ }++ fn disarm(&mut self) {+ self.armed = false;+ }+}++impl Drop for AsyncPoisonGuard {+ fn drop(&mut self) {+ if self.armed {+ poison(self.owner, self.reason);+ }+ }+}++#[derive(Debug)]+struct SessionReferences;++struct RegisteredHandle {+ role: FileRole,+ handle: FileSystemSyncAccessHandle,+}++#[derive(Clone, Debug)]+struct OwnerBinding {+ paths: Paths,+ lock_name: String,+}++impl OwnerBinding {+ fn into_owner(self, id: OwnerId, fresh: bool) -> OpfsOwner {+ OpfsOwner {+ id,+ paths: self.paths,+ lock_name: self.lock_name,+ fresh,+ armed: true,+ }+ }+}++// Each Function comes from Closure::into_js_value: JavaScript owns the Rust+// closure allocation. Registry clones intentionally keep grant/settlement+// callbacks reachable until the outer Web Lock request has actually settled.+struct LockCallbacks {+ _grant: Function,+ _fulfilled: Function,+ _rejected: Function,+}++struct RegisteredOwnerLock {+ owner: OwnerId,+ binding: OwnerBinding,+ release: Function,+ request: Option<Promise>,+ callbacks: Option<LockCallbacks>,+}++struct PendingOwnerLock {+ lock_name: String,+ controller: AbortController,+ request: Option<Promise>,+ callbacks: LockCallbacks,+ cancelled: bool,+}++#[derive(Default)]+struct Registry {+ machine: Machine,+ handles: HashMap<HandleId, RegisteredHandle>,+ owner_lock: Option<RegisteredOwnerLock>,+ pending_lock: Option<PendingOwnerLock>,+ #[cfg(test)]+ faults: TestFaults,+}++#[cfg(test)]+#[derive(Clone, Copy, Debug, PartialEq, Eq)]+enum ResetFault {+ AfterMainRemoval,+ AfterMainRecreate,+}++#[cfg(test)]+#[derive(Default)]+struct TestFaults {+ fail_open: Option<FileRole>,+ fail_close: Option<FileRole>,+ database_open_error: Option<CompletionError>,+ database_connect_error: Option<CompletionError>,+ fail_connection_close: bool,+ connection_close_calls: usize,+ reset_fault: Option<ResetFault>,+ max_write_chunk: Option<usize>,+ next_write_error: Option<CompletionError>,+ write_error_after_chunks: Option<(usize, CompletionError)>,+}++thread_local! {+ // The sole long-lived owner of JavaScript OPFS objects. It is never placed+ // in Arc/Mutex and never enters a Turso Send + Sync trait object.+ static REGISTRY: RefCell<Registry> = RefCell::new(Registry::default());+}++#[derive(Debug)]+struct OpfsIo {+ owner: OwnerId,+ session: SessionId,+ references: Arc<SessionReferences>,+ last_monotonic_nanos: AtomicU64,+}++#[derive(Debug)]+struct OpfsFile {+ owner: OwnerId,+ session: SessionId,+ handle: HandleId,+ _references: Arc<SessionReferences>,+}++impl Clock for OpfsIo {+ fn current_time_monotonic(&self) -> MonotonicInstant {+ let observed = (performance_now().max(0.0) * 1_000_000.0) as u64;+ let mut previous = self.last_monotonic_nanos.load(Ordering::Relaxed);+ loop {+ let next = observed.max(previous.saturating_add(1));+ match self.last_monotonic_nanos.compare_exchange_weak(+ previous,+ next,+ Ordering::Relaxed,+ Ordering::Relaxed,+ ) {+ Ok(_) => return MonotonicInstant::from_nanos(next as u128),+ Err(current) => previous = current,+ }+ }+ }++ fn current_time_wall_clock(&self) -> WallClockInstant {+ let millis = js_sys::Date::now();+ let seconds = (millis / 1_000.0).floor() as i64;+ let micros = ((millis - seconds as f64 * 1_000.0) * 1_000.0) as u32;+ WallClockInstant {+ secs: seconds,+ micros,+ }+ }+}++impl IO for OpfsIo {+ fn open_file(+ &self,+ path: &str,+ flags: OpenFlags,+ direct: bool,+ ) -> turso_core::Result<Arc<dyn File>> {+ let _operation = OperationGuard::enter(self.owner, self.session)?;+ let handle = REGISTRY.with(|registry| {+ registry.borrow().machine.validate_open(+ self.owner,+ self.session,+ path,+ flags.contains(OpenFlags::ReadOnly),+ flags.contains(OpenFlags::NoLock),+ direct,+ )+ })?;+ Ok(Arc::new(OpfsFile {+ owner: self.owner,+ session: self.session,+ handle,+ _references: self.references.clone(),+ }))+ }++ fn remove_file(&self, _path: &str) -> turso_core::Result<()> {+ let _operation = OperationGuard::enter(self.owner, self.session)?;+ Err(completion_io_error(+ ErrorKind::Unsupported,+ "synchronous OPFS remove_file is forbidden",+ ))+ }++ fn file_id(&self, path: &str) -> turso_core::Result<FileId> {+ let _operation = OperationGuard::enter(self.owner, self.session)?;+ REGISTRY.with(|registry| {+ registry+ .borrow()+ .machine+ .validate_path(self.owner, self.session, path)+ })?;+ Ok(FileId::from_path_hash(path))+ }++ fn supports_shared_wal_coordination(&self) -> bool {+ false+ }+}++impl File for OpfsFile {+ fn lock_file(&self, _exclusive: bool) -> turso_core::Result<()> {+ let _operation = OperationGuard::enter(self.owner, self.session)?;+ registered_handle(self.owner, self.session, self.handle).map(|_| ())+ }++ fn unlock_file(&self) -> turso_core::Result<()> {+ let _operation = OperationGuard::enter(self.owner, self.session)?;+ registered_handle(self.owner, self.session, self.handle).map(|_| ())+ }++ fn pread(&self, pos: u64, completion: Completion) -> turso_core::Result<Completion> {+ let _operation = OperationGuard::enter(self.owner, self.session)?;+ let result = read_once(+ self.owner,+ self.session,+ self.handle,+ pos,+ completion.as_read().buf(),+ );+ finish_completion(&completion, result);+ Ok(completion)+ }++ fn pwrite(+ &self,+ pos: u64,+ buffer: Arc<Buffer>,+ completion: Completion,+ ) -> turso_core::Result<Completion> {+ let _operation = OperationGuard::enter(self.owner, self.session)?;+ completion.keep_write_buffer_alive(buffer.clone());+ let result = preflight_write_range(pos, [buffer.as_slice().len()])+ .and_then(|expected| {+ write_all(+ pos,+ buffer.as_slice(),+ self.owner,+ self.session,+ self.handle,+ )+ .and_then(|written| {+ if written == expected {+ completion_count(written)+ } else {+ Err(CompletionError::ShortWrite)+ }+ })+ })+ .map_err(LimboError::CompletionError);+ finish_completion(&completion, result);+ Ok(completion)+ }++ fn pwritev(+ &self,+ mut pos: u64,+ buffers: Vec<Arc<Buffer>>,+ completion: Completion,+ ) -> turso_core::Result<Completion> {+ let _operation = OperationGuard::enter(self.owner, self.session)?;+ // All browser writes are synchronous, so the argument vector keeps+ // every buffer alive until all writes finish and completion fires.+ // Aggregate count and end offset are checked before the first write.+ let result = (|| {+ let expected =+ preflight_write_range(pos, buffers.iter().map(|buffer| buffer.as_slice().len()))?;+ let mut total = 0_usize;+ for buffer in &buffers {+ let written = write_all(+ pos,+ buffer.as_slice(),+ self.owner,+ self.session,+ self.handle,+ )?;+ total = total+ .checked_add(written)+ .ok_or(CompletionError::ShortWrite)?;+ pos = pos+ .checked_add(written as u64)+ .ok_or(CompletionError::ShortWrite)?;+ }+ if total == expected {+ completion_count(total)+ } else {+ Err(CompletionError::ShortWrite)+ }+ })()+ .map_err(LimboError::CompletionError);+ finish_completion(&completion, result);+ Ok(completion)+ }++ fn sync(+ &self,+ completion: Completion,+ _sync_type: FileSyncType,+ ) -> turso_core::Result<Completion> {+ let _operation = OperationGuard::enter(self.owner, self.session)?;+ let result = registered_handle(self.owner, self.session, self.handle).and_then(|handle| {+ handle.flush().map_err(|error| {+ js_handle_completion_error(self.owner, "OPFS flush", &error, ErrorKind::Other)+ })?;+ Ok(0)+ });+ finish_completion(&completion, result);+ Ok(completion)+ }++ fn size(&self) -> turso_core::Result<u64> {+ let _operation = OperationGuard::enter(self.owner, self.session)?;+ registered_handle(self.owner, self.session, self.handle).and_then(|handle| {+ handle+ .get_size()+ .map_err(|error| {+ js_handle_limbo_error(self.owner, "OPFS getSize", &error, ErrorKind::Other)+ })+ .and_then(number_to_u64)+ })+ }++ fn truncate(&self, len: u64, completion: Completion) -> turso_core::Result<Completion> {+ let _operation = OperationGuard::enter(self.owner, self.session)?;+ let result = validate_position(len).and_then(|()| {+ let handle = registered_handle(self.owner, self.session, self.handle)?;+ handle.truncate_with_f64(len as f64).map_err(|error| {+ js_handle_limbo_error(self.owner, "OPFS truncate", &error, ErrorKind::Other)+ })?;+ Ok(0)+ });+ finish_completion(&completion, result);+ Ok(completion)+ }+}++#[derive(Debug)]+struct OperationGuard {+ owner: OwnerId,+ session: SessionId,+}++impl OperationGuard {+ fn enter(owner: OwnerId, session: SessionId) -> turso_core::Result<Self> {+ REGISTRY.with(|registry| {+ registry+ .borrow_mut()+ .machine+ .begin_operation(owner, session)+ })?;+ Ok(Self { owner, session })+ }+}++impl Drop for OperationGuard {+ fn drop(&mut self) {+ REGISTRY.with(|registry| {+ registry+ .borrow_mut()+ .machine+ .end_operation(self.owner, self.session);+ });+ }+}++fn approved_paths(database_name: &str) -> Result<Paths, OpfsError> {+ if database_name.is_empty()+ || database_name == "."+ || database_name == ".."+ || database_name.ends_with("-wal")+ || database_name.contains(['/', '\\', '\0'])+ {+ return Err(OpfsError::new(+ OpfsErrorKind::InvalidName,+ "database identity must be a direct child and must not use the reserved -wal suffix",+ ));+ }+ let wal = format!("{database_name}-wal");+ Ok(Paths::new(database_name.to_owned(), wal))+}++fn owner_lock_name(database_identity: &str) -> String {+ format!(+ "macro:turso-opfs:v1:{}:{database_identity}",+ database_identity.len()+ )+}++#[derive(Debug)]+struct PendingAcquireGuard {+ lock_name: String,+ armed: bool,+}++impl PendingAcquireGuard {+ fn disarm(&mut self) {+ self.armed = false;+ }+}++impl Drop for PendingAcquireGuard {+ fn drop(&mut self) {+ if self.armed {+ cancel_database_lock_acquire(&self.lock_name);+ }+ }+}++async fn acquire_database_lock(+ database_identity: &str,+ lock_name: &str,+) -> Result<OwnerId, OpfsError> {+ let worker = js_sys::global()+ .dyn_into::<DedicatedWorkerGlobalScope>()+ .map_err(|error| js_error(OpfsErrorKind::Lock, "DedicatedWorker lock scope", &error))?;+ let manager = Reflect::get(worker.navigator().as_ref(), &JsValue::from_str("locks"))+ .map_err(|error| js_error(OpfsErrorKind::Lock, "Web Lock manager", &error))?;+ if manager.is_null() || manager.is_undefined() {+ return Err(OpfsError::new(+ OpfsErrorKind::Lock,+ "Web Locks API is unavailable in this DedicatedWorker",+ ));+ }+ let request_function = Reflect::get(&manager, &JsValue::from_str("request"))+ .and_then(|value| value.dyn_into::<Function>())+ .map_err(|error| js_error(OpfsErrorKind::Lock, "Web Lock request function", &error))?;+ let occupied = REGISTRY.with(|registry| {+ let registry = registry.borrow();+ registry.pending_lock.is_some() || registry.owner_lock.is_some()+ });+ if occupied {+ return Err(OpfsError::new(+ OpfsErrorKind::Ownership,+ "worker-local OPFS registry already owns or is acquiring a Web Lock",+ ));+ }++ let controller = AbortController::new()+ .map_err(|error| js_error(OpfsErrorKind::Lock, "Web Lock abort controller", &error))?;+ let options = Object::new();+ Reflect::set(+ options.as_ref(),+ &JsValue::from_str("mode"),+ &JsValue::from_str("exclusive"),+ )+ .map_err(|error| js_error(OpfsErrorKind::Lock, "Web Lock mode", &error))?;+ Reflect::set(+ options.as_ref(),+ &JsValue::from_str("signal"),+ controller.signal().as_ref(),+ )+ .map_err(|error| js_error(OpfsErrorKind::Lock, "Web Lock abort signal", &error))?;++ let mut acquired_resolve = None;+ let mut acquired_reject = None;+ let acquired = Promise::new(&mut |resolve, reject| {+ acquired_resolve = Some(resolve.clone());+ acquired_reject = Some(reject.clone());+ });+ let resolve = acquired_resolve.expect("Promise constructor supplies resolve");+ let reject = acquired_reject.expect("Promise constructor supplies reject");+ let callback_reject = reject.clone();+ let callback_resolve = resolve.clone();+ let callback_lock_name = lock_name.to_owned();+ let binding = OwnerBinding {+ paths: approved_paths(database_identity)?,+ lock_name: lock_name.to_owned(),+ };+ let grant = Closure::wrap(Box::new(move |lock: JsValue| -> Promise {+ if lock.is_null() || lock.is_undefined() {+ let _ = callback_reject.call1(+ &JsValue::UNDEFINED,+ &JsValue::from_str("exclusive Web Lock was not granted"),+ );+ return Promise::resolve(&JsValue::UNDEFINED);+ }+ let actual_name = Reflect::get(&lock, &JsValue::from_str("name"))+ .ok()+ .and_then(|value| value.as_string());+ let actual_mode = Reflect::get(&lock, &JsValue::from_str("mode"))+ .ok()+ .and_then(|value| value.as_string());+ if actual_name.as_deref() != Some(callback_lock_name.as_str())+ || actual_mode.as_deref() != Some("exclusive")+ {+ let _ = callback_reject.call1(+ &JsValue::UNDEFINED,+ &JsValue::from_str("granted Web Lock did not match canonical identity"),+ );+ return Promise::resolve(&JsValue::UNDEFINED);+ }++ let mut release_resolve = None;+ let held = Promise::new(&mut |resolve, _reject| {+ release_resolve = Some(resolve.clone());+ });+ let release = release_resolve.expect("Promise constructor supplies resolve");+ let claimed = REGISTRY.with(|registry| {+ let mut registry = registry.borrow_mut();+ if registry+ .pending_lock+ .as_ref()+ .is_none_or(|pending| pending.lock_name != callback_lock_name)+ || registry.owner_lock.is_some()+ {+ return Err(OpfsError::new(+ OpfsErrorKind::Ownership,+ "Web Lock callback did not match the pending acquisition",+ ));+ }+ let owner = registry.machine.claim_owner().map_err(state_error)?;+ registry.owner_lock = Some(RegisteredOwnerLock {+ owner,+ binding: binding.clone(),+ release,+ request: None,+ callbacks: None,+ });+ Ok(owner)+ });+ match claimed {+ Ok(_) => {+ let _ = callback_resolve.call1(&JsValue::UNDEFINED, &JsValue::TRUE);+ held+ }+ Err(error) => {+ let _ = callback_reject+ .call1(&JsValue::UNDEFINED, &JsValue::from_str(&error.to_string()));+ Promise::resolve(&JsValue::UNDEFINED)+ }+ }+ }) as Box<dyn FnMut(JsValue) -> Promise>)+ .into_js_value()+ .unchecked_into::<Function>();++ let fulfilled_lock_name = lock_name.to_owned();+ let fulfilled = Closure::wrap(Box::new(move |_value: JsValue| -> JsValue {+ REGISTRY.with(|registry| {+ let mut registry = registry.borrow_mut();+ let cancelled = registry.pending_lock.as_ref().is_some_and(|pending| {+ pending.lock_name == fulfilled_lock_name && pending.cancelled+ });+ if cancelled {+ registry.pending_lock = None;+ if registry.owner_lock.as_ref().is_some_and(|lock| {+ lock.binding.lock_name == fulfilled_lock_name && lock.callbacks.is_none()+ }) {+ registry.owner_lock = None;+ }+ }+ });+ JsValue::UNDEFINED+ }) as Box<dyn FnMut(JsValue) -> JsValue>)+ .into_js_value()+ .unchecked_into::<Function>();++ let rejected_lock_name = lock_name.to_owned();+ let request_reject = reject.clone();+ let rejected = Closure::wrap(Box::new(move |error: JsValue| -> JsValue {+ let _ = request_reject.call1(&JsValue::UNDEFINED, &error);+ let owner = REGISTRY.with(|registry| {+ let mut registry = registry.borrow_mut();+ if registry+ .pending_lock+ .as_ref()+ .is_some_and(|pending| pending.lock_name == rejected_lock_name)+ {+ registry.pending_lock = None;+ }+ if registry+ .owner_lock+ .as_ref()+ .is_some_and(|lock| lock.binding.lock_name == rejected_lock_name)+ {+ registry.owner_lock.take().map(|lock| lock.owner)+ } else {+ None+ }+ });+ if let Some(owner) = owner {+ poison(owner, "held Web Lock request rejected before clean release");+ }+ JsValue::UNDEFINED+ }) as Box<dyn FnMut(JsValue) -> JsValue>)+ .into_js_value()+ .unchecked_into::<Function>();++ let callbacks = LockCallbacks {+ _grant: grant.clone(),+ _fulfilled: fulfilled.clone(),+ _rejected: rejected.clone(),+ };+ REGISTRY.with(|registry| {+ registry.borrow_mut().pending_lock = Some(PendingOwnerLock {+ lock_name: lock_name.to_owned(),+ controller,+ request: None,+ callbacks,+ cancelled: false,+ });+ });+ let mut guard = PendingAcquireGuard {+ lock_name: lock_name.to_owned(),+ armed: true,+ };++ let request = match request_function+ .call3(+ &manager,+ &JsValue::from_str(lock_name),+ options.as_ref(),+ grant.as_ref(),+ )+ .and_then(|value| value.dyn_into::<Promise>())+ {+ Ok(request) => request,+ Err(error) => {+ REGISTRY.with(|registry| registry.borrow_mut().pending_lock = None);+ guard.disarm();+ return Err(js_error(OpfsErrorKind::Lock, "Web Lock request", &error));+ }+ };+ REGISTRY.with(|registry| {+ if let Some(pending) = registry.borrow_mut().pending_lock.as_mut() {+ pending.request = Some(request.clone());+ }+ });+ let then = Reflect::get(request.as_ref(), &JsValue::from_str("then"))+ .and_then(|value| value.dyn_into::<Function>())+ .and_then(|then| then.call2(request.as_ref(), fulfilled.as_ref(), rejected.as_ref()));+ if let Err(error) = then {+ cancel_database_lock_acquire(lock_name);+ let _ = JsFuture::from(request).await;+ REGISTRY.with(|registry| registry.borrow_mut().pending_lock = None);+ guard.disarm();+ return Err(js_error(+ OpfsErrorKind::Lock,+ "Web Lock settlement handlers",+ &error,+ ));+ }++ JsFuture::from(acquired)+ .await+ .map_err(|error| js_error(OpfsErrorKind::Lock, "Web Lock acquisition", &error))?;++ let owner = REGISTRY.with(|registry| {+ let mut registry = registry.borrow_mut();+ let pending = registry.pending_lock.take().ok_or_else(|| {+ OpfsError::new(+ OpfsErrorKind::Lock,+ "Web Lock acquisition lost its pending capability",+ )+ })?;+ if pending.lock_name != lock_name || pending.cancelled {+ return Err(OpfsError::new(+ OpfsErrorKind::Lock,+ "Web Lock acquisition completed for a cancelled identity",+ ));+ }+ let registered = registry.owner_lock.as_mut().ok_or_else(|| {+ OpfsError::new(+ OpfsErrorKind::Lock,+ "Web Lock callback completed without an owner capability",+ )+ })?;+ if registered.binding.lock_name != lock_name {+ return Err(OpfsError::new(+ OpfsErrorKind::Lock,+ "registered owner lock does not match canonical identity",+ ));+ }+ registered.request = pending.request;+ registered.callbacks = Some(pending.callbacks);+ Ok(registered.owner)+ })?;+ guard.disarm();+ Ok(owner)+}++fn cancel_database_lock_acquire(lock_name: &str) {+ let (controller, release, owner) = REGISTRY.with(|registry| {+ let mut registry = registry.borrow_mut();+ let controller = registry+ .pending_lock+ .as_mut()+ .filter(|pending| pending.lock_name == lock_name)+ .map(|pending| {+ pending.cancelled = true;+ pending.controller.clone()+ });+ let lock = registry+ .owner_lock+ .as_ref()+ .filter(|lock| lock.binding.lock_name == lock_name && lock.callbacks.is_none());+ (+ controller,+ lock.map(|lock| lock.release.clone()),+ lock.map(|lock| lock.owner),+ )+ });+ if let Some(controller) = controller {+ controller.abort();+ }+ if let Some(owner) = owner {+ poison(owner, "Web Lock acquisition future cancelled after grant");+ }+ if let Some(release) = release {+ let _ = release.call0(&JsValue::UNDEFINED);+ }+}++fn owner_binding(owner: OwnerId) -> Result<OwnerBinding, OpfsError> {+ REGISTRY.with(|registry| {+ registry+ .borrow()+ .owner_lock+ .as_ref()+ .filter(|lock| lock.owner == owner && lock.request.is_some())+ .map(|lock| lock.binding.clone())+ .ok_or_else(|| {+ OpfsError::new(+ OpfsErrorKind::Lock,+ "owner is not backed by the matching held Web Lock",+ )+ })+ })+}++fn begin_database_lock_release(owner: OwnerId) {+ let release = REGISTRY.with(|registry| {+ registry+ .borrow()+ .owner_lock+ .as_ref()+ .filter(|lock| lock.owner == owner)+ .map(|lock| lock.release.clone())+ });+ if let Some(release) = release {+ let _ = release.call0(&JsValue::UNDEFINED);+ }+}++async fn release_database_lock(owner: OwnerId) -> Result<(), OpfsError> {+ let (release, request) = REGISTRY.with(|registry| {+ let registry = registry.borrow();+ let lock = registry+ .owner_lock+ .as_ref()+ .filter(|lock| lock.owner == owner)+ .ok_or_else(|| {+ OpfsError::new(+ OpfsErrorKind::Lock,+ "owner release lacks its matching held Web Lock",+ )+ })?;+ let request = lock.request.clone().ok_or_else(|| {+ OpfsError::new(+ OpfsErrorKind::Lock,+ "owner Web Lock request has no completion proof",+ )+ })?;+ Ok::<_, OpfsError>((lock.release.clone(), request))+ })?;+ release+ .call0(&JsValue::UNDEFINED)+ .map_err(|error| js_error(OpfsErrorKind::Lock, "Web Lock release signal", &error))?;+ JsFuture::from(request)+ .await+ .map_err(|error| js_error(OpfsErrorKind::Lock, "Web Lock release completion", &error))?;+ REGISTRY.with(|registry| {+ let mut registry = registry.borrow_mut();+ if registry+ .owner_lock+ .as_ref()+ .is_some_and(|lock| lock.owner == owner)+ {+ registry.owner_lock = None;+ Ok(())+ } else {+ Err(OpfsError::new(+ OpfsErrorKind::Lock,+ "released Web Lock did not match the current owner",+ ))+ }+ })+}++async fn worker_root() -> Result<FileSystemDirectoryHandle, JsValue> {+ let worker = js_sys::global().dyn_into::<DedicatedWorkerGlobalScope>()?;+ JsFuture::from(worker.navigator().storage().get_directory())+ .await?+ .dyn_into::<FileSystemDirectoryHandle>()+}++async fn open_sync_handle(+ root: &FileSystemDirectoryHandle,+ path: &str,+) -> Result<(FileSystemSyncAccessHandle, bool), JsValue> {+ let (file, created) = match JsFuture::from(root.get_file_handle(path)).await {+ Ok(file) => (file.dyn_into::<FileSystemFileHandle>()?, false),+ Err(error) if is_not_found(&error) => {+ let options = FileSystemGetFileOptions::new();+ options.set_create(true);+ (+ JsFuture::from(root.get_file_handle_with_options(path, &options))+ .await?+ .dyn_into::<FileSystemFileHandle>()?,+ true,+ )+ }+ Err(error) => return Err(error),+ };+ let handle = JsFuture::from(file.create_sync_access_handle())+ .await?+ .dyn_into::<FileSystemSyncAccessHandle>()?;+ Ok((handle, created))+}++fn open_turso_database(+ io: Arc<dyn IO>,+ path: &str,+ options: OpenOptions,+) -> turso_core::Result<Arc<Database>> {+ #[cfg(test)]+ if let Some(error) =+ REGISTRY.with(|registry| registry.borrow_mut().faults.database_open_error.take())+ {+ return Err(LimboError::CompletionError(error));+ }+ Database::open(io, path, options)+}++fn connect_turso_database(database: &Arc<Database>) -> turso_core::Result<Arc<Connection>> {+ #[cfg(test)]+ if let Some(error) =+ REGISTRY.with(|registry| registry.borrow_mut().faults.database_connect_error.take())+ {+ return Err(LimboError::CompletionError(error));+ }+ database.connect()+}++#[cfg(test)]+fn inject_out_of_band_marked_close_failure(connection: &Connection) -> turso_core::Result<()> {+ // Faithfully model pinned Turso's ordering: Connection::close marks the+ // connection closed before shutdown checkpoint can return an error.+ connection.close()?;+ debug_assert!(connection.is_closed());+ Err(LimboError::InternalError(+ "injected failure after out-of-band close marked the connection".into(),+ ))+}++fn close_turso_connection(connection: &Connection) -> turso_core::Result<()> {+ #[cfg(test)]+ if REGISTRY.with(|registry| {+ let mut registry = registry.borrow_mut();+ registry.faults.connection_close_calls += 1;+ std::mem::take(&mut registry.faults.fail_connection_close)+ }) {+ return Err(LimboError::InternalError(+ "injected session-bound Turso close failure".into(),+ ));+ }+ connection.close()+}++fn close_session_handles(+ owner: OwnerId,+ session: SessionId,+ reset_only: bool,+) -> Result<ClosedSession, OpfsError> {+ let handle_ids = REGISTRY+ .with(|registry| {+ let mut registry = registry.borrow_mut();+ if reset_only {+ registry.machine.start_reset_only_close(owner, session)+ } else {+ registry.machine.start_close(owner, session)+ }+ })+ .map_err(state_error)+ .inspect_err(|_| poison(owner, "handle close proof did not match active session"))?;++ let mut failures = Vec::new();+ let mut unexpected = false;+ for (role, handle_id) in [+ (FileRole::Wal, handle_ids[FileRole::Wal.index()]),+ (FileRole::Main, handle_ids[FileRole::Main.index()]),+ ] {+ let entry = REGISTRY.with(|registry| registry.borrow_mut().handles.remove(&handle_id));+ let Some(entry) = entry else {+ unexpected = true;+ continue;+ };+ if entry.role != role || close_registered_handle(&entry).is_err() {+ failures.push((handle_id, entry));+ }+ }++ if unexpected || !failures.is_empty() {+ REGISTRY.with(|registry| {+ let mut registry = registry.borrow_mut();+ registry.handles.extend(failures);+ let _ = registry.machine.poison(+ owner,+ "sync handle close was uncertain or registry state was unexpected".into(),+ );+ });+ return Err(OpfsError::new(+ OpfsErrorKind::Close,+ "OPFS sync handle close was uncertain; session poisoned",+ ));+ }++ let token = REGISTRY+ .with(|registry| registry.borrow_mut().machine.finish_close(owner, session))+ .map_err(state_error)+ .inspect_err(|_| poison(owner, "close completion did not match worker registry"))?;+ Ok(ClosedSession {+ owner,+ token,+ armed: true,+ })+}++fn cleanup_failed_open(owner: OwnerId, session: SessionId, cause: &OpfsError) {+ let entries =+ REGISTRY.with(|registry| registry.borrow_mut().handles.drain().collect::<Vec<_>>());+ let mut uncertain = Vec::new();+ for (id, entry) in entries {+ if close_registered_handle(&entry).is_err() {+ uncertain.push((id, entry));+ }+ }+ REGISTRY.with(|registry| {+ let mut registry = registry.borrow_mut();+ registry.handles.extend(uncertain);+ let cleanup_certain = registry.handles.is_empty();+ let _ = registry.machine.abort_open(+ owner,+ session,+ cleanup_certain,+ format!(+ "partial open cleanup uncertain after {}",+ cause.kind() as u8+ ),+ );+ });+}++fn open_failure_after_cleanup(error: OpfsError, mut owner: OpfsOwner) -> OpenFailure {+ let reusable = REGISTRY.with(|registry| {+ let registry = registry.borrow();+ registry.machine.is_idle_owner(owner.id)+ && registry.handles.is_empty()+ && registry.pending_lock.is_none()+ && registry.owner_lock.as_ref().is_some_and(|lock| {+ lock.owner == owner.id+ && lock.request.is_some()+ && lock.binding.paths == owner.paths+ && lock.binding.lock_name == owner.lock_name+ })+ });+ if reusable {+ OpenFailure::recoverable(error, owner)+ } else {+ owner.armed = false;+ OpenFailure::poisoned(OpfsError::new(+ OpfsErrorKind::Poisoned,+ "partial OPFS open cleanup was uncertain; session poisoned",+ ))+ }+}++fn close_registered_handle(entry: &RegisteredHandle) -> Result<(), JsValue> {+ #[cfg(test)]+ if take_close_failure(entry.role) {+ return Err(JsValue::from_str("injected sync handle close failure"));+ }+ close_sync_handle(&entry.handle)+}++fn close_sync_handle(handle: &FileSystemSyncAccessHandle) -> Result<(), JsValue> {+ let close =+ Reflect::get(handle.as_ref(), &JsValue::from_str("close"))?.dyn_into::<Function>()?;+ close.call0(handle.as_ref()).map(|_| ())+}++async fn reset_paths(paths: &Paths, recursive: bool) -> Result<(), OpfsError> {+ let root = worker_root()+ .await+ .map_err(|error| js_error(OpfsErrorKind::Remove, "OPFS reset root open", &error))?;+ for role in FileRole::ALL {+ remove_if_present(&root, paths.get(role), recursive).await?;+ #[cfg(test)]+ if role == FileRole::Main && take_reset_failure(ResetFault::AfterMainRemoval) {+ return Err(OpfsError::new(+ OpfsErrorKind::Remove,+ "injected failure after removing the main path",+ ));+ }+ }+ for role in FileRole::ALL {+ let options = FileSystemGetFileOptions::new();+ options.set_create(true);+ JsFuture::from(root.get_file_handle_with_options(paths.get(role), &options))+ .await+ .map_err(|error| js_error(OpfsErrorKind::Recreate, "OPFS path recreate", &error))?+ .dyn_into::<FileSystemFileHandle>()+ .map_err(|error| {+ js_error(OpfsErrorKind::Recreate, "OPFS recreated entry type", &error)+ })?;+ #[cfg(test)]+ if role == FileRole::Main && take_reset_failure(ResetFault::AfterMainRecreate) {+ return Err(OpfsError::new(+ OpfsErrorKind::Recreate,+ "injected failure after recreating the main path",+ ));+ }+ }+ Ok(())+}++async fn remove_if_present(+ root: &FileSystemDirectoryHandle,+ path: &str,+ recursive: bool,+) -> Result<(), OpfsError> {+ let remove = if recursive {+ let options = FileSystemRemoveOptions::new();+ options.set_recursive(true);+ root.remove_entry_with_options(path, &options)+ } else {+ root.remove_entry(path)+ };+ match JsFuture::from(remove).await {+ Ok(_) => Ok(()),+ Err(error) if is_not_found(&error) => Ok(()),+ Err(error) => Err(js_error(OpfsErrorKind::Remove, "OPFS path remove", &error)),+ }+}++fn is_not_found(value: &JsValue) -> bool {+ dom_exception_name(value).as_deref() == Some("NotFoundError")+}++fn registered_handle(+ owner: OwnerId,+ session: SessionId,+ id: HandleId,+) -> turso_core::Result<FileSystemSyncAccessHandle> {+ let handle = REGISTRY.with(|registry| {+ let registry = registry.borrow();+ registry.machine.validate_session(owner, session)?;+ Ok::<_, LimboError>(registry.handles.get(&id).map(|entry| entry.handle.clone()))+ })?;+ handle.ok_or_else(|| {+ poison(+ owner,+ "active session referenced a missing registered OPFS handle",+ );+ completion_io_error(ErrorKind::Other, "active OPFS handle registry is invalid")+ })+}++fn read_once(+ owner: OwnerId,+ session: SessionId,+ id: HandleId,+ pos: u64,+ buffer: &Buffer,+) -> turso_core::Result<i32> {+ validate_position(pos)?;+ let handle = registered_handle(owner, session, id)?;+ let options = FileSystemReadWriteOptions::new();+ options.set_at(pos as f64);+ handle+ .read_with_u8_array_and_options(buffer.as_mut_slice(), &options)+ .map_err(|error| js_handle_limbo_error(owner, "OPFS read", &error, ErrorKind::Other))+ .and_then(number_to_i32)+}++fn preflight_write_range(+ pos: u64,+ lengths: impl IntoIterator<Item = usize>,+) -> Result<usize, CompletionError> {+ let total = lengths.into_iter().try_fold(0_usize, |total, length| {+ total.checked_add(length).ok_or(CompletionError::ShortWrite)+ })?;+ completion_count(total)?;+ if total == 0 {+ return Ok(0);+ }+ validate_position(pos).map_err(limbo_to_completion)?;+ let total_u64 = u64::try_from(total).map_err(|_| CompletionError::ShortWrite)?;+ let end = pos+ .checked_add(total_u64)+ .ok_or(CompletionError::ShortWrite)?;+ if end > MAX_SAFE_INTEGER {+ return Err(CompletionError::IOError(+ ErrorKind::InvalidInput,+ "OPFS write end exceeds JavaScript safe integer",+ ));+ }+ Ok(total)+}++fn write_all(+ mut pos: u64,+ mut bytes: &[u8],+ owner: OwnerId,+ session: SessionId,+ id: HandleId,+) -> Result<usize, CompletionError> {+ let expected = bytes.len();+ let mut total = 0_usize;+ while !bytes.is_empty() {+ let written = write_once(owner, session, id, pos, bytes)?;+ if written == 0 || written > bytes.len() {+ return Err(CompletionError::ShortWrite);+ }+ total = total+ .checked_add(written)+ .ok_or(CompletionError::ShortWrite)?;+ pos = pos+ .checked_add(written as u64)+ .ok_or(CompletionError::ShortWrite)?;+ bytes = &bytes[written..];+ }+ if total == expected {+ Ok(total)+ } else {+ Err(CompletionError::ShortWrite)+ }+}++fn write_once(+ owner: OwnerId,+ session: SessionId,+ id: HandleId,+ pos: u64,+ bytes: &[u8],+) -> Result<usize, CompletionError> {+ validate_position(pos).map_err(limbo_to_completion)?;+ let handle = registered_handle(owner, session, id).map_err(limbo_to_completion)?;+ #[cfg(test)]+ let (chunk_limit, injected_error) = REGISTRY.with(|registry| {+ let mut registry = registry.borrow_mut();+ let injected = registry.faults.next_write_error.take().or_else(|| {+ let fault = registry.faults.write_error_after_chunks.as_mut()?;+ if fault.0 == 0 {+ let error = fault.1;+ registry.faults.write_error_after_chunks = None;+ Some(error)+ } else {+ fault.0 -= 1;+ None+ }+ });+ (registry.faults.max_write_chunk, injected)+ });+ #[cfg(not(test))]+ let (chunk_limit, injected_error): (Option<usize>, Option<CompletionError>) = (None, None);+ if let Some(error) = injected_error {+ return Err(error);+ }+ let chunk_len = chunk_limit.unwrap_or(bytes.len()).min(bytes.len());+ if chunk_len == 0 {+ return Ok(0);+ }+ let options = FileSystemReadWriteOptions::new();+ options.set_at(pos as f64);+ let written = handle+ .write_with_u8_array_and_options(&bytes[..chunk_len], &options)+ .map_err(|error| {+ js_handle_completion_error(owner, "OPFS write", &error, ErrorKind::Other)+ })?;+ let written = number_to_i32(written)+ .map(|written| written as usize)+ .map_err(limbo_to_completion)?;+ if written <= chunk_len {+ Ok(written)+ } else {+ Err(CompletionError::ShortWrite)+ }+}++fn completion_count(count: usize) -> Result<i32, CompletionError> {+ i32::try_from(count).map_err(|_| CompletionError::ShortWrite)+}++fn finish_completion(completion: &Completion, result: turso_core::Result<i32>) {+ match result {+ Ok(value) => completion.complete(value),+ Err(error) => completion.error(limbo_to_completion(error)),+ }+}++fn validate_position(value: u64) -> turso_core::Result<()> {+ if value <= MAX_SAFE_INTEGER {+ Ok(())+ } else {+ Err(completion_io_error(+ ErrorKind::InvalidInput,+ "OPFS offset exceeds JavaScript safe integer",+ ))+ }+}++fn number_to_i32(value: f64) -> turso_core::Result<i32> {+ if value.is_finite() && value >= 0.0 && value.fract() == 0.0 && value <= i32::MAX as f64 {+ Ok(value as i32)+ } else {+ Err(completion_io_error(+ ErrorKind::InvalidData,+ "invalid OPFS byte count",+ ))+ }+}++fn number_to_u64(value: f64) -> turso_core::Result<u64> {+ if value.is_finite() && value >= 0.0 && value.fract() == 0.0 && value <= MAX_SAFE_INTEGER as f64+ {+ Ok(value as u64)+ } else {+ Err(completion_io_error(+ ErrorKind::InvalidData,+ "invalid OPFS file size",+ ))+ }+}++fn state_error(error: StateError) -> OpfsError {+ let kind = match error.kind {+ StateErrorKind::Ownership => OpfsErrorKind::Ownership,+ StateErrorKind::Reentrant => OpfsErrorKind::Reentrant,+ StateErrorKind::ActiveReferences => OpfsErrorKind::ActiveReferences,+ StateErrorKind::Poisoned => OpfsErrorKind::Poisoned,+ StateErrorKind::Path | StateErrorKind::Flags => OpfsErrorKind::InvalidName,+ StateErrorKind::Session+ | StateErrorKind::Registration+ | StateErrorKind::Token+ | StateErrorKind::Exhausted => OpfsErrorKind::Lifecycle,+ };+ OpfsError::new(kind, error.message)+}++impl From<StateError> for LimboError {+ fn from(error: StateError) -> Self {+ let kind = match error.kind {+ StateErrorKind::Reentrant | StateErrorKind::ActiveReferences => ErrorKind::WouldBlock,+ StateErrorKind::Path => ErrorKind::NotFound,+ StateErrorKind::Flags => ErrorKind::PermissionDenied,+ StateErrorKind::Ownership+ | StateErrorKind::Session+ | StateErrorKind::Registration+ | StateErrorKind::Token+ | StateErrorKind::Exhausted+ | StateErrorKind::Poisoned => ErrorKind::Other,+ };+ completion_io_error(kind, error.message)+ }+}++fn completion_io_error(kind: ErrorKind, operation: &'static str) -> LimboError {+ CompletionError::IOError(kind, operation).into()+}++fn limbo_to_completion(error: LimboError) -> CompletionError {+ match error {+ LimboError::CompletionError(error) => error,+ _ => CompletionError::IOError(ErrorKind::Other, "OPFS adapter"),+ }+}++fn js_handle_limbo_error(+ owner: OwnerId,+ operation: &'static str,+ value: &JsValue,+ fallback: ErrorKind,+) -> LimboError {+ LimboError::CompletionError(js_handle_completion_error(+ owner, operation, value, fallback,+ ))+}++fn js_handle_completion_error(+ owner: OwnerId,+ operation: &'static str,+ value: &JsValue,+ fallback: ErrorKind,+) -> CompletionError {+ if is_invalid_active_handle_error(value) {+ poison(+ owner,+ "browser reported invalid ownership/state for an active OPFS handle",+ );+ }+ js_completion_error(operation, value, fallback)+}++fn is_invalid_active_handle_error(value: &JsValue) -> bool {+ matches!(+ dom_exception_name(value).as_deref(),+ Some("InvalidStateError") | Some("NoModificationAllowedError")+ )+}++fn js_completion_error(+ operation: &'static str,+ value: &JsValue,+ fallback: ErrorKind,+) -> CompletionError {+ let kind = match dom_exception_name(value).as_deref() {+ Some("QuotaExceededError") => ErrorKind::StorageFull,+ Some("NotFoundError") => ErrorKind::NotFound,+ Some("InvalidStateError") | Some("NoModificationAllowedError") => ErrorKind::Other,+ Some("TypeMismatchError") | Some("InvalidModificationError") => ErrorKind::InvalidInput,+ _ => fallback,+ };+ CompletionError::IOError(kind, operation)+}++fn turso_error(operation: &'static str, error: LimboError) -> OpfsError {+ let kind = match &error {+ LimboError::CompletionError(CompletionError::IOError(ErrorKind::StorageFull, _)) => {+ OpfsErrorKind::StorageFull+ }+ _ => OpfsErrorKind::Turso,+ };+ OpfsError::new(kind, format!("Turso {operation} failed: {error}"))+}++fn js_error(kind: OpfsErrorKind, operation: &'static str, value: &JsValue) -> OpfsError {+ let actual_kind = if dom_exception_name(value).as_deref() == Some("QuotaExceededError") {+ OpfsErrorKind::StorageFull+ } else {+ kind+ };+ let name = dom_exception_name(value).unwrap_or_else(|| "JavaScriptError".into());+ OpfsError::new(actual_kind, format!("{operation} failed ({name})"))+}++fn dom_exception_name(value: &JsValue) -> Option<String> {+ value+ .dyn_ref::<DomException>()+ .map(DomException::name)+ .or_else(|| {+ Reflect::get(value, &JsValue::from_str("name"))+ .ok()+ .and_then(|name| name.as_string())+ })+}++fn poison(owner: OwnerId, reason: &str) {+ let _ = REGISTRY.try_with(|registry| {+ if let Ok(mut registry) = registry.try_borrow_mut() {+ let _ = registry.machine.poison(owner, reason.to_owned());+ }+ });+}++#[cfg(test)]+fn take_open_failure(role: FileRole) -> bool {+ REGISTRY.with(|registry| {+ let mut registry = registry.borrow_mut();+ if registry.faults.fail_open == Some(role) {+ registry.faults.fail_open = None;+ true+ } else {+ false+ }+ })+}++#[cfg(test)]+fn take_reset_failure(fault: ResetFault) -> bool {+ REGISTRY.with(|registry| {+ let mut registry = registry.borrow_mut();+ if registry.faults.reset_fault == Some(fault) {+ registry.faults.reset_fault = None;+ true+ } else {+ false+ }+ })+}++#[cfg(test)]+fn take_close_failure(role: FileRole) -> bool {+ REGISTRY.with(|registry| {+ let mut registry = registry.borrow_mut();+ if registry.faults.fail_close == Some(role) {+ registry.faults.fail_close = None;+ true+ } else {+ false+ }+ })+}++#[allow(dead_code)]+fn assert_send_sync_contract() {+ fn assert_send_sync<T: Send + Sync>() {}+ assert_send_sync::<OwnerId>();+ assert_send_sync::<SessionId>();+ assert_send_sync::<HandleId>();+ assert_send_sync::<OpfsIo>();+ assert_send_sync::<OpfsFile>();+}diff --git a/crates/client/turso-opfs/src/browser/test.rs b/crates/client/turso-opfs/src/browser/test.rsnew file mode 100644index 0000000000..f855fada40--- /dev/null+++ b/crates/client/turso-opfs/src/browser/test.rs@@ -0,0 +1,1048 @@+use super::*;+use std::{+ cell::{Cell, RefCell},+ future::Future,+ rc::Rc,+ sync::{+ Mutex,+ atomic::{AtomicBool, AtomicUsize},+ },+ task::{Context, Poll, Waker},+};+use turso_core::{Row, StepResult};+use wasm_bindgen_test::*;+use web_sys::{FileSystemGetDirectoryOptions, FileSystemGetFileOptions, FileSystemRemoveOptions};++wasm_bindgen_test_configure!(run_in_dedicated_worker);++#[derive(Debug)]+struct TrackedCompletion {+ completion: Completion,+ count: Arc<AtomicUsize>,+ result: Arc<Mutex<Option<Result<i32, CompletionError>>>>,+}++fn write_completion() -> TrackedCompletion {+ tracked_completion(Completion::new_write)+}++fn sync_completion() -> TrackedCompletion {+ tracked_completion(Completion::new_sync)+}++fn truncate_completion() -> TrackedCompletion {+ tracked_completion(Completion::new_trunc)+}++fn tracked_completion(+ build: impl FnOnce(Box<dyn Fn(Result<i32, CompletionError>) + Send + Sync>) -> Completion,+) -> TrackedCompletion {+ let count = Arc::new(AtomicUsize::new(0));+ let result = Arc::new(Mutex::new(None));+ let callback_count = count.clone();+ let callback_result = result.clone();+ let callback: Box<dyn Fn(Result<i32, CompletionError>) + Send + Sync> =+ Box::new(move |value| {+ callback_count.fetch_add(1, Ordering::SeqCst);+ *callback_result.lock().expect("tracked callback result") = Some(value);+ });+ TrackedCompletion {+ completion: build(callback),+ count,+ result,+ }+}++fn read_completion(buffer: Arc<Buffer>) -> TrackedCompletion {+ let count = Arc::new(AtomicUsize::new(0));+ let result = Arc::new(Mutex::new(None));+ let callback_count = count.clone();+ let callback_result = result.clone();+ let completion = Completion::new_read(buffer, move |value| {+ callback_count.fetch_add(1, Ordering::SeqCst);+ *callback_result.lock().expect("tracked read result") = Some(+ value+ .as_ref()+ .map(|(_, bytes)| *bytes)+ .map_err(|error| *error),+ );+ None+ });+ TrackedCompletion {+ completion,+ count,+ result,+ }+}++fn assert_completion(tracked: &TrackedCompletion, expected: Result<i32, CompletionError>) {+ assert_eq!(tracked.count.load(Ordering::SeqCst), 1);+ assert_eq!(+ tracked.result.lock().expect("tracked result").as_ref(),+ Some(&expected)+ );+ assert!(tracked.completion.finished());+ assert_eq!(tracked.completion.get_error(), expected.err());+}++fn query_one_i64(connection: &Arc<Connection>, sql: &str) -> turso_core::Result<i64> {+ let mut statement = connection.prepare(sql)?;+ let mut result = None;+ drive_statement(&mut statement, |row| {+ result = Some(row.get::<i64>(0)?);+ Ok(())+ })?;+ result.ok_or_else(|| LimboError::InternalError("query returned no row".into()))+}++fn drive_statement(+ statement: &mut turso_core::Statement,+ mut on_row: impl FnMut(&Row) -> turso_core::Result<()>,+) -> turso_core::Result<()> {+ loop {+ match statement.step()? {+ StepResult::Done => return Ok(()),+ StepResult::Row => on_row(+ statement+ .row()+ .ok_or_else(|| LimboError::InternalError("row step had no row".into()))?,+ )?,+ StepResult::IO | StepResult::Yield => statement._io().step()?,+ StepResult::Busy => return Err(LimboError::Busy),+ StepResult::Interrupt => return Err(LimboError::Interrupt),+ }+ }+}++async fn recursive_remove(root: &FileSystemDirectoryHandle, path: &str) {+ let options = FileSystemRemoveOptions::new();+ options.set_recursive(true);+ match JsFuture::from(root.remove_entry_with_options(path, &options)).await {+ Ok(_) => {}+ Err(error) if is_not_found(&error) => {}+ Err(error) => panic!("failed to clean browser test artifact: {error:?}"),+ }+}++async fn clean_pair(database_name: &str) {+ let root = worker_root().await.expect("worker OPFS root");+ recursive_remove(&root, database_name).await;+ recursive_remove(&root, &format!("{database_name}-wal")).await;+}++async fn replace_poisoned_registry_for_test() {+ let (handles, pending, lock) = REGISTRY.with(|registry| {+ let mut registry = registry.borrow_mut();+ (+ std::mem::take(&mut registry.handles),+ registry.pending_lock.take(),+ registry.owner_lock.take(),+ )+ });+ for entry in handles.into_values() {+ let _ = close_sync_handle(&entry.handle);+ }+ if let Some(pending) = pending {+ pending.controller.abort();+ }+ if let Some(lock) = lock {+ let _ = lock.release.call0(&JsValue::UNDEFINED);+ if let Some(request) = lock.request {+ let _ = JsFuture::from(request).await;+ }+ }+ REGISTRY.with(|registry| *registry.borrow_mut() = Registry::default());+}++async fn open_ready(owner: OpfsOwner) -> OpfsSession {+ match owner.open().await.expect("pre-open OPFS pair") {+ OpenResult::Ready(session) => session,+ OpenResult::ResetRequired(_) => panic!("expected a complete OPFS pair"),+ }+}++fn connect_ready(session: OpfsSession) -> ConnectedOpfsSession {+ session+ .connect()+ .expect("open sole production Turso connection")+}++async fn fresh_closed(database_name: &str) -> ClosedSession {+ let owner = OpfsOwner::acquire(database_name)+ .await+ .expect("identity-bound owner");+ let owner = owner.recovery_wipe().await.expect("fresh recovery wipe");+ connect_ready(open_ready(owner).await)+ .try_close()+ .expect("adapter-driven close")+}++struct RawHeldLock {+ release: Function,+ request: Promise,+ _grant: Function,+}++impl RawHeldLock {+ async fn release(self) {+ self.release+ .call0(&JsValue::UNDEFINED)+ .expect("release raw test Web Lock");+ JsFuture::from(self.request)+ .await+ .expect("raw test Web Lock settles");+ }+}++async fn acquire_raw_web_lock(lock_name: &str) -> RawHeldLock {+ let worker = js_sys::global()+ .dyn_into::<DedicatedWorkerGlobalScope>()+ .expect("DedicatedWorker raw lock");+ let manager = Reflect::get(worker.navigator().as_ref(), &JsValue::from_str("locks"))+ .expect("raw Web Lock manager");+ let mut granted_resolve = None;+ let granted = Promise::new(&mut |resolve, _reject| granted_resolve = Some(resolve.clone()));+ let granted_resolve = granted_resolve.expect("granted resolver");+ let release_slot = Rc::new(RefCell::new(None));+ let callback_release = release_slot.clone();+ let grant = Closure::wrap(Box::new(move |lock: JsValue| -> Promise {+ assert!(!lock.is_null() && !lock.is_undefined());+ let mut release_resolve = None;+ let held = Promise::new(&mut |resolve, _reject| release_resolve = Some(resolve.clone()));+ *callback_release.borrow_mut() = release_resolve;+ let _ = granted_resolve.call1(&JsValue::UNDEFINED, &JsValue::TRUE);+ held+ }) as Box<dyn FnMut(JsValue) -> Promise>)+ .into_js_value()+ .unchecked_into::<Function>();+ let options = Object::new();+ Reflect::set(+ options.as_ref(),+ &JsValue::from_str("mode"),+ &JsValue::from_str("exclusive"),+ )+ .expect("raw lock mode");+ let request = Reflect::get(&manager, &JsValue::from_str("request"))+ .expect("raw request property")+ .dyn_into::<Function>()+ .expect("raw request function")+ .call3(+ &manager,+ &JsValue::from_str(lock_name),+ options.as_ref(),+ grant.as_ref(),+ )+ .expect("raw lock request")+ .dyn_into::<Promise>()+ .expect("raw request promise");+ JsFuture::from(granted).await.expect("raw Web Lock granted");+ let release = release_slot+ .borrow_mut()+ .take()+ .expect("raw lock release resolver");+ RawHeldLock {+ release,+ request,+ _grant: grant,+ }+}++async fn yield_tasks_until(mut condition: impl FnMut() -> bool) {+ for _ in 0..32 {+ if condition() {+ return;+ }+ let task = Promise::new(&mut |resolve, reject| {+ let result = Reflect::get(&js_sys::global(), &JsValue::from_str("setTimeout"))+ .and_then(|value| value.dyn_into::<Function>())+ .and_then(|set_timeout| {+ set_timeout.call2(&js_sys::global(), resolve.as_ref(), &JsValue::from_f64(0.0))+ });+ if let Err(error) = result {+ let _ = reject.call1(&JsValue::UNDEFINED, &error);+ }+ });+ JsFuture::from(task).await.expect("browser task yield");+ }+ assert!(+ condition(),+ "condition did not settle after browser task yields"+ );+}++async fn web_lock_available(lock_name: &str) -> bool {+ let worker = js_sys::global()+ .dyn_into::<DedicatedWorkerGlobalScope>()+ .expect("DedicatedWorker lock probe");+ let manager = Reflect::get(worker.navigator().as_ref(), &JsValue::from_str("locks"))+ .expect("Web Lock manager");+ let options = Object::new();+ Reflect::set(+ options.as_ref(),+ &JsValue::from_str("mode"),+ &JsValue::from_str("exclusive"),+ )+ .expect("lock mode");+ Reflect::set(+ options.as_ref(),+ &JsValue::from_str("ifAvailable"),+ &JsValue::TRUE,+ )+ .expect("ifAvailable");+ let observed = Rc::new(Cell::new(None));+ let callback_observed = observed.clone();+ let callback = Closure::wrap(Box::new(move |lock: JsValue| -> Promise {+ callback_observed.set(Some(!lock.is_null() && !lock.is_undefined()));+ Promise::resolve(&JsValue::UNDEFINED)+ }) as Box<dyn FnMut(JsValue) -> Promise>);+ let request = Reflect::get(&manager, &JsValue::from_str("request"))+ .expect("request property")+ .dyn_into::<Function>()+ .expect("request function")+ .call3(+ &manager,+ &JsValue::from_str(lock_name),+ options.as_ref(),+ callback.as_ref().unchecked_ref::<Function>().as_ref(),+ )+ .expect("request lock probe")+ .dyn_into::<Promise>()+ .expect("request promise");+ JsFuture::from(request).await.expect("lock probe completes");+ observed.get().expect("lock callback observed")+}++fn poll_once<F: Future>(mut future: std::pin::Pin<&mut F>) -> Poll<F::Output> {+ let waker = Waker::noop();+ let mut context = Context::from_waker(waker);+ future.as_mut().poll(&mut context)+}++fn assert_poisoned() {+ assert!(REGISTRY.with(|registry| registry.borrow().machine.is_poisoned()));+}++#[wasm_bindgen_test]+async fn real_worker_opfs_contract_and_consuming_lifecycle() {+ let nonce = js_sys::Date::now() as u64;+ let database_name = format!("wp05-{nonce}.db");+ let wal_name = format!("{database_name}-wal");+ clean_pair(&database_name).await;++ assert_eq!(+ OpfsOwner::acquire("")+ .await+ .expect_err("empty database identity")+ .kind(),+ OpfsErrorKind::InvalidName+ );+ assert_eq!(+ OpfsOwner::acquire("nested/cache.db")+ .await+ .expect_err("database identity must be a direct child")+ .kind(),+ OpfsErrorKind::InvalidName+ );+ assert_eq!(+ OpfsOwner::acquire(&format!("{database_name}-wal"))+ .await+ .expect_err("a WAL path cannot become a second canonical identity")+ .kind(),+ OpfsErrorKind::InvalidName+ );++ // Cancellation before grant keeps JS-owned callbacks alive until the+ // aborted request rejects, then clears the pending capability without a+ // trap or leaked lock.+ let queued_db = format!("wp05-lock-queued-{nonce}.db");+ let queued_lock_name = owner_lock_name(&queued_db);+ let blocker = acquire_raw_web_lock(&queued_lock_name).await;+ let mut queued_acquire = Box::pin(OpfsOwner::acquire(&queued_db));+ assert!(matches!(poll_once(queued_acquire.as_mut()), Poll::Pending));+ assert!(REGISTRY.with(|registry| registry.borrow().pending_lock.is_some()));+ drop(queued_acquire);+ yield_tasks_until(|| REGISTRY.with(|registry| registry.borrow().pending_lock.is_none())).await;+ assert!(REGISTRY.with(|registry| registry.borrow().owner_lock.is_none()));+ assert_eq!(+ REGISTRY.with(|registry| registry.borrow().machine.phase_label()),+ "unowned"+ );+ blocker.release().await;+ assert!(web_lock_available(&queued_lock_name).await);++ // If the browser grants before Rust polls the acquisition future again,+ // dropping that future poisons, releases, and retains all JS callbacks+ // until the held request fulfills.+ let granted_db = format!("wp05-lock-granted-{nonce}.db");+ let granted_lock_name = owner_lock_name(&granted_db);+ let mut granted_acquire = Box::pin(OpfsOwner::acquire(&granted_db));+ assert!(matches!(poll_once(granted_acquire.as_mut()), Poll::Pending));+ yield_tasks_until(|| REGISTRY.with(|registry| registry.borrow().owner_lock.is_some())).await;+ assert!(REGISTRY.with(|registry| registry.borrow().pending_lock.is_some()));+ drop(granted_acquire);+ yield_tasks_until(|| {+ REGISTRY.with(|registry| {+ let registry = registry.borrow();+ registry.pending_lock.is_none() && registry.owner_lock.is_none()+ })+ })+ .await;+ assert_poisoned();+ assert!(web_lock_available(&granted_lock_name).await);+ replace_poisoned_registry_for_test().await;++ let mut owner = OpfsOwner::acquire(&database_name)+ .await+ .expect("physical owner Web Lock");+ assert_eq!(owner.database_path(), database_name);+ assert_eq!(owner.lock_name(), owner_lock_name(&database_name));+ assert!(!web_lock_available(owner.lock_name()).await);+ assert_eq!(+ OpfsOwner::acquire("other.db")+ .await+ .expect_err("one worker cannot own a second capability")+ .kind(),+ OpfsErrorKind::Ownership+ );++ REGISTRY.with(|registry| registry.borrow_mut().faults.fail_open = Some(FileRole::Wal));+ let failure = owner+ .open()+ .await+ .expect_err("injected WAL pre-open failure");+ assert_eq!(failure.error().kind(), OpfsErrorKind::Open);+ owner = failure+ .into_owner()+ .expect("certain partial-open cleanup returns locked owner");+ assert_eq!(+ REGISTRY.with(|registry| registry.borrow().machine.phase_label()),+ "idle"+ );+ assert!(REGISTRY.with(|registry| registry.borrow().handles.is_empty()));++ let incomplete = match owner.open().await.expect("detect one-sided pair") {+ OpenResult::ResetRequired(incomplete) => incomplete,+ OpenResult::Ready(_) => panic!("one-sided pair must never expose Turso I/O"),+ };+ assert_eq!(incomplete.database_path(), database_name);+ owner = incomplete+ .reset()+ .await+ .expect("reset-only type removes and recreates both paths");++ let session = open_ready(owner).await;+ assert_eq!(session.disposition(), OpenDisposition::Fresh);+ assert_eq!(session.database_path(), database_name);+ assert_eq!(session.wal_path(), wal_name);++ // Internal-only direct adapter checks. Production callers cannot obtain+ // this I/O; they can only consume OpfsSession::connect.+ {+ let io = session.io.clone();+ let main = io+ .open_file(&database_name, OpenFlags::Create, true)+ .expect("approved main flags");+ let wal = io+ .open_file(&wal_name, OpenFlags::Create, false)+ .expect("approved WAL flags");+ assert!(+ io.open_file("unregistered.db", OpenFlags::Create, true)+ .is_err()+ );+ assert!(+ io.open_file(&database_name, OpenFlags::ReadOnly, true)+ .is_err()+ );+ assert!(+ io.open_file(&database_name, OpenFlags::Create | OpenFlags::NoLock, true,)+ .is_err()+ );+ assert!(io.open_file(&wal_name, OpenFlags::Create, true).is_err());+ assert!(io.remove_file(&database_name).is_err());+ assert_eq!(+ io.file_id(&database_name).expect("registered file ID"),+ FileId::from_path_hash(&database_name)+ );+ main.lock_file(true)+ .expect("owner lock makes file lock a no-op");+ main.unlock_file().expect("owner unlock no-op");+ // Monotonic clock samples are strictly increasing.+ assert!(io.current_time_monotonic() < io.current_time_monotonic());+ // Wall-clock micros is the sub-second microsecond component.+ assert!(io.current_time_wall_clock().micros < 1_000_000);++ let empty = write_completion();+ drop(+ main.pwrite(+ u64::MAX,+ Arc::new(Buffer::new(Vec::new())),+ empty.completion.clone(),+ )+ .expect("empty write submission"),+ );+ assert_completion(&empty, Ok(0));++ REGISTRY.with(|registry| registry.borrow_mut().faults.max_write_chunk = Some(2));+ let partial = write_completion();+ drop(+ main.pwrite(+ 0,+ Arc::new(Buffer::new(b"abcdef".to_vec())),+ partial.completion.clone(),+ )+ .expect("partial write retry submission"),+ );+ assert_completion(&partial, Ok(6));+ REGISTRY.with(|registry| registry.borrow_mut().faults.max_write_chunk = None);++ let vectored = write_completion();+ drop(+ main.pwritev(+ 6,+ vec![+ Arc::new(Buffer::new(b"12".to_vec())),+ Arc::new(Buffer::new(b"34".to_vec())),+ ],+ vectored.completion.clone(),+ )+ .expect("vectored write submission"),+ );+ assert_completion(&vectored, Ok(4));+ assert_eq!(main.size().expect("size after writes"), 10);++ let before_overflow = main.size().expect("size before overflow probes");+ let overflow = write_completion();+ drop(+ main.pwrite(+ MAX_SAFE_INTEGER,+ Arc::new(Buffer::new(vec![1])),+ overflow.completion.clone(),+ )+ .expect("overflow submission completes through callback"),+ );+ assert_completion(+ &overflow,+ Err(CompletionError::IOError(+ ErrorKind::InvalidInput,+ "OPFS write end exceeds JavaScript safe integer",+ )),+ );+ assert_eq!(+ main.size().expect("pwrite overflow is mutation-free"),+ before_overflow+ );++ let vectored_overflow = write_completion();+ drop(+ main.pwritev(+ MAX_SAFE_INTEGER - 1,+ vec![+ Arc::new(Buffer::new(vec![1])),+ Arc::new(Buffer::new(vec![2])),+ ],+ vectored_overflow.completion.clone(),+ )+ .expect("vectored overflow submission"),+ );+ assert_completion(+ &vectored_overflow,+ Err(CompletionError::IOError(+ ErrorKind::InvalidInput,+ "OPFS write end exceeds JavaScript safe integer",+ )),+ );+ assert_eq!(+ main.size().expect("pwritev overflow is mutation-free"),+ before_overflow+ );+ assert_eq!(+ preflight_write_range(0, [i32::MAX as usize, 1]),+ Err(CompletionError::ShortWrite)+ );++ let truncate = truncate_completion();+ drop(+ main.truncate(0, truncate.completion.clone())+ .expect("clear direct test bytes"),+ );+ assert_completion(&truncate, Ok(0));+ let injected = CompletionError::IOError(ErrorKind::StorageFull, "injected partial error");+ REGISTRY.with(|registry| {+ let mut registry = registry.borrow_mut();+ registry.faults.max_write_chunk = Some(2);+ registry.faults.write_error_after_chunks = Some((1, injected));+ });+ let partial_error = write_completion();+ drop(+ main.pwrite(+ 0,+ Arc::new(Buffer::new(b"abcdef".to_vec())),+ partial_error.completion.clone(),+ )+ .expect("partial-then-error submission"),+ );+ assert_completion(&partial_error, Err(injected));+ assert_eq!(main.size().expect("first chunk was physically written"), 2);+ let partial_bytes = Arc::new(Buffer::new(vec![0; 2]));+ let partial_read = read_completion(partial_bytes.clone());+ drop(+ main.pread(0, partial_read.completion.clone())+ .expect("read partial runtime write"),+ );+ assert_completion(&partial_read, Ok(2));+ assert_eq!(partial_bytes.as_slice(), b"ab");+ REGISTRY.with(|registry| registry.borrow_mut().faults.max_write_chunk = None);++ let clear = truncate_completion();+ drop(+ main.truncate(0, clear.completion.clone())+ .expect("restore blank Turso main file"),+ );+ assert_completion(&clear, Ok(0));+ let sync = sync_completion();+ drop(+ main.sync(sync.completion.clone(), FileSyncType::Fsync)+ .expect("sync blank file"),+ );+ assert_completion(&sync, Ok(0));++ let reentrant_rejected = Arc::new(AtomicBool::new(false));+ let callback_file = main.clone();+ let callback_observation = reentrant_rejected.clone();+ let reentrant = Completion::new_write(move |_| {+ callback_observation.store(callback_file.size().is_err(), Ordering::SeqCst);+ });+ drop(+ main.pwrite(0, Arc::new(Buffer::new(Vec::new())), reentrant.clone())+ .expect("reentrancy callback probe"),+ );+ assert!(reentrant.finished());+ assert!(reentrant_rejected.load(Ordering::SeqCst));+ drop((main, wal, io));+ }++ let stale_owner = session.owner;+ let stale_session = session.session;+ let connected = connect_ready(session);+ let connection = connected.connection();+ connection+ .execute("CREATE TABLE persistence (id INTEGER PRIMARY KEY, value TEXT NOT NULL)")+ .expect("create persistence table");+ connection+ .execute("INSERT INTO persistence (id, value) VALUES (1, 'preserved')")+ .expect("insert persistence marker");+ assert_eq!(+ query_one_i64(&connection, "SELECT COUNT(*) FROM persistence")+ .expect("query persistence count"),+ 1+ );++ let close_failure = connected+ .try_close()+ .expect_err("connection clone proves graceful close was omitted");+ assert_eq!(+ close_failure.error().kind(),+ OpfsErrorKind::ActiveReferences+ );+ let connected = close_failure+ .into_session()+ .expect("pre-close rejection returns connected session");+ assert!(!connection.is_closed());+ let connection_weak = Arc::downgrade(&connection);+ drop(connection);+ let close_calls = REGISTRY.with(|registry| registry.borrow().faults.connection_close_calls);+ let closed = connected+ .try_close()+ .expect("adapter calls and proves Connection::close success");+ assert_eq!(+ REGISTRY.with(|registry| registry.borrow().faults.connection_close_calls),+ close_calls + 1+ );+ assert!(connection_weak.upgrade().is_none());++ let valid_token = closed.token;+ let invalid = ClosedSession {+ owner: closed.owner,+ token: CloseToken::from_raw(valid_token.get() + 1),+ armed: true,+ };+ assert_eq!(+ invalid.preserve().expect_err("invalid close token").kind(),+ OpfsErrorKind::Lifecycle+ );+ assert_eq!(+ REGISTRY.with(|registry| registry.borrow().machine.phase_label()),+ "closed"+ );+ let closed = ClosedSession {+ owner: stale_owner,+ token: valid_token,+ armed: true,+ };+ owner = closed.preserve().expect("valid one-use preserve");++ let session = open_ready(owner).await;+ assert_eq!(session.disposition(), OpenDisposition::Existing);+ let connected = connect_ready(session);+ let connection = connected.connection();+ assert_eq!(+ query_one_i64(&connection, "SELECT COUNT(*) FROM persistence")+ .expect("preserved row count"),+ 1+ );+ drop(connection);+ owner = connected+ .try_close()+ .expect("close preserved Turso session")+ .reset()+ .await+ .expect("delete and recreate complete pair");+ assert!(REGISTRY.with(|registry| {+ registry+ .borrow_mut()+ .machine+ .preserve(stale_owner, valid_token)+ .is_err()+ }));+ assert_eq!(+ REGISTRY.with(|registry| registry.borrow().machine.phase_label()),+ "idle"+ );++ let stale_io = OpfsIo {+ owner: stale_owner,+ session: stale_session,+ references: Arc::new(SessionReferences),+ last_monotonic_nanos: AtomicU64::new(0),+ };+ assert!(+ stale_io+ .open_file(&database_name, OpenFlags::Create, true)+ .is_err()+ );+ assert_eq!(+ REGISTRY.with(|registry| registry.borrow().machine.phase_label()),+ "idle"+ );++ let session = open_ready(owner).await;+ assert_eq!(session.disposition(), OpenDisposition::Fresh);+ {+ let io = session.io.clone();+ let main = io+ .open_file(&database_name, OpenFlags::Create, true)+ .expect("recreated main");+ let wal = io+ .open_file(&wal_name, OpenFlags::Create, false)+ .expect("recreated WAL");+ assert_eq!(main.size().expect("recreated main is empty"), 0);+ assert_eq!(wal.size().expect("recreated WAL is empty"), 0);+ }+ let connected = connect_ready(session);+ let closed = connected.try_close().expect("close recreated pair");+ owner = closed.preserve().expect("preserve recreated pair");+ let lock_name = owner.lock_name().to_owned();+ owner+ .release()+ .await+ .expect("prove physical Web Lock release");+ assert!(web_lock_available(&lock_name).await);+ clean_pair(&database_name).await;++ // Recovery wipe recursively resolves a pre-open directory conflict while+ // the bound owner lock is physically held.+ let recovery_db = format!("wp05-recovery-{nonce}.db");+ let root = worker_root().await.expect("recovery root");+ let directory_options = FileSystemGetDirectoryOptions::new();+ directory_options.set_create(true);+ let conflict =+ JsFuture::from(root.get_directory_handle_with_options(&recovery_db, &directory_options))+ .await+ .expect("conflicting main directory")+ .dyn_into::<FileSystemDirectoryHandle>()+ .expect("directory conflict type");+ let child_options = FileSystemGetFileOptions::new();+ child_options.set_create(true);+ JsFuture::from(conflict.get_file_handle_with_options("child", &child_options))+ .await+ .expect("non-empty conflict");+ owner = OpfsOwner::acquire(&recovery_db)+ .await+ .expect("recovery owner");+ owner = owner+ .recovery_wipe()+ .await+ .expect("owner-bound pre-open recovery wipe");+ let connected = connect_ready(open_ready(owner).await);+ owner = connected+ .try_close()+ .expect("close recovery pair")+ .preserve()+ .expect("preserve recovery pair");+ owner.release().await.expect("release recovery lock");+ clean_pair(&recovery_db).await;++ // Cancellation after start_reset enters Resetting and the armed future+ // guard poisons on drop.+ let cancel_db = format!("wp05-cancel-{nonce}.db");+ let closed = fresh_closed(&cancel_db).await;+ let mut reset = Box::pin(closed.reset());+ assert!(matches!(poll_once(reset.as_mut()), Poll::Pending));+ assert_eq!(+ REGISTRY.with(|registry| registry.borrow().machine.phase_label()),+ "resetting"+ );+ drop(reset);+ assert_poisoned();+ replace_poisoned_registry_for_test().await;+ clean_pair(&cancel_db).await;++ for (suffix, fault, expected_kind) in [+ (+ "remove",+ ResetFault::AfterMainRemoval,+ OpfsErrorKind::Remove,+ ),+ (+ "recreate",+ ResetFault::AfterMainRecreate,+ OpfsErrorKind::Recreate,+ ),+ ] {+ let db = format!("wp05-{suffix}-{nonce}.db");+ let closed = fresh_closed(&db).await;+ REGISTRY.with(|registry| registry.borrow_mut().faults.reset_fault = Some(fault));+ let failure = closed+ .reset()+ .await+ .expect_err("partial reset failure must poison");+ assert_eq!(failure.error().kind(), expected_kind);+ assert_poisoned();+ replace_poisoned_registry_for_test().await;+ clean_pair(&db).await;+ }++ // Adapter-driven Connection::close failure is consuming and poison-only.+ let close_fail_db = format!("wp05-close-fail-{nonce}.db");+ let owner = OpfsOwner::acquire(&close_fail_db)+ .await+ .expect("close-failure owner")+ .recovery_wipe()+ .await+ .expect("close-failure wipe");+ let connected = connect_ready(open_ready(owner).await);+ REGISTRY.with(|registry| registry.borrow_mut().faults.fail_connection_close = true);+ let failure = connected+ .try_close()+ .expect_err("injected Turso close failure");+ assert_eq!(failure.error().kind(), OpfsErrorKind::Turso);+ assert!(failure.into_session().is_none());+ assert_poisoned();+ replace_poisoned_registry_for_test().await;+ clean_pair(&close_fail_db).await;++ // Pinned Turso marks a connection closed before shutdown checkpoint can+ // fail. A faithful out-of-band marked-then-error sequence must therefore+ // never be accepted later as a healthy adapter-driven close.+ let out_of_band_db = format!("wp05-out-of-band-close-{nonce}.db");+ let owner = OpfsOwner::acquire(&out_of_band_db)+ .await+ .expect("out-of-band owner")+ .recovery_wipe()+ .await+ .expect("out-of-band wipe");+ let connected = connect_ready(open_ready(owner).await);+ let connection = connected.connection();+ assert!(inject_out_of_band_marked_close_failure(&connection).is_err());+ assert!(connection.is_closed());+ drop(connection);+ let failure = connected+ .try_close()+ .expect_err("already-closed connection must poison");+ assert_eq!(failure.error().kind(), OpfsErrorKind::Turso);+ assert!(failure.into_session().is_none());+ assert_poisoned();+ replace_poisoned_registry_for_test().await;+ clean_pair(&out_of_band_db).await;++ // Open/storage failures preserve storage-full classification but never+ // return a reusable ready session. Recovery is replacement + canonical+ // lock reacquisition + wipe-before-open.+ let storage_fail_db = format!("wp05-storage-fail-{nonce}.db");+ let owner = OpfsOwner::acquire(&storage_fail_db)+ .await+ .expect("storage-failure owner")+ .recovery_wipe()+ .await+ .expect("storage-failure wipe");+ let session = open_ready(owner).await;+ REGISTRY.with(|registry| {+ registry.borrow_mut().faults.database_open_error = Some(CompletionError::IOError(+ ErrorKind::StorageFull,+ "injected database storage recovery",+ ));+ });+ let failure = session+ .connect()+ .expect_err("database open/storage failure must poison");+ assert_eq!(failure.error().kind(), OpfsErrorKind::StorageFull);+ assert_poisoned();+ replace_poisoned_registry_for_test().await;+ let owner = OpfsOwner::acquire(&storage_fail_db)+ .await+ .expect("replacement storage owner")+ .recovery_wipe()+ .await+ .expect("replacement recovery wipe");+ let connected = connect_ready(open_ready(owner).await);+ let owner = connected+ .try_close()+ .expect("replacement closes cleanly")+ .preserve()+ .expect("replacement preserve");+ owner.release().await.expect("release replacement lock");+ clean_pair(&storage_fail_db).await;++ let connect_fail_db = format!("wp05-connect-fail-{nonce}.db");+ let owner = OpfsOwner::acquire(&connect_fail_db)+ .await+ .expect("connect-failure owner")+ .recovery_wipe()+ .await+ .expect("connect-failure wipe");+ let session = open_ready(owner).await;+ REGISTRY.with(|registry| {+ registry.borrow_mut().faults.database_connect_error = Some(CompletionError::IOError(+ ErrorKind::Other,+ "injected database connect failure",+ ));+ });+ let failure = session+ .connect()+ .expect_err("database connect failure must poison");+ assert_eq!(failure.error().kind(), OpfsErrorKind::Turso);+ assert_poisoned();+ replace_poisoned_registry_for_test().await;+ clean_pair(&connect_fail_db).await;++ // Omitting the consuming close transition poisons on drop.+ let omit_db = format!("wp05-omit-close-{nonce}.db");+ let owner = OpfsOwner::acquire(&omit_db)+ .await+ .expect("omitted-close owner")+ .recovery_wipe()+ .await+ .expect("omitted-close wipe");+ drop(connect_ready(open_ready(owner).await));+ assert_poisoned();+ replace_poisoned_registry_for_test().await;+ clean_pair(&omit_db).await;++ let incomplete_drop_db = format!("wp05-incomplete-drop-{nonce}.db");+ let root = worker_root().await.expect("incomplete-drop root");+ let create = FileSystemGetFileOptions::new();+ create.set_create(true);+ JsFuture::from(root.get_file_handle_with_options(&incomplete_drop_db, &create))+ .await+ .expect("create one-sided main path");+ let owner = OpfsOwner::acquire(&incomplete_drop_db)+ .await+ .expect("incomplete-drop owner");+ let incomplete = match owner.open().await.expect("one-sided open") {+ OpenResult::ResetRequired(incomplete) => incomplete,+ OpenResult::Ready(_) => panic!("one-sided drop probe must be reset-only"),+ };+ drop(incomplete);+ assert_poisoned();+ replace_poisoned_registry_for_test().await;+ clean_pair(&incomplete_drop_db).await;++ // Browser-invalid state for a registered active handle is an ownership+ // invariant failure: ErrorKind::Other plus poison, never WouldBlock.+ let invalid_db = format!("wp05-invalid-handle-{nonce}.db");+ let owner = OpfsOwner::acquire(&invalid_db)+ .await+ .expect("invalid-handle owner")+ .recovery_wipe()+ .await+ .expect("invalid-handle wipe");+ let session = open_ready(owner).await;+ let io = session.io.clone();+ let main = io+ .open_file(&invalid_db, OpenFlags::Create, true)+ .expect("registered main before invalidation");+ let registered_main = REGISTRY.with(|registry| {+ registry+ .borrow()+ .handles+ .values()+ .find(|entry| entry.role == FileRole::Main)+ .expect("registered main handle")+ .handle+ .clone()+ });+ close_sync_handle(®istered_main).expect("externally invalidate active handle in test");+ let error = main.size().expect_err("invalid active handle must fail");+ assert!(matches!(+ error,+ LimboError::CompletionError(CompletionError::IOError(ErrorKind::Other, _))+ ));+ assert_poisoned();+ drop((main, io, session));+ replace_poisoned_registry_for_test().await;+ clean_pair(&invalid_db).await;++ // Armed owner and close-token drops also poison and begin lock release.+ let owner_drop_db = format!("wp05-owner-drop-{nonce}.db");+ drop(+ OpfsOwner::acquire(&owner_drop_db)+ .await+ .expect("owner drop capability"),+ );+ assert_poisoned();+ replace_poisoned_registry_for_test().await;++ let token_drop_db = format!("wp05-token-drop-{nonce}.db");+ drop(fresh_closed(&token_drop_db).await);+ assert_poisoned();+ replace_poisoned_registry_for_test().await;+ clean_pair(&token_drop_db).await;++ // Uncertain partial-open and handle-close cleanup retain no reusable type.+ let uncertain_open_db = format!("wp05-open-poison-{nonce}.db");+ let owner = OpfsOwner::acquire(&uncertain_open_db)+ .await+ .expect("uncertain-open owner");+ REGISTRY.with(|registry| {+ let mut registry = registry.borrow_mut();+ registry.faults.fail_open = Some(FileRole::Wal);+ registry.faults.fail_close = Some(FileRole::Main);+ });+ let failure = owner+ .open()+ .await+ .expect_err("uncertain partial-open cleanup");+ assert_eq!(failure.error().kind(), OpfsErrorKind::Poisoned);+ assert!(failure.into_owner().is_none());+ assert_poisoned();+ replace_poisoned_registry_for_test().await;+ clean_pair(&uncertain_open_db).await;++ let uncertain_close_db = format!("wp05-handle-close-{nonce}.db");+ let owner = OpfsOwner::acquire(&uncertain_close_db)+ .await+ .expect("uncertain-handle-close owner")+ .recovery_wipe()+ .await+ .expect("uncertain-handle-close wipe");+ let connected = connect_ready(open_ready(owner).await);+ REGISTRY.with(|registry| registry.borrow_mut().faults.fail_close = Some(FileRole::Wal));+ let failure = connected+ .try_close()+ .expect_err("uncertain sync handle close");+ assert_eq!(failure.error().kind(), OpfsErrorKind::Close);+ assert!(failure.into_session().is_none());+ assert_poisoned();+ replace_poisoned_registry_for_test().await;+ clean_pair(&uncertain_close_db).await;+}diff --git a/crates/client/turso-opfs/src/lib.rs b/crates/client/turso-opfs/src/lib.rsnew file mode 100644index 0000000000..dc67c7cb8c--- /dev/null+++ b/crates/client/turso-opfs/src/lib.rs@@ -0,0 +1,30 @@+//! Browser-only Turso I/O over worker-owned Origin Private File System files.+//!+//! The production implementation exists only on `wasm32` DedicatedWorkers.+//! [`OpfsOwner::acquire`] derives and physically holds an exclusive Web Lock+//! and main/WAL paths from one canonical database identity. JavaScript lock and OPFS handles remain in+//! worker-local storage; Turso sees only checked numeric IDs.+//!+//! Opening is typed: a one-sided main/WAL pair becomes+//! [`ResetRequiredSession`] and cannot expose I/O. A complete [`OpfsSession`]+//! creates exactly one production Turso connection. Closing is consuming and+//! adapter-driven: [`ConnectedOpfsSession::try_close`] requires sole connection+//! ownership, calls `Connection::close`, proves success, drops Turso resources,+//! checks all references, and only then closes OPFS handles. [`ClosedSession`]+//! is a one-use choice between preservation and asynchronous physical reset.++#![deny(missing_docs)]+#![forbid(unsafe_code)]++#[cfg(any(test, target_arch = "wasm32"))]+mod state;++#[cfg(target_arch = "wasm32")]+mod browser;++#[cfg(target_arch = "wasm32")]+pub use browser::{+ CloseFailure, ClosedSession, ConnectFailure, ConnectedOpfsSession, OpenDisposition,+ OpenFailure, OpenResult, OpfsError, OpfsErrorKind, OpfsOwner, OpfsSession, ResetFailure,+ ResetRequiredSession, WipeFailure,+};diff --git a/crates/client/turso-opfs/src/state.rs b/crates/client/turso-opfs/src/state.rsnew file mode 100644index 0000000000..451f24fd55--- /dev/null+++ b/crates/client/turso-opfs/src/state.rs@@ -0,0 +1,834 @@+//! Target-independent consuming lifecycle for the worker-local adapter.++use std::fmt;++#[cfg(test)]+mod test;++#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]+pub(crate) struct OwnerId(u64);++#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]+pub(crate) struct SessionId(u64);++#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]+pub(crate) struct HandleId(u64);++#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]+pub(crate) struct CloseToken(u64);++impl OwnerId {+ #[cfg(test)]+ pub(crate) fn get(self) -> u64 {+ self.0+ }+}++impl SessionId {+ #[cfg(test)]+ pub(crate) fn get(self) -> u64 {+ self.0+ }+}++impl HandleId {+ #[cfg(test)]+ pub(crate) fn get(self) -> u64 {+ self.0+ }+}++impl CloseToken {+ #[cfg(test)]+ pub(crate) fn get(self) -> u64 {+ self.0+ }++ #[cfg(test)]+ pub(crate) fn from_raw(value: u64) -> Self {+ Self(value)+ }+}++#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]+pub(crate) enum FileRole {+ Main,+ Wal,+}++impl FileRole {+ pub(crate) const ALL: [Self; 2] = [Self::Main, Self::Wal];++ pub(crate) const fn index(self) -> usize {+ match self {+ Self::Main => 0,+ Self::Wal => 1,+ }+ }+}++#[derive(Clone, Debug, PartialEq, Eq)]+pub(crate) struct Paths {+ main: String,+ wal: String,+}++impl Paths {+ pub(crate) fn new(main: String, wal: String) -> Self {+ Self { main, wal }+ }++ pub(crate) fn get(&self, role: FileRole) -> &str {+ match role {+ FileRole::Main => &self.main,+ FileRole::Wal => &self.wal,+ }+ }++ pub(crate) fn role_for(&self, path: &str) -> Option<FileRole> {+ FileRole::ALL+ .into_iter()+ .find(|role| self.get(*role) == path)+ }+}++#[derive(Clone, Copy, Debug, PartialEq, Eq)]+pub(crate) enum StateErrorKind {+ Ownership,+ Session,+ Reentrant,+ ActiveReferences,+ Path,+ Flags,+ Registration,+ Token,+ Exhausted,+ Poisoned,+}++#[derive(Clone, Copy, Debug, PartialEq, Eq)]+pub(crate) struct StateError {+ pub(crate) kind: StateErrorKind,+ pub(crate) message: &'static str,+}++impl StateError {+ const fn new(kind: StateErrorKind, message: &'static str) -> Self {+ Self { kind, message }+ }+}++impl fmt::Display for StateError {+ fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {+ formatter.write_str(self.message)+ }+}++#[derive(Clone, Copy, Debug, PartialEq, Eq)]+pub(crate) enum ActiveKind {+ Ready,+ Connected,+ ConnectionClosed,+ ResetOnly,+}++#[derive(Clone, Debug, PartialEq, Eq)]+enum Phase {+ Unowned,+ Idle {+ owner: OwnerId,+ },+ Opening {+ owner: OwnerId,+ session: SessionId,+ paths: Paths,+ handles: [Option<HandleId>; 2],+ },+ Active {+ owner: OwnerId,+ session: SessionId,+ paths: Paths,+ handles: [HandleId; 2],+ kind: ActiveKind,+ operation_active: bool,+ },+ Closing {+ owner: OwnerId,+ session: SessionId,+ paths: Paths,+ },+ Closed {+ owner: OwnerId,+ token: CloseToken,+ paths: Paths,+ },+ Resetting {+ owner: OwnerId,+ token: CloseToken,+ paths: Paths,+ },+ Wiping {+ owner: OwnerId,+ paths: Paths,+ },+ Poisoned {+ owner: OwnerId,+ reason: String,+ },+}++#[derive(Debug)]+pub(crate) struct Machine {+ next_owner: u64,+ next_session: u64,+ next_handle: u64,+ next_close_token: u64,+ phase: Phase,+}++impl Default for Machine {+ fn default() -> Self {+ Self {+ next_owner: 0,+ next_session: 0,+ next_handle: 0,+ next_close_token: 0,+ phase: Phase::Unowned,+ }+ }+}++impl Machine {+ pub(crate) fn claim_owner(&mut self) -> Result<OwnerId, StateError> {+ if matches!(self.phase, Phase::Poisoned { .. }) {+ return Err(poisoned());+ }+ if self.phase != Phase::Unowned {+ return Err(StateError::new(+ StateErrorKind::Ownership,+ "worker-local OPFS registry already has an owner",+ ));+ }+ self.next_owner = next_id(self.next_owner, "owner ID space exhausted")?;+ let owner = OwnerId(self.next_owner);+ self.phase = Phase::Idle { owner };+ Ok(owner)+ }++ pub(crate) fn release_owner(&mut self, owner: OwnerId) -> Result<(), StateError> {+ match self.phase {+ Phase::Idle { owner: current } if current == owner => {+ self.phase = Phase::Unowned;+ Ok(())+ }+ Phase::Poisoned { .. } => Err(poisoned()),+ _ => Err(StateError::new(+ StateErrorKind::Ownership,+ "owner release requires the matching idle owner",+ )),+ }+ }++ pub(crate) fn start_open(+ &mut self,+ owner: OwnerId,+ paths: Paths,+ ) -> Result<SessionId, StateError> {+ match self.phase {+ Phase::Idle { owner: current } if current == owner => {}+ Phase::Poisoned { .. } => return Err(poisoned()),+ _ => {+ return Err(StateError::new(+ StateErrorKind::Ownership,+ "session open requires the matching idle owner",+ ));+ }+ }+ self.next_session = next_id(self.next_session, "session ID space exhausted")?;+ let session = SessionId(self.next_session);+ self.phase = Phase::Opening {+ owner,+ session,+ paths,+ handles: [None, None],+ };+ Ok(session)+ }++ pub(crate) fn register(+ &mut self,+ owner: OwnerId,+ session: SessionId,+ role: FileRole,+ ) -> Result<HandleId, StateError> {+ let handles = match &mut self.phase {+ Phase::Opening {+ owner: current_owner,+ session: current_session,+ handles,+ ..+ } if *current_owner == owner && *current_session == session => handles,+ Phase::Poisoned { .. } => return Err(poisoned()),+ _ => {+ return Err(StateError::new(+ StateErrorKind::Session,+ "handle registration does not match the opening session",+ ));+ }+ };+ if handles[role.index()].is_some() {+ return Err(StateError::new(+ StateErrorKind::Registration,+ "an approved path was registered twice",+ ));+ }+ self.next_handle = next_id(self.next_handle, "handle ID space exhausted")?;+ let handle = HandleId(self.next_handle);+ handles[role.index()] = Some(handle);+ Ok(handle)+ }++ pub(crate) fn activate(+ &mut self,+ owner: OwnerId,+ session: SessionId,+ reset_only: bool,+ ) -> Result<Paths, StateError> {+ let (paths, handles) = match &self.phase {+ Phase::Opening {+ owner: current_owner,+ session: current_session,+ paths,+ handles: [Some(main), Some(wal)],+ } if *current_owner == owner && *current_session == session => {+ (paths.clone(), [*main, *wal])+ }+ Phase::Opening { .. } => {+ return Err(StateError::new(+ StateErrorKind::Registration,+ "activation requires both approved paths",+ ));+ }+ Phase::Poisoned { .. } => return Err(poisoned()),+ _ => {+ return Err(StateError::new(+ StateErrorKind::Session,+ "activation does not match the opening session",+ ));+ }+ };+ self.phase = Phase::Active {+ owner,+ session,+ paths: paths.clone(),+ handles,+ kind: if reset_only {+ ActiveKind::ResetOnly+ } else {+ ActiveKind::Ready+ },+ operation_active: false,+ };+ Ok(paths)+ }++ pub(crate) fn bind_connection(+ &mut self,+ owner: OwnerId,+ session: SessionId,+ ) -> Result<(), StateError> {+ match &mut self.phase {+ Phase::Active {+ owner: current_owner,+ session: current_session,+ kind,+ operation_active: false,+ ..+ } if *current_owner == owner+ && *current_session == session+ && *kind == ActiveKind::Ready =>+ {+ *kind = ActiveKind::Connected;+ Ok(())+ }+ Phase::Poisoned { .. } => Err(poisoned()),+ _ => Err(StateError::new(+ StateErrorKind::Session,+ "connection binding requires the matching ready session",+ )),+ }+ }++ pub(crate) fn record_connection_close(+ &mut self,+ owner: OwnerId,+ session: SessionId,+ ) -> Result<(), StateError> {+ match &mut self.phase {+ Phase::Active {+ owner: current_owner,+ session: current_session,+ kind,+ operation_active: false,+ ..+ } if *current_owner == owner+ && *current_session == session+ && *kind == ActiveKind::Connected =>+ {+ *kind = ActiveKind::ConnectionClosed;+ Ok(())+ }+ Phase::Poisoned { .. } => Err(poisoned()),+ _ => Err(StateError::new(+ StateErrorKind::ActiveReferences,+ "connection close proof requires the matching connected session",+ )),+ }+ }++ pub(crate) fn abort_open(+ &mut self,+ owner: OwnerId,+ session: SessionId,+ cleanup_certain: bool,+ reason: String,+ ) -> Result<(), StateError> {+ match self.phase {+ Phase::Opening {+ owner: current_owner,+ session: current_session,+ ..+ } if current_owner == owner && current_session == session => {}+ Phase::Poisoned { .. } => return Err(poisoned()),+ _ => {+ return Err(StateError::new(+ StateErrorKind::Session,+ "opening cleanup does not match the opening session",+ ));+ }+ }+ self.phase = if cleanup_certain {+ Phase::Idle { owner }+ } else {+ Phase::Poisoned { owner, reason }+ };+ Ok(())+ }++ pub(crate) fn validate_session(+ &self,+ owner: OwnerId,+ session: SessionId,+ ) -> Result<(), StateError> {+ match self.phase {+ Phase::Active {+ owner: current_owner,+ session: current_session,+ kind: ActiveKind::Ready | ActiveKind::Connected,+ ..+ } if current_owner == owner && current_session == session => Ok(()),+ Phase::Poisoned { .. } => Err(poisoned()),+ _ => Err(StateError::new(+ StateErrorKind::Session,+ "stale or mismatched owner/session ID",+ )),+ }+ }++ pub(crate) fn validate_open(+ &self,+ owner: OwnerId,+ session: SessionId,+ path: &str,+ read_only: bool,+ no_lock: bool,+ direct: bool,+ ) -> Result<HandleId, StateError> {+ let (paths, handles) = match &self.phase {+ Phase::Active {+ owner: current_owner,+ session: current_session,+ paths,+ handles,+ kind: ActiveKind::Ready | ActiveKind::Connected,+ ..+ } if *current_owner == owner && *current_session == session => (paths, handles),+ Phase::Poisoned { .. } => return Err(poisoned()),+ _ => {+ return Err(StateError::new(+ StateErrorKind::Session,+ "open_file used a stale or mismatched session",+ ));+ }+ };+ let role = paths.role_for(path).ok_or_else(|| {+ StateError::new(+ StateErrorKind::Path,+ "open_file path was not pre-registered",+ )+ })?;+ if read_only {+ return Err(StateError::new(+ StateErrorKind::Flags,+ "read-only open is not approved for the writable cache session",+ ));+ }+ let expected_direct = role == FileRole::Main;+ if direct != expected_direct {+ return Err(StateError::new(+ StateErrorKind::Flags,+ "open_file direct mode does not match the approved main/WAL mode",+ ));+ }+ if no_lock && role != FileRole::Wal {+ return Err(StateError::new(+ StateErrorKind::Flags,+ "NoLock is approved only for the WAL path",+ ));+ }+ Ok(handles[role.index()])+ }++ pub(crate) fn validate_path(+ &self,+ owner: OwnerId,+ session: SessionId,+ path: &str,+ ) -> Result<(), StateError> {+ let paths = match &self.phase {+ Phase::Active {+ owner: current_owner,+ session: current_session,+ paths,+ kind: ActiveKind::Ready | ActiveKind::Connected,+ ..+ } if *current_owner == owner && *current_session == session => paths,+ Phase::Poisoned { .. } => return Err(poisoned()),+ _ => {+ return Err(StateError::new(+ StateErrorKind::Session,+ "path lookup used a stale or mismatched session",+ ));+ }+ };+ if paths.role_for(path).is_some() {+ Ok(())+ } else {+ Err(StateError::new(+ StateErrorKind::Path,+ "path was not pre-registered",+ ))+ }+ }++ pub(crate) fn begin_operation(+ &mut self,+ owner: OwnerId,+ session: SessionId,+ ) -> Result<(), StateError> {+ match &mut self.phase {+ Phase::Active {+ owner: current_owner,+ session: current_session,+ kind: ActiveKind::Ready | ActiveKind::Connected,+ operation_active,+ ..+ } if *current_owner == owner && *current_session == session => {+ if *operation_active {+ return Err(StateError::new(+ StateErrorKind::Reentrant,+ "reentrant OPFS operation rejected",+ ));+ }+ *operation_active = true;+ Ok(())+ }+ Phase::Poisoned { .. } => Err(poisoned()),+ _ => Err(StateError::new(+ StateErrorKind::Session,+ "operation used a stale or mismatched session",+ )),+ }+ }++ pub(crate) fn end_operation(&mut self, owner: OwnerId, session: SessionId) {+ if let Phase::Active {+ owner: current_owner,+ session: current_session,+ operation_active,+ ..+ } = &mut self.phase+ && *current_owner == owner+ && *current_session == session+ {+ *operation_active = false;+ }+ }++ pub(crate) fn start_close(+ &mut self,+ owner: OwnerId,+ session: SessionId,+ ) -> Result<[HandleId; 2], StateError> {+ self.start_close_with_kind(owner, session, ActiveKind::ConnectionClosed)+ }++ pub(crate) fn start_reset_only_close(+ &mut self,+ owner: OwnerId,+ session: SessionId,+ ) -> Result<[HandleId; 2], StateError> {+ self.start_close_with_kind(owner, session, ActiveKind::ResetOnly)+ }++ fn start_close_with_kind(+ &mut self,+ owner: OwnerId,+ session: SessionId,+ required_kind: ActiveKind,+ ) -> Result<[HandleId; 2], StateError> {+ let (paths, handles) = match &self.phase {+ Phase::Active {+ owner: current_owner,+ session: current_session,+ paths,+ handles,+ kind,+ operation_active: false,+ } if *current_owner == owner+ && *current_session == session+ && *kind == required_kind =>+ {+ (paths.clone(), *handles)+ }+ Phase::Active {+ owner: current_owner,+ session: current_session,+ operation_active: true,+ ..+ } if *current_owner == owner && *current_session == session => {+ return Err(StateError::new(+ StateErrorKind::ActiveReferences,+ "cannot close while an OPFS operation is active",+ ));+ }+ Phase::Active {+ owner: current_owner,+ session: current_session,+ ..+ } if *current_owner == owner && *current_session == session => {+ return Err(StateError::new(+ StateErrorKind::ActiveReferences,+ "close requires the matching connection-close or reset-only proof",+ ));+ }+ Phase::Poisoned { .. } => return Err(poisoned()),+ _ => {+ return Err(StateError::new(+ StateErrorKind::Session,+ "close used a stale or mismatched session",+ ));+ }+ };+ self.phase = Phase::Closing {+ owner,+ session,+ paths: paths.clone(),+ };+ Ok(handles)+ }++ pub(crate) fn finish_close(+ &mut self,+ owner: OwnerId,+ session: SessionId,+ ) -> Result<CloseToken, StateError> {+ let paths = match &self.phase {+ Phase::Closing {+ owner: current_owner,+ session: current_session,+ paths,+ } if *current_owner == owner && *current_session == session => paths.clone(),+ Phase::Poisoned { .. } => return Err(poisoned()),+ _ => {+ return Err(StateError::new(+ StateErrorKind::Session,+ "close completion did not match the closing session",+ ));+ }+ };+ self.next_close_token = next_id(self.next_close_token, "close token space exhausted")?;+ let token = CloseToken(self.next_close_token);+ self.phase = Phase::Closed {+ owner,+ token,+ paths,+ };+ Ok(token)+ }++ pub(crate) fn preserve(&mut self, owner: OwnerId, token: CloseToken) -> Result<(), StateError> {+ match self.phase {+ Phase::Closed {+ owner: current_owner,+ token: current_token,+ ..+ } if current_owner == owner && current_token == token => {+ self.phase = Phase::Idle { owner };+ Ok(())+ }+ Phase::Poisoned { .. } => Err(poisoned()),+ _ => Err(StateError::new(+ StateErrorKind::Token,+ "preserve requires the matching one-use close token",+ )),+ }+ }++ pub(crate) fn start_reset(+ &mut self,+ owner: OwnerId,+ token: CloseToken,+ ) -> Result<Paths, StateError> {+ let paths = match &self.phase {+ Phase::Closed {+ owner: current_owner,+ token: current_token,+ paths,+ } if *current_owner == owner && *current_token == token => paths.clone(),+ Phase::Poisoned { .. } => return Err(poisoned()),+ _ => {+ return Err(StateError::new(+ StateErrorKind::Token,+ "reset requires the matching one-use close token",+ ));+ }+ };+ self.phase = Phase::Resetting {+ owner,+ token,+ paths: paths.clone(),+ };+ Ok(paths)+ }++ pub(crate) fn finish_reset(+ &mut self,+ owner: OwnerId,+ token: CloseToken,+ ) -> Result<(), StateError> {+ match self.phase {+ Phase::Resetting {+ owner: current_owner,+ token: current_token,+ ..+ } if current_owner == owner && current_token == token => {+ self.phase = Phase::Idle { owner };+ Ok(())+ }+ Phase::Poisoned { .. } => Err(poisoned()),+ _ => Err(StateError::new(+ StateErrorKind::Token,+ "reset completion did not match the consumed close token",+ )),+ }+ }++ pub(crate) fn start_wipe(&mut self, owner: OwnerId, paths: Paths) -> Result<(), StateError> {+ match self.phase {+ Phase::Idle { owner: current } if current == owner => {+ self.phase = Phase::Wiping { owner, paths };+ Ok(())+ }+ Phase::Poisoned { .. } => Err(poisoned()),+ _ => Err(StateError::new(+ StateErrorKind::Ownership,+ "recovery wipe requires the matching idle owner",+ )),+ }+ }++ pub(crate) fn finish_wipe(&mut self, owner: OwnerId) -> Result<(), StateError> {+ match self.phase {+ Phase::Wiping { owner: current, .. } if current == owner => {+ self.phase = Phase::Idle { owner };+ Ok(())+ }+ Phase::Poisoned { .. } => Err(poisoned()),+ _ => Err(StateError::new(+ StateErrorKind::Ownership,+ "recovery wipe completion requires the matching wiping owner",+ )),+ }+ }++ pub(crate) fn poison(&mut self, owner: OwnerId, reason: String) -> Result<(), StateError> {+ if matches!(self.phase, Phase::Poisoned { owner: current, .. } if current == owner) {+ return Ok(());+ }+ let current_owner = match self.phase {+ Phase::Unowned => None,+ Phase::Idle { owner }+ | Phase::Opening { owner, .. }+ | Phase::Active { owner, .. }+ | Phase::Closing { owner, .. }+ | Phase::Closed { owner, .. }+ | Phase::Resetting { owner, .. }+ | Phase::Wiping { owner, .. }+ | Phase::Poisoned { owner, .. } => Some(owner),+ };+ if current_owner != Some(owner) {+ return Err(StateError::new(+ StateErrorKind::Ownership,+ "stale owner cannot poison the current OPFS lifecycle",+ ));+ }+ self.phase = Phase::Poisoned { owner, reason };+ Ok(())+ }++ pub(crate) fn is_idle_owner(&self, owner: OwnerId) -> bool {+ matches!(self.phase, Phase::Idle { owner: current } if current == owner)+ }++ #[cfg(test)]+ pub(crate) fn phase_label(&self) -> &'static str {+ match self.phase {+ Phase::Unowned => "unowned",+ Phase::Idle { .. } => "idle",+ Phase::Opening { .. } => "opening",+ Phase::Active { .. } => "active",+ Phase::Closing { .. } => "closing",+ Phase::Closed { .. } => "closed",+ Phase::Resetting { .. } => "resetting",+ Phase::Wiping { .. } => "wiping",+ Phase::Poisoned { .. } => "poisoned",+ }+ }++ #[cfg(all(test, target_arch = "wasm32"))]+ pub(crate) fn is_poisoned(&self) -> bool {+ matches!(self.phase, Phase::Poisoned { .. })+ }++ #[cfg(test)]+ pub(crate) fn poison_reason(&self) -> Option<&str> {+ match &self.phase {+ Phase::Poisoned { reason, .. } => Some(reason),+ _ => None,+ }+ }+}++fn next_id(value: u64, message: &'static str) -> Result<u64, StateError> {+ value+ .checked_add(1)+ .ok_or_else(|| StateError::new(StateErrorKind::Exhausted, message))+}++fn poisoned() -> StateError {+ StateError::new(+ StateErrorKind::Poisoned,+ "worker-local OPFS session is poisoned",+ )+}diff --git a/crates/client/turso-opfs/src/state/test.rs b/crates/client/turso-opfs/src/state/test.rsnew file mode 100644index 0000000000..2a8a8bd001--- /dev/null+++ b/crates/client/turso-opfs/src/state/test.rs@@ -0,0 +1,323 @@+use super::*;++fn paths() -> Paths {+ Paths::new("cache.db".into(), "cache.db-wal".into())+}++fn active_machine() -> (Machine, OwnerId, SessionId, [HandleId; 2]) {+ let mut machine = Machine::default();+ let owner = machine.claim_owner().unwrap();+ let session = machine.start_open(owner, paths()).unwrap();+ let main = machine.register(owner, session, FileRole::Main).unwrap();+ let wal = machine.register(owner, session, FileRole::Wal).unwrap();+ machine.activate(owner, session, false).unwrap();+ (machine, owner, session, [main, wal])+}++fn closed_machine() -> (Machine, OwnerId, CloseToken) {+ let (mut machine, owner, session, _) = active_machine();+ machine.bind_connection(owner, session).unwrap();+ machine.record_connection_close(owner, session).unwrap();+ machine.start_close(owner, session).unwrap();+ let token = machine.finish_close(owner, session).unwrap();+ (machine, owner, token)+}++#[test]+fn numeric_trait_tokens_are_send_sync_and_pointer_free() {+ fn assert_send_sync<T: Send + Sync>() {}+ assert_send_sync::<OwnerId>();+ assert_send_sync::<SessionId>();+ assert_send_sync::<HandleId>();+ assert_send_sync::<CloseToken>();+ assert_eq!(std::mem::size_of::<OwnerId>(), std::mem::size_of::<u64>());+ assert_eq!(std::mem::size_of::<SessionId>(), std::mem::size_of::<u64>());+ assert_eq!(std::mem::size_of::<HandleId>(), std::mem::size_of::<u64>());+ assert_eq!(+ std::mem::size_of::<CloseToken>(),+ std::mem::size_of::<u64>()+ );+}++#[test]+fn one_owner_and_matching_idle_release_are_required() {+ let mut machine = Machine::default();+ let owner = machine.claim_owner().unwrap();+ assert_eq!(owner.get(), 1);+ assert!(machine.is_idle_owner(owner));+ assert_eq!(+ machine.claim_owner().unwrap_err().kind,+ StateErrorKind::Ownership+ );+ assert_eq!(+ machine+ .release_owner(OwnerId(owner.get() + 1))+ .unwrap_err()+ .kind,+ StateErrorKind::Ownership+ );+ assert_eq!(machine.phase_label(), "idle");+ machine.release_owner(owner).unwrap();+ assert_eq!(machine.phase_label(), "unowned");+ assert_eq!(machine.claim_owner().unwrap().get(), 2);+}++#[test]+fn opening_requires_exactly_main_and_wal_once() {+ let mut machine = Machine::default();+ let owner = machine.claim_owner().unwrap();+ let session = machine.start_open(owner, paths()).unwrap();+ let main = machine.register(owner, session, FileRole::Main).unwrap();+ assert_eq!(main.get(), 1);+ assert_eq!(+ machine+ .register(owner, session, FileRole::Main)+ .unwrap_err()+ .kind,+ StateErrorKind::Registration+ );+ assert_eq!(+ machine.activate(owner, session, false).unwrap_err().kind,+ StateErrorKind::Registration+ );+ let wal = machine.register(owner, session, FileRole::Wal).unwrap();+ assert_eq!(wal.get(), 2);+ machine.activate(owner, session, false).unwrap();+ assert_eq!(machine.phase_label(), "active");+}++#[test]+fn partial_open_cleanup_returns_idle_only_when_certain() {+ let mut clean = Machine::default();+ let owner = clean.claim_owner().unwrap();+ let session = clean.start_open(owner, paths()).unwrap();+ clean.register(owner, session, FileRole::Main).unwrap();+ clean+ .abort_open(owner, session, true, "WAL open failed".into())+ .unwrap();+ assert_eq!(clean.phase_label(), "idle");+ assert!(clean.start_open(owner, paths()).is_ok());++ let mut uncertain = Machine::default();+ let owner = uncertain.claim_owner().unwrap();+ let session = uncertain.start_open(owner, paths()).unwrap();+ uncertain.register(owner, session, FileRole::Main).unwrap();+ uncertain+ .abort_open(+ owner,+ session,+ false,+ "WAL open and main close failed".into(),+ )+ .unwrap();+ assert_eq!(uncertain.phase_label(), "poisoned");+ assert_eq!(+ uncertain.start_open(owner, paths()).unwrap_err().kind,+ StateErrorKind::Poisoned+ );+ assert_eq!(+ uncertain.release_owner(owner).unwrap_err().kind,+ StateErrorKind::Poisoned+ );+}++#[test]+fn approved_main_and_wal_flags_are_enforced() {+ let (machine, owner, session, handles) = active_machine();+ machine.validate_session(owner, session).unwrap();+ machine+ .validate_path(owner, session, "cache.db-wal")+ .unwrap();+ assert_eq!(+ machine+ .validate_open(owner, session, "cache.db", false, false, true)+ .unwrap(),+ handles[0]+ );+ assert_eq!(+ machine+ .validate_open(owner, session, "cache.db-wal", false, false, false)+ .unwrap(),+ handles[1]+ );+ assert_eq!(+ machine+ .validate_open(owner, session, "cache.db-wal", false, true, false)+ .unwrap(),+ handles[1]+ );+ for error in [+ machine.validate_open(owner, session, "other.db", false, false, true),+ machine.validate_open(owner, session, "cache.db", true, false, true),+ machine.validate_open(owner, session, "cache.db", false, true, true),+ machine.validate_open(owner, session, "cache.db", false, false, false),+ machine.validate_open(owner, session, "cache.db-wal", false, false, true),+ ] {+ assert!(error.is_err());+ }+}++#[test]+fn stale_sessions_and_reentrant_operations_do_not_mutate_health() {+ let (mut machine, owner, session, _) = active_machine();+ assert_eq!(+ machine+ .poison(OwnerId(owner.get() + 1), "stale cleanup".into())+ .unwrap_err()+ .kind,+ StateErrorKind::Ownership+ );+ assert_eq!(machine.phase_label(), "active");+ assert_eq!(+ machine+ .begin_operation(owner, SessionId(session.get() + 1))+ .unwrap_err()+ .kind,+ StateErrorKind::Session+ );+ assert_eq!(machine.phase_label(), "active");+ machine.begin_operation(owner, session).unwrap();+ assert_eq!(+ machine.begin_operation(owner, session).unwrap_err().kind,+ StateErrorKind::Reentrant+ );+ assert_eq!(+ machine.start_close(owner, session).unwrap_err().kind,+ StateErrorKind::ActiveReferences+ );+ machine.end_operation(owner, session);+ assert_eq!(+ machine.start_close(owner, session).unwrap_err().kind,+ StateErrorKind::ActiveReferences+ );+ machine.bind_connection(owner, session).unwrap();+ assert_eq!(+ machine.start_close(owner, session).unwrap_err().kind,+ StateErrorKind::ActiveReferences+ );+ machine.record_connection_close(owner, session).unwrap();+ machine.start_close(owner, session).unwrap();+ assert_eq!(machine.phase_label(), "closing");+}++#[test]+fn invalid_close_tokens_never_mutate_closed_state() {+ let (mut machine, owner, token) = closed_machine();+ assert_eq!(token.get(), 1);+ assert_eq!(+ machine+ .preserve(OwnerId(owner.get() + 1), token)+ .unwrap_err()+ .kind,+ StateErrorKind::Token+ );+ assert_eq!(machine.phase_label(), "closed");+ assert_eq!(+ machine+ .start_reset(owner, CloseToken::from_raw(token.get() + 1))+ .unwrap_err()+ .kind,+ StateErrorKind::Token+ );+ assert_eq!(machine.phase_label(), "closed");+ machine.preserve(owner, token).unwrap();+ assert_eq!(machine.phase_label(), "idle");+ assert_eq!(+ machine.preserve(owner, token).unwrap_err().kind,+ StateErrorKind::Token+ );+ assert_eq!(machine.phase_label(), "idle");+}++#[test]+fn reset_consumes_token_and_returns_matching_owner_to_idle() {+ let (mut machine, owner, token) = closed_machine();+ let selected = machine.start_reset(owner, token).unwrap();+ assert_eq!(selected, paths());+ assert_eq!(machine.phase_label(), "resetting");+ assert_eq!(+ machine.start_reset(owner, token).unwrap_err().kind,+ StateErrorKind::Token+ );+ assert_eq!(machine.phase_label(), "resetting");+ machine.finish_reset(owner, token).unwrap();+ assert_eq!(machine.phase_label(), "idle");+ assert_eq!(+ machine.start_reset(owner, token).unwrap_err().kind,+ StateErrorKind::Token+ );+ assert_eq!(machine.phase_label(), "idle");+}++#[test]+fn reset_failure_poison_rejects_reopen_release_and_token_reuse() {+ let (mut machine, owner, token) = closed_machine();+ machine.start_reset(owner, token).unwrap();+ machine.poison(owner, "partial deletion".into()).unwrap();+ machine.poison(owner, "later failure".into()).unwrap();+ assert_eq!(machine.phase_label(), "poisoned");+ assert_eq!(machine.poison_reason(), Some("partial deletion"));+ assert_eq!(+ machine.finish_reset(owner, token).unwrap_err().kind,+ StateErrorKind::Poisoned+ );+ assert_eq!(+ machine.start_reset(owner, token).unwrap_err().kind,+ StateErrorKind::Poisoned+ );+ assert_eq!(+ machine.start_open(owner, paths()).unwrap_err().kind,+ StateErrorKind::Poisoned+ );+ assert_eq!(+ machine.release_owner(owner).unwrap_err().kind,+ StateErrorKind::Poisoned+ );+}++#[test]+fn incomplete_pair_is_reset_only_and_never_operational() {+ let mut machine = Machine::default();+ let owner = machine.claim_owner().unwrap();+ let session = machine.start_open(owner, paths()).unwrap();+ machine.register(owner, session, FileRole::Main).unwrap();+ machine.register(owner, session, FileRole::Wal).unwrap();+ machine.activate(owner, session, true).unwrap();+ assert_eq!(+ machine.begin_operation(owner, session).unwrap_err().kind,+ StateErrorKind::Session+ );+ assert_eq!(+ machine.bind_connection(owner, session).unwrap_err().kind,+ StateErrorKind::Session+ );+ assert_eq!(+ machine.start_close(owner, session).unwrap_err().kind,+ StateErrorKind::ActiveReferences+ );+ machine.start_reset_only_close(owner, session).unwrap();+ let token = machine.finish_close(owner, session).unwrap();+ machine.start_reset(owner, token).unwrap();+ machine.finish_reset(owner, token).unwrap();+ assert_eq!(machine.phase_label(), "idle");+}++#[test]+fn recovery_wipe_is_consuming_and_poisoned_cancellation_cannot_finish() {+ let mut machine = Machine::default();+ let owner = machine.claim_owner().unwrap();+ machine.start_wipe(owner, paths()).unwrap();+ assert_eq!(machine.phase_label(), "wiping");+ assert_eq!(+ machine.start_open(owner, paths()).unwrap_err().kind,+ StateErrorKind::Ownership+ );+ machine+ .poison(owner, "recovery future cancelled".into())+ .unwrap();+ assert_eq!(machine.phase_label(), "poisoned");+ assert_eq!(+ machine.finish_wipe(owner).unwrap_err().kind,+ StateErrorKind::Poisoned+ );+}diff --git a/deny.toml b/deny.tomlindex 2713b1325e..a802868bd6 100644--- a/deny.toml+++ b/deny.toml@@ -216,6 +216,7 @@ deny = ["tracing-panic", # External crate allowed to use tracing-subscriber"tracing-tree","tracing-web", # External WASM tracing layer+ "turso_core", # External Turso crate requires tracing-subscriber directly"worker-rs-otel", # Cloudflare/WASM OpenTelemetry integration"workspace-hack", # cargo-hakari generated crate], reason = "Use macro_entrypoint for tracing setup in workspace crates" },diff --git a/infra/stacks/web-app/index.ts b/infra/stacks/web-app/index.tsindex 5b32884f64..ee97c59d47 100644--- a/infra/stacks/web-app/index.ts+++ b/infra/stacks/web-app/index.ts@@ -63,9 +63,32 @@ const publicAccessBlock = new aws.s3.BucketPublicAccessBlock(});-const appArchive = new pulumi.asset.FileArchive(localPath);+// Stage web delivery and a native/OTA archive separately. Web delivery keeps+// the Brotli sidecar for targeted S3 upload; native clients need the raw WASM+// only, so their archive copy removes the sidecar before FileArchive snapshots it.+const buildOutputPath = './output/app';+const appArchiveOutputPath = './output/app-archive';+const cacheWasmRetentionDays = 7;+const shellQuote = (value: string): string =>+ "'" + value.replaceAll("'", "'\\''") + "'";+execSync('rm -rf ./output', { stdio: 'inherit' });+execSync(+ `mkdir -p ${shellQuote(buildOutputPath)} ${shellQuote(appArchiveOutputPath)}`,+ { stdio: 'inherit' }+);+execSync(`cp -r ${shellQuote(localPath)}/* ${shellQuote(buildOutputPath)}`, {+ stdio: 'inherit',+});+execSync(+ `cp -r ${shellQuote(localPath)}/* ${shellQuote(appArchiveOutputPath)}`,+ { stdio: 'inherit' }+);+execSync(+ `find ${shellQuote(appArchiveOutputPath)} -type f -name 'cache_wasm_bg*.wasm.br' -delete`,+ { stdio: 'inherit' }+);-// Upload the app archive to the S3 bucket+const appArchive = new pulumi.asset.FileArchive(appArchiveOutputPath);new aws.s3.BucketObjectv2('app-archive',{@@ -78,25 +101,21 @@ new aws.s3.BucketObjectv2(dependsOn: [ownershipControls, publicAccessBlock],});--// Create web-app output folder-// Remove the existing app folder-let buildOutputPath = './output/app';-execSync(`rm -rf ./output`, { stdio: 'inherit' });-// Create the app folder-execSync(`mkdir -p ${buildOutputPath}`, { stdio: 'inherit' });-// Move the files to the app folder-execSync(`cp -r ${localPath}/* ${buildOutputPath}`, { stdio: 'inherit' });// Copy the index.html to the routing lambda-execSync(`cp ${buildOutputPath}/index.html ./appRouteLambda/index.html`, {- stdio: 'inherit',-});+execSync(+ `cp ${shellQuote(`${buildOutputPath}/index.html`)} ./appRouteLambda/index.html`,+ { stdio: 'inherit' }+);const syncAssetsCommand = new command.local.Command('sync-assets-command',{// Source maps are intentionally public in production; the web client is open source.- create: pulumi.interpolate`aws s3 sync ./output s3://${webAppAssets.bucket} --acl public-read --delete --exclude "app/app-archive.zip"`,+ // Cache WASM is over CloudFront's automatic-compression size limit. Keep+ // raw bytes in dist/archive for Tauri and local preview, but exclude both+ // raw and sidecar from generic sync. The targeted uploader stores Brotli+ // bytes at the original .wasm key with application/wasm + Content-Encoding br.+ create: pulumi.interpolate`bash ../../../apps/web/scripts/cache-wasm/upload-brotli-to-s3.sh ./output/app s3://${webAppAssets.bucket}/app public-read && aws s3 sync ./output s3://${webAppAssets.bucket} --acl public-read --delete --exclude "app/app-archive.zip" --exclude "app-archive/*" --exclude "*cache_wasm_bg*.wasm" --exclude "*cache_wasm_bg*.wasm.br"`,triggers: [Date.now()],},{@@ -115,7 +134,7 @@ const updateIndexHtmlObjectMetadataCommand = webAppAssets.id.apply();// Run the command to update the index.html object metadata-new command.local.Command(+const indexHtmlObjectMetadataCommand = new command.local.Command('index-html-object-metadata-command',{create: updateIndexHtmlObjectMetadataCommand,@@ -123,6 +142,20 @@ new command.local.Command({ dependsOn: [webAppAssets, syncAssetsCommand], replaceOnChanges: ['*'] });+// Prune only after the current WASM, generic assets, index content, and index+// metadata have all published. Any earlier failure preserves all prior keys.+new command.local.Command(+ 'prune-old-cache-wasm-command',+ {+ create: pulumi.interpolate`bash ../../../apps/web/scripts/cache-wasm/prune-old-brotli-from-s3.sh ./output/app s3://${webAppAssets.bucket}/app ${cacheWasmRetentionDays}`,+ triggers: [Date.now()],+ },+ {+ dependsOn: [indexHtmlObjectMetadataCommand],+ replaceOnChanges: ['*'],+ }+);+// First, create an IAM role and attach the AWSLambdaBasicExecutionRole policyconst lambdaRole = new aws.iam.Role('content-encoding-header-lambda-role', {assumeRolePolicy: aws.iam.assumeRolePolicyForPrincipal({diff --git a/nix/cloud-storage.nix b/nix/cloud-storage.nixindex 34cc488d4e..8abae62c8e 100644--- a/nix/cloud-storage.nix+++ b/nix/cloud-storage.nix@@ -709,6 +709,7 @@just-lsptaplobun+ brotlipnpmsqlx-clitypescript-language-serverdiff --git a/packages/observability/src/privacy.ts b/packages/observability/src/privacy.tsnew file mode 100644index 0000000000..384e7b8a2f--- /dev/null+++ b/packages/observability/src/privacy.ts@@ -0,0 +1,15 @@+import { type Context, createContextKey } from "@opentelemetry/api";++const SUPPRESS_USER_ID_KEY = createContextKey(+ "@macro-inc/observability/suppress-user-id",+);++/** Marks telemetry whose contract forbids user identity enrichment. */+export function suppressUserId(context: Context): Context {+ return context.setValue(SUPPRESS_USER_ID_KEY, true);+}++/** Returns whether a span/log context forbids user identity enrichment. */+export function userIdSuppressed(context: Context): boolean {+ return context.getValue(SUPPRESS_USER_ID_KEY) === true;+}diff --git a/packages/observability/src/telemetry.test.ts b/packages/observability/src/telemetry.test.tsindex 65820b54f3..1015583530 100644--- a/packages/observability/src/telemetry.test.ts+++ b/packages/observability/src/telemetry.test.ts@@ -13,6 +13,7 @@ import {} from "@opentelemetry/sdk-trace-base";import { beforeEach, describe, expect, test } from "vitest";import { Telemetry } from "./index";+import { userIdSuppressed } from "./privacy";import { ZoneContextManager } from "./zone";context.setGlobalContextManager(new ZoneContextManager().enable());@@ -20,7 +21,19 @@ context.setGlobalContextManager(new ZoneContextManager().enable());const spanExporter = new InMemorySpanExporter();trace.setGlobalTracerProvider(new BasicTracerProvider({- spanProcessors: [new SimpleSpanProcessor(spanExporter)],+ spanProcessors: [+ {+ onStart: (span, parentContext) => {+ if (!userIdSuppressed(parentContext)) {+ span.setAttribute("usr.id", "test-user");+ }+ },+ onEnd: () => {},+ forceFlush: () => Promise.resolve(),+ shutdown: () => Promise.resolve(),+ },+ new SimpleSpanProcessor(spanExporter),+ ],}),);@@ -78,6 +91,25 @@ describe("Telemetry", () => {});});+ test("anonymous span trees are detached roots and suppress identity", () => {+ const regular = Telemetry.span("regular");+ const anonymous = regular.run(() =>+ Telemetry.anonymousSpan("cache.request"),+ );+ const child = anonymous.span("cache.storage");+ child.end();+ anonymous.end();+ regular.end();++ const spans = new Map(+ spanExporter.getFinishedSpans().map((span) => [span.name, span]),+ );+ expect(spans.get("regular")?.attributes["usr.id"]).toBe("test-user");+ expect(spans.get("cache.request")?.attributes).not.toHaveProperty("usr.id");+ expect(spans.get("cache.request")?.parentSpanContext).toBeUndefined();+ expect(spans.get("cache.storage")?.attributes).not.toHaveProperty("usr.id");+ });+test("ends a callback span after the async operation", async () => {let complete: () => void = () => {};const operation = Telemetry.span("doc.save", async (span) => {diff --git a/packages/observability/src/telemetry.ts b/packages/observability/src/telemetry.tsindex c872a5472d..a37bfba41d 100644--- a/packages/observability/src/telemetry.ts+++ b/packages/observability/src/telemetry.ts@@ -33,16 +33,27 @@ export class Telemetry {name: string,operation?: SpanOperation<T>,): Span | Promise<T> {- const span = Telemetry.#tracing.span(name);- if (!operation) return span;+ return Telemetry.#runSpan(Telemetry.#tracing.span(name), operation);+ }- return span.run(async () => {- try {- return await operation(span);- } finally {- span.end();- }- });+ /**+ * Start telemetry whose complete span tree is forbidden from receiving the+ * runtime user-id enrichment. Use this for privacy-aggregated subsystem+ * metrics whose schema does not permit identity.+ */+ static anonymousSpan<T>(+ name: string,+ operation: SpanOperation<T>,+ ): Promise<T>;+ static anonymousSpan(name: string): Span;+ static anonymousSpan<T>(+ name: string,+ operation?: SpanOperation<T>,+ ): Span | Promise<T> {+ return Telemetry.#runSpan(+ Telemetry.#tracing.anonymousSpan(name),+ operation,+ );}/** Start an HTTP client span. Callers must end the returned span. */@@ -77,6 +88,21 @@ export class Telemetry {]);}+ static #runSpan<T>(+ span: Span,+ operation?: SpanOperation<T>,+ ): Span | Promise<T> {+ if (!operation) return span;++ return span.run(async () => {+ try {+ return await operation(span);+ } finally {+ span.end();+ }+ });+ }+static async #initialize(config: TelemetryInitConfig): Promise<void> {try {if (!(await config.enabled())) return;diff --git a/packages/observability/src/tracing.ts b/packages/observability/src/tracing.tsindex 37ad20ffb4..47b3108658 100644--- a/packages/observability/src/tracing.ts+++ b/packages/observability/src/tracing.ts@@ -1,7 +1,14 @@-import { type Context, context, SpanKind, trace } from "@opentelemetry/api";+import {+ type Context,+ context,+ ROOT_CONTEXT,+ SpanKind,+ trace,+} from "@opentelemetry/api";import type { Resource } from "@opentelemetry/resources";import type { TelemetryInitConfig } from "./config";import { INSTRUMENTATION_SCOPE_NAME } from "./constants";+import { suppressUserId } from "./privacy";import type { TelemetryTracingProvider } from "./provider";import { type Span, SpanImpl } from "./span";@@ -20,6 +27,11 @@ export class Tracing {return this.#startSpan(name, context.active());}+ /** Starts a detached root span tree with user enrichment suppressed. */+ anonymousSpan(name: string): Span {+ return this.#startSpan(name, suppressUserId(ROOT_CONTEXT));+ }+clientSpan(name: string): Span {return this.#startSpan(name, context.active(), SpanKind.CLIENT);}diff --git a/packages/observability/src/web.ts b/packages/observability/src/web.tsindex 3bff964281..e85a8a79cf 100644--- a/packages/observability/src/web.ts+++ b/packages/observability/src/web.ts@@ -5,6 +5,7 @@ import { BatchSpanProcessor } from "@opentelemetry/sdk-trace-base";import { WebTracerProvider } from "@opentelemetry/sdk-trace-web";import type { TelemetryInitConfig } from "./config";import { ATTR_USER_ID } from "./constants";+import { userIdSuppressed } from "./privacy";import type { TelemetryTracingProvider } from "./provider";/** Creates the browser OpenTelemetry provider used by the web application. */@@ -17,7 +18,8 @@ export function createWebTracingProvider(resource,spanProcessors: [{- onStart: (span) => {+ onStart: (span, parentContext) => {+ if (userIdSuppressed(parentContext)) return;const userId = getUserId();if (userId !== undefined) span.setAttribute(ATTR_USER_ID, userId);},diff --git a/packages/observability/src/worker.ts b/packages/observability/src/worker.tsindex 8398603e5e..808dbb8da8 100644--- a/packages/observability/src/worker.ts+++ b/packages/observability/src/worker.ts@@ -8,8 +8,9 @@ import {OTLPExporter,type TraceConfig,} from "@microlabs/otel-cf-workers";-import type { Span } from "@opentelemetry/api";+import type { Context, Span } from "@opentelemetry/api";import { ATTR_DEPLOYMENT_ENVIRONMENT, ATTR_USER_ID } from "./constants";+import { userIdSuppressed } from "./privacy";export type { TraceConfig };export { instrument, instrumentDO };@@ -46,8 +47,9 @@ export function createWorkerTraceConfig(service: { name: options.serviceName },spanProcessors: [{- onStart: (span: Span) => {+ onStart: (span: Span, parentContext: Context) => {span.setAttribute(ATTR_DEPLOYMENT_ENVIRONMENT, options.environment);+ if (userIdSuppressed(parentContext)) return;const userId = options.getUserId?.();if (userId !== undefined) span.setAttribute(ATTR_USER_ID, userId);},diff --git a/tooling/xtask/crates/xtask_workflows/src/workflows/web_artifact_paths.rs b/tooling/xtask/crates/xtask_workflows/src/workflows/web_artifact_paths.rsindex c5a9607e84..a37329546d 100644--- a/tooling/xtask/crates/xtask_workflows/src/workflows/web_artifact_paths.rs+++ b/tooling/xtask/crates/xtask_workflows/src/workflows/web_artifact_paths.rs@@ -11,8 +11,9 @@ pub const WEB_ARTIFACT_PATHS: &[RepoGlob<'static>] = &[RepoGlob::new("apps/web/**"),RepoGlob::new("packages/**"),RepoGlob::new("crates/client/cache-core/**"),- RepoGlob::new("crates/client/cache-idb/**"),+ RepoGlob::new("crates/client/cache-turso/**"),RepoGlob::new("crates/client/cache-wasm/**"),+ RepoGlob::new("crates/client/turso-opfs/**"),RepoGlob::new("static_assets/schema.graphql"),RepoGlob::new("Cargo.toml"),RepoGlob::new("Cargo.lock"),