rulit 1.0.0

package/dist/index.js

@@ -0,0 +1,1357 @@
+"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/index.ts
+var src_exports = {};
+__export(src_exports, {
+  Rules: () => Rules,
+  condition: () => condition,
+  createOtelAdapter: () => createOtelAdapter,
+  field: () => field,
+  op: () => op,
+  registry: () => registry2,
+  ruleset: () => ruleset,
+  zodEffects: () => zodEffects,
+  zodFacts: () => zodFacts
+});
+module.exports = __toCommonJS(src_exports);
+
+// src/condition.ts
+function condition(label, test, options) {
+  const meta = {
+    label,
+    reasonCode: typeof options === "object" ? options?.reasonCode : void 0,
+    kind: "atomic"
+  };
+  const cond = (facts) => {
+    const result = test(facts);
+    const details = typeof options === "function" ? options : options?.details;
+    const info = details ? details(facts) : void 0;
+    return {
+      label,
+      result,
+      left: info?.left,
+      op: info?.op,
+      right: info?.right,
+      reasonCode: meta.reasonCode
+    };
+  };
+  cond.meta = meta;
+  return cond;
+}
+
+// src/field.ts
+function field(path) {
+  if (path === void 0) {
+    return (nextPath) => createField(nextPath);
+  }
+  return createField(path);
+}
+function createField(path) {
+  const getter = (facts) => getPathValue(facts, path);
+  const base = {
+    path,
+    get: getter,
+    eq: (value) => condition(
+      `${path} == ${String(value)}`,
+      (facts) => getter(facts) === value,
+      (facts) => ({
+        left: getter(facts),
+        op: "==",
+        right: value
+      })
+    ),
+    in: (values) => condition(
+      `${path} in [${values.length}]`,
+      (facts) => values.includes(getter(facts)),
+      (facts) => ({
+        left: getter(facts),
+        op: "in",
+        right: values
+      })
+    )
+  };
+  return addOperators(base);
+}
+function addOperators(base) {
+  const anyBase = base;
+  anyBase.gt = (value) => condition(
+    `${base.path} > ${value}`,
+    (facts) => Number(base.get(facts)) > value,
+    (facts) => ({
+      left: base.get(facts),
+      op: ">",
+      right: value
+    })
+  );
+  anyBase.gte = (value) => condition(
+    `${base.path} >= ${value}`,
+    (facts) => Number(base.get(facts)) >= value,
+    (facts) => ({
+      left: base.get(facts),
+      op: ">=",
+      right: value
+    })
+  );
+  anyBase.lt = (value) => condition(
+    `${base.path} < ${value}`,
+    (facts) => Number(base.get(facts)) < value,
+    (facts) => ({
+      left: base.get(facts),
+      op: "<",
+      right: value
+    })
+  );
+  anyBase.lte = (value) => condition(
+    `${base.path} <= ${value}`,
+    (facts) => Number(base.get(facts)) <= value,
+    (facts) => ({
+      left: base.get(facts),
+      op: "<=",
+      right: value
+    })
+  );
+  anyBase.between = (min, max) => condition(
+    `${base.path} between ${min} and ${max}`,
+    (facts) => {
+      const value = Number(base.get(facts));
+      return value >= min && value <= max;
+    },
+    (facts) => ({
+      left: base.get(facts),
+      op: "between",
+      right: [min, max]
+    })
+  );
+  anyBase.contains = (value) => condition(
+    `${base.path} contains ${String(value)}`,
+    (facts) => {
+      const current = base.get(facts);
+      if (typeof current === "string") {
+        return current.includes(String(value));
+      }
+      if (Array.isArray(current)) {
+        return current.includes(value);
+      }
+      return false;
+    },
+    (facts) => ({
+      left: base.get(facts),
+      op: "contains",
+      right: value
+    })
+  );
+  anyBase.startsWith = (value) => condition(
+    `${base.path} startsWith ${value}`,
+    (facts) => {
+      const current = base.get(facts);
+      return typeof current === "string" ? current.startsWith(value) : false;
+    },
+    (facts) => ({
+      left: base.get(facts),
+      op: "startsWith",
+      right: value
+    })
+  );
+  anyBase.matches = (value) => condition(
+    `${base.path} matches ${value.toString()}`,
+    (facts) => {
+      const current = base.get(facts);
+      return typeof current === "string" ? value.test(current) : false;
+    },
+    (facts) => ({
+      left: base.get(facts),
+      op: "matches",
+      right: value.toString()
+    })
+  );
+  anyBase.isTrue = () => condition(
+    `${base.path} is true`,
+    (facts) => base.get(facts) === true,
+    (facts) => ({
+      left: base.get(facts),
+      op: "is",
+      right: true
+    })
+  );
+  anyBase.isFalse = () => condition(
+    `${base.path} is false`,
+    (facts) => base.get(facts) === false,
+    (facts) => ({
+      left: base.get(facts),
+      op: "is",
+      right: false
+    })
+  );
+  anyBase.before = (value) => condition(
+    `${base.path} before ${value.toISOString()}`,
+    (facts) => {
+      const current = base.get(facts);
+      return current instanceof Date ? current.getTime() < value.getTime() : false;
+    },
+    (facts) => ({
+      left: base.get(facts),
+      op: "before",
+      right: value.toISOString()
+    })
+  );
+  anyBase.after = (value) => condition(
+    `${base.path} after ${value.toISOString()}`,
+    (facts) => {
+      const current = base.get(facts);
+      return current instanceof Date ? current.getTime() > value.getTime() : false;
+    },
+    (facts) => ({
+      left: base.get(facts),
+      op: "after",
+      right: value.toISOString()
+    })
+  );
+  anyBase.any = (predicate, label = `${base.path} any`) => condition(
+    label,
+    (facts) => {
+      const current = base.get(facts);
+      return Array.isArray(current) ? current.some(predicate) : false;
+    },
+    (facts) => ({
+      left: base.get(facts),
+      op: "any",
+      right: "predicate"
+    })
+  );
+  anyBase.all = (predicate, label = `${base.path} all`) => condition(
+    label,
+    (facts) => {
+      const current = base.get(facts);
+      return Array.isArray(current) ? current.every(predicate) : false;
+    },
+    (facts) => ({
+      left: base.get(facts),
+      op: "all",
+      right: "predicate"
+    })
+  );
+  return base;
+}
+function getPathValue(facts, path) {
+  const parts = String(path).split(".");
+  let current = facts;
+  for (const part of parts) {
+    if (current && typeof current === "object") {
+      current = current[part];
+    } else {
+      return void 0;
+    }
+  }
+  return current;
+}
+
+// src/op.ts
+function resolveLabel(defaultLabel, label) {
+  if (!label) {
+    return defaultLabel;
+  }
+  return typeof label === "string" ? label : label.label;
+}
+var op = { and, or, not, custom, register, use, has, list };
+var registry = {};
+function and(...args) {
+  const { label, conditions } = splitArgs("and", args);
+  const meta = { label, kind: "and", children: conditions };
+  const cond = (facts) => {
+    const children = conditions.map((cond2) => cond2(facts));
+    const result = children.every((child) => child.result);
+    return {
+      label,
+      result,
+      op: "and",
+      left: children.map((child) => child.label),
+      right: void 0,
+      children
+    };
+  };
+  cond.meta = meta;
+  return cond;
+}
+function or(...args) {
+  const { label, conditions } = splitArgs("or", args);
+  const meta = { label, kind: "or", children: conditions };
+  const cond = (facts) => {
+    const children = conditions.map((cond2) => cond2(facts));
+    const result = children.some((child) => child.result);
+    return {
+      label,
+      result,
+      op: "or",
+      left: children.map((child) => child.label),
+      right: void 0,
+      children
+    };
+  };
+  cond.meta = meta;
+  return cond;
+}
+function not(labelOrCondition, maybeCondition) {
+  const label = resolveLabel(
+    "not",
+    typeof labelOrCondition === "function" ? void 0 : labelOrCondition
+  );
+  const conditionToNegate = typeof labelOrCondition === "function" ? labelOrCondition : maybeCondition;
+  const meta = {
+    label,
+    kind: "not",
+    children: [conditionToNegate]
+  };
+  const cond = (facts) => {
+    const child = conditionToNegate(facts);
+    return {
+      label,
+      result: !child.result,
+      op: "not",
+      left: child.label,
+      right: void 0,
+      children: [child]
+    };
+  };
+  cond.meta = meta;
+  return cond;
+}
+function custom(label, test, options) {
+  return condition(label, test, options);
+}
+function register(name, factory) {
+  if (registry[name]) {
+    throw new Error(`Operator "${name}" is already registered.`);
+  }
+  registry[name] = factory;
+}
+function use(name, ...args) {
+  const factory = registry[name];
+  if (!factory) {
+    throw new Error(`Operator "${name}" is not registered.`);
+  }
+  return factory(...args);
+}
+function has(name) {
+  return Boolean(registry[name]);
+}
+function list() {
+  return Object.keys(registry).sort();
+}
+function splitArgs(defaultLabel, args) {
+  if (args.length === 0) {
+    return { label: defaultLabel, conditions: [] };
+  }
+  const [first, ...rest] = args;
+  if (typeof first === "function") {
+    return { label: defaultLabel, conditions: args };
+  }
+  const conditions = rest;
+  return {
+    label: resolveLabel(defaultLabel, first),
+    conditions
+  };
+}
+
+// src/trace.ts
+function explainTrace(trace, name) {
+  const header = name ? `Ruleset ${name}` : "Ruleset";
+  const lines = [header];
+  for (const rule of trace) {
+    const tags = rule.meta?.tags?.length ? ` [tags: ${rule.meta.tags.join(", ")}]` : "";
+    const reason = rule.meta?.reasonCode ? ` [reason: ${rule.meta.reasonCode}]` : "";
+    const skipped = rule.skippedReason ? ` (skipped: ${rule.skippedReason})` : "";
+    lines.push(
+      `- Rule ${rule.ruleId}: ${rule.matched ? "matched" : "skipped"}${skipped}${tags}${reason}`
+    );
+    for (const condition2 of rule.conditions) {
+      lines.push(...renderCondition(condition2, 2));
+    }
+    for (const note of rule.notes) {
+      lines.push(`  - note: ${note}`);
+    }
+  }
+  return lines.join("\n");
+}
+function formatCondition(condition2) {
+  const parts = [`[${condition2.result ? "true" : "false"}]`, condition2.label];
+  if (condition2.reasonCode) {
+    parts.push(`{reason: ${condition2.reasonCode}}`);
+  }
+  if (condition2.op) {
+    const left = formatValue(condition2.left);
+    const right = formatValue(condition2.right);
+    parts.push(`(${left} ${condition2.op} ${right})`);
+  }
+  return parts.join(" ");
+}
+function renderCondition(condition2, indent) {
+  const pad = " ".repeat(indent);
+  const lines = [`${pad}- ${formatCondition(condition2)}`];
+  if (condition2.children && condition2.children.length > 0) {
+    for (const child of condition2.children) {
+      lines.push(...renderCondition(child, indent + 2));
+    }
+  }
+  return lines;
+}
+function formatValue(value) {
+  if (typeof value === "string") {
+    return `"${value}"`;
+  }
+  return String(value);
+}
+
+// src/registry.ts
+var entries = /* @__PURE__ */ new Map();
+var nameIndex = /* @__PURE__ */ new Map();
+var counter = 0;
+var traceCounter = 0;
+var traceLimit = 25;
+function makeId() {
+  return `ruleset-${counter++}`;
+}
+var registry2 = {
+  /**
+   * Register a ruleset in the global registry.
+   *
+   * @example
+   * ```ts
+   * const rs = Rules.ruleset<Facts, Effects>("eligibility");
+   * Rules.registry.list();
+   * ```
+   */
+  register(source, name) {
+    const id = makeId();
+    entries.set(id, { id, name, createdAt: Date.now(), source, traces: [] });
+    if (name) {
+      nameIndex.set(name, id);
+    }
+    return id;
+  },
+  /**
+   * List all registered rulesets.
+   *
+   * @example
+   * ```ts
+   * const list = Rules.registry.list();
+   * ```
+   */
+  list() {
+    return Array.from(entries.values()).map(({ id, name, createdAt }) => ({
+      id,
+      name,
+      createdAt
+    }));
+  },
+  /**
+   * Get a graph by id or ruleset name.
+   *
+   * @example
+   * ```ts
+   * const graph = Rules.registry.getGraph("eligibility");
+   * ```
+   */
+  getGraph(idOrName) {
+    const entry = getEntry(idOrName);
+    return entry?.source.graph();
+  },
+  /**
+   * Get Mermaid output by id or ruleset name.
+   *
+   * @example
+   * ```ts
+   * const mermaid = Rules.registry.getMermaid("eligibility");
+   * ```
+   */
+  getMermaid(idOrName) {
+    const entry = getEntry(idOrName);
+    return entry?.source.toMermaid();
+  },
+  /**
+   * Record a trace run for a ruleset. Keeps a rolling window of traces.
+   *
+   * @example
+   * ```ts
+   * Rules.registry.recordTrace("eligibility", trace, fired);
+   * ```
+   */
+  recordTrace(idOrName, trace, fired, facts) {
+    const entry = getEntry(idOrName);
+    if (!entry) {
+      return void 0;
+    }
+    const run = {
+      id: `trace-${traceCounter++}`,
+      createdAt: Date.now(),
+      facts,
+      fired,
+      trace
+    };
+    entry.traces.push(run);
+    if (entry.traces.length > traceLimit) {
+      entry.traces.splice(0, entry.traces.length - traceLimit);
+    }
+    return run;
+  },
+  /**
+   * List trace runs for a ruleset.
+   *
+   * @example
+   * ```ts
+   * const traces = Rules.registry.listTraces("eligibility");
+   * ```
+   */
+  listTraces(idOrName) {
+    const entry = getEntry(idOrName);
+    return entry ? [...entry.traces] : [];
+  },
+  /**
+   * Get a trace by id for a ruleset.
+   *
+   * @example
+   * ```ts
+   * const trace = Rules.registry.getTrace("eligibility", "trace-0");
+   * ```
+   */
+  getTrace(idOrName, traceId) {
+    const entry = getEntry(idOrName);
+    return entry?.traces.find((run) => run.id === traceId);
+  },
+  /**
+   * Clear the registry (useful in tests).
+   *
+   * @example
+   * ```ts
+   * Rules.registry.clear();
+   * ```
+   */
+  clear() {
+    entries.clear();
+    nameIndex.clear();
+    traceCounter = 0;
+  }
+};
+function getEntry(idOrName) {
+  const byId = entries.get(idOrName);
+  if (byId) {
+    return byId;
+  }
+  const id = nameIndex.get(idOrName);
+  return id ? entries.get(id) : void 0;
+}
+
+// src/ruleset.ts
+var RulesetBuilderImpl = class {
+  constructor(name) {
+    this.rules = [];
+    this.nextOrder = 0;
+    this.name = name;
+  }
+  /**
+   * Set the default effects factory. Required before compile().
+   *
+   * @example
+   * ```ts
+   * const rs = Rules.ruleset<Facts, Effects>("rs")
+   *   .defaultEffects(() => ({ flags: [] }));
+   * ```
+   */
+  defaultEffects(factory) {
+    this.defaultEffectsFactory = factory;
+    return this;
+  }
+  /**
+   * Provide a validation function for facts. Called before each run.
+   *
+   * @example
+   * ```ts
+   * const rs = Rules.ruleset<Facts, Effects>("validate")
+   *   .validateFacts((facts) => {
+   *     if (!facts.user) throw new Error("missing user");
+   *   });
+   * ```
+   */
+  validateFacts(validator) {
+    this.validateFactsFn = validator;
+    return this;
+  }
+  /**
+   * Provide a validation function for effects. Called after default effects creation
+   * and after each run completes.
+   *
+   * @example
+   * ```ts
+   * const rs = Rules.ruleset<Facts, Effects>("validate")
+   *   .validateEffects((effects) => {
+   *     if (!Array.isArray(effects.flags)) throw new Error("invalid effects");
+   *   });
+   * ```
+   */
+  validateEffects(validator) {
+    this.validateEffectsFn = validator;
+    return this;
+  }
+  /**
+   * Attach telemetry adapter (OpenTelemetry-compatible).
+   *
+   * @example
+   * ```ts
+   * const adapter = Rules.otel.createAdapter(trace.getTracer("rulit"));
+   * Rules.ruleset("rs").telemetry(adapter);
+   * ```
+   */
+  telemetry(adapter) {
+    this.telemetryAdapter = adapter;
+    return this;
+  }
+  _setRegistryId(id) {
+    this.registryId = id;
+  }
+  /**
+   * Add a new rule to the ruleset.
+   *
+   * @example
+   * ```ts
+   * Rules.ruleset<Facts, Effects>("rs")
+   *   .defaultEffects(() => ({ flags: [] }))
+   *   .rule("vip")
+   *   .when(factsField("user.tags").contains("vip"))
+   *   .then(({ effects }) => effects.flags.push("vip"))
+   *   .end();
+   * ```
+   */
+  rule(id) {
+    return new RuleBuilderImpl(this, id);
+  }
+  /**
+   * Create a typed field helper bound to the facts type.
+   *
+   * @example
+   * ```ts
+   * const factsField = Rules.ruleset<Facts, Effects>("rs").field();
+   * const isAdult = factsField("user.age").gte(18);
+   * ```
+   */
+  field() {
+    return field();
+  }
+  _addRule(rule) {
+    this.rules.push(rule);
+  }
+  _nextOrder() {
+    const order = this.nextOrder;
+    this.nextOrder += 1;
+    return order;
+  }
+  /**
+   * Export a graph representation of the ruleset.
+   *
+   * @example
+   * ```ts
+   * const graph = ruleset.graph();
+   * ```
+   */
+  graph() {
+    const nodes = [];
+    const edges = [];
+    const rulesetId = `ruleset:${this.name ?? "ruleset"}`;
+    nodes.push({
+      id: rulesetId,
+      type: "ruleset",
+      label: this.name ?? "ruleset"
+    });
+    let conditionCounter = 0;
+    const visitCondition = (condition2, parentId) => {
+      const meta = condition2.meta;
+      const conditionId = `condition:${conditionCounter++}`;
+      nodes.push({
+        id: conditionId,
+        type: "condition",
+        label: meta?.label ?? "condition",
+        reasonCode: meta?.reasonCode
+      });
+      edges.push({ from: parentId, to: conditionId });
+      if (meta?.children && meta.children.length > 0) {
+        for (const child of meta.children) {
+          visitCondition(child, conditionId);
+        }
+      }
+    };
+    for (const rule of this.rules) {
+      const ruleId = `rule:${rule.id}`;
+      nodes.push({
+        id: ruleId,
+        type: "rule",
+        label: rule.id,
+        reasonCode: rule.meta?.reasonCode,
+        tags: rule.meta?.tags,
+        description: rule.meta?.description,
+        version: rule.meta?.version
+      });
+      edges.push({ from: rulesetId, to: ruleId });
+      for (const condition2 of rule.conditions) {
+        visitCondition(condition2, ruleId);
+      }
+    }
+    return { nodes, edges };
+  }
+  /**
+   * Export a Mermaid flowchart for visualization.
+   *
+   * @example
+   * ```ts
+   * const mermaid = ruleset.toMermaid();
+   * ```
+   */
+  toMermaid() {
+    const graph = this.graph();
+    const idMap = /* @__PURE__ */ new Map();
+    let counter2 = 0;
+    for (const node of graph.nodes) {
+      idMap.set(node.id, `n${counter2++}`);
+    }
+    const lines = ["flowchart TD"];
+    for (const node of graph.nodes) {
+      const id = idMap.get(node.id);
+      if (!id) {
+        continue;
+      }
+      const reason = node.reasonCode ? ` [reason: ${node.reasonCode}]` : "";
+      const tags = node.tags?.length ? ` [tags: ${node.tags.join(", ")}]` : "";
+      const label = `${capitalize(node.type)}: ${node.label}${tags}${reason}`;
+      lines.push(`  ${id}["${label}"]`);
+    }
+    for (const edge of graph.edges) {
+      const from = idMap.get(edge.from);
+      const to = idMap.get(edge.to);
+      if (from && to) {
+        lines.push(`  ${from} --> ${to}`);
+      }
+    }
+    return lines.join("\n");
+  }
+  /**
+   * Compile the ruleset into an engine.
+   *
+   * @example
+   * ```ts
+   * const engine = Rules.ruleset<Facts, Effects>("rs")
+   *   .defaultEffects(() => ({ flags: [] }))
+   *   .compile();
+   * ```
+   */
+  compile() {
+    const defaultEffectsFactory = this.defaultEffectsFactory;
+    if (!defaultEffectsFactory) {
+      throw new Error("defaultEffects() is required before compile().");
+    }
+    const sortedRules = [...this.rules].sort((a, b) => {
+      if (a.priority !== b.priority) {
+        return b.priority - a.priority;
+      }
+      return a.order - b.order;
+    });
+    return {
+      run: ({
+        facts,
+        activation = "all",
+        effectsMode = "mutable",
+        mergeStrategy = "assign",
+        rollbackOnError = false,
+        includeTags,
+        excludeTags
+      }) => {
+        return runWithSpan(
+          this.telemetryAdapter,
+          "rulit.run",
+          rulesetSpanAttrs(this.name, this.registryId),
+          () => runSync({
+            facts,
+            activation,
+            effectsMode,
+            mergeStrategy,
+            rollbackOnError,
+            includeTags,
+            excludeTags,
+            rules: sortedRules,
+            defaultEffectsFactory,
+            validateFactsFn: this.validateFactsFn,
+            validateEffectsFn: this.validateEffectsFn,
+            registryId: this.registryId,
+            rulesetName: this.name,
+            telemetryAdapter: this.telemetryAdapter
+          })
+        );
+      },
+      runAsync: async ({
+        facts,
+        activation = "all",
+        effectsMode = "mutable",
+        mergeStrategy = "assign",
+        rollbackOnError = false,
+        includeTags,
+        excludeTags
+      }) => {
+        return runWithSpanAsync(
+          this.telemetryAdapter,
+          "rulit.run",
+          rulesetSpanAttrs(this.name, this.registryId),
+          () => runAsync({
+            facts,
+            activation,
+            effectsMode,
+            mergeStrategy,
+            rollbackOnError,
+            includeTags,
+            excludeTags,
+            rules: sortedRules,
+            defaultEffectsFactory,
+            validateFactsFn: this.validateFactsFn,
+            validateEffectsFn: this.validateEffectsFn,
+            registryId: this.registryId,
+            rulesetName: this.name,
+            telemetryAdapter: this.telemetryAdapter
+          })
+        );
+      }
+    };
+  }
+};
+var RuleBuilderImpl = class {
+  constructor(ruleset2, id) {
+    this.priorityValue = 0;
+    this.conditions = [];
+    this.metaValue = {};
+    this.ruleset = ruleset2;
+    this.id = id;
+  }
+  /**
+   * Set rule priority. Higher runs first.
+   *
+   * @example
+   * ```ts
+   * rule.priority(100);
+   * ```
+   */
+  priority(value) {
+    this.priorityValue = value;
+    return this;
+  }
+  /**
+   * Add conditions to a rule.
+   *
+   * @example
+   * ```ts
+   * rule.when(factsField("user.age").gte(18), factsField("user.tags").contains("vip"));
+   * ```
+   */
+  when(...conditions) {
+    this.conditions = conditions;
+    return this;
+  }
+  /**
+   * Set rule metadata in one call.
+   *
+   * @example
+   * ```ts
+   * rule.meta({ tags: ["vip"], version: "1.0.0", reasonCode: "VIP_RULE" });
+   * ```
+   */
+  meta(meta) {
+    const tags = meta.tags ?? this.metaValue.tags;
+    this.metaValue = { ...this.metaValue, ...meta, tags };
+    return this;
+  }
+  /**
+   * Set rule tags used for filtering.
+   *
+   * @example
+   * ```ts
+   * rule.tags("vip", "adult");
+   * ```
+   */
+  tags(...tags) {
+    this.metaValue = { ...this.metaValue, tags };
+    return this;
+  }
+  /**
+   * Set a human-readable description.
+   *
+   * @example
+   * ```ts
+   * rule.description("VIP adult rule");
+   * ```
+   */
+  description(description) {
+    this.metaValue = { ...this.metaValue, description };
+    return this;
+  }
+  /**
+   * Set a rule version string.
+   *
+   * @example
+   * ```ts
+   * rule.version("1.2.3");
+   * ```
+   */
+  version(version) {
+    this.metaValue = { ...this.metaValue, version };
+    return this;
+  }
+  /**
+   * Set a reason code for audit/explain output.
+   *
+   * @example
+   * ```ts
+   * rule.reasonCode("VIP_ADULT");
+   * ```
+   */
+  reasonCode(reasonCode) {
+    this.metaValue = { ...this.metaValue, reasonCode };
+    return this;
+  }
+  /**
+   * Enable or disable a rule.
+   *
+   * @example
+   * ```ts
+   * rule.enabled(false);
+   * ```
+   */
+  enabled(enabled) {
+    this.metaValue = { ...this.metaValue, enabled };
+    return this;
+  }
+  /**
+   * Set the rule action. Returning a partial effects object applies a patch.
+   *
+   * @example
+   * ```ts
+   * rule.then(({ effects }) => {
+   *   effects.flags.push("vip");
+   * });
+   * ```
+   */
+  then(action) {
+    this.action = action;
+    return this;
+  }
+  /**
+   * Set an async rule action. Returning a partial effects object applies a patch.
+   *
+   * @example
+   * ```ts
+   * rule.thenAsync(async ({ effects }) => {
+   *   effects.flags.push("vip");
+   * });
+   * ```
+   */
+  thenAsync(action) {
+    this.action = action;
+    return this;
+  }
+  /**
+   * Finalize the rule and return to the ruleset builder.
+   *
+   * @example
+   * ```ts
+   * ruleset.rule("vip").then(() => undefined).end();
+   * ```
+   */
+  end() {
+    if (!this.action) {
+      throw new Error("then() is required before end().");
+    }
+    const rule = {
+      id: this.id,
+      priority: this.priorityValue,
+      order: this.ruleset._nextOrder(),
+      conditions: this.conditions,
+      action: this.action,
+      meta: Object.keys(this.metaValue).length ? this.metaValue : void 0
+    };
+    this.ruleset._addRule(rule);
+    return this.ruleset;
+  }
+};
+function ruleset(name) {
+  const builder = new RulesetBuilderImpl(name);
+  const registryId = registry2.register(builder, name);
+  builder._setRegistryId(registryId);
+  return builder;
+}
+function getSkipReason(meta, includeTags, excludeTags) {
+  if (meta?.enabled === false) {
+    return "disabled";
+  }
+  const tags = meta?.tags ?? [];
+  if (includeTags && includeTags.length > 0 && !includeTags.some((tag) => tags.includes(tag))) {
+    return "tag-filtered";
+  }
+  if (excludeTags && excludeTags.length > 0 && excludeTags.some((tag) => tags.includes(tag))) {
+    return "tag-excluded";
+  }
+  return void 0;
+}
+function mergeEffects(target, patch, strategy) {
+  if (strategy === "assign") {
+    Object.assign(target, patch);
+    return;
+  }
+  deepMerge(target, patch);
+}
+function deepMerge(target, patch) {
+  for (const [key, value] of Object.entries(patch)) {
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+      const current = target[key];
+      if (!current || typeof current !== "object" || Array.isArray(current)) {
+        target[key] = {};
+      }
+      deepMerge(target[key], value);
+    } else {
+      target[key] = value;
+    }
+  }
+}
+function cloneEffects(effects) {
+  if (typeof structuredClone === "function") {
+    return structuredClone(effects);
+  }
+  return JSON.parse(JSON.stringify(effects));
+}
+function runSync({
+  facts,
+  activation,
+  effectsMode,
+  mergeStrategy,
+  rollbackOnError,
+  includeTags,
+  excludeTags,
+  rules,
+  defaultEffectsFactory,
+  validateFactsFn,
+  validateEffectsFn,
+  registryId,
+  rulesetName,
+  telemetryAdapter
+}) {
+  validateFactsFn?.(facts);
+  let effects = defaultEffectsFactory();
+  validateEffectsFn?.(effects);
+  const trace = [];
+  const fired = [];
+  for (const rule of rules) {
+    const start = Date.now();
+    const ruleTrace = {
+      ruleId: rule.id,
+      matched: false,
+      conditions: [],
+      notes: [],
+      meta: rule.meta
+    };
+    const skipReason = getSkipReason(rule.meta, includeTags, excludeTags);
+    if (skipReason) {
+      ruleTrace.skippedReason = skipReason;
+      ruleTrace.durationMs = Date.now() - start;
+      trace.push(ruleTrace);
+      continue;
+    }
+    let matched = true;
+    for (const condition2 of rule.conditions) {
+      const conditionTrace = runWithSpan(
+        telemetryAdapter,
+        "rulit.condition",
+        conditionSpanAttrs(rulesetName, rule, condition2),
+        () => condition2(facts)
+      );
+      ruleTrace.conditions.push(conditionTrace);
+      if (!conditionTrace.result) {
+        matched = false;
+        break;
+      }
+    }
+    ruleTrace.matched = matched;
+    if (matched) {
+      const workingEffects = effectsMode === "immutable" ? cloneEffects(effects) : effects;
+      const ctx = {
+        facts,
+        effects: workingEffects,
+        trace: {
+          note: (message) => {
+            ruleTrace.notes.push(message);
+          }
+        }
+      };
+      try {
+        const patch = runWithSpan(
+          telemetryAdapter,
+          "rulit.rule",
+          ruleSpanAttrs(rulesetName, rule),
+          () => rule.action(ctx)
+        );
+        if (isPromise(patch)) {
+          throw new Error("Async rule action detected. Use runAsync().");
+        }
+        if (patch && typeof patch === "object") {
+          mergeEffects(workingEffects, patch, mergeStrategy);
+        }
+        if (effectsMode === "immutable") {
+          effects = workingEffects;
+        }
+      } catch (error) {
+        ruleTrace.error = String(error);
+        ruleTrace.notes.push(`error: ${String(error)}`);
+        if (!rollbackOnError) {
+          throw error;
+        }
+        if (effectsMode === "immutable") {
+          effects = effects;
+        }
+      }
+      fired.push(rule.id);
+    }
+    ruleTrace.durationMs = Date.now() - start;
+    trace.push(ruleTrace);
+    if (matched && activation === "first") {
+      break;
+    }
+  }
+  validateEffectsFn?.(effects);
+  if (registryId) {
+    registry2.recordTrace(registryId, trace, fired, facts);
+  }
+  return {
+    effects,
+    fired,
+    trace,
+    explain: () => explainTrace(trace, rulesetName)
+  };
+}
+async function runAsync({
+  facts,
+  activation,
+  effectsMode,
+  mergeStrategy,
+  rollbackOnError,
+  includeTags,
+  excludeTags,
+  rules,
+  defaultEffectsFactory,
+  validateFactsFn,
+  validateEffectsFn,
+  registryId,
+  rulesetName,
+  telemetryAdapter
+}) {
+  validateFactsFn?.(facts);
+  let effects = defaultEffectsFactory();
+  validateEffectsFn?.(effects);
+  const trace = [];
+  const fired = [];
+  for (const rule of rules) {
+    const start = Date.now();
+    const ruleTrace = {
+      ruleId: rule.id,
+      matched: false,
+      conditions: [],
+      notes: [],
+      meta: rule.meta
+    };
+    const skipReason = getSkipReason(rule.meta, includeTags, excludeTags);
+    if (skipReason) {
+      ruleTrace.skippedReason = skipReason;
+      ruleTrace.durationMs = Date.now() - start;
+      trace.push(ruleTrace);
+      continue;
+    }
+    let matched = true;
+    for (const condition2 of rule.conditions) {
+      const conditionTrace = runWithSpan(
+        telemetryAdapter,
+        "rulit.condition",
+        conditionSpanAttrs(rulesetName, rule, condition2),
+        () => condition2(facts)
+      );
+      ruleTrace.conditions.push(conditionTrace);
+      if (!conditionTrace.result) {
+        matched = false;
+        break;
+      }
+    }
+    ruleTrace.matched = matched;
+    if (matched) {
+      const workingEffects = effectsMode === "immutable" ? cloneEffects(effects) : effects;
+      const ctx = {
+        facts,
+        effects: workingEffects,
+        trace: {
+          note: (message) => {
+            ruleTrace.notes.push(message);
+          }
+        }
+      };
+      try {
+        const patch = await runWithSpanAsync(
+          telemetryAdapter,
+          "rulit.rule",
+          ruleSpanAttrs(rulesetName, rule),
+          () => rule.action(ctx)
+        );
+        if (patch && typeof patch === "object") {
+          mergeEffects(workingEffects, patch, mergeStrategy);
+        }
+        if (effectsMode === "immutable") {
+          effects = workingEffects;
+        }
+      } catch (error) {
+        ruleTrace.error = String(error);
+        ruleTrace.notes.push(`error: ${String(error)}`);
+        if (!rollbackOnError) {
+          throw error;
+        }
+        if (effectsMode === "immutable") {
+          effects = effects;
+        }
+      }
+      fired.push(rule.id);
+    }
+    ruleTrace.durationMs = Date.now() - start;
+    trace.push(ruleTrace);
+    if (matched && activation === "first") {
+      break;
+    }
+  }
+  validateEffectsFn?.(effects);
+  if (registryId) {
+    registry2.recordTrace(registryId, trace, fired, facts);
+  }
+  return {
+    effects,
+    fired,
+    trace,
+    explain: () => explainTrace(trace, rulesetName)
+  };
+}
+function isPromise(value) {
+  return Boolean(value) && typeof value.then === "function";
+}
+function runWithSpan(adapter, name, attributes, fn) {
+  if (!adapter) {
+    return fn();
+  }
+  const span = adapter.startSpan(name, attributes);
+  try {
+    const result = fn();
+    span.end();
+    return result;
+  } catch (error) {
+    span.recordException?.(error);
+    span.end();
+    throw error;
+  }
+}
+async function runWithSpanAsync(adapter, name, attributes, fn) {
+  if (!adapter) {
+    return await fn();
+  }
+  const span = adapter.startSpan(name, attributes);
+  try {
+    const result = await fn();
+    span.end();
+    return result;
+  } catch (error) {
+    span.recordException?.(error);
+    span.end();
+    throw error;
+  }
+}
+function rulesetSpanAttrs(name, registryId) {
+  return {
+    "rulit.ruleset": name ?? registryId ?? "ruleset"
+  };
+}
+function ruleSpanAttrs(rulesetName, rule) {
+  return {
+    "rulit.ruleset": rulesetName ?? "ruleset",
+    "rulit.rule_id": rule.id
+  };
+}
+function conditionSpanAttrs(rulesetName, rule, condition2) {
+  return {
+    "rulit.ruleset": rulesetName ?? "ruleset",
+    "rulit.rule_id": rule.id,
+    "rulit.condition": condition2.meta?.label ?? "condition"
+  };
+}
+function capitalize(value) {
+  return value.length > 0 ? value[0].toUpperCase() + value.slice(1) : value;
+}
+
+// src/zod.ts
+function zodFacts(schema) {
+  return (facts) => {
+    schema.parse(facts);
+  };
+}
+function zodEffects(schema) {
+  return (effects) => {
+    schema.parse(effects);
+  };
+}
+
+// src/otel.ts
+function createOtelAdapter(tracer) {
+  return {
+    startSpan(name, attributes) {
+      const span = tracer.startSpan(name, { attributes });
+      if (attributes) {
+        span.setAttributes?.(attributes);
+      }
+      return span;
+    }
+  };
+}
+
+// src/index.ts
+var Rules = {
+  ruleset,
+  condition,
+  field,
+  op,
+  registry: registry2,
+  zodFacts,
+  zodEffects,
+  otel: {
+    createAdapter: createOtelAdapter
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Rules,
+  condition,
+  createOtelAdapter,
+  field,
+  op,
+  registry,
+  ruleset,
+  zodEffects,
+  zodFacts
+});
+//# sourceMappingURL=index.js.map