@plures/praxis 1.2.41 → 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") {
@@ -275,7 +359,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);
@@ -294,8 +384,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",
@@ -304,21 +417,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/node/integrations/svelte.d.cts

@@ -1,6 +1,6 @@
-import { L as LogicEngine } from '../reactive-engine.svelte-CGe8SpVE.cjs';
-export { R as ReactiveEngineOptions, a as ReactiveLogicEngine, c as createReactiveEngine } from '../reactive-engine.svelte-CGe8SpVE.cjs';
-import { P as PraxisState, a as PraxisEvent } from '../protocol-BocKczNv.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-D-xTDxT5.js';
-export { R as ReactiveEngineOptions, a as ReactiveLogicEngine, c as createReactiveEngine } from '../reactive-engine.svelte-D-xTDxT5.js';
-import { P as PraxisState, a as PraxisEvent } from '../protocol-BocKczNv.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-32YFEEML.js";
+} from "../chunk-5JQJZADT.js";
 import "../chunk-R2PSBPKQ.js";
-import "../chunk-BBP2F7TT.js";
+import "../chunk-KMJWAFZV.js";
 import "../chunk-QGM4M3NI.js";
 
 // src/integrations/svelte.ts

package/dist/node/{protocol-BocKczNv.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) */

package/dist/node/{protocol-BocKczNv.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) */

package/dist/node/{reactive-engine.svelte-D-xTDxT5.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, e as PraxisDiagnostics } from './protocol-BocKczNv.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.
@@ -550,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, type ReactiveEngineOptions as R, type Severity as S, 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, createPraxisEngine as m, defineContract as n, getContract as o, isContract 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 };

package/dist/node/{reactive-engine.svelte-CGe8SpVE.d.cts → reactive-engine.svelte-DekxqFu0.d.ts}

@@ -1,4 +1,4 @@
-import { P as PraxisState, a as PraxisEvent, b as PraxisFact, c as PraxisStepResult, d as PraxisStepConfig, e as PraxisDiagnostics } from './protocol-BocKczNv.cjs';
+import { b as PraxisFact, P as PraxisState, a as PraxisEvent, c as PraxisStepResult, d as PraxisStepConfig, e as PraxisDiagnostics } from './protocol-DcyGMmWY.js';
 
 /**
  * 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.
@@ -550,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, type ReactiveEngineOptions as R, type Severity as S, 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, createPraxisEngine as m, defineContract as n, getContract as o, isContract 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 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plures/praxis",
-  "version": "1.2.41",
+  "version": "1.3.0",
   "description": "The Full Plures Application Framework - declarative schemas, logic engine, component generation, and local-first data",
   "type": "module",
   "packageManager": "pnpm@9.15.1",
@@ -138,4 +138,4 @@
   "publishConfig": {
     "access": "public"
   }
-}
+}