@cosmicdrift/kumiko-bundled-features 0.90.2 → 0.91.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.90.2",
+  "version": "0.91.0",
   "description": "Built-in features — tenant, user, auth, delivery. The stuff you'd rewrite anyway, already typed.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -35,6 +35,7 @@
     "./folders": "./src/folders/index.ts",
     "./folders/web": "./src/folders/web/index.ts",
     "./folders-user-data": "./src/folders-user-data/index.ts",
+    "./ledger": "./src/ledger/index.ts",
     "./billing-foundation": "./src/billing-foundation/index.ts",
     "./subscription-stripe": "./src/subscription-stripe/index.ts",
     "./subscription-mollie": "./src/subscription-mollie/index.ts",
@@ -89,11 +90,11 @@
     "./step-dispatcher": "./src/step-dispatcher/index.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.90.2",
-    "@cosmicdrift/kumiko-framework": "0.90.2",
-    "@cosmicdrift/kumiko-headless": "0.90.2",
-    "@cosmicdrift/kumiko-renderer": "0.90.2",
-    "@cosmicdrift/kumiko-renderer-web": "0.90.2",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.91.0",
+    "@cosmicdrift/kumiko-framework": "0.91.0",
+    "@cosmicdrift/kumiko-headless": "0.91.0",
+    "@cosmicdrift/kumiko-renderer": "0.91.0",
+    "@cosmicdrift/kumiko-renderer-web": "0.91.0",
     "@mollie/api-client": "^4.5.0",
     "@node-rs/argon2": "^2.0.2",
     "@types/nodemailer": "^8.0.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(),
+  },
+});

package/src/ledger/executor.ts

@@ -0,0 +1,14 @@
+import { createEntityExecutor } from "@cosmicdrift/kumiko-framework/engine";
+import { accountEntity, transactionEntity } from "./entity";
+
+// Shared tables + executors for the account + transaction handlers. Built once
+// (side-effect-free). The tables back the report query-handlers (selectMany over
+// the entity projections — see handlers/reports.query.ts).
+export const { table: accountTable, executor: accountExecutor } = createEntityExecutor(
+  "account",
+  accountEntity,
+);
+export const { table: transactionTable, executor: transactionExecutor } = createEntityExecutor(
+  "transaction",
+  transactionEntity,
+);

package/src/ledger/feature.ts

@@ -0,0 +1,109 @@
+// ledger — double-entry bookkeeping as a host-agnostic primitive.
+//
+// Two event-sourced entities:
+//   1. `account` (read_ledger_accounts)        — per-tenant chart of accounts (parentId tree).
+//   2. `transaction` (read_ledger_transactions) — journal entries with embedded,
+//      balanced posting lines (Σ amount = 0). IMMUTABLE: no update/delete handler;
+//      corrections are reverse-transaction (Storno) entries.
+//
+// Everything financial — banking, accounting, rent cashflow, credits, invoices —
+// is accounts + balanced transactions on top. Balances and reports (Bilanz, GuV,
+// Cashflow) are pure queries over the postings (Phase 1), never stored state.
+//
+// Spec: kumiko-platform/docs/plans/ledger-feature.md
+
+import {
+  type AccessRule,
+  defineEntityCreateHandler,
+  defineEntityDetailHandler,
+  defineEntityListHandler,
+  defineEntityUpdateHandler,
+  defineFeature,
+  type FeatureRegistrar,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { DEFAULT_LEDGER_ACCESS, LEDGER_FEATURE_NAME } from "./constants";
+import { accountEntity, transactionEntity } from "./entity";
+import { createCreateTransactionHandler } from "./handlers/create-transaction.write";
+import {
+  createBalanceSheetHandler,
+  createBalancesReportHandler,
+  createIncomeStatementHandler,
+} from "./handlers/reports.query";
+import { createReverseTransactionHandler } from "./handlers/reverse-transaction.write";
+
+// Opt-in tier-gating (mirrors folders): when set, the feature declares itself
+// r.toggleable so the dispatcher gate + tier-engine can switch the WHOLE ledger
+// on/off per tenant. Use { default: false } for fail-closed gating.
+type LedgerToggleable = { readonly default: boolean };
+
+function registerLedger(
+  r: FeatureRegistrar<typeof LEDGER_FEATURE_NAME>,
+  access: AccessRule,
+  toggleable: LedgerToggleable | undefined,
+): void {
+  r.describe(
+    "Double-entry bookkeeping primitive. Owns two event-sourced entities — the per-tenant `account` chart of accounts (`read_ledger_accounts`, self-referential via parentId, typed asset/liability/equity/income/expense) and immutable `transaction` journal entries (`read_ledger_transactions`) whose balanced posting lines are embedded as jsonb (Σ amount = 0, signed integer minor units). The account catalog uses the generic entity handlers (create, update, list, detail); create-transaction books a balanced entry (Σ=0 and ≥2 distinct accounts enforced at the command boundary, referential integrity against accounts checked) and reverse-transaction books its Storno mirror — there is deliberately NO transaction update/delete, so a posted entry is an immutable fact and the audit trail stays intact. Balances and reports (balance sheet, P&L, cashflow) derive as pure queries over the postings. Everything financial — banking, accounting, rent cashflow, credits, invoices — models as accounts + balanced transactions on top. Pin roles with createLedgerFeature({ roles }) or adopt the host model with { access }; pass { toggleable: { default: false } } to tier-gate the whole feature.",
+  );
+  r.uiHints({
+    displayLabel: "Ledger",
+    category: "data",
+    recommended: false,
+  });
+
+  if (toggleable !== undefined) r.toggleable(toggleable);
+
+  r.entity("account", accountEntity);
+  r.entity("transaction", transactionEntity);
+
+  // Chart of accounts — plain CRUD, no custom logic. No delete in v1: removing an
+  // account that has postings would orphan them; a posting-aware guard lands with
+  // the postings projection (Phase 1).
+  r.writeHandler(defineEntityCreateHandler("account", accountEntity, { access }));
+  r.writeHandler(defineEntityUpdateHandler("account", accountEntity, { access }));
+  r.queryHandler(defineEntityListHandler("account", accountEntity, { access }));
+  r.queryHandler(defineEntityDetailHandler("account", accountEntity, { access }));
+
+  // Journal entries — immutable. Only create (balanced) + reverse (Storno). No
+  // update/delete handler is registered, so a posted entry cannot be mutated.
+  r.writeHandler(createCreateTransactionHandler(access));
+  r.writeHandler(createReverseTransactionHandler(access));
+  r.queryHandler(defineEntityListHandler("transaction", transactionEntity, { access }));
+  r.queryHandler(defineEntityDetailHandler("transaction", transactionEntity, { access }));
+
+  // Reports — pure aggregations over the posted entries (account balances,
+  // GuV, Bilanz with the current result folded into equity).
+  r.queryHandler(createBalancesReportHandler(access));
+  r.queryHandler(createIncomeStatementHandler(access));
+  r.queryHandler(createBalanceSheetHandler(access));
+}
+
+export const ledgerFeature = defineFeature(LEDGER_FEATURE_NAME, (r) =>
+  registerLedger(r, DEFAULT_LEDGER_ACCESS, undefined),
+);
+
+export type LedgerFeatureOptions = {
+  /** Access rule for all ledger write/read paths. Default { roles: ["TenantAdmin","TenantMember"] }.
+   *  Takes precedence over `roles`. */
+  readonly access?: AccessRule;
+  /** Shorthand for { access: { roles } }. Ignored when `access` is set. */
+  readonly roles?: readonly string[];
+  /** Make the whole feature tier-gatable via the tier-engine. Use { default: false }
+   *  for fail-closed gating. Omit to keep the ledger always-on (default). */
+  readonly toggleable?: LedgerToggleable;
+};
+
+function resolveAccess(opts: LedgerFeatureOptions): AccessRule {
+  if (opts.access !== undefined) return opts.access;
+  if (opts.roles !== undefined) return { roles: opts.roles };
+  return DEFAULT_LEDGER_ACCESS;
+}
+
+// Options wrapper. Without options returns the module-level singleton (no
+// rebuild). access/roles/toggleable build a fresh feature-definition.
+export function createLedgerFeature(opts: LedgerFeatureOptions = {}): typeof ledgerFeature {
+  if (opts.access === undefined && opts.roles === undefined && opts.toggleable === undefined) {
+    return ledgerFeature;
+  }
+  const access = resolveAccess(opts);
+  return defineFeature(LEDGER_FEATURE_NAME, (r) => registerLedger(r, access, opts.toggleable));
+}

package/src/ledger/handlers/create-transaction.write.ts

@@ -0,0 +1,44 @@
+import type { AccessRule, WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import { NotFoundError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import { generateId } from "@cosmicdrift/kumiko-framework/utils";
+import { DEFAULT_LEDGER_ACCESS } from "../constants";
+import { accountExecutor, transactionExecutor } from "../executor";
+import { type CreateTransactionPayload, createTransactionPayloadSchema } from "../schemas";
+
+// create-transaction — books a balanced journal entry. The Σ=0 and ≥2-accounts
+// invariants are enforced by createTransactionPayloadSchema (command boundary).
+// This handler adds referential integrity (every posting's account must exist —
+// there is no FK in an event-sourced store) and assigns a fresh id. Entries are
+// posted by default and immutable thereafter (no update/delete handler exists).
+export function createCreateTransactionHandler(
+  access: AccessRule = DEFAULT_LEDGER_ACCESS,
+): WriteHandlerDef {
+  return {
+    name: "create-transaction",
+    schema: createTransactionPayloadSchema,
+    access,
+    handler: async (event, ctx) => {
+      const payload = event.payload as CreateTransactionPayload; // @cast-boundary engine-payload
+
+      for (const accountId of new Set(payload.lines.map((l) => l.accountId))) {
+        const account = await accountExecutor.detail({ id: accountId }, event.user, ctx.db);
+        if (!account) return writeFailure(new NotFoundError("account", accountId));
+      }
+
+      return transactionExecutor.create(
+        {
+          id: generateId(),
+          date: payload.date,
+          description: payload.description,
+          reference: payload.reference ?? null,
+          status: payload.status ?? "posted",
+          lines: payload.lines,
+        },
+        event.user,
+        ctx.db,
+      );
+    },
+  };
+}
+
+export const createTransactionHandler: WriteHandlerDef = createCreateTransactionHandler();

package/src/ledger/handlers/reports.query.ts

@@ -0,0 +1,79 @@
+import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import type { AccessRule, QueryHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
+import { DEFAULT_LEDGER_ACCESS } from "../constants";
+import { accountTable, transactionTable } from "../executor";
+import {
+  accountBalances,
+  balanceSheet,
+  incomeStatement,
+  type LedgerAccount,
+  type LedgerEntry,
+  toAccounts,
+  toEntries,
+} from "../reports";
+
+// Reports take an optional reporting period. Balance-sheet is cumulative → pass
+// { to: asOf }; income-statement is a period → { from, to }.
+const periodSchema = z.object({
+  from: z.string().min(1).max(32).optional(),
+  to: z.string().min(1).max(32).optional(),
+});
+
+type QueryCtx = Parameters<QueryHandlerDef["handler"]>[1];
+
+async function loadBooks(
+  ctx: QueryCtx,
+): Promise<{ accounts: LedgerAccount[]; entries: LedgerEntry[] }> {
+  const accountRows = await selectMany(ctx.db.raw, accountTable, { tenantId: ctx.user.tenantId });
+  const txRows = await selectMany(ctx.db.raw, transactionTable, { tenantId: ctx.user.tenantId });
+  return { accounts: toAccounts(accountRows), entries: toEntries(txRows) };
+}
+
+// Per-account balances (natural sign) + the trial balance (Σ raw = 0 invariant).
+export function createBalancesReportHandler(
+  access: AccessRule = DEFAULT_LEDGER_ACCESS,
+): QueryHandlerDef {
+  return {
+    name: "report:balances",
+    schema: periodSchema,
+    access,
+    handler: async (query, ctx) => {
+      const period = periodSchema.parse(query);
+      const { accounts, entries } = await loadBooks(ctx);
+      return accountBalances(accounts, entries, period);
+    },
+  };
+}
+
+// GuV — income − expense over the period.
+export function createIncomeStatementHandler(
+  access: AccessRule = DEFAULT_LEDGER_ACCESS,
+): QueryHandlerDef {
+  return {
+    name: "report:income-statement",
+    schema: periodSchema,
+    access,
+    handler: async (query, ctx) => {
+      const period = periodSchema.parse(query);
+      const { accounts, entries } = await loadBooks(ctx);
+      return incomeStatement(accounts, entries, period);
+    },
+  };
+}
+
+// Bilanz as of `to` — current result folded into equity so it balances.
+export function createBalanceSheetHandler(
+  access: AccessRule = DEFAULT_LEDGER_ACCESS,
+): QueryHandlerDef {
+  return {
+    name: "report:balance-sheet",
+    schema: periodSchema,
+    access,
+    handler: async (query, ctx) => {
+      const period = periodSchema.parse(query);
+      const { accounts, entries } = await loadBooks(ctx);
+      return balanceSheet(accounts, entries, period);
+    },
+  };
+}

package/src/ledger/handlers/reverse-transaction.write.ts

@@ -0,0 +1,48 @@
+import type { AccessRule, WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import { NotFoundError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import { generateId } from "@cosmicdrift/kumiko-framework/utils";
+import { DEFAULT_LEDGER_ACCESS } from "../constants";
+import { transactionExecutor } from "../executor";
+import type { Posting } from "../schemas";
+import { type ReverseTransactionPayload, reverseTransactionPayloadSchema } from "../schemas";
+
+// reverse-transaction (Storno) — the ONLY correction path for a posted entry.
+// Books the mirror image (every amount negated) as a new posted entry that
+// references the original, leaving the original untouched. This is why
+// transactions need no update/delete: the audit trail stays intact and the
+// mirror entry still satisfies Σ=0 (negating a zero-sum set stays zero-sum).
+export function createReverseTransactionHandler(
+  access: AccessRule = DEFAULT_LEDGER_ACCESS,
+): WriteHandlerDef {
+  return {
+    name: "reverse-transaction",
+    schema: reverseTransactionPayloadSchema,
+    access,
+    handler: async (event, ctx) => {
+      const payload = event.payload as ReverseTransactionPayload; // @cast-boundary engine-payload
+
+      const original = await transactionExecutor.detail({ id: payload.id }, event.user, ctx.db);
+      if (!original) return writeFailure(new NotFoundError("transaction", payload.id));
+
+      const originalLines = original["lines"] as readonly Posting[]; // @cast-boundary db-row
+      const lines = originalLines.map((l) => ({ accountId: l.accountId, amount: -l.amount }));
+
+      return transactionExecutor.create(
+        {
+          id: generateId(),
+          // Pass the original's date through untyped — create takes Record<string,
+          // unknown>, so no guess at the projection's date runtime type.
+          date: payload.date ?? original["date"],
+          description: payload.description ?? `Storno: ${String(original["description"])}`,
+          reference: payload.id,
+          status: "posted",
+          lines,
+        },
+        event.user,
+        ctx.db,
+      );
+    },
+  };
+}
+
+export const reverseTransactionHandler: WriteHandlerDef = createReverseTransactionHandler();

package/src/ledger/index.ts

@@ -0,0 +1,52 @@
+export {
+  ACCOUNT_TYPES,
+  type AccountType,
+  DEFAULT_LEDGER_ACCESS,
+  DEFAULT_LEDGER_ROLES,
+  LEDGER_FEATURE_NAME,
+  LedgerHandlers,
+  LedgerQueries,
+  TRANSACTION_STATUS,
+  type TransactionStatus,
+} from "./constants";
+export { accountEntity, transactionEntity } from "./entity";
+export {
+  createLedgerFeature,
+  type LedgerFeatureOptions,
+  ledgerFeature,
+} from "./feature";
+export {
+  createCreateTransactionHandler,
+  createTransactionHandler,
+} from "./handlers/create-transaction.write";
+export {
+  createBalanceSheetHandler,
+  createBalancesReportHandler,
+  createIncomeStatementHandler,
+} from "./handlers/reports.query";
+export {
+  createReverseTransactionHandler,
+  reverseTransactionHandler,
+} from "./handlers/reverse-transaction.write";
+export {
+  type AccountBalance,
+  accountBalances,
+  type BalanceSheet,
+  type BalancesReport,
+  balanceSheet,
+  type IncomeStatement,
+  incomeStatement,
+  type LedgerAccount,
+  type LedgerEntry,
+  type Period,
+  rawBalances,
+} from "./reports";
+export {
+  accountTypeSchema,
+  type CreateTransactionPayload,
+  createTransactionPayloadSchema,
+  type Posting,
+  postingSchema,
+  type ReverseTransactionPayload,
+  reverseTransactionPayloadSchema,
+} from "./schemas";

package/src/ledger/reports.ts

@@ -0,0 +1,164 @@
+import { parseJsonSafe } from "@cosmicdrift/kumiko-framework/utils";
+import type { AccountType } from "./constants";
+import type { Posting } from "./schemas";
+
+// Pure report aggregation over posted journal entries. No DB, no IO — the query
+// handlers fetch accounts + transactions (selectMany) and feed them here, so the
+// accounting logic is fully unit-testable. v1 aggregates over the transaction
+// list directly (query-first); a flat read_ledger_postings projection is the
+// documented materialisation upgrade for when this is measurably slow.
+
+export type LedgerAccount = {
+  readonly id: string;
+  readonly name: string;
+  readonly type: AccountType;
+};
+
+export type LedgerEntry = {
+  readonly status: string;
+  readonly date: string;
+  readonly lines: readonly Posting[];
+};
+
+export type Period = { readonly from?: string; readonly to?: string };
+
+// asset/expense are debit-normal (a positive raw balance = normal side);
+// liability/equity/income are credit-normal (negative raw = normal side).
+const DEBIT_NORMAL: ReadonlySet<AccountType> = new Set<AccountType>(["asset", "expense"]);
+
+function naturalBalance(type: AccountType, raw: number): number {
+  const n = DEBIT_NORMAL.has(type) ? raw : -raw;
+  return n === 0 ? 0 : n; // avoid -0 for credit-normal accounts with a 0 balance
+}
+
+// jsonb lines surface as a parsed array or a JSON string depending on the driver
+// path — normalise so the pure fns always get Posting[].
+export function normalizeLines(raw: unknown): Posting[] {
+  const value = typeof raw === "string" ? parseJsonSafe<unknown>(raw, null) : raw;
+  return Array.isArray(value) ? (value as Posting[]) : []; // @cast-boundary db-row
+}
+
+export function toAccounts(rows: readonly Record<string, unknown>[]): LedgerAccount[] {
+  return rows.map((r) => ({
+    id: r["id"] as string, // @cast-boundary db-row
+    name: r["name"] as string, // @cast-boundary db-row
+    type: r["type"] as AccountType, // @cast-boundary db-row
+  }));
+}
+
+export function toEntries(rows: readonly Record<string, unknown>[]): LedgerEntry[] {
+  return rows.map((r) => ({
+    status: r["status"] as string, // @cast-boundary db-row
+    date: String(r["date"]),
+    lines: normalizeLines(r["lines"]),
+  }));
+}
+
+function inPeriod(date: string, period?: Period): boolean {
+  if (period?.from !== undefined && date < period.from) return false;
+  if (period?.to !== undefined && date > period.to) return false;
+  return true;
+}
+
+// Raw signed balance (Soll +, Haben −) per accountId over POSTED entries in the
+// period. Draft entries never count toward the books.
+export function rawBalances(entries: readonly LedgerEntry[], period?: Period): Map<string, number> {
+  const out = new Map<string, number>();
+  for (const e of entries) {
+    if (e.status !== "posted") continue;
+    if (!inPeriod(e.date, period)) continue;
+    for (const l of e.lines) {
+      out.set(l.accountId, (out.get(l.accountId) ?? 0) + l.amount);
+    }
+  }
+  return out;
+}
+
+export type AccountBalance = {
+  readonly id: string;
+  readonly name: string;
+  readonly type: AccountType;
+  readonly balance: number; // natural (sign-corrected by type)
+};
+
+export type BalancesReport = {
+  readonly accounts: readonly AccountBalance[];
+  // Σ of every RAW balance — 0 on a consistent ledger (the trial balance),
+  // because every entry sums to 0. The golden invariant.
+  readonly trialBalance: number;
+};
+
+export function accountBalances(
+  accounts: readonly LedgerAccount[],
+  entries: readonly LedgerEntry[],
+  period?: Period,
+): BalancesReport {
+  const raw = rawBalances(entries, period);
+  const rows = accounts.map((a) => ({
+    id: a.id,
+    name: a.name,
+    type: a.type,
+    balance: naturalBalance(a.type, raw.get(a.id) ?? 0),
+  }));
+  let trial = 0;
+  for (const v of raw.values()) trial += v;
+  return { accounts: rows, trialBalance: trial };
+}
+
+export type IncomeStatement = {
+  readonly income: number;
+  readonly expense: number;
+  readonly netIncome: number;
+};
+
+export function incomeStatement(
+  accounts: readonly LedgerAccount[],
+  entries: readonly LedgerEntry[],
+  period?: Period,
+): IncomeStatement {
+  const raw = rawBalances(entries, period);
+  let income = 0;
+  let expense = 0;
+  for (const a of accounts) {
+    const nat = naturalBalance(a.type, raw.get(a.id) ?? 0);
+    if (a.type === "income") income += nat;
+    else if (a.type === "expense") expense += nat;
+  }
+  return { income, expense, netIncome: income - expense };
+}
+
+export type BalanceSheet = {
+  readonly assets: number;
+  readonly liabilities: number;
+  readonly equity: number; // includes currentResult
+  readonly currentResult: number; // laufendes Ergebnis = net income to date
+  readonly balances: boolean; // assets === liabilities + equity
+};
+
+// Balance sheet as of a date — pass the period as { to: asOf } (cumulative). The
+// current result (net income to date) is folded into equity as the "laufendes
+// Ergebnis" line, so the statement balances WITHOUT a period-close: assets =
+// liabilities + equity holds because the trial balance is 0.
+export function balanceSheet(
+  accounts: readonly LedgerAccount[],
+  entries: readonly LedgerEntry[],
+  period?: Period,
+): BalanceSheet {
+  const raw = rawBalances(entries, period);
+  let assets = 0;
+  let liabilities = 0;
+  let equityBase = 0;
+  let income = 0;
+  let expense = 0;
+  for (const a of accounts) {
+    const nat = naturalBalance(a.type, raw.get(a.id) ?? 0);
+    if (a.type === "asset") assets += nat;
+    else if (a.type === "liability") liabilities += nat;
+    else if (a.type === "equity") equityBase += nat;
+    else if (a.type === "income") income += nat;
+    else if (a.type === "expense") expense += nat;
+  }
+  const currentResult = income - expense;
+  const equity = equityBase + currentResult;
+  return { assets, liabilities, equity, currentResult, balances: assets === liabilities + equity };
+}

package/src/ledger/schemas.ts

@@ -0,0 +1,51 @@
+import { z } from "zod";
+import { ACCOUNT_TYPES, TRANSACTION_STATUS } from "./constants";
+
+// A posting line. amount is integer minor units (cents), SIGNED: Soll/debit > 0,
+// Haben/credit < 0. Integer → the balance check is exact (=== 0), no float epsilon.
+export const postingSchema = z.object({
+  accountId: z.string().min(1).max(64),
+  amount: z.number().int(),
+});
+export type Posting = z.infer<typeof postingSchema>;
+
+const sumIsZero = (lines: readonly Posting[]): boolean =>
+  lines.reduce((s, l) => s + l.amount, 0) === 0;
+
+const touchesTwoAccounts = (lines: readonly Posting[]): boolean =>
+  new Set(lines.map((l) => l.accountId)).size >= 2;
+
+// create-transaction — a balanced journal entry. The two invariants of
+// double-entry live here at the command boundary: every entry balances (Σ=0)
+// and moves value between at least two distinct accounts.
+export const createTransactionPayloadSchema = z
+  .object({
+    date: z.string().min(1).max(32), // ISO booking date
+    description: z.string().min(1).max(200),
+    reference: z.string().max(120).optional(),
+    // Defaults to "posted" in the handler. draft lifecycle (editable) lands with
+    // the Soll/recurring work — Phase 0 only ever creates posted entries.
+    status: z.enum(TRANSACTION_STATUS).optional(),
+    lines: z.array(postingSchema).min(2),
+  })
+  .refine((p) => sumIsZero(p.lines), {
+    message: "Transaction must balance: Σ of posting amounts must equal 0",
+    path: ["lines"],
+  })
+  .refine((p) => touchesTwoAccounts(p.lines), {
+    message: "Transaction must touch at least 2 distinct accounts",
+    path: ["lines"],
+  });
+export type CreateTransactionPayload = z.infer<typeof createTransactionPayloadSchema>;
+
+// reverse-transaction (Storno) — corrects a posted entry by booking its mirror,
+// never by mutating it. Optional date/description for the reversing entry.
+export const reverseTransactionPayloadSchema = z.object({
+  id: z.string().min(1).max(64),
+  date: z.string().min(1).max(32).optional(),
+  description: z.string().min(1).max(200).optional(),
+});
+export type ReverseTransactionPayload = z.infer<typeof reverseTransactionPayloadSchema>;
+
+// Re-export so callers building accounts have the type vocabulary in one place.
+export const accountTypeSchema = z.enum(ACCOUNT_TYPES);