@fayz-ai/db 0.12.0 → 0.13.0

package/migrations/134_field_rules_on_read.sql

@@ -0,0 +1,341 @@
+-- ============================================================================
+-- 134_field_rules_on_read.sql — a hidden field stops being a front-end
+-- convention (#221).
+--
+-- `field_rules` (085) already models this: (tenant, unit, context, reference,
+-- field_key, state hidden|visible|required, role_key), migrated from V1's
+-- field_visibility_rules, with a per-unit override for free. "Reception does not
+-- see the patient's phone" is ONE ROW, set by the tenant admin, no deploy.
+--
+-- What was missing is enforcement on READ. `field_rules_check` runs on the write
+-- path (105/106) and validates `required`; `hidden` was honoured by the front
+-- end, so the value was in the PostgREST response.
+--
+-- RLS cannot close this — it is row-level by construction, and no policy hides a
+-- column. Column privileges cannot either: GRANT SELECT (col) is per DATABASE
+-- role, and every logged-in user is `authenticated`.
+--
+-- WHY THE VIEW CARRIES THE PREDICATE INSTEAD OF `security_invoker`
+--
+-- `security_invoker = true` keeps RLS working, but it also means the caller
+-- needs SELECT on the base table — which is exactly the privilege the boundary
+-- has to remove. Owner rights is the other half of the trade: no table privilege
+-- needed, but `postgres` holds BYPASSRLS, so the row filter has to be IN THE
+-- VIEW. That is not a new pattern here: `v_public_services` (plugin-agenda 015)
+-- made the same call for the same reason.
+--
+-- The duplication that normally makes this a bad idea is removed at the source:
+-- `app.scaffold_scope_sql()` is extracted from 116 and is now the ONE place the
+-- row predicate is written. `scaffold_table`, `scaffold_refresh_policies` and
+-- the masked view all render from it, so the view cannot drift from the policy —
+-- they are the same string.
+--
+-- The mask itself resolves ONCE PER STATEMENT, not once per row: the hidden set
+-- is `(select app.hidden_fields(…))`, which the planner lifts to an InitPlan —
+-- the same trick the authz helpers have used since 041. That is only affordable
+-- because #220 gave the session one unit; a per-row unit would mean a per-row
+-- rule lookup.
+--
+-- What this file does NOT do: revoke the base table. That is the step that turns
+-- the view from available into mandatory, it has its own blast radius, and it
+-- gets its own migration.
+--
+-- Replay-safe: CREATE OR REPLACE + a generated view rebuilt from the catalog.
+-- ============================================================================
+
+-- ── the row predicate, written once ─────────────────────────────────────
+-- Lifted verbatim out of 126's scaffold_table / scaffold_refresh_policies. The
+-- string it returns is byte-identical to the one those two built inline, so the
+-- policies this migration re-emits are the policies that were already there.
+-- The third parameter is defaulted and unused here: 126 gives `unit_id` a
+-- declared class per table, and this is the one place the predicate is written,
+-- so the signature is the final one from the start. Defining the 2-arg form now
+-- and widening it later would leave both overloads alive on a replay — 124 would
+-- recreate the narrow one beside 136's wide one, and every 2-arg call would stop
+-- resolving. That is not hypothetical: it is what the force-replay pass caught.
+CREATE OR REPLACE FUNCTION app.scaffold_scope_sql(p_resource_type text, p_plugin text, p_scope text DEFAULT NULL)
+RETURNS text
+LANGUAGE sql IMMUTABLE
+SET search_path = ''
+AS $$
+  SELECT format(
+    'tenant_id = (select app.current_tenant_id())'
+    || CASE WHEN p_scope = 'unit'
+            THEN ' AND (select app.has_unit(unit_id))'
+            ELSE ' AND (unit_id IS NULL OR (select app.has_unit(unit_id)))' END
+    || ' AND (NOT (select app.owner_scoped(%L))'
+    ||      ' OR owner_id IS NULL OR owner_id = (select auth.uid())'
+    ||      ' OR (select app.has_grant(%L, id, ARRAY[''shared_with'']))'
+    ||      ' OR (select app.has_permission(%L, unit_id)))',
+    p_resource_type, p_resource_type, p_plugin || '.read_all');
+$$;
+REVOKE ALL ON FUNCTION app.scaffold_scope_sql(text, text, text) FROM public, anon, authenticated;
+
+COMMENT ON FUNCTION app.scaffold_scope_sql(text, text, text) IS
+  'The row-scope predicate of the §4/§7 template, as text. The ONE place it is written: scaffold_table, scaffold_refresh_policies and app.masked_view_refresh all render from it, so a masked view can never drift from the policy it mirrors (#221).';
+
+-- ── which fields are hidden from me, right now ──────────────────────────
+-- Thin on purpose: field_rules_resolve (085) already resolves tenant, effective
+-- role per unit, the unit override and its precedence, and even the
+-- `available_in` release on the RULE itself. This only picks the hidden ones and
+-- returns an array, which is the shape a per-statement InitPlan wants.
+--
+-- The unit is the SESSION's unit (#220). Without a focus there is no unit whose
+-- override could apply — "which branch's rule?" has no answer — so an unfocused
+-- session gets the tenant-level rules. That is the honest reading, not a
+-- fallback.
+CREATE OR REPLACE FUNCTION app.hidden_fields(p_context text, p_reference text)
+RETURNS text[]
+LANGUAGE sql STABLE SECURITY DEFINER
+SET search_path = ''
+AS $$
+  SELECT coalesce(array_agg(r.field_key ORDER BY r.field_key), '{}'::text[])
+    FROM public.field_rules_resolve(
+           p_context, p_reference,
+           nullif(app.current_unit_id(), '00000000-0000-0000-0000-000000000000'::uuid)) r
+   WHERE r.state = 'hidden';
+$$;
+REVOKE ALL ON FUNCTION app.hidden_fields(text, text) FROM public, anon;
+GRANT EXECUTE ON FUNCTION app.hidden_fields(text, text) TO authenticated, service_role;
+
+COMMENT ON FUNCTION app.hidden_fields(text, text) IS
+  'The field_keys `field_rules` hides from the caller, for the session''s unit (#221). Call it as (select app.hidden_fields(…)) so it resolves once per statement rather than once per row.';
+
+-- ── the registry of masked views ────────────────────────────────────────
+-- N16 refuses an owner-rights view over a tenant_id table, and it is right to:
+-- an owner-invoked view IS an RLS bypass. A masked view is owner-rights on
+-- purpose, so it needs to be distinguishable from the mistake N16 exists to
+-- catch — and a name on a hand-maintained allowlist is not a distinction, it is
+-- a hole with a comment next to it.
+--
+-- So the exception is earned, not granted: only app.masked_view_refresh writes
+-- here, and 900_verification asserts that every view listed carries the tenant
+-- filter and the read permission in its own body. Registering buys nothing on
+-- its own.
+CREATE TABLE IF NOT EXISTS app.masked_views (
+  table_schema text NOT NULL,
+  table_name   text NOT NULL,
+  view_name    text NOT NULL,
+  context      text NOT NULL,
+  reference    text NOT NULL,
+  applied_at   timestamptz NOT NULL DEFAULT now(),
+  PRIMARY KEY (table_schema, table_name)
+);
+ALTER TABLE app.masked_views ENABLE ROW LEVEL SECURITY;
+GRANT SELECT ON app.masked_views TO authenticated;
+DROP POLICY IF EXISTS masked_views_select ON app.masked_views;
+CREATE POLICY masked_views_select ON app.masked_views FOR SELECT TO authenticated USING (true);
+COMMENT ON TABLE app.masked_views IS
+  'Which tables read through a field_rules-masked view, and under which context/reference (#221). Written only by app.masked_view_refresh; 900_verification/001 checks that each listed view actually carries the row predicate, so a row here is not a bypass permit.';
+
+-- ── generate the masked read view for a scaffolded table ────────────────
+-- Structural columns pass through untouched — the view is still joined on and
+-- filtered by them. Everything else is wrapped so a hidden field reads NULL.
+--
+-- DROP + CREATE rather than CREATE OR REPLACE: replace refuses a changed column
+-- list, and a table that loses a column has to be able to lose it here too.
+CREATE OR REPLACE FUNCTION app.masked_view_refresh(
+  p_table     regclass,
+  p_context   text,
+  p_reference text
+)
+RETURNS void
+LANGUAGE plpgsql SECURITY DEFINER
+SET search_path = ''
+AS $$
+DECLARE
+  v_schema    text;
+  v_name      text;
+  v_view      text;
+  r           app.scaffold_registry%ROWTYPE;
+  v_cols      text;
+  v_structural constant text[] := ARRAY['id','tenant_id','unit_id','owner_id','created_at','updated_at'];
+BEGIN
+  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;
+
+  SELECT * INTO r FROM app.scaffold_registry WHERE table_schema = v_schema AND table_name = v_name;
+  IF NOT FOUND THEN
+    RAISE EXCEPTION 'masked_view_refresh: %.% is not scaffolded — the view renders the scaffold''s own predicate', v_schema, v_name
+      USING ERRCODE = 'P0002';
+  END IF;
+  IF NOT EXISTS (SELECT 1 FROM public.field_rule_contexts WHERE key = p_context) THEN
+    RAISE EXCEPTION 'masked_view_refresh: unknown field-rule context %', p_context USING ERRCODE = '23503';
+  END IF;
+
+  v_view := 'v_' || v_name;
+
+  SELECT string_agg(
+           CASE WHEN c.column_name = ANY (v_structural)
+                THEN format('%I', c.column_name)
+                -- `@>` and not `= ANY (…)`: a parenthesised scalar subquery is
+                -- parsed as ANY's SUBQUERY form, which compares against rows and
+                -- chokes on a text[]. Containment takes the array directly and
+                -- still plans as a once-per-statement InitPlan.
+                ELSE format('CASE WHEN NOT ((select app.hidden_fields(%L, %L)) @> ARRAY[%L::text]) THEN %I END AS %I',
+                            p_context, p_reference, c.column_name, c.column_name, c.column_name)
+           END, E',\n       ' ORDER BY c.ordinal_position)
+    INTO v_cols
+    FROM information_schema.columns c
+   WHERE c.table_schema = v_schema AND c.table_name = v_name;
+
+  EXECUTE format('DROP VIEW IF EXISTS %I.%I', v_schema, v_view);
+  -- Owner rights on purpose (see the header): the predicate below IS the
+  -- scaffold's, rendered from the same function the policies render from.
+  EXECUTE format(
+    'CREATE VIEW %I.%I AS SELECT %s FROM %I.%I WHERE %s AND (select app.has_permission(%L, unit_id))',
+    v_schema, v_view, v_cols, v_schema, v_name,
+    app.scaffold_scope_sql(r.resource_type, r.plugin), r.plugin || '.read');
+
+  EXECUTE format('REVOKE ALL ON %I.%I FROM public, anon', v_schema, v_view);
+  EXECUTE format('GRANT SELECT ON %I.%I TO authenticated, service_role', v_schema, v_view);
+  EXECUTE format(
+    'COMMENT ON VIEW %I.%I IS %L',
+    v_schema, v_view,
+    format('Masked read of %I.%I (#221): every non-structural column reads NULL when field_rules hides it for the caller''s role and unit. Owner rights with the scaffold''s own row predicate — regenerate with app.masked_view_refresh(''%I.%I'', %L, %L), never edit by hand.',
+           v_schema, v_name, v_schema, v_name, p_context, p_reference));
+
+  INSERT INTO app.masked_views (table_schema, table_name, view_name, context, reference)
+  VALUES (v_schema, v_name, v_view, p_context, p_reference)
+  ON CONFLICT (table_schema, table_name) DO UPDATE
+    SET view_name = EXCLUDED.view_name, context = EXCLUDED.context,
+        reference = EXCLUDED.reference, applied_at = now();
+END $$;
+REVOKE ALL ON FUNCTION app.masked_view_refresh(regclass, text, text) FROM public, anon, authenticated;
+
+
+-- ── scaffold_table, re-emitted to render from the shared predicate ──────
+-- 126's function with one assignment changed: the inline format() that built
+-- v_scope becomes the call to app.scaffold_scope_sql(). Everything else is 116
+-- verbatim — this file lifts the text rather than retyping it, so "the policies
+-- are the same policies" is a property of how it was produced, not a claim.
+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');
+
+  INSERT INTO app.scaffold_registry (table_schema, table_name, resource_type, plugin, owner_scoping, mode, previous_policies)
+  VALUES (v_schema, v_name, p_resource_type, p_plugin, p_owner_scoping, p_mode, v_prev)
+  ON CONFLICT (table_schema, table_name) DO UPDATE
+    SET resource_type = EXCLUDED.resource_type, plugin = EXCLUDED.plugin, owner_scoping = EXCLUDED.owner_scoping,
+        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 $$;
+
+-- ── scaffold_refresh_policies, same treatment ───────────────────────────
+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;
+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;
+
+  v_scope := app.scaffold_scope_sql(r.resource_type, r.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, 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');
+  -- the INSERT policy has no owner clause (there is no row yet to own)
+END $$;
+REVOKE ALL ON FUNCTION app.scaffold_refresh_policies(text) FROM public, anon, authenticated;
+
+-- ── the pilot: people ───────────────────────────────────────────────────
+-- context 'person' is 095's own ("The person record itself"); reference 'person'
+-- is the plg_entity_fields reference the V1 rules migrated onto.
+SELECT app.masked_view_refresh('public.people', 'person', 'person');

package/migrations/135_distribution_polarity.sql

@@ -0,0 +1,158 @@
+-- ============================================================================
+-- 135_distribution_polarity.sql — distribution gets a subtractive form, so
+-- "19 of 20 branches" stops costing 19 rows (#223).
+--
+-- `resource_grants` had only `available_in`, which is additive. Releasing a
+-- service to 19 of 20 branches meant 19 tuples; there was no way to say
+-- "everywhere except these two". And `products.unit_id` does not help — it holds
+-- ONE value, so it covers exactly 1 of 20 and does nothing at 2.
+--
+--   an 'unavailable_in' tuple that applies to me  → no
+--   else, any 'available_in' tuple exists         → only if one names a unit of mine
+--   else                                          → yes   (default open, unchanged)
+--
+-- Cost becomes min(k, n−k): 1 of 20 is one row, 19 of 20 is one row.
+--
+-- BACKWARD COMPATIBLE BY CONSTRUCTION: with no `unavailable_in` tuples anywhere,
+-- `excluded_in_my_units` is false and the expression reduces to 051's original.
+-- No policy is regenerated either — the six RESTRICTIVE catalog policies call
+-- `available_in_my_units`, so replacing the function is the whole change.
+--
+-- DENY IS "EVERY UNIT OF MINE", NOT "ANY"
+--
+-- RLS hides a row from the PERSON, not from a unit. A manager who holds b1 and
+-- b2, with b2 excluded, must still see the row — she has a branch that offers
+-- it. "Any" would hide it from her entirely, which is a different and wrong
+-- statement. So the unit-subject exclusion only bites when no unit of hers
+-- escapes it.
+--
+-- …and "of mine" respects the session's focus (#220). Focused on b2, b2 is the
+-- only unit in scope, so an exclusion on b2 does hide the row — which is the
+-- answer the person actually asked for. The two features compose: the focus is
+-- what makes a per-unit exclusion legible at all.
+--
+-- A user-subject or role-subject exclusion has none of that subtlety: the
+-- subject IS the person, so it simply bites.
+--
+-- Replay-safe: CREATE OR REPLACE only.
+-- ============================================================================
+
+-- ── excluded_in_my_units(type, id) ──────────────────────────────────────
+CREATE OR REPLACE FUNCTION app.excluded_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
+  ),
+  ex AS (
+    SELECT 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      = 'unavailable_in'
+  ),
+  -- the units in scope right now: what I hold, narrowed by the focus
+  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)
+  )
+  SELECT
+    -- named directly: me, or a role I hold. No "every" about it.
+    EXISTS (
+      SELECT 1 FROM ex, me
+       WHERE (ex.subject_type = 'user' AND ex.subject_id = me.uid)
+          OR (ex.subject_type = 'role' AND ex.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)))
+    -- or every unit in scope is excluded — and there is at least one, so that a
+    -- caller who holds no units at all does not lose the catalogue to a rule
+    -- about units that cannot apply to them.
+    OR (
+      EXISTS (SELECT 1 FROM ex WHERE ex.subject_type = 'unit')
+      AND EXISTS (SELECT 1 FROM mine)
+      AND NOT EXISTS (
+        SELECT 1 FROM mine
+         WHERE NOT EXISTS (SELECT 1 FROM ex WHERE ex.subject_type = 'unit' AND ex.subject_id = mine.unit_id))
+    );
+$$;
+REVOKE ALL ON FUNCTION app.excluded_in_my_units(text, uuid) FROM public, anon;
+GRANT EXECUTE ON FUNCTION app.excluded_in_my_units(text, uuid) TO authenticated, service_role;
+
+COMMENT ON FUNCTION app.excluded_in_my_units(text, uuid) IS
+  'Does an `unavailable_in` tuple hide this resource from the caller (#223)? A user- or role-subject tuple bites directly. A unit-subject tuple bites only when EVERY unit in scope is excluded — RLS hides a row from the person, not from a unit — and "in scope" is narrowed by the session''s operating unit (#220).';
+
+-- ── has_grant(type, id, relations[]) — the unit subject respects the focus ──
+-- Found by the test for "released to b1, focused on b2": the row stayed visible,
+-- because 051's has_grant matches a unit-subject tuple against the caller's WHOLE
+-- user_unit_access, and b1 is still hers even while she is operating in b2.
+--
+-- That is the same asymmetry the exclusion side had to solve, so it is solved in
+-- the same place rather than worked around in the caller. The focus narrows what
+-- "a unit of mine" means, for every relation and every caller — `available_in`
+-- here, and `shared_with` in the owner clause of all 45 scaffolded tables. Both
+-- readings are consistent: while operating in b2, a release to b1 is not offered
+-- here, and a share with b1's staff is not mine to use here.
+--
+-- User- and role-subject tuples are untouched: the subject is the person, and a
+-- person does not change branch.
+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 a.unit_id = g.subject_id
+                  AND (app.current_unit_id() IS NULL OR a.unit_id = app.current_unit_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 in scope — "in scope" being narrowed by the session''s operating unit (#220/#223). User and role subjects ignore the focus: the subject is the person.';
+
+-- ── available_in_my_units(type, id) ─────────────────────────────────────
+-- 051's expression with the exclusion ANDed in front. Deny wins: an explicit
+-- exclusion beats an explicit inclusion, which is the precedence every access
+-- system settles on and the only one that is safe to get wrong in one direction.
+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 $$
+  SELECT NOT app.excluded_in_my_units(p_type, p_id)
+     AND (NOT 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 = 'available_in')
+          OR app.has_grant(p_type, p_id, ARRAY['available_in']));
+$$;
+
+COMMENT ON FUNCTION app.available_in_my_units(text, uuid) IS
+  'The release rule with polarity (#223): an applicable `unavailable_in` tuple hides it; otherwise no `available_in` tuple ⇒ available everywhere, and one ⇒ only where it names. Cost is min(k, n−k) — 1 of 20 and 19 of 20 are both one row.';