@accounter/server 0.0.9-alpha-20251231123714-6cdd9de71b4672d74ece5d34c438d162987b2c93 → 0.0.9-alpha-20251231163357-33d4c33fec5e21dad2e04d1f293f6248d2550588

package/src/demo-fixtures/use-cases/expenses/monthly-expense-foreign-currency.ts

@@ -0,0 +1,377 @@
+import type { UseCaseSpec } from '../../../fixtures/fixture-spec.js';
+import { CountryCode, Currency } from '../../../shared/enums.js';
+import { makeUUID } from '../../helpers/deterministic-uuid.js';
+
+/**
+ * Monthly Expense Use-Case: Foreign Currency Transaction
+ *
+ * Demonstrates a US-based supplier invoice paid via bank transfer with
+ * exchange rate conversion from USD to ILS. This use-case validates:
+ * - Foreign currency transaction handling
+ * - Exchange rate application
+ * - Cross-border payment processing
+ * - Ledger generation with currency conversion
+ */
+export const monthlyExpenseForeignCurrency: UseCaseSpec = {
+  id: 'monthly-expense-foreign-currency',
+  name: 'Monthly Expense (Foreign Currency)',
+  description:
+    'US-based supplier invoice paid via bank transfer with exchange rate conversion from USD to ILS. Validates foreign currency handling and ledger generation.',
+  category: 'expenses',
+  fixtures: {
+    businesses: [
+      {
+        id: makeUUID('business', 'us-supplier-acme-llc'),
+        name: 'Acme Consulting LLC',
+        country: CountryCode['United States of America (the)'],
+        canSettleWithReceipt: false,
+      },
+    ],
+    taxCategories: [
+      {
+        id: makeUUID('tax-category', 'consulting-expenses'),
+        name: 'Consulting Expenses',
+      },
+    ],
+    financialAccounts: [
+      {
+        id: makeUUID('financial-account', 'bank-usd-account'),
+        accountNumber: '123-456-7890',
+        type: 'BANK_ACCOUNT',
+        currency: Currency.Usd,
+        taxCategoryMappings: [
+          {
+            taxCategoryId: makeUUID('tax-category', 'consulting-expenses'),
+            currency: Currency.Usd,
+          },
+        ],
+      },
+    ],
+    charges: [
+      {
+        id: makeUUID('charge', 'consulting-invoice-2024-01'),
+        ownerId: '{{ADMIN_BUSINESS_ID}}',
+        userDescription: 'January consulting services',
+      },
+      {
+        id: makeUUID('charge', 'consulting-invoice-2024-02'),
+        ownerId: '{{ADMIN_BUSINESS_ID}}',
+        userDescription: 'February consulting services',
+      },
+      {
+        id: makeUUID('charge', 'consulting-invoice-2024-03'),
+        ownerId: '{{ADMIN_BUSINESS_ID}}',
+        userDescription: 'March consulting services',
+      },
+      {
+        id: makeUUID('charge', 'consulting-invoice-2024-04'),
+        ownerId: '{{ADMIN_BUSINESS_ID}}',
+        userDescription: 'April consulting services',
+      },
+      {
+        id: makeUUID('charge', 'consulting-invoice-2024-05'),
+        ownerId: '{{ADMIN_BUSINESS_ID}}',
+        userDescription: 'May consulting services',
+      },
+      {
+        id: makeUUID('charge', 'consulting-invoice-2024-06'),
+        ownerId: '{{ADMIN_BUSINESS_ID}}',
+        userDescription: 'June consulting services',
+      },
+      {
+        id: makeUUID('charge', 'consulting-invoice-2024-07'),
+        ownerId: '{{ADMIN_BUSINESS_ID}}',
+        userDescription: 'July consulting services',
+      },
+      {
+        id: makeUUID('charge', 'consulting-invoice-2024-08'),
+        ownerId: '{{ADMIN_BUSINESS_ID}}',
+        userDescription: 'August consulting services',
+      },
+      {
+        id: makeUUID('charge', 'consulting-invoice-2024-09'),
+        ownerId: '{{ADMIN_BUSINESS_ID}}',
+        userDescription: 'September consulting services',
+      },
+      {
+        id: makeUUID('charge', 'consulting-invoice-2024-10'),
+        ownerId: '{{ADMIN_BUSINESS_ID}}',
+        userDescription: 'October consulting services',
+      },
+      {
+        id: makeUUID('charge', 'consulting-invoice-2024-11'),
+        ownerId: '{{ADMIN_BUSINESS_ID}}',
+        userDescription: 'November consulting services',
+      },
+      {
+        id: makeUUID('charge', 'consulting-invoice-2024-12'),
+        ownerId: '{{ADMIN_BUSINESS_ID}}',
+        userDescription: 'December consulting services',
+      },
+    ],
+    transactions: [
+      {
+        id: makeUUID('transaction', 'consulting-payment-usd-01'),
+        chargeId: makeUUID('charge', 'consulting-invoice-2024-01'),
+        businessId: makeUUID('business', 'us-supplier-acme-llc'),
+        amount: '-500.00',
+        currency: Currency.Usd,
+        eventDate: '2024-01-15',
+        debitDate: '2024-01-15',
+        accountNumber: '123-456-7890',
+      },
+      {
+        id: makeUUID('transaction', 'consulting-payment-usd-02'),
+        chargeId: makeUUID('charge', 'consulting-invoice-2024-02'),
+        businessId: makeUUID('business', 'us-supplier-acme-llc'),
+        amount: '-500.00',
+        currency: Currency.Usd,
+        eventDate: '2024-02-15',
+        debitDate: '2024-02-15',
+        accountNumber: '123-456-7890',
+      },
+      {
+        id: makeUUID('transaction', 'consulting-payment-usd-03'),
+        chargeId: makeUUID('charge', 'consulting-invoice-2024-03'),
+        businessId: makeUUID('business', 'us-supplier-acme-llc'),
+        amount: '-500.00',
+        currency: Currency.Usd,
+        eventDate: '2024-03-15',
+        debitDate: '2024-03-15',
+        accountNumber: '123-456-7890',
+      },
+      {
+        id: makeUUID('transaction', 'consulting-payment-usd-04'),
+        chargeId: makeUUID('charge', 'consulting-invoice-2024-04'),
+        businessId: makeUUID('business', 'us-supplier-acme-llc'),
+        amount: '-500.00',
+        currency: Currency.Usd,
+        eventDate: '2024-04-15',
+        debitDate: '2024-04-15',
+        accountNumber: '123-456-7890',
+      },
+      {
+        id: makeUUID('transaction', 'consulting-payment-usd-05'),
+        chargeId: makeUUID('charge', 'consulting-invoice-2024-05'),
+        businessId: makeUUID('business', 'us-supplier-acme-llc'),
+        amount: '-500.00',
+        currency: Currency.Usd,
+        eventDate: '2024-05-15',
+        debitDate: '2024-05-15',
+        accountNumber: '123-456-7890',
+      },
+      {
+        id: makeUUID('transaction', 'consulting-payment-usd-06'),
+        chargeId: makeUUID('charge', 'consulting-invoice-2024-06'),
+        businessId: makeUUID('business', 'us-supplier-acme-llc'),
+        amount: '-500.00',
+        currency: Currency.Usd,
+        eventDate: '2024-06-15',
+        debitDate: '2024-06-15',
+        accountNumber: '123-456-7890',
+      },
+      {
+        id: makeUUID('transaction', 'consulting-payment-usd-07'),
+        chargeId: makeUUID('charge', 'consulting-invoice-2024-07'),
+        businessId: makeUUID('business', 'us-supplier-acme-llc'),
+        amount: '-500.00',
+        currency: Currency.Usd,
+        eventDate: '2024-07-15',
+        debitDate: '2024-07-15',
+        accountNumber: '123-456-7890',
+      },
+      {
+        id: makeUUID('transaction', 'consulting-payment-usd-08'),
+        chargeId: makeUUID('charge', 'consulting-invoice-2024-08'),
+        businessId: makeUUID('business', 'us-supplier-acme-llc'),
+        amount: '-500.00',
+        currency: Currency.Usd,
+        eventDate: '2024-08-15',
+        debitDate: '2024-08-15',
+        accountNumber: '123-456-7890',
+      },
+      {
+        id: makeUUID('transaction', 'consulting-payment-usd-09'),
+        chargeId: makeUUID('charge', 'consulting-invoice-2024-09'),
+        businessId: makeUUID('business', 'us-supplier-acme-llc'),
+        amount: '-500.00',
+        currency: Currency.Usd,
+        eventDate: '2024-09-15',
+        debitDate: '2024-09-15',
+        accountNumber: '123-456-7890',
+      },
+      {
+        id: makeUUID('transaction', 'consulting-payment-usd-10'),
+        chargeId: makeUUID('charge', 'consulting-invoice-2024-10'),
+        businessId: makeUUID('business', 'us-supplier-acme-llc'),
+        amount: '-500.00',
+        currency: Currency.Usd,
+        eventDate: '2024-10-15',
+        debitDate: '2024-10-15',
+        accountNumber: '123-456-7890',
+      },
+      {
+        id: makeUUID('transaction', 'consulting-payment-usd-11'),
+        chargeId: makeUUID('charge', 'consulting-invoice-2024-11'),
+        businessId: makeUUID('business', 'us-supplier-acme-llc'),
+        amount: '-500.00',
+        currency: Currency.Usd,
+        eventDate: '2024-11-15',
+        debitDate: '2024-11-15',
+        accountNumber: '123-456-7890',
+      },
+      {
+        id: makeUUID('transaction', 'consulting-payment-usd-12'),
+        chargeId: makeUUID('charge', 'consulting-invoice-2024-12'),
+        businessId: makeUUID('business', 'us-supplier-acme-llc'),
+        amount: '-500.00',
+        currency: Currency.Usd,
+        eventDate: '2024-12-15',
+        debitDate: '2024-12-15',
+        accountNumber: '123-456-7890',
+      },
+    ],
+    documents: [
+      {
+        id: makeUUID('document', 'consulting-invoice-inv-2024-01-15'),
+        chargeId: makeUUID('charge', 'consulting-invoice-2024-01'),
+        creditorId: makeUUID('business', 'us-supplier-acme-llc'),
+        debtorId: '{{ADMIN_BUSINESS_ID}}',
+        serialNumber: 'INV-2024-01-15',
+        type: 'INVOICE',
+        date: '2024-01-01',
+        totalAmount: '500.00',
+        currencyCode: Currency.Usd,
+      },
+      {
+        id: makeUUID('document', 'consulting-invoice-inv-2024-02-15'),
+        chargeId: makeUUID('charge', 'consulting-invoice-2024-02'),
+        creditorId: makeUUID('business', 'us-supplier-acme-llc'),
+        debtorId: '{{ADMIN_BUSINESS_ID}}',
+        serialNumber: 'INV-2024-02-15',
+        type: 'INVOICE',
+        date: '2024-02-01',
+        totalAmount: '500.00',
+        currencyCode: Currency.Usd,
+      },
+      {
+        id: makeUUID('document', 'consulting-invoice-inv-2024-03-15'),
+        chargeId: makeUUID('charge', 'consulting-invoice-2024-03'),
+        creditorId: makeUUID('business', 'us-supplier-acme-llc'),
+        debtorId: '{{ADMIN_BUSINESS_ID}}',
+        serialNumber: 'INV-2024-03-15',
+        type: 'INVOICE',
+        date: '2024-03-01',
+        totalAmount: '500.00',
+        currencyCode: Currency.Usd,
+      },
+      {
+        id: makeUUID('document', 'consulting-invoice-inv-2024-04-15'),
+        chargeId: makeUUID('charge', 'consulting-invoice-2024-04'),
+        creditorId: makeUUID('business', 'us-supplier-acme-llc'),
+        debtorId: '{{ADMIN_BUSINESS_ID}}',
+        serialNumber: 'INV-2024-04-15',
+        type: 'INVOICE',
+        date: '2024-04-01',
+        totalAmount: '500.00',
+        currencyCode: Currency.Usd,
+      },
+      {
+        id: makeUUID('document', 'consulting-invoice-inv-2024-05-15'),
+        chargeId: makeUUID('charge', 'consulting-invoice-2024-05'),
+        creditorId: makeUUID('business', 'us-supplier-acme-llc'),
+        debtorId: '{{ADMIN_BUSINESS_ID}}',
+        serialNumber: 'INV-2024-05-15',
+        type: 'INVOICE',
+        date: '2024-05-01',
+        totalAmount: '500.00',
+        currencyCode: Currency.Usd,
+      },
+      {
+        id: makeUUID('document', 'consulting-invoice-inv-2024-06-15'),
+        chargeId: makeUUID('charge', 'consulting-invoice-2024-06'),
+        creditorId: makeUUID('business', 'us-supplier-acme-llc'),
+        debtorId: '{{ADMIN_BUSINESS_ID}}',
+        serialNumber: 'INV-2024-06-15',
+        type: 'INVOICE',
+        date: '2024-06-01',
+        totalAmount: '500.00',
+        currencyCode: Currency.Usd,
+      },
+      {
+        id: makeUUID('document', 'consulting-invoice-inv-2024-07-15'),
+        chargeId: makeUUID('charge', 'consulting-invoice-2024-07'),
+        creditorId: makeUUID('business', 'us-supplier-acme-llc'),
+        debtorId: '{{ADMIN_BUSINESS_ID}}',
+        serialNumber: 'INV-2024-07-15',
+        type: 'INVOICE',
+        date: '2024-07-01',
+        totalAmount: '500.00',
+        currencyCode: Currency.Usd,
+      },
+      {
+        id: makeUUID('document', 'consulting-invoice-inv-2024-08-15'),
+        chargeId: makeUUID('charge', 'consulting-invoice-2024-08'),
+        creditorId: makeUUID('business', 'us-supplier-acme-llc'),
+        debtorId: '{{ADMIN_BUSINESS_ID}}',
+        serialNumber: 'INV-2024-08-15',
+        type: 'INVOICE',
+        date: '2024-08-01',
+        totalAmount: '500.00',
+        currencyCode: Currency.Usd,
+      },
+      {
+        id: makeUUID('document', 'consulting-invoice-inv-2024-09-15'),
+        chargeId: makeUUID('charge', 'consulting-invoice-2024-09'),
+        creditorId: makeUUID('business', 'us-supplier-acme-llc'),
+        debtorId: '{{ADMIN_BUSINESS_ID}}',
+        serialNumber: 'INV-2024-09-15',
+        type: 'INVOICE',
+        date: '2024-09-01',
+        totalAmount: '500.00',
+        currencyCode: Currency.Usd,
+      },
+      {
+        id: makeUUID('document', 'consulting-invoice-inv-2024-10-15'),
+        chargeId: makeUUID('charge', 'consulting-invoice-2024-10'),
+        creditorId: makeUUID('business', 'us-supplier-acme-llc'),
+        debtorId: '{{ADMIN_BUSINESS_ID}}',
+        serialNumber: 'INV-2024-10-15',
+        type: 'INVOICE',
+        date: '2024-10-01',
+        totalAmount: '500.00',
+        currencyCode: Currency.Usd,
+      },
+      {
+        id: makeUUID('document', 'consulting-invoice-inv-2024-11-15'),
+        chargeId: makeUUID('charge', 'consulting-invoice-2024-11'),
+        creditorId: makeUUID('business', 'us-supplier-acme-llc'),
+        debtorId: '{{ADMIN_BUSINESS_ID}}',
+        serialNumber: 'INV-2024-11-15',
+        type: 'INVOICE',
+        date: '2024-11-01',
+        totalAmount: '500.00',
+        currencyCode: Currency.Usd,
+      },
+      {
+        id: makeUUID('document', 'consulting-invoice-inv-2024-12-15'),
+        chargeId: makeUUID('charge', 'consulting-invoice-2024-12'),
+        creditorId: makeUUID('business', 'us-supplier-acme-llc'),
+        debtorId: '{{ADMIN_BUSINESS_ID}}',
+        serialNumber: 'INV-2024-12-15',
+        type: 'INVOICE',
+        date: '2024-12-01',
+        totalAmount: '500.00',
+        currencyCode: Currency.Usd,
+      },
+    ],
+  },
+  metadata: {
+    author: 'demo-team',
+    createdAt: '2024-01-01',
+    updatedAt: '2024-01-01',
+  },
+  expectations: {
+    ledgerRecordCount: 24,
+  },
+};

package/src/demo-fixtures/use-cases/income/client-payment-with-refund.ts

@@ -0,0 +1,115 @@
+import type { UseCaseSpec } from '../../../fixtures/fixture-spec.js';
+import { CountryCode, Currency } from '../../../shared/enums.js';
+import { makeUUID } from '../../helpers/deterministic-uuid.js';
+
+/**
+ * Client Payment with Refund Cycle
+ *
+ * Models an income scenario where a client pays an invoice
+ * and later receives a partial refund via a credit invoice.
+ * Sign convention follows demo rules: negative amount = income,
+ * positive amount = reversal/refund.
+ */
+export const clientPaymentWithRefund: UseCaseSpec = {
+  id: 'client-payment-with-refund',
+  name: 'Client Payment with Refund',
+  description:
+    'Client invoice paid (income) followed by a partial refund via credit invoice. Uses ILS bank account.',
+  category: 'income',
+  fixtures: {
+    businesses: [
+      {
+        id: makeUUID('business', 'acme-retail-client'),
+        name: 'Acme Retail Client',
+        country: CountryCode['Israel'],
+        canSettleWithReceipt: false,
+      },
+    ],
+    taxCategories: [
+      {
+        id: makeUUID('tax-category', 'service-income'),
+        name: 'Service Income',
+      },
+    ],
+    financialAccounts: [
+      {
+        id: makeUUID('financial-account', 'bank-ils-account-income'),
+        accountNumber: '22-333-4444',
+        type: 'BANK_ACCOUNT',
+        currency: Currency.Ils,
+        taxCategoryMappings: [
+          {
+            taxCategoryId: makeUUID('tax-category', 'service-income'),
+            currency: Currency.Ils,
+          },
+        ],
+      },
+    ],
+    charges: [
+      {
+        id: makeUUID('charge', 'client-invoice-2024-11'),
+        ownerId: '{{ADMIN_BUSINESS_ID}}',
+        userDescription: 'Client invoice for November services',
+      },
+      {
+        id: makeUUID('charge', 'client-refund-credit-2024-11'),
+        ownerId: '{{ADMIN_BUSINESS_ID}}',
+        userDescription: 'Refund credit for November services',
+      },
+    ],
+    transactions: [
+      {
+        id: makeUUID('transaction', 'client-payment-2024-11-15'),
+        chargeId: makeUUID('charge', 'client-invoice-2024-11'),
+        businessId: makeUUID('business', 'acme-retail-client'),
+        amount: '-2000.00',
+        currency: Currency.Ils,
+        eventDate: '2024-11-15',
+        debitDate: '2024-11-15',
+        accountNumber: '22-333-4444',
+      },
+      {
+        id: makeUUID('transaction', 'client-refund-2024-11-20'),
+        chargeId: makeUUID('charge', 'client-refund-credit-2024-11'),
+        businessId: makeUUID('business', 'acme-retail-client'),
+        amount: '500.00',
+        currency: Currency.Ils,
+        eventDate: '2024-11-20',
+        debitDate: '2024-11-20',
+        accountNumber: '22-333-4444',
+      },
+    ],
+    documents: [
+      {
+        id: makeUUID('document', 'client-invoice-inv-2024-11-01'),
+        chargeId: makeUUID('charge', 'client-invoice-2024-11'),
+        creditorId: '{{ADMIN_BUSINESS_ID}}',
+        debtorId: makeUUID('business', 'acme-retail-client'),
+        serialNumber: 'INV-2024-11-01',
+        type: 'INVOICE',
+        date: '2024-11-01',
+        totalAmount: '2000.00',
+        currencyCode: Currency.Ils,
+      },
+      {
+        id: makeUUID('document', 'client-credit-invoice-2024-11-20'),
+        chargeId: makeUUID('charge', 'client-refund-credit-2024-11'),
+        creditorId: '{{ADMIN_BUSINESS_ID}}',
+        debtorId: makeUUID('business', 'acme-retail-client'),
+        serialNumber: 'CR-2024-11-20',
+        type: 'CREDIT_INVOICE',
+        date: '2024-11-20',
+        totalAmount: '500.00',
+        currencyCode: Currency.Ils,
+      },
+    ],
+  },
+  metadata: {
+    author: 'demo-team',
+    createdAt: '2024-11-24',
+    updatedAt: '2024-11-24',
+  },
+  expectations: {
+    ledgerRecordCount: 4,
+  },
+};

package/src/demo-fixtures/use-cases/index.ts

@@ -0,0 +1,52 @@
+import type { UseCaseSpec } from '../../fixtures/fixture-spec.js';
+import { shareholderDividend } from './equity/shareholder-dividend.js';
+import { monthlyExpenseForeignCurrency } from './expenses/monthly-expense-foreign-currency.js';
+import { clientPaymentWithRefund } from './income/client-payment-with-refund.js';
+
+/**
+ * Central registry of all demo use-cases organized by category.
+ *
+ * Each category contains an array of use-case specifications that will be
+ * seeded into the staging environment. Use-cases are processed in the order
+ * they appear in each category array.
+ *
+ * @example
+ * ```typescript
+ * // Adding a new use-case:
+ * import { monthlyExpense } from './expenses/monthly-expense.js';
+ *
+ * export const USE_CASE_REGISTRY: Record<string, UseCaseSpec[]> = {
+ *   expenses: [monthlyExpense],
+ *   income: [],
+ *   equity: [],
+ * };
+ * ```
+ */
+export const USE_CASE_REGISTRY: Record<string, UseCaseSpec[]> = {
+  expenses: [monthlyExpenseForeignCurrency],
+  equity: [shareholderDividend],
+  income: [clientPaymentWithRefund],
+};
+
+/**
+ * Get all registered use-cases across all categories.
+ *
+ * This function flattens the registry into a single array, maintaining
+ * the order: expenses first, then income, then equity (based on object
+ * key insertion order).
+ *
+ * @returns Array of all use-case specifications
+ *
+ * @example
+ * ```typescript
+ * const allUseCases = getAllUseCases();
+ * console.log(`Total use-cases: ${allUseCases.length}`);
+ *
+ * allUseCases.forEach(useCase => {
+ *   console.log(`${useCase.category}: ${useCase.name}`);
+ * });
+ * ```
+ */
+export function getAllUseCases(): UseCaseSpec[] {
+  return Object.values(USE_CASE_REGISTRY).flat();
+}

package/src/demo-fixtures/validate-demo-data.ts

@@ -0,0 +1,153 @@
+/**
+ * Demo Data Validation Script
+ *
+ * Validates the integrity of seeded demo data with comprehensive ledger validation.
+ *
+ * Validation Checks:
+ * - Admin business entity exists
+ * - Charge count matches expected
+ * - Ledger records for each use-case:
+ *   - Per-record internal balance (FR1)
+ *   - Aggregate balance (FR2)
+ *   - Entity-level balance (FR3)
+ *   - No orphaned amounts (FR4)
+ *   - Positive amounts only (FR5)
+ *   - Foreign currency consistency (FR6)
+ *   - Valid dates (FR7)
+ *   - Record count matches (FR8)
+ *
+ * Exit codes:
+ * - 0: All validations passed
+ * - 1: Validation errors found or database connection failed
+ */
+import { config } from 'dotenv';
+import pg from 'pg';
+import { getAllUseCases } from './use-cases/index.js';
+import { validateLedgerRecords } from './validators/ledger-validators.js';
+import type { LedgerRecord, ValidationContext } from './validators/types.js';
+
+config({
+  path: '../../.env',
+});
+
+const DEFAULT_CURRENCY = 'ILS';
+const BALANCE_TOLERANCE = 0.005;
+
+/**
+ * Main validation function - connects to DB and runs all checks
+ */
+async function validateDemoData() {
+  const client = new pg.Client({
+    user: process.env.POSTGRES_USER,
+    password: process.env.POSTGRES_PASSWORD,
+    host: process.env.POSTGRES_HOST,
+    port: parseInt(process.env.POSTGRES_PORT || '5432'),
+    database: process.env.POSTGRES_DB,
+    ssl: process.env.POSTGRES_SSL === '1',
+  });
+
+  const errors: string[] = [];
+
+  try {
+    await client.connect();
+
+    // 1. Admin business exists
+    const adminCheck = await client.query(
+      `SELECT id FROM accounter_schema.financial_entities WHERE type = 'business' AND name = 'Accounter Admin Business'`,
+    );
+    if (adminCheck.rows.length === 0) {
+      errors.push('Admin business entity missing');
+    }
+
+    // 2. Use-case charge count reconciliation
+    const useCases = getAllUseCases();
+    const expectedChargeCount = useCases.reduce((sum, uc) => sum + uc.fixtures.charges.length, 0);
+    const actualChargeCount = await client.query(`SELECT COUNT(*) FROM accounter_schema.charges`);
+    if (parseInt(actualChargeCount.rows[0].count) !== expectedChargeCount) {
+      errors.push(
+        `Charge count mismatch: expected ${expectedChargeCount}, got ${actualChargeCount.rows[0].count}`,
+      );
+    }
+
+    // 3. Comprehensive ledger validation for all use-cases with expectations (FR9)
+    const useCasesWithExpectations = useCases.filter(uc => uc.expectations);
+
+    console.log(
+      `\nValidating ledger records for ${useCasesWithExpectations.length} use-case(s)...`,
+    );
+
+    let ledgerRecordsExist = false;
+
+    for (const useCase of useCasesWithExpectations) {
+      // Get all charges for this use-case
+      const chargeIds = useCase.fixtures.charges.map(c => c.id);
+
+      // Fetch all ledger records for these charges
+      const ledgerRecords = await client.query<LedgerRecord>(
+        `SELECT * FROM accounter_schema.ledger_records WHERE charge_id = ANY($1) ORDER BY created_at`,
+        [chargeIds],
+      );
+
+      if (ledgerRecords.rows.length === 0) {
+        // Ledger generation is separate from seeding - this is expected
+        console.log(`  ⚠ ${useCase.id}: no ledger records (ledger generation not run)`);
+        continue;
+      }
+
+      ledgerRecordsExist = true;
+
+      // Create validation context
+      const context: ValidationContext = {
+        useCaseId: useCase.id,
+        defaultCurrency: DEFAULT_CURRENCY,
+        tolerance: BALANCE_TOLERANCE,
+      };
+
+      // Run comprehensive validation
+      const validationErrors = validateLedgerRecords(
+        ledgerRecords.rows,
+        useCase.expectations!.ledgerRecordCount,
+        context,
+      );
+
+      errors.push(...validationErrors);
+
+      // Log progress
+      if (validationErrors.length === 0) {
+        console.log(`  ✓ ${useCase.id} (${ledgerRecords.rows.length} records)`);
+      } else {
+        console.log(`  ✗ ${useCase.id} (${validationErrors.length} error(s))`);
+      }
+    }
+
+    if (!ledgerRecordsExist) {
+      console.log(
+        '  ℹ️  Ledger records not found. Run ledger generation to create and validate ledger entries.',
+      );
+    }
+
+    // 4. VAT row present (percentage stored as decimal 0.17 for 17%)
+    const vatCheck = await client.query(
+      `SELECT 1 FROM accounter_schema.vat_value WHERE percentage = 0.17`,
+    );
+    if (vatCheck.rows.length === 0) {
+      errors.push('VAT default (17%) missing');
+    }
+
+    // Report errors or success
+    if (errors.length > 0) {
+      console.error('❌ Validation failed:');
+      for (const err of errors) console.error(`  - ${err}`);
+      process.exit(1);
+    }
+
+    console.log('✅ Demo data validation passed');
+  } catch (error) {
+    console.error('❌ Validation error:', error);
+    process.exit(1);
+  } finally {
+    await client.end();
+  }
+}
+
+validateDemoData();