okengine 0.18.5 → 0.19.0

package/src/compiler/effects-infer.ts

@@ -10,6 +10,8 @@ import type {
   AuthApiKeysResourceRef,
   AuthTenantsResourceRef,
   Effects,
+  EmbedRef,
+  FetchHostRef,
   PromptRef,
   ResourceRef,
   SecretRef,
@@ -53,6 +55,7 @@ export interface InferBinding {
   readonly kind:
     | "store"
     | "signal"
+    | "clock"
     | "prompt"
     | "secret"
     | "template"
@@ -96,7 +99,7 @@ export interface InferredEffects {
    * the flow must opt out of auto-caching.
    */
   readonly cacheIneligible: boolean;
-  /** True when any `fx.ask` was seen (implies nondeterministic). */
+  /** True when any `fx.ask` or `fx.embed` was seen (implies nondeterministic). */
   readonly nondeterministic: boolean;
   /** True when the body references `fx.auth.userId`. */
   readonly readsUserId: boolean;
@@ -112,6 +115,10 @@ const READ_METHODS = new Set([
   "find",
   "list",
   "ttlMs",
+  "count",
+  "page",
+  "search",
+  "raw",
 ]);
 
 const WRITE_METHODS = new Set([
@@ -139,6 +146,9 @@ const TABLE_ARG_METHODS = new Set([
   "upsert",
   "increment",
   "delete",
+  "count",
+  "page",
+  "search",
 ]);
 
 /**
@@ -154,8 +164,10 @@ export function inferEffects(options: InferEffectsOptions): InferredEffects {
   const emits = new Set<SignalRef>();
   const sends = new Set<TemplateRef>();
   const asks = new Set<PromptRef>();
+  const embeds = new Set<EmbedRef>();
   const secrets = new Set<SecretRef>();
   const calls = new Set<FlowRef>();
+  const fetches = new Set<FetchHostRef>();
   const steps: string[] = [];
   let usesRaw = false;
 
@@ -211,6 +223,34 @@ export function inferEffects(options: InferEffectsOptions): InferredEffects {
       continue;
     }
 
+    if (chain.rootMethod === "embed" && call === chain.rootCall) {
+      // fx.embed(model, text) — distinct from fx.ask; never classified as asks.
+      // Prefer model binding; also accept embed-pipeline and string literals.
+      const lit = stringArg(call.arguments[0]);
+      if (lit) {
+        embeds.add(lit);
+      } else {
+        const binding = resolveBinding(call.arguments[0], options.bindings);
+        if (binding && (binding.kind === "embed" || binding.kind === "unknown")) {
+          embeds.add(binding.ref);
+        } else {
+          const name = identifierName(call.arguments[0]);
+          if (name) embeds.add(name);
+        }
+      }
+      continue;
+    }
+
+    if (chain.rootMethod === "fetch" && call === chain.rootCall) {
+      // fx.fetch(url) — host becomes effects.fetches entry.
+      const lit = stringArg(call.arguments[0]);
+      if (lit) {
+        const host = hostFromUrlLiteral(lit);
+        if (host) fetches.add(host);
+      }
+      continue;
+    }
+
     if (chain.rootMethod === "vault" && call === chain.rootCall) {
       // `fx.vault.list()` / `fx.vault.status()` take no path — nothing to
       // declare. Every other method's first argument is the secret.
@@ -289,15 +329,17 @@ export function inferEffects(options: InferEffectsOptions): InferredEffects {
   if (emits.size > 0) effects.emits = sortUnique([...emits]);
   if (sends.size > 0) effects.sends = sortUnique([...sends]);
   if (asks.size > 0) effects.asks = sortUnique([...asks]);
+  if (embeds.size > 0) effects.embeds = sortUnique([...embeds]);
   if (secrets.size > 0) effects.secrets = sortUnique([...secrets]);
   if (calls.size > 0) effects.calls = sortUnique([...calls]);
+  if (fetches.size > 0) effects.fetches = sortUnique([...fetches]);
 
   return {
     effects,
     steps,
     usesRaw,
     cacheIneligible: usesRaw && !options.hasExplicitEffects,
-    nondeterministic: asks.size > 0,
+    nondeterministic: asks.size > 0 || embeds.size > 0,
     readsUserId: containsAuthUserId(options.doNode),
   };
 }
@@ -658,6 +700,20 @@ export function stringArg(node: AstNode | undefined): string | undefined {
   return undefined;
 }
 
+/**
+ * Hostname from a URL string literal for `fx.fetch` inference.
+ *
+ * @param url - Absolute or protocol-relative URL string
+ */
+export function hostFromUrlLiteral(url: string): string | undefined {
+  try {
+    const parsed = new URL(url);
+    return parsed.hostname || undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 /**
  * Identifier name.
  *

package/src/compiler/extract.test.ts

@@ -246,6 +246,133 @@ export const db = store.sql("app", { schema: { notes } });
     });
   });
 
+  test("extracts searchable / embed column meta and table.search engines", async () => {
+    const source = `
+import { store, field, ai } from "okengine";
+
+export const embedder = ai.model("embedder", { provider: "openai-compatible", model: "nomic-embed-text" });
+
+export const articles = store.schema.table("articles", {
+  id: field.text().primaryKey(),
+  title: field.text().searchable({ weight: 2 }).notNull(),
+  body: field.text().searchable().embed({ dims: 8, model: embedder }),
+});
+
+export const db = store.sql("app", { schema: { articles } });
+`;
+    const manifest = await extractFromSources({
+      "src/schema.decl.ts": source,
+    });
+    const table = manifest.stores?.app?.tables?.articles;
+    expect(table?.columns?.title).toMatchObject({
+      searchable: { weight: 2 },
+    });
+    expect(table?.columns?.body).toMatchObject({
+      searchable: { weight: 1 },
+      embed: { dims: 8, model: "embedder" },
+    });
+    expect(table?.search?.engines).toEqual(["bm25", "lsh"]);
+  });
+
+  test("embed without ai element fails SearchConfigError", async () => {
+    const source = `
+import { store, field } from "okengine";
+
+export const articles = store.schema.table("articles", {
+  id: field.text().primaryKey(),
+  body: field.text().searchable().embed({ dims: 8, model: "embedder" }),
+});
+
+export const db = store.sql("app", { schema: { articles } });
+`;
+    await expect(extractFromSources({ "src/schema.decl.ts": source })).rejects.toThrow(
+      /SearchConfigError|ai element/,
+    );
+  });
+
+  test("project search.embed default stamps bare .embed()", async () => {
+    const source = `
+import { store, field, ai, oke } from "okengine";
+
+export const embedder = ai.model("embedder", { provider: "openai-compatible", model: "nomic-embed-text" });
+
+oke({
+  store: {
+    search: {
+      embed: { model: embedder, dims: 768 },
+    },
+  },
+});
+
+export const articles = store.schema.table("articles", {
+  id: field.text().primaryKey(),
+  body: field.text().searchable().embed(),
+});
+
+export const db = store.sql("app", { schema: { articles } });
+`;
+    const manifest = await extractFromSources({
+      "src/schema.decl.ts": source,
+    });
+    expect(manifest.store?.search?.embed).toEqual({ model: "embedder", dims: 768 });
+    expect(manifest.stores?.app?.tables?.articles?.columns?.body).toMatchObject({
+      searchable: { weight: 1 },
+      embed: { model: "embedder", dims: 768 },
+    });
+    expect(manifest.stores?.app?.tables?.articles?.search?.engines).toEqual(["bm25", "lsh"]);
+  });
+
+  test("field .embed() override wins over project search.embed default", async () => {
+    const source = `
+import { store, field, ai, oke } from "okengine";
+
+export const embedder = ai.model("embedder", { provider: "openai-compatible", model: "nomic-embed-text" });
+export const other = ai.model("other", { provider: "openai-compatible", model: "nomic-embed-text" });
+
+oke({
+  store: {
+    search: {
+      embed: { model: embedder, dims: 768 },
+    },
+  },
+});
+
+export const articles = store.schema.table("articles", {
+  id: field.text().primaryKey(),
+  body: field.text().searchable().embed(),
+  caption: field.text().searchable().embed({ model: other }),
+  alt: field.text().searchable().embed({ model: other, dims: 384 }),
+});
+
+export const db = store.sql("app", { schema: { articles } });
+`;
+    const manifest = await extractFromSources({
+      "src/schema.decl.ts": source,
+    });
+    const cols = manifest.stores?.app?.tables?.articles?.columns;
+    expect(cols?.body).toMatchObject({ embed: { model: "embedder", dims: 768 } });
+    expect(cols?.caption).toMatchObject({ embed: { model: "other", dims: 768 } });
+    expect(cols?.alt).toMatchObject({ embed: { model: "other", dims: 384 } });
+  });
+
+  test("bare .embed() without project default fails SearchConfigError", async () => {
+    const source = `
+import { store, field, ai } from "okengine";
+
+export const embedder = ai.model("embedder", { provider: "openai-compatible", model: "nomic-embed-text" });
+
+export const articles = store.schema.table("articles", {
+  id: field.text().primaryKey(),
+  body: field.text().searchable().embed(),
+});
+
+export const db = store.sql("app", { schema: { articles } });
+`;
+    await expect(extractFromSources({ "src/schema.decl.ts": source })).rejects.toThrow(
+      /SearchConfigError|model and dims|store: \{ search: \{ embed/,
+    );
+  });
+
   test("extracts RLS helpers onto store.tables", async () => {
     const source = `
 import { store, field } from "okengine";
@@ -349,6 +476,69 @@ export const db = store.sql("app", { schema: { assets } });
     expect(cols?.createdAt).toMatchObject({ type: "integer", nullable: false, default: null });
   });
 
+  test("field.id() / field.okid() heads extract as text PK with dynamic default", async () => {
+    const source = `
+import { store, field } from "okengine";
+
+export const tasks = store.schema.table("tasks", {
+  id: field.id().primaryKey(),
+  title: field.text().notNull(),
+  updatedAt: field.timestamp().notNull().now(),
+});
+
+export const assets = store.schema.table("assets", {
+  id: field.okid().primaryKey(),
+  name: field.text().notNull(),
+});
+
+export const db = store.sql("app", { schema: { tasks, assets } });
+`;
+    const manifest = await extractFromSources({
+      "src/schema.decl.ts": source,
+    });
+    expect(manifest.stores?.app?.tables?.tasks?.columns?.id).toMatchObject({
+      type: "text",
+      primaryKey: true,
+      default: null,
+      sqlName: "id",
+    });
+    expect(manifest.stores?.app?.tables?.assets?.columns?.id).toMatchObject({
+      type: "text",
+      primaryKey: true,
+      default: null,
+    });
+  });
+
+  test("live(.live(table)) accepts field.id().primaryKey() tables", async () => {
+    const source = `
+import { on, flow, http, gate, store, field } from "okengine";
+
+export const tasks = store.schema.table("tasks", {
+  id: field.id().primaryKey(),
+  status: field.text().notNull(),
+  updatedAt: field.timestamp().notNull().now(),
+});
+
+export const db = store.sql("app", { schema: { tasks } });
+export const member = gate.policy("member", { require: ["member"] });
+
+export const live = on(
+  http.get("/tasks/live").gate(member).live(tasks),
+  flow("tasks.live", {
+    do: async () => ({ ok: true }),
+  }),
+);
+`;
+    const manifest = await extractFromSources({
+      "src/schema.decl.ts": source,
+      "src/flows/live.ts": source,
+    });
+    expect(manifest.flows?.["tasks.live"]).toBeDefined();
+    expect(manifest.stores?.app?.tables?.tasks?.columns?.id).toMatchObject({
+      primaryKey: true,
+    });
+  });
+
   test("decimal head collapses to numeric in the manifest", async () => {
     const source = `
 import { store, field } from "okengine";
@@ -389,10 +579,7 @@ export const embeddings = store.index("embeddings", {
 
 export const sessions = store.kv("sessions", { description: "Session cache" });
 
-export const orderPlaced = signal("order-placed", {
-  delivery: "once",
-  description: "Order placed event",
-});
+export const orderPlaced = signal.once("order-placed", { description: "Order placed event" });
 
 export const bookingConfirmed = channel.template("booking-confirmed", {
   medium: "email",
@@ -438,11 +625,8 @@ export const stripeKey = vault.secret("STRIPE_KEY", {
     const manifest = await extractFromSources({
       "src/signals.ts": `
 import { signal } from "okengine";
-export const orderStatus = signal("order-status", {
-  delivery: "live",
-  optional: true,
-  retention: { maxAge: "24h", maxCount: 500 },
-});
+export const orderStatus = signal.live("order-status", { optional: true,
+  retention: { maxAge: "24h", maxCount: 500 } });
 `,
     });
     expect(manifest.signals?.["order-status"]?.retention).toEqual({
@@ -802,9 +986,8 @@ export const tasksTable = store.schema.table(
 );
 
 export const tasksLive = on(
-  http.get("/tasks/live").gate(member).live(tasksTable),
+  http.get("/tasks/live", { in: { unknown: true } }).gate(member).live(tasksTable),
   flow("tasks.live", {
-    in: { unknown: true },
     do: async (_input, fx) => liveQuery(fx, tasksTable, _input),
   }),
 );
@@ -948,12 +1131,13 @@ export const attach = on(
 
   test("fx.store(files).list(...) infers a read, unannotated", async () => {
     const source = `
-import { on, flow, every, store } from "okengine";
+import { on, flow, clock, store } from "okengine";
 
 export const files = store.files("uploads");
+export const sweepClock = clock("notes.sweep", { every: "1d" });
 
 export const sweep = on(
-  every("1d"),
+  sweepClock,
   flow("notes.sweep", {
     do: async (_input, fx) => {
       const keys = await fx.store(files).list();
@@ -968,16 +1152,49 @@ export const sweep = on(
   });
 });
 
+describe("extractManifest — clock convenience helpers", () => {
+  test("daily / cron fields / every compile into clocks", async () => {
+    const source = `
+import { clock } from "okengine";
+
+export const daily = clock.daily("reports.daily", { at: "06:00", description: "Morning" });
+export const sweep = clock.cron("ops.sweep", {
+  minute: "*/15",
+  hour: [9, 12, 17],
+  dayOfWeek: "1-5",
+  overridable: true,
+});
+export const ping = clock.every("health.ping", "30s");
+export const nick = clock.cron("metrics.hourly", "@hourly");
+export const weekly = clock.weekly("digest", { on: ["mon", "fri"], at: "09:00" });
+`;
+    const manifest = await extractFromSources({ "src/clocks.ts": source });
+
+    expect(manifest.clocks?.["reports.daily"]).toMatchObject({
+      cron: "0 6 * * *",
+      description: "Morning",
+    });
+    expect(manifest.clocks?.["ops.sweep"]).toMatchObject({
+      cron: "*/15 9,12,17 * * 1-5",
+      overridable: true,
+    });
+    expect(manifest.clocks?.["health.ping"]).toMatchObject({ every: "30s" });
+    expect(manifest.clocks?.["metrics.hourly"]).toMatchObject({ cron: "@hourly" });
+    expect(manifest.clocks?.digest).toMatchObject({ cron: "0 9 * * 1,5" });
+  });
+});
+
 describe("extractManifest — kv key methods", () => {
   test("fx.store(kv).delete(key) writes kv:<namespace>, not kv:<identifier>", async () => {
     const source = `
-import { on, flow, every, store, signal } from "okengine";
+import { on, flow, clock, store, signal } from "okengine";
 
 export const draftsKv = store.kv("drafts");
-export const draftExpired = signal("draft-expired", { delivery: "broadcast", retries: 0, deadLetter: false });
+export const draftExpired = signal.broadcast("draft-expired", { retries: 0, deadLetter: false });
+export const expireClock = clock("drafts.expire", { every: "10m" });
 
 export const expire = on(
-  every("10m"),
+  expireClock,
   flow("drafts.expire", {
     do: async (_input, fx) => {
       const keys = await fx.store(draftsKv).list();
@@ -1005,7 +1222,7 @@ describe("extractManifest — fx.deadLetters", () => {
     const source = `
 import { on, flow, http, signal } from "okengine";
 
-export const notify = signal("notify", { delivery: "once" });
+export const notify = signal.once("notify");
 
 export const failed = on(
   http.get("/notifications/failed").public(),
@@ -1026,9 +1243,7 @@ import { on, http, gate, signal } from "okengine";
 import { z } from "zod";
 
 export const member = gate.policy("member", ({ auth }) => !!auth.verified);
-export const orderStatus = signal("order-status", {
-  delivery: "live",
-  optional: true,
+export const orderStatus = signal.live("order-status", { optional: true,
   schema: z.object({ orderId: z.string(), status: z.string() }),
 });
 
@@ -1049,7 +1264,7 @@ export const events = on(http.get("/orders/:orderId/events").gate(member).live(o
 import { on, http, gate, signal } from "okengine";
 
 export const member = gate.policy("member", ({ auth }) => !!auth.verified);
-export const orderStatus = signal("order-status", { delivery: "live", optional: true });
+export const orderStatus = signal.live("order-status", { optional: true });
 
 export const firehose = on(http.live(orderStatus).gate(member));
 `;
@@ -1065,7 +1280,7 @@ export const firehose = on(http.live(orderStatus).gate(member));
     const source = `
 import { on, flow, http, signal } from "okengine";
 
-export const orderStatus = signal("order-status", { delivery: "live", optional: true });
+export const orderStatus = signal.live("order-status", { optional: true });
 
 export const events = on(
   http.get("/feed").public().live(orderStatus),
@@ -1130,12 +1345,12 @@ export const send = on(
   });
 });
 
-describe("extractManifest — flow(name, options) positional signature", () => {
-  test("bare flow(name, {...}) extracts name, in, out, effects", async () => {
+describe("extractManifest — call(name, options) invoke contract", () => {
+  test("bare call(name, {...}) extracts name, in, out, effects", async () => {
     const source = `
-import { flow } from "okengine";
+import { call } from "okengine";
 
-export const chargeOrder = flow("checkout.chargeOrder", {
+export const chargeOrder = call("checkout.chargeOrder", {
   in: ChargeIn,
   out: ChargeOut,
   effects: { reads: ["sql:orders"], writes: ["sql:orders"] },
@@ -1153,14 +1368,13 @@ export const chargeOrder = flow("checkout.chargeOrder", {
     expect(manifest.flows?.["checkout.chargeOrder"]?.effects?.writes).toEqual(["sql:orders"]);
   });
 
-  test("on(trigger, flow(name, {...})) extracts the same shape as bare flow()", async () => {
+  test("on(trigger, flow(name, {...})) extracts HTTP contract from the trigger", async () => {
     const source = `
 import { on, http, flow } from "okengine";
 
 export const getOrder = on(
-  http.get("/orders/:id"),
+  http.get("/orders/:id", { out: OrderOut }),
   flow("checkout.getOrder", {
-    out: OrderOut,
     effects: { reads: ["sql:orders"] },
     do: async (input, fx) => {
       return { id: input.id };
@@ -1338,7 +1552,7 @@ export const ping = flow({ do: () => ({ ok: true }) });
 import { on, flow, http, store, signal } from "okengine";
 export const db = store.sql("db");
 export const notes = { name: "notes" };
-export const noteCreated = signal("note-created");
+export const noteCreated = signal.once("note-created");
 export const get = on(
   http.get("/notes/:id").public(),
   flow("notes.get", {
@@ -1350,7 +1564,7 @@ export const get = on(
 import { on, flow, http, store, signal } from "okengine";
 export const db = store.sql("db");
 export const notes = { name: "notes" };
-export const noteCreated = signal("note-created");
+export const noteCreated = signal.once("note-created");
 export const get = on(
   http.get().public(),
   flow({
@@ -1372,10 +1586,10 @@ export const get = on(
   });
 });
 
-describe("extractManifest — flow in/out schema expansion", () => {
+describe("extractManifest — invoke contract schema expansion", () => {
   test("expands z.object identifiers into JSON Schema fields", async () => {
     const source = `
-import { flow } from "okengine";
+import { call } from "okengine";
 import { z } from "zod";
 
 export const TaskCreateIn = z.object({
@@ -1389,7 +1603,7 @@ export const TaskCreateOut = z.object({
   identifier: z.string(),
 });
 
-export const create = flow("tasks.create", {
+export const create = call("tasks.create", {
   in: TaskCreateIn,
   out: TaskCreateOut,
   do: async () => ({ id: "1", identifier: "ENG-1" }),
@@ -1428,7 +1642,7 @@ export const users = store.schema.table("users", {
 });
 `;
     const flows = `
-import { flow } from "okengine";
+import { call } from "okengine";
 import { createInsertSchema, createSelectSchema, createUpdateSchema } from "drizzle-orm/zod";
 import { users } from "../schema.decl.ts";
 
@@ -1436,13 +1650,13 @@ export const userSelect = createSelectSchema(users);
 export const userInsert = createInsertSchema(users);
 export const userUpdate = createUpdateSchema(users);
 
-export const create = flow("users.create", {
+export const create = call("users.create", {
   in: userInsert,
   out: userSelect,
   do: async () => ({}),
 });
 
-export const patch = flow("users.patch", {
+export const patch = call("users.patch", {
   in: userUpdate,
   do: async () => ({}),
 });
@@ -1503,8 +1717,8 @@ export function tableZod(table) {
 export const spacesZod = tableZod(spaces);
 `;
     const flows = `
-import { flow } from "okengine";
-export const create = flow("spaces.create", {
+import { call } from "okengine";
+export const create = call("spaces.create", {
   in: spacesZod.insert,
   out: spacesZod.select.pick({ id: true, key: true }),
   do: async () => ({}),
@@ -1580,19 +1794,19 @@ export const { list, create, get, update, remove } = bindCrud({
 
   test("same-named createIn stays file-local (does not leak across units)", async () => {
     const spaces = `
-import { flow } from "okengine";
+import { call } from "okengine";
 import { z } from "zod";
 const createIn = z.object({ key: z.string(), name: z.string() });
-export const create = flow("spaces.create", {
+export const create = call("spaces.create", {
   in: createIn,
   do: async () => ({}),
 });
 `;
     const views = `
-import { flow } from "okengine";
+import { call } from "okengine";
 import { z } from "zod";
 const createIn = z.object({ kind: z.enum(["list", "board"]) });
-export const create = flow("views.create", {
+export const create = call("views.create", {
   in: createIn,
   do: async () => ({}),
 });