PF-100: Platform Ambient Transcription & AI Note Generation — Integration Contract

Cross-core integration contract for PF-100. Captures the boundary between PF (capture, STT, LLM, template engine, evidence map, lifecycle) and consuming cores (CL, PM, HR, GR, CE, RH). All cross-core consumption is via @/platform/transcription — no direct module imports.

​

1. Pattern

• Layer: @/platform/transcription exposes hooks, components, types.
• Events: pf.transcription.* event family published; cores subscribe via PF-66 realtime + edge-function subscriptions.
• Tables: pf_transcription_* owned by PF; cores own their domain tables (e.g. cl_progress_notes, hr_meeting_summaries) and link via session_id UUID column (no cross-core FK except CL → PM encounter per ADR-002).

​

2. Scope of contract

​

3. Public API surface (@/platform/transcription)

import {
  useStartTranscriptionSession,
  useReviewQueue,
  useAttestDraft,
} from '@/platform/transcription';

// CL example (encounter-linked)
const start = useStartTranscriptionSession();
await start.mutateAsync({
  module_key: 'cl',
  recording_purpose: 'cl_individual',
  encounter_id,
  subject_of_record_type: 'patient',
  subject_of_record_id: patient_id,
  source: 'browser',
});

// HR example
await start.mutateAsync({
  module_key: 'hr',
  recording_purpose: 'hr_one_on_one',
  subject_of_record_type: 'employee',
  subject_of_record_id: employee_id,
  source: 'browser',
});

​

4. Event Contracts

​

Consumed events

• pf.consent.cl_consent.revoked (CL-11) — triggers session-revocation cascade for any active CL session referencing the consent
• pf.encounter.created (PM) — optional auto-link encounter for a clinical session in pre-record state
• pf.encounter.cancelled (PM) — cancels any in-progress capture for that encounter

​

5. Cross-core FK rules (ADR-002 compliance)

• pf_transcription_sessions.encounter_id — UUID column with no FK constraint to pm_encounters.id at the database level (cross-core FK exception is reserved for CL→PM, not PF→PM).
  • Validation is enforced at the application layer (edge function pf-transcription-start-session rejects sessions whose encounter_id does not resolve to an existing pm_encounters.id in the same organization_id at session start).
  • No trigger-enforced FK is created; an earlier draft of spec §7.1 implied a trigger — that has been corrected.
• pf_transcription_sessions.subject_of_record_id — polymorphic UUID; no FK.
• CL projection layer (Phase 3): cl_ambient_sessions becomes a VIEW over pf_transcription_sessions WHERE module_key='cl'. The CL→PM FK from CL-36-EN-01’s existing schema is preserved independently on the CL side (via a separate cl_ambient_session_encounters materialization or a CL-owned trigger that enforces the FK only when module_key='cl' AND encounter_id IS NOT NULL). PF-100 itself does not own the CL→PM FK; the CL DX team retains that responsibility per ADR-002.

​

6. Vendor adapter contract

​

7. CL-36 migration contract (Phase 3)

1. cl_ambient_sessions continues writing through CL-36 hooks; PF-100 hooks are added in parallel and wrap the same vendor calls.
2. CL backend swap: cl_ambient_sessions becomes a VIEW over pf_transcription_sessions WHERE module_key='cl'; cl_ambient_transcripts similarly over pf_transcription_segments.
3. CL-36 attribution overlay (cl_ai_note_attributions) consumes pf.transcription.draft.attested event with module_attest_payload.cl_progress_note_id.
4. CL-36 hooks become deprecated shims; deletion in next major release per constitution §8.4 deprecation policy.

​

8. PF-96 jurisdiction profile extension contract (PF-96-EN-RECORDING)

• recording_consent_model
• wiretap_class_severity
• recording_max_retention_days_part2
• recording_max_retention_days_general_clinical
• recording_max_retention_days_hr
• recording_max_retention_days_gr
• external_recorder_allowed
• external_recorder_forbidden_for_part2
• mental_health_record_retention_years
• requires_visible_recording_indicator
• requires_per_participant_verbal_affirmation
• recording_pause_resume_consent_threshold_seconds

​

8A. PF-71 dependency contract (patient-name list lookup)

// supabase/functions/_shared/pf-71/patient-name-list.ts (PF-71 owned)
export async function pf71PatientNameList(args: {
  organization_id: string;
  encounter_id?: string;          // when present, returns names of all patients linked to the encounter
  group_session_id?: string;      // when present, returns names of all attendees of the group session
  context: 'draft_redaction';
}): Promise<{ names: string[]; phonetic_variants: string[]; }>;

• Returns first/last/preferred names + phonetic/common-misspelling variants for every patient in scope.
• Excludes the subject-of-record (caller passes subject_of_record_id separately).
• Server-side only — never invoked from the browser.
• Names are used solely for redaction matching; PF-100 MUST NOT log returned names. Edge function logs only counts ({ matched_count: N }).

​

9. PF-91 evidence emission contract

• Part 2 control evidence (is_part2_program=true only): consent record id + version, segregation hash (Part 2 KMS alias confirmation), retention proof, deletion proof.
• All-party consent control evidence: per-participant consent acknowledgment timestamps, jurisdiction profile id, recording-indicator-shown proof.
• Retention control evidence: applied retention policy, scheduled deletion date, actual deletion timestamp.
• BAA-coverage control evidence: vendor id, BAA evidence id, model version, call counts.

​

10. Audit & enforcement

• npm run audit:integration-contracts — verifies this file is referenced from PF-100 spec
• npm run audit:permissions — verifies all keys in PF-100 §6 are seeded
• npm run audit:routes-navigation — verifies any new routes (e.g. /platform/transcription/sessions, /platform/transcription/review) are registered

​

11. Backlinks

• Spec: PF-100
• Predecessor: CL-36, CL-36-EN-01
• Predecessor integration: CL-36-ai-documentation-INTEGRATION.md
• Jurisdiction: PF-96-medicaid-state-compliance-configuration-INTEGRATION.md
• Cross-core matrix: CROSS_CORE_INTEGRATIONS.md
• Architecture decisions: ADR-002-cl-pm-cross-core-foreign-keys.md

​

Activating a Vendor (Runbook)

Until these four steps are completed for at least one STT vendor, every call to pf-transcription-stt-stream returns 409 vendor_baa_inactive. LLM note generation works today via Lovable AI Gateway (no BAA gate).

1. Sign the BAA — paper artifact between the org and the vendor (Deepgram / AssemblyAI / AWS). Cannot be code-completed.
2. Register the BAA row in pf_transcription_vendor_baas:
   INSERT INTO pf_transcription_vendor_baas
     (organization_id, vendor_id, status, baa_signed_at, baa_expires_at)
   VALUES ('<org>', '<vendor_id>', 'active', now(), now() + interval '1 year');
   
   Use the Settings → Transcription → Vendors UI (VendorBaaTable) instead of raw SQL when possible.
3. Add the API key to PF-76 vault under the credential name expected by the adapter (e.g. deepgram_api_key). The router calls pf_retrieve_credential(org_id, name); missing keys surface as vendor_baa_inactive with reason: 'missing_credential'.
4. (Optional) Add a routing rule in pf_transcription_jurisdiction_routing so a specific (jurisdiction_code, recording_channel) resolves to this vendor instead of the org default.

​

PF-100-EN-01 — Ambient Vendor-BAA Enablement Runbook