[knqiufan]

Which issue or RFC does this PR close?

Closes #2169.

Rationale for this change

Archive validation performs one target lookup per record. Batching reduces compatibility queries for 5,000 Sources, one Scope, and one journal head from 5,002 to 52 while retaining per-record decoding, dependency validation, and digest comparisons.

What changes are included in this PR?

• Group target lookups by record type into bounded UNION ALL statements: up to 100 branches per statement, 900 pending parameters, and 1 MiB of encoded pending keys/digests.
• Carry archive ordinals through SQL to preserve database collation and alternate unique-key semantics. Any differing match counts as one conflict; nullable alternate keys retain SQL NULL behavior.
• Retain keys/digests instead of archive bodies and stream target results one row at a time.
• Preserve fresh restore-time validation, write-time conflicts and rollback, publication/tag integrity checks, and projection receipts.
• Emit target progress after every completed batch so counts that skip multiples of 1,000 still produce intermediate updates.
• Cover classification, query budgets, wide keys, collation, nullable keys, cancellation/retry, large payloads, changes after dry-run, and intermediate progress for absent, empty, and identical targets.
• Include a reproducible SQLite benchmark and English/Chinese operator documentation.

Are there any user-facing changes?

Archive dry-run, restore validation, and idempotent retry perform fewer database executions. Target-check progress is reported after each completed batch. Public APIs, schemas, archive formats, and conflict classification are unchanged.

Recorded file-backed SQLite measurements from 2026-10-23 show 5,002-record validation decreasing from 16.3445 to 9.1713 seconds for an empty target and from 16.9955 to 10.7552 seconds for an identical target. These are medians of three runs on Windows 11, CPython 3.12.13, and SQLite 3.50.4 with 256-byte Source content and no injected network delay. Environment, baseline, query counts, restore timing, and qualification limits are documented in both locales; these measurements are not a general backend throughput guarantee.

How was this change tested?

• Windows SQLite/CLI/archive validation: 203 passed, 63 skipped; the target-progress regression is covered.
• macOS arm64, CPython 3.12.15, pylibseekdb 1.4.0.post1: all 31 SeekDB portable archive scenarios passed, including the 205-Source batch, restore-time revalidation, idempotent retry and reopen scenario.
• After integrating current master, SQLite/CLI/archive tests: 203 passed, 32 skipped (SeekDB deselected; unconfigured OceanBase cases skipped).
• Upgrade gate, publication and schema-equivalence tests with PC_UPGRADE_SOURCE_SHA and GITHUB_SHA injected: 124 passed, 6 skipped. Disposable release fixtures isolate checkout identity from CI environment variables while retaining the explicit source-identity override test.
• CI change-selection and workflow contracts: 76 passed.
• macOS arm64 Desktop UI suite: 98 passed; TypeScript and changed-file Prettier checks passed (Node 24.22.1, pnpm 11.13.1; Intel macOS Desktop CI also passed).
• Repository-wide uv run --locked prek run -a, immutable workflow action checks and git diff --check: passed.

SeekDB batching runs in both Python 3.11 and 3.14 CI jobs. Topic Memory migration scenarios keep a native SeekDB lease across independent maintenance connections to avoid the known rapid-restart runtime-lock stall; separate restart/exclusion acceptance remains intact. The Desktop connection-transition journey has a 15-second per-test timeout for shared Intel macOS runners, with all behavior assertions retained.

The real OceanBase CI job explicitly runs test_archive_batches_validation_and_rechecks_after_dry_run[server] and rejects skipped results. No local OceanBase instance was available. At commit 1a56ace8, real OceanBase acceptance passed, including the exact archive case above. Python 3.11/3.14 SeekDB archive checks and Intel macOS Desktop checks also passed. Main CI and the upgrade summary gates passed. The SeekDB no-vector upgrade first timed out while native DDL waited for transactions; an unchanged rerun passed all 11 acceptance tests in 474.67 seconds. This qualifies the tested upgrade path but does not establish that the intermittent native-engine stall is fixed. All required CI checks are green for the reviewed head; the PR is ready for review.

AI usage statement

OpenAI Codex assisted with implementation, regression tests, documentation, and local review using the Open Code Review plugin's delegation rules. The original optimization and benchmark also used the plugin's configured DeepSeek Flash provider for automated review.

[hidb4ai]

One non-blocking progress-reporting regression in the batching change.

[hidb4ai]

LGTM