@directive-run/core 0.8.1 → 0.8.3

package/dist/internals.d.cts

@@ -0,0 +1,1176 @@
+import { Q as Schema, F as Facts, a1 as FactsStore, E as EffectsDef, a2 as ConstraintsDef, p as RequirementKeyFn, R as RequirementWithId, a3 as ConstraintState, a4 as ResolversDef, a5 as ResolverStatus, o as Requirement, P as Plugin, V as System, a6 as FactChange, v as FactsSnapshot, a7 as ReconcileResult, U as Snapshot, D as DirectiveError, a8 as RecoveryStrategy, _ as TraceEntry, a9 as ErrorSource, n as ErrorBoundaryConfig, aa as RetryLaterConfig, H as HistoryAPI, w as HistoryOption, W as SystemConfig } from './plugins-Bg_oq2sO.cjs';
+export { ab as BatchItemResult, ac as BatchResolveResults, ad as ConstraintsControl, ae as CrossModuleConstraintDef, g as CrossModuleConstraintsDef, af as CrossModuleDerivationFn, e as CrossModuleDerivationsDef, ag as CrossModuleEffectDef, f as CrossModuleEffectsDef, ah as CrossModuleFactsWithSelf, ai as DerivationKeys, aj as DerivationReturnType, ak as DerivationsControl, al as DerivationsSchema, am as DeriveAccessor, an as DispatchEventsFromSchema, q as DistributableSnapshot, r as DistributableSnapshotOptions, ao as EffectCleanup, ap as EffectsControl, aq as EventPayloadSchema, ar as EventsAccessor, as as EventsAccessorFromSchema, at as EventsDef, au as EventsSchema, av as FactKeys, aw as FactReturnType, ax as FlexibleEventHandler, ay as HistoryConfig, az as InferEventPayloadFromSchema, aA as InferRequirementPayloadFromSchema, aB as InferSchema, aC as MutableNamespacedFacts, aD as NamespacedDerivations, aE as NamespacedEventsAccessor, aF as NamespacedFacts, aG as ObservableKeys, aH as RequirementExplanation, aI as RequirementOutput, aJ as RequirementPayloadSchema, aK as RequirementsSchema, aL as ResolverContext, aM as ResolversControl, aN as SnapshotMeta, aO as SystemEvent, aP as TraceConfig, aQ as TypedConstraintDef, b as TypedConstraintsDef, T as TypedDerivationsDef, a as TypedEventsDef, aR as TypedResolverContext, aS as TypedResolverDef, c as TypedResolversDef, aT as UnionEvents } from './plugins-Bg_oq2sO.cjs';
+export { T as TypedConstraint, b as TypedResolver, c as createConstraintFactory, d as createResolverFactory } from './helpers-B6SkcKCD.cjs';
+
+/**
+ * Derivation Types - Type definitions for derivations
+ */
+
+/** Tracking context for auto-dependency detection */
+interface TrackingContext {
+    readonly isTracking: boolean;
+    track(key: string): void;
+    getDependencies(): Set<string>;
+}
+/** Derivation definition function signature. */
+interface DerivationDef<S extends Schema, T, D extends DerivationsDef<S>> {
+    (facts: Facts<S>, derived: DerivedValues<S, D>): T;
+}
+/** Map of derivation definitions. */
+type DerivationsDef<S extends Schema> = Record<string, DerivationDef<S, unknown, DerivationsDef<S>>>;
+/** Computed derived values. */
+type DerivedValues<S extends Schema, D extends DerivationsDef<S>> = {
+    readonly [K in keyof D]: ReturnType<D[K]>;
+};
+/** Internal derivation state */
+interface DerivationState<T> {
+    id: string;
+    compute: () => T;
+    cachedValue: T | undefined;
+    dependencies: Set<string>;
+    isStale: boolean;
+    isComputing: boolean;
+}
+
+/**
+ * Facts Store - Proxy-based reactive state with auto-tracking
+ *
+ * Features:
+ * - Proxy-based access (facts.phase instead of facts.get("phase"))
+ * - Automatic dependency tracking via tracking context
+ * - Batched updates with coalesced notifications
+ * - Granular subscriptions by key
+ * - Schema validation in development mode
+ */
+
+/** Options for creating a facts store */
+interface CreateFactsStoreOptions<S extends Schema> {
+    schema: S;
+    /** Validate values against schema (default: process.env.NODE_ENV !== 'production') */
+    validate?: boolean;
+    /** Throw on unknown schema keys (default: true in dev mode) */
+    strictKeys?: boolean;
+    /** Redact sensitive values in error messages */
+    redactErrors?: boolean;
+    /** Callback when facts change (for plugin hooks) */
+    onChange?: (key: string, value: unknown, prev: unknown) => void;
+    /** Callback for batch changes */
+    onBatch?: (changes: Array<{
+        key: string;
+        value: unknown;
+        prev: unknown;
+        type: "set" | "delete";
+    }>) => void;
+}
+/**
+ * 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 {@link FactsStore} with get/set/batch/subscribe methods and automatic schema validation
+ *
+ * @example
+ * ```ts
+ * const store = createFactsStore({
+ *   schema: { count: t.number(), name: t.string() },
+ * });
+ *
+ * store.set("count", 1);
+ * store.get("count"); // 1
+ *
+ * store.batch(() => {
+ *   store.set("count", 2);
+ *   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 {@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`.
+ *
+ * @param options - Same options as {@link createFactsStore}
+ * @returns An object with `store` (the reactive Map-backed store) and `facts` (the Proxy accessor)
+ *
+ * @example
+ * ```ts
+ * const { store, facts } = createFacts({
+ *   schema: { phase: t.string<"red" | "green">() },
+ * });
+ *
+ * facts.phase = "red";
+ * 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>;
+    facts: Facts<S>;
+};
+
+/**
+ * Derivations - Auto-tracked computed values with composition
+ *
+ * Features:
+ * - Automatic dependency tracking (no manual deps arrays)
+ * - Memoization with smart invalidation
+ * - Derivation composition (derivations can depend on other derivations)
+ * - Circular dependency detection
+ * - Lazy evaluation
+ */
+
+interface DerivationsManager<S extends Schema, D extends DerivationsDef<S>> {
+    /** Get a derived value (computes if stale) */
+    get<K extends keyof D>(id: K): ReturnType<D[K]>;
+    /** Check if a derivation is stale */
+    isStale(id: keyof D): boolean;
+    /** Invalidate derivations that depend on a fact key */
+    invalidate(factKey: string): void;
+    /** Invalidate derivations for multiple fact keys, notifying listeners once at the end */
+    invalidateMany(factKeys: Iterable<string>): void;
+    /** Invalidate all derivations */
+    invalidateAll(): void;
+    /** Subscribe to derivation changes */
+    subscribe(ids: Array<keyof D>, listener: () => void): () => void;
+    /** Get the proxy for composition */
+    getProxy(): DerivedValues<S, D>;
+    /** Get dependencies for a derivation */
+    getDependencies(id: keyof D): Set<string>;
+    /** Register new derivation definitions (for dynamic module registration) */
+    registerDefinitions(newDefs: DerivationsDef<S>): void;
+    /** Override an existing derivation function */
+    assignDefinition(id: string, fn: DerivationsDef<S>[keyof DerivationsDef<S>]): void;
+    /** Remove a derivation and clean up its state */
+    unregisterDefinition(id: string): void;
+    /** Compute a derivation immediately (ignores cache) */
+    callOne(id: string): unknown;
+}
+/** Options for creating a derivations manager */
+interface CreateDerivationsOptions<S extends Schema, D extends DerivationsDef<S>> {
+    definitions: D;
+    facts: Facts<S>;
+    store: FactsStore<S>;
+    /** Callback when a derivation is computed */
+    onCompute?: (id: string, value: unknown, oldValue: unknown, deps: string[]) => void;
+    /** Callback when a derivation is invalidated */
+    onInvalidate?: (id: string) => void;
+    /** Callback when a derivation errors */
+    onError?: (id: string, error: unknown) => void;
+}
+/**
+ * Create a manager for lazily-evaluated, auto-tracked derived values.
+ *
+ * Derivations are memoized computations that automatically track which facts
+ * they read. When a tracked fact changes, the derivation is invalidated and
+ * recomputed on next access. Derivations can depend on other derivations
+ * (composition), and circular dependencies are detected at compute time.
+ *
+ * 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 {@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>;
+
+/**
+ * Effects - Fire-and-forget side effects
+ *
+ * Features:
+ * - Separate from requirement resolution
+ * - Error isolation (never breaks reconciliation)
+ * - Optional explicit dependencies for optimization
+ * - Runs after facts stabilize
+ *
+ * IMPORTANT: Auto-tracking limitations
+ * ------------------------------------
+ * When using auto-tracking (no explicit `deps`), only SYNCHRONOUS fact accesses
+ * are tracked. If your effect reads facts after an `await`, those reads are NOT
+ * tracked and won't trigger the effect on future changes.
+ *
+ * For async effects, always use explicit `deps`:
+ * @example
+ * ```typescript
+ * effects: {
+ *   // BAD: fetchData is async, facts.userId read after await won't be tracked
+ *   badEffect: {
+ *     run: async (facts) => {
+ *       await someAsyncOp();
+ *       console.log(facts.userId); // NOT tracked!
+ *     },
+ *   },
+ *   // GOOD: explicit deps for async effects
+ *   goodEffect: {
+ *     deps: ["userId"],
+ *     run: async (facts) => {
+ *       await someAsyncOp();
+ *       console.log(facts.userId); // Works because we declared the dep
+ *     },
+ *   },
+ * }
+ * ```
+ */
+
+/**
+ * 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 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 every enabled effect unconditionally, regardless of dependencies.
+     */
+    runAll(): Promise<void>;
+    /**
+     * Disable an effect so it is skipped during subsequent runs.
+     *
+     * @param id - The effect definition ID.
+     */
+    disable(id: string): void;
+    /**
+     * Re-enable a previously disabled effect.
+     *
+     * @param id - The effect definition ID.
+     */
+    enable(id: string): void;
+    /**
+     * 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;
+    /**
+     * 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 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;
+    /**
+     * Override an existing effect definition. Runs cleanup of the old effect first.
+     *
+     * @param id - The effect definition ID to override.
+     * @param def - The new effect definition.
+     * @throws If no effect with this ID exists.
+     */
+    assignDefinition(id: string, def: EffectsDef<Schema>[string]): void;
+    /**
+     * Remove an effect definition. Runs cleanup (try-catch) and removes from state.
+     *
+     * @param id - The effect definition ID to remove.
+     */
+    unregisterDefinition(id: string): void;
+    /**
+     * Execute an effect's `run()` function immediately.
+     *
+     * @param id - The effect definition ID.
+     */
+    callOne(id: string): Promise<void>;
+}
+/**
+ * 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>;
+    /** Called when an effect executes, with the fact keys that triggered it. */
+    onRun?: (id: string, deps: string[]) => void;
+    /** 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.
+ *
+ * @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"]));
+ * ```
+ *
+ * @internal
+ */
+declare function createEffectsManager<S extends Schema>(options: CreateEffectsOptions<S>): EffectsManager<S>;
+
+/**
+ * Constraints - Rules that produce requirements when conditions aren't met
+ *
+ * Features:
+ * - Sync and async constraint evaluation
+ * - Priority ordering (higher runs first)
+ * - Timeout handling for async constraints
+ * - 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 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 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 the state of every registered constraint.
+     *
+     * @returns An array of all {@link ConstraintState} objects.
+     */
+    getAllStates(): ConstraintState[];
+    /**
+     * Disable a constraint so it is skipped during evaluation.
+     *
+     * @param id - The constraint definition ID.
+     */
+    disable(id: string): void;
+    /**
+     * Re-enable a previously disabled constraint.
+     *
+     * @param id - The constraint definition ID.
+     */
+    enable(id: string): void;
+    /**
+     * 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 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;
+    /**
+     * 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 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 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 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;
+    /**
+     * Override an existing constraint definition.
+     * Stores the original in an internal map for inspection.
+     *
+     * @param id - The constraint definition ID to override.
+     * @param def - The new constraint definition.
+     * @throws If no constraint with this ID exists.
+     */
+    assignDefinition(id: string, def: ConstraintsDef<Schema>[string]): void;
+    /**
+     * Remove a constraint definition and all its internal state.
+     *
+     * @param id - The constraint definition ID to remove.
+     */
+    unregisterDefinition(id: string): void;
+    /**
+     * Evaluate a single constraint and emit its requirement if active.
+     * Props are merged into the requirement object.
+     *
+     * @param id - The constraint definition ID.
+     * @param props - Optional properties to merge into the requirement.
+     * @returns The emitted requirements (if any).
+     */
+    callOne(id: string, props?: Record<string, unknown>): Promise<RequirementWithId[]>;
+}
+/**
+ * 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 requirement deduplication, keyed by constraint ID. */
+    requirementKeys?: Record<string, RequirementKeyFn>;
+    /** Default timeout in milliseconds for async constraint evaluation (defaults to 5 000). */
+    defaultTimeout?: number;
+    /** Called after each constraint evaluation with the constraint ID and whether `when()` was active. */
+    onEvaluate?: (id: string, active: boolean) => void;
+    /** 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.
+ *
+ * @remarks
+ * Constraints are evaluated in priority order (higher priority first), with
+ * topological ordering for same-priority constraints connected by `after`
+ * 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),
+ * });
+ *
+ * const unmet = await constraints.evaluate();
+ * ```
+ *
+ * @internal
+ */
+declare function createConstraintsManager<S extends Schema>(options: CreateConstraintsOptions<S>): ConstraintsManager<S>;
+
+/**
+ * Resolvers - Capability-based handlers for requirements
+ *
+ * Features:
+ * - Capability matching (handles predicate)
+ * - Custom dedupe keys
+ * - Retry policies with exponential backoff
+ * - Batched resolution for similar requirements
+ * - Cancellation via AbortController
+ */
+
+/**
+ * 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 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 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 every in-flight resolver and flush all pending batch queues.
+     */
+    cancelAll(): void;
+    /**
+     * 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 the requirement IDs of all currently in-flight resolvers.
+     *
+     * @returns An array of requirement ID strings.
+     */
+    getInflight(): string[];
+    /**
+     * Get detailed info for every in-flight resolver.
+     *
+     * @returns An array of {@link InflightInfo} objects.
+     */
+    getInflightInfo(): InflightInfo[];
+    /**
+     * 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;
+    /**
+     * Immediately flush all pending batch queues, executing their resolvers.
+     */
+    processBatches(): void;
+    /**
+     * 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;
+    /**
+     * Override an existing resolver definition.
+     *
+     * @param id - The resolver definition ID to override.
+     * @param def - The new resolver definition.
+     * @throws If no resolver with this ID exists.
+     */
+    assignDefinition(id: string, def: ResolversDef<Schema>[string]): void;
+    /**
+     * Remove a resolver definition. Cancels any inflight resolution.
+     *
+     * @param id - The resolver definition ID to remove.
+     */
+    unregisterDefinition(id: string): void;
+    /**
+     * Execute a resolver with a given requirement object.
+     *
+     * @param id - The resolver definition ID.
+     * @param requirement - The requirement to resolve.
+     */
+    callOne(id: string, requirement: Requirement): Promise<void>;
+    /**
+     * Clean up all internal state. Called on system destroy.
+     */
+    destroy(): void;
+}
+/**
+ * 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>;
+    /** Called when a resolver begins execution. */
+    onStart?: (resolver: string, req: RequirementWithId) => void;
+    /** Called when a resolver completes successfully, with the wall-clock duration in ms. */
+    onComplete?: (resolver: string, req: RequirementWithId, duration: number) => void;
+    /** Called when a resolver exhausts all retry attempts. */
+    onError?: (resolver: string, req: RequirementWithId, error: unknown) => void;
+    /** Called before each retry attempt with the upcoming attempt number. */
+    onRetry?: (resolver: string, req: RequirementWithId, attempt: number) => void;
+    /** Called when a resolver is canceled via {@link ResolversManager.cancel | cancel}. */
+    onCancel?: (resolver: string, req: RequirementWithId) => void;
+    /** Called after any resolver finishes (success, error, or batch completion) to trigger reconciliation. */
+    onResolutionComplete?: () => void;
+}
+declare function createResolversManager<S extends Schema>(options: CreateResolversOptions<S>): ResolversManager<S>;
+
+/**
+ * Plugin Architecture - Extensible middleware for Directive
+ *
+ * Features:
+ * - Lifecycle hooks for all engine events
+ * - Multiple plugins can be composed
+ * - 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`
+ * - **History:** `emitSnapshot`, `emitHistoryNavigate`
+ * - **Errors:** `emitError`, `emitErrorRecovery`
+ * - **Trace:** `emitTraceComplete`
+ *
+ * @typeParam _S - The flat schema type (unused at runtime).
+ *
+ * @internal
+ */
+interface PluginManager<_S extends Schema = any> {
+    /** Register a plugin */
+    register(plugin: Plugin<any>): void;
+    /** Unregister a plugin by name */
+    unregister(name: string): void;
+    /** Get all registered plugins */
+    getPlugins(): Plugin<any>[];
+    emitInit(system: System<any>): Promise<void>;
+    emitStart(system: System<any>): void;
+    emitStop(system: System<any>): void;
+    emitDestroy(system: System<any>): void;
+    emitFactSet(key: string, value: unknown, prev: unknown): void;
+    emitFactDelete(key: string, prev: unknown): void;
+    emitFactsBatch(changes: FactChange[]): void;
+    emitDerivationCompute(id: string, value: unknown, deps: string[]): void;
+    emitDerivationInvalidate(id: string): void;
+    emitReconcileStart(snapshot: FactsSnapshot<any>): void;
+    emitReconcileEnd(result: ReconcileResult): void;
+    emitConstraintEvaluate(id: string, active: boolean): void;
+    emitConstraintError(id: string, error: unknown): void;
+    emitRequirementCreated(req: RequirementWithId): void;
+    emitRequirementMet(req: RequirementWithId, byResolver: string): void;
+    emitRequirementCanceled(req: RequirementWithId): void;
+    emitResolverStart(resolver: string, req: RequirementWithId): void;
+    emitResolverComplete(resolver: string, req: RequirementWithId, duration: number): void;
+    emitResolverError(resolver: string, req: RequirementWithId, error: unknown): void;
+    emitResolverRetry(resolver: string, req: RequirementWithId, attempt: number): void;
+    emitResolverCancel(resolver: string, req: RequirementWithId): void;
+    emitEffectRun(id: string): void;
+    emitEffectError(id: string, error: unknown): void;
+    emitSnapshot(snapshot: Snapshot): 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;
+    emitTraceComplete(run: TraceEntry): void;
+}
+/**
+ * Create a {@link PluginManager} that broadcasts lifecycle events to registered plugins.
+ *
+ * @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 {@link PluginManager} with `register`/`unregister`/`getPlugins` and `emit*` methods for every lifecycle event.
+ *
+ * @internal
+ */
+declare function createPluginManager<S extends Schema = any>(): PluginManager<S>;
+
+/**
+ * Error Boundaries - Configurable error handling and recovery
+ *
+ * Features:
+ * - Catch errors in constraints/resolvers/effects/derivations
+ * - Configurable recovery strategies (skip, retry, retry-later, disable, throw)
+ * - Circuit breaker pattern for automatic failure protection
+ * - Error reporting to plugins
+ */
+
+/**
+ * A queued retry entry tracking its source, attempt count, and scheduled time.
+ *
+ * @internal
+ */
+interface PendingRetry {
+    source: ErrorSource;
+    sourceId: string;
+    context: unknown;
+    attempt: number;
+    nextRetryTime: number;
+    callback?: () => void;
+}
+/**
+ * Create a manager for deferred retry scheduling with exponential backoff.
+ *
+ * @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 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 */
+    scheduleRetry: (source: ErrorSource, sourceId: string, context: unknown, attempt: number, callback?: () => void) => PendingRetry | null;
+    /** Get pending retries */
+    getPendingRetries: () => PendingRetry[];
+    /** Process due retries */
+    processDueRetries: () => PendingRetry[];
+    /** Cancel a retry */
+    cancelRetry: (sourceId: string) => void;
+    /** Clear all pending retries */
+    clearAll: () => void;
+};
+/**
+ * Handle returned by {@link createErrorBoundaryManager} for routing errors
+ * through configurable recovery strategies.
+ *
+ * @internal
+ */
+interface ErrorBoundaryManager {
+    /**
+     * 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;
+    /**
+     * Return the most recently recorded error, or `null` if none exist.
+     *
+     * @returns The last {@link DirectiveError}, or `null`.
+     */
+    getLastError(): DirectiveError | null;
+    /**
+     * 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 recorded errors. */
+    clearErrors(): void;
+    /**
+     * Access the underlying retry-later manager for advanced scheduling.
+     *
+     * @returns The {@link createRetryLaterManager} instance used internally.
+     */
+    getRetryLaterManager(): ReturnType<typeof createRetryLaterManager>;
+    /**
+     * Drain and return retry entries whose scheduled time has elapsed.
+     *
+     * @returns An array of {@link PendingRetry} entries that are now due.
+     */
+    processDueRetries(): PendingRetry[];
+    /**
+     * 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 accepted by {@link createErrorBoundaryManager}.
+ *
+ * @internal
+ */
+interface CreateErrorBoundaryOptions {
+    /** Per-source recovery strategies and retry-later tuning. */
+    config?: ErrorBoundaryConfig;
+    /** Invoked every time an error is recorded, before the recovery strategy runs. */
+    onError?: (error: DirectiveError) => void;
+    /** 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.
+ *
+ * @remarks
+ * Five recovery strategies are available:
+ *
+ * - `"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}.
+ *
+ * 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.
+ *
+ * @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;
+
+/**
+ * History — Snapshot-based state history
+ *
+ * Features:
+ * - Ring buffer of state snapshots
+ * - Go back/forward through history
+ * - Replay from any snapshot
+ * - Export/import state history
+ */
+
+/**
+ * Internal history manager that extends the public {@link HistoryAPI}
+ * 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 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 history is enabled */
+    readonly isEnabled: boolean;
+    /** True while restoring a snapshot (engine should skip reconciliation) */
+    readonly isRestoring: boolean;
+    /** Pause snapshot taking */
+    pause(): void;
+    /** Resume snapshot taking */
+    resume(): void;
+}
+/**
+ * Options for creating a history manager via {@link createHistoryManager}.
+ *
+ * @typeParam S - The facts schema type.
+ *
+ * @internal
+ */
+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 history navigation occurs */
+    onHistoryChange?: (from: number, to: number) => void;
+}
+/**
+ * Create a snapshot-based history manager backed by a ring buffer.
+ *
+ * @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.
+ *
+ * Call `pause()` to temporarily stop recording snapshots (e.g., during bulk
+ * fact imports) and `resume()` to re-enable recording.
+ *
+ * @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 createHistoryManager<S extends Schema>(options: CreateHistoryOptions<S>): HistoryManager<S>;
+/**
+ * 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 HistoryManager}
+ * interface regardless of whether history is enabled.
+ *
+ * @returns A {@link HistoryManager} where every method is a no-op and `isEnabled` is `false`.
+ *
+ * @internal
+ */
+declare function createDisabledHistory<S extends Schema>(): HistoryManager<S>;
+
+/**
+ * Engine - The core reconciliation loop
+ *
+ * The engine orchestrates:
+ * 1. Fact changes trigger reconciliation
+ * 2. Constraints produce requirements
+ * 3. Resolvers fulfill requirements
+ * 4. Effects run after stabilization
+ * 5. Derivations are invalidated and recomputed
+ */
+
+/**
+ * Create the core Directive reconciliation engine that wires facts, derivations,
+ * effects, constraints, resolvers, plugins, error boundaries, and history
+ * into a single reactive system.
+ *
+ * @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 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
+ * // Prefer createSystem for most use cases:
+ * import { createSystem, createModule, t } from "@directive-run/core";
+ *
+ * const counter = createModule("counter", {
+ *   schema: { count: t.number() },
+ *   init: (facts) => { facts.count = 0; },
+ * });
+ *
+ * const system = createSystem({ module: counter });
+ * system.start();
+ * system.facts.count = 42;
+ * ```
+ *
+ * @internal
+ */
+declare function createEngine<S extends Schema>(config: SystemConfig<any>): System<any>;
+
+/**
+ * Dependency tracking context for auto-tracking derivations
+ *
+ * Uses a stack-based approach to handle nested derivation computations.
+ * When a derivation accesses a fact, the tracking context records it.
+ */
+
+/**
+ * Get the current tracking context.
+ *
+ * @returns The active {@link TrackingContext}, or a null context (no-op) if
+ *   no tracking is active.
+ *
+ * @internal
+ */
+declare function getCurrentTracker(): TrackingContext;
+/**
+ * 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.
+ *
+ * @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;
+    deps: Set<string>;
+};
+/**
+ * Run a function without tracking.
+ *
+ * @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.
+ *
+ * @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;
+
+export { ConstraintState, ConstraintsDef, type DerivationState, type DerivationsDef, type DerivedValues, EffectsDef, ErrorSource, FactChange, FactsStore, type InflightInfo, type PendingRetry, ReconcileResult, RecoveryStrategy, RequirementKeyFn, ResolverStatus, ResolversDef, RetryLaterConfig, createConstraintsManager, createDerivationsManager, createDisabledHistory, createEffectsManager, createEngine, createErrorBoundaryManager, createFacts, createFactsProxy, createFactsStore, createHistoryManager, createPluginManager, createResolversManager, createRetryLaterManager, getCurrentTracker, isTracking, trackAccess, withTracking, withoutTracking };