okengine 0.10.2 → 0.11.0

package/src/kernel/journal.ts

@@ -14,7 +14,49 @@ import { JournalSuspend } from "./journal-suspend.ts";
 export { JournalSuspend, isJournalSuspend } from "./journal-suspend.ts";
 
 /** Status of a durable run. */
-export type JournalRunStatus = "running" | "sleeping" | "completed" | "failed";
+export type JournalRunStatus = "running" | "sleeping" | "compensating" | "completed" | "failed";
+
+/** Reserved prefix for compensation undo steps — never use for forward work. */
+export const JOURNAL_UNDO_PREFIX = "undo:";
+
+/**
+ * Options for {@link JournalSession.step}.
+ *
+ * @typeParam T - Step result type
+ */
+export interface JournalStepOptions<T> {
+  /**
+   * Durable undo for this step — registered on persist and replay.
+   * Invoked with the journaled value on terminal failure (LIFO).
+   */
+  readonly undo?: (value: T) => unknown | Promise<unknown>;
+}
+
+/** One registered per-step undo frame (in-memory; closures re-bound on resume). */
+export interface JournalUndoFrame {
+  /** Forward step name (without {@link JOURNAL_UNDO_PREFIX}). */
+  readonly name: string;
+  /** Journaled step value passed to {@link undo}. */
+  readonly value: unknown;
+  /** Undo body. */
+  readonly undo: (value: unknown) => unknown | Promise<unknown>;
+}
+
+/**
+ * Thrown during a compensating registration pass when `do` would execute
+ * new forward work — stops re-entry without continuing the happy path.
+ */
+export class JournalRegistrationComplete extends Error {
+  constructor() {
+    super("journal: registration pass complete");
+    this.name = "JournalRegistrationComplete";
+  }
+}
+
+/** Type guard for {@link JournalRegistrationComplete}. */
+export function isJournalRegistrationComplete(err: unknown): err is JournalRegistrationComplete {
+  return err instanceof JournalRegistrationComplete;
+}
 
 /** A completed named step. */
 export interface JournalStepEntry {
@@ -98,8 +140,8 @@ export interface JournalLeaseStore {
    */
   claimDueSleep(instanceId: string, now: number, leaseMs: number): Promise<JournalRun | undefined>;
   /**
-   * Boot-time orphan discovery: `running` / `sleeping` runs with no live lease
-   * (crashed holder or never claimed). Rows are never deleted.
+   * Boot-time orphan discovery: `running` / `sleeping` / `compensating` runs
+   * with no live lease (crashed holder or never claimed). Rows are never deleted.
    *
    * @param now - Epoch-ms
    */
@@ -212,7 +254,11 @@ function leaseMethods(
     async listOrphans(now) {
       const map = await load();
       return [...map.values()]
-        .filter((r) => (r.status === "running" || r.status === "sleeping") && !hasLiveLease(r, now))
+        .filter(
+          (r) =>
+            (r.status === "running" || r.status === "sleeping" || r.status === "compensating") &&
+            !hasLiveLease(r, now),
+        )
         .map(cloneRun);
     },
   };
@@ -325,8 +371,9 @@ export interface JournalSession {
    *
    * @param name - Step name
    * @param fn - Step body
+   * @param opts - Optional per-step undo registration
    */
-  step<T>(name: string, fn: () => T | Promise<T>): Promise<T>;
+  step<T>(name: string, fn: () => T | Promise<T>, opts?: JournalStepOptions<T>): Promise<T>;
   /**
    * Durable sleep — journals wake time; suspends until elapsed.
    *
@@ -346,9 +393,25 @@ export interface JournalSession {
   /**
    * Rewind the replay cursor to the start of the entry list.
    * Used by flow-level retry so a re-entered `do` replays completed steps
-   * instead of treating the cursor as past them.
+   * instead of treating the cursor as past them. Clears the in-memory undo stack
+   * so frames re-bind on the next walk.
    */
   rewind(): void;
+  /** Registered per-step undos in persist/replay order (LIFO compensate). */
+  undoStack(): readonly JournalUndoFrame[];
+  /**
+   * Enter registration-only mode — replay + re-bind undos; new forward work
+   * throws {@link JournalRegistrationComplete}.
+   */
+  beginRegistrationPass(): void;
+  /** Exit registration-only mode. */
+  endRegistrationPass(): void;
+  /**
+   * Allow appending `undo:*` steps (compensation phase only).
+   *
+   * @param allowed - Whether undo-prefix steps may append
+   */
+  setUndoExecution(allowed: boolean): void;
   /** Persist current run status / output. */
   commit(
     status: JournalRunStatus,
@@ -389,6 +452,9 @@ export function createJournal(options: CreateJournalOptions): Journal {
     /** Next entry index to consume on replay. */
     let cursor = 0;
     let leaseHeld = leased;
+    let registrationPass = false;
+    let undoExecution = false;
+    const undos: JournalUndoFrame[] = [];
 
     async function persist(): Promise<void> {
       run.updatedAt = now();
@@ -407,18 +473,53 @@ export function createJournal(options: CreateJournalOptions): Journal {
       delete run.leaseExpiresAt;
     }
 
+    function registerUndo<T>(name: string, value: T, opts?: JournalStepOptions<T>): void {
+      if (!opts?.undo) return;
+      const undo = opts.undo as (value: unknown) => unknown | Promise<unknown>;
+      const idx = undos.findIndex((f) => f.name === name);
+      const frame: JournalUndoFrame = { name, value, undo };
+      if (idx >= 0) undos[idx] = frame;
+      else undos.push(frame);
+    }
+
+    function assertCanAppendStep(name: string): void {
+      if (registrationPass) {
+        throw new JournalRegistrationComplete();
+      }
+      const isUndoStep = name.startsWith(JOURNAL_UNDO_PREFIX);
+      if (isUndoStep && !undoExecution) {
+        throw new Error(
+          `journal: step name "${name}" uses reserved prefix "${JOURNAL_UNDO_PREFIX}"`,
+        );
+      }
+      if (!isUndoStep && run.entries.some((e) => e.kind === "step" && e.name === name)) {
+        throw new Error(`journal: duplicate step name "${name}"`);
+      }
+    }
+
     return {
       runId: run.id,
       run,
-      async step<T>(name: string, fn: () => T | Promise<T>): Promise<T> {
+      async step<T>(
+        name: string,
+        fn: () => T | Promise<T>,
+        opts?: JournalStepOptions<T>,
+      ): Promise<T> {
+        if (name.startsWith(JOURNAL_UNDO_PREFIX) && opts?.undo) {
+          throw new Error("journal: undo steps cannot register nested undo");
+        }
         // Prefer name match among remaining entries (resume after crash).
         for (let i = cursor; i < run.entries.length; i++) {
           const e = run.entries[i]!;
           if (e.kind === "step" && e.name === name) {
             cursor = i + 1;
+            if (!name.startsWith(JOURNAL_UNDO_PREFIX)) {
+              registerUndo(name, e.value as T, opts);
+            }
             return e.value as T;
           }
         }
+        assertCanAppendStep(name);
         const value = await fn();
         const entry: JournalStepEntry = {
           kind: "step",
@@ -429,6 +530,9 @@ export function createJournal(options: CreateJournalOptions): Journal {
         run.entries.push(entry);
         cursor = run.entries.length;
         await persist();
+        if (!name.startsWith(JOURNAL_UNDO_PREFIX)) {
+          registerUndo(name, value, opts);
+        }
         return value;
       },
       async sleep(label, duration, parseMs) {
@@ -446,6 +550,9 @@ export function createJournal(options: CreateJournalOptions): Journal {
             return;
           }
         }
+        if (registrationPass) {
+          throw new JournalRegistrationComplete();
+        }
         const wakeAt = now() + parseMs(duration);
         const entry: JournalSleepEntry = {
           kind: "sleep",
@@ -477,6 +584,9 @@ export function createJournal(options: CreateJournalOptions): Journal {
             return e.value as T;
           }
         }
+        if (registrationPass) {
+          throw new JournalRegistrationComplete();
+        }
         const value = await execute();
         const entry: JournalEffectEntry = {
           kind: "effect",
@@ -492,6 +602,19 @@ export function createJournal(options: CreateJournalOptions): Journal {
       },
       rewind() {
         cursor = 0;
+        undos.length = 0;
+      },
+      undoStack() {
+        return undos;
+      },
+      beginRegistrationPass() {
+        registrationPass = true;
+      },
+      endRegistrationPass() {
+        registrationPass = false;
+      },
+      setUndoExecution(allowed) {
+        undoExecution = allowed;
       },
       async commit(status, patch) {
         run.status = status;

package/src/kernel/pipeline.test.ts

@@ -212,10 +212,10 @@ describe("pipeline — Bearer cryptographic verification", () => {
         auth: { secret: "hmac-secret-for-tests", sessions, http: false },
         policies: [member],
       },
-      env: "local",
+      env: "test",
       startScheduler: false,
     });
-    await app.boot({ env: "local", gates: [member], startScheduler: false });
+    await app.boot({ env: "test", gates: [member], startScheduler: false });
 
     const res = await app.fetch(
       new Request("http://localhost/secure", {
@@ -267,12 +267,12 @@ describe("pipeline — Bearer cryptographic verification", () => {
         auth: { secret, sessions, now: () => nowMs, http: false },
         policies: [member],
       },
-      env: "local",
+      env: "test",
       elements: { clock: clockRt },
       startScheduler: false,
     });
     await app.boot({
-      env: "local",
+      env: "test",
       gates: [member],
       startScheduler: false,
       elements: { clock: clockRt },
@@ -317,10 +317,24 @@ describe("pipeline — Bearer cryptographic verification", () => {
     const app = oke({
       name: "no-inject",
       gate: { policies: [member] },
-      env: "local",
+      env: "dev",
+      config: {
+        drivers: {
+          store: { kv: { dev: "memory", test: "memory", prod: "memory" } },
+          signal: { dev: "memory", test: "memory", prod: "memory" },
+          clock: { dev: "memory", test: "frozen", prod: "memory" },
+          journal: { dev: "memory", test: "memory", prod: "memory" },
+          channel: { email: { dev: "console", test: "console", prod: "console" } },
+        },
+      },
+      startScheduler: false,
+    });
+    await app.boot({
+      env: "dev",
+      gates: [member],
       startScheduler: false,
+      config: app.$options.config,
     });
-    await app.boot({ env: "local", gates: [member], startScheduler: false });
 
     const result = await app.execute(
       app.flow("orders.inject")!,

package/src/kernel/redacted.test.ts

@@ -0,0 +1,35 @@
+/**
+ * Unit tests for {@link Redacted} serialization / inspect hygiene.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { inspect } from "node:util";
+import { REDACTED_PLACEHOLDER, Redacted } from "./redacted.ts";
+
+describe("Redacted", () => {
+  test("does not leak in JSON.stringify", () => {
+    const r = Redacted.of("secret");
+    expect(JSON.stringify({ r })).toBe(`{"r":"${REDACTED_PLACEHOLDER}"}`);
+  });
+
+  test("does not leak in string coercion", () => {
+    const r = Redacted.of("secret");
+    expect(r.toString()).toBe(REDACTED_PLACEHOLDER);
+    expect(r.valueOf()).toBe(REDACTED_PLACEHOLDER);
+    expect(String(r)).toBe(REDACTED_PLACEHOLDER);
+    expect(`${r}`).toBe(REDACTED_PLACEHOLDER);
+  });
+
+  test("does not leak in util.inspect", () => {
+    const r = Redacted.of("secret");
+    const inspected = inspect(r);
+    expect(inspected).toContain("Redacted");
+    expect(inspected).not.toContain("secret");
+  });
+
+  test("reveal and map keep the cleartext only behind reveal", () => {
+    const r = Redacted.of("secret").map((v) => v.toUpperCase());
+    expect(r.reveal()).toBe("SECRET");
+    expect(JSON.stringify(r)).toBe(`"${REDACTED_PLACEHOLDER}"`);
+  });
+});

package/src/kernel/redacted.ts

@@ -20,11 +20,29 @@ export class Redacted<T> {
     this.#value = value;
   }
 
+  /**
+   * Construct a {@link Redacted} without calling `new`.
+   *
+   * @param value - Wrapped secret
+   */
+  static of<T>(value: T): Redacted<T> {
+    return new Redacted(value);
+  }
+
   /** The one explicit way to get the real value. */
   reveal(): T {
     return this.#value;
   }
 
+  /**
+   * Transform the wrapped value without exposing it to callers.
+   *
+   * @param fn - Mapper over the cleartext
+   */
+  map<U>(fn: (value: T) => U): Redacted<U> {
+    return Redacted.of(fn(this.#value));
+  }
+
   toString(): string {
     return REDACTED_PLACEHOLDER;
   }
@@ -33,13 +51,17 @@ export class Redacted<T> {
     return REDACTED_PLACEHOLDER;
   }
 
+  valueOf(): string {
+    return REDACTED_PLACEHOLDER;
+  }
+
   [Symbol.toPrimitive](): string {
     return REDACTED_PLACEHOLDER;
   }
 
-  /** `util.inspect` / `console.log` — never the real value. */
+  /** `util.inspect` / `console.log` / Bun — never the real value. */
   [Symbol.for("nodejs.util.inspect.custom")](): string {
-    return REDACTED_PLACEHOLDER;
+    return `Redacted<${typeof this.#value}>`;
   }
 }
 

package/src/kernel/router/create-default.ts

@@ -0,0 +1,16 @@
+/**
+ * Default long-lived server router preset — RegExp → Trie.
+ */
+
+import { RegExpRouter } from "./regexp.ts";
+import { SmartRouter } from "./smart.ts";
+import { TrieRouter } from "./trie.ts";
+
+/**
+ * Create the default SmartRouter (RegExp → Trie) for long-lived servers.
+ */
+export function createDefaultRouter<T>(): SmartRouter<T> {
+  return new SmartRouter<T>({
+    factories: [() => new RegExpRouter<T>(), () => new TrieRouter<T>()],
+  });
+}

package/src/kernel/router/create-edge.ts

@@ -0,0 +1,18 @@
+/**
+ * Edge / cold-start router preset — Linear → Trie (no RegExp compile).
+ */
+
+import { LinearRouter } from "./linear.ts";
+import { SmartRouter } from "./smart.ts";
+import { TrieRouter } from "./trie.ts";
+
+/**
+ * Create an edge-oriented SmartRouter (Linear → Trie).
+ *
+ * Does not import `regexp.ts`, so edge bundles can tree-shake RegExpRouter.
+ */
+export function createEdgeRouter<T>(): SmartRouter<T> {
+  return new SmartRouter<T>({
+    factories: [() => new LinearRouter<T>(), () => new TrieRouter<T>()],
+  });
+}

package/src/kernel/router/create.ts

@@ -0,0 +1,23 @@
+/**
+ * Preset switch for {@link createRouter}.
+ */
+
+import { createDefaultRouter } from "./create-default.ts";
+import { createEdgeRouter } from "./create-edge.ts";
+import type { SmartRouter } from "./smart.ts";
+import type { RouterPreset } from "./types.ts";
+
+/**
+ * Create a router for the given preset.
+ *
+ * - `default` — SmartRouter(RegExp → Trie), long-lived servers
+ * - `edge` — SmartRouter(Linear → Trie), cold-start / one-shot isolates
+ *
+ * @param preset - Preset name
+ */
+export function createRouter<T>(preset: RouterPreset = "default"): SmartRouter<T> {
+  if (preset === "edge") {
+    return createEdgeRouter<T>();
+  }
+  return createDefaultRouter<T>();
+}

package/src/kernel/router/index.ts

@@ -0,0 +1,23 @@
+/**
+ * HTTP router — compiled RegExp matching with a Trie fallback, plus a linear
+ * preset for cold-start edge builds.
+ *
+ * Chosen at build/startup: try RegExp first; on unsupported patterns fall
+ * back to Trie. The `edge` preset uses LinearRouter for fast registration.
+ */
+
+export { createRouter } from "./create.ts";
+export { createDefaultRouter } from "./create-default.ts";
+export { createEdgeRouter } from "./create-edge.ts";
+export { LinearRouter } from "./linear.ts";
+export { RegExpRouter } from "./regexp.ts";
+export { SmartRouter } from "./smart.ts";
+export { TrieRouter } from "./trie.ts";
+export {
+  UnsupportedPathError,
+  isUnsupportedByRegExp,
+  type RouteMatch,
+  type Router,
+  type RouterFactory,
+  type RouterPreset,
+} from "./types.ts";

package/src/kernel/router/linear.ts

@@ -0,0 +1,88 @@
+/**
+ * Linear router — fast registration, O(n) string-scan match.
+ * Edge / cold-start preset (no compile phase).
+ */
+
+import type { RouteMatch, Router } from "./types.ts";
+
+interface LinearRoute<T> {
+  readonly method: string;
+  readonly path: string;
+  readonly value: T;
+  readonly parts: readonly string[];
+}
+
+/**
+ * Linear router — fast registration, O(n) string-scan match.
+ * Edge / cold-start preset (no compile phase).
+ */
+export class LinearRouter<T> implements Router<T> {
+  readonly name = "LinearRouter";
+  readonly #routes: LinearRoute<T>[] = [];
+
+  /**
+   * @param method - HTTP method
+   * @param path - Path pattern
+   * @param value - Route value
+   */
+  add(method: string, path: string, value: T): void {
+    const parts = path.startsWith("/") ? path.split("/").slice(1) : path.split("/");
+    this.#routes.push({ method, path, value, parts });
+  }
+
+  /**
+   * @param method - HTTP method
+   * @param path - Pathname
+   */
+  match(method: string, path: string): RouteMatch<T> | undefined {
+    const pathParts = path.startsWith("/") ? path.split("/").slice(1) : path.split("/");
+    if (pathParts.length > 0 && pathParts[pathParts.length - 1] === "") {
+      pathParts.pop();
+    }
+
+    for (const route of this.#routes) {
+      if (route.method !== method) continue;
+
+      if (!route.path.includes(":") && !route.path.includes("*")) {
+        if (route.path === path || `${route.path}/` === path) {
+          return { value: route.value, params: {} };
+        }
+        continue;
+      }
+
+      const params: Record<string, string> = {};
+      let pi = 0;
+      let matched = true;
+
+      for (let ri = 0; ri < route.parts.length; ri++) {
+        const part = route.parts[ri] ?? "";
+        if (part === "*") {
+          params["*"] = pathParts.slice(pi).join("/");
+          pi = pathParts.length;
+          break;
+        }
+        if (pi >= pathParts.length) {
+          matched = false;
+          break;
+        }
+        const got = pathParts[pi] ?? "";
+        if (part.startsWith(":") && part.length > 1) {
+          const name = part.endsWith("?") ? part.slice(1, -1) : part.slice(1);
+          params[name] = got;
+          pi += 1;
+          continue;
+        }
+        if (part !== got) {
+          matched = false;
+          break;
+        }
+        pi += 1;
+      }
+
+      if (matched && pi === pathParts.length) {
+        return { value: route.value, params };
+      }
+    }
+    return undefined;
+  }
+}