@plures/praxis 1.2.12 → 1.2.41

package/dist/node/index.js

@@ -21,7 +21,7 @@ import {
   formatValidationReportJSON,
   formatValidationReportSARIF,
   validateContracts
-} from "./chunk-5RH7UAQC.js";
+} from "./chunk-PTH6MD6P.js";
 import {
   defineContract,
   getContract,
@@ -50,7 +50,7 @@ import {
 import {
   ReactiveLogicEngine,
   createReactiveEngine
-} from "./chunk-PRPQO6R5.js";
+} from "./chunk-32YFEEML.js";
 import {
   PraxisRegistry
 } from "./chunk-R2PSBPKQ.js";
@@ -79,7 +79,7 @@ import {
   LogicEngine,
   PRAXIS_PROTOCOL_VERSION,
   createPraxisEngine
-} from "./chunk-VOMLVI6V.js";
+} from "./chunk-BBP2F7TT.js";
 import "./chunk-QGM4M3NI.js";
 
 // src/core/reactive-engine.ts
@@ -622,6 +622,53 @@ function createIntrospector(registry) {
   return new RegistryIntrospector(registry);
 }
 
+// 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 */
@@ -657,12 +704,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
    *
@@ -677,7 +744,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]);
   }
   /**
@@ -691,7 +782,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);
   }
@@ -733,7 +848,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
@@ -746,6 +883,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) ?? [];
@@ -756,8 +894,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
@@ -870,6 +1030,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 {
+            }
+          }
         }
       }
     }
@@ -989,6 +1164,156 @@ function createSchemaRegistry(db) {
   return new PraxisSchemaRegistry(db);
 }
 
+// src/core/chronicle/chronicle.ts
+var CHRONICLE_PATHS = {
+  BASE: "/_praxis/chronos",
+  NODES: "/_praxis/chronos/nodes",
+  EDGES_OUT: "/_praxis/chronos/edges/out",
+  EDGES_IN: "/_praxis/chronos/edges/in",
+  CONTEXT: "/_praxis/chronos/context",
+  INDEX: "/_praxis/chronos/index"
+};
+var _nodeCounter = 0;
+var PluresDbChronicle = class {
+  db;
+  constructor(db) {
+    this.db = db;
+  }
+  async record(event) {
+    const timestamp = Date.now();
+    const id = `chronos:${timestamp}-${++_nodeCounter}`;
+    const node = { id, timestamp, event };
+    await this.db.set(`${CHRONICLE_PATHS.NODES}/${id}`, node);
+    const index = await this.db.get(CHRONICLE_PATHS.INDEX) ?? [];
+    await this.db.set(CHRONICLE_PATHS.INDEX, [...index, id]);
+    if (event.cause) {
+      await this.addEdge(event.cause, id, "causes");
+    }
+    if (event.context) {
+      const contextPath = `${CHRONICLE_PATHS.CONTEXT}/${event.context}`;
+      const contextNodes = await this.db.get(contextPath) ?? [];
+      if (contextNodes.length > 0) {
+        const prevId = contextNodes[contextNodes.length - 1];
+        await this.addEdge(prevId, id, "follows");
+      }
+      await this.db.set(contextPath, [...contextNodes, id]);
+    }
+    return node;
+  }
+  async trace(nodeId, direction, maxDepth) {
+    const visited = /* @__PURE__ */ new Set();
+    const result = [];
+    await this._traceRecursive(nodeId, direction, maxDepth, 0, visited, result);
+    return result;
+  }
+  async range(start, end) {
+    const index = await this.db.get(CHRONICLE_PATHS.INDEX) ?? [];
+    const result = [];
+    for (const id of index) {
+      const node = await this.db.get(`${CHRONICLE_PATHS.NODES}/${id}`);
+      if (node && node.timestamp >= start && node.timestamp <= end) {
+        result.push(node);
+      }
+    }
+    return result;
+  }
+  async subgraph(contextId) {
+    const contextPath = `${CHRONICLE_PATHS.CONTEXT}/${contextId}`;
+    const nodeIds = await this.db.get(contextPath) ?? [];
+    const result = [];
+    for (const id of nodeIds) {
+      const node = await this.db.get(`${CHRONICLE_PATHS.NODES}/${id}`);
+      if (node) {
+        result.push(node);
+      }
+    }
+    return result;
+  }
+  // ── Internal helpers ──────────────────────────────────────────────────────
+  async addEdge(from, to, type) {
+    const edge = { from, to, type };
+    const outPath = `${CHRONICLE_PATHS.EDGES_OUT}/${from}`;
+    const outEdges = await this.db.get(outPath) ?? [];
+    await this.db.set(outPath, [...outEdges, edge]);
+    const inPath = `${CHRONICLE_PATHS.EDGES_IN}/${to}`;
+    const inEdges = await this.db.get(inPath) ?? [];
+    await this.db.set(inPath, [...inEdges, edge]);
+  }
+  async _traceRecursive(nodeId, direction, maxDepth, depth, visited, result) {
+    if (depth > maxDepth || visited.has(nodeId)) {
+      return;
+    }
+    visited.add(nodeId);
+    const node = await this.db.get(`${CHRONICLE_PATHS.NODES}/${nodeId}`);
+    if (node) {
+      result.push(node);
+    }
+    if (direction === "backward" || direction === "both") {
+      const inEdges = await this.db.get(`${CHRONICLE_PATHS.EDGES_IN}/${nodeId}`) ?? [];
+      for (const edge of inEdges) {
+        await this._traceRecursive(edge.from, direction, maxDepth, depth + 1, visited, result);
+      }
+    }
+    if (direction === "forward" || direction === "both") {
+      const outEdges = await this.db.get(`${CHRONICLE_PATHS.EDGES_OUT}/${nodeId}`) ?? [];
+      for (const edge of outEdges) {
+        await this._traceRecursive(edge.to, direction, maxDepth, depth + 1, visited, result);
+      }
+    }
+  }
+};
+function createChronicle(db) {
+  return new PluresDbChronicle(db);
+}
+
+// src/core/chronicle/mcp.ts
+function createChronosMcpTools(chronicle) {
+  return {
+    async trace(params) {
+      try {
+        const nodes = await chronicle.trace(
+          params.nodeId,
+          params.direction ?? "backward",
+          params.maxDepth ?? 10
+        );
+        return { success: true, data: nodes };
+      } catch (error) {
+        return {
+          success: false,
+          error: error instanceof Error ? error.message : String(error)
+        };
+      }
+    },
+    async search(params) {
+      try {
+        const query = params.query.toLowerCase();
+        let candidates;
+        if (params.contextId) {
+          candidates = await chronicle.subgraph(params.contextId);
+        } else {
+          candidates = await chronicle.range(params.since ?? 0, params.until ?? Date.now());
+        }
+        const filtered = candidates.filter((node) => {
+          const inPath = node.event.path.toLowerCase().includes(query);
+          const inMeta = Object.values(node.event.metadata).some(
+            (v) => v.toLowerCase().includes(query)
+          );
+          const inAfter = JSON.stringify(node.event.after ?? "").toLowerCase().includes(query);
+          const inBefore = JSON.stringify(node.event.before ?? "").toLowerCase().includes(query);
+          return inPath || inMeta || inAfter || inBefore;
+        });
+        const limited = params.limit !== void 0 ? filtered.slice(0, params.limit) : filtered;
+        return { success: true, data: limited };
+      } catch (error) {
+        return {
+          success: false,
+          error: error instanceof Error ? error.message : String(error)
+        };
+      }
+    }
+  };
+}
+
 // src/integrations/pluresdb.ts
 function createPluresDBAdapter(options) {
   const store = createPraxisDBStore(options.db, options.registry, options.initialContext);
@@ -1443,7 +1768,7 @@ function generateTauriConfig(config) {
 
 // src/integrations/unified.ts
 async function createUnifiedApp(config) {
-  const { createPraxisEngine: createPraxisEngine2 } = await import("./engine-2DQBKBJC.js");
+  const { createPraxisEngine: createPraxisEngine2 } = await import("./engine-7CXQV6RC.js");
   const { createInMemoryDB: createInMemoryDB2 } = await import("./adapter-75ISSMWD.js");
   const db = config.db || createInMemoryDB2();
   const pluresdb = createPluresDBAdapter({
@@ -1576,6 +1901,8 @@ export {
   AcknowledgeContractGap,
   ActorManager,
   BehaviorLedger,
+  CHRONICLE_PATHS,
+  ChronicleContext,
   ContractAdded,
   ContractGapAcknowledged,
   ContractMissing,
@@ -1588,6 +1915,7 @@ export {
   PRAXIS_PROTOCOL_VERSION,
   PluresDBGenerator,
   PluresDBPraxisAdapter,
+  PluresDbChronicle,
   PraxisDBStore,
   PraxisRegistry,
   PraxisSchemaRegistry,
@@ -1605,6 +1933,8 @@ export {
   canvasToYaml,
   createBehaviorLedger,
   createCanvasEditor,
+  createChronicle,
+  createChronosMcpTools,
   createReactiveEngine2 as createFrameworkAgnosticReactiveEngine,
   createInMemoryDB,
   createIntrospector,

package/dist/node/integrations/svelte.cjs

@@ -215,8 +215,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 ?? [],
@@ -272,6 +276,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) {
@@ -282,6 +287,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);
@@ -293,9 +304,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);
@@ -348,6 +379,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 +414,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-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';
 
 /**
  * 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-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';
 
 /**
  * Svelte v5 Integration

package/dist/node/integrations/svelte.js

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

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

@@ -119,4 +119,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-BocKczNv.d.ts}

@@ -119,4 +119,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 };