@tailor-platform/erp-kit 0.6.0 → 0.8.0

package/src/modules/finance-ledger/command/generateTrialBalance.test.ts

@@ -0,0 +1,439 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  NoActiveChartOfAccountsError,
+  AccountingPeriodNotFoundError,
+  InvalidVariantError,
+  TrialBalanceImbalancedError,
+} from "../lib/errors.generated";
+import {
+  baseCompany,
+  baseChartOfAccounts,
+  baseAccountingPeriod,
+  baseAccount,
+  baseAccount2,
+  baseAccountGroup,
+  baseTrialBalance,
+  baseTrialBalanceLine,
+  revenueAccount,
+  expenseAccount,
+} from "../testing/fixtures";
+import { commandCtx, expectErr, expectOk } from "../testing/commandTestUtils";
+import { run, type GenerateTrialBalanceInput } from "./generateTrialBalance";
+
+const baseInput: GenerateTrialBalanceInput = {
+  companyId: baseCompany.id,
+  accountingPeriodId: baseAccountingPeriod.id,
+  variant: "PRE_CLOSE",
+};
+
+// Fixtures with accountGroupId for testing issue #1
+const accountWithGroup = {
+  ...baseAccount,
+  accountGroupId: baseAccountGroup.id,
+};
+
+const account2WithGroup = {
+  ...baseAccount2,
+  accountGroupId: null,
+};
+
+describe("generateTrialBalance", () => {
+  it("returns error when company has no active CoA", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(undefined); // ChartOfAccounts lookup
+
+    const result = await run(db, baseInput, commandCtx);
+
+    expectErr(result, NoActiveChartOfAccountsError);
+  });
+
+  it("returns error when accounting period not found", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseChartOfAccounts) // ChartOfAccounts lookup
+      .mockReturnValueOnce(undefined); // AccountingPeriod lookup
+
+    const result = await run(db, baseInput, commandCtx);
+
+    expectErr(result, AccountingPeriodNotFoundError);
+  });
+
+  it("returns error when variant is invalid", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseChartOfAccounts) // ChartOfAccounts lookup
+      .mockReturnValueOnce(baseAccountingPeriod); // AccountingPeriod lookup
+
+    const result = await run(db, { ...baseInput, variant: "INVALID" }, commandCtx);
+
+    expectErr(result, InvalidVariantError);
+  });
+
+  it("generates trial balance with correct balances for PRE_CLOSE", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+
+    const journalEntry = {
+      id: "je-1",
+      accountingPeriodId: baseAccountingPeriod.id,
+      status: "POSTED",
+      journalType: "MISCELLANEOUS",
+    };
+
+    const journalLine1 = {
+      id: "jl-1",
+      journalEntryId: "je-1",
+      accountId: baseAccount.id,
+      functionalDebitAmount: 5000,
+      functionalCreditAmount: null,
+    };
+
+    const journalLine2 = {
+      id: "jl-2",
+      journalEntryId: "je-1",
+      accountId: baseAccount2.id,
+      functionalDebitAmount: null,
+      functionalCreditAmount: 5000,
+    };
+
+    const insertedTrialBalance = {
+      ...baseTrialBalance,
+      id: "tb-new",
+      totalDebits: 5000,
+      totalCredits: 5000,
+    };
+
+    spies.select
+      .mockReturnValueOnce(baseChartOfAccounts) // ChartOfAccounts lookup
+      .mockReturnValueOnce(baseAccountingPeriod) // AccountingPeriod lookup
+      .mockImplementationOnce(() => [baseAccount, baseAccount2]) // accounts
+      .mockImplementationOnce(() => [journalEntry]) // journal entries
+      .mockImplementationOnce(() => [journalLine1, journalLine2]) // journal lines
+      .mockReturnValueOnce(undefined) // preceding period lookup (no preceding period)
+      .mockReturnValueOnce(undefined); // existingTrialBalance lookup (no prior TB for upsert)
+
+    spies.insert
+      .mockReturnValueOnce(insertedTrialBalance) // TrialBalance insert
+      .mockReturnValueOnce({ ...baseTrialBalanceLine, trialBalanceId: "tb-new" }) // line 1
+      .mockReturnValueOnce({
+        ...baseTrialBalanceLine,
+        trialBalanceId: "tb-new",
+        accountId: baseAccount2.id,
+      }); // line 2
+
+    const result = await run(db, baseInput, commandCtx);
+
+    const value = expectOk(result);
+    expect(value.trialBalance.totalDebits).toBe(5000);
+    expect(value.trialBalance.totalCredits).toBe(5000);
+    expect(value.trialBalance.id).toBe("tb-new");
+  });
+
+  it("includes zero-balance accounts from active CoA", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+
+    // No journal entries at all — all accounts should still appear
+    const insertedTrialBalance = {
+      ...baseTrialBalance,
+      id: "tb-zero",
+      totalDebits: 0,
+      totalCredits: 0,
+    };
+
+    spies.select
+      .mockReturnValueOnce(baseChartOfAccounts) // ChartOfAccounts lookup
+      .mockReturnValueOnce(baseAccountingPeriod) // AccountingPeriod lookup
+      .mockImplementationOnce(() => [baseAccount, baseAccount2]) // accounts (both active)
+      .mockImplementationOnce(() => []) // journal entries (none)
+      .mockImplementationOnce(() => []) // journal lines (none)
+      .mockReturnValueOnce(undefined) // preceding period lookup (no preceding period)
+      .mockReturnValueOnce(undefined); // existingTrialBalance lookup (no prior TB for upsert)
+
+    spies.insert
+      .mockReturnValueOnce(insertedTrialBalance) // TrialBalance insert
+      .mockReturnValueOnce({}) // line 1 insert
+      .mockReturnValueOnce({}); // line 2 insert
+
+    const result = await run(db, baseInput, commandCtx);
+
+    const value = expectOk(result);
+    expect(value.trialBalance.totalDebits).toBe(0);
+    expect(value.trialBalance.totalCredits).toBe(0);
+    // Verify insert was called: 1 for TB + 2 for TB lines (one per account)
+    expect(spies.insert).toHaveBeenCalledTimes(3);
+  });
+
+  it("returns error when trial balance is imbalanced", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+
+    // Create journal lines where debits != credits (imbalanced data)
+    const journalEntry = {
+      id: "je-1",
+      accountingPeriodId: baseAccountingPeriod.id,
+      status: "POSTED",
+      journalType: "MISCELLANEOUS",
+    };
+
+    const journalLine1 = {
+      id: "jl-1",
+      journalEntryId: "je-1",
+      accountId: baseAccount.id,
+      functionalDebitAmount: 5000,
+      functionalCreditAmount: null,
+    };
+
+    const journalLine2 = {
+      id: "jl-2",
+      journalEntryId: "je-1",
+      accountId: baseAccount2.id,
+      functionalDebitAmount: null,
+      functionalCreditAmount: 3000, // intentionally imbalanced
+    };
+
+    spies.select
+      .mockReturnValueOnce(baseChartOfAccounts) // ChartOfAccounts lookup
+      .mockReturnValueOnce(baseAccountingPeriod) // AccountingPeriod lookup
+      .mockImplementationOnce(() => [baseAccount, baseAccount2]) // accounts
+      .mockImplementationOnce(() => [journalEntry]) // journal entries
+      .mockImplementationOnce(() => [journalLine1, journalLine2]) // journal lines
+      .mockReturnValueOnce(undefined); // preceding period lookup (no preceding period)
+
+    const result = await run(db, baseInput, commandCtx);
+
+    expectErr(result, TrialBalanceImbalancedError);
+  });
+
+  it("emits audit event with correct actor and trial balance details", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+
+    const insertedTrialBalance = {
+      ...baseTrialBalance,
+      id: "tb-audit",
+      totalDebits: 0,
+      totalCredits: 0,
+    };
+
+    spies.select
+      .mockReturnValueOnce(baseChartOfAccounts) // ChartOfAccounts lookup
+      .mockReturnValueOnce(baseAccountingPeriod) // AccountingPeriod lookup
+      .mockImplementationOnce(() => [baseAccount, baseAccount2]) // accounts
+      .mockImplementationOnce(() => []) // journal entries
+      .mockImplementationOnce(() => []) // journal lines
+      .mockReturnValueOnce(undefined) // preceding period lookup (no preceding period)
+      .mockReturnValueOnce(undefined); // existingTrialBalance lookup (no prior TB for upsert)
+
+    spies.insert
+      .mockReturnValueOnce(insertedTrialBalance)
+      .mockReturnValueOnce({})
+      .mockReturnValueOnce({});
+
+    const result = await run(db, baseInput, commandCtx);
+
+    const value = expectOk(result);
+    expect(value.auditEvent).toBeDefined();
+    expect(value.auditEvent.type).toBe("TRIAL_BALANCE_GENERATED");
+    expect(value.auditEvent.actorId).toBe(commandCtx.actorId);
+    expect(value.auditEvent.timestamp).toBeInstanceOf(Date);
+    expect(value.auditEvent.trialBalanceId).toBe("tb-audit");
+    expect(value.auditEvent.variant).toBe("PRE_CLOSE");
+    expect(value.auditEvent.isBalanced).toBe(true);
+  });
+
+  it("uses accountGroupId from Account record when available", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+
+    const insertedTrialBalance = {
+      ...baseTrialBalance,
+      id: "tb-group",
+      totalDebits: 0,
+      totalCredits: 0,
+    };
+
+    spies.select
+      .mockReturnValueOnce(baseChartOfAccounts) // ChartOfAccounts lookup
+      .mockReturnValueOnce(baseAccountingPeriod) // AccountingPeriod lookup
+      .mockImplementationOnce(() => [accountWithGroup, account2WithGroup]) // accounts with groupId
+      .mockImplementationOnce(() => []) // journal entries
+      .mockImplementationOnce(() => []) // journal lines
+      .mockReturnValueOnce(undefined) // preceding period lookup (no preceding period)
+      .mockReturnValueOnce(undefined); // existingTrialBalance lookup
+
+    spies.insert
+      .mockReturnValueOnce(insertedTrialBalance)
+      .mockReturnValueOnce({})
+      .mockReturnValueOnce({});
+
+    const result = await run(db, baseInput, commandCtx);
+
+    expectOk(result);
+
+    // The first line insert should pass accountGroupId from the account fixture
+    const firstLineValues = spies.values.mock.calls.find(
+      (call: unknown[]) =>
+        call[0] &&
+        typeof call[0] === "object" &&
+        "accountGroupId" in (call[0] as Record<string, unknown>) &&
+        (call[0] as Record<string, unknown>).accountGroupId === baseAccountGroup.id,
+    );
+    expect(firstLineValues).toBeDefined();
+  });
+
+  it("zeros closing balances for revenue and expense accounts in POST_CLOSE variant", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+
+    const postCloseInput: GenerateTrialBalanceInput = {
+      ...baseInput,
+      variant: "POST_CLOSE",
+    };
+
+    // Revenue account: 3000 debit, 8000 credit → closingBalance would be -5000 but POST_CLOSE zeros it
+    // Expense account: 4000 debit, 4000 credit → balanced, still zeroed for POST_CLOSE
+    // Asset account: 8000 debit, 3000 credit → not zeroed
+    const journalEntry = {
+      id: "je-post",
+      accountingPeriodId: baseAccountingPeriod.id,
+      status: "POSTED",
+      journalType: "CLOSING",
+    };
+
+    const revenueJournalLine = {
+      id: "jl-rev",
+      journalEntryId: "je-post",
+      accountId: revenueAccount.id,
+      functionalDebitAmount: 3000,
+      functionalCreditAmount: null,
+    };
+
+    const expenseJournalLine = {
+      id: "jl-exp",
+      journalEntryId: "je-post",
+      accountId: expenseAccount.id,
+      functionalDebitAmount: null,
+      functionalCreditAmount: 3000,
+    };
+
+    // Total debits = 3000, total credits = 3000 — balanced
+    const insertedTrialBalance = {
+      ...baseTrialBalance,
+      id: "tb-post-close",
+      variant: "POST_CLOSE" as const,
+      totalDebits: 3000,
+      totalCredits: 3000,
+    };
+
+    spies.select
+      .mockReturnValueOnce(baseChartOfAccounts) // ChartOfAccounts lookup
+      .mockReturnValueOnce(baseAccountingPeriod) // AccountingPeriod lookup
+      .mockImplementationOnce(() => [revenueAccount, expenseAccount]) // accounts
+      .mockImplementationOnce(() => [journalEntry]) // journal entries (CLOSING included for POST_CLOSE)
+      .mockImplementationOnce(() => [revenueJournalLine, expenseJournalLine]) // journal lines
+      .mockReturnValueOnce(undefined) // preceding period lookup (no preceding period)
+      .mockReturnValueOnce(undefined); // existingTrialBalance lookup
+
+    spies.insert
+      .mockReturnValueOnce(insertedTrialBalance)
+      .mockReturnValueOnce({})
+      .mockReturnValueOnce({});
+
+    const result = await run(db, postCloseInput, commandCtx);
+
+    expectOk(result);
+
+    // Verify that TrialBalanceLine inserts have closingBalance = 0 for REVENUE/EXPENSE accounts
+    const lineInsertCalls = spies.values.mock.calls.filter(
+      (call: unknown[]) =>
+        call[0] &&
+        typeof call[0] === "object" &&
+        "closingBalance" in (call[0] as Record<string, unknown>),
+    );
+    expect(lineInsertCalls.length).toBe(2);
+    for (const call of lineInsertCalls) {
+      expect((call[0] as Record<string, unknown>).closingBalance).toBe(0);
+    }
+  });
+
+  it("deletes existing TrialBalance before inserting when regenerating for same period and variant", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+
+    const existingTb = {
+      ...baseTrialBalance,
+      id: "tb-existing",
+    };
+
+    const insertedTrialBalance = {
+      ...baseTrialBalance,
+      id: "tb-regenerated",
+      totalDebits: 0,
+      totalCredits: 0,
+    };
+
+    spies.select
+      .mockReturnValueOnce(baseChartOfAccounts) // ChartOfAccounts lookup
+      .mockReturnValueOnce(baseAccountingPeriod) // AccountingPeriod lookup
+      .mockImplementationOnce(() => [baseAccount, baseAccount2]) // accounts
+      .mockImplementationOnce(() => []) // journal entries
+      .mockImplementationOnce(() => []) // journal lines
+      .mockReturnValueOnce(undefined) // preceding period lookup (no preceding period)
+      .mockReturnValueOnce(existingTb); // existingTrialBalance lookup — found!
+
+    spies.insert
+      .mockReturnValueOnce(insertedTrialBalance)
+      .mockReturnValueOnce({})
+      .mockReturnValueOnce({});
+
+    const result = await run(db, baseInput, commandCtx);
+
+    expectOk(result);
+
+    // delete spy should have been called twice: once for TrialBalanceLine, once for TrialBalance
+    expect(spies.delete).toHaveBeenCalledTimes(2);
+    // New trial balance should be inserted fresh
+    expect(spies.insert).toHaveBeenCalledTimes(3); // 1 TB + 2 lines
+  });
+
+  it("sorts trial balance lines by account code ascending", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+
+    // Provide accounts out of order — code "2000" before "1000"
+    const insertedTrialBalance = {
+      ...baseTrialBalance,
+      id: "tb-sorted",
+      totalDebits: 0,
+      totalCredits: 0,
+    };
+
+    spies.select
+      .mockReturnValueOnce(baseChartOfAccounts) // ChartOfAccounts lookup
+      .mockReturnValueOnce(baseAccountingPeriod) // AccountingPeriod lookup
+      .mockImplementationOnce(() => [baseAccount2, baseAccount]) // accounts: "2000" first, then "1000"
+      .mockImplementationOnce(() => []) // journal entries
+      .mockImplementationOnce(() => []) // journal lines
+      .mockReturnValueOnce(undefined) // preceding period lookup (no preceding period)
+      .mockReturnValueOnce(undefined); // existingTrialBalance lookup
+
+    spies.insert
+      .mockReturnValueOnce(insertedTrialBalance)
+      .mockReturnValueOnce({})
+      .mockReturnValueOnce({});
+
+    const result = await run(db, baseInput, commandCtx);
+
+    expectOk(result);
+
+    // The first TrialBalanceLine insert should be for account code "1000" (sortOrder: 1)
+    // and second for "2000" (sortOrder: 2)
+    const lineInsertCalls = spies.values.mock.calls.filter(
+      (call: unknown[]) =>
+        call[0] &&
+        typeof call[0] === "object" &&
+        "sortOrder" in (call[0] as Record<string, unknown>),
+    );
+
+    expect(lineInsertCalls.length).toBe(2);
+    expect((lineInsertCalls[0][0] as Record<string, unknown>).accountCode).toBe("1000");
+    expect((lineInsertCalls[0][0] as Record<string, unknown>).sortOrder).toBe(1);
+    expect((lineInsertCalls[1][0] as Record<string, unknown>).accountCode).toBe("2000");
+    expect((lineInsertCalls[1][0] as Record<string, unknown>).sortOrder).toBe(2);
+  });
+});

package/src/modules/finance-ledger/command/generateTrialBalance.ts

@@ -0,0 +1,268 @@
+import { err, ok, type CommandContext } from "@tailor-platform/erp-kit/module";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  NoActiveChartOfAccountsError,
+  AccountingPeriodNotFoundError,
+  InvalidVariantError,
+  TrialBalanceImbalancedError,
+} from "../lib/errors.generated";
+
+export interface GenerateTrialBalanceInput {
+  companyId: string;
+  accountingPeriodId: string;
+  variant: string;
+}
+
+const VALID_VARIANTS = ["PRE_CLOSE", "POST_CLOSE"] as const;
+
+/**
+ * Function: generateTrialBalance
+ *
+ * Creates a point-in-time snapshot report of GL account balances for a specific
+ * accounting period. Includes opening balance, period debits, credits, closing
+ * balance for each account organized by account group hierarchy. Supports
+ * PRE_CLOSE and POST_CLOSE variants.
+ */
+export async function run(db: Transaction, input: GenerateTrialBalanceInput, ctx: CommandContext) {
+  const { companyId, accountingPeriodId, variant } = input;
+
+  // 1. Find the active ChartOfAccounts for the company
+  const chartOfAccounts = await db
+    .selectFrom("ChartOfAccounts")
+    .selectAll()
+    .where("companyId", "=", companyId)
+    .where("status", "=", "ACTIVE")
+    .executeTakeFirst();
+
+  if (!chartOfAccounts) {
+    return err(new NoActiveChartOfAccountsError(companyId));
+  }
+
+  // 2. Find the AccountingPeriod
+  const accountingPeriod = await db
+    .selectFrom("AccountingPeriod")
+    .selectAll()
+    .where("id", "=", accountingPeriodId)
+    .executeTakeFirst();
+
+  if (!accountingPeriod) {
+    return err(new AccountingPeriodNotFoundError(accountingPeriodId));
+  }
+
+  // 3. Validate variant is PRE_CLOSE or POST_CLOSE
+  if (!VALID_VARIANTS.includes(variant as (typeof VALID_VARIANTS)[number])) {
+    return err(new InvalidVariantError(variant));
+  }
+
+  // 4. Fetch all accounts from the CoA, sorted by account code ascending
+  const accountsRaw = await db
+    .selectFrom("Account")
+    .selectAll()
+    .where("status", "=", "ACTIVE")
+    .execute();
+
+  const accounts = [
+    ...(accountsRaw as {
+      id: string;
+      code: string | null;
+      name: string | null;
+      classification: string | null;
+      accountGroupId?: string | null;
+    }[]),
+  ].sort((a, b) => (a.code ?? "").localeCompare(b.code ?? ""));
+
+  // 5. Fetch posted journal lines for the period
+  const journalEntries = await db
+    .selectFrom("JournalEntry")
+    .selectAll()
+    .where("accountingPeriodId", "=", accountingPeriodId)
+    .where("status", "=", "POSTED")
+    .execute();
+
+  // 6. For PRE_CLOSE, exclude CLOSING journal type entries; for POST_CLOSE include all
+  const filteredEntries =
+    variant === "PRE_CLOSE"
+      ? journalEntries.filter((e: { journalType: string }) => e.journalType !== "CLOSING")
+      : journalEntries;
+
+  const entryIds = new Set(filteredEntries.map((e: { id: string }) => e.id));
+
+  const allJournalLines = await db
+    .selectFrom("JournalLine")
+    .selectAll()
+    .where("journalEntryId", "in", [...entryIds])
+    .execute();
+
+  const journalLines = allJournalLines.filter((line: { journalEntryId: string }) =>
+    entryIds.has(line.journalEntryId),
+  );
+
+  // 7. Fetch opening balances from the immediately preceding period's trial balance
+  const precedingPeriod = await db
+    .selectFrom("AccountingPeriod")
+    .selectAll()
+    .where("companyId", "=", companyId)
+    .where("endDate", "<", accountingPeriod.startDate)
+    .orderBy("endDate", "desc")
+    .executeTakeFirst();
+
+  const priorBalanceByAccount = new Map<string, number>();
+
+  if (precedingPeriod) {
+    const precedingTrialBalance = await db
+      .selectFrom("TrialBalance")
+      .selectAll()
+      .where("companyId", "=", companyId)
+      .where("chartOfAccountsId", "=", chartOfAccounts.id)
+      .where("accountingPeriodId", "=", precedingPeriod.id)
+      .where("variant", "=", variant as "PRE_CLOSE" | "POST_CLOSE")
+      .executeTakeFirst();
+
+    if (precedingTrialBalance) {
+      const priorLines = await db
+        .selectFrom("TrialBalanceLine")
+        .selectAll()
+        .where("trialBalanceId", "=", precedingTrialBalance.id)
+        .execute();
+
+      for (const line of priorLines) {
+        priorBalanceByAccount.set(line.accountId, line.closingBalance ?? 0);
+      }
+    }
+  }
+
+  // Calculate per-account balances
+  const linesByAccount = new Map<string, { debits: number; credits: number }>();
+  for (const line of journalLines) {
+    const accountId = line.accountId;
+    const current = linesByAccount.get(accountId) ?? { debits: 0, credits: 0 };
+    current.debits += line.functionalDebitAmount ?? 0;
+    current.credits += line.functionalCreditAmount ?? 0;
+    linesByAccount.set(accountId, current);
+  }
+
+  // Build trial balance lines for all accounts (including zero-balance),
+  // accounts are already sorted by code ascending.
+  let totalDebits = 0;
+  let totalCredits = 0;
+
+  const trialBalanceLines = accounts.map(
+    (
+      account: {
+        id: string;
+        code: string | null;
+        name: string | null;
+        classification: string | null;
+        accountGroupId?: string | null;
+      },
+      index: number,
+    ) => {
+      const openingBalance = priorBalanceByAccount.get(account.id) ?? 0;
+      const periodData = linesByAccount.get(account.id) ?? { debits: 0, credits: 0 };
+      const periodDebits = periodData.debits;
+      const periodCredits = periodData.credits;
+      let closingBalance = openingBalance + periodDebits - periodCredits;
+
+      // POST_CLOSE variant: zero out balances for temporary accounts (revenue and expense)
+      if (
+        variant === "POST_CLOSE" &&
+        (account.classification === "REVENUE" || account.classification === "EXPENSE")
+      ) {
+        closingBalance = 0;
+      }
+
+      totalDebits += periodDebits;
+      totalCredits += periodCredits;
+
+      return {
+        accountId: account.id,
+        accountGroupId: account.accountGroupId ?? null,
+        accountCode: account.code ?? "",
+        accountName: account.name ?? "",
+        openingBalance,
+        periodDebits,
+        periodCredits,
+        closingBalance,
+        sortOrder: index + 1,
+      };
+    },
+  );
+
+  // 8. Check equilibrium: totalDebits == totalCredits
+  if (totalDebits !== totalCredits) {
+    const discrepancy = Math.abs(totalDebits - totalCredits);
+    return err(new TrialBalanceImbalancedError(`${companyId} (discrepancy: ${discrepancy})`));
+  }
+
+  // 9. Upsert: delete existing TrialBalance (and lines) for same period/variant if any
+  const existingTrialBalance = await db
+    .selectFrom("TrialBalance")
+    .selectAll()
+    .where("companyId", "=", companyId)
+    .where("accountingPeriodId", "=", accountingPeriodId)
+    .where("chartOfAccountsId", "=", chartOfAccounts.id)
+    .where("variant", "=", variant as "PRE_CLOSE" | "POST_CLOSE")
+    .executeTakeFirst();
+
+  if (existingTrialBalance) {
+    await db
+      .deleteFrom("TrialBalanceLine")
+      .where("trialBalanceId", "=", existingTrialBalance.id)
+      .execute();
+
+    await db.deleteFrom("TrialBalance").where("id", "=", existingTrialBalance.id).execute();
+  }
+
+  // 10. Insert TrialBalance record
+  const now = new Date();
+  const trialBalance = await db
+    .insertInto("TrialBalance")
+    .values({
+      companyId,
+      accountingPeriodId,
+      chartOfAccountsId: chartOfAccounts.id,
+      variant: variant as "PRE_CLOSE" | "POST_CLOSE",
+      generatedAt: now,
+      totalDebits,
+      totalCredits,
+      isBalanced: true,
+      updatedAt: null,
+    })
+    .returningAll()
+    .executeTakeFirstOrThrow();
+
+  // 11. Insert TrialBalanceLine records for each account
+  for (const line of trialBalanceLines) {
+    await db
+      .insertInto("TrialBalanceLine")
+      .values({
+        trialBalanceId: trialBalance.id,
+        accountId: line.accountId,
+        accountGroupId: line.accountGroupId,
+        accountCode: line.accountCode,
+        accountName: line.accountName,
+        openingBalance: line.openingBalance,
+        periodDebits: line.periodDebits,
+        periodCredits: line.periodCredits,
+        closingBalance: line.closingBalance,
+        sortOrder: line.sortOrder,
+        updatedAt: null,
+      })
+      .returningAll()
+      .executeTakeFirstOrThrow();
+  }
+
+  // 12. Emit audit event and return
+  const auditEvent = {
+    type: "TRIAL_BALANCE_GENERATED",
+    variant,
+    actorId: ctx.actorId,
+    timestamp: now,
+    trialBalanceId: trialBalance.id,
+    totalDebits,
+    totalCredits,
+    isBalanced: true,
+  };
+
+  return ok({ trialBalance, auditEvent });
+}