Skip to content

feat(cli): enforce mandatory sync and SQLite-only retrieval - #45

Merged
pablontiv merged 24 commits into
mainfrom
docs/issue-44-db-only-sync-design
Aug 21, 2026
Merged

feat(cli): enforce mandatory sync and SQLite-only retrieval#45
pablontiv merged 24 commits into
mainfrom
docs/issue-44-db-only-sync-design

Conversation

@pablontiv

@pablontiv pablontiv commented Aug 20, 2026

Copy link
Copy Markdown
Owner

What

  • enforce one root-owned startup sync before every operational command
  • remove public backscroll read, the singular internal/reader package, and every --indexed-only bypass
  • make SQLite the sole public retrieval source while preserving search --source-path as a query filter
  • allow only typed, recoverable index/sync failures to continue into recover
  • verify and sync an installed recovery database before reporting success
  • preserve structured JSON/robot startup diagnostics and dual recovery failure causes
  • add hermetic CLI, Markdown ingestion/retrieval, recovery, machine-output, and living-documentation contracts
  • record the architecture in ADR 0002 and the implementation design/plan

Why

The Go port reintroduced direct-file retrieval and handler-selected freshness, diverging from Backscroll's North Star: transient source files are ingested into a perennial SQLite event store, and users query that synchronized index.

This PR restores the database-only boundary and fails closed instead of returning cached rows when configuration, manifest validation, compatibility preparation, discovery, parsing, hashing, or sync fails.

Closes #44.

Architecture

Cobra PersistentPreRunE owns configuration loading, manifest preflight, index preparation, and exactly one startup sync. Handlers consume the synchronized configuration/index and never choose freshness themselves. Help/version remain side-effect free.

recover is the sole controlled continuation, and only for typed recoverable index-preparation or startup-sync failures. Successful replacement is followed by a post-install sync before success output.

Validation

  • just check
  • just test
  • just ci — aggregate coverage 85.0% (fresh raw profile 5033/5920 = 85.0169%)
  • rootline validate docs/adr/*.md --strict --output table
  • git diff --check
  • whole-branch architecture review plus scoped re-reviews of final recovery/error fixes
  • GitHub CI: Test & Build and gitleaks passed for head 9a4f302

Checklist

  • Tests pass (just test)
  • CI parity gate passes (just ci)
  • Code is clean (just check)
  • ADR records pass strict Rootline validation
  • User-facing living documentation and shipped skill updated

@pablontiv pablontiv changed the title docs: define mandatory sync retrieval invariant feat(cli): enforce mandatory sync and SQLite-only retrieval Aug 21, 2026
@pablontiv
pablontiv merged commit 6bc40f9 into main Aug 21, 2026
6 checks passed
@pablontiv
pablontiv deleted the docs/issue-44-db-only-sync-design branch August 21, 2026 05:23
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

bug: restore mandatory sync and database-only retrieval invariants

1 participant