Test Suite Overview ​

This page maps the full tests/ directory: what exists, what each test validates, and how to run everything.

Test Categories ​

CategoryLocationPurposePre-build gatetests/pre-build.test.mjsOrchestrates release-critical checks before publish.Axiomstests/axioms.test.tsVerifies invariants (stealth roots, hash-chain, LWW, pointers, operators).Phasestests/phases.test.jsEnd-to-end fire tests for feature phases 0-8.Build compatibilitytests/Builds/*Ensures CJS/ESM/UMD outputs behave correctly.DSL contractstests/contracts/dsl.contract.test.mjsContract suite for selector/filter/broadcast/query behavior.Benchmarkstests/Benchmarks/*Performance and complexity characterization.Demostests/Demos/*, tests/sand.tsPractical usage walkthroughs and exploratory scripts.## Run Commands ​

CommandWhat It Runsnpm run test:prebuildBuild + Axioms + Phases + CJS/ESM/TS/UMD checksnpm run test:contractsDSL contract suitenpm run test:demosRuns the three practical walkthrough demos under tests/Demos/*``npm run test:tsType-check (tsc --noEmit)npm run test:umdUMD runtime compatibility testnpm run test:phase3:exactExact vector-search correctness baselinenpm run test:phase3:ivfIVF sidecar smoke testnpm run bench:vector:corpusColumnar secret vector corpus write/read validationnpm run bench:phase3:exact-scaleExact vector-search scaling benchmarknpm run bench:phase3:ivf-vs-exactExact vs IVF comparison on the same corpusnpm run bench:phase3:ivf-tuningIVF tuning sweep (nlist, nprobe, candidate caps, dataset mode)You can also run files directly:

node tests/axioms.test.ts
node tests/phases.test.js
node tests/contracts/dsl.contract.test.mjs
node tests/Benchmarks/benchmark.11.secret-push-vs-pull.test.ts

Suggested CI Order ​

• npm run test:prebuild
• npm run test:contracts
• Optional nightly: selected benchmarks + regression gate
• Performance work: test:phase3:* and bench:phase3:* when changing vector search or secret chunk storage

Current Performance Story ​

• Phase 1 proved batch-write viability and removed heavy journal retention from _memories.
• Phase 2 closed bounded residency for the secret vector corpus by switching to chunked columnar envelopes with typed payloads.
• Phase 3 closed realistic ANN search at 100k on a chunk-coherent corpus with IVF p95 = 3318.42ms, recall@10 = 1.000, and 18.40 chunks/query.
• The hostile legacy_fragmented corpus remains in the suite as a documented worst-case profile rather than a hidden failure mode.

Navigation ​

• Axioms & Phases
• Build Compatibility Tests
• Examples & Contracts
• Performance & Benchmarks