@cadenza.io/core 3.21.0 → 3.23.0

package/dist/index.d.mts

@@ -1805,34 +1805,77 @@ declare class GraphStandardRun extends GraphRunStrategy {
     export(): any;
 }
 
+/**
+ * Determines when an actor key should be materialized in memory.
+ * - `eager`: creates the default key record immediately.
+ * - `lazy`: creates key records on first access.
+ */
 type ActorLoadPolicy = "eager" | "lazy";
+/**
+ * Defines how durable writes should be interpreted by actor tasks.
+ * - `overwrite`: replace full durable state.
+ * - `patch`: shallow-merge object fields.
+ * - `reducer`: allow reducer-return handlers.
+ */
 type ActorWriteContract = "overwrite" | "patch" | "reducer";
+/**
+ * Declares the intent of an actor task.
+ * - `read`: no state writes allowed.
+ * - `write`: durable/runtime writes allowed.
+ * - `meta`: write semantics with forced meta task registration.
+ */
 type ActorTaskMode = "read" | "write" | "meta";
+/**
+ * Actor classification.
+ * Meta actors are internal/framework-level actors and force bound tasks to meta.
+ */
 type ActorKind = "standard" | "meta";
+/**
+ * Optional runtime read protection policy.
+ */
 type ActorRuntimeReadGuard = "none" | "freeze-shallow";
+/**
+ * Consistency profile hint used primarily by distributed/service extensions.
+ */
 type ActorConsistencyProfileName = "strict" | "balanced" | "cached" | "async";
+/**
+ * Per-invocation actor options accepted via `context.__actorOptions`.
+ * Only key targeting and idempotency are overridable at invocation level.
+ */
 interface ActorInvocationOptions {
     actorKey?: string;
     idempotencyKey?: string;
 }
+/**
+ * Session expiry/touch behavior for actor keys.
+ */
 interface SessionPolicy {
     enabled?: boolean;
     idleTtlMs?: number;
     absoluteTtlMs?: number;
     extendIdleTtlOnRead?: boolean;
 }
+/**
+ * Task retry policy metadata for actor definitions/specs.
+ */
 interface RetryPolicy {
     attempts?: number;
     delayMs?: number;
     maxDelayMs?: number;
     factor?: number;
 }
+/**
+ * Idempotency policy for actor task execution.
+ */
 interface IdempotencyPolicy {
     enabled?: boolean;
     mode?: "required" | "optional";
     rerunOnFailedDuplicate?: boolean;
     ttlMs?: number;
 }
+/**
+ * Declarative actor-key resolution configuration.
+ */
 type ActorKeyDefinition = {
     source: "path";
     path: string;
@@ -1843,30 +1886,38 @@ type ActorKeyDefinition = {
     source: "template";
     template: string;
 };
+/**
+ * Serializable metadata describing a task bound to an actor.
+ */
 interface ActorTaskBindingDefinition {
     taskName: string;
     mode?: ActorTaskMode;
     description?: string;
 }
+/**
+ * Declarative state schema/configuration for an actor.
+ *
+ * Durable state uses `initState` for bootstrap defaults.
+ * Runtime state is intentionally task-driven (no actor-level init lifecycle hook).
+ */
 interface ActorStateDefinition<D extends Record<string, any>, R = AnyObject> {
     durable?: {
-        initialState?: D | (() => D);
+        /**
+         * Initial durable state. Prefer static values for simple cases.
+         * Function form is intended for advanced computed initialization.
+         */
+        initState?: D | (() => D);
         schema?: AnyObject;
         description?: string;
     };
     runtime?: {
-        initialState?: R | (() => R);
         schema?: AnyObject;
         description?: string;
-        factoryToken?: string;
-        factoryConfig?: AnyObject;
     };
 }
-interface ActorLifecycleDefinition {
-    initTaskName?: string;
-    initRoutineName?: string;
-    initHandlerToken?: string;
-}
+/**
+ * Serializable actor definition used for persistence/round-tripping.
+ */
 interface ActorDefinition<D extends Record<string, any>, R = AnyObject> {
     name: string;
     description: string;
@@ -1881,18 +1932,20 @@ interface ActorDefinition<D extends Record<string, any>, R = AnyObject> {
     runtimeReadGuard?: ActorRuntimeReadGuard;
     key?: ActorKeyDefinition;
     state?: ActorStateDefinition<D, R>;
-    lifecycle?: ActorLifecycleDefinition;
     tasks?: ActorTaskBindingDefinition[];
 }
+/**
+ * Runtime actor specification used by `Cadenza.createActor(...)`.
+ */
 interface ActorSpec<D extends Record<string, any>, R = AnyObject> {
     name: string;
     description?: string;
     state?: ActorStateDefinition<D, R>;
-    initialState?: D | (() => D);
-    initialDurableState?: D | (() => D);
-    initialRuntimeState?: R | (() => R);
+    /**
+     * Shortcut durable bootstrap state when `state.durable.initState` is not supplied.
+     */
+    initState?: D | (() => D);
     defaultKey: string;
-    init?: ActorInitHandler<D, R>;
     key?: ActorKeyDefinition;
     keyResolver?: (input: Record<string, any>) => string | undefined;
     loadPolicy?: ActorLoadPolicy;
@@ -1904,17 +1957,28 @@ interface ActorSpec<D extends Record<string, any>, R = AnyObject> {
     consistencyProfile?: ActorConsistencyProfileName;
     runtimeReadGuard?: ActorRuntimeReadGuard;
     taskBindings?: ActorTaskBindingDefinition[];
-    lifecycle?: ActorLifecycleDefinition;
 }
+/**
+ * Optional actor creation flags.
+ */
 interface ActorFactoryOptions<D extends Record<string, any> = Record<string, any>, R = AnyObject> {
     isMeta?: boolean;
     definitionSource?: ActorDefinition<D, R>;
 }
+/**
+ * Optional per-binding behavior when wrapping actor handlers.
+ */
 interface ActorTaskBindingOptions {
     mode?: ActorTaskMode;
     touchSession?: boolean;
 }
+/**
+ * Reducer function used for state transitions.
+ */
 type ActorStateReducer<S> = (state: S, input: AnyObject) => S;
+/**
+ * Fully resolved invocation options used during actor task execution.
+ */
 interface ActorResolvedInvocationOptions {
     actorKey?: string;
     loadPolicy: ActorLoadPolicy;
@@ -1923,6 +1987,9 @@ interface ActorResolvedInvocationOptions {
     idempotencyKey?: string;
     touchSession: boolean;
 }
+/**
+ * Durable/runtime mutator helpers exposed to actor handlers.
+ */
 interface ActorStateMutators<D extends Record<string, any>, R = AnyObject> {
     setDurable: (next: D | ActorStateReducer<D>) => void;
     patchDurable: (partial: Partial<D>) => void;
@@ -1931,6 +1998,9 @@ interface ActorStateMutators<D extends Record<string, any>, R = AnyObject> {
     patchRuntime: (partial: Partial<R>) => void;
     reduceRuntime: (reducer: ActorStateReducer<R>) => void;
 }
+/**
+ * Combined actor state snapshot and mutators exposed to handlers.
+ */
 interface ActorStateStore<D extends Record<string, any>, R = AnyObject> extends ActorStateMutators<D, R> {
     durable: D;
     runtime: R;
@@ -1938,11 +2008,13 @@ interface ActorStateStore<D extends Record<string, any>, R = AnyObject> extends
     durableVersion: number;
     runtimeVersion: number;
 }
-interface ActorInitStateStore<D extends Record<string, any>, R = AnyObject> extends ActorStateMutators<D, R> {
-    durable: D;
-    runtime: R;
-}
+/**
+ * Context injected into `actor.task(...)` handlers.
+ */
 interface ActorTaskContext<D extends Record<string, any>, R = AnyObject> {
+    /**
+     * Durable state alias retained for backwards ergonomics.
+     */
     state: D;
     durableState: D;
     runtimeState: R;
@@ -1970,52 +2042,31 @@ interface ActorTaskContext<D extends Record<string, any>, R = AnyObject> {
     emit: (signal: string, payload?: AnyObject) => void;
     inquire: (inquiry: string, context?: AnyObject, options?: InquiryOptions) => Promise<AnyObject>;
 }
+/**
+ * Handler signature used by `actor.task(...)`.
+ */
 type ActorTaskHandler<D extends Record<string, any>, R = AnyObject> = (context: ActorTaskContext<D, R>) => TaskResult | ActorStateReducer<D> | Promise<TaskResult | ActorStateReducer<D>>;
-interface ActorInitResult<D extends Record<string, any>, R = AnyObject> {
-    state?: D;
-    durableState?: D;
-    runtimeState?: R;
-}
-interface ActorInitContext<D extends Record<string, any>, R = AnyObject> {
-    baseState: D;
-    durableBaseState: D;
-    runtimeBaseState: R;
-    store: ActorInitStateStore<D, R>;
-    input: AnyObject;
-    actor: {
-        name: string;
-        description?: string;
-        key: string;
-        kind: ActorKind;
-    };
-    options: ActorResolvedInvocationOptions;
-    setState: (next: D | ActorStateReducer<D>) => void;
-    patchState: (partial: Partial<D>) => void;
-    reduceState: (reducer: ActorStateReducer<D>) => void;
-    setDurableState: (next: D | ActorStateReducer<D>) => void;
-    patchDurableState: (partial: Partial<D>) => void;
-    reduceDurableState: (reducer: ActorStateReducer<D>) => void;
-    setRuntimeState: (next: R | ActorStateReducer<R>) => void;
-    patchRuntimeState: (partial: Partial<R>) => void;
-    reduceRuntimeState: (reducer: ActorStateReducer<R>) => void;
-}
-type ActorInitHandler<D extends Record<string, any>, R = AnyObject> = (context: ActorInitContext<D, R>) => D | ActorInitResult<D, R> | void | Promise<D | ActorInitResult<D, R> | void>;
-interface ActorRuntimeFactoryContext<D extends Record<string, any> = Record<string, any>, R = AnyObject> {
-    definition: ActorDefinition<D, R>;
-    actor: {
-        name: string;
-        key: string;
-        kind: ActorKind;
-    };
-    input: AnyObject;
-    config?: AnyObject;
-}
-type ActorRuntimeFactory<R = AnyObject, D extends Record<string, any> = Record<string, any>> = (context: ActorRuntimeFactoryContext<D, R>) => R | Promise<R>;
-interface ActorDefinitionFactoryOptions<D extends Record<string, any> = Record<string, any>, R = AnyObject> {
-    isMeta?: boolean;
-    runtimeFactories?: Record<string, ActorRuntimeFactory<R, D>>;
-    initHandlers?: Record<string, ActorInitHandler<D, R>>;
+/**
+ * Metadata attached to wrapped actor task functions.
+ */
+interface ActorTaskRuntimeMetadata {
+    actorName: string;
+    actorDescription?: string;
+    actorKind: ActorKind;
+    mode: ActorTaskMode;
+    forceMeta: boolean;
 }
+/**
+ * Reads actor metadata from a wrapped task function if available.
+ */
+declare function getActorTaskRuntimeMetadata(taskFunction: TaskFunction): ActorTaskRuntimeMetadata | undefined;
+/**
+ * In-memory actor runtime.
+ *
+ * Actors keep durable and runtime state per resolved actor key.
+ * Durable defaults are loaded from `initState`.
+ * Runtime state is intentionally initialized/updated by normal actor write tasks.
+ */
 declare class Actor<D extends Record<string, any> = AnyObject, R = AnyObject> {
     readonly spec: ActorSpec<D, R>;
     readonly kind: ActorKind;
@@ -2023,22 +2074,48 @@ declare class Actor<D extends Record<string, any> = AnyObject, R = AnyObject> {
     private readonly stateByKey;
     private readonly sessionByKey;
     private readonly idempotencyByKey;
-    private readonly initializedKeys;
-    private readonly initializationByKey;
     private nextTaskBindingIndex;
+    /**
+     * Creates an actor instance and optionally materializes the default key.
+     */
     constructor(spec: ActorSpec<D, R>, options?: ActorFactoryOptions<D, R>);
+    /**
+     * Wraps an actor-aware handler into a standard Cadenza task function.
+     */
     task(handler: ActorTaskHandler<D, R>, bindingOptions?: ActorTaskBindingOptions): TaskFunction;
+    /**
+     * Returns durable state snapshot for the resolved key.
+     */
     getState(actorKey?: string): D;
+    /**
+     * Returns durable state snapshot for the resolved key.
+     */
     getDurableState(actorKey?: string): D;
+    /**
+     * Returns runtime state reference for the resolved key.
+     */
     getRuntimeState(actorKey?: string): R;
+    /**
+     * Alias of `getDurableVersion`.
+     */
     getVersion(actorKey?: string): number;
+    /**
+     * Returns durable state version for the resolved key.
+     */
     getDurableVersion(actorKey?: string): number;
+    /**
+     * Returns runtime state version for the resolved key.
+     */
     getRuntimeVersion(actorKey?: string): number;
+    /**
+     * Exports this actor as a serializable definition.
+     */
     toDefinition(): ActorDefinition<D, R>;
+    /**
+     * Resets one actor key or all keys.
+     */
     reset(actorKey?: string): void;
     private applyRuntimeReadGuard;
-    private buildDefaultInvocationOptions;
-    private primeInitialization;
     private normalizeInputContext;
     private resolveInvocationOptions;
     private resolveActorKey;
@@ -2046,10 +2123,10 @@ declare class Actor<D extends Record<string, any> = AnyObject, R = AnyObject> {
     private resolveInitialDurableState;
     private resolveInitialRuntimeState;
     private ensureStateRecord;
-    private ensureInitialized;
     private touchSession;
     private runWithOptionalIdempotency;
     private getActiveIdempotencyRecord;
+    private emitActorCreatedSignal;
 }
 
 interface TaskOptions {
@@ -2083,6 +2160,7 @@ declare class Cadenza {
     static metaRunner: GraphRunner;
     static registry: GraphRegistry;
     private static taskCache;
+    private static actorCache;
     static isBootstrapped: boolean;
     static mode: CadenzaMode;
     /**
@@ -2123,8 +2201,7 @@ declare class Cadenza {
      */
     static validateName(name: string): void;
     private static resolveTaskOptionsForActorTask;
-    private static applyActorInitResult;
-    private static createActorInitHandlerFromDefinition;
+    private static registerActor;
     /**
      * Executes the specified task or GraphRoutine with the given context using an internal runner.
      *
@@ -2166,11 +2243,25 @@ declare class Cadenza {
     static interval(taskName: string, context: AnyObject, intervalMs: number, leading?: boolean, startDateTime?: Date): void;
     static debounce(signalName: string, context: any, delayMs: number): void;
     static get(taskName: string): Task | undefined;
+    static getActor<D extends Record<string, any> = AnyObject, R = AnyObject>(actorName: string): Actor<D, R> | undefined;
+    static getAllActors<D extends Record<string, any> = AnyObject, R = AnyObject>(): Actor<D, R>[];
     static getRoutine(routineName: string): GraphRoutine | undefined;
     static defineIntent(intent: Intent): Intent;
     static inquire(inquiry: string, context: AnyObject, options?: InquiryOptions): Promise<any>;
+    /**
+     * 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<D extends Record<string, any> = AnyObject, R = AnyObject>(spec: ActorSpec<D, R>, options?: ActorFactoryOptions): Actor<D, R>;
-    static createActorFromDefinition<D extends Record<string, any> = AnyObject, R = AnyObject>(definition: ActorDefinition<D, R>, options?: ActorDefinitionFactoryOptions<D, R>): Actor<D, R>;
+    /**
+     * 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<D extends Record<string, any> = AnyObject, R = AnyObject>(definition: ActorDefinition<D, R>, options?: ActorFactoryOptions<D, R>): Actor<D, R>;
     /**
      * Creates and registers a new task with the specified parameters and options.
      * Tasks are the basic building blocks of Cadenza graphs and are responsible for executing logic.
@@ -2522,4 +2613,4 @@ declare class Cadenza {
     static reset(): void;
 }
 
-export { Actor, type ActorConsistencyProfileName, type ActorDefinition, type ActorDefinitionFactoryOptions, type ActorFactoryOptions, type ActorInitContext, type ActorInitHandler, type ActorInitResult, type ActorInitStateStore, type ActorInvocationOptions, type ActorKeyDefinition, type ActorKind, type ActorLifecycleDefinition, type ActorLoadPolicy, type ActorRuntimeFactory, type ActorRuntimeFactoryContext, type ActorRuntimeReadGuard, type ActorSpec, type ActorStateDefinition, type ActorStateReducer, type ActorStateStore, type ActorTaskBindingDefinition, type ActorTaskBindingOptions, type ActorTaskContext, type ActorTaskHandler, type ActorTaskMode, type ActorWriteContract, type AnyObject, type CadenzaMode, type DebounceOptions, DebounceTask, type EmitOptions, EphemeralTask, type EphemeralTaskOptions, GraphContext, GraphRegistry, GraphRoutine, GraphRun, GraphRunner, type IdempotencyPolicy, InquiryBroker, type InquiryOptions, type Intent, type RetryPolicy, type Schema, type SchemaConstraints, type SchemaDefinition, type SchemaType, type SessionPolicy, SignalBroker, SignalEmitter, Task, type TaskFunction, type TaskOptions, type TaskResult, type ThrottleTagGetter, Cadenza as default };
+export { Actor, type ActorConsistencyProfileName, type ActorDefinition, type ActorFactoryOptions, type ActorInvocationOptions, type ActorKeyDefinition, type ActorKind, type ActorLoadPolicy, type ActorRuntimeReadGuard, type ActorSpec, type ActorStateDefinition, type ActorStateReducer, type ActorStateStore, type ActorTaskBindingDefinition, type ActorTaskBindingOptions, type ActorTaskContext, type ActorTaskHandler, type ActorTaskMode, type ActorTaskRuntimeMetadata, type ActorWriteContract, type AnyObject, type CadenzaMode, type DebounceOptions, DebounceTask, type EmitOptions, EphemeralTask, type EphemeralTaskOptions, GraphContext, GraphRegistry, GraphRoutine, GraphRun, GraphRunner, type IdempotencyPolicy, InquiryBroker, type InquiryOptions, type Intent, type RetryPolicy, type Schema, type SchemaConstraints, type SchemaDefinition, type SchemaType, type SessionPolicy, SignalBroker, SignalEmitter, Task, type TaskFunction, type TaskOptions, type TaskResult, type ThrottleTagGetter, Cadenza as default, getActorTaskRuntimeMetadata };