feat(ai): centralize durable usage

Add a content-free usage ledger with legacy backfill. Reserve Workspace and durable Strategy/CV work before execution so deleted history or duplicate admission cannot reset limits.

docs/verification/ai-002-provider-routing.md

@@ -30,7 +30,7 @@ Deterministic match, profile diff, keyword, email-classification and application
 
 `local_only`, `local_first` and `external_only` are supported. Invalid modes fail closed to `local_only`. `external_only` still requires explicit backend permission and an allowed task. The default remains `local_first`, while `EXTERNAL_AI_ENABLED=false` makes it effectively local-only.
 
-The external prompt ceiling is a per-request cost/privacy control, not a monthly spend ledger. Current plan-level monthly accounting covers AI Workspace interactions only; complete cross-feature accounting remains a POL-001/AI-003/AI-004 rollout gate.
+The external prompt ceiling remains a per-request cost/privacy control. A separate content-free monthly ledger now covers AI Workspace and the durable Strategy/CV producers, with conservative reservation before work and actual Strategy/Workspace estimates on success. Older synchronous generators still need the same admission boundary before accounting is universal.
 
 ## Backend integration
 
@@ -53,7 +53,7 @@ The external prompt ceiling is a per-request cost/privacy control, not a monthly
 
 - No Ollama model, external provider, paid API, real CV/email, production service or production egress was used.
 - PROD-001/003 must identify hardware and benchmark/select the primary and optional secondary local model. No secondary local model is configured yet.
-- AI-003/004 must register real Strategy/CV handlers, choose explicit task allowlists, pass cancellation through their work and verify retry/deduplication with durable results.
+- Strategy and CV have registered typed handlers, cancellation, retry/deduplication and durable results. They remain local-only until an explicit task allowlist and production-safe validation authorize otherwise.
 - The local circuit is intentionally process-local for the current single-sidecar deployment. Multi-replica or restart-persistent circuit coordination requires measured need and a separate design.
 - The existing named HTTP client still has a 30-second transport timeout for synchronous callers. AI-003/004 must move long work to durable handlers and align their cancellation/transport budget; increasing the synchronous timeout is not accepted as the timeout fix.
 - Browser disclosure, MariaDB execution, controlled synthetic provider fallback, production health/circuit telemetry and rollback/canary checks remain unverified.

docs/verification/ai-003-strategy-snapshot-queue.md

@@ -18,6 +18,7 @@ The Overview button in `JobDetailsDialog.tsx` called candidate fit and `GET /api
 - The handler makes one bounded structured generation request, validates the entire JSON shape before publishing, passes worker cancellation, records actual provider/model/route metadata and rejects embedded source instructions. Job text, profile text, structured profile and extracted attachment context have explicit ceilings.
 - UI states cover queued, local processing, retry wait, approved-fallback wait, completed, failed, cancelled and cancellation requested, with cancel/retry actions. A request-version guard prevents a stale resume lookup from erasing a newly queued operation.
 - The existing generic terminal notification is produced transactionally by the operation store. No email is sent.
+- Admission creates one content-free usage reservation in the same transaction as the operation. Duplicate clicks reuse it, and successful execution replaces the conservative 12,000-token reservation with the measured input/output character estimate.
 
 `strategy.snapshot` is not in the external fallback allowlist, so it remains local-only even when a user has external consent. The worker switch remains off by default pending the production canary.
 
@@ -36,7 +37,7 @@ The Overview button in `JobDetailsDialog.tsx` called candidate fit and `GET /api
 - No Ollama model, external provider, private CV, production service or paid API was called.
 - Worker/model restart and lease recovery are proven generically by AI-001 tests but not run with a real Strategy model.
 - MariaDB execution, production queue telemetry, selected-model timeout/quality benchmarks, notification navigation and deployment rollback remain unverified.
-- Cross-feature monthly token/cost accounting remains incomplete; the durable operation row prevents duplicate work and records execution provenance, but is not a billing ledger.
+- The Strategy operation now participates in the central monthly usage ledger. Older synchronous AI endpoints outside this workflow remain a separate POL-001 completion item.
 
 ## Rollback
 

docs/verification/ai-004-cv-processing-queue.md

@@ -19,6 +19,7 @@ CV upload previously saved an artifact and held the HTTP request while extractio
 - Upload/reprocess reopen the stored owner artifact in the worker. Rebuild/improve pass the worker cancellation token to the metadata-capable generation call.
 - Successful processing stops at `pending_review`. It does not update profile text/structure/current-version pointers until the existing accept endpoint is called. Discard remains available.
 - The UI shows queued, local processing, retry wait, approved-fallback wait, failed, cancelled and cancellation-requested states with cancel/retry actions. The upload spinner now ends after admission and reports the queued run rather than false extraction success.
+- Admission creates one content-free conservative usage reservation atomically with the operation. Active duplicates reuse it. CV processing intentionally retains the 16,000-token reservation because the multi-stage sidecar does not yet return complete per-stage usage telemetry.
 
 No dependency, schema, migration, proxy timeout or production switch changed. `Workers:AiOperationsEnabled` remains false by default.
 
@@ -40,7 +41,7 @@ No dependency, schema, migration, proxy timeout or production switch changed. `W
 - The generic lease tests cover restart recovery, but no CV parser/model process was interrupted and resumed in a runtime canary.
 - MariaDB, selected Ollama model, worker telemetry, production activation and rollback canary remain unverified. The worker stays default-off.
 
-The focused CV/operation/store regression slice is now 17/17 and the full backend is 660/660 after dormant-row cancellation/deadline/retry coverage.
+The focused accounting/operation/lifecycle regression slice passes 28/28 and the full backend is 663/663 after durable usage and dormant-row lifecycle coverage.
 
 ## Rollback
 

docs/verification/pol-001-free-pro-entitlements.md

@@ -11,22 +11,22 @@ Status: `IMPLEMENTED — NOT VERIFIED`. The server policy, worker rechecks, Free
 - Pro and Admin use AI and Pro CV themes. The persisted Identity role remains `Premium`, and `Stripe:PricePremium` remains a compatibility key; neither is exposed as a public plan name.
 - Current database roles are authoritative on every explicit HTTP AI action. A stale role claim cannot preserve access after downgrade.
 - A locked explicit action returns HTTP 403 with `{ "code": "pro_required", "message": "This AI feature requires Pro." }`.
-- Existing 250-call/1,000,000-token Pro ceilings remain because they are defined in the existing implementation roadmap. Free ceilings are zero. Only AI Workspace currently writes complete `AiInteraction` usage rows; this accounting gap blocks full verification and must be resolved as AI-001/AI-002 move all producers through durable operations.
+- Existing 250-call/1,000,000-token Pro ceilings remain because they are defined in the existing implementation roadmap. Free ceilings are zero. A content-free `AiUsageRecord` ledger is now authoritative for AI Workspace plus durable Strategy and CV work; legacy `AiInteraction` usage is backfilled. Older synchronous AI actions still need the same admission boundary before the numeric ceilings can be described as universal.
 
 ## Entry-point inventory
 
 | Capability | User entry / frontend | API or worker execution path | Admission and recheck | Usage accounting | Free behavior |
 |---|---|---|---|---|---|
-| AI Workspace modules | Job details → AI Workspace; `AiWorkspacePanel` | `POST /api/jobapplications/{jobId}/ai/generate` → `AiWorkspaceService` → `ISummarizerService` | `Pro` policy with live role lookup | `AiInteraction` call/token row; monthly check | Generate disabled; existing history/read/delete remain available |
+| AI Workspace modules | Job details → AI Workspace; `AiWorkspacePanel` | `POST /api/jobapplications/{jobId}/ai/generate` → `AiWorkspaceService` → `ISummarizerService` | `Pro` policy with live role lookup | Ledger reservation before generation; actual estimate finalized on success | Generate disabled; existing history/read/delete remain available |
 | Candidate fit | Job details Candidate Fit and Strategy Snapshot | `GET .../{id}/candidate-fit` → attachment/correspondence context → multiple summarizer calls | `Pro` policy | No complete shared usage row | Deterministic `match-score` remains available; AI narrative locked |
-| Focus plan | Job details Focus Plan and Strategy Snapshot | `GET .../{id}/focus-plan` → summarizer | `Pro` policy | No complete shared usage row | Locked; no synthetic fallback presented as generated |
+| Focus plan | Job details Focus Plan and Strategy Snapshot | Durable `strategy.snapshot` operation → summarizer | `Pro` admission plus worker recheck | Atomic operation-ledger reservation; successful input/output estimate finalized | Locked; no synthetic fallback presented as generated |
 | Interview brief | Job details Interview Prep | `GET .../{id}/interview-prep/brief` → summarizer | `Pro` policy | No complete shared usage row | Editable non-AI interview board remains available; generated brief locked |
 | Tailored CV generation | Add Job option and job Tailored CV tab | `POST .../{id}/generate-tailored-cv-draft` → shared generation helpers → summarizer | `Pro` policy | No complete shared usage row | Job creation and manual tailored-draft editing remain available; no operation is started |
 | Application package | Job workspace drafts | `POST .../{id}/generate-application-package` → attachment/email context → summarizer | `Pro` policy | No complete shared usage row | Existing/manual package drafts remain readable and editable |
 | Follow-up draft | Job Follow-up tab | `GET .../{id}/followup-draft` → context → summarizer | `Pro` policy | No complete shared usage row | Manual correspondence data remains available; AI draft is locked |
 | Job summary refresh | Job overview | `POST .../{id}/refresh-ai` → `SummarizeAsync` | `Pro` policy | No complete shared usage row | Existing summary/tags remain visible; refresh locked |
 | Automatic job summary | Job create/detail | Core `POST /jobapplications` and `GET /{id}` optional summarizer calls | Live role condition inside core action | No complete shared usage row | Core request succeeds without calling AI |
-| CV import/parse | Career Profile upload/parse/reprocess | `/profile-cv/upload`, `/parse`, `/reprocess` → extraction/structured parsing | `Pro` policy before admission; queued run rechecks live roles | CV-run state only | Manual profile editing and previous review runs remain available |
+| CV import/parse | Career Profile upload/parse/reprocess | `/profile-cv/upload`, `/parse`, `/reprocess` → durable `cv.process` operation | `Pro` policy before admission; queued run rechecks live roles | Atomic conservative operation-ledger reservation; no raw CV content | Manual profile editing and previous review runs remain available |
 | CV rebuild/improve/rewrite/PDF | Career Profile AI buttons | `/rebuild`, `/improve`, `/rewrite-section`, `/rewrite-preview`, `/export-pdf` | `Pro` policy; queued rebuild/improve recheck live roles | CV-run state only | AI controls locked; manual profile data remains available |
 | CV Builder writing aid | CV Builder AI Tools | `POST /api/cv/ai/assist` → summarizer | `Pro` policy | No complete shared usage row | AI buttons disabled; CV editing/history remain available |
 | Pro CV themes | CV Builder Customize | `GET /api/cv/themes`; create/save validates selected theme | Live role lookup in theme catalog checks | Not applicable | Pro themes identified and unavailable; existing unchanged selection can still be saved |
@@ -42,6 +42,8 @@ Status: `IMPLEMENTED — NOT VERIFIED`. The server policy, worker rechecks, Free
 - `ProfileCvControllerTests`: a queued CV run fails with `pro_required` semantics after downgrade and never reaches the model.
 - `AccountPlansTests`: Free zero AI, Pro/Admin AI, and only `free`/`pro` external names.
 - AI Workspace UI test: Free locked state, disabled generation and upgrade link.
+- `AiUsageMeterTests`, operation integration, account export/deletion and SQLite compatibility tests cover idempotent reservation, limits, owner isolation, history-independent totals, Strategy finalization, CV conservative reservation and lifecycle handling.
+- Full backend after the ledger migration: 663/663.
 - Full backend: 568/568.
 - Full frontend: 47/47 suites, 157/157 tests.
 - Production frontend build: pass.
@@ -53,7 +55,7 @@ Status: `IMPLEMENTED — NOT VERIFIED`. The server policy, worker rechecks, Free
 - Stripe webhook transitions were code-inspected and existing status tests cover active/trialing vs expired states, but no real or mocked end-to-end checkout/webhook cycle ran in this package.
 - MariaDB and production were not changed or tested.
 - PRODUCT-001 removed landing-page prices, the third “Bring your own key” tier, Free AI allowance and “Unlimited AI” claims. Public capability copy now comes from one two-plan catalogue; commercial terms remain in configured Stripe Checkout.
-- Full cross-feature usage accounting is incomplete. It must be centralized with AI operation execution before provider rollout; current numeric ceilings must not be advertised as universal until then.
+- The durable ledger now spans AI Workspace, Strategy Snapshot and CV processing, and deleting user-visible AI history no longer erases usage. Candidate Fit, Interview Prep, application-package/follow-up drafting, CV Builder assistance and automatic summary paths remain synchronous and are not yet universally admitted through this ledger; the UI must therefore avoid claiming that the displayed numeric ceiling covers every AI path.
 
 ## Rollback