Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt

Use this file to discover all available pages before exploring further.

Spec: specs/pm/specs/PM-07-EN-13-jurisdiction-aware-billing-rules.md
Feature ID: PM-07-EN-13
Core: PM
Status: Draft (ready for implementation pending review)

​
Summary

PM-07 timed-unit and modifier logic consumes jurisdiction-specific billing configuration from PF-96 profiles to remove hardcoded Arizona constants while preserving Arizona parity behavior.

​
Integration Pattern

  • Publisher Core: PF (jurisdiction profile data ownership)
  • Consumer Core: PM (charge capture and billing rules evaluation)
  • Pattern: Direct configuration dependency. PM reads PF-96 jurisdiction profile values via pf_resolve_jurisdiction_profile() (SECURITY DEFINER) per docs/architecture/integrations/API_CONTRACTS.md § PF-96 and docs/architecture/integrations/PF-96-medicaid-state-compliance-configuration-INTEGRATION.md. Frontend uses useJurisdictionProfile() from @/platform/jurisdiction; edge functions use the RPC directly.
No direct CL import paths are introduced — this integration concerns PM and PF only.

​
Data Contract (Read)

PM consumes the resolved JurisdictionProfile (defined in src/platform/jurisdiction/types.ts) and reads:
  • billing.min_billable_minutes (number; AZ default 8)
  • billing.timed_code_unit_minutes (number; AZ default 15)
  • billing.modifier_conventions (ModifierConvention[]; may be empty)
  • clinical.iop_php_compliance (IOP/PHP threshold and program-naming behavior)
  • display_name (program label, e.g. “AHCCCS”)
Naming note: the underlying column is pf_jurisdiction_profiles.billing_rules (JSONB). Both pf_resolve_jurisdiction_profile() and useJurisdictionProfile() expose this JSON under the billing key on JurisdictionProfile. PM code MUST reference the runtime field billing.*, not the column name billing_rules.*.

​
Failure Modes

ConditionBehaviorLogging
Profile RPC unreachable / timeoutFall back to AHCCCS hardcoded defaultswarn (no PHI)
Profile resolved but billing key missingFall back to AHCCCS hardcoded defaultswarn
modifier_conventions empty/undefinedUse legacy hardcoded modifier logicnone
min_billable_minutes <= 0Return 0 units (safety guard)none
Failure posture is fail-open / fail-safe (charges continue to flow with AZ defaults), not fail-closed. No retry/idempotency contract is required: configuration reads are cached per-request in the edge function and via useJurisdictionProfile() (staleTime: 5 min, gcTime: 10 min) on the frontend.

​
Security and Tenant Isolation

  • Profile reads scoped by organization_id (and site_id when supplied).
  • All resolution flows through pf_resolve_jurisdiction_profile(p_org_id, p_site_id) SECURITY DEFINER (search_path = public, pg_catalog); PM code does not query pf_jurisdiction_profiles directly.
  • No PHI in profile resolution; no PHI in fallback warnings.
  • Billing calculations remain auditable via existing PM-07 charge audit paths.
  • No new permission keys; uses existing pm.charges.create / pm.charges.edit.

​
Backward Compatibility

  • Arizona organizations remain behaviorally equivalent to legacy PM-07 logic.
  • No breaking schema changes.
  • Existing PM-07 unit/integration tests remain green with AZ fixture parity.
  • specs/pm/specs/PM-07-charge-capture-fee-schedules.md
  • specs/pf/specs/PF-96-medicaid-state-compliance-configuration.md
  • specs/pm/specs/PM-07-EN-14-payer-specific-modifier-rules-engine.md
  • specs/pm/specs/PM-08-EN-13-jurisdiction-aware-filing-deadlines.md (sibling pattern)
  • specs/pm/specs/PM-01-EN-02-jurisdiction-aware-patient-identifiers.md (sibling pattern)