okengine 0.22.0 → 0.23.1

package/src/compiler/extract.ts

@@ -28,6 +28,7 @@ import { SearchConfigError } from "../elements/store/search-errors.ts";
 import type {
   Ai,
   AiAgent,
+  AiDecision,
   AiMcpServer,
   AiModel,
   AiPrompt,
@@ -257,11 +258,18 @@ export async function extractManifest(options: ExtractManifestOptions = {}): Pro
   if (Object.keys(gates).length > 0) manifest.gates = gates;
   if (Object.keys(vault).length > 0) manifest.vault = vault;
   if (Object.keys(channels).length > 0) manifest.channels = channels;
-  if (scope.ai.models || scope.ai.prompts || scope.ai.agents || scope.ai.mcpServers) {
+  if (
+    scope.ai.models ||
+    scope.ai.prompts ||
+    scope.ai.agents ||
+    scope.ai.decisions ||
+    scope.ai.mcpServers
+  ) {
     manifest.ai = {
       ...(scope.ai.models ? { models: sortRecord(scope.ai.models) } : {}),
       ...(scope.ai.prompts ? { prompts: sortRecord(scope.ai.prompts) } : {}),
       ...(scope.ai.agents ? { agents: sortRecord(scope.ai.agents) } : {}),
+      ...(scope.ai.decisions ? { decisions: sortRecord(scope.ai.decisions) } : {}),
       ...(scope.ai.mcpServers ? { mcpServers: sortRecord(scope.ai.mcpServers) } : {}),
     };
   }
@@ -1426,7 +1434,11 @@ function visitDeclarationCall(call: CallExpression, program: AstNode, scope: Pro
     }
 
     if (obj === "ai" && prop === "agent") {
-      collectAgent(call, scope);
+      collectAgent(call, program, scope);
+    }
+
+    if (obj === "ai" && prop === "decision") {
+      collectDecision(call, program, scope);
     }
 
     if (obj === "ai" && prop === "mcpServer") {
@@ -1494,6 +1506,7 @@ function visitDeclarationCall(call: CallExpression, program: AstNode, scope: Pro
             : {}),
           ...(via && via.length > 0 ? { via } : {}),
           ...(timeout !== undefined ? { timeout } : {}),
+          ...(numberProp(opts, "repair") === 1 ? { repair: 1 as const } : {}),
         };
         scope.ai.prompts = scope.ai.prompts ?? {};
         scope.ai.prompts[promptName] = prompt;
@@ -1648,27 +1661,267 @@ function visitDeclarationCall(call: CallExpression, program: AstNode, scope: Pro
   }
 }
 
-function collectAgent(call: CallExpression, scope: ProjectScope): void {
+function agentToolEntry(
+  el: AstNode,
+  scope: ProjectScope,
+): { name: string; approval: boolean } | undefined {
+  if (el.type === "ObjectExpression") {
+    const nameNode = objectProp(el, "name");
+    const raw =
+      (nameNode ? resolveCallTarget(nameNode, scope.bindings) : undefined) ??
+      stringArg(nameNode) ??
+      identifierName(nameNode);
+    if (!raw) return undefined;
+    const name = scope.flowExports.get(raw) ?? scope.bindings.get(raw)?.ref ?? raw;
+    const approvalNode = objectProp(el, "approval");
+    return { name, approval: approvalNode !== undefined && boolProp(el, "approval") !== false };
+  }
+  const resolved = resolveCallTarget(el, scope.bindings);
+  const raw = resolved ?? identifierName(el) ?? stringArg(el);
+  if (!raw) return undefined;
+  const name = scope.flowExports.get(raw) ?? scope.bindings.get(raw)?.ref ?? raw;
+  return { name, approval: false };
+}
+
+function assertDecisionPlacement(flowName: string, flow: Flow, scope: ProjectScope): void {
+  const names = flow.effects?.decides ?? [];
+  if (names.length === 0) return;
+  const http = flow.trigger !== undefined && "http" in flow.trigger;
+  for (const decisionName of names) {
+    const decision = scope.ai.decisions?.[decisionName];
+    if (!decision || decision.mode !== "review") continue;
+    if (http) {
+      throw new Error(
+        `ai.decision("${decisionName}") review cannot run in HTTP flow "${flowName}" — a park answers 204. fx.emit a signal and decide in a consumer.`,
+      );
+    }
+    if (flow.durable !== true) {
+      throw new Error(
+        `ai.decision("${decisionName}"): flow "${flowName}" must set durable: true to review`,
+      );
+    }
+  }
+}
+
+function decisionReviewName(node: AstNode | undefined, scope: ProjectScope): string {
+  const literal = stringArg(node);
+  if (literal) return literal;
+  if (node?.type === "Identifier") {
+    const name = (node as Identifier).name;
+    return scope.gateIds.get(name) ?? name;
+  }
+  if (node?.type === "CallExpression") {
+    const arg = stringArg((node as CallExpression).arguments[0]);
+    if (arg) return arg;
+  }
+  if (node?.type === "MemberExpression") {
+    const member = node as AstNode & { property: AstNode; computed?: boolean };
+    if (member.property.type === "Identifier" && member.computed !== true) {
+      return (member.property as Identifier).name;
+    }
+  }
+  throw new Error("ai.decision: review gate name could not be resolved");
+}
+
+function assertDecisionQuestion(
+  decisionName: string,
+  key: string,
+  value: AstNode | undefined,
+  program: AstNode,
+): void {
+  const resolved = resolveDecisionExpr(value, program, decisionName, key);
+  if (!resolved || resolved.type !== "CallExpression") {
+    throw new Error(
+      `ai.decision("${decisionName}"): question "${key}" must be ai.choice, ai.score, or ai.boolean`,
+    );
+  }
+  const callee = (resolved as CallExpression).callee;
+  const member = callee as AstNode & { property?: AstNode };
+  const fn =
+    callee.type === "MemberExpression" && member.property?.type === "Identifier"
+      ? (member.property as Identifier).name
+      : undefined;
+  const args = (resolved as CallExpression).arguments;
+  if (fn === "choice") {
+    const options = args[1];
+    if (!options || options.type !== "ObjectExpression") {
+      throw new Error(
+        `ai.decision("${decisionName}"): choice "${key}" options must be an object literal`,
+      );
+    }
+    const keys = objectProperties(options)
+      .map((prop) => propKey(prop))
+      .filter((name): name is string => typeof name === "string");
+    if (keys.includes("none_of_these")) {
+      throw new Error(`ai.decision("${decisionName}"): choice "${key}" must not set none_of_these`);
+    }
+    if (keys.length > 254) {
+      throw new Error(
+        `ai.decision("${decisionName}"): choice "${key}" has ${keys.length} options; max 254`,
+      );
+    }
+  }
+  if (fn === "score") {
+    const levels = resolveScoreLevels(args[1], program, decisionName, key);
+    const count = ((levels as AstNode & { elements?: unknown[] }).elements ?? []).length;
+    if (count < 2 || count > 10) {
+      throw new Error(`ai.decision("${decisionName}"): score "${key}" needs 2–10 levels`);
+    }
+  }
+}
+
+function resolveDecisionExpr(
+  value: AstNode | undefined,
+  program: AstNode,
+  decisionName: string,
+  key: string,
+): AstNode | undefined {
+  if (!value) return undefined;
+  if (value.type !== "Identifier") return value;
+  const name = (value as Identifier).name;
+  const init = sameFileConstInit(name, program);
+  if (!init) {
+    throw new Error(
+      `ai.decision("${decisionName}"): question "${key}" is "${name}", which is not a same-file const`,
+    );
+  }
+  return init;
+}
+
+function resolveScoreLevels(
+  levels: AstNode | undefined,
+  program: AstNode,
+  decisionName: string,
+  key: string,
+): AstNode {
+  const resolved =
+    levels?.type === "Identifier"
+      ? sameFileConstInit((levels as Identifier).name, program)
+      : levels;
+  if (!resolved || resolved.type !== "ArrayExpression") {
+    const label = levels?.type === "Identifier" ? (levels as Identifier).name : "the levels";
+    throw new Error(
+      `ai.decision("${decisionName}"): score "${key}" levels (${label}) must be an array literal or a same-file const`,
+    );
+  }
+  return resolved;
+}
+
+function sameFileConstInit(name: string, program: AstNode): AstNode | undefined {
+  let found: AstNode | undefined;
+  walk(program, (node) => {
+    if (found || node.type !== "VariableDeclarator") return;
+    const decl = node as AstNode & { id?: AstNode; init?: AstNode };
+    if (decl.id?.type === "Identifier" && (decl.id as Identifier).name === name) {
+      found = decl.init;
+    }
+  });
+  return found;
+}
+
+function collectDecision(call: CallExpression, program: AstNode, scope: ProjectScope): void {
+  const decisionName = stringArg(call.arguments[0]);
+  const opts = objectArg(call.arguments[1]);
+  if (!decisionName || !opts) return;
+  const ask = objectProp(opts, "ask");
+  const questionProps = ask?.type === "ObjectExpression" ? objectProperties(ask) : [];
+  const questionNames = questionProps
+    .map((prop) => propKey(prop))
+    .filter((name): name is string => typeof name === "string" && name.length > 0);
+  if (questionNames.length === 0) {
+    throw new Error(`ai.decision("${decisionName}"): ask is empty`);
+  }
+  for (const prop of questionProps) {
+    const key = propKey(prop);
+    if (!key) continue;
+    if (key === "meta" || key === "$") {
+      throw new Error(`ai.decision("${decisionName}"): question id "${key}" is reserved`);
+    }
+    assertDecisionQuestion(
+      decisionName,
+      key,
+      (prop as AstNode & { value?: AstNode }).value,
+      program,
+    );
+  }
+  if (scope.ai.decisions?.[decisionName]) {
+    throw new Error(`ai.decision("${decisionName}"): duplicate decision name`);
+  }
+  const hasReview = objectProp(opts, "review") !== undefined;
+  const uncertain = stringProp(opts, "onUncertain");
+  const abstain = uncertain === "abstain";
+  if (hasReview === abstain) {
+    throw new Error(
+      `ai.decision("${decisionName}"): declare exactly one of review or onUncertain: "abstain"`,
+    );
+  }
+  const autonomyNode = objectProp(opts, "autonomy");
+  let autonomy: AiDecision["autonomy"];
+  if (autonomyNode?.type === "ObjectExpression") {
+    if (objectProp(autonomyNode, "audit") === undefined) {
+      throw new Error(`ai.decision("${decisionName}"): autonomy requires audit`);
+    }
+    const maxError = numberProp(autonomyNode, "maxError");
+    const audit = numberProp(autonomyNode, "audit");
+    const risk = numberProp(autonomyNode, "risk");
+    if (maxError === undefined || audit === undefined) {
+      throw new Error(`ai.decision("${decisionName}"): autonomy requires maxError and audit`);
+    }
+    autonomy = { maxError, audit, ...(risk !== undefined ? { risk } : {}) };
+  }
+  const evals = stringProp(opts, "evals");
+  const decision: AiDecision = {
+    mode: abstain ? "abstain" : "review",
+    questions: questionNames,
+    ...(hasReview ? { review: decisionReviewName(objectProp(opts, "review"), scope) } : {}),
+    ...(stringProp(opts, "model") ? { model: stringProp(opts, "model") } : {}),
+    driverId: stringProp(opts, "driverId") === "typesafe" ? "typesafe" : "openrouter",
+    ...(evals !== undefined ? { evals } : {}),
+    ...(autonomy !== undefined ? { autonomy } : {}),
+  };
+  scope.ai.decisions = scope.ai.decisions ?? {};
+  scope.ai.decisions[decisionName] = decision;
+  const bindingName = enclosingConstName(call, program);
+  if (bindingName) {
+    scope.bindings.set(bindingName, { kind: "decision", ref: decisionName });
+  }
+}
+
+function collectAgent(call: CallExpression, program: AstNode, scope: ProjectScope): void {
   const agentName = stringArg(call.arguments[0]);
   const opts = objectArg(call.arguments[1]);
   if (!agentName || !opts) return;
   const toolsArr = arrayProp(opts, "tools");
-  const tools = toolsArr
-    ?.map((el) => {
-      const resolved = resolveCallTarget(el, scope.bindings);
-      if (resolved) return resolved;
-      return identifierName(el) ?? stringArg(el);
-    })
-    .filter((x): x is string => typeof x === "string")
-    .map((id) => scope.flowExports.get(id) ?? scope.bindings.get(id)?.ref ?? id);
+  const entries = (toolsArr ?? [])
+    .map((el) => agentToolEntry(el, scope))
+    .filter((entry): entry is { name: string; approval: boolean } => entry !== undefined);
+  const tools = entries.map((entry) => entry.name);
+  const agentCalls = tools.filter(
+    (name) => scope.bindings.get(name)?.kind === "agent" || scope.ai.agents?.[name],
+  );
+  const approvals = Object.fromEntries(
+    entries.filter((entry) => entry.approval).map((entry) => [entry.name, true as const]),
+  );
   const agent: AiAgent = {
-    ...(tools && tools.length > 0 ? { tools } : {}),
+    ...(tools.length > 0 ? { tools } : {}),
+    ...(Object.keys(approvals).length > 0 ? { approvals } : {}),
     ...(numberProp(opts, "maxSteps") !== undefined
       ? { maxSteps: numberProp(opts, "maxSteps") }
       : {}),
+    ...(numberProp(opts, "maxDepth") !== undefined
+      ? { maxDepth: numberProp(opts, "maxDepth") }
+      : {}),
   };
   scope.ai.agents = scope.ai.agents ?? {};
   scope.ai.agents[agentName] = agent;
+  const bindingName = enclosingConstName(call, program);
+  if (bindingName) {
+    scope.bindings.set(bindingName, {
+      kind: "agent",
+      ref: agentName,
+      ...(agentCalls.length > 0 ? { agentCalls } : {}),
+    });
+  }
 }
 
 function collectMcpServer(call: CallExpression, program: AstNode, scope: ProjectScope): void {
@@ -1941,6 +2194,7 @@ function registerFlow(args: {
         flowName: name,
         file: args.file.path,
         resolveCallee: (callee, file) => args.scope.fxIndex.resolve(file, callee),
+        resolveFlowRef: (localName, file) => args.scope.fxIndex.flowRef(file, localName),
       })
     : {
         effects: {} as Effects,
@@ -1949,6 +2203,7 @@ function registerFlow(args: {
         cacheIneligible: false,
         nondeterministic: false,
         readsUserId: false,
+        bareIrreversible: [] as ("fetch" | "send")[],
       };
 
   let effects: Effects | undefined;
@@ -2009,7 +2264,16 @@ function registerFlow(args: {
   const line = lineAt(args.file.source, args.flowCall.start ?? 0);
   flow.source = `${args.file.path}:${line}`;
 
-  if (boolProp(opts, "durable")) flow.durable = true;
+  if (boolProp(opts, "durable")) {
+    flow.durable = true;
+    const bare = inferred.bareIrreversible[0];
+    if (bare !== undefined) {
+      throw new Error(
+        `OKE1901: durable flow "${name}" calls fx.${bare} outside fx.step. Wrap fx.fetch and fx.send in fx.step.`,
+      );
+    }
+  }
+  assertDecisionPlacement(name, flow, args.scope);
   if (typeof liveFromTrigger === "string") {
     flow.live = liveFromTrigger;
     // Manual live surface — `.live(tableBinding)` on the trigger. Synthesize
@@ -2908,6 +3172,7 @@ function parseEffectsObject(node: AstNode | undefined): Effects | undefined {
   const secrets = stringArrayProp(node, "secrets");
   const calls = stringArrayProp(node, "calls");
   const fetches = stringArrayProp(node, "fetches");
+  const decides = stringArrayProp(node, "decides");
   if (reads) effects.reads = reads as Effects["reads"];
   if (writes) effects.writes = writes as Effects["writes"];
   if (emits) effects.emits = emits;
@@ -2917,6 +3182,7 @@ function parseEffectsObject(node: AstNode | undefined): Effects | undefined {
   if (secrets) effects.secrets = secrets;
   if (calls) effects.calls = calls;
   if (fetches) effects.fetches = fetches;
+  if (decides) effects.decides = decides;
   return effects;
 }
 

package/src/compiler/fx-index.ts

@@ -26,6 +26,14 @@ export interface FxIndex {
    * @param callee - Call callee node
    */
   resolve(file: string, callee: AstNode): FxCalleeResolution;
+  /**
+   * Flow name behind an imported handle (`import { create as createTask }`).
+   * Absent when `localName` is not a named import of a `flow()` / `on()` export.
+   *
+   * @param file - File that contains the `fx.call`
+   * @param localName - Local binding (`createTask`)
+   */
+  flowRef(file: string, localName: string): string | undefined;
 }
 
 interface NamedImport {
@@ -61,6 +69,8 @@ interface FileFx {
   readonly functions: Map<string, AstNode>;
   readonly imports: Map<string, ImportBinding>;
   readonly exports: Map<string, LocalExport | Reexport>;
+  /** Local binding → `flow("name")` / `on(…, flow("name"))` literal. */
+  readonly flowNames: Map<string, string>;
 }
 
 const INTRINSIC_SOURCES: Readonly<
@@ -176,7 +186,29 @@ export function buildFxIndex(
     return resolveExport(target, imported.imported, seen);
   }
 
+  function flowExportName(file: string, exportName: string, seen: Set<string>): string | undefined {
+    const key = `${file}#flow:${exportName}`;
+    if (seen.has(key)) return undefined;
+    seen.add(key);
+    const indexed = byFile.get(file);
+    if (!indexed) return undefined;
+    const exported = indexed.exports.get(exportName);
+    if (!exported) return indexed.flowNames.get(exportName);
+    if (exported.kind === "local") return indexed.flowNames.get(exported.binding);
+    const target = resolveModule(file, exported.from);
+    if (!target) return undefined;
+    return flowExportName(target, exported.imported, seen);
+  }
+
   return {
+    flowRef(file, localName) {
+      const from = normalizePosix(file);
+      const imported = byFile.get(from)?.imports.get(localName);
+      if (!imported || imported.kind !== "named") return undefined;
+      const target = resolveModule(from, imported.from);
+      if (!target) return undefined;
+      return flowExportName(target, imported.imported, new Set());
+    },
     resolve(file, callee) {
       const from = normalizePosix(file);
       const seen = new Set<string>();
@@ -212,9 +244,10 @@ function indexFile(program: AstNode): FileFx {
   const functions = new Map<string, AstNode>();
   const imports = new Map<string, ImportBinding>();
   const exports = new Map<string, LocalExport | Reexport>();
+  const flowNames = new Map<string, string>();
   const body = (program as AstNode & { body?: AstNode[] }).body ?? [];
-  for (const stmt of body) indexStmt(stmt, functions, imports, exports);
-  return { functions, imports, exports };
+  for (const stmt of body) indexStmt(stmt, functions, imports, exports, flowNames);
+  return { functions, imports, exports, flowNames };
 }
 
 function indexStmt(
@@ -222,6 +255,7 @@ function indexStmt(
   functions: Map<string, AstNode>,
   imports: Map<string, ImportBinding>,
   exports: Map<string, LocalExport | Reexport>,
+  flowNames: Map<string, string>,
 ): void {
   if (stmt.type === "ImportDeclaration") {
     indexImport(stmt, imports);
@@ -232,7 +266,7 @@ function indexStmt(
     return;
   }
   if (stmt.type === "VariableDeclaration") {
-    rememberVars(stmt, functions, exports, false);
+    rememberVars(stmt, functions, exports, flowNames, false);
     return;
   }
   if (stmt.type === "ExportDefaultDeclaration") {
@@ -247,7 +281,7 @@ function indexStmt(
   const decl = (stmt as AstNode & { declaration?: AstNode | null }).declaration;
   const source = stringArg((stmt as AstNode & { source?: AstNode }).source);
   if (decl?.type === "FunctionDeclaration") rememberFunction(decl, functions, exports, true);
-  if (decl?.type === "VariableDeclaration") rememberVars(decl, functions, exports, true);
+  if (decl?.type === "VariableDeclaration") rememberVars(decl, functions, exports, flowNames, true);
   const specifiers = (stmt as AstNode & { specifiers?: AstNode[] }).specifiers ?? [];
   for (const spec of specifiers) {
     const local = exportedLocalName(spec);
@@ -309,6 +343,7 @@ function rememberVars(
   decl: AstNode,
   functions: Map<string, AstNode>,
   exports: Map<string, LocalExport | Reexport>,
+  flowNames: Map<string, string>,
   exportIt: boolean,
 ): void {
   const declarations = (decl as AstNode & { declarations?: AstNode[] }).declarations ?? [];
@@ -317,10 +352,29 @@ function rememberVars(
     if (!name) continue;
     const init = (item as AstNode & { init?: AstNode | null }).init;
     if (init && isFunctionNode(unwrapValue(init))) functions.set(name, unwrapValue(init));
+    const flowName = init ? flowLiteralName(unwrapValue(init)) : undefined;
+    if (flowName) flowNames.set(name, flowName);
     if (exportIt) exports.set(name, { kind: "local", binding: name });
   }
 }
 
+/**
+ * `flow("name")` / `call("name")` / `on(trigger, flow("name"))` literal.
+ *
+ * @param node - Initializer
+ */
+function flowLiteralName(node: AstNode): string | undefined {
+  if (node.type !== "CallExpression") return undefined;
+  const call = node as AstNode & { callee: AstNode; arguments?: AstNode[] };
+  const callee = identifierName(call.callee);
+  if (callee === "flow" || callee === "call") return stringArg(call.arguments?.[0]);
+  if (callee === "on") {
+    const body = call.arguments?.[1];
+    return body ? flowLiteralName(unwrapValue(body)) : undefined;
+  }
+  return undefined;
+}
+
 function exportedLocalName(spec: AstNode): string | undefined {
   return (
     identifierName((spec as AstNode & { local?: AstNode }).local) ??

package/src/compiler/response.ts

@@ -70,6 +70,11 @@ export function encodeFailure(failure: FlowFailure): Response {
   });
 }
 
+/** SSE id reader. Kept off the edge bundle until a stream chunk is encoded. */
+function loadSseId(): typeof import("../kernel/sse-id.ts") {
+  return lazyRequire(`${import.meta.dir}/../kernel`, ["sse", "id"].join("-"));
+}
+
 function loadFxLiveStream(): typeof import("../kernel/fx-live-stream.ts") {
   return lazyRequire(`${import.meta.dir}/../kernel`, ["fx", "live", "stream"].join("-"));
 }
@@ -133,6 +138,24 @@ export async function encodeExecuteResult(result: {
   return encodeSuccess(result.output);
 }
 
+/**
+ * Durable park thrown from a streamed agent after the interrupt frame.
+ *
+ * Duck-typed so this encoder does not import the journal module.
+ *
+ * @param err - Value thrown by the chunk iterator
+ */
+function isStreamPark(err: unknown): err is { readonly wakeAt: number; readonly label: string } {
+  return (
+    err instanceof Error &&
+    err.name === "JournalSuspend" &&
+    "wakeAt" in err &&
+    typeof err.wakeAt === "number" &&
+    "label" in err &&
+    typeof err.label === "string"
+  );
+}
+
 function encodeSseStream(carrier: JsonStreamResult): Response {
   const encoder = new TextEncoder();
   let finalized = false;
@@ -147,8 +170,12 @@ function encodeSseStream(carrier: JsonStreamResult): Response {
         for await (const chunk of carrier.chunks) {
           const frame = loadFxJson().isSseFrame(chunk)
             ? chunk
-            : { data: chunk as unknown, id: undefined as string | undefined };
+            : { data: chunk as unknown, id: loadSseId().readSseId(chunk) };
           const lines: string[] = [];
+          if ("comment" in frame && frame.comment && frame.data === undefined) {
+            controller.enqueue(encoder.encode(`: ${frame.comment}\n\n`));
+            continue;
+          }
           if (frame.id !== undefined) lines.push(`id: ${frame.id}`);
           lines.push(`data: ${JSON.stringify(frame.data)}`);
           controller.enqueue(encoder.encode(`${lines.join("\n")}\n\n`));
@@ -156,7 +183,13 @@ function encodeSseStream(carrier: JsonStreamResult): Response {
         controller.enqueue(encoder.encode("data: [DONE]\n\n"));
         controller.close();
       } catch (err) {
-        controller.error(err);
+        if (isStreamPark(err)) {
+          carrier.parked = { wakeAt: err.wakeAt, label: err.label };
+          controller.enqueue(encoder.encode("data: [DONE]\n\n"));
+          controller.close();
+        } else {
+          controller.error(err);
+        }
       } finally {
         await finish();
       }

package/src/config/index.ts

@@ -508,12 +508,30 @@ export function resolveDriverId(
   env: ConfigEnv,
   defaults?: EnvDriverMap,
 ): string | undefined {
+  return driverRefId(resolveDriverRef(map, env, defaults));
+}
+
+/**
+ * Resolve the rich driver ref for an env (`pool`, `replicas`, `url`).
+ *
+ * Same merge rules as {@link resolveDriverId}. A string pin has no pool or
+ * replicas. With `defaults`, an unset env key keeps that driver's default
+ * pin rather than a sibling environment.
+ *
+ * @param map - Env → driver map (or bare ref)
+ * @param env - Active environment
+ * @param defaults - Real default map for this specific driver (per-key merge)
+ */
+export function resolveDriverRef(
+  map: EnvDriverInput | undefined,
+  env: ConfigEnv,
+  defaults?: EnvDriverMap,
+): DriverRef | undefined {
   const normalized = normalizeEnvDriverMap(map);
   if (defaults) {
     const merged = mergeEnvDriverMap(normalized, defaults);
-    return driverRefId(merged[env]);
+    return merged[env];
   }
   if (!normalized) return undefined;
-  const ref = normalized[env] ?? normalized.dev ?? normalized.prod ?? normalized.test;
-  return driverRefId(ref);
+  return normalized[env] ?? normalized.dev ?? normalized.prod ?? normalized.test;
 }

package/src/console/index.ts

@@ -1,5 +1,5 @@
 /**
- * Console — operator plane UI + server (port 6533).
+ * Console — operator plane UI + server (port 6533). Public import: `okengine/console`.
  *
  * Built on `createClient<ConsoleApp>`. Every action is a real flow through `fx`;
  * the audit log is the trace (docs/spec/console.md).