8aa1fbb414
Three real defects, plus a retracted fourth that was a probe artifact. P3 (fixed) - query/stored normalization asymmetry. The write path L2-normalized every stored vector; the read path passed the caller's raw query straight to the index, so the two sides lived in different spaces. With unit v, d = |q|^2 - 2q.v + 1, so a non-unit query shifted and scaled every distance by |q|^2. Measured live: 591-1174 against a documented [0,4], and an exact match scoring |q|^2 - 1 instead of ~0. vector_search_items now normalizes with the canonical l2_normalize; a zero-norm query (no direction, so nearest-by-cosine is undefined) is rejected with 400. Ranking is unchanged - |q|^2 and 1 are constant across candidates - which is why it went unnoticed; what broke was every absolute use of the number. WIRE-VISIBLE, recorded in CHANGELOG. P2 (fixed) - the blob path had zero instrumentation. Added per-kind tidaldb_cluster_blobs_originated/applied/apply_failed totals. Label cardinality is fixed at 4 by construction via a new BlobKind enum, and BlobRecord::blob_kind is now the ONE exhaustive match over the variants (kind() derives from it), so a new variant is a compile error in one place instead of a silent zero in three. Only the live apply path is counted - boot replay would inflate applied past originated on every restart. Coverage gap (fixed) - tidaldb_usearch_vector_count rendered only the metrics owner's shard group, so on a 3-group node two thirds of the corpus had no vector-count series at all. Co-located groups now render shard="N"; the owner stays unlabeled for wire compatibility, so an alert grouped by (shard) buckets each replica set separately without double-counting. P1 (RETRACTED) - the "replica-divergent vector index" does not exist. Every probe wrote through the /sharded/ surface, which hash-partitions and applies to the owning region's local store with no WAL append, and therefore does not replicate BY DESIGN (cluster/node.rs:8828-8829). A controlled A/B settled it: on /items plus /embeddings all 6 entities reach all 3 replicas; on the sharded surface four of six reach exactly one node. Both are now pinned by tests. See tmp/vector-search-correctness/diagnosis.md and the k3s-fleet cluster-state.yaml entry RETRACTED_blob_replication_rf1_2026_08_30. Pre-work: usearch_index.rs 872 to 503 lines by extracting its tests to a sibling (the project's existing path-attribute convention), and the three hand-rolled l2_normalize copies collapsed to one. The two entity copies used a zero threshold about 2900x looser than the canonical one; normalize_centroid now names the centroid zero-tolerance policy once, and a test pins the tightened behavior. Tests: 2107 lib (+5), 8 vector_search e2e (+4, three of which fail without the P3 fix), 4 cluster_sharding e2e (+2). The heavy multiproc tests in cluster_sharding are now serialized - four concurrent 3-node clusters made the pre-existing failover test miss its 10s budget. |
||
|---|---|---|
| .. | ||
| guides | ||
| legal | ||
| ops | ||
| planning | ||
| profiling | ||
| research | ||
| reviews | ||
| runbooks | ||
| specs | ||
| content-strategy.md | ||
| personal-briefing-beachhead.md | ||
| README.md | ||
| roadmap-to-cluster.md | ||
tidalDB Engineering Docs
The engineering documentation home. Top-level product docs (VISION, USE_CASES, SEQUENCE, ARCHITECTURE, API, QUICKSTART, CODING_GUIDELINES, thoughts) live at the repository root; everything below is the deeper engineering record.
This and the repo root are the two canonical doc homes. There is intentionally no per-crate doc mirror (no
tidal/docs/). Edit the canonical file, never a copy.
Component specs — specs/
The authoritative component specifications (status: Implemented, M0–M12).
| # | Spec | # | Spec |
|---|---|---|---|
| 00 | Architecture overview | 08 | Query engine |
| 01 | Storage engine | 09 | Ranking & scoring |
| 02 | Entity model | 10 | Feedback loop |
| 03 | Signal system | 11 | Schema |
| 04 | Relationships | 12 | Cold start |
| 05 | Cohorts | 13 | Concurrency |
| 06 | Text retrieval | 14 | Scale architecture |
| 07 | Vector retrieval |
Planning — planning/
- ROADMAP.md — milestones M0–M12, phase status, known gaps
- roadmap-to-cluster.md — adopted M11 plan: gap analysis + phase specs taking the multi-process cluster from experimental to enterprise-grade (all nine phases m11p1–p9 ✅, 2026-06-13), grounded in the 2026-06-10 live stress-test baselines
- PRODUCT_ROADMAP.md · architecture-review.md · roadmap-cohort-analysis.md · site-cohort-analysis.md
- Per-milestone phase/task archive:
planning/milestone-0,1,2,3,5,7,8,9,10,11,p/
Code reviews — reviews/
- M0–M10 code review — 2026-06-07 — seven-dimension re-review, 88 verified findings
- M0–M10 code review — 2026-06-08 — seven-dimension review, 142 findings (latest pass)
- M0–M10 seven-dimension review — additional pass (2 BLOCKERs: signal-checkpoint trim, 30-day window)
Guides — guides/
Task-oriented, build-an-app docs (complements the root QUICKSTART.md and API.md):
- Build a feed app — end-to-end TikTok/Reels-style "For You" feed, embedded and over HTTP
- Embedding integration — wiring a real embedding model (OpenAI / Cohere / local) into the write + query paths
- Server deployment — running the
tidal-serverHTTP service: config, auth, the served OpenAPI spec, Docker - Ranking-profile reference: ai-lookup/services/ranking-profiles.md — all 25 built-in profiles
Operations — ops/ and runbooks/
- Monitoring · Prometheus alerts · Grafana dashboard · Capacity planning · Recovery
- Runbooks: Kubernetes · Cluster (experimental)
Research — research/
ANN (1, 2) · Tantivy (1, 2) · Signal ledger (1, 2) · WAL · Type system · Tooling & diagnostics · Enterprise-readiness risks
Profiling — profiling/
Hotspot analysis · Scale baselines · Signal memory · Signal rollup eval · Social scale · Tantivy merge tuning · USearch tuning