@cosmicdrift/kumiko-framework 0.328.0 → 0.329.0

package/dist/lifecycle/index.d.ts

@@ -0,0 +1,2 @@
+export { createLifecycle, type Lifecycle, type LifecycleOptions, type LifecycleState, type ShutdownHookFn, type StateChangeListener, } from "./lifecycle.js";
+export { type AttachSignalHandlersOptions, attachSignalHandlers, type SignalHandlerHandle, } from "./signal-handlers.js";

package/dist/lifecycle/index.js

@@ -0,0 +1,2 @@
+export { createLifecycle, } from "./lifecycle.js";
+export { attachSignalHandlers, } from "./signal-handlers.js";

package/dist/lifecycle/lifecycle.d.ts

@@ -0,0 +1,23 @@
+import type { Logger } from "../logging/types.js";
+export type LifecycleState = "starting" | "ready" | "draining" | "stopped";
+export type StateChangeListener = (from: LifecycleState, to: LifecycleState) => void;
+export type ShutdownHookFn = (signal: string) => Promise<void>;
+export interface Lifecycle {
+    state(): LifecycleState;
+    uptimeSec(): number;
+    markReady(): void;
+    onStateChange(cb: StateChangeListener): () => void;
+    registerShutdownHook(name: string, fn: ShutdownHookFn): void;
+    hookNames(): readonly string[];
+    drain(opts?: {
+        signal?: string;
+        timeoutMs?: number;
+    }): Promise<void>;
+}
+export type LifecycleOptions = {
+    readonly startReady?: boolean;
+    /** @internal Test-only clock injection for deterministic uptimeSec assertions. */
+    readonly now?: () => number;
+    readonly logger?: Pick<Logger, "error">;
+};
+export declare function createLifecycle(opts?: LifecycleOptions): Lifecycle;

package/dist/lifecycle/lifecycle.js

@@ -0,0 +1,111 @@
+// Process lifecycle: 4-state machine + LIFO shutdown hooks.
+// Signal wiring lives in signal-handlers.ts; v1 scope in architecture/lifecycle.md.
+const DEFAULT_DRAIN_TIMEOUT_MS = 40_000;
+export function createLifecycle(opts = {}) {
+    const now = opts.now ?? (() => Date.now());
+    const startedAt = now();
+    const logError = makeErrorLogger(opts.logger);
+    let current = opts.startReady ? "ready" : "starting";
+    const listeners = new Set();
+    const hooks = [];
+    let drainPromise = null;
+    function transition(to) {
+        const from = current;
+        // skip: no real state change (e.g. markReady() on an already-ready
+        // lifecycle). Listeners only fire on actual transitions.
+        if (from === to)
+            return;
+        current = to;
+        for (const cb of listeners) {
+            try {
+                cb(from, to);
+            }
+            catch (err) {
+                // A broken listener must not tear the state machine down, but swallowing
+                // silently hides bugs from ops. Log and move on.
+                logError(`onStateChange listener threw during ${from}→${to}`, err);
+            }
+        }
+    }
+    async function drainOnce(signal, timeoutMs) {
+        transition("draining");
+        const runAllHooks = async () => {
+            // LIFO: the last thing registered is the first thing stopped. Matches
+            // the "things registered later depend on things registered earlier"
+            // convention — tear them down in reverse dependency order.
+            for (let i = hooks.length - 1; i >= 0; i--) {
+                const hook = hooks[i];
+                if (!hook)
+                    continue;
+                try {
+                    await hook.fn(signal);
+                }
+                catch (err) {
+                    // Isolated failure: one broken hook must not block the others. Log
+                    // so ops can see which hook failed during shutdown — silent swallow
+                    // made prod incidents invisible.
+                    logError(`shutdown hook "${hook.name}" threw`, err);
+                }
+            }
+        };
+        let forceTimer;
+        const forcePromise = new Promise((resolve) => {
+            forceTimer = setTimeout(resolve, timeoutMs);
+        });
+        try {
+            await Promise.race([runAllHooks(), forcePromise]);
+        }
+        finally {
+            if (forceTimer)
+                clearTimeout(forceTimer);
+            transition("stopped");
+        }
+    }
+    return {
+        state: () => current,
+        uptimeSec: () => Math.floor((now() - startedAt) / 1000),
+        markReady: () => {
+            // skip: already past the "starting" phase. markReady is idempotent
+            // so boot orchestrators can call it defensively without branching.
+            if (current !== "starting")
+                return;
+            transition("ready");
+        },
+        onStateChange: (cb) => {
+            listeners.add(cb);
+            return () => {
+                listeners.delete(cb);
+            };
+        },
+        registerShutdownHook: (name, fn) => {
+            // Accepting hooks after `draining` has started would silently drop them
+            // — better to reject so mis-wired late registrations surface.
+            if (current === "draining" || current === "stopped") {
+                throw new Error(`Cannot register shutdown hook "${name}" — lifecycle is already ${current}`);
+            }
+            hooks.push({ name, fn });
+        },
+        hookNames: () => hooks.map((h) => h.name),
+        drain: async (drainOpts = {}) => {
+            const signal = drainOpts.signal ?? "manual";
+            const timeoutMs = drainOpts.timeoutMs ?? DEFAULT_DRAIN_TIMEOUT_MS;
+            // Re-entrant drain: concurrent calls share the in-flight promise.
+            // Post-stop calls are a no-op so double-SIGTERM doesn't double-run hooks.
+            if (drainPromise)
+                return drainPromise;
+            // skip: already fully stopped (e.g. SIGTERM arrives after drain finished).
+            // Returning without action keeps the post-drain state pristine.
+            if (current === "stopped")
+                return;
+            drainPromise = drainOnce(signal, timeoutMs);
+            return drainPromise;
+        },
+    };
+}
+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);
+}

package/dist/lifecycle/signal-handlers.d.ts

@@ -0,0 +1,10 @@
+import type { Lifecycle } from "./lifecycle.js";
+export type AttachSignalHandlersOptions = {
+    readonly timeoutMs?: number;
+    readonly signals?: readonly NodeJS.Signals[];
+    readonly exit?: (code: number) => void;
+};
+export type SignalHandlerHandle = {
+    detach(): void;
+};
+export declare function attachSignalHandlers(lifecycle: Lifecycle, opts?: AttachSignalHandlersOptions): SignalHandlerHandle;

package/dist/lifecycle/signal-handlers.js

@@ -0,0 +1,40 @@
+// Opt-in signal handlers. Kept separate from createLifecycle() so test
+// processes don't accidentally hijack SIGTERM/SIGINT — production `main.ts`
+// calls this explicitly, tests drive drain() directly.
+export function attachSignalHandlers(lifecycle, opts = {}) {
+    const signals = opts.signals ?? ["SIGTERM", "SIGINT"];
+    const exitFn = opts.exit ?? ((code) => process.exit(code));
+    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
+    // per signal otherwise.
+    let exitScheduled = false;
+    for (const sig of signals) {
+        const handler = () => {
+            // skip: exit already scheduled by a prior signal — drain() is in flight
+            // and will fire exitFn itself when it settles. Second signal is a no-op.
+            if (exitScheduled)
+                return;
+            exitScheduled = true;
+            void lifecycle
+                .drain({
+                signal: sig,
+                ...(opts.timeoutMs !== undefined && { timeoutMs: opts.timeoutMs }),
+            })
+                .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);
+        listeners.set(sig, handler);
+    }
+    return {
+        detach: () => {
+            for (const [sig, handler] of listeners) {
+                process.off(sig, handler);
+            }
+            listeners.clear();
+        },
+    };
+}

package/dist/logging/index.d.ts

@@ -0,0 +1,4 @@
+export type { LoggerOptions } from "./pino-logger.js";
+export { createLogger } from "./pino-logger.js";
+export type { Logger } from "./types.js";
+export { createFallbackLogger } from "./utils.js";

package/dist/logging/index.js

@@ -0,0 +1,2 @@
+export { createLogger } from "./pino-logger.js";
+export { createFallbackLogger } from "./utils.js";

package/dist/logging/pino-logger.d.ts

@@ -0,0 +1,9 @@
+import { type DestinationStream } from "pino";
+import type { Logger } from "./types.js";
+export type LoggerOptions = {
+    level?: "debug" | "info" | "warn" | "error";
+    pretty?: boolean;
+    destination?: DestinationStream;
+};
+export declare function createLogger(options?: LoggerOptions): Logger;
+export declare function mergeTraceFields(data: Record<string, unknown> | undefined): Record<string, unknown> | undefined;

package/dist/logging/pino-logger.js

@@ -0,0 +1,61 @@
+import pino, {} from "pino";
+import { observabilityContext } from "../observability/index.js";
+export function createLogger(options = {}) {
+    const level = options.level ?? process.env["LOG_LEVEL"] ?? "info"; // @cast-boundary dynamic-key
+    const pretty = options.pretty ?? process.env["LOG_FORMAT"] === "pretty";
+    const pinoConfig = {
+        level,
+        ...(pretty && !options.destination
+            ? { transport: { target: "pino-pretty", options: { colorize: true } } }
+            : {}),
+    };
+    const pinoLogger = options.destination ? pino(pinoConfig, options.destination) : pino(pinoConfig);
+    return wrapPino(pinoLogger);
+}
+// Pull traceId/spanId from the active observability context so every log
+// line carries them when tracing is active. Empty IDs (NoopProvider) skip —
+// nothing to correlate, no need to clutter output. Trace fields don't
+// overwrite caller-provided data so explicit overrides still win. Exported
+// for unit tests.
+export function mergeTraceFields(data) {
+    const span = observabilityContext.getActiveSpan();
+    if (!span?.traceId)
+        return data;
+    const traceFields = { traceId: span.traceId, spanId: span.spanId };
+    return data ? { ...traceFields, ...data } : traceFields;
+}
+function wrapPino(p) {
+    return {
+        info(msg, data) {
+            const merged = mergeTraceFields(data);
+            if (merged)
+                p.info(merged, msg);
+            else
+                p.info(msg);
+        },
+        warn(msg, data) {
+            const merged = mergeTraceFields(data);
+            if (merged)
+                p.warn(merged, msg);
+            else
+                p.warn(msg);
+        },
+        error(msg, data) {
+            const merged = mergeTraceFields(data);
+            if (merged)
+                p.error(merged, msg);
+            else
+                p.error(msg);
+        },
+        debug(msg, data) {
+            const merged = mergeTraceFields(data);
+            if (merged)
+                p.debug(merged, msg);
+            else
+                p.debug(msg);
+        },
+        child(ctx) {
+            return wrapPino(p.child(ctx));
+        },
+    };
+}

package/dist/logging/types.js

@@ -0,0 +1 @@
+export {};

package/dist/logging/utils.d.ts

@@ -0,0 +1,8 @@
+import type { Logger } from "./types.js";
+type FallbackLogger = {
+    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 createFallbackLogger(namespace: string, logger?: (Pick<Logger, "error"> & Partial<Pick<Logger, "warn" | "debug">>) | undefined): FallbackLogger;
+export {};

package/dist/logging/utils.js

@@ -0,0 +1,41 @@
+export function createFallbackLogger(namespace, logger) {
+    if (logger) {
+        return {
+            error(msg, data) {
+                logger.error(`[${namespace}] ${msg}`, data);
+            },
+            warn(msg, data) {
+                if (logger.warn) {
+                    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);
+                }
+            },
+            debug(msg, data) {
+                if (logger.debug) {
+                    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);
+                }
+            },
+        };
+    }
+    return {
+        error(msg, data) {
+            // biome-ignore lint/suspicious/noConsole: ops-visible fallback when no logger is wired
+            console.error(`[${namespace}] ${msg}`, data);
+        },
+        warn(msg, data) {
+            // biome-ignore lint/suspicious/noConsole: ops-visible fallback when no logger is wired
+            console.warn(`[${namespace}] ${msg}`, data);
+        },
+        debug(msg, data) {
+            // biome-ignore lint/suspicious/noConsole: ops-visible fallback when no logger is wired
+            console.debug(`[${namespace}] ${msg}`, data);
+        },
+    };
+}

package/dist/migrations/index.d.ts

@@ -0,0 +1,4 @@
+export { assertKumikoSchemaCurrent, type ChecksumMismatch, detectKumikoDrift, formatKumikoDriftReport, type KumikoDriftReport, SchemaDriftError, } from "./kumiko-drift.js";
+export { createPendingRebuildsTable, type EnqueueProjectionRebuildDeps, type EnqueueProjectionRebuildResult, enqueueProjectionRebuild, listPendingRebuilds, type PendingRebuildRun, PROJECTION_REBUILD_JOB, pendingRebuildsTable, queueRebuildsFromMarkers, type RunPendingRebuildsOptions, rebuildProjectionOrMultiStream, runPendingRebuilds, } from "./pending-rebuilds.js";
+export { createPiiBackfillStateTable, type PiiEventBackfillOptions, type PiiEventBackfillResult, type PiiRebuildRun, piiAnnotationFingerprint, piiBackfillStateTable, runPiiEventBackfill, } from "./pii-event-backfill.js";
+export { buildProjectionTableIndex } from "./projection-table-index.js";

package/dist/migrations/index.js

@@ -0,0 +1,8 @@
+// Drizzle-free gate (kumiko/migrations system) — the canonical boot-gate.
+export { assertKumikoSchemaCurrent, detectKumikoDrift, formatKumikoDriftReport, SchemaDriftError, } from "./kumiko-drift.js";
+// Persistente Pending-Rebuild-Queue (survives Rebuild-Failures + Crashes).
+export { createPendingRebuildsTable, enqueueProjectionRebuild, listPendingRebuilds, PROJECTION_REBUILD_JOB, pendingRebuildsTable, queueRebuildsFromMarkers, rebuildProjectionOrMultiStream, 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.
+export { buildProjectionTableIndex } from "./projection-table-index.js";

package/dist/migrations/kumiko-drift.d.ts

@@ -0,0 +1,26 @@
+import type { DbConnection } from "../db/connection.js";
+export type ChecksumMismatch = {
+    readonly id: string;
+    readonly expected: string;
+    readonly actual: string;
+};
+export type MissingColumns = {
+    readonly table: string;
+    readonly columns: readonly string[];
+};
+export type KumikoDriftReport = {
+    readonly ok: boolean;
+    readonly pending: readonly string[];
+    readonly checksumMismatches: readonly ChecksumMismatch[];
+    readonly missingTables: readonly string[];
+    readonly missingColumns: readonly MissingColumns[];
+};
+export declare class SchemaDriftError extends Error {
+    readonly report: KumikoDriftReport;
+    constructor(message: string, report: KumikoDriftReport);
+}
+export declare function detectKumikoDrift(db: DbConnection, migrationsDir: string): Promise<KumikoDriftReport>;
+export declare function formatKumikoDriftReport(report: KumikoDriftReport): string;
+/** Throws SchemaDriftError with a human-readable message when the DB is not
+ *  current with the checked-in kumiko/migrations. */
+export declare function assertKumikoSchemaCurrent(db: DbConnection, migrationsDir: string): Promise<void>;

package/dist/migrations/kumiko-drift.js

@@ -0,0 +1,151 @@
+// Drizzle-free schema-drift gate for the `kumiko/migrations` system.
+//
+// Replaces the drizzle-journal gate (schema-drift.ts). Validates two layers
+// against the checked-in artifacts:
+//
+//   1. Migrations applied: every `kumiko/migrations/*.sql` has a row in
+//      `_kumiko_migrations`. Applied-but-edited (checksum mismatch) is drift.
+//   2. Tables exist: every table in `kumiko/migrations/.snapshot.json` exists.
+//   3. Columns exist: every column the snapshot declares for an existing table
+//      is present in the live schema. A migrated-but-incomplete table (snapshot
+//      richer than the DB — e.g. a ride-along column the generator once missed)
+//      would otherwise surface only as a runtime-500 on the first write.
+//
+// Contract (unchanged from the legacy gate): boot VALIDATES only, never
+// applies. Apply is the deploy-step `kumiko schema apply` (runMigrationsFromDir).
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { loadSnapshotJson } from "../db/migrate-generator.js";
+import { fetchAppliedMigrations, loadMigrationsFromDir } from "../db/migrate-runner.js";
+import { columnNamesOf, tableExists } from "../db/schema-inspection.js";
+const SNAPSHOT_FILENAME = ".snapshot.json";
+export class SchemaDriftError extends Error {
+    report;
+    constructor(message, report) {
+        super(message);
+        this.name = "SchemaDriftError";
+        this.report = report;
+    }
+}
+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.
+    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.
+    const trackingExists = await tableExists(db, "_kumiko_migrations");
+    const applied = trackingExists
+        ? new Map((await fetchAppliedMigrations(db)).map((a) => [a.id, a.checksum]))
+        : new Map();
+    const pending = [];
+    const checksumMismatches = [];
+    for (const m of local) {
+        const appliedChecksum = applied.get(m.id);
+        if (appliedChecksum === undefined) {
+            pending.push(m.id);
+        }
+        else if (appliedChecksum !== m.checksum) {
+            checksumMismatches.push({ id: m.id, expected: appliedChecksum, actual: m.checksum });
+        }
+    }
+    // Layer 2 — tables from the latest snapshot must exist. No snapshot (app
+    // hasn't generated one yet) → skip table-existence, the migrations-applied
+    // layer still gates.
+    const snapshot = loadSnapshotJson(join(migrationsDir, SNAPSHOT_FILENAME));
+    const missingTables = [];
+    const missingColumns = [];
+    if (snapshot) {
+        const existence = await Promise.all(snapshot.tables.map((t) => tableExists(db, t.tableName).then((exists) => ({ t, exists }))));
+        const present = [];
+        for (const { t, exists } of existence) {
+            if (exists)
+                present.push(t);
+            else
+                missingTables.push(t.tableName);
+        }
+        // Layer 3 — column-diff for tables that DO exist.
+        const columnChecks = await Promise.all(present.map((t) => columnNamesOf(db, t.tableName).then((live) => ({
+            table: t.tableName,
+            columns: t.columns.map((c) => c.name).filter((n) => !live.has(n)),
+        }))));
+        for (const c of columnChecks)
+            if (c.columns.length > 0)
+                missingColumns.push(c);
+    }
+    return {
+        ok: pending.length === 0 &&
+            checksumMismatches.length === 0 &&
+            missingTables.length === 0 &&
+            missingColumns.length === 0,
+        pending,
+        checksumMismatches,
+        missingTables,
+        missingColumns,
+    };
+}
+export function formatKumikoDriftReport(report) {
+    if (report.ok)
+        return "Schema is current.";
+    const lines = ["Schema drift detected:"];
+    if (report.pending.length > 0) {
+        lines.push(`  ${report.pending.length} unapplied migration(s):`);
+        for (const id of report.pending)
+            lines.push(`    - ${id}`);
+    }
+    if (report.checksumMismatches.length > 0) {
+        lines.push(`  ${report.checksumMismatches.length} edited-after-apply migration(s):`);
+        for (const m of report.checksumMismatches) {
+            lines.push(`    - ${m.id}: db ${m.expected.slice(0, 12)}…, file ${m.actual.slice(0, 12)}…`);
+        }
+    }
+    if (report.missingTables.length > 0) {
+        lines.push(`  ${report.missingTables.length} missing table(s):`);
+        for (const t of report.missingTables)
+            lines.push(`    - ${t}`);
+    }
+    if (report.missingColumns.length > 0) {
+        const count = report.missingColumns.reduce((n, m) => n + m.columns.length, 0);
+        lines.push(`  ${count} missing column(s):`);
+        for (const m of report.missingColumns) {
+            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.
+    lines.push("");
+    if (report.pending.length > 0) {
+        lines.push("Run 'kumiko schema apply' to apply the pending migration(s).");
+    }
+    if (report.checksumMismatches.length > 0) {
+        lines.push("Revert the edited migration file(s) to their applied content, or hand-correct");
+        lines.push("the checksum in _kumiko_migrations — 'kumiko schema apply' cannot resolve a");
+        lines.push("checksum mismatch.");
+    }
+    if (report.missingTables.length > 0 && report.pending.length === 0) {
+        lines.push("Missing table(s) without pending migration(s) — table was dropped after apply.");
+        lines.push("Restore from backup, or generate a new migration that re-creates the table.");
+    }
+    if (report.missingColumns.length > 0) {
+        lines.push("Missing column(s) — the live table predates a richer snapshot (e.g. a");
+        lines.push("ride-along column the generator now emits). Run 'kumiko schema generate' to");
+        lines.push("produce an ALTER-TABLE migration for the new column(s), then 'kumiko schema apply'.");
+    }
+    return lines.join("\n");
+}
+/** Throws SchemaDriftError with a human-readable message when the DB is not
+ *  current with the checked-in kumiko/migrations. */
+export async function assertKumikoSchemaCurrent(db, migrationsDir) {
+    const report = await detectKumikoDrift(db, migrationsDir);
+    if (!report.ok)
+        throw new SchemaDriftError(formatKumikoDriftReport(report), report);
+}

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

@@ -0,0 +1,81 @@
+import type { DbConnection } from "../db/connection.js";
+import type { Registry } from "../engine/types/index.js";
+import type { JobRunner } from "../jobs/index.js";
+import { type RebuildResult } from "../pipeline/index.js";
+export declare const pendingRebuildsTable: import("@cosmicdrift/kumiko-types/schema-table-types").SchemaTable;
+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). */
+export declare function queueRebuildsFromMarkers(db: DbConnection, options: {
+    readonly migrationsDir: string;
+    readonly appliedIds: readonly string[];
+}): Promise<readonly string[]>;
+type PendingRebuildRow = {
+    readonly tableName: string;
+    readonly migrationId: string;
+};
+export declare function listPendingRebuildRows(db: DbConnection): Promise<readonly PendingRebuildRow[]>;
+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). */
+    readonly rebuilt: readonly {
+        readonly projection: string;
+        readonly eventsProcessed: number;
+    }[];
+    /** Fehlgeschlagene Projektionen — ihre Tabellen BLEIBEN pending. */
+    readonly failed: readonly {
+        readonly projection: string;
+        readonly error: string;
+    }[];
+    /** Pending tables without a registered projection that are either NOT
+     *  freshly emptied via marker in this run (pre-existing / legacy unmanaged
+     *  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. */
+    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). */
+    readonly thisRunTables?: readonly string[];
+};
+export declare function rebuildProjectionOrMultiStream(name: string, deps: {
+    readonly db: DbConnection;
+    readonly registry: Registry;
+    readonly signal?: AbortSignal;
+    readonly errorPolicy?: {
+        readonly skipApplyErrors?: boolean;
+    };
+}): Promise<RebuildResult>;
+/** 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`). */
+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 = {
+    readonly mode: "dispatched";
+    readonly bullJobId: string;
+} | {
+    readonly mode: "inline";
+    readonly result: RebuildResult;
+};
+export type EnqueueProjectionRebuildDeps = {
+    readonly db: DbConnection;
+    readonly registry: Registry;
+    readonly jobRunner?: JobRunner;
+};
+export declare function enqueueProjectionRebuild(projection: string, deps: EnqueueProjectionRebuildDeps): Promise<EnqueueProjectionRebuildResult>;
+export {};