@cosmicdrift/kumiko-framework 0.386.0 → 0.387.0

package/dist/migrations/kumiko-drift.js

@@ -28,18 +28,19 @@ export class SchemaDriftError extends Error {
     }
 }
 export async function detectKumikoDrift(db, migrationsDir) {
-    // App auf neuer Framework-Version, hat aber `./kumiko/migrations` noch nicht
-    // generiert (z.B. erstes Upgrade, custom Schema-Setup ohne kumiko schema
-    // generate) → keine local migrations → keine drift. Konsistent zum
-    // status-Subcommand, der ebenfalls existsSync-guarded ist. Ohne diesen Guard
-    // würde loadMigrationsFromDir → readdirSync synchron ENOENT werfen
-    // (plain Error, kein SchemaDriftError) und der Boot crasht roh.
+    // A newer framework version may not have generated `./kumiko/migrations` yet
+    // (for example, a first upgrade or custom schema setup without `kumiko schema
+    // generate`). Treat this as no local migrations and therefore no drift, matching
+    // the status subcommand's `existsSync` guard. Without it, `loadMigrationsFromDir`
+    // calls `readdirSync`, which throws synchronous ENOENT as a plain Error instead
+    // of SchemaDriftError and causes an unhandled boot failure.
     if (!existsSync(migrationsDir)) {
         return { ok: true, pending: [], checksumMismatches: [], missingTables: [], missingColumns: [] };
     }
     const local = loadMigrationsFromDir(migrationsDir);
-    // Frische DB ohne je gelaufenes `kumiko schema apply` → tracking-table fehlt.
-    // Das ist kein Fehler, sondern "nichts applied" → alle local sind pending.
+    // A fresh database may not have the tracking table because `kumiko schema apply`
+    // has never run. Treat that as no applied migrations, so all local migrations are
+    // pending rather than reporting an error.
     const trackingExists = await tableExists(db, "_kumiko_migrations");
     const applied = trackingExists
         ? new Map((await fetchAppliedMigrations(db)).map((a) => [a.id, a.checksum]))
@@ -117,11 +118,11 @@ export function formatKumikoDriftReport(report) {
             lines.push(`    - ${m.table}: ${m.columns.join(", ")}`);
         }
     }
-    // Per-Cause Remediation — `kumiko schema apply` löst NUR pending. Checksum-
-    // mismatch ist eine Sackgasse für apply (MigrationChecksumMismatchError) und
-    // baseline (ON CONFLICT DO NOTHING → landet in alreadyTracked). Missing
-    // tables ohne pending = manuell gelöschte Tabelle nach apply → ebenfalls
-    // nicht durch apply heilbar.
+    // Remediation depends on the cause: `kumiko schema apply` handles only pending
+    // migrations. A checksum mismatch causes MigrationChecksumMismatchError during
+    // apply, and baseline's ON CONFLICT DO NOTHING leaves it in alreadyTracked.
+    // A missing table with no pending migration was deleted after apply and cannot be
+    // restored by apply.
     lines.push("");
     if (report.pending.length > 0) {
         lines.push("Run 'kumiko schema apply' to apply the pending migration(s).");

package/dist/migrations/pending-rebuilds.d.ts

@@ -5,10 +5,10 @@ import type { Logger } from "../logging/types.ts";
 import { type RebuildResult } from "../pipeline/index.ts";
 export declare const pendingRebuildsTable: import("@cosmicdrift/kumiko-types/executor-brand").WritableSchemaTable;
 export declare function createPendingRebuildsTable(db: DbConnection): Promise<void>;
-/** Liest die rebuild-Marker der frisch applizierten Migrations und queued
- *  die betroffenen Tabellen. Upsert: ein bereits pending-er Tisch behält
- *  seinen Queue-Slot (queued_at bleibt, damit die Reihenfolge stabil ist) —
- *  migration_id zeigt auf die zuletzt flaggende Migration (Debug-Bezug). */
+/** Reads rebuild markers from freshly applied migrations and queues the
+ *  affected tables. Upsert: an already-pending table keeps its queue slot
+ *  (`queued_at` remains unchanged, preserving order), while `migration_id`
+ *  points to the latest migration that flagged it for debugging. */
 export declare function queueRebuildsFromMarkers(db: DbConnection, options: {
     readonly migrationsDir: string;
     readonly appliedIds: readonly string[];
@@ -21,7 +21,7 @@ export declare function listPendingRebuildRows(db: DbConnection): Promise<readon
 export declare function listPendingRebuilds(db: DbConnection): Promise<readonly string[]>;
 export declare function clearPendingRebuilds(db: DbConnection, rows: readonly PendingRebuildRow[]): Promise<void>;
 export type PendingRebuildRun = {
-    /** Erfolgreich rebuildte Projektionen (Queue-Einträge geräumt). */
+    /** Projections rebuilt successfully (queue entries removed). */
     readonly rebuilt: readonly {
         readonly projection: string;
         readonly eventsProcessed: number;
@@ -36,18 +36,19 @@ export type PendingRebuildRun = {
      *  marker) OR were deliberately DROPped by a later migration in the same
      *  run (no data loss, no projection left to resolve) — drained, silent. */
     readonly unmapped: readonly string[];
-    /** In DIESEM Run via Marker geleerte managed-Tabellen ohne auflösbare
-     *  Projektion = das owning-Feature fehlt in der Komposition. Geräumt (kein
-     *  Stuck-Loop), aber LAUT geloggt — die Projektion ist jetzt leer. */
+    /** Managed tables emptied by a marker in THIS run without a resolvable
+     *  projection, indicating that the owning feature is missing from the
+     *  composition. They are drained to avoid a stuck loop, but logged loudly
+     *  because the projection is now empty. */
     readonly unresolvedManaged: readonly string[];
 };
 export type RunPendingRebuildsOptions = {
-    /** Tabellen, die in DIESEM apply-Run frisch via Marker gequeued wurden
-     *  (Rückgabe von `queueRebuildsFromMarkers`). Marker tragen nur managed
-     *  Tabellen — eine davon ohne auflösbare Projektion ist ein echter Defekt
-     *  (fehlendes Feature) und wird laut gemeldet statt still geleert. Fehlt die
-     *  Option, wird jede unmapped Tabelle als pre-existing/benign behandelt
-     *  (Verhalten vor #361). */
+    /** Tables freshly queued via markers in THIS apply run
+     *  (returned by `queueRebuildsFromMarkers`). Markers contain only managed
+     *  tables, so one without a resolvable projection is a real defect (a
+     *  missing feature) and is reported loudly instead of being silently
+     *  drained. Without this option, every unmapped table is treated as
+     *  pre-existing and benign. */
     readonly thisRunTables?: readonly string[];
 };
 export declare function rebuildProjectionOrMultiStream(name: string, deps: {
@@ -63,12 +64,12 @@ export declare function rebuildProjectionOrMultiStream(name: string, deps: {
  *  failed tables stay queued. Shared by every `schema apply` entry point so the
  *  report and the error text cannot drift apart. */
 export declare function reportPendingRebuildRun(run: PendingRebuildRun, log: (line: string) => void): void;
-/** Arbeitet die persistierte Queue ab: mappt Tabellen auf Projektionen,
- *  rebuildet jede betroffene Projektion und räumt ihre Tabellen erst nach
- *  ERFOLG aus der Queue. Fehlgeschlagene bleiben pending — der nächste
- *  apply (oder ein direkter Re-Call) holt sie nach. Unmapped-Tabellen werden
- *  geräumt (kein Stuck-Loop); die in diesem Run frisch geleerten managed-
- *  Tabellen ohne Projektion zusätzlich laut gemeldet (`unresolvedManaged`). */
+/** Processes the persistent queue: maps tables to projections, rebuilds each
+ *  affected projection, and removes its tables from the queue only after
+ *  SUCCESS. Failed tables remain pending and are retried by the next apply
+ *  (or a direct re-call). Unmapped tables are drained to avoid a stuck loop;
+ *  managed tables freshly emptied in this run without a projection are also
+ *  reported through `unresolvedManaged`. */
 export declare function runPendingRebuilds(db: DbConnection, registry: Registry, options?: RunPendingRebuildsOptions): Promise<PendingRebuildRun>;
 export declare const PROJECTION_REBUILD_JOB = "jobs:job:projection-rebuild";
 export type EnqueueProjectionRebuildResult = {

package/dist/migrations/pending-rebuilds.js

@@ -1,15 +1,15 @@
-// Persistente Pending-Rebuild-Queue für den `kumiko schema apply`-Pfad.
+// Persistent pending-rebuild queue for the `kumiko schema apply` path.
 //
-// Problem (studio#36/#46): Apps lasen die rebuild-Marker nur für
-// `result.applied` der AKTUELLEN apply-Runde. Schlug der Projection-Rebuild
-// fehl (oder crashte der Prozess dazwischen), war der Marker-Bezug beim
-// nächsten apply weg — `applied` ist dann leer — und die Projektion blieb
-// stillschweigend unfertig, ohne Self-Service-Retry-Pfad.
+// Problem: Apps read rebuild markers only from `result.applied` for the
+// CURRENT apply round. If the projection rebuild failed (or the process
+// crashed in between), the marker reference was gone on the next apply —
+// `applied` was empty — leaving the projection silently incomplete without a
+// self-service retry path.
 //
-// Lösung: die betroffenen Tabellen werden VOR dem Rebuild in
-// `kumiko_pending_rebuilds` persistiert und erst nach erfolgreichem Rebuild
-// der zugehörigen Projektion gelöscht. Ein erneuter apply (auch ohne neue
-// Migrations) holt offene Rebuilds über `runPendingRebuilds` nach.
+// Solution: persist the affected tables in `kumiko_pending_rebuilds` BEFORE
+// the rebuild and delete them only after the associated projection rebuild
+// succeeds. A subsequent apply, even without new migrations, processes open
+// rebuilds through `runPendingRebuilds`.
 import { instant, table as pgTable, sql, text } from "../db/dialect.js";
 import { deleteMany, selectMany, upsertOnConflict } from "../db/query.js";
 import { readRebuildMarker } from "../db/rebuild-marker.js";
@@ -24,15 +24,15 @@ export const pendingRebuildsTable = pgTable("kumiko_pending_rebuilds", {
     queuedAt: instant("queued_at", { precision: 3 }).notNull().default(sql `now()`),
 });
 export async function createPendingRebuildsTable(db) {
-    // skip: table already exists — bootstrap läuft aus mehreren Pfaden
+    // skip: table already exists — bootstrap runs from multiple paths
     if (await tableExists(db, "public.kumiko_pending_rebuilds"))
         return;
     await unsafePushTables(db, { kumikoPendingRebuilds: pendingRebuildsTable });
 }
-/** Liest die rebuild-Marker der frisch applizierten Migrations und queued
- *  die betroffenen Tabellen. Upsert: ein bereits pending-er Tisch behält
- *  seinen Queue-Slot (queued_at bleibt, damit die Reihenfolge stabil ist) —
- *  migration_id zeigt auf die zuletzt flaggende Migration (Debug-Bezug). */
+/** Reads rebuild markers from freshly applied migrations and queues the
+ *  affected tables. Upsert: an already-pending table keeps its queue slot
+ *  (`queued_at` remains unchanged, preserving order), while `migration_id`
+ *  points to the latest migration that flagged it for debugging. */
 export async function queueRebuildsFromMarkers(db, options) {
     await createPendingRebuildsTable(db);
     const queued = new Set();
@@ -58,7 +58,7 @@ export async function listPendingRebuilds(db) {
 // table_name alone: a concurrent queueRebuildsFromMarkers can re-queue the same
 // table for a NEWER migration (upsert bumps migration_id, keeps the slot)
 // between the read and the clear. Scoping the delete to the snapshot's
-// migration_id leaves that fresh re-queue intact instead of dropping it. (#328)
+// migration_id leaves that fresh re-queue intact instead of dropping it.
 export async function clearPendingRebuilds(db, rows) {
     for (const { tableName, migrationId } of rows) {
         await deleteMany(db, pendingRebuildsTable, { tableName, migrationId });
@@ -106,12 +106,12 @@ export function reportPendingRebuildRun(run, log) {
             .join("; ")}. Table(s) stay queued in kumiko_pending_rebuilds — retried on the next apply.`);
     }
 }
-/** Arbeitet die persistierte Queue ab: mappt Tabellen auf Projektionen,
- *  rebuildet jede betroffene Projektion und räumt ihre Tabellen erst nach
- *  ERFOLG aus der Queue. Fehlgeschlagene bleiben pending — der nächste
- *  apply (oder ein direkter Re-Call) holt sie nach. Unmapped-Tabellen werden
- *  geräumt (kein Stuck-Loop); die in diesem Run frisch geleerten managed-
- *  Tabellen ohne Projektion zusätzlich laut gemeldet (`unresolvedManaged`). */
+/** Processes the persistent queue: maps tables to projections, rebuilds each
+ *  affected projection, and removes its tables from the queue only after
+ *  SUCCESS. Failed tables remain pending and are retried by the next apply
+ *  (or a direct re-call). Unmapped tables are drained to avoid a stuck loop;
+ *  managed tables freshly emptied in this run without a projection are also
+ *  reported through `unresolvedManaged`. */
 export async function runPendingRebuilds(db, registry, options = {}) {
     const pendingRows = await listPendingRebuildRows(db);
     if (pendingRows.length === 0) {
@@ -119,7 +119,7 @@ export async function runPendingRebuilds(db, registry, options = {}) {
     }
     // (table → migration) snapshot read together with the table list; the clear
     // below scopes its DELETE to this migration_id so a concurrent re-queue for a
-    // newer migration survives instead of being dropped (#328).
+    // newer migration survives instead of being dropped.
     const migrationByTable = new Map(pendingRows.map((r) => [r.tableName, r.migrationId]));
     const snapshotRows = (tables) => tables.flatMap((tableName) => {
         const migrationId = migrationByTable.get(tableName);
@@ -136,7 +136,7 @@ export async function runPendingRebuilds(db, registry, options = {}) {
         if (projection === undefined) {
             // Markers only carry managed tables (rebuild-marker.ts). A table emptied
             // in THIS run with no resolving projection is a real defect (owning
-            // feature missing from the composition) → loud (#361) — unless the table
+            // feature missing from the composition) → loud — unless the table
             // no longer exists: then a later migration in the same run deliberately
             // DROPped it after migrating its data elsewhere, no data loss. Pre-
             // existing pending tables stay indistinguishable from old unmanaged
@@ -151,9 +151,9 @@ export async function runPendingRebuilds(db, registry, options = {}) {
         }
         byProjection.set(projection, [...(byProjection.get(projection) ?? []), tableName]);
     }
-    // Beide Klassen räumen: die Queue darf nicht ewig wachsen, und ein Re-Apply
-    // darf nicht sticky-stuck werfen. Die Lautstärke liegt im Log + Return-Feld,
-    // nicht im Liegenlassen.
+    // Both classes are drained: the queue must not grow indefinitely, and a
+    // re-apply must not remain stuck. The distinction is conveyed through the
+    // log and return field rather than by leaving entries queued.
     const drained = [...unmapped, ...unresolvedManaged];
     if (drained.length > 0) {
         await clearPendingRebuilds(db, snapshotRows(drained));

package/dist/migrations/projection-table-index.d.ts

@@ -1,5 +1,5 @@
 import type { Registry } from "../engine/types/feature.ts";
-/** Index `tableName → projection-name` aus der Registry. Nur Projections mit
- *  table-Definition (single-stream + multi-stream-with-table) zählen.
- *  Side-effect-only MSPs (table omitted) haben keinen Rebuild-Sinn. */
+/** Index `tableName → projection-name` from the registry. Only projections with
+ *  a table definition (single-stream + multi-stream-with-table) are included.
+ *  Side-effect-only MSPs (table omitted) cannot be rebuilt. */
 export declare function buildProjectionTableIndex(registry: Registry): ReadonlyMap<string, string>;

package/dist/migrations/projection-table-index.js

@@ -1,13 +1,13 @@
-// Index `tableName → projection-name` aus der Registry. Genutzt vom
-// app-seitigen Projection-Rebuild (`kumiko schema apply` liest die
-// rebuild-Marker → mappt Tabellen auf Projektionen → rebuildProjection).
+// Index `tableName → projection-name` from the registry, used by the
+// app-side projection rebuild (`kumiko schema apply` reads rebuild markers,
+// maps tables to projections, then calls rebuildProjection).
 //
-// Drizzle-frei: der Tabellen-Name kommt aus dem kumiko-Symbol das
-// buildEntityTable/deriveEntityTableMeta an die Table-Definition hängt.
+// Drizzle-free: the table name comes from the kumiko symbol attached to the
+// table definition by buildEntityTable/deriveEntityTableMeta.
 import { extractTableName } from "../db/index.js";
-/** Index `tableName → projection-name` aus der Registry. Nur Projections mit
- *  table-Definition (single-stream + multi-stream-with-table) zählen.
- *  Side-effect-only MSPs (table omitted) haben keinen Rebuild-Sinn. */
+/** Index `tableName → projection-name` from the registry. Only projections with
+ *  a table definition (single-stream + multi-stream-with-table) are included.
+ *  Side-effect-only MSPs (table omitted) cannot be rebuilt. */
 export function buildProjectionTableIndex(registry) {
     const index = new Map();
     for (const [name, def] of registry.getAllProjections()) {

package/dist/observability/metric-validator.js

@@ -52,7 +52,7 @@ export function validateMetricName(name, type) {
 // time) — normalize "-" to "_" here so a feature like "ai-foundation"
 // resolves to the same "kumiko_ai_foundation_x" on both the registration
 // path (registry-ingest.ts) and the read path (ctx.metrics / ctx.metricsFor),
-// instead of the kebab form being rejected outright (framework#1844).
+// instead of the kebab form being rejected outright.
 export function buildMetricName(featureName, shortName) {
     const normalizedFeatureName = toKebab(featureName).replace(/-/g, "_");
     if (!SNAKE_CASE.test(normalizedFeatureName)) {

package/dist/observability/metrics-handle.js

@@ -25,12 +25,12 @@ export function createMetricsHandle(meter, featureName) {
 }
 // Same feature-bound resolution as createMetricsHandle, but for an
 // explicit `featureName` chosen by the caller rather than the dispatching
-// handler's own feature (framework#1844). Meant for shared/library code
+// handler's own feature. Meant for shared/library code
 // invoked from many features' HandlerContext (ctx.metricsFor) — the
 // library owns one stable metric name instead of splintering into
 // kumiko_<caller>_x per consumer.
 //
-// Decision (framework#1844 DoD): unlike createMetricsHandle, an
+// Decision: unlike createMetricsHandle, an
 // unregistered name here is a silent no-op, not a throw. This handle is
 // meant for error/catch-path counters in shared code — a missing
 // registration (consuming feature not mounted, metric not declared yet)
@@ -101,7 +101,7 @@ export function createNoopMetricsHandle() {
     };
 }
 // Shared factory behind ctx.metricsFor for handler and job contexts, so both
-// keep the same no-op-on-unregistered contract (framework#1844).
+// keep the same no-op-on-unregistered contract.
 export function createMetricsForFactory(meter) {
     return meter
         ? (featureName) => createSafeMetricsHandle(meter, featureName)

package/dist/pipeline/append-event-core.js

@@ -1,3 +1,4 @@
+import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
 import { requestContext } from "../api/request-context.js";
 import { SYSTEM_EVENT_PREFIX } from "../crypto/system-event-pii.js";
 import { qnScope, toKebab } from "../engine/qualified-name.js";
@@ -6,6 +7,14 @@ import { isStreamArchived } from "../event-store/archive.js";
 import { ArchivedStreamError } from "../event-store/errors.js";
 import { append, getStreamVersion } from "../event-store/event-store.js";
 import { runProjectionsForEvent } from "./projections-runner.js";
+function requirePayloadObject(payload, eventType) {
+    if (!isPlainObject(payload)) {
+        throw new InternalError({
+            message: `appendEvent("${eventType}"): payload must be an object, got ${Array.isArray(payload) ? "array" : typeof payload}`,
+        });
+    }
+    return payload;
+}
 export async function appendDomainEventCore(deps, args) {
     const isSystemEvent = args.type.startsWith(SYSTEM_EVENT_PREFIX);
     const eventDef = deps.registry.getEvent(args.type);
@@ -42,10 +51,10 @@ export async function appendDomainEventCore(deps, args) {
         const parsed = eventDef.schema.safeParse(args.payload ?? {});
         if (!parsed.success)
             throw validationErrorFromZod(parsed.error);
-        validatedPayload = parsed.data;
+        validatedPayload = requirePayloadObject(parsed.data, args.type);
     }
     else {
-        validatedPayload = (args.payload ?? {});
+        validatedPayload = requirePayloadObject(args.payload ?? {}, args.type);
     }
     // Archive guard: block writes on archived streams. Without this an append
     // would produce an "invisible" row that loadAggregate filters out by default

package/dist/pipeline/cascade-handler.d.ts

@@ -1,6 +1,6 @@
 import type { TableColumns } from "../db/dialect.ts";
 import type { PreDeleteHookFn, Registry } from "../engine/types/index.ts";
 import type { SystemHookDef } from "./lifecycle-pipeline.ts";
-type TableMap = ReadonlyMap<string, TableColumns<any>>;
+type TableMap = ReadonlyMap<string, TableColumns>;
 export declare function createCascadeDeleteHook(registry: Registry, tables: TableMap): SystemHookDef<PreDeleteHookFn>;
 export {};

package/dist/pipeline/dispatch-batch.js

@@ -3,7 +3,7 @@ import { transaction } from "../db/query.js";
 import { InternalError, toWriteErrorInfo, UnprocessableError, writeFailure, } from "../errors/index.js";
 import { createFallbackLogger } from "../logging/utils.js";
 import { parseJsonSafe } from "../utils/safe-json.js";
-import { resolveDbSource } from "./dispatch-shared.js";
+import { resolveAppPoolDb } from "./dispatch-shared.js";
 import { executeNestedWrite, executeWrite } from "./dispatch-write.js";
 import { BatchRollback, isLifecycleResult, wrapToKumiko, } from "./dispatcher-utils.js";
 import { reserveBeforeTransaction, runAsCommand, } from "./pre-transaction-reservations.js";
@@ -209,7 +209,7 @@ async function runBatchBody(ctx, commands, user, requestId, inheritedOrigin) {
     }
     // batch() opens its own outer transaction — needs the top-level
     // connection's `.begin()` (TransactionSql exposes only `.savepoint()`).
-    const db = resolveDbSource(ctx, undefined);
+    const db = resolveAppPoolDb(ctx);
     if (!db || runsWithoutTransaction) {
         // Without a DB connection (or for a perCommand handler, whose writes open their own transactions)
         // there is no transaction to open. Fall back to

package/dist/pipeline/dispatch-query.js

@@ -1,4 +1,4 @@
-import { propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
+import { isPlainObject, propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
 import { hasAccess } from "../engine/access.js";
 import { tenantOverrideDenied } from "../engine/cross-tenant.js";
 import { filterReadFields } from "../engine/field-access.js";
@@ -60,16 +60,16 @@ async function runQueryHandler(ctx, type, handler, payload, includeDeleted, user
     const { registry } = ctx;
     const handlerContext = await buildHandlerContext(ctx, type, user, origin, tx, undefined, includeDeleted, undefined, outerNotifySink);
     let result = await handler.handler({ type, payload, user }, handlerContext);
-    // postQuery-Hooks: fire BEFORE field-access-filter so hooks see raw data
-    // and can merge custom-fields/computed-counts/tags/etc. Each hook is
-    // responsible for its own field-access on values it adds (the filter
-    // below only knows the entity's stammfields).
+    // postQuery hooks run BEFORE field-access filtering so they see raw data and can
+    // merge custom fields, computed counts, tags, and similar values. Each hook is
+    // responsible for applying field access to values it adds; the filter below
+    // only knows the entity's standard fields.
     //
-    // Two firing-pfade kombiniert in dieser Reihenfolge:
+    // Two hook scopes run in this order:
     //   1. Handler-keyed hooks via r.hook({ type: "postQuery", target: "ns:query:list", handler })
-    //      — feuern nur für genau diesen handler
+    //      — run only for that handler
     //   2. Entity-keyed hooks via r.entityHook("postQuery", "property", fn)
-    //      — feuern für ALLE query-handlers des entity
+    //      — run for all query handlers of the entity
     const entityName = registry.getHandlerEntity(type);
     // Handler-keyed postQuery hooks fire for any query (incl. entity-less
     // standalone queries like "ns:dashboard"). Entity-keyed hooks only apply
@@ -87,7 +87,7 @@ async function runQueryHandler(ctx, type, handler, payload, includeDeleted, user
             }
             result = rows;
         }
-        else if (Array.isArray(result.rows)) {
+        else if (isPlainObject(result) && Array.isArray(result["rows"])) {
             // @cast-boundary engine-payload
             const r = result;
             let rows = r.rows;
@@ -121,7 +121,7 @@ async function runQueryHandler(ctx, type, handler, payload, includeDeleted, user
         }
         else {
             const resultAsDbRow = result; // @cast-boundary engine-payload
-            if (Array.isArray(resultAsDbRow.rows)) {
+            if (Array.isArray(resultAsDbRow["rows"])) {
                 // generic handler-result shape narrow
                 const r = result; // @cast-boundary engine-payload
                 result = {

package/dist/pipeline/dispatch-shared.d.ts

@@ -52,6 +52,7 @@ export type DispatchContext = {
 };
 export declare const DEFAULT_MEMBER_READ_TIMEOUT_MS = 10000;
 export declare function resolveDbSource(ctx: DispatchContext, tx: DbTx | undefined): DbConnection | DbTx | undefined;
+export declare function resolveAppPoolDb(ctx: DispatchContext): DbConnection | undefined;
 export declare function isMemberResolutionPrincipal(user: SessionUser): boolean;
 export declare function applyMemberResolutionReadOnly(handlerContext: HandlerContext): HandlerContext;
 export declare function perCommandNestedDenied(targetType: string): InternalError;

package/dist/pipeline/dispatch-shared.js

@@ -42,13 +42,13 @@ export { TENANT_TIMEZONE_CONFIG_KEY };
 export const CONFIG_WRITE_SET_TYPE = "config:write:set";
 export const CONFIG_WRITE_RESET_TYPE = "config:write:reset";
 export const DEFAULT_MEMBER_READ_TIMEOUT_MS = 10_000;
-// Narrowing-helper: AppContext.db ist DbConnection|TenantDb|undefined. Die
-// dispatch-Pfade brauchen DbConnection (oder DbTx aus Caller-Scope) für
-// appendEvent/projection-writes; TenantDb-Branch wird hier ausgeschlossen.
+// Narrowing helper: AppContext.db is DbConnection|TenantDb|undefined. The
+// dispatch paths need DbConnection (or DbTx from the caller scope) for
+// appendEvent/projection writes; the TenantDb branch is excluded here.
 export function resolveDbSource(ctx, tx) {
     return tx ?? resolveAppPoolDb(ctx);
 }
-function resolveAppPoolDb(ctx) {
+export function resolveAppPoolDb(ctx) {
     return ctx.appContext.db; // @cast-boundary db-operator
 }
 // ctx.appendEvent — append a domain event onto a specific aggregate stream
@@ -492,8 +492,8 @@ readOnlyForTenant = false) {
     const meter = context.meter;
     const metrics = meter && featureName ? createMetricsHandle(meter, featureName) : createNoopMetricsHandle();
     // ctx.metricsFor(featureName) — shared/library code binds to a feature
-    // name of its own choosing instead of the dispatching handler's
-    // (framework#1844). Unregistered names no-op rather than throw.
+    // name of its own choosing instead of the dispatching handler's.
+    // Unregistered names no-op rather than throw.
     const metricsFor = createMetricsForFactory(meter);
     // A failed inner write has already appended its event and projections when a later
     // step (e.g. an inTransaction hook) fails, and the outer handler may swallow the
@@ -819,7 +819,7 @@ readOnlyForTenant = false) {
     // (context.geoTzProvider) feeds ctx.tz.fromCoordinates / fromAddress.
     //
     // Resolving this via `config()` is a config-table SELECT on every single
-    // dispatch (fw#2462) — ctx.tenantTimezoneCache memoizes it per tenant.
+    // dispatch — ctx.tenantTimezoneCache memoizes it per tenant.
     // dispatch-write.ts invalidates on config:write:set/reset for this key.
     // Only populate from a tx-free read (tx === undefined): a write-path
     // lookup runs inside the caller's own open transaction, and caching a
@@ -859,8 +859,8 @@ readOnlyForTenant = false) {
     });
     // ctx.locale — request-layer signal (X-Locale header → Accept-Language,
     // resolved once at the HTTP boundary by request-id-middleware.ts) wins;
-    // then SessionUser.locale (set at login, see fw#2333 — stale until
-    // re-login, same tradeoff as ctx.tz.user); falls back to the app's
+    // then SessionUser.locale (set at login — stale until re-login, same
+    // tradeoff as ctx.tz.user); falls back to the app's
     // boot-configured defaultLocale, then DEFAULT_LOCALE. Mirrors ctx.tz's
     // Request → Session → Boot-Default chain above.
     const safeUserLocale = user.locale !== undefined && isValidLocaleTag(user.locale) ? user.locale : undefined;
@@ -889,8 +889,7 @@ readOnlyForTenant = false) {
         ...(derivatives && { derivatives }),
         // preSave hooks need `changes`/`previous`/`isNew`, which only exist once
         // a handler actually starts building its write — bound here so entity
-        // CRUD handlers (entity-handlers.ts) can forward it to the executor
-        // (kumiko-framework#1672).
+        // CRUD handlers (entity-handlers.ts) can forward it to the executor.
         ...(lifecycle && {
             runPreSave: (handlerName, changes, previous, isNew) => lifecycle.runPreSave(handlerName, changes, previous, isNew, context),
         }),
@@ -911,11 +910,10 @@ readOnlyForTenant = false) {
         // Lets write handlers call ctx.jobRunner.dispatch(...) directly, same
         // as a follow-up job would (test-stack.ts wires the matching runner).
         ...(jobRunner && { jobRunner }),
-        // ctx.user als Convenience-Alias auf event.user. Der typisch-
-        // intuitive Pfad „der Context kennt seinen User" — ohne den
-        // schreiben Handler `event.user.tenantId` und brechen sich die
-        // Finger an typo-resistenten ctx.user-Patterns. Identisch zum
-        // event.user-Wert; Identity-Switches nutzen weiterhin queryAs/writeAs.
+        // ctx.user as a convenience alias for event.user. The intuitive path—"the
+        // context knows its user"—lets handlers avoid writing `event.user.tenantId`
+        // and reduces errors in ctx.user access patterns. It is identical to
+        // event.user; identity switches still use queryAs/writeAs.
         user,
         _tenantId: user.tenantId,
         ...(hasLiveCommitSink && { scheduleAfterCommit }),
@@ -970,7 +968,7 @@ export async function runHandlerInstrumented(ctx, type, operation, user, inner)
             attributes: dispatcherSpanAttributes(type, operation, user, registry.getHandlerFeature(type)),
         }, async (span) => {
             try {
-                // #3043 — everything the handler writes, including entity-executor
+                // Everything the handler writes, including entity-executor
                 // writes below it, is attributed to this handler.
                 const result = await runWithOrigin({
                     handler: type,

package/dist/pipeline/dispatch-stream.js

@@ -53,7 +53,7 @@ async function* executeStreamInner(ctx, type, payload, user, origin, options) {
     // When access is revoked mid-pull, `iterator.next()` is still in flight.
     // Awaiting `iterator.return()` in that state deadlocks async generators in
     // Bun (overlapping next+return). Track abandonment so finally skips the
-    // await; close is fire-and-forget instead (#1563).
+    // await; close is fire-and-forget instead.
     let abandonedForInvalidation = false;
     try {
         const handlerContext = await buildHandlerContext(ctx, type, user, origin);

package/dist/pipeline/dispatch-write.js

@@ -54,7 +54,7 @@ function isConfigWriteResult(data) {
         return false;
     return typeof data.key === "string";
 }
-// fw#2462: dispatch-shared.ts caches the resolved tenant:config:timezone
+// dispatch-shared.ts caches the resolved tenant:config:timezone
 // value per tenant. A successful write to that key must drop the stale
 // entry — tenant/user scope only affects the writing tenant, system scope
 // changes the fallback every tenant without an override reads, so the
@@ -252,8 +252,8 @@ export async function executeNestedWrite(ctx, type, payload, user, origin, tx, a
     // enumerates columns generically WOULD see `tasks`; no such subscriber
     // exists today. If you add one that iterates `Object.keys(save.data)`,
     // filter by `entity.fields` membership to stay correct.
-    // handler-Result.data ist generic über alle Entity-Handler; nested-
-    // write inspiziert die shape strukturell.
+    // handler-Result.data is generic across all entity handlers; nested-
+    // write inspects the shape structurally.
     const parentWrapper = parentResult.data; // @cast-boundary engine-payload
     const parentRow = (parentWrapper["data"] ?? parentWrapper); // @cast-boundary engine-payload
     const parentId = parentRow["id"];

package/dist/pipeline/dispatcher-utils.d.ts

@@ -5,7 +5,7 @@ export type FailedWriteResult = Extract<WriteResult, {
 }>;
 export declare function isFailedWriteResult(result: unknown): result is FailedWriteResult;
 export declare function isLifecycleResult(data: unknown): data is LifecycleResult;
-export declare function isWriteResultShape(result: unknown): boolean;
+export declare function isWriteResultShape(result: unknown): result is WriteResult;
 export declare function describeShape(result: unknown): string;
 export declare function dispatcherSpanAttributes(type: string, operation: "query" | "write" | "stream", user: SessionUser, feature: string | undefined): Record<string, string | number | boolean>;
 export type AfterCommitHook = () => Promise<void>;

package/dist/pipeline/dispatcher-utils.js

@@ -56,7 +56,7 @@ export function extractNestedSpecs(parentType, payload, registry) {
     if (!entityName)
         return null;
     const relations = registry.getRelations(entityName);
-    const source = payload; // @cast-boundary engine-payload — generic dispatch über alle Entity-Types
+    const source = payload; // @cast-boundary engine-payload — generic dispatch across all entity types
     const clean = { ...source };
     const specs = [];
     const typeIssues = [];

package/dist/pipeline/event-consumer-state.js

@@ -4,7 +4,7 @@ import { tableExists } from "../db/schema-inspection.js";
 import { unsafePushTables } from "../db/table-push.js";
 // Reserved sentinel used in the instance_id column for consumers whose
 // delivery is "shared" — i.e. one cursor across all dispatcher instances
-// (the default, pre-Welle-2.7 behaviour). Per-instance consumers store
+// (the default behaviour). Per-instance consumers store
 // the concrete instanceId. Postgres PK columns can't be NULL and
 // `NULL = NULL` is UNKNOWN in SQL — a nullable instance_id would break
 // both uniqueness and PK constraints. The boot-validator refuses to
@@ -62,7 +62,7 @@ export async function createEventConsumerStateTable(db) {
         // no need to pre-check columnNamesOf first. Two instances booting
         // concurrently against the same DB (this table is explicitly
         // multi-instance) both ALTER, neither crashes on "column already
-        // exists" (#1362).
+        // exists".
         await alterTableAddColumn(db, "kumiko_event_consumers", "rearm_count", "integer", " DEFAULT 0", " NOT NULL", 
         /* ifNotExists */ true);
         await alterTableAddColumn(db, "kumiko_event_consumers", "pending_gaps", "jsonb", " DEFAULT '[]'::jsonb", " NOT NULL", 

package/dist/pipeline/event-dispatcher-delivery.js

@@ -239,7 +239,7 @@ export async function deliverEvents(consumer, events, context, maxAttempts, stat
 // turn (see applyBatch for why). requestId falls back to a fresh id
 // because the dispatcher runs outside any HTTP request (background poll),
 // and a stable log-correlation handle is still useful for debugging.
-// #3043 — an event this apply writes is attributed to the consumer, not
+// An event this apply writes is attributed to the consumer, not
 // to whatever wrote the triggering event; causationId already links back.
 function buildConsumerRequestScope(consumer, causationSource) {
     const correlationId = causationSource.metadata.correlationId ?? requestContext.generateId();