@cosmicdrift/kumiko-framework 0.362.0 → 0.364.0

package/agents/examples/lane-routing.md

@@ -0,0 +1,246 @@
+<!-- Generated by `bun run gen:agent-docs` from samples/recipes/lane-routing. Do not edit. -->
+
+# lane-routing
+
+runIn lane-routing: r.job pinned to api/worker deploy-lanes, event-chain via ctx.appendEvent, verified end-to-end through createAllInOneEntrypoint.
+
+## README
+
+# Lane Routing
+
+Pin jobs to deploy lanes (`api` | `worker`) with event-triggered fan-out.
+
+## What it shows
+
+- `r.job({ runIn: "worker" })` after an HTTP write
+- End-to-end verification via `createAllInOneEntrypoint`
+
+## Source
+
+Feature entry point: `src/feature.ts`.
+
+## Tests
+
+Needs a running Postgres and `TEST_DATABASE_URL` set (e.g. `postgres://postgres:postgres@127.0.0.1:5432/postgres`, see `demo/.env.example`).
+
+```bash
+cd samples/recipes/lane-routing
+bun test
+```
+
+## Source files
+
+### src/__tests__/feature.integration.test.ts
+
+```ts
+// Lane-Routing Sample — End-to-End Proof
+//
+// What we're proving (via createAllInOneEntrypoint + BullMQ + Hono — no
+// framework-internal shortcuts):
+//   1. A write lands on the HTTP surface.
+//   2. The command-dispatcher fires `jobRunner.handleEvent` as an
+//      afterCommit-hook (welle-2.5-gap fix, auto-wired by the entrypoint).
+//   3. Both `runIn: "worker"` jobs fan out onto the `kumiko-jobs-worker`
+//      queue and execute — the worker-side BullMQ worker picks them up,
+//      the api-side one does not (even in all-in-one, the lane-scoped
+//      dispatch() routes the job to the right queue).
+//
+// If the feature were wired with `runLocalJobs: true`-style api-lane
+// jobs, the scaling.md pick-guide would apply — this sample stays
+// worker-only because that's the prod default.
+
+import { afterAll, afterEach, beforeAll, describe, expect, test } from "bun:test";
+import { createRegistry } from "@cosmicdrift/kumiko-framework/engine";
+import { createAllInOneEntrypoint } from "@cosmicdrift/kumiko-framework/entrypoint";
+import {
+  createArchivedStreamsTable,
+  createEventsTable,
+} from "@cosmicdrift/kumiko-framework/event-store";
+import { createEventConsumerStateTable } from "@cosmicdrift/kumiko-framework/pipeline";
+import {
+  createTestDb,
+  createTestRedis,
+  type TestDb,
+  type TestRedis,
+  TestUsers,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { waitFor } from "@cosmicdrift/kumiko-framework/testing";
+import { createLaneRoutingFeature, renderedReceipts, sentConfirmations } from "../feature";
+
+const JWT = "lane-routing-sample-secret-minimum-32-chars!";
+const adminUser = TestUsers.admin;
+
+let testDb: TestDb;
+let testRedis: TestRedis;
+
+beforeAll(async () => {
+  [testDb, testRedis] = await Promise.all([createTestDb(), createTestRedis()]);
+  await createEventsTable(testDb.db);
+  await createArchivedStreamsTable(testDb.db);
+  await createEventConsumerStateTable(testDb.db);
+});
+
+afterAll(async () => {
+  await Promise.all([testDb.cleanup(), testRedis.cleanup()]);
+});
+
+afterEach(() => {
+  renderedReceipts.length = 0;
+  sentConfirmations.length = 0;
+});
+
+describe("lane-routing sample", () => {
+  test("order.create fans out to render-receipt + send-confirmation on the worker lane", async () => {
+    const registry = createRegistry([createLaneRoutingFeature()]);
+    const redisUrl = `redis://${testRedis.redis.options.host}:${testRedis.redis.options.port}/${testRedis.redis.options.db}`;
+    const entry = createAllInOneEntrypoint({
+      registry,
+      context: { db: testDb.db, redis: testRedis.redis },
+      jwtSecret: JWT,
+      redisUrl,
+      queueNamePrefix: `lane-routing-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+    });
+    await entry.start();
+    try {
+      const token = await entry.jwt.sign(adminUser);
+      const res = await entry.app.request("/api/write", {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${token}`,
+        },
+        body: JSON.stringify({
+          type: "orders:write:order:create",
+          payload: { customerName: "Acme GmbH", amount: 299 },
+        }),
+      });
+      const result = (await res.json()) as { isSuccess: boolean };
+      expect(result.isSuccess).toBe(true);
+
+      // Both jobs are declared runIn:"worker" — they enqueue into
+      // kumiko-jobs-worker-*, and the all-in-one worker runner consumes
+      // them. Without welle-2.6 the enqueue would drop silently (welle-2.5
+      // gap) or the routing would hit the wrong queue.
+      await waitFor(() => {
+        expect(renderedReceipts).toHaveLength(1);
+        expect(sentConfirmations).toHaveLength(1);
+        expect(renderedReceipts[0]?.customerName).toBe("Acme GmbH");
+        expect(sentConfirmations[0]?.amount).toBe(299);
+      });
+    } finally {
+      await entry.stop();
+    }
+  });
+});
+```
+
+### src/feature.ts
+
+```ts
+// Lane-Routing Sample
+//
+// Shows `r.job({ runIn: "worker" })` end-to-end: an HTTP write emits an
+// event, the event fans out to two worker-lane jobs via BullMQ, and the
+// jobs actually execute on the worker lane (kumiko-jobs-worker queue).
+//
+// Deploy-shape: any of the three entrypoints. The test uses
+// createAllInOneEntrypoint so the Single Integration-Test covers the full
+// path without having to coordinate two processes.
+
+import {
+  createEntity,
+  createNumberField,
+  createTextField,
+  defineFeature,
+  type FeatureDefinition,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
+
+// In-memory collectors so the integration-test can assert both jobs ran
+// and got the right payload. A real app would do DB writes, HTTP calls,
+// PDF rendering, mail sending — whatever the side-effect is, it's
+// opaque to the framework.
+export const renderedReceipts: Array<{ customerName: string; amount: number }> = [];
+export const sentConfirmations: Array<{ customerName: string; amount: number }> = [];
+
+// Entity-Dekl sichert den qualified-name-Prefix "orders:write:order:create"
+// für den Write-Handler unten und damit den Job-Trigger auf diesem Event.
+// Persistenz passiert im Custom-Handler nicht (id ist hardcoded für den
+// Sample-Test) — in einer echten App würde ein entityWriteHandler in die DB
+// schreiben.
+const orderEntity = createEntity({
+  table: "read_orders",
+  fields: {
+    customerName: createTextField({ personal: { of: "id" }, find: "none", required: true }),
+    amount: createNumberField({ required: true }),
+  },
+});
+
+export function createLaneRoutingFeature(): FeatureDefinition {
+  return defineFeature("orders", (r) => {
+    r.entity("order", orderEntity);
+
+    // Write handler — runs in the API process (or wherever the command
+    // lands). Event "orders:write:order:create" is the auto-generated
+    // write-event both jobs trigger on.
+    r.writeHandler(
+      "order:create",
+      z.object({
+        customerName: z.string().min(1),
+        amount: z.number().positive(),
+      }),
+      async (event) => ({
+        isSuccess: true as const,
+        data: {
+          id: 1,
+          customerName: event.payload.customerName,
+          amount: event.payload.amount,
+        },
+      }),
+      {
+        access: {
+          openToAll: {
+            reason:
+              "demo recipe: any signed-in user may place an order; the handler is a stub with no persistence",
+          },
+        },
+      },
+    );
+
+    // Receipt-rendering: heavy CPU work. Pinned to `worker` so the
+    // BullMQ consumer on the API process never picks it up — even if the
+    // API happens to run runLocalJobs for something else. `runIn` is the
+    // Welle-2.6 contract that makes this stable across deploy shapes.
+    r.job(
+      "render-receipt",
+      {
+        trigger: { on: "orders:write:order:create" },
+        runIn: "worker",
+      },
+      async (payload) => {
+        renderedReceipts.push({
+          customerName: payload["customerName"] as string,
+          amount: payload["amount"] as number,
+        });
+      },
+    );
+
+    // Confirmation-mail: external I/O. Also worker-lane. Both jobs fan
+    // out from the same event in parallel — BullMQ handles their order
+    // independently.
+    r.job(
+      "send-confirmation",
+      {
+        trigger: { on: "orders:write:order:create" },
+        runIn: "worker",
+      },
+      async (payload) => {
+        sentConfirmations.push({
+          customerName: payload["customerName"] as string,
+          amount: payload["amount"] as number,
+        });
+      },
+    );
+  });
+}
+```

package/agents/examples/ledger-banking.md

@@ -0,0 +1,214 @@
+<!-- Generated by `bun run gen:agent-docs` from samples/recipes/ledger-banking. Do not edit. -->
+
+# ledger-banking
+
+Bank accounts + transfers on the ledger primitive — balances are pure queries, never stored.
+
+## README
+
+# Ledger Banking
+
+Model bank accounts and transfers on the `ledger` primitive. This is the
+simplest double-entry case: every account is an `asset`, a transfer is **one
+balanced transaction**, and a balance is a **pure query** over the postings —
+never a stored field you keep in sync.
+
+## What it shows
+
+A transfer moves money between two bank accounts as a single balanced transaction, and every balance is a pure query over the postings rather than a stored field you keep in sync.
+
+- **A transfer is one transaction, not two updates** — moving €200 from
+  checking to savings is a single `ledger:write:create-transaction` that debits
+  savings (`+20000`) and credits checking (`−20000`). The two lines sum to 0,
+  which is what makes the entry _balanced_; the framework rejects anything else.
+- **Balances are derived, never stored** — there is no `balance` column on an
+  account. `ledger:query:report:balances` sums the postings on the fly and
+  applies each account's natural sign (asset = debit-normal).
+- **The trial balance is the safety net** — because every entry sums to 0, the
+  sum of _all_ postings is always 0. The flow asserts it after the transfers:
+  if it ever drifts, the books are inconsistent.
+- **Cents are signed integers** — amounts are integer minor units; `+` is a
+  debit, `−` is a credit. No floats, no rounding drift.
+
+## The banking flow
+
+The flow below is embedded from `usage.ts` and is run end-to-end against the
+real dispatcher + DB by this recipe's integration test (`the documented
+bankingFlow …`):
+
+```ts file=<rootDir>/_samples/recipes-ledger-banking/src/usage.ts
+```
+
+## Why no `feature.ts`?
+
+Unlike most recipes, banking mounts no host feature — the `ledger` bundle _is_
+the host. Accounts and transactions are its own entities, so the recipe just
+dispatches `ledger:*` handlers. Mount it once with `createLedgerFeature()` and
+the whole chart of accounts + journal is available.
+
+## Run
+
+Needs a running Postgres and `TEST_DATABASE_URL` set (e.g. `postgres://postgres:postgres@127.0.0.1:5432/postgres`, see `demo/.env.example`).
+
+```bash
+bun test src/__tests__/feature.integration.test.ts
+```
+
+## Source files
+
+### src/__tests__/feature.integration.test.ts
+
+```ts
+// Ledger Banking — integration test.
+//
+// Proves the documented bankingFlow end-to-end via the real dispatcher + DB:
+// two asset accounts funded from equity, one transfer between them, and the
+// balances read back as a pure query. The trial balance stays 0 — the golden
+// double-entry invariant.
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import {
+  accountEntity,
+  createLedgerFeature,
+  transactionEntity,
+} from "@cosmicdrift/kumiko-bundled-features/ledger";
+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 { bankingFlow, type LedgerClient } from "../usage";
+
+const admin = createTestUser({ roles: ["TenantAdmin"] });
+const ledger = createLedgerFeature();
+
+let stack: TestStack;
+
+// Adapt the test stack to the host-facing LedgerClient the docs embed uses.
+const client: LedgerClient = {
+  write: <T>(type: string, payload: unknown) => stack.http.writeOk<T>(type, payload, admin),
+  query: <T>(type: string, payload: unknown) => stack.http.queryOk<T>(type, payload, admin),
+};
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [ledger] });
+  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");
+});
+
+describe("ledger-banking recipe — transfer + derived balance", () => {
+  test("the documented bankingFlow funds, transfers, and reads balances back", async () => {
+    const result = await bankingFlow(client);
+
+    expect(result.checking).toBe(80000);
+    expect(result.savings).toBe(20000);
+    // A transfer never destroys value — the books stay consistent.
+    expect(result.trialBalance).toBe(0);
+  });
+});
+```
+
+### src/usage.ts
+
+```ts
+// Ledger Banking — money on accounts, moved by balanced transactions.
+//
+// Banking is the simplest double-entry case: each bank account is an `asset`,
+// and a transfer is ONE transaction that debits the receiving account (+) and
+// credits the sending one (−). The two lines sum to 0 — that is what makes the
+// entry "balanced". No balance is ever stored; it's a pure query over the
+// postings (ledger:query:report:balances).
+//
+// This recipe's integration test runs `bankingFlow` below against the real
+// dispatcher + DB.
+
+// The bundle exports its qualified handler/query names — use them instead of
+// hardcoding the wire strings.
+import {
+  type AccountType,
+  LedgerHandlers,
+  LedgerQueries,
+} from "@cosmicdrift/kumiko-bundled-features/ledger";
+
+// The minimal surface the flow needs from a host dispatcher. An app's client
+// satisfies this; the integration test adapts the test stack to it.
+export type LedgerClient = {
+  write: <T>(type: string, payload: unknown) => Promise<T>;
+  query: <T>(type: string, payload: unknown) => Promise<T>;
+};
+
+type BalancesReport = {
+  accounts: Array<{ id: string; name: string; balance: number }>;
+  trialBalance: number;
+};
+
+// Open an account in the tenant's chart of accounts → returns its id.
+async function openAccount(client: LedgerClient, name: string, type: AccountType): Promise<string> {
+  const { id } = await client.write<{ id: string }>(LedgerHandlers.createAccount, { name, type });
+  return id;
+}
+
+// A transfer is one balanced transaction: debit the receiver (+amount), credit
+// the sender (−amount). Amounts are signed integer minor units (cents).
+async function transfer(
+  client: LedgerClient,
+  opts: { from: string; to: string; amount: number; description: string; date: string },
+): Promise<void> {
+  await client.write(LedgerHandlers.createTransaction, {
+    date: opts.date,
+    description: opts.description,
+    lines: [
+      { accountId: opts.to, amount: opts.amount },
+      { accountId: opts.from, amount: -opts.amount },
+    ],
+  });
+}
+
+// Fund a checking account from equity, move €200 of it to savings, then read
+// the closing balances back. Returns the balances + the trial balance (Σ of all
+// raw postings — 0 on a consistent ledger).
+export async function bankingFlow(client: LedgerClient) {
+  const opening = await openAccount(client, "Anfangsbestand", "equity");
+  const checking = await openAccount(client, "Girokonto", "asset");
+  const savings = await openAccount(client, "Sparkonto", "asset");
+
+  await transfer(client, {
+    from: opening,
+    to: checking,
+    amount: 100000,
+    description: "Anfangsbestand Girokonto",
+    date: "2026-01-01",
+  });
+
+  await transfer(client, {
+    from: checking,
+    to: savings,
+    amount: 20000,
+    description: "Sparrate Januar",
+    date: "2026-01-05",
+  });
+
+  const report = await client.query<BalancesReport>(LedgerQueries.reportBalances, {});
+  const balanceOf = (id: string) => report.accounts.find((a) => a.id === id)?.balance ?? 0;
+
+  return {
+    checking: balanceOf(checking), // 80000 — €1,000 funded − €200 moved out
+    savings: balanceOf(savings), // 20000 — €200 moved in
+    trialBalance: report.trialBalance, // 0 — the books are consistent
+  };
+}
+```

package/agents/examples/ledger-invoicing.md

@@ -0,0 +1,235 @@
+<!-- Generated by `bun run gen:agent-docs` from samples/recipes/ledger-invoicing. Do not edit. -->
+
+# ledger-invoicing
+
+Accrual invoicing on the ledger primitive — revenue at invoice time, VAT as a liability, receivable cleared on payment.
+
+## README
+
+# Ledger Invoicing
+
+Model accrual invoicing (Rechnungswesen) on the `ledger` primitive. Issuing an
+invoice and receiving its payment are **two separate transactions**, and
+revenue is recognised when the invoice is **issued** — not when the cash
+arrives. This is the difference between banking (cash moves) and accounting
+(obligations are recorded as they arise).
+
+## What it shows
+
+Accrual accounting recognises revenue when an invoice is issued, not when the cash arrives: the invoice and its payment are two separate transactions, VAT is held as a liability, and the receivable clears to zero once paid.
+
+- **Accrual: revenue at invoice time** — issuing the invoice debits Forderungen
+  (accounts receivable) and credits Erlöse (income). The revenue is on the P&L
+  immediately; the flow asserts it via `report:income-statement` _before_ any
+  payment exists.
+- **VAT is a liability, not income** — the gross €1,190 splits into €1,000 net
+  revenue and €190 Umsatzsteuer. The VAT is money you owe the tax office, so it
+  lands on a `liability` account, never inflating revenue.
+- **The receivable has a lifecycle** — it's raised at the gross amount on
+  invoice and cleared to 0 on payment (debit Bank / credit Forderungen). An open
+  receivable balance _is_ your "unpaid invoices" total, with no extra bookkeeping.
+- **Reports re-derive, payment doesn't double-count income** — booking the
+  payment moves cash and settles the receivable; it touches no income account,
+  so revenue stays €1,000.
+
+## The invoicing flow
+
+The flow below is embedded from `usage.ts` and is run end-to-end against the
+real dispatcher + DB by this recipe's integration test (`the documented
+invoicingFlow …`):
+
+```ts file=<rootDir>/_samples/recipes-ledger-invoicing/src/usage.ts
+```
+
+## Banking vs. invoicing
+
+Both recipes use the same primitive — accounts + balanced transactions — but
+record different things:
+
+| | [ledger-banking](../ledger-banking/) | ledger-invoicing |
+|---|---|---|
+| Accounts | all `asset` (bank accounts) | `asset` + `income` + `liability` |
+| A transaction is… | a transfer (cash moves) | an obligation (invoice) or its settlement |
+| Revenue recognised | n/a | at invoice time (accrual) |
+| Reports surfaced | balances | balances + P&L |
+
+## Run
+
+Needs a running Postgres and `TEST_DATABASE_URL` set (e.g. `postgres://postgres:postgres@127.0.0.1:5432/postgres`, see `demo/.env.example`).
+
+```bash
+bun test src/__tests__/feature.integration.test.ts
+```
+
+## Source files
+
+### src/__tests__/feature.integration.test.ts
+
+```ts
+// Ledger Invoicing — integration test.
+//
+// Proves the documented invoicingFlow end-to-end via the real dispatcher + DB:
+//   - issuing an invoice recognises revenue immediately (accrual), splits VAT
+//     off as a liability, and raises a receivable for the gross amount
+//   - the payment clears the receivable and brings in the cash — without
+//     touching the P&L a second time
+//   - the trial balance stays 0 throughout
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import {
+  accountEntity,
+  createLedgerFeature,
+  transactionEntity,
+} from "@cosmicdrift/kumiko-bundled-features/ledger";
+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 { invoicingFlow, type LedgerClient } from "../usage";
+
+const admin = createTestUser({ roles: ["TenantAdmin"] });
+const ledger = createLedgerFeature();
+
+let stack: TestStack;
+
+const client: LedgerClient = {
+  write: <T>(type: string, payload: unknown) => stack.http.writeOk<T>(type, payload, admin),
+  query: <T>(type: string, payload: unknown) => stack.http.queryOk<T>(type, payload, admin),
+};
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [ledger] });
+  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");
+});
+
+describe("ledger-invoicing recipe — accrual + receivable lifecycle", () => {
+  test("the documented invoicingFlow recognises revenue at invoice time, clears AR on payment", async () => {
+    const result = await invoicingFlow(client);
+
+    // Revenue recognised when invoiced — before any cash moved.
+    expect(result.revenueBeforePayment).toBe(100000);
+    // Payment doesn't double-count income — revenue is still €1,000 afterwards.
+    expect(result.revenueAfterPayment).toBe(100000);
+    // Receivable settled once paid.
+    expect(result.receivablesAfterPayment).toBe(0);
+    // Gross cash in; VAT held as a liability owed to the tax office.
+    expect(result.bank).toBe(119000);
+    expect(result.vatOwed).toBe(19000);
+    expect(result.trialBalance).toBe(0);
+  });
+});
+```
+
+### src/usage.ts
+
+```ts
+// Ledger Invoicing — accrual accounting (Rechnungswesen).
+//
+// Issuing an invoice and receiving its payment are TWO separate transactions,
+// and revenue is recognised when the invoice is ISSUED (accrual), not when the
+// cash arrives:
+//
+//   1. Issue:   debit Forderungen (asset, accounts receivable) for the GROSS
+//               amount, credit Erlöse (income) for the NET and Umsatzsteuer
+//               (liability) for the VAT. Revenue hits the P&L now.
+//   2. Payment: debit Bank (asset), credit Forderungen — the receivable nets
+//               back to 0 once the customer has paid.
+//
+// This recipe's integration test runs `invoicingFlow` below against the real
+// dispatcher + DB.
+
+import {
+  type AccountType,
+  LedgerHandlers,
+  LedgerQueries,
+} from "@cosmicdrift/kumiko-bundled-features/ledger";
+
+export type LedgerClient = {
+  write: <T>(type: string, payload: unknown) => Promise<T>;
+  query: <T>(type: string, payload: unknown) => Promise<T>;
+};
+
+type BalancesReport = {
+  accounts: Array<{ id: string; name: string; balance: number }>;
+  trialBalance: number;
+};
+
+async function openAccount(client: LedgerClient, name: string, type: AccountType): Promise<string> {
+  const { id } = await client.write<{ id: string }>(LedgerHandlers.createAccount, { name, type });
+  return id;
+}
+
+// Issue an invoice, observe that the revenue is already on the P&L before any
+// cash moves, then book the incoming payment. Returns the figures the test
+// asserts: accrual revenue, the cleared receivable, cash in, VAT owed.
+export async function invoicingFlow(client: LedgerClient) {
+  const receivables = await openAccount(client, "Forderungen", "asset");
+  const revenue = await openAccount(client, "Erlöse", "income");
+  const vat = await openAccount(client, "Umsatzsteuer", "liability");
+  const bank = await openAccount(client, "Bank", "asset");
+
+  // Invoice: net €1,000 + 19% VAT = €1,190 gross. One balanced 3-line entry.
+  await client.write(LedgerHandlers.createTransaction, {
+    date: "2026-02-01",
+    description: "Rechnung 2026-001",
+    reference: "INV-2026-001",
+    lines: [
+      { accountId: receivables, amount: 119000 }, // gross owed to us
+      { accountId: revenue, amount: -100000 }, // net revenue → income
+      { accountId: vat, amount: -19000 }, // VAT collected → liability
+    ],
+  });
+
+  // Revenue is recognised at invoice time — it's on the P&L before any payment.
+  const beforePayment = await client.query<{ income: number; netIncome: number }>(
+    LedgerQueries.reportIncomeStatement,
+    {},
+  );
+
+  // Payment arrives → Bank up, receivable cleared. Income does NOT change here.
+  await client.write(LedgerHandlers.createTransaction, {
+    date: "2026-02-20",
+    description: "Zahlung Rechnung 2026-001",
+    reference: "INV-2026-001",
+    lines: [
+      { accountId: bank, amount: 119000 },
+      { accountId: receivables, amount: -119000 },
+    ],
+  });
+
+  // The payment moved cash and cleared the receivable — it touched no income
+  // account, so the recognised revenue is unchanged.
+  const afterPayment = await client.query<{ income: number }>(
+    LedgerQueries.reportIncomeStatement,
+    {},
+  );
+
+  const balances = await client.query<BalancesReport>(LedgerQueries.reportBalances, {});
+  const balanceOf = (id: string) => balances.accounts.find((a) => a.id === id)?.balance ?? 0;
+
+  return {
+    revenueBeforePayment: beforePayment.income, // 100000 — accrual, cash-independent
+    revenueAfterPayment: afterPayment.income, // 100000 — payment doesn't double-count
+    receivablesAfterPayment: balanceOf(receivables), // 0 — invoice settled
+    bank: balanceOf(bank), // 119000 — gross cash received
+    vatOwed: balanceOf(vat), // 19000 — liability to the tax office
+    trialBalance: balances.trialBalance, // 0
+  };
+}
+```