okengine 0.18.4 → 0.19.0

package/src/compiler/extract.ts

@@ -8,6 +8,14 @@
 
 import { parseSync } from "oxc-parser";
 
+import {
+  AI_NATIVE_DRIVER_IDS,
+  formatAiProviderTier2Warn,
+  getAiProviderEntry,
+} from "../elements/ai/providers.ts";
+import { buildCronExpression, type CronField } from "../elements/clock/cron-fields.ts";
+import { SearchConfigError } from "../elements/store/search-errors.ts";
+
 import type {
   Ai,
   AiAgent,
@@ -230,7 +238,21 @@ export async function extractManifest(options: ExtractManifestOptions = {}): Pro
   if (Object.keys(journeys).length > 0) manifest.journeys = journeys;
   if (Object.keys(drivers).length > 0) manifest.drivers = drivers;
   if (scope.tenancy) manifest.tenancy = scope.tenancy;
-  if (scope.store && scope.store.live === true) manifest.store = { live: true };
+  if (scope.store) {
+    const storeManifest: NonNullable<Manifest["store"]> = {};
+    if (scope.store.live === true) storeManifest.live = true;
+    if (scope.store.search?.embed) {
+      storeManifest.search = {
+        embed: {
+          model: scope.store.search.embed.model,
+          dims: scope.store.search.embed.dims,
+        },
+      };
+    }
+    if (storeManifest.live === true || storeManifest.search?.embed) {
+      manifest.store = storeManifest;
+    }
+  }
   if (scope.i18n) manifest.i18n = scope.i18n;
   if (scope.topology) manifest.topology = scope.topology;
   if (scope.images) manifest.images = scope.images;
@@ -238,6 +260,8 @@ export async function extractManifest(options: ExtractManifestOptions = {}): Pro
   applyTenancyDefaults(manifest);
   assertTenantSafeSchema(manifest);
   applyLiveDefaults(manifest, scope);
+  resolveSearchEmbedDefaults(manifest);
+  assertSearchConfig(manifest);
 
   return manifest;
 }
@@ -295,6 +319,7 @@ function collectDeclarations(filePath: string, program: AstNode, scope: ProjectS
     if (name) scope.app = name;
     applyOkeTenantConfig(opts, scope);
     applyOkeStoreLiveConfig(opts, scope);
+    applyOkeStoreSearchConfig(opts, scope);
   });
 }
 
@@ -495,16 +520,35 @@ function tableFromDeclared(t: DeclaredSchemaTable): {
   policies?: Record<string, TablePolicy>;
   tenantScoped?: boolean;
   live?: boolean;
+  search?: { engines: Array<"bm25" | "lsh"> };
 } {
+  const engines = searchEnginesFromColumns(t.columns);
   return {
     columns: t.columns,
     ...(t.rls ? { rls: true } : {}),
     ...(t.policies ? { policies: t.policies } : {}),
     ...(t.tenantScoped === false ? { tenantScoped: false } : {}),
     ...(t.live === false ? { live: false } : {}),
+    ...(engines ? { search: { engines } } : {}),
   };
 }
 
+function searchEnginesFromColumns(
+  columns: Record<string, DeclaredColumn>,
+): Array<"bm25" | "lsh"> | undefined {
+  let bm25 = false;
+  let lsh = false;
+  for (const col of Object.values(columns)) {
+    if (col.searchable) bm25 = true;
+    if (col.embed) lsh = true;
+  }
+  if (!bm25 && !lsh) return undefined;
+  const engines: Array<"bm25" | "lsh"> = [];
+  if (bm25) engines.push("bm25");
+  if (lsh) engines.push("lsh");
+  return engines;
+}
+
 function parseSchemaTableExtras(
   node: AstNode | undefined,
 ): Pick<DeclaredSchemaTable, "rls" | "policies" | "tenantScoped" | "live"> {
@@ -678,11 +722,19 @@ const FIELD_SQL_TYPES: ReadonlySet<string> = new Set([
   "cidr",
   "macaddr",
   "macaddr8",
+  // Prepared text-id factories (`field.id()` / `field.okid()` ≡ text + defaultFn).
+  "id",
+  "okid",
 ]);
 
+/** Prepared text-id heads that imply a dynamic default (same as `.okid()` / `.defaultFn(id)`). */
+const FIELD_ID_HEADS: ReadonlySet<string> = new Set(["id", "okid"]);
+
 /** Manifest primitive for a field head (`decimal` collapses into `numeric`). */
 function manifestFieldType(head: string): DeclaredColumn["type"] {
-  return head === "decimal" ? "numeric" : (head as DeclaredColumn["type"]);
+  if (head === "decimal") return "numeric";
+  if (FIELD_ID_HEADS.has(head)) return "text";
+  return head as DeclaredColumn["type"];
 }
 
 /**
@@ -719,7 +771,7 @@ function parseFieldChain(node: AstNode, key: string): DeclaredColumn | undefined
         if (method === "describe") {
           description = stringArg(call.arguments[0]) ?? description;
         }
-        if (method === "defaultFn" || method === "okid" || method === "now") {
+        if (method === "defaultFn" || method === "okid" || method === "now" || method === "id") {
           hasDefault = true;
           defaultValue = defaultValue ?? null;
         }
@@ -755,11 +807,17 @@ function parseFieldChain(node: AstNode, key: string): DeclaredColumn | undefined
     const member = cur as AstNode & { object: AstNode; property: AstNode };
     if (identifierName(member.object) === "field") {
       const t = identifierName(member.property);
-      if (t && FIELD_SQL_TYPES.has(t)) sqlType = manifestFieldType(t);
+      if (t && FIELD_SQL_TYPES.has(t)) {
+        sqlType = manifestFieldType(t);
+        if (FIELD_ID_HEADS.has(t)) {
+          hasDefault = true;
+          defaultValue = defaultValue ?? null;
+        }
+      }
     }
   }
 
-  // Also: field.text() ends as CallExpression with callee MemberExpression field.text
+  // Also: field.text() / field.id() ends as CallExpression with callee MemberExpression
   if (!sqlType && node.type === "CallExpression") {
     let probe: AstNode | undefined = node;
     while (probe && probe.type === "CallExpression") {
@@ -770,6 +828,10 @@ function parseFieldChain(node: AstNode, key: string): DeclaredColumn | undefined
         const head = identifierName(member.property);
         if (identifierName(member.object) === "field" && head && FIELD_SQL_TYPES.has(head)) {
           sqlType = manifestFieldType(head);
+          if (FIELD_ID_HEADS.has(head)) {
+            hasDefault = true;
+            defaultValue = defaultValue ?? null;
+          }
           const arg0 = call.arguments[0];
           if (arg0?.type === "ObjectExpression") optionsNode = arg0;
           break;
@@ -796,6 +858,86 @@ function parseFieldChain(node: AstNode, key: string): DeclaredColumn | undefined
     ...(methods.has("sensitive") ? { sensitive: true } : {}),
     ...parseFieldOptions(optionsNode),
   };
+  if (methods.has("searchable")) {
+    let weight = 1;
+    let probe: AstNode | undefined = node;
+    while (probe && probe.type === "CallExpression") {
+      const call = probe as CallExpression;
+      const callee = call.callee;
+      if (callee.type === "MemberExpression") {
+        const member = callee as AstNode & { object: AstNode; property: AstNode };
+        if (identifierName(member.property) === "searchable") {
+          const arg0 = call.arguments[0];
+          if (arg0?.type === "ObjectExpression") {
+            const w = numberProp(arg0, "weight");
+            if (w !== undefined) weight = w;
+          }
+          break;
+        }
+        probe = member.object;
+        continue;
+      }
+      break;
+    }
+    col.searchable = { weight };
+  }
+  if (methods.has("embed")) {
+    if (!methods.has("searchable")) {
+      throw new Error(
+        `extract: .embed() on column "${key}" requires a prior .searchable() — weight is free SQL math; embed is an async AI pipeline`,
+      );
+    }
+    let dims: number | undefined;
+    let model: string | undefined;
+    let probe: AstNode | undefined = node;
+    while (probe && probe.type === "CallExpression") {
+      const call = probe as CallExpression;
+      const callee = call.callee;
+      if (callee.type === "MemberExpression") {
+        const member = callee as AstNode & { object: AstNode; property: AstNode };
+        if (identifierName(member.property) === "embed") {
+          const arg0 = call.arguments[0];
+          if (arg0?.type === "ObjectExpression") {
+            const d = numberProp(arg0, "dims");
+            if (d !== undefined) dims = d;
+            const modelNode = objectProp(arg0, "model");
+            if (modelNode) {
+              const lit = stringArg(modelNode);
+              if (lit) model = lit;
+              else {
+                const bindingName = identifierName(modelNode);
+                if (bindingName) model = bindingName;
+                else if (modelNode.type === "MemberExpression") {
+                  const m = modelNode as AstNode & { property: AstNode };
+                  const prop = identifierName(m.property);
+                  if (prop === "name") {
+                    const obj = (modelNode as AstNode & { object: AstNode }).object;
+                    model = identifierName(obj) ?? model;
+                  }
+                }
+              }
+            }
+          }
+          break;
+        }
+        probe = member.object;
+        continue;
+      }
+      break;
+    }
+    if (dims !== undefined && !(Number.isInteger(dims) && dims > 0)) {
+      throw new Error(
+        `extract: .embed() on column "${key}" has invalid dims (need positive integer)`,
+      );
+    }
+    // Stamp partial embed; resolveSearchEmbedDefaults fills model/dims from
+    // oke({ store: { search: { embed } } }) before assertSearchConfig.
+    // Cast: Manifest DeclaredColumn requires concrete dims after resolution.
+    (col as { embed?: { model?: string; dims?: number } }).embed = {
+      ...(dims !== undefined ? { dims } : {}),
+      ...(model !== undefined ? { model } : {}),
+    };
+  }
   if (methods.has("retain")) {
     // retain("7y") — find the call in the original chain by re-walk
     let probe: AstNode | undefined = node;
@@ -1013,7 +1155,7 @@ function visitDeclarationCall(call: CallExpression, program: AstNode, scope: Pro
       const name = stringArg(call.arguments[0]);
       const opts = objectArg(call.arguments[1]);
       if (name) {
-        scope.clocks[name] = {
+        recordClockDecl(scope, program, call, name, {
           ...(stringProp(opts, "every") ? { every: stringProp(opts, "every") } : {}),
           ...(stringProp(opts, "cron") ? { cron: stringProp(opts, "cron") } : {}),
           ...(boolProp(opts, "overridable") !== undefined
@@ -1023,7 +1165,61 @@ function visitDeclarationCall(call: CallExpression, program: AstNode, scope: Pro
             ? { description: stringProp(opts, "description") }
             : {}),
           perTenant: true,
-        };
+        });
+      }
+    }
+
+    // clock.every("name", "30s", opts?)
+    if (obj === "clock" && prop === "every") {
+      const name = stringArg(call.arguments[0]);
+      const duration = stringArg(call.arguments[1]);
+      const opts = objectArg(call.arguments[2]);
+      if (name && duration) {
+        recordClockDecl(scope, program, call, name, {
+          every: duration,
+          ...clockHelperOptsFromAst(opts),
+        });
+      }
+    }
+
+    // clock.cron("name", "0 6 * * *" | fields, opts?)
+    if (obj === "clock" && prop === "cron") {
+      const name = stringArg(call.arguments[0]);
+      if (name) {
+        const expr = stringArg(call.arguments[1]);
+        const fieldsObj = objectArg(call.arguments[1]);
+        if (expr) {
+          recordClockDecl(scope, program, call, name, {
+            cron: expr,
+            ...clockHelperOptsFromAst(objectArg(call.arguments[2])),
+          });
+        } else if (fieldsObj) {
+          const built = cronExpressionFromFieldsAst(fieldsObj);
+          if (built) {
+            recordClockDecl(scope, program, call, name, {
+              cron: built,
+              ...clockHelperOptsFromAst(fieldsObj),
+            });
+          }
+        }
+      }
+    }
+
+    // clock.daily / hourly / weekly / monthly
+    if (
+      obj === "clock" &&
+      (prop === "daily" || prop === "hourly" || prop === "weekly" || prop === "monthly")
+    ) {
+      const name = stringArg(call.arguments[0]);
+      const opts = objectArg(call.arguments[1]);
+      if (name) {
+        const cron = cronFromPresetHelper(prop, opts);
+        if (cron) {
+          recordClockDecl(scope, program, call, name, {
+            cron,
+            ...clockHelperOptsFromAst(opts),
+          });
+        }
       }
     }
 
@@ -1143,13 +1339,23 @@ function visitDeclarationCall(call: CallExpression, program: AstNode, scope: Pro
       const modelName = stringArg(call.arguments[0]);
       const opts = objectArg(call.arguments[1]);
       if (modelName) {
+        const provider = stringProp(opts, "provider");
+        const driverId = stringProp(opts, "driverId");
+        const baseUrl = stringProp(opts, "baseUrl");
         const model: AiModel = {
-          ...(stringProp(opts, "provider") ? { provider: stringProp(opts, "provider") } : {}),
+          ...(provider ? { provider } : {}),
           ...(stringProp(opts, "tier") ? { tier: stringProp(opts, "tier") } : {}),
-          ...(stringProp(opts, "driverId") ? { driverId: stringProp(opts, "driverId") } : {}),
+          ...(driverId ? { driverId } : {}),
         };
         scope.ai.models = scope.ai.models ?? {};
         scope.ai.models[modelName] = model;
+        // Limited OpenAI-compat caveat — same honesty as declare-time warn.
+        if (provider && !baseUrl && !(driverId && AI_NATIVE_DRIVER_IDS.has(driverId))) {
+          const entry = getAiProviderEntry(provider);
+          if (entry?.tier === 2 && entry.caveat) {
+            console.warn(formatAiProviderTier2Warn(provider, entry.caveat, "[oke extract] warn"));
+          }
+        }
         const bindingName = enclosingConstName(call, program);
         if (bindingName) {
           scope.bindings.set(bindingName, {
@@ -1265,15 +1471,13 @@ function visitDeclarationCall(call: CallExpression, program: AstNode, scope: Pro
         }
       }
     }
-  }
 
-  // signal("name", { delivery, … })
-  if (identifierName(callee) === "signal") {
-    const signalName = stringArg(call.arguments[0]);
-    const opts = objectArg(call.arguments[1]);
-    if (signalName) {
-      const delivery = stringProp(opts, "delivery") as SignalDelivery | undefined;
-      if (delivery) {
+    // signal.once("name", opts?) / .broadcast / .live
+    if (obj === "signal" && (prop === "once" || prop === "broadcast" || prop === "live")) {
+      const signalName = stringArg(call.arguments[0]);
+      const opts = objectArg(call.arguments[1]);
+      if (signalName) {
+        const delivery = prop as SignalDelivery;
         const retentionObj = objectProp(opts, "retention");
         const maxAge = retentionObj ? stringProp(retentionObj, "maxAge") : undefined;
         const maxCount = retentionObj ? numberProp(retentionObj, "maxCount") : undefined;
@@ -1314,7 +1518,7 @@ function visitDeclarationCall(call: CallExpression, program: AstNode, scope: Pro
     const name = stringArg(call.arguments[0]);
     const opts = objectArg(call.arguments[1]);
     if (name && opts) {
-      scope.clocks[name] = {
+      recordClockDecl(scope, program, call, name, {
         ...(stringProp(opts, "every") ? { every: stringProp(opts, "every") } : {}),
         ...(stringProp(opts, "cron") ? { cron: stringProp(opts, "cron") } : {}),
         ...(boolProp(opts, "overridable") !== undefined
@@ -1324,7 +1528,7 @@ function visitDeclarationCall(call: CallExpression, program: AstNode, scope: Pro
           ? { description: stringProp(opts, "description") }
           : {}),
         ...(boolProp(opts, "perTenant") === true ? { perTenant: true } : {}),
-      };
+      });
     }
   }
 
@@ -1582,8 +1786,8 @@ function collectFlows(file: SourceFile, program: AstNode, scope: ProjectScope):
       return;
     }
 
-    if (callee === "flow") {
-      // Bare flow — skip when this call is the second arg of an on().
+    if (callee === "flow" || callee === "call") {
+      // Bare flow / call — skip when this call is the second arg of an on().
       if (isOnFlowArgument(call, program)) return;
       const exportName = enclosingConstName(call, program);
       registerFlow({
@@ -1621,12 +1825,9 @@ function isOnFlowArgument(flowCall: CallExpression, program: AstNode): boolean {
 }
 
 function unwrapFlowCall(node: AstNode): CallExpression | undefined {
-  if (
-    node.type === "CallExpression" &&
-    identifierName((node as CallExpression).callee) === "flow"
-  ) {
-    return node as CallExpression;
-  }
+  if (node.type !== "CallExpression") return undefined;
+  const name = identifierName((node as CallExpression).callee);
+  if (name === "flow" || name === "call") return node as CallExpression;
   return undefined;
 }
 
@@ -1709,12 +1910,17 @@ function registerFlow(args: {
   }
   if (gates && gates.length > 0) flow.gates = gates;
 
-  const inSchema = schemaProp(opts, "in", args.scope, args.file.path);
+  const inSchema =
+    schemaProp(opts, "in", args.scope, args.file.path) ??
+    exposureSchemaProp(trigger?.contract, "in", args.scope, args.file.path);
   if (inSchema !== undefined) flow.in = inSchema;
-  const outSchema = schemaProp(opts, "out", args.scope, args.file.path);
+  const outSchema =
+    schemaProp(opts, "out", args.scope, args.file.path) ??
+    exposureSchemaProp(trigger?.contract, "out", args.scope, args.file.path);
   if (outSchema !== undefined) flow.out = outSchema;
 
-  const errors = parseErrors(objectProp(opts, "errors"));
+  const errors =
+    parseErrors(objectProp(opts, "errors")) ?? parseErrors(objectProp(trigger?.contract, "errors"));
   if (errors) flow.errors = errors;
 
   if (effects) flow.effects = effects;
@@ -1738,7 +1944,7 @@ function registerFlow(args: {
       };
     }
   }
-  if (boolProp(opts, "breaking")) flow.breaking = true;
+  if (boolProp(opts, "breaking") || boolProp(trigger?.contract, "breaking")) flow.breaking = true;
 
   const slo = parseSlo(objectProp(opts, "slo"));
   if (slo) flow.slo = slo;
@@ -2146,6 +2352,8 @@ interface ParsedTrigger {
   live?: string;
   /** Physical table name when `.live(tableBinding)` — manual live surface. */
   liveTable?: string;
+  /** Invoke contract bag authored on `http.*` / `mcp.tool`. */
+  contract?: AstNode;
 }
 
 function parseTrigger(
@@ -2153,13 +2361,22 @@ function parseTrigger(
   scope: ProjectScope,
   filePath?: string,
 ): ParsedTrigger | undefined {
-  // every("10m")
   if (node.type === "CallExpression") {
     const call = node as CallExpression;
     const name = identifierName(call.callee);
-    if (name === "every") {
-      const interval = stringArg(call.arguments[0]);
-      if (interval) return { trigger: { every: interval } };
+    if (name === "clock") {
+      const clockName = stringArg(call.arguments[0]);
+      const opts = objectArg(call.arguments[1]);
+      const cron = stringProp(opts, "cron");
+      const every = stringProp(opts, "every");
+      if (cron) return { trigger: { cron } };
+      if (every) return { trigger: { every } };
+      if (clockName) {
+        const clockDef = scope.clocks[clockName];
+        if (clockDef?.cron) return { trigger: { cron: clockDef.cron } };
+        if (clockDef?.every) return { trigger: { every: clockDef.every } };
+        return { trigger: { cron: clockName } };
+      }
     }
     if (name === "internal") {
       return { trigger: {} };
@@ -2173,8 +2390,8 @@ function parseTrigger(
     const http = parseHttpTrigger(call, scope, filePath);
     if (http) return http;
 
-    // table("orders").changed("status") / db.table(orders).changed(...)
-    const cdc = parseCdcTrigger(call);
+    // db.table(orders).changed(...) / <storeName>.table(orders).changed(...)
+    const cdc = parseCdcTrigger(call, scope);
     if (cdc) return { trigger: { cdc } };
 
     // on(signalHandle, …) — Identifier referring to a signal binding
@@ -2191,6 +2408,18 @@ function parseTrigger(
     const id = (node as Identifier).name;
     if (id === "internal") return { trigger: {} };
     const binding = scope.bindings.get(id);
+    if (binding?.kind === "clock") {
+      const clockDef = scope.clocks[binding.ref];
+      if (clockDef?.cron) return { trigger: { cron: clockDef.cron } };
+      if (clockDef?.every) return { trigger: { every: clockDef.every } };
+      return { trigger: { cron: binding.ref } };
+    }
+    if (scope.clocks[id]) {
+      const clockDef = scope.clocks[id];
+      if (clockDef?.cron) return { trigger: { cron: clockDef.cron } };
+      if (clockDef?.every) return { trigger: { every: clockDef.every } };
+      return { trigger: { cron: id } };
+    }
     if (binding?.kind === "signal") {
       return { trigger: { signal: binding.ref } };
     }
@@ -2237,6 +2466,7 @@ function parseHttpTrigger(
   let live: string | undefined;
   /** Table name when `.live(tableBinding)` — a manual live query surface. */
   let liveTable: string | undefined;
+  let contract: AstNode | undefined;
   const gateNames: string[] = [];
 
   for (const node of chain) {
@@ -2269,7 +2499,14 @@ function parseHttpTrigger(
           continue;
         }
         method = prop.toUpperCase();
-        path = stringArg(c.arguments[0]);
+        const pathArg = c.arguments[0];
+        const contractArg = c.arguments[1];
+        if (stringArg(pathArg) !== undefined) {
+          path = stringArg(pathArg);
+          if (isBoundaryContractObject(contractArg)) contract = contractArg;
+        } else if (isBoundaryContractObject(pathArg)) {
+          contract = pathArg;
+        }
         continue;
       }
 
@@ -2323,10 +2560,11 @@ function parseHttpTrigger(
     gates: gateNames.length > 0 ? gateNames : undefined,
     ...(live !== undefined ? { live } : {}),
     ...(liveTable !== undefined ? { liveTable } : {}),
+    ...(contract !== undefined ? { contract } : {}),
   };
 }
 
-function parseCdcTrigger(call: CallExpression): Trigger["cdc"] | undefined {
+function parseCdcTrigger(call: CallExpression, scope?: ProjectScope): Trigger["cdc"] | undefined {
   // *.changed("col") or *.changed()
   const callee = call.callee;
   if (callee.type !== "MemberExpression") return undefined;
@@ -2334,21 +2572,22 @@ function parseCdcTrigger(call: CallExpression): Trigger["cdc"] | undefined {
   if (identifierName(member.property) !== "changed") return undefined;
 
   const column = stringArg(call.arguments[0]);
-  // object is table("orders") or db.table(orders) or table(orders)
+  // object is db.table(orders) or <storeName>.table(orders)
   const obj = member.object;
   if (obj.type === "CallExpression") {
     const inner = obj as CallExpression;
     const innerCallee = inner.callee;
-    if (identifierName(innerCallee) === "table") {
-      const tableName = stringArg(inner.arguments[0]) ?? identifierName(inner.arguments[0]);
-      if (!tableName) return undefined;
-      return column ? { table: tableName, column } : { table: tableName };
-    }
     if (
       innerCallee.type === "MemberExpression" &&
       identifierName((innerCallee as AstNode & { property: AstNode }).property) === "table"
     ) {
-      const tableName = stringArg(inner.arguments[0]) ?? identifierName(inner.arguments[0]);
+      const argId = identifierName(inner.arguments[0]);
+      const resolvedName = argId
+        ? scope?.bindings.get(argId)?.kind === "table"
+          ? scope.bindings.get(argId)?.ref
+          : argId
+        : undefined;
+      const tableName = stringArg(inner.arguments[0]) ?? resolvedName;
       if (!tableName) return undefined;
       return column ? { table: tableName, column } : { table: tableName };
     }
@@ -2368,6 +2607,7 @@ function stripTriggerExtras(trigger: Trigger): Trigger {
 function parseMcpTrigger(leaf: AstNode, scope: ProjectScope): ParsedTrigger | undefined {
   const chain = flattenMemberCallChain(leaf);
   let toolName: string | undefined;
+  let contract: AstNode | undefined;
   const gateNames: string[] = [];
 
   for (const node of chain) {
@@ -2383,6 +2623,7 @@ function parseMcpTrigger(leaf: AstNode, scope: ProjectScope): ParsedTrigger | un
       (member.object as Identifier).name === "mcp"
     ) {
       toolName = stringArg(c.arguments[0]);
+      if (isBoundaryContractObject(c.arguments[1])) contract = c.arguments[1];
       continue;
     }
     if (prop === "gate") {
@@ -2396,6 +2637,7 @@ function parseMcpTrigger(leaf: AstNode, scope: ProjectScope): ParsedTrigger | un
   return {
     trigger: { mcp: { name: toolName } },
     gates: gateNames.length > 0 ? gateNames : undefined,
+    ...(contract !== undefined ? { contract } : {}),
   };
 }
 
@@ -2407,15 +2649,19 @@ function parseEffectsObject(node: AstNode | undefined): Effects | undefined {
   const emits = stringArrayProp(node, "emits");
   const sends = stringArrayProp(node, "sends");
   const asks = stringArrayProp(node, "asks");
+  const embeds = stringArrayProp(node, "embeds");
   const secrets = stringArrayProp(node, "secrets");
   const calls = stringArrayProp(node, "calls");
+  const fetches = stringArrayProp(node, "fetches");
   if (reads) effects.reads = reads as Effects["reads"];
   if (writes) effects.writes = writes as Effects["writes"];
   if (emits) effects.emits = emits;
   if (sends) effects.sends = sends;
   if (asks) effects.asks = asks;
+  if (embeds) effects.embeds = embeds;
   if (secrets) effects.secrets = secrets;
   if (calls) effects.calls = calls;
+  if (fetches) effects.fetches = fetches;
   return effects;
 }
 
@@ -2526,6 +2772,26 @@ function schemaProp(
   return "…";
 }
 
+/** Read invoke contract fields from an exposure bag (`http.*` / `mcp.tool`). */
+function exposureSchemaProp(
+  contract: AstNode | undefined,
+  key: string,
+  scope: ProjectScope,
+  filePath: string,
+): JsonSchema | undefined {
+  return schemaProp(contract, key, scope, filePath);
+}
+
+/** True when an AST node looks like a {@link BoundaryContract} bag (not a path). */
+function isBoundaryContractObject(node: AstNode | undefined): node is AstNode {
+  if (!node || node.type !== "ObjectExpression") return false;
+  for (const prop of objectProperties(node)) {
+    const key = propKey(prop);
+    if (key === "in" || key === "out" || key === "errors" || key === "breaking") return true;
+  }
+  return false;
+}
+
 // ── AST helpers ────────────────────────────────────────────────────────────
 
 /** Leaf-to-root walk of `http.get("/x").public().live(signal)`. */
@@ -2648,10 +2914,148 @@ function objectArg(node: AstNode | undefined): AstNode | undefined {
   return undefined;
 }
 
+/** Shared helper options (`timezone` is runtime-only — Manifest Clock has no zone field). */
+function clockHelperOptsFromAst(opts: AstNode | undefined): {
+  readonly overridable?: boolean;
+  readonly description?: string;
+  readonly perTenant?: boolean;
+} {
+  return {
+    ...(boolProp(opts, "overridable") !== undefined
+      ? { overridable: boolProp(opts, "overridable") }
+      : {}),
+    ...(stringProp(opts, "description") ? { description: stringProp(opts, "description") } : {}),
+    ...(boolProp(opts, "perTenant") === true ? { perTenant: true } : {}),
+  };
+}
+
+/**
+ * Record a clock into the extract scope + binding map.
+ *
+ * @param scope - Project scope
+ * @param program - AST program
+ * @param call - Declaration call
+ * @param name - Clock name
+ * @param entry - Partial Manifest clock
+ */
+function recordClockDecl(
+  scope: ProjectScope,
+  program: AstNode,
+  call: CallExpression,
+  name: string,
+  entry: Clock,
+): void {
+  scope.clocks[name] = entry;
+  const bindingName = enclosingConstName(call, program);
+  if (bindingName) {
+    scope.bindings.set(bindingName, {
+      kind: "clock",
+      ref: name,
+    });
+  }
+}
+
+/**
+ * Read a structured cron field from an AST node (literal or array of literals).
+ *
+ * @param node - Property value
+ */
+function cronFieldFromAst(node: AstNode | undefined): CronField | undefined {
+  if (!node) return undefined;
+  if (node.type === "Literal") {
+    const v = (node as Literal).value;
+    if (typeof v === "number" || typeof v === "string") return v;
+    return undefined;
+  }
+  if (node.type === "ArrayExpression") {
+    const els = (node as AstNode & { elements?: AstNode[] }).elements ?? [];
+    const out: Array<number | string> = [];
+    for (const el of els) {
+      if (!el || el.type !== "Literal") return undefined;
+      const v = (el as Literal).value;
+      if (typeof v !== "number" && typeof v !== "string") return undefined;
+      out.push(v);
+    }
+    return out;
+  }
+  return undefined;
+}
+
+/**
+ * Build a cron expression from a structured fields object literal.
+ *
+ * @param obj - ObjectExpression with CronFields keys
+ */
+function cronExpressionFromFieldsAst(obj: AstNode): string | undefined {
+  const fields: {
+    minute?: CronField;
+    hour?: CronField;
+    dayOfMonth?: CronField;
+    month?: CronField;
+    dayOfWeek?: CronField;
+    at?: string;
+  } = {};
+  const minute = cronFieldFromAst(objectProp(obj, "minute"));
+  const hour = cronFieldFromAst(objectProp(obj, "hour"));
+  const dayOfMonth = cronFieldFromAst(objectProp(obj, "dayOfMonth"));
+  const month = cronFieldFromAst(objectProp(obj, "month"));
+  const dayOfWeek = cronFieldFromAst(objectProp(obj, "dayOfWeek"));
+  const at = stringProp(obj, "at");
+  if (minute !== undefined) fields.minute = minute;
+  if (hour !== undefined) fields.hour = hour;
+  if (dayOfMonth !== undefined) fields.dayOfMonth = dayOfMonth;
+  if (month !== undefined) fields.month = month;
+  if (dayOfWeek !== undefined) fields.dayOfWeek = dayOfWeek;
+  if (at !== undefined) fields.at = at;
+  try {
+    return buildCronExpression(fields);
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Compile a preset helper (`daily` / `hourly` / `weekly` / `monthly`) to cron.
+ *
+ * @param prop - Helper name
+ * @param opts - Options object literal
+ */
+function cronFromPresetHelper(
+  prop: "daily" | "hourly" | "weekly" | "monthly",
+  opts: AstNode | undefined,
+): string | undefined {
+  try {
+    if (prop === "daily") {
+      return buildCronExpression({ at: stringProp(opts, "at") ?? "00:00" });
+    }
+    if (prop === "hourly") {
+      const minute = numberProp(opts, "minute") ?? 0;
+      return buildCronExpression({ minute });
+    }
+    if (prop === "weekly") {
+      const on = cronFieldFromAst(objectProp(opts, "on"));
+      if (on === undefined) return undefined;
+      return buildCronExpression({
+        at: stringProp(opts, "at") ?? "00:00",
+        dayOfWeek: on,
+      });
+    }
+    const on = cronFieldFromAst(objectProp(opts, "on"));
+    if (on === undefined) return undefined;
+    return buildCronExpression({
+      at: stringProp(opts, "at") ?? "00:00",
+      dayOfMonth: on,
+    });
+  } catch {
+    return undefined;
+  }
+}
+
 /**
- * `flow("name", { do })` options live in arg1; `flow({ do })` in arg0.
+ * `flow("name", { do })` / `call("name", { do })` options live in arg1;
+ * `flow({ do })` in arg0.
  *
- * @param flowCall - `flow(...)` AST node
+ * @param flowCall - `flow(...)` / `call(...)` AST node
  */
 function flowOptionsArg(flowCall: CallExpression): AstNode | undefined {
   const named = objectArg(flowCall.arguments[1]);
@@ -2787,6 +3191,54 @@ function applyOkeStoreLiveConfig(opts: AstNode | undefined, scope: ProjectScope)
   scope.store = { ...scope.store, live: true };
 }
 
+/**
+ * Stamp project default for field `.embed()` from
+ * `oke({ store: { search: { embed: { model, dims } } } })`.
+ *
+ * @param opts - `oke({…})` options object
+ * @param scope - Project scope
+ */
+function applyOkeStoreSearchConfig(opts: AstNode | undefined, scope: ProjectScope): void {
+  const store = objectProp(opts, "store");
+  const search = objectProp(store, "search");
+  const embed = objectProp(search, "embed");
+  if (!embed) return;
+  const dims = numberProp(embed, "dims");
+  if (dims === undefined || !(Number.isInteger(dims) && dims > 0)) {
+    throw new Error(
+      `extract: oke({ store: { search: { embed } } }) requires dims: positive integer`,
+    );
+  }
+  const modelNode = objectProp(embed, "model");
+  let model: string | undefined = stringArg(modelNode);
+  if (!model && modelNode) {
+    const bindingName = identifierName(modelNode);
+    if (bindingName) {
+      const binding = scope.bindings.get(bindingName);
+      model = binding?.ref ?? bindingName;
+    } else if (modelNode.type === "MemberExpression") {
+      const prop = identifierName((modelNode as AstNode & { property: AstNode }).property);
+      if (prop === "name") {
+        const obj = (modelNode as AstNode & { object: AstNode }).object;
+        const objName = identifierName(obj);
+        if (objName) {
+          const binding = scope.bindings.get(objName);
+          model = binding?.ref ?? objName;
+        }
+      }
+    }
+  }
+  if (!model) {
+    throw new Error(
+      `extract: oke({ store: { search: { embed } } }) requires model (ai.model handle or name string)`,
+    );
+  }
+  scope.store = {
+    ...scope.store,
+    search: { embed: { model, dims } },
+  };
+}
+
 /**
  * Default every SQL table to live when `oke({ store: { live: true } })` is
  * on, unless the table explicitly opted out with `store.schema.live(false)`.
@@ -2881,6 +3333,72 @@ function assertTenantSafeSchema(manifest: Manifest): void {
   }
 }
 
+/**
+ * Inherit `oke({ store: { search: { embed } } })` onto every column that
+ * called `.embed()`, then stamp concrete `{ model, dims }` on the Manifest.
+ * Per-field values win when set.
+ */
+function resolveSearchEmbedDefaults(manifest: Manifest): void {
+  const project = manifest.store?.search?.embed;
+  for (const store of Object.values(manifest.stores ?? {})) {
+    if (store.facet !== "sql" || !store.tables) continue;
+    for (const [tableName, table] of Object.entries(store.tables)) {
+      for (const [colName, col] of Object.entries(table.columns ?? {})) {
+        if (!col || typeof col !== "object") continue;
+        const declared = col as DeclaredColumn;
+        // `embed: {}` is stamped when `.embed()` was called with no options.
+        if (declared.embed === undefined) continue;
+        const model = declared.embed.model ?? project?.model;
+        const dims = declared.embed.dims ?? project?.dims;
+        if (!model || dims === undefined || !(Number.isInteger(dims) && dims > 0)) {
+          throw new SearchConfigError(
+            tableName,
+            colName,
+            `.embed() needs model and dims — set oke({ store: { search: { embed: { model, dims } } } }) or pass them on .embed({ model, dims })`,
+          );
+        }
+        declared.embed = { model, dims };
+      }
+    }
+  }
+}
+
+/**
+ * Fail-loud hybrid-search config: `.embed()` requires an `ai` element;
+ * `.embed()` without `searchable` is already rejected in parseFieldChain.
+ * Call after {@link resolveSearchEmbedDefaults} so columns carry concrete dims.
+ */
+function assertSearchConfig(manifest: Manifest): void {
+  const hasAi =
+    manifest.ai !== undefined &&
+    (Object.keys(manifest.ai.models ?? {}).length > 0 ||
+      Object.keys(manifest.ai.prompts ?? {}).length > 0 ||
+      Object.keys(manifest.ai.agents ?? {}).length > 0);
+  for (const store of Object.values(manifest.stores ?? {})) {
+    if (store.facet !== "sql" || !store.tables) continue;
+    for (const [tableName, table] of Object.entries(store.tables)) {
+      for (const [colName, col] of Object.entries(table.columns ?? {})) {
+        if (!col || typeof col !== "object") continue;
+        const declared = col as DeclaredColumn;
+        if (declared.embed && !hasAi) {
+          throw new SearchConfigError(
+            tableName,
+            colName,
+            `.embed() requires a configured ai element (ai.model / ai.embed). Remove .embed() for BM25-only search, or declare an embedding model.`,
+          );
+        }
+        if (declared.embed && !declared.searchable) {
+          throw new SearchConfigError(
+            tableName,
+            colName,
+            `.embed() requires a prior .searchable() on the same field`,
+          );
+        }
+      }
+    }
+  }
+}
+
 function sortRecord<T>(record: Record<string, T>): Record<string, T> {
   const out: Record<string, T> = {};
   for (const key of Object.keys(record).sort()) {