okengine 0.18.5 → 0.19.0

package/src/drivers/postgres.test.ts

@@ -1,9 +1,24 @@
 /**
- * Postgres placeholder conversion.
+ * Postgres placeholder conversion + shared pool lifecycle.
  */
 
-import { describe, expect, test } from "bun:test";
-import { toPostgresParams } from "./postgres.ts";
+import { afterEach, describe, expect, test } from "bun:test";
+import {
+  closeSharedPostgresClients,
+  connectPostgres,
+  isPostgresConnectionNoise,
+  isSharedPostgresPaused,
+  pauseSharedPostgresClients,
+  resumeSharedPostgresClients,
+  SharedPostgresPausedError,
+  sharedPostgresClient,
+  toPostgresParams,
+} from "./postgres.ts";
+
+afterEach(async () => {
+  resumeSharedPostgresClients();
+  await closeSharedPostgresClients();
+});
 
 describe("toPostgresParams", () => {
   test("rewrites ? only when values are bound", () => {
@@ -21,3 +36,59 @@ describe("toPostgresParams", () => {
     expect(toPostgresParams(sql, [])).toBe(sql);
   });
 });
+
+describe("closeSharedPostgresClients", () => {
+  test("drops cached pools so the next checkout is a new client", async () => {
+    const url = "postgres://127.0.0.1:9/oke-close-shared-test";
+    const first = sharedPostgresClient(url);
+    expect(sharedPostgresClient(url)).toBe(first);
+    await closeSharedPostgresClients();
+    const second = sharedPostgresClient(url);
+    expect(second).not.toBe(first);
+  });
+
+  test("holder close is a no-op so seed stop cannot leave a dead cached pool", async () => {
+    const url = "postgres://127.0.0.1:9/oke-holder-close-shared-test";
+    const first = sharedPostgresClient(url);
+    await first.close?.({ timeout: 1 });
+    // Same live pool — journal/instances close during in-process seed must not
+    // tear Bun.SQL while the map still hands out this client.
+    expect(sharedPostgresClient(url)).toBe(first);
+    await expect(first.close?.({ timeout: 1 })).resolves.toBeUndefined();
+  });
+});
+
+describe("pauseSharedPostgresClients", () => {
+  test("blocks new pools and fails soft on existing wrappers", async () => {
+    const url = "postgres://127.0.0.1:9/oke-pause-shared-test";
+    const sql = await connectPostgres({ url });
+    const held = sharedPostgresClient(url);
+    await pauseSharedPostgresClients();
+    expect(isSharedPostgresPaused()).toBe(true);
+    expect(() => sharedPostgresClient(url)).toThrow(SharedPostgresPausedError);
+    await expect(sql.query("SELECT 1")).rejects.toBeInstanceOf(SharedPostgresPausedError);
+    // Fleet wrappers (journal / clock / instances) call .unsafe on the held client.
+    expect(() => held.unsafe("SELECT 1")).toThrow(SharedPostgresPausedError);
+    resumeSharedPostgresClients();
+    expect(isSharedPostgresPaused()).toBe(false);
+    const next = sharedPostgresClient(url);
+    expect(next).toBeDefined();
+  });
+
+  test("isPostgresConnectionNoise matches Bun close / refuse codes", () => {
+    expect(
+      isPostgresConnectionNoise({
+        code: "ERR_POSTGRES_CONNECTION_CLOSED",
+        message: "Connection closed",
+      }),
+    ).toBe(true);
+    expect(
+      isPostgresConnectionNoise({
+        code: "ERR_POSTGRES_CONNECTION_REFUSED",
+        message: "Failed to connect",
+      }),
+    ).toBe(true);
+    expect(isPostgresConnectionNoise(new SharedPostgresPausedError())).toBe(true);
+    expect(isPostgresConnectionNoise(new Error("relation missing"))).toBe(false);
+  });
+});

package/src/drivers/postgres.ts

@@ -5,6 +5,7 @@
  */
 
 import type { SqlConnectOptions, SqlConnection, SqlDriver, SqlRole, SqlRow } from "./types.ts";
+import { hostFromUrl } from "./external.ts";
 
 /** Bun.SQL client checked out via {@link PostgresClientLike.reserve}. */
 export interface PostgresReservedClient extends PostgresClientLike {
@@ -36,7 +37,35 @@ export interface PostgresClientLike {
 /** Cap shared Bun.SQL pools so one process cannot outrun PgDog (default 10). */
 export const POSTGRES_POOL_MAX = 8;
 
-const sharedClients = new Map<string, PostgresClientLike>();
+/** One shared pool entry — raw Bun.SQL plus a pause-aware facade. */
+type SharedPostgresEntry = {
+  readonly raw: PostgresClientLike;
+  readonly guarded: PostgresClientLike;
+};
+
+const sharedClients = new Map<string, SharedPostgresEntry>();
+
+/**
+ * When true, shared pools stay closed and every query fails fast — no Bun.SQL
+ * reconnect into a torn-down Postgres (see {@link pauseSharedPostgresClients}).
+ */
+let sharedPostgresPaused = false;
+
+/**
+ * Thrown when Console / host code touches SQL after `oke dev` paused Postgres
+ * for compose stop. Fail soft — never open a new TCP connection.
+ */
+export class SharedPostgresPausedError extends Error {
+  readonly code = "ERR_OKE_POSTGRES_PAUSED";
+
+  /**
+   * @param message - Operator-facing reason
+   */
+  constructor(message = "shared Postgres pools are paused (compose stopped)") {
+    super(message);
+    this.name = "SharedPostgresPausedError";
+  }
+}
 
 /**
  * Resolve the Postgres URL (injected, `DATABASE_URL`, then localhost).
@@ -47,18 +76,145 @@ export function resolvePostgresUrl(url?: string): string {
   return url ?? process.env.DATABASE_URL ?? "postgres://localhost:5432/oke";
 }
 
+/**
+ * True while {@link pauseSharedPostgresClients} has not been resumed.
+ */
+export function isSharedPostgresPaused(): boolean {
+  return sharedPostgresPaused;
+}
+
+/**
+ * Bun / driver connection failures that flood the TTY when Postgres dies
+ * under an open pool (compose stop).
+ *
+ * @param reason - Rejection reason
+ */
+export function isPostgresConnectionNoise(reason: unknown): boolean {
+  if (reason instanceof SharedPostgresPausedError) return true;
+  if (!reason || typeof reason !== "object") return false;
+  const code = (reason as { code?: unknown }).code;
+  if (typeof code === "string") {
+    if (
+      code === "ERR_POSTGRES_CONNECTION_CLOSED" ||
+      code === "ERR_POSTGRES_CONNECTION_REFUSED" ||
+      code === "ERR_POSTGRES_CONNECTION_TIMEOUT" ||
+      code === "ERR_OKE_POSTGRES_PAUSED"
+    ) {
+      return true;
+    }
+  }
+  const message = (reason as { message?: unknown }).message;
+  if (typeof message !== "string") return false;
+  return (
+    message === "Connection closed" ||
+    /Failed to connect/i.test(message) ||
+    /ECONNREFUSED/i.test(message)
+  );
+}
+
+function assertSharedPostgresReady(): void {
+  if (sharedPostgresPaused) throw new SharedPostgresPausedError();
+}
+
+/**
+ * Pause-aware facade over a Bun.SQL client so journal / clock / instances /
+ * Console wrappers that call `.unsafe` directly cannot reconnect after pause.
+ *
+ * @param raw - Underlying Bun.SQL (or test fake)
+ */
+function guardSharedPostgresClient(raw: PostgresClientLike): PostgresClientLike {
+  const guarded: PostgresClientLike = {
+    unsafe(sql, values) {
+      assertSharedPostgresReady();
+      return raw.unsafe(sql, values);
+    },
+    async reserve() {
+      assertSharedPostgresReady();
+      if (typeof raw.reserve !== "function") {
+        throw new Error("postgres client needs reserve()");
+      }
+      const reserved = await raw.reserve();
+      const guardedReserved = guardSharedPostgresClient(reserved) as PostgresReservedClient;
+      return Object.assign(guardedReserved, {
+        release(): void {
+          reserved.release();
+        },
+      });
+    },
+    begin(fn) {
+      assertSharedPostgresReady();
+      if (typeof raw.begin !== "function") {
+        throw new Error("postgres client needs begin()");
+      }
+      return raw.begin((tx) => fn(guardSharedPostgresClient(tx)));
+    },
+    async close(): Promise<void> {
+      // Shared pools are process-owned ({@link closeSharedPostgresClients}).
+      // Journal / clock / instances / store holders must not tear down Bun.SQL
+      // or the map keeps a dead client — next checkout returns
+      // ERR_POSTGRES_CONNECTION_CLOSED (e.g. after in-process `oke db seed`
+      // stops the temporary app boot inside `oke dev`).
+    },
+  };
+  return guarded;
+}
+
 /**
  * One Bun.SQL pool per URL for store / journal / clock / vault / console.
  *
+ * Returns a pause-aware client — holders (including fleet store wrappers)
+ * fail soft after {@link pauseSharedPostgresClients} instead of reconnecting.
+ *
  * @param url - Connection URL
  */
 export function sharedPostgresClient(url?: string): PostgresClientLike {
+  assertSharedPostgresReady();
   const key = resolvePostgresUrl(url);
   const existing = sharedClients.get(key);
-  if (existing) return existing;
-  const created = new Bun.SQL(key, { max: POSTGRES_POOL_MAX }) as unknown as PostgresClientLike;
-  sharedClients.set(key, created);
-  return created;
+  if (existing) return existing.guarded;
+  const raw = new Bun.SQL(key, { max: POSTGRES_POOL_MAX }) as unknown as PostgresClientLike;
+  const guarded = guardSharedPostgresClient(raw);
+  sharedClients.set(key, { raw, guarded });
+  return guarded;
+}
+
+/**
+ * Close and drop every shared Bun.SQL pool.
+ *
+ * Prefer {@link pauseSharedPostgresClients} from `oke dev` — close alone does
+ * not stop Console from opening a fresh pool on the next poll.
+ */
+export async function closeSharedPostgresClients(): Promise<void> {
+  const clients = [...sharedClients.values()];
+  sharedClients.clear();
+  await Promise.all(
+    clients.map(async (entry) => {
+      try {
+        await entry.raw.close?.({ timeout: 1 });
+      } catch {
+        // Pool already closed / server already gone.
+      }
+    }),
+  );
+}
+
+/**
+ * Pause shared Postgres: block new pools, fail soft on existing wrappers, and
+ * close open clients.
+ *
+ * Used by `oke dev` **`x`** before `docker compose stop` so parent Console
+ * polls do not keep reconnecting into a torn-down Postgres/PgDog.
+ */
+export async function pauseSharedPostgresClients(): Promise<void> {
+  sharedPostgresPaused = true;
+  await closeSharedPostgresClients();
+}
+
+/**
+ * Allow shared pools again after compose is back ( `oke dev` **`u`** ).
+ */
+export function resumeSharedPostgresClients(): void {
+  sharedPostgresPaused = false;
 }
 
 /**
@@ -135,6 +291,7 @@ export async function connectPostgres(options: SqlConnectOptions = {}): Promise<
       : sharedPostgresClient(options.url));
   return wrapPostgresClient(client, role, {
     shared: injected === undefined && !dedicated,
+    ...(options.url !== undefined ? { url: options.url } : {}),
   });
 }
 
@@ -153,18 +310,29 @@ function dedicatedPostgresClient(url: string): PostgresClientLike {
 function wrapPostgresClient(
   client: PostgresClientLike,
   role: SqlRole,
-  opts: { readonly shared?: boolean; readonly pinned?: boolean } = {},
+  opts: {
+    readonly shared?: boolean;
+    readonly pinned?: boolean;
+    readonly url?: string;
+  } = {},
 ): SqlConnection {
+  const host = opts.url ? hostFromUrl(opts.url) : undefined;
   const connection: SqlConnection = {
     driverId: "postgres",
     role,
+    ...(host !== undefined
+      ? { external: { host, provider: "postgres", kind: "infrastructure" as const } }
+      : {}),
     async query(sql, params = []) {
+      // Shared wrappers outlive pause — fail soft before Bun.SQL reconnects.
+      if (opts.shared) assertSharedPostgresReady();
       const pg = toPostgresParams(sql, params);
       const result = await client.unsafe(pg, [...params]);
       if (Array.isArray(result)) return result as SqlRow[];
       return Array.from(result as ArrayLike<SqlRow>);
     },
     async exec(sql, params = []) {
+      if (opts.shared) assertSharedPostgresReady();
       const pg = toPostgresParams(sql, params);
       const result = await client.unsafe(pg, [...params]);
       if (
@@ -181,6 +349,7 @@ function wrapPostgresClient(
       return { changes: 0 };
     },
     async transaction(fn) {
+      if (opts.shared) assertSharedPostgresReady();
       if (opts.pinned) return fn(connection);
       return withPinnedPostgres(client, (tx) => fn(wrapPostgresClient(tx, role, { pinned: true })));
     },

package/src/drivers/signal-types.ts

@@ -150,7 +150,7 @@ export interface SignalReplayMessageResult {
 
 /** Irreversible effect intercepted during a dry-run replay. */
 export interface SignalDryRunStub {
-  readonly kind: "send" | "ask";
+  readonly kind: "send" | "ask" | "embed" | "fetch";
   readonly resource: string;
   readonly messageId?: string;
 }
@@ -201,7 +201,7 @@ export interface LiveEvent {
 export interface LiveSubscribeOptions {
   /**
    * Exclusive SSE cursor — replay events after this id, then continue.
-   * Omit for the full retained tape. Unknown / pruned ids throw OKE1014.
+   * Omit for the full retained tape. Unknown / pruned ids throw OKE1210.
    */
   readonly afterId?: string;
 }
@@ -332,7 +332,7 @@ export interface SignalBus {
    *
    * Replays retained history, then yields new events until the iterator
    * returns. `delivery` must be `"live"`. `afterId` skips through that
-   * id (exclusive); unknown or pruned ids throw OKE1014.
+   * id (exclusive); unknown or pruned ids throw OKE1210.
    *
    * @param signal - Signal name
    * @param opts - Optional resume cursor
@@ -341,7 +341,7 @@ export interface SignalBus {
   /**
    * Validate a live resume cursor without waiting for new events.
    *
-   * Prunes the tape first. Throws OKE1014 when `afterId` is absent.
+   * Prunes the tape first. Throws OKE1210 when `afterId` is absent.
    *
    * @param signal - Signal name
    * @param afterId - SSE cursor
@@ -399,7 +399,7 @@ export interface SignalDriver {
 /**
  * Validate an emit payload against the signal declaration's Standard Schema.
  *
- * @param name - Signal name (for OKE1043)
+ * @param name - Signal name (for OKE1250)
  * @param decl - Declared signal
  * @param payload - Raw emit payload
  */

package/src/drivers/types.ts

@@ -48,6 +48,11 @@ export interface SqlConnection {
   readonly driverId: "postgres" | "pglite" | "memory";
   /** Primary vs replica. */
   readonly role: SqlRole;
+  /**
+   * Egress identity when queries leave the process (remote Postgres).
+   * Omitted for in-process drivers (`pglite`, `memory`).
+   */
+  readonly external?: import("./external.ts").DriverExternal;
   /**
    * Run a parameterised query and return rows.
    *
@@ -338,6 +343,8 @@ export interface TextIndexSearchResult {
 /** Full-text index handle. */
 export interface TextIndexStore {
   readonly driverId: "meilisearch";
+  /** Egress identity for Meilisearch HTTP calls. */
+  readonly external?: import("./external.ts").DriverExternal;
   /**
    * Upsert a document.
    *

package/src/drivers/vault-types.ts

@@ -54,6 +54,11 @@ export interface VaultOpenOptions {
 export interface VaultBag {
   /** Protocol driver id. */
   readonly driverId: VaultDriverId;
+  /**
+   * Egress identity when the bag was opened / mutated over the network.
+   * Omitted for `env` / `memory` / injected managed bags.
+   */
+  readonly external?: import("./external.ts").DriverExternal;
   /**
    * Read a secret by name.
    *

package/src/elements/ai/declare.ts

@@ -13,6 +13,7 @@ import {
 } from "../../kernel/element-registries.ts";
 import { mcpToolRef, type McpToolRef } from "../../manifest/mcp-ref.ts";
 import type { VaultSecretDecl } from "../vault/declare.ts";
+import { formatAiProviderTier2Warn, resolveAiModelBaseUrl } from "./providers.ts";
 
 /** Budget for a prompt or agent. */
 export interface AiBudgetDecl {
@@ -27,14 +28,15 @@ export interface AiModelOptions {
   readonly model?: string;
   /**
    * Optional endpoint override for this logical binding (openai-compatible /
-   * ollama). Lets `fx.ask(…, { via: ["smart", "local"] })` reach cloud then
-   * local without sharing one process-wide base URL.
+   * local). When omitted and `provider` is a known OpenAI-compatible name,
+   * the verified registry base URL is filled in automatically. Explicit
+   * `baseUrl` always wins (self-hosted proxy / mirror).
    */
   readonly baseUrl?: string;
   /** Optional API key override for this binding (cloud providers). */
   readonly apiKey?: string;
   /**
-   * Protocol driver for this binding (`anthropic`, `ollama`, …).
+   * Protocol driver for this binding (`anthropic`, `openai-compatible`, …).
    * When omitted, the app-level default driver is used.
    */
   readonly driverId?: string;
@@ -260,13 +262,24 @@ export const ai: AiNamespace = {
    */
   model(name: string, options: AiModelOptions = {}): AiModelDecl {
     if (!name) throw new TypeError("ai.model: name is required");
+    const resolved = resolveAiModelBaseUrl({
+      ...(options.provider !== undefined ? { provider: options.provider } : {}),
+      ...(options.baseUrl !== undefined ? { baseUrl: options.baseUrl } : {}),
+      ...(options.driverId !== undefined ? { driverId: options.driverId } : {}),
+    });
+    if (resolved.tier2Caveat !== undefined && resolved.tier2Provider !== undefined) {
+      console.warn(
+        formatAiProviderTier2Warn(resolved.tier2Provider, resolved.tier2Caveat, "ai.model"),
+      );
+    }
+    const baseUrl = resolved.baseUrl;
     const decl: AiModelDecl = {
       kind: "model",
       name,
       ...(options.provider !== undefined ? { provider: options.provider } : {}),
       ...(options.tier !== undefined ? { tier: options.tier } : {}),
       ...(options.model !== undefined ? { model: options.model } : {}),
-      ...(options.baseUrl !== undefined ? { baseUrl: options.baseUrl } : {}),
+      ...(baseUrl !== undefined ? { baseUrl } : {}),
       ...(options.apiKey !== undefined ? { apiKey: options.apiKey } : {}),
       ...(options.driverId !== undefined ? { driverId: options.driverId } : {}),
       prompt(promptName, promptOpts = {}) {

package/src/elements/ai/eval.ts

@@ -126,7 +126,7 @@ export async function runPromptEvals(options: RunPromptEvalsOptions): Promise<Ev
 export function parseEvalJsonl(text: string): EvalCase[] {
   const jsonl = (Bun as typeof Bun & { JSONL?: { parse: (t: string) => unknown[] } }).JSONL;
   if (!jsonl) {
-    throw new Error("ai.eval: Bun.JSONL is required (Bun >= 1.4.0)");
+    throw new Error("ai.eval: Bun.JSONL is required (Bun >= 1.4.2)");
   }
   return jsonl.parse(text) as EvalCase[];
 }

package/src/elements/ai/mcp-http.ts

@@ -153,7 +153,7 @@ async function readSseJsonRpc(
 function responseTextStream(res: Response): AsyncIterable<string> {
   const stream = (res as Response & { textStream?: () => AsyncIterable<string> }).textStream;
   if (typeof stream !== "function") {
-    throw new Error("ai.mcp: Response.textStream is required (Bun >= 1.4.0)");
+    throw new Error("ai.mcp: Response.textStream is required (Bun >= 1.4.2)");
   }
   return stream.call(res);
 }

package/src/elements/ai/pii.ts

@@ -70,7 +70,7 @@ function isPiiTags(tags: ColumnClassification | string | readonly string[] | und
 function isThirdParty(provider: string | undefined): boolean {
   if (!provider) return true;
   const p = provider.toLowerCase();
-  return p !== "mock" && p !== "ollama" && p !== "local";
+  return p !== "mock" && p !== "local" && p !== "openai-compatible";
 }
 
 /**