@plures/praxis 1.2.41 → 1.3.0

package/dist/browser/{chunk-BBP2F7TT.js → chunk-MJK3IYTJ.js}

@@ -1,6 +1,90 @@
 // 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") {
@@ -80,7 +164,13 @@ 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);
@@ -99,8 +189,31 @@ var LogicEngine = class {
         }
       }
       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",
@@ -109,21 +222,26 @@ 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 newState.facts) factMap.set(f.tag, f);
+        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 = [...newState.facts, ...newFacts];
+        mergedFacts = [...existingFacts, ...newFacts];
         break;
       case "none":
       default:
-        mergedFacts = [...newState.facts, ...newFacts];
+        mergedFacts = [...existingFacts, ...newFacts];
         break;
     }
     if (this.maxFacts > 0 && mergedFacts.length > this.maxFacts) {

package/dist/browser/{chunk-FCEH7WMH.js → chunk-N63K4KWS.js}

@@ -1,6 +1,6 @@
 import {
   createPraxisEngine
-} from "./chunk-BBP2F7TT.js";
+} from "./chunk-MJK3IYTJ.js";
 
 // src/core/rules.ts
 var PraxisRegistry = class {

package/dist/browser/{engine-65QDGCAN.js → engine-YIEGSX7U.js}

@@ -1,7 +1,7 @@
 import {
   LogicEngine,
   createPraxisEngine
-} from "./chunk-BBP2F7TT.js";
+} from "./chunk-MJK3IYTJ.js";
 export {
   LogicEngine,
   createPraxisEngine

package/dist/browser/index.d.ts

@@ -1,5 +1,5 @@
-import { L as LogicEngine, P as PraxisState, a as PraxisEvent, b as PraxisRegistry, R as RuleDescriptor, C as ConstraintDescriptor, c as ConstraintFn, d as Contract, e as RuleFn, f as PraxisFact, g as PraxisModule } from './reactive-engine.svelte-Cqd8Mod2.js';
-export { h as ConstraintId, i as PRAXIS_PROTOCOL_VERSION, j as PraxisDiagnostics, k as PraxisEngineOptions, l as PraxisStepConfig, m as PraxisStepFn, n as PraxisStepResult, o as ReactiveEngineOptions, p as ReactiveLogicEngine, q as RuleId, r as createPraxisEngine, s as createReactiveEngine } from './reactive-engine.svelte-Cqd8Mod2.js';
+import { L as LogicEngine, P as PraxisState, a as PraxisEvent, b as PraxisRegistry, R as RuleDescriptor, C as ConstraintDescriptor, c as ConstraintFn, d as Contract, e as RuleFn, f as PraxisFact, g as PraxisModule } from './reactive-engine.svelte-DjynI82A.js';
+export { h as ConstraintId, i as PRAXIS_PROTOCOL_VERSION, j as PraxisDiagnostics, k as PraxisEngineOptions, l as PraxisStepConfig, m as PraxisStepFn, n as PraxisStepResult, o as ReactiveEngineOptions, p as ReactiveLogicEngine, q as RuleId, r as createPraxisEngine, s as createReactiveEngine } from './reactive-engine.svelte-DjynI82A.js';
 import { LocalFirstOptions } from '@plures/pluresdb/local-first';
 
 /**

package/dist/browser/index.js

@@ -2,12 +2,12 @@ import {
   PraxisRegistry,
   ReactiveLogicEngine,
   createReactiveEngine
-} from "./chunk-FCEH7WMH.js";
+} from "./chunk-N63K4KWS.js";
 import {
   LogicEngine,
   PRAXIS_PROTOCOL_VERSION,
   createPraxisEngine
-} from "./chunk-BBP2F7TT.js";
+} from "./chunk-MJK3IYTJ.js";
 import {
   InMemoryPraxisDB,
   PluresDBPraxisAdapter,
@@ -1277,13 +1277,18 @@ var PraxisDBStore = class {
     const state = {
       context: this.context,
       facts: [],
+      events,
       meta: {}
     };
     const derivedFacts = [];
     for (const rule of rules) {
       try {
-        const facts = rule.impl(state, events);
-        derivedFacts.push(...facts);
+        const result = rule.impl(state, events);
+        if (Array.isArray(result)) {
+          derivedFacts.push(...result);
+        } else if (result && "kind" in result && result.kind === "emit") {
+          derivedFacts.push(...result.facts);
+        }
       } catch (error) {
         this.onRuleError(rule.id, error);
       }
@@ -2889,7 +2894,7 @@ function generateTauriConfig(config) {
 
 // src/integrations/unified.ts
 async function createUnifiedApp(config) {
-  const { createPraxisEngine: createPraxisEngine2 } = await import("./engine-65QDGCAN.js");
+  const { createPraxisEngine: createPraxisEngine2 } = await import("./engine-YIEGSX7U.js");
   const { createInMemoryDB: createInMemoryDB2 } = await import("./adapter-CIMBGDC7.js");
   const db = config.db || createInMemoryDB2();
   const pluresdb = createPluresDBAdapter({

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

@@ -1,5 +1,5 @@
-import { P as PraxisState, a as PraxisEvent, L as LogicEngine } from '../reactive-engine.svelte-Cqd8Mod2.js';
-export { o as ReactiveEngineOptions, p as ReactiveLogicEngine, s as createReactiveEngine } from '../reactive-engine.svelte-Cqd8Mod2.js';
+import { P as PraxisState, a as PraxisEvent, L as LogicEngine } from '../reactive-engine.svelte-DjynI82A.js';
+export { o as ReactiveEngineOptions, p as ReactiveLogicEngine, s as createReactiveEngine } from '../reactive-engine.svelte-DjynI82A.js';
 
 /**
  * Svelte v5 Integration

package/dist/browser/integrations/svelte.js

@@ -1,8 +1,8 @@
 import {
   ReactiveLogicEngine,
   createReactiveEngine
-} from "../chunk-FCEH7WMH.js";
-import "../chunk-BBP2F7TT.js";
+} from "../chunk-N63K4KWS.js";
+import "../chunk-MJK3IYTJ.js";
 
 // src/integrations/svelte.ts
 function createPraxisStore(engine) {

package/dist/browser/{reactive-engine.svelte-Cqd8Mod2.d.ts → reactive-engine.svelte-DjynI82A.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) */
@@ -218,6 +225,71 @@ interface ContractGap {
     message?: 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;
+}
+
 /**
  * Rules and Constraints System
  *
@@ -238,13 +310,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.

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

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

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

@@ -1,6 +1,93 @@
 // 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;
+  }
+};
+function fact(tag, payload) {
+  return { tag, payload };
+}
+
 // src/core/engine.ts
 function safeClone(value) {
   if (value === null || typeof value !== "object") {
@@ -80,7 +167,13 @@ 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);
@@ -99,8 +192,31 @@ var LogicEngine = class {
         }
       }
       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",
@@ -109,21 +225,26 @@ 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 newState.facts) factMap.set(f.tag, f);
+        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 = [...newState.facts, ...newFacts];
+        mergedFacts = [...existingFacts, ...newFacts];
         break;
       case "none":
       default:
-        mergedFacts = [...newState.facts, ...newFacts];
+        mergedFacts = [...existingFacts, ...newFacts];
         break;
     }
     if (this.maxFacts > 0 && mergedFacts.length > this.maxFacts) {
@@ -261,6 +382,8 @@ function createPraxisEngine(options) {
 
 export {
   PRAXIS_PROTOCOL_VERSION,
+  RuleResult,
+  fact,
   LogicEngine,
   createPraxisEngine
 };

package/dist/node/cloud/index.d.cts

@@ -1,4 +1,4 @@
-import { b as PraxisFact, a as PraxisEvent } from '../protocol-BocKczNv.cjs';
+import { b as PraxisFact, a as PraxisEvent } from '../protocol-DcyGMmWY.cjs';
 
 /**
  * Cloud Relay Types

package/dist/node/cloud/index.d.ts

@@ -1,4 +1,4 @@
-import { b as PraxisFact, a as PraxisEvent } from '../protocol-BocKczNv.js';
+import { b as PraxisFact, a as PraxisEvent } from '../protocol-DcyGMmWY.js';
 
 /**
  * Cloud Relay Types

package/dist/node/{engine-7CXQV6RC.js → engine-FEN5IYZ5.js}

@@ -1,7 +1,7 @@
 import {
   LogicEngine,
   createPraxisEngine
-} from "./chunk-BBP2F7TT.js";
+} from "./chunk-KMJWAFZV.js";
 import "./chunk-QGM4M3NI.js";
 export {
   LogicEngine,