@plures/praxis 1.2.13 → 1.3.0

package/dist/browser/index.js

@@ -2,12 +2,12 @@ import {
   PraxisRegistry,
   ReactiveLogicEngine,
   createReactiveEngine
-} from "./chunk-K377RW4V.js";
+} from "./chunk-N63K4KWS.js";
 import {
   LogicEngine,
   PRAXIS_PROTOCOL_VERSION,
   createPraxisEngine
-} from "./chunk-VOMLVI6V.js";
+} from "./chunk-MJK3IYTJ.js";
 import {
   InMemoryPraxisDB,
   PluresDBPraxisAdapter,
@@ -586,6 +586,7 @@ function defineRule(options) {
     id: options.id,
     description: options.description,
     impl: options.impl,
+    eventTypes: options.eventTypes,
     contract,
     meta
   };
@@ -884,6 +885,53 @@ function validateForGeneration(schema) {
   };
 }
 
+// src/core/chronicle/context.ts
+var ChronicleContext = class {
+  static _stack = [];
+  /**
+   * Get the current active span, if any.
+   */
+  static get current() {
+    return this._stack[this._stack.length - 1];
+  }
+  /**
+   * Run a synchronous function within a causal span.
+   * The span is automatically popped when the function returns.
+   */
+  static run(span, fn) {
+    this._stack.push(span);
+    try {
+      return fn();
+    } finally {
+      this._stack.pop();
+    }
+  }
+  /**
+   * Run an async function within a causal span.
+   * The span is popped after the promise settles.
+   */
+  static async runAsync(span, fn) {
+    this._stack.push(span);
+    try {
+      return await fn();
+    } finally {
+      this._stack.pop();
+    }
+  }
+  /**
+   * Create a child span that inherits the current contextId.
+   *
+   * @param spanId ID for the new span
+   * @returns A new ChronicleSpan with the current contextId
+   */
+  static childSpan(spanId) {
+    return {
+      spanId,
+      contextId: this.current?.contextId
+    };
+  }
+};
+
 // src/core/pluresdb/store.ts
 var PRAXIS_PATHS = {
   /** Base path for all Praxis data */
@@ -919,12 +967,32 @@ var PraxisDBStore = class {
   subscriptions = [];
   factWatchers = /* @__PURE__ */ new Map();
   onRuleError;
+  chronicle;
   constructor(options) {
     this.db = options.db;
     this.registry = options.registry;
     this.context = options.initialContext ?? {};
     this.onRuleError = options.onRuleError ?? defaultErrorHandler;
   }
+  /**
+   * Attach a Chronicle observer to this store.
+   *
+   * Every subsequent `storeFact` and `appendEvent` call will be recorded as a
+   * causal graph node in PluresDB, enabling full observability for free.
+   *
+   * @param chronicle Chronicle implementation to attach
+   * @returns `this` for fluent chaining
+   *
+   * @example
+   * ```typescript
+   * const store = createPraxisDBStore(db, registry)
+   *   .withChronicle(createChronicle(db));
+   * ```
+   */
+  withChronicle(chronicle) {
+    this.chronicle = chronicle;
+    return this;
+  }
   /**
    * Store a fact in PluresDB
    *
@@ -939,7 +1007,31 @@ var PraxisDBStore = class {
     if (!constraintResult.valid) {
       throw new Error(`Constraint violation: ${constraintResult.errors.join(", ")}`);
     }
+    let before;
+    if (this.chronicle) {
+      const payload = fact.payload;
+      const id = payload?.id;
+      if (id) {
+        before = await this.getFact(fact.tag, id);
+      }
+    }
     await this.persistFact(fact);
+    if (this.chronicle) {
+      const payload = fact.payload;
+      const id = payload?.id ?? "";
+      const span = ChronicleContext.current;
+      try {
+        await this.chronicle.record({
+          path: getFactPath(fact.tag, id),
+          before,
+          after: fact,
+          cause: span?.spanId,
+          context: span?.contextId,
+          metadata: { factTag: fact.tag, operation: "storeFact" }
+        });
+      } catch {
+      }
+    }
     await this.triggerRules([fact]);
   }
   /**
@@ -953,7 +1045,31 @@ var PraxisDBStore = class {
       throw new Error(`Constraint violation: ${constraintResult.errors.join(", ")}`);
     }
     for (const fact of facts) {
+      let before;
+      if (this.chronicle) {
+        const payload = fact.payload;
+        const id = payload?.id;
+        if (id) {
+          before = await this.getFact(fact.tag, id);
+        }
+      }
       await this.persistFact(fact);
+      if (this.chronicle) {
+        const payload = fact.payload;
+        const id = payload?.id ?? "";
+        const span = ChronicleContext.current;
+        try {
+          await this.chronicle.record({
+            path: getFactPath(fact.tag, id),
+            before,
+            after: fact,
+            cause: span?.spanId,
+            context: span?.contextId,
+            metadata: { factTag: fact.tag, operation: "storeFacts" }
+          });
+        } catch {
+        }
+      }
     }
     await this.triggerRules(facts);
   }
@@ -995,7 +1111,29 @@ var PraxisDBStore = class {
     };
     const newEvents = [...existingEvents, entry];
     await this.db.set(path, newEvents);
-    await this.triggerRulesForEvents([event]);
+    let eventNodeId;
+    if (this.chronicle) {
+      const span = ChronicleContext.current;
+      try {
+        const node = await this.chronicle.record({
+          path,
+          before: existingEvents.length > 0 ? existingEvents[existingEvents.length - 1] : void 0,
+          after: entry,
+          cause: span?.spanId,
+          context: span?.contextId,
+          metadata: { eventTag: event.tag, sequence: String(entry.sequence), operation: "appendEvent" }
+        });
+        eventNodeId = node.id;
+      } catch {
+      }
+    }
+    const outerSpan = ChronicleContext.current;
+    const ruleSpan = eventNodeId ? { spanId: eventNodeId, contextId: outerSpan?.contextId } : outerSpan;
+    if (ruleSpan && this.chronicle) {
+      await ChronicleContext.runAsync(ruleSpan, () => this.triggerRulesForEvents([event]));
+    } else {
+      await this.triggerRulesForEvents([event]);
+    }
   }
   /**
    * Append multiple events to their respective streams
@@ -1008,6 +1146,7 @@ var PraxisDBStore = class {
       const existing = eventsByTag.get(event.tag) ?? [];
       eventsByTag.set(event.tag, [...existing, event]);
     }
+    let lastEventNodeId;
     for (const [tag, tagEvents] of eventsByTag) {
       const path = getEventPath(tag);
       const existingEvents = await this.db.get(path) ?? [];
@@ -1018,8 +1157,30 @@ var PraxisDBStore = class {
         sequence: sequence++
       }));
       await this.db.set(path, [...existingEvents, ...newEntries]);
+      if (this.chronicle) {
+        const span = ChronicleContext.current;
+        for (const entry of newEntries) {
+          try {
+            const node = await this.chronicle.record({
+              path,
+              after: entry,
+              cause: span?.spanId,
+              context: span?.contextId,
+              metadata: { eventTag: tag, sequence: String(entry.sequence), operation: "appendEvents" }
+            });
+            lastEventNodeId = node.id;
+          } catch {
+          }
+        }
+      }
+    }
+    const outerSpan = ChronicleContext.current;
+    const ruleSpan = lastEventNodeId ? { spanId: lastEventNodeId, contextId: outerSpan?.contextId } : outerSpan;
+    if (ruleSpan && this.chronicle) {
+      await ChronicleContext.runAsync(ruleSpan, () => this.triggerRulesForEvents(events));
+    } else {
+      await this.triggerRulesForEvents(events);
     }
-    await this.triggerRulesForEvents(events);
   }
   /**
    * Get events from a stream
@@ -1116,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);
       }
@@ -1132,6 +1298,21 @@ var PraxisDBStore = class {
       if (constraintResult.valid) {
         for (const fact of derivedFacts) {
           await this.persistFact(fact);
+          if (this.chronicle) {
+            const payload = fact.payload;
+            const id = payload?.id ?? "";
+            const span = ChronicleContext.current;
+            try {
+              await this.chronicle.record({
+                path: getFactPath(fact.tag, id),
+                after: fact,
+                cause: span?.spanId,
+                context: span?.contextId,
+                metadata: { factTag: fact.tag, operation: "derivedFact" }
+              });
+            } catch {
+            }
+          }
         }
       }
     }
@@ -2713,7 +2894,7 @@ function generateTauriConfig(config) {
 
 // src/integrations/unified.ts
 async function createUnifiedApp(config) {
-  const { createPraxisEngine: createPraxisEngine2 } = await import("./engine-YJZV4SLD.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 { L as LogicEngine, P as PraxisState, a as PraxisEvent } from '../reactive-engine.svelte-9aS0kTa8.js';
-export { q as ReactiveEngineOptions, r as ReactiveLogicEngine, s as createReactiveEngine } from '../reactive-engine.svelte-9aS0kTa8.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-K377RW4V.js";
-import "../chunk-VOMLVI6V.js";
+} from "../chunk-N63K4KWS.js";
+import "../chunk-MJK3IYTJ.js";
 
 // src/integrations/svelte.ts
 function createPraxisStore(engine) {

package/dist/browser/{reactive-engine.svelte-9aS0kTa8.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.
@@ -265,6 +344,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 +484,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 +508,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 +548,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 +572,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 +685,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-5JQJZADT.js}

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