Patient catalog & access — implementation plan

Status (2026-06-19): Phases 1, 1.5, 2, 3.1 shipped + verified live. Catalog browse (clinic curation + portal "Programe ghidate" tab), patient self-enroll (the deep-copy 500 fixed → atomic admin tx; live 201), the access engine (play gate free/premium/grant/prescription+sub, browse PRO lock state, entitlement resolver, capture column on protocols), and per-patient content grants (3.1) are all in. Build plan for the design in patient-catalog-and-access.md (authoritative for the why; this doc is the how + build order). See "Paid-launch plan" below for what's left — the access engine is built and everything except Bucket 3 shipped (enroll-capture + enforcement; the required_entitlement writer + clinic Free/Premium control; the tier-entitlement-assignment endpoint, all originally landed 2026-05-31). A clinic can now mark content premium and build a tier that grants content.premium through the product — and the clinic patient-tier-management UI (1D.2.D / L17) shipped, so it's all self-serve. Remaining (September-launch-gating): Bucket 3 (the D2C first-party-clinic + ~20k legacy-patient migration + Free/Everything tier seed + legacy-ownership grant backfill) — a pre-launch task, not an active workstream yet (see headline below). The platform is launch-capable for paid self-enroll.

Paid-launch plan (decided 2026-05-31 — paid/premium self-enroll IS a September full-launch requirement)

September-launch-gating headline — Bucket 3 (D2C launch data). The one remaining paid-launch item is a pre-launch task, not an active current workstream: stand up the RestartiX-operated first-party clinic org, seed its Free / Everything tiers (incl. the content.premium grant), run the ~20k legacy-patient migration (patients + profiles + patient_subscriptions, ~11k treatment plans, ~5k subscriptions), and backfill patient_content_grants from legacy per-program ownership (each legacy purchase → a lifetime grant under the first-party clinic). This depends on the legacy DB, the billing/SKU mapping decision (§3.2 open item), and a dedicated session — it can't be built/tested in this environment. This is the same ~20k migration the portal-auth custom-domain handoff feeds (the legacy→new self-migration bridge provisions accounts; this seeds their content/subscription state). Detail lives in §3.2/§3.3 + Bucket 3 below.

The access engine is built + tested; the controls that make content cost a tier are not all wired — so nothing is paywalled yet in practice (no content carries a premium marking, because the authoring path doesn't exist; a free program enrolls + plays for anyone; onboarding no longer auto-subscribes — originally it auto-subscribed to the patient tier granting content.prescription_play, then to a nothing-granting free tier, and is now revised so the paywall lives in provisioning: the default tier is renamed standard and carries content.prescription_play, but a self-signup patient gets no subscription at all and must be put on a tier to play prescriptions — see the paywall note below). The loose wires discovered 2026-05-31:

Plus: standalone session play from the catalog isn't built (portal tab's session cards are display-only; backend gate exists).

Build order:

Decisions locked (recap from the design note)

Copy-on-derive for both prescribe + enroll; no sharing, no versioning.
Catalog membership = eligibility — no self_enrollable boolean on content; a per-org catalog layer carries it.
Per-clinic gating — each (white-labeled) clinic curates which content is shown + premium.
Capture-at-enroll keeps the play gate catalog-free.
Two tier bundles — Free and Everything; Annual/Lifetime/Founders share the Everything bundle, differing by term/cohort. Prescriptions are in Everything, not Free.
Audio = sessions.kind='audio' (000023:175) — the catalog/access substrate handles it for free; only the portal audio player is "later."
Products/services are a separate axis — own catalog, reuse the pattern, bridged at appointments.

Dependencies & touch surface

Substrate already shipped: content model + copy-on-derive + _select_self RLS; patient_tiers (000005), patient_subscriptions + entitlements/limits/snapshots/overrides (000007); entitlements catalog (000004).
New domain: catalog (internal/core/domain/catalog/). Modified: programs, sessions, exercises (browse endpoints + access hook), protocols (capture column).
Run /new-domain catalog and /new-migration for the per-step checklists (permission seeding, RLS, route gating, classification entries).

Prerequisite — sessions gain a published state (shared with the render-pipeline chat)

Sessions adopt the program lifecycle so the catalog can gate on readiness and the render trigger is uniform. Owned by the async-render-pipeline chat (it also fixes their standalone-session render break); Phase 1's standalone-session surfacing depends on it. SHIPPED 2026-05-30 (commit 6f5fe93).

[x] sessions.status → draft | published | archived (default draft; map existing active → published, pre-prod). session_exercises stays active/archived (dose rows follow the parent).
[x] PublishSession becomes a durable flip + enqueue renders (not a readiness gate); readiness moves to attach/play, like a published program. The builder's render-state poller already watches pending → ready.
[x] AttachSession requires source.status='published'; the copy's renders are content-addressed cache hits.
[x] Edit-after-publish mirrors programs (content edits require a draft — ErrSessionNotDraft; setting published via PATCH is rejected, use the publish endpoint), keeping the two lifecycles symmetric.

Phase 1 — Catalog layer (sections + entries)

Goal: clinics curate a per-org catalog (incl. selected platform content) into ordered, featured sections; patients browse the union of platform-default + their clinic's catalog.

Phase 1 shipped (backend + 1.5 UI). Migration 000032 (sections/entries + clinic RLS/perms + the cross-domain patient-visibility policies for catalogued org content) + the catalog domain (clinic CRUD + GET /v1/me/catalog) + the clinic curation surface + the portal "Programe ghidate" tab. make check + integration + frontend (typecheck/lint/build) green. Carried into later phases: program session-count in the browse summary (needs the same broader subtree RLS that self-enroll deep-copy will) and the enroll-time subtree read (Phase 2/3). Sessions carry direct exercise_count/estimated_duration_s. Open in Phase 1 still: the target-content status='published' browse/play gate (line below) — the browse join already filters it; the standalone-play gate lands with Phase 2.

1.1 Schema

[ ] catalog_sections — id, organization_id (NULL = platform-default), code (slug), name, description, translations JSONB (P21), sort_order, status (draft|published|archived), created_by_principal_id, created_at/updated_at, deleted_at. Unique (organization_id, code); index (organization_id, sort_order).
[ ] catalog_entries — id, organization_id (NULL = platform-default), section_id → catalog_sections(id) ON DELETE CASCADE, content_type CHECK (program|session|educational_video) — audio is session (the entry filters by the session's kind), content_id UUID (typed-polymorphic, no FK — a dangling entry just doesn't render), sort_order, featured BOOL, presentation overrides (cover_content_file_id → content_files, badge, subtitle, translations JSONB), status, required_entitlement TEXT NULL → entitlements(code) (reserved here, enforced in Phase 2; NULL = free), audit cols. Unique (section_id, content_type, content_id); index (organization_id, content_type, content_id) — the "is this content catalogued for me" lookup the access check + standalone gate hit.
[ ] Classification registry entries for every new column (CI gate).

1.2 RLS

[ ] catalog_sections_select / catalog_entries_select (PG permissive-OR):
- platform-default (organization_id IS NULL AND status='published' AND current_app_principal_id() IS NOT NULL) — any authenticated principal (incl. patients);
- org published (organization_id = current_app_org_id() AND status='published') — patients + staff of the clinic see the live catalog;
- org all incl. drafts (organization_id = current_app_org_id() AND current_app_has_permission('catalog','read')) — staff curation.
[ ] INSERT/UPDATE/DELETE: org-tier only, catalog.manage; platform-default rows via AdminPool (Console).

1.3 Permissions

[ ] Seed catalog.read, catalog.manage; grant to admin + specialist (read also to customer_support).

1.4 Endpoints

[ ] Clinic (gated catalog.manage/catalog.read): GET/POST /v1/catalog/sections, PATCH/DELETE /v1/catalog/sections/{id}, PUT .../sections/reorder; POST/PATCH/DELETE /v1/catalog/sections/{id}/entries, PUT .../entries/arrange (mirror the programs arrange pattern).
[x] Patient browse: GET /v1/me/catalog — a unified catalog read unioning platform-default + own-org published sections/entries, grouped + ordered, content-resolved (program/session summaries). Session entries cover standalone sessions, so no separate /me/library/sessions. Supersedes the platform-only /me/library/programs (left in place; the portal migrates in 1.5).
[ ] Browse gates on the target content's status='published', not just the entry's. Editing a published session/program unpublishes it (→ draft; ErrSessionNotDraft / unpublish-to-edit, shipped in the prerequisite), so a published entry can point at a now-draft target — the browse join must hide those, and the standalone-play gate must reject them. (Surfaced verifying the session-lifecycle prerequisite.)

1.5 UI (separate PRs)

[x] Clinic curation surface (sections + entries: create/rename/publish/archive sections, add published programs/sessions as entries, feature/unfeature, publish/unpublish, remove) — follows the SWR-owned program-builder pattern. /library/catalog + /library/catalog/{sectionId}. Shipped (commits 667ce7e, 7b2fba9). Deferred (cosmetic): drag-reorder, cover-image picker, async-typeahead content picker, i18n of the editor strings (currently English) — all post-Phase-1.
[x] Portal "Programe ghidate" catalog tab — migrated the /library surface off the platform-only /me/library/programs onto GET /v1/me/catalog; renders sections → program/session cards (localized name/subtitle/description, featured highlight, session exercise-count/duration badges). Program cards link to enroll (/my-programs/{id}?source=library); session cards are display-only until Phase 2 gates standalone play. Relabeled the tab to "Programe ghidate" (freeing "Biblioteca" for the Phase 4 exercise library). Deferred: the featured hero = prescription/Today card pinned above is the Today-gate roadmap item (not built); featured entries get a soft in-section highlight for now.

Phase 2 — Access enforcement (tier gating)

Goal: gate play by tier; render shown-but-locked (PRO) cards on browse.

Shipped 2026-05-30. Migration 000033 + the access decision package + the patientsubscriptions resolver + capture-on-protocols + the enforcePlayGate access branch + browse lock state + portal PRO cards. make check green.
Decision recorded — gate rules. The two specs only ever disagreed on the code list, not the gate rules. Catalog content gates per-entry (required_entitlement — NULL = free for any patient, no subscription needed; else tierHas(code)). Prescriptions gate on content.prescription_play + an active subscription. Seeded exactly two codes (content.prescription_play, content.premium); the orphan content.enrollment_play was dropped and the Phase-4 exercise-library codes (content.library_browse, exercise play) are deferred to Phase 4 (they gate the faceted exercise library, not catalog content — which is also why the clinic tier editor shows exactly the two content toggles today).
Revised 2026-05-31 → paywall = no auto-subscribe. The gate moved twice. (1) Originally the seeded default tier granted content.prescription_play and onboarding auto-subscribed everyone ("default-open"). (2) Interim: the default tier was renamed → free and granted nothing, but onboarding still auto-subscribed (the sub just carried no entitlements). (3) Final: the paywall lives in provisioning — onboarding does not auto-subscribe a self-signup patient (no patient_subscriptions row → EvalPrescription denies subscription_required). The default tier is renamed → standard and does carry content.prescription_play (000009 seeds it on the live junction + the v1 snapshot), so it's the meaningful base tier patients subscribe to (self-checkout / staff Abonament tab / a tier-pinning invite). A self-signup patient gets full portal access (browse free catalog, see the upsell) but plays no prescriptions until put on a tier. Rationale in decisions.md → Why onboarding does not auto-subscribe.

2.1 Entitlement codes

[x] Seed content.prescription_play + content.premium (000033, non-regulated). Phase-4 exercise codes deferred; enrollment_play dropped.
[x] ~~Default "Patient" tier grants content.prescription_play~~ Revised → paywall = no auto-subscribe (2026-05-31): the seeded default tier is renamed → standard and does carry content.prescription_play (000009 companion function: live junction + v1 snapshot). The paywall is that onboarding does not auto-subscribe (ResolveDefaultTier fallback removed; only an invite/share-link tier pin provisions a sub at signup). A self-signup patient has no subscription → prescriptions deny until they're put on standard (or higher). Per-clinic premium tier configuration is clinic-side data, not a platform seed.

2.2 Access-check service

[x] internal/core/access (leaf): EvalCatalogContent + EvalPrescription → Decision{Allowed, LockReason} (requires_upgrade / requires_tier / subscription_expired / content_unavailable). patientsubscriptions.Service.ResolveForPatient (admin pool, by id) / ResolveForCurrentPatientAtOrg (RLS) build the EntitlementSet (active sub within period + snapshot merged with active overrides; period gap fixed). Grant path is a Phase-3 no-op param.
[x] Mode rules wired in enforcePlayGate: catalog content → free(entry) OR tierHas(req); prescription → EvalPrescription. Exercise browse/play → Phase 4.

2.3 Capture-at-enroll

[x] protocols.required_entitlement (column in 000023 CREATE TABLE per the editable-migration convention; FK to entitlements(code)). Set in protocols.Service.Create: prescription → content.prescription_play; enrollment → caller's source-entry code (nil today). Re-checked against the current subscription at play.

2.4 Hook the gate

[x] enforcePlayGate restructured: the access check runs for every mode (standalone catalog lookup / enrollment captured code / prescription rule), cadence stays prescription-only. Access locks → 402 Payment Required (cadence stays 409). Standalone play does one indexed catalog lookup (RequiredEntitlementForSession); uncatalogued/unpublished standalone → content_unavailable.
[x] GET /v1/me/catalog returns per-entry locked + lock_reason; the portal "Programe ghidate" tab renders shown-but-locked PRO cards (no enroll link, muted, lock icon).

2.5 Prescription rule

[x] Prescription playability bounded by the live subscription — the resolver only returns codes for an active, in-period subscription, so playability lapses when current_period_ends_at passes; never grantable (the grant path is catalog-content-only).
[x] Subscription expiry write path + sweep — SHIPPED 2026-05-31. The access window is now actually settable (it was a dormant column before): CreateParams/CreateOnTx carry the period, SetSubscriptionParams gains period_ends_at (nil = perpetual; handler rejects a past cutoff), and the clinic Abonament dialog offers duration presets / custom date / "Indefinite" + an "Active until / Expires soon / Expired" indicator. A daily sweep (cmd/patient-subscriptions-expiry-sweep + crons.tf, mirroring expire-hard-cap-protocols) flips lapsed live subs → expired (audited, system actor) — hygiene only; the resolver's live date-check already revokes access the moment the window passes. Renewal is manual (re-run Set-subscription); auto-renew/Stripe deferred. Tests: TestPatientSubscriptions_ExpirySweep + TestPatientSubscriptions_PeriodGate. Rationale in decisions.md → Why subscription expiry is per-subscription + manual-renewal.

Phase 3 — Grants + the 20k migration

3.1 shipped 2026-05-30 (migration 000034 + the patientcontentgrants domain + access.GrantKey + gate/browse wiring + staff CRUD API). 3.2 + 3.3 remain launch-gate — they need the legacy DB + the billing/SKU decision (§3.2 open item) and can't be built/tested in this environment. The clinic grant-management UI is also a separate follow-up.

3.1 `patient_content_grants`

[x] Table: id, organization_id, patient_id, content_type, content_id, granted_from, granted_until TIMESTAMPTZ NULL (NULL = lifetime; revoke = set it to now, no DELETE), source (legacy_migration|comp|promo), granted_by_principal_id, reason, audit cols. RLS: patient-self read (via current_human_patient_profile_ids() — what the RLS browse resolver reads), staff SELECT/INSERT/UPDATE (content.grant perm). Index (organization_id, patient_id, content_type, content_id). Keyed on patient_id (per-org), not the portable patient_profile_id.
[x] Wired into the access check (catalog content only — never prescriptions): the third OR-branch (granted) in access.EvalCatalogContent. The patientcontentgrants.Service resolves active grant keys for the play gate (ResolveGrantKeysForPatient, admin pool, by id — enrollment keys on protocols.source_program_id, standalone on the session id) and the browse (ResolveGrantKeysForCurrentPatientAtOrg, RLS). Staff CRUD: POST/GET /v1/patients/{patientId}/content-grants + POST .../{id}/revoke (gated content.grant; mints comp/promo — legacy_migration is admin-pool only). api-client content-grants module + PERM_CONTENT_GRANT.

3.2 First-party clinic + tiers

[ ] Create the RestartiX-operated first-party clinic org (one tenant). Seed its patient_tiers: Free, Everything (represent Annual/Lifetime/Founders as term/cohort — separate SKU rows sharing the Everything entitlement set, or one Everything tier + term on the subscription + a founder cohort marker; decide with the billing/SKU mapping).
[ ] Migrate the ~20k patients (patients + patient_profiles + patient_subscriptions per their legacy plan).

3.3 Legacy-ownership backfill

[ ] Backfill patient_content_grants from legacy per-program ownership (each legacy purchase → a lifetime grant under the first-party clinic).
[ ] (Separate effort) rebuild legacy programs as platform/org programs — the content migration the legacy covers reuse.

Phase 4 — Exercise library ("Biblioteca")

Faceted browse over the taxonomy — not the catalog.

[ ] GET /me/library/exercises?zona=&obiectiv=&dificultate=&durata=&echipament=&q=&sort=&limit=&cursor= — server-side filter over the 000027 taxonomy + pagination; q uses unaccent trigram. Gated by content.library_browse.
[ ] patient_exercise_favorites (patient_id, exercise_id, created_at; patient-self RLS) — the heart.
[ ] "Recomandate pentru tine" sort — start with a heuristic (the patient's active program's body-regions/conditions); the AI ranking is a later hook.
[ ] Standalone exercise play gated by content.standalone_play (Free can browse, not play).

Phase 5+ — Out of scope here (separate axes / later)

[ ] Portal audio player (audio sessions are catalogable now; only playback waits).
[ ] educational_videos entity + player + catalog content_type.
[ ] Service axis — service_plans, patient_tier_inclusions, per-patient consumption counter, appointments. See tiers-and-subscriptions.md + appointments-substrate.md.
[ ] Products/services catalog (reuse the Phase-1 pattern) + cross-sell promo-slot.

Open items

[ ] Annual/Lifetime/Founders as separate SKU rows vs. one tier + term — settle with the external-billing SKU mapping (§3.2).
[ ] patient_content_grants keyed on patient_id (per-org) — confirmed org-scoped (legacy ownership lives under the first-party clinic), not the portable patient_profile_id.
[ ] Granularity of content gate codes — one content.premium_content vs. per-tier codes (clinic choice; the schema allows any entitlements(code) on the entry).

Patient-tier versioning — made load-bearing (publish-on-save). ✅ CLOSED 2026-05-31

The patient_tiers.version / published / published_at + patient_tier_versions apparatus was dead scaffolding (no Go read, nothing bumped version, the UI couldn't set published → every UI-created tier was a silently-un-subscribable Draft, and marking one default wedged onboarding's ResolveDefaultTier). Now real, on the publish-on-save model:

Three states from two booleans: Draft (version=0, published=false) → Published v{N} (published=true, is_active=true) → Retired (is_active=false). Create makes a Draft; the first "Save & publish" cuts v1.
PublishVersion (Go, AdminPool tx) replaces the entitlement junction with the submitted set, freezes a patient_tier_versions snapshot (entitlements + resolved limits + metadata + changed_by_principal_id), and bumps version/published/published_at. The granular POST/DELETE …/entitlements endpoints (Bucket 2b) were superseded by POST …/patient-tiers/{id}/versions; GET …/versions returns history.
Correctness: patientsubscriptions.CreateOnTx now snapshots from the published version (patient_tier_versions at the resolved version, via jsonb_to_recordset), not the live junction — so unpublished draft edits never leak to new subscribers. (Grandfathering still rides the per-subscription snapshot; existing subs are untouched.)
Guard: service.Update rejects setting an unpublished tier as default (cannot_default_unpublished) — the root fix for the wedge; the editor also disables "Set default" on Drafts.
Clinic UI: the /patient-tiers editor reworked to batched local edit + Save & publish, state badges, and a per-tier version-history disclosure (lazy GET …/versions).
Tests: TestPatientTiers_PublishVersion, TestPatientTiers_PublishedVersionReachesSubscription (rlstest). Deferred: "migrate v1→v2 subscribers" admin op (data model supports it); deliberate draft-staging on a live tier; the parallel org-side tiers/tier_versions carry the identical dormant pattern (out of scope here).

Deferred / parked (re-verified 2026-06-19 against current code; originally logged 2026-05-31 after Buckets 1–2 + L17 shipped)

Carried so we don't lose them when attention moves to feedback work. None block the D2C paid-self-enroll loop, which is functional end-to-end. Each item below is tagged September-blocking (must close before the full launch) or post-launch polish.

Patient catalog & access — implementation plan ​

Paid-launch plan (decided 2026-05-31 — paid/premium self-enroll IS a September full-launch requirement) ​

Decisions locked (recap from the design note) ​

Dependencies & touch surface ​

Prerequisite — sessions gain a published state (shared with the render-pipeline chat) ​

Phase 1 — Catalog layer (sections + entries) ​

1.1 Schema ​

1.2 RLS ​

1.3 Permissions ​

1.4 Endpoints ​

1.5 UI (separate PRs) ​

Phase 2 — Access enforcement (tier gating) ​

2.1 Entitlement codes ​

2.2 Access-check service ​

2.3 Capture-at-enroll ​

2.4 Hook the gate ​

2.5 Prescription rule ​

Phase 3 — Grants + the 20k migration ​

3.1 patient_content_grants ​

3.2 First-party clinic + tiers ​

3.3 Legacy-ownership backfill ​

Phase 4 — Exercise library ("Biblioteca") ​

Phase 5+ — Out of scope here (separate axes / later) ​

Open items ​

Patient-tier versioning — made load-bearing (publish-on-save). ✅ CLOSED 2026-05-31 ​

Deferred / parked (re-verified 2026-06-19 against current code; originally logged 2026-05-31 after Buckets 1–2 + L17 shipped) ​