@cosmicdrift/kumiko-bundled-features 0.90.3 → 0.92.0

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);