@cosmicdrift/kumiko-samples 0.385.0 → 0.387.0

package/packages/bundled-features/src/inbound-provider-inmemory/feature.ts

@@ -1,15 +1,15 @@
 // kumiko-feature-version: 1
 //
-// inbound-provider-inmemory — scriptbarer In-Memory-Provider für die
-// inbound-mail-foundation Plugin-API. Für Tests, Demos und Sample-Apps:
-// Messages werden per `seedInboundMessage()` eingespeist statt von einem
-// echten Postfach gefetcht; `watch()` pusht geseedete Messages sofort
-// (IDLE-Simulation), `fetch()` liefert sie cursor-basiert nach
-// (Reconciliation-Pfad) — beide Pfade zusammen exercisen exakt die
-// Dedup-Garantie der Foundation.
+// inbound-provider-inmemory — scriptable in-memory provider for the
+// inbound-mail-foundation plugin API. For tests, demos, and sample apps:
+// messages are supplied via `seedInboundMessage()` instead of being fetched
+// from a real mailbox; `watch()` immediately pushes seeded messages
+// (IDLE simulation), while `fetch()` returns them by cursor
+// (reconciliation path). Together, both paths exercise the foundation's
+// deduplication guarantee exactly.
 //
-// **Pattern-Vorbild:** mail-transport-inmemory (module-level State +
-// Test-Helper-Exports). NICHT für Production.
+// **Pattern basis:** mail-transport-inmemory (module-level state +
+// test-helper exports). Not for production.
 
 import type {
   InboundFetchResult,
@@ -24,8 +24,8 @@ const FEATURE_NAME = "inbound-provider-inmemory";
 export const INMEMORY_PROVIDER_KEY = "inmemory";
 
 // =============================================================================
-// Module-level State — pro Account: Message-Log (append-only, wie ein
-// echtes Postfach), aktive Watch-Handler, One-Shot-Fehlerinjektion.
+// Module-level state — per account: an append-only message log, like a real
+// mailbox; active watch handlers and one-shot error injection.
 // =============================================================================
 
 type WatchHandlers = {
@@ -51,28 +51,28 @@ function stateFor(accountId: string): AccountState {
   return state;
 }
 
-/** Test-Helper: Message ins Postfach legen. Läuft ein watch, wird sie
- *  sofort gepusht (IDLE-Simulation); der nächste fetch liefert sie
- *  cursor-basiert ebenfalls — Dedup der Foundation macht das idempotent. */
+/** Test helper: adds a message to the mailbox. If a watch is active, it is
+ *  pushed immediately (IDLE simulation); the next fetch also returns it by
+ *  cursor — the foundation's deduplication makes this idempotent. */
 export async function seedInboundMessage(accountId: string, msg: RawInboundMessage): Promise<void> {
   const state = stateFor(accountId);
   state.log.push(msg);
   if (state.watch) await state.watch.onMessages([msg]);
 }
 
-/** Test-Helper: One-Shot-Fehler für den nächsten fetch (z.B.
- *  InboundAuthError, InboundCursorInvalidError). */
+/** Test helper: injects a one-shot error into the next fetch (e.g.
+ *  InboundAuthError or InboundCursorInvalidError). */
 export function failNextFetchWith(accountId: string, err: unknown): void {
   stateFor(accountId).nextFetchError = err;
 }
 
-/** Test-Helper: One-Shot-Fehler für das nächste verify. */
+/** Test helper: injects a one-shot error into the next verify. */
 export function failNextVerifyWith(accountId: string, err: unknown): void {
   stateFor(accountId).nextVerifyError = err;
 }
 
-/** Test-Helper: Tod der Live-Verbindung simulieren (Supervisor muss
- *  mit Backoff neu starten). */
+/** Test helper: simulates the live connection terminating (the supervisor
+ *  must restart with backoff). */
 export function emitWatchError(accountId: string, err: unknown): void {
   const state = accounts.get(accountId);
   if (state?.watch) {
@@ -82,7 +82,7 @@ export function emitWatchError(accountId: string, err: unknown): void {
   }
 }
 
-/** Test-Helper: läuft gerade ein watch für den Account? */
+/** Test helper: reports whether an account currently has an active watch. */
 export function isWatching(accountId: string): boolean {
   return accounts.get(accountId)?.watch != null;
 }
@@ -94,7 +94,7 @@ export function resetInboundInMemory(): void {
 }
 
 // =============================================================================
-// Plugin — cursor = { offset: number } über das append-only-Log.
+// Plugin — cursor = { offset: number } over the append-only log.
 // =============================================================================
 
 function offsetOf(cursor: SyncCursorPayload | null): number {

package/packages/bundled-features/src/jobs/db/queries/retention.ts

@@ -1,4 +1,4 @@
-// Job-run retention (#2243): store_job_runs/store_job_run_logs are
+// Job-run retention: store_job_runs/store_job_run_logs are
 // direct-write stores now, not event-sourced projections — nothing else
 // purges them, so without this query they grow forever with the run count
 // instead of the runtime. Not the retention-cleanup executor: that executor
@@ -44,7 +44,7 @@ export async function deleteStaleJobRuns(
     { limit: RETENTION_DELETE_BATCH_SIZE },
   );
 
-  // Same window for the tenant-visible failure records (fw#3079): the run
+  // Same window for the tenant-visible failure records: the run
   // they point at is gone by now, and a job whose subject never ran again
   // would otherwise keep its record forever.
   const tenantFailuresResult = await deleteManyBatched(

package/packages/bundled-features/src/jobs/db/queries/stale-run-sweep.ts

@@ -1,5 +1,5 @@
-// Stale job-run sweep (#2246): store_job_runs is a direct-write store
-// (#2243) — status is set to "running" once at onJobStart and only ever
+// Stale job-run sweep: store_job_runs is a direct-write store
+// Status is set to "running" once at onJobStart and only ever
 // flipped to "completed"/"failed" by onJobComplete/onJobFailed. If the
 // process dies mid-run (crash, OOM, kill -9), those callbacks never fire and
 // the row is stuck on "running" forever — nothing else on the read side
@@ -48,7 +48,7 @@ export async function markStaleJobRunsFailed(
   // user subject annotation as job-run-logger.ts's onJobFailed path
   // (personal: { of: "triggeredById" } on job-run-table.ts), so it is encrypted
   // under the triggering user's DEK, or the system tenant key when
-  // triggeredById is null (whenAbsent: "tenant", fw#3654). Runs are grouped by
+  // triggeredById is null (whenAbsent: "tenant"). Runs are grouped by
   // that subject: one encrypt and one updateMany per subject instead of per run.
   const stale = await selectMany<{ id: string; triggeredById: string | null }>(db, jobRunsTable, {
     status: "running",

package/packages/bundled-features/src/jobs/events.ts

@@ -1,4 +1,4 @@
-// Payload schemas for the jobRun direct-write path (#2243). Pre-#2243 these
+// Payload schemas for the jobRun direct-write path. Previously these
 // backed jobRun's event-store payloads (r.defineEvent + inline projections);
 // now job-run-logger.ts parses against them before writing straight into
 // jobRunsTable/jobRunLogsTable, so an out-of-dispatcher write still gets the

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

@@ -44,7 +44,7 @@ export type JobsFeatureOptions = {
   // which a tenant-visible "queued" row counts as lost and is dropped by the stale-run sweep.
   readonly retentionDays?: number;
   // How long a run can sit at status "running" before the hourly
-  // stale-run-sweep job marks it "failed" (#2246 — a process kill mid-run
+  // stale-run-sweep job marks it "failed" — a process kill mid-run
   // never fires onJobComplete/onJobFailed, so nothing else ever revisits
   // it). Must clear any legitimately long-running job (reindexEntity,
   // projectionRebuild) — set high, not tight.
@@ -67,11 +67,10 @@ export function createJobsFeature(options: JobsFeatureOptions = {}): FeatureDefi
     r.storeTable(jobRunsTableMeta, {
       reason: "direct_write.job_runs",
       // payload/error carry personal:{of:"triggeredById"} (job-run-table.ts): encrypted under the
-      // triggering user's DEK, or the system tenant key when triggeredById is null
-      // (whenAbsent: "tenant", fw#3654).
+      // triggering user's DEK, or the system tenant key when triggeredById is null.
       // job-run-logger.ts manually encrypts both before every insert/update
       // (encryptStartedPayload/encryptFailureError) since this store bypasses
-      // the executor's automatic PII pipeline (#2243).
+      // the executor's automatic PII pipeline.
       piiEncryptedOnWrite: true,
     });
     r.storeTable(jobRunLogsTableMeta, {
@@ -91,7 +90,7 @@ export function createJobsFeature(options: JobsFeatureOptions = {}): FeatureDefi
       projectionRebuildJob,
     );
 
-    // Retroactive search backfill (#1206/#1215) — manual + perTenant, so one
+    // Retroactive search backfill — manual + perTenant, so one
     // `jobs:write:trigger` call with { entity } fans out to every active
     // tenant (job-runner.ts perTenant dispatch applies to manual triggers
     // too, not just cron).
@@ -107,7 +106,7 @@ export function createJobsFeature(options: JobsFeatureOptions = {}): FeatureDefi
     );
 
     // store_job_runs/store_job_run_logs are direct-write, unbounded-growth
-    // stores (#2243) — nothing else purges them.
+    // stores — nothing else purges them.
     r.job(
       "retention-cleanup",
       { trigger: { cron: "0 3 * * *" }, concurrency: "skip" },
@@ -115,7 +114,7 @@ export function createJobsFeature(options: JobsFeatureOptions = {}): FeatureDefi
     );
 
     // Sweeps store_job_runs for rows stuck at status "running" past the
-    // timeout (#2246). Hourly matches the timeout's own granularity —
+    // timeout. Hourly matches the timeout's own granularity —
     // frequent enough to catch a stuck run soon after it crosses the
     // threshold, cheap enough that an (almost always empty) result set
     // doesn't matter.

package/packages/bundled-features/src/jobs/handlers/detail.query.ts

@@ -32,12 +32,12 @@ export const detailQuery = defineQueryHandler({
 
     if (!row) return null;
 
-    // payload is stored encrypted under the triggering user's DEK (#799).
+    // payload is stored encrypted under the triggering user's DEK.
     if (typeof row["payload"] === "string") {
       row["payload"] = await decryptStoredPii(row["payload"], "payload", "job-run-detail");
     }
 
-    // error is stored encrypted under the triggering user's DEK (#2307),
+    // error is stored encrypted under the triggering user's DEK,
     // same mechanism as row.payload above.
     if (typeof row["error"] === "string") {
       row["error"] = await decryptStoredPii(row["error"], "error", "job-run-detail");
@@ -52,8 +52,8 @@ export const detailQuery = defineQueryHandler({
       },
     );
 
-    // message is stored encrypted under the triggering user's DEK (#2247),
-    // same mechanism as row.payload above. Bounded concurrency (#2307) —
+    // message is stored encrypted under the triggering user's DEK,
+    // same mechanism as row.payload above. Bounded concurrency —
     // unbounded Promise.all would fire one decrypt per log line at once
     // against the KMS adapter's pool.
     const decryptedLogs = await mapWithConcurrency(logs, KMS_POOL_CONCURRENCY, async (log) => {

package/packages/bundled-features/src/jobs/handlers/list.query.ts

@@ -109,7 +109,7 @@ export const listQuery = defineQueryHandler({
     // capped at the page size and would silently undercount the total.
     const total =
       query.payload.totalCount === true ? await countWhere(db, jobRunsTable, where) : undefined;
-    // payload/error are stored encrypted under the triggering user's DEK (#799, #2307).
+    // payload/error are stored encrypted under the triggering user's DEK.
     return {
       rows: await mapWithConcurrency(rows, KMS_POOL_CONCURRENCY, decryptRunRow),
       nextCursor: hasMore ? encodeCursor(String(offset + limit)) : null,

package/packages/bundled-features/src/jobs/handlers/projection-rebuild.job.ts

@@ -8,7 +8,7 @@ import * as z from "zod";
 
 export const projectionRebuildPayloadSchema = z.object({
   projection: z.string().min(1),
-  // Quarantine mode (#760): skip + dead-letter poison events instead of
+  // Quarantine mode: skip + dead-letter poison events instead of
   // failing the whole rebuild. Operator opt-in per run.
   skipApplyErrors: z.boolean().optional(),
 });

package/packages/bundled-features/src/jobs/handlers/reindex-entity.job.ts

@@ -1,4 +1,4 @@
-// Manual, perTenant backfill job (#1206/#1215) — indexes existing rows for
+// Manual, perTenant backfill job — indexes existing rows for
 // an entity that only got `searchable: true` after rows already existed.
 // perTenant fan-out (job-runner.ts) also applies to a manual dispatch, not
 // just cron: one `jobs:write:trigger` call with { entity } re-runs once per

package/packages/bundled-features/src/jobs/handlers/retry.write.ts

@@ -58,7 +58,7 @@ export const retryWrite = defineWriteHandler({
       );
     }
 
-    // payload is stored encrypted under the triggering user's DEK (#799),
+    // payload is stored encrypted under the triggering user's DEK,
     // same mechanism as detail.query.ts/list.query.ts — decrypt before
     // parsing it as JSON. A key erased since the run finished decrypts to
     // PII_ERASED_SENTINEL, which is not JSON; reject the retry rather than

package/packages/bundled-features/src/jobs/job-instant.ts

@@ -1,6 +1,6 @@
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 
-// kumiko-framework#1525: the five value-position Temporal.Instant.from
+// The five value-position Temporal.Instant.from
 // call sites in feature.ts live inside defineApply callbacks with no
 // exported seam, so this thin wrapper gives the ambient-global-independence
 // regression test something to import directly.

package/packages/bundled-features/src/jobs/job-run-logger.ts

@@ -41,9 +41,9 @@ import { tenantJobRunsTable } from "./tenant-job-run-table.ts";
 // every connection in the pool.
 const KMS_POOL_CONCURRENCY = 4;
 
-// Direct-write job-run log (#2243): onJobStart/-Complete/-Failed write
+// Direct-write job-run log: onJobStart/-Complete/-Failed write
 // straight into jobRunsTable / jobRunLogsTable instead of appending to the
-// event store and replaying through inline projections. Pre-#2243 every run
+// event store and replaying through inline projections. Before this change every run
 // left two permanent `kumiko_events` rows that nothing else ever replayed
 // or MSP-subscribed to — in two production apps that was ~99% of all
 // events. Same tables, same shape, no event stream in between.
@@ -76,7 +76,7 @@ const DEFAULT_CACHE_TTL_MS = 60 * 60 * 1000; // 1 hour
 
 // Run rows hang on SYSTEM_TENANT_ID and a null trigger is a cron/system run;
 // job-run-table.ts declares whenAbsent: "tenant" for exactly that case, so the
-// logger must resolve the same subject the entity chain would (fw#3654).
+// logger must resolve the same subject the entity chain would.
 function jobRunSubject(triggeredById: string | null): SubjectId {
   return triggeredById === null
     ? { kind: "tenant", tenantId: SYSTEM_TENANT_ID }
@@ -112,12 +112,12 @@ async function encryptOrSentinel(
 }
 
 // Same per-subject encryption as encryptStartedPayload, applied to each
-// batched log line's `message` (#2247) before insertMany into
+// batched log line's `message` before insertMany into
 // jobRunLogsTable — that table is unmanaged/direct-write, so there is no
 // event-piiFields catalog to lean on here either. "message" is the AAD
 // field name and must match the field passed to decryptStoredPii on read
 // (detail.query.ts) or decrypt fails loud. Same skip rule as the payload:
-// absent KMS (rollout mode) stays plaintext. Bounded concurrency (#2307) —
+// absent KMS (rollout mode) stays plaintext. Bounded concurrency —
 // unbounded Promise.all would fire one getOrCreateDek per log line at once
 // against the KMS adapter's pool.
 async function encryptLogMessages<T extends { readonly message: string }>(
@@ -133,7 +133,7 @@ async function encryptLogMessages<T extends { readonly message: string }>(
   }));
 }
 
-// Mirrors encryptFailureError for the failure-path `error` column (#2307):
+// Mirrors encryptFailureError for the failure-path `error` column:
 // stored alongside logs[].message under the same triggering user's DEK, so
 // a log/error pair from the same failed run decrypt together or erase
 // together. Exported so stale-run-sweep.ts's crash-recovery write (a
@@ -149,12 +149,12 @@ export async function encryptFailureError(
 }
 
 // The run-started payload can carry arbitrary user data; triggeredById
-// names its owning user. No event-PII catalog involved (#2243 removed the
-// jobRun r.defineEvent registrations, so there is nothing to catalog) —
-// the subject is known statically, so we encrypt directly. A null subject
+// names its owning user. No event-PII catalog involved (the
+// jobRun r.defineEvent registrations were removed, so there is nothing to
+// catalog) — the subject is known statically, so we encrypt directly. A null subject
 // (system cron runs, recipient-less triggers) encrypts under the system
 // tenant key. Absent KMS adapter stays plaintext (rollout mode, unchanged).
-// A key already erased by the time the trigger lands (#2307) must not fail
+// A key already erased by the time the trigger lands must not fail
 // the whole run-start write — sentinel like the log/error paths.
 async function encryptStartedPayload(
   payload: string | null,
@@ -173,13 +173,12 @@ const TENANT_JOB_FAILURE_LOCK_NAMESPACE = 0x746a666c;
 const TENANT_JOB_RUN_LOCK_NAMESPACE = 0x746a726c;
 const TENANT_RUN_CONFLICT_KEYS = ["tenantId", "jobName", "bullJobId"] as const;
 
-// fw#3079 — which row the tenant-visible failure record lives in: one per
+// Which row the tenant-visible failure record lives in: one per
 // (tenant, job, subject), so the next outcome of the same work replaces or
 // clears it. `subject` is null for a job that declares no subjectFields.
 // Null target = nothing to write or clear: the job did not opt in, the run
 // was tenant-less (cron resolves to SYSTEM_TENANT_ID, where no tenant-scoped
-// query could ever read the row), or the caller predates fw#3079 and passes
-// no outcome at all.
+// query could ever read the row), or the caller passes no outcome at all.
 function tenantJobFailureTarget(
   jobName: string,
   outcome: JobOutcomeMeta | undefined,
@@ -229,7 +228,7 @@ async function clearTenantJobFailure(
   await deleteMany(db, tenantJobFailuresTable, where);
 }
 
-// fw#3616 — tenant-visible run state. One row per BullMQ job in
+// Tenant-visible run state. One row per BullMQ job in
 // store_tenant_job_runs, addressed by (tenant, job name, bullJobId): BullMQ
 // ids are only unique per queue (api and worker lane both count from 1) and
 // restart after a Redis reset, so the id alone must never pick a row. The
@@ -445,7 +444,7 @@ export function createJobRunLogger(opts: JobRunLoggerOptions): JobRunLoggerCallb
   // Bounded cache (LRU-ish with TTL) — worker-crash between start and
   // complete would otherwise leak entries. DB-lookup recovers evicted
   // entries via bull_job_id on jobRunsTable.
-  // triggeredById rides along with runId (#2247) — resolved once at start
+  // triggeredById rides along with runId — resolved once at start
   // (or on cache-miss DB fallback) so onJobComplete/-Failed know the log
   // subject without an extra always-on DB round trip.
   type CacheEntry = {

package/packages/bundled-features/src/jobs/job-run-table.ts

@@ -18,10 +18,10 @@ import {
 export type JobRunStatus = "queued" | "running" | "completed" | "failed";
 export type JobLogLevel = "info" | "warn" | "error";
 
-// jobRun is a system-scoped direct-write store (#2243): every job execution
+// jobRun is a system-scoped direct-write store: every job execution
 // writes straight into jobRunsTable / jobRunLogsTable from the BullMQ
 // callbacks (onJobStart / -Complete / -Failed, see job-run-logger.ts) —
-// no event-store detour. Pre-#2243 this was an events-only aggregate
+// no event-store detour. Previously this was an events-only aggregate
 // replayed through two inline projections; that generated two permanent
 // `kumiko_events` rows per run for data that is itself already the
 // system of record (no other consumer replays or MSP-subscribes to it).
@@ -38,7 +38,7 @@ export type JobLogLevel = "info" | "warn" | "error";
 // app boundary (same pattern as template-resolver kind/scope).
 // `table: "store_job_runs"` (not `read_*`) because this is no longer a
 // rebuildable projection — `defineUnmanagedTable`/`deriveEntityTableMeta`
-// reject the `read_` prefix for `source: "unmanaged"` (#1208/#1220).
+// reject the `read_` prefix for `source: "unmanaged"`.
 export const jobRunEntity = createEntity({
   table: "store_job_runs",
   fields: {

package/packages/bundled-features/src/jobs/screens.ts

@@ -111,7 +111,7 @@ export const jobRunDetailScreen: ProjectionDetailScreenDefinition = {
           "error",
         ],
       },
-      // No section `title` here (fw#2312 label-dedup fix): the section
+      // No section `title` here (label-dedup fix): the section
       // holds exactly one field, so a title would repeat the field's own
       // label (rendered by RenderField as the Field's heading) verbatim.
       {

package/packages/bundled-features/src/jobs/tenant-job-failure-table.ts

@@ -11,7 +11,7 @@ import {
   uuid,
 } from "@cosmicdrift/kumiko-framework/db";
 
-// The tenant's own view of a failed job (fw#3079). Direct-write store like
+// The tenant's own view of a failed job. Direct-write store like
 // store_job_runs: job-run-logger.ts writes it from the BullMQ callbacks,
 // outside any dispatcher transaction.
 //

package/packages/bundled-features/src/jobs/tenant-job-run-table.ts

@@ -13,7 +13,7 @@ import {
 
 export type TenantJobRunStatus = "queued" | "running" | "completed" | "failed";
 
-// The tenant's own view of a job's run state (fw#3616). Direct-write store
+// The tenant's own view of a job's run state. Direct-write store
 // like store_job_runs, written by job-run-logger.ts from the runner callbacks.
 //
 // store_job_runs cannot serve the tenant: it anchors every run on the system

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

@@ -13,7 +13,7 @@ import { ACCOUNT_TYPES, SCHEDULE_INTERVALS, TRANSACTION_STATUS } from "./web/con
 // 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.
+// money column — balances are DERIVED from postings, 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",
@@ -49,13 +49,13 @@ export const accountEntity = createEntity({
 // 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
+// framework projects `read_ledger_transactions`; a flat
+// `read_ledger_postings` projection (one row per line) supports 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.
+// posted entry is a fact; corrections are reverse-transaction entries.
+// `status` carries draft|posted.
 export const transactionEntity = createEntity({
   table: "read_ledger_transactions",
   description:

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

@@ -7,8 +7,8 @@
 //      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.
+// is accounts + balanced transactions on top. Balances and reports (balance
+// sheet, P&L, cashflow) are pure queries over the postings, never stored state.
 //
 // Spec: kumiko-platform/docs/plans/ledger-feature.md
 
@@ -60,7 +60,7 @@ function registerLedger(
 
   // 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).
+  // the postings projection.
   r.writeHandler(
     defineEntityCreateHandler("account", accountEntity, {
       access,

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

@@ -27,11 +27,11 @@ const CONFIRM_PERIOD_LOCK_NAMESPACE = 0x6c637370;
 // 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
+// Idempotent and 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.
+// exist) mirrors create-transaction because a schedule could name a bogus
+// account that the generic CRUD create does not check.
 export function createConfirmSchedulePeriodHandler(
   access: AccessRule = DEFAULT_LEDGER_ACCESS,
 ): WriteHandlerDef {

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

@@ -1,17 +1,17 @@
 // 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:
+// booking template ("Rent from 1/1/2026, €500/month") used 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.
+//   • projectSchedule()      — the forecast: a pure projection over a window with
+//                              no transactions required (chart, "does it pay for itself?").
+//   • mergeScheduleActuals() — forecast vs. actual: the projection left-joined
+//                              against posted confirmations (by `reference`), so
+//                              each month is posted | open | forecast.
 //
-// confirm-schedule-period (handler) turns one projected month into ONE balanced
+// The 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.
+// pure—no DB or Date API (windows/asOf are supplied as parameters)—so the forecast
+// remains deterministic and the no-date-api guard stays green.
 
 import type { Posting } from "./schemas.ts";
 import type { ScheduleInterval } from "./web/constants.ts";
@@ -109,8 +109,8 @@ export function projectSchedule(
   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
+// Planned vs. actual. A month is `posted` when a confirmation for its reference exists
+// AND has not been reversed; 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(

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

@@ -24,7 +24,7 @@ export const createTransactionPayloadSchema = z
     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.
+    // the debit/recurring work — 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.

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

@@ -30,7 +30,7 @@ export const LedgerQueries = {
   transactionDetail: "ledger:query:transaction:detail",
   scheduleList: "ledger:query:schedule:list",
   scheduleDetail: "ledger:query:schedule:detail",
-  // Reports — pure aggregations over the posted entries (Phase 1).
+  // Reports — pure aggregations over the posted entries.
   reportBalances: "ledger:query:report:balances",
   reportIncomeStatement: "ledger:query:report:income-statement",
   reportBalanceSheet: "ledger:query:report:balance-sheet",
@@ -38,7 +38,7 @@ export const LedgerQueries = {
 
 // 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.
+// 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];
 

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

@@ -1,10 +1,10 @@
-// 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 postgres-js — 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.
+// Client-safe ledger surface: QN constants, pure recurring helpers
+// (projection + Soll/Ist merge), and Zod payload schemas for client-side
+// pre-validation before dispatch. The full `../ledger` entry also re-exports
+// the feature/handlers/executor, which pull postgres-js; importing it in a
+// browser bundle fails on Node builtins. Client screens import dispatch QNs and
+// pure forecast/merge helpers from this module, then dispatch via the renderer's
+// useDispatcher.
 
 export {
   type LedgerTxRow,