okengine 0.18.5 → 0.19.0

package/src/kernel/fx.test.ts

@@ -129,7 +129,7 @@ describe("fx — capability enforcement", () => {
       err = e;
     }
     expect(err).toBeInstanceOf(OkeError);
-    expect((err as OkeError).code).toBe(1015);
+    expect((err as OkeError).code).toBe(1810);
   });
 
   test("index driverId is meilisearch before first I/O (not a function, not memory)", async () => {
@@ -485,9 +485,15 @@ describe("fx — wholesale swap", () => {
       async ask() {
         return {};
       },
+      async embed() {
+        return [];
+      },
       async search() {
         return [];
       },
+      async fetch() {
+        return new Response(null, { status: 204 });
+      },
       async run() {
         return {};
       },
@@ -679,31 +685,31 @@ describe("fx.json", () => {
 });
 
 describe("errors — registry", () => {
-  test("OKE1042 is reserved with the §21 shape", () => {
+  test("OKE1240 is reserved with the §21 shape", () => {
     const def = OKE_ERRORS.ORPHAN_EMIT;
-    expect(def.code).toBe(1042);
-    expect(lookupOkeError(1042)).toEqual(def);
+    expect(def.code).toBe(1240);
+    expect(lookupOkeError(1240)).toEqual(def);
     const err = new OkeError(def, {
       flow: "bookings.create",
       resource: "order-placed",
     });
-    expect(err.message).toContain("OKE1042");
+    expect(err.message).toContain("OKE1240");
     expect(err.message).toContain("no subscriber");
-    expect(err.message).toContain("https://oke.omqkhafi.dev/e/1042");
+    expect(err.message).toContain("https://oke.omqkhafi.dev/e/1240");
     expect(err.message).toContain("→");
   });
 
-  test("OKE1043 is reserved for signal schema emit failures", () => {
+  test("OKE1250 is reserved for signal schema emit failures", () => {
     const def = OKE_ERRORS.SIGNAL_SCHEMA;
-    expect(def.code).toBe(1043);
-    expect(lookupOkeError(1043)).toEqual(def);
+    expect(def.code).toBe(1250);
+    expect(lookupOkeError(1250)).toEqual(def);
     const err = new OkeError(def, {
       resource: "order-placed",
       detail: "total: Expected number, received string",
     });
-    expect(err.message).toContain("OKE1043");
+    expect(err.message).toContain("OKE1250");
     expect(err.message).toContain("order-placed");
-    expect(err.message).toContain("https://oke.omqkhafi.dev/e/1043");
+    expect(err.message).toContain("https://oke.omqkhafi.dev/e/1250");
   });
 
   test("fx.fail returns a value, not an exception", () => {

package/src/kernel/fx.ts

@@ -44,7 +44,13 @@ import type { TenantStore } from "../auth/tenants.ts";
 import type { SessionCrypto, SessionStore } from "../auth/sessions.ts";
 import type { Manifest } from "../manifest/types.ts";
 import { createCapabilityToken, type CapabilityToken } from "./capability.ts";
-import { createEffectLedger, recordEffect, reversibilityOf, type EffectLedger } from "./effects.ts";
+import {
+  createEffectLedger,
+  recordEffect,
+  reversibilityOf,
+  type EffectExternal,
+  type EffectLedger,
+} from "./effects.ts";
 import { resolveDurationMs } from "./elapsed.ts";
 import {
   DryRunWriteIsolationError,
@@ -90,6 +96,11 @@ function loadFxLiveStream(): typeof import("./fx-live-stream.ts") {
   return lazyRequire(import.meta.dir, ["fx", "live", "stream"].join("-"));
 }
 
+/** `fx.fetch` — keep host parsing + dry-run stub off cold edge / Store-only graphs. */
+function loadFxFetch(): typeof import("./fx-fetch.ts") {
+  return lazyRequire(import.meta.dir, ["fx", "fetch"].join("-"));
+}
+
 /** Resource ref Flows declare to read the Runs store via {@link Fx.runs}. */
 export const RUNS_RESOURCE = "runs";
 
@@ -386,7 +397,7 @@ export interface JsonStreamResult {
   readonly kind: "stream";
   readonly status: 200;
   readonly chunks: AsyncIterable<unknown>;
-  /** Awaited before the 200 SSE body; throws OKE1014 on a missing resume cursor. */
+  /** Awaited before the 200 SSE body; throws OKE1210 on a missing resume cursor. */
   ready?: () => Promise<void>;
   /** Set by the kernel to commit journal / Runs after the stream settles. */
   finalize?: () => Promise<void>;
@@ -693,7 +704,7 @@ export interface Fx {
    * Stream a `delivery: "live"` signal as SSE (records `read` on `signal:<name>`).
    *
    * HTTP `Last-Event-ID` is applied when `opts.afterId` is omitted. A missing
-   * cursor throws OKE1014; `JsonStreamResult.ready` turns that into HTTP 410.
+   * cursor throws OKE1210; `JsonStreamResult.ready` turns that into HTTP 410.
    *
    * @param signal - Signal name or handle
    * @param opts - Payload filter and optional resume cursor
@@ -773,6 +784,14 @@ export interface Fx {
    * @param opts - Model routing opts
    */
   ask(prompt: NamedRef, input?: unknown, opts?: FxAskOptions): Promise<Record<string, unknown>>;
+  /**
+   * Embed text via a named model (records `embed` — distinct from `ask`).
+   * Returns the vector; does not write an index.
+   *
+   * @param model - Model name or handle
+   * @param text - Text to embed
+   */
+  embed(model: NamedRef, text: string): Promise<readonly number[]>;
   /**
    * Similarity search over an index/embed (records `read` on the embed ref).
    *
@@ -781,6 +800,17 @@ export interface Fx {
    * @param opts - Search options
    */
   search(embed: NamedRef, query: unknown, opts?: FxSearchOptions): Promise<unknown[]>;
+  /**
+   * Outbound HTTP to an arbitrary URL (records `fetch` on the hostname).
+   *
+   * Unconditionally external (`kind: "third-party"`). Declare the hostname in
+   * `effects.fetches`. Prefer wrapping inside {@link Fx.step}; use
+   * {@link Fx.retry} only when the remote API is safe to repeat.
+   *
+   * @param url - Absolute URL (string or URL)
+   * @param init - Standard `RequestInit`
+   */
+  fetch(url: string | URL, init?: RequestInit): Promise<Response>;
   /**
    * Run a bounded AI agent (records `ask`).
    *
@@ -1077,6 +1107,15 @@ function stampAskTelemetry(
   if (outputTokens > 0) telemetry.outputTokens += outputTokens;
 }
 
+/**
+ * Hostname for `fx.fetch` capability / ledger resource.
+ *
+ * @param href - Absolute URL string
+ */
+export function hostFromFetchUrl(href: string): string {
+  return loadFxFetch().hostFromFetchUrl(href);
+}
+
 /**
  * Create an in-memory `fx` context (v1 stubs, full surface).
  *
@@ -1162,9 +1201,12 @@ export function createFxContext(options: CreateFxOptions): FxContext {
     kind: Parameters<CapabilityToken["assert"]>[0],
     resource: string,
     body: () => T | Promise<T>,
+    externalOf?:
+      | EffectExternal
+      | ((result: T | undefined, error: unknown) => EffectExternal | undefined),
   ): Promise<T> {
     capability.assert(kind, resource);
-    const execute = () => recordEffect(ledger, kind, resource, now, body);
+    const execute = () => recordEffect(ledger, kind, resource, now, body, externalOf);
     if (journal) {
       return journal.effect(kind, resource, execute);
     }
@@ -1265,14 +1307,15 @@ export function createFxContext(options: CreateFxOptions): FxContext {
       table: unknown,
       body: () => T | Promise<T>,
     ): Promise<T> => {
+      const externalOf = (): EffectExternal | undefined => cached?.external;
       const name = schemaTableName(table);
       if (name !== undefined) {
         const perTable = sqlTableRef(name);
         if (perTable !== ref && capability.allows(kind, perTable)) {
-          return gated(kind, perTable, body);
+          return gated(kind, perTable, body, externalOf);
         }
       }
-      return gated(kind, ref, body);
+      return gated(kind, ref, body, externalOf);
     };
 
     return {
@@ -1443,6 +1486,42 @@ export function createFxContext(options: CreateFxOptions): FxContext {
           return h.page(table, pageOptions);
         });
       },
+      search(table, searchOptions) {
+        return gatedTable("read", table, async () => {
+          const h = await ensure();
+          const result = await h.search(table, searchOptions);
+          // Optional rerank via fx.ask — only when explicitly requested.
+          if (
+            searchOptions.rerank &&
+            typeof searchOptions.rerank === "object" &&
+            searchOptions.rerank.model
+          ) {
+            const model = searchOptions.rerank.model;
+            const pk = "id";
+            const docs = result.data.map((row) => ({
+              id: String(row[pk] ?? ""),
+              text: Object.values(row)
+                .filter((v) => typeof v === "string")
+                .join("\n"),
+              score: 0,
+            }));
+            const out = (await fx.ask(model, {
+              query: searchOptions.query,
+              docs,
+            })) as { rankedIds?: string[] };
+            if (out.rankedIds && out.rankedIds.length > 0) {
+              const byId = new Map(result.data.map((r) => [String(r[pk] ?? ""), r]));
+              return {
+                ...result,
+                data: out.rankedIds
+                  .map((id) => byId.get(id))
+                  .filter((r): r is NonNullable<typeof r> => r !== undefined),
+              };
+            }
+          }
+          return result;
+        });
+      },
       ensureTable(table) {
         return gatedTable("write", table, async () => {
           refuseDryRunWrite();
@@ -1555,17 +1634,28 @@ export function createFxContext(options: CreateFxOptions): FxContext {
           }
           const isRead = prop === "get" || prop === "search" || prop === "list" || prop === "ttlMs";
           return (...args: unknown[]) =>
-            gated(isRead ? "read" : "write", baseRef, async () => {
-              if (!isRead && isDryRun()) {
-                throw new DryRunWriteIsolationError(
-                  `Driver-backed store "${baseRef}" cannot isolate writes during dry-run; dry-run refused rather than risk a double-write.`,
-                );
-              }
-              const h = await open();
-              const fn = (h as unknown as Record<string | symbol, unknown>)[prop];
-              if (typeof fn !== "function") return undefined;
-              return (fn as (...a: unknown[]) => unknown).apply(h, args);
-            });
+            gated(
+              isRead ? "read" : "write",
+              baseRef,
+              async () => {
+                if (!isRead && isDryRun()) {
+                  throw new DryRunWriteIsolationError(
+                    `Driver-backed store "${baseRef}" cannot isolate writes during dry-run; dry-run refused rather than risk a double-write.`,
+                  );
+                }
+                const h = await open();
+                const fn = (h as unknown as Record<string | symbol, unknown>)[prop];
+                if (typeof fn !== "function") return undefined;
+                return (fn as (...a: unknown[]) => unknown).apply(h, args);
+              },
+              () => {
+                const opened = cache.handle;
+                if (opened && typeof opened === "object" && "external" in opened) {
+                  return (opened as { external?: EffectExternal }).external;
+                }
+                return undefined;
+              },
+            );
         },
       });
     }
@@ -1893,26 +1983,33 @@ export function createFxContext(options: CreateFxOptions): FxContext {
     cache,
     send(template, opts) {
       const name = resolveName(template);
-      return gated("send", name, async () => {
-        // Dry-run: record "would have fired" — never contact a real channel
-        // (console §9.1 · §9.3 · §9.4).
-        if (isDryRun()) {
-          recordWouldHaveFired("send", name);
+      let sendExternal: EffectExternal | undefined;
+      return gated(
+        "send",
+        name,
+        async () => {
+          // Dry-run: record "would have fired" — never contact a real channel
+          // (console §9.1 · §9.3 · §9.4).
+          if (isDryRun()) {
+            recordWouldHaveFired("send", name);
+            return { ok: true as const };
+          }
+          if (options.channelRuntime) {
+            const result = await options.channelRuntime.send(name, {
+              to: opts?.to ?? "",
+              data: opts?.data,
+              via: opts?.via?.map(resolveName),
+              locale: opts?.locale ?? locale,
+              profileLocale: opts?.profileLocale,
+              acceptLanguage: opts?.acceptLanguage,
+            });
+            sendExternal = result.external;
+            return { ok: result.ok as true };
+          }
           return { ok: true as const };
-        }
-        if (options.channelRuntime) {
-          const result = await options.channelRuntime.send(name, {
-            to: opts?.to ?? "",
-            data: opts?.data,
-            via: opts?.via?.map(resolveName),
-            locale: opts?.locale ?? locale,
-            profileLocale: opts?.profileLocale,
-            acceptLanguage: opts?.acceptLanguage,
-          });
-          return { ok: result.ok as true };
-        }
-        return { ok: true as const };
-      });
+        },
+        () => sendExternal,
+      );
     },
     sendOtp(opts) {
       return gated("send", "sms-otp", async () => {
@@ -1982,28 +2079,51 @@ export function createFxContext(options: CreateFxOptions): FxContext {
     },
     ask(prompt, input, opts) {
       const name = resolveName(prompt);
-      return gated("ask", name, async () => {
-        // Dry-run: stub the model call the same way as send.
-        if (isDryRun()) {
-          recordWouldHaveFired("ask", name);
-          return {};
-        }
-        if (options.aiRuntime) {
-          try {
-            return await options.aiRuntime.ask(name, input, {
-              via: opts?.via?.map(resolveName),
-              ...(opts?.timeout !== undefined ? { timeout: opts.timeout } : {}),
-              tools: opts?.tools?.map(resolveName),
-              maxSteps: opts?.maxSteps,
-              // Host fx.call — same capability / ledger / Runs path as any call.
-              callTool: (tool, toolInput) => fx.call(tool, toolInput),
-            });
-          } finally {
-            stampAskTelemetry(telemetry, options.aiRuntime, name);
+      return gated(
+        "ask",
+        name,
+        async () => {
+          // Dry-run: stub the model call the same way as send.
+          if (isDryRun()) {
+            recordWouldHaveFired("ask", name);
+            return {};
           }
-        }
-        throw new Error(`fx.ask: AI runtime is not configured for prompt "${name}"`);
-      });
+          if (options.aiRuntime) {
+            try {
+              return await options.aiRuntime.ask(name, input, {
+                via: opts?.via?.map(resolveName),
+                ...(opts?.timeout !== undefined ? { timeout: opts.timeout } : {}),
+                tools: opts?.tools?.map(resolveName),
+                maxSteps: opts?.maxSteps,
+                // Host fx.call — same capability / ledger / Runs path as any call.
+                callTool: (tool, toolInput) => fx.call(tool, toolInput),
+              });
+            } finally {
+              stampAskTelemetry(telemetry, options.aiRuntime, name);
+            }
+          }
+          throw new Error(`fx.ask: AI runtime is not configured for prompt "${name}"`);
+        },
+        () => options.aiRuntime?.lastExternal,
+      );
+    },
+    embed(model, text) {
+      const name = resolveName(model);
+      return gated(
+        "embed",
+        name,
+        async () => {
+          if (isDryRun()) {
+            recordWouldHaveFired("embed", name);
+            return [];
+          }
+          if (options.aiRuntime && typeof options.aiRuntime.embedVector === "function") {
+            return options.aiRuntime.embedVector(name, text);
+          }
+          throw new Error(`fx.embed: AI runtime is not configured for model "${name}"`);
+        },
+        () => options.aiRuntime?.lastExternal,
+      );
     },
     search(embed, query, opts) {
       const name = resolveName(embed);
@@ -2029,6 +2149,9 @@ export function createFxContext(options: CreateFxOptions): FxContext {
         return [];
       });
     },
+    fetch(url, init) {
+      return loadFxFetch().runFxFetch(gated, url, init);
+    },
     run(agent, input) {
       const name = resolveName(agent);
       return gated("ask", name, async () => {

package/src/kernel/horizontal-child.ts

@@ -104,7 +104,7 @@ const signalRt = createSignalRuntime({
   durablePath: signalPath,
   leaseMs: Number.isFinite(leaseMs) ? leaseMs : 300,
 });
-const job = signal(SIG, { delivery: "once", retries: 3, deadLetter: true, optional: true });
+const job = signal.once(SIG, { retries: 3, deadLetter: true, optional: true });
 signalRt.register(job);
 const bus = await signalRt.start();
 await bus.subscribe(SIG, `consumer-${instanceId}`, async (msg) => {

package/src/kernel/http-query.test.ts

@@ -19,16 +19,14 @@ describe("http.query — RFC 10008", () => {
   test("a QUERY flow receives the JSON body exactly as POST does", async () => {
     const schema = z.object({ n: z.number() });
     on(
-      http.query("/q"),
+      http.query("/q", { in: schema }),
       flow("q.run", {
-        in: schema,
         do: (input: { n: number }) => input,
       }),
     );
     on(
-      http.post("/p"),
+      http.post("/p", { in: schema }),
       flow("p.run", {
-        in: schema,
         do: (input: { n: number }) => input,
       }),
     );
@@ -70,9 +68,8 @@ describe("http.query — RFC 10008", () => {
 describe("http.query — RFC 10008 media type", () => {
   function queryApp(aot = true) {
     on(
-      http.query("/q"),
+      http.query("/q", { in: z.object({ n: z.number() }) }),
       flow("q.run", {
-        in: z.object({ n: z.number() }),
         do: (input: { n: number }) => input,
       }),
     );

package/src/kernel/index.ts

@@ -91,6 +91,7 @@ export {
   recordEffect,
   reversibilityOf,
   type EffectEntry,
+  type EffectExternal,
   type EffectKind,
   type EffectLedger,
   type ReversibilityTier,
@@ -107,6 +108,7 @@ export {
   fail,
   formatOkeMessage,
   lookupOkeError,
+  OKE_ERROR_RANGES,
   OKE_ERRORS,
   OkeError,
   throwOke,
@@ -115,6 +117,7 @@ export {
   type FlowFailure,
   type OkeErrorCode,
   type OkeErrorDefinition,
+  type OkeErrorDomain,
   type OkeErrorParams,
 } from "./errors.ts";
 
@@ -133,6 +136,14 @@ export {
   type StandardSchemaV1,
 } from "./flow.ts";
 
+export { call } from "./call.ts";
+export type {
+  BoundaryContract,
+  InferBoundaryErrors,
+  InferBoundaryIn,
+  InferBoundaryOut,
+} from "./boundary-contract.ts";
+
 export {
   createFx,
   createFxContext,
@@ -346,15 +357,15 @@ export {
 
 export {
   asSignalTrigger,
-  every,
   http,
   internal,
+  isClockDecl,
   isResourceMount,
   isSignalTriggerSource,
   normalizeTrigger,
-  table,
   type BoundTriggerOf,
   type CdcTrigger,
+  type ClockTrigger,
   type EveryTrigger,
   type GateRef,
   type HttpMethod,
@@ -365,7 +376,6 @@ export {
   type ResourceMount,
   type SignalAsTrigger,
   type SignalSource,
-  type TableHandle,
   type Trigger,
   type TriggerKind,
 } from "./triggers.ts";

package/src/kernel/instance-id.ts

@@ -12,7 +12,7 @@ export const INSTANCE_ID_PREFIX = "inst-";
  * Mint a process instance id (`inst-<okid>`).
  */
 export function mintInstanceId(): string {
-  return `${INSTANCE_ID_PREFIX}${okid()}`;
+  return okid({ prefix: INSTANCE_ID_PREFIX });
 }
 
 /**

package/src/kernel/instances.test.ts

@@ -11,7 +11,9 @@ import { INSTANCE_ID_PREFIX } from "./instance-id.ts";
 import {
   createInstanceRuntime,
   createMemoryInstanceStore,
+  isBenignSqlDisconnect,
   projectInstancesList,
+  type InstanceStore,
 } from "./instances.ts";
 
 describe("projectInstancesList", () => {
@@ -64,6 +66,44 @@ describe("instance heartbeat", () => {
     expect(second?.heartbeatAt).toBe(1_100);
     expect(second?.startedAt).toBe(first?.startedAt);
   });
+
+  test("heartbeat swallows paused / connection-closed SQL errors", async () => {
+    const store: InstanceStore = {
+      kind: "memory",
+      async upsert() {
+        const err = new Error("shared Postgres pools are paused (compose stopped)");
+        (err as { code?: string; name?: string }).code = "ERR_OKE_POSTGRES_PAUSED";
+        (err as { name?: string }).name = "SharedPostgresPausedError";
+        throw err;
+      },
+      async get() {
+        return undefined;
+      },
+      async list() {
+        return [];
+      },
+      async listAlive() {
+        return [];
+      },
+      async remove() {},
+    };
+    const rt = createInstanceRuntime({
+      instanceId: "inst-pause",
+      store,
+      env: "dev",
+      heartbeatMs: 1,
+      leaseMs: 300,
+    });
+    await expect(rt.heartbeat()).resolves.toBeUndefined();
+  });
+});
+
+describe("isBenignSqlDisconnect", () => {
+  test("matches pause and Bun connection codes", () => {
+    expect(isBenignSqlDisconnect({ code: "ERR_OKE_POSTGRES_PAUSED" })).toBe(true);
+    expect(isBenignSqlDisconnect({ code: "ERR_POSTGRES_CONNECTION_CLOSED" })).toBe(true);
+    expect(isBenignSqlDisconnect(new Error("relation missing"))).toBe(false);
+  });
 });
 
 describe("boot instanceId unification", () => {

package/src/kernel/instances.ts

@@ -188,6 +188,38 @@ export interface InstanceRuntime {
   close(): Promise<void>;
 }
 
+/**
+ * SQL failures that are expected while `oke dev` pauses shared Postgres for
+ * compose stop (or the server is already gone). Scheduler ticks must not dump
+ * these as unhandled rejections.
+ *
+ * @param err - Rejection / throw
+ */
+export function isBenignSqlDisconnect(err: unknown): boolean {
+  if (!err || typeof err !== "object") return false;
+  const code = (err as { code?: unknown }).code;
+  if (typeof code === "string") {
+    if (
+      code === "ERR_OKE_POSTGRES_PAUSED" ||
+      code === "ERR_POSTGRES_CONNECTION_CLOSED" ||
+      code === "ERR_POSTGRES_CONNECTION_REFUSED" ||
+      code === "ERR_POSTGRES_CONNECTION_TIMEOUT"
+    ) {
+      return true;
+    }
+  }
+  const name = (err as { name?: unknown }).name;
+  if (name === "SharedPostgresPausedError") return true;
+  const message = (err as { message?: unknown }).message;
+  if (typeof message !== "string") return false;
+  return (
+    message === "Connection closed" ||
+    /shared Postgres pools are paused/i.test(message) ||
+    /Failed to connect/i.test(message) ||
+    /ECONNREFUSED/i.test(message)
+  );
+}
+
 /**
  * Create a heartbeat runtime for one process.
  *
@@ -214,15 +246,21 @@ export function createInstanceRuntime(options: CreateInstanceRuntimeOptions): In
     },
     async heartbeat(at) {
       const t = at ?? now();
-      await options.store.upsert({
-        id: options.instanceId,
-        startedAt,
-        heartbeatAt: t,
-        leaseExpiresAt: t + leaseMs,
-        env: options.env,
-        pid,
-      });
-      lastHeartbeatAt = t;
+      try {
+        await options.store.upsert({
+          id: options.instanceId,
+          startedAt,
+          heartbeatAt: t,
+          leaseExpiresAt: t + leaseMs,
+          env: options.env,
+          pid,
+        });
+        lastHeartbeatAt = t;
+      } catch (err) {
+        // Compose-stop pause / torn-down Postgres — skip until pools resume.
+        if (isBenignSqlDisconnect(err)) return;
+        throw err;
+      }
     },
     async release() {
       await options.store.remove(options.instanceId);