@fayz-ai/db 0.11.0 → 0.13.0

package/migrations/118_migration_catalog_writers.sql

@@ -0,0 +1,450 @@
+-- 118_migration_catalog_writers.sql
+--
+-- The catalog half of the extractor stops landing `pending`. #139 / #148.
+--
+-- 091 allowlisted the V1 catalog tables and pointed them at a `catalog.*` schema
+-- that never shipped -- the tables live in `public` -- and no writer existed for
+-- any of them, so every price table, package and package item landed `pending`
+-- with no data and `reconcile()` could never reach `pending = 0`.
+--
+-- Two of the mappings also named destination columns that do not exist, which is
+-- the quiet half of the problem: `map_row` builds whatever the mapping says and
+-- the writer reads the keys it knows, so a mapped column with no home is dropped
+-- in silence. That is the shape of #198 (`duration_minutes` mapped to JSONB while
+-- the column was real) and of the `counterparty_id` drop in `upsert_invoice`.
+-- They are corrected here rather than left for a writer to ignore:
+--
+--   price_tables.type          -> metadata (public.price_tables has no `kind`)
+--   package_items.item_type,
+--   unit_price, package_price  -> metadata (public.service_package_items carries
+--                                 quantity and sort_order; the money lives on the
+--                                 package and on the order, not on the line)
+--
+-- ONE TABLE IS DEFERRED RATHER THAN MAPPED. V1 `price_variations` is not a
+-- product variant -- it is a price RULE (`variation_type`, `value_type`, `value`,
+-- `first_appointment_only`). V2 resolves price through price_tables +
+-- price_table_items and has no rule engine, so `public.product_variants`
+-- (product_id NOT NULL, name, sku, attributes) is not the same concept and
+-- writing one into the other would invent data. It goes to excluded_tables with
+-- the reason, like recurring_bills (#188): a decision recorded, not a silent gap.
+-- Same for `package_settings` and `package_unit_shares`, which are tenant
+-- configuration and a revenue-share facet with no destination contract.
+--
+-- Replay-safe: `_allow` upserts under the freeze's documented unlock, the
+-- exclusions are an upsert, the writers are CREATE OR REPLACE.
+
+-- ── the writer vocabulary, widened (never narrowed) ──────────────────────
+-- 090 constrains allowlist.writer to the six names that existed then. Each new
+-- destination writer widens it; the CHECK is the registry, which is what makes
+-- the dynamic dispatch below safe.
+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'));
+
+DO $unlock$
+BEGIN
+  PERFORM set_config('migration.allowlist_unlock', 'on', true);
+
+  PERFORM migration._allow('price_tables', 'public.price_tables', 'catalog', 'price_table', '{}', '{}',
+    '{"uuid":"id","description":"name","type":"jsonb:catalog.v1_type","valid_from":"valid_from","valid_until":"valid_to","unit_ids":"jsonb:scope.v1_unit_refs","category_ids":"jsonb:scope.v1_category_refs","professional_ids":"jsonb:scope.v1_professional_refs","partnership_ids":"jsonb:scope.v1_partnership_refs","active":"is_active"}',
+    'PRD 04 R3. `type` has no column on public.price_tables — it rides in metadata rather than being dropped by a writer that does not know it (#108).');
+
+  PERFORM migration._allow('price_table_items', 'public.price_table_items', 'catalog', 'price_table_item', '{}', '{}',
+    '{"uuid":"id","price_table_id":"price_table_id@price_tables","service_id":"product_id@services","table_price":"price"}',
+    'PRD 04 R3.');
+
+  PERFORM migration._allow('service_packages', 'public.service_packages', 'catalog', 'package', '{}', '{}',
+    '{"uuid":"id","name":"name","description":"description","total_price":"price","status":"jsonb:v1_status","validity_days":"validity_days","validity_months":"jsonb:validity.months","validity_enabled":"jsonb:validity.enabled","replaces_uuid":"jsonb:v1_replaces","replaced_by_uuid":"jsonb:v1_replaced_by","active":"is_active"}',
+    'PRD 04 R4: packages facet.');
+
+  PERFORM migration._allow('service_package_items', 'public.service_package_items', 'catalog', 'package_item', '{}', '{}',
+    '{"uuid":"id","package_id":"package_id@service_packages","service_id":"product_id@services","product_id":"product_id@products","item_type":"jsonb:v1_item_type","quantity":"quantity","unit_price":"jsonb:v1_unit_price","package_price":"jsonb:v1_package_price"}',
+    'PRD 04 R4. The money columns ride in metadata: a package line carries quantity, the price is on the package and on the order (#108).');
+
+  DELETE FROM migration.allowlist WHERE source_table IN ('price_variations', 'package_settings', 'package_unit_shares');
+END $unlock$;
+
+INSERT INTO migration.excluded_tables (source_table, reason) VALUES
+  ('price_variations',    'Deferred: not a product variant. V1 price_variations is a price RULE (variation_type / value_type / value / first_appointment_only); V2 resolves price through price_tables + price_table_items and has no rule engine, so public.product_variants (product_id NOT NULL, name, sku, attributes) is a different concept. Re-admit in the wave that ships a pricing-rule contract (#108).'),
+  ('package_settings',    'Deferred: tenant-level package configuration with no destination contract. Settings are set by a human in V2, not migrated (#108).'),
+  ('package_unit_shares', 'Deferred: package revenue share by unit — a facet PRD 04 R4 names but does not specify. No destination contract (#108).')
+ON CONFLICT (source_table) DO UPDATE SET reason = EXCLUDED.reason;
+
+
+
+CREATE OR REPLACE FUNCTION migration.upsert_price_table(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_meta jsonb := coalesce(p_row -> 'metadata', '{}'::jsonb);
+  v_existing_tenant 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 nullif(btrim(coalesce(p_row ->> 'name', '')), '') IS NULL THEN
+    RETURN jsonb_build_object('status', 'quarantined', 'kind', 'state', 'reason', 'price table needs an id and name');
+  END IF;
+  SELECT tenant_id INTO v_existing_tenant FROM public.price_tables WHERE id = p_id;
+  IF v_existing_tenant IS NOT NULL AND v_existing_tenant <> p_tenant THEN
+    RETURN jsonb_build_object('status', 'quarantined', 'kind', 'tenant', 'reason', format('%s already exists in another tenant', p_id));
+  END IF;
+  IF v_existing_tenant IS NULL THEN
+    INSERT INTO public.price_tables (id, tenant_id, name, description, channel, currency, valid_from, valid_to, is_default, priority, is_active, metadata)
+    VALUES (p_id, p_tenant,
+            p_row ->> 'name',
+            p_row ->> 'description',
+            p_row ->> 'channel',
+            coalesce(p_row ->> 'currency', 'BRL'),
+            (p_row ->> 'valid_from')::date,
+            (p_row ->> 'valid_to')::date,
+            coalesce((p_row ->> 'is_default')::boolean, false),
+            coalesce((p_row ->> 'priority')::integer, 0),
+            coalesce((p_row ->> 'is_active')::boolean, true),
+            v_meta);
+    v_created := true;
+  ELSE
+    UPDATE public.price_tables SET
+      name = CASE WHEN p_row ? 'name' THEN p_row ->> 'name' ELSE name END,
+      description = CASE WHEN p_row ? 'description' THEN p_row ->> 'description' ELSE description END,
+      channel = CASE WHEN p_row ? 'channel' THEN p_row ->> 'channel' ELSE channel END,
+      currency = CASE WHEN p_row ? 'currency' THEN coalesce(p_row ->> 'currency', 'BRL') ELSE currency END,
+      valid_from = CASE WHEN p_row ? 'valid_from' THEN (p_row ->> 'valid_from')::date ELSE valid_from END,
+      valid_to = CASE WHEN p_row ? 'valid_to' THEN (p_row ->> 'valid_to')::date ELSE valid_to END,
+      is_default = CASE WHEN p_row ? 'is_default' THEN coalesce((p_row ->> 'is_default')::boolean, false) ELSE is_default END,
+      priority = CASE WHEN p_row ? 'priority' THEN coalesce((p_row ->> 'priority')::integer, 0) ELSE priority END,
+      is_active = CASE WHEN p_row ? 'is_active' THEN coalesce((p_row ->> 'is_active')::boolean, true) ELSE is_active END,
+      metadata = migration._merge_meta(metadata, v_meta)
+    WHERE id = p_id;
+  END IF;
+  IF v_standalone THEN PERFORM migration._audit(p_tenant, 'public.price_tables', 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_price_table_item(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_meta jsonb := coalesce(p_row -> 'metadata', '{}'::jsonb);
+  v_existing_tenant 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', 'price table item needs an id and nothing else');
+  END IF;
+  -- a price line without its table or its product is a broken reference, not a
+  -- row with holes: the FK would refuse it anyway, and a quarantine says why.
+  IF (p_row ->> 'price_table_id') IS NULL OR (p_row ->> 'product_id') IS NULL THEN
+    RETURN jsonb_build_object('status', 'quarantined', 'kind', 'fk', 'reason', 'a price line needs both its price table and its product');
+  END IF;
+  IF coalesce((p_row ->> 'price')::numeric, -1) < 0 THEN
+    RETURN jsonb_build_object('status', 'quarantined', 'kind', 'value', 'reason', 'a price line needs a price >= 0');
+  END IF;
+  SELECT tenant_id INTO v_existing_tenant FROM public.price_table_items WHERE id = p_id;
+  IF v_existing_tenant IS NOT NULL AND v_existing_tenant <> p_tenant THEN
+    RETURN jsonb_build_object('status', 'quarantined', 'kind', 'tenant', 'reason', format('%s already exists in another tenant', p_id));
+  END IF;
+  IF v_existing_tenant IS NULL THEN
+    INSERT INTO public.price_table_items (id, tenant_id, price_table_id, product_id, price, min_qty, metadata)
+    VALUES (p_id, p_tenant,
+            (p_row ->> 'price_table_id')::uuid,
+            (p_row ->> 'product_id')::uuid,
+            round(coalesce((p_row ->> 'price')::numeric, 0), 2),
+            coalesce((p_row ->> 'min_qty')::numeric, 1),
+            v_meta);
+    v_created := true;
+  ELSE
+    UPDATE public.price_table_items SET
+      price_table_id = CASE WHEN p_row ? 'price_table_id' THEN (p_row ->> 'price_table_id')::uuid ELSE price_table_id END,
+      product_id = CASE WHEN p_row ? 'product_id' THEN (p_row ->> 'product_id')::uuid ELSE product_id END,
+      price = CASE WHEN p_row ? 'price' THEN round(coalesce((p_row ->> 'price')::numeric, 0), 2) ELSE price END,
+      min_qty = CASE WHEN p_row ? 'min_qty' THEN coalesce((p_row ->> 'min_qty')::numeric, 1) ELSE min_qty END,
+      metadata = migration._merge_meta(metadata, v_meta)
+    WHERE id = p_id;
+  END IF;
+  IF v_standalone THEN PERFORM migration._audit(p_tenant, 'public.price_table_items', 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_package(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_meta jsonb := coalesce(p_row -> 'metadata', '{}'::jsonb);
+  v_existing_tenant 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 nullif(btrim(coalesce(p_row ->> 'name', '')), '') IS NULL THEN
+    RETURN jsonb_build_object('status', 'quarantined', 'kind', 'state', 'reason', 'package needs an id and name');
+  END IF;
+  SELECT tenant_id INTO v_existing_tenant FROM public.service_packages WHERE id = p_id;
+  IF v_existing_tenant IS NOT NULL AND v_existing_tenant <> p_tenant THEN
+    RETURN jsonb_build_object('status', 'quarantined', 'kind', 'tenant', 'reason', format('%s already exists in another tenant', p_id));
+  END IF;
+  IF v_existing_tenant IS NULL THEN
+    INSERT INTO public.service_packages (id, tenant_id, name, description, price, currency, sessions_total, validity_days, is_active, metadata)
+    VALUES (p_id, p_tenant,
+            p_row ->> 'name',
+            p_row ->> 'description',
+            round(coalesce((p_row ->> 'price')::numeric, 0), 2),
+            coalesce(p_row ->> 'currency', 'BRL'),
+            (p_row ->> 'sessions_total')::integer,
+            (p_row ->> 'validity_days')::integer,
+            coalesce((p_row ->> 'is_active')::boolean, true),
+            v_meta);
+    v_created := true;
+  ELSE
+    UPDATE public.service_packages SET
+      name = CASE WHEN p_row ? 'name' THEN p_row ->> 'name' ELSE name END,
+      description = CASE WHEN p_row ? 'description' THEN p_row ->> 'description' ELSE description END,
+      price = CASE WHEN p_row ? 'price' THEN round(coalesce((p_row ->> 'price')::numeric, 0), 2) ELSE price END,
+      currency = CASE WHEN p_row ? 'currency' THEN coalesce(p_row ->> 'currency', 'BRL') ELSE currency END,
+      sessions_total = CASE WHEN p_row ? 'sessions_total' THEN (p_row ->> 'sessions_total')::integer ELSE sessions_total END,
+      validity_days = CASE WHEN p_row ? 'validity_days' THEN (p_row ->> 'validity_days')::integer ELSE validity_days END,
+      is_active = CASE WHEN p_row ? 'is_active' THEN coalesce((p_row ->> 'is_active')::boolean, true) ELSE is_active END,
+      metadata = migration._merge_meta(metadata, v_meta)
+    WHERE id = p_id;
+  END IF;
+  IF v_standalone THEN PERFORM migration._audit(p_tenant, 'public.service_packages', 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_package_item(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_meta jsonb := coalesce(p_row -> 'metadata', '{}'::jsonb);
+  v_existing_tenant 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', 'package item needs an id and nothing else');
+  END IF;
+  IF (p_row ->> 'package_id') IS NULL OR (p_row ->> 'product_id') IS NULL THEN
+    RETURN jsonb_build_object('status', 'quarantined', 'kind', 'fk', 'reason', 'a package line needs both its package and its product');
+  END IF;
+  SELECT tenant_id INTO v_existing_tenant FROM public.service_package_items WHERE id = p_id;
+  IF v_existing_tenant IS NOT NULL AND v_existing_tenant <> p_tenant THEN
+    RETURN jsonb_build_object('status', 'quarantined', 'kind', 'tenant', 'reason', format('%s already exists in another tenant', p_id));
+  END IF;
+  IF v_existing_tenant IS NULL THEN
+    INSERT INTO public.service_package_items (id, tenant_id, package_id, product_id, quantity, sort_order, metadata)
+    VALUES (p_id, p_tenant,
+            (p_row ->> 'package_id')::uuid,
+            (p_row ->> 'product_id')::uuid,
+            coalesce((p_row ->> 'quantity')::numeric, 1),
+            coalesce((p_row ->> 'sort_order')::integer, 0),
+            v_meta);
+    v_created := true;
+  ELSE
+    UPDATE public.service_package_items SET
+      package_id = CASE WHEN p_row ? 'package_id' THEN (p_row ->> 'package_id')::uuid ELSE package_id END,
+      product_id = CASE WHEN p_row ? 'product_id' THEN (p_row ->> 'product_id')::uuid ELSE product_id END,
+      quantity = CASE WHEN p_row ? 'quantity' THEN coalesce((p_row ->> 'quantity')::numeric, 1) ELSE quantity END,
+      sort_order = CASE WHEN p_row ? 'sort_order' THEN coalesce((p_row ->> 'sort_order')::integer, 0) ELSE sort_order END,
+      metadata = migration._merge_meta(metadata, v_meta)
+    WHERE id = p_id;
+  END IF;
+  IF v_standalone THEN PERFORM migration._audit(p_tenant, 'public.service_package_items', 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 $$;
+
+-- The writers are the migration role's, like every other one in this schema.
+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_price_table', 'upsert_price_table_item', 'upsert_package', 'upsert_package_item') 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 $$;
+
+-- ── dispatch by name, so a new writer is an _allow call and a function ───
+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
+    -- Dispatch by name rather than by a CASE arm per writer. The CASE meant every
+    -- new destination writer had to re-emit this whole function, and a row naming
+    -- a writer the CASE did not list fell through to NULL — silently, which is
+    -- the failure mode this schema exists to prevent. The allowlist's CHECK is
+    -- the vocabulary, `migration` is definer-only, and the name is verified to
+    -- exist before it is called, so an allowlist row naming a writer nobody built
+    -- quarantines with that sentence instead of vanishing.
+    IF to_regprocedure(format('migration.upsert_%s(uuid,uuid,jsonb,jsonb)', a.writer)) IS NULL THEN
+      RETURN migration._quarantine(l.id, p_batch, 'state',
+        format('the allowlist names writer %L for %s, and migration.upsert_%s does not exist', a.writer, p_source_table, a.writer),
+        p_row, v_target_table);
+    END IF;
+    -- %I on the whole identifier, not on the suffix: format('upsert_%I', 'order')
+    -- yields upsert_"order", which is not the function's name.
+    EXECUTE format('SELECT migration.%I($1, $2, $3, $4)', 'upsert_' || a.writer)
+      INTO v_res USING b.tenant_id, v_target_id, v_row, a.writer_args;
+  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 $$;