okengine 0.15.2 → 0.17.0

package/src/drivers/signal-postgres.ts

@@ -9,10 +9,12 @@ import type { SignalDecl } from "../elements/signal/declare.ts";
 import type { SignalDelivery } from "../manifest/types.ts";
 import { DryRunWriteIsolationError, setDryRunMessageId, withDryRun } from "../kernel/dry-run.ts";
 import { OkeError, OKE_ERRORS } from "../kernel/errors.ts";
+import { LIVE_RESUME_GAP } from "../kernel/errors-live-resume.ts";
 import {
   SIGNAL_DEFAULT_LEASE_MS,
   validateSignalEmitPayload,
   type DeadLetter,
+  type LiveEvent,
   type LiveHandler,
   type SignalBus,
   type SignalDiscardOptions,
@@ -27,7 +29,10 @@ import {
   type SignalStats,
   type SignalTransaction,
   type SignalUnsubscribe,
+  type LiveSubscribeOptions,
 } from "./signal-types.ts";
+import { createLiveIterable } from "./signal-live-iter.ts";
+import { liveIdsToPrune, skipAfterId } from "./signal-retention.ts";
 
 /** Row shape in `oke_signal_messages`. */
 interface MsgRow {
@@ -261,6 +266,23 @@ export function createPostgresSignalFake(options?: {
       const state = view();
 
       if (/^CREATE\s+TABLE/i.test(text)) return { changes: 0 };
+      if (/^CREATE\s+INDEX/i.test(text)) return { changes: 0 };
+
+      const delLive =
+        /^DELETE\s+FROM\s+oke_signal_messages\s+WHERE\s+id\s*=\s*\?\s+AND\s+delivery\s*=\s*'live'\s*$/i.exec(
+          text,
+        );
+      if (delLive) {
+        let changes = 0;
+        for (let i = state.messages.length - 1; i >= 0; i--) {
+          const m = state.messages[i]!;
+          if (m.id === params[0] && m.delivery === "live") {
+            state.messages.splice(i, 1);
+            changes += 1;
+          }
+        }
+        return { changes };
+      }
 
       const delDead =
         /^DELETE\s+FROM\s+oke_signal_messages\s+WHERE\s+id\s*=\s*\?\s+AND\s+signal\s*=\s*\?\s+AND\s+status\s*=\s*'dead'\s*$/i.exec(
@@ -440,6 +462,13 @@ async function ensureSchema(sql: PostgresSignalSql): Promise<void> {
     key TEXT PRIMARY KEY,
     value TEXT
   )`);
+  try {
+    await sql.exec(
+      `CREATE INDEX IF NOT EXISTS oke_signal_messages_live_created ON oke_signal_messages (signal, delivery, created_at)`,
+    );
+  } catch {
+    /* fake / older engines without IF NOT EXISTS — ignore */
+  }
 }
 
 function rowToMessage(row: Record<string, unknown>): SignalMessage {
@@ -687,27 +716,71 @@ export async function openPostgresSignal(options: SignalOpenOptions): Promise<Si
     };
   }
 
-  async function live(signal: string, handler: LiveHandler): Promise<SignalUnsubscribe> {
+  function live(signal: string, opts?: LiveSubscribeOptions): AsyncIterable<LiveEvent> {
     const decl = requireDecl(signal);
     if (decl.delivery !== "live") {
       throw new Error(`signal "${signal}" is not delivery: "live"`);
     }
-    let set = liveHandlers.get(signal);
-    if (!set) {
-      set = new Set();
-      liveHandlers.set(signal, set);
+    const afterId = opts?.afterId;
+    return createLiveIterable(async (emit) => {
+      await pruneLive(signal);
+      const historyRows = await sql.query(
+        `SELECT * FROM oke_signal_messages WHERE signal = ? AND delivery = 'live' ORDER BY created_at ASC`,
+        [signal],
+      );
+      const history: LiveEvent[] = historyRows.map((row) => ({
+        id: String(row.id),
+        payload: JSON.parse(String(row.payload)),
+      }));
+      const skipped = skipAfterId(history, afterId);
+      if (afterId !== undefined && afterId.length > 0 && !skipped.found) {
+        throw new OkeError(LIVE_RESUME_GAP, { signal, afterId });
+      }
+      let set = liveHandlers.get(signal);
+      if (!set) {
+        set = new Set();
+        liveHandlers.set(signal, set);
+      }
+      const handler: LiveHandler = (event) => {
+        emit(event);
+      };
+      set.add(handler);
+      for (const event of skipped.rest) {
+        emit(event);
+      }
+      return () => {
+        set.delete(handler);
+      };
+    });
+  }
+
+  async function checkLiveResume(signal: string, afterId: string): Promise<void> {
+    requireDecl(signal);
+    await pruneLive(signal);
+    const history = await sql.query(
+      `SELECT * FROM oke_signal_messages WHERE signal = ? AND delivery = 'live' ORDER BY created_at ASC`,
+      [signal],
+    );
+    if (!history.some((row) => String(row.id) === afterId)) {
+      throw new OkeError(LIVE_RESUME_GAP, { signal, afterId });
     }
-    set.add(handler);
+  }
+
+  async function pruneLive(signal: string): Promise<void> {
+    const decl = signals.get(signal);
+    if (decl?.retention === undefined) return;
     const history = await sql.query(
       `SELECT * FROM oke_signal_messages WHERE signal = ? AND delivery = 'live' ORDER BY created_at ASC`,
       [signal],
     );
-    for (const row of history) {
-      await handler(JSON.parse(String(row.payload)));
+    const drop = liveIdsToPrune(
+      history.map((row) => ({ id: String(row.id), createdAt: Number(row.created_at) })),
+      decl.retention,
+      now(),
+    );
+    for (const id of drop) {
+      await sql.exec(`DELETE FROM oke_signal_messages WHERE id = ? AND delivery = 'live'`, [id]);
     }
-    return () => {
-      set!.delete(handler);
-    };
   }
 
   async function deliverOnce(
@@ -830,7 +903,8 @@ export async function openPostgresSignal(options: SignalOpenOptions): Promise<Si
       const handlers = liveHandlers.get(String(row.signal));
       const payload = JSON.parse(String(row.payload));
       if (handlers) {
-        for (const h of handlers) await h(payload);
+        const event: LiveEvent = { id: String(row.id), payload };
+        for (const h of handlers) await h(event);
       }
       const sig = String(row.signal);
       let list = recentLive.get(sig);
@@ -846,6 +920,14 @@ export async function openPostgresSignal(options: SignalOpenOptions): Promise<Si
         [row.id],
       );
     }
+    const pruned = new Set<string>();
+    for (const row of pending) {
+      if (row.delivery !== "live") continue;
+      const sig = String(row.signal);
+      if (pruned.has(sig)) continue;
+      pruned.add(sig);
+      await pruneLive(sig);
+    }
     return progress;
   }
 
@@ -1114,6 +1196,7 @@ export async function openPostgresSignal(options: SignalOpenOptions): Promise<Si
     begin,
     subscribe,
     live,
+    checkLiveResume,
     drain,
     deadLetters,
     inspect,

package/src/drivers/signal-redis.ts

@@ -253,7 +253,8 @@ export async function openRedisSignal(options: SignalOpenOptions): Promise<Signa
       };
     },
     subscribe: (signal, subscriberId, handler) => outbox.subscribe(signal, subscriberId, handler),
-    live: (signal, handler) => outbox.live(signal, handler),
+    live: (signal, opts) => outbox.live(signal, opts),
+    checkLiveResume: (signal, afterId) => outbox.checkLiveResume(signal, afterId),
     drain: () => outbox.drain(),
     deadLetters: (s) => outbox.deadLetters(s),
     inspect: (s) => outbox.inspect(s),

package/src/drivers/signal-retention.ts

@@ -0,0 +1,64 @@
+/**
+ * Live-tape retention — which history rows survive `maxAge` / `maxCount`.
+ *
+ * AND-combined when both are set. Omitted retention is unbounded.
+ */
+
+import { parseDurationMs } from "../elements/clock/duration.ts";
+import type { SignalRetention } from "../elements/signal/declare.ts";
+
+/** One live history row used to decide prune vs keep. */
+export interface LiveRetentionRow {
+  readonly id: string;
+  readonly createdAt: number;
+}
+
+/**
+ * Ids that fall outside {@link SignalRetention} (oldest first among drops).
+ *
+ * @param rows - Live rows for one signal
+ * @param retention - Declared cap; omit or empty = keep all
+ * @param now - Clock ms
+ */
+export function liveIdsToPrune(
+  rows: readonly LiveRetentionRow[],
+  retention: SignalRetention | undefined,
+  now: number,
+): string[] {
+  if (retention === undefined) return [];
+  const maxAge = retention.maxAge;
+  const maxCount = retention.maxCount;
+  if (maxAge === undefined && maxCount === undefined) return [];
+
+  const indexed = rows.map((row, index) => ({ ...row, index }));
+  const sorted = indexed.toSorted((a, b) => a.createdAt - b.createdAt || a.index - b.index);
+  let keep = sorted;
+  if (maxAge !== undefined) {
+    const windowMs = parseDurationMs(maxAge);
+    const cutoff = now - windowMs;
+    keep = keep.filter((row) => row.createdAt >= cutoff);
+  }
+  if (maxCount !== undefined) {
+    keep = keep.slice(-maxCount);
+  }
+  const keepIds = new Set(keep.map((row) => row.id));
+  return sorted.filter((row) => !keepIds.has(row.id)).map((row) => row.id);
+}
+
+/**
+ * Exclusive skip through `afterId` on a snapshot already ordered oldest-first.
+ *
+ * @param rows - Tape snapshot
+ * @param afterId - SSE cursor; omit = full tape
+ */
+export function skipAfterId<T extends { readonly id: string }>(
+  rows: readonly T[],
+  afterId: string | undefined,
+): { readonly found: boolean; readonly rest: readonly T[] } {
+  if (afterId === undefined || afterId.length === 0) {
+    return { found: true, rest: rows };
+  }
+  const idx = rows.findIndex((row) => row.id === afterId);
+  if (idx < 0) return { found: false, rest: rows };
+  return { found: true, rest: rows.slice(idx + 1) };
+}

package/src/drivers/signal-types.ts

@@ -189,8 +189,25 @@ export type SignalUnsubscribe = () => void | Promise<void>;
 /** Consumer handler for once / broadcast. */
 export type SignalHandler = (message: SignalMessage) => void | Promise<void>;
 
-/** Live client handler (payload only). */
-export type LiveHandler = (payload: unknown) => void | Promise<void>;
+/** One retained or live-pushed event from {@link SignalBus.live}. */
+export interface LiveEvent {
+  /** Durable message id (SSE `id:`). */
+  readonly id: string;
+  /** Signal payload. */
+  readonly payload: unknown;
+}
+
+/** Options for {@link SignalBus.live}. */
+export interface LiveSubscribeOptions {
+  /**
+   * Exclusive SSE cursor — replay events after this id, then continue.
+   * Omit for the full retained tape. Unknown / pruned ids throw OKE1014.
+   */
+  readonly afterId?: string;
+}
+
+/** Live subscriber (payload + id). */
+export type LiveHandler = (event: LiveEvent) => void | Promise<void>;
 
 /**
  * Transaction that enrols store writes and signal emits atomically.
@@ -313,10 +330,23 @@ export interface SignalBus {
   /**
    * Client-subscribable live feed.
    *
-   * @param signal - Signal name (`delivery: "live"`)
-   * @param handler - Payload handler
+   * Replays retained history, then yields new events until the iterator
+   * returns. `delivery` must be `"live"`. `afterId` skips through that
+   * id (exclusive); unknown or pruned ids throw OKE1014.
+   *
+   * @param signal - Signal name
+   * @param opts - Optional resume cursor
+   */
+  live(signal: string, opts?: LiveSubscribeOptions): AsyncIterable<LiveEvent>;
+  /**
+   * Validate a live resume cursor without waiting for new events.
+   *
+   * Prunes the tape first. Throws OKE1014 when `afterId` is absent.
+   *
+   * @param signal - Signal name
+   * @param afterId - SSE cursor
    */
-  live(signal: string, handler: LiveHandler): Promise<SignalUnsubscribe>;
+  checkLiveResume(signal: string, afterId: string): Promise<void>;
   /**
    * Process pending work until idle (deterministic tests).
    */

package/src/elements/clock/declare.ts

@@ -22,6 +22,11 @@ export interface ClockOptions {
   readonly overridable?: boolean;
   /** Optional human description for Console / docs (falls back to the clock name). */
   readonly description?: string;
+  /**
+   * Expand one `oke_crons` row per tenant (`{name}#{tenantId}`).
+   * The bare template name is never ticked.
+   */
+  readonly perTenant?: boolean;
 }
 
 /**
@@ -40,6 +45,8 @@ export interface ClockDecl {
   readonly overridable: boolean;
   /** Optional human description. */
   readonly description?: string;
+  /** When true, reconcile expands `{name}#{tenantId}` rows. */
+  readonly perTenant?: boolean;
 }
 
 /**
@@ -67,9 +74,9 @@ export function resetClocks(): void {
  * Declare a named clock / cron schedule.
  *
  * @param name - Schedule name
- * @param options - `cron` and/or `every`, timezone, overridable
+ * @param options - `cron` and/or `every`, timezone, overridable, perTenant
  */
-export function clock(name: string, options: ClockOptions = {}): ClockDecl {
+function declareClock(name: string, options: ClockOptions = {}): ClockDecl {
   if (!options.cron && !options.every) {
     throw new TypeError(`clock("${name}"): require cron or every`);
   }
@@ -80,7 +87,62 @@ export function clock(name: string, options: ClockOptions = {}): ClockDecl {
     timezone: options.timezone ?? "UTC",
     overridable: options.overridable ?? false,
     ...(options.description !== undefined ? { description: options.description } : {}),
+    ...(options.perTenant === true ? { perTenant: true } : {}),
   };
   clockRegistry.push(decl);
   return decl;
 }
+
+/**
+ * Per-tenant schedule template — one `oke_crons` row per tenant.
+ *
+ * @param name - Template name
+ * @param options - Same as {@link clock}
+ */
+function declarePerTenantClock(name: string, options: ClockOptions = {}): ClockDecl {
+  return declareClock(name, { ...options, perTenant: true });
+}
+
+/**
+ * Separator between a per-tenant template name and the tenant id.
+ */
+export const PER_TENANT_CRON_SEP = "#";
+
+/**
+ * Physical cron row name for a per-tenant template.
+ *
+ * @param template - Declared clock name
+ * @param tenantId - Tenant id
+ */
+export function perTenantCronName(template: string, tenantId: string): string {
+  return `${template}${PER_TENANT_CRON_SEP}${tenantId}`;
+}
+
+/**
+ * Parse `{template}#{tenantId}` when `template` is a known per-tenant clock.
+ *
+ * @param name - Store row name
+ * @param templates - Per-tenant template names
+ */
+export function parsePerTenantCronName(
+  name: string,
+  templates?: ReadonlySet<string>,
+): { readonly template: string; readonly tenantId: string } | null {
+  const i = name.lastIndexOf(PER_TENANT_CRON_SEP);
+  if (i <= 0) return null;
+  const template = name.slice(0, i);
+  const tenantId = name.slice(i + 1);
+  if (!tenantId) return null;
+  if (templates && !templates.has(template)) return null;
+  return { template, tenantId };
+}
+
+/**
+ * Declare a named clock / cron schedule.
+ *
+ * @param name - Schedule name
+ * @param options - `cron` and/or `every`, timezone, overridable
+ */
+export const clock: ((name: string, options?: ClockOptions) => ClockDecl) & {
+  readonly perTenant: typeof declarePerTenantClock;
+} = Object.assign(declareClock, { perTenant: declarePerTenantClock });

package/src/elements/clock/reconcile.ts

@@ -15,6 +15,7 @@ import { mkdir, rename, rm, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 
 import type { ClockDecl } from "./declare.ts";
+import { parsePerTenantCronName, perTenantCronName } from "./declare.ts";
 
 /** Cron lifecycle status in `oke_crons`. */
 export type CronStatus = "active" | "paused" | "orphaned";
@@ -86,54 +87,60 @@ export interface ReconcileResult {
   readonly rows: readonly CronRow[];
 }
 
+/** Extra inputs for {@link reconcileClocks}. */
+export interface ReconcileClocksOptions {
+  /** Tenant ids used to expand {@link ClockDecl.perTenant} templates. */
+  readonly tenantIds?: readonly string[];
+}
+
 /**
  * Reconcile declared clocks into the Store.
  *
  * - Declared schedules are upserted (`status: "active"`).
+ * - Per-tenant templates expand to `{template}#{tenantId}` before the orphan pass.
+ * - The bare template name is never put (never ticked).
  * - 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`)
+ * @param options - Tenant expansion
  */
 export async function reconcileClocks(
   declared: readonly ClockDecl[],
   store: CronStore,
+  options: ReconcileClocksOptions = {},
 ): Promise<ReconcileResult> {
-  const declaredByName = new Map(declared.map((d) => [d.name, d]));
+  const tenantIds = options.tenantIds ?? [];
+  const declaredByName = new Map<string, ClockDecl>();
   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);
+    if (decl.perTenant === true) {
+      for (const tenantId of tenantIds) {
+        const name = perTenantCronName(decl.name, tenantId);
+        declaredByName.set(name, decl);
+        await putActiveRow(store, decl, name);
+        active.push(name);
+      }
+      continue;
+    }
+    declaredByName.set(decl.name, decl);
+    await putActiveRow(store, decl, decl.name);
     active.push(decl.name);
   }
 
+  const perTenantTemplates = new Set(
+    declared.filter((d) => d.perTenant === true).map((d) => d.name),
+  );
+
   for (const existing of await store.list()) {
     if (declaredByName.has(existing.name)) continue;
+    const parsed = parsePerTenantCronName(existing.name, perTenantTemplates);
+    if (parsed && existing.status === "active") {
+      // Expansion already listed current tenants; leftover ids orphan.
+    }
     if (existing.status === "orphaned") {
       orphaned.push(existing.name);
       continue;
@@ -153,6 +160,72 @@ export async function reconcileClocks(
   };
 }
 
+/**
+ * Expand per-tenant templates for a newly created tenant (preserve lease).
+ *
+ * @param store - Cron store
+ * @param templates - Clock decls (`perTenant` only applied)
+ * @param tenantId - Tenant id
+ */
+export async function putPerTenantCronRows(
+  store: CronStore,
+  templates: readonly ClockDecl[],
+  tenantId: string,
+): Promise<void> {
+  for (const decl of templates) {
+    if (decl.perTenant !== true) continue;
+    await putActiveRow(store, decl, perTenantCronName(decl.name, tenantId));
+  }
+}
+
+/**
+ * Mark per-tenant rows orphaned when a tenant is deleted.
+ *
+ * @param store - Cron store
+ * @param templates - Clock decls
+ * @param tenantId - Tenant id
+ */
+export async function orphanPerTenantCronRows(
+  store: CronStore,
+  templates: readonly ClockDecl[],
+  tenantId: string,
+): Promise<void> {
+  for (const decl of templates) {
+    if (decl.perTenant !== true) continue;
+    const name = perTenantCronName(decl.name, tenantId);
+    const row = await store.get(name);
+    if (!row || row.status === "orphaned") continue;
+    await store.put({ ...row, status: "orphaned" });
+  }
+}
+
+async function putActiveRow(store: CronStore, decl: ClockDecl, name: string): Promise<void> {
+  const prev = await store.get(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,
+    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);
+}
+
 /**
  * Effective schedule the scheduler must read — from the Store, not code.
  *

package/src/elements/clock/runtime.ts

@@ -40,6 +40,8 @@ export interface CreateClockRuntimeOptions {
    * and {@link ClockRuntime.now} reads it.
    */
   readonly timeTravel?: TimeTravel;
+  /** Tenant ids for {@link ClockDecl.perTenant} expansion at reconcile. */
+  readonly tenantIds?: () => readonly string[] | Promise<readonly string[]>;
 }
 
 /** Clock runtime. */
@@ -178,11 +180,19 @@ export function createClockRuntime(options: CreateClockRuntimeOptions = {}): Clo
       nextRunAt,
     });
 
-    const handler = handlers.get(name);
+    const template = templateNameOf(name);
+    const handler = handlers.get(name) ?? (template ? handlers.get(template) : undefined);
     if (handler) await handler(fresh);
     return true;
   }
 
+  function templateNameOf(rowName: string): string | undefined {
+    const i = rowName.lastIndexOf("#");
+    if (i <= 0) return undefined;
+    const template = rowName.slice(0, i);
+    return declarations.has(template) ? template : undefined;
+  }
+
   function isDue(row: CronRow, until: number): boolean {
     if (row.status !== "active") return false;
     const sched = effectiveSchedule(row);
@@ -217,7 +227,8 @@ export function createClockRuntime(options: CreateClockRuntimeOptions = {}): Clo
       declarations.set(decl.name, decl);
     },
     async reconcile() {
-      const result = await reconcileClocks([...declarations.values()], store);
+      const tenantIds = (await options.tenantIds?.()) ?? [];
+      const result = await reconcileClocks([...declarations.values()], store, { tenantIds });
       // Attach DST warnings for active cron expressions.
       for (const row of result.rows) {
         if (row.status !== "active") continue;

package/src/elements/clock.test.ts

@@ -299,6 +299,34 @@ describe("reconciliation", () => {
     expect(ranOrphan).toBe(false);
   });
 
+  test("per-tenant templates expand to {name}#{id} and never put the bare name", async () => {
+    const store = createMemoryCronStore();
+    const invoices = clock.perTenant("invoices", { every: "1h" });
+    const result = await reconcileClocks([invoices], store, { tenantIds: ["acme", "globex"] });
+    expect([...result.active].sort()).toEqual(["invoices#acme", "invoices#globex"]);
+    expect(await store.get("invoices")).toBeUndefined();
+    expect((await store.get("invoices#acme"))?.status).toBe("active");
+
+    const rt = createTestClockRuntime(0, {
+      store,
+      instanceId: "solo",
+      tenantIds: () => ["acme", "globex"],
+    });
+    rt.register(invoices);
+    let bare = 0;
+    let expanded = 0;
+    rt.onCron("invoices", () => {
+      bare += 1;
+    });
+    rt.onCron("invoices#acme", () => {
+      expanded += 1;
+    });
+    expect(await rt.runNow("invoices")).toBe(false);
+    expect(bare).toBe(0);
+    expect(await rt.runNow("invoices#acme")).toBe(true);
+    expect(expanded).toBe(1);
+  });
+
   test("scheduler reads effective state from the store", async () => {
     const store = createMemoryCronStore();
     const rt = createTestClockRuntime(0, { store, instanceId: "s1" });

package/src/elements/clock.ts

@@ -10,7 +10,12 @@
  * @module
  */
 
-export { clock } from "./clock/declare.ts";
+export {
+  clock,
+  perTenantCronName,
+  parsePerTenantCronName,
+  PER_TENANT_CRON_SEP,
+} from "./clock/declare.ts";
 export type { ClockDecl, ClockOptions } from "./clock/declare.ts";
 
 export { parseDurationMs } from "./clock/duration.ts";
@@ -27,6 +32,8 @@ export {
 
 export {
   reconcileClocks,
+  putPerTenantCronRows,
+  orphanPerTenantCronRows,
   effectiveSchedule,
   createMemoryCronStore,
   createFileCronStore,
@@ -34,6 +41,7 @@ export {
   type CronStatus,
   type CronStore,
   type ReconcileResult,
+  type ReconcileClocksOptions,
 } from "./clock/reconcile.ts";
 
 export { createTimeTravel, type TimeTravel } from "./clock/time-travel.ts";

package/src/elements/gate/declare.ts

@@ -19,6 +19,8 @@ export interface GatePolicyContext {
     readonly userId: string | null;
     readonly scopes: ReadonlySet<string>;
     readonly verified?: boolean;
+    /** Authenticating API key id when the principal is a key; otherwise omitted. */
+    readonly apiKeyId?: string | null;
   };
   /** Operator-plane principal (`fx.operator`). */
   readonly operator: {