@yieldstar/core 0.4.6 → 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,34 @@ 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.wakeAt = wakeAt;
+  }
+}
+
+export class StepStoreWait extends StepResponse {
+  static type = "store-wait";
+  readonly type = "store-wait";
+  constructor() {
+    super();
+  }
+}
+
+/**
+ * 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.resumeIn = resumeIn;
+    this.wakeAt = wakeAt;
   }
 }
 
@@ -88,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;
   }
 }

package/src/base/store.test.ts

@@ -0,0 +1,176 @@
+import { expect, test } from "vitest";
+import {
+  cloneStoreState,
+  storePathsIntersect,
+  trackStoreSelector,
+  trackStoreUpdater,
+  unwrapTrackedValue,
+  type StorePath,
+} from "./store";
+
+type State = {
+  messages: { id: string; processed?: boolean; claimedBy?: string }[];
+  status: string;
+  profile: { name: string; tags: Record<string, string> };
+};
+
+function makeState(): State {
+  return {
+    messages: [
+      { id: "msg-1" },
+      { id: "msg-2" },
+      { id: "msg-3" },
+      { id: "msg-4" },
+    ],
+    status: "idle",
+    profile: { name: "dan", tags: {} },
+  };
+}
+
+function wakes(readPath: StorePath, writePaths: StorePath[]): boolean {
+  return storePathsIntersect([readPath], writePaths);
+}
+
+test("trackStoreUpdater: push onto an array records index paths that wake array waiters", () => {
+  const draft = makeState();
+  const tracked = trackStoreUpdater(draft);
+
+  tracked.draft.messages.push({ id: "msg-5" });
+
+  const paths = tracked.writePaths();
+  expect(paths).toContainEqual(["messages", 4]);
+  // A waiter on ["messages"] wakes via prefix intersection
+  expect(wakes(["messages"], paths)).toBe(true);
+  // The mutation landed on the raw draft
+  expect(draft.messages).toHaveLength(5);
+  expect(draft.messages[4]).toEqual({ id: "msg-5" });
+});
+
+test("trackStoreUpdater: splice and shift record the shifted indices", () => {
+  const draft = makeState();
+  const tracked = trackStoreUpdater(draft);
+
+  tracked.draft.messages.splice(1, 1);
+
+  const paths = tracked.writePaths();
+  // Elements shift down: indices 1..2 rewritten, index 3 deleted
+  expect(wakes(["messages", 1], paths)).toBe(true);
+  expect(wakes(["messages", 2], paths)).toBe(true);
+  expect(wakes(["messages", 3], paths)).toBe(true);
+  expect(draft.messages.map((m) => m.id)).toEqual(["msg-1", "msg-3", "msg-4"]);
+
+  const shifted = trackStoreUpdater(makeState());
+  shifted.draft.messages.shift();
+  const shiftPaths = shifted.writePaths();
+  expect(wakes(["messages", 0], shiftPaths)).toBe(true);
+  expect(wakes(["messages", 2], shiftPaths)).toBe(true);
+});
+
+test("trackStoreUpdater: nested field set records the full path", () => {
+  const draft = makeState();
+  const tracked = trackStoreUpdater(draft);
+
+  tracked.draft.profile.name = "grant";
+  tracked.draft.messages[0]!.processed = true;
+
+  const paths = tracked.writePaths();
+  expect(paths).toContainEqual(["profile", "name"]);
+  expect(paths).toContainEqual(["messages", 0, "processed"]);
+  // Unrelated paths do not intersect
+  expect(wakes(["status"], paths)).toBe(false);
+  expect(draft.profile.name).toBe("grant");
+  expect(draft.messages[0]!.processed).toBe(true);
+});
+
+test("trackStoreUpdater: Object.assign onto a nested object records each assigned key", () => {
+  const draft = makeState();
+  const tracked = trackStoreUpdater(draft);
+
+  Object.assign(tracked.draft.profile.tags, { a: "1", b: "2" });
+
+  const paths = tracked.writePaths();
+  expect(paths).toContainEqual(["profile", "tags", "a"]);
+  expect(paths).toContainEqual(["profile", "tags", "b"]);
+  expect(draft.profile.tags).toEqual({ a: "1", b: "2" });
+});
+
+test("trackStoreUpdater: delete records the deleted path", () => {
+  const draft = makeState();
+  draft.profile.tags = { a: "1" };
+  const tracked = trackStoreUpdater(draft);
+
+  delete tracked.draft.profile.tags["a"];
+
+  expect(tracked.writePaths()).toContainEqual(["profile", "tags", "a"]);
+  expect(draft.profile.tags).toEqual({});
+});
+
+test("trackStoreUpdater: defineProperty records conservatively", () => {
+  const draft = makeState();
+  const tracked = trackStoreUpdater(draft);
+
+  Object.defineProperty(tracked.draft.profile, "name", {
+    value: "defined",
+    writable: true,
+    enumerable: true,
+    configurable: true,
+  });
+
+  expect(tracked.writePaths()).toContainEqual(["profile", "name"]);
+  expect(draft.profile.name).toBe("defined");
+});
+
+test("trackStoreUpdater: duplicate write paths are collapsed", () => {
+  const draft = makeState();
+  const tracked = trackStoreUpdater(draft);
+
+  tracked.draft.status = "working";
+  tracked.draft.status = "idle";
+  tracked.draft.status = "working";
+
+  expect(
+    tracked.writePaths().filter((p) => p.join(".") === "status")
+  ).toHaveLength(1);
+});
+
+test("trackStoreUpdater: values assigned through the proxy are unwrapped onto the raw draft", () => {
+  const draft = makeState();
+  const tracked = trackStoreUpdater(draft);
+
+  // Read a child (returns a proxy) and store it elsewhere in the draft –
+  // the raw draft must receive the raw object, not the proxy wrapper.
+  const first = tracked.draft.messages[0]!;
+  (tracked.draft as any).lastMessage = first;
+
+  const stored = (draft as any).lastMessage;
+  expect(stored).toBe(draft.messages[0]);
+  expect(unwrapTrackedValue(stored)).toBe(stored);
+  // Proxy-free: structuredClone rejects proxies, so this must not throw
+  expect(() => structuredClone(draft)).not.toThrow();
+});
+
+test("trackStoreUpdater: mutations through a value selected via trackStoreSelector are recorded", () => {
+  const draft = makeState();
+  const tracked = trackStoreUpdater(draft);
+
+  const { result } = trackStoreSelector(tracked.draft, (s) =>
+    s.messages.find((m) => !m.claimedBy)
+  );
+  const selected = unwrapTrackedValue(result)!;
+  selected.claimedBy = "exec-1";
+
+  expect(tracked.writePaths()).toContainEqual(["messages", 0, "claimedBy"]);
+  expect(draft.messages[0]!.claimedBy).toBe("exec-1");
+});
+
+test("cloneStoreState launders proxy wrappers into plain objects", () => {
+  const tracked = trackStoreUpdater(makeState());
+  // A fresh object holding a nested proxy (the shallow set-unwrap cannot
+  // reach it) – commit-time cloning must still produce a proxy-free state.
+  const dirty = { wrapper: { inner: tracked.draft.messages } };
+
+  const clean = cloneStoreState(dirty);
+
+  expect(() => structuredClone(clean)).not.toThrow();
+  expect(clean.wrapper.inner).toEqual(makeState().messages);
+});