@directive-run/core 1.4.0 → 1.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (71) hide show
  1. package/dist/adapter-utils.cjs +1 -1
  2. package/dist/adapter-utils.d.cts +1 -1
  3. package/dist/adapter-utils.d.ts +1 -1
  4. package/dist/adapter-utils.js +1 -1
  5. package/dist/{chunk-FK7BD7XT.js → chunk-EH2Q754B.js} +3 -3
  6. package/dist/chunk-EH2Q754B.js.map +1 -0
  7. package/dist/chunk-HAF5JCET.js +16 -0
  8. package/dist/chunk-HAF5JCET.js.map +1 -0
  9. package/dist/{chunk-4CMO5OVZ.js → chunk-M5KZXNZX.js} +2 -2
  10. package/dist/chunk-M5KZXNZX.js.map +1 -0
  11. package/dist/chunk-PGUTGWUI.cjs +3 -0
  12. package/dist/chunk-PGUTGWUI.cjs.map +1 -0
  13. package/dist/{chunk-DDUARSUH.cjs → chunk-S3CFYDIB.cjs} +3 -3
  14. package/dist/chunk-S3CFYDIB.cjs.map +1 -0
  15. package/dist/chunk-SQVKCJHE.cjs +16 -0
  16. package/dist/chunk-SQVKCJHE.cjs.map +1 -0
  17. package/dist/chunk-YCCQ73C6.js +3 -0
  18. package/dist/chunk-YCCQ73C6.js.map +1 -0
  19. package/dist/{chunk-BEJ6ICA7.cjs → chunk-ZHS3EW2Z.cjs} +2 -2
  20. package/dist/chunk-ZHS3EW2Z.cjs.map +1 -0
  21. package/dist/{helpers-D6LcRum7.d.ts → helpers-B1MiHave.d.cts} +12 -2
  22. package/dist/{helpers-BUY1lYCX.d.cts → helpers-h9PR2JSJ.d.ts} +12 -2
  23. package/dist/index.cjs +1 -1
  24. package/dist/index.cjs.map +1 -1
  25. package/dist/index.d.cts +183 -5
  26. package/dist/index.d.ts +183 -5
  27. package/dist/index.js +1 -1
  28. package/dist/index.js.map +1 -1
  29. package/dist/internals.cjs +1 -1
  30. package/dist/internals.d.cts +49 -39
  31. package/dist/internals.d.ts +49 -39
  32. package/dist/internals.js +1 -1
  33. package/dist/plugins/index.cjs +1 -1
  34. package/dist/plugins/index.cjs.map +1 -1
  35. package/dist/plugins/index.d.cts +11 -8
  36. package/dist/plugins/index.d.ts +11 -8
  37. package/dist/plugins/index.js +1 -1
  38. package/dist/plugins/index.js.map +1 -1
  39. package/dist/{plugins-Dy1C8GtT.d.cts → plugins-Bakr7js6.d.cts} +369 -69
  40. package/dist/{plugins-Dy1C8GtT.d.ts → plugins-Bakr7js6.d.ts} +369 -69
  41. package/dist/system-744ZPPES.js +2 -0
  42. package/dist/{system-JIO36ALC.js.map → system-744ZPPES.js.map} +1 -1
  43. package/dist/system-CK3SHMXZ.cjs +2 -0
  44. package/dist/{system-2THXJBFM.cjs.map → system-CK3SHMXZ.cjs.map} +1 -1
  45. package/dist/testing.cjs +1 -1
  46. package/dist/testing.cjs.map +1 -1
  47. package/dist/testing.d.cts +1 -1
  48. package/dist/testing.d.ts +1 -1
  49. package/dist/testing.js +1 -1
  50. package/dist/testing.js.map +1 -1
  51. package/dist/worker.cjs +1 -1
  52. package/dist/worker.cjs.map +1 -1
  53. package/dist/worker.d.cts +1 -1
  54. package/dist/worker.d.ts +1 -1
  55. package/dist/worker.js +1 -1
  56. package/dist/worker.js.map +1 -1
  57. package/package.json +1 -1
  58. package/dist/chunk-4CMO5OVZ.js.map +0 -1
  59. package/dist/chunk-BEJ6ICA7.cjs.map +0 -1
  60. package/dist/chunk-DDUARSUH.cjs.map +0 -1
  61. package/dist/chunk-E2WETPLH.js +0 -3
  62. package/dist/chunk-E2WETPLH.js.map +0 -1
  63. package/dist/chunk-FK7BD7XT.js.map +0 -1
  64. package/dist/chunk-LFMRWCIG.js +0 -16
  65. package/dist/chunk-LFMRWCIG.js.map +0 -1
  66. package/dist/chunk-TUS5WDVE.cjs +0 -3
  67. package/dist/chunk-TUS5WDVE.cjs.map +0 -1
  68. package/dist/chunk-VSHSYVSY.cjs +0 -16
  69. package/dist/chunk-VSHSYVSY.cjs.map +0 -1
  70. package/dist/system-2THXJBFM.cjs +0 -2
  71. package/dist/system-JIO36ALC.js +0 -2
@@ -1,7 +1,7 @@
1
- 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 ConstraintBindMode, aa as ResolverStatus, o as Requirement, P as Plugin, Z as System, ab as FactChange, w as FactsSnapshot, ac as ReconcileResult, Y as Snapshot, q as DirectiveError, ad as RecoveryStrategy, a2 as TraceEntry, ae as ErrorSource, n as ErrorBoundaryConfig, af as RetryLaterConfig, H as HistoryAPI, x as HistoryOption, _ as SystemConfig } from './plugins-Dy1C8GtT.cjs';
2
- export { ag as BatchItemResult, ah as BatchResolveResults, ai as ConstraintsControl, aj as CrossModuleConstraintDef, g as CrossModuleConstraintsDef, ak as CrossModuleDerivationFn, e as CrossModuleDerivationsDef, al as CrossModuleEffectDef, f as CrossModuleEffectsDef, am as CrossModuleFactsWithSelf, an as DerivationKeys, ao as DerivationReturnType, ap as DerivationsControl, aq as DerivationsSchema, ar as DeriveAccessor, as as DispatchEventsFromSchema, r as DistributableSnapshot, s as DistributableSnapshotOptions, at as EffectCleanup, au as EffectsControl, av as EventPayloadSchema, aw as EventsAccessor, ax as EventsAccessorFromSchema, ay as EventsDef, az as EventsSchema, aA as FactKeys, aB as FactReturnType, aC as FlexibleEventHandler, aD as HistoryConfig, aE as InferEventPayloadFromSchema, aF as InferRequirementPayloadFromSchema, aG as InferSchema, aH as MutableNamespacedFacts, aI as NamespacedDerivations, aJ as NamespacedEventsAccessor, aK as NamespacedFacts, aL as ObservableKeys, aM as RequirementExplanation, aN as RequirementOutput, aO as RequirementPayloadSchema, aP as RequirementsSchema, aQ as ResolverContext, aR as ResolversControl, aS as SnapshotMeta, aT as SystemEvent, aU as TraceConfig, aV as TypedConstraintDef, b as TypedConstraintsDef, T as TypedDerivationsDef, a as TypedEventsDef, aW as TypedResolverContext, aX as TypedResolverDef, c as TypedResolversDef, aY as UnionEvents } from './plugins-Dy1C8GtT.cjs';
3
- import { b as DerivationsDef, c as DerivedValues } from './helpers-BUY1lYCX.cjs';
4
- export { d as DerivationState, T as TypedConstraint, e as TypedResolver, f as createConstraintFactory, g as createResolverFactory } from './helpers-BUY1lYCX.cjs';
1
+ 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';
2
+ 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';
3
+ import { b as DerivationsDef, c as DerivedValues } from './helpers-B1MiHave.cjs';
4
+ export { d as DerivationState, T as TypedConstraint, e as TypedResolver, f as createConstraintFactory, g as createResolverFactory } from './helpers-B1MiHave.cjs';
5
5
  export { g as safeStringify } from './utils-BnQajqPu.cjs';
6
6
 
7
7
  /**
@@ -369,16 +369,6 @@ interface CreateEffectsOptions<S extends Schema> {
369
369
  */
370
370
  declare function createEffectsManager<S extends Schema>(options: CreateEffectsOptions<S>): EffectsManager<S>;
371
371
 
372
- /**
373
- * Constraints - Rules that produce requirements when conditions aren't met
374
- *
375
- * Features:
376
- * - Sync and async constraint evaluation
377
- * - Priority ordering (higher runs first)
378
- * - Timeout handling for async constraints
379
- * - Error isolation
380
- */
381
-
382
372
  /**
383
373
  * Manager returned by {@link createConstraintsManager} that evaluates
384
374
  * constraint rules against the current facts and produces unmet
@@ -512,6 +502,19 @@ interface ConstraintsManager<_S extends Schema> {
512
502
  * @param requirementType - The requirement type string to remove.
513
503
  */
514
504
  removeRequirementKey(requirementType: string): void;
505
+ /**
506
+ * Return the original {@link FactPredicate} spec a constraint was declared
507
+ * with — present only when the constraint's `when` was provided as data.
508
+ * Used by `system.inspect()` / `system.explain()` and devtools to render
509
+ * the clause structure.
510
+ */
511
+ getWhenSpec(id: string): FactPredicate<Record<string, unknown>> | undefined;
512
+ /**
513
+ * Evaluate a data-form `when` and return the per-clause breakdown
514
+ * (which clauses passed, which failed, against what fact values).
515
+ * Returns `undefined` for constraints whose `when` is a function.
516
+ */
517
+ explainWhen(id: string): ClauseResult[] | undefined;
515
518
  }
516
519
  /**
517
520
  * Configuration options accepted by {@link createConstraintsManager}.
@@ -622,6 +625,20 @@ interface ResolversManager<_S extends Schema> {
622
625
  * @param requirementId - The unique requirement ID to cancel.
623
626
  */
624
627
  cancel(requirementId: string): void;
628
+ /**
629
+ * Untrack an in-flight resolver by requirement ID **without** aborting it
630
+ * (RFC-0003 resolver constraint-binding).
631
+ *
632
+ * @remarks
633
+ * Used for bound resolvers whose triggering requirement was removed: the
634
+ * resolver runs to completion (its data writes land; the binding still
635
+ * guards owned facts) but it no longer occupies the `inflight` slot, so the
636
+ * same requirement re-dispatches cleanly if it returns. A no-op if the
637
+ * requirement is not in-flight.
638
+ *
639
+ * @param requirementId - The unique requirement ID to detach.
640
+ */
641
+ detach(requirementId: string): void;
625
642
  /**
626
643
  * Cancel every in-flight resolver and flush all pending batch queues.
627
644
  */
@@ -709,23 +726,18 @@ interface ResolversManager<_S extends Schema> {
709
726
  * Per-constraint binding info, used by RFC-1 (resolver constraint-binding).
710
727
  *
711
728
  * The engine wires this lookup into the resolvers manager so that a resolver
712
- * dispatched from a constraint with `bind: 'auto'` can re-evaluate the
713
- * constraint's `when()` predicate live on every fact write.
729
+ * dispatched from a constraint with an `owns` field knows which facts it
730
+ * *owns* writes to those are clobber-checked (see {@link createBoundFacts}).
714
731
  *
715
- * Returns `null` (or the lookup itself returns `undefined`) when the source
716
- * constraint is unknown, async, or has `bind: 'none'` in which case
717
- * binding is a no-op and the resolver behaves exactly as before.
732
+ * Returns `undefined`/`null` when the source constraint is unknown or has no
733
+ * `owns` field in which case binding is a no-op and the resolver behaves
734
+ * exactly as before.
718
735
  *
719
736
  * @internal
720
737
  */
721
- interface ConstraintBindingInfo<S extends Schema> {
722
- /** The constraint's `bind` mode (effective; async predicates are forced to `'none'`). */
723
- mode: ConstraintBindMode;
724
- /**
725
- * The constraint's `when()` predicate, narrowed to a sync signature.
726
- * Only populated when `mode === 'auto'` and the constraint is sync.
727
- */
728
- when: ((facts: Facts<S>) => boolean) | null;
738
+ interface ConstraintBindingInfo {
739
+ /** Fact keys the triggering resolver owns; writes to these are clobber-checked. */
740
+ readonly fields: readonly string[];
729
741
  }
730
742
  /**
731
743
  * Configuration options accepted by {@link createResolversManager}.
@@ -743,11 +755,10 @@ interface CreateResolversOptions<S extends Schema> {
743
755
  * Look up binding info for a source constraint id (RFC-1).
744
756
  *
745
757
  * Wired by the engine — given the `fromConstraint` of a `RequirementWithId`,
746
- * returns the constraint's effective bind mode + a synchronous `when()`
747
- * reference. Return `undefined` if the constraint is unknown or binding
748
- * does not apply.
758
+ * returns the constraint's owned fact keys. Return `undefined` if the
759
+ * constraint is unknown or has no `owns` field.
749
760
  */
750
- getConstraintBinding?: (constraintId: string) => ConstraintBindingInfo<S> | undefined;
761
+ getConstraintBinding?: (constraintId: string) => ConstraintBindingInfo | undefined;
751
762
  /** Called when a resolver begins execution. */
752
763
  onStart?: (resolver: string, req: RequirementWithId) => void;
753
764
  /** Called when a resolver completes successfully, with the wall-clock duration in ms. */
@@ -768,16 +779,15 @@ interface CreateResolversOptions<S extends Schema> {
768
779
  */
769
780
  onRequeue?: (requirementId: string) => void;
770
781
  }
771
- declare function createResolversManager<S extends Schema>(options: CreateResolversOptions<S>): ResolversManager<S>;
772
-
773
782
  /**
774
- * Plugin Architecture - Extensible middleware for Directive
783
+ * Creates a resolver manager that tracks active resolver instances and
784
+ * coordinates their lifecycle (start / complete / error / cancel) against
785
+ * the engine's requirement graph.
775
786
  *
776
- * Features:
777
- * - Lifecycle hooks for all engine events
778
- * - Multiple plugins can be composed
779
- * - Plugins execute in registration order
787
+ * @param options - resolver definitions, facts reference, and event hooks
788
+ * @returns the manager handle used by the engine to drive resolver invocations
780
789
  */
790
+ declare function createResolversManager<S extends Schema>(options: CreateResolversOptions<S>): ResolversManager<S>;
781
791
 
782
792
  /**
783
793
  * Internal manager that broadcasts lifecycle events to registered {@link Plugin} instances.
@@ -826,7 +836,7 @@ interface PluginManager<_S extends Schema = any> {
826
836
  emitDerivationInvalidate(id: string): void;
827
837
  emitReconcileStart(snapshot: FactsSnapshot<any>): void;
828
838
  emitReconcileEnd(result: ReconcileResult): void;
829
- emitConstraintEvaluate(id: string, active: boolean): void;
839
+ emitConstraintEvaluate(id: string, active: boolean, whenExplain?: ClauseResult[]): void;
830
840
  emitConstraintError(id: string, error: unknown): void;
831
841
  emitRequirementCreated(req: RequirementWithId): void;
832
842
  emitRequirementMet(req: RequirementWithId, byResolver: string): void;
@@ -1,7 +1,7 @@
1
- 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 ConstraintBindMode, aa as ResolverStatus, o as Requirement, P as Plugin, Z as System, ab as FactChange, w as FactsSnapshot, ac as ReconcileResult, Y as Snapshot, q as DirectiveError, ad as RecoveryStrategy, a2 as TraceEntry, ae as ErrorSource, n as ErrorBoundaryConfig, af as RetryLaterConfig, H as HistoryAPI, x as HistoryOption, _ as SystemConfig } from './plugins-Dy1C8GtT.js';
2
- export { ag as BatchItemResult, ah as BatchResolveResults, ai as ConstraintsControl, aj as CrossModuleConstraintDef, g as CrossModuleConstraintsDef, ak as CrossModuleDerivationFn, e as CrossModuleDerivationsDef, al as CrossModuleEffectDef, f as CrossModuleEffectsDef, am as CrossModuleFactsWithSelf, an as DerivationKeys, ao as DerivationReturnType, ap as DerivationsControl, aq as DerivationsSchema, ar as DeriveAccessor, as as DispatchEventsFromSchema, r as DistributableSnapshot, s as DistributableSnapshotOptions, at as EffectCleanup, au as EffectsControl, av as EventPayloadSchema, aw as EventsAccessor, ax as EventsAccessorFromSchema, ay as EventsDef, az as EventsSchema, aA as FactKeys, aB as FactReturnType, aC as FlexibleEventHandler, aD as HistoryConfig, aE as InferEventPayloadFromSchema, aF as InferRequirementPayloadFromSchema, aG as InferSchema, aH as MutableNamespacedFacts, aI as NamespacedDerivations, aJ as NamespacedEventsAccessor, aK as NamespacedFacts, aL as ObservableKeys, aM as RequirementExplanation, aN as RequirementOutput, aO as RequirementPayloadSchema, aP as RequirementsSchema, aQ as ResolverContext, aR as ResolversControl, aS as SnapshotMeta, aT as SystemEvent, aU as TraceConfig, aV as TypedConstraintDef, b as TypedConstraintsDef, T as TypedDerivationsDef, a as TypedEventsDef, aW as TypedResolverContext, aX as TypedResolverDef, c as TypedResolversDef, aY as UnionEvents } from './plugins-Dy1C8GtT.js';
3
- import { b as DerivationsDef, c as DerivedValues } from './helpers-D6LcRum7.js';
4
- export { d as DerivationState, T as TypedConstraint, e as TypedResolver, f as createConstraintFactory, g as createResolverFactory } from './helpers-D6LcRum7.js';
1
+ 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';
2
+ 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';
3
+ import { b as DerivationsDef, c as DerivedValues } from './helpers-h9PR2JSJ.js';
4
+ export { d as DerivationState, T as TypedConstraint, e as TypedResolver, f as createConstraintFactory, g as createResolverFactory } from './helpers-h9PR2JSJ.js';
5
5
  export { g as safeStringify } from './utils-BnQajqPu.js';
6
6
 
7
7
  /**
@@ -369,16 +369,6 @@ interface CreateEffectsOptions<S extends Schema> {
369
369
  */
370
370
  declare function createEffectsManager<S extends Schema>(options: CreateEffectsOptions<S>): EffectsManager<S>;
371
371
 
372
- /**
373
- * Constraints - Rules that produce requirements when conditions aren't met
374
- *
375
- * Features:
376
- * - Sync and async constraint evaluation
377
- * - Priority ordering (higher runs first)
378
- * - Timeout handling for async constraints
379
- * - Error isolation
380
- */
381
-
382
372
  /**
383
373
  * Manager returned by {@link createConstraintsManager} that evaluates
384
374
  * constraint rules against the current facts and produces unmet
@@ -512,6 +502,19 @@ interface ConstraintsManager<_S extends Schema> {
512
502
  * @param requirementType - The requirement type string to remove.
513
503
  */
514
504
  removeRequirementKey(requirementType: string): void;
505
+ /**
506
+ * Return the original {@link FactPredicate} spec a constraint was declared
507
+ * with — present only when the constraint's `when` was provided as data.
508
+ * Used by `system.inspect()` / `system.explain()` and devtools to render
509
+ * the clause structure.
510
+ */
511
+ getWhenSpec(id: string): FactPredicate<Record<string, unknown>> | undefined;
512
+ /**
513
+ * Evaluate a data-form `when` and return the per-clause breakdown
514
+ * (which clauses passed, which failed, against what fact values).
515
+ * Returns `undefined` for constraints whose `when` is a function.
516
+ */
517
+ explainWhen(id: string): ClauseResult[] | undefined;
515
518
  }
516
519
  /**
517
520
  * Configuration options accepted by {@link createConstraintsManager}.
@@ -622,6 +625,20 @@ interface ResolversManager<_S extends Schema> {
622
625
  * @param requirementId - The unique requirement ID to cancel.
623
626
  */
624
627
  cancel(requirementId: string): void;
628
+ /**
629
+ * Untrack an in-flight resolver by requirement ID **without** aborting it
630
+ * (RFC-0003 resolver constraint-binding).
631
+ *
632
+ * @remarks
633
+ * Used for bound resolvers whose triggering requirement was removed: the
634
+ * resolver runs to completion (its data writes land; the binding still
635
+ * guards owned facts) but it no longer occupies the `inflight` slot, so the
636
+ * same requirement re-dispatches cleanly if it returns. A no-op if the
637
+ * requirement is not in-flight.
638
+ *
639
+ * @param requirementId - The unique requirement ID to detach.
640
+ */
641
+ detach(requirementId: string): void;
625
642
  /**
626
643
  * Cancel every in-flight resolver and flush all pending batch queues.
627
644
  */
@@ -709,23 +726,18 @@ interface ResolversManager<_S extends Schema> {
709
726
  * Per-constraint binding info, used by RFC-1 (resolver constraint-binding).
710
727
  *
711
728
  * The engine wires this lookup into the resolvers manager so that a resolver
712
- * dispatched from a constraint with `bind: 'auto'` can re-evaluate the
713
- * constraint's `when()` predicate live on every fact write.
729
+ * dispatched from a constraint with an `owns` field knows which facts it
730
+ * *owns* writes to those are clobber-checked (see {@link createBoundFacts}).
714
731
  *
715
- * Returns `null` (or the lookup itself returns `undefined`) when the source
716
- * constraint is unknown, async, or has `bind: 'none'` in which case
717
- * binding is a no-op and the resolver behaves exactly as before.
732
+ * Returns `undefined`/`null` when the source constraint is unknown or has no
733
+ * `owns` field in which case binding is a no-op and the resolver behaves
734
+ * exactly as before.
718
735
  *
719
736
  * @internal
720
737
  */
721
- interface ConstraintBindingInfo<S extends Schema> {
722
- /** The constraint's `bind` mode (effective; async predicates are forced to `'none'`). */
723
- mode: ConstraintBindMode;
724
- /**
725
- * The constraint's `when()` predicate, narrowed to a sync signature.
726
- * Only populated when `mode === 'auto'` and the constraint is sync.
727
- */
728
- when: ((facts: Facts<S>) => boolean) | null;
738
+ interface ConstraintBindingInfo {
739
+ /** Fact keys the triggering resolver owns; writes to these are clobber-checked. */
740
+ readonly fields: readonly string[];
729
741
  }
730
742
  /**
731
743
  * Configuration options accepted by {@link createResolversManager}.
@@ -743,11 +755,10 @@ interface CreateResolversOptions<S extends Schema> {
743
755
  * Look up binding info for a source constraint id (RFC-1).
744
756
  *
745
757
  * Wired by the engine — given the `fromConstraint` of a `RequirementWithId`,
746
- * returns the constraint's effective bind mode + a synchronous `when()`
747
- * reference. Return `undefined` if the constraint is unknown or binding
748
- * does not apply.
758
+ * returns the constraint's owned fact keys. Return `undefined` if the
759
+ * constraint is unknown or has no `owns` field.
749
760
  */
750
- getConstraintBinding?: (constraintId: string) => ConstraintBindingInfo<S> | undefined;
761
+ getConstraintBinding?: (constraintId: string) => ConstraintBindingInfo | undefined;
751
762
  /** Called when a resolver begins execution. */
752
763
  onStart?: (resolver: string, req: RequirementWithId) => void;
753
764
  /** Called when a resolver completes successfully, with the wall-clock duration in ms. */
@@ -768,16 +779,15 @@ interface CreateResolversOptions<S extends Schema> {
768
779
  */
769
780
  onRequeue?: (requirementId: string) => void;
770
781
  }
771
- declare function createResolversManager<S extends Schema>(options: CreateResolversOptions<S>): ResolversManager<S>;
772
-
773
782
  /**
774
- * Plugin Architecture - Extensible middleware for Directive
783
+ * Creates a resolver manager that tracks active resolver instances and
784
+ * coordinates their lifecycle (start / complete / error / cancel) against
785
+ * the engine's requirement graph.
775
786
  *
776
- * Features:
777
- * - Lifecycle hooks for all engine events
778
- * - Multiple plugins can be composed
779
- * - Plugins execute in registration order
787
+ * @param options - resolver definitions, facts reference, and event hooks
788
+ * @returns the manager handle used by the engine to drive resolver invocations
780
789
  */
790
+ declare function createResolversManager<S extends Schema>(options: CreateResolversOptions<S>): ResolversManager<S>;
781
791
 
782
792
  /**
783
793
  * Internal manager that broadcasts lifecycle events to registered {@link Plugin} instances.
@@ -826,7 +836,7 @@ interface PluginManager<_S extends Schema = any> {
826
836
  emitDerivationInvalidate(id: string): void;
827
837
  emitReconcileStart(snapshot: FactsSnapshot<any>): void;
828
838
  emitReconcileEnd(result: ReconcileResult): void;
829
- emitConstraintEvaluate(id: string, active: boolean): void;
839
+ emitConstraintEvaluate(id: string, active: boolean, whenExplain?: ClauseResult[]): void;
830
840
  emitConstraintError(id: string, error: unknown): void;
831
841
  emitRequirementCreated(req: RequirementWithId): void;
832
842
  emitRequirementMet(req: RequirementWithId, byResolver: string): void;
package/dist/internals.js CHANGED
@@ -1,2 +1,2 @@
1
- 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-E2WETPLH.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
1
+ 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
2
2
  //# sourceMappingURL=internals.js.map