@directive-run/core 0.3.0 → 0.4.1

package/dist/index.d.ts

@@ -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, 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-DZljh9NJ.js';
-export { $ as AnySystem, a0 as BatchItemResult, a1 as BatchResolveResults, a2 as CircuitBreakerConfig, a3 as CircuitBreakerState, a4 as CrossModuleConstraintDef, a5 as CrossModuleDerivationFn, a6 as CrossModuleEffectDef, a7 as CrossModuleFactsWithSelf, a8 as DerivationKeys, a9 as DerivationReturnType, aa as DeriveAccessor, ab as DispatchEventsFromSchema, ac as DistributableSnapshot, ad as DistributableSnapshotOptions, ae as EffectCleanup, 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 InferDerivations, ao as InferEventPayloadFromSchema, ap as InferEvents, aq as InferRequirementPayloadFromSchema, ar as InferRequirementTypes, as as InferSchema, at as InferSchemaType, au as InferSelectorState, av as MutableNamespacedFacts, aw as NamespacedDerivations, ax as NamespacedEventsAccessor, ay as NamespacedFacts, az as ObservableKeys, aA as RequirementExplanation, aB as RequirementPayloadSchema, aC as RequirementsSchema, aD as SnapshotMeta, aE as SystemEvent, aF as SystemInspection, aG as SystemMode, aH as SystemSnapshot, aI as TimeTravelState, aJ as TypedResolverContext, aK as TypedResolverDef, aL as UnionEvents, aM as isNamespacedSystem, aN as isSingleModuleSystem } from './plugins-DZljh9NJ.js';
+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.js';
+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.js';
 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.js';
 export { DirectiveModuleStructure, ReduxSliceConfig, XStateMachineConfig, ZustandStoreConfig, analyzeReduxSlice, analyzeXStateMachine, analyzeZustandStore, generateMigrationChecklist, generateModuleCode } from './migration.js';
 
@@ -252,6 +252,11 @@ interface ChainableSchemaType<T> extends ExtendedSchemaType<T> {
 /**
  * Schema type builders for defining fact types.
  *
+ * @remarks
+ * Each builder returns a chainable {@link ExtendedSchemaType} with validation
+ * methods (`.min()`, `.max()`, `.pattern()`, etc.) and dev-mode runtime
+ * type checking. Validators are tree-shaken in production builds.
+ *
  * @example
  * ```typescript
  * const module = createModule("example", {
@@ -264,6 +269,8 @@ interface ChainableSchemaType<T> extends ExtendedSchemaType<T> {
  *   },
  * });
  * ```
+ *
+ * @public
  */
 declare const t: {
     /**
@@ -511,11 +518,12 @@ interface CreateFactsStoreOptions<S extends Schema> {
  * Create a reactive facts store backed by a Map with schema validation,
  * batched mutations, and granular key-level subscriptions.
  *
+ * @remarks
  * The store is the low-level primitive that powers the `facts` proxy.
  * Most users should use {@link createFacts} or `createModule` instead.
  *
  * @param options - Store configuration including schema, validation settings, and change callbacks
- * @returns A `FactsStore<S>` with get/set/batch/subscribe methods and automatic schema validation
+ * @returns A {@link FactsStore} with get/set/batch/subscribe methods and automatic schema validation
  *
  * @example
  * ```ts
@@ -531,26 +539,41 @@ interface CreateFactsStoreOptions<S extends Schema> {
  *   store.set("name", "hello");
  * }); // listeners fire once after batch completes
  * ```
+ *
+ * @internal
  */
 declare function createFactsStore<S extends Schema>(options: CreateFactsStoreOptions<S>): FactsStore<S>;
 /**
  * Create a Proxy wrapper around a {@link FactsStore} for clean property-style
  * access (`facts.phase`) with automatic dependency tracking.
  *
+ * @remarks
  * Reading a property calls `store.get()` (which tracks the access for
  * auto-tracked derivations). Writing a property calls `store.set()` (which
  * validates against the schema). The proxy also exposes `$store` for direct
  * store access and `$snapshot()` for untracked reads.
  *
  * @param store - The underlying facts store to wrap
- * @param schema - The schema definition (used for `ownKeys` enumeration)
- * @returns A `Facts<S>` proxy with property-style get/set and prototype pollution guards
+ * @param schema - The schema definition used for `ownKeys` enumeration
+ * @returns A {@link Facts} proxy with property-style get/set and prototype pollution guards
+ *
+ * @example
+ * ```ts
+ * const store = createFactsStore({ schema: { phase: t.string() } });
+ * const facts = createFactsProxy(store, { phase: t.string() });
+ *
+ * facts.phase = "red";
+ * console.log(facts.phase); // "red"
+ * ```
+ *
+ * @internal
  */
 declare function createFactsProxy<S extends Schema>(store: FactsStore<S>, schema: S): Facts<S>;
 /**
  * Convenience factory that creates both a {@link FactsStore} and its
  * {@link createFactsProxy | proxy wrapper} in a single call.
  *
+ * @remarks
  * This is the recommended entry point when you need low-level store access
  * outside of `createModule` / `createSystem`.
  *
@@ -567,6 +590,8 @@ declare function createFactsProxy<S extends Schema>(store: FactsStore<S>, schema
  * console.log(facts.phase); // "red"
  * store.subscribe(["phase"], () => console.log("phase changed"));
  * ```
+ *
+ * @internal
  */
 declare function createFacts<S extends Schema>(options: CreateFactsStoreOptions<S>): {
     store: FactsStore<S>;
@@ -675,6 +700,10 @@ interface ModuleConfigWithDeps<M extends ModuleSchema, Deps extends CrossModuleD
  * - Event dispatch (`system.dispatch({ type: "..." })` has autocomplete)
  * - Resolver requirements (`req.payload` is typed based on requirement type)
  *
+ * @param id - Unique module identifier (kebab-case recommended)
+ * @param config - Module configuration including schema, init, derive, constraints, resolvers, etc.
+ * @returns A frozen module definition ready for use with `createSystem`
+ *
  * @example
  * ```ts
  * const trafficLight = createModule("traffic-light", {
@@ -749,6 +778,8 @@ interface ModuleConfigWithDeps<M extends ModuleSchema, Deps extends CrossModuleD
  *   },
  * });
  * ```
+ *
+ * @public
  */
 declare function createModule<const M extends ModuleSchema, const Deps extends CrossModuleDeps>(id: string, config: ModuleConfigWithDeps<M, Deps>): ModuleDef<M>;
 declare function createModule<const M extends ModuleSchema>(id: string, config: ModuleConfig<M>): ModuleDef<M>;
@@ -758,6 +789,9 @@ declare function createModule<const M extends ModuleSchema>(id: string, config:
  * Useful for multi-instance UIs (tabs, panels, multi-tenant) where you need
  * isolated state from the same schema.
  *
+ * @param config - Module configuration (same shape as `createModule` minus the `id`)
+ * @returns A factory function that accepts a name and returns a `ModuleDef`
+ *
  * @example
  * ```typescript
  * const chatRoom = createModuleFactory({
@@ -776,6 +810,8 @@ declare function createModule<const M extends ModuleSchema>(id: string, config:
  *   },
  * });
  * ```
+ *
+ * @public
  */
 declare function createModuleFactory<const M extends ModuleSchema>(config: ModuleConfig<M>): (name: string) => ModuleDef<M>;
 declare function createModuleFactory<const M extends ModuleSchema, const Deps extends CrossModuleDeps>(config: ModuleConfigWithDeps<M, Deps>): (name: string) => ModuleDef<M>;
@@ -805,6 +841,14 @@ declare function createModuleFactory<const M extends ModuleSchema, const Deps ex
  * - **Single module**: Use `module` prop for direct access without namespace
  * - **Multiple modules**: Use `modules` prop for namespaced access
  *
+ * @remarks
+ * The system is the top-level runtime object. It owns the reconciliation loop,
+ * manages plugins, and exposes reactive accessors for facts, derivations, and events.
+ * Call `system.start()` to begin the lifecycle (init → ready → running → settled).
+ *
+ * @param options - System configuration with either `module` (single) or `modules` (namespaced)
+ * @returns A fully-typed {@link System} instance with reactive accessors
+ *
  * @example Single module (direct access)
  * ```ts
  * const system = createSystem({ module: counterModule });
@@ -820,6 +864,8 @@ declare function createModuleFactory<const M extends ModuleSchema, const Deps ex
  * system.facts.auth.token      // Namespaced access
  * system.events.auth.login()   // Namespaced events
  * ```
+ *
+ * @public
  */
 declare function createSystem<S extends ModuleSchema>(options: CreateSystemOptionsSingle<S>): SingleModuleSystem<S>;
 declare function createSystem<const Modules extends ModulesMap>(options: CreateSystemOptionsNamed<Modules>): NamespacedSystem<Modules>;
@@ -864,9 +910,15 @@ declare function createSystem<const Modules extends ModulesMap>(options: CreateS
  */
 
 /**
- * Module builder interface - provides fluent API for building modules.
+ * 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 (set after calling `.schema()`)
+ * @typeParam M - The module schema type, narrowed after calling `.schema()`.
+ * @public
  */
 interface ModuleBuilder<M extends ModuleSchema = ModuleSchema> {
     /**
@@ -961,10 +1013,47 @@ interface ResolverDef<M extends ModuleSchema> {
     }) => string;
 }
 /**
- * Create a new module builder.
+ * 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();
+ * ```
  *
- * @param id - The unique identifier for this module
- * @returns A module builder
+ * @public
  */
 declare function module$1(id: string): ModuleBuilder<ModuleSchema>;
 
@@ -1082,45 +1171,127 @@ declare function when<M extends ModuleSchema>(condition: WhenFn<M>): WhenBuilder
  * ```
  */
 
-/** Initial builder — must choose .module() or .modules() */
+/**
+ * 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 single-module system */
+/**
+ * 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 namespaced multi-module system */
+/**
+ * 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 system using the fluent builder pattern.
- * Choose `.module()` for single-module or `.modules()` for namespaced.
+ * Create a Directive system using the fluent builder pattern.
  *
- * @example
+ * 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;
 
@@ -1278,25 +1449,37 @@ declare function createSystemWithStatus<M extends ModuleSchema>(options: CreateS
  */
 
 /**
- * Generate a stable ID for a requirement.
- * Uses type + sorted properties by default.
+ * Generate a stable identity string for a requirement.
+ *
+ * When no custom key function is provided, the ID is formed from the
+ * requirement's `type` plus a deterministic JSON serialization of its
+ * remaining properties. A custom {@link RequirementKeyFn} can override
+ * this to control deduplication granularity.
+ *
+ * @param req - The requirement to generate an ID for.
+ * @param keyFn - Optional custom key function that overrides the default identity logic.
+ * @returns A stable string that uniquely identifies this requirement for deduplication.
+ *
+ * @public
  */
 declare function generateRequirementId(req: Requirement, keyFn?: RequirementKeyFn): string;
 /**
- * Helper to create typed requirements with a fluent API.
+ * Create a typed requirement factory for a given requirement type string.
  *
- * Creates a factory function that produces requirements with a specific type.
- * Useful for creating requirements in constraint definitions.
+ * Returns a function that, when called with a properties object, produces a
+ * fully-typed {@link Requirement} whose `type` field is the literal `T`.
+ * This is the recommended way to build requirements inside constraint
+ * definitions because it keeps the type string in one place and gives you
+ * full TypeScript inference on the payload.
  *
- * @param type - The requirement type string
- * @returns A factory function that creates requirements with the given type
+ * @param type - The requirement type string (e.g. `"FETCH_USER"`).
+ * @returns A factory that merges `type` with arbitrary properties into a typed requirement.
  *
  * @example
  * ```typescript
- * // Create a requirement factory
  * const fetchUser = req("FETCH_USER");
  *
- * // Use in constraint definition
+ * // Use inside a module's constraint definition
  * constraints: {
  *   needsUser: {
  *     when: (facts) => facts.userId && !facts.user,
@@ -1304,89 +1487,149 @@ declare function generateRequirementId(req: Requirement, keyFn?: RequirementKeyF
  *   },
  * }
  *
- * // Results in: { type: "FETCH_USER", userId: 123, priority: "high" }
+ * // Produces: { type: "FETCH_USER", userId: 123, priority: "high" }
  * ```
+ *
+ * @public
  */
 declare function req<T extends string>(type: T): <P extends Record<string, unknown>>(props: P) => Requirement & {
     type: T;
 } & P;
 /**
- * Check if a requirement matches a type.
+ * Type-narrowing guard that checks whether a requirement's `type` matches the
+ * given string literal.
+ *
+ * After this guard returns `true`, TypeScript narrows `req` to
+ * `Requirement & { type: T }`, giving you access to type-specific fields.
+ *
+ * @param req - The requirement to test.
+ * @param type - The expected type string to match against.
+ * @returns `true` when `req.type === type`.
+ *
+ * @public
  */
 declare function isRequirementType<T extends string>(req: Requirement, type: T): req is Requirement & {
     type: T;
 };
 /**
- * Create a type guard for resolver `requirement` predicate.
- * Cleaner alternative to writing verbose type guards.
+ * Create a type-guard function suitable for a resolver's `requirement`
+ * predicate field.
+ *
+ * @remarks
+ * The returned predicate narrows any {@link Requirement} to the concrete
+ * type `R` (or `Requirement & { type: T }` when no explicit generic is
+ * provided). This is a cleaner alternative to writing verbose inline type
+ * guards in every resolver definition.
+ *
+ * @param type - The requirement type string to match.
+ * @returns A predicate that returns `true` for requirements whose `type` matches, narrowing the value for downstream callbacks like `key` and `resolve`.
  *
  * @example
  * ```typescript
- * // With explicit requirement type (recommended for complex types)
- * interface FetchUserRequirement { type: "FETCH_USER"; userId: string }
- * requirement: forType<FetchUserRequirement>("FETCH_USER"),
- * key: (req) => req.userId,  // req is FetchUserRequirement
+ * // With an explicit requirement interface (recommended for complex payloads)
+ * interface FetchUserReq { type: "FETCH_USER"; userId: string }
+ * requirement: forType<FetchUserReq>("FETCH_USER"),
+ * key: (req) => req.userId,  // req is FetchUserReq
  *
- * // Or simple string literal (for basic types)
+ * // With a simple string literal
  * requirement: forType("FETCH_USER"),
  * key: (req) => req.type,  // req is Requirement & { type: "FETCH_USER" }
  * ```
+ *
+ * @public
  */
 declare function forType<R extends Requirement>(type: R["type"]): (req: Requirement) => req is R;
 declare function forType<T extends string>(type: T): (req: Requirement) => req is Requirement & {
     type: T;
 };
 /**
- * A set of requirements with automatic deduplication by ID.
+ * A deduplicated collection of {@link RequirementWithId} entries keyed by
+ * their identity string.
  *
- * Requirements are uniquely identified by their ID (generated from type + properties).
- * When adding a requirement with a duplicate ID, the first one wins.
+ * @remarks
+ * Requirements are uniquely identified by their ID (generated from type +
+ * properties via {@link generateRequirementId}). When adding a requirement
+ * whose ID already exists, the first entry wins and the duplicate is
+ * silently ignored. The {@link RequirementSet.diff | diff} method computes
+ * added, removed, and unchanged entries relative to another set, which the
+ * engine uses during reconciliation.
  *
  * @example
  * ```typescript
  * const set = new RequirementSet();
- *
- * // Add requirements
- * set.add(createRequirementWithId({ type: "FETCH_USER", userId: 1 }, "constraint1"));
- * set.add(createRequirementWithId({ type: "FETCH_USER", userId: 1 }, "constraint2")); // Ignored (duplicate)
- *
- * // Check and retrieve
+ * set.add(createRequirementWithId({ type: "FETCH_USER", userId: 1 }, "c1"));
+ * set.add(createRequirementWithId({ type: "FETCH_USER", userId: 1 }, "c2")); // ignored
  * console.log(set.size); // 1
- * console.log(set.has("FETCH_USER:{\"userId\":1}")); // true
- *
- * // Diff with another set
- * const newSet = new RequirementSet();
- * newSet.add(createRequirementWithId({ type: "FETCH_USER", userId: 2 }, "constraint1"));
- * const { added, removed } = newSet.diff(set);
- * // added: [{ type: "FETCH_USER", userId: 2 }]
- * // removed: [{ type: "FETCH_USER", userId: 1 }]
+ *
+ * const next = new RequirementSet();
+ * next.add(createRequirementWithId({ type: "FETCH_USER", userId: 2 }, "c1"));
+ * const { added, removed } = next.diff(set);
+ * // added has userId: 2, removed has userId: 1
  * ```
+ *
+ * @public
  */
 declare class RequirementSet {
     private map;
     /**
-     * Add a requirement to the set.
-     * If a requirement with the same ID already exists, it is ignored (first wins).
-     * @param req - The requirement with its computed ID
+     * Add a requirement to the set (first-wins deduplication).
+     *
+     * @param req - The requirement with its computed ID to insert.
      */
     add(req: RequirementWithId): void;
-    /** Remove a requirement by ID */
+    /**
+     * Remove a requirement by its identity string.
+     *
+     * @param id - The requirement identity string to remove.
+     * @returns `true` if the requirement existed and was removed.
+     */
     remove(id: string): boolean;
-    /** Check if a requirement exists */
+    /**
+     * Check whether a requirement with the given ID is in the set.
+     *
+     * @param id - The requirement identity string to look up.
+     * @returns `true` if the set contains a requirement with this ID.
+     */
     has(id: string): boolean;
-    /** Get a requirement by ID */
+    /**
+     * Retrieve a requirement by its identity string.
+     *
+     * @param id - The requirement identity string to look up.
+     * @returns The matching requirement, or `undefined` if not found.
+     */
     get(id: string): RequirementWithId | undefined;
-    /** Get all requirements */
+    /**
+     * Return a snapshot array of all requirements in the set.
+     *
+     * @returns A new array containing every {@link RequirementWithId} in insertion order.
+     */
     all(): RequirementWithId[];
-    /** Get all requirement IDs */
+    /**
+     * Return a snapshot array of all requirement identity strings.
+     *
+     * @returns A new array of ID strings in insertion order.
+     */
     ids(): string[];
-    /** Get the count of requirements */
+    /**
+     * The number of requirements currently in the set.
+     */
     get size(): number;
-    /** Clear all requirements */
+    /**
+     * Remove all requirements from the set.
+     */
     clear(): void;
-    /** Create a copy */
+    /**
+     * Create a shallow copy of this set.
+     *
+     * @returns A new {@link RequirementSet} containing the same entries.
+     */
     clone(): RequirementSet;
-    /** Diff with another set - returns added and removed */
+    /**
+     * Compute the difference between this set and another.
+     *
+     * @param other - The previous set to compare against.
+     * @returns An object with `added` (in this but not other), `removed` (in other but not this), and `unchanged` arrays.
+     */
     diff(other: RequirementSet): {
         added: RequirementWithId[];
         removed: RequirementWithId[];
@@ -1491,44 +1734,126 @@ declare function createDerivationsManager<S extends Schema, D extends Derivation
  * ```
  */
 
+/**
+ * Manager returned by {@link createEffectsManager} that runs fire-and-forget
+ * side effects after facts stabilize.
+ *
+ * @internal
+ */
 interface EffectsManager<_S extends Schema = Schema> {
-    /** Run all effects that should trigger based on changes */
+    /**
+     * Run all effects whose tracked dependencies overlap with `changedKeys`.
+     *
+     * @remarks
+     * Effects with no recorded dependencies (first run or auto-tracked with no
+     * reads) run on any change. After execution, a snapshot of current facts is
+     * stored for the `prev` parameter on the next invocation.
+     *
+     * @param changedKeys - Fact keys that changed since the last run.
+     */
     runEffects(changedKeys: Set<string>): Promise<void>;
-    /** Run all effects unconditionally */
+    /**
+     * Run every enabled effect unconditionally, regardless of dependencies.
+     */
     runAll(): Promise<void>;
-    /** Disable an effect */
+    /**
+     * Disable an effect so it is skipped during subsequent runs.
+     *
+     * @param id - The effect definition ID.
+     */
     disable(id: string): void;
-    /** Enable an effect */
+    /**
+     * Re-enable a previously disabled effect.
+     *
+     * @param id - The effect definition ID.
+     */
     enable(id: string): void;
-    /** Check if an effect is enabled */
+    /**
+     * Check whether an effect is currently enabled.
+     *
+     * @param id - The effect definition ID.
+     * @returns `true` if the effect has not been disabled.
+     */
     isEnabled(id: string): boolean;
-    /** Run all stored cleanup functions (called on system stop/destroy) */
+    /**
+     * Invoke every stored cleanup function and mark the manager as stopped.
+     *
+     * @remarks
+     * After this call, any cleanup functions returned by in-flight async effects
+     * will be invoked immediately rather than stored.
+     */
     cleanupAll(): void;
-    /** Register new effect definitions (for dynamic module registration) */
+    /**
+     * Register additional effect definitions at runtime (used for dynamic
+     * module registration).
+     *
+     * @param newDefs - New effect definitions to merge into the manager.
+     */
     registerDefinitions(newDefs: EffectsDef<Schema>): void;
 }
-/** Options for creating an effects manager */
+/**
+ * Configuration options accepted by {@link createEffectsManager}.
+ *
+ * @internal
+ */
 interface CreateEffectsOptions<S extends Schema> {
+    /** Effect definitions keyed by ID. */
     definitions: EffectsDef<S>;
+    /** Proxy-based facts object passed to effect `run()` functions. */
     facts: Facts<S>;
+    /** Underlying fact store used for `batch()` coalescing of mutations. */
     store: FactsStore<S>;
-    /** Callback when an effect runs (deps = the fact keys that triggered it) */
+    /** Called when an effect executes, with the fact keys that triggered it. */
     onRun?: (id: string, deps: string[]) => void;
-    /** Callback when an effect errors */
+    /** Called when an effect's `run()` or cleanup function throws. */
     onError?: (id: string, error: unknown) => void;
 }
 /**
  * Create a manager for fire-and-forget side effects that run after facts
  * stabilize.
  *
- * Effects support auto-tracked dependencies (re-tracked on every run to
- * capture conditional reads) or explicit `deps` arrays. Each effect can
- * return a cleanup function that runs before the next execution or on
- * system stop. Errors in effects are isolated and never break the
- * reconciliation loop.
+ * @remarks
+ * Effects support two dependency modes:
+ *
+ * - **Auto-tracked** (no `deps`): Dependencies are re-tracked on every run
+ *   via {@link withTracking}, so conditional fact reads are always captured.
+ *   Only synchronous reads are tracked; reads after an `await` are invisible.
+ *
+ * - **Explicit `deps`**: A fixed array of fact keys declared on the definition.
+ *   Preferred for async effects where auto-tracking cannot cross `await`
+ *   boundaries.
+ *
+ * Each effect can return a cleanup function that runs before the next
+ * execution or when {@link EffectsManager.cleanupAll | cleanupAll} is called.
+ * Errors in effects are isolated via try-catch and never break the
+ * reconciliation loop. Synchronous fact mutations inside effects are
+ * coalesced with `store.batch()`.
+ *
+ * @param options - Configuration including effect definitions, facts proxy,
+ *   store, and lifecycle callbacks.
+ * @returns An {@link EffectsManager} for running, enabling/disabling, and
+ *   cleaning up effects.
+ *
+ * @example
+ * ```typescript
+ * const effects = createEffectsManager({
+ *   definitions: {
+ *     logPhase: {
+ *       run: (facts, prev) => {
+ *         if (prev?.phase !== facts.phase) {
+ *           console.log(`Phase changed to ${facts.phase}`);
+ *         }
+ *       },
+ *     },
+ *   },
+ *   facts: factsProxy,
+ *   store: factsStore,
+ * });
+ *
+ * await effects.runEffects(new Set(["phase"]));
+ * ```
  *
- * @param options - Effect definitions, facts proxy, store, and optional lifecycle callbacks
- * @returns An `EffectsManager` with runEffects/runAll/enable/disable/cleanupAll methods
+ * @internal
  */
 declare function createEffectsManager<S extends Schema>(options: CreateEffectsOptions<S>): EffectsManager<S>;
 
@@ -1542,54 +1867,155 @@ declare function createEffectsManager<S extends Schema>(options: CreateEffectsOp
  * - Error isolation
  */
 
+/**
+ * Manager returned by {@link createConstraintsManager} that evaluates
+ * constraint rules against the current facts and produces unmet
+ * {@link RequirementWithId | requirements}.
+ *
+ * @internal
+ */
 interface ConstraintsManager<_S extends Schema> {
-    /** Evaluate all constraints and return unmet requirements */
+    /**
+     * Evaluate all enabled constraints and return unmet requirements.
+     *
+     * @remarks
+     * On the first call (or when `changedKeys` is empty), every enabled
+     * constraint is evaluated. On subsequent calls, only constraints whose
+     * tracked dependencies overlap with `changedKeys` are re-evaluated.
+     * Sync constraints run first, async constraints run in parallel, and
+     * `after` ordering is respected across multiple passes.
+     *
+     * @param changedKeys - Fact keys that changed since the last evaluation.
+     *   When omitted or empty, all constraints are evaluated.
+     * @returns An array of {@link RequirementWithId} representing unmet requirements.
+     */
     evaluate(changedKeys?: Set<string>): Promise<RequirementWithId[]>;
-    /** Get the current state of a constraint */
+    /**
+     * Get the current state of a constraint by its definition ID.
+     *
+     * @param id - The constraint definition ID.
+     * @returns The {@link ConstraintState}, or `undefined` if the ID is unknown.
+     */
     getState(id: string): ConstraintState | undefined;
-    /** Get all constraint states */
+    /**
+     * Get the state of every registered constraint.
+     *
+     * @returns An array of all {@link ConstraintState} objects.
+     */
     getAllStates(): ConstraintState[];
-    /** Disable a constraint */
+    /**
+     * Disable a constraint so it is skipped during evaluation.
+     *
+     * @param id - The constraint definition ID.
+     */
     disable(id: string): void;
-    /** Enable a constraint */
+    /**
+     * Re-enable a previously disabled constraint.
+     *
+     * @param id - The constraint definition ID.
+     */
     enable(id: string): void;
-    /** Invalidate constraints that depend on the given fact key */
+    /**
+     * Mark all constraints that depend on `factKey` as dirty so they are
+     * re-evaluated on the next {@link ConstraintsManager.evaluate | evaluate} call.
+     *
+     * @param factKey - The fact store key that changed.
+     */
     invalidate(factKey: string): void;
-    /** Get the tracked dependencies for a constraint */
+    /**
+     * Get the auto-tracked or explicit dependency set for a constraint.
+     *
+     * @param id - The constraint definition ID.
+     * @returns A `Set` of fact keys, or `undefined` if no dependencies have been recorded.
+     */
     getDependencies(id: string): Set<string> | undefined;
-    /** Mark a constraint's resolver as completed (for `after` ordering) */
+    /**
+     * Record that a constraint's resolver completed successfully, unblocking
+     * any constraints that list it in their `after` array.
+     *
+     * @param constraintId - The constraint definition ID whose resolver finished.
+     */
     markResolved(constraintId: string): void;
-    /** Check if a constraint is currently disabled */
+    /**
+     * Check whether a constraint is currently disabled.
+     *
+     * @param id - The constraint definition ID.
+     * @returns `true` if the constraint has been disabled via {@link ConstraintsManager.disable | disable}.
+     */
     isDisabled(id: string): boolean;
-    /** Check if a constraint has been resolved (for `after` ordering) */
+    /**
+     * Check whether a constraint has been marked as resolved.
+     *
+     * @param constraintId - The constraint definition ID.
+     * @returns `true` if {@link ConstraintsManager.markResolved | markResolved} was called for this constraint.
+     */
     isResolved(constraintId: string): boolean;
-    /** Register new constraint definitions (for dynamic module registration) */
+    /**
+     * Register additional constraint definitions at runtime (used for dynamic
+     * module registration).
+     *
+     * @remarks
+     * Rebuilds the topological order and reverse dependency map so new `after`
+     * dependencies are validated for cycles and indexed.
+     *
+     * @param newDefs - New constraint definitions to merge into the manager.
+     */
     registerDefinitions(newDefs: ConstraintsDef<Schema>): void;
 }
-/** Options for creating a constraints manager */
+/**
+ * Configuration options accepted by {@link createConstraintsManager}.
+ *
+ * @internal
+ */
 interface CreateConstraintsOptions<S extends Schema> {
+    /** Constraint definitions keyed by ID. */
     definitions: ConstraintsDef<S>;
+    /** Proxy-based facts object used to evaluate `when()` predicates. */
     facts: Facts<S>;
-    /** Custom key functions for requirements (by constraint ID) */
+    /** Custom key functions for requirement deduplication, keyed by constraint ID. */
     requirementKeys?: Record<string, RequirementKeyFn>;
-    /** Default timeout for async constraints (ms) */
+    /** Default timeout in milliseconds for async constraint evaluation (defaults to 5 000). */
     defaultTimeout?: number;
-    /** Callback when a constraint is evaluated */
+    /** Called after each constraint evaluation with the constraint ID and whether `when()` was active. */
     onEvaluate?: (id: string, active: boolean) => void;
-    /** Callback when a constraint errors */
+    /** Called when a constraint's `when()` or `require()` throws. */
     onError?: (id: string, error: unknown) => void;
 }
 /**
  * Create a manager that evaluates constraint rules and produces unmet
  * requirements.
  *
- * Constraints are evaluated in priority order (higher first), with
+ * @remarks
+ * Constraints are evaluated in priority order (higher priority first), with
  * topological ordering for same-priority constraints connected by `after`
- * dependencies. Supports sync and async `when()` predicates, incremental
- * evaluation based on changed fact keys, and per-constraint enable/disable.
+ * dependencies. The manager supports sync and async `when()` predicates,
+ * incremental evaluation based on changed fact keys, and per-constraint
+ * enable/disable toggling. Cycle detection runs eagerly at construction time
+ * to prevent deadlocks in production.
+ *
+ * @param options - Configuration including constraint definitions, facts proxy,
+ *   custom requirement key functions, and lifecycle callbacks.
+ * @returns A {@link ConstraintsManager} for evaluating, invalidating, and
+ *   managing constraint lifecycle.
+ *
+ * @example
+ * ```typescript
+ * const constraints = createConstraintsManager({
+ *   definitions: {
+ *     mustTransition: {
+ *       priority: 50,
+ *       when: (facts) => facts.phase === "red" && facts.elapsed > 30,
+ *       require: { type: "TRANSITION", to: "green" },
+ *     },
+ *   },
+ *   facts: factsProxy,
+ *   onEvaluate: (id, active) => console.log(id, active),
+ * });
  *
- * @param options - Constraint definitions, facts proxy, custom requirement key functions, and lifecycle callbacks
- * @returns A `ConstraintsManager` with evaluate/invalidate/enable/disable/markResolved methods
+ * const unmet = await constraints.evaluate();
+ * ```
+ *
+ * @internal
  */
 declare function createConstraintsManager<S extends Schema>(options: CreateConstraintsOptions<S>): ConstraintsManager<S>;
 
@@ -1604,62 +2030,171 @@ declare function createConstraintsManager<S extends Schema>(options: CreateConst
  * - Cancellation via AbortController
  */
 
-/** Inflight resolver info */
+/**
+ * Summary of a resolver that is currently in flight.
+ *
+ * @internal
+ */
 interface InflightInfo {
+    /** The unique requirement ID being resolved. */
     id: string;
+    /** The definition ID of the resolver handling this requirement. */
     resolverId: string;
+    /** Epoch timestamp (ms) when resolution started. */
     startedAt: number;
 }
+/**
+ * Manager returned by {@link createResolversManager} that matches
+ * requirements to resolver handlers and manages their execution lifecycle.
+ *
+ * @internal
+ */
 interface ResolversManager<_S extends Schema> {
-    /** Start resolving a requirement */
+    /**
+     * Start resolving a requirement by matching it to a resolver handler.
+     *
+     * @remarks
+     * Duplicate in-flight requirements (same `req.id`) are silently ignored.
+     * If the matched resolver has `batch.enabled`, the requirement is queued
+     * for batch processing instead of being resolved immediately.
+     *
+     * @param req - The requirement (with a stable identity ID) to resolve.
+     */
     resolve(req: RequirementWithId): void;
-    /** Cancel a resolver by requirement ID */
+    /**
+     * Cancel an in-flight or batch-queued resolver by requirement ID.
+     *
+     * @remarks
+     * Aborts the `AbortController` for in-flight resolvers. For batch-queued
+     * requirements, removes the requirement from the pending batch.
+     *
+     * @param requirementId - The unique requirement ID to cancel.
+     */
     cancel(requirementId: string): void;
-    /** Cancel all inflight resolvers */
+    /**
+     * Cancel every in-flight resolver and flush all pending batch queues.
+     */
     cancelAll(): void;
-    /** Get status of a resolver by requirement ID */
+    /**
+     * Get the current status of a resolver by requirement ID.
+     *
+     * @param requirementId - The unique requirement ID to look up.
+     * @returns The {@link ResolverStatus} (idle, pending, running, success, error, or canceled).
+     */
     getStatus(requirementId: string): ResolverStatus;
-    /** Get all inflight requirement IDs */
+    /**
+     * Get the requirement IDs of all currently in-flight resolvers.
+     *
+     * @returns An array of requirement ID strings.
+     */
     getInflight(): string[];
-    /** Get full info for all inflight resolvers */
+    /**
+     * Get detailed info for every in-flight resolver.
+     *
+     * @returns An array of {@link InflightInfo} objects.
+     */
     getInflightInfo(): InflightInfo[];
-    /** Check if a requirement is being resolved */
+    /**
+     * Check whether a requirement is currently being resolved.
+     *
+     * @param requirementId - The unique requirement ID to check.
+     * @returns `true` if the requirement has an active in-flight resolver.
+     */
     isResolving(requirementId: string): boolean;
-    /** Process batched requirements (called periodically) */
+    /**
+     * Immediately flush all pending batch queues, executing their resolvers.
+     */
     processBatches(): void;
-    /** Register new resolver definitions (for dynamic module registration) */
+    /**
+     * Check whether any batch queues have requirements waiting to be processed.
+     *
+     * @returns `true` if at least one batch queue is non-empty.
+     */
+    hasPendingBatches(): boolean;
+    /**
+     * Register additional resolver definitions at runtime (used for dynamic
+     * module registration).
+     *
+     * @remarks
+     * Clears the resolver-by-type cache so newly registered resolvers are
+     * discoverable on the next {@link ResolversManager.resolve | resolve} call.
+     *
+     * @param newDefs - New resolver definitions to merge into the manager.
+     */
     registerDefinitions(newDefs: ResolversDef<Schema>): void;
 }
-/** Options for creating a resolvers manager */
+/**
+ * Configuration options accepted by {@link createResolversManager}.
+ *
+ * @internal
+ */
 interface CreateResolversOptions<S extends Schema> {
+    /** Resolver definitions keyed by ID. */
     definitions: ResolversDef<S>;
+    /** Proxy-based facts object passed to resolver contexts. */
     facts: Facts<S>;
+    /** Underlying fact store used for `batch()` coalescing of mutations. */
     store: FactsStore<S>;
-    /** Callback when a resolver starts */
+    /** Called when a resolver begins execution. */
     onStart?: (resolver: string, req: RequirementWithId) => void;
-    /** Callback when a resolver completes */
+    /** Called when a resolver completes successfully, with the wall-clock duration in ms. */
     onComplete?: (resolver: string, req: RequirementWithId, duration: number) => void;
-    /** Callback when a resolver errors */
+    /** Called when a resolver exhausts all retry attempts. */
     onError?: (resolver: string, req: RequirementWithId, error: unknown) => void;
-    /** Callback when a resolver retries */
+    /** Called before each retry attempt with the upcoming attempt number. */
     onRetry?: (resolver: string, req: RequirementWithId, attempt: number) => void;
-    /** Callback when a resolver is canceled */
+    /** Called when a resolver is canceled via {@link ResolversManager.cancel | cancel}. */
     onCancel?: (resolver: string, req: RequirementWithId) => void;
-    /** Callback when resolution cycle completes (for reconciliation) */
+    /** Called after any resolver finishes (success, error, or batch completion) to trigger reconciliation. */
     onResolutionComplete?: () => void;
 }
 /**
  * Create a manager that fulfills requirements by matching them to resolver
  * handlers.
  *
- * Resolvers are matched by requirement type (string or predicate). Each
- * resolution runs with an `AbortController` for cancellation, configurable
- * retry policies (none/linear/exponential backoff), and optional batching
- * for grouping similar requirements. Duplicate in-flight requirements are
- * automatically deduplicated.
+ * @remarks
+ * Resolvers are matched by requirement type (string equality) or a predicate
+ * function. Each resolution runs with an `AbortController` for cancellation
+ * and configurable retry policies (none, linear, or exponential backoff).
+ *
+ * **Batching:** When a resolver sets `batch.enabled`, incoming requirements
+ * are queued and flushed either when `batch.maxSize` is reached or after
+ * `batch.windowMs` elapses, whichever comes first. Batch resolvers can use
+ * `resolveBatch` (all-or-nothing) or `resolveBatchWithResults` (per-item
+ * success/failure). If only `resolve` is provided with batching enabled, the
+ * manager falls back to individual resolution calls.
+ *
+ * Duplicate in-flight requirements (same requirement ID) are automatically
+ * deduplicated. Resolver-by-type lookups are cached with FIFO eviction at
+ * 1 000 entries to handle dynamic requirement types.
+ *
+ * @param options - Configuration including resolver definitions, facts proxy,
+ *   store, and lifecycle callbacks.
+ * @returns A {@link ResolversManager} for dispatching, canceling, and
+ *   inspecting requirement resolution.
+ *
+ * @example
+ * ```typescript
+ * const resolvers = createResolversManager({
+ *   definitions: {
+ *     transition: {
+ *       requirement: "TRANSITION",
+ *       retry: { attempts: 3, backoff: "exponential" },
+ *       resolve: async (req, context) => {
+ *         context.facts.phase = req.to;
+ *         context.facts.elapsed = 0;
+ *       },
+ *     },
+ *   },
+ *   facts: factsProxy,
+ *   store: factsStore,
+ *   onComplete: (id, req, ms) => console.log(`${id} resolved in ${ms}ms`),
+ * });
+ *
+ * resolvers.resolve(requirementWithId);
+ * ```
  *
- * @param options - Resolver definitions, facts proxy, store, and lifecycle callbacks (onStart/onComplete/onError/onRetry/onCancel/onResolutionComplete)
- * @returns A `ResolversManager` with resolve/cancel/cancelAll/getStatus/processBatches methods
+ * @internal
  */
 declare function createResolversManager<S extends Schema>(options: CreateResolversOptions<S>): ResolversManager<S>;
 
@@ -1672,6 +2207,35 @@ declare function createResolversManager<S extends Schema>(options: CreateResolve
  * - Plugins execute in registration order
  */
 
+/**
+ * Internal manager that broadcasts lifecycle events to registered {@link Plugin} instances.
+ *
+ * @remarks
+ * PluginManager uses `Schema` (flat) internally because the engine works with
+ * flat schemas. The public API uses `ModuleSchema` (consolidated), and the
+ * conversion happens in `createSystem`.
+ *
+ * Plugins execute in registration order. All hook invocations are wrapped in
+ * try-catch so a misbehaving plugin never breaks the engine. Duplicate plugin
+ * names are detected and the older registration is replaced with a warning.
+ *
+ * Lifecycle hook categories:
+ * - **System lifecycle:** `emitInit`, `emitStart`, `emitStop`, `emitDestroy`
+ * - **Facts:** `emitFactSet`, `emitFactDelete`, `emitFactsBatch`
+ * - **Derivations:** `emitDerivationCompute`, `emitDerivationInvalidate`
+ * - **Reconciliation:** `emitReconcileStart`, `emitReconcileEnd`
+ * - **Constraints:** `emitConstraintEvaluate`, `emitConstraintError`
+ * - **Requirements:** `emitRequirementCreated`, `emitRequirementMet`, `emitRequirementCanceled`
+ * - **Resolvers:** `emitResolverStart`, `emitResolverComplete`, `emitResolverError`, `emitResolverRetry`, `emitResolverCancel`
+ * - **Effects:** `emitEffectRun`, `emitEffectError`
+ * - **Time-travel:** `emitSnapshot`, `emitTimeTravel`
+ * - **Errors:** `emitError`, `emitErrorRecovery`
+ * - **Run history:** `emitRunComplete`
+ *
+ * @typeParam _S - The flat schema type (unused at runtime).
+ *
+ * @internal
+ */
 interface PluginManager<_S extends Schema = any> {
     /** Register a plugin */
     register(plugin: Plugin<any>): void;
@@ -1709,14 +2273,17 @@ interface PluginManager<_S extends Schema = any> {
     emitRunComplete(run: RunChangelogEntry): void;
 }
 /**
- * Create a manager that broadcasts lifecycle events to registered plugins.
+ * Create a {@link PluginManager} that broadcasts lifecycle events to registered plugins.
  *
- * Plugins are called in registration order. All hook invocations are
- * wrapped in try-catch so a misbehaving plugin never breaks the engine.
- * Duplicate plugin names are detected and the older registration is
- * replaced with a warning.
+ * @remarks
+ * Plugins are called in registration order. All hook invocations are wrapped
+ * in try-catch so a misbehaving plugin never breaks the engine. Duplicate
+ * plugin names are detected and the older registration is replaced with a
+ * console warning.
  *
- * @returns A `PluginManager` with register/unregister/getPlugins and emit* methods for every lifecycle event
+ * @returns A {@link PluginManager} with `register`/`unregister`/`getPlugins` and `emit*` methods for every lifecycle event.
+ *
+ * @internal
  */
 declare function createPluginManager<S extends Schema = any>(): PluginManager<S>;
 
@@ -1731,7 +2298,9 @@ declare function createPluginManager<S extends Schema = any>(): PluginManager<S>
  */
 
 /**
- * Pending retry entry.
+ * A queued retry entry tracking its source, attempt count, and scheduled time.
+ *
+ * @internal
  */
 interface PendingRetry {
     source: ErrorSource;
@@ -1744,13 +2313,18 @@ interface PendingRetry {
 /**
  * Create a manager for deferred retry scheduling with exponential backoff.
  *
- * Retries are stored in a Map keyed by source ID. Each retry tracks its
- * attempt number and next retry time. When `processDueRetries()` is called
- * (typically during reconciliation), entries whose time has elapsed are
- * returned and removed from the queue.
+ * @remarks
+ * Retries are stored in a Map keyed by source ID. Each entry tracks its
+ * attempt number and the timestamp of the next eligible retry. When
+ * {@link createRetryLaterManager | processDueRetries} is called (typically
+ * during reconciliation), entries whose scheduled time has elapsed are
+ * returned and removed from the queue. The delay grows exponentially:
+ * `delayMs * backoffMultiplier^(attempt - 1)`, capped at `maxDelayMs`.
  *
- * @param config - Backoff configuration: `delayMs`, `maxRetries`, `backoffMultiplier`, `maxDelayMs`
- * @returns A manager with `scheduleRetry`, `getPendingRetries`, `processDueRetries`, `cancelRetry`, and `clearAll` methods
+ * @param config - Backoff configuration including `delayMs`, `maxRetries`, `backoffMultiplier`, and `maxDelayMs`.
+ * @returns A manager exposing `scheduleRetry`, `getPendingRetries`, `processDueRetries`, `cancelRetry`, and `clearAll` methods.
+ *
+ * @internal
  */
 declare function createRetryLaterManager(config?: RetryLaterConfig): {
     /** Schedule a retry */
@@ -1764,57 +2338,92 @@ declare function createRetryLaterManager(config?: RetryLaterConfig): {
     /** Clear all pending retries */
     clearAll: () => void;
 };
+/**
+ * Handle returned by {@link createErrorBoundaryManager} for routing errors
+ * through configurable recovery strategies.
+ *
+ * @internal
+ */
 interface ErrorBoundaryManager {
-    /** Handle an error from a specific source */
+    /**
+     * Route an error through the configured recovery strategy for its source.
+     *
+     * @param source - The subsystem that produced the error.
+     * @param sourceId - Identifier of the specific constraint, resolver, effect, or derivation.
+     * @param error - The thrown value (coerced to {@link DirectiveError} internally).
+     * @param context - Optional context forwarded to callbacks and retry entries.
+     * @returns The {@link RecoveryStrategy} that was applied.
+     */
     handleError(source: ErrorSource, sourceId: string, error: unknown, context?: unknown): RecoveryStrategy;
-    /** Get the last error */
+    /**
+     * Return the most recently recorded error, or `null` if none exist.
+     *
+     * @returns The last {@link DirectiveError}, or `null`.
+     */
     getLastError(): DirectiveError | null;
-    /** Get all errors */
+    /**
+     * Return a snapshot array of all recorded errors (up to the last 100).
+     *
+     * @returns A shallow copy of the internal error ring buffer.
+     */
     getAllErrors(): DirectiveError[];
-    /** Clear all errors */
+    /** Clear all recorded errors. */
     clearErrors(): void;
-    /** Get retry-later manager */
+    /**
+     * Access the underlying retry-later manager for advanced scheduling.
+     *
+     * @returns The {@link createRetryLaterManager} instance used internally.
+     */
     getRetryLaterManager(): ReturnType<typeof createRetryLaterManager>;
-    /** Process due retries (call periodically or on reconcile) */
+    /**
+     * Drain and return retry entries whose scheduled time has elapsed.
+     *
+     * @returns An array of {@link PendingRetry} entries that are now due.
+     */
     processDueRetries(): PendingRetry[];
-    /** Clear retry attempts for a source ID (call on success) */
+    /**
+     * Reset retry attempt tracking for a source, typically after a successful resolution.
+     *
+     * @param sourceId - The source identifier whose retry counter should be cleared.
+     */
     clearRetryAttempts(sourceId: string): void;
 }
-/** Options for creating an error boundary manager */
+/**
+ * Options accepted by {@link createErrorBoundaryManager}.
+ *
+ * @internal
+ */
 interface CreateErrorBoundaryOptions {
+    /** Per-source recovery strategies and retry-later tuning. */
     config?: ErrorBoundaryConfig;
-    /** Callback when an error occurs */
+    /** Invoked every time an error is recorded, before the recovery strategy runs. */
     onError?: (error: DirectiveError) => void;
-    /** Callback when recovery is attempted */
+    /** Invoked after a recovery strategy has been selected for an error. */
     onRecovery?: (error: DirectiveError, strategy: RecoveryStrategy) => void;
 }
 /**
  * Create a manager that handles errors from constraints, resolvers, effects,
  * and derivations with configurable per-source recovery strategies.
  *
- * Supported strategies: `"skip"` (ignore), `"retry"` (immediate),
- * `"retry-later"` (deferred with backoff), `"disable"` (turn off source),
- * and `"throw"` (re-throw). Recent errors are kept in a ring buffer
- * (last 100) for inspection. The retry-later strategy delegates to an
- * internal {@link createRetryLaterManager}.
+ * @remarks
+ * Five recovery strategies are available:
  *
- * @param options - Error boundary configuration, plus `onError` and `onRecovery` callbacks for plugin integration
- * @returns An `ErrorBoundaryManager` with handleError/getLastError/getAllErrors/clearErrors/processDueRetries methods
+ * - `"skip"` -- Swallow the error and continue.
+ * - `"retry"` -- Signal the caller to retry immediately.
+ * - `"retry-later"` -- Enqueue a deferred retry with exponential backoff
+ *   (delegated to an internal {@link createRetryLaterManager}).
+ * - `"disable"` -- Permanently disable the failing source.
+ * - `"throw"` -- Re-throw the error as a {@link DirectiveError}.
  *
- * @example
- * ```ts
- * const boundary = createErrorBoundaryManager({
- *   config: {
- *     onResolverError: "retry-later",
- *     onEffectError: "skip",
- *     retryLater: { maxRetries: 5, delayMs: 500 },
- *   },
- *   onError: (err) => console.error(err.source, err.message),
- * });
+ * Recent errors are kept in a ring buffer (last 100) for inspection via
+ * {@link ErrorBoundaryManager.getAllErrors | getAllErrors}. Each strategy
+ * can be configured per source type (`onConstraintError`, `onResolverError`,
+ * etc.) or as a callback that dynamically selects a strategy.
  *
- * const strategy = boundary.handleError("resolver", "fetchUser", new Error("timeout"));
- * // strategy === "retry-later"
- * ```
+ * @param options - Error boundary configuration, plus `onError` and `onRecovery` callbacks for plugin integration.
+ * @returns An {@link ErrorBoundaryManager} for routing errors through the configured strategies.
+ *
+ * @internal
  */
 declare function createErrorBoundaryManager(options?: CreateErrorBoundaryOptions): ErrorBoundaryManager;
 
@@ -1828,6 +2437,23 @@ declare function createErrorBoundaryManager(options?: CreateErrorBoundaryOptions
  * - Export/import state history
  */
 
+/**
+ * Internal time-travel manager that extends the public {@link TimeTravelAPI}
+ * with snapshot capture, restoration, and pause/resume controls.
+ *
+ * @remarks
+ * - `takeSnapshot(trigger)` records the current facts into the ring buffer.
+ * - `restore(snapshot)` deserializes a snapshot back into the facts store,
+ *   setting `isRestoring = true` so the engine skips reconciliation.
+ * - `pause()` / `resume()` temporarily suspend snapshot recording (e.g.,
+ *   during bulk imports or programmatic state resets).
+ * - `beginChangeset(label)` / `endChangeset()` group consecutive snapshots
+ *   so `goBack`/`goForward` treat them as a single undo/redo unit.
+ *
+ * @typeParam _S - The schema type (unused at runtime but preserved for type safety).
+ *
+ * @internal
+ */
 interface TimeTravelManager<_S extends Schema> extends TimeTravelAPI {
     /** Take a snapshot of current state */
     takeSnapshot(trigger: string): Snapshot;
@@ -1842,7 +2468,13 @@ interface TimeTravelManager<_S extends Schema> extends TimeTravelAPI {
     /** Resume snapshot taking */
     resume(): void;
 }
-/** Options for creating a time-travel manager */
+/**
+ * Options for creating a time-travel manager via {@link createTimeTravelManager}.
+ *
+ * @typeParam S - The facts schema type.
+ *
+ * @internal
+ */
 interface CreateTimeTravelOptions<S extends Schema> {
     config: DebugConfig;
     facts: Facts<S>;
@@ -1853,24 +2485,35 @@ interface CreateTimeTravelOptions<S extends Schema> {
     onTimeTravel?: (from: number, to: number) => void;
 }
 /**
- * Create a snapshot-based time-travel debugger with a ring buffer of state
- * history.
+ * Create a snapshot-based time-travel debugger backed by a ring buffer.
  *
- * Snapshots are taken automatically after fact changes (during
- * reconciliation) and can be navigated with `goBack`/`goForward`/`goTo`.
- * Changesets group multiple snapshots into a single undo/redo unit.
- * The entire history can be exported to JSON and re-imported for
- * cross-session debugging.
+ * @remarks
+ * Snapshots are taken automatically after fact changes (during reconciliation)
+ * and can be navigated with `goBack`/`goForward`/`goTo`. Use
+ * `beginChangeset(label)` and `endChangeset()` to group multiple snapshots
+ * into a single undo/redo unit. The entire history can be exported to JSON
+ * via `export()` and re-imported with `import()` for cross-session debugging.
  *
- * @param options - Debug config (maxSnapshots, timeTravel flag), facts proxy, store, and snapshot/time-travel callbacks
- * @returns A `TimeTravelManager` with takeSnapshot/restore/goBack/goForward/goTo/replay/export/import and changeset methods
+ * 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.
+ *
+ * @internal
  */
 declare function createTimeTravelManager<S extends Schema>(options: CreateTimeTravelOptions<S>): TimeTravelManager<S>;
 /**
- * Create a no-op time-travel manager used when `debug.timeTravel` is
- * disabled. All methods are safe to call but perform no work.
+ * Create a no-op time-travel manager for use when `debug.timeTravel` 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.
  *
- * @returns A `TimeTravelManager` where every method is a no-op and `isEnabled` is `false`
+ * @returns A {@link TimeTravelManager} where every method is a no-op and `isEnabled` is `false`.
+ *
+ * @internal
  */
 declare function createDisabledTimeTravel<S extends Schema>(): TimeTravelManager<S>;
 
@@ -1890,12 +2533,13 @@ declare function createDisabledTimeTravel<S extends Schema>(): TimeTravelManager
  * effects, constraints, resolvers, plugins, error boundaries, and time-travel
  * into a single reactive system.
  *
- * This is the internal factory used by `createSystem`. Most users should call
- * `createSystem` instead, which provides a friendlier API and handles module
- * composition.
+ * @remarks
+ * This is the internal factory used by {@link createSystem}. Most users should
+ * call `createSystem` instead, which provides a friendlier API and handles
+ * module composition.
  *
- * @param config - Full system configuration: modules, plugins, error boundary settings, and debug options
- * @returns A `System` instance with facts, derive, events, dispatch, subscribe, watch, settle, and lifecycle methods
+ * @param config - Full system configuration including modules, plugins, error boundary settings, and debug options
+ * @returns A {@link System} instance with facts, derive, events, dispatch, subscribe, watch, settle, and lifecycle methods
  *
  * @example
  * ```ts
@@ -1911,6 +2555,8 @@ declare function createDisabledTimeTravel<S extends Schema>(): TimeTravelManager
  * system.start();
  * system.facts.count = 42;
  * ```
+ *
+ * @internal
  */
 declare function createEngine<S extends Schema>(config: SystemConfig<any>): System<any>;