# CV-IMPORT implementation plan

26 October 2026. Owner-authorised development work; no production operations, main merge, Phase 10 or live generative-model qualification.

## Entry and baseline

Clean starting branch `feature/cv-editor-flowcv-redesign`, local and fetched remote HEAD `4a0af6273b4d45f652c7e0dee69c2c668e1a9ac5`. New branch `feature/cv-import-docling-ai` descends from that commit. The current request explicitly starts this work and supersedes the earlier deferred import specification.

Read `docs/cv-redesign/ACCEPTANCE.md`, `CV_IMPORT_HANDOFF.md`, and `docs/architecture/current.md` -> `overview.md`. CV-UX automated development PASS / overall CONDITIONAL GO permits separately authorised development. Its live-model, human, hosted and production limitations persist. Legacy parsing remains available until replacement qualification.

Fresh entry MariaDB run: `.artifacts/cv-import/entry-mariadb-01/run.json`, 64 passed, zero failures/skips; migration/rollback and frozen-package tests included. Generated project `jobtracker-it-d19819d1e7d44ab5aa3e9845db130f0d`, loopback ephemeral port/tmpfs, server 12.2.2; all startup/test/cleanup commands exited 0. Historical 1,234 backend / 981 frontend / 364 ordinary-browser results are baseline evidence, not results for this branch.

## Architecture and implementation matrix

| Existing functionality | Current owner | Proposed change | Compatibility impact | Required tests |
|---|---|---|---|---|
| Upload/storage | ProfileCvController.Upload / SaveUploadArtifactAsync | New qualified PDF/DOCX import route reusing artifact/run ownership; signature/archive validation; bounded retention | Keep legacy upload/text/image contract available | spoofing, archives, limits, interrupted upload, owner |
| Binary parser isolation | tools/summarizer app.py / parser_child.py | Pinned Docling adapter inside existing bounded child; structural blocks, page evidence; no implicit OCR/downloads/remote services | Preserve legacy extractor until new pipeline qualified | real synthetic PDF/DOCX, malformed inputs, timeout, cleanup |
| Extraction transport | SummarizerService / AiTextExtractionResult | Add explicit document extraction transport with blocks/warnings/method | Existing text API remains compatible | schema bounds, cancellation, error privacy |
| Structured profile | StructuredCvProfile / parsing partial | Conservative deterministic block interpretation, explicit unknowns; separate optional local-model adapter | No new canonical schema; no guessed experience, names or date precision | EN/NB fixtures, partial dates, ambiguous sections, injected output |
| Source evidence | StructuredCvFieldMetadata / CvExtractionRun | Persist document evidence and review decisions as additive run metadata | Existing profile history/CV overrides untouched | source IDs/pages/snippets, account export/deletion |
| Progress/recovery | cv.process / UserOperationStore / AiOperationWorker | Real stage updates preserving lease/recovery/cancel/retry owner | No second scheduler; no invented percentages | refresh, cancellation, stale lease, restart, deadlines |
| Review/merge | current run diff/accept / CvProfileDiffService | New explicit field decisions/corrections and conservative record matches; owned source endpoint | Legacy acceptance stays compatible; new engine cannot use implicit acceptance | keep/use/correct, duplicate dates, invalid IDs, stale review |
| Canonical persistence | CareerProfileService.ExecuteAtomicAsync / SaveVersionAsync | Apply only reviewed data under expected revision; idempotent acknowledgement | Existing IDs, relational children, history, projection, CV/letter snapshots preserved | SQLite + actual MariaDB rollback/concurrent/stale/duplicate apply |
| UI | CareerProfilePage / MUI / operations / EN/NB | PDF/DOCX entry, stage progress, adjacent source/review, explicit choices, completion/editor links | Keep text editing, legacy history and dirty drafts | unit + browser, responsive, axe, languages/themes |
| Qualification | existing test suites and PDF oracles | frozen synthetic import corpus, metric runner, separate deterministic/model results | No weakened oracle/test or inferred production acceptance | full suites, source hashes, exact count reconciliation |

```mermaid
flowchart LR
  Upload[Authenticated upload] --> Validate[File/signature/archive validation]
  Validate --> Artifact[Owned artifact and extraction run]
  Artifact --> Queue[Existing durable cv.process operation]
  Queue --> Child[Bounded parser child: Docling]
  Child --> Blocks[Structured blocks and provenance]
  Blocks --> Interpret[Deterministic interpretation]
  Blocks -. explicitly enabled local provider .-> Suggestions[Schema-constrained grounded suggestions]
  Suggestions --> Review[Owned review with corrections and decisions]
  Interpret --> Review
  Review --> Transaction[Expected revision + atomic CareerProfileService]
  Transaction --> Career[Canonical Career Profile]
  Career --> Editor[Existing CV Editor and PDF exporter]
```

## Checkpoints and completion contracts

1. **CV-IMPORT-00 audit**: this matrix, entry/provider evidence and plan; documentation validation, commit, push, remote equality.
2. **CV-IMPORT-01 secure extraction**: sidecar structural API and pinned dependency, real source fixtures/security tests; API secure admission/storage and evidence transport. Tests must fail before new behavior and pass after. Record actual Docling versus deterministic fallback separately.
3. **CV-IMPORT-02 interpretation**: canonical field mapping and provenance, conservative deterministic interpreter, configurable self-hosted adapter with strict schema/grounding tests. No inference/model artifact download. Unknowns remain unknown; date precision preserved.
4. **CV-IMPORT-03 lifecycle**: extend existing operation stage/lease mechanism, cancel/retry/recovery/retention. No timer-simulated completion. Focused operation/security tests.
5. **CV-IMPORT-04 review**: responsive adjacent source/review, granular keep/use/correct, source evidence, duplicate handling, stale comparison refresh, keyboard/localisation. Focused UI/browser tests; nothing persists before Apply.
6. **CV-IMPORT-05 canonical apply**: revision-aware transactional approved merge, idempotency, original-data/overrides/frozen-document preservation, provider migration/down-up, rollback and stale-write tests on actual MariaDB.
7. **CV-IMPORT-06 evaluation**: frozen nonpersonal corpus and ground truth; precision/recall/date/records/unsupported facts/duplicate/review burden/completion metrics; resource timings/security/cleanup. Keep development and frozen cases distinct. Real generative inference remains BLOCKED.
8. **CV-IMPORT-07 acceptance**: full repository-supported backend/frontend/browser/contracts/provider/RD21/Python/security/build/type/lint/preservation/PDF lanes, fresh artifacts and exact reconciliation; independent decisions and CV-QA-01 handoff.

Each completed checkpoint gets focused green evidence, documentation, commit, feature push and local/remote HEAD verification. Builds/browser/PDF/provider lanes are serialised; unrelated source-only/unit-test work may proceed independently. Failed attempts are retained. No checkpoint is accepted merely because implementation exists.

## Review focus

- Spoofed/expanded DOCX and PDF external content must be refused or treated as inert local data within hard limits.
- A model response may have valid JSON yet unsupported facts; source spans and field equality must reject it.
- Same employer/title with different employment dates must not silently collapse distinct jobs.
- Lost operation leases/cancellation must not publish later review results or resurrect deleted documents.
- Stale reviewed apply and repeat network delivery must not overwrite canonical edits or create duplicate history.

## Execution decisions

Use the current clean checkout on the requested isolated feature branch, retaining installed runtimes and accepted fixture artifacts. The explicit autonomous request supplies routine design/execution approval; no additional brainstorming approval loop is required. Source-only backend/frontend/sidecar work can be delegated with disjoint ownership; root owns commits, integration, serialized acceptance and evidence. Existing production/model/hosted claims remain unverified and are not prerequisites for the safe model-independent implementation.