Encore OS — Documentation

Version: 1.1
Last Updated: 2026-03-02 (manual follow-up: FA journal entry guidance, deleted_at, pending contracts updated)
Status: 📋 Planned
Spec: PM-33 Capitation & PMPM Revenue Reconciliation
Constitution Reference: Section 1.2 (Core Independence), Section 1.3 (Integration Patterns)

Overview

PM-33 adds capitation contract management, roster tracking (enrollment/dis-enrollment), monthly period generation, and payment reconciliation for PMPM contracts. It integrates with PM-01 (patient/member identity for roster events), PM-09 (payment posting), PM-11 (RCM dashboard — capitation revenue and utilization), PM-23 (contract terms reference), and FA (revenue recognition via capitation_payment_received event).

Integration Points (from spec)

Dependency	Pattern	Purpose	Status
PM-01	Data (same core)	Patient/member identity for `pm_capitation_roster_events.patient_id`	📋 Planned
PM-09	Data (same core)	Future: link capitation payment posting to PM-09 payment records	📋 Deferred (MVP: PM-33 dedicated flow)
PM-11	Data (same core)	Capitation revenue and utilization vs. cap in RCM dashboard	📋 Planned
PM-23	Data (same core)	Contract terms cross-reference (no FK in MVP; future: link to pm_contracts)	📋 Deferred
FA	Event (`capitation_payment_received`)	Revenue recognition — FA consumes event for AR/revenue posting	📋 Planned
PF-30	Platform Layer	Permission seeding — `pm.capitation.view`, `pm.capitation.manage`	📋 Planned

Data Source Tables (PM-33)

Table	Key Columns	Used By
`pm_capitation_contracts`	organization_id, payer_id, pmpm_rate, effective_from, effective_to, roster_source, deleted_at	Contract list (active only: `WHERE deleted_at IS NULL`), period generation
`pm_capitation_periods`	contract_id, period_start_date, enrolled_member_count, expected_revenue, received_revenue, status	RCM dashboard (PM-11), reconciliation
`pm_capitation_roster_events`	contract_id, patient_id, member_id_external (encrypted), event_type, effective_date, source	Roster management, enrollment count
`pm_capitation_reconciliations`	period_id, expected_amount, received_amount, variance_amount, variance_disposition, reconciled_by	Variance tracking, audit trail

Event Contract: `capitation_payment_received`

Publisher: PM (pm_capitation_reconciliations on payment post)
Subscriber: FA (AR / revenue recognition)
Status: 📋 Pending — EVENT_CONTRACTS.md entry to be created as a generate-tasks task. Draft payload:

{
  "event": "capitation_payment_received",
  "version": "1.0",
  "payload": {
    "organization_id": "uuid",
    "contract_id": "uuid",       // → pm_capitation_contracts.id
    "period_id": "uuid",         // → pm_capitation_periods.id
    "amount": "numeric",         // received_amount
    "payment_date": "date",
    "payer_id": "uuid",          // → pm_payers.id
    "reconciliation_id": "uuid"  // → pm_capitation_reconciliations.id
  }
}

Security: Event payload must not include member_id_external or any PHI. organization_id is required for FA tenant isolation.

FA Journal Entry Guidance (GAAP ASC 606)

Capitation revenue is recognized ratably over the service period (not upon cash receipt). The FA consumer of capitation_payment_received should post the following journal entry:

Account	Dr / Cr	Amount	Notes
Cash / AR (asset)	Dr	`amount`	Cash received from MCO
Capitation Revenue (revenue)	Cr	`amount`	Recognized for `period_id` service period

Period matching: FA must use period_id (→ pm_capitation_periods.period_start_date / period_end_date) to post revenue to the correct accounting period. Payments received outside the service month (early or late) must still credit the revenue account for the period covered, not the cash receipt date — confirm with CFO/Controller. Deferred revenue consideration: If MCO pays capitation in advance of the service month, FA may need a deferred revenue liability entry until the period begins. Confirm with FA team whether advance capitation payments occur in practice. FA team confirmation required (PENDING_CONTRACTS.md): FA team must confirm the chart of accounts structure (account codes for MCO capitation revenue, payer-specific AR) before EVENT_CONTRACTS.md entry is finalized.

Platform Layer Usage

PM-11: Reads pm_capitation_periods (expected_revenue, received_revenue, status) and pm_encounters (encounter count vs. capitation amount) for dashboard widgets. No new event contracts; same-core data access.
PF-30 Permissions: pm.capitation.view and pm.capitation.manage seeded via migration; checked via useHasPermission in UI.
@/platform/csv: Bulk import pattern for CSV roster upload; column mapping derived from pm_capitation_roster_events schema.

Integration Matrix

From	To	Pattern	Status	Doc
PM (PM-33)	FA	Event (`capitation_payment_received`)	📋 Planned	This doc; EVENT_CONTRACTS.md stub pending
PM (PM-33)	PM-11	Data (same core)	📋 Planned	This doc
PM (PM-33)	PM-01	Data (same core, patient_id FK)	📋 Planned	This doc
PM (PM-33)	PM-09	Data (same core, future payment link)	📋 Deferred	This doc
PM (PM-33)	PM-23	Data (same core, future contract FK)	📋 Deferred	This doc

Pending Contracts

Contract	Blocked On	What’s Needed
capitation_payment_received EVENT_CONTRACTS.md entry	PM-33 implementation	Formalize event payload; FA team to confirm chart of accounts (capitation revenue account codes, payer-specific AR) and deferred revenue handling for advance MCO payments — see FA Journal Entry Guidance above
PM-33 to PM-11 utilization query	PM-11 implementation	Define SQL: encounter count per contract per period vs. capitation amount; join pm_capitation_periods + pm_encounters on organization_id + period date range; confirm join key with PM-11 implementation

Security Notes

All four PM-33 tables are RLS-protected with pm_has_org_access(organization_id, auth.uid()).
UPDATE policies include WITH CHECK preventing organization_id modification.
member_id_external is PHI; encrypted at rest via pgcrypto; decrypt only via pm_decrypt_member_id() SECURITY DEFINER function.
capitation_payment_received event must never include PHI in payload.

Start Here

Module Engineering Snapshots

Canonical AI Governance

Architecture

Integrations

Development

Decision Guides

Database

Module Reference

Testing

Migration

Operations

Governance & Security

Platform Internals

Capitation & PMPM Revenue Reconciliation — Integration

Overview

Integration Points (from spec)

Data Source Tables (PM-33)

Event Contract: `capitation_payment_received`

FA Journal Entry Guidance (GAAP ASC 606)

Platform Layer Usage

Integration Matrix

Pending Contracts

Security Notes

References

​Overview

​Integration Points (from spec)

​Data Source Tables (PM-33)

​Event Contract: capitation_payment_received

​FA Journal Entry Guidance (GAAP ASC 606)

​Platform Layer Usage

​Integration Matrix

​Pending Contracts

​Security Notes

​References

Overview

Integration Points (from spec)

Data Source Tables (PM-33)

Event Contract: `capitation_payment_received`

FA Journal Entry Guidance (GAAP ASC 606)

Platform Layer Usage

Integration Matrix

Pending Contracts

Security Notes

References