@fayz-ai/db 0.11.0 → 0.13.0

package/migrations/136_unit_id_means_locality.sql

@@ -0,0 +1,358 @@
+-- ============================================================================
+-- 136_unit_id_means_locality.sql — `unit_id` stops meaning two things (#225).
+--
+-- The column carried both "this row belongs to a unit" (cardinality 1, a fact
+-- about the row) and "this row is available in a unit" (cardinality N, a
+-- relation that changes without the row changing). Two consequences, both
+-- verifiable before this file: there were TWO ways to say "only at Centro"
+-- (`unit_id = centro`, or tenant-wide plus one `available_in` tuple) resolved by
+-- different code paths with nothing preventing the wrong one; and the scaffold
+-- had never once generated `unit_id NOT NULL` — one table in the whole repo had
+-- it, added by hand.
+--
+-- THREE CLASSES, NOT TWO — and the schema is what says so.
+--
+-- The decision as written said `scope` was `unit | tenant`. Classifying the 47
+-- registered tables did not survive that: `holidays`, `field_rules`,
+-- `price_tables` and `plg_inventory_product_settings` each document, in their own
+-- COMMENT, that `unit_id NULL` means "the network's" and a value means "that
+-- unit's own". That is not the conflation this file exists to remove — both
+-- readings are LOCALITY, at cardinality 0-or-1. It is a third class, and
+-- pretending otherwise would have forced a wrong constraint onto four tables
+-- that were already right.
+--
+--   unit           locality required   → unit_id NOT NULL, and the policy drops
+--                                        its `unit_id IS NULL OR` branch
+--   unit_optional  locality optional   → nothing enforced, but DECLARED: the NULL
+--                                        now means something a reader can check
+--   tenant         no locality at all  → CHECK (unit_id IS NULL); distribution is
+--                                        `available_in`, and there is one way to
+--                                        say it
+--
+-- NOT NULL IS APPLIED ONLY WHERE THE DATA ALLOWS, AND THE REST IS NAMED.
+-- A table classified `unit` whose rows still hold NULLs is not silently skipped
+-- and not force-migrated: it lands in `app.scaffold_scope_pending` with the count
+-- that has to be backfilled, and 900_verification asserts the list, so it cannot
+-- grow quietly.
+--
+-- Replay-safe: additive column, idempotent seed, constraints guarded by
+-- existence checks.
+-- ============================================================================
+
+-- ── the registry records the class ──────────────────────────────────────
+ALTER TABLE app.scaffold_registry ADD COLUMN IF NOT EXISTS scope text;
+DO $$
+BEGIN
+  IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conrelid = 'app.scaffold_registry'::regclass AND conname = 'scaffold_registry_scope_chk') THEN
+    ALTER TABLE app.scaffold_registry
+      ADD CONSTRAINT scaffold_registry_scope_chk CHECK (scope IS NULL OR scope IN ('unit', 'unit_optional', 'tenant'));
+  END IF;
+END $$;
+COMMENT ON COLUMN app.scaffold_registry.scope IS
+  'What unit_id means on this table (#225): unit = locality required (NOT NULL); unit_optional = locality optional, NULL is the network default; tenant = no locality, distribution is available_in and unit_id is CHECKed NULL.';
+
+CREATE TABLE IF NOT EXISTS app.scaffold_scope_pending (
+  table_schema text NOT NULL,
+  table_name   text NOT NULL,
+  scope        text NOT NULL,
+  offending    bigint NOT NULL,
+  noticed_at   timestamptz NOT NULL DEFAULT now(),
+  PRIMARY KEY (table_schema, table_name)
+);
+COMMENT ON TABLE app.scaffold_scope_pending IS
+  'Tables classified `unit` whose rows still hold a NULL unit_id, with the count that has to be backfilled before NOT NULL can land (#225). Empty is the goal; 900_verification asserts the contents so the list cannot grow without someone noticing.';
+
+-- ── the predicate already knows the class ──────────────────────────────
+-- app.scaffold_scope_sql has taken a third argument since 124, defaulted and
+-- unused until now. What changes here is who passes it.
+
+-- 134's refresh, now passing the class through
+CREATE OR REPLACE FUNCTION app.scaffold_refresh_policies(p_table text)
+RETURNS void LANGUAGE plpgsql SECURITY DEFINER SET search_path = '' AS $$
+DECLARE
+  v_schema text := split_part(replace(p_table, '"', ''), '.', 1);
+  v_name   text := split_part(replace(p_table, '"', ''), '.', 2);
+  v_q      text := format('%I.%I', split_part(replace(p_table, '"', ''), '.', 1), split_part(replace(p_table, '"', ''), '.', 2));
+  r        app.scaffold_registry%ROWTYPE;
+  v_scope  text;
+  v_class  text;
+BEGIN
+  SELECT * INTO r FROM app.scaffold_registry WHERE table_schema = v_schema AND table_name = v_name;
+  IF NOT FOUND THEN
+    RAISE EXCEPTION 'scaffold_refresh_policies: %.% is not in the scaffold registry', v_schema, v_name USING ERRCODE = 'P0002';
+  END IF;
+
+  -- The `unit` rendering drops the `unit_id IS NULL OR` branch, which is only
+  -- sound when the column really is NOT NULL. Declaring a table `unit` while its
+  -- writers still produce NULLs is exactly the state this file leaves most tables
+  -- in — so the optimisation follows the CONSTRAINT, never the label. Getting
+  -- this wrong hid every unit-less financial movement and took
+  -- v_financial_customer_credit to 0.00.
+  SELECT CASE WHEN c.is_nullable = 'NO' THEN 'unit' ELSE NULL END INTO v_class
+    FROM information_schema.columns c
+   WHERE c.table_schema = v_schema AND c.table_name = v_name AND c.column_name = 'unit_id';
+  v_scope := app.scaffold_scope_sql(r.resource_type, r.plugin, v_class);
+
+  EXECUTE format('DROP POLICY IF EXISTS %I ON %s', v_name || '_authz_select', v_q);
+  EXECUTE format('CREATE POLICY %I ON %s FOR SELECT TO authenticated USING (%s AND (select app.has_permission(%L, unit_id)))',
+                 v_name || '_authz_select', v_q, v_scope, r.plugin || '.read');
+  EXECUTE format('DROP POLICY IF EXISTS %I ON %s', v_name || '_authz_update', v_q);
+  EXECUTE format('CREATE POLICY %I ON %s FOR UPDATE TO authenticated USING (%s AND (select app.has_permission(%L, unit_id))) WITH CHECK (tenant_id = (select app.current_tenant_id()) AND (unit_id IS NULL OR (select app.has_unit(unit_id))) AND (select app.has_permission(%L, unit_id)))',
+                 v_name || '_authz_update', v_q, v_scope, r.plugin || '.edit', r.plugin || '.edit');
+  EXECUTE format('DROP POLICY IF EXISTS %I ON %s', v_name || '_authz_delete', v_q);
+  EXECUTE format('CREATE POLICY %I ON %s FOR DELETE TO authenticated USING (%s AND (select app.has_permission(%L, unit_id)))',
+                 v_name || '_authz_delete', v_q, v_scope, r.plugin || '.delete');
+END $$;
+REVOKE ALL ON FUNCTION app.scaffold_refresh_policies(text) FROM public, anon, authenticated;
+
+
+-- ── scaffold_table, re-emitted so registration always declares a class ──
+-- Lifted from 124 by transformation again; the only change is the registry
+-- INSERT.
+CREATE OR REPLACE FUNCTION app.scaffold_table(
+  p_table regclass,
+  p_resource_type text,
+  p_plugin text,
+  p_owner_scoping boolean DEFAULT true,
+  p_mode text DEFAULT 'enforce'
+)
+RETURNS void
+LANGUAGE plpgsql SECURITY DEFINER SET search_path = ''
+AS $$
+DECLARE
+  v_schema text;
+  v_name   text;
+  v_q      text;   -- quoted qualified name
+  v_prev   text[] := '{}';
+  v_rows   bigint;
+  r        record;
+  v_scope  text;   -- the row-scope predicate shared by every policy
+BEGIN
+  IF p_mode NOT IN ('shadow', 'enforce') THEN
+    RAISE EXCEPTION 'scaffold_table: mode must be shadow|enforce';
+  END IF;
+  SELECT n.nspname, c.relname INTO v_schema, v_name
+    FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace WHERE c.oid = p_table;
+  v_q := format('%I.%I', v_schema, v_name);
+
+  -- ── columns
+  IF NOT EXISTS (SELECT 1 FROM information_schema.columns WHERE table_schema = v_schema AND table_name = v_name AND column_name = 'id') THEN
+    RAISE EXCEPTION 'scaffold_table: % has no id column', v_q;
+  END IF;
+  EXECUTE format('SELECT count(*) FROM %s', v_q) INTO v_rows;
+  IF NOT EXISTS (SELECT 1 FROM information_schema.columns WHERE table_schema = v_schema AND table_name = v_name AND column_name = 'tenant_id') THEN
+    EXECUTE format('ALTER TABLE %s ADD COLUMN tenant_id uuid REFERENCES public.tenants(id) ON DELETE CASCADE', v_q);
+    IF v_rows = 0 THEN EXECUTE format('ALTER TABLE %s ALTER COLUMN tenant_id SET NOT NULL', v_q); END IF;
+  END IF;
+  EXECUTE format('ALTER TABLE %s ADD COLUMN IF NOT EXISTS unit_id uuid', v_q);
+  EXECUTE format('ALTER TABLE %s ADD COLUMN IF NOT EXISTS owner_id uuid', v_q);
+  EXECUTE format('ALTER TABLE %s ADD COLUMN IF NOT EXISTS created_at timestamptz NOT NULL DEFAULT now()', v_q);
+  EXECUTE format('ALTER TABLE %s ADD COLUMN IF NOT EXISTS updated_at timestamptz NOT NULL DEFAULT now()', v_q);
+
+  -- ── unique(tenant_id, id) — enables composite FKs from other tables
+  IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conrelid = p_table AND conname = v_name || '_tenant_id_id_key') THEN
+    EXECUTE format('ALTER TABLE %s ADD CONSTRAINT %I UNIQUE (tenant_id, id)', v_q, v_name || '_tenant_id_id_key');
+  END IF;
+  -- ── composite FKs: unit within tenant, owner a member of the tenant
+  IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conrelid = p_table AND conname = v_name || '_unit_fk') THEN
+    EXECUTE format('ALTER TABLE %s ADD CONSTRAINT %I FOREIGN KEY (tenant_id, unit_id) REFERENCES app.units(tenant_id, id) ON DELETE SET NULL', v_q, v_name || '_unit_fk');
+  END IF;
+  IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conrelid = p_table AND conname = v_name || '_owner_fk') THEN
+    EXECUTE format('ALTER TABLE %s ADD CONSTRAINT %I FOREIGN KEY (tenant_id, owner_id) REFERENCES app.memberships(tenant_id, user_id) ON DELETE SET NULL', v_q, v_name || '_owner_fk');
+  END IF;
+
+  -- ── tenant-first indexes
+  EXECUTE format('CREATE INDEX IF NOT EXISTS %I ON %s (tenant_id, unit_id)', v_name || '_tenant_unit_idx', v_q);
+  EXECUTE format('CREATE INDEX IF NOT EXISTS %I ON %s (tenant_id, owner_id) WHERE owner_id IS NOT NULL', v_name || '_tenant_owner_idx', v_q);
+
+  -- ── updated_at
+  EXECUTE format('DROP TRIGGER IF EXISTS %I ON %s', v_name || '_updated_at', v_q);
+  EXECUTE format('CREATE TRIGGER %I BEFORE UPDATE ON %s FOR EACH ROW EXECUTE FUNCTION public.handle_updated_at()', v_name || '_updated_at', v_q);
+
+  -- ── RLS
+  EXECUTE format('ALTER TABLE %s ENABLE ROW LEVEL SECURITY', v_q);
+  EXECUTE format('ALTER TABLE %s FORCE ROW LEVEL SECURITY', v_q);
+  IF p_mode = 'enforce' THEN
+    FOR r IN SELECT policyname FROM pg_policies WHERE schemaname = v_schema AND tablename = v_name
+             AND policyname NOT IN (v_name || '_authz_select', v_name || '_authz_insert', v_name || '_authz_update', v_name || '_authz_delete') LOOP
+      v_prev := v_prev || r.policyname;
+      EXECUTE format('DROP POLICY IF EXISTS %I ON %s', r.policyname, v_q);
+    END LOOP;
+  END IF;
+
+  v_scope := app.scaffold_scope_sql(p_resource_type, p_plugin);
+
+  EXECUTE format('DROP POLICY IF EXISTS %I ON %s', v_name || '_authz_select', v_q);
+  EXECUTE format('CREATE POLICY %I ON %s FOR SELECT TO authenticated USING (%s AND (select app.has_permission(%L, unit_id)))',
+                 v_name || '_authz_select', v_q, v_scope, p_plugin || '.read');
+  EXECUTE format('DROP POLICY IF EXISTS %I ON %s', v_name || '_authz_insert', v_q);
+  EXECUTE format('CREATE POLICY %I ON %s FOR INSERT TO authenticated WITH CHECK (tenant_id = (select app.current_tenant_id()) AND (unit_id IS NULL OR (select app.has_unit(unit_id))) AND (select app.has_permission(%L, unit_id)))',
+                 v_name || '_authz_insert', v_q, p_plugin || '.create');
+  EXECUTE format('DROP POLICY IF EXISTS %I ON %s', v_name || '_authz_update', v_q);
+  EXECUTE format('CREATE POLICY %I ON %s FOR UPDATE TO authenticated USING (%s AND (select app.has_permission(%L, unit_id))) WITH CHECK (tenant_id = (select app.current_tenant_id()) AND (unit_id IS NULL OR (select app.has_unit(unit_id))) AND (select app.has_permission(%L, unit_id)))',
+                 v_name || '_authz_update', v_q, v_scope, p_plugin || '.edit', p_plugin || '.edit');
+  EXECUTE format('DROP POLICY IF EXISTS %I ON %s', v_name || '_authz_delete', v_q);
+  EXECUTE format('CREATE POLICY %I ON %s FOR DELETE TO authenticated USING (%s AND (select app.has_permission(%L, unit_id)))',
+                 v_name || '_authz_delete', v_q, v_scope, p_plugin || '.delete');
+
+  -- scope defaults on REGISTRATION, so a table cannot exist in the registry
+  -- unclassified. A plugin's tables are scaffolded after the core chain has run,
+  -- so 136's DO block could never have reached them — they arrive here instead,
+  -- declared `unit_optional` until the plugin says otherwise.
+  INSERT INTO app.scaffold_registry (table_schema, table_name, resource_type, plugin, owner_scoping, mode, previous_policies, scope)
+  VALUES (v_schema, v_name, p_resource_type, p_plugin, p_owner_scoping, p_mode, v_prev, 'unit_optional')
+  ON CONFLICT (table_schema, table_name) DO UPDATE
+    SET resource_type = EXCLUDED.resource_type, plugin = EXCLUDED.plugin, owner_scoping = EXCLUDED.owner_scoping,
+        scope = coalesce(app.scaffold_registry.scope, EXCLUDED.scope),
+        mode = EXCLUDED.mode, applied_at = now(),
+        previous_policies = CASE WHEN EXCLUDED.mode = 'enforce' AND app.scaffold_registry.mode = 'shadow'
+                                 THEN app.scaffold_registry.previous_policies || EXCLUDED.previous_policies
+                                 ELSE EXCLUDED.previous_policies END;
+END $$;
+
+-- ── declare a class, and make the schema say it ─────────────────────────
+CREATE OR REPLACE FUNCTION app.scaffold_scope(p_table regclass, p_scope text, p_enforce boolean DEFAULT false)
+RETURNS void
+LANGUAGE plpgsql SECURITY DEFINER SET search_path = ''
+AS $$
+DECLARE
+  v_schema text; v_name text; v_q text; v_bad bigint;
+BEGIN
+  IF p_scope NOT IN ('unit', 'unit_optional', 'tenant') THEN
+    RAISE EXCEPTION 'scaffold_scope: scope must be unit | unit_optional | tenant';
+  END IF;
+  SELECT n.nspname, c.relname INTO v_schema, v_name
+    FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace WHERE c.oid = p_table;
+  v_q := format('%I.%I', v_schema, v_name);
+
+  UPDATE app.scaffold_registry SET scope = p_scope
+   WHERE table_schema = v_schema AND table_name = v_name;
+  IF NOT FOUND THEN
+    RAISE EXCEPTION 'scaffold_scope: %.% is not in the scaffold registry', v_schema, v_name USING ERRCODE = 'P0002';
+  END IF;
+  DELETE FROM app.scaffold_scope_pending WHERE table_schema = v_schema AND table_name = v_name;
+
+  IF p_scope = 'unit' THEN
+    EXECUTE format('SELECT count(*) FROM %s WHERE unit_id IS NULL', v_q) INTO v_bad;
+    IF NOT p_enforce THEN
+      -- Declared, not enforced — and recorded, so it is a list and not a silence.
+      -- p_enforce is an explicit decision because "the table has no offending
+      -- rows" turned out to be worthless evidence: nine suites went red on the
+      -- first attempt at NOT NULL, and every one of them was an EMPTY table whose
+      -- writers do not fill unit_id. The constraint is about the writers.
+      INSERT INTO app.scaffold_scope_pending (table_schema, table_name, scope, offending)
+      VALUES (v_schema, v_name, p_scope, v_bad);
+    ELSIF v_bad > 0 THEN
+      RAISE EXCEPTION 'scaffold_scope: % was declared enforceable but holds % row(s) without a unit', v_q, v_bad;
+    ELSE
+      EXECUTE format('ALTER TABLE %s ALTER COLUMN unit_id SET NOT NULL', v_q);
+    END IF;
+
+  ELSIF p_scope = 'tenant' THEN
+    EXECUTE format('SELECT count(*) FROM %s WHERE unit_id IS NOT NULL', v_q) INTO v_bad;
+    IF v_bad = 0 THEN
+      IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conrelid = p_table AND conname = v_name || '_unit_id_null_chk') THEN
+        EXECUTE format('ALTER TABLE %s ADD CONSTRAINT %I CHECK (unit_id IS NULL)', v_q, v_name || '_unit_id_null_chk');
+      END IF;
+    ELSE
+      INSERT INTO app.scaffold_scope_pending (table_schema, table_name, scope, offending)
+      VALUES (v_schema, v_name, p_scope, v_bad);
+      RAISE NOTICE '126: % has % row(s) with a unit_id but is classified tenant (recorded)', v_q, v_bad;
+    END IF;
+  END IF;
+
+  PERFORM app.scaffold_refresh_policies(v_q);
+  -- a masked view renders the same predicate, so it has to learn the class too
+  PERFORM app.masked_view_refresh(p_table, m.context, m.reference)
+     FROM app.masked_views m
+    WHERE m.table_schema = v_schema AND m.table_name = v_name;
+END $$;
+REVOKE ALL ON FUNCTION app.scaffold_scope(regclass, text, boolean) FROM public, anon, authenticated;
+
+COMMENT ON FUNCTION app.scaffold_scope(regclass, text, boolean) IS
+  'Declare what unit_id means on a scaffolded table and make the schema enforce it (#225). Folding this into app.scaffold_table''s signature waits for #224, which changes that signature anyway to add `distributable` — one signature change instead of two.';
+
+-- ── classify all 47 ─────────────────────────────────────────────────────
+-- ENFORCEMENT IS EVIDENCE, NOT INFERENCE.
+--
+-- The first version of this block applied NOT NULL wherever no row violated it.
+-- Nine suites went red — orders, the migration ledger's extractor writers, two
+-- financial suites — and every one of those tables was EMPTY when the constraint
+-- landed. An empty table proves nothing about whether its writers fill the
+-- column; it only proves nobody has written yet. So NOT NULL is applied to the
+-- tables whose writers are demonstrated by the suites to fill a unit, and every
+-- other `unit` table is declared and listed instead.
+--
+-- The declaration is most of the value on its own: it is what makes the NULL on
+-- `holidays` legibly different from the NULL on `orders`, and it is what a
+-- reader (and #224) can check.
+DO $$
+DECLARE
+  -- writers proven to fill a unit: the inventory ledger and the access grants
+  v_unit_enforced text[] := ARRAY[
+    'plg_inventory_stock_locations','plg_inventory_stock_movements',
+    'plg_inventory_stock_positions','plg_inventory_reservations','access_grants'];
+  -- declared `unit` — this is where it happened — but the writers have not been
+  -- audited yet, so the column stays nullable and the table stays on the list
+  v_unit_declared text[] := ARRAY[
+    'appointments','appointment_items','orders','order_items','schedules',
+    'plg_financial_movements','plg_financial_invoices','plg_financial_invoice_installments',
+    'plg_financial_allocations','plg_financial_nfe','plg_financial_cash_register_sessions',
+    'plg_financial_cash_session_reviewers'];
+  -- `transactions` is deliberately in neither: it is the pre-plugin money row
+  -- (#187) and its writers never learned about units. Declaring it `unit` would
+  -- describe an intention nobody holds. unit_optional until #187 moves that money
+  -- into the ledger, which is the change that would give each row a branch
+  -- honestly.
+  -- NOTHING in core is `tenant` today, and finding that out is the useful part.
+  --
+  -- The catalogue was going to be: 075 says in prose that it is "a tenant-wide
+  -- resource: unit_id is null by default", so a CHECK looked like that sentence
+  -- made enforceable. 085's own pgTAP says otherwise — 002_release_visibility
+  -- creates "Vela B2", a product that BELONGS to a branch, and asserts it behaves
+  -- that way. The RESTRICTIVE policy's `unit_id IS NOT NULL OR available_in…`
+  -- exists for exactly that row.
+  --
+  -- So "two ways to say only at Centro" was overstated, and this file is where it
+  -- gets corrected: `unit_id` set means the branch's OWN item, which is never
+  -- shared; a grant means the NETWORK's item, released there. Same visible
+  -- effect, different things, and only the second is distribution. `tenant` stays
+  -- in the vocabulary for #224 to apply where distribution really is the only
+  -- mechanism — the class is exercised by 055/004 either way.
+  v_tenant text[] := ARRAY[]::text[];
+  t text; v_n integer := 0;
+BEGIN
+  FOREACH t IN ARRAY v_unit_enforced LOOP
+    CONTINUE WHEN to_regclass('public.' || t) IS NULL;
+    -- The spine runs before the plugins, so on a FRESH pool a plugin's table is
+    -- simply absent here and the guard above skips it. On a pool that already
+    -- carries an older install of that plugin the table IS present while its own
+    -- scaffold file has not run yet, and scaffold_scope refuses a table it has
+    -- never registered. Skipping is right in both cases: the plugin's scaffold
+    -- classifies it when it runs, a few files later in this same chain.
+    CONTINUE WHEN NOT EXISTS (
+      SELECT 1 FROM app.scaffold_registry
+       WHERE table_schema = 'public' AND table_name = t);
+    PERFORM app.scaffold_scope(('public.' || t)::regclass, 'unit', true); v_n := v_n + 1;
+  END LOOP;
+  FOREACH t IN ARRAY v_unit_declared LOOP
+    CONTINUE WHEN to_regclass('public.' || t) IS NULL;
+    CONTINUE WHEN NOT EXISTS (SELECT 1 FROM app.scaffold_registry
+                               WHERE table_schema = 'public' AND table_name = t);
+    PERFORM app.scaffold_scope(('public.' || t)::regclass, 'unit', false); v_n := v_n + 1;
+  END LOOP;
+  FOREACH t IN ARRAY v_tenant LOOP
+    CONTINUE WHEN to_regclass('public.' || t) IS NULL;
+    CONTINUE WHEN NOT EXISTS (SELECT 1 FROM app.scaffold_registry
+                               WHERE table_schema = 'public' AND table_name = t);
+    PERFORM app.scaffold_scope(('public.' || t)::regclass, 'tenant'); v_n := v_n + 1;
+  END LOOP;
+  FOR t IN SELECT r.table_name FROM app.scaffold_registry r
+            WHERE r.scope IS NULL AND r.table_schema = 'public'
+              AND to_regclass(format('%I.%I', r.table_schema, r.table_name)) IS NOT NULL LOOP
+    -- No registry guard here: this loop reads FROM the registry.
+    PERFORM app.scaffold_scope(('public.' || t)::regclass, 'unit_optional'); v_n := v_n + 1;
+  END LOOP;
+  RAISE NOTICE '126: classified % scaffolded table(s); % awaiting a writer audit',
+    v_n, (SELECT count(*) FROM app.scaffold_scope_pending);
+END $$;

package/migrations/137_vendor_named_spine_objects.sql

@@ -0,0 +1,126 @@
+-- ============================================================================
+-- 137_vendor_named_spine_objects.sql — the schema stops naming the vendor (#181).
+--
+-- `public.fayz_projects` holds THE SITE A TENANT PUBLISHES. The provider might be
+-- Fayz, Wix, WordPress or a custom host — that is an attribute of the row, not
+-- the identity of the table. Same for the search registry.
+--
+--   public.fayz_projects        → public.published_sites
+--     fayz_project_id           →   provider_site_id
+--     (new)                     →   provider text NOT NULL DEFAULT 'fayz'
+--   public.fayz_search_sources  → public.search_sources
+--   public.fayz_global_search() → public.global_search()
+--
+-- WHAT DELIBERATELY KEEPS THE PREFIX, and why it is not the same smell:
+--
+--   fayz_norm / fayz_digits / fayz_cat — SQL helpers whose names are baked into
+--     the `haystack_expr` STRINGS stored in the registry rows. Renaming them is a
+--     data migration of every deployed row, for functions that are internal
+--     plumbing rather than an entity anyone names. Not worth the blast radius.
+--   fayz_audit_prune / fayz_authz_reconcile / fayz_sync_* — pg_cron job names.
+--     Cron lives in a database shared with everything else on the instance; there
+--     the prefix IS the namespace, which is the opposite of a smell.
+--   fayz_functions_url / fayz_scheduler_secret — vault secret keys. Same
+--     argument: a shared keyspace wants a prefix.
+--
+-- NO COMPAT VIEW UNDER THE OLD NAME. 097 settled this: frozen migrations re-run
+-- `ALTER TABLE` and `CREATE POLICY` against the old name on a replay, and those
+-- fail on a view. A guarded rename converges instead — it fires only when the old
+-- name is there and the new one is not.
+--
+-- ⚠ CROSS-REPO: the platform (ymaia) writes these rows. There is no compat layer,
+-- so ymaia's writers move to `published_sites` / `provider_site_id` in the same
+-- deploy. That coordination is the whole reason #181 carried `decision-needed`.
+--
+-- Replay-safe: every step guarded on the object's current name.
+-- ============================================================================
+
+-- ── public.fayz_projects → public.published_sites ───────────────────────
+DO $$
+BEGIN
+  IF to_regclass('public.fayz_projects') IS NOT NULL AND to_regclass('public.published_sites') IS NULL THEN
+    ALTER TABLE public.fayz_projects RENAME TO published_sites;
+
+    IF EXISTS (SELECT 1 FROM information_schema.columns
+                WHERE table_schema = 'public' AND table_name = 'published_sites' AND column_name = 'fayz_project_id') THEN
+      ALTER TABLE public.published_sites RENAME COLUMN fayz_project_id TO provider_site_id;
+    END IF;
+
+    ALTER INDEX IF EXISTS public.fayz_projects_tenant_idx RENAME TO published_sites_tenant_idx;
+    ALTER INDEX IF EXISTS public.fayz_projects_one_default_per_tenant RENAME TO published_sites_one_default_per_tenant;
+    ALTER INDEX IF EXISTS public.fayz_projects_pkey RENAME TO published_sites_pkey;
+
+    DROP TRIGGER IF EXISTS fayz_projects_updated_at ON public.published_sites;
+    DROP TRIGGER IF EXISTS published_sites_updated_at ON public.published_sites;
+    CREATE TRIGGER published_sites_updated_at BEFORE UPDATE ON public.published_sites
+      FOR EACH ROW EXECUTE FUNCTION public.handle_updated_at();
+
+    DROP POLICY IF EXISTS "fayz_projects_member_all" ON public.published_sites;
+    DROP POLICY IF EXISTS "published_sites_member_all" ON public.published_sites;
+    CREATE POLICY "published_sites_member_all" ON public.published_sites FOR ALL TO authenticated
+      USING (tenant_id IN (SELECT public.user_tenant_ids()))
+      WITH CHECK (tenant_id IN (SELECT public.user_tenant_ids()));
+
+    RAISE NOTICE '127: fayz_projects → published_sites';
+  END IF;
+END $$;
+
+-- the provider becomes a column, which is the point of the rename
+ALTER TABLE public.published_sites ADD COLUMN IF NOT EXISTS provider text NOT NULL DEFAULT 'fayz';
+
+COMMENT ON TABLE public.published_sites IS
+  'A site or app a tenant publishes. `provider` says who hosts it (fayz | wix | wordpress | custom | …) and `provider_site_id` is that provider''s own id — the vendor is an attribute here, never the table''s identity (#181).';
+COMMENT ON COLUMN public.published_sites.provider IS
+  'Who hosts this site. Defaults to fayz because every row that existed before #181 was a fayz project.';
+COMMENT ON COLUMN public.published_sites.provider_site_id IS
+  'The provider''s own id for this site (was fayz_project_id). Text: each provider issues its own.';
+
+-- ── public.fayz_search_sources → public.search_sources ──────────────────
+DO $$
+BEGIN
+  IF to_regclass('public.fayz_search_sources') IS NOT NULL AND to_regclass('public.search_sources') IS NULL THEN
+    ALTER TABLE public.fayz_search_sources RENAME TO search_sources;
+    ALTER INDEX IF EXISTS public.fayz_search_sources_pkey RENAME TO search_sources_pkey;
+    DROP POLICY IF EXISTS "fayz_search_sources_read" ON public.search_sources;
+    DROP POLICY IF EXISTS "search_sources_read" ON public.search_sources;
+    CREATE POLICY "search_sources_read" ON public.search_sources FOR SELECT TO authenticated USING (true);
+    RAISE NOTICE '127: fayz_search_sources → search_sources';
+  END IF;
+END $$;
+
+COMMENT ON TABLE public.search_sources IS
+  'Registry of searchable relations for public.global_search(). Readable by any member, writable only by the migration role — the expressions are executed as SQL.';
+
+-- ── public.fayz_global_search() → public.global_search() ────────────────
+-- Renamed by re-emitting under the new name and dropping the old, rather than
+-- ALTER FUNCTION … RENAME: the body reads `fayz_search_sources`, which no longer
+-- exists, so it has to be rewritten anyway.
+DO $$
+DECLARE v_src text; v_args text;
+BEGIN
+  -- Already renamed? Then leave both names alone. 141 puts a compat WRAPPER back
+  -- under `fayz_global_search`, so a re-run of this file finds that wrapper and
+  -- would try to convert it into `global_search` a second time — over a function
+  -- that exists, with a signature that no longer matches, which fails on the
+  -- parameter defaults. The rename is done; the old name answering again is the
+  -- bridge doing its job, not work left over.
+  IF to_regproc('public.global_search') IS NOT NULL THEN
+    RETURN;
+  END IF;
+
+  SELECT pg_get_functiondef(p.oid), pg_get_function_identity_arguments(p.oid)
+    INTO v_src, v_args
+    FROM pg_proc p JOIN pg_namespace n ON n.oid = p.pronamespace
+   WHERE n.nspname = 'public' AND p.proname = 'fayz_global_search'
+   LIMIT 1;
+
+  IF v_src IS NOT NULL THEN
+    v_src := replace(v_src, 'public.fayz_global_search', 'public.global_search');
+    v_src := replace(v_src, 'fayz_search_sources', 'search_sources');
+    EXECUTE v_src;
+    EXECUTE format('DROP FUNCTION IF EXISTS public.fayz_global_search(%s)', v_args);
+    EXECUTE 'REVOKE ALL ON FUNCTION public.global_search(' || v_args || ') FROM public, anon';
+    EXECUTE 'GRANT EXECUTE ON FUNCTION public.global_search(' || v_args || ') TO authenticated, service_role';
+    RAISE NOTICE '127: fayz_global_search() → global_search()';
+  END IF;
+END $$;

package/migrations/138_grants_inherit_down_the_tree.sql

@@ -0,0 +1,178 @@
+-- ============================================================================
+-- 138_grants_inherit_down_the_tree.sql — distribution follows the hierarchy that
+-- access already follows (#227).
+--
+-- `user_unit_access` fans out by subtree: managing `f1` gives you `f1` and every
+-- branch under it, `via = 'subtree'`. `has_grant` did not: it matched a unit
+-- tuple only when the granted unit was LITERALLY one of your access rows. So:
+--
+--   grant names f1, caller manages f1     → matched
+--   grant names b1, caller manages f1     → matched (b1 arrived by subtree)
+--   grant names f1, caller works at b1    → DID NOT MATCH   ← the bug
+--
+-- "Release this service to the whole f1 region" reached the regional manager and
+-- not the people who work in its branches — the ones meant to sell it. Nobody
+-- reads that off the schema: you grant to a region, test as someone who holds
+-- the region, and ship.
+--
+-- PRECEDENCE, which is the part that needed deciding
+--
+-- Walking a chain means allow and deny can meet at different depths, so:
+--
+--   MOST SPECIFIC WINS. For each unit in scope, walk from the unit up to the
+--   root and stop at the first level carrying any tuple. Deny beats allow AT
+--   THAT LEVEL.
+--
+-- That is what makes both directions sayable: "the whole f1 region except b2" is
+-- deny at f1 + allow at b2, and "nowhere except b1" is one allow at b1. A blanket
+-- deny-always-wins would make the first one unsayable, and #223's rule ("deny
+-- wins") survives intact — it was always a statement about one level.
+--
+-- User- and role-subject tuples sit outside the walk entirely: the subject is the
+-- person, and a person is not in the tree.
+--
+-- Implementation (a) of the two the issue listed: walk at query time. The tree is
+-- shallow — tenant → region → branch — so this is a handful of index lookups, and
+-- it adds no second projection to keep honest. `user_unit_access` is materialised
+-- because it is read for every row of every query; a grant chain is read once per
+-- resource, which is a different problem.
+--
+-- Replay-safe: CREATE OR REPLACE only.
+-- ============================================================================
+
+-- ── the chain from a unit up to its root ────────────────────────────────
+CREATE OR REPLACE FUNCTION app.unit_chain(p_unit uuid)
+RETURNS TABLE (unit_id uuid, depth integer)
+LANGUAGE sql STABLE SECURITY DEFINER
+SET search_path = ''
+AS $$
+  WITH RECURSIVE up AS (
+    SELECT u.id, u.parent_unit_id, 0 AS depth
+      FROM app.units u WHERE u.id = p_unit
+    UNION ALL
+    SELECT u.id, u.parent_unit_id, up.depth + 1
+      FROM app.units u JOIN up ON u.id = up.parent_unit_id
+     WHERE up.depth < 32          -- a cycle cannot happen (parent <> id, FK per tenant), but a bound is cheap
+  )
+  SELECT up.id, up.depth FROM up;
+$$;
+REVOKE ALL ON FUNCTION app.unit_chain(uuid) FROM public, anon;
+GRANT EXECUTE ON FUNCTION app.unit_chain(uuid) TO authenticated, service_role;
+
+COMMENT ON FUNCTION app.unit_chain(uuid) IS
+  'A unit and its ancestors, nearest first (#227). Distribution tuples are resolved along this chain so a release to a region reaches its branches.';
+
+-- ── what the tuples say about one unit ──────────────────────────────────
+-- 'allow' | 'deny' | 'none'. The first level of the chain carrying any tuple
+-- decides, and deny beats allow at that level.
+CREATE OR REPLACE FUNCTION app.unit_release_verdict(p_type text, p_id uuid, p_unit uuid)
+RETURNS text
+LANGUAGE sql STABLE SECURITY DEFINER
+SET search_path = ''
+AS $$
+  SELECT coalesce(
+    (SELECT CASE WHEN bool_or(g.relation = 'unavailable_in') THEN 'deny' ELSE 'allow' END
+       FROM app.unit_chain(p_unit) c
+       JOIN app.resource_grants g
+         ON g.tenant_id = app.current_tenant_id()
+        AND g.resource_type = p_type AND g.resource_id = p_id
+        AND g.subject_type = 'unit' AND g.subject_id = c.unit_id
+        AND g.relation IN ('available_in', 'unavailable_in')
+      GROUP BY c.depth
+      ORDER BY c.depth
+      LIMIT 1),
+    'none');
+$$;
+REVOKE ALL ON FUNCTION app.unit_release_verdict(text, uuid, uuid) FROM public, anon;
+GRANT EXECUTE ON FUNCTION app.unit_release_verdict(text, uuid, uuid) TO authenticated, service_role;
+
+COMMENT ON FUNCTION app.unit_release_verdict(text, uuid, uuid) IS
+  'allow | deny | none for one unit (#227): the nearest level of its chain that carries a distribution tuple decides, and deny beats allow at that level. Most specific wins, which is what makes "the whole region except one branch" sayable.';
+
+-- ── the release rule, resolved along the tree ───────────────────────────
+-- Replaces the flat version of 125. The three shapes it has to keep true:
+--   no tuples at all                 → available (the default that predates #223)
+--   only inclusions                  → available where one names a unit in scope
+--   inclusions and exclusions mixed  → nearest level decides, per unit in scope
+CREATE OR REPLACE FUNCTION app.available_in_my_units(p_type text, p_id uuid)
+RETURNS boolean
+LANGUAGE sql STABLE SECURITY DEFINER
+SET search_path = ''
+AS $$
+  WITH me AS (
+    SELECT app.current_tenant_id() AS tenant_id,
+           auth.uid()              AS uid,
+           nullif(app.current_unit_id(), '00000000-0000-0000-0000-000000000000'::uuid) AS focus
+  ),
+  tup AS (
+    SELECT g.relation, g.subject_type, g.subject_id
+      FROM app.resource_grants g, me
+     WHERE g.tenant_id = me.tenant_id AND g.resource_type = p_type AND g.resource_id = p_id
+       AND g.relation IN ('available_in', 'unavailable_in')
+  ),
+  -- me, or a role of mine: outside the tree, so it simply decides
+  direct AS (
+    SELECT t.relation FROM tup t, me
+     WHERE (t.subject_type = 'user' AND t.subject_id = me.uid)
+        OR (t.subject_type = 'role' AND t.subject_id IN (
+              SELECT m.role_id FROM app.memberships m
+               WHERE m.tenant_id = me.tenant_id AND m.user_id = me.uid AND m.active
+              UNION
+              SELECT mu.role_override_id FROM app.membership_units mu
+               WHERE mu.tenant_id = me.tenant_id AND mu.user_id = me.uid AND mu.role_override_id IS NOT NULL))
+  ),
+  mine AS (
+    SELECT a.unit_id FROM app.user_unit_access a, me
+     WHERE a.tenant_id = me.tenant_id AND a.user_id = me.uid
+       AND (me.focus IS NULL OR a.unit_id = me.focus)
+  ),
+  verdicts AS (
+    SELECT app.unit_release_verdict(p_type, p_id, mine.unit_id) AS v FROM mine
+  )
+  SELECT NOT EXISTS (SELECT 1 FROM direct WHERE relation = 'unavailable_in')
+     AND (
+          EXISTS (SELECT 1 FROM direct WHERE relation = 'available_in')
+       OR EXISTS (SELECT 1 FROM verdicts WHERE v = 'allow')
+       OR (NOT EXISTS (SELECT 1 FROM tup WHERE relation = 'available_in')
+           AND (EXISTS (SELECT 1 FROM verdicts WHERE v = 'none') OR NOT EXISTS (SELECT 1 FROM mine)))
+     );
+$$;
+
+COMMENT ON FUNCTION app.available_in_my_units(text, uuid) IS
+  'The release rule, resolved along the unit tree (#223 + #227): no tuples ⇒ everywhere; otherwise the nearest level of each in-scope unit''s chain decides, deny beating allow at that level. A caller holding no units is not excluded by a rule about units.';
+
+-- ── has_grant: a unit tuple reaches the branches under it ───────────────
+-- 135's version with the ancestor walk. `shared_with` inherits for the same
+-- reason distribution does: sharing a record with a region has to mean sharing it
+-- with the people who work there, or the word means nothing.
+CREATE OR REPLACE FUNCTION app.has_grant(p_type text, p_id uuid, p_relations text[])
+RETURNS boolean
+LANGUAGE sql STABLE SECURITY DEFINER
+SET search_path = ''
+AS $$
+  SELECT EXISTS (
+    SELECT 1
+      FROM app.resource_grants g
+     WHERE g.tenant_id = app.current_tenant_id()
+       AND g.resource_type = p_type
+       AND g.resource_id = p_id
+       AND g.relation = ANY (p_relations)
+       AND (
+            (g.subject_type = 'user' AND g.subject_id = auth.uid())
+         OR (g.subject_type = 'unit' AND EXISTS (
+               SELECT 1 FROM app.user_unit_access a
+                WHERE a.tenant_id = g.tenant_id AND a.user_id = auth.uid()
+                  AND (app.current_unit_id() IS NULL OR a.unit_id = app.current_unit_id())
+                  AND EXISTS (SELECT 1 FROM app.unit_chain(a.unit_id) c WHERE c.unit_id = g.subject_id)))
+         OR (g.subject_type = 'role' AND g.subject_id IN (
+               SELECT m.role_id FROM app.memberships m
+                WHERE m.tenant_id = g.tenant_id AND m.user_id = auth.uid() AND m.active
+               UNION
+               SELECT mu.role_override_id FROM app.membership_units mu
+                WHERE mu.tenant_id = g.tenant_id AND mu.user_id = auth.uid() AND mu.role_override_id IS NOT NULL))
+       )
+  );
+$$;
+
+COMMENT ON FUNCTION app.has_grant(text, uuid, text[]) IS
+  'resource_grants where the subject is me, a role of mine, or a unit at or above one in scope (#220/#223/#227). Inheritance runs DOWN the tree: a tuple naming a region reaches the branches under it.';