@cosmicdrift/kumiko-framework 0.215.4 → 0.215.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.215.4",
+  "version": "0.215.6",
   "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>",
@@ -194,7 +194,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-types": "0.215.4",
+    "@cosmicdrift/kumiko-types": "0.215.6",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -210,7 +210,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.215.4",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.215.6",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/__tests__/store-table.integration.test.ts

@@ -49,7 +49,7 @@ describe("r.storeTable — DB roundtrip via setupTestStack", () => {
 
     expect(rows).toHaveLength(1);
     expect(rows[0]?.payload).toBe(payload);
-    expect(rows[0]?.receivedAt).toBeInstanceOf(Temporal.Instant);
+    expect(String(rows[0]?.receivedAt)).toMatch(/^\d{4}-\d{2}-\d{2}T/);
   });
 
   test("registry exposes the store table with its reason and featureName", () => {

package/src/bun-db/__tests__/coerce-row-plain-date.test.ts

@@ -28,7 +28,6 @@ describe("coerceRow — date → Temporal.PlainDate", () => {
     // (2026-03-15T00:00:00.000Z) regardless of process TZ.
     const row = { published_at: new Date(Date.UTC(2026, 2, 15)) };
     const result = coerceRow(row, dateTableInfo());
-    expect(result.published_at).toBeInstanceOf(Temporal.PlainDate);
     expect((result.published_at as unknown as Temporal.PlainDate).toString()).toBe("2026-03-15");
   });
 
@@ -51,7 +50,6 @@ describe("coerceRow — date → Temporal.PlainDate", () => {
   test("coerces a plain 'yyyy-mm-dd' driver string", () => {
     const row = { published_at: "2026-12-01" };
     const result = coerceRow(row, dateTableInfo());
-    expect(result.published_at).toBeInstanceOf(Temporal.PlainDate);
     expect((result.published_at as unknown as Temporal.PlainDate).toString()).toBe("2026-12-01");
   });
 

package/src/bun-db/__tests__/coerce-row-temporal.test.ts

@@ -8,7 +8,7 @@
 // coerceRow — proving the coercion no longer depends on the global at all.
 
 import { describe, expect, test } from "bun:test";
-import { Temporal } from "temporal-polyfill";
+import type { Temporal } from "temporal-polyfill";
 import { coerceRow, type TableInfo } from "../query";
 
 function timestamptzTableInfo(): TableInfo {
@@ -29,7 +29,6 @@ describe("coerceRow — timestamptz → Temporal.Instant", () => {
     try {
       const row = { updated_at: new Date("2026-04-18T10:00:00Z") };
       const result = coerceRow(row, timestamptzTableInfo());
-      expect(result.updated_at).toBeInstanceOf(Temporal.Instant);
       expect((result.updated_at as unknown as Temporal.Instant).toString()).toBe(
         "2026-04-18T10:00:00Z",
       );

package/src/db/__tests__/multi-row-insert.integration.test.ts

@@ -59,7 +59,9 @@ describe("instant() customType is forgiving with ISO strings", () => {
     });
     const rows = await selectMany(stack.db, tsTable);
     expect(rows).toHaveLength(1);
-    expect(rows[0]?.["insertedAt"]).toBeInstanceOf(Temporal.Instant);
+    const insertedAt = rows[0]?.["insertedAt"];
+    expect(insertedAt).toBeDefined();
+    expect((insertedAt as Temporal.Instant).toString()).toBe(isoString);
   });
 });
 

package/src/db/__tests__/schema-migration.integration.test.ts

@@ -314,7 +314,6 @@ describe("date field — real DATE column, no TZ dependence (kumiko-framework#19
     const rows = await selectMany(testDb.db, table);
     expect(rows).toHaveLength(1);
     const periodFrom = (rows[0] as { periodFrom: unknown }).periodFrom;
-    expect(periodFrom).toBeInstanceOf(Temporal.PlainDate);
     expect((periodFrom as Temporal.PlainDate).toString()).toBe("2026-03-15");
   });
 

package/src/db/__tests__/source-shadow-create.integration.test.ts

@@ -50,6 +50,8 @@ describe("entity with a `source` field — create-path is shadow-proof", () => {
     const rows = await selectMany(stack.db, sourceTable);
     expect(rows).toHaveLength(1);
     expect(rows[0]?.["source"]).toBe("import");
-    expect(rows[0]?.["insertedAt"]).toBeInstanceOf(Temporal.Instant);
+    const insertedAt = rows[0]?.["insertedAt"];
+    expect(insertedAt).toBeDefined();
+    expect((insertedAt as Temporal.Instant).toString()).toBe("2026-01-15T12:00:00Z");
   });
 });

package/src/engine/feature-ast/__tests__/parse.test.ts

@@ -138,7 +138,7 @@ defineFeature("wrapped", (r) => {
 `);
 
     expect(result.errors).toEqual([]);
-    expect(result.patterns.map((p) => p.kind)).toEqual(["systemScope", "entity", "requires"]);
+    expect(result.patterns.map((p) => p.kind)).toEqual(["entity", "requires", "systemScope"]);
   });
 
   test("recurses into a registrar-wrapper declared as a const arrow function", () => {
@@ -1823,6 +1823,226 @@ defineFeature("f", (r) => {
   });
 });
 
+describe("extractAiGenerate", () => {
+  test("captures inline object literal args", () => {
+    const result = parseInline(`
+const paramsSchema = z.object({ maxTokens: z.number().optional() });
+
+defineFeature("f", (r) => {
+  defineWorkflow({
+    name: "demo",
+    steps: stepsPipeline(({ r }) => [
+      aiGenerateStep({
+        stepKey: "generate",
+        promptKey: "demo:generate",
+        promptFallback: "Write a summary.",
+        paramsSchema,
+        defaults: { enabled: true, params: { maxTokens: 256 } },
+        input: (ctx) => ctx.event.label,
+      }),
+    ]),
+  });
+});
+`);
+
+    expect(result.errors).toEqual([]);
+    expect(result.patterns).toContainEqual(
+      expect.objectContaining({
+        kind: "ai.generate",
+        stepKey: "generate",
+        promptKey: "demo:generate",
+        promptFallback: "Write a summary.",
+        defaults: { enabled: true, params: { maxTokens: 256 } },
+      }),
+    );
+  });
+
+  test("resolves same-file const spec reference", () => {
+    const result = parseInline(`
+const paramsSchema = z.object({});
+const generateSpec = {
+  stepKey: "generate",
+  promptKey: "demo:generate",
+  promptFallback: "Write a summary.",
+  paramsSchema,
+  defaults: { enabled: true, params: {} },
+  input: (ctx) => ctx.event.label,
+};
+
+defineFeature("f", (r) => {
+  defineWorkflow({
+    name: "demo",
+    steps: stepsPipeline(() => [aiGenerateStep(generateSpec)]),
+  });
+});
+`);
+
+    expect(result.errors).toEqual([]);
+    expect(result.patterns).toContainEqual(
+      expect.objectContaining({ kind: "ai.generate", stepKey: "generate" }),
+    );
+  });
+});
+
+describe("extractAiExtract", () => {
+  test("captures inline extract step", () => {
+    const result = parseInline(`
+const paramsSchema = z.object({});
+
+defineFeature("f", (r) => {
+  defineWorkflow({
+    name: "demo",
+    steps: stepsPipeline(() => [
+      aiExtractStep({
+        stepKey: "extract",
+        promptKey: "demo:extract",
+        promptFallback: "Extract fields.",
+        paramsSchema,
+        defaults: { enabled: true, params: {} },
+        outputSchema: z.object({ title: z.string() }),
+        instructions: () => "Extract the title.",
+      }),
+    ]),
+  });
+});
+`);
+
+    expect(result.errors).toEqual([]);
+    expect(result.patterns).toContainEqual(
+      expect.objectContaining({ kind: "ai.extract", stepKey: "extract" }),
+    );
+  });
+});
+
+describe("extractAiClassify", () => {
+  test("keeps unresolvable spec ref as opaque argsSource", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  defineWorkflow({
+    name: "demo",
+    steps: stepsPipeline(() => [aiClassifyStep(importedSpec)]),
+  });
+});
+`);
+
+    expect(result.errors).toEqual([]);
+    expect(result.patterns).toContainEqual(
+      expect.objectContaining({
+        kind: "ai.classify",
+        argsSource: { __raw: "importedSpec" },
+      }),
+    );
+  });
+  test("defaults with both providerId and model round-trip", () => {
+    const result = parseInline(`
+const paramsSchema = z.object({ maxTokens: z.number().optional() });
+
+defineFeature("f", (r) => {
+  defineWorkflow({
+    name: "demo",
+    steps: stepsPipeline(() => [
+      aiGenerateStep({
+        stepKey: "generate",
+        promptKey: "demo:generate",
+        promptFallback: "Write a summary.",
+        paramsSchema,
+        defaults: {
+          enabled: true,
+          params: { maxTokens: 256 },
+          providerId: "openai",
+          model: "gpt-4",
+        },
+        input: (ctx) => ctx.event.label,
+      }),
+    ]),
+  });
+});
+`);
+
+    expect(result.errors).toEqual([]);
+    expect(result.patterns).toContainEqual(
+      expect.objectContaining({
+        kind: "ai.generate",
+        defaults: {
+          enabled: true,
+          params: { maxTokens: 256 },
+          providerId: "openai",
+          model: "gpt-4",
+        },
+      }),
+    );
+  });
+
+  test("ignores ai step calls outside defineWorkflow", () => {
+    const result = parseInline(`
+const paramsSchema = z.object({});
+
+function helperOutsideWorkflow() {
+  aiGenerateStep({
+    stepKey: "orphan",
+    promptKey: "demo:orphan",
+    promptFallback: "Should not appear.",
+    paramsSchema,
+    defaults: { enabled: true, params: {} },
+    input: (ctx) => ctx.event.label,
+  });
+}
+
+defineFeature("f", (r) => {
+  defineWorkflow({
+    name: "demo",
+    steps: stepsPipeline(() => [
+      aiGenerateStep({
+        stepKey: "inside",
+        promptKey: "demo:inside",
+        promptFallback: "Inside workflow.",
+        paramsSchema,
+        defaults: { enabled: true, params: {} },
+        input: (ctx) => ctx.event.label,
+      }),
+    ]),
+  });
+});
+`);
+
+    expect(result.errors).toEqual([]);
+    const aiPatterns = result.patterns.filter((p) => p.kind.startsWith("ai."));
+    expect(aiPatterns).toHaveLength(1);
+    expect(aiPatterns[0]).toMatchObject({ kind: "ai.generate", stepKey: "inside" });
+  });
+
+  test("patterns are sorted by source line when registrar patterns precede ai steps", () => {
+    const result = parseInline(`
+const paramsSchema = z.object({});
+
+defineFeature("f", (r) => {
+  r.entity({ name: "item", fields: { name: { type: "text", required: true } } });
+
+  defineWorkflow({
+    name: "demo",
+    steps: stepsPipeline(() => [
+      aiGenerateStep({
+        stepKey: "generate",
+        promptKey: "demo:generate",
+        promptFallback: "Write.",
+        paramsSchema,
+        defaults: { enabled: true, params: {} },
+        input: (ctx) => ctx.event.label,
+      }),
+    ]),
+  });
+});
+`);
+
+    expect(result.errors).toEqual([]);
+    expect(result.patterns.length).toBeGreaterThanOrEqual(2);
+    const lines = result.patterns.map((p) => p.source.start.line);
+    expect(lines).toEqual([...lines].sort((a, b) => a - b));
+    expect(result.patterns[0]?.kind).toBe("entity");
+    expect(result.patterns.some((p) => p.kind === "ai.generate")).toBe(true);
+  });
+});
+
 describe("extractHttpRoute", () => {
   test("captures method, path, anonymous, handler", () => {
     const result = parseInline(`
@@ -2368,10 +2588,7 @@ describe("cross-file registrar-wrapper resolution against a real filesystem Proj
 
   test("resolves the imported wrapper and recognises the nav pattern it registers", () => {
     expect(result.errors).toEqual([]);
-    expect(result.patterns).toMatchObject([
-      { kind: "requires", featureNames: ["config"] },
-      { kind: "nav", definition: { id: "foo", label: "Foo" } },
-    ]);
+    expect(result.patterns.map((p) => p.kind)).toEqual(["nav", "requires"]);
   });
 
   test("the resolved pattern's source points at the imported file, not the entry file", () => {

package/src/engine/feature-ast/__tests__/patch.test.ts

@@ -708,3 +708,61 @@ defineFeature("inventory", (r) => {
     ).toThrow(/no call found/);
   });
 });
+describe("ai step patterns — shorthand stepKey (#1491)", () => {
+  const AI_STEP_FIXTURE = `
+import { defineFeature, defineWorkflow, stepsPipeline } from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
+
+const paramsSchema = z.object({});
+const stepKey = "generate";
+
+defineFeature("ai-demo", (r) => {
+  defineWorkflow({
+    name: "demo",
+    steps: stepsPipeline(() => [
+      aiGenerateStep({
+        stepKey,
+        promptKey: "demo:generate",
+        promptFallback: "Write.",
+        paramsSchema,
+        defaults: { enabled: true, params: {} },
+        input: (ctx) => ctx.event.label,
+      }),
+    ]),
+  });
+});
+`;
+
+  test("removePattern finds ai.generate with shorthand stepKey", () => {
+    const sf = makeSourceFile(AI_STEP_FIXTURE);
+    removePattern(sf, { kind: "ai.generate", stepKey: "generate" });
+    const reparsed = parseSourceFile(sf);
+    expect(reparsed.errors).toEqual([]);
+    expect(reparsed.patterns.filter((p) => p.kind.startsWith("ai."))).toEqual([]);
+  });
+
+  test("replacePattern finds ai.generate with shorthand stepKey", () => {
+    const sf = makeSourceFile(AI_STEP_FIXTURE);
+    const replacement: FeaturePattern = {
+      kind: "ai.generate",
+      source: SAMPLE_LOC,
+      stepKey: "generate",
+      promptKey: "demo:generate",
+      promptFallback: "Updated.",
+      defaults: { enabled: true, params: {} },
+      paramsSchemaSource: { ...SAMPLE_LOC, raw: "paramsSchema" },
+      inputBody: { ...SAMPLE_LOC, raw: "(ctx) => ctx.event.label" },
+    };
+    replacePattern(sf, { kind: "ai.generate", stepKey: "generate" }, replacement);
+    const reparsed = parseSourceFile(sf);
+    expect(reparsed.errors).toEqual([]);
+    expect(reparsed.patterns).toContainEqual(
+      expect.objectContaining({
+        kind: "ai.generate",
+        stepKey: "generate",
+        promptFallback: "Updated.",
+      }),
+    );
+    expect(sf.getFullText()).toContain("defineWorkflow");
+  });
+});

package/src/engine/feature-ast/__tests__/render-roundtrip.test.ts

@@ -13,7 +13,7 @@ import * as path from "node:path";
 import { Project, ts } from "ts-morph";
 import { parseSourceFile } from "../parse";
 import type { FeaturePattern } from "../patterns";
-import { renderFeatureFile, renderPattern } from "../render";
+import { indent, renderFeatureFile, renderPattern } from "../render";
 
 const STATIC_FEATURE = `
 import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
@@ -92,6 +92,11 @@ const BODY_LOC_KEYS = new Set([
   "recipientBody",
   "dataBody",
   "defBody",
+  "inputBody",
+  "instructionsBody",
+  "documentBody",
+  "outputSchemaSource",
+  "paramsSchemaSource",
 ]);
 
 function normalizeBodyRaw(raw: string): string {
@@ -815,3 +820,73 @@ describe("render → compiles against the real FeatureRegistrar type — full pa
     expect(renderAndCompile(INTEGRATION_FEATURE)).toEqual([]);
   }, 20_000);
 });
+
+const AI_PIPELINE_FEATURE = `
+import { defineFeature, defineWorkflow, stepsPipeline } from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
+
+const paramsSchema = z.object({ maxTokens: z.number().optional() });
+
+const generateSpec = {
+  stepKey: "generate",
+  promptKey: "demo:generate",
+  promptFallback: "Write a summary.",
+  paramsSchema,
+  defaults: { enabled: true, params: {} },
+  input: (ctx) => ctx.event.label,
+};
+
+defineFeature("ai-demo", (r) => {
+  defineWorkflow({
+    name: "demo",
+    steps: stepsPipeline(() => [
+      aiExtractStep({
+        stepKey: "extract",
+        promptKey: "demo:extract",
+        promptFallback: "Extract fields.",
+        paramsSchema,
+        defaults: { enabled: true, params: {} },
+        outputSchema: z.object({ title: z.string() }),
+        instructions: () => "Extract the title.",
+      }),
+      aiClassifyStep({
+        stepKey: "classify",
+        promptKey: "demo:classify",
+        promptFallback: "Classify the input.",
+        paramsSchema,
+        defaults: { enabled: true, params: {} },
+        actions: [{ type: "approve", description: "Approve" }],
+        input: (ctx) => ctx.event.label,
+      }),
+      aiGenerateStep(generateSpec),
+    ]),
+  });
+});
+`;
+
+describe("render → parse roundtrip — AI pipeline steps", () => {
+  const initial = parse(AI_PIPELINE_FEATURE);
+
+  test("inline + const-ref ai steps round-trip structurally", () => {
+    const aiPatterns = initial.patterns.filter((p) => p.kind.startsWith("ai."));
+    const stepCalls = aiPatterns
+      .map((p) => indent(renderPattern(p), "      ").replace(/;\s*$/, ","))
+      .join("\n");
+    const wrapped = `
+import { defineFeature, defineWorkflow, stepsPipeline } from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
+
+defineFeature("${initial.featureName ?? "ai-demo"}", (r) => {
+  defineWorkflow({
+    name: "demo",
+    trigger: { kind: "event", eventType: "demo.run" },
+    steps: stepsPipeline(() => [
+${stepCalls}
+    ]),
+  });
+});
+`;
+    const reparsed = parse(wrapped);
+    expect(reparsed.patterns.map(stripLocations)).toEqual(aiPatterns.map(stripLocations));
+  });
+});