@cosmicdrift/kumiko-samples 0.338.0

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

@@ -0,0 +1,60 @@
+// @runtime client
+// ledger bundle constants — feature-name + qualified handler/query names.
+//
+// Spec: kumiko-platform/docs/plans/ledger-feature.md
+
+import type { AccessRule } from "@cosmicdrift/kumiko-framework/engine";
+
+export const LEDGER_FEATURE_NAME = "ledger";
+
+// Qualified names (QN format: scope:type:name). The account catalog uses the
+// generic defineEntity*Handler (create/update/list/detail) → "account:<verb>"
+// qualified to "ledger:write:account:<verb>". Transactions are immutable: only
+// create-transaction (balanced, Σ=0) and reverse-transaction (Storno) exist —
+// no update/delete, so a posted journal entry can never be mutated.
+export const LedgerHandlers = {
+  createAccount: "ledger:write:account:create",
+  updateAccount: "ledger:write:account:update",
+  createTransaction: "ledger:write:create-transaction",
+  reverseTransaction: "ledger:write:reverse-transaction",
+  // 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 = {
+  accountList: "ledger:query:account:list",
+  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",
+  reportBalanceSheet: "ledger:query:report:balance-sheet",
+} as const;
+
+// Account types double-entry needs to interpret a balance: asset/expense are
+// debit-normal, liability/equity/income are credit-normal. The report layer
+// (Phase 1) flips signs by type; the primitive only stores them.
+export const ACCOUNT_TYPES = ["asset", "liability", "equity", "income", "expense"] as const;
+export type AccountType = (typeof ACCOUNT_TYPES)[number];
+
+export const TRANSACTION_STATUS = ["draft", "posted"] as const;
+export type TransactionStatus = (typeof TRANSACTION_STATUS)[number];
+
+// 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.
+export const DEFAULT_LEDGER_ROLES = ["TenantAdmin", "TenantMember"] as const;
+
+export const DEFAULT_LEDGER_ACCESS: AccessRule = { roles: DEFAULT_LEDGER_ROLES };

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

@@ -0,0 +1,177 @@
+import { sql } from "@cosmicdrift/kumiko-framework/db";
+import {
+  createDateField,
+  createEmbeddedListField,
+  createEntity,
+  createNumberField,
+  createSelectField,
+  createTextField,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { ACCOUNT_TYPES, SCHEDULE_INTERVALS, TRANSACTION_STATUS } from "./constants.js";
+
+// account — a node in the chart of accounts. Event-sourced (create/update/list/
+// detail via the standard handlers); the framework projects `read_ledger_accounts`
+// from its CRUD events. `parentId` null → root account; otherwise the chart-of-
+// accounts tree. `type` drives how the report layer interprets a balance. No
+// money column — balances are DERIVED from postings (Phase 1), never stored.
+// tenantId is a base column set by the framework → each tenant has its own books.
+export const accountEntity = createEntity({
+  table: "read_ledger_accounts",
+  description:
+    "One node of a tenant's chart of accounts: a name, an asset/liability/equity/income/expense type that decides how reports read its balance, an optional account code and an optional parent account forming the account tree; balances are derived from postings, never stored here.",
+  fields: {
+    name: createTextField({
+      required: true,
+      maxLength: 120,
+      personal: false,
+      reason: "is_business_data",
+    }),
+    type: createSelectField({ options: ACCOUNT_TYPES, required: true }),
+    // Optional account number (Kontonummer / SKR code); unique per tenant when set.
+    code: createTextField({ maxLength: 32, personal: false, reason: "technical_reference" }),
+    // Parent account id, or absent for a root account. No FK (event-sourced).
+    parentId: createTextField({ maxLength: 64, personal: false, reason: "technical_reference" }),
+  },
+  // Find-then-create by code (solon, money-horse) races across tabs/devices;
+  // only the DB closes that gap. Partial because code is optional. The name is
+  // the one money-horse's hand-written migration 0024 already uses, so both
+  // declare the same Postgres object instead of two indexes.
+  indexes: [
+    {
+      columns: ["tenantId", "code"],
+      unique: true,
+      where: sql`"code" IS NOT NULL`,
+      name: "read_ledger_accounts_tenant_id_code_uidx",
+    },
+  ],
+});
+
+// transaction — a journal entry. The balanced posting lines live embedded as
+// `lines` (embedded list: { accountId, amount }[], Σ amount = 0), so an entry is atomic:
+// the Σ=0 invariant holds within a single command, no cross-row write. The
+// framework projects `read_ledger_transactions`; Phase 1 adds a flat
+// `read_ledger_postings` projection (one row per line) for per-account/period
+// report queries.
+//
+// IMMUTABLE: the feature registers NO update/delete handler for transaction. A
+// posted entry is a fact; corrections are reverse-transaction (Storno) entries.
+// `status` carries draft|posted for the later Soll/Ist work — Phase 0 posts only.
+export const transactionEntity = createEntity({
+  table: "read_ledger_transactions",
+  description:
+    "One journal entry: a booking date, a narration, an optional reference (a reversal points at the entry it corrects), a draft/posted status and the embedded posting lines of accountId plus signed minor-unit amount that must sum to zero; posted entries are immutable and corrected only by a reversing entry.",
+  fields: {
+    date: createDateField({ required: true }),
+    // Journal narration ("Miete Januar", "Storno: …") is accounting data, not
+    // user-generated PII → `personal: false` silences the user-content heuristic.
+    description: createTextField({
+      required: true,
+      maxLength: 200,
+      personal: false,
+      reason: "is_business_data",
+    }),
+    // Free-text memo (a reversal or confirmed schedule period overwrites it with
+    // a system-generated id, but a manual entry can carry caller-supplied text).
+    reference: createTextField({
+      maxLength: 120,
+      personal: false,
+      reason: "is_business_data",
+    }),
+    status: createSelectField({ options: TRANSACTION_STATUS, required: true }),
+    // Posting lines are born with the entry and never change on their own —
+    // a correction is a new (reversing) entry. The embedded list validates
+    // each line's shape; `money` pins amount to signed integer minor units
+    // (the entry's currency is a book-level concern, not per line). The
+    // cross-line invariants (Σ=0, ≥2 distinct accounts) stay in
+    // createTransactionPayloadSchema.
+    lines: createEmbeddedListField(
+      {
+        accountId: { type: "text", required: true },
+        amount: { type: "money", required: true },
+      },
+      { required: true },
+    ),
+    // Optional business-object reference (e.g. a lease contract) so entries can
+    // be filtered by what they're about, not just grepped out of `reference`.
+    subjectType: createTextField({
+      maxLength: 64,
+      personal: false,
+      reason: "technical_reference",
+      filterable: true,
+    }),
+    subjectId: createTextField({
+      maxLength: 128,
+      personal: false,
+      reason: "technical_reference",
+      filterable: true,
+    }),
+  },
+  indexes: [{ columns: ["tenantId", "subjectType", "subjectId"] }],
+});
+
+// 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",
+  description:
+    "One recurring booking template: book a positive minor-unit amount from a debit account to a credit account each interval between a start date and an optional open end; it holds no bookings itself, periods become real entries only when confirmed.",
+  fields: {
+    description: createTextField({
+      required: true,
+      maxLength: 200,
+      personal: false,
+      reason: "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, min: 1, integer: true }),
+    debitAccountId: createTextField({
+      required: true,
+      maxLength: 64,
+      personal: false,
+      reason: "technical_reference",
+    }),
+    creditAccountId: createTextField({
+      required: true,
+      maxLength: 64,
+      personal: false,
+      reason: "technical_reference",
+    }),
+    // Confirmed periods inherit this from the schedule (see
+    // confirm-schedule-period.write.ts) rather than repeating it per period.
+    subjectType: createTextField({
+      maxLength: 64,
+      personal: false,
+      reason: "technical_reference",
+      filterable: true,
+    }),
+    subjectId: createTextField({
+      maxLength: 128,
+      personal: false,
+      reason: "technical_reference",
+      filterable: true,
+    }),
+    // Caller-assigned stable key (e.g. one id per lease position) to find the
+    // schedule again. Not unique: callers keep their own find-then-create;
+    // `description` stays pure display text instead of a lookup key.
+    sourceRef: createTextField({
+      maxLength: 128,
+      personal: false,
+      reason: "technical_reference",
+      filterable: true,
+    }),
+  },
+  // A separate non-unique index: changing the subject index would drop and
+  // recreate it, an additional one is a plain CREATE INDEX.
+  indexes: [
+    { columns: ["tenantId", "subjectType", "subjectId"] },
+    { columns: ["tenantId", "sourceRef"] },
+  ],
+});

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

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

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

@@ -0,0 +1,180 @@
+// 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.js";
+import { accountEntity, scheduleEntity, transactionEntity } from "./entity.js";
+import { createConfirmSchedulePeriodHandler } from "./handlers/confirm-schedule-period.write.js";
+import { createCreateTransactionHandler } from "./handlers/create-transaction.write.js";
+import {
+  createBalanceSheetHandler,
+  createBalancesReportHandler,
+  createIncomeStatementHandler,
+} from "./handlers/reports.query.js";
+import { createReverseTransactionHandler } from "./handlers/reverse-transaction.write.js";
+
+// 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. Recurring schedules (`read_ledger_schedules`) layer Dauerauftrag templates on top — a schedule names debit/credit accounts, an amount, a monthly interval and an optional caller-assigned `sourceRef` key (filterable, to find a schedule again), 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",
+    category: "data",
+    recommended: false,
+  });
+
+  if (toggleable !== undefined) r.toggleable(toggleable);
+
+  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
+  // the postings projection (Phase 1).
+  r.writeHandler(
+    defineEntityCreateHandler("account", accountEntity, {
+      access,
+      description:
+        "Adds an account to the tenant's chart of accounts with a name, a type of asset, liability, equity, income or expense, an optional code and an optional parent account; use it before booking anything against that account.",
+    }),
+  );
+  r.writeHandler(
+    defineEntityUpdateHandler("account", accountEntity, {
+      access,
+      description:
+        "Changes an existing chart-of-accounts entry's name, type, code or parent; use it to rename or re-file an account, its balance is derived from postings and never edited here.",
+    }),
+  );
+  r.queryHandler(
+    defineEntityListHandler("account", accountEntity, {
+      access,
+      description:
+        "Lists the tenant's chart of accounts with name, type, code and parent; use it to browse the account tree or to look up the account id a booking needs.",
+    }),
+  );
+  r.queryHandler(
+    defineEntityDetailHandler("account", accountEntity, {
+      access,
+      description:
+        "Returns one chart-of-accounts entry by id with its name, type, code and parent; use it to inspect a single account.",
+    }),
+  );
+
+  // 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,
+      description:
+        "Lists the tenant's journal entries with date, description, reference, status and their embedded posting lines; use it to browse the books or to find the entry a reversal should target.",
+    }),
+  );
+  r.queryHandler(
+    defineEntityDetailHandler("transaction", transactionEntity, {
+      access,
+      description:
+        "Returns one journal entry by id including every posting line; use it to inspect a single booking.",
+    }),
+  );
+
+  // 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,
+      description:
+        "Creates a recurring booking template that names a debit and a credit account, a positive amount, an interval and a start plus optional end date; use it to set up a standing order, it books nothing on its own.",
+    }),
+  );
+  r.writeHandler(
+    defineEntityUpdateHandler("schedule", scheduleEntity, {
+      access,
+      description:
+        "Changes a recurring booking template's description, accounts, amount, interval or date window; use it when a standing order's terms change, already confirmed periods stay booked as they were.",
+    }),
+  );
+  r.writeHandler(createConfirmSchedulePeriodHandler(access));
+  r.queryHandler(
+    defineEntityListHandler("schedule", scheduleEntity, {
+      access,
+      description:
+        "Lists the tenant's recurring booking templates with their accounts, amount, interval and date window; use it to see which standing orders exist and forecast upcoming periods.",
+    }),
+  );
+  r.queryHandler(
+    defineEntityDetailHandler("schedule", scheduleEntity, {
+      access,
+      description:
+        "Returns one recurring booking template by id with its accounts, amount, interval and date window; use it to inspect a single standing order before confirming a period.",
+    }),
+  );
+
+  // 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/packages/bundled-features/src/ledger/handlers/confirm-schedule-period.write.ts

@@ -0,0 +1,134 @@
+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.js";
+import {
+  accountExecutor,
+  scheduleExecutor,
+  transactionExecutor,
+  transactionTable,
+} from "../executor.js";
+import { findReversedIds, isoMonth, scheduleReference } from "../recurring.js";
+import {
+  type ConfirmSchedulePeriodPayload,
+  confirmSchedulePeriodPayloadSchema,
+} from "../schemas.js";
+import { readSubjectReference } from "../subject-reference.js";
+
+// 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,
+    description:
+      "Turns one month of a recurring schedule into a posted balanced entry between its debit and credit account, returning the existing booking instead when that period is already booked and not reversed; use it to move a forecast period into the actual books.",
+    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));
+
+      if (
+        payload.period < isoMonth(String(schedule["startDate"])) ||
+        (schedule["endDate"] != null && payload.period > isoMonth(String(schedule["endDate"])))
+      ) {
+        return writeFailure(new NotFoundError("schedule-period", payload.period));
+      }
+
+      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);
+
+      // Two targeted reads instead of a full-tenant transaction scan: (1) any
+      // booking that already carries this exact schedule-period reference —
+      // normally 0 or 1 row, never O(tenant's-full-history); (2) any Storno
+      // that mirrors one of those candidates (a tx is reversed when ANOTHER
+      // tx's `reference` names its id).
+      // 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 candidates = await ctx.db.selectMany(transactionTable, {
+        tenantId: event.user.tenantId,
+        reference,
+      });
+      const candidateIds = candidates.map((r) => String(r["id"]));
+      const stornos =
+        candidateIds.length > 0
+          ? await ctx.db.selectMany(transactionTable, {
+              tenantId: event.user.tenantId,
+              reference: { in: candidateIds },
+            })
+          : [];
+      const reversedIds = findReversedIds(
+        [...candidates, ...stornos].map((r) => ({
+          id: String(r["id"]),
+          reference: r["reference"] === null ? null : String(r["reference"]),
+        })),
+      );
+      const active = candidates.find((r) => !reversedIds.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"]);
+      // The subject is a property of the schedule, not the confirm call — a
+      // period without one stays without one, no backfill/error.
+      const { subjectType, subjectId } = readSubjectReference(schedule);
+      const created = await 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 },
+          ],
+          subjectType,
+          subjectId,
+        },
+        event.user,
+        ctx.db,
+      );
+      // Same shape as the idempotent-path return above (684/6) — a caller
+      // shouldn't have to check "does alreadyBooked exist" to know which
+      // branch fired.
+      if (!created.isSuccess) return created;
+      return {
+        isSuccess: true,
+        data: { ...created.data, alreadyBooked: false as const },
+      };
+    },
+  };
+}
+
+export const confirmSchedulePeriodHandler: WriteHandlerDef = createConfirmSchedulePeriodHandler();

package/packages/bundled-features/src/ledger/handlers/create-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.js";
+import { accountExecutor, transactionExecutor } from "../executor.js";
+import { type CreateTransactionPayload, createTransactionPayloadSchema } from "../schemas.js";
+
+// 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,
+    description:
+      "Books one balanced journal entry from a date, description and at least two posting lines summing to zero, after verifying every named account exists; use it to record any financial movement in the tenant's books.",
+    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,
+          subjectType: payload.subjectType ?? null,
+          subjectId: payload.subjectId ?? null,
+        },
+        event.user,
+        ctx.db,
+      );
+    },
+  };
+}
+
+export const createTransactionHandler: WriteHandlerDef = createCreateTransactionHandler();