@yieldstar/sqlite-runtime 0.5.0 → 0.6.0

package/src/sqlite-execution.ts

@@ -0,0 +1,238 @@
+import {
+  acknowledgeExecution,
+  claimExecution,
+  createExecutionState,
+  createStartedExecution,
+  executionIdConflict,
+  executionNotFound,
+  isExecutionClaimable,
+  matchStartRequest,
+  prepareExecutionAdmission,
+  prepareExecutionStart,
+  releaseExecutionLease,
+  renewExecutionLease,
+  requestExecutionWake,
+  toExecutionRecord,
+  type ExecutionAcknowledgeResult,
+  type ExecutionAdmissionRequest,
+  type ExecutionAdmissionResult,
+  type ExecutionClient,
+  type ExecutionLease,
+  type ExecutionRecord,
+  type ExecutionStartRequest,
+  type ExecutionStartResult,
+  type ExecutionReleaseResult,
+  type ExecutionRenewResult,
+  type ExecutionState,
+  type ExecutionWakeResult,
+  type WorkflowRunOutcome,
+} from "@yieldstar/core";
+import { ExecutionsDao } from "./dao/executions-dao";
+import { StartRequestsDao } from "./dao/start-requests-dao";
+import type { SqliteDriver } from "./sqlite-driver";
+import { runTransaction } from "./sqlite-transaction";
+
+export type SqliteExecutionClientOptions = {
+  /** Reads the current time. Defaults to `Date.now`. */
+  clock?: () => number;
+};
+
+/**
+ * Execution records in the `executions` table. Every operation loads a row,
+ * applies a pure transition from @yieldstar/core and writes it back inside one
+ * IMMEDIATE transaction, so processes sharing the database file see the same
+ * semantics as the memory runtime.
+ */
+export class SqliteExecutionClient implements ExecutionClient {
+  private db: SqliteDriver;
+  private executionsDao: ExecutionsDao;
+  private startRequestsDao: StartRequestsDao;
+  private clock: () => number;
+
+  constructor(db: SqliteDriver, options: SqliteExecutionClientOptions = {}) {
+    this.db = db;
+    this.executionsDao = new ExecutionsDao(db);
+    this.startRequestsDao = new StartRequestsDao(db);
+    // Read Date.now lazily so fake timers installed later still apply.
+    this.clock = options.clock ?? (() => Date.now());
+  }
+
+  async admit(
+    request: ExecutionAdmissionRequest
+  ): Promise<ExecutionAdmissionResult> {
+    const prepared = prepareExecutionAdmission(request);
+    if (!prepared.ok) {
+      return {
+        status: "rejected",
+        code: prepared.code,
+        message: prepared.message,
+      };
+    }
+
+    return runTransaction(this.db, () => {
+      const state = createExecutionState({
+        executionId: prepared.executionId,
+        workflowId: request.workflowId,
+        encoded: prepared.encoded,
+        now: this.clock(),
+      });
+      // The record is inserted already due, so it and its first wake commit
+      // together.
+      if (!this.executionsDao.insertState(state)) {
+        return executionIdConflict(prepared.executionId);
+      }
+      return { status: "accepted", executionId: prepared.executionId };
+    });
+  }
+
+  async start(request: ExecutionStartRequest): Promise<ExecutionStartResult> {
+    const prepared = prepareExecutionStart(request);
+    if (!prepared.ok) return prepared.result;
+    const { start } = prepared;
+
+    // The lookup, the target and the start request share one IMMEDIATE
+    // transaction, so concurrent starts with one request ID serialize and a
+    // new start commits all-or-nothing.
+    return runTransaction(this.db, () => {
+      const recorded = this.startRequestsDao.get(
+        start.callerExecutionId,
+        start.stepKey
+      );
+      if (recorded) return matchStartRequest(recorded, start);
+
+      const caller = this.executionsDao.getState(start.callerExecutionId);
+      if (!caller) {
+        throw new Error(
+          `Cannot start a workflow from execution "${start.callerExecutionId}": it does not exist`
+        );
+      }
+      let created = createStartedExecution({ start, caller, now: this.clock() });
+      while (!this.executionsDao.insertState(created.target)) {
+        created = createStartedExecution({ start, caller, now: this.clock() });
+      }
+      this.startRequestsDao.insert(created.startRequest);
+      return {
+        status: "accepted" as const,
+        executionId: created.target.executionId,
+      };
+    });
+  }
+
+  async get(executionId: string): Promise<ExecutionRecord | undefined> {
+    const state = this.executionsDao.getState(executionId);
+    return state ? toExecutionRecord(state, this.clock()) : undefined;
+  }
+
+  async requestWake(request: {
+    executionId: string;
+    wakeAt: number;
+  }): Promise<ExecutionWakeResult> {
+    return runTransaction(this.db, () => {
+      const state = this.executionsDao.getState(request.executionId);
+      if (!state) return executionNotFound(request.executionId);
+
+      const next = requestExecutionWake(state, request.wakeAt, this.clock());
+      if (!next) return { status: "ignored" };
+
+      this.executionsDao.updateState(next);
+      return { status: "requested" };
+    });
+  }
+
+  async claimDue(request: {
+    limit: number;
+    duration: number;
+  }): Promise<ExecutionLease[]> {
+    if (request.limit <= 0) return [];
+    // The IMMEDIATE transaction holds the write lock, so concurrent claims from
+    // any process sharing the file see each other's leases.
+    return runTransaction(this.db, () => {
+      const now = this.clock();
+      const leases: ExecutionLease[] = [];
+
+      for (const executionId of this.executionsDao.getClaimableIds(
+        now,
+        request.limit
+      )) {
+        const state = this.executionsDao.getState(executionId);
+        if (!state || !isExecutionClaimable(state, now)) continue;
+
+        const claimed = claimExecution(state, {
+          now,
+          duration: request.duration,
+        });
+        this.executionsDao.updateState(claimed.state);
+        leases.push(claimed.lease);
+      }
+
+      return leases;
+    });
+  }
+
+  async renew(request: {
+    lease: ExecutionLease;
+    duration: number;
+  }): Promise<ExecutionRenewResult> {
+    return this.transition(request.lease, (state) =>
+      renewExecutionLease(state, {
+        lease: request.lease,
+        duration: request.duration,
+        now: this.clock(),
+      })
+    );
+  }
+
+  async release(request: {
+    lease: ExecutionLease;
+  }): Promise<ExecutionReleaseResult> {
+    return this.transition(request.lease, (state) =>
+      releaseExecutionLease(state, { lease: request.lease, now: this.clock() })
+    );
+  }
+
+  async acknowledge(request: {
+    lease: ExecutionLease;
+    outcome: WorkflowRunOutcome;
+  }): Promise<ExecutionAcknowledgeResult> {
+    return this.transition(request.lease, (state) =>
+      acknowledgeExecution(state, {
+        lease: request.lease,
+        outcome: request.outcome,
+        now: this.clock(),
+      })
+    );
+  }
+
+  /**
+   * Applies a fenced transition in one transaction. The transition checks the
+   * lease against the stored token, so the check and the write are atomic.
+   */
+  private transition<R>(
+    lease: ExecutionLease,
+    fn: (state: ExecutionState) => { state: ExecutionState; result: R }
+  ): Promise<R | { status: "lost" }> {
+    return Promise.resolve(
+      runTransaction(this.db, () => {
+        const state = this.executionsDao.getState(lease.executionId);
+        if (!state) return { status: "lost" as const };
+        const next = fn(state);
+        if (next.state !== state) this.executionsDao.updateState(next.state);
+        return next.result;
+      })
+    );
+  }
+
+  /**
+   * @internal Requests a wake from inside a transaction the caller already
+   * holds on the same database, so the wake commits with the caller's write
+   * (e.g. a store commit). `wakeAt` defaults to the runtime clock's now.
+   * Unknown and terminal executions are ignored.
+   */
+  wakeInTransaction(executionId: string, wakeAt: number = this.clock()) {
+    const state = this.executionsDao.getState(executionId);
+    if (!state) return;
+
+    const next = requestExecutionWake(state, wakeAt, this.clock());
+    if (next) this.executionsDao.updateState(next);
+  }
+}

package/src/sqlite-heap.ts

@@ -1,12 +1,30 @@
-import type { HeapClient } from "@yieldstar/core";
+import {
+  isLeaseCurrent,
+  type ExecutionLease,
+  type HeapClient,
+  type HeapRecord,
+  type LeaseLost,
+} from "@yieldstar/core";
+import { EffectWaitersDao } from "./dao/effect-waiters-dao";
+import { ExecutionsDao } from "./dao/executions-dao";
 import { StepResponsesDao } from "./dao/step-response-dao";
+import { StoreWaitersDao } from "./dao/store-waiters-dao";
 import type { SqliteDriver } from "./sqlite-driver";
+import { runTransaction } from "./sqlite-transaction";
 
 export class SqliteHeapClient implements HeapClient {
+  private db: SqliteDriver;
+  private executionsDao: ExecutionsDao;
   private stepResponsesDao: StepResponsesDao;
+  private storeWaitersDao: StoreWaitersDao;
+  private effectWaitersDao: EffectWaitersDao;
 
   constructor(db: SqliteDriver) {
+    this.db = db;
+    this.executionsDao = new ExecutionsDao(db);
     this.stepResponsesDao = new StepResponsesDao(db);
+    this.storeWaitersDao = new StoreWaitersDao(db);
+    this.effectWaitersDao = new EffectWaitersDao(db);
   }
 
   async getAllSteps() {
@@ -23,7 +41,7 @@ export class SqliteHeapClient implements HeapClient {
       params.stepKey
     );
 
-    if (!result?.step_response) {
+    if (!result) {
       return null;
     }
 
@@ -36,19 +54,53 @@ export class SqliteHeapClient implements HeapClient {
     };
   }
 
+  /**
+   * Checks the lease against the `executions` row and writes the step record
+   * in one IMMEDIATE transaction, so no claim can interleave between them.
+   */
   async writeStep(params: {
-    executionId: string;
+    lease: ExecutionLease;
     stepKey: string;
     stepAttempt: number;
-    stepDone: boolean;
+    done: boolean;
     stepResponseJson: string;
-  }) {
-    this.stepResponsesDao.insertStepResponse(
-      params.executionId,
-      params.stepKey,
-      params.stepAttempt,
-      params.stepDone,
-      params.stepResponseJson
-    );
+  }): Promise<HeapRecord | LeaseLost> {
+    const { lease, stepKey, stepAttempt, done, stepResponseJson } = params;
+    const { executionId } = lease;
+    return runTransaction(this.db, () => {
+      const state = this.executionsDao.getState(executionId);
+      if (!state || !isLeaseCurrent(state, lease)) {
+        return { status: "lost" as const };
+      }
+
+      // A record never changes once written: return it as stored.
+      const existing = this.stepResponsesDao.getStepResponse(
+        executionId,
+        stepKey,
+        stepAttempt
+      );
+      if (existing) {
+        return {
+          stepResponseJson: existing.step_response,
+          meta: { attempt: existing.step_attempt, done: Boolean(existing.step_done) },
+        };
+      }
+
+      this.stepResponsesDao.insertStepResponse(
+        executionId,
+        stepKey,
+        stepAttempt,
+        done,
+        stepResponseJson
+      );
+      // A waiter is deleted with the write that records its step's result.
+      // Unfinished attempts (e.g. a store wait or a suspended effect) keep the
+      // waiter they registered.
+      if (done) {
+        this.storeWaitersDao.deleteStepWaiters(executionId, stepKey);
+        this.effectWaitersDao.deleteStepWaiters(executionId, stepKey);
+      }
+      return { stepResponseJson, meta: { attempt: stepAttempt, done } };
+    });
   }
 }

package/src/sqlite-runtime.ts

@@ -0,0 +1,36 @@
+import { Runtime, type RuntimeOptions } from "@yieldstar/core";
+import { SqliteEffectClient } from "./sqlite-effect";
+import { SqliteExecutionClient } from "./sqlite-execution";
+import { SqliteHeapClient } from "./sqlite-heap";
+import { SqliteStoreClient } from "./sqlite-store";
+import type { SqliteDriver } from "./sqlite-driver";
+
+export type SqliteRuntimeOptions = RuntimeOptions;
+
+/**
+ * Execution records, step records, stores, effects and waiters in one SQLite
+ * database, so every guarantee that spans them (wakes for a store commit or an
+ * effect settlement, deleting a waiter with its step's result) holds in a
+ * single transaction.
+ */
+export class SqliteRuntime extends Runtime {
+  readonly clock: () => number;
+  readonly executions: SqliteExecutionClient;
+  readonly effects: SqliteEffectClient;
+  readonly heap: SqliteHeapClient;
+  readonly stores: SqliteStoreClient;
+
+  constructor(db: SqliteDriver, options: SqliteRuntimeOptions = {}) {
+    super();
+    // Read Date.now lazily so fake timers installed later still apply.
+    this.clock = options.clock ?? (() => Date.now());
+    this.executions = new SqliteExecutionClient(db, { clock: this.clock });
+    this.heap = new SqliteHeapClient(db);
+    this.stores = new SqliteStoreClient({ db, executions: this.executions });
+    this.effects = new SqliteEffectClient({
+      db,
+      executions: this.executions,
+      clock: this.clock,
+    });
+  }
+}