@fayz-ai/db 0.11.0 → 0.13.0

package/migrations/111_migration_excluded_is_a_decision.sql

@@ -0,0 +1,259 @@
+-- 111_migration_excluded_is_a_decision.sql
+--
+-- A rehearsal could never go green. Fix for #188, and for a defect underneath it.
+--
+-- #188 is that `migration.allowlist` points three V1 tables at
+-- `plg_financial_recurring_bills`, which nobody built -- PRD 05 specifies invoice
+-- + installments + ledger and never mentions recurrence. Offering those rows
+-- leaves them `pending`, and `migration.reconcile()` requires `pending = 0`.
+--
+-- Deferring them is the honest move (building a recurrence contract is product
+-- work, not a migration fix) -- except deferring did not help either, and that is
+-- the defect underneath: an explicitly EXCLUDED table produced an OPEN quarantine,
+-- and green also requires `quarantine_open = 0`. Nothing could ever clear it. Not
+-- a human, not a re-offer, not a resolution -- there is no ambiguity to resolve,
+-- the decision was taken in 091 and reviewed. So ANY rehearsal that offered a
+-- dead legacy table (`guests`, `payments`, `orders`, the previous vendor's
+-- `import_ef_*`) stayed red forever, for a reason nobody could act on.
+--
+-- The distinction this file draws:
+--
+--   · a table NOT IN the allowlist        -> open quarantine. A surprise. Someone
+--                                            has to look at it.
+--   · a table explicitly EXCLUDED         -> quarantine row written and RESOLVED
+--                                            on the spot, carrying the decision as
+--                                            its resolution. Still visible, because
+--                                            an extractor sending tables it was
+--                                            told not to send is worth seeing -- but
+--                                            it does not hold the batch red.
+--
+-- Replay-safe: CREATE OR REPLACE throughout; the allowlist rows are removed under
+-- the freeze's own documented unlock; the exclusion insert is an upsert.
+
+-- ── 1. the three rows say what they are: deferred, not undeliverable ──────
+DO $unlock$
+BEGIN
+  PERFORM set_config('migration.allowlist_unlock', 'on', true);
+  DELETE FROM migration.allowlist
+   WHERE source_table IN ('recurring_bills', 'recurring_bill_items', 'recurring_bill_occurrences');
+END $unlock$;
+
+INSERT INTO migration.excluded_tables (source_table, reason) VALUES
+  ('recurring_bills',            'Deferred: no destination contract. core-beauty-chef §3.1 lists recurrence under core-A financeiro base, but PRD 05 specifies invoice + installments + ledger and never defines recurrence, so plg_financial_recurring_bills was never built (#188). Re-admit to the allowlist in the wave that ships the contract; until then a rehearsal must not stay red for a table nobody can write.'),
+  ('recurring_bill_items',       'Deferred with recurring_bills (#188).'),
+  ('recurring_bill_occurrences', 'Deferred with recurring_bills (#188).')
+ON CONFLICT (source_table) DO UPDATE SET reason = EXCLUDED.reason;
+
+-- ── 2. a recorded decision is not an open question ────────────────────────
+CREATE OR REPLACE FUNCTION migration._quarantine(p_ledger_id bigint, p_batch uuid, p_kind text, p_reason text, p_payload jsonb, p_target_table text DEFAULT NULL, p_decided text DEFAULT NULL)
+RETURNS jsonb LANGUAGE plpgsql SECURITY DEFINER SET search_path = '' AS $$
+DECLARE v_q bigint; v_l migration.ledger%ROWTYPE;
+BEGIN
+  UPDATE migration.quarantine SET resolved_at = now(), resolution = 'superseded by a later offer of the same row'
+   WHERE ledger_id = p_ledger_id AND resolved_at IS NULL;
+  -- a row already at the destination keeps status 'migrated' (the earlier
+  -- version stays); the open quarantine row is what flags it
+  UPDATE migration.ledger SET status = CASE WHEN status = 'migrated' THEN 'migrated' ELSE 'quarantined' END,
+         reason = p_kind || ': ' || p_reason, batch_id = p_batch, target_table = coalesce(target_table, p_target_table)
+   WHERE id = p_ledger_id RETURNING * INTO v_l;
+  -- p_decided: this is not an ambiguity awaiting a human, it is a decision that
+  -- was already taken and reviewed in a migration file. The row is still written,
+  -- so an extractor sending tables it was told not to send stays visible — but it
+  -- lands RESOLVED, because nobody can "resolve" a decision that is already made.
+  -- Leaving it open made reconcile() unreachable forever: green requires
+  -- quarantine_open = 0, and no operator action could ever clear it (#188).
+  INSERT INTO migration.quarantine (ledger_id, tenant_id, batch_id, kind, reason, payload, resolved_at, resolution)
+  VALUES (p_ledger_id, v_l.tenant_id, p_batch, p_kind, p_reason, p_payload,
+          CASE WHEN p_decided IS NOT NULL THEN now() END, p_decided) RETURNING id INTO v_q;
+  PERFORM migration._count(p_batch, 'quarantined');
+  RETURN jsonb_build_object('status', 'quarantined', 'kind', p_kind, 'reason', p_reason, 'target_table', v_l.target_table,
+                            'target_id', v_l.target_id, 'ledger_id', p_ledger_id, 'quarantine_id', v_q);
+END $$;
+
+-- The added parameter makes a NEW function rather than replacing the old one, so
+-- every 5- and 6-argument call site would be ambiguous until the previous
+-- signature is gone. Dropping it here is what makes this replace rather than
+-- overload; the grant posture is restated because 102's bulk REVOKE loop ran
+-- before this signature existed.
+DROP FUNCTION IF EXISTS migration._quarantine(bigint, uuid, text, text, jsonb, text);
+REVOKE ALL ON FUNCTION migration._quarantine(bigint, uuid, text, text, jsonb, text, text) FROM public, anon, authenticated;
+
+CREATE OR REPLACE FUNCTION migration._upsert_row_impl(p_batch uuid, p_source_table text, p_source_numeric_id bigint, p_source_uuid uuid, p_cursor text, p_row jsonb)
+RETURNS jsonb LANGUAGE plpgsql SECURITY DEFINER SET search_path = '' AS $$
+DECLARE
+  b migration.batches%ROWTYPE;
+  a migration.allowlist%ROWTYPE;
+  l migration.ledger%ROWTYPE;
+  v_checksum text := md5(p_row::text);
+  v_target_table text;
+  v_target_id uuid;
+  v_mapped jsonb; v_row jsonb; v_meta jsonb; v_unres jsonb;
+  v_dest jsonb; v_fin jsonb;
+  v_res jsonb; v_status text; v_col text; v_excl text;
+  v_retry_split boolean := false;
+  x jsonb; v_xid bigint;
+BEGIN
+  SELECT * INTO b FROM migration.batches WHERE id = p_batch;
+  IF NOT FOUND THEN RAISE EXCEPTION 'upsert_row: unknown batch %', p_batch USING ERRCODE = 'P0002'; END IF;
+  IF b.status <> 'running' THEN
+    RAISE EXCEPTION 'upsert_row: batch % is % (only a running batch accepts rows)', p_batch, b.status USING ERRCODE = '55000';
+  END IF;
+  PERFORM migration._assert_fence(b.tenant_id);
+
+  SELECT * INTO a FROM migration.allowlist WHERE source_table = p_source_table;
+  v_target_table := a.target_table;
+
+  SELECT * INTO l FROM migration.ledger
+   WHERE source_project = b.source_project AND source_table = p_source_table
+     AND ((p_source_numeric_id IS NOT NULL AND source_numeric_id = p_source_numeric_id)
+       OR (p_source_numeric_id IS NULL AND source_uuid = p_source_uuid))
+     AND coalesce(target_table, '') = coalesce(v_target_table, '')
+   FOR UPDATE;
+  IF NOT FOUND THEN
+    INSERT INTO migration.ledger (source_project, source_table, source_numeric_id, source_uuid, tenant_id, target_table, checksum, cursor, batch_id, status)
+    VALUES (b.source_project, p_source_table, p_source_numeric_id, p_source_uuid, b.tenant_id, v_target_table, v_checksum, p_cursor, p_batch, 'pending')
+    RETURNING * INTO l;
+  ELSIF l.tenant_id <> b.tenant_id THEN
+    RETURN migration._quarantine(l.id, p_batch, 'tenant',
+      format('source row already belongs to tenant %s; this batch migrates tenant %s', l.tenant_id, b.tenant_id), p_row);
+  END IF;
+
+  -- allowlist
+  IF p_source_table LIKE 'import\_ef\_%' OR EXISTS (SELECT 1 FROM migration.excluded_tables e WHERE e.source_table = p_source_table) THEN
+    SELECT reason INTO v_excl FROM migration.excluded_tables e WHERE e.source_table = CASE WHEN p_source_table LIKE 'import\_ef\_%' THEN 'import_ef_*' ELSE p_source_table END;
+    RETURN migration._quarantine(l.id, p_batch, 'allowlist', 'source table is explicitly excluded: ' || coalesce(v_excl, 'no reason recorded'), p_row,
+      NULL, 'recorded decision: the table is in migration.excluded_tables');
+  END IF;
+  IF a.source_table IS NULL THEN
+    RETURN migration._quarantine(l.id, p_batch, 'allowlist', format('source table %s is not in the core-A allowlist', p_source_table), p_row);
+  END IF;
+  -- tenant identity of the source row vs the batch
+  IF b.source_tenant_id IS NOT NULL AND (p_row ->> 'tenant_id') ~ '^\d+$' AND (p_row ->> 'tenant_id')::bigint <> b.source_tenant_id THEN
+    RETURN migration._quarantine(l.id, p_batch, 'tenant',
+      format('source row tenant_id %s differs from the batch source_tenant_id %s', p_row ->> 'tenant_id', b.source_tenant_id), p_row);
+  END IF;
+
+  -- idempotency + delta
+  IF EXISTS (SELECT 1 FROM migration.quarantine q WHERE q.ledger_id = l.id AND q.resolved_at IS NULL AND md5(q.payload::text) = v_checksum) THEN
+    PERFORM migration._count(p_batch, 'skipped');
+    RETURN jsonb_build_object('status', 'skipped', 'reason', 'quarantined and unresolved: ' || coalesce(l.reason, ''),
+                              'target_table', l.target_table, 'target_id', l.target_id, 'ledger_id', l.id);
+  END IF;
+  IF l.status = 'migrated' THEN
+    -- a split destination that did not exist on the first offer (invoice) and exists now: run the writer again
+    SELECT EXISTS (SELECT 1 FROM migration.ledger s
+                    WHERE s.source_project = l.source_project AND s.source_table = l.source_table
+                      AND s.source_numeric_id IS NOT DISTINCT FROM l.source_numeric_id AND s.source_uuid IS NOT DISTINCT FROM l.source_uuid
+                      AND s.id <> l.id AND s.status IN ('pending', 'skipped') AND to_regclass(s.target_table) IS NOT NULL) INTO v_retry_split;
+    IF l.checksum = v_checksum AND NOT v_retry_split THEN
+      PERFORM migration._count(p_batch, 'skipped');
+      RETURN jsonb_build_object('status', 'skipped', 'reason', 'unchanged', 'target_table', l.target_table, 'target_id', l.target_id, 'ledger_id', l.id);
+    END IF;
+    IF l.checksum <> v_checksum AND migration.cursor_cmp(p_cursor, l.cursor) < 0 THEN
+      PERFORM migration._count(p_batch, 'skipped');
+      RETURN jsonb_build_object('status', 'skipped', 'reason', format('stale cursor: %s < %s already migrated', p_cursor, l.cursor),
+                                'target_table', l.target_table, 'target_id', l.target_id, 'ledger_id', l.id);
+    END IF;
+  END IF;
+
+  -- no writer yet: recorded, re-offered later
+  IF a.writer IS NULL THEN
+    UPDATE migration.ledger SET status = 'pending', reason = format('no destination writer for %s yet', v_target_table),
+           checksum = v_checksum, cursor = p_cursor, batch_id = p_batch WHERE id = l.id;
+    PERFORM migration._count(p_batch, 'pending');
+    RETURN jsonb_build_object('status', 'pending', 'reason', format('no destination writer for %s yet', v_target_table),
+                              'target_table', v_target_table, 'target_id', l.target_id, 'ledger_id', l.id);
+  END IF;
+
+  -- map + references
+  v_mapped := migration.map_row(b.source_project, p_source_table, p_row);
+  v_row := v_mapped -> 'row'; v_meta := v_mapped -> 'metadata'; v_unres := v_mapped -> 'unresolved';
+  IF jsonb_array_length(v_unres) > 0 THEN
+    RETURN migration._quarantine(l.id, p_batch, 'fk', 'unresolved reference(s): ' || v_unres::text, p_row);
+  END IF;
+
+  -- destination id (ADR 0007): the source uuid, else the id minted on the first offer
+  v_target_id := coalesce(l.target_id, p_source_uuid, gen_random_uuid());
+  v_meta := jsonb_set(v_meta, '{migration}', coalesce(v_meta -> 'migration', '{}'::jsonb) || jsonb_build_object(
+              'source_project', b.source_project, 'source_table', p_source_table, 'source_numeric_id', p_source_numeric_id,
+              'source_uuid', p_source_uuid, 'batch_id', p_batch), true);
+  v_row := v_row || jsonb_build_object('metadata', v_meta);
+  SELECT coalesce(jsonb_object_agg(c, v_row -> c), '{}'::jsonb) INTO v_fin FROM unnest(a.financial_columns) c WHERE v_row ? c;
+
+  -- never overwrite an existing financial value; never re-create a deleted row
+  IF l.status = 'migrated' THEN
+    IF cardinality(a.financial_columns) > 0 THEN
+      v_dest := migration._destination_values(v_target_table, l.target_id, a.financial_columns);
+      IF v_dest IS NULL THEN
+        RETURN migration._quarantine(l.id, p_batch, 'state', 'target row no longer exists in the destination (deleted after migration); not re-created', p_row);
+      END IF;
+      FOREACH v_col IN ARRAY a.financial_columns LOOP
+        IF (v_row ? v_col) AND round(coalesce((v_row ->> v_col)::numeric, 0), 2) IS DISTINCT FROM round(coalesce((v_dest ->> v_col)::numeric, 0), 2) THEN
+          RETURN migration._quarantine(l.id, p_batch, 'value',
+            format('financial column %s: destination %s, incoming %s — an existing financial value is never overwritten', v_col, coalesce(v_dest ->> v_col, 'null'), coalesce(v_row ->> v_col, 'null')), p_row);
+        END IF;
+      END LOOP;
+    ELSIF migration._destination_values(v_target_table, l.target_id, ARRAY['id']) IS NULL THEN
+      RETURN migration._quarantine(l.id, p_batch, 'state', 'target row no longer exists in the destination (deleted after migration); not re-created', p_row);
+    END IF;
+  END IF;
+
+  -- delegate; any error is a state quarantine, never a partial write
+  BEGIN
+    v_res := CASE a.writer
+      WHEN 'person'   THEN migration.upsert_person(b.tenant_id, v_target_id, v_row, a.writer_args)
+      WHEN 'unit'     THEN migration.upsert_unit(b.tenant_id, v_target_id, v_row, a.writer_args)
+      WHEN 'category' THEN migration.upsert_category(b.tenant_id, v_target_id, v_row, a.writer_args)
+      WHEN 'product'  THEN migration.upsert_product(b.tenant_id, v_target_id, v_row, a.writer_args)
+      WHEN 'order'    THEN migration.upsert_order(b.tenant_id, v_target_id, v_row, a.writer_args)
+      WHEN 'invoice'  THEN migration.upsert_invoice(b.tenant_id, v_target_id, v_row, a.writer_args)
+    END;
+  EXCEPTION WHEN OTHERS THEN
+    v_res := jsonb_build_object('status', 'quarantined', 'kind', 'state', 'reason', format('%s: %s', SQLSTATE, SQLERRM));
+  END;
+  v_status := coalesce(v_res ->> 'status', 'quarantined');
+
+  IF v_status = 'quarantined' THEN
+    RETURN migration._quarantine(l.id, p_batch, coalesce(v_res ->> 'kind', 'state'), coalesce(v_res ->> 'reason', 'writer refused'), p_row);
+  END IF;
+  IF v_status = 'skipped' THEN
+    UPDATE migration.ledger SET status = 'skipped', reason = v_res ->> 'reason', checksum = v_checksum, cursor = p_cursor, batch_id = p_batch,
+           target_id = coalesce((v_res ->> 'target_id')::uuid, target_id) WHERE id = l.id;
+    PERFORM migration._count(p_batch, 'skipped');
+    RETURN jsonb_build_object('status', 'skipped', 'reason', v_res ->> 'reason', 'target_table', v_target_table, 'target_id', v_res ->> 'target_id', 'ledger_id', l.id);
+  END IF;
+
+  v_target_id := coalesce((v_res ->> 'target_id')::uuid, v_target_id);
+  UPDATE migration.ledger
+     SET status = 'migrated', target_table = v_target_table, target_id = v_target_id, checksum = v_checksum, cursor = p_cursor,
+         batch_id = p_batch, reason = v_res ->> 'reason', financial = nullif(v_fin, '{}'::jsonb)
+   WHERE id = l.id;
+  UPDATE migration.quarantine SET resolved_at = now(), resolution = 'row migrated on a later offer' WHERE ledger_id = l.id AND resolved_at IS NULL;
+
+  -- split rows (a Venda's invoice): one more ledger row per extra destination
+  FOR x IN SELECT value FROM jsonb_array_elements(coalesce(v_res -> 'extra', '[]'::jsonb)) LOOP
+    SELECT id INTO v_xid FROM migration.ledger
+     WHERE source_project = b.source_project AND source_table = p_source_table
+       AND source_numeric_id IS NOT DISTINCT FROM p_source_numeric_id AND source_uuid IS NOT DISTINCT FROM p_source_uuid
+       AND target_table = x ->> 'target_table';
+    IF v_xid IS NULL THEN
+      INSERT INTO migration.ledger (source_project, source_table, source_numeric_id, source_uuid, tenant_id, target_table, target_id, checksum, cursor, batch_id, status, reason, financial)
+      VALUES (b.source_project, p_source_table, p_source_numeric_id, p_source_uuid, b.tenant_id, x ->> 'target_table', (x ->> 'target_id')::uuid,
+              v_checksum, p_cursor, p_batch, x ->> 'status', x ->> 'reason', nullif(x -> 'financial', 'null'::jsonb));
+    ELSE
+      UPDATE migration.ledger SET target_id = (x ->> 'target_id')::uuid, checksum = v_checksum, cursor = p_cursor, batch_id = p_batch,
+             status = x ->> 'status', reason = x ->> 'reason', financial = coalesce(nullif(x -> 'financial', 'null'::jsonb), financial) WHERE id = v_xid;
+    END IF;
+  END LOOP;
+
+  INSERT INTO public.audit_logs (tenant_id, user_id, action, entity_type, entity_id, metadata)
+  VALUES (b.tenant_id, NULL, 'migration.upsert', v_target_table, v_target_id::text,
+          jsonb_build_object('batch_id', p_batch, 'source_project', b.source_project, 'source_table', p_source_table,
+                             'source_numeric_id', p_source_numeric_id, 'source_uuid', p_source_uuid, 'reason', v_res ->> 'reason'));
+  PERFORM migration._count(p_batch, 'migrated');
+  RETURN jsonb_build_object('status', 'migrated', 'reason', v_res ->> 'reason', 'target_table', v_target_table, 'target_id', v_target_id,
+                            'ledger_id', l.id, 'merged', coalesce((v_res ->> 'merged')::boolean, false), 'extra', coalesce(v_res -> 'extra', '[]'::jsonb));
+END $$;
+
+-- The generic destination write. Marks the transaction as a migration writer
+-- (so the PONR triggers of 093 stay quiet) for the duration of the call only.

package/migrations/111_replacing_a_view_keeps_its_dependents.sql

@@ -0,0 +1,132 @@
+-- ============================================================================
+-- 111_replacing_a_view_keeps_its_dependents.sql — a view can be reshaped even
+-- when something reads it.
+--
+-- Four files in this chain hit the same wall on a pool that already has the
+-- view they declare: `DROP VIEW` refuses while anything depends on it, and
+-- `CREATE OR REPLACE` refuses to reorder or rename columns. Between the two
+-- there is no way to change a view's SHAPE — and the shape moves on its own,
+-- because a view written `SELECT t.*` follows its table, and the scoping wave
+-- adds `unit_id` to those tables.
+--
+-- CASCADE is not the answer: it drops the dependents silently and the pool comes
+-- back missing a report nobody notices until someone opens it.
+--
+-- So the dependents are captured first, dropped, and put back from their own
+-- definitions afterwards. Two calls around the replace:
+--
+--     SELECT app.detach_view_dependents('public.v_leads');   -- returns them
+--     DROP VIEW IF EXISTS public.v_leads;
+--     CREATE VIEW public.v_leads … ;
+--     SELECT app.reattach_view_dependents();                 -- puts them back
+--
+-- security_invoker travels with them. A dependent that came back definer would
+-- answer with the owner's rights over a tenant_id table — the leak 043 swept out
+-- of v_documents, reintroduced by the very act of rebuilding.
+-- ============================================================================
+
+CREATE TABLE IF NOT EXISTS app.view_replace_stash (
+  id         bigserial PRIMARY KEY,
+  view_name  text NOT NULL,
+  definition text NOT NULL,
+  invoker    boolean NOT NULL DEFAULT false,
+  grants     jsonb NOT NULL DEFAULT '[]'::jsonb,
+  depth      integer NOT NULL DEFAULT 0
+);
+COMMENT ON TABLE app.view_replace_stash IS
+  'Scratch for 111: views dropped so one below them could be reshaped, waiting to be rebuilt in the same migration.';
+
+CREATE OR REPLACE FUNCTION app.detach_view_dependents(p_view text)
+RETURNS integer LANGUAGE plpgsql AS $$
+DECLARE
+  r      record;
+  v_n    integer := 0;
+  v_lvl  integer := 0;
+BEGIN
+  DELETE FROM app.view_replace_stash;
+  IF to_regclass(p_view) IS NULL THEN RETURN 0; END IF;
+
+  -- THE WHOLE TREE, NOT JUST THE FIRST LEVEL. A report reads a view that reads
+  -- the one being reshaped, and dropping the middle one fails for exactly the
+  -- reason we are here. The recursive walk collects every descendant with the
+  -- distance from the root, so they can go deepest-first and come back the
+  -- other way round.
+  FOR r IN
+    WITH RECURSIVE tree(oid, lvl) AS (
+      SELECT to_regclass(p_view)::oid, 0
+      UNION
+      SELECT dv.oid, t.lvl + 1
+        FROM tree t
+        JOIN pg_depend d ON d.refobjid = t.oid
+        JOIN pg_rewrite rw ON rw.oid = d.objid
+        JOIN pg_class dv ON dv.oid = rw.ev_class AND dv.relkind = 'v'
+       WHERE dv.oid <> t.oid AND t.lvl < 10
+    )
+    -- Deepest FIRST: the outermost view has to go before the one it reads, which
+    -- is the whole reason a plain DROP failed. A view reachable by two paths
+    -- keeps its longest distance, so it is never dropped before something that
+    -- still depends on it.
+    SELECT d.name, d.def, d.invoker, d.lvl
+      FROM (
+        SELECT DISTINCT ON (t.oid)
+               quote_ident(dn.nspname) || '.' || quote_ident(dv.relname) AS name,
+               pg_get_viewdef(dv.oid, true) AS def,
+               COALESCE(array_to_string(dv.reloptions, ',') LIKE '%security_invoker=true%', false) AS invoker,
+               t.lvl
+          FROM tree t
+          JOIN pg_class dv ON dv.oid = t.oid
+          JOIN pg_namespace dn ON dn.oid = dv.relnamespace
+         WHERE t.lvl > 0
+         ORDER BY t.oid, t.lvl DESC
+      ) d
+     ORDER BY d.lvl DESC
+  LOOP
+    v_lvl := r.lvl;
+    INSERT INTO app.view_replace_stash (view_name, definition, invoker, grants, depth)
+    SELECT r.name, r.def, r.invoker,
+           COALESCE(jsonb_agg(DISTINCT jsonb_build_object('grantee', g.grantee, 'priv', g.privilege_type))
+                    FILTER (WHERE g.grantee IS NOT NULL), '[]'::jsonb),
+           v_lvl
+      FROM information_schema.role_table_grants g
+     WHERE g.table_schema = split_part(replace(r.name, '"', ''), '.', 1)
+       AND g.table_name = split_part(replace(r.name, '"', ''), '.', 2)
+       AND g.grantee IN ('anon', 'authenticated', 'service_role');
+
+    EXECUTE format('DROP VIEW IF EXISTS %s', r.name);
+    v_n := v_n + 1;
+  END LOOP;
+  RETURN v_n;
+END $$;
+
+CREATE OR REPLACE FUNCTION app.reattach_view_dependents()
+RETURNS integer LANGUAGE plpgsql AS $$
+DECLARE r record; g record; v_n integer := 0;
+BEGIN
+  -- Deepest last out, first back in.
+  FOR r IN SELECT * FROM app.view_replace_stash ORDER BY depth ASC, id ASC LOOP
+    BEGIN
+      EXECUTE format('CREATE VIEW %s %s AS %s',
+        r.view_name,
+        CASE WHEN r.invoker THEN 'WITH (security_invoker = true)' ELSE '' END,
+        r.definition);
+      FOR g IN SELECT * FROM jsonb_to_recordset(r.grants) AS x(grantee text, priv text) LOOP
+        EXECUTE format('GRANT %s ON %s TO %I', g.priv, r.view_name, g.grantee);
+      END LOOP;
+      v_n := v_n + 1;
+    EXCEPTION WHEN OTHERS THEN
+      -- A dependent that no longer fits is EXPECTED, not an error to stop on:
+      -- the whole point of the replace is that the view underneath changed
+      -- shape, and a report written against the old columns cannot survive
+      -- that. crm's rep_leads reads `status` where v_leads now says
+      -- `lead_status` — and the file that owns that report rebuilds it correctly
+      -- later in this same chain. Failing here would stop the migration to
+      -- preserve a view that is about to be replaced anyway.
+      RAISE NOTICE '111: % not restored (%) — its own migration rebuilds it', r.view_name, SQLERRM;
+    END;
+  END LOOP;
+  DELETE FROM app.view_replace_stash;
+  RETURN v_n;
+END $$;
+
+REVOKE ALL ON FUNCTION app.detach_view_dependents(text) FROM public, anon, authenticated;
+REVOKE ALL ON FUNCTION app.reattach_view_dependents() FROM public, anon, authenticated;

package/migrations/112_money_precision_standard.sql

@@ -0,0 +1,132 @@
+-- 112_money_precision_standard.sql
+--
+-- One money standard, pinned where it was left open. Fix for #182.
+--
+-- The review asked whether the amount columns should be `decimal`. In Postgres
+-- `decimal` IS `numeric` — an alias — so on that axis there was nothing to
+-- change, and the property that actually matters already held: no money column
+-- anywhere in the chain is a float. But underneath the question was a real
+-- inconsistency. `plg_financial_*` amounts are `numeric(14,2)`, unit costs are
+-- `numeric(16,4)`, rates are `numeric(7,4)` — all deliberate — while the oldest
+-- columns in the chain, from `004_archetypes.sql`, are **bare `numeric`**:
+-- unbounded scale, so 19.999999 is a legal price and rounds differently at every
+-- reader that touches it.
+--
+-- The standard, written in DATA-MODEL.md and enforced by
+-- scripts/check-money-columns.mjs from this commit:
+--
+--   amounts        numeric(14,2)
+--   unit costs     numeric(16,4)      (a unit cost genuinely needs four)
+--   rates          numeric(7,4)
+--   quantities     numeric(14,4)
+--   never float; integer cents only where a provider's API dictates it, and
+--   never for tenant-facing money.
+--
+-- WHY THIS REFUSES RATHER THAN ROUNDS. `ALTER TYPE numeric(14,2)` silently
+-- rounds every existing value that has more scale than that. On a pool where a
+-- price really is 19.999, that is money changing without anyone deciding it —
+-- exactly what #148's "no silent correction" rule forbids, applied to the schema
+-- instead of to a migrated row. So each column is checked first and the
+-- migration STOPS with the offending count if rounding would lose anything.
+-- Nothing in the fleet is expected to trip it; if one does, that pool needs a
+-- human, not a DDL statement.
+--
+-- products.stock / min_stock are deliberately NOT pinned: they are quantities,
+-- they are deprecated mirrors, and #185 retires them. Pinning a column on its way
+-- out is churn.
+--
+-- Driven off the LIVE schema rather than a hand-written list, for two reasons.
+-- A list goes stale the moment a slice adds a column, and — the reason a static
+-- lint was tried first and thrown away — the migration files cannot answer this
+-- question at all: `v_amount numeric` in a DECLARE block and `p_total numeric` in
+-- an RPC signature are not columns and are perfectly correct as they are, but
+-- they read identically to a column declaration in the text. The catalog knows
+-- the difference. The posture suite (900_verification) asserts the result, so the
+-- rule holds for every column a future slice adds, not just today's.
+--
+-- Replay-safe: each ALTER is guarded on the current type, so a second run is a
+-- no-op.
+
+DO $$
+DECLARE
+  r record;
+  v_dep record;
+  v_views jsonb := '[]'::jsonb;
+  i int;
+  v_bad bigint;
+  v_scale integer;
+  v_n   integer := 0;
+BEGIN
+  FOR r IN
+    SELECT c.relname AS tbl, a.attname AS col, format_type(a.atttypid, a.atttypmod) AS typ
+      FROM pg_attribute a
+      JOIN pg_class c ON c.oid = a.attrelid
+      JOIN pg_namespace n ON n.oid = c.relnamespace
+     WHERE n.nspname = 'public' AND c.relkind = 'r' AND a.attnum > 0 AND NOT a.attisdropped
+       -- a column whose NAME says money. Narrow on purpose: a false positive here
+       -- rewrites a column that was right, which is worse than a miss.
+       AND (a.attname IN ('amount', 'total', 'subtotal', 'price', 'cost', 'balance',
+                          'paid_amount', 'fee_amount', 'discount_value', 'interest_value',
+                          'opening_balance', 'closing_balance', 'total_amount', 'unit_price',
+                          'price_delta', 'expected_amount', 'counted_amount', 'difference_amount')
+            OR a.attname LIKE '%\_amount' OR a.attname LIKE '%\_price' OR a.attname LIKE '%\_total')
+       -- …and is NOT one of the things that merely sounds like money
+       AND a.attname NOT LIKE '%\_count' AND a.attname NOT LIKE '%\_percent'
+       AND a.attname NOT LIKE '%\_rate' AND a.attname NOT LIKE '%quantity%'
+       -- bare numeric (unbounded scale) is the case being closed; a float would be
+       -- worse and is reported by the same query.
+       AND format_type(a.atttypid, a.atttypmod) IN ('numeric', 'real', 'double precision')
+     ORDER BY c.relname, a.attname
+  LOOP
+    IF r.typ <> 'numeric' THEN
+      RAISE EXCEPTION '102: public.%.% is % — money is never a float', r.tbl, r.col, r.typ
+        USING ERRCODE = '22003';
+    END IF;
+    -- A UNIT price is not an amount, and this file's own standard says so:
+    -- "unit costs numeric(16,4) (a unit cost genuinely needs four)". The name
+    -- heuristic above cannot tell them apart -- `unit_price` matches `%_price`
+    -- and would be pinned to two -- so the exceptions are named here.
+    --
+    -- resto's order_items proved it: 2.137 x 2000 units is 4274.00 exactly, and
+    -- two decimals turns that into 4280.00. The scale is the data, not noise.
+    -- The unit-cost set. `cost` reads like an amount and is one on a document,
+    -- but on a PRODUCT it is what one unit costs — resto carries 2.137 and
+    -- 35.9002, all of which land exactly on four and none on two.
+    v_scale := CASE WHEN r.col IN ('unit_price', 'unit_cost', 'cost', 'avg_cost', 'last_cost')
+                    THEN 4 ELSE 2 END;
+
+    EXECUTE format('SELECT count(*) FROM public.%I WHERE %I IS NOT NULL AND %I <> round(%I, %s)',
+                   r.tbl, r.col, r.col, r.col, v_scale)
+      INTO v_bad;
+    IF v_bad > 0 THEN
+      RAISE EXCEPTION
+        '102: public.%.% holds % value(s) with more than % decimals; pinning would round money without anyone deciding it',
+        r.tbl, r.col, v_bad, v_scale
+        USING ERRCODE = '22003',
+              HINT = 'Decide what those values should be and correct them, then re-run. This migration will not round them for you.';
+    END IF;
+    -- A view over the column makes ALTER TYPE fail outright, and this sweep runs
+    -- over every public table — including the ones a vertical brought with it
+    -- (resto's menu_items/v_menu_items is the case that found this).
+    --
+    -- This USED TO capture the direct dependents and DROP … CASCADE. Both halves
+    -- were wrong, and salon showed it: CASCADE takes the views it was never told
+    -- about — v_invoice_balances went that way — and the naive reverse-order
+    -- rebuild then failed on v_appointments, which reads it. 111 already solves
+    -- exactly this: it walks the WHOLE tree, records the distance, drops
+    -- deepest-first and rebuilds the other way round, carrying security_invoker.
+    PERFORM app.detach_view_dependents(format('public.%I', r.tbl));
+
+    EXECUTE format('ALTER TABLE public.%I ALTER COLUMN %I TYPE numeric(%s,%s)',
+                   r.tbl, r.col, CASE WHEN v_scale = 4 THEN 16 ELSE 14 END, v_scale);
+
+    PERFORM app.reattach_view_dependents();
+    v_n := v_n + 1;
+  END LOOP;
+  RAISE NOTICE '102: pinned % money column(s) to numeric(14,2)', v_n;
+END $$;
+
+COMMENT ON COLUMN public.products.price IS
+  'Money: numeric(14,2) (#182). Amounts are (14,2), unit costs (16,4), rates (7,4), quantities (14,4) — never float, and never integer cents for tenant-facing money.';
+COMMENT ON COLUMN public.products.cost IS
+  'Money: numeric(14,2) (#182). A per-unit inventory cost that needs four decimals lives on plg_inventory_stock_positions.unit_cost, not here.';

package/migrations/113_addresses_units_companies.sql

@@ -0,0 +1,114 @@
+-- 113_addresses_units_companies.sql
+--
+-- A unit's address becomes a typed thing again. Partial fix for #180.
+--
+-- `public.addresses` is the spine's address book — structured, polymorphic,
+-- moved out of the shop in `017` precisely so there would be ONE model of "where
+-- something is". Two Phase 0 tables never got the memo:
+--
+--   · `public.company_legal_entities` (#138) inlines seven address columns,
+--     because PRD 02 R2 lists "endereço fiscal" as fields of the Empresa and the
+--     slice implemented that literally;
+--   · `app.units` has no typed address AT ALL — worse than inline. It inherited
+--     a metadata bag from the `locations` → `units` projection (#134), where the
+--     address survives as loose keys (`metadata->>'address'`, `->>'city'`…).
+--     Against V1's `locations`, which had typed columns, that is a regression.
+--
+-- WHAT THIS FILE DOES, AND WHAT IT DELIBERATELY LEAVES:
+--
+-- It establishes the canonical shape — the owner types, the backfill, and a flat
+-- read view for each — so the shape is settled BEFORE the V1 extractor grows an
+-- address writer (it has none today: every address row lands `pending`). Getting
+-- this right after data lands costs a migration per tenant.
+--
+-- It does NOT move the write path. Today a unit's address is written through the
+-- `public.locations` compat projection, which packs it into `units.metadata`
+-- inside one clause of a large trigger — and Phase 1 (#214) deletes that
+-- projection outright. Rewiring it here, then deleting it there, is work thrown
+-- away twice. So `addresses` becomes the canonical READ model now and the write
+-- path moves with the retirement, which is where it belongs.
+--
+-- The consequence to be honest about: until #214, an address edited through
+-- `locations` updates `units.metadata` and NOT `public.addresses`. The view says
+-- so, and the metadata keys carry a deprecation comment. This is a staged move,
+-- not a finished one.
+--
+-- Replay-safe: the CHECKs are dropped and rebuilt WIDER (never narrower — 017's
+-- own rule), the backfill is `WHERE NOT EXISTS`, the views are CREATE OR REPLACE.
+
+-- ── 1. two more things can own an address ────────────────────────────────
+ALTER TABLE public.addresses DROP CONSTRAINT IF EXISTS addresses_owner_type_check;
+ALTER TABLE public.addresses
+  ADD CONSTRAINT addresses_owner_type_check
+  CHECK (owner_type IN ('person', 'shop_customer', 'location', 'tenant', 'unit', 'company_legal_entity'));
+
+ALTER TABLE public.addresses DROP CONSTRAINT IF EXISTS addresses_kind_check;
+ALTER TABLE public.addresses
+  ADD CONSTRAINT addresses_kind_check
+  CHECK (kind IN ('shipping', 'billing', 'both', 'main', 'fiscal'));
+
+-- ── 2. backfill what already exists ──────────────────────────────────────
+-- Only rows that can be represented honestly: postal_code, street, city and
+-- state are NOT NULL on addresses, and inventing a value to satisfy a constraint
+-- is how a fiscal address quietly becomes wrong. Partial ones are counted and
+-- left where they are.
+DO $$
+DECLARE v_units integer; v_cle integer; v_skipped integer;
+BEGIN
+  INSERT INTO public.addresses (tenant_id, owner_type, owner_id, kind, postal_code, street, number, complement, district, city, state, country, metadata)
+  SELECT u.tenant_id, 'unit', u.id, 'main',
+         u.metadata ->> 'postal_code', u.metadata ->> 'address', u.metadata ->> 'address_number',
+         u.metadata ->> 'address_complement', u.metadata ->> 'district',
+         u.metadata ->> 'city', u.metadata ->> 'state', coalesce(u.metadata ->> 'country', 'BR'),
+         jsonb_build_object('source', 'migration:103', 'from', 'units.metadata')
+    FROM app.units u
+   WHERE nullif(btrim(coalesce(u.metadata ->> 'postal_code', '')), '') IS NOT NULL
+     AND nullif(btrim(coalesce(u.metadata ->> 'address', '')), '') IS NOT NULL
+     AND nullif(btrim(coalesce(u.metadata ->> 'city', '')), '') IS NOT NULL
+     AND nullif(btrim(coalesce(u.metadata ->> 'state', '')), '') IS NOT NULL
+     AND NOT EXISTS (SELECT 1 FROM public.addresses a WHERE a.owner_type = 'unit' AND a.owner_id = u.id);
+  GET DIAGNOSTICS v_units = ROW_COUNT;
+
+  SELECT count(*)::int INTO v_skipped FROM app.units u
+   WHERE NOT EXISTS (SELECT 1 FROM public.addresses a WHERE a.owner_type = 'unit' AND a.owner_id = u.id)
+     AND (u.metadata ?| ARRAY['address', 'city', 'state', 'postal_code']);
+
+  INSERT INTO public.addresses (tenant_id, owner_type, owner_id, kind, postal_code, street, number, complement, district, city, state, country, metadata)
+  SELECT c.tenant_id, 'company_legal_entity', c.id, 'fiscal',
+         c.postal_code, c.address, c.address_number, c.address_complement, c.district,
+         c.city, c.state, coalesce(c.country, 'BR'),
+         jsonb_build_object('source', 'migration:103', 'from', 'company_legal_entities')
+    FROM public.company_legal_entities c
+   WHERE nullif(btrim(coalesce(c.postal_code, '')), '') IS NOT NULL
+     AND nullif(btrim(coalesce(c.address, '')), '') IS NOT NULL
+     AND nullif(btrim(coalesce(c.city, '')), '') IS NOT NULL
+     AND nullif(btrim(coalesce(c.state, '')), '') IS NOT NULL
+     AND NOT EXISTS (SELECT 1 FROM public.addresses a WHERE a.owner_type = 'company_legal_entity' AND a.owner_id = c.id);
+  GET DIAGNOSTICS v_cle = ROW_COUNT;
+
+  RAISE NOTICE '103: % unit address(es), % company address(es) moved into public.addresses; % unit(s) had partial address data and were left alone', v_units, v_cle, v_skipped;
+END $$;
+
+-- ── 3. flat read views, so consumers do not learn a join ─────────────────
+CREATE OR REPLACE VIEW public.v_unit_address WITH (security_invoker = true) AS
+SELECT u.id AS unit_id, u.tenant_id, u.slug, u.name,
+       a.id AS address_id, a.postal_code, a.street, a.number, a.complement, a.district,
+       a.city, a.state, a.country
+  FROM app.units u
+  LEFT JOIN public.addresses a ON a.owner_type = 'unit' AND a.owner_id = u.id;
+
+COMMENT ON VIEW public.v_unit_address IS
+  'A unit and its address (#180). NOTE: until the locations projection is retired (#214) the WRITE path is still public.locations -> units.metadata, so a very recent edit may not be here yet. Reads should prefer this view; writes still go through locations.';
+
+CREATE OR REPLACE VIEW public.v_company_legal_entity_address WITH (security_invoker = true) AS
+SELECT c.id AS company_legal_entity_id, c.tenant_id, c.legal_name, c.document_number,
+       a.id AS address_id, a.postal_code, a.street, a.number, a.complement, a.district,
+       a.city, a.state, a.country
+  FROM public.company_legal_entities c
+  LEFT JOIN public.addresses a ON a.owner_type = 'company_legal_entity' AND a.owner_id = c.id;
+
+COMMENT ON VIEW public.v_company_legal_entity_address IS
+  'An Empresa and its fiscal address (#180). The inline columns on company_legal_entities are deprecated mirrors kept for #138''s consumers; public.addresses is the model.';
+
+COMMENT ON COLUMN public.company_legal_entities.address IS
+  'DEPRECATED (#180): the fiscal address belongs in public.addresses (owner_type company_legal_entity, kind fiscal). Read v_company_legal_entity_address.';