@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.
- package/README.md +153 -9
- package/dist/adapter-utils.d.cts +1 -1
- package/dist/adapter-utils.d.ts +1 -1
- package/dist/index.cjs +16 -16
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +18 -39
- package/dist/index.d.ts +18 -39
- package/dist/index.js +16 -16
- package/dist/index.js.map +1 -1
- package/dist/migration.cjs +12 -12
- package/dist/migration.cjs.map +1 -1
- package/dist/migration.js +12 -12
- package/dist/migration.js.map +1 -1
- package/dist/plugins/index.cjs +2 -2
- package/dist/plugins/index.cjs.map +1 -1
- package/dist/plugins/index.d.cts +103 -23
- package/dist/plugins/index.d.ts +103 -23
- package/dist/plugins/index.js +2 -2
- package/dist/plugins/index.js.map +1 -1
- package/dist/{plugins-CcwEXXMS.d.cts → plugins-DZljh9NJ.d.cts} +135 -3
- package/dist/{plugins-CcwEXXMS.d.ts → plugins-DZljh9NJ.d.ts} +135 -3
- package/dist/testing.cjs +3 -3
- package/dist/testing.cjs.map +1 -1
- package/dist/testing.d.cts +1 -1
- package/dist/testing.d.ts +1 -1
- package/dist/testing.js +3 -3
- package/dist/testing.js.map +1 -1
- package/dist/worker.cjs +3 -3
- package/dist/worker.cjs.map +1 -1
- package/dist/worker.d.cts +1 -1
- package/dist/worker.d.ts +1 -1
- package/dist/worker.js +3 -3
- package/dist/worker.js.map +1 -1
- package/package.json +1 -1
|
@@ -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:
|
|
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)
|
|
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
|
|
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:
|
|
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)
|
|
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
|
|
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 };
|