okengine 0.21.1 → 0.23.0

package/src/kernel/app.ts

@@ -6,6 +6,7 @@
  * pipeline, and wires `fx.call` to untriggered (and triggered) flows.
  */
 
+import { bindAgentApprovalFlows } from "../elements/ai/approval-http.ts";
 import { compileRoute } from "../compiler/dynamic.ts";
 import type { CompiledRoute } from "../compiler/aot.ts";
 import { encodeExecuteResult, encodeFailure } from "../compiler/response.ts";
@@ -43,7 +44,7 @@ import { parseAcceptLanguage } from "../elements/channel/locale.ts";
 import { runWithLocale } from "../i18n/locale-context.ts";
 import { isFlow, type AnyFlowDef } from "./flow.ts";
 import { failureFromUnknown, runCompensationPhase } from "./compensate.ts";
-import { withAbortSignal } from "./abort-scope.ts";
+import { runDetached, withAbortSignal } from "./abort-scope.ts";
 import { withCdcMutationId } from "../elements/store/sql-session.ts";
 import { MUTATION_ID_HEADER } from "./mutation-id.ts";
 import { fxRetry } from "./concurrency.ts";
@@ -67,6 +68,7 @@ import {
 import { GATE_PUBLIC_NAME } from "../elements/gate/flatten.ts";
 import type { JsonCodeAuth } from "../runtime/json-code-block.ts";
 import { resolveDurationMs } from "./elapsed.ts";
+import { captureHttpFrame } from "./http-frame.ts";
 import { fail, throwOke, OkeError } from "./errors.ts";
 import { FLOW_NAME_DUPLICATE, FLOW_UNNAMED } from "./errors-flow-name.ts";
 import { ONCE_SIGNAL_MULTI_FLOW } from "./errors-once-signal.ts";
@@ -83,6 +85,7 @@ import {
 } from "./hooks.ts";
 import {
   createJournal,
+  createJournalSlot,
   createMemoryJournalStore,
   hasJournalLease,
   isJournalLeaseBusy,
@@ -91,6 +94,7 @@ import {
   type JournalSession,
   type JournalStore,
 } from "./journal.ts";
+import type { IdempotencyAttempt } from "./idempotency.ts";
 import { releaseInstanceLeases } from "./graceful-shutdown.ts";
 import { mintInstanceId } from "./instance-id.ts";
 import type { JournalRuntime } from "./boot-bind/journal.ts";
@@ -181,6 +185,11 @@ function loadFx(): {
   return lazyRequire(import.meta.dir, ["fx", "runtime"].join("-"));
 }
 
+/** Idempotency policy — off the edge graph until a request actually claims. */
+function loadIdempotency(): typeof import("./idempotency.ts") {
+  return lazyRequire(import.meta.dir, ["idem", "potency"].join(""));
+}
+
 /** App-shell tenancy wiring — loaded only when `gate.auth.tenant` is on. */
 function loadAppTenant(): { w: (kind: number, ...args: unknown[]) => unknown } {
   return lazyRequire(import.meta.dir, ["app", "tenant"].join("-"));
@@ -210,6 +219,39 @@ function loadClientDescriptor(): typeof import("./client-descriptor.ts") {
   return lazyRequire(import.meta.dir, ["client", "descriptor"].join("-"));
 }
 
+/** Decision HTTP flows. A static `import()` still lands on every HTTP bundle. */
+function loadDecisionBind(): typeof import("../elements/ai/decisions/bind.ts") {
+  return lazyRequire(`${import.meta.dir}/../elements/ai/decisions`, ["bi", "nd"].join(""));
+}
+
+/** Decision lockfile. Loaded only when the manifest declares decisions. */
+function loadDecisionCertificate(): typeof import("../elements/ai/decisions/certificate.ts") {
+  return lazyRequire(`${import.meta.dir}/../elements/ai/decisions`, ["certificate"].join(""));
+}
+
+/** Decision label opener. Loaded only when the manifest declares decisions. */
+function loadDecisionLabels(): typeof import("../elements/ai/decisions/labels.ts") {
+  return lazyRequire(`${import.meta.dir}/../elements/ai/decisions`, ["lab", "els"].join(""));
+}
+
+/** Drift-flag registration. Loaded only when the manifest declares decisions. */
+function loadDecisionLabelStore(): typeof import("./decision-label-store.ts") {
+  return lazyRequire(import.meta.dir, ["decision", "label", "store"].join("-"));
+}
+
+/** `fx.decide` gate hook. Loaded only when the manifest declares decisions. */
+function loadFxDecideModule(): typeof import("./fx-decide.ts") {
+  return lazyRequire(import.meta.dir, ["fx", "decide"].join("-"));
+}
+
+/**
+ * Full boot graph (drivers, elements). A static `import()` string is still
+ * bundled into every HTTP app; the stem stays computed.
+ */
+function loadBoot(): typeof import("./boot.ts") {
+  return lazyRequire(import.meta.dir, ["bo", "ot"].join(""));
+}
+
 /** Options for {@link oke}. */
 export interface OkeOptions {
   /** Application name (Manifest `app`). */
@@ -1088,6 +1130,8 @@ export function oke(options: OkeOptions): OkeApp {
   // contribute auth-method Bindings before traffic (plan Phase 2).
   const router: Router<Binding> = smart;
 
+  bindAgentApprovalFlows(adoptBinding);
+
   function adoptBinding(b: Binding): void {
     adopted.push(b);
     registerFlow(b.flow);
@@ -1108,6 +1152,24 @@ export function oke(options: OkeOptions): OkeApp {
 
   /** Once-per-app: system `_oke_search_embed_*` CDC bindings from Manifest. */
   let searchEmbedFlowsBound = false;
+  let decisionFlowsBound = false;
+
+  /**
+   * Register the decision aggregate, drift monitor, and candidate route
+   * when any decision declares autonomy.
+   *
+   * @param manifest - Boot manifest
+   */
+  async function ensureDecisionFlows(manifest: BootOptions["manifest"] | undefined): Promise<void> {
+    if (decisionFlowsBound || !manifest) return;
+    const { bindDecisionFlows, manifestHasDecisionAutonomy } = loadDecisionBind();
+    if (!manifestHasDecisionAutonomy(manifest)) {
+      decisionFlowsBound = true;
+      return;
+    }
+    bindDecisionFlows(adoptBinding, manifest);
+    decisionFlowsBound = true;
+  }
   /**
    * Auto-register hybrid-search embed CDC flows when any `.embed()` column
    * exists. Lazy-loads search-bind so edge graphs without search stay lean.
@@ -1332,6 +1394,19 @@ export function oke(options: OkeOptions): OkeApp {
             ...durableResumeFx(),
             ...(gateConfig.auth?.tenant ? (loadAppTenant().w(5, gateConfig.auth) as object) : {}),
             ...(existing?.tenant ? { tenant: { id: existing.tenant } } : {}),
+            callHandler: async (name, callInput) => {
+              const target = flowsByName.get(name);
+              if (!target) return undefined;
+              const inner = await execute(
+                target,
+                callInput,
+                { kind: "internal" } satisfies InternalTrigger,
+                { parentId: runId },
+              );
+              if (inner.failure) return inner.failure;
+              if (inner.ctx.error !== undefined) throw inner.ctx.error;
+              return inner.output;
+            },
           },
         });
       } catch (err) {
@@ -1360,7 +1435,7 @@ export function oke(options: OkeOptions): OkeApp {
   }
 
   async function doBoot(overrides?: Partial<BootOptions>): Promise<BootResult> {
-    const { bootApplication, resolveElementNeeds } = await import("./boot.ts");
+    const { bootApplication, resolveElementNeeds } = loadBoot();
     const { assertHttpGatePosture } = await import("../elements/gate/boot.ts");
     const { assertPluginNeeds, buildAvailableNeedTokens } = await import("./plugin-needs.ts");
     const dockerFlag =
@@ -1381,6 +1456,7 @@ export function oke(options: OkeOptions): OkeApp {
     }
 
     const unguardedHttp = overrides?.unguardedHttp ?? gateConfig.unguardedHttp ?? "deny";
+    await ensureDecisionFlows(overrides?.manifest ?? options.manifest);
     // Auth bindings are in `adopted` — missing posture fails with GateBootError.
     assertHttpGatePosture(adopted, { unguardedHttp, env: bootEnv });
 
@@ -1550,6 +1626,26 @@ export function oke(options: OkeOptions): OkeApp {
     // Built-in hybrid search — auto-register durable embed CDC flows when the
     // Manifest declares any `.embed()` column (writer flows stay embed-free).
     await ensureSearchEmbedFlows(overrides?.manifest ?? options.manifest);
+    const decisionManifest = overrides?.manifest ?? options.manifest;
+    const declaredDecisions = decisionManifest?.ai?.decisions;
+    if (declaredDecisions && Object.keys(declaredDecisions).length > 0) {
+      const { loadDecisionLockfile, setDecisionDrift } = loadDecisionCertificate();
+      const { openDecisionLabelStore } = loadDecisionLabels();
+      const { setDeclaredDriftDecisions } = loadDecisionLabelStore();
+      const { setDecisionGateAllow } = loadFxDecideModule();
+      const root = overrides?.rootDir ?? options.rootDir ?? process.env["OKE_ROOT_DIR"];
+      if (!root) {
+        throw new Error(
+          "oke boot: decisions are declared but rootDir and OKE_ROOT_DIR are unset, so the decision lockfile cannot load.",
+        );
+      }
+      await loadDecisionLockfile(root);
+      setDeclaredDriftDecisions(Object.keys(declaredDecisions));
+      if (result.journal && result.journal.store.decisions) {
+        await openDecisionLabelStore(result.journal.store, setDecisionDrift);
+      }
+      if (result.gate) setDecisionGateAllow((names, ctx) => result.gate!.allow(names, ctx));
+    }
     // otp() provider / app mode capability — fail loud at boot, never silent downgrade.
     if (result.channel) {
       const { assertOtpPluginCapability } = await import("../auth/otp-capability.ts");
@@ -1837,23 +1933,61 @@ export function oke(options: OkeOptions): OkeApp {
       );
 
       capability = booted.capabilities.get(flowDef.name);
-
-      if (flowDef.durable) {
-        const { store, instanceId, leaseMs } = activeJournal();
-        const journal = createJournal({
-          store,
-          now,
-          id: () => runId,
-          // Hold the run lease for the request's lifetime — a crash mid-run
-          // leaves an expired lease another instance can reclaim and resume.
-          ...(hasJournalLease(store) ? { lease: { instanceId, leaseMs } } : {}),
-        });
-        journalSession = await journal.start(flowDef.name, input);
-        inflightRuns.add(journalSession.runId);
-      }
     }
 
     const effects = flowDef.effects ?? capability?.declared;
+    const requestForIdem = extras?.request;
+    const rawIdemHeader = requestForIdem?.headers.get("idempotency-key") ?? null;
+    const idemRequired =
+      flowDef.idempotency === "required" ||
+      (typeof flowDef.idempotency === "object" && flowDef.idempotency.required === true) ||
+      flowDef.resolvedIdempotency?.mode === "required";
+    let idemAttempt: IdempotencyAttempt | undefined;
+    if (requestForIdem && (rawIdemHeader !== null || idemRequired)) {
+      const method = trigger.kind === "http" ? trigger.method : requestForIdem.method;
+      const live =
+        flowDef.live !== undefined || (trigger.kind === "http" && trigger.liveSignal !== undefined);
+      idemAttempt = loadIdempotency().prepareIdempotencyAttempt({
+        hasRequest: true,
+        method,
+        stream: flowDef.stream === true,
+        live,
+        effects,
+        usesRaw: flowDef.usesRaw === true,
+        option: flowDef.idempotency,
+        resolved: flowDef.resolvedIdempotency,
+        header: rawIdemHeader,
+      });
+    }
+    const claiming = idemAttempt?.claiming === true;
+
+    const openJournal = (): ReturnType<typeof createJournal> => {
+      const { store, instanceId, leaseMs } = activeJournal();
+      return createJournal({
+        store,
+        now,
+        id: () => runId,
+        // Hold the run lease for the request's lifetime — a crash mid-run
+        // leaves an expired lease another instance can reclaim and resume.
+        ...(hasJournalLease(store) ? { lease: { instanceId, leaseMs } } : {}),
+      });
+    };
+
+    // A claim starts the journal only after it wins, so a replay or a 409
+    // does not open a run. Auto with no header keeps the start here.
+    if (booted && flowDef.durable && !claiming) {
+      journalSession = await openJournal().start(flowDef.name, input);
+      inflightRuns.add(journalSession.runId);
+    }
+
+    let journalSlot: { session?: JournalSession } | undefined;
+    let journalFacade: JournalSession | undefined;
+    if (booted && flowDef.durable && claiming) {
+      const created = createJournalSlot();
+      journalSlot = created.slot;
+      journalFacade = created.facade;
+    }
+    const journalForFx = journalSession ?? journalFacade;
     const { fx, ledger } = loadFx().createFxContext({
       ...options.fx,
       flow: flowDef.name,
@@ -1906,7 +2040,7 @@ export function oke(options: OkeOptions): OkeApp {
           }
         : {}),
       runsRuntime: booted?.runs ?? (isRunsRuntimeLike(options.runs) ? options.runs : undefined),
-      ...(journalSession ? { journal: journalSession, durable: true } : {}),
+      ...(journalForFx ? { journal: journalForFx, durable: true } : {}),
       callHandler: async (name, callInput) => {
         const target = flowsByName.get(name);
         if (!target) {
@@ -2038,13 +2172,141 @@ export function oke(options: OkeOptions): OkeApp {
             }
             return output;
           };
+          const runClaimed = async (validated: unknown): Promise<unknown> => {
+            if (!claiming || idemAttempt === undefined) return invoke(validated);
+            const policy = loadIdempotency();
+            const classified = policy.classifyIdempotencyKey(rawIdemHeader);
+            if (classified === "missing") {
+              return policy.idempotencyErrorResponse("IdempotencyKeyMissing");
+            }
+            if (classified === "invalid") {
+              return policy.idempotencyErrorResponse("IdempotencyKeyInvalid");
+            }
+            const idemStore = activeJournal().store.idempotency;
+            if (!idemStore) return invoke(validated);
+            const scope = {
+              tenant: fx.tenant.id ?? "",
+              principal: policy.idempotencyPrincipal(fx.auth),
+              flow: flowDef.name,
+              key: classified,
+            };
+            const claimToken = crypto.randomUUID();
+            const leaseMs = activeJournal().leaseMs;
+            const claimed = await idemStore.claim({
+              scope,
+              fingerprint: policy.idempotencyFingerprint(flowDef.name, validated),
+              claimToken,
+              now: now(),
+              leaseMs,
+              ttlMs: idemAttempt.ttlMs,
+            });
+            if (claimed.kind === "mismatch") {
+              return policy.idempotencyErrorResponse("IdempotencyKeyReused");
+            }
+            if (claimed.kind === "in_progress") {
+              return policy.idempotencyErrorResponse(
+                "IdempotencyInProgress",
+                claimed.retryAfterSeconds,
+              );
+            }
+            if (claimed.kind === "replay") return policy.replayResponse(claimed.row);
+
+            if (booted && flowDef.durable) {
+              const journal = openJournal();
+              const resumeId = claimed.kind === "reclaimed" ? claimed.row.runId : undefined;
+              try {
+                const session = resumeId
+                  ? await journal.resume(resumeId)
+                  : await journal.start(flowDef.name, validated);
+                if (journalSlot) journalSlot.session = session;
+                journalSession = session;
+                inflightRuns.add(session.runId);
+                const tenantId = principals?.tenant.id ?? fx.tenant.id;
+                if (tenantId) await session.stampTenant(tenantId);
+                await idemStore.attachRun(scope, claimToken, session.runId);
+              } catch (err) {
+                if (isJournalLeaseBusy(err)) {
+                  await idemStore.forfeit(scope, claimToken);
+                  return policy.idempotencyErrorResponse("IdempotencyInProgress", 1);
+                }
+                await idemStore.remove(scope, claimToken);
+                throw err;
+              }
+            }
+
+            const timer = setInterval(
+              () => {
+                void idemStore.renew(scope, claimToken, now() + leaseMs);
+              },
+              Math.max(5, Math.floor(leaseMs / 3)),
+            );
+            if (typeof timer === "object" && timer !== null && "unref" in timer) timer.unref();
+
+            const storeEncoded = async (encoded: {
+              readonly status: number;
+              readonly headers: { get(name: string): string | null };
+              text(): Promise<string>;
+            }): Promise<void> => {
+              const stored = await policy.storedFromResponse(encoded);
+              if (!stored) {
+                await idemStore.remove(scope, claimToken);
+                return;
+              }
+              await idemStore.complete(scope, claimToken, stored, journalSession?.runId);
+            };
+            try {
+              const output = await runDetached(() => invoke(validated));
+              if (loadFx().isJsonStreamResult(output)) {
+                await idemStore.remove(scope, claimToken);
+                return output;
+              }
+              if (output instanceof Response) {
+                const contentType = output.headers.get("content-type") ?? "";
+                const buffered =
+                  output.status === 204 ||
+                  contentType.includes("json") ||
+                  contentType.startsWith("text/");
+                if (!buffered || contentType.includes("text/event-stream")) {
+                  await idemStore.remove(scope, claimToken);
+                  return output;
+                }
+                await storeEncoded(output.clone());
+                return output;
+              }
+              await storeEncoded(
+                await encodeExecuteResult({
+                  output: isFlowFailure(output) ? undefined : output,
+                  failure: isFlowFailure(output) ? output : undefined,
+                }),
+              );
+              return output;
+            } catch (err) {
+              if (flowDef.durable && isJournalSuspend(err)) {
+                await idemStore.complete(
+                  scope,
+                  claimToken,
+                  { status: 204, body: "" },
+                  journalSession?.runId,
+                );
+                throw err;
+              }
+              if (policy.attemptedMutation(ledger.entries) || idemAttempt.usesRaw) {
+                await storeEncoded(encodeFailure(fail("InternalError", {})));
+              } else {
+                await idemStore.remove(scope, claimToken);
+              }
+              throw err;
+            } finally {
+              clearInterval(timer);
+            }
+          };
           if (!alreadyValidated) {
             const parsed = await validate(flowDef.in, ctx.input);
             if (!parsed.ok) return parsed.failure;
             ctx.input = parsed.value;
-            return await invoke(parsed.value);
+            return await runClaimed(parsed.value);
           }
-          return await invoke(ctx.input);
+          return await runClaimed(ctx.input);
         } catch (err) {
           if (isFlowFailure(err)) return err;
           // A durable sleep that has not yet elapsed suspends the run — this
@@ -2084,6 +2346,14 @@ export function oke(options: OkeOptions): OkeApp {
         : durationMs;
       if (journalSession) {
         inflightRuns.delete(journalSession.runId);
+        const parked = streamOut?.parked;
+        if (parked) {
+          ctx.state.sleeping = {
+            wakeAt: parked.wakeAt,
+            label: parked.label,
+            runId: journalSession.runId,
+          };
+        }
         const sleeping = ctx.state.sleeping as
           | { readonly wakeAt: number; readonly label: string; readonly runId: string }
           | undefined;
@@ -2104,6 +2374,8 @@ export function oke(options: OkeOptions): OkeApp {
             fx,
             error: terminalErr,
           });
+        } else if (parked && sleeping) {
+          await journalSession.commit("sleeping", { wakeAt: sleeping.wakeAt });
         } else if (!sleeping) {
           await journalSession.commit("completed", {
             output: streamOut ? { streamed: true } : result.output,
@@ -2136,6 +2408,9 @@ export function oke(options: OkeOptions): OkeApp {
               ? { output: streamOut ? { streamed: true } : result.output }
               : {}),
             ...(parentId !== undefined ? { parentId } : {}),
+            ...(trigger.kind === "http" && extras?.request
+              ? { http: captureHttpFrame(extras.request, result.response) }
+              : {}),
           },
           archiveCleartext,
         );

package/src/kernel/auto-cache.test.ts

@@ -58,7 +58,7 @@ describe("automatic tier-1 cache from effects", () => {
       stores: [db],
       gate: { policies: [gate.public] },
     }).adopt({ list });
-    const t = await createTestApp(app);
+    const t = await createTestApp(app, { capability: "open" });
     const notesApi = requireNotesApi(t);
 
     const first = await notesApi.list({});
@@ -90,7 +90,7 @@ describe("automatic tier-1 cache from effects", () => {
       stores: [db],
       gate: { policies: [gate.public] },
     }).adopt({ list });
-    const t = await createTestApp(app);
+    const t = await createTestApp(app, { capability: "open" });
     const trigger = list.triggers[0];
     if (trigger === undefined) throw new Error("notes.list has no trigger");
 
@@ -128,7 +128,7 @@ describe("automatic tier-1 cache from effects", () => {
       stores: [db],
       gate: { policies: [gate.public] },
     }).adopt({ list });
-    const t = await createTestApp(app);
+    const t = await createTestApp(app, { capability: "open" });
     const notesApi = requireNotesApi(t);
     await notesApi.list({});
     await notesApi.list({});
@@ -158,7 +158,7 @@ describe("automatic tier-1 cache from effects", () => {
       stores: [db],
       gate: { policies: [gate.public] },
     }).adopt({ list });
-    const t = await createTestApp(app);
+    const t = await createTestApp(app, { capability: "open" });
     const notesApi = requireNotesApi(t);
 
     await notesApi.list({});
@@ -209,7 +209,7 @@ describe("automatic tier-1 cache from effects", () => {
       stores: [db],
       gate: { policies: [gate.public] },
     }).adopt({ list, create });
-    const t = await createTestApp(app);
+    const t = await createTestApp(app, { capability: "open" });
     const notesApi = requireNotesApi(t);
 
     await notesApi.list({});
@@ -251,7 +251,7 @@ describe("automatic tier-1 cache from effects", () => {
       stores: [db],
       gate: { policies: [gate.public] },
     }).adopt({ list, create });
-    const t = await createTestApp(app);
+    const t = await createTestApp(app, { capability: "open" });
     const notesApi = requireNotesApi(t);
 
     await notesApi.list({});

package/src/kernel/boot-bind/ai.ts

@@ -14,6 +14,7 @@ import type { AiDriver, AiOpenOptions } from "../../drivers/ai-types.ts";
 import { createAiRuntime, type AiRuntime } from "../../elements/ai.ts";
 import type { GateRuntime } from "../../elements/gate.ts";
 import type { VaultRuntime } from "../../elements/vault.ts";
+import type { JournalStore } from "../journal.ts";
 import type { BootOptions } from "../boot.ts";
 
 /**
@@ -33,6 +34,7 @@ export function bindAi(
   env: ConfigEnv = "test",
   docker = false,
   vault?: VaultRuntime,
+  journalStore?: JournalStore,
 ): AiRuntime {
   const id = resolveAiDriverId(options, env, docker);
   const driver =
@@ -48,6 +50,7 @@ export function bindAi(
     },
     gates: options.ai?.gates ?? gate,
     now,
+    ...(journalStore ? { journalStore } : {}),
   });
 }
 

package/src/kernel/boot-bind/store.test.ts

@@ -13,6 +13,7 @@ import {
   resolveIndexDriverId,
   resolveKvDriverId,
   resolveSqlDriverId,
+  sqlBindingForDecl,
 } from "./store.ts";
 
 describe("bindStore driver resolution", () => {
@@ -99,6 +100,31 @@ describe("bindStore driver resolution", () => {
   });
 });
 
+describe("sqlBindingForDecl", () => {
+  test("pool.max and replica URLs land on the binding; min is ignored", () => {
+    const binding = sqlBindingForDecl("db", "postgres://primary/db", {
+      driver: "postgres",
+      pool: { max: 20, min: 2 },
+      replicas: ["postgres://ro-1/db", "postgres://ro-2/db"],
+    });
+    expect(binding).toEqual({
+      name: "db",
+      primary: { url: "postgres://primary/db", pool: { max: 20 } },
+      replicas: [
+        { url: "postgres://ro-1/db", pool: { max: 20 } },
+        { url: "postgres://ro-2/db", pool: { max: 20 } },
+      ],
+    });
+  });
+
+  test("a string pin keeps the URL and omits pool and replicas", () => {
+    expect(sqlBindingForDecl("db", "memory://", "memory")).toEqual({
+      name: "db",
+      primary: { url: "memory://" },
+    });
+  });
+});
+
 describe("bindStore durable KV routing", () => {
   const prev = {
     redis: process.env.REDIS_URL,

package/src/kernel/boot-bind/store.ts

@@ -2,7 +2,14 @@
  * Lazy store binder — loaded only when Store is declared.
  */
 
-import { resolveDomainDdlMode, resolveDriverId, type ConfigEnv } from "../../config/index.ts";
+import {
+  driverRefId,
+  resolveDomainDdlMode,
+  resolveDriverId,
+  resolveDriverRef,
+  type ConfigEnv,
+  type DriverRef,
+} from "../../config/index.ts";
 import {
   STORE_FILES_DEFAULTS,
   STORE_KV_DEFAULTS,
@@ -18,6 +25,7 @@ import { redisDriver } from "../../drivers/redis.ts";
 import { s3Driver } from "../../drivers/s3.ts";
 import type { FilesDriver, IndexDriver, KvDriver, SqlDriver } from "../../drivers/types.ts";
 import { createStoreRuntime, type StoreRuntime } from "../../elements/store.ts";
+import type { SqlRuntimeBinding } from "../../elements/store/runtime.ts";
 import type { StoreDecl } from "../../elements/store/declare.ts";
 import { emitBootWarn } from "../../runtime/boot-warn.ts";
 import type { BootOptions } from "../boot.ts"; // type-only — no cycle at runtime
@@ -129,17 +137,15 @@ export function bindStore(
     warnKvMemoryDurable(durableKvDecls.map((d) => d.name));
   }
 
-  const sqlBindings: Record<string, { name: string; primary: { url: string } }> = {};
+  const sqlRef = resolveSqlDriverRef(options, env, docker);
+  const sqlBindings: Record<string, SqlRuntimeBinding> = {};
   const kvBindings: Record<string, { url?: string }> = {};
   const filesBindings: Record<string, { root?: string }> = {};
   const indexBindings: Record<string, { url?: string; apiKey?: string }> = {};
 
   for (const decl of options.stores ?? []) {
     if (isSqlDecl(decl)) {
-      sqlBindings[decl.name] = {
-        name: decl.name,
-        primary: { url: sqlUrl },
-      };
+      sqlBindings[decl.name] = sqlBindingForDecl(decl.name, sqlUrl, sqlRef);
     } else if (isKvDecl(decl)) {
       if (decl.durable === true) {
         kvBindings[decl.name] = {};
@@ -210,6 +216,76 @@ export function resolveSqlDriverId(options: BootOptions, env: ConfigEnv, docker:
   return resolveDriverId(options.config?.drivers?.store?.sql, env, STORE_SQL_DEFAULTS)!;
 }
 
+/**
+ * Rich SQL driver ref for the active env. A docker `OKE_SQL_DRIVER` override
+ * that changes the protocol drops `pool` / `replicas` — those belong to the
+ * configured driver, not the override.
+ *
+ * @param options - Boot options
+ * @param env - Active environment
+ * @param docker - Docker mode
+ */
+function resolveSqlDriverRef(
+  options: BootOptions,
+  env: ConfigEnv,
+  docker: boolean,
+): DriverRef | undefined {
+  const configured = resolveDriverRef(options.config?.drivers?.store?.sql, env, STORE_SQL_DEFAULTS);
+  const fromEnv = process.env.OKE_SQL_DRIVER?.trim();
+  if (docker && fromEnv && fromEnv !== driverRefId(configured)) return fromEnv;
+  return configured;
+}
+
+/**
+ * Primary URL plus documented `pool.max` and read-replica URLs.
+ *
+ * `pool.min` is ignored — Bun.SQL has no minimum pool size. Unset `max`
+ * leaves pool sizing to the postgres driver default of 8.
+ *
+ * @param name - Store declaration name
+ * @param url - Primary connection URL
+ * @param ref - Active driver pin (string or rich object)
+ */
+export function sqlBindingForDecl(
+  name: string,
+  url: string,
+  ref: DriverRef | undefined,
+): SqlRuntimeBinding {
+  const max = driverPoolMax(ref);
+  const pool = max !== undefined ? { pool: { max } } : {};
+  const replicas = driverReplicaUrls(ref).map((replicaUrl) => ({
+    url: replicaUrl,
+    ...pool,
+  }));
+  return {
+    name,
+    primary: { url, ...pool },
+    ...(replicas.length > 0 ? { replicas } : {}),
+  };
+}
+
+/**
+ * Positive finite `pool.max` from a rich driver ref.
+ *
+ * @param ref - Driver pin
+ */
+function driverPoolMax(ref: DriverRef | undefined): number | undefined {
+  if (ref === undefined || typeof ref === "string") return undefined;
+  const max = ref.pool?.max;
+  if (typeof max !== "number" || !Number.isFinite(max) || max < 1) return undefined;
+  return Math.floor(max);
+}
+
+/**
+ * Replica connection strings from a rich driver ref. Non-strings are dropped.
+ *
+ * @param ref - Driver pin
+ */
+function driverReplicaUrls(ref: DriverRef | undefined): readonly string[] {
+  if (ref === undefined || typeof ref === "string" || ref.replicas === undefined) return [];
+  return ref.replicas.filter((item): item is string => typeof item === "string" && item.length > 0);
+}
+
 /**
  * @param options - Boot options
  * @param env - Active env