@plures/praxis 1.2.41 → 1.3.0

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
@@ -150,8 +151,15 @@ 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);
@@ -174,8 +182,35 @@ export class LogicEngine<TContext = unknown> {
       }
 
       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',
@@ -185,23 +220,30 @@ 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 newState.facts) factMap.set(f.tag, f);
+        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 = [...newState.facts, ...newFacts];
+        mergedFacts = [...existingFacts, ...newFacts];
         break;
       case 'none':
       default:
-        mergedFacts = [...newState.facts, ...newFacts];
+        mergedFacts = [...existingFacts, ...newFacts];
         break;
     }
 

package/src/core/pluresdb/store.ts

@@ -502,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: {},
     };
 
@@ -512,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);
       }

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.