@plures/praxis 1.4.4 → 2.0.3

package/dist/node/unified/index.cjs

@@ -0,0 +1,494 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/unified/index.ts
+var unified_exports = {};
+__export(unified_exports, {
+  RuleResult: () => RuleResult,
+  createApp: () => createApp,
+  defineConstraint: () => defineConstraint,
+  defineModule: () => defineModule,
+  definePath: () => definePath,
+  defineRule: () => defineRule,
+  fact: () => fact
+});
+module.exports = __toCommonJS(unified_exports);
+
+// src/unified/core.ts
+var _idCounter = 0;
+function nextId() {
+  return `px:${Date.now()}-${++_idCounter}`;
+}
+function createApp(config) {
+  const paths = /* @__PURE__ */ new Map();
+  for (const schema of config.schema) {
+    paths.set(schema.path, {
+      schema,
+      value: schema.initial,
+      subscribers: /* @__PURE__ */ new Set(),
+      lastUpdated: 0,
+      updateCount: 0
+    });
+  }
+  let facts = [];
+  const factMap = /* @__PURE__ */ new Map();
+  const timeline = [];
+  const maxTimeline = 1e4;
+  function recordTimeline(path, kind, data) {
+    const entry = {
+      id: nextId(),
+      timestamp: Date.now(),
+      path,
+      kind,
+      data
+    };
+    timeline.push(entry);
+    if (timeline.length > maxTimeline) {
+      timeline.splice(0, timeline.length - maxTimeline);
+    }
+  }
+  const ruleStates = (config.rules ?? []).map((rule) => ({
+    rule,
+    lastResult: null,
+    emittedTags: /* @__PURE__ */ new Set()
+  }));
+  const constraints = config.constraints ?? [];
+  const livenessConfig = config.liveness;
+  const initTime = Date.now();
+  let livenessTimer = null;
+  if (livenessConfig) {
+    const timeout = livenessConfig.timeoutMs ?? 5e3;
+    livenessTimer = setTimeout(() => {
+      for (const expectedPath of livenessConfig.expect) {
+        const state = paths.get(expectedPath);
+        if (!state || state.updateCount === 0) {
+          const elapsed = Date.now() - initTime;
+          recordTimeline(expectedPath, "liveness", {
+            stale: true,
+            elapsed,
+            message: `Path "${expectedPath}" never updated after ${elapsed}ms`
+          });
+          livenessConfig.onStale?.(expectedPath, elapsed);
+        }
+      }
+    }, timeout);
+  }
+  function getPathValues(watchPaths) {
+    const values = {};
+    for (const p of watchPaths) {
+      const state = paths.get(p);
+      values[p] = state ? state.value : void 0;
+    }
+    return values;
+  }
+  function notify(path, value) {
+    const state = paths.get(path);
+    if (!state) return;
+    for (const cb of state.subscribers) {
+      try {
+        cb(value);
+      } catch (err) {
+        console.error(`[praxis] Subscriber error for "${path}":`, err);
+      }
+    }
+  }
+  function checkConstraints(path, value) {
+    const violations = [];
+    for (const c of constraints) {
+      if (!c.watch.includes(path)) continue;
+      const values = getPathValues(c.watch);
+      values[path] = value;
+      try {
+        const result = c.validate(values);
+        if (result !== true) {
+          violations.push({
+            kind: "constraint-violation",
+            message: result,
+            data: { constraintId: c.id, path, description: c.description }
+          });
+          recordTimeline(path, "constraint-check", {
+            constraintId: c.id,
+            violated: true,
+            message: result
+          });
+        }
+      } catch (err) {
+        violations.push({
+          kind: "constraint-violation",
+          message: `Constraint "${c.id}" threw: ${err instanceof Error ? err.message : String(err)}`,
+          data: { constraintId: c.id, error: err }
+        });
+      }
+    }
+    return violations;
+  }
+  function evaluateRules() {
+    const newFacts = [];
+    const retractions = [];
+    for (const rs of ruleStates) {
+      const values = getPathValues(rs.rule.watch);
+      try {
+        const result = rs.rule.evaluate(values, [...facts]);
+        rs.lastResult = result;
+        recordTimeline(rs.rule.watch[0] ?? "*", "rule-eval", {
+          ruleId: rs.rule.id,
+          kind: result.kind,
+          reason: result.reason
+        });
+        switch (result.kind) {
+          case "emit":
+            newFacts.push(...result.facts);
+            for (const f of result.facts) {
+              rs.emittedTags.add(f.tag);
+            }
+            break;
+          case "retract":
+            retractions.push(...result.retractTags);
+            for (const tag of result.retractTags) {
+              rs.emittedTags.delete(tag);
+            }
+            break;
+          case "noop":
+          case "skip":
+            if (rs.emittedTags.size > 0) {
+              retractions.push(...rs.emittedTags);
+              rs.emittedTags.clear();
+            }
+            break;
+        }
+      } catch (err) {
+        console.error(`[praxis] Rule "${rs.rule.id}" error:`, err);
+      }
+    }
+    if (retractions.length > 0) {
+      const retractSet = new Set(retractions);
+      for (const tag of retractSet) {
+        factMap.delete(tag);
+      }
+    }
+    for (const f of newFacts) {
+      factMap.set(f.tag, f);
+    }
+    facts = Array.from(factMap.values());
+  }
+  function query(path, opts) {
+    let state = paths.get(path);
+    if (!state) {
+      state = {
+        schema: { path, initial: void 0 },
+        value: void 0,
+        subscribers: /* @__PURE__ */ new Set(),
+        lastUpdated: 0,
+        updateCount: 0
+      };
+      paths.set(path, state);
+    }
+    const ref = {
+      get current() {
+        const s = paths.get(path);
+        return applyQueryOpts(s?.value ?? state.schema.initial, opts);
+      },
+      subscribe(cb) {
+        const wrappedCb = (rawValue) => {
+          const processed = applyQueryOpts(rawValue, opts);
+          cb(processed);
+        };
+        const s = paths.get(path);
+        s.subscribers.add(wrappedCb);
+        try {
+          cb(ref.current);
+        } catch (err) {
+          console.error(`[praxis] query("${path}") subscriber init error:`, err);
+        }
+        return () => {
+          s.subscribers.delete(wrappedCb);
+        };
+      }
+    };
+    return ref;
+  }
+  function applyQueryOpts(value, opts) {
+    if (!opts || !Array.isArray(value)) return value;
+    let result = [...value];
+    if (opts.where) result = result.filter(opts.where);
+    if (opts.sort) result.sort(opts.sort);
+    if (opts.select) result = result.map(opts.select);
+    if (opts.limit) result = result.slice(0, opts.limit);
+    return result;
+  }
+  function mutateInternal(path, value) {
+    const violations = checkConstraints(path, value);
+    if (violations.length > 0) {
+      return { violations, emittedFacts: [] };
+    }
+    const state = paths.get(path);
+    if (!state) {
+      paths.set(path, {
+        schema: { path, initial: value },
+        value,
+        subscribers: /* @__PURE__ */ new Set(),
+        lastUpdated: Date.now(),
+        updateCount: 1
+      });
+    } else {
+      const before = state.value;
+      state.value = value;
+      state.lastUpdated = Date.now();
+      state.updateCount++;
+      recordTimeline(path, "mutation", {
+        before: summarize(before),
+        after: summarize(value)
+      });
+    }
+    notify(path, value);
+    const factsBefore = facts.length;
+    evaluateRules();
+    const emittedFacts = facts.slice(factsBefore);
+    return { violations: [], emittedFacts };
+  }
+  function mutate(path, value) {
+    const { violations, emittedFacts } = mutateInternal(path, value);
+    return {
+      accepted: violations.length === 0,
+      violations,
+      facts: emittedFacts
+    };
+  }
+  function batchMutate(fn) {
+    const allViolations = [];
+    const pendingWrites = [];
+    fn((path, value) => {
+      const violations = checkConstraints(path, value);
+      if (violations.length > 0) {
+        allViolations.push(...violations);
+      } else {
+        pendingWrites.push({ path, value });
+      }
+    });
+    if (allViolations.length > 0) {
+      return { accepted: false, violations: allViolations, facts: [] };
+    }
+    for (const { path, value } of pendingWrites) {
+      const state = paths.get(path);
+      if (state) {
+        const before = state.value;
+        state.value = value;
+        state.lastUpdated = Date.now();
+        state.updateCount++;
+        recordTimeline(path, "mutation", {
+          before: summarize(before),
+          after: summarize(value)
+        });
+      } else {
+        paths.set(path, {
+          schema: { path, initial: value },
+          value,
+          subscribers: /* @__PURE__ */ new Set(),
+          lastUpdated: Date.now(),
+          updateCount: 1
+        });
+      }
+    }
+    for (const { path, value } of pendingWrites) {
+      notify(path, value);
+    }
+    const factsBefore = facts.length;
+    evaluateRules();
+    return {
+      accepted: true,
+      violations: [],
+      facts: facts.slice(factsBefore)
+    };
+  }
+  function getLiveness() {
+    const result = {};
+    const now = Date.now();
+    const watchPaths = livenessConfig?.expect ?? [];
+    for (const p of watchPaths) {
+      const state = paths.get(p);
+      const lastUpdated = state?.lastUpdated ?? 0;
+      const elapsed = lastUpdated > 0 ? now - lastUpdated : now - initTime;
+      result[p] = {
+        stale: !state || state.updateCount === 0,
+        lastUpdated,
+        elapsed
+      };
+    }
+    return result;
+  }
+  function destroy() {
+    if (livenessTimer) clearTimeout(livenessTimer);
+    for (const state of paths.values()) {
+      state.subscribers.clear();
+    }
+    paths.clear();
+    facts = [];
+    factMap.clear();
+    timeline.length = 0;
+  }
+  return {
+    query,
+    mutate,
+    batch: batchMutate,
+    facts: () => [...facts],
+    violations: () => {
+      const allViolations = [];
+      for (const c of constraints) {
+        const values = getPathValues(c.watch);
+        try {
+          const result = c.validate(values);
+          if (result !== true) {
+            allViolations.push({
+              kind: "constraint-violation",
+              message: result,
+              data: { constraintId: c.id }
+            });
+          }
+        } catch {
+        }
+      }
+      return allViolations;
+    },
+    timeline: () => [...timeline],
+    evaluate: evaluateRules,
+    destroy,
+    liveness: getLiveness
+  };
+}
+function summarize(value) {
+  if (value === null || value === void 0) return value;
+  if (typeof value !== "object") return value;
+  if (Array.isArray(value)) return `[Array(${value.length})]`;
+  const keys = Object.keys(value);
+  if (keys.length > 10) return `{Object(${keys.length} keys)}`;
+  return value;
+}
+
+// src/unified/types.ts
+function definePath(path, initial, opts) {
+  return { path, initial, ...opts };
+}
+
+// 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/unified/rules.ts
+function defineRule(rule) {
+  return rule;
+}
+function defineConstraint(constraint) {
+  return constraint;
+}
+function defineModule(name, rules) {
+  return { name, rules };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  RuleResult,
+  createApp,
+  defineConstraint,
+  defineModule,
+  definePath,
+  defineRule,
+  fact
+});