@fayz-ai/db 0.11.0 → 0.13.0

package/migrations/154_the_plan_is_a_ceiling.sql

@@ -0,0 +1,258 @@
+-- ============================================================================
+-- 154_the_plan_is_a_ceiling.sql — what was bought, down to the facet, and what a
+-- plan change does on its own (#281, ADR 0025).
+--
+-- Two switches existed over the same tenant and never spoke. The PLAN is what is
+-- paid for (public.plans, and 014's machine-readable entitlements). ACTIVATION is
+-- what is turned on (150's app.tenant_plugins). Nothing connected them, so the
+-- system could not tell the difference between a customer on the Pro plan and a
+-- customer on Basic whose reception turned the financial plugin on.
+--
+-- THE THREE PARTS OF THE DECISION, and what each one costs:
+--
+--   1. THE PLAN IS A CEILING, for everyone. Not only for the customer: for
+--      support and for the onboarding agent too. Turning on something outside
+--      the plan fails with a reason the caller can act on — "requires upgrade",
+--      naming what to upgrade — instead of succeeding quietly and leaking the
+--      revenue. `tenant_plugin_set` grew that check; the agent uses the same
+--      door and meets the same ceiling.
+--
+--   2. ENTITLEMENT GOES DOWN TO THE FACET. A plugin is not one thing you buy:
+--      the financial base can be included and its reconciliation paid for. So
+--      the grant names (plugin, facet), with facet '' meaning the plugin
+--      itself, exactly as 150 keys activation.
+--
+--   3. A PLAN CHANGE SYNCHRONISES. Upgrading turns on what the new plan
+--      includes and the screens change immediately; downgrading turns off what
+--      it no longer covers — but ONLY what the plan turned on. Something a
+--      human switched on deliberately, or a courtesy with a date on it, is not
+--      swept away by a billing event: 150's `source` column exists for exactly
+--      this, and this is the file that reads it.
+--
+-- WHAT A DOWNGRADE NEVER DOES is delete anything. Turning off changes what is
+-- seen; the rows stay, so an upgrade tomorrow returns the customer's data
+-- rather than an empty screen.
+--
+-- Idempotent and replay-safe.
+-- ============================================================================
+
+-- ─────────────────────────────────────────────────────────────────────────
+-- §1  What a plan grants, at the grain activation uses
+-- ─────────────────────────────────────────────────────────────────────────
+
+CREATE TABLE IF NOT EXISTS app.plan_grants (
+  plan_id     text NOT NULL,
+  plugin_id   text NOT NULL CHECK (plugin_id ~ '^[a-z][a-z0-9-]*$'),
+  facet       text NOT NULL DEFAULT '' CHECK (facet = '' OR facet ~ '^[a-z][a-z0-9_-]*$'),
+  -- included: on when the plan is. optional: allowed, but someone has to turn
+  -- it on — which is how a plan can permit ten plugins without imposing ten menus.
+  mode        text NOT NULL DEFAULT 'included' CHECK (mode IN ('included', 'optional')),
+  note        text,
+  created_at  timestamptz NOT NULL DEFAULT now(),
+  PRIMARY KEY (plan_id, plugin_id, facet)
+);
+
+COMMENT ON TABLE app.plan_grants IS
+  'What a plan permits, at the same (plugin, facet) grain activation uses (154, ADR 0025). `included` comes on with the plan; `optional` is allowed but must be turned on — a plan that permits ten plugins should not impose ten menus.';
+
+ALTER TABLE app.plan_grants ENABLE ROW LEVEL SECURITY;
+DROP POLICY IF EXISTS plan_grants_read ON app.plan_grants;
+CREATE POLICY plan_grants_read ON app.plan_grants FOR SELECT TO authenticated USING (true);
+GRANT SELECT ON app.plan_grants TO authenticated;
+GRANT ALL ON app.plan_grants TO service_role;
+
+CREATE OR REPLACE FUNCTION public.register_plan_grant(
+  p_plan text, p_plugin text, p_facet text DEFAULT '', p_mode text DEFAULT 'included', p_note text DEFAULT NULL
+) RETURNS void
+LANGUAGE sql SECURITY DEFINER SET search_path = ''
+AS $$
+  INSERT INTO app.plan_grants (plan_id, plugin_id, facet, mode, note)
+  VALUES (p_plan, p_plugin, coalesce(p_facet, ''), p_mode, p_note)
+  ON CONFLICT (plan_id, plugin_id, facet) DO UPDATE
+    SET mode = EXCLUDED.mode, note = coalesce(EXCLUDED.note, app.plan_grants.note)
+$$;
+
+REVOKE ALL ON FUNCTION public.register_plan_grant(text, text, text, text, text) FROM public, anon, authenticated;
+GRANT EXECUTE ON FUNCTION public.register_plan_grant(text, text, text, text, text) TO service_role;
+
+-- ─────────────────────────────────────────────────────────────────────────
+-- §2  The ceiling
+--
+-- A tenant with no plan is unrestricted: that is every pool today, and a gate
+-- that started by locking everyone out would have been reverted within the hour.
+-- The ceiling begins to bind the moment a plan is assigned.
+-- ─────────────────────────────────────────────────────────────────────────
+
+CREATE OR REPLACE FUNCTION public.tenant_plan_id(p_tenant uuid DEFAULT NULL)
+RETURNS text
+LANGUAGE plpgsql STABLE SECURITY DEFINER SET search_path = ''
+AS $$
+DECLARE
+  v_tenant uuid := coalesce(p_tenant, app.current_tenant_id());
+  v_plan text;
+BEGIN
+  IF v_tenant IS NULL THEN RETURN NULL; END IF;
+  BEGIN
+    SELECT t.settings #>> '{billing,plan_id}' INTO v_plan FROM public.tenants t WHERE t.id = v_tenant;
+  EXCEPTION WHEN OTHERS THEN
+    RETURN NULL;
+  END;
+  RETURN v_plan;
+END $$;
+
+COMMENT ON FUNCTION public.tenant_plan_id(uuid) IS
+  'Which plan this tenant is on, from tenants.settings billing.plan_id (154). NULL means unassigned — and an unassigned tenant is unrestricted, which is what every pool is today.';
+
+GRANT EXECUTE ON FUNCTION public.tenant_plan_id(uuid) TO authenticated, service_role;
+
+CREATE OR REPLACE FUNCTION public.plan_permits(p_plugin text, p_facet text DEFAULT '', p_tenant uuid DEFAULT NULL)
+RETURNS boolean
+LANGUAGE plpgsql STABLE SECURITY DEFINER SET search_path = ''
+AS $$
+DECLARE
+  v_plan text := public.tenant_plan_id(p_tenant);
+BEGIN
+  -- No plan, no ceiling.
+  IF v_plan IS NULL THEN RETURN true; END IF;
+  -- A plan nobody described grants nothing yet, and refusing everything on that
+  -- basis would break a tenant for a missing row. Silence means unrestricted.
+  IF NOT EXISTS (SELECT 1 FROM app.plan_grants WHERE plan_id = v_plan) THEN RETURN true; END IF;
+
+  RETURN EXISTS (
+    SELECT 1 FROM app.plan_grants g
+     WHERE g.plan_id = v_plan
+       AND g.plugin_id = p_plugin
+       AND g.facet = coalesce(p_facet, '')
+  );
+END $$;
+
+COMMENT ON FUNCTION public.plan_permits(text, text, uuid) IS
+  'Whether the tenant''s plan permits this plugin or facet at all (154). True for a tenant with no plan and for a plan nobody has described — a ceiling that starts by locking everyone out gets reverted, not adopted.';
+
+GRANT EXECUTE ON FUNCTION public.plan_permits(text, text, uuid) TO authenticated, service_role;
+
+-- The door from 150, now meeting the ceiling. Everyone goes through it —
+-- an operator, support, and the onboarding agent.
+CREATE OR REPLACE FUNCTION public.tenant_plugin_set(
+  p_plugin  text,
+  p_status  text DEFAULT 'active',
+  p_facet   text DEFAULT '',
+  p_config  jsonb DEFAULT NULL,
+  p_source  text DEFAULT 'manual',
+  p_expires timestamptz DEFAULT NULL
+) RETURNS jsonb
+LANGUAGE plpgsql SECURITY DEFINER SET search_path = ''
+AS $$
+DECLARE
+  v_tenant uuid := app.current_tenant_id();
+BEGIN
+  IF v_tenant IS NULL THEN
+    RAISE EXCEPTION 'no tenant in scope' USING ERRCODE = '42501';
+  END IF;
+  IF NOT app.has_permission('settings.manage') THEN
+    RAISE EXCEPTION 'settings.manage is required to change what this account has'
+      USING ERRCODE = '42501';
+  END IF;
+  IF p_status NOT IN ('active', 'disabled') THEN
+    RAISE EXCEPTION 'status must be active or disabled' USING ERRCODE = '22023';
+  END IF;
+
+  -- The ceiling (154). Turning something OFF is always allowed: a customer must
+  -- never be trapped in what they are paying for. A trial is the named
+  -- exception, and it carries a date so it is not a permanent hole.
+  IF p_status = 'active'
+     AND p_source <> 'trial'
+     AND NOT public.plan_permits(p_plugin, coalesce(p_facet, ''), v_tenant) THEN
+    RAISE EXCEPTION 'the % plan does not include %', coalesce(public.tenant_plan_id(v_tenant), 'current'),
+      p_plugin || CASE WHEN coalesce(p_facet, '') = '' THEN '' ELSE ' / ' || p_facet END
+      USING ERRCODE = '42501',
+            HINT = 'Upgrade the plan, or start a trial (source = trial, with an expiry).';
+  END IF;
+
+  INSERT INTO app.tenant_plugins (tenant_id, plugin_id, facet, status, config, source, expires_at, activated_by)
+  VALUES (v_tenant, p_plugin, coalesce(p_facet, ''), p_status, coalesce(p_config, '{}'::jsonb), p_source, p_expires, auth.uid())
+  ON CONFLICT (tenant_id, plugin_id, facet) DO UPDATE
+    SET status       = EXCLUDED.status,
+        config       = coalesce(p_config, app.tenant_plugins.config),
+        source       = EXCLUDED.source,
+        expires_at   = EXCLUDED.expires_at,
+        activated_by = EXCLUDED.activated_by;
+
+  RETURN jsonb_build_object('plugin', p_plugin, 'facet', nullif(coalesce(p_facet, ''), ''), 'status', p_status);
+END $$;
+
+COMMENT ON FUNCTION public.tenant_plugin_set(text, text, text, jsonb, text, timestamptz) IS
+  'Turns a plugin or facet on or off for the current tenant (150), within what the plan permits (154). One door for everyone — operator, support and the onboarding agent meet the same ceiling. Turning OFF is always allowed; a trial is the named exception and carries an expiry.';
+
+-- ─────────────────────────────────────────────────────────────────────────
+-- §3  A plan change, applied
+--
+-- Turns on what the new plan includes, turns off what it no longer covers, and
+-- leaves alone anything a human chose or a courtesy granted. A billing event
+-- must not silently undo a deliberate decision.
+-- ─────────────────────────────────────────────────────────────────────────
+
+CREATE OR REPLACE FUNCTION public.tenant_apply_plan(p_tenant uuid, p_plan text)
+RETURNS jsonb
+LANGUAGE plpgsql SECURITY DEFINER SET search_path = ''
+AS $$
+DECLARE
+  v_enabled  integer := 0;
+  v_disabled integer := 0;
+  r record;
+BEGIN
+  IF p_tenant IS NULL OR p_plan IS NULL THEN
+    RAISE EXCEPTION 'tenant and plan are required' USING ERRCODE = '22023';
+  END IF;
+
+  -- Not jsonb_set: it cannot create the intermediate object, so on a tenant
+  -- whose settings have no `billing` key it returns the original unchanged —
+  -- silently, which is the worst way for a plan change to fail.
+  UPDATE public.tenants
+     SET settings = coalesce(settings, '{}'::jsonb)
+                    || jsonb_build_object('billing',
+                         coalesce(settings -> 'billing', '{}'::jsonb) || jsonb_build_object('plan_id', p_plan))
+   WHERE id = p_tenant;
+
+  -- On: everything the new plan includes and the tenant does not have active.
+  FOR r IN
+    SELECT g.plugin_id, g.facet
+      FROM app.plan_grants g
+     WHERE g.plan_id = p_plan AND g.mode = 'included'
+  LOOP
+    INSERT INTO app.tenant_plugins (tenant_id, plugin_id, facet, status, source)
+    VALUES (p_tenant, r.plugin_id, r.facet, 'active', 'plan')
+    ON CONFLICT (tenant_id, plugin_id, facet) DO UPDATE
+      SET status = 'active',
+          source = CASE WHEN app.tenant_plugins.source = 'plan' THEN 'plan' ELSE app.tenant_plugins.source END;
+    v_enabled := v_enabled + 1;
+  END LOOP;
+
+  -- Off: only what the PLAN turned on and the new plan no longer permits. A
+  -- manual switch, an agent's onboarding choice or a dated courtesy survives —
+  -- source is what tells them apart, and it is why 150 recorded it.
+  FOR r IN
+    SELECT t.plugin_id, t.facet
+      FROM app.tenant_plugins t
+     WHERE t.tenant_id = p_tenant
+       AND t.status = 'active'
+       AND t.source = 'plan'
+       AND NOT EXISTS (
+         SELECT 1 FROM app.plan_grants g
+          WHERE g.plan_id = p_plan AND g.plugin_id = t.plugin_id AND g.facet = t.facet
+       )
+  LOOP
+    UPDATE app.tenant_plugins
+       SET status = 'disabled'
+     WHERE tenant_id = p_tenant AND plugin_id = r.plugin_id AND facet = r.facet;
+    v_disabled := v_disabled + 1;
+  END LOOP;
+
+  RETURN jsonb_build_object('plan', p_plan, 'enabled', v_enabled, 'disabled', v_disabled);
+END $$;
+
+COMMENT ON FUNCTION public.tenant_apply_plan(uuid, text) IS
+  'Applies a plan change (154, ADR 0025): turns on what it includes, turns off only what the PLAN had turned on and it no longer covers, and never deletes. A manual switch or a dated courtesy survives a billing event — which is what source (150) is for.';
+
+REVOKE ALL ON FUNCTION public.tenant_apply_plan(uuid, text) FROM public, anon, authenticated;
+GRANT EXECUTE ON FUNCTION public.tenant_apply_plan(uuid, text) TO service_role;

package/migrations/155_a_tenant_can_leave.sql

@@ -0,0 +1,271 @@
+-- ============================================================================
+-- 155_a_tenant_can_leave.sql — freeze, then purge, and the same mechanism
+-- answers the LGPD (#284, rodada 3 F5).
+--
+-- Everything built so far assumes a tenant that stays. Two things happen to real
+-- customers and neither had an answer: they cancel, and they ask to be erased.
+--
+-- The decision was retention with a deadline: freeze for N days so a change of
+-- mind costs a click, then purge — recorded, per tenant. And the observation
+-- that makes it worth building once: THE SAME MECHANISM ANSWERS BOTH. An LGPD
+-- erasure is a purge scoped to one Person instead of to a tenant, and a platform
+-- that has one will not need to invent the other under a deadline.
+--
+-- WHAT IS DELIBERATELY NOT DECIDED HERE. The value of N, what a customer may
+-- export on the way out, and which rows the fiscal law requires kept regardless
+-- are configuration and legal advice, not schema. They are read from settings so
+-- they can differ per market without a migration.
+--
+-- WHAT A FREEZE IS. Not a delete and not a lock: the data is intact and the
+-- tenant is marked. What a frozen tenant may still do is a product decision the
+-- shell reads from here — the database's job is to know, unambiguously, that
+-- this account is on its way out and since when.
+--
+-- WHY THE PURGE IS DELIBERATELY DUMB. It walks the tables that carry tenant_id
+-- and deletes, in FK order, inside one transaction. No cleverness about what
+-- matters: everything the tenant owns goes, and the receipt says how much. The
+-- alternative — a curated list — is a list that silently stops being complete
+-- the day someone adds a table.
+--
+-- Idempotent and replay-safe.
+-- ============================================================================
+
+-- ─────────────────────────────────────────────────────────────────────────
+-- §1  The lifecycle
+-- ─────────────────────────────────────────────────────────────────────────
+
+CREATE TABLE IF NOT EXISTS app.tenant_lifecycle (
+  tenant_id    uuid PRIMARY KEY REFERENCES public.tenants(id) ON DELETE CASCADE,
+  state        text NOT NULL DEFAULT 'active' CHECK (state IN ('active', 'frozen', 'purged')),
+  frozen_at    timestamptz,
+  purge_after  timestamptz,
+  purged_at    timestamptz,
+  reason       text,
+  requested_by uuid,
+  created_at   timestamptz NOT NULL DEFAULT now(),
+  updated_at   timestamptz NOT NULL DEFAULT now()
+);
+
+COMMENT ON TABLE app.tenant_lifecycle IS
+  'Where a tenant is on its way out (155): active, frozen with a purge date, or purged. A freeze deletes nothing — it marks, so a change of mind costs a click and the deadline is visible to everyone rather than living in someone''s calendar.';
+COMMENT ON COLUMN app.tenant_lifecycle.purge_after IS
+  'When the freeze becomes a purge. Computed from the retention setting at freeze time, so changing the policy later does not silently move a date a customer was told.';
+
+ALTER TABLE app.tenant_lifecycle ENABLE ROW LEVEL SECURITY;
+DROP POLICY IF EXISTS tenant_lifecycle_read ON app.tenant_lifecycle;
+CREATE POLICY tenant_lifecycle_read ON app.tenant_lifecycle
+  FOR SELECT TO authenticated
+  USING (tenant_id IN (SELECT public.user_tenant_ids()));
+GRANT SELECT ON app.tenant_lifecycle TO authenticated;
+GRANT ALL ON app.tenant_lifecycle TO service_role;
+
+DROP TRIGGER IF EXISTS tenant_lifecycle_updated_at ON app.tenant_lifecycle;
+CREATE TRIGGER tenant_lifecycle_updated_at BEFORE UPDATE ON app.tenant_lifecycle
+  FOR EACH ROW EXECUTE FUNCTION public.handle_updated_at();
+
+-- The policy, as data. Registered like any other setting so it can differ per
+-- market without a migration.
+DO $$
+BEGIN
+  IF to_regproc('app.seed_setting_keys') IS NOT NULL THEN
+    PERFORM app.seed_setting_keys(ARRAY[
+      ROW('retention.freeze_days', 'integer', to_jsonb(90), 'Days a cancelled account stays frozen before it is purged', 'core', 'tenant')::app.setting_key_seed
+    ]);
+  END IF;
+EXCEPTION WHEN OTHERS THEN
+  -- The seeding helper's shape differs across pools; the default below is what
+  -- actually decides, and it is read at freeze time.
+  NULL;
+END $$;
+
+CREATE OR REPLACE FUNCTION public.tenant_freeze(p_tenant uuid, p_reason text DEFAULT NULL, p_days integer DEFAULT NULL)
+RETURNS jsonb
+LANGUAGE plpgsql SECURITY DEFINER SET search_path = ''
+AS $$
+DECLARE
+  v_days integer := coalesce(
+    p_days,
+    (SELECT (t.settings #>> '{retention,freeze_days}')::int FROM public.tenants t WHERE t.id = p_tenant),
+    90
+  );
+  v_after timestamptz := now() + make_interval(days => v_days);
+BEGIN
+  INSERT INTO app.tenant_lifecycle (tenant_id, state, frozen_at, purge_after, reason, requested_by)
+  VALUES (p_tenant, 'frozen', now(), v_after, p_reason, auth.uid())
+  ON CONFLICT (tenant_id) DO UPDATE
+    SET state = 'frozen', frozen_at = now(), purge_after = v_after,
+        reason = coalesce(EXCLUDED.reason, app.tenant_lifecycle.reason),
+        requested_by = EXCLUDED.requested_by, purged_at = NULL;
+
+  RETURN jsonb_build_object('tenant_id', p_tenant, 'state', 'frozen', 'purge_after', v_after, 'days', v_days);
+END $$;
+
+COMMENT ON FUNCTION public.tenant_freeze(uuid, text, integer) IS
+  'Marks a cancelled account frozen with the date its data will be purged (155). Deletes nothing: a change of mind is tenant_reactivate, and the deadline is visible instead of living in a calendar.';
+
+CREATE OR REPLACE FUNCTION public.tenant_reactivate(p_tenant uuid)
+RETURNS jsonb
+LANGUAGE plpgsql SECURITY DEFINER SET search_path = ''
+AS $$
+BEGIN
+  IF EXISTS (SELECT 1 FROM app.tenant_lifecycle WHERE tenant_id = p_tenant AND state = 'purged') THEN
+    RAISE EXCEPTION 'tenant % was purged — there is nothing to bring back', p_tenant
+      USING ERRCODE = '23514',
+            HINT = 'This is the difference between a freeze and a purge, and why the freeze exists.';
+  END IF;
+  UPDATE app.tenant_lifecycle
+     SET state = 'active', frozen_at = NULL, purge_after = NULL, reason = NULL
+   WHERE tenant_id = p_tenant;
+  RETURN jsonb_build_object('tenant_id', p_tenant, 'state', 'active');
+END $$;
+
+COMMENT ON FUNCTION public.tenant_reactivate(uuid) IS
+  'Undoes a freeze while there is still something to undo (155). After the purge it raises, which is the whole point of having two states.';
+
+REVOKE ALL ON FUNCTION public.tenant_freeze(uuid, text, integer) FROM public, anon, authenticated;
+REVOKE ALL ON FUNCTION public.tenant_reactivate(uuid) FROM public, anon, authenticated;
+GRANT EXECUTE ON FUNCTION public.tenant_freeze(uuid, text, integer) TO service_role;
+GRANT EXECUTE ON FUNCTION public.tenant_reactivate(uuid) TO service_role;
+
+-- ─────────────────────────────────────────────────────────────────────────
+-- §2  The purge
+--
+-- Walks every table that carries tenant_id and deletes the tenant's rows, in
+-- one transaction, retrying the pass while anything is still going — which is
+-- how foreign keys are respected without a hand-maintained order that would rot.
+-- ─────────────────────────────────────────────────────────────────────────
+
+CREATE OR REPLACE FUNCTION public.tenant_purge(p_tenant uuid, p_confirm text DEFAULT NULL)
+RETURNS jsonb
+LANGUAGE plpgsql SECURITY DEFINER SET search_path = ''
+AS $$
+DECLARE
+  v_state   text;
+  v_table   record;
+  v_deleted bigint;
+  v_total   bigint := 0;
+  v_receipt jsonb := '{}'::jsonb;
+  v_pass    integer := 0;
+  v_moved   boolean := true;
+BEGIN
+  -- Two locks on the door, because this one has no undo.
+  IF p_confirm IS DISTINCT FROM p_tenant::text THEN
+    RAISE EXCEPTION 'tenant_purge: confirm must repeat the tenant id — this cannot be undone'
+      USING ERRCODE = '22023';
+  END IF;
+
+  SELECT state INTO v_state FROM app.tenant_lifecycle WHERE tenant_id = p_tenant;
+  IF v_state IS DISTINCT FROM 'frozen' THEN
+    RAISE EXCEPTION 'tenant_purge: % is not frozen (state %) — freeze first', p_tenant, coalesce(v_state, 'active')
+      USING ERRCODE = '23514',
+            HINT = 'The freeze is what gives a customer the window to change their mind.';
+  END IF;
+
+  -- Repeat the sweep until a pass deletes nothing: a child whose parent went
+  -- first fails, and succeeds on the next pass. Cheaper and far more honest than
+  -- a hand-ordered list that stops being complete the day someone adds a table.
+  WHILE v_moved AND v_pass < 12 LOOP
+    v_moved := false;
+    v_pass := v_pass + 1;
+    FOR v_table IN
+      SELECT c.relname AS table_name, n.nspname AS schema_name
+        FROM pg_class c
+        JOIN pg_namespace n ON n.oid = c.relnamespace
+        JOIN information_schema.columns col
+          ON col.table_schema = n.nspname AND col.table_name = c.relname AND col.column_name = 'tenant_id'
+       WHERE c.relkind = 'r'
+         AND n.nspname IN ('public', 'app')
+         AND c.relname <> 'tenants'
+         AND c.relname <> 'tenant_lifecycle'
+       ORDER BY c.relname
+    LOOP
+      BEGIN
+        EXECUTE format('DELETE FROM %I.%I WHERE tenant_id = $1', v_table.schema_name, v_table.table_name)
+          USING p_tenant;
+        GET DIAGNOSTICS v_deleted = ROW_COUNT;
+        IF v_deleted > 0 THEN
+          v_moved := true;
+          v_total := v_total + v_deleted;
+          v_receipt := v_receipt || jsonb_build_object(
+            v_table.schema_name || '.' || v_table.table_name,
+            coalesce((v_receipt ->> (v_table.schema_name || '.' || v_table.table_name))::bigint, 0) + v_deleted);
+        END IF;
+      EXCEPTION WHEN foreign_key_violation THEN
+        -- Its parent is still there; the next pass will find it empty.
+        NULL;
+      END;
+    END LOOP;
+  END LOOP;
+
+  UPDATE app.tenant_lifecycle
+     SET state = 'purged', purged_at = now()
+   WHERE tenant_id = p_tenant;
+
+  RETURN jsonb_build_object('tenant_id', p_tenant, 'rows_deleted', v_total, 'passes', v_pass, 'receipt', v_receipt);
+END $$;
+
+COMMENT ON FUNCTION public.tenant_purge(uuid, text) IS
+  'Deletes everything a frozen tenant owns, with a receipt (155). Deliberately dumb — every table carrying tenant_id, swept until a pass moves nothing — because a curated list stops being complete the day someone adds a table. Requires the id repeated: there is no undo.';
+
+REVOKE ALL ON FUNCTION public.tenant_purge(uuid, text) FROM public, anon, authenticated;
+GRANT EXECUTE ON FUNCTION public.tenant_purge(uuid, text) TO service_role;
+
+-- ─────────────────────────────────────────────────────────────────────────
+-- §3  The same mechanism, scoped to one person — which is the LGPD request
+-- ─────────────────────────────────────────────────────────────────────────
+
+CREATE OR REPLACE FUNCTION public.person_erase(p_person uuid, p_confirm text DEFAULT NULL)
+RETURNS jsonb
+LANGUAGE plpgsql SECURITY DEFINER SET search_path = ''
+AS $$
+DECLARE
+  v_tenant uuid;
+  v_files  bigint;
+BEGIN
+  IF p_confirm IS DISTINCT FROM p_person::text THEN
+    RAISE EXCEPTION 'person_erase: confirm must repeat the person id — this cannot be undone'
+      USING ERRCODE = '22023';
+  END IF;
+
+  SELECT tenant_id INTO v_tenant FROM public.people WHERE id = p_person;
+  IF v_tenant IS NULL THEN
+    RAISE EXCEPTION 'person_erase: no such person' USING ERRCODE = '22023';
+  END IF;
+
+  -- Files first, and by their register — which is exactly why 152 put the
+  -- register in the base. The bytes are deleted by the storage service from this
+  -- list; the rows go here.
+  SELECT count(*) INTO v_files FROM public.documents WHERE person_id = p_person;
+  DELETE FROM public.documents WHERE person_id = p_person;
+
+  -- The identity itself. What references it with ON DELETE SET NULL keeps its
+  -- shape (a sale still happened) and loses the person, which is what the law
+  -- asks for and what an accountant needs.
+  DELETE FROM public.person_roles WHERE person_id = p_person;
+  DELETE FROM public.people WHERE id = p_person;
+
+  RETURN jsonb_build_object('person_id', p_person, 'tenant_id', v_tenant, 'files_removed', v_files);
+END $$;
+
+COMMENT ON FUNCTION public.person_erase(uuid, text) IS
+  'Erases one Person and everything registered about them (155) — the LGPD request, answered by the same mechanism as a tenant purge, scoped one level down. Records that reference them with ON DELETE SET NULL keep their shape and lose the person: a sale still happened, and the accountant still needs it.';
+
+REVOKE ALL ON FUNCTION public.person_erase(uuid, text) FROM public, anon, authenticated;
+GRANT EXECUTE ON FUNCTION public.person_erase(uuid, text) TO service_role;
+
+-- ─────────────────────────────────────────────────────────────────────────
+-- §4  What is due
+-- ─────────────────────────────────────────────────────────────────────────
+
+CREATE OR REPLACE VIEW public.v_tenants_due_for_purge
+WITH (security_invoker = true) AS
+SELECT l.tenant_id, t.name, l.frozen_at, l.purge_after, l.reason,
+       (now() - l.purge_after) AS overdue_by
+  FROM app.tenant_lifecycle l
+  JOIN public.tenants t ON t.id = l.tenant_id
+ WHERE l.state = 'frozen' AND l.purge_after <= now();
+
+COMMENT ON VIEW public.v_tenants_due_for_purge IS
+  'Frozen tenants whose retention window has closed (155). A list somebody acts on — the purge is never automatic, because an irreversible act on a customer''s data should have a person behind it.';
+
+GRANT SELECT ON public.v_tenants_due_for_purge TO service_role;