@cosmicdrift/kumiko-framework 0.328.0 → 0.328.1

package/src/secrets/leak-guard.ts

@@ -1,87 +0,0 @@
-// Response-leak guard. Walks a handler-result tree and throws the moment it
-// finds a Secret<> branded value — the dispatcher calls this after every
-// handler returns, so accidentally including a plaintext secret in the
-// response body becomes a runtime error at the handler boundary rather
-// than a silent exfiltration to the client.
-
-import { InternalError } from "../errors";
-import { isSecret } from "./types";
-
-// Maximum depth the walker descends. A legitimate result tree is rarely
-// deeper than a few levels; the cap is a safety net against cyclic or
-// pathologically-deep user input smuggled into a response.
-const MAX_DEPTH = 12;
-
-export function assertNoSecretLeak(value: unknown, path = "$", depth = 0): void {
-  // skip: nothing to walk at null/undefined leaves.
-  if (value === null || value === undefined) return;
-
-  if (isSecret(value)) {
-    throw new InternalError({
-      message:
-        `[secrets] Secret<> leaked into response at ${path}. ` +
-        "Feature code must call .reveal() and use the plaintext in an " +
-        "external call (SMTP, HTTP header, etc.) — never return the branded " +
-        "value, even unwrapped, unless you've stripped it from the response first.",
-    });
-  }
-
-  // skip: hit the recursion cap. Cyclic or pathologically-deep input is
-  // more likely than a legitimate 12-level-deep secret — trade coverage
-  // for termination guarantees.
-  if (depth >= MAX_DEPTH) return;
-
-  const t = typeof value;
-  // skip: primitives already handled by the isSecret check above — strings,
-  // numbers, booleans can't hold a brand.
-  if (t !== "object") return;
-
-  // Map and Set get walked through their entries — a feature could legitimately
-  // build either, and a custom toJSON could expand them onto the wire.
-  // JSON.stringify-by-default produces "{}" for both, which would mask the
-  // leak silently; we'd rather throw at the boundary than rely on that
-  // accident.
-  if (value instanceof Map) {
-    let i = 0;
-    for (const [k, v] of value) {
-      assertNoSecretLeak(k, `${path}.<map[${i}].key>`, depth + 1);
-      assertNoSecretLeak(v, `${path}.<map[${i}].val>`, depth + 1);
-      i++;
-    }
-    // skip: map fully walked, nothing else at this level.
-    return;
-  }
-  if (value instanceof Set) {
-    let i = 0;
-    for (const v of value) {
-      assertNoSecretLeak(v, `${path}.<set[${i}]>`, depth + 1);
-      i++;
-    }
-    // skip: set fully walked, nothing else at this level.
-    return;
-  }
-
-  // Skip remaining class instances we can't introspect safely (Date, Buffer,
-  // Temporal.Instant, custom domain classes, etc.). Plain objects have
-  // Object.prototype or null prototype — that's what handler responses
-  // serialize to JSON from.
-  const proto = Object.getPrototypeOf(value);
-  // skip: non-plain object (class instance). Brand check at entry already
-  // verified it's not a Secret<>; anything else is opaque to us.
-  if (proto !== null && proto !== Object.prototype && !Array.isArray(value)) {
-    return;
-  }
-
-  if (Array.isArray(value)) {
-    for (let i = 0; i < value.length; i++) {
-      assertNoSecretLeak(value[i], `${path}[${i}]`, depth + 1);
-    }
-    // skip: array fully walked, nothing else at this level.
-    return;
-  }
-
-  const obj = value as Record<string, unknown>; // @cast-boundary recursive-walk
-  for (const [k, v] of Object.entries(obj)) {
-    assertNoSecretLeak(v, `${path}.${k}`, depth + 1);
-  }
-}

package/src/secrets/rotation.ts

@@ -1,34 +0,0 @@
-// KEK rotation: unwrap the DEK with the OLD kekVersion, re-wrap with the
-// CURRENT one. The ciphertext never changes — this is why envelope
-// encryption makes rotation affordable on large tables.
-
-import type { Envelope, MasterKeyProvider } from "./types";
-
-// Re-wrap the DEK of a single envelope so it references the current KEK
-// version. No-op when the envelope is already current (caller-side this
-// means "filter WHERE kekVersion != currentVersion" before calling).
-export async function rewrapDek(
-  envelope: Envelope,
-  provider: MasterKeyProvider,
-): Promise<Envelope> {
-  if (envelope.kekVersion === provider.currentVersion()) {
-    return envelope;
-  }
-  // Unwrap with the old KEK. Provider must still know the old version
-  // (keyring contains both until ops retires the old KEK).
-  const dek = await provider.unwrapDek(envelope.encryptedDek, envelope.kekVersion);
-  try {
-    const { encryptedDek, kekVersion } = await provider.wrapDek(dek);
-    return {
-      ciphertext: envelope.ciphertext,
-      iv: envelope.iv,
-      authTag: envelope.authTag,
-      encryptedDek,
-      kekVersion,
-    };
-  } finally {
-    // Zero the unwrapped DEK — it was held in plaintext only long enough
-    // to wrap it again.
-    dek.fill(0);
-  }
-}

package/src/secrets/stored-envelope.ts

@@ -1,46 +0,0 @@
-// Canonical at-rest form of an Envelope: every Buffer as base64, ready for
-// jsonb columns (secrets feature) or JSON-stringified TEXT columns
-// (EnvelopeCipher for config values / entity fields). One wire shape for
-// every envelope-encrypted store in the framework.
-
-import type { Envelope } from "./types";
-
-export type StoredEnvelope = {
-  readonly ciphertext: string; // base64
-  readonly iv: string; // base64
-  readonly authTag: string; // base64
-  readonly encryptedDek: string; // base64
-  readonly kekVersion: number;
-};
-
-export function encodeStoredEnvelope(envelope: Envelope): StoredEnvelope {
-  return {
-    ciphertext: envelope.ciphertext.toString("base64"),
-    iv: envelope.iv.toString("base64"),
-    authTag: envelope.authTag.toString("base64"),
-    encryptedDek: envelope.encryptedDek.toString("base64"),
-    kekVersion: envelope.kekVersion,
-  };
-}
-
-export function decodeStoredEnvelope(stored: StoredEnvelope): Envelope {
-  return {
-    ciphertext: Buffer.from(stored.ciphertext, "base64"),
-    iv: Buffer.from(stored.iv, "base64"),
-    authTag: Buffer.from(stored.authTag, "base64"),
-    encryptedDek: Buffer.from(stored.encryptedDek, "base64"),
-    kekVersion: stored.kekVersion,
-  };
-}
-
-export function isStoredEnvelope(value: unknown): value is StoredEnvelope {
-  if (!value || typeof value !== "object") return false;
-  const v = value as Record<string, unknown>; // @cast-boundary parse-boundary after typeof check
-  return (
-    typeof v["ciphertext"] === "string" &&
-    typeof v["iv"] === "string" &&
-    typeof v["authTag"] === "string" &&
-    typeof v["encryptedDek"] === "string" &&
-    typeof v["kekVersion"] === "number"
-  );
-}

package/src/seeding/__tests__/entity-seed.test.ts

@@ -1,70 +0,0 @@
-import { describe, expect, test } from "bun:test";
-import { runEventStoreSeed } from "../entity-seed";
-
-describe("runEventStoreSeed", () => {
-  test('default ifExists="skip" returns existing id without update', async () => {
-    let updateCalls = 0;
-    let createCalls = 0;
-
-    const result = await runEventStoreSeed<string>({
-      existing: { id: "agg-1", version: 3 },
-      create: async () => {
-        createCalls++;
-        return { id: "new" };
-      },
-      update: async () => {
-        updateCalls++;
-        return { id: "agg-1" };
-      },
-    });
-
-    expect(result.id).toBe("agg-1");
-    expect(updateCalls).toBe(0);
-    expect(createCalls).toBe(0);
-  });
-
-  test('ifExists="update" calls update when row exists', async () => {
-    let updateCalls = 0;
-
-    const result = await runEventStoreSeed<string>({
-      existing: { id: "agg-2", version: 1 },
-      ifExists: "update",
-      create: async () => ({ id: "new" }),
-      update: async (existing) => {
-        updateCalls++;
-        expect(existing.version).toBe(1);
-        return { id: existing.id };
-      },
-    });
-
-    expect(result.id).toBe("agg-2");
-    expect(updateCalls).toBe(1);
-  });
-
-  test("missing row calls create", async () => {
-    let createCalls = 0;
-
-    const result = await runEventStoreSeed<string>({
-      existing: null,
-      create: async () => {
-        createCalls++;
-        return { id: "created" };
-      },
-      update: async () => ({ id: "never" }),
-    });
-
-    expect(result.id).toBe("created");
-    expect(createCalls).toBe(1);
-  });
-
-  test("supports numeric id type via explicit generic", async () => {
-    const result = await runEventStoreSeed<number>({
-      existing: { id: 42, version: 1 },
-      ifExists: "update",
-      create: async () => ({ id: 99 }),
-      update: async (row) => ({ id: row.id }),
-    });
-
-    expect(result.id).toBe(42);
-  });
-});

package/src/seeding/entity-seed.ts

@@ -1,31 +0,0 @@
-import { DEFAULT_SEED_IF_EXISTS, type SeedIfExists } from "./types";
-
-export type EventStoreSeedExisting<TId extends string | number = string> = {
-  readonly id: TId;
-  readonly version: number;
-};
-
-export type RunEventStoreSeedOptions<
-  TId extends string | number = string,
-  TExisting extends EventStoreSeedExisting<TId> = EventStoreSeedExisting<TId>,
-> = {
-  readonly existing: TExisting | null | undefined;
-  readonly ifExists?: SeedIfExists;
-  readonly create: () => Promise<{ id: TId }>;
-  readonly update: (existing: TExisting) => Promise<{ id: TId }>;
-};
-
-/** Shared create-or-skip/update path for event-store boot-seed helpers. */
-export async function runEventStoreSeed<
-  TId extends string | number = string,
-  TExisting extends EventStoreSeedExisting<TId> = EventStoreSeedExisting<TId>,
->(opts: RunEventStoreSeedOptions<TId, TExisting>): Promise<{ id: TId }> {
-  const ifExists = opts.ifExists ?? DEFAULT_SEED_IF_EXISTS;
-  if (opts.existing != null) {
-    if (ifExists === "skip") {
-      return { id: opts.existing.id };
-    }
-    return opts.update(opts.existing);
-  }
-  return opts.create();
-}

package/src/seeding/index.ts

@@ -1,6 +0,0 @@
-export {
-  type EventStoreSeedExisting,
-  type RunEventStoreSeedOptions,
-  runEventStoreSeed,
-} from "./entity-seed";
-export { DEFAULT_SEED_IF_EXISTS, type SeedIfExists } from "./types";

package/src/seeding/types.ts

@@ -1,8 +0,0 @@
-/** Boot-seed semantics for event-sourced entity helpers.
- *
- *  - `skip` (default): row exists → return without write (no event).
- *  - `update`: row exists → overwrite via executor.update (opt-in, e.g.
- *    demo-fixtures where code is source-of-truth). */
-export type SeedIfExists = "skip" | "update";
-
-export const DEFAULT_SEED_IF_EXISTS: SeedIfExists = "skip";

package/src/stack/__tests__/drain-event-consumers.integration.test.ts

@@ -1,166 +0,0 @@
-// drainEventConsumers — pass-budgeted alternative to
-// `while ((await eventDispatcher.runOnce())?.processed ?? 0) > 0) {}`, which
-// under-drains a backlog bigger than one dispatcher batch and gives no
-// diagnostics when a consumer is stuck.
-
-import { afterAll, afterEach, beforeAll, describe, expect, test } from "bun:test";
-import { insertOne } from "../../db";
-import { defineFeature } from "../../engine";
-import { eventsTable } from "../../event-store";
-import { drainEventConsumers } from "../drain-event-consumers";
-import { resetEventStore } from "../table-helpers";
-import { setupTestStack, type TestStack } from "../test-stack";
-import { TestUsers } from "../test-users";
-
-const admin = TestUsers.admin;
-const TRACKER_QN = "drain-test:projection:tracker";
-const POISON_QN = "drain-test:projection:poison";
-
-// Distinct from POISON_TARGET_NAME (test 3's own poison consumer) so the two
-// scenarios can't accidentally cross-trigger each other's throw branch.
-const CASCADE_TRIGGER_NAME = "cascade-trigger";
-const CASCADE_POISON_NAME = "cascade-poison-must-not-be-processed";
-const POISON_TARGET_NAME = "always-poison";
-
-let observed: string[] = [];
-
-const drainTestFeature = defineFeature("drain-test", (r) => {
-  r.multiStreamProjection({
-    name: "tracker",
-    apply: {
-      "drain-test.tick": async (event, tx) => {
-        const name = (event.payload as { name: string }).name;
-        if (name === CASCADE_POISON_NAME) {
-          throw new Error(`tracker must not process the post-snapshot cascade: ${name}`);
-        }
-        observed.push(name);
-        // Simulates a consumer whose own handler writes a follow-up event —
-        // drainEventConsumers snapshots the target once, so this write must
-        // never be waited on.
-        if (name === CASCADE_TRIGGER_NAME) {
-          await insertOne(tx, eventsTable, {
-            aggregateId: crypto.randomUUID(),
-            aggregateType: "drain-test-source",
-            tenantId: admin.tenantId,
-            version: 1,
-            type: "drain-test.tick",
-            eventVersion: 1,
-            payload: { name: CASCADE_POISON_NAME },
-            metadata: { userId: admin.id },
-            createdBy: admin.id,
-          });
-        }
-      },
-    },
-  });
-  r.multiStreamProjection({
-    name: "poison",
-    apply: {
-      "drain-test.tick": async (event) => {
-        const name = (event.payload as { name: string }).name;
-        if (name === POISON_TARGET_NAME) {
-          throw new Error(`boom: ${name}`);
-        }
-      },
-    },
-  });
-});
-
-async function appendTick(name: string): Promise<void> {
-  await insertOne(stack.db, eventsTable, {
-    aggregateId: crypto.randomUUID(),
-    aggregateType: "drain-test-source",
-    tenantId: admin.tenantId,
-    version: 1,
-    type: "drain-test.tick",
-    eventVersion: 1,
-    payload: { name },
-    metadata: { userId: admin.id },
-    createdBy: admin.id,
-  });
-}
-
-let stack: TestStack;
-
-beforeAll(async () => {
-  stack = await setupTestStack({ features: [drainTestFeature], systemHooks: [] });
-});
-
-afterEach(async () => {
-  observed = [];
-  await resetEventStore(stack);
-});
-
-afterAll(async () => {
-  await stack.cleanup();
-});
-
-describe("drainEventConsumers", () => {
-  test("backlog larger than the dispatcher batch size gets fully processed", async () => {
-    const names = Array.from({ length: 220 }, (_, i) => `evt-${i}`);
-    for (const name of names) await appendTick(name);
-
-    await drainEventConsumers({ db: stack.db, eventDispatcher: stack.eventDispatcher }, [
-      TRACKER_QN,
-    ]);
-
-    expect(observed.sort()).toEqual([...names].sort());
-  });
-
-  test("an event written after the HWM snapshot does not block", async () => {
-    await appendTick(CASCADE_TRIGGER_NAME);
-
-    await drainEventConsumers({ db: stack.db, eventDispatcher: stack.eventDispatcher }, [
-      TRACKER_QN,
-    ]);
-
-    // The cascade event was written by the handler DURING the drain, after
-    // the target snapshot — proven never processed (would throw otherwise).
-    expect(observed).toEqual([CASCADE_TRIGGER_NAME]);
-  });
-
-  test("a throwing consumer exhausts the budget and the error contains lastError", async () => {
-    await appendTick(POISON_TARGET_NAME);
-
-    let caughtMessage: string | undefined;
-    try {
-      await drainEventConsumers(
-        { db: stack.db, eventDispatcher: stack.eventDispatcher },
-        [POISON_QN],
-        { maxPasses: 2 },
-      );
-    } catch (e) {
-      caughtMessage = e instanceof Error ? e.message : String(e);
-    }
-
-    expect(caughtMessage).toBeDefined();
-    expect(caughtMessage).toContain(POISON_QN);
-    expect(caughtMessage).toContain(`lastError=boom: ${POISON_TARGET_NAME}`);
-  });
-
-  test("an unknown consumer name throws", async () => {
-    let caughtMessage: string | undefined;
-    try {
-      await drainEventConsumers({ db: stack.db, eventDispatcher: stack.eventDispatcher }, [
-        "drain-test:projection:does-not-exist",
-      ]);
-    } catch (e) {
-      caughtMessage = e instanceof Error ? e.message : String(e);
-    }
-
-    expect(caughtMessage).toContain(
-      'consumer "drain-test:projection:does-not-exist" not registered or per-instance',
-    );
-  });
-
-  test("missing eventDispatcher raises a clear error", async () => {
-    let caughtMessage: string | undefined;
-    try {
-      await drainEventConsumers({ db: stack.db, eventDispatcher: undefined }, [TRACKER_QN]);
-    } catch (e) {
-      caughtMessage = e instanceof Error ? e.message : String(e);
-    }
-
-    expect(caughtMessage).toContain("eventDispatcher is undefined");
-  });
-});

package/src/stack/__tests__/drain-jobs.integration.test.ts

@@ -1,159 +0,0 @@
-// fw#3360: stack.drainJobs() waits deterministically for every in-flight
-// job AND its follow-up event-consumer / job-trigger cascade — replaces
-// `waitFor` polling on a specific job's side effect.
-
-import { afterEach, describe, expect, test } from "bun:test";
-import * as z from "zod";
-import { defineFeature } from "../../engine";
-import { SYSTEM_ROLE } from "../../engine/system-user";
-import { setupTestStack, type TestStack } from "../test-stack";
-import { TestUsers } from "../test-users";
-
-const chainResults: Array<{ value: string }> = [];
-
-// Job A → write handler that appends an r.defineEvent event → the async
-// job-trigger event-consumer → Job B. Exercises exactly the gap drainJobs
-// exists for: a job-completion that only cascades into a follow-up job via
-// the event-dispatcher, not the synchronous write-handler dispatch path.
-const chainFeature = defineFeature("draintestchain", (r) => {
-  const relayed = r.defineEvent("relayed", z.object({ value: z.string() }), {
-    piiFields: "none",
-  });
-
-  r.writeHandler(
-    "start",
-    z.object({ value: z.string() }),
-    async () => ({ isSuccess: true as const, data: {} }),
-    { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
-  );
-
-  r.writeHandler(
-    "emit-relayed",
-    z.object({ value: z.string() }),
-    async (event, ctx) => {
-      await ctx.unsafeAppendEvent({
-        aggregateId: crypto.randomUUID(),
-        aggregateType: "draintestchain",
-        type: relayed.name,
-        payload: { value: event.payload.value },
-      });
-      return { isSuccess: true as const, data: {} };
-    },
-    { access: { roles: [SYSTEM_ROLE] } },
-  );
-
-  r.job(
-    "job-a",
-    { trigger: { on: "draintestchain:write:start" }, retries: 0 },
-    async (payload, ctx) => {
-      await ctx.write("draintestchain:write:emit-relayed", { value: payload["value"] });
-    },
-  );
-
-  r.job("job-b", { trigger: { on: relayed.name }, retries: 0 }, async (payload) => {
-    chainResults.push({ value: payload["value"] as string }); // @cast-boundary test-fixture
-  });
-});
-
-const alwaysFailsRuns: string[] = [];
-const retrySucceedsAttempts: number[] = [];
-
-const failureFeature = defineFeature("draintestfailure", (r) => {
-  r.job("always-fails", { trigger: { manual: true }, retries: 0 }, async () => {
-    alwaysFailsRuns.push("ran");
-    throw new Error("job-c always fails");
-  });
-
-  r.job(
-    "retry-succeeds",
-    { trigger: { manual: true }, retries: 1, backoff: { type: "fixed", delayMs: 10 } },
-    async () => {
-      retrySucceedsAttempts.push(Date.now());
-      if (retrySucceedsAttempts.length === 1) throw new Error("first attempt fails on purpose");
-    },
-  );
-});
-
-let stack: TestStack | undefined;
-
-afterEach(async () => {
-  if (stack) await stack.cleanup();
-  stack = undefined;
-});
-
-describe("stack.drainJobs() waits for a job's async event-trigger cascade", () => {
-  test("job A → event → job B settles before drainJobs() resolves", async () => {
-    chainResults.length = 0;
-    stack = await setupTestStack({
-      features: [chainFeature],
-      jobs: { consumerLane: "worker" },
-    });
-
-    await stack.http.writeOk("draintestchain:write:start", { value: "hi" }, TestUsers.admin);
-    await stack.drainJobs();
-
-    expect(chainResults).toEqual([{ value: "hi" }]);
-  });
-
-  test("a huge event-dispatcher poll interval doesn't stop drainJobs() from driving the cascade itself", async () => {
-    chainResults.length = 0;
-    stack = await setupTestStack({
-      features: [chainFeature],
-      jobs: { consumerLane: "worker" },
-    });
-    // stop() tears down both the poll timer AND the LISTEN/NOTIFY
-    // subscription (idempotent — cleanup()'s own stop() later is a no-op).
-    // runOnce() still works afterward (event-dispatcher.ts's own contract),
-    // so this leaves drainJobs() as the ONLY thing that can advance the
-    // job-trigger consumer past job A's emitted event — without this, the
-    // always-on pgClient wake-up races the assertion regardless of
-    // eventDispatcherPollIntervalMs.
-    await stack.eventDispatcher?.stop();
-
-    await stack.http.writeOk("draintestchain:write:start", { value: "race" }, TestUsers.admin);
-    await stack.drainJobs();
-
-    expect(chainResults).toEqual([{ value: "race" }]);
-  });
-});
-
-describe("stack.drainJobs() surfaces final job failures", () => {
-  test("a job that always throws rejects drainJobs() with its name and error", async () => {
-    alwaysFailsRuns.length = 0;
-    stack = await setupTestStack({
-      features: [failureFeature],
-      jobs: { consumerLane: "worker" },
-    });
-
-    await stack.jobRunner?.dispatch("draintestfailure:job:always-fails");
-
-    await expect(stack.drainJobs()).rejects.toThrow(
-      /draintestfailure:job:always-fails.*job-c always fails/s,
-    );
-
-    // The tracker is cleared after a rejection — a later drainJobs() call
-    // (e.g. the next test's setup) must not still see this failure.
-    await expect(stack.drainJobs()).resolves.toBeUndefined();
-  });
-
-  test("a job with retries:1 that fails once then succeeds resolves drainJobs()", async () => {
-    retrySucceedsAttempts.length = 0;
-    stack = await setupTestStack({
-      features: [failureFeature],
-      jobs: { consumerLane: "worker" },
-    });
-
-    await stack.jobRunner?.dispatch("draintestfailure:job:retry-succeeds");
-
-    await expect(stack.drainJobs()).resolves.toBeUndefined();
-    expect(retrySucceedsAttempts).toHaveLength(2);
-  });
-});
-
-describe("stack.drainJobs() without a jobRunner", () => {
-  test("rejects with a clear message when the stack has no `jobs` opt-in", async () => {
-    stack = await setupTestStack({ features: [chainFeature] });
-
-    await expect(stack.drainJobs()).rejects.toThrow(/jobRunner is undefined/);
-  });
-});

package/src/stack/__tests__/event-collector.test.ts

@@ -1,42 +0,0 @@
-import { describe, expect, test } from "bun:test";
-import type { SseEvent } from "../../api/sse-broker";
-import type { SaveContext } from "../../engine/types";
-import { createEventCollector } from "../event-collector";
-
-const probeSseEvent: SseEvent = { type: "probe", data: {} };
-const probeSaveContext: SaveContext = {
-  kind: "save",
-  id: "e1",
-  data: {},
-  changes: {},
-  previous: {},
-  isNew: true,
-};
-
-describe("createEventCollector", () => {
-  test("starts empty", () => {
-    const collector = createEventCollector();
-    expect(collector.sse).toEqual([]);
-    expect(collector.postSave).toEqual([]);
-  });
-
-  test("reset() clears both arrays in place, keeping the same references", () => {
-    const collector = createEventCollector();
-    const sseRef = collector.sse;
-    const postSaveRef = collector.postSave;
-    collector.sse.push(probeSseEvent);
-    collector.postSave.push(probeSaveContext);
-
-    expect(collector.sse).toHaveLength(1);
-    expect(collector.postSave).toHaveLength(1);
-
-    collector.reset();
-
-    expect(collector.sse).toHaveLength(0);
-    expect(collector.postSave).toHaveLength(0);
-    // Same array instances — callers that captured a reference before reset
-    // still see the cleared state, not a stale snapshot.
-    expect(collector.sse).toBe(sseRef);
-    expect(collector.postSave).toBe(postSaveRef);
-  });
-});