@cosmicdrift/kumiko-framework 0.1.0

package/src/observability/types/metric.ts

@@ -0,0 +1,56 @@
+// 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;
+}

package/src/observability/types/provider.ts

@@ -0,0 +1,32 @@
+// 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>;
+}

package/src/observability/types/span.ts

@@ -0,0 +1,64 @@
+// 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;
+  // @deprecated Prefer `startSpan(name, { parent: context })`.
+  startSpanFromContext(
+    name: string,
+    context: SerializedTraceContext,
+    options?: StartSpanOptions,
+  ): Span;
+}

package/src/pipeline/__tests__/archive-stream.integration.ts

@@ -0,0 +1,220 @@
+// C2 — archiveStream (Marten-aligned).
+//
+// Marten's session.Events.ArchiveStream(id): the stream becomes read-only,
+// loads return an empty slice, further appends throw. Restoring un-archives.
+// Kumiko carries this as a sparse kumiko_archived_streams table so active
+// streams never pay for extra metadata writes.
+
+import { afterAll, afterEach, beforeAll, describe, expect, test } from "vitest";
+import { z } from "zod";
+import { createEventStoreExecutor } from "../../db/event-store-executor";
+import { buildDrizzleTable } from "../../db/table-builder";
+import { createEntity, createTextField, defineFeature } from "../../engine";
+import {
+  ArchivedStreamError,
+  isStreamArchived,
+  loadAggregate as loadAggregateRaw,
+} from "../../event-store";
+import {
+  createEntityTable,
+  resetEventStore,
+  setupTestStack,
+  type TestStack,
+  TestUsers,
+} from "../../stack";
+
+const itemEntity = createEntity({
+  table: "read_arch_items",
+  fields: { label: createTextField({ required: true }) },
+});
+const itemTable = buildDrizzleTable("arch-item", itemEntity);
+
+const archFeature = defineFeature("archtest", (r) => {
+  r.entity("arch-item", itemEntity);
+
+  const labelChanged = r.defineEvent("label-changed", z.object({ label: z.string() }));
+
+  const executor = createEventStoreExecutor(itemTable, itemEntity, {
+    entityName: "arch-item",
+  });
+
+  r.writeHandler(
+    "item:create",
+    z.object({ label: z.string() }),
+    async (event, ctx) => executor.create(event.payload, event.user, ctx.db),
+    { access: { roles: ["Admin"] } },
+  );
+
+  r.writeHandler(
+    "item:relabel",
+    z.object({ id: z.uuid(), label: z.string() }),
+    async (event, ctx) => {
+      await ctx.appendEventUnsafe({
+        aggregateId: event.payload.id,
+        aggregateType: "arch-item",
+        type: labelChanged.name,
+        payload: { label: event.payload.label },
+      });
+      return { isSuccess: true as const, data: { id: event.payload.id } };
+    },
+    { access: { roles: ["Admin"] } },
+  );
+
+  r.writeHandler(
+    "item:archive",
+    z.object({ id: z.uuid(), reason: z.string().optional() }),
+    async (event, ctx) => {
+      await ctx.archiveStream(event.payload.id, {
+        aggregateType: "arch-item",
+        reason: event.payload.reason,
+      });
+      return { isSuccess: true as const, data: { id: event.payload.id } };
+    },
+    { access: { roles: ["Admin"] } },
+  );
+
+  r.writeHandler(
+    "item:restore",
+    z.object({ id: z.uuid() }),
+    async (event, ctx) => {
+      await ctx.restoreStream(event.payload.id);
+      return { isSuccess: true as const, data: { id: event.payload.id } };
+    },
+    { access: { roles: ["Admin"] } },
+  );
+
+  r.queryHandler(
+    "item:events",
+    z.object({ id: z.uuid() }),
+    async (query, ctx) => ctx.loadAggregate(query.payload.id),
+    { access: { openToAll: true } },
+  );
+
+  r.queryHandler(
+    "item:is-archived",
+    z.object({ id: z.uuid() }),
+    async (query, ctx) => ctx.isStreamArchived(query.payload.id),
+    { access: { openToAll: true } },
+  );
+});
+
+let stack: TestStack;
+const admin = TestUsers.admin;
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [archFeature], systemHooks: [] });
+  await createEntityTable(stack.db, itemEntity, "arch-item");
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+afterEach(async () => {
+  await resetEventStore(stack, ["read_arch_items"]);
+});
+
+describe("archiveStream — Marten ArchiveStream equivalent", () => {
+  test("archived stream returns empty from ctx.loadAggregate", async () => {
+    const { id } = await stack.http.writeOk<{ id: string }>(
+      "archtest:write:item:create",
+      { label: "alpha" },
+      admin,
+    );
+    await stack.http.writeOk("archtest:write:item:relabel", { id, label: "beta" }, admin);
+
+    // Pre-archive: two events visible.
+    const before = await stack.http.queryOk<unknown[]>("archtest:query:item:events", { id }, admin);
+    expect(before.length).toBe(2);
+
+    await stack.http.writeOk("archtest:write:item:archive", { id, reason: "cleanup" }, admin);
+
+    // Post-archive: empty slice by default.
+    const after = await stack.http.queryOk<unknown[]>("archtest:query:item:events", { id }, admin);
+    expect(after).toEqual([]);
+
+    // Archive flag is visible.
+    const archived = await stack.http.queryOk<boolean>(
+      "archtest:query:item:is-archived",
+      { id },
+      admin,
+    );
+    expect(archived).toBe(true);
+
+    // Low-level loader with includeArchived surfaces the events for ops.
+    const raw = await loadAggregateRaw(stack.db, id, admin.tenantId, {
+      includeArchived: true,
+    });
+    expect(raw).toHaveLength(2);
+  });
+
+  test("appendEvent on an archived stream is rejected with ArchivedStreamError", async () => {
+    const { id } = await stack.http.writeOk<{ id: string }>(
+      "archtest:write:item:create",
+      { label: "before-archive" },
+      admin,
+    );
+    await stack.http.writeOk("archtest:write:item:archive", { id }, admin);
+
+    // Writing through the handler surfaces the ArchivedStreamError as a
+    // 500 (InternalError path) — the framework treats archive violations
+    // as logic errors, not user-input errors. The detail message is
+    // masked in the HTTP response (don't leak internals), so the proof
+    // is structural: 500 status + no event landed on disk.
+    const res = await stack.http.write(
+      "archtest:write:item:relabel",
+      { id, label: "too-late" },
+      admin,
+    );
+    expect(res.status).toBe(500);
+
+    // Sanity: the failed write did not land on disk.
+    const raw = await loadAggregateRaw(stack.db, id, admin.tenantId, {
+      includeArchived: true,
+    });
+    const types = raw.map((e) => e.type);
+    expect(types).toContain("arch-item.created");
+    expect(types).not.toContain("archtest:event:label-changed");
+  });
+
+  test("restoreStream reopens the stream for writes and reads", async () => {
+    const { id } = await stack.http.writeOk<{ id: string }>(
+      "archtest:write:item:create",
+      { label: "phoenix" },
+      admin,
+    );
+    await stack.http.writeOk("archtest:write:item:archive", { id }, admin);
+    expect(await isStreamArchived(stack.db, admin.tenantId, id)).toBe(true);
+
+    await stack.http.writeOk("archtest:write:item:restore", { id }, admin);
+    expect(await isStreamArchived(stack.db, admin.tenantId, id)).toBe(false);
+
+    // Writes go through again AND keep the correct version lineage —
+    // the original "created" event is at version 1, so the post-restore
+    // relabel lands at version 2.
+    await stack.http.writeOk("archtest:write:item:relabel", { id, label: "reborn" }, admin);
+    const events = await loadAggregateRaw(stack.db, id, admin.tenantId);
+    expect(events.map((e) => e.version)).toEqual([1, 2]);
+  });
+
+  test("archive is idempotent — repeated archive calls do not throw", async () => {
+    const { id } = await stack.http.writeOk<{ id: string }>(
+      "archtest:write:item:create",
+      { label: "repeat" },
+      admin,
+    );
+
+    await stack.http.writeOk("archtest:write:item:archive", { id, reason: "first" }, admin);
+    await stack.http.writeOk("archtest:write:item:archive", { id, reason: "second" }, admin);
+
+    const archived = await isStreamArchived(stack.db, admin.tenantId, id);
+    expect(archived).toBe(true);
+  });
+
+  test("ArchivedStreamError carries aggregateId + tenantId", () => {
+    const err = new ArchivedStreamError(admin.tenantId, "agg-1");
+    expect(err.aggregateId).toBe("agg-1");
+    expect(err.tenantId).toBe(admin.tenantId);
+    expect(err.name).toBe("ArchivedStreamError");
+  });
+});

package/src/pipeline/__tests__/auth-claims-resolver.test.ts

@@ -0,0 +1,279 @@
+import { describe, expect, test, vi } from "vitest";
+import type { AuthClaimsContext, AuthClaimsHookDef, SessionUser } from "../../engine/types";
+import type { Logger } from "../../logging/types";
+import { resolveAuthClaims } from "../auth-claims-resolver";
+
+type TestLogger = {
+  readonly log: Logger;
+  readonly warn: ReturnType<typeof vi.fn>;
+};
+
+function makeTestLogger(): TestLogger {
+  const warn = vi.fn();
+  const info = vi.fn();
+  const error = vi.fn();
+  const debug = vi.fn();
+  const logger: Logger = {
+    warn,
+    info,
+    error,
+    debug,
+    child: () => logger,
+  };
+  return { log: logger, warn };
+}
+
+const testUser: SessionUser = {
+  id: "11111111-0000-4000-8000-000000000001",
+  tenantId: "22222222-0000-4000-8000-000000000001",
+  roles: ["User"],
+};
+
+// The resolver doesn't actually USE the AuthClaimsContext — it passes it
+// through to each hook. For unit tests we only need the shape; we don't
+// construct a real TenantDb.
+const stubContext: AuthClaimsContext = {
+  db: {} as AuthClaimsContext["db"],
+  queryAs: async () => {
+    throw new Error("queryAs not implemented in stub");
+  },
+};
+
+function hooks(...entries: AuthClaimsHookDef[]): readonly AuthClaimsHookDef[] {
+  return entries;
+}
+
+describe("resolveAuthClaims — empty", () => {
+  test("zero hooks registered → empty record, contextFactory not called", async () => {
+    const factory = vi.fn();
+    const result = await resolveAuthClaims({
+      user: testUser,
+      hooks: [],
+      contextFactory: factory,
+    });
+    expect(result).toEqual({});
+    expect(factory).not.toHaveBeenCalled();
+  });
+});
+
+describe("resolveAuthClaims — single hook", () => {
+  test("feature's keys get prefixed with <featureName>:", async () => {
+    const result = await resolveAuthClaims({
+      user: testUser,
+      hooks: hooks({
+        featureName: "drivers",
+        fn: async () => ({ teamId: "t-1", regionId: "r-7" }),
+      }),
+      contextFactory: () => stubContext,
+    });
+    expect(result).toEqual({
+      "drivers:teamId": "t-1",
+      "drivers:regionId": "r-7",
+    });
+  });
+
+  test("receives the user and context handed in", async () => {
+    const fn = vi.fn(async () => ({}));
+    const factory = vi.fn(() => stubContext);
+    await resolveAuthClaims({
+      user: testUser,
+      hooks: hooks({ featureName: "any", fn }),
+      contextFactory: factory,
+    });
+    expect(fn).toHaveBeenCalledWith(testUser, stubContext);
+    expect(factory).toHaveBeenCalledWith(testUser);
+    expect(factory).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe("resolveAuthClaims — multiple hooks", () => {
+  test("two features run in parallel and both contribute claims", async () => {
+    const ordering: string[] = [];
+    const result = await resolveAuthClaims({
+      user: testUser,
+      hooks: hooks(
+        {
+          featureName: "drivers",
+          fn: async () => {
+            ordering.push("drivers");
+            return { teamId: "t-1" };
+          },
+        },
+        {
+          featureName: "billing",
+          fn: async () => {
+            ordering.push("billing");
+            return { plan: "pro" };
+          },
+        },
+      ),
+      contextFactory: () => stubContext,
+    });
+    expect(result).toEqual({
+      "drivers:teamId": "t-1",
+      "billing:plan": "pro",
+    });
+    // Promise.allSettled fires both; order of push() can vary but both must run.
+    expect(ordering.sort()).toEqual(["billing", "drivers"]);
+  });
+
+  test("auto-prefix eliminates cross-feature collisions on the SAME inner key", async () => {
+    const result = await resolveAuthClaims({
+      user: testUser,
+      hooks: hooks(
+        { featureName: "drivers", fn: async () => ({ teamId: "t-drivers" }) },
+        { featureName: "billing", fn: async () => ({ teamId: "t-billing" }) },
+      ),
+      contextFactory: () => stubContext,
+    });
+    expect(result).toEqual({
+      "drivers:teamId": "t-drivers",
+      "billing:teamId": "t-billing",
+    });
+  });
+});
+
+describe("resolveAuthClaims — same-feature duplicate hooks", () => {
+  test("last-wins within one feature", async () => {
+    // Two r.authClaims() calls in the same feature both return `plan`.
+    // The second registration wins (matches the JWT-layer spread semantics).
+    const result = await resolveAuthClaims({
+      user: testUser,
+      hooks: hooks(
+        { featureName: "billing", fn: async () => ({ plan: "free" }) },
+        { featureName: "billing", fn: async () => ({ plan: "enterprise" }) },
+      ),
+      contextFactory: () => stubContext,
+    });
+    expect(result["billing:plan"]).toBe("enterprise");
+  });
+});
+
+describe("resolveAuthClaims — error policy (best-effort)", () => {
+  test("one hook throws → its feature contributes nothing, others unaffected", async () => {
+    const { log, warn } = makeTestLogger();
+    const result = await resolveAuthClaims({
+      user: testUser,
+      hooks: hooks(
+        {
+          featureName: "broken",
+          fn: async () => {
+            throw new Error("db blew up");
+          },
+        },
+        {
+          featureName: "healthy",
+          fn: async () => ({ teamId: "t-1" }),
+        },
+      ),
+      contextFactory: () => stubContext,
+      log,
+    });
+    // healthy feature's claims make it into the record; broken feature's do not.
+    expect(result).toEqual({ "healthy:teamId": "t-1" });
+    // The warn should mention the feature name so ops can pinpoint the hook.
+    expect(warn).toHaveBeenCalledTimes(1);
+    const [warnMsg, warnData] = warn.mock.calls[0] ?? [];
+    expect(String(warnMsg)).toContain("authClaims");
+    expect(warnData).toMatchObject({ featureName: "broken" });
+  });
+
+  test("every hook throws → result is still an object (login does not fail)", async () => {
+    const { log } = makeTestLogger();
+    const result = await resolveAuthClaims({
+      user: testUser,
+      hooks: hooks(
+        {
+          featureName: "a",
+          fn: async () => {
+            throw new Error("x");
+          },
+        },
+        {
+          featureName: "b",
+          fn: async () => {
+            throw new Error("y");
+          },
+        },
+      ),
+      contextFactory: () => stubContext,
+      log,
+    });
+    expect(result).toEqual({});
+  });
+});
+
+describe("resolveAuthClaims — reserved separator guard", () => {
+  test("a key containing ':' is dropped with a warning (keeps prefix owned by framework)", async () => {
+    const { log, warn } = makeTestLogger();
+    const result = await resolveAuthClaims({
+      user: testUser,
+      hooks: hooks({
+        featureName: "smart",
+        // A feature that tries to sneak in its own prefix would bypass
+        // auto-prefix intent — so we reject such keys rather than double-prefix.
+        fn: async () => ({ "evil:teamId": "nope", okKey: "yes" }),
+      }),
+      contextFactory: () => stubContext,
+      log,
+    });
+    expect(result).toEqual({ "smart:okKey": "yes" });
+    expect(warn).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe("resolveAuthClaims — declaredKeys drift warning", () => {
+  test("hook returns a key NOT in declaredKeys → warn, but claim still lands in JWT", async () => {
+    const { log, warn } = makeTestLogger();
+    const result = await resolveAuthClaims({
+      user: testUser,
+      hooks: hooks({
+        featureName: "drivers",
+        // Feature declared `teamId` but the hook also returns `rouge` — the
+        // resolver flags it (typo/rename protection) but still merges it in,
+        // honoring best-effort.
+        declaredKeys: new Set(["teamId"]),
+        fn: async () => ({ teamId: "t-1", rouge: "x" }),
+      }),
+      contextFactory: () => stubContext,
+      log,
+    });
+    expect(result).toEqual({
+      "drivers:teamId": "t-1",
+      "drivers:rouge": "x",
+    });
+    expect(warn).toHaveBeenCalledTimes(1);
+    const [, data] = warn.mock.calls[0] ?? [];
+    expect(data).toMatchObject({ featureName: "drivers", undeclaredKey: "rouge" });
+  });
+
+  test("declaredKeys undefined → never warn, backwards-compat for ad-hoc hooks", async () => {
+    const { log, warn } = makeTestLogger();
+    await resolveAuthClaims({
+      user: testUser,
+      hooks: hooks({
+        featureName: "legacy",
+        // No declaredKeys on this hook — legacy hooks don't opt in.
+        fn: async () => ({ anything: 1, else: 2 }),
+      }),
+      contextFactory: () => stubContext,
+      log,
+    });
+    expect(warn).not.toHaveBeenCalled();
+  });
+
+  test("all returned keys declared → silent", async () => {
+    const { log, warn } = makeTestLogger();
+    await resolveAuthClaims({
+      user: testUser,
+      hooks: hooks({
+        featureName: "drivers",
+        declaredKeys: new Set(["teamId", "regionId"]),
+        fn: async () => ({ teamId: "t-1", regionId: 7 }),
+      }),
+      contextFactory: () => stubContext,
+      log,
+    });
+    expect(warn).not.toHaveBeenCalled();
+  });
+});