@fayz-ai/db 0.11.0 → 0.13.0

package/migrations/099_access_grants.sql

@@ -0,0 +1,293 @@
+-- ============================================================================
+-- 099_access_grants.sql — Delegated access grants: a signed grant becomes a
+-- scoped session (PRD 07 R6 / #144; RN-PLT-03; US-PUB-DEV-04).
+--
+-- Someone with config.manage delegates a slice of her tenant — one unit, one
+-- role, for a bounded time — to whoever holds a secret. The holder redeems the
+-- secret and receives a scoped session. THE QR CODE IS ONE DELIVERY CHANNEL FOR
+-- THAT SECRET, not the concept: the same grant works as a link in a message, a
+-- totem at the door, or a code read out loud. V1 called the tables
+-- qr_access_configs / qr_access_grants / qr_access_sessions and V2 mirrored the
+-- name at first; nothing in the schema was ever QR-specific, so the delivery
+-- method is now a column (`channel`) and the objects carry the concept's name.
+--
+--   grant    access_grants: (tenant, unit, role, label, channel, expiry,
+--            max_uses, session_ttl) + secret_hash. The delivery payload carries
+--            {grant_id, signature}; the signature is the grant's secret, shown
+--            ONCE at creation (access_grant_create) and stored only as sha256 —
+--            a read of the table cannot forge a grant. Verification is a hash
+--            compare.
+--   redeem   access_grant_redeem(grant_id, signature) — anon-callable (the phone
+--            has no session yet): grant active, not expired, not exhausted,
+--            signature right, burst counter under the threshold → uses+1, a
+--            session row (token_hash, tenant, unit, role, channel, expires_at =
+--            now()+session_ttl) and the opaque session_token returned once.
+--            Every refusal is 42501 with one message: the caller learns nothing
+--            about which check failed.
+--   claims   access_session_claims(session_token) — service-only (the edge
+--            function that mints the JWT): single use (used_at), expired/used/
+--            revoked → 42501. What it returns is what goes into the token:
+--            tenant_id, unit_id, role_key, expires_at.
+--   revoke   access_session_revoke(session_id) — config.manage in the tenant.
+--
+-- Rate limit and anti-abuse live at the edge (IP/device throttling before the
+-- RPC is reached). The database backstop is access_grant_attempts: a per-grant
+-- sliding-minute counter that refuses more than N redemptions of one grant per
+-- minute (a leaked grant cannot be mass-redeemed). Note the limit of a database
+-- counter: a refused call rolls back its own increment, so only redemptions
+-- that commit are counted — brute force of a 244-bit secret is not the threat,
+-- replay of a real grant is, and that is what max_uses, expiry and the burst
+-- counter bound.
+--
+-- Idempotent and replay-safe.
+-- ============================================================================
+
+-- ── grants ──────────────────────────────────────────────────────────────
+CREATE TABLE IF NOT EXISTS public.access_grants (
+  id           uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  tenant_id    uuid NOT NULL REFERENCES public.tenants(id) ON DELETE CASCADE,
+  unit_id      uuid NOT NULL,
+  role_id      uuid NOT NULL,
+  label        text NOT NULL CHECK (btrim(label) <> ''),
+  channel      text NOT NULL DEFAULT 'qr' CHECK (channel IN ('qr', 'link', 'totem', 'manual')),
+  secret_hash  text NOT NULL,                              -- sha256 hex of the secret the delivery payload carries
+  expires_at   timestamptz NOT NULL,
+  max_uses     integer CHECK (max_uses IS NULL OR max_uses > 0),
+  uses         integer NOT NULL DEFAULT 0,
+  session_ttl  interval NOT NULL DEFAULT interval '12 hours',
+  is_active    boolean NOT NULL DEFAULT true,
+  created_by   uuid,
+  created_at   timestamptz NOT NULL DEFAULT now(),
+  updated_at   timestamptz NOT NULL DEFAULT now(),
+  CONSTRAINT access_grants_unit_fk FOREIGN KEY (tenant_id, unit_id) REFERENCES app.units(tenant_id, id) ON DELETE CASCADE,
+  CONSTRAINT access_grants_role_fk FOREIGN KEY (tenant_id, role_id) REFERENCES app.roles(tenant_id, id) ON DELETE CASCADE
+);
+CREATE INDEX IF NOT EXISTS access_grants_active ON public.access_grants (tenant_id, unit_id) WHERE is_active;
+
+SELECT app.scaffold_table('public.access_grants', 'config.access_grant', 'config', false, 'enforce');
+REVOKE ALL ON public.access_grants FROM anon;
+GRANT SELECT, INSERT, UPDATE, DELETE ON public.access_grants TO authenticated;
+GRANT ALL ON public.access_grants TO service_role;
+
+CREATE OR REPLACE FUNCTION public.access_grants_stamp_actor()
+RETURNS trigger LANGUAGE plpgsql SECURITY DEFINER SET search_path = '' AS $$
+BEGIN
+  IF TG_OP = 'INSERT' THEN NEW.created_by := coalesce(auth.uid(), NEW.created_by); END IF;
+  RETURN NEW;
+END $$;
+REVOKE ALL ON FUNCTION public.access_grants_stamp_actor() FROM public, anon, authenticated;
+DROP TRIGGER IF EXISTS access_grants_actor ON public.access_grants;
+CREATE TRIGGER access_grants_actor BEFORE INSERT ON public.access_grants
+  FOR EACH ROW EXECUTE FUNCTION public.access_grants_stamp_actor();
+
+-- ── sessions (no API role reads or writes this table) ───────────────────
+CREATE TABLE IF NOT EXISTS public.access_sessions (
+  id          uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  tenant_id   uuid NOT NULL REFERENCES public.tenants(id) ON DELETE CASCADE,
+  unit_id     uuid NOT NULL,
+  role_id     uuid NOT NULL,
+  grant_id    uuid NOT NULL REFERENCES public.access_grants(id) ON DELETE CASCADE,
+  channel     text NOT NULL DEFAULT 'qr' CHECK (channel IN ('qr', 'link', 'totem', 'manual')),
+  token_hash  text NOT NULL UNIQUE,                        -- sha256 hex of the opaque session token
+  expires_at  timestamptz NOT NULL,
+  used_at     timestamptz,                                 -- claims consumed (single use)
+  revoked_at  timestamptz,
+  created_at  timestamptz NOT NULL DEFAULT now()
+);
+CREATE INDEX IF NOT EXISTS access_sessions_grant ON public.access_sessions (grant_id, created_at DESC);
+ALTER TABLE public.access_sessions ENABLE ROW LEVEL SECURITY;
+REVOKE ALL ON public.access_sessions FROM anon, authenticated;
+GRANT ALL ON public.access_sessions TO service_role;
+DROP POLICY IF EXISTS tenant_isolation_select ON public.access_sessions;
+DROP POLICY IF EXISTS tenant_isolation_insert ON public.access_sessions;
+DROP POLICY IF EXISTS tenant_isolation_update ON public.access_sessions;
+DROP POLICY IF EXISTS tenant_isolation_delete ON public.access_sessions;
+
+-- ── burst counter (internal) ────────────────────────────────────────────
+CREATE TABLE IF NOT EXISTS public.access_grant_attempts (
+  grant_id uuid NOT NULL REFERENCES public.access_grants(id) ON DELETE CASCADE,
+  minute   timestamptz NOT NULL,
+  count    integer NOT NULL DEFAULT 0,
+  PRIMARY KEY (grant_id, minute)
+);
+ALTER TABLE public.access_grant_attempts ENABLE ROW LEVEL SECURITY;
+REVOKE ALL ON public.access_grant_attempts FROM anon, authenticated;
+GRANT ALL ON public.access_grant_attempts TO service_role;
+
+-- ── helpers ─────────────────────────────────────────────────────────────
+CREATE OR REPLACE FUNCTION app.sha256_hex(p_text text)
+RETURNS text LANGUAGE sql IMMUTABLE SET search_path = '' AS $$
+  SELECT encode(sha256(convert_to(p_text, 'UTF8')), 'hex');
+$$;
+GRANT EXECUTE ON FUNCTION app.sha256_hex(text) TO authenticated, service_role;
+
+-- 244 bits from two v4 uuids — core Postgres, no extension schema to guess.
+CREATE OR REPLACE FUNCTION app.opaque_token()
+RETURNS text LANGUAGE sql VOLATILE SET search_path = '' AS $$
+  SELECT replace(gen_random_uuid()::text, '-', '') || replace(gen_random_uuid()::text, '-', '');
+$$;
+REVOKE ALL ON FUNCTION app.opaque_token() FROM public, anon, authenticated;
+
+-- ── create a grant: the secret is returned once ─────────────────────────
+CREATE OR REPLACE FUNCTION public.access_grant_create(
+  p_unit       uuid,
+  p_role_key   text,
+  p_label      text,
+  p_expires_at timestamptz DEFAULT NULL,
+  p_max_uses   integer DEFAULT NULL,
+  p_session_ttl interval DEFAULT NULL,
+  p_channel    text DEFAULT 'qr'
+)
+RETURNS jsonb
+LANGUAGE plpgsql SECURITY DEFINER SET search_path = ''
+AS $$
+DECLARE
+  v_tenant  uuid := app.current_tenant_id();
+  v_role    uuid;
+  v_secret  text;
+  v_id      uuid;
+  v_channel text := coalesce(nullif(btrim(p_channel), ''), 'qr');
+BEGIN
+  IF v_tenant IS NULL OR auth.uid() IS NULL THEN
+    RAISE EXCEPTION 'access_grant_create: no tenant in scope' USING ERRCODE = '42501';
+  END IF;
+  IF NOT app.has_unit(p_unit) OR NOT app.has_permission('config.manage', p_unit) THEN
+    RAISE EXCEPTION 'access_grant_create: config.manage in the unit is required' USING ERRCODE = '42501';
+  END IF;
+  IF v_channel NOT IN ('qr', 'link', 'totem', 'manual') THEN
+    RAISE EXCEPTION 'access_grant_create: unknown channel %', v_channel USING ERRCODE = '22023';
+  END IF;
+  SELECT r.id INTO v_role FROM app.roles r WHERE r.tenant_id = v_tenant AND r.key = p_role_key;
+  IF v_role IS NULL THEN
+    RAISE EXCEPTION 'access_grant_create: unknown role %', p_role_key USING ERRCODE = '22023';
+  END IF;
+  v_secret := app.opaque_token();
+  INSERT INTO public.access_grants (tenant_id, unit_id, role_id, label, channel, secret_hash, expires_at, max_uses, session_ttl, created_by)
+  VALUES (v_tenant, p_unit, v_role, p_label, v_channel, app.sha256_hex(v_secret),
+          coalesce(p_expires_at, now() + interval '365 days'), p_max_uses,
+          coalesce(p_session_ttl, interval '12 hours'), auth.uid())
+  RETURNING id INTO v_id;
+  RETURN jsonb_build_object('grant_id', v_id, 'signature', v_secret, 'channel', v_channel,
+                            'grant_payload', jsonb_build_object('g', v_id, 's', v_secret));
+END $$;
+REVOKE ALL ON FUNCTION public.access_grant_create(uuid, text, text, timestamptz, integer, interval, text) FROM public, anon;
+GRANT EXECUTE ON FUNCTION public.access_grant_create(uuid, text, text, timestamptz, integer, interval, text) TO authenticated, service_role;
+
+-- ── redeem: signed grant → session token (anon-callable) ────────────────
+CREATE OR REPLACE FUNCTION public.access_grant_redeem(p_grant_id uuid, p_signature text)
+RETURNS jsonb
+LANGUAGE plpgsql SECURITY DEFINER SET search_path = ''
+AS $$
+DECLARE
+  c_limit  constant integer := 10;             -- redemptions per grant per sliding minute
+  v_grant  public.access_grants%ROWTYPE;
+  v_role   text;
+  v_token  text;
+  v_sid    uuid;
+  v_exp    timestamptz;
+  v_burst  integer;
+BEGIN
+  IF p_grant_id IS NULL OR nullif(btrim(coalesce(p_signature, '')), '') IS NULL THEN
+    RAISE EXCEPTION 'access_grant: invalid or expired grant' USING ERRCODE = '42501';
+  END IF;
+
+  -- burst backstop: count this call, refuse over the threshold
+  DELETE FROM public.access_grant_attempts a WHERE a.grant_id = p_grant_id AND a.minute < now() - interval '1 hour';
+  INSERT INTO public.access_grant_attempts (grant_id, minute, count)
+  SELECT p_grant_id, date_trunc('minute', now()), 1
+   WHERE EXISTS (SELECT 1 FROM public.access_grants g WHERE g.id = p_grant_id)
+  ON CONFLICT (grant_id, minute) DO UPDATE SET count = public.access_grant_attempts.count + 1;
+  SELECT coalesce(sum(a.count), 0) INTO v_burst FROM public.access_grant_attempts a
+   WHERE a.grant_id = p_grant_id AND a.minute >= date_trunc('minute', now()) - interval '1 minute';
+  IF v_burst > c_limit THEN
+    RAISE EXCEPTION 'access_grant: too many attempts' USING ERRCODE = '42501';
+  END IF;
+
+  SELECT g.* INTO v_grant FROM public.access_grants g WHERE g.id = p_grant_id FOR UPDATE;
+  IF v_grant.id IS NULL
+     OR NOT v_grant.is_active
+     OR v_grant.expires_at <= now()
+     OR (v_grant.max_uses IS NOT NULL AND v_grant.uses >= v_grant.max_uses)
+     OR v_grant.secret_hash <> app.sha256_hex(p_signature)
+     OR NOT EXISTS (SELECT 1 FROM app.units u WHERE u.tenant_id = v_grant.tenant_id AND u.id = v_grant.unit_id AND u.active) THEN
+    RAISE EXCEPTION 'access_grant: invalid or expired grant' USING ERRCODE = '42501';
+  END IF;
+
+  SELECT r.key INTO v_role FROM app.roles r WHERE r.tenant_id = v_grant.tenant_id AND r.id = v_grant.role_id;
+  v_token := app.opaque_token();
+  v_exp := now() + v_grant.session_ttl;
+  INSERT INTO public.access_sessions (tenant_id, unit_id, role_id, grant_id, channel, token_hash, expires_at)
+  VALUES (v_grant.tenant_id, v_grant.unit_id, v_grant.role_id, v_grant.id, v_grant.channel, app.sha256_hex(v_token), v_exp)
+  RETURNING id INTO v_sid;
+  UPDATE public.access_grants SET uses = uses + 1 WHERE id = v_grant.id;
+
+  RETURN jsonb_build_object(
+    'session_id', v_sid,
+    'session_token', v_token,
+    'tenant_id', v_grant.tenant_id,
+    'unit_id', v_grant.unit_id,
+    'role_key', v_role,
+    'channel', v_grant.channel,
+    'expires_at', v_exp
+  );
+END $$;
+REVOKE ALL ON FUNCTION public.access_grant_redeem(uuid, text) FROM public;
+GRANT EXECUTE ON FUNCTION public.access_grant_redeem(uuid, text) TO anon, authenticated, service_role;
+
+-- ── claims: session token → what the JWT carries (service-only, single use) ─
+CREATE OR REPLACE FUNCTION public.access_session_claims(p_session_token text)
+RETURNS jsonb
+LANGUAGE plpgsql SECURITY DEFINER SET search_path = ''
+AS $$
+DECLARE
+  v_s    public.access_sessions%ROWTYPE;
+  v_role text;
+BEGIN
+  IF auth.uid() IS NOT NULL THEN
+    RAISE EXCEPTION 'access_session_claims: service-only' USING ERRCODE = '42501';
+  END IF;
+  SELECT s.* INTO v_s FROM public.access_sessions s
+   WHERE s.token_hash = app.sha256_hex(coalesce(p_session_token, '')) FOR UPDATE;
+  IF v_s.id IS NULL OR v_s.used_at IS NOT NULL OR v_s.revoked_at IS NOT NULL OR v_s.expires_at <= now() THEN
+    RAISE EXCEPTION 'access_grant: invalid, used or expired session' USING ERRCODE = '42501';
+  END IF;
+  UPDATE public.access_sessions SET used_at = now() WHERE id = v_s.id;
+  SELECT r.key INTO v_role FROM app.roles r WHERE r.tenant_id = v_s.tenant_id AND r.id = v_s.role_id;
+  RETURN jsonb_build_object(
+    'session_id', v_s.id,
+    'tenant_id', v_s.tenant_id,
+    'unit_id', v_s.unit_id,
+    'role_id', v_s.role_id,
+    'role_key', v_role,
+    'expires_at', v_s.expires_at
+  );
+END $$;
+REVOKE ALL ON FUNCTION public.access_session_claims(text) FROM public, anon, authenticated;
+GRANT EXECUTE ON FUNCTION public.access_session_claims(text) TO service_role;
+
+-- ── revoke a session (config.manage in the tenant) ──────────────────────
+CREATE OR REPLACE FUNCTION public.access_session_revoke(p_session_id uuid)
+RETURNS boolean
+LANGUAGE plpgsql SECURITY DEFINER SET search_path = ''
+AS $$
+DECLARE v_tenant uuid := app.current_tenant_id(); v_n integer;
+BEGIN
+  IF v_tenant IS NULL OR NOT app.has_permission('config.manage') THEN
+    RAISE EXCEPTION 'access_session_revoke: config.manage is required' USING ERRCODE = '42501';
+  END IF;
+  UPDATE public.access_sessions SET revoked_at = coalesce(revoked_at, now())
+   WHERE id = p_session_id AND tenant_id = v_tenant;
+  GET DIAGNOSTICS v_n = ROW_COUNT;
+  RETURN v_n > 0;
+END $$;
+REVOKE ALL ON FUNCTION public.access_session_revoke(uuid) FROM public, anon;
+GRANT EXECUTE ON FUNCTION public.access_session_revoke(uuid) TO authenticated, service_role;
+
+COMMENT ON TABLE public.access_grants IS
+  'Delegated access grants (PRD 07 R6): unit + role + expiry + max_uses; the delivery payload carries {grant_id, signature} and only sha256(signature) is stored. '
+  'channel records HOW the secret was delivered (qr | link | totem | manual) — the QR code is one channel, not the concept. '
+  'access_grant_redeem() turns a valid grant into a single-use session; access_session_claims() (service-only) exchanges it for JWT claims.';
+COMMENT ON TABLE public.access_sessions IS
+  'Opaque scoped sessions minted by a grant (token_hash only), stamped with the channel that minted them. Single use (used_at), expiry, revocation. No API role reads this table.';
+COMMENT ON COLUMN public.access_grants.channel IS
+  'Delivery channel of the grant secret: qr (printed/scanned code), link (message or e-mail), totem (kiosk at the unit), manual (read out loud / typed).';

package/migrations/100_migration_schema.sql

@@ -0,0 +1,217 @@
+-- ============================================================================
+-- 100_migration_schema.sql — the private migration ledger (PRD 10 / #148,
+-- ADR 0007, ADR 0008): schema `migration`, its tables, and the grant posture.
+--
+-- The SDK is the DESTINATION of the V1→V2 extraction. The extractor tool runs
+-- elsewhere with a service credential; what lives here is what the destination
+-- guarantees: one ledger row per source row, quarantine instead of silent
+-- correction, a frozen table allowlist, a per-tenant write fence with a
+-- kill switch that dies at the point of no return, and reconciliation reports.
+--
+-- Nothing in this schema is API surface: PostgREST does not expose it, anon and
+-- authenticated hold no privilege on it, every table has RLS enabled with no
+-- policy for an API role. Only service_role (the extractor) and the migration
+-- owner (the RPCs, SECURITY DEFINER) touch it.
+--
+-- Idempotent and replay-safe: IF NOT EXISTS / guarded DO blocks throughout.
+-- ============================================================================
+
+CREATE SCHEMA IF NOT EXISTS migration;
+REVOKE ALL ON SCHEMA migration FROM public, anon, authenticated;
+GRANT USAGE ON SCHEMA migration TO service_role;
+ALTER DEFAULT PRIVILEGES IN SCHEMA migration REVOKE ALL ON TABLES FROM public, anon, authenticated;
+ALTER DEFAULT PRIVILEGES IN SCHEMA migration REVOKE ALL ON SEQUENCES FROM public, anon, authenticated;
+ALTER DEFAULT PRIVILEGES IN SCHEMA migration REVOKE EXECUTE ON FUNCTIONS FROM public, anon, authenticated;
+
+-- ─────────────────────────────── batches ───────────────────────────────
+-- One extractor run (or resume) for one tenant from one source project.
+-- source_tenant_id is the V1 licence id: a source row whose tenant_id disagrees
+-- with it is quarantined ('tenant'), never re-homed.
+CREATE TABLE IF NOT EXISTS migration.batches (
+  id               uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  tenant_id        uuid NOT NULL REFERENCES public.tenants(id) ON DELETE CASCADE,
+  source_project   text NOT NULL,
+  source_tenant_id bigint,
+  status           text NOT NULL DEFAULT 'running' CHECK (status IN ('running', 'paused', 'done', 'failed')),
+  started_at       timestamptz NOT NULL DEFAULT now(),
+  finished_at      timestamptz,
+  cursor_from      text,
+  cursor_to        text,
+  counts           jsonb NOT NULL DEFAULT '{}'::jsonb,
+  notes            text,
+  created_at       timestamptz NOT NULL DEFAULT now(),
+  updated_at       timestamptz NOT NULL DEFAULT now()
+);
+CREATE INDEX IF NOT EXISTS batches_tenant_idx ON migration.batches (tenant_id, started_at DESC);
+
+-- ─────────────────────────────── ledger ────────────────────────────────
+-- One row per source row ever offered to the destination. status is the state
+-- of the SOURCE ROW at the destination, not the outcome of the last call:
+-- a no-op replay leaves the row untouched (that is what makes the batch
+-- checksum stable). `financial` holds the financial values as written, so the
+-- reconciliation can compare Σ(ledger) with Σ(destination) to the cent.
+CREATE TABLE IF NOT EXISTS migration.ledger (
+  id                bigserial PRIMARY KEY,
+  source_project    text NOT NULL,
+  source_table      text NOT NULL,
+  source_numeric_id bigint,
+  source_uuid       uuid,
+  tenant_id         uuid NOT NULL REFERENCES public.tenants(id) ON DELETE CASCADE,
+  target_table      text,
+  target_id         uuid,
+  checksum          text NOT NULL,
+  cursor            text,
+  batch_id          uuid REFERENCES migration.batches(id) ON DELETE SET NULL,
+  status            text NOT NULL DEFAULT 'pending' CHECK (status IN ('pending', 'migrated', 'quarantined', 'skipped')),
+  reason            text,
+  financial         jsonb,
+  created_at        timestamptz NOT NULL DEFAULT now(),
+  updated_at        timestamptz NOT NULL DEFAULT now(),
+  CHECK (source_numeric_id IS NOT NULL OR source_uuid IS NOT NULL)
+);
+-- One row per (source row, destination table): a split (Venda → invoice) is a
+-- second row for the same source row; a merge is N source rows on one target_id.
+CREATE UNIQUE INDEX IF NOT EXISTS ledger_source_numeric_key
+  ON migration.ledger (source_project, source_table, source_numeric_id, coalesce(target_table, '')) WHERE source_numeric_id IS NOT NULL;
+CREATE UNIQUE INDEX IF NOT EXISTS ledger_source_uuid_key
+  ON migration.ledger (source_project, source_table, source_uuid, coalesce(target_table, '')) WHERE source_numeric_id IS NULL AND source_uuid IS NOT NULL;
+CREATE INDEX IF NOT EXISTS ledger_source_uuid_idx ON migration.ledger (source_project, source_table, source_uuid) WHERE source_uuid IS NOT NULL;
+CREATE INDEX IF NOT EXISTS ledger_batch_idx ON migration.ledger (batch_id);
+CREATE INDEX IF NOT EXISTS ledger_tenant_target_idx ON migration.ledger (tenant_id, target_table, target_id);
+CREATE INDEX IF NOT EXISTS ledger_tenant_source_idx ON migration.ledger (tenant_id, source_project, source_table);
+
+-- ─────────────────────────────── quarantine ────────────────────────────
+-- A source row the destination refused to write, with WHY and the payload the
+-- extractor sent (the source row — synthetic in every fixture, real only on
+-- the rehearsal/production destination, never in Git). A human resolves it
+-- (resolved_at + resolution) and the extractor re-offers the row.
+CREATE TABLE IF NOT EXISTS migration.quarantine (
+  id          bigserial PRIMARY KEY,
+  ledger_id   bigint NOT NULL REFERENCES migration.ledger(id) ON DELETE CASCADE,
+  tenant_id   uuid NOT NULL REFERENCES public.tenants(id) ON DELETE CASCADE,
+  batch_id    uuid REFERENCES migration.batches(id) ON DELETE SET NULL,
+  kind        text NOT NULL CHECK (kind IN ('tenant', 'identity', 'state', 'value', 'fk', 'allowlist')),
+  reason      text NOT NULL,
+  payload     jsonb,
+  created_at  timestamptz NOT NULL DEFAULT now(),
+  resolved_at timestamptz,
+  resolution  text
+);
+CREATE INDEX IF NOT EXISTS quarantine_ledger_idx ON migration.quarantine (ledger_id);
+CREATE INDEX IF NOT EXISTS quarantine_open_idx ON migration.quarantine (tenant_id, kind) WHERE resolved_at IS NULL;
+
+-- ─────────────────────────────── allowlist ─────────────────────────────
+-- Only these source tables may reach the destination (core-A, core-beauty-chef
+-- §3.1). columns: source column → target spec ("col" | "col@ref_source_table"
+-- resolved through the ledger | "jsonb:path" into metadata | "-" dropped on
+-- purpose). writer: the typed destination writer of 092 ('person', 'unit',
+-- 'category', 'product', 'order', 'invoice', NULL = recorded as pending until a
+-- writer exists). financial_columns: target columns that are NEVER overwritten
+-- once written (EF lesson #3). frozen rows refuse UPDATE/DELETE unless the
+-- session declares migration.allowlist_unlock = 'on' (a migration file does).
+CREATE TABLE IF NOT EXISTS migration.allowlist (
+  source_table      text PRIMARY KEY,
+  target_table      text,
+  layer             text NOT NULL DEFAULT 'core-A',
+  domain            text,
+  columns           jsonb NOT NULL DEFAULT '{}'::jsonb,
+  writer            text CHECK (writer IS NULL OR writer IN ('person', 'unit', 'category', 'product', 'order', 'invoice')),
+  writer_args       jsonb NOT NULL DEFAULT '{}'::jsonb,
+  financial_columns text[] NOT NULL DEFAULT '{}',
+  frozen            boolean NOT NULL DEFAULT false,
+  notes             text,
+  created_at        timestamptz NOT NULL DEFAULT now(),
+  updated_at        timestamptz NOT NULL DEFAULT now()
+);
+
+CREATE OR REPLACE FUNCTION migration.trg_allowlist_frozen()
+RETURNS trigger LANGUAGE plpgsql SECURITY DEFINER SET search_path = '' AS $$
+BEGIN
+  IF OLD.frozen AND coalesce(current_setting('migration.allowlist_unlock', true), '') <> 'on' THEN
+    RAISE EXCEPTION 'migration.allowlist: % is frozen (core-A allowlist changes are a migration file, not a write)', OLD.source_table
+      USING ERRCODE = '55000';
+  END IF;
+  IF TG_OP = 'DELETE' THEN RETURN OLD; END IF;
+  RETURN NEW;
+END $$;
+DROP TRIGGER IF EXISTS allowlist_frozen ON migration.allowlist;
+CREATE TRIGGER allowlist_frozen BEFORE UPDATE OR DELETE ON migration.allowlist
+  FOR EACH ROW EXECUTE FUNCTION migration.trg_allowlist_frozen();
+
+-- Tables the extractor must never send: dead legacy tables and the previous
+-- vendor's one-off import. An upsert for one of these is quarantined
+-- ('allowlist') with the reason below.
+CREATE TABLE IF NOT EXISTS migration.excluded_tables (
+  source_table text PRIMARY KEY,
+  reason       text NOT NULL,
+  created_at   timestamptz NOT NULL DEFAULT now()
+);
+
+-- ─────────────────────────────── tenant fence ──────────────────────────
+-- ADR 0008. v1_writer: V1 owns the tenant, the destination refuses migration
+-- writes. fenced: V1 frozen for cut-over, migration writes allowed, V2 app
+-- writes are the point of no return. v2_writer: live on V2. The kill switch
+-- returns the tenant to V1 ONLY while first_v2_write_at is null; after the
+-- first exclusive V2 write there is no way back (no reverse sync).
+CREATE TABLE IF NOT EXISTS migration.tenant_fence (
+  tenant_id         uuid PRIMARY KEY REFERENCES public.tenants(id) ON DELETE CASCADE,
+  state             text NOT NULL DEFAULT 'v1_writer' CHECK (state IN ('v1_writer', 'fenced', 'v2_writer')),
+  fenced_at         timestamptz,
+  first_v2_write_at timestamptz,
+  kill_switch       boolean NOT NULL DEFAULT false,
+  notes             text,
+  created_at        timestamptz NOT NULL DEFAULT now(),
+  updated_at        timestamptz NOT NULL DEFAULT now()
+);
+
+-- ─────────────────────────────── reconciliation ────────────────────────
+-- Approved differences: a value mismatch (target_table.column) or a source
+-- table the report may ignore, signed by a human. Anything not listed here
+-- keeps the report red.
+CREATE TABLE IF NOT EXISTS migration.exceptions (
+  id           bigserial PRIMARY KEY,
+  tenant_id    uuid NOT NULL REFERENCES public.tenants(id) ON DELETE CASCADE,
+  batch_id     uuid REFERENCES migration.batches(id) ON DELETE SET NULL,
+  source_table text,
+  key          text NOT NULL,
+  reason       text NOT NULL,
+  approved_by  text NOT NULL,
+  approved_at  timestamptz NOT NULL DEFAULT now(),
+  created_at   timestamptz NOT NULL DEFAULT now()
+);
+CREATE INDEX IF NOT EXISTS exceptions_tenant_idx ON migration.exceptions (tenant_id, key);
+
+CREATE TABLE IF NOT EXISTS migration.reconciliation_reports (
+  id         uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  tenant_id  uuid NOT NULL REFERENCES public.tenants(id) ON DELETE CASCADE,
+  batch_id   uuid REFERENCES migration.batches(id) ON DELETE SET NULL,
+  green      boolean NOT NULL,
+  report     jsonb NOT NULL,
+  created_at timestamptz NOT NULL DEFAULT now()
+);
+CREATE INDEX IF NOT EXISTS reconciliation_reports_batch_idx ON migration.reconciliation_reports (batch_id, created_at DESC);
+
+-- ─────────────────────────────── updated_at ────────────────────────────
+DROP TRIGGER IF EXISTS batches_updated_at ON migration.batches;
+CREATE TRIGGER batches_updated_at BEFORE UPDATE ON migration.batches FOR EACH ROW EXECUTE FUNCTION public.handle_updated_at();
+DROP TRIGGER IF EXISTS ledger_updated_at ON migration.ledger;
+CREATE TRIGGER ledger_updated_at BEFORE UPDATE ON migration.ledger FOR EACH ROW EXECUTE FUNCTION public.handle_updated_at();
+DROP TRIGGER IF EXISTS allowlist_updated_at ON migration.allowlist;
+CREATE TRIGGER allowlist_updated_at BEFORE UPDATE ON migration.allowlist FOR EACH ROW EXECUTE FUNCTION public.handle_updated_at();
+DROP TRIGGER IF EXISTS tenant_fence_updated_at ON migration.tenant_fence;
+CREATE TRIGGER tenant_fence_updated_at BEFORE UPDATE ON migration.tenant_fence FOR EACH ROW EXECUTE FUNCTION public.handle_updated_at();
+
+-- ─────────────────────────────── posture ───────────────────────────────
+-- RLS on, no policy for any API role; service_role bypasses RLS and is the
+-- only role granted; the RPC owner reaches the tables as owner.
+DO $$
+DECLARE t text;
+BEGIN
+  FOREACH t IN ARRAY ARRAY['batches', 'ledger', 'quarantine', 'allowlist', 'excluded_tables', 'tenant_fence', 'exceptions', 'reconciliation_reports'] LOOP
+    EXECUTE format('ALTER TABLE migration.%I ENABLE ROW LEVEL SECURITY', t);
+    EXECUTE format('REVOKE ALL ON migration.%I FROM public, anon, authenticated', t);
+    EXECUTE format('GRANT ALL ON migration.%I TO service_role', t);
+  END LOOP;
+END $$;
+GRANT USAGE, SELECT ON ALL SEQUENCES IN SCHEMA migration TO service_role;
+REVOKE ALL ON FUNCTION migration.trg_allowlist_frozen() FROM public, anon, authenticated;