@fayz-ai/db 0.12.0 → 0.13.0

package/migrations/139_distributable_is_a_scaffold_option.sql

@@ -0,0 +1,109 @@
+-- ============================================================================
+-- 139_distributable_is_a_scaffold_option.sql — multi-unit distribution stops
+-- being hand-wired, and `people` gets it (#224).
+--
+-- The RESTRICTIVE release policy was written by hand on six catalog tables and
+-- was absent from `people`. So "a provider serves 2 of 15 branches" was covered
+-- when the provider LOGS IN (a membership plus two membership_units rows) and not
+-- covered when the provider is a record — which is most providers.
+--
+-- The mechanism was always generic: `resource_grants` is
+-- (resource_type, resource_id, relation, subject_type, subject_id) and serves
+-- anything. What was not generic is the wiring, and for an SDK meant to carry a
+-- fleet, "does this table support multi-unit distribution" cannot depend on
+-- whether someone remembered to write a policy.
+--
+-- TWO SHAPES, because the six hand-written policies had two:
+--
+--   self-keyed   products, services, service_packages
+--                `unit_id IS NOT NULL OR available_in_my_units(rt, id)`
+--                the unit escape is the point: a row that BELONGS to a branch is
+--                governed by has_unit, and only a network row is distributed
+--                (#225 — "Vela B2" is a real, tested case)
+--   parent-keyed product_variants, price_table_items, service_package_items
+--                `available_in_my_units(rt, <parent>_id)`
+--                a variant is released with the product it varies, never on its
+--                own; no escape, because the parent's row is the one that has a
+--                unit
+--
+-- Replay-safe: additive columns, generated policy dropped and recreated.
+-- ============================================================================
+
+ALTER TABLE app.scaffold_registry ADD COLUMN IF NOT EXISTS distributable boolean NOT NULL DEFAULT false;
+ALTER TABLE app.scaffold_registry ADD COLUMN IF NOT EXISTS dist_resource_type text;
+ALTER TABLE app.scaffold_registry ADD COLUMN IF NOT EXISTS dist_key_column text;
+ALTER TABLE app.scaffold_registry ADD COLUMN IF NOT EXISTS dist_unit_escape boolean;
+COMMENT ON COLUMN app.scaffold_registry.distributable IS
+  'Whether this table carries the generated RESTRICTIVE release policy (#224). dist_resource_type/dist_key_column say WHICH resource the row is released with — a variant is released with its product.';
+
+-- ── declare a table distributable, and generate its release policy ──────
+CREATE OR REPLACE FUNCTION app.scaffold_distributable(
+  p_table         regclass,
+  p_resource_type text    DEFAULT NULL,   -- defaults to the table's own resource_type
+  p_key_column    text    DEFAULT 'id',
+  p_unit_escape   boolean DEFAULT true,
+  p_enabled       boolean DEFAULT true
+)
+RETURNS void
+LANGUAGE plpgsql SECURITY DEFINER SET search_path = ''
+AS $$
+DECLARE
+  v_schema text; v_name text; v_q text; v_policy text;
+  r app.scaffold_registry%ROWTYPE; v_rt text;
+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;
+  v_q := format('%I.%I', v_schema, v_name);
+  v_policy := v_name || '_available_in';
+
+  SELECT * INTO r FROM app.scaffold_registry WHERE table_schema = v_schema AND table_name = v_name;
+  IF NOT FOUND THEN
+    RAISE EXCEPTION 'scaffold_distributable: %.% is not scaffolded', v_schema, v_name USING ERRCODE = 'P0002';
+  END IF;
+  v_rt := coalesce(p_resource_type, r.resource_type);
+
+  EXECUTE format('DROP POLICY IF EXISTS %I ON %s', v_policy, v_q);
+
+  IF p_enabled THEN
+    IF NOT EXISTS (SELECT 1 FROM information_schema.columns
+                    WHERE table_schema = v_schema AND table_name = v_name AND column_name = p_key_column) THEN
+      RAISE EXCEPTION 'scaffold_distributable: %.% has no column %', v_schema, v_name, p_key_column;
+    END IF;
+    -- RESTRICTIVE: permissive policies OR together, so a release rule that is
+    -- meant to REMOVE rows has to AND with the scaffold's select.
+    EXECUTE format(
+      'CREATE POLICY %I ON %s AS RESTRICTIVE FOR SELECT TO authenticated USING (%s(select app.available_in_my_units(%L, %I)))',
+      v_policy, v_q,
+      CASE WHEN p_unit_escape THEN 'unit_id IS NOT NULL OR ' ELSE '' END,
+      v_rt, p_key_column);
+  END IF;
+
+  UPDATE app.scaffold_registry
+     SET distributable = p_enabled,
+         dist_resource_type = CASE WHEN p_enabled THEN v_rt END,
+         dist_key_column    = CASE WHEN p_enabled THEN p_key_column END,
+         dist_unit_escape   = CASE WHEN p_enabled THEN p_unit_escape END
+   WHERE table_schema = v_schema AND table_name = v_name;
+END $$;
+REVOKE ALL ON FUNCTION app.scaffold_distributable(regclass, text, text, boolean, boolean) FROM public, anon, authenticated;
+
+COMMENT ON FUNCTION app.scaffold_distributable(regclass, text, text, boolean, boolean) IS
+  'Generate (or remove) a table''s RESTRICTIVE release policy (#224). Whether a table supports multi-unit distribution becomes a declaration in the registry rather than a policy somebody remembered to write.';
+
+-- ── convert the six hand-written catalog policies ───────────────────────
+-- Same predicates, now generated. 075/077's CREATE POLICY statements stay in
+-- their files (never edited); the scaffold drops and re-creates the same name,
+-- so a replay converges on the generated one.
+SELECT app.scaffold_distributable('public.products',              'catalog.product',         'id',         true);
+SELECT app.scaffold_distributable('public.services',              'catalog.product',         'id',         true);
+SELECT app.scaffold_distributable('public.service_packages',      'catalog.service_package', 'id',         true);
+SELECT app.scaffold_distributable('public.product_variants',      'catalog.product',         'product_id', false);
+SELECT app.scaffold_distributable('public.price_table_items',     'catalog.product',         'product_id', false);
+SELECT app.scaffold_distributable('public.service_package_items', 'catalog.service_package', 'package_id', false);
+
+-- ── the case this issue was filed for ───────────────────────────────────
+-- A provider who does not log in is a Person. With this, a Person registered at
+-- no branch (unit_id NULL — the network's) can be released to the two branches
+-- that use them, and a Person registered AT a branch keeps being that branch's
+-- through has_unit. Both readings coexist, which is #225's point.
+SELECT app.scaffold_distributable('public.people', 'people.person', 'id', true);

package/migrations/140_masking_is_a_scaffold_option.sql

@@ -0,0 +1,85 @@
+-- ============================================================================
+-- 140_masking_is_a_scaffold_option.sql — field masking joins scope and
+-- distribution as something a table DECLARES (#222).
+--
+-- 124 generated `v_people` from the catalog, so the view was never hand-written
+-- and a new column is picked up by regenerating. What was missing is the rest of
+-- the scaffold contract: a declaration API shaped like the other two, and a gate
+-- that notices when a table grows a column its view has not.
+--
+--   app.scaffold_scope(table, scope, enforce)              #225
+--   app.scaffold_distributable(table, rt, key, escape)     #224
+--   app.scaffold_masked(table, context, reference)         here
+--
+-- The staleness gate is the point. A generated view is only trustworthy while
+-- something checks that it was regenerated: add `cpf` to `people`, forget to
+-- refresh, and the column is simply absent from the view — which reads as "no
+-- such field" rather than as a mistake. N16d turns that into a red build.
+--
+-- WHAT THIS DELIBERATELY DOES NOT DO: revoke SELECT on the base tables.
+--
+-- That is what turns a masked view from available into mandatory, and it is a
+-- fleet-wide change — ~92 SQL references to `public.people` (most inside
+-- SECURITY DEFINER functions and unaffected), two security_invoker views, 22
+-- client-side `.from('people')` call sites and 7 pgTAP files reading as personas.
+-- It is also no longer required for the compliance goal: the boundary may be the
+-- app's own server, decided per app (DECISIONS.md 2026-08-20). What must hold
+-- either way is the condition, not the mechanism — no path from a browser to the
+-- unmasked column — and that is an app-by-app fact this migration cannot assert.
+--
+-- Replay-safe: CREATE OR REPLACE + an idempotent re-declaration.
+-- ============================================================================
+
+CREATE OR REPLACE FUNCTION app.scaffold_masked(
+  p_table     regclass,
+  p_context   text,
+  p_reference text,
+  p_enabled   boolean DEFAULT true
+)
+RETURNS void
+LANGUAGE plpgsql SECURITY DEFINER SET search_path = ''
+AS $$
+DECLARE v_schema text; v_name text;
+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;
+
+  IF p_enabled THEN
+    PERFORM app.masked_view_refresh(p_table, p_context, p_reference);
+  ELSE
+    EXECUTE format('DROP VIEW IF EXISTS %I.%I', v_schema, 'v_' || v_name);
+    DELETE FROM app.masked_views WHERE table_schema = v_schema AND table_name = v_name;
+  END IF;
+END $$;
+REVOKE ALL ON FUNCTION app.scaffold_masked(regclass, text, text, boolean) FROM public, anon, authenticated;
+
+COMMENT ON FUNCTION app.scaffold_masked(regclass, text, text, boolean) IS
+  'Declare that a table reads through a field_rules-masked view, and generate it (#222). The third member of the scaffold''s declaration API, beside scaffold_scope and scaffold_distributable.';
+
+-- ── which masked views no longer match their table ──────────────────────
+-- Column SETS, not order: the generator emits ordinal order, and a table that
+-- gained a column mid-list would otherwise read as merely reordered.
+CREATE OR REPLACE FUNCTION app.masked_views_stale()
+RETURNS TABLE (table_name text, missing text[])
+LANGUAGE sql STABLE SECURITY DEFINER
+SET search_path = ''
+AS $$
+  SELECT m.table_name,
+         array_agg(c.column_name ORDER BY c.column_name)
+    FROM app.masked_views m
+    JOIN information_schema.columns c
+      ON c.table_schema = m.table_schema AND c.table_name = m.table_name
+   WHERE NOT EXISTS (
+           SELECT 1 FROM information_schema.columns v
+            WHERE v.table_schema = m.table_schema AND v.table_name = m.view_name
+              AND v.column_name = c.column_name)
+   GROUP BY m.table_name;
+$$;
+REVOKE ALL ON FUNCTION app.masked_views_stale() FROM public, anon;
+GRANT EXECUTE ON FUNCTION app.masked_views_stale() TO authenticated, service_role;
+
+COMMENT ON FUNCTION app.masked_views_stale() IS
+  'Masked views that have fallen behind their table (#222). A column absent from the view reads to a client as "no such field", not as a mistake — 900_verification/001 N16d makes it a red build instead.';
+
+-- ── re-declare the pilot through the API ────────────────────────────────
+SELECT app.scaffold_masked('public.people', 'person', 'person');

package/migrations/141_renamed_objects_keep_a_compat_name.sql

@@ -0,0 +1,192 @@
+-- ============================================================================
+-- 141_renamed_objects_keep_a_compat_name.sql — the old names answer again,
+-- so the rename stops being a synchronised deploy.
+--
+-- 107_core_table_prefix and 137_vendor_named_spine_objects each renamed objects
+-- and each wrote the same paragraph: NO COMPAT VIEW. Both gave one reason, and
+-- it was the same reason:
+--
+--   107 — "on the bench's force-replay pass the frozen files re-run and execute
+--          ALTER TABLE … ENABLE ROW LEVEL SECURITY … every one of which errors
+--          with 'this operation is not supported for views'."
+--   137 — "frozen migrations re-run ALTER TABLE and CREATE POLICY against the
+--          old name on a replay, and those fail on a view."
+--
+-- THAT CONSTRAINT WAS THE BENCH, NEVER PRODUCTION. A pool applies each file once
+-- and the ledger skips it forever after; only the force-replay pass re-executes
+-- a frozen file, and replay-from-zero is no longer a gate this repository pays
+-- for. With that dropped, the compat shape those files wanted is available, and
+-- it is the difference between a rename anyone can ship and a rename that needs
+-- every pool's edge functions redeployed in the same minute.
+--
+-- WHAT THE RENAME COSTS WITHOUT THIS FILE. `plg_connections` and `plg_sync_runs`
+-- are read by literal name inside SIX functions that are deployed right now
+-- (bling-sync v20 and shop-shipping-quote v3 on ecommerce, tyxter-template-sync
+-- and tyxter-number-claim on beauty, kiwify-courses-sync on school, plus the
+-- three vindi-* through _shared/vindi-shop.ts). An edge function is a deployed
+-- artifact: publishing the npm packages does not update it. So the instant 107
+-- lands, Bling sync, shipping quotes, Vindi checkout and the WhatsApp channel
+-- answer with "relation does not exist" — and nothing in the SDK reports it.
+--
+-- WHY A VIEW AND NOT A PROJECTION TABLE. 063 needed tables because the legacy
+-- tenancy names had to keep taking writes and carry FKs. Here a simple view over
+-- one table is auto-updatable in Postgres, so INSERT/UPDATE/DELETE through the
+-- old name reach the real table with no trigger; and nothing declares a foreign
+-- key to these eight.
+--
+-- security_invoker = true, deliberately. A definer view would answer with the
+-- owner's rights over a tenant_id table — exactly the leak 043 swept out of
+-- v_documents. The caller's own RLS on the base table decides, which makes the
+-- old name a pure alias and never a second, weaker door.
+--
+-- THIS FILE IS A BRIDGE, NOT A DESTINATION. Every caller moves to the real name
+-- (scripts/check-schema-code-names.mjs fails the PR that adds a new one), and
+-- when the last one has moved these views are dropped. Until then the exemption
+-- list in that script names who is still crossing.
+--
+-- Idempotent and order-independent: each object is guarded on what is actually
+-- in the catalog, so a pool that has not taken 107/137 yet is left completely
+-- alone — the old name is still the real table there, and creating a view over
+-- a name that is already a table would be wrong, not helpful.
+-- ============================================================================
+
+-- ── §1  the renamed tables ──────────────────────────────────────────────────
+DO $$
+DECLARE
+  pair   text[];
+  v_old  text;
+  v_new  text;
+  g      record;
+  v_cols text;
+BEGIN
+  FOREACH pair SLICE 1 IN ARRAY ARRAY[
+    -- 107_core_table_prefix
+    ['plg_analytics_read_models', 'analytics_read_models'],
+    ['plg_connections',           'connections'],
+    ['plg_connection_secrets',    'connection_secrets'],
+    ['plg_connector_schedules',   'connector_schedules'],
+    ['plg_entity_fields',         'entity_fields'],
+    ['plg_event_log',             'event_log'],
+    ['plg_sync_runs',             'sync_runs'],
+    ['plg_sync_schedule',         'sync_schedule'],
+    -- 137_vendor_named_spine_objects
+    ['fayz_projects',             'published_sites'],
+    ['fayz_search_sources',       'search_sources']
+  ] LOOP
+    v_old := pair[1];
+    v_new := pair[2];
+
+    -- The new name has to be there, or there is nothing to alias.
+    CONTINUE WHEN to_regclass('public.' || v_new) IS NULL;
+    -- The old name being a TABLE means this pool has not taken the rename: it is
+    -- the real thing and must stay that way. The old name being a VIEW means it
+    -- is an earlier run of THIS file — and that one may be wrong (the first cut
+    -- did `SELECT *`, which answers under the new column name). Skipping on
+    -- "exists" would make this file unable to correct itself, so a view is
+    -- dropped and rebuilt while a table is left alone.
+    CONTINUE WHEN EXISTS (
+      SELECT 1 FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace
+       WHERE n.nspname = 'public' AND c.relname = v_old AND c.relkind = 'r');
+    -- Something may read the alias by now (marketing's landing-page view reads
+    -- fayz_projects), so the dependents come off first and go back after — 143.
+    --
+    -- Guarded on the helper EXISTING, because 143 runs after this file: on a
+    -- fresh pool there is no alias yet and nothing to drop, so the helper is
+    -- never needed there. It is only ever needed on the re-application that
+    -- corrects an earlier alias, and by then 143 has long been applied.
+    IF to_regproc('app.detach_view_dependents') IS NOT NULL THEN
+      PERFORM app.detach_view_dependents('public.' || v_old);
+    END IF;
+    EXECUTE format('DROP VIEW IF EXISTS public.%I', v_old);
+
+    -- SELECT * IS NOT ENOUGH WHERE A COLUMN WAS RENAMED TOO. 137 renamed
+    -- fayz_projects.fayz_project_id to provider_site_id, so a `SELECT *` alias
+    -- answers under the old TABLE name with the new COLUMN name — and every
+    -- caller that names the column still breaks. plugin-marketing 008 found it.
+    -- A compat alias has to reproduce the old SHAPE, not just the old name.
+    SELECT string_agg(
+             CASE WHEN v_new = 'published_sites' AND a.attname = 'provider_site_id'
+                  THEN 'provider_site_id AS fayz_project_id'
+                  ELSE quote_ident(a.attname) END, ', ' ORDER BY a.attnum)
+      INTO v_cols
+      FROM pg_attribute a
+     WHERE a.attrelid = ('public.' || v_new)::regclass
+       AND a.attnum > 0 AND NOT a.attisdropped;
+
+    EXECUTE format(
+      'CREATE VIEW public.%I WITH (security_invoker = true) AS SELECT %s FROM public.%I',
+      v_old, v_cols, v_new);
+
+    -- The alias is exactly as reachable as what it points at — no more (a role
+    -- that cannot read the table cannot read it through the old name either)
+    -- and no less (the deployed callers keep the access they have today).
+    FOR g IN
+      SELECT DISTINCT grantee, privilege_type
+        FROM information_schema.role_table_grants
+       WHERE table_schema = 'public'
+         AND table_name = v_new
+         AND grantee IN ('anon', 'authenticated', 'service_role')
+    LOOP
+      EXECUTE format('GRANT %s ON public.%I TO %I', g.privilege_type, v_old, g.grantee);
+    END LOOP;
+
+    EXECUTE format(
+      'COMMENT ON VIEW public.%I IS %L',
+      v_old,
+      format('Compat alias for public.%s (141). Callers move to the real name; '
+             || 'this view is dropped when the last one has.', v_new));
+
+    IF to_regproc('app.reattach_view_dependents') IS NOT NULL THEN
+      PERFORM app.reattach_view_dependents();
+    END IF;
+
+    RAISE NOTICE '141: public.% → compat view over public.%', v_old, v_new;
+  END LOOP;
+END $$;
+
+-- ── §2  fayz_global_search() ────────────────────────────────────────────────
+-- 137 renamed the function and dropped the old name. The SDK's search engine
+-- degrades rather than breaks (it reads PGRST202 and falls back to the fan-out
+-- path), so this is a performance regression and not an outage — but the
+-- fallback is the slow path on every query until the caller is repointed, and
+-- restoring the name costs one wrapper.
+DO $$
+DECLARE
+  v_args text;
+  v_ret  text;
+BEGIN
+  -- By NAME, never by a spelled-out signature: the real one is
+  -- (text, uuid, text[], integer, integer) and a guard that hardcodes the
+  -- arguments silently misses, then CREATE FUNCTION collides with the alias it
+  -- was supposed to detect.
+  IF EXISTS (SELECT 1 FROM pg_proc p JOIN pg_namespace n ON n.oid = p.pronamespace
+              WHERE n.nspname = 'public' AND p.proname = 'fayz_global_search') THEN
+    RETURN;  -- already aliased
+  END IF;
+
+  SELECT pg_get_function_identity_arguments(p.oid), pg_get_function_result(p.oid)
+    INTO v_args, v_ret
+    FROM pg_proc p JOIN pg_namespace n ON n.oid = p.pronamespace
+   WHERE n.nspname = 'public' AND p.proname = 'global_search'
+   LIMIT 1;
+
+  IF v_args IS NULL THEN
+    RETURN;  -- pool has not taken 137
+  END IF;
+
+  EXECUTE format($f$
+    CREATE OR REPLACE FUNCTION public.fayz_global_search(%s) RETURNS %s
+    LANGUAGE sql STABLE SECURITY INVOKER SET search_path = public, pg_temp
+    AS 'SELECT * FROM public.global_search(%s)'
+  $f$, v_args, v_ret,
+       (SELECT string_agg(split_part(trim(a), ' ', 1), ', ')
+          FROM unnest(string_to_array(v_args, ',')) AS a));
+
+  EXECUTE 'REVOKE ALL ON FUNCTION public.fayz_global_search(' || v_args || ') FROM public, anon';
+  EXECUTE 'GRANT EXECUTE ON FUNCTION public.fayz_global_search(' || v_args || ') TO authenticated, service_role';
+
+  COMMENT ON FUNCTION public.fayz_global_search IS
+    'Compat alias for public.global_search() (141). Dropped when the last caller has moved.';
+
+  RAISE NOTICE '141: public.fayz_global_search() → wrapper over public.global_search()';
+END $$;

package/migrations/142_a_person_has_addresses.sql

@@ -0,0 +1,212 @@
+-- ============================================================================
+-- 142_a_person_has_addresses.sql — a person has addresses, not an address.
+--
+-- `people` carries four inline columns — address, city, state, postal_code —
+-- while `public.addresses` has been the spine's address book all along and 113
+-- already lists 'person' among the owners it accepts. So the shape was never in
+-- question; the inline copy just outlived it.
+--
+-- ONE COLUMN CANNOT HOLD WHAT THE PRODUCT ALREADY ASKS FOR. A client has a home
+-- and a delivery address; a professional has a home and the branch they bill
+-- from; a supplier has a fiscal address and a warehouse. The UI has been
+-- modelling that for a while, and every screen that does it has to keep the two
+-- sides in step by hand because the database only remembers one.
+--
+-- WHAT THIS DOES. Every non-empty inline address becomes a row in `addresses`
+-- owned by the person, marked `is_default` because it is the only one they had.
+-- Idempotent by construction: a person who already owns an address is skipped,
+-- so re-running adds nothing and a pool that was migrated by hand converges.
+--
+-- WHAT THIS DELIBERATELY DOES NOT DO. The columns stay. Dropping them is a
+-- separate wave with the readers moved first — `products.stock` is the same
+-- shape in this chain, kept as a deprecated mirror while the writers migrate.
+-- They are COMMENTed as deprecated so nothing new reaches for them, and the
+-- 900_verification posture suite is where a "no new readers" rule belongs once
+-- the readers are counted.
+--
+-- The street is NOT parsed. `address` is one free-text line and `addresses`
+-- wants street/number/complement/district; splitting "Rua X, 123 - apto 4" with
+-- a regex invents structure the row never had, and a wrong number on a delivery
+-- address costs more than an unsplit one. The line lands in `street` whole, and
+-- whoever edits it next in the UI fills the parts.
+-- ============================================================================
+
+INSERT INTO public.addresses (
+  tenant_id, owner_type, owner_id, kind, label,
+  street, city, state, postal_code, country, is_default
+)
+SELECT
+  p.tenant_id,
+  'person',
+  p.id,
+  -- THE VOCABULARY IS 113'S, NOT A NEW ONE. addresses_kind_check allows
+  -- shipping|billing|both|main|fiscal, and 113 already chose 'main' for a unit's
+  -- principal address and 'fiscal' for a company's. A person's principal address
+  -- is the same idea, so it is 'main'. The word this file used before was a
+  -- sixth name for a concept that already had one, and the ecommerce pool —
+  -- which has no trigger quietly rewriting it — refused the row outright.
+  'main',
+  'Endereço principal',
+  NULLIF(btrim(COALESCE(p.address, '')), ''),
+  NULLIF(btrim(COALESCE(p.city, '')), ''),
+  NULLIF(btrim(COALESCE(p.state, '')), ''),
+  NULLIF(btrim(COALESCE(p.postal_code, '')), ''),
+  COALESCE(NULLIF(btrim(COALESCE(p.country, '')), ''), 'BR'),
+  true
+FROM public.people p
+-- COMPLETE ONES ONLY. `addresses` requires postal_code, street, city and state,
+-- and 113 already settled why: "inventing a value to satisfy a constraint is how
+-- a fiscal address quietly becomes wrong". resto carries people with a city and
+-- nothing else — those are counted below and left where they are, readable in
+-- the deprecated columns, rather than becoming an address with a made-up CEP.
+WHERE NULLIF(btrim(COALESCE(p.address, '')), '') IS NOT NULL
+  AND NULLIF(btrim(COALESCE(p.city, '')), '') IS NOT NULL
+  AND NULLIF(btrim(COALESCE(p.state, '')), '') IS NOT NULL
+  AND NULLIF(btrim(COALESCE(p.postal_code, '')), '') IS NOT NULL
+  -- A person who already owns one has either been migrated or edited since;
+  -- either way the address book is ahead of the inline copy and wins.
+  AND NOT EXISTS (
+    SELECT 1 FROM public.addresses a
+     WHERE a.owner_type = 'person' AND a.owner_id = p.id
+  );
+
+COMMENT ON COLUMN public.people.address IS
+  'DEPRECATED (142): a person has many addresses — read public.addresses WHERE owner_type = ''person''. Kept as a mirror until the writers move.';
+COMMENT ON COLUMN public.people.city IS
+  'DEPRECATED (142): see public.addresses.';
+COMMENT ON COLUMN public.people.state IS
+  'DEPRECATED (142): see public.addresses.';
+COMMENT ON COLUMN public.people.postal_code IS
+  'DEPRECATED (142): see public.addresses.';
+
+-- The read every screen wants: a person with their addresses, newest default
+-- first, without each one re-deriving the join and the ordering.
+CREATE OR REPLACE VIEW public.v_person_addresses
+WITH (security_invoker = true) AS
+SELECT
+  a.id, a.tenant_id, a.owner_id AS person_id, p.name AS person_name,
+  a.kind, a.label, a.recipient, a.phone,
+  a.postal_code, a.street, a.number, a.complement, a.district,
+  a.city, a.state, a.country, a.is_default,
+  a.created_at, a.updated_at
+FROM public.addresses a
+JOIN public.people p ON p.id = a.owner_id
+WHERE a.owner_type = 'person';
+
+GRANT SELECT ON public.v_person_addresses TO authenticated;
+
+COMMENT ON VIEW public.v_person_addresses IS
+  'A person and every address they own (142). The default one sorts first via is_default.';
+
+-- ── the same, for the Empresa ───────────────────────────────────────────────
+-- 113 already named this: "company_legal_entities (#138) inlines seven address
+-- columns", and it already added 'company_legal_entity' to the owners
+-- `addresses` accepts. What it did not do was move the rows — it declared the
+-- address book the read model and left the write path for later. This is later.
+--
+-- A company genuinely has more than one: the fiscal address on the nota is not
+-- always where the goods ship from, and a change of accountant moves one without
+-- touching the other.
+--
+-- Unlike a person's, this address is ALREADY structured — number, complement and
+-- district are their own columns — so each part lands in its own field and
+-- nothing is guessed.
+INSERT INTO public.addresses (
+  tenant_id, owner_type, owner_id, kind, label,
+  street, number, complement, district, city, state, postal_code, country,
+  phone, is_default
+)
+SELECT
+  c.tenant_id,
+  'company_legal_entity',
+  c.id,
+  'fiscal',
+  'Endereço fiscal',
+  NULLIF(btrim(COALESCE(c.address, '')), ''),
+  NULLIF(btrim(COALESCE(c.address_number, '')), ''),
+  NULLIF(btrim(COALESCE(c.address_complement, '')), ''),
+  NULLIF(btrim(COALESCE(c.district, '')), ''),
+  NULLIF(btrim(COALESCE(c.city, '')), ''),
+  NULLIF(btrim(COALESCE(c.state, '')), ''),
+  NULLIF(btrim(COALESCE(c.postal_code, '')), ''),
+  COALESCE(NULLIF(btrim(COALESCE(c.country, '')), ''), 'BR'),
+  NULLIF(btrim(COALESCE(c.phone, '')), ''),
+  true
+FROM public.company_legal_entities c
+WHERE 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 NULLIF(btrim(COALESCE(c.postal_code, '')), '') 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
+  );
+
+COMMENT ON COLUMN public.company_legal_entities.address IS
+  'DEPRECATED (142): a company has many addresses — read public.addresses WHERE owner_type = ''company_legal_entity''. Kept as a mirror until the writers move.';
+COMMENT ON COLUMN public.company_legal_entities.address_number IS
+  'DEPRECATED (142): see public.addresses.number.';
+COMMENT ON COLUMN public.company_legal_entities.address_complement IS
+  'DEPRECATED (142): see public.addresses.complement.';
+COMMENT ON COLUMN public.company_legal_entities.district IS
+  'DEPRECATED (142): see public.addresses.district.';
+COMMENT ON COLUMN public.company_legal_entities.city IS
+  'DEPRECATED (142): see public.addresses.';
+COMMENT ON COLUMN public.company_legal_entities.state IS
+  'DEPRECATED (142): see public.addresses.';
+COMMENT ON COLUMN public.company_legal_entities.postal_code IS
+  'DEPRECATED (142): see public.addresses.';
+
+-- A unit bills through a company (app.units.company_legal_entity_id), so the
+-- branch's fiscal address is the company's — this is the join every fiscal
+-- screen needs and none of them should re-derive.
+CREATE OR REPLACE VIEW public.v_company_addresses
+WITH (security_invoker = true) AS
+SELECT
+  a.id, a.tenant_id, a.owner_id AS company_legal_entity_id,
+  c.legal_name, c.trade_name, c.document_number,
+  a.kind, a.label,
+  a.postal_code, a.street, a.number, a.complement, a.district,
+  a.city, a.state, a.country, a.phone, a.is_default,
+  a.created_at, a.updated_at
+FROM public.addresses a
+JOIN public.company_legal_entities c ON c.id = a.owner_id
+WHERE a.owner_type = 'company_legal_entity';
+
+GRANT SELECT ON public.v_company_addresses TO authenticated;
+
+COMMENT ON VIEW public.v_company_addresses IS
+  'An Empresa and every address it owns (142), with the CNPJ that identifies it.';
+
+-- What did not come across, said out loud. A partial address is not a failure to
+-- fix here — it is a person or a company whose address was never fully typed in,
+-- and the place to finish it is the screen, not a migration.
+DO $$
+DECLARE v_people integer; v_co integer;
+BEGIN
+  SELECT count(*) INTO v_people FROM public.people p
+   WHERE (COALESCE(btrim(p.address),'') <> '' OR COALESCE(btrim(p.city),'') <> ''
+       OR COALESCE(btrim(p.state),'') <> '' OR COALESCE(btrim(p.postal_code),'') <> '')
+     AND NOT EXISTS (SELECT 1 FROM public.addresses a
+                      WHERE a.owner_type = 'person' AND a.owner_id = p.id);
+  SELECT count(*) INTO v_co FROM public.company_legal_entities c
+   WHERE (COALESCE(btrim(c.address),'') <> '' OR COALESCE(btrim(c.city),'') <> '')
+     AND NOT EXISTS (SELECT 1 FROM public.addresses a
+                      WHERE a.owner_type = 'company_legal_entity' AND a.owner_id = c.id);
+  IF v_people > 0 OR v_co > 0 THEN
+    RAISE NOTICE '142: % person(s) and % company(ies) hold a PARTIAL address — left in the deprecated columns, not invented into public.addresses', v_people, v_co;
+  END IF;
+END $$;
+
+-- Pools that took an earlier version of this file. It asked for a kind the
+-- CHECK does not list, and a pool with a normalising trigger stored 'both'
+-- instead — a person's one address filed as "shipping and billing at once",
+-- which is not what anyone meant. The label is this migration's own signature,
+-- so only its own rows move.
+UPDATE public.addresses
+   SET kind = 'main'
+ WHERE owner_type = 'person' AND label = 'Endereço principal' AND kind <> 'main';
+
+UPDATE public.addresses
+   SET kind = 'fiscal'
+ WHERE owner_type = 'company_legal_entity' AND label = 'Endereço fiscal' AND kind <> 'fiscal';