@cosmicdrift/kumiko-framework 0.158.2 → 0.160.0

package/src/observability/types/metric.ts

@@ -1,56 +1 @@
-// Metric + Meter contract. Feature code interacts through ctx.metrics
-// (MetricsHandle); the framework wires Counter/Histogram/Gauge behind that.
-
-export type MetricLabels = Record<string, string | number | boolean>;
-
-export type MetricType = "counter" | "histogram" | "gauge";
-
-export type MetricDefinition = {
-  // Fully-qualified name (with kumiko_<feature>_ prefix already applied).
-  readonly name: string;
-  readonly type: MetricType;
-  readonly description?: string;
-  // Declared label keys. Inc/observe calls with unknown label keys throw.
-  readonly labels?: readonly string[];
-  // Buckets only for histogram. If omitted, provider-default is used.
-  readonly buckets?: readonly number[];
-  readonly unit?: string;
-  // If true, the framework auto-injects tenant_id from the active ctx.
-  // Default false — adding tenant_id multiplies cardinality by tenant count.
-  readonly tenantLabel?: boolean;
-};
-
-export interface Counter {
-  inc(value?: number, labels?: MetricLabels): void;
-}
-
-export interface Histogram {
-  observe(value: number, labels?: MetricLabels): void;
-}
-
-export interface Gauge {
-  set(value: number, labels?: MetricLabels): void;
-  inc(value?: number, labels?: MetricLabels): void;
-  dec(value?: number, labels?: MetricLabels): void;
-}
-
-export interface Meter {
-  // Called once per metric during boot. Duplicate names throw.
-  registerMetric(def: MetricDefinition): void;
-  // Lookup by fully-qualified name. Unknown names throw — typed access only.
-  counter(name: string): Counter;
-  histogram(name: string): Histogram;
-  gauge(name: string): Gauge;
-  // List of registered definitions — used by ctx.metrics to validate labels.
-  definitions(): ReadonlyMap<string, MetricDefinition>;
-}
-
-// Public handle for feature code — ctx.metrics.
-// Name resolution uses the fully-qualified name (kumiko_<feature>_<short>).
-// The registrar resolves the short name from the calling feature context
-// at boot time; at handler time the map is ready.
-export interface MetricsHandle {
-  inc(name: string, labels?: MetricLabels, value?: number): void;
-  observe(name: string, value: number, labels?: MetricLabels): void;
-  set(name: string, value: number, labels?: MetricLabels): void;
-}
+export * from "@cosmicdrift/kumiko-types/observability/metric";

package/src/observability/types/provider.ts

@@ -1,32 +1 @@
-// Observability provider contract — the "plug" that implementations (noop,
-// console, otlp, prometheus) fulfil. Configuration types that consumers
-// (buildServer, setupTestStack) hand in also live here.
-
-import type { Meter } from "./metric";
-import type { Tracer } from "./span";
-
-export type SamplingConfig = {
-  // Base sampling rate 0..1. Default 1 in v1 (sample everything).
-  readonly tracing?: number;
-  readonly alwaysOnError?: boolean;
-  readonly alwaysOnSlow?: { readonly thresholdMs: number };
-};
-
-export type SensitiveFilterConfig = {
-  readonly redactedHeaders: readonly string[];
-  readonly redactedQueryParams: readonly string[];
-  readonly redactedAttributeKeyPatterns: readonly RegExp[];
-};
-
-export type ObservabilityOptions = {
-  readonly sampling?: SamplingConfig;
-  readonly sensitiveFilter?: Partial<SensitiveFilterConfig>;
-};
-
-export interface ObservabilityProvider {
-  readonly name: string;
-  readonly tracer: Tracer;
-  readonly meter: Meter;
-  // Graceful flush. Called from framework lifecycle shutdown.
-  shutdown(): Promise<void>;
-}
+export * from "@cosmicdrift/kumiko-types/observability/provider";

package/src/observability/types/span.ts

@@ -1,58 +1 @@
-// Span + Tracer contract. Provider implementations (noop, recording → console/otlp)
-// all speak this — everything else (middleware, dispatcher, db, redis, jobs)
-// is provider-agnostic.
-
-export type SpanAttributeValue = string | number | boolean;
-export type SpanAttributes = Record<string, SpanAttributeValue>;
-
-export type SpanStatus = "unset" | "ok" | "error";
-
-export type SpanKind = "internal" | "server" | "client" | "producer" | "consumer";
-
-// Serialized form of a trace context — what we pass across process boundaries
-// (outbox row, BullMQ job payload). Matches W3C trace-context spec loosely,
-// but staying minimal — a full W3C parser is v2.
-export type SerializedTraceContext = {
-  readonly traceId: string;
-  readonly spanId: string;
-  readonly baggage?: Readonly<Record<string, string>>;
-};
-
-export type StartSpanOptions = {
-  // Either a live Span (normal in-process parent) or a serialized trace
-  // context (cross-process — outbox row, job payload). Both carry traceId
-  // and spanId, so the tracer reads them uniformly. Omitted → fall back to
-  // the AsyncLocalStorage active span.
-  readonly parent?: Span | SerializedTraceContext;
-  readonly attributes?: SpanAttributes;
-  readonly kind?: SpanKind;
-  readonly startTime?: number;
-};
-
-export interface Span {
-  readonly traceId: string;
-  readonly spanId: string;
-  readonly parentSpanId: string | undefined;
-  readonly name: string;
-  setAttribute(key: string, value: SpanAttributeValue): void;
-  setAttributes(attrs: SpanAttributes): void;
-  setStatus(status: SpanStatus, message?: string): void;
-  recordException(error: Error): void;
-  end(endTime?: number): void;
-  // Whether end() has been called. Idempotency guard for auto-wrappers.
-  readonly ended: boolean;
-}
-
-export interface Tracer {
-  startSpan(name: string, options?: StartSpanOptions): Span;
-  // Runs fn inside the span context (AsyncLocalStorage), ends the span
-  // automatically — including on thrown errors, where the error is recorded
-  // and status set to "error" before re-throwing.
-  withSpan<T>(
-    name: string,
-    optionsOrFn: StartSpanOptions | ((span: Span) => Promise<T>),
-    fn?: (span: Span) => Promise<T>,
-  ): Promise<T>;
-  // Current active span from AsyncLocalStorage, or undefined.
-  getActiveSpan(): Span | undefined;
-}
+export * from "@cosmicdrift/kumiko-types/observability/span";

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

@@ -25,6 +25,17 @@ const echoFeature = defineFeature("echo", (r) => {
     { access: { openToAll: true } },
   );
 
+  r.streamHandler(
+    "item:tail",
+    z.object({ count: z.number().int().min(0) }),
+    async function* (query) {
+      for (let i = 0; i < query.payload.count; i++) {
+        yield { i };
+      }
+    },
+    { access: { roles: ["Admin"] } },
+  );
+
   r.hook("validation", "item:create", (data) => {
     if (data["name"] === "forbidden") return [{ field: "name", error: "forbidden_name" }];
     return null;
@@ -214,6 +225,55 @@ describe("dispatcher.query", () => {
   });
 });
 
+async function collect<T>(gen: AsyncGenerator<T>): Promise<T[]> {
+  const out: T[] = [];
+  for await (const chunk of gen) out.push(chunk);
+  return out;
+}
+
+describe("dispatcher.stream", () => {
+  test("validates and calls stream handler, yielding chunks in order", async () => {
+    const dispatcher = createTestDispatcher();
+    const chunks = await collect(
+      dispatcher.stream(
+        "echo:stream:item:tail",
+        { count: 3 },
+        createTestUser({ roles: ["Admin"] }),
+      ),
+    );
+
+    expect(chunks).toEqual([{ i: 0 }, { i: 1 }, { i: 2 }]);
+  });
+
+  test("gates fire on first pull, not on the stream() call itself", async () => {
+    const dispatcher = createTestDispatcher();
+    const gen = dispatcher.stream(
+      "echo:stream:item:tail",
+      { count: -1 },
+      createTestUser({ roles: ["Admin"] }),
+    );
+
+    await expect(collect(gen)).rejects.toMatchObject({ code: "validation_error", httpStatus: 400 });
+  });
+
+  test("rejects unauthorized user", async () => {
+    const dispatcher = createTestDispatcher();
+    const guest = createTestUser({ roles: ["Guest"] });
+
+    await expect(
+      collect(dispatcher.stream("echo:stream:item:tail", { count: 1 }, guest)),
+    ).rejects.toMatchObject({ code: "access_denied" });
+  });
+
+  test("throws for unknown stream handler", async () => {
+    const dispatcher = createTestDispatcher();
+
+    await expect(
+      collect(dispatcher.stream("nonexistent", {}, createTestUser({ roles: ["Admin"] }))),
+    ).rejects.toMatchObject({ code: "not_found", httpStatus: 404 });
+  });
+});
+
 // --- postQuery hooks on standalone (entity-less) queries ---
 
 describe("dispatcher.query postQuery hooks", () => {
@@ -362,6 +422,20 @@ describe("dispatcher feature-gate", () => {
         async (event) => ({ isSuccess: true, data: { name: event.payload.name } }),
         { access: { roles: ["Admin"] } },
       );
+      r.streamHandler(
+        "widget:tail",
+        z.object({}).passthrough(),
+        async function* () {
+          // Never completes on its own — the mid-stream toggle-off test
+          // relies on the generator staying open past the first yield.
+          let i = 0;
+          while (true) {
+            yield { i };
+            i++;
+          }
+        },
+        { access: { openToAll: true } },
+      );
     });
   }
 
@@ -397,6 +471,28 @@ describe("dispatcher feature-gate", () => {
     });
   });
 
+  test("disabling the feature mid-stream aborts an already-open stream", async () => {
+    const registry = createRegistry([toggled()]);
+    const disabled = new Set<string>();
+    const dispatcher = createDispatcher(
+      registry,
+      {},
+      {
+        effectiveFeatures: () => {
+          const all = new Set(registry.features.keys());
+          for (const d of disabled) all.delete(d);
+          return all;
+        },
+      },
+    );
+
+    const gen = dispatcher.stream("toggled:stream:widget:tail", {}, user);
+    expect((await gen.next()).value).toEqual({ i: 0 });
+
+    disabled.add("toggled");
+    await expect(gen.next()).rejects.toThrow(/feature toggled is disabled/);
+  });
+
   test("write of disabled feature returns WriteFailure with feature_disabled reason", async () => {
     const registry = createRegistry([toggled()]);
     const disabled = new Set<string>(["toggled"]);
@@ -509,7 +605,7 @@ describe("dispatcher feature-gate", () => {
       r.queryHandler(
         "check",
         z.object({}).passthrough(),
-        async (_event, ctx) => ({ enabled: ctx.hasFeature("toggled") }),
+        async (_event, ctx) => ({ enabled: await ctx.hasFeature("toggled") }),
         { access: { openToAll: true } },
       );
     });
@@ -533,6 +629,43 @@ describe("dispatcher feature-gate", () => {
       enabled: false,
     });
   });
+
+  test("issue #1233: ctx.hasFeature falls back to trialGate for a companion feature the tenant doesn't own", async () => {
+    // Regression for the trial-tenant bug: a handler owned by an always-on
+    // feature checks a DIFFERENT (trial-tier) feature via ctx.hasFeature.
+    // The sync resolver never carries trial features, so without the
+    // trialGate fallback this silently reads false for a trial tenant even
+    // though the tenant is genuinely in-trial for that companion feature —
+    // mirrors packages/bundled-features/src/managed-pages/handlers/branding.query.ts
+    // checking MANAGED_PAGES_CSS_FEATURE, which no handler owns.
+    const trialTenant = "00000000-0000-4000-8000-0000000000c5" as TenantId;
+    const plainTenant = "00000000-0000-4000-8000-0000000000d6" as TenantId;
+
+    const probe = defineFeature("probe", (r) => {
+      r.queryHandler(
+        "check",
+        z.object({}).passthrough(),
+        async (_event, ctx) => ({ enabled: await ctx.hasFeature("premium-companion") }),
+        { access: { openToAll: true } },
+      );
+    });
+    const registry = createRegistry([probe]);
+    const effectiveFeatures = Object.assign(() => new Set(["probe"]), {
+      trialGate: async (tenantId: TenantId, feature: string) =>
+        tenantId === trialTenant && feature === "premium-companion",
+    });
+    const dispatcher = createDispatcher(registry, {}, { effectiveFeatures });
+
+    const trialUser = createTestUser({ id: "u-c5", tenantId: trialTenant, roles: ["Admin"] });
+    const plainUser = createTestUser({ id: "u-d6", tenantId: plainTenant, roles: ["Admin"] });
+
+    await expect(dispatcher.query("probe:query:check", {}, trialUser)).resolves.toEqual({
+      enabled: true,
+    });
+    await expect(dispatcher.query("probe:query:check", {}, plainUser)).resolves.toEqual({
+      enabled: false,
+    });
+  });
 });
 
 describe("write-handler shape guard", () => {

package/src/pipeline/__tests__/event-dispatcher-delivery-max-attempts.test.ts

@@ -0,0 +1,126 @@
+// EventConsumerErrorPolicy.maxAttempts lets a consumer override the
+// dispatcher-wide default (kumiko-framework#1349) — a consumer depending on
+// infra that may still be provisioning at boot (search adapter) needs more
+// retry headroom before it gets dead-lettered. deliverEvents is a pure
+// free function, so this is unit-level: no DB, no dispatcher lifecycle.
+
+import { beforeAll, describe, expect, test } from "bun:test";
+import type { AppContext } from "../../engine/types";
+import { ensureTemporalPolyfill } from "../../time/polyfill";
+import type { EventConsumer } from "../event-dispatcher";
+import {
+  type ConsumerStateRow,
+  deliverEvents,
+  type StoredEventRow,
+} from "../event-dispatcher-delivery";
+import { createSearchEventConsumer } from "../system-hooks";
+
+beforeAll(async () => {
+  await ensureTemporalPolyfill();
+});
+
+function stubContext(): AppContext {
+  return {
+    db: {} as unknown as AppContext["db"],
+    redis: {} as unknown as AppContext["redis"],
+    registry: {} as unknown as AppContext["registry"],
+  } as AppContext;
+}
+
+function stubEvent(id: bigint): StoredEventRow {
+  return {
+    id,
+    aggregateId: "agg-1",
+    aggregateType: "widget",
+    tenantId: "tenant-1",
+    version: 1,
+    type: "widget.created",
+    eventVersion: 1,
+    payload: {},
+    metadata: { userId: "system" },
+    createdAt: Temporal.Now.instant(),
+    createdBy: "system",
+  };
+}
+
+function stubState(): ConsumerStateRow {
+  return {
+    name: "consumer",
+    instanceId: "shared",
+    lastProcessedEventId: 0n,
+    status: "idle",
+    attempts: 0,
+    rearmCount: 0,
+    lastError: null,
+    updatedAt: Temporal.Now.instant(),
+  };
+}
+
+describe("deliverEvents — per-consumer maxAttempts override", () => {
+  test("stays alive past the dispatcher-wide default when errorPolicy.maxAttempts is higher", async () => {
+    const consumer: EventConsumer = {
+      name: "search",
+      errorPolicy: { maxAttempts: 20 },
+      handler: async () => {
+        throw new Error("meilisearch not provisioned yet");
+      },
+    };
+
+    const outcome = await deliverEvents(
+      consumer,
+      [stubEvent(1n)],
+      stubContext(),
+      /* dispatcher-wide default */ 10,
+      { ...stubState(), attempts: 10 },
+    );
+
+    expect(outcome.attempts).toBe(11);
+    expect(outcome.deadLettered).toBe(false);
+  });
+
+  test("dead-letters at the override once attempts reach it", async () => {
+    const consumer: EventConsumer = {
+      name: "search",
+      errorPolicy: { maxAttempts: 20 },
+      handler: async () => {
+        throw new Error("meilisearch not provisioned yet");
+      },
+    };
+
+    const outcome = await deliverEvents(consumer, [stubEvent(1n)], stubContext(), 10, {
+      ...stubState(),
+      attempts: 19,
+    });
+
+    expect(outcome.attempts).toBe(20);
+    expect(outcome.deadLettered).toBe(true);
+  });
+
+  test("a consumer without the override still dies at the dispatcher-wide default", async () => {
+    const consumer: EventConsumer = {
+      name: "plain",
+      handler: async () => {
+        throw new Error("boom");
+      },
+    };
+
+    const outcome = await deliverEvents(consumer, [stubEvent(1n)], stubContext(), 10, {
+      ...stubState(),
+      attempts: 9,
+    });
+
+    expect(outcome.attempts).toBe(10);
+    expect(outcome.deadLettered).toBe(true);
+  });
+});
+
+describe("createSearchEventConsumer — errorPolicy wiring", () => {
+  test("wires more retry headroom than the dispatcher-wide default", () => {
+    const consumer = createSearchEventConsumer(
+      {} as unknown as Parameters<typeof createSearchEventConsumer>[0],
+      {} as unknown as Parameters<typeof createSearchEventConsumer>[1],
+    );
+
+    expect(consumer.errorPolicy?.maxAttempts).toBeGreaterThan(10);
+  });
+});

package/src/pipeline/__tests__/event-dispatcher-rearm.integration.test.ts

@@ -0,0 +1,180 @@
+// Issue #1350 — bounded auto-revival of a dead consumer.
+//
+// acquireConsumerState no longer parks a dead consumer forever: once its
+// last write is older than rearmCooldownMs it gets reset to idle and
+// retried, up to maxRearmCount times. A poison event (permanent failure)
+// still ends up permanently dead once the budget is exhausted — the
+// mechanism is a bounded number of extra chances, not unlimited retry.
+
+import { afterEach, beforeAll, describe, expect, test } from "bun:test";
+import { createEventStoreExecutor } from "../../db/event-store-executor";
+import { asRawClient } from "../../db/query";
+import { createTenantDb, type TenantDb } from "../../db/tenant-db";
+import { defineFeature } from "../../engine";
+import { getConsumerState } from "../../pipeline";
+import {
+  resetEventStore,
+  setupTestStack,
+  type TestStack,
+  TestUsers,
+  unsafeCreateEntityTable,
+} from "../../stack";
+import { sharedWidgetEntity, sharedWidgetTable } from "../../testing";
+import { SHARED_INSTANCE_SENTINEL } from "../event-consumer-state";
+
+const executor = createEventStoreExecutor(sharedWidgetTable, sharedWidgetEntity, {
+  entityName: "widget",
+});
+
+let poisonNames = new Set<string>();
+let observed: Array<{ name: string }> = [];
+
+const rearmFeature = defineFeature("rearmtest", (r) => {
+  r.entity("widget", sharedWidgetEntity);
+
+  r.multiStreamProjection({
+    name: "observer",
+    apply: {
+      "widget.created": async (event) => {
+        const name = event.payload["name"] as string;
+        if (poisonNames.has(name)) {
+          throw new Error(`poisoned: ${name}`);
+        }
+        observed.push({ name });
+      },
+    },
+  });
+});
+
+const admin = TestUsers.admin;
+const qn = "rearmtest:projection:observer";
+let stack: TestStack;
+let tdb: TenantDb;
+
+beforeAll(async () => {
+  stack = await setupTestStack({
+    features: [rearmFeature],
+    systemHooks: [],
+  });
+  await unsafeCreateEntityTable(stack.db, sharedWidgetEntity, "widget");
+  tdb = createTenantDb(stack.db, admin.tenantId);
+});
+
+afterEach(async () => {
+  poisonNames = new Set();
+  observed = [];
+  await resetEventStore(stack, ["read_widgets"]);
+});
+
+async function appendWidget(name: string): Promise<void> {
+  await executor.create({ name }, admin, tdb);
+}
+
+async function driveUntilDead(): Promise<void> {
+  for (let i = 0; i < 10; i++) {
+    await stack.eventDispatcher?.runOnce();
+  }
+}
+
+// Simulates cooldown elapsed without waiting real wall-clock time.
+async function backdateUpdatedAt(minutesAgo: number): Promise<void> {
+  await asRawClient(stack.db).unsafe(
+    `UPDATE "kumiko_event_consumers" SET "updated_at" = now() - make_interval(mins => $1)
+     WHERE "name" = $2 AND "instance_id" = $3`,
+    [minutesAgo, qn, SHARED_INSTANCE_SENTINEL],
+  );
+}
+
+describe("issue #1350 — bounded dead-consumer re-arm", () => {
+  test("stays dead within the cooldown window", async () => {
+    poisonNames.add("poison");
+    await appendWidget("poison");
+    await driveUntilDead();
+
+    const dead = await getConsumerState(stack.db, qn);
+    expect(dead?.status).toBe("dead");
+    expect(dead?.rearmCount).toBe(0);
+
+    // No backdate — cooldown (5min default) hasn't elapsed.
+    await stack.eventDispatcher?.runOnce();
+    const stillDead = await getConsumerState(stack.db, qn);
+    expect(stillDead?.status).toBe("dead");
+    expect(stillDead?.rearmCount).toBe(0);
+  });
+
+  test("auto-revives once cooldown elapses, and re-dies on the same poison event", async () => {
+    poisonNames.add("poison");
+    await appendWidget("poison");
+    await driveUntilDead();
+
+    await backdateUpdatedAt(10);
+    await stack.eventDispatcher?.runOnce();
+
+    const revived = await getConsumerState(stack.db, qn);
+    expect(revived?.status).toBe("idle");
+    expect(revived?.rearmCount).toBe(1);
+    // Same pass that revives it also retries the pending poisoned event —
+    // acquireConsumerState's reset (attempts=0) is followed immediately by
+    // one failed delivery attempt within this runOnce() call.
+    expect(revived?.attempts).toBe(1);
+
+    // Handler still throws on "poison" — climbs back to dead.
+    await driveUntilDead();
+    const deadAgain = await getConsumerState(stack.db, qn);
+    expect(deadAgain?.status).toBe("dead");
+    expect(deadAgain?.rearmCount).toBe(1);
+  });
+
+  test("a re-arm that leads to a real delivery resets rearmCount to 0", async () => {
+    poisonNames.add("poison");
+    await appendWidget("poison");
+    await driveUntilDead();
+
+    // Cause is gone by the time the cooldown elapses — the retried event
+    // now succeeds instead of re-poisoning the consumer.
+    poisonNames.delete("poison");
+    await backdateUpdatedAt(10);
+    await stack.eventDispatcher?.runOnce();
+
+    const recovered = await getConsumerState(stack.db, qn);
+    expect(recovered?.status).toBe("idle");
+    expect(recovered?.rearmCount).toBe(0);
+    expect(observed.map((o) => o.name)).toEqual(["poison"]);
+
+    // A later, unrelated poison event gets its own fresh maxRearmCount
+    // budget instead of inheriting the spent counter from the resolved one.
+    poisonNames.add("later-poison");
+    await appendWidget("later-poison");
+    await driveUntilDead();
+    const deadAgain = await getConsumerState(stack.db, qn);
+    expect(deadAgain?.status).toBe("dead");
+    expect(deadAgain?.rearmCount).toBe(0);
+  });
+
+  test("permanently dead after maxRearmCount cycles, even once cooldown elapses again", async () => {
+    poisonNames.add("poison");
+    await appendWidget("poison");
+    await driveUntilDead();
+
+    // Cycles 1..3: each backdate+drive re-arms once, then re-dies on the
+    // same poison event. Default maxRearmCount is 3.
+    for (let cycle = 1; cycle <= 3; cycle++) {
+      await backdateUpdatedAt(10);
+      await stack.eventDispatcher?.runOnce();
+      const revived = await getConsumerState(stack.db, qn);
+      expect(revived?.rearmCount).toBe(cycle);
+      await driveUntilDead();
+    }
+
+    const exhausted = await getConsumerState(stack.db, qn);
+    expect(exhausted?.status).toBe("dead");
+    expect(exhausted?.rearmCount).toBe(3);
+
+    // Cooldown elapsed again, but the budget is spent — stays dead.
+    await backdateUpdatedAt(10);
+    await stack.eventDispatcher?.runOnce();
+    const stillExhausted = await getConsumerState(stack.db, qn);
+    expect(stillExhausted?.status).toBe("dead");
+    expect(stillExhausted?.rearmCount).toBe(3);
+  });
+});