okengine 0.2.6 → 0.3.2

package/src/elements/channel/runtime.ts

@@ -5,11 +5,7 @@
  * error hierarchy via sently). Fallback chains record every attempt.
  */
 
-import {
-  FallbackTransport,
-  type FallbackAttempt,
-  type Transport,
-} from "sently";
+import { FallbackTransport, type FallbackAttempt, type Transport } from "sently";
 import { RetryTransport } from "sently/transports/retry";
 import type {
   ChannelAttempt,
@@ -20,14 +16,8 @@ import type {
 import type { ChannelMedium } from "../../manifest/types.ts";
 import type { ConsentStore } from "./consent.ts";
 import type { ChannelTemplateDecl } from "./declare.ts";
-import {
-  DEFAULT_MEDIUM_COSTS,
-  type MediumCosts,
-} from "./costs.ts";
-import {
-  resolveLocale,
-  type LocaleChainStep,
-} from "./locale.ts";
+import { DEFAULT_MEDIUM_COSTS, type MediumCosts } from "./costs.ts";
+import { resolveLocale, type LocaleChainStep } from "./locale.ts";
 import type { DeliveryOutcomeState } from "./outcomes.ts";
 import {
   createReceiptLedger,
@@ -36,20 +26,14 @@ import {
   type IngestOutcomeInput,
   type ReceiptLedger,
 } from "./receipts.ts";
-import {
-  createSuppressionStore,
-  type SuppressionStore,
-} from "./suppression.ts";
+import { createSuppressionStore, type SuppressionStore } from "./suppression.ts";
 
 /** Locale catalog: template → locale → rendered body. */
 export type TemplateCatalog = Readonly<
   Record<
     string,
     Readonly<
-      Record<
-        string,
-        { readonly subject?: string; readonly text?: string; readonly html?: string }
-      >
+      Record<string, { readonly subject?: string; readonly text?: string; readonly html?: string }>
     >
   >
 >;
@@ -107,10 +91,7 @@ export interface ChannelRuntime {
    * @param template - Template name
    * @param options - Recipient / data / locale / via
    */
-  send(
-    template: string,
-    options: ChannelSendOptions,
-  ): Promise<ChannelSendResult>;
+  send(template: string, options: ChannelSendOptions): Promise<ChannelSendResult>;
   /**
    * Ingest a post-send provider outcome (bounce / complaint / …).
    * Hard bounce auto-adds suppression. Console projects the ledger — never
@@ -126,18 +107,14 @@ export interface ChannelRuntime {
  *
  * @param options - Templates + drivers + catalog
  */
-export function createChannelRuntime(
-  options: CreateChannelRuntimeOptions = {},
-): ChannelRuntime {
+export function createChannelRuntime(options: CreateChannelRuntimeOptions = {}): ChannelRuntime {
   const templates = new Map<string, ChannelTemplateDecl>();
   for (const t of options.templates ?? []) {
     templates.set(t.name, t);
   }
   const suppression =
     options.suppression ??
-    createSuppressionStore(
-      options.consent ? { consent: options.consent } : {},
-    );
+    createSuppressionStore(options.consent ? { consent: options.consent } : {});
   const receipts = options.receipts ?? createReceiptLedger();
   const costs = options.costs ?? { ...DEFAULT_MEDIUM_COSTS };
   const catalog = options.catalog ?? {};
@@ -151,8 +128,7 @@ export function createChannelRuntime(
     data: Readonly<Record<string, unknown>>,
   ): { subject?: string; text?: string; html?: string } {
     const byLocale = catalog[template];
-    const entry =
-      byLocale?.[locale] ?? byLocale?.[defaultLocale] ?? byLocale?.en;
+    const entry = byLocale?.[locale] ?? byLocale?.[defaultLocale] ?? byLocale?.en;
     if (!entry) {
       return {
         subject: template,
@@ -161,9 +137,7 @@ export function createChannelRuntime(
     }
     const interpolate = (s: string | undefined): string | undefined => {
       if (s === undefined) return undefined;
-      return s.replace(/\{\{(\w+)\}\}/g, (_, key: string) =>
-        String(data[key] ?? ""),
-      );
+      return s.replace(/\{\{(\w+)\}\}/g, (_, key: string) => String(data[key] ?? ""));
     };
     return {
       subject: interpolate(entry.subject),
@@ -172,10 +146,7 @@ export function createChannelRuntime(
     };
   }
 
-  function driversFor(
-    medium: ChannelMedium,
-    via?: readonly string[],
-  ): ChannelDriver[] {
+  function driversFor(medium: ChannelMedium, via?: readonly string[]): ChannelDriver[] {
     let list = drivers;
     if (via && via.length > 0) {
       list = via
@@ -184,13 +155,11 @@ export function createChannelRuntime(
     }
     return list.filter((d) => {
       if (medium === "email" || medium === "any") {
-        return !!d.transport || d.channel?.mediums.includes(medium) ||
-          d.channel?.mediums.includes("any");
+        return (
+          !!d.transport || d.channel?.mediums.includes(medium) || d.channel?.mediums.includes("any")
+        );
       }
-      return (
-        d.channel?.mediums.includes(medium) ||
-        d.channel?.mediums.includes("any")
-      );
+      return d.channel?.mediums.includes(medium) || d.channel?.mediums.includes("any");
     });
   }
 
@@ -202,9 +171,7 @@ export function createChannelRuntime(
     const transports: Transport[] = [];
     for (const d of chain) {
       if (!d.transport) continue;
-      const t = options.retry
-        ? new RetryTransport(d.transport)
-        : d.transport;
+      const t = options.retry ? new RetryTransport(d.transport) : d.transport;
       transports.push(t);
     }
     if (transports.length === 0) {
@@ -215,9 +182,7 @@ export function createChannelRuntime(
     const fallback = new FallbackTransport(transports, {
       onFallback(failedIndex, error) {
         const provider =
-          transports[failedIndex]?.provider ??
-          chain[failedIndex]?.id ??
-          `driver-${failedIndex}`;
+          transports[failedIndex]?.provider ?? chain[failedIndex]?.id ?? `driver-${failedIndex}`;
         recorded.push({ provider, error });
         attempts.push({
           driverId: provider,
@@ -317,9 +282,7 @@ export function createChannelRuntime(
     };
   }
 
-  function classifySendFailure(
-    attempts: readonly ChannelAttempt[],
-  ): DeliveryOutcomeState {
+  function classifySendFailure(attempts: readonly ChannelAttempt[]): DeliveryOutcomeState {
     const err = attempts
       .map((a) => a.error ?? "")
       .join(" ")
@@ -344,14 +307,9 @@ export function createChannelRuntime(
       const existing = receipts.byMessageId(input.messageId);
       if (input.state === "hard-bounce") {
         const subject = input.to ?? existing?.to;
-        const medium = (input.medium ??
-          existing?.medium ??
-          "email") as ChannelMedium;
+        const medium = (input.medium ?? existing?.medium ?? "email") as ChannelMedium;
         if (subject) {
-          suppression.addPriorBounce(
-            subject,
-            medium === "any" ? "email" : medium,
-          );
+          suppression.addPriorBounce(subject, medium === "any" ? "email" : medium);
         }
       }
 
@@ -384,15 +342,12 @@ export function createChannelRuntime(
         throw new Error(`channel: unknown template "${template}"`);
       }
       const medium = decl.medium;
-      const checkMedium: ChannelMedium =
-        medium === "any" ? "email" : medium;
+      const checkMedium: ChannelMedium = medium === "any" ? "email" : medium;
 
       const suppressed = suppression.isSuppressed(opts.to, checkMedium);
       if (suppressed.suppressed) {
         const status: DeliveryStatus =
-          suppressed.reason === "opted-out"
-            ? "suppressed/opted-out"
-            : "suppressed/prior-bounce";
+          suppressed.reason === "opted-out" ? "suppressed/opted-out" : "suppressed/prior-bounce";
         const resolved = resolveLocale({
           locale: opts.locale,
           profileLocale: opts.profileLocale,
@@ -409,10 +364,7 @@ export function createChannelRuntime(
           status,
           attempts: [],
           at: now(),
-          error:
-            suppressed.reason === "opted-out"
-              ? "opted out"
-              : "prior hard bounce",
+          error: suppressed.reason === "opted-out" ? "opted out" : "prior hard bounce",
         };
         receipts.record(receipt);
         return {
@@ -469,8 +421,7 @@ export function createChannelRuntime(
 
       let status: DeliveryStatus;
       if (result.ok) {
-        status =
-          attempts.filter((a) => !a.ok).length > 0 ? "fallback" : "sent";
+        status = attempts.filter((a) => !a.ok).length > 0 ? "fallback" : "sent";
       } else {
         status = classifySendFailure(attempts);
       }
@@ -490,7 +441,10 @@ export function createChannelRuntime(
         ...(result.ok
           ? {}
           : {
-              error: attempts.map((a) => a.error).filter(Boolean).join("; "),
+              error: attempts
+                .map((a) => a.error)
+                .filter(Boolean)
+                .join("; "),
             }),
       });
 

package/src/elements/channel/suppression.ts

@@ -5,11 +5,7 @@
  */
 
 import type { ChannelMedium } from "../../manifest/types.ts";
-import {
-  createConsentStore,
-  type ConsentStore,
-  type OptOut,
-} from "./consent.ts";
+import { createConsentStore, type ConsentStore, type OptOut } from "./consent.ts";
 
 /** Why an address is suppressed. */
 export type SuppressionReason = "opted-out" | "prior-bounce";
@@ -35,9 +31,11 @@ export interface SuppressionStore {
   isSuppressed(
     subject: string,
     medium: ChannelMedium,
-  ): { readonly suppressed: true; readonly reason: SuppressionReason } | {
-    readonly suppressed: false;
-  };
+  ):
+    | { readonly suppressed: true; readonly reason: SuppressionReason }
+    | {
+        readonly suppressed: false;
+      };
   /**
    * Record an opt-out.
    *
@@ -76,9 +74,7 @@ export function createSuppressionStore(
 
   function bounceMatches(subject: string, medium: ChannelMedium): boolean {
     return bounces.some(
-      (r) =>
-        r.subject === subject &&
-        (r.medium === "all" || r.medium === medium),
+      (r) => r.subject === subject && (r.medium === "all" || r.medium === medium),
     );
   }
 
@@ -97,9 +93,7 @@ export function createSuppressionStore(
       consent.optOut(subject, medium);
     },
     addPriorBounce(subject, medium) {
-      if (
-        !bounces.some((r) => r.subject === subject && r.medium === medium)
-      ) {
+      if (!bounces.some((r) => r.subject === subject && r.medium === medium)) {
         bounces.push({ subject, medium, at: Date.now() });
       }
     },

package/src/elements/channel.test.ts

@@ -9,17 +9,8 @@
 
 import { describe, expect, test } from "bun:test";
 import type { MailOptions, SendResult, Transport } from "sently";
-import {
-  createChannelInbox,
-  openConsoleChannel,
-  type ChannelDriver,
-} from "../drivers/index.ts";
-import {
-  channel,
-  createChannelRuntime,
-  createConsentStore,
-  FallbackTransport,
-} from "./channel.ts";
+import { createChannelInbox, openConsoleChannel, type ChannelDriver } from "../drivers/index.ts";
+import { channel, createChannelRuntime, createConsentStore, FallbackTransport } from "./channel.ts";
 
 /** Create a sently-compatible transport that always fails. */
 function failingTransport(provider: string): Transport {
@@ -56,10 +47,7 @@ function addressToString(input: MailOptions["to"]): string {
   return input.address;
 }
 
-function driverFromTransport(
-  id: ChannelDriver["id"],
-  transport: Transport,
-): ChannelDriver {
+function driverFromTransport(id: ChannelDriver["id"], transport: Transport): ChannelDriver {
   return { id, transport };
 }
 
@@ -113,9 +101,7 @@ describe("fallback chain records both attempts", () => {
 
     expect(result.ok).toBe(true);
     expect(result.attempts.length).toBeGreaterThanOrEqual(2);
-    expect(result.attempts.some((a) => a.driverId === "smtp" && !a.ok)).toBe(
-      true,
-    );
+    expect(result.attempts.some((a) => a.driverId === "smtp" && !a.ok)).toBe(true);
     expect(result.attempts.some((a) => a.ok)).toBe(true);
 
     const receipts = runtime.receipts.forTemplate("booking-confirmed");
@@ -125,10 +111,7 @@ describe("fallback chain records both attempts", () => {
   });
 
   test("sently FallbackTransport is the same interface", async () => {
-    const fb = new FallbackTransport([
-      failingTransport("a"),
-      okTransport("b"),
-    ]);
+    const fb = new FallbackTransport([failingTransport("a"), okTransport("b")]);
     const r = await fb.send({
       from: "a@b.c",
       to: "d@e.f",
@@ -168,9 +151,7 @@ describe("consent and i18n", () => {
     });
     const blocked = await runtime.send("news", { to: "bounce@example.com" });
     expect(blocked.ok).toBe(false);
-    expect(runtime.receipts.all().at(-1)!.status).toBe(
-      "suppressed/prior-bounce",
-    );
+    expect(runtime.receipts.all().at(-1)!.status).toBe("suppressed/prior-bounce");
   });
 
   test("locale chain is recorded on the receipt", async () => {
@@ -192,9 +173,7 @@ describe("consent and i18n", () => {
   test("locale selects catalog body", async () => {
     const inbox = createChannelInbox();
     const runtime = createChannelRuntime({
-      templates: [
-        channel.template("hello", { medium: "email", locales: ["en", "ar"] }),
-      ],
+      templates: [channel.template("hello", { medium: "email", locales: ["en", "ar"] })],
       drivers: [openConsoleChannel({ inbox })],
       catalog: {
         hello: {
@@ -213,9 +192,7 @@ describe("console driver", () => {
   test("dev inbox captures every medium", async () => {
     const inbox = createChannelInbox();
     const runtime = createChannelRuntime({
-      templates: [
-        channel.template("sms-otp", { medium: "sms" }),
-      ],
+      templates: [channel.template("sms-otp", { medium: "sms" })],
       drivers: [openConsoleChannel({ inbox })],
       catalog: {
         "sms-otp": { en: { text: "code {{code}}" } },

package/src/elements/channel.ts

@@ -19,9 +19,7 @@ export type {
   ChannelTemplateOptions,
 } from "./channel/declare.ts";
 
-export {
-  createChannelRuntime,
-} from "./channel/runtime.ts";
+export { createChannelRuntime } from "./channel/runtime.ts";
 export type {
   ChannelRuntime,
   ChannelSendOptions,
@@ -29,11 +27,7 @@ export type {
   TemplateCatalog,
 } from "./channel/runtime.ts";
 
-export {
-  createConsentStore,
-  type ConsentStore,
-  type OptOut,
-} from "./channel/consent.ts";
+export { createConsentStore, type ConsentStore, type OptOut } from "./channel/consent.ts";
 
 export {
   createSuppressionStore,
@@ -81,12 +75,7 @@ export {
   type MediumCosts,
 } from "./channel/costs.ts";
 
-export {
-  CHANNEL_PII_MASK,
-  maskEmail,
-  maskPhone,
-  maskRecipient,
-} from "./channel/mask.ts";
+export { CHANNEL_PII_MASK, maskEmail, maskPhone, maskRecipient } from "./channel/mask.ts";
 
 export {
   domainFromFrom,

package/src/elements/clock/actions.ts

@@ -50,10 +50,7 @@ export class ClockResourceNotFoundError extends Error {
  * @param store - Cron store
  * @param name - Cron name
  */
-export async function pauseCron(
-  store: CronStore,
-  name: string,
-): Promise<CronRow> {
+export async function pauseCron(store: CronStore, name: string): Promise<CronRow> {
   const row = await store.get(name);
   if (!row) throw new ClockResourceNotFoundError("cron", name);
   const next: CronRow = { ...row, status: "paused" };
@@ -74,19 +71,14 @@ export interface EditScheduleInput {
  * @param store - Cron store
  * @param input - Name + override cron and/or every
  */
-export async function editSchedule(
-  store: CronStore,
-  input: EditScheduleInput,
-): Promise<CronRow> {
+export async function editSchedule(store: CronStore, input: EditScheduleInput): Promise<CronRow> {
   const row = await store.get(input.name);
   if (!row) throw new ClockResourceNotFoundError("cron", input.name);
   if (!row.overridable) {
     throw new ScheduleNotOverridableError(input.name);
   }
-  const overrideCron =
-    input.cron !== undefined ? input.cron : row.overrideCron;
-  const overrideEvery =
-    input.every !== undefined ? input.every : row.overrideEvery;
+  const overrideCron = input.cron !== undefined ? input.cron : row.overrideCron;
+  const overrideEvery = input.every !== undefined ? input.every : row.overrideEvery;
   const next: CronRow = {
     ...row,
     overrideCron,
@@ -125,9 +117,7 @@ export interface WakeEarlyResult {
  *
  * @param options - Journal, run id, optional flow resolver
  */
-export async function wakeEarly(
-  options: WakeEarlyOptions,
-): Promise<WakeEarlyResult> {
+export async function wakeEarly(options: WakeEarlyOptions): Promise<WakeEarlyResult> {
   const now = options.now ?? (() => Date.now());
   const t = now();
   const run = await options.journal.get(options.runId);
@@ -136,9 +126,7 @@ export async function wakeEarly(
   }
 
   const entries = run.entries.map((e) =>
-    e.kind === "sleep" && e.wakeAt === run.wakeAt
-      ? { ...e, wakeAt: t }
-      : e,
+    e.kind === "sleep" && e.wakeAt === run.wakeAt ? { ...e, wakeAt: t } : e,
   );
   await options.journal.put({
     ...run,

package/src/elements/clock/declare.ts

@@ -44,9 +44,7 @@ export interface ClockDecl {
  */
 export function clock(name: string, options: ClockOptions = {}): ClockDecl {
   if (!options.cron && !options.every) {
-    throw new TypeError(
-      `clock("${name}"): require cron or every`,
-    );
+    throw new TypeError(`clock("${name}"): require cron or every`);
   }
   return {
     name,

package/src/elements/clock/dst.ts

@@ -134,11 +134,7 @@ function classifyLocalInstant(
   for (let offsetMin = -14 * 60; offsetMin <= 14 * 60; offsetMin += 15) {
     const utc = base + hour * 3_600_000 + minute * 60_000 - offsetMin * 60_000;
     const local = formatInZone(utc, timezone);
-    if (
-      local.date === dateStr &&
-      local.hour === hour &&
-      local.minute === minute
-    ) {
+    if (local.date === dateStr && local.hour === hour && local.minute === minute) {
       if (!matches.includes(utc)) matches.push(utc);
     }
   }

package/src/elements/clock/durable.ts

@@ -7,11 +7,7 @@
  */
 
 import type { AnyFlowDef } from "../../kernel/flow.ts";
-import {
-  createFxContext,
-  type CreateFxOptions,
-  type Fx,
-} from "../../kernel/fx.ts";
+import { createFxContext, type CreateFxOptions, type Fx } from "../../kernel/fx.ts";
 import {
   createJournal,
   isJournalSuspend,
@@ -51,10 +47,7 @@ export interface RunDurableOptions {
   /** Injectable clock. */
   readonly now?: () => number;
   /** Extra fx options (secrets, store runtime, …). */
-  readonly fx?: Omit<
-    CreateFxOptions,
-    "flow" | "effects" | "capability" | "now" | "journal"
-  >;
+  readonly fx?: Omit<CreateFxOptions, "flow" | "effects" | "capability" | "now" | "journal">;
 }
 
 /**
@@ -73,13 +66,8 @@ export async function runDurable<O = unknown>(
 
   if (options.runId) {
     const existing = await options.journalStore.get(options.runId);
-    if (
-      existing?.wakeAt !== undefined &&
-      now() < existing.wakeAt
-    ) {
-      const sleepEntry = [...existing.entries]
-        .reverse()
-        .find((e) => e.kind === "sleep");
+    if (existing?.wakeAt !== undefined && now() < existing.wakeAt) {
+      const sleepEntry = [...existing.entries].reverse().find((e) => e.kind === "sleep");
       return {
         status: "sleeping",
         runId: existing.id,

package/src/elements/clock/health.ts

@@ -7,10 +7,7 @@
 
 import { parseDurationMs } from "./duration.ts";
 import { effectiveSchedule, type CronRow } from "./reconcile.ts";
-import {
-  countMissedOccurrences,
-  previousOccurrence,
-} from "./schedule.ts";
+import { countMissedOccurrences, previousOccurrence } from "./schedule.ts";
 
 /** Catch-up policy matching ClockRuntime physics. */
 export type CatchUpPolicy = "one";
@@ -39,9 +36,7 @@ export interface CronHealth {
  */
 export function cronHealth(row: CronRow, now: number): CronHealth {
   const overdue = isOverdue(row, now);
-  const missedRuns = overdue
-    ? countMissedFromRow(row, now)
-    : 0;
+  const missedRuns = overdue ? countMissedFromRow(row, now) : 0;
   const driftMs = computeDrift(row, now);
 
   return {

package/src/elements/clock/leader.ts

@@ -33,12 +33,7 @@ export interface LeaseStore {
    * @param now - Current epoch-ms
    * @param leaseMs - Lease TTL
    */
-  acquireLease?(
-    name: string,
-    instanceId: string,
-    now: number,
-    leaseMs: number,
-  ): Promise<boolean>;
+  acquireLease?(name: string, instanceId: string, now: number, leaseMs: number): Promise<boolean>;
 }
 
 /** Options for {@link tryAcquireLease}. */
@@ -63,9 +58,7 @@ export interface AcquireLeaseOptions {
  *
  * @param options - Name, instance, clock, store
  */
-export async function tryAcquireLease(
-  options: AcquireLeaseOptions,
-): Promise<boolean> {
+export async function tryAcquireLease(options: AcquireLeaseOptions): Promise<boolean> {
   if (options.store.acquireLease) {
     return options.store.acquireLease(
       options.name,

package/src/elements/clock/reconcile.ts

@@ -68,12 +68,7 @@ export interface CronStore {
    * @param now - Current epoch-ms
    * @param leaseMs - Lease TTL
    */
-  acquireLease(
-    name: string,
-    instanceId: string,
-    now: number,
-    leaseMs: number,
-  ): Promise<boolean>;
+  acquireLease(name: string, instanceId: string, now: number, leaseMs: number): Promise<boolean>;
 }
 
 /** Result of one reconciliation pass. */
@@ -107,13 +102,9 @@ export async function reconcileClocks(
   for (const decl of declared) {
     const prev = await store.get(decl.name);
     const overrideCron =
-      decl.overridable && prev?.overrideCron !== undefined
-        ? prev.overrideCron
-        : undefined;
+      decl.overridable && prev?.overrideCron !== undefined ? prev.overrideCron : undefined;
     const overrideEvery =
-      decl.overridable && prev?.overrideEvery !== undefined
-        ? prev.overrideEvery
-        : undefined;
+      decl.overridable && prev?.overrideEvery !== undefined ? prev.overrideEvery : undefined;
 
     const row: CronRow = {
       name: decl.name,
@@ -179,9 +170,7 @@ export function effectiveSchedule(row: CronRow): {
  *
  * @param seed - Optional initial rows
  */
-export function createMemoryCronStore(
-  seed?: readonly CronRow[],
-): CronStore {
+export function createMemoryCronStore(seed?: readonly CronRow[]): CronStore {
   const rows = new Map<string, CronRow>();
   for (const r of seed ?? []) {
     rows.set(r.name, structuredClone(r));

package/src/elements/clock/runtime.ts

@@ -99,12 +99,9 @@ export interface ClockRuntime {
  *
  * @param options - Instance id, store, clock
  */
-export function createClockRuntime(
-  options: CreateClockRuntimeOptions = {},
-): ClockRuntime {
+export function createClockRuntime(options: CreateClockRuntimeOptions = {}): ClockRuntime {
   const timeTravel = options.timeTravel;
-  const now = (): number =>
-    timeTravel ? timeTravel.now() : (options.now ?? (() => Date.now()))();
+  const now = (): number => (timeTravel ? timeTravel.now() : (options.now ?? (() => Date.now()))());
   const store = options.store ?? createMemoryCronStore();
   const instanceId = options.instanceId ?? crypto.randomUUID();
   const leaseMs = options.leaseMs ?? 30_000;