@plures/praxis 1.2.12 → 1.2.41

package/dist/browser/{reactive-engine.svelte-9aS0kTa8.d.ts → reactive-engine.svelte-Cqd8Mod2.d.ts}

@@ -265,6 +265,18 @@ interface RuleDescriptor<TContext = unknown> {
     description: string;
     /** Implementation function */
     impl: RuleFn<TContext>;
+    /**
+     * Optional event type filter — only evaluate this rule when at least one
+     * event in the batch has a matching `tag`. When omitted, the rule runs on
+     * every step (catch-all).
+     *
+     * Accepts a single tag string or an array of tags.
+     *
+     * @example
+     * { id: 'sprint-behind', eventTypes: ['sprint.update'], impl: ... }
+     * { id: 'note-check', eventTypes: 'note.update', impl: ... }
+     */
+    eventTypes?: string | string[];
     /** Optional contract for rule behavior */
     contract?: Contract;
     /** Optional metadata */
@@ -393,6 +405,20 @@ interface PraxisEngineOptions<TContext = unknown> {
     initialFacts?: PraxisFact[];
     /** Initial metadata (optional) */
     initialMeta?: Record<string, unknown>;
+    /**
+     * Fact deduplication strategy (default: 'last-write-wins').
+     *
+     * - 'none': facts accumulate without dedup (original behavior)
+     * - 'last-write-wins': only keep the latest fact per tag (most common)
+     * - 'append': keep all facts but cap at maxFacts
+     */
+    factDedup?: 'none' | 'last-write-wins' | 'append';
+    /**
+     * Maximum number of facts to retain (default: 1000).
+     * When exceeded, oldest facts are evicted (FIFO).
+     * Set to 0 for unlimited (not recommended).
+     */
+    maxFacts?: number;
 }
 /**
  * The Praxis Logic Engine
@@ -403,6 +429,8 @@ interface PraxisEngineOptions<TContext = unknown> {
 declare class LogicEngine<TContext = unknown> {
     private state;
     private readonly registry;
+    private readonly factDedup;
+    private readonly maxFacts;
     constructor(options: PraxisEngineOptions<TContext>);
     /**
      * Get the current state (immutable copy)
@@ -441,6 +469,23 @@ declare class LogicEngine<TContext = unknown> {
      * @param updater Function that produces new context from old context
      */
     updateContext(updater: (context: TContext) => TContext): void;
+    /**
+     * Atomically update context AND process events in a single call.
+     *
+     * This avoids the fragile pattern of calling updateContext() then step()
+     * separately, where rules could see stale context if the ordering is wrong.
+     *
+     * @param updater Function that produces new context from old context
+     * @param events Events to process after context is updated
+     * @returns Result with new state and diagnostics
+     *
+     * @example
+     * engine.stepWithContext(
+     *   ctx => ({ ...ctx, sprintName: sprint.name, items: sprint.items }),
+     *   [{ tag: 'sprint.update', payload: { name: sprint.name } }]
+     * );
+     */
+    stepWithContext(updater: (context: TContext) => TContext, events: PraxisEvent[]): PraxisStepResult;
     /**
      * Add facts directly (for exceptional cases).
      * Generally, facts should be added through rules.
@@ -448,6 +493,16 @@ declare class LogicEngine<TContext = unknown> {
      * @param facts Facts to add
      */
     addFacts(facts: PraxisFact[]): void;
+    /**
+     * Check all constraints without processing any events.
+     *
+     * Useful for validation-only scenarios (e.g., form validation,
+     * pre-save checks) where you want constraint diagnostics without
+     * triggering any rules.
+     *
+     * @returns Array of constraint violation diagnostics (empty = all passing)
+     */
+    checkConstraints(): PraxisDiagnostics[];
     /**
      * Clear all facts
      */
@@ -551,4 +606,4 @@ declare class ReactiveLogicEngine<TContext extends object> {
  */
 declare function createReactiveEngine<TContext extends object>(options: ReactiveEngineOptions<TContext>): ReactiveLogicEngine<TContext>;
 
-export { type ConstraintDescriptor as C, LogicEngine as L, type PraxisState as P, type RuleDescriptor as R, type PraxisEvent as a, PraxisRegistry as b, type PraxisFact as c, type RuleFn as d, type Contract as e, type ConstraintFn as f, type PraxisModule as g, type PraxisDiagnostics as h, type PraxisStepConfig as i, type PraxisStepResult as j, type PraxisStepFn as k, PRAXIS_PROTOCOL_VERSION as l, type RuleId as m, type ConstraintId as n, type PraxisEngineOptions as o, createPraxisEngine as p, type ReactiveEngineOptions as q, ReactiveLogicEngine as r, createReactiveEngine as s };
+export { type ConstraintDescriptor as C, LogicEngine as L, type PraxisState as P, type RuleDescriptor as R, type PraxisEvent as a, PraxisRegistry as b, type ConstraintFn as c, type Contract as d, type RuleFn as e, type PraxisFact as f, type PraxisModule as g, type ConstraintId as h, PRAXIS_PROTOCOL_VERSION as i, type PraxisDiagnostics as j, type PraxisEngineOptions as k, type PraxisStepConfig as l, type PraxisStepFn as m, type PraxisStepResult as n, type ReactiveEngineOptions as o, ReactiveLogicEngine as p, type RuleId as q, createPraxisEngine as r, createReactiveEngine as s };

package/dist/node/{chunk-PRPQO6R5.js → chunk-32YFEEML.js}

@@ -3,7 +3,7 @@ import {
 } from "./chunk-R2PSBPKQ.js";
 import {
   createPraxisEngine
-} from "./chunk-VOMLVI6V.js";
+} from "./chunk-BBP2F7TT.js";
 
 // src/core/reactive-engine.svelte.ts
 import * as $ from "svelte/internal/client";

package/dist/node/{chunk-VOMLVI6V.js → chunk-BBP2F7TT.js}

@@ -20,8 +20,12 @@ function safeClone(value) {
 var LogicEngine = class {
   state;
   registry;
+  factDedup;
+  maxFacts;
   constructor(options) {
     this.registry = options.registry;
+    this.factDedup = options.factDedup ?? "last-write-wins";
+    this.maxFacts = options.maxFacts ?? 1e3;
     this.state = {
       context: options.initialContext,
       facts: options.initialFacts ?? [],
@@ -77,6 +81,7 @@ var LogicEngine = class {
     const diagnostics = [];
     let newState = { ...this.state };
     const newFacts = [];
+    const eventTags = new Set(events.map((e) => e.tag));
     for (const ruleId of config.ruleIds) {
       const rule = this.registry.getRule(ruleId);
       if (!rule) {
@@ -87,6 +92,12 @@ var LogicEngine = class {
         });
         continue;
       }
+      if (rule.eventTypes) {
+        const filterTags = Array.isArray(rule.eventTypes) ? rule.eventTypes : [rule.eventTypes];
+        if (!filterTags.some((t) => eventTags.has(t))) {
+          continue;
+        }
+      }
       try {
         const ruleFacts = rule.impl(newState, events);
         newFacts.push(...ruleFacts);
@@ -98,9 +109,29 @@ var LogicEngine = class {
         });
       }
     }
+    let mergedFacts;
+    switch (this.factDedup) {
+      case "last-write-wins": {
+        const factMap = /* @__PURE__ */ new Map();
+        for (const f of newState.facts) factMap.set(f.tag, f);
+        for (const f of newFacts) factMap.set(f.tag, f);
+        mergedFacts = Array.from(factMap.values());
+        break;
+      }
+      case "append":
+        mergedFacts = [...newState.facts, ...newFacts];
+        break;
+      case "none":
+      default:
+        mergedFacts = [...newState.facts, ...newFacts];
+        break;
+    }
+    if (this.maxFacts > 0 && mergedFacts.length > this.maxFacts) {
+      mergedFacts = mergedFacts.slice(mergedFacts.length - this.maxFacts);
+    }
     newState = {
       ...newState,
-      facts: [...newState.facts, ...newFacts]
+      facts: mergedFacts
     };
     for (const constraintId of config.constraintIds) {
       const constraint = this.registry.getConstraint(constraintId);
@@ -153,6 +184,29 @@ var LogicEngine = class {
       context: updater(this.state.context)
     };
   }
+  /**
+   * Atomically update context AND process events in a single call.
+   *
+   * This avoids the fragile pattern of calling updateContext() then step()
+   * separately, where rules could see stale context if the ordering is wrong.
+   *
+   * @param updater Function that produces new context from old context
+   * @param events Events to process after context is updated
+   * @returns Result with new state and diagnostics
+   *
+   * @example
+   * engine.stepWithContext(
+   *   ctx => ({ ...ctx, sprintName: sprint.name, items: sprint.items }),
+   *   [{ tag: 'sprint.update', payload: { name: sprint.name } }]
+   * );
+   */
+  stepWithContext(updater, events) {
+    this.state = {
+      ...this.state,
+      context: updater(this.state.context)
+    };
+    return this.step(events);
+  }
   /**
    * Add facts directly (for exceptional cases).
    * Generally, facts should be added through rules.
@@ -165,6 +219,21 @@ var LogicEngine = class {
       facts: [...this.state.facts, ...facts]
     };
   }
+  /**
+   * Check all constraints without processing any events.
+   *
+   * Useful for validation-only scenarios (e.g., form validation,
+   * pre-save checks) where you want constraint diagnostics without
+   * triggering any rules.
+   *
+   * @returns Array of constraint violation diagnostics (empty = all passing)
+   */
+  checkConstraints() {
+    return this.stepWithConfig([], {
+      ruleIds: [],
+      constraintIds: this.registry.getConstraintIds()
+    }).diagnostics;
+  }
   /**
    * Clear all facts
    */

package/dist/node/{chunk-5RH7UAQC.js → chunk-PTH6MD6P.js}

@@ -32,6 +32,7 @@ function defineRule(options) {
     id: options.id,
     description: options.description,
     impl: options.impl,
+    eventTypes: options.eventTypes,
     contract,
     meta
   };