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

# POL-001 Free/Pro entitlement verification

Date: 2026-08-02

Status: `IMPLEMENTED — NOT VERIFIED`. The server policy, worker rechecks, Free locked states and automated regressions pass. Real-browser, Stripe lifecycle, MariaDB and production checks remain unavailable.

## Canonical policy

- External plan names are `free` and `pro` only.
- Free retains core non-AI job tracking, deterministic match scoring, manual profile/CV editing, saved drafts, exports and existing AI history, but cannot start AI work.
- 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.

## 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 |
| 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 |
| 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 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 |
| Job enrichment worker | No direct UI; disabled by default | `JobEnrichmentHostedService` per owner | Live role recheck immediately before summary; deterministic tag detection still runs for Free | No complete shared usage row | No model call; core tag enrichment remains possible |
| Admin AI probe | Admin system diagnostics | `/api/admin/system/ai/probe` | Admin role; Admin maps to Pro | Health metric only | Not a Free user path |
| Periodic service probe | No user entry | summarizer health probe | No private/user payload; operational health only | Health metric only | Not a user AI capability |
| Attachment storage | Add-job/files UI | `AttachmentsController` storage check | Central Free/Pro storage entitlement | Bytes stored | 250 MB Free; 5 GB Pro (existing defined capability) |

## Automated evidence

- `ProEntitlementAuthorizationTests`: Pro/Admin success, stale-claim downgrade failure, stable 403 body, and reflection inventory of all explicit AI actions.
- `BackgroundWorkerTenantTests`: Pro owners use fake AI; Free owners never call it.
- `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.
- Full backend: 568/568.
- Full frontend: 47/47 suites, 157/157 tests.
- Production frontend build: pass.
- `git diff --check`: no whitespace errors; existing line-ending notices only.

## Limitations and remaining checks

- Browser localhost access is denied by the available browser policy, so 375/768/1440, keyboard, themes and actual navigation to the upgrade action are not claimed.
- 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.
- Landing-page prices, a third “Bring your own key” tier and “Unlimited AI” claims remain assigned to PRODUCT-001; they are not presented as resolved by POL-001.
- 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.

## Rollback

Revert the policy registrations, action attributes, worker checks and frontend plan context together. No schema or dependency change is involved. Keep workers disabled during rollback; reverting only the worker rechecks would restore a downgrade bypass.