fix: support exact snapshot updates

[steipete]

What

Add a persistent exact snapshot update mode for dedicated readers of privacy-filtered shares.

The existing monotonic merge behavior correctly preserves richer local rows. However, a dedicated reader could retain channels and messages after a newer privacy-filtered snapshot omitted them because their permissions had become private.

Why

PR #118 intentionally introduced merge-by-default so snapshot updates would not delete rows learned from live Discord or the desktop cache. The existing --force flag was deliberately a one-shot exact replacement, and there was no persistent contract for readers that should mirror every new snapshot exactly.

Fix

• Add share.update_mode = "merge" | "exact", defaulting to merge.
• Add subscribe --exact to persist exact mode for dedicated snapshot readers.
• Make initial subscription imports, manual updates, auto-updates, and sync --update=auto honor the configured mode.
• Keep --force as a one-shot exact replacement without changing the persisted mode.
• Do not infer update behavior from public_only; filtering and reader reconciliation remain separate choices.

Proof

• GOWORK=off go test ./...
• make fmt
• make lint
• Source-blind behavior validation: 6/6 clauses passed, covering merge preservation, persistent exact removal, auto-update, one-shot force, invalid configuration, and no Discord access.
• Codex autoreview: clean, with no accepted or actionable findings.
• git diff --check

No release was performed.

[clawsweeper]

🦞👀
ClawSweeper picked this up.

Pull request received. I will update this pull request when review starts.

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed August 16, 2026, 9:54 PM ET / August 17, 2026, 01:54 UTC.

ClawSweeper review

What this changes

This PR adds a persisted merge or exact snapshot-update mode and subscribe --exact, allowing dedicated snapshot readers to remove rows omitted by later filtered snapshots.

Merge readiness

⚠️ Ready for maintainer review - 1 item remains

Keep open for normal collaborator PR review. The opt-in exact mode preserves the established merge default, is wired through subscription, manual update, read-command refresh, and hybrid sync, and has focused regression coverage.

Priority: P2
Reviewed head: 4e196bee03a76629886d642d365bd858d308fa78

Review scores

Measure	Result	What it means
Overall readiness	🐚 platinum hermit (4/6)	A focused, documented implementation with regression coverage and no actionable correctness finding.
Proof confidence	🌊 off-meta tidepool	Not applicable: The author is a collaborator, so the external-contributor real-behavior-proof gate does not apply; the PR body nevertheless reports focused behavior validation.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Not applicable	Not applicable: The author is a collaborator, so the external-contributor real-behavior-proof gate does not apply; the PR body nevertheless reports focused behavior validation.
Evidence reviewed	4 items	Opt-in implementation: The branch validates share.update_mode, defaults missing settings to merge, and uses exact replacement only when the saved mode is exact or the caller passes --force. All update paths covered: The branch routes configured exact mode through subscribe, update, and automatic refresh; sync --update=auto already flows through the same update-mode dispatcher. Regression coverage: Tests cover filtered-snapshot omissions, preserving rows in merge mode, exact removal, configuration normalization, and read-command auto-update without Discord credentials.
Findings	None	None.
Security	None	None.

How this fits together

Discrawl imports Git-hosted archive snapshots into a local SQLite cache. Subscription, manual update, automatic refresh, and hybrid sync select merge or exact reconciliation before search and sync commands use that cache.

flowchart LR
  A[Git snapshot] --> B[Subscribe update or sync]
  C[Saved update mode] --> D[Choose merge or exact]
  B --> D
  D --> E[Local SQLite archive]
  E --> F[Search and sync commands]

Loading

Before merge

• Complete next step (P2) - Normal collaborator PR review is the remaining action; no narrow automated repair is indicated.

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Code and regression scope	production +29/-5, tests +93/-2	The small production change is accompanied by substantially more targeted coverage for update semantics.
Files affected	14 files: 4 production, 3 tests, 7 docs/release notes	The changed contract is consistently reflected in implementation, validation, CLI help, and user documentation.

Technical review

Best possible solution:

Land the explicit opt-in exact mode while retaining merge as the default for existing and richer local archives.

Do we have a high-confidence way to reproduce the issue?

Not applicable: this PR adds an explicit operating mode rather than reporting a currently reproducible defect.

Is this the best way to solve the issue?

Yes. A persisted, opt-in exact mode solves dedicated-reader reconciliation without changing the documented merge default for existing archives.

AGENTS.md: not found in the target repository.

Codex review notes: model internal, reasoning high; reviewed against b560fd127b34.

Labels

Label changes:

• add P2: This adds a bounded snapshot-reconciliation capability without evidence of an urgent active user outage.
• add rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit.
• add status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: The author is a collaborator, so the external-contributor real-behavior-proof gate does not apply; the PR body nevertheless reports focused behavior validation.

Label justifications:

• P2: This adds a bounded snapshot-reconciliation capability without evidence of an urgent active user outage.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: The author is a collaborator, so the external-contributor real-behavior-proof gate does not apply; the PR body nevertheless reports focused behavior validation.

Evidence

What I checked:

• Opt-in implementation: The branch validates share.update_mode, defaults missing settings to merge, and uses exact replacement only when the saved mode is exact or the caller passes --force. (internal/config/config.go:335, 4e196bee03a7)
• All update paths covered: The branch routes configured exact mode through subscribe, update, and automatic refresh; sync --update=auto already flows through the same update-mode dispatcher. (internal/cli/cli.go:823, 4e196bee03a7)
• Regression coverage: Tests cover filtered-snapshot omissions, preserving rows in merge mode, exact removal, configuration normalization, and read-command auto-update without Discord credentials. (internal/share/merge_test.go:132, 4e196bee03a7)
• Established merge contract: Current main documents and implements merge-without-deletion as the existing behavior; the related merged work is fix: make routine snapshot updates monotonic #118. (internal/share/merge.go:48, 54eb70cfb320)

Likely related people:

• steipete: The merged monotonic snapshot-update work and this PR both originate from the share-import surface. (role: feature owner and recent area contributor; confidence: high; commits: 77e286f09657, 54eb70cfb320; files: internal/share/merge.go, internal/cli/cli.go, internal/cli/share_commands.go)

Rating scale

Score	Internal tier	Crab rank	Meaning
6/6	S	🦀 challenger crab	Exceptional readiness
5/6	A	🦞 diamond lobster	Very strong readiness
4/6	B	🐚 platinum hermit	Good normal PR; ordinary maintainer review
3/6	C	🦐 gold shrimp	Useful, but confidence is limited
2/6	D	🦪 silver shellfish	Proof or implementation needs work
1/6	F	🧂 unranked krab	Not merge-ready
N/A	NA	🌊 off-meta tidepool	Rating does not apply

Overall follows the weaker of proof and patch quality.
Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

Workflow

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.