@cosmicdrift/kumiko-bundled-features 0.94.0 → 0.96.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.94.0",
+  "version": "0.96.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>",
@@ -36,6 +36,7 @@
     "./folders/web": "./src/folders/web/index.ts",
     "./folders-user-data": "./src/folders-user-data/index.ts",
     "./ledger": "./src/ledger/index.ts",
+    "./ledger/web": "./src/ledger/web/index.ts",
     "./billing-foundation": "./src/billing-foundation/index.ts",
     "./subscription-stripe": "./src/subscription-stripe/index.ts",
     "./subscription-mollie": "./src/subscription-mollie/index.ts",
@@ -90,11 +91,11 @@
     "./step-dispatcher": "./src/step-dispatcher/index.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.94.0",
-    "@cosmicdrift/kumiko-framework": "0.94.0",
-    "@cosmicdrift/kumiko-headless": "0.94.0",
-    "@cosmicdrift/kumiko-renderer": "0.94.0",
-    "@cosmicdrift/kumiko-renderer-web": "0.94.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.96.0",
+    "@cosmicdrift/kumiko-framework": "0.96.0",
+    "@cosmicdrift/kumiko-headless": "0.96.0",
+    "@cosmicdrift/kumiko-renderer": "0.96.0",
+    "@cosmicdrift/kumiko-renderer-web": "0.96.0",
     "@mollie/api-client": "^4.5.0",
     "@node-rs/argon2": "^2.0.2",
     "@types/nodemailer": "^8.0.0",

package/src/folders/web/__tests__/folder-manager.test.tsx

@@ -165,4 +165,43 @@ describe("FolderManager filing mode", () => {
       expect(dispatchSpy).toHaveBeenCalledWith(FoldersHandlers.createFolder, { name: "Inbox" }),
     );
   });
+
+  test("a mixed-type tree files each leaf under its own entityType (per-leaf override + fallback)", async () => {
+    folderRows = [
+      { id: "f1", name: "A", parentId: null, version: 1 },
+      { id: "f2", name: "B", parentId: null, version: 1 },
+    ];
+    const mixed: FolderFiling = {
+      entityType: "credit", // tree default
+      leavesByFolder: new Map([["f1", [{ id: "b-1", label: "Bauspar 1", entityType: "bauspar" }]]]),
+      unfiled: [{ id: "c-1", label: "Credit 1" }], // no override → inherits "credit"
+      unfiledLabel: "Unfiled",
+      onReassigned: () => {},
+    };
+    render(
+      <Wrapper>
+        <FolderManager filing={mixed} />
+      </Wrapper>,
+    );
+
+    // The bauspar leaf carries its own entityType into the set-folder write…
+    dropLeaf("folder-node-f2", "b-1");
+    await waitFor(() =>
+      expect(dispatchSpy).toHaveBeenCalledWith(FoldersHandlers.setFolder, {
+        folderId: "f2",
+        entityType: "bauspar",
+        entityId: "b-1",
+      }),
+    );
+
+    // …while a leaf without an override still falls back to filing.entityType.
+    dropLeaf("folder-node-f1", "c-1");
+    await waitFor(() =>
+      expect(dispatchSpy).toHaveBeenCalledWith(FoldersHandlers.setFolder, {
+        folderId: "f1",
+        entityType: "credit",
+        entityId: "c-1",
+      }),
+    );
+  });
 });

package/src/folders/web/folder-manager.tsx

@@ -47,6 +47,10 @@ export type FolderLeaf = {
   readonly label: string;
   readonly trailing?: ReactNode;
   readonly onOpen?: () => void;
+  // Overrides filing.entityType for this leaf — lets one filing tree hold leaves
+  // of mixed entity types (e.g. credits + Bausparverträge), each filed/cleared
+  // under its own type. Omit for single-type trees.
+  readonly entityType?: string;
 };
 
 // Opt-in filing binding. Host computes the grouping (it already holds the
@@ -133,12 +137,21 @@ export function FolderManager({
   const rows = catalog.data?.rows ?? [];
   const tree = buildFolderTree(rows);
 
-  // entityId → current folder (null = unfiled) for the drop no-op guard.
+  // entityId → current folder (null = unfiled) for the drop no-op guard, and
+  // entityId → entityType so a mixed-type tree files each leaf under its own type.
   const currentFolderByEntity = new Map<string, string | null>();
+  const typeByEntity = new Map<string, string>();
   if (filing !== undefined) {
+    const typeOf = (leaf: FolderLeaf): string => leaf.entityType ?? filing.entityType;
     for (const [folderId, leaves] of filing.leavesByFolder)
-      for (const leaf of leaves) currentFolderByEntity.set(leaf.id, folderId);
-    for (const leaf of filing.unfiled) currentFolderByEntity.set(leaf.id, null);
+      for (const leaf of leaves) {
+        currentFolderByEntity.set(leaf.id, folderId);
+        typeByEntity.set(leaf.id, typeOf(leaf));
+      }
+    for (const leaf of filing.unfiled) {
+      currentFolderByEntity.set(leaf.id, null);
+      typeByEntity.set(leaf.id, typeOf(leaf));
+    }
   }
 
   const toggleCollapse = (id: string): void =>
@@ -228,12 +241,13 @@ export function FolderManager({
     if (filing === undefined) return;
     if ((currentFolderByEntity.get(entityId) ?? null) === folderId) return;
     setErrorKey(null);
+    const entityType = typeByEntity.get(entityId) ?? filing.entityType;
     const ok =
       folderId === null
-        ? await writeOk(FoldersHandlers.clearFolder, { entityType: filing.entityType, entityId })
+        ? await writeOk(FoldersHandlers.clearFolder, { entityType, entityId })
         : await writeOk(FoldersHandlers.setFolder, {
             folderId,
-            entityType: filing.entityType,
+            entityType,
             entityId,
           });
     if (ok) {

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

@@ -20,11 +20,11 @@ function writeAccess(
 }
 
 describe("createLedgerFeature shape", () => {
-  test("registers account + transaction entities, 4 write-handlers, 4 query-handlers", () => {
+  test("registers account + transaction + schedule entities, 7 write-handlers, 9 query-handlers", () => {
     const feature = createLedgerFeature();
 
     expect(Object.keys(feature.entities ?? {})).toEqual(
-      expect.arrayContaining(["account", "transaction"]),
+      expect.arrayContaining(["account", "transaction", "schedule"]),
     );
 
     expect(Object.keys(feature.writeHandlers)).toEqual(
@@ -33,9 +33,12 @@ describe("createLedgerFeature shape", () => {
         expect.stringMatching(/account:update/),
         expect.stringMatching(/create-transaction/),
         expect.stringMatching(/reverse-transaction/),
+        expect.stringMatching(/schedule:create/),
+        expect.stringMatching(/schedule:update/),
+        expect.stringMatching(/confirm-schedule-period/),
       ]),
     );
-    expect(Object.keys(feature.writeHandlers)).toHaveLength(4);
+    expect(Object.keys(feature.writeHandlers)).toHaveLength(7);
 
     expect(Object.keys(feature.queryHandlers)).toEqual(
       expect.arrayContaining([
@@ -43,12 +46,14 @@ describe("createLedgerFeature shape", () => {
         expect.stringMatching(/account:detail/),
         expect.stringMatching(/transaction:list/),
         expect.stringMatching(/transaction:detail/),
+        expect.stringMatching(/schedule:list/),
+        expect.stringMatching(/schedule:detail/),
         expect.stringMatching(/report:balances/),
         expect.stringMatching(/report:income-statement/),
         expect.stringMatching(/report:balance-sheet/),
       ]),
     );
-    expect(Object.keys(feature.queryHandlers)).toHaveLength(7);
+    expect(Object.keys(feature.queryHandlers)).toHaveLength(9);
   });
 
   test("transaction is immutable: NO update/delete handler is registered", () => {

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

@@ -19,8 +19,9 @@ import {
   unsafeCreateEntityTable,
 } from "@cosmicdrift/kumiko-framework/stack";
 import { type AccountType, LedgerHandlers, LedgerQueries } from "../constants";
-import { accountEntity, transactionEntity } from "../entity";
+import { accountEntity, scheduleEntity, transactionEntity } from "../entity";
 import { createLedgerFeature } from "../feature";
+import { scheduleReference } from "../recurring";
 import type { Posting } from "../schemas";
 
 const ledgerFeature = createLedgerFeature();
@@ -31,6 +32,7 @@ beforeAll(async () => {
   stack = await setupTestStack({ features: [ledgerFeature] });
   await unsafeCreateEntityTable(stack.db, accountEntity);
   await unsafeCreateEntityTable(stack.db, transactionEntity);
+  await unsafeCreateEntityTable(stack.db, scheduleEntity);
   await createEventsTable(stack.db);
 });
 
@@ -42,6 +44,7 @@ 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");
+  await asRawClient(stack.db).unsafe("DELETE FROM read_ledger_schedules");
 });
 
 const admin = createTestUser({ roles: ["TenantAdmin"] });
@@ -298,3 +301,111 @@ describe("ledger integration — reports (end-to-end)", () => {
     expect(r.balances).toBe(true);
   });
 });
+
+describe("ledger integration — confirm-schedule-period (recurring)", () => {
+  async function createSchedule(
+    debitAccountId: string,
+    creditAccountId: string,
+    over: { amount?: number; description?: string; startDate?: string } = {},
+  ): Promise<string> {
+    const s = await stack.http.writeOk<{ id: string }>(
+      LedgerHandlers.createSchedule,
+      {
+        description: over.description ?? "Miete WE1",
+        startDate: over.startDate ?? "2026-01-01",
+        interval: "monthly",
+        amount: over.amount ?? 50000,
+        debitAccountId,
+        creditAccountId,
+      },
+      admin,
+    );
+    return s.id;
+  }
+
+  async function confirm(
+    scheduleId: string,
+    period: string,
+    amount?: number,
+  ): Promise<{ id: string }> {
+    return stack.http.writeOk<{ id: string }>(
+      LedgerHandlers.confirmSchedulePeriod,
+      amount === undefined ? { scheduleId, period } : { scheduleId, period, amount },
+      admin,
+    );
+  }
+
+  test("confirm books a balanced entry tagged with the schedule reference", async () => {
+    const bank = await createAccount("Bank", "asset");
+    const rent = await createAccount("Mieterträge", "income");
+    const scheduleId = await createSchedule(bank, rent);
+
+    await confirm(scheduleId, "2026-01");
+
+    const rows = await listTransactions();
+    expect(rows).toHaveLength(1);
+    expect(rows[0]?.["reference"]).toBe(scheduleReference(scheduleId, "2026-01"));
+    expect(rows[0]?.["description"]).toBe("Miete WE1");
+    const lines = linesOf(rows[0] as Record<string, unknown>);
+    expect(lines.find((l) => l.accountId === bank)?.amount).toBe(50000);
+    expect(lines.find((l) => l.accountId === rent)?.amount).toBe(-50000);
+    expect(trialBalance(rows)).toBe(0);
+  });
+
+  test("re-confirming the same period is an idempotent no-op (no second booking)", async () => {
+    const bank = await createAccount("Bank", "asset");
+    const rent = await createAccount("Mieterträge", "income");
+    const scheduleId = await createSchedule(bank, rent);
+
+    const first = await confirm(scheduleId, "2026-01");
+    const second = await confirm(scheduleId, "2026-01");
+
+    expect(second.id).toBe(first.id);
+    expect(await listTransactions()).toHaveLength(1);
+  });
+
+  test("amount override books the actual received amount", async () => {
+    const bank = await createAccount("Bank", "asset");
+    const rent = await createAccount("Mieterträge", "income");
+    const scheduleId = await createSchedule(bank, rent, { amount: 50000 });
+
+    await confirm(scheduleId, "2026-02", 48000);
+
+    const rows = await listTransactions();
+    expect(
+      linesOf(rows[0] as Record<string, unknown>).find((l) => l.accountId === bank)?.amount,
+    ).toBe(48000);
+  });
+
+  test("confirm fails (404) when the schedule names a non-existent account", async () => {
+    const bank = await createAccount("Bank", "asset");
+    const scheduleId = await createSchedule(bank, "00000000-0000-4000-8000-00000000dead");
+
+    const err = await stack.http.writeErr(
+      LedgerHandlers.confirmSchedulePeriod,
+      { scheduleId, period: "2026-01" },
+      admin,
+    );
+    expect(err.httpStatus).toBe(404);
+    expect(await listTransactions()).toHaveLength(0);
+  });
+
+  test("a stornoed period is re-confirmable → a fresh booking is written", async () => {
+    const bank = await createAccount("Bank", "asset");
+    const rent = await createAccount("Mieterträge", "income");
+    const scheduleId = await createSchedule(bank, rent);
+
+    const booked = await confirm(scheduleId, "2026-01");
+    await stack.http.writeOk(LedgerHandlers.reverseTransaction, { id: booked.id }, admin);
+
+    // Original + Storno present; the period now reads as un-booked → re-confirm books anew.
+    expect(await listTransactions()).toHaveLength(2);
+    const reconfirmed = await confirm(scheduleId, "2026-01", 48000);
+    expect(reconfirmed.id).not.toBe(booked.id);
+
+    const rows = await listTransactions();
+    expect(rows).toHaveLength(3);
+    // Books net to zero (original cancels Storno) plus the fresh 48000 confirmation.
+    expect(trialBalance(rows)).toBe(0);
+  });
+});

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

@@ -0,0 +1,136 @@
+import { describe, expect, test } from "bun:test";
+import {
+  type LedgerTxRow,
+  mergeScheduleActuals,
+  projectSchedule,
+  type ScheduleDef,
+  scheduleReference,
+} from "../recurring";
+
+// Pure projection + Soll/Ist merge — no DB, no Date API (the window/asOf are
+// params), so these are deterministic and cover the recurring primitive's logic
+// the integration test then proves end-to-end against a real dispatcher.
+
+const monthly = (over: Partial<ScheduleDef> = {}): ScheduleDef => ({
+  startDate: "2026-01-15",
+  interval: "monthly",
+  amount: 50000,
+  ...over,
+});
+
+describe("projectSchedule", () => {
+  test("projects one period per month across the window, clamped to startDate", () => {
+    const periods = projectSchedule(monthly(), { from: "2025-11", to: "2026-04" });
+    expect(periods.map((p) => p.period)).toEqual(["2026-01", "2026-02", "2026-03", "2026-04"]);
+    expect(periods.every((p) => p.amount === 50000)).toBe(true);
+    expect(periods[0]).toEqual({ period: "2026-01", date: "2026-01-01", amount: 50000 });
+  });
+
+  test("clamps the tail to endDate (inclusive)", () => {
+    const periods = projectSchedule(monthly({ endDate: "2026-03-31" }), {
+      from: "2026-01",
+      to: "2026-12",
+    });
+    expect(periods.map((p) => p.period)).toEqual(["2026-01", "2026-02", "2026-03"]);
+  });
+
+  test("open-ended schedule projects to the window end", () => {
+    const periods = projectSchedule(monthly(), { from: "2026-01", to: "2026-02" });
+    expect(periods.map((p) => p.period)).toEqual(["2026-01", "2026-02"]);
+  });
+
+  test("window entirely before startDate yields nothing", () => {
+    expect(projectSchedule(monthly(), { from: "2025-01", to: "2025-12" })).toEqual([]);
+  });
+
+  test("tolerates full ISO dates in the window bounds", () => {
+    const periods = projectSchedule(monthly(), { from: "2026-02-10", to: "2026-03-05" });
+    expect(periods.map((p) => p.period)).toEqual(["2026-02", "2026-03"]);
+  });
+});
+
+describe("mergeScheduleActuals", () => {
+  const ref = (period: string): string => scheduleReference("s1", period);
+  const confirmTx = (id: string, period: string, amount = 50000): LedgerTxRow => ({
+    id,
+    reference: ref(period),
+    lines: [
+      { accountId: "bank", amount },
+      { accountId: "rent", amount: -amount },
+    ],
+  });
+
+  const projection = projectSchedule(monthly(), { from: "2026-01", to: "2026-04" });
+
+  test("posted for a confirmed month, open for past-unbooked, forecast for future", () => {
+    const months = mergeScheduleActuals(
+      "s1",
+      projection,
+      [confirmTx("tx-jan", "2026-01")],
+      "2026-03",
+    );
+    expect(months.map((m) => [m.period, m.status])).toEqual([
+      ["2026-01", "posted"],
+      ["2026-02", "open"],
+      ["2026-03", "open"],
+      ["2026-04", "forecast"],
+    ]);
+    const jan = months[0];
+    expect(jan).toMatchObject({ planned: 50000, actual: 50000, txId: "tx-jan" });
+    expect(months[1]).toMatchObject({ actual: null, txId: null });
+  });
+
+  test("a reversed (stornoed) confirmation drops the month back to open + re-confirmable", () => {
+    const tx: LedgerTxRow[] = [
+      confirmTx("tx-jan", "2026-01"),
+      // Storno mirror: references the confirming tx's id (reverse-transaction shape).
+      {
+        id: "tx-storno",
+        reference: "tx-jan",
+        lines: [
+          { accountId: "bank", amount: -50000 },
+          { accountId: "rent", amount: 50000 },
+        ],
+      },
+    ];
+    const months = mergeScheduleActuals("s1", projection, tx, "2026-03");
+    expect(months[0]).toMatchObject({
+      period: "2026-01",
+      status: "open",
+      actual: null,
+      txId: null,
+    });
+  });
+
+  test("a re-confirmation after Storno posts again with the new tx", () => {
+    const tx: LedgerTxRow[] = [
+      confirmTx("tx-jan", "2026-01"),
+      {
+        id: "tx-storno",
+        reference: "tx-jan",
+        lines: [
+          { accountId: "bank", amount: -50000 },
+          { accountId: "rent", amount: 50000 },
+        ],
+      },
+      confirmTx("tx-jan-2", "2026-01", 48000), // re-confirmed, came in short
+    ];
+    const months = mergeScheduleActuals("s1", projection, tx, "2026-03");
+    expect(months[0]).toMatchObject({ status: "posted", actual: 48000, txId: "tx-jan-2" });
+  });
+
+  test("ignores transactions of other schedules", () => {
+    const tx: LedgerTxRow[] = [
+      {
+        id: "tx-other",
+        reference: scheduleReference("s2", "2026-01"),
+        lines: [
+          { accountId: "bank", amount: 50000 },
+          { accountId: "rent", amount: -50000 },
+        ],
+      },
+    ];
+    const months = mergeScheduleActuals("s1", projection, tx, "2026-03");
+    expect(months[0]).toMatchObject({ status: "open", txId: null });
+  });
+});

package/src/ledger/constants.ts

@@ -17,6 +17,11 @@ export const LedgerHandlers = {
   updateAccount: "ledger:write:account:update",
   createTransaction: "ledger:write:create-transaction",
   reverseTransaction: "ledger:write:reverse-transaction",
+  // Recurring schedules — the catalog's CRUD verbs plus the confirm verb that
+  // books one projected period as a balanced, idempotent entry.
+  createSchedule: "ledger:write:schedule:create",
+  updateSchedule: "ledger:write:schedule:update",
+  confirmSchedulePeriod: "ledger:write:confirm-schedule-period",
 } as const;
 
 export const LedgerQueries = {
@@ -24,6 +29,8 @@ export const LedgerQueries = {
   accountDetail: "ledger:query:account:detail",
   transactionList: "ledger:query:transaction:list",
   transactionDetail: "ledger:query:transaction:detail",
+  scheduleList: "ledger:query:schedule:list",
+  scheduleDetail: "ledger:query:schedule:detail",
   // Reports — pure aggregations over the posted entries (Phase 1).
   reportBalances: "ledger:query:report:balances",
   reportIncomeStatement: "ledger:query:report:income-statement",
@@ -39,6 +46,12 @@ export type AccountType = (typeof ACCOUNT_TYPES)[number];
 export const TRANSACTION_STATUS = ["draft", "posted"] as const;
 export type TransactionStatus = (typeof TRANSACTION_STATUS)[number];
 
+// Recurrence steps a schedule can project. Monthly is the only step v1 needs
+// (rent, loan rate, salary); weekly/quarterly/yearly add to projectSchedule when
+// a schedule actually requires them.
+export const SCHEDULE_INTERVALS = ["monthly"] as const;
+export type ScheduleInterval = (typeof SCHEDULE_INTERVALS)[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.

package/src/ledger/entity.ts

@@ -2,10 +2,11 @@ import {
   createDateField,
   createEntity,
   createJsonbField,
+  createNumberField,
   createSelectField,
   createTextField,
 } from "@cosmicdrift/kumiko-framework/engine";
-import { ACCOUNT_TYPES, TRANSACTION_STATUS } from "./constants";
+import { ACCOUNT_TYPES, SCHEDULE_INTERVALS, 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`
@@ -52,3 +53,28 @@ export const transactionEntity = createEntity({
     lines: createJsonbField(),
   },
 });
+
+// schedule — a recurring booking template (Dauerauftrag): "book `amount` from
+// debitAccount to creditAccount every period from startDate". Event-sourced CRUD
+// (create/update/list/detail); the framework projects `read_ledger_schedules`. It
+// holds NO bookings — the Soll (forecast) is a pure projection (projectSchedule)
+// and the Ist is materialised one period at a time by confirm-schedule-period,
+// which books a balanced transaction referencing scheduleReference(id, period).
+// amount is stored positive (minor units); the confirm handler assigns the signs.
+export const scheduleEntity = createEntity({
+  table: "read_ledger_schedules",
+  fields: {
+    description: createTextField({
+      required: true,
+      maxLength: 200,
+      allowPlaintext: "is-business-data",
+    }),
+    startDate: createDateField({ required: true }),
+    // Absent → open-ended (projects to the window's end).
+    endDate: createDateField(),
+    interval: createSelectField({ options: SCHEDULE_INTERVALS, required: true }),
+    amount: createNumberField({ required: true }),
+    debitAccountId: createTextField({ required: true, maxLength: 64 }),
+    creditAccountId: createTextField({ required: true, maxLength: 64 }),
+  },
+});

package/src/ledger/executor.ts

@@ -1,5 +1,5 @@
 import { createEntityExecutor } from "@cosmicdrift/kumiko-framework/engine";
-import { accountEntity, transactionEntity } from "./entity";
+import { accountEntity, scheduleEntity, 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
@@ -12,3 +12,7 @@ export const { table: transactionTable, executor: transactionExecutor } = create
   "transaction",
   transactionEntity,
 );
+export const { table: scheduleTable, executor: scheduleExecutor } = createEntityExecutor(
+  "schedule",
+  scheduleEntity,
+);

package/src/ledger/feature.ts

@@ -22,7 +22,8 @@ import {
   type FeatureRegistrar,
 } from "@cosmicdrift/kumiko-framework/engine";
 import { DEFAULT_LEDGER_ACCESS, LEDGER_FEATURE_NAME } from "./constants";
-import { accountEntity, transactionEntity } from "./entity";
+import { accountEntity, scheduleEntity, transactionEntity } from "./entity";
+import { createConfirmSchedulePeriodHandler } from "./handlers/confirm-schedule-period.write";
 import { createCreateTransactionHandler } from "./handlers/create-transaction.write";
 import {
   createBalanceSheetHandler,
@@ -42,7 +43,7 @@ function registerLedger(
   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.",
+    "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. Recurring schedules (`read_ledger_schedules`) layer Dauerauftrag templates on top — a schedule names debit/credit accounts, an amount and a monthly interval, from which the Soll (forecast) is a pure projection (projectSchedule) needing no bookings, and confirm-schedule-period materialises one period as an idempotent, reversal-aware balanced entry referencing scheduleReference(id, period); only confirming writes. 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",
@@ -54,6 +55,7 @@ function registerLedger(
 
   r.entity("account", accountEntity);
   r.entity("transaction", transactionEntity);
+  r.entity("schedule", scheduleEntity);
 
   // 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
@@ -70,6 +72,15 @@ function registerLedger(
   r.queryHandler(defineEntityListHandler("transaction", transactionEntity, { access }));
   r.queryHandler(defineEntityDetailHandler("transaction", transactionEntity, { access }));
 
+  // Recurring schedules — CRUD catalog plus confirm-schedule-period, which books
+  // one projected period as a balanced, idempotent + reversal-aware entry. The
+  // Soll (forecast) is a pure projection (projectSchedule); only confirming writes.
+  r.writeHandler(defineEntityCreateHandler("schedule", scheduleEntity, { access }));
+  r.writeHandler(defineEntityUpdateHandler("schedule", scheduleEntity, { access }));
+  r.writeHandler(createConfirmSchedulePeriodHandler(access));
+  r.queryHandler(defineEntityListHandler("schedule", scheduleEntity, { access }));
+  r.queryHandler(defineEntityDetailHandler("schedule", scheduleEntity, { access }));
+
   // Reports — pure aggregations over the posted entries (account balances,
   // GuV, Bilanz with the current result folded into equity).
   r.queryHandler(createBalancesReportHandler(access));

package/src/ledger/handlers/confirm-schedule-period.write.ts

@@ -0,0 +1,100 @@
+import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import type {
+  AccessRule,
+  WriteHandlerDef,
+  WriteResult,
+} 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,
+  scheduleExecutor,
+  transactionExecutor,
+  transactionTable,
+} from "../executor";
+import { scheduleReference } from "../recurring";
+import { type ConfirmSchedulePeriodPayload, confirmSchedulePeriodPayloadSchema } from "../schemas";
+
+// confirm-schedule-period — turn ONE projected period of a schedule into a posted,
+// balanced transaction (debit +amount / credit −amount), tagged with
+// scheduleReference(scheduleId, period) so the host can merge Soll vs. Ist.
+//
+// Idempotent + reversal-aware: if an ACTIVE (non-reversed) booking for this
+// reference already exists, it's a no-op; a booking that was reversed (Storno)
+// leaves the period re-confirmable. Referential integrity (both accounts must
+// exist) mirrors create-transaction — a schedule could name a bogus account, the
+// generic CRUD create doesn't check.
+export function createConfirmSchedulePeriodHandler(
+  access: AccessRule = DEFAULT_LEDGER_ACCESS,
+): WriteHandlerDef {
+  return {
+    name: "confirm-schedule-period",
+    schema: confirmSchedulePeriodPayloadSchema,
+    access,
+    handler: async (event, ctx) => {
+      const payload = event.payload as ConfirmSchedulePeriodPayload; // @cast-boundary engine-payload
+
+      const schedule = await scheduleExecutor.detail(
+        { id: payload.scheduleId },
+        event.user,
+        ctx.db,
+      );
+      if (!schedule) return writeFailure(new NotFoundError("schedule", payload.scheduleId));
+
+      const debitAccountId = String(schedule["debitAccountId"]);
+      const creditAccountId = String(schedule["creditAccountId"]);
+      for (const accountId of [debitAccountId, creditAccountId]) {
+        const account = await accountExecutor.detail({ id: accountId }, event.user, ctx.db);
+        if (!account) return writeFailure(new NotFoundError("account", accountId));
+      }
+
+      const reference = scheduleReference(payload.scheduleId, payload.period);
+
+      // Scan this tenant's transactions (same full-tenant read the reports do) to
+      // find an active booking for this reference. A tx is reversed when another
+      // tx's reference names its id (the Storno mirror).
+      // ponytail: read-then-write, so two confirms racing the same period could
+      // double-book; add a unique index on (tenantId, reference) when concurrent
+      // confirms become real.
+      const txRows = await selectMany(ctx.db.raw, transactionTable, {
+        tenantId: event.user.tenantId,
+      });
+      const txIds = new Set(txRows.map((r) => String(r["id"])));
+      const reversedTxIds = new Set(
+        txRows
+          .filter((r) => r["reference"] != null && txIds.has(String(r["reference"])))
+          .map((r) => String(r["reference"])),
+      );
+      const active = txRows.find(
+        (r) => r["reference"] === reference && !reversedTxIds.has(String(r["id"])),
+      );
+      if (active) {
+        const ok: WriteResult<{ id: string; alreadyBooked: true }> = {
+          isSuccess: true,
+          data: { id: String(active["id"]), alreadyBooked: true },
+        };
+        return ok;
+      }
+
+      const amount = payload.amount ?? Number(schedule["amount"]);
+      return transactionExecutor.create(
+        {
+          id: generateId(),
+          date: payload.date ?? `${payload.period}-01`,
+          description: String(schedule["description"]),
+          reference,
+          status: "posted",
+          lines: [
+            { accountId: debitAccountId, amount },
+            { accountId: creditAccountId, amount: -amount },
+          ],
+        },
+        event.user,
+        ctx.db,
+      );
+    },
+  };
+}
+
+export const confirmSchedulePeriodHandler: WriteHandlerDef = createConfirmSchedulePeriodHandler();

package/src/ledger/index.ts

@@ -6,15 +6,21 @@ export {
   LEDGER_FEATURE_NAME,
   LedgerHandlers,
   LedgerQueries,
+  SCHEDULE_INTERVALS,
+  type ScheduleInterval,
   TRANSACTION_STATUS,
   type TransactionStatus,
 } from "./constants";
-export { accountEntity, transactionEntity } from "./entity";
+export { accountEntity, scheduleEntity, transactionEntity } from "./entity";
 export {
   createLedgerFeature,
   type LedgerFeatureOptions,
   ledgerFeature,
 } from "./feature";
+export {
+  confirmSchedulePeriodHandler,
+  createConfirmSchedulePeriodHandler,
+} from "./handlers/confirm-schedule-period.write";
 export {
   createCreateTransactionHandler,
   createTransactionHandler,
@@ -28,6 +34,16 @@ export {
   createReverseTransactionHandler,
   reverseTransactionHandler,
 } from "./handlers/reverse-transaction.write";
+export {
+  type LedgerTxRow,
+  mergeScheduleActuals,
+  type ProjectedPeriod,
+  projectSchedule,
+  type ScheduleDef,
+  type ScheduleMonth,
+  type ScheduleMonthStatus,
+  scheduleReference,
+} from "./recurring";
 export {
   type AccountBalance,
   accountBalances,
@@ -43,7 +59,9 @@ export {
 } from "./reports";
 export {
   accountTypeSchema,
+  type ConfirmSchedulePeriodPayload,
   type CreateTransactionPayload,
+  confirmSchedulePeriodPayloadSchema,
   createTransactionPayloadSchema,
   type Posting,
   postingSchema,

package/src/ledger/recurring.ts

@@ -0,0 +1,140 @@
+// Recurring schedules on top of the ledger primitive. A `schedule` is a standing
+// booking template ("Miete ab 1.1.2026, 500 €/Monat") from which two things fall
+// out WITHOUT booking every month up front:
+//
+//   • projectSchedule()      — the Soll (forecast): pure projection over a window,
+//                              no transactions needed (chart, "trägt sich das?").
+//   • mergeScheduleActuals() — Soll vs. Ist: the projection left-joined against
+//                              the posted confirmations (per `reference`), so each
+//                              month is posted | open | forecast.
+//
+// confirm-schedule-period (handler) turns one projected month into ONE balanced
+// transaction tagged with `scheduleReference(id, period)`. Both functions here are
+// pure — no DB, no Date API (windows/asOf come in as params) — so the no-date-api
+// guard stays green and the forecast is deterministic.
+
+import type { ScheduleInterval } from "./constants";
+import type { Posting } from "./schemas";
+
+export type ScheduleDef = {
+  readonly startDate: string; // ISO; first period (day ignored for monthly)
+  readonly endDate?: string | null; // ISO; last period inclusive, or open-ended
+  readonly interval: ScheduleInterval;
+  readonly amount: number; // positive minor units; the handler assigns debit/credit signs
+};
+
+export type ProjectedPeriod = {
+  readonly period: string; // "YYYY-MM"
+  readonly date: string; // ISO booking date (first of the period month)
+  readonly amount: number;
+};
+
+export type ScheduleMonthStatus = "posted" | "open" | "forecast";
+
+export type ScheduleMonth = {
+  readonly period: string;
+  readonly planned: number; // Soll from the schedule
+  readonly actual: number | null; // Ist (booked) or null
+  readonly txId: string | null; // the confirming transaction, for un-confirm (Storno)
+  readonly status: ScheduleMonthStatus;
+};
+
+// The transaction shape the host feeds the merge (transaction:list rows with the
+// jsonb `lines` already parsed — driver-normalised, like the integration test's
+// linesOf helper).
+export type LedgerTxRow = {
+  readonly id: string;
+  readonly reference: string | null;
+  readonly lines: readonly Posting[];
+};
+
+// "schedule:<id>:<period>" — the stable idempotency + merge key on a confirmation.
+export function scheduleReference(scheduleId: string, period: string): string {
+  return `schedule:${scheduleId}:${period}`;
+}
+
+// "YYYY-MM" ⇄ a month index (year*12 + monthOfYear), so window math is pure
+// integer arithmetic — no Date object (no-date-api guard) and no DST/timezone
+// drift. isoMonth tolerates a full ISO date ("2026-01-15" → "2026-01").
+function isoMonth(iso: string): string {
+  return iso.slice(0, 7);
+}
+
+function monthIndex(ym: string): number {
+  const [y, m] = ym.split("-");
+  return Number(y) * 12 + (Number(m) - 1);
+}
+
+function indexToMonth(index: number): string {
+  const year = Math.floor(index / 12);
+  const month = (index % 12) + 1;
+  return `${year}-${String(month).padStart(2, "0")}`;
+}
+
+// The Soll: every period the schedule covers within [window.from, window.to],
+// clamped to the schedule's own [startDate, endDate]. Monthly only in v1.
+// ponytail: monthly-only; add weekly/quarterly/yearly to the interval union +
+// the step here when a schedule needs it.
+export function projectSchedule(
+  schedule: ScheduleDef,
+  window: { readonly from: string; readonly to: string },
+): ProjectedPeriod[] {
+  const firstIndex = Math.max(
+    monthIndex(isoMonth(schedule.startDate)),
+    monthIndex(isoMonth(window.from)),
+  );
+  const lastIndex = Math.min(
+    schedule.endDate != null ? monthIndex(isoMonth(schedule.endDate)) : Number.POSITIVE_INFINITY,
+    monthIndex(isoMonth(window.to)),
+  );
+  const periods: ProjectedPeriod[] = [];
+  for (let index = firstIndex; index <= lastIndex; index++) {
+    const period = indexToMonth(index);
+    periods.push({ period, date: `${period}-01`, amount: schedule.amount });
+  }
+  return periods;
+}
+
+// Soll vs. Ist. A month is `posted` when a confirmation for its reference exists
+// AND has not been reversed (Storno); a reversed confirmation drops the month back
+// to `open` so it can be re-confirmed. Past/current unbooked months are `open`,
+// future ones `forecast` (asOf is the boundary — month-granular).
+export function mergeScheduleActuals(
+  scheduleId: string,
+  projection: readonly ProjectedPeriod[],
+  transactions: readonly LedgerTxRow[],
+  asOf: string,
+): ScheduleMonth[] {
+  const txIds = new Set(transactions.map((t) => t.id));
+  // A Storno mirror carries reference = the reversed tx's id, so any tx whose
+  // reference names another tx marks that other tx reversed.
+  const reversedTxIds = new Set(
+    transactions
+      .filter((t) => t.reference != null && txIds.has(t.reference))
+      .map((t) => t.reference as string),
+  );
+  const asOfIndex = monthIndex(isoMonth(asOf));
+
+  return projection.map((projected) => {
+    const reference = scheduleReference(scheduleId, projected.period);
+    const active = transactions.find((t) => t.reference === reference && !reversedTxIds.has(t.id));
+    if (active) {
+      return {
+        period: projected.period,
+        planned: projected.amount,
+        actual: Math.abs(active.lines[0]?.amount ?? 0),
+        txId: active.id,
+        status: "posted",
+      };
+    }
+    const status: ScheduleMonthStatus =
+      monthIndex(projected.period) <= asOfIndex ? "open" : "forecast";
+    return {
+      period: projected.period,
+      planned: projected.amount,
+      actual: null,
+      txId: null,
+      status,
+    };
+  });
+}

package/src/ledger/schemas.ts

@@ -47,5 +47,19 @@ export const reverseTransactionPayloadSchema = z.object({
 });
 export type ReverseTransactionPayload = z.infer<typeof reverseTransactionPayloadSchema>;
 
+// confirm-schedule-period — materialise ONE projected period of a schedule as a
+// posted, balanced entry. `amount` overrides the schedule's amount for that period
+// (e.g. rent came in short); `date` overrides the booking date (default: 1st of
+// the period). Idempotent + reversal-aware in the handler via the schedule
+// reference, so re-confirming a booked month is a no-op and a stornoed month can
+// be re-confirmed.
+export const confirmSchedulePeriodPayloadSchema = z.object({
+  scheduleId: z.string().min(1).max(64),
+  period: z.string().regex(/^\d{4}-\d{2}$/, "period must be YYYY-MM"),
+  amount: z.number().int().positive().optional(),
+  date: z.string().min(1).max(32).optional(),
+});
+export type ConfirmSchedulePeriodPayload = z.infer<typeof confirmSchedulePeriodPayloadSchema>;
+
 // Re-export so callers building accounts have the type vocabulary in one place.
 export const accountTypeSchema = z.enum(ACCOUNT_TYPES);

package/src/ledger/web/index.ts

@@ -0,0 +1,35 @@
+// @runtime client
+// Client-safe ledger surface: QN constants + the pure recurring helpers
+// (projection + Soll/Ist merge), nothing else. The full `../ledger` entry
+// re-exports the feature/handlers/executor, which pull bun-db/postgres — a
+// browser bundle that imports from there fails on Node builtins. A client screen
+// (e.g. a rent-cashflow view) imports the dispatch QNs + the pure forecast/merge
+// from HERE, then dispatches via the renderer's useDispatcher.
+
+export {
+  ACCOUNT_TYPES,
+  type AccountType,
+  LEDGER_FEATURE_NAME,
+  LedgerHandlers,
+  LedgerQueries,
+  SCHEDULE_INTERVALS,
+  type ScheduleInterval,
+  TRANSACTION_STATUS,
+  type TransactionStatus,
+} from "../constants";
+export {
+  type LedgerTxRow,
+  mergeScheduleActuals,
+  type ProjectedPeriod,
+  projectSchedule,
+  type ScheduleDef,
+  type ScheduleMonth,
+  type ScheduleMonthStatus,
+  scheduleReference,
+} from "../recurring";
+export {
+  type ConfirmSchedulePeriodPayload,
+  confirmSchedulePeriodPayloadSchema,
+  type Posting,
+  postingSchema,
+} from "../schemas";