@cosmicdrift/kumiko-framework 0.230.0 → 0.231.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.230.0",
+  "version": "0.231.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -198,7 +198,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-types": "0.230.0",
+    "@cosmicdrift/kumiko-types": "0.231.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -214,7 +214,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.230.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.231.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/compliance/__tests__/sub-processors.test.ts

@@ -82,16 +82,6 @@ describe("KUMIKO_SUB_PROCESSORS", () => {
           "sccRequired": false,
           "status": "active",
         },
-        {
-          "appliesTo": [
-            "all-tiers",
-          ],
-          "name": "Heinlein Hosting (Mailbox.org)",
-          "optInOnly": false,
-          "region": "EU (Germany)",
-          "sccRequired": false,
-          "status": "active",
-        },
         {
           "appliesTo": [
             "business",
@@ -101,7 +91,7 @@ describe("KUMIKO_SUB_PROCESSORS", () => {
           "optInOnly": true,
           "region": "US",
           "sccRequired": true,
-          "status": "planned",
+          "status": "active",
         },
         {
           "appliesTo": [
@@ -111,7 +101,17 @@ describe("KUMIKO_SUB_PROCESSORS", () => {
           "optInOnly": false,
           "region": "Global (US-headquartered)",
           "sccRequired": true,
-          "status": "planned",
+          "status": "active",
+        },
+        {
+          "appliesTo": [
+            "all-tiers",
+          ],
+          "name": "ALL-INKL.COM – Neue Medien Münnich",
+          "optInOnly": false,
+          "region": "EU (Germany)",
+          "sccRequired": false,
+          "status": "active",
         },
       ]
     `);

package/src/compliance/sub-processors.ts

@@ -101,15 +101,6 @@ export const KUMIKO_SUB_PROCESSORS: readonly SubProcessor[] = [
     appliesTo: ["standard", "business", "enterprise"],
     status: "active",
   },
-  {
-    name: "Heinlein Hosting (Mailbox.org)",
-    purpose: "Marketing Email Delivery",
-    region: "EU (Germany)",
-    dpa: "https://mailbox.org/de/datenschutzerklaerung",
-    addedAt: "2024-03-01",
-    appliesTo: ["all-tiers"],
-    status: "active",
-  },
   {
     name: "Anthropic PBC",
     purpose: "AI Model Inference (L2 Composition Layer, AI-Foundation)",
@@ -120,7 +111,7 @@ export const KUMIKO_SUB_PROCESSORS: readonly SubProcessor[] = [
     sccRequired: true,
     optInOnly: true,
     hipaaBaaAvailable: true,
-    status: "planned",
+    status: "active",
   },
   {
     name: "Stripe, Inc.",
@@ -130,7 +121,16 @@ export const KUMIKO_SUB_PROCESSORS: readonly SubProcessor[] = [
     addedAt: "2026-06-01",
     appliesTo: ["all-tiers"],
     sccRequired: true,
-    status: "planned",
+    status: "active",
+  },
+  {
+    name: "ALL-INKL.COM – Neue Medien Münnich",
+    purpose: "Mailbox Hosting (support and contact mailboxes)",
+    region: "EU (Germany)",
+    dpa: "https://all-inkl.com/members/avv_muster_print.php",
+    addedAt: "2026-09-02",
+    appliesTo: ["all-tiers"],
+    status: "active",
   },
 ];
 

package/src/engine/__tests__/steps-workflow.test.ts

@@ -1,5 +1,6 @@
 import { beforeEach, describe, expect, it, mock } from "bun:test";
 import { getStep } from "../define-step";
+import { evaluateEventMatch } from "../steps/_event-match";
 import {
   SUSPEND_SENTINEL,
   WORKFLOW_AGGREGATE_TYPE,
@@ -9,7 +10,7 @@ import {
 import { buildRetryStep, calculateBackoff } from "../steps/retry";
 import { buildWaitStep } from "../steps/wait";
 import { buildWaitForEventStep } from "../steps/wait-for-event";
-import type { PipelineCtx } from "../types/step";
+import type { EventMatch, PipelineCtx } from "../types/step";
 
 const mockUnsafeAppendEvent = mock();
 
@@ -96,10 +97,14 @@ describe("buildWaitForEventStep", () => {
     expect(step.kind).toBe("workflow.waitForEvent");
   });
 
-  it("accepts an optional match resolver", () => {
+  it("accepts an optional match AST", () => {
+    const match: EventMatch = {
+      version: 1,
+      expr: { kind: "atom", path: ["email"], op: { kind: "eq", value: "test@test.com" } },
+    };
     const step = buildWaitForEventStep({
       event: "user.confirmed-email",
-      match: (payload: unknown) => (payload as { email: string }).email === "test@test.com",
+      match,
       timeout: "P7D",
     });
     expect(step.kind).toBe("workflow.waitForEvent");
@@ -138,6 +143,144 @@ describe("workflow.waitForEvent run", () => {
     expect(typeof eventArg.payload.timeoutAt).toBe("string");
     expect(eventArg.payload.workflowName).toBe("test-workflow");
   });
+
+  it("omits the match key from the payload when no match is given", async () => {
+    const stepDef = getStep("workflow.waitForEvent");
+    expect(stepDef).toBeDefined();
+
+    await stepDef!.run({ event: "user.confirmed-email", timeout: "P7D" }, workflowCtx);
+
+    const eventArg = mockUnsafeAppendEvent.mock.calls[0]![0];
+    expect("match" in eventArg.payload).toBe(false);
+  });
+
+  it("resolves a match resolver to a serializable AST that round-trips through JSON and evaluates against real payloads", async () => {
+    const stepDef = getStep("workflow.waitForEvent");
+    expect(stepDef).toBeDefined();
+
+    const result = await stepDef!.run(
+      {
+        event: "user.confirmed-email",
+        match: (ctx: PipelineCtx): EventMatch => ({
+          version: 1,
+          expr: {
+            kind: "atom",
+            path: ["email"],
+            op: { kind: "eq", value: (ctx.event.payload as { email: string }).email },
+          },
+        }),
+        timeout: "P7D",
+      },
+      workflowCtx,
+    );
+
+    expect(result).toBe(SUSPEND_SENTINEL);
+    const eventArg = mockUnsafeAppendEvent.mock.calls[0]![0];
+    const persistedMatch = eventArg.payload.match;
+
+    // Proves the persisted value is the resolved literal AST, not the resolver function.
+    expect(persistedMatch).toEqual({
+      version: 1,
+      expr: {
+        kind: "atom",
+        path: ["email"],
+        op: { kind: "eq", value: "test@example.com" },
+      },
+    });
+
+    // Proves serializability — the whole point of the AST switch — by round-tripping
+    // through JSON before feeding it to the evaluator, same as a rehydrated event would.
+    const roundTripped = JSON.parse(JSON.stringify(persistedMatch));
+    expect(evaluateEventMatch(roundTripped, { email: "test@example.com" })).toBe(true);
+    expect(evaluateEventMatch(roundTripped, { email: "someone-else@example.com" })).toBe(false);
+  });
+});
+
+describe("evaluateEventMatch", () => {
+  it("throws on an unsupported version", () => {
+    const stale = JSON.parse(
+      JSON.stringify({
+        version: 2,
+        expr: { kind: "atom", path: ["x"], op: { kind: "eq", value: 1 } },
+      }),
+    );
+    expect(() => evaluateEventMatch(stale, {})).toThrow(/version/i);
+  });
+
+  it("throws on an unrecognized expr kind", () => {
+    const bad = JSON.parse(JSON.stringify({ version: 1, expr: { kind: "not-a-kind" } }));
+    expect(() => evaluateEventMatch(bad, {})).toThrow(/kind/i);
+  });
+
+  it("throws on an unrecognized op kind", () => {
+    const bad = JSON.parse(
+      JSON.stringify({
+        version: 1,
+        expr: { kind: "atom", path: ["x"], op: { kind: "not-an-op" } },
+      }),
+    );
+    expect(() => evaluateEventMatch(bad, {})).toThrow(/kind/i);
+  });
+
+  it("and with empty nodes is true, or with empty nodes is false", () => {
+    expect(evaluateEventMatch({ version: 1, expr: { kind: "and", nodes: [] } }, {})).toBe(true);
+    expect(evaluateEventMatch({ version: 1, expr: { kind: "or", nodes: [] } }, {})).toBe(false);
+  });
+
+  it("combines atoms with and/or", () => {
+    const match: EventMatch = {
+      version: 1,
+      expr: {
+        kind: "and",
+        nodes: [
+          { kind: "atom", path: ["status"], op: { kind: "eq", value: "confirmed" } },
+          { kind: "atom", path: ["tier"], op: { kind: "in", values: ["gold", "platinum"] } },
+        ],
+      },
+    };
+    expect(evaluateEventMatch(match, { status: "confirmed", tier: "gold" })).toBe(true);
+    expect(evaluateEventMatch(match, { status: "confirmed", tier: "silver" })).toBe(false);
+  });
+
+  it("ne matches when the resolved value differs", () => {
+    const match: EventMatch = {
+      version: 1,
+      expr: { kind: "atom", path: ["status"], op: { kind: "ne", value: "cancelled" } },
+    };
+    expect(evaluateEventMatch(match, { status: "confirmed" })).toBe(true);
+    expect(evaluateEventMatch(match, { status: "cancelled" })).toBe(false);
+  });
+
+  it("compares numbers with gte", () => {
+    const match: EventMatch = {
+      version: 1,
+      expr: { kind: "atom", path: ["amount"], op: { kind: "gte", value: 100 } },
+    };
+    expect(evaluateEventMatch(match, { amount: 150 })).toBe(true);
+    expect(evaluateEventMatch(match, { amount: 50 })).toBe(false);
+  });
+
+  it("does not match a comparison op when the payload value's type differs from the operand", () => {
+    const match: EventMatch = {
+      version: 1,
+      expr: { kind: "atom", path: ["amount"], op: { kind: "gt", value: 100 } },
+    };
+    expect(evaluateEventMatch(match, { amount: "150" })).toBe(false);
+  });
+
+  it("resolves nested paths and treats a path running into a non-object as unmatched", () => {
+    const match: EventMatch = {
+      version: 1,
+      expr: {
+        kind: "atom",
+        path: ["user", "email"],
+        op: { kind: "eq", value: "a@b.com" },
+      },
+    };
+    expect(evaluateEventMatch(match, { user: { email: "a@b.com" } })).toBe(true);
+    expect(evaluateEventMatch(match, { user: "not-an-object" })).toBe(false);
+    expect(evaluateEventMatch(match, {})).toBe(false);
+  });
 });
 
 describe("buildRetryStep", () => {

package/src/engine/index.ts

@@ -247,6 +247,7 @@ export {
 } from "./screen-helpers";
 export type { TransitionGraph } from "./state-machine";
 export { defineTransitions, guardTransition } from "./state-machine";
+export { evaluateEventMatch } from "./steps/_event-match";
 export {
   SUSPEND_SENTINEL,
   WORKFLOW_AGGREGATE_TYPE,

package/src/engine/steps/_event-match.ts

@@ -0,0 +1,98 @@
+// Evaluator for the persisted r.step.waitForEvent `match` AST (EventMatch).
+// Runtime-only: kept in the framework package (not packages/types) so it
+// stays out of the type graph, same steps/-vs-packages/types split as
+// _duration-utils.ts.
+
+import type { EventMatch, EventMatchExpr, EventMatchOp } from "../types/step";
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+function resolvePath(payload: unknown, path: readonly string[]): unknown {
+  let current: unknown = payload;
+  for (const segment of path) {
+    if (!isRecord(current)) return undefined;
+    current = current[segment];
+  }
+  return current;
+}
+
+function compareOrdered(
+  actual: number | string,
+  expected: number | string,
+  kind: "gt" | "gte" | "lt" | "lte",
+): boolean {
+  if (typeof actual === "number" && typeof expected === "number") {
+    switch (kind) {
+      case "gt":
+        return actual > expected;
+      case "gte":
+        return actual >= expected;
+      case "lt":
+        return actual < expected;
+      case "lte":
+        return actual <= expected;
+    }
+  }
+  if (typeof actual === "string" && typeof expected === "string") {
+    switch (kind) {
+      case "gt":
+        return actual > expected;
+      case "gte":
+        return actual >= expected;
+      case "lt":
+        return actual < expected;
+      case "lte":
+        return actual <= expected;
+    }
+  }
+  return false;
+}
+
+function evaluateOp(op: EventMatchOp, actual: unknown): boolean {
+  switch (op.kind) {
+    case "eq":
+      return actual === op.value;
+    case "ne":
+      return actual !== op.value;
+    case "in":
+      return op.values.some((value) => value === actual);
+    case "gt":
+    case "gte":
+    case "lt":
+    case "lte":
+      // A payload value of a different primitive kind than the operand
+      // doesn't match — bad input, not a malformed AST.
+      if (typeof actual !== "number" && typeof actual !== "string") return false;
+      return compareOrdered(actual, op.value, op.kind);
+    default: {
+      // op.kind comes from a persisted event, not from this call's static
+      // type — an unrecognized kind means a format we don't understand.
+      const unrecognized: { readonly kind: string } = op;
+      throw new Error(`Unknown EventMatchOp kind "${unrecognized.kind}"`);
+    }
+  }
+}
+
+function evaluateExpr(expr: EventMatchExpr, payload: unknown): boolean {
+  switch (expr.kind) {
+    case "and":
+      return expr.nodes.every((node) => evaluateExpr(node, payload));
+    case "or":
+      return expr.nodes.some((node) => evaluateExpr(node, payload));
+    case "atom":
+      return evaluateOp(expr.op, resolvePath(payload, expr.path));
+    default: {
+      const unrecognized: { readonly kind: string } = expr;
+      throw new Error(`Unknown EventMatchExpr kind "${unrecognized.kind}"`);
+    }
+  }
+}
+
+export function evaluateEventMatch(match: EventMatch, payload: unknown): boolean {
+  if (match.version !== 1) {
+    throw new Error(`Unsupported EventMatch version ${JSON.stringify(match.version)} — expected 1`);
+  }
+  return evaluateExpr(match.expr, payload);
+}

package/src/engine/steps/wait-for-event.ts

@@ -8,13 +8,15 @@
 // it writes workflow.step.resumed with the matched event's data.
 //
 // The `match` resolver is optional — when omitted, any event of the given
-// type resumes the workflow. When provided, it receives the event payload
-// and must return true for the event to trigger resume.
+// type resumes the workflow. When provided, it resolves to a serializable
+// EventMatch AST (not a closure) that is persisted into the waiting event's
+// payload; the Resume-Loop evaluates it via evaluateEventMatch against the
+// candidate event's payload.
 
 import { defineStep } from "../define-step";
-import type { PipelineCtx, StepInstance, StepResolver } from "../types/step";
+import type { EventMatch, PipelineCtx, StepInstance, StepResolver } from "../types/step";
 import { addDuration } from "./_duration-utils";
-import { resolveRequired } from "./_resolver-utils";
+import { resolveOptional, resolveRequired } from "./_resolver-utils";
 import {
   SUSPEND_SENTINEL,
   WORKFLOW_AGGREGATE_TYPE,
@@ -23,7 +25,7 @@ import {
 
 type WaitForEventArgs = {
   readonly event: string;
-  readonly match?: StepResolver<(payload: unknown) => boolean>;
+  readonly match?: StepResolver<EventMatch>;
   readonly timeout: StepResolver<string>;
 };
 
@@ -40,6 +42,7 @@ defineStep<WaitForEventArgs, undefined | typeof SUSPEND_SENTINEL>({
     }
 
     const timeout = resolveRequired(args.timeout, ctx);
+    const resolvedMatch = resolveOptional(args.match, ctx);
 
     const now = Temporal.Now.instant().toString();
     const timeoutAt =
@@ -51,6 +54,7 @@ defineStep<WaitForEventArgs, undefined | typeof SUSPEND_SENTINEL>({
       type: WORKFLOW_WAITING_FOR_EVENT_TYPE,
       payload: {
         eventType: args.event,
+        ...(resolvedMatch && { match: resolvedMatch }),
         timeoutAt,
         stepIndex: ctx.workflow.stepIndex,
         workflowName: ctx.workflow.workflowName,

package/src/files/__tests__/file-handle.test.ts

@@ -90,6 +90,32 @@ describe("createFileContext", () => {
     const h2 = files.ref("tenant/foo.pdf");
     expect(Array.from(await h2.read())).toEqual([7]);
   });
+
+  test("list delegates to the provider and returns its result", async () => {
+    const provider = createInMemoryFileProvider();
+    await provider.write("tenant/photo.jpg", new Uint8Array([1]));
+    await provider.write("tenant/photo.medium.jpg", new Uint8Array([2]));
+    await provider.write("other/photo.jpg", new Uint8Array([3]));
+    const files = createFileContext(() => Promise.resolve(provider));
+
+    const keys = await files.list("tenant/");
+    expect([...keys].sort()).toEqual(["tenant/photo.jpg", "tenant/photo.medium.jpg"].sort());
+  });
+
+  test("the provider is resolved once and memoized across ref() and list()", async () => {
+    const provider = createInMemoryFileProvider();
+    let resolveCount = 0;
+    const files = createFileContext(() => {
+      resolveCount++;
+      return Promise.resolve(provider);
+    });
+
+    await files.ref("tenant/a.jpg").write(new Uint8Array([1]));
+    await files.list("tenant/");
+    await files.ref("tenant/b.jpg").write(new Uint8Array([2]));
+
+    expect(resolveCount).toBe(1);
+  });
 });
 
 describe("InMemoryFileProvider", () => {

package/src/files/file-handle.ts

@@ -45,6 +45,7 @@ export function createFileContext(resolve: () => Promise<FileStorageProvider>):
   };
   return {
     ref: (key) => createFileHandle(key, getProvider),
+    list: async (prefix) => (await getProvider()).list(prefix),
   };
 }