CL-24 Integration Contract: Telehealth Documentation & Compliance

​

Purpose

​

Ownership boundary

Why CL-24 does not publish modifier data: the modifier (95 / FQ / GQ) is a billing decision that depends on payer policy, not a clinical compliance event. PM-07 has owned this since CL-PM-TELEHEALTH v1.1.0. Adding a parallel publisher in CL-24 would create two sources of truth.

​

Published events (4)

​

1. cl_telehealth_consent_captured

{
  event: 'cl_telehealth_consent_captured';
  publisher: 'CL';
  payload: {
    consent_id: string;
    organization_id: string;
    chart_id: string;
    consent_type: 'telehealth_general' | 'audio_only';
    expires_at: string; // ISO 8601
  };
  metadata: { organization_id, user_id, timestamp, correlation_id, event_id };
}

​

2. cl_telehealth_consent_revoked

{
  event: 'cl_telehealth_consent_revoked';
  publisher: 'CL';
  payload: {
    consent_id: string;
    organization_id: string;
    chart_id: string;
    consent_type: 'telehealth_general' | 'audio_only';
    revoked_at: string; // ISO 8601
  };
  metadata: { organization_id, user_id, timestamp, correlation_id, event_id };
}

PM-13 contract: on receipt, PM-13 must refuse to release a join URL for any future pm_telehealth_sessions whose linked chart matches chart_id and whose required consent_type is now revoked. Re-establishing consent is handled by capturing a new consent row, which re-emits cl_telehealth_consent_captured.

​

3. cl_telehealth_consent_expiring

{
  event: 'cl_telehealth_consent_expiring';
  publisher: 'CL';
  payload: {
    consent_id: string;
    organization_id: string;
    chart_id: string;
    consent_type: 'telehealth_general' | 'audio_only';
    expires_at: string;     // ISO 8601
    days_remaining: number; // 0..30
  };
  metadata: { organization_id, user_id: SYSTEM_ACTOR_UUID, timestamp, correlation_id, event_id };
}

​

4. cl_telehealth_session_safety_completed

{
  event: 'cl_telehealth_session_safety_completed';
  publisher: 'CL';
  payload: {
    session_id: string;
    organization_id: string;
    chart_id: string;
    pm_telehealth_session_id: string | null; // null if CL-24 session is not yet linked to a PM-13 session
    modality: 'synchronous_video' | 'synchronous_audio_only' | 'asynchronous' | 'remote_monitoring';
  };
  metadata: { organization_id, user_id, timestamp, correlation_id, event_id };
}

​

Consumed events (2)

​

clinical_note_finalized (CL-04 → CL-24)

​

telehealth_session_completed (PM-13 → CL-24)

​

Helper function contract

cl_telehealth_consent_is_valid(p_chart_id UUID, p_type TEXT, p_as_of TIMESTAMPTZ DEFAULT now())
  RETURNS BOOLEAN
  LANGUAGE sql STABLE SECURITY DEFINER
  SET search_path = public, pg_catalog

• Type values: 'telehealth_general' | 'audio_only'. Anything else returns false.
• Time semantics: expires_at is a strict greater-than against p_as_of — a consent that expires at exactly p_as_of is not valid.
• Inheritance: the helper does not model the general→audio inheritance rule. The application layer (useStartTelehealthSession) is responsible for checking telehealth_general first when the session is audio-only.
• Performance: STABLE, uses idx_cl_telehealth_consents_chart_type (partial index WHERE revoked_at IS NULL). Safe to call inline in CHECK contexts or RLS predicates.
• Security: SECURITY DEFINER with hardened search_path. Callers do not need direct SELECT on cl_telehealth_consents.

​

Cron contract

​

RLS contract

​

Error contract

class ConsentRequiredError extends Error {
  code: 'CL24_CONSENT_REQUIRED';
  consent_type: 'telehealth_general' | 'audio_only';
  chart_id: string;
}

class SafetyChecklistRequiredError extends Error {
  code: 'CL24_SAFETY_CHECKLIST_REQUIRED';
  session_id: string;
  missing_fields: Array<
    'patient_current_location_verified' |
    'disconnect_protocol_acknowledged' |
    'local_emergency_number'
  >;
}

• When the corresponding block flag is false, the orchestrator emits a structured warning toast (cl24.warn.consent / cl24.warn.safety) but does not throw.
• All other failure modes (network, RLS denial, database constraint violation) surface as their native Supabase error types and are not wrapped.

​

Permission keys

​

Platform integration layer

• TelehealthConsentBadge — visual badge for chart sidebar and PM-13 appointment form.
• useTelehealthConsentValidity(chartId, type) — read-only validity check.
• useTelehealthDocumentationEnabled(orgId) — feature-flag read.
• useTelehealthSessionsByPmIds(pmSessionIds) — bulk lookup for PM-13 session-list join.
• useChartIdForPatient(patientId) — helper used by the badge mount in PM-13.

​

Test contract

• RLS tests (8 + 2 trigger): cross-tenant isolation on both tables; revocation-immutability trigger; safety-checklist CHECK constraint.
• Unit tests: date-math edges on cl_telehealth_consent_is_valid; safety completion predicate; jurisdiction-mismatch predicate; connectivity-issues append.
• Integration tests: start-session block-vs-warn matrix; cron idempotency within 24h window; clinical_note_finalized backfill of progress_note_id.
• E2E (Playwright): 6 curated user paths — capture consent, revoke consent, complete safety checklist, log connectivity issue, jurisdiction mismatch banner, link progress note.

​

References

• CL-24 spec
• CL-24 user guide
• CL-24 admin guide
• CL-PM Telehealth contract
• CL-FW Event Automation contract (system-actor UUID)
• EVENT_CONTRACTS.md
• REGULATORY_COMPLIANCE_TRACKER.md