@plures/praxis 1.2.13 → 1.2.41

package/src/core/chronicle/types.ts

@@ -0,0 +1,61 @@
+/**
+ * Chronicle Types
+ *
+ * Core types for the Chronicle causal tracking system.
+ * Records state transitions as a causal graph stored in PluresDB.
+ */
+
+/**
+ * Direction for traversing causal chains.
+ */
+export type TraceDirection = 'backward' | 'forward' | 'both';
+
+/**
+ * Causal relationship type between Chronicle nodes.
+ * - `causes`: node A caused node B (explicit causal link)
+ * - `context`: node B belongs to the same session/request as node A
+ * - `follows`: node B happened after node A in the same context
+ */
+export type EdgeType = 'causes' | 'context' | 'follows';
+
+/**
+ * A recorded state transition event passed to Chronicle.
+ */
+export interface ChronicleEvent {
+  /** Path to the changed value (fact or event stream path) */
+  path: string;
+  /** Value before the change (undefined for creates) */
+  before?: unknown;
+  /** Value after the change */
+  after?: unknown;
+  /** Parent span/node ID that caused this change */
+  cause?: string;
+  /** Session or request ID grouping related changes */
+  context?: string;
+  /** Additional metadata key-value pairs */
+  metadata: Record<string, string>;
+}
+
+/**
+ * A Chronicle node representing a single recorded state transition.
+ */
+export interface ChronicleNode {
+  /** Unique node ID: `chronos:{timestamp}-{counter}` */
+  id: string;
+  /** Timestamp (ms since epoch) when this node was recorded */
+  timestamp: number;
+  /** The recorded state transition */
+  event: ChronicleEvent;
+}
+
+/**
+ * A directed edge in the causal graph connecting two Chronicle nodes.
+ */
+export interface ChronicleEdge {
+  /** Source node ID */
+  from: string;
+  /** Target node ID */
+  to: string;
+  /** Type of causal relationship */
+  type: EdgeType;
+}

package/src/core/engine.ts

@@ -28,6 +28,20 @@ export 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;
 }
 
 /**
@@ -69,9 +83,13 @@ function safeClone<T>(value: T): T {
 export class LogicEngine<TContext = unknown> {
   private state: PraxisState & { context: TContext };
   private readonly registry: PraxisRegistry<TContext>;
+  private readonly factDedup: 'none' | 'last-write-wins' | 'append';
+  private readonly maxFacts: number;
 
   constructor(options: PraxisEngineOptions<TContext>) {
     this.registry = options.registry;
+    this.factDedup = options.factDedup ?? 'last-write-wins';
+    this.maxFacts = options.maxFacts ?? 1000;
     this.state = {
       context: options.initialContext,
       facts: options.initialFacts ?? [],
@@ -134,6 +152,7 @@ export class LogicEngine<TContext = unknown> {
 
     // Apply rules
     const newFacts: PraxisFact[] = [];
+    const eventTags = new Set(events.map(e => e.tag));
     for (const ruleId of config.ruleIds) {
       const rule = this.registry.getRule(ruleId);
       if (!rule) {
@@ -145,6 +164,15 @@ export class LogicEngine<TContext = unknown> {
         continue;
       }
 
+      // Event type filtering: if rule declares eventTypes, skip unless
+      // at least one event in the batch matches.
+      if (rule.eventTypes) {
+        const filterTags = Array.isArray(rule.eventTypes) ? rule.eventTypes : [rule.eventTypes];
+        if (!filterTags.some(t => eventTags.has(t))) {
+          continue; // No matching events — skip this rule
+        }
+      }
+
       try {
         const ruleFacts = rule.impl(newState, events);
         newFacts.push(...ruleFacts);
@@ -157,10 +185,35 @@ export class LogicEngine<TContext = unknown> {
       }
     }
 
+    // Merge new facts with deduplication
+    let mergedFacts: PraxisFact[];
+    switch (this.factDedup) {
+      case 'last-write-wins': {
+        // Build a map keyed by tag — new facts overwrite old ones with same tag
+        const factMap = new Map<string, PraxisFact>();
+        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;
+    }
+
+    // Enforce maxFacts limit (evict oldest first)
+    if (this.maxFacts > 0 && mergedFacts.length > this.maxFacts) {
+      mergedFacts = mergedFacts.slice(mergedFacts.length - this.maxFacts);
+    }
+
     // Add new facts to state
     newState = {
       ...newState,
-      facts: [...newState.facts, ...newFacts],
+      facts: mergedFacts,
     };
 
     // Check constraints
@@ -221,6 +274,35 @@ export class LogicEngine<TContext = unknown> {
     };
   }
 
+  /**
+   * 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 {
+    // Update context first — rules see fresh data
+    this.state = {
+      ...this.state,
+      context: updater(this.state.context),
+    };
+    // Then step with the now-current context
+    return this.step(events);
+  }
+
   /**
    * Add facts directly (for exceptional cases).
    * Generally, facts should be added through rules.
@@ -234,6 +316,22 @@ export class LogicEngine<TContext = unknown> {
     };
   }
 
+  /**
+   * 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[] {
+    return this.stepWithConfig([], {
+      ruleIds: [],
+      constraintIds: this.registry.getConstraintIds(),
+    }).diagnostics;
+  }
+
   /**
    * Clear all facts
    */

package/src/core/pluresdb/index.ts

@@ -32,3 +32,25 @@ export {
 // Config Generator - Generate PluresDB config from schemas
 export type { PluresDBGeneratorOptions, GeneratedPluresDBFile } from './generator.js';
 export { PluresDBGenerator, createPluresDBGenerator } from './generator.js';
+
+// Chronicle - Causal graph tracking for state transitions
+export type {
+  TraceDirection,
+  EdgeType,
+  ChronicleEvent,
+  ChronicleNode,
+  ChronicleEdge,
+  Chronicle,
+  ChronosTraceParams,
+  ChronosSearchParams,
+  McpToolResult,
+  ChronosMcpTools,
+} from '../chronicle/index.js';
+export {
+  ChronicleContext,
+  PluresDbChronicle,
+  createChronicle,
+  CHRONICLE_PATHS,
+  createChronosMcpTools,
+} from '../chronicle/index.js';
+export type { ChronicleSpan } from '../chronicle/index.js';

package/src/core/pluresdb/store.ts

@@ -11,6 +11,8 @@ declare const process: { env: { [key: string]: string | undefined } } | undefine
 import type { PraxisDB, UnsubscribeFn } from './adapter.js';
 import type { PraxisRegistry } from '../rules.js';
 import type { PraxisFact, PraxisEvent, PraxisState } from '../protocol.js';
+import type { Chronicle } from '../chronicle/chronicle.js';
+import { ChronicleContext } from '../chronicle/context.js';
 
 /**
  * Key paths for Praxis data in PluresDB
@@ -110,6 +112,7 @@ export class PraxisDBStore<TContext = unknown> {
   private subscriptions: UnsubscribeFn[] = [];
   private factWatchers = new Map<string, Set<(facts: PraxisFact[]) => void>>();
   private onRuleError: RuleErrorHandler;
+  private chronicle?: Chronicle;
 
   constructor(options: PraxisDBStoreOptions<TContext> & { onRuleError?: RuleErrorHandler }) {
     this.db = options.db;
@@ -118,6 +121,26 @@ export class PraxisDBStore<TContext = unknown> {
     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: Chronicle): this {
+    this.chronicle = chronicle;
+    return this;
+  }
+
   /**
    * Store a fact in PluresDB
    *
@@ -134,8 +157,37 @@ export class PraxisDBStore<TContext = unknown> {
       throw new Error(`Constraint violation: ${constraintResult.errors.join(', ')}`);
     }
 
+    // Capture before state for Chronicle (best-effort; ignore errors)
+    let before: unknown;
+    if (this.chronicle) {
+      const payload = fact.payload as Record<string, unknown> | undefined;
+      const id = payload?.id as string | undefined;
+      if (id) {
+        before = await this.getFact(fact.tag, id);
+      }
+    }
+
     await this.persistFact(fact);
 
+    // Record state transition in Chronicle
+    if (this.chronicle) {
+      const payload = fact.payload as Record<string, unknown> | undefined;
+      const id = (payload?.id as string | undefined) ?? '';
+      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 {
+        // Chronicle errors must never fail the primary operation
+      }
+    }
+
     // Trigger rule evaluation - facts stored directly may trigger derived computations
     await this.triggerRules([fact]);
   }
@@ -153,7 +205,36 @@ export class PraxisDBStore<TContext = unknown> {
     }
 
     for (const fact of facts) {
+      // Capture before state for Chronicle (best-effort)
+      let before: unknown;
+      if (this.chronicle) {
+        const payload = fact.payload as Record<string, unknown> | undefined;
+        const id = payload?.id as string | undefined;
+        if (id) {
+          before = await this.getFact(fact.tag, id);
+        }
+      }
+
       await this.persistFact(fact);
+
+      // Record state transition in Chronicle
+      if (this.chronicle) {
+        const payload = fact.payload as Record<string, unknown> | undefined;
+        const id = (payload?.id as string | undefined) ?? '';
+        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 {
+          // Chronicle errors must never fail the primary operation
+        }
+      }
     }
 
     // Trigger rule evaluation
@@ -207,8 +288,37 @@ export class PraxisDBStore<TContext = unknown> {
     const newEvents = [...existingEvents, entry];
     await this.db.set(path, newEvents);
 
-    // Trigger rules with this event
-    await this.triggerRulesForEvents([event]);
+    // Record event in Chronicle and capture node ID so derived facts can link back to it
+    let eventNodeId: string | undefined;
+    if (this.chronicle) {
+      const span = ChronicleContext.current;
+      try {
+        const node = await this.chronicle.record({
+          path,
+          before: existingEvents.length > 0 ? existingEvents[existingEvents.length - 1] : undefined,
+          after: entry,
+          cause: span?.spanId,
+          context: span?.contextId,
+          metadata: { eventTag: event.tag, sequence: String(entry.sequence), operation: 'appendEvent' },
+        });
+        eventNodeId = node.id;
+      } catch {
+        // Chronicle errors must never fail the primary operation
+      }
+    }
+
+    // Trigger rules within a causal span attributed to this event node,
+    // so any derived facts automatically link back to this event via 'causes' edges.
+    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]);
+    }
   }
 
   /**
@@ -224,7 +334,8 @@ export class PraxisDBStore<TContext = unknown> {
       eventsByTag.set(event.tag, [...existing, event]);
     }
 
-    // Append each group
+    // Append each group and collect the last recorded event node ID for causal linking
+    let lastEventNodeId: string | undefined;
     for (const [tag, tagEvents] of eventsByTag) {
       const path = getEventPath(tag);
       const existingEvents = (await this.db.get<EventStreamEntry[]>(path)) ?? [];
@@ -237,10 +348,38 @@ export class PraxisDBStore<TContext = unknown> {
       }));
 
       await this.db.set(path, [...existingEvents, ...newEntries]);
+
+      // Record each appended event in Chronicle
+      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 {
+            // Chronicle errors must never fail the primary operation
+          }
+        }
+      }
     }
 
-    // Trigger rules
-    await this.triggerRulesForEvents(events);
+    // Trigger rules in a causal span attributed to the last event node
+    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);
+    }
   }
 
   /**
@@ -386,6 +525,24 @@ export class PraxisDBStore<TContext = unknown> {
       if (constraintResult.valid) {
         for (const fact of derivedFacts) {
           await this.persistFact(fact);
+
+          // Record derived fact in Chronicle using the current causal span
+          if (this.chronicle) {
+            const payload = fact.payload as Record<string, unknown> | undefined;
+            const id = (payload?.id as string | undefined) ?? '';
+            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 {
+              // Chronicle errors must never fail the primary operation
+            }
+          }
         }
       }
     }

package/src/core/rules.ts

@@ -61,6 +61,18 @@ export 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 */

package/src/dsl/index.ts

@@ -85,6 +85,11 @@ export interface DefineRuleOptions<TContext = unknown> {
   id: string;
   description: string;
   impl: RuleFn<TContext>;
+  /**
+   * Optional event type filter — only evaluate this rule when at least one
+   * event in the batch has a matching `tag`. Accepts a single tag or array.
+   */
+  eventTypes?: string | string[];
   contract?: Contract;
   meta?: Record<string, unknown>;
 }
@@ -115,6 +120,7 @@ export function defineRule<TContext = unknown>(
     id: options.id,
     description: options.description,
     impl: options.impl,
+    eventTypes: options.eventTypes,
     contract,
     meta,
   };

package/src/index.ts

@@ -208,6 +208,18 @@ export type {
   GeneratedPluresDBFile,
   PluresDBAdapter,
   PluresDBAdapterOptions,
+  // Chronicle
+  TraceDirection,
+  EdgeType,
+  ChronicleEvent,
+  ChronicleNode,
+  ChronicleEdge,
+  Chronicle,
+  ChronicleSpan,
+  ChronosTraceParams,
+  ChronosSearchParams,
+  McpToolResult,
+  ChronosMcpTools,
 } from './integrations/pluresdb.js';
 export {
   InMemoryPraxisDB,
@@ -229,6 +241,12 @@ export {
   createPluresDBGenerator,
   createPluresDBAdapter,
   attachToEngine,
+  // Chronicle
+  ChronicleContext,
+  PluresDbChronicle,
+  createChronicle,
+  CHRONICLE_PATHS,
+  createChronosMcpTools,
 } from './integrations/pluresdb.js';
 
 // Unum Integration (Identity & Channels)

package/src/integrations/pluresdb.ts

@@ -57,6 +57,28 @@ export type {
   GeneratedPluresDBFile,
 } from '../core/pluresdb/generator.js';
 
+// Chronicle - Causal graph tracking for Praxis state transitions
+export type {
+  TraceDirection,
+  EdgeType,
+  ChronicleEvent,
+  ChronicleNode,
+  ChronicleEdge,
+  Chronicle,
+  ChronicleSpan,
+  ChronosTraceParams,
+  ChronosSearchParams,
+  McpToolResult,
+  ChronosMcpTools,
+} from '../core/chronicle/index.js';
+export {
+  ChronicleContext,
+  PluresDbChronicle,
+  createChronicle,
+  CHRONICLE_PATHS,
+  createChronosMcpTools,
+} from '../core/chronicle/index.js';
+
 /**
  * PluresDB adapter interface for engine integration
  *