okengine 0.1.4

package/src/elements/clock/reconcile.ts

@@ -0,0 +1,241 @@
+/**
+ * Boot-time reconciliation — declared Manifest → Store (console §5).
+ *
+ * ```
+ * Declared   (from the Manifest baked into the code)   ← the truth
+ * Override   (in the Store, only where overridable)    ← operational drift
+ * Effective  = declared + override                     ← what actually runs
+ * ```
+ *
+ * Rows that vanished from the code are marked `orphaned`, never deleted.
+ * The scheduler reads the effective state from the Store, not the code.
+ */
+
+import type { ClockDecl } from "./declare.ts";
+
+/** Cron lifecycle status in `oke_crons`. */
+export type CronStatus = "active" | "paused" | "orphaned";
+
+/** Reconciled cron row (Store / `oke_crons`). */
+export interface CronRow {
+  readonly name: string;
+  /** Declared cron expression from code (if any). */
+  declaredCron?: string;
+  /** Declared interval from code (if any). */
+  declaredEvery?: string;
+  /** Console override cron (only when overridable). */
+  overrideCron?: string;
+  /** Console override every (only when overridable). */
+  overrideEvery?: string;
+  /** What the scheduler uses. */
+  effectiveCron?: string;
+  /** What the scheduler uses for interval schedules. */
+  effectiveEvery?: string;
+  timezone: string;
+  overridable: boolean;
+  status: CronStatus;
+  leaderInstanceId?: string;
+  leaderLeaseUntil?: number;
+  lastRunAt?: number;
+  nextRunAt?: number;
+  /** DST warning payload when expression+zone is ambiguous. */
+  dstAmbiguity?: {
+    readonly kind: "gap" | "overlap";
+    readonly reason: string;
+    readonly on: string;
+    readonly localTime: string;
+  };
+}
+
+/** Store surface for reconciled crons. */
+export interface CronStore {
+  /**
+   * @param name - Cron name
+   */
+  get(name: string): Promise<CronRow | undefined>;
+  /**
+   * @param row - Full row
+   */
+  put(row: CronRow): Promise<void>;
+  /** All rows currently in the store. */
+  list(): Promise<readonly CronRow[]>;
+  /**
+   * Atomic leader-lease acquire (compare-and-set). Required so N in-process
+   * instances cannot all win a race on read-modify-write.
+   *
+   * @param name - Cron name
+   * @param instanceId - Candidate instance
+   * @param now - Current epoch-ms
+   * @param leaseMs - Lease TTL
+   */
+  acquireLease(
+    name: string,
+    instanceId: string,
+    now: number,
+    leaseMs: number,
+  ): Promise<boolean>;
+}
+
+/** Result of one reconciliation pass. */
+export interface ReconcileResult {
+  /** Names upserted / refreshed as active. */
+  readonly active: readonly string[];
+  /** Names marked orphaned (present in store, absent from code). */
+  readonly orphaned: readonly string[];
+  /** Snapshot of every row after reconciliation. */
+  readonly rows: readonly CronRow[];
+}
+
+/**
+ * Reconcile declared clocks into the Store.
+ *
+ * - Declared schedules are upserted (`status: "active"`).
+ * - Overrides are preserved when `overridable`.
+ * - Store rows missing from declarations are marked `orphaned` (not deleted).
+ *
+ * @param declared - Clocks from the Manifest / code
+ * @param store - Cron store (`oke_crons`)
+ */
+export async function reconcileClocks(
+  declared: readonly ClockDecl[],
+  store: CronStore,
+): Promise<ReconcileResult> {
+  const declaredByName = new Map(declared.map((d) => [d.name, d]));
+  const active: string[] = [];
+  const orphaned: string[] = [];
+
+  for (const decl of declared) {
+    const prev = await store.get(decl.name);
+    const overrideCron =
+      decl.overridable && prev?.overrideCron !== undefined
+        ? prev.overrideCron
+        : undefined;
+    const overrideEvery =
+      decl.overridable && prev?.overrideEvery !== undefined
+        ? prev.overrideEvery
+        : undefined;
+
+    const row: CronRow = {
+      name: decl.name,
+      declaredCron: decl.cron,
+      declaredEvery: decl.every,
+      overrideCron,
+      overrideEvery,
+      effectiveCron: overrideCron ?? decl.cron,
+      effectiveEvery: overrideEvery ?? decl.every,
+      timezone: decl.timezone,
+      overridable: decl.overridable,
+      status: "active",
+      leaderInstanceId: prev?.leaderInstanceId,
+      leaderLeaseUntil: prev?.leaderLeaseUntil,
+      lastRunAt: prev?.lastRunAt,
+      nextRunAt: prev?.nextRunAt,
+      dstAmbiguity: prev?.dstAmbiguity,
+    };
+    await store.put(row);
+    active.push(decl.name);
+  }
+
+  for (const existing of await store.list()) {
+    if (declaredByName.has(existing.name)) continue;
+    if (existing.status === "orphaned") {
+      orphaned.push(existing.name);
+      continue;
+    }
+    const row: CronRow = {
+      ...existing,
+      status: "orphaned",
+    };
+    await store.put(row);
+    orphaned.push(existing.name);
+  }
+
+  return {
+    active,
+    orphaned,
+    rows: await store.list(),
+  };
+}
+
+/**
+ * Effective schedule the scheduler must read — from the Store, not code.
+ *
+ * @param row - Reconciled row
+ */
+export function effectiveSchedule(row: CronRow): {
+  readonly cron?: string;
+  readonly every?: string;
+  readonly timezone: string;
+} {
+  return {
+    cron: row.effectiveCron,
+    every: row.effectiveEvery,
+    timezone: row.timezone,
+  };
+}
+
+/**
+ * In-memory cron store for tests / memory clock driver.
+ *
+ * @param seed - Optional initial rows
+ */
+export function createMemoryCronStore(
+  seed?: readonly CronRow[],
+): CronStore {
+  const rows = new Map<string, CronRow>();
+  for (const r of seed ?? []) {
+    rows.set(r.name, structuredClone(r));
+  }
+
+  /** Per-name mutex chain for atomic lease acquires. */
+  const locks = new Map<string, Promise<void>>();
+
+  async function withLock<T>(name: string, fn: () => T | Promise<T>): Promise<T> {
+    const prev = locks.get(name) ?? Promise.resolve();
+    let release!: () => void;
+    const gate = new Promise<void>((resolve) => {
+      release = resolve;
+    });
+    locks.set(
+      name,
+      prev.then(() => gate),
+    );
+    await prev;
+    try {
+      return await fn();
+    } finally {
+      release();
+    }
+  }
+
+  return {
+    async get(name) {
+      const r = rows.get(name);
+      return r ? structuredClone(r) : undefined;
+    },
+    async put(row) {
+      rows.set(row.name, structuredClone(row));
+    },
+    async list() {
+      return [...rows.values()].map((r) => structuredClone(r));
+    },
+    async acquireLease(name, instanceId, now, leaseMs) {
+      return withLock(name, () => {
+        const row = rows.get(name);
+        if (!row) return false;
+        const held =
+          row.leaderLeaseUntil !== undefined &&
+          row.leaderLeaseUntil > now &&
+          row.leaderInstanceId !== undefined &&
+          row.leaderInstanceId !== instanceId;
+        if (held) return false;
+        rows.set(name, {
+          ...row,
+          leaderInstanceId: instanceId,
+          leaderLeaseUntil: now + leaseMs,
+        });
+        return true;
+      });
+    },
+  };
+}

package/src/elements/clock/runtime.ts

@@ -0,0 +1,243 @@
+/**
+ * Clock runtime — reconciliation, leader-elected scheduling, time travel.
+ *
+ * The scheduler reads the effective state from the Store after boot
+ * reconciliation (console §5). Crons leader-elect so N instances do not
+ * duplicate (unified-theory · Clone).
+ */
+
+import type { ClockDecl } from "./declare.ts";
+import { detectDstAmbiguity } from "./dst.ts";
+import { parseDurationMs } from "./duration.ts";
+import { tryAcquireLease } from "./leader.ts";
+import {
+  createMemoryCronStore,
+  effectiveSchedule,
+  reconcileClocks,
+  type CronRow,
+  type CronStore,
+  type ReconcileResult,
+} from "./reconcile.ts";
+import { createTimeTravel, type TimeTravel } from "./time-travel.ts";
+
+/** Handler invoked when a cron fires. */
+export type CronHandler = (cron: CronRow) => void | Promise<void>;
+
+/** Options for {@link createClockRuntime}. */
+export interface CreateClockRuntimeOptions {
+  /** This instance's id (leader election). */
+  readonly instanceId?: string;
+  /** Cron store (`oke_crons`). Defaults to in-memory. */
+  readonly store?: CronStore;
+  /** Injectable clock (frozen / time-travel in tests). */
+  readonly now?: () => number;
+  /** Leader lease TTL (default 30s). */
+  readonly leaseMs?: number;
+  /**
+   * Optional frozen clock — when set, {@link ClockRuntime.advance} moves it
+   * and {@link ClockRuntime.now} reads it.
+   */
+  readonly timeTravel?: TimeTravel;
+}
+
+/** Clock runtime. */
+export interface ClockRuntime {
+  /** Instance id used for leases. */
+  readonly instanceId: string;
+  /** Cron store the scheduler reads. */
+  readonly store: CronStore;
+  /** Current epoch-ms. */
+  now(): number;
+  /**
+   * Advance a time-travel clock (no-op when not frozen).
+   *
+   * @param by - Duration string or ms
+   */
+  advance(by: string | number): number;
+  /**
+   * Register a declared clock (pre-reconcile).
+   *
+   * @param decl - From {@link clock}
+   */
+  register(decl: ClockDecl): void;
+  /** Registered declarations. */
+  readonly declarations: ReadonlyMap<string, ClockDecl>;
+  /**
+   * Reconcile declarations into the Store. Marks removed crons orphaned.
+   */
+  reconcile(): Promise<ReconcileResult>;
+  /**
+   * Attach a handler for a cron name (reads effective schedule from Store).
+   *
+   * @param name - Cron name
+   * @param handler - Fired when due and this instance holds the lease
+   */
+  onCron(name: string, handler: CronHandler): void;
+  /**
+   * Tick the scheduler once: for each active non-orphaned cron that is due,
+   * try to acquire the lease and run the handler at most once across instances.
+   *
+   * @param until - Optional horizon; defaults to `now()`
+   */
+  tick(until?: number): Promise<{ readonly ran: readonly string[] }>;
+  /**
+   * Run a named cron now (still requires the lease — three instances → one run).
+   *
+   * @param name - Cron name
+   */
+  runNow(name: string): Promise<boolean>;
+  /**
+   * DST ambiguity for a store row (expression + zone).
+   *
+   * @param name - Cron name
+   */
+  dstAmbiguity(name: string): Promise<ReturnType<typeof detectDstAmbiguity>>;
+}
+
+/**
+ * Create a clock runtime.
+ *
+ * @param options - Instance id, store, clock
+ */
+export function createClockRuntime(
+  options: CreateClockRuntimeOptions = {},
+): ClockRuntime {
+  const timeTravel = options.timeTravel;
+  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;
+  const declarations = new Map<string, ClockDecl>();
+  const handlers = new Map<string, CronHandler>();
+
+  async function fire(name: string): Promise<boolean> {
+    const row = await store.get(name);
+    if (!row || row.status === "orphaned" || row.status === "paused") {
+      return false;
+    }
+    const t = now();
+    // One execution per lease window — even the leader cannot double-fire.
+    if (
+      row.leaderLeaseUntil !== undefined &&
+      row.leaderLeaseUntil > t &&
+      row.lastRunAt !== undefined
+    ) {
+      const leaseStart = row.leaderLeaseUntil - leaseMs;
+      if (row.lastRunAt >= leaseStart) return false;
+    }
+    const acquired = await tryAcquireLease({
+      name,
+      instanceId,
+      now: t,
+      leaseMs,
+      store,
+    });
+    if (!acquired) return false;
+
+    const handler = handlers.get(name);
+    const fresh = (await store.get(name))!;
+    if (handler) await handler(fresh);
+    await store.put({
+      ...fresh,
+      lastRunAt: now(),
+    });
+    return true;
+  }
+
+  function isDue(row: CronRow, until: number): boolean {
+    if (row.status !== "active") return false;
+    const sched = effectiveSchedule(row);
+    if (sched.every) {
+      const interval = parseDurationMs(sched.every);
+      if (interval <= 0) return false;
+      if (row.lastRunAt === undefined) return true;
+      return row.lastRunAt + interval <= until;
+    }
+    if (sched.cron) {
+      // Interval-free cron: due when nextRunAt is unset or <= until.
+      // Tests drive `runNow` / first tick; production would compute next fire.
+      if (row.nextRunAt !== undefined) return row.nextRunAt <= until;
+      return row.lastRunAt === undefined;
+    }
+    return false;
+  }
+
+  const runtime: ClockRuntime = {
+    instanceId,
+    store,
+    declarations,
+    now,
+    advance(by) {
+      if (!timeTravel) {
+        throw new Error("clock.advance requires a time-travel harness");
+      }
+      return timeTravel.advance(by);
+    },
+    register(decl) {
+      declarations.set(decl.name, decl);
+    },
+    async reconcile() {
+      const result = await reconcileClocks([...declarations.values()], store);
+      // Attach DST warnings for active cron expressions.
+      for (const row of result.rows) {
+        if (row.status !== "active") continue;
+        const cronExpr = row.effectiveCron;
+        if (!cronExpr) continue;
+        const amb = detectDstAmbiguity(cronExpr, row.timezone, now());
+        if (amb) {
+          await store.put({
+            ...row,
+            dstAmbiguity: {
+              kind: amb.kind,
+              reason: amb.reason,
+              on: amb.on,
+              localTime: amb.localTime,
+            },
+          });
+        }
+      }
+      return {
+        ...result,
+        rows: await store.list(),
+      };
+    },
+    onCron(name, handler) {
+      handlers.set(name, handler);
+    },
+    async tick(until) {
+      const horizon = until ?? now();
+      const ran: string[] = [];
+      for (const row of await store.list()) {
+        if (!isDue(row, horizon)) continue;
+        if (await fire(row.name)) ran.push(row.name);
+      }
+      return { ran };
+    },
+    async runNow(name) {
+      return fire(name);
+    },
+    async dstAmbiguity(name) {
+      const row = await store.get(name);
+      if (!row?.effectiveCron) return null;
+      return detectDstAmbiguity(row.effectiveCron, row.timezone, now());
+    },
+  };
+
+  return runtime;
+}
+
+/**
+ * Create a clock runtime with a frozen time-travel harness.
+ *
+ * @param start - Initial epoch-ms
+ * @param options - Extra runtime options
+ */
+export function createTestClockRuntime(
+  start = 0,
+  options: Omit<CreateClockRuntimeOptions, "timeTravel" | "now"> = {},
+): ClockRuntime & { readonly timeTravel: TimeTravel } {
+  const timeTravel = createTimeTravel(start);
+  const runtime = createClockRuntime({ ...options, timeTravel });
+  return Object.assign(runtime, { timeTravel });
+}