@cosmicdrift/kumiko-framework 0.385.0 → 0.387.0

package/dist/jobs/job-runner.js

@@ -1,8 +1,9 @@
 /// <reference types="temporal-polyfill/global" preserve="true" />
-import { escapeHatchFor } from "@cosmicdrift/kumiko-types/handlers";
+import { crossTenantReadsGrantFor, escapeHatchFor } from "@cosmicdrift/kumiko-types/handlers";
 import { DelayedError, Queue, UnrecoverableError, Worker } from "bullmq";
 import { Redis } from "ioredis";
 import { requestContext } from "../api/request-context.js";
+import { createCrossTenantReads } from "../db/cross-tenant-reads.js";
 import { createTenantDb, createUncheckedSystemDb } from "../db/tenant-db.js";
 import { createDerivativesContext } from "../derivatives/derivatives-context.js";
 import { bridgeStub } from "../engine/bridge-stub.js";
@@ -19,7 +20,7 @@ import { RedisKeys } from "../pipeline/redis-keys.js";
 import { createGatedIdentitySwitch } from "../pipeline/system-identity-switch.js";
 import { buildPersonalDataGate, parseWriteOrigin } from "../pipeline/write-origin.js";
 import { cronRepeatOptions } from "./cron-repeat-options.js";
-import { BOOT_GATE_SLOW_WARN_MS, BOOT_REDIS_TIMEOUT_MS, buildRetryBullOpts, COMPLETED_JOB_RETENTION_AGE_SEC, captureTraceContext, createCrossTenantReads, createJobLogger, DEFAULT_MAX_DEFERS, DEFER_BACKOFF_MAX_DOUBLINGS, DEFER_COUNT_KEY, DEFER_DELAY_CAP_MS, FAILED_JOB_RETENTION_AGE_SEC, HANDLER_DEFER_COUNT_KEY, isJobTriggerEvent, jobSubjectKey, maxRetryWindowMs, missingDbProxy, parseRedisOpts, payloadMatchesTriggerFilter, priorAttemptsOf, readTraceContext, resolveJobTz, STOP_QUEUE_READY_TIMEOUT_MS, stampGatedWriteOrigin, startQueueDepthPolling, TRACE_CONTEXT_KEY, tenantFailureMessageKey, timeoutReject, } from "./job-runner-helpers.js";
+import { BOOT_GATE_SLOW_WARN_MS, BOOT_REDIS_TIMEOUT_MS, buildRetryBullOpts, COMPLETED_JOB_RETENTION_AGE_SEC, captureTraceContext, createJobLogger, DEFAULT_MAX_DEFERS, DEFER_BACKOFF_MAX_DOUBLINGS, DEFER_COUNT_KEY, DEFER_DELAY_CAP_MS, FAILED_JOB_RETENTION_AGE_SEC, HANDLER_DEFER_COUNT_KEY, isJobTriggerEvent, jobSubjectKey, maxRetryWindowMs, missingDbProxy, parseRedisOpts, payloadMatchesTriggerFilter, priorAttemptsOf, readTraceContext, resolveJobTz, STOP_QUEUE_READY_TIMEOUT_MS, stampGatedWriteOrigin, startQueueDepthPolling, TRACE_CONTEXT_KEY, tenantFailureMessageKey, timeoutReject, } from "./job-runner-helpers.js";
 import { ACTIVE_TENANT_IDS_QUERY_NAME, bootJobIdForJobName, DEFAULT_QUEUE_NAME_PREFIX, markSchedulersSeen, ORPHAN_SCHEDULER_GRACE_MS, perTenantChildJobId, queueNameFor, removeOrphanJobSchedulers, schedulerIdForJobName, } from "./job-runner-schedulers.js";
 import { resolveMaxPerTenant } from "./max-per-tenant.js";
 export { serializeJobSubject } from "./job-runner-helpers.js";
@@ -138,8 +139,7 @@ export function createJobRunner(options) {
         lockRedis = new Redis(redisOpts);
         // Without a listener, a post-close 'error' (e.g. a teardown-race
         // "Connection is closed") is unhandled and crashes the process — in
-        // bun:test it gets attributed to whichever test happens to run next
-        // (fw#1805).
+        // bun:test it gets attributed to whichever test happens to run next.
         lockRedis.on("error", (err) => {
             const log = stopping ? errorLogger.debug : errorLogger.error;
             log("lock redis connection error", { error: err.message });
@@ -180,7 +180,7 @@ export function createJobRunner(options) {
         }),
     };
     // Same unhandled-'error'-crash hazard as lockRedis above, just via
-    // BullMQ's internal ioredis client (fw#1805).
+    // BullMQ's internal ioredis client.
     for (const queue of Object.values(queues)) {
         queue.on("error", (err) => {
             const log = stopping ? errorLogger.debug : errorLogger.error;
@@ -556,7 +556,7 @@ export function createJobRunner(options) {
         // Same buildHandlerContext parity as ctx.files above: ctx.notify/ctx.config
         // must resolve for jobs the same way they do for write-handlers, or an
         // app-author job calling ctx.notify(...)/ctx.config(...) hits a TypeError
-        // at runtime the write-handler path never would (framework#1532).
+        // at runtime the write-handler path never would.
         const notify = context._notifyFactory?.(jobSystemUser, tenantId, selfRunner, undefined, context._fileProviderResolver);
         const configDb = context.db; // @cast-boundary db-operator
         // Shared by the config accessor and ctx.derivatives below — both need the
@@ -611,7 +611,7 @@ export function createJobRunner(options) {
                 },
             })
             : undefined;
-        const crossTenantReadsReason = escapeHatchFor(jobDef.escapeHatch, "unsafeRaw")?.reason;
+        const crossTenantReadsReason = crossTenantReadsGrantFor(jobDef.escapeHatch)?.reason;
         const crossTenantReads = tenantScopedDb && crossTenantReadsReason !== undefined
             ? createCrossTenantReads(tenantScopedDb, crossTenantReadsReason, reportEscapeHatch)
             : undefined;
@@ -738,7 +738,7 @@ export function createJobRunner(options) {
                 const handlerResult = await requestContext.run({
                     requestId: jobRequestId,
                     correlationId: jobCorrelationId,
-                    // #3043 — events a job writes carry the job as their origin.
+                    // Events a job writes carry the job as their origin.
                     handler: jobName,
                     feature: registry.getJobFeature(jobName) ?? qnScope(jobName),
                     writeOrigin: jobOrigin,
@@ -793,7 +793,7 @@ export function createJobRunner(options) {
                     "job.id": jobId,
                     "job.attempt": attempt,
                     "kumiko.tenant_id": tenantId,
-                    // Lane-routing attributes (Welle 2.6). `run_in` is the job's
+                    // Lane-routing attributes. `run_in` is the job's
                     // declared lane (explicit or default-"worker"); `consumer_lane`
                     // is which runner actually executed it. They diverge in
                     // all-in-one (both lanes live in one process) but must match
@@ -839,7 +839,7 @@ export function createJobRunner(options) {
     // Boot gates run inline and are awaited, so a throwing gate rejects start()
     // — and with it the entrypoint's start() and runProdApp's boot, before the
     // process reports ready. Enqueuing them (as runOnBoot does) would only fail
-    // a queue job and let the deploy through (fw#2590).
+    // a queue job and let the deploy through.
     async function runBootGates(lane) {
         for (const [name, jobDef] of allJobs) {
             if (laneForJob(jobDef) !== lane)
@@ -977,7 +977,7 @@ export function createJobRunner(options) {
             // still-settling blocking connection: it rejects in-flight commands
             // via ioredis's flushQueue() during close(), which isn't a listenable
             // 'error' event — the only fix is to not return until both of the
-            // worker's connections (main + blocking) are ready (fw#1805). This
+            // worker's connections (main + blocking) are ready. This
             // mirrors the wait BullMQ already does internally for
             // upsertJobScheduler()/add() below when the lane has a cron/boot job.
             // Racing a timeout against it keeps an unreachable Redis from hanging
@@ -1069,7 +1069,7 @@ export function createJobRunner(options) {
             }
             // BullMQ close() while a Queue's connection is still 'initializing'
             // rejects the in-flight INFO with "Connection is closed." on an emitter
-            // without listeners -> unhandled rejection (fw#1805). Wait for readiness
+            // without listeners -> unhandled rejection. Wait for readiness
             // first; a failed/timed-out wait must not block the close itself.
             const stopReadyTimeoutMs = Math.min(bootRedisTimeoutMs, STOP_QUEUE_READY_TIMEOUT_MS);
             await settleAbandonedBootGates(stopReadyTimeoutMs);
@@ -1202,8 +1202,8 @@ export function createJobRunner(options) {
             for (const [name, jobDef] of allJobs) {
                 if (!("on" in jobDef.trigger))
                     continue;
-                // skip: andere Trigger-Formen (cron, manual) reagieren nicht auf
-                // Events. Nur "on"-Trigger werden hier matched.
+                // skip: other trigger types (cron, manual) do not respond to events.
+                // Only "on" triggers are matched here.
                 const triggerOn = jobDef.trigger.on;
                 const matches = Array.isArray(triggerOn)
                     ? triggerOn.includes(eventName)
@@ -1217,10 +1217,9 @@ export function createJobRunner(options) {
                     data["_tenantId"] = user.tenantId;
                     data["_triggeredById"] = user.id;
                 }
-                // Multi-Trigger: payload bekommt _triggerName damit der Handler
-                // weiß, welcher der N Trigger gefeuert hat. Bei Single-Trigger
-                // setzen wir es auch — kostet nichts und vereinfacht Handler-Code
-                // (kein "ist es Multi?"-Branch nötig).
+                // Multi-trigger: add _triggerName to the payload so the handler knows which
+                // of the N triggers fired. Set it for single triggers too; this costs
+                // nothing and keeps handler code simple (no "is it multi?" branch).
                 data["_triggerName"] = eventName;
                 if (triggerEvent)
                     data["_triggerEvent"] = triggerEvent;

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/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)