@cadenza.io/core 3.20.0 → 3.22.0

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,315 @@ 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;
+} | {
+    source: "field";
+    field: string;
+} | {
+    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?: {
+        /**
+         * 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?: {
+        schema?: AnyObject;
+        description?: string;
+    };
+}
+/**
+ * Serializable actor definition used for persistence/round-tripping.
+ */
+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>;
+    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>;
+    /**
+     * Shortcut durable bootstrap state when `state.durable.initState` is not supplied.
+     */
+    initState?: D | (() => D);
+    defaultKey: string;
+    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[];
+}
+/**
+ * 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;
+    writeContract: ActorWriteContract;
+    consistencyProfile?: ActorConsistencyProfileName;
+    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;
+    reduceDurable: (reducer: ActorStateReducer<D>) => void;
+    setRuntime: (next: R | ActorStateReducer<R>) => void;
+    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;
+    version: number;
+    durableVersion: number;
+    runtimeVersion: number;
+}
+/**
+ * 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;
+    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>;
+}
+/**
+ * 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>>;
+/**
+ * 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;
+    private readonly sourceDefinition?;
+    private readonly stateByKey;
+    private readonly sessionByKey;
+    private readonly idempotencyByKey;
+    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 normalizeInputContext;
+    private resolveInvocationOptions;
+    private resolveActorKey;
+    private resolveActorKeyFromDefinition;
+    private resolveInitialDurableState;
+    private resolveInitialRuntimeState;
+    private ensureStateRecord;
+    private touchSession;
+    private runWithOptionalIdempotency;
+    private getActiveIdempotencyRecord;
+}
+
 interface TaskOptions {
     concurrency?: number;
     timeout?: number;
@@ -1829,6 +2144,7 @@ declare class Cadenza {
     static runner: GraphRunner;
     static metaRunner: GraphRunner;
     static registry: GraphRegistry;
+    private static taskCache;
     static isBootstrapped: boolean;
     static mode: CadenzaMode;
     /**
@@ -1868,6 +2184,7 @@ declare class Cadenza {
      * @throws {Error} If the name is not a non-empty string.
      */
     static validateName(name: string): void;
+    private static resolveTaskOptionsForActorTask;
     /**
      * Executes the specified task or GraphRoutine with the given context using an internal runner.
      *
@@ -1912,6 +2229,20 @@ declare class Cadenza {
     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>;
+    /**
+     * 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.
@@ -2263,4 +2594,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 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 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 };