feat(pax8): add safe ordering and billing-truth workflow

apps/api/migrations/2026-07-13-a-pax8-ordering.sql

@@ -0,0 +1,141 @@
+-- Pax8 ordering: staged intent ledger.
+-- Pax8 has no idempotency key and no order status field, so THIS TABLE — not
+-- Pax8 — is the record of whether money was spent. A line is claimed
+-- (submit_state='in_flight') in a committed txn before the HTTP call.
+-- Partner-axis (RLS shape 3), matching the five existing pax8_* tables:
+-- org_id is a linkage column, never the tenancy axis.
+
+CREATE TABLE IF NOT EXISTS pax8_orders (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  integration_id UUID NOT NULL,
+  partner_id UUID NOT NULL REFERENCES partners(id),
+  org_id UUID NOT NULL,
+  pax8_company_id VARCHAR(64),
+  status VARCHAR(20) NOT NULL DEFAULT 'draft',
+  source VARCHAR(10) NOT NULL DEFAULT 'direct',
+  source_quote_id UUID REFERENCES quotes(id) ON DELETE SET NULL,
+  dedupe_key VARCHAR(120) NOT NULL,
+  pax8_order_id VARCHAR(64),
+  error TEXT,
+  created_by UUID REFERENCES users(id),
+  submitted_by UUID REFERENCES users(id),
+  submitted_at TIMESTAMPTZ,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  CONSTRAINT pax8_orders_status_chk CHECK (status IN (
+    'draft','awaiting_details','ready','submitting','completed','partially_failed','failed','cancelled')),
+  CONSTRAINT pax8_orders_source_chk CHECK (source IN ('direct','quote')),
+  CONSTRAINT pax8_orders_integration_partner_fkey
+    FOREIGN KEY (integration_id, partner_id)
+    REFERENCES pax8_integrations(id, partner_id) ON DELETE CASCADE,
+  CONSTRAINT pax8_orders_org_partner_fkey
+    FOREIGN KEY (org_id, partner_id)
+    REFERENCES organizations(id, partner_id) ON DELETE CASCADE
+);
+
+-- The idempotency guard. A concurrent submit of the same intent loses this race.
+CREATE UNIQUE INDEX IF NOT EXISTS pax8_orders_dedupe_key_uq
+  ON pax8_orders(partner_id, dedupe_key);
+CREATE INDEX IF NOT EXISTS pax8_orders_partner_idx ON pax8_orders(partner_id);
+CREATE INDEX IF NOT EXISTS pax8_orders_org_idx ON pax8_orders(org_id);
+CREATE INDEX IF NOT EXISTS pax8_orders_status_idx ON pax8_orders(partner_id, status);
+CREATE INDEX IF NOT EXISTS pax8_orders_quote_idx ON pax8_orders(source_quote_id);
+-- Target for the order_lines composite FK. Including org_id prevents an order
+-- line from pointing at another customer under the same MSP partner.
+CREATE UNIQUE INDEX IF NOT EXISTS pax8_orders_id_partner_org_idx
+  ON pax8_orders(id, partner_id, org_id);
+
+CREATE TABLE IF NOT EXISTS pax8_order_lines (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  order_id UUID NOT NULL,
+  partner_id UUID NOT NULL REFERENCES partners(id),
+  org_id UUID NOT NULL,
+  action VARCHAR(20) NOT NULL,
+  submit_state VARCHAR(20) NOT NULL DEFAULT 'pending',
+  pax8_product_id VARCHAR(64),
+  catalog_item_id UUID,
+  billing_term VARCHAR(20),
+  commitment_term_id VARCHAR(64),
+  quantity NUMERIC(12,2),
+  provisioning_details JSONB NOT NULL DEFAULT '[]'::jsonb,
+  target_subscription_id VARCHAR(64),
+  cancel_date DATE,
+  result_subscription_id VARCHAR(64),
+  contract_line_id UUID,
+  source_quote_line_id UUID,
+  error TEXT,
+  sort_order INTEGER NOT NULL DEFAULT 0,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  CONSTRAINT pax8_order_lines_action_chk CHECK (action IN (
+    'new_subscription','change_quantity','cancel')),
+  CONSTRAINT pax8_order_lines_state_chk CHECK (submit_state IN (
+    'pending','in_flight','succeeded','failed','needs_reconcile')),
+  CONSTRAINT pax8_order_lines_billing_term_chk CHECK (
+    billing_term IS NULL OR billing_term IN (
+      'Monthly','Annual','2-Year','3-Year','One-Time','Trial','Activation')),
+  -- Each action carries a different payload; enforce the shape rather than
+  -- trusting the service layer. A cancel with a quantity is a bug, not data.
+  CONSTRAINT pax8_order_lines_action_payload_chk CHECK (
+    (action = 'new_subscription'
+       AND pax8_product_id IS NOT NULL AND billing_term IS NOT NULL
+       AND quantity IS NOT NULL AND quantity > 0 AND target_subscription_id IS NULL)
+    OR (action = 'change_quantity'
+       AND target_subscription_id IS NOT NULL AND quantity IS NOT NULL AND quantity >= 0)
+    OR (action = 'cancel'
+       AND target_subscription_id IS NOT NULL AND quantity IS NULL)
+  ),
+  CONSTRAINT pax8_order_lines_order_partner_org_fkey
+    FOREIGN KEY (order_id, partner_id, org_id)
+    REFERENCES pax8_orders(id, partner_id, org_id) ON DELETE CASCADE,
+  CONSTRAINT pax8_order_lines_org_partner_fkey
+    FOREIGN KEY (org_id, partner_id)
+    REFERENCES organizations(id, partner_id) ON DELETE CASCADE,
+  CONSTRAINT pax8_order_lines_catalog_item_partner_fkey
+    FOREIGN KEY (catalog_item_id, partner_id)
+    REFERENCES catalog_items(id, partner_id) ON DELETE SET NULL (catalog_item_id),
+  CONSTRAINT pax8_order_lines_contract_line_org_fkey
+    FOREIGN KEY (contract_line_id, org_id)
+    REFERENCES contract_lines(id, org_id) ON DELETE SET NULL (contract_line_id)
+);
+
+CREATE INDEX IF NOT EXISTS pax8_order_lines_order_idx ON pax8_order_lines(order_id);
+CREATE INDEX IF NOT EXISTS pax8_order_lines_partner_idx ON pax8_order_lines(partner_id);
+CREATE INDEX IF NOT EXISTS pax8_order_lines_org_idx ON pax8_order_lines(org_id);
+CREATE INDEX IF NOT EXISTS pax8_order_lines_contract_line_idx ON pax8_order_lines(contract_line_id);
+-- Finds lines stranded mid-flight (crash between claim and result).
+CREATE INDEX IF NOT EXISTS pax8_order_lines_inflight_idx
+  ON pax8_order_lines(submit_state) WHERE submit_state IN ('in_flight','needs_reconcile');
+
+ALTER TABLE pax8_orders ENABLE ROW LEVEL SECURITY;
+ALTER TABLE pax8_orders FORCE ROW LEVEL SECURITY;
+ALTER TABLE pax8_order_lines ENABLE ROW LEVEL SECURITY;
+ALTER TABLE pax8_order_lines FORCE ROW LEVEL SECURITY;
+
+DROP POLICY IF EXISTS breeze_partner_isolation_select ON pax8_orders;
+DROP POLICY IF EXISTS breeze_partner_isolation_insert ON pax8_orders;
+DROP POLICY IF EXISTS breeze_partner_isolation_update ON pax8_orders;
+DROP POLICY IF EXISTS breeze_partner_isolation_delete ON pax8_orders;
+CREATE POLICY breeze_partner_isolation_select ON pax8_orders
+  FOR SELECT USING (public.breeze_has_partner_access(partner_id));
+CREATE POLICY breeze_partner_isolation_insert ON pax8_orders
+  FOR INSERT WITH CHECK (public.breeze_has_partner_access(partner_id));
+CREATE POLICY breeze_partner_isolation_update ON pax8_orders
+  FOR UPDATE USING (public.breeze_has_partner_access(partner_id))
+  WITH CHECK (public.breeze_has_partner_access(partner_id));
+CREATE POLICY breeze_partner_isolation_delete ON pax8_orders
+  FOR DELETE USING (public.breeze_has_partner_access(partner_id));
+
+DROP POLICY IF EXISTS breeze_partner_isolation_select ON pax8_order_lines;
+DROP POLICY IF EXISTS breeze_partner_isolation_insert ON pax8_order_lines;
+DROP POLICY IF EXISTS breeze_partner_isolation_update ON pax8_order_lines;
+DROP POLICY IF EXISTS breeze_partner_isolation_delete ON pax8_order_lines;
+CREATE POLICY breeze_partner_isolation_select ON pax8_order_lines
+  FOR SELECT USING (public.breeze_has_partner_access(partner_id));
+CREATE POLICY breeze_partner_isolation_insert ON pax8_order_lines
+  FOR INSERT WITH CHECK (public.breeze_has_partner_access(partner_id));
+CREATE POLICY breeze_partner_isolation_update ON pax8_order_lines
+  FOR UPDATE USING (public.breeze_has_partner_access(partner_id))
+  WITH CHECK (public.breeze_has_partner_access(partner_id));
+CREATE POLICY breeze_partner_isolation_delete ON pax8_order_lines
+  FOR DELETE USING (public.breeze_has_partner_access(partner_id));

apps/api/migrations/2026-07-14-pax8-direct-draft-uniqueness.sql

@@ -0,0 +1,41 @@
+-- Keep at most one mutable direct Pax8 order per partner/customer. Quote
+-- staging intentionally remains outside this index so multiple accepted quotes
+-- may wait for fulfillment details at the same time.
+DO $$
+DECLARE
+  cleaned_count INTEGER;
+BEGIN
+  WITH ranked AS (
+    SELECT
+      id,
+      ROW_NUMBER() OVER (
+        PARTITION BY partner_id, org_id
+        ORDER BY created_at, id
+      ) AS ordinal
+    FROM pax8_orders
+    WHERE source = 'direct'
+      AND status IN ('draft', 'awaiting_details')
+  ), cleaned AS (
+    UPDATE pax8_orders AS duplicate
+    SET
+      status = 'cancelled',
+      error = CONCAT_WS(
+        E'\n',
+        NULLIF(duplicate.error, ''),
+        'Cancelled duplicate mutable direct draft during 2026-07-14 uniqueness migration.'
+      ),
+      updated_at = NOW()
+    FROM ranked
+    WHERE duplicate.id = ranked.id
+      AND ranked.ordinal > 1
+    RETURNING duplicate.id
+  )
+  SELECT COUNT(*) INTO cleaned_count FROM cleaned;
+
+  RAISE WARNING 'cancelled % duplicate mutable direct Pax8 draft order(s)', cleaned_count;
+END $$;
+
+CREATE UNIQUE INDEX IF NOT EXISTS pax8_orders_one_mutable_direct_per_org_uq
+  ON pax8_orders(partner_id, org_id)
+  WHERE source = 'direct'
+    AND status IN ('draft', 'awaiting_details');

apps/api/migrations/2026-07-14-pax8-snapshot-quantity-evidence.sql

@@ -0,0 +1,5 @@
+-- Pax8 omits Subscription.quantity in some responses. The client normalizes
+-- that absence to 0.00 for wire compatibility; retain the evidence bit so a
+-- synthesized zero can never be mistaken for real billing drift.
+ALTER TABLE pax8_subscription_snapshots
+  ADD COLUMN IF NOT EXISTS quantity_known boolean NOT NULL DEFAULT false;

apps/api/migrations/2026-07-16-pax8-order-line-authorized-baseline.sql

@@ -0,0 +1,22 @@
+-- Preserve the Breeze manual quantity against which a direct Pax8 quantity
+-- change was authorized. Submit must match this value under lock before any
+-- vendor write so a later billing edit cannot invert increase/decrease policy.
+
+ALTER TABLE pax8_order_lines
+  ADD COLUMN IF NOT EXISTS authorized_baseline_quantity NUMERIC(12,2);
+
+DO $$
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1
+    FROM pg_constraint
+    WHERE conname = 'pax8_order_lines_authorized_baseline_chk'
+      AND conrelid = 'pax8_order_lines'::regclass
+  ) THEN
+    ALTER TABLE pax8_order_lines
+      ADD CONSTRAINT pax8_order_lines_authorized_baseline_chk CHECK (
+        authorized_baseline_quantity IS NULL
+        OR (action = 'change_quantity' AND authorized_baseline_quantity >= 0)
+      );
+  END IF;
+END $$;