@directive-run/core 0.2.0 → 0.4.0

package/dist/{plugins-KKRG7lDP.d.cts → plugins-cDWoL7A7.d.cts}

@@ -250,7 +250,7 @@ interface ConstraintDef<S extends Schema, R extends Requirement = Requirement> {
      * Constraint IDs whose resolvers must complete before this constraint is evaluated.
      * If a dependency's `when()` returns false (no requirements), this constraint proceeds.
      * If a dependency's resolver fails, this constraint remains blocked.
-     * Cross-module: use "moduleName.constraintName" format.
+     * Cross-module: use "moduleName::constraintName" format (after references are not auto-prefixed).
      */
     after?: string[];
     /**
@@ -275,6 +275,10 @@ interface ConstraintState {
     lastResolvedAt: number | null;
     /** Constraint IDs this constraint is waiting on (from `after` property) */
     after: string[];
+    /** Number of times when() evaluated to true */
+    hitCount: number;
+    /** Timestamp of last when() → true evaluation */
+    lastActiveAt: number | null;
 }
 
 /**
@@ -337,7 +341,7 @@ type EffectCleanup = () => void;
  * ```
  */
 interface EffectDef<S extends Schema> {
-    run(facts: Facts<S>, prev: FactsSnapshot<S> | null): void | EffectCleanup | Promise<void | EffectCleanup>;
+    run(facts: Facts<S>, prev: InferSchema<S> | null): void | EffectCleanup | Promise<void | EffectCleanup>;
     /** Optional explicit dependencies for optimization */
     deps?: Array<keyof InferSchema<S>>;
 }
@@ -391,7 +395,7 @@ type EventsDef<S extends Schema> = Record<string, FlexibleEventHandler<S>>;
  */
 
 /** Retry policy configuration */
-interface RetryPolicy$1 {
+interface RetryPolicy {
     /** Maximum number of attempts */
     attempts: number;
     /** Backoff strategy */
@@ -416,16 +420,10 @@ interface BatchConfig {
     enabled: boolean;
     /** Time window to collect requirements (ms) */
     windowMs: number;
-    /** Maximum batch size (default: unlimited) */
+    /** Maximum batch size. When reached, the batch flushes immediately instead of waiting for the timer. (default: unlimited) */
     maxSize?: number;
     /** Per-batch timeout in ms (overrides resolver timeout for batches) */
     timeoutMs?: number;
-    /**
-     * Failure strategy for partial batch failures:
-     * - "all-or-nothing" (default): If resolveBatch throws, all requirements fail
-     * - "per-item": Use resolveBatchWithResults to get per-item results
-     */
-    failureStrategy?: "all-or-nothing" | "per-item";
 }
 /**
  * Result for a single item in a batch resolution.
@@ -447,6 +445,7 @@ type BatchResolveResults<T = unknown> = Array<BatchItemResult<T>>;
 interface ResolverContext<S extends Schema = Schema> {
     readonly facts: Facts<S>;
     readonly signal: AbortSignal;
+    /** Returns a read-only snapshot of the current facts state, useful for before/after comparisons inside resolvers. */
     readonly snapshot: () => FactsSnapshot<S>;
 }
 /** Single resolver definition (untyped - use TypedResolversDef for type safety) */
@@ -460,10 +459,10 @@ interface ResolverDef<S extends Schema, R extends Requirement = Requirement> {
     /** Custom key function for deduplication */
     key?: RequirementKeyFn<R>;
     /** Retry policy */
-    retry?: RetryPolicy$1;
+    retry?: RetryPolicy;
     /** Timeout for resolver execution (ms) */
     timeout?: number;
-    /** Batch configuration (mutually exclusive with regular resolve) */
+    /** Batch configuration. Works with resolve() (individual fallback), resolveBatch(), or resolveBatchWithResults(). */
     batch?: BatchConfig;
     /** Resolve function for single requirement */
     resolve?: (req: R, ctx: ResolverContext<S>) => Promise<void>;
@@ -579,32 +578,15 @@ interface RetryLaterConfig {
     /** Maximum delay in milliseconds (default: 30000) */
     maxDelayMs?: number;
 }
-/**
- * Circuit breaker configuration for automatic failure protection.
- * After `failureThreshold` consecutive failures, the circuit opens
- * and all requests fail fast for `resetTimeoutMs`.
- */
-interface CircuitBreakerConfig {
-    /** Number of consecutive failures before opening the circuit (default: 5) */
-    failureThreshold?: number;
-    /** Time in milliseconds before attempting to close the circuit (default: 60000) */
-    resetTimeoutMs?: number;
-    /** Number of successful requests needed to close a half-open circuit (default: 1) */
-    successThreshold?: number;
-}
-/** Circuit breaker state */
-type CircuitBreakerState = "closed" | "open" | "half-open";
 /** Error boundary configuration */
 interface ErrorBoundaryConfig {
-    onConstraintError?: RecoveryStrategy | ((error: Error, constraint: string) => void);
-    onResolverError?: RecoveryStrategy | ((error: Error, resolver: string) => void);
-    onEffectError?: RecoveryStrategy | ((error: Error, effect: string) => void);
-    onDerivationError?: RecoveryStrategy | ((error: Error, derivation: string) => void);
+    onConstraintError?: RecoveryStrategy | ((error: Error, constraint: string) => RecoveryStrategy | void);
+    onResolverError?: RecoveryStrategy | ((error: Error, resolver: string) => RecoveryStrategy | void);
+    onEffectError?: RecoveryStrategy | ((error: Error, effect: string) => RecoveryStrategy | void);
+    onDerivationError?: RecoveryStrategy | ((error: Error, derivation: string) => RecoveryStrategy | void);
     onError?: (error: DirectiveError) => void;
     /** Configuration for retry-later strategy */
     retryLater?: RetryLaterConfig;
-    /** Circuit breaker configuration (applies to resolvers only) */
-    circuitBreaker?: CircuitBreakerConfig;
 }
 
 /**
@@ -751,6 +733,14 @@ interface NamespacedSystem<Modules extends ModulesMap> {
     readonly derive: NamespacedDerivations<Modules>;
     /** Events accessor (union of all module events) */
     readonly events: NamespacedEventsAccessor<Modules>;
+    /** Runtime control for constraints (disable/enable/isDisabled) */
+    readonly constraints: ConstraintsControl;
+    /** Runtime control for effects (disable/enable/isEnabled) */
+    readonly effects: EffectsControl;
+    /** Per-run changelog entries (null if debug.runHistory is not enabled) */
+    readonly runHistory: RunChangelogEntry[] | null;
+    /** Initialize facts and derivations without starting reconciliation. Safe for SSR. */
+    initialize(): void;
     /** Start the system (initialize modules, begin reconciliation) */
     start(): void;
     /** Stop the system (cancel resolvers, stop reconciliation) */
@@ -970,6 +960,14 @@ interface SingleModuleSystem<S extends ModuleSchema> {
     readonly derive: InferDerivations<S>;
     /** Direct events accessor: system.events.increment() */
     readonly events: SingleModuleEvents<S>;
+    /** Runtime control for constraints (disable/enable/isDisabled) */
+    readonly constraints: ConstraintsControl;
+    /** Runtime control for effects (disable/enable/isEnabled) */
+    readonly effects: EffectsControl;
+    /** Per-run changelog entries (null if debug.runHistory is not enabled) */
+    readonly runHistory: RunChangelogEntry[] | null;
+    /** Initialize facts and derivations without starting reconciliation. Safe for SSR. */
+    initialize(): void;
     /** Start the system (initialize modules, begin reconciliation) */
     start(): void;
     /** Stop the system (cancel resolvers, stop reconciliation) */
@@ -1109,6 +1107,7 @@ interface AnySystem {
     readonly isSettled: boolean;
     readonly isInitialized: boolean;
     readonly isReady: boolean;
+    initialize(): void;
     start(): void;
     stop(): void;
     destroy(): void;
@@ -1210,7 +1209,7 @@ interface TypedConstraintDef<M extends ModuleSchema> {
      * Constraint IDs whose resolvers must complete before this constraint is evaluated.
      * If a dependency's `when()` returns false (no requirements), this constraint proceeds.
      * If a dependency's resolver fails, this constraint remains blocked.
-     * Cross-module: use "moduleName.constraintName" format.
+     * Cross-module: use "moduleName::constraintName" format (after references are not auto-prefixed).
      */
     after?: string[];
     /**
@@ -1248,7 +1247,7 @@ interface CrossModuleConstraintDef<M extends ModuleSchema, Deps extends CrossMod
      * Constraint IDs whose resolvers must complete before this constraint is evaluated.
      * If a dependency's `when()` returns false (no requirements), this constraint proceeds.
      * If a dependency's resolver fails, this constraint remains blocked.
-     * Cross-module: use "moduleName.constraintName" format.
+     * Cross-module: use "moduleName::constraintName" format (after references are not auto-prefixed).
      */
     after?: string[];
     /**
@@ -1294,21 +1293,14 @@ type CrossModuleDerivationFn<M extends ModuleSchema, Deps extends CrossModuleDep
 type CrossModuleDerivationsDef<M extends ModuleSchema, Deps extends CrossModuleDeps> = {
     [K in keyof GetDerivationsSchema<M>]: CrossModuleDerivationFn<M, Deps, K>;
 };
-/**
- * Retry policy configuration.
- */
-interface RetryPolicy {
-    attempts: number;
-    backoff: "none" | "linear" | "exponential";
-    initialDelay?: number;
-    maxDelay?: number;
-}
 /**
  * Resolver context with typed facts.
  */
 interface TypedResolverContext<M extends ModuleSchema> {
     readonly facts: Facts<M["facts"]>;
     readonly signal: AbortSignal;
+    /** Returns a read-only snapshot of the current facts state, useful for before/after comparisons inside resolvers. */
+    readonly snapshot: () => FactsSnapshot<M["facts"]>;
 }
 /**
  * Helper to extract a specific requirement type from the schema.
@@ -1328,8 +1320,14 @@ interface TypedResolverDef<M extends ModuleSchema, T extends keyof GetRequiremen
     retry?: RetryPolicy;
     /** Timeout for resolver execution (ms) */
     timeout?: number;
-    /** Resolve function */
-    resolve: (req: ExtractRequirement<M, T>, ctx: TypedResolverContext<M>) => Promise<void>;
+    /** Batch configuration */
+    batch?: BatchConfig;
+    /** Resolve function for single requirement */
+    resolve?: (req: ExtractRequirement<M, T>, ctx: TypedResolverContext<M>) => Promise<void>;
+    /** Resolve batched requirements as a group (all-or-nothing). Receives the full array collected during the batch window. If this throws, all items in the batch are considered failed. */
+    resolveBatch?: (reqs: ExtractRequirement<M, T>[], ctx: TypedResolverContext<M>) => Promise<void>;
+    /** Resolve batched requirements with per-item success/failure results. Return a `BatchResolveResults` array in the same order as the input. Failed items can be individually retried. */
+    resolveBatchWithResults?: (reqs: ExtractRequirement<M, T>[], ctx: TypedResolverContext<M>) => Promise<BatchResolveResults>;
 }
 /**
  * Union of all typed resolver definitions for all requirement types.
@@ -1409,6 +1407,10 @@ interface DebugConfig {
     maxSnapshots?: number;
     /** Only snapshot events from these modules. Omit to snapshot all modules. Multi-module only. */
     snapshotModules?: string[];
+    /** Enable per-run changelog (default false) */
+    runHistory?: boolean;
+    /** Ring buffer cap for run history (default 100) */
+    maxRuns?: number;
 }
 /** Time-travel API */
 interface TimeTravelAPI {
@@ -1454,6 +1456,79 @@ interface TimeTravelState {
     pause: () => void;
     resume: () => void;
 }
+/** A structured record of one reconciliation run — from facts through resolvers and effects. */
+interface RunChangelogEntry {
+    /** Monotonic run ID */
+    id: number;
+    /** When the reconcile started */
+    timestamp: number;
+    /** Total duration from reconcile start to all resolvers settled (ms) */
+    duration: number;
+    /** 'pending' while resolvers are inflight, 'settled' when all done */
+    status: "pending" | "settled";
+    /** Facts that changed, triggering this run */
+    factChanges: Array<{
+        key: string;
+        oldValue: unknown;
+        newValue: unknown;
+    }>;
+    /** Derivations recomputed during this run, with tracked dependencies and values */
+    derivationsRecomputed: Array<{
+        id: string;
+        deps: string[];
+        oldValue: unknown;
+        newValue: unknown;
+    }>;
+    /** Constraints that evaluated to active, with tracked dependencies */
+    constraintsHit: Array<{
+        id: string;
+        priority: number;
+        deps: string[];
+    }>;
+    /** Requirements added from constraint diff */
+    requirementsAdded: Array<{
+        id: string;
+        type: string;
+        fromConstraint: string;
+    }>;
+    /** Requirements removed (no longer active), with originating constraint */
+    requirementsRemoved: Array<{
+        id: string;
+        type: string;
+        fromConstraint: string;
+    }>;
+    /** Resolvers started for new requirements */
+    resolversStarted: Array<{
+        resolver: string;
+        requirementId: string;
+    }>;
+    /** Resolvers that completed (async — populated after reconcile) */
+    resolversCompleted: Array<{
+        resolver: string;
+        requirementId: string;
+        duration: number;
+    }>;
+    /** Resolvers that errored (async — populated after reconcile) */
+    resolversErrored: Array<{
+        resolver: string;
+        requirementId: string;
+        error: string;
+    }>;
+    /** Effects that ran, with their triggering fact keys */
+    effectsRun: Array<{
+        id: string;
+        triggeredBy: string[];
+    }>;
+    /** Effect errors */
+    effectErrors: Array<{
+        id: string;
+        error: string;
+    }>;
+    /** Human-readable causal chain summary (populated when run settles) */
+    causalChain?: string;
+    /** Anomaly flags (populated when run stats deviate significantly) */
+    anomalies?: string[];
+}
 /** System inspection result */
 interface SystemInspection {
     unmet: RequirementWithId[];
@@ -1465,9 +1540,21 @@ interface SystemInspection {
     constraints: Array<{
         id: string;
         active: boolean;
+        disabled: boolean;
         priority: number;
+        hitCount: number;
+        lastActiveAt: number | null;
     }>;
     resolvers: Record<string, ResolverStatus>;
+    /** All defined resolver names and their requirement types */
+    resolverDefs: Array<{
+        id: string;
+        requirement: string;
+    }>;
+    /** Whether debug.runHistory is enabled on this system */
+    runHistoryEnabled: boolean;
+    /** Per-run changelog entries (only present if debug.runHistory is enabled) */
+    runHistory?: RunChangelogEntry[];
 }
 /** Explanation of why a requirement exists */
 interface RequirementExplanation {
@@ -1546,6 +1633,8 @@ interface ConstraintsControl {
     disable(id: string): void;
     /** Enable a previously disabled constraint — it will be re-evaluated on the next cycle */
     enable(id: string): void;
+    /** Check if a constraint is currently disabled */
+    isDisabled(id: string): boolean;
 }
 /** Runtime control for effects */
 interface EffectsControl {
@@ -1563,6 +1652,10 @@ interface System<M extends ModuleSchema = ModuleSchema> {
     readonly events: EventsAccessorFromSchema<M>;
     readonly constraints: ConstraintsControl;
     readonly effects: EffectsControl;
+    /** Per-run changelog entries (null if debug.runHistory is not enabled) */
+    readonly runHistory: RunChangelogEntry[] | null;
+    /** Initialize facts and derivations without starting reconciliation. Safe for SSR. */
+    initialize(): void;
     start(): void;
     stop(): void;
     destroy(): void;
@@ -1881,6 +1974,12 @@ interface Plugin<M extends ModuleSchema = ModuleSchema> {
      * @param strategy - The recovery strategy used
      */
     onErrorRecovery?: (error: DirectiveError, strategy: RecoveryStrategy) => void;
+    /**
+     * Called when a run finalizes (all resolvers settled or no resolvers started).
+     * Only fires when debug.runHistory is enabled.
+     * @param run - The complete run changelog entry
+     */
+    onRunComplete?: (run: RunChangelogEntry) => void;
 }
 
-export { type BatchItemResult as $, type ConstraintState as A, type BatchConfig as B, type CrossModuleDeps as C, type DerivationsSchema as D, type EffectsDef as E, type Facts as F, type ResolversDef as G, type ResolverStatus as H, type InferRequirements as I, type System as J, type FactChange as K, type FactsSnapshot as L, type ModuleSchema as M, type NamespacedSystem as N, type ReconcileResult as O, type Plugin as P, type Snapshot as Q, type Requirement as R, type Schema as S, type TypedDerivationsDef as T, DirectiveError as U, type RecoveryStrategy as V, type ErrorSource as W, type RetryLaterConfig as X, type TimeTravelAPI as Y, type SystemConfig as Z, type AnySystem as _, type RequirementOutput$1 as a, type BatchResolveResults as a0, type CircuitBreakerConfig as a1, type CircuitBreakerState as a2, type CrossModuleConstraintDef as a3, type CrossModuleDerivationFn as a4, type CrossModuleEffectDef as a5, type CrossModuleFactsWithSelf as a6, type DerivationKeys as a7, type DerivationReturnType as a8, type DeriveAccessor as a9, type RequirementPayloadSchema$1 as aA, type RequirementsSchema as aB, type SnapshotMeta as aC, type SystemEvent as aD, type SystemInspection as aE, type SystemMode as aF, type SystemSnapshot as aG, type TimeTravelState as aH, type TypedResolverContext as aI, type TypedResolverDef as aJ, type UnionEvents as aK, isNamespacedSystem as aL, isSingleModuleSystem as aM, type DispatchEventsFromSchema as aa, type DistributableSnapshot as ab, type DistributableSnapshotOptions as ac, type EffectCleanup as ad, type EventPayloadSchema as ae, type EventsAccessor as af, type EventsAccessorFromSchema as ag, type EventsDef as ah, type EventsSchema as ai, type FactKeys as aj, type FactReturnType as ak, type FlexibleEventHandler as al, type InferDerivations as am, type InferEventPayloadFromSchema as an, type InferEvents as ao, type InferRequirementPayloadFromSchema as ap, type InferRequirementTypes as aq, type InferSchema as ar, type InferSchemaType as as, type InferSelectorState as at, type MutableNamespacedFacts as au, type NamespacedDerivations as av, type NamespacedEventsAccessor as aw, type NamespacedFacts as ax, type ObservableKeys as ay, type RequirementExplanation as az, type RetryPolicy$1 as b, type ResolverContext as c, type SchemaType as d, type FactsStore as e, type TypedEventsDef as f, type TypedConstraintsDef as g, type TypedResolversDef as h, type ModuleHooks as i, type CrossModuleDerivationsDef as j, type CrossModuleEffectsDef as k, type CrossModuleConstraintsDef as l, type ModuleDef as m, type CreateSystemOptionsSingle as n, type SingleModuleSystem as o, type ModulesMap as p, type CreateSystemOptionsNamed as q, type TypedConstraintDef as r, type RequirementOutput as s, type DebugConfig as t, type ErrorBoundaryConfig as u, type InferFacts as v, type ExtractSchema as w, type RequirementWithId as x, type RequirementKeyFn as y, type ConstraintsDef as z };
+export { type AnySystem as $, type ConstraintState as A, type BatchConfig as B, type CrossModuleDeps as C, type DerivationsSchema as D, type EffectsDef as E, type Facts as F, type ResolversDef as G, type ResolverStatus as H, type InferRequirements as I, type System as J, type FactChange as K, type FactsSnapshot as L, type ModuleSchema as M, type NamespacedSystem as N, type ReconcileResult as O, type Plugin as P, type Snapshot as Q, type Requirement as R, type Schema as S, type TypedDerivationsDef as T, DirectiveError as U, type RecoveryStrategy as V, type RunChangelogEntry as W, type ErrorSource as X, type RetryLaterConfig as Y, type TimeTravelAPI as Z, type SystemConfig as _, type RequirementOutput$1 as a, type BatchItemResult as a0, type BatchResolveResults as a1, type CrossModuleConstraintDef as a2, type CrossModuleDerivationFn as a3, type CrossModuleEffectDef as a4, type CrossModuleFactsWithSelf as a5, type DerivationKeys as a6, type DerivationReturnType as a7, type DeriveAccessor as a8, type DispatchEventsFromSchema as a9, type RequirementsSchema as aA, type SnapshotMeta as aB, type SystemEvent as aC, type SystemInspection as aD, type SystemMode as aE, type SystemSnapshot as aF, type TimeTravelState as aG, type TypedResolverContext as aH, type TypedResolverDef as aI, type UnionEvents as aJ, isNamespacedSystem as aK, isSingleModuleSystem as aL, type DistributableSnapshot as aa, type DistributableSnapshotOptions as ab, type EffectCleanup as ac, type EventPayloadSchema as ad, type EventsAccessor as ae, type EventsAccessorFromSchema as af, type EventsDef as ag, type EventsSchema as ah, type FactKeys as ai, type FactReturnType as aj, type FlexibleEventHandler as ak, type InferDerivations as al, type InferEventPayloadFromSchema as am, type InferEvents as an, type InferRequirementPayloadFromSchema as ao, type InferRequirementTypes as ap, type InferSchema as aq, type InferSchemaType as ar, type InferSelectorState as as, type MutableNamespacedFacts as at, type NamespacedDerivations as au, type NamespacedEventsAccessor as av, type NamespacedFacts as aw, type ObservableKeys as ax, type RequirementExplanation as ay, type RequirementPayloadSchema$1 as az, type RetryPolicy as b, type ResolverContext as c, type SchemaType as d, type FactsStore as e, type TypedEventsDef as f, type TypedConstraintsDef as g, type TypedResolversDef as h, type ModuleHooks as i, type CrossModuleDerivationsDef as j, type CrossModuleEffectsDef as k, type CrossModuleConstraintsDef as l, type ModuleDef as m, type CreateSystemOptionsSingle as n, type SingleModuleSystem as o, type ModulesMap as p, type CreateSystemOptionsNamed as q, type TypedConstraintDef as r, type RequirementOutput as s, type DebugConfig as t, type ErrorBoundaryConfig as u, type InferFacts as v, type ExtractSchema as w, type RequirementWithId as x, type RequirementKeyFn as y, type ConstraintsDef as z };