@plures/praxis 1.2.13 → 1.3.0

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);
+    }
   }
 
   /**
@@ -363,9 +502,10 @@ export class PraxisDBStore<TContext = unknown> {
     const rules = this.registry.getAllRules();
 
     // Build state for rule evaluation
-    const state: PraxisState & { context: TContext } = {
+    const state: PraxisState & { context: TContext; events: PraxisEvent[] } = {
       context: this.context,
       facts: [],
+      events,
       meta: {},
     };
 
@@ -373,8 +513,13 @@ export class PraxisDBStore<TContext = unknown> {
     const derivedFacts: PraxisFact[] = [];
     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 as any).facts);
+        }
+        // noop/skip/retract handled by engine, not store
       } catch (error) {
         this.onRuleError(rule.id, error);
       }
@@ -386,6 +531,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/protocol.ts

@@ -75,6 +75,13 @@ export 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/src/core/rule-result.ts

@@ -0,0 +1,130 @@
+/**
+ * Typed Rule Results
+ *
+ * Rules must always return a RuleResult — never an empty array.
+ * A rule that has nothing to say returns RuleResult.noop().
+ * This makes every rule evaluation traceable and eliminates
+ * the ambiguity of "did the rule run but produce nothing,
+ * or did it not run at all?"
+ */
+
+import type { PraxisFact } from './protocol.js';
+
+/**
+ * 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
+ */
+export 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(
+    kind: 'emit' | 'noop' | 'skip' | 'retract',
+    facts: PraxisFact[],
+    retractTags: string[],
+    reason?: string,
+  ) {
+    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: PraxisFact[]): RuleResult {
+    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?: string): RuleResult {
+    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?: string): RuleResult {
+    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: string[], reason?: string): RuleResult {
+    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(): boolean {
+    return this.facts.length > 0;
+  }
+
+  /** Whether this result retracts facts */
+  get hasRetractions(): boolean {
+    return this.retractTags.length > 0;
+  }
+}
+
+/**
+ * A rule function that returns a typed RuleResult.
+ * New API — replaces the old PraxisFact[] return type.
+ */
+export type TypedRuleFn<TContext = unknown> = (
+  state: import('./protocol.js').PraxisState & { context: TContext; events: import('./protocol.js').PraxisEvent[] },
+  events: import('./protocol.js').PraxisEvent[]
+) => RuleResult;
+
+/**
+ * Convenience: create a fact object (just a shorthand)
+ */
+export function fact(tag: string, payload: unknown): PraxisFact {
+  return { tag, payload };
+}

package/src/core/rules.ts

@@ -8,6 +8,7 @@
 
 import type { PraxisEvent, PraxisFact, PraxisState } from './protocol.js';
 import type { Contract, ContractGap, MissingArtifact, Severity } from '../decision-ledger/types.js';
+import type { RuleResult } from './rule-result.js';
 
 declare const process:
   | {
@@ -31,14 +32,20 @@ export 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
  */
 export type RuleFn<TContext = unknown> = (
-  state: PraxisState & { context: TContext },
+  state: PraxisState & { context: TContext; events: PraxisEvent[] },
   events: PraxisEvent[]
-) => PraxisFact[];
+) => RuleResult | PraxisFact[];
 
 /**
  * A constraint function checks that an invariant holds.
@@ -61,6 +68,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 */