@cosmicdrift/kumiko-framework 0.1.0

package/src/pipeline/__tests__/ctx-bridge.integration.ts

@@ -0,0 +1,234 @@
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "vitest";
+import { z } from "zod";
+import { createEventStoreExecutor } from "../../db/event-store-executor";
+import { buildDrizzleTable } from "../../db/table-builder";
+import {
+  access,
+  createEntity,
+  createNumberField,
+  createSystemUser,
+  createTextField,
+  defineFeature,
+} from "../../engine";
+import { UnprocessableError, writeFailure } from "../../errors";
+import { createEntityTable, setupTestStack, type TestStack, TestUsers } from "../../stack";
+
+// Two entities: `bag` (outer) + `secret` (inner). The outer handler calls
+// the inner via ctx.queryAs / ctx.writeAs. We verify:
+//   - ctx.query / ctx.write run under the CURRENT user (field-access filters)
+//   - ctx.queryAs(systemUser) bypasses field-access read filters
+//   - A writeAs inside a failing outer write rolls back with the outer tx
+//   - afterCommit hooks from writeAs fire exactly once on outer commit
+
+const bagEntity = createEntity({
+  table: "ctx_bags",
+  fields: {
+    label: createTextField({ required: true }),
+    counter: createNumberField({ default: 0 }),
+  },
+});
+const bagTable = buildDrizzleTable("bag", bagEntity);
+
+// secret has a system-only read field — proves queryAs(system) reads it,
+// plain query doesn't.
+const secretEntity = createEntity({
+  table: "ctx_secrets",
+  fields: {
+    owner: createTextField({ required: true }),
+    token: createTextField({
+      required: true,
+      access: { read: access.privileged, write: access.privileged },
+    }),
+  },
+});
+const secretTable = buildDrizzleTable("secret", secretEntity);
+
+let stack: TestStack;
+const admin = TestUsers.admin;
+
+const afterCommitLog: string[] = [];
+
+const bridgeFeature = defineFeature("ctxbridge", (r) => {
+  const bag = r.entity("bag", bagEntity);
+  const secret = r.entity("secret", secretEntity);
+
+  r.writeHandler(
+    "bag:create",
+    z.object({ label: z.string() }),
+    async (event, ctx) => {
+      const crud = createEventStoreExecutor(bagTable, bagEntity, { entityName: "bag" });
+      return crud.create(event.payload, event.user, ctx.db);
+    },
+    { access: { roles: ["Admin"] } },
+  );
+
+  r.writeHandler(
+    "secret:create",
+    z.object({ owner: z.string(), token: z.string() }),
+    async (event, ctx) => {
+      const crud = createEventStoreExecutor(secretTable, secretEntity, { entityName: "secret" });
+      return crud.create(event.payload, event.user, ctx.db);
+    },
+    { access: { roles: access.privileged } },
+  );
+
+  r.queryHandler(
+    "secret:by-owner",
+    z.object({ owner: z.string() }),
+    async (query, ctx) => {
+      const rows = await ctx.db.select().from(secretTable);
+      return (
+        (rows as Array<Record<string, unknown>>).find((r) => r["owner"] === query.payload.owner) ??
+        null
+      );
+    },
+    { access: { roles: access.privileged } },
+  );
+
+  // Outer handler: creates a bag AND (as system) creates a secret for the user.
+  // writeAs(system) must share the outer tx. An intentional failure in a later
+  // step rolls the secret back too.
+  r.writeHandler(
+    "bag:create-with-secret",
+    z.object({ label: z.string(), token: z.string(), fail: z.boolean().optional() }),
+    async (event, ctx) => {
+      const crud = createEventStoreExecutor(bagTable, bagEntity, { entityName: "bag" });
+      const created = await crud.create({ label: event.payload.label }, event.user, ctx.db);
+      if (!created.isSuccess) return created;
+
+      const secretRes = await ctx.writeAs(
+        createSystemUser(event.user.tenantId),
+        "ctxbridge:write:secret:create",
+        {
+          owner: event.user.id,
+          token: event.payload.token,
+        },
+      );
+      if (!secretRes.isSuccess) return secretRes;
+
+      if (event.payload.fail) {
+        return writeFailure(new UnprocessableError("intentional_failure"));
+      }
+
+      return created;
+    },
+    { access: { roles: ["Admin"] } },
+  );
+
+  // Handler that fetches the secret via ctx.queryAs(system) — proves the
+  // privileged call returns the token field even though the caller (Admin)
+  // couldn't read it themselves.
+  r.queryHandler(
+    "bag:peek-secret",
+    z.object({ owner: z.string() }),
+    async (query, ctx) => {
+      return ctx.queryAs(createSystemUser(query.user.tenantId), "ctxbridge:query:secret:by-owner", {
+        owner: query.payload.owner,
+      });
+    },
+    { access: { roles: ["Admin"] } },
+  );
+
+  // afterCommit hook on bag — fires once per outer commit.
+  r.entityHook("postSave", bag, async (result) => {
+    afterCommitLog.push(`bag:${result.data["label"]}`);
+  });
+
+  // afterCommit hook on secret — the entity targeted by the nested writeAs.
+  // Proves: (a) hook fires exactly once per successful writeAs, (b) hook
+  // does NOT fire when the outer transaction rolls back.
+  r.entityHook("postSave", secret, async (result) => {
+    afterCommitLog.push(`secret:${result.data["owner"]}`);
+  });
+});
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [bridgeFeature] });
+  await createEntityTable(stack.db, bagEntity);
+  await createEntityTable(stack.db, secretEntity);
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+beforeEach(async () => {
+  afterCommitLog.length = 0;
+  await stack.db.delete(bagTable);
+  await stack.db.delete(secretTable);
+  // Clear the event-dedup cache — tests re-use entity ids (Postgres sequences
+  // reset, each test sees id=1). Without flushing Redis the second test hits
+  // a dedup hit on the same handler:id:version:phase key and the hook is
+  // silently skipped.
+  await stack.redis.flushNamespace();
+});
+
+describe("ctx.query / ctx.queryAs", () => {
+  test("queryAs(system) returns fields that the caller's role cannot read", async () => {
+    // Seed via writeAs(system) — the caller Admin can't write the token directly
+    const res = await stack.http.write(
+      "ctxbridge:write:bag:create-with-secret",
+      { label: "outer", token: "top-secret" },
+      admin,
+    );
+    expect((await res.json()).isSuccess).toBe(true);
+
+    // Fetch via ctx.queryAs(system) — token comes through because system
+    // satisfies the field-access read rule on `token`.
+    const peeked = await stack.http.queryOk<Record<string, unknown>>(
+      "ctxbridge:query:bag:peek-secret",
+      { owner: admin.id },
+      admin,
+    );
+    expect(peeked).toMatchObject({ owner: admin.id, token: "top-secret" });
+  });
+});
+
+describe("ctx.writeAs shares the outer transaction", () => {
+  test("failure in outer write rolls back the writeAs insert too", async () => {
+    const res = await stack.http.write(
+      "ctxbridge:write:bag:create-with-secret",
+      { label: "rolled-back", token: "discarded", fail: true },
+      admin,
+    );
+    const body = await res.json();
+    expect(body.isSuccess).toBe(false);
+
+    // Both tables empty — outer bag + inner secret rolled back together
+    const bags = await stack.db.select().from(bagTable);
+    const secrets = await stack.db.select().from(secretTable);
+    expect(bags).toHaveLength(0);
+    expect(secrets).toHaveLength(0);
+  });
+
+  test("success: both writes persist, both afterCommit hooks fire exactly once", async () => {
+    const res = await stack.http.write(
+      "ctxbridge:write:bag:create-with-secret",
+      { label: "committed", token: "kept" },
+      admin,
+    );
+    expect((await res.json()).isSuccess).toBe(true);
+
+    const bags = await stack.db.select().from(bagTable);
+    const secrets = await stack.db.select().from(secretTable);
+    expect(bags).toHaveLength(1);
+    expect(secrets).toHaveLength(1);
+
+    // Both entities' afterCommit hooks fire once each: bag (outer write) and
+    // secret (inner writeAs). Neither fires twice, even though secret was
+    // created through the nested bridge call.
+    expect(afterCommitLog.sort()).toEqual([`bag:committed`, `secret:${admin.id}`]);
+  });
+
+  test("rollback: inner secret hook does NOT fire when outer write fails", async () => {
+    const res = await stack.http.write(
+      "ctxbridge:write:bag:create-with-secret",
+      { label: "ignored", token: "discarded", fail: true },
+      admin,
+    );
+    expect((await res.json()).isSuccess).toBe(false);
+
+    // Both hooks must stay silent — tx rolled back, afterCommit queue dropped.
+    expect(afterCommitLog).toEqual([]);
+  });
+});

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

@@ -0,0 +1,379 @@
+import { describe, expect, test } from "vitest";
+import { z } from "zod";
+import { createEntity, createRegistry, createTextField, defineFeature } from "../../engine";
+import { createTestUser } from "../../stack";
+import { createDispatcher } from "../dispatcher";
+
+const echoFeature = defineFeature("echo", (r) => {
+  r.entity("item", createEntity({ table: "Items", fields: { name: createTextField() } }));
+
+  r.writeHandler(
+    "item:create",
+    z.object({ name: z.string().min(1) }),
+    async (event) => ({ isSuccess: true, data: { name: event.payload.name } }),
+    { access: { roles: ["Admin"] } },
+  );
+
+  r.queryHandler(
+    "item:list",
+    z.object({ search: z.string().optional() }),
+    async (query) => ({
+      items: [],
+      search: query.payload.search,
+    }),
+    { access: { openToAll: true } },
+  );
+
+  r.hook("validation", "item:create", (data) => {
+    if (data["name"] === "forbidden") return [{ field: "name", error: "forbidden_name" }];
+    return null;
+  });
+});
+
+function createTestDispatcher() {
+  const registry = createRegistry([echoFeature]);
+  return createDispatcher(registry, {});
+}
+
+// --- Dispatch: Write ---
+
+describe("dispatcher.write", () => {
+  test("validates payload and calls handler", async () => {
+    const dispatcher = createTestDispatcher();
+    const result = await dispatcher.write(
+      "echo:write:item:create",
+      { name: "Test" },
+      createTestUser(),
+    );
+
+    expect(result.isSuccess).toBe(true);
+    if (result.isSuccess) {
+      expect(result.data).toEqual({ name: "Test" });
+    }
+  });
+
+  test("rejects invalid payload", async () => {
+    const dispatcher = createTestDispatcher();
+    const result = await dispatcher.write("echo:write:item:create", { name: "" }, createTestUser());
+
+    expect(result.isSuccess).toBe(false);
+    if (!result.isSuccess) {
+      expect(result.error.code).toBe("validation_error");
+    }
+  });
+
+  test("rejects unauthorized user", async () => {
+    const dispatcher = createTestDispatcher();
+    const guest = createTestUser({ roles: ["Guest"] });
+    const result = await dispatcher.write("echo:write:item:create", { name: "Test" }, guest);
+
+    expect(result.isSuccess).toBe(false);
+    if (!result.isSuccess) {
+      expect(result.error.code).toBe("access_denied");
+    }
+  });
+
+  test("ctx.user ist Convenience-Alias auf event.user (gleicher Wert)", async () => {
+    // Pinst dass der Handler auf ctx.user zugreifen kann ohne den
+    // typo-resistenten event.user-Pfad zu nutzen. Identitätsprüfung
+    // gegen denselben SessionUser — sonst ist's nicht der gleiche.
+    const captured: { fromEvent?: unknown; fromCtx?: unknown } = {};
+    const aliasFeature = defineFeature("alias", (r) => {
+      r.entity("item", createEntity({ table: "Items", fields: { name: createTextField() } }));
+      r.writeHandler(
+        "item:create",
+        z.object({ name: z.string() }),
+        async (event, ctx) => {
+          captured.fromEvent = event.user;
+          captured.fromCtx = ctx.user;
+          return { isSuccess: true, data: {} };
+        },
+        { access: { roles: ["Admin"] } },
+      );
+    });
+    const dispatcher = createDispatcher(createRegistry([aliasFeature]), {});
+    const user = createTestUser();
+    const res = await dispatcher.write("alias:write:item:create", { name: "x" }, user);
+    expect(res.isSuccess).toBe(true);
+    expect(captured.fromCtx).toBe(captured.fromEvent);
+    expect((captured.fromCtx as { id: number }).id).toBe(user.id);
+  });
+
+  test("runs validation hooks", async () => {
+    const dispatcher = createTestDispatcher();
+    const result = await dispatcher.write(
+      "echo:write:item:create",
+      { name: "forbidden" },
+      createTestUser(),
+    );
+
+    expect(result.isSuccess).toBe(false);
+    if (!result.isSuccess) {
+      expect(result.error.code).toBe("validation_error");
+      const fields = (result.error.details as { fields: Array<{ code: string }> }).fields;
+      expect(fields.some((f) => f.code === "forbidden_name")).toBe(true);
+    }
+  });
+
+  test("returns error for unknown handler", async () => {
+    const dispatcher = createTestDispatcher();
+    const result = await dispatcher.write("nonexistent", {}, createTestUser());
+
+    expect(result.isSuccess).toBe(false);
+    if (!result.isSuccess) {
+      expect(result.error.code).toBe("not_found");
+    }
+  });
+});
+
+// --- Dispatch: Query ---
+
+describe("dispatcher.query", () => {
+  test("validates and calls query handler", async () => {
+    const dispatcher = createTestDispatcher();
+    const result = await dispatcher.query(
+      "echo:query:item:list",
+      { search: "hello" },
+      createTestUser(),
+    );
+
+    expect(result).toEqual({ items: [], search: "hello" });
+  });
+
+  test("rejects invalid query payload", async () => {
+    const dispatcher = createTestDispatcher();
+
+    await expect(
+      dispatcher.query("echo:query:item:list", { search: 123 }, createTestUser()),
+    ).rejects.toMatchObject({ code: "validation_error", httpStatus: 400 });
+  });
+
+  test("throws for unknown query handler", async () => {
+    const dispatcher = createTestDispatcher();
+
+    await expect(dispatcher.query("nonexistent", {}, createTestUser())).rejects.toMatchObject({
+      code: "not_found",
+      httpStatus: 404,
+    });
+  });
+});
+
+// --- Dispatch: Command (fire-and-forget) ---
+
+describe("dispatcher.command", () => {
+  test("executes write handler without returning data", async () => {
+    const dispatcher = createTestDispatcher();
+    // Command uses write handlers but discards the result
+    await expect(
+      dispatcher.command("echo:write:item:create", { name: "Fire" }, createTestUser()),
+    ).resolves.toBeUndefined();
+  });
+
+  test("still validates and checks access", async () => {
+    const dispatcher = createTestDispatcher();
+    const guest = createTestUser({ roles: ["Guest"] });
+
+    await expect(
+      dispatcher.command("echo:write:item:create", { name: "Test" }, guest),
+    ).rejects.toThrow(/access/i);
+  });
+});
+
+// --- Dispatch: Idempotency ---
+
+describe("dispatcher.write idempotency", () => {
+  test("duplicate requestId returns cached result", async () => {
+    const registry = createRegistry([echoFeature]);
+    const dispatcher = createDispatcher(
+      registry,
+      {},
+      {
+        idempotency: createMockIdempotencyGuard(),
+      },
+    );
+
+    const user = createTestUser();
+    const result1 = await dispatcher.write(
+      "echo:write:item:create",
+      { name: "Once" },
+      user,
+      "req-001",
+    );
+    const result2 = await dispatcher.write(
+      "echo:write:item:create",
+      { name: "Once" },
+      user,
+      "req-001",
+    );
+
+    expect(result1.isSuccess).toBe(true);
+    expect(result2.isSuccess).toBe(true);
+    // Same cached result — handler should only have been called once
+    if (result1.isSuccess && result2.isSuccess) {
+      expect(result2.data).toEqual(result1.data);
+    }
+  });
+
+  test("different requestIds execute separately", async () => {
+    const registry = createRegistry([echoFeature]);
+    const dispatcher = createDispatcher(
+      registry,
+      {},
+      {
+        idempotency: createMockIdempotencyGuard(),
+      },
+    );
+
+    const user = createTestUser();
+    const result1 = await dispatcher.write("echo:write:item:create", { name: "A" }, user, "req-a");
+    const result2 = await dispatcher.write("echo:write:item:create", { name: "B" }, user, "req-b");
+
+    expect(result1.isSuccess).toBe(true);
+    expect(result2.isSuccess).toBe(true);
+    if (result1.isSuccess && result2.isSuccess) {
+      expect(result1.data).toEqual({ name: "A" });
+      expect(result2.data).toEqual({ name: "B" });
+    }
+  });
+});
+
+// --- Feature-toggle gate ---
+
+describe("dispatcher feature-gate", () => {
+  function toggled() {
+    return defineFeature("toggled", (r) => {
+      r.toggleable({ default: true });
+      r.entity("widget", createEntity({ table: "Widgets", fields: { name: createTextField() } }));
+      r.queryHandler("widget:list", z.object({}).passthrough(), async () => ({ items: [] }), {
+        access: { openToAll: true },
+      });
+      r.writeHandler(
+        "widget:create",
+        z.object({ name: z.string() }),
+        async (event) => ({ isSuccess: true, data: { name: event.payload.name } }),
+        { access: { roles: ["Admin"] } },
+      );
+    });
+  }
+
+  const user = createTestUser({ id: "u1", roles: ["Admin"] });
+
+  test("query of disabled feature throws FeatureDisabledError", 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;
+        },
+      },
+    );
+
+    await expect(dispatcher.query("toggled:query:widget:list", {}, user)).resolves.toEqual({
+      items: [],
+    });
+
+    disabled.add("toggled");
+    await expect(dispatcher.query("toggled:query:widget:list", {}, user)).rejects.toThrow(
+      /feature toggled is disabled/,
+    );
+
+    disabled.delete("toggled");
+    await expect(dispatcher.query("toggled:query:widget:list", {}, user)).resolves.toEqual({
+      items: [],
+    });
+  });
+
+  test("write of disabled feature returns WriteFailure with feature_disabled reason", async () => {
+    const registry = createRegistry([toggled()]);
+    const disabled = new Set<string>(["toggled"]);
+    const dispatcher = createDispatcher(
+      registry,
+      {},
+      {
+        effectiveFeatures: () => {
+          const all = new Set(registry.features.keys());
+          for (const d of disabled) all.delete(d);
+          return all;
+        },
+      },
+    );
+
+    const result = await dispatcher.write("toggled:write:widget:create", { name: "x" }, user);
+    expect(result.isSuccess).toBe(false);
+    if (!result.isSuccess) {
+      expect(result.error.code).toBe("feature_disabled");
+      expect(result.error.details).toMatchObject({
+        reason: "feature_disabled",
+        feature: "toggled",
+      });
+    }
+  });
+
+  test("no effectiveFeatures callback → gate is pass-through", async () => {
+    const registry = createRegistry([toggled()]);
+    const dispatcher = createDispatcher(registry, {});
+    await expect(dispatcher.query("toggled:query:widget:list", {}, user)).resolves.toEqual({
+      items: [],
+    });
+  });
+});
+
+describe("write-handler shape guard", () => {
+  // Real footgun caught while building the publicstatus showcase: a custom
+  // handler that returns `{ id }` instead of `{ isSuccess: true, data: { id } }`
+  // used to crash the dispatcher with an obscure "internal error". The
+  // shape-guard turns this into a clear actionable message at the
+  // dispatcher boundary.
+
+  function brokenFeature() {
+    return defineFeature("broken", (r) => {
+      r.entity("item", createEntity({ table: "Items", fields: { name: createTextField() } }));
+      r.writeHandler(
+        "item:create",
+        z.object({ name: z.string() }),
+        // biome-ignore lint/suspicious/noExplicitAny: deliberate wrong-shape return for the test
+        async (event) => ({ id: "x", name: event.payload.name }) as any,
+        { access: { roles: ["Admin"] } },
+      );
+    });
+  }
+
+  test("handler returning a non-WriteResult shape → InternalError with actionable hint", async () => {
+    const registry = createRegistry([brokenFeature()]);
+    const dispatcher = createDispatcher(registry, {});
+    const result = await dispatcher.write(
+      "broken:write:item:create",
+      { name: "test" },
+      createTestUser(),
+    );
+
+    expect(result.isSuccess).toBe(false);
+    if (!result.isSuccess) {
+      expect(result.error.code).toBe("internal_error");
+      // Message points at defineWriteHandler / WriteResult-shape — that's
+      // the developer's actionable next step. Also surfaces in the
+      // dev-mode response body via error.message.
+      expect(result.error.message).toContain("invalid shape");
+      expect(result.error.message).toContain("defineWriteHandler");
+    }
+  });
+});
+
+// --- Mock helpers ---
+
+function createMockIdempotencyGuard() {
+  const cache = new Map<string, string>();
+  return {
+    async check(requestId: string) {
+      return cache.get(requestId) ?? null;
+    },
+    async store(requestId: string, result: unknown) {
+      cache.set(requestId, JSON.stringify(result));
+    },
+  };
+}

package/src/pipeline/__tests__/distributed-lock.integration.ts

@@ -0,0 +1,67 @@
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import { createTestRedis, type TestRedis } from "../../stack";
+import { createDistributedLock } from "../distributed-lock";
+
+let testRedis: TestRedis;
+
+beforeAll(async () => {
+  testRedis = await createTestRedis();
+});
+
+afterAll(async () => {
+  await testRedis.cleanup();
+});
+
+describe("distributed lock", () => {
+  test("acquire returns token on success", async () => {
+    const lock = createDistributedLock(testRedis.redis);
+    const token = await lock.acquire("test-lock-1");
+    expect(token).not.toBeNull();
+    expect(typeof token).toBe("string");
+  });
+
+  test("second acquire on same key fails", async () => {
+    const lock = createDistributedLock(testRedis.redis);
+    const token1 = await lock.acquire("test-lock-2");
+    const token2 = await lock.acquire("test-lock-2");
+
+    expect(token1).not.toBeNull();
+    expect(token2).toBeNull();
+  });
+
+  test("release allows re-acquire", async () => {
+    const lock = createDistributedLock(testRedis.redis);
+    const token = await lock.acquire("test-lock-3");
+    expect(token).not.toBeNull();
+
+    if (!token) throw new Error("expected token");
+    const released = await lock.release("test-lock-3", token);
+    expect(released).toBe(true);
+
+    const token2 = await lock.acquire("test-lock-3");
+    expect(token2).not.toBeNull();
+  });
+
+  test("release with wrong token fails", async () => {
+    const lock = createDistributedLock(testRedis.redis);
+    await lock.acquire("test-lock-4");
+
+    const released = await lock.release("test-lock-4", "wrong-token");
+    expect(released).toBe(false);
+  });
+
+  test("lock expires after TTL", async () => {
+    const lock = createDistributedLock(testRedis.redis);
+    await lock.acquire("test-lock-5", { ttlSeconds: 1 });
+
+    // Can't acquire immediately
+    expect(await lock.acquire("test-lock-5")).toBeNull();
+
+    // Wait for expiry
+    await new Promise((r) => setTimeout(r, 1100));
+
+    // Now we can
+    const token = await lock.acquire("test-lock-5");
+    expect(token).not.toBeNull();
+  });
+});