Encore OS — Documentation

Version: 0.1 (stub created by spec-review 2026-04-19) Created: 2026-04-19 Last Updated: 2026-04-19 Status: 📝 Planned (stub — to be expanded during Phase A implementation) Spec: specs/pm/specs/PM-53-refund-recoupment-takeback-management.md

Overview

PM-53 introduces three first-class money-out / money-clawed-back workflows on top of PM-09: patient refund, payer recoupment / takeback detection, and disputed-takeback escalation to PM-29. PM-53 owns the operational data model and state machines; FA owns GL posting and is reached exclusively via event publishing to cl_pm_events. PM-37 (proposed) owns the patient liability ledger and consumes append events when it ships (Phase C, deferred). This stub captures the canonical integration points; full payload schemas and consumer contracts will be expanded during Phase A implementation. See the spec’s Event Contracts section for authoritative payload definitions today.

Integration Points

Platform Foundation (PF) Dependencies

PF Spec	Integration Type	Description
PF-04 (Audit)	Direct dependency	All refund/recoupment state transitions captured in PF audit pipeline
PF-10 (Notifications)	Platform Integration Layer	`pm.refund.approval_required` notifications to tier-2/3 approvers (FR-8)
PF-30 (RBAC)	Direct dependency	Permission keys: `pm.refunds.{view,create,approve}`, `pm.recoupments.{view,manage}` (5 keys)
PF-44 (HIPAA Audit Controls)	Direct dependency	Append-only audit of refund decisions and recoupment dispositions (US-4)
PF-96 (Jurisdiction Profiles)	Platform Layer	Recoupment dispute window resolution via `useJurisdictionProfile().recoupmentDisputeWindowDays` (FR-5.3)

Same-Core Dependencies (PM)

PM Spec	Integration Type	Description
PM-09 (Payment Posting & ERA)	Data dependency / Edge Function extension	Source of `pm_payments` for original payment selection; ERA parser extension (`process-era`) detects CARC/PLB takebacks
PM-15 (Clearinghouse)	Co-resident in `process-era`	Recoupment detection lives inside the existing PM-15 ERA pipeline (no new edge function)
PM-23 (Contract & Fee Schedule)	Indirect data dependency (via PM-44 outputs)	Contract rate/variance interpretation for recoupment context is supplied through PM-44 outputs; PM-44 depends on PM-23, PM-53 receives context via PM-44
PM-28 (Module Settings)	Data dependency	Owns `pm_module_settings` table; PM-53 contributes refund threshold + tier role columns
PM-29 (Denial & Appeals)	API / action	Disputed recoupments create pre-populated `pm_claim_appeals` rows (FR-5.1)
PM-37 (Self-Pay AR Ledger — proposed)	Event consumer (deferred)	When PM-37 ships, consumes `payment_refund_issued` and `payer_recoupment_detected` to append patient-liability ledger rows (Phase C)
PM-44 (ERA Reconciliation & Underpayment)	Cooperative filter	Excludes claim lines with active recoupments to avoid double-counting reversed payments (FR-6.1)
PM-45 (Patient Payment Plans & Collections)	Data / token dependency	Refund via `card_token_reverse` uses PM-45 payment-processor token from the original payment; refund may settle written-off bad debt (link maintained)

Cross-Core Dependencies

Core	Integration Type	Description
FA (Cash Receipts / GL)	Event-based (consumer)	Consumes `payment_refund_issued` from `cl_pm_events`; creates the GL journal entry; writes `fa_journal_entry_id` back to `pm_refunds` (existing batch consumer pattern from RH episode events)

Event Contracts

Events Published

Event	Subscribers	Payload	Idempotency Key	Purpose
`payment_refund_issued`	FA Cash Receipts / GL consumer	See spec § Event Contracts for full schema	`refund_id`	Triggers FA GL posting and `fa_journal_entry_id` writeback
`payer_recoupment_detected`	PM-44 (filter cooperation), FA (informational), PF-10 (AR Manager alert), PM-37 (Phase C)	See spec § Event Contracts for full schema	`recoupment_id`	Notifies downstream consumers of a new payer takeback

PHI minimization: Both payloads contain only opaque UUIDs (patient_id, refund_id, original_payment_id) and amounts, but patient-linked identifiers should be treated as sensitive metadata and handled with PHI/PII-safe logging, notification, and access controls per the documentation guidelines. Additional safeguards (e.g., masking, access checks, audit logging) are recommended when UUIDs are used to correlate patient records.

Events Consumed

PM-53 does not consume cross-core events in MVP. The process-era extension reads incoming 835 segments (already processed by PM-09 / PM-15) and creates recoupment rows synchronously during ERA ingestion.

API Contracts

PM-53 does not expose new external APIs. All cross-core communication is via events. Internal frontend hooks (useRefunds, usePayerRecoupments, etc.) call Supabase RPC / table queries directly under RLS.

Permission Keys (5 keys)

Key	Purpose
`pm.refunds.view`	Read refund list and details
`pm.refunds.create`	Insert `pm_refunds` row
`pm.refunds.approve`	Insert `pm_refund_approvals` decision (tier 1/2/3 actions)
`pm.recoupments.view`	Read recoupment queue and details
`pm.recoupments.manage`	Mutate `pm_payer_recoupments` (accept / dispute / mark resolved)

Pending Items (to be expanded)

Concrete consumer contract for FA Edge Function (fa-consume-pm-payment-events or new fa-consume-pm-refund-events).
Phase C contract with PM-37 (deferred — populated when PM-37 ships).
Notification template pm.refund.approval_required payload schema and PF-10 registration.
Jurisdiction profile schema additions for recoupmentDisputeWindowDays (PF-96 cross-link).

These items are tracked in PENDING_CONTRACTS.md under PM-53.

References

Spec: specs/pm/specs/PM-53-refund-recoupment-takeback-management.md
Cross-core matrix: CROSS_CORE_INTEGRATIONS.md — PM-53 row registered after PM-44.
Event contracts (general): EVENT_CONTRACTS.md
Adjacent integrations:
Lite alternatives (superseded 2026-04-19): PM-09-EN-11, PM-09-EN-15

Start Here

Module Engineering Snapshots

Canonical AI Governance

Architecture

Integrations

Development

Decision Guides

Database

Module Reference

Testing

Migration

Operations

Governance & Security

Platform Internals

Integration Documentation: PM-53 — Refund, Recoupment & Takeback Management

Overview

Integration Points

Platform Foundation (PF) Dependencies

Same-Core Dependencies (PM)

Cross-Core Dependencies

Event Contracts

Events Published

Events Consumed

API Contracts

Permission Keys (5 keys)

Pending Items (to be expanded)

References

​Overview

​Integration Points

​Platform Foundation (PF) Dependencies

​Same-Core Dependencies (PM)

​Cross-Core Dependencies

​Event Contracts

​Events Published

​Events Consumed

​API Contracts

​Permission Keys (5 keys)

​Pending Items (to be expanded)

​References

Overview

Integration Points

Platform Foundation (PF) Dependencies

Same-Core Dependencies (PM)

Cross-Core Dependencies

Event Contracts

Events Published

Events Consumed

API Contracts

Permission Keys (5 keys)

Pending Items (to be expanded)

References