@cadenza.io/core 3.23.0 → 3.25.0

package/dist/index.d.mts

@@ -854,8 +854,10 @@ declare class Task extends SignalEmitter implements Graph {
     readonly isEphemeral: boolean;
     readonly isDebounce: boolean;
     inputContextSchema: Schema;
+    hasExplicitInputContextSchema: boolean;
     validateInputContext: boolean;
     outputContextSchema: Schema;
+    hasExplicitOutputContextSchema: boolean;
     validateOutputContext: boolean;
     readonly retryCount: number;
     readonly retryDelay: number;
@@ -962,7 +964,10 @@ declare class Task extends SignalEmitter implements Graph {
      * @param {AnyObject} context - The input context to validate.
      * @return {true | AnyObject} - Returns `true` if validation succeeds, otherwise returns an error object containing details of the validation failure.
      */
-    validateInput(context: AnyObject): true | AnyObject;
+    private getEffectiveValidationMode;
+    private warnMissingSchema;
+    private logValidationFailure;
+    validateInput(context: AnyObject, metadata?: AnyObject): true | AnyObject;
     /**
      * Validates the output context using the provided schema and emits metadata if validation fails.
      *
@@ -970,7 +975,7 @@ declare class Task extends SignalEmitter implements Graph {
      * @return {true | AnyObject} Returns `true` if the output context is valid; otherwise, returns an object
      * containing error information when validation fails.
      */
-    validateOutput(context: AnyObject): true | AnyObject;
+    validateOutput(context: AnyObject, metadata?: AnyObject): true | AnyObject;
     /**
      * Executes a task within a given context, optionally emitting signals and reporting progress.
      *
@@ -1854,6 +1859,8 @@ interface SessionPolicy {
     idleTtlMs?: number;
     absoluteTtlMs?: number;
     extendIdleTtlOnRead?: boolean;
+    persistDurableState?: boolean;
+    persistenceTimeoutMs?: number;
 }
 /**
  * Task retry policy metadata for actor definitions/specs.
@@ -2056,6 +2063,7 @@ interface ActorTaskRuntimeMetadata {
     mode: ActorTaskMode;
     forceMeta: boolean;
 }
+declare const META_ACTOR_SESSION_STATE_PERSIST_INTENT = "meta-actor-session-state-persist";
 /**
  * Reads actor metadata from a wrapped task function if available.
  */
@@ -2126,6 +2134,7 @@ declare class Actor<D extends Record<string, any> = AnyObject, R = AnyObject> {
     private touchSession;
     private runWithOptionalIdempotency;
     private getActiveIdempotencyRecord;
+    private persistDurableStateIfConfigured;
     private emitActorCreatedSignal;
 }
 
@@ -2148,6 +2157,33 @@ interface TaskOptions {
     retryDelayFactor?: number;
 }
 type CadenzaMode = "dev" | "debug" | "verbose" | "production";
+type RuntimeValidationMode = "off" | "warn" | "enforce";
+interface RuntimeValidationPolicy {
+    metaInput?: RuntimeValidationMode;
+    metaOutput?: RuntimeValidationMode;
+    businessInput?: RuntimeValidationMode;
+    businessOutput?: RuntimeValidationMode;
+    warnOnMissingMetaInputSchema?: boolean;
+    warnOnMissingMetaOutputSchema?: boolean;
+    warnOnMissingBusinessInputSchema?: boolean;
+    warnOnMissingBusinessOutputSchema?: boolean;
+}
+interface RuntimeValidationScope {
+    id: string;
+    active?: boolean;
+    startTaskNames?: string[];
+    startRoutineNames?: string[];
+    policy?: RuntimeValidationPolicy;
+}
+interface ResolvedRuntimeValidationPolicy {
+    layer: "meta" | "business";
+    inputMode: RuntimeValidationMode;
+    outputMode: RuntimeValidationMode;
+    warnOnMissingInputSchema: boolean;
+    warnOnMissingOutputSchema: boolean;
+    activeScopeIds: string[];
+}
+type RuntimeInquiryDelegate = (inquiry: string, context: AnyObject, options?: InquiryOptions) => Promise<any>;
 /**
  * Represents the core class of the Cadenza framework managing tasks, meta-tasks, signal emissions, and execution strategies.
  * All core components such as SignalBroker, GraphRunner, and GraphRegistry are initialized through this class, and it provides
@@ -2161,6 +2197,10 @@ declare class Cadenza {
     static registry: GraphRegistry;
     private static taskCache;
     private static actorCache;
+    private static runtimeInquiryDelegate;
+    private static runtimeValidationPolicy;
+    private static runtimeValidationScopes;
+    private static emittedMissingSchemaWarnings;
     static isBootstrapped: boolean;
     static mode: CadenzaMode;
     /**
@@ -2248,6 +2288,19 @@ 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 setRuntimeInquiryDelegate(delegate?: RuntimeInquiryDelegate): void;
+    static resolveRuntimeInquiryDelegate(): RuntimeInquiryDelegate;
+    static getRuntimeValidationPolicy(): RuntimeValidationPolicy;
+    static setRuntimeValidationPolicy(policy?: RuntimeValidationPolicy): RuntimeValidationPolicy;
+    static replaceRuntimeValidationPolicy(policy?: RuntimeValidationPolicy): RuntimeValidationPolicy;
+    static clearRuntimeValidationPolicy(): void;
+    static getRuntimeValidationScopes(): RuntimeValidationScope[];
+    static upsertRuntimeValidationScope(scope: RuntimeValidationScope): RuntimeValidationScope;
+    static removeRuntimeValidationScope(id: string): void;
+    static clearRuntimeValidationScopes(): void;
+    static applyRuntimeValidationScopesToContext(context: AnyObject, routineName: string, tasks: Task[]): AnyObject;
+    static resolveRuntimeValidationPolicyForTask(task: Task, metadata?: AnyObject): ResolvedRuntimeValidationPolicy;
+    static shouldEmitMissingSchemaWarning(cacheKey: string): boolean;
     /**
      * Creates an in-memory actor runtime instance.
      *
@@ -2613,4 +2666,4 @@ declare class Cadenza {
     static reset(): void;
 }
 
-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 };
+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, META_ACTOR_SESSION_STATE_PERSIST_INTENT, type ResolvedRuntimeValidationPolicy, type RetryPolicy, type RuntimeValidationMode, type RuntimeValidationPolicy, type RuntimeValidationScope, 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 };

package/dist/index.d.ts

@@ -854,8 +854,10 @@ declare class Task extends SignalEmitter implements Graph {
     readonly isEphemeral: boolean;
     readonly isDebounce: boolean;
     inputContextSchema: Schema;
+    hasExplicitInputContextSchema: boolean;
     validateInputContext: boolean;
     outputContextSchema: Schema;
+    hasExplicitOutputContextSchema: boolean;
     validateOutputContext: boolean;
     readonly retryCount: number;
     readonly retryDelay: number;
@@ -962,7 +964,10 @@ declare class Task extends SignalEmitter implements Graph {
      * @param {AnyObject} context - The input context to validate.
      * @return {true | AnyObject} - Returns `true` if validation succeeds, otherwise returns an error object containing details of the validation failure.
      */
-    validateInput(context: AnyObject): true | AnyObject;
+    private getEffectiveValidationMode;
+    private warnMissingSchema;
+    private logValidationFailure;
+    validateInput(context: AnyObject, metadata?: AnyObject): true | AnyObject;
     /**
      * Validates the output context using the provided schema and emits metadata if validation fails.
      *
@@ -970,7 +975,7 @@ declare class Task extends SignalEmitter implements Graph {
      * @return {true | AnyObject} Returns `true` if the output context is valid; otherwise, returns an object
      * containing error information when validation fails.
      */
-    validateOutput(context: AnyObject): true | AnyObject;
+    validateOutput(context: AnyObject, metadata?: AnyObject): true | AnyObject;
     /**
      * Executes a task within a given context, optionally emitting signals and reporting progress.
      *
@@ -1854,6 +1859,8 @@ interface SessionPolicy {
     idleTtlMs?: number;
     absoluteTtlMs?: number;
     extendIdleTtlOnRead?: boolean;
+    persistDurableState?: boolean;
+    persistenceTimeoutMs?: number;
 }
 /**
  * Task retry policy metadata for actor definitions/specs.
@@ -2056,6 +2063,7 @@ interface ActorTaskRuntimeMetadata {
     mode: ActorTaskMode;
     forceMeta: boolean;
 }
+declare const META_ACTOR_SESSION_STATE_PERSIST_INTENT = "meta-actor-session-state-persist";
 /**
  * Reads actor metadata from a wrapped task function if available.
  */
@@ -2126,6 +2134,7 @@ declare class Actor<D extends Record<string, any> = AnyObject, R = AnyObject> {
     private touchSession;
     private runWithOptionalIdempotency;
     private getActiveIdempotencyRecord;
+    private persistDurableStateIfConfigured;
     private emitActorCreatedSignal;
 }
 
@@ -2148,6 +2157,33 @@ interface TaskOptions {
     retryDelayFactor?: number;
 }
 type CadenzaMode = "dev" | "debug" | "verbose" | "production";
+type RuntimeValidationMode = "off" | "warn" | "enforce";
+interface RuntimeValidationPolicy {
+    metaInput?: RuntimeValidationMode;
+    metaOutput?: RuntimeValidationMode;
+    businessInput?: RuntimeValidationMode;
+    businessOutput?: RuntimeValidationMode;
+    warnOnMissingMetaInputSchema?: boolean;
+    warnOnMissingMetaOutputSchema?: boolean;
+    warnOnMissingBusinessInputSchema?: boolean;
+    warnOnMissingBusinessOutputSchema?: boolean;
+}
+interface RuntimeValidationScope {
+    id: string;
+    active?: boolean;
+    startTaskNames?: string[];
+    startRoutineNames?: string[];
+    policy?: RuntimeValidationPolicy;
+}
+interface ResolvedRuntimeValidationPolicy {
+    layer: "meta" | "business";
+    inputMode: RuntimeValidationMode;
+    outputMode: RuntimeValidationMode;
+    warnOnMissingInputSchema: boolean;
+    warnOnMissingOutputSchema: boolean;
+    activeScopeIds: string[];
+}
+type RuntimeInquiryDelegate = (inquiry: string, context: AnyObject, options?: InquiryOptions) => Promise<any>;
 /**
  * Represents the core class of the Cadenza framework managing tasks, meta-tasks, signal emissions, and execution strategies.
  * All core components such as SignalBroker, GraphRunner, and GraphRegistry are initialized through this class, and it provides
@@ -2161,6 +2197,10 @@ declare class Cadenza {
     static registry: GraphRegistry;
     private static taskCache;
     private static actorCache;
+    private static runtimeInquiryDelegate;
+    private static runtimeValidationPolicy;
+    private static runtimeValidationScopes;
+    private static emittedMissingSchemaWarnings;
     static isBootstrapped: boolean;
     static mode: CadenzaMode;
     /**
@@ -2248,6 +2288,19 @@ 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 setRuntimeInquiryDelegate(delegate?: RuntimeInquiryDelegate): void;
+    static resolveRuntimeInquiryDelegate(): RuntimeInquiryDelegate;
+    static getRuntimeValidationPolicy(): RuntimeValidationPolicy;
+    static setRuntimeValidationPolicy(policy?: RuntimeValidationPolicy): RuntimeValidationPolicy;
+    static replaceRuntimeValidationPolicy(policy?: RuntimeValidationPolicy): RuntimeValidationPolicy;
+    static clearRuntimeValidationPolicy(): void;
+    static getRuntimeValidationScopes(): RuntimeValidationScope[];
+    static upsertRuntimeValidationScope(scope: RuntimeValidationScope): RuntimeValidationScope;
+    static removeRuntimeValidationScope(id: string): void;
+    static clearRuntimeValidationScopes(): void;
+    static applyRuntimeValidationScopesToContext(context: AnyObject, routineName: string, tasks: Task[]): AnyObject;
+    static resolveRuntimeValidationPolicyForTask(task: Task, metadata?: AnyObject): ResolvedRuntimeValidationPolicy;
+    static shouldEmitMissingSchemaWarning(cacheKey: string): boolean;
     /**
      * Creates an in-memory actor runtime instance.
      *
@@ -2613,4 +2666,4 @@ declare class Cadenza {
     static reset(): void;
 }
 
-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 };
+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, META_ACTOR_SESSION_STATE_PERSIST_INTENT, type ResolvedRuntimeValidationPolicy, type RetryPolicy, type RuntimeValidationMode, type RuntimeValidationPolicy, type RuntimeValidationScope, 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 };