@plures/praxis 1.3.0 → 1.4.4

package/dist/node/chunk-AZLNISFI.js

@@ -0,0 +1,1690 @@
+import {
+  getContractFromDescriptor
+} from "./chunk-PGVSB6NR.js";
+import {
+  RuleResult
+} from "./chunk-IG5BJ2MT.js";
+
+// src/dsl/index.ts
+function defineFact(tag) {
+  return {
+    tag,
+    create(payload) {
+      return { tag, payload };
+    },
+    is(fact) {
+      return fact.tag === tag;
+    }
+  };
+}
+function defineEvent(tag) {
+  return {
+    tag,
+    create(payload) {
+      return { tag, payload };
+    },
+    is(event) {
+      return event.tag === tag;
+    }
+  };
+}
+function defineRule(options) {
+  const contract = options.contract ?? options.meta?.contract;
+  const meta = contract ? { ...options.meta ?? {}, contract } : options.meta;
+  return {
+    id: options.id,
+    description: options.description,
+    impl: options.impl,
+    eventTypes: options.eventTypes,
+    contract,
+    meta
+  };
+}
+function defineConstraint(options) {
+  const contract = options.contract ?? options.meta?.contract;
+  const meta = contract ? { ...options.meta ?? {}, contract } : options.meta;
+  return {
+    id: options.id,
+    description: options.description,
+    impl: options.impl,
+    contract,
+    meta
+  };
+}
+function defineModule(options) {
+  return {
+    rules: options.rules ?? [],
+    constraints: options.constraints ?? [],
+    meta: options.meta
+  };
+}
+function filterEvents(events, definition) {
+  return events.filter(definition.is);
+}
+function filterFacts(facts, definition) {
+  return facts.filter(definition.is);
+}
+function findEvent(events, definition) {
+  return events.find(definition.is);
+}
+function findFact(facts, definition) {
+  return facts.find(definition.is);
+}
+
+// src/decision-ledger/facts-events.ts
+var ContractMissing = defineFact("ContractMissing");
+var ContractValidated = defineFact("ContractValidated");
+var AcknowledgeContractGap = defineEvent("ACKNOWLEDGE_CONTRACT_GAP");
+var ValidateContracts = defineEvent("VALIDATE_CONTRACTS");
+var ContractGapAcknowledged = defineFact("ContractGapAcknowledged");
+var ContractAdded = defineEvent("CONTRACT_ADDED");
+var ContractUpdated = defineEvent("CONTRACT_UPDATED");
+var ContractGapEmitted = defineEvent("CONTRACT_GAP_EMITTED");
+
+// src/decision-ledger/validation.ts
+function validateContracts(registry, options = {}) {
+  const {
+    incompleteSeverity = "warning",
+    requiredFields = ["behavior", "examples"],
+    artifactIndex
+  } = options;
+  const complete = [];
+  const incomplete = [];
+  const missing = [];
+  for (const rule of registry.getAllRules()) {
+    const contract = getContractFromDescriptor(rule);
+    if (!contract) {
+      missing.push(rule.id);
+      if (options.missingSeverity) {
+        incomplete.push({
+          ruleId: rule.id,
+          missing: ["contract"],
+          severity: options.missingSeverity,
+          message: `Rule '${rule.id}' has no contract`
+        });
+      }
+      continue;
+    }
+    const gaps = validateContract(contract, requiredFields, artifactIndex);
+    if (gaps.length > 0) {
+      incomplete.push({
+        ruleId: rule.id,
+        missing: gaps,
+        severity: incompleteSeverity,
+        message: `Rule '${rule.id}' contract is incomplete: missing ${gaps.join(", ")}`
+      });
+    } else {
+      complete.push({ ruleId: rule.id, contract });
+    }
+  }
+  for (const constraint of registry.getAllConstraints()) {
+    const contract = getContractFromDescriptor(constraint);
+    if (!contract) {
+      missing.push(constraint.id);
+      if (options.missingSeverity) {
+        incomplete.push({
+          ruleId: constraint.id,
+          missing: ["contract"],
+          severity: options.missingSeverity,
+          message: `Constraint '${constraint.id}' has no contract`
+        });
+      }
+      continue;
+    }
+    const gaps = validateContract(contract, requiredFields, artifactIndex);
+    if (gaps.length > 0) {
+      incomplete.push({
+        ruleId: constraint.id,
+        missing: gaps,
+        severity: incompleteSeverity,
+        message: `Constraint '${constraint.id}' contract is incomplete: missing ${gaps.join(", ")}`
+      });
+    } else {
+      complete.push({ ruleId: constraint.id, contract });
+    }
+  }
+  const total = registry.getAllRules().length + registry.getAllConstraints().length;
+  return {
+    complete,
+    incomplete,
+    missing,
+    total,
+    timestamp: (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+function validateContract(contract, requiredFields, artifactIndex) {
+  const missing = [];
+  if (requiredFields.includes("behavior") && isFieldEmpty(contract.behavior)) {
+    missing.push("behavior");
+  }
+  if (requiredFields.includes("examples") && (!contract.examples || contract.examples.length === 0)) {
+    missing.push("examples");
+  }
+  if (requiredFields.includes("invariants") && (!contract.invariants || contract.invariants.length === 0)) {
+    missing.push("invariants");
+  }
+  if (artifactIndex?.tests && !artifactIndex.tests.has(contract.ruleId)) {
+    missing.push("tests");
+  }
+  if (artifactIndex?.spec && !artifactIndex.spec.has(contract.ruleId)) {
+    missing.push("spec");
+  }
+  return missing;
+}
+function isFieldEmpty(value) {
+  return !value || value.trim() === "";
+}
+function formatValidationReport(report) {
+  const lines = [];
+  lines.push("Contract Validation Report");
+  lines.push("=".repeat(50));
+  lines.push("");
+  lines.push(`Total: ${report.total}`);
+  lines.push(`Complete: ${report.complete.length}`);
+  lines.push(`Incomplete: ${report.incomplete.length}`);
+  lines.push(`Missing: ${report.missing.length}`);
+  lines.push("");
+  if (report.complete.length > 0) {
+    lines.push("\u2713 Complete Contracts:");
+    for (const { ruleId, contract } of report.complete) {
+      lines.push(`  \u2713 ${ruleId} (v${contract.version || "1.0.0"})`);
+    }
+    lines.push("");
+  }
+  if (report.incomplete.length > 0) {
+    lines.push("\u2717 Incomplete Contracts:");
+    for (const gap of report.incomplete) {
+      const icon = gap.severity === "error" ? "\u2717" : gap.severity === "warning" ? "\u26A0" : "\u2139";
+      lines.push(`  ${icon} ${gap.ruleId} - Missing: ${gap.missing.join(", ")}`);
+      if (gap.message) {
+        lines.push(`     ${gap.message}`);
+      }
+    }
+    lines.push("");
+  }
+  if (report.missing.length > 0) {
+    lines.push("\u2717 No Contract:");
+    for (const ruleId of report.missing) {
+      lines.push(`  \u2717 ${ruleId}`);
+    }
+    lines.push("");
+  }
+  lines.push(`Validated at: ${report.timestamp}`);
+  return lines.join("\n");
+}
+function formatValidationReportJSON(report) {
+  return JSON.stringify(report, null, 2);
+}
+function formatValidationReportSARIF(report) {
+  const results = report.incomplete.map((gap) => {
+    const primaryMissing = gap.missing.length > 0 ? gap.missing[0] : "contract";
+    return {
+      ruleId: `decision-ledger/${primaryMissing}`,
+      level: gap.severity === "error" ? "error" : gap.severity === "warning" ? "warning" : "note",
+      message: {
+        text: gap.message || `Missing: ${gap.missing.join(", ")}`
+      },
+      locations: [
+        {
+          physicalLocation: {
+            artifactLocation: {
+              uri: "registry"
+            },
+            region: {
+              startLine: 1
+            }
+          }
+        }
+      ],
+      properties: {
+        ruleId: gap.ruleId,
+        missing: gap.missing
+      }
+    };
+  });
+  const sarif = {
+    version: "2.1.0",
+    $schema: "https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/Schemata/sarif-schema-2.1.0.json",
+    runs: [
+      {
+        tool: {
+          driver: {
+            name: "Praxis Decision Ledger",
+            version: "1.0.0",
+            informationUri: "https://github.com/plures/praxis",
+            rules: [
+              {
+                id: "decision-ledger/contract",
+                shortDescription: {
+                  text: "Rule or constraint missing contract"
+                }
+              },
+              {
+                id: "decision-ledger/behavior",
+                shortDescription: {
+                  text: "Contract missing behavior description"
+                }
+              },
+              {
+                id: "decision-ledger/examples",
+                shortDescription: {
+                  text: "Contract missing examples"
+                }
+              },
+              {
+                id: "decision-ledger/invariants",
+                shortDescription: {
+                  text: "Contract missing invariants"
+                }
+              },
+              {
+                id: "decision-ledger/tests",
+                shortDescription: {
+                  text: "Contract missing tests"
+                }
+              },
+              {
+                id: "decision-ledger/spec",
+                shortDescription: {
+                  text: "Contract missing spec"
+                }
+              }
+            ]
+          }
+        },
+        results
+      }
+    ]
+  };
+  return JSON.stringify(sarif, null, 2);
+}
+
+// src/decision-ledger/ledger.ts
+var BehaviorLedger = class _BehaviorLedger {
+  entries = [];
+  entryMap = /* @__PURE__ */ new Map();
+  /**
+   * Append a new entry to the ledger.
+   *
+   * @param entry The entry to append
+   * @throws Error if entry ID already exists
+   */
+  append(entry) {
+    if (this.entryMap.has(entry.id)) {
+      throw new Error(`Ledger entry with ID '${entry.id}' already exists`);
+    }
+    if (entry.supersedes) {
+      const superseded = this.entryMap.get(entry.supersedes);
+      if (superseded && superseded.status === "active") {
+        const updatedEntry = {
+          ...superseded,
+          status: "superseded"
+        };
+        this.entryMap.set(entry.supersedes, updatedEntry);
+      }
+    }
+    this.entries.push(entry);
+    this.entryMap.set(entry.id, entry);
+  }
+  /**
+   * Get an entry by ID.
+   *
+   * @param id The entry ID
+   * @returns The entry, or undefined if not found
+   */
+  getEntry(id) {
+    return this.entryMap.get(id);
+  }
+  /**
+   * Get all entries (in order of append) with current status.
+   *
+   * @returns Array of all entries with current status from the map
+   */
+  getAllEntries() {
+    return this.entries.map((entry) => this.entryMap.get(entry.id));
+  }
+  /**
+   * Get entries for a specific rule ID.
+   *
+   * @param ruleId The rule ID
+   * @returns Array of entries for this rule with current status
+   */
+  getEntriesForRule(ruleId) {
+    return this.entries.map((entry) => this.entryMap.get(entry.id)).filter((entry) => entry.contract.ruleId === ruleId);
+  }
+  /**
+   * Get the latest active entry for a rule.
+   *
+   * @param ruleId The rule ID
+   * @returns The latest active entry, or undefined if none
+   */
+  getLatestEntry(ruleId) {
+    const entries = this.getEntriesForRule(ruleId);
+    const activeEntries = entries.filter((entry) => entry.status === "active");
+    if (activeEntries.length === 0) {
+      return void 0;
+    }
+    return activeEntries[activeEntries.length - 1];
+  }
+  /**
+   * Get all active assumptions across all entries.
+   *
+   * @returns Map of assumption ID to assumption
+   */
+  getActiveAssumptions() {
+    const assumptions = /* @__PURE__ */ new Map();
+    for (const entry of this.entries) {
+      const currentEntry = this.entryMap.get(entry.id);
+      if (currentEntry.status !== "active") {
+        continue;
+      }
+      for (const assumption of currentEntry.contract.assumptions || []) {
+        if (assumption.status === "active") {
+          assumptions.set(assumption.id, assumption);
+        }
+      }
+    }
+    return assumptions;
+  }
+  /**
+   * Find assumptions that impact a specific artifact type.
+   *
+   * @param impactType The artifact type ('spec', 'tests', 'code')
+   * @returns Array of assumptions
+   */
+  findAssumptionsByImpact(impactType) {
+    const assumptions = [];
+    for (const entry of this.entries) {
+      const currentEntry = this.entryMap.get(entry.id);
+      if (currentEntry.status !== "active") {
+        continue;
+      }
+      for (const assumption of currentEntry.contract.assumptions || []) {
+        if (assumption.status === "active" && assumption.impacts.includes(impactType)) {
+          assumptions.push(assumption);
+        }
+      }
+    }
+    return assumptions;
+  }
+  /**
+   * Get ledger statistics.
+   */
+  getStats() {
+    const currentEntries = this.entries.map((e) => this.entryMap.get(e.id));
+    const active = currentEntries.filter((e) => e.status === "active").length;
+    const superseded = currentEntries.filter((e) => e.status === "superseded").length;
+    const deprecated = currentEntries.filter((e) => e.status === "deprecated").length;
+    const uniqueRules = new Set(currentEntries.map((e) => e.contract.ruleId)).size;
+    return {
+      totalEntries: this.entries.length,
+      activeEntries: active,
+      supersededEntries: superseded,
+      deprecatedEntries: deprecated,
+      uniqueRules
+    };
+  }
+  /**
+   * Export ledger as JSON.
+   *
+   * @returns JSON string with current entry status
+   */
+  toJSON() {
+    return JSON.stringify(
+      {
+        version: "1.0.0",
+        // Export entries with current status from the map
+        entries: this.entries.map((entry) => this.entryMap.get(entry.id)),
+        stats: this.getStats()
+      },
+      null,
+      2
+    );
+  }
+  /**
+   * Import ledger from JSON.
+   * 
+   * Note: The JSON must contain entries in the order they were originally appended.
+   * If a superseding entry appears before the entry it supersedes, the superseding
+   * logic will not work correctly. The toJSON method preserves this order.
+   *
+   * @param json The JSON string
+   * @returns A new BehaviorLedger instance
+   */
+  static fromJSON(json) {
+    const data = JSON.parse(json);
+    const ledger = new _BehaviorLedger();
+    for (const entry of data.entries || []) {
+      ledger.append(entry);
+    }
+    return ledger;
+  }
+};
+function createBehaviorLedger() {
+  return new BehaviorLedger();
+}
+
+// src/decision-ledger/analyzer.ts
+function analyzeDependencyGraph(registry) {
+  const facts = /* @__PURE__ */ new Map();
+  const edges = [];
+  const producers = /* @__PURE__ */ new Map();
+  const consumers = /* @__PURE__ */ new Map();
+  const rules = registry.getAllRules();
+  for (const rule of rules) {
+    const ruleId = rule.id;
+    const produced = [];
+    const consumed = [];
+    const probeFacts = probeRuleExecution(rule);
+    for (const tag of probeFacts.produced) {
+      produced.push(tag);
+    }
+    for (const tag of probeFacts.consumed) {
+      consumed.push(tag);
+    }
+    if (rule.contract) {
+      for (const example of rule.contract.examples) {
+        const thenTags = extractFactTagsFromText(example.then);
+        for (const tag of thenTags) {
+          if (!produced.includes(tag)) produced.push(tag);
+        }
+        const givenTags = extractFactTagsFromText(example.given);
+        for (const tag of givenTags) {
+          if (!consumed.includes(tag)) consumed.push(tag);
+        }
+      }
+    }
+    producers.set(ruleId, produced);
+    consumers.set(ruleId, consumed);
+    for (const tag of produced) {
+      const node = getOrCreateFactNode(facts, tag);
+      if (!node.producedBy.includes(ruleId)) {
+        node.producedBy.push(ruleId);
+      }
+      edges.push({ from: ruleId, to: tag, type: "produces" });
+    }
+    for (const tag of consumed) {
+      const node = getOrCreateFactNode(facts, tag);
+      if (!node.consumedBy.includes(ruleId)) {
+        node.consumedBy.push(ruleId);
+      }
+      edges.push({ from: tag, to: ruleId, type: "consumes" });
+    }
+  }
+  return { facts, edges, producers, consumers };
+}
+function findDeadRules(registry, knownEventTypes) {
+  const dead = [];
+  const known = new Set(knownEventTypes);
+  const rules = registry.getAllRules();
+  for (const rule of rules) {
+    if (!rule.eventTypes) continue;
+    const required = Array.isArray(rule.eventTypes) ? rule.eventTypes : [rule.eventTypes];
+    const hasMatch = required.some((t) => known.has(t));
+    if (!hasMatch) {
+      dead.push({
+        ruleId: rule.id,
+        description: rule.description,
+        requiredEventTypes: required,
+        reason: `Rule requires event types [${required.join(", ")}] but none are in the known event types [${knownEventTypes.join(", ")}]`
+      });
+    }
+  }
+  return dead;
+}
+function findUnreachableStates(registry) {
+  const graph = analyzeDependencyGraph(registry);
+  const unreachable = [];
+  for (const [tag, node] of graph.facts) {
+    if (node.producedBy.length === 0 && node.consumedBy.length > 0) {
+      unreachable.push({
+        factTags: [tag],
+        reason: `Fact "${tag}" is consumed by rules [${node.consumedBy.join(", ")}] but never produced by any rule`
+      });
+    }
+  }
+  const allProducedTags = Array.from(graph.facts.keys()).filter(
+    (tag) => graph.facts.get(tag).producedBy.length > 0
+  );
+  for (let i = 0; i < allProducedTags.length; i++) {
+    for (let j = i + 1; j < allProducedTags.length; j++) {
+      const tagA = allProducedTags[i];
+      const tagB = allProducedTags[j];
+      const producersA = graph.facts.get(tagA).producedBy;
+      const producersB = graph.facts.get(tagB).producedBy;
+      const sharedProducer = producersA.find((p) => producersB.includes(p));
+      if (sharedProducer) continue;
+      const rules = registry.getAllRules();
+      const getEventTypes = (ruleId) => {
+        const rule = rules.find((r) => r.id === ruleId);
+        if (!rule?.eventTypes) return [];
+        return Array.isArray(rule.eventTypes) ? rule.eventTypes : [rule.eventTypes];
+      };
+      const eventTypesA = new Set(producersA.flatMap(getEventTypes));
+      const eventTypesB = new Set(producersB.flatMap(getEventTypes));
+      if (eventTypesA.size > 0 && eventTypesB.size > 0 && ![...eventTypesA].some((t) => eventTypesB.has(t))) {
+        const consumersA = graph.facts.get(tagA).consumedBy;
+        const consumersB = graph.facts.get(tagB).consumedBy;
+        const sharedConsumer = consumersA.find((c) => consumersB.includes(c));
+        if (sharedConsumer) {
+          unreachable.push({
+            factTags: [tagA, tagB],
+            reason: `Facts "${tagA}" and "${tagB}" are both consumed by rule "${sharedConsumer}" but are produced by rules with non-overlapping event types`
+          });
+        }
+      }
+    }
+  }
+  return unreachable;
+}
+function findShadowedRules(registry) {
+  const shadowed = [];
+  const graph = analyzeDependencyGraph(registry);
+  const rules = registry.getAllRules();
+  for (let i = 0; i < rules.length; i++) {
+    for (let j = 0; j < rules.length; j++) {
+      if (i === j) continue;
+      const ruleA = rules[i];
+      const ruleB = rules[j];
+      const typesA = normalizeEventTypes(ruleA.eventTypes);
+      const typesB = normalizeEventTypes(ruleB.eventTypes);
+      if (typesA.length === 0 || typesB.length === 0) continue;
+      const shared = typesA.filter((t) => typesB.includes(t));
+      if (shared.length === 0) continue;
+      const producedA = graph.producers.get(ruleA.id) ?? [];
+      const producedB = graph.producers.get(ruleB.id) ?? [];
+      if (producedA.length === 0) continue;
+      const isSuperset = producedA.every((tag) => producedB.includes(tag));
+      const isProperSuperset = isSuperset && producedB.length > producedA.length;
+      if (isProperSuperset) {
+        shadowed.push({
+          ruleId: ruleA.id,
+          shadowedBy: ruleB.id,
+          sharedEventTypes: shared,
+          reason: `Rule "${ruleB.id}" produces a superset of facts [${producedB.join(", ")}] compared to "${ruleA.id}" [${producedA.join(", ")}] for the same event types [${shared.join(", ")}]`
+        });
+      }
+    }
+  }
+  return shadowed;
+}
+function findContradictions(registry) {
+  const contradictions = [];
+  const graph = analyzeDependencyGraph(registry);
+  const rules = registry.getAllRules();
+  for (const [tag, node] of graph.facts) {
+    if (node.producedBy.length < 2) continue;
+    for (let i = 0; i < node.producedBy.length; i++) {
+      for (let j = i + 1; j < node.producedBy.length; j++) {
+        const ruleIdA = node.producedBy[i];
+        const ruleIdB = node.producedBy[j];
+        const ruleA = rules.find((r) => r.id === ruleIdA);
+        const ruleB = rules.find((r) => r.id === ruleIdB);
+        if (!ruleA || !ruleB) continue;
+        const typesA = normalizeEventTypes(ruleA.eventTypes);
+        const typesB = normalizeEventTypes(ruleB.eventTypes);
+        const bothCatchAll = typesA.length === 0 && typesB.length === 0;
+        const sharedTypes = typesA.filter((t) => typesB.includes(t));
+        const hasOverlap = sharedTypes.length > 0;
+        if (bothCatchAll || hasOverlap) {
+          const conflictDetail = checkContractConflict(ruleA, ruleB, tag);
+          if (conflictDetail || bothCatchAll || hasOverlap) {
+            contradictions.push({
+              ruleA: ruleIdA,
+              ruleB: ruleIdB,
+              conflictingTag: tag,
+              reason: conflictDetail ?? `Rules "${ruleIdA}" and "${ruleIdB}" both produce fact "${tag}" and respond to ${bothCatchAll ? "all events" : `event types [${sharedTypes.join(", ")}]`}`
+            });
+          }
+        }
+      }
+    }
+  }
+  return contradictions;
+}
+function findGaps(registry, expectations) {
+  const gaps = [];
+  const rules = registry.getAllRules();
+  const constraints = registry.getAllConstraints();
+  for (const exp of expectations.expectations) {
+    const nameLower = exp.name.toLowerCase();
+    const nameParts = nameLower.split(/[-_./\s]+/);
+    const related = rules.filter((r) => {
+      const idLower = r.id.toLowerCase();
+      const descLower = r.description.toLowerCase();
+      const behaviorLower = r.contract?.behavior?.toLowerCase() ?? "";
+      if (idLower.includes(nameLower) || nameLower.includes(idLower)) return true;
+      if (descLower.includes(nameLower) || behaviorLower.includes(nameLower)) return true;
+      const minParts = Math.min(2, nameParts.length);
+      const matches = nameParts.filter(
+        (part) => part.length > 2 && (idLower.includes(part) || descLower.includes(part))
+      );
+      return matches.length >= minParts;
+    });
+    const relatedConstraints = constraints.filter((c) => {
+      const idLower = c.id.toLowerCase();
+      const descLower = c.description.toLowerCase();
+      return idLower.includes(nameLower) || nameLower.includes(idLower) || descLower.includes(nameLower);
+    });
+    if (related.length === 0 && relatedConstraints.length === 0) {
+      gaps.push({
+        expectationName: exp.name,
+        description: `No rules or constraints found for expectation "${exp.name}"`,
+        partialCoverage: [],
+        type: "no-rule"
+      });
+      continue;
+    }
+    const uncoveredConditions = exp.conditions.filter((cond) => {
+      const condLower = cond.description.toLowerCase();
+      return !related.some(
+        (r) => r.contract?.examples.some(
+          (ex) => ex.given.toLowerCase().includes(condLower) || ex.when.toLowerCase().includes(condLower) || ex.then.toLowerCase().includes(condLower) || condLower.includes(ex.given.toLowerCase()) || condLower.includes(ex.when.toLowerCase())
+        ) || r.contract?.invariants.some(
+          (inv) => inv.toLowerCase().includes(condLower) || condLower.includes(inv.toLowerCase())
+        ) || r.contract?.behavior.toLowerCase().includes(condLower) || r.description.toLowerCase().includes(condLower)
+      );
+    });
+    if (uncoveredConditions.length > 0 && uncoveredConditions.length < exp.conditions.length) {
+      gaps.push({
+        expectationName: exp.name,
+        description: `Expectation "${exp.name}" is partially covered. Uncovered conditions: ${uncoveredConditions.map((c) => c.description).join("; ")}`,
+        partialCoverage: related.map((r) => r.id),
+        type: "partial-coverage"
+      });
+    } else if (uncoveredConditions.length === exp.conditions.length && exp.conditions.length > 0) {
+      const rulesWithoutContracts = related.filter((r) => !r.contract);
+      if (rulesWithoutContracts.length > 0) {
+        gaps.push({
+          expectationName: exp.name,
+          description: `Rules related to "${exp.name}" lack contracts: [${rulesWithoutContracts.map((r) => r.id).join(", ")}]`,
+          partialCoverage: related.map((r) => r.id),
+          type: "no-contract"
+        });
+      }
+    }
+  }
+  return gaps;
+}
+function getOrCreateFactNode(facts, tag) {
+  let node = facts.get(tag);
+  if (!node) {
+    node = { tag, producedBy: [], consumedBy: [] };
+    facts.set(tag, node);
+  }
+  return node;
+}
+function normalizeEventTypes(eventTypes) {
+  if (!eventTypes) return [];
+  return Array.isArray(eventTypes) ? eventTypes : [eventTypes];
+}
+function probeRuleExecution(rule) {
+  const produced = [];
+  const consumed = [];
+  const eventTypes = normalizeEventTypes(rule.eventTypes);
+  const syntheticEvents = eventTypes.length > 0 ? eventTypes.map((tag) => ({ tag, payload: {} })) : [{ tag: "__probe__", payload: {} }];
+  const syntheticState = {
+    context: {},
+    facts: [],
+    events: syntheticEvents,
+    meta: {},
+    protocolVersion: "1.0.0"
+  };
+  try {
+    const result = rule.impl(syntheticState, syntheticEvents);
+    if (result instanceof RuleResult) {
+      if (result.kind === "emit") {
+        for (const fact of result.facts) {
+          if (!produced.includes(fact.tag)) {
+            produced.push(fact.tag);
+          }
+        }
+      } else if (result.kind === "retract") {
+        for (const tag of result.retractTags) {
+          if (!consumed.includes(tag)) {
+            consumed.push(tag);
+          }
+        }
+      }
+    } else if (Array.isArray(result)) {
+      for (const fact of result) {
+        if (fact.tag && !produced.includes(fact.tag)) {
+          produced.push(fact.tag);
+        }
+      }
+    }
+  } catch {
+  }
+  return { produced, consumed };
+}
+function extractFactTagsFromText(text) {
+  const tags = [];
+  const patterns = [
+    /(?:emit|produce|retract|read|consume|fact)\s+['"]?([a-zA-Z][a-zA-Z0-9._-]+)['"]?/gi,
+    /['"]([a-zA-Z][a-zA-Z0-9._-]*\.[a-zA-Z][a-zA-Z0-9._-]*)['"]?/g
+  ];
+  for (const pattern of patterns) {
+    let match;
+    while ((match = pattern.exec(text)) !== null) {
+      const tag = match[1];
+      if (tag && !tags.includes(tag)) {
+        tags.push(tag);
+      }
+    }
+  }
+  return tags;
+}
+function checkContractConflict(ruleA, ruleB, _factTag) {
+  if (!ruleA.contract || !ruleB.contract) return null;
+  for (const exA of ruleA.contract.examples) {
+    for (const exB of ruleB.contract.examples) {
+      const sameGiven = exA.given.toLowerCase() === exB.given.toLowerCase();
+      const sameWhen = exA.when.toLowerCase() === exB.when.toLowerCase();
+      const differentThen = exA.then.toLowerCase() !== exB.then.toLowerCase();
+      if ((sameGiven || sameWhen) && differentThen) {
+        return `Contract conflict: "${ruleA.id}" expects "${exA.then}" but "${ruleB.id}" expects "${exB.then}" under similar conditions`;
+      }
+    }
+  }
+  return null;
+}
+
+// src/decision-ledger/derivation.ts
+function traceDerivation(factTag, _engine, registry) {
+  const graph = analyzeDependencyGraph(registry);
+  const steps = [];
+  const visited = /* @__PURE__ */ new Set();
+  function walkBackward(tag, depth) {
+    if (visited.has(tag) || depth > 20) return;
+    visited.add(tag);
+    const factNode = graph.facts.get(tag);
+    if (!factNode) {
+      steps.unshift({
+        type: "fact-produced",
+        id: tag,
+        description: `Fact "${tag}" (origin unknown \u2014 not in dependency graph)`
+      });
+      return;
+    }
+    steps.unshift({
+      type: "fact-produced",
+      id: tag,
+      description: `Fact "${tag}" produced`
+    });
+    for (const ruleId of factNode.producedBy) {
+      if (visited.has(ruleId)) continue;
+      visited.add(ruleId);
+      const rule = registry.getRule(ruleId);
+      steps.unshift({
+        type: "rule-fired",
+        id: ruleId,
+        description: `Rule "${ruleId}" fired${rule ? `: ${rule.description}` : ""}`
+      });
+      const consumed = graph.consumers.get(ruleId) ?? [];
+      for (const consumedTag of consumed) {
+        steps.unshift({
+          type: "fact-read",
+          id: consumedTag,
+          description: `Rule "${ruleId}" reads fact "${consumedTag}"`
+        });
+        walkBackward(consumedTag, depth + 1);
+      }
+      if (rule?.eventTypes) {
+        const types = Array.isArray(rule.eventTypes) ? rule.eventTypes : [rule.eventTypes];
+        for (const eventType of types) {
+          steps.unshift({
+            type: "event",
+            id: eventType,
+            description: `Event "${eventType}" triggers rule "${ruleId}"`
+          });
+        }
+      }
+    }
+  }
+  walkBackward(factTag, 0);
+  const seen = /* @__PURE__ */ new Set();
+  const dedupedSteps = steps.filter((step) => {
+    const key = `${step.type}:${step.id}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+  return {
+    targetFact: factTag,
+    steps: dedupedSteps,
+    depth: dedupedSteps.filter((s) => s.type === "rule-fired").length
+  };
+}
+function traceImpact(factTag, registry) {
+  const graph = analyzeDependencyGraph(registry);
+  const affectedRules = [];
+  const affectedFacts = [];
+  const visited = /* @__PURE__ */ new Set();
+  function walkForward(tag, depth2) {
+    if (visited.has(tag) || depth2 > 20) return depth2;
+    visited.add(tag);
+    const factNode = graph.facts.get(tag);
+    if (!factNode) return depth2;
+    let maxDepth = depth2;
+    for (const ruleId of factNode.consumedBy) {
+      if (!affectedRules.includes(ruleId)) {
+        affectedRules.push(ruleId);
+      }
+      const produced = graph.producers.get(ruleId) ?? [];
+      for (const producedTag of produced) {
+        if (producedTag !== factTag && !affectedFacts.includes(producedTag)) {
+          affectedFacts.push(producedTag);
+          const childDepth = walkForward(producedTag, depth2 + 1);
+          if (childDepth > maxDepth) maxDepth = childDepth;
+        }
+      }
+    }
+    return maxDepth;
+  }
+  const depth = walkForward(factTag, 0);
+  return {
+    factTag,
+    affectedRules,
+    affectedFacts,
+    depth
+  };
+}
+
+// src/decision-ledger/contract-verification.ts
+function verifyContractExamples(rule, contract) {
+  const examples = [];
+  for (let i = 0; i < contract.examples.length; i++) {
+    const example = contract.examples[i];
+    try {
+      const state = buildStateFromDescription(example.given);
+      const events = buildEventsFromDescription(example.when, rule.eventTypes);
+      const stateWithEvents = { ...state, events };
+      const result = rule.impl(stateWithEvents, events);
+      const verification = verifyOutput(result, example.then, rule.id);
+      examples.push({
+        index: i,
+        given: example.given,
+        when: example.when,
+        expectedThen: example.then,
+        passed: verification.passed,
+        actualOutput: verification.actualOutput,
+        error: verification.error
+      });
+    } catch (error) {
+      examples.push({
+        index: i,
+        given: example.given,
+        when: example.when,
+        expectedThen: example.then,
+        passed: false,
+        error: `Execution error: ${error instanceof Error ? error.message : String(error)}`
+      });
+    }
+  }
+  const passCount = examples.filter((e) => e.passed).length;
+  const failCount = examples.filter((e) => !e.passed).length;
+  return {
+    ruleId: rule.id,
+    examples,
+    allPassed: failCount === 0,
+    passCount,
+    failCount
+  };
+}
+function verifyInvariants(registry) {
+  const checks = [];
+  const rules = registry.getAllRules();
+  for (const rule of rules) {
+    if (!rule.contract) continue;
+    for (const invariant of rule.contract.invariants) {
+      const consistent = rule.contract.examples.every((example) => {
+        return isConsistentWithInvariant(example, invariant);
+      });
+      checks.push({
+        invariant,
+        ruleId: rule.id,
+        holds: consistent,
+        explanation: consistent ? `Invariant "${invariant}" is consistent with all ${rule.contract.examples.length} examples` : `Invariant "${invariant}" may be violated by one or more examples`
+      });
+    }
+  }
+  return checks;
+}
+function findContractGaps(registry) {
+  const gaps = [];
+  const rules = registry.getAllRules();
+  for (const rule of rules) {
+    if (!rule.contract) continue;
+    const examples = rule.contract.examples;
+    const hasErrorExamples = examples.some(
+      (ex) => ex.then.toLowerCase().includes("error") || ex.then.toLowerCase().includes("fail") || ex.then.toLowerCase().includes("skip") || ex.then.toLowerCase().includes("noop") || ex.then.toLowerCase().includes("retract") || ex.then.toLowerCase().includes("violation")
+    );
+    if (!hasErrorExamples && examples.length > 0) {
+      gaps.push({
+        ruleId: rule.id,
+        description: `No error/failure path examples. All ${examples.length} examples show happy paths`,
+        type: "missing-error-path"
+      });
+    }
+    if (rule.eventTypes) {
+      const eventTypes = Array.isArray(rule.eventTypes) ? rule.eventTypes : [rule.eventTypes];
+      if (eventTypes.length > 1) {
+        const coveredTypes = /* @__PURE__ */ new Set();
+        for (const ex of examples) {
+          for (const et of eventTypes) {
+            if (ex.when.toLowerCase().includes(et.toLowerCase()) || ex.when.toLowerCase().includes(et.replace(".", " ").toLowerCase())) {
+              coveredTypes.add(et);
+            }
+          }
+        }
+        const uncovered = eventTypes.filter((et) => !coveredTypes.has(et));
+        if (uncovered.length > 0) {
+          gaps.push({
+            ruleId: rule.id,
+            description: `Event types [${uncovered.join(", ")}] not covered by any example`,
+            type: "missing-edge-case"
+          });
+        }
+      }
+    }
+    if (examples.length === 1) {
+      gaps.push({
+        ruleId: rule.id,
+        description: `Only 1 contract example \u2014 likely missing boundary conditions and edge cases`,
+        type: "missing-boundary"
+      });
+    }
+  }
+  return gaps;
+}
+function crossReferenceContracts(registry) {
+  const graph = analyzeDependencyGraph(registry);
+  const references = [];
+  const rules = registry.getAllRules();
+  for (const rule of rules) {
+    if (!rule.contract) continue;
+    for (const example of rule.contract.examples) {
+      const referencedTags = extractReferencedFactTags(example.given + " " + example.when);
+      for (const tag of referencedTags) {
+        const factNode = graph.facts.get(tag);
+        const producerRuleId = factNode?.producedBy[0] ?? null;
+        const valid = factNode ? factNode.producedBy.length > 0 : false;
+        if (producerRuleId === rule.id) continue;
+        references.push({
+          sourceRuleId: rule.id,
+          referencedFactTag: tag,
+          producerRuleId,
+          valid
+        });
+      }
+    }
+  }
+  return references;
+}
+function buildStateFromDescription(given) {
+  const context = {};
+  const facts = [];
+  const factPattern = /fact\s+['"]([^'"]+)['"]/gi;
+  let match;
+  while ((match = factPattern.exec(given)) !== null) {
+    facts.push({ tag: match[1], payload: {} });
+  }
+  const dottedPattern = /['"]([a-zA-Z][a-zA-Z0-9]*\.[a-zA-Z][a-zA-Z0-9.]*)['"]/g;
+  while ((match = dottedPattern.exec(given)) !== null) {
+    const tag = match[1];
+    if (!facts.some((f) => f.tag === tag)) {
+      facts.push({ tag, payload: {} });
+    }
+  }
+  return {
+    context,
+    facts,
+    meta: {},
+    protocolVersion: "1.0.0"
+  };
+}
+function buildEventsFromDescription(when, eventTypes) {
+  const events = [];
+  if (eventTypes) {
+    const types = Array.isArray(eventTypes) ? eventTypes : [eventTypes];
+    for (const type of types) {
+      if (when.toLowerCase().includes(type.toLowerCase()) || when.toLowerCase().includes(type.replace(".", " ").toLowerCase())) {
+        events.push({ tag: type, payload: {} });
+      }
+    }
+  }
+  if (events.length === 0) {
+    const eventPattern = /['"]([A-Z][A-Z0-9._-]+)['"]/g;
+    let match;
+    while ((match = eventPattern.exec(when)) !== null) {
+      events.push({ tag: match[1], payload: {} });
+    }
+  }
+  if (events.length === 0) {
+    const types = eventTypes ? Array.isArray(eventTypes) ? eventTypes : [eventTypes] : ["__test__"];
+    events.push({ tag: types[0], payload: {} });
+  }
+  return events;
+}
+function verifyOutput(result, expectedThen, ruleId) {
+  const thenLower = expectedThen.toLowerCase();
+  if (result instanceof RuleResult) {
+    switch (result.kind) {
+      case "emit": {
+        const factTags = result.facts.map((f) => f.tag);
+        const actualOutput = `Emitted: [${factTags.join(", ")}]`;
+        const emitExpected = thenLower.includes("emit") || thenLower.includes("produce") || thenLower.includes("fact");
+        if (emitExpected) {
+          const expectedTags = extractReferencedFactTags(expectedThen);
+          if (expectedTags.length > 0) {
+            const allFound = expectedTags.every(
+              (tag) => factTags.some((ft) => ft.toLowerCase() === tag.toLowerCase())
+            );
+            return { passed: allFound, actualOutput };
+          }
+          return { passed: true, actualOutput };
+        }
+        return { passed: true, actualOutput };
+      }
+      case "noop": {
+        const expectNoop = thenLower.includes("noop") || thenLower.includes("nothing") || thenLower.includes("no fact") || thenLower.includes("skip");
+        return {
+          passed: expectNoop,
+          actualOutput: `Noop: ${result.reason ?? "no reason"}`
+        };
+      }
+      case "skip": {
+        const expectSkip = thenLower.includes("skip") || thenLower.includes("noop") || thenLower.includes("not fire") || thenLower.includes("nothing");
+        return {
+          passed: expectSkip,
+          actualOutput: `Skip: ${result.reason ?? "no reason"}`
+        };
+      }
+      case "retract": {
+        const expectRetract = thenLower.includes("retract") || thenLower.includes("remove") || thenLower.includes("clear");
+        return {
+          passed: expectRetract,
+          actualOutput: `Retract: [${result.retractTags.join(", ")}]`
+        };
+      }
+    }
+  } else if (Array.isArray(result)) {
+    const factTags = result.map((f) => f.tag);
+    const actualOutput = `Facts: [${factTags.join(", ")}]`;
+    return { passed: factTags.length > 0 || thenLower.includes("nothing"), actualOutput };
+  }
+  return { passed: false, error: `Unexpected result type from rule "${ruleId}"` };
+}
+function isConsistentWithInvariant(example, invariant) {
+  const invLower = invariant.toLowerCase();
+  const thenLower = example.then.toLowerCase();
+  if (invLower.includes("must not") || invLower.includes("never")) {
+    const keyword = invLower.replace(/must not|never|should not/g, "").trim().split(/\s+/)[0];
+    if (keyword && thenLower.includes(keyword)) {
+      return false;
+    }
+  }
+  if (invLower.includes("must ") && !invLower.includes("must not")) {
+    const mustPart = invLower.split("must ")[1]?.split(/[.,;]/)[0]?.trim();
+    if (mustPart) {
+      const negations = ["no ", "not ", "never ", "without "];
+      for (const neg of negations) {
+        if (thenLower.includes(neg + mustPart.split(/\s+/)[0])) {
+          return false;
+        }
+      }
+    }
+  }
+  return true;
+}
+function extractReferencedFactTags(text) {
+  const tags = [];
+  const patterns = [
+    /['"]([a-zA-Z][a-zA-Z0-9]*\.[a-zA-Z][a-zA-Z0-9.]*)['"]/g,
+    /fact\s+['"]?([a-zA-Z][a-zA-Z0-9._-]+)['"]?/gi,
+    /(?:emit|produce|retract)\s+['"]?([a-zA-Z][a-zA-Z0-9._-]+)['"]?/gi
+  ];
+  for (const pattern of patterns) {
+    let match;
+    while ((match = pattern.exec(text)) !== null) {
+      const tag = match[1];
+      if (tag && !tags.includes(tag)) {
+        tags.push(tag);
+      }
+    }
+  }
+  return tags;
+}
+
+// src/decision-ledger/suggestions.ts
+function suggest(finding, type) {
+  switch (type) {
+    case "dead-rule":
+      return suggestForDeadRule(finding);
+    case "gap":
+      return suggestForGap(finding);
+    case "contradiction":
+      return suggestForContradiction(finding);
+    case "unreachable-state":
+      return suggestForUnreachableState(finding);
+    case "shadowed-rule":
+      return suggestForShadowedRule(finding);
+    case "contract-gap":
+      return suggestForContractGap(finding);
+    default:
+      return {
+        findingType: type,
+        entityId: "unknown",
+        message: "Unknown finding type",
+        action: "modify",
+        priority: 1
+      };
+  }
+}
+function suggestAll(findings) {
+  const suggestions = [];
+  if (findings.deadRules) {
+    for (const f of findings.deadRules) {
+      suggestions.push(suggestForDeadRule(f));
+    }
+  }
+  if (findings.gaps) {
+    for (const f of findings.gaps) {
+      suggestions.push(suggestForGap(f));
+    }
+  }
+  if (findings.contradictions) {
+    for (const f of findings.contradictions) {
+      suggestions.push(suggestForContradiction(f));
+    }
+  }
+  if (findings.unreachableStates) {
+    for (const f of findings.unreachableStates) {
+      suggestions.push(suggestForUnreachableState(f));
+    }
+  }
+  if (findings.shadowedRules) {
+    for (const f of findings.shadowedRules) {
+      suggestions.push(suggestForShadowedRule(f));
+    }
+  }
+  if (findings.contractGaps) {
+    for (const f of findings.contractGaps) {
+      suggestions.push(suggestForContractGap(f));
+    }
+  }
+  suggestions.sort((a, b) => b.priority - a.priority);
+  return suggestions;
+}
+function suggestForDeadRule(finding) {
+  const eventList = finding.requiredEventTypes.join(", ");
+  return {
+    findingType: "dead-rule",
+    entityId: finding.ruleId,
+    message: `Remove rule "${finding.ruleId}" or add event type "${finding.requiredEventTypes[0]}" to your event sources. Rule requires [${eventList}] but none are emitted by the application.`,
+    action: finding.requiredEventTypes.length === 1 ? "add-event-type" : "remove",
+    priority: 5,
+    skeleton: `// Option 1: Remove the dead rule
+registry.removeRule('${finding.ruleId}');
+
+// Option 2: Add the missing event type
+engine.step([{ tag: '${finding.requiredEventTypes[0]}', payload: {} }]);`
+  };
+}
+function suggestForGap(finding) {
+  const ruleId = finding.expectationName.toLowerCase().replace(/\s+/g, "-").replace(/[^a-z0-9-]/g, "");
+  switch (finding.type) {
+    case "no-rule":
+      return {
+        findingType: "gap",
+        entityId: finding.expectationName,
+        message: `Add a rule covering: "${finding.expectationName}". No rules or constraints address this expected behavior.`,
+        action: "add-rule",
+        priority: 8,
+        skeleton: `defineRule({
+  id: '${ruleId}',
+  description: '${finding.description}',
+  eventTypes: ['TODO_EVENT_TYPE'],
+  impl: (state, events) => {
+    // TODO: Implement logic for "${finding.expectationName}"
+    return RuleResult.noop('Not implemented');
+  },
+  contract: defineContract({
+    ruleId: '${ruleId}',
+    behavior: '${finding.expectationName}',
+    examples: [
+      { given: 'TODO', when: 'TODO', then: 'TODO' },
+    ],
+    invariants: [],
+  }),
+});`
+      };
+    case "partial-coverage":
+      return {
+        findingType: "gap",
+        entityId: finding.expectationName,
+        message: `Expectation "${finding.expectationName}" is partially covered by rules [${finding.partialCoverage.join(", ")}]. Add contract examples or additional rules for uncovered conditions.`,
+        action: "modify",
+        priority: 6
+      };
+    case "no-contract":
+      return {
+        findingType: "gap",
+        entityId: finding.expectationName,
+        message: `Rules related to "${finding.expectationName}" ([${finding.partialCoverage.join(", ")}]) lack contracts. Add contracts with examples covering the expected behavior.`,
+        action: "add-contract",
+        priority: 7
+      };
+    default:
+      return {
+        findingType: "gap",
+        entityId: finding.expectationName,
+        message: finding.description,
+        action: "add-rule",
+        priority: 5
+      };
+  }
+}
+function suggestForContradiction(finding) {
+  return {
+    findingType: "contradiction",
+    entityId: `${finding.ruleA}\u2194${finding.ruleB}`,
+    message: `Rules "${finding.ruleA}" and "${finding.ruleB}" both produce fact "${finding.conflictingTag}" with potentially different payloads. Add priority ordering, merge the rules, or add distinguishing conditions.`,
+    action: "add-priority",
+    priority: 9,
+    skeleton: `// Option 1: Add priority via meta
+defineRule({
+  id: '${finding.ruleA}',
+  meta: { priority: 10 },  // Higher priority wins
+  // ...
+});
+
+// Option 2: Add distinguishing conditions
+defineRule({
+  id: '${finding.ruleA}',
+  impl: (state, events) => {
+    // Add condition to distinguish from "${finding.ruleB}"
+    if (/* specific condition */) {
+      return RuleResult.emit([{ tag: '${finding.conflictingTag}', payload: { /* ... */ } }]);
+    }
+    return RuleResult.skip('Deferred to ${finding.ruleB}');
+  },
+});`
+  };
+}
+function suggestForUnreachableState(finding) {
+  const tags = finding.factTags.join(", ");
+  return {
+    findingType: "unreachable-state",
+    entityId: finding.factTags.join("+"),
+    message: `No rule produces facts [${tags}] together. If this state combination is valid, add a composite rule that produces all required facts.`,
+    action: "add-rule",
+    priority: 4,
+    skeleton: `defineRule({
+  id: 'composite-${finding.factTags[0]?.replace(".", "-") ?? "unknown"}',
+  description: 'Produces facts [${tags}] together',
+  impl: (state, events) => {
+    return RuleResult.emit([
+${finding.factTags.map((t) => `      { tag: '${t}', payload: {} },`).join("\n")}
+    ]);
+  },
+});`
+  };
+}
+function suggestForShadowedRule(finding) {
+  return {
+    findingType: "shadowed-rule",
+    entityId: finding.ruleId,
+    message: `Rule "${finding.ruleId}" is always superseded by "${finding.shadowedBy}" for event types [${finding.sharedEventTypes.join(", ")}]. Consider merging the rules or adding a distinguishing condition to "${finding.ruleId}".`,
+    action: "merge",
+    priority: 3,
+    skeleton: `// Option 1: Remove the shadowed rule
+registry.removeRule('${finding.ruleId}');
+
+// Option 2: Add unique behavior to the shadowed rule
+defineRule({
+  id: '${finding.ruleId}',
+  impl: (state, events) => {
+    // Add condition that "${finding.shadowedBy}" doesn't cover
+    if (/* unique condition */) {
+      return RuleResult.emit([/* unique facts */]);
+    }
+    return RuleResult.skip('Handled by ${finding.shadowedBy}');
+  },
+});`
+  };
+}
+function suggestForContractGap(finding) {
+  let message;
+  let action = "add-contract";
+  let priority;
+  switch (finding.type) {
+    case "missing-error-path":
+      message = `Rule "${finding.ruleId}" has no error/failure examples in its contract. Add examples showing what happens when preconditions fail, inputs are invalid, or the rule needs to skip.`;
+      priority = 6;
+      break;
+    case "missing-edge-case":
+      message = `Rule "${finding.ruleId}": ${finding.description}. Add contract examples covering all declared event types.`;
+      priority = 5;
+      break;
+    case "missing-boundary":
+      message = `Rule "${finding.ruleId}" has only 1 contract example. Add boundary condition examples (empty input, maximum values, concurrent events).`;
+      priority = 4;
+      break;
+    case "cross-reference-broken":
+      message = `Rule "${finding.ruleId}": ${finding.description}. Verify the referenced fact producer exists.`;
+      action = "modify";
+      priority = 7;
+      break;
+    default:
+      message = finding.description;
+      priority = 3;
+  }
+  return {
+    findingType: "contract-gap",
+    entityId: finding.ruleId,
+    message,
+    action,
+    priority
+  };
+}
+
+// src/decision-ledger/report.ts
+function generateLedger(registry, engine, expectations) {
+  const allEventTypes = /* @__PURE__ */ new Set();
+  for (const rule of registry.getAllRules()) {
+    if (rule.eventTypes) {
+      const types = Array.isArray(rule.eventTypes) ? rule.eventTypes : [rule.eventTypes];
+      for (const t of types) allEventTypes.add(t);
+    }
+  }
+  const deadRules = findDeadRules(registry, [...allEventTypes]);
+  const unreachableStates = findUnreachableStates(registry);
+  const shadowedRules = findShadowedRules(registry);
+  const contradictions = findContradictions(registry);
+  const contractGaps = findContractGaps(registry);
+  const gaps = expectations ? findGaps(registry, expectations) : [];
+  const currentFacts = engine.getFacts();
+  const factDerivationChains = currentFacts.map(
+    (fact) => traceDerivation(fact.tag, engine, registry)
+  );
+  const suggestions = suggestAll({
+    deadRules,
+    gaps,
+    contradictions,
+    unreachableStates,
+    shadowedRules,
+    contractGaps
+  });
+  const totalRules = registry.getRuleIds().length;
+  const totalConstraints = registry.getConstraintIds().length;
+  const totalIssues = deadRules.length + unreachableStates.length + shadowedRules.length + contradictions.length + gaps.length;
+  const maxIssues = Math.max(totalRules + totalConstraints, 1);
+  const healthScore = Math.max(0, Math.round(100 - totalIssues / maxIssues * 100));
+  return {
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    factDerivationChains,
+    deadRules,
+    unreachableStates,
+    shadowedRules,
+    contradictions,
+    gaps,
+    suggestions,
+    summary: {
+      totalRules,
+      totalConstraints,
+      deadRuleCount: deadRules.length,
+      unreachableStateCount: unreachableStates.length,
+      shadowedRuleCount: shadowedRules.length,
+      contradictionCount: contradictions.length,
+      gapCount: gaps.length,
+      suggestionCount: suggestions.length,
+      healthScore
+    }
+  };
+}
+function formatLedger(report) {
+  const lines = [];
+  const icon = report.summary.healthScore >= 90 ? "\u2705" : report.summary.healthScore >= 70 ? "\u{1F7E1}" : "\u{1F534}";
+  lines.push(`# ${icon} Decision Ledger Analysis`);
+  lines.push("");
+  lines.push(`**Health Score:** ${report.summary.healthScore}/100`);
+  lines.push(`**Timestamp:** ${report.timestamp}`);
+  lines.push("");
+  lines.push("## Summary");
+  lines.push("");
+  lines.push(`| Metric | Count |`);
+  lines.push(`|--------|-------|`);
+  lines.push(`| Rules | ${report.summary.totalRules} |`);
+  lines.push(`| Constraints | ${report.summary.totalConstraints} |`);
+  lines.push(`| Dead Rules | ${report.summary.deadRuleCount} |`);
+  lines.push(`| Unreachable States | ${report.summary.unreachableStateCount} |`);
+  lines.push(`| Shadowed Rules | ${report.summary.shadowedRuleCount} |`);
+  lines.push(`| Contradictions | ${report.summary.contradictionCount} |`);
+  lines.push(`| Gaps | ${report.summary.gapCount} |`);
+  lines.push(`| Suggestions | ${report.summary.suggestionCount} |`);
+  lines.push("");
+  if (report.deadRules.length > 0) {
+    lines.push("## \u{1F480} Dead Rules");
+    lines.push("");
+    for (const dr of report.deadRules) {
+      lines.push(`- **${dr.ruleId}**: ${dr.reason}`);
+    }
+    lines.push("");
+  }
+  if (report.unreachableStates.length > 0) {
+    lines.push("## \u{1F6AB} Unreachable States");
+    lines.push("");
+    for (const us of report.unreachableStates) {
+      lines.push(`- **[${us.factTags.join(", ")}]**: ${us.reason}`);
+    }
+    lines.push("");
+  }
+  if (report.shadowedRules.length > 0) {
+    lines.push("## \u{1F47B} Shadowed Rules");
+    lines.push("");
+    for (const sr of report.shadowedRules) {
+      lines.push(`- **${sr.ruleId}** shadowed by **${sr.shadowedBy}**: ${sr.reason}`);
+    }
+    lines.push("");
+  }
+  if (report.contradictions.length > 0) {
+    lines.push("## \u26A1 Contradictions");
+    lines.push("");
+    for (const c of report.contradictions) {
+      lines.push(`- **${c.ruleA}** \u2194 **${c.ruleB}** on \`${c.conflictingTag}\`: ${c.reason}`);
+    }
+    lines.push("");
+  }
+  if (report.gaps.length > 0) {
+    lines.push("## \u{1F573}\uFE0F Gaps");
+    lines.push("");
+    for (const g of report.gaps) {
+      lines.push(`- **${g.expectationName}** (${g.type}): ${g.description}`);
+    }
+    lines.push("");
+  }
+  if (report.factDerivationChains.length > 0) {
+    lines.push("## \u{1F517} Fact Derivation Chains");
+    lines.push("");
+    for (const chain of report.factDerivationChains) {
+      if (chain.steps.length === 0) continue;
+      lines.push(`### \`${chain.targetFact}\` (depth: ${chain.depth})`);
+      for (const step of chain.steps) {
+        const icon2 = step.type === "event" ? "\u26A1" : step.type === "rule-fired" ? "\u2699\uFE0F" : step.type === "fact-produced" ? "\u{1F4E6}" : "\u{1F4D6}";
+        lines.push(`  ${icon2} ${step.description}`);
+      }
+      lines.push("");
+    }
+  }
+  if (report.suggestions.length > 0) {
+    lines.push("## \u{1F4A1} Suggestions");
+    lines.push("");
+    for (const s of report.suggestions) {
+      const priorityIcon = s.priority >= 8 ? "\u{1F534}" : s.priority >= 5 ? "\u{1F7E1}" : "\u{1F7E2}";
+      lines.push(`${priorityIcon} **[${s.findingType}]** ${s.message}`);
+      if (s.skeleton) {
+        lines.push("```typescript");
+        lines.push(s.skeleton);
+        lines.push("```");
+      }
+      lines.push("");
+    }
+  }
+  return lines.join("\n");
+}
+function formatBuildOutput(report) {
+  const lines = [];
+  lines.push(`::group::Decision Ledger Analysis (Score: ${report.summary.healthScore}/100)`);
+  for (const c of report.contradictions) {
+    lines.push(`::error title=Contradiction::Rules "${c.ruleA}" and "${c.ruleB}" both produce "${c.conflictingTag}"`);
+  }
+  for (const g of report.gaps) {
+    if (g.type === "no-rule") {
+      lines.push(`::error title=Missing Rule::No rule covers expectation "${g.expectationName}"`);
+    }
+  }
+  for (const dr of report.deadRules) {
+    lines.push(`::warning title=Dead Rule::Rule "${dr.ruleId}" can never fire (requires [${dr.requiredEventTypes.join(", ")}])`);
+  }
+  for (const sr of report.shadowedRules) {
+    lines.push(`::warning title=Shadowed Rule::Rule "${sr.ruleId}" is always superseded by "${sr.shadowedBy}"`);
+  }
+  for (const us of report.unreachableStates) {
+    lines.push(`::warning title=Unreachable State::Facts [${us.factTags.join(", ")}] cannot be produced together`);
+  }
+  for (const g of report.gaps) {
+    if (g.type === "partial-coverage") {
+      lines.push(`::warning title=Partial Coverage::Expectation "${g.expectationName}" is only partially covered`);
+    } else if (g.type === "no-contract") {
+      lines.push(`::warning title=Missing Contract::Rules for "${g.expectationName}" lack contracts`);
+    }
+  }
+  lines.push("");
+  lines.push(`Rules: ${report.summary.totalRules} | Constraints: ${report.summary.totalConstraints} | Health: ${report.summary.healthScore}/100`);
+  lines.push(`Dead: ${report.summary.deadRuleCount} | Unreachable: ${report.summary.unreachableStateCount} | Shadowed: ${report.summary.shadowedRuleCount} | Contradictions: ${report.summary.contradictionCount} | Gaps: ${report.summary.gapCount}`);
+  lines.push("::endgroup::");
+  return lines.join("\n");
+}
+function diffLedgers(before, after) {
+  const changes = [];
+  diffItems(
+    before.deadRules,
+    after.deadRules,
+    (dr) => dr.ruleId,
+    (dr) => `Dead rule: ${dr.ruleId} \u2014 ${dr.reason}`,
+    "dead-rule",
+    changes
+  );
+  diffItems(
+    before.unreachableStates,
+    after.unreachableStates,
+    (us) => us.factTags.join("+"),
+    (us) => `Unreachable state: [${us.factTags.join(", ")}]`,
+    "unreachable-state",
+    changes
+  );
+  diffItems(
+    before.shadowedRules,
+    after.shadowedRules,
+    (sr) => sr.ruleId,
+    (sr) => `Shadowed rule: ${sr.ruleId} by ${sr.shadowedBy}`,
+    "shadowed-rule",
+    changes
+  );
+  diffItems(
+    before.contradictions,
+    after.contradictions,
+    (c) => `${c.ruleA}\u2194${c.ruleB}`,
+    (c) => `Contradiction: ${c.ruleA} \u2194 ${c.ruleB} on ${c.conflictingTag}`,
+    "contradiction",
+    changes
+  );
+  diffItems(
+    before.gaps,
+    after.gaps,
+    (g) => g.expectationName,
+    (g) => `Gap: ${g.expectationName} (${g.type})`,
+    "gap",
+    changes
+  );
+  const scoreDelta = after.summary.healthScore - before.summary.healthScore;
+  const scoreDirection = scoreDelta > 0 ? "improved" : scoreDelta < 0 ? "degraded" : "unchanged";
+  return {
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    beforeTimestamp: before.timestamp,
+    afterTimestamp: after.timestamp,
+    changes,
+    scoreDelta,
+    summary: `Score ${scoreDirection} by ${Math.abs(scoreDelta)} points (${before.summary.healthScore} \u2192 ${after.summary.healthScore}). ${changes.length} changes: ${changes.filter((c) => c.type === "added").length} added, ${changes.filter((c) => c.type === "removed").length} removed, ${changes.filter((c) => c.type === "changed").length} changed.`
+  };
+}
+function diffItems(before, after, getKey, describe, category, changes) {
+  const beforeKeys = new Set(before.map(getKey));
+  const afterKeys = new Set(after.map(getKey));
+  for (const item of after) {
+    const key = getKey(item);
+    if (!beforeKeys.has(key)) {
+      changes.push({
+        type: "added",
+        category,
+        description: describe(item),
+        entityId: key
+      });
+    }
+  }
+  for (const item of before) {
+    const key = getKey(item);
+    if (!afterKeys.has(key)) {
+      changes.push({
+        type: "removed",
+        category,
+        description: describe(item),
+        entityId: key
+      });
+    }
+  }
+}
+
+export {
+  defineFact,
+  defineEvent,
+  defineRule,
+  defineConstraint,
+  defineModule,
+  filterEvents,
+  filterFacts,
+  findEvent,
+  findFact,
+  ContractMissing,
+  ContractValidated,
+  AcknowledgeContractGap,
+  ValidateContracts,
+  ContractGapAcknowledged,
+  ContractAdded,
+  ContractUpdated,
+  validateContracts,
+  formatValidationReport,
+  formatValidationReportJSON,
+  formatValidationReportSARIF,
+  BehaviorLedger,
+  createBehaviorLedger,
+  analyzeDependencyGraph,
+  findDeadRules,
+  findUnreachableStates,
+  findShadowedRules,
+  findContradictions,
+  findGaps,
+  traceDerivation,
+  traceImpact,
+  verifyContractExamples,
+  verifyInvariants,
+  findContractGaps,
+  crossReferenceContracts,
+  suggest,
+  suggestAll,
+  generateLedger,
+  formatLedger,
+  formatBuildOutput,
+  diffLedgers
+};