> ## 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/cl/specs/CL-12-EN-67-bidirectional-referral-community.md Core: CL (Clinical & EHR) Status: Planned

**Spec:** `specs/cl/specs/CL-12-EN-67-bidirectional-referral-community.md`\
**Core:** CL (Clinical & EHR)\
**Status:** Planned

## Purpose

Define integration boundaries and contract expectations for closed-loop referral status updates with community providers and optional directory lookup integration for referral destinations.

## Integration Points

1. **Internal CL-12 referral workflow**
   * Source of truth for referral entity lifecycle.
   * Supports inbound status updates and closeout tracking fields/history.

2. **CL-18 relationship (boundary only)**
   * Shares conceptual status/closeout pattern where useful.
   * No duplication of SDOH domain ownership.

3. **External directory lookup**
   * Optional FindTreatment.gov (or Arizona directory) read-only lookup.
   * Backend-only API calls via adapter/edge function.
   * Secret reference resolved from Supabase Vault at runtime.

## Security and Tenancy

* All mutation paths must enforce `organization_id` isolation.
* RLS policies required for new referral status history structures.
* FindTreatment.gov requires pre-approval (access request form) but no runtime API key. Adapter pattern supports future credential-based directories via Supabase Vault. No API keys in client code, logs, or front-end bundles.
* No PHI in integration logs; use identifiers only as required for operational tracing.

## Data Model

* **`cl_referral_status_history`** — Append-only table; columns: `id`, `organization_id`, `referral_id` (bare UUID → `pm_referrals.id`), `status` (enum: sent, accepted, declined, patient\_connected, patient\_did\_not\_connect, closed), `patient_connected`, `patient_connected_at`, `external_status_source`, `notes`, `custom_fields JSONB`, `created_at`, `created_by`.
* **`cl_referral_current_status`** — View (`security_invoker = true`): latest status per referral via `DISTINCT ON (referral_id)`.

## API/Event Contract Notes

### Inbound referral status update contract

* **Fields:** `referral_id` (UUID, required), `status` (enum, required), `patient_connected` (boolean, optional), `patient_connected_at` (timestamptz, optional), `external_status_source` (enum: partner\_api | manual | file\_import, optional), `notes` (text, optional).
* **Validation:** Allowed status enum values; tenant ownership check (`referral_id` exists in `cl_transitions` for caller's `organization_id`); append-only (no UPDATE).

### Directory lookup contract (edge function: `cl-referral-directory-search`)

* **Upstream API:** FindTreatment.gov v1.10 — `GET /locator/exportsAsJson/v2?{querystring}`.
* **Request (internal):** `{ sType?: 'sa' | 'mh', limitType: 0 | 1 | 2, limitValue: string, lat?: number, lng?: number, page?: number, pageSize?: number }`.
* **Response (normalized):** `{ results: [{ name, address, phone, services: string[], accepting_new_patients: boolean }], total: number, page: number }`.
* **Auth:** FindTreatment.gov requires pre-approval via SAMHSA access request form; no runtime API key. Adapter pattern supports future credential-based directories (Vault-stored). CORS via `getCorsHeaders(req.headers.get('origin'))`.

### Events Published

| Event                        | Channel     | Payload                                                                   |
| ---------------------------- | ----------- | ------------------------------------------------------------------------- |
| `cl_referral_status_updated` | `cl_events` | `{ organization_id, referral_id, status, patient_connected, created_at }` |

## Permission Keys

| Key                            | Description                                     |
| ------------------------------ | ----------------------------------------------- |
| `cl.referral_status.view`      | View referral status history and current status |
| `cl.referral_status.manage`    | Record status updates and closeout              |
| `cl.referral_directory.search` | Search external provider directory              |

## Testing Expectations

* **Unit:** Status enum validation, closeout derivation, directory response normalization, referral\_id ownership check. Files: `tests/unit/cl/referral-status-history.test.ts`, `tests/unit/cl/referral-directory-search.test.ts`.
* **RLS:** Tenant isolation on `cl_referral_status_history`; INSERT org-scoped; UPDATE blocked; DELETE org\_admin only. File: `tests/rls/cl-referral_status_history.rls.test.ts`.
* **Integration:** Chart display of status history; directory search edge function (mocked). File: `tests/integration/cl/cl-referral-status-history.test.ts`.
* **E2E:** Create referral → status update → closeout → outcome report → CSV export. File: `tests/e2e/cl/referral-closed-loop.spec.ts`.