@directive-run/core 0.1.1 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -275,6 +275,10 @@ interface ConstraintState {
275
275
  lastResolvedAt: number | null;
276
276
  /** Constraint IDs this constraint is waiting on (from `after` property) */
277
277
  after: string[];
278
+ /** Number of times when() evaluated to true */
279
+ hitCount: number;
280
+ /** Timestamp of last when() → true evaluation */
281
+ lastActiveAt: number | null;
278
282
  }
279
283
 
280
284
  /**
@@ -337,7 +341,7 @@ type EffectCleanup = () => void;
337
341
  * ```
338
342
  */
339
343
  interface EffectDef<S extends Schema> {
340
- run(facts: Facts<S>, prev: FactsSnapshot<S> | null): void | EffectCleanup | Promise<void | EffectCleanup>;
344
+ run(facts: Facts<S>, prev: InferSchema<S> | null): void | EffectCleanup | Promise<void | EffectCleanup>;
341
345
  /** Optional explicit dependencies for optimization */
342
346
  deps?: Array<keyof InferSchema<S>>;
343
347
  }
@@ -751,6 +755,14 @@ interface NamespacedSystem<Modules extends ModulesMap> {
751
755
  readonly derive: NamespacedDerivations<Modules>;
752
756
  /** Events accessor (union of all module events) */
753
757
  readonly events: NamespacedEventsAccessor<Modules>;
758
+ /** Runtime control for constraints (disable/enable/isDisabled) */
759
+ readonly constraints: ConstraintsControl;
760
+ /** Runtime control for effects (disable/enable/isEnabled) */
761
+ readonly effects: EffectsControl;
762
+ /** Per-run changelog entries (null if debug.runHistory is not enabled) */
763
+ readonly runHistory: RunChangelogEntry[] | null;
764
+ /** Initialize facts and derivations without starting reconciliation. Safe for SSR. */
765
+ initialize(): void;
754
766
  /** Start the system (initialize modules, begin reconciliation) */
755
767
  start(): void;
756
768
  /** Stop the system (cancel resolvers, stop reconciliation) */
@@ -970,6 +982,14 @@ interface SingleModuleSystem<S extends ModuleSchema> {
970
982
  readonly derive: InferDerivations<S>;
971
983
  /** Direct events accessor: system.events.increment() */
972
984
  readonly events: SingleModuleEvents<S>;
985
+ /** Runtime control for constraints (disable/enable/isDisabled) */
986
+ readonly constraints: ConstraintsControl;
987
+ /** Runtime control for effects (disable/enable/isEnabled) */
988
+ readonly effects: EffectsControl;
989
+ /** Per-run changelog entries (null if debug.runHistory is not enabled) */
990
+ readonly runHistory: RunChangelogEntry[] | null;
991
+ /** Initialize facts and derivations without starting reconciliation. Safe for SSR. */
992
+ initialize(): void;
973
993
  /** Start the system (initialize modules, begin reconciliation) */
974
994
  start(): void;
975
995
  /** Stop the system (cancel resolvers, stop reconciliation) */
@@ -1109,6 +1129,7 @@ interface AnySystem {
1109
1129
  readonly isSettled: boolean;
1110
1130
  readonly isInitialized: boolean;
1111
1131
  readonly isReady: boolean;
1132
+ initialize(): void;
1112
1133
  start(): void;
1113
1134
  stop(): void;
1114
1135
  destroy(): void;
@@ -1357,6 +1378,12 @@ interface ModuleDef<M extends ModuleSchema = ModuleSchema> {
1357
1378
  constraints?: TypedConstraintsDef<M>;
1358
1379
  resolvers?: TypedResolversDef<M>;
1359
1380
  hooks?: ModuleHooks<M>;
1381
+ /**
1382
+ * Events that create time-travel snapshots.
1383
+ * If omitted, ALL events create snapshots (default).
1384
+ * If provided, only listed events create snapshots for undo/redo.
1385
+ */
1386
+ snapshotEvents?: Array<keyof GetEventsSchema<M> & string>;
1360
1387
  /**
1361
1388
  * Cross-module dependencies (runtime marker).
1362
1389
  * When present, constraints/effects receive `facts.self.*` + `facts.{dep}.*`.
@@ -1401,6 +1428,12 @@ type EventsAccessor<M extends ModuleSchema> = EventsAccessorFromSchema<M>;
1401
1428
  interface DebugConfig {
1402
1429
  timeTravel?: boolean;
1403
1430
  maxSnapshots?: number;
1431
+ /** Only snapshot events from these modules. Omit to snapshot all modules. Multi-module only. */
1432
+ snapshotModules?: string[];
1433
+ /** Enable per-run changelog (default false) */
1434
+ runHistory?: boolean;
1435
+ /** Ring buffer cap for run history (default 100) */
1436
+ maxRuns?: number;
1404
1437
  }
1405
1438
  /** Time-travel API */
1406
1439
  interface TimeTravelAPI {
@@ -1446,6 +1479,79 @@ interface TimeTravelState {
1446
1479
  pause: () => void;
1447
1480
  resume: () => void;
1448
1481
  }
1482
+ /** A structured record of one reconciliation run — from facts through resolvers and effects. */
1483
+ interface RunChangelogEntry {
1484
+ /** Monotonic run ID */
1485
+ id: number;
1486
+ /** When the reconcile started */
1487
+ timestamp: number;
1488
+ /** Total duration from reconcile start to all resolvers settled (ms) */
1489
+ duration: number;
1490
+ /** 'pending' while resolvers are inflight, 'settled' when all done */
1491
+ status: "pending" | "settled";
1492
+ /** Facts that changed, triggering this run */
1493
+ factChanges: Array<{
1494
+ key: string;
1495
+ oldValue: unknown;
1496
+ newValue: unknown;
1497
+ }>;
1498
+ /** Derivations recomputed during this run, with tracked dependencies and values */
1499
+ derivationsRecomputed: Array<{
1500
+ id: string;
1501
+ deps: string[];
1502
+ oldValue: unknown;
1503
+ newValue: unknown;
1504
+ }>;
1505
+ /** Constraints that evaluated to active, with tracked dependencies */
1506
+ constraintsHit: Array<{
1507
+ id: string;
1508
+ priority: number;
1509
+ deps: string[];
1510
+ }>;
1511
+ /** Requirements added from constraint diff */
1512
+ requirementsAdded: Array<{
1513
+ id: string;
1514
+ type: string;
1515
+ fromConstraint: string;
1516
+ }>;
1517
+ /** Requirements removed (no longer active), with originating constraint */
1518
+ requirementsRemoved: Array<{
1519
+ id: string;
1520
+ type: string;
1521
+ fromConstraint: string;
1522
+ }>;
1523
+ /** Resolvers started for new requirements */
1524
+ resolversStarted: Array<{
1525
+ resolver: string;
1526
+ requirementId: string;
1527
+ }>;
1528
+ /** Resolvers that completed (async — populated after reconcile) */
1529
+ resolversCompleted: Array<{
1530
+ resolver: string;
1531
+ requirementId: string;
1532
+ duration: number;
1533
+ }>;
1534
+ /** Resolvers that errored (async — populated after reconcile) */
1535
+ resolversErrored: Array<{
1536
+ resolver: string;
1537
+ requirementId: string;
1538
+ error: string;
1539
+ }>;
1540
+ /** Effects that ran, with their triggering fact keys */
1541
+ effectsRun: Array<{
1542
+ id: string;
1543
+ triggeredBy: string[];
1544
+ }>;
1545
+ /** Effect errors */
1546
+ effectErrors: Array<{
1547
+ id: string;
1548
+ error: string;
1549
+ }>;
1550
+ /** Human-readable causal chain summary (populated when run settles) */
1551
+ causalChain?: string;
1552
+ /** Anomaly flags (populated when run stats deviate significantly) */
1553
+ anomalies?: string[];
1554
+ }
1449
1555
  /** System inspection result */
1450
1556
  interface SystemInspection {
1451
1557
  unmet: RequirementWithId[];
@@ -1457,9 +1563,21 @@ interface SystemInspection {
1457
1563
  constraints: Array<{
1458
1564
  id: string;
1459
1565
  active: boolean;
1566
+ disabled: boolean;
1460
1567
  priority: number;
1568
+ hitCount: number;
1569
+ lastActiveAt: number | null;
1461
1570
  }>;
1462
1571
  resolvers: Record<string, ResolverStatus>;
1572
+ /** All defined resolver names and their requirement types */
1573
+ resolverDefs: Array<{
1574
+ id: string;
1575
+ requirement: string;
1576
+ }>;
1577
+ /** Whether debug.runHistory is enabled on this system */
1578
+ runHistoryEnabled: boolean;
1579
+ /** Per-run changelog entries (only present if debug.runHistory is enabled) */
1580
+ runHistory?: RunChangelogEntry[];
1463
1581
  }
1464
1582
  /** Explanation of why a requirement exists */
1465
1583
  interface RequirementExplanation {
@@ -1511,7 +1629,9 @@ interface DistributableSnapshotOptions {
1511
1629
  *
1512
1630
  * // Later, in an API route (no Directive runtime needed)
1513
1631
  * const cached = JSON.parse(await redis.get(`entitlements:${userId}`));
1514
- * if (!cached.data.canUseFeature.api) throw new ForbiddenError();
1632
+ * if (!cached.data.canUseFeature.api) {
1633
+ * throw new ForbiddenError();
1634
+ * }
1515
1635
  * ```
1516
1636
  */
1517
1637
  interface DistributableSnapshot<T = Record<string, unknown>> {
@@ -1536,6 +1656,8 @@ interface ConstraintsControl {
1536
1656
  disable(id: string): void;
1537
1657
  /** Enable a previously disabled constraint — it will be re-evaluated on the next cycle */
1538
1658
  enable(id: string): void;
1659
+ /** Check if a constraint is currently disabled */
1660
+ isDisabled(id: string): boolean;
1539
1661
  }
1540
1662
  /** Runtime control for effects */
1541
1663
  interface EffectsControl {
@@ -1553,6 +1675,10 @@ interface System<M extends ModuleSchema = ModuleSchema> {
1553
1675
  readonly events: EventsAccessorFromSchema<M>;
1554
1676
  readonly constraints: ConstraintsControl;
1555
1677
  readonly effects: EffectsControl;
1678
+ /** Per-run changelog entries (null if debug.runHistory is not enabled) */
1679
+ readonly runHistory: RunChangelogEntry[] | null;
1680
+ /** Initialize facts and derivations without starting reconciliation. Safe for SSR. */
1681
+ initialize(): void;
1556
1682
  start(): void;
1557
1683
  stop(): void;
1558
1684
  destroy(): void;
@@ -1871,6 +1997,12 @@ interface Plugin<M extends ModuleSchema = ModuleSchema> {
1871
1997
  * @param strategy - The recovery strategy used
1872
1998
  */
1873
1999
  onErrorRecovery?: (error: DirectiveError, strategy: RecoveryStrategy) => void;
2000
+ /**
2001
+ * Called when a run finalizes (all resolvers settled or no resolvers started).
2002
+ * Only fires when debug.runHistory is enabled.
2003
+ * @param run - The complete run changelog entry
2004
+ */
2005
+ onRunComplete?: (run: RunChangelogEntry) => void;
1874
2006
  }
1875
2007
 
1876
- 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 };
2008
+ 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 CircuitBreakerConfig as a2, type CircuitBreakerState as a3, type CrossModuleConstraintDef as a4, type CrossModuleDerivationFn as a5, type CrossModuleEffectDef as a6, type CrossModuleFactsWithSelf as a7, type DerivationKeys as a8, type DerivationReturnType as a9, type RequirementExplanation as aA, type RequirementPayloadSchema$1 as aB, type RequirementsSchema as aC, type SnapshotMeta as aD, type SystemEvent as aE, type SystemInspection as aF, type SystemMode as aG, type SystemSnapshot as aH, type TimeTravelState as aI, type TypedResolverContext as aJ, type TypedResolverDef as aK, type UnionEvents as aL, isNamespacedSystem as aM, isSingleModuleSystem as aN, type DeriveAccessor as aa, type DispatchEventsFromSchema as ab, type DistributableSnapshot as ac, type DistributableSnapshotOptions as ad, type EffectCleanup as ae, type EventPayloadSchema as af, type EventsAccessor as ag, type EventsAccessorFromSchema as ah, type EventsDef as ai, type EventsSchema as aj, type FactKeys as ak, type FactReturnType as al, type FlexibleEventHandler as am, type InferDerivations as an, type InferEventPayloadFromSchema as ao, type InferEvents as ap, type InferRequirementPayloadFromSchema as aq, type InferRequirementTypes as ar, type InferSchema as as, type InferSchemaType as at, type InferSelectorState as au, type MutableNamespacedFacts as av, type NamespacedDerivations as aw, type NamespacedEventsAccessor as ax, type NamespacedFacts as ay, type ObservableKeys 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 };
@@ -275,6 +275,10 @@ interface ConstraintState {
275
275
  lastResolvedAt: number | null;
276
276
  /** Constraint IDs this constraint is waiting on (from `after` property) */
277
277
  after: string[];
278
+ /** Number of times when() evaluated to true */
279
+ hitCount: number;
280
+ /** Timestamp of last when() → true evaluation */
281
+ lastActiveAt: number | null;
278
282
  }
279
283
 
280
284
  /**
@@ -337,7 +341,7 @@ type EffectCleanup = () => void;
337
341
  * ```
338
342
  */
339
343
  interface EffectDef<S extends Schema> {
340
- run(facts: Facts<S>, prev: FactsSnapshot<S> | null): void | EffectCleanup | Promise<void | EffectCleanup>;
344
+ run(facts: Facts<S>, prev: InferSchema<S> | null): void | EffectCleanup | Promise<void | EffectCleanup>;
341
345
  /** Optional explicit dependencies for optimization */
342
346
  deps?: Array<keyof InferSchema<S>>;
343
347
  }
@@ -751,6 +755,14 @@ interface NamespacedSystem<Modules extends ModulesMap> {
751
755
  readonly derive: NamespacedDerivations<Modules>;
752
756
  /** Events accessor (union of all module events) */
753
757
  readonly events: NamespacedEventsAccessor<Modules>;
758
+ /** Runtime control for constraints (disable/enable/isDisabled) */
759
+ readonly constraints: ConstraintsControl;
760
+ /** Runtime control for effects (disable/enable/isEnabled) */
761
+ readonly effects: EffectsControl;
762
+ /** Per-run changelog entries (null if debug.runHistory is not enabled) */
763
+ readonly runHistory: RunChangelogEntry[] | null;
764
+ /** Initialize facts and derivations without starting reconciliation. Safe for SSR. */
765
+ initialize(): void;
754
766
  /** Start the system (initialize modules, begin reconciliation) */
755
767
  start(): void;
756
768
  /** Stop the system (cancel resolvers, stop reconciliation) */
@@ -970,6 +982,14 @@ interface SingleModuleSystem<S extends ModuleSchema> {
970
982
  readonly derive: InferDerivations<S>;
971
983
  /** Direct events accessor: system.events.increment() */
972
984
  readonly events: SingleModuleEvents<S>;
985
+ /** Runtime control for constraints (disable/enable/isDisabled) */
986
+ readonly constraints: ConstraintsControl;
987
+ /** Runtime control for effects (disable/enable/isEnabled) */
988
+ readonly effects: EffectsControl;
989
+ /** Per-run changelog entries (null if debug.runHistory is not enabled) */
990
+ readonly runHistory: RunChangelogEntry[] | null;
991
+ /** Initialize facts and derivations without starting reconciliation. Safe for SSR. */
992
+ initialize(): void;
973
993
  /** Start the system (initialize modules, begin reconciliation) */
974
994
  start(): void;
975
995
  /** Stop the system (cancel resolvers, stop reconciliation) */
@@ -1109,6 +1129,7 @@ interface AnySystem {
1109
1129
  readonly isSettled: boolean;
1110
1130
  readonly isInitialized: boolean;
1111
1131
  readonly isReady: boolean;
1132
+ initialize(): void;
1112
1133
  start(): void;
1113
1134
  stop(): void;
1114
1135
  destroy(): void;
@@ -1357,6 +1378,12 @@ interface ModuleDef<M extends ModuleSchema = ModuleSchema> {
1357
1378
  constraints?: TypedConstraintsDef<M>;
1358
1379
  resolvers?: TypedResolversDef<M>;
1359
1380
  hooks?: ModuleHooks<M>;
1381
+ /**
1382
+ * Events that create time-travel snapshots.
1383
+ * If omitted, ALL events create snapshots (default).
1384
+ * If provided, only listed events create snapshots for undo/redo.
1385
+ */
1386
+ snapshotEvents?: Array<keyof GetEventsSchema<M> & string>;
1360
1387
  /**
1361
1388
  * Cross-module dependencies (runtime marker).
1362
1389
  * When present, constraints/effects receive `facts.self.*` + `facts.{dep}.*`.
@@ -1401,6 +1428,12 @@ type EventsAccessor<M extends ModuleSchema> = EventsAccessorFromSchema<M>;
1401
1428
  interface DebugConfig {
1402
1429
  timeTravel?: boolean;
1403
1430
  maxSnapshots?: number;
1431
+ /** Only snapshot events from these modules. Omit to snapshot all modules. Multi-module only. */
1432
+ snapshotModules?: string[];
1433
+ /** Enable per-run changelog (default false) */
1434
+ runHistory?: boolean;
1435
+ /** Ring buffer cap for run history (default 100) */
1436
+ maxRuns?: number;
1404
1437
  }
1405
1438
  /** Time-travel API */
1406
1439
  interface TimeTravelAPI {
@@ -1446,6 +1479,79 @@ interface TimeTravelState {
1446
1479
  pause: () => void;
1447
1480
  resume: () => void;
1448
1481
  }
1482
+ /** A structured record of one reconciliation run — from facts through resolvers and effects. */
1483
+ interface RunChangelogEntry {
1484
+ /** Monotonic run ID */
1485
+ id: number;
1486
+ /** When the reconcile started */
1487
+ timestamp: number;
1488
+ /** Total duration from reconcile start to all resolvers settled (ms) */
1489
+ duration: number;
1490
+ /** 'pending' while resolvers are inflight, 'settled' when all done */
1491
+ status: "pending" | "settled";
1492
+ /** Facts that changed, triggering this run */
1493
+ factChanges: Array<{
1494
+ key: string;
1495
+ oldValue: unknown;
1496
+ newValue: unknown;
1497
+ }>;
1498
+ /** Derivations recomputed during this run, with tracked dependencies and values */
1499
+ derivationsRecomputed: Array<{
1500
+ id: string;
1501
+ deps: string[];
1502
+ oldValue: unknown;
1503
+ newValue: unknown;
1504
+ }>;
1505
+ /** Constraints that evaluated to active, with tracked dependencies */
1506
+ constraintsHit: Array<{
1507
+ id: string;
1508
+ priority: number;
1509
+ deps: string[];
1510
+ }>;
1511
+ /** Requirements added from constraint diff */
1512
+ requirementsAdded: Array<{
1513
+ id: string;
1514
+ type: string;
1515
+ fromConstraint: string;
1516
+ }>;
1517
+ /** Requirements removed (no longer active), with originating constraint */
1518
+ requirementsRemoved: Array<{
1519
+ id: string;
1520
+ type: string;
1521
+ fromConstraint: string;
1522
+ }>;
1523
+ /** Resolvers started for new requirements */
1524
+ resolversStarted: Array<{
1525
+ resolver: string;
1526
+ requirementId: string;
1527
+ }>;
1528
+ /** Resolvers that completed (async — populated after reconcile) */
1529
+ resolversCompleted: Array<{
1530
+ resolver: string;
1531
+ requirementId: string;
1532
+ duration: number;
1533
+ }>;
1534
+ /** Resolvers that errored (async — populated after reconcile) */
1535
+ resolversErrored: Array<{
1536
+ resolver: string;
1537
+ requirementId: string;
1538
+ error: string;
1539
+ }>;
1540
+ /** Effects that ran, with their triggering fact keys */
1541
+ effectsRun: Array<{
1542
+ id: string;
1543
+ triggeredBy: string[];
1544
+ }>;
1545
+ /** Effect errors */
1546
+ effectErrors: Array<{
1547
+ id: string;
1548
+ error: string;
1549
+ }>;
1550
+ /** Human-readable causal chain summary (populated when run settles) */
1551
+ causalChain?: string;
1552
+ /** Anomaly flags (populated when run stats deviate significantly) */
1553
+ anomalies?: string[];
1554
+ }
1449
1555
  /** System inspection result */
1450
1556
  interface SystemInspection {
1451
1557
  unmet: RequirementWithId[];
@@ -1457,9 +1563,21 @@ interface SystemInspection {
1457
1563
  constraints: Array<{
1458
1564
  id: string;
1459
1565
  active: boolean;
1566
+ disabled: boolean;
1460
1567
  priority: number;
1568
+ hitCount: number;
1569
+ lastActiveAt: number | null;
1461
1570
  }>;
1462
1571
  resolvers: Record<string, ResolverStatus>;
1572
+ /** All defined resolver names and their requirement types */
1573
+ resolverDefs: Array<{
1574
+ id: string;
1575
+ requirement: string;
1576
+ }>;
1577
+ /** Whether debug.runHistory is enabled on this system */
1578
+ runHistoryEnabled: boolean;
1579
+ /** Per-run changelog entries (only present if debug.runHistory is enabled) */
1580
+ runHistory?: RunChangelogEntry[];
1463
1581
  }
1464
1582
  /** Explanation of why a requirement exists */
1465
1583
  interface RequirementExplanation {
@@ -1511,7 +1629,9 @@ interface DistributableSnapshotOptions {
1511
1629
  *
1512
1630
  * // Later, in an API route (no Directive runtime needed)
1513
1631
  * const cached = JSON.parse(await redis.get(`entitlements:${userId}`));
1514
- * if (!cached.data.canUseFeature.api) throw new ForbiddenError();
1632
+ * if (!cached.data.canUseFeature.api) {
1633
+ * throw new ForbiddenError();
1634
+ * }
1515
1635
  * ```
1516
1636
  */
1517
1637
  interface DistributableSnapshot<T = Record<string, unknown>> {
@@ -1536,6 +1656,8 @@ interface ConstraintsControl {
1536
1656
  disable(id: string): void;
1537
1657
  /** Enable a previously disabled constraint — it will be re-evaluated on the next cycle */
1538
1658
  enable(id: string): void;
1659
+ /** Check if a constraint is currently disabled */
1660
+ isDisabled(id: string): boolean;
1539
1661
  }
1540
1662
  /** Runtime control for effects */
1541
1663
  interface EffectsControl {
@@ -1553,6 +1675,10 @@ interface System<M extends ModuleSchema = ModuleSchema> {
1553
1675
  readonly events: EventsAccessorFromSchema<M>;
1554
1676
  readonly constraints: ConstraintsControl;
1555
1677
  readonly effects: EffectsControl;
1678
+ /** Per-run changelog entries (null if debug.runHistory is not enabled) */
1679
+ readonly runHistory: RunChangelogEntry[] | null;
1680
+ /** Initialize facts and derivations without starting reconciliation. Safe for SSR. */
1681
+ initialize(): void;
1556
1682
  start(): void;
1557
1683
  stop(): void;
1558
1684
  destroy(): void;
@@ -1871,6 +1997,12 @@ interface Plugin<M extends ModuleSchema = ModuleSchema> {
1871
1997
  * @param strategy - The recovery strategy used
1872
1998
  */
1873
1999
  onErrorRecovery?: (error: DirectiveError, strategy: RecoveryStrategy) => void;
2000
+ /**
2001
+ * Called when a run finalizes (all resolvers settled or no resolvers started).
2002
+ * Only fires when debug.runHistory is enabled.
2003
+ * @param run - The complete run changelog entry
2004
+ */
2005
+ onRunComplete?: (run: RunChangelogEntry) => void;
1874
2006
  }
1875
2007
 
1876
- 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 };
2008
+ 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 CircuitBreakerConfig as a2, type CircuitBreakerState as a3, type CrossModuleConstraintDef as a4, type CrossModuleDerivationFn as a5, type CrossModuleEffectDef as a6, type CrossModuleFactsWithSelf as a7, type DerivationKeys as a8, type DerivationReturnType as a9, type RequirementExplanation as aA, type RequirementPayloadSchema$1 as aB, type RequirementsSchema as aC, type SnapshotMeta as aD, type SystemEvent as aE, type SystemInspection as aF, type SystemMode as aG, type SystemSnapshot as aH, type TimeTravelState as aI, type TypedResolverContext as aJ, type TypedResolverDef as aK, type UnionEvents as aL, isNamespacedSystem as aM, isSingleModuleSystem as aN, type DeriveAccessor as aa, type DispatchEventsFromSchema as ab, type DistributableSnapshot as ac, type DistributableSnapshotOptions as ad, type EffectCleanup as ae, type EventPayloadSchema as af, type EventsAccessor as ag, type EventsAccessorFromSchema as ah, type EventsDef as ai, type EventsSchema as aj, type FactKeys as ak, type FactReturnType as al, type FlexibleEventHandler as am, type InferDerivations as an, type InferEventPayloadFromSchema as ao, type InferEvents as ap, type InferRequirementPayloadFromSchema as aq, type InferRequirementTypes as ar, type InferSchema as as, type InferSchemaType as at, type InferSelectorState as au, type MutableNamespacedFacts as av, type NamespacedDerivations as aw, type NamespacedEventsAccessor as ax, type NamespacedFacts as ay, type ObservableKeys 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 };