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.