@plures/praxis 1.2.41 → 1.4.0

package/dist/node/{chunk-BBP2F7TT.js → chunk-KMJWAFZV.js}

@@ -1,6 +1,93 @@
 // 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") {
@@ -80,7 +167,13 @@ var LogicEngine = class {
   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);
@@ -99,8 +192,31 @@ var LogicEngine = class {
         }
       }
       try {
-        const ruleFacts = rule.impl(newState, events);
-        newFacts.push(...ruleFacts);
+        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",
@@ -109,21 +225,26 @@ var LogicEngine = class {
         });
       }
     }
+    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 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;
     }
     if (this.maxFacts > 0 && mergedFacts.length > this.maxFacts) {
@@ -261,6 +382,8 @@ function createPraxisEngine(options) {
 
 export {
   PRAXIS_PROTOCOL_VERSION,
+  RuleResult,
+  fact,
   LogicEngine,
   createPraxisEngine
 };

package/dist/node/chunk-PGVSB6NR.js

@@ -0,0 +1,59 @@
+// src/decision-ledger/types.ts
+function isContract(obj) {
+  if (typeof obj !== "object" || obj === null) {
+    return false;
+  }
+  const contract = obj;
+  return typeof contract.ruleId === "string" && typeof contract.behavior === "string" && Array.isArray(contract.examples) && contract.examples.length > 0 && contract.examples.every(
+    (ex) => typeof ex === "object" && ex !== null && typeof ex.given === "string" && typeof ex.when === "string" && typeof ex.then === "string"
+  ) && Array.isArray(contract.invariants) && contract.invariants.every((inv) => typeof inv === "string");
+}
+function defineContract(options) {
+  if (options.examples.length === 0) {
+    throw new Error("Contract must have at least one example");
+  }
+  if (options.assumptions) {
+    for (const assumption of options.assumptions) {
+      if (assumption.confidence < 0 || assumption.confidence > 1) {
+        throw new Error(
+          `Assumption '${assumption.id}' has invalid confidence value ${assumption.confidence}. Must be between 0.0 and 1.0`
+        );
+      }
+    }
+  }
+  return {
+    ruleId: options.ruleId,
+    behavior: options.behavior,
+    examples: options.examples,
+    invariants: options.invariants,
+    assumptions: options.assumptions,
+    references: options.references,
+    version: options.version || "1.0.0",
+    timestamp: (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+function getContract(meta) {
+  if (!meta || !meta.contract) {
+    return void 0;
+  }
+  if (isContract(meta.contract)) {
+    return meta.contract;
+  }
+  return void 0;
+}
+function getContractFromDescriptor(descriptor) {
+  if (!descriptor) {
+    return void 0;
+  }
+  if (descriptor.contract && isContract(descriptor.contract)) {
+    return descriptor.contract;
+  }
+  return getContract(descriptor.meta);
+}
+
+export {
+  isContract,
+  defineContract,
+  getContract,
+  getContractFromDescriptor
+};