okengine 0.7.0 → 0.8.0

package/src/kernel/boot-bind/honor-config.test.ts

@@ -15,6 +15,7 @@ import { gate } from "../../elements/gate.ts";
 import { signal } from "../../elements/signal.ts";
 import { vault } from "../../elements/vault.ts";
 import { buildVaultBootChain } from "../../elements/vault/boot-chain.ts";
+import { flow } from "../flow.ts";
 import { bootApplication } from "../boot.ts";
 
 describe("boot binders honour drivers.* config", () => {
@@ -126,19 +127,119 @@ describe("boot binders honour drivers.* config", () => {
     }
   });
 
-  test("clock: drivers.clock postgres fails loud", async () => {
+  test("clock: drivers.clock postgres fails without DATABASE_URL", async () => {
+    const prevDb = process.env.DATABASE_URL;
+    const prevStore = process.env.OKE_STORE_SQL_URL;
+    delete process.env.DATABASE_URL;
+    delete process.env.OKE_STORE_SQL_URL;
+    try {
+      await expect(
+        bootApplication({
+          env: "local",
+          startScheduler: false,
+          clocks: [clock("tick", { every: "1h" })],
+          config: {
+            drivers: {
+              clock: { local: "postgres" },
+            },
+          },
+        }),
+      ).rejects.toThrow(/clock driver "postgres" needs DATABASE_URL/);
+    } finally {
+      if (prevDb !== undefined) process.env.DATABASE_URL = prevDb;
+      else delete process.env.DATABASE_URL;
+      if (prevStore !== undefined) process.env.OKE_STORE_SQL_URL = prevStore;
+      else delete process.env.OKE_STORE_SQL_URL;
+    }
+  });
+
+  test("journal: durable flow binds memory journal by default", async () => {
+    const result = await bootApplication({
+      env: "local",
+      startScheduler: false,
+      flows: [flow({ name: "charge", durable: true, do: () => ({ ok: true }) })],
+    });
+    try {
+      expect(result.journal?.driverId).toBe("memory");
+      expect(typeof result.journal?.instanceId).toBe("string");
+      expect(result.journal?.leaseMs).toBeGreaterThan(0);
+    } finally {
+      await result.close();
+    }
+  });
+
+  test("journal: no durable flow → no journal runtime", async () => {
+    const result = await bootApplication({
+      env: "local",
+      startScheduler: false,
+      flows: [flow({ name: "plain", do: () => ({ ok: true }) })],
+    });
+    try {
+      expect(result.journal).toBeUndefined();
+    } finally {
+      await result.close();
+    }
+  });
+
+  test("journal: drivers.journal file binds file store", async () => {
+    tmp = await mkdtemp(join(tmpdir(), "oke-journal-file-"));
+    process.chdir(tmp);
+    const result = await bootApplication({
+      env: "local",
+      startScheduler: false,
+      flows: [flow({ name: "charge", durable: true, do: () => ({ ok: true }) })],
+      config: {
+        drivers: {
+          journal: { local: "file", docker: "postgres", test: "memory", prod: "postgres" },
+        },
+      },
+    });
+    try {
+      expect(result.journal?.driverId).toBe("file");
+    } finally {
+      await result.close();
+    }
+  });
+
+  test("journal: drivers.journal postgres fails without DATABASE_URL", async () => {
+    const prevDb = process.env.DATABASE_URL;
+    const prevStore = process.env.OKE_STORE_SQL_URL;
+    delete process.env.DATABASE_URL;
+    delete process.env.OKE_STORE_SQL_URL;
+    try {
+      await expect(
+        bootApplication({
+          env: "local",
+          startScheduler: false,
+          flows: [flow({ name: "charge", durable: true, do: () => ({ ok: true }) })],
+          config: {
+            drivers: {
+              journal: { local: "postgres" },
+            },
+          },
+        }),
+      ).rejects.toThrow(/journal driver "postgres" needs DATABASE_URL/);
+    } finally {
+      if (prevDb !== undefined) process.env.DATABASE_URL = prevDb;
+      else delete process.env.DATABASE_URL;
+      if (prevStore !== undefined) process.env.OKE_STORE_SQL_URL = prevStore;
+      else delete process.env.OKE_STORE_SQL_URL;
+    }
+  });
+
+  test("journal: unknown driver fails loud", async () => {
     await expect(
       bootApplication({
         env: "local",
         startScheduler: false,
-        clocks: [clock("tick", { every: "1h" })],
+        flows: [flow({ name: "charge", durable: true, do: () => ({ ok: true }) })],
         config: {
           drivers: {
-            clock: { local: "postgres" },
+            journal: { local: "neon" },
           },
         },
       }),
-    ).rejects.toThrow(/clock driver "postgres" is not implemented/);
+    ).rejects.toThrow(/unknown journal driver "neon"/);
   });
 
   test("gate: drivers.store.kv redis opens redis-backed oke:gates", async () => {

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

@@ -0,0 +1,89 @@
+/**
+ * Lazy journal binder — loaded only when a flow declares `durable: true`.
+ */
+
+import { mkdirSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import {
+  createFileJournalStore,
+  createMemoryJournalStore,
+  JOURNAL_DEFAULT_LEASE_MS,
+  type JournalStore,
+} from "../journal.ts";
+import { createPostgresJournalStore } from "../../drivers/journal-postgres.ts";
+import { resolveDriverId, type ConfigEnv } from "../../config/index.ts";
+import type { BootOptions } from "../boot.ts";
+
+/** Bound journal runtime — store + this instance's lease identity. */
+export interface JournalRuntime {
+  readonly store: JournalStore;
+  readonly instanceId: string;
+  readonly leaseMs: number;
+  readonly driverId: string;
+}
+
+/** Result of binding a journal runtime. */
+export interface BindJournalResult {
+  readonly journal: JournalRuntime;
+}
+
+/** Default on-disk journal path (single-host file driver). */
+export const DEFAULT_FILE_JOURNAL_PATH = ".oke/journal.json";
+
+/**
+ * Resolve `drivers.journal` for the active env (default `memory`).
+ *
+ * @param options - Boot options
+ * @param env - Active environment
+ */
+export function resolveJournalDriverId(options: BootOptions, env: ConfigEnv): string {
+  const resolved = resolveDriverId(options.config?.drivers?.journal, env);
+  if (resolved) return resolved;
+  return "memory";
+}
+
+/**
+ * Construct a journal store. Supported ids: `memory` · `file` · `postgres`.
+ *
+ * @param options - Boot options
+ * @param env - Active environment
+ */
+export async function bindJournal(
+  options: BootOptions,
+  env: ConfigEnv,
+): Promise<BindJournalResult> {
+  const driver = resolveJournalDriverId(options, env);
+  const instanceId = options.instanceId ?? `inst-${crypto.randomUUID()}`;
+
+  let store: JournalStore;
+  if (driver === "memory") {
+    store = createMemoryJournalStore();
+  } else if (driver === "file") {
+    const path = resolve(process.cwd(), DEFAULT_FILE_JOURNAL_PATH);
+    mkdirSync(dirname(path), { recursive: true });
+    store = createFileJournalStore(path);
+  } else if (driver === "postgres") {
+    const url = process.env.DATABASE_URL ?? process.env.OKE_STORE_SQL_URL ?? undefined;
+    if (!url) {
+      throw new Error(
+        env === "docker"
+          ? 'oke boot: journal driver "postgres" needs DATABASE_URL (did `oke dev -d` write docker/.env.docker?)'
+          : 'oke boot: journal driver "postgres" needs DATABASE_URL',
+      );
+    }
+    store = await createPostgresJournalStore({ url });
+  } else {
+    throw new Error(
+      `oke boot: unknown journal driver "${driver}" (expected memory · file · postgres)`,
+    );
+  }
+
+  return {
+    journal: {
+      store,
+      instanceId,
+      leaseMs: options.journalLeaseMs ?? JOURNAL_DEFAULT_LEASE_MS,
+      driverId: driver,
+    },
+  };
+}

package/src/kernel/boot.test.ts

@@ -79,7 +79,7 @@ describe("boot — lazy element needs", () => {
     expect(needs.signal).toBe(false);
   });
 
-  test("oke() Store-only graph stays under the prior 50 kB baseline", async () => {
+  test("oke() Store-only graph stays under the prior 51 kB baseline", async () => {
     const dir = await mkdtemp(join(tmpdir(), "oke-store-only-"));
     const entry = join(dir, "entry.ts");
     const appPath = join(import.meta.dir, "app.ts");
@@ -116,9 +116,11 @@ describe("boot — lazy element needs", () => {
         if (raw.byteLength === 0) continue;
         total += Bun.gzipSync(new Uint8Array(raw)).byteLength;
       }
-      // Rebased after AI stream/tool-loop + fx.t/i18n on the shared fx surface
-      // (~49.5 kB gzip). Still far below an eager full-element bind.
-      expect(total).toBeLessThan(50_000);
+      // Rebased after fx.sendOtp/verifyOtp on the shared fx surface (~50.1 kB
+      // gzip), then again after the durable-journal lease surface (SKIP LOCKED
+      // claim/release/orphan-scan on journal.ts + app.ts wiring, ~51.2 kB).
+      // Clock/channel/journal drivers stay lazy-bound; far below eager bind.
+      expect(total).toBeLessThan(51_500);
     } finally {
       await rm(dir, { recursive: true, force: true });
     }

package/src/kernel/boot.ts

@@ -5,7 +5,9 @@
  * 1. Vault     — resolve every declared secret (list all gaps at once)
  * 2. Store     — bind drivers per environment; open connections
  * 3. Signals   — register declarations; start consumers
- * 4. Clocks    — reconcile into the Store; start scheduler (leader election)
+ * 4. Clocks    — reconcile into the Store
+ * 4b. Journal  — bind the durable-run store (SKIP LOCKED + lease when shared)
+ * 4c. Scheduler — tick clocks + resume due durable runs (leader election)
  * 5. Channel   — bind channel runtime
  * 6. AI        — bind AI runtime
  * 7. Runs      — open the runs store
@@ -33,6 +35,7 @@ import type {
   VaultRuntime,
   VaultSecretDecl,
 } from "../elements/vault.ts";
+import type { JournalRuntime } from "./boot-bind/journal.ts";
 import type { CreateRunsRuntimeOptions, RunsRuntime } from "../runs/index.ts";
 import { createCapabilityToken, type CapabilityToken } from "./capability.ts";
 import type { AnyFlowDef } from "./flow.ts";
@@ -48,6 +51,8 @@ export interface ElementRuntimes {
   readonly channel?: ChannelRuntime;
   readonly ai?: AiRuntime;
   readonly runs?: RunsRuntime;
+  /** Pre-bound durable-run journal (skips driver resolution). */
+  readonly journal?: JournalRuntime;
 }
 
 /** Declarations + options consumed by {@link bootApplication}. */
@@ -112,6 +117,13 @@ export interface BootOptions {
    * @param payload - Payload
    */
   readonly onSignal?: (signal: string, payload: unknown) => void | Promise<void>;
+  /**
+   * Resume due durable runs — called on every scheduler tick when any flow
+   * declares `durable: true` (claimDueSleep on the shared journal store).
+   */
+  readonly onDurableResume?: () => void | Promise<void>;
+  /** Durable-run lease duration ms (default 30_000 — matches Signal claims). */
+  readonly journalLeaseMs?: number;
   /** Injectable clock for test / frozen harnesses. */
   readonly now?: () => number;
   /**
@@ -144,6 +156,8 @@ export interface BootResult {
   readonly channel?: ChannelRuntime;
   readonly ai?: AiRuntime;
   readonly runs?: RunsRuntime;
+  /** Durable-run journal (present when any flow declares `durable: true`). */
+  readonly journal?: JournalRuntime;
   /** Per-flow capability tokens minted from declared effects. */
   readonly capabilities: ReadonlyMap<string, CapabilityToken>;
   /** Stop the background scheduler (if started). */
@@ -162,6 +176,8 @@ export interface ElementNeeds {
   readonly channel: boolean;
   readonly ai: boolean;
   readonly runs: boolean;
+  /** Durable-run journal — any flow with `durable: true`. */
+  readonly journal: boolean;
 }
 
 /**
@@ -182,9 +198,11 @@ export function resolveElementNeeds(options: BootOptions): ElementNeeds {
   let channel = pre.channel !== undefined || options.channel !== undefined;
   let ai = pre.ai !== undefined || options.ai !== undefined;
   let runs = pre.runs !== undefined || options.runs !== undefined;
+  let journal = pre.journal !== undefined;
 
   const considerFlow = (f: AnyFlowDef): void => {
     const e = f.effects;
+    if (f.durable === true) journal = true;
     if ((e?.reads?.length ?? 0) > 0 || (e?.writes?.length ?? 0) > 0) {
       store = true;
     }
@@ -216,7 +234,7 @@ export function resolveElementNeeds(options: BootOptions): ElementNeeds {
     signal = true;
   }
 
-  return { vault, store, signal, clock, gate, channel, ai, runs };
+  return { vault, store, signal, clock, gate, channel, ai, runs, journal };
 }
 
 /**
@@ -272,6 +290,7 @@ export async function bootApplication(input: BootOptions = {}): Promise<BootResu
   type StoreBind = typeof import("./boot-bind/store.ts");
   type SignalBind = typeof import("./boot-bind/signal.ts");
   type ClockBind = typeof import("./boot-bind/clock.ts");
+  type JournalBind = typeof import("./boot-bind/journal.ts");
   type GateBind = typeof import("./boot-bind/gate.ts");
   type ChannelBind = typeof import("./boot-bind/channel.ts");
   type AiBind = typeof import("./boot-bind/ai.ts");
@@ -280,6 +299,7 @@ export async function bootApplication(input: BootOptions = {}): Promise<BootResu
   let storeBind: StoreBind | undefined;
   let signalBind: SignalBind | undefined;
   let clockBind: ClockBind | undefined;
+  let journalBind: JournalBind | undefined;
   let gateBind: GateBind | undefined;
   let channelBind: ChannelBind | undefined;
   let aiBind: AiBind | undefined;
@@ -306,6 +326,13 @@ export async function bootApplication(input: BootOptions = {}): Promise<BootResu
       }),
     );
   }
+  if (needs.journal && !pre.journal) {
+    binderLoads.push(
+      loadBind<JournalBind>("journal").then((m) => {
+        journalBind = m;
+      }),
+    );
+  }
   if (needs.gate && !pre.gate) {
     binderLoads.push(
       loadBind<GateBind>("gate").then((m) => {
@@ -364,21 +391,31 @@ export async function bootApplication(input: BootOptions = {}): Promise<BootResu
     }
   }
 
-  // 4. Clocks + optional scheduler
+  // 4. Clocks
   let clock = pre.clock;
-  let schedulerTimer: ReturnType<typeof setInterval> | undefined;
   if (needs.clock) {
     const bound = await clockBind!.bindClock(options, env, now, clock);
     clock = bound.clock;
-    const startScheduler = options.startScheduler ?? env !== "test";
-    if (startScheduler) {
-      const period = options.schedulerIntervalMs ?? 1000;
-      const clockRt = clock;
-      schedulerTimer = setInterval(() => {
-        void clockRt.tick();
-      }, period);
-      schedulerTimer.unref?.();
-    }
+  }
+
+  // 4b. Journal — durable-run store (shared + leased when a driver is bound).
+  let journal = pre.journal;
+  if (needs.journal && !journal) {
+    journal = (await journalBind!.bindJournal(options, env)).journal;
+  }
+
+  // 4c. Scheduler — one timer drives clock ticks and durable-run resume.
+  let schedulerTimer: ReturnType<typeof setInterval> | undefined;
+  const startScheduler = options.startScheduler ?? env !== "test";
+  if (startScheduler && (clock !== undefined || journal !== undefined)) {
+    const period = options.schedulerIntervalMs ?? 1000;
+    const clockRt = clock;
+    const durableResume = options.onDurableResume;
+    schedulerTimer = setInterval(() => {
+      if (clockRt) void clockRt.tick();
+      if (journal && durableResume) void durableResume();
+    }, period);
+    schedulerTimer.unref?.();
   }
 
   // Gate (before AI)
@@ -427,6 +464,7 @@ export async function bootApplication(input: BootOptions = {}): Promise<BootResu
     channel,
     ai,
     runs,
+    journal,
     capabilities,
     stopScheduler() {
       if (schedulerTimer !== undefined) {
@@ -442,6 +480,8 @@ export async function bootApplication(input: BootOptions = {}): Promise<BootResu
       await signal?.close();
       await vault?.close();
       await runs?.flush();
+      const journalStore = journal?.store as { close?: () => Promise<void> } | undefined;
+      await journalStore?.close?.();
     },
   };
 }

package/src/kernel/concurrency.ts

@@ -14,7 +14,7 @@ import {
   linkAbort,
   withAbortSignal,
 } from "./abort-scope.ts";
-import { isJournalSuspend } from "./journal.ts";
+import { isJournalSuspend } from "./journal-suspend.ts";
 
 /** A unit of work started under an abort scope. */
 export type FxThunk<T> = () => T | Promise<T>;

package/src/kernel/fx.test.ts

@@ -141,6 +141,12 @@ describe("fx — wholesale swap", () => {
       async send() {
         return { ok: true };
       },
+      async sendOtp() {
+        return { ok: true };
+      },
+      async verifyOtp() {
+        return { ok: true };
+      },
       async ask() {
         return {};
       },

package/src/kernel/fx.ts

@@ -11,7 +11,14 @@
 
 import type { Effects, ResourceRef } from "../manifest/types.ts";
 import type {
+  FilesStoreDecl,
+  FilesStoreFxHandle,
+  IndexStoreDecl,
+  IndexStoreFxHandle,
+  KvStoreDecl,
+  KvStoreFxHandle,
   SelectOrderBuilder,
+  SqlStoreDecl,
   StoreDecl,
   StoreHandle,
   StoreRuntime,
@@ -228,6 +235,36 @@ export interface FxSendOptions {
   readonly acceptLanguage?: string;
 }
 
+/** Options for {@link Fx.sendOtp} (provider-managed SMS OTP). */
+export interface FxSendOtpOptions {
+  /** Recipient phone number (E.164). */
+  readonly to: string;
+  /** Unique id for this verification flow (required again on verify). */
+  readonly requestId: string;
+  /** Message language (`en` or `ar`). */
+  readonly lang?: "en" | "ar";
+  /** Optional note appended to the OTP SMS. */
+  readonly note?: string;
+  /** Sender id override. */
+  readonly from?: string;
+}
+
+/** Options for {@link Fx.verifyOtp}. */
+export interface FxVerifyOtpOptions {
+  /** Recipient phone number (same as send). */
+  readonly to: string;
+  /** Same {@link FxSendOtpOptions.requestId} used when sending. */
+  readonly requestId: string;
+  /** OTP code the user entered. */
+  readonly code: string;
+  /** Message language (`en` or `ar`). */
+  readonly lang?: "en" | "ar";
+  /** Sender id override. */
+  readonly from?: string;
+  /** Optional note. */
+  readonly note?: string;
+}
+
 /** Options for {@link Fx.ask}. */
 export interface FxAskOptions {
   readonly via?: readonly NamedRef[];
@@ -286,10 +323,15 @@ export interface Fx {
    * Open a store handle for `ref` (capability checked on each op).
    *
    * When a {@link CreateFxOptions.storeRuntime} is bound and `ref` is a
-   * registered store declaration, returns the driver-backed handle.
+   * facet declaration, returns the driver-backed handle for that facet.
+   * String / `{ ref }` forms return the in-memory stub (tests).
    *
    * @param ref - Store resource ref, named handle, or store declaration
    */
+  store(ref: SqlStoreDecl): SqlStoreHandle;
+  store(ref: KvStoreDecl): KvStoreFxHandle;
+  store(ref: FilesStoreDecl): FilesStoreFxHandle;
+  store(ref: IndexStoreDecl): IndexStoreFxHandle;
   store(ref: NamedRef | { readonly ref: ResourceRef } | StoreDecl): FxStoreHandle;
   /**
    * Emit a signal (records `emit`).
@@ -327,6 +369,22 @@ export interface Fx {
    * @param opts - Recipient / data
    */
   send(template: NamedRef, opts?: FxSendOptions): Promise<{ ok: true }>;
+  /**
+   * Send a provider-managed SMS OTP (records `send` on `sms-otp`).
+   *
+   * Vendor extra (Taqnyat Verify API) — requires a bound SMS driver that
+   * supports provider-managed OTP. Dry-run records would-have-fired without
+   * contacting the provider.
+   *
+   * @param opts - Recipient + requestId (+ lang / note / from)
+   */
+  sendOtp(opts: FxSendOtpOptions): Promise<{ ok: true }>;
+  /**
+   * Verify a provider-managed SMS OTP code (records `send` on `sms-otp`).
+   *
+   * @param opts - Recipient + requestId + code (+ lang / note / from)
+   */
+  verifyOtp(opts: FxVerifyOtpOptions): Promise<{ ok: true }>;
   /**
    * Ask an AI prompt (records `ask`). Stub returns `{}`.
    *
@@ -837,6 +895,13 @@ export function createFxContext(options: CreateFxOptions): FxContext {
           return h.exists(table, idOrWhere);
         });
       },
+      upsert(table, matchOn, values, upsertOptions) {
+        return gated("write", ref, async () => {
+          refuseDryRunWrite();
+          const h = await ensure();
+          return h.upsert(table, matchOn, values, upsertOptions);
+        });
+      },
       increment(table, id, column, by) {
         return gated("write", ref, async () => {
           refuseDryRunWrite();
@@ -872,10 +937,25 @@ export function createFxContext(options: CreateFxOptions): FxContext {
     } as SqlStoreHandle;
   }
 
+  function storeHandle(ref: SqlStoreDecl): SqlStoreHandle;
+  function storeHandle(ref: KvStoreDecl): KvStoreFxHandle;
+  function storeHandle(ref: FilesStoreDecl): FilesStoreFxHandle;
+  function storeHandle(ref: IndexStoreDecl): IndexStoreFxHandle;
+  function storeHandle(ref: NamedRef | { readonly ref: ResourceRef } | StoreDecl): FxStoreHandle;
   function storeHandle(ref: NamedRef | { readonly ref: ResourceRef } | StoreDecl): FxStoreHandle {
     const runtime = options.storeRuntime;
-    if (runtime && typeof ref === "object" && ref !== null && "facet" in ref) {
+    if (typeof ref === "object" && ref !== null && "facet" in ref) {
       const decl = ref;
+      // SQL physics cannot run on the in-memory stub (insert(table).values ≠ stub insert(row)).
+      // Without a runtime, fail loudly — never return a stub missing upsert/select/….
+      if (!runtime) {
+        if (decl.facet === "sql") {
+          throw new Error(
+            `fx.store("${decl.ref}"): no store runtime — boot the app (stores / flow effects) before using SQL handles`,
+          );
+        }
+        return stubStoreHandle(decl.ref);
+      }
       const cache: { handle?: StoreHandle } = {};
       const open = async () => {
         if (!cache.handle) {
@@ -1030,9 +1110,7 @@ export function createFxContext(options: CreateFxOptions): FxContext {
   };
 
   const fx: Fx = {
-    store(ref) {
-      return storeHandle(ref);
-    },
+    store: storeHandle,
     emit(signal, payload, emitOptions) {
       const name = resolveName(signal);
       return gated("emit", name, async () => {
@@ -1092,6 +1170,49 @@ export function createFxContext(options: CreateFxOptions): FxContext {
         return { ok: true as const };
       });
     },
+    sendOtp(opts) {
+      return gated("send", "sms-otp", async () => {
+        if (isDryRun()) {
+          recordWouldHaveFired("send", "sms-otp");
+          return { ok: true as const };
+        }
+        if (!options.channelRuntime) {
+          throw new Error(
+            "fx.sendOtp needs a bound Channel — declare channel and set drivers.channel.sms (e.g. taqnyat)",
+          );
+        }
+        await options.channelRuntime.sendOtp({
+          to: opts.to,
+          requestId: opts.requestId,
+          ...(opts.lang ? { lang: opts.lang } : {}),
+          ...(opts.note ? { note: opts.note } : {}),
+          ...(opts.from ? { from: opts.from } : {}),
+        });
+        return { ok: true as const };
+      });
+    },
+    verifyOtp(opts) {
+      return gated("send", "sms-otp", async () => {
+        if (isDryRun()) {
+          recordWouldHaveFired("send", "sms-otp");
+          return { ok: true as const };
+        }
+        if (!options.channelRuntime) {
+          throw new Error(
+            "fx.verifyOtp needs a bound Channel — declare channel and set drivers.channel.sms (e.g. taqnyat)",
+          );
+        }
+        await options.channelRuntime.verifyOtp({
+          to: opts.to,
+          requestId: opts.requestId,
+          code: opts.code,
+          ...(opts.lang ? { lang: opts.lang } : {}),
+          ...(opts.from ? { from: opts.from } : {}),
+          ...(opts.note ? { note: opts.note } : {}),
+        });
+        return { ok: true as const };
+      });
+    },
     ask(prompt, input, opts) {
       const name = resolveName(prompt);
       return gated("ask", name, async () => {

package/src/kernel/index.ts

@@ -167,10 +167,16 @@ export {
   createJournal,
   createMemoryJournalStore,
   createFileJournalStore,
+  hasJournalLease,
+  isJournalLeaseBusy,
   isJournalSuspend,
+  JournalLeaseBusy,
   JournalSuspend,
+  JOURNAL_DEFAULT_LEASE_MS,
   type Journal,
   type JournalEntry,
+  type JournalLeaseOptions,
+  type JournalLeaseStore,
   type JournalRun,
   type JournalRunStatus,
   type JournalSession,