@fayz-ai/db 0.13.0 → 0.14.0

package/migrations/129_order_kind_terminal_states.sql

@@ -1,57 +0,0 @@
--- 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

@@ -1,196 +0,0 @@
--- 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

@@ -1,127 +0,0 @@
--- 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

@@ -1,28 +0,0 @@
--- 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

@@ -1,155 +0,0 @@
--- ============================================================================
--- 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;