@plures/praxis 1.2.13 → 1.3.0

package/dist/node/integrations/svelte.cjs

@@ -196,6 +196,90 @@ var PraxisRegistry = class {
 // src/core/protocol.ts
 var PRAXIS_PROTOCOL_VERSION = "1.0.0";
 
+// src/core/rule-result.ts
+var RuleResult = class _RuleResult {
+  /** The kind of result */
+  kind;
+  /** Facts produced (only for 'emit') */
+  facts;
+  /** Fact tags to retract (only for 'retract') */
+  retractTags;
+  /** Optional reason (for noop/skip/retract — useful for debugging) */
+  reason;
+  /** The rule ID that produced this result (set by engine) */
+  ruleId;
+  constructor(kind, facts, retractTags, reason) {
+    this.kind = kind;
+    this.facts = facts;
+    this.retractTags = retractTags;
+    this.reason = reason;
+  }
+  /**
+   * Rule produced facts.
+   *
+   * @example
+   * return RuleResult.emit([
+   *   { tag: 'sprint.behind', payload: { deficit: 5 } }
+   * ]);
+   */
+  static emit(facts) {
+    if (facts.length === 0) {
+      throw new Error(
+        "RuleResult.emit() requires at least one fact. Use RuleResult.noop() or RuleResult.skip() when a rule has nothing to say."
+      );
+    }
+    return new _RuleResult("emit", facts, []);
+  }
+  /**
+   * Rule evaluated but had nothing to report.
+   * Unlike returning [], this is explicit and traceable.
+   *
+   * @example
+   * if (ctx.completedHours >= expectedHours) {
+   *   return RuleResult.noop('Sprint is on pace');
+   * }
+   */
+  static noop(reason) {
+    return new _RuleResult("noop", [], [], reason);
+  }
+  /**
+   * Rule decided to skip because preconditions were not met.
+   * Distinct from noop: skip means "I can't evaluate", noop means "I evaluated and found nothing".
+   *
+   * @example
+   * if (!ctx.sprintName) {
+   *   return RuleResult.skip('No active sprint');
+   * }
+   */
+  static skip(reason) {
+    return new _RuleResult("skip", [], [], reason);
+  }
+  /**
+   * Rule retracts previously emitted facts by tag.
+   * Used when a condition that previously produced facts is no longer true.
+   *
+   * @example
+   * // Sprint was behind, but caught up
+   * if (ctx.completedHours >= expectedHours) {
+   *   return RuleResult.retract(['sprint.behind'], 'Sprint caught up');
+   * }
+   */
+  static retract(tags, reason) {
+    if (tags.length === 0) {
+      throw new Error("RuleResult.retract() requires at least one tag.");
+    }
+    return new _RuleResult("retract", [], tags, reason);
+  }
+  /** Whether this result produced facts */
+  get hasFacts() {
+    return this.facts.length > 0;
+  }
+  /** Whether this result retracts facts */
+  get hasRetractions() {
+    return this.retractTags.length > 0;
+  }
+};
+
 // src/core/engine.ts
 function safeClone(value) {
   if (value === null || typeof value !== "object") {
@@ -215,8 +299,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 ?? [],
@@ -271,7 +359,14 @@ var LogicEngine = class {
   stepWithConfig(events, config) {
     const diagnostics = [];
     let newState = { ...this.state };
+    const stateWithEvents = {
+      ...newState,
+      events
+      // current batch — rules can read state.events
+    };
     const newFacts = [];
+    const retractions = [];
+    const eventTags = new Set(events.map((e) => e.tag));
     for (const ruleId of config.ruleIds) {
       const rule = this.registry.getRule(ruleId);
       if (!rule) {
@@ -282,9 +377,38 @@ 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);
+        const rawResult = rule.impl(stateWithEvents, events);
+        if (rawResult instanceof RuleResult) {
+          rawResult.ruleId = ruleId;
+          switch (rawResult.kind) {
+            case "emit":
+              newFacts.push(...rawResult.facts);
+              break;
+            case "retract":
+              retractions.push(...rawResult.retractTags);
+              break;
+            case "noop":
+            case "skip":
+              if (rawResult.reason) {
+                diagnostics.push({
+                  kind: "rule-error",
+                  // reused kind — could add 'rule-trace' in protocol v2
+                  message: `[${rawResult.kind}] ${ruleId}: ${rawResult.reason}`,
+                  data: { ruleId, resultKind: rawResult.kind, reason: rawResult.reason }
+                });
+              }
+              break;
+          }
+        } else if (Array.isArray(rawResult)) {
+          newFacts.push(...rawResult);
+        }
       } catch (error) {
         diagnostics.push({
           kind: "rule-error",
@@ -293,9 +417,34 @@ var LogicEngine = class {
         });
       }
     }
+    let existingFacts = newState.facts;
+    if (retractions.length > 0) {
+      const retractSet = new Set(retractions);
+      existingFacts = existingFacts.filter((f) => !retractSet.has(f.tag));
+    }
+    let mergedFacts;
+    switch (this.factDedup) {
+      case "last-write-wins": {
+        const factMap = /* @__PURE__ */ new Map();
+        for (const f of existingFacts) factMap.set(f.tag, f);
+        for (const f of newFacts) factMap.set(f.tag, f);
+        mergedFacts = Array.from(factMap.values());
+        break;
+      }
+      case "append":
+        mergedFacts = [...existingFacts, ...newFacts];
+        break;
+      case "none":
+      default:
+        mergedFacts = [...existingFacts, ...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);
@@ -348,6 +497,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.
@@ -360,6 +532,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/integrations/svelte.d.cts

@@ -1,6 +1,6 @@
-import { L as LogicEngine } from '../reactive-engine.svelte-BFIZfawz.cjs';
-export { a as ReactiveEngineOptions, R as ReactiveLogicEngine, c as createReactiveEngine } from '../reactive-engine.svelte-BFIZfawz.cjs';
-import { P as PraxisState, a as PraxisEvent } from '../protocol-Qek7ebBl.cjs';
+import { L as LogicEngine } from '../reactive-engine.svelte-Cg0Yc2Hs.cjs';
+export { R as ReactiveEngineOptions, a as ReactiveLogicEngine, c as createReactiveEngine } from '../reactive-engine.svelte-Cg0Yc2Hs.cjs';
+import { P as PraxisState, a as PraxisEvent } from '../protocol-DcyGMmWY.cjs';
 
 /**
  * Svelte v5 Integration

package/dist/node/integrations/svelte.d.ts

@@ -1,6 +1,6 @@
-import { L as LogicEngine } from '../reactive-engine.svelte-CRNqHlbv.js';
-export { a as ReactiveEngineOptions, R as ReactiveLogicEngine, c as createReactiveEngine } from '../reactive-engine.svelte-CRNqHlbv.js';
-import { P as PraxisState, a as PraxisEvent } from '../protocol-Qek7ebBl.js';
+import { L as LogicEngine } from '../reactive-engine.svelte-DekxqFu0.js';
+export { R as ReactiveEngineOptions, a as ReactiveLogicEngine, c as createReactiveEngine } from '../reactive-engine.svelte-DekxqFu0.js';
+import { P as PraxisState, a as PraxisEvent } from '../protocol-DcyGMmWY.js';
 
 /**
  * Svelte v5 Integration

package/dist/node/integrations/svelte.js

@@ -1,9 +1,9 @@
 import {
   ReactiveLogicEngine,
   createReactiveEngine
-} from "../chunk-PRPQO6R5.js";
+} from "../chunk-5JQJZADT.js";
 import "../chunk-R2PSBPKQ.js";
-import "../chunk-VOMLVI6V.js";
+import "../chunk-KMJWAFZV.js";
 import "../chunk-QGM4M3NI.js";
 
 // src/integrations/svelte.ts

package/dist/node/{protocol-Qek7ebBl.d.ts → protocol-DcyGMmWY.d.cts}

@@ -71,6 +71,13 @@ interface PraxisState {
     context: unknown;
     /** Current facts about the domain */
     facts: PraxisFact[];
+    /**
+     * Events currently being processed in this step.
+     * Available to rules during execution — guaranteed to contain the exact
+     * events passed to step()/stepWithContext().
+     * Empty outside of step execution.
+     */
+    events?: PraxisEvent[];
     /** Optional metadata (timestamps, version, etc.) */
     meta?: Record<string, unknown>;
     /** Protocol version (for cross-language compatibility) */
@@ -119,4 +126,4 @@ interface PraxisStepResult {
  */
 type PraxisStepFn = (state: PraxisState, events: PraxisEvent[], config: PraxisStepConfig) => PraxisStepResult;
 
-export { type PraxisState as P, type PraxisEvent as a, type PraxisFact as b, type PraxisStepResult as c, type PraxisStepConfig as d, type PraxisDiagnostics as e, type PraxisStepFn as f, PRAXIS_PROTOCOL_VERSION as g };
+export { type PraxisState as P, type PraxisEvent as a, type PraxisFact as b, type PraxisStepResult as c, type PraxisStepConfig as d, type PraxisDiagnostics as e, PRAXIS_PROTOCOL_VERSION as f, type PraxisStepFn as g };

package/dist/node/{protocol-Qek7ebBl.d.cts → protocol-DcyGMmWY.d.ts}

@@ -71,6 +71,13 @@ interface PraxisState {
     context: unknown;
     /** Current facts about the domain */
     facts: PraxisFact[];
+    /**
+     * Events currently being processed in this step.
+     * Available to rules during execution — guaranteed to contain the exact
+     * events passed to step()/stepWithContext().
+     * Empty outside of step execution.
+     */
+    events?: PraxisEvent[];
     /** Optional metadata (timestamps, version, etc.) */
     meta?: Record<string, unknown>;
     /** Protocol version (for cross-language compatibility) */
@@ -119,4 +126,4 @@ interface PraxisStepResult {
  */
 type PraxisStepFn = (state: PraxisState, events: PraxisEvent[], config: PraxisStepConfig) => PraxisStepResult;
 
-export { type PraxisState as P, type PraxisEvent as a, type PraxisFact as b, type PraxisStepResult as c, type PraxisStepConfig as d, type PraxisDiagnostics as e, type PraxisStepFn as f, PRAXIS_PROTOCOL_VERSION as g };
+export { type PraxisState as P, type PraxisEvent as a, type PraxisFact as b, type PraxisStepResult as c, type PraxisStepConfig as d, type PraxisDiagnostics as e, PRAXIS_PROTOCOL_VERSION as f, type PraxisStepFn as g };

package/dist/node/{reactive-engine.svelte-CRNqHlbv.d.ts → reactive-engine.svelte-Cg0Yc2Hs.d.cts}

@@ -1,4 +1,4 @@
-import { P as PraxisState, a as PraxisEvent, b as PraxisFact, c as PraxisStepResult, d as PraxisStepConfig } from './protocol-Qek7ebBl.js';
+import { b as PraxisFact, P as PraxisState, a as PraxisEvent, c as PraxisStepResult, d as PraxisStepConfig, e as PraxisDiagnostics } from './protocol-DcyGMmWY.cjs';
 
 /**
  * Decision Ledger - Contract Types
@@ -162,6 +162,83 @@ interface ValidationReport {
     timestamp: string;
 }
 
+/**
+ * The result of evaluating a rule. Every rule MUST return one of:
+ * - `RuleResult.emit(facts)` — rule produced facts
+ * - `RuleResult.noop(reason?)` — rule evaluated but had nothing to say
+ * - `RuleResult.skip(reason?)` — rule decided to skip (preconditions not met)
+ * - `RuleResult.retract(tags)` — rule retracts previously emitted facts
+ */
+declare class RuleResult {
+    /** The kind of result */
+    readonly kind: 'emit' | 'noop' | 'skip' | 'retract';
+    /** Facts produced (only for 'emit') */
+    readonly facts: PraxisFact[];
+    /** Fact tags to retract (only for 'retract') */
+    readonly retractTags: string[];
+    /** Optional reason (for noop/skip/retract — useful for debugging) */
+    readonly reason?: string;
+    /** The rule ID that produced this result (set by engine) */
+    ruleId?: string;
+    private constructor();
+    /**
+     * Rule produced facts.
+     *
+     * @example
+     * return RuleResult.emit([
+     *   { tag: 'sprint.behind', payload: { deficit: 5 } }
+     * ]);
+     */
+    static emit(facts: PraxisFact[]): RuleResult;
+    /**
+     * Rule evaluated but had nothing to report.
+     * Unlike returning [], this is explicit and traceable.
+     *
+     * @example
+     * if (ctx.completedHours >= expectedHours) {
+     *   return RuleResult.noop('Sprint is on pace');
+     * }
+     */
+    static noop(reason?: string): RuleResult;
+    /**
+     * Rule decided to skip because preconditions were not met.
+     * Distinct from noop: skip means "I can't evaluate", noop means "I evaluated and found nothing".
+     *
+     * @example
+     * if (!ctx.sprintName) {
+     *   return RuleResult.skip('No active sprint');
+     * }
+     */
+    static skip(reason?: string): RuleResult;
+    /**
+     * Rule retracts previously emitted facts by tag.
+     * Used when a condition that previously produced facts is no longer true.
+     *
+     * @example
+     * // Sprint was behind, but caught up
+     * if (ctx.completedHours >= expectedHours) {
+     *   return RuleResult.retract(['sprint.behind'], 'Sprint caught up');
+     * }
+     */
+    static retract(tags: string[], reason?: string): RuleResult;
+    /** Whether this result produced facts */
+    get hasFacts(): boolean;
+    /** Whether this result retracts facts */
+    get hasRetractions(): boolean;
+}
+/**
+ * A rule function that returns a typed RuleResult.
+ * New API — replaces the old PraxisFact[] return type.
+ */
+type TypedRuleFn<TContext = unknown> = (state: PraxisState & {
+    context: TContext;
+    events: PraxisEvent[];
+}, events: PraxisEvent[]) => RuleResult;
+/**
+ * Convenience: create a fact object (just a shorthand)
+ */
+declare function fact(tag: string, payload: unknown): PraxisFact;
+
 /**
  * Rules and Constraints System
  *
@@ -182,13 +259,20 @@ type ConstraintId = string;
  * A rule function derives new facts or transitions from context + input facts/events.
  * Rules must be pure - no side effects.
  *
- * @param state Current Praxis state
- * @param events Events to process
- * @returns Array of new facts to add to the state
+ * Returns either:
+ * - `RuleResult` (new API — typed, traceable, supports retraction)
+ * - `PraxisFact[]` (legacy — backward compatible, will be deprecated)
+ *
+ * The state parameter includes `events` — the current batch being processed.
+ *
+ * @param state Current Praxis state (includes state.events for current batch)
+ * @param events Events to process (same as state.events, provided for convenience)
+ * @returns RuleResult or array of new facts
  */
 type RuleFn<TContext = unknown> = (state: PraxisState & {
     context: TContext;
-}, events: PraxisEvent[]) => PraxisFact[];
+    events: PraxisEvent[];
+}, events: PraxisEvent[]) => RuleResult | PraxisFact[];
 /**
  * A constraint function checks that an invariant holds.
  * Constraints must be pure - no side effects.
@@ -209,6 +293,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 */
@@ -337,6 +433,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
@@ -347,6 +457,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)
@@ -385,6 +497,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.
@@ -392,6 +521,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
      */
@@ -495,4 +634,4 @@ declare class ReactiveLogicEngine<TContext extends object> {
  */
 declare function createReactiveEngine<TContext extends object>(options: ReactiveEngineOptions<TContext>): ReactiveLogicEngine<TContext>;
 
-export { type Assumption as A, type ConstraintDescriptor as C, type DefineContractOptions as D, type Example as E, LogicEngine as L, type MissingArtifact as M, PraxisRegistry as P, ReactiveLogicEngine as R, type Severity as S, type ValidationReport as V, type ReactiveEngineOptions as a, type RuleDescriptor as b, createReactiveEngine as c, type RuleFn as d, type Contract as e, type ConstraintFn as f, type PraxisModule as g, type RuleId as h, type ConstraintId as i, type PraxisEngineOptions as j, createPraxisEngine as k, defineContract as l, getContract as m, isContract as n, type Reference as o, type ContractGap as p };
+export { type Assumption as A, type ConstraintDescriptor as C, type DefineContractOptions as D, type Example as E, LogicEngine as L, type MissingArtifact as M, PraxisRegistry as P, type ReactiveEngineOptions as R, type Severity as S, type TypedRuleFn as T, type ValidationReport as V, ReactiveLogicEngine as a, type RuleDescriptor as b, createReactiveEngine as c, type ConstraintFn as d, type Contract as e, type RuleFn as f, type PraxisModule as g, type ConstraintId as h, type ContractGap as i, type PraxisEngineOptions as j, type Reference as k, type RuleId as l, RuleResult as m, createPraxisEngine as n, defineContract as o, fact as p, getContract as q, isContract as r };