@cosmicdrift/kumiko-bundled-features 0.90.3 → 0.92.0

package/src/ledger/__tests__/feature.test.ts

@@ -0,0 +1,164 @@
+import { describe, expect, test } from "bun:test";
+import { DEFAULT_LEDGER_ROLES } from "../constants";
+import { createLedgerFeature } from "../feature";
+import { createTransactionPayloadSchema, reverseTransactionPayloadSchema } from "../schemas";
+
+// Unit tests: feature-shape, role-options, and the two double-entry invariants
+// that live in the command schema (balance + ≥2 accounts). The ES-loop behaviour
+// (posting projection, Storno, tenant-isolation) needs a real stack →
+// ledger.integration.test.ts.
+
+function writeAccess(
+  feature: ReturnType<typeof createLedgerFeature>,
+  nameMatch: string,
+): readonly string[] {
+  const entry = Object.entries(feature.writeHandlers).find(([qn]) => qn.includes(nameMatch));
+  if (!entry) throw new Error(`handler ${nameMatch} not registered`);
+  const access = entry[1].access;
+  if (!access || !("roles" in access)) throw new Error(`handler ${nameMatch} has no roles`);
+  return access.roles;
+}
+
+describe("createLedgerFeature shape", () => {
+  test("registers account + transaction entities, 4 write-handlers, 4 query-handlers", () => {
+    const feature = createLedgerFeature();
+
+    expect(Object.keys(feature.entities ?? {})).toEqual(
+      expect.arrayContaining(["account", "transaction"]),
+    );
+
+    expect(Object.keys(feature.writeHandlers)).toEqual(
+      expect.arrayContaining([
+        expect.stringMatching(/account:create/),
+        expect.stringMatching(/account:update/),
+        expect.stringMatching(/create-transaction/),
+        expect.stringMatching(/reverse-transaction/),
+      ]),
+    );
+    expect(Object.keys(feature.writeHandlers)).toHaveLength(4);
+
+    expect(Object.keys(feature.queryHandlers)).toEqual(
+      expect.arrayContaining([
+        expect.stringMatching(/account:list/),
+        expect.stringMatching(/account:detail/),
+        expect.stringMatching(/transaction:list/),
+        expect.stringMatching(/transaction:detail/),
+        expect.stringMatching(/report:balances/),
+        expect.stringMatching(/report:income-statement/),
+        expect.stringMatching(/report:balance-sheet/),
+      ]),
+    );
+    expect(Object.keys(feature.queryHandlers)).toHaveLength(7);
+  });
+
+  test("transaction is immutable: NO update/delete handler is registered", () => {
+    const feature = createLedgerFeature();
+    const writeQns = Object.keys(feature.writeHandlers);
+    expect(writeQns.some((qn) => qn.includes("transaction:update"))).toBe(false);
+    expect(writeQns.some((qn) => qn.includes("transaction:delete"))).toBe(false);
+  });
+
+  test("account has no delete handler in v1 (postings-aware guard deferred)", () => {
+    const feature = createLedgerFeature();
+    expect(Object.keys(feature.writeHandlers).some((qn) => qn.includes("account:delete"))).toBe(
+      false,
+    );
+  });
+});
+
+describe("createLedgerFeature access-options", () => {
+  test("without options: singleton with default roles on every path", () => {
+    const feature = createLedgerFeature();
+    expect(feature).toBe(createLedgerFeature());
+    for (const path of ["account:create", "create-transaction", "reverse-transaction"]) {
+      expect(writeAccess(feature, path)).toEqual([...DEFAULT_LEDGER_ROLES]);
+    }
+  });
+
+  test("roles option overrides every write-path", () => {
+    const feature = createLedgerFeature({ roles: ["Accountant"] });
+    expect(writeAccess(feature, "create-transaction")).toEqual(["Accountant"]);
+    expect(writeAccess(feature, "account:create")).toEqual(["Accountant"]);
+  });
+
+  test("toggleable:{default:false} makes the feature tier-gatable, fail-closed", () => {
+    const feature = createLedgerFeature({ toggleable: { default: false } });
+    expect(feature.toggleableDefault).toBe(false);
+  });
+});
+
+describe("createTransactionPayloadSchema — double-entry invariants", () => {
+  const ok = {
+    date: "2026-01-15",
+    description: "Miete Januar",
+    lines: [
+      { accountId: "acc-bank", amount: 100000 },
+      { accountId: "acc-rent-income", amount: -100000 },
+    ],
+  };
+
+  test("accepts a balanced entry across two accounts", () => {
+    expect(createTransactionPayloadSchema.safeParse(ok).success).toBe(true);
+  });
+
+  test("rejects an unbalanced entry (Σ ≠ 0)", () => {
+    const bad = {
+      ...ok,
+      lines: [
+        { accountId: "acc-bank", amount: 100000 },
+        { accountId: "acc-rent-income", amount: -90000 },
+      ],
+    };
+    expect(createTransactionPayloadSchema.safeParse(bad).success).toBe(false);
+  });
+
+  test("rejects fewer than 2 lines", () => {
+    const bad = { ...ok, lines: [{ accountId: "acc-bank", amount: 0 }] };
+    expect(createTransactionPayloadSchema.safeParse(bad).success).toBe(false);
+  });
+
+  test("rejects 2 balanced lines on the SAME account (no value moved)", () => {
+    const bad = {
+      ...ok,
+      lines: [
+        { accountId: "acc-bank", amount: 100000 },
+        { accountId: "acc-bank", amount: -100000 },
+      ],
+    };
+    expect(createTransactionPayloadSchema.safeParse(bad).success).toBe(false);
+  });
+
+  test("rejects non-integer amounts (cents are integers)", () => {
+    const bad = {
+      ...ok,
+      lines: [
+        { accountId: "acc-bank", amount: 1000.5 },
+        { accountId: "acc-rent-income", amount: -1000.5 },
+      ],
+    };
+    expect(createTransactionPayloadSchema.safeParse(bad).success).toBe(false);
+  });
+
+  test("accepts a balanced split across three accounts (e.g. credit rate)", () => {
+    const split = {
+      date: "2026-01-01",
+      description: "Kreditrate (Zins + Tilgung)",
+      lines: [
+        { accountId: "acc-bank", amount: -150000 }, // Zahlung raus
+        { accountId: "acc-interest-expense", amount: 50000 }, // Zins
+        { accountId: "acc-loan-liability", amount: 100000 }, // Tilgung mindert Schuld
+      ],
+    };
+    expect(createTransactionPayloadSchema.safeParse(split).success).toBe(true);
+  });
+});
+
+describe("reverseTransactionPayloadSchema", () => {
+  test("accepts an id-only Storno request", () => {
+    expect(reverseTransactionPayloadSchema.safeParse({ id: "tx-1" }).success).toBe(true);
+  });
+
+  test("rejects a missing id", () => {
+    expect(reverseTransactionPayloadSchema.safeParse({}).success).toBe(false);
+  });
+});

package/src/ledger/__tests__/ledger.integration.test.ts

@@ -0,0 +1,300 @@
+// Full-stack integration for the ledger bundle. Drives account + transaction
+// through the real dispatcher + entity-projection + DB. Proves the double-entry
+// primitive end-to-end:
+//   - create-transaction books a balanced entry; the embedded lines round-trip
+//   - an unbalanced entry (Σ ≠ 0) is rejected at the command boundary (400)
+//   - a posting to a non-existent account is rejected (404, referential integrity)
+//   - reverse-transaction books the negated mirror referencing the original
+//   - the TRIAL BALANCE (Σ of every posting amount) is 0 — the invariant that
+//     always holds, unlike the balance-sheet equation (which needs period close)
+//   - multi-tenant isolation: each tenant has its own books
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
+import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import {
+  createTestUser,
+  setupTestStack,
+  type TestStack,
+  unsafeCreateEntityTable,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { type AccountType, LedgerHandlers, LedgerQueries } from "../constants";
+import { accountEntity, transactionEntity } from "../entity";
+import { createLedgerFeature } from "../feature";
+import type { Posting } from "../schemas";
+
+const ledgerFeature = createLedgerFeature();
+
+let stack: TestStack;
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [ledgerFeature] });
+  await unsafeCreateEntityTable(stack.db, accountEntity);
+  await unsafeCreateEntityTable(stack.db, transactionEntity);
+  await createEventsTable(stack.db);
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+beforeEach(async () => {
+  await asRawClient(stack.db).unsafe("DELETE FROM kumiko_events");
+  await asRawClient(stack.db).unsafe("DELETE FROM read_ledger_accounts");
+  await asRawClient(stack.db).unsafe("DELETE FROM read_ledger_transactions");
+});
+
+const admin = createTestUser({ roles: ["TenantAdmin"] });
+const otherTenant = createTestUser({
+  roles: ["TenantAdmin"],
+  tenantId: "00000000-0000-4000-8000-0000000000aa",
+});
+
+async function createAccount(name: string, type: AccountType, user = admin): Promise<string> {
+  const acc = await stack.http.writeOk<{ id: string }>(
+    LedgerHandlers.createAccount,
+    { name, type },
+    user,
+  );
+  return acc.id;
+}
+
+async function createTransaction(
+  lines: readonly Posting[],
+  opts: { date?: string; description?: string } = {},
+  user = admin,
+): Promise<{ id: string }> {
+  return stack.http.writeOk<{ id: string }>(
+    LedgerHandlers.createTransaction,
+    {
+      date: opts.date ?? "2026-01-15",
+      description: opts.description ?? "Test entry",
+      lines,
+    },
+    user,
+  );
+}
+
+async function listTransactions(user = admin): Promise<Array<Record<string, unknown>>> {
+  const res = await stack.http.queryOk<{ rows: Array<Record<string, unknown>> }>(
+    LedgerQueries.transactionList,
+    {},
+    user,
+  );
+  return res.rows;
+}
+
+// jsonb may surface as a parsed array or a string depending on the driver path —
+// normalise so the assertions don't depend on it.
+function linesOf(row: Record<string, unknown>): Posting[] {
+  const raw = row["lines"];
+  return (typeof raw === "string" ? JSON.parse(raw) : raw) as Posting[]; // @cast-boundary db-row
+}
+
+// The golden double-entry invariant: every entry sums to 0, so the sum over ALL
+// postings of ALL transactions is 0.
+function trialBalance(rows: Array<Record<string, unknown>>): number {
+  return rows.reduce((s, r) => s + linesOf(r).reduce((t, l) => t + l.amount, 0), 0);
+}
+
+describe("ledger integration — create-transaction (balance invariant)", () => {
+  test("books a balanced entry; lines round-trip; status posted", async () => {
+    const bank = await createAccount("Bank", "asset");
+    const rent = await createAccount("Mieterträge", "income");
+
+    const tx = await createTransaction(
+      [
+        { accountId: bank, amount: 100000 },
+        { accountId: rent, amount: -100000 },
+      ],
+      { description: "Miete Januar" },
+    );
+
+    const rows = await listTransactions();
+    expect(rows).toHaveLength(1);
+    expect(rows[0]?.["id"]).toBe(tx.id);
+    expect(rows[0]?.["status"]).toBe("posted");
+    expect(rows[0]?.["description"]).toBe("Miete Januar");
+    expect(linesOf(rows[0] as Record<string, unknown>)).toHaveLength(2);
+  });
+
+  test("rejects an unbalanced entry (Σ ≠ 0) — no transaction written", async () => {
+    const bank = await createAccount("Bank", "asset");
+    const rent = await createAccount("Mieterträge", "income");
+
+    const err = await stack.http.writeErr(
+      LedgerHandlers.createTransaction,
+      {
+        date: "2026-01-15",
+        description: "schief",
+        lines: [
+          { accountId: bank, amount: 100000 },
+          { accountId: rent, amount: -90000 },
+        ],
+      },
+      admin,
+    );
+    expect(err.httpStatus).toBe(400);
+    expect(await listTransactions()).toHaveLength(0);
+  });
+
+  test("rejects a posting to a non-existent account (404) — referential integrity", async () => {
+    const bank = await createAccount("Bank", "asset");
+
+    const err = await stack.http.writeErr(
+      LedgerHandlers.createTransaction,
+      {
+        date: "2026-01-15",
+        description: "ghost",
+        lines: [
+          { accountId: bank, amount: 100000 },
+          { accountId: "00000000-0000-4000-8000-00000000dead", amount: -100000 },
+        ],
+      },
+      admin,
+    );
+    expect(err.httpStatus).toBe(404);
+    expect(await listTransactions()).toHaveLength(0);
+  });
+});
+
+describe("ledger integration — reverse-transaction (Storno)", () => {
+  test("books the negated mirror referencing the original; both remain", async () => {
+    const bank = await createAccount("Bank", "asset");
+    const rent = await createAccount("Mieterträge", "income");
+
+    const tx = await createTransaction(
+      [
+        { accountId: bank, amount: 100000 },
+        { accountId: rent, amount: -100000 },
+      ],
+      { description: "Miete" },
+    );
+
+    await stack.http.writeOk(LedgerHandlers.reverseTransaction, { id: tx.id }, admin);
+
+    const rows = await listTransactions();
+    expect(rows).toHaveLength(2);
+
+    const storno = rows.find((r) => r["reference"] === tx.id);
+    expect(storno).toBeDefined();
+    const stornoLines = linesOf(storno as Record<string, unknown>);
+    expect(stornoLines.find((l) => l.accountId === bank)?.amount).toBe(-100000);
+    expect(stornoLines.find((l) => l.accountId === rent)?.amount).toBe(100000);
+
+    // Original + Storno cancel → books net to zero.
+    expect(trialBalance(rows)).toBe(0);
+  });
+});
+
+describe("ledger integration — trial balance (golden invariant)", () => {
+  test("Σ of every posting across all entries is 0", async () => {
+    const bank = await createAccount("Bank", "asset");
+    const rent = await createAccount("Mieterträge", "income");
+    const expense = await createAccount("Aufwand", "expense");
+
+    await createTransaction([
+      { accountId: bank, amount: 100000 },
+      { accountId: rent, amount: -100000 },
+    ]);
+    // Credit rate split: Zins (expense) + Tilgung … here just expense vs bank.
+    await createTransaction([
+      { accountId: expense, amount: 30000 },
+      { accountId: bank, amount: -30000 },
+    ]);
+
+    expect(trialBalance(await listTransactions())).toBe(0);
+  });
+});
+
+describe("ledger integration — multi-tenant isolation", () => {
+  test("tenant B sees neither tenant A's accounts nor transactions", async () => {
+    const bank = await createAccount("Bank", "asset", admin);
+    const rent = await createAccount("Mieterträge", "income", admin);
+    await createTransaction(
+      [
+        { accountId: bank, amount: 100000 },
+        { accountId: rent, amount: -100000 },
+      ],
+      {},
+      admin,
+    );
+
+    expect(await listTransactions(otherTenant)).toHaveLength(0);
+    const otherAccounts = await stack.http.queryOk<{ rows: unknown[] }>(
+      LedgerQueries.accountList,
+      {},
+      otherTenant,
+    );
+    expect(otherAccounts.rows).toHaveLength(0);
+
+    expect(await listTransactions(admin)).toHaveLength(1);
+  });
+});
+
+describe("ledger integration — reports (end-to-end)", () => {
+  // Books: capital injection + rent income + an expense.
+  async function seedBooks() {
+    const bank = await createAccount("Bank", "asset");
+    const equity = await createAccount("Eigenkapital", "equity");
+    const rent = await createAccount("Mieterträge", "income");
+    const expense = await createAccount("Aufwand", "expense");
+    await createTransaction(
+      [
+        { accountId: bank, amount: 500000 },
+        { accountId: equity, amount: -500000 },
+      ],
+      { date: "2026-01-01", description: "Kapital" },
+    );
+    await createTransaction(
+      [
+        { accountId: bank, amount: 100000 },
+        { accountId: rent, amount: -100000 },
+      ],
+      { date: "2026-01-15", description: "Miete" },
+    );
+    await createTransaction(
+      [
+        { accountId: expense, amount: 30000 },
+        { accountId: bank, amount: -30000 },
+      ],
+      { date: "2026-01-20", description: "Aufwand" },
+    );
+    return { bank };
+  }
+
+  test("balances report: natural balances + trial balance 0", async () => {
+    const { bank } = await seedBooks();
+    const r = await stack.http.queryOk<{
+      accounts: Array<{ id: string; balance: number }>;
+      trialBalance: number;
+    }>(LedgerQueries.reportBalances, {}, admin);
+    expect(r.trialBalance).toBe(0);
+    expect(r.accounts.find((a) => a.id === bank)?.balance).toBe(570000);
+  });
+
+  test("income statement: income − expense = net income", async () => {
+    await seedBooks();
+    const r = await stack.http.queryOk<{
+      income: number;
+      expense: number;
+      netIncome: number;
+    }>(LedgerQueries.reportIncomeStatement, {}, admin);
+    expect(r).toEqual({ income: 100000, expense: 30000, netIncome: 70000 });
+  });
+
+  test("balance sheet balances with the current result in equity", async () => {
+    await seedBooks();
+    const r = await stack.http.queryOk<{
+      assets: number;
+      liabilities: number;
+      equity: number;
+      currentResult: number;
+      balances: boolean;
+    }>(LedgerQueries.reportBalanceSheet, {}, admin);
+    expect(r.assets).toBe(570000);
+    expect(r.currentResult).toBe(70000);
+    expect(r.equity).toBe(570000);
+    expect(r.balances).toBe(true);
+  });
+});

package/src/ledger/__tests__/reports.test.ts

@@ -0,0 +1,122 @@
+import { describe, expect, test } from "bun:test";
+import {
+  accountBalances,
+  balanceSheet,
+  incomeStatement,
+  type LedgerAccount,
+  type LedgerEntry,
+} from "../reports";
+
+// Pure report math — no DB. A small but complete set of books:
+//   1. owner capital:  bank +500000 / equity −500000
+//   2. rent income:    bank +100000 / rent  −100000
+//   3. an expense:     expense +30000 / bank −30000
+const accounts: LedgerAccount[] = [
+  { id: "bank", name: "Bank", type: "asset" },
+  { id: "equity", name: "Eigenkapital", type: "equity" },
+  { id: "rent", name: "Mieterträge", type: "income" },
+  { id: "expense", name: "Aufwand", type: "expense" },
+  { id: "loan", name: "Darlehen", type: "liability" },
+];
+
+const posted: LedgerEntry[] = [
+  {
+    status: "posted",
+    date: "2026-01-01",
+    lines: [
+      { accountId: "bank", amount: 500000 },
+      { accountId: "equity", amount: -500000 },
+    ],
+  },
+  {
+    status: "posted",
+    date: "2026-01-15",
+    lines: [
+      { accountId: "bank", amount: 100000 },
+      { accountId: "rent", amount: -100000 },
+    ],
+  },
+  {
+    status: "posted",
+    date: "2026-01-20",
+    lines: [
+      { accountId: "expense", amount: 30000 },
+      { accountId: "bank", amount: -30000 },
+    ],
+  },
+];
+
+function balanceOf(report: ReturnType<typeof accountBalances>, id: string): number {
+  return report.accounts.find((a) => a.id === id)?.balance ?? Number.NaN;
+}
+
+describe("accountBalances — natural balances + trial balance", () => {
+  test("natural balances are sign-corrected by account type", () => {
+    const r = accountBalances(accounts, posted);
+    expect(balanceOf(r, "bank")).toBe(570000); // asset, debit-normal
+    expect(balanceOf(r, "equity")).toBe(500000); // equity, credit-normal → flipped
+    expect(balanceOf(r, "rent")).toBe(100000); // income, credit-normal → flipped
+    expect(balanceOf(r, "expense")).toBe(30000); // expense, debit-normal
+  });
+
+  test("an account with no postings has a 0 balance", () => {
+    expect(balanceOf(accountBalances(accounts, posted), "loan")).toBe(0);
+  });
+
+  test("the trial balance (Σ raw) is 0 — the golden invariant", () => {
+    expect(accountBalances(accounts, posted).trialBalance).toBe(0);
+  });
+
+  test("draft entries never count toward the books", () => {
+    const withDraft: LedgerEntry[] = [
+      ...posted,
+      {
+        status: "draft",
+        date: "2026-02-01",
+        lines: [
+          { accountId: "bank", amount: 999999 },
+          { accountId: "rent", amount: -999999 },
+        ],
+      },
+    ];
+    expect(balanceOf(accountBalances(accounts, withDraft), "bank")).toBe(570000);
+  });
+
+  test("period filter excludes entries outside [from, to]", () => {
+    // Only the rent entry (2026-01-15) falls inside.
+    const r = accountBalances(accounts, posted, { from: "2026-01-10", to: "2026-01-18" });
+    expect(balanceOf(r, "bank")).toBe(100000);
+    expect(balanceOf(r, "rent")).toBe(100000);
+    expect(r.trialBalance).toBe(0);
+  });
+});
+
+describe("incomeStatement (GuV)", () => {
+  test("income − expense = net income", () => {
+    expect(incomeStatement(accounts, posted)).toEqual({
+      income: 100000,
+      expense: 30000,
+      netIncome: 70000,
+    });
+  });
+});
+
+describe("balanceSheet (Bilanz)", () => {
+  test("balances with the current result folded into equity", () => {
+    const b = balanceSheet(accounts, posted);
+    expect(b.assets).toBe(570000);
+    expect(b.liabilities).toBe(0);
+    expect(b.currentResult).toBe(70000); // laufendes Ergebnis
+    expect(b.equity).toBe(570000); // 500000 capital + 70000 result
+    expect(b.balances).toBe(true); // assets === liabilities + equity
+  });
+
+  test("balances even before any income/expense is closed (current result line)", () => {
+    // Just the capital injection → assets 500000, equity 500000, result 0.
+    const onlyCapital = [posted[0] as LedgerEntry];
+    const b = balanceSheet(accounts, onlyCapital);
+    expect(b.assets).toBe(500000);
+    expect(b.currentResult).toBe(0);
+    expect(b.balances).toBe(true);
+  });
+});

package/src/ledger/constants.ts

@@ -0,0 +1,47 @@
+// @runtime client
+// ledger bundle constants — feature-name + qualified handler/query names.
+//
+// Spec: kumiko-platform/docs/plans/ledger-feature.md
+
+import type { AccessRule } from "@cosmicdrift/kumiko-framework/engine";
+
+export const LEDGER_FEATURE_NAME = "ledger";
+
+// Qualified names (QN format: scope:type:name). The account catalog uses the
+// generic defineEntity*Handler (create/update/list/detail) → "account:<verb>"
+// qualified to "ledger:write:account:<verb>". Transactions are immutable: only
+// create-transaction (balanced, Σ=0) and reverse-transaction (Storno) exist —
+// no update/delete, so a posted journal entry can never be mutated.
+export const LedgerHandlers = {
+  createAccount: "ledger:write:account:create",
+  updateAccount: "ledger:write:account:update",
+  createTransaction: "ledger:write:create-transaction",
+  reverseTransaction: "ledger:write:reverse-transaction",
+} as const;
+
+export const LedgerQueries = {
+  accountList: "ledger:query:account:list",
+  accountDetail: "ledger:query:account:detail",
+  transactionList: "ledger:query:transaction:list",
+  transactionDetail: "ledger:query:transaction:detail",
+  // Reports — pure aggregations over the posted entries (Phase 1).
+  reportBalances: "ledger:query:report:balances",
+  reportIncomeStatement: "ledger:query:report:income-statement",
+  reportBalanceSheet: "ledger:query:report:balance-sheet",
+} as const;
+
+// Account types double-entry needs to interpret a balance: asset/expense are
+// debit-normal, liability/equity/income are credit-normal. The report layer
+// (Phase 1) flips signs by type; the primitive only stores them.
+export const ACCOUNT_TYPES = ["asset", "liability", "equity", "income", "expense"] as const;
+export type AccountType = (typeof ACCOUNT_TYPES)[number];
+
+export const TRANSACTION_STATUS = ["draft", "posted"] as const;
+export type TransactionStatus = (typeof TRANSACTION_STATUS)[number];
+
+// Default RBAC for every ledger path. A ledger is sensitive (it's the books), but
+// like folders it adopts the host's model — apps pin roles via
+// createLedgerFeature({ roles }) or { access }. Default: both tenant roles.
+export const DEFAULT_LEDGER_ROLES = ["TenantAdmin", "TenantMember"] as const;
+
+export const DEFAULT_LEDGER_ACCESS: AccessRule = { roles: DEFAULT_LEDGER_ROLES };

package/src/ledger/entity.ts

@@ -0,0 +1,54 @@
+import {
+  createDateField,
+  createEntity,
+  createJsonbField,
+  createSelectField,
+  createTextField,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { ACCOUNT_TYPES, TRANSACTION_STATUS } from "./constants";
+
+// account — a node in the chart of accounts. Event-sourced (create/update/list/
+// detail via the standard handlers); the framework projects `read_ledger_accounts`
+// from its CRUD events. `parentId` null → root account; otherwise the chart-of-
+// accounts tree. `type` drives how the report layer interprets a balance. No
+// money column — balances are DERIVED from postings (Phase 1), never stored.
+// tenantId is a base column set by the framework → each tenant has its own books.
+export const accountEntity = createEntity({
+  table: "read_ledger_accounts",
+  fields: {
+    name: createTextField({ required: true, maxLength: 120 }),
+    type: createSelectField({ options: ACCOUNT_TYPES, required: true }),
+    // Optional account number (Kontonummer / SKR code) — free text in v1.
+    code: createTextField({ maxLength: 32 }),
+    // Parent account id, or absent for a root account. No FK (event-sourced).
+    parentId: createTextField({ maxLength: 64 }),
+  },
+});
+
+// transaction — a journal entry. The balanced posting lines live embedded as
+// `lines` (jsonb: { accountId, amount }[], Σ amount = 0), so an entry is atomic:
+// the Σ=0 invariant holds within a single command, no cross-row write. The
+// framework projects `read_ledger_transactions`; Phase 1 adds a flat
+// `read_ledger_postings` projection (one row per line) for per-account/period
+// report queries.
+//
+// IMMUTABLE: the feature registers NO update/delete handler for transaction. A
+// posted entry is a fact; corrections are reverse-transaction (Storno) entries.
+// `status` carries draft|posted for the later Soll/Ist work — Phase 0 posts only.
+export const transactionEntity = createEntity({
+  table: "read_ledger_transactions",
+  fields: {
+    date: createDateField({ required: true }),
+    // Journal narration ("Miete Januar", "Storno: …") is accounting data, not
+    // user-generated PII → allowPlaintext silences the user-content heuristic.
+    description: createTextField({
+      required: true,
+      maxLength: 200,
+      allowPlaintext: "is-business-data",
+    }),
+    // For a Storno entry this points at the reversed transaction's id.
+    reference: createTextField({ maxLength: 120 }),
+    status: createSelectField({ options: TRANSACTION_STATUS, required: true }),
+    lines: createJsonbField(),
+  },
+});