​

PF-111 — Unified AI Gateway Integration

Integration with an external system (Vercel AI Gateway), not a cross-core integration. Listed here for the external-integration catalog; not added to CROSS_CORE_INTEGRATIONS.md (no core-to-core surface).

​

External System

​

Consumers (16 edge functions)

​

Contract (to be finalized in Phase 1)

• Request: OpenAI-compatible chat-completions body (model, messages, optional tools, tool_choice, temperature, max_tokens, stream).
• Response (non-stream): normalized to { content, toolCalls?, usage?, modelUsed }.
• Response (stream): SSE passthrough, OpenAI-compatible frames (consumed by src/platform/ai/utils/encoreOpenAiSseChatTransport.ts).
• Errors: { error: { code, message } }, sanitized; 429 retried with backoff; 402/401 non-retryable; ≥500 retryable.
• PHI lane: lane: 'phi' resolves to BAA-covered models for modules with a PHI-lane configuration, and throws PhiLaneNotConfiguredError for any module that does not. As of 2026-05-29, the clinical (cl) and practice management (pm) modules are enabled on the PHI lane with anthropic/claude-sonnet-4.6 (primary) and openai/gpt-4o (fallback) — both BAA-covered through the Vercel AI Gateway. All other modules continue to fail closed on lane: 'phi'.

​

PHI lane routing

// supabase/functions/_shared/ai/models.ts
export const PHI_MODELS: Record<string, string[]> = {
  cl: ['anthropic/claude-sonnet-4.6', 'openai/gpt-4o'],
  pm: ['anthropic/claude-sonnet-4.6', 'openai/gpt-4o'],
};

​

Trace store (Langfuse)

1. Execute a Langfuse BAA.
2. Rotate LANGFUSE_BASE_URL to https://hipaa.cloud.langfuse.com (or a self-hosted instance).
3. Update AI_SUBPROCESSOR_BAA_POSTURE.md and the REGULATORY_COMPLIANCE_TRACKER row.

​

Open items

• Confirm "provider/model" ids (incl. an embedding model for generate-embeddings) against the live catalog.
• Finalize request/response examples once the gateway is wired (Phase 1).

​

PF-111-EN-01 — AI Usage/Audit Ledger + Cost Governance

​

Producer / Consumer Matrix

​

Event Contract

​

API / RPC Surface

pf_record_agent_phi_access(
  p_organization_id        UUID,
  p_agent_principal_id     UUID,
  p_authorizer_user_id     UUID,
  p_operation              TEXT,            -- 'read' | 'write'
  p_resource_table         TEXT,
  p_resource_ref           UUID DEFAULT NULL,
  p_session_id             UUID DEFAULT NULL,
  p_parent_task_id         UUID DEFAULT NULL,
  p_governance_approval_id UUID DEFAULT NULL,  -- required for 'write' (FR-12)
  p_phi_category           TEXT DEFAULT NULL,  -- e.g. 'clinical' | 'sud_part2'
  p_correlation_id         TEXT DEFAULT NULL
) RETURNS UUID

pf_agent_usage_rollup(
  p_organization_id UUID,
  p_since           TIMESTAMPTZ DEFAULT (now() - interval '30 days')
) RETURNS TABLE (
  agent_principal_id UUID,
  session_id         UUID,
  calls              BIGINT,
  total_tokens       BIGINT,
  total_cost_usd     NUMERIC,
  total_latency_ms   BIGINT,
  phi_touches        BIGINT
)

pf_ai_usage_rollup(p_organization_id, p_billing_month)
RETURNS TABLE (billing_month, consumer_module, model_used, total_tokens, estimated_cost_usd)

• checkAgentBudget(input: AgentBudgetInput, projectedCost: number): AgentBudgetVerdict — pure, synchronous budget-decision function. Evaluates task → agent → org hard caps independently; returns { throttled: true, dimension, limit, used } on a hard breach and { throttled: false, warn: true } on an org soft-limit breach. Not yet wired into the gateway dispatch path.
• recordAgentPhiAccess(rpc: UsageRpcClient, input: PhiAccessInput): Promise<{ recorded: true; id: string }> — calls pf_record_agent_phi_access via RPC; throws PhiAccessLogError on failure; caller MUST re-throw to block the PHI operation.
• buildUsageRecord(module, result): AIUsageRecord (in _shared/ai/usage.ts) — builds a PHI-safe token record; persistence to pf_ai_usage_logs is planned (FR-2) but not yet wired.

​

Data / FK Contract

​

PHI / RLS / Tenant-Scoping Notes

• pf_ai_usage_logs — RLS on organization_id; org-member reads; gateway / service-role writes. No content columns: prompt_tokens, completion_tokens, total_tokens are integer counts only. The table has no column capable of holding prompt or response text (NFR-1 enforced by schema, not policy).
• pf_agent_phi_access_log — deny-by-default RLS. SELECT requires both pf_has_org_access and the pf.audit.phi_access.view permission (compliance / admin readers only). INSERT is exclusively via the pf_record_agent_phi_access SECURITY DEFINER RPC. UPDATE is revoked from authenticated; no DELETE policy. Append-only audit by construction.
• pf_agent_usage_rollup — SECURITY DEFINER function; pf.audit.phi_access.view gated; returns only aggregated counts and costs — no content, no per-row PHI exposure.
• SUD category handling — PHI touches on 42 CFR Part 2 records set phi_category='sud_part2'; the access event is recorded here, but the protected SUD content itself is governed by CL / PF-27-EN-01. This table records the access event identifier, not the content.
• No cross-core FKs — resource_table / resource_ref are soft (text + UUID) references, enabling PHI-touch audit of any-core records without a DB-level FK. agent_principal_id / session_id / parent_task_id are loose UUID references to PF-30-EN-01 and PF-125 entities (same-platform, no FK declared).
• Compliance gate — specs/pf/reviews/PF-111-EN-01-COMPLIANCE-SIGNOFF.md must exist before pipeline_status may advance to compliance_reviewed (governed spec; regulated PHI-adjacent audit trail).

​

Open Items

​

PF-111-EN-02 — AI Eval / Observability Quality Gate