@fayz-ai/db 0.10.0 → 0.11.0

package/migrations/033_sync_schedule.sql

@@ -0,0 +1,651 @@
+-- ============================================================================
+-- 033_sync_schedule.sql — the clock. One, generic, per connection.
+--
+-- Until this file nothing woke a connector. `SyncTrigger` has carried
+-- `'scheduled'` since 029, `rateLimit` and `firstLoad` are declared on every
+-- ConnectorDefinition, cursors are typed and asserted in the bench — and the
+-- only use of the word `scheduled` in the codebase was a default value for a log
+-- field. A merchant authorised Bling, closed the browser, and nothing ever
+-- pulled the catalogue.
+--
+-- ── Why every mirroring connector needs this, not only the ones without push ──
+-- Webhook is best-effort. The endpoint is down, the watch channel expires, the
+-- provider gives up after N retries, the network eats one. With only a webhook,
+-- ONE missed delivery is permanent silent divergence: the mirror is wrong and
+-- nobody finds out until a customer is sold stock that does not exist.
+--
+-- The pull is not an alternative to the webhook. It is what makes the webhook
+-- safe to trust. Push changes the FREQUENCY this has to run at; it never
+-- changes whether it has to run. Google Calendar survives today by accident.
+--
+-- ── Why the clock is here and not in the platform ─────────────────────────────
+-- The inverse symmetry of FAY-1388. The credential lives in the platform
+-- because that is where it is audited. Execution lives in the pool because that
+-- is where the edge function and `plg_sync_runs` already are, and because a
+-- mirror must not stop diverging-and-repairing when fayz is down. A platform
+-- job would make every tenant's freshness depend on one control plane's uptime.
+--
+-- ── Two jobs, both generic, neither belonging to any connector ────────────────
+--   reconcile  wake the connector to read from its cursor, apply, advance.
+--   renew      renew the provider-side subscription before it expires (Google's
+--              watch channel, Bling's webhook registration).
+-- A third, `prune`, retires the note 029 left on plg_prune_sync_runs — "no pool
+-- runs pg_cron, so the caller is the sync ingress". A pool runs pg_cron now.
+--
+-- ── ORDERING ─────────────────────────────────────────────────────────────────
+-- This file REQUIRES the connector spine: it references public.plg_connections
+-- and public.plg_sync_runs, so it must be applied AFTER 029 (and, for the
+-- pruner comment, after that same file). It does NOT touch 030/031/032. Four of
+-- the seven pools (agency, restaurant, dentist, creators) have no spine at all
+-- today; on those, `fayz db apply` reaches 029 before 033 in file order and the
+-- requirement is satisfied by the ordering alone. Applying 033 to a pool with no
+-- 029 fails loudly at the first CREATE — which is the correct outcome, not a
+-- case to be guarded away: a clock with nothing to wake is a bug, not a state.
+--
+-- Additive and idempotent throughout: every statement is IF NOT EXISTS, CREATE
+-- OR REPLACE, or a guarded DO. `fayz db apply` re-runs a file whose checksum
+-- moved, so it must be safe twice.
+-- ============================================================================
+
+-- ── §0  provider_state: declared by FAY-1388, never built ────────────────────
+-- FAY-1405 says the subscription expiry "lives in plg_connections.provider_state
+-- (FAY-1388)". It does not: nothing in this repository has ever created that
+-- column. It is added here because the renewal job cannot exist without it.
+--
+-- What belongs in it: what the PROVIDER knows about this connection and we only
+-- mirror — the watch channel id and its expiry, the registered webhook id, the
+-- resource id an unsubscribe needs. What does not: anything the tenant chose
+-- (that is `settings`), anything about resume position (`cursors`), and above
+-- all any credential — 029 and 032 both turn on there being no secret in this
+-- table, and the channel token of a watch is not an exception worth making.
+--
+-- IT IS TENANT-WRITABLE, and that is deliberate rather than overlooked: 029
+-- grants `authenticated` UPDATE on the whole table, and a column-level revoke on
+-- top of a table-level grant is a no-op in Postgres. The renewal job therefore
+-- treats `expiresAt` as a HINT and floors it (§4, `floor_seconds`) — a tenant who
+-- writes an expiry one second in the future gets one renewal per floor, not a
+-- loop that eats the pool's share of the provider's quota.
+ALTER TABLE public.plg_connections
+  ADD COLUMN IF NOT EXISTS provider_state jsonb NOT NULL DEFAULT '{}'::jsonb;
+
+COMMENT ON COLUMN public.plg_connections.provider_state IS
+  'What the PROVIDER knows about this connection and we only mirror: watch '
+  'channel id and expiry (`expiresAt`, ISO 8601), registered webhook id, '
+  'resource id. Not settings, not cursors, and never a credential. Written '
+  'server-side; the scheduler reads `expiresAt` as a hint and floors it.';
+
+-- ── §1  extensions ───────────────────────────────────────────────────────────
+-- Guarded one at a time so a pool that has one and not the other still gets it,
+-- and so this file applies on a bare Postgres (the migration bench) instead of
+-- aborting the chain. A pool missing either degrades to "nothing is dispatched
+-- and every attempt says why" (§4), never to a broken migration.
+DO $do$
+BEGIN
+  BEGIN
+    EXECUTE 'CREATE EXTENSION IF NOT EXISTS pg_net WITH SCHEMA extensions';
+  EXCEPTION WHEN OTHERS THEN
+    RAISE WARNING 'pg_net could not be installed (%) — the clock will file every attempt as an error until it is', SQLERRM;
+  END;
+  BEGIN
+    -- No SCHEMA clause: Supabase ships a control file that pins pg_cron to
+    -- pg_catalog, and naming a schema there fails.
+    EXECUTE 'CREATE EXTENSION IF NOT EXISTS pg_cron';
+  EXCEPTION WHEN OTHERS THEN
+    RAISE WARNING 'pg_cron could not be installed (%) — NOTHING WILL WAKE A CONNECTOR on this pool', SQLERRM;
+  END;
+END
+$do$;
+
+-- ── §2  the registry: how a connector declares a cadence ─────────────────────
+-- One row per (connector, kind). This is the ONLY place a connector says how
+-- often it needs waking, and it says it in SQL — shipped by the connector's own
+-- migration, next to the tables it already ships.
+--
+-- WHY NOT A FIELD ON ConnectorDefinition. Because nothing would read it. The
+-- clock runs inside Postgres with no view of a TypeScript manifest, and there is
+-- no manifest→pool projection in this repository. A declared field nothing
+-- consumes is prose that writes the future in the present; when that projection
+-- exists, this table is its target and the connector's migration stops being
+-- hand-written. Until then the declaration lives where the reader is.
+--
+-- `function_name` is CHECKed to a slug, not merely validated in the register
+-- function: it is concatenated onto the pool's functions base URL, and a
+-- constraint is what stops a row containing `../` from ever existing, however
+-- it was inserted.
+CREATE TABLE IF NOT EXISTS public.plg_connector_schedules (
+  connector_id     text    NOT NULL,
+  kind             text    NOT NULL CHECK (kind IN ('reconcile', 'renew')),
+  -- The edge function to wake, and the `action` inside its body. Two fields
+  -- because one function serves both kinds and several actions.
+  function_name    text    NOT NULL CHECK (function_name ~ '^[a-z0-9][a-z0-9_-]{0,62}$'),
+  action           text    NOT NULL CHECK (action ~ '^[a-z][a-z0-9_]{0,62}$'),
+  -- The cadence. Floored at 60s because the clock ticks once a minute; anything
+  -- smaller is a number that lies to whoever reads it.
+  interval_seconds integer NOT NULL CHECK (interval_seconds >= 60),
+  -- The spread. Each connection gets a deterministic offset in [0, jitter) so a
+  -- thousand connections enrolled in the same second do not come due together,
+  -- and do not re-converge after the first run.
+  jitter_seconds   integer NOT NULL DEFAULT 60 CHECK (jitter_seconds >= 0),
+  -- The hard ceiling on dispatches per tick, per connector. This is what makes
+  -- a cold start drain instead of stampede: a pool where every connection is due
+  -- at once still issues at most this many calls a minute.
+  max_per_tick     integer NOT NULL DEFAULT 25 CHECK (max_per_tick BETWEEN 1 AND 500),
+  -- The fastest this connector may EVER be woken, whatever any other input says.
+  -- The renewal job reads a tenant-writable expiry; this is what makes that safe.
+  floor_seconds    integer NOT NULL DEFAULT 300 CHECK (floor_seconds >= 60),
+  -- Renewal only: how long before `provider_state.expiresAt` to renew. A watch
+  -- renewed at the last second is a watch that expires during a retry.
+  lead_seconds     integer NOT NULL DEFAULT 86400 CHECK (lead_seconds >= 0),
+  -- After this, a run with no verdict is declared dead (§4, the reaper).
+  timeout_seconds  integer NOT NULL DEFAULT 900 CHECK (timeout_seconds >= 60),
+  enabled          boolean NOT NULL DEFAULT true,
+  created_at       timestamptz NOT NULL DEFAULT now(),
+  updated_at       timestamptz NOT NULL DEFAULT now(),
+  PRIMARY KEY (connector_id, kind)
+);
+
+COMMENT ON TABLE public.plg_connector_schedules IS
+  'How often each connector needs waking, and which edge function + action to '
+  'wake. Written by the connector''s own migration through '
+  'plg_register_connector_schedule. Granted to no client role: it decides how '
+  'much of a provider''s quota the whole pool spends.';
+
+-- ── §3  the clock's own bookkeeping ──────────────────────────────────────────
+-- One row per (connection, kind). NOT a second history — plg_sync_runs is the
+-- history and stays the only one. This holds the single question the selection
+-- asks ("when is this one next due?") so that question is an index range scan
+-- over the DUE rows rather than a per-connection lookup over every connection in
+-- the pool. That is the difference between cheap at a thousand connections and
+-- a per-minute scan that grows with the pool.
+--
+-- It is also why "due" is not computed from plg_connections.last_sync_at:
+-- `authenticated` may UPDATE that column, so a due-test built on it is a due-test
+-- the tenant can drive. Everything the clock decides on lives either here (the
+-- clock writes it) or in plg_sync_runs (029 grants the app no write at all).
+CREATE TABLE IF NOT EXISTS public.plg_sync_schedule (
+  connection_id   uuid NOT NULL REFERENCES public.plg_connections(id) ON DELETE CASCADE,
+  kind            text NOT NULL CHECK (kind IN ('reconcile', 'renew')),
+  next_attempt_at timestamptz NOT NULL DEFAULT now(),
+  last_attempt_at timestamptz,
+  -- The run this connection was last dispatched with, until it gets a verdict.
+  -- Non-NULL means "in flight": the fold and the reaper both key off it.
+  last_run_id     uuid,
+  -- Consecutive failures, for the backoff. Reset by the fold on any run that
+  -- came back success or partial.
+  failures        integer NOT NULL DEFAULT 0,
+  PRIMARY KEY (connection_id, kind)
+);
+
+CREATE INDEX IF NOT EXISTS idx_plg_sync_schedule_due
+  ON public.plg_sync_schedule (kind, next_attempt_at);
+
+-- Small and only ever read by the fold/reaper, but without it those two do a
+-- seq scan on every tick of a pool with a thousand idle connections.
+CREATE INDEX IF NOT EXISTS idx_plg_sync_schedule_inflight
+  ON public.plg_sync_schedule (last_run_id)
+  WHERE last_run_id IS NOT NULL;
+
+COMMENT ON TABLE public.plg_sync_schedule IS
+  'The clock''s bookkeeping: when each connection is next due, what is in '
+  'flight, how many consecutive failures. Not a history — plg_sync_runs is. '
+  'Rows are enrolled lazily by plg_sync_tick, with a deterministic offset so a '
+  'cold start spreads instead of stampeding.';
+
+-- ── §4  registration ─────────────────────────────────────────────────────────
+-- Upsert, so a connector's migration re-applied (or its cadence changed in a
+-- later migration) converges instead of erroring.
+CREATE OR REPLACE FUNCTION public.plg_register_connector_schedule(
+  p_connector_id     text,
+  p_kind             text,
+  p_function_name    text,
+  p_action           text,
+  p_interval_seconds integer,
+  p_jitter_seconds   integer DEFAULT NULL,
+  p_max_per_tick     integer DEFAULT 25,
+  p_floor_seconds    integer DEFAULT 300,
+  p_lead_seconds     integer DEFAULT 86400,
+  p_timeout_seconds  integer DEFAULT 900,
+  p_enabled          boolean DEFAULT true
+)
+RETURNS void
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = public
+AS $fn$
+DECLARE
+  -- A quarter of the cadence by default: enough to break a cohort apart, small
+  -- enough that "every 15 minutes" is still true to within a rounding a merchant
+  -- would not notice.
+  v_jitter integer := COALESCE(p_jitter_seconds, GREATEST(p_interval_seconds / 4, 1));
+BEGIN
+  INSERT INTO public.plg_connector_schedules AS s
+    (connector_id, kind, function_name, action, interval_seconds, jitter_seconds,
+     max_per_tick, floor_seconds, lead_seconds, timeout_seconds, enabled)
+  VALUES
+    (p_connector_id, p_kind, p_function_name, p_action, p_interval_seconds, v_jitter,
+     p_max_per_tick, p_floor_seconds, p_lead_seconds, p_timeout_seconds, p_enabled)
+  ON CONFLICT (connector_id, kind) DO UPDATE SET
+    function_name    = EXCLUDED.function_name,
+    action           = EXCLUDED.action,
+    interval_seconds = EXCLUDED.interval_seconds,
+    jitter_seconds   = EXCLUDED.jitter_seconds,
+    max_per_tick     = EXCLUDED.max_per_tick,
+    floor_seconds    = EXCLUDED.floor_seconds,
+    lead_seconds     = EXCLUDED.lead_seconds,
+    timeout_seconds  = EXCLUDED.timeout_seconds,
+    enabled          = EXCLUDED.enabled,
+    updated_at       = now();
+END;
+$fn$;
+
+-- ── §5  the endpoint, in Vault ───────────────────────────────────────────────
+-- The same shape the Google Calendar outbound trigger has run since 2026-07-28
+-- (plugin-agenda .../005_outbound_vault_delivery.sql): the credential is
+-- encrypted at rest, outside pg_dump's plaintext, readable only by a definer
+-- function, and it authorises exactly one thing — calling this pool's own edge
+-- functions. Losing it does not hand anyone a tenant's data.
+--
+-- Emphatically NOT the service-role key. 005's header spells out why that was
+-- an unrestricted read/write over every tenant of the cluster sitting in
+-- pg_db_role_setting in plain text. The clock never needs a tenant identity: the
+-- tenant is resolved from the connection row and travels in the BODY, the same
+-- discipline plg_claim_effect follows. The header proves only "not a browser".
+--
+-- No secret is created here — nothing in this repository may contain one. The
+-- operator calls this once per pool.
+CREATE OR REPLACE FUNCTION public.plg_set_scheduler_endpoint(
+  p_functions_base_url text,
+  p_secret             text
+)
+RETURNS void
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = public
+AS $fn$
+DECLARE
+  v_id uuid;
+BEGIN
+  IF COALESCE(p_functions_base_url, '') = '' OR COALESCE(p_secret, '') = '' THEN
+    RAISE EXCEPTION 'both the functions base url and the scheduler secret are required';
+  END IF;
+  IF p_functions_base_url !~ '^https://' THEN
+    -- The bearer travels on this request. A plaintext scheme would put it on the
+    -- wire; refusing is the only place that can be caught before it happens.
+    RAISE EXCEPTION 'the functions base url must be https';
+  END IF;
+
+  -- Replace, never accumulate — 032's rule. A rotated secret that leaves the old
+  -- one decryptable in the vault is not a rotation.
+  SELECT id INTO v_id FROM vault.secrets WHERE name = 'fayz_functions_url';
+  IF v_id IS NULL THEN
+    PERFORM vault.create_secret(rtrim(p_functions_base_url, '/'), 'fayz_functions_url', 'fayz pool edge functions base url');
+  ELSE
+    PERFORM vault.update_secret(v_id, rtrim(p_functions_base_url, '/'));
+  END IF;
+
+  SELECT id INTO v_id FROM vault.secrets WHERE name = 'fayz_scheduler_secret';
+  IF v_id IS NULL THEN
+    PERFORM vault.create_secret(p_secret, 'fayz_scheduler_secret', 'fayz sync scheduler bearer');
+  ELSE
+    PERFORM vault.update_secret(v_id, p_secret);
+  END IF;
+END;
+$fn$;
+
+-- ── §6  the tick ─────────────────────────────────────────────────────────────
+-- One function, two kinds, four phases. Runs once a minute under pg_cron as
+-- `postgres`; SECURITY DEFINER so it can write plg_sync_runs, which 029 grants
+-- no application role a write on.
+--
+--   reap     a dispatch that never came back is a failure, not a silence.
+--   fold     a settled run becomes backoff (or clears it).
+--   enroll   connections with a registered schedule and no state row.
+--   dispatch open a run, post, advance.
+--
+-- THE ORDER MATTERS: reap before fold means a dead run is folded in the same
+-- tick it is declared dead, so a connector whose function is down backs off
+-- immediately instead of being re-dispatched every minute for the timeout.
+--
+-- A RUN ROW FOR EVERY ATTEMPT, INCLUDING ONE THAT NEVER REACHED THE FUNCTION.
+-- Missing pg_net, no Vault secret, a rejected post: each files a run with
+-- status 'error' and a sentence saying which. A schedule that silently does
+-- nothing is indistinguishable from one that works, and this is the whole
+-- difference.
+CREATE OR REPLACE FUNCTION public.plg_sync_tick(p_kind text)
+RETURNS integer
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = public, extensions, net, vault
+AS $fn$
+DECLARE
+  v_base       text;
+  v_secret     text;
+  v_have_net   boolean;
+  v_row        record;
+  v_run_id     uuid;
+  v_next       timestamptz;
+  v_expires    timestamptz;
+  v_offset     integer;
+  v_dispatched integer := 0;
+  v_reason     text;
+BEGIN
+  IF p_kind NOT IN ('reconcile', 'renew') THEN
+    RAISE EXCEPTION 'plg_sync_tick: unknown kind %', p_kind;
+  END IF;
+
+  -- A tick that outlives its minute must not overlap the next one: two ticks
+  -- would both see the same due rows and dispatch each twice. Skipping is right
+  -- — the work is not lost, it is due a minute later.
+  IF NOT pg_try_advisory_xact_lock(hashtext('plg_sync_tick:' || p_kind)) THEN
+    RETURN 0;
+  END IF;
+
+  v_have_net := to_regprocedure('net.http_post(text, jsonb, jsonb, jsonb, integer)') IS NOT NULL;
+
+  -- Wrapped: a pool without the vault extension must degrade to "every attempt
+  -- says it is not configured", not abort the tick.
+  BEGIN
+    SELECT decrypted_secret INTO v_base
+      FROM vault.decrypted_secrets WHERE name = 'fayz_functions_url'
+      ORDER BY created_at DESC LIMIT 1;
+    SELECT decrypted_secret INTO v_secret
+      FROM vault.decrypted_secrets WHERE name = 'fayz_scheduler_secret'
+      ORDER BY created_at DESC LIMIT 1;
+  EXCEPTION WHEN OTHERS THEN
+    v_base := NULL;
+    v_secret := NULL;
+  END;
+
+  -- ── reap ──────────────────────────────────────────────────────────────────
+  UPDATE public.plg_sync_runs r
+     SET status      = 'error',
+         finished_at = now(),
+         error       = COALESCE(r.error, 'the connector function returned no verdict within the schedule timeout')
+    FROM public.plg_sync_schedule s
+    JOIN public.plg_connections c ON c.id = s.connection_id
+    JOIN public.plg_connector_schedules d
+      ON d.connector_id = c.connector_id AND d.kind = s.kind
+   WHERE s.kind = p_kind
+     AND r.id = s.last_run_id
+     AND r.status = 'running'
+     AND r.started_at < now() - make_interval(secs => d.timeout_seconds);
+
+  -- ── fold ──────────────────────────────────────────────────────────────────
+  -- Exponential backoff on consecutive failures, capped at a day. The cap is not
+  -- decoration: without it a connection that failed twenty times would next be
+  -- tried after the heat death of the merchant's patience, and a provider that
+  -- came back would never be noticed.
+  UPDATE public.plg_sync_schedule s
+     SET failures = CASE WHEN r.status IN ('success', 'partial') THEN 0 ELSE s.failures + 1 END,
+         last_run_id = NULL,
+         next_attempt_at = CASE
+           WHEN r.status IN ('success', 'partial') THEN s.next_attempt_at
+           ELSE GREATEST(
+                  s.next_attempt_at,
+                  now() + make_interval(secs => LEAST(
+                    d.interval_seconds::bigint * (2 ^ LEAST(s.failures + 1, 6))::bigint,
+                    86400)::double precision)
+                )
+         END
+    FROM public.plg_sync_runs r,
+         public.plg_connections c,
+         public.plg_connector_schedules d
+   WHERE s.kind = p_kind
+     AND r.id = s.last_run_id
+     AND r.finished_at IS NOT NULL
+     AND c.id = s.connection_id
+     AND d.connector_id = c.connector_id
+     AND d.kind = s.kind;
+
+  -- ── enroll ────────────────────────────────────────────────────────────────
+  -- Lazy, so neither the connect flow nor a backfill script has to know the
+  -- clock exists — a connection made before this migration and one made a minute
+  -- from now enter the same way.
+  --
+  -- THE OFFSET IS THE ANTI-STAMPEDE, and it is applied HERE because this is the
+  -- one moment a whole pool can enter the schedule at once: the first tick after
+  -- this file is applied enrolls every existing connection in the same second.
+  -- Without the offset all of them would be due at the same instant forever
+  -- after, since each advance adds the same interval to the same base.
+  -- Deterministic from the connection id, so it survives a re-enrollment.
+  INSERT INTO public.plg_sync_schedule (connection_id, kind, next_attempt_at)
+  SELECT q.id, p_kind,
+         now() + make_interval(secs => mod(abs(hashtext(q.id::text)::bigint), GREATEST(q.jitter_seconds, 1))::double precision)
+    FROM (
+      SELECT c.id, d.jitter_seconds
+        FROM public.plg_connections c
+        JOIN public.plg_connector_schedules d
+          ON d.connector_id = c.connector_id AND d.kind = p_kind AND d.enabled
+        LEFT JOIN public.plg_sync_schedule s
+          ON s.connection_id = c.id AND s.kind = p_kind
+       WHERE s.connection_id IS NULL
+         AND c.active
+       -- Bounded so the first tick on a large pool does not enrol ten thousand
+       -- rows in one transaction; the rest arrive on the next tick.
+       LIMIT 500
+    ) q
+  ON CONFLICT (connection_id, kind) DO NOTHING;
+
+  -- ── dispatch ──────────────────────────────────────────────────────────────
+  FOR v_row IN
+    SELECT *
+      FROM (
+        SELECT s.connection_id, s.failures, c.tenant_id, c.connector_id, c.provider_state,
+               d.function_name, d.action, d.interval_seconds, d.jitter_seconds,
+               d.floor_seconds, d.lead_seconds, d.timeout_seconds, d.max_per_tick,
+               row_number() OVER (PARTITION BY c.connector_id ORDER BY s.next_attempt_at, s.connection_id) AS rn
+          FROM (
+            SELECT s2.*
+              FROM public.plg_sync_schedule s2
+             WHERE s2.kind = p_kind AND s2.next_attempt_at <= now()
+             ORDER BY s2.next_attempt_at
+             -- A ceiling on the work ONE tick can consider, independent of any
+             -- connector's max_per_tick. Ten thousand due rows must not become a
+             -- ten-thousand-row sort every minute.
+             LIMIT 2000
+          ) s
+          JOIN public.plg_connections c ON c.id = s.connection_id
+          JOIN public.plg_connector_schedules d
+            ON d.connector_id = c.connector_id AND d.kind = s.kind
+         WHERE d.enabled
+           AND c.active
+           -- 'pending' is "connected but not configured yet" — waking it just
+           -- files an error a minute. 'revoked' is the tenant saying stop.
+           AND c.status IN ('connected', 'error')
+      ) ranked
+     WHERE ranked.rn <= ranked.max_per_tick
+  LOOP
+    -- The run row is opened BEFORE the post, so a post that throws still leaves
+    -- an attempt on the record. tenant_id comes from the connection, never from
+    -- a caller — plg_claim_effect's discipline, for the same reason.
+    INSERT INTO public.plg_sync_runs
+      (tenant_id, connection_id, connector_id, direction, trigger_kind, status, stats)
+    VALUES
+      (v_row.tenant_id, v_row.connection_id, v_row.connector_id,
+       CASE WHEN p_kind = 'renew' THEN 'outbound' ELSE 'inbound' END,
+       'scheduled', 'running',
+       jsonb_build_object('schedule_kind', p_kind, 'attempt', v_row.failures + 1))
+    RETURNING id INTO v_run_id;
+
+    v_reason := NULL;
+    IF NOT v_have_net THEN
+      v_reason := 'pg_net is not installed on this pool, so the scheduler cannot call the connector function';
+    ELSIF COALESCE(v_base, '') = '' OR COALESCE(v_secret, '') = '' THEN
+      v_reason := 'the scheduler endpoint is not configured: run plg_set_scheduler_endpoint on this pool';
+    ELSE
+      BEGIN
+        PERFORM net.http_post(
+          url := v_base || '/' || v_row.function_name,
+          headers := jsonb_build_object(
+            'Content-Type', 'application/json',
+            -- Proves "not a browser" and nothing else. It is NOT an identity:
+            -- the tenant is in the body, resolved from the connection row.
+            'Authorization', 'Bearer ' || v_secret,
+            'X-Fayz-Scheduler', '1'
+          ),
+          body := jsonb_build_object(
+            'action', v_row.action,
+            'kind', p_kind,
+            'connectionId', v_row.connection_id,
+            'tenantId', v_row.tenant_id,
+            'connectorId', v_row.connector_id,
+            'runId', v_run_id,
+            'attempt', v_row.failures + 1,
+            'scheduledAt', to_char(now() AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS"Z"')
+          ),
+          timeout_milliseconds := v_row.timeout_seconds * 1000
+        );
+      EXCEPTION WHEN OTHERS THEN
+        v_reason := 'the scheduler could not post to the connector function: ' || SQLERRM;
+      END;
+    END IF;
+
+    IF v_reason IS NOT NULL THEN
+      -- Settled here rather than left to the reaper: this attempt provably never
+      -- left the database, so waiting out the timeout would only delay the
+      -- backoff and hide the reason.
+      UPDATE public.plg_sync_runs
+         SET status = 'error', error = v_reason, finished_at = now()
+       WHERE id = v_run_id;
+    END IF;
+
+    -- ── advance ─────────────────────────────────────────────────────────────
+    v_offset := mod(abs(hashtext(v_row.connection_id::text)::bigint),
+                    GREATEST(v_row.jitter_seconds, 1))::integer;
+    v_next := now() + make_interval(secs => (v_row.interval_seconds + v_offset)::double precision);
+
+    IF p_kind = 'renew' THEN
+      -- The expiry the provider gave us pulls the next attempt EARLIER, never
+      -- later: a watch that dies in an hour must not wait for a daily cadence.
+      BEGIN
+        v_expires := (v_row.provider_state ->> 'expiresAt')::timestamptz;
+      EXCEPTION WHEN OTHERS THEN
+        v_expires := NULL;   -- a malformed hint is no hint
+      END;
+      IF v_expires IS NOT NULL THEN
+        v_next := LEAST(v_next, v_expires - make_interval(secs => v_row.lead_seconds::double precision));
+      END IF;
+    END IF;
+
+    -- The floor, last and unconditional. provider_state is tenant-writable
+    -- (§0); this is the line that makes that harmless.
+    v_next := GREATEST(v_next, now() + make_interval(secs => v_row.floor_seconds::double precision));
+
+    UPDATE public.plg_sync_schedule
+       SET next_attempt_at = v_next,
+           last_attempt_at = now(),
+           last_run_id     = v_run_id
+     WHERE connection_id = v_row.connection_id AND kind = p_kind;
+
+    v_dispatched := v_dispatched + 1;
+  END LOOP;
+
+  RETURN v_dispatched;
+END;
+$fn$;
+
+-- ── §7  who may reach any of this ────────────────────────────────────────────
+-- 011 shut `anon` out of every new table in this schema and left `authenticated`
+-- born with the full set — the trap 029 and 032 both documented. Both new tables
+-- are stripped and nothing is granted back, and RLS with no policy makes the
+-- grant and the policy set agree, so "fixing the grant" alone reopens nothing.
+--
+-- Neither table is tenant data, and that is exactly why they are shut. A tenant
+-- who could write plg_connector_schedules would set interval_seconds to its
+-- floor for every tenant on the pool and spend the provider's shared quota; one
+-- who could write plg_sync_schedule would put itself first in a queue everyone
+-- shares. "Next sync at" is a legitimate thing for a panel to want — it can be
+-- served later by a definer function that returns one connection's row, not by
+-- opening the table.
+REVOKE ALL ON public.plg_connector_schedules FROM PUBLIC;
+REVOKE ALL ON public.plg_connector_schedules FROM anon, authenticated;
+REVOKE ALL ON public.plg_sync_schedule FROM PUBLIC;
+REVOKE ALL ON public.plg_sync_schedule FROM anon, authenticated;
+
+ALTER TABLE public.plg_connector_schedules ENABLE ROW LEVEL SECURITY;
+ALTER TABLE public.plg_sync_schedule       ENABLE ROW LEVEL SECURITY;
+
+-- PUBLIC first: EXECUTE on a new function is granted to PUBLIC by default, and
+-- revoking from anon/authenticated alone leaves it reachable through that.
+--
+-- plg_sync_tick is the sharpest of the three. Anyone who can call it can make
+-- the database issue a burst of authenticated calls to every connector function
+-- on the pool, on demand, as fast as they can loop — the stampede this whole
+-- file is built to prevent, handed to a browser.
+REVOKE ALL ON FUNCTION public.plg_sync_tick(text) FROM PUBLIC;
+REVOKE ALL ON FUNCTION public.plg_sync_tick(text) FROM anon, authenticated;
+GRANT EXECUTE ON FUNCTION public.plg_sync_tick(text) TO service_role;
+
+REVOKE ALL ON FUNCTION public.plg_register_connector_schedule(text, text, text, text, integer, integer, integer, integer, integer, integer, boolean) FROM PUBLIC;
+REVOKE ALL ON FUNCTION public.plg_register_connector_schedule(text, text, text, text, integer, integer, integer, integer, integer, integer, boolean) FROM anon, authenticated;
+GRANT EXECUTE ON FUNCTION public.plg_register_connector_schedule(text, text, text, text, integer, integer, integer, integer, integer, integer, boolean) TO service_role;
+
+REVOKE ALL ON FUNCTION public.plg_set_scheduler_endpoint(text, text) FROM PUBLIC;
+REVOKE ALL ON FUNCTION public.plg_set_scheduler_endpoint(text, text) FROM anon, authenticated;
+GRANT EXECUTE ON FUNCTION public.plg_set_scheduler_endpoint(text, text) TO service_role;
+
+COMMENT ON FUNCTION public.plg_sync_tick(text) IS
+  'One tick of the sync clock: reap dead dispatches, fold verdicts into backoff, '
+  'enrol new connections with a deterministic offset, dispatch what is due up to '
+  'max_per_tick per connector. Files a plg_sync_runs row for EVERY attempt, '
+  'including one that never reached the function. service_role and cron only.';
+COMMENT ON FUNCTION public.plg_register_connector_schedule(text, text, text, text, integer, integer, integer, integer, integer, integer, boolean) IS
+  'How a connector declares its cadence. Called from the connector''s own '
+  'migration; upsert, so re-applying converges.';
+COMMENT ON FUNCTION public.plg_set_scheduler_endpoint(text, text) IS
+  'Place the pool''s edge-functions base URL and the scheduler bearer in Vault. '
+  'Run once per pool by an operator; no secret is ever committed.';
+
+-- ── §8  cron, and who may not touch it ───────────────────────────────────────
+-- MEASURED, not assumed, on cluster-salon-br-01 and cluster-ecommerce-br-01:
+--
+--   schema cron          {supabase_admin=UC, postgres=U*}      -- no anon/authenticated
+--   cron.schedule        {=X/supabase_admin, ...}              -- EXECUTE to PUBLIC
+--   cron.unschedule      {=X/supabase_admin, ...}              -- EXECUTE to PUBLIC
+--   cron.job             {=r/supabase_admin, ...}              -- SELECT  to PUBLIC
+--   cron.job_run_details {=rd/supabase_admin, ...}             -- SELECT+DELETE to PUBLIC
+--
+-- So the ONLY thing standing between `authenticated` and rescheduling this pool's
+-- clock is USAGE on the `cron` schema, which Supabase does not grant. The
+-- function and table ACLs behind it are wide open, and every one of those objects
+-- is owned by `supabase_admin` — a migration running as `postgres` cannot revoke
+-- a grant it did not make, so this file does NOT pretend to close them. What it
+-- does instead is make the one line that matters a graded assertion
+-- (sync-schedule.regression.sql S8): the day anyone runs
+-- `GRANT USAGE ON SCHEMA cron TO authenticated` "for the dashboard", CI goes red.
+--
+-- Idempotent: cron.schedule upserts by job name.
+DO $do$
+BEGIN
+  IF to_regprocedure('cron.schedule(text, text, text)') IS NULL THEN
+    RAISE WARNING 'pg_cron is not available: the sync clock is NOT scheduled on this pool and no connector will be woken';
+    RETURN;
+  END IF;
+
+  -- Every minute. The per-connector cadence lives in the registry, not here:
+  -- a job per connector would put the connector's name in the platform's clock,
+  -- which is the coupling this file exists to avoid.
+  PERFORM cron.schedule('fayz_sync_reconcile', '* * * * *',
+                        $cmd$SELECT public.plg_sync_tick('reconcile')$cmd$);
+
+  -- Renewal windows are hours and days; a minute of granularity buys nothing and
+  -- costs a query. `lead_seconds` is what makes five minutes safe.
+  PERFORM cron.schedule('fayz_sync_renew', '*/5 * * * *',
+                        $cmd$SELECT public.plg_sync_tick('renew')$cmd$);
+
+  -- 029 shipped the pruner and wrote on it "no pool runs pg_cron, so the caller
+  -- is the sync ingress — it prunes the connection it just wrote". That was true
+  -- and is not any more; leaving retention to whoever happens to sync means a
+  -- connector that stops syncing keeps its rows forever.
+  PERFORM cron.schedule('fayz_sync_prune', '17 4 * * *',
+                        $cmd$SELECT public.plg_prune_sync_runs()$cmd$);
+EXCEPTION WHEN OTHERS THEN
+  RAISE WARNING 'could not schedule the fayz sync clock (%) — no connector will be woken on this pool', SQLERRM;
+END
+$do$;
+
+-- The note 029 left on the pruner — "No pool runs pg_cron, so the caller is the
+-- sync ingress" — is now wrong. Restated rather than edited in place: 029 is
+-- applied on every pool and editing an applied migration is a ledger hard stop.
+COMMENT ON FUNCTION public.plg_prune_sync_runs(integer, integer) IS
+  'Retention for plg_sync_runs: deletes runs that are both outside the newest N of their connection and older than the window. Scheduled nightly by 033 (cron job fayz_sync_prune); the sync ingress may still call it directly.';