> ## 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.

# Integration Contract

> 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)

**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

| Condition                                  | Behavior                               | Logging         |
| ------------------------------------------ | -------------------------------------- | --------------- |
| Profile RPC unreachable / timeout          | Fall back to AHCCCS hardcoded defaults | `warn` (no PHI) |
| Profile resolved but `billing` key missing | Fall back to AHCCCS hardcoded defaults | `warn`          |
| `modifier_conventions` empty/undefined     | Use legacy hardcoded modifier logic    | none            |
| `min_billable_minutes <= 0`                | Return 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.

***

## Related Specs

* `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)