pg_ledger 0.1.0

data/lib/generators/pg_ledger/install/templates/create_pg_ledger_tables.rb

@@ -0,0 +1,511 @@
+class CreatePgLedgerTables < ActiveRecord::Migration<%= migration_version %>
+  def change
+    # Isolated ledgers (brands, legal entities, platform tenants). Everything
+    # is scoped to one; the default ledger "main" keeps single-ledger apps
+    # entirely unaware of this layer.
+    create_table :pg_ledger_ledgers do |t|
+      t.string :name, null: false, index: { unique: true }
+      # Who this book belongs to (platform tenant, brand, legal entity).
+      # Structural membership of accounts is ledger_id; domain ownership of a
+      # wallet stays accounts.owner — two different relations.
+      t.references :owner, polymorphic: true
+      t.datetime :created_at, null: false
+    end
+
+    create_table :pg_ledger_accounts do |t|
+      t.bigint :ledger_id, null: false, default: 1
+      t.string :code, null: false
+      t.string :currency, null: false
+      t.string :normal_balance, null: false
+      t.references :owner, polymorphic: true
+      t.bigint :min_balance
+      t.datetime :frozen_at
+      t.integer :balance_shards, null: false, default: 1
+      t.jsonb :metadata, null: false, default: {}
+      t.timestamps
+
+      t.check_constraint "normal_balance IN ('debit', 'credit')", name: "pg_ledger_accounts_normal_balance"
+      t.check_constraint "currency = upper(currency)", name: "pg_ledger_accounts_currency_upcase"
+      t.check_constraint "balance_shards >= 1", name: "pg_ledger_accounts_shards_positive"
+      t.check_constraint "min_balance IS NULL OR balance_shards = 1", name: "pg_ledger_accounts_no_sharded_min"
+    end
+
+    add_index :pg_ledger_accounts,
+      "ledger_id, code, currency, coalesce(owner_type, ''), coalesce(owner_id, 0)",
+      unique: true, name: "index_pg_ledger_accounts_uniqueness"
+    add_foreign_key :pg_ledger_accounts, :pg_ledger_ledgers, column: :ledger_id
+
+    create_table :pg_ledger_entries do |t|
+      t.bigint :ledger_id, null: false, default: 1
+      t.string :idempotency_key
+      t.string :request_digest
+      t.bigint :reverses_entry_id
+      t.jsonb :metadata, null: false, default: {}
+      t.datetime :posted_at, null: false
+      t.datetime :created_at, null: false
+
+      t.index :reverses_entry_id, where: "reverses_entry_id IS NOT NULL"
+
+      t.index [:ledger_id, :idempotency_key], unique: true,
+        where: "idempotency_key IS NOT NULL",
+        name: "index_pg_ledger_entries_on_idempotency_key"
+      t.index :posted_at
+    end
+    add_foreign_key :pg_ledger_entries, :pg_ledger_ledgers, column: :ledger_id
+
+    # One journal row IS one double entry: money moves debit_account →
+    # credit_account in one currency. Any posting decomposes into pairs
+    # (after per-account netting), so every set of rows is balanced by
+    # construction — no balance trigger exists. The composite foreign keys
+    # below make a cross-currency or cross-ledger pair physically
+    # unrepresentable.
+    create_table :pg_ledger_lines do |t|
+      t.references :entry, null: false, index: false, foreign_key: { to_table: :pg_ledger_entries }
+      t.bigint :ledger_id, null: false
+      t.string :currency, null: false
+      t.bigint :debit_account_id, null: false
+      t.bigint :credit_account_id, null: false
+      t.bigint :amount, null: false
+      # Denormalized from the entry so reporting scans lines without a join.
+      t.datetime :posted_at, null: false
+      t.datetime :created_at, null: false
+
+      t.check_constraint "amount > 0", name: "pg_ledger_lines_amount_positive"
+      t.check_constraint "debit_account_id <> credit_account_id", name: "pg_ledger_lines_distinct_accounts"
+      t.index :entry_id
+      t.index [:debit_account_id, :posted_at]
+      t.index [:credit_account_id, :posted_at]
+      # Lines are appended in time order, so a BRIN index is tiny and makes
+      # recent-window scans (load detection, ops queries) cheap.
+      t.index :posted_at, using: :brin
+    end
+
+    # The uniqueness pillar the composite FKs stand on: an account id always
+    # carries exactly this (ledger, currency).
+    add_index :pg_ledger_accounts, [:id, :ledger_id, :currency], unique: true,
+      name: "index_pg_ledger_accounts_identity"
+    add_foreign_key :pg_ledger_lines, :pg_ledger_accounts,
+      column: [:debit_account_id, :ledger_id, :currency],
+      primary_key: [:id, :ledger_id, :currency],
+      name: "fk_pg_ledger_lines_debit_identity"
+    add_foreign_key :pg_ledger_lines, :pg_ledger_accounts,
+      column: [:credit_account_id, :ledger_id, :currency],
+      primary_key: [:id, :ledger_id, :currency],
+      name: "fk_pg_ledger_lines_credit_identity"
+
+    # Per-ledger config. closed_before: entries with posted_at earlier than
+    # this date are rejected — that ledger's accounting period is closed.
+    create_table :pg_ledger_config, id: false do |t|
+      t.bigint :ledger_id, primary_key: true
+      t.date :closed_before
+    end
+    add_foreign_key :pg_ledger_config, :pg_ledger_ledgers, column: :ledger_id
+
+    # Daily per-account rollups. Filled by PgLedger.rollup! (idempotent, run it
+    # from a scheduled job); reporting reads snapshot + today's tail from lines.
+    # The write path never touches this table.
+    create_table :pg_ledger_account_days, primary_key: [:account_id, :day] do |t|
+      t.bigint :account_id, null: false
+      t.date :day, null: false
+      t.bigint :debits, null: false, default: 0
+      t.bigint :credits, null: false, default: 0
+    end
+
+    # Update-heavy: low fillfactor leaves page room so balance updates stay
+    # HOT (no index maintenance); the only index is the (account_id, shard) key.
+    create_table :pg_ledger_balances, options: "WITH (fillfactor = 80)" do |t|
+      t.references :account, null: false, foreign_key: { to_table: :pg_ledger_accounts }
+      t.integer :shard, null: false, default: 0
+      t.bigint :amount, null: false, default: 0
+      t.timestamps
+
+      t.index [:account_id, :shard], unique: true
+    end
+
+    # Invariants enforced by Postgres itself. Ruby checks are a convenience;
+    # these triggers and functions are the guarantee.
+    reversible do |dir|
+      dir.up do
+        execute <<~SQL
+          INSERT INTO pg_ledger_ledgers (id, name, created_at) VALUES (1, 'main', now());
+          SELECT setval('pg_ledger_ledgers_id_seq', 1);
+        SQL
+
+        # 1. Balance-per-currency needs no trigger in this schema: a journal
+        #    row IS a balanced pair, and the composite FKs pin its currency
+        #    and ledger. There is nothing left to check at write time.
+        # 2. The ledger is append-only. Corrections are reversal entries.
+        execute <<~SQL
+          CREATE FUNCTION pg_ledger_immutable() RETURNS trigger AS $$
+          BEGIN
+            RAISE EXCEPTION 'pg_ledger: % rows are immutable', TG_TABLE_NAME;
+          END $$ LANGUAGE plpgsql;
+
+          CREATE TRIGGER pg_ledger_lines_immutable
+          BEFORE UPDATE OR DELETE ON pg_ledger_lines
+          FOR EACH ROW EXECUTE FUNCTION pg_ledger_immutable();
+
+          CREATE TRIGGER pg_ledger_entries_immutable
+          BEFORE UPDATE OR DELETE ON pg_ledger_entries
+          FOR EACH ROW EXECUTE FUNCTION pg_ledger_immutable();
+        SQL
+
+        # 3. Balance application. Deltas arrive pre-sorted per posting; the loop
+        #    locks/updates one row at a time in (account_id, shard) order — the
+        #    deadlock-prevention invariant. A plpgsql loop guarantees lock order
+        #    where ORDER BY + FOR UPDATE does not (seq scan locks in scan order).
+        execute <<~SQL
+          -- Set-based: one lock pass, one upsert, one min_balance check.
+          -- Locks are taken in canonical (account_id, shard) order via the
+          -- sorted LATERAL — a plain ORDER BY + FOR UPDATE does not guarantee
+          -- acquisition order, a nested loop over a sorted outer side does.
+          -- min_balance is enforced on the post's final amounts (the posting
+          -- is atomic; intermediate per-leg states are unobservable).
+          CREATE FUNCTION pg_ledger_apply_deltas(p_deltas jsonb, p_check boolean DEFAULT true) RETURNS void AS $$
+          DECLARE
+            viol record;
+          BEGIN
+            PERFORM 1
+            FROM (SELECT DISTINCT (x->>'account_id')::bigint AS account_id,
+                         coalesce((x->>'shard')::int, 0) AS shard
+                  FROM jsonb_array_elements(p_deltas) x
+                  ORDER BY 1, 2) t,
+            LATERAL (SELECT 1 FROM pg_ledger_balances b
+                     WHERE b.account_id = t.account_id AND b.shard = t.shard
+                     FOR UPDATE) l;
+
+            WITH d AS (
+              SELECT (x->>'account_id')::bigint AS account_id,
+                     coalesce((x->>'shard')::int, 0) AS shard,
+                     SUM((x->>'delta')::bigint) AS delta,
+                     MAX((x->>'min_balance')::bigint) AS min_balance
+              FROM jsonb_array_elements(p_deltas) x
+              GROUP BY 1, 2
+            ),
+            ups AS (
+              INSERT INTO pg_ledger_balances (account_id, shard, amount, created_at, updated_at)
+              SELECT account_id, shard, delta, now(), now() FROM d ORDER BY account_id, shard
+              ON CONFLICT (account_id, shard) DO UPDATE
+                SET amount = pg_ledger_balances.amount + EXCLUDED.amount, updated_at = now()
+              RETURNING account_id, shard, amount
+            )
+            SELECT u.account_id, u.amount, d.min_balance INTO viol
+            FROM ups u JOIN d USING (account_id, shard)
+            WHERE p_check AND d.min_balance IS NOT NULL AND u.amount < d.min_balance
+            LIMIT 1;
+
+            IF viol.account_id IS NOT NULL THEN
+              RAISE EXCEPTION 'pg_ledger:insufficient_balance account=% amount=% min=%',
+                viol.account_id, viol.amount, viol.min_balance;
+            END IF;
+          END $$ LANGUAGE plpgsql;
+        SQL
+
+        # 4. One posting = one statement (implicit transaction, single fsync).
+        #    Also enforces: no postings on frozen accounts, no postings into a
+        #    closed period, and reversal limits — per account, the sum of all
+        #    reversals of an entry can never exceed the original legs.
+        execute <<~SQL
+          CREATE FUNCTION pg_ledger_post(
+            p_key text, p_digest text, p_metadata jsonb, p_posted_at timestamptz,
+            p_legs jsonb, p_deltas jsonb, p_reverses bigint DEFAULT NULL,
+            p_ledger bigint DEFAULT 1, p_check boolean DEFAULT true
+          ) RETURNS pg_ledger_entries AS $$
+          DECLARE
+            v_entry pg_ledger_entries;
+            v_bad record;
+            v_closed date;
+            r record;
+            v_orig bigint;
+            v_prev bigint;
+          BEGIN
+            IF p_key IS NOT NULL THEN
+              SELECT * INTO v_entry FROM pg_ledger_entries
+              WHERE ledger_id = p_ledger AND idempotency_key = p_key;
+              IF FOUND THEN
+                IF v_entry.request_digest = p_digest THEN RETURN v_entry; END IF;
+                RAISE EXCEPTION 'pg_ledger:idempotency_conflict key=% entry=%', p_key, v_entry.id;
+              END IF;
+            END IF;
+
+            -- Both sides of every pair; LATERAL forces an index probe per id.
+            SELECT a.code, a.frozen_at, a.ledger_id INTO v_bad
+            FROM jsonb_array_elements(p_legs) l,
+            LATERAL (SELECT unnest(ARRAY[(l->>'debit_account_id')::bigint,
+                                         (l->>'credit_account_id')::bigint]) AS id) s,
+            LATERAL (SELECT code, frozen_at, ledger_id FROM pg_ledger_accounts
+                     WHERE id = s.id) a
+            WHERE a.frozen_at IS NOT NULL OR a.ledger_id <> p_ledger
+            LIMIT 1;
+            IF v_bad.code IS NOT NULL THEN
+              IF v_bad.ledger_id <> p_ledger THEN
+                RAISE EXCEPTION 'pg_ledger:cross_ledger account % belongs to ledger %, entry targets %',
+                  v_bad.code, v_bad.ledger_id, p_ledger;
+              END IF;
+              RAISE EXCEPTION 'pg_ledger:frozen_account %', v_bad.code;
+            END IF;
+
+            SELECT closed_before INTO v_closed FROM pg_ledger_config WHERE ledger_id = p_ledger;
+            IF v_closed IS NOT NULL AND coalesce(p_posted_at, now()) < v_closed THEN
+              RAISE EXCEPTION 'pg_ledger:period_closed posted_at % is before %',
+                coalesce(p_posted_at, now()), v_closed;
+            END IF;
+
+            IF p_reverses IS NOT NULL THEN
+              -- Lock the original entry row: concurrent reversals serialize here.
+              PERFORM 1 FROM pg_ledger_entries
+              WHERE id = p_reverses AND ledger_id = p_ledger FOR UPDATE;
+              IF NOT FOUND THEN
+                RAISE EXCEPTION 'pg_ledger:invalid_reversal entry % not found in ledger %', p_reverses, p_ledger;
+              END IF;
+
+              -- A reversal pair (d -> c) undoes original flow (c -> d); per
+              -- directed pair the reversals may never exceed the original.
+              FOR r IN
+                SELECT (x->>'debit_account_id')::bigint AS d,
+                       (x->>'credit_account_id')::bigint AS c,
+                       (x->>'amount')::bigint AS amount
+                FROM jsonb_array_elements(p_legs) x
+              LOOP
+                SELECT COALESCE(SUM(amount), 0) INTO v_orig FROM pg_ledger_lines
+                WHERE entry_id = p_reverses AND debit_account_id = r.c AND credit_account_id = r.d;
+                IF v_orig = 0 THEN
+                  RAISE EXCEPTION 'pg_ledger:invalid_reversal entry % has no opposite leg on account %',
+                    p_reverses, r.d;
+                END IF;
+
+                SELECT COALESCE(SUM(l.amount), 0) INTO v_prev
+                FROM pg_ledger_lines l
+                JOIN pg_ledger_entries e ON e.id = l.entry_id
+                WHERE e.reverses_entry_id = p_reverses
+                  AND l.debit_account_id = r.d AND l.credit_account_id = r.c;
+                IF v_prev + r.amount > v_orig THEN
+                  RAISE EXCEPTION 'pg_ledger:over_reversal account % already reversed % of %, cannot add %',
+                    r.d, v_prev, v_orig, r.amount;
+                END IF;
+              END LOOP;
+            END IF;
+
+            BEGIN
+              INSERT INTO pg_ledger_entries (ledger_id, idempotency_key, request_digest, reverses_entry_id, metadata, posted_at, created_at)
+              VALUES (p_ledger, p_key, p_digest, p_reverses, coalesce(p_metadata, '{}'), coalesce(p_posted_at, now()), now())
+              RETURNING * INTO v_entry;
+            EXCEPTION WHEN unique_violation THEN
+              SELECT * INTO v_entry FROM pg_ledger_entries
+              WHERE ledger_id = p_ledger AND idempotency_key = p_key;
+              IF v_entry.request_digest = p_digest THEN RETURN v_entry; END IF;
+              RAISE EXCEPTION 'pg_ledger:idempotency_conflict key=% entry=%', p_key, v_entry.id;
+            END;
+
+            INSERT INTO pg_ledger_lines (entry_id, ledger_id, currency, debit_account_id, credit_account_id, amount, posted_at, created_at)
+            SELECT v_entry.id, p_ledger, l->>'currency',
+                   (l->>'debit_account_id')::bigint, (l->>'credit_account_id')::bigint,
+                   (l->>'amount')::bigint, v_entry.posted_at, now()
+            FROM jsonb_array_elements(p_legs) l;
+
+            PERFORM pg_ledger_apply_deltas(p_deltas, p_check);
+            RETURN v_entry;
+          END $$ LANGUAGE plpgsql;
+        SQL
+
+        # 5. Batch: N postings = one statement, one fsync, atomic as a whole.
+        #    Pre-locks the union of touched balance rows in global order so
+        #    per-posting lock sequences cannot interleave into a deadlock.
+        execute <<~SQL
+          CREATE FUNCTION pg_ledger_post_batch(
+            p_ledger bigint[], p_key text[], p_digest text[], p_metadata jsonb[],
+            p_posted timestamptz[], p_reverses bigint[],
+            p_leg_ent int[], p_leg_debit bigint[], p_leg_credit bigint[], p_leg_cur text[], p_leg_amount bigint[],
+            p_d_ent int[], p_d_account bigint[], p_d_shard int[], p_d_delta bigint[], p_d_min bigint[]
+          ) RETURNS SETOF pg_ledger_entries AS $$
+          DECLARE
+            e record;
+            v_bad record;
+            v_ids bigint[];
+            v_inserted bigint[];
+          BEGIN
+            -- Typed arrays land pre-parsed: no jsonb walking on the hot path.
+            CREATE TEMP TABLE IF NOT EXISTS batch_req (
+              ord int, ledger_id bigint, key text, digest text,
+              metadata jsonb, posted_at timestamptz, reverses bigint, entry_id bigint
+            ) ON COMMIT DELETE ROWS;
+            CREATE TEMP TABLE IF NOT EXISTS batch_legs (
+              ord int, debit_account_id bigint, credit_account_id bigint, currency text, amount bigint
+            ) ON COMMIT DELETE ROWS;
+            CREATE INDEX IF NOT EXISTS batch_legs_ord ON batch_legs (ord);
+            CREATE TEMP TABLE IF NOT EXISTS batch_deltas (
+              ord int, account_id bigint, shard int, delta bigint, min_balance bigint
+            ) ON COMMIT DELETE ROWS;
+            CREATE INDEX IF NOT EXISTS batch_deltas_ord ON batch_deltas (ord);
+            DELETE FROM batch_req; DELETE FROM batch_legs; DELETE FROM batch_deltas;
+
+            INSERT INTO batch_req
+            SELECT i, p_ledger[i], p_key[i], p_digest[i], coalesce(p_metadata[i], '{}'::jsonb),
+                   coalesce(p_posted[i], now()), p_reverses[i], NULL
+            FROM generate_subscripts(p_ledger, 1) i;
+
+            INSERT INTO batch_legs
+            SELECT p_leg_ent[i], p_leg_debit[i], p_leg_credit[i], p_leg_cur[i], p_leg_amount[i]
+            FROM generate_subscripts(p_leg_ent, 1) i;
+
+            INSERT INTO batch_deltas
+            SELECT p_d_ent[i], p_d_account[i], p_d_shard[i], p_d_delta[i], p_d_min[i]
+            FROM generate_subscripts(p_d_ent, 1) i;
+
+            ANALYZE batch_req;
+
+            -- Canonical pre-lock over every touched balance row.
+            PERFORM 1
+            FROM (SELECT DISTINCT account_id, shard FROM batch_deltas ORDER BY 1, 2) t,
+            LATERAL (SELECT 1 FROM pg_ledger_balances b
+                     WHERE b.account_id = t.account_id AND b.shard = t.shard
+                     FOR UPDATE) l;
+
+            -- Replays return their entries and move no money; digest mismatch
+            -- is a hard conflict.
+            UPDATE batch_req r SET entry_id = en.id
+            FROM pg_ledger_entries en
+            WHERE r.key IS NOT NULL AND r.reverses IS NULL
+              AND en.ledger_id = r.ledger_id AND en.idempotency_key = r.key;
+
+            SELECT r.key, en.id, en.request_digest INTO v_bad
+            FROM batch_req r JOIN pg_ledger_entries en ON en.id = r.entry_id
+            WHERE en.request_digest IS DISTINCT FROM r.digest
+            LIMIT 1;
+            IF v_bad.key IS NOT NULL THEN
+              RAISE EXCEPTION 'pg_ledger:idempotency_conflict key=% entry=%', v_bad.key, v_bad.id;
+            END IF;
+
+            -- Batch-wide account validation for the fast path.
+            SELECT a.code, a.frozen_at, a.ledger_id, r.ledger_id AS want INTO v_bad
+            FROM batch_req r JOIN batch_legs g ON g.ord = r.ord,
+            LATERAL (SELECT unnest(ARRAY[g.debit_account_id, g.credit_account_id]) AS id) s,
+            LATERAL (SELECT code, frozen_at, ledger_id FROM pg_ledger_accounts
+                     WHERE id = s.id) a
+            WHERE r.entry_id IS NULL AND r.reverses IS NULL
+              AND (a.frozen_at IS NOT NULL OR a.ledger_id <> r.ledger_id)
+            LIMIT 1;
+            IF v_bad.code IS NOT NULL THEN
+              IF v_bad.ledger_id <> v_bad.want THEN
+                RAISE EXCEPTION 'pg_ledger:cross_ledger account % belongs to ledger %, entry targets %',
+                  v_bad.code, v_bad.ledger_id, v_bad.want;
+              END IF;
+              RAISE EXCEPTION 'pg_ledger:frozen_account %', v_bad.code;
+            END IF;
+
+            SELECT r.posted_at, c.closed_before INTO v_bad
+            FROM batch_req r JOIN pg_ledger_config c ON c.ledger_id = r.ledger_id
+            WHERE r.entry_id IS NULL AND r.reverses IS NULL
+              AND c.closed_before IS NOT NULL AND r.posted_at < c.closed_before
+            LIMIT 1;
+            IF v_bad.posted_at IS NOT NULL THEN
+              RAISE EXCEPTION 'pg_ledger:period_closed posted_at % is before %',
+                v_bad.posted_at, v_bad.closed_before;
+            END IF;
+
+            -- Fast path: three set-based writes for all plain postings.
+            SELECT array_agg(nextval('pg_ledger_entries_id_seq')) INTO v_ids
+            FROM batch_req WHERE entry_id IS NULL AND reverses IS NULL;
+
+            WITH todo AS (
+              SELECT r.ord, r.ledger_id, r.key, r.digest, r.metadata, r.posted_at,
+                     v_ids[row_number() OVER (ORDER BY r.ord)] AS new_id
+              FROM batch_req r WHERE r.entry_id IS NULL AND r.reverses IS NULL
+            ),
+            ins AS (
+              INSERT INTO pg_ledger_entries (id, ledger_id, idempotency_key, request_digest, metadata, posted_at, created_at)
+              SELECT new_id, ledger_id, key, digest, metadata, posted_at, now() FROM todo
+              ORDER BY ledger_id, key NULLS LAST
+              ON CONFLICT (ledger_id, idempotency_key) WHERE idempotency_key IS NOT NULL DO NOTHING
+              RETURNING id
+            )
+            SELECT array_agg(id) INTO v_inserted FROM ins;
+
+            UPDATE batch_req r SET entry_id = t.new_id
+            FROM (SELECT r2.ord, v_ids[row_number() OVER (ORDER BY r2.ord)] AS new_id
+                  FROM batch_req r2 WHERE r2.entry_id IS NULL AND r2.reverses IS NULL) t
+            WHERE r.ord = t.ord AND t.new_id = ANY(coalesce(v_inserted, '{}'));
+
+            UPDATE batch_req r SET entry_id = en.id
+            FROM pg_ledger_entries en
+            WHERE r.entry_id IS NULL AND r.reverses IS NULL AND r.key IS NOT NULL
+              AND en.ledger_id = r.ledger_id AND en.idempotency_key = r.key;
+
+            SELECT r.key, en.id, en.request_digest INTO v_bad
+            FROM batch_req r JOIN pg_ledger_entries en ON en.id = r.entry_id
+            WHERE en.request_digest IS DISTINCT FROM r.digest
+            LIMIT 1;
+            IF v_bad.key IS NOT NULL THEN
+              RAISE EXCEPTION 'pg_ledger:idempotency_conflict key=% entry=%', v_bad.key, v_bad.id;
+            END IF;
+
+            INSERT INTO pg_ledger_lines (entry_id, ledger_id, currency, debit_account_id, credit_account_id, amount, posted_at, created_at)
+            SELECT r.entry_id, r.ledger_id, g.currency, g.debit_account_id, g.credit_account_id,
+                   g.amount, r.posted_at, now()
+            FROM batch_req r JOIN batch_legs g ON g.ord = r.ord
+            WHERE r.reverses IS NULL AND r.entry_id = ANY(coalesce(v_inserted, '{}'));
+
+            -- Deltas of the fresh entries, applied set-wise without the
+            -- per-post check; min_balance holds on the batch's final state.
+            PERFORM pg_ledger_apply_deltas(
+              (SELECT jsonb_agg(jsonb_build_object(
+                 'account_id', d.account_id, 'shard', d.shard,
+                 'delta', d.delta, 'min_balance', d.min_balance))
+               FROM batch_req r JOIN batch_deltas d ON d.ord = r.ord
+               WHERE r.reverses IS NULL AND r.entry_id = ANY(coalesce(v_inserted, '{}'))), false)
+            WHERE EXISTS (SELECT 1 FROM batch_req r WHERE r.reverses IS NULL
+                          AND r.entry_id = ANY(coalesce(v_inserted, '{}')));
+
+            -- Reversals stay on the guarded single-post path (rare).
+            FOR e IN SELECT * FROM batch_req WHERE reverses IS NOT NULL ORDER BY ord LOOP
+              UPDATE batch_req SET entry_id = (
+                SELECT id FROM pg_ledger_post(
+                  e.key, e.digest, e.metadata, e.posted_at,
+                  (SELECT jsonb_agg(jsonb_build_object(
+                     'debit_account_id', g.debit_account_id,
+                     'credit_account_id', g.credit_account_id,
+                     'currency', g.currency,
+                     'amount', g.amount))
+                   FROM batch_legs g WHERE g.ord = e.ord),
+                  (SELECT jsonb_agg(jsonb_build_object(
+                     'account_id', d.account_id, 'shard', d.shard,
+                     'delta', d.delta, 'min_balance', d.min_balance))
+                   FROM batch_deltas d WHERE d.ord = e.ord),
+                  e.reverses, e.ledger_id, false)
+              ) WHERE ord = e.ord;
+            END LOOP;
+
+            -- min_balance on the batch's FINAL account state.
+            SELECT a.id AS account_id, s.amount, a.min_balance INTO v_bad
+            FROM (SELECT DISTINCT account_id FROM batch_deltas) t
+            JOIN pg_ledger_accounts a ON a.id = t.account_id AND a.min_balance IS NOT NULL,
+            LATERAL (SELECT SUM(amount) AS amount FROM pg_ledger_balances
+                     WHERE account_id = t.account_id) s
+            WHERE s.amount < a.min_balance
+            LIMIT 1;
+            IF v_bad.account_id IS NOT NULL THEN
+              RAISE EXCEPTION 'pg_ledger:insufficient_balance account=% amount=% min=%',
+                v_bad.account_id, v_bad.amount, v_bad.min_balance;
+            END IF;
+
+            RETURN QUERY
+            SELECT en.* FROM batch_req r
+            JOIN pg_ledger_entries en ON en.id = r.entry_id
+            ORDER BY r.ord;
+          END $$ LANGUAGE plpgsql;
+        SQL
+      end
+
+      dir.down do
+        execute <<~SQL
+          DROP FUNCTION pg_ledger_post_batch(bigint[], text[], text[], jsonb[], timestamptz[], bigint[], int[], bigint[], bigint[], text[], bigint[], int[], bigint[], int[], bigint[], bigint[]);
+          DROP FUNCTION pg_ledger_post(text, text, jsonb, timestamptz, jsonb, jsonb, bigint, bigint, boolean);
+          DROP FUNCTION pg_ledger_apply_deltas(jsonb, boolean);
+          DROP TRIGGER pg_ledger_entries_immutable ON pg_ledger_entries;
+          DROP TRIGGER pg_ledger_lines_immutable ON pg_ledger_lines;
+          DROP FUNCTION pg_ledger_immutable();
+        SQL
+      end
+    end
+  end
+end

data/lib/pg_ledger/batch.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module PgLedger
+  # Collects postings and commits them as ONE statement / one fsync.
+  # Atomic: if any posting fails, the whole batch rolls back.
+  class Batch
+    # Typed arrays instead of one big jsonb: the server unnests pre-parsed
+    # values straight into the batch temp tables — no jsonb walking.
+    CALL_SQL = <<~SQL
+      SELECT * FROM pg_ledger_post_batch(
+        $1::bigint[], $2::text[], $3::text[], $4::jsonb[], $5::timestamptz[], $6::bigint[],
+        $7::int[], $8::bigint[], $9::bigint[], $10::text[], $11::bigint[],
+        $12::int[], $13::bigint[], $14::int[], $15::bigint[], $16::bigint[])
+    SQL
+
+    def initialize(default_ledger_id: DEFAULT_LEDGER_ID)
+      @default_ledger_id = default_ledger_id
+      @postings = []
+      # Shard affinity: every posting in this batch hits the same shard per
+      # account, so the batch pre-locks one row per account and concurrent
+      # batches (with different hints) don't contend.
+      @shard_hint = rand
+    end
+
+    def post!(idempotency_key: nil, metadata: {}, posted_at: nil, reverses: nil,
+              ledger_id: nil)
+      ledger_id ||= @default_ledger_id
+      builder = EntryBuilder.new
+      yield builder
+      @postings << Posting.new(
+        legs: builder.legs, idempotency_key: idempotency_key,
+        metadata: metadata, posted_at: posted_at,
+        reverses: reverses.is_a?(Entry) ? reverses.id : reverses,
+        shard_hint: @shard_hint,
+        ledger_id: ledger_id
+      )
+      nil
+    end
+
+    def transfer!(from:, to:, amount:, idempotency_key: nil, metadata: {}, posted_at: nil,
+                  ledger_id: nil)
+      ledger_id ||= @default_ledger_id
+      from = Account.resolve!(from, ledger_id: ledger_id)
+      to = Account.resolve!(to, ledger_id: ledger_id)
+      post!(idempotency_key: idempotency_key, metadata: metadata, posted_at: posted_at,
+            ledger_id: from.ledger_id) do |entry|
+        PgLedger.build_transfer(entry, from, to, amount)
+      end
+    end
+
+    def commit!
+      return [] if @postings.empty?
+
+      encoder = PG::TextEncoder::Array.new
+      result = Entry.connection.raw_connection.exec_params(
+        CALL_SQL, column_arrays.map { |a| encoder.encode(a) }
+      )
+      entries = result.map { |row| Entry.instantiate(row) }
+      result.clear
+      entries
+    rescue PG::Error, ActiveRecord::StatementInvalid => e
+      raise Posting.map_pg_error(e)
+    end
+
+    private
+
+    # The batch flattened into the 16 parallel arrays the SQL function takes:
+    # entry headers, then legs and deltas keyed by their entry's ordinal.
+    def column_arrays
+      cols = Array.new(16) { [] }
+      @postings.map(&:payload).each_with_index do |p, idx|
+        ord = idx + 1
+        cols[0] << p[:ledger_id]
+        cols[1] << p[:idempotency_key]
+        cols[2] << p[:request_digest]
+        cols[3] << JSON.generate(p[:metadata] || {})
+        cols[4] << p[:posted_at]&.iso8601(6)
+        cols[5] << p[:reverses_entry_id]
+        p[:legs].each do |l|
+          cols[6] << ord
+          cols[7] << l[:debit_account_id]
+          cols[8] << l[:credit_account_id]
+          cols[9] << l[:currency]
+          cols[10] << l[:amount]
+        end
+        p[:deltas].each do |d|
+          cols[11] << ord
+          cols[12] << d[:account_id]
+          cols[13] << d[:shard]
+          cols[14] << d[:delta]
+          cols[15] << d[:min_balance]
+        end
+      end
+      cols
+    end
+  end
+end

data/lib/pg_ledger/entry_builder.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module PgLedger
+  class EntryBuilder
+    Leg = Struct.new(:direction, :account_ref, :amount)
+
+    attr_reader :legs
+
+    def initialize
+      @legs = []
+    end
+
+    def debit(account, amount)
+      add(:debit, account, amount)
+    end
+
+    def credit(account, amount)
+      add(:credit, account, amount)
+    end
+
+    private
+
+    def add(direction, account, amount)
+      unless amount.is_a?(Integer)
+        raise ArgumentError, "amount must be an Integer in minor units, got #{amount.class}"
+      end
+      raise ArgumentError, "amount must be positive, got #{amount}" unless amount.positive?
+
+      @legs << Leg.new(direction.to_s, account, amount)
+      self
+    end
+  end
+end

data/lib/pg_ledger/ledger_scope.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module PgLedger
+  # Every module operation, pinned to one ledger:
+  #   billing = PgLedger.ledger("billing")
+  #   billing.create_account!(code: "cash", currency: "USD", normal_balance: :debit)
+  #   billing.transfer!(from: "cash", to: "fees", amount: 100)
+  class LedgerScope
+    attr_reader :record
+
+    def initialize(record)
+      @record = record
+    end
+
+    def id = record.id
+    def name = record.name
+
+    SCOPED = %i[
+      post! transfer! reverse! create_account! freeze_account! unfreeze_account!
+      close_period! balances
+    ].freeze
+
+    SCOPED.each do |m|
+      define_method(m) do |*args, **kwargs, &block|
+        PgLedger.public_send(m, *args, **kwargs.merge(ledger_id: id), &block)
+      end
+    end
+
+    def batch
+      collector = Batch.new(default_ledger_id: id)
+      yield collector
+      collector.commit!
+    end
+
+    def resolve!(ref, currency: nil)
+      Account.resolve!(ref, currency: currency, ledger_id: id)
+    end
+
+    def accounts
+      Account.where(ledger_id: id)
+    end
+  end
+end