ADR-024: @/platform/workflow Execution Seam (IG-06)

Shipped (2026-06): the seam is live — @/platform/workflow exposes enqueueWorkflowExecution/getThrottleStatus (src/platform/workflow/execution.ts) over the fw-enqueue-execution edge function, with the useWorkflowEnqueue hook for component use.

​

Context

​

Current state (file:line evidence)

• @/platform/workflow is diagram-only. src/platform/workflow/index.ts:1-42 exports SwimLaneCanvas, WorkflowCanvas, diagram version/presence/broadcast hooks and BPMN utils — no execution API. src/platform/workflow/types.ts is entirely swim-lane/canvas types; there is no execution request/result type.
• FW’s real execution path is pgmq-based. The durable worker supabase/functions/workflow-executor-worker/index.ts reads workflow_execution_queue via pgmq_read (line ~568), processes batches under a per-org semaphore on fw_module_settings (lines ~110-150), and on permanent failure routes to workflow_dlq via pgmq_send. The canonical enqueue primitive is INSERT INTO fw_workflow_executions (… status: 'queued' …) followed by supabase.rpc('pgmq_send', { queue_name: 'workflow_execution_queue', msg: { execution_id, rule_id, trigger_type, organization_id, attempt } }) — see the recovery-workflow path at supabase/functions/workflow-executor-worker/index.ts:490-519 for the exact shape.
• App-side cores never touch pgmq directly today — they invoke an edge function (e.g. automation-executor, cl-loc-assessment-get) and let the function own the insert+enqueue. The cross-core service style to mirror is src/platform/clinical/loc/getLocAssessmentForUM.ts — a thin async function that supabase.functions.invoke(...)s an org/consent-gated edge function and returns a typed result.
• FW-53 throttle is live. fw_rate_limit_configs / fw_execution_rate_counters (types: src/cores/fw/types/rate-limiting.ts) back a per-org / per-workflow rate state; the read hook is src/cores/fw/hooks/useExecutionRateSnapshot.ts. The worker rate-limit enforcement (B3) defers/holds over-limit work rather than dropping it (conflict_resolution: 'skip' | 'delay' | 'error' in supabase/functions/_shared/fw-schedule-dispatch.ts:22). A cross-core caller needs to see that hold state before/while enqueuing.
• FW-58 KPI snapshots live in fw_kpi_snapshots (src/cores/fw/hooks/useKpiSnapshots.ts).

​

The boundary constraint

​

Decision

​

Proposed API (@/platform/workflow)

// --- enqueue -------------------------------------------------------------
export interface EnqueueWorkflowExecutionInput {
  /** FW workflow template/rule key (e.g. 'hr-leave-request-approval'). Resolved to a rule_id server-side, per org. */
  workflowKey: string;
  /** Tenant scope. Verified server-side via pf_has_org_access; never trusted from the client. */
  organizationId: string;
  /** Trigger discriminator stored on the execution + queue msg. */
  triggerType: 'event' | 'manual' | 'scheduled' | 'api';
  /** Non-PHI trigger payload merged into fw_workflow_executions.trigger_payload. */
  triggerPayload?: Record<string, unknown>;
  /** Dedupe key. Re-enqueues with the same key for the same org return the existing execution (no duplicate row/msg). */
  idempotencyKey: string;
  /** Optional caller correlation id for tracing across cores. */
  correlationId?: string;
}

export interface EnqueueWorkflowExecutionResult {
  executionId: string;
  /** 'queued' on first enqueue; 'deduplicated' when idempotencyKey already mapped; 'throttled' when accepted-but-held by FW-53. */
  status: 'queued' | 'deduplicated' | 'throttled';
  /** Present when status==='throttled': when FW expects to release the hold. */
  retryAfter?: string; // ISO-8601
  correlationId: string;
}

export function enqueueWorkflowExecution(
  input: EnqueueWorkflowExecutionInput,
): Promise<EnqueueWorkflowExecutionResult>;

// --- throttle (FW-53) ----------------------------------------------------
export interface ThrottleStatus {
  organizationId: string;
  workflowKey?: string;
  /** True when a relevant FW-53 limit is currently holding/deferring executions. */
  isThrottled: boolean;
  /** 'ok' | 'held' (deferred, will run later) | 'rejected' (over a hard cap). */
  state: 'ok' | 'held' | 'rejected';
  /** Per-limit detail surfaced from fw_execution_rate_counters / fw_rate_limit_configs. */
  limits: Array<{
    limitType: 'max_concurrent' | 'max_per_minute' | 'max_per_hour' | 'max_cascade_depth';
    current: number;
    limit: number;
    windowResetAt?: string; // ISO-8601
  }>;
}

export function getThrottleStatus(args: {
  organizationId: string;
  workflowKey?: string;
}): Promise<ThrottleStatus>;

// --- KPI (FW-58) ---------------------------------------------------------
export interface KpiSnapshot {
  organizationId: string;
  workflowKey?: string;
  capturedAt: string; // ISO-8601
  metrics: {
    queuedCount: number;
    runningCount: number;
    completedCount: number;
    failedCount: number;
    p50DurationMs?: number;
    p95DurationMs?: number;
  };
}

/** Realtime subscription; returns an unsubscribe handle. Backed by a TanStack-Query/Realtime hook in the consumer. */
export function subscribeKpiSnapshot(
  args: { organizationId: string; workflowKey?: string },
  onSnapshot: (snapshot: KpiSnapshot) => void,
): () => void;

• enqueueWorkflowExecution / getThrottleStatus ship as plain async services (callable from mutations, schedulers, or React) — the getLocAssessmentForUM pattern.
• A thin useWorkflowEnqueue() mutation hook and useWorkflowThrottleStatus() / useWorkflowKpiSnapshot() query hooks wrap them for component use (the useExecutionRateSnapshot / useKpiSnapshots pattern), reusing useOrganization() for the default org and sanitizeErrorMessage for errors.

​

Tenant + auth scoping

• organizationId is always re-verified server-side in the edge function via pf_has_org_access; client-supplied org is never trusted (security rule + §1).
• Caller must hold a workflow-execute permission for the org (new fw.workflows.execute_cross_core permission, checked in the edge fn). Read surfaces (getThrottleStatus, subscribeKpiSnapshot) are RLS-scoped reads of fw_execution_rate_counters / fw_kpi_snapshots — no new write capability.
• No PHI in triggerPayload, workflowKey, or correlationId (security rule); the edge fn rejects payloads exceeding a size cap and logs only IDs.

​

Idempotency

​

Failure modes & backpressure

​

How HR/FA/RH consume it

// HR-03 onboarding (src/cores/hr/...), no FW import:
import { enqueueWorkflowExecution, getThrottleStatus } from '@/platform/workflow';

const { isThrottled } = await getThrottleStatus({ organizationId, workflowKey: 'hr-employee-onboarding' });
const res = await enqueueWorkflowExecution({
  workflowKey: 'hr-employee-onboarding',
  organizationId,
  triggerType: 'event',
  triggerPayload: { employeeId, startDate },          // non-PHI ids only
  idempotencyKey: `hr_employee_hired:${employeeId}`,
});
// res.status: 'queued' | 'deduplicated' | 'throttled'

​

Phased implementation plan

• Phase 0 — this ADR (planning). No code. ~done.
• Phase 1 — MVP (enqueueWorkflowExecution + getThrottleStatus). New fw-enqueue-execution edge fn (insert+pgmq_send+idempotency+pf_has_org_access); migration adding idempotency_key + unique index + fw.workflows.execute_cross_core permission; the two async services + a useWorkflowEnqueue hook in src/platform/workflow/; RLS + integration tests; wire one template end-to-end (hr-employee-onboarding) as proof. Est. 3–4 days.
• Phase 2 — KPI subscription + remaining read surface. subscribeKpiSnapshot over Supabase Realtime on fw_kpi_snapshots; query hooks; docs. Est. 1–2 days.
• Phase 3 — roll out the 19 templates across HR/FA/RH, flipping each integration guide to Implemented. Est. 1–2 days per core (template-config heavy, not seam work).

​

Open questions (for human decision)

1. workflowKey → rule_id resolution. Per-org registry table (fw_workflow_template_registry) vs. convention on fw_automation_rules.template_key? Affects whether each org must “install” a template before cross-core enqueue works.
2. Throttled = accepted-or-rejected? Should enqueueWorkflowExecution always persist the row on FW-53 hold (return 'throttled', drain later) or hard-fail so the caller owns retry? MVP assumes accept-and-hold; confirm this is the desired backpressure contract.
3. Permission model. New fw.workflows.execute_cross_core, or reuse an existing FW-03 automation-trigger permission? Does an HR user enqueueing an FW workflow need an FW grant, or is the cross-core call system-actor on the user’s behalf?
4. Edge fn vs. PF RPC. Wrap via a Deno edge function (matches getLocAssessmentForUM) or a single SECURITY DEFINER Postgres function (fw_enqueue_execution) the seam calls via supabase.rpc? RPC is one less deploy surface but moves pgmq_send into SQL.
5. KPI realtime vs. poll. Is fw_kpi_snapshots updated often enough to justify a Realtime channel, or is a polling query hook (like useKpiSnapshots) sufficient for Phase 2?

​

Consequences

• @/platform/workflow gains a second responsibility (execution) alongside diagrams; index doc should section it clearly.
• FW owns one new edge fn + one additive migration; no change to the worker contract.
• HR/FA/RH stay import-clean (boundary preserved); the 19 templates become buildable.
• New always-on surface is minimal (small typed API; tree-shakeable).

​

References

• ADR-010 Core–PF Dependency Boundary
• ADR-004 CL↔FW Event Patterns
• HR-FW · FA-FW · RH-FW integration contracts
• supabase/functions/workflow-executor-worker/index.ts (pgmq enqueue/dispatch shape)
• src/platform/clinical/loc/getLocAssessmentForUM.ts (cross-core service pattern)
• FW-53 rate limiting (src/cores/fw/types/rate-limiting.ts) · FW-58 KPI (src/cores/fw/hooks/useKpiSnapshots.ts)