@cadenza.io/core 3.20.0 → 3.21.0

package/dist/index.d.mts

@@ -352,7 +352,9 @@ interface Intent {
     output?: SchemaDefinition;
 }
 interface InquiryOptions {
-    timeout: number;
+    timeout?: number;
+    rejectOnTimeout?: boolean;
+    includePendingTasks?: boolean;
 }
 declare class InquiryBroker extends SignalEmitter {
     static instance_: InquiryBroker;
@@ -394,6 +396,7 @@ declare class InquiryBroker extends SignalEmitter {
     addInquiry(inquiry: string): void;
     addIntent(intent: Intent): void;
     inquire(inquiry: string, context: AnyObject, options?: InquiryOptions): Promise<AnyObject>;
+    reset(): void;
 }
 
 /**
@@ -1546,12 +1549,15 @@ declare class SignalBroker {
     private flushGroup;
     private flushStrategy;
     clearSquashState(): void;
+    private clearScheduledState;
     private scheduledBuckets;
     private scheduleTimer;
     schedule(signal: string, context: AnyObject, options?: EmitOptions): AbortController;
     private flushScheduled;
     private debouncedEmitters;
     private readonly MAX_DEBOUNCERS;
+    private clearDebounceState;
+    private clearThrottleState;
     debounce(signal: string, context: any, options?: {
         delayMs: number;
     }): void;
@@ -1799,6 +1805,253 @@ declare class GraphStandardRun extends GraphRunStrategy {
     export(): any;
 }
 
+type ActorLoadPolicy = "eager" | "lazy";
+type ActorWriteContract = "overwrite" | "patch" | "reducer";
+type ActorTaskMode = "read" | "write" | "meta";
+type ActorKind = "standard" | "meta";
+type ActorRuntimeReadGuard = "none" | "freeze-shallow";
+type ActorConsistencyProfileName = "strict" | "balanced" | "cached" | "async";
+interface ActorInvocationOptions {
+    actorKey?: string;
+    idempotencyKey?: string;
+}
+interface SessionPolicy {
+    enabled?: boolean;
+    idleTtlMs?: number;
+    absoluteTtlMs?: number;
+    extendIdleTtlOnRead?: boolean;
+}
+interface RetryPolicy {
+    attempts?: number;
+    delayMs?: number;
+    maxDelayMs?: number;
+    factor?: number;
+}
+interface IdempotencyPolicy {
+    enabled?: boolean;
+    mode?: "required" | "optional";
+    rerunOnFailedDuplicate?: boolean;
+    ttlMs?: number;
+}
+type ActorKeyDefinition = {
+    source: "path";
+    path: string;
+} | {
+    source: "field";
+    field: string;
+} | {
+    source: "template";
+    template: string;
+};
+interface ActorTaskBindingDefinition {
+    taskName: string;
+    mode?: ActorTaskMode;
+    description?: string;
+}
+interface ActorStateDefinition<D extends Record<string, any>, R = AnyObject> {
+    durable?: {
+        initialState?: 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;
+}
+interface ActorDefinition<D extends Record<string, any>, R = AnyObject> {
+    name: string;
+    description: string;
+    defaultKey: string;
+    kind?: ActorKind;
+    loadPolicy?: ActorLoadPolicy;
+    writeContract?: ActorWriteContract;
+    consistencyProfile?: ActorConsistencyProfileName;
+    retry?: RetryPolicy;
+    idempotency?: IdempotencyPolicy;
+    session?: SessionPolicy;
+    runtimeReadGuard?: ActorRuntimeReadGuard;
+    key?: ActorKeyDefinition;
+    state?: ActorStateDefinition<D, R>;
+    lifecycle?: ActorLifecycleDefinition;
+    tasks?: ActorTaskBindingDefinition[];
+}
+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);
+    defaultKey: string;
+    init?: ActorInitHandler<D, R>;
+    key?: ActorKeyDefinition;
+    keyResolver?: (input: Record<string, any>) => string | undefined;
+    loadPolicy?: ActorLoadPolicy;
+    writeContract?: ActorWriteContract;
+    kind?: ActorKind;
+    retry?: RetryPolicy;
+    idempotency?: IdempotencyPolicy;
+    session?: SessionPolicy;
+    consistencyProfile?: ActorConsistencyProfileName;
+    runtimeReadGuard?: ActorRuntimeReadGuard;
+    taskBindings?: ActorTaskBindingDefinition[];
+    lifecycle?: ActorLifecycleDefinition;
+}
+interface ActorFactoryOptions<D extends Record<string, any> = Record<string, any>, R = AnyObject> {
+    isMeta?: boolean;
+    definitionSource?: ActorDefinition<D, R>;
+}
+interface ActorTaskBindingOptions {
+    mode?: ActorTaskMode;
+    touchSession?: boolean;
+}
+type ActorStateReducer<S> = (state: S, input: AnyObject) => S;
+interface ActorResolvedInvocationOptions {
+    actorKey?: string;
+    loadPolicy: ActorLoadPolicy;
+    writeContract: ActorWriteContract;
+    consistencyProfile?: ActorConsistencyProfileName;
+    idempotencyKey?: string;
+    touchSession: boolean;
+}
+interface ActorStateMutators<D extends Record<string, any>, R = AnyObject> {
+    setDurable: (next: D | ActorStateReducer<D>) => void;
+    patchDurable: (partial: Partial<D>) => void;
+    reduceDurable: (reducer: ActorStateReducer<D>) => void;
+    setRuntime: (next: R | ActorStateReducer<R>) => void;
+    patchRuntime: (partial: Partial<R>) => void;
+    reduceRuntime: (reducer: ActorStateReducer<R>) => void;
+}
+interface ActorStateStore<D extends Record<string, any>, R = AnyObject> extends ActorStateMutators<D, R> {
+    durable: D;
+    runtime: R;
+    version: number;
+    durableVersion: number;
+    runtimeVersion: number;
+}
+interface ActorInitStateStore<D extends Record<string, any>, R = AnyObject> extends ActorStateMutators<D, R> {
+    durable: D;
+    runtime: R;
+}
+interface ActorTaskContext<D extends Record<string, any>, R = AnyObject> {
+    state: D;
+    durableState: D;
+    runtimeState: R;
+    store: ActorStateStore<D, R>;
+    input: AnyObject;
+    actor: {
+        name: string;
+        description?: string;
+        key: string;
+        version: number;
+        durableVersion: number;
+        runtimeVersion: number;
+        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;
+    emit: (signal: string, payload?: AnyObject) => void;
+    inquire: (inquiry: string, context?: AnyObject, options?: InquiryOptions) => Promise<AnyObject>;
+}
+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>>;
+}
+declare class Actor<D extends Record<string, any> = AnyObject, R = AnyObject> {
+    readonly spec: ActorSpec<D, R>;
+    readonly kind: ActorKind;
+    private readonly sourceDefinition?;
+    private readonly stateByKey;
+    private readonly sessionByKey;
+    private readonly idempotencyByKey;
+    private readonly initializedKeys;
+    private readonly initializationByKey;
+    private nextTaskBindingIndex;
+    constructor(spec: ActorSpec<D, R>, options?: ActorFactoryOptions<D, R>);
+    task(handler: ActorTaskHandler<D, R>, bindingOptions?: ActorTaskBindingOptions): TaskFunction;
+    getState(actorKey?: string): D;
+    getDurableState(actorKey?: string): D;
+    getRuntimeState(actorKey?: string): R;
+    getVersion(actorKey?: string): number;
+    getDurableVersion(actorKey?: string): number;
+    getRuntimeVersion(actorKey?: string): number;
+    toDefinition(): ActorDefinition<D, R>;
+    reset(actorKey?: string): void;
+    private applyRuntimeReadGuard;
+    private buildDefaultInvocationOptions;
+    private primeInitialization;
+    private normalizeInputContext;
+    private resolveInvocationOptions;
+    private resolveActorKey;
+    private resolveActorKeyFromDefinition;
+    private resolveInitialDurableState;
+    private resolveInitialRuntimeState;
+    private ensureStateRecord;
+    private ensureInitialized;
+    private touchSession;
+    private runWithOptionalIdempotency;
+    private getActiveIdempotencyRecord;
+}
+
 interface TaskOptions {
     concurrency?: number;
     timeout?: number;
@@ -1829,6 +2082,7 @@ declare class Cadenza {
     static runner: GraphRunner;
     static metaRunner: GraphRunner;
     static registry: GraphRegistry;
+    private static taskCache;
     static isBootstrapped: boolean;
     static mode: CadenzaMode;
     /**
@@ -1868,6 +2122,9 @@ declare class Cadenza {
      * @throws {Error} If the name is not a non-empty string.
      */
     static validateName(name: string): void;
+    private static resolveTaskOptionsForActorTask;
+    private static applyActorInitResult;
+    private static createActorInitHandlerFromDefinition;
     /**
      * Executes the specified task or GraphRoutine with the given context using an internal runner.
      *
@@ -1912,6 +2169,8 @@ declare class Cadenza {
     static getRoutine(routineName: string): GraphRoutine | undefined;
     static defineIntent(intent: Intent): Intent;
     static inquire(inquiry: string, context: AnyObject, options?: InquiryOptions): Promise<any>;
+    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 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.
@@ -2263,4 +2522,4 @@ declare class Cadenza {
     static reset(): void;
 }
 
-export { type AnyObject, type CadenzaMode, type DebounceOptions, DebounceTask, type EmitOptions, EphemeralTask, type EphemeralTaskOptions, GraphContext, GraphRegistry, GraphRoutine, GraphRun, GraphRunner, InquiryBroker, type InquiryOptions, type Intent, type Schema, type SchemaConstraints, type SchemaDefinition, type SchemaType, SignalBroker, SignalEmitter, Task, type TaskFunction, type TaskOptions, type TaskResult, type ThrottleTagGetter, Cadenza as default };
+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 };

package/dist/index.d.ts

@@ -352,7 +352,9 @@ interface Intent {
     output?: SchemaDefinition;
 }
 interface InquiryOptions {
-    timeout: number;
+    timeout?: number;
+    rejectOnTimeout?: boolean;
+    includePendingTasks?: boolean;
 }
 declare class InquiryBroker extends SignalEmitter {
     static instance_: InquiryBroker;
@@ -394,6 +396,7 @@ declare class InquiryBroker extends SignalEmitter {
     addInquiry(inquiry: string): void;
     addIntent(intent: Intent): void;
     inquire(inquiry: string, context: AnyObject, options?: InquiryOptions): Promise<AnyObject>;
+    reset(): void;
 }
 
 /**
@@ -1546,12 +1549,15 @@ declare class SignalBroker {
     private flushGroup;
     private flushStrategy;
     clearSquashState(): void;
+    private clearScheduledState;
     private scheduledBuckets;
     private scheduleTimer;
     schedule(signal: string, context: AnyObject, options?: EmitOptions): AbortController;
     private flushScheduled;
     private debouncedEmitters;
     private readonly MAX_DEBOUNCERS;
+    private clearDebounceState;
+    private clearThrottleState;
     debounce(signal: string, context: any, options?: {
         delayMs: number;
     }): void;
@@ -1799,6 +1805,253 @@ declare class GraphStandardRun extends GraphRunStrategy {
     export(): any;
 }
 
+type ActorLoadPolicy = "eager" | "lazy";
+type ActorWriteContract = "overwrite" | "patch" | "reducer";
+type ActorTaskMode = "read" | "write" | "meta";
+type ActorKind = "standard" | "meta";
+type ActorRuntimeReadGuard = "none" | "freeze-shallow";
+type ActorConsistencyProfileName = "strict" | "balanced" | "cached" | "async";
+interface ActorInvocationOptions {
+    actorKey?: string;
+    idempotencyKey?: string;
+}
+interface SessionPolicy {
+    enabled?: boolean;
+    idleTtlMs?: number;
+    absoluteTtlMs?: number;
+    extendIdleTtlOnRead?: boolean;
+}
+interface RetryPolicy {
+    attempts?: number;
+    delayMs?: number;
+    maxDelayMs?: number;
+    factor?: number;
+}
+interface IdempotencyPolicy {
+    enabled?: boolean;
+    mode?: "required" | "optional";
+    rerunOnFailedDuplicate?: boolean;
+    ttlMs?: number;
+}
+type ActorKeyDefinition = {
+    source: "path";
+    path: string;
+} | {
+    source: "field";
+    field: string;
+} | {
+    source: "template";
+    template: string;
+};
+interface ActorTaskBindingDefinition {
+    taskName: string;
+    mode?: ActorTaskMode;
+    description?: string;
+}
+interface ActorStateDefinition<D extends Record<string, any>, R = AnyObject> {
+    durable?: {
+        initialState?: 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;
+}
+interface ActorDefinition<D extends Record<string, any>, R = AnyObject> {
+    name: string;
+    description: string;
+    defaultKey: string;
+    kind?: ActorKind;
+    loadPolicy?: ActorLoadPolicy;
+    writeContract?: ActorWriteContract;
+    consistencyProfile?: ActorConsistencyProfileName;
+    retry?: RetryPolicy;
+    idempotency?: IdempotencyPolicy;
+    session?: SessionPolicy;
+    runtimeReadGuard?: ActorRuntimeReadGuard;
+    key?: ActorKeyDefinition;
+    state?: ActorStateDefinition<D, R>;
+    lifecycle?: ActorLifecycleDefinition;
+    tasks?: ActorTaskBindingDefinition[];
+}
+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);
+    defaultKey: string;
+    init?: ActorInitHandler<D, R>;
+    key?: ActorKeyDefinition;
+    keyResolver?: (input: Record<string, any>) => string | undefined;
+    loadPolicy?: ActorLoadPolicy;
+    writeContract?: ActorWriteContract;
+    kind?: ActorKind;
+    retry?: RetryPolicy;
+    idempotency?: IdempotencyPolicy;
+    session?: SessionPolicy;
+    consistencyProfile?: ActorConsistencyProfileName;
+    runtimeReadGuard?: ActorRuntimeReadGuard;
+    taskBindings?: ActorTaskBindingDefinition[];
+    lifecycle?: ActorLifecycleDefinition;
+}
+interface ActorFactoryOptions<D extends Record<string, any> = Record<string, any>, R = AnyObject> {
+    isMeta?: boolean;
+    definitionSource?: ActorDefinition<D, R>;
+}
+interface ActorTaskBindingOptions {
+    mode?: ActorTaskMode;
+    touchSession?: boolean;
+}
+type ActorStateReducer<S> = (state: S, input: AnyObject) => S;
+interface ActorResolvedInvocationOptions {
+    actorKey?: string;
+    loadPolicy: ActorLoadPolicy;
+    writeContract: ActorWriteContract;
+    consistencyProfile?: ActorConsistencyProfileName;
+    idempotencyKey?: string;
+    touchSession: boolean;
+}
+interface ActorStateMutators<D extends Record<string, any>, R = AnyObject> {
+    setDurable: (next: D | ActorStateReducer<D>) => void;
+    patchDurable: (partial: Partial<D>) => void;
+    reduceDurable: (reducer: ActorStateReducer<D>) => void;
+    setRuntime: (next: R | ActorStateReducer<R>) => void;
+    patchRuntime: (partial: Partial<R>) => void;
+    reduceRuntime: (reducer: ActorStateReducer<R>) => void;
+}
+interface ActorStateStore<D extends Record<string, any>, R = AnyObject> extends ActorStateMutators<D, R> {
+    durable: D;
+    runtime: R;
+    version: number;
+    durableVersion: number;
+    runtimeVersion: number;
+}
+interface ActorInitStateStore<D extends Record<string, any>, R = AnyObject> extends ActorStateMutators<D, R> {
+    durable: D;
+    runtime: R;
+}
+interface ActorTaskContext<D extends Record<string, any>, R = AnyObject> {
+    state: D;
+    durableState: D;
+    runtimeState: R;
+    store: ActorStateStore<D, R>;
+    input: AnyObject;
+    actor: {
+        name: string;
+        description?: string;
+        key: string;
+        version: number;
+        durableVersion: number;
+        runtimeVersion: number;
+        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;
+    emit: (signal: string, payload?: AnyObject) => void;
+    inquire: (inquiry: string, context?: AnyObject, options?: InquiryOptions) => Promise<AnyObject>;
+}
+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>>;
+}
+declare class Actor<D extends Record<string, any> = AnyObject, R = AnyObject> {
+    readonly spec: ActorSpec<D, R>;
+    readonly kind: ActorKind;
+    private readonly sourceDefinition?;
+    private readonly stateByKey;
+    private readonly sessionByKey;
+    private readonly idempotencyByKey;
+    private readonly initializedKeys;
+    private readonly initializationByKey;
+    private nextTaskBindingIndex;
+    constructor(spec: ActorSpec<D, R>, options?: ActorFactoryOptions<D, R>);
+    task(handler: ActorTaskHandler<D, R>, bindingOptions?: ActorTaskBindingOptions): TaskFunction;
+    getState(actorKey?: string): D;
+    getDurableState(actorKey?: string): D;
+    getRuntimeState(actorKey?: string): R;
+    getVersion(actorKey?: string): number;
+    getDurableVersion(actorKey?: string): number;
+    getRuntimeVersion(actorKey?: string): number;
+    toDefinition(): ActorDefinition<D, R>;
+    reset(actorKey?: string): void;
+    private applyRuntimeReadGuard;
+    private buildDefaultInvocationOptions;
+    private primeInitialization;
+    private normalizeInputContext;
+    private resolveInvocationOptions;
+    private resolveActorKey;
+    private resolveActorKeyFromDefinition;
+    private resolveInitialDurableState;
+    private resolveInitialRuntimeState;
+    private ensureStateRecord;
+    private ensureInitialized;
+    private touchSession;
+    private runWithOptionalIdempotency;
+    private getActiveIdempotencyRecord;
+}
+
 interface TaskOptions {
     concurrency?: number;
     timeout?: number;
@@ -1829,6 +2082,7 @@ declare class Cadenza {
     static runner: GraphRunner;
     static metaRunner: GraphRunner;
     static registry: GraphRegistry;
+    private static taskCache;
     static isBootstrapped: boolean;
     static mode: CadenzaMode;
     /**
@@ -1868,6 +2122,9 @@ declare class Cadenza {
      * @throws {Error} If the name is not a non-empty string.
      */
     static validateName(name: string): void;
+    private static resolveTaskOptionsForActorTask;
+    private static applyActorInitResult;
+    private static createActorInitHandlerFromDefinition;
     /**
      * Executes the specified task or GraphRoutine with the given context using an internal runner.
      *
@@ -1912,6 +2169,8 @@ declare class Cadenza {
     static getRoutine(routineName: string): GraphRoutine | undefined;
     static defineIntent(intent: Intent): Intent;
     static inquire(inquiry: string, context: AnyObject, options?: InquiryOptions): Promise<any>;
+    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 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.
@@ -2263,4 +2522,4 @@ declare class Cadenza {
     static reset(): void;
 }
 
-export { type AnyObject, type CadenzaMode, type DebounceOptions, DebounceTask, type EmitOptions, EphemeralTask, type EphemeralTaskOptions, GraphContext, GraphRegistry, GraphRoutine, GraphRun, GraphRunner, InquiryBroker, type InquiryOptions, type Intent, type Schema, type SchemaConstraints, type SchemaDefinition, type SchemaType, SignalBroker, SignalEmitter, Task, type TaskFunction, type TaskOptions, type TaskResult, type ThrottleTagGetter, Cadenza as default };
+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 };