@yieldstar/sqlite-runtime 0.5.0 → 0.6.1

package/src/dao/executions-dao.ts

@@ -0,0 +1,199 @@
+import type { ExecutionState } from "@yieldstar/core";
+import { nextClaimAt } from "@yieldstar/core";
+import type { SqliteDriver } from "../sqlite-driver";
+
+class ExecutionRow {
+  execution_id!: string;
+  workflow_id!: string;
+  params!: string;
+  context!: string;
+  status!: ExecutionState["status"];
+  outcome!: string | null;
+  admitted_at!: number;
+  updated_at!: number;
+  due_at!: number | null;
+  claimed_due_at!: number | null;
+  lease_token!: number;
+  lease_expires_at!: number | null;
+  unacknowledged_delivery_count!: number;
+  redeliver_at!: number | null;
+  next_claim_at!: number | null;
+  parent_execution_id!: string | null;
+  parent_step_key!: string | null;
+}
+
+class ExecutionIdRow {
+  execution_id!: string;
+}
+
+/**
+ * Persists every ExecutionState field, plus `next_claim_at` (derived with
+ * nextClaimAt) so claimDue can find due executions through an index.
+ * Callers own the surrounding transaction.
+ */
+export class ExecutionsDao {
+  private db: SqliteDriver;
+
+  constructor(db: SqliteDriver) {
+    this.db = db;
+    this.setupDb();
+  }
+
+  setupDb() {
+    this.db.run(`
+      CREATE TABLE IF NOT EXISTS executions (
+        execution_id TEXT PRIMARY KEY,
+        workflow_id TEXT NOT NULL,
+        params TEXT NOT NULL,
+        context TEXT NOT NULL,
+        status TEXT NOT NULL,
+        outcome TEXT,
+        admitted_at INTEGER NOT NULL,
+        updated_at INTEGER NOT NULL,
+        due_at INTEGER,
+        claimed_due_at INTEGER,
+        lease_token INTEGER NOT NULL DEFAULT 0,
+        lease_expires_at INTEGER,
+        unacknowledged_delivery_count INTEGER NOT NULL DEFAULT 0,
+        redeliver_at INTEGER,
+        next_claim_at INTEGER,
+        parent_execution_id TEXT,
+        parent_step_key TEXT
+      );
+      CREATE INDEX IF NOT EXISTS idx_executions_next_claim_at
+      ON executions(next_claim_at) WHERE next_claim_at IS NOT NULL;
+    `);
+  }
+
+  getState(executionId: string): ExecutionState | undefined {
+    const row = this.db
+      .query<ExecutionRow>(
+        `SELECT * FROM executions WHERE execution_id = $executionId`
+      )
+      .get({ $executionId: executionId });
+    return row ? toState(row) : undefined;
+  }
+
+  /**
+   * Up to `limit` claimable execution IDs, earliest due first. `now` is a
+   * millisecond Unix timestamp from the runtime clock. When `executionIds` is
+   * given, only those executions are considered.
+   */
+  getClaimableIds(
+    now: number,
+    limit: number,
+    executionIds?: readonly string[]
+  ) {
+    return this.db
+      .query<ExecutionIdRow>(
+        `SELECT execution_id FROM executions
+         WHERE next_claim_at IS NOT NULL AND next_claim_at <= $now
+           AND ($executionIds IS NULL
+             OR execution_id IN (SELECT value FROM json_each($executionIds)))
+         ORDER BY next_claim_at, execution_id
+         LIMIT $limit`
+      )
+      .all({
+        $now: now,
+        $limit: limit,
+        $executionIds: executionIds ? JSON.stringify(executionIds) : null,
+      })
+      .map((row) => row.execution_id);
+  }
+
+  /** Returns false when the execution ID is already in use. */
+  insertState(state: ExecutionState): boolean {
+    const result = this.db
+      .query(
+        `INSERT INTO executions (
+           execution_id, workflow_id, params, context, status, outcome,
+           admitted_at, updated_at, due_at, claimed_due_at, lease_token,
+           lease_expires_at, unacknowledged_delivery_count, redeliver_at,
+           next_claim_at, parent_execution_id, parent_step_key
+         ) VALUES (
+           $executionId, $workflowId, $params, $context, $status, $outcome,
+           $admittedAt, $updatedAt, $dueAt, $claimedDueAt, $leaseToken,
+           $leaseExpiresAt, $unacknowledgedDeliveryCount, $redeliverAt,
+           $nextClaimAt, $parentExecutionId, $parentStepKey
+         )
+         ON CONFLICT(execution_id) DO NOTHING`
+      )
+      .run({
+        ...toBindings(state),
+        $parentExecutionId: state.parent?.executionId ?? null,
+        $parentStepKey: state.parent?.stepKey ?? null,
+      });
+    return Number(result.changes) === 1;
+  }
+
+  /** Leaves the parent link as inserted: it is immutable. */
+  updateState(state: ExecutionState) {
+    this.db
+      .query(
+        `UPDATE executions SET
+           workflow_id = $workflowId,
+           params = $params,
+           context = $context,
+           status = $status,
+           outcome = $outcome,
+           admitted_at = $admittedAt,
+           updated_at = $updatedAt,
+           due_at = $dueAt,
+           claimed_due_at = $claimedDueAt,
+           lease_token = $leaseToken,
+           lease_expires_at = $leaseExpiresAt,
+           unacknowledged_delivery_count = $unacknowledgedDeliveryCount,
+           redeliver_at = $redeliverAt,
+           next_claim_at = $nextClaimAt
+         WHERE execution_id = $executionId`
+      )
+      .run(toBindings(state));
+  }
+}
+
+function toState(row: ExecutionRow): ExecutionState {
+  return {
+    executionId: row.execution_id,
+    workflowId: row.workflow_id,
+    params: row.params,
+    context: row.context,
+    status: row.status,
+    outcome: row.outcome,
+    admittedAt: Number(row.admitted_at),
+    updatedAt: Number(row.updated_at),
+    dueAt: toNumberOrNull(row.due_at),
+    claimedDueAt: toNumberOrNull(row.claimed_due_at),
+    leaseToken: Number(row.lease_token),
+    leaseExpiresAt: toNumberOrNull(row.lease_expires_at),
+    unacknowledgedDeliveryCount: Number(row.unacknowledged_delivery_count),
+    redeliverAt: toNumberOrNull(row.redeliver_at),
+    parent:
+      row.parent_execution_id !== null && row.parent_step_key !== null
+        ? { executionId: row.parent_execution_id, stepKey: row.parent_step_key }
+        : null,
+  };
+}
+
+function toBindings(state: ExecutionState) {
+  return {
+    $executionId: state.executionId,
+    $workflowId: state.workflowId,
+    $params: state.params,
+    $context: state.context,
+    $status: state.status,
+    $outcome: state.outcome,
+    $admittedAt: state.admittedAt,
+    $updatedAt: state.updatedAt,
+    $dueAt: state.dueAt,
+    $claimedDueAt: state.claimedDueAt,
+    $leaseToken: state.leaseToken,
+    $leaseExpiresAt: state.leaseExpiresAt,
+    $unacknowledgedDeliveryCount: state.unacknowledgedDeliveryCount,
+    $redeliverAt: state.redeliverAt,
+    $nextClaimAt: nextClaimAt(state),
+  };
+}
+
+function toNumberOrNull(value: number | null) {
+  return value === null ? null : Number(value);
+}

package/src/dao/start-requests-dao.ts

@@ -0,0 +1,72 @@
+import type { StartRequestState } from "@yieldstar/core";
+import type { SqliteDriver } from "../sqlite-driver";
+
+class StartRequestRow {
+  caller_execution_id!: string;
+  step_key!: string;
+  workflow_id!: string;
+  params!: string | null;
+  execution_id!: string;
+}
+
+/**
+ * Start requests recorded by `ExecutionClient.start`, keyed by the caller's
+ * execution ID and step key. Callers own the surrounding transaction, which
+ * must also insert the target execution.
+ */
+export class StartRequestsDao {
+  private db: SqliteDriver;
+
+  constructor(db: SqliteDriver) {
+    this.db = db;
+    this.setupDb();
+  }
+
+  setupDb() {
+    this.db.run(`
+      CREATE TABLE IF NOT EXISTS start_requests (
+        caller_execution_id TEXT NOT NULL,
+        step_key TEXT NOT NULL,
+        workflow_id TEXT NOT NULL,
+        params TEXT,
+        execution_id TEXT NOT NULL,
+        PRIMARY KEY (caller_execution_id, step_key)
+      );
+    `);
+  }
+
+  get(callerExecutionId: string, stepKey: string): StartRequestState | undefined {
+    const row = this.db
+      .query<StartRequestRow>(
+        `SELECT * FROM start_requests
+         WHERE caller_execution_id = $callerExecutionId AND step_key = $stepKey`
+      )
+      .get({ $callerExecutionId: callerExecutionId, $stepKey: stepKey });
+    return row
+      ? {
+          callerExecutionId: row.caller_execution_id,
+          stepKey: row.step_key,
+          workflowId: row.workflow_id,
+          params: row.params,
+          executionId: row.execution_id,
+        }
+      : undefined;
+  }
+
+  insert(request: StartRequestState) {
+    this.db
+      .query(
+        `INSERT INTO start_requests
+           (caller_execution_id, step_key, workflow_id, params, execution_id)
+         VALUES
+           ($callerExecutionId, $stepKey, $workflowId, $params, $executionId)`
+      )
+      .run({
+        $callerExecutionId: request.callerExecutionId,
+        $stepKey: request.stepKey,
+        $workflowId: request.workflowId,
+        $params: request.params,
+        $executionId: request.executionId,
+      });
+  }
+}

package/src/dao/step-response-dao.ts

@@ -23,7 +23,7 @@ export class StepResponsesDao {
         step_key TEXT NOT NULL,
         step_attempt INTEGER NOT NULL,
         step_done BOOL NOT NULL,
-        step_response JSONB,
+        step_response TEXT NOT NULL,
         PRIMARY KEY (execution_id, step_key, step_attempt)
       );
       CREATE INDEX IF NOT EXISTS idx_execution_step_attempt 
@@ -57,6 +57,21 @@ export class StepResponsesDao {
     return result;
   }
 
+  getStepResponse(executionId: string, stepKey: string, stepAttempt: number) {
+    return this.db
+      .query<StepReponseRow>(
+        `SELECT * FROM step_responses
+         WHERE execution_id = $executionId
+         AND step_key = $stepKey
+         AND step_attempt = $stepAttempt`
+      )
+      .get({
+        $executionId: executionId,
+        $stepKey: stepKey,
+        $stepAttempt: stepAttempt,
+      });
+  }
+
   insertStepResponse(
     executionId: string,
     stepKey: string,

package/src/dao/store-waiters-dao.ts

@@ -0,0 +1,92 @@
+import type { StoreWaiter } from "@yieldstar/core";
+import type { SqliteDriver } from "../sqlite-driver";
+
+export class StoreWaiterRow {
+  workflow_id!: string;
+  execution_id!: string;
+  step_key!: string;
+  store_name!: string;
+  store_id!: string;
+  since_version!: number;
+  read_paths!: string;
+}
+
+/**
+ * Store waiters live in the same database as step records, so the heap can
+ * delete a waiter in the same transaction that records its step's result.
+ * Callers own the surrounding transaction.
+ */
+export class StoreWaitersDao {
+  private db: SqliteDriver;
+
+  constructor(db: SqliteDriver) {
+    this.db = db;
+    this.setupDb();
+  }
+
+  setupDb() {
+    this.db.run(`
+      CREATE TABLE IF NOT EXISTS store_waiters (
+        workflow_id TEXT NOT NULL,
+        execution_id TEXT NOT NULL,
+        step_key TEXT NOT NULL,
+        store_name TEXT NOT NULL,
+        store_id TEXT NOT NULL,
+        since_version INTEGER NOT NULL,
+        read_paths TEXT NOT NULL,
+        PRIMARY KEY (store_name, store_id, execution_id, step_key)
+      );
+      CREATE INDEX IF NOT EXISTS idx_store_waiters_step
+      ON store_waiters(execution_id, step_key);
+    `);
+  }
+
+  upsertWaiter(waiter: StoreWaiter) {
+    this.db
+      .query(
+        `INSERT INTO store_waiters
+           (workflow_id, execution_id, step_key, store_name, store_id, since_version, read_paths)
+         VALUES
+           ($workflowId, $executionId, $stepKey, $storeName, $storeId, $sinceVersion, $readPaths)
+         ON CONFLICT(store_name, store_id, execution_id, step_key)
+         DO UPDATE SET
+           workflow_id = excluded.workflow_id,
+           since_version = excluded.since_version,
+           read_paths = excluded.read_paths`
+      )
+      .run({
+        $workflowId: waiter.workflowId,
+        $executionId: waiter.executionId,
+        $stepKey: waiter.stepKey,
+        $storeName: waiter.storeName,
+        $storeId: waiter.storeId,
+        $sinceVersion: waiter.sinceVersion,
+        $readPaths: JSON.stringify(waiter.readPaths),
+      });
+  }
+
+  getStoreWaiters(storeName: string, storeId: string) {
+    return this.db
+      .query<StoreWaiterRow>(
+        `SELECT * FROM store_waiters
+         WHERE store_name = $storeName AND store_id = $storeId`
+      )
+      .all({ $storeName: storeName, $storeId: storeId });
+  }
+
+  deleteStoreWaiters(storeName: string, storeId: string) {
+    this.db
+      .query(
+        `DELETE FROM store_waiters WHERE store_name = $storeName AND store_id = $storeId`
+      )
+      .run({ $storeName: storeName, $storeId: storeId });
+  }
+
+  deleteStepWaiters(executionId: string, stepKey: string) {
+    this.db
+      .query(
+        `DELETE FROM store_waiters WHERE execution_id = $executionId AND step_key = $stepKey`
+      )
+      .run({ $executionId: executionId, $stepKey: stepKey });
+  }
+}

package/src/index.ts

@@ -1,9 +1,11 @@
+export { SqliteRuntime, type SqliteRuntimeOptions } from "./sqlite-runtime";
+export {
+  SqliteExecutionClient,
+  type SqliteExecutionClientOptions,
+} from "./sqlite-execution";
+export { SqliteEffectClient } from "./sqlite-effect";
 export { SqliteHeapClient } from "./sqlite-heap";
 export { SqliteStoreClient } from "./sqlite-store";
-export { SqliteSchedulerClient } from "./sqlite-scheduler";
-export { SqliteEventLoop } from "./sqlite-event-loop";
-export { SqliteTaskQueueClient } from "./sqlite-task-queue";
-export { SqliteTimersClient } from "./sqlite-timers";
 export type {
   SqliteDriver,
   SqliteParameters,

package/src/sqlite-effect.ts

@@ -0,0 +1,99 @@
+import {
+  createEffectState,
+  effectNotFound,
+  matchEffectBegin,
+  prepareEffectBegin,
+  prepareEffectSettle,
+  prepareEffectWatch,
+  settleEffect,
+  toEffectRecord,
+  type EffectBeginRequest,
+  type EffectBeginResult,
+  type EffectClient,
+  type EffectRecord,
+  type EffectSettleRequest,
+  type EffectSettleResult,
+  type EffectWatchRequest,
+} from "@yieldstar/core";
+import { EffectWaitersDao } from "./dao/effect-waiters-dao";
+import { EffectsDao } from "./dao/effects-dao";
+import type { SqliteDriver } from "./sqlite-driver";
+import { SqliteExecutionClient } from "./sqlite-execution";
+import { runTransaction } from "./sqlite-transaction";
+
+/**
+ * Effect records and waiters in the same database as the execution records,
+ * so a settlement and the wakes of its waiters commit in one IMMEDIATE
+ * transaction.
+ */
+export class SqliteEffectClient implements EffectClient {
+  private db: SqliteDriver;
+  private executions: SqliteExecutionClient;
+  private effectsDao: EffectsDao;
+  private effectWaitersDao: EffectWaitersDao;
+  private clock: () => number;
+
+  /**
+   * @param params.executions The execution client whose records waiters wake.
+   * Defaults to one over `db` with the default clock; SqliteRuntime passes
+   * its own so both share the runtime clock.
+   */
+  constructor(params: {
+    db: SqliteDriver;
+    executions?: SqliteExecutionClient;
+    clock?: () => number;
+  }) {
+    this.db = params.db;
+    // Read Date.now lazily so fake timers installed later still apply.
+    this.clock = params.clock ?? (() => Date.now());
+    this.executions =
+      params.executions ?? new SqliteExecutionClient(params.db, { clock: this.clock });
+    this.effectsDao = new EffectsDao(params.db);
+    this.effectWaitersDao = new EffectWaitersDao(params.db);
+  }
+
+  async begin(request: EffectBeginRequest): Promise<EffectBeginResult> {
+    const begin = prepareEffectBegin(request);
+    return runTransaction(this.db, () => {
+      const state = this.effectsDao.getState(begin.effectId);
+      if (state) return matchEffectBegin(state, begin);
+      this.effectsDao.insertState(createEffectState(begin));
+      return { status: "new" as const };
+    });
+  }
+
+  async settle(request: EffectSettleRequest): Promise<EffectSettleResult> {
+    const settle = prepareEffectSettle(request);
+    return runTransaction(this.db, () => {
+      const state = this.effectsDao.getState(settle.effectId);
+      if (!state) throw effectNotFound(settle.effectId);
+      const settled = settleEffect(state, settle, this.clock());
+      if (settled.state !== state) this.effectsDao.updateState(state, settled.state);
+      if (settled.wake) {
+        for (const executionId of this.effectWaitersDao.getWaitingExecutionIds(
+          settle.effectId
+        )) {
+          this.executions.wakeInTransaction(executionId);
+        }
+      }
+      return settled.result;
+    });
+  }
+
+  async watch(request: EffectWatchRequest): Promise<void> {
+    const watch = prepareEffectWatch(request);
+    runTransaction(this.db, () => {
+      const state = this.effectsDao.getState(watch.effectId);
+      if (!state) throw effectNotFound(watch.effectId);
+      this.effectWaitersDao.upsertWaiter(watch);
+      if (state.status === "settled") {
+        this.executions.wakeInTransaction(watch.executionId);
+      }
+    });
+  }
+
+  async getEffect(effectId: string): Promise<EffectRecord | undefined> {
+    const state = this.effectsDao.getState(effectId);
+    return state ? toEffectRecord(state) : undefined;
+  }
+}