@cosmicdrift/kumiko-framework 0.386.0 → 0.387.0

package/dist/db/located-timestamp.d.ts

@@ -1,13 +1,13 @@
 import type { EntityDefinition } from "../engine/types/index.ts";
 /**
- * API → DB: locatedTimestamp-Felder zu zwei flachen Spalten flatten.
+ * API → DB: flatten locatedTimestamp fields into two flat columns.
  *
- * - `{ at, tz }` (UI-Form) → `{ <name>Utc, <name>Tz }` (utc via Temporal berechnet)
- * - `{ utc, tz }` (Server-Form) → utc gewinnt direkt
- * - `{ at, tz, utc }` → utc gewinnt; at wird ignoriert (Konsistenz-Check ist
- *   Caller-Verantwortung)
+ * - `{ at, tz }` (UI form) → `{ <name>Utc, <name>Tz }` (`utc` calculated via Temporal)
+ * - `{ utc, tz }` (server form) → `utc` takes precedence
+ * - `{ at, tz, utc }` → `utc` takes precedence; `at` is ignored (the caller is
+ *   responsible for the consistency check)
  *
- * Pure — mutiert nicht.
+ * Pure — does not mutate.
  */
 export declare function flattenLocatedTimestamp(payload: Record<string, unknown>, entity: EntityDefinition): Record<string, unknown>;
 /** Shape of a single rehydrated locatedTimestamp field. `at` is the wall clock in `tz`
@@ -18,12 +18,12 @@ export type LocatedTimestampRead = {
     readonly utc: string;
 };
 /**
- * DB → API: zwei flache Spalten zu combined { at, tz, utc } rehydraten.
+ * DB → API: rehydrate two flat columns into combined { at, tz, utc }.
  *
- * `at` ist immer Wall-Clock in der gespeicherten `tz` (Pickup-Ort-lokal).
- * Wer User-Sicht braucht, leitet aus `utc` selbst ab — der Server kennt
- * keine User-TZ.
+ * `at` is always the wall-clock time in the stored `tz` (local to the pickup
+ * location). To obtain a user-specific view, derive it from `utc` yourself —
+ * the server does not know the user's time zone.
  *
- * Pure — mutiert nicht.
+ * Pure — does not mutate.
  */
 export declare function rehydrateLocatedTimestamp(row: Record<string, unknown>, entity: EntityDefinition): Record<string, unknown>;

package/dist/db/located-timestamp.js

@@ -1,23 +1,22 @@
-// Auto-Convert für locatedTimestamp-Felder im DB-Layer.
+// Automatically converts locatedTimestamp fields in the DB layer.
 //
-// Vertrag (siehe auch db/money.ts — gleicher Compound-Type-Pattern):
-//   API-Form:    { at, tz } | { utc, tz }
-//   DB-Form:     <name>Utc TIMESTAMPTZ + <name>Tz TEXT
-//   Read-Form:   { at, tz, utc }
+// Contract (see also db/money.ts — the same compound-type pattern):
+//   API form:   { at, tz } | { utc, tz }
+//   DB form:    <name>Utc TIMESTAMPTZ + <name>Tz TEXT
+//   Read form:  { at, tz, utc }
 //
-// `at`-Default-Sicht beim Read: Pickup-Ort-lokal (utc projiziert in
-// gespeicherter tz). Server kennt User-TZ nicht — User-spezifische
-// Anzeige passiert client-seitig aus utc.
+// Default `at` view on read: local to the pickup location (`utc` projected into
+// the stored `tz`). The server does not know the user's time zone, so
+// user-specific display is derived from `utc` on the client.
 // Static import, not the ambient global: Bun doesn't expose Temporal on
 // globalThis, so this crashed with "Temporal is not defined" outside boot
-// paths that install it (#1480).
+// paths that install it.
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
-// Sprint F: <name>Utc-Spalte ist jetzt instant() (siehe dialect.ts) —
-// Drizzle gibt direkt Temporal.Instant zurück. Vor Sprint F kam ein PG-
-// Wire-Format-String "2026-04-15 09:00:00+00" rein der via String-Massage
-// zu ISO-8601 gemacht werden musste. Heute übernimmt der customType die
-// Konversion DB↔Instant — diese Funktion ist nur noch defensive Glue für
-// Legacy-Code-Pfade die noch Strings durchreichen (z.B. raw SQL).
+// The <name>Utc column uses instant() (see dialect.ts), so Drizzle returns Temporal.Instant.
+// Previously, a PostgreSQL wire-format string "2026-04-15 09:00:00+00" had to be
+// converted to ISO 8601 through string manipulation. The customType now handles
+// DB↔Instant conversion, so this function is only defensive glue for legacy code
+// paths that still pass strings (for example, raw SQL).
 function toInstant(value) {
     if (value instanceof Temporal.Instant)
         return value;
@@ -27,14 +26,14 @@ function toInstant(value) {
     return Temporal.Instant.from(iso);
 }
 /**
- * API → DB: locatedTimestamp-Felder zu zwei flachen Spalten flatten.
+ * API → DB: flatten locatedTimestamp fields into two flat columns.
  *
- * - `{ at, tz }` (UI-Form) → `{ <name>Utc, <name>Tz }` (utc via Temporal berechnet)
- * - `{ utc, tz }` (Server-Form) → utc gewinnt direkt
- * - `{ at, tz, utc }` → utc gewinnt; at wird ignoriert (Konsistenz-Check ist
- *   Caller-Verantwortung)
+ * - `{ at, tz }` (UI form) → `{ <name>Utc, <name>Tz }` (`utc` calculated via Temporal)
+ * - `{ utc, tz }` (server form) → `utc` takes precedence
+ * - `{ at, tz, utc }` → `utc` takes precedence; `at` is ignored (the caller is
+ *   responsible for the consistency check)
  *
- * Pure — mutiert nicht.
+ * Pure — does not mutate.
  */
 export function flattenLocatedTimestamp(payload, entity) {
     const T = Temporal;
@@ -53,10 +52,10 @@ export function flattenLocatedTimestamp(payload, entity) {
         if (pair.tz === undefined)
             continue;
         const tz = pair.tz;
-        // Sprint F: <name>Utc-Spalte ist instant() — Drizzle erwartet
-        // Temporal.Instant. Konvertierung pair.utc-string → Instant geht via
-        // toInstant() (kennt String + Instant); pair.at + tz → Instant via
-        // Temporal-Math.
+        // The <name>Utc column uses instant(); Drizzle expects
+        // Temporal.Instant. Conversion from pair.utc string → Instant goes through
+        // toInstant() (which handles strings and Instant values); pair.at + tz →
+        // Instant uses Temporal math.
         const instant = pair.utc !== undefined
             ? toInstant(pair.utc)
             : pair.at !== undefined
@@ -70,13 +69,13 @@ export function flattenLocatedTimestamp(payload, entity) {
     return result;
 }
 /**
- * DB → API: zwei flache Spalten zu combined { at, tz, utc } rehydraten.
+ * DB → API: rehydrate two flat columns into combined { at, tz, utc }.
  *
- * `at` ist immer Wall-Clock in der gespeicherten `tz` (Pickup-Ort-lokal).
- * Wer User-Sicht braucht, leitet aus `utc` selbst ab — der Server kennt
- * keine User-TZ.
+ * `at` is always the wall-clock time in the stored `tz` (local to the pickup
+ * location). To obtain a user-specific view, derive it from `utc` yourself —
+ * the server does not know the user's time zone.
  *
- * Pure — mutiert nicht.
+ * Pure — does not mutate.
  */
 export function rehydrateLocatedTimestamp(row, entity) {
     const result = { ...row };

package/dist/db/migrate-generator.d.ts

@@ -3,7 +3,7 @@ import { type RetiredFrameworkTable } from "./retired-framework-tables.ts";
 declare const SNAPSHOT_VERSION: 1;
 export type Snapshot = {
     readonly version: typeof SNAPSHOT_VERSION;
-    readonly generatedAt: string;
+    readonly generatedAt?: string;
     readonly tables: readonly EntityTableMeta[];
 };
 export type ColumnChange = {

package/dist/db/migrate-generator.js

@@ -1,31 +1,36 @@
-// Build-time Generator: EntityTableMeta[] → reviewbares SQL-Migration-File.
-// Ersatz für `drizzle-kit generate`.
+// Build-time generator: EntityTableMeta[] → reviewable SQL migration file.
+// Replacement for `drizzle-kit generate`.
 //
-// **NO-MAGIC-ON-DATA Kernprinzip** (siehe drizzle-replacement.md):
-//   - Generator emittiert SQL-Files für PR-Review/Edit
-//   - Generator wird NIE zur App-Runtime aufgerufen
-//   - Output ist Start-Form; App-Author darf das SQL hand-editieren
-//     (BRIN-Index, partial-Index, performance-tuning) bevor committed
-//   - Append-only: bestehende Migration-Files werden NIE überschrieben.
-//     Neue Schema-Diffs landen in einem NEUEN File mit incrementierter
-//     Sequence-Number.
+// **NO-MAGIC-ON-DATA core principle** (see drizzle-replacement.md):
+//   - The generator emits SQL files for PR review/editing.
+//   - The generator is NEVER called at app runtime.
+//   - The output is a starting point; app authors may hand-edit the SQL
+//     (BRIN index, partial index, performance tuning) before committing.
+//   - Append-only: existing migration files are NEVER overwritten.
+//     New schema diffs go into a NEW file with an incremented sequence number.
 //
-// **DESTRUCTIVE-ops** (DROP TABLE/COLUMN, INDEX-removal) werden als
-// AUSKOMMENTIERTE statements emittiert — Reviewer muss explizit
-// uncommenten + ggf. Data-Backup-Schritt vorlauf einfügen. Default:
-// niemals automatisch droppen.
+// **DESTRUCTIVE operations** (DROP TABLE/COLUMN, index removal) are emitted
+// as commented-out statements — reviewers must explicitly uncomment them
+// and may need to add a data-backup step beforehand. Default:
+// never drop automatically.
 import { readFileSync, writeFileSync } from "node:fs";
 import { errorCodeOf, isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
 import { compareByCodepoint } from "../utils/index.js";
 import { renderIndex, renderTableDdl } from "./render-ddl.js";
 import { findRetiredTableDrops } from "./retired-framework-tables.js";
 const SNAPSHOT_VERSION = 1;
+function isSnapshot(value) {
+    return (isPlainObject(value) &&
+        value["version"] === SNAPSHOT_VERSION &&
+        (value["generatedAt"] === undefined || typeof value["generatedAt"] === "string") &&
+        Array.isArray(value["tables"]));
+}
 export function snapshotFromMetas(metas) {
     // Stable ordering by tableName so the snapshot.json diff in PRs is
     // meaningful (table-add isn't a noisy re-sort of everything). Codepoint, not
     // localeCompare: the snapshot is serialized to byte-exact JSON and the table
     // order carries into the generated migration SQL — locale-dependent ordering
-    // would drift between macOS-dev and Linux-CI (#367).
+    // would drift between macOS-dev and Linux-CI.
     const sorted = [...metas].sort((a, b) => compareByCodepoint(a.tableName, b.tableName));
     return {
         version: SNAPSHOT_VERSION,
@@ -41,6 +46,9 @@ export function loadSnapshotJson(path) {
         if (version !== SNAPSHOT_VERSION) {
             throw new Error(`Snapshot at ${path} has version ${String(version)}, expected ${SNAPSHOT_VERSION}`);
         }
+        if (!isSnapshot(parsed)) {
+            throw new Error(`Snapshot at ${path} is malformed: expected a tables list`);
+        }
         return parsed;
     }
     catch (err) {
@@ -53,7 +61,7 @@ export function writeSnapshotJson(path, snapshot) {
     writeFileSync(path, `${JSON.stringify(snapshot, null, 2)}\n`);
 }
 function indexMetaKey(idx) {
-    // Index-Identität via Name (PG-Constraint: unique innerhalb der DB)
+    // Index identity is based on its name (PostgreSQL constraint: unique within the database).
     return idx.name;
 }
 function indexColumnsEqual(a, b) {
@@ -273,8 +281,7 @@ function renderColumnChange(tableName, change) {
         // timestamptz → date: PG's implicit ::date cast (what a bare ALTER ...
         // TYPE without USING falls back to) reads the session TimeZone, so the
         // same row migrates to a different calendar day depending on who/where
-        // runs it — exactly the non-determinism kumiko-framework#1924 fixes.
-        // Anchor explicitly at UTC instead of trusting the session.
+        // runs it. Anchor explicitly at UTC instead of trusting the session.
         if ((from === "timestamptz" || from === "timestamptz(3)") && to === "date") {
             out.push(`-- ${from} → date: explicit UTC anchor — a bare cast would use the session TimeZone (non-deterministic).`);
             out.push(`ALTER TABLE ${tbl} ALTER COLUMN ${col} TYPE date USING (${col} AT TIME ZONE 'UTC')::date;`);
@@ -383,7 +390,7 @@ export function renderMigrationSql(diff, options) {
                 // needsManualWhere renders CREATE as a commented WARN (renderIndex),
                 // since the generator can't express the new WHERE — the DROP has to
                 // stay commented too, or the live index gets dropped with no
-                // executable replacement (kumiko-framework#2492 review).
+                // executable replacement.
                 lines.push(nextIdxMeta.needsManualWhere === true
                     ? `-- (review) DROP INDEX IF EXISTS ${quoteIdent(idxChange.name)};`
                     : `DROP INDEX IF EXISTS ${quoteIdent(idxChange.name)};`);

package/dist/db/migrate-runner.js

@@ -1,26 +1,26 @@
-// Migrate-Runner: applied checked-in SQL-Files gegen eine DB.
-// Ersatz für `drizzle-kit migrate` als Runtime-Komponente.
+// Migration runner: applies checked-in SQL files to a database.
+// Replaces `drizzle-kit migrate` as a runtime component.
 //
-// **NO-MAGIC-ON-DATA Kernprinzip** (siehe drizzle-replacement.md):
-//   - Runner liest NUR checked-in `<dir>/*.sql` Files
-//   - Kein Reach-back zu EntityDefinition zur Runtime
-//   - Kein Auto-Apply-on-App-Boot — Deploy-Skript oder Init-Container ruft
-//     `kumiko migrate apply` als eigenen Schritt
-//   - Schema-Drift wird durch Checksum-Mismatch fail-loud detektiert
+// **NO-MAGIC-ON-DATA core principle** (see drizzle-replacement.md):
+//   - The runner reads ONLY checked-in `<dir>/*.sql` files.
+//   - It does not reach back to EntityDefinition at runtime.
+//   - It does not auto-apply on app boot — a deploy script or init container
+//     invokes `kumiko migrate apply` as a separate step.
+//   - Schema drift is detected fail-loudly through checksum mismatches.
 //
-// Tracking-Table `_kumiko_migrations(id, applied_at, checksum)`. id = filename
-// ohne .sql-Endung. Checksum = sha256 vom File-Content beim Apply. Wenn ein
-// schon-appliedes File nachträglich editiert wird, schlägt der nächste Apply
-// fehl mit klarer Fehlermeldung (production-DBs haben das alte SQL drin —
-// edit nachträglich = production-state inkonsistent mit committed-state).
+// Tracking table: `_kumiko_migrations(id, applied_at, checksum)`. `id` is the
+// filename without the `.sql` suffix. The checksum is the sha256 hash of the
+// file content at apply time. If an already-applied file is edited, the next
+// apply fails with a clear error (production databases contain the old SQL —
+// editing it makes production state inconsistent with committed state).
 import { createHash } from "node:crypto";
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
 import { asRawClient, hasBegin, } from "./query.js";
-// Advisory-lock key (random 32-bit int, stable). Verhindert dass zwei
-// gleichzeitig bootende Pods beide migrate apply laufen lassen (zweiter
-// blockiert bis erster fertig).
+// Advisory-lock key (random 32-bit integer, stable). Prevents two Pods
+// booting at the same time from both running migrate apply (the second
+// blocks until the first finishes).
 export const MIGRATION_ADVISORY_LOCK_KEY = 0x6b756d69; // "kumi" in ASCII
 const MIGRATIONS_TABLE_DDL = `
 CREATE TABLE IF NOT EXISTS "_kumiko_migrations" (
@@ -147,7 +147,7 @@ function sha256Hex(content) {
 // returns Migration[] with id + checksum + statements. `preprocess` is an
 // optional hook applied to each file's raw content before splitting/hashing
 // — used by replayMigrationsDir to expand its DESTRUCTIVE-marker comments
-// without a second, drifting copy of this file-discovery logic (#1522/9).
+// without a second, drifting copy of this file-discovery logic.
 export function loadMigrationsFromDir(dir, preprocess) {
     const files = readdirSync(dir)
         .filter((f) => f.endsWith(".sql"))
@@ -230,9 +230,9 @@ export class MigrationChecksumMismatchError extends Error {
         this.name = "MigrationChecksumMismatchError";
     }
 }
-// Apply pending migrations. Idempotent: schon applied migrations werden via
-// _kumiko_migrations-Lookup übersprungen. Checksum-Mismatch wirft fail-loud.
-// Advisory-Lock verhindert concurrent-apply-races.
+// Applies pending migrations. Idempotent: already-applied migrations are
+// skipped via the _kumiko_migrations lookup. Checksum mismatches fail loudly.
+// The advisory lock prevents concurrent-apply races.
 export async function runMigrations(db, migrations) {
     // Session-level advisory lock and per-migration BEGIN/COMMIT must share one
     // session. Pool calls may land on different connections (the pool round-robins),
@@ -256,9 +256,9 @@ export async function runMigrations(db, migrations) {
                     skippedIds.push(m.id);
                     continue;
                 }
-                // Apply file content + INSERT tracking-row in einer TX. Wenn ein
-                // Statement bricht, Rollback inkl. Tracking-Row → kein partial-apply
-                // stuck in den books.
+                // Applies the file content and INSERT tracking row in one transaction. If a
+                // statement fails, the rollback includes the tracking row, so no partial
+                // apply remains stuck in the books.
                 await conn.unsafe("BEGIN");
                 try {
                     for (const stmt of m.statements) {
@@ -289,8 +289,8 @@ export async function runMigrations(db, migrations) {
         await conn.release();
     }
 }
-// Convenience: load + run in einem Call. Wird vom `kumiko migrate apply`
-// CLI-Command + von Test-Setup-Helfern verwendet.
+// Convenience: loads and runs migrations in one call. Used by the
+// `kumiko migrate apply` CLI command and by test setup helpers.
 export async function runMigrationsFromDir(db, dir) {
     const migrations = loadMigrationsFromDir(dir);
     return runMigrations(db, migrations);

package/dist/db/money.d.ts

@@ -15,17 +15,17 @@ export type MoneyRead = {
      * @deprecated Removed in 0.390.0. Use `amountScaled` — this name implies ISO-4217 minor units
      * (cents), which is wrong once a currency needing a different scale than
      * the current flat MINOR_UNIT_SCALE=100 lands (e.g. JPY, 0 decimals).
-     * Alias of `amountScaled`, kept until #1976/4 and #1976/5 migrate their
-     * consumers off it.
+     * Alias of `amountScaled`, kept until the consumers migrate off it.
      */
     readonly amountMinor: number;
 };
 /**
- * DB → API: zwei flache Spalten zu combined { amount, currency } rehydraten.
+ * Rehydrate two flat DB columns into a combined `{ amount, currency }` value.
  *
- * Wirft loud bei korrupter DB-Form (string das nicht zur Zahl wird) — silent
- * data-loss wäre Bug-Vektor. NULL/undefined amount → field aus Output entfernt.
+ * Throws loudly for corrupt DB values (for example, a string that cannot be
+ * converted to a number), because silent data loss would hide a bug. A
+ * NULL/undefined amount removes the field from the output.
  *
- * Pure — mutiert nicht.
+ * Pure — does not mutate its input.
  */
 export declare function rehydrateMoney(row: Record<string, unknown>, entity: EntityDefinition): Record<string, unknown>;

package/dist/db/money.js

@@ -1,17 +1,17 @@
-// Auto-Convert für money-Felder im DB-Layer.
+// Automatically convert money fields in the DB layer.
 //
-// Vertrag (siehe auch db/located-timestamp.ts — gleicher Compound-Type-Pattern):
-//   API-Form:    { amount, currency } | number — amount in MAJOR units (56799.16 EUR)
-//   DB-Form:     <name> BIGINT (minor units, e.g. cents) + <name>Currency TEXT
-//   Read-Form:   { amount, currency, amountScaled } — amount in MAJOR units again,
-//                amountScaled sits alongside as the exact integer value in
-//                MINOR_UNIT_SCALE units (fw#1830) for callers that need
-//                scale-exact comparisons (e.g. invoice sums) instead of
-//                round-tripping the float amount through /100·*100.
+// Contract (see also db/located-timestamp.ts — the same compound-type pattern):
+//   API form:   { amount, currency } | number — amount in MAJOR units (56799.16 EUR)
+//   DB form:    <name> BIGINT (minor units, e.g. cents) + <name>Currency TEXT
+//   Read form:  { amount, currency, amountScaled } — amount in MAJOR units again,
+//               amountScaled sits alongside as the exact integer value in
+//               MINOR_UNIT_SCALE units for callers that need scale-exact
+//               comparisons (e.g. invoice sums) instead of round-tripping the
+//               float amount through /100·*100.
 //                `amountMinor` stays as a @deprecated alias of the same
-//                value until #1976/4 and #1976/5 migrate their remaining
-//                consumers (renderer/web/primitives/index.tsx,
-//                renderer/components/render-field.tsx) off the old name.
+//               value until the remaining consumers
+//               (renderer/web/primitives/index.tsx,
+//               renderer/components/render-field.tsx) migrate off the old name.
 //
 // table-builder.ts's moneyAmount column has always documented BIGINT as
 // "the integer minor unit" — this file used to just pass the API amount
@@ -23,13 +23,13 @@
 // pass/receive ordinary decimal amounts; DB storage stays exact-integer
 // cents (no float drift in SUM()/aggregate queries).
 //
-// Permissiv-Insert: primitive number wird als amount akzeptiert (Legacy aus
-// pre-Stufe-3-Samples). Currency fällt dann auf entity.defaultCurrency
-// zurück (oder DEFAULT_CURRENCIES[0] = "EUR" als Framework-Fallback).
+// Permissive insert: a primitive number is accepted as amount (legacy from
+// pre-Stufe-3 samples). Currency then falls back to entity.defaultCurrency
+// (or DEFAULT_CURRENCIES[0] = "EUR" as the framework fallback).
 //
-// Anders als locatedTimestamp behalten wir den Field-Namen `<name>` als
-// amount-Spalte (Legacy DB-Convention für Money — `SUM(buying_price)` bleibt
-// idiomatisch). `<name>Currency` ist die zusätzliche Spalte.
+// Unlike locatedTimestamp, we retain the field name `<name>` as the
+// amount column (legacy DB convention for money — `SUM(buying_price)` remains
+// idiomatic). `<name>Currency` is the additional column.
 import { MINOR_UNIT_SCALE, toMinorUnits } from "../engine/minor-units.js";
 import { DEFAULT_CURRENCIES } from "../engine/types/index.js";
 const FRAMEWORK_DEFAULT_CURRENCY = DEFAULT_CURRENCIES[0]; // "EUR"
@@ -46,9 +46,9 @@ function toMajorUnits(amountScaled) {
 // scaled the same way. `applyTotalsMatchRefinements` (schema-builder.ts)
 // uses this internally for `EmbeddedFieldDef.totalsMatch`; exported so a
 // custom write-handler doing its own total check doesn't have to re-derive
-// this unwrap-and-scale step by hand (kumiko-framework#1972 — a hand-rolled
-// comparison of a raw `{amount}` against a raw minor-unit row sum is exactly
-// what silently fails 100x off).
+// this unwrap-and-scale step by hand. A hand-rolled comparison of a raw
+// `{amount}` against a raw minor-unit row sum is exactly what silently fails
+// 100× off.
 export function moneyPayloadToMinorUnits(raw) {
     if (typeof raw === "number")
         return toMinorUnits(raw);
@@ -81,7 +81,7 @@ export function flattenMoney(payload, entity) {
         }
         else if (typeof raw === "number") {
             amount = raw;
-            // Expliziter currency-key im Payload überschreibt den Default-Fallback.
+            // An explicit currency key in the payload overrides the default fallback.
             const explicitCurrency = result[`${name}Currency`];
             currency = typeof explicitCurrency === "string" ? explicitCurrency : fallbackCurrency;
         }
@@ -95,12 +95,13 @@ export function flattenMoney(payload, entity) {
     return result;
 }
 /**
- * DB → API: zwei flache Spalten zu combined { amount, currency } rehydraten.
+ * Rehydrate two flat DB columns into a combined `{ amount, currency }` value.
  *
- * Wirft loud bei korrupter DB-Form (string das nicht zur Zahl wird) — silent
- * data-loss wäre Bug-Vektor. NULL/undefined amount → field aus Output entfernt.
+ * Throws loudly for corrupt DB values (for example, a string that cannot be
+ * converted to a number), because silent data loss would hide a bug. A
+ * NULL/undefined amount removes the field from the output.
  *
- * Pure — mutiert nicht.
+ * Pure — does not mutate its input.
  */
 export function rehydrateMoney(row, entity) {
     const result = { ...row };
@@ -126,7 +127,8 @@ export function rehydrateMoney(row, entity) {
             }
         }
         else if (typeof amountRaw === "string" && amountRaw !== "") {
-            // PG-driver liefert BIGINT manchmal als String (>2^53 sicher).
+            // The PG driver sometimes returns BIGINT as a string (when it exceeds the
+            // safe integer range of 2^53).
             amountScaled = Number(amountRaw);
             if (!Number.isSafeInteger(amountScaled)) {
                 throw new Error(`rehydrateMoney: field "${name}" amount string "${amountRaw}" is not a safe integer — DB corruption?`);

package/dist/db/queries/backfill-pii.js

@@ -1,18 +1,18 @@
-// One-time backfill for pre-KMS plaintext PII in kumiko_events (#799).
+// One-time backfill for pre-KMS plaintext PII in kumiko_events.
 //
-// Crypto-shredding (#724/#818) only covers NEW writes — events appended
+// Crypto-shredding only covers NEW writes — events appended
 // before a KMS was configured still carry plaintext (user.created email,
 // delivery attempt recipientAddress, job payloads). This tool re-encrypts
 // them in place, per field, under the owning subject's DEK:
 //
 //   - entity lifecycle events (<entity>.created/updated/deleted/forgotten/
 //     restored) for every entity with PII subject annotations — generic over
-//     subject kind (user/tenant/record, fw#2790), since it goes through the
+//     subject kind (user/tenant/record), since it goes through the
 //     same collectPiiEncryptedFields/resolveSubjectForField the live write
 //     path uses
 //   - custom events from the event-PII catalog (r.defineEvent piiFields) —
 //     user/tenant/self subjects, via the same resolveEventSubject the live
-//     append path uses (fw#2801)
+//     append path uses
 //
 // Already-forgotten subjects must NOT get a fresh key minted for their old
 // plaintext — three erased-detection layers write [[erased]] instead:
@@ -28,7 +28,7 @@
 // Owner resolution for entity-lifecycle events. The live write path
 // (event-store-executor-write.ts) resolves the same chain via
 // subject-resolver.ts: row owner, then the owner the same event sets, then
-// the field's whenAbsent (fw#3654). Backfill adds two opt-in stages and
+// the field's whenAbsent. Backfill adds two opt-in stages and
 // delays whenAbsent behind the projection so a known owner is never shadowed:
 //   1. payload — the event section (plus the owner the same event sets) names
 //      the owner field; whenAbsent is not applied yet.

package/dist/db/queries/ddl.js

@@ -12,7 +12,7 @@ export async function alterTableAddColumn(db, tableName, columnName, columnType,
 // throwing when a column already exists with a different shape than
 // EntityTableMeta expects — that's how it surfaces drift. Callers that
 // just need an idempotent, race-safe backfill (e.g. event-consumer-state's
-// multi-instance boot path, #1362) opt in explicitly.
+// multi-instance boot path) opt in explicitly.
 ifNotExists = false) {
     await asRawClient(db).unsafe(`ALTER TABLE ${quoteTableIdent(tableName)} ADD COLUMN ${ifNotExists ? "IF NOT EXISTS " : ""}${quoteTableIdent(columnName)} ${columnType}${defaultClause}${notNull}`);
 }

package/dist/db/queries/es-ops.d.ts

@@ -1,5 +1,5 @@
 import type { AnyDb } from "../query.ts";
-/** Stabiler Lock-Key für pg_advisory_xact_lock — multi-replica seed boots. */
+/** Stable lock key for pg_advisory_xact_lock across multi-replica seed boots. */
 export declare const ES_OPS_ADVISORY_LOCK_KEY = 1702063984;
 export declare function acquireEsOpsAdvisoryLock(db: AnyDb): Promise<void>;
 export declare function esOperationExists(db: AnyDb, operationId: string): Promise<boolean>;

package/dist/db/queries/es-ops.js

@@ -1,5 +1,5 @@
 import { asRawClient } from "../query.js";
-/** Stabiler Lock-Key für pg_advisory_xact_lock — multi-replica seed boots. */
+/** Stable lock key for pg_advisory_xact_lock across multi-replica seed boots. */
 export const ES_OPS_ADVISORY_LOCK_KEY = 0x65_73_6f_70; // 'esop'
 export async function acquireEsOpsAdvisoryLock(db) {
     await asRawClient(db).unsafe(`SELECT pg_advisory_xact_lock($1)`, [ES_OPS_ADVISORY_LOCK_KEY]);

package/dist/db/queries/event-consumer.js

@@ -24,7 +24,7 @@ export async function lockEventConsumersShareMode(db) {
     await asRawClient(db).unsafe(`LOCK TABLE "kumiko_event_consumers" IN SHARE MODE`);
 }
 // The MAX(id) horizon plus every currently-open id gap below it, read from a
-// single statement snapshot. Used both to seed startFrom "now" (#3231) and to
+// single statement snapshot. Used both to seed startFrom "now" and to
 // seed an MSP rebuild's handoff to the live dispatcher (msp-rebuild.ts).
 //
 // Scan lower bound: the consumer with the highest cursor already tracks every
@@ -84,7 +84,7 @@ export async function selectEventIdHorizonWithMissingRanges(db) {
 // WithMissingRanges): a transaction holding a lower id can still be
 // in-flight at boot, and without seeding those gaps its event would commit
 // after the cursor already sits above it, so `id > cursor` would never
-// deliver it (#3231). The cheap existence check skips the scan entirely for
+// deliver it. The cheap existence check skips the scan entirely for
 // the (overwhelmingly common) case of an already-registered consumer.
 // ON CONFLICT DO NOTHING keeps both branches safe for an existing row: the
 // subquery only ever affects the row this statement inserts.
@@ -144,7 +144,7 @@ export async function markConsumerProcessing(db, name, instanceId) {
 // repeated infra blips (the exact case this backoff exists for) dead-letter
 // the consumer on the next real handler failure instead of after
 // maxAttempts. Visibility is covered by last_error, updated_at, and the
-// caller's console.error — status and the cursor are left as-is too, since
+// caller's error log — status and the cursor are left as-is too, since
 // we don't know at this point whether the consumer should be "dead" (that's
 // the deliverEvents/maxAttempts contract, which never ran this pass).
 //

package/dist/db/queries/event-store.js

@@ -1,7 +1,9 @@
+import { createFallbackLogger } from "../../logging/utils.js";
 import { constraintOf, isLockNotAvailable, isTableAlreadyExists, isUniqueViolation, } from "../pg-error.js";
 import { asRawClient, runInNewTransaction, runnerCanBeginTransaction, unsafeReadRetrying, } from "../query.js";
 import { withoutStatementTimeout } from "../statement-timeout.js";
 import { toPostgresArrayLiteral } from "./postgres-array-literal.js";
+const log = createFallbackLogger("event-store");
 // Gap-finality (event-dispatcher pending_gaps) needs every holder of an
 // event id to already have a *real* xact id by the time it inserts — Postgres
 // assigns those lazily on first write, so a bare INSERT alone doesn't
@@ -81,9 +83,9 @@ async function buildIdempotencyKeyIndex(db) {
             // skip: sibling pod already built a valid index — this race loser is done.
             if ((await indexValidity(client)) === true)
                 return;
-            console.warn(`ensureIdempotencyKeyIndex: backed off on a "benign" race (${String(e)}) but ` +
+            log.warn(`ensureIdempotencyKeyIndex: backed off on a "benign" race but ` +
                 `"events_idempotency_uq" is still missing/invalid afterward — likely a ` +
-                `lock_timeout during CREATE INDEX CONCURRENTLY, not an actual winner/loser race.`);
+                `lock_timeout during CREATE INDEX CONCURRENTLY, not an actual winner/loser race.`, { err: e });
             throw e;
         }
         throw duplicateIdempotencyKeyErrorOr(e);

package/dist/db/queries/projection-rebuild.js

@@ -14,7 +14,7 @@ export async function markProjectionRebuilding(db, projectionName) {
 export async function selectEventsForProjectionRebuildBatch(db, aggregateTypes, eventTypes, afterId, limit) {
     // Archived streams don't replay (Marten-aligned): their aggregates are
     // frozen ops-tombstones — replaying them would resurrect rows (or, for
-    // stranded duplicate-aggregates like fw#832, collide on unique indexes).
+    // stranded duplicate-aggregates, collide on unique indexes).
     return unsafeReadRetrying(db, `SELECT * FROM "kumiko_events" e
      WHERE e."aggregate_type" = ANY($1::text[])
        AND e."type" = ANY($2::text[])
@@ -29,9 +29,9 @@ export async function selectEventsForProjectionRebuildBatch(db, aggregateTypes,
 // Total subscribed events in the log — same source/type filter as
 // selectEventsForProjectionRebuildBatch, no id cursor. Under the cutover fence
 // this is the ground-truth count the rebuild must have applied; a shortfall
-// means a lower-id event committed late and the id-cursor leapt past it (#443).
+// means a lower-id event committed late and the id-cursor leapt past it.
 export async function countSubscribedEvents(db, aggregateTypes, eventTypes) {
-    // Same archived-streams exclusion as the batch query — the #443 recompute
+    // Same archived-streams exclusion as the batch query — the recompute
     // compares this count against applied events; a filter mismatch would make
     // every rebuild with an archived stream loop the full-re-replay forever.
     const rows = await unsafeReadRetrying(db, `SELECT count(*)::bigint AS n FROM "kumiko_events" e

package/dist/db/queries/raw-sql.d.ts

@@ -1,9 +1,9 @@
 import type { AnyDb } from "../query.ts";
 /** Escape hatch for caller-built SQL that may write (or lock). No closed-connection retry —
- *  retrying an ambiguous write risks double-apply (#1358). Prefer {@link executeRawQueryRead}
+ *  retrying an ambiguous write risks double-apply. Prefer {@link executeRawQueryRead}
  *  for SELECT-only paths. */
 export declare function executeRawQuery<T = Record<string, unknown>>(db: AnyDb, sqlText: string, params?: readonly unknown[]): Promise<readonly T[]>;
-/** SELECT-only escape hatch with the #1163 closed-connection retry. Do not pass
+/** SELECT-only escape hatch with the closed-connection retry. Do not pass
  *  INSERT/UPDATE/DELETE — retry re-executes the statement. */
 export declare function executeRawQueryRead<T = Record<string, unknown>>(db: AnyDb, sqlText: string, params?: readonly unknown[]): Promise<readonly T[]>;
 export declare function pingDatabase(db: AnyDb): Promise<void>;