From 45e94ce4431965f40ac9f0cfee29a9fc81a9ad52 Mon Sep 17 00:00:00 2001 From: codewarnab Date: Sun, 18 Oct 2026 19:28:46 +0000 Subject: [PATCH] test(snapshot): freeze published 1.0.1 compatibility fixture --- .../historical-snapshot-compatibility.md | 5 + docs/IMPROVEMENT-PLAN.md | 1 + .../webgpu-search/test/fixtures/README.md | 34 ++++ .../test/fixtures/snapshot-1.0.1.bin | Bin 0 -> 1465 bytes .../test/fixtures/snapshot-1.0.1.json | 187 ++++++++++++++++++ scripts/test-snapshot.ts | 35 ++++ 6 files changed, 262 insertions(+) create mode 100644 .changeset/historical-snapshot-compatibility.md create mode 100644 packages/webgpu-search/test/fixtures/README.md create mode 100644 packages/webgpu-search/test/fixtures/snapshot-1.0.1.bin create mode 100644 packages/webgpu-search/test/fixtures/snapshot-1.0.1.json diff --git a/.changeset/historical-snapshot-compatibility.md b/.changeset/historical-snapshot-compatibility.md new file mode 100644 index 0000000..81de8e4 --- /dev/null +++ b/.changeset/historical-snapshot-compatibility.md @@ -0,0 +1,5 @@ +--- +"webgpu-search": patch +--- + +Add a frozen snapshot from the published 1.0.1 package to verify backward-compatible restoration, document contents, and ordered search scores in CI. diff --git a/docs/IMPROVEMENT-PLAN.md b/docs/IMPROVEMENT-PLAN.md index 4ccbe2c..201483c 100644 --- a/docs/IMPROVEMENT-PLAN.md +++ b/docs/IMPROVEMENT-PLAN.md @@ -31,6 +31,7 @@ There are about 300 tests, but several core modules have none of their own. This - **Why:** AGENTS.md §2.4 requires the two paths to score the same, and nothing enforces it today. ### 2.2 Snapshot codec tests +- **Historical compatibility covered:** `scripts/test-snapshot.ts` loads the frozen `test/fixtures/snapshot-1.0.1.bin` written by the published npm package, with provenance and fixed search expectations in its JSON manifest. Existing round-trip and typed corruption/profile error checks remain in the same suite, which CI runs through `test:snapshot`. - Add `test/snapshot-codec.test.ts`: - Saving an index and loading it back gives identical search results. - Bad input is rejected with the right typed error: wrong magic bytes, wrong version, truncated data, a corrupted checksum, a mismatched text profile. diff --git a/packages/webgpu-search/test/fixtures/README.md b/packages/webgpu-search/test/fixtures/README.md new file mode 100644 index 0000000..5e83efc --- /dev/null +++ b/packages/webgpu-search/test/fixtures/README.md @@ -0,0 +1,34 @@ +# Historical snapshots + +`snapshot-1.0.1.bin` was written by the **published npm package +`webgpu-search@1.0.1`**, not by the working tree. Its JSON manifest records +the npm tarball URL and integrity, input documents, index options, snapshot +format and SHA-256, and ordered search results from that released package. + +The fixture protects compatibility with an older writer independently of +current serialization code. The snapshot suite loads the bytes directly and +checks result IDs, scores, matched fields, and restored documents. CI already +runs it through `bun run test:snapshot`. + +## Preserve the fixture + +Do not regenerate or update this pair to make a failing test pass. Investigate +the compatibility regression instead. Add a separately versioned fixture when +covering another release; retain the existing ones. + +To reproduce the original generation in a temporary directory: + +1. Install `webgpu-search@1.0.1` with + `npm install --ignore-scripts --no-audit --no-fund --save-exact webgpu-search@1.0.1`. +2. Verify its `package-lock.json` integrity matches `producer.integrity` in + the manifest. Import `DocumentIndex` from that installation, outside this + monorepo so workspace aliases cannot select current code. +3. Pass the manifest's `documents` and `options` to `DocumentIndex.create()`. + Write `new Uint8Array(index.serialize())` to a temporary file. +4. Run each manifest query using its `mode` and `cpuScorer: 'exact'`. Compare + `totalMatches` and ordered `{ id, score, matchedField }` against `expected`. + Destroy the index when finished. + +The resulting file must match `snapshotSha256`; reproduction must not overwrite +the checked-in artifact. Queries cover weighted multi-field ranking, ASCII, +German and Greek case folding, decomposed accents, CJK, emoji/ZWJ, and no hits. diff --git a/packages/webgpu-search/test/fixtures/snapshot-1.0.1.bin b/packages/webgpu-search/test/fixtures/snapshot-1.0.1.bin new file mode 100644 index 0000000000000000000000000000000000000000..4598e89bcdf28b4febd700490a80f3811b80c9f8 GIT binary patch literal 1465 zcmbW1&ubGw6vq=(1fhR`;9(f>BC*&a2mw#l20=t9MNo2>Y$nY#o87oO+Z<{j=s^$! z^`IcN6@MU=927j+W4w5=|AT1MTMy#d?>C!CHbp(S@X5^1d-Hwo&E)Orh56-!xm+%v z;SlCWz|LsxBgUt67(MrHH_xuin$dnWmc?u9GEhw|i_#kFYgv$OZC2`57Uw&KvCRtu zs{@;{&UMNKSq;4lLlLQB&zO^Qa7btKm?eSn!YU=b)dqfbGh8(i+dLKPB^|`Znl(hO zDL>W)*@|>cN2OLWUTG#)SrZ25TcKB%#Zv`j?OPo!y4=g1Hj2`q0#-l^BtU=|(565H zJWvOJTNkiVgZmAr0`8~31=OGx-<^iQoVr}Efgj*HM0%If9F9Rqb|zYDuv60qAz;3I zr?vp*XFfNB$qq*9xp<6^<)J^cN0)60E|hk zS@1vSEJpiymek_e3&6ZMGG_L^T)nO)-YI?Q*8t3eT89s$c~O&g=1O1Y&%FY;b=Jps z-YaWnZG?IP^r5wXWSp;XDqz#*oz(uXGyT(lh8oO;c`z^L$U58^bbsZCae1!$&xiT( z9(XUSBRlo@%z&fdI5+{$fUDpJcnDqrHa^GHCOwTjSGXvR@% z7v-Xgt!Sx8`M&l?4x$!D0&Si&(f;wQ&R8SSANb839^jz%T61z7ulIh3C z$qk;o{qnvi1}`?gy?Zt#H+b}Nu+jVedefCYtRy3pe!nIKFX%Pxhb ({ id, score, matchedField })), + }, entry.expected, `1.0.1 snapshot search changed for ${JSON.stringify(entry.query)}`); + for (const hit of response.results) { + assert.deepStrictEqual(hit.doc, snapshotFixture.documents.find(doc => doc.id === hit.id)); + } + } + } finally { + restored.destroy(); + } + console.log(' ✅ Published 1.0.1 snapshot compatibility confirmed'); + } + console.log('\n--- All Persistence Tests Passed Successfully! ✅ ---'); }