Encore OS — Documentation

Spec: PM-50
Created: 2026-04-07
Status: 📝 Planned

Overview

PM-50 provides ML-based claim denial prediction as a pre-submission advisory layer. It integrates into the PM-08 claim submission queue, complements PM-18 rule-based scrubbing, reads documentation completeness metadata from CL-36 via Platform Integration Layer, and uses PF-96 jurisdiction profiles for payer/state-specific context.

Integration Points

Platform Foundation Dependencies

PF Feature	Integration Type	Usage
PF-01 (Organizations & Sites)	Direct dependency	Tenant isolation, site-scoped predictions
PF-02 (RBAC)	Direct dependency	Permission checks for billing specialist and revenue cycle director roles
PF-10 (Notifications)	Platform Integration Layer	Send documentation request notifications to clinical team
PF-96 (Jurisdiction Profiles)	Platform Integration Layer	Read payer/state-specific parameters (filing deadlines, modifier conventions)

Same-Core Dependencies

PM Feature	Integration Type	Usage
PM-08 (Claims Management)	Shared UI surface	Risk scores displayed in claim submission queue; scoring triggered on claim queue entry
PM-18 (Claim Scrubbing)	Sequential pipeline	PM-18 scrubbing runs first (rule-based), PM-50 adds ML-based prediction after
PM-29 (Denial Management)	Data feedback	PM-29 denial outcomes feed PM-50 retraining pipeline (actual_outcome field)

Cross-Core Dependencies

Feature	Integration Type	Usage
CL-36 (Clinical Documentation)	Platform Integration Layer (`@/platform/clinical`)	Read documentation completeness metadata (note section count, word count, required section presence, diagnosis specificity); no PHI content crosses into PM-50

Events Published

Event Name	Publisher	Subscribers	Status
`pm.denial_prediction.created`	PM-50	None (available for GR dashboards)	📝 Planned
`pm.denial_prediction.outcome_recorded`	PM-50	None (available for analytics)	📝 Planned

Event Payload Schemas

pm.denial_prediction.created:

{
  prediction_id: string;
  claim_id: string;
  risk_level: 'low' | 'medium' | 'high';
  organization_id: string;
}

pm.denial_prediction.outcome_recorded:

{
  prediction_id: string;
  claim_id: string;
  actual_outcome: 'paid' | 'denied';
  organization_id: string;
}

Edge Functions

Function	Purpose	Auth
`predict-denial-risk`	Receive claim features, return risk score + reasons + actions	`verifyOrgAccess()`
`retrain-denial-model`	Cron-triggered monthly retraining using historical outcomes	Service role (cron)
`denial-prediction-metrics`	Return aggregated model performance metrics for dashboard	`verifyOrgAccess()`

Platform Integration Layer Usage

@/platform/notifications — Send documentation request to clinical team (FR-3.2)
@/platform/clinical — Read documentation completeness metadata from CL-36 (FR-3.1); PM-50 implements stub/adapter returning null signals when CL-36 unavailable

Data Flow

PM-08 (Claim enters queue) → PM-18 (Rule-based scrub) → PM-50 (ML prediction)
                                                              ↓
                                                    Risk Score + Actions
                                                              ↓
                                                    Biller Review (UI)
                                                    ├─ Acknowledge → Submit
                                                    ├─ Hold → Investigate
                                                    ├─ Correct → Re-queue
                                                    └─ Override → Submit with reason

Security Boundaries

No PHI crosses into PM-50 — only categorical/aggregate features and completeness metadata
All prediction data scoped to organization via RLS with SECURITY DEFINER helper
Model training data never crosses organization boundaries
Edge functions validate org access via verifyOrgAccess() from _shared/auth.ts

References

Spec: specs/pm/specs/PM-50-ai-denial-prediction-prevention.md
Related: PM-08, PM-18, PM-29, PM-49, CL-36, PF-96
Events: docs/architecture/integrations/EVENT_CONTRACTS.md
Platform layers: docs/architecture/integrations/PLATFORM_INTEGRATION_LAYERS.md

Encounter-Level Cost Accounting — Integration Automated Charge Reconciliation — Integration Doc

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-50 — AI-Powered Denial Prediction & Prevention

Overview

Integration Points

Platform Foundation Dependencies

Same-Core Dependencies

Cross-Core Dependencies

Events Published

Event Payload Schemas

Edge Functions

Platform Integration Layer Usage

Data Flow

Security Boundaries

References

​Overview

​Integration Points

​Platform Foundation Dependencies

​Same-Core Dependencies

​Cross-Core Dependencies

​Events Published

​Event Payload Schemas

​Edge Functions

​Platform Integration Layer Usage

​Data Flow

​Security Boundaries

​References

Overview

Integration Points

Platform Foundation Dependencies

Same-Core Dependencies

Cross-Core Dependencies

Events Published

Event Payload Schemas

Edge Functions

Platform Integration Layer Usage

Data Flow

Security Boundaries

References