@plures/praxis 1.2.13 → 1.3.0

package/dist/node/chunk-KMJWAFZV.js

@@ -0,0 +1,389 @@
+// src/core/protocol.ts
+var PRAXIS_PROTOCOL_VERSION = "1.0.0";
+
+// src/core/rule-result.ts
+var RuleResult = class _RuleResult {
+  /** The kind of result */
+  kind;
+  /** Facts produced (only for 'emit') */
+  facts;
+  /** Fact tags to retract (only for 'retract') */
+  retractTags;
+  /** Optional reason (for noop/skip/retract — useful for debugging) */
+  reason;
+  /** The rule ID that produced this result (set by engine) */
+  ruleId;
+  constructor(kind, facts, retractTags, reason) {
+    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) {
+    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) {
+    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) {
+    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, reason) {
+    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() {
+    return this.facts.length > 0;
+  }
+  /** Whether this result retracts facts */
+  get hasRetractions() {
+    return this.retractTags.length > 0;
+  }
+};
+function fact(tag, payload) {
+  return { tag, payload };
+}
+
+// src/core/engine.ts
+function safeClone(value) {
+  if (value === null || typeof value !== "object") {
+    return value;
+  }
+  if (typeof globalThis.structuredClone === "function") {
+    try {
+      return globalThis.structuredClone(value);
+    } catch {
+    }
+  }
+  if (Array.isArray(value)) {
+    return [...value];
+  }
+  return { ...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 ?? [],
+      meta: options.initialMeta ?? {},
+      protocolVersion: PRAXIS_PROTOCOL_VERSION
+    };
+  }
+  /**
+   * Get the current state (immutable copy)
+   */
+  getState() {
+    return {
+      context: safeClone(this.state.context),
+      facts: [...this.state.facts],
+      meta: this.state.meta ? safeClone(this.state.meta) : void 0,
+      protocolVersion: this.state.protocolVersion
+    };
+  }
+  /**
+   * Get the current context
+   */
+  getContext() {
+    return safeClone(this.state.context);
+  }
+  /**
+   * Get current facts
+   */
+  getFacts() {
+    return [...this.state.facts];
+  }
+  /**
+   * Process events through the engine.
+   * Applies all registered rules and checks all registered constraints.
+   *
+   * @param events Events to process
+   * @returns Result with new state and diagnostics
+   */
+  step(events) {
+    const config = {
+      ruleIds: this.registry.getRuleIds(),
+      constraintIds: this.registry.getConstraintIds()
+    };
+    return this.stepWithConfig(events, config);
+  }
+  /**
+   * Process events with specific rule and constraint configuration.
+   *
+   * @param events Events to process
+   * @param config Step configuration
+   * @returns Result with new state and diagnostics
+   */
+  stepWithConfig(events, config) {
+    const diagnostics = [];
+    let newState = { ...this.state };
+    const stateWithEvents = {
+      ...newState,
+      events
+      // current batch — rules can read state.events
+    };
+    const newFacts = [];
+    const retractions = [];
+    const eventTags = new Set(events.map((e) => e.tag));
+    for (const ruleId of config.ruleIds) {
+      const rule = this.registry.getRule(ruleId);
+      if (!rule) {
+        diagnostics.push({
+          kind: "rule-error",
+          message: `Rule "${ruleId}" not found in registry`,
+          data: { ruleId }
+        });
+        continue;
+      }
+      if (rule.eventTypes) {
+        const filterTags = Array.isArray(rule.eventTypes) ? rule.eventTypes : [rule.eventTypes];
+        if (!filterTags.some((t) => eventTags.has(t))) {
+          continue;
+        }
+      }
+      try {
+        const rawResult = rule.impl(stateWithEvents, events);
+        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":
+              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)) {
+          newFacts.push(...rawResult);
+        }
+      } catch (error) {
+        diagnostics.push({
+          kind: "rule-error",
+          message: `Error executing rule "${ruleId}": ${error instanceof Error ? error.message : String(error)}`,
+          data: { ruleId, error }
+        });
+      }
+    }
+    let existingFacts = newState.facts;
+    if (retractions.length > 0) {
+      const retractSet = new Set(retractions);
+      existingFacts = existingFacts.filter((f) => !retractSet.has(f.tag));
+    }
+    let mergedFacts;
+    switch (this.factDedup) {
+      case "last-write-wins": {
+        const factMap = /* @__PURE__ */ new Map();
+        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;
+    }
+    if (this.maxFacts > 0 && mergedFacts.length > this.maxFacts) {
+      mergedFacts = mergedFacts.slice(mergedFacts.length - this.maxFacts);
+    }
+    newState = {
+      ...newState,
+      facts: mergedFacts
+    };
+    for (const constraintId of config.constraintIds) {
+      const constraint = this.registry.getConstraint(constraintId);
+      if (!constraint) {
+        diagnostics.push({
+          kind: "constraint-violation",
+          message: `Constraint "${constraintId}" not found in registry`,
+          data: { constraintId }
+        });
+        continue;
+      }
+      try {
+        const result = constraint.impl(newState);
+        if (result === false) {
+          diagnostics.push({
+            kind: "constraint-violation",
+            message: `Constraint "${constraintId}" violated`,
+            data: { constraintId, description: constraint.description }
+          });
+        } else if (typeof result === "string") {
+          diagnostics.push({
+            kind: "constraint-violation",
+            message: result,
+            data: { constraintId, description: constraint.description }
+          });
+        }
+      } catch (error) {
+        diagnostics.push({
+          kind: "constraint-violation",
+          message: `Error checking constraint "${constraintId}": ${error instanceof Error ? error.message : String(error)}`,
+          data: { constraintId, error }
+        });
+      }
+    }
+    this.state = newState;
+    return {
+      state: newState,
+      diagnostics
+    };
+  }
+  /**
+   * Update the context directly (for exceptional cases).
+   * Generally, context should be updated through rules.
+   *
+   * @param updater Function that produces new context from old context
+   */
+  updateContext(updater) {
+    this.state = {
+      ...this.state,
+      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.
+   *
+   * @param facts Facts to add
+   */
+  addFacts(facts) {
+    this.state = {
+      ...this.state,
+      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
+   */
+  clearFacts() {
+    this.state = {
+      ...this.state,
+      facts: []
+    };
+  }
+  /**
+   * Reset the engine to initial state
+   */
+  reset(options) {
+    this.state = {
+      context: options.initialContext,
+      facts: options.initialFacts ?? [],
+      meta: options.initialMeta ?? {},
+      protocolVersion: PRAXIS_PROTOCOL_VERSION
+    };
+  }
+};
+function createPraxisEngine(options) {
+  return new LogicEngine(options);
+}
+
+export {
+  PRAXIS_PROTOCOL_VERSION,
+  RuleResult,
+  fact,
+  LogicEngine,
+  createPraxisEngine
+};

package/dist/node/{chunk-5RH7UAQC.js → chunk-PTH6MD6P.js}

@@ -32,6 +32,7 @@ function defineRule(options) {
     id: options.id,
     description: options.description,
     impl: options.impl,
+    eventTypes: options.eventTypes,
     contract,
     meta
   };