@fayz-ai/db 0.11.0 → 0.13.0

package/migrations/122_migration_inventory_writers.sql

@@ -0,0 +1,245 @@
+-- 122_migration_inventory_writers.sql
+--
+-- Inventory gets its writers, and positions get told the truth. #143 / #148.
+--
+-- Every inventory row in the allowlist had `writer = NULL`. Three of them are
+-- plain reference data (measurement units, their conversions, stock locations)
+-- and one is the ledger itself.
+--
+-- POSITIONS ARE NOT MIGRATED, AND THAT IS THE POINT OF THE SLICE. In V2 a
+-- position is DERIVED: `plg_inventory_stock_movements` is the ledger, and the
+-- after-insert trigger of `007` maintains `plg_inventory_stock_positions` from
+-- it. Writing V1 positions in directly would fight the derivation and produce a
+-- balance that agrees with nothing — the first movement after cutover would
+-- recompute it away. So `stock_positions` becomes `verify_only`, exactly like
+-- `client_credits`: the extractor offers it, nothing is written, and
+-- reconciliation compares the V1 balance against the one V2 derived. That is a
+-- stronger check than copying the number would have been, because it proves the
+-- movements add up.
+--
+-- The movement writer declares itself internal. `005`'s single-writer gate
+-- refuses any write to the ledger or to positions unless
+-- `fayz.inventory_internal` is on, and it is right to: "however privileged" is
+-- the phrase in its own message. The migration is one of the internal writers —
+-- it is definer-only, fenced, and audited — so it sets the flag for its
+-- statement and lets the derivation run, rather than being exempted from it.
+--
+-- THREE MAPPINGS NAMED COLUMNS THAT DO NOT EXIST, because `005` renamed them and
+-- 091 was written against the shape before that: `stock_location_id` is
+-- `source_location_id` on movements (and stays `stock_location_id` on positions),
+-- `destination_stock_location_id` is `destination_location_id`, and V1's
+-- `movement_type` is `kind` with a closed vocabulary (in/out/transfer/adjust/
+-- reverse) that is now validated instead of trusted.
+--
+-- TWO TABLES ARE DEFERRED because their destination was never built:
+-- `plg_inventory_stock_unit_labels` and `plg_inventory_supplier_products` do not
+-- exist anywhere in the repo (#143 found this). Creating them here would mean
+-- inventing columns PRD 06 R5 names but does not specify.
+--
+-- Replay-safe: `_allow` upserts under the documented unlock; writers are
+-- CREATE OR REPLACE.
+
+ALTER TABLE migration.allowlist DROP CONSTRAINT IF EXISTS allowlist_writer_check;
+ALTER TABLE migration.allowlist ADD CONSTRAINT allowlist_writer_check
+  CHECK (writer IS NULL OR writer IN ('person', 'unit', 'category', 'product', 'order', 'invoice',
+                                      'price_table', 'price_table_item', 'package', 'package_item',
+                                      'field_rule', 'holiday', 'facet',
+                                      'fin_account', 'fin_payment_method_type', 'fin_payment_method',
+                                      'fin_card_brand', 'fin_chart_account', 'fin_cost_center',
+                                      'inv_measurement_unit', 'inv_unit_conversion', 'inv_location', 'inv_movement'));
+
+DO $unlock$
+BEGIN
+  PERFORM set_config('migration.allowlist_unlock', 'on', true);
+
+  UPDATE migration.allowlist SET writer = 'inv_measurement_unit' WHERE source_table = 'measurement_units';
+  UPDATE migration.allowlist SET writer = 'inv_unit_conversion'  WHERE source_table = 'unit_conversions';
+  UPDATE migration.allowlist SET writer = 'inv_location'         WHERE source_table = 'stock_locations';
+
+  UPDATE migration.allowlist SET writer = 'inv_movement',
+         columns = '{"uuid":"id","product_id":"product_id@products","stock_location_id":"source_location_id@stock_locations","destination_stock_location_id":"destination_location_id@stock_locations","movement_type":"kind","quantity":"quantity","unit_cost":"unit_cost","total_cost":"total_cost","batch_number":"batch_number","expiration_date":"expiration_date","document_number":"document_number","reason":"reason","notes":"notes","movement_date":"movement_date","supplier_id":"jsonb:v1_supplier_ref"}'::jsonb,
+         notes = 'PRD 06 R1: the append-only ledger. 005 renamed stock_location_id -> source_location_id and movement_type -> kind; 091 was written against the shape before that (#112).'
+   WHERE source_table = 'stock_movements';
+
+  -- positions are DERIVED from the ledger in V2; copying V1''s numbers in would
+  -- fight the derivation, so reconciliation compares them instead
+  UPDATE migration.allowlist SET writer = NULL, writer_args = '{"verify_only":true}'::jsonb,
+         notes = 'PRD 06 R1: NOT migrated. A position is derived from plg_inventory_stock_movements by 007''s trigger; writing V1 balances in directly would fight that and the first movement after cutover would recompute them away. Reconciliation compares the V1 balance against the derived one, which proves the movements add up (#112).'
+   WHERE source_table = 'stock_positions';
+
+  DELETE FROM migration.allowlist WHERE source_table IN ('stock_unit_labels', 'supplier_product_mappings',
+                                                          'discount_reasons', 'discount_users',
+                                                          'cancellation_reasons', 'cancellation_users');
+END $unlock$;
+
+INSERT INTO migration.excluded_tables (source_table, reason) VALUES
+  ('stock_unit_labels',         'Deferred: public.plg_inventory_stock_unit_labels does not exist anywhere in the repo. PRD 06 R5 names the concept without specifying it, so building the table here would mean inventing its columns (#143).'),
+  ('discount_reasons',          'Deferred: 091 pointed it at `config.orders`, a schema that never shipped. PRD 04 R7 says a discount reason is configuration of the owning plugin (orders/financial) — and no such table was built, so there is nowhere to put it. A tenant re-declares its reasons in V2 (#112).'),
+  ('discount_users',            'Deferred with discount_reasons: who may grant a discount is a permission in V2 (app.role_permissions), not a row (#112).'),
+  ('cancellation_reasons',      'Deferred: same as discount_reasons — configuration with no destination contract (#112).'),
+  ('cancellation_users',        'Deferred with cancellation_reasons: who may cancel is a permission in V2, not a row (#112).'),
+  ('supplier_product_mappings', 'Deferred: public.plg_inventory_supplier_products does not exist. Same as stock_unit_labels — named by PRD 06 R5, never specified. The supplier itself IS migrated, as a Person with the supplier role (#143).')
+ON CONFLICT (source_table) DO UPDATE SET reason = EXCLUDED.reason;
+
+CREATE OR REPLACE FUNCTION migration.upsert_inv_measurement_unit(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_existing uuid; v_created boolean := false; v_standalone boolean := migration._standalone();
+BEGIN
+  IF v_standalone THEN PERFORM migration._assert_fence(p_tenant); PERFORM set_config('migration.writer', 'on', true); END IF;
+  IF p_id IS NULL OR nullif(btrim(coalesce(p_row ->> 'name', '')), '') IS NULL THEN
+    RETURN jsonb_build_object('status', 'quarantined', 'kind', 'state', 'reason', 'a measurement unit needs an id and a name');
+  END IF;
+  SELECT tenant_id INTO v_existing FROM public.plg_inventory_measurement_units WHERE id = p_id;
+  IF v_existing IS NOT NULL AND v_existing <> p_tenant THEN
+    RETURN jsonb_build_object('status', 'quarantined', 'kind', 'tenant', 'reason', format('measurement unit %s already exists in another tenant', p_id));
+  END IF;
+  IF v_existing IS NULL THEN
+    INSERT INTO public.plg_inventory_measurement_units (id, tenant_id, name, abbreviation, is_active)
+    VALUES (p_id, p_tenant, p_row ->> 'name', p_row ->> 'abbreviation', coalesce((p_row ->> 'is_active')::boolean, true));
+    v_created := true;
+  ELSE
+    UPDATE public.plg_inventory_measurement_units SET
+      name = p_row ->> 'name',
+      abbreviation = CASE WHEN p_row ? 'abbreviation' THEN p_row ->> 'abbreviation' ELSE abbreviation END,
+      is_active = CASE WHEN p_row ? 'is_active' THEN coalesce((p_row ->> 'is_active')::boolean, true) ELSE is_active END
+    WHERE id = p_id;
+  END IF;
+  IF v_standalone THEN PERFORM migration._audit(p_tenant, 'public.plg_inventory_measurement_units', 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_inv_unit_conversion(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_existing uuid; v_created boolean := false; v_standalone boolean := migration._standalone();
+BEGIN
+  IF v_standalone THEN PERFORM migration._assert_fence(p_tenant); PERFORM set_config('migration.writer', 'on', true); END IF;
+  IF p_id IS NULL OR (p_row ->> 'from_unit_id') IS NULL OR (p_row ->> 'to_unit_id') IS NULL THEN
+    RETURN jsonb_build_object('status', 'quarantined', 'kind', 'fk', 'reason', 'a conversion needs both of its units');
+  END IF;
+  IF coalesce((p_row ->> 'factor')::numeric, 0) <= 0 THEN
+    RETURN jsonb_build_object('status', 'quarantined', 'kind', 'value', 'reason', 'a conversion factor must be > 0 — a zero factor would make every converted quantity vanish');
+  END IF;
+  SELECT tenant_id INTO v_existing FROM public.plg_inventory_unit_conversions WHERE id = p_id;
+  IF v_existing IS NOT NULL AND v_existing <> p_tenant THEN
+    RETURN jsonb_build_object('status', 'quarantined', 'kind', 'tenant', 'reason', format('conversion %s already exists in another tenant', p_id));
+  END IF;
+  IF v_existing IS NULL THEN
+    INSERT INTO public.plg_inventory_unit_conversions (id, tenant_id, from_unit_id, to_unit_id, factor, product_id)
+    VALUES (p_id, p_tenant, (p_row ->> 'from_unit_id')::uuid, (p_row ->> 'to_unit_id')::uuid,
+            (p_row ->> 'factor')::numeric, (p_row ->> 'product_id')::uuid);
+    v_created := true;
+  ELSE
+    UPDATE public.plg_inventory_unit_conversions SET
+      from_unit_id = (p_row ->> 'from_unit_id')::uuid, to_unit_id = (p_row ->> 'to_unit_id')::uuid,
+      factor = (p_row ->> 'factor')::numeric
+    WHERE id = p_id;
+  END IF;
+  IF v_standalone THEN PERFORM migration._audit(p_tenant, 'public.plg_inventory_unit_conversions', 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_inv_location(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_existing uuid; v_created boolean := false; v_standalone boolean := migration._standalone();
+BEGIN
+  IF v_standalone THEN PERFORM migration._assert_fence(p_tenant); PERFORM set_config('migration.writer', 'on', true); END IF;
+  IF p_id IS NULL OR nullif(btrim(coalesce(p_row ->> 'name', '')), '') IS NULL THEN
+    RETURN jsonb_build_object('status', 'quarantined', 'kind', 'state', 'reason', 'a stock location needs an id and a name');
+  END IF;
+  -- PRD 06 R1: a location belongs to a unit. V1 rows without one cannot be placed.
+  IF (p_row ->> 'unit_id') IS NULL THEN
+    RETURN jsonb_build_object('status', 'quarantined', 'kind', 'fk', 'reason', 'a stock location needs its unit (PRD 06 R1: unit_id is mandatory)');
+  END IF;
+  SELECT tenant_id INTO v_existing FROM public.plg_inventory_stock_locations WHERE id = p_id;
+  IF v_existing IS NOT NULL AND v_existing <> p_tenant THEN
+    RETURN jsonb_build_object('status', 'quarantined', 'kind', 'tenant', 'reason', format('stock location %s already exists in another tenant', p_id));
+  END IF;
+  IF v_existing IS NULL THEN
+    INSERT INTO public.plg_inventory_stock_locations (id, tenant_id, name, description, unit_id, is_active)
+    VALUES (p_id, p_tenant, p_row ->> 'name', p_row ->> 'description', (p_row ->> 'unit_id')::uuid,
+            coalesce((p_row ->> 'is_active')::boolean, true));
+    v_created := true;
+  ELSE
+    UPDATE public.plg_inventory_stock_locations SET
+      name = p_row ->> 'name',
+      description = CASE WHEN p_row ? 'description' THEN p_row ->> 'description' ELSE description END,
+      unit_id = (p_row ->> 'unit_id')::uuid,
+      is_active = CASE WHEN p_row ? 'is_active' THEN coalesce((p_row ->> 'is_active')::boolean, true) ELSE is_active END
+    WHERE id = p_id;
+  END IF;
+  IF v_standalone THEN PERFORM migration._audit(p_tenant, 'public.plg_inventory_stock_locations', 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_inv_movement(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_kind_raw text := nullif(btrim(lower(coalesce(p_row ->> 'kind', ''))), '');
+  v_kind text := CASE v_kind_raw
+                   WHEN 'in' THEN 'in' WHEN 'out' THEN 'out'
+                   WHEN 'transfer' THEN 'transfer' WHEN 'adjust' THEN 'adjust' WHEN 'reverse' THEN 'reverse'
+                   -- the SDK's legacy labels, and V1's pt-BR
+                   WHEN 'entry' THEN 'in' WHEN 'entrada' THEN 'in'
+                   WHEN 'exit' THEN 'out' WHEN 'saida' THEN 'out' WHEN 'saída' THEN 'out'
+                   WHEN 'loss' THEN 'out' WHEN 'perda' THEN 'out'
+                   WHEN 'adjustment' THEN 'adjust' WHEN 'ajuste' THEN 'adjust'
+                   WHEN 'transferencia' THEN 'transfer' WHEN 'transferência' THEN 'transfer'
+                 END;
+  v_meta jsonb := coalesce(p_row -> 'metadata', '{}'::jsonb);
+  v_exists boolean;
+  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 (p_row ->> 'product_id') IS NULL THEN
+    RETURN jsonb_build_object('status', 'quarantined', 'kind', 'fk', 'reason', 'a stock movement needs an id and its product');
+  END IF;
+  IF v_kind IS NULL THEN
+    RETURN jsonb_build_object('status', 'quarantined', 'kind', 'value',
+      'reason', format('unknown movement type %L (expected in|out|transfer|adjust|reverse, or a V1 label of one)', coalesce(v_kind_raw, '<null>')));
+  END IF;
+  IF coalesce((p_row ->> 'quantity')::numeric, 0) <= 0 THEN
+    RETURN jsonb_build_object('status', 'quarantined', 'kind', 'value', 'reason', 'a stock movement needs a quantity > 0 — direction is the kind, not the sign');
+  END IF;
+  IF v_kind = 'transfer' AND (p_row ->> 'destination_location_id') IS NULL THEN
+    RETURN jsonb_build_object('status', 'quarantined', 'kind', 'state', 'reason', 'a transfer needs its destination location');
+  END IF;
+
+  SELECT EXISTS (SELECT 1 FROM public.plg_inventory_stock_movements WHERE id = p_id) INTO v_exists;
+  IF v_exists THEN
+    -- the ledger is append-only: a second offer of the same movement is a replay,
+    -- not an update. Nothing to do, and saying "migrated" again is honest —
+    -- the destination already holds exactly this row.
+    RETURN jsonb_build_object('status', 'migrated', 'target_id', p_id, 'reason', 'already in the ledger (append-only)');
+  END IF;
+
+  -- 005's single-writer gate refuses any write "however privileged" unless this
+  -- is set. The migration IS one of the internal writers — definer-only, fenced
+  -- and audited — so it declares itself rather than being exempted, and the
+  -- after-insert trigger derives the position from what it writes.
+  PERFORM set_config('fayz.inventory_internal', 'on', true);
+  INSERT INTO public.plg_inventory_stock_movements
+    (id, tenant_id, product_id, kind, quantity, unit_cost, total_cost,
+     source_location_id, destination_location_id, batch_number, expiration_date,
+     document_number, reason, notes, movement_date, metadata)
+  VALUES (p_id, p_tenant, (p_row ->> 'product_id')::uuid, v_kind,
+          (p_row ->> 'quantity')::numeric,
+          (p_row ->> 'unit_cost')::numeric, (p_row ->> 'total_cost')::numeric,
+          (p_row ->> 'source_location_id')::uuid, (p_row ->> 'destination_location_id')::uuid,
+          p_row ->> 'batch_number', (p_row ->> 'expiration_date')::date,
+          p_row ->> 'document_number', p_row ->> 'reason', p_row ->> 'notes',
+          coalesce((p_row ->> 'movement_date')::timestamptz, now()), v_meta);
+  PERFORM set_config('fayz.inventory_internal', 'off', true);
+
+  IF v_standalone THEN PERFORM migration._audit(p_tenant, 'public.plg_inventory_stock_movements', p_id, jsonb_build_object('reason', 'created')); END IF;
+  RETURN jsonb_build_object('status', 'migrated', 'target_id', p_id, 'reason', 'created');
+END $$;
+
+DO $$
+DECLARE r record;
+BEGIN
+  FOR r IN SELECT p.oid::regprocedure AS sig FROM pg_proc p JOIN pg_namespace n ON n.oid = p.pronamespace
+            WHERE n.nspname = 'migration' AND p.proname LIKE 'upsert\_inv\_%' LOOP
+    EXECUTE format('REVOKE ALL ON FUNCTION %s FROM public, anon, authenticated', r.sig);
+    EXECUTE format('GRANT EXECUTE ON FUNCTION %s TO service_role', r.sig);
+  END LOOP;
+END $$;

package/migrations/123_migration_order_item_writer.sql

@@ -0,0 +1,144 @@
+-- 123_migration_order_item_writer.sql
+--
+-- The Venda's lines, and four histories that were never mapped. #140 / #148.
+--
+-- `invoice_items` is the last big row-per-row destination in the catalog/orders
+-- half. It becomes `public.order_items`, which `091` made a first-class business
+-- table (tenant_id, unit_id, composite FK to the order, execution status as a
+-- column).
+--
+-- ONE THING THE WRITER REFUSES ON PURPOSE. `091` gave the line an
+-- `execution_status` COLUMN, and 091 maps V1's `is_executed` into
+-- `jsonb:execution.is_executed`. Both cannot be the truth. The column wins — it
+-- is what `financial_cancel_paid_item` reads — so the writer sets it from the
+-- V1 flag and leaves the rest of the execution detail in metadata, which is what
+-- ADR 0009 says a promoted column means. This is the same defect as #198, caught
+-- before it shipped rather than after.
+--
+-- THREE FACETS AND FOUR HISTORIES:
+--
+--   invoice_item_adjustments / _participants / invoice_items_discounted map NO
+--   column (`'{}'` in 091), so they become facets of the line. The facet writer
+--   reports `skipped` with "the facet maps no column into the destination" —
+--   recorded, not silently dropped, and reconcile-safe.
+--
+--   invoice_cancellation_logs, invoice_item_cancellation_logs,
+--   payment_deletion_logs and payment_unlink_logs are DEFERRED. They map no
+--   column either, and unlike a facet there is no row for them to enrich: each
+--   would have to become an `audit_logs` row, and `public.audit_logs` is the
+--   actor-derived log of V2 actions — every row carries the user who did it and
+--   the entity it happened to. A V1 history row has neither in the mapping, so
+--   importing it produces audit entries with no actor and no content. They are
+--   re-admitted the day someone maps their columns.
+--
+--   bill_attachments points at `storage`: files, not rows. Recorded as a
+--   decision rather than left pending forever.
+--
+-- Replay-safe: `_allow` upserts under the documented unlock; writer is
+-- CREATE OR REPLACE.
+
+ALTER TABLE migration.allowlist DROP CONSTRAINT IF EXISTS allowlist_writer_check;
+ALTER TABLE migration.allowlist ADD CONSTRAINT allowlist_writer_check
+  CHECK (writer IS NULL OR writer IN ('person', 'unit', 'category', 'product', 'order', 'invoice',
+                                      'price_table', 'price_table_item', 'package', 'package_item',
+                                      'field_rule', 'holiday', 'facet',
+                                      'fin_account', 'fin_payment_method_type', 'fin_payment_method',
+                                      'fin_card_brand', 'fin_chart_account', 'fin_cost_center',
+                                      'inv_measurement_unit', 'inv_unit_conversion', 'inv_location', 'inv_movement',
+                                      'order_item'));
+
+DO $unlock$
+BEGIN
+  PERFORM set_config('migration.allowlist_unlock', 'on', true);
+
+  UPDATE migration.allowlist SET writer = 'order_item' WHERE source_table = 'invoice_items';
+
+  UPDATE migration.allowlist SET writer = 'facet', writer_args = jsonb_build_object('target', 'public.order_items')
+   WHERE source_table IN ('invoice_item_adjustments', 'invoice_item_participants', 'invoice_items_discounted');
+
+  UPDATE migration.allowlist SET writer = 'facet', writer_args = jsonb_build_object('target', 'public.products')
+   WHERE source_table = 'product_intermediate_info';
+
+  DELETE FROM migration.allowlist
+   WHERE source_table IN ('invoice_cancellation_logs', 'invoice_item_cancellation_logs',
+                          'payment_deletion_logs', 'payment_unlink_logs', 'bill_attachments');
+END $unlock$;
+
+INSERT INTO migration.excluded_tables (source_table, reason) VALUES
+  ('invoice_cancellation_logs',      'Deferred: 091 maps no column, and public.audit_logs is the actor-derived log of V2 actions — every row carries who did it and what it happened to. A V1 history row has neither in the mapping, so importing it produces audit entries with no actor and no content. Re-admit when the columns are mapped (#113).'),
+  ('invoice_item_cancellation_logs', 'Deferred with invoice_cancellation_logs (#113).'),
+  ('payment_deletion_logs',          'Deferred with invoice_cancellation_logs (#113).'),
+  ('payment_unlink_logs',            'Deferred with invoice_cancellation_logs (#113).'),
+  ('bill_attachments',               'Not a row destination: bill attachments are FILES. 091 pointed them at `storage`, which is object storage and not something a row writer reaches. Recorded as a decision rather than left pending forever (#113).')
+ON CONFLICT (source_table) DO UPDATE SET reason = EXCLUDED.reason;
+
+CREATE OR REPLACE FUNCTION migration.upsert_order_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_order uuid;
+  v_order_tenant uuid;
+  v_exec text;
+  v_existing uuid;
+  v_created boolean := false;
+  v_standalone boolean := migration._standalone();
+BEGIN
+  IF v_standalone THEN PERFORM migration._assert_fence(p_tenant); PERFORM set_config('migration.writer', 'on', true); END IF;
+  BEGIN
+    v_order := (p_row ->> 'order_id')::uuid;
+  EXCEPTION WHEN OTHERS THEN v_order := NULL; END;
+  IF p_id IS NULL OR v_order IS NULL THEN
+    RETURN jsonb_build_object('status', 'quarantined', 'kind', 'fk', 'reason', 'an order line needs its order — a line without a Venda is not a line');
+  END IF;
+  SELECT tenant_id INTO v_order_tenant FROM public.orders WHERE id = v_order;
+  IF v_order_tenant IS NULL THEN
+    RETURN jsonb_build_object('status', 'quarantined', 'kind', 'fk', 'reason', format('order %s is not in the destination yet', v_order));
+  END IF;
+  IF v_order_tenant <> p_tenant THEN
+    RETURN jsonb_build_object('status', 'quarantined', 'kind', 'tenant', 'reason', format('order %s belongs to another tenant', v_order));
+  END IF;
+
+  -- 081 promoted execution state to a COLUMN and 091 still maps V1's is_executed
+  -- into JSONB. Both cannot be the truth; the column is what
+  -- financial_cancel_paid_item reads, so it is set from the flag and the rest of
+  -- the execution detail stays in metadata (ADR 0009).
+  v_exec := CASE
+              WHEN (v_meta #>> '{execution,is_executed}') IN ('true', 't', '1') THEN 'executed'
+              WHEN (v_meta #>> '{cancellation,at}') IS NOT NULL THEN 'cancelled'
+              ELSE 'pending'
+            END;
+
+  SELECT tenant_id INTO v_existing FROM public.order_items WHERE id = p_id;
+  IF v_existing IS NOT NULL AND v_existing <> p_tenant THEN
+    RETURN jsonb_build_object('status', 'quarantined', 'kind', 'tenant', 'reason', format('order line %s already exists in another tenant', p_id));
+  END IF;
+  IF v_existing IS NULL THEN
+    INSERT INTO public.order_items (id, tenant_id, order_id, product_id, name, description,
+                                    quantity, unit_price, discount, total, sort_order, execution_status, metadata)
+    VALUES (p_id, p_tenant, v_order, (p_row ->> 'product_id')::uuid,
+            coalesce(nullif(btrim(coalesce(p_row ->> 'name', '')), ''), 'Item'),
+            p_row ->> 'description',
+            coalesce((p_row ->> 'quantity')::numeric, 1),
+            round(coalesce((p_row ->> 'unit_price')::numeric, 0), 2),
+            round(coalesce((p_row ->> 'discount')::numeric, 0), 2),
+            round(coalesce((p_row ->> 'total')::numeric, 0), 2),
+            coalesce((p_row ->> 'sort_order')::integer, 0), v_exec, v_meta);
+    v_created := true;
+  ELSE
+    UPDATE public.order_items SET
+      order_id = v_order,
+      product_id = CASE WHEN p_row ? 'product_id' THEN (p_row ->> 'product_id')::uuid ELSE product_id END,
+      name = CASE WHEN p_row ? 'name' THEN coalesce(nullif(btrim(p_row ->> 'name'), ''), name) ELSE name END,
+      quantity = CASE WHEN p_row ? 'quantity' THEN coalesce((p_row ->> 'quantity')::numeric, 1) ELSE quantity END,
+      unit_price = CASE WHEN p_row ? 'unit_price' THEN round(coalesce((p_row ->> 'unit_price')::numeric, 0), 2) ELSE unit_price END,
+      discount = CASE WHEN p_row ? 'discount' THEN round(coalesce((p_row ->> 'discount')::numeric, 0), 2) ELSE discount END,
+      total = CASE WHEN p_row ? 'total' THEN round(coalesce((p_row ->> 'total')::numeric, 0), 2) ELSE total END,
+      execution_status = v_exec,
+      metadata = migration._merge_meta(metadata, v_meta)
+    WHERE id = p_id;
+  END IF;
+  IF v_standalone THEN PERFORM migration._audit(p_tenant, 'public.order_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 $$;
+REVOKE ALL ON FUNCTION migration.upsert_order_item(uuid, uuid, jsonb, jsonb) FROM public, anon, authenticated;
+GRANT EXECUTE ON FUNCTION migration.upsert_order_item(uuid, uuid, jsonb, jsonb) TO service_role;

package/migrations/124_migration_ledger_writers.sql

@@ -0,0 +1,170 @@
+-- 124_migration_ledger_writers.sql
+--
+-- V1's money events reach the two-leg ledger. #142 / #148.
+--
+-- `financial_movements` is the largest financial table in a V1 pool and had no
+-- writer, so every one of a tenant's money events landed `pending`.
+--
+-- LEGS. V2's ledger is two-legged and `plg_financial_movements_legs_check`
+-- refuses a money event without both. A V1 movement has neither — it predates
+-- the model — so the writer resolves them the same way the in-place backfill
+-- does, through `plg_financial_legacy_legs`: the money holder from the bank
+-- account or the cash session, the counter-leg from the invoice's direction, and
+-- `legacy` / `legacy_holder` when neither is knowable. Reusing that function
+-- rather than reimplementing it means a migrated pool and an upgraded pool end
+-- up with the same postings, which is the property that makes the two paths
+-- comparable at all.
+--
+-- Bills and commissions are obligation MIRRORS, not money events: the helper
+-- says so and they are inserted without legs, which is what `legs_check`'s own
+-- first clause allows.
+--
+-- TWO TABLES ARE DEFERRED, both because writing them would mean guessing at
+-- money:
+--
+--   payment_allocations. V1 links a payment movement to a BILL MOVEMENT; V2
+--   links a payment movement to an INSTALLMENT (`plg_financial_invoice_
+--   installments`), and those are different objects — the installment is created
+--   by `financial_create_invoice`, not by the movement import. 101's mapping
+--   papers over that by pointing `bill_movement_id` at
+--   `installment_id@financial_movements`, which would write a movement's id into
+--   a column that means an installment. An allocation is what says WHICH debt a
+--   payment settled; getting it wrong silently mis-states every balance built on
+--   it, and there is no way to verify the mapping without the real V1 rows. It
+--   is re-admitted with #141's invoice split, which is what creates the
+--   installments an allocation can point at.
+--
+--   cc_receiving_fee_configs. 091 maps NO column (`'{}'`), and a fee config is
+--   brand x installment range x rate per receiving account — four things, none
+--   of them mapped. A wrong fee rate silently mis-states every card receivable.
+--
+-- Replay-safe: `_allow` upserts under the documented unlock; writers are
+-- CREATE OR REPLACE; the movement writer is idempotent by id and the ledger is
+-- append-only, so a second offer is a replay.
+
+ALTER TABLE migration.allowlist DROP CONSTRAINT IF EXISTS allowlist_writer_check;
+ALTER TABLE migration.allowlist ADD CONSTRAINT allowlist_writer_check
+  CHECK (writer IS NULL OR writer IN ('person', 'unit', 'category', 'product', 'order', 'invoice',
+                                      'price_table', 'price_table_item', 'package', 'package_item',
+                                      'field_rule', 'holiday', 'facet',
+                                      'fin_account', 'fin_payment_method_type', 'fin_payment_method',
+                                      'fin_card_brand', 'fin_chart_account', 'fin_cost_center',
+                                      'inv_measurement_unit', 'inv_unit_conversion', 'inv_location', 'inv_movement',
+                                      'order_item', 'fin_movement'));
+
+DO $unlock$
+BEGIN
+  PERFORM set_config('migration.allowlist_unlock', 'on', true);
+  -- `direction` was NOT MAPPED by 091, and it is the column that says whether
+  -- money came in or went out. Without it every movement would have to guess.
+  UPDATE migration.allowlist SET writer = 'fin_movement',
+         columns = columns || '{"direction":"direction"}'::jsonb
+   WHERE source_table = 'financial_movements';
+  DELETE FROM migration.allowlist WHERE source_table IN ('payment_allocations', 'cc_receiving_fee_configs',
+                                                          'cash_register_sessions', 'cash_session_reviewers');
+END $unlock$;
+
+INSERT INTO migration.excluded_tables (source_table, reason) VALUES
+  ('payment_allocations',      'Deferred: V1 links a payment movement to a BILL MOVEMENT; V2 links it to an INSTALLMENT, and those are different objects — the installment is created by financial_create_invoice, not by the movement import. 091 papered over that by pointing bill_movement_id at installment_id@financial_movements, which writes a movement id into a column meaning an installment. An allocation says WHICH debt a payment settled; getting it wrong silently mis-states every balance built on it. Re-admit with #141''s invoice split, which creates the installments an allocation can point at (#114).'),
+  ('cash_register_sessions',   'Deferred: a V2 cash session is ATTRIBUTED — user_id is NOT NULL and only one may be open per user and unit, because the session is the accountability record for a drawer. 091 carries V1''s opener only as an opaque `v1_opened_by` reference with no mapping to a V2 auth user, so every migrated session would have to be attributed to somebody who did not open it. Re-admit when V1 users are mapped to V2 logins (#114).'),
+  ('cash_session_reviewers',   'Deferred with cash_register_sessions: a reviewer of a session that is not migrated has nothing to review (#114).'),
+  ('cc_receiving_fee_configs', 'Deferred: 091 maps no column at all, and a fee config is brand x installment range x rate per receiving account — four things, none of them mapped. A wrong fee rate silently mis-states every card receivable (#114).')
+ON CONFLICT (source_table) DO UPDATE SET reason = EXCLUDED.reason;
+
+CREATE OR REPLACE FUNCTION migration.upsert_fin_movement(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_kind_raw text := nullif(btrim(lower(coalesce(p_row ->> 'movement_kind', ''))), '');
+  v_kind text := CASE v_kind_raw
+                   WHEN 'bill' THEN 'bill' WHEN 'payment' THEN 'payment'
+                   WHEN 'transfer' THEN 'transfer' WHEN 'commission' THEN 'commission'
+                   -- V1's vocabulary
+                   WHEN 'conta' THEN 'bill' WHEN 'titulo' THEN 'bill' WHEN 'título' THEN 'bill'
+                   WHEN 'pagamento' THEN 'payment' WHEN 'recebimento' THEN 'payment'
+                   WHEN 'transferencia' THEN 'transfer' WHEN 'transferência' THEN 'transfer'
+                   WHEN 'comissao' THEN 'commission' WHEN 'comissão' THEN 'commission'
+                 END;
+  v_dir text := nullif(btrim(lower(coalesce(p_row ->> 'direction', ''))), '');
+  v_amount numeric := round(coalesce((p_row ->> 'amount')::numeric, 0), 2);
+  v_legs record;
+  v_debit uuid := (p_row ->> 'debit_account_id')::uuid;
+  v_credit uuid := (p_row ->> 'credit_account_id')::uuid;
+  v_exists boolean;
+  v_standalone boolean := migration._standalone();
+BEGIN
+  IF v_standalone THEN PERFORM migration._assert_fence(p_tenant); PERFORM set_config('migration.writer', 'on', true); END IF;
+  IF p_id IS NULL THEN
+    RETURN jsonb_build_object('status', 'quarantined', 'kind', 'state', 'reason', 'a movement needs an id');
+  END IF;
+  IF v_kind IS NULL THEN
+    RETURN jsonb_build_object('status', 'quarantined', 'kind', 'value',
+      'reason', format('unknown movement kind %L (expected bill|payment|transfer|commission, or a V1 label of one)', coalesce(v_kind_raw, '<null>')));
+  END IF;
+  IF v_dir IS NOT NULL AND v_dir NOT IN ('debit', 'credit') THEN
+    RETURN jsonb_build_object('status', 'quarantined', 'kind', 'value', 'reason', format('unknown direction %L (expected debit|credit)', v_dir));
+  END IF;
+  -- A V1 pool that does not carry the column still knows the direction, through
+  -- the invoice the movement settles: a receivable is money in, a payable money
+  -- out. That is a derivation, not a guess. When there is no invoice either,
+  -- refuse — "which way did this money go" is not something to default.
+  IF v_dir IS NULL AND (p_row ->> 'financial_invoice_id') IS NOT NULL THEN
+    SELECT CASE t.direction WHEN 'receivable' THEN 'credit' WHEN 'payable' THEN 'debit' END INTO v_dir
+      FROM public.plg_financial_invoices t WHERE t.id = (p_row ->> 'financial_invoice_id')::uuid;
+  END IF;
+  IF v_dir IS NULL THEN
+    RETURN jsonb_build_object('status', 'quarantined', 'kind', 'state',
+      'reason', 'the movement carries no direction and settles no invoice — which way the money went cannot be derived, and must not be defaulted');
+  END IF;
+  IF v_amount < 0 THEN
+    RETURN jsonb_build_object('status', 'quarantined', 'kind', 'value', 'reason', 'a money event cannot carry a negative amount — direction is the direction, not the sign');
+  END IF;
+
+  SELECT EXISTS (SELECT 1 FROM public.plg_financial_movements WHERE id = p_id) INTO v_exists;
+  IF v_exists THEN
+    -- append-only: a second offer of the same money event is a replay
+    RETURN jsonb_build_object('status', 'migrated', 'target_id', p_id, 'reason', 'already in the ledger (append-only)');
+  END IF;
+
+  -- Legs, resolved exactly as the in-place backfill resolves them, so a migrated
+  -- pool and an upgraded pool end up with the same postings.
+  IF v_debit IS NULL OR v_credit IS NULL THEN
+    SELECT * INTO v_legs FROM public.plg_financial_legacy_legs(
+      p_tenant, v_kind, v_dir, (p_row ->> 'bank_account_id')::uuid, (p_row ->> 'cash_session_id')::uuid,
+      (p_row ->> 'financial_invoice_id')::uuid, v_meta);
+    IF v_legs.o_mirror THEN
+      -- an obligation mirror, not a money event: legs_check allows it legless
+      v_meta := v_meta || jsonb_build_object('legacy_mirror', true);
+      v_debit := NULL; v_credit := NULL;
+    ELSE
+      v_debit := coalesce(v_debit, v_legs.o_debit);
+      v_credit := coalesce(v_credit, v_legs.o_credit);
+    END IF;
+  END IF;
+
+  INSERT INTO public.plg_financial_movements
+    (id, tenant_id, financial_invoice_id, direction, movement_kind, amount, paid_amount, status,
+     due_date, payment_date, installment_number, notes, metadata, debit_account_id, credit_account_id)
+  VALUES (p_id, p_tenant, (p_row ->> 'financial_invoice_id')::uuid, v_dir, v_kind, v_amount,
+          round(coalesce((p_row ->> 'paid_amount')::numeric, 0), 2),
+          coalesce(p_row ->> 'status', 'pending'),
+          -- due_date is NOT NULL on the ledger. A V1 payment has no due date —
+          -- it is not an obligation — so it takes the date the money moved, which
+          -- is the only date that means anything for it. A bill keeps its own.
+          coalesce((p_row ->> 'due_date')::date, (p_row ->> 'paid_at')::date, current_date),
+          (p_row ->> 'paid_at')::date,
+          (p_row ->> 'installment_number')::integer, p_row ->> 'notes', v_meta, v_debit, v_credit);
+
+  IF v_standalone THEN PERFORM migration._audit(p_tenant, 'public.plg_financial_movements', p_id, jsonb_build_object('reason', 'created')); END IF;
+  RETURN jsonb_build_object('status', 'migrated', 'target_id', p_id, 'reason', 'created');
+END $$;
+
+DO $$
+DECLARE r record;
+BEGIN
+  FOR r IN SELECT p.oid::regprocedure AS sig FROM pg_proc p JOIN pg_namespace n ON n.oid = p.pronamespace
+            WHERE n.nspname = 'migration' AND p.proname = 'upsert_fin_movement' 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 $$;