@cosmicdrift/kumiko-framework 0.157.2 → 0.159.1

package/src/i18n/required-surface-keys.ts

@@ -1,3 +1,4 @@
+import { isExtensionEditSection, normalizeListColumn } from "../engine/screen-helpers";
 import type {
   ActionFormScreenDefinition,
   ConfigEditScreenDefinition,
@@ -15,7 +16,6 @@ import type {
   ToolbarAction,
   WorkspaceDefinition,
 } from "../engine/types";
-import { isExtensionEditSection, normalizeListColumn } from "../engine/types/screen";
 
 /** Pseudo-entity for actionForm field labels (renderer action-form-shim). */
 export const ACTION_FORM_ENTITY = "__action-form__";

package/src/logging/types.ts

@@ -1,7 +1 @@
-export type Logger = {
-  info(msg: string, data?: Record<string, unknown>): void;
-  warn(msg: string, data?: Record<string, unknown>): void;
-  error(msg: string, data?: Record<string, unknown>): void;
-  debug(msg: string, data?: Record<string, unknown>): void;
-  child(context: Record<string, unknown>): Logger;
-};
+export * from "@cosmicdrift/kumiko-types/logger";

package/src/observability/types/index.ts

@@ -1,29 +1 @@
-// Barrel for observability types. Split into span/metric/provider files so
-// each module stays focused; consumers still import from "./types".
-
-export type {
-  Counter,
-  Gauge,
-  Histogram,
-  Meter,
-  MetricDefinition,
-  MetricLabels,
-  MetricsHandle,
-  MetricType,
-} from "./metric";
-export type {
-  ObservabilityOptions,
-  ObservabilityProvider,
-  SamplingConfig,
-  SensitiveFilterConfig,
-} from "./provider";
-export type {
-  SerializedTraceContext,
-  Span,
-  SpanAttributes,
-  SpanAttributeValue,
-  SpanKind,
-  SpanStatus,
-  StartSpanOptions,
-  Tracer,
-} from "./span";
+export * from "@cosmicdrift/kumiko-types/observability";

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

@@ -509,7 +509,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 +533,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);
+  });
+});

package/src/pipeline/dispatch-shared.ts

@@ -484,8 +484,18 @@ export function buildHandlerContext(
     // When the feature-toggles or tier-engine feature isn't wired (no
     // effectiveFeatures callback), always returns true — apps without
     // tier-cuts treat all features on.
-    hasFeature: (featureName: string): boolean =>
-      effectiveFeatures ? effectiveFeatures(user.tenantId).has(featureName) : true,
+    //
+    // Falls back to the live trialGate when the sync set says the feature
+    // is off — the sync set never contains trial-tier features (time-
+    // derived, can't boot-cache), so without this a trial tenant checking
+    // a companion feature's toggle would silently read `false` even though
+    // the dispatch gate already lets trial-tier handlers run.
+    hasFeature: async (featureName: string): Promise<boolean> => {
+      if (!effectiveFeatures) return true;
+      if (effectiveFeatures(user.tenantId).has(featureName)) return true;
+      if (!effectiveFeatures.trialGate) return false;
+      return effectiveFeatures.trialGate(user.tenantId, featureName);
+    },
   };
 
   // Registry is always the dispatcher's registry — injecting it here lets

package/src/pipeline/entity-cache.ts

@@ -1,3 +1,4 @@
+import type { EntityCache } from "@cosmicdrift/kumiko-types/entity-cache";
 import type Redis from "ioredis";
 import type { EntityId, TenantId } from "../engine/types/identifiers";
 import { RedisKeys } from "./redis-keys";
@@ -23,39 +24,7 @@ function parseCached(raw: string): Record<string, unknown> | null {
   }
 }
 
-export type EntityCache = {
-  /** Get a single cached entity. Returns null on miss. */
-  get(
-    tenantId: TenantId,
-    entityName: string,
-    id: EntityId,
-  ): Promise<Record<string, unknown> | null>;
-
-  /** Get multiple cached entities. Returns a Map of id → data (misses are absent). */
-  mget(
-    tenantId: TenantId,
-    entityName: string,
-    ids: readonly EntityId[],
-  ): Promise<Map<EntityId, Record<string, unknown>>>;
-
-  /** Cache a single entity. */
-  set(
-    tenantId: TenantId,
-    entityName: string,
-    id: EntityId,
-    data: Record<string, unknown>,
-  ): Promise<void>;
-
-  /** Cache multiple entities at once. */
-  mset(
-    tenantId: TenantId,
-    entityName: string,
-    entries: ReadonlyArray<{ id: EntityId; data: Record<string, unknown> }>,
-  ): Promise<void>;
-
-  /** Invalidate a single cached entity. */
-  del(tenantId: TenantId, entityName: string, id: EntityId): Promise<void>;
-};
+export type { EntityCache } from "@cosmicdrift/kumiko-types/entity-cache";
 
 export type EntityCacheOptions = {
   ttlSeconds?: number;