71e80ef655
The suite had not been run since 2026-08-23 and deps were not installed. Running it
against the freshly rolled m12-vsc-20260830 found four failures. Every one was the
harness doing its job; three were stale pins it explicitly told me to invert.
REAL FINDING, caught by the suite and nothing else: tidaldb-2 was NotReady mid-run.
It had exited(0) with {"reason":"reseed_self_restart","shard":1}, reinstalled a
snapshot and converged. Designed behavior - but the suite sampled readiness ONCE and
reported a self-healing cluster as broken. Readiness is now polled via
waitForPodsReady with a bounded budget and the whole timeline attached as evidence.
Deliberately not Playwright retries: retries:0 is correct here, because a live check
that only passes on attempt two has told you something true.
STALE PINS INVERTED (each verified live first, not taken on the message's word):
- 06-logs: ANSI escapes are gone (0 in a 5-line sample), BUG-006 resolved on this
image. Now pinned so a regression to coloured output fails.
- 09-operator-authority + CAP-015 capture: tidaldb_http_* exists (185 series
against a 552 baseline). Runbook 9.1 moved from inert to LIVE. CAP-015 keeps its
purpose - state the gaps - and now names the one that is still real: no JSON_LOGS.
- The transient /search 500 and public 502 were tidaldb-2's restart window, not
defects; both surfaces returned 200 on eight retries afterwards.
THRESHOLD CALIBRATED AGAINST A MEASUREMENT, TWICE. My first fix capped
consecutive ship failures at 500, guessing a restart burst was ~100. Measurement
killed it: a reseed restart is a ~2 minute absence, which at the shipper's 100ms
cadence is ~1200-2000 failures - observed exactly 1950, then "peer recovered", with
peer_acked_seqno back at the frontier. A COUNT cannot separate "a peer restarted"
from "shipping is stuck"; it only encodes how long the peer was away. The test now
compares the newest distress line against the newest recovery line and fails only
when distress is newer. Same correction applied to the alert in k3s-fleet.
STALE EVIDENCE WAS THE WORST GAP. demo/public/captures and capture-manifest.json
still described m12-admin-gate-20260823 - two image rolls stale - while
demo:preflight reported "audited perfect" about week-old frames, and the rendered
title card read "image m12-admin-gate-20260823 - 32 checks green". The capture suite
writes to test-results/demo-captures/ and the copy-and-merge step into the published
set simply did not exist; it was done by hand once. Added demo/promote.ts: copies
frames, verifies each PNG against its fragment hash, and stamps buildRevision and
verifiedImage from the live StatefulSet. Verdicts land `pending`, so preflight fails
until the frames are audited - that failure is the gate. scenes.ts now derives the
image tag and check count from the manifest, and preflight fails if a literal is
pasted back in (proven by pasting one back in).
All 10 captures were opened individually at full resolution; the audit note is stored
in the manifest beside each verdict rather than only in prose.
Green: 34 e2e + 5 hermetic semantics + 10 captures + preflight + 2107 lib.
Video: demo/out/deploy-verification.mp4, 90.05s 1920x1080 h264, title card now
reading "image m12-vsc-20260830 - 34 checks green".
CLAUDE.md gains a Deploy Verification section and AGENTS.md a short mandatory
pointer: every deploy is verified through this harness, and maintaining it is part
of the change, not follow-up. The suite pins current reality including defects, so a
correct improvement WILL turn it red - and that is the harness working.
|
||
|---|---|---|
| .. | ||
| 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