@cosmicdrift/kumiko-framework 0.165.0 → 0.165.1

package/src/pipeline/event-dispatcher-delivery.ts

@@ -1,3 +1,7 @@
+// Value-only import, aliased to avoid shadowing the ambient global
+// `Temporal` TYPE that ConsumerStateRow.updatedAt/StoredEventRow.createdAt
+// resolve against (same #1438 dual-package-hazard pattern as event-store.ts).
+import { Temporal as TemporalPolyfill } from "temporal-polyfill";
 import { requestContext } from "../api/request-context";
 import type { DbConnection, DbTx } from "../db/connection";
 import {
@@ -111,8 +115,18 @@ export async function acquireConsumerState(
     // a prior re-arm) gates the retry; maxRearmCount stops a poison event
     // from looping forever (re-arm → same event fails → dead → re-arm →
     // ...) — after the cap it stays dead until a human intervenes.
-    const cooldownDeadline = Temporal.Now.instant().subtract({ milliseconds: rearmCooldownMs });
-    const cooldownElapsed = Temporal.Instant.compare(state.updatedAt, cooldownDeadline) <= 0;
+    const cooldownDeadline = TemporalPolyfill.Now.instant().subtract({
+      milliseconds: rearmCooldownMs,
+    });
+    // @cast-boundary temporal-polyfill-vs-ambient: same TC39 Temporal.Instant
+    // at runtime — state.updatedAt is DB-row-typed against the ambient
+    // global, two distinct nominal types across the two .d.ts sources (see
+    // event-store.ts).
+    const cooldownElapsed =
+      TemporalPolyfill.Instant.compare(
+        state.updatedAt as unknown as InstanceType<typeof TemporalPolyfill.Instant>,
+        cooldownDeadline,
+      ) <= 0;
     if (cooldownElapsed && state.rearmCount < maxRearmCount) {
       const rearmed = await rearmDeadConsumer(tx, name, instanceId);
       const rearmedState =
@@ -120,10 +134,10 @@ export async function acquireConsumerState(
         (coerceRow(rearmed, extractTableInfo(eventConsumerStateTable)) as ConsumerStateRow);
       if (rearmedState) return { state: rearmedState, skip: null };
     }
-    // ponytail: no log/metric fires when the rearm budget is exhausted here
-    // (the exact "braucht manuellen Eingriff" moment) — queryable via
-    // getConsumerState but silent otherwise. Add an emitDispatcherError-style
-    // signal if ops needs a push instead of a dead+lag poll.
+    // Caller (event-dispatcher.ts's processConsumer) emits
+    // kumiko_event_consumer_rearm_exhausted_total once per (consumer,
+    // instance) transition into this branch — it has the process-lifetime
+    // state to dedupe across poll passes that this pure function doesn't.
     return { state: null, skip: "dead" };
   }
   return { state, skip: null };

package/src/pipeline/event-dispatcher.ts

@@ -4,6 +4,7 @@ import { SYSTEM_TENANT_ID } from "../engine/types/identifiers";
 import { EVENTS_PUBSUB_CHANNEL, type StoredEvent } from "../event-store";
 import {
   emitEventConsumerPassOutcome,
+  emitEventConsumerRearmExhausted,
   emitEventDispatcherListenConnected,
   getFallbackMeter,
   getFallbackTracer,
@@ -201,6 +202,14 @@ export function createEventDispatcher(options: EventDispatcherOptions): EventDis
   }
   const tracer: Tracer = options.tracer ?? getFallbackTracer();
   const meter: Meter = options.meter ?? getFallbackMeter();
+  // Tracks which (consumer, instanceId) pairs already fired
+  // kumiko_event_consumer_rearm_exhausted_total, so a consumer stuck dead
+  // across many poll passes emits the ops-signal once, not every pass
+  // (that would be log/metric spam for a state that hasn't changed).
+  // Process-lifetime only — restarting the dispatcher re-arms reporting,
+  // which is fine: a fresh process re-observing a still-dead consumer is
+  // exactly the "still needs a human" signal ops wants.
+  const reportedDeadConsumers = new Set<string>();
 
   let running = false;
   // Separate from `running` on purpose: pre-registration of consumer state
@@ -304,8 +313,21 @@ export function createEventDispatcher(options: EventDispatcherOptions): EventDis
         // disabled/dead. Nothing to deliver this pass.
         if (acquired.skip !== null) {
           span.setAttribute("consumer.skip_reason", acquired.skip);
+          if (acquired.skip === "dead") {
+            const reportKey = `${consumer.name}:${instanceId}`;
+            if (!reportedDeadConsumers.has(reportKey)) {
+              reportedDeadConsumers.add(reportKey);
+              emitEventConsumerRearmExhausted(meter, { consumer: consumer.name, instanceId });
+            }
+          }
+          // skip: skip reason already recorded on the span above (and, for
+          // "dead", already emitted as a metric) — nothing left to deliver.
           return;
         }
+        // Acquired normally (including via a successful auto-rearm) — clear
+        // any prior dead-report so a future exhaustion re-emits instead of
+        // staying permanently suppressed by this process's Set.
+        reportedDeadConsumers.delete(`${consumer.name}:${instanceId}`);
 
         const events = await fetchPendingEvents(tx, acquired.state.lastProcessedEventId, batchSize);
         // skip: nothing to deliver — no markProcessing/persistConsumerOutcome write,

package/src/pipeline/index.ts

@@ -57,6 +57,8 @@ export {
 } from "./projection-state";
 export { runProjectionsForEvent } from "./projections-runner";
 export {
+  ACCESS_INVALIDATION_CONSUMER_NAME,
+  createAccessInvalidationEventConsumer,
   createSearchEventConsumer,
   createSseBroadcastEventConsumer,
   SEARCH_CONSUMER_NAME,

package/src/pipeline/system-hooks.ts

@@ -298,3 +298,90 @@ export function createJobTriggerEventConsumer(
     },
   };
 }
+
+// --- Access-Invalidation Consumer (async, via event-dispatcher) ---
+//
+// #1524 (Design), #1558 (channel + stream subscribe), #1559 (session-revoke
+// emits an event). This consumer is the last leg: it watches for the two
+// event types that can make an already-issued JWT stale mid-stream and
+// pushes an invalidation through sseBroker.publishAccessInvalidation, which
+// dispatch-stream.ts's subscribeAccessInvalidation listener turns into an
+// AccessDeniedError thrown into the open stream.
+//
+// Event types are literal strings, not imports — this package (framework)
+// cannot depend on bundled-features (sessions, tenant own these events),
+// mirrors the es-ops-seed precedent (literal QNs, no subpath import).
+//
+//   "sessions:event:session-revoked" — payload.userId direct (own aggregate,
+//     see bundled-features/sessions/session-revoked-event.ts). Fired for
+//     both self-service revoke and the privileged cross-tenant
+//     revoke-all-for-user (SYSTEM_TENANT_ID-anchored DSGVO Art.18 freeze).
+//     fetchPendingEvents has no tenant predicate, so the SYSTEM_TENANT_ID-
+//     anchored event reaches this consumer the same as any other — routing
+//     is purely on payload.userId, never on event.tenantId.
+//   "tenant-membership.updated" / "tenant-membership.deleted" — role change
+//     or member removal. userId isn't in payload.changes (update only
+//     carries the changed fields, e.g. { roles }) so it's read from
+//     payload.previous, the full pre-write entity snapshot written by
+//     createEventStoreExecutor. tenantMembershipEntity declares no
+//     encrypted/PII fields, so previous.userId is plaintext — no KMS
+//     decrypt step (see kumiko-framework#1560 PR discussion; the issue's
+//     original handoff assumed encryption that doesn't apply here).
+//
+// Over-invalidation (e.g. tenant-membership.updated fired by something
+// other than a role change) is fail-safe: the stream closes, the client
+// reconnects and re-authorizes. No opt-out/allowlist — #1524 chose
+// global-by-default specifically so this can't be silently disabled per
+// handler.
+//
+// Scope note: entityEventName also emits "tenant-membership.forgotten" (DSGVO
+// erasure) and ".restored" — .restored re-grants access so ignoring it is
+// correct, .forgotten is not currently produced by any user-data-rights
+// pipeline for memberships but would be revocation-relevant if it ever is.
+// Out of #1560's stated scope (session-revoke + role/membership change),
+// tracked rather than handled speculatively here.
+export const ACCESS_INVALIDATION_CONSUMER_NAME = "system:consumer:access-invalidation";
+
+const SESSION_REVOKED_EVENT_TYPE = "sessions:event:session-revoked";
+const TENANT_MEMBERSHIP_UPDATED_EVENT_TYPE = "tenant-membership.updated";
+const TENANT_MEMBERSHIP_DELETED_EVENT_TYPE = "tenant-membership.deleted";
+
+function readUserIdFromPreviousSnapshot(payload: Record<string, unknown>): string | undefined {
+  const previous = payload["previous"];
+  if (typeof previous !== "object" || previous === null) return undefined;
+  const userId = (previous as Record<string, unknown>)["userId"];
+  return typeof userId === "string" && userId.length > 0 ? userId : undefined;
+}
+
+export function createAccessInvalidationEventConsumer(sseBroker: SseBroker): EventConsumer {
+  return {
+    name: ACCESS_INVALIDATION_CONSUMER_NAME,
+    // Per-instance, same reasoning as SSE broadcast: subscribeAccessInvalidation
+    // listeners live in this process's in-memory sseBroker only. A shared
+    // cursor would deliver the event to exactly one instance and leave
+    // every other instance's open streams for that user un-invalidated.
+    delivery: "per-instance",
+    handler: async (event) => {
+      if (event.type === SESSION_REVOKED_EVENT_TYPE) {
+        const userId = event.payload["userId"];
+        // skip: malformed session-revoked payload — fail open on this one
+        // event rather than dead-lettering the whole consumer (halt-on-
+        // poison would otherwise permanently stop access-invalidation for
+        // every user behind one bad row).
+        if (typeof userId !== "string" || userId.length === 0) return;
+        sseBroker.publishAccessInvalidation(userId);
+      }
+
+      if (
+        event.type === TENANT_MEMBERSHIP_UPDATED_EVENT_TYPE ||
+        event.type === TENANT_MEMBERSHIP_DELETED_EVENT_TYPE
+      ) {
+        const userId = readUserIdFromPreviousSnapshot(event.payload);
+        // skip: previous snapshot missing/malformed userId — same fail-open
+        // reasoning as above.
+        if (userId === undefined) return;
+        sseBroker.publishAccessInvalidation(userId);
+      }
+    },
+  };
+}

package/src/rate-limit/__tests__/resolver.integration.test.ts

@@ -169,6 +169,24 @@ describe("createRateLimitResolver — peek", () => {
   });
 });
 
+describe("createRateLimitResolver — kumiko-framework#1525: no ambient Temporal global", () => {
+  test("check() and peek() compute resetAt without relying on globalThis.Temporal", async () => {
+    const config = { limit: 5, windowSeconds: 60 };
+    const savedGlobal = (globalThis as { Temporal?: unknown }).Temporal;
+    delete (globalThis as { Temporal?: unknown }).Temporal;
+    try {
+      const checked = await resolver.check("no-ambient:user", config);
+      expect(checked.resetAt).toBeDefined();
+
+      const peeked = await resolver.peek("no-ambient:user", config);
+      expect(peeked.resetAt).toBeDefined();
+    } finally {
+      if (savedGlobal === undefined) delete (globalThis as { Temporal?: unknown }).Temporal;
+      else (globalThis as { Temporal?: unknown }).Temporal = savedGlobal;
+    }
+  });
+});
+
 describe("createRateLimitResolver — enforce", () => {
   test("enforce throws RateLimitError with the bucket details when blocked", async () => {
     const config = { limit: 1, windowSeconds: 60 };

package/src/rate-limit/resolver.ts

@@ -4,6 +4,10 @@ import type {
   RateLimitResolver,
 } from "@cosmicdrift/kumiko-types/rate-limit-types";
 import type Redis from "ioredis";
+// Value-only import, aliased to avoid shadowing the ambient global
+// `Temporal` TYPE that RateLimitDecision.resetAt resolves against (see
+// event-store.ts for the same #1438 dual-package-hazard pattern).
+import { Temporal as TemporalPolyfill } from "temporal-polyfill";
 import { RateLimitError } from "../errors";
 import { RedisKeys } from "../pipeline/redis-keys";
 
@@ -189,7 +193,7 @@ export function createRateLimitResolver(opts: RateLimitResolverOptions): RateLim
     );
 
     const retryAfterSeconds = Math.ceil(retryAfterMs / 1000);
-    const resetAt = Temporal.Instant.fromEpochMilliseconds(nowMs + retryAfterMs);
+    const resetAt = TemporalPolyfill.Instant.fromEpochMilliseconds(nowMs + retryAfterMs);
 
     return {
       allowed: allowedFlag === 1,
@@ -229,7 +233,7 @@ export function createRateLimitResolver(opts: RateLimitResolverOptions): RateLim
     );
 
     const retryAfterSeconds = Math.ceil(retryAfterMs / 1000);
-    const resetAt = Temporal.Instant.fromEpochMilliseconds(nowMs + retryAfterMs);
+    const resetAt = TemporalPolyfill.Instant.fromEpochMilliseconds(nowMs + retryAfterMs);
 
     return {
       // peek doesn't deduct, so a "would-be" allowed flag is meaningful:

package/src/schema-cli.ts

@@ -275,20 +275,32 @@ export async function runSchemaCli(
       // diff the reconstructed schema against .snapshot.json.
       const committedSnapshot = existsSync(snapshotPath) ? loadSnapshotJson(snapshotPath) : null;
       if (existsSync(migrationsDir) && committedSnapshot !== null) {
-        const replayed = replayMigrationsDir(migrationsDir);
-        const mismatches = diffReplayAgainstSnapshot(replayed, committedSnapshot);
-        if (mismatches.length === 0) {
-          out.log("  ✓ migrations: committed SQL matches .snapshot.json");
-        } else {
-          ok = false;
-          out.err(
-            "  ✗ migration-content drift: committed *.sql files don't produce .snapshot.json.",
-          );
-          for (const m of mismatches) {
-            out.err(`    ${m.tableName} (${m.kind}): ${m.detail}`);
+        try {
+          const replayed = replayMigrationsDir(migrationsDir);
+          const mismatches = diffReplayAgainstSnapshot(replayed, committedSnapshot);
+          if (mismatches.length === 0) {
+            out.log("  ✓ migrations: table/column names match .snapshot.json");
+          } else {
+            ok = false;
+            out.err(
+              "  ✗ migration-content drift: committed *.sql files don't produce .snapshot.json.",
+            );
+            for (const m of mismatches) {
+              out.err(`    ${m.tableName} (${m.kind}): ${m.detail}`);
+            }
+            out.err(
+              "    Fix: a migration file's body doesn't match what it (or the snapshot) claims — hand-fix the file, or ship a corrective migration if it's already applied in prod.",
+            );
           }
+        } catch (e) {
+          // replayMigrationsDir fail-loud's on a table-DDL statement it can't
+          // parse — that must surface as a normal ✗ line like every other
+          // check here, not a raw stack trace that kills the process before
+          // any later check (or the Fix: help) ever runs (framework#1535).
+          ok = false;
+          out.err(`  ✗ migration-content: ${e instanceof Error ? e.message : String(e)}`);
           out.err(
-            "    Fix: a migration file's body doesn't match what it (or the snapshot) claims — hand-fix the file, or ship a corrective migration if it's already applied in prod.",
+            "    Fix: a statement in a migration file isn't recognizable to the replay parser — extend the parser's recognized patterns, or reword the migration to one it understands.",
           );
         }
       }

package/src/search/__tests__/reindex-entity.integration.test.ts

@@ -6,6 +6,7 @@
 
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
 import {
+  asRawClient,
   buildEntityTable,
   createEventStoreExecutor,
   createTenantDb,
@@ -111,11 +112,33 @@ describe("reindexEntity", () => {
       admin.tenantId,
       { dryRun: true },
     );
-    expect(result.indexedRows).toBeGreaterThan(0);
+    expect(result.indexedRows).toBe(0);
+    expect(result.wouldIndexRows).toBeGreaterThan(0);
 
     const postResults = await stack.search.search(admin.tenantId, "dryrun", {
       filterType: "widget",
     });
     expect(postResults).toHaveLength(0);
   });
+
+  // kumiko-framework#1549: a searchable field with no matching read-table
+  // column (dropped/never-migrated) used to push one identical failures[]
+  // entry per scanned row instead of failing fast — fails loud on the first
+  // row's column set instead, which is invariant across the whole scan.
+  test("throws immediately when a searchable field has no matching column, without scanning every row", async () => {
+    const executor = seedExecutor();
+    await executor.create({ name: "Row A" }, admin, tenantDb());
+    await executor.create({ name: "Row B" }, admin, tenantDb());
+
+    await asRawClient(stack.db).unsafe(`ALTER TABLE "read_reindex_widgets" DROP COLUMN "name"`);
+    try {
+      await expect(
+        reindexEntity(stack.db, stack.registry, stack.search, "widget", admin.tenantId),
+      ).rejects.toThrow(/searchable field "name" is not mappable/);
+    } finally {
+      await asRawClient(stack.db).unsafe(
+        `ALTER TABLE "read_reindex_widgets" ADD COLUMN "name" text`,
+      );
+    }
+  });
 });

package/src/search/reindex-entity.ts

@@ -21,6 +21,9 @@ export type ReindexEntityFailure = {
 export type ReindexEntityResult = {
   readonly scannedRows: number;
   readonly indexedRows: number;
+  // Only nonzero in a dry run — docs that would have been indexed. In a
+  // real run indexedRows already counts these; wouldIndexRows stays 0.
+  readonly wouldIndexRows: number;
   readonly failures: readonly ReindexEntityFailure[];
 };
 
@@ -82,9 +85,23 @@ export async function reindexEntity(
   const deletedFilter =
     entity.softDelete === true ? `AND ${quoteIdent("is_deleted")} IS NOT TRUE` : "";
 
-  const result = { scannedRows: 0, indexedRows: 0, failures: [] as ReindexEntityFailure[] };
+  const result = {
+    scannedRows: 0,
+    indexedRows: 0,
+    wouldIndexRows: 0,
+    failures: [] as ReindexEntityFailure[],
+  };
 
   let offset = 0;
+  // Whether a searchable field lacks a matching read-table column depends
+  // only on the table's column set (rowToState/Object.hasOwn), not on any
+  // particular row's data — every row from the same SELECT * has the same
+  // columns. Check once against the first row instead of every row, so a
+  // dropped/never-migrated column fails fast with one clear error instead
+  // of one identical failures[] entry per scanned row (1M rows → 1M
+  // entries, and the real schema problem is buried in "x failed").
+  let uncheckedSchema = true;
+
   for (;;) {
     // ponytail: LIMIT/OFFSET, not a keyset cursor — id can be uuid or
     // serial depending on the entity, and a uniform cursor comparison
@@ -101,6 +118,18 @@ export async function reindexEntity(
     );
     if (rows.length === 0) break;
 
+    if (uncheckedSchema) {
+      uncheckedSchema = false;
+      const sampleState = rowToState(rows[0] as Record<string, unknown>, fieldNames);
+      const unmappedField = searchableFields.find((fieldName) => !(fieldName in sampleState));
+      if (unmappedField !== undefined) {
+        throw new Error(
+          `reindexEntity: searchable field "${unmappedField}" is not mappable from read-table ` +
+            `column ${quoteIdent(tableName)} — likely a dropped/never-migrated column.`,
+        );
+      }
+    }
+
     const docs: Array<{ entityId: string; doc: SearchDocument }> = [];
     for (const row of rows) {
       result.scannedRows++;
@@ -137,7 +166,7 @@ export async function reindexEntity(
         }
       }
     } else if (options.dryRun) {
-      result.indexedRows += docs.length;
+      result.wouldIndexRows += docs.length;
     }
 
     offset += rows.length;

package/src/search/types.ts

@@ -1 +1 @@
-export * from "@cosmicdrift/kumiko-types/search-adapter";
+export type * from "@cosmicdrift/kumiko-types/search-adapter";

package/src/stack/__tests__/setup-test-stack-jobs.integration.test.ts

@@ -99,7 +99,7 @@ describe("setupTestStack({ jobs }) wires ctx.jobRunner for manual dispatch", ()
 });
 
 describe("setupTestStack({ jobs }) job context matches the request-path context", () => {
-  test("job handler's context carries tracer + searchAdapter + effectiveFeatures, not a reduced literal", async () => {
+  test("job handler's context carries tracer + searchAdapter, mirrors prod's effectiveFeatures-less job context", async () => {
     jobContextFields.length = 0;
     stack = await setupTestStack({
       features: [jobContextFeature],
@@ -112,10 +112,14 @@ describe("setupTestStack({ jobs }) job context matches the request-path context"
     await waitFor(() => {
       expect(jobContextFields.length).toBeGreaterThan(0);
     });
+    // #1255: effectiveFeatures deliberately stays OUT of the job/appContext
+    // (prod only carries it in dispatcherOptions.effectiveFeatures, consumed
+    // by the command-dispatcher) — putting it here would let a job read
+    // `ctx.effectiveFeatures` green in tests and break on deploy.
     expect(jobContextFields[0]).toEqual({
       hasTracer: true,
       hasSearchAdapter: true,
-      hasEffectiveFeatures: true,
+      hasEffectiveFeatures: false,
     });
   });
 });

package/src/stack/db.ts

@@ -2,6 +2,7 @@
 // Provider-agnostic via createConnection (DB_PROVIDER env).
 // postgres-js = default. DB_PROVIDER=bun = Bun.SQL (experimentell).
 
+import type { DbConnection } from "@cosmicdrift/kumiko-types/db-connection";
 import { createConnection } from "../db/api";
 import { createDatabase, databaseExists, dropDatabaseIfExists } from "../db/queries/test-stack";
 import { ensureTemporalPolyfill } from "../time/polyfill";
@@ -18,7 +19,7 @@ function requireEnv(name: string): string {
 }
 
 export type TestDb = {
-  db: unknown;
+  db: DbConnection;
   client: unknown;
   dbName: string;
   cleanup: () => Promise<void>;

package/src/stack/push-entity-projection-tables.ts

@@ -1,3 +1,4 @@
+import { KUMIKO_NAME_SYMBOL } from "@cosmicdrift/kumiko-types/schema-table-types";
 import { tableExists } from "../db/schema-inspection";
 import type { Registry } from "../engine/types";
 import { unsafePushTables } from "./table-helpers";
@@ -35,7 +36,7 @@ export async function pushEntityProjectionTables(
     if (seen.has(proj.table)) continue;
     seen.add(proj.table);
     const tableRec = proj.table as unknown as Record<symbol, unknown>;
-    const physical = tableRec[Symbol.for("kumiko:schema:Name")] as string;
+    const physical = tableRec[KUMIKO_NAME_SYMBOL] as string;
     if (await tableExists(stack.db, `public.${physical}`)) {
       logInfo(`[kumiko-stack] table ${physical} already exists — skipping create`);
       continue;

package/src/stack/request-helper.ts

@@ -111,10 +111,29 @@ export function createRequestHelper(
   jwt: JwtHelper,
   options: RequestHelperOptions = {},
 ): RequestHelper {
+  // sid per (user.id, tenantId), not one mint per authHeader() call:
+  // sessionCreator opens a live session row, so an unmemoized call mints a
+  // fresh one on every request a test makes for the same user — tests
+  // asserting on session counts / massRevoker / revokeAllOthers behavior
+  // then see extra live sids that have nothing to do with what they're
+  // testing. Keyed on tenantId too — the same user.id can hold sessions in
+  // more than one tenant, and sessionCreator writes the row scoped to
+  // `user.tenantId` (session-callbacks.ts), so a user.id-only key would
+  // hand a cross-tenant test its wrong tenant's sid.
+  // Cache the Promise (not the settled sid) so two concurrent authHeader
+  // calls for the same key share one mint instead of racing on a miss.
+  const sidByUserKey = new Map<string, Promise<string>>();
+
   async function authHeader(user: SessionUser): Promise<Record<string, string>> {
     let forJwt = user;
     if (options.sessionCreator && !user.sid) {
-      const sid = await options.sessionCreator(user, { ip: "test", userAgent: "request-helper" });
+      const key = `${user.id}:${user.tenantId}`;
+      let sidPromise = sidByUserKey.get(key);
+      if (sidPromise === undefined) {
+        sidPromise = options.sessionCreator(user, { ip: "test", userAgent: "request-helper" });
+        sidByUserKey.set(key, sidPromise);
+      }
+      const sid = await sidPromise;
       forJwt = { ...user, sid };
     }
     const token = await jwt.sign(forJwt);

package/src/stack/table-helpers.ts

@@ -1,3 +1,7 @@
+import {
+  KUMIKO_META_SYMBOL,
+  KUMIKO_NAME_SYMBOL,
+} from "@cosmicdrift/kumiko-types/schema-table-types";
 import type { DbConnection } from "../db/connection";
 import { pgTypeToSqlType } from "../db/dialect";
 import type { ColumnMeta, EntityTableMeta } from "../db/entity-table-meta";
@@ -5,15 +9,13 @@ import {
   alterTableAddColumn,
   createIndexIfNotExists,
   executeDdlStatement,
-  truncateTablesRestartIdentity,
-} from "../db/queries/test-stack";
+} from "../db/queries/ddl";
+import { truncateTablesRestartIdentity } from "../db/queries/test-stack";
 import { renderTableDdl } from "../db/render-ddl";
 import { tableExists } from "../db/schema-inspection";
 import { buildEntityTable, toTableName } from "../db/table-builder";
 import type { EventDispatcher } from "../pipeline";
 
-const KUMIKO_NAME_SYMBOL = Symbol.for("kumiko:schema:Name");
-const KUMIKO_META_SYMBOL = Symbol.for("kumiko:schema:Meta");
 function tableNameOf(table: unknown): string {
   if (typeof table !== "object" || table === null) {
     throw new Error("table-helpers: table is not a SchemaTable object");

package/src/stack/test-stack.ts

@@ -2,7 +2,7 @@ import type { Hono } from "hono";
 import type { AuthRoutesConfig } from "../api/auth-routes";
 import type { JwtHelper } from "../api/jwt";
 import { buildServer } from "../api/server";
-import { createSseBroker } from "../api/sse-broker";
+import { createSseBroker, type SseBroker } from "../api/sse-broker";
 import type { PgClient } from "../db/connection";
 import { extractTableInfo } from "../db/query";
 import { createRegistry } from "../engine/registry";
@@ -25,13 +25,17 @@ export type TestStack = {
   app: Hono;
   jwt: JwtHelper;
   registry: Registry;
-  // biome-ignore lint/suspicious/noExplicitAny: cross-provider connection
-  db: any;
+  db: import("../db").DbConnection;
   redis: TestRedis;
   search: SearchAdapter;
   events: EventCollector;
   http: RequestHelper;
   observability: ObservabilityProvider;
+  // In-memory broker backing the server's SSE routes + access-invalidation
+  // channel. Tests subscribe directly (e.g. sseBroker.subscribeAccessInvalidation)
+  // to assert a consumer pushed an invalidation without opening a real SSE
+  // connection.
+  sseBroker: SseBroker;
   // Command-dispatcher behind the HTTP routes — for direct system-writes
   // in tests and dev-server extraRoutes (provider-webhook wiring).
   dispatcher: Dispatcher;
@@ -66,8 +70,7 @@ export type TestStackOptions = {
     | Record<string, unknown>
     | ((deps: {
         registry: Registry;
-        // biome-ignore lint/suspicious/noExplicitAny: cross-provider connection
-        db: any;
+        db: import("../db").DbConnection;
         sseBroker: import("../api/sse-broker").SseBroker;
         redis: import("ioredis").default;
       }) => Record<string, unknown>);
@@ -119,8 +122,7 @@ export type TestStackOptions = {
     | import("../api/server").ServerOptions["anonymousAccess"]
     | ((deps: {
         registry: Registry;
-        // biome-ignore lint/suspicious/noExplicitAny: cross-provider connection
-        db: any;
+        db: import("../db").DbConnection;
         sseBroker: import("../api/sse-broker").SseBroker;
         redis: import("ioredis").default;
       }) => import("../api/server").ServerOptions["anonymousAccess"]);
@@ -130,8 +132,7 @@ export type TestStackOptions = {
     base: import("../api/server").ServerOptions["anonymousAccess"] | undefined,
     deps: {
       registry: Registry;
-      // biome-ignore lint/suspicious/noExplicitAny: cross-provider connection
-      db: any;
+      db: import("../db").DbConnection;
     },
   ) => Promise<import("../api/server").ServerOptions["anonymousAccess"] | undefined>;
   /** Opt-in JobRunner wired into ctx.jobRunner and merged into
@@ -268,11 +269,12 @@ export async function setupTestStack(options: TestStackOptions): Promise<TestSta
   // (kumiko-framework#1232: a reduced `{ db, registry }` literal let jobs
   // pass in tests while reaching for fields only prod's context has).
   //
-  // effectiveFeatures is included per the issue's explicit ask, even though
-  // prod's job context never gets it today (only dispatcherOptions.
-  // effectiveFeatures, consumed by the command-dispatcher — see
-  // buildJobRunnerWithHook in entrypoint/index.ts). Tracked as a real prod
-  // gap in a follow-up issue rather than silently matched here.
+  // effectiveFeatures deliberately stays OUT of appContext — prod never puts
+  // it there either (only dispatcherOptions.effectiveFeatures, consumed by
+  // the command-dispatcher — see buildJobRunnerWithHook in entrypoint/
+  // index.ts). Putting it here would reintroduce the exact test-vs-prod
+  // drift #1232 fixed: a job/handler reading `ctx.effectiveFeatures` would
+  // pass in tests and break in prod (kumiko-framework#1255).
   const appContext = {
     db: testDb.db,
     redis: testRedis.redis,
@@ -281,7 +283,6 @@ export async function setupTestStack(options: TestStackOptions): Promise<TestSta
     registry,
     ...(options.masterKeyProvider ? { masterKeyProvider: options.masterKeyProvider } : {}),
     ...(fileProviderResolver ? { _fileProviderResolver: fileProviderResolver } : {}),
-    ...(options.effectiveFeatures ? { effectiveFeatures: options.effectiveFeatures } : {}),
     ...(typeof options.extraContext === "function"
       ? options.extraContext({ registry, db: testDb.db, sseBroker, redis: testRedis.redis })
       : options.extraContext),
@@ -377,6 +378,7 @@ export async function setupTestStack(options: TestStackOptions): Promise<TestSta
         systemConsumers: {
           sse: enabledHooks.includes("sse"),
           search: enabledHooks.includes("search"),
+          accessInvalidation: enabledHooks.includes("sse"),
         },
       },
       // Default tests to no login rate-limiter so existing suites that loop
@@ -437,6 +439,7 @@ export async function setupTestStack(options: TestStackOptions): Promise<TestSta
       events,
       http,
       observability: server.observability,
+      sseBroker,
       dispatcher: server.dispatcher,
       ...(eventDispatcher ? { eventDispatcher } : {}),
       ...(server.lifecycle ? { lifecycle: server.lifecycle } : {}),

package/src/testing/__tests__/late-bound.test.ts

@@ -22,4 +22,11 @@ describe("createLateBoundHolder", () => {
     holder.set("second");
     expect(holder.get()).toBe("second");
   });
+
+  test("set(undefined) still marks the holder ready", () => {
+    const holder = createLateBoundHolder<number | undefined>("opt");
+    holder.set(undefined);
+    expect(holder.isReady()).toBe(true);
+    expect(holder.get()).toBeUndefined();
+  });
 });

package/src/testing/__tests__/wait-for.test.ts

@@ -39,6 +39,12 @@ describe("waitFor", () => {
     expect(calls).toBe(2);
   });
 
+  test("throws a descriptive error for an empty delay schedule", async () => {
+    await expect(waitFor(() => {}, { delays: [] })).rejects.toThrow(
+      "waitFor: empty delay schedule",
+    );
+  });
+
   test("supports an async fn", async () => {
     let calls = 0;
     await waitFor(