autopilot-core-sandbox 0.0.1

package/dist/dist/migrations/20260729004305_marketing_charge_txn_functions.sql

@@ -0,0 +1,242 @@
+-- Transactional wallet charging for marketing sends.
+--
+-- chargeMarketingUsage/refundMarketingCharge in autopilot-web previously
+-- performed the claim insert, usage event, balance movement, and status
+-- update as four separate PostgREST calls; any failure between them left a
+-- split state (a claimed key whose money never moved, a completed movement
+-- stuck 'pending', a credited refund whose claim row was already terminal).
+-- These functions make each charge/refund one transaction, so those states
+-- can no longer exist:
+--
+--   - unexpected errors abort the WHOLE transaction: no claim row, no usage
+--     event, no money moved - the caller may safely retry with the same
+--     idempotency key;
+--   - insufficient funds (deduct_from_balance's balance floor) is a business
+--     outcome, not a fault: the charge row COMMITS as status 'failed' with
+--     metadata.failure = 'insufficient_funds', so uncollected post-send
+--     charges stay queryable/collectible, while the money (never moved) and
+--     the row can no longer disagree;
+--   - a lost response after commit is self-correcting: the transaction
+--     committed whole, so a retry hits the idempotency key and no-ops with
+--     'already_charged' / 'already_refunded'.
+--
+-- Charge quote math (quota, rates, billable remainder) stays in web's
+-- marketingCharging.ts - charge_marketing_usage only owns the write phase.
+-- Refund math is the exception: it derives entirely from the deduction row
+-- being reversed, so it lives in refund_marketing_charge (see below).
+
+create or replace function "public"."charge_marketing_usage"(
+    "input_company_id" uuid,
+    "input_meter" text,
+    "input_period_start" date,
+    "input_period_end" date,
+    "input_quantity_total" integer,
+    "input_quantity_included" numeric,
+    "input_quantity_charged" numeric,
+    "input_unit_rate" numeric,
+    "input_amount_cents" integer,
+    "input_idempotency_key" text,
+    "input_source" text,
+    -- Pre-send callers (email) abort the send when the deduction fails, so
+    -- the usage event must not survive an insufficient-funds failure;
+    -- post-send callers (SMS) keep it - the messages went out.
+    "input_release_usage_on_failure" boolean default false
+) returns text
+language plpgsql
+security invoker
+set search_path = public
+as $$
+begin
+    insert into "public"."usage_charge" (
+        "company_id", "period_start", "period_end", "meter", "kind",
+        "quantity_total", "quantity_included", "quantity_charged",
+        "unit_rate", "amount_cents", "status", "idempotency_key", "metadata"
+    ) values (
+        input_company_id, input_period_start, input_period_end, input_meter,
+        'wallet_deduction',
+        input_quantity_total, input_quantity_included, input_quantity_charged,
+        input_unit_rate, input_amount_cents,
+        case when input_amount_cents > 0 then 'pending' else 'zero' end,
+        input_idempotency_key,
+        jsonb_build_object('source', input_source)
+    )
+    on conflict ("idempotency_key") do nothing;
+    if not found then
+        return 'already_charged';
+    end if;
+
+    if input_quantity_total <> 0 then
+        insert into "public"."usage_event"
+            ("company_id", "meter", "quantity", "source", "ref")
+        values
+            (input_company_id, input_meter, input_quantity_total,
+             input_source, input_idempotency_key)
+        on conflict ("company_id", "meter", "ref") where "ref" is not null
+        do nothing;
+    end if;
+
+    if input_amount_cents <= 0 then
+        return 'zero';
+    end if;
+
+    begin
+        perform "public"."deduct_from_balance"(
+            input_company_id, input_amount_cents / 100.0
+        );
+    exception when others then
+        -- 'AP402' is deduct_from_balance's stable insufficient-funds
+        -- errcode (see the update_deduct_from_balance_errcode migration);
+        -- the message match is a belt-and-braces fallback in case a later
+        -- hand edit of that function drops the errcode.
+        if sqlstate = 'AP402' or sqlerrm like 'Insufficient funds%' then
+            update "public"."usage_charge"
+            set "status" = 'failed',
+                "metadata" = "metadata" || jsonb_build_object(
+                    'failure', 'insufficient_funds',
+                    'failure_message', sqlerrm
+                )
+            where "idempotency_key" = input_idempotency_key;
+            if input_release_usage_on_failure then
+                delete from "public"."usage_event"
+                where "company_id" = input_company_id
+                  and "meter" = input_meter
+                  and "ref" = input_idempotency_key;
+            end if;
+            return 'insufficient_funds';
+        end if;
+        raise;
+    end;
+
+    update "public"."usage_charge"
+    set "status" = 'charged'
+    where "idempotency_key" = input_idempotency_key;
+    return 'charged';
+end;
+$$;
+
+alter function "public"."charge_marketing_usage"(
+    uuid, text, date, date, integer, numeric, numeric, numeric, integer,
+    text, text, boolean
+) owner to "postgres";
+
+-- Refund mirror. Everything money-shaped is derived here from the
+-- deduction row being reversed - the refund's idempotency key is
+-- '<deduction key>:refund', units are capped by what the deduction
+-- recorded, and the rate and meter come from the row - so the caller
+-- supplies no amounts and a malformed request cannot over-credit,
+-- re-credit under a fresh key, or refund a nonexistent deduction. Returns
+-- jsonb (unlike the charge function's text) because the caller needs the
+-- refunded amount computed here.
+--
+-- Free quota is consumed before billed units, so the billed units are the
+-- LAST quantity_charged of the batch - the unsent tail refunds from the
+-- billed portion first. A deduction that never charged (status 'failed' or
+-- 'zero') moves no money, and releases quota only if its usage event is
+-- still recorded - a failed pre-send charge already released it.
+--
+-- add_to_balance has no balance floor, so there is no business-failure
+-- branch: any error aborts the whole transaction (claim row included),
+-- leaving the refund cleanly retryable.
+create or replace function "public"."refund_marketing_charge"(
+    "input_company_id" uuid,
+    "input_period_start" date,
+    "input_period_end" date,
+    "input_unsent_units" integer,
+    "input_deduction_key" text
+) returns jsonb
+language plpgsql
+security invoker
+set search_path = public
+as $$
+declare
+    deduction "public"."usage_charge"%rowtype;
+    refund_key text := input_deduction_key || ':refund';
+    unsent integer;
+    refund_units numeric;
+    refund_cents integer;
+begin
+    select * into deduction
+    from "public"."usage_charge"
+    where "idempotency_key" = input_deduction_key
+      and "company_id" = input_company_id
+      and "kind" = 'wallet_deduction';
+    if not found then
+        return jsonb_build_object(
+            'outcome', 'no_deduction', 'refunded_cents', 0
+        );
+    end if;
+
+    unsent := least(
+        input_unsent_units::numeric, deduction."quantity_total"
+    )::integer;
+    if unsent <= 0 then
+        return jsonb_build_object('outcome', 'zero', 'refunded_cents', 0);
+    end if;
+    refund_units := least(unsent::numeric, deduction."quantity_charged");
+    refund_cents := case
+        when deduction."status" = 'charged'
+        then round(refund_units * deduction."unit_rate" * 100)::integer
+        else 0
+    end;
+
+    insert into "public"."usage_charge" (
+        "company_id", "period_start", "period_end", "meter", "kind",
+        "quantity_total", "quantity_included", "quantity_charged",
+        "unit_rate", "amount_cents", "status", "idempotency_key", "metadata"
+    ) values (
+        input_company_id, input_period_start, input_period_end,
+        deduction."meter",
+        'wallet_refund',
+        unsent, unsent - refund_units, refund_units,
+        deduction."unit_rate", refund_cents,
+        case when refund_cents > 0 then 'pending' else 'zero' end,
+        refund_key,
+        jsonb_build_object('refunds', input_deduction_key)
+    )
+    on conflict ("idempotency_key") do nothing;
+    if not found then
+        return jsonb_build_object(
+            'outcome', 'already_refunded', 'refunded_cents', 0
+        );
+    end if;
+
+    -- Release the unsent units' quota consumption - but only if the
+    -- deduction's usage event is still recorded. A pre-send charge that
+    -- failed with release_usage_on_failure already deleted its event, so
+    -- releasing again here would drive net usage negative and grant quota
+    -- the company never consumed.
+    if exists (
+        select 1 from "public"."usage_event"
+        where "company_id" = input_company_id
+          and "meter" = deduction."meter"
+          and "ref" = input_deduction_key
+    ) then
+        insert into "public"."usage_event"
+            ("company_id", "meter", "quantity", "source", "ref")
+        values
+            (input_company_id, deduction."meter", -unsent, 'refund',
+             refund_key)
+        on conflict ("company_id", "meter", "ref") where "ref" is not null
+        do nothing;
+    end if;
+
+    if refund_cents <= 0 then
+        return jsonb_build_object('outcome', 'zero', 'refunded_cents', 0);
+    end if;
+
+    perform "public"."add_to_balance"(
+        input_company_id, refund_cents / 100.0
+    );
+
+    update "public"."usage_charge"
+    set "status" = 'charged'
+    where "idempotency_key" = refund_key;
+    return jsonb_build_object(
+        'outcome', 'refunded', 'refunded_cents', refund_cents
+    );
+end;
+$$;
+
+alter function "public"."refund_marketing_charge"(
+    uuid, date, date, integer, text
+) owner to "postgres";

package/dist/dist/migrations/20260729004306_marketing_charge_txn_functions_rls.sql

@@ -0,0 +1,37 @@
+-- Grants for the transactional marketing charge/refund functions.
+--
+-- These move money, so unlike sum_usage_events they are service_role-only:
+-- the web server's admin client is the sole caller. Functions default to
+-- EXECUTE for public on creation, so revoke that and grant service_role
+-- explicitly. security invoker + no authenticated/anon grant means no
+-- privilege escalation path exists through them.
+
+revoke all on function "public"."charge_marketing_usage"(
+    uuid, text, date, date, integer, numeric, numeric, numeric, integer,
+    text, text, boolean
+) from public;
+revoke all on function "public"."charge_marketing_usage"(
+    uuid, text, date, date, integer, numeric, numeric, numeric, integer,
+    text, text, boolean
+) from "anon";
+revoke all on function "public"."charge_marketing_usage"(
+    uuid, text, date, date, integer, numeric, numeric, numeric, integer,
+    text, text, boolean
+) from "authenticated";
+grant execute on function "public"."charge_marketing_usage"(
+    uuid, text, date, date, integer, numeric, numeric, numeric, integer,
+    text, text, boolean
+) to "service_role";
+
+revoke all on function "public"."refund_marketing_charge"(
+    uuid, date, date, integer, text
+) from public;
+revoke all on function "public"."refund_marketing_charge"(
+    uuid, date, date, integer, text
+) from "anon";
+revoke all on function "public"."refund_marketing_charge"(
+    uuid, date, date, integer, text
+) from "authenticated";
+grant execute on function "public"."refund_marketing_charge"(
+    uuid, date, date, integer, text
+) to "service_role";

package/dist/dist/migrations/20260729005524_update_deduct_from_balance_errcode.sql

@@ -0,0 +1,42 @@
+-- Give deduct_from_balance's insufficient-funds rejection a stable,
+-- machine-readable SQLSTATE ('AP402', app-defined "payment required").
+-- charge_marketing_usage branches on this errcode to decide whether a
+-- deduction failure is a business outcome (commit the charge row as
+-- 'failed', collectible later) or an unexpected fault (roll the whole
+-- transaction back); previously the only contract was the message text,
+-- which a wording change would silently break.
+--
+-- Everything else - signature, message, floor, SECURITY DEFINER, grants
+-- (preserved by CREATE OR REPLACE) - is unchanged, so existing callers
+-- are unaffected.
+
+CREATE OR REPLACE FUNCTION "public"."deduct_from_balance"("input_company_id" "uuid", "amount_to_deduct" numeric) RETURNS numeric
+    LANGUAGE "plpgsql" SECURITY DEFINER
+    AS $$
+DECLARE
+  current_balance NUMERIC;
+  new_balance NUMERIC;
+BEGIN
+  -- First, get the current balance
+  SELECT balance INTO current_balance
+  FROM billing
+  WHERE company_id = input_company_id;
+
+  -- Calculate the new balance
+  new_balance := current_balance - amount_to_deduct;
+
+  -- Check if the new balance would be less than -20.00
+  IF new_balance < -20.00 THEN
+    RAISE EXCEPTION 'Insufficient funds: Balance cannot go below -20.00'
+      USING ERRCODE = 'AP402';
+  END IF;
+
+  -- If we've passed the check, update the balance
+  UPDATE billing
+  SET balance = new_balance
+  WHERE company_id = input_company_id;
+
+  -- Return the new balance
+  RETURN new_balance;
+END;
+$$;

package/dist/dist/migrations/20260730193601_fix_deduct_from_balance_lost_update.sql

@@ -0,0 +1,46 @@
+-- Lock the billing row while deducting. The read was a bare SELECT, so two
+-- concurrent charges (e.g. an SMS blast chunk and a sequence batch) could
+-- both read the same balance, both pass the -20.00 floor, and both write
+-- their own absolute new_balance - the second write silently erases the
+-- first deduction even though both usage_charge rows commit as 'charged'.
+-- FOR UPDATE serializes the read-modify-write per company row, which also
+-- makes the floor enforceable under concurrency. The lock is held to the
+-- end of the caller's transaction (charge_marketing_usage runs this inside
+-- one txn), which is exactly the window that needs protecting.
+--
+-- Everything else - signature, message, floor, ERRCODE 'AP402',
+-- SECURITY DEFINER, grants (preserved by CREATE OR REPLACE) - is unchanged,
+-- so existing callers are unaffected.
+
+CREATE OR REPLACE FUNCTION "public"."deduct_from_balance"("input_company_id" "uuid", "amount_to_deduct" numeric) RETURNS numeric
+    LANGUAGE "plpgsql" SECURITY DEFINER
+    AS $$
+DECLARE
+  current_balance NUMERIC;
+  new_balance NUMERIC;
+BEGIN
+  -- Get the current balance, locking the row so a concurrent deduction
+  -- can't read the same starting balance
+  SELECT balance INTO current_balance
+  FROM billing
+  WHERE company_id = input_company_id
+  FOR UPDATE;
+
+  -- Calculate the new balance
+  new_balance := current_balance - amount_to_deduct;
+
+  -- Check if the new balance would be less than -20.00
+  IF new_balance < -20.00 THEN
+    RAISE EXCEPTION 'Insufficient funds: Balance cannot go below -20.00'
+      USING ERRCODE = 'AP402';
+  END IF;
+
+  -- If we've passed the check, update the balance
+  UPDATE billing
+  SET balance = new_balance
+  WHERE company_id = input_company_id;
+
+  -- Return the new balance
+  RETURN new_balance;
+END;
+$$;

package/dist/dist/migrations/20260730193602_add_blast_sms_chunk_reaper_columns.sql

@@ -0,0 +1,27 @@
+-- Mirror blast_email_chunk (20260717162900): per-chunk delivery outcomes so
+-- blast_sms totals can be derived by aggregating chunk rows (overlapping
+-- chunk workers can't lose each other's increments the way the current
+-- read-modify-write on blast_sms.processed_chunks can), plus the claim
+-- timestamp that lets a retry prove a 'processing' chunk's worker was
+-- hard-killed and reap it - without that, a mid-chunk crash strands the
+-- blast in 'processing' forever.
+--
+-- No per-chunk cost column: blast_sms.actual_cost stays derived from
+-- usage_charge rows keyed 'blast-sms:{blastId}:chunk:%'.
+--
+-- All columns nullable so chunks written by the pre-reaper worker are
+-- unaffected; the worker treats a null claimed_at as not-provably-stale.
+
+alter table "public"."blast_sms_chunk"
+    add column if not exists "successful_count" integer,
+    add column if not exists "failed_count" integer,
+    add column if not exists "claimed_at" timestamp with time zone,
+    add column if not exists "recipient_count" integer;
+
+-- Same access paths as the email worker: aggregate/sweep by blast, claim by
+-- QStash message id.
+create index if not exists "blast_sms_chunk_blast_sms_id_idx"
+    on "public"."blast_sms_chunk" ("blast_sms_id");
+
+create index if not exists "blast_sms_chunk_qstash_message_id_idx"
+    on "public"."blast_sms_chunk" ("qstash_message_id");

package/dist/dist/migrations/20260731011415_create_google_calendar_connection.sql

@@ -0,0 +1,84 @@
+-- Per-USER Google Calendar connection — the first user-scoped integration
+-- (every other *_connection table is one row per company). A user connects
+-- their personal Google account and autopilot-web mirrors the jobs, events,
+-- and estimates they can see onto their primary Google calendar. The refresh
+-- token is AES-256-GCM encrypted by the web layer (v1.<iv>.<tag>.<ct>
+-- format, GOOGLE_CALENDAR_TOKEN_ENCRYPTION_KEY) and, like Bing/Facebook Ads,
+-- exposed only to service-role routes by the companion RLS migration —
+-- clients read connection state through /api/google-calendar/status.
+--
+-- status:
+--   active        normal operation
+--   needs_reauth  Google reported the grant revoked/expired; sync pauses
+--                 until the user reconnects
+--   disconnecting user disconnected; a 'purge' sync task is deleting the
+--                 mirrored Google events, after which the worker deletes
+--                 this row
+create table if not exists "public"."google_calendar_connection" (
+    "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,
+    "user_id" uuid not null,
+    "google_email" text,
+    "refresh_token_encrypted" text not null,
+    -- false pauses the mirror without touching the token or the already
+    -- synced events; re-enabling runs a full reconcile to catch up
+    "sync_enabled" boolean default true not null,
+    "status" text default 'active' not null,
+    "last_synced_at" timestamp with time zone,
+    constraint "google_calendar_connection_pkey" primary key ("id"),
+    -- a user working for two companies connects (and mirrors) per company
+    constraint "google_calendar_connection_company_user_key"
+        unique ("company_id", "user_id"),
+    -- These cascades are the LAST-RESORT cleanup, not the purge path: the
+    -- refresh token needed to delete the mirrored Google events dies with
+    -- this row, so account deletion (delete-own-account-owner, the only flow
+    -- that deletes company/user rows) best-effort purges every connection's
+    -- events and revokes the grants BEFORE deleting the company. Employee
+    -- removal never deletes user rows, so it never hits these.
+    constraint "google_calendar_connection_company_id_fkey"
+        foreign key ("company_id") references "public"."company"("id") on delete cascade,
+    constraint "google_calendar_connection_user_id_fkey"
+        foreign key ("user_id") references "public"."user"("id") on delete cascade,
+    constraint "google_calendar_connection_status_check"
+        check ("status" in ('active', 'needs_reauth', 'disconnecting'))
+);
+
+alter table "public"."google_calendar_connection" owner to "postgres";
+
+create or replace function "public"."set_google_calendar_connection_updated_at"()
+returns trigger
+language plpgsql
+as $$
+begin
+    new."updated_at" = now();
+    return new;
+end;
+$$;
+
+alter function "public"."set_google_calendar_connection_updated_at"() owner to "postgres";
+
+create or replace trigger "set_google_calendar_connection_updated_at_trigger"
+before update on "public"."google_calendar_connection"
+for each row execute function "public"."set_google_calendar_connection_updated_at"();
+
+-- DB-stored OAuth CSRF state (the qb_state model, in its own table because
+-- no connection row exists yet at connect time, and because the mobile
+-- in-app-browser flow completes on a sessionless server callback where a
+-- cookie-based state check is impossible). The callback accepts a state only
+-- when younger than 15 minutes and deletes it on use; the connect route
+-- clears the user's stale rows when issuing a new one.
+create table if not exists "public"."google_calendar_oauth_state" (
+    "state" uuid default gen_random_uuid() not null,
+    "created_at" timestamp with time zone default now() not null,
+    "company_id" uuid not null,
+    "user_id" uuid not null,
+    constraint "google_calendar_oauth_state_pkey" primary key ("state"),
+    constraint "google_calendar_oauth_state_company_id_fkey"
+        foreign key ("company_id") references "public"."company"("id") on delete cascade,
+    constraint "google_calendar_oauth_state_user_id_fkey"
+        foreign key ("user_id") references "public"."user"("id") on delete cascade
+);
+
+alter table "public"."google_calendar_oauth_state" owner to "postgres";

package/dist/dist/migrations/20260731011416_google_calendar_connection_rls.sql

@@ -0,0 +1,23 @@
+-- Google Calendar connections are accessed only by authenticated server
+-- routes using the service role, matching the Bing/Facebook Ads posture. The
+-- browser and mobile app get no direct table access; the encrypted refresh
+-- token in particular must never be readable client-side. Clients read
+-- connection state through /api/google-calendar/status.
+alter table "public"."google_calendar_connection" enable row level security;
+alter table "public"."google_calendar_oauth_state" enable row level security;
+
+revoke all on table "public"."google_calendar_connection" from public;
+revoke all on table "public"."google_calendar_connection" from "anon";
+revoke all on table "public"."google_calendar_connection" from "authenticated";
+
+revoke all on table "public"."google_calendar_oauth_state" from public;
+revoke all on table "public"."google_calendar_oauth_state" from "anon";
+revoke all on table "public"."google_calendar_oauth_state" from "authenticated";
+
+grant all on table "public"."google_calendar_connection" to "service_role";
+grant all on table "public"."google_calendar_oauth_state" to "service_role";
+
+revoke all on function "public"."set_google_calendar_connection_updated_at"() from public;
+revoke all on function "public"."set_google_calendar_connection_updated_at"() from "anon";
+revoke all on function "public"."set_google_calendar_connection_updated_at"() from "authenticated";
+grant execute on function "public"."set_google_calendar_connection_updated_at"() to "service_role";

package/dist/dist/migrations/20260731011417_create_google_calendar_sync.sql

@@ -0,0 +1,157 @@
+-- Google Calendar sync bookkeeping: the event map (Autopilot entity →
+-- mirrored Google event ids, per connection) and the per-(user, entity) task
+-- queue. The fan-out pass in autopilot-web (webhook-outbox-cron) converts
+-- job.*/event.*/estimate.* outbound_events into at most one PENDING task per
+-- (connected user, entity); /api/google-calendar/sync-cron claims due tasks
+-- via claim_gcal_sync_tasks, recomputes what that user should see, diffs it
+-- against google_calendar_event_map, and patches the user's primary Google
+-- calendar. Tasks are self-contained (no FK to outbound_event) so the outbox
+-- retention purge never has to consider calendar state.
+
+-- One row per mirrored Google event. entity_id is always the PARENT id
+-- (job.id / event.id / estimate.id) — never job_schedule.id, because editing
+-- a job deletes and re-creates its schedule rows with fresh uuids (see
+-- reminder_dispatch), so a multi-block job simply maps to several rows with
+-- the same entity_id. start_time/end_time/content_hash record what was last
+-- pushed to Google: the times give the diff a stable pairing order and let
+-- the worker leave past events frozen (the mirror is future-only), and the
+-- hash lets it skip no-op patches.
+create table if not exists "public"."google_calendar_event_map" (
+    "id" uuid default gen_random_uuid() not null,
+    "created_at" timestamp with time zone default now() not null,
+    "company_id" uuid not null,
+    "connection_id" uuid not null,
+    "user_id" uuid not null,
+    "entity_type" text not null,
+    "entity_id" uuid not null,
+    "google_event_id" text not null,
+    "start_time" timestamp with time zone not null,
+    "end_time" timestamp with time zone not null,
+    "content_hash" text not null,
+    constraint "google_calendar_event_map_pkey" primary key ("id"),
+    constraint "google_calendar_event_map_google_event_key"
+        unique ("connection_id", "entity_type", "entity_id", "google_event_id"),
+    constraint "google_calendar_event_map_connection_id_fkey"
+        foreign key ("connection_id") references "public"."google_calendar_connection"("id") on delete cascade,
+    constraint "google_calendar_event_map_company_id_fkey"
+        foreign key ("company_id") references "public"."company"("id") on delete cascade,
+    constraint "google_calendar_event_map_entity_type_check"
+        check ("entity_type" in ('job', 'event', 'estimate'))
+);
+
+alter table "public"."google_calendar_event_map" owner to "postgres";
+
+-- reconcileEntity reads by entity, purge/reconcileAll page by connection
+create index if not exists "google_calendar_event_map_entity_idx"
+    on "public"."google_calendar_event_map" ("connection_id", "entity_type", "entity_id");
+
+create index if not exists "google_calendar_event_map_company_idx"
+    on "public"."google_calendar_event_map" ("company_id");
+
+-- entity_type 'reconcile_all' (full rebuild: initial backfill after connect,
+-- re-enable catch-up, nightly drift/role-change safety net) and 'purge'
+-- (disconnect cleanup) address a CONNECTION, so their entity_id is the
+-- google_calendar_connection id; cursor lets those long runs resume across
+-- worker time budgets.
+create table if not exists "public"."google_calendar_sync_task" (
+    "id" uuid default gen_random_uuid() not null,
+    "created_at" timestamp with time zone default now() not null,
+    "company_id" uuid not null,
+    "user_id" uuid not null,
+    "entity_type" text not null,
+    "entity_id" uuid not null,
+    -- informational: newest event that (re)enqueued this task. Deliberately
+    -- NO foreign key — outbound_event rows are purged after 90 days and a
+    -- dangling debug pointer is fine.
+    "trigger_event_id" uuid,
+    "cursor" jsonb,
+    "status" text default 'pending' 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,
+    "last_error" text,
+    constraint "google_calendar_sync_task_pkey" primary key ("id"),
+    constraint "google_calendar_sync_task_company_id_fkey"
+        foreign key ("company_id") references "public"."company"("id") on delete cascade,
+    constraint "google_calendar_sync_task_entity_type_check"
+        check ("entity_type" in ('job', 'event', 'estimate', 'reconcile_all', 'purge')),
+    -- pending:    waiting for next_attempt_at
+    -- processing: claimed by a worker run (stuck rows swept back to pending)
+    -- done:       reconciled into Google Calendar
+    -- skipped:    connection missing/paused/needs_reauth, or the company's
+    --             google_calendar entitlement lapsed, at process time
+    -- dead:       exhausted retries; kept for inspection
+    constraint "google_calendar_sync_task_status_check"
+        check ("status" in ('pending', 'processing', 'done', 'skipped', 'dead'))
+);
+
+alter table "public"."google_calendar_sync_task" owner to "postgres";
+
+-- At most ONE pending task per (user, entity): any burst of events while a
+-- task is pending collapses into it (the consumer re-reads state at process
+-- time, so intermediate events are pure duplicates). A task already claimed
+-- ('processing') does NOT block a new pending task — a write that lands
+-- mid-flight must trigger another sync afterwards. user_id (not company_id)
+-- leads the key because the same entity fans out to every connected user in
+-- the company.
+create unique index if not exists "google_calendar_sync_task_pending_entity_key"
+    on "public"."google_calendar_sync_task" ("user_id", "entity_type", "entity_id")
+    where "status" = 'pending';
+
+create index if not exists "google_calendar_sync_task_due_idx"
+    on "public"."google_calendar_sync_task" ("next_attempt_at")
+    where "status" = 'pending';
+
+-- FK support for the company cascade + failure-surfacing queries
+create index if not exists "google_calendar_sync_task_company_idx"
+    on "public"."google_calendar_sync_task" ("company_id", "created_at");
+
+-- Fan-out enqueue. An RPC because ON CONFLICT against a partial unique index
+-- needs the WHERE clause in the arbiter, which supabase-js upsert cannot
+-- express. tasks: [{company_id, user_id, entity_type, entity_id,
+-- trigger_event_id}]
+create or replace function "public"."enqueue_gcal_sync_tasks"("tasks" jsonb)
+returns integer
+language "sql"
+security definer
+set search_path = 'public'
+as $$
+  with ins as (
+    insert into google_calendar_sync_task (company_id, user_id, entity_type, entity_id, trigger_event_id)
+    select distinct
+      (t ->> 'company_id')::uuid,
+      (t ->> 'user_id')::uuid,
+      t ->> 'entity_type',
+      (t ->> 'entity_id')::uuid,
+      (t ->> 'trigger_event_id')::uuid
+    from jsonb_array_elements(tasks) as t
+    on conflict ("user_id", "entity_type", "entity_id")
+      where "status" = 'pending'
+      do nothing
+    returning 1
+  )
+  select count(*)::integer from ins;
+$$;
+
+-- Atomic claim, mirroring claim_qb_sync_tasks (SKIP LOCKED is not
+-- expressible through supabase-js; overlapping cron runs must never
+-- double-sync).
+create or replace function "public"."claim_gcal_sync_tasks"("batch_size" integer)
+returns setof "public"."google_calendar_sync_task"
+language "sql"
+security definer
+set search_path = 'public'
+as $$
+  update google_calendar_sync_task set
+    status = 'processing',
+    attempt_count = attempt_count + 1,
+    last_attempt_at = now()
+  where id in (
+    select id from google_calendar_sync_task
+    where status = 'pending' and next_attempt_at <= now()
+    order by next_attempt_at
+    limit least(batch_size, 1000)
+    for update skip locked
+  )
+  returning *;
+$$;