## Summary
This PR is Phase 7 of 7 in the [AERIE-1838 — Map phased OCR and image document extraction rollout](https://linear.app/builder-team/issue/AERIE-1838/map-phased-ocr-and-image-document-extraction-rollout). It adds a controlled selector for historical document-knowledge backfill candidates. The selector admits only existing Drive-backed documents with a current not_searchable ingest result for ocr_required, or an unsupported_type result whose persisted MIME is exactly image/jpeg, image/png, image/gif, or image/webp.
This phase is tracked by [AERIE-1845 — OCR rollout 7/7: Add controlled historical OCR backfill selection](https://linear.app/builder-team/issue/AERIE-1845). Revision fencing and the existing backfill lifecycle remain in place. Merging this change does not start pilot or all mode, and no historical backfill is run by this change.
## Why
Historical selection must not turn every in-scope document into a new generation request. The selector needs to distinguish documents that currently require OCR from ready documents, stale or unrelated outcomes, unsupported image types, and records whose document or Site identity no longer matches. Narrowing membership to those current signals keeps a future explicit rollout bounded and prevents selection from bypassing existing lifecycle safeguards.
## Business Value
- Prevents unintended OCR and generation work for ready, stale, mismatched, or unsupported records.
- Extends the existing historical selector to recover OCR-required documents and the exact supported image types without broadening source eligibility.
- Preserves Site scope, revision fencing, continuation handling, deduplication, attempt limits, lease behavior, and stale-delivery protection already used by the backfill lifecycle.
- Keeps historical processing an explicit, reviewable rollout action: merging this code does not start pilot or all mode and does not run a backfill.
## How does it work
1. On each existing 50-item historical membership page, a document must have a public identity and a matching document-knowledge state: the state points to the same document and Site, has sourceKind: "drive", and is not removed.
2. The selector rejects a document when its current version is already at the state's desired generation, so a ready current version is not selected.
3. The state's latest job must be an ingest job for the same document and Site, at the desired generation, with status not_searchable.
4. The latest job must record ocr_required, or record unsupported_type with one of the exact case-sensitive MIME values image/jpeg, image/png, image/gif, or image/webp. Other image types, case variants, and missing MIME values are not selected.
5. An eligible document continues through the existing backfill generation lifecycle. Pilot and all mode use this same predicate, while existing Site-scope checks, revision checks, opaque continuation claims, page size, duplicate protection, and stale-delivery handling remain unchanged.
## Scope
Included behavior:
- Controlled historical membership selection for current Drive-backed OCR candidates.
- Matching document/Site identity, desired-generation, latest-job, status, and ready-version checks.
- Exact supported-image MIME matching for image/jpeg, image/png, image/gif, and image/webp.
- The existing lifecycle request for an eligible not_searchable candidate, with existing protections for queued, processing, and terminal work preserved.
- Exact final diff paths:
- chat/convex/documentKnowledge/backfill.ts
- chat/convex/documentKnowledge/backfill.test.ts
Deliberately excluded:
- Changes to rollout configuration, pilot/all controls, or configuration reindex behavior.
- Automatic rollout activation, OCR/provider behavior, or running a historical backfill.
- New schema, UI, API, MCP, or document source surfaces.
- Changes to the existing continuation, fencing, claims, deduplication, attempt-cap, lease, stale-delivery, Site-scope, or processing-gate contracts.
## Test plan
- cd chat && pnpm vitest run convex/documentKnowledge/backfill.test.ts convex/documentKnowledge/configurationReindex.test.ts — 2 files and 16 tests passed.
- cd chat && pnpm vitest run convex/documentKnowledge/lifecycle.test.ts convex/documentKnowledge/processing.test.ts convex/documentKnowledge/runtimeConfig.test.ts — 3 files and 67 tests passed.
- pnpm --dir chat typecheck — passed.
- pnpm --dir chat lint — Biome checked 1,951 files with no fixes applied.
- pnpm lint:boundaries, pnpm lint:convex-paths, and pnpm lint:read-bounds — all passed.
- Exact-scope and diff checks — the candidate is a direct child of current main, contains exactly the two paths listed above, and git diff --check passed.
- No rollout activation or historical backfill was run during these checks.
## Release checks
- Reconfirm that the exact final PR head has current main as an ancestor and contains only the two authorized paths listed in Scope.
- Require all hosted CI checks to be green on that exact final PR head.
- Require Mercy approval for that exact final PR head.
- Confirm the read-only development rollout check: mode pilot, revision 1, the current historical run is completed, membership is complete, there is no continuation, and the processing gate is enabled. This shows that existing durable rollout state will not automatically start newly eligible work when this code is merged.
- Merge only after the current-main ancestry, exact diff, hosted CI, Mercy approval, and no-auto-start check are all confirmed. Merging does not start pilot or all mode, and no historical backfill is run.