@fayz-ai/db 0.12.0 → 0.13.0

package/migrations/125_migration_authz_people_writers.sql

@@ -0,0 +1,205 @@
+-- 125_migration_authz_people_writers.sql
+--
+-- The last of the extractor's destinations get an answer. #137 / #136 / #148.
+--
+-- Three writers, and six decisions. The decisions are the point of this file:
+-- every one of them was a row that would otherwise have sat `pending` forever,
+-- and most of them turn out to say the same thing.
+--
+-- THE IDENTITY BRIDGE THAT DOES NOT EXIST. `app.memberships.user_id` is an FK to
+-- `auth.users`. Nothing in the allowlist maps a V1 login to a V2 one -- `profiles`
+-- explicitly drops its id (`"id":"-"`) -- so there is no way to say which V2
+-- account a V1 membership belongs to. That single gap is why `license_users`,
+-- `employee_permission_rules`, `professional_permission_rules` and (in 114)
+-- `cash_register_sessions` are all deferred: each needs to attribute something to
+-- a person's LOGIN, and the login does not cross. It is one missing mapping, not
+-- four missing writers, and it is worth naming as such rather than four times.
+--
+-- WHAT IS WRITTEN:
+--
+--   permission_rules -> app.roles. A V1 rule IS a tenant role, and 091 says so.
+--   permission_rule_details -> app.role_permissions, TRANSLATED through
+--     `app.v1_permission_map` -- the table #136 built for exactly this. A V1 code
+--     with no V2 key quarantines rather than being invented, which is what the
+--     map's `backlog` rows already mean.
+--   client_registrations -> public.person_registrations, which is where a
+--     pre-registration belongs. 091 pointed it at `public.people`, and that is
+--     wrong in a way that matters: a registration is a QUEUE ENTRY awaiting dedup
+--     (#137's whole slice), not a Person. Writing it as a Person would skip the
+--     dedup and mint duplicates of people who already exist.
+--
+-- WHAT IS NOT, AND WHY:
+--
+--   licenses and system_permissions become `verify_only`. Both destinations are
+--     built by something other than the extractor -- a tenant is provisioned by a
+--     human before `batch_open`, and the permission catalog is GENERATED from
+--     declaredFeatures (#136) -- so the extractor's job is to prove they agree,
+--     not to write them. Their own notes already said so.
+--   service_locations is deferred by its own note: "a service location is a place
+--     INSIDE a unit, not a unit". Pointing it at `app.units` would turn every
+--     treatment room into a branch.
+--   client_access_tokens: the note says the token value never migrates and is
+--     re-issued in V2, which leaves nothing to write.
+--   professions is a reference list, like origins and partnerships (#110).
+--   profiles: its own note ends "no writer" -- the login profile is folded into
+--     the Person of the member.
+--
+-- Replay-safe: `_allow` upserts under the documented unlock; writers are
+-- CREATE OR REPLACE.
+
+ALTER TABLE migration.allowlist DROP CONSTRAINT IF EXISTS allowlist_writer_check;
+ALTER TABLE migration.allowlist ADD CONSTRAINT allowlist_writer_check
+  CHECK (writer IS NULL OR writer IN ('person', 'unit', 'category', 'product', 'order', 'invoice',
+                                      'price_table', 'price_table_item', 'package', 'package_item',
+                                      'field_rule', 'holiday', 'facet',
+                                      'fin_account', 'fin_payment_method_type', 'fin_payment_method',
+                                      'fin_card_brand', 'fin_chart_account', 'fin_cost_center',
+                                      'inv_measurement_unit', 'inv_unit_conversion', 'inv_location', 'inv_movement',
+                                      'order_item', 'fin_movement',
+                                      'authz_role', 'authz_role_permission', 'person_registration'));
+
+DO $unlock$
+BEGIN
+  PERFORM set_config('migration.allowlist_unlock', 'on', true);
+
+  UPDATE migration.allowlist SET writer = 'authz_role' WHERE source_table = 'permission_rules';
+  UPDATE migration.allowlist SET writer = 'authz_role_permission' WHERE source_table = 'permission_rule_details';
+
+  UPDATE migration.allowlist SET writer = 'person_registration', target_table = 'public.person_registrations',
+         notes = 'PRD 03 R6: a pre-registration is a QUEUE ENTRY awaiting dedup, not a Person. 091 pointed it at public.people, which would skip the dedup and mint duplicates of people who already exist (#115).'
+   WHERE source_table = 'client_registrations';
+
+  UPDATE migration.allowlist SET writer_args = '{"verify_only":true}'::jsonb,
+         notes = 'ADR 0002: a tenant is provisioned by a human before batch_open. The extractor proves the map, it does not create tenants — this row''s own note said so (#115).'
+   WHERE source_table = 'licenses';
+  UPDATE migration.allowlist SET writer_args = '{"verify_only":true}'::jsonb,
+         notes = '#136: the permission catalog is GENERATED from declaredFeatures and seeded by migrations, not migrated row by row. The V1 codes are translated through app.v1_permission_map (#115).'
+   WHERE source_table = 'system_permissions';
+
+  DELETE FROM migration.allowlist
+   WHERE source_table IN ('service_locations', 'license_users', 'employee_permission_rules',
+                          'professional_permission_rules', 'client_access_tokens', 'professions', 'profiles');
+END $unlock$;
+
+INSERT INTO migration.excluded_tables (source_table, reason) VALUES
+  ('service_locations',             'Deferred by its own note: "a service location is a place INSIDE a unit, not a unit". 091 pointed it at app.units, which would turn every treatment room into a branch. It belongs to the owning plugin as an extension (#115).'),
+  ('license_users',                 'Deferred: app.memberships.user_id is an FK to auth.users, and NOTHING in the allowlist maps a V1 login to a V2 one — profiles explicitly drops its id. Until that bridge exists a membership cannot say whose it is (#115).'),
+  ('employee_permission_rules',     'Deferred with license_users: same missing V1->V2 login mapping (#115).'),
+  ('professional_permission_rules', 'Deferred with license_users: same missing V1->V2 login mapping (#115).'),
+  ('client_access_tokens',          'Deferred by its own note: portal tokens are opaque and re-issued in V2, so the token value never migrates — which leaves nothing to write (#115).'),
+  ('professions',                   'Deferred: a reference list folded into the professional role, like origins and partnerships (#110). The value reaches V2 inside the person that references it (#115).'),
+  ('profiles',                      'Deferred by its own note: the login profile is folded into the Person of the member (memberships.person_id, PRD 03 R3). There is no separate row to write (#115).')
+ON CONFLICT (source_table) DO UPDATE SET reason = EXCLUDED.reason;
+
+CREATE OR REPLACE FUNCTION migration.upsert_authz_role(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_name text := nullif(btrim(coalesce(p_row ->> 'name', '')), '');
+  v_key text;
+  v_existing uuid; v_created boolean := false;
+  v_standalone boolean := migration._standalone();
+BEGIN
+  IF v_standalone THEN PERFORM migration._assert_fence(p_tenant); PERFORM set_config('migration.writer', 'on', true); END IF;
+  IF p_id IS NULL OR v_name IS NULL THEN
+    RETURN jsonb_build_object('status', 'quarantined', 'kind', 'state', 'reason', 'a role needs an id and a name');
+  END IF;
+  -- the key is derived from the name, because V1 rules have no key. A collision
+  -- with one of the system roles is refused rather than merged: 'owner' means
+  -- something specific in V2 and a V1 rule called Owner is not it.
+  -- fold the accents first: a plain [^a-z0-9] strip turns "Caixa Sênior" into
+  -- caixa_s_nior. translate() rather than unaccent() because the extension is not
+  -- guaranteed on a pool and a key is not worth a dependency.
+  v_key := translate(lower(v_name),
+                     'áàâãäéèêëíìîïóòôõöúùûüçñ',
+                     'aaaaaeeeeiiiiooooouuuucn');
+  v_key := regexp_replace(v_key, '[^a-z0-9]+', '_', 'g');
+  v_key := btrim(v_key, '_');
+  IF v_key = '' THEN v_key := 'role_' || left(replace(p_id::text, '-', ''), 8); END IF;
+  IF EXISTS (SELECT 1 FROM app.roles r WHERE r.tenant_id = p_tenant AND r.key = v_key AND r.is_system AND r.id <> p_id) THEN
+    RETURN jsonb_build_object('status', 'quarantined', 'kind', 'state',
+      'reason', format('a V1 rule named %L collides with the system role %L, which means something specific in V2', v_name, v_key));
+  END IF;
+  SELECT tenant_id INTO v_existing FROM app.roles WHERE id = p_id;
+  IF v_existing IS NOT NULL AND v_existing <> p_tenant THEN
+    RETURN jsonb_build_object('status', 'quarantined', 'kind', 'tenant', 'reason', format('role %s already exists in another tenant', p_id));
+  END IF;
+  IF v_existing IS NULL THEN
+    INSERT INTO app.roles (id, tenant_id, key, name, is_system) VALUES (p_id, p_tenant, v_key, v_name, false);
+    v_created := true;
+  ELSE
+    UPDATE app.roles SET name = v_name WHERE id = p_id AND NOT is_system;
+  END IF;
+  IF v_standalone THEN PERFORM migration._audit(p_tenant, 'app.roles', p_id, jsonb_build_object('reason', CASE WHEN v_created THEN 'created' ELSE 'updated' END)); END IF;
+  RETURN jsonb_build_object('status', 'migrated', 'target_id', p_id, 'reason', CASE WHEN v_created THEN 'created' ELSE 'updated' END);
+END $$;
+
+CREATE OR REPLACE FUNCTION migration.upsert_authz_role_permission(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_role uuid := (p_row ->> 'role_id')::uuid;
+  v_v1 text := nullif(btrim(coalesce(p_row ->> 'permission', '')), '');
+  v_key text; v_state text;
+  v_standalone boolean := migration._standalone();
+BEGIN
+  IF v_standalone THEN PERFORM migration._assert_fence(p_tenant); PERFORM set_config('migration.writer', 'on', true); END IF;
+  IF v_role IS NULL OR v_v1 IS NULL THEN
+    RETURN jsonb_build_object('status', 'quarantined', 'kind', 'fk', 'reason', 'a role permission needs its role and its V1 code');
+  END IF;
+  IF NOT EXISTS (SELECT 1 FROM app.roles r WHERE r.id = v_role AND r.tenant_id = p_tenant) THEN
+    RETURN jsonb_build_object('status', 'quarantined', 'kind', 'fk', 'reason', format('role %s is not in this tenant yet', v_role));
+  END IF;
+  -- #136 built app.v1_permission_map for exactly this translation. A code with no
+  -- V2 key is not invented: the map's own `backlog` rows say those codes have no
+  -- V2 surface yet, and granting a key that does not exist would fail the FK
+  -- anyway — quarantining says which code, which is actionable.
+  SELECT m.v2_key, m.status INTO v_key, v_state FROM app.v1_permission_map m WHERE m.v1_code = v_v1;
+  IF v_key IS NULL THEN
+    RETURN jsonb_build_object('status', 'quarantined', 'kind', 'value',
+      'reason', format('V1 permission %L has no V2 key in app.v1_permission_map (status %s)', v_v1, coalesce(v_state, 'unmapped')));
+  END IF;
+  INSERT INTO app.role_permissions (tenant_id, role_id, permission) VALUES (p_tenant, v_role, v_key)
+  ON CONFLICT DO NOTHING;
+  IF v_standalone THEN PERFORM migration._audit(p_tenant, 'app.role_permissions', v_role, jsonb_build_object('reason', 'granted', 'permission', v_key)); END IF;
+  RETURN jsonb_build_object('status', 'migrated', 'target_id', v_role, 'reason', format('granted %s', v_key));
+END $$;
+
+CREATE OR REPLACE FUNCTION migration.upsert_person_registration(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_payload jsonb;
+  v_existing uuid; v_created boolean := false;
+  v_standalone boolean := migration._standalone();
+BEGIN
+  IF v_standalone THEN PERFORM migration._assert_fence(p_tenant); PERFORM set_config('migration.writer', 'on', true); END IF;
+  IF p_id IS NULL THEN
+    RETURN jsonb_build_object('status', 'quarantined', 'kind', 'state', 'reason', 'a registration needs an id');
+  END IF;
+  -- the queue entry keeps the form as submitted; dedup happens later, through
+  -- person_registrations_process, which is the whole point of not writing a Person
+  v_payload := jsonb_strip_nulls(jsonb_build_object(
+    'name', p_row ->> 'name', 'email', p_row ->> 'email', 'phone', p_row ->> 'phone',
+    'document_number', p_row ->> 'document_number', 'source', 'migration:v1'));
+  SELECT tenant_id INTO v_existing FROM public.person_registrations WHERE id = p_id;
+  IF v_existing IS NOT NULL AND v_existing <> p_tenant THEN
+    RETURN jsonb_build_object('status', 'quarantined', 'kind', 'tenant', 'reason', format('registration %s already exists in another tenant', p_id));
+  END IF;
+  IF v_existing IS NULL THEN
+    INSERT INTO public.person_registrations (id, tenant_id, unit_id, payload)
+    VALUES (p_id, p_tenant, (p_row ->> 'unit_id')::uuid, v_payload);
+    v_created := true;
+  ELSE
+    UPDATE public.person_registrations SET payload = payload || v_payload WHERE id = p_id AND status = 'pending';
+  END IF;
+  IF v_standalone THEN PERFORM migration._audit(p_tenant, 'public.person_registrations', p_id, jsonb_build_object('reason', CASE WHEN v_created THEN 'created' ELSE 'updated' END)); END IF;
+  RETURN jsonb_build_object('status', 'migrated', 'target_id', p_id, 'reason', CASE WHEN v_created THEN 'created' ELSE 'updated' END);
+END $$;
+
+DO $$
+DECLARE r record;
+BEGIN
+  FOR r IN SELECT p.oid::regprocedure AS sig FROM pg_proc p JOIN pg_namespace n ON n.oid = p.pronamespace
+            WHERE n.nspname = 'migration' AND p.proname IN ('upsert_authz_role', 'upsert_authz_role_permission', 'upsert_person_registration') LOOP
+    EXECUTE format('REVOKE ALL ON FUNCTION %s FROM public, anon, authenticated', r.sig);
+    EXECUTE format('GRANT EXECUTE ON FUNCTION %s TO service_role', r.sig);
+  END LOOP;
+END $$;

package/migrations/126_owner_scoping_is_configuration.sql

@@ -0,0 +1,247 @@
+-- 126_owner_scoping_is_configuration.sql
+--
+-- `owner_scoping` stops being a column nobody reads. #135.
+--
+-- The criterion is "vertical differences are configuration: salon template
+-- owner_id off, clinic on". What shipped records `owner_scoping` per table in
+-- `app.scaffold_registry` and then never consults it — the audit's finding, and
+-- `053`'s own comment says it in the future tense ("owner_scoping is recorded so
+-- a template CAN say which"). The actual difference between a salon and a clinic
+-- today is a DATA convention: the clinic fills `owner_id`, the salon leaves it
+-- null, and the identical policy therefore behaves differently. That works, and
+-- it is not configuration — nothing declares it, nothing can check it, and a
+-- salon row that acquires an owner_id by accident silently becomes private.
+--
+-- One table serves every tenant, so DDL cannot vary per tenant: the variation
+-- has to be a LOOKUP. `app.owner_scoped(resource_type)` reads the tenant's
+-- `role_template` and answers for that resource, and the policy template asks it
+-- before applying the owner clause at all. A salon's people are visible to the
+-- unit because its vertical says so, not because every row happens to be
+-- unowned.
+--
+-- Defaults are the safe direction: an unknown template, or a resource with no
+-- row, falls back to the registry's own `owner_scoping` flag, which defaults
+-- true. Configuration can only ever RELAX the clause, never tighten it by
+-- omission.
+--
+-- Every registered table is re-scaffolded at the end so the new template lands
+-- on all of them at once — the registry records the arguments each was created
+-- with, which is what makes that possible.
+--
+-- Replay-safe: CREATE OR REPLACE + an idempotent seed + a re-scaffold that
+-- rewrites the same four policies.
+
+CREATE TABLE IF NOT EXISTS app.vertical_owner_scoping (
+  role_template text NOT NULL,
+  resource_type text NOT NULL,
+  owner_scoped  boolean NOT NULL,
+  note          text,
+  PRIMARY KEY (role_template, resource_type)
+);
+ALTER TABLE app.vertical_owner_scoping ENABLE ROW LEVEL SECURITY;
+GRANT SELECT ON app.vertical_owner_scoping TO authenticated;
+DROP POLICY IF EXISTS vertical_owner_scoping_select ON app.vertical_owner_scoping;
+CREATE POLICY vertical_owner_scoping_select ON app.vertical_owner_scoping FOR SELECT TO authenticated USING (true);
+
+COMMENT ON TABLE app.vertical_owner_scoping IS
+  'Which resource types a vertical scopes by owner (#135). One table serves every tenant, so this is the only place the salon/clinic difference can live as configuration rather than as a data convention. Absent row ⇒ the scaffold registry''s own flag, which defaults true.';
+
+INSERT INTO app.vertical_owner_scoping (role_template, resource_type, owner_scoped, note) VALUES
+  ('clinic',     'people.person', true,  'A professional sees her own patients; PRD 03 / the clinic template.'),
+  ('salon',      'people.person', false, 'The unit decides; a salon''s people are shared across the team.'),
+  ('restaurant', 'people.person', false, 'The unit decides.'),
+  ('generic',    'people.person', false, 'The unit decides, until a vertical says otherwise.'),
+  -- THE DIARY IS THE OTHER HALF OF THE SAME DECISION, and it was left out.
+  -- `agenda.appointment` is the only other owner-scoped resource in the
+  -- registry, and with no row here it fell through to the default — true — for
+  -- every vertical including salon. That is backwards for most of them: a
+  -- receptionist books for the whole team, and a shared diary that hides the
+  -- owner's own appointments from her staff is not a stricter salon, it is a
+  -- broken one. 128 refused to flip a live clinic pool over exactly one such
+  -- row, which is the brake doing its job.
+  ('clinic',     'agenda.appointment', true,  'A professional sees her own consultations; the same PRD 03 rule as her patients.'),
+  ('salon',      'agenda.appointment', false, 'One diary for the floor — whoever is at the desk books for everyone.'),
+  ('restaurant', 'agenda.appointment', false, 'One book of reservations, read by whoever answers the phone.'),
+  ('generic',    'agenda.appointment', false, 'The unit decides, until a vertical says otherwise.')
+ON CONFLICT (role_template, resource_type) DO UPDATE SET owner_scoped = EXCLUDED.owner_scoped, note = EXCLUDED.note;
+
+CREATE OR REPLACE FUNCTION app.owner_scoped(p_resource_type text)
+RETURNS boolean LANGUAGE sql STABLE SECURITY DEFINER SET search_path = '' AS $$
+  SELECT coalesce(
+    (SELECT v.owner_scoped FROM app.vertical_owner_scoping v
+       JOIN public.tenants t ON t.role_template = v.role_template
+      WHERE t.id = app.current_tenant_id() AND v.resource_type = p_resource_type),
+    -- no configuration for this vertical: the table's own flag, which defaults
+    -- true. Configuration relaxes; it never tightens by omission.
+    (SELECT r.owner_scoping FROM app.scaffold_registry r WHERE r.resource_type = p_resource_type LIMIT 1),
+    true)
+$$;
+REVOKE ALL ON FUNCTION app.owner_scoped(text) FROM public;
+GRANT EXECUTE ON FUNCTION app.owner_scoped(text) TO authenticated, service_role;
+
+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;
+
+  -- The owner clause is now CONDITIONAL ON THE TENANT'S VERTICAL, which is what
+  -- "vertical differences are configuration" has to mean when one table serves
+  -- every tenant: DDL cannot vary per tenant, so the variation has to be a
+  -- lookup. app.owner_scoped() reads the tenant's role_template and answers for
+  -- this resource type; when a vertical does not scope by owner the clause drops
+  -- out entirely instead of relying on every row happening to have a null
+  -- owner_id. Wrapped in (select …) like every other helper, so it is evaluated
+  -- once per statement and not once per row.
+  v_scope := format(
+    'tenant_id = (select app.current_tenant_id())'
+    || ' AND (unit_id IS NULL OR (select app.has_unit(unit_id)))'
+    || ' 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');
+
+  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 $$;
+
+-- Refresh ONLY the four template policies, leaving everything else alone.
+--
+-- The first version of this file re-ran app.scaffold_table over the registry,
+-- and enforce mode does what it says: it drops every policy that is not one of
+-- the four. That wiped `products_available_in` — the RESTRICTIVE release rule
+-- #139 added AFTER the table was scaffolded — which the bench caught. A template
+-- change is not a re-scaffold, and it must not be able to remove a rule another
+-- slice layered on top.
+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 := format(
+    'tenant_id = (select app.current_tenant_id())'
+    || ' AND (unit_id IS NULL OR (select app.has_unit(unit_id)))'
+    || ' 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)))',
+    r.resource_type, r.resource_type, r.plugin || '.read_all');
+
+  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), so it is
+  -- unaffected by this change and is left exactly as scaffold_table wrote it.
+END $$;
+REVOKE ALL ON FUNCTION app.scaffold_refresh_policies(text) FROM public, anon, authenticated;
+
+DO $$
+DECLARE r record; v_n integer := 0;
+BEGIN
+  FOR r IN SELECT * FROM app.scaffold_registry ORDER BY table_schema, table_name LOOP
+    CONTINUE WHEN to_regclass(format('%I.%I', r.table_schema, r.table_name)) IS NULL;
+    PERFORM app.scaffold_refresh_policies(format('%I.%I', r.table_schema, r.table_name));
+    v_n := v_n + 1;
+  END LOOP;
+  RAISE NOTICE '116: refreshed the template policies of % table(s) onto the vertical-aware scope', v_n;
+END $$;

package/migrations/127_scaffold_audit_hook.sql

@@ -0,0 +1,98 @@
+-- 127_scaffold_audit_hook.sql
+--
+-- The scaffold template gets the audit hook its contract names. #135.
+--
+-- #135 lists an "audit hook" among the things every scaffolded business table
+-- gets. `app.scaffold_table` attaches `handle_updated_at` and nothing else — the
+-- audit slice (`096`) landed separately and was never wired into the template.
+--
+-- OPT-IN, NOT AUTOMATIC, and the reason is not squeamishness about volume. An
+-- audit row is a claim about WHO did something. On a transactional table
+-- (`orders`, `order_items`, `plg_financial_movements`) the interesting history is
+-- already the table itself — those ledgers are append-only, so their past is not
+-- something an audit trail has to reconstruct. Auditing them would double every
+-- write to restate what the row already says. The tables worth auditing are the
+-- ones where the CURRENT value is all you can see and the change is rare and
+-- consequential: a company's fiscal identity, a tenant's settings, a role's
+-- permissions. So the hook is a per-table decision recorded in the registry,
+-- and `company_legal_entities` is its first taker — a CNPJ changing is exactly
+-- the kind of thing you want to be able to ask "who, and when" about.
+--
+-- INSERT AND UPDATE ONLY, and this one IS a hard constraint rather than a
+-- preference: #144's gate refuses an audit row for a destructive action without
+-- a `reason`, and `audit_action_is_destructive` counts anything ending in
+-- `.delete`. A trigger has no reason to give — it would have to invent one, and
+-- an invented reason in an audit log is worse than no row, because it reads like
+-- somebody typed it. A delete that matters goes through an RPC that asks.
+--
+-- Replay-safe: CREATE OR REPLACE, an idempotent column add, and a trigger that
+-- is dropped and recreated.
+
+ALTER TABLE app.scaffold_registry ADD COLUMN IF NOT EXISTS audit_hook boolean NOT NULL DEFAULT false;
+COMMENT ON COLUMN app.scaffold_registry.audit_hook IS
+  'Whether this table carries the template''s audit hook (#135/117). Opt-in: an audit row is a claim about who did something, and on an append-only ledger the table already IS its own history. Reserved for tables where the current value is all you can see and a change is rare and consequential.';
+
+CREATE OR REPLACE FUNCTION app.trg_scaffold_audit()
+RETURNS trigger LANGUAGE plpgsql SECURITY DEFINER SET search_path = '' AS $$
+DECLARE
+  v_rt text := TG_ARGV[0];
+  v_before jsonb;
+  v_after jsonb;
+BEGIN
+  -- Only what actually changed, so an audit row says something. A full row
+  -- snapshot on every UPDATE is a diff nobody can read.
+  IF TG_OP = 'UPDATE' THEN
+    SELECT jsonb_object_agg(o.key, o.value), jsonb_object_agg(n.key, n.value)
+      INTO v_before, v_after
+      FROM jsonb_each(to_jsonb(OLD)) o
+      JOIN jsonb_each(to_jsonb(NEW)) n ON n.key = o.key
+     WHERE o.value IS DISTINCT FROM n.value
+       AND o.key NOT IN ('updated_at', 'created_at');
+    IF v_after IS NULL THEN
+      RETURN NEW;   -- nothing but a timestamp moved
+    END IF;
+  END IF;
+
+  INSERT INTO public.audit_logs (tenant_id, user_id, action, entity_type, entity_id, unit_id, before, after)
+  VALUES (NEW.tenant_id, auth.uid(),
+          v_rt || CASE TG_OP WHEN 'INSERT' THEN '.create' ELSE '.edit' END,
+          v_rt, NEW.id::text,
+          CASE WHEN to_jsonb(NEW) ? 'unit_id' THEN (to_jsonb(NEW) ->> 'unit_id')::uuid END,
+          v_before, coalesce(v_after, to_jsonb(NEW)));
+  RETURN NEW;
+END $$;
+REVOKE ALL ON FUNCTION app.trg_scaffold_audit() FROM public, anon, authenticated;
+
+CREATE OR REPLACE FUNCTION app.scaffold_attach_audit(p_table text, p_on boolean DEFAULT true)
+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;
+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_attach_audit: %.% is not in the scaffold registry — the audit hook is part of the template, not a loose trigger', v_schema, v_name
+      USING ERRCODE = 'P0002';
+  END IF;
+  EXECUTE format('DROP TRIGGER IF EXISTS %I ON %s', v_name || '_scaffold_audit', v_q);
+  IF p_on THEN
+    -- INSERT and UPDATE only: #144's gate refuses a destructive action without a
+    -- reason, and a trigger has none to give.
+    EXECUTE format('CREATE TRIGGER %I AFTER INSERT OR UPDATE ON %s FOR EACH ROW EXECUTE FUNCTION app.trg_scaffold_audit(%L)',
+                   v_name || '_scaffold_audit', v_q, r.resource_type);
+  END IF;
+  UPDATE app.scaffold_registry SET audit_hook = p_on WHERE table_schema = v_schema AND table_name = v_name;
+END $$;
+REVOKE ALL ON FUNCTION app.scaffold_attach_audit(text, boolean) FROM public, anon, authenticated;
+
+-- The first taker. A CNPJ or a fiscal address changing is exactly the kind of
+-- thing you want to be able to ask "who, and when" about, and it happens rarely
+-- enough that the trail stays readable.
+DO $$
+BEGIN
+  IF EXISTS (SELECT 1 FROM app.scaffold_registry WHERE table_schema = 'public' AND table_name = 'company_legal_entities') THEN
+    PERFORM app.scaffold_attach_audit('public.company_legal_entities');
+  END IF;
+END $$;

package/migrations/128_shadow_tables_enforced.sql

@@ -0,0 +1,93 @@
+-- 128_shadow_tables_enforced.sql
+--
+-- The six shadow tables are flipped, and the report that authorises it is
+-- recorded rather than implied. #135.
+--
+-- #135's acceptance reads "shadow-mode report shows zero unexpected denials on
+-- the synthetic fixture BEFORE force is enabled". Two things were true and
+-- neither was the criterion: the report IS all-zero on the fixture, and it is
+-- all-zero vacuously — all six shadow tables hold zero rows — while
+-- `app.scaffold_set_mode` had never been called by anything. The 41 enforced
+-- tables got there because each owning slice passed 'enforce' to
+-- `scaffold_table` directly.
+--
+-- So this file does the step the criterion describes, and says out loud what the
+-- report is worth:
+--
+--   1. run `app.shadow_report()` and RECORD it, in a table, with the row counts
+--      beside it — so "zero denials" can be read together with "zero rows" and
+--      nobody mistakes one for the other later;
+--   2. flip the six with `app.scaffold_set_mode`, which is what it is for;
+--   3. refuse to flip a table that has rows AND unexpected denials — the guard
+--      the criterion is actually asking for, and the only reading under which
+--      "zero unexpected denials" means anything.
+--
+-- The flip is safe here precisely BECAUSE the tables are empty: an empty table
+-- cannot lose a row to a stricter policy. On a populated pool the guard is what
+-- stops it, and the recorded report is what an operator reads first. That is a
+-- weaker claim than the criterion implies, and it is the true one — the slice's
+-- own `002_shadow_report.sql` asserts the opposite outcome deliberately, by
+-- inserting rows and showing three unexpected denials, because seeing them is
+-- the point of the report.
+--
+-- Replay-safe: the record table is upserted by run, and set_mode re-applies the
+-- same template.
+
+CREATE TABLE IF NOT EXISTS app.scaffold_shadow_records (
+  id            bigserial PRIMARY KEY,
+  table_schema  text NOT NULL,
+  table_name    text NOT NULL,
+  rows_at_flip  bigint NOT NULL,
+  report        jsonb NOT NULL,
+  flipped_at    timestamptz NOT NULL DEFAULT now(),
+  note          text
+);
+COMMENT ON TABLE app.scaffold_shadow_records IS
+  'What the shadow report said at the moment a table was flipped to enforce (#135). rows_at_flip is stored beside it on purpose: a report of zero unexpected denials over zero rows is not evidence, and the two numbers have to be read together.';
+
+CREATE OR REPLACE FUNCTION app.scaffold_enforce(p_table regclass, p_note text DEFAULT NULL)
+RETURNS jsonb LANGUAGE plpgsql SECURITY DEFINER SET search_path = '' AS $$
+DECLARE
+  v_schema text; v_name text; v_rows bigint; v_report jsonb; v_unexpected int;
+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;
+  EXECUTE format('SELECT count(*) FROM %I.%I', v_schema, v_name) INTO v_rows;
+
+  SELECT coalesce(jsonb_agg(to_jsonb(r)), '[]'::jsonb) INTO v_report
+    FROM app.shadow_report() r
+   WHERE r.table_name = v_name;
+  SELECT coalesce(sum((e ->> 'unexpected_denials')::int), 0) INTO v_unexpected
+    FROM jsonb_array_elements(v_report) e;
+
+  -- The guard the criterion is actually asking for. Zero denials over zero rows
+  -- proves nothing, so it is only allowed to authorise a flip when there is
+  -- something to deny.
+  IF v_rows > 0 AND v_unexpected > 0 THEN
+    RAISE EXCEPTION
+      'scaffold_enforce: %.% has % row(s) and % unexpected denial(s) in shadow — flipping would take those rows away from someone',
+      v_schema, v_name, v_rows, v_unexpected
+      USING ERRCODE = '55000',
+            HINT = 'Read app.shadow_report() for this table: each unexpected denial is a row the old policy allowed and the template does not.';
+  END IF;
+
+  PERFORM app.scaffold_set_mode(p_table, 'enforce');
+  INSERT INTO app.scaffold_shadow_records (table_schema, table_name, rows_at_flip, report, note)
+  VALUES (v_schema, v_name, v_rows, v_report,
+          coalesce(p_note, CASE WHEN v_rows = 0 THEN 'flipped empty: no row can be lost to a stricter policy' END));
+  RETURN jsonb_build_object('table', v_schema || '.' || v_name, 'rows', v_rows, 'unexpected_denials', v_unexpected, 'mode', 'enforce');
+END $$;
+REVOKE ALL ON FUNCTION app.scaffold_enforce(regclass, text) FROM public, anon, authenticated;
+GRANT EXECUTE ON FUNCTION app.scaffold_enforce(regclass, text) TO service_role;
+
+DO $$
+DECLARE r record; v_res jsonb;
+BEGIN
+  FOR r IN SELECT table_schema, table_name FROM app.scaffold_registry WHERE mode = 'shadow'
+            ORDER BY table_schema, table_name
+  LOOP
+    CONTINUE WHEN to_regclass(format('%I.%I', r.table_schema, r.table_name)) IS NULL;
+    v_res := app.scaffold_enforce(format('%I.%I', r.table_schema, r.table_name)::regclass);
+    RAISE NOTICE '118: %', v_res;
+  END LOOP;
+END $$;