fe8d0c87e7
Implements tmp/tidaldb-fleet-hardening (20 planned tasks + 2 found by measurement). Ring 0 — restore verification. .woodpecker.yaml step pods ran at the namespace default of 1500m/2Gi, which OOMKilled a prior pipeline and starved the release gate past its budget. Both push-path steps now declare backend_options.kubernetes.resources as two YAML anchors declared once on their first consuming step. The values are CALIBRATED against measured free node capacity, not against the LimitRange max: `requests: cpu 2` (this roadmap's original figure) fits on NO node and would sit Pending forever, because `ci-build-bounds` grants permission and the nodes supply capacity, and those are not the same thing. The `nightly` cron described in this file for 216 days was never created, so tier-3 chaos, the fault classes, mTLS and the PITR test produced exactly zero signal while reading like standing coverage. nightly-chaos and nightly-security-ops now alias the anchors and have budgets matching the gate (their 120/90 were TIGHTER on the same runner, so they would have failed nightly for a budget reason, not a correctness one). nightly-soak is REMOVED, not scheduled: it drives 1000 rps for 600s gating on p99 <= 250ms, and the best node has 1700m free CPU, so it would fail on starvation rather than regression — manufacturing a nightly false alarm. Its commands move verbatim to docs/runbooks/nightly-soak.md. Ring 1 — four fabrications removed from the wire. - scatter_merge sorted and truncated without re-stamping rank, so /feed and /search returned 1,1,2 under full placement. Reuses merge_cross_shard's existing stamp; asserted on BOTH the multi-group merge path and the single-group [only] fast path that bypasses it. - aggregate_region_row's None arm invented `applied_events: 0` plus a deficit derived from it. applied_events/lag_events are now Option<u64>, null on the wire. leader_last_seq was also unwrap_or(0), so a node that could not reach the LEADER computed 0 - applied = 0 for every region and reported a converged cluster it had never measured — a fabrication pointing the dangerous way. - tidalctl inferred NO REPORT from `applied == 0 && lag > 0`. That heuristic was actively hiding the PVC-wipe shape: a measured zero with a real deficit rendered as "no report" instead of BEHIND. Now read off the wire; converged exits 0, partitioned still exits nonzero. - /sharded/* answered 201/204 for single-copy writes with nothing anywhere saying so. Now requires `x-tidal-ack: local`, rejecting with 400 via the existing invalid_input path. Six call sites migrated, not the two this roadmap predicted — including docs/runbooks/cluster.md §16.3, which told operators to run a quorum-write probe via POST /sharded/items. That probe cannot verify quorum: the surface applies locally with no WAL append. It was used as the safety check between every step of a staged deploy earlier today. Ring 2 — observability. JSON_LOGS was already implemented and the deployment simply never asked for it; the StatefulSet now sets it, plus TIDAL_SERVICE_NAME=tidaldb because enabling it silently renames the VictoriaLogs `service` stream field and would have blinded every query keyed on it. Adds tidaldb_usearch_replicated_vectors_total, incremented on BOTH the origin (wal_blob_first -> Ok(Some)) and the follower apply path — counting only the origin would mean each vector lands on exactly one node, replicas never agree, and the alert built on it pages forever. Found by measurement, not planned: the 401 path discarded every fact about every rejection. Traefik has served 101,858 rejected requests to the public ingress — 87.6% of all its traffic — with no record of who or why anywhere. unauthorized_response now emits reason (missing_token vs invalid_token, the distinction that separates a scanner from a rotation that missed a consumer) and the forwarded client. The token is never logged. Also: scripts/restore-fleet.sh --cluster started the soak monitor while deliberately leaving its gate suspended, orphaning a watcher that has reported "0/30 green nights" for 13 days. The pair now moves together. Doc-guard's three-warning backlog is cleared with real backfill for M4/M6/M12. Verified: fmt clean; clippy 5 crates 0 new warnings (74 vs 74 baseline, counted in a detached worktree at HEAD); lib 2110 passed; cluster_sharding 5; cluster_runbook 10; tidalctl 38; doc-guard 0 warnings. Playwright 32/34 with the two remaining failures asserting the rank fix against the not-yet-rolled image — they are the post-deploy proof. |
||
|---|---|---|
| .. | ||
| 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