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

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 -. future qualified local provider integration .-> 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

CV-IMPORT-00 audit: this matrix, entry/provider evidence and plan; documentation validation, commit, push, remote equality.
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.
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.
CV-IMPORT-03 lifecycle: extend existing operation stage/lease mechanism, cancel/retry/recovery/retention. No timer-simulated completion. Focused operation/security tests.
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.
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.
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.
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.

8.2 KiB Raw Blame History