@yieldstar/core 0.5.0 → 0.6.1

package/src/base/store.ts

@@ -1,5 +1,6 @@
 import type { StandardSchemaV1 } from "@standard-schema/spec";
-import type { WorkflowEvent } from "./event";
+import { durableValueCodec, type Durable, type IfDurable } from "./durable-value";
+import { WorkflowValueError, registerErrorClass } from "./errors";
 
 export type Draft<T> = T extends object
   ? { -readonly [K in keyof T]: Draft<T[K]> }
@@ -12,6 +13,12 @@ export type StoreDefinition<Schema extends StandardSchemaV1 = StandardSchemaV1>
   {
     name: string;
     schema: Schema;
+    /**
+     * The state a store starts with. Every operation on a missing store
+     * creates it from this state, so it is evaluated only when the store with
+     * this `id` does not exist.
+     */
+    initial: (id: string) => StoreState<Schema>;
   };
 
 export type StoreState<Schema extends StandardSchemaV1> =
@@ -68,12 +75,6 @@ export type StoreDeleteFromResult =
       actualInstanceId: string;
       expectedVersion: StoreVersion;
       actualVersion: StoreVersion;
-    }
-  | {
-      deleted: false;
-      reason: "not-found";
-      expectedInstanceId: string;
-      expectedVersion: StoreVersion;
     };
 
 export type StoreSelector<T, R> = (state: Readonly<T>) => R;
@@ -96,7 +97,6 @@ export type StoreWaiter = {
   workflowId: string;
   executionId: string;
   stepKey: string;
-  event: WorkflowEvent;
   storeName: string;
   storeId: string;
   instanceId: string;
@@ -107,18 +107,39 @@ export type StoreWaiter = {
 export type StoreMutationCommitResult =
   | { status: "committed" }
   | { status: "already-applied"; result: unknown }
-  | { status: "conflict"; snapshot: StoreSnapshot<unknown> };
+  | { status: "conflict"; snapshot: StoreSnapshot<unknown> }
+  | { status: "missing" };
+
+/**
+ * A snapshot read from a store, or, when `created` is true, the initial state
+ * of a store that did not exist when it was read. A created snapshot's
+ * `instanceId` is new and its `version` is 0.
+ */
+export type StoreReadSnapshot<T> = StoreSnapshot<T> & { created: boolean };
 
 export type StoreMutation = {
   definition: StoreDefinition;
   id: string;
-  expected: StoreSnapshot<unknown>;
+  /**
+   * The snapshot the mutation was computed from. When `created` is true the
+   * commit first inserts it as the store's initial state, and conflicts if
+   * the store exists by then.
+   */
+  expected: StoreReadSnapshot<unknown>;
   nextState: unknown;
   changedPaths: StorePath[];
   stepId?: StoreStepId;
   result: unknown;
 };
 
+export type StoreDeletion = {
+  definition: StoreDefinition;
+  id: string;
+  expected: StoreSnapshot<unknown>;
+  stepId?: StoreStepId;
+  result: StoreDeleteFromResult;
+};
+
 export type RuntimeStore<T> = {
   get(): Promise<StoreSnapshot<T>>;
   update(updater: (draft: Draft<T>) => void | T): Promise<StoreUpdateResult<T>>;
@@ -129,11 +150,47 @@ export type RuntimeStore<T> = {
   deleteFrom(snapshot: StoreSnapshot<T>): Promise<StoreDeleteFromResult>;
 };
 
-export function defineStore<Schema extends StandardSchemaV1>(
+/** A store state failed its schema. Workflow code can catch it. */
+export class StoreValidationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "StoreValidationError";
+  }
+}
+
+registerErrorClass("StoreValidationError", StoreValidationError);
+
+/**
+ * A schema whose output, the store state, is a durable value. The state is
+ * still validated by the codec at runtime.
+ */
+export type DurableStoreSchema<Schema extends StandardSchemaV1> = IfDurable<
+  StoreState<Schema>,
+  StandardSchemaV1<
+    StandardSchemaV1.InferInput<Schema>,
+    Durable<StoreState<Schema>>
+  >
+>;
+
+/**
+ * `State` is inferred from the schema alone, so `initial` is checked against
+ * it and keeps literal types such as `status: "idle"`.
+ */
+export function defineStore<
+  Schema extends StandardSchemaV1<any, State>,
+  State = StoreState<Schema>,
+>(
   name: string,
-  schema: Schema
+  schema: Schema & StandardSchemaV1<any, State> & DurableStoreSchema<Schema>,
+  options: {
+    initial: (id: string) => NoInfer<Durable<State>>;
+  }
 ): StoreDefinition<Schema> {
-  return { name, schema };
+  return {
+    name,
+    schema,
+    initial: options.initial as (id: string) => StoreState<Schema>,
+  };
 }
 
 export abstract class StoreClient {
@@ -169,14 +226,13 @@ export abstract class StoreClient {
     };
   }
 
-  abstract getOrCreateStore<Schema extends StandardSchemaV1>(params: {
-    definition: StoreDefinition<Schema>;
-    id: string;
-    initial?:
-      | StoreState<Schema>
-      | (() => StoreState<Schema> | Promise<StoreState<Schema>>);
-  }): Promise<StoreSnapshot<StoreState<Schema>>>;
-
+  /**
+   * Every operation that takes a `definition` and `id`, except `deleteStore`,
+   * first creates a missing store from `definition.initial(id)`, in the same
+   * atomic write as the operation. `initial` is evaluated only when the store
+   * is missing, and concurrent operations on a missing store record exactly
+   * one initial state. A creation is version 0 of a new instance.
+   */
   abstract getStore<Schema extends StandardSchemaV1>(params: {
     definition: StoreDefinition<Schema>;
     id: string;
@@ -248,6 +304,14 @@ export abstract class StoreClient {
     stepId?: StoreStepId;
   }): Promise<StoreTakeResult<R>>;
 
+  /**
+   * Registers a versioned read observation. Registration must be linearizable
+   * with mutations: a stale observation is woken immediately, while a current
+   * observation is woken by a later intersecting mutation. A wake requests a
+   * delivery of `waiter.executionId`; it carries no copy of the event. Once a
+   * mutation is durable, the wakes it requires are durable too. The waiter
+   * stays registered until the heap records its step's result.
+   */
   abstract registerWaiter(waiter: StoreWaiter): Promise<void>;
 
   /**
@@ -259,15 +323,21 @@ export abstract class StoreClient {
   abstract listStores(definition: StoreDefinition): Promise<string[]>;
 
   /**
-   * Removes a store instance and all of its associated rows (state, waiters,
-   * applied-steps ledger). A no-op if the store does not exist.
+   * Removes a physical store instance and its waiters. Applied-step receipts
+   * remain authoritative for the logical store key across recreation. A no-op
+   * if the store does not exist; it never creates one.
    */
   abstract deleteStore(params: {
     definition: StoreDefinition;
     id: string;
   }): Promise<void>;
 
-  /** Deletes a store only if its instance ID and version still match the snapshot. */
+  /**
+   * Deletes a store only if its instance ID and version still match the
+   * snapshot. A missing store is created first, so the result is a conflict
+   * with the new instance. With a `stepId`, a committed deletion is recorded
+   * and a repeated call returns the recorded result.
+   */
   abstract deleteStoreFrom(params: {
     definition: StoreDefinition;
     id: string;
@@ -279,9 +349,27 @@ export abstract class StoreClient {
 /**
  * Implements store transformations as read/compute/compare-and-swap loops.
  * Storage connectors only implement the atomic mutation protocol and never
- * execute application callbacks while holding a storage transaction.
+ * execute application callbacks, including `initial`, while holding a storage
+ * transaction.
  */
 export abstract class CasStoreClient extends StoreClient {
+  /** Reads a store's current snapshot, or `undefined` if it does not exist. */
+  protected abstract readStore(params: {
+    definition: StoreDefinition;
+    id: string;
+  }): Promise<StoreSnapshot<unknown> | undefined>;
+
+  /**
+   * Atomically inserts `snapshot` as a store's initial state unless the store
+   * exists, and returns the store's snapshot after the write: `snapshot` if it
+   * was inserted, otherwise the existing store's.
+   */
+  protected abstract insertStore(params: {
+    definition: StoreDefinition;
+    id: string;
+    snapshot: StoreSnapshot<unknown>;
+  }): Promise<StoreSnapshot<unknown>>;
+
   protected abstract getAppliedStoreStep(params: {
     definition: StoreDefinition;
     id: string;
@@ -289,13 +377,39 @@ export abstract class CasStoreClient extends StoreClient {
   }): Promise<{ result: unknown } | undefined>;
 
   /**
-   * Atomically compares `expected`, writes the next state, records the step
-   * result, and persists the changed paths for durable wake delivery.
+   * Atomically compares `expected`, writes the next state at
+   * `expected.version + 1`, records the optional step result, and records the
+   * wake obligations created by `changedPaths`. When `expected.created` is
+   * true the store must still be missing, and the commit inserts it under
+   * `expected.instanceId`; otherwise a missing store returns `missing`. A
+   * recorded step result wins over both checks. A transactional outbox is
+   * recommended but is not part of the protocol.
    */
   protected abstract commitStoreMutation(
     mutation: StoreMutation
   ): Promise<StoreMutationCommitResult>;
 
+  /**
+   * Atomically compares `expected`, deletes the store and its waiters, and
+   * records the optional step result. A recorded step result wins over the
+   * comparison, and a missing store returns `missing`.
+   */
+  protected abstract commitStoreDeletion(
+    deletion: StoreDeletion
+  ): Promise<StoreMutationCommitResult>;
+
+  /** Names the instance a store is created as. Connectors may override it. */
+  protected createInstanceId(): string {
+    return crypto.randomUUID();
+  }
+
+  async getStore<Schema extends StandardSchemaV1>(params: {
+    definition: StoreDefinition<Schema>;
+    id: string;
+  }): Promise<StoreSnapshot<StoreState<Schema>>> {
+    return this.getOrInsertStore(params.definition, params.id);
+  }
+
   async updateStore<Schema extends StandardSchemaV1>(params: {
     definition: StoreDefinition<Schema>;
     id: string;
@@ -307,15 +421,14 @@ export abstract class CasStoreClient extends StoreClient {
       return applied.result as StoreUpdateResult<StoreState<Schema>>;
     }
 
-    let snapshot = await this.getStore({
-      definition: params.definition,
-      id: params.id,
-    });
+    const stepKey = params.stepId?.stepKey;
+    let snapshot = await this.readOrInitialize(params.definition, params.id, stepKey);
     while (true) {
       const prepared = await prepareStoreUpdate(
         params.definition,
         snapshot,
-        params.updater
+        params.updater,
+        stepKey
       );
       const result: StoreUpdateResult<StoreState<Schema>> = {
         state: cloneStoreState(prepared.nextState),
@@ -336,7 +449,10 @@ export abstract class CasStoreClient extends StoreClient {
       if (committed.status === "already-applied") {
         return committed.result as StoreUpdateResult<StoreState<Schema>>;
       }
-      snapshot = committed.snapshot as StoreSnapshot<StoreState<Schema>>;
+      snapshot =
+        committed.status === "conflict"
+          ? existing(committed.snapshot as StoreSnapshot<StoreState<Schema>>)
+          : await this.readOrInitialize(params.definition, params.id, stepKey);
       // TODO: add a configurable retry cap/backoff policy before remote CAS
       // connectors are introduced; SQLite serializes commits locally.
     }
@@ -356,10 +472,8 @@ export abstract class CasStoreClient extends StoreClient {
 
     assertStoreSnapshotInstanceId(params.snapshot);
 
-    const current = await this.getStore({
-      definition: params.definition,
-      id: params.id,
-    });
+    const stepKey = params.stepId?.stepKey;
+    const current = await this.getOrInsertStore(params.definition, params.id, stepKey);
     if (!sameStoreVersion(current, params.snapshot)) {
       return storeUpdateConflict(params.snapshot, current);
     }
@@ -367,7 +481,8 @@ export abstract class CasStoreClient extends StoreClient {
     const prepared = await prepareStoreUpdate(
       params.definition,
       params.snapshot,
-      params.updater
+      params.updater,
+      stepKey
     );
     const result: StoreUpdateFromResult<StoreState<Schema>> = {
       updated: true,
@@ -378,7 +493,7 @@ export abstract class CasStoreClient extends StoreClient {
     const committed = await this.commitStoreMutation({
       definition: params.definition,
       id: params.id,
-      expected: params.snapshot,
+      expected: existing(params.snapshot),
       nextState: prepared.nextState,
       changedPaths: prepared.changedPaths,
       stepId: params.stepId,
@@ -389,7 +504,54 @@ export abstract class CasStoreClient extends StoreClient {
     if (committed.status === "already-applied") {
       return committed.result as StoreUpdateFromResult<StoreState<Schema>>;
     }
-    return storeUpdateConflict(params.snapshot, committed.snapshot);
+    return storeUpdateConflict(
+      params.snapshot,
+      committed.status === "conflict"
+        ? committed.snapshot
+        : await this.getOrInsertStore(params.definition, params.id, stepKey)
+    );
+  }
+
+  async deleteStoreFrom(params: {
+    definition: StoreDefinition;
+    id: string;
+    snapshot: StoreSnapshot<unknown>;
+    stepId?: StoreStepId;
+  }): Promise<StoreDeleteFromResult> {
+    const applied = await this.getAppliedResult(params);
+    if (applied) return applied.result as StoreDeleteFromResult;
+
+    assertStoreSnapshotInstanceId(params.snapshot);
+
+    const stepKey = params.stepId?.stepKey;
+    let current = await this.getOrInsertStore(params.definition, params.id, stepKey);
+    while (sameStoreVersion(current, params.snapshot)) {
+      const result: StoreDeleteFromResult = { deleted: true };
+      const committed = await this.commitStoreDeletion({
+        definition: params.definition,
+        id: params.id,
+        expected: params.snapshot,
+        stepId: params.stepId,
+        result,
+      });
+
+      if (committed.status === "committed") return result;
+      if (committed.status === "already-applied") {
+        return committed.result as StoreDeleteFromResult;
+      }
+      current =
+        committed.status === "conflict"
+          ? committed.snapshot
+          : await this.getOrInsertStore(params.definition, params.id, stepKey);
+    }
+    return {
+      deleted: false,
+      reason: "conflict",
+      expectedInstanceId: params.snapshot.instanceId,
+      actualInstanceId: current.instanceId,
+      expectedVersion: params.snapshot.version,
+      actualVersion: current.version,
+    };
   }
 
   async takeFromStore<Schema extends StandardSchemaV1, R>(params: {
@@ -405,10 +567,8 @@ export abstract class CasStoreClient extends StoreClient {
     const applied = await this.getAppliedResult(params);
     if (applied) return applied.result as StoreTakeResult<R>;
 
-    let snapshot = await this.getStore({
-      definition: params.definition,
-      id: params.id,
-    });
+    const stepKey = params.stepId?.stepKey;
+    let snapshot = await this.readOrInitialize(params.definition, params.id, stepKey);
     while (true) {
       const previousState = cloneStoreState(snapshot.state);
       const draft = cloneStoreState(previousState) as Draft<StoreState<Schema>>;
@@ -419,6 +579,19 @@ export abstract class CasStoreClient extends StoreClient {
       );
 
       if (!isStoreSelectorMatch(selectedResult)) {
+        // An unmatched take still creates the store, so a waiter registered
+        // from this result observes an instance that exists.
+        if (snapshot.created) {
+          const stored = await this.insertStore({
+            definition: params.definition,
+            id: params.id,
+            snapshot: detach(snapshot),
+          });
+          if (stored.instanceId !== snapshot.instanceId) {
+            snapshot = existing(stored as StoreSnapshot<StoreState<Schema>>);
+            continue;
+          }
+        }
         return {
           matched: false,
           instanceId: snapshot.instanceId,
@@ -434,7 +607,15 @@ export abstract class CasStoreClient extends StoreClient {
         previousState,
         draft,
         tracked,
+        stepKey,
       });
+      // Checked before the commit, so a selection that cannot be recorded
+      // leaves the store unchanged.
+      assertDurableStoreValue(
+        selected,
+        stepKey ?? "",
+        `Store take selection for "${params.definition.name}"`
+      );
       const selectedSnapshot = cloneStoreState(selected);
       const result: StoreTakeResult<R> = {
         matched: true,
@@ -456,11 +637,50 @@ export abstract class CasStoreClient extends StoreClient {
       if (committed.status === "already-applied") {
         return committed.result as StoreTakeResult<R>;
       }
-      snapshot = committed.snapshot as StoreSnapshot<StoreState<Schema>>;
+      snapshot =
+        committed.status === "conflict"
+          ? existing(committed.snapshot as StoreSnapshot<StoreState<Schema>>)
+          : await this.readOrInitialize(params.definition, params.id, stepKey);
       // TODO: share the configurable retry cap/backoff policy with updateStore.
     }
   }
 
+  /**
+   * Reads a store, or evaluates and validates `definition.initial` when it is
+   * missing. Nothing is written: a created snapshot is committed by the
+   * operation computed from it.
+   */
+  private async readOrInitialize<Schema extends StandardSchemaV1>(
+    definition: StoreDefinition<Schema>,
+    id: string,
+    stepKey?: string
+  ): Promise<StoreReadSnapshot<StoreState<Schema>>> {
+    const snapshot = await this.readStore({ definition, id });
+    if (snapshot) return existing(snapshot as StoreSnapshot<StoreState<Schema>>);
+
+    const state = await validateStoreState(definition, definition.initial(id), stepKey);
+    return {
+      state,
+      instanceId: this.createInstanceId(),
+      version: 0,
+      created: true,
+    };
+  }
+
+  private async getOrInsertStore<Schema extends StandardSchemaV1>(
+    definition: StoreDefinition<Schema>,
+    id: string,
+    stepKey?: string
+  ): Promise<StoreSnapshot<StoreState<Schema>>> {
+    const snapshot = await this.readOrInitialize(definition, id, stepKey);
+    if (!snapshot.created) return detach(snapshot);
+    return (await this.insertStore({
+      definition,
+      id,
+      snapshot: detach(snapshot),
+    })) as StoreSnapshot<StoreState<Schema>>;
+  }
+
   private getAppliedResult(params: {
     definition: StoreDefinition;
     id: string;
@@ -476,10 +696,28 @@ export abstract class CasStoreClient extends StoreClient {
   }
 }
 
+function existing<T>(snapshot: StoreSnapshot<T>): StoreReadSnapshot<T> {
+  return {
+    state: snapshot.state,
+    instanceId: snapshot.instanceId,
+    version: snapshot.version,
+    created: false,
+  };
+}
+
+function detach<T>(snapshot: StoreReadSnapshot<T>): StoreSnapshot<T> {
+  return {
+    state: snapshot.state,
+    instanceId: snapshot.instanceId,
+    version: snapshot.version,
+  };
+}
+
 async function prepareStoreUpdate<Schema extends StandardSchemaV1>(
   definition: StoreDefinition<Schema>,
   snapshot: StoreSnapshot<StoreState<Schema>>,
-  updater: (draft: Draft<StoreState<Schema>>) => void | StoreState<Schema>
+  updater: (draft: Draft<StoreState<Schema>>) => void | StoreState<Schema>,
+  stepKey: string | undefined
 ) {
   const previousState = cloneStoreState(snapshot.state);
   const draft = cloneStoreState(previousState) as Draft<StoreState<Schema>>;
@@ -493,6 +731,7 @@ async function prepareStoreUpdate<Schema extends StandardSchemaV1>(
     draft,
     tracked,
     replacement: returned,
+    stepKey,
   });
 }
 
@@ -502,12 +741,14 @@ async function finalizeStoreMutation<Schema extends StandardSchemaV1>(params: {
   draft: Draft<StoreState<Schema>>;
   tracked: TrackedStoreUpdater<Draft<StoreState<Schema>>>;
   replacement?: unknown;
+  stepKey?: string;
 }) {
   const isReplacement =
     params.replacement !== undefined && params.replacement !== params.draft;
   const nextState = await validateStoreState(
     params.definition,
-    isReplacement ? params.replacement : params.draft
+    isReplacement ? params.replacement : params.draft,
+    params.stepKey
   );
   const changedPaths =
     !isReplacement && (nextState as unknown) === params.draft
@@ -570,21 +811,70 @@ export function assertSynchronousUpdater(updaterResult: unknown): void {
   }
 }
 
+/**
+ * Validates a state against its store's schema, then checks that the schema's
+ * output is a durable value. Throws `StoreValidationError` when the schema
+ * rejects the state, and `WorkflowValueError` (`INVALID_STEP_VALUE`) when the
+ * output is not durable, so callers that validate before committing leave the
+ * store unchanged. `stepKey` names the step in that error.
+ */
 export async function validateStoreState<Schema extends StandardSchemaV1>(
   definition: StoreDefinition<Schema>,
-  state: unknown
+  state: unknown,
+  stepKey = ""
 ): Promise<StoreState<Schema>> {
   const result = await definition.schema["~standard"].validate(state);
 
   if ("issues" in result && result.issues) {
     const messages = result.issues.map((issue) => issue.message).join("; ");
-    throw new Error(`Invalid store state for "${definition.name}": ${messages}`);
+    throw new StoreValidationError(
+      `Invalid store state for "${definition.name}": ${messages}`
+    );
   }
 
+  assertDurableStoreValue(result.value, stepKey, `Store state for "${definition.name}"`);
   return result.value as StoreState<Schema>;
 }
 
+function assertDurableStoreValue(value: unknown, stepKey: string, label: string) {
+  const encoding = durableValueCodec.encode(value);
+  if (encoding.status === "invalid") {
+    throw new WorkflowValueError(
+      "INVALID_STEP_VALUE",
+      stepKey,
+      `${label} is not a durable value: ${encoding.message}`
+    );
+  }
+}
+
+/** Encodes a store state or step result for storage. Throws if it is not durable. */
+export function encodeStoreValue(value: unknown): string {
+  const encoding = durableValueCodec.encode(value);
+  if (encoding.status === "invalid") {
+    throw new Error(`Store value is not a durable value: ${encoding.message}`);
+  }
+  return encoding.canonical;
+}
+
+export function decodeStoreValue(canonical: string): unknown {
+  const decoding = durableValueCodec.decode(canonical);
+  if (decoding.status === "invalid") {
+    throw new Error(`Invalid store value encoding: ${decoding.message}`);
+  }
+  return decoding.value;
+}
+
+/**
+ * Copies a state as the durable value codec would read it back. Values the
+ * codec rejects, which validation keeps out of committed state, are copied
+ * with `structuredClone`.
+ */
 export function cloneStoreState<T>(state: T): T {
+  const encoding = durableValueCodec.encode(state);
+  if (encoding.status === "encoded") {
+    const decoding = durableValueCodec.decode(encoding.canonical);
+    if (decoding.status === "decoded") return decoding.value as T;
+  }
   if (typeof structuredClone === "function") {
     try {
       return structuredClone(state);

package/src/base/workflow.ts

@@ -1,5 +1,7 @@
 import type { Logger } from "pino";
 import type { EventParams, WorkflowEvent, EventContext } from "./event";
+import type { EffectClient } from "./effect";
+import type { ExecutionClient, ExecutionLease } from "./execution";
 import { HeapClient } from "./heap";
 import { StoreClient } from "./store";
 import { StepResponse, WorkflowResult } from "./step";
@@ -9,8 +11,21 @@ export type WorkflowGeneratorParams<
   Context extends EventContext
 > = {
   event: WorkflowEvent<Params, Context>;
+  /** Every heap step write is fenced by this lease. */
+  lease: ExecutionLease;
+  /**
+   * Aborted when the delivery must stop. The driver checks it before each
+   * step function and each fenced write.
+   */
+  signal: AbortSignal;
   heapClient: HeapClient;
   storeClient: StoreClient;
+  /** `step.start` admits its target through this client. */
+  executionClient: ExecutionClient;
+  /** `step.effect` records and settles its effects through this client. */
+  effectClient: EffectClient;
+  /** The runtime clock. Delay and retry wake times are read from it. */
+  clock: () => number;
   logger: Logger;
 };