@cosmicdrift/kumiko-framework 1.0.0 → 2.0.0

package/README.md

@@ -28,9 +28,10 @@ Bun is the intended runtime and test runner.
 ## At-a-glance
 
 ```typescript
-import { defineFeature, createEntity, createTextField } from "@cosmicdrift/kumiko-framework/engine";
+import { createEntity, createTextField, defineFeature } from "@cosmicdrift/kumiko-framework/engine";
 
 export const taskEntity = createEntity({
+  table: "read_tasks",
   fields: {
     title: createTextField({ required: true, searchable: true }),
     done: createTextField(),
@@ -38,44 +39,14 @@ export const taskEntity = createEntity({
   softDelete: true,
 });
 
-const taskTable = buildDrizzleTable("task", taskEntity);
-const taskExecutor = createEventStoreExecutor(taskTable, taskEntity, { entityName: "task" });
-
 export const taskFeature = defineFeature("tasks", (r) => {
-  r.entity("task", taskEntity);
-
-  // Write handlers go through createEventStoreExecutor — events + projection in one TX,
-  // optimistic locking, access control, all explicit.
-  r.writeHandler(
-    "task:create",
-    z.object({ title: z.string() }),
-    async (event, ctx) => taskExecutor.create(event.payload, event.user, ctx.db),
-    { access: { roles: ["User"] } },
-  );
-  r.writeHandler(
-    "task:update",
-    z.object({ id: z.uuid(), version: z.number(), changes: z.object({ title: z.string().optional() }) }),
-    async (event, ctx) => taskExecutor.update(event.payload, event.user, ctx.db),
-    { access: { roles: ["User"] } },
-  );
-  r.writeHandler(
-    "task:delete",
-    z.object({ id: z.uuid() }),
-    async (event, ctx) => taskExecutor.delete(event.payload, event.user, ctx.db),
-    { access: { roles: ["Admin"] } },
-  );
-  r.queryHandler(
-    "task:list",
-    z.object({}),
-    async (query, ctx) => taskExecutor.list(query.payload, query.user, ctx.db),
-    { access: { openToAll: true } },
-  );
-  r.queryHandler(
-    "task:detail",
-    z.object({ id: z.uuid() }),
-    async (query, ctx) => taskExecutor.detail(query.payload, query.user, ctx.db),
-    { access: { openToAll: true } },
-  );
+  // r.crud wires create/update/delete/restore + list/detail queries in one
+  // call — events + projection in the same TX, optimistic locking, access
+  // control, all explicit via the options below.
+  r.crud("task", taskEntity, {
+    write: { access: { roles: ["User"] } },
+    read: { access: { openToAll: true } },
+  });
 
   // Read-model fed from task events, rebuildable via the CLI
   r.projection({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "1.0.0",
+  "version": "2.0.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>",
@@ -99,6 +99,10 @@
       "types": "./src/jobs/index.ts",
       "default": "./src/jobs/index.ts"
     },
+    "./observability": {
+      "types": "./src/observability/index.ts",
+      "default": "./src/observability/index.ts"
+    },
     "./migrations": {
       "types": "./src/migrations/index.ts",
       "default": "./src/migrations/index.ts"
@@ -131,10 +135,22 @@
       "types": "./src/secrets/index.ts",
       "default": "./src/secrets/index.ts"
     },
+    "./crypto": {
+      "types": "./src/crypto/index.ts",
+      "default": "./src/crypto/index.ts"
+    },
+    "./logging": {
+      "types": "./src/logging/index.ts",
+      "default": "./src/logging/index.ts"
+    },
     "./schema-cli": {
       "types": "./src/schema-cli.ts",
       "default": "./src/schema-cli.ts"
     },
+    "./consumer-cli": {
+      "types": "./src/consumer-cli.ts",
+      "default": "./src/consumer-cli.ts"
+    },
     "./stack": {
       "types": "./src/stack/index.ts",
       "default": "./src/stack/index.ts"
@@ -180,8 +196,11 @@
     "uuid": "^14.0.0",
     "zod": "^4.4.3"
   },
+  "peerDependencies": {
+    "@cosmicdrift/kumiko-types": "^2.0.0"
+  },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "1.0.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "2.0.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/__tests__/anonymous-access.integration.test.ts

@@ -8,6 +8,7 @@
 
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
 import { z } from "zod";
+import type { AnonymousAccessConfig } from "../api/auth-middleware";
 import { createEventStoreExecutor } from "../db/event-store-executor";
 import { asRawClient, selectMany } from "../db/query";
 import { buildEntityTable } from "../db/table-builder";
@@ -307,6 +308,190 @@ describe("anonymous access — header-supplied tenant", () => {
   });
 });
 
+describe("anonymous access — resolverTrust: authoritative", () => {
+  let stack: TestStack;
+
+  beforeAll(async () => {
+    // Simulates a subdomain resolver: TENANT_ID is "known" (the resolver
+    // recognises it), everything else is an unrecognised host (null).
+    stack = await setupTestStack({
+      features: [shopFeature],
+      anonymousAccess: {
+        tenantResolver: () => TENANT_ID,
+        resolverTrust: "authoritative",
+        tenantExists: async (id: TenantId) => id === TENANT_ID || id === OTHER_TENANT_ID,
+      },
+    });
+    await unsafeCreateEntityTable(stack.db, productEntity);
+    await unsafeCreateEntityTable(stack.db, orderEntity);
+  });
+
+  afterAll(() => stack.cleanup());
+
+  test("no client tenant → resolver wins", async () => {
+    const res = await stack.http.raw("POST", "/api/query", {
+      type: "anonshop:query:product:list",
+      payload: {},
+    });
+    expect(res.status).toBe(200);
+  });
+
+  test("X-Tenant header agreeing with the resolver → accepted", async () => {
+    const res = await stack.http.raw(
+      "POST",
+      "/api/query",
+      { type: "anonshop:query:product:list", payload: {} },
+      { "X-Tenant": TENANT_ID },
+    );
+    expect(res.status).toBe(200);
+  });
+
+  test("X-Tenant header disagreeing with the resolver → 400 tenant_mismatch, resolver's tenant is NOT overridden", async () => {
+    // The core #51 regression: a header claiming a different (real, active)
+    // tenant than the one the resolver derived must never win — that would
+    // let a guest on tenantA's subdomain write into tenantB by forging a
+    // header. Reject, don't silently prefer either side.
+    const res = await stack.http.raw(
+      "POST",
+      "/api/query",
+      { type: "anonshop:query:product:list", payload: {} },
+      { "X-Tenant": OTHER_TENANT_ID },
+    );
+    expect(res.status).toBe(400);
+    const body = (await res.json()) as { error: { code: string } };
+    expect(body.error.code).toBe("tenant_mismatch");
+  });
+
+  // pr-review kumiko-framework #1052/3 — resolveTenant treats header and
+  // cookie identically, but every case above only exercised the header.
+  // These two lock in that the cookie path behaves the same way.
+  test("kumiko_tenant cookie agreeing with the resolver → accepted", async () => {
+    const res = await stack.http.raw(
+      "POST",
+      "/api/query",
+      { type: "anonshop:query:product:list", payload: {} },
+      { Cookie: `kumiko_tenant=${TENANT_ID}` },
+    );
+    expect(res.status).toBe(200);
+  });
+
+  test("kumiko_tenant cookie disagreeing with the resolver → 400 tenant_mismatch, same as a disagreeing header", async () => {
+    const res = await stack.http.raw(
+      "POST",
+      "/api/query",
+      { type: "anonshop:query:product:list", payload: {} },
+      { Cookie: `kumiko_tenant=${OTHER_TENANT_ID}` },
+    );
+    expect(res.status).toBe(400);
+    const body = (await res.json()) as { error: { code: string } };
+    expect(body.error.code).toBe("tenant_mismatch");
+  });
+});
+
+describe("anonymous access — resolverTrust: authoritative, resolver returns null", () => {
+  let stack: TestStack;
+
+  beforeAll(async () => {
+    // Resolver never recognises the host (e.g. an unmapped/unknown
+    // subdomain) — always returns null.
+    stack = await setupTestStack({
+      features: [shopFeature],
+      anonymousAccess: {
+        tenantResolver: () => null,
+        resolverTrust: "authoritative",
+        tenantExists: async (id: TenantId) => id === TENANT_ID || id === OTHER_TENANT_ID,
+      },
+    });
+    await unsafeCreateEntityTable(stack.db, productEntity);
+    await unsafeCreateEntityTable(stack.db, orderEntity);
+  });
+
+  afterAll(() => stack.cleanup());
+
+  test("resolver null + X-Tenant header present → 400 tenant_required, header does NOT pick the tenant", async () => {
+    // If this fell back to the client header, an unrecognised-host request
+    // could still choose its own tenant via X-Tenant — the same override
+    // "authoritative" exists to prevent, just reached via "unknown host"
+    // instead of "known host, disagreeing header".
+    const res = await stack.http.raw(
+      "POST",
+      "/api/query",
+      { type: "anonshop:query:product:list", payload: {} },
+      { "X-Tenant": TENANT_ID },
+    );
+    expect(res.status).toBe(400);
+    const body = (await res.json()) as { error: { code: string } };
+    expect(body.error.code).toBe("tenant_required");
+  });
+
+  test("resolver null + no client tenant → 400 tenant_required", async () => {
+    const res = await stack.http.raw("POST", "/api/query", {
+      type: "anonshop:query:product:list",
+      payload: {},
+    });
+    expect(res.status).toBe(400);
+    const body = (await res.json()) as { error: { code: string } };
+    expect(body.error.code).toBe("tenant_required");
+  });
+});
+
+describe("anonymous access — resolverTrust: fallback-only", () => {
+  let stack: TestStack;
+
+  beforeAll(async () => {
+    stack = await setupTestStack({
+      features: [shopFeature],
+      anonymousAccess: {
+        tenantResolver: () => TENANT_ID,
+        resolverTrust: "fallback-only",
+        tenantExists: async (id: TenantId) => id === TENANT_ID || id === OTHER_TENANT_ID,
+      },
+    });
+    await unsafeCreateEntityTable(stack.db, productEntity);
+    await unsafeCreateEntityTable(stack.db, orderEntity);
+  });
+
+  afterAll(() => stack.cleanup());
+
+  test("X-Tenant header disagreeing with the resolver → header wins (documented convenience-fallback behaviour)", async () => {
+    // Opposite of "authoritative": a client tenant that disagrees with the
+    // resolver is accepted, not rejected — this mode is for resolvers that
+    // carry no more trust than the client's own claim.
+    const res = await stack.http.raw(
+      "POST",
+      "/api/query",
+      { type: "anonshop:query:product:list", payload: {} },
+      { "X-Tenant": OTHER_TENANT_ID },
+    );
+    expect(res.status).toBe(200);
+  });
+
+  test("no client tenant → resolver runs as fallback", async () => {
+    const res = await stack.http.raw("POST", "/api/query", {
+      type: "anonshop:query:product:list",
+      payload: {},
+    });
+    expect(res.status).toBe(200);
+  });
+});
+
+describe("anonymous access — tenantResolver without resolverTrust", () => {
+  test("authMiddleware throws at boot, not silently at request time", async () => {
+    await expect(
+      setupTestStack({
+        features: [shopFeature],
+        // Simulates a caller that bypasses the compiler (JS consumer, an
+        // `as any` cast) — the discriminated union stops well-typed callers,
+        // this proves the runtime guard behind it also fires.
+        anonymousAccess: {
+          tenantResolver: () => TENANT_ID,
+          resolverTrust: undefined,
+        } as unknown as AnonymousAccessConfig,
+      }),
+    ).rejects.toThrow(/resolverTrust/);
+  });
+});
+
 describe("anonymous access — disabled by default", () => {
   let stack: TestStack;
 

package/src/__tests__/consumer-cli.integration.test.ts

@@ -0,0 +1,172 @@
+// Integration test for `runConsumerCli` (kumiko-framework#1351).
+//
+// Recovery semantics themselves are already covered by
+// event-dispatcher-recovery — this only exercises the CLI layer: argv
+// parsing, DB-connection handling, exit codes, output formatting.
+
+import { afterAll, afterEach, beforeAll, describe, expect, test } from "bun:test";
+import { type BunTestDb, createTestDb } from "../bun-db/__tests__/bun-test-db";
+import { type ConsumerCliOut, runConsumerCli } from "../consumer-cli";
+import { insertConsumerIfAbsent, markConsumerRebuildFailed } from "../db/queries/event-consumer";
+import { asRawClient } from "../db/query";
+import { createEventConsumerStateTable } from "../pipeline";
+import { ensureTemporalPolyfill } from "../time/polyfill";
+
+const SHARED = "__shared__";
+
+let testDb: BunTestDb;
+let testUrl: string;
+let prevDbUrl: string | undefined;
+
+beforeAll(async () => {
+  await ensureTemporalPolyfill();
+  testDb = await createTestDb();
+  const baseUrl = process.env["TEST_DATABASE_URL"];
+  if (!baseUrl) throw new Error("TEST_DATABASE_URL not set — required for this test file");
+  testUrl = baseUrl.replace(/\/[^/]+$/, `/${testDb.dbName}`);
+  await createEventConsumerStateTable(testDb.db);
+});
+
+afterAll(async () => {
+  await testDb.cleanup();
+});
+
+afterEach(async () => {
+  await asRawClient(testDb.db).unsafe(`TRUNCATE TABLE "kumiko_event_consumers"`);
+  if (prevDbUrl === undefined) delete process.env["DATABASE_URL"];
+  else process.env["DATABASE_URL"] = prevDbUrl;
+});
+
+function captureOut(): { out: ConsumerCliOut; lines: string[] } {
+  const lines: string[] = [];
+  return {
+    out: { log: (l: string) => lines.push(l), err: (l: string) => lines.push(`ERR ${l}`) },
+    lines,
+  };
+}
+
+describe("runConsumerCli status", () => {
+  test("unknown consumer → exit 1, not-found message", async () => {
+    prevDbUrl = process.env["DATABASE_URL"];
+    process.env["DATABASE_URL"] = testUrl;
+    const { out, lines } = captureOut();
+    const code = await runConsumerCli(["status", "no-such-consumer"], out);
+    expect(code).toBe(1);
+    expect(lines.join("\n")).toContain("not found");
+  });
+
+  test("known consumer → exit 0, reports status/cursor/attempts", async () => {
+    prevDbUrl = process.env["DATABASE_URL"];
+    process.env["DATABASE_URL"] = testUrl;
+    await insertConsumerIfAbsent(testDb.db, "test:consumer:foo", SHARED);
+    const { out, lines } = captureOut();
+    const code = await runConsumerCli(["status", "test:consumer:foo"], out);
+    expect(code).toBe(0);
+    const joined = lines.join("\n");
+    expect(joined).toContain("test:consumer:foo");
+    expect(joined).toContain("status:      idle");
+  });
+
+  test("missing <name> → exit 1, usage message", async () => {
+    prevDbUrl = process.env["DATABASE_URL"];
+    process.env["DATABASE_URL"] = testUrl;
+    const { out, lines } = captureOut();
+    const code = await runConsumerCli(["status"], out);
+    expect(code).toBe(1);
+    expect(lines.join("\n")).toContain("Usage:");
+  });
+
+  test("missing DATABASE_URL → exit 1", async () => {
+    prevDbUrl = process.env["DATABASE_URL"];
+    delete process.env["DATABASE_URL"];
+    const { out, lines } = captureOut();
+    const code = await runConsumerCli(["status", "whatever"], out);
+    expect(code).toBe(1);
+    expect(lines.join("\n")).toContain("DATABASE_URL not set");
+  });
+
+  test("--instance-id flag → status looks up the per-instance consumer, not shared", async () => {
+    prevDbUrl = process.env["DATABASE_URL"];
+    process.env["DATABASE_URL"] = testUrl;
+    await insertConsumerIfAbsent(testDb.db, "test:consumer:inst", "inst-1");
+    const { out, lines } = captureOut();
+    const code = await runConsumerCli(
+      ["status", "test:consumer:inst", "--instance-id", "inst-1"],
+      out,
+    );
+    expect(code).toBe(0);
+    const joined = lines.join("\n");
+    expect(joined).toContain('instance_id="inst-1"');
+  });
+
+  test("--instance-id=<id> form is recognised (#1412)", async () => {
+    prevDbUrl = process.env["DATABASE_URL"];
+    process.env["DATABASE_URL"] = testUrl;
+    await insertConsumerIfAbsent(testDb.db, "test:consumer:eq", "inst-2");
+    const { out, lines } = captureOut();
+    const code = await runConsumerCli(["status", "test:consumer:eq", "--instance-id=inst-2"], out);
+    expect(code).toBe(0);
+    expect(lines.join("\n")).toContain('instance_id="inst-2"');
+  });
+
+  test("--instance-id before the name still parses the name correctly (#1412)", async () => {
+    prevDbUrl = process.env["DATABASE_URL"];
+    process.env["DATABASE_URL"] = testUrl;
+    await insertConsumerIfAbsent(testDb.db, "test:consumer:order", "inst-3");
+    const { out, lines } = captureOut();
+    const code = await runConsumerCli(
+      ["status", "--instance-id", "inst-3", "test:consumer:order"],
+      out,
+    );
+    expect(code).toBe(0);
+    expect(lines.join("\n")).toContain('instance_id="inst-3"');
+  });
+
+  test("--instance-id with a missing value errors instead of silently falling back to shared (#1412)", async () => {
+    prevDbUrl = process.env["DATABASE_URL"];
+    process.env["DATABASE_URL"] = testUrl;
+    const { out, lines } = captureOut();
+    const code = await runConsumerCli(["status", "test:consumer:foo", "--instance-id"], out);
+    expect(code).toBe(1);
+    expect(lines.join("\n")).toContain("--instance-id braucht einen Wert");
+  });
+});
+
+describe("runConsumerCli — unknown/empty subcommand exit codes", () => {
+  test("no subcommand at all → exit 0 (usage, not an error)", async () => {
+    const { out, lines } = captureOut();
+    const code = await runConsumerCli([], out);
+    expect(code).toBe(0);
+    expect(lines.join("\n")).toContain("Subcommands:");
+  });
+
+  test("an unrecognized subcommand → exit 1", async () => {
+    const { out, lines } = captureOut();
+    const code = await runConsumerCli(["bogus"], out);
+    expect(code).toBe(1);
+    expect(lines.join("\n")).toContain("Subcommands:");
+  });
+});
+
+describe("runConsumerCli restart", () => {
+  test("dead consumer → idle, exit 0", async () => {
+    prevDbUrl = process.env["DATABASE_URL"];
+    process.env["DATABASE_URL"] = testUrl;
+    await insertConsumerIfAbsent(testDb.db, "test:consumer:bar", SHARED);
+    await markConsumerRebuildFailed(testDb.db, "test:consumer:bar", SHARED, "boom");
+    const { out, lines } = captureOut();
+    const code = await runConsumerCli(["restart", "test:consumer:bar"], out);
+    expect(code).toBe(0);
+    expect(lines.join("\n")).toContain("→ idle");
+  });
+
+  test("non-dead consumer → propagated error, exit 1", async () => {
+    prevDbUrl = process.env["DATABASE_URL"];
+    process.env["DATABASE_URL"] = testUrl;
+    await insertConsumerIfAbsent(testDb.db, "test:consumer:baz", SHARED);
+    const { out, lines } = captureOut();
+    const code = await runConsumerCli(["restart", "test:consumer:baz"], out);
+    expect(code).toBe(1);
+    expect(lines.join("\n")).toContain("not dead");
+  });
+});

package/src/__tests__/entity-permalink-open.integration.test.ts

@@ -0,0 +1,94 @@
+// Issue #912 — Teilbare Entity-Permalinks. Der Copy-Link-Button selbst ist
+// UI-Zucker (baut eine URL, kopiert sie); die eigentliche Anforderung des
+// Issues ist "ein Permalink darf nie Auth/Tenant-Isolation umgehen". Ein
+// entityEdit-Permalink öffnet beim Klick exactly denselben
+// `<feature>:query:<entity>:detail`-Call, den jede Entity schon für ihr
+// Update-Formular nutzt — es gibt keinen separaten Permalink-Resolve-Pfad.
+// Dieser Test beweist den Deny für beide Achsen, die einen Leak verhindern
+// müssten: Rollen-Gate (dispatcher-seitig, default-deny) und Tenant-Scoping
+// (strukturell über ctx.db).
+
+import { describe, expect, test } from "bun:test";
+import { setupTestStackFromFeatures } from "@cosmicdrift/kumiko-dev-server/setup-test-stack-from-features";
+import {
+  createEntity,
+  createTextField,
+  defineEntityCreateHandler,
+  defineEntityDetailHandler,
+  defineFeature,
+} from "@cosmicdrift/kumiko-framework/engine";
+import {
+  createTestUser,
+  pushEntityProjectionTables,
+  testTenantId,
+} from "@cosmicdrift/kumiko-framework/stack";
+
+const noteEntity = createEntity({
+  table: "read_permalink_notes",
+  fields: {
+    title: createTextField({ required: true, maxLength: 160, allowPlaintext: "is-business-data" }),
+  },
+});
+
+const permalinkFeature = defineFeature("permalink-fixture", (r) => {
+  r.entity("note", noteEntity);
+  const access = { roles: ["TenantAdmin"] } as const;
+  r.writeHandler(defineEntityCreateHandler("note", noteEntity, { access }));
+  r.queryHandler(defineEntityDetailHandler("note", noteEntity, { access }));
+});
+
+describe("entityEdit permalink open-path denies cleanly", () => {
+  test("unauthorized role → AccessDeniedError, not the record", async () => {
+    const stack = await setupTestStackFromFeatures([permalinkFeature]);
+    try {
+      const tenantId = testTenantId(701);
+      const owner = createTestUser({ id: 701, tenantId, roles: ["TenantAdmin"] });
+      const outsider = createTestUser({ id: 702, tenantId, roles: ["TeamMember"] });
+      await pushEntityProjectionTables(stack, stack.registry);
+
+      const created = await stack.http.writeOk<{ id: string }>(
+        "permalink-fixture:write:note:create",
+        { title: "Q3 Forecast" },
+        owner,
+      );
+
+      const res = await stack.http.query(
+        "permalink-fixture:query:note:detail",
+        { id: created.id },
+        outsider,
+      );
+      expect(res.ok).toBe(false);
+      const body = (await res.json()) as { isSuccess?: boolean; error?: { code?: string } };
+      expect(body.isSuccess).not.toBe(true);
+      expect(body.error?.code).toBe("access_denied");
+    } finally {
+      await stack.cleanup();
+    }
+  });
+
+  test("cross-tenant open → not-found, not the other tenant's record", async () => {
+    const stack = await setupTestStackFromFeatures([permalinkFeature]);
+    try {
+      const tenantA = testTenantId(703);
+      const tenantB = testTenantId(704);
+      const ownerA = createTestUser({ id: 703, tenantId: tenantA, roles: ["TenantAdmin"] });
+      const adminB = createTestUser({ id: 704, tenantId: tenantB, roles: ["TenantAdmin"] });
+      await pushEntityProjectionTables(stack, stack.registry);
+
+      const created = await stack.http.writeOk<{ id: string }>(
+        "permalink-fixture:write:note:create",
+        { title: "Tenant A Secret" },
+        ownerA,
+      );
+
+      const row = await stack.http.queryOk<Record<string, unknown> | null>(
+        "permalink-fixture:query:note:detail",
+        { id: created.id },
+        adminB,
+      );
+      expect(row).toBeNull();
+    } finally {
+      await stack.cleanup();
+    }
+  });
+});

package/src/__tests__/full-stack.integration.test.ts

@@ -182,7 +182,7 @@ const userFeature = defineFeature("users", (r) => {
     { access: { openToAll: true } },
   );
 
-  r.entityHook("postSave", user, async (result) => {
+  r.hook("postSave", { allOf: user }, async (result) => {
     featurePostSaveLog.push(result);
   });
 

package/src/__tests__/schema-cli-temporal-polyfill.test.ts

@@ -0,0 +1,48 @@
+import { afterEach, describe, expect, spyOn, test } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { runSchemaCli, type SchemaCliOut } from "../schema-cli";
+import * as timeModule from "../time";
+
+function captureOut(): { out: SchemaCliOut; log: string[]; err: string[] } {
+  const log: string[] = [];
+  const err: string[] = [];
+  return { out: { log: (l) => log.push(l), err: (l) => err.push(l) }, log, err };
+}
+
+describe("runSchemaCli — Temporal polyfill", () => {
+  let appCwd: string;
+
+  afterEach(() => {
+    if (appCwd) rmSync(appCwd, { recursive: true, force: true });
+  });
+
+  test("calls ensureTemporalPolyfill on every invocation", async () => {
+    // runProdApp/runDevApp call ensureTemporalPolyfill() at boot; the
+    // standalone CLI (migrate-db initContainer, `bun kumiko.js schema apply`)
+    // never goes through that boot path. Without this, a projection rebuild's
+    // tz/timestamp coercion throws "Temporal is not defined" on any runtime
+    // that lacks native Temporal — deterministically, since the crashed
+    // process still records the migration as applied and the rebuild is
+    // never retried on the next run.
+    //
+    // Asserting on globalThis.Temporal directly doesn't work here: the test
+    // harness's own preload (test-setup/base.preload.ts) already calls
+    // ensureTemporalPolyfill() once per process, and its idempotency cache
+    // (a module-level flag, not re-derived from globalThis) short-circuits
+    // any later call regardless of what a test does to globalThis.Temporal in
+    // between. Spying on the imported binding sidesteps that cache entirely.
+    appCwd = mkdtempSync(join(tmpdir(), "kumiko-schema-cli-temporal-"));
+    mkdirSync(join(appCwd, "kumiko"), { recursive: true });
+    const spy = spyOn(timeModule, "ensureTemporalPolyfill");
+    try {
+      const cap = captureOut();
+      const code = await runSchemaCli([], appCwd, cap.out);
+      expect(code).toBe(0);
+      expect(spy).toHaveBeenCalled();
+    } finally {
+      spy.mockRestore();
+    }
+  });
+});