okengine 0.21.0 → 0.22.0

package/src/kernel/app.ts

@@ -17,7 +17,6 @@ import {
   type RoutesFromNamespace,
   type RuntimeRouteMap,
 } from "./adopt-routes.ts";
-import { buildClientDescriptor } from "./client-descriptor.ts";
 import { liveExposureKey, liveGatesKey, liveMatchKeyFromPath } from "./live-http.ts";
 // `./boot.ts` pulls in every element + driver module (vault, store, signal,
 // clock, gate, channel, ai, runs) — a type-only import here keeps that whole
@@ -44,7 +43,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";
@@ -84,6 +83,7 @@ import {
 } from "./hooks.ts";
 import {
   createJournal,
+  createJournalSlot,
   createMemoryJournalStore,
   hasJournalLease,
   isJournalLeaseBusy,
@@ -92,6 +92,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";
@@ -182,6 +183,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("-"));
@@ -203,6 +209,14 @@ function loadJsonCodeBlock(): typeof import("../runtime/json-code-block.ts") {
   return lazyRequire(`${import.meta.dir}/../runtime`, ["json", "code", "block"].join("-"));
 }
 
+/**
+ * Route descriptor for `GET /_oke/client.json`.
+ * A static import evaluates Zod on every HTTP cold start; load it on first fetch.
+ */
+function loadClientDescriptor(): typeof import("./client-descriptor.ts") {
+  return lazyRequire(import.meta.dir, ["client", "descriptor"].join("-"));
+}
+
 /** Options for {@link oke}. */
 export interface OkeOptions {
   /** Application name (Manifest `app`). */
@@ -1830,23 +1844,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,
@@ -1899,7 +1951,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) {
@@ -2031,13 +2083,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
@@ -2381,7 +2561,7 @@ export function oke(options: OkeOptions): OkeApp {
       }
 
       if (method === "GET" && url.pathname === "/_oke/client.json") {
-        const descriptor = buildClientDescriptor(routes, flowsByName);
+        const descriptor = loadClientDescriptor().buildClientDescriptor(routes, flowsByName);
         return respond(
           new Response(JSON.stringify(descriptor), {
             headers: { "content-type": "application/json" },

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/vault.ts

@@ -51,6 +51,7 @@ export async function bindVault(options: BootOptions, env: ConfigEnv): Promise<V
       env,
       cwd: process.cwd(),
       seed: {},
+      ...(options.config?.vault?.audit === undefined ? {} : { audit: options.config.vault.audit }),
     });
   const vault = createVaultRuntime({
     secrets: vaultSecrets,

package/src/kernel/boot.ts

@@ -601,6 +601,15 @@ export async function bootApplication(input: BootOptions = {}): Promise<BootResu
     docker,
   });
 
+  const needsIdempotencyJournal = (options.flows ?? []).some((f) => {
+    const mode = f.resolvedIdempotency?.mode;
+    return mode === "auto" || mode === "required";
+  });
+  if (!journal && needsIdempotencyJournal) {
+    journalBind ??= await loadBind<JournalBind>("journal");
+    journal = (await journalBind.bindJournal(options, env)).journal;
+  }
+
   // 9. `.adopt()` barrel freshness — opt-in only (same `rootDir` gate as
   // capability minting above; never a filesystem read the kernel performs
   // on its own).
@@ -712,7 +721,12 @@ export async function mintCapabilities(
 
   let manifest = options.manifest;
   let extractError: string | undefined;
-  const needsManifest = manifest === undefined && flows.some((f) => f.effects === undefined);
+  const needsManifest =
+    manifest === undefined &&
+    flows.some(
+      (f) =>
+        f.effects === undefined || (f.idempotency !== false && f.resolvedIdempotency === undefined),
+    );
   if (needsManifest) {
     const rootDir = options.rootDir ?? process.env["OKE_ROOT_DIR"];
     if (rootDir) {
@@ -723,6 +737,10 @@ export async function mintCapabilities(
   }
 
   for (const f of flows) {
+    const manifestFlow = manifest?.flows?.[f.name];
+    if (manifestFlow?.idempotency) f.resolvedIdempotency = manifestFlow.idempotency;
+    if (manifestFlow?.usesRaw === true) f.usesRaw = true;
+
     if (f.effects !== undefined) {
       map.set(f.name, createCapabilityToken(f.name, f.effects));
       continue;

package/src/kernel/builtin-errors.ts

@@ -21,6 +21,10 @@ export const BUILTIN_ERROR_STATUS = {
   AuthFailed: 400,
   InternalError: 500,
   ServiceUnavailable: 503,
+  IdempotencyKeyMissing: 400,
+  IdempotencyKeyInvalid: 400,
+  IdempotencyKeyReused: 422,
+  IdempotencyInProgress: 409,
 } as const;
 
 /** Built-in error code (including `DatabaseError`). */
@@ -86,6 +90,10 @@ export type BuiltinErrorMap = {
   };
   readonly InternalError: Record<string, never>;
   readonly ServiceUnavailable: { readonly retryAfter?: number };
+  readonly IdempotencyKeyMissing: Record<string, never>;
+  readonly IdempotencyKeyInvalid: Record<string, never>;
+  readonly IdempotencyKeyReused: Record<string, never>;
+  readonly IdempotencyInProgress: { readonly retryAfter?: number };
 };
 
 /**

package/src/kernel/client-descriptor.test.ts

@@ -0,0 +1,78 @@
+/**
+ * Client descriptor printing — schema type strings are cached per object.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { z } from "zod";
+import type { AnyFlowDef } from "./flow.ts";
+import type { RuntimeRouteMap } from "./adopt-routes.ts";
+import { buildClientDescriptor } from "./client-descriptor.ts";
+
+const FLOW_COUNT = 64;
+
+function fieldSchema() {
+  return z.object({
+    id: z.string().uuid(),
+    title: z.string().min(1).max(120),
+    tags: z.array(z.string()),
+    count: z.number().int().nonnegative(),
+  });
+}
+
+function fixture(): {
+  routes: RuntimeRouteMap;
+  flows: Map<string, AnyFlowDef>;
+} {
+  const routes: RuntimeRouteMap = { app: {} };
+  const flows = new Map<string, AnyFlowDef>();
+  for (let i = 0; i < FLOW_COUNT; i++) {
+    const name = `flow${i}`;
+    routes.app![name] = { method: "GET", path: `/${name}` };
+    flows.set(`app.${name}`, {
+      in: fieldSchema(),
+      out: z.object({
+        id: z.string(),
+        title: z.string(),
+        createdAt: z.iso.datetime(),
+      }),
+    } as AnyFlowDef);
+  }
+  return { routes, flows };
+}
+
+describe("schemaToTsString cache", () => {
+  test("a second pass over the same schema objects skips reprinting them", () => {
+    const { routes, flows } = fixture();
+
+    const coldStart = performance.now();
+    const cold = buildClientDescriptor(routes, flows);
+    const coldMs = performance.now() - coldStart;
+
+    const warmStart = performance.now();
+    const warm = buildClientDescriptor(routes, flows);
+    const warmMs = performance.now() - warmStart;
+
+    expect(warm).toEqual(cold);
+    expect(cold.routes.app?.flow0?.in).toContain("title");
+    // Uncached toJSONSchema is the whole map. A cache hit is the map lookup.
+    expect(warmMs).toBeLessThan(coldMs / 4);
+    console.log(
+      `client descriptor ${FLOW_COUNT} flows cold=${coldMs.toFixed(1)}ms warm=${warmMs.toFixed(1)}ms`,
+    );
+
+    const previous = flows.get("app.flow0");
+    flows.set("app.flow0", {
+      in: z.object({ id: z.string(), extra: z.boolean() }),
+      out: previous?.out,
+    } as AnyFlowDef);
+
+    const touchedStart = performance.now();
+    const touched = buildClientDescriptor(routes, flows);
+    const touchedMs = performance.now() - touchedStart;
+
+    expect(touched.routes.app?.flow0?.in).toContain("extra");
+    expect(touched.routes.app?.flow1?.in).toBe(warm.routes.app?.flow1?.in);
+    expect(touchedMs).toBeLessThan(coldMs / 4);
+    console.log(`client descriptor one schema replaced=${touchedMs.toFixed(1)}ms`);
+  });
+});

package/src/kernel/client-descriptor.ts

@@ -9,6 +9,15 @@ import type { AnyFlowDef } from "./flow.ts";
 import type { RuntimeRouteMap } from "./adopt-routes.ts";
 import { z } from "zod";
 
+/**
+ * Printed type string per schema object.
+ *
+ * A flows-tree reload replaces the schema objects of the modules that
+ * actually changed. Every other flow keeps the same reference and hits
+ * this map instead of running `toJSONSchema` again.
+ */
+const schemaTsCache = new WeakMap<object, string>();
+
 /**
  * Build a client descriptor from runtime routes + flow defs (type strings + stamps).
  *
@@ -47,6 +56,7 @@ export function buildClientDescriptor(
         ...(stamp.stream === true ? { stream: true as const } : {}),
         ...(stamp.matchKey !== undefined ? { matchKey: stamp.matchKey } : {}),
         ...(stamp.gates !== undefined && stamp.gates.length > 0 ? { gates: stamp.gates } : {}),
+        ...(def?.resolvedIdempotency !== undefined ? { idempotency: def.resolvedIdempotency } : {}),
       };
     }
     out[unit] = unitOut;
@@ -62,6 +72,20 @@ export function buildClientDescriptor(
  */
 export function schemaToTsString(schema: unknown): string {
   if (schema === undefined || schema === null) return "unknown";
+  if (typeof schema !== "object" && typeof schema !== "function") return "unknown";
+  const cached = schemaTsCache.get(schema);
+  if (cached !== undefined) return cached;
+  const printed = printSchemaToTs(schema);
+  schemaTsCache.set(schema, printed);
+  return printed;
+}
+
+/**
+ * Convert one schema object to a TypeScript type string. Uncached.
+ *
+ * @param schema - Object or function schema
+ */
+function printSchemaToTs(schema: object): string {
   try {
     if (hasToJSONSchema(schema)) {
       return jsonSchemaToTs(schema.toJSONSchema());

package/src/kernel/concurrency.test.ts

@@ -90,6 +90,39 @@ describe("fx.race — structured concurrency", () => {
   test("empty race throws", async () => {
     await expect(fxRace([])).rejects.toThrow(/empty/);
   });
+
+  test("a gated effect does not start after the branch is aborted", async () => {
+    const { fx } = createFxContext({
+      flow: "t",
+      effects: { reads: ["sql:notes"] },
+    });
+    const store = fx.store("sql:notes") as { get(key: string): Promise<unknown> };
+    let sawAbort = false;
+
+    const winner = await fx.race([
+      async () => {
+        await new Promise<void>((resolve) => {
+          const signal = fx.signal;
+          if (signal.aborted) {
+            resolve();
+            return;
+          }
+          signal.addEventListener("abort", () => resolve(), { once: true });
+        });
+        try {
+          await store.get("n1");
+        } catch (err) {
+          sawAbort = isAbortError(err);
+        }
+        return "slow";
+      },
+      async () => "fast",
+    ]);
+
+    expect(winner).toBe("fast");
+    await new Promise((r) => setTimeout(r, 20));
+    expect(sawAbort).toBe(true);
+  });
 });
 
 describe("fx.using — scoped cleanup", () => {

package/src/kernel/effects-stamping.test.ts

@@ -71,7 +71,7 @@ describe("boot-level: undeclared-effects flow, no manifest / rootDir", () => {
     const create = buildUnannotatedCreateFlow(db);
     const app = oke({ name: "stamp-open", gate: { policies: [gate.public] } }).adopt({ create });
     Object.assign(app.$options, { stores: [db] });
-    await createTestApp(app); // createTestApp always boots env: "test"
+    await createTestApp(app, { capability: "open" });
 
     const res = await app.fetch(
       new Request("http://localhost/notes", {
@@ -157,7 +157,7 @@ describe("boot-level: table-ref resolution stays backward compatible", () => {
       create,
     });
     Object.assign(app.$options, { stores: [db] });
-    await createTestApp(app);
+    await createTestApp(app, { capability: "open" });
 
     const res = await app.fetch(
       new Request("http://localhost/notes", {

package/src/kernel/errors-compiler.ts

@@ -0,0 +1,20 @@
+/**
+ * OKE1900 — kept off the kernel edge profile.
+ *
+ * Effect inference throws a plain `Error` (`OKE1900` in the message) from
+ * `okengine/compiler`. This definition is registry-only so the compiler
+ * chunk does not import the kernel error module.
+ */
+
+import type { OkeErrorDefinition } from "./errors.ts";
+
+/**
+ * A Flow hides `fx` from effect inference, or an explicit `effects` block
+ * omits an effect the walk can see.
+ */
+export const FX_INFERENCE_OPAQUE: OkeErrorDefinition = {
+  code: 1900,
+  domain: "compiler",
+  cause: 'Flow "{flow}" hides fx from effect inference ({detail}).',
+  fix: "Name the parameter fx, keep chain aliases in the same function, and include every effect inference can see. An effects block may add keys; it cannot omit keys inference can see.",
+};