@cosmicdrift/kumiko-framework 0.171.2 → 0.173.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.171.2",
+  "version": "0.173.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>",
@@ -182,7 +182,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-types": "0.171.2",
+    "@cosmicdrift/kumiko-types": "0.173.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.12.27",
@@ -198,7 +198,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.171.2",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.173.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/api/__tests__/api.test.ts

@@ -532,8 +532,14 @@ describe("POST /api/stream pre-pull race", () => {
     // First .next() takes longer than heartbeatMs → settledInTime=false →
     // streamSSE opens immediately and pumpStream emits ping until the chunk
     // arrives (framework#1547 route-level contract).
+    //
+    // 25x the heartbeat, not 3x: the assertion rides on the timer winning the
+    // race, and a loaded CI runner delays timers by tens of milliseconds. At
+    // 60ms the timer occasionally fired after the chunk, the route took the
+    // settled path, and the run failed with ["chunk","done"] — a red main that
+    // blocks the release job.
     const dispatcher = stubDispatcher(async function* () {
-      await Bun.sleep(60);
+      await Bun.sleep(500);
       yield { i: 0 };
     });
     const app = mountStreamApp(dispatcher, 20);

package/src/crypto/__tests__/kms-wiring.test.ts

@@ -124,6 +124,15 @@ describe("resolveKmsWiring", () => {
     );
   });
 
+  test("rejects rotation settings when the main trio is absent", () => {
+    expect(() =>
+      resolveKmsWiring({
+        PLATFORM_KEK_PREVIOUS: KEK_B,
+        PLATFORM_KEK_PREVIOUS_VERSION: "1",
+      }),
+    ).toThrow(/all-or-none/);
+  });
+
   test.each([
     ["PLATFORM_KEK_PREVIOUS without version", { PLATFORM_KEK_PREVIOUS: KEK_B }],
     ["version without PLATFORM_KEK_PREVIOUS", { PLATFORM_KEK_PREVIOUS_VERSION: "1" }],

package/src/crypto/__tests__/pg-kms-adapter.integration.test.ts

@@ -93,6 +93,25 @@ describe("PgKmsAdapter — pg specifics", () => {
     expect(rows[0]?.["erase_reason"]).toBe("user-forget");
   });
 
+  test("concurrent cold-start createSchema across processes does not crash", async () => {
+    const coldDb = await createTestDb();
+    const coldUrl = baseUrl.replace(/\/[^/]+$/, `/${coldDb.dbName}`);
+    const kek = randomBytes(32).toString("base64");
+    const adapters = Array.from(
+      { length: 4 },
+      () => new PgKmsAdapter({ databaseUrl: coldUrl, platformKek: kek, maxConnections: 1 }),
+    );
+    try {
+      // Simulates API + worker processes booting simultaneously against a
+      // schema-less DB — each adapter races createSchema on its own connection.
+      const results = await Promise.all(adapters.map((a) => a.health()));
+      expect(results.every((r) => r.ok)).toBe(true);
+    } finally {
+      await Promise.all(adapters.map((a) => a.close()));
+      await coldDb.cleanup();
+    }
+  });
+
   test("repeat erase keeps the original tombstone audit fields", async () => {
     const user = freshUser();
     await adapter.createKey(user, ctx);

package/src/crypto/kms-wiring.ts

@@ -115,10 +115,17 @@ function assertTrioConsistent(env: KmsWiringEnv, logPrefix: string | undefined):
   }
   if (Boolean(env.PLATFORM_KEK_PREVIOUS) !== Boolean(env.PLATFORM_KEK_PREVIOUS_VERSION)) {
     throw new Error(
-      "PLATFORM_KEK_PREVIOUS and PLATFORM_KEK_PREVIOUS_VERSION must be set together " +
+      `${logPrefix ? `${logPrefix} ` : ""}PLATFORM_KEK_PREVIOUS and ` +
+        "PLATFORM_KEK_PREVIOUS_VERSION must be set together " +
         "(KEK rotation, runbook kek-rotation.md).",
     );
   }
+  if (!complete && (env.PLATFORM_KEK_PREVIOUS || env.PLATFORM_KEK_PREVIOUS_VERSION)) {
+    throw new Error(
+      `${logPrefix ? `${logPrefix} ` : ""}PLATFORM_KEK / SUBJECT_KEYS_DATABASE_URL / ` +
+        "KUMIKO_BLIND_INDEX_KEY are all-or-none — rotation settings require the complete KMS wiring.",
+    );
+  }
   return complete;
 }
 

package/src/crypto/pg-kms-adapter.ts

@@ -46,6 +46,10 @@ function decodePlatformKek(base64: string): Buffer {
 
 const PG_UNIQUE_VIOLATION = "23505";
 
+// pg_advisory_xact_lock key for createSchema — serializes concurrent cold-start
+// DDL across processes sharing one subject-keys DB.
+const SCHEMA_ADVISORY_LOCK_KEY = 0x6b_6d_73_31; // 'kms1'
+
 function isPgUniqueViolation(error: unknown): boolean {
   return (
     typeof error === "object" &&
@@ -182,23 +186,26 @@ export class PgKmsAdapter implements LocalKeyKmsAdapter {
   }
 
   private async createSchema(): Promise<void> {
-    await this.sql`
-      CREATE TABLE IF NOT EXISTS kumiko_subject_keys (
-        subject_id    TEXT        PRIMARY KEY,
-        cipher_key    BYTEA,
-        kek_version   INTEGER     NOT NULL DEFAULT 1,
-        created_at    TIMESTAMPTZ NOT NULL DEFAULT now(),
-        created_by    TEXT,
-        erased_at     TIMESTAMPTZ,
-        erased_by     TEXT,
-        erase_reason  TEXT
-      )`;
-    await this.sql`
-      CREATE INDEX IF NOT EXISTS kumiko_subject_keys_erased_idx
-      ON kumiko_subject_keys (erased_at) WHERE erased_at IS NOT NULL`;
-    await this.sql`
-      CREATE INDEX IF NOT EXISTS kumiko_subject_keys_audit_idx
-      ON kumiko_subject_keys (created_at, erased_at)`;
+    await this.sql.begin(async (tx) => {
+      await tx`SELECT pg_advisory_xact_lock(${SCHEMA_ADVISORY_LOCK_KEY})`;
+      await tx`
+        CREATE TABLE IF NOT EXISTS kumiko_subject_keys (
+          subject_id    TEXT        PRIMARY KEY,
+          cipher_key    BYTEA,
+          kek_version   INTEGER     NOT NULL DEFAULT 1,
+          created_at    TIMESTAMPTZ NOT NULL DEFAULT now(),
+          created_by    TEXT,
+          erased_at     TIMESTAMPTZ,
+          erased_by     TEXT,
+          erase_reason  TEXT
+        )`;
+      await tx`
+        CREATE INDEX IF NOT EXISTS kumiko_subject_keys_erased_idx
+        ON kumiko_subject_keys (erased_at) WHERE erased_at IS NOT NULL`;
+      await tx`
+        CREATE INDEX IF NOT EXISTS kumiko_subject_keys_audit_idx
+        ON kumiko_subject_keys (created_at, erased_at)`;
+    });
   }
 }
 

package/src/engine/feature-manifest.ts

@@ -8,7 +8,6 @@
 
 import { compareByCodepoint } from "../utils";
 import { isEncryptedAtRest } from "./config-helpers";
-import type { ChangelogEntry } from "./feature-changelog";
 import { qualifyEntityName } from "./qualified-name";
 import type { Registry, UiHints } from "./types/feature";
 
@@ -65,9 +64,6 @@ export type ManifestFeature = {
   readonly uiHints?: UiHints;
   /** Optionaler Herkunfts-Tag (z.B. "enterprise") — gesetzt via Options. */
   readonly tier?: string;
-  /** Per-feature changelog entries (from changes.json). Optional —
-   *  absent when no changes.json exists or feature has no entries. */
-  readonly changelog?: readonly ChangelogEntry[];
 };
 
 export type FeatureManifest = {

package/src/entrypoint/__tests__/split-deploy.integration.test.ts

@@ -5,7 +5,8 @@
 // pin the public guarantees:
 //
 //   1. API entrypoint has no eventDispatcher/jobRunner handles.
-//   2. Worker entrypoint has no HTTP app.
+//   2. Worker entrypoint has no HTTP app, but does hand out the
+//      command-dispatcher — app-wired background components need it.
 //   3. All-in-one has both.
 //   4. Worker throws when there's literally nothing to consume (defensive
 //      guard — buildServer always wires an SSE consumer so this only
@@ -14,10 +15,11 @@
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
 import { z } from "zod";
 import { type BunTestDb, createTestDb } from "../../bun-db/__tests__/bun-test-db";
+import { asRawClient } from "../../db/query";
 import { createRegistry, defineFeature } from "../../engine";
 import { createArchivedStreamsTable, createEventsTable } from "../../event-store";
 import { createEventConsumerStateTable } from "../../pipeline";
-import { createTestRedis, type TestRedis } from "../../stack";
+import { createTestRedis, type TestRedis, TestUsers } from "../../stack";
 import { createAllInOneEntrypoint, createApiEntrypoint, createWorkerEntrypoint } from "../index";
 
 const splitFeature = defineFeature("split", (r) => {
@@ -30,6 +32,24 @@ const splitFeature = defineFeature("split", (r) => {
   });
 });
 
+const workerWriteFeature = defineFeature("workerWrite", (r) => {
+  const noted = r.defineEvent("noted", z.object({ note: z.string() }), { version: 1 });
+  r.writeHandler(
+    "note",
+    z.object({ note: z.string() }),
+    async (event, ctx) => {
+      await ctx.unsafeAppendEvent({
+        aggregateId: crypto.randomUUID(),
+        aggregateType: "worker-note",
+        type: noted.name,
+        payload: { note: event.payload.note },
+      });
+      return { isSuccess: true as const, data: { note: event.payload.note } };
+    },
+    { access: { openToAll: true } },
+  );
+});
+
 const JWT = "split-deploy-test-secret-must-be-32-chars!!";
 
 // Per-test queue-name with a random suffix. Date.now() alone collided
@@ -86,6 +106,7 @@ describe("entrypoint factories", () => {
     expect(worker.mode).toBe("worker");
     expect(worker.eventDispatcher).toBeDefined();
     expect(worker.jobRunner).toBeDefined();
+    expect(worker.dispatcher).toBeDefined();
     expect("app" in worker).toBe(false);
     expect("jwt" in worker).toBe(false);
 
@@ -95,6 +116,42 @@ describe("entrypoint factories", () => {
     await worker.stop();
   });
 
+  // An app-wired component running in the worker (analysis service, IMAP
+  // supervisor) has to persist its result, and persisting goes through the
+  // write-path — JobContext has no write/query. The dispatcher is the only
+  // way in, so a worker that doesn't hand it out forces such a component
+  // into the API process, which defeats the split.
+  test("Worker dispatcher runs a write end-to-end — handler executes, event lands in the store", async () => {
+    const registry = createRegistry([workerWriteFeature]);
+    const redisUrl = `redis://${testRedis.redis.options.host}:${testRedis.redis.options.port}/${testRedis.redis.options.db}`;
+    const worker = createWorkerEntrypoint({
+      registry,
+      context: { db: testDb.db, redis: testRedis.redis },
+      jwtSecret: JWT,
+      redisUrl,
+      queueNamePrefix: uniquePrefix("split-dispatch"),
+    });
+
+    try {
+      const result = await worker.dispatcher.write(
+        "worker-write:write:note",
+        { note: "written from the worker" },
+        TestUsers.admin,
+      );
+      expect(result.isSuccess).toBe(true);
+
+      const rows = await asRawClient(testDb.db).unsafe(
+        `SELECT payload FROM kumiko_events WHERE type = 'worker-write:event:noted'`,
+      );
+      expect(rows).toHaveLength(1);
+      expect((rows[0] as { payload: { note: string } }).payload.note).toBe(
+        "written from the worker",
+      );
+    } finally {
+      await worker.stop();
+    }
+  });
+
   test("All-in-one entrypoint has both HTTP surface and background workers", async () => {
     const registry = createRegistry([splitFeature]);
     const redisUrl = process.env["REDIS_URL"] ?? "redis://localhost:16379";

package/src/entrypoint/index.ts

@@ -142,6 +142,12 @@ export type WorkerEntrypoint = {
   readonly eventDispatcher: EventDispatcher;
   readonly jobRunner: JobRunner;
   readonly observability: ObservabilityProvider;
+  // Same dispatcher the API process exposes — a worker builds the identical
+  // server, only without routes. App-wired components that run in the worker
+  // and must persist their result need it: JobContext has no write/query
+  // (handlers.ts JobContext), so writing goes through dispatchSystemWrite,
+  // the pattern inbound-mail-foundation/watch-supervisor.ts established.
+  readonly dispatcher: Dispatcher;
   readonly mode: "worker";
   // Starts event-dispatcher poll + BullMQ worker. SIGTERM triggers
   // `lifecycle.drain()`, which stops both via registered hooks.
@@ -428,6 +434,7 @@ export function createWorkerEntrypoint(options: WorkerEntrypointOptions): Worker
     eventDispatcher,
     jobRunner,
     observability: server.observability,
+    dispatcher: server.dispatcher,
     mode: "worker",
     async start() {
       await eventDispatcher.start();

package/src/jobs/index.ts

@@ -1,2 +1,2 @@
 export type { JobLogEntry, JobMeta, JobRunner, JobRunnerOptions } from "./job-runner";
-export { createJobRunner, schedulerIdForJobName } from "./job-runner";
+export { createJobRunner } from "./job-runner";

package/src/jobs/job-runner.ts

@@ -45,7 +45,7 @@ export function schedulerIdForJobName(jobName: string): string {
   return `scheduler-${jobName.replace(/[.:]/g, "-")}`;
 }
 
-/** Pre-sanitize id (`.` only) — remove on boot so colon-form ghosts die. */
+// ponytail: migration shim, remove after fw#1603 deploy is everywhere.
 function legacySchedulerIdForJobName(jobName: string): string {
   return `scheduler-${jobName.replace(/\./g, "-")}`;
 }