@cosmicdrift/kumiko-framework 0.327.0 → 0.328.1

package/dist/migrations/pending-rebuilds.js

@@ -0,0 +1,163 @@
+// Persistente Pending-Rebuild-Queue für den `kumiko schema apply`-Pfad.
+//
+// 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.
+//
+// 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.
+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";
+import { tableExists } from "../db/schema-inspection.js";
+import { createFallbackLogger } from "../logging/utils.js";
+import { rebuildMultiStreamProjection, rebuildProjection, } from "../pipeline/index.js";
+import { unsafePushTables } from "../stack/index.js";
+import { buildProjectionTableIndex } from "./projection-table-index.js";
+export const pendingRebuildsTable = pgTable("kumiko_pending_rebuilds", {
+    tableName: text("table_name").primaryKey(),
+    migrationId: text("migration_id").notNull(),
+    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
+    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). */
+export async function queueRebuildsFromMarkers(db, options) {
+    await createPendingRebuildsTable(db);
+    const queued = new Set();
+    for (const migrationId of options.appliedIds) {
+        for (const tableName of readRebuildMarker(options.migrationsDir, migrationId)) {
+            await upsertOnConflict(db, pendingRebuildsTable, { tableName, migrationId }, { conflictKeys: ["tableName"], update: { migrationId } });
+            queued.add(tableName);
+        }
+    }
+    return [...queued];
+}
+export async function listPendingRebuildRows(db) {
+    await createPendingRebuildsTable(db);
+    const rows = await selectMany(db, pendingRebuildsTable, undefined, {
+        orderBy: [{ col: "queuedAt" }, { col: "tableName" }],
+    });
+    return rows.map((row) => ({ tableName: row.tableName, migrationId: row.migrationId }));
+}
+export async function listPendingRebuilds(db) {
+    return (await listPendingRebuildRows(db)).map((row) => row.tableName);
+}
+// Clears against the (table_name, migration_id) snapshot the caller read, not
+// 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)
+export async function clearPendingRebuilds(db, rows) {
+    for (const { tableName, migrationId } of rows) {
+        await deleteMany(db, pendingRebuildsTable, { tableName, migrationId });
+    }
+}
+// buildProjectionTableIndex maps both single-stream and multi-stream projection
+// tables to their name, so the rebuild has to pick the matching path. Queue
+// drains are automatic rebuilds: a failed MSP replay rolls back, stays queued
+// and must not park the still-intact live consumer as dead.
+export async function rebuildProjectionOrMultiStream(name, deps) {
+    const { db, registry, signal, errorPolicy } = deps;
+    if (registry.getAllMultiStreamProjections().has(name)) {
+        return rebuildMultiStreamProjection(name, { db, registry, markDeadOnFailure: false });
+    }
+    return rebuildProjection(name, {
+        db,
+        registry,
+        ...(signal && { signal }),
+        ...(errorPolicy && { errorPolicy }),
+    });
+}
+/** 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 async function runPendingRebuilds(db, registry, options = {}) {
+    const pendingRows = await listPendingRebuildRows(db);
+    if (pendingRows.length === 0) {
+        return { rebuilt: [], failed: [], unmapped: [], unresolvedManaged: [] };
+    }
+    // (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).
+    const migrationByTable = new Map(pendingRows.map((r) => [r.tableName, r.migrationId]));
+    const snapshotRows = (tables) => tables.flatMap((tableName) => {
+        const migrationId = migrationByTable.get(tableName);
+        return migrationId === undefined ? [] : [{ tableName, migrationId }];
+    });
+    const pending = pendingRows.map((r) => r.tableName);
+    const tableToProjection = buildProjectionTableIndex(registry);
+    const thisRun = new Set(options.thisRunTables ?? []);
+    const byProjection = new Map();
+    const unmapped = [];
+    const unresolvedManaged = [];
+    for (const tableName of pending) {
+        const projection = tableToProjection.get(tableName);
+        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
+            // 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
+            // markers → still drain silently as before.
+            if (thisRun.has(tableName) && (await tableExists(db, `public.${tableName}`))) {
+                unresolvedManaged.push(tableName);
+            }
+            else {
+                unmapped.push(tableName);
+            }
+            continue;
+        }
+        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.
+    const drained = [...unmapped, ...unresolvedManaged];
+    if (drained.length > 0) {
+        await clearPendingRebuilds(db, snapshotRows(drained));
+    }
+    if (unresolvedManaged.length > 0) {
+        createFallbackLogger("migrations:pending-rebuilds").error(`${unresolvedManaged.length} managed projection table(s) emptied by a migration in this run have no registered projection — the owning feature is likely missing from the composition. They are now EMPTY and were NOT rebuilt: ${unresolvedManaged.join(", ")}. Restore the owning feature or rebuild the projection manually.`, { tables: unresolvedManaged });
+    }
+    const rebuilt = [];
+    const failed = [];
+    for (const [projection, tables] of byProjection) {
+        try {
+            const result = await rebuildProjectionOrMultiStream(projection, { db, registry });
+            await clearPendingRebuilds(db, snapshotRows(tables));
+            rebuilt.push({ projection, eventsProcessed: result.eventsProcessed });
+        }
+        catch (e) {
+            failed.push({ projection, error: e instanceof Error ? e.message : String(e) });
+        }
+    }
+    return { rebuilt, failed, unmapped, unresolvedManaged };
+}
+// Registered by the `jobs` bundled-feature; a jobs-less boot has no jobRunner and rebuilds inline instead.
+export const PROJECTION_REBUILD_JOB = "jobs:job:projection-rebuild";
+// Capability detection via registry.getJob (NOT hasFeature) — deterministic, no toggle-runtime dependency.
+export async function enqueueProjectionRebuild(projection, deps) {
+    const { db, registry, jobRunner } = deps;
+    if (jobRunner !== undefined && registry.getJob(PROJECTION_REBUILD_JOB) !== undefined) {
+        const bullJobId = await jobRunner.dispatch(PROJECTION_REBUILD_JOB, { projection });
+        return { mode: "dispatched", bullJobId };
+    }
+    const result = await rebuildProjectionOrMultiStream(projection, { db, registry });
+    return { mode: "inline", result };
+}

package/dist/migrations/pii-event-backfill.d.ts

@@ -0,0 +1,40 @@
+import type { DbConnection } from "../db/connection.js";
+import { type PiiBackfillFailure } from "../db/queries/backfill-pii.js";
+import type { Registry } from "../engine/types/index.js";
+import type { Logger } from "../logging/types.js";
+export declare const piiBackfillStateTable: import("@cosmicdrift/kumiko-types/schema-table-types").SchemaTable;
+export declare function createPiiBackfillStateTable(db: DbConnection): Promise<void>;
+export declare function piiAnnotationEntries(registry: Registry): readonly string[];
+export declare function piiAnnotationFingerprint(registry: Registry): string;
+export type PiiEventBackfillOptions = {
+    readonly signal?: AbortSignal;
+    readonly batchSize?: number;
+    readonly logger?: Pick<Logger, "error"> & Partial<Pick<Logger, "warn" | "debug">>;
+};
+export type PiiRebuildRun = {
+    readonly rebuilt: readonly {
+        readonly projection: string;
+        readonly eventsProcessed: number;
+    }[];
+    readonly failed: readonly {
+        readonly projection: string;
+        readonly error: string;
+    }[];
+    readonly skippedTables: readonly string[];
+};
+export type PiiEventBackfillResult = {
+    readonly status: "skipped";
+    readonly reason: "no_kms" | "no_pii";
+} | {
+    readonly status: "ran";
+    readonly mode: "full" | "catch-up";
+    readonly aborted: boolean;
+    readonly scannedEvents: number;
+    readonly updatedEvents: number;
+    readonly encryptedFields: number;
+    readonly erasedFields: number;
+    readonly failures: readonly PiiBackfillFailure[];
+    readonly queuedTables: readonly string[];
+    readonly rebuild: PiiRebuildRun | null;
+};
+export declare function runPiiEventBackfill(db: DbConnection, registry: Registry, options?: PiiEventBackfillOptions): Promise<PiiEventBackfillResult>;

package/dist/migrations/pii-event-backfill.js

@@ -0,0 +1,275 @@
+// Boot-time PII backfill for kumiko_events: when a field gains a PII annotation
+// after events were already stored, the rebuild copies payloads unchanged, so
+// old events stay plaintext until they are re-encrypted in place. This runs the
+// batch primitive from backfill-pii.ts once per annotation state (fingerprint),
+// then cheap catch-up passes, and rebuilds the projections whose source events
+// changed (including multi-stream projections with their own table) so
+// ciphertext and blind-index columns get materialized.
+import { createHash } from "node:crypto";
+import { configuredEventPiiCatalog } from "../crypto/event-pii.js";
+import { isLocalKeyKmsAdapter } from "../crypto/kms-adapter.js";
+import { configuredPiiSubjectKms } from "../crypto/pii-field-encryption.js";
+import { collectPiiSubjectFields } from "../crypto/subject-resolver.js";
+import { bigint, instant, table as pgTable, sql, text } from "../db/dialect.js";
+import { extractTableName } from "../db/index.js";
+import { acquireNamespacedAdvisoryLock } from "../db/queries/advisory-lock.js";
+import { backfillEventPiiEncryptionBatch, } from "../db/queries/backfill-pii.js";
+import { persistPiiBackfillState, readPiiBackfillState, } from "../db/queries/pii-backfill-state.js";
+import { upsertOnConflict } from "../db/query.js";
+import { tableExists } from "../db/schema-inspection.js";
+import { createFallbackLogger } from "../logging/utils.js";
+import { unsafePushTables } from "../stack/index.js";
+import { clearPendingRebuilds, createPendingRebuildsTable, listPendingRebuildRows, pendingRebuildsTable, rebuildProjectionOrMultiStream, } from "./pending-rebuilds.js";
+import { buildProjectionTableIndex } from "./projection-table-index.js";
+const PII_EVENT_BACKFILL_LOCK_NAMESPACE = 0x70_69_69_62; // 'piib'
+const PII_EVENT_BACKFILL_LOCK_KEY = "pii-event-backfill";
+const PII_BACKFILL_MIGRATION_PREFIX = "pii-backfill:";
+const DEFAULT_BATCH_SIZE = 500;
+const MAX_LOGGED_FAILURE_IDS = 50;
+// Events can commit with an id lower than an already-scanned one (late commits),
+// and old pods in a rolling deploy keep writing the newly annotated field as
+// plaintext. The transformation is idempotent, so overlap only costs reads.
+const CATCH_UP_OVERLAP_EVENT_IDS = 1000n;
+export const piiBackfillStateTable = pgTable("kumiko_pii_backfill_state", {
+    fingerprint: text("fingerprint").primaryKey(),
+    cursorEventId: bigint("cursor_event_id", { mode: "bigint" }).notNull().default(0),
+    completedAt: instant("completed_at", { precision: 3 }),
+    updatedAt: instant("updated_at", { precision: 3 }).notNull().default(sql `now()`),
+});
+export async function createPiiBackfillStateTable(db) {
+    // skip: table already exists — boot runs on every replica
+    if (await tableExists(db, "public.kumiko_pii_backfill_state"))
+        return;
+    await unsafePushTables(db, { kumikoPiiBackfillState: piiBackfillStateTable });
+}
+// Replicas boot concurrently: two of them can both pass the tableExists gate and
+// one CREATE then fails. The table existing afterwards means the other won.
+async function ensureInfraTable(db, tableName, create) {
+    try {
+        await create(db);
+    }
+    catch (e) {
+        if (!(await tableExists(db, `public.${tableName}`)))
+            throw e;
+    }
+}
+export function piiAnnotationEntries(registry) {
+    const entries = [];
+    for (const [name, entity] of registry.getAllEntities()) {
+        for (const field of collectPiiSubjectFields(entity))
+            entries.push(`entity:${name}.${field}`);
+    }
+    for (const [eventType, fields] of configuredEventPiiCatalog()) {
+        for (const field of Object.keys(fields))
+            entries.push(`event:${eventType}.${field}`);
+    }
+    return entries.sort();
+}
+export function piiAnnotationFingerprint(registry) {
+    return createHash("sha256").update(piiAnnotationEntries(registry).join("\n")).digest("hex");
+}
+async function queueRebuildTables(db, tableNames, migrationId) {
+    for (const tableName of tableNames) {
+        await upsertOnConflict(db, pendingRebuildsTable, { tableName, migrationId }, { conflictKeys: ["tableName"], update: { migrationId } });
+    }
+}
+function affectedProjectionTables(registry, touchedAggregateTypes, touchedEventTypes) {
+    const tables = new Set();
+    for (const [name, def] of registry.getAllProjections()) {
+        const sources = [
+            ...(Array.isArray(def.source) ? def.source : [def.source]),
+            ...(def.extraSources ?? []),
+        ];
+        const isAffected = sources.some((source) => touchedAggregateTypes.has(source)) ||
+            Object.keys(def.apply).some((eventType) => touchedEventTypes.has(eventType));
+        if (isAffected)
+            tables.add(extractTableName(def.table, `pii-event-backfill(${name})`));
+    }
+    // MSP apply gets the raw event payloads, so their tables hold plaintext until rebuilt.
+    for (const [name, def] of registry.getAllMultiStreamProjections()) {
+        if (def.table === undefined)
+            continue;
+        if (Object.keys(def.apply).some((eventType) => touchedEventTypes.has(eventType))) {
+            tables.add(extractTableName(def.table, `pii-event-backfill(${name})`));
+        }
+    }
+    return [...tables];
+}
+function initialScanCursor(state) {
+    const cursor = BigInt(state?.cursor ?? "0");
+    if (state?.completed !== true)
+        return { mode: "full", scanCursor: cursor };
+    return {
+        mode: "catch-up",
+        scanCursor: cursor > CATCH_UP_OVERLAP_EVENT_IDS ? cursor - CATCH_UP_OVERLAP_EVENT_IDS : 0n,
+    };
+}
+// One transaction per batch: the advisory lock serializes pods, and the payload
+// is re-read inside it so a value is never encrypted twice and two backfills
+// never mint the same DEK. Returns null when another pod already finished a full run.
+async function runOneBatch(ctx, progress) {
+    return ctx.db.begin(async (tx) => {
+        await acquireNamespacedAdvisoryLock(tx, PII_EVENT_BACKFILL_LOCK_NAMESPACE, PII_EVENT_BACKFILL_LOCK_KEY);
+        const state = await readPiiBackfillState(tx, ctx.fingerprint);
+        if (ctx.mode === "full" && state?.completed === true)
+            return null;
+        const startCursor = ctx.mode === "full" && state
+            ? maxBigInt(progress.scanCursor, BigInt(state.cursor))
+            : progress.scanCursor;
+        const batch = await backfillEventPiiEncryptionBatch(tx, ctx.registry, {
+            afterEventId: startCursor,
+            batchSize: ctx.batchSize,
+            resolveOwnerFromProjection: true,
+            scanCache: progress.scanCache,
+        });
+        const batchTouchedEventTypes = new Set(batch.touchedEventTypes);
+        const tables = batch.updatedEvents > 0
+            ? affectedProjectionTables(ctx.registry, new Set(batch.touchedAggregateTypes), batchTouchedEventTypes)
+            : [];
+        if (tables.length > 0)
+            await queueRebuildTables(tx, tables, ctx.migrationId);
+        if (!progress.failureSeen) {
+            const completesRun = batch.scannedAll && batch.failures.length === 0;
+            await persistPiiBackfillState(tx, ctx.fingerprint, persistableCursor(batch, startCursor), completesRun);
+        }
+        return { batch, tables };
+    });
+}
+function recordBatch(progress, step) {
+    const { batch } = step;
+    progress.totals.scannedEvents += batch.scannedEvents;
+    progress.totals.updatedEvents += batch.updatedEvents;
+    progress.totals.encryptedFields += batch.encryptedFields;
+    progress.totals.erasedFields += batch.erasedFields;
+    progress.failures.push(...batch.failures);
+    for (const table of step.tables)
+        progress.queuedTables.add(table);
+    if (batch.failures.length > 0)
+        progress.failureSeen = true;
+}
+// Returns true when the run was aborted between batches.
+async function scanAllBatches(ctx, progress, signal) {
+    for (;;) {
+        if (signal?.aborted)
+            return true;
+        const step = await runOneBatch(ctx, progress);
+        if (step === null)
+            return false;
+        recordBatch(progress, step);
+        if (step.batch.lastEventId === null || step.batch.scannedAll)
+            return false;
+        progress.scanCursor = BigInt(step.batch.lastEventId);
+    }
+}
+function reportRunOutcome(log, progress) {
+    if (progress.failures.length > 0) {
+        log.error(`${progress.failures.length} event(s) could not be PII-encrypted and will be retried on the next boot`, {
+            failureCount: progress.failures.length,
+            eventIds: progress.failures.slice(0, MAX_LOGGED_FAILURE_IDS).map((f) => f.eventId),
+        });
+    }
+}
+export async function runPiiEventBackfill(db, registry, options = {}) {
+    const log = createFallbackLogger("pii-event-backfill", options.logger);
+    const kms = configuredPiiSubjectKms();
+    if (!kms || !isLocalKeyKmsAdapter(kms))
+        return { status: "skipped", reason: "no_kms" };
+    if (piiAnnotationEntries(registry).length === 0) {
+        return { status: "skipped", reason: "no_pii" };
+    }
+    const fingerprint = piiAnnotationFingerprint(registry);
+    await ensureInfraTable(db, "kumiko_pii_backfill_state", createPiiBackfillStateTable);
+    await ensureInfraTable(db, "kumiko_pending_rebuilds", createPendingRebuildsTable);
+    const { mode, scanCursor } = initialScanCursor(await readPiiBackfillState(db, fingerprint));
+    const ctx = {
+        db,
+        registry,
+        fingerprint,
+        migrationId: `${PII_BACKFILL_MIGRATION_PREFIX}${fingerprint.slice(0, 12)}`,
+        mode,
+        batchSize: options.batchSize ?? DEFAULT_BATCH_SIZE,
+    };
+    const progress = {
+        scanCursor,
+        failureSeen: false,
+        scanCache: {},
+        totals: { scannedEvents: 0, updatedEvents: 0, encryptedFields: 0, erasedFields: 0 },
+        failures: [],
+        queuedTables: new Set(),
+    };
+    const aborted = await scanAllBatches(ctx, progress, options.signal);
+    reportRunOutcome(log, progress);
+    const rebuild = aborted ? null : await rebuildQueuedTables(db, registry, options.signal, log);
+    const queuedTables = [...progress.queuedTables];
+    log.debug("PII event backfill finished", {
+        mode,
+        aborted,
+        ...progress.totals,
+        failureCount: progress.failures.length,
+        queuedTables,
+    });
+    return {
+        status: "ran",
+        mode,
+        aborted,
+        ...progress.totals,
+        failures: progress.failures,
+        queuedTables,
+        rebuild,
+    };
+}
+// Never advance past a failed event so the next boot retries it.
+function persistableCursor(batch, startCursor) {
+    if (batch.firstFailedEventId !== null) {
+        const beforeFailure = BigInt(batch.firstFailedEventId) - 1n;
+        return beforeFailure > startCursor ? beforeFailure : startCursor;
+    }
+    return batch.lastEventId === null ? startCursor : BigInt(batch.lastEventId);
+}
+function maxBigInt(a, b) {
+    return a > b ? a : b;
+}
+// Only our own queue rows: runPendingRebuilds would drain the whole queue and
+// silently clear entries this process cannot map (a worker with a narrower
+// feature set would swallow rebuilds queued by the API pod or by schema apply).
+async function rebuildQueuedTables(db, registry, signal, log) {
+    const ownRows = (await listPendingRebuildRows(db)).filter((row) => row.migrationId.startsWith(PII_BACKFILL_MIGRATION_PREFIX));
+    if (ownRows.length === 0)
+        return null;
+    const tableToProjection = buildProjectionTableIndex(registry);
+    const rowsByProjection = new Map();
+    const skippedTables = [];
+    for (const row of ownRows) {
+        const projection = tableToProjection.get(row.tableName);
+        if (projection === undefined) {
+            skippedTables.push(row.tableName);
+            continue;
+        }
+        rowsByProjection.set(projection, [...(rowsByProjection.get(projection) ?? []), row]);
+    }
+    if (skippedTables.length > 0) {
+        log.warn("Queued tables have no projection in this process and stay queued for a process that mounts them", { tables: skippedTables });
+    }
+    const rebuilt = [];
+    const failed = [];
+    for (const [projection, rows] of rowsByProjection) {
+        if (signal?.aborted)
+            break;
+        try {
+            const result = await rebuildProjectionOrMultiStream(projection, {
+                db,
+                registry,
+                ...(signal && { signal }),
+            });
+            await clearPendingRebuilds(db, rows);
+            rebuilt.push({ projection, eventsProcessed: result.eventsProcessed });
+        }
+        catch (e) {
+            failed.push({ projection, error: e instanceof Error ? e.message : String(e) });
+        }
+    }
+    if (failed.length > 0) {
+        log.error("Projection rebuild after PII backfill failed; tables stay queued and are retried on the next boot", { failed });
+    }
+    return { rebuilt, failed, skippedTables };
+}

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

@@ -0,0 +1,5 @@
+import type { Registry } from "../engine/types/feature.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. */
+export declare function buildProjectionTableIndex(registry: Registry): ReadonlyMap<string, string>;

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

@@ -0,0 +1,21 @@
+// 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).
+//
+// Drizzle-frei: der Tabellen-Name kommt aus dem kumiko-Symbol das
+// buildEntityTable/deriveEntityTableMeta an die Table-Definition hängt.
+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. */
+export function buildProjectionTableIndex(registry) {
+    const index = new Map();
+    for (const [name, def] of registry.getAllProjections()) {
+        index.set(extractTableName(def.table, `projection-table-index(${name})`), name);
+    }
+    for (const [name, def] of registry.getAllMultiStreamProjections()) {
+        if (def.table)
+            index.set(extractTableName(def.table, `projection-table-index(${name})`), name);
+    }
+    return index;
+}

package/dist/observability/console-provider.d.ts

@@ -0,0 +1,10 @@
+import type { ObservabilityOptions, ObservabilityProvider } from "./types/index.js";
+type ConsoleWriter = {
+    readonly log: (line: string) => void;
+};
+export type ConsoleProviderOptions = ObservabilityOptions & {
+    readonly writer?: ConsoleWriter;
+    readonly bufferUntilRoot?: boolean;
+};
+export declare function createConsoleProvider(options?: ConsoleProviderOptions): ObservabilityProvider;
+export {};

package/dist/observability/console-provider.js

@@ -0,0 +1,101 @@
+import { RecordingMeter } from "./recording-meter.js";
+import { RecordingTracer } from "./recording-tracer.js";
+import { DEFAULT_SENSITIVE_CONFIG, mergeSensitiveConfig } from "./sensitive-filter.js";
+// Pretty-print a span-tree rooted at `root` into a multi-line string.
+function renderTree(root, children) {
+    const lines = [];
+    const render = (span, prefix, isLast, isRoot) => {
+        const connector = isRoot ? "" : isLast ? "└─ " : "├─ ";
+        const duration = span.endTime !== undefined
+            ? `${(span.endTime - span.startTime).toFixed(1)}ms`
+            : "(unfinished)";
+        const statusTag = span.status === "error" ? " [ERR]" : span.status === "ok" ? "" : "";
+        lines.push(`${prefix}${connector}${span.name} (${duration})${statusTag}`);
+        const attrKeys = Object.keys(span.attributes);
+        const nextPrefix = isRoot ? "  " : `${prefix}${isLast ? "   " : "│  "}`;
+        if (attrKeys.length > 0) {
+            for (const key of attrKeys) {
+                const value = span.attributes[key];
+                lines.push(`${nextPrefix}  ${key}=${String(value)}`);
+            }
+        }
+        if (span.exception) {
+            lines.push(`${nextPrefix}  !exception=${span.exception.name}: ${span.exception.message}`);
+        }
+        const kids = children.get(span.spanId) ?? [];
+        kids.forEach((child, i) => {
+            render(child, nextPrefix, i === kids.length - 1, false);
+        });
+    };
+    render(root, "", true, true);
+    return lines.join("\n");
+}
+function groupByParent(spans) {
+    const map = new Map();
+    for (const s of spans) {
+        const list = map.get(s.parentSpanId) ?? [];
+        list.push(s);
+        map.set(s.parentSpanId, list);
+    }
+    // Sort children by startTime for stable output.
+    for (const [, list] of map) {
+        list.sort((a, b) => a.startTime - b.startTime);
+    }
+    return map;
+}
+export function createConsoleProvider(options = {}) {
+    const writer = options.writer ?? { log: (_line) => { } };
+    const sensitiveConfig = mergeSensitiveConfig(options.sensitiveFilter ?? DEFAULT_SENSITIVE_CONFIG);
+    const bufferUntilRoot = options.bufferUntilRoot !== false;
+    // Per-trace buffer. Once the root (parentSpanId === undefined) ends, we
+    // render and flush. Child spans that arrive after the root ends are
+    // printed immediately as orphans — shouldn't happen in practice but
+    // safer than losing them.
+    const buffer = new Map();
+    const rootSeen = new Map();
+    const handleSpanEnd = (span) => {
+        if (!bufferUntilRoot) {
+            writer.log(renderTree(span, new Map([[span.parentSpanId, []]])));
+            // skip: flat-print mode already emitted the span, no tree buffering needed
+            return;
+        }
+        const bucket = buffer.get(span.traceId) ?? [];
+        bucket.push(span);
+        buffer.set(span.traceId, bucket);
+        if (span.parentSpanId === undefined) {
+            rootSeen.set(span.traceId, span);
+        }
+        const root = rootSeen.get(span.traceId);
+        if (root && span.spanId === root.spanId) {
+            const children = groupByParent(bucket);
+            writer.log(renderTree(root, children));
+            buffer.delete(span.traceId);
+            rootSeen.delete(span.traceId);
+        }
+    };
+    const handleMetric = (event) => {
+        const labelStr = event.labels
+            ? ` {${Object.entries(event.labels)
+                .map(([k, v]) => `${k}=${String(v)}`)
+                .join(",")}}`
+            : "";
+        writer.log(`[metric] ${event.type} ${event.name}${labelStr} value=${event.value}`);
+    };
+    const tracer = new RecordingTracer({ sensitiveConfig, onSpanEnd: handleSpanEnd });
+    const meter = new RecordingMeter(handleMetric);
+    return {
+        name: "console",
+        tracer,
+        meter,
+        async shutdown() {
+            // Flush any orphaned spans (trace whose root never arrived).
+            for (const [traceId, bucket] of buffer) {
+                for (const s of bucket) {
+                    writer.log(`[orphan-span ${traceId}] ${s.name}`);
+                }
+            }
+            buffer.clear();
+            rootSeen.clear();
+        },
+    };
+}

package/dist/observability/context.d.ts

@@ -0,0 +1,10 @@
+import type { Span } from "./types/index.js";
+type ObservabilityContextData = {
+    readonly activeSpan?: Span;
+};
+export declare const observabilityContext: {
+    run<T>(data: ObservabilityContextData, fn: () => T): T;
+    get(): ObservabilityContextData | undefined;
+    getActiveSpan(): Span | undefined;
+};
+export {};

package/dist/observability/context.js

@@ -0,0 +1,13 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+const storage = new AsyncLocalStorage();
+export const observabilityContext = {
+    run(data, fn) {
+        return storage.run(data, fn);
+    },
+    get() {
+        return storage.getStore();
+    },
+    getActiveSpan() {
+        return storage.getStore()?.activeSpan;
+    },
+};

package/dist/observability/escape-hatch-report.d.ts

@@ -0,0 +1,23 @@
+import type { EscapeHatchAuditSink, EscapeHatchReporter, EscapeHatchUseEvent, TenantId } from "../engine/types/index.js";
+import type { Logger } from "../logging/types.js";
+export declare const ESCAPE_HATCH_USED_SIGNAL = "security:escape-hatch-used";
+export type EscapeHatchReportWindow = {
+    shouldReport(key: string, nowMs: number): boolean;
+};
+export declare function createEscapeHatchReportWindow(opts?: {
+    readonly windowMs?: number;
+    readonly maxEntries?: number;
+}): EscapeHatchReportWindow;
+export declare function reportEscapeHatchUse(event: EscapeHatchUseEvent, deps: {
+    readonly sink?: EscapeHatchAuditSink;
+    readonly log?: Logger;
+}): void;
+export declare function createEscapeHatchReporter(opts: {
+    readonly handler: string;
+    readonly tenantId: TenantId;
+    readonly actor: string;
+    readonly sink?: EscapeHatchAuditSink;
+    readonly log?: Logger;
+    readonly window?: EscapeHatchReportWindow;
+}): EscapeHatchReporter;
+export declare function fallbackEscapeHatchReporter(tenantId: TenantId): EscapeHatchReporter;