LOKTORE v4.2.0 — Data · ER · API Utility+

LOKTORE controls two independent questions behind a single call, canAccess(user, action, resource, context): does the relevant party's subscription cover this feature (Entitlements), and is this specific user allowed to perform this action (Authorization/RBAC). The rest of the codebase never needs to know two systems exist.

Core problem this revision solves

In the original design, editing a commercial plan changed access immediately for every center already subscribed to it — contradicting LOKTORE's own commitment that pricing and features are locked until renewal. This revision introduces a frozen snapshot per subscription and full version history for plans (composition, price, limits), so a plan can be edited and published safely without touching any existing subscriber.

Commercial catalog structure

Built from functional_capabilities — the atomic, developer-owned features LOKTORE actually implements (teleconsultation, e-prescribing, claims tracking). Commercial modules (e.g. “Clinical Tools”) are a freely reconfigurable, Super-Admin-managed grouping with no technical logic of their own; plans reference capabilities directly, so reorganizing modules never affects a plan already sold. A Draft → Review → Publish workflow, backed by granular permissions, prevents accidental live edits.

Delegation

Administrative rights (Super Admin → Country Admin → Country Staff) follow standard RBAC, confined by one explicit rule: nobody can grant a permission or scope they do not themselves hold. Checked at grant time, not on every subsequent use (§9.2.2).

Two defects found and fixed by this revision's own engineering review

• Delegated access was unreachable for any user without a direct role (fixed — grant source is now role OR delegation, §2.2)
• Break-glass emergency access was unreachable for the exact scenario it exists for — a center with a suspended subscription (fixed — moved to an early bypass, §2.0)

Scalability finding

The engine as specified would not scale past a few hundred requests/second without caching. Remediation: data classified by staleness tolerance, materialized permission/entitlement lookups, asynchronous audit logging, and an explicit bounded-staleness consistency commitment requiring security sign-off (§13).

Multi-party entitlement model

Capabilities can require independent subscription from more than one kind of subscriber (a Center, a Patient, both, or more) — each side checked only against its own frozen subscription, never arbitrated against the other's plan version. Every subscriber type is a configurable catalog row (subscriber_types), never hard-coded (§1.3). Funding capability is derived from subscriber_type_funding_rules, never a flag.

Status

Ready for the SQL constraint matrix. Eight items remain for governance/product/security sign-off rather than engineering — see §12.3.

1.1 Key Principles

• Single Public Entry Point — all access checks go through canAccess(user, action, resource, context); no business service implements its own authorization or entitlement logic
• Two Internal Engines, One Orchestrator — the Entitlements Service (commercial) and the Authorization Engine (Domain 10 — RBAC/ReBAC/ABAC); neither calls the other
• Refusal by Default — anything not explicitly authorized is refused, at either gate
• Entitlement Before Normal Authorization — after break-glass, Entitlements is checked before RBAC: it's a cheap, cacheable read against a frozen snapshot and gives a clearer refusal reason (“not in your plan” vs. “you lack the role”)
• Entitlements Are Frozen at Subscription Time — a snapshot taken at subscription/renewal, never a live read of the editable catalog. Declared exception: capability_permissions is live-editable and governed (§3.3)
• Capability Operational Activation Gate — independent of the commercial plan, a capability can be enabled/disabled per country, center type, or specific center (capability_activations)
• Commercial Model ≠ Navigation Model — what's sold (modules/capabilities) and what's clicked (menus/submenus) are distinct hierarchies, linked only through the shared resources/permissions registry
• Structured Decisions — every check returns { status, gate, reason, rulesEvaluated }
• Rule Versioning, Zero-Trust, Separation of Concerns (configuration roles cannot access business/patient data)

1.2 What Changed vs. v1.0

v1.0 merged all 10 checks (subscription status, plan coverage, module activation, roles, overrides, delegation, break-glass) into a single can() function. This worked operationally but created two problems: no frozen snapshot (editing a plan retroactively changed access for active subscribers, contradicting LOKTORE's 30-days'-notice commitment), and coupled ownership (commercial + RBAC logic in one engine). v2.0+ keeps the single-entry-point ergonomics while splitting the internals into two independently ownable services and adding the snapshot mechanism.

1.3 Dynamic Subscriber Type Catalog

Every kind of subscriber — health center, patient, organization, insurer, or any future kind — is a row in subscriber_types, not a hard-coded value. The engine has no built-in concept of “CENTER” or “PATIENT.” Funding capability is derived, never a flag: whether a type can fund others is determined entirely by the existence of a row in subscriber_type_funding_rules. Creating/modifying a subscriber_types row is a structural decision reserved for Developer/System Administrator, never the functional Super Admin.

1.4 N Independent Entitlements, Never a Shared Policy

A capability can require entitlement from any number of independent subscriber types. None are arbitrated against a shared policy version — each party resolves independently against its own eligible sources, and ALL required types must independently pass:

An imbalance between the number of parties of each required type is a normal commercial supply/demand signal, never a system inconsistency (§3.3.2).

canAccess() evaluates a break-glass check first, then two phases in order — see the Flowcharts tab for the visual version of this section.

2.0 Break-Glass Bypass (evaluated first)

Moved from Phase 2 step 9 to an early bypass branch — placed at the end, it was unreachable for its primary purpose (a suspended subscription would REFUSE at Phase 1 step 1 long before reaching it).

2.1 Phase 1 — Entitlements (N-party, source-based)

Algorithm rewritten around entitlement SOURCES (own subscription OR funding link), not the assumption that every party holds its own subscription — this correctly handles a Patient covered only through an NGO.

A permission with NO row in capability_permissions (e.g. PLAN+CREATE, an RBAC-only/administrative permission) skips Phase 1 entirely — a deliberate branch based on the presence of a capability mapping, not on whether context carries a centerId.

2.2 Phase 2 — Authorization (Domain 10 Engine)

Fixes a v1.0 defect: role-permission failure used to terminate the pipeline before delegation (evaluated after it) was ever reached — a pure delegate was always refused. Fix: grant source is now the disjunction of role-permission and delegation.

2.3 Signature & Response

• user — userId from Keycloak token
• action — view, create, update, delete, approve, export, …
• resource — a stable resources.code (e.g. PRESCRIPTION, CLAIM) — not a submenu code; the backend authorizes a business action, not a click on a screen
• context — { countryId, siteId, parties: [ { type, id }, … ], targetId? } — a generic party collection, no fixed centerId/patientId fields

Response: { status: AUTHORIZED|REFUSED, gate: break_glass|entitlement|authorization|null, reason, missingSubscriberType?, rulesEvaluated: [...] }. The constraints field (trialEndsAt, maxUsers, …) is removed — canAccess() never evaluates capacity; that's a separate checkCapacity() call by the business service.

This is the section carried into LOKTORE Utility's live 118-table model (governance + entitlements domains, v3.7.1). The subsections below map 1:1 onto that implementation — cross-reference against the Data tables / ER diagram tabs for live column lists.

3.1 Access Catalog — resources, actions, permissions

A stable, UI-independent business object layer sitting between commercial capabilities and RBAC permissions, owned by neither domain (renamed acl_resources in this app to avoid colliding with the pre-existing scheduling.resources physical-resource table). Introduced so the same business object (a claim) can be secured and entitled once, then exposed identically through multiple portals' navigation.

3.2 Roles & Assignments

roles (scope_level, role_category), role_permissions, user_roles (scoped country/center/site), user_permission_overrides (deny-only). A configuration-category role cannot be assigned a permission on a business/medical-category resource — rejected at write time, not only at request time.

3.3 Functional Capabilities

functional_modules / functional_capabilities / module_capabilities are the commercial catalog. capability_permissions (capability ↔ permission, i.e. capability ↔ resource+action) replaces the earlier capability_resources — this is what disambiguates two capabilities sharing a resource, e.g. CLAIM_SUBMISSION (CENTER+INSURANCE) vs. CLAIM_REVIEW (INSURANCE alone). UNIQUE(permission_id): a permission can map to at most one capability.

3.3.1 Capability Subscriber Requirements

capability_subscriber_requirements declares which subscriber_types must independently pass entitlement for a given capability — generic, no special-cased type anywhere in the table or resolution engine.

3.3.2 Two-Sided Market

A capability can be funded by one subscriber type and consumed by another (e.g. an Insurer funding Patient teleconsultation without appearing in the Patient's own navigation) — an imbalance between funders and consumers is a commercial signal, not a data-integrity problem.

3.3.3 RBAC-Only Permissions

A permission with no capability_permissions row is RBAC-only / administrative (creating a plan, managing the Access Catalog, assigning a role) — no subscription entitles it, so Phase 1 is skipped entirely for it, always.

3.4 Delegations

Operational delegation (view / manage_availabilities / create_appointment / modify_appointment / cancel_appointment / configure_booking) — created (pending) → accepted → effective. Revocable any time, optional expiry, auto-revoked on detachment from center/site.

3.5 Subscriber Type Catalog

subscriber_types — every kind of subscription holder, wired to a registered identity resolver. Two-level governance: configuration is not no-code — adding a row makes the engine aware such a party may hold subscriptions, but the portal/roles/scopes/menus remain a separate engineering deliverable.

3.6 Subscription Plans

subscription_plans (polymorphic holder_type_id), plan_eligible_center_types. LOKTORE plans combine two independent axes: Depth (billing-only vs. full practice tools) and Visibility (invisible vs. patient-discoverable).

3.6.1 Plan Eligibility by Center Type / 3.6.2 Center Type Change / 3.6.3 Audience Lock-In

A plan can be restricted to specific center types; once a plan has ever had a subscription, its audience is locked in — a commercial mechanism kept distinct from the operational capability_activations gate.

3.7 Plan Versioning / 3.7.1 Draft → Review → Publish

plan_versions (status: draft/live/archived) with plan_version_capabilities / plan_version_action_limits / plan_version_capacity_limits, immutable once published (DB-enforced trigger). Granular permissions (§9.2) make prepare-vs-publish a real permission boundary, not a UI convention.

3.8 Subscriptions & Frozen Snapshot

3.8.1 Polymorphic Owner — subscriptions.owner_type_id/owner_id validated at write time via the identity_resolvers registry. 3.8.2 Funding Relations — subscriber_type_funding_rules is the sole source of truth for who can fund whom. 3.8.3 Coverage Links & Quotas — subscription_party_links + subscription_party_limits (isWithinLimit() NULL-safe helper). 3.8.4 Funding Rules. 3.8.5 resolvePartyEntitlement() / evaluatePartyEntitlement() — source-based, permission-precise resolution. 3.8.6 Action-Limit Freeze — subscription_action_limits. 3.8.7 Internal Capacity Limits — capacity_dimensions ↔ subscriber_types via capacity_dimension_subscriber_types (many-to-many, v4.4), replacing max_users/max_sites; PROFESSIONALS and STAFF are counted by their own resolver, never by counting RBAC role assignments. 3.8.8 Trial Abuse Prevention — subscription_trial_usage, UNIQUE(owner_type_id, owner_id, plan_id) as the actual arbiter, not an application check-then-insert.

3.9 Subscription History / 3.10 Frozen Data Retention

subscription_history (full version-aware change log) and subscription_frozen_data (data tied to removed modules on downgrade — preserved, restored automatically on re-upgrade, never deleted).

3.11 Authorization Rules & Decision Log

authorization_rules (versioned), authorization_decisions_log + authorization_decision_entitlement_sources (one row per source actually evaluated, plus grant_sources JSONB recording every ROLE/DELEGATION that granted). Freezes permission_id and capability_id at decision time — audit records are never reconstructed from the live Access Catalog. No synchronous write on the request path (§13.5).

3.12 Break-Glass Sessions

break_glass_sessions — token_hash, granted_by, scope JSONB, is_active, post_review_completed. Reclassified into a fourth Orchestration/Audit group alongside the decision log, since it legitimately needs visibility across RBAC and Entitlements for audit purposes.

4.1 Entitlements Service

Owns subscriber_types, subscription_plans, plan_versions and its children, functional_capabilities, capability_permissions, capability_subscriber_requirements, subscriptions and everything under it, capacity_dimensions and its children. Does NOT own resources — shared, platform-owned, read-only from here. No dependency on the RBAC engine.

4.2 Authorization Engine (Domain 10) — RBAC only

4.3 Orchestrator — canAccess()

Implements §2 end to end: (0) break-glass; (1) resolve (resource, action) → permission, check for a capability_permissions row; (2) if mapped, resolve activationContext once and evaluate every required subscriber type via evaluatePartyEntitlement(); (3) call authorizationEngine.can(); (4) merge into the §2.3 response shape. A missing capability mapping is an expected branch straight to Phase 2 — never an error.

buildMenuTree(userId, navigationParty?, context) — tri-state navigation (ENABLED / LOCKED / HIDDEN, §4.3/v3.2.5+). LOCKED never grants access; a direct API call behind a locked screen is refused exactly like any unauthorized attempt. submenus.navigation_permission_id (DB-trigger-enforced to belong to the submenu's own resource) removes the old “any permission on the resource” ambiguity.

4.4 Middleware

Express authorize('delete','USER') factory constructs context per §2.3's shape — parties[] populated from whatever the request provides, never a bare top-level centerId — then calls accessOrchestrator.canAccess(); returns 403 with the structured { gate, reason } body if denied.

5.1 /api/v1/entitlements/ (new namespace)

5.2 /api/v1/rbac/ (mostly unchanged from v1.0)

Menu/submenu management, permission & action management, role management, user RBAC, delegations, break-glass. Module/capability activation endpoints have moved out of this namespace entirely — activation now targets capability_id under /entitlements/capabilities/:capabilityId/activations, never module_id.

5.3 Orchestrated check

Inside the recommended modular monolith this is an in-process call. The moment any external service consumes it over the network: mTLS/service-token auth, client-side caching with event-driven invalidation, a circuit breaker, and a documented fail-closed policy (treat unreachable/erroring as REFUSED, never AUTHORIZED) are mandatory from day one.

Unchanged from v1.0 — see the Role & Scope Hierarchy diagram in the Flowcharts tab for the visual version.

Scope hierarchy: Platform → Country → Center → Site. A higher-scope role includes access to all lower scopes within its boundary (a Burkina Faso Country Admin reaches every center/site in Burkina Faso, nothing in Côte d'Ivoire or Guinea). Configuration roles configure modules/rules/features/plans but cannot access patient/medical/business data; operational roles execute business operations but cannot modify global configuration — enforced via role_category.

LOKTORE plans are not a linear tier ladder — two independent axes: Depth (“Billing only” vs. “Practice on Loktoré” — clinical tools, on-call, insurance) and Visibility (invisible to the public vs. discoverable by patients). Real modules: Organisation & digital front desk, Clinical tools, On-call & continuity of care, Insurance & reimbursement, Billing & financial tracking, Visibility & patient acquisition.

7.1 Lifecycle

States: active → suspended → reactivated → active · active → cancelled · active → expired · trial → active (after payment) · trial → expired.

• Suspended/expired/cancelled: all non-essential routes return 403 (reason: subscription_inactive). Profile + billing remain reachable. All data preserved.
• Upgrade — immediate re-freeze from the target plan_version; instant access to new features.
• Downgrade — re-freeze at end of current billing cycle, 30 days' advance notice. Data tied to removed modules is frozen (subscription_frozen_data), restored automatically on a later upgrade.
• Renewal — default: no change mid-cycle; 30 days before renewal the center is notified of the exact diff; snapshot resyncs at the renewal date. Individual plans can require explicit confirmation instead of silent auto-resync for sensitive tiers.

7.2 Illustrative Feature Matrix

A user may hold multiple cumulative RBAC roles simultaneously. RBAC role assignment does NOT determine STAFF/PROFESSIONAL business classification (§3.8.7). The physical Identity/account model for STAFF vs. PROFESSIONAL — one authentication account with separate business profiles, or genuinely separate accounts — is owned by the Identity domain, not decided by this document (v4.6 walked back an earlier “one account” phrasing that overreached).

Example: a practitioner who is CENTER_ADMIN at Center A and HEALTHCARE_PROFESSIONAL at Center B holds full admin capabilities at A and provider-only capabilities at B.

Same-Center hybrid roles

A healthcare professional may hold CENTER_ADMIN and/or SITE_ADMIN in the SAME Center they practise in — a clinic director who is both HEALTHCARE_PROFESSIONAL and CENTER_ADMIN for the same Center. These combinations never affect commercial capacity classification: the user remains counted under PROFESSIONALS, never additionally under STAFF, regardless of how many admin roles they also hold. WHAT a person IS commercially and WHAT a person CAN DO administratively are two independent axes — neither derives the other.

Audit record

There is no user-selected “acting role.” authorization_decisions_log records every grant source that actually granted the permission in grant_sources (every matching ROLE and any qualifying DELEGATION) — a prior “acting as” single-role phrasing was corrected as false whenever several roles independently grant the same permission at the same scope.

LOKTORE has two distinct delegation mechanisms. They are not interchangeable.

9.1 Operational Delegation (schedule/availability) — unchanged

A professional remains master of their schedule. Any third-party action requires explicit, granular, modifiable, revocable delegation (delegations table). Delegable actions: view, manage_availabilities, create_appointment, modify_appointment, cancel_appointment, configure_booking. Lifecycle: created (pending) → accepted → effective. Revocable any time, optional expiry, auto-revoked on detachment.

9.2 Plan-Edit Delegation — uses existing RBAC scoping, no new table

The right to act on a plan is not a fixed role and not a single permission — it is delegated, country-scoped, and follows a chain: Super Admin (always authorized, all countries) → LOKTORE Staff (granted, platform-scoped) → Country Admin (granted, scoped to their country_id) → Country Staff (granted by their Country Admin, same country_id).

This granularity makes Draft → Review → Publish a real permission boundary: a Country Staff can hold CREATE_PLAN_VERSION + EDIT_PLAN_VERSION without PUBLISH_PLAN_VERSION — they prepare, the Country Admin publishes. Each is an ordinary permission through user_roles/role_permissions — no separate grant table.

9.2.1 Confinement Rule

A user can never grant a permission or scope greater than what they themselves possess. Enforced at grant time via a dedicated mayGrant(actorId, targetPermissionSet, targetScope) function — not by re-checking the grantor on every subsequent use. Permission confinement: can only grant permissions currently held. Scope confinement: can only grant a scope contained within their own (a Burkina Faso Country Admin can never create a Côte d'Ivoire-scoped or platform-wide role).

9.2.2 Grant-Time vs. Use-Time Validity

Confinement is checked once, at grant time, deliberately NOT re-checked on every use. Plan-edit rights are ordinary RBAC assignments, not a dependent delegation chain — a Country Staff's granted permission becomes their own and does not depend on the Country Admin retaining it. Re-validating on every call would mean a manager leaving LOKTORE silently cascades to revoke dozens of legitimately onboarded staff — not a wanted property. What happens when an administrative permission is revoked is an open decision (§12.3).

10.1 Audit Events

10.2 Scoped Audit Log Access

10.3 Security Requirements

• Zero-Trust — every access verified, never implicitly granted
• MFA mandatory for SUPER_ADMIN and COUNTRY_ADMIN
• Refusal by default at either gate; configuration roles cannot access patient/medical data
• All unauthorized access attempts logged as security events, tagged with the failing gate
• Break-glass requires justification, time limit, full traceability
• Audit logs are immutable, append-only, stored separately
• Plan versions immutable once published — DB trigger rejects UPDATEs to plan_versions/plan_version_capabilities/plan_version_action_limits/plan_version_capacity_limits once status leaves draft
• Periodic access review to detect/revoke unnecessary permissions and stale plan-edit delegations
• Polymorphic subscription ownership validated at write time via the identity_resolvers registry, with a DB-level integrity check as defense-in-depth

Restructured around four groups — see the Domain Cluster diagram in the Flowcharts tab. RBAC and Entitlements are structurally independent of EACH OTHER; neither references a table owned by the other. Both depend on a shared, Platform-owned Access Catalog (resources, actions, permissions) — the only tables either references outside its own boundary for its own operation.

• RBAC cluster — roles, role_permissions, user_roles, user_permission_overrides, delegations, break_glass_sessions
• Access Catalog — resources, actions, permissions — owned by neither domain
• Entitlements cluster — functional_modules/capabilities, module_capabilities, capability_permissions, capability_subscriber_requirements, subscriber_types, subscription_plans and everything under it
• Orchestration/Audit — authorization_decisions_log + authorization_decision_entitlement_sources — the accessOrchestrator's own record; legitimately references identifiers from every other group because auditing the orchestrator's decisions is precisely the one legitimate reason to need visibility into both sides at once

This is a stronger form of the “single intentional bridge” principle: rather than one domain reaching into the other's schema, both domains reach into neutral, stable ones — the Access Catalog for day-to-day operation, Orchestration/Audit for after-the-fact record-keeping.

12.1 Kept as-is

The single canAccess() entry point, the two-engine split, refusal-by-default, zero-trust, and the role/scope hierarchy (§6) are unchanged since early revisions — this is a maturing, not a rewriting, of the original design.

12.2 Changed (headline items across the v2.0–v4.7 revision sequence)

• Break-glass moved from a Phase-2 dead-end to an early bypass (§2.0) — it was unreachable for its own purpose
• Delegation grant-source fixed to role OR delegation, not role alone (§2.2) — a pure delegate was always refused
• capability_resources replaced by capability_permissions to disambiguate capabilities sharing a resource (§3.3)
• Hard-coded CENTER/PATIENT replaced by a configurable subscriber_types catalog; the algorithm generalized to isPartyEntitledTo() over any number of parties (§1.3, §1.4)
• max_users/max_sites removed entirely, replaced by the many-to-many capacity_dimensions model (§3.8.7, resolved v4.4)
• Tri-state navigation (ENABLED/LOCKED/HIDDEN) replacing a binary shown/hidden model (§4.3)
• authorization_decisions_log reclassified out of the RBAC cluster into a new Orchestration/Audit group, with a proper 0..N entitlement-sources table replacing a single nullable subscription_id FK (§11, §3.11)

12.3 Open decisions for CTO sign-off

• Renewal resync policy — recommended: auto-resync + 30-day notice by default, per-plan override for sensitive tiers; large price-increase renewals may need forced confirmation regardless of default — confirm with commercial/legal
• Deployment topology — recommended: Entitlements + Authorization as two modules inside one Governance service, not day-one microservices
• Draft/Review/Publish — confirm no second-approver step is required at launch (current recommendation: no, granular permissions + audit suffice)
• Cascade revocation of delegated admin permissions — recommended: keep existing grants valid by default, with a UI warning + explicit opt-in cascade at revocation time
• Which business domain owns practitioner↔center attachment — confirmed NOT user_roles; a dedicated association/membership model must own it, gating both the auto-revoke-on-detachment contract and the PROFESSIONALS count_provider_key
• Consistency SLA sign-off — Class C ≤5s / Class A/B ≤60s bounded staleness (§13.7) is a security/compliance decision, not engineering
• [RESOLVED v4.4] max_users/max_sites vs. capacity_dimensions — removed entirely, folded into SITES/PROFESSIONALS/STAFF dimensions
• STAFF definition scope for non-CENTER subscriber types, and the Identity/account model for STAFF vs. PROFESSIONAL — both new in v4.6, deliberately left open rather than answered by implication

12.4 Validation Criteria (representative sample — the full document lists ~25)

• Reorganizing module_capabilities never changes the composition of any already-published plan_version
• Publishing a new plan_version never modifies any subscription_capability_access row; only future subscriptions/renewals resolve to it
• Confinement: a user attempting to grant a permission or scope they don't hold is REFUSED by can() at grant time — both permission and scope dimensions
• A user holding a valid, accepted, non-expired delegation but no direct role grant is AUTHORIZED — the pure-delegate case previously always refused
• A break-glass session correctly grants access to a resource in a center whose subscription is suspended, with gate: break_glass and a mandatory audit entry
• A permission with no capability_permissions row is evaluated by Phase 2 only — Phase 1 skipped because there is no capability to resolve against
• Two capability_activations rows at conflicting scope levels resolve by fixed priority (specific center > center_type+country > country > global), never ambiguously
• No synchronous write to authorization_decisions_log on the canAccess() request path

Answers one question: can the design in §1-§12 run strongly consistent and scale to thousands of requests/second? Short answer — it is strongly consistent today only because every check reads PostgreSQL directly, which is exactly why it will not scale as specified without the changes below. Scaling requires introducing controlled, bounded staleness, made explicit rather than implicit.

13.1 Problem Statement

• A naive canAccess() performs 8–12 PostgreSQL queries per call
• At 2,000–5,000 req/s with 1–3 checks per request → 20,000–150,000 queries/second against PostgreSQL for authorization alone
• A synchronous INSERT into authorization_decisions_log on every decision is severe write amplification on top of that
• A synchronous HTTP call to a central authorization service adds 5–20ms latency and a platform-wide single point of failure

13.2 Data Classification & Staleness Budget

13.3 Effective Permission & Entitlement Materialization

Precompute effective permission sets per (user, scope) in Redis (rbac:eff:{userId}:{scopeHash}); entitlement gates resolved once per subscription_id and shared (entitlements:eff:{subscriptionId}). Deny overrides checked against a separate, always-fresh structure so a cached grant can never survive an explicit deny. Multi-funder resolution materialized as party_entitlement:{partyTypeCode}:{partyId}:{capabilityId} → { entitled, allowedPermissionIds }.

13.4 Deployment Model — PAP / PDP

Refines, doesn't replace, the §12.3 one-service recommendation: the Governance service is the Policy Administration Point (source of truth, only writer); canAccess() reads a locally replicated policy snapshot (in-process cache backed by Redis) as the Policy Decision Point — same service boundary, not a network hop. Fail-closed: an unverifiable policy snapshot (cache empty AND PAP store unreachable) → reject, never authorize.

13.5 Asynchronous Decision Logging

Decisions published to a queue, batch-inserted — never synchronous on the request path. 100% of REFUSED + 100% of break-glass logged; AUTHORIZED sampled 1–10% (raisable during an investigation). Partitioned by month; UPDATE/DELETE revoked from the application's DB role.

13.6 Database Hardening for Scale

• Partial unique index on subscriptions: UNIQUE(owner_type_id, owner_id) WHERE status IN ('active','trial')
• UNIQUE NULLS NOT DISTINCT on every nullable-scope table (user_roles, user_permission_overrides, capability_activations, …)
• Hot-path indexes: delegations(delegate_user_id, is_active, expires_at), break_glass_sessions(user_id, is_active, expires_at), subscriptions(status, expires_at), capability_activations(capability_id, country_id, center_type_id, center_id)
• Read replicas for getEffectivePermissions/getEffectiveEntitlements/buildMenuTree/reporting; connection pooling (PgBouncer)
• All expiries evaluated live via expires_at > now(); sweeper jobs only reconcile flags for listing/reporting performance

13.7 Consistency Model

Target: bounded staleness with event-driven invalidation, not global strong consistency. Class C ≤5s, Class A/B ≤60s. Must be reviewed and signed off by security/compliance — it changes what “Zero-Trust — every access is verified” means in practice (§1.1).

13.8 Validation & Capacity Targets

Load: p99 ≤5ms on cache hit, ≤50ms cold path, 5,000 sustained checks/sec with PostgreSQL CPU <50%. Chaos: Redis loss (fail-closed + recovery), PAP outage (PDP survives on last-known-good snapshot within budget), invalidation storm without cache stampede (request coalescing/singleflight). Correctness: pure-delegate authorized, break-glass on suspended subscription, revocation-to-effect latency measured per class against the §13.7 SLA.

13.9 Migration Strategy

A full v1.0→current schema migration (frozen plan_versions, functional_capabilities, resources/permissions replacing submenu-keyed security) is non-trivial and out of scope for this document. Concrete near-term path: the Insurance portal, built largely from scratch — legacy submenu → resources row → permissions → capability_permissions mapping → submenu.resource_id. Existing Center/Provider screens exposing the same object are re-pointed at the same resources row rather than duplicating it (§13.9 — see Roadmap Phase 9).

13.10 Storage Growth

Partitioned, sampled decision logging (§13.5) and materialized caches (§13.3) are the primary levers keeping storage and write volume bounded as request volume scales — governed by the same staleness budget and retention-per-country policy defined above.