autopilot-core-sandbox 0.0.1

package/dist/dist/migrations/20260826150934_facebook_ads_lead_ingestion.sql

@@ -0,0 +1,1711 @@
+-- Meta Lead Ads ingestion: Page/Form configuration, durable webhook receipt,
+-- consent evidence, atomic lead creation, and agent-first call attempts.
+--
+-- Everything in this migration is additive and fail-closed. Lead sync and
+-- auto-dial are disabled for every existing company until a server route
+-- validates and enables the configuration through
+-- set_facebook_ads_lead_settings(). The companion RLS migration keeps every
+-- credential, PII, evidence, and queue table service-role only.
+
+-- ============================================================
+-- Shared normalized-array checks
+-- ============================================================
+
+create or replace function "public"."facebook_ads_text_array_is_normalized"(
+    "p_values" text[]
+)
+returns boolean
+language sql
+immutable
+parallel safe
+set search_path = ''
+as $$
+    select case
+        when cardinality("p_values") = 0 then true
+        when coalesce(array_ndims("p_values"), 0) <> 1 then false
+        when exists (
+            select 1
+            from unnest("p_values") as "item"("value")
+            where "item"."value" is null
+               or nullif(btrim("item"."value"), '') is null
+        ) then false
+        else "p_values" = array(
+            select distinct "item"."value"
+            from unnest("p_values") as "item"("value")
+            order by "item"."value"
+        )
+    end;
+$$;
+
+alter function "public"."facebook_ads_text_array_is_normalized"(text[])
+owner to "postgres";
+
+create or replace function "public"."facebook_ads_call_days_are_normalized"(
+    "p_days" smallint[]
+)
+returns boolean
+language sql
+immutable
+parallel safe
+set search_path = ''
+as $$
+    select case
+        when cardinality("p_days") = 0 then false
+        when coalesce(array_ndims("p_days"), 0) <> 1 then false
+        when exists (
+            select 1
+            from unnest("p_days") as "day_row"("value")
+            where "day_row"."value" is null
+               or "day_row"."value" not between 1 and 7
+        ) then false
+        else "p_days" = array(
+            select distinct "day_row"."value"
+            from unnest("p_days") as "day_row"("value")
+            order by "day_row"."value"
+        )::smallint[]
+    end;
+$$;
+
+alter function "public"."facebook_ads_call_days_are_normalized"(smallint[])
+owner to "postgres";
+
+-- ============================================================
+-- Existing-table additions
+-- ============================================================
+
+alter table "public"."client"
+    add column if not exists "is_do_not_marketing_email" boolean
+    default false not null;
+
+alter table "public"."facebook_ads_connection"
+    add column if not exists "granted_scopes" text[]
+    default '{}'::text[] not null;
+
+alter table "public"."facebook_ads_connection"
+    add constraint "facebook_ads_connection_granted_scopes_check"
+    check (
+        "public"."facebook_ads_text_array_is_normalized"("granted_scopes")
+    );
+
+alter table "public"."settings_facebook_ads"
+    add column if not exists "lead_sync_enabled" boolean default false not null,
+    add column if not exists "lead_tag_id" uuid,
+    add column if not exists "lead_sms_rule_id" uuid,
+    add column if not exists "lead_email_rule_id" uuid,
+    -- The customer attests that the company service timezone governs calling
+    -- every lead delivered by its selected Meta Forms. This is deliberately
+    -- separate from enabling the feature so the legal assumption is explicit.
+    add column if not exists "lead_auto_dial_timezone_attested" boolean
+        default false not null,
+    add column if not exists "lead_auto_dial_enabled" boolean default false not null,
+    add column if not exists "lead_auto_dial_phone_number_id" uuid,
+    add column if not exists "lead_auto_dial_user_id" uuid,
+    add column if not exists "lead_auto_dial_delay_seconds" integer default 0 not null,
+    add column if not exists "lead_auto_dial_window_start" time without time zone
+        default '08:00:00'::time without time zone not null,
+    add column if not exists "lead_auto_dial_window_end" time without time zone
+        default '20:00:00'::time without time zone not null,
+    -- ISO weekdays: Monday=1 through Sunday=7.
+    add column if not exists "lead_auto_dial_window_days" smallint[]
+        default array[1, 2, 3, 4, 5, 6, 7]::smallint[] not null;
+
+alter table "public"."settings_facebook_ads"
+    add constraint "settings_facebook_ads_lead_tag_id_fkey"
+        foreign key ("lead_tag_id") references "public"."client_tag"("id")
+        on delete set null,
+    add constraint "settings_facebook_ads_lead_sms_rule_id_fkey"
+        foreign key ("lead_sms_rule_id") references "public"."automation_rule"("id")
+        on delete set null,
+    add constraint "settings_facebook_ads_lead_email_rule_id_fkey"
+        foreign key ("lead_email_rule_id") references "public"."automation_rule"("id")
+        on delete set null,
+    add constraint "settings_facebook_ads_lead_auto_dial_phone_number_id_fkey"
+        foreign key ("lead_auto_dial_phone_number_id")
+        references "public"."phone_number"("id") on delete set null,
+    add constraint "settings_facebook_ads_lead_auto_dial_user_id_fkey"
+        foreign key ("lead_auto_dial_user_id") references "public"."user"("id")
+        on delete set null,
+    add constraint "settings_facebook_ads_lead_sync_source_check"
+        check (not "lead_sync_enabled" or "source_id" is not null),
+    add constraint "settings_facebook_ads_lead_rule_distinct_check"
+        check (
+            "lead_sms_rule_id" is null
+            or "lead_email_rule_id" is null
+            or "lead_sms_rule_id" <> "lead_email_rule_id"
+        ),
+    add constraint "settings_facebook_ads_lead_auto_dial_config_check"
+        check (
+            not "lead_auto_dial_enabled"
+            or (
+                "lead_auto_dial_timezone_attested"
+                and
+                "lead_auto_dial_phone_number_id" is not null
+                and "lead_auto_dial_user_id" is not null
+            )
+        ),
+    add constraint "settings_facebook_ads_lead_auto_dial_delay_check"
+        check ("lead_auto_dial_delay_seconds" between 0 and 86400),
+    add constraint "settings_facebook_ads_lead_auto_dial_window_check"
+        check ("lead_auto_dial_window_start" < "lead_auto_dial_window_end"),
+    add constraint "settings_facebook_ads_lead_auto_dial_days_check"
+        check (
+            "public"."facebook_ads_call_days_are_normalized"(
+                "lead_auto_dial_window_days"
+            )
+        );
+
+-- Facebook lead response rules are selected explicitly in settings rather
+-- than discovered from every company-wide lead_created rule. Snapshot that
+-- selection on the automation event created by the existing client trigger:
+-- downstream fanout can then require both provenance and rule-id inclusion.
+-- The non-Facebook branch deliberately preserves the old INSERT shape, so its
+-- payload remains the automation_event default '{}'::jsonb.
+create or replace function "public"."capture_automation_lead_created"()
+returns trigger
+language plpgsql
+security definer
+set search_path = ''
+as $$
+declare
+    "v_rule_ids" jsonb;
+begin
+    if new."created_via" = 'facebook_lead_ads' then
+        select to_jsonb(array_remove(array[
+            "settings"."lead_sms_rule_id",
+            "settings"."lead_email_rule_id"
+        ], null::uuid))
+        into "v_rule_ids"
+        from "public"."settings_facebook_ads" as "settings"
+        where "settings"."company_id" = new."company_id";
+
+        insert into "public"."automation_event" (
+            "company_id", "event_type", "client_id", "payload"
+        ) values (
+            new."company_id",
+            'lead_created',
+            new."id",
+            jsonb_build_object(
+                'created_via', 'facebook_lead_ads',
+                'rule_ids', coalesce("v_rule_ids", '[]'::jsonb)
+            )
+        );
+    else
+        insert into "public"."automation_event" (
+            "company_id", "event_type", "client_id"
+        ) values (new."company_id", 'lead_created', new."id");
+    end if;
+
+    return null;
+end;
+$$;
+
+alter function "public"."capture_automation_lead_created"()
+owner to "postgres";
+
+-- ============================================================
+-- Page and Form configuration
+-- ============================================================
+
+create table if not exists "public"."facebook_ads_lead_page" (
+    "id" uuid default gen_random_uuid() not null,
+    "created_at" timestamp with time zone default now() not null,
+    "updated_at" timestamp with time zone default now() not null,
+    "company_id" uuid not null,
+    "connection_id" uuid not null,
+    "meta_page_id" text not null,
+    "page_name" text not null,
+    -- Ciphertext produced by autopilot-web's Facebook token encryption.
+    "encrypted_page_access_token" text not null,
+    "token_expires_at" timestamp with time zone,
+    "is_enabled" boolean default false not null,
+    "subscription_status" text default 'pending' not null,
+    "subscribed_at" timestamp with time zone,
+    "last_subscription_attempt_at" timestamp with time zone,
+    "last_subscription_error" text,
+    -- selected is fail-closed: no Form is accepted until explicitly saved.
+    "form_selection_mode" text default 'selected' not null,
+    constraint "facebook_ads_lead_page_pkey" primary key ("id"),
+    constraint "facebook_ads_lead_page_company_id_id_key"
+        unique ("company_id", "id"),
+    constraint "facebook_ads_lead_page_meta_page_id_key" unique ("meta_page_id"),
+    constraint "facebook_ads_lead_page_company_id_fkey"
+        foreign key ("company_id") references "public"."company"("id")
+        on delete cascade,
+    constraint "facebook_ads_lead_page_company_connection_fkey"
+        foreign key ("company_id", "connection_id")
+        references "public"."facebook_ads_connection"("company_id", "id")
+        on delete cascade,
+    constraint "facebook_ads_lead_page_meta_page_id_check"
+        check ("meta_page_id" ~ '^[0-9]+$'),
+    constraint "facebook_ads_lead_page_page_name_check"
+        check (nullif(btrim("page_name"), '') is not null),
+    constraint "facebook_ads_lead_page_token_check"
+        check (nullif(btrim("encrypted_page_access_token"), '') is not null),
+    constraint "facebook_ads_lead_page_subscription_status_check"
+        check (
+            "subscription_status" in (
+                'pending', 'subscribed', 'error', 'disconnected'
+            )
+        ),
+    constraint "facebook_ads_lead_page_form_selection_mode_check"
+        check ("form_selection_mode" in ('all', 'selected')),
+    constraint "facebook_ads_lead_page_enabled_subscription_check"
+        check (not "is_enabled" or "subscription_status" = 'subscribed')
+);
+
+alter table "public"."facebook_ads_lead_page" owner to "postgres";
+
+create index if not exists "facebook_ads_lead_page_company_enabled_idx"
+    on "public"."facebook_ads_lead_page" ("company_id", "is_enabled");
+
+create table if not exists "public"."facebook_ads_lead_form" (
+    "id" uuid default gen_random_uuid() not null,
+    "created_at" timestamp with time zone default now() not null,
+    "updated_at" timestamp with time zone default now() not null,
+    "company_id" uuid not null,
+    "page_id" uuid not null,
+    "meta_form_id" text not null,
+    "form_name" text not null,
+    "is_enabled" boolean default false not null,
+    -- Successful reconciliation advances this cursor. Workers overlap their
+    -- next Graph scan slightly so delayed Meta writes are still observed.
+    "last_reconciled_at" timestamp with time zone,
+    -- Maps Meta field names to first_name/last_name/email/phone. The exact
+    -- JSON shape is validated by the server-safe module added with this PR.
+    "field_mapping" jsonb default '{}'::jsonb not null,
+    -- A company must explicitly attest each channel and save the disclosure
+    -- shown on the Meta Form. A missing attestation/disclosure can never be
+    -- normalized to granted consent during finalization.
+    "sms_consent_attested" boolean default false not null,
+    "sms_consent_disclosure" text,
+    "email_consent_attested" boolean default false not null,
+    "email_consent_disclosure" text,
+    "voice_consent_attested" boolean default false not null,
+    "voice_consent_disclosure" text,
+    constraint "facebook_ads_lead_form_pkey" primary key ("id"),
+    constraint "facebook_ads_lead_form_company_id_id_key"
+        unique ("company_id", "id"),
+    constraint "facebook_ads_lead_form_page_form_key"
+        unique ("page_id", "meta_form_id"),
+    constraint "facebook_ads_lead_form_company_id_fkey"
+        foreign key ("company_id") references "public"."company"("id")
+        on delete cascade,
+    constraint "facebook_ads_lead_form_company_page_fkey"
+        foreign key ("company_id", "page_id")
+        references "public"."facebook_ads_lead_page"("company_id", "id")
+        on delete cascade,
+    constraint "facebook_ads_lead_form_meta_form_id_check"
+        check ("meta_form_id" ~ '^[0-9]+$'),
+    constraint "facebook_ads_lead_form_name_check"
+        check (nullif(btrim("form_name"), '') is not null),
+    constraint "facebook_ads_lead_form_field_mapping_check"
+        check (jsonb_typeof("field_mapping") = 'object'),
+    constraint "facebook_ads_lead_form_sms_consent_check"
+        check (
+            not "sms_consent_attested"
+            or nullif(btrim("sms_consent_disclosure"), '') is not null
+        ),
+    constraint "facebook_ads_lead_form_email_consent_check"
+        check (
+            not "email_consent_attested"
+            or nullif(btrim("email_consent_disclosure"), '') is not null
+        ),
+    constraint "facebook_ads_lead_form_voice_consent_check"
+        check (
+            not "voice_consent_attested"
+            or nullif(btrim("voice_consent_disclosure"), '') is not null
+        )
+);
+
+alter table "public"."facebook_ads_lead_form" owner to "postgres";
+
+create index if not exists "facebook_ads_lead_form_company_page_enabled_idx"
+    on "public"."facebook_ads_lead_form" (
+        "company_id", "page_id", "is_enabled"
+    );
+
+create or replace trigger "set_facebook_ads_lead_page_updated_at_trigger"
+before update on "public"."facebook_ads_lead_page"
+for each row execute function "public"."set_facebook_ads_updated_at"();
+
+create or replace trigger "set_facebook_ads_lead_form_updated_at_trigger"
+before update on "public"."facebook_ads_lead_form"
+for each row execute function "public"."set_facebook_ads_updated_at"();
+
+-- ============================================================
+-- Durable receipt and consent evidence
+-- ============================================================
+
+create table if not exists "public"."facebook_ads_lead_event" (
+    "id" uuid default gen_random_uuid() not null,
+    "created_at" timestamp with time zone default now() not null,
+    "updated_at" timestamp with time zone default now() not null,
+    "company_id" uuid not null,
+    -- Nullable specifically so disconnecting a Page can erase its token and
+    -- configuration without erasing historical submission/consent evidence.
+    "page_id" uuid,
+    "meta_page_id" text not null,
+    "meta_leadgen_id" text not null,
+    "meta_form_id" text not null,
+    "meta_created_at" timestamp with time zone not null,
+    "meta_ad_id" text,
+    "meta_adset_id" text,
+    "meta_campaign_id" text,
+    "source_id" uuid,
+    "client_id" uuid,
+    "webhook_payload" jsonb not null,
+    "lead_payload" jsonb,
+    -- Immutable snapshot of mapping + channel attestations/disclosures at
+    -- receipt time. Form/Page deletion cannot destroy compliance evidence.
+    "form_configuration_snapshot" jsonb default '{}'::jsonb not null,
+    "status" text default 'pending' not null,
+    "skip_reason" text,
+    "received_count" integer default 1 not null,
+    "replay_count" integer default 0 not null,
+    "last_received_at" timestamp with time zone default now() not null,
+    "attempt_count" integer default 0 not null,
+    "next_attempt_at" timestamp with time zone default now() not null,
+    "last_attempt_at" timestamp with time zone,
+    "fetched_at" timestamp with time zone,
+    "processed_at" timestamp with time zone,
+    "last_error" text,
+    constraint "facebook_ads_lead_event_pkey" primary key ("id"),
+    constraint "facebook_ads_lead_event_company_id_id_key"
+        unique ("company_id", "id"),
+    constraint "facebook_ads_lead_event_meta_submission_key"
+        unique ("meta_page_id", "meta_leadgen_id"),
+    constraint "facebook_ads_lead_event_company_id_fkey"
+        foreign key ("company_id") references "public"."company"("id")
+        on delete cascade,
+    constraint "facebook_ads_lead_event_company_page_fkey"
+        foreign key ("company_id", "page_id")
+        references "public"."facebook_ads_lead_page"("company_id", "id")
+        on delete set null ("page_id"),
+    constraint "facebook_ads_lead_event_source_id_fkey"
+        foreign key ("source_id") references "public"."job_source"("id")
+        on delete set null,
+    constraint "facebook_ads_lead_event_client_id_fkey"
+        foreign key ("client_id") references "public"."client"("id")
+        on delete set null,
+    constraint "facebook_ads_lead_event_meta_page_id_check"
+        check ("meta_page_id" ~ '^[0-9]+$'),
+    constraint "facebook_ads_lead_event_meta_leadgen_id_check"
+        check ("meta_leadgen_id" ~ '^[0-9]+$'),
+    constraint "facebook_ads_lead_event_meta_form_id_check"
+        check ("meta_form_id" ~ '^[0-9]+$'),
+    constraint "facebook_ads_lead_event_meta_ad_id_check"
+        check ("meta_ad_id" is null or "meta_ad_id" ~ '^[0-9]+$'),
+    constraint "facebook_ads_lead_event_meta_adset_id_check"
+        check ("meta_adset_id" is null or "meta_adset_id" ~ '^[0-9]+$'),
+    constraint "facebook_ads_lead_event_meta_campaign_id_check"
+        check ("meta_campaign_id" is null or "meta_campaign_id" ~ '^[0-9]+$'),
+    constraint "facebook_ads_lead_event_webhook_payload_check"
+        check (jsonb_typeof("webhook_payload") = 'object'),
+    constraint "facebook_ads_lead_event_lead_payload_check"
+        check ("lead_payload" is null or jsonb_typeof("lead_payload") = 'object'),
+    constraint "facebook_ads_lead_event_form_snapshot_check"
+        check (jsonb_typeof("form_configuration_snapshot") = 'object'),
+    constraint "facebook_ads_lead_event_status_check"
+        check ("status" in ('pending', 'processing', 'processed', 'skipped', 'dead')),
+    constraint "facebook_ads_lead_event_received_count_check"
+        check ("received_count" > 0),
+    constraint "facebook_ads_lead_event_replay_count_check"
+        check ("replay_count" >= 0),
+    constraint "facebook_ads_lead_event_attempt_count_check"
+        check ("attempt_count" >= 0),
+    constraint "facebook_ads_lead_event_processed_at_check"
+        check ("status" <> 'processed' or "processed_at" is not null)
+);
+
+alter table "public"."facebook_ads_lead_event" owner to "postgres";
+
+create index if not exists "facebook_ads_lead_event_due_idx"
+    on "public"."facebook_ads_lead_event" ("next_attempt_at", "created_at")
+    where "status" = 'pending';
+
+create index if not exists "facebook_ads_lead_event_company_history_idx"
+    on "public"."facebook_ads_lead_event" ("company_id", "created_at" desc);
+
+create index if not exists "facebook_ads_lead_event_client_idx"
+    on "public"."facebook_ads_lead_event" ("client_id")
+    where "client_id" is not null;
+
+create table if not exists "public"."facebook_ads_lead_consent" (
+    "id" uuid default gen_random_uuid() not null,
+    "created_at" timestamp with time zone default now() not null,
+    "company_id" uuid not null,
+    "lead_event_id" uuid not null,
+    "channel" text not null,
+    "status" text default 'unknown' not null,
+    "captured_at" timestamp with time zone,
+    "disclosure_text" text,
+    "response_value" text,
+    "evidence" jsonb default '{}'::jsonb not null,
+    constraint "facebook_ads_lead_consent_pkey" primary key ("id"),
+    constraint "facebook_ads_lead_consent_company_id_id_key"
+        unique ("company_id", "id"),
+    constraint "facebook_ads_lead_consent_event_channel_key"
+        unique ("lead_event_id", "channel"),
+    constraint "facebook_ads_lead_consent_company_id_fkey"
+        foreign key ("company_id") references "public"."company"("id")
+        on delete cascade,
+    constraint "facebook_ads_lead_consent_company_event_fkey"
+        foreign key ("company_id", "lead_event_id")
+        references "public"."facebook_ads_lead_event"("company_id", "id")
+        on delete cascade,
+    constraint "facebook_ads_lead_consent_channel_check"
+        check ("channel" in ('email', 'sms', 'voice')),
+    constraint "facebook_ads_lead_consent_status_check"
+        check ("status" in ('granted', 'denied', 'unknown')),
+    constraint "facebook_ads_lead_consent_evidence_check"
+        check (jsonb_typeof("evidence") = 'object'),
+    constraint "facebook_ads_lead_consent_granted_evidence_check"
+        check (
+            "status" <> 'granted'
+            or (
+                "captured_at" is not null
+                and nullif(btrim("disclosure_text"), '') is not null
+            )
+        )
+);
+
+alter table "public"."facebook_ads_lead_consent" owner to "postgres";
+
+create index if not exists "facebook_ads_lead_consent_company_event_idx"
+    on "public"."facebook_ads_lead_consent" ("company_id", "lead_event_id");
+
+-- ============================================================
+-- Agent-first auto-dial queue
+-- ============================================================
+
+create table if not exists "public"."facebook_ads_lead_call_attempt" (
+    "id" uuid default gen_random_uuid() not null,
+    "created_at" timestamp with time zone default now() not null,
+    "updated_at" timestamp with time zone default now() not null,
+    "company_id" uuid not null,
+    "lead_event_id" uuid not null,
+    "client_id" uuid,
+    "consent_id" uuid not null,
+    "from_phone_number_id" uuid,
+    "target_user_id" uuid,
+    "answered_by_user_id" uuid,
+    -- Immutable snapshots keep the audit useful after a number/user changes.
+    "from_phone_number" text not null,
+    "destination_phone_number" text not null,
+    "routing_snapshot" jsonb default '{}'::jsonb not null,
+    "status" text default 'pending' not null,
+    -- quiet-hours/business-window holds return a claimed row to pending with
+    -- a future next_attempt_at; workers never need a direct table update.
+    "held_reason" text,
+    "attempt_count" integer default 0 not null,
+    "next_attempt_at" timestamp with time zone default now() not null,
+    "last_attempt_at" timestamp with time zone,
+    "twilio_agent_call_sid" text,
+    "twilio_lead_call_sid" text,
+    "twilio_conference_sid" text,
+    "started_at" timestamp with time zone,
+    "connected_at" timestamp with time zone,
+    "completed_at" timestamp with time zone,
+    "skip_reason" text,
+    "last_error" text,
+    constraint "facebook_ads_lead_call_attempt_pkey" primary key ("id"),
+    constraint "facebook_ads_lead_call_attempt_company_id_id_key"
+        unique ("company_id", "id"),
+    constraint "facebook_ads_lead_call_attempt_lead_event_id_key"
+        unique ("lead_event_id"),
+    constraint "facebook_ads_lead_call_attempt_company_id_fkey"
+        foreign key ("company_id") references "public"."company"("id")
+        on delete cascade,
+    constraint "facebook_ads_lead_call_attempt_company_event_fkey"
+        foreign key ("company_id", "lead_event_id")
+        references "public"."facebook_ads_lead_event"("company_id", "id")
+        on delete cascade,
+    constraint "facebook_ads_lead_call_attempt_client_id_fkey"
+        foreign key ("client_id") references "public"."client"("id")
+        on delete set null,
+    constraint "facebook_ads_lead_call_attempt_company_consent_fkey"
+        foreign key ("company_id", "consent_id")
+        references "public"."facebook_ads_lead_consent"("company_id", "id")
+        on delete cascade,
+    constraint "facebook_ads_lead_call_attempt_from_phone_number_id_fkey"
+        foreign key ("from_phone_number_id")
+        references "public"."phone_number"("id") on delete set null,
+    constraint "facebook_ads_lead_call_attempt_target_user_id_fkey"
+        foreign key ("target_user_id") references "public"."user"("id")
+        on delete set null,
+    constraint "facebook_ads_lead_call_attempt_answered_by_user_id_fkey"
+        foreign key ("answered_by_user_id") references "public"."user"("id")
+        on delete set null,
+    constraint "facebook_ads_lead_call_attempt_status_check"
+        check (
+            "status" in (
+                'pending', 'processing', 'agent_ringing', 'lead_ringing',
+                'connected', 'completed', 'skipped', 'failed', 'dead'
+            )
+        ),
+    constraint "facebook_ads_lead_call_attempt_count_check"
+        check ("attempt_count" >= 0),
+    constraint "facebook_ads_lead_call_attempt_from_phone_check"
+        check (nullif(btrim("from_phone_number"), '') is not null),
+    constraint "facebook_ads_lead_call_attempt_destination_phone_check"
+        check (nullif(btrim("destination_phone_number"), '') is not null),
+    constraint "facebook_ads_lead_call_attempt_routing_snapshot_check"
+        check (jsonb_typeof("routing_snapshot") = 'object')
+);
+
+alter table "public"."facebook_ads_lead_call_attempt" owner to "postgres";
+
+create index if not exists "facebook_ads_lead_call_attempt_due_idx"
+    on "public"."facebook_ads_lead_call_attempt" (
+        "next_attempt_at", "created_at"
+    ) where "status" = 'pending';
+
+create index if not exists "facebook_ads_lead_call_attempt_company_history_idx"
+    on "public"."facebook_ads_lead_call_attempt" (
+        "company_id", "created_at" desc
+    );
+
+create unique index if not exists "facebook_ads_lead_call_attempt_agent_sid_key"
+    on "public"."facebook_ads_lead_call_attempt" ("twilio_agent_call_sid")
+    where "twilio_agent_call_sid" is not null;
+
+create unique index if not exists "facebook_ads_lead_call_attempt_lead_sid_key"
+    on "public"."facebook_ads_lead_call_attempt" ("twilio_lead_call_sid")
+    where "twilio_lead_call_sid" is not null;
+
+create unique index if not exists "facebook_ads_lead_call_attempt_conference_sid_key"
+    on "public"."facebook_ads_lead_call_attempt" ("twilio_conference_sid")
+    where "twilio_conference_sid" is not null;
+
+create or replace trigger "set_facebook_ads_lead_event_updated_at_trigger"
+before update on "public"."facebook_ads_lead_event"
+for each row execute function "public"."set_facebook_ads_updated_at"();
+
+create or replace trigger "set_facebook_ads_lead_call_attempt_updated_at_trigger"
+before update on "public"."facebook_ads_lead_call_attempt"
+for each row execute function "public"."set_facebook_ads_updated_at"();
+
+-- ============================================================
+-- Lead settings RPC
+-- ============================================================
+
+create or replace function "public"."set_facebook_ads_lead_settings"("p" jsonb)
+returns void
+language plpgsql
+security definer
+set search_path = ''
+as $$
+declare
+    "v_company_id" uuid := ("p" ->> 'company_id')::uuid;
+    "v_current" "public"."settings_facebook_ads"%rowtype;
+    "v_sync_enabled" boolean;
+    "v_tag_id" uuid;
+    "v_sms_rule_id" uuid;
+    "v_email_rule_id" uuid;
+    "v_timezone_attested" boolean;
+    "v_auto_dial_enabled" boolean;
+    "v_phone_number_id" uuid;
+    "v_user_id" uuid;
+    "v_delay_seconds" integer;
+    "v_window_start" time without time zone;
+    "v_window_end" time without time zone;
+    "v_window_days" smallint[];
+begin
+    if jsonb_typeof("p") <> 'object' or "v_company_id" is null then
+        raise exception 'company_id and an object payload are required'
+            using errcode = '22023';
+    end if;
+
+    if not exists (
+        select 1 from "public"."company" where "id" = "v_company_id"
+    ) then
+        raise exception 'Company does not exist' using errcode = '23503';
+    end if;
+
+    insert into "public"."settings_facebook_ads" ("company_id")
+    values ("v_company_id")
+    on conflict ("company_id") do nothing;
+
+    select * into "v_current"
+    from "public"."settings_facebook_ads"
+    where "company_id" = "v_company_id"
+    for update;
+
+    "v_sync_enabled" := case when "p" ? 'lead_sync_enabled'
+        then coalesce(("p" ->> 'lead_sync_enabled')::boolean, false)
+        else "v_current"."lead_sync_enabled" end;
+    "v_tag_id" := case when "p" ? 'lead_tag_id'
+        then ("p" ->> 'lead_tag_id')::uuid
+        else "v_current"."lead_tag_id" end;
+    "v_sms_rule_id" := case when "p" ? 'lead_sms_rule_id'
+        then ("p" ->> 'lead_sms_rule_id')::uuid
+        else "v_current"."lead_sms_rule_id" end;
+    "v_email_rule_id" := case when "p" ? 'lead_email_rule_id'
+        then ("p" ->> 'lead_email_rule_id')::uuid
+        else "v_current"."lead_email_rule_id" end;
+    "v_timezone_attested" := case
+        when "p" ? 'lead_auto_dial_timezone_attested'
+            then coalesce(
+                ("p" ->> 'lead_auto_dial_timezone_attested')::boolean,
+                false
+            )
+        else "v_current"."lead_auto_dial_timezone_attested" end;
+    "v_auto_dial_enabled" := case when "p" ? 'lead_auto_dial_enabled'
+        then coalesce(("p" ->> 'lead_auto_dial_enabled')::boolean, false)
+        else "v_current"."lead_auto_dial_enabled" end;
+    "v_phone_number_id" := case when "p" ? 'lead_auto_dial_phone_number_id'
+        then ("p" ->> 'lead_auto_dial_phone_number_id')::uuid
+        else "v_current"."lead_auto_dial_phone_number_id" end;
+    "v_user_id" := case when "p" ? 'lead_auto_dial_user_id'
+        then ("p" ->> 'lead_auto_dial_user_id')::uuid
+        else "v_current"."lead_auto_dial_user_id" end;
+    "v_delay_seconds" := case when "p" ? 'lead_auto_dial_delay_seconds'
+        then coalesce(("p" ->> 'lead_auto_dial_delay_seconds')::integer, 0)
+        else "v_current"."lead_auto_dial_delay_seconds" end;
+    "v_window_start" := case when "p" ? 'lead_auto_dial_window_start'
+        then ("p" ->> 'lead_auto_dial_window_start')::time without time zone
+        else "v_current"."lead_auto_dial_window_start" end;
+    "v_window_end" := case when "p" ? 'lead_auto_dial_window_end'
+        then ("p" ->> 'lead_auto_dial_window_end')::time without time zone
+        else "v_current"."lead_auto_dial_window_end" end;
+
+    if "p" ? 'lead_auto_dial_window_days' then
+        if jsonb_typeof("p" -> 'lead_auto_dial_window_days') <> 'array' then
+            raise exception 'lead_auto_dial_window_days must be an array'
+                using errcode = '22023';
+        end if;
+        select coalesce(
+            array_agg("day_row"."value"::smallint order by "day_row"."value"::smallint),
+            '{}'::smallint[]
+        ) into "v_window_days"
+        from jsonb_array_elements_text(
+            "p" -> 'lead_auto_dial_window_days'
+        ) as "day_row"("value");
+    else
+        "v_window_days" := "v_current"."lead_auto_dial_window_days";
+    end if;
+
+    if "v_sync_enabled" and "v_current"."source_id" is null then
+        raise exception 'A Facebook Ads lead source is required before enabling lead sync'
+            using errcode = '23514';
+    end if;
+
+    if "v_tag_id" is not null and not exists (
+        select 1 from "public"."client_tag"
+        where "id" = "v_tag_id" and "company_id" = "v_company_id"
+    ) then
+        raise exception 'Lead tag does not belong to this company'
+            using errcode = '23503';
+    end if;
+
+    -- Facebook follow-up is marketing by definition. Requiring both trusted
+    -- Facebook provenance and explicit marketing classification prevents a
+    -- generic lead rule from being repurposed and keeps the executor's
+    -- per-channel DNM gates in the path for every selected rule.
+    if "v_sms_rule_id" is not null and not exists (
+        select 1 from "public"."automation_rule"
+        where "id" = "v_sms_rule_id"
+          and "company_id" = "v_company_id"
+          and "trigger_type" = 'lead_created'
+          and "trigger_config" ->> 'created_via' = 'facebook_lead_ads'
+          and "action_type" = 'sms_client'
+          and "action_config" ->> 'communication_type' = 'marketing'
+    ) then
+        raise exception 'SMS rule must be this company''s Facebook lead-created marketing SMS rule'
+            using errcode = '23503';
+    end if;
+
+    if "v_email_rule_id" is not null and not exists (
+        select 1 from "public"."automation_rule"
+        where "id" = "v_email_rule_id"
+          and "company_id" = "v_company_id"
+          and "trigger_type" = 'lead_created'
+          and "trigger_config" ->> 'created_via' = 'facebook_lead_ads'
+          and "action_type" = 'email_client'
+          and "action_config" ->> 'communication_type' = 'marketing'
+    ) then
+        raise exception 'Email rule must be this company''s Facebook lead-created marketing email rule'
+            using errcode = '23503';
+    end if;
+
+    if "v_sms_rule_id" is not null
+       and "v_sms_rule_id" = "v_email_rule_id" then
+        raise exception 'SMS and email rules must be different'
+            using errcode = '23514';
+    end if;
+
+    if "v_delay_seconds" not between 0 and 86400
+       or "v_window_start" is null
+       or "v_window_end" is null
+       or "v_window_start" >= "v_window_end"
+       or not "public"."facebook_ads_call_days_are_normalized"("v_window_days")
+    then
+        raise exception 'Auto-dial delay or call window is invalid'
+            using errcode = '23514';
+    end if;
+
+    if "v_auto_dial_enabled" then
+        if not "v_timezone_attested" then
+            raise exception 'Auto-dial requires company service timezone attestation'
+                using errcode = '23514';
+        end if;
+
+        if "v_phone_number_id" is null or "v_user_id" is null then
+            raise exception 'Auto-dial requires a phone number and user'
+                using errcode = '23514';
+        end if;
+
+        if not exists (
+            select 1 from "public"."phone_number"
+            where "id" = "v_phone_number_id"
+              and "company_id" = "v_company_id"
+              and "twilio" = true
+              and "client_id" is null
+              and "phone_sid" is not null
+        ) then
+            raise exception 'Auto-dial phone number is not an active company Twilio number'
+                using errcode = '23503';
+        end if;
+
+        if not exists (
+            select 1 from "public"."user"
+            where "id" = "v_user_id"
+              and "company_id" = "v_company_id"
+              and "is_current_employee" = true
+        ) then
+            raise exception 'Auto-dial user is not a current company employee'
+                using errcode = '23503';
+        end if;
+
+        if not exists (
+            select 1 from "public"."phone_number_user_link"
+            where "company_id" = "v_company_id"
+              and "phone_number_id" = "v_phone_number_id"
+              and "user_id" = "v_user_id"
+        ) then
+            raise exception 'Auto-dial user is not linked to the selected number'
+                using errcode = '23514';
+        end if;
+    end if;
+
+    update "public"."settings_facebook_ads"
+    set
+        "lead_sync_enabled" = "v_sync_enabled",
+        "lead_tag_id" = "v_tag_id",
+        "lead_sms_rule_id" = "v_sms_rule_id",
+        "lead_email_rule_id" = "v_email_rule_id",
+        "lead_auto_dial_timezone_attested" = "v_timezone_attested",
+        "lead_auto_dial_enabled" = "v_auto_dial_enabled",
+        "lead_auto_dial_phone_number_id" = "v_phone_number_id",
+        "lead_auto_dial_user_id" = "v_user_id",
+        "lead_auto_dial_delay_seconds" = "v_delay_seconds",
+        "lead_auto_dial_window_start" = "v_window_start",
+        "lead_auto_dial_window_end" = "v_window_end",
+        "lead_auto_dial_window_days" = "v_window_days"
+    where "company_id" = "v_company_id";
+end;
+$$;
+
+alter function "public"."set_facebook_ads_lead_settings"(jsonb)
+owner to "postgres";
+
+-- ============================================================
+-- Receipt, claim, replay, and finalization RPCs
+-- ============================================================
+
+create or replace function "public"."enqueue_facebook_ads_lead_event"("p" jsonb)
+returns jsonb
+language plpgsql
+security definer
+set search_path = ''
+as $$
+declare
+    "v_page" "public"."facebook_ads_lead_page"%rowtype;
+    "v_form" "public"."facebook_ads_lead_form"%rowtype;
+    "v_settings" "public"."settings_facebook_ads"%rowtype;
+    "v_form_found" boolean := false;
+    "v_form_selected" boolean := false;
+    "v_accepted" boolean := false;
+    "v_reason" text;
+    "v_snapshot" jsonb := '{}'::jsonb;
+    "v_event_id" uuid;
+    "v_received_count" integer;
+    "v_status" text;
+    "v_return_reason" text;
+    "v_webhook_payload" jsonb := coalesce("p" -> 'webhook_payload', '{}'::jsonb);
+begin
+    if jsonb_typeof("p") <> 'object'
+       or jsonb_typeof("v_webhook_payload") <> 'object'
+       or coalesce("p" ->> 'meta_page_id', '') !~ '^[0-9]+$'
+       or coalesce("p" ->> 'meta_leadgen_id', '') !~ '^[0-9]+$'
+       or coalesce("p" ->> 'meta_form_id', '') !~ '^[0-9]+$'
+       or "p" ->> 'meta_created_at' is null
+    then
+        raise exception 'Valid Meta Page, lead, Form, created time, and payload are required'
+            using errcode = '22023';
+    end if;
+
+    select * into "v_page"
+    from "public"."facebook_ads_lead_page"
+    where "meta_page_id" = "p" ->> 'meta_page_id';
+
+    if not found then
+        return jsonb_build_object(
+            'event_id', null,
+            'accepted', false,
+            'duplicate', false,
+            'reason', 'page_not_configured'
+        );
+    end if;
+
+    select * into "v_settings"
+    from "public"."settings_facebook_ads"
+    where "company_id" = "v_page"."company_id";
+
+    select * into "v_form"
+    from "public"."facebook_ads_lead_form"
+    where "company_id" = "v_page"."company_id"
+      and "page_id" = "v_page"."id"
+      and "meta_form_id" = "p" ->> 'meta_form_id';
+    "v_form_found" := found;
+
+    if "v_form_found" then
+        "v_snapshot" := jsonb_build_object(
+            'form_id', "v_form"."id",
+            'form_name', "v_form"."form_name",
+            'is_enabled', "v_form"."is_enabled",
+            'field_mapping', "v_form"."field_mapping",
+            'sms', jsonb_build_object(
+                'attested', "v_form"."sms_consent_attested",
+                'disclosure', "v_form"."sms_consent_disclosure"
+            ),
+            'email', jsonb_build_object(
+                'attested', "v_form"."email_consent_attested",
+                'disclosure', "v_form"."email_consent_disclosure"
+            ),
+            'voice', jsonb_build_object(
+                'attested', "v_form"."voice_consent_attested",
+                'disclosure', "v_form"."voice_consent_disclosure"
+            )
+        );
+    end if;
+
+    "v_form_selected" := "v_page"."form_selection_mode" = 'all'
+        or ("v_form_found" and "v_form"."is_enabled");
+    "v_accepted" := "v_page"."is_enabled"
+        and "v_page"."subscription_status" = 'subscribed'
+        and coalesce("v_settings"."lead_sync_enabled", false)
+        and "v_settings"."source_id" is not null
+        and "v_form_selected";
+
+    "v_reason" := case
+        when not "v_page"."is_enabled"
+         and "v_page"."subscription_status" = 'pending'
+            then 'page_activation_pending'
+        when not "v_page"."is_enabled" then 'page_disabled'
+        when "v_page"."subscription_status" <> 'subscribed' then 'page_not_subscribed'
+        when not coalesce("v_settings"."lead_sync_enabled", false) then 'lead_sync_disabled'
+        when "v_settings"."source_id" is null then 'source_not_configured'
+        when not "v_form_selected" then 'form_not_selected'
+        else null
+    end;
+
+    insert into "public"."facebook_ads_lead_event" (
+        "company_id", "page_id", "meta_page_id", "meta_leadgen_id",
+        "meta_form_id", "meta_created_at", "source_id", "webhook_payload",
+        "form_configuration_snapshot", "status", "skip_reason"
+    ) values (
+        "v_page"."company_id",
+        "v_page"."id",
+        "p" ->> 'meta_page_id',
+        "p" ->> 'meta_leadgen_id',
+        "p" ->> 'meta_form_id',
+        ("p" ->> 'meta_created_at')::timestamp with time zone,
+        "v_settings"."source_id",
+        "v_webhook_payload",
+        "v_snapshot",
+        case when "v_accepted" then 'pending' else 'skipped' end,
+        "v_reason"
+    )
+    on conflict ("meta_page_id", "meta_leadgen_id") do update
+    set
+        "received_count" = "facebook_ads_lead_event"."received_count" + 1,
+        "last_received_at" = now()
+    returning "id", "received_count", "status", "skip_reason"
+    into "v_event_id", "v_received_count", "v_status", "v_return_reason";
+
+    return jsonb_build_object(
+        'event_id', "v_event_id",
+        'accepted', "v_status" <> 'skipped',
+        'duplicate', "v_received_count" > 1,
+        'reason', "v_return_reason"
+    );
+end;
+$$;
+
+alter function "public"."enqueue_facebook_ads_lead_event"(jsonb)
+owner to "postgres";
+
+create or replace function "public"."claim_facebook_ads_lead_events"(
+    "batch_size" integer
+)
+returns setof "public"."facebook_ads_lead_event"
+language sql
+security definer
+set search_path = ''
+as $$
+    update "public"."facebook_ads_lead_event"
+    set
+        "status" = 'processing',
+        "attempt_count" = "attempt_count" + 1,
+        "last_attempt_at" = now()
+    where "id" in (
+        select "id"
+        from "public"."facebook_ads_lead_event"
+        where "status" = 'pending' and "next_attempt_at" <= now()
+        order by "next_attempt_at", "created_at"
+        limit least(greatest(coalesce("batch_size", 0), 0), 100)
+        for update skip locked
+    )
+    returning *;
+$$;
+
+alter function "public"."claim_facebook_ads_lead_events"(integer)
+owner to "postgres";
+
+create or replace function "public"."replay_facebook_ads_lead_event"(
+    "p_company_id" uuid,
+    "p_event_id" uuid
+)
+returns boolean
+language plpgsql
+security definer
+set search_path = ''
+as $$
+declare
+    "v_updated" uuid;
+begin
+    update "public"."facebook_ads_lead_event" as "event_row"
+    set
+        "status" = 'pending',
+        "skip_reason" = null,
+        "attempt_count" = 0,
+        "replay_count" = "event_row"."replay_count" + 1,
+        "next_attempt_at" = now(),
+        "last_attempt_at" = null,
+        "processed_at" = null,
+        "last_error" = null
+    from "public"."settings_facebook_ads" as "settings",
+         "public"."facebook_ads_lead_page" as "page"
+    where "event_row"."id" = "p_event_id"
+      and "event_row"."company_id" = "p_company_id"
+      and "event_row"."status" in ('skipped', 'dead')
+      and "event_row"."client_id" is null
+      and "event_row"."page_id" = "page"."id"
+      and "page"."company_id" = "p_company_id"
+      and "page"."is_enabled"
+      and "page"."subscription_status" = 'subscribed'
+      -- Replay must respect the Page's current Form-selection policy. The
+      -- receipt-time form_configuration_snapshot remains untouched below so
+      -- consent evidence cannot be upgraded by later Form edits.
+      and (
+          "page"."form_selection_mode" = 'all'
+          or (
+              "page"."form_selection_mode" = 'selected'
+              and exists (
+                  select 1
+                  from "public"."facebook_ads_lead_form" as "form"
+                  where "form"."company_id" = "p_company_id"
+                    and "form"."page_id" = "page"."id"
+                    and "form"."meta_form_id" = "event_row"."meta_form_id"
+                    and "form"."is_enabled"
+              )
+          )
+      )
+      and "settings"."company_id" = "p_company_id"
+      and "settings"."lead_sync_enabled"
+      and "settings"."source_id" is not null
+    returning "event_row"."id" into "v_updated";
+
+    return "v_updated" is not null;
+end;
+$$;
+
+alter function "public"."replay_facebook_ads_lead_event"(uuid, uuid)
+owner to "postgres";
+
+create or replace function "public"."promote_facebook_ads_activation_gap_events"(
+    "p_company_id" uuid,
+    "p_page_id" uuid
+)
+returns table ("event_id" uuid)
+language plpgsql
+security definer
+set search_path = ''
+as $$
+begin
+    if "p_company_id" is null or "p_page_id" is null then
+        raise exception 'company_id and page_id are required'
+            using errcode = '22023';
+    end if;
+
+    return query
+    update "public"."facebook_ads_lead_event" as "event_row"
+    set
+        "status" = 'pending',
+        "skip_reason" = null,
+        "attempt_count" = 0,
+        "replay_count" = "event_row"."replay_count" + 1,
+        "next_attempt_at" = now(),
+        "last_attempt_at" = null,
+        "processed_at" = null,
+        "last_error" = null
+    from "public"."settings_facebook_ads" as "settings",
+         "public"."facebook_ads_lead_page" as "page"
+    where "event_row"."company_id" = "p_company_id"
+      and "event_row"."page_id" = "p_page_id"
+      and "event_row"."status" = 'skipped'
+      and "event_row"."skip_reason" = 'page_activation_pending'
+      and "event_row"."client_id" is null
+      and "page"."company_id" = "p_company_id"
+      and "page"."id" = "p_page_id"
+      and "page"."is_enabled"
+      and "page"."subscription_status" = 'subscribed'
+      and "settings"."company_id" = "p_company_id"
+      and "settings"."lead_sync_enabled"
+      and "settings"."source_id" is not null
+      and nullif(btrim(
+          "event_row"."form_configuration_snapshot" ->> 'form_id'
+      ), '') is not null
+      and "event_row"."form_configuration_snapshot" -> 'is_enabled'
+          = 'true'::jsonb
+      and exists (
+          select 1
+          from (values ('sms'), ('email'), ('voice')) as "channel_row"("name")
+          where "event_row"."form_configuration_snapshot"
+                    -> "channel_row"."name" -> 'attested' = 'true'::jsonb
+            and nullif(btrim(
+                "event_row"."form_configuration_snapshot"
+                    -> "channel_row"."name" ->> 'disclosure'
+            ), '') is not null
+      )
+    returning "event_row"."id";
+end;
+$$;
+
+alter function "public"."promote_facebook_ads_activation_gap_events"(uuid, uuid)
+owner to "postgres";
+
+create or replace function "public"."finalize_facebook_ads_lead_event"("p" jsonb)
+returns table (
+    "event_id" uuid,
+    "client_id" uuid,
+    "client_created" boolean,
+    "call_attempt_id" uuid
+)
+language plpgsql
+security definer
+set search_path = ''
+as $$
+declare
+    "v_event" "public"."facebook_ads_lead_event"%rowtype;
+    "v_page" "public"."facebook_ads_lead_page"%rowtype;
+    "v_settings" "public"."settings_facebook_ads"%rowtype;
+    "v_client_id" uuid;
+    "v_call_attempt_id" uuid;
+    "v_voice_consent_id" uuid;
+    "v_inserted_consent_id" uuid;
+    "v_phone" text := nullif(btrim("p" ->> 'primary_phone_number'), '');
+    "v_email" text := nullif(btrim("p" ->> 'email'), '');
+    "v_consents" jsonb := coalesce("p" -> 'consents', '[]'::jsonb);
+    "v_consent" jsonb;
+    "v_channel" text;
+    "v_status" text;
+    "v_disclosure" text;
+    "v_attested" boolean;
+    "v_sms_granted" boolean := false;
+    "v_email_granted" boolean := false;
+    "v_voice_granted" boolean := false;
+    "v_from_phone" text;
+    "v_company_timezone" text;
+begin
+    if jsonb_typeof("p") <> 'object'
+       or "p" ->> 'event_id' is null
+       or jsonb_typeof(coalesce("p" -> 'lead_payload', '{}'::jsonb)) <> 'object'
+       or jsonb_typeof("v_consents") <> 'array'
+    then
+        raise exception 'event_id, lead payload, and a consent array are required'
+            using errcode = '22023';
+    end if;
+
+    select * into "v_event"
+    from "public"."facebook_ads_lead_event"
+    where "id" = ("p" ->> 'event_id')::uuid
+    for update;
+
+    if not found then
+        raise exception 'Facebook lead event does not exist'
+            using errcode = 'P0002';
+    end if;
+
+    if "v_event"."status" = 'processed' and "v_event"."client_id" is not null then
+        return query select "v_event"."id", "v_event"."client_id", false, (
+            select "id" from "public"."facebook_ads_lead_call_attempt"
+            where "lead_event_id" = "v_event"."id"
+        );
+        return;
+    end if;
+
+    if "v_event"."status" <> 'processing' or "v_event"."client_id" is not null then
+        raise exception 'Facebook lead event is not claimable for finalization'
+            using errcode = '55000';
+    end if;
+
+    select * into "v_settings"
+    from "public"."settings_facebook_ads"
+    where "company_id" = "v_event"."company_id"
+    for share;
+
+    if not found
+       or not "v_settings"."lead_sync_enabled"
+       or "v_settings"."source_id" is null
+    then
+        update "public"."facebook_ads_lead_event"
+        set "status" = 'skipped', "skip_reason" = 'lead_sync_disabled'
+        where "id" = "v_event"."id";
+        return query select "v_event"."id", null::uuid, false, null::uuid;
+        return;
+    end if;
+
+    -- Graph retrieval happens outside this transaction. Re-lock the current
+    -- Page before any client/automation side effect so a disconnect that
+    -- completed in that interval fails closed. Holding the Page row through
+    -- commit also prevents it from being disabled after this check but before
+    -- the client INSERT below.
+    select * into "v_page"
+    from "public"."facebook_ads_lead_page"
+    where "id" = "v_event"."page_id"
+      and "company_id" = "v_event"."company_id"
+    for share;
+
+    if not found or not "v_page"."is_enabled" then
+        update "public"."facebook_ads_lead_event"
+        set "status" = 'skipped', "skip_reason" = 'page_disabled'
+        where "id" = "v_event"."id";
+        return query select "v_event"."id", null::uuid, false, null::uuid;
+        return;
+    end if;
+
+    if "v_page"."subscription_status" <> 'subscribed' then
+        update "public"."facebook_ads_lead_event"
+        set "status" = 'skipped', "skip_reason" = 'page_not_subscribed'
+        where "id" = "v_event"."id";
+        return query select "v_event"."id", null::uuid, false, null::uuid;
+        return;
+    end if;
+
+    if not exists (
+        select 1 from "public"."job_source"
+        where "id" = "v_settings"."source_id"
+          and "company_id" = "v_event"."company_id"
+    ) then
+        raise exception 'Configured Facebook lead source is invalid'
+            using errcode = '23503';
+    end if;
+
+    if nullif(btrim("p" ->> 'first_name'), '') is null
+       and nullif(btrim("p" ->> 'last_name'), '') is null
+       and "v_email" is null
+       and "v_phone" is null
+    then
+        raise exception 'A lead must include at least one contact field'
+            using errcode = '23514';
+    end if;
+
+    if (
+        select count(*) <> count(distinct "consent_row"."value" ->> 'channel')
+        from jsonb_array_elements("v_consents") as "consent_row"("value")
+    ) then
+        raise exception 'Consent channels must be unique'
+            using errcode = '23505';
+    end if;
+
+    -- Normalize consent before inserting the client. This is a critical
+    -- fail-closed invariant: the lead_created automation trigger fires on
+    -- the client INSERT, so its marketing DND flags must already reflect
+    -- explicit channel consent at that exact statement.
+    for "v_consent" in
+        select "consent_row"."value"
+        from jsonb_array_elements("v_consents") as "consent_row"("value")
+    loop
+        "v_channel" := "v_consent" ->> 'channel';
+        "v_status" := "v_consent" ->> 'status';
+
+        if "v_channel" is null
+           or "v_channel" not in ('email', 'sms', 'voice')
+           or "v_status" is null
+           or "v_status" not in ('granted', 'denied', 'unknown')
+           or jsonb_typeof(coalesce("v_consent" -> 'evidence', '{}'::jsonb)) <> 'object'
+        then
+            raise exception 'Consent channel, status, or evidence is invalid'
+                using errcode = '22023';
+        end if;
+
+        "v_attested" := coalesce((
+            "v_event"."form_configuration_snapshot"
+                -> "v_channel" ->> 'attested'
+        )::boolean, false);
+        "v_disclosure" := nullif(btrim(
+            "v_event"."form_configuration_snapshot"
+                -> "v_channel" ->> 'disclosure'
+        ), '');
+
+        if "v_status" = 'granted' and (
+            not "v_attested"
+            or "v_disclosure" is null
+            or "v_consent" ->> 'captured_at' is null
+        ) then
+            raise exception 'Granted consent requires an attested Form disclosure and capture time'
+                using errcode = '23514';
+        end if;
+
+        if "v_status" = 'granted' and "v_channel" = 'sms' then
+            "v_sms_granted" := true;
+        elsif "v_status" = 'granted' and "v_channel" = 'email' then
+            "v_email_granted" := true;
+        elsif "v_status" = 'granted' and "v_channel" = 'voice' then
+            "v_voice_granted" := true;
+        end if;
+    end loop;
+
+    insert into "public"."client" (
+        "company_id", "email", "first_name", "last_name",
+        "client_or_lead", "primary_phone_number", "source_id",
+        "created_via", "is_do_not_marketing_sms",
+        "is_do_not_marketing_email"
+    ) values (
+        "v_event"."company_id",
+        "v_email",
+        nullif(btrim("p" ->> 'first_name'), ''),
+        nullif(btrim("p" ->> 'last_name'), ''),
+        'lead'::"public"."client_or_lead_enum",
+        "v_phone",
+        "v_settings"."source_id",
+        'facebook_lead_ads',
+        not "v_sms_granted",
+        not "v_email_granted"
+    ) returning "id" into "v_client_id";
+
+    if "v_phone" is not null then
+        insert into "public"."phone_number" (
+            "company_id", "client_id", "twilio", "phone_number", "label"
+        ) values (
+            "v_event"."company_id", "v_client_id", false, "v_phone", 'Primary'
+        );
+    end if;
+
+    if "v_settings"."lead_tag_id" is not null then
+        if not exists (
+            select 1 from "public"."client_tag"
+            where "id" = "v_settings"."lead_tag_id"
+              and "company_id" = "v_event"."company_id"
+        ) then
+            raise exception 'Configured Facebook lead tag is invalid'
+                using errcode = '23503';
+        end if;
+        insert into "public"."client_tag_link" (
+            "company_id", "client_id", "client_tag_id"
+        ) values (
+            "v_event"."company_id", "v_client_id", "v_settings"."lead_tag_id"
+        );
+    end if;
+
+    for "v_consent" in
+        select "consent_row"."value"
+        from jsonb_array_elements("v_consents") as "consent_row"("value")
+    loop
+        "v_channel" := "v_consent" ->> 'channel';
+        "v_status" := "v_consent" ->> 'status';
+        "v_disclosure" := nullif(btrim(
+            "v_event"."form_configuration_snapshot"
+                -> "v_channel" ->> 'disclosure'
+        ), '');
+
+        insert into "public"."facebook_ads_lead_consent" (
+            "company_id", "lead_event_id", "channel", "status",
+            "captured_at", "disclosure_text", "response_value", "evidence"
+        ) values (
+            "v_event"."company_id",
+            "v_event"."id",
+            "v_channel",
+            "v_status",
+            ("v_consent" ->> 'captured_at')::timestamp with time zone,
+            "v_disclosure",
+            "v_consent" ->> 'response_value',
+            coalesce("v_consent" -> 'evidence', '{}'::jsonb)
+        ) returning "id" into "v_inserted_consent_id";
+
+        if "v_channel" = 'voice' and "v_status" = 'granted' then
+            "v_voice_consent_id" := "v_inserted_consent_id";
+        end if;
+    end loop;
+
+    update "public"."facebook_ads_lead_event"
+    set
+        "source_id" = "v_settings"."source_id",
+        "client_id" = "v_client_id",
+        "lead_payload" = coalesce("p" -> 'lead_payload', '{}'::jsonb),
+        "meta_ad_id" = nullif("p" ->> 'meta_ad_id', ''),
+        "meta_adset_id" = nullif("p" ->> 'meta_adset_id', ''),
+        "meta_campaign_id" = nullif("p" ->> 'meta_campaign_id', ''),
+        "fetched_at" = now(),
+        "processed_at" = now(),
+        "status" = 'processed',
+        "skip_reason" = null,
+        "last_error" = null
+    where "id" = "v_event"."id";
+
+    -- Voice is stricter than record creation: no explicit, attested voice
+    -- grant means no call-attempt row exists for a worker to accidentally
+    -- claim. Settings and current number/user linkage are revalidated here.
+    if "v_voice_granted"
+       and "v_voice_consent_id" is not null
+       and "v_phone" is not null
+       and "v_settings"."lead_auto_dial_enabled"
+       and "v_settings"."lead_auto_dial_phone_number_id" is not null
+       and "v_settings"."lead_auto_dial_user_id" is not null
+    then
+        select "phone"."phone_number", "company"."time_zone"
+        into "v_from_phone", "v_company_timezone"
+        from "public"."phone_number" as "phone"
+        inner join "public"."company" as "company"
+          on "company"."id" = "phone"."company_id"
+        inner join "public"."user" as "user_row"
+          on "user_row"."id" = "v_settings"."lead_auto_dial_user_id"
+         and "user_row"."company_id" = "phone"."company_id"
+         and "user_row"."is_current_employee" = true
+        inner join "public"."phone_number_user_link" as "link"
+          on "link"."company_id" = "phone"."company_id"
+         and "link"."phone_number_id" = "phone"."id"
+         and "link"."user_id" = "user_row"."id"
+        where "phone"."id" = "v_settings"."lead_auto_dial_phone_number_id"
+          and "phone"."company_id" = "v_event"."company_id"
+          and "phone"."twilio" = true
+          and "phone"."client_id" is null
+          and "phone"."phone_sid" is not null;
+
+        if found then
+            insert into "public"."facebook_ads_lead_call_attempt" (
+                "company_id", "lead_event_id", "client_id", "consent_id",
+                "from_phone_number_id", "target_user_id",
+                "from_phone_number", "destination_phone_number",
+                "routing_snapshot", "next_attempt_at"
+            ) values (
+                "v_event"."company_id",
+                "v_event"."id",
+                "v_client_id",
+                "v_voice_consent_id",
+                "v_settings"."lead_auto_dial_phone_number_id",
+                "v_settings"."lead_auto_dial_user_id",
+                "v_from_phone",
+                "v_phone",
+                jsonb_build_object(
+                    'time_zone', "v_company_timezone",
+                    'window_start', "v_settings"."lead_auto_dial_window_start",
+                    'window_end', "v_settings"."lead_auto_dial_window_end",
+                    'window_days', "v_settings"."lead_auto_dial_window_days",
+                    'delay_seconds', "v_settings"."lead_auto_dial_delay_seconds"
+                ),
+                now() + make_interval(
+                    secs => "v_settings"."lead_auto_dial_delay_seconds"
+                )
+            ) returning "id" into "v_call_attempt_id";
+        end if;
+    end if;
+
+    return query select "v_event"."id", "v_client_id", true, "v_call_attempt_id";
+end;
+$$;
+
+alter function "public"."finalize_facebook_ads_lead_event"(jsonb)
+owner to "postgres";
+
+-- ============================================================
+-- Call claim and state-transition RPCs
+-- ============================================================
+
+create or replace function "public"."claim_facebook_ads_lead_call_attempts"(
+    "batch_size" integer
+)
+returns setof "public"."facebook_ads_lead_call_attempt"
+language sql
+security definer
+set search_path = ''
+as $$
+    update "public"."facebook_ads_lead_call_attempt"
+    set
+        "status" = 'processing',
+        "held_reason" = null,
+        "attempt_count" = "attempt_count" + 1,
+        "last_attempt_at" = now(),
+        "started_at" = coalesce("started_at", now())
+    where "id" in (
+        select "id"
+        from "public"."facebook_ads_lead_call_attempt"
+        where "status" = 'pending' and "next_attempt_at" <= now()
+        order by "next_attempt_at", "created_at"
+        limit least(greatest(coalesce("batch_size", 0), 0), 100)
+        for update skip locked
+    )
+    returning *;
+$$;
+
+alter function "public"."claim_facebook_ads_lead_call_attempts"(integer)
+owner to "postgres";
+
+create or replace function "public"."update_facebook_ads_lead_call_state"(
+    "p" jsonb
+)
+returns boolean
+language plpgsql
+security definer
+set search_path = ''
+as $$
+declare
+    "v_company_id" uuid := ("p" ->> 'company_id')::uuid;
+    "v_attempt_id" uuid := ("p" ->> 'attempt_id')::uuid;
+    "v_new_status" text := "p" ->> 'status';
+    "v_expected_status" text := "p" ->> 'expected_status';
+    "v_attempt" "public"."facebook_ads_lead_call_attempt"%rowtype;
+    "v_old_rank" integer;
+    "v_new_rank" integer;
+    "v_terminal" boolean;
+    "v_answered_by" uuid := ("p" ->> 'answered_by_user_id')::uuid;
+    "v_next_attempt_at" timestamp with time zone :=
+        ("p" ->> 'next_attempt_at')::timestamp with time zone;
+    "v_expected_updated_at" timestamp with time zone :=
+        ("p" ->> 'expected_updated_at')::timestamp with time zone;
+    "v_is_retry_hold" boolean;
+begin
+    if jsonb_typeof("p") <> 'object'
+       or "v_company_id" is null
+       or "v_attempt_id" is null
+       or "v_new_status" is null
+       or ("p" ? 'next_attempt_at' and "v_next_attempt_at" is null)
+       or (
+            "p" ? 'expected_updated_at'
+            and "v_expected_updated_at" is null
+       )
+       or (
+            "p" ? 'expected_status'
+            and (
+                "v_expected_status" is null
+                or "v_expected_status" not in (
+                    'pending', 'processing', 'agent_ringing', 'lead_ringing',
+                    'connected', 'completed', 'skipped', 'failed', 'dead'
+                )
+            )
+       )
+       or "v_new_status" not in (
+            'pending', 'processing', 'agent_ringing', 'lead_ringing',
+            'connected', 'completed', 'skipped', 'failed', 'dead'
+       )
+    then
+        raise exception 'Valid company, attempt, and call status are required'
+            using errcode = '22023';
+    end if;
+
+    select * into "v_attempt"
+    from "public"."facebook_ads_lead_call_attempt"
+    where "id" = "v_attempt_id" and "company_id" = "v_company_id"
+    for update;
+
+    if not found then
+        return false;
+    end if;
+
+    -- Optional compare-and-set guards let sweepers inspect provider state,
+    -- then safely dead-letter only if no callback advanced the row while the
+    -- provider request was in flight. Existing callers can omit both keys.
+    if ("p" ? 'expected_status'
+        and "v_attempt"."status" <> "v_expected_status")
+       or ("p" ? 'expected_updated_at'
+        and "v_attempt"."updated_at" is distinct from "v_expected_updated_at")
+    then
+        return false;
+    end if;
+
+    "v_terminal" := "v_attempt"."status" in (
+        'completed', 'skipped', 'failed', 'dead'
+    );
+    "v_old_rank" := case "v_attempt"."status"
+        when 'pending' then 0
+        when 'processing' then 1
+        when 'agent_ringing' then 2
+        when 'lead_ringing' then 3
+        when 'connected' then 4
+        else 5
+    end;
+    "v_new_rank" := case "v_new_status"
+        when 'pending' then 0
+        when 'processing' then 1
+        when 'agent_ringing' then 2
+        when 'lead_ringing' then 3
+        when 'connected' then 4
+        else 5
+    end;
+    -- A hold is the sole permitted backward transition. Before provider work
+    -- it releases a processing claim; after the agent answers it lets a
+    -- transient entitlement/configuration check defer safely once the web
+    -- worker has ended the current conference. CAS guards remain available so
+    -- a concurrent callback always wins.
+    "v_is_retry_hold" := "v_attempt"."status" in ('processing', 'agent_ringing')
+        and "v_new_status" = 'pending'
+        and "v_next_attempt_at" is not null
+        and "v_next_attempt_at" > now()
+        and nullif(btrim("p" ->> 'held_reason'), '') is not null;
+
+    if ("v_terminal" and "v_new_status" <> "v_attempt"."status")
+       or (
+            not "v_terminal"
+            and "v_new_rank" < "v_old_rank"
+            and not "v_is_retry_hold"
+       )
+    then
+        raise exception 'Call state cannot transition backward or leave a terminal state'
+            using errcode = '23514';
+    end if;
+
+    if "v_answered_by" is not null and not exists (
+        select 1 from "public"."user"
+        where "id" = "v_answered_by" and "company_id" = "v_company_id"
+    ) then
+        raise exception 'Answered-by user does not belong to this company'
+            using errcode = '23503';
+    end if;
+
+    update "public"."facebook_ads_lead_call_attempt"
+    set
+        "status" = "v_new_status",
+        "held_reason" = case
+            when "p" ? 'held_reason' then "p" ->> 'held_reason'
+            when "v_new_status" <> 'pending' then null
+            else "v_attempt"."held_reason" end,
+        "next_attempt_at" = case
+            when "p" ? 'next_attempt_at' then "v_next_attempt_at"
+            else "v_attempt"."next_attempt_at" end,
+        "twilio_agent_call_sid" = case
+            when "p" ? 'twilio_agent_call_sid'
+                then nullif("p" ->> 'twilio_agent_call_sid', '')
+            else "v_attempt"."twilio_agent_call_sid" end,
+        "twilio_lead_call_sid" = case
+            when "p" ? 'twilio_lead_call_sid'
+                then nullif("p" ->> 'twilio_lead_call_sid', '')
+            else "v_attempt"."twilio_lead_call_sid" end,
+        "twilio_conference_sid" = case
+            when "p" ? 'twilio_conference_sid'
+                then nullif("p" ->> 'twilio_conference_sid', '')
+            else "v_attempt"."twilio_conference_sid" end,
+        "answered_by_user_id" = case
+            when "p" ? 'answered_by_user_id' then "v_answered_by"
+            else "v_attempt"."answered_by_user_id" end,
+        "started_at" = case
+            when "p" ? 'started_at'
+                then ("p" ->> 'started_at')::timestamp with time zone
+            else "v_attempt"."started_at" end,
+        "connected_at" = case
+            when "p" ? 'connected_at'
+                then ("p" ->> 'connected_at')::timestamp with time zone
+            when "v_new_status" = 'connected'
+                then coalesce("v_attempt"."connected_at", now())
+            else "v_attempt"."connected_at" end,
+        "completed_at" = case
+            when "p" ? 'completed_at'
+                then ("p" ->> 'completed_at')::timestamp with time zone
+            when "v_new_status" in ('completed', 'skipped', 'failed', 'dead')
+                then coalesce("v_attempt"."completed_at", now())
+            else "v_attempt"."completed_at" end,
+        "skip_reason" = case
+            when "p" ? 'skip_reason' then "p" ->> 'skip_reason'
+            else "v_attempt"."skip_reason" end,
+        "last_error" = case
+            when "p" ? 'last_error' then "p" ->> 'last_error'
+            else "v_attempt"."last_error" end
+    where "id" = "v_attempt_id";
+
+    return true;
+end;
+$$;
+
+alter function "public"."update_facebook_ads_lead_call_state"(jsonb)
+owner to "postgres";
+
+-- ============================================================
+-- Function permissions (tables are handled in the RLS migration)
+-- ============================================================
+
+revoke all on function "public"."facebook_ads_text_array_is_normalized"(text[])
+from public;
+revoke all on function "public"."facebook_ads_text_array_is_normalized"(text[])
+from "anon";
+revoke all on function "public"."facebook_ads_text_array_is_normalized"(text[])
+from "authenticated";
+grant execute on function "public"."facebook_ads_text_array_is_normalized"(text[])
+to "service_role";
+
+revoke all on function "public"."facebook_ads_call_days_are_normalized"(smallint[])
+from public;
+revoke all on function "public"."facebook_ads_call_days_are_normalized"(smallint[])
+from "anon";
+revoke all on function "public"."facebook_ads_call_days_are_normalized"(smallint[])
+from "authenticated";
+grant execute on function "public"."facebook_ads_call_days_are_normalized"(smallint[])
+to "service_role";
+
+revoke all on function "public"."set_facebook_ads_lead_settings"(jsonb) from public;
+revoke all on function "public"."set_facebook_ads_lead_settings"(jsonb) from "anon";
+revoke all on function "public"."set_facebook_ads_lead_settings"(jsonb) from "authenticated";
+grant execute on function "public"."set_facebook_ads_lead_settings"(jsonb) to "service_role";
+
+revoke all on function "public"."enqueue_facebook_ads_lead_event"(jsonb) from public;
+revoke all on function "public"."enqueue_facebook_ads_lead_event"(jsonb) from "anon";
+revoke all on function "public"."enqueue_facebook_ads_lead_event"(jsonb) from "authenticated";
+grant execute on function "public"."enqueue_facebook_ads_lead_event"(jsonb) to "service_role";
+
+revoke all on function "public"."claim_facebook_ads_lead_events"(integer) from public;
+revoke all on function "public"."claim_facebook_ads_lead_events"(integer) from "anon";
+revoke all on function "public"."claim_facebook_ads_lead_events"(integer) from "authenticated";
+grant execute on function "public"."claim_facebook_ads_lead_events"(integer) to "service_role";
+
+revoke all on function "public"."replay_facebook_ads_lead_event"(uuid, uuid) from public;
+revoke all on function "public"."replay_facebook_ads_lead_event"(uuid, uuid) from "anon";
+revoke all on function "public"."replay_facebook_ads_lead_event"(uuid, uuid) from "authenticated";
+grant execute on function "public"."replay_facebook_ads_lead_event"(uuid, uuid) to "service_role";
+
+revoke all on function "public"."promote_facebook_ads_activation_gap_events"(uuid, uuid) from public;
+revoke all on function "public"."promote_facebook_ads_activation_gap_events"(uuid, uuid) from "anon";
+revoke all on function "public"."promote_facebook_ads_activation_gap_events"(uuid, uuid) from "authenticated";
+grant execute on function "public"."promote_facebook_ads_activation_gap_events"(uuid, uuid) to "service_role";
+
+revoke all on function "public"."finalize_facebook_ads_lead_event"(jsonb) from public;
+revoke all on function "public"."finalize_facebook_ads_lead_event"(jsonb) from "anon";
+revoke all on function "public"."finalize_facebook_ads_lead_event"(jsonb) from "authenticated";
+grant execute on function "public"."finalize_facebook_ads_lead_event"(jsonb) to "service_role";
+
+revoke all on function "public"."claim_facebook_ads_lead_call_attempts"(integer)
+from public;
+revoke all on function "public"."claim_facebook_ads_lead_call_attempts"(integer)
+from "anon";
+revoke all on function "public"."claim_facebook_ads_lead_call_attempts"(integer)
+from "authenticated";
+grant execute on function "public"."claim_facebook_ads_lead_call_attempts"(integer)
+to "service_role";
+
+revoke all on function "public"."update_facebook_ads_lead_call_state"(jsonb)
+from public;
+revoke all on function "public"."update_facebook_ads_lead_call_state"(jsonb)
+from "anon";
+revoke all on function "public"."update_facebook_ads_lead_call_state"(jsonb)
+from "authenticated";
+grant execute on function "public"."update_facebook_ads_lead_call_state"(jsonb)
+to "service_role";