@fayz-ai/db 0.8.0 → 0.8.3

package/migrations/002_rls_user_tenant_ids.sql

@@ -31,8 +31,9 @@ DECLARE
     -- 004 archetypes (self-governed via 004/006 policies)
     'people', 'categories', 'products', 'services', 'orders', 'order_items',
     'transactions', 'appointments', 'appointment_items', 'schedules',
-    -- core, non-API helper tables
-    'sequences', 'documents', 'fayz_migration_ledger'
+    -- core, non-API helper tables (both ledger names kept for pre/post-rename compat;
+    -- `_migrations` is also covered by the NOT LIKE '\_%' filter below)
+    'sequences', 'documents', 'fayz_migration_ledger', '_migrations'
   ];
 BEGIN
   FOR t IN

package/migrations/010_migration_ledger.sql

@@ -8,9 +8,15 @@
 -- service_role only: no anon/authenticated grants, RLS enabled with NO
 -- policies, so PostgREST (anon/authenticated) is deny-all. Only the service
 -- role (which bypasses RLS) — i.e. the runner — can read/write it.
+--
+-- Naming: the ledger is an internal, non-API table, so it uses the `_`-prefixed
+-- `public._migrations` name (excluded from the project_rls auto-policy pass by
+-- the `NOT LIKE '\_%'` filter). Legacy pools provisioned as `fayz_migration_ledger`
+-- are migrated by 012_rename_migration_ledger.sql (and by the runner's
+-- ensureLedger guard); fresh installs are born as `_migrations` here.
 -- ============================================================================
 
-CREATE TABLE IF NOT EXISTS public.fayz_migration_ledger (
+CREATE TABLE IF NOT EXISTS public._migrations (
   id bigserial PRIMARY KEY,
   plugin_id text NOT NULL,
   file_name text NOT NULL,
@@ -21,10 +27,10 @@ CREATE TABLE IF NOT EXISTS public.fayz_migration_ledger (
   UNIQUE(plugin_id, file_name)
 );
 
-ALTER TABLE public.fayz_migration_ledger ENABLE ROW LEVEL SECURITY;
+ALTER TABLE public._migrations ENABLE ROW LEVEL SECURITY;
 
 -- Deny-all through PostgREST: revoke any inherited grants, grant to nobody but
 -- service_role (which bypasses RLS anyway). No policies = no anon/authenticated access.
-REVOKE ALL ON public.fayz_migration_ledger FROM anon, authenticated;
-GRANT ALL ON public.fayz_migration_ledger TO service_role;
-GRANT USAGE, SELECT ON SEQUENCE public.fayz_migration_ledger_id_seq TO service_role;
+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;

package/migrations/012_rename_migration_ledger.sql

@@ -0,0 +1,61 @@
+-- ============================================================================
+-- 012_rename_migration_ledger.sql — rename the migration ledger onto the
+-- internal `_`-prefixed baseline name:
+--
+--   public.fayz_migration_ledger → public._migrations
+--
+-- Legacy-pool remediation ONLY: 010_migration_ledger.sql now creates `_migrations`
+-- directly, so fresh installs never reach a rename branch. The runner's
+-- ensureLedger (cli/src/lib/ledger.ts) performs the same guarded rename at the
+-- START of every apply, so on a real pool the ledger is already `_migrations`
+-- by the time this migration runs — this file is the declarative backstop.
+--
+-- Fully idempotent + guarded: each RENAME fires only when the old object exists
+-- and the new one does not. A table RENAME preserves the rows (the applied-file
+-- history MUST survive), plus RLS state, grants and constraints; re-assert the
+-- deny-all grants afterwards to keep the baseline explicit.
+-- ============================================================================
+
+DO $$
+BEGIN
+  -- Table (carries the applied-migration history — never drop + recreate).
+  IF to_regclass('public.fayz_migration_ledger') IS NOT NULL
+     AND to_regclass('public._migrations') IS NULL THEN
+    ALTER TABLE public.fayz_migration_ledger RENAME TO _migrations;
+  END IF;
+
+  -- bigserial owns fayz_migration_ledger_id_seq — a table rename does not move it.
+  IF to_regclass('public.fayz_migration_ledger_id_seq') IS NOT NULL
+     AND to_regclass('public._migrations_id_seq') IS NULL THEN
+    ALTER SEQUENCE public.fayz_migration_ledger_id_seq RENAME TO _migrations_id_seq;
+  END IF;
+
+  -- Named constraints are auto-named after the old table; rename for parity with
+  -- a fresh install. Guard on the new table existing so this is safe pre-rename.
+  IF to_regclass('public._migrations') IS NOT NULL THEN
+    IF EXISTS (SELECT 1 FROM pg_constraint
+               WHERE conname = 'fayz_migration_ledger_pkey'
+                 AND conrelid = 'public._migrations'::regclass) THEN
+      ALTER TABLE public._migrations RENAME CONSTRAINT fayz_migration_ledger_pkey TO _migrations_pkey;
+    END IF;
+    IF EXISTS (SELECT 1 FROM pg_constraint
+               WHERE conname = 'fayz_migration_ledger_plugin_id_file_name_key'
+                 AND conrelid = 'public._migrations'::regclass) THEN
+      ALTER TABLE public._migrations
+        RENAME CONSTRAINT fayz_migration_ledger_plugin_id_file_name_key
+        TO _migrations_plugin_id_file_name_key;
+    END IF;
+  END IF;
+END $$;
+
+-- Re-assert the deny-all posture (idempotent; RLS/grants survive a rename but the
+-- baseline keeps this explicit so a manually-created ledger converges too).
+DO $$
+BEGIN
+  IF to_regclass('public._migrations') IS NOT NULL THEN
+    EXECUTE 'ALTER TABLE public._migrations ENABLE ROW LEVEL SECURITY';
+    EXECUTE 'REVOKE ALL ON public._migrations FROM anon, authenticated';
+    EXECUTE 'GRANT ALL ON public._migrations TO service_role';
+    EXECUTE 'GRANT USAGE, SELECT ON SEQUENCE public._migrations_id_seq TO service_role';
+  END IF;
+END $$;

package/migrations/013_sequences_rls.sql

@@ -0,0 +1,22 @@
+-- ============================================================================
+-- 013_sequences_rls.sql — close the RLS drift on public.sequences.
+--
+-- public.sequences (the REC-/PAG- numbering counter, created by the financial
+-- plugin's 004_order_to_cash.sql) shipped WITHOUT row-level security on a set of
+-- pools. Baseline = RLS ON, deny-all (no policies), exactly like the salon pool:
+-- the table is written ONLY through the SECURITY DEFINER function
+-- public.next_sequence(), which runs as the table owner and so bypasses RLS.
+-- With RLS on and no policy, the PostgREST anon/authenticated surface is deny-all,
+-- so the counter can never be read or tampered with directly by a tenant.
+--
+-- Legacy-pool remediation: guarded so it is a no-op on pools that never enabled
+-- Payments (sequences absent) and idempotent on pools already at RLS ON. Fresh
+-- installs are born with RLS via the financial plugin's own 004_order_to_cash.sql.
+--
+-- NOTE: next_sequence() MUST be SECURITY DEFINER for the deny-all baseline to
+-- keep working — it is called directly via PostgREST RPC by authenticated users
+-- (plugins/plugin-financial/src/data/supabase.ts → createInvoice). That fix ships
+-- in the financial plugin migration alongside this one.
+-- ============================================================================
+
+ALTER TABLE IF EXISTS public.sequences ENABLE ROW LEVEL SECURITY;

package/migrations/014_plan_entitlements.sql

@@ -0,0 +1,28 @@
+-- ============================================================================
+-- 014_plan_entitlements.sql — plans carry machine-readable entitlements.
+--
+-- public.plans shipped with `features jsonb` as DISPLAY BULLETS only — nothing
+-- in the pool encodes what a plan actually gates. Server-side enforcement (the
+-- agent RPCs' role→plan→limit guard, and eventually RLS defense-in-depth)
+-- needs the SAME `{features: {id: bool}, limits: {key: number}}` structure the
+-- client resolves from `config.billing` (@fayz-ai/core PlanEntitlements; -1 =
+-- unlimited, absent feature = allowed).
+--
+-- Writer: the app's plan catalog is code (billing.ts) → synced into this table
+-- (transitionally by the app seed, then by the Fayz platform on
+-- `fayz manifest sync` — the manifest carries billing.plans verbatim).
+--
+-- `hidden` retires the "qa-free-test plans visible on SubscriptionPage" debt:
+-- QA/internal plans stay selectable by id but are never rendered.
+--
+-- Guarded + idempotent: no-op when the pool predates public.plans (legacy
+-- saas_core pools run their app-local mirror of this ALTER instead).
+-- ============================================================================
+
+DO $$
+BEGIN
+  IF to_regclass('public.plans') IS NOT NULL THEN
+    ALTER TABLE public.plans ADD COLUMN IF NOT EXISTS entitlements jsonb NOT NULL DEFAULT '{}'::jsonb;
+    ALTER TABLE public.plans ADD COLUMN IF NOT EXISTS hidden boolean NOT NULL DEFAULT false;
+  END IF;
+END $$;

package/migrations/015_agent_guard.sql

@@ -0,0 +1,108 @@
+-- ============================================================================
+-- 015_agent_guard.sql — the role→plan→limit gate for agent_* RPCs.
+--
+-- Every server-plane agent write RPC (agent_<domain>_<verb>) calls this FIRST.
+-- It is the SQL mirror of the shared TS engine (@fayz-ai/core/access
+-- resolveAccess/resolveLimit): role first (owner bypasses role, NOT plan;
+-- `manage` satisfies any action; tenant_role_overrides win over role grants),
+-- then plan feature gate (only explicit false denies), then the plan cap for
+-- p_limit_key (absent / -1 = unlimited). The RPC counts its own domain rows
+-- and passes p_used — the guard never runs dynamic SQL.
+--
+-- Returns NULL when allowed, or the AgentDenial jsonb mirror when denied:
+--   {"allowed":false,"reason":"role"|"plan"|"limit",
+--    "limit":{"key":..,"max":..,"used":..},"upgradeUrl":"/settings/subscription"}
+-- A parity test on the app side runs the same scenarios through the TS engine
+-- and through this function — divergence is a bug.
+--
+-- Permission ids use the `category.action` catalog form; grants live in
+-- role_permissions (+ per-tenant tenant_role_overrides with granted boolean).
+-- ============================================================================
+
+CREATE OR REPLACE FUNCTION public.agent_guard(
+  p_tenant_id uuid,
+  p_actor_user_id uuid,
+  p_feature text,
+  p_action text,
+  p_limit_key text DEFAULT NULL,
+  p_used integer DEFAULT NULL,
+  p_n integer DEFAULT 1
+) RETURNS jsonb
+LANGUAGE plpgsql STABLE SECURITY DEFINER
+SET search_path = public
+AS $$
+DECLARE
+  v_role text;
+  v_has boolean;
+  v_override boolean;
+  v_plan_id text;
+  v_ent jsonb;
+  v_feature_flag jsonb;
+  v_cap numeric;
+BEGIN
+  -- ── membership + role ────────────────────────────────────────────────────
+  SELECT tm.role INTO v_role
+  FROM tenant_members tm
+  WHERE tm.tenant_id = p_tenant_id AND tm.user_id = p_actor_user_id;
+  IF v_role IS NULL THEN
+    RETURN jsonb_build_object('allowed', false, 'reason', 'role',
+                              'upgradeUrl', '/settings/subscription');
+  END IF;
+
+  IF v_role <> 'owner' THEN
+    -- per-tenant override wins in BOTH directions (grant or deny)
+    SELECT tro.granted INTO v_override
+    FROM tenant_role_overrides tro
+    WHERE tro.tenant_id = p_tenant_id AND tro.role = v_role
+      AND tro.permission_id IN (p_feature || '.' || p_action, p_feature || '.manage')
+    ORDER BY (tro.permission_id = p_feature || '.' || p_action) DESC
+    LIMIT 1;
+
+    IF v_override IS NOT NULL THEN
+      v_has := v_override;
+    ELSE
+      SELECT EXISTS (
+        SELECT 1 FROM role_permissions rp
+        WHERE rp.role = v_role
+          AND rp.permission_id IN (p_feature || '.' || p_action, p_feature || '.manage')
+      ) INTO v_has;
+    END IF;
+
+    IF NOT v_has THEN
+      RETURN jsonb_build_object('allowed', false, 'reason', 'role',
+                                'upgradeUrl', '/settings/subscription');
+    END IF;
+  END IF;
+
+  -- ── plan feature gate (owner does NOT bypass) ────────────────────────────
+  SELECT t.plan INTO v_plan_id FROM tenants t WHERE t.id = p_tenant_id;
+  SELECT p.entitlements INTO v_ent FROM plans p WHERE p.id = v_plan_id;
+
+  IF v_ent IS NOT NULL THEN
+    v_feature_flag := v_ent->'features'->p_feature;
+    -- only an EXPLICIT false denies (additive plans — mirror isEntitledByPlan)
+    IF v_feature_flag IS NOT NULL AND v_feature_flag = to_jsonb(false) THEN
+      RETURN jsonb_build_object('allowed', false, 'reason', 'plan',
+                                'upgradeUrl', '/settings/subscription');
+    END IF;
+
+    -- ── plan cap (mirror resolveLimit: absent / -1 = unlimited) ────────────
+    IF p_limit_key IS NOT NULL AND p_used IS NOT NULL THEN
+      v_cap := (v_ent->'limits'->>p_limit_key)::numeric;
+      IF v_cap IS NOT NULL AND v_cap <> -1 AND (p_used + COALESCE(p_n, 1)) > v_cap THEN
+        RETURN jsonb_build_object('allowed', false, 'reason', 'limit',
+                                  'limit', jsonb_build_object('key', p_limit_key,
+                                                              'max', v_cap,
+                                                              'used', p_used),
+                                  'upgradeUrl', '/settings/subscription');
+      END IF;
+    END IF;
+  END IF;
+
+  RETURN NULL; -- allowed
+END;
+$$;
+
+REVOKE ALL ON FUNCTION public.agent_guard(uuid, uuid, text, text, text, integer, integer) FROM public;
+GRANT EXECUTE ON FUNCTION public.agent_guard(uuid, uuid, text, text, text, integer, integer)
+  TO authenticated, service_role;

package/migrations/016_agent_guard_actor.sql

@@ -0,0 +1,102 @@
+-- ============================================================================
+-- 016_agent_guard_actor.sql — the actor cannot be spoofed by a signed-in caller.
+--
+-- agent_* RPCs receive p_actor_user_id explicitly because the Fayz broker
+-- (service_role, no JWT) injects the verified actor server-side. But the same
+-- functions are EXECUTE-granted to `authenticated` so the surface can call
+-- them client-plane before S4 — and there, p_actor comes from the client. A
+-- signed-in user passing SOMEONE ELSE's id would borrow their role.
+--
+-- Rule added at the top of agent_guard (every write RPC's first call): when
+-- the caller carries a JWT identity (auth.uid() not null), p_actor MUST be
+-- that identity. Service-role/broker calls (auth.uid() null) are unaffected.
+-- New file rather than editing 015 — applied migrations are never edited
+-- (ledger rule); CREATE OR REPLACE supersedes the body.
+-- ============================================================================
+
+CREATE OR REPLACE FUNCTION public.agent_guard(
+  p_tenant_id uuid,
+  p_actor_user_id uuid,
+  p_feature text,
+  p_action text,
+  p_limit_key text DEFAULT NULL,
+  p_used integer DEFAULT NULL,
+  p_n integer DEFAULT 1
+) RETURNS jsonb
+LANGUAGE plpgsql STABLE SECURITY DEFINER
+SET search_path = public
+AS $$
+DECLARE
+  v_role text;
+  v_has boolean;
+  v_override boolean;
+  v_plan_id text;
+  v_ent jsonb;
+  v_feature_flag jsonb;
+  v_cap numeric;
+BEGIN
+  -- ── actor integrity: a JWT caller can only act as themselves ─────────────
+  IF auth.uid() IS NOT NULL AND auth.uid() IS DISTINCT FROM p_actor_user_id THEN
+    RETURN jsonb_build_object('allowed', false, 'reason', 'role',
+                              'upgradeUrl', '/settings/subscription');
+  END IF;
+
+  -- ── membership + role ────────────────────────────────────────────────────
+  SELECT tm.role INTO v_role
+  FROM tenant_members tm
+  WHERE tm.tenant_id = p_tenant_id AND tm.user_id = p_actor_user_id;
+  IF v_role IS NULL THEN
+    RETURN jsonb_build_object('allowed', false, 'reason', 'role',
+                              'upgradeUrl', '/settings/subscription');
+  END IF;
+
+  IF v_role <> 'owner' THEN
+    SELECT tro.granted INTO v_override
+    FROM tenant_role_overrides tro
+    WHERE tro.tenant_id = p_tenant_id AND tro.role = v_role
+      AND tro.permission_id IN (p_feature || '.' || p_action, p_feature || '.manage')
+    ORDER BY (tro.permission_id = p_feature || '.' || p_action) DESC
+    LIMIT 1;
+
+    IF v_override IS NOT NULL THEN
+      v_has := v_override;
+    ELSE
+      SELECT EXISTS (
+        SELECT 1 FROM role_permissions rp
+        WHERE rp.role = v_role
+          AND rp.permission_id IN (p_feature || '.' || p_action, p_feature || '.manage')
+      ) INTO v_has;
+    END IF;
+
+    IF NOT v_has THEN
+      RETURN jsonb_build_object('allowed', false, 'reason', 'role',
+                                'upgradeUrl', '/settings/subscription');
+    END IF;
+  END IF;
+
+  -- ── plan feature gate (owner does NOT bypass) ────────────────────────────
+  SELECT t.plan INTO v_plan_id FROM tenants t WHERE t.id = p_tenant_id;
+  SELECT p.entitlements INTO v_ent FROM plans p WHERE p.id = v_plan_id;
+
+  IF v_ent IS NOT NULL THEN
+    v_feature_flag := v_ent->'features'->p_feature;
+    IF v_feature_flag IS NOT NULL AND v_feature_flag = to_jsonb(false) THEN
+      RETURN jsonb_build_object('allowed', false, 'reason', 'plan',
+                                'upgradeUrl', '/settings/subscription');
+    END IF;
+
+    IF p_limit_key IS NOT NULL AND p_used IS NOT NULL THEN
+      v_cap := (v_ent->'limits'->>p_limit_key)::numeric;
+      IF v_cap IS NOT NULL AND v_cap <> -1 AND (p_used + COALESCE(p_n, 1)) > v_cap THEN
+        RETURN jsonb_build_object('allowed', false, 'reason', 'limit',
+                                  'limit', jsonb_build_object('key', p_limit_key,
+                                                              'max', v_cap,
+                                                              'used', p_used),
+                                  'upgradeUrl', '/settings/subscription');
+      END IF;
+    END IF;
+  END IF;
+
+  RETURN NULL;
+END;
+$$;

package/migrations/017_core_addresses.sql

@@ -0,0 +1,115 @@
+-- ============================================================================
+-- 017_core_addresses.sql — public.addresses becomes part of the SPINE.
+-- ----------------------------------------------------------------------------
+-- The address book was already declared "core" by @fayz-ai/shop's 0012
+-- ("move address/payment concepts OUT of the plugin, into core"), but the SQL
+-- physically shipped inside the shop package. Consequence, live today: any app
+-- that does not install @fayz-ai/shop has no addresses table, while the person
+-- archetype's "Endereços" tab (packages/saas AddressesTab) queries it
+-- unconditionally — beauty-saas, dentist-saas, agency-os and every other
+-- non-shop vertical render "Could not find the table 'public.addresses'".
+--
+-- An address is not e-commerce. It is where a client is delivered to, where a
+-- supplier is collected from, where a staff member lives, where a unit of the
+-- business sits. It belongs beside `people` and `locations`, in the spine.
+--
+-- Replay safety (this file runs on pools that already have the table, via shop
+-- 0012, AND on pools that have never seen it):
+--   • CREATE TABLE IF NOT EXISTS + ADD COLUMN IF NOT EXISTS — additive only
+--   • the owner_type CHECK is dropped and rebuilt WIDER, never narrower, so a
+--     pool holding 'shop_customer' rows keeps them valid
+--   • no DROP of data, no DROP of the shop's own policies
+-- Ordering: the spine runs BEFORE plugin migrations (cli buildMigrationPlan
+-- ① spine → ④ plugin), so on a fresh shop pool this file creates the table and
+-- shop 0012's own CREATE ... IF NOT EXISTS degrades to a no-op.
+--
+-- `owner_type` stays text rather than a FK because the owner is polymorphic:
+-- a core `people` row, a `locations` row, the tenant itself, or — until the
+-- shop's customer table is folded into `people` — a plg_shop_customers row.
+-- ============================================================================
+
+-- ----------------------------------------------------------------------------
+-- 1. The table
+-- ----------------------------------------------------------------------------
+CREATE TABLE IF NOT EXISTS public.addresses (
+  id           uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  tenant_id    uuid NOT NULL,
+  owner_type   text NOT NULL DEFAULT 'person',
+  owner_id     uuid,
+  kind         text NOT NULL DEFAULT 'both',
+  label        text,          -- "Casa", "Trabalho", "Depósito"
+  recipient    text,          -- quem recebe, se não for o próprio dono
+  phone        text,
+  postal_code  text NOT NULL, -- CEP
+  street       text NOT NULL,
+  number       text,
+  complement   text,
+  district     text,          -- bairro
+  city         text NOT NULL,
+  state        text NOT NULL, -- UF
+  country      text NOT NULL DEFAULT 'BR',
+  is_default   boolean NOT NULL DEFAULT false,
+  metadata     jsonb NOT NULL DEFAULT '{}',
+  created_at   timestamptz NOT NULL DEFAULT now(),
+  updated_at   timestamptz NOT NULL DEFAULT now()
+);
+
+COMMENT ON TABLE public.addresses IS
+  'Core address book. N addresses per owner (person, location, tenant), tenant-scoped. Owned by @fayz-ai/db — plugins read it, none of them own it.';
+
+-- Pools provisioned by shop 0012 predate `metadata`/'both' defaults; add what
+-- is missing rather than assuming the 0012 shape.
+ALTER TABLE public.addresses
+  ADD COLUMN IF NOT EXISTS owner_type text NOT NULL DEFAULT 'person',
+  ADD COLUMN IF NOT EXISTS owner_id   uuid,
+  ADD COLUMN IF NOT EXISTS kind       text NOT NULL DEFAULT 'both',
+  ADD COLUMN IF NOT EXISTS label      text,
+  ADD COLUMN IF NOT EXISTS recipient  text,
+  ADD COLUMN IF NOT EXISTS phone      text,
+  ADD COLUMN IF NOT EXISTS number     text,
+  ADD COLUMN IF NOT EXISTS complement text,
+  ADD COLUMN IF NOT EXISTS district   text,
+  ADD COLUMN IF NOT EXISTS metadata   jsonb NOT NULL DEFAULT '{}';
+
+-- ----------------------------------------------------------------------------
+-- 2. Constraints — rebuilt WIDER than shop 0012's.
+--    'staff' and 'partner' are person kinds and already covered by 'person';
+--    what 0012 lacked is nothing — this only re-asserts the same set so a pool
+--    that never ran 0012 gets it, and a pool that did is left unchanged.
+-- ----------------------------------------------------------------------------
+ALTER TABLE public.addresses DROP CONSTRAINT IF EXISTS addresses_owner_type_check;
+ALTER TABLE public.addresses
+  ADD CONSTRAINT addresses_owner_type_check
+  CHECK (owner_type IN ('person', 'shop_customer', 'location', 'tenant'));
+
+ALTER TABLE public.addresses DROP CONSTRAINT IF EXISTS addresses_kind_check;
+ALTER TABLE public.addresses
+  ADD CONSTRAINT addresses_kind_check
+  CHECK (kind IN ('shipping', 'billing', 'both'));
+
+CREATE INDEX IF NOT EXISTS addresses_tenant_idx ON public.addresses (tenant_id);
+CREATE INDEX IF NOT EXISTS addresses_owner_idx  ON public.addresses (owner_type, owner_id);
+-- One default per owner per kind, enforced here rather than trusting every
+-- caller to clear the previous one.
+CREATE UNIQUE INDEX IF NOT EXISTS addresses_one_default_idx
+  ON public.addresses (owner_type, owner_id, kind) WHERE is_default;
+
+DROP TRIGGER IF EXISTS addresses_updated_at ON public.addresses;
+CREATE TRIGGER addresses_updated_at BEFORE UPDATE ON public.addresses
+  FOR EACH ROW EXECUTE FUNCTION public.handle_updated_at();
+
+-- ----------------------------------------------------------------------------
+-- 3. RLS — tenant members manage their tenant's rows. Anon gets nothing.
+--    The shop's extra `addresses_self_read` policy (a signed-in storefront
+--    customer reading their own rows) is left untouched: it is additive, and
+--    shop 0012 runs after this file.
+-- ----------------------------------------------------------------------------
+ALTER TABLE public.addresses ENABLE ROW LEVEL SECURITY;
+
+DROP POLICY IF EXISTS "addresses_member_all" ON public.addresses;
+CREATE POLICY "addresses_member_all" ON public.addresses FOR ALL TO authenticated
+  USING (tenant_id IN (SELECT public.user_tenant_ids()))
+  WITH CHECK (tenant_id IN (SELECT public.user_tenant_ids()));
+
+GRANT ALL ON public.addresses TO authenticated, service_role;
+REVOKE ALL ON public.addresses FROM anon;

package/migrations/018_global_search.sql

@@ -0,0 +1,482 @@
+-- ============================================================================
+-- 018_global_search.sql — ONE indexed lookup for "find me anything".
+-- ----------------------------------------------------------------------------
+-- The command palette and the agent's findAnything both answered the same
+-- question — "which record is this text?" — by asking every entity separately:
+-- N round-trips of `column ILIKE '%term%'`, accent-sensitive, single-word only,
+-- and unindexable (every one of them a sequential scan). It is correct at
+-- fixture size and unusable at ten thousand clients.
+--
+-- This replaces the fan-out with a spine primitive:
+--
+--   public.fayz_norm(text)          fold: strip accents, lowercase, collapse
+--                                   punctuation. IMMUTABLE, so it can be
+--                                   INDEXED. Mirrors foldText() in
+--                                   @fayz-ai/core/src/search/text.ts — the two
+--                                   must agree or server and client disagree
+--                                   about what matched.
+--   public.fayz_digits(text)        digits only — phones, CPF/CNPJ, SKUs.
+--   public.fayz_search_sources      WHAT is searchable. A registry row per
+--                                   source, the SQL mirror of the client's
+--                                   entity registry. Plugins and apps add their
+--                                   own rows from their own migrations; nothing
+--                                   here is hard-coded into the function.
+--   public.fayz_search_reindex()    builds the GIN trigram index for every
+--                                   registered source FROM THE REGISTRY, so the
+--                                   index expression is the query expression by
+--                                   construction (an index built by hand from a
+--                                   retyped expression is an index the planner
+--                                   silently refuses to use).
+--   public.fayz_global_search(...)  one call, all sources, ranked, capped.
+--
+-- Why trigram GIN and not tsvector full-text: people search a CRM for fragments
+-- and typos ("bigodin", "jose", "1198"), not for stemmed words. `%term%` under
+-- a gin_trgm_ops index is an index scan; under FTS it is not expressible at all.
+--
+-- SECURITY INVOKER on purpose: the search runs as the caller, so RLS decides
+-- which rows exist. `p_tenant_id` narrows, it does not authorize.
+--
+-- Replay safety: every statement is CREATE OR REPLACE / IF NOT EXISTS /
+-- ON CONFLICT DO UPDATE. Re-running is a no-op. Degrades cleanly on a pool
+-- without pg_trgm — the function still answers, just without index support and
+-- without typo tolerance.
+-- ============================================================================
+
+-- ----------------------------------------------------------------------------
+-- 0. Extensions (best effort — a managed pool usually has them already)
+-- ----------------------------------------------------------------------------
+DO $$
+DECLARE
+  v_schema text := CASE WHEN EXISTS (SELECT 1 FROM pg_namespace WHERE nspname = 'extensions')
+                        THEN 'extensions' ELSE 'public' END;
+BEGIN
+  IF NOT EXISTS (SELECT 1 FROM pg_extension WHERE extname = 'pg_trgm') THEN
+    BEGIN
+      EXECUTE format('CREATE EXTENSION pg_trgm WITH SCHEMA %I', v_schema);
+    EXCEPTION WHEN OTHERS THEN
+      RAISE NOTICE 'fayz search: pg_trgm unavailable (%), falling back to unindexed LIKE', SQLERRM;
+    END;
+  END IF;
+  IF NOT EXISTS (SELECT 1 FROM pg_extension WHERE extname = 'btree_gin') THEN
+    BEGIN
+      EXECUTE format('CREATE EXTENSION btree_gin WITH SCHEMA %I', v_schema);
+    EXCEPTION WHEN OTHERS THEN
+      RAISE NOTICE 'fayz search: btree_gin unavailable (%), tenant filter stays a recheck', SQLERRM;
+    END;
+  END IF;
+END $$;
+
+-- ----------------------------------------------------------------------------
+-- 1. Folding — the one definition of "same text"
+-- ----------------------------------------------------------------------------
+-- translate() rather than unaccent(): unaccent is STABLE (it depends on a
+-- dictionary), so it cannot appear in an index expression without an IMMUTABLE
+-- wrapper whose correctness depends on nobody ever editing the dictionary.
+-- A fixed character map is IMMUTABLE by construction and covers every accent
+-- the fleet's Latin-script locales actually produce.
+CREATE OR REPLACE FUNCTION public.fayz_norm(p_text text)
+RETURNS text
+LANGUAGE sql IMMUTABLE PARALLEL SAFE
+AS $$
+  SELECT btrim(regexp_replace(
+    lower(translate(
+      coalesce(p_text, ''),
+      'ÀÁÂÃÄÅàáâãäåÈÉÊËèéêëÌÍÎÏìíîïÒÓÔÕÖòóôõöÙÚÛÜùúûüÇçÑñÝýÿŠšŽžØøÆ挜ÐðÞþıŁł',
+      'AAAAAAaaaaaaEEEEeeeeIIIIiiiiOOOOOoooooUUUUuuuuCcNnYyySsZzOoAaOoDdTtiLl'
+    )),
+    '[^a-z0-9]+', ' ', 'g'))
+$$;
+
+COMMENT ON FUNCTION public.fayz_norm(text) IS
+  'Search folding: strip diacritics, lowercase, collapse non-alphanumerics to single spaces. IMMUTABLE so it can be indexed. Mirrored by foldText() in @fayz-ai/core.';
+
+CREATE OR REPLACE FUNCTION public.fayz_digits(p_text text)
+RETURNS text
+LANGUAGE sql IMMUTABLE PARALLEL SAFE
+AS $$ SELECT regexp_replace(coalesce(p_text, ''), '[^0-9]+', '', 'g') $$;
+
+COMMENT ON FUNCTION public.fayz_digits(text) IS
+  'Digits only — lets "(11) 98765-4321", "11987654321" and "98765" all find the same phone.';
+
+-- concat_ws(), concat() and array_to_string() are all STABLE (they route through
+-- type output functions), which bars them from an index expression — Postgres
+-- rejects the CREATE INDEX outright. A haystack has to be assembled from
+-- something IMMUTABLE, and for text arguments with a fixed separator the
+-- assembly genuinely is: same input, same output, forever.
+CREATE OR REPLACE FUNCTION public.fayz_cat(VARIADIC p_parts text[])
+RETURNS text
+LANGUAGE sql IMMUTABLE PARALLEL SAFE
+AS $$ SELECT coalesce(array_to_string(p_parts, ' '), '') $$;
+
+COMMENT ON FUNCTION public.fayz_cat(text[]) IS
+  'IMMUTABLE space-join of text values, NULLs skipped. The only concatenation allowed inside a fayz_search_sources haystack_expr — concat_ws is STABLE and cannot be indexed.';
+
+-- ----------------------------------------------------------------------------
+-- 2. The source registry — what global search is allowed to look at
+-- ----------------------------------------------------------------------------
+CREATE TABLE IF NOT EXISTS public.fayz_search_sources (
+  -- Matches the client's deriveEntityKey(). Sources with a `kind_column` emit
+  -- `<entity_key>:<kind>` per row, which is exactly how archetype entities are
+  -- keyed on the client ('person' + kind 'customer' → 'person:customer').
+  entity_key     text PRIMARY KEY,
+  relation       text NOT NULL,                        -- 'public.people'
+  id_column      text NOT NULL DEFAULT 'id',
+  tenant_column  text NOT NULL DEFAULT 'tenant_id',
+  kind_column    text,
+  title_expr     text NOT NULL,                        -- what the row is CALLED
+  subtitle_expr  text,                                 -- the disambiguating line
+  haystack_expr  text NOT NULL,                        -- everything matchable
+  digits_expr    text,                                 -- phone/document columns
+  filter_expr    text,                                 -- extra SQL predicate
+  icon           text,
+  weight         numeric NOT NULL DEFAULT 1,           -- multiplies the rank
+  enabled        boolean NOT NULL DEFAULT true,
+  created_at     timestamptz NOT NULL DEFAULT now()
+);
+
+COMMENT ON TABLE public.fayz_search_sources IS
+  'Registry of searchable relations for public.fayz_global_search. Readable by any member, writable only by the migration role — the expressions are executed as SQL.';
+
+ALTER TABLE public.fayz_search_sources ENABLE ROW LEVEL SECURITY;
+
+DO $$ BEGIN
+  IF NOT EXISTS (
+    SELECT 1 FROM pg_policies
+    WHERE schemaname = 'public' AND tablename = 'fayz_search_sources'
+      AND policyname = 'fayz_search_sources_read'
+  ) THEN
+    -- Not tenant-scoped: the catalog describes SHAPES, never rows. Row access
+    -- is decided by each source relation's own RLS when the search runs.
+    CREATE POLICY "fayz_search_sources_read" ON public.fayz_search_sources
+      FOR SELECT TO authenticated USING (true);
+  END IF;
+END $$;
+
+REVOKE ALL ON public.fayz_search_sources FROM anon;
+GRANT SELECT ON public.fayz_search_sources TO authenticated;
+
+-- ----------------------------------------------------------------------------
+-- 3. Spine sources
+-- ----------------------------------------------------------------------------
+-- `weight` is the editorial call about what a business means when it types a
+-- name: a person first, then what it sells, then where and when. Ledger rows
+-- are found by number, so they sit lower.
+INSERT INTO public.fayz_search_sources
+  (entity_key, relation, kind_column, title_expr, subtitle_expr, haystack_expr, digits_expr, filter_expr, icon, weight)
+VALUES
+  ('person', 'public.people', 'kind',
+   'name',
+   $sub$nullif(concat_ws(' · ', nullif(email,''), nullif(phone,'')), '')$sub$,
+   $hay$public.fayz_cat(name, email, phone, document_number, notes, public.fayz_cat(VARIADIC tags))$hay$,
+   $dig$concat_ws(' ', phone, document_number)$dig$,
+   NULL, 'User', 1.00),
+
+  ('product', 'public.products', NULL,
+   'name',
+   $sub$nullif(concat_ws(' · ', nullif(sku,''), nullif(description,'')), '')$sub$,
+   $hay$public.fayz_cat(name, sku, description, public.fayz_cat(VARIADIC tags))$hay$,
+   $dig$sku$dig$,
+   NULL, 'Box', 0.95),
+
+  ('service', 'public.services', NULL,
+   'name',
+   $sub$nullif(description, '')$sub$,
+   $hay$public.fayz_cat(name, description, public.fayz_cat(VARIADIC tags))$hay$,
+   NULL,
+   NULL, 'Sparkles', 0.95),
+
+  ('location', 'public.locations', 'kind',
+   'name',
+   $sub$nullif(concat_ws(' · ', nullif(city,''), nullif(state,'')), '')$sub$,
+   $hay$public.fayz_cat(name, email, phone, address, city, state, postal_code)$hay$,
+   $dig$concat_ws(' ', phone, postal_code)$dig$,
+   NULL, 'MapPin', 0.80),
+
+  ('category', 'public.categories', 'kind',
+   'name',
+   $sub$nullif(slug, '')$sub$,
+   $hay$public.fayz_cat(name, slug)$hay$,
+   NULL,
+   NULL, 'Tag', 0.60),
+
+  ('address', 'public.addresses', NULL,
+   $tit$concat_ws(', ', nullif(street,''), nullif(number,''))$tit$,
+   $sub$nullif(concat_ws(' · ', nullif(district,''), nullif(city,''), nullif(postal_code,'')), '')$sub$,
+   $hay$public.fayz_cat(label, recipient, street, number, complement, district, city, state, postal_code)$hay$,
+   $dig$concat_ws(' ', postal_code, phone)$dig$,
+   NULL, 'MapPin', 0.55)
+ON CONFLICT (entity_key) DO UPDATE SET
+  relation      = EXCLUDED.relation,
+  kind_column   = EXCLUDED.kind_column,
+  title_expr    = EXCLUDED.title_expr,
+  subtitle_expr = EXCLUDED.subtitle_expr,
+  haystack_expr = EXCLUDED.haystack_expr,
+  digits_expr   = EXCLUDED.digits_expr,
+  filter_expr   = EXCLUDED.filter_expr,
+  icon          = EXCLUDED.icon,
+  weight        = EXCLUDED.weight;
+
+-- Order/transaction sources only make sense once those tables carry a human
+-- reference; they are registered by the plugins that own that shape.
+
+-- ----------------------------------------------------------------------------
+-- 4. Index builder — derived from the registry, never retyped
+-- ----------------------------------------------------------------------------
+CREATE OR REPLACE FUNCTION public.fayz_search_reindex()
+RETURNS integer
+LANGUAGE plpgsql VOLATILE
+SET search_path = public, extensions, pg_temp
+AS $$
+DECLARE
+  v_src      record;
+  v_rel      text;
+  v_name     text;
+  v_built    integer := 0;
+  v_has_trgm boolean := EXISTS (SELECT 1 FROM pg_extension WHERE extname = 'pg_trgm');
+  v_has_gin  boolean := EXISTS (SELECT 1 FROM pg_extension WHERE extname = 'btree_gin');
+BEGIN
+  IF NOT v_has_trgm THEN
+    RAISE NOTICE 'fayz search: pg_trgm missing — no index built, search falls back to sequential LIKE';
+    RETURN 0;
+  END IF;
+
+  FOR v_src IN
+    SELECT * FROM public.fayz_search_sources WHERE enabled ORDER BY entity_key
+  LOOP
+    v_rel := to_regclass(v_src.relation)::text;
+    CONTINUE WHEN v_rel IS NULL;
+    -- A view cannot be indexed; only its base tables can.
+    CONTINUE WHEN (SELECT c.relkind FROM pg_class c WHERE c.oid = to_regclass(v_src.relation))
+                  NOT IN ('r', 'p');
+
+    -- Name derived from (relation, expression): two sources over the same
+    -- columns share one index instead of building it twice.
+    v_name := 'fayz_search_' || substr(md5(v_rel || '|' || v_src.haystack_expr), 1, 20);
+
+    BEGIN
+      IF v_has_gin THEN
+        -- Composite: the tenant equality is resolved INSIDE the index, so a
+        -- 500-tenant pool does not trigram-scan its neighbours' rows.
+        EXECUTE format(
+          'CREATE INDEX IF NOT EXISTS %I ON %s USING gin (%I, public.fayz_norm(%s) gin_trgm_ops)',
+          v_name, v_rel, v_src.tenant_column, v_src.haystack_expr);
+      ELSE
+        EXECUTE format(
+          'CREATE INDEX IF NOT EXISTS %I ON %s USING gin (public.fayz_norm(%s) gin_trgm_ops)',
+          v_name, v_rel, v_src.haystack_expr);
+      END IF;
+      v_built := v_built + 1;
+    EXCEPTION WHEN OTHERS THEN
+      -- Most likely cause: btree_gin present but with no GIN opclass for the
+      -- tenant column's type. A trigram-only index still serves every query;
+      -- the tenant equality just becomes a recheck.
+      BEGIN
+        EXECUTE format(
+          'CREATE INDEX IF NOT EXISTS %I ON %s USING gin (public.fayz_norm(%s) gin_trgm_ops)',
+          v_name, v_rel, v_src.haystack_expr);
+        v_built := v_built + 1;
+      EXCEPTION WHEN OTHERS THEN
+        RAISE NOTICE 'fayz search: could not index % (%): %', v_src.entity_key, v_rel, SQLERRM;
+      END;
+    END;
+  END LOOP;
+
+  RETURN v_built;
+END $$;
+
+COMMENT ON FUNCTION public.fayz_search_reindex() IS
+  'Builds/refreshes the GIN trigram index for every enabled row of fayz_search_sources. Call it after inserting your own source row.';
+
+SELECT public.fayz_search_reindex();
+
+-- ----------------------------------------------------------------------------
+-- 5. The search itself
+-- ----------------------------------------------------------------------------
+DO $$ BEGIN
+  IF NOT EXISTS (SELECT 1 FROM pg_type WHERE typname = 'fayz_search_hit'
+                   AND typnamespace = 'public'::regnamespace) THEN
+    CREATE TYPE public.fayz_search_hit AS (
+      entity_key text,
+      record_id  text,
+      title      text,
+      subtitle   text,
+      score      real
+    );
+  END IF;
+END $$;
+
+CREATE OR REPLACE FUNCTION public.fayz_global_search(
+  p_query       text,
+  p_tenant_id   uuid,
+  p_entity_keys text[] DEFAULT NULL,
+  p_limit       integer DEFAULT 30,
+  p_per_source  integer DEFAULT 8
+)
+RETURNS TABLE (entity_key text, record_id text, title text, subtitle text, score real)
+LANGUAGE plpgsql STABLE SECURITY INVOKER
+SET search_path = public, extensions, pg_temp
+AS $$
+DECLARE
+  v_q        text := public.fayz_norm(p_query);
+  v_digits   text := public.fayz_digits(p_query);
+  v_tokens   text[];
+  v_token    text;
+  v_src      record;
+  v_acc      public.fayz_search_hit[] := '{}';
+  v_rows     public.fayz_search_hit[];
+  v_title    text;
+  v_hay      text;
+  v_match    text;
+  v_where    text;
+  v_key      text;
+  v_kinds    text[];
+  v_sql      text;
+  v_phase    integer;
+  v_has_trgm boolean := EXISTS (SELECT 1 FROM pg_extension WHERE extname = 'pg_trgm');
+BEGIN
+  -- One character matches every row; two is where a lookup starts to mean
+  -- something. The client enforces the same floor before it even calls.
+  IF v_q IS NULL OR length(v_q) < 2 THEN RETURN; END IF;
+  IF p_tenant_id IS NULL THEN RETURN; END IF;
+
+  v_tokens   := array_remove(string_to_array(v_q, ' '), '');
+  p_limit      := least(greatest(coalesce(p_limit, 30), 1), 200);
+  p_per_source := least(greatest(coalesce(p_per_source, 8), 1), 50);
+  IF length(v_digits) < 4 THEN v_digits := ''; END IF;
+
+  IF v_has_trgm THEN
+    BEGIN
+      -- Touching a pg_trgm function loads the library, which is what registers
+      -- its GUCs; before that they are unrecognized placeholders only a
+      -- superuser may set. pg_trgm ships word_similarity_threshold at 0.6,
+      -- which forgives a wrong letter but not the transposition people
+      -- actually type ("bigdoinho"). LOCAL, so nothing outside this call
+      -- inherits a looser notion of "close" — and best-effort, because a pool
+      -- that refuses the setting should still search, just less forgivingly.
+      PERFORM similarity('a', 'a');
+      PERFORM set_config('pg_trgm.word_similarity_threshold', '0.40', true);
+    EXCEPTION WHEN OTHERS THEN NULL;
+    END;
+  END IF;
+
+  -- Two phases. Phase 1 is literal: every token must appear, which is exactly
+  -- what the trigram index answers, and it is what the user meant 99 times out
+  -- of 100. Phase 2 only runs when phase 1 found NOTHING, and only then pays
+  -- for fuzzy matching. ORing the two would have made every ordinary query
+  -- carry the cost — and would have let near-misses dilute exact answers.
+  <<phases>>
+  FOR v_phase IN 1..2 LOOP
+    EXIT WHEN v_phase = 2 AND (
+      coalesce(array_length(v_acc, 1), 0) > 0 OR NOT v_has_trgm OR length(v_q) < 4
+    );
+
+  FOR v_src IN
+    SELECT s.* FROM public.fayz_search_sources s
+    WHERE s.enabled
+      AND to_regclass(s.relation) IS NOT NULL
+      AND (
+        p_entity_keys IS NULL
+        OR s.entity_key = ANY (p_entity_keys)
+        OR (s.kind_column IS NOT NULL AND EXISTS (
+              SELECT 1 FROM unnest(p_entity_keys) k WHERE k LIKE s.entity_key || ':%'))
+      )
+    ORDER BY s.weight DESC, s.entity_key
+  LOOP
+    v_title := 'public.fayz_norm(' || v_src.title_expr || ')';
+    v_hay   := 'public.fayz_norm(' || v_src.haystack_expr || ')';
+
+    IF v_phase = 1 THEN
+      -- Every token must land somewhere. Emitted as separate literal LIKEs (not
+      -- `LIKE ALL (array)`) because that is the only form the planner can push
+      -- into the trigram index. The tokens came out of fayz_norm, so they are
+      -- already [a-z0-9 ] — quote_literal is belt and braces.
+      v_where := '';
+      FOREACH v_token IN ARRAY v_tokens LOOP
+        IF v_where <> '' THEN v_where := v_where || ' AND '; END IF;
+        v_where := v_where || v_hay || ' LIKE ' || quote_literal('%' || v_token || '%');
+      END LOOP;
+      v_match := '(' || v_where || ')';
+
+      IF v_digits <> '' AND v_src.digits_expr IS NOT NULL THEN
+        v_match := v_match || ' OR public.fayz_digits(' || v_src.digits_expr || ') LIKE '
+                   || quote_literal('%' || v_digits || '%');
+      END IF;
+    ELSE
+      -- `<%` (word_similarity) rather than `%` (similarity): the right-hand
+      -- side is a whole haystack, and plain similarity of a 7-letter query
+      -- against a 200-character row is always below any usable threshold.
+      -- Measured against the INDEXED expression so phase 2 is an index scan too.
+      v_match := quote_literal(v_q) || ' <% ' || v_hay;
+    END IF;
+
+    -- Archetype sources emit one key per kind. When the caller asked for a
+    -- subset of kinds, push that INTO the source query: filtering after a
+    -- per-source LIMIT would let a populous kind starve the one being asked for.
+    v_key := quote_literal(v_src.entity_key);
+    IF v_src.kind_column IS NOT NULL THEN
+      v_key := v_key || ' || '':'' || ' || quote_ident(v_src.kind_column);
+      IF p_entity_keys IS NOT NULL AND NOT (v_src.entity_key = ANY (p_entity_keys)) THEN
+        SELECT array_agg(substr(k, length(v_src.entity_key) + 2))
+          INTO v_kinds
+          FROM unnest(p_entity_keys) k
+         WHERE k LIKE v_src.entity_key || ':%';
+        IF v_kinds IS NOT NULL THEN
+          v_match := '(' || v_match || ') AND ' || quote_ident(v_src.kind_column)
+                     || ' = ANY (' || quote_literal(v_kinds::text) || '::text[])';
+        END IF;
+      END IF;
+    END IF;
+
+    v_sql :=
+      'SELECT ' || v_key || '::text AS entity_key, '
+        || quote_ident(v_src.id_column) || '::text AS record_id, '
+        || '(' || v_src.title_expr || ')::text AS title, '
+        || '(' || coalesce(v_src.subtitle_expr, 'NULL') || ')::text AS subtitle, '
+        -- Rank ladder, mirrored by scoreCandidate() on the client. The client
+        -- re-scores what it receives; this ordering decides what survives the
+        -- per-source LIMIT, which is the decision the client cannot make.
+        || '(GREATEST('
+        || '  CASE WHEN ' || v_title || ' = ' || quote_literal(v_q) || ' THEN 1.00'
+        || '       WHEN ' || v_title || ' LIKE ' || quote_literal(v_q || '%') || ' THEN 0.94'
+        || '       WHEN ' || v_title || ' LIKE ' || quote_literal('% ' || v_q || '%') || ' THEN 0.88'
+        || '       WHEN ' || v_title || ' LIKE ' || quote_literal('%' || v_q || '%') || ' THEN 0.76'
+        || '       WHEN ' || v_hay   || ' LIKE ' || quote_literal('%' || v_q || '%') || ' THEN 0.62'
+        || '       ELSE 0.40 END'
+        || CASE WHEN v_has_trgm
+                THEN ', word_similarity(' || quote_literal(v_q) || ', ' || v_title || ')::numeric * 0.60'
+                ELSE '' END
+        || ') * ' || v_src.weight || ')::real AS score'
+      || ' FROM ' || to_regclass(v_src.relation)::text
+      || ' WHERE ' || quote_ident(v_src.tenant_column) || ' = $1'
+      || CASE WHEN v_src.filter_expr IS NULL THEN '' ELSE ' AND (' || v_src.filter_expr || ')' END
+      || ' AND (' || v_match || ')'
+      || ' ORDER BY 5 DESC LIMIT ' || p_per_source;
+
+    BEGIN
+      EXECUTE 'SELECT coalesce(array_agg(x::public.fayz_search_hit), ''{}''::public.fayz_search_hit[]) FROM ('
+              || v_sql || ') x'
+        INTO v_rows USING p_tenant_id;
+      v_acc := v_acc || v_rows;
+    EXCEPTION WHEN OTHERS THEN
+      -- One misconfigured source must never blank the whole search box.
+      RAISE NOTICE 'fayz search: source % failed: %', v_src.entity_key, SQLERRM;
+    END;
+  END LOOP;
+  END LOOP phases;
+
+  RETURN QUERY
+    SELECT h.entity_key, h.record_id, h.title, h.subtitle, h.score
+      FROM unnest(v_acc) h
+     ORDER BY h.score DESC, length(coalesce(h.title, '')) ASC, h.title
+     LIMIT p_limit;
+END $$;
+
+COMMENT ON FUNCTION public.fayz_global_search(text, uuid, text[], integer, integer) IS
+  'Global search across every registered source in one round-trip. SECURITY INVOKER — RLS decides visibility; p_tenant_id only narrows. p_entity_keys restricts to the keys the caller is allowed to see.';
+
+REVOKE ALL ON FUNCTION public.fayz_global_search(text, uuid, text[], integer, integer) FROM PUBLIC;
+REVOKE ALL ON FUNCTION public.fayz_global_search(text, uuid, text[], integer, integer) FROM anon;
+GRANT EXECUTE ON FUNCTION public.fayz_global_search(text, uuid, text[], integer, integer) TO authenticated;
+
+GRANT EXECUTE ON FUNCTION public.fayz_norm(text) TO authenticated, anon;
+GRANT EXECUTE ON FUNCTION public.fayz_digits(text) TO authenticated, anon;

package/migrations/019_tenant_members_person_id.sql

@@ -0,0 +1,20 @@
+-- 019: Person-first team model — link a membership (login + RBAC role) to the
+-- person record it represents.
+--
+-- A "team member" is a PERSON (public.people, kind in the app's team.personKinds).
+-- public.tenant_members is the OPTIONAL access overlay: a row exists only when a
+-- person is granted login + role. person_id ties the two. Nullable both ways:
+--   * login-only account (e.g. the owner who signed up)  -> tenant_members with person_id NULL
+--   * team person without access (e.g. a teacher who never logs in) -> people row, NO tenant_members row
+-- Idempotent + additive (safe to re-apply).
+
+ALTER TABLE public.tenant_members
+  ADD COLUMN IF NOT EXISTS person_id uuid REFERENCES public.people(id) ON DELETE SET NULL;
+
+-- A person maps to at most one membership per tenant (partial: many NULLs allowed).
+CREATE UNIQUE INDEX IF NOT EXISTS tenant_members_tenant_person_uidx
+  ON public.tenant_members (tenant_id, person_id)
+  WHERE person_id IS NOT NULL;
+
+CREATE INDEX IF NOT EXISTS tenant_members_person_idx
+  ON public.tenant_members (person_id);

package/package.json

@@ -3,7 +3,7 @@
   "fayz": {
     "status": "beta"
   },
-  "version": "0.8.0",
+  "version": "0.8.3",
   "description": "Fayz SDK database layer — Drizzle schema primitives, spine references, and migration helpers shared across plugins.",
   "type": "module",
   "main": "./dist/index.cjs",