okengine 0.18.4 → 0.19.0

package/src/kernel/triggers.ts

@@ -6,11 +6,14 @@
  */
 
 import { flattenGateArgs, GATE_PUBLIC_NAME, type GateAllDecl } from "../elements/gate/flatten.ts";
+import type { ClockDecl } from "../elements/clock/declare.ts";
+import type { BoundaryContract } from "./boundary-contract.ts";
 import type { NamedRef } from "./fx.ts";
 import { HTTP_PATH_PENDING, type HttpPathPending } from "./http-path-pending.ts";
 import { lazyRequire } from "./lazy-require.ts";
 
 export { HTTP_PATH_PENDING, isPendingHttpPath, type HttpPathPending } from "./http-path-pending.ts";
+export type { BoundaryContract } from "./boundary-contract.ts";
 
 /** HTTP methods accepted by {@link http}. */
 export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "OPTIONS" | "HEAD" | "QUERY";
@@ -27,15 +30,25 @@ export type GateAttach<T> = (...gates: GateArg[]) => T;
 /**
  * HTTP trigger value. Method and path are literal type parameters so
  * `typeof app` / the client can derive REST wire shape from the declaration.
+ * `C` preserves the invoke-contract bag for {@link on} → `$routes` typing.
  *
  * @typeParam M - HTTP method literal
  * @typeParam P - Path template literal (`/notes/:id`)
+ * @typeParam C - Invoke contract bag (or `undefined` when omitted)
  */
-export interface HttpTrigger<M extends HttpMethod = HttpMethod, P extends string = string> {
+export interface HttpTrigger<
+  M extends HttpMethod = HttpMethod,
+  P extends string = string,
+  // Default `any` so `Trigger` accepts contracted + contractless HTTP triggers;
+  // verb overloads still pin `C` to `undefined` or the authored bag.
+  C extends BoundaryContract | undefined = any,
+> {
   readonly kind: "http";
   readonly method: M;
   readonly path: P;
   readonly gates: readonly GateRef[];
+  /** Invoke contract authored on the verb options bag. */
+  readonly contract?: C extends undefined ? never : C;
   /**
    * Signal this GET exposes as a live SSE feed (`undefined` when not a live route).
    */
@@ -43,17 +56,17 @@ export interface HttpTrigger<M extends HttpMethod = HttpMethod, P extends string
   /**
    * Attach gates (registration order). `gate.all` handles and arrays flatten.
    */
-  readonly gate: GateAttach<HttpTrigger<M, P>>;
+  readonly gate: GateAttach<HttpTrigger<M, P, C>>;
   /**
    * Attach the unauthenticated public sentinel.
    */
-  public(): HttpTrigger<M, P>;
+  public(): HttpTrigger<M, P, C>;
   /**
    * Expose a `delivery: "live"` signal as SSE on this GET.
    *
    * @param signal - Live signal handle
    */
-  live(signal: SignalSource): LiveHttpTrigger<M, P>;
+  live(signal: SignalSource): LiveHttpTrigger<M, P, C>;
   /**
    * Declare a live query surface over a table on this GET: same CDC +
    * per-subscriber RLS classification physics as
@@ -62,7 +75,7 @@ export interface HttpTrigger<M extends HttpMethod = HttpMethod, P extends string
    *
    * @param table - `store.schema.table` (or drizzle/table handle) binding
    */
-  live(table: object): LiveHttpTrigger<M, P>;
+  live(table: object): LiveHttpTrigger<M, P, C>;
 }
 
 /**
@@ -73,14 +86,23 @@ export interface HttpTrigger<M extends HttpMethod = HttpMethod, P extends string
  *
  * @typeParam M - HTTP method literal
  * @typeParam P - Path template literal
+ * @typeParam C - Invoke contract bag (or `undefined` when omitted)
  */
 export interface LiveHttpTrigger<
   M extends HttpMethod = "GET",
   P extends string = string,
-> extends HttpTrigger<M, P> {
+  C extends BoundaryContract | undefined = any,
+> extends HttpTrigger<M, P, C> {
   readonly liveSignal: SignalSource;
-  readonly gate: GateAttach<LiveHttpTrigger<M, P>>;
-  public(): LiveHttpTrigger<M, P>;
+  readonly gate: GateAttach<LiveHttpTrigger<M, P, C>>;
+  public(): LiveHttpTrigger<M, P, C>;
+}
+
+/** Clock / cron trigger (`clock("daily", { every: "1d" })`). */
+export interface ClockTrigger {
+  readonly kind: "clock";
+  readonly name: string;
+  readonly clock?: ClockDecl;
 }
 
 /** Clock / interval trigger (`every("1h")`). */
@@ -124,17 +146,20 @@ export interface InternalTrigger {
  * Gates are required (typically `gate.auth` + `gate.scope(...)`) exactly
  * like sensitive HTTP routes.
  */
-export interface McpToolTrigger {
+export interface McpToolTrigger<C extends BoundaryContract | undefined = any> {
   readonly kind: "mcp";
   /** Tool name exposed in MCP `tools/list`. */
   readonly name: string;
   readonly gates: readonly GateRef[];
-  readonly gate: GateAttach<McpToolTrigger>;
+  /** Invoke contract authored on `mcp.tool(name, bag)`. */
+  readonly contract?: C extends undefined ? never : C;
+  readonly gate: GateAttach<McpToolTrigger<C>>;
 }
 
 /** Discriminated union of all trigger kinds. */
 export type Trigger =
   | HttpTrigger
+  | ClockTrigger
   | EveryTrigger
   | SignalAsTrigger
   | CdcTrigger
@@ -164,34 +189,54 @@ export function createGateAttach<T>(
  * @param path - Route path
  * @param gates - Attached gate refs
  * @param liveSignal - Live signal when `.live(signal)` was applied
+ * @param contract - Invoke contract bag from the verb options
  */
-export function createHttpTrigger<M extends HttpMethod, P extends string>(
+export function createHttpTrigger<
+  M extends HttpMethod,
+  P extends string,
+  C extends BoundaryContract | undefined = undefined,
+>(
   method: M,
   path: P,
   gates: readonly GateRef[],
   liveSignal: SignalSource,
-): LiveHttpTrigger<M, P>;
-export function createHttpTrigger<M extends HttpMethod, P extends string>(
+  contract?: C,
+): LiveHttpTrigger<M, P, C>;
+export function createHttpTrigger<
+  M extends HttpMethod,
+  P extends string,
+  C extends BoundaryContract | undefined = undefined,
+>(
   method: M,
   path: P,
   gates?: readonly GateRef[],
   liveSignal?: SignalSource,
-): HttpTrigger<M, P>;
-export function createHttpTrigger<M extends HttpMethod, P extends string>(
+  contract?: C,
+): HttpTrigger<M, P, C>;
+export function createHttpTrigger<
+  M extends HttpMethod,
+  P extends string,
+  C extends BoundaryContract | undefined = undefined,
+>(
   method: M,
   path: P,
   gates: readonly GateRef[] = [],
   liveSignal?: SignalSource,
-): HttpTrigger<M, P> {
-  const trigger: HttpTrigger<M, P> = {
-    kind: "http",
+  contract?: C,
+): HttpTrigger<M, P, C> {
+  const trigger = {
+    kind: "http" as const,
     method,
     path,
     gates,
+    ...(contract !== undefined ? { contract } : {}),
     ...(liveSignal !== undefined ? { liveSignal } : {}),
-    gate: createGateAttach((next) => createHttpTrigger(method, path, next, liveSignal), gates),
+    gate: createGateAttach(
+      (next) => createHttpTrigger(method, path, next, liveSignal, contract),
+      gates,
+    ),
     public() {
-      return createHttpTrigger(method, path, [...gates, GATE_PUBLIC_NAME], liveSignal);
+      return createHttpTrigger(method, path, [...gates, GATE_PUBLIC_NAME], liveSignal, contract);
     },
     live(source: SignalSource | object) {
       if (typeof source === "object" && !("name" in source)) {
@@ -203,12 +248,12 @@ export function createHttpTrigger<M extends HttpMethod, P extends string>(
           "table",
         );
         const signal = { name: `oke/live/sql:${storeTable.resolveTableName(source)}` };
-        return createHttpTrigger(method, path, gates, signal);
+        return createHttpTrigger(method, path, gates, signal, contract);
       }
-      return createHttpTrigger(method, path, gates, source as SignalSource);
+      return createHttpTrigger(method, path, gates, source as SignalSource, contract);
     },
   };
-  return trigger;
+  return trigger as HttpTrigger<M, P, C>;
 }
 
 /** Flow shape accepted by {@link http.resource} (duck-typed — any FlowDef). */
@@ -272,64 +317,113 @@ function loadHttpResource(): typeof import("./http-resource.ts") {
 /**
  * Shape of the {@link http} trigger namespace. Each method keeps `P` as a
  * generic type parameter so callers (and the client) retain literal path
- * types for param extraction.
+ * types for param extraction. Invoke contracts use an options bag
+ * (`http.post({ in, out })` or `http.post("/notes", { in, out })`); the bag
+ * type is preserved so {@link on} can project `in` / `out` / `errors` onto
+ * `FlowDef` / `$routes`.
  */
 export interface HttpTriggerNamespace {
-  /**
-   * Pathless — file-tree stamp fills the URL. Unresolved sentinel fails boot.
-   */
-  get(): HttpTrigger<"GET", HttpPathPending>;
+  /** Pathless — file-tree stamp fills the URL. Unresolved sentinel fails boot. */
+  get<C extends BoundaryContract | undefined = undefined>(
+    contract?: C,
+  ): HttpTrigger<"GET", HttpPathPending, C>;
   /**
    * @param path - Route path (`/:id` params supported)
+   * @param contract - Invoke contract bag
    */
-  get<P extends string>(path: P): HttpTrigger<"GET", P>;
+  get<P extends string, C extends BoundaryContract | undefined = undefined>(
+    path: P,
+    contract?: C,
+  ): HttpTrigger<"GET", P, C>;
   /** Pathless — file-tree stamp fills the URL. */
-  post(): HttpTrigger<"POST", HttpPathPending>;
+  post<C extends BoundaryContract | undefined = undefined>(
+    contract?: C,
+  ): HttpTrigger<"POST", HttpPathPending, C>;
   /**
    * @param path - Route path
+   * @param contract - Invoke contract bag
    */
-  post<P extends string>(path: P): HttpTrigger<"POST", P>;
+  post<P extends string, C extends BoundaryContract | undefined = undefined>(
+    path: P,
+    contract?: C,
+  ): HttpTrigger<"POST", P, C>;
   /** Pathless — file-tree stamp fills the URL. */
-  put(): HttpTrigger<"PUT", HttpPathPending>;
+  put<C extends BoundaryContract | undefined = undefined>(
+    contract?: C,
+  ): HttpTrigger<"PUT", HttpPathPending, C>;
   /**
    * @param path - Route path
+   * @param contract - Invoke contract bag
    */
-  put<P extends string>(path: P): HttpTrigger<"PUT", P>;
+  put<P extends string, C extends BoundaryContract | undefined = undefined>(
+    path: P,
+    contract?: C,
+  ): HttpTrigger<"PUT", P, C>;
   /** Pathless — file-tree stamp fills the URL. */
-  patch(): HttpTrigger<"PATCH", HttpPathPending>;
+  patch<C extends BoundaryContract | undefined = undefined>(
+    contract?: C,
+  ): HttpTrigger<"PATCH", HttpPathPending, C>;
   /**
    * @param path - Route path
+   * @param contract - Invoke contract bag
    */
-  patch<P extends string>(path: P): HttpTrigger<"PATCH", P>;
+  patch<P extends string, C extends BoundaryContract | undefined = undefined>(
+    path: P,
+    contract?: C,
+  ): HttpTrigger<"PATCH", P, C>;
   /** Pathless — file-tree stamp fills the URL. */
-  delete(): HttpTrigger<"DELETE", HttpPathPending>;
+  delete<C extends BoundaryContract | undefined = undefined>(
+    contract?: C,
+  ): HttpTrigger<"DELETE", HttpPathPending, C>;
   /**
    * @param path - Route path
+   * @param contract - Invoke contract bag
    */
-  delete<P extends string>(path: P): HttpTrigger<"DELETE", P>;
+  delete<P extends string, C extends BoundaryContract | undefined = undefined>(
+    path: P,
+    contract?: C,
+  ): HttpTrigger<"DELETE", P, C>;
   /** Pathless — file-tree stamp fills the URL. */
-  options(): HttpTrigger<"OPTIONS", HttpPathPending>;
+  options<C extends BoundaryContract | undefined = undefined>(
+    contract?: C,
+  ): HttpTrigger<"OPTIONS", HttpPathPending, C>;
   /**
    * @param path - Route path
+   * @param contract - Invoke contract bag
    */
-  options<P extends string>(path: P): HttpTrigger<"OPTIONS", P>;
+  options<P extends string, C extends BoundaryContract | undefined = undefined>(
+    path: P,
+    contract?: C,
+  ): HttpTrigger<"OPTIONS", P, C>;
   /** Pathless — file-tree stamp fills the URL. */
-  head(): HttpTrigger<"HEAD", HttpPathPending>;
+  head<C extends BoundaryContract | undefined = undefined>(
+    contract?: C,
+  ): HttpTrigger<"HEAD", HttpPathPending, C>;
   /**
    * @param path - Route path
+   * @param contract - Invoke contract bag
    */
-  head<P extends string>(path: P): HttpTrigger<"HEAD", P>;
+  head<P extends string, C extends BoundaryContract | undefined = undefined>(
+    path: P,
+    contract?: C,
+  ): HttpTrigger<"HEAD", P, C>;
   /**
    * Safe, idempotent read that carries a JSON body (RFC 10008).
    * Pathless — file-tree stamp fills the URL.
    */
-  query(): HttpTrigger<"QUERY", HttpPathPending>;
+  query<C extends BoundaryContract | undefined = undefined>(
+    contract?: C,
+  ): HttpTrigger<"QUERY", HttpPathPending, C>;
   /**
    * Safe, idempotent read that carries a JSON body (RFC 10008).
    *
    * @param path - Route path
+   * @param contract - Invoke contract bag
    */
-  query<P extends string>(path: P): HttpTrigger<"QUERY", P>;
+  query<P extends string, C extends BoundaryContract | undefined = undefined>(
+    path: P,
+    contract?: C,
+  ): HttpTrigger<"QUERY", P, C>;
   /**
    * Mount a CRUD resource (list/create on `path`, get/update/remove on
    * `path/:id`) for the `on(http.resource(…))` overload. Chain `.gate(...)`
@@ -344,17 +438,44 @@ export interface HttpTriggerNamespace {
   live(signal: SignalSource): LiveHttpTrigger<"GET">;
 }
 
+/** True when `value` looks like a {@link BoundaryContract} options bag (not a path). */
+function isHttpContractBag(value: unknown): value is BoundaryContract {
+  if (typeof value !== "object" || value === null) return false;
+  const o = value as Record<string, unknown>;
+  return "in" in o || "out" in o || "errors" in o || "breaking" in o;
+}
+
 /** Bind an HTTP verb constructor (`http.get`, `http.query`, …). */
 function httpVerb<M extends HttpMethod>(
   method: M,
 ): {
-  (): HttpTrigger<M, HttpPathPending>;
-  <P extends string>(path: P): HttpTrigger<M, P>;
+  <C extends BoundaryContract | undefined = undefined>(
+    contract?: C,
+  ): HttpTrigger<M, HttpPathPending, C>;
+  <P extends string, C extends BoundaryContract | undefined = undefined>(
+    path: P,
+    contract?: C,
+  ): HttpTrigger<M, P, C>;
 } {
-  return ((path?: string) =>
-    createHttpTrigger(method, path === undefined ? HTTP_PATH_PENDING : path)) as {
-    (): HttpTrigger<M, HttpPathPending>;
-    <P extends string>(path: P): HttpTrigger<M, P>;
+  return ((pathOrContract?: string | BoundaryContract, maybeContract?: BoundaryContract) => {
+    if (pathOrContract === undefined) {
+      return createHttpTrigger(method, HTTP_PATH_PENDING);
+    }
+    if (typeof pathOrContract === "string") {
+      return createHttpTrigger(method, pathOrContract, [], undefined, maybeContract);
+    }
+    if (isHttpContractBag(pathOrContract)) {
+      return createHttpTrigger(method, HTTP_PATH_PENDING, [], undefined, pathOrContract);
+    }
+    throw new TypeError(`http.${method.toLowerCase()}(…): expected a path string or contract bag`);
+  }) as {
+    <C extends BoundaryContract | undefined = undefined>(
+      contract?: C,
+    ): HttpTrigger<M, HttpPathPending, C>;
+    <P extends string, C extends BoundaryContract | undefined = undefined>(
+      path: P,
+      contract?: C,
+    ): HttpTrigger<M, P, C>;
   };
 }
 
@@ -378,12 +499,19 @@ export const http: HttpTriggerNamespace = {
 };
 
 /**
- * Clock trigger — run on an interval (`every("10m")`, `every("1h")`).
+ * True when `value` is a declared clock handle (`clock("daily", { every: "1d" })`).
  *
- * @param interval - Duration string
+ * @param value - Unknown
  */
-export function every(interval: string): EveryTrigger {
-  return { kind: "every", interval };
+export function isClockDecl(value: unknown): value is ClockDecl {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value as Record<string, unknown>;
+  return (
+    typeof v.name === "string" &&
+    !("kind" in v) &&
+    !("do" in v) &&
+    ("cron" in v || "every" in v || "timezone" in v)
+  );
 }
 
 /**
@@ -427,34 +555,6 @@ export function isSignalTriggerSource(value: unknown): value is SignalSource {
   return true;
 }
 
-/** Table handle returned by {@link table}. */
-export interface TableHandle {
-  readonly name: string;
-  /**
-   * CDC trigger when `column` (or any column) changes.
-   *
-   * @param column - Optional column name
-   */
-  changed(column?: string): CdcTrigger;
-}
-
-/**
- * CDC table handle — `table("orders").changed("status")`.
- *
- * @param name - Table name
- * @param store - Optional store name
- */
-export function table(name: string, store?: string): TableHandle {
-  return {
-    name,
-    changed(column?: string): CdcTrigger {
-      return column === undefined
-        ? { kind: "cdc", table: name, store }
-        : { kind: "cdc", table: name, column, store };
-    },
-  };
-}
-
 /**
  * Explicit internal / call-only trigger.
  * Prefer an untriggered `flow(name, {…})` when no trigger value is needed.
@@ -462,42 +562,51 @@ export function table(name: string, store?: string): TableHandle {
 export const internal: InternalTrigger = { kind: "internal" };
 
 /**
- * MCP tool namespace — `mcp.tool("bookings.create")` marks a flow as an
- * explicitly exposed MCP tool for OAuth user-plane clients. Chain `.gate(...)`
- * like HTTP triggers; no gates ⇒ not exposed (deny-by-default).
+ * MCP tool namespace — `mcp.tool("bookings.create", { in, out })` marks a flow
+ * as an explicitly exposed MCP tool for OAuth user-plane clients. Chain
+ * `.gate(...)` like HTTP triggers; no gates ⇒ not exposed (deny-by-default).
  *
  * @param name - Tool name (namespaced, e.g. `bookings.create`)
  */
 export const mcp: {
   /**
    * @param name - Tool name
+   * @param contract - Invoke contract bag
    */
-  tool(name: string): McpToolTrigger;
+  tool<C extends BoundaryContract | undefined = undefined>(
+    name: string,
+    contract?: C,
+  ): McpToolTrigger<C>;
 } = {
-  tool(name: string): McpToolTrigger {
+  tool(name: string, contract?: BoundaryContract): McpToolTrigger {
     if (typeof name !== "string" || name.trim().length === 0) {
       throw new TypeError("mcp.tool(name): name is required");
     }
-    return withMcpGates(name, []);
+    return withMcpGates(name, [], contract);
   },
 };
 
 /** @internal Attach a resolved gate list onto a fresh {@link McpToolTrigger}. */
-function withMcpGates(name: string, gates: readonly GateRef[]): McpToolTrigger {
+function withMcpGates<C extends BoundaryContract | undefined = undefined>(
+  name: string,
+  gates: readonly GateRef[],
+  contract?: C,
+): McpToolTrigger<C> {
   return {
     kind: "mcp",
     name,
     gates,
-    gate: createGateAttach((next) => withMcpGates(name, next), gates),
-  };
+    ...(contract !== undefined ? { contract } : {}),
+    gate: createGateAttach((next) => withMcpGates(name, next, contract), gates),
+  } as McpToolTrigger<C>;
 }
 
 /**
  * Normalize anything accepted by {@link on} into a {@link Trigger}.
  *
- * @param value - Trigger or signal handle
+ * @param value - Trigger, clock, or signal handle
  */
-export function normalizeTrigger(value: Trigger | SignalSource): Trigger {
+export function normalizeTrigger(value: Trigger | SignalSource | ClockDecl): Trigger {
   if (typeof value !== "object" || value === null) {
     throw new TypeError("on() expected a trigger or signal handle");
   }
@@ -505,6 +614,7 @@ export function normalizeTrigger(value: Trigger | SignalSource): Trigger {
     const kind = (value as Trigger).kind;
     if (
       kind === "http" ||
+      kind === "clock" ||
       kind === "every" ||
       kind === "signal" ||
       kind === "cdc" ||
@@ -514,6 +624,9 @@ export function normalizeTrigger(value: Trigger | SignalSource): Trigger {
       return value as Trigger;
     }
   }
+  if (isClockDecl(value)) {
+    return { kind: "clock", name: value.name, clock: value };
+  }
   if (isSignalTriggerSource(value)) {
     return asSignalTrigger(value);
   }
@@ -527,6 +640,8 @@ export function normalizeTrigger(value: Trigger | SignalSource): Trigger {
  */
 export type BoundTriggerOf<T> = T extends Trigger
   ? T
-  : T extends SignalSource
-    ? SignalAsTrigger
-    : Trigger;
+  : T extends ClockDecl
+    ? ClockTrigger
+    : T extends SignalSource
+      ? SignalAsTrigger
+      : Trigger;

package/src/kernel-entry.ts

@@ -9,7 +9,6 @@ export {
   on,
   flow,
   http,
-  every,
   internal,
   fail,
   createFx,

package/src/manifest/diff.ts

@@ -42,7 +42,17 @@ const CATEGORY_RANK: Record<DiffCategory, number> = {
   "no-impact": 0,
 };
 
-const EFFECT_KEYS = ["reads", "writes", "emits", "sends", "asks", "secrets", "calls"] as const;
+const EFFECT_KEYS = [
+  "reads",
+  "writes",
+  "emits",
+  "sends",
+  "asks",
+  "embeds",
+  "secrets",
+  "calls",
+  "fetches",
+] as const;
 
 /** Isolation strength: higher = stronger tenant separation. */
 const ISOLATION_RANK: Record<string, number> = {

package/src/manifest/fixtures/skyport.excerpt.json

@@ -15,7 +15,7 @@
         "secrets": []
       },
       "slo": { "availability": "99.9%", "latency": { "p99": "200ms" } },
-      "source": "src/flows/bookings/index.ts:18"
+      "source": "src/flows/bookings/index.ts:24"
     },
     "bookings.mine": { "cacheKeys": "computed:sql:bookings/userId" },
     "payments.chargeBooking": {

package/src/manifest/types.ts

@@ -89,7 +89,8 @@ export type JsonSchema = string | Record<string, unknown>;
  *
  * `secrets` is a capability (not an irreversible effect).
  * `calls` portals to the callee's transitive effects.
- * `sends` / `asks` are irreversible (asks also nondeterministic + cost).
+ * `sends` / `asks` / `embeds` / `fetches` are irreversible
+ * (asks/embeds also nondeterministic + cost).
  */
 export interface Effects {
   /** Store reads, plus `"runs"` for `fx.runs` and `signal:name` for `fx.deadLetters` / `fx.live`. */
@@ -108,12 +109,28 @@ export interface Effects {
   sends?: TemplateRef[];
   /** AI prompt asks (irreversible, nondeterministic, cost). */
   asks?: PromptRef[];
+  /**
+   * AI embedding model refs from `fx.embed` (irreversible, nondeterministic, cost).
+   * Distinct from {@link asks} — never conflated with prompt asks.
+   */
+  embeds?: EmbedRef[];
   /** Vault secret capabilities. */
   secrets?: SecretRef[];
   /** Nested flow calls (transitive effects). */
   calls?: FlowRef[];
+  /**
+   * Outbound HTTP hosts from `fx.fetch` (irreversible).
+   * Hostname only (e.g. `"api.stripe.com"`), never a full URL.
+   */
+  fetches?: FetchHostRef[];
 }
 
+/** Embedding model ref for `effects.embeds` / `fx.embed` (model name). */
+export type EmbedRef = string;
+
+/** Host ref for `effects.fetches` / `fx.fetch` (hostname). */
+export type FetchHostRef = string;
+
 /** HTTP trigger surface. */
 export interface HttpTrigger {
   method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS" | "QUERY";
@@ -299,6 +316,14 @@ export interface DeclaredColumn extends ColumnClassification {
   description?: string;
   /** Foreign key when `.references()` was declared. */
   references?: DeclaredColumnReference;
+  /**
+   * Built-in hybrid search — BM25 when present; LSH when `embed` is set.
+   * Weight is BM25F field weight (default 1).
+   */
+  searchable?: { weight: number };
+  /** Async embedding + LSH — requires `searchable` and a configured AI element. */
+  /** Concrete after extract resolves project defaults — `dims` is always set. */
+  embed?: { model?: string; dims: number };
 }
 
 /** Field classification value forms. */
@@ -331,6 +356,15 @@ export interface Table {
    * defaulting.
    */
   live?: boolean;
+  /**
+   * Derived hybrid-search posture for Console / doctor inspectability.
+   * Present when any column has `.searchable()` / `.embed()`.
+   */
+  search?: {
+    engines: Array<"bm25" | "lsh">;
+    /** True when push detected existing rows needing `oke db search-backfill`. */
+    backfillRequired?: boolean;
+  };
 }
 
 /** One Store declaration. */
@@ -494,10 +528,20 @@ export interface Plugin {
   tables?: Record<string, PluginTable>;
 }
 
-/** Store-wide live-query defaulting configuration. */
+/** Store-wide live-query / search defaulting configuration. */
 export interface StoreLive {
   /** `oke({ store: { live: true } })` is on — new tables are live by default. */
   live?: boolean;
+  /**
+   * Project default for field `.embed()` — `oke({ store: { search: { embed } } })`.
+   * Per-field `.embed({ model?, dims? })` overrides these when set.
+   */
+  search?: {
+    embed?: {
+      model: string;
+      dims: number;
+    };
+  };
 }
 
 /** Tenancy configuration (resolver is code; isolation is data). */