okengine 0.21.1 → 0.22.0

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

@@ -56,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;

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.",
+};

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

@@ -85,6 +85,42 @@ describe("fx.fetch", () => {
       globalThis.fetch = originalFetch;
     }
   });
+
+  test("fx.race aborts an in-flight fx.fetch", async () => {
+    const originalFetch = globalThis.fetch;
+    let signal: AbortSignal | undefined;
+    globalThis.fetch = (async (_input: unknown, init?: RequestInit) => {
+      signal = init?.signal ?? undefined;
+      return new Promise<Response>((_resolve, reject) => {
+        const onAbort = (): void => {
+          reject(new DOMException("aborted", "AbortError"));
+        };
+        if (init?.signal?.aborted) {
+          onAbort();
+          return;
+        }
+        init?.signal?.addEventListener("abort", onAbort, { once: true });
+      });
+    }) as typeof fetch;
+    try {
+      const { fx } = createFxContext({
+        flow: "stripe.pull",
+        effects: { fetches: ["api.stripe.com"] },
+      });
+      const winner = await fx.race([
+        () => fx.fetch("https://api.stripe.com/v1/charges").then(() => "slow"),
+        async () => {
+          await new Promise((r) => setTimeout(r, 10));
+          return "fast" as const;
+        },
+      ]);
+      expect(winner).toBe("fast");
+      await new Promise((r) => setTimeout(r, 15));
+      expect(signal?.aborted).toBe(true);
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
 });
 
 describe("Channel failover — winning provider on EffectEntry", () => {

package/src/kernel/flow.ts

@@ -54,6 +54,16 @@ export interface FlowOptions<I = unknown, O = unknown> {
    * (`"30s"`) adds a TTL on top of write invalidation.
    */
   readonly cache?: boolean | string;
+  /**
+   * HTTP `Idempotency-Key` handling.
+   * Omitted is auto: the header is honored on an eligible mutating flow.
+   * `"required"` rejects a missing header. `false` ignores the header.
+   * A TTL string (`"24h"`) overrides the 24 hour default.
+   */
+  readonly idempotency?:
+    | false
+    | "required"
+    | { readonly required?: boolean; readonly ttl?: string };
   /** Declared service-level objective. */
   readonly slo?: Slo;
   /**
@@ -168,6 +178,19 @@ export interface FlowDef<
   readonly liveCustomMatch: boolean;
   /** Cache option. */
   readonly cache: boolean | string | undefined;
+  /** Author idempotency option. */
+  readonly idempotency:
+    | false
+    | "required"
+    | { readonly required?: boolean; readonly ttl?: string }
+    | undefined;
+  /**
+   * Extracted idempotency stamp. Boot copies this from the Manifest.
+   * Runtime resolves it when extract has not run.
+   */
+  resolvedIdempotency?: { readonly mode: "off" | "auto" | "required"; readonly ttl: string };
+  /** True when extract saw `fx.raw`. A throw then completes the idempotency row. */
+  usesRaw?: boolean;
   /** SLO. */
   readonly slo: Slo | undefined;
   /** Plane (user vs operator). */
@@ -305,6 +328,7 @@ export function flow(
     live: undefined,
     liveCustomMatch: false,
     cache: options.cache,
+    idempotency: options.idempotency,
     slo: options.slo,
     plane: options.plane,
     breaking: false,

package/src/kernel/fx-fetch.ts

@@ -5,6 +5,7 @@
 
 import type { EffectExternal } from "./effects.ts";
 import { isDryRun, recordWouldHaveFired } from "./dry-run.ts";
+import { requestSignal } from "./abort-scope.ts";
 
 /**
  * Hostname for `fx.fetch` capability / ledger resource.
@@ -48,7 +49,10 @@ export function runFxFetch(gated: Gated, url: string | URL, init?: RequestInit):
         recordWouldHaveFired("fetch", host);
         return new Response(null, { status: 204 });
       }
-      return globalThis.fetch(url, init);
+      return globalThis.fetch(url, {
+        ...init,
+        signal: requestSignal(init?.signal),
+      });
     },
     { host, kind: "third-party" },
   );

package/src/kernel/fx.ts

@@ -62,7 +62,7 @@ import {
   touchDryRunStore,
 } from "./dry-run.ts";
 import type { FailFn } from "./errors.ts";
-import { currentAbortSignal, linkAbort } from "./abort-scope.ts";
+import { abortError, currentAbortSignal, linkAbort } from "./abort-scope.ts";
 import type { FxRetryOptions, FxThunk } from "./concurrency.ts";
 import { maskRedactedDeep, Redacted } from "./redacted.ts";
 import type { JournalSession, JournalStepOptions } from "./journal.ts";
@@ -1201,6 +1201,8 @@ export function createFxContext(options: CreateFxOptions): FxContext {
       | EffectExternal
       | ((result: T | undefined, error: unknown) => EffectExternal | undefined),
   ): Promise<T> {
+    const signal = currentAbortSignal();
+    if (signal.aborted) throw abortError(signal.reason);
     capability.assert(kind, resource);
     const execute = () => recordEffect(ledger, kind, resource, now, body, externalOf);
     if (journal) {
@@ -1511,6 +1513,8 @@ export function createFxContext(options: CreateFxOptions): FxContext {
    * @param body - Work to run under the gate
    */
   async function gatedSecret<T>(name: string, body: () => T | Promise<T>): Promise<T> {
+    const signal = currentAbortSignal();
+    if (signal.aborted) throw abortError(signal.reason);
     capability.assert("secret", name);
     const timestamp = now();
     const t0 = performance.now();