okengine 0.6.1 → 0.8.0

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,8 +117,23 @@ 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;
+  /**
+   * Test-only client injection for binders that open redis / signal redis.
+   * Production apps leave this unset.
+   */
+  readonly clients?: {
+    readonly kv?: import("../drivers/types.ts").KvClientLike;
+    readonly signalRedis?: import("../drivers/signal-types.ts").SignalRedisClientLike;
+  };
   /** Instance id for leader election. */
   readonly instanceId?: string;
   /**
@@ -136,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). */
@@ -154,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;
 }
 
 /**
@@ -174,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;
     }
@@ -208,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 };
 }
 
 /**
@@ -264,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");
@@ -272,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;
@@ -298,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) => {
@@ -344,7 +379,7 @@ export async function bootApplication(input: BootOptions = {}): Promise<BootResu
   let signal = pre.signal;
   if (needs.signal) {
     if (!signal) {
-      signal = await signalBind!.bindSignal(options, env, now);
+      signal = await signalBind!.bindSignal(options, env, now, docker);
     } else {
       // Pre-built: still register decls / start if needed.
       for (const decl of options.signals ?? []) {
@@ -356,27 +391,37 @@ 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)
   let gate = pre.gate;
   if (needs.gate && !gate) {
-    gate = await gateBind!.bindGate(options, now);
+    gate = await gateBind!.bindGate(options, now, env, docker);
   }
 
   // 5. Channel
@@ -419,6 +464,7 @@ export async function bootApplication(input: BootOptions = {}): Promise<BootResu
     channel,
     ai,
     runs,
+    journal,
     capabilities,
     stopScheduler() {
       if (schedulerTimer !== undefined) {
@@ -434,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/errors.ts

@@ -143,14 +143,20 @@ export const OKE_ERRORS = {
     fix: 'Add "{resource}" to this flow\'s effects.calls.',
   },
   /**
-   * Emit target has no subscriber (unified-theory §21 example).
-   * Reserved now so the number stays permanent.
+   * Emit target has no subscriber (unified-theory §21).
+   * Thrown at emit when `optional` is false and nobody is subscribed.
    */
   ORPHAN_EMIT: {
     code: 1042,
     cause: 'Flow "{flow}" emits signal "{resource}" with no subscriber.',
     fix: "Add `on({resource}, …)` or mark the signal `{ optional: true }`.",
   },
+  /** Emit payload failed the signal's declared Standard Schema. */
+  SIGNAL_SCHEMA: {
+    code: 1043,
+    cause: '"{resource}": {detail}',
+    fix: "Fix schema payload.",
+  },
   /**
    * Domain table/column missing under docker/prod (migrations not applied).
    * Store/DDL band starts at 1100.

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 {};
       },
@@ -258,6 +264,19 @@ describe("errors — registry", () => {
     expect(err.message).toContain("→");
   });
 
+  test("OKE1043 is reserved for signal schema emit failures", () => {
+    const def = OKE_ERRORS.SIGNAL_SCHEMA;
+    expect(def.code).toBe(1043);
+    expect(lookupOkeError(1043)).toEqual(def);
+    const err = new OkeError(def, {
+      resource: "order-placed",
+      detail: "total: Expected number, received string",
+    });
+    expect(err.message).toContain("OKE1043");
+    expect(err.message).toContain("order-placed");
+    expect(err.message).toContain("https://oke.omqkhafi.dev/e/1043");
+  });
+
   test("fx.fail returns a value, not an exception", () => {
     const fx = createFx({ flow: "x", effects: {} });
     const result = fx.fail(

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,
@@ -19,6 +26,7 @@ import type {
 } from "../elements/store.ts";
 import type { SqlRow } from "../drivers/types.ts";
 import type { SignalRuntime } from "../elements/signal.ts";
+import type { SignalEmitOptions } from "../drivers/signal-types.ts";
 import type { VaultRuntime } from "../elements/vault.ts";
 import type { ChannelRuntime } from "../elements/channel.ts";
 import type { AiRuntime } from "../elements/ai.ts";
@@ -227,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[];
@@ -285,18 +323,24 @@ 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`).
    *
    * @param signal - Signal name or handle
    * @param payload - Payload
+   * @param options - Optional emit options (`key` for per-key once ordering)
    */
-  emit(signal: NamedRef, payload?: unknown): Promise<void>;
+  emit(signal: NamedRef, payload?: unknown, options?: SignalEmitOptions): Promise<void>;
   /**
    * Call another flow (records `call`). Stub returns `undefined`.
    *
@@ -325,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 `{}`.
    *
@@ -835,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();
@@ -870,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) {
@@ -892,7 +974,28 @@ export function createFxContext(options: CreateFxOptions): FxContext {
         });
       }
 
-      // KV / files / index — thin gated wrappers preserving driver methods.
+      if (decl.facet === "files") {
+        const ref = decl.ref;
+        return runtime.openFilesFx(
+          decl as Extract<StoreDecl, { facet: "files" }>,
+          {
+            effects: options.effects ?? {},
+            revealPii: options.revealPii,
+          },
+          {
+            gate: gated,
+            refuseDryRunWrite: () => {
+              if (isDryRun()) {
+                throw new DryRunWriteIsolationError(
+                  `Driver-backed store "${ref}" cannot isolate writes during dry-run; dry-run refused rather than risk a double-write.`,
+                );
+              }
+            },
+          },
+        );
+      }
+
+      // KV / index — thin gated wrappers preserving driver methods.
       const baseRef = decl.ref;
       return new Proxy({} as StoreHandle, {
         get(_t, prop) {
@@ -1007,14 +1110,12 @@ export function createFxContext(options: CreateFxOptions): FxContext {
   };
 
   const fx: Fx = {
-    store(ref) {
-      return storeHandle(ref);
-    },
-    emit(signal, payload) {
+    store: storeHandle,
+    emit(signal, payload, emitOptions) {
       const name = resolveName(signal);
       return gated("emit", name, async () => {
         if (options.signalRuntime) {
-          await options.signalRuntime.emit(name, payload);
+          await options.signalRuntime.emit(name, payload, emitOptions);
         }
       });
     },
@@ -1069,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,