@fayz-ai/db 0.11.0 → 0.13.0

package/canonical-schema.json

@@ -0,0 +1,49 @@
+{
+  "$comment": "The canonical schema (#279, ADR 0022). ONE schema on every cluster: the spine plus every plugin that has passed the capability gate. The pool profiles in cli/pool-profiles/ stop deciding what a cluster HAS and become activation defaults — what a new tenant of that industry gets turned on, which is configuration and lives in the database (ADR 0023, migration 150). What varies per cluster is data, never DDL. A plugin joins `plugins` below when its gate is green; until then it is in `pending`, with the reason, and it exists in no cluster at all.",
+  "version": 1,
+  "plugins": [
+    {
+      "id": "financial",
+      "dir": "plugins/plugin-financial/src/migrations",
+      "gate": "capability",
+      "$note": "core-A. In three of the four live pools already."
+    },
+    {
+      "id": "inventory",
+      "dir": "plugins/plugin-inventory/src/migrations",
+      "gate": "capability",
+      "$note": "core-A. Sole writer of the stock archetype since #276."
+    },
+    {
+      "id": "tasks",
+      "dir": "plugins/plugin-tasks/src/migrations",
+      "gate": "enforced",
+      "$note": "The only plugin at ENFORCED — the reference implementation."
+    }
+  ],
+  "pending": [
+    { "id": "agenda", "reason": "Owns the species of the Compromisso archetype; the Google Calendar integration inside it has to come out as an addon first (#285's rule, ADR 0024)." },
+    { "id": "crm", "reason": "Installed in three pools; capability gate not green (seed + capability tests missing)." },
+    { "id": "forms", "reason": "Creates public.documents, which the base owns since 152 — the guarded CREATE has to go (#282)." },
+    { "id": "marketing", "reason": "Capability gate not green." },
+    { "id": "menu", "reason": "Nine tables of its own and no capability suite yet." },
+    { "id": "shop", "reason": "Its data lives in packages/shop, not in the plugin, and it still keeps a second stock book (#276's remaining half)." },
+    { "id": "courses", "reason": "Its data lives in packages/courses, not in the plugin (#285)." },
+    { "id": "conversations", "reason": "Capability gate not green." },
+    { "id": "automations", "reason": "Creates public.event_log, which the base owns; the copy is a guarded no-op that should go." },
+    { "id": "blog", "reason": "Capability gate not green." },
+    { "id": "reputation", "reason": "Capability gate not green." },
+    { "id": "scribe", "reason": "Capability gate not green." },
+    { "id": "banking-br", "reason": "Addon of financial; capability gate not green." },
+    { "id": "admin", "reason": "No data of its own — the base absorbed what it was for (#274 rule 1)." },
+    { "id": "auth", "reason": "No data of its own — same." },
+    { "id": "orders", "reason": "The Venda is a base archetype; nothing is left for a plugin to own." },
+    { "id": "dashboard", "reason": "A mechanism other plugins feed; no capability suite yet." },
+    { "id": "reports", "reason": "Same." },
+    { "id": "payments", "reason": "Never built." },
+    { "id": "sites", "reason": "Never built." },
+    { "id": "linkinbio", "reason": "Never built." },
+    { "id": "tables", "reason": "Never built; will own the restaurant floor when it is." },
+    { "id": "agent-runtime", "reason": "A library, not a plugin — it is base (rodada 3 Q1)." }
+  ]
+}

package/migrations/010_migration_ledger.sql

@@ -33,4 +33,14 @@ ALTER TABLE public._migrations ENABLE ROW LEVEL SECURITY;
 -- service_role (which bypasses RLS anyway). No policies = no anon/authenticated access.
 REVOKE ALL ON public._migrations FROM anon, authenticated;
 GRANT ALL ON public._migrations TO service_role;
-GRANT USAGE, SELECT ON SEQUENCE public._migrations_id_seq TO service_role;
+-- The sequence, WHATEVER IT IS CALLED. A legacy pool whose table was renamed
+-- ahead of 012 still owns fayz_migration_ledger_id_seq, and naming the new one
+-- here would stop the chain twelve files before the migration that renames it.
+-- pg_get_serial_sequence asks the column instead of guessing.
+DO $$
+DECLARE v_seq text := pg_get_serial_sequence('public._migrations', 'id');
+BEGIN
+  IF v_seq IS NOT NULL THEN
+    EXECUTE format('GRANT USAGE, SELECT ON SEQUENCE %s TO service_role', v_seq);
+  END IF;
+END $$;

package/migrations/037_sync_tick_one_at_a_time.sql

@@ -0,0 +1,256 @@
+-- ============================================================================
+-- 037_sync_tick_one_at_a_time.sql — a connection with a dispatch in flight is
+-- not due.
+--
+-- 033 selects what to dispatch by ONE test: `next_attempt_at <= now()`. It never
+-- asks whether the previous dispatch came back. In the ordinary case that is
+-- invisible — the advance pushes the row a whole interval into the future in the
+-- same statement that dispatches it, so nothing is due again for an hour.
+--
+-- It stops being invisible the moment anything else writes `next_attempt_at`.
+-- The shop's wake trigger (packages/shop 0064) sets it to `now()` whenever an
+-- order, a customer or a product changes — which is exactly what a catalogue
+-- pull DOES, by the thousand, while it is still running. Measured on the
+-- ecommerce pool: bling-sync dispatched, pulled, wrote products, each write
+-- moved its own next attempt to now(), the next tick dispatched it again on top
+-- of itself, and the merchant's history filled with an hourly connector running
+-- every sixty seconds. The cadence was never wrong; nothing enforced it.
+--
+-- ── The guard ────────────────────────────────────────────────────────────────
+-- `last_run_id IS NOT NULL` already means "dispatched, no verdict yet" — the
+-- fold and the reaper both key off it. This file makes the selection honour the
+-- same fact: one dispatch per connection per kind at a time, and the reaper
+-- (timeout_seconds) is what ends it if a function never answers. A wake that
+-- lands mid-run is not lost, it is served by the tick after the verdict.
+--
+-- This is a ceiling nobody could opt out of, which is the point: rate limits,
+-- the provider's daily quota and the connector's own cursor all assume its
+-- previous call finished. `max_per_tick` bounds a connector across connections;
+-- nothing bounded ONE connection against itself.
+--
+-- ── And the orphan ───────────────────────────────────────────────────────────
+-- A guard on a pointer needs the pointer to be honest. If the run a schedule
+-- points at no longer exists, the fold cannot fold it and the reaper cannot reap
+-- it, and under the new guard that connection would never be dispatched again.
+-- Cleared before the fold, so a vanished run costs one tick instead of forever.
+--
+-- CREATE OR REPLACE of plg_sync_tick, and nothing else: no table, no grant, no
+-- cron job changes. Idempotent, and safe to re-run — `fayz db apply` re-applies
+-- a file whose checksum moved.
+-- ============================================================================
+
+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;
+
+  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;
+
+  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;
+
+  -- ── orphan ────────────────────────────────────────────────────────────────
+  -- Before anything reads `last_run_id` as "in flight": a pointer at a run that
+  -- no longer exists is not a dispatch in flight, it is a dead end that would
+  -- park this connection permanently.
+  UPDATE public.plg_sync_schedule s
+     SET last_run_id = NULL
+   WHERE s.kind = p_kind
+     AND s.last_run_id IS NOT NULL
+     AND NOT EXISTS (SELECT 1 FROM public.plg_sync_runs r WHERE r.id = s.last_run_id);
+
+  -- ── 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 ──────────────────────────────────────────────────────────────────
+  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 ────────────────────────────────────────────────────────────────
+  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
+       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()
+               -- THE GUARD. Due is not enough: a connection whose last dispatch
+               -- has no verdict is already being served. Cleared by the fold on
+               -- a verdict, or by the reaper at timeout_seconds.
+               AND s2.last_run_id IS NULL
+             ORDER BY s2.next_attempt_at
+             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
+           AND c.status IN ('connected', 'error')
+      ) ranked
+     WHERE ranked.rn <= ranked.max_per_tick
+  LOOP
+    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',
+            '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
+      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
+      BEGIN
+        v_expires := (v_row.provider_state ->> 'expiresAt')::timestamptz;
+      EXCEPTION WHEN OTHERS THEN
+        v_expires := NULL;
+      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;
+
+    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$;
+
+COMMENT ON FUNCTION public.plg_sync_tick(text) IS
+  'One tick of the sync clock: clear orphaned pointers, reap dead dispatches, '
+  'fold verdicts into backoff, enrol new connections with a deterministic '
+  'offset, dispatch what is due AND has no dispatch in flight, 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.';

package/migrations/038_onboarding_responses.sql

@@ -0,0 +1,103 @@
+-- ============================================================================
+-- 038 — plg_onboarding_responses: what the owner told us while creating the
+-- workspace, and tenant_slug_available: can this handle still be taken.
+--
+-- The setup wizard asks things no table has a column for — whether they already
+-- run another system, how many chairs, how they hear about us — and the answers
+-- are worth keeping BECAUSE they are not settings: they are how we decide what
+-- to configure for this merchant and what kind of merchant they are.
+--
+-- The answers live in ONE jsonb keyed by question id, not in typed columns. That
+-- is the point: the questionnaire gets reworded every time we learn something
+-- about a vertical, and rewording must never be a migration. The two things we
+-- will actually filter and group by — the vertical and where they came from —
+-- are lifted out as columns, because those are the queries we know we want.
+--
+-- One row per completed run. Nothing is written before the tenant exists: the
+-- wizard holds its draft in localStorage until the org is created, so a fully
+-- abandoned flow leaves no orphan rows to reconcile.
+--
+-- Idempotent.
+-- ============================================================================
+
+CREATE TABLE IF NOT EXISTS public.plg_onboarding_responses (
+  id            uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+
+  tenant_id     uuid NOT NULL REFERENCES public.tenants(id) ON DELETE CASCADE,
+  -- Who answered. Not the same as the tenant owner forever — an owner can be
+  -- transferred, and it stays true that THIS account filled the form.
+  user_id       uuid NOT NULL REFERENCES auth.users(id) ON DELETE CASCADE,
+
+  -- Which questionnaire, and which revision of it. Answers from flow_version 1
+  -- are not comparable to version 3 once questions are dropped or rescaled, and
+  -- the stamp is what lets a report say so instead of silently averaging both.
+  flow_id       text NOT NULL,
+  flow_version  integer NOT NULL DEFAULT 1,
+
+  -- Copied from the tenant at answer time on purpose: a merchant who later
+  -- switches vertical must not retro-relabel the answers they gave as a salon.
+  vertical_id   text,
+  -- Where the flow was opened from: first workspace after signup, or an extra
+  -- one from the switcher. Same questions, very different intent.
+  source        text CHECK (source IS NULL OR source IN ('signup', 'switcher')),
+  -- Lifted out of `answers` because acquisition is the one question we will
+  -- group by across every tenant, and reaching into jsonb for it every time is
+  -- how a "how did they find us" report ends up not being written.
+  heard_from    text,
+
+  -- { "<question id>": <answer> }. Scalars for single choice, arrays for multi.
+  answers       jsonb NOT NULL DEFAULT '{}'::jsonb,
+
+  created_at    timestamptz NOT NULL DEFAULT now()
+);
+
+-- The tenant's own answers, newest first — the read the admin does.
+CREATE INDEX IF NOT EXISTS plg_onboarding_responses_tenant
+  ON public.plg_onboarding_responses (tenant_id, created_at DESC);
+-- The cross-tenant read: "what did restaurants say", "where did they come from".
+CREATE INDEX IF NOT EXISTS plg_onboarding_responses_segment
+  ON public.plg_onboarding_responses (vertical_id, heard_from);
+
+-- ---------------------------------------------------------------------------
+-- RLS. 011 closed `anon` on new public tables but not `authenticated`, which is
+-- still born with the full grant — here that would be every tenant reading every
+-- other tenant's answers. Stripped first, granted back deliberately.
+-- ---------------------------------------------------------------------------
+REVOKE ALL ON public.plg_onboarding_responses FROM anon, authenticated;
+
+ALTER TABLE public.plg_onboarding_responses ENABLE ROW LEVEL SECURITY;
+
+-- No UPDATE, no DELETE: this is a record of what someone said at a moment, and
+-- an answer that can be rewritten later is not evidence of anything.
+GRANT SELECT, INSERT ON public.plg_onboarding_responses TO authenticated;
+
+DROP POLICY IF EXISTS plg_onboarding_responses_member_read ON public.plg_onboarding_responses;
+CREATE POLICY plg_onboarding_responses_member_read ON public.plg_onboarding_responses
+  FOR SELECT TO authenticated
+  USING (tenant_id IN (SELECT public.user_tenant_ids()));
+
+DROP POLICY IF EXISTS plg_onboarding_responses_member_insert ON public.plg_onboarding_responses;
+CREATE POLICY plg_onboarding_responses_member_insert ON public.plg_onboarding_responses
+  FOR INSERT TO authenticated
+  WITH CHECK (tenant_id IN (SELECT public.user_tenant_ids()) AND user_id = auth.uid());
+
+-- ---------------------------------------------------------------------------
+-- tenant_slug_available — is this handle free?
+--
+-- `tenants.slug` is UNIQUE, and RLS keeps a signed-in user from reading tenants
+-- they do not belong to. Without this the wizard cannot tell someone their
+-- handle is taken until the final submit fails, four questions after they chose
+-- it. SECURITY DEFINER, returning only a boolean: it answers "is it free", never
+-- "who has it".
+-- ---------------------------------------------------------------------------
+CREATE OR REPLACE FUNCTION public.tenant_slug_available(p_slug text)
+RETURNS boolean
+LANGUAGE sql STABLE SECURITY DEFINER
+SET search_path = public, pg_temp
+AS $$
+  SELECT p_slug ~ '^[a-z0-9][a-z0-9-]{1,38}[a-z0-9]$'
+     AND NOT EXISTS (SELECT 1 FROM public.tenants t WHERE t.slug = lower(p_slug));
+$$;
+
+REVOKE ALL ON FUNCTION public.tenant_slug_available(text) FROM PUBLIC, anon;
+GRANT EXECUTE ON FUNCTION public.tenant_slug_available(text) TO authenticated, service_role;