@yieldstar/core 0.5.0 → 0.6.0

package/src/base/invoker.ts

@@ -1,7 +1,65 @@
 import type { EventEmitter } from "node:events";
-import type { ExecutionEvent } from "./event";
+import type { WorkflowEvent } from "./event";
+import type { ExecutionLease, WorkflowRunOutcome } from "./execution";
+
+export type DeliveryOptions = {
+  /** Every fenced write the delivery makes carries this lease. */
+  lease: ExecutionLease;
+  /**
+   * Aborted when the delivery must stop: the dispatcher aborts it, with a
+   * `LeaseLostError` as its reason, when a renewal returns `lost`. The driver
+   * checks it before each step function and each fenced write, and ends an
+   * aborted delivery without running more workflow code.
+   */
+  signal: AbortSignal;
+};
 
 export type WorkflowInvoker = {
+  /**
+   * @deprecated The execution record is the source of truth for outcomes.
+   * The dispatcher still emits terminal outcomes here as an in-process fast
+   * path; no guarantee depends on it.
+   */
   workflowEndEmitter: EventEmitter;
-  execute(event: ExecutionEvent): Promise<void>;
+  /**
+   * Runs one delivery of an execution and resolves with its outcome. Rejects,
+   * without an outcome, when the delivery hits an infrastructure error or the
+   * worker exits before replying. Once `options.signal` aborts, the delivery runs
+   * no more workflow code and makes no more fenced writes; it rejects with an
+   * `InfrastructureError` whose cause is the signal's reason. An invoker that
+   * can stop a step function already running, as the worker invoker does by
+   * killing its worker, should do so and reject at once. The dispatcher
+   * abandons a delivery that has not settled within its `abortGracePeriod`
+   * of the abort, and frees its slot.
+   *
+   * A worker that exits before replying rejects with a `WorkerExitedError`:
+   * the dispatcher then leaves the lease to expire, because the worker's last
+   * writes may still be landing. Every other rejection is a retry reply, and
+   * the dispatcher releases the lease.
+   */
+  deliver(event: WorkflowEvent, options: DeliveryOptions): Promise<WorkflowRunOutcome>;
 };
+
+const WORKER_EXITED = Symbol.for("yieldstar.workerExited");
+
+/**
+ * Rejects a delivery whose worker exited, or was killed, before replying.
+ * The dispatcher does not release the lease: it expires, and the execution is
+ * delivered again after the redelivery delay.
+ */
+export class WorkerExitedError extends Error {
+  readonly [WORKER_EXITED] = true;
+
+  constructor(message: string) {
+    super(message);
+    this.name = "WorkerExitedError";
+  }
+
+  static is(value: unknown): value is WorkerExitedError {
+    return (
+      typeof value === "object" &&
+      value !== null &&
+      (value as Record<symbol, unknown>)[WORKER_EXITED] === true
+    );
+  }
+}

package/src/base/runtime.ts

@@ -1,8 +1,29 @@
-import type { Logger } from "pino";
-import type { WorkflowResult } from "./step";
-import type { WorkflowEvent } from "./event";
+import type { EffectClient } from "./effect";
+import type { ExecutionClient } from "./execution";
+import type { HeapClient } from "./heap";
+import type { StoreClient } from "./store";
 
-export type EventProcessor = (
-  event: WorkflowEvent,
-  logger: Logger
-) => Promise<void | WorkflowResult<any>>;
+export interface RuntimeOptions {
+  /** Every client of the runtime reads time from this clock. Defaults to `Date.now`. */
+  clock?: () => number;
+}
+
+/**
+ * A runtime is defined by the guarantees its clients keep, not by how many
+ * databases it uses:
+ *
+ * - Where one write must accompany another, such as the wakes for a store
+ *   commit, the second is durable once the first commits and is applied
+ *   eventually (in one transaction or through an outbox).
+ * - A store or effect waiter is deleted atomically with its step's result.
+ * - An effect's settlement and the wakes of its waiters are one atomic write.
+ * - Every client reads time from the runtime's clock.
+ */
+export abstract class Runtime {
+  /** The clock every client, and every step's wake time, reads. */
+  abstract readonly clock: () => number;
+  abstract readonly executions: ExecutionClient;
+  abstract readonly effects: EffectClient;
+  abstract readonly heap: HeapClient;
+  abstract readonly stores: StoreClient;
+}

package/src/base/step.ts

@@ -22,13 +22,18 @@ export class StepInvalid extends StepResponse {
   readonly type = "step-invalid";
 }
 
+export type StepSchemaVerdict = "accepted" | "rejected";
+
 export class StepResult extends StepResponse {
   static type = "step-result";
   readonly type = "step-result";
   result: any;
-  constructor(result: any) {
+  /** Whether the step's schema accepted its value on the first run. */
+  schema?: StepSchemaVerdict;
+  constructor(result: any, schema?: StepSchemaVerdict) {
     super();
     this.result = result;
+    if (schema !== undefined) this.schema = schema;
   }
 }
 
@@ -45,10 +50,11 @@ export class WorkflowResult<T extends any> extends StepResponse {
 export class WorkflowDelay extends StepResponse {
   static type = "workflow-delay";
   readonly type = "workflow-delay";
-  resumeIn: number;
-  constructor(resumeIn: number) {
+  /** The absolute time the step's pause ends, read from the runtime clock. */
+  wakeAt: number;
+  constructor(wakeAt: number) {
     super();
-    this.resumeIn = resumeIn;
+    this.wakeAt = wakeAt;
   }
 }
 
@@ -60,6 +66,21 @@ export class StepStoreWait extends StepResponse {
   }
 }
 
+/**
+ * An effect step whose outcome is uncertain. The driver records it as an
+ * unfinished step after watching the effect, so the next delivery begins the
+ * effect again; `wakeAt` is when that delivery is due.
+ */
+export class StepEffectWait extends StepResponse {
+  static type = "effect-wait";
+  readonly type = "effect-wait";
+  wakeAt: number;
+  constructor(wakeAt: number) {
+    super();
+    this.wakeAt = wakeAt;
+  }
+}
+
 export class WorkflowRestart extends StepResponse {
   static type = "workflow-restart";
   readonly type = "workflow-restart";
@@ -96,9 +117,10 @@ export class StepError extends StepResponse {
 export class StepDelay extends StepResponse {
   static type = "step-delay";
   readonly type = "step-delay";
-  resumeIn: number;
-  constructor(resumeIn: number) {
+  /** The absolute time the step's pause ends, read from the runtime clock. */
+  wakeAt: number;
+  constructor(wakeAt: number) {
     super();
-    this.resumeIn = resumeIn;
+    this.wakeAt = wakeAt;
   }
 }