@fayz-ai/db 0.11.0 → 0.12.0

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;

package/migrations/039_unit_tree.sql

@@ -0,0 +1,270 @@
+-- ============================================================================
+-- 039_unit_tree.sql — the org tree `locations` always was, finally readable.
+--
+-- WHAT A UNIT IS. A franchise brand is ONE tenant with N units: "Alem do Olhar"
+-- has 15 of them. The unit is not a new noun — it is `public.locations`, which
+-- 001_core created with `is_headquarters` and `kind DEFAULT 'branch'` and which
+-- nothing has ever read for authorization. Two kinds and only two:
+--
+--     kind='region'  groups units          kind='branch'  IS the unit
+--
+-- A ROOM IS NOT A UNIT. Sala, cadeira, mesa, consultório are *service
+-- locations* — operational places that HAVE a unit — and they do not belong in
+-- this table; mixing "where the chair is" with "who may see the money" is how
+-- an authorization model stops being explainable. No room concept exists in the
+-- code today (`kind='room'`/`'zone'` appears in prose documentation and in no
+-- table and no screen), so there is nothing to migrate and the tree is exactly
+-- two levels deep.
+--
+-- WHAT THIS FILE DOES NOT DO. Nothing here changes what any query returns. It
+-- adds the tree, the bindings, the per-tenant switch and the five helper
+-- functions; 042 is the file that turns them into a boundary, and even that one
+-- is inert until a tenant sets `unit_scoping_enabled`.
+--
+-- IT ALSO REPAIRS `location_members`. That table has existed since 001_core
+-- with a SELECT policy and NOTHING else: no INSERT, no UPDATE, no DELETE, so no
+-- screen has ever been able to write a binding. It also has no index leading
+-- with `user_id`, which would make `user_unit_ids()` seq-scan it on every
+-- single query. Both are fixed here.
+--
+-- Additive and idempotent: safe to re-run, no-ops when already applied.
+-- ============================================================================
+
+-- ── The tree ────────────────────────────────────────────────────────────────
+ALTER TABLE public.locations
+  ADD COLUMN IF NOT EXISTS parent_id uuid,
+  ADD COLUMN IF NOT EXISTS code text;
+
+COMMENT ON COLUMN public.locations.parent_id IS
+  'Parent node of the org tree: a branch points at its region. Two levels only.';
+COMMENT ON COLUMN public.locations.code IS
+  'The unit code the franchise already uses on its own paperwork (e.g. "RJ-042").';
+
+-- A parent in ANOTHER tenant would be a cross-tenant edge inside the very
+-- structure that decides visibility. The composite FK makes it unrepresentable
+-- rather than merely discouraged — cheaper and more honest than a trigger.
+DO $$
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1 FROM pg_constraint WHERE conname = 'locations_id_tenant_uniq'
+  ) THEN
+    ALTER TABLE public.locations ADD CONSTRAINT locations_id_tenant_uniq UNIQUE (id, tenant_id);
+  END IF;
+
+  IF NOT EXISTS (
+    SELECT 1 FROM pg_constraint WHERE conname = 'locations_parent_same_tenant'
+  ) THEN
+    ALTER TABLE public.locations
+      ADD CONSTRAINT locations_parent_same_tenant
+      FOREIGN KEY (parent_id, tenant_id)
+      REFERENCES public.locations (id, tenant_id) ON DELETE SET NULL;
+  END IF;
+
+  -- Self-parenting is the one cycle a CHECK can catch. Deeper cycles are
+  -- survivable by construction: user_unit_ids() walks with UNION (which dedupes
+  -- and therefore terminates) plus a depth guard. NOT VALID so no live table is
+  -- scanned; new and updated rows are checked from here on.
+  IF NOT EXISTS (
+    SELECT 1 FROM pg_constraint WHERE conname = 'locations_no_self_parent'
+  ) THEN
+    ALTER TABLE public.locations
+      ADD CONSTRAINT locations_no_self_parent CHECK (parent_id IS DISTINCT FROM id) NOT VALID;
+  END IF;
+END $$;
+
+CREATE INDEX IF NOT EXISTS locations_parent_idx
+  ON public.locations (parent_id) WHERE parent_id IS NOT NULL;
+
+-- ── The bindings ────────────────────────────────────────────────────────────
+-- `tenant_id` denormalised so this table's own policies take the canonical
+-- shape instead of joining back through `locations` on every check.
+ALTER TABLE public.location_members
+  ADD COLUMN IF NOT EXISTS tenant_id uuid REFERENCES public.tenants(id) ON DELETE CASCADE;
+
+UPDATE public.location_members lm
+   SET tenant_id = l.tenant_id
+  FROM public.locations l
+ WHERE l.id = lm.location_id
+   AND lm.tenant_id IS DISTINCT FROM l.tenant_id;
+
+-- The column is derived, so deriving it is the trigger's job — a caller that
+-- has to remember to pass it will eventually not, and a binding with a NULL
+-- tenant is invisible to every policy below.
+CREATE OR REPLACE FUNCTION public.handle_location_member_tenant()
+RETURNS trigger
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = public, pg_temp
+AS $$
+BEGIN
+  SELECT l.tenant_id INTO NEW.tenant_id
+    FROM public.locations l WHERE l.id = NEW.location_id;
+  RETURN NEW;
+END;
+$$;
+
+REVOKE ALL ON FUNCTION public.handle_location_member_tenant() FROM public, anon;
+
+DROP TRIGGER IF EXISTS location_members_tenant ON public.location_members;
+CREATE TRIGGER location_members_tenant
+  BEFORE INSERT OR UPDATE OF location_id ON public.location_members
+  FOR EACH ROW EXECUTE FUNCTION public.handle_location_member_tenant();
+
+-- Without this index every RLS-evaluated call of user_unit_ids() seq-scans the
+-- table. 001_core's only index is UNIQUE(location_id, user_id) — wrong leading
+-- column for the one question this table is ever asked.
+CREATE INDEX IF NOT EXISTS location_members_user_idx
+  ON public.location_members (user_id, location_id);
+
+-- A binding with no role is the normal case: it says "you work here", and the
+-- role you already have in the org applies. A role here only ever ADDS.
+ALTER TABLE public.location_members ALTER COLUMN role DROP DEFAULT;
+
+COMMENT ON COLUMN public.location_members.role IS
+  'Additional role INSIDE this unit. Unions with the org role, never subtracts. NULL = no extra role.';
+
+-- ── The per-tenant switch ───────────────────────────────────────────────────
+-- A column and not a key in `tenants.settings`, following the precedent shop
+-- 0020 set with `storefront_strict_scope`: a security flag read inside a policy
+-- has to be cheap and indexable, and a jsonb extraction is neither.
+ALTER TABLE public.tenants
+  ADD COLUMN IF NOT EXISTS unit_scoping_enabled boolean NOT NULL DEFAULT false;
+
+COMMENT ON COLUMN public.tenants.unit_scoping_enabled IS
+  'Off by default. While false, every unit predicate in 042 short-circuits and this tenant behaves exactly as before.';
+
+-- ── Helpers ─────────────────────────────────────────────────────────────────
+-- Every one of these is zero-argument on purpose. A helper that takes the row's
+-- own column (is_tenant_admin(tenant_id) is the cautionary example) is
+-- correlated: RLS injects the predicate into securityQuals, where the planner
+-- never turns a sublink into a semijoin, so it becomes a SubPlan re-executed
+-- once PER ROW. Zero-argument helpers wrapped in `(SELECT …)` become one
+-- InitPlan per query, hashed, then a probe per row.
+--
+-- All are SECURITY DEFINER for the reason 023 spells out: they read the very
+-- tables whose policies will call them, and invoker semantics would recurse.
+
+-- The pool-level short circuit. On a pool where nobody uses units this returns
+-- false once per query and the whole predicate in 042 costs one boolean test
+-- per row — no hash build, because OR does not evaluate its later arms.
+CREATE OR REPLACE FUNCTION public.unit_scoping_active()
+RETURNS boolean
+LANGUAGE sql STABLE SECURITY DEFINER
+SET search_path = public, pg_temp
+AS $$
+  SELECT EXISTS (SELECT 1 FROM public.tenants WHERE unit_scoping_enabled);
+$$;
+
+CREATE OR REPLACE FUNCTION public.unit_scoped_tenants()
+RETURNS SETOF uuid
+LANGUAGE sql STABLE SECURITY DEFINER
+SET search_path = public, pg_temp
+AS $$
+  SELECT id FROM public.tenants WHERE unit_scoping_enabled;
+$$;
+
+-- The tenants where the caller may see everything regardless of unit. Mirrors
+-- is_tenant_admin's role set exactly (001_core:87) — divergence here would mean
+-- the settings screens and the row predicate disagree about who is an admin.
+CREATE OR REPLACE FUNCTION public.user_admin_tenant_ids()
+RETURNS SETOF uuid
+LANGUAGE sql STABLE SECURITY DEFINER
+SET search_path = public, pg_temp
+AS $$
+  SELECT tm.tenant_id
+    FROM public.tenant_members tm
+   WHERE tm.user_id = auth.uid()
+     AND tm.role IN ('owner', 'admin');
+$$;
+
+-- The units the caller reaches. A binding to a region reaches its branches;
+-- reach flows DOWN the tree and never up — a unit manager is not a regional.
+--
+-- Deliberately NOT tenant-aware: a user can belong to tenant A with units on
+-- and tenant B with units off, and one answer cannot serve both. The mode check
+-- lives in the predicate (042), where it is free.
+CREATE OR REPLACE FUNCTION public.user_unit_ids()
+RETURNS SETOF uuid
+LANGUAGE sql STABLE SECURITY DEFINER
+SET search_path = public, pg_temp
+AS $$
+  WITH RECURSIVE seed AS (
+    SELECT lm.location_id AS id, 0 AS depth
+      FROM public.location_members lm
+     WHERE lm.user_id = auth.uid()
+  ),
+  tree AS (
+    SELECT id, depth FROM seed
+    UNION                                -- UNION, not UNION ALL: dedupes, and
+    SELECT l.id, t.depth + 1             -- therefore terminates on a cycle
+      FROM public.locations l
+      JOIN tree t ON l.parent_id = t.id
+     WHERE t.depth < 8                   -- a policy must never be able to hang
+  )
+  SELECT id FROM tree;
+$$;
+
+-- The unit the browser says it is looking at, read from a request header the
+-- same way shop 0020 reads `x-fayz-store`. It NARROWS a write's default stamp;
+-- it never grants anything — 042 validates the stamped unit against
+-- user_unit_ids() in WITH CHECK. Swallows every parse failure for the reason
+-- 028 states: an RLS-adjacent function is not a place to raise.
+CREATE OR REPLACE FUNCTION public.requested_unit()
+RETURNS uuid
+LANGUAGE plpgsql STABLE
+SET search_path = public, pg_temp
+AS $$
+DECLARE v text;
+BEGIN
+  v := nullif(current_setting('request.headers', true), '')::json ->> 'x-fayz-unit';
+  RETURN nullif(v, '')::uuid;
+EXCEPTION WHEN OTHERS THEN
+  RETURN NULL;
+END;
+$$;
+
+GRANT EXECUTE ON FUNCTION public.unit_scoping_active()     TO authenticated, service_role;
+GRANT EXECUTE ON FUNCTION public.unit_scoped_tenants()     TO authenticated, service_role;
+GRANT EXECUTE ON FUNCTION public.user_admin_tenant_ids()   TO authenticated, service_role;
+GRANT EXECUTE ON FUNCTION public.user_unit_ids()           TO authenticated, service_role;
+GRANT EXECUTE ON FUNCTION public.requested_unit()          TO authenticated, service_role;
+
+-- ── Policies on the tree itself ─────────────────────────────────────────────
+-- `locations` and `location_members` are in 002's core_tables exclusion list,
+-- so they carry curated policies and no sweep will overwrite these.
+--
+-- RLS is re-enabled rather than assumed: 001_core enables it, but a pool built
+-- by hand (the ecommerce pool has tables the ledger never heard of) may not have
+-- run 001, and a policy on a table without RLS is decoration.
+ALTER TABLE public.locations ENABLE ROW LEVEL SECURITY;
+ALTER TABLE public.location_members ENABLE ROW LEVEL SECURITY;
+--
+-- The tree stays readable tenant-wide even under unit scoping, on purpose: the
+-- unit switcher, the "Unidade: Ipanema" label on a record and the reports
+-- breakdown all need to name a unit the reader may not have data in. A unit's
+-- NAME is not its data.
+DROP POLICY IF EXISTS "locations_select" ON public.locations;
+CREATE POLICY "locations_select" ON public.locations FOR SELECT TO authenticated
+  USING (tenant_id IN (SELECT public.user_tenant_ids()));
+
+DROP POLICY IF EXISTS "loc_members_select" ON public.location_members;
+CREATE POLICY "loc_members_select" ON public.location_members FOR SELECT TO authenticated
+  USING (tenant_id IN (SELECT public.user_tenant_ids()));
+
+-- The missing three quarters of the table. Only a tenant admin hands out
+-- access to a unit — the same bar `tenant_role_overrides` and `invitations`
+-- already set for who may change who can do what.
+DROP POLICY IF EXISTS "loc_members_insert" ON public.location_members;
+CREATE POLICY "loc_members_insert" ON public.location_members FOR INSERT TO authenticated
+  WITH CHECK (tenant_id IN (SELECT public.user_admin_tenant_ids()));
+
+DROP POLICY IF EXISTS "loc_members_update" ON public.location_members;
+CREATE POLICY "loc_members_update" ON public.location_members FOR UPDATE TO authenticated
+  USING (tenant_id IN (SELECT public.user_admin_tenant_ids()));
+
+DROP POLICY IF EXISTS "loc_members_delete" ON public.location_members;
+CREATE POLICY "loc_members_delete" ON public.location_members FOR DELETE TO authenticated
+  USING (tenant_id IN (SELECT public.user_admin_tenant_ids()));
+
+GRANT SELECT, INSERT, UPDATE, DELETE ON public.location_members TO authenticated;
+GRANT ALL ON public.location_members TO service_role;