fix(share): add persistent exact updates

Author: steipete

CHANGELOG.md

@@ -4,6 +4,7 @@
 
 ### Fixes
 
+- Add persistent exact snapshot updates for dedicated Git-only readers so rows omitted by a newer filtered snapshot are removed without changing the merge-by-default behavior of richer local archives.
 - Skip Discord members with a missing user object during pagination and record conversion so public sync no longer panics on a nil `User`. Thanks @SebTardif.
 
 ## v0.13.2 - 2026-08-14

README.md

@@ -95,7 +95,7 @@ discrawl publish --check
 discrawl publish
 ```
 
-The preflight is read-only and reports the export scope before any snapshot is written. Published snapshots exclude wiretap direct messages and local failure history. See [Git snapshots](docs/guides/git-snapshots.md) for repository layout, filters, media handling, and update behavior.
+The preflight is read-only and reports the export scope before any snapshot is written. Published snapshots exclude wiretap direct messages and local failure history. Dedicated readers of privacy-filtered snapshots can subscribe with `--exact` so later omissions remove previously shared rows; normal subscriptions preserve richer local rows. See [Git snapshots](docs/guides/git-snapshots.md) for repository layout, filters, media handling, and update behavior.
 
 ## Automation
 

docs/commands/subscribe.md

@@ -14,6 +14,7 @@ discrawl subscribe --branch main https://github.com/example/discord-archive.git
 discrawl subscribe --stale-after 15m https://github.com/example/discord-archive.git
 discrawl subscribe --no-auto-update https://github.com/example/discord-archive.git
 discrawl subscribe --no-import https://github.com/example/discord-archive.git
+discrawl subscribe --exact https://github.com/example/public-archive.git
 discrawl subscribe --force https://github.com/example/discord-archive.git
 discrawl subscribe --with-embeddings https://github.com/example/discord-archive.git
 discrawl subscribe --no-media https://github.com/example/discord-archive.git
@@ -22,8 +23,9 @@ discrawl subscribe --no-media https://github.com/example/discord-archive.git
 ## What it does
 
 - writes a config with `discord.token_source = "none"` (so no bot token is required)
-- safely merges the latest snapshot into the local SQLite archive without deleting destination-only rows
+- safely merges the latest snapshot into the local SQLite archive without deleting destination-only rows by default
 - enables auto-refresh: read commands fetch and import when the local share import is older than `share.stale_after` (default `15m`)
+- with `--exact`, persists `share.update_mode = "exact"` and makes the initial import plus later manual and automatic updates mirror the current snapshot
 
 ## Flags
 
@@ -32,14 +34,17 @@ discrawl subscribe --no-media https://github.com/example/discord-archive.git
 - `--stale-after <duration>` - how stale the local import can get before read commands auto-refresh
 - `--no-auto-update` - disable auto-refresh (use [`update`](update.html) manually)
 - `--no-import` - write config only; skip the initial pull/import
-- `--force` - replace public snapshot tables so the local database exactly matches the snapshot
+- `--exact` - persist exact replacement for this dedicated reader; rows omitted by later snapshots are removed
+- `--force` - replace public snapshot tables for the initial import only; later updates still use the configured update mode
 - `--with-embeddings` - import vectors that match your local `[search.embeddings]` identity
 - `--no-media` - skip restoring cached attachment media files into `cache_dir/media`
 
 ## Disabled in this mode
 
 `sync` and `tail` are disabled when `discord.token_source = "none"` because they need live Discord access. Switch to a token-equipped config to re-enable them.
 
+Use `--exact` for a cache that must expose exactly the publisher's current privacy-filtered view. Do not enable it on a richer local archive: exact updates intentionally remove non-DM rows that are absent from the snapshot. The default merge mode remains appropriate for archives that also ingest Discord or desktop-cache data.
+
 ## After subscribing
 
 ```bash

docs/commands/sync.md

@@ -7,7 +7,7 @@ By default, `sync` runs both live/local sources and does **not** import the Git
 - Discord bot-token sync for bot-visible guild data
 - local Discord Desktop cache import for classifiable cached messages and proven DMs
 
-Use [`update`](update.html) when you want to pull/import the shared Git snapshot. Routine imports upsert changed shards without deleting local cache rows. If you intentionally want a sync run to import the snapshot before live deltas, pass `--update=auto` for a stale safe merge or `--update=force` for an exact replacement. `--no-update` is accepted as an explicit no-op alias for the default.
+Use [`update`](update.html) when you want to pull/import the shared Git snapshot. Routine imports upsert changed shards without deleting local cache rows. If you intentionally want a sync run to import the snapshot before live deltas, pass `--update=auto` for the configured stale update mode (merge by default) or `--update=force` for an exact replacement. `--no-update` is accepted as an explicit no-op alias for the default.
 
 Run one explicit `--full` pass when you want a complete historical guild archive. Use plain `sync` afterward for frequent latest-message and desktop-cache refreshes.
 
@@ -44,15 +44,15 @@ discrawl sync --with-media
 | Command | Use when | Behavior |
 | --- | --- | --- |
 | `discrawl sync` | routine refresh | skips member refreshes, checks live top-level channels plus active threads, only fetches new messages for channels with a stored cursor |
-| `discrawl sync --update=auto` | hybrid Git/live refresh | safely merges a stale Git snapshot first, then runs the routine live refresh |
+| `discrawl sync --update=auto` | hybrid Git/live refresh | applies the configured stale snapshot update mode first, then runs the routine live refresh |
 | `discrawl sync --update=force` | intentional exact reconciliation | replaces public snapshot tables first, then runs the routine live refresh |
 | `discrawl sync --all-channels` | repair pass | broad incremental sweep across every stored channel/thread, including archived threads |
 | `discrawl sync --full` | historical backfill | crawls older history until channels are complete |
 
 ## Flags
 
 - `--source <both|discord|wiretap>` - which archive sources to read
-- `--update <auto|force|none>` - safe-merge a stale snapshot, force an exact replacement, or skip snapshot import before live deltas
+- `--update <auto|force|none>` - apply the configured stale snapshot update mode, force an exact replacement, or skip snapshot import before live deltas
 - `--full` - historical backfill (slow on large guilds)
 - `--all-channels` - broader incremental sweep across every stored channel/thread
 - `--latest-only` - explicit latest-only run (also the default for untargeted `sync`)

docs/commands/update.md

@@ -2,7 +2,7 @@
 
 Pulls a Git snapshot and safely merges changed rows into the local cache.
 
-Routine imports are delta-planned from crawlkit shard fingerprints, with a Git-object fallback for older manifests. Changed and new shards are upserted without deleting destination-only rows. Discrawl never falls back to an exact replacement unless you pass `--force`.
+Routine imports are delta-planned from crawlkit shard fingerprints, with a Git-object fallback for older manifests. Changed and new shards are upserted without deleting destination-only rows. Discrawl never falls back to an exact replacement unless you pass `--force` or explicitly configure `share.update_mode = "exact"`.
 
 ## Usage
 
@@ -33,13 +33,14 @@ discrawl update --force --ref backup-2026-06-19
 - you set `--no-auto-update` when subscribing and want to refresh on demand
 - a CI job already imported the latest snapshot but read commands still consider it stale
 - you need an exact reconciliation after Discrawl reports removed shards or an incompatible table change (`discrawl update --force`)
+- this is a dedicated filtered-snapshot reader configured with `share.update_mode = "exact"`, so every update must remove rows no longer present upstream
 - you need to restore a named tag or commit while leaving the checked-out share branch untouched (`discrawl update --force --ref <ref>`)
 
-Normal updates preserve rows learned from live Discord or the desktop cache, even when those rows are absent from the Git snapshot. Generated event history and local sync cursors are not replayed during routine merges. If a safe merge is impossible, Discrawl keeps the current database, marks the snapshot as needing attention in `status --json`, and asks you to rerun with `--force`.
+Normal updates preserve rows learned from live Discord or the desktop cache, even when those rows are absent from the Git snapshot. Generated event history and local sync cursors are not replayed during routine merges. If a safe merge is impossible, Discrawl keeps the current database, marks the snapshot as needing attention in `status --json`, and asks you to rerun with `--force`. Exact mode instead replaces public snapshot tables on every update; use it only for a dedicated cache because destination-only non-DM rows are intentionally removed.
 
 ## How `sync` interacts
 
-`discrawl sync` does **not** auto-import the share unless `--update=auto` (safe merge when stale) or `--update=force` (exact replacement before live deltas). Routine live refreshes stay fast; explicit imports happen via `update`.
+`discrawl sync` does **not** auto-import the share unless `--update=auto` (configured update mode when stale) or `--update=force` (exact replacement before live deltas). Routine live refreshes stay fast; explicit imports happen via `update`.
 
 ## See also
 

docs/configuration.md

@@ -93,6 +93,7 @@ remote = ""
 repo_path = "~/.local/share/discrawl/share" # macOS: "~/Library/Application Support/discrawl/share"
 branch = "main"
 auto_update = true
+update_mode = "merge" # "exact" for a dedicated snapshot-only cache
 stale_after = "15m"
 media = true
 
@@ -145,6 +146,7 @@ Set `discord.token_source = "keyring"` if you want to require keyring lookup and
 - changing `db_path` does not migrate existing data; copy the file yourself if you want to keep history
 - `sync.attachment_media = true` makes `sync` behave like `sync --with-media`; media bytes are cached under `cache_dir/media`, and CDN `404`/other fetch failures are recorded on attachment rows
 - `share.media = false` makes publish/update/auto-update omit or skip restoring cached media; `subscribe --no-media` writes this for Git-only readers. With the default `share.media = true`, publish/update include cached non-DM media as gzip-compressed snapshot files, but publish does not fetch missing Discord files by itself.
+- `share.update_mode = "merge"` preserves destination-only rows during update and auto-update. Set it to `"exact"` only for a dedicated snapshot reader whose public tables must mirror the current snapshot; exact updates remove non-DM rows that the publisher omits. `subscribe --exact` writes this setting.
 - `[share.filter]` narrows only `publish` output; sync can still keep a richer local archive
 - `share.filter.public_only` exports only channels visible to the guild
   `@everyone` role after category/channel permission overwrites; private

docs/guides/git-snapshots.md

@@ -61,13 +61,14 @@ Once `share.remote` is configured, read commands auto-fetch and import when the
 ```bash
 discrawl subscribe --stale-after 15m https://github.com/example/discord-archive.git
 discrawl subscribe --no-auto-update https://github.com/example/discord-archive.git
+discrawl subscribe --exact https://github.com/example/public-archive.git
 ```
 
-`discrawl update` runs the same safe pull/merge step manually. `discrawl update --force --ref <tag-or-commit>` reads historical Git objects directly and leaves the share checkout unchanged. Snapshot imports are delta-planned from crawlkit shard fingerprints. Older manifests without those fields fall back to Git blob identity, so the common publish shape only imports changed canonical shards. Routine merges preserve destination-only rows and do not replay generated event history or remote sync cursors.
+`discrawl update` runs the configured pull/import step manually. The default `share.update_mode = "merge"` is delta-planned from crawlkit shard fingerprints. Older manifests without those fields fall back to Git blob identity, so the common publish shape only imports changed canonical shards. Routine merges preserve destination-only rows and do not replay generated event history or remote sync cursors. `subscribe --exact` persists exact replacement for a dedicated snapshot-only cache, so rows omitted from newer privacy-filtered snapshots are removed during both manual and automatic updates.
 
-Discrawl does not silently fall back to a full import. Removed shards and incompatible table changes leave the current database intact and require `discrawl update --force`. Forced updates replace public snapshot tables and rebuild search indexes; local DM rows remain untouched.
+Discrawl does not silently fall back from merge mode to a full import. Removed shards and incompatible table changes leave the current database intact and require `discrawl update --force`. Forced and configured exact updates replace public snapshot tables and rebuild search indexes; local DM rows remain untouched. Exact mode intentionally removes other destination-only rows, so do not use it on a richer archive that also ingests live Discord or desktop-cache data. `--force` is a one-shot override; `--exact` is the persistent subscription contract.
 
-`discrawl sync` does **not** auto-import the share unless `--update=auto` or `--update=force` is provided. Auto mode uses the safe merge; force mode performs exact replacement before live deltas.
+`discrawl sync` does **not** auto-import the share unless `--update=auto` or `--update=force` is provided. Auto mode uses the configured update mode (merge by default); force mode performs exact replacement before live deltas.
 
 ## Hybrid mode
 

internal/cli/cli.go

@@ -820,15 +820,16 @@ func (r *runtime) autoUpdateShare(mode shareUpdateMode) error {
 		return err
 	}
 	r.setSyncLockPhase("share import")
-	if mode == shareUpdateForce {
+	exact := mode == shareUpdateForce || r.cfg.ShareUpdatesExact()
+	if exact {
 		_, _, err = share.Replace(r.ctx, r.store, opts)
 	} else {
 		_, _, err = share.MergeIfChanged(r.ctx, r.store, opts)
 	}
 	if errors.Is(err, share.ErrNoManifest) {
 		return nil
 	}
-	if errors.Is(err, share.ErrReplacementRequired) && mode != shareUpdateForce {
+	if errors.Is(err, share.ErrReplacementRequired) && !exact {
 		r.logger.Warn("share update requires forced exact reconciliation", "error", err)
 		return nil
 	}

internal/cli/cli_test.go

@@ -1279,17 +1279,19 @@ func TestReadCommandsCanDisableAutoImportWithEnv(t *testing.T) {
 	require.Empty(t, lastImport)
 }
 
-func TestSubscribeNoMediaPersistsShareMediaOptOut(t *testing.T) {
+func TestSubscribePersistsExactModeAndMediaOptOut(t *testing.T) {
 	ctx := context.Background()
 	dir := t.TempDir()
 	cfgPath := filepath.Join(dir, "config.toml")
 
 	var out bytes.Buffer
-	require.NoError(t, Run(ctx, []string{"--config", cfgPath, "subscribe", "--no-import", "--no-media", "https://github.com/example/archive.git"}, &out, &bytes.Buffer{}))
+	require.NoError(t, Run(ctx, []string{"--config", cfgPath, "subscribe", "--no-import", "--exact", "--no-media", "https://github.com/example/archive.git"}, &out, &bytes.Buffer{}))
 
 	cfg, err := config.Load(cfgPath)
 	require.NoError(t, err)
 	require.False(t, cfg.ShareMediaEnabled())
+	require.Equal(t, config.ShareUpdateModeExact, cfg.Share.UpdateMode)
+	require.True(t, cfg.ShareUpdatesExact())
 }
 
 func TestSubscribeCloudDoesNotCreateLocalDB(t *testing.T) {
@@ -2333,6 +2335,18 @@ func TestShareUpdateImportsNewRemoteSnapshot(t *testing.T) {
 	require.NoError(t, Run(ctx, []string{"--config", readerCfgPath, "search", "newer snapshot"}, &out, &bytes.Buffer{}))
 	require.Contains(t, out.String(), "newer git snapshot arrived")
 
+	readerCfg.Share.UpdateMode = config.ShareUpdateModeExact
+	readerCfg.Share.StaleAfter = "1ns"
+	require.NoError(t, config.Write(readerCfgPath, readerCfg))
+	out.Reset()
+	require.NoError(t, Run(ctx, []string{"--config", readerCfgPath, "search", "newer snapshot"}, &out, &bytes.Buffer{}))
+	reader, err = store.Open(ctx, readerCfg.DBPath)
+	require.NoError(t, err)
+	_, rows, err = reader.ReadOnlyQuery(ctx, `select count(*) from messages where id = 'local-only'`)
+	require.NoError(t, err)
+	require.Equal(t, "0", rows[0][0], "configured exact auto-update must remove destination-only rows")
+	require.NoError(t, reader.Close())
+
 	out.Reset()
 	require.NoError(t, Run(ctx, []string{"--config", readerCfgPath, "update", "--force"}, &out, &bytes.Buffer{}))
 	require.Contains(t, out.String(), "forced=true")

internal/cli/output.go

@@ -207,7 +207,7 @@ Generate the archive activity report.
 
 Check configuration, storage, credentials, and optional services.
 `,
-	"subscribe": `Usage: discrawl subscribe [--repo PATH] [--branch NAME] [--stale-after DURATION] [--no-auto-update] [--no-import] [--force] [--with-embeddings] [--no-media] REMOTE
+	"subscribe": `Usage: discrawl subscribe [--repo PATH] [--branch NAME] [--stale-after DURATION] [--no-auto-update] [--no-import] [--exact] [--force] [--with-embeddings] [--no-media] REMOTE
 
 Configure and optionally import a read-only snapshot subscription.
 `,