DB grounding verdict + db-doctor/db-sync (#94)

[mobileskyfi]

Problem

In a checkout, nothing told a session whether the resolved ros-help.db matched the code querying it (#94). Dev mode serves the git-ignored repo-root DB, and checkDbFreshness intentionally ignores release-tag drift in dev mode (so it never clobbers a contributor's local build) — which means a schema-matching but wrong-corpus DB starts up silently and invalidates grounded work.

Confirmed live: the repo-root DB was a "Frankenstein" — db_meta said v0.10.0/schema 5/321 Confluence pages, but PRAGMA user_version=10 (an in-place initDb bumped it). Nothing flagged it.

What this adds

A pure classifier — classifyDbGrounding (src/paths.ts) — shared by three surfaces so they stay in lockstep:

• routeros_stats gains a provenance block + grounding verdict (ok / schema_mismatch / internal_inconsistent / tag_behind / unstamped). One call self-checks the DB against the checkout. The browse TUI stats screen inherits it via shared getDbStats.
• MCP dev-mode startup emits a loud but non-fatal banner on a non-ok verdict — never fetches, so a contributor's local build is never clobbered.
• make db-doctor / bun run db:doctor prints the verdict and exits non-zero on drift (CI / pre-commit ready).

The load-bearing new signal is internal_inconsistent (db_meta.schema_version ≠ PRAGMA user_version) — the "Frankenstein" tell that every prior check missed.

make db-sync (the grounding source of truth)

make db-sync / bun run db:sync fetches the newest CI release DB that matches this checkout's schema. It uses gh to find the newest release shipping ros-help.db.gz — prereleases included — rather than --refresh, which pins the URL to package.json's CI-placeholder version (v0.11.0-rc.0, no such release) and falls back to /releases/latest (the newest stable, an older schema). Reuses the hardened downloadDb() (lock + schema/content validation + stale-sidecar cleanup + atomic swap) via a new backward-compatible urlsOverride param, so it's safe to run while an MCP server holds the old file open.

Also

• Fixes same-class stale hardcodes: doc_export and the "317 pages / March 2026 Confluence" text baked into the routeros_stats description now defer to the live provenance block.
• Durable guidance: new .github/instructions/local-db-grounding.instructions.md; V-db-grounding row in VALIDATION.md; CLAUDE.md pointer, MANUAL.md section, CHANGELOG entry.

Verification

• db-doctor flags the pre-sync Frankenstein as internal_inconsistent (exit 1) and the synced CI artifact as ok (exit 0). ✅ ran live
• make db-sync installs v0.11.0-rc.102 (schema 10, 363 pages) into the repo-root path. ✅ ran live
• Dev startup banner fires on a drifted DB. ✅ ran live
• bun test (914 pass, +new classifier / provenance / tooling-anchor tests), bun run typecheck, bun run lint, markdownlint, cspell — all green. ✅

Closes #94

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Added database diagnostics to verify schema compatibility, provenance, and grounding status.
  • Added database synchronization to fetch and safely install the latest compatible release database.
  • Added database provenance and grounding details to statistics and MCP responses.
  • Development startup now displays a warning when the database is not fully grounded.

• Documentation

  • Added guidance covering database verification, synchronization, grounding statuses, and troubleshooting.

• Tests

  • Added coverage for grounding classifications, provenance reporting, and database tooling.

[coderabbitai]

Important

Review skipped

Auto incremental reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 013c2e27-9460-4618-b936-793c8df819da

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Adds database provenance and grounding classification, exposes verdicts through runtime stats and MCP warnings, and introduces db-doctor and db-sync commands for verification and release database replacement. Documentation and tests define verdict precedence, freshness behavior, and command wiring.

Changes

Database grounding

Layer / File(s)	Summary
Grounding classification contract src/paths.ts, src/paths.test.ts, src/setup.ts	Adds grounding verdict types and classification precedence, centralizes development-mode detection, and extends database probes with provenance metadata.
Runtime provenance reporting and warnings src/db.ts, src/mcp.ts, src/query.test.ts	Adds provenance and grounding data to getDbStats(), derives export metadata from database stamps, and warns during development startup when grounding is not ok.
Diagnostic and release database commands scripts/db-doctor.ts, scripts/db-sync.ts, src/setup.ts, package.json, Makefile, src/release.test.ts	Adds database verification and release synchronization commands, including release discovery, override downloads, validation, and atomic replacement.
Freshness behavior and grounding guidance src/setup.test.ts, .github/instructions/..., MANUAL.md, CLAUDE.md, CHANGELOG.md, VALIDATION.md	Updates freshness tests and documents database trust, verdict semantics, synchronization, startup behavior, and validation requirements.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

Database synchronization

sequenceDiagram
  participant db-sync
  participant GitHub
  participant downloadDb
  participant ros-help.db
  db-sync->>GitHub: Query newest release asset
  GitHub-->>db-sync: Return ros-help.db.gz URL
  db-sync->>downloadDb: Download with urlsOverride
  downloadDb->>ros-help.db: Validate and atomically replace

Loading

MCP grounding verification

sequenceDiagram
  participant MCP
  participant probeDb
  participant classifyDbGrounding
  MCP->>probeDb: Read database metadata
  MCP->>classifyDbGrounding: Evaluate schema and provenance
  classifyDbGrounding-->>MCP: Return grounding verdict
  MCP-->>MCP: Log warning when verdict is not ok

Loading

Possibly related PRs

• tikoci/rosetta#36: Both changes extend the getDbStats() payload.
• tikoci/rosetta#78: Both changes modify database startup and provenance-based refresh behavior.
• tikoci/rosetta#99: Changes database schema/versioning used by grounding classification.

Suggested reviewers: copilot

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: DB grounding verdicts plus db-doctor/db-sync tooling.
Linked Issues check	✅ Passed	The PR satisfies #94 by adding grounding classification, provenance exposure, non-OK reporting, db-doctor, db-sync, and documentation.
Out of Scope Changes check	✅ Passed	No unrelated code changes stand out; the edits are scoped to DB grounding, synchronization, docs, and supporting tests.
Docstring Coverage	✅ Passed	Docstring coverage is 81.82% which is sufficient. The required threshold is 80.00%.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch db-grounding-visibility

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[Copilot]

Pull request overview

This PR adds a shared “DB grounding” classifier and surfaces DB provenance/grounding status across the MCP server, TUI stats, and new local tooling (db-doctor, db-sync) to prevent silently grounding work on a schema-coherent but wrong-corpus ros-help.db in dev checkouts.

Changes:

• Introduces classifyDbGrounding (pure) and threads its verdict into getDbStats/routeros_stats, plus a dev-only MCP startup warning banner.
• Adds make db-doctor / bun run db:doctor (verdict + non-zero exit on drift) and make db-sync / bun run db:sync (fetch newest release DB asset via gh, prereleases included) with supporting docs/tests.
• Updates documentation and validation/CI anchors (VALIDATION row, MANUAL/CLAUDE pointers, CHANGELOG entry, new instruction file).

Reviewed changes

Copilot reviewed 17 out of 17 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
VALIDATION.md	Adds V-db-grounding coverage and where it’s validated.
src/setup.ts	Extends DB probing to read additional db_meta provenance and adds downloadDb URL override.
src/setup.test.ts	Adapts checkDbFreshness tests to the expanded probe shape.
src/release.test.ts	Asserts package/Makefile wiring for db:doctor/db:sync and db-sync’s intended behavior.
src/query.test.ts	Verifies getDbStats() exposes provenance + grounding verdict.
src/paths.ts	Adds grounding classifier + version-base comparison helpers and isDevInvocation.
src/paths.test.ts	New unit tests for grounding verdict precedence and edge cases.
src/mcp.ts	Emits a dev-only grounding warning banner; updates routeros_stats description to reference provenance instead of hardcoded corpus facts.
src/db.ts	Adds provenance block to stats; derives doc_export display from provenance instead of hardcoding.
scripts/db-sync.ts	New script to discover newest release DB asset via gh and install it via downloadDb(urlsOverride).
scripts/db-doctor.ts	New script to print provenance + grounding verdict and exit non-zero when not ok.
package.json	Adds db:doctor and db:sync scripts.
MANUAL.md	Documents dev-checkout grounding rules and the new commands.
Makefile	Adds db-doctor and db-sync targets.
CLAUDE.md	Adds a quick pointer for grounding verification.
CHANGELOG.md	Adds an Unreleased entry describing the new grounding/provenance/tooling behavior.
.github/instructions/local-db-grounding.instructions.md	New durable rule doc for local DB grounding expectations and invariants.

[coderabbitai]

Actionable comments posted: 3

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

src/setup.ts (1)

422-458: 🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win

Preserve the explicit sync target during lock contention.

When urlsOverride is supplied, Lines 429-442 can return an arbitrary usable database before the override is evaluated. db-sync can therefore report success without installing its selected release. In override mode, reacquire the lock and perform the requested download, or verify that the reused probe matches the expected release.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/setup.ts` around lines 422 - 458, Update downloadDb so urlsOverride takes
precedence over reuse paths after lock contention: do not return an arbitrary
usable database from waitForUsableDb or the fallback probe when an override is
supplied. Reacquire the lock and continue to the requested download, or only
reuse a probe after verifying it matches the explicit target; preserve existing
reuse behavior when urlsOverride is absent.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.github/instructions/local-db-grounding.instructions.md:
- Around line 1-4: Update the frontmatter applyTo field in
local-db-grounding.instructions.md from a comma-separated string to a YAML array
containing each target path pattern, preserving all existing entries.

In `@src/db.ts`:
- Around line 1115-1119: Update the doc_export fallback derived from provenance
so artifacts identified by release_tag/source_commit or is_ci_artifact are
labeled as having an unknown build time rather than “(unstamped local build)”;
retain the existing stamped format when built_at exists and reserve the
local-build fallback for genuinely unstamped metadata.

In `@src/paths.ts`:
- Around line 241-249: Update the version-validation branch around
compareBaseVersion in the release-tag verdict flow so a null comparison returns
an appropriate non-OK verdict instead of falling through to "ok"; preserve the
existing tag_behind behavior for parsed older versions, and add a regression
test covering malformed release_tag or unknown codeVersion inputs.

---

Outside diff comments:
In `@src/setup.ts`:
- Around line 422-458: Update downloadDb so urlsOverride takes precedence over
reuse paths after lock contention: do not return an arbitrary usable database
from waitForUsableDb or the fallback probe when an override is supplied.
Reacquire the lock and continue to the requested download, or only reuse a probe
after verifying it matches the explicit target; preserve existing reuse behavior
when urlsOverride is absent.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 77e3033d-a72e-496e-abda-8063b9271320

📥 Commits

Reviewing files that changed from the base of the PR and between 92ba5d4 and d82fc11.

📒 Files selected for processing (17)

• .github/instructions/local-db-grounding.instructions.md
• CHANGELOG.md
• CLAUDE.md
• MANUAL.md
• Makefile
• VALIDATION.md
• package.json
• scripts/db-doctor.ts
• scripts/db-sync.ts
• src/db.ts
• src/mcp.ts
• src/paths.test.ts
• src/paths.ts
• src/query.test.ts
• src/release.test.ts
• src/setup.test.ts
• src/setup.ts

📜 Review details

⏰ Context from checks skipped due to timeout. (1)

• GitHub Check: copilot-pull-request-reviewer

🧰 Additional context used

📓 Path-based instructions (7)

*

📄 CodeRabbit inference engine (.github/copilot-instructions.md)

Keep this Copilot instructions file short; put substantive rules in narrow instruction files under .github/instructions/*.instructions.md.

Files:

• VALIDATION.md
• CLAUDE.md
• package.json
• MANUAL.md
• Makefile
• CHANGELOG.md

*.md

📄 CodeRabbit inference engine (CLAUDE.md)

*.md: Keep each project document in its canonical location and role; do not invent new top-level Markdown files or duplicate content across documents.
Record durable project rationale in DESIGN.md, operator or release procedures in MANUAL.md, user-visible shipped changes in CHANGELOG.md, and load-bearing invariants plus their proofs in VALIDATION.md.
Avoid ticket sprawl: treat an issue as discussion initially, and apply the agent-ready label only after acceptance criteria are settled rather than by default.

Files:

• VALIDATION.md
• CLAUDE.md
• MANUAL.md
• CHANGELOG.md

CLAUDE.md

📄 CodeRabbit inference engine (AGENTS.md)

Read CLAUDE.md before non-trivial work; it is the repository routing index.

Files:

• CLAUDE.md

**/*.{ts,tsx}

📄 CodeRabbit inference engine (.github/copilot-instructions.md)

Use Bun and TypeScript, including Bun-native runtime APIs such as bun:sqlite, Bun.serve, and bunx.

Rosetta uses Bun and TypeScript; prefer bun and bun test rather than Node/npm-oriented substitutes.

Files:

• src/paths.test.ts
• scripts/db-doctor.ts
• src/release.test.ts
• src/query.test.ts
• src/db.ts
• src/setup.test.ts
• scripts/db-sync.ts
• src/paths.ts
• src/mcp.ts
• src/setup.ts

{README.md,src/setup.ts,MANUAL.md}

📄 CodeRabbit inference engine (AGENTS.md)

Keep public client setup snippets aligned across README.md, src/setup.ts, and MANUAL.md, including the Codex command codex mcp add rosetta -- bunx @tikoci/rosetta``.

Files:

• MANUAL.md
• src/setup.ts

.github/instructions/*.instructions.md

📄 CodeRabbit inference engine (AGENTS.md)

Manually read the matching .github/instructions/*.instructions.md files because Codex does not automatically apply Copilot’s applyTo selection.

Keep narrow normative coding rules in .github/instructions/*.instructions.md, and route them using their applyTo scopes.

Files:

• .github/instructions/local-db-grounding.instructions.md

src/{query,mcp,browse}.ts

📄 CodeRabbit inference engine (AGENTS.md)

Route MCP, query, classifier, TUI, and canonicalizer behavior through shared core code, usually src/query.ts; keep src/mcp.ts and src/browse.ts thin adapters.

Files:

• src/mcp.ts

🧠 Learnings (1)

📓 Common learnings

Learnt from: CR
Repo: tikoci/rosetta

Timestamp: 2026-07-17T17:56:42.525Z
Learning: Committed codebase work belongs in a GitHub issue, grounded research and decision support in a briefing, durable rationale in `DESIGN.md`, procedures in `MANUAL.md`, shipped behavior in `CHANGELOG.md`, and invariants with proof in `VALIDATION.md`.

Learnt from: CR
Repo: tikoci/rosetta

Timestamp: 2026-07-17T17:56:42.525Z
Learning: Before changing extraction, MCP, or TUI search in response to the MikroTik manual-site migration, read `DESIGN.md` and `briefings/B-0012-docusaurus-manual-migration.md`.

Learnt from: CR
Repo: tikoci/rosetta

Timestamp: 2026-07-17T17:56:42.525Z
Learning: Before claiming a PR is mergeable or Ready for Review, run the `pr-review-gate` skill; green checks and `reviewDecision` do not override unresolved bot threads blocking `main`.

Learnt from: CR
Repo: tikoci/rosetta

Timestamp: 2026-07-17T17:56:42.525Z
Learning: Do not trust the checkout's root `ros-help.db` for grounding claims until it is verified with `make db-doctor`; use `make db-sync` to fetch the latest CI release database when needed.

🪛 LanguageTool

CLAUDE.md

[uncategorized] ~64-~64: The official name of this software platform is spelled with a capital “H”.
Context: ...DB (the grounding source of truth). See `.github/instructions/local-db-grounding.instruc...

(GITHUB)

MANUAL.md

[uncategorized] ~126-~126: The official name of this software platform is spelled with a capital “H”.
Context: ...'s local build is never clobbered). See `.github/instructions/local-db-grounding.instruc...

(GITHUB)

🔇 Additional comments (17)

scripts/db-doctor.ts (1)

1-60: LGTM!

scripts/db-sync.ts (1)

1-71: LGTM!

package.json (1)

25-27: LGTM!

Makefile (1)

14-14: LGTM!

Also applies to: 25-40

src/release.test.ts (1)

106-137: LGTM!

src/setup.test.ts (1)

269-307: LGTM!

.github/instructions/local-db-grounding.instructions.md (1)

5-59: LGTM!

CHANGELOG.md (1)

27-28: LGTM!

CLAUDE.md (1)

64-64: LGTM!

MANUAL.md (1)

118-127: LGTM!

VALIDATION.md (1)

30-30: LGTM!

src/paths.ts (1)

83-88: LGTM!

src/paths.test.ts (1)

1-112: LGTM!

src/setup.ts (1)

45-54: LGTM!

Also applies to: 166-199

src/db.ts (1)

41-41: LGTM!

Also applies to: 1033-1069

src/mcp.ts (1)

74-74: LGTM!

Also applies to: 168-191, 941-956

src/query.test.ts (1)

2160-2173: LGTM!

[mobileskyfi]

Codex review/POV

I’d request changes before merging PR #113. The core direction is strong, but the trust verdict and sync path still have false-success cases—exactly the kind
that coding agents will accept too readily.

Findings

1. P1 — db-sync can report success without installing its selected release.
   src/setup.ts:427 reuses any schema-compatible DB after lock contention before considering urlsOverride. Consequently scripts/db-sync.ts:56 can print “Synced”
   while retaining an older or unrelated DB. With an explicit override, reuse must verify the target release or reacquire the lock and perform the requested
   download.

2. P1 — “newest release matching this checkout’s schema” is not implemented.
   scripts/db-sync.ts:34 selects only the first release containing the asset, then downloads that single URL. Once a newer release has a different schema, an
   older checkout fails even if a compatible release exists immediately below it. It should pass the ordered candidate URLs to downloadDb, which already
   continues after schema mismatch.

3. P1 — incomplete provenance can still produce grounding.status: "ok".
   src/paths.ts:227 permits missing db_meta.schema_version, while built_at is unused and source_commit is checked only for presence. Thus {release_tag,
   source_commit} plus a matching pragma can be trusted even though the release invariant requires all four provenance stamps. For an agent-facing trust signal,
   missing/invalid provenance should fail closed with something like provenance_incomplete.

4. P2 — ok means schema/version-compatible, not “matches the codebase.”
   src/paths.ts:241 deliberately accepts a future release base as ok, and does not establish whether source_commit relates to the checkout. Either tighten the
   verdict or consistently describe it as “compatible with this build,” not proof that the DB matches the code being read.

5. P2 — the normal TUI stats screen does not show the grounding verdict.
   src/browse.ts:1086 displays a one-line provenance label and counts, but not provenance.grounding. That contradicts the PR’s claim that the TUI stats screen
   inherits the verdict.

The strongest parts are the internal_inconsistent detection, the routeros_stats provenance block, agent-readable tool description, dev startup warning, and
documentation routing. The live db-doctor also correctly classified the current rc.102 artifact as OK; its source commit is an ancestor of the PR head.

Validation: 418 targeted tests passed, typecheck and Biome passed, all review threads are resolved, and GitHub currently reports mergeStateStatus: CLEAN. Those
gates do not exercise the explicit-override contention path or compatible-release fallback, so I would still treat findings 1–3 as merge blockers.

[mobileskyfi]

Thanks — this was a sharp review; all five addressed in d5e9bd9.

P1 #1 — db-sync false success under lock contention. downloadDb now takes a forceDownload path when an explicit urlsOverride is passed (db-sync): it no longer returns a reused schema-compatible DB on contention. It still waits for the other process to release the lock (waitForUsableDb returns once the lock file disappears), then re-acquires the lock and downloads the requested release. A reused/older DB can no longer be reported as "Synced".

P1 #2 — "newest matching this checkout's schema" now implemented. db-sync collects the whole ordered candidate list (newest-first, prereleases included) and hands all URLs to downloadDb, which validates each schema and continues past a mismatch — so an older checkout walks down to the newest compatible release instead of failing on a higher-schema newest release.

P1 #3 — incomplete provenance no longer grounds. New provenance_incomplete status. A DB that claims release identity (release_tag or source_commit) but is missing any of the four CI stamps (release_tag/source_commit/built_at/schema_version) now fails closed, as does a stamped-but-unparseable version. built_at is now load-bearing, not merely read. Regression tests added.

P2 #4 — "ok" wording. Reframed as schema/release-compatible with this build (coherent schema, complete provenance, release not behind) — explicitly not proof the DB was built from the exact checked-out commit (a release DB is built from an ancestor; db-doctor reports that commit for inspection). Updated in the routeros_stats description, the classifier doc, MANUAL.md, and the instructions file.

P2 #5 — TUI verdict. The browse stats screen now renders a Grounding: line (status + detail when not ok), so the "TUI inherits the verdict" claim holds.

Gate after the fix: bun test 918 pass / 0 fail (+ new provenance_incomplete + ordered-list-handoff coverage), typecheck / Biome / markdownlint / cspell clean; live db-doctor still classifies the rc.102 artifact OK. The contention path (P1 #1) is a control-flow guard I verified by reading rather than an automated test — downloadDb's wait uses the 90s production timeout, so a faithful contention test would hang or need a 100+ page fixture DB; happy to add one if you'd prefer.

[mobileskyfi]

Codex re-review

Yes—I agree with the fixes. I found no remaining blocking issue on head d5e9bd9.

All five findings are addressed:

• Explicit db-sync overrides no longer reuse an arbitrary DB after lock contention.
• Candidate releases are tried newest-first until a schema-compatible DB is found.
• Partial provenance now fails closed as provenance_incomplete.
• ok is accurately described as schema/release-compatible, not exact-commit identity.
• The TUI displays the grounding verdict.

Validation is clean:

• 420 focused tests passed.
• Typecheck, Biome, Markdown lint, spelling, and git diff --check passed.
• Live db-doctor reports OK for rc.102.
• All required GitHub checks pass.
• Zero unresolved review threads.
• mergeStateStatus: CLEAN.

One non-blocking test gap remains: the lock-contention override and multi-candidate schema fallback are asserted structurally, not exercised as behavioral
regression tests. The implementation itself looks correct, so I would not hold this PR for that.

CodeRabbit skipped an incremental rereview because that feature is disabled, but the existing threads are resolved and I independently checked the new diff.
From my review, PR #113 is mergeable.