@cadenza.io/core 3.21.0 → 3.22.0

package/dist/index.js

@@ -6088,18 +6088,6 @@ function deepClone(value) {
 function cloneForDurableState(value) {
   return deepClone(value);
 }
-function cloneForRuntimeState(value) {
-  if (Array.isArray(value)) {
-    return [...value];
-  }
-  if (isObject2(value)) {
-    const prototype = Object.getPrototypeOf(value);
-    if (prototype === Object.prototype || prototype === null) {
-      return { ...value };
-    }
-  }
-  return value;
-}
 function cloneForIdempotency(value) {
   try {
     return deepClone(value);
@@ -6160,12 +6148,13 @@ function getActorTaskRuntimeMetadata(taskFunction) {
   return taskFunction[ACTOR_TASK_METADATA];
 }
 var Actor = class {
+  /**
+   * Creates an actor instance and optionally materializes the default key.
+   */
   constructor(spec, options = {}) {
     this.stateByKey = /* @__PURE__ */ new Map();
     this.sessionByKey = /* @__PURE__ */ new Map();
     this.idempotencyByKey = /* @__PURE__ */ new Map();
-    this.initializedKeys = /* @__PURE__ */ new Set();
-    this.initializationByKey = /* @__PURE__ */ new Map();
     this.nextTaskBindingIndex = 0;
     if (!spec.name || typeof spec.name !== "string") {
       throw new Error("Actor name must be a non-empty string");
@@ -6183,9 +6172,11 @@ var Actor = class {
     };
     if ((this.spec.loadPolicy ?? "eager") === "eager") {
       this.ensureStateRecord(this.spec.defaultKey);
-      this.primeInitialization(this.spec.defaultKey);
     }
   }
+  /**
+   * Wraps an actor-aware handler into a standard Cadenza task function.
+   */
   task(handler, bindingOptions = {}) {
     const mode = bindingOptions.mode ?? "read";
     const taskBindingId = `${this.spec.name}:${++this.nextTaskBindingIndex}`;
@@ -6198,11 +6189,6 @@ var Actor = class {
       const actorKey = this.resolveActorKey(normalizedInput, invocationOptions);
       this.touchSession(actorKey, invocationOptions.touchSession, Date.now());
       const runTask = async () => {
-        await this.ensureInitialized(
-          actorKey,
-          normalizedInput,
-          invocationOptions
-        );
         const stateRecord = this.ensureStateRecord(actorKey);
         stateRecord.lastReadAt = Date.now();
         let durableStateChanged = false;
@@ -6352,32 +6338,54 @@ var Actor = class {
     };
     return wrapped;
   }
+  /**
+   * Returns durable state snapshot for the resolved key.
+   */
   getState(actorKey) {
     return this.getDurableState(actorKey);
   }
+  /**
+   * Returns durable state snapshot for the resolved key.
+   */
   getDurableState(actorKey) {
     const key = normalizeActorKey(actorKey) ?? this.spec.defaultKey;
     return cloneForDurableState(this.ensureStateRecord(key).durableState);
   }
+  /**
+   * Returns runtime state reference for the resolved key.
+   */
   getRuntimeState(actorKey) {
     const key = normalizeActorKey(actorKey) ?? this.spec.defaultKey;
     return this.ensureStateRecord(key).runtimeState;
   }
+  /**
+   * Alias of `getDurableVersion`.
+   */
   getVersion(actorKey) {
     return this.getDurableVersion(actorKey);
   }
+  /**
+   * Returns durable state version for the resolved key.
+   */
   getDurableVersion(actorKey) {
     const key = normalizeActorKey(actorKey) ?? this.spec.defaultKey;
     return this.ensureStateRecord(key).version;
   }
+  /**
+   * Returns runtime state version for the resolved key.
+   */
   getRuntimeVersion(actorKey) {
     const key = normalizeActorKey(actorKey) ?? this.spec.defaultKey;
     return this.ensureStateRecord(key).runtimeVersion;
   }
+  /**
+   * Exports this actor as a serializable definition.
+   */
   toDefinition() {
     if (this.sourceDefinition) {
       return cloneForIdempotency(this.sourceDefinition);
     }
+    const durableInitState = this.spec.state?.durable?.initState ?? this.spec.initState ?? {};
     return {
       name: this.spec.name,
       description: this.spec.description ?? "",
@@ -6391,26 +6399,27 @@ var Actor = class {
       session: this.spec.session,
       runtimeReadGuard: this.spec.runtimeReadGuard,
       key: this.spec.key,
-      state: this.spec.state ?? {
+      state: {
+        ...this.spec.state ?? {},
         durable: {
-          initialState: this.spec.initialDurableState ?? this.spec.initialState ?? {}
+          ...this.spec.state?.durable ?? {},
+          initState: durableInitState
         },
-        runtime: this.spec.initialRuntimeState !== void 0 ? { initialState: this.spec.initialRuntimeState } : void 0
+        runtime: this.spec.state?.runtime
       },
-      lifecycle: this.spec.lifecycle,
       tasks: this.spec.taskBindings
     };
   }
+  /**
+   * Resets one actor key or all keys.
+   */
   reset(actorKey) {
     if (actorKey === void 0) {
       this.stateByKey.clear();
       this.sessionByKey.clear();
       this.idempotencyByKey.clear();
-      this.initializedKeys.clear();
-      this.initializationByKey.clear();
       if ((this.spec.loadPolicy ?? "eager") === "eager") {
         this.ensureStateRecord(this.spec.defaultKey);
-        this.primeInitialization(this.spec.defaultKey);
       }
       return;
     }
@@ -6420,8 +6429,6 @@ var Actor = class {
     }
     this.stateByKey.delete(normalizedKey);
     this.sessionByKey.delete(normalizedKey);
-    this.initializedKeys.delete(normalizedKey);
-    this.initializationByKey.delete(normalizedKey);
     for (const key of this.idempotencyByKey.keys()) {
       if (key.startsWith(`${normalizedKey}:`)) {
         this.idempotencyByKey.delete(key);
@@ -6435,23 +6442,6 @@ var Actor = class {
     }
     return runtimeState;
   }
-  buildDefaultInvocationOptions(actorKey) {
-    return {
-      actorKey,
-      loadPolicy: this.spec.loadPolicy ?? "eager",
-      writeContract: this.spec.writeContract ?? "overwrite",
-      consistencyProfile: this.spec.consistencyProfile,
-      idempotencyKey: void 0,
-      touchSession: this.spec.session?.extendIdleTtlOnRead ?? true
-    };
-  }
-  primeInitialization(actorKey) {
-    this.ensureInitialized(
-      actorKey,
-      {},
-      this.buildDefaultInvocationOptions(actorKey)
-    ).catch(() => void 0);
-  }
   normalizeInputContext(context) {
     if (!isObject2(context)) {
       return {};
@@ -6500,8 +6490,8 @@ var Actor = class {
     return resolveTemplateKey(input, this.spec.key.template);
   }
   resolveInitialDurableState() {
-    const definitionInitialState = this.spec.state?.durable?.initialState;
-    const initialDurableState = definitionInitialState ?? this.spec.initialDurableState ?? this.spec.initialState;
+    const legacyDefinitionInitialState = this.spec.state?.durable?.initialState;
+    const initialDurableState = this.spec.state?.durable?.initState ?? legacyDefinitionInitialState ?? this.spec.initState;
     if (initialDurableState === void 0) {
       return {};
     }
@@ -6511,15 +6501,7 @@ var Actor = class {
     return cloneForDurableState(initialDurableState);
   }
   resolveInitialRuntimeState() {
-    const definitionInitialRuntimeState = this.spec.state?.runtime?.initialState;
-    const initialRuntimeState = definitionInitialRuntimeState ?? this.spec.initialRuntimeState;
-    if (initialRuntimeState === void 0) {
-      return {};
-    }
-    if (typeof initialRuntimeState === "function") {
-      return cloneForRuntimeState(initialRuntimeState());
-    }
-    return cloneForRuntimeState(initialRuntimeState);
+    return void 0;
   }
   ensureStateRecord(actorKey) {
     const existing = this.stateByKey.get(actorKey);
@@ -6541,149 +6523,6 @@ var Actor = class {
     this.touchSession(actorKey, true, now2);
     return record;
   }
-  async ensureInitialized(actorKey, input, options) {
-    this.ensureStateRecord(actorKey);
-    if (!this.spec.init) {
-      this.initializedKeys.add(actorKey);
-      return;
-    }
-    if (this.initializedKeys.has(actorKey)) {
-      return;
-    }
-    const inFlight = this.initializationByKey.get(actorKey);
-    if (inFlight) {
-      return inFlight;
-    }
-    const initializationPromise = Promise.resolve().then(async () => {
-      const record = this.ensureStateRecord(actorKey);
-      let nextDurableState = cloneForDurableState(record.durableState);
-      let nextRuntimeState = record.runtimeState;
-      let durableUpdatedViaSetter = false;
-      let runtimeUpdatedViaSetter = false;
-      const reduceDurableState = (reducer) => {
-        nextDurableState = cloneForDurableState(
-          reducer(cloneForDurableState(nextDurableState), input)
-        );
-        durableUpdatedViaSetter = true;
-      };
-      const setDurableState = (next) => {
-        if (typeof next === "function") {
-          reduceDurableState(next);
-          return;
-        }
-        nextDurableState = cloneForDurableState(next);
-        durableUpdatedViaSetter = true;
-      };
-      const patchDurableState = (partial) => {
-        if (!isObject2(nextDurableState) || !isObject2(partial)) {
-          throw new Error(
-            `Actor "${this.spec.name}" patchDurableState requires object state and partial patch`
-          );
-        }
-        nextDurableState = {
-          ...nextDurableState,
-          ...partial
-        };
-        durableUpdatedViaSetter = true;
-      };
-      const reduceRuntimeState = (reducer) => {
-        nextRuntimeState = reducer(nextRuntimeState, input);
-        runtimeUpdatedViaSetter = true;
-      };
-      const setRuntimeState = (next) => {
-        if (typeof next === "function") {
-          reduceRuntimeState(next);
-          return;
-        }
-        nextRuntimeState = next;
-        runtimeUpdatedViaSetter = true;
-      };
-      const patchRuntimeState = (partial) => {
-        if (!isObject2(nextRuntimeState) || !isObject2(partial)) {
-          throw new Error(
-            `Actor "${this.spec.name}" patchRuntimeState requires object state and partial patch`
-          );
-        }
-        nextRuntimeState = {
-          ...nextRuntimeState,
-          ...partial
-        };
-        runtimeUpdatedViaSetter = true;
-      };
-      const store = {
-        durable: cloneForDurableState(record.durableState),
-        runtime: record.runtimeState,
-        setDurable: setDurableState,
-        patchDurable: patchDurableState,
-        reduceDurable: reduceDurableState,
-        setRuntime: setRuntimeState,
-        patchRuntime: patchRuntimeState,
-        reduceRuntime: reduceRuntimeState
-      };
-      const initResult = await this.spec.init?.({
-        baseState: cloneForDurableState(record.durableState),
-        durableBaseState: cloneForDurableState(record.durableState),
-        runtimeBaseState: record.runtimeState,
-        store,
-        input,
-        actor: {
-          name: this.spec.name,
-          description: this.spec.description,
-          key: actorKey,
-          kind: this.kind
-        },
-        options,
-        setState: setDurableState,
-        patchState: patchDurableState,
-        reduceState: reduceDurableState,
-        setDurableState,
-        patchDurableState,
-        reduceDurableState,
-        setRuntimeState,
-        patchRuntimeState,
-        reduceRuntimeState
-      });
-      if (initResult !== void 0) {
-        if (isObject2(initResult) && ("durableState" in initResult || "runtimeState" in initResult || "state" in initResult)) {
-          const normalizedResult = initResult;
-          if (normalizedResult.state !== void 0) {
-            nextDurableState = cloneForDurableState(normalizedResult.state);
-            durableUpdatedViaSetter = true;
-          }
-          if (normalizedResult.durableState !== void 0) {
-            nextDurableState = cloneForDurableState(
-              normalizedResult.durableState
-            );
-            durableUpdatedViaSetter = true;
-          }
-          if (normalizedResult.runtimeState !== void 0) {
-            nextRuntimeState = normalizedResult.runtimeState;
-            runtimeUpdatedViaSetter = true;
-          }
-        } else {
-          nextDurableState = cloneForDurableState(initResult);
-          durableUpdatedViaSetter = true;
-        }
-      }
-      const writeTimestamp = Date.now();
-      if (durableUpdatedViaSetter) {
-        record.durableState = nextDurableState;
-        record.lastDurableWriteAt = writeTimestamp;
-      }
-      if (runtimeUpdatedViaSetter) {
-        record.runtimeState = nextRuntimeState;
-        record.lastRuntimeWriteAt = writeTimestamp;
-      }
-      this.initializedKeys.add(actorKey);
-    }).catch((error) => {
-      this.initializedKeys.delete(actorKey);
-      throw error;
-    }).finally(() => {
-      this.initializationByKey.delete(actorKey);
-    });
-    this.initializationByKey.set(actorKey, initializationPromise);
-    return initializationPromise;
-  }
   touchSession(actorKey, shouldTouch, touchedAt) {
     if (!this.spec.session?.enabled || !shouldTouch) {
       return;
@@ -6873,105 +6712,6 @@ var Cadenza = class {
       isMeta: true
     };
   }
-  static applyActorInitResult(context, result) {
-    if (result === void 0) {
-      return;
-    }
-    if (typeof result === "object" && result !== null && ("durableState" in result || "runtimeState" in result || "state" in result)) {
-      const normalizedResult = result;
-      if (normalizedResult.state !== void 0) {
-        context.setState(normalizedResult.state);
-      }
-      if (normalizedResult.durableState !== void 0) {
-        context.setDurableState(normalizedResult.durableState);
-      }
-      if (normalizedResult.runtimeState !== void 0) {
-        context.setRuntimeState(normalizedResult.runtimeState);
-      }
-      return;
-    }
-    context.setState(result);
-  }
-  static createActorInitHandlerFromDefinition(definition, options) {
-    const runtimeFactoryToken = definition.state?.runtime?.factoryToken;
-    const initHandlerToken = definition.lifecycle?.initHandlerToken;
-    const initTaskName = definition.lifecycle?.initTaskName;
-    const initRoutineName = definition.lifecycle?.initRoutineName;
-    if (!runtimeFactoryToken && !initHandlerToken && !initTaskName && !initRoutineName) {
-      return void 0;
-    }
-    return async (context) => {
-      if (runtimeFactoryToken) {
-        const runtimeFactory = options.runtimeFactories?.[runtimeFactoryToken];
-        if (!runtimeFactory) {
-          throw new Error(
-            `Actor "${definition.name}" requires runtimeFactory token "${runtimeFactoryToken}"`
-          );
-        }
-        const runtimeState = await runtimeFactory({
-          definition,
-          actor: {
-            name: context.actor.name,
-            key: context.actor.key,
-            kind: context.actor.kind
-          },
-          input: context.input,
-          config: definition.state?.runtime?.factoryConfig
-        });
-        context.setRuntimeState(runtimeState);
-      }
-      if (initHandlerToken) {
-        const initHandler = options.initHandlers?.[initHandlerToken];
-        if (!initHandler) {
-          throw new Error(
-            `Actor "${definition.name}" requires initHandler token "${initHandlerToken}"`
-          );
-        }
-        const initHandlerResult = await initHandler(context);
-        this.applyActorInitResult(context, initHandlerResult);
-      }
-      if (initTaskName) {
-        const initTask = this.get(initTaskName);
-        if (!initTask) {
-          throw new Error(
-            `Actor "${definition.name}" initTask "${initTaskName}" is not registered`
-          );
-        }
-        const initTaskResult = await initTask.taskFunction(
-          {
-            ...context.input,
-            __actorInit: {
-              actor: context.actor,
-              options: context.options,
-              durableBaseState: context.durableBaseState,
-              runtimeBaseState: context.runtimeBaseState
-            }
-          },
-          () => void 0,
-          async () => ({}),
-          () => void 0
-        );
-        this.applyActorInitResult(context, initTaskResult);
-      }
-      if (initRoutineName) {
-        const initRoutine = this.getRoutine(initRoutineName);
-        if (!initRoutine) {
-          throw new Error(
-            `Actor "${definition.name}" initRoutine "${initRoutineName}" is not registered`
-          );
-        }
-        this.run(initRoutine, {
-          ...context.input,
-          __actorInit: {
-            actor: context.actor,
-            options: context.options,
-            durableBaseState: context.durableBaseState,
-            runtimeBaseState: context.runtimeBaseState
-          }
-        });
-      }
-    };
-  }
   /**
    * Executes the specified task or GraphRoutine with the given context using an internal runner.
    *
@@ -7044,10 +6784,22 @@ var Cadenza = class {
   static async inquire(inquiry, context, options) {
     return this.inquiryBroker?.inquire(inquiry, context, options);
   }
+  /**
+   * Creates an in-memory actor runtime instance.
+   *
+   * Actors are not graph nodes. Use `actor.task(...)` to produce standard tasks that
+   * participate in the graph like any other task.
+   */
   static createActor(spec, options = {}) {
     this.bootstrap();
     return new Actor(spec, options);
   }
+  /**
+   * Creates an actor from a serializable actor definition.
+   *
+   * Durable bootstrap state is resolved from `state.durable.initState`.
+   * For backwards compatibility, legacy `state.durable.initialState` is also accepted.
+   */
   static createActorFromDefinition(definition, options = {}) {
     this.bootstrap();
     if (!definition.description || !definition.description.trim()) {
@@ -7069,11 +6821,8 @@ var Cadenza = class {
       runtimeReadGuard: definition.runtimeReadGuard,
       key: definition.key,
       state: definition.state,
-      lifecycle: definition.lifecycle,
       taskBindings: definition.tasks,
-      initialDurableState: definition.state?.durable?.initialState,
-      initialRuntimeState: definition.state?.runtime?.initialState,
-      init: this.createActorInitHandlerFromDefinition(definition, options)
+      initState: definition.state?.durable?.initState ?? definition.state?.durable?.initialState
     };
     const actorOptions = {
       isMeta: options.isMeta,