@cosmicdrift/kumiko-framework 0.155.1 → 0.156.1

package/src/es-ops/context.ts

@@ -42,13 +42,15 @@ export function createSeedMigrationContext(
   const defaultSystemUser = createSystemUser(SYSTEM_TENANT_ID);
 
   return {
-    systemWriteAs: async (handlerQualifiedName, payload, tenantIdOverride) => {
+    systemWriteAs: async (handlerQualifiedName, payload, tenantIdOverride, extraRoles) => {
       // tenantIdOverride: baut einen System-User mit der Stream-tenantId
       // damit der Event-Store-Executor das Aggregate im richtigen Stream
       // findet. Verhindert die version_conflict-Falle (siehe Memory
       // feedback_event_store_tenant_consistency.md).
       const executor =
-        tenantIdOverride !== undefined ? createSystemUser(tenantIdOverride) : defaultSystemUser;
+        tenantIdOverride !== undefined || (extraRoles && extraRoles.length > 0)
+          ? createSystemUser(tenantIdOverride ?? SYSTEM_TENANT_ID, extraRoles)
+          : defaultSystemUser;
       const result = await args.dispatcher.write(handlerQualifiedName, payload, executor);
       // Critical: WriteResult{isSuccess: false} würde sonst silent durchlaufen
       // → Marker landet trotz failed-Write → Migration falsch als "applied"

package/src/es-ops/types.ts

@@ -95,11 +95,18 @@ export type SeedMigrationContext = {
    *      tenantIdOverride weglassen (Default SYSTEM_TENANT_ID).
    *    - Tenant-scope-Aggregate (memberships, tenant-config, app-data) →
    *      `tenantIdOverride: m.tenantId` (oder den Stream-Tenant aus
-   *      einem find*-Helper). */
+   *      einem find*-Helper).
+   *
+   *  **extraRoles:** hasAccess has no system-bypass — a handler with an
+   *  explicit role gate (e.g. `access: { roles: ["SystemAdmin"] }` or
+   *  `["anonymous"]`) otherwise rejects the bare `system` actor with
+   *  `access_denied`. Pass the required role(s) here — see
+   *  `createSystemUser`'s `extraRoles` doc. */
   readonly systemWriteAs: (
     handlerQualifiedName: string,
     payload: unknown,
     tenantIdOverride?: TenantId,
+    extraRoles?: readonly string[],
   ) => Promise<WriteResult>;
 
   // Read-helpers für die häufigsten Lookups. Wachsen on-demand —

package/src/pipeline/__tests__/dispatcher.test.ts

@@ -100,6 +100,35 @@ describe("dispatcher.write", () => {
     expect(result.isSuccess).toBe(true);
   });
 
+  test("user-bucketed handler without RateLimitResolver → internal_error", async () => {
+    // Misconfig: a handler opts into L3 rate-limit but the app never loaded the
+    // rate-limiting feature. User buckets cannot skip (unlike ip+no-IP), so we
+    // fail loud at first write instead of silently running uncapped.
+    const rlFeature = defineFeature("rl-user", (r) => {
+      r.entity("item", createEntity({ table: "Items", fields: { name: createTextField() } }));
+      r.writeHandler(
+        "item:create",
+        z.object({ name: z.string() }),
+        async (event) => ({ isSuccess: true, data: { name: event.payload.name } }),
+        {
+          access: { openToAll: true },
+          rateLimit: { per: "user", limit: 3, windowSeconds: 60 },
+        },
+      );
+    });
+    const dispatcher = createDispatcher(createRegistry([rlFeature]), {});
+    const result = await dispatcher.write(
+      "rl-user:write:item:create",
+      { name: "should-not-run" },
+      createTestUser(),
+    );
+    expect(result.isSuccess).toBe(false);
+    if (!result.isSuccess) {
+      expect(result.error.code).toBe("internal_error");
+      expect(result.error.message).toMatch(/RateLimitResolver is configured/);
+    }
+  });
+
   test("ctx.user ist Convenience-Alias auf event.user (gleicher Wert)", async () => {
     // Pinst dass der Handler auf ctx.user zugreifen kann ohne den
     // typo-resistenten event.user-Pfad zu nutzen. Identitätsprüfung

package/src/pipeline/msp-rebuild.ts

@@ -247,6 +247,10 @@ export async function rebuildMultiStreamProjection(
     eventsSkipped: skipped.length,
     lastProcessedEventId,
     durationMs: Date.now() - startedAt,
+    // countColumnDrift is single-table (public.<t> vs kumiko_rebuild.<t>) and
+    // not wired into the multi-stream rebuild path — MSPs don't run the
+    // implicit-projection ghost-row guard either. #916 scope is single-table.
+    columnDriftCount: 0,
   };
   if (deps.meter) {
     emitProjectionRebuild(

package/src/pipeline/projection-rebuild.ts

@@ -10,6 +10,8 @@ import {
   assertLiveColumnsMatchMeta,
   assertNoUnreachableLiveRows,
   buildShadowTable,
+  type ColumnDriftResult,
+  countColumnDrift,
   ensureRebuildSchema,
   fenceLiveTable,
   rebuildMetaOrThrow,
@@ -134,6 +136,11 @@ export type RebuildResult = {
   readonly eventsSkipped: number;
   readonly lastProcessedEventId: bigint;
   readonly durationMs: number;
+  // Live rows whose columns differ from the freshly-replayed shadow (bidx
+  // columns excluded — see countColumnDrift). Non-blocking: the swap
+  // proceeds regardless (#916). 0 for explicit projections (guard is
+  // implicit-only) or when no drift was found.
+  readonly columnDriftCount: number;
 };
 
 type RebuildDeps = {
@@ -178,6 +185,27 @@ type RebuildDeps = {
   readonly __test_onBuildShadowTable?: () => void;
 };
 
+// Ops-facing log line for countColumnDrift's result. No-op when clean. #916.
+function warnOnColumnDrift(
+  projectionName: string,
+  tableName: string,
+  drift: ColumnDriftResult,
+): void {
+  // skip: no drift found — nothing to warn about
+  if (drift.rowCount === 0) return;
+  const sampledIds = new Set(drift.sample.map((s) => s.slice(0, s.lastIndexOf("."))));
+  const countLabel =
+    sampledIds.size < drift.rowCount
+      ? `${drift.rowCount} (sample truncated)`
+      : String(drift.rowCount);
+  console.warn(
+    `projection-rebuild "${projectionName}": ${countLabel} live row(s) in "${tableName}" have ` +
+      `column values that differ from the freshly-replayed shadow (sample: ${drift.sample.join(", ")}). ` +
+      "Not blocking — replay wins on swap. Likely cause: a legacy direct-write predating the row's " +
+      "event history (#494), or a sensitive custom field pending #972. Investigate if unexpected.",
+  );
+}
+
 export async function rebuildProjection(
   projectionName: string,
   deps: RebuildDeps,
@@ -205,6 +233,7 @@ export async function rebuildProjection(
   const fenceLockTimeoutMs = deps.fenceLockTimeoutMs ?? DEFAULT_FENCE_LOCK_TIMEOUT_MS;
   const startedAt = Date.now();
   let eventsProcessed = 0;
+  let columnDriftCount = 0;
   let lastProcessedEventId = 0n;
   const skipApplyErrors = deps.errorPolicy?.skipApplyErrors === true;
   // Quarantined events, collected in memory and written once after the
@@ -332,6 +361,11 @@ export async function rebuildProjection(
       // which the swap would silently drop. Implicit projections only.
       if (projection.isImplicit === true) {
         await assertNoUnreachableLiveRows(tx, projectionName, meta.tableName, sourcesList);
+        // Non-blocking counterpart: reports column-level drift (bidx excluded)
+        // without aborting — see countColumnDrift for why this isn't fail-hard.
+        const drift = await countColumnDrift(tx, meta.tableName, meta);
+        columnDriftCount = drift.rowCount;
+        warnOnColumnDrift(projectionName, meta.tableName, drift);
       }
       await finalizeProjectionRebuild(tx, projectionName, lastProcessedEventId);
       await swapShadowIntoLive(tx, meta.tableName);
@@ -361,6 +395,7 @@ export async function rebuildProjection(
     eventsSkipped: skipped.length,
     lastProcessedEventId,
     durationMs: Date.now() - startedAt,
+    columnDriftCount,
   };
   if (deps.meter) {
     emitProjectionRebuild(

package/src/search/__tests__/meilisearch-adapter.integration.test.ts

@@ -9,7 +9,7 @@ const MEILI_KEY = process.env["MEILI_MASTER_KEY"] ?? "kumiko-dev-key";
 
 async function meiliAvailable(): Promise<boolean> {
   try {
-    const health = await fetch(`${MEILI_URL}/health`);
+    const health = await fetch(`${MEILI_URL}/health`, { signal: AbortSignal.timeout(2000) });
     return health.ok;
   } catch {
     return false;
@@ -17,8 +17,15 @@ async function meiliAvailable(): Promise<boolean> {
 }
 
 // skipIf when compose Meili is down — unit tests still cover index/doc id shaping.
+// In a dedicated integration job (REQUIRE_MEILI=1) a down Meili is a hard
+// failure, not a silent skip — the compose service is expected to be up there.
 const MEILI_UP = await meiliAvailable();
 if (!MEILI_UP) {
+  if (process.env["REQUIRE_MEILI"] === "1") {
+    throw new Error(
+      `REQUIRE_MEILI=1 but Meilisearch not reachable at ${MEILI_URL} — integration job misconfigured`,
+    );
+  }
   console.warn(
     `Meilisearch not reachable at ${MEILI_URL} — skipping live adapter tests ` +
       `(docker compose up -d meilisearch, default port 17700)`,

package/src/stack/test-stack.ts

@@ -409,8 +409,13 @@ export async function setupTestStack(options: TestStackOptions): Promise<TestSta
       },
     };
   } catch (error) {
-    // Best-effort — a broken jobRunner.stop() must never mask the real
-    // setup failure below.
+    // Best-effort — a broken jobRunner.stop()/cleanup() must never mask the
+    // real setup failure below. testDb/testRedis are created before this
+    // try even starts, so a throw anywhere in setup (buildServer,
+    // search-config, ...) would otherwise leak their open pg/ioredis
+    // sockets — the caller never gets the stack object back to call
+    // cleanup() itself, which is the same "hangs on exit" failure class
+    // this function exists to prevent.
     if (jobRunner) {
       try {
         await jobRunner.stop();
@@ -418,6 +423,16 @@ export async function setupTestStack(options: TestStackOptions): Promise<TestSta
         // ignore — `error` is the one that matters
       }
     }
+    try {
+      await testDb.cleanup();
+    } catch {
+      // ignore — `error` is the one that matters
+    }
+    try {
+      await testRedis.cleanup();
+    } catch {
+      // ignore — `error` is the one that matters
+    }
     throw error;
   }
 }

package/src/ui-types/index.ts

@@ -89,4 +89,5 @@ export {
 export type { TargetRef } from "../engine/types/target-ref";
 export type { TreeAction, TreeNode, TreeNodeState } from "../engine/types/tree-node";
 export type { WorkspaceDefinition } from "../engine/types/workspace";
+export { PROJECTION_DETAIL_ENTITY } from "../i18n/required-surface-keys";
 export type { AppSchema, FeatureSchema, WorkspaceSchema } from "./app-schema";

package/src/engine/__tests__/unmanaged-table.test.ts

@@ -1,172 +0,0 @@
-// Unit tests for r.unmanagedTable() — the EntityTableMeta cousin of
-// r.rawTable. Same audit-trail contract, different storage shape (post-
-// drizzle migrate-runner). See define-feature.ts / DX-4.
-
-import { describe, expect, test } from "bun:test";
-import {
-  buildEntityTableMeta,
-  defineUnmanagedTable,
-  resolveTableName,
-} from "../../db/entity-table-meta";
-import { defineFeature } from "../define-feature";
-import { createEntity, createTextField } from "../index";
-import { createRegistry } from "../registry";
-
-const probeMeta = defineUnmanagedTable({
-  tableName: "ut_probe",
-  columns: [{ name: "id", pgType: "text", notNull: true, primaryKey: true }],
-});
-const probeMetaTwo = defineUnmanagedTable({
-  tableName: "ut_probe_two",
-  columns: [{ name: "id", pgType: "text", notNull: true, primaryKey: true }],
-});
-
-describe("r.unmanagedTable — declaration", () => {
-  test("rejects duplicate registrations within one feature", () => {
-    expect(() =>
-      defineFeature("probe", (r) => {
-        r.unmanagedTable(probeMeta, { reason: "test" });
-        r.unmanagedTable(probeMeta, { reason: "test" });
-      }),
-    ).toThrow(/already registered/);
-  });
-
-  test("rejects empty reason", () => {
-    expect(() =>
-      defineFeature("probe", (r) => {
-        r.unmanagedTable(probeMeta, { reason: "" });
-      }),
-    ).toThrow(/options\.reason must be a non-empty string/);
-  });
-
-  test("rejects whitespace-only reason", () => {
-    expect(() =>
-      defineFeature("probe", (r) => {
-        r.unmanagedTable(probeMeta, { reason: "   " });
-      }),
-    ).toThrow(/options\.reason must be a non-empty string/);
-  });
-
-  test("accepts valid registration and stores meta + reason", () => {
-    const feature = defineFeature("probe", (r) => {
-      r.unmanagedTable(probeMeta, {
-        reason: "read-side projection of an event-stream",
-      });
-    });
-    expect(feature.unmanagedTables).toHaveProperty("ut_probe");
-    expect(feature.unmanagedTables["ut_probe"]?.reason).toBe(
-      "read-side projection of an event-stream",
-    );
-    expect(feature.unmanagedTables["ut_probe"]?.meta).toBe(probeMeta);
-  });
-
-  test("two unmanaged tables on one feature register under their tableName", () => {
-    const feature = defineFeature("dual", (r) => {
-      r.unmanagedTable(probeMeta, { reason: "one" });
-      r.unmanagedTable(probeMetaTwo, { reason: "two" });
-    });
-    expect(Object.keys(feature.unmanagedTables).sort()).toEqual(["ut_probe", "ut_probe_two"]);
-  });
-
-  test("absent unmanagedTables on a feature is ok", () => {
-    const feat = defineFeature("plain", () => {
-      // no r.unmanagedTable calls
-    });
-    expect(feat.unmanagedTables).toEqual({});
-  });
-});
-
-describe("createRegistry — unmanagedTable aggregation", () => {
-  test("rejects cross-feature tableName collisions at boot", () => {
-    // Two features can't share the same physical tableName — migrate-runner
-    // would race two CREATE TABLE statements. Boot-validator catches it.
-    const featA = defineFeature("a", (r) => {
-      r.unmanagedTable(probeMeta, { reason: "first" });
-    });
-    const featB = defineFeature("b", (r) => {
-      r.unmanagedTable(probeMeta, { reason: "second" });
-    });
-    expect(() => createRegistry([featA, featB])).toThrow(
-      /Unmanaged-table "ut_probe" registered by both feature "a" and "b"/,
-    );
-  });
-
-  test("two features with distinct tableNames register cleanly", () => {
-    const featA = defineFeature("a", (r) => {
-      r.unmanagedTable(probeMeta, { reason: "first" });
-    });
-    const featB = defineFeature("b", (r) => {
-      r.unmanagedTable(probeMetaTwo, { reason: "second" });
-    });
-    expect(() => createRegistry([featA, featB])).not.toThrow();
-  });
-
-  test("rejects an unmanaged-table that collides with an entity's physical name", () => {
-    const widget = createEntity({ fields: { name: createTextField() } });
-    // resolveTableName mirrors the migrate-runner — pin the exact physical name.
-    const physical = resolveTableName("widget", widget, "shop");
-    const clashing = defineUnmanagedTable({
-      tableName: physical,
-      columns: [{ name: "id", pgType: "text", notNull: true, primaryKey: true }],
-    });
-    const entityFeature = defineFeature("shop", (r) => {
-      r.entity("widget", widget);
-    });
-    const tableFeature = defineFeature("other", (r) => {
-      r.unmanagedTable(clashing, { reason: "clash" });
-    });
-
-    // Entity registered first, then the colliding unmanaged table.
-    expect(() => createRegistry([entityFeature, tableFeature])).toThrow(
-      new RegExp(
-        `Unmanaged-table "${physical}".*collides with the physical table of entity "widget"`,
-      ),
-    );
-
-    // Order-independent: unmanaged table registered first, then the entity.
-    expect(() => createRegistry([tableFeature, entityFeature])).toThrow(
-      new RegExp(`Entity "widget".*collides with r.unmanagedTable\\("${physical}"\\)`),
-    );
-  });
-});
-
-describe("createRegistry — unmanaged tables with PII-annotated fields (#820)", () => {
-  const piiEntity = createEntity({
-    table: "ut_pii_probe",
-    fields: {
-      userId: createTextField({ required: true }),
-      ip: createTextField({ userOwned: { ownerField: "userId" } }),
-    },
-  });
-  const piiMeta = buildEntityTableMeta("ut-pii-probe", piiEntity);
-
-  test("buildEntityTableMeta records the subject-annotated field names", () => {
-    expect(piiMeta.piiSubjectFields).toEqual(["ip"]);
-  });
-
-  test("rejects a PII-carrying unmanaged table without piiEncryptedOnWrite", () => {
-    const feat = defineFeature("probe", (r) => {
-      r.unmanagedTable(piiMeta, { reason: "direct-write store" });
-    });
-    expect(() => createRegistry([feat])).toThrow(
-      /has PII-annotated fields \(ip\) but direct writes bypass the executor's PII encryption/,
-    );
-  });
-
-  test("accepts it once the feature declares piiEncryptedOnWrite", () => {
-    const feat = defineFeature("probe", (r) => {
-      r.unmanagedTable(piiMeta, {
-        reason: "direct-write store",
-        piiEncryptedOnWrite: true,
-      });
-    });
-    expect(() => createRegistry([feat])).not.toThrow();
-  });
-
-  test("a PII-free unmanaged table needs no declaration", () => {
-    const feat = defineFeature("probe", (r) => {
-      r.unmanagedTable(probeMeta, { reason: "plain store" });
-    });
-    expect(() => createRegistry([feat])).not.toThrow();
-  });
-});