fix(integrity): safe hydration --repair with snapshot + drift detection + re-emit (#602)

[dollspace-gay]

Summary

Fixes GH#602. crosslink integrity hydration --repair used to call clear_shared_data() followed by hydrate_to_sqlite(). Any SQLite row not represented in JSON was silently destroyed in the clear step. And the drift detection above the repair only compared issue/milestone counts, so content-level divergence (e.g. a dependencies (a, b) row in SQLite that no JSON file mentions) never registered as drift at all.

Implements all four mitigations from the issue, in the order it ranked them.

(1) Always snapshot before destroying state

Every --repair run writes .crosslink/integrity/hydration-backup-<utc-ts>.sqlite via SQLite's VACUUM INTO. Self-contained (works in WAL mode), reversible (drop it in place), and unconditional — runs even when the repair was non-destructive, as an audit trail of what state the repair was applied against.

New module: crosslink/src/db/snapshot.rs.

(2) Detect drift by content, not by count

New module commands::integrity_drift. detect() hydrates JSON into an isolated temp SQLite file (reusing the production hydrate_to_sqlite), ATTACH-es that file to the main connection, and SQL-diffs every shared table:

• issues, labels, dependencies, relations, milestone_issues, comments, time_entries

Returns a categorized HydrationDriftReport with is_empty(), has_unrecoverable_loss(), and is_fully_re_emittable() semantics. The reproducer scenario from the issue (INSERT INTO dependencies directly into SQLite) now shows up in sqlite_only_dependencies where the old count-based check was blind to it.

(3) Re-emit SQLite-only state back to JSON when possible

re_emit() walks the drift report and calls SharedWriter::{add_label, add_blocker, add_relation, set_milestone_on_issues} for each row. The SharedWriter idempotency short-circuits from #600 (PR #605) mean these calls are safe even if the JSON side raced ahead between detection and re-emit.

Comments and time entries are NOT re-emitted:

• Comments: re-emit would generate a new UUID and lose the original identity — the snapshot is their recovery handle.
• Time entries: no SharedWriter API exists for them; they're written directly to SQLite by crosslink timer. Snapshot is the recovery handle.

(4) --accept-data-loss flag gates destructive repair

New CLI flag on crosslink integrity hydration. When drift contains rows that re-emit cannot represent, or when no SharedWriter is available (no agent.json / no hub branch), --repair refuses without the flag, prints the snapshot path, and exits non-zero. With the flag, proceeds destructively (snapshot is still written).

Behavior the user will notice

• --repair always writes a snapshot at .crosslink/integrity/hydration-backup-<utc-ts>.sqlite (was: silent destroy).
• --repair now tries to re-emit SQLite-only labels/deps/relations/milestone-links back to JSON via the writer — each becomes a real git commit on the hub branch.
• --repair refuses when SQLite has comments or time entries that aren't in JSON, unless --accept-data-loss is also given.
• Hydration check (without --repair) now surfaces content-level drift (e.g. "1 sqlite-only dependency(ies)") that the old count check missed.

Dependency change

tempfile moved from [dev-dependencies] to [dependencies] — the drift detector uses a temp SQLite file at runtime for the JSON-view ATTACH. No new transitive deps; the crate was already in the dev tree.

Out of scope

• Snapshot retention / pruning. Hydration snapshots accumulate under .crosslink/integrity/. Could add a --prune-snapshots flag or a TTL in a follow-up.
• Re-emit for sqlite-only issues. The existing #427 self-heal in hydrate_to_sqlite already preserves created_by IS NULL issues; full re-emit for SharedWriter-created issues with no JSON would mean a recursive create_issue path (parents, comments, the full graph), better as its own design.
• Add a SharedWriter API for time entries. Same out-of-scope reasoning — separate feature.

Test plan

• cargo test --lib --bin crosslink — 2875 passed (+9 new)
• cargo clippy --lib --bin crosslink --tests -- -D warnings — clean
• Snapshot tests: file created, integrity dir auto-created, UTC timestamp format
• Drift detection tests: empty state, label-only drift, comment-only drift (unrecoverable), reproducer-scenario sqlite-only dependency
• End-to-end re-emit integration test (test_re_emit_writes_sqlite_only_dependency_to_json): real SharedWriter + hub cache, injects SQLite-only dep, runs detect + re_emit, asserts JSON now contains the row and detect returns clean
• Manual repro from the issue:

  crosslink issue create "first"  -q   # → L1
  crosslink issue create "second" -q   # → L2
  sqlite3 .crosslink/issues.db \
    "INSERT INTO dependencies (blocker_id, blocked_id) VALUES (1, 2);"
  crosslink integrity hydration                # should now report "1 sqlite-only dependency(ies)"
  crosslink integrity hydration --repair       # should snapshot, re-emit, and the dep should survive
  crosslink issue show L2 | grep -i blocked    # → Blocked by: L1 (preserved)

Related

• crosslink issue block exits non-zero when the blocker is already set #600 (PR fix(shared-writer): make blocker/label/relation mutations idempotent (#600) #605) — SharedWriter idempotency. This PR's re-emit path relies on those short-circuits being in place.
• git_commit_in_cache_with_args reports empty error messages for the most common failure mode #601 (PR fix(shared-writer,sync): include stdout in git cache-failure errors (#601) #606) — git error messages. Same code area, separate concern.
• add_blocker flow is not transactional across JSON / git / SQLite #604 — add_blocker transactionality across JSON/git/SQLite. Structurally complementary: that one is about how drift is produced, this one is about how drift is destroyed.

🤖 Generated with Claude Code