On this page
By now the vault has several derived views — a Wiki.js site, a read-only reader, an embeddings index, a backup mirror. Each is useful and each can silently fall behind. This is the reference-grade operations chapter: how to keep every projection provably honest. The instinct is the same one Google’s Site Reliability Engineering book formalizes for distributed systems — you don’t trust a component to be healthy, you continuously measure whether it is.
A many-view system is trustworthy only if every view exposes the commit it was built from, and you verify they all match the vault HEAD. A projection reporting an older commit is stale — still usable, but it forfeits any claim that the system as a whole is current until it’s rebuilt.
Replace the stand-ins: 10.0.0.76 → your vault host’s IP; vaultreader → your reader account; ~/wiki and the mirror path → your own locations; the commit 64dc195 is an example — yours will differ.
The health model: everyone reports a commit
Three green, one amber. The embeddings index lags — nothing is broken, but you can no longer say “everything is current.” The health check’s job is to make that amber visible immediately, not three days later when an agent quotes a stale hit.
The checks
Each projection has a verify step that asserts two things: its content matches the source (parity), and it reports the source commit (currency).
VAULT_HEAD=$(git -C ~/wiki rev-parse HEAD)
verify-projection # Wiki.js: published set == manifest, commit == HEAD
verify-index # embeddings: index commit == HEAD
ssh -i ~/.ssh/vault-reader vaultreader@10.0.0.76 status # reader: prints commit
git -C /path/to/mirror rev-parse HEAD # mirror: == HEAD ?
The Wiki.js delete-cascade’s final assertion — published set exactly equals the manifest — is precisely a health check: it catches orphaned pages the source no longer knows about. Parity you assert on every import is parity you never have to go hunting for later.
The validation CLIs that print usage and exit non-zero on bad input — instead of hanging on stdin or throwing a cryptic error — are part of the health story. A check that hangs gives you no signal; a check that exits 2 with “usage” tells you exactly what’s wrong. Loud, fast failure is a feature.
The controlled write ends by advancing a mirror on a separate machine, so there’s always an independent copy at a known commit.
git -C /path/to/mirror fetch --all
git -C /path/to/mirror reset --hard origin/master
git -C /path/to/mirror rev-parse HEAD # confirm == vault HEAD
Failure behavior: fail closed, then rebuild
The correct response to a stale consumer is not to panic and not to ignore it — it’s to stop claiming currency, rebuild the lagging consumer, and re-verify. Encode that: any tool or agent that depends on “the whole system is current” checks all consumers first and fails closed if any disagree, exactly as the begin step does.
No projection lagging behind ever corrupts the vault — the authority is untouched. The only real danger is presenting stale output as current. Health checks exist to make that mistake impossible to make by accident.
The swap-in box
CI/CD: treat each projection’s verify step as a monitored job; alert when its built-commit drifts from the source’s default-branch HEAD. Observability stacks (Grafana): export each consumer’s commit as a metric/label and alert on divergence. The universal rule: every derived view emits the revision it represents, and something continuously checks those revisions agree.
What you have now
A system that can prove it’s current — or tell you exactly which view isn’t. That’s the operational maturity a serious second brain needs. The final post is the one you hope never to need: what to do when the rules were broken and the brain is already a mess — repairing a messy brain.
Related posts:
- Turn Your Git Vault Into a Searchable Wiki.js Site — the projection whose parity assertion anchors these checks
- Semantic Search for Your Notes, Running Locally — the index whose commit you verify here
- Why Auto-Syncing Your Notes Repo Will Corrupt It — where the refresh + mirror-advance steps live
- Already Made a Mess of Your Notes? Here’s the Fix — recovery when health checks were never in place
- Proxmox Monitoring with Prometheus and Grafana — export consumer commits as metrics to alert on drift
Comments
Comments are powered by GitHub Discussions — sign in with a GitHub account to join the conversation.