fix(close): freeze hard-close trial balance evidence

database/migrations/0009_accounting_book_period_control.sql

@@ -22,12 +22,13 @@ CREATE INDEX accounting_book_period_scope_index
         tenant_account_id, accounting_book_id, fiscal_period_id, period_status_code
     );
 
-ALTER TABLE accounting_core.accounting_book_period_control ENABLE ROW LEVEL SECURITY;
-ALTER TABLE accounting_core.accounting_book_period_control FORCE ROW LEVEL SECURITY;
-CREATE POLICY accounting_book_period_isolation
-    ON accounting_core.accounting_book_period_control
-    USING (tenant_account_id = accounting_core.current_tenant_account_id())
-    WITH CHECK (tenant_account_id = accounting_core.current_tenant_account_id());
+-- Migrations 0005+ force the table owner through tenant RLS on both source
+-- relations. An unbound NOSUPERUSER/NOBYPASSRLS migration owner therefore
+-- needs its normal owner visibility restored on the sources before this
+-- all-tenant backfill. RLS stays enabled for non-owner roles, and FORCE is
+-- restored before the migration transaction commits.
+ALTER TABLE accounting_core.accounting_book NO FORCE ROW LEVEL SECURITY;
+ALTER TABLE accounting_core.fiscal_period NO FORCE ROW LEVEL SECURITY;
 
 INSERT INTO accounting_core.accounting_book_period_control (
     tenant_account_id, accounting_book_id, fiscal_period_id,
@@ -44,6 +45,16 @@ JOIN accounting_core.fiscal_period
 WHERE accounting_book.valid_to IS NULL
 ON CONFLICT (tenant_account_id, accounting_book_id, fiscal_period_id) DO NOTHING;
 
+ALTER TABLE accounting_core.fiscal_period FORCE ROW LEVEL SECURITY;
+ALTER TABLE accounting_core.accounting_book FORCE ROW LEVEL SECURITY;
+
+ALTER TABLE accounting_core.accounting_book_period_control ENABLE ROW LEVEL SECURITY;
+ALTER TABLE accounting_core.accounting_book_period_control FORCE ROW LEVEL SECURITY;
+CREATE POLICY accounting_book_period_isolation
+    ON accounting_core.accounting_book_period_control
+    USING (tenant_account_id = accounting_core.current_tenant_account_id())
+    WITH CHECK (tenant_account_id = accounting_core.current_tenant_account_id());
+
 CREATE OR REPLACE FUNCTION accounting_core.guard_period_insert()
 RETURNS trigger
 LANGUAGE plpgsql

database/migrations/0029_trial_balance_snapshot_population_unique_index.sql

@@ -0,0 +1,6 @@
+-- PostgreSQL requires CREATE INDEX CONCURRENTLY to run outside a transaction block.
+-- Keep this migration to the single concurrent build so the canonical installer can
+-- apply it as one autocommit statement without blocking ordinary table writes.
+CREATE UNIQUE INDEX CONCURRENTLY trial_balance_snapshot_one_population_per_book_period
+ON accounting_reporting.trial_balance_snapshot
+    (tenant_account_id, accounting_book_id, fiscal_period_id);

database/migrations/0030_trial_balance_snapshot_immutability.sql

@@ -0,0 +1,245 @@
+BEGIN;
+
+-- The unique index was built concurrently in migration 0029. Attaching it as a
+-- constraint is a short metadata operation and makes the physical invariant part
+-- of the table contract without rebuilding the index under a long write-blocking lock.
+ALTER TABLE accounting_reporting.trial_balance_snapshot
+    ADD CONSTRAINT trial_balance_snapshot_one_population_per_book_period
+    UNIQUE USING INDEX trial_balance_snapshot_one_population_per_book_period;
+
+-- Retained trial-balance values are accounting evidence, not three independently
+-- writable amounts. Add the row-local invariant without scanning inherited rows
+-- under this transaction's ADD-CONSTRAINT lock. Migration 0031 validates history
+-- in a separate autocommit statement after this transaction releases its locks.
+ALTER TABLE accounting_reporting.trial_balance_line
+    ADD CONSTRAINT trial_balance_line_net_balance_conservation
+    CHECK (net_balance_amount = debit_total_amount - credit_total_amount)
+    NOT VALID;
+
+CREATE OR REPLACE FUNCTION accounting_reporting.reject_trial_balance_snapshot_mutation()
+RETURNS trigger
+LANGUAGE plpgsql
+AS $$
+BEGIN
+    RAISE EXCEPTION
+        'hard-close trial balance evidence is immutable (trial_balance_snapshot_immutable)'
+        USING ERRCODE = 'check_violation';
+END;
+$$;
+
+CREATE TRIGGER trial_balance_snapshot_immutable_guard
+    BEFORE UPDATE OR DELETE
+    ON accounting_reporting.trial_balance_snapshot
+    FOR EACH ROW
+    EXECUTE FUNCTION accounting_reporting.reject_trial_balance_snapshot_mutation();
+
+CREATE OR REPLACE FUNCTION accounting_reporting.reject_trial_balance_line_mutation()
+RETURNS trigger
+LANGUAGE plpgsql
+AS $$
+BEGIN
+    RAISE EXCEPTION
+        'hard-close trial balance evidence is immutable (trial_balance_snapshot_immutable)'
+        USING ERRCODE = 'check_violation';
+END;
+$$;
+
+CREATE TRIGGER trial_balance_line_immutable_guard
+    BEFORE UPDATE OR DELETE
+    ON accounting_reporting.trial_balance_line
+    FOR EACH ROW
+    EXECUTE FUNCTION accounting_reporting.reject_trial_balance_line_mutation();
+
+CREATE OR REPLACE FUNCTION accounting_reporting.guard_trial_balance_snapshot_insert()
+RETURNS trigger
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = pg_catalog, pg_temp
+AS $$
+DECLARE
+    period_status_value text;
+    book_legal_entity_id uuid;
+    book_reporting_currency_code text;
+    close_command_lock_held boolean;
+BEGIN
+    SELECT accounting_book_period_control.period_status_code
+      INTO period_status_value
+      FROM accounting_core.accounting_book_period_control
+     WHERE accounting_book_period_control.tenant_account_id = NEW.tenant_account_id
+       AND accounting_book_period_control.accounting_book_id = NEW.accounting_book_id
+       AND accounting_book_period_control.fiscal_period_id = NEW.fiscal_period_id
+     FOR UPDATE;
+
+    IF period_status_value IS NULL THEN
+        RAISE EXCEPTION
+            'trial balance snapshot has no matching book-period authority (trial_balance_snapshot_scope_missing)'
+            USING ERRCODE = 'check_violation';
+    END IF;
+
+    SELECT accounting_book.legal_entity_id,
+           accounting_book.reporting_currency_code
+      INTO book_legal_entity_id,
+           book_reporting_currency_code
+      FROM accounting_core.accounting_book
+     WHERE accounting_book.tenant_account_id = NEW.tenant_account_id
+       AND accounting_book.accounting_book_id = NEW.accounting_book_id;
+
+    IF book_legal_entity_id IS NOT NULL
+       AND book_legal_entity_id IS DISTINCT FROM NEW.legal_entity_id THEN
+        RAISE EXCEPTION
+            'trial balance snapshot legal entity must own the accounting book (trial_balance_snapshot_book_entity_mismatch)'
+            USING ERRCODE = 'check_violation';
+    END IF;
+
+    IF book_reporting_currency_code IS NOT NULL
+       AND book_reporting_currency_code IS DISTINCT FROM NEW.snapshot_currency_code THEN
+        RAISE EXCEPTION
+            'trial balance snapshot currency must match the accounting book reporting currency (trial_balance_snapshot_currency_mismatch)'
+            USING ERRCODE = 'check_violation';
+    END IF;
+
+    IF period_status_value = 'hard_closed' THEN
+        RAISE EXCEPTION
+            'hard-close trial balance evidence is immutable (trial_balance_snapshot_immutable)'
+            USING ERRCODE = 'check_violation';
+    END IF;
+
+    -- The hard-close command always acquires this tenant/book/period advisory
+    -- lock before assembling close evidence. The lock remains present even when
+    -- zero net revenue/expense means no period-closing journal is emitted. A
+    -- caller-set journal_write_role GUC is therefore never snapshot authority.
+    SELECT EXISTS (
+        SELECT 1
+          FROM pg_catalog.pg_locks AS held_lock
+          JOIN accounting_core.tenant_account
+            ON tenant_account.tenant_account_id = NEW.tenant_account_id
+          JOIN accounting_core.accounting_book
+            ON accounting_book.tenant_account_id = NEW.tenant_account_id
+           AND accounting_book.accounting_book_id = NEW.accounting_book_id
+          JOIN accounting_core.fiscal_period
+            ON fiscal_period.tenant_account_id = NEW.tenant_account_id
+           AND fiscal_period.fiscal_period_id = NEW.fiscal_period_id
+         WHERE held_lock.locktype = 'advisory'
+           AND held_lock.pid = pg_backend_pid()
+           AND held_lock.database = (
+                SELECT pg_database.oid
+                  FROM pg_catalog.pg_database
+                 WHERE pg_database.datname = current_database()
+           )
+           AND held_lock.mode = 'ExclusiveLock'
+           AND held_lock.granted
+           AND held_lock.objsubid = 2
+           AND held_lock.classid::bigint = (
+                hashtext(tenant_account.tenant_account_code)::bigint & 4294967295
+           )
+           AND held_lock.objid::bigint = (
+                hashtext(
+                    'period:' || accounting_book.accounting_book_id::text || ':' || fiscal_period.period_code
+                )::bigint & 4294967295
+           )
+    ) INTO close_command_lock_held;
+
+    IF period_status_value <> 'soft_closed'
+       OR NOT pg_has_role(session_user, 'accounting_closing_writer', 'MEMBER')
+       OR NOT close_command_lock_held
+    THEN
+        RAISE EXCEPTION
+            'trial balance snapshot creation requires the purpose-limited hard-close writer (trial_balance_snapshot_authority_required)'
+            USING ERRCODE = 'check_violation';
+    END IF;
+
+    -- Snapshot chronology is an AIS system-time fact. A purpose-limited closing
+    -- writer may supply accounting evidence but cannot select the recording clock.
+    NEW.snapshot_generated_at := clock_timestamp();
+
+    IF EXISTS (
+        SELECT 1
+          FROM accounting_reporting.trial_balance_snapshot
+         WHERE trial_balance_snapshot.tenant_account_id = NEW.tenant_account_id
+           AND trial_balance_snapshot.accounting_book_id = NEW.accounting_book_id
+           AND trial_balance_snapshot.fiscal_period_id = NEW.fiscal_period_id
+    ) THEN
+        RAISE EXCEPTION
+            'trial balance snapshot population already occupies this book-period (trial_balance_snapshot_population_conflict)'
+            USING ERRCODE = 'check_violation';
+    END IF;
+
+    RETURN NEW;
+END;
+$$;
+
+REVOKE ALL ON FUNCTION accounting_reporting.guard_trial_balance_snapshot_insert()
+    FROM PUBLIC;
+
+CREATE TRIGGER trial_balance_snapshot_population_guard
+    BEFORE INSERT
+    ON accounting_reporting.trial_balance_snapshot
+    FOR EACH ROW
+    EXECUTE FUNCTION accounting_reporting.guard_trial_balance_snapshot_insert();
+
+CREATE OR REPLACE FUNCTION accounting_reporting.guard_trial_balance_line_insert()
+RETURNS trigger
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = pg_catalog, pg_temp
+AS $$
+DECLARE
+    period_status_value text;
+    snapshot_book_id uuid;
+    chart_account_book_id uuid;
+BEGIN
+    SELECT accounting_book_period_control.period_status_code,
+           trial_balance_snapshot.accounting_book_id
+      INTO period_status_value, snapshot_book_id
+      FROM accounting_reporting.trial_balance_snapshot
+      JOIN accounting_core.accounting_book_period_control
+        ON accounting_book_period_control.tenant_account_id
+           = trial_balance_snapshot.tenant_account_id
+       AND accounting_book_period_control.accounting_book_id
+           = trial_balance_snapshot.accounting_book_id
+       AND accounting_book_period_control.fiscal_period_id
+           = trial_balance_snapshot.fiscal_period_id
+     WHERE trial_balance_snapshot.tenant_account_id = NEW.tenant_account_id
+       AND trial_balance_snapshot.trial_balance_snapshot_id
+           = NEW.trial_balance_snapshot_id
+     FOR UPDATE OF accounting_book_period_control;
+
+    IF period_status_value IS NULL THEN
+        RAISE EXCEPTION
+            'trial balance snapshot has no matching book-period authority (trial_balance_snapshot_scope_missing)'
+            USING ERRCODE = 'check_violation';
+    END IF;
+
+    SELECT chart_account.accounting_book_id
+      INTO chart_account_book_id
+      FROM accounting_core.chart_account
+     WHERE chart_account.tenant_account_id = NEW.tenant_account_id
+       AND chart_account.chart_account_id = NEW.chart_account_id;
+
+    IF chart_account_book_id IS NOT NULL
+       AND snapshot_book_id IS DISTINCT FROM chart_account_book_id THEN
+        RAISE EXCEPTION
+            'trial balance line chart account must belong to the snapshot accounting book (trial_balance_line_book_scope_mismatch)'
+            USING ERRCODE = 'check_violation';
+    END IF;
+
+    IF period_status_value = 'hard_closed' THEN
+        RAISE EXCEPTION
+            'hard-close trial balance evidence is immutable (trial_balance_snapshot_immutable)'
+            USING ERRCODE = 'check_violation';
+    END IF;
+
+    RETURN NEW;
+END;
+$$;
+
+REVOKE ALL ON FUNCTION accounting_reporting.guard_trial_balance_line_insert()
+    FROM PUBLIC;
+
+CREATE TRIGGER trial_balance_line_population_guard
+    BEFORE INSERT
+    ON accounting_reporting.trial_balance_line
+    FOR EACH ROW
+    EXECUTE FUNCTION accounting_reporting.guard_trial_balance_line_insert();
+
+COMMIT;

database/migrations/0031_trial_balance_line_conservation_validation.sql

@@ -0,0 +1,2 @@
+ALTER TABLE accounting_reporting.trial_balance_line
+    VALIDATE CONSTRAINT trial_balance_line_net_balance_conservation;

database/migrations/0032_period_close_journal_population_fence.sql

@@ -0,0 +1,100 @@
+BEGIN;
+
+-- Journals admitted while a period is soft-closed change the authoritative
+-- population that hard close is about to freeze. Version those close-window
+-- writes on the same control row that hard close later locks. Ordinary open-
+-- period posting must not UPDATE that row on every journal: concurrent open
+-- posting instead holds a shared row lock so a period-state transition cannot
+-- overtake a journal that was admitted under the open-state contract.
+ALTER TABLE accounting_core.accounting_book_period_control
+    ADD COLUMN journal_population_revision bigint NOT NULL DEFAULT 0
+        CHECK (journal_population_revision >= 0);
+
+CREATE OR REPLACE FUNCTION accounting_core.guard_period_insert()
+RETURNS trigger
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = pg_catalog, pg_temp
+AS $$
+DECLARE
+    period_status_value text;
+    locked_period_status_value text;
+    journal_write_role_value text;
+BEGIN
+    SELECT accounting_book_period_control.period_status_code
+      INTO period_status_value
+      FROM accounting_core.accounting_book_period_control
+     WHERE accounting_book_period_control.tenant_account_id = NEW.tenant_account_id
+       AND accounting_book_period_control.accounting_book_id = NEW.accounting_book_id
+       AND accounting_book_period_control.fiscal_period_id = NEW.fiscal_period_id;
+
+    IF period_status_value IS NULL THEN
+        RAISE EXCEPTION
+            'accounting book fiscal period control is missing for this journal insert (period_control_missing)'
+            USING ERRCODE = 'check_violation';
+    END IF;
+
+    IF period_status_value = 'open' THEN
+        -- Many ordinary postings may share this row lock concurrently. A soft-close
+        -- UPDATE must wait for all journals admitted as open-period work to commit.
+        -- If the period changed while this statement waited, retry from a fresh
+        -- transaction rather than silently applying open-period authority to a
+        -- soft-closed period.
+        SELECT accounting_book_period_control.period_status_code
+          INTO locked_period_status_value
+          FROM accounting_core.accounting_book_period_control
+         WHERE accounting_book_period_control.tenant_account_id = NEW.tenant_account_id
+           AND accounting_book_period_control.accounting_book_id = NEW.accounting_book_id
+           AND accounting_book_period_control.fiscal_period_id = NEW.fiscal_period_id
+         FOR SHARE;
+
+        IF locked_period_status_value = 'open' THEN
+            RETURN NEW;
+        END IF;
+
+        RAISE EXCEPTION
+            'accounting book fiscal period changed during journal admission (period_state_changed_retry)'
+            USING ERRCODE = 'serialization_failure';
+    END IF;
+
+    journal_write_role_value := nullif(
+        current_setting('accounting_core.journal_write_role', true),
+        ''
+    );
+
+    IF period_status_value = 'soft_closed'
+       AND journal_write_role_value IN ('period_closing', 'adjusting', 'reversal')
+       AND pg_has_role(session_user, 'accounting_closing_writer', 'MEMBER')
+    THEN
+        -- Close-window journals are intentionally serialized on this revision.
+        -- If hard close already won the row, PostgreSQL either raises a serialization
+        -- failure under REPEATABLE READ or this predicate stops matching after wait.
+        locked_period_status_value := NULL;
+        UPDATE accounting_core.accounting_book_period_control
+           SET journal_population_revision = journal_population_revision + 1
+         WHERE tenant_account_id = NEW.tenant_account_id
+           AND accounting_book_id = NEW.accounting_book_id
+           AND fiscal_period_id = NEW.fiscal_period_id
+           AND period_status_code = 'soft_closed'
+         RETURNING period_status_code
+              INTO locked_period_status_value;
+
+        IF locked_period_status_value = 'soft_closed' THEN
+            RETURN NEW;
+        END IF;
+
+        RAISE EXCEPTION
+            'accounting book fiscal period changed during close-window journal admission (period_state_changed_retry)'
+            USING ERRCODE = 'serialization_failure';
+    END IF;
+
+    RAISE EXCEPTION
+        'Accounting book fiscal period is % (period_closed). Ordinary journals cannot be inserted after close. Post the AIS closing journal before hard-close; do not insert a later ordinary or reversal journal into a locked book period.',
+        period_status_value
+        USING ERRCODE = 'check_violation';
+END;
+$$;
+
+REVOKE ALL ON FUNCTION accounting_core.guard_period_insert() FROM PUBLIC;
+
+COMMIT;