@directive-run/core 0.4.2 → 0.7.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/dist/index.d.cts CHANGED
@@ -1,7 +1,6 @@
1
- import { S as Schema, F as Facts, R as Requirement, a as RequirementOutput, b as RetryPolicy, B as BatchConfig, c as ResolverContext, d as SchemaType, e as FactsStore, M as ModuleSchema, T as TypedDerivationsDef, f as TypedEventsDef, E as EffectsDef, g as TypedConstraintsDef, h as TypedResolversDef, i as ModuleHooks, C as CrossModuleDeps, j as CrossModuleDerivationsDef, k as CrossModuleEffectsDef, l as CrossModuleConstraintsDef, m as ModuleDef, n as CreateSystemOptionsSingle, o as SingleModuleSystem, p as ModulesMap, q as CreateSystemOptionsNamed, N as NamespacedSystem, D as DerivationsSchema, r as TypedConstraintDef, s as RequirementOutput$1, I as InferRequirements, P as Plugin, t as DebugConfig, u as ErrorBoundaryConfig, v as InferFacts, w as ExtractSchema, x as RequirementWithId, y as RequirementKeyFn, z as ConstraintsDef, A as ConstraintState, G as ResolversDef, H as ResolverStatus, J as System, K as FactChange, L as FactsSnapshot, O as ReconcileResult, Q as Snapshot, U as DirectiveError, V as RecoveryStrategy, W as RunChangelogEntry, X as ErrorSource, Y as RetryLaterConfig, Z as TimeTravelAPI, _ as SystemConfig } from './plugins-cDWoL7A7.cjs';
2
- export { $ as AnySystem, a0 as BatchItemResult, a1 as BatchResolveResults, a2 as CrossModuleConstraintDef, a3 as CrossModuleDerivationFn, a4 as CrossModuleEffectDef, a5 as CrossModuleFactsWithSelf, a6 as DerivationKeys, a7 as DerivationReturnType, a8 as DeriveAccessor, a9 as DispatchEventsFromSchema, aa as DistributableSnapshot, ab as DistributableSnapshotOptions, ac as EffectCleanup, ad as EventPayloadSchema, ae as EventsAccessor, af as EventsAccessorFromSchema, ag as EventsDef, ah as EventsSchema, ai as FactKeys, aj as FactReturnType, ak as FlexibleEventHandler, al as InferDerivations, am as InferEventPayloadFromSchema, an as InferEvents, ao as InferRequirementPayloadFromSchema, ap as InferRequirementTypes, aq as InferSchema, ar as InferSchemaType, as as InferSelectorState, at as MutableNamespacedFacts, au as NamespacedDerivations, av as NamespacedEventsAccessor, aw as NamespacedFacts, ax as ObservableKeys, ay as RequirementExplanation, az as RequirementPayloadSchema, aA as RequirementsSchema, aB as SnapshotMeta, aC as SystemEvent, aD as SystemInspection, aE as SystemMode, aF as SystemSnapshot, aG as TimeTravelState, aH as TypedResolverContext, aI as TypedResolverDef, aJ as UnionEvents, aK as isNamespacedSystem, aL as isSingleModuleSystem } from './plugins-cDWoL7A7.cjs';
1
+ import { S as Schema, F as Facts, R as Requirement, a as RequirementOutput, b as RetryPolicy, B as BatchConfig, c as ResolverContext, d as SchemaType, M as ModuleSchema, T as TypedDerivationsDef, e as TypedEventsDef, E as EffectsDef, f as TypedConstraintsDef, g as TypedResolversDef, h as ModuleHooks, C as CrossModuleDeps, i as CrossModuleDerivationsDef, j as CrossModuleEffectsDef, k as CrossModuleConstraintsDef, l as ModuleDef, m as CreateSystemOptionsSingle, n as SingleModuleSystem, o as ModulesMap, p as CreateSystemOptionsNamed, N as NamespacedSystem, P as Plugin, q as TraceOption, r as ErrorBoundaryConfig, s as RequirementWithId, t as RequirementKeyFn, u as FactsStore, v as ConstraintsDef, w as ConstraintState, x as ResolversDef, y as ResolverStatus, z as System, A as FactChange, D as FactsSnapshot, G as ReconcileResult, H as Snapshot, I as DirectiveError, J as RecoveryStrategy, K as TraceEntry, L as ErrorSource, O as RetryLaterConfig, Q as HistoryAPI, U as HistoryOption, V as SystemConfig } from './plugins-DaglUQVX.cjs';
2
+ export { W as AnySystem, X as BatchItemResult, Y as BatchResolveResults, Z as ConstraintsControl, _ as CrossModuleConstraintDef, $ as CrossModuleDerivationFn, a0 as CrossModuleEffectDef, a1 as CrossModuleFactsWithSelf, a2 as DerivationKeys, a3 as DerivationReturnType, a4 as DerivationsControl, a5 as DerivationsSchema, a6 as DeriveAccessor, a7 as DispatchEventsFromSchema, a8 as DistributableSnapshot, a9 as DistributableSnapshotOptions, aa as DynamicConstraintDef, ab as DynamicEffectDef, ac as DynamicResolverDef, ad as EffectCleanup, ae as EffectsControl, af as EventPayloadSchema, ag as EventsAccessor, ah as EventsAccessorFromSchema, ai as EventsDef, aj as EventsSchema, ak as FactKeys, al as FactReturnType, am as FlexibleEventHandler, an as HistoryConfig, ao as HistoryState, ap as InferDerivations, aq as InferEventPayloadFromSchema, ar as InferEvents, as as InferFacts, at as InferRequirementPayloadFromSchema, au as InferRequirementTypes, av as InferRequirements, aw as InferSchema, ax as InferSchemaType, ay as InferSelectorState, az as MutableNamespacedFacts, aA as NamespacedDerivations, aB as NamespacedEventsAccessor, aC as NamespacedFacts, aD as ObservableKeys, aE as RequirementExplanation, aF as RequirementOutput, aG as RequirementPayloadSchema, aH as RequirementsSchema, aI as ResolversControl, aJ as SnapshotMeta, aK as SystemEvent, aL as SystemInspection, aM as SystemMode, aN as SystemSnapshot, aO as TraceConfig, aP as TypedConstraintDef, aQ as TypedResolverContext, aR as TypedResolverDef, aS as UnionEvents, aT as isNamespacedSystem, aU as isSingleModuleSystem } from './plugins-DaglUQVX.cjs';
3
3
  export { D as DistributableSnapshotLike, S as SignedSnapshot, a as SnapshotDiff, b as SnapshotDiffEntry, d as diffSnapshots, i as isSignedSnapshot, c as isSnapshotExpired, s as shallowEqual, e as signSnapshot, v as validateSnapshot, f as verifySnapshotSignature } from './utils-4JrY5fk9.cjs';
4
- export { DirectiveModuleStructure, ReduxSliceConfig, XStateMachineConfig, ZustandStoreConfig, analyzeReduxSlice, analyzeXStateMachine, analyzeZustandStore, generateMigrationChecklist, generateModuleCode } from './migration.cjs';
5
4
 
6
5
  /**
7
6
  * Derivation Types - Type definitions for derivations
@@ -15,7 +14,7 @@ interface TrackingContext {
15
14
  }
16
15
  /** Derivation definition function signature. */
17
16
  interface DerivationDef<S extends Schema, T, D extends DerivationsDef<S>> {
18
- (facts: Facts<S>, derive: DerivedValues<S, D>): T;
17
+ (facts: Facts<S>, derived: DerivedValues<S, D>): T;
19
18
  }
20
19
  /** Map of derivation definitions. */
21
20
  type DerivationsDef<S extends Schema> = Record<string, DerivationDef<S, unknown, DerivationsDef<S>>>;
@@ -143,7 +142,7 @@ interface TypedResolver<S extends Schema, R extends Requirement = Requirement> {
143
142
  * @example
144
143
  * ```typescript
145
144
  * const schema = { count: t.number(), threshold: t.number() };
146
- * const factory = constraintFactory<typeof schema>();
145
+ * const factory = createConstraintFactory<typeof schema>();
147
146
  *
148
147
  * const maxCountConstraint = factory.create({
149
148
  * when: (facts) => facts.count > facts.threshold,
@@ -151,7 +150,7 @@ interface TypedResolver<S extends Schema, R extends Requirement = Requirement> {
151
150
  * });
152
151
  * ```
153
152
  */
154
- declare function constraintFactory<S extends Schema>(): {
153
+ declare function createConstraintFactory<S extends Schema>(): {
155
154
  /**
156
155
  * Create a typed constraint
157
156
  */
@@ -164,7 +163,7 @@ declare function constraintFactory<S extends Schema>(): {
164
163
  * @example
165
164
  * ```typescript
166
165
  * const schema = { user: t.object<User>() };
167
- * const factory = resolverFactory<typeof schema>();
166
+ * const factory = createResolverFactory<typeof schema>();
168
167
  *
169
168
  * const fetchUserResolver = factory.create<FetchUserReq>({
170
169
  * requirement: (req): req is FetchUserReq => req.type === "FETCH_USER",
@@ -174,7 +173,7 @@ declare function constraintFactory<S extends Schema>(): {
174
173
  * });
175
174
  * ```
176
175
  */
177
- declare function resolverFactory<S extends Schema>(): {
176
+ declare function createResolverFactory<S extends Schema>(): {
178
177
  /**
179
178
  * Create a typed resolver
180
179
  */
@@ -182,7 +181,7 @@ declare function resolverFactory<S extends Schema>(): {
182
181
  };
183
182
  /**
184
183
  * Type-safe constraint creator.
185
- * Simpler alternative to constraintFactory when you don't need a factory pattern.
184
+ * Simpler alternative to createConstraintFactory when you don't need a factory pattern.
186
185
  *
187
186
  * @example
188
187
  * ```typescript
@@ -195,7 +194,7 @@ declare function resolverFactory<S extends Schema>(): {
195
194
  declare function typedConstraint<S extends Schema, R extends Requirement = Requirement>(constraint: TypedConstraint<S, R>): TypedConstraint<S, R>;
196
195
  /**
197
196
  * Type-safe resolver creator.
198
- * Simpler alternative to resolverFactory when you don't need a factory pattern.
197
+ * Simpler alternative to createResolverFactory when you don't need a factory pattern.
199
198
  *
200
199
  * @example
201
200
  * ```typescript
@@ -210,14 +209,12 @@ declare function typedConstraint<S extends Schema, R extends Requirement = Requi
210
209
  declare function typedResolver<S extends Schema, R extends Requirement = Requirement>(resolver: TypedResolver<S, R>): TypedResolver<S, R>;
211
210
 
212
211
  /**
213
- * Facts Store - Proxy-based reactive state with auto-tracking
212
+ * Schema Type Builders
214
213
  *
215
- * Features:
216
- * - Proxy-based access (facts.phase instead of facts.get("phase"))
217
- * - Automatic dependency tracking via tracking context
218
- * - Batched updates with coalesced notifications
219
- * - Granular subscriptions by key
220
- * - Schema validation in development mode
214
+ * Provides type-safe schema definitions with optional runtime validation.
215
+ * Used to define fact types, derivation types, event payload types, etc.
216
+ *
217
+ * This module has no dependency on the facts store or tracking system.
221
218
  */
222
219
 
223
220
  /** Brand symbol for branded types */
@@ -497,108 +494,6 @@ declare const t: {
497
494
  */
498
495
  bigint(): ChainableSchemaType<bigint>;
499
496
  };
500
- /** Options for creating a facts store */
501
- interface CreateFactsStoreOptions<S extends Schema> {
502
- schema: S;
503
- /** Validate values against schema (default: process.env.NODE_ENV !== 'production') */
504
- validate?: boolean;
505
- /** Throw on unknown schema keys (default: true in dev mode) */
506
- strictKeys?: boolean;
507
- /** Redact sensitive values in error messages */
508
- redactErrors?: boolean;
509
- /** Callback when facts change (for plugin hooks) */
510
- onChange?: (key: string, value: unknown, prev: unknown) => void;
511
- /** Callback for batch changes */
512
- onBatch?: (changes: Array<{
513
- key: string;
514
- value: unknown;
515
- prev: unknown;
516
- type: "set" | "delete";
517
- }>) => void;
518
- }
519
- /**
520
- * Create a reactive facts store backed by a Map with schema validation,
521
- * batched mutations, and granular key-level subscriptions.
522
- *
523
- * @remarks
524
- * The store is the low-level primitive that powers the `facts` proxy.
525
- * Most users should use {@link createFacts} or `createModule` instead.
526
- *
527
- * @param options - Store configuration including schema, validation settings, and change callbacks
528
- * @returns A {@link FactsStore} with get/set/batch/subscribe methods and automatic schema validation
529
- *
530
- * @example
531
- * ```ts
532
- * const store = createFactsStore({
533
- * schema: { count: t.number(), name: t.string() },
534
- * });
535
- *
536
- * store.set("count", 1);
537
- * store.get("count"); // 1
538
- *
539
- * store.batch(() => {
540
- * store.set("count", 2);
541
- * store.set("name", "hello");
542
- * }); // listeners fire once after batch completes
543
- * ```
544
- *
545
- * @internal
546
- */
547
- declare function createFactsStore<S extends Schema>(options: CreateFactsStoreOptions<S>): FactsStore<S>;
548
- /**
549
- * Create a Proxy wrapper around a {@link FactsStore} for clean property-style
550
- * access (`facts.phase`) with automatic dependency tracking.
551
- *
552
- * @remarks
553
- * Reading a property calls `store.get()` (which tracks the access for
554
- * auto-tracked derivations). Writing a property calls `store.set()` (which
555
- * validates against the schema). The proxy also exposes `$store` for direct
556
- * store access and `$snapshot()` for untracked reads.
557
- *
558
- * @param store - The underlying facts store to wrap
559
- * @param schema - The schema definition used for `ownKeys` enumeration
560
- * @returns A {@link Facts} proxy with property-style get/set and prototype pollution guards
561
- *
562
- * @example
563
- * ```ts
564
- * const store = createFactsStore({ schema: { phase: t.string() } });
565
- * const facts = createFactsProxy(store, { phase: t.string() });
566
- *
567
- * facts.phase = "red";
568
- * console.log(facts.phase); // "red"
569
- * ```
570
- *
571
- * @internal
572
- */
573
- declare function createFactsProxy<S extends Schema>(store: FactsStore<S>, schema: S): Facts<S>;
574
- /**
575
- * Convenience factory that creates both a {@link FactsStore} and its
576
- * {@link createFactsProxy | proxy wrapper} in a single call.
577
- *
578
- * @remarks
579
- * This is the recommended entry point when you need low-level store access
580
- * outside of `createModule` / `createSystem`.
581
- *
582
- * @param options - Same options as {@link createFactsStore}
583
- * @returns An object with `store` (the reactive Map-backed store) and `facts` (the Proxy accessor)
584
- *
585
- * @example
586
- * ```ts
587
- * const { store, facts } = createFacts({
588
- * schema: { phase: t.string<"red" | "green">() },
589
- * });
590
- *
591
- * facts.phase = "red";
592
- * console.log(facts.phase); // "red"
593
- * store.subscribe(["phase"], () => console.log("phase changed"));
594
- * ```
595
- *
596
- * @internal
597
- */
598
- declare function createFacts<S extends Schema>(options: CreateFactsStoreOptions<S>): {
599
- store: FactsStore<S>;
600
- facts: Facts<S>;
601
- };
602
497
 
603
498
  /**
604
499
  * Module - The declarative API for defining Directive modules
@@ -620,8 +515,11 @@ interface ModuleConfig<M extends ModuleSchema> {
620
515
  constraints?: TypedConstraintsDef<M>;
621
516
  resolvers?: TypedResolversDef<M>;
622
517
  hooks?: ModuleHooks<M>;
623
- /** Events that create time-travel snapshots for undo/redo. Omit to snapshot all events. */
624
- snapshotEvents?: Array<keyof (M["events"] extends Record<string, unknown> ? M["events"] : Record<string, never>) & string>;
518
+ /** History configuration — controls which events create snapshots for undo/redo. */
519
+ history?: {
520
+ /** Events that create history snapshots. Omit to snapshot all events. */
521
+ snapshotEvents?: Array<keyof (M["events"] extends Record<string, unknown> ? M["events"] : Record<string, never>) & string>;
522
+ };
625
523
  }
626
524
  /**
627
525
  * Module configuration with cross-module dependencies for type-safe access
@@ -691,14 +589,17 @@ interface ModuleConfigWithDeps<M extends ModuleSchema, Deps extends CrossModuleD
691
589
  /** Resolvers. Uses flat access (`ctx.facts.myFact`) to keep async mutations scoped to own module. */
692
590
  resolvers?: TypedResolversDef<M>;
693
591
  hooks?: ModuleHooks<M>;
694
- /** Events that create time-travel snapshots for undo/redo. Omit to snapshot all events. */
695
- snapshotEvents?: Array<keyof (M["events"] extends Record<string, unknown> ? M["events"] : Record<string, never>) & string>;
592
+ /** History configuration — controls which events create snapshots for undo/redo. */
593
+ history?: {
594
+ /** Events that create history snapshots. Omit to snapshot all events. */
595
+ snapshotEvents?: Array<keyof (M["events"] extends Record<string, unknown> ? M["events"] : Record<string, never>) & string>;
596
+ };
696
597
  }
697
598
  /**
698
599
  * Create a module definition with full type inference.
699
600
  *
700
601
  * The consolidated schema provides:
701
- * - Derivation composition (`derive.otherDerivation` is typed)
602
+ * - Derivation composition (`derived.otherDerivation` is typed)
702
603
  * - Event dispatch (`system.dispatch({ type: "..." })` has autocomplete)
703
604
  * - Resolver requirements (`req.payload` is typed based on requirement type)
704
605
  *
@@ -732,9 +633,9 @@ interface ModuleConfigWithDeps<M extends ModuleSchema, Deps extends CrossModuleD
732
633
  * },
733
634
  * derive: {
734
635
  * isRed: (facts) => facts.phase === "red",
735
- * timeRemaining: (facts, derive) => {
736
- * // derive.isRed is typed as boolean!
737
- * return derive.isRed ? 30 - facts.elapsed : 0;
636
+ * timeRemaining: (facts, derived) => {
637
+ * // derived.isRed is typed as boolean!
638
+ * return derived.isRed ? 30 - facts.elapsed : 0;
738
639
  * },
739
640
  * },
740
641
  * events: {
@@ -872,431 +773,6 @@ declare function createModuleFactory<const M extends ModuleSchema, const Deps ex
872
773
  declare function createSystem<S extends ModuleSchema>(options: CreateSystemOptionsSingle<S>): SingleModuleSystem<S>;
873
774
  declare function createSystem<const Modules extends ModulesMap>(options: CreateSystemOptionsNamed<Modules>): NamespacedSystem<Modules>;
874
775
 
875
- /**
876
- * Builder Pattern API for Directive Modules
877
- *
878
- * An alternative, fluent API for creating modules that provides
879
- * a more declarative style for module definition.
880
- *
881
- * @example
882
- * ```typescript
883
- * import { module, t } from '@directive-run/core';
884
- *
885
- * const counter = module("counter")
886
- * .schema({
887
- * facts: { count: t.number(), lastAction: t.string() },
888
- * derivations: { doubled: t.number(), isPositive: t.boolean() },
889
- * events: { increment: {}, decrement: {} },
890
- * requirements: {},
891
- * })
892
- * .init((facts) => {
893
- * facts.count = 0;
894
- * facts.lastAction = "";
895
- * })
896
- * .derive({
897
- * doubled: (facts) => facts.count * 2,
898
- * isPositive: (facts) => facts.count > 0,
899
- * })
900
- * .events({
901
- * increment: (facts) => {
902
- * facts.count += 1;
903
- * facts.lastAction = "increment";
904
- * },
905
- * decrement: (facts) => {
906
- * facts.count -= 1;
907
- * facts.lastAction = "decrement";
908
- * },
909
- * })
910
- * .build();
911
- * ```
912
- */
913
-
914
- /**
915
- * Fluent builder interface for constructing {@link ModuleDef} instances step by step.
916
- *
917
- * Chain methods like `.schema()`, `.init()`, `.derive()`, `.events()`, and others
918
- * to configure the module, then call `.build()` to produce the final definition.
919
- * The builder validates that all schema-declared derivations and events have
920
- * corresponding implementations before returning.
921
- *
922
- * @typeParam M - The module schema type, narrowed after calling `.schema()`.
923
- * @public
924
- */
925
- interface ModuleBuilder<M extends ModuleSchema = ModuleSchema> {
926
- /**
927
- * Define the schema for this module (facts, derivations, events, requirements).
928
- */
929
- schema<NewM extends ModuleSchema>(schema: NewM): ModuleBuilder<NewM>;
930
- /**
931
- * Define the initialization function for this module.
932
- */
933
- init(initFn: (facts: Facts<M["facts"]>) => void): ModuleBuilder<M>;
934
- /**
935
- * Define derivation implementations for this module.
936
- * Keys must match those declared in schema.derivations.
937
- */
938
- derive<D extends Record<string, (facts: Facts<M["facts"]>, derive: DeriveAccessor<M>) => unknown>>(derivations: D): ModuleBuilder<M>;
939
- /**
940
- * Define event handler implementations for this module.
941
- * Keys must match those declared in schema.events.
942
- */
943
- events<E extends Record<string, (facts: Facts<M["facts"]>, payload: unknown) => void>>(events: E): ModuleBuilder<M>;
944
- /**
945
- * Define effects (side effects) for this module.
946
- */
947
- effects(effects: EffectsDef<M["facts"]>): ModuleBuilder<M>;
948
- /**
949
- * Define constraints for this module.
950
- */
951
- constraints<C extends Record<string, ConstraintDef<M>>>(constraints: C): ModuleBuilder<M>;
952
- /**
953
- * Define resolvers for this module.
954
- */
955
- resolvers<R extends Record<string, ResolverDef<M>>>(resolvers: R): ModuleBuilder<M>;
956
- /**
957
- * Define lifecycle hooks for this module.
958
- */
959
- hooks(hooks: ModuleHooks<M>): ModuleBuilder<M>;
960
- /**
961
- * Build the module definition.
962
- */
963
- build(): ModuleDef<M>;
964
- }
965
- /**
966
- * Accessor for reading other derivations within a derivation function.
967
- */
968
- type DeriveAccessor<M extends ModuleSchema> = M["derivations"] extends DerivationsSchema ? {
969
- readonly [K in keyof M["derivations"]]: InferSchemaType<M["derivations"][K]>;
970
- } : Record<string, never>;
971
- /**
972
- * Infer the TypeScript type from a schema type definition.
973
- */
974
- type InferSchemaType<T> = T extends {
975
- _type: infer U;
976
- } ? U : any;
977
- /**
978
- * Constraint definition for the builder.
979
- */
980
- interface ConstraintDef<M extends ModuleSchema> {
981
- when: (facts: Facts<M["facts"]>) => boolean;
982
- require: {
983
- type: string;
984
- [key: string]: unknown;
985
- } | ((facts: Facts<M["facts"]>) => {
986
- type: string;
987
- [key: string]: unknown;
988
- } | null);
989
- priority?: number;
990
- }
991
- /**
992
- * Resolver definition for the builder.
993
- */
994
- interface ResolverDef<M extends ModuleSchema> {
995
- requirement: string | ((req: {
996
- type: string;
997
- [key: string]: unknown;
998
- }) => boolean);
999
- resolve: (req: {
1000
- type: string;
1001
- [key: string]: unknown;
1002
- }, ctx: {
1003
- facts: Facts<M["facts"]>;
1004
- signal?: AbortSignal;
1005
- }) => void | Promise<void>;
1006
- retry?: {
1007
- attempts?: number;
1008
- backoff?: "linear" | "exponential";
1009
- delay?: number;
1010
- };
1011
- timeout?: number;
1012
- key?: (req: {
1013
- type: string;
1014
- [key: string]: unknown;
1015
- }) => string;
1016
- }
1017
- /**
1018
- * Create a new module using the fluent builder pattern.
1019
- *
1020
- * Returns a {@link ModuleBuilder} that lets you declaratively define a module's
1021
- * schema, initialization, derivations, events, effects, constraints, resolvers,
1022
- * and lifecycle hooks via method chaining. Call `.build()` at the end to produce
1023
- * the final {@link ModuleDef}.
1024
- *
1025
- * @remarks
1026
- * The builder validates at build time that every derivation and event declared
1027
- * in the schema has a corresponding implementation. Missing implementations
1028
- * cause a descriptive error.
1029
- *
1030
- * @param id - Unique identifier for this module, used for namespacing in multi-module systems.
1031
- * @returns A {@link ModuleBuilder} ready for configuration via method chaining.
1032
- *
1033
- * @example
1034
- * ```typescript
1035
- * import { module, t } from '@directive-run/core';
1036
- *
1037
- * const counter = module("counter")
1038
- * .schema({
1039
- * facts: { count: t.number() },
1040
- * derivations: { doubled: t.number() },
1041
- * events: { increment: {} },
1042
- * requirements: {},
1043
- * })
1044
- * .init((facts) => {
1045
- * facts.count = 0;
1046
- * })
1047
- * .derive({
1048
- * doubled: (facts) => facts.count * 2,
1049
- * })
1050
- * .events({
1051
- * increment: (facts) => {
1052
- * facts.count += 1;
1053
- * },
1054
- * })
1055
- * .build();
1056
- * ```
1057
- *
1058
- * @public
1059
- */
1060
- declare function module$1(id: string): ModuleBuilder<ModuleSchema>;
1061
-
1062
- /**
1063
- * Constraint Builder API
1064
- *
1065
- * Fluent builders for creating typed constraint definitions.
1066
- *
1067
- * @example Full builder
1068
- * ```typescript
1069
- * import { constraint } from '@directive-run/core';
1070
- *
1071
- * const escalate = constraint<typeof schema>()
1072
- * .when(f => f.confidence < 0.7)
1073
- * .require({ type: 'ESCALATE' })
1074
- * .priority(50)
1075
- * .build();
1076
- * ```
1077
- *
1078
- * @example Quick shorthand
1079
- * ```typescript
1080
- * import { when } from '@directive-run/core';
1081
- *
1082
- * const pause = when<typeof schema>(f => f.errors > 3)
1083
- * .require({ type: 'PAUSE' });
1084
- * ```
1085
- */
1086
-
1087
- type WhenFn<M extends ModuleSchema> = (facts: Facts<M["facts"]>) => boolean | Promise<boolean>;
1088
- type RequireValue<M extends ModuleSchema> = RequirementOutput$1<InferRequirements<M>> | ((facts: Facts<M["facts"]>) => RequirementOutput$1<InferRequirements<M>>);
1089
- /** Builder after constraint() — must call .when() first */
1090
- interface ConstraintBuilderStart<M extends ModuleSchema> {
1091
- when(condition: WhenFn<M>): ConstraintBuilderWithWhen<M>;
1092
- }
1093
- /** Builder after .when() — must call .require() next */
1094
- interface ConstraintBuilderWithWhen<M extends ModuleSchema> {
1095
- require(req: RequireValue<M>): ConstraintBuilderComplete<M>;
1096
- }
1097
- /** Builder after .require() — optional chaining + .build() */
1098
- interface ConstraintBuilderComplete<M extends ModuleSchema> {
1099
- priority(n: number): ConstraintBuilderComplete<M>;
1100
- after(...ids: string[]): ConstraintBuilderComplete<M>;
1101
- deps(...keys: string[]): ConstraintBuilderComplete<M>;
1102
- timeout(ms: number): ConstraintBuilderComplete<M>;
1103
- async(value: boolean): ConstraintBuilderComplete<M>;
1104
- build(): TypedConstraintDef<M>;
1105
- }
1106
- /** Result from when().require() — a valid constraint with optional immutable chaining */
1107
- type WhenConstraint<M extends ModuleSchema> = TypedConstraintDef<M> & {
1108
- withPriority(n: number): WhenConstraint<M>;
1109
- withAfter(...ids: string[]): WhenConstraint<M>;
1110
- withDeps(...keys: string[]): WhenConstraint<M>;
1111
- withTimeout(ms: number): WhenConstraint<M>;
1112
- withAsync(value: boolean): WhenConstraint<M>;
1113
- };
1114
- /** Result from when() — must call .require() */
1115
- interface WhenBuilder<M extends ModuleSchema> {
1116
- require(req: RequireValue<M>): WhenConstraint<M>;
1117
- }
1118
- /**
1119
- * Create a constraint using the full builder pattern.
1120
- * Requires `.when()`, `.require()`, and `.build()`.
1121
- *
1122
- * @example
1123
- * ```typescript
1124
- * const c = constraint<typeof schema>()
1125
- * .when(f => f.phase === "red")
1126
- * .require({ type: "TRANSITION", to: "green" })
1127
- * .priority(50)
1128
- * .after("healthCheck")
1129
- * .build();
1130
- * ```
1131
- */
1132
- declare function constraint<M extends ModuleSchema>(): ConstraintBuilderStart<M>;
1133
- /**
1134
- * Quick shorthand for creating constraints.
1135
- * Returns a valid constraint directly (no `.build()` needed).
1136
- *
1137
- * @example
1138
- * ```typescript
1139
- * const pause = when<typeof schema>(f => f.errors > 3)
1140
- * .require({ type: 'PAUSE' });
1141
- *
1142
- * // With optional chaining (immutable — returns new constraint)
1143
- * const halt = when<typeof schema>(f => f.errors > 10)
1144
- * .require({ type: 'HALT' })
1145
- * .withPriority(100)
1146
- * .withAfter('healthCheck');
1147
- * ```
1148
- */
1149
- declare function when<M extends ModuleSchema>(condition: WhenFn<M>): WhenBuilder<M>;
1150
-
1151
- /**
1152
- * System Builder API
1153
- *
1154
- * Fluent builder for creating Directive systems.
1155
- *
1156
- * @example Single module
1157
- * ```typescript
1158
- * import { system } from '@directive-run/core';
1159
- *
1160
- * const sys = system()
1161
- * .module(counterModule)
1162
- * .plugins([loggingPlugin()])
1163
- * .debug({ timeTravel: true })
1164
- * .build();
1165
- * ```
1166
- *
1167
- * @example Multiple modules
1168
- * ```typescript
1169
- * const sys = system()
1170
- * .modules({ auth: authModule, cart: cartModule })
1171
- * .plugins([loggingPlugin()])
1172
- * .build();
1173
- * ```
1174
- */
1175
-
1176
- /**
1177
- * Entry point of the system builder, returned by {@link system}.
1178
- *
1179
- * Choose `.module()` for a single-module {@link SingleModuleSystem} with direct
1180
- * fact/derivation access, or `.modules()` for a namespaced {@link NamespacedSystem}
1181
- * that composes multiple modules.
1182
- *
1183
- * @public
1184
- */
1185
- interface SystemBuilderStart {
1186
- /**
1187
- * Configure the system with a single module definition.
1188
- *
1189
- * @param mod - The module definition to use as the system's sole module.
1190
- * @returns A {@link SingleModuleSystemBuilder} for further configuration.
1191
- */
1192
- module<S extends ModuleSchema>(mod: ModuleDef<S>): SingleModuleSystemBuilder<S>;
1193
- /**
1194
- * Configure the system with multiple named modules.
1195
- *
1196
- * @param mods - A map of namespace keys to module definitions.
1197
- * @returns A {@link NamespacedSystemBuilder} for further configuration.
1198
- */
1199
- modules<const Modules extends ModulesMap>(mods: Modules): NamespacedSystemBuilder<Modules>;
1200
- }
1201
- /**
1202
- * Builder for a single-module system with direct access to facts, derivations, and events.
1203
- *
1204
- * @remarks
1205
- * Use this builder when your system contains exactly one module. The resulting
1206
- * {@link SingleModuleSystem} exposes facts, derivations, and dispatch without
1207
- * namespace prefixes.
1208
- *
1209
- * @typeParam S - The module schema type.
1210
- * @public
1211
- */
1212
- interface SingleModuleSystemBuilder<S extends ModuleSchema> {
1213
- /** Register plugins that hook into system lifecycle events. */
1214
- plugins(plugins: Array<Plugin<ModuleSchema>>): SingleModuleSystemBuilder<S>;
1215
- /** Enable debug features such as time-travel debugging and snapshot limits. */
1216
- debug(config: DebugConfig): SingleModuleSystemBuilder<S>;
1217
- /** Configure error boundary behavior including recovery strategies. */
1218
- errorBoundary(config: ErrorBoundaryConfig): SingleModuleSystemBuilder<S>;
1219
- /** Set the reconciliation tick interval in milliseconds. */
1220
- tickMs(ms: number): SingleModuleSystemBuilder<S>;
1221
- /** Enable zero-config mode which auto-generates constraints from schema metadata. */
1222
- zeroConfig(enabled?: boolean): SingleModuleSystemBuilder<S>;
1223
- /** Provide initial fact values to hydrate the system on startup. */
1224
- initialFacts(facts: Partial<InferFacts<S>>): SingleModuleSystemBuilder<S>;
1225
- /** Finalize configuration and create the running {@link SingleModuleSystem}. */
1226
- build(): SingleModuleSystem<S>;
1227
- }
1228
- /**
1229
- * Builder for a namespaced multi-module system.
1230
- *
1231
- * @remarks
1232
- * Use this builder when composing multiple modules. The resulting
1233
- * {@link NamespacedSystem} prefixes facts and derivations with the module
1234
- * namespace key (e.g., `system.facts.auth.token`).
1235
- *
1236
- * @typeParam Modules - The modules map type mapping namespace keys to module definitions.
1237
- * @public
1238
- */
1239
- interface NamespacedSystemBuilder<Modules extends ModulesMap> {
1240
- /** Register plugins that hook into system lifecycle events. */
1241
- plugins(plugins: Array<Plugin<ModuleSchema>>): NamespacedSystemBuilder<Modules>;
1242
- /** Enable debug features such as time-travel debugging and snapshot limits. */
1243
- debug(config: DebugConfig): NamespacedSystemBuilder<Modules>;
1244
- /** Configure error boundary behavior including recovery strategies. */
1245
- errorBoundary(config: ErrorBoundaryConfig): NamespacedSystemBuilder<Modules>;
1246
- /** Set the reconciliation tick interval in milliseconds. */
1247
- tickMs(ms: number): NamespacedSystemBuilder<Modules>;
1248
- /** Enable zero-config mode which auto-generates constraints from schema metadata. */
1249
- zeroConfig(enabled?: boolean): NamespacedSystemBuilder<Modules>;
1250
- /** Provide initial fact values keyed by module namespace for hydration on startup. */
1251
- initialFacts(facts: Partial<{
1252
- [K in keyof Modules]: Partial<InferFacts<ExtractSchema<Modules[K]>>>;
1253
- }>): NamespacedSystemBuilder<Modules>;
1254
- /** Control the order in which modules are initialized: automatic, declaration order, or explicit. */
1255
- initOrder(order: "auto" | "declaration" | Array<keyof Modules & string>): NamespacedSystemBuilder<Modules>;
1256
- /** Finalize configuration and create the running {@link NamespacedSystem}. */
1257
- build(): NamespacedSystem<Modules>;
1258
- }
1259
- /**
1260
- * Create a Directive system using the fluent builder pattern.
1261
- *
1262
- * Returns a {@link SystemBuilderStart} that branches into either a
1263
- * single-module path (`.module()`) or a namespaced multi-module path
1264
- * (`.modules()`). Chain configuration methods like `.plugins()`, `.debug()`,
1265
- * and `.errorBoundary()`, then call `.build()` to produce the running system.
1266
- *
1267
- * @remarks
1268
- * This is a convenience wrapper around {@link createSystem}. Both produce
1269
- * identical systems; the builder simply offers a more discoverable,
1270
- * chainable API.
1271
- *
1272
- * @returns A {@link SystemBuilderStart} ready to receive a module or modules map.
1273
- *
1274
- * @example Single-module system
1275
- * ```typescript
1276
- * import { system } from '@directive-run/core';
1277
- *
1278
- * const sys = system()
1279
- * .module(counterModule)
1280
- * .plugins([loggingPlugin()])
1281
- * .debug({ timeTravel: true })
1282
- * .build();
1283
- * ```
1284
- *
1285
- * @example Multi-module namespaced system
1286
- * ```typescript
1287
- * import { system } from '@directive-run/core';
1288
- *
1289
- * const sys = system()
1290
- * .modules({ auth: authModule, cart: cartModule })
1291
- * .plugins([loggingPlugin()])
1292
- * .initOrder(["auth", "cart"])
1293
- * .build();
1294
- * ```
1295
- *
1296
- * @public
1297
- */
1298
- declare function system(): SystemBuilderStart;
1299
-
1300
776
  /**
1301
777
  * Requirement Status Utilities
1302
778
  *
@@ -1383,8 +859,8 @@ interface CreateSystemWithStatusOptions<M extends ModuleSchema> {
1383
859
  module: ModuleDef<M>;
1384
860
  /** Additional plugins to include alongside the status plugin */
1385
861
  plugins?: Plugin<any>[];
1386
- /** Debug configuration */
1387
- debug?: DebugConfig;
862
+ /** Trace: per-run reconciliation changelog */
863
+ trace?: TraceOption;
1388
864
  /** Error boundary configuration */
1389
865
  errorBoundary?: ErrorBoundaryConfig;
1390
866
  /** Tick interval in milliseconds */
@@ -1450,20 +926,6 @@ declare function createSystemWithStatus<M extends ModuleSchema>(options: CreateS
1450
926
  * - Requirement comparison and hashing
1451
927
  */
1452
928
 
1453
- /**
1454
- * Generate a stable identity string for a requirement.
1455
- *
1456
- * When no custom key function is provided, the ID is formed from the
1457
- * requirement's `type` plus a deterministic JSON serialization of its
1458
- * remaining properties. A custom {@link RequirementKeyFn} can override
1459
- * this to control deduplication granularity.
1460
- *
1461
- * @param req - The requirement to generate an ID for.
1462
- * @param keyFn - Optional custom key function that overrides the default identity logic.
1463
- * @returns A stable string that uniquely identifies this requirement for deduplication.
1464
- *
1465
- * @public
1466
- */
1467
929
  declare function generateRequirementId(req: Requirement, keyFn?: RequirementKeyFn): string;
1468
930
  /**
1469
931
  * Create a typed requirement factory for a given requirement type string.
@@ -1639,6 +1101,120 @@ declare class RequirementSet {
1639
1101
  };
1640
1102
  }
1641
1103
 
1104
+ /**
1105
+ * Facts Store - Proxy-based reactive state with auto-tracking
1106
+ *
1107
+ * Features:
1108
+ * - Proxy-based access (facts.phase instead of facts.get("phase"))
1109
+ * - Automatic dependency tracking via tracking context
1110
+ * - Batched updates with coalesced notifications
1111
+ * - Granular subscriptions by key
1112
+ * - Schema validation in development mode
1113
+ */
1114
+
1115
+ /** Options for creating a facts store */
1116
+ interface CreateFactsStoreOptions<S extends Schema> {
1117
+ schema: S;
1118
+ /** Validate values against schema (default: process.env.NODE_ENV !== 'production') */
1119
+ validate?: boolean;
1120
+ /** Throw on unknown schema keys (default: true in dev mode) */
1121
+ strictKeys?: boolean;
1122
+ /** Redact sensitive values in error messages */
1123
+ redactErrors?: boolean;
1124
+ /** Callback when facts change (for plugin hooks) */
1125
+ onChange?: (key: string, value: unknown, prev: unknown) => void;
1126
+ /** Callback for batch changes */
1127
+ onBatch?: (changes: Array<{
1128
+ key: string;
1129
+ value: unknown;
1130
+ prev: unknown;
1131
+ type: "set" | "delete";
1132
+ }>) => void;
1133
+ }
1134
+ /**
1135
+ * Create a reactive facts store backed by a Map with schema validation,
1136
+ * batched mutations, and granular key-level subscriptions.
1137
+ *
1138
+ * @remarks
1139
+ * The store is the low-level primitive that powers the `facts` proxy.
1140
+ * Most users should use {@link createFacts} or `createModule` instead.
1141
+ *
1142
+ * @param options - Store configuration including schema, validation settings, and change callbacks
1143
+ * @returns A {@link FactsStore} with get/set/batch/subscribe methods and automatic schema validation
1144
+ *
1145
+ * @example
1146
+ * ```ts
1147
+ * const store = createFactsStore({
1148
+ * schema: { count: t.number(), name: t.string() },
1149
+ * });
1150
+ *
1151
+ * store.set("count", 1);
1152
+ * store.get("count"); // 1
1153
+ *
1154
+ * store.batch(() => {
1155
+ * store.set("count", 2);
1156
+ * store.set("name", "hello");
1157
+ * }); // listeners fire once after batch completes
1158
+ * ```
1159
+ *
1160
+ * @internal
1161
+ */
1162
+ declare function createFactsStore<S extends Schema>(options: CreateFactsStoreOptions<S>): FactsStore<S>;
1163
+ /**
1164
+ * Create a Proxy wrapper around a {@link FactsStore} for clean property-style
1165
+ * access (`facts.phase`) with automatic dependency tracking.
1166
+ *
1167
+ * @remarks
1168
+ * Reading a property calls `store.get()` (which tracks the access for
1169
+ * auto-tracked derivations). Writing a property calls `store.set()` (which
1170
+ * validates against the schema). The proxy also exposes `$store` for direct
1171
+ * store access and `$snapshot()` for untracked reads.
1172
+ *
1173
+ * @param store - The underlying facts store to wrap
1174
+ * @param schema - The schema definition used for `ownKeys` enumeration
1175
+ * @returns A {@link Facts} proxy with property-style get/set and prototype pollution guards
1176
+ *
1177
+ * @example
1178
+ * ```ts
1179
+ * const store = createFactsStore({ schema: { phase: t.string() } });
1180
+ * const facts = createFactsProxy(store, { phase: t.string() });
1181
+ *
1182
+ * facts.phase = "red";
1183
+ * console.log(facts.phase); // "red"
1184
+ * ```
1185
+ *
1186
+ * @internal
1187
+ */
1188
+ declare function createFactsProxy<S extends Schema>(store: FactsStore<S>, schema: S): Facts<S>;
1189
+ /**
1190
+ * Convenience factory that creates both a {@link FactsStore} and its
1191
+ * {@link createFactsProxy | proxy wrapper} in a single call.
1192
+ *
1193
+ * @remarks
1194
+ * This is the recommended entry point when you need low-level store access
1195
+ * outside of `createModule` / `createSystem`.
1196
+ *
1197
+ * @param options - Same options as {@link createFactsStore}
1198
+ * @returns An object with `store` (the reactive Map-backed store) and `facts` (the Proxy accessor)
1199
+ *
1200
+ * @example
1201
+ * ```ts
1202
+ * const { store, facts } = createFacts({
1203
+ * schema: { phase: t.string<"red" | "green">() },
1204
+ * });
1205
+ *
1206
+ * facts.phase = "red";
1207
+ * console.log(facts.phase); // "red"
1208
+ * store.subscribe(["phase"], () => console.log("phase changed"));
1209
+ * ```
1210
+ *
1211
+ * @internal
1212
+ */
1213
+ declare function createFacts<S extends Schema>(options: CreateFactsStoreOptions<S>): {
1214
+ store: FactsStore<S>;
1215
+ facts: Facts<S>;
1216
+ };
1217
+
1642
1218
  /**
1643
1219
  * Derivations - Auto-tracked computed values with composition
1644
1220
  *
@@ -1669,6 +1245,12 @@ interface DerivationsManager<S extends Schema, D extends DerivationsDef<S>> {
1669
1245
  getDependencies(id: keyof D): Set<string>;
1670
1246
  /** Register new derivation definitions (for dynamic module registration) */
1671
1247
  registerDefinitions(newDefs: DerivationsDef<S>): void;
1248
+ /** Override an existing derivation function */
1249
+ assignDefinition(id: string, fn: DerivationsDef<S>[keyof DerivationsDef<S>]): void;
1250
+ /** Remove a derivation and clean up its state */
1251
+ unregisterDefinition(id: string): void;
1252
+ /** Compute a derivation immediately (ignores cache) */
1253
+ callOne(id: string): unknown;
1672
1254
  }
1673
1255
  /** Options for creating a derivations manager */
1674
1256
  interface CreateDerivationsOptions<S extends Schema, D extends DerivationsDef<S>> {
@@ -1792,6 +1374,26 @@ interface EffectsManager<_S extends Schema = Schema> {
1792
1374
  * @param newDefs - New effect definitions to merge into the manager.
1793
1375
  */
1794
1376
  registerDefinitions(newDefs: EffectsDef<Schema>): void;
1377
+ /**
1378
+ * Override an existing effect definition. Runs cleanup of the old effect first.
1379
+ *
1380
+ * @param id - The effect definition ID to override.
1381
+ * @param def - The new effect definition.
1382
+ * @throws If no effect with this ID exists.
1383
+ */
1384
+ assignDefinition(id: string, def: EffectsDef<Schema>[string]): void;
1385
+ /**
1386
+ * Remove an effect definition. Runs cleanup (try-catch) and removes from state.
1387
+ *
1388
+ * @param id - The effect definition ID to remove.
1389
+ */
1390
+ unregisterDefinition(id: string): void;
1391
+ /**
1392
+ * Execute an effect's `run()` function immediately.
1393
+ *
1394
+ * @param id - The effect definition ID.
1395
+ */
1396
+ callOne(id: string): Promise<void>;
1795
1397
  }
1796
1398
  /**
1797
1399
  * Configuration options accepted by {@link createEffectsManager}.
@@ -1963,6 +1565,30 @@ interface ConstraintsManager<_S extends Schema> {
1963
1565
  * @param newDefs - New constraint definitions to merge into the manager.
1964
1566
  */
1965
1567
  registerDefinitions(newDefs: ConstraintsDef<Schema>): void;
1568
+ /**
1569
+ * Override an existing constraint definition.
1570
+ * Stores the original in an internal map for inspection.
1571
+ *
1572
+ * @param id - The constraint definition ID to override.
1573
+ * @param def - The new constraint definition.
1574
+ * @throws If no constraint with this ID exists.
1575
+ */
1576
+ assignDefinition(id: string, def: ConstraintsDef<Schema>[string]): void;
1577
+ /**
1578
+ * Remove a constraint definition and all its internal state.
1579
+ *
1580
+ * @param id - The constraint definition ID to remove.
1581
+ */
1582
+ unregisterDefinition(id: string): void;
1583
+ /**
1584
+ * Evaluate a single constraint and emit its requirement if active.
1585
+ * Props are merged into the requirement object.
1586
+ *
1587
+ * @param id - The constraint definition ID.
1588
+ * @param props - Optional properties to merge into the requirement.
1589
+ * @returns The emitted requirements (if any).
1590
+ */
1591
+ callOne(id: string, props?: Record<string, unknown>): Promise<RequirementWithId[]>;
1966
1592
  }
1967
1593
  /**
1968
1594
  * Configuration options accepted by {@link createConstraintsManager}.
@@ -2124,6 +1750,31 @@ interface ResolversManager<_S extends Schema> {
2124
1750
  * @param newDefs - New resolver definitions to merge into the manager.
2125
1751
  */
2126
1752
  registerDefinitions(newDefs: ResolversDef<Schema>): void;
1753
+ /**
1754
+ * Override an existing resolver definition.
1755
+ *
1756
+ * @param id - The resolver definition ID to override.
1757
+ * @param def - The new resolver definition.
1758
+ * @throws If no resolver with this ID exists.
1759
+ */
1760
+ assignDefinition(id: string, def: ResolversDef<Schema>[string]): void;
1761
+ /**
1762
+ * Remove a resolver definition. Cancels any inflight resolution.
1763
+ *
1764
+ * @param id - The resolver definition ID to remove.
1765
+ */
1766
+ unregisterDefinition(id: string): void;
1767
+ /**
1768
+ * Execute a resolver with a given requirement object.
1769
+ *
1770
+ * @param id - The resolver definition ID.
1771
+ * @param requirement - The requirement to resolve.
1772
+ */
1773
+ callOne(id: string, requirement: Requirement): Promise<void>;
1774
+ /**
1775
+ * Clean up all internal state. Called on system destroy.
1776
+ */
1777
+ destroy(): void;
2127
1778
  }
2128
1779
  /**
2129
1780
  * Configuration options accepted by {@link createResolversManager}.
@@ -2230,9 +1881,9 @@ declare function createResolversManager<S extends Schema>(options: CreateResolve
2230
1881
  * - **Requirements:** `emitRequirementCreated`, `emitRequirementMet`, `emitRequirementCanceled`
2231
1882
  * - **Resolvers:** `emitResolverStart`, `emitResolverComplete`, `emitResolverError`, `emitResolverRetry`, `emitResolverCancel`
2232
1883
  * - **Effects:** `emitEffectRun`, `emitEffectError`
2233
- * - **Time-travel:** `emitSnapshot`, `emitTimeTravel`
1884
+ * - **History:** `emitSnapshot`, `emitHistoryNavigate`
2234
1885
  * - **Errors:** `emitError`, `emitErrorRecovery`
2235
- * - **Run history:** `emitRunComplete`
1886
+ * - **Trace:** `emitTraceComplete`
2236
1887
  *
2237
1888
  * @typeParam _S - The flat schema type (unused at runtime).
2238
1889
  *
@@ -2269,10 +1920,14 @@ interface PluginManager<_S extends Schema = any> {
2269
1920
  emitEffectRun(id: string): void;
2270
1921
  emitEffectError(id: string, error: unknown): void;
2271
1922
  emitSnapshot(snapshot: Snapshot): void;
2272
- emitTimeTravel(from: number, to: number): void;
1923
+ emitHistoryNavigate(from: number, to: number): void;
2273
1924
  emitError(error: DirectiveError): void;
2274
1925
  emitErrorRecovery(error: DirectiveError, strategy: RecoveryStrategy): void;
2275
- emitRunComplete(run: RunChangelogEntry): void;
1926
+ emitDefinitionRegister(type: string, id: string, def: unknown): void;
1927
+ emitDefinitionAssign(type: string, id: string, def: unknown, original: unknown): void;
1928
+ emitDefinitionUnregister(type: string, id: string): void;
1929
+ emitDefinitionCall(type: string, id: string, props?: unknown): void;
1930
+ emitTraceComplete(run: TraceEntry): void;
2276
1931
  }
2277
1932
  /**
2278
1933
  * Create a {@link PluginManager} that broadcasts lifecycle events to registered plugins.
@@ -2430,7 +2085,7 @@ interface CreateErrorBoundaryOptions {
2430
2085
  declare function createErrorBoundaryManager(options?: CreateErrorBoundaryOptions): ErrorBoundaryManager;
2431
2086
 
2432
2087
  /**
2433
- * Time-Travel Debugging - Snapshot-based state history
2088
+ * History Snapshot-based state history
2434
2089
  *
2435
2090
  * Features:
2436
2091
  * - Ring buffer of state snapshots
@@ -2440,7 +2095,7 @@ declare function createErrorBoundaryManager(options?: CreateErrorBoundaryOptions
2440
2095
  */
2441
2096
 
2442
2097
  /**
2443
- * Internal time-travel manager that extends the public {@link TimeTravelAPI}
2098
+ * Internal history manager that extends the public {@link HistoryAPI}
2444
2099
  * with snapshot capture, restoration, and pause/resume controls.
2445
2100
  *
2446
2101
  * @remarks
@@ -2456,12 +2111,12 @@ declare function createErrorBoundaryManager(options?: CreateErrorBoundaryOptions
2456
2111
  *
2457
2112
  * @internal
2458
2113
  */
2459
- interface TimeTravelManager<_S extends Schema> extends TimeTravelAPI {
2114
+ interface HistoryManager<_S extends Schema> extends HistoryAPI {
2460
2115
  /** Take a snapshot of current state */
2461
2116
  takeSnapshot(trigger: string): Snapshot;
2462
2117
  /** Restore facts from a snapshot */
2463
2118
  restore(snapshot: Snapshot): void;
2464
- /** Check if time-travel is enabled */
2119
+ /** Check if history is enabled */
2465
2120
  readonly isEnabled: boolean;
2466
2121
  /** True while restoring a snapshot (engine should skip reconciliation) */
2467
2122
  readonly isRestoring: boolean;
@@ -2471,23 +2126,23 @@ interface TimeTravelManager<_S extends Schema> extends TimeTravelAPI {
2471
2126
  resume(): void;
2472
2127
  }
2473
2128
  /**
2474
- * Options for creating a time-travel manager via {@link createTimeTravelManager}.
2129
+ * Options for creating a history manager via {@link createHistoryManager}.
2475
2130
  *
2476
2131
  * @typeParam S - The facts schema type.
2477
2132
  *
2478
2133
  * @internal
2479
2134
  */
2480
- interface CreateTimeTravelOptions<S extends Schema> {
2481
- config: DebugConfig;
2135
+ interface CreateHistoryOptions<S extends Schema> {
2136
+ historyOption: HistoryOption;
2482
2137
  facts: Facts<S>;
2483
2138
  store: FactsStore<S>;
2484
2139
  /** Callback when a snapshot is taken */
2485
2140
  onSnapshot?: (snapshot: Snapshot) => void;
2486
- /** Callback when time-travel occurs */
2487
- onTimeTravel?: (from: number, to: number) => void;
2141
+ /** Callback when history navigation occurs */
2142
+ onHistoryChange?: (from: number, to: number) => void;
2488
2143
  }
2489
2144
  /**
2490
- * Create a snapshot-based time-travel debugger backed by a ring buffer.
2145
+ * Create a snapshot-based history manager backed by a ring buffer.
2491
2146
  *
2492
2147
  * @remarks
2493
2148
  * Snapshots are taken automatically after fact changes (during reconciliation)
@@ -2499,25 +2154,25 @@ interface CreateTimeTravelOptions<S extends Schema> {
2499
2154
  * Call `pause()` to temporarily stop recording snapshots (e.g., during bulk
2500
2155
  * fact imports) and `resume()` to re-enable recording.
2501
2156
  *
2502
- * @param options - Debug config, facts proxy, store, and optional snapshot/time-travel callbacks.
2503
- * @returns A {@link TimeTravelManager} with snapshot capture, navigation, changeset, and export/import methods.
2157
+ * @param options - History config, facts proxy, store, and optional snapshot/history callbacks.
2158
+ * @returns A {@link HistoryManager} with snapshot capture, navigation, changeset, and export/import methods.
2504
2159
  *
2505
2160
  * @internal
2506
2161
  */
2507
- declare function createTimeTravelManager<S extends Schema>(options: CreateTimeTravelOptions<S>): TimeTravelManager<S>;
2162
+ declare function createHistoryManager<S extends Schema>(options: CreateHistoryOptions<S>): HistoryManager<S>;
2508
2163
  /**
2509
- * Create a no-op time-travel manager for use when `debug.timeTravel` is disabled.
2164
+ * Create a no-op history manager for use when history is disabled.
2510
2165
  *
2511
2166
  * @remarks
2512
2167
  * All methods are safe to call but perform no work. This avoids null-checks
2513
- * throughout the engine -- callers can use the same {@link TimeTravelManager}
2514
- * interface regardless of whether time-travel is enabled.
2168
+ * throughout the engine -- callers can use the same {@link HistoryManager}
2169
+ * interface regardless of whether history is enabled.
2515
2170
  *
2516
- * @returns A {@link TimeTravelManager} where every method is a no-op and `isEnabled` is `false`.
2171
+ * @returns A {@link HistoryManager} where every method is a no-op and `isEnabled` is `false`.
2517
2172
  *
2518
2173
  * @internal
2519
2174
  */
2520
- declare function createDisabledTimeTravel<S extends Schema>(): TimeTravelManager<S>;
2175
+ declare function createDisabledHistory<S extends Schema>(): HistoryManager<S>;
2521
2176
 
2522
2177
  /**
2523
2178
  * Engine - The core reconciliation loop
@@ -2532,7 +2187,7 @@ declare function createDisabledTimeTravel<S extends Schema>(): TimeTravelManager
2532
2187
 
2533
2188
  /**
2534
2189
  * Create the core Directive reconciliation engine that wires facts, derivations,
2535
- * effects, constraints, resolvers, plugins, error boundaries, and time-travel
2190
+ * effects, constraints, resolvers, plugins, error boundaries, and history
2536
2191
  * into a single reactive system.
2537
2192
  *
2538
2193
  * @remarks
@@ -2640,4 +2295,4 @@ declare const Backoff: {
2640
2295
  readonly Exponential: "exponential";
2641
2296
  };
2642
2297
 
2643
- export { Backoff, BatchConfig, type Branded, type ChainableSchemaType, type ConstraintBuilderComplete, type ConstraintBuilderStart, type ConstraintBuilderWithWhen, ConstraintState, ConstraintsDef, CreateSystemOptionsNamed, CreateSystemOptionsSingle, CrossModuleConstraintsDef, CrossModuleDeps, CrossModuleDerivationsDef, CrossModuleEffectsDef, DebugConfig, type DerivationState, type DerivationsDef, DerivationsSchema, type DerivedValues, DirectiveError, EffectsDef, ErrorBoundaryConfig, ErrorSource, type ExtendedSchemaType, FactChange, Facts, FactsSnapshot, FactsStore, InferFacts, InferRequirements, type InflightInfo, type ModuleBuilder, type ModuleConfig, type ModuleConfigWithDeps, ModuleDef, ModuleHooks, ModuleSchema, ModulesMap, NamespacedSystem, type NamespacedSystemBuilder, type PendingRetry, Plugin, ReconcileResult, RecoveryStrategy, Requirement, RequirementKeyFn, RequirementOutput$1 as RequirementOutput, RequirementSet, type RequirementTypeStatus, RequirementWithId, ResolverContext, ResolverStatus, ResolversDef, RetryLaterConfig, RetryPolicy, RunChangelogEntry, Schema, SchemaType, SingleModuleSystem, type SingleModuleSystemBuilder, Snapshot, System, type SystemBuilderStart, SystemConfig, TimeTravelAPI, type TypedConstraint, TypedConstraintDef, TypedConstraintsDef, TypedDerivationsDef, TypedEventsDef, type TypedResolver, TypedResolversDef, type WhenBuilder, type WhenConstraint, constraint, constraintFactory, createConstraintsManager, createDerivationsManager, createDisabledTimeTravel, createEffectsManager, createEngine, createErrorBoundaryManager, createFacts, createFactsProxy, createFactsStore, createModule, createModuleFactory, createPluginManager, createRequirementStatusPlugin, createResolversManager, createRetryLaterManager, createStatusHook, createSystem, createSystemWithStatus, createTimeTravelManager, forType, generateRequirementId, getCurrentTracker, isRequirementType, isTracking, module$1 as module, req, resolverFactory, system, t, trackAccess, typedConstraint, typedResolver, when, withTracking, withoutTracking };
2298
+ export { Backoff, BatchConfig, type Branded, type ChainableSchemaType, ConstraintState, ConstraintsDef, CreateSystemOptionsNamed, CreateSystemOptionsSingle, CrossModuleConstraintsDef, CrossModuleDeps, CrossModuleDerivationsDef, CrossModuleEffectsDef, type DerivationState, type DerivationsDef, type DerivedValues, DirectiveError, EffectsDef, ErrorBoundaryConfig, ErrorSource, type ExtendedSchemaType, FactChange, Facts, FactsSnapshot, FactsStore, HistoryAPI, HistoryOption, type InflightInfo, type ModuleConfig, type ModuleConfigWithDeps, ModuleDef, ModuleHooks, ModuleSchema, ModulesMap, NamespacedSystem, type PendingRetry, Plugin, ReconcileResult, RecoveryStrategy, Requirement, RequirementKeyFn, RequirementSet, type RequirementTypeStatus, RequirementWithId, ResolverContext, ResolverStatus, ResolversDef, RetryLaterConfig, RetryPolicy, Schema, SchemaType, SingleModuleSystem, Snapshot, System, SystemConfig, TraceEntry, TraceOption, type TypedConstraint, TypedConstraintsDef, TypedDerivationsDef, TypedEventsDef, type TypedResolver, TypedResolversDef, createConstraintFactory, createConstraintsManager, createDerivationsManager, createDisabledHistory, createEffectsManager, createEngine, createErrorBoundaryManager, createFacts, createFactsProxy, createFactsStore, createHistoryManager, createModule, createModuleFactory, createPluginManager, createRequirementStatusPlugin, createResolverFactory, createResolversManager, createRetryLaterManager, createStatusHook, createSystem, createSystemWithStatus, forType, generateRequirementId, getCurrentTracker, isRequirementType, isTracking, req, t, trackAccess, typedConstraint, typedResolver, withTracking, withoutTracking };