@cosmicdrift/kumiko-framework 1.0.0 → 2.0.0

package/src/entrypoint/__tests__/entrypoint-job-wiring.integration.test.ts

@@ -17,9 +17,10 @@ import { z } from "zod";
 import { type BunTestDb, createTestDb } from "../../bun-db/__tests__/bun-test-db";
 import { createRegistry, defineFeature } from "../../engine";
 import { createArchivedStreamsTable, createEventsTable } from "../../event-store";
+import { createNoopProvider, createPrometheusMeter } from "../../observability";
 import { createEventConsumerStateTable } from "../../pipeline";
 import { createTestRedis, type TestRedis, TestUsers } from "../../stack";
-import { waitFor } from "../../testing";
+import { sleep, waitFor } from "../../testing";
 import { createAllInOneEntrypoint } from "../index";
 
 const jobRuns: Array<{ name: string; payload: Record<string, unknown> }> = [];
@@ -172,3 +173,121 @@ describe("createAllInOneEntrypoint auto-wires jobRunner into command-dispatcher"
     }
   });
 });
+
+// Regression test for #1046 — createJobRunner is built from the caller's
+// RAW context, BEFORE buildServer ever merges observability.tracer/meter
+// into a context object of its own. Without threading the resolved
+// provider into the job-runner's context too, `context.meter` stayed
+// undefined, the queue-depth poller's `if (context.meter)` guard skipped
+// silently, and `/metrics` showed the kumiko_job_queue_depth HELP/TYPE
+// header but never a single data line — forever, with no error anywhere.
+describe("createAllInOneEntrypoint — kumiko_job_queue_depth sees the SAME meter as buildServer (#1046)", () => {
+  test("passing an explicit observability provider makes the queue-depth poller emit real data for BOTH lanes", async () => {
+    const registry = createRegistry([wiringFeature]);
+    const redisUrl = `redis://${testRedis.redis.options.host}:${testRedis.redis.options.port}/${testRedis.redis.options.db}`;
+    const meter = createPrometheusMeter();
+    const observability = { ...createNoopProvider(), meter };
+    const entry = createAllInOneEntrypoint({
+      registry,
+      context: { db: testDb.db, redis: testRedis.redis },
+      jwtSecret: JWT,
+      redisUrl,
+      queueNamePrefix: `wiring-qd-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+      observability,
+    });
+    await entry.start();
+    try {
+      // If the job-runner never saw this meter (the #1046 bug), the poller's
+      // `if (context.meter)` guard skips entirely and no slots ever appear —
+      // this assertion is the one that would have caught it.
+      const snapshot = meter.snapshot().get("kumiko_job_queue_depth");
+      expect(snapshot).toBeDefined();
+      const workerWaiting = snapshot?.slots.find(
+        (s) => s.labels?.["lane"] === "worker" && s.labels?.["state"] === "waiting",
+      );
+      const apiWaiting = snapshot?.slots.find(
+        (s) => s.labels?.["lane"] === "api" && s.labels?.["state"] === "waiting",
+      );
+      expect(workerWaiting).toBeDefined();
+      expect(apiWaiting).toBeDefined();
+      // Same instance, not a coincidentally-equal one — proves buildServer's
+      // internal registerStandardMetrics() and the job-runner's poller wrote
+      // into the identical meter, not two disconnected Noop instances.
+      expect(entry.observability.meter).toBe(meter);
+      // BullMQ's fresh Worker connections are still settling right after
+      // start() returns — stopping immediately races their own connection
+      // teardown and throws an unrelated "Connection is closed" from
+      // ioredis (same artifact documented in job-queue-depth.integration.
+      // test.ts). Production runners live far longer than this.
+      await sleep(50);
+    } finally {
+      await entry.stop();
+    }
+  });
+});
+
+// Regression test for #1253 — effectiveFeatures was wired into
+// dispatcherOptions (command-dispatcher's feature-gate) but never merged
+// into the job-runner's context. A job handler reading
+// `context.effectiveFeatures?.(tenantId)` always saw undefined in prod.
+const featuresSeenByJob: Array<ReadonlySet<string> | undefined> = [];
+
+const featureGateJobFeature = defineFeature("featuregate", (r) => {
+  r.writeHandler(
+    "ping",
+    z.object({ msg: z.string() }),
+    async (event) => ({
+      isSuccess: true as const,
+      data: { id: 1, msg: event.payload.msg },
+    }),
+    { access: { openToAll: true } },
+  );
+  r.job(
+    "record-features",
+    { trigger: { on: "featuregate:write:ping" }, runIn: "worker" },
+    async (_payload, context) => {
+      featuresSeenByJob.push(context.effectiveFeatures?.(adminUser.tenantId));
+    },
+  );
+});
+
+describe("createAllInOneEntrypoint — job context sees dispatcherOptions.effectiveFeatures (#1253)", () => {
+  test("job handler reads the same effectiveFeatures resolver as the command-dispatcher's feature-gate", async () => {
+    featuresSeenByJob.length = 0;
+    const registry = createRegistry([featureGateJobFeature]);
+    const redisUrl = `redis://${testRedis.redis.options.host}:${testRedis.redis.options.port}/${testRedis.redis.options.db}`;
+    const entry = createAllInOneEntrypoint({
+      registry,
+      context: { db: testDb.db, redis: testRedis.redis },
+      jwtSecret: JWT,
+      redisUrl,
+      queueNamePrefix: `wiring-features-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+      dispatcherOptions: {
+        effectiveFeatures: () => new Set(["featuregate", "some-feature"]),
+      },
+    });
+    await entry.start();
+    try {
+      const token = await entry.jwt.sign(adminUser);
+      const res = await entry.app.request("/api/write", {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${token}`,
+        },
+        body: JSON.stringify({ type: "featuregate:write:ping", payload: { msg: "hi" } }),
+      });
+      const result = (await res.json()) as { isSuccess: boolean };
+      expect(result.isSuccess).toBe(true);
+
+      // Without the fix, context.effectiveFeatures is undefined and this
+      // stays empty forever — waitFor times out on the missing entry.
+      await waitFor(() => {
+        expect(featuresSeenByJob.length).toBeGreaterThan(0);
+        expect(featuresSeenByJob[0]?.has("some-feature")).toBe(true);
+      });
+    } finally {
+      await entry.stop();
+    }
+  });
+});

package/src/entrypoint/index.ts

@@ -32,17 +32,19 @@
 
 import type { Hono } from "hono";
 import type { AuthRoutesConfig } from "../api/auth-routes";
-import type { JwtHelper } from "../api/jwt";
+import type { JwtHelper, JwtKeyring } from "../api/jwt";
 import type { KumikoServer, ServerOptions } from "../api/server";
 import { buildServer } from "../api/server";
 import type { SseBroker } from "../api/sse-broker";
 import type { PgClient } from "../db/connection";
+import type { EffectiveFeaturesResolver } from "../engine/tier-resolver-extension";
 import type { AppContext, JobRunIn, Registry, RunIn } from "../engine/types";
 import type { JobRunner, JobRunnerOptions } from "../jobs/job-runner";
 import { createJobRunner } from "../jobs/job-runner";
 import type { Lifecycle } from "../lifecycle";
 import { createLifecycle } from "../lifecycle";
 import type { ObservabilityOptions, ObservabilityProvider } from "../observability";
+import { createNoopProvider } from "../observability";
 import type { EventDedup, EventDispatcher } from "../pipeline";
 import type { Dispatcher, DispatcherOptions } from "../pipeline/dispatcher";
 import type { SystemHooks } from "../pipeline/lifecycle-pipeline";
@@ -52,7 +54,7 @@ import type { SystemHooks } from "../pipeline/lifecycle-pipeline";
 export type BaseEntrypointOptions = {
   readonly registry: Registry;
   readonly context: AppContext;
-  readonly jwtSecret: string;
+  readonly jwtSecret: string | JwtKeyring;
   readonly jwtIssuer?: string;
   readonly observability?: ObservabilityProvider;
   readonly observabilityOptions?: ObservabilityOptions;
@@ -175,6 +177,31 @@ function mergeDispatcherOptions(
   return { ...(caller ?? {}), jobRunner };
 }
 
+// Resolved once for the job-runner's context only — buildServer still gets
+// the caller's original `options.observability` (unresolved) since it
+// derives `shouldWrapRedis` from whether that was explicitly set.
+function resolveObservability(
+  observability: ObservabilityProvider | undefined,
+): ObservabilityProvider {
+  return observability ?? createNoopProvider();
+}
+
+function contextWithObservability(
+  context: AppContext,
+  observability: ObservabilityProvider,
+  effectiveFeatures: EffectiveFeaturesResolver | undefined,
+): AppContext {
+  return {
+    ...context,
+    // Same source of truth as buildServer's contextWithObservability
+    // (api/server.ts) — job handlers reading ctx.effectiveFeatures should
+    // see the same resolver as command handlers, not just dispatcherOptions.
+    ...(effectiveFeatures && { effectiveFeatures }),
+    tracer: observability.tracer,
+    meter: observability.meter,
+  };
+}
+
 // buildApiServer shapes ServerOptions from API-mode caller-options.
 // AllInOneEntrypointOptions extends ApiEntrypointOptions, so structural
 // subtyping makes the all-in-one path a valid caller without an explicit
@@ -291,6 +318,7 @@ function requireDispatcher(server: KumikoServer, mode: string): EventDispatcher
 
 export function createApiEntrypoint(options: ApiEntrypointOptions): ApiEntrypoint {
   const lifecycle = options.lifecycle ?? createLifecycle({ startReady: true });
+  const observability = resolveObservability(options.observability);
 
   // Boot-validation (Welle 2.6.c) — fail loud before traffic arrives:
   //   (a) Any jobs declared + no jobs-block → command-dispatcher would
@@ -324,7 +352,11 @@ export function createApiEntrypoint(options: ApiEntrypointOptions): ApiEntrypoin
   const apiJobRunner = options.jobs
     ? buildJobRunnerWithHook(
         options.registry,
-        options.context,
+        contextWithObservability(
+          options.context,
+          observability,
+          options.dispatcherOptions?.effectiveFeatures,
+        ),
         options.jobs,
         options.jobs.runLocalJobs ? "api" : undefined,
         lifecycle,
@@ -375,9 +407,14 @@ export function createApiEntrypoint(options: ApiEntrypointOptions): ApiEntrypoin
 
 export function createWorkerEntrypoint(options: WorkerEntrypointOptions): WorkerEntrypoint {
   const lifecycle = options.lifecycle ?? createLifecycle({ startReady: true });
+  const observability = resolveObservability(options.observability);
   const jobRunner = buildJobRunnerWithHook(
     options.registry,
-    options.context,
+    contextWithObservability(
+      options.context,
+      observability,
+      options.dispatcherOptions?.effectiveFeatures,
+    ),
     options,
     "worker",
     lifecycle,
@@ -406,6 +443,12 @@ export function createWorkerEntrypoint(options: WorkerEntrypointOptions): Worker
 
 export function createAllInOneEntrypoint(options: AllInOneEntrypointOptions): AllInOneEntrypoint {
   const lifecycle = options.lifecycle ?? createLifecycle({ startReady: true });
+  const observability = resolveObservability(options.observability);
+  const jobRunnerContext = contextWithObservability(
+    options.context,
+    observability,
+    options.dispatcherOptions?.effectiveFeatures,
+  );
 
   // All-in-one consumes BOTH lanes: two runners, each with a BullMQ worker
   // for its own lane's queue. Both runners hold queue-clients for both
@@ -416,7 +459,7 @@ export function createAllInOneEntrypoint(options: AllInOneEntrypointOptions): Al
   // its own lane in its own .start().
   const workerJobRunner = buildJobRunnerWithHook(
     options.registry,
-    options.context,
+    jobRunnerContext,
     options,
     "worker",
     lifecycle,
@@ -424,7 +467,7 @@ export function createAllInOneEntrypoint(options: AllInOneEntrypointOptions): Al
   );
   const apiJobRunner = buildJobRunnerWithHook(
     options.registry,
-    options.context,
+    jobRunnerContext,
     options,
     "api",
     lifecycle,

package/src/errors/classes.ts

@@ -2,7 +2,7 @@ import { toSnakeCase } from "../utils/case";
 import type { FieldIssue } from "./field-issue";
 import { type ErrorOpts, KumikoError } from "./kumiko-error";
 
-export type { FieldIssue, ValidationFieldIssue } from "./field-issue";
+export type { FieldIssue } from "./field-issue";
 
 export type ValidationDetails = {
   readonly fields: readonly FieldIssue[];
@@ -138,6 +138,27 @@ export class VersionConflictError extends ConflictError {
   }
 }
 
+// The caller retried a write with an idempotencyKey it had already used —
+// the event-store's partial unique index on metadata.idempotencyKey caught
+// the duplicate. Distinct from unique_violation/version_conflict: this is
+// not an error the caller should retry, it means the earlier attempt
+// already succeeded and this one is a no-op replay.
+export class IdempotentReplayError extends ConflictError {
+  override readonly code: string = "idempotent_replay";
+
+  constructor(
+    details: { readonly idempotencyKey: string },
+    opts?: Pick<ErrorOpts, "i18nKey" | "cause">,
+  ) {
+    super({
+      message: `event with idempotencyKey "${details.idempotencyKey}" was already appended`,
+      i18nKey: opts?.i18nKey ?? "errors.idempotentReplay",
+      details,
+      ...(opts?.cause && { cause: opts.cause }),
+    });
+  }
+}
+
 // Entity-level unique-index violation. Distinct from VersionConflictError:
 // version_conflict means "two writers raced on the events_aggregate_version
 // _uq index" (optimistic-concurrency); unique_violation means "you tried to

package/src/errors/field-issue.ts

@@ -6,6 +6,3 @@ export type FieldIssue = {
   readonly i18nKey: string;
   readonly params?: Readonly<Record<string, unknown>>;
 };
-
-/** @deprecated Use `FieldIssue` — kept for existing imports. */
-export type ValidationFieldIssue = FieldIssue;

package/src/errors/index.ts

@@ -7,13 +7,13 @@ export type {
   UniqueViolationDetails,
   UnprocessableOpts,
   ValidationDetails,
-  ValidationFieldIssue,
   VersionConflictDetails,
 } from "./classes";
 export {
   AccessDeniedError,
   ConflictError,
   FeatureDisabledError,
+  IdempotentReplayError,
   InternalError,
   NotFoundError,
   RateLimitError,

package/src/errors/write-error-info.ts

@@ -1,30 +1,18 @@
+import type {
+  WriteErrorInfo,
+  WriteFailure,
+} from "@cosmicdrift/kumiko-types/write-error-info-types";
 import { NotFoundError, UnprocessableError } from "./classes";
 import { KumikoError } from "./kumiko-error";
 import { FrameworkReasons } from "./reasons";
 import { buildInvalidTransitionDetails } from "./transition-details";
 
-// Plain, JSON-serializable snapshot of a KumikoError for use on the write-path
-// (WriteResult.error, BatchResult.error). The dispatcher stores results under
-// an idempotency key — a KumikoError instance wouldn't round-trip through
-// JSON, so we keep structural data only and rebuild the instance on demand
-// via reraiseAsKumikoError when we need to throw upstream again.
-export type WriteErrorInfo = {
-  readonly code: string;
-  readonly httpStatus: number;
-  readonly i18nKey: string;
-  readonly i18nParams?: Readonly<Record<string, unknown>>;
-  readonly message: string;
-  readonly details?: unknown;
-};
-
-// The failure half of WriteResult — `{ isSuccess: false } + error`. Named
-// so the three write-failure factories below and WriteResult share one
-// shape instead of restating it. Not generic: the error carries zero data,
-// so there's nothing for the caller to narrow.
-export type WriteFailure = {
-  readonly isSuccess: false;
-  readonly error: WriteErrorInfo;
-};
+// Re-exported so a caller importing this module directly (instead of via
+// the `./errors` barrel, which already re-exports these by name) still
+// gets the types — explicit, not a wildcard: this module isn't a public
+// subpath export (see package.json `exports`), so the only readers are
+// framework-internal.
+export type { WriteErrorInfo, WriteFailure };
 
 // Convenience for call sites that return a failed WriteResult. Keeps the
 // pattern `return writeFailure(new NotFoundError(...))` compact so handlers

package/src/es-ops/README.md

@@ -7,7 +7,7 @@ ES-Operations für Kumiko-Apps. Phase 1+1.5 liefert `seed-migrations` als file-b
 ## Quick API
 
 ```ts
-import { runProdApp } from "@cosmicdrift/kumiko-dev-server";
+import { runProdApp } from "@cosmicdrift/kumiko-server-runtime";
 
 await runProdApp({
   features: [...],

package/src/es-ops/__tests__/runner.integration.test.ts

@@ -72,6 +72,14 @@ const seedTestFeature = defineFeature("esopstest", (r) => {
     },
     { access: { openToAll: true } },
   );
+  // Role-gated handler (no openToAll): the bare system actor has no bypass
+  // for explicit role gates — only systemWriteAs' extraRoles reaches it.
+  r.writeHandler(
+    "probe:admin-only",
+    z.object({ label: z.string().min(1) }),
+    async (event, ctx) => probeExecutor.create(event.payload, event.user, ctx.db),
+    { access: { roles: ["SystemAdmin"] } },
+  );
 });
 
 let testDb: TestDb;
@@ -233,6 +241,72 @@ describe("runPendingSeedMigrations (integration)", () => {
     }
   });
 
+  test("systemWriteAs ohne extraRoles → access_denied gegen rollen-gated Handler, mit extraRoles → durch", async () => {
+    const denyDir = makeTempSeedsDir([
+      {
+        name: "2026-05-20-denied.ts",
+        content: `
+          export default {
+            description: "no extraRoles against a role-gated handler",
+            run: async (ctx) => {
+              await ctx.systemWriteAs("esopstest:write:probe:admin-only", { label: "denied" });
+            },
+          };
+        `,
+      },
+    ]);
+    try {
+      await expect(
+        runPendingSeedMigrations({
+          db: testDb.db,
+          seedsDir: denyDir,
+          appliedBy: "boot",
+          registry,
+          createContext: (dbRunner) => createSeedMigrationContext({ dispatcher, dbRunner }),
+          logger: () => {},
+        }),
+      ).rejects.toThrow(/access_denied/);
+      expect(await selectEvents()).toHaveLength(0);
+    } finally {
+      rmSync(denyDir, { recursive: true, force: true });
+    }
+
+    const allowDir = makeTempSeedsDir([
+      {
+        name: "2026-05-20-allowed.ts",
+        content: `
+          export default {
+            description: "extraRoles reaches a role-gated handler",
+            run: async (ctx) => {
+              await ctx.systemWriteAs(
+                "esopstest:write:probe:admin-only",
+                { label: "allowed" },
+                undefined,
+                ["SystemAdmin"],
+              );
+            },
+          };
+        `,
+      },
+    ]);
+    try {
+      await runPendingSeedMigrations({
+        db: testDb.db,
+        seedsDir: allowDir,
+        appliedBy: "boot",
+        registry,
+        createContext: (dbRunner) => createSeedMigrationContext({ dispatcher, dbRunner }),
+        logger: () => {},
+      });
+      const events = await selectEvents();
+      expect(events).toHaveLength(1);
+      expect(events[0]?.type).toBe("esops-probe.created");
+      expect(events[0]?.tenant_id).toBe(SYSTEM_TENANT_ID);
+    } finally {
+      rmSync(allowDir, { recursive: true, force: true });
+    }
+  });
+
   test("WriteResult{isSuccess:false} → throw + Marker NICHT geschrieben", async () => {
     // Critical: ohne diese Garantie würde ein silent-failed Write den Seed
     // als "applied" markieren → beim nächsten Boot kein retry → DB-Drift

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/event-store/__tests__/admin-api.integration.test.ts

@@ -15,7 +15,7 @@ import { asRawClient, selectMany } from "../../db/query";
 import { createTestDb, type TestDb } from "../../stack";
 import { generateId as uuid } from "../../utils";
 import { appendRaw, appendRawBatch, type RawEventToAppend } from "../admin-api";
-import { VersionConflictError } from "../errors";
+import { IdempotentAppendConflictError, VersionConflictError } from "../errors";
 import { append, loadAggregate } from "../event-store";
 import { createEventsTable, eventsTable } from "../events-schema";
 
@@ -187,6 +187,32 @@ describe("appendRaw — single event", () => {
     ).rejects.toBeInstanceOf(VersionConflictError);
   });
 
+  test("appendRaw distinguishes an idempotency-key replay from a version conflict (#1499)", async () => {
+    const idempotencyKey = uuid();
+    await appendRaw(
+      testDb.db,
+      makeEvent({
+        aggregateId: uuid(),
+        expectedVersion: 0,
+        metadata: { userId: userMigration, idempotencyKey },
+      }),
+    );
+
+    // A second, different aggregate reusing the same idempotencyKey hits
+    // the tenant-scoped partial unique index — distinct from a version
+    // race on the same aggregate, and must not be reported as one.
+    await expect(
+      appendRaw(
+        testDb.db,
+        makeEvent({
+          aggregateId: uuid(),
+          expectedVersion: 0,
+          metadata: { userId: userMigration, idempotencyKey },
+        }),
+      ),
+    ).rejects.toBeInstanceOf(IdempotentAppendConflictError);
+  });
+
   test("version_conflict on missing predecessor (appendRaw v=5 without v=1..4)", async () => {
     const aggregateId = uuid();
     // Try to write version=5 (expectedVersion=4) against an empty stream.