@directive-run/core 1.3.0 → 1.5.0

package/dist/internals.d.cts

@@ -1,7 +1,7 @@
-import { X as Schema, a5 as FactsStore, F as Facts, D as DefinitionMeta, E as EffectsDef, a6 as ConstraintsDef, p as RequirementKeyFn, R as RequirementWithId, a7 as ConstraintState, a8 as ResolversDef, a9 as ResolverStatus, o as Requirement, P as Plugin, Z as System, aa as FactChange, w as FactsSnapshot, ab as ReconcileResult, Y as Snapshot, q as DirectiveError, ac as RecoveryStrategy, a2 as TraceEntry, ad as ErrorSource, n as ErrorBoundaryConfig, ae as RetryLaterConfig, H as HistoryAPI, x as HistoryOption, _ as SystemConfig } from './plugins-CLZ3xci0.cjs';
-export { af as BatchItemResult, ag as BatchResolveResults, ah as ConstraintsControl, ai as CrossModuleConstraintDef, g as CrossModuleConstraintsDef, aj as CrossModuleDerivationFn, e as CrossModuleDerivationsDef, ak as CrossModuleEffectDef, f as CrossModuleEffectsDef, al as CrossModuleFactsWithSelf, am as DerivationKeys, an as DerivationReturnType, ao as DerivationsControl, ap as DerivationsSchema, aq as DeriveAccessor, ar as DispatchEventsFromSchema, r as DistributableSnapshot, s as DistributableSnapshotOptions, as as EffectCleanup, at as EffectsControl, au as EventPayloadSchema, av as EventsAccessor, aw as EventsAccessorFromSchema, ax as EventsDef, ay as EventsSchema, az as FactKeys, aA as FactReturnType, aB as FlexibleEventHandler, aC as HistoryConfig, aD as InferEventPayloadFromSchema, aE as InferRequirementPayloadFromSchema, aF as InferSchema, aG as MutableNamespacedFacts, aH as NamespacedDerivations, aI as NamespacedEventsAccessor, aJ as NamespacedFacts, aK as ObservableKeys, aL as RequirementExplanation, aM as RequirementOutput, aN as RequirementPayloadSchema, aO as RequirementsSchema, aP as ResolverContext, aQ as ResolversControl, aR as SnapshotMeta, aS as SystemEvent, aT as TraceConfig, aU as TypedConstraintDef, b as TypedConstraintsDef, T as TypedDerivationsDef, a as TypedEventsDef, aV as TypedResolverContext, aW as TypedResolverDef, c as TypedResolversDef, aX as UnionEvents } from './plugins-CLZ3xci0.cjs';
-import { b as DerivationsDef, c as DerivedValues } from './helpers-CCljEIsG.cjs';
-export { d as DerivationState, T as TypedConstraint, e as TypedResolver, f as createConstraintFactory, g as createResolverFactory } from './helpers-CCljEIsG.cjs';
+import { a8 as Schema, ai as FactsStore, a as Facts, D as DefinitionMeta, E as EffectsDef, aj as ConstraintsDef, s as RequirementKeyFn, R as RequirementWithId, ak as ConstraintState, z as FactPredicate, C as ClauseResult, al as ResolversDef, am as ResolverStatus, r as Requirement, o as Plugin, aa as System, an as FactChange, G as FactsSnapshot, ao as ReconcileResult, a9 as Snapshot, t as DirectiveError, ap as RecoveryStrategy, af as TraceEntry, aq as ErrorSource, q as ErrorBoundaryConfig, ar as RetryLaterConfig, H as HistoryAPI, I as HistoryOption, ab as SystemConfig } from './plugins-Bakr7js6.cjs';
+export { as as BatchItemResult, at as BatchResolveResults, au as ConstraintsControl, av as CrossModuleConstraintDef, i as CrossModuleConstraintsDef, aw as CrossModuleDerivationFn, g as CrossModuleDerivationsDef, ax as CrossModuleEffectDef, h as CrossModuleEffectsDef, ay as CrossModuleFactsWithSelf, az as DerivationKeys, aA as DerivationReturnType, aB as DerivationsControl, aC as DerivationsSchema, aD as DeriveAccessor, aE as DispatchEventsFromSchema, u as DistributableSnapshot, v as DistributableSnapshotOptions, aF as EffectCleanup, aG as EffectsControl, aH as EventPayloadSchema, aI as EventsAccessor, aJ as EventsAccessorFromSchema, aK as EventsDef, aL as EventsSchema, aM as FactKeys, aN as FactReturnType, aO as FlexibleEventHandler, aP as HistoryConfig, aQ as InferEventPayloadFromSchema, aR as InferRequirementPayloadFromSchema, aS as InferSchema, aT as MutableNamespacedFacts, aU as NamespacedDerivations, aV as NamespacedEventsAccessor, aW as NamespacedFacts, aX as ObservableKeys, aY as RequirementExplanation, aZ as RequirementOutput, a_ as RequirementPayloadSchema, a$ as RequirementsSchema, b0 as ResolverContext, b1 as ResolversControl, b2 as SnapshotMeta, b3 as SystemEvent, b4 as TraceConfig, b5 as TypedConstraintDef, c as TypedConstraintsDef, T as TypedDerivationsDef, b as TypedEventsDef, b6 as TypedResolverContext, b7 as TypedResolverDef, d as TypedResolversDef, b8 as UnionEvents } from './plugins-Bakr7js6.cjs';
+import { b as DerivationsDef, c as DerivedValues } from './helpers-B1MiHave.cjs';
+export { d as DerivationState, T as TypedConstraint, e as TypedResolver, f as createConstraintFactory, g as createResolverFactory } from './helpers-B1MiHave.cjs';
 export { g as safeStringify } from './utils-BnQajqPu.cjs';
 
 /**
@@ -369,16 +369,6 @@ interface CreateEffectsOptions<S extends Schema> {
  */
 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
@@ -512,6 +502,19 @@ interface ConstraintsManager<_S extends Schema> {
      * @param requirementType - The requirement type string to remove.
      */
     removeRequirementKey(requirementType: string): void;
+    /**
+     * Return the original {@link FactPredicate} spec a constraint was declared
+     * with — present only when the constraint's `when` was provided as data.
+     * Used by `system.inspect()` / `system.explain()` and devtools to render
+     * the clause structure.
+     */
+    getWhenSpec(id: string): FactPredicate<Record<string, unknown>> | undefined;
+    /**
+     * Evaluate a data-form `when` and return the per-clause breakdown
+     * (which clauses passed, which failed, against what fact values).
+     * Returns `undefined` for constraints whose `when` is a function.
+     */
+    explainWhen(id: string): ClauseResult[] | undefined;
 }
 /**
  * Configuration options accepted by {@link createConstraintsManager}.
@@ -622,6 +625,20 @@ interface ResolversManager<_S extends Schema> {
      * @param requirementId - The unique requirement ID to cancel.
      */
     cancel(requirementId: string): void;
+    /**
+     * Untrack an in-flight resolver by requirement ID **without** aborting it
+     * (RFC-0003 resolver constraint-binding).
+     *
+     * @remarks
+     * Used for bound resolvers whose triggering requirement was removed: the
+     * resolver runs to completion (its data writes land; the binding still
+     * guards owned facts) but it no longer occupies the `inflight` slot, so the
+     * same requirement re-dispatches cleanly if it returns. A no-op if the
+     * requirement is not in-flight.
+     *
+     * @param requirementId - The unique requirement ID to detach.
+     */
+    detach(requirementId: string): void;
     /**
      * Cancel every in-flight resolver and flush all pending batch queues.
      */
@@ -705,6 +722,23 @@ interface ResolversManager<_S extends Schema> {
      */
     destroy(): void;
 }
+/**
+ * Per-constraint binding info, used by RFC-1 (resolver constraint-binding).
+ *
+ * The engine wires this lookup into the resolvers manager so that a resolver
+ * dispatched from a constraint with an `owns` field knows which facts it
+ * *owns* — writes to those are clobber-checked (see {@link createBoundFacts}).
+ *
+ * Returns `undefined`/`null` when the source constraint is unknown or has no
+ * `owns` field — in which case binding is a no-op and the resolver behaves
+ * exactly as before.
+ *
+ * @internal
+ */
+interface ConstraintBindingInfo {
+    /** Fact keys the triggering resolver owns; writes to these are clobber-checked. */
+    readonly fields: readonly string[];
+}
 /**
  * Configuration options accepted by {@link createResolversManager}.
  *
@@ -717,6 +751,14 @@ interface CreateResolversOptions<S extends Schema> {
     facts: Facts<S>;
     /** Underlying fact store used for `batch()` coalescing of mutations. */
     store: FactsStore<S>;
+    /**
+     * Look up binding info for a source constraint id (RFC-1).
+     *
+     * Wired by the engine — given the `fromConstraint` of a `RequirementWithId`,
+     * returns the constraint's owned fact keys. Return `undefined` if the
+     * constraint is unknown or has no `owns` field.
+     */
+    getConstraintBinding?: (constraintId: string) => ConstraintBindingInfo | undefined;
     /** 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. */
@@ -737,16 +779,15 @@ interface CreateResolversOptions<S extends Schema> {
      */
     onRequeue?: (requirementId: string) => void;
 }
-declare function createResolversManager<S extends Schema>(options: CreateResolversOptions<S>): ResolversManager<S>;
-
 /**
- * Plugin Architecture - Extensible middleware for Directive
+ * Creates a resolver manager that tracks active resolver instances and
+ * coordinates their lifecycle (start / complete / error / cancel) against
+ * the engine's requirement graph.
  *
- * Features:
- * - Lifecycle hooks for all engine events
- * - Multiple plugins can be composed
- * - Plugins execute in registration order
+ * @param options - resolver definitions, facts reference, and event hooks
+ * @returns the manager handle used by the engine to drive resolver invocations
  */
+declare function createResolversManager<S extends Schema>(options: CreateResolversOptions<S>): ResolversManager<S>;
 
 /**
  * Internal manager that broadcasts lifecycle events to registered {@link Plugin} instances.
@@ -795,7 +836,7 @@ interface PluginManager<_S extends Schema = any> {
     emitDerivationInvalidate(id: string): void;
     emitReconcileStart(snapshot: FactsSnapshot<any>): void;
     emitReconcileEnd(result: ReconcileResult): void;
-    emitConstraintEvaluate(id: string, active: boolean): void;
+    emitConstraintEvaluate(id: string, active: boolean, whenExplain?: ClauseResult[]): void;
     emitConstraintError(id: string, error: unknown): void;
     emitRequirementCreated(req: RequirementWithId): void;
     emitRequirementMet(req: RequirementWithId, byResolver: string): void;

package/dist/internals.d.ts

@@ -1,7 +1,7 @@
-import { X as Schema, a5 as FactsStore, F as Facts, D as DefinitionMeta, E as EffectsDef, a6 as ConstraintsDef, p as RequirementKeyFn, R as RequirementWithId, a7 as ConstraintState, a8 as ResolversDef, a9 as ResolverStatus, o as Requirement, P as Plugin, Z as System, aa as FactChange, w as FactsSnapshot, ab as ReconcileResult, Y as Snapshot, q as DirectiveError, ac as RecoveryStrategy, a2 as TraceEntry, ad as ErrorSource, n as ErrorBoundaryConfig, ae as RetryLaterConfig, H as HistoryAPI, x as HistoryOption, _ as SystemConfig } from './plugins-CLZ3xci0.js';
-export { af as BatchItemResult, ag as BatchResolveResults, ah as ConstraintsControl, ai as CrossModuleConstraintDef, g as CrossModuleConstraintsDef, aj as CrossModuleDerivationFn, e as CrossModuleDerivationsDef, ak as CrossModuleEffectDef, f as CrossModuleEffectsDef, al as CrossModuleFactsWithSelf, am as DerivationKeys, an as DerivationReturnType, ao as DerivationsControl, ap as DerivationsSchema, aq as DeriveAccessor, ar as DispatchEventsFromSchema, r as DistributableSnapshot, s as DistributableSnapshotOptions, as as EffectCleanup, at as EffectsControl, au as EventPayloadSchema, av as EventsAccessor, aw as EventsAccessorFromSchema, ax as EventsDef, ay as EventsSchema, az as FactKeys, aA as FactReturnType, aB as FlexibleEventHandler, aC as HistoryConfig, aD as InferEventPayloadFromSchema, aE as InferRequirementPayloadFromSchema, aF as InferSchema, aG as MutableNamespacedFacts, aH as NamespacedDerivations, aI as NamespacedEventsAccessor, aJ as NamespacedFacts, aK as ObservableKeys, aL as RequirementExplanation, aM as RequirementOutput, aN as RequirementPayloadSchema, aO as RequirementsSchema, aP as ResolverContext, aQ as ResolversControl, aR as SnapshotMeta, aS as SystemEvent, aT as TraceConfig, aU as TypedConstraintDef, b as TypedConstraintsDef, T as TypedDerivationsDef, a as TypedEventsDef, aV as TypedResolverContext, aW as TypedResolverDef, c as TypedResolversDef, aX as UnionEvents } from './plugins-CLZ3xci0.js';
-import { b as DerivationsDef, c as DerivedValues } from './helpers-CfZCxxkR.js';
-export { d as DerivationState, T as TypedConstraint, e as TypedResolver, f as createConstraintFactory, g as createResolverFactory } from './helpers-CfZCxxkR.js';
+import { a8 as Schema, ai as FactsStore, a as Facts, D as DefinitionMeta, E as EffectsDef, aj as ConstraintsDef, s as RequirementKeyFn, R as RequirementWithId, ak as ConstraintState, z as FactPredicate, C as ClauseResult, al as ResolversDef, am as ResolverStatus, r as Requirement, o as Plugin, aa as System, an as FactChange, G as FactsSnapshot, ao as ReconcileResult, a9 as Snapshot, t as DirectiveError, ap as RecoveryStrategy, af as TraceEntry, aq as ErrorSource, q as ErrorBoundaryConfig, ar as RetryLaterConfig, H as HistoryAPI, I as HistoryOption, ab as SystemConfig } from './plugins-Bakr7js6.js';
+export { as as BatchItemResult, at as BatchResolveResults, au as ConstraintsControl, av as CrossModuleConstraintDef, i as CrossModuleConstraintsDef, aw as CrossModuleDerivationFn, g as CrossModuleDerivationsDef, ax as CrossModuleEffectDef, h as CrossModuleEffectsDef, ay as CrossModuleFactsWithSelf, az as DerivationKeys, aA as DerivationReturnType, aB as DerivationsControl, aC as DerivationsSchema, aD as DeriveAccessor, aE as DispatchEventsFromSchema, u as DistributableSnapshot, v as DistributableSnapshotOptions, aF as EffectCleanup, aG as EffectsControl, aH as EventPayloadSchema, aI as EventsAccessor, aJ as EventsAccessorFromSchema, aK as EventsDef, aL as EventsSchema, aM as FactKeys, aN as FactReturnType, aO as FlexibleEventHandler, aP as HistoryConfig, aQ as InferEventPayloadFromSchema, aR as InferRequirementPayloadFromSchema, aS as InferSchema, aT as MutableNamespacedFacts, aU as NamespacedDerivations, aV as NamespacedEventsAccessor, aW as NamespacedFacts, aX as ObservableKeys, aY as RequirementExplanation, aZ as RequirementOutput, a_ as RequirementPayloadSchema, a$ as RequirementsSchema, b0 as ResolverContext, b1 as ResolversControl, b2 as SnapshotMeta, b3 as SystemEvent, b4 as TraceConfig, b5 as TypedConstraintDef, c as TypedConstraintsDef, T as TypedDerivationsDef, b as TypedEventsDef, b6 as TypedResolverContext, b7 as TypedResolverDef, d as TypedResolversDef, b8 as UnionEvents } from './plugins-Bakr7js6.js';
+import { b as DerivationsDef, c as DerivedValues } from './helpers-h9PR2JSJ.js';
+export { d as DerivationState, T as TypedConstraint, e as TypedResolver, f as createConstraintFactory, g as createResolverFactory } from './helpers-h9PR2JSJ.js';
 export { g as safeStringify } from './utils-BnQajqPu.js';
 
 /**
@@ -369,16 +369,6 @@ interface CreateEffectsOptions<S extends Schema> {
  */
 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
@@ -512,6 +502,19 @@ interface ConstraintsManager<_S extends Schema> {
      * @param requirementType - The requirement type string to remove.
      */
     removeRequirementKey(requirementType: string): void;
+    /**
+     * Return the original {@link FactPredicate} spec a constraint was declared
+     * with — present only when the constraint's `when` was provided as data.
+     * Used by `system.inspect()` / `system.explain()` and devtools to render
+     * the clause structure.
+     */
+    getWhenSpec(id: string): FactPredicate<Record<string, unknown>> | undefined;
+    /**
+     * Evaluate a data-form `when` and return the per-clause breakdown
+     * (which clauses passed, which failed, against what fact values).
+     * Returns `undefined` for constraints whose `when` is a function.
+     */
+    explainWhen(id: string): ClauseResult[] | undefined;
 }
 /**
  * Configuration options accepted by {@link createConstraintsManager}.
@@ -622,6 +625,20 @@ interface ResolversManager<_S extends Schema> {
      * @param requirementId - The unique requirement ID to cancel.
      */
     cancel(requirementId: string): void;
+    /**
+     * Untrack an in-flight resolver by requirement ID **without** aborting it
+     * (RFC-0003 resolver constraint-binding).
+     *
+     * @remarks
+     * Used for bound resolvers whose triggering requirement was removed: the
+     * resolver runs to completion (its data writes land; the binding still
+     * guards owned facts) but it no longer occupies the `inflight` slot, so the
+     * same requirement re-dispatches cleanly if it returns. A no-op if the
+     * requirement is not in-flight.
+     *
+     * @param requirementId - The unique requirement ID to detach.
+     */
+    detach(requirementId: string): void;
     /**
      * Cancel every in-flight resolver and flush all pending batch queues.
      */
@@ -705,6 +722,23 @@ interface ResolversManager<_S extends Schema> {
      */
     destroy(): void;
 }
+/**
+ * Per-constraint binding info, used by RFC-1 (resolver constraint-binding).
+ *
+ * The engine wires this lookup into the resolvers manager so that a resolver
+ * dispatched from a constraint with an `owns` field knows which facts it
+ * *owns* — writes to those are clobber-checked (see {@link createBoundFacts}).
+ *
+ * Returns `undefined`/`null` when the source constraint is unknown or has no
+ * `owns` field — in which case binding is a no-op and the resolver behaves
+ * exactly as before.
+ *
+ * @internal
+ */
+interface ConstraintBindingInfo {
+    /** Fact keys the triggering resolver owns; writes to these are clobber-checked. */
+    readonly fields: readonly string[];
+}
 /**
  * Configuration options accepted by {@link createResolversManager}.
  *
@@ -717,6 +751,14 @@ interface CreateResolversOptions<S extends Schema> {
     facts: Facts<S>;
     /** Underlying fact store used for `batch()` coalescing of mutations. */
     store: FactsStore<S>;
+    /**
+     * Look up binding info for a source constraint id (RFC-1).
+     *
+     * Wired by the engine — given the `fromConstraint` of a `RequirementWithId`,
+     * returns the constraint's owned fact keys. Return `undefined` if the
+     * constraint is unknown or has no `owns` field.
+     */
+    getConstraintBinding?: (constraintId: string) => ConstraintBindingInfo | undefined;
     /** 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. */
@@ -737,16 +779,15 @@ interface CreateResolversOptions<S extends Schema> {
      */
     onRequeue?: (requirementId: string) => void;
 }
-declare function createResolversManager<S extends Schema>(options: CreateResolversOptions<S>): ResolversManager<S>;
-
 /**
- * Plugin Architecture - Extensible middleware for Directive
+ * Creates a resolver manager that tracks active resolver instances and
+ * coordinates their lifecycle (start / complete / error / cancel) against
+ * the engine's requirement graph.
  *
- * Features:
- * - Lifecycle hooks for all engine events
- * - Multiple plugins can be composed
- * - Plugins execute in registration order
+ * @param options - resolver definitions, facts reference, and event hooks
+ * @returns the manager handle used by the engine to drive resolver invocations
  */
+declare function createResolversManager<S extends Schema>(options: CreateResolversOptions<S>): ResolversManager<S>;
 
 /**
  * Internal manager that broadcasts lifecycle events to registered {@link Plugin} instances.
@@ -795,7 +836,7 @@ interface PluginManager<_S extends Schema = any> {
     emitDerivationInvalidate(id: string): void;
     emitReconcileStart(snapshot: FactsSnapshot<any>): void;
     emitReconcileEnd(result: ReconcileResult): void;
-    emitConstraintEvaluate(id: string, active: boolean): void;
+    emitConstraintEvaluate(id: string, active: boolean, whenExplain?: ClauseResult[]): void;
     emitConstraintError(id: string, error: unknown): void;
     emitRequirementCreated(req: RequirementWithId): void;
     emitRequirementMet(req: RequirementWithId, byResolver: string): void;

package/dist/internals.js

@@ -1,2 +1,2 @@
-export{c as createConstraintFactory,p as createConstraintsManager,q as createDerivationsManager,j as createDisabledHistory,r as createEffectsManager,z as createEngine,t as createErrorBoundaryManager,w as createFacts,v as createFactsProxy,u as createFactsStore,i as createHistoryManager,x as createPluginManager,d as createResolverFactory,y as createResolversManager,s as createRetryLaterManager}from'./chunk-GVVNFVEX.js';export{g as getCurrentDeps,h as isTracking,k as trackAccess,i as withTracking,j as withoutTracking}from'./chunk-FK7BD7XT.js';export{l as safeStringify}from'./chunk-4CMO5OVZ.js';//# sourceMappingURL=internals.js.map
+export{m as createConstraintFactory,z as createConstraintsManager,A as createDerivationsManager,t as createDisabledHistory,B as createEffectsManager,J as createEngine,D as createErrorBoundaryManager,G as createFacts,F as createFactsProxy,E as createFactsStore,s as createHistoryManager,H as createPluginManager,n as createResolverFactory,I as createResolversManager,C as createRetryLaterManager}from'./chunk-YCCQ73C6.js';export{g as getCurrentDeps,h as isTracking,k as trackAccess,i as withTracking,j as withoutTracking}from'./chunk-EH2Q754B.js';export{l as safeStringify}from'./chunk-M5KZXNZX.js';//# sourceMappingURL=internals.js.map
 //# sourceMappingURL=internals.js.map