@cosmicdrift/kumiko-samples 0.338.0

package/packages/bundled-features/src/ledger/handlers/reports.query.ts

@@ -0,0 +1,84 @@
+import type { AccessRule, QueryHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import * as z from "zod";
+import { DEFAULT_LEDGER_ACCESS } from "../constants.js";
+import { accountTable, transactionTable } from "../executor.js";
+import {
+  accountBalances,
+  balanceSheet,
+  incomeStatement,
+  type LedgerAccount,
+  type LedgerEntry,
+  toAccounts,
+  toEntries,
+} from "../reports.js";
+
+// 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 ctx.db.selectMany(accountTable, { tenantId: ctx.user.tenantId });
+  const txRows = await ctx.db.selectMany(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,
+    description:
+      "Returns the per-account balance in its natural sign plus the trial balance over an optional from/to period; use it for a trial balance or to read one account's standing.",
+    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,
+    description:
+      "Returns income minus expense over an optional from/to period; use it for a profit-and-loss statement.",
+    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,
+    description:
+      "Returns assets, liabilities and equity as of the optional `to` date with the period result folded into equity so the sheet balances; use it for a balance sheet at a point in time.",
+    handler: async (query, ctx) => {
+      const period = periodSchema.parse(query);
+      const { accounts, entries } = await loadBooks(ctx);
+      return balanceSheet(accounts, entries, period);
+    },
+  };
+}

package/packages/bundled-features/src/ledger/handlers/reverse-transaction.write.ts

@@ -0,0 +1,95 @@
+import type { AccessRule, WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  ConflictError,
+  NotFoundError,
+  UnprocessableError,
+  writeFailure,
+} from "@cosmicdrift/kumiko-framework/errors";
+import { generateId } from "@cosmicdrift/kumiko-framework/utils";
+import { DEFAULT_LEDGER_ACCESS } from "../constants.js";
+import { transactionExecutor, transactionTable } from "../executor.js";
+import { normalizeLines } from "../reports.js";
+import { type ReverseTransactionPayload, reverseTransactionPayloadSchema } from "../schemas.js";
+import { readSubjectReference } from "../subject-reference.js";
+
+// 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,
+    description:
+      "Books the mirror image of a posted journal entry as a new entry referencing the original, refusing entries that are not posted or already reversed; use it as the only way to correct a booking, since entries themselves are immutable.",
+    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));
+
+      // Only a posted entry contributes to the books (rawBalances skips
+      // anything else) — reversing a draft would book a real, balanced
+      // Storno entry against a booking that was never counted, creating a
+      // phantom balance with no corresponding original.
+      if (original["status"] !== "posted") {
+        return writeFailure(
+          new UnprocessableError("transaction_not_posted", {
+            details: { transactionId: payload.id, status: original["status"] },
+          }),
+        );
+      }
+
+      // Dedup guard: two reverse() calls on the same original would each book
+      // an independently-balanced Storno (the global trial balance stays 0
+      // either way, masking the bug), doubling the per-account effect. The
+      // reference column ties a Storno back to its original 1:1.
+      const alreadyReversed = await ctx.db.selectMany(transactionTable, {
+        tenantId: event.user.tenantId,
+        reference: payload.id,
+      });
+      if (alreadyReversed.length > 0) {
+        return writeFailure(
+          new ConflictError({
+            message: "transaction already reversed",
+            details: { transactionId: payload.id },
+          }),
+        );
+      }
+
+      // jsonb `lines` may surface as a parsed array or a JSON string depending
+      // on the driver path — normalizeLines handles both (see reports.ts).
+      const lines = normalizeLines(original["lines"]).map((l) => ({
+        accountId: l.accountId,
+        amount: -l.amount,
+      }));
+
+      // The reversal shares its subject with the original so filtering by
+      // subjectId still finds the Storno; unset on the original stays unset.
+      const { subjectType, subjectId } = readSubjectReference(original);
+
+      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,
+          subjectType,
+          subjectId,
+        },
+        event.user,
+        ctx.db,
+      );
+    },
+  };
+}
+
+export const reverseTransactionHandler: WriteHandlerDef = createReverseTransactionHandler();

package/packages/bundled-features/src/ledger/index.ts

@@ -0,0 +1,71 @@
+export {
+  ACCOUNT_TYPES,
+  type AccountType,
+  DEFAULT_LEDGER_ACCESS,
+  DEFAULT_LEDGER_ROLES,
+  LEDGER_FEATURE_NAME,
+  LedgerHandlers,
+  LedgerQueries,
+  SCHEDULE_INTERVALS,
+  type ScheduleInterval,
+  TRANSACTION_STATUS,
+  type TransactionStatus,
+} from "./constants.js";
+export { accountEntity, scheduleEntity, transactionEntity } from "./entity.js";
+export {
+  createLedgerFeature,
+  type LedgerFeatureOptions,
+  ledgerFeature,
+} from "./feature.js";
+export {
+  confirmSchedulePeriodHandler,
+  createConfirmSchedulePeriodHandler,
+} from "./handlers/confirm-schedule-period.write.js";
+export {
+  createCreateTransactionHandler,
+  createTransactionHandler,
+} from "./handlers/create-transaction.write.js";
+export {
+  createBalanceSheetHandler,
+  createBalancesReportHandler,
+  createIncomeStatementHandler,
+} from "./handlers/reports.query.js";
+export {
+  createReverseTransactionHandler,
+  reverseTransactionHandler,
+} from "./handlers/reverse-transaction.write.js";
+export {
+  findReversedIds,
+  type LedgerTxRow,
+  mergeScheduleActuals,
+  type ProjectedPeriod,
+  projectSchedule,
+  type ScheduleDef,
+  type ScheduleMonth,
+  type ScheduleMonthStatus,
+  scheduleReference,
+} from "./recurring.js";
+export {
+  type AccountBalance,
+  accountBalances,
+  type BalanceSheet,
+  type BalancesReport,
+  balanceSheet,
+  type IncomeStatement,
+  incomeStatement,
+  type LedgerAccount,
+  type LedgerEntry,
+  type Period,
+  rawBalances,
+} from "./reports.js";
+export {
+  accountTypeSchema,
+  type ConfirmSchedulePeriodPayload,
+  type CreateTransactionPayload,
+  confirmSchedulePeriodPayloadSchema,
+  createTransactionPayloadSchema,
+  type Posting,
+  postingSchema,
+  type ReverseTransactionPayload,
+  reverseTransactionPayloadSchema,
+} from "./schemas.js";

package/packages/bundled-features/src/ledger/recurring.ts

@@ -0,0 +1,149 @@
+// 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.js";
+import type { Posting } from "./schemas.js";
+
+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}`;
+}
+
+// A Storno mirror carries reference = the reversed tx's id, so any tx whose
+// reference names another tx in the set marks that other tx reversed. Shared
+// by mergeScheduleActuals (below) and confirm-schedule-period.write.ts's
+// idempotency check (684/4) — same detection, kept in one place so a fix
+// can't land in one call-site and drift from the other.
+export function findReversedIds(
+  rows: readonly { readonly id: string; readonly reference: string | null }[],
+): Set<string> {
+  const ids = new Set(rows.map((r) => r.id));
+  return new Set(
+    rows
+      .filter((r) => r.reference !== null && ids.has(r.reference))
+      .map((r) => r.reference as string),
+  );
+}
+
+// "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").
+export 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 reversedTxIds = findReversedIds(transactions);
+  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/packages/bundled-features/src/ledger/reports.ts

@@ -0,0 +1,164 @@
+import { parseJsonSafe } from "@cosmicdrift/kumiko-framework/utils";
+import type { AccountType } from "./constants.js";
+import type { Posting } from "./schemas.js";
+
+// 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/packages/bundled-features/src/ledger/schemas.ts

@@ -0,0 +1,71 @@
+import * as z from "zod";
+import { ACCOUNT_TYPES, TRANSACTION_STATUS } from "./constants.js";
+
+// 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),
+    // Business-object reference (e.g. a lease contract) this entry is about.
+    subjectType: z.string().max(64).optional(),
+    subjectId: z.string().max(128).optional(),
+  })
+  .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>;
+
+// 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()
+    .regex(/^\d{4}-\d{2}-\d{2}$/, "date must be YYYY-MM-DD")
+    .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/packages/bundled-features/src/ledger/subject-reference.ts

@@ -0,0 +1,10 @@
+// Subject columns are nullable; anything that is not a string reads as unset.
+export function readSubjectReference(row: Record<string, unknown>): {
+  subjectType: string | null;
+  subjectId: string | null;
+} {
+  return {
+    subjectType: typeof row["subjectType"] === "string" ? row["subjectType"] : null,
+    subjectId: typeof row["subjectId"] === "string" ? row["subjectId"] : null,
+  };
+}

package/packages/bundled-features/src/ledger/web/index.ts

@@ -0,0 +1,36 @@
+// @runtime client
+// Client-safe ledger surface: QN constants, the pure recurring helpers
+// (projection + Soll/Ist merge), and the Zod payload schemas (for client-side
+// pre-validation before dispatch) — 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.js";
+export {
+  type LedgerTxRow,
+  mergeScheduleActuals,
+  type ProjectedPeriod,
+  projectSchedule,
+  type ScheduleDef,
+  type ScheduleMonth,
+  type ScheduleMonthStatus,
+  scheduleReference,
+} from "../recurring.js";
+export {
+  type ConfirmSchedulePeriodPayload,
+  confirmSchedulePeriodPayloadSchema,
+  type Posting,
+  postingSchema,
+} from "../schemas.js";