@directive-run/core 0.5.0 → 0.8.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-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, D as DerivationsSchema, q as TypedConstraintDef, r as RequirementOutput$1, I as InferRequirements, P as Plugin, s as DebugConfig, t as ErrorBoundaryConfig, u as InferFacts, v as ExtractSchema, w as RequirementWithId, x as RequirementKeyFn, y as FactsStore, 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-Co2_xohI.cjs';
-export { $ as AnySystem, a0 as BatchItemResult, a1 as BatchResolveResults, a2 as ConstraintsControl, a3 as CrossModuleConstraintDef, a4 as CrossModuleDerivationFn, a5 as CrossModuleEffectDef, a6 as CrossModuleFactsWithSelf, a7 as DerivationKeys, a8 as DerivationReturnType, a9 as DerivationsControl, aa as DeriveAccessor, ab as DispatchEventsFromSchema, ac as DistributableSnapshot, ad as DistributableSnapshotOptions, ae as EffectCleanup, af as EffectsControl, ag as EventPayloadSchema, ah as EventsAccessor, ai as EventsAccessorFromSchema, aj as EventsDef, ak as EventsSchema, al as FactKeys, am as FactReturnType, an as FlexibleEventHandler, ao as InferDerivations, ap as InferEventPayloadFromSchema, aq as InferEvents, ar as InferRequirementPayloadFromSchema, as as InferRequirementTypes, at as InferSchema, au as InferSchemaType, av as InferSelectorState, aw as MutableNamespacedFacts, ax as NamespacedDerivations, ay as NamespacedEventsAccessor, az as NamespacedFacts, aA as ObservableKeys, aB as RequirementExplanation, aC as RequirementPayloadSchema, aD as RequirementsSchema, aE as ResolversControl, aF as SnapshotMeta, aG as SystemEvent, aH as SystemInspection, aI as SystemMode, aJ as SystemSnapshot, aK as TimeTravelState, aL as TypedResolverContext, aM as TypedResolverDef, aN as UnionEvents, aO as isNamespacedSystem, aP as isSingleModuleSystem } from './plugins-Co2_xohI.cjs';
+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';
+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';
 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';
 
 /**
@@ -515,8 +515,11 @@ interface ModuleConfig<M extends ModuleSchema> {
     constraints?: TypedConstraintsDef<M>;
     resolvers?: TypedResolversDef<M>;
     hooks?: ModuleHooks<M>;
-    /** Events that create time-travel snapshots for undo/redo. Omit to snapshot all events. */
-    snapshotEvents?: Array<keyof (M["events"] extends Record<string, unknown> ? M["events"] : Record<string, never>) & string>;
+    /** History configuration — controls which events create snapshots for undo/redo. */
+    history?: {
+        /** Events that create history snapshots. Omit to snapshot all events. */
+        snapshotEvents?: Array<keyof (M["events"] extends Record<string, unknown> ? M["events"] : Record<string, never>) & string>;
+    };
 }
 /**
  * Module configuration with cross-module dependencies for type-safe access
@@ -586,8 +589,11 @@ interface ModuleConfigWithDeps<M extends ModuleSchema, Deps extends CrossModuleD
     /** Resolvers. Uses flat access (`ctx.facts.myFact`) to keep async mutations scoped to own module. */
     resolvers?: TypedResolversDef<M>;
     hooks?: ModuleHooks<M>;
-    /** Events that create time-travel snapshots for undo/redo. Omit to snapshot all events. */
-    snapshotEvents?: Array<keyof (M["events"] extends Record<string, unknown> ? M["events"] : Record<string, never>) & string>;
+    /** History configuration — controls which events create snapshots for undo/redo. */
+    history?: {
+        /** Events that create history snapshots. Omit to snapshot all events. */
+        snapshotEvents?: Array<keyof (M["events"] extends Record<string, unknown> ? M["events"] : Record<string, never>) & string>;
+    };
 }
 /**
  * Create a module definition with full type inference.
@@ -767,431 +773,6 @@ declare function createModuleFactory<const M extends ModuleSchema, const Deps ex
 declare function createSystem<S extends ModuleSchema>(options: CreateSystemOptionsSingle<S>): SingleModuleSystem<S>;
 declare function createSystem<const Modules extends ModulesMap>(options: CreateSystemOptionsNamed<Modules>): NamespacedSystem<Modules>;
 
-/**
- * Builder Pattern API for Directive Modules
- *
- * An alternative, fluent API for creating modules that provides
- * a more declarative style for module definition.
- *
- * @example
- * ```typescript
- * import { module, t } from '@directive-run/core';
- *
- * const counter = module("counter")
- *   .schema({
- *     facts: { count: t.number(), lastAction: t.string() },
- *     derivations: { doubled: t.number(), isPositive: t.boolean() },
- *     events: { increment: {}, decrement: {} },
- *     requirements: {},
- *   })
- *   .init((facts) => {
- *     facts.count = 0;
- *     facts.lastAction = "";
- *   })
- *   .derive({
- *     doubled: (facts) => facts.count * 2,
- *     isPositive: (facts) => facts.count > 0,
- *   })
- *   .events({
- *     increment: (facts) => {
- *       facts.count += 1;
- *       facts.lastAction = "increment";
- *     },
- *     decrement: (facts) => {
- *       facts.count -= 1;
- *       facts.lastAction = "decrement";
- *     },
- *   })
- *   .build();
- * ```
- */
-
-/**
- * Fluent builder interface for constructing {@link ModuleDef} instances step by step.
- *
- * Chain methods like `.schema()`, `.init()`, `.derive()`, `.events()`, and others
- * to configure the module, then call `.build()` to produce the final definition.
- * The builder validates that all schema-declared derivations and events have
- * corresponding implementations before returning.
- *
- * @typeParam M - The module schema type, narrowed after calling `.schema()`.
- * @public
- */
-interface ModuleBuilder<M extends ModuleSchema = ModuleSchema> {
-    /**
-     * Define the schema for this module (facts, derivations, events, requirements).
-     */
-    schema<NewM extends ModuleSchema>(schema: NewM): ModuleBuilder<NewM>;
-    /**
-     * Define the initialization function for this module.
-     */
-    init(initFn: (facts: Facts<M["facts"]>) => void): ModuleBuilder<M>;
-    /**
-     * Define derivation implementations for this module.
-     * Keys must match those declared in schema.derivations.
-     */
-    derive<D extends Record<string, (facts: Facts<M["facts"]>, derived: DeriveAccessor<M>) => unknown>>(derivations: D): ModuleBuilder<M>;
-    /**
-     * Define event handler implementations for this module.
-     * Keys must match those declared in schema.events.
-     */
-    events<E extends Record<string, (facts: Facts<M["facts"]>, payload: unknown) => void>>(events: E): ModuleBuilder<M>;
-    /**
-     * Define effects (side effects) for this module.
-     */
-    effects(effects: EffectsDef<M["facts"]>): ModuleBuilder<M>;
-    /**
-     * Define constraints for this module.
-     */
-    constraints<C extends Record<string, ConstraintDef<M>>>(constraints: C): ModuleBuilder<M>;
-    /**
-     * Define resolvers for this module.
-     */
-    resolvers<R extends Record<string, ResolverDef<M>>>(resolvers: R): ModuleBuilder<M>;
-    /**
-     * Define lifecycle hooks for this module.
-     */
-    hooks(hooks: ModuleHooks<M>): ModuleBuilder<M>;
-    /**
-     * Build the module definition.
-     */
-    build(): ModuleDef<M>;
-}
-/**
- * Accessor for reading other derivations within a derivation function.
- */
-type DeriveAccessor<M extends ModuleSchema> = M["derivations"] extends DerivationsSchema ? {
-    readonly [K in keyof M["derivations"]]: InferSchemaType<M["derivations"][K]>;
-} : Record<string, never>;
-/**
- * Infer the TypeScript type from a schema type definition.
- */
-type InferSchemaType<T> = T extends {
-    _type: infer U;
-} ? U : any;
-/**
- * Constraint definition for the builder.
- */
-interface ConstraintDef<M extends ModuleSchema> {
-    when: (facts: Facts<M["facts"]>) => boolean;
-    require: {
-        type: string;
-        [key: string]: unknown;
-    } | ((facts: Facts<M["facts"]>) => {
-        type: string;
-        [key: string]: unknown;
-    } | null);
-    priority?: number;
-}
-/**
- * Resolver definition for the builder.
- */
-interface ResolverDef<M extends ModuleSchema> {
-    requirement: string | ((req: {
-        type: string;
-        [key: string]: unknown;
-    }) => boolean);
-    resolve: (req: {
-        type: string;
-        [key: string]: unknown;
-    }, ctx: {
-        facts: Facts<M["facts"]>;
-        signal?: AbortSignal;
-    }) => void | Promise<void>;
-    retry?: {
-        attempts?: number;
-        backoff?: "linear" | "exponential";
-        delay?: number;
-    };
-    timeout?: number;
-    key?: (req: {
-        type: string;
-        [key: string]: unknown;
-    }) => string;
-}
-/**
- * Create a new module using the fluent builder pattern.
- *
- * Returns a {@link ModuleBuilder} that lets you declaratively define a module's
- * schema, initialization, derivations, events, effects, constraints, resolvers,
- * and lifecycle hooks via method chaining. Call `.build()` at the end to produce
- * the final {@link ModuleDef}.
- *
- * @remarks
- * The builder validates at build time that every derivation and event declared
- * in the schema has a corresponding implementation. Missing implementations
- * cause a descriptive error.
- *
- * @param id - Unique identifier for this module, used for namespacing in multi-module systems.
- * @returns A {@link ModuleBuilder} ready for configuration via method chaining.
- *
- * @example
- * ```typescript
- * import { module, t } from '@directive-run/core';
- *
- * const counter = module("counter")
- *   .schema({
- *     facts: { count: t.number() },
- *     derivations: { doubled: t.number() },
- *     events: { increment: {} },
- *     requirements: {},
- *   })
- *   .init((facts) => {
- *     facts.count = 0;
- *   })
- *   .derive({
- *     doubled: (facts) => facts.count * 2,
- *   })
- *   .events({
- *     increment: (facts) => {
- *       facts.count += 1;
- *     },
- *   })
- *   .build();
- * ```
- *
- * @public
- */
-declare function module$1(id: string): ModuleBuilder<ModuleSchema>;
-
-/**
- * Constraint Builder API
- *
- * Fluent builders for creating typed constraint definitions.
- *
- * @example Full builder
- * ```typescript
- * import { constraint } from '@directive-run/core';
- *
- * const escalate = constraint<typeof schema>()
- *   .when(f => f.confidence < 0.7)
- *   .require({ type: 'ESCALATE' })
- *   .priority(50)
- *   .build();
- * ```
- *
- * @example Quick shorthand
- * ```typescript
- * import { when } from '@directive-run/core';
- *
- * const pause = when<typeof schema>(f => f.errors > 3)
- *   .require({ type: 'PAUSE' });
- * ```
- */
-
-type WhenFn<M extends ModuleSchema> = (facts: Facts<M["facts"]>) => boolean | Promise<boolean>;
-type RequireValue<M extends ModuleSchema> = RequirementOutput$1<InferRequirements<M>> | ((facts: Facts<M["facts"]>) => RequirementOutput$1<InferRequirements<M>>);
-/** Builder after constraint() — must call .when() first */
-interface ConstraintBuilderStart<M extends ModuleSchema> {
-    when(condition: WhenFn<M>): ConstraintBuilderWithWhen<M>;
-}
-/** Builder after .when() — must call .require() next */
-interface ConstraintBuilderWithWhen<M extends ModuleSchema> {
-    require(req: RequireValue<M>): ConstraintBuilderComplete<M>;
-}
-/** Builder after .require() — optional chaining + .build() */
-interface ConstraintBuilderComplete<M extends ModuleSchema> {
-    priority(n: number): ConstraintBuilderComplete<M>;
-    after(...ids: string[]): ConstraintBuilderComplete<M>;
-    deps(...keys: string[]): ConstraintBuilderComplete<M>;
-    timeout(ms: number): ConstraintBuilderComplete<M>;
-    async(value: boolean): ConstraintBuilderComplete<M>;
-    build(): TypedConstraintDef<M>;
-}
-/** Result from when().require() — a valid constraint with optional immutable chaining */
-type WhenConstraint<M extends ModuleSchema> = TypedConstraintDef<M> & {
-    withPriority(n: number): WhenConstraint<M>;
-    withAfter(...ids: string[]): WhenConstraint<M>;
-    withDeps(...keys: string[]): WhenConstraint<M>;
-    withTimeout(ms: number): WhenConstraint<M>;
-    withAsync(value: boolean): WhenConstraint<M>;
-};
-/** Result from when() — must call .require() */
-interface WhenBuilder<M extends ModuleSchema> {
-    require(req: RequireValue<M>): WhenConstraint<M>;
-}
-/**
- * Create a constraint using the full builder pattern.
- * Requires `.when()`, `.require()`, and `.build()`.
- *
- * @example
- * ```typescript
- * const c = constraint<typeof schema>()
- *   .when(f => f.phase === "red")
- *   .require({ type: "TRANSITION", to: "green" })
- *   .priority(50)
- *   .after("healthCheck")
- *   .build();
- * ```
- */
-declare function constraint<M extends ModuleSchema>(): ConstraintBuilderStart<M>;
-/**
- * Quick shorthand for creating constraints.
- * Returns a valid constraint directly (no `.build()` needed).
- *
- * @example
- * ```typescript
- * const pause = when<typeof schema>(f => f.errors > 3)
- *   .require({ type: 'PAUSE' });
- *
- * // With optional chaining (immutable — returns new constraint)
- * const halt = when<typeof schema>(f => f.errors > 10)
- *   .require({ type: 'HALT' })
- *   .withPriority(100)
- *   .withAfter('healthCheck');
- * ```
- */
-declare function when<M extends ModuleSchema>(condition: WhenFn<M>): WhenBuilder<M>;
-
-/**
- * System Builder API
- *
- * Fluent builder for creating Directive systems.
- *
- * @example Single module
- * ```typescript
- * import { system } from '@directive-run/core';
- *
- * const sys = system()
- *   .module(counterModule)
- *   .plugins([loggingPlugin()])
- *   .debug({ timeTravel: true })
- *   .build();
- * ```
- *
- * @example Multiple modules
- * ```typescript
- * const sys = system()
- *   .modules({ auth: authModule, cart: cartModule })
- *   .plugins([loggingPlugin()])
- *   .build();
- * ```
- */
-
-/**
- * Entry point of the system builder, returned by {@link system}.
- *
- * Choose `.module()` for a single-module {@link SingleModuleSystem} with direct
- * fact/derivation access, or `.modules()` for a namespaced {@link NamespacedSystem}
- * that composes multiple modules.
- *
- * @public
- */
-interface SystemBuilderStart {
-    /**
-     * Configure the system with a single module definition.
-     *
-     * @param mod - The module definition to use as the system's sole module.
-     * @returns A {@link SingleModuleSystemBuilder} for further configuration.
-     */
-    module<S extends ModuleSchema>(mod: ModuleDef<S>): SingleModuleSystemBuilder<S>;
-    /**
-     * Configure the system with multiple named modules.
-     *
-     * @param mods - A map of namespace keys to module definitions.
-     * @returns A {@link NamespacedSystemBuilder} for further configuration.
-     */
-    modules<const Modules extends ModulesMap>(mods: Modules): NamespacedSystemBuilder<Modules>;
-}
-/**
- * Builder for a single-module system with direct access to facts, derivations, and events.
- *
- * @remarks
- * Use this builder when your system contains exactly one module. The resulting
- * {@link SingleModuleSystem} exposes facts, derivations, and dispatch without
- * namespace prefixes.
- *
- * @typeParam S - The module schema type.
- * @public
- */
-interface SingleModuleSystemBuilder<S extends ModuleSchema> {
-    /** Register plugins that hook into system lifecycle events. */
-    plugins(plugins: Array<Plugin<ModuleSchema>>): SingleModuleSystemBuilder<S>;
-    /** Enable debug features such as time-travel debugging and snapshot limits. */
-    debug(config: DebugConfig): SingleModuleSystemBuilder<S>;
-    /** Configure error boundary behavior including recovery strategies. */
-    errorBoundary(config: ErrorBoundaryConfig): SingleModuleSystemBuilder<S>;
-    /** Set the reconciliation tick interval in milliseconds. */
-    tickMs(ms: number): SingleModuleSystemBuilder<S>;
-    /** Enable zero-config mode which auto-generates constraints from schema metadata. */
-    zeroConfig(enabled?: boolean): SingleModuleSystemBuilder<S>;
-    /** Provide initial fact values to hydrate the system on startup. */
-    initialFacts(facts: Partial<InferFacts<S>>): SingleModuleSystemBuilder<S>;
-    /** Finalize configuration and create the running {@link SingleModuleSystem}. */
-    build(): SingleModuleSystem<S>;
-}
-/**
- * Builder for a namespaced multi-module system.
- *
- * @remarks
- * Use this builder when composing multiple modules. The resulting
- * {@link NamespacedSystem} prefixes facts and derivations with the module
- * namespace key (e.g., `system.facts.auth.token`).
- *
- * @typeParam Modules - The modules map type mapping namespace keys to module definitions.
- * @public
- */
-interface NamespacedSystemBuilder<Modules extends ModulesMap> {
-    /** Register plugins that hook into system lifecycle events. */
-    plugins(plugins: Array<Plugin<ModuleSchema>>): NamespacedSystemBuilder<Modules>;
-    /** Enable debug features such as time-travel debugging and snapshot limits. */
-    debug(config: DebugConfig): NamespacedSystemBuilder<Modules>;
-    /** Configure error boundary behavior including recovery strategies. */
-    errorBoundary(config: ErrorBoundaryConfig): NamespacedSystemBuilder<Modules>;
-    /** Set the reconciliation tick interval in milliseconds. */
-    tickMs(ms: number): NamespacedSystemBuilder<Modules>;
-    /** Enable zero-config mode which auto-generates constraints from schema metadata. */
-    zeroConfig(enabled?: boolean): NamespacedSystemBuilder<Modules>;
-    /** Provide initial fact values keyed by module namespace for hydration on startup. */
-    initialFacts(facts: Partial<{
-        [K in keyof Modules]: Partial<InferFacts<ExtractSchema<Modules[K]>>>;
-    }>): NamespacedSystemBuilder<Modules>;
-    /** Control the order in which modules are initialized: automatic, declaration order, or explicit. */
-    initOrder(order: "auto" | "declaration" | Array<keyof Modules & string>): NamespacedSystemBuilder<Modules>;
-    /** Finalize configuration and create the running {@link NamespacedSystem}. */
-    build(): NamespacedSystem<Modules>;
-}
-/**
- * Create a Directive system using the fluent builder pattern.
- *
- * Returns a {@link SystemBuilderStart} that branches into either a
- * single-module path (`.module()`) or a namespaced multi-module path
- * (`.modules()`). Chain configuration methods like `.plugins()`, `.debug()`,
- * and `.errorBoundary()`, then call `.build()` to produce the running system.
- *
- * @remarks
- * This is a convenience wrapper around {@link createSystem}. Both produce
- * identical systems; the builder simply offers a more discoverable,
- * chainable API.
- *
- * @returns A {@link SystemBuilderStart} ready to receive a module or modules map.
- *
- * @example Single-module system
- * ```typescript
- * import { system } from '@directive-run/core';
- *
- * const sys = system()
- *   .module(counterModule)
- *   .plugins([loggingPlugin()])
- *   .debug({ timeTravel: true })
- *   .build();
- * ```
- *
- * @example Multi-module namespaced system
- * ```typescript
- * import { system } from '@directive-run/core';
- *
- * const sys = system()
- *   .modules({ auth: authModule, cart: cartModule })
- *   .plugins([loggingPlugin()])
- *   .initOrder(["auth", "cart"])
- *   .build();
- * ```
- *
- * @public
- */
-declare function system(): SystemBuilderStart;
-
 /**
  * Requirement Status Utilities
  *
@@ -1278,8 +859,8 @@ interface CreateSystemWithStatusOptions<M extends ModuleSchema> {
     module: ModuleDef<M>;
     /** Additional plugins to include alongside the status plugin */
     plugins?: Plugin<any>[];
-    /** Debug configuration */
-    debug?: DebugConfig;
+    /** Trace: per-run reconciliation changelog */
+    trace?: TraceOption;
     /** Error boundary configuration */
     errorBoundary?: ErrorBoundaryConfig;
     /** Tick interval in milliseconds */
@@ -1694,8 +1275,12 @@ interface CreateDerivationsOptions<S extends Schema, D extends DerivationsDef<S>
  * Notifications are deferred during invalidation so listeners always see
  * consistent state across multiple simultaneous fact changes.
  *
- * @param options - Derivation definitions, facts proxy, store, and optional lifecycle callbacks
- * @returns A `DerivationsManager` with get/invalidate/subscribe/getProxy methods
+ * @param options - Derivation definitions, facts proxy, store, and optional
+ *   lifecycle callbacks.
+ * @returns A {@link DerivationsManager} for accessing, invalidating, and
+ *   subscribing to derived values.
+ *
+ * @internal
  */
 declare function createDerivationsManager<S extends Schema, D extends DerivationsDef<S>>(options: CreateDerivationsOptions<S, D>): DerivationsManager<S, D>;
 
@@ -2300,9 +1885,9 @@ declare function createResolversManager<S extends Schema>(options: CreateResolve
  * - **Requirements:** `emitRequirementCreated`, `emitRequirementMet`, `emitRequirementCanceled`
  * - **Resolvers:** `emitResolverStart`, `emitResolverComplete`, `emitResolverError`, `emitResolverRetry`, `emitResolverCancel`
  * - **Effects:** `emitEffectRun`, `emitEffectError`
- * - **Time-travel:** `emitSnapshot`, `emitTimeTravel`
+ * - **History:** `emitSnapshot`, `emitHistoryNavigate`
  * - **Errors:** `emitError`, `emitErrorRecovery`
- * - **Run history:** `emitRunComplete`
+ * - **Trace:** `emitTraceComplete`
  *
  * @typeParam _S - The flat schema type (unused at runtime).
  *
@@ -2339,14 +1924,14 @@ interface PluginManager<_S extends Schema = any> {
     emitEffectRun(id: string): void;
     emitEffectError(id: string, error: unknown): void;
     emitSnapshot(snapshot: Snapshot): void;
-    emitTimeTravel(from: number, to: number): void;
+    emitHistoryNavigate(from: number, to: number): void;
     emitError(error: DirectiveError): void;
     emitErrorRecovery(error: DirectiveError, strategy: RecoveryStrategy): void;
     emitDefinitionRegister(type: string, id: string, def: unknown): void;
     emitDefinitionAssign(type: string, id: string, def: unknown, original: unknown): void;
     emitDefinitionUnregister(type: string, id: string): void;
     emitDefinitionCall(type: string, id: string, props?: unknown): void;
-    emitRunComplete(run: RunChangelogEntry): void;
+    emitTraceComplete(run: TraceEntry): void;
 }
 /**
  * Create a {@link PluginManager} that broadcasts lifecycle events to registered plugins.
@@ -2504,7 +2089,7 @@ interface CreateErrorBoundaryOptions {
 declare function createErrorBoundaryManager(options?: CreateErrorBoundaryOptions): ErrorBoundaryManager;
 
 /**
- * Time-Travel Debugging - Snapshot-based state history
+ * History — Snapshot-based state history
  *
  * Features:
  * - Ring buffer of state snapshots
@@ -2514,7 +2099,7 @@ declare function createErrorBoundaryManager(options?: CreateErrorBoundaryOptions
  */
 
 /**
- * Internal time-travel manager that extends the public {@link TimeTravelAPI}
+ * Internal history manager that extends the public {@link HistoryAPI}
  * with snapshot capture, restoration, and pause/resume controls.
  *
  * @remarks
@@ -2530,12 +2115,12 @@ declare function createErrorBoundaryManager(options?: CreateErrorBoundaryOptions
  *
  * @internal
  */
-interface TimeTravelManager<_S extends Schema> extends TimeTravelAPI {
+interface HistoryManager<_S extends Schema> extends HistoryAPI {
     /** Take a snapshot of current state */
     takeSnapshot(trigger: string): Snapshot;
     /** Restore facts from a snapshot */
     restore(snapshot: Snapshot): void;
-    /** Check if time-travel is enabled */
+    /** Check if history is enabled */
     readonly isEnabled: boolean;
     /** True while restoring a snapshot (engine should skip reconciliation) */
     readonly isRestoring: boolean;
@@ -2545,23 +2130,23 @@ interface TimeTravelManager<_S extends Schema> extends TimeTravelAPI {
     resume(): void;
 }
 /**
- * Options for creating a time-travel manager via {@link createTimeTravelManager}.
+ * Options for creating a history manager via {@link createHistoryManager}.
  *
  * @typeParam S - The facts schema type.
  *
  * @internal
  */
-interface CreateTimeTravelOptions<S extends Schema> {
-    config: DebugConfig;
+interface CreateHistoryOptions<S extends Schema> {
+    historyOption: HistoryOption;
     facts: Facts<S>;
     store: FactsStore<S>;
     /** Callback when a snapshot is taken */
     onSnapshot?: (snapshot: Snapshot) => void;
-    /** Callback when time-travel occurs */
-    onTimeTravel?: (from: number, to: number) => void;
+    /** Callback when history navigation occurs */
+    onHistoryChange?: (from: number, to: number) => void;
 }
 /**
- * Create a snapshot-based time-travel debugger backed by a ring buffer.
+ * Create a snapshot-based history manager backed by a ring buffer.
  *
  * @remarks
  * Snapshots are taken automatically after fact changes (during reconciliation)
@@ -2573,25 +2158,25 @@ interface CreateTimeTravelOptions<S extends Schema> {
  * Call `pause()` to temporarily stop recording snapshots (e.g., during bulk
  * fact imports) and `resume()` to re-enable recording.
  *
- * @param options - Debug config, facts proxy, store, and optional snapshot/time-travel callbacks.
- * @returns A {@link TimeTravelManager} with snapshot capture, navigation, changeset, and export/import methods.
+ * @param options - History config, facts proxy, store, and optional snapshot/history callbacks.
+ * @returns A {@link HistoryManager} with snapshot capture, navigation, changeset, and export/import methods.
  *
  * @internal
  */
-declare function createTimeTravelManager<S extends Schema>(options: CreateTimeTravelOptions<S>): TimeTravelManager<S>;
+declare function createHistoryManager<S extends Schema>(options: CreateHistoryOptions<S>): HistoryManager<S>;
 /**
- * Create a no-op time-travel manager for use when `debug.timeTravel` is disabled.
+ * Create a no-op history manager for use when history is disabled.
  *
  * @remarks
  * All methods are safe to call but perform no work. This avoids null-checks
- * throughout the engine -- callers can use the same {@link TimeTravelManager}
- * interface regardless of whether time-travel is enabled.
+ * throughout the engine -- callers can use the same {@link HistoryManager}
+ * interface regardless of whether history is enabled.
  *
- * @returns A {@link TimeTravelManager} where every method is a no-op and `isEnabled` is `false`.
+ * @returns A {@link HistoryManager} where every method is a no-op and `isEnabled` is `false`.
  *
  * @internal
  */
-declare function createDisabledTimeTravel<S extends Schema>(): TimeTravelManager<S>;
+declare function createDisabledHistory<S extends Schema>(): HistoryManager<S>;
 
 /**
  * Engine - The core reconciliation loop
@@ -2606,7 +2191,7 @@ declare function createDisabledTimeTravel<S extends Schema>(): TimeTravelManager
 
 /**
  * Create the core Directive reconciliation engine that wires facts, derivations,
- * effects, constraints, resolvers, plugins, error boundaries, and time-travel
+ * effects, constraints, resolvers, plugins, error boundaries, and history
  * into a single reactive system.
  *
  * @remarks
@@ -2645,16 +2230,34 @@ declare function createEngine<S extends Schema>(config: SystemConfig<any>): Syst
 
 /**
  * Get the current tracking context.
- * Returns null context if no tracking is active.
+ *
+ * @returns The active {@link TrackingContext}, or a null context (no-op) if
+ *   no tracking is active.
+ *
+ * @internal
  */
 declare function getCurrentTracker(): TrackingContext;
 /**
- * Check if we're currently tracking dependencies.
+ * Check if dependency tracking is currently active.
+ *
+ * @returns `true` if inside a {@link withTracking} call, `false` otherwise.
+ *
+ * @internal
  */
 declare function isTracking(): boolean;
 /**
  * Run a function with dependency tracking.
- * Returns the computed value and the set of dependencies accessed.
+ *
+ * @remarks
+ * Pushes a fresh tracking context onto the stack, executes `fn`, then pops
+ * the context. Any fact reads inside `fn` are recorded as dependencies.
+ * Nesting is supported — inner calls get their own independent context.
+ *
+ * @param fn - The function to execute under tracking.
+ * @returns An object with the computed `value` and a `deps` Set of accessed
+ *   fact keys.
+ *
+ * @internal
  */
 declare function withTracking<T>(fn: () => T): {
     value: T;
@@ -2662,12 +2265,28 @@ declare function withTracking<T>(fn: () => T): {
 };
 /**
  * Run a function without tracking.
- * Useful for reading facts without creating dependencies.
+ *
+ * @remarks
+ * Temporarily clears the tracking stack so that fact reads inside `fn` do
+ * not register as dependencies. The stack is restored after `fn` returns
+ * (even on error). Useful for side-effect reads that should not trigger
+ * derivation invalidation.
+ *
+ * @param fn - The function to execute without tracking.
+ * @returns The return value of `fn`.
+ *
+ * @internal
  */
 declare function withoutTracking<T>(fn: () => T): T;
 /**
  * Track a specific key in the current context.
- * No-op if not currently tracking.
+ *
+ * @remarks
+ * No-op if no tracking context is active.
+ *
+ * @param key - The fact key to record as a dependency.
+ *
+ * @internal
  */
 declare function trackAccess(key: string): void;
 
@@ -2714,4 +2333,4 @@ declare const Backoff: {
     readonly Exponential: "exponential";
 };
 
-export { Backoff, BatchConfig, type Branded, type ChainableSchemaType, 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 PendingRetry, Plugin, ReconcileResult, RecoveryStrategy, Requirement, RequirementKeyFn, RequirementOutput$1 as RequirementOutput, RequirementSet, type RequirementTypeStatus, RequirementWithId, ResolverContext, ResolverStatus, ResolversDef, RetryLaterConfig, RetryPolicy, RunChangelogEntry, Schema, SchemaType, SingleModuleSystem, Snapshot, System, SystemConfig, TimeTravelAPI, type TypedConstraint, TypedConstraintDef, TypedConstraintsDef, TypedDerivationsDef, TypedEventsDef, type TypedResolver, TypedResolversDef, type WhenConstraint, constraint, createConstraintFactory, createConstraintsManager, createDerivationsManager, createDisabledTimeTravel, createEffectsManager, createEngine, createErrorBoundaryManager, createFacts, createFactsProxy, createFactsStore, createModule, createModuleFactory, createPluginManager, createRequirementStatusPlugin, createResolverFactory, createResolversManager, createRetryLaterManager, createStatusHook, createSystem, createSystemWithStatus, createTimeTravelManager, forType, generateRequirementId, getCurrentTracker, isRequirementType, isTracking, module$1 as module, req, system, t, trackAccess, typedConstraint, typedResolver, when, withTracking, withoutTracking };
+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 };