@cosmicdrift/kumiko-framework 0.328.0 → 0.328.1

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

@@ -1,185 +0,0 @@
-// Drives the manual `ctx.jobRunner.dispatch(...)` path a write handler
-// uses directly — distinct from the auto-trigger path covered by
-// entrypoint-job-wiring.integration.test.ts, which reads a different
-// context slot and isn't guaranteed by this test passing.
-
-import { afterEach, describe, expect, test } from "bun:test";
-import * as z from "zod";
-import { defineFeature } from "../../engine";
-import { InternalError, writeFailure } from "../../errors";
-import { waitFor } from "../../testing";
-import { generateId } from "../../utils";
-import { setupTestStack, type TestStack } from "../test-stack";
-import { TestUsers } from "../test-users";
-
-const jobRuns: Array<{ name: string; payload: Record<string, unknown> }> = [];
-
-const manualDispatchFeature = defineFeature("manualdispatch", (r) => {
-  r.writeHandler(
-    "create",
-    z.object({ note: z.string() }),
-    async (event, ctx) => {
-      // Exact repro from #983: bracket-access, dynamic context extension —
-      // not a typed HandlerContext field (mirrors trigger.write.ts).
-      const jobRunner = ctx["jobRunner"] as
-        | { dispatch: (name: string, payload: Record<string, unknown>) => Promise<string> }
-        | undefined;
-      if (!jobRunner) {
-        return writeFailure(new InternalError({ message: "no jobRunner on ctx" }));
-      }
-      await jobRunner.dispatch("manualdispatch:job:record", { note: event.payload.note });
-      return { isSuccess: true as const, data: { id: 1, note: event.payload.note } };
-    },
-    { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
-  );
-  r.job("record", { trigger: { manual: true }, runIn: "worker" }, async (payload) => {
-    jobRuns.push({ name: "manualdispatch:job:record", payload });
-  });
-});
-
-// kumiko-framework#1232: setupTestStack used to hand jobs a bare
-// `{ db, registry }` context literal — nothing else buildServer's request
-// path gets (tracer/meter, searchAdapter, ...). A job could pass in tests
-// while reading a field only prod's context has, then break silently on
-// deploy. This job records which fields actually arrived.
-const jobContextFields: Array<{
-  hasTracer: boolean;
-  hasSearchAdapter: boolean;
-  hasEffectiveFeatures: boolean;
-}> = [];
-
-const jobContextFeature = defineFeature("jobcontextcheck", (r) => {
-  r.job("record", { trigger: { manual: true }, runIn: "worker" }, async (_payload, context) => {
-    jobContextFields.push({
-      hasTracer: context.tracer !== undefined,
-      hasSearchAdapter: context.searchAdapter !== undefined,
-      hasEffectiveFeatures: context.effectiveFeatures !== undefined,
-    });
-  });
-});
-
-const laneIsolationRuns: Array<{ from: unknown }> = [];
-
-const laneIsolationFeature = defineFeature("laneisolation", (r) => {
-  r.job("record", { trigger: { manual: true }, runIn: "worker" }, async (payload) => {
-    laneIsolationRuns.push({ from: payload["from"] });
-  });
-});
-
-let stack: TestStack | undefined;
-let secondStack: TestStack | undefined;
-
-afterEach(async () => {
-  if (stack) await stack.cleanup();
-  if (secondStack) await secondStack.cleanup();
-  stack = undefined;
-  secondStack = undefined;
-});
-
-describe("setupTestStack({ jobs }) wires ctx.jobRunner for manual dispatch", () => {
-  test("write handler's ctx.jobRunner.dispatch(...) works end-to-end", async () => {
-    jobRuns.length = 0;
-    stack = await setupTestStack({
-      features: [manualDispatchFeature],
-      // consumerLane: this test has no separate consumer (unlike runDevApp's
-      // startDevJobRunners), so it must be the one running the job.
-      jobs: { consumerLane: "worker" },
-    });
-
-    await stack.http.writeOk("manualdispatch:write:create", { note: "hi" }, TestUsers.admin);
-
-    await waitFor(() => {
-      const run = jobRuns.find((e) => e.name === "manualdispatch:job:record");
-      expect(run).toBeDefined();
-      expect(run?.payload["note"]).toBe("hi");
-    });
-  });
-
-  test("without `jobs` opt-in, ctx.jobRunner stays undefined (no-op, not a throw)", async () => {
-    stack = await setupTestStack({ features: [manualDispatchFeature] });
-    expect(stack.jobRunner).toBeUndefined();
-
-    // The handler itself guards against a missing jobRunner (writeFailure,
-    // not a thrown TypeError) — same contract as trigger.write.ts's cast.
-    const err = await stack.http.writeErr(
-      "manualdispatch:write:create",
-      { note: "hi" },
-      TestUsers.admin,
-    );
-    expect(err.code).toBe("internal_error");
-  });
-});
-
-// Stack "api" consumes only the api lane, so its worker-lane job can only run
-// if the "worker" stack's consumer reads the same queue.
-describe("setupTestStack({ jobs }) queue isolation between parallel stacks", () => {
-  async function dispatchFromApiStackThenRunOwnJob(): Promise<void> {
-    await stack?.jobRunner?.dispatch("laneisolation:job:record", { from: "api-stack" });
-    await secondStack?.jobRunner?.dispatch("laneisolation:job:record", { from: "worker-stack" });
-    await waitFor(() => {
-      expect(laneIsolationRuns.some((run) => run.from === "worker-stack")).toBe(true);
-    });
-  }
-
-  test("without an explicit queueNamePrefix, one stack's consumer never runs another stack's job", async () => {
-    laneIsolationRuns.length = 0;
-    [stack, secondStack] = await Promise.all([
-      setupTestStack({ features: [laneIsolationFeature], jobs: { consumerLane: "api" } }),
-      setupTestStack({ features: [laneIsolationFeature], jobs: { consumerLane: "worker" } }),
-    ]);
-
-    await dispatchFromApiStackThenRunOwnJob();
-
-    expect(laneIsolationRuns.map((run) => run.from)).toEqual(["worker-stack"]);
-  });
-
-  test("an explicit shared queueNamePrefix wins, so both stacks read one queue", async () => {
-    laneIsolationRuns.length = 0;
-    const queueNamePrefix = `laneisolation-shared-${generateId()}`;
-    [stack, secondStack] = await Promise.all([
-      setupTestStack({
-        features: [laneIsolationFeature],
-        jobs: { consumerLane: "api", queueNamePrefix },
-      }),
-      setupTestStack({
-        features: [laneIsolationFeature],
-        jobs: { consumerLane: "worker", queueNamePrefix },
-      }),
-    ]);
-
-    await dispatchFromApiStackThenRunOwnJob();
-
-    await waitFor(() => {
-      expect(laneIsolationRuns.map((run) => run.from).sort()).toEqual([
-        "api-stack",
-        "worker-stack",
-      ]);
-    });
-  });
-});
-
-describe("setupTestStack({ jobs }) job context matches the request-path context", () => {
-  test("job handler's context carries tracer + searchAdapter, mirrors prod's effectiveFeatures-less job context", async () => {
-    jobContextFields.length = 0;
-    stack = await setupTestStack({
-      features: [jobContextFeature],
-      jobs: { consumerLane: "worker" },
-      effectiveFeatures: () => new Set(["jobcontextcheck"]),
-    });
-
-    await stack.jobRunner?.dispatch("jobcontextcheck:job:record");
-
-    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: false,
-    });
-  });
-});

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

@@ -1,79 +0,0 @@
-import { afterEach, describe, expect, test } from "bun:test";
-import * as z from "zod";
-import { defineFeature } from "../../engine";
-import { resolveObservabilityWiring } from "../../observability/metrics-wiring";
-import { setupTestStack, type TestStack } from "../test-stack";
-import { TestUsers } from "../test-users";
-
-const METRICS_TOKEN = "setup-test-stack-metrics-token-minimum-32-chars!!";
-
-const pingFeature = defineFeature("stmetrics", (r) => {
-  r.writeHandler(
-    "ping",
-    z.object({}),
-    async () => ({ isSuccess: true as const, data: { ok: true } }),
-    { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
-  );
-});
-
-let stack: TestStack | undefined;
-
-afterEach(async () => {
-  await stack?.cleanup();
-  stack = undefined;
-});
-
-describe("setupTestStack metrics option (integration)", () => {
-  test("mirrors runProdApp wiring: /metrics scrapes after a real request, token-gated", async () => {
-    stack = await setupTestStack({
-      features: [pingFeature],
-      ...resolveObservabilityWiring(METRICS_TOKEN),
-    });
-
-    // kumiko_http_requests_total is only recorded by the http middleware, so scrape after a real request.
-    await stack.http.command("stmetrics:write:ping", {}, TestUsers.admin);
-
-    const noAuth = await stack.app.request("/metrics");
-    expect(noAuth.status).toBe(401);
-
-    const wrongToken = await stack.app.request("/metrics", {
-      headers: { Authorization: "Bearer wrong-token" },
-    });
-    expect(wrongToken.status).toBe(401);
-
-    const scraped = await stack.app.request("/metrics", {
-      headers: { Authorization: `Bearer ${METRICS_TOKEN}` },
-    });
-    expect(scraped.status).toBe(200);
-    expect(scraped.headers.get("Content-Type")).toMatch(/openmetrics-text/);
-    const body = await scraped.text();
-    expect(body).toMatch(/kumiko_http_requests_total\{[^}]*route="\/api\/command"[^}]*\} 1/);
-  });
-
-  test("no metrics option: /metrics is unmounted (404)", async () => {
-    stack = await setupTestStack({ features: [pingFeature] });
-
-    const res = await stack.app.request("/metrics");
-    expect(res.status).toBe(404);
-  });
-
-  test("custom path override: mounts only at the overridden path", async () => {
-    const wiring = resolveObservabilityWiring(METRICS_TOKEN);
-    if (!("metrics" in wiring)) throw new Error("resolveObservabilityWiring did not wire metrics");
-
-    stack = await setupTestStack({
-      features: [pingFeature],
-      ...wiring,
-      metrics: { ...wiring.metrics, path: "/internal/metrics" },
-    });
-
-    const atDefault = await stack.app.request("/metrics");
-    expect(atDefault.status).toBe(404);
-
-    const atCustom = await stack.app.request("/internal/metrics", {
-      headers: { Authorization: `Bearer ${METRICS_TOKEN}` },
-    });
-    expect(atCustom.status).toBe(200);
-    expect(atCustom.headers.get("Content-Type")).toMatch(/openmetrics-text/);
-  });
-});

package/src/stack/db.ts

@@ -1,82 +0,0 @@
-// Test-DB Factory: CREATE DATABASE → connect → createEventsTable.
-// 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";
-import { generateId } from "../utils";
-
-function requireEnv(name: string): string {
-  const value = process.env[name];
-  if (!value) {
-    throw new Error(
-      `Missing required env var: ${name}. Copy .env.example to .env and fill in values. Tests also need the test services (Postgres, Redis) running, e.g. "docker compose up -d".`,
-    );
-  }
-  return value;
-}
-
-export type TestDb = {
-  db: DbConnection;
-  client: unknown;
-  dbName: string;
-  cleanup: () => Promise<void>;
-};
-
-export type CreateTestDbOptions = {
-  readonly baseUrl?: string;
-  readonly dbName?: string;
-  readonly persistent?: boolean;
-};
-
-/**
- * Provider-agnostische Test-DB. createConnection liest DB_PROVIDER.
- * Für Bun.SQL: DB_PROVIDER=bun setzen (experimentell — siehe db/bun-provider.ts).
- */
-export async function createTestDb(arg?: string | CreateTestDbOptions): Promise<TestDb> {
-  await ensureTemporalPolyfill();
-  const opts: CreateTestDbOptions = typeof arg === "string" ? { baseUrl: arg } : (arg ?? {});
-  const url = opts.baseUrl ?? requireEnv("TEST_DATABASE_URL");
-  const dbName = opts.dbName ?? `kumiko_test_${generateId().slice(-8)}`;
-  const adminUrl = url.replace(/\/[^/]+$/, "/postgres");
-
-  const admin = await createConnection(adminUrl, { maxConnections: 1 });
-  try {
-    if (opts.persistent) {
-      if (!(await databaseExists(admin.db, dbName))) {
-        await createDatabase(admin.db, dbName);
-      }
-    } else {
-      await createDatabase(admin.db, dbName);
-    }
-  } finally {
-    await admin.close();
-  }
-
-  const testUrl = url.replace(/\/[^/]+$/, `/${dbName}`);
-  const conn = await createConnection(testUrl);
-
-  const { createEventsTable } = await import("../event-store");
-  await createEventsTable(conn.db);
-
-  return {
-    db: conn.db,
-    client: conn.client,
-    dbName,
-    cleanup: async () => {
-      await conn.close();
-      if (!opts.persistent) {
-        const admin2 = await createConnection(adminUrl, { maxConnections: 1 });
-        try {
-          await dropDatabaseIfExists(admin2.db, dbName);
-        } finally {
-          await admin2.close();
-        }
-      }
-    },
-  };
-}
-
-export { requireEnv };

package/src/stack/drain-event-consumers.ts

@@ -1,74 +0,0 @@
-import type { DbConnection } from "../db";
-import { getEventsHighWaterMark } from "../event-store";
-import { type ConsumerRecoveryState, getConsumerState } from "../pipeline";
-import type { TestStack } from "./test-stack";
-
-const DEFAULT_MAX_PASSES = 25;
-
-// Drives eventDispatcher.runOnce() until every named consumer has caught up
-// to the events high-water mark captured at call time. No "no progress ⇒
-// throw" shortcut: a pass can legitimately advance zero cursors even though
-// work remains — runOnce's FOR UPDATE SKIP LOCKED lets a concurrent pass
-// (the test stack's own 50ms poll timer) hold a consumer's row, and a
-// consumer coming off a thrown-pass backoff sits idle until its retryAtMs
-// elapses. A bounded pass budget tolerates both without pretending to detect
-// "stuck" from a single empty pass. The target is a snapshot: events a
-// consumer's own handler writes afterward (cascades) are not waited on.
-export async function drainEventConsumers(
-  stack: Pick<TestStack, "db" | "eventDispatcher">,
-  consumerNames: readonly [string, ...string[]],
-  options?: { readonly maxPasses?: number },
-): Promise<void> {
-  const { db, eventDispatcher } = stack;
-  if (!eventDispatcher) {
-    throw new Error(
-      "drainEventConsumers: stack.eventDispatcher is undefined — no system consumer or " +
-        "multiStreamProjection is wired for this stack.",
-    );
-  }
-  const maxPasses = options?.maxPasses ?? DEFAULT_MAX_PASSES;
-  const target = await getEventsHighWaterMark(db);
-
-  for (let pass = 0; pass < maxPasses; pass++) {
-    await eventDispatcher.runOnce();
-    const states = await loadConsumerStates(db, consumerNames);
-    // skip: every named consumer has already caught up to the target snapshot — the
-    // remaining budgeted passes are unnecessary, not a swallowed error.
-    if (states.every((state) => state.lastProcessedEventId >= target)) return;
-    if (pass === maxPasses - 1) {
-      throw budgetExhaustedError(maxPasses, target, states);
-    }
-  }
-}
-
-async function loadConsumerStates(
-  db: DbConnection,
-  consumerNames: readonly [string, ...string[]],
-): Promise<readonly ConsumerRecoveryState[]> {
-  return Promise.all(
-    consumerNames.map(async (name) => {
-      const state = await getConsumerState(db, name);
-      if (!state) {
-        throw new Error(`drainEventConsumers: consumer "${name}" not registered or per-instance`);
-      }
-      return state;
-    }),
-  );
-}
-
-function budgetExhaustedError(
-  maxPasses: number,
-  target: bigint,
-  states: readonly ConsumerRecoveryState[],
-): Error {
-  const unfinished = states.filter((state) => state.lastProcessedEventId < target);
-  const lines = unfinished.map(
-    (state) =>
-      `  ${state.name}: lastProcessedEventId=${state.lastProcessedEventId} target=${target} ` +
-      `status=${state.status} attempts=${state.attempts} lastError=${state.lastError ?? "null"}`,
-  );
-  return new Error(
-    `drainEventConsumers: budget of ${maxPasses} passes exhausted, consumers still behind target:\n` +
-      lines.join("\n"),
-  );
-}

package/src/stack/drain-jobs.ts

@@ -1,129 +0,0 @@
-import type { DbConnection } from "../db";
-import { getEventsHighWaterMark } from "../event-store";
-import type { JobRunner } from "../jobs";
-import { type EventDispatcher, getConsumerState } from "../pipeline";
-
-// Gap between idle-checks while waiting for a job hook to fire. Short enough
-// that a test never feels it, long enough that consecutive idle passes don't
-// hammer Postgres/Redis with pointless polling between hook-driven wakeups.
-const DRAIN_IDLE_POLL_MS = 25;
-// Two consecutive idle passes (not one) before declaring the stack drained —
-// a single "pending===0 and consumers caught up" pass can be a race: a job
-// hook fires and enqueues a follow-up between the countPendingJobs() read
-// and the consumer check of the SAME pass. A DRAIN_IDLE_POLL_MS wait sits
-// between every pass, including the first and second idle one, so an
-// enqueue that lands just after the first idle read still gets picked up
-// by the second pass instead of racing straight past it.
-const REQUIRED_IDLE_PASSES = 2;
-
-function sleep(ms: number): Promise<void> {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
-
-export type JobFailureTracker = {
-  readonly onJobComplete: (jobName: string, jobId: string) => void;
-  readonly onJobFailed: (jobName: string, jobId: string, error: string) => void;
-  waitForActivity(): Promise<void>;
-  readonly failures: ReadonlyMap<string, { readonly jobName: string; readonly error: string }>;
-  clear(): void;
-};
-
-export function createJobFailureTracker(): JobFailureTracker {
-  const failures = new Map<string, { jobName: string; error: string }>();
-  let wake: (() => void) | undefined;
-  let armed: Promise<void> | undefined;
-
-  function fire(): void {
-    wake?.();
-    armed = undefined;
-    wake = undefined;
-  }
-
-  return {
-    onJobComplete(_jobName, jobId) {
-      // A retry that eventually succeeds must not leave a stale failure
-      // behind from its earlier attempt(s).
-      failures.delete(jobId);
-      fire();
-    },
-    onJobFailed(jobName, jobId, error) {
-      failures.set(jobId, { jobName, error });
-      fire();
-    },
-    waitForActivity() {
-      armed ??= new Promise<void>((resolve) => {
-        wake = resolve;
-      });
-      return armed;
-    },
-    failures,
-    clear() {
-      failures.clear();
-    },
-  };
-}
-
-export type DrainJobsStack = {
-  readonly db: DbConnection;
-  readonly eventDispatcher?: EventDispatcher;
-  readonly jobRunner?: JobRunner;
-};
-
-async function sharedConsumersCaughtUp(
-  db: DbConnection,
-  consumerNames: readonly string[],
-): Promise<boolean> {
-  // skip: no shared consumers wired — nothing to catch up on.
-  if (consumerNames.length === 0) return true;
-  const target = await getEventsHighWaterMark(db);
-  let allCaughtUp = true;
-  for (const name of consumerNames) {
-    const state = await getConsumerState(db, name);
-    if (!state) {
-      throw new Error(`drainJobs: consumer "${name}" not registered or per-instance`);
-    }
-    if (state.status === "dead") {
-      throw new Error(
-        `drainJobs: consumer "${state.name}" is dead — lastError: ${state.lastError ?? "unknown"}`,
-      );
-    }
-    if (state.lastProcessedEventId < target) allCaughtUp = false;
-  }
-  return allCaughtUp;
-}
-
-export async function drainJobs(stack: DrainJobsStack, tracker: JobFailureTracker): Promise<void> {
-  const { db, eventDispatcher, jobRunner } = stack;
-  if (!jobRunner) {
-    throw new Error(
-      "drainJobs: stack.jobRunner is undefined — pass `jobs: {...}` to setupTestStack and " +
-        "register at least one r.job(...) so a runner is built.",
-    );
-  }
-
-  const sharedConsumerNames = (eventDispatcher?.consumers ?? [])
-    .filter((consumer) => (consumer.delivery ?? "shared") === "shared")
-    .map((consumer) => consumer.name);
-
-  try {
-    let consecutiveIdlePasses = 0;
-    while (consecutiveIdlePasses < REQUIRED_IDLE_PASSES) {
-      await eventDispatcher?.runOnce();
-      const pending = await jobRunner.countPendingJobs();
-      const caughtUp = await sharedConsumersCaughtUp(db, sharedConsumerNames);
-      consecutiveIdlePasses = pending === 0 && caughtUp ? consecutiveIdlePasses + 1 : 0;
-      if (consecutiveIdlePasses < REQUIRED_IDLE_PASSES) {
-        await Promise.race([tracker.waitForActivity(), sleep(DRAIN_IDLE_POLL_MS)]);
-      }
-    }
-
-    if (tracker.failures.size > 0) {
-      const details = [...tracker.failures.values()]
-        .map((failure) => `${failure.jobName}: ${failure.error}`)
-        .join("; ");
-      throw new Error(`drainJobs: job(s) failed: ${details}`);
-    }
-  } finally {
-    tracker.clear();
-  }
-}

package/src/stack/event-collector.ts

@@ -1,23 +0,0 @@
-import type { SseEvent } from "../api/sse-broker";
-import type { SaveContext } from "../engine/types";
-
-export type EventCollector = {
-  readonly sse: SseEvent[];
-  readonly postSave: SaveContext[];
-  /** Clears all collected events — call in beforeEach for per-test isolation */
-  reset(): void;
-};
-
-export function createEventCollector(): EventCollector {
-  const sse: SseEvent[] = [];
-  const postSave: SaveContext[] = [];
-
-  return {
-    sse,
-    postSave,
-    reset() {
-      sse.length = 0;
-      postSave.length = 0;
-    },
-  };
-}

package/src/stack/index.ts

@@ -1,34 +0,0 @@
-// Runtime-safe Stack-Builder. Was hier liegt, wird vom dev-server zum Hochfahren
-// einer kompletten Kumiko-Instanz genutzt — DB, Redis, Hono-App, Dispatcher,
-// SSE-Broker. Die Files heißen historisch `test*` (createTestDb,
-// setupTestStack, TestUsers, …), bedienen aber heute Dev- UND Test-Code: das
-// ist genau derselbe Hochfahr-Pfad, nur einmal mit ephemeral-DB (test) und
-// einmal mit persistent-DB (dev).
-//
-// Wichtig: dieses Modul darf KEINE vitest-Imports enthalten und keine
-// Vitest-only Helper transitiv ziehen — sonst crasht jedes Tooling, das den
-// dev-server unter Node lädt (drizzle-kit, build-scripts).
-
-export {
-  type CreateTestDbOptions,
-  createTestDb,
-  type TestDb,
-} from "./db";
-export { drainEventConsumers } from "./drain-event-consumers";
-export { createEventCollector, type EventCollector } from "./event-collector";
-export { pushEntityProjectionTables } from "./push-entity-projection-tables";
-export { createTestRedis, type TestRedis } from "./redis";
-export { createRequestHelper, type RequestHelper } from "./request-helper";
-export {
-  resetEventStore,
-  unsafeCreateEntityTable,
-  unsafeEnsureEntityTable,
-  unsafePushTables,
-} from "./table-helpers";
-export { setupTestStack, type TestStack, type TestStackOptions } from "./test-stack";
-export {
-  createTestUser,
-  TestUsers,
-  testTenantId,
-  testUserId,
-} from "./test-users";