@fayz-ai/db 0.12.0 → 0.13.0

package/migrations/129_order_kind_terminal_states.sql

@@ -0,0 +1,57 @@
+-- 129_order_kind_terminal_states.sql
+--
+-- The four deferred kinds get the one rule nobody disputes. #140.
+--
+-- #140 asks for "an explicit sale state machine per kind". `sale` and `dine_in`
+-- carry the default machine; `appointment`, `service_order`, `quote` and `deal`
+-- declare their STATUSES and leave `transitions` NULL, with "lifecycle owned by
+-- plugin-agenda / plugin-crm" written beside each. `shop` and `purchase` are
+-- `{"*": ["*"]}` — deliberately free, because their documents are mirrored from
+-- systems that own the lifecycle outright.
+--
+-- That deferral is right: what a quote may do after it is `sent` is product
+-- design, and the slice that owns the quote should decide it. Inventing a
+-- workflow here would put agenda's and CRM's rules in the orders spine, which is
+-- exactly the coupling #146's convention exists to prevent.
+--
+-- But there is one rule that needs nobody's product opinion: A TERMINAL STATE IS
+-- TERMINAL. A cancelled appointment does not become confirmed again — you make a
+-- new one. A paid order does not go back to draft. An archived deal is archived.
+-- Encoding that costs no design decisions and closes the hole the deferral left:
+-- today any of these kinds can go from any status to any other, including
+-- backwards out of a terminal state, and nothing notices.
+--
+-- The guard reads `transitions -> OLD.status`, falling back to `transitions ->
+-- '*'` and then to `[]`. So `{"*": ["*"], "cancelled": []}` means "anything may
+-- happen, except that nothing may happen after cancelled" — free where the
+-- owning slice has not decided, closed where the answer is not in doubt.
+--
+-- Which statuses are terminal, and why each is beyond argument:
+--   appointment     cancelled, no_show, paid
+--   service_order   cancelled, paid
+--   quote           converted, archived        (rejected/expired stay open: a
+--                                               rejected quote can be revised)
+--   deal            archived                   (won/lost stay open: a deal can be
+--                                               reopened, and CRMs do)
+--
+-- Replay-safe: register_order_kind upserts by kind.
+
+SELECT public.register_order_kind('appointment', 'agenda',
+  ARRAY['scheduled', 'confirmed', 'in_progress', 'completed', 'cancelled', 'no_show', 'invoiced', 'paid'],
+  '{"*": ["*"], "cancelled": [], "no_show": [], "paid": []}'::jsonb,
+  'An appointment''s commercial document (agenda); lifecycle owned by plugin-agenda, except that a terminal state is terminal (#119)');
+
+SELECT public.register_order_kind('service_order', 'agenda',
+  ARRAY['draft', 'scheduled', 'confirmed', 'in_progress', 'completed', 'cancelled', 'invoiced', 'paid'],
+  '{"*": ["*"], "cancelled": [], "paid": []}'::jsonb,
+  'A service order (agenda); lifecycle owned by plugin-agenda, except that a terminal state is terminal (#119)');
+
+SELECT public.register_order_kind('quote', 'crm',
+  ARRAY['draft', 'sent', 'approved', 'rejected', 'expired', 'converted', 'archived'],
+  '{"*": ["*"], "converted": [], "archived": []}'::jsonb,
+  'A quote (CRM); lifecycle owned by plugin-crm. rejected and expired stay open — a rejected quote can be revised (#119)');
+
+SELECT public.register_order_kind('deal', 'crm',
+  ARRAY['open', 'won', 'lost', 'archived'],
+  '{"*": ["*"], "archived": []}'::jsonb,
+  'A deal (CRM); lifecycle owned by plugin-crm. won and lost stay open — a deal can be reopened, and CRMs do (#119)');

package/migrations/130_every_login_is_a_person.sql

@@ -0,0 +1,196 @@
+-- 130_every_login_is_a_person.sql
+--
+-- `memberships.person_id` becomes required, because a login is a person. #137.
+--
+-- #137 asks for "memberships.person_id required for employee/professional roles
+-- with login; one user = one person per tenant". The FK, the one-person-per-user
+-- unique index and the merge-tombstone guard all shipped; the REQUIREMENT did
+-- not, and 7 of 8 salon memberships carry NULL.
+--
+-- `082`'s header argues it cannot be a constraint — "a professional without a
+-- login is legitimate" — and that is true, but it is the other direction. A
+-- Person may have no membership; the question here is whether a MEMBERSHIP may
+-- have no Person, and a membership IS a login. Somebody is using it.
+--
+-- THE DECISION TAKEN, since #137 left it open: every login gets a Person, not
+-- only the staff roles. Two reasons. Splitting by role means asking "is this
+-- role staff?" at every write, and role sets are per tenant and per vertical —
+-- the question has no stable answer. And the whole point of #137 is that a
+-- Person is the one identity a human has in a tenant: an owner who is not a
+-- Person cannot be scheduled, paid a commission, or given a document, and would
+-- have to be invented later anyway.
+--
+-- HOW, so that no writer has to remember: a BEFORE INSERT trigger fills
+-- `person_id` when it is absent, finding the Person already linked to that login
+-- or creating one from the account's own name and e-mail. The legacy projection
+-- (053), the invitation flow, `create_tenant` and the seed all go through it
+-- without knowing it exists — which is the only way a NOT NULL on this column
+-- could be added without breaking one of them.
+--
+-- The Person it creates is `kind = 'employee'`: a login is a member of the team
+-- until somebody says otherwise, and `people_link_membership` already used that
+-- rule when linking an existing Person with no staff role.
+--
+-- Replay-safe: the backfill is `WHERE person_id IS NULL`, the trigger is dropped
+-- and recreated, and the NOT NULL is applied only once every row satisfies it.
+
+CREATE OR REPLACE FUNCTION app.person_for_login(p_tenant uuid, p_user uuid)
+RETURNS uuid LANGUAGE plpgsql SECURITY DEFINER SET search_path = '' AS $$
+DECLARE
+  v_person uuid;
+  v_email text;
+  v_name text;
+BEGIN
+  IF p_tenant IS NULL OR p_user IS NULL THEN RETURN NULL; END IF;
+
+  -- already linked somewhere in this tenant? one user = one person per tenant
+  SELECT m.person_id INTO v_person FROM app.memberships m
+   WHERE m.tenant_id = p_tenant AND m.user_id = p_user AND m.person_id IS NOT NULL
+   LIMIT 1;
+  IF v_person IS NOT NULL THEN RETURN v_person; END IF;
+
+  SELECT u.email, coalesce(nullif(btrim(u.raw_user_meta_data ->> 'full_name'), ''),
+                           nullif(btrim(u.raw_user_meta_data ->> 'name'), ''))
+    INTO v_email, v_name
+    FROM auth.users u WHERE u.id = p_user;
+
+  -- an existing Person of this tenant with the same e-mail is the same human:
+  -- creating a second one would be the duplicate #137 exists to prevent
+  IF v_email IS NOT NULL THEN
+    SELECT p.id INTO v_person FROM public.people p
+     WHERE p.tenant_id = p_tenant AND p.merged_into_id IS NULL
+       AND lower(p.email) = lower(v_email)
+       AND NOT EXISTS (SELECT 1 FROM app.memberships m2 WHERE m2.tenant_id = p_tenant AND m2.person_id = p.id)
+     ORDER BY p.created_at LIMIT 1;
+    IF v_person IS NOT NULL THEN RETURN v_person; END IF;
+  END IF;
+
+  INSERT INTO public.people (tenant_id, kind, name, email, metadata)
+  VALUES (p_tenant, 'employee',
+          coalesce(v_name, split_part(coalesce(v_email, 'membro'), '@', 1)),
+          v_email,
+          jsonb_build_object('source', 'migration:120', 'reason', 'a login is a person'))
+  RETURNING id INTO v_person;
+  RETURN v_person;
+END $$;
+REVOKE ALL ON FUNCTION app.person_for_login(uuid, uuid) FROM public, anon, authenticated;
+
+CREATE OR REPLACE FUNCTION app.trg_memberships_person_default()
+RETURNS trigger LANGUAGE plpgsql SECURITY DEFINER SET search_path = '' AS $$
+BEGIN
+  IF NEW.person_id IS NULL THEN
+    NEW.person_id := app.person_for_login(NEW.tenant_id, NEW.user_id);
+  END IF;
+  RETURN NEW;
+END $$;
+REVOKE ALL ON FUNCTION app.trg_memberships_person_default() FROM public, anon, authenticated;
+
+-- BEFORE the link check of 072 (alphabetical order decides, and
+-- `memberships_person_default` sorts before `memberships_person_link_check`), so
+-- the value this fills is the value that gets validated.
+DROP TRIGGER IF EXISTS memberships_person_default ON app.memberships;
+CREATE TRIGGER memberships_person_default
+  BEFORE INSERT ON app.memberships
+  FOR EACH ROW EXECUTE FUNCTION app.trg_memberships_person_default();
+
+DO $$
+DECLARE r record; v_n integer := 0;
+BEGIN
+  FOR r IN SELECT tenant_id, user_id FROM app.memberships WHERE person_id IS NULL LOOP
+    UPDATE app.memberships SET person_id = app.person_for_login(r.tenant_id, r.user_id)
+     WHERE tenant_id = r.tenant_id AND user_id = r.user_id AND person_id IS NULL;
+    v_n := v_n + 1;
+  END LOOP;
+  RAISE NOTICE '120: gave a Person to % membership(s) that had none', v_n;
+
+  IF NOT EXISTS (SELECT 1 FROM app.memberships WHERE person_id IS NULL) THEN
+    ALTER TABLE app.memberships ALTER COLUMN person_id SET NOT NULL;
+  ELSE
+    -- A membership whose login has no auth.users row cannot get a Person, and
+    -- that is a broken membership, not a reason to relax the rule. Say which.
+    RAISE WARNING '120: % membership(s) still have no Person (no auth.users row for the login?) — person_id stays nullable until they are resolved',
+      (SELECT count(*) FROM app.memberships WHERE person_id IS NULL);
+  END IF;
+END $$;
+
+COMMENT ON COLUMN app.memberships.person_id IS
+  'The Person this login IS, in this tenant (#137). Required: a membership is a login and somebody is using it. Filled automatically on insert when a writer does not supply it, so create_tenant, the invitation flow, the legacy projection and the seed all satisfy it without knowing (#120).';
+
+
+-- ── naming the real human is an answer, not a conflict ───────────────────
+-- people_link_membership refused when the login already pointed at a different
+-- Person — the rule that stops one login being two humans. Every login now
+-- points at one from the moment it exists, so without this the RPC could never
+-- be called: the placeholder would always be in the way.
+CREATE OR REPLACE FUNCTION public.people_link_membership(p_person uuid, p_user uuid)
+RETURNS uuid
+LANGUAGE plpgsql SECURITY DEFINER SET search_path = ''
+AS $$
+DECLARE
+  v_tenant uuid := public.people_assert_scope('members.manage');
+  p        public.people%ROWTYPE;
+  m        app.memberships%ROWTYPE;
+  v_other  uuid;
+BEGIN
+  SELECT * INTO p FROM public.people WHERE tenant_id = v_tenant AND id = p_person FOR UPDATE;
+  IF NOT FOUND THEN RAISE EXCEPTION 'people_link_membership: person not found in this tenant' USING ERRCODE = 'P0002'; END IF;
+  IF p.merged_into_id IS NOT NULL THEN
+    RAISE EXCEPTION 'people_link_membership: person is a merge tombstone (use %)', p.merged_into_id USING ERRCODE = 'P0001';
+  END IF;
+  IF p.unit_id IS NOT NULL AND NOT app.has_unit(p.unit_id) THEN
+    RAISE EXCEPTION 'people_link_membership: person is in a unit out of your scope' USING ERRCODE = '42501';
+  END IF;
+  SELECT * INTO m FROM app.memberships WHERE tenant_id = v_tenant AND user_id = p_user FOR UPDATE;
+  IF NOT FOUND THEN RAISE EXCEPTION 'people_link_membership: no membership for this user in this tenant' USING ERRCODE = 'P0002'; END IF;
+  -- Since #120 every login already HAS a Person: the membership trigger mints a
+  -- placeholder when nobody says who the human is. Naming the real one is not a
+  -- conflict, it is the answer — so a placeholder is replaced and removed rather
+  -- than standing in the way. Anything else (a Person somebody actually chose)
+  -- still refuses, which is the rule this guard was written for.
+  IF m.person_id IS NOT NULL AND m.person_id <> p_person
+     AND EXISTS (SELECT 1 FROM public.people ph
+                  WHERE ph.id = m.person_id AND ph.tenant_id = v_tenant
+                    AND ph.metadata ->> 'source' = 'migration:120') THEN
+    -- Move the reference straight to the real Person rather than clearing it
+    -- first: person_id is NOT NULL now, so there is no moment in between. Then
+    -- the placeholder has nothing pointing at it and can go.
+    UPDATE app.memberships SET person_id = p_person WHERE tenant_id = v_tenant AND user_id = p_user;
+    DELETE FROM public.person_roles WHERE tenant_id = v_tenant AND person_id = m.person_id;
+    DELETE FROM public.people WHERE tenant_id = v_tenant AND id = m.person_id;
+    m.person_id := p_person;
+  END IF;
+  IF m.person_id IS NOT NULL AND m.person_id <> p_person THEN
+    RAISE EXCEPTION 'people_link_membership: this login is already linked to another person (%)', m.person_id USING ERRCODE = '23505';
+  END IF;
+  SELECT x.user_id INTO v_other FROM app.memberships x WHERE x.tenant_id = v_tenant AND x.person_id = p_person AND x.user_id <> p_user;
+  IF v_other IS NOT NULL THEN
+    RAISE EXCEPTION 'people_link_membership: this person is already linked to another login (%)', v_other USING ERRCODE = '23505';
+  END IF;
+
+  IF m.person_id IS DISTINCT FROM p_person THEN
+    UPDATE app.memberships SET person_id = p_person WHERE tenant_id = v_tenant AND user_id = p_user;
+  END IF;
+
+  -- a login is a member of the team: at least one staff role
+  IF NOT EXISTS (SELECT 1 FROM public.person_roles r
+                  WHERE r.tenant_id = v_tenant AND r.person_id = p_person
+                    AND r.role IN ('professional', 'employee')
+                    AND public.person_role_active(r.valid_from, r.valid_to)) THEN
+    INSERT INTO public.person_roles (tenant_id, person_id, role, unit_id, is_primary, metadata)
+    VALUES (v_tenant, p_person, 'employee', p.unit_id,
+            NOT EXISTS (SELECT 1 FROM public.person_roles r WHERE r.tenant_id = v_tenant AND r.person_id = p_person AND r.is_primary),
+            jsonb_build_object('source', 'people_link_membership'))
+    ON CONFLICT DO NOTHING;
+    -- an expired employee row for the same unit blocks the insert above: reopen it
+    UPDATE public.person_roles r
+       SET valid_to = NULL, valid_from = least(r.valid_from, current_date)
+     WHERE r.tenant_id = v_tenant AND r.person_id = p_person AND r.role = 'employee'
+       AND NOT public.person_role_active(r.valid_from, r.valid_to)
+       AND NOT EXISTS (SELECT 1 FROM public.person_roles x WHERE x.tenant_id = v_tenant AND x.person_id = p_person
+                        AND x.role IN ('professional', 'employee') AND public.person_role_active(x.valid_from, x.valid_to));
+  END IF;
+
+  INSERT INTO public.audit_logs (tenant_id, user_id, action, entity_type, entity_id, metadata)
+  VALUES (v_tenant, auth.uid(), 'people.link_membership', 'people', p_person::text, jsonb_build_object('user_id', p_user, 'membership_id', m.id));
+  RETURN m.id;
+END $$;

package/migrations/131_migration_invoice_split.sql

@@ -0,0 +1,127 @@
+-- 131_migration_invoice_split.sql
+--
+-- The invoice split completes: an invoice arrives with its installments. #141 / #148.
+--
+-- `migration.upsert_invoice` existed and wrote a header with no installments, so
+-- the split V1 invoices produced a `plg_financial_invoices` row whose balance
+-- views had nothing to compute from — `v_financial_invoice_balances` derives
+-- everything from `plg_financial_invoice_installments`, so every migrated invoice
+-- read as zero owed and zero paid regardless of what V1 said.
+--
+-- IT ALSO DROPPED COLUMNS IN SILENCE, which is the same defect as #198 wearing a
+-- different hat. The writer built a CANDIDATE object with several speculative
+-- names for each value — `party_id` and `counterparty_id`, `total` and
+-- `total_amount` and `amount`, `kind` and `direction` — and kept whichever
+-- `_has_column` recognised. That reads as robustness and behaves as a silent
+-- drop: the real column is `counterparty_person_id`, which was in none of the
+-- guesses, so **every migrated invoice lost its counterparty** and nothing said
+-- so. A destination column is not something to guess at; it is something to
+-- name.
+--
+-- The rewrite names them, and quarantines rather than guessing:
+--   · no total, or a negative one            -> value quarantine
+--   · a direction outside receivable|payable -> value quarantine
+--   · a counterparty that is not a Person of this tenant -> fk quarantine
+--     (rather than dropping the reference, which is what it did before)
+--
+-- INSTALLMENTS. V1 offers them under `installments` when the extractor has them;
+-- when it does not, the invoice still needs one, because an invoice with no
+-- installment is a document nobody can pay. That single installment carries the
+-- whole total and the invoice's own due date — the same shape
+-- `financial_create_invoice` builds for a one-off. Installments must sum to the
+-- total to the cent: a mismatch quarantines instead of being absorbed, because
+-- deciding which installment is wrong is not a migration's call.
+--
+-- The number is minted from the tenant's own sequence, so a migrated invoice is
+-- numbered in the same series as one created in V2 — two numbering schemes in
+-- one tenant is the kind of thing nobody notices until an auditor does.
+--
+-- Replay-safe: it still refuses to rewrite an invoice that exists ("financial
+-- documents are never rewritten by the migration"), so a second offer is inert.
+
+CREATE OR REPLACE FUNCTION migration.upsert_invoice(p_tenant uuid, p_id uuid, p_row jsonb, p_args jsonb DEFAULT '{}'::jsonb)
+RETURNS jsonb LANGUAGE plpgsql SECURITY DEFINER SET search_path = '' AS $$
+DECLARE
+  v_table text := 'public.plg_financial_invoices';
+  v_dir text := coalesce(p_args ->> 'direction', p_row ->> 'direction', 'receivable');
+  v_total numeric := round(coalesce((p_row ->> 'total')::numeric, -1), 2);
+  v_party uuid;
+  v_number text;
+  v_insts jsonb;
+  v_sum numeric := 0;
+  v_i jsonb;
+  v_n integer := 0;
+  v_due date;
+  v_exists boolean;
+  v_standalone boolean := migration._standalone();
+BEGIN
+  IF to_regclass(v_table) IS NULL THEN
+    RETURN jsonb_build_object('status', 'skipped', 'reason', 'destination table absent: ' || v_table);
+  END IF;
+  IF v_standalone THEN PERFORM migration._assert_fence(p_tenant); PERFORM set_config('migration.writer', 'on', true); END IF;
+  EXECUTE format('SELECT EXISTS (SELECT 1 FROM %s WHERE id = $1)', v_table) INTO v_exists USING p_id;
+  IF v_exists THEN
+    RETURN jsonb_build_object('status', 'skipped', 'target_id', p_id, 'reason', 'invoice already exists: financial documents are never rewritten by the migration');
+  END IF;
+
+  IF v_dir NOT IN ('receivable', 'payable') THEN
+    RETURN jsonb_build_object('status', 'quarantined', 'kind', 'value', 'reason', format('unknown invoice direction %L', v_dir));
+  END IF;
+  IF v_total < 0 THEN
+    RETURN jsonb_build_object('status', 'quarantined', 'kind', 'value', 'reason', 'an invoice needs a total >= 0');
+  END IF;
+
+  -- the counterparty is a Person. A reference that does not resolve is a broken
+  -- link, not a column to drop — which is what the old candidate-name loop did.
+  BEGIN
+    v_party := coalesce((p_row ->> 'counterparty_person_id')::uuid, (p_row ->> 'party_id')::uuid);
+  EXCEPTION WHEN OTHERS THEN v_party := NULL; END;
+  IF v_party IS NOT NULL AND NOT EXISTS (SELECT 1 FROM public.people p WHERE p.id = v_party AND p.tenant_id = p_tenant) THEN
+    RETURN jsonb_build_object('status', 'quarantined', 'kind', 'fk',
+      'reason', format('counterparty %s is not a Person of this tenant', v_party));
+  END IF;
+
+  v_due := coalesce((p_row ->> 'due_date')::date, (p_row ->> 'competence_date')::date, current_date);
+
+  -- installments: as offered, or one for the whole total. An invoice with no
+  -- installment is a document nobody can pay, and the balance views derive
+  -- everything from them.
+  v_insts := CASE WHEN jsonb_typeof(p_row -> 'installments') = 'array' AND jsonb_array_length(p_row -> 'installments') > 0
+                  THEN p_row -> 'installments'
+                  ELSE jsonb_build_array(jsonb_build_object('number', 1, 'due_date', v_due, 'amount', v_total)) END;
+  FOR v_i IN SELECT * FROM jsonb_array_elements(v_insts) LOOP
+    v_sum := v_sum + round(coalesce((v_i ->> 'amount')::numeric, 0), 2);
+  END LOOP;
+  IF v_sum <> v_total THEN
+    RETURN jsonb_build_object('status', 'quarantined', 'kind', 'value',
+      'reason', format('installments sum to %s but the invoice total is %s — which one is wrong is not a migration''s call', v_sum, v_total));
+  END IF;
+
+  -- same series as an invoice created in V2: two numbering schemes in one tenant
+  -- is the kind of thing nobody notices until an auditor does
+  BEGIN
+    v_number := public.plg_financial_next_invoice_number(p_tenant, v_dir);
+  EXCEPTION WHEN OTHERS THEN v_number := p_row ->> 'number'; END;
+
+  INSERT INTO public.plg_financial_invoices
+    (id, tenant_id, unit_id, direction, counterparty_person_id, order_id, number,
+     competence_date, issue_date, total, description, notes, metadata)
+  VALUES (p_id, p_tenant, (p_row ->> 'unit_id')::uuid, v_dir, v_party, (p_row ->> 'order_id')::uuid, v_number,
+          coalesce((p_row ->> 'competence_date')::date, v_due), coalesce((p_row ->> 'issue_date')::date, v_due),
+          v_total, p_row ->> 'description', p_row ->> 'notes',
+          coalesce(p_row -> 'metadata', '{}'::jsonb));
+
+  FOR v_i IN SELECT * FROM jsonb_array_elements(v_insts) LOOP
+    v_n := v_n + 1;
+    INSERT INTO public.plg_financial_invoice_installments
+      (tenant_id, unit_id, invoice_id, number, due_date, amount, metadata)
+    VALUES (p_tenant, (p_row ->> 'unit_id')::uuid, p_id,
+            coalesce((v_i ->> 'number')::int, v_n),
+            coalesce((v_i ->> 'due_date')::date, v_due),
+            round(coalesce((v_i ->> 'amount')::numeric, 0), 2),
+            CASE WHEN jsonb_typeof(v_i -> 'metadata') = 'object' THEN v_i -> 'metadata' ELSE '{}'::jsonb END);
+  END LOOP;
+
+  IF v_standalone THEN PERFORM migration._audit(p_tenant, v_table, p_id, jsonb_build_object('reason', 'created', 'installments', v_n)); END IF;
+  RETURN jsonb_build_object('status', 'migrated', 'target_id', p_id, 'reason', 'created', 'installments', v_n, 'number', v_number);
+END $$;

package/migrations/132_audit_prune_scheduled.sql

@@ -0,0 +1,28 @@
+-- 132_audit_prune_scheduled.sql
+--
+-- The retention policy starts being a policy. #144 / #205.
+--
+-- `096` shipped `audit_logs_prune` and `audit_retention_policies` — service-only,
+-- per-tenant `keep_days`, tested — and nothing ever called it. The seed commits a
+-- tenant to 365 days; `pg_cron` runs three jobs and this was not among them,
+-- while the sibling `plg_prune_sync_runs` (spine 033) is scheduled at 04:17. A
+-- retention policy nothing enforces is a promise, and the thing it promises —
+-- that an audit trail does not grow forever — is exactly the kind that is only
+-- noticed when a table is already too big to prune comfortably.
+--
+-- 04:37: after the sync pruner and after the authz reconciliation (03:41), and
+-- off the hour for the same reason those are. Daily, because retention is
+-- measured in days and a finer cadence buys nothing.
+--
+-- Replay-safe: `cron.schedule` upserts by job name; guarded on pg_cron being
+-- present, like `033` and `117`.
+
+DO $do$
+BEGIN
+  IF to_regprocedure('cron.schedule(text, text, text)') IS NULL THEN
+    RAISE WARNING 'pg_cron is not available: audit retention is NOT scheduled on this pool and audit_logs will grow without bound';
+    RETURN;
+  END IF;
+  PERFORM cron.schedule('fayz_audit_prune', '37 4 * * *',
+                        $cmd$SELECT public.audit_logs_prune()$cmd$);
+END $do$;

package/migrations/133_unit_is_a_session_property.sql

@@ -0,0 +1,155 @@
+-- ============================================================================
+-- 133_unit_is_a_session_property.sql — the operating unit joins the session,
+-- and like the tenant claim it only ever narrows (#220).
+--
+-- `has_unit(u)` answers "do I have access to this unit", so a user with fifteen
+-- branches receives all fifteen branches' rows in one query. Nothing in the
+-- database could express "I am operating in branch X" — which is what corporate
+-- operation and compliance both ask for, and what 051's own comment already
+-- anticipated ("Only tenant_id (and, later, the active unit) live in the JWT").
+--
+-- Not a new shape: `access_sessions` (089) has minted (tenant_id, unit_id,
+-- role_key) for the QR/link path since #144. Normal logins get the same thing.
+--
+-- ONE function changes and every policy follows. The scaffold template calls
+-- `app.has_unit(unit_id)` in all four policies of all 45 registered tables, and
+-- the RPC guards of 070/071/072/089/120 plus plugin-financial 015 and
+-- plugin-inventory 008 call it too. Narrowing the function narrows every one of
+-- them, with no policy regenerated and no table touched.
+--
+-- WHAT DOES *NOT* NARROW, on purpose:
+--   app.units  — its SELECT policy is `is_member(tenant_id)`, so the unit
+--                switcher keeps listing every unit of the tenant. A session
+--                focused on one branch must still be able to see the others in
+--                order to leave.
+--   unit_id IS NULL rows — the template reads `unit_id IS NULL OR has_unit(…)`,
+--                so tenant-wide rows (the catalog) stay visible while operating
+--                in a branch. That is the point of tenant-wide.
+--
+-- Replay-safe: CREATE OR REPLACE only. No DDL, no data touched. Every existing
+-- session has no `unit_id` claim, so `current_unit_id()` returns NULL and the
+-- behaviour is byte-for-byte the one before this file.
+-- ============================================================================
+
+-- ── current_unit_id() ───────────────────────────────────────────────────
+-- Three states, and the third is why this deliberately does NOT mirror
+-- current_tenant_id():
+--
+--   no claim              → NULL       the session spans every unit the caller holds
+--   claim, parseable      → that uuid  the session is focused there
+--   claim, unparseable    → nil uuid   focused on nothing
+--
+-- current_tenant_id() returns NULL for a tenant you are not a member of, and
+-- NULL there means "no tenant" — fail closed. NULL *here* would mean "no focus",
+-- which is fail OPEN: a garbage claim would silently widen the session back to
+-- every unit you hold. So a claim that is present but unusable focuses the
+-- session on the nil uuid, which no unit can ever be.
+--
+-- And it does NOT check membership. It does not need to: has_unit ANDs the focus
+-- with user_unit_access, so a claim naming someone else's unit focuses you on a
+-- unit whose rows you cannot see, and you see nothing. Keeping the membership
+-- test out of here also keeps the helper honest about what it is — the session's
+-- FOCUS, never a grant of access.
+CREATE OR REPLACE FUNCTION app.current_unit_id()
+RETURNS uuid
+LANGUAGE plpgsql STABLE SECURITY DEFINER
+SET search_path = ''
+AS $$
+DECLARE
+  v_jwt jsonb := coalesce(auth.jwt(), '{}'::jsonb);
+  v_raw text;
+BEGIN
+  IF NOT jsonb_exists(v_jwt, 'unit_id') THEN
+    RETURN NULL;
+  END IF;
+  v_raw := v_jwt ->> 'unit_id';
+  IF v_raw IS NULL OR v_raw !~* '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$' THEN
+    RETURN '00000000-0000-0000-0000-000000000000'::uuid;
+  END IF;
+  RETURN v_raw::uuid;
+END $$;
+REVOKE ALL ON FUNCTION app.current_unit_id() FROM public, anon;
+GRANT EXECUTE ON FUNCTION app.current_unit_id() TO authenticated, service_role;
+
+COMMENT ON FUNCTION app.current_unit_id() IS
+  'The unit the session is operating in, from the `unit_id` JWT claim (#220). NULL = no focus (every unit the caller holds). A present-but-unparseable claim focuses on the nil uuid — fail closed, because NULL here would widen. Never checks membership: this is the session''s focus, and app.has_unit ANDs it with user_unit_access.';
+
+-- ── has_unit(unit) ──────────────────────────────────────────────────────
+-- 051's function with the focus clause ANDed on. THE ORDER OF THE TWO CLAUSES
+-- IS THE SECURITY: `access AND focus`. It must never become `access OR focus`,
+-- because then a claim would grant instead of narrow — 080_people/005 carries
+-- the negative test that proves it (a session claiming a unit the user does not
+-- hold returns empty, not that unit's rows).
+--
+-- The focus check goes first because it is a JWT read and the access check is a
+-- table lookup: a focused session skips the lookup for every unit but one.
+CREATE OR REPLACE FUNCTION app.has_unit(p_unit uuid)
+RETURNS boolean
+LANGUAGE sql STABLE SECURITY DEFINER
+SET search_path = ''
+AS $$
+  SELECT p_unit IS NOT NULL
+     AND (app.current_unit_id() IS NULL OR p_unit = app.current_unit_id())
+     AND CASE WHEN app.unit_scoping_on()
+              THEN EXISTS (SELECT 1 FROM app.user_unit_access a
+                            WHERE a.tenant_id = app.current_tenant_id()
+                              AND a.user_id = auth.uid()
+                              AND a.unit_id = p_unit)
+              ELSE EXISTS (SELECT 1 FROM app.units u
+                            WHERE u.id = p_unit AND u.tenant_id = app.current_tenant_id())
+         END;
+$$;
+
+COMMENT ON FUNCTION app.has_unit(uuid) IS
+  'Access to a unit, narrowed by the session''s operating unit (#220): user_unit_access AND the focus. AND, never OR — the focus can only ever remove units, so a forged claim restricts the caller and cannot widen anything.';
+
+-- ── the acting unit is derived, exactly like the tenant ─────────────────
+-- 096's audit_log() re-emitted with one expression changed: `p_unit` becomes
+-- `coalesce(p_unit, app.current_unit_id())`. A focused session stamps the unit
+-- it was acting in without every caller having to remember to pass it, and the
+-- audit trail can answer "acting as whom, in which branch" without taking the
+-- client's word for either. An explicit p_unit still wins — a service job
+-- naming the unit it acts for has no JWT to read.
+CREATE OR REPLACE FUNCTION public.audit_log(
+  p_action      text,
+  p_entity_type text,
+  p_entity_id   uuid,
+  p_reason      text  DEFAULT NULL,
+  p_before      jsonb DEFAULT NULL,
+  p_after       jsonb DEFAULT NULL,
+  p_unit        uuid  DEFAULT NULL,
+  p_metadata    jsonb DEFAULT NULL,
+  p_tenant      uuid  DEFAULT NULL
+)
+RETURNS uuid
+LANGUAGE plpgsql SECURITY DEFINER SET search_path = ''
+AS $$
+DECLARE
+  v_uid    uuid := auth.uid();
+  v_tenant uuid;
+  v_unit   uuid;
+  v_id     uuid;
+BEGIN
+  IF nullif(btrim(coalesce(p_action, '')), '') IS NULL THEN
+    RAISE EXCEPTION 'audit_log: action is required' USING ERRCODE = '22023';
+  END IF;
+  IF v_uid IS NOT NULL THEN
+    v_tenant := app.current_tenant_id();
+    IF p_tenant IS NOT NULL AND p_tenant <> v_tenant THEN
+      RAISE EXCEPTION 'audit_log: tenant is derived server-side' USING ERRCODE = '42501';
+    END IF;
+  ELSE
+    v_tenant := coalesce(p_tenant, app.current_tenant_id());
+  END IF;
+  IF v_tenant IS NULL THEN
+    RAISE EXCEPTION 'audit_log: no tenant in scope' USING ERRCODE = '42501';
+  END IF;
+  -- the nil uuid is "focused on nothing", not a unit: it must never be stamped
+  v_unit := coalesce(p_unit, nullif(app.current_unit_id(), '00000000-0000-0000-0000-000000000000'::uuid));
+  INSERT INTO public.audit_logs (tenant_id, unit_id, user_id, action, entity_type, entity_id, reason, before, after, metadata)
+  VALUES (v_tenant, v_unit, v_uid, p_action, p_entity_type, p_entity_id::text, p_reason, p_before, p_after, coalesce(p_metadata, '{}'::jsonb))
+  RETURNING id INTO v_id;
+  RETURN v_id;
+END $$;
+REVOKE ALL ON FUNCTION public.audit_log(text, text, uuid, text, jsonb, jsonb, uuid, jsonb, uuid) FROM public, anon;
+GRANT EXECUTE ON FUNCTION public.audit_log(text, text, uuid, text, jsonb, jsonb, uuid, jsonb, uuid) TO authenticated, service_role;