@cosmicdrift/kumiko-framework 0.158.2 → 0.160.0

package/src/db/entity-table-meta.ts

@@ -19,86 +19,25 @@
 //      append-only-logs mit serial PK, aggregate-ID ohne DEFAULT, …).
 
 import { collectPiiSubjectFields } from "../crypto";
+import type { EntityDefinition, EntityIndexDef, FieldDefinition } from "../engine/types";
 import type {
-  EntityDefinition,
-  EntityIndexDef,
-  EntityRelations,
-  FieldDefinition,
-} from "../engine/types";
+  BuildEntityTableMetaOptions,
+  ColumnMeta,
+  EntityTableMeta,
+  IndexMeta,
+  UnmanagedTableInput,
+} from "./entity-table-meta-types";
 import { READ_MODEL_PREFIX, toSnakeCase, toTableName } from "./table-builder";
 
-// PG-Type-Repertoire das die Read-Model-Tabellen brauchen. Bewusst
-// schmal — keine Vendor-spezifischen Typen (TSVECTOR, HSTORE, etc.).
-// App-Author die solche braucht greift in der reviewten SQL-Migration
-// hand-edit ein, nicht im Generator.
-export type PgType =
-  | "uuid"
-  | "text"
-  | "boolean"
-  | "integer"
-  | "double precision"
-  | "bigint"
-  | "serial"
-  | "bigserial"
-  | "jsonb"
-  | "timestamptz"
-  | "timestamptz(3)"
-  // Exact decimal — precision/scale are encoded in the type string so the
-  // DDL renderer and read-coercion need no side-channel metadata.
-  | `numeric(${number},${number})`;
-
-export type ColumnMeta = {
-  readonly name: string; // snake_case PG column name
-  readonly pgType: PgType;
-  readonly notNull: boolean;
-  // Raw SQL-default-expression (e.g. `now()`, `gen_random_uuid()`,
-  // `'[]'::jsonb`). undefined = no DEFAULT clause.
-  readonly defaultSql?: string;
-  readonly primaryKey?: boolean;
-  readonly identity?: boolean;
-  // bigint/bigserial only: JS round-trip mode. `number` = createBigIntField /
-  // drizzle mode:"number" (safe ≤2^53). `bigint` = money cents, raw unmanaged.
-  readonly bigintJsMode?: "number" | "bigint";
-};
-
-export type IndexMeta = {
-  readonly name: string;
-  readonly columns: readonly string[]; // snake_case PG column names
-  readonly unique?: boolean;
-  // Raw SQL-where-expression for partial indexes. Caller is responsible
-  // for safety — emitted verbatim.
-  readonly whereSql?: string;
-  // Set wenn die EntityDefinition ein partial-Index hat (def.where als
-  // drizzle SQL-AST), der vom Generator nicht zuverlässig renderbar ist.
-  // Renderer emittiert das Statement dann AUSKOMMENTIERT mit Warn-Hint —
-  // App-Author muss das WHERE manuell im generierten SQL hinzufügen.
-  readonly needsManualWhere?: boolean;
-};
-
-export type CompositePrimaryKeyMeta = {
-  readonly name: string;
-  readonly columns: readonly string[];
-};
-
-export type EntityTableMeta = {
-  readonly tableName: string;
-  readonly columns: readonly ColumnMeta[];
-  readonly indexes: readonly IndexMeta[];
-  // For tables with composite PK (no single id column, e.g. snapshots
-  // keyed by aggregate_id+version). When set, no column should have
-  // primaryKey:true; the constraint is emitted at table-level.
-  readonly compositePrimaryKey?: CompositePrimaryKeyMeta;
-  // Source-hint für Diagnose/Tests — nicht funktional verwendet.
-  // "managed" = aus EntityDefinition (mit base-columns + audit-trail).
-  // "unmanaged" = via defineUnmanagedTable — kein Standard-Audit, App
-  // trägt Verantwortung. Migration-Generator + Tooling können den
-  // discriminator nutzen um Warnungen zu rendern ("X tables are unmanaged").
-  readonly source: "managed" | "unmanaged";
-  // PII-Subject-annotated field names (pii/userOwned/tenantOwned). Set by
-  // buildEntityTableMeta so the registry can reject r.storeTable stores
-  // whose direct writes would skip the executor's encryption (#820).
-  readonly piiSubjectFields?: readonly string[];
-};
+export type {
+  BuildEntityTableMetaOptions,
+  ColumnMeta,
+  CompositePrimaryKeyMeta,
+  EntityTableMeta,
+  IndexMeta,
+  PgType,
+  UnmanagedTableInput,
+} from "./entity-table-meta-types";
 
 // Standard base-columns für event-sourced Read-Model-Tabellen. Spiegelt
 // `buildBaseColumns()` aus table-builder.ts (drizzle-Variante).
@@ -293,12 +232,6 @@ export function resolveTableName(
   return `${featureName}_${baseName}`;
 }
 
-export type BuildEntityTableMetaOptions = {
-  readonly featureName?: string;
-  readonly relations?: EntityRelations;
-  readonly source?: "managed" | "unmanaged";
-};
-
 export function buildEntityTableMeta(
   entityName: string,
   entity: EntityDefinition,
@@ -434,13 +367,6 @@ export function buildEntityTableMeta(
 // Heutige use-cases im framework:
 //   - `store_delivery_attempts` — id kommt aus dem Aggregate-Stream
 //   - `store_job_run_logs` — child-table, serial PK, kein tenant-scope
-export type UnmanagedTableInput = {
-  readonly tableName: string;
-  readonly columns: readonly ColumnMeta[];
-  readonly indexes?: readonly IndexMeta[];
-  readonly compositePrimaryKey?: CompositePrimaryKeyMeta;
-};
-
 function sqlExpressionText(where: unknown): string | undefined {
   if (
     typeof where === "object" &&

package/src/db/event-store-executor.ts

@@ -1,19 +1,14 @@
+import type { EventStoreExecutor } from "@cosmicdrift/kumiko-types/event-store-executor-types";
 import type { LocalKeyKmsAdapter } from "../crypto";
-import type {
-  DeleteContext,
-  EntityDefinition,
-  EntityId,
-  SaveContext,
-  SessionUser,
-  WriteResult,
-} from "../engine/types";
+import type { EntityDefinition } from "../engine/types";
 import type { EntityCache } from "../pipeline/entity-cache";
 import type { SearchAdapter } from "../search/types";
 import type { EnvelopeCipher } from "../secrets/envelope-cipher";
 import { buildExecutorContext, type Table } from "./event-store-executor-context";
 import { createReadVerbs } from "./event-store-executor-read";
 import { createWriteVerbs } from "./event-store-executor-write";
-import type { CursorResult } from "./index";
+
+export type { EventStoreExecutor } from "@cosmicdrift/kumiko-types/event-store-executor-types";
 
 // The executor writes events + auto-projection (entity table) in one TX.
 // It no longer knows about user projections — those are driven by the
@@ -42,93 +37,6 @@ export type EventStoreExecutorOptions = {
   kms?: LocalKeyKmsAdapter;
 };
 
-export type EventStoreExecutor = {
-  create: (
-    payload: Record<string, unknown>,
-    user: SessionUser,
-    db: import("./tenant-db").TenantDb,
-  ) => Promise<WriteResult<SaveContext>>;
-
-  update: (
-    payload: { id: EntityId; version?: number | undefined; changes: Record<string, unknown> },
-    user: SessionUser,
-    db: import("./tenant-db").TenantDb,
-    options?: { skipOptimisticLock?: boolean; skipUnchanged?: boolean },
-  ) => Promise<WriteResult<SaveContext>>;
-
-  delete: (
-    payload: { id: EntityId },
-    user: SessionUser,
-    db: import("./tenant-db").TenantDb,
-  ) => Promise<WriteResult<DeleteContext>>;
-
-  // Hard-purge (Art. 17 erasure). Like delete, but emits `<entity>.forgotten`
-  // which hard-deletes the row even for softDelete entities — and, being an
-  // auto-verb replayed by the implicit projection, the erasure survives a
-  // rebuild (created → forgotten → row gone). Reaches soft-deleted rows too.
-  forget: (
-    payload: { id: EntityId },
-    user: SessionUser,
-    db: import("./tenant-db").TenantDb,
-  ) => Promise<WriteResult<DeleteContext>>;
-
-  restore: (
-    payload: { id: EntityId },
-    user: SessionUser,
-    db: import("./tenant-db").TenantDb,
-  ) => Promise<WriteResult<SaveContext>>;
-
-  list: (
-    payload: {
-      cursor?: string | undefined;
-      limit?: number | undefined;
-      search?: string | undefined;
-      sort?: string | undefined;
-      sortDirection?: "asc" | "desc" | undefined;
-      offset?: number | undefined;
-      totalCount?: boolean | undefined;
-      filter?:
-        | {
-            readonly field: string;
-            readonly op: "eq" | "ne" | "lt" | "gt" | "in";
-            readonly value: unknown;
-          }
-        | undefined;
-      // User-gewählte Faceted-Filter (dynamisch, additiv zum statischen
-      // `filter`). Alle werden mit AND verknüpft.
-      filters?:
-        | ReadonlyArray<{
-            readonly field: string;
-            readonly op: "eq" | "ne" | "lt" | "gt" | "in";
-            readonly value: unknown;
-          }>
-        | undefined;
-    },
-    user: SessionUser,
-    db: import("./tenant-db").TenantDb,
-    /** Tier 2.7e Audit-Fix: per-Call SearchAdapter Override. Wenn der
-     *  Executor beim Build keinen SearchAdapter via Options bekommen
-     *  hat (defaultEntityQueryHandler-Pfad), kann der Caller (Handler)
-     *  hier zur Runtime einen aus ctx.searchAdapter durchreichen.
-     *  options.searchAdapter (build-time) gewinnt — runtime-Override
-     *  ist Fallback für die default-Wrapper. */
-    runtimeOptions?: {
-      readonly searchAdapter?: SearchAdapter;
-      // Trash query: skip the implicit `isDeleted = FALSE` filter so soft-
-      // deleted rows are returned too. Tenant + ownership clauses still apply
-      // — includeDeleted only relaxes the soft-delete predicate, never the
-      // visibility ones, so it can ride untrusted query input safely.
-      readonly includeDeleted?: boolean;
-    },
-  ) => Promise<CursorResult<Record<string, unknown>>>;
-
-  detail: (
-    payload: { id: EntityId },
-    user: SessionUser,
-    db: import("./tenant-db").TenantDb,
-  ) => Promise<Record<string, unknown> | null>;
-};
-
 export function createEventStoreExecutor(
   table: Table,
   entity: EntityDefinition,

package/src/db/queries/backfill-pii.ts

@@ -236,6 +236,7 @@ export async function backfillEventPiiEncryption(
           subject,
           value,
           kmsCtx,
+          field,
         );
         return "encrypted";
       } catch (e) {

package/src/db/queries/event-consumer.ts

@@ -47,6 +47,7 @@ export type ConsumerDeliveryOutcome = {
   readonly attempts: number;
   readonly lastError: string | null;
   readonly deadLettered: boolean;
+  readonly processed: number;
 };
 
 export async function updateConsumerDeliveryOutcome(
@@ -55,19 +56,26 @@ export async function updateConsumerDeliveryOutcome(
   instanceId: string,
   outcome: ConsumerDeliveryOutcome,
 ): Promise<void> {
+  // Advancing the cursor proves this pass wasn't poison — reset the re-arm
+  // budget so an unrelated failure down the line gets its own fresh 3
+  // chances instead of inheriting a partially-spent counter from a past,
+  // already-resolved outage.
+  const resetRearmCount = outcome.processed > 0;
   await asRawClient(db).unsafe(
     `UPDATE "kumiko_event_consumers" SET
        "last_processed_event_id" = $1,
        "attempts" = $2,
        "status" = $3,
        "last_error" = $4,
+       "rearm_count" = CASE WHEN $5 THEN 0 ELSE "rearm_count" END,
        "updated_at" = now()
-     WHERE "name" = $5 AND "instance_id" = $6`,
+     WHERE "name" = $6 AND "instance_id" = $7`,
     [
       outcome.cursor,
       outcome.attempts,
       outcome.deadLettered ? "dead" : "idle",
       outcome.lastError,
+      resetRearmCount,
       name,
       instanceId,
     ],
@@ -81,7 +89,7 @@ export async function updateConsumerStatusReturning(
   status: "idle" | "disabled",
 ): Promise<Record<string, unknown> | undefined> {
   const rows = (await asRawClient(db).unsafe(
-    `UPDATE "kumiko_event_consumers" SET "status" = $1, "attempts" = 0, "last_error" = NULL, "updated_at" = now()
+    `UPDATE "kumiko_event_consumers" SET "status" = $1, "attempts" = 0, "last_error" = NULL, "rearm_count" = 0, "updated_at" = now()
      WHERE "name" = $2 AND "instance_id" = $3
      RETURNING *`,
     [status, name, instanceId],
@@ -101,6 +109,7 @@ export async function advanceConsumerPastEventReturning(
        "status" = 'idle',
        "attempts" = 0,
        "last_error" = NULL,
+       "rearm_count" = 0,
        "updated_at" = now()
      WHERE "name" = $2 AND "instance_id" = $3
      RETURNING *`,
@@ -168,3 +177,27 @@ export async function markConsumerRebuildFailed(
     [errorMessage, name, instanceId],
   );
 }
+
+// Auto-revive a dead consumer once its cooldown has elapsed (called from
+// acquireConsumerState — not an ops action, so no "requireConsumerRow"
+// precondition like restartConsumer/enableConsumer). Increments rearm_count
+// so the caller can enforce a lifetime cap on automatic revivals; manual
+// restartConsumer()/enableConsumer() reset it back to 0.
+export async function rearmDeadConsumer(
+  db: AnyDb,
+  name: string,
+  instanceId: string,
+): Promise<Record<string, unknown> | undefined> {
+  const rows = (await asRawClient(db).unsafe(
+    `UPDATE "kumiko_event_consumers" SET
+       "status" = 'idle',
+       "attempts" = 0,
+       "last_error" = NULL,
+       "rearm_count" = "rearm_count" + 1,
+       "updated_at" = now()
+     WHERE "name" = $1 AND "instance_id" = $2
+     RETURNING *`,
+    [name, instanceId],
+  )) as ReadonlyArray<Record<string, unknown>>;
+  return rows[0];
+}

package/src/db/table-builder.ts

@@ -1,3 +1,4 @@
+import type { ExecutorOnly } from "@cosmicdrift/kumiko-types/executor-brand";
 import type {
   EntityDefinition,
   EntityRelations,
@@ -382,25 +383,7 @@ type SoftDeleteColumnsType = {
 };
 
 // ── ES-write brand ──────────────────────────────────────────────────────
-// A managed projection is only writable through the executor (event →
-// rebuild-safe). To make a direct write a *compile* error rather than a
-// convention, EntityTable carries a phantom `unique symbol` prop; the public
-// write helpers reject anything that has it (see NotExecutorOnly + query.ts).
-// The symbol key dodges SchemaTable's `[field: string]: unknown` index
-// signature (string index sigs don't cover symbol keys), so the brand
-// survives the type-erasure that would swallow a plain marker prop — and the
-// executor seam (applyEntityEvent) erases `table` to TableColumns<any>, which
-// carries no such prop, so the one legitimate writer stays green.
-declare const EXECUTOR_ONLY: unique symbol;
-export interface ExecutorOnly {
-  readonly [EXECUTOR_ONLY]: true;
-}
-// Negative brand for write-helper params: a branded EntityTable is NOT
-// assignable (its `true` clashes with `never`), while unmanaged EntityTableMeta
-// and erased SchemaTable pass (they lack the prop, so `?: never` is satisfied).
-export type NotExecutorOnly = {
-  readonly [EXECUTOR_ONLY]?: never;
-};
+export type { ExecutorOnly, NotExecutorOnly } from "@cosmicdrift/kumiko-types/executor-brand";
 
 export type EntityTable<E extends EntityDefinition = EntityDefinition> =
   TableColumns<// biome-ignore lint/suspicious/noExplicitAny: drizzle's internal table-config stays generic; we layer typed columns on top via the intersection below.

package/src/db/tenant-db.ts

@@ -1,3 +1,5 @@
+import type { SchemaTable } from "@cosmicdrift/kumiko-types/schema-table-types";
+import type { TenantDb, TenantDbMode } from "@cosmicdrift/kumiko-types/tenant-db-types";
 import {
   asEntityTableMeta,
   asRawClient,
@@ -12,61 +14,10 @@ import {
 import { SYSTEM_TENANT_ID, type TenantId } from "../engine/types/identifiers";
 import { emitDbQuery, type Meter, registerStandardMetrics, type Tracer } from "../observability";
 import type { DbRunner } from "./connection";
-import type { TableColumns } from "./dialect";
-import type { EntityTableMeta } from "./entity-table-meta";
-import type { NotExecutorOnly } from "./table-builder";
-
-// biome-ignore lint/suspicious/noExplicitAny: Dynamic tables — keys depend on user-defined schema.
-type Table = TableColumns<any>;
-
-// Method-form writes reject the executor-only brand exactly like the free-function
-// helpers (#742): a managed EntityTable is a rebuildable projection, so writing it
-// directly — free-function OR method-form — drifts the row past its event stream and
-// a rebuild wipes it. The permissive base stays (raw pgTables AND unmanaged entity
-// metas are not projections → writable); `& NotExecutorOnly` strips only branded
-// EntityTables (its `[EXECUTOR_ONLY]: true` violates the optional-never). Reads keep
-// the plain `Table` param.
-type WritableTable = (Table | EntityTableMeta) & NotExecutorOnly;
-
-/**
- * TenantDb scope modes:
- *
- * - "tenant" (default): SELECT/UPDATE/DELETE filtered by tenantId + reference data (tenantId=SYSTEM_TENANT_ID).
- *   INSERT forces tenantId — handler cannot override.
- *
- * - "system" (r.systemScope()): No tenant filter on reads/updates/deletes.
- *   INSERT uses tenantId as default but handler can override.
- *
- * Tables without a tenantId column are always unfiltered regardless of mode.
- */
-export type TenantDbMode = "tenant" | "system";
-
-export type TenantDb = {
-  readonly tenantId: TenantId;
-  readonly mode: TenantDbMode;
-  /**
-   * Underlying DbRunner. Framework-internal use (event-store, migrations) —
-   * bypasses tenant-filter. Feature code uses the typed helpers above so the
-   * automatic scoping stays intact.
-   */
-  readonly raw: DbRunner;
-  selectMany<T = Record<string, unknown>>(
-    table: Table,
-    where?: WhereObject,
-    options?: SelectOptions,
-  ): Promise<readonly T[]>;
-  fetchOne<T = Record<string, unknown>>(table: Table, where: WhereObject): Promise<T | undefined>;
-  insertOne<T = Record<string, unknown>>(
-    table: WritableTable,
-    values: Record<string, unknown>,
-  ): Promise<T | undefined>;
-  updateMany<T = Record<string, unknown>>(
-    table: WritableTable,
-    set: Record<string, unknown>,
-    where: WhereObject,
-  ): Promise<readonly T[]>;
-  deleteMany(table: WritableTable, where: WhereObject): Promise<void>;
-};
+
+type Table = SchemaTable;
+
+export type { TenantDb, TenantDbMode } from "@cosmicdrift/kumiko-types/tenant-db-types";
 
 // @cast-boundary tenant-db-row
 export function castTenantRows<T>(rows: readonly Record<string, unknown>[]): readonly T[] {

package/src/engine/__tests__/boot-validator-boot-check.test.ts

@@ -0,0 +1,99 @@
+// r.bootCheck(fn) — feature-declared mount invariants, checked at boot.
+// Mirrors the prompt-store trap (kumiko-enterprise#229): a feature with
+// PII-annotated fields was mounted without its required companion feature,
+// and nothing caught it at boot. The conditional-invariant tests below
+// reproduce that shape: the check only fails when the feature actually has
+// PII fields AND the companion is missing — a bare "is X mounted" check
+// would already be covered by r.requires and wouldn't justify this API.
+
+import { describe, expect, test } from "bun:test";
+import { validateFeatureBootChecks } from "../boot-validator/boot-check";
+import { defineFeature } from "../define-feature";
+import { createEntity, createTextField } from "../factories";
+
+function catchMessage(fn: () => void): string {
+  try {
+    fn();
+  } catch (e) {
+    return e instanceof Error ? e.message : String(e);
+  }
+  throw new Error("expected function to throw, but it did not");
+}
+
+const requiresUserDataHook = (features: readonly { readonly name: string }[]) =>
+  features.some((f) => f.name === "user-data-hook");
+
+const promptStore = () =>
+  defineFeature("prompt-store", (r) => {
+    const promptFields = { text: createTextField({ pii: true }) };
+    r.entity("prompt", createEntity({ fields: promptFields }));
+    r.bootCheck(({ features }) => {
+      // Conditional on this feature's own shape (has a pii field), closed
+      // over from setup — r.requires("user-data-hook") can't express that.
+      const hasPiiField = Object.values(promptFields).some((field) => field.pii);
+      if (hasPiiField && !requiresUserDataHook(features)) {
+        throw new Error("prompt-store has PII fields but no user-data-hook feature is mounted");
+      }
+    });
+  });
+
+describe("r.bootCheck / validateFeatureBootChecks", () => {
+  test("no bootChecks registered → no-op", () => {
+    const noop = defineFeature("noop", () => {});
+    expect(() => validateFeatureBootChecks([noop])).not.toThrow();
+  });
+
+  test("conditional invariant satisfied (companion mounted) → boot succeeds", () => {
+    const userDataHook = defineFeature("user-data-hook", () => {});
+    expect(() => validateFeatureBootChecks([userDataHook, promptStore()])).not.toThrow();
+  });
+
+  test("conditional invariant violated (PII field, no companion) → boot fails with feature-prefixed message", () => {
+    const message = catchMessage(() => validateFeatureBootChecks([promptStore()]));
+    expect(message).toContain("[Feature prompt-store]");
+    expect(message).toContain(
+      "prompt-store has PII fields but no user-data-hook feature is mounted",
+    );
+  });
+
+  test("no PII field → boot succeeds even without the companion", () => {
+    const noPiiFields = { text: createTextField() };
+    const noPii = defineFeature("prompt-store-no-pii", (r) => {
+      r.entity("note", createEntity({ fields: noPiiFields }));
+      r.bootCheck(({ features }) => {
+        const hasPiiField = Object.values(noPiiFields).some((field) => field.pii);
+        if (hasPiiField && !requiresUserDataHook(features)) {
+          throw new Error("unreachable in this test");
+        }
+      });
+    });
+    expect(() => validateFeatureBootChecks([noPii])).not.toThrow();
+  });
+
+  test("multiple bootChecks on one feature all run in order until one throws", () => {
+    const calls: string[] = [];
+    const feature = defineFeature("multi-check", (r) => {
+      r.bootCheck(() => {
+        calls.push("first");
+      });
+      r.bootCheck(() => {
+        calls.push("second");
+        throw new Error("second check failed");
+      });
+    });
+    expect(() => validateFeatureBootChecks([feature])).toThrow("second check failed");
+    expect(calls).toEqual(["first", "second"]);
+  });
+
+  test("ctx.features exposes every mounted feature, not just the declaring one", () => {
+    const a = defineFeature("feature-a", () => {});
+    let seenNames: string[] = [];
+    const b = defineFeature("feature-b", (r) => {
+      r.bootCheck(({ features }) => {
+        seenNames = features.map((f) => f.name);
+      });
+    });
+    validateFeatureBootChecks([a, b]);
+    expect(seenNames).toEqual(["feature-a", "feature-b"]);
+  });
+});