feat(ncbivirus): native local filters + Filtered completeness; fix multi-page total reconciliation

[001TMF]

What & why

Makes the NCBI Virus connector run the exact kind of query VirBench's hard cases exercise — sequence-length, collection-date range, ambiguous-character ceiling, and lab-passaged exclusion — natively and deterministically, instead of only partially (post-hoc filtering outside the engine).

The NCBI Datasets v2 API cannot evaluate these server-side (the dataset_report exposes length, collection_date, isolate.name, and a sequence_hash, but no ambiguous-base count and no server filter for these fields). So the connector applies them as local predicates over the COMPLETE, count-reconciled candidate set and reports a new filtered completeness whose authoritative_count is the exact match count (a whole exhaustive scan, not a sample). This is strictly stronger than gget virus (which downloads + filters locally with no reconciliation).

New FilteredState completeness

• engine/contract: FilteredState + NewFiltered(matched, returned, reason) + IsExact(). ReconciledCount = records returned; AuthoritativeCount = exact match count (they differ only when an output limit truncates the returned records — so search --limit 1 still reports the true total).
• A filtered result is served live (deterministic, re-derivable by re-running) — it is not content-addressed as a reproducible snapshot, so the "snapshot ⇒ reconciled-complete" invariant Verify trusts is untouched.

Connector

• sequence_length (gte/lte), collection_date (gte/lte, interval-overlap semantics for partial dates), max_ambiguous_chars (lte), exclude_lab_passaged (eq).
• Multi-operator-per-field rule table (a two-sided range = two different operators on one field); duplicate (field, operator) rejected.
• New efetch endpoint supplies the sequence for the ambiguous-base count only — it never enters a RawRecord or the logical hash (sequences are immutable per accession.version, so the count is reproducible). Cheap report-only predicates run first; sequences are fetched only for survivors.

Bug fixes surfaced by this work

• Multi-page reconciliation (latent, affects the base connector): NCBI returns x-ncbi-total-count only on the first page of a token walk; continuation pages omit it. The walk previously read that absence as total=0 / a mid-walk mutation and downgraded every >1000-record query to best-effort. The page-0 total is now authoritative for the whole walk; only a present, differing total is a real mutation. (Prior multi-page fixtures set the total on every page, masking this — a new test reflects real NCBI behavior.)
• Completeness serialization: CompletenessState now marshals as its string token (matching schema/manifest.schema.json) rather than the raw uint8 ordinal, with a backward-compatible reader. The manifest is not content-addressed, so no snapshot hashes change.

Review

Cross-model reviewed (codex/GPT-5.5 independent pass + an adversarial Sonnet pass) — both SHIP, no P0. Their P1/P2 findings are folded in: reject duplicate (field, op); per-month/leap-year day validation in normalizeDate; propagate the FASTA scanner error.

Validated live

pinakes search against live NCBI returns state: "filtered" with exact dual counts (include vs exclude proven), the efetch ambiguous-base path works, and the full ZEBOV human query (taxid 3052462, 2014 outbreak window) reconciles natively.

Tests

Full local-filter path (Filtered exact count; limit bounds output not count; efetch only for report-survivors; lab-passaged; unreconciled candidate → best-effort), the multi-page total-header behavior, predicate units, and the contract codec/round-trip — all proven-by-revert. make ci green; govulncheck clean.

• case-studies/ebola: refreshed filter_logic_hash (the connector's published semantics changed — intended drift signal).

🤖 Generated with Claude Code