@cosmicdrift/kumiko-framework 0.386.0 → 0.388.0

package/dist/lifecycle/lifecycle.js

@@ -1,5 +1,6 @@
 // Process lifecycle: 4-state machine + LIFO shutdown hooks.
 // Signal wiring lives in signal-handlers.ts; v1 scope in architecture/lifecycle.md.
+import { createFallbackLogger } from "../logging/utils.js";
 const DEFAULT_DRAIN_TIMEOUT_MS = 40_000;
 export function createLifecycle(opts = {}) {
     const now = opts.now ?? (() => Date.now());
@@ -103,9 +104,6 @@ export function createLifecycle(opts = {}) {
     };
 }
 function makeErrorLogger(logger) {
-    if (logger) {
-        return (msg, err) => logger.error(`[lifecycle] ${msg}`, { err });
-    }
-    // biome-ignore lint/suspicious/noConsole: ops-visible fallback when no logger is wired
-    return (msg, err) => console.error(`[lifecycle] ${msg}:`, err);
+    const log = createFallbackLogger("lifecycle", logger);
+    return (msg, err) => log.error(msg, { err });
 }

package/dist/lifecycle/signal-handlers.js

@@ -4,6 +4,9 @@
 export function attachSignalHandlers(lifecycle, opts = {}) {
     const signals = opts.signals ?? ["SIGTERM", "SIGINT"];
     const exitFn = opts.exit ?? ((code) => process.exit(code));
+    // bun-types vs @types/node: signal overload on process.on/off is not
+    // selectable via bind() under the merged types — EventEmitter seam is intentional.
+    const processEmitter = process;
     const listeners = new Map();
     // Guard so double-SIGTERM doesn't call exitFn twice. drain() is already
     // idempotent via its shared promise, but its .then/.catch chain would fire
@@ -24,15 +27,13 @@ export function attachSignalHandlers(lifecycle, opts = {}) {
                 .then(() => exitFn(0))
                 .catch(() => exitFn(1));
         };
-        // bun-types vs @types/node: signal overload on process.on/off is not
-        // selectable via bind() under the merged types — EventEmitter seam is intentional.
-        process.on(sig, handler);
+        processEmitter.on(sig, handler);
         listeners.set(sig, handler);
     }
     return {
         detach: () => {
             for (const [sig, handler] of listeners) {
-                process.off(sig, handler);
+                processEmitter.off(sig, handler);
             }
             listeners.clear();
         },

package/dist/logging/utils.d.ts

@@ -1,9 +1,10 @@
 import type { Logger } from "./types.ts";
 type FallbackLogger = {
+    info(msg: string, data?: Record<string, unknown>): void;
     error(msg: string, data?: Record<string, unknown>): void;
     warn(msg: string, data?: Record<string, unknown>): void;
     debug(msg: string, data?: Record<string, unknown>): void;
 };
 export declare function setProcessLogger(logger: Logger | null): void;
-export declare function createFallbackLogger(namespace: string, logger?: (Pick<Logger, "error"> & Partial<Pick<Logger, "warn" | "debug">>) | undefined): FallbackLogger;
+export declare function createFallbackLogger(namespace: string, logger?: (Pick<Logger, "error"> & Partial<Pick<Logger, "info" | "warn" | "debug" | "child">>) | undefined): FallbackLogger;
 export {};

package/dist/logging/utils.js

@@ -3,9 +3,33 @@ let processLogger = null;
 export function setProcessLogger(logger) {
     processLogger = logger;
 }
+// Bun prints a trailing "undefined" when a second argument is passed explicitly as undefined.
+function writeConsole(write, line, data) {
+    if (data === undefined)
+        write(line);
+    else
+        write(line, data);
+}
 export function createFallbackLogger(namespace, logger) {
+    if (logger?.child) {
+        const child = logger.child({ component: namespace });
+        return {
+            info: (msg, data) => child.info(msg, data),
+            error: (msg, data) => child.error(msg, data),
+            warn: (msg, data) => child.warn(msg, data),
+            debug: (msg, data) => child.debug(msg, data),
+        };
+    }
     if (logger) {
         return {
+            info(msg, data) {
+                if (logger.info) {
+                    logger.info(`[${namespace}] ${msg}`, data);
+                }
+                else {
+                    writeConsole(console.info, `[${namespace}] ${msg}`, data);
+                }
+            },
             error(msg, data) {
                 logger.error(`[${namespace}] ${msg}`, data);
             },
@@ -14,8 +38,7 @@ export function createFallbackLogger(namespace, logger) {
                     logger.warn(`[${namespace}] ${msg}`, data);
                 }
                 else {
-                    // biome-ignore lint/suspicious/noConsole: ops-visible fallback when the wrapped logger has no warn method
-                    console.warn(`[${namespace}] ${msg}`, data);
+                    writeConsole(console.warn, `[${namespace}] ${msg}`, data);
                 }
             },
             debug(msg, data) {
@@ -23,8 +46,7 @@ export function createFallbackLogger(namespace, logger) {
                     logger.debug(`[${namespace}] ${msg}`, data);
                 }
                 else {
-                    // biome-ignore lint/suspicious/noConsole: ops-visible fallback when the wrapped logger has no debug method
-                    console.debug(`[${namespace}] ${msg}`, data);
+                    writeConsole(console.debug, `[${namespace}] ${msg}`, data);
                 }
             },
         };
@@ -41,14 +63,22 @@ export function createFallbackLogger(namespace, logger) {
         return cachedChild;
     };
     return {
+        info(msg, data) {
+            const child = resolveProcessChild();
+            if (child) {
+                child.info(msg, data);
+            }
+            else {
+                writeConsole(console.info, `[${namespace}] ${msg}`, data);
+            }
+        },
         error(msg, data) {
             const child = resolveProcessChild();
             if (child) {
                 child.error(msg, data);
             }
             else {
-                // biome-ignore lint/suspicious/noConsole: ops-visible fallback when no logger is wired
-                console.error(`[${namespace}] ${msg}`, data);
+                writeConsole(console.error, `[${namespace}] ${msg}`, data);
             }
         },
         warn(msg, data) {
@@ -57,8 +87,7 @@ export function createFallbackLogger(namespace, logger) {
                 child.warn(msg, data);
             }
             else {
-                // biome-ignore lint/suspicious/noConsole: ops-visible fallback when no logger is wired
-                console.warn(`[${namespace}] ${msg}`, data);
+                writeConsole(console.warn, `[${namespace}] ${msg}`, data);
             }
         },
         debug(msg, data) {
@@ -67,8 +96,7 @@ export function createFallbackLogger(namespace, logger) {
                 child.debug(msg, data);
             }
             else {
-                // biome-ignore lint/suspicious/noConsole: ops-visible fallback when no logger is wired
-                console.debug(`[${namespace}] ${msg}`, data);
+                writeConsole(console.debug, `[${namespace}] ${msg}`, data);
             }
         },
     };

package/dist/migrations/index.js

@@ -4,5 +4,5 @@ export { assertKumikoSchemaCurrent, detectKumikoDrift, formatKumikoDriftReport,
 export { createPendingRebuildsTable, enqueueProjectionRebuild, listPendingRebuilds, PROJECTION_REBUILD_JOB, pendingRebuildsTable, queueRebuildsFromMarkers, rebuildProjectionOrMultiStream, reportPendingRebuildRun, runPendingRebuilds, } from "./pending-rebuilds.js";
 // Boot-time backfill: re-encrypts plaintext events after a PII annotation was added.
 export { createPiiBackfillStateTable, piiAnnotationFingerprint, piiBackfillStateTable, runPiiEventBackfill, } from "./pii-event-backfill.js";
-// tableName → projection-name, für den app-seitigen Projection-Rebuild.
+// tableName → projection-name, for application-side projection rebuilds.
 export { buildProjectionTableIndex } from "./projection-table-index.js";

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/escape-hatch-report.d.ts

@@ -12,6 +12,9 @@ export declare function createEscapeHatchReportWindow(opts?: {
 export type EscapeHatchProcessDedup = {
     readonly kinds: ReadonlySet<EscapeHatchKind>;
     readonly lastAuditedAt: Map<string, number>;
+    readonly lastSweep: {
+        atMs: number;
+    };
 };
 export declare function createEscapeHatchProcessDedup(kinds: readonly EscapeHatchKind[]): EscapeHatchProcessDedup;
 export declare function withEscapeHatchAuditScope<T>(run: () => Promise<T>): Promise<T>;

package/dist/observability/escape-hatch-report.js

@@ -40,8 +40,18 @@ const READ_WINDOW_KINDS = new Set([
 // A long-lived worker must leave an audit event inside every retention window
 // (90 days), or its crons vanish from the log once the first event is pruned.
 const PROCESS_REAUDIT_INTERVAL_MS = 24 * 60 * 60 * 1000;
+// Row-level targets add a key per touched row; without a sweep a long-lived worker keeps them all.
+function sweepExpiredProcessDedup(dedup, nowMs) {
+    if (nowMs - dedup.lastSweep.atMs >= PROCESS_REAUDIT_INTERVAL_MS) {
+        dedup.lastSweep.atMs = nowMs;
+        for (const [key, auditedAt] of dedup.lastAuditedAt) {
+            if (nowMs - auditedAt >= PROCESS_REAUDIT_INTERVAL_MS)
+                dedup.lastAuditedAt.delete(key);
+        }
+    }
+}
 export function createEscapeHatchProcessDedup(kinds) {
-    return { kinds: new Set(kinds), lastAuditedAt: new Map() };
+    return { kinds: new Set(kinds), lastAuditedAt: new Map(), lastSweep: { atMs: 0 } };
 }
 // Default window for createEscapeHatchReporter callers that don't pass their own.
 const fallbackReportWindow = createEscapeHatchReportWindow();
@@ -160,6 +170,7 @@ export function createEscapeHatchReporter(opts) {
             if (lastAuditedAt !== undefined && nowMs - lastAuditedAt < PROCESS_REAUDIT_INTERVAL_MS) {
                 return;
             }
+            sweepExpiredProcessDedup(processDedup, nowMs);
             processDedup.lastAuditedAt.set(processKey, nowMs);
             reportEscapeHatchUse(eventFor(kind, reason, target), deps);
             // skip: audited above, the window dedup below only serves the other kinds

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 {};