@plures/praxis 1.2.13 → 1.3.0

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/completeness.ts

@@ -0,0 +1,274 @@
+/**
+ * @plures/praxis — Completeness Analysis
+ *
+ * This module provides tools to measure and enforce "Praxis Completeness" —
+ * the degree to which an application's logic is expressed through Praxis
+ * rules, constraints, and contracts rather than scattered conditionals.
+ *
+ * ## Definition: Praxis Logic Completeness
+ *
+ * An application is "Praxis Complete" when:
+ *
+ * 1. **DOMAIN RULES (100%)** — Every business decision that produces user-visible
+ *    behavior change is expressed as a Praxis rule. "If the sprint is behind pace,
+ *    show a warning" is domain logic. It belongs in Praxis.
+ *
+ * 2. **INVARIANTS (100%)** — Every data validity assertion is a Praxis constraint.
+ *    "Sprint hours must not exceed 80" is an invariant. It belongs in Praxis.
+ *
+ * 3. **CONTRACTS (>80%)** — Rules that encode non-obvious behavior have contracts
+ *    (behavior description + examples + invariants). Contracts are documentation
+ *    AND test vectors — they prove the tool isn't the bug.
+ *
+ * 4. **CONTEXT COVERAGE (100%)** — Every piece of application state that rules
+ *    reason about is in the Praxis context. If a rule needs to know about
+ *    connection status, connection status must be in the context.
+ *
+ * 5. **EVENT COVERAGE (100%)** — Every state transition that should trigger rule
+ *    evaluation fires a Praxis event. If notes can be saved, there's a note.save
+ *    event. If sprint refreshes, there's a sprint.refresh event.
+ *
+ * ## What Is NOT Praxis Logic
+ *
+ * - **UI mechanics**: Panel toggle, scroll position, animation state, focus management
+ * - **Data transport**: fetch() calls, WebSocket plumbing, file I/O
+ * - **Framework wiring**: Svelte subscriptions, onMount, store creation
+ * - **Data transformation**: Parsing, formatting, serialization
+ * - **Routing/navigation**: URL handling, panel switching (unless it has business rules)
+ *
+ * The line: "Does this `if` statement encode a business decision or an app invariant?"
+ * If yes → Praxis rule/constraint. If no → leave it.
+ *
+ * ## Measuring Completeness
+ *
+ * ### Quantitative Metrics
+ * - **Rule Coverage**: (domain `if` branches in Praxis) / (total domain `if` branches)
+ * - **Constraint Coverage**: (data invariants in Praxis) / (total data invariants)
+ * - **Contract Coverage**: (rules with contracts) / (rules that need contracts)
+ * - **Context Coverage**: (state fields wired to context) / (state fields rules need)
+ * - **Event Coverage**: (state transitions with events) / (state transitions that matter)
+ *
+ * ### Qualitative Indicators
+ * - Can you change a business rule by editing ONE rule definition? (single source of truth)
+ * - Can you test a business rule without rendering UI? (Praxis engine is headless)
+ * - Can you explain every business rule to a PM by reading the registry? (self-documenting)
+ * - Does the PraxisPanel show all active concerns? (observable)
+ *
+ * ## The Completeness Score
+ *
+ * ```
+ * Score = (
+ *   rulesCovered / totalDomainBranches * 40 +     // Rules are king (40%)
+ *   constraintsCovered / totalInvariants * 20 +    // Invariants matter (20%)
+ *   contractsCovered / rulesNeedingContracts * 15 + // Contracts prevent bugs (15%)
+ *   contextFieldsCovered / totalNeeded * 15 +       // Context = visibility (15%)
+ *   eventsCovered / totalTransitions * 10            // Events = reactivity (10%)
+ * )
+ * ```
+ *
+ * 90+ = Complete | 70-89 = Good | 50-69 = Partial | <50 = Incomplete
+ */
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+export interface LogicBranch {
+  /** Source file + line */
+  location: string;
+  /** The condition expression */
+  condition: string;
+  /** Classification */
+  kind: 'domain' | 'invariant' | 'ui' | 'transport' | 'wiring' | 'transform';
+  /** If domain/invariant: the Praxis rule/constraint that covers it, or null */
+  coveredBy: string | null;
+  /** Human note */
+  note?: string;
+}
+
+export interface StateField {
+  /** Store or source name */
+  source: string;
+  /** Field path */
+  field: string;
+  /** Whether it's in the Praxis context */
+  inContext: boolean;
+  /** Whether any rule references it */
+  usedByRule: boolean;
+}
+
+export interface StateTransition {
+  /** What changes */
+  description: string;
+  /** The Praxis event tag, or null if missing */
+  eventTag: string | null;
+  /** Source location */
+  location: string;
+}
+
+export interface CompletenessReport {
+  /** Overall score (0-100) */
+  score: number;
+  /** Rating */
+  rating: 'complete' | 'good' | 'partial' | 'incomplete';
+
+  rules: {
+    total: number;
+    covered: number;
+    uncovered: LogicBranch[];
+  };
+  constraints: {
+    total: number;
+    covered: number;
+    uncovered: LogicBranch[];
+  };
+  contracts: {
+    total: number;
+    withContracts: number;
+    missing: string[];
+  };
+  context: {
+    total: number;
+    covered: number;
+    missing: StateField[];
+  };
+  events: {
+    total: number;
+    covered: number;
+    missing: StateTransition[];
+  };
+}
+
+export interface CompletenessConfig {
+  /** Minimum score to pass (default: 90) */
+  threshold?: number;
+  /** Whether to throw on failure (for CI) */
+  strict?: boolean;
+}
+
+// ─── Audit Helper ───────────────────────────────────────────────────────────
+
+/**
+ * Run a completeness audit against a Praxis registry and app manifest.
+ *
+ * The manifest is a developer-authored declaration of all logic branches,
+ * state fields, and state transitions in the app. The auditor checks which
+ * ones are covered by Praxis.
+ */
+export function auditCompleteness(
+  manifest: {
+    branches: LogicBranch[];
+    stateFields: StateField[];
+    transitions: StateTransition[];
+    rulesNeedingContracts: string[];
+  },
+  registryRuleIds: string[],
+  registryConstraintIds: string[],
+  rulesWithContracts: string[],
+  config?: CompletenessConfig,
+): CompletenessReport {
+  const threshold = config?.threshold ?? 90;
+
+  // Rules
+  const domainBranches = manifest.branches.filter(b => b.kind === 'domain');
+  const coveredDomain = domainBranches.filter(b => b.coveredBy && registryRuleIds.includes(b.coveredBy));
+  const uncoveredDomain = domainBranches.filter(b => !b.coveredBy || !registryRuleIds.includes(b.coveredBy));
+
+  // Constraints
+  const invariantBranches = manifest.branches.filter(b => b.kind === 'invariant');
+  const coveredInvariants = invariantBranches.filter(b => b.coveredBy && registryConstraintIds.includes(b.coveredBy));
+  const uncoveredInvariants = invariantBranches.filter(b => !b.coveredBy || !registryConstraintIds.includes(b.coveredBy));
+
+  // Contracts
+  const needContracts = manifest.rulesNeedingContracts;
+  const haveContracts = needContracts.filter(id => rulesWithContracts.includes(id));
+  const missingContracts = needContracts.filter(id => !rulesWithContracts.includes(id));
+
+  // Context
+  const neededFields = manifest.stateFields.filter(f => f.usedByRule);
+  const coveredFields = neededFields.filter(f => f.inContext);
+  const missingFields = neededFields.filter(f => !f.inContext);
+
+  // Events
+  const coveredTransitions = manifest.transitions.filter(t => t.eventTag);
+  const missingTransitions = manifest.transitions.filter(t => !t.eventTag);
+
+  // Score
+  const ruleScore = domainBranches.length > 0 ? (coveredDomain.length / domainBranches.length) * 40 : 40;
+  const constraintScore = invariantBranches.length > 0 ? (coveredInvariants.length / invariantBranches.length) * 20 : 20;
+  const contractScore = needContracts.length > 0 ? (haveContracts.length / needContracts.length) * 15 : 15;
+  const contextScore = neededFields.length > 0 ? (coveredFields.length / neededFields.length) * 15 : 15;
+  const eventScore = manifest.transitions.length > 0 ? (coveredTransitions.length / manifest.transitions.length) * 10 : 10;
+
+  const score = Math.round(ruleScore + constraintScore + contractScore + contextScore + eventScore);
+  const rating = score >= 90 ? 'complete' : score >= 70 ? 'good' : score >= 50 ? 'partial' : 'incomplete';
+
+  const report: CompletenessReport = {
+    score,
+    rating,
+    rules: { total: domainBranches.length, covered: coveredDomain.length, uncovered: uncoveredDomain },
+    constraints: { total: invariantBranches.length, covered: coveredInvariants.length, uncovered: uncoveredInvariants },
+    contracts: { total: needContracts.length, withContracts: haveContracts.length, missing: missingContracts },
+    context: { total: neededFields.length, covered: coveredFields.length, missing: missingFields },
+    events: { total: manifest.transitions.length, covered: coveredTransitions.length, missing: missingTransitions },
+  };
+
+  if (config?.strict && score < threshold) {
+    throw new Error(`Praxis completeness ${score}/100 (${rating}) — below threshold ${threshold}. ${uncoveredDomain.length} uncovered rules, ${uncoveredInvariants.length} uncovered invariants, ${missingContracts.length} missing contracts.`);
+  }
+
+  return report;
+}
+
+/**
+ * Format a completeness report as human-readable text.
+ */
+export function formatReport(report: CompletenessReport): string {
+  const lines: string[] = [];
+  const icon = report.rating === 'complete' ? '✅' : report.rating === 'good' ? '🟢' : report.rating === 'partial' ? '🟡' : '🔴';
+
+  lines.push(`${icon} Praxis Completeness: ${report.score}/100 (${report.rating})`);
+  lines.push('');
+  lines.push(`Rules:       ${report.rules.covered}/${report.rules.total} domain branches covered (${pct(report.rules.covered, report.rules.total)})`);
+  lines.push(`Constraints: ${report.constraints.covered}/${report.constraints.total} invariants covered (${pct(report.constraints.covered, report.constraints.total)})`);
+  lines.push(`Contracts:   ${report.contracts.withContracts}/${report.contracts.total} rules have contracts (${pct(report.contracts.withContracts, report.contracts.total)})`);
+  lines.push(`Context:     ${report.context.covered}/${report.context.total} state fields in context (${pct(report.context.covered, report.context.total)})`);
+  lines.push(`Events:      ${report.events.covered}/${report.events.total} transitions have events (${pct(report.events.covered, report.events.total)})`);
+
+  if (report.rules.uncovered.length > 0) {
+    lines.push('');
+    lines.push('Uncovered domain logic:');
+    for (const b of report.rules.uncovered) {
+      lines.push(`  ❌ ${b.location}: ${b.condition}${b.note ? ` — ${b.note}` : ''}`);
+    }
+  }
+
+  if (report.constraints.uncovered.length > 0) {
+    lines.push('');
+    lines.push('Uncovered invariants:');
+    for (const b of report.constraints.uncovered) {
+      lines.push(`  ❌ ${b.location}: ${b.condition}${b.note ? ` — ${b.note}` : ''}`);
+    }
+  }
+
+  if (report.contracts.missing.length > 0) {
+    lines.push('');
+    lines.push('Rules missing contracts:');
+    for (const id of report.contracts.missing) {
+      lines.push(`  📝 ${id}`);
+    }
+  }
+
+  if (report.events.missing.length > 0) {
+    lines.push('');
+    lines.push('State transitions without events:');
+    for (const t of report.events.missing) {
+      lines.push(`  ⚡ ${t.location}: ${t.description}`);
+    }
+  }
+
+  return lines.join('\n');
+}
+
+function pct(a: number, b: number): string {
+  if (b === 0) return '100%';
+  return Math.round((a / b) * 100) + '%';
+}

package/src/core/engine.ts

@@ -15,6 +15,7 @@ import type {
 } from './protocol.js';
 import { PRAXIS_PROTOCOL_VERSION } from './protocol.js';
 import { PraxisRegistry } from './rules.js';
+import { RuleResult } from './rule-result.js';
 
 /**
  * Options for creating a Praxis engine
@@ -28,6 +29,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 +84,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 ?? [],
@@ -132,8 +151,16 @@ export class LogicEngine<TContext = unknown> {
     const diagnostics: PraxisDiagnostics[] = [];
     let newState = { ...this.state };
 
+    // ── Inject events into state so rules can access them via state.events ──
+    const stateWithEvents = {
+      ...newState,
+      events, // current batch — rules can read state.events
+    };
+
     // Apply rules
     const newFacts: PraxisFact[] = [];
+    const retractions: string[] = [];
+    const eventTags = new Set(events.map(e => e.tag));
     for (const ruleId of config.ruleIds) {
       const rule = this.registry.getRule(ruleId);
       if (!rule) {
@@ -145,9 +172,45 @@ 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);
+        const rawResult = rule.impl(stateWithEvents, events);
+
+        // Support both legacy PraxisFact[] return and new RuleResult return
+        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':
+              // Traceable no-ops — store in diagnostics for introspection
+              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)) {
+          // Legacy: PraxisFact[] — backward compatible
+          newFacts.push(...rawResult);
+        }
       } catch (error) {
         diagnostics.push({
           kind: 'rule-error',
@@ -157,10 +220,42 @@ export class LogicEngine<TContext = unknown> {
       }
     }
 
+    // ── Apply retractions ──
+    let existingFacts = newState.facts;
+    if (retractions.length > 0) {
+      const retractSet = new Set(retractions);
+      existingFacts = existingFacts.filter(f => !retractSet.has(f.tag));
+    }
+
+    // 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 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 = [...existingFacts, ...newFacts];
+        break;
+      case 'none':
+      default:
+        mergedFacts = [...existingFacts, ...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 +316,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 +358,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';