@plures/praxis 1.4.0 → 1.4.4

package/dist/node/index.cjs

@@ -622,12 +622,15 @@ __export(src_exports, {
   PraxisDBStore: () => PraxisDBStore,
   PraxisRegistry: () => PraxisRegistry,
   PraxisSchemaRegistry: () => PraxisSchemaRegistry,
+  ProjectChronicle: () => ProjectChronicle,
   ReactiveLogicEngine: () => ReactiveLogicEngine,
   RegistryIntrospector: () => RegistryIntrospector,
   RuleResult: () => RuleResult,
   StateDocsGenerator: () => StateDocsGenerator,
   TerminalAdapter: () => TerminalAdapter,
+  Timeline: () => Timeline,
   ValidateContracts: () => ValidateContracts,
+  analyzeDependencyGraph: () => analyzeDependencyGraph,
   attachAllIntegrations: () => attachAllIntegrations,
   attachTauriToEngine: () => attachTauriToEngine,
   attachToEngine: () => attachToEngine,
@@ -653,16 +656,19 @@ __export(src_exports, {
   createPraxisDBStore: () => createPraxisDBStore,
   createPraxisEngine: () => createPraxisEngine,
   createPraxisLocalFirst: () => createPraxisLocalFirst,
+  createProjectChronicle: () => createProjectChronicle,
   createReactiveEngine: () => createReactiveEngine,
   createSchemaRegistry: () => createSchemaRegistry,
   createSchemaTemplate: () => createSchemaTemplate,
   createStateDocsGenerator: () => createStateDocsGenerator,
   createTauriPraxisAdapter: () => createTauriPraxisAdapter,
   createTerminalAdapter: () => createTerminalAdapter,
+  createTimeline: () => createTimeline,
   createTimerActor: () => createTimerActor,
   createUIModule: () => createUIModule,
   createUnifiedApp: () => createUnifiedApp,
   createUnumAdapter: () => createUnumAdapter,
+  crossReferenceContracts: () => crossReferenceContracts,
   dataRules: () => dataRules,
   defineConstraint: () => defineConstraint,
   defineContract: () => defineContract,
@@ -671,17 +677,33 @@ __export(src_exports, {
   defineGate: () => defineGate,
   defineModule: () => defineModule,
   defineRule: () => defineRule,
+  diffContracts: () => diffContracts,
+  diffExpectations: () => diffExpectations,
+  diffLedgers: () => diffLedgers,
+  diffRegistries: () => diffRegistries,
   dirtyGuardRule: () => dirtyGuardRule,
+  enableProjectChronicle: () => enableProjectChronicle,
   errorDisplayRule: () => errorDisplayRule,
   expectBehavior: () => expectBehavior,
   expectationGate: () => expectationGate,
   fact: () => fact,
   filterEvents: () => filterEvents,
   filterFacts: () => filterFacts,
+  findContractGaps: () => findContractGaps,
+  findContradictions: () => findContradictions,
+  findDeadRules: () => findDeadRules,
   findEvent: () => findEvent,
   findFact: () => findFact,
+  findGaps: () => findGaps,
+  findShadowedRules: () => findShadowedRules,
+  findUnreachableStates: () => findUnreachableStates,
   formRules: () => formRules,
+  formatBehavioralCommit: () => formatCommitMessage,
+  formatBuildOutput: () => formatBuildOutput,
+  formatDelta: () => formatDelta,
   formatGate: () => formatGate,
+  formatLedger: () => formatLedger,
+  formatReleaseNotes: () => formatReleaseNotes,
   formatReport: () => formatReport,
   formatValidationReport: () => formatValidationReport,
   formatValidationReportJSON: () => formatValidationReportJSON,
@@ -689,6 +711,7 @@ __export(src_exports, {
   formatVerificationReport: () => formatVerificationReport,
   generateDocs: () => generateDocs,
   generateId: () => generateId,
+  generateLedger: () => generateLedger,
   generateTauriConfig: () => generateTauriConfig,
   getContract: () => getContract,
   getEventPath: () => getEventPath,
@@ -708,12 +731,17 @@ __export(src_exports, {
   navigationRules: () => navigationRules,
   noInteractionWhileLoadingConstraint: () => noInteractionWhileLoadingConstraint,
   offlineIndicatorRule: () => offlineIndicatorRule,
+  recordAudit: () => recordAudit,
   registerSchema: () => registerSchema,
   resizeEvent: () => resizeEvent,
   runTerminalCommand: () => runTerminalCommand,
   schemaToCanvas: () => schemaToCanvas,
   semverContract: () => semverContract,
+  suggest: () => suggest,
+  suggestAll: () => suggestAll,
   toastRules: () => toastRules,
+  traceDerivation: () => traceDerivation,
+  traceImpact: () => traceImpact,
   uiModule: () => uiModule,
   uiStateChanged: () => uiStateChanged,
   validateContracts: () => validateContracts,
@@ -721,6 +749,8 @@ __export(src_exports, {
   validateSchema: () => validateSchema,
   validateWithGuardian: () => validateWithGuardian,
   verify: () => verify,
+  verifyContractExamples: () => verifyContractExamples,
+  verifyInvariants: () => verifyInvariants,
   viewportRule: () => viewportRule
 });
 module.exports = __toCommonJS(src_exports);
@@ -2012,6 +2042,1190 @@ var import_node_path = __toESM(require("path"), 1);
 var import_node_fs2 = require("fs");
 var import_node_path2 = __toESM(require("path"), 1);
 
+// src/decision-ledger/analyzer.ts
+init_rule_result();
+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 fact2 of result.facts) {
+          if (!produced.includes(fact2.tag)) {
+            produced.push(fact2.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 fact2 of result) {
+        if (fact2.tag && !produced.includes(fact2.tag)) {
+          produced.push(fact2.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
+init_rule_result();
+function verifyContractExamples(rule, contract) {
+  const examples = [];
+  for (let i = 0; i < contract.examples.length; i++) {
+    const example = contract.examples[i];
+    try {
+      const state2 = buildStateFromDescription(example.given);
+      const events = buildEventsFromDescription(example.when, rule.eventTypes);
+      const stateWithEvents = { ...state2, 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(
+    (fact2) => traceDerivation(fact2.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
+      });
+    }
+  }
+}
+
 // src/runtime/terminal-adapter.ts
 async function defaultExecutor(command, options) {
   try {
@@ -6193,6 +7407,509 @@ function expectationGate(config = {}) {
     onViolation: "expectations-failed"
   });
 }
+
+// src/chronos/project-chronicle.ts
+var ProjectChronicle = class {
+  events = [];
+  maxEvents;
+  now;
+  constructor(options = {}) {
+    this.maxEvents = options.maxEvents ?? 1e4;
+    this.now = options.now ?? (() => Date.now());
+  }
+  // ── Recording ───────────────────────────────────────────────────────────
+  /**
+   * Record a project event. Returns the recorded event (with timestamp filled in).
+   */
+  record(event) {
+    const full = {
+      kind: event.kind,
+      action: event.action,
+      subject: event.subject,
+      timestamp: event.timestamp ?? this.now(),
+      metadata: event.metadata,
+      diff: event.diff
+    };
+    this.events.push(full);
+    if (this.maxEvents > 0 && this.events.length > this.maxEvents) {
+      this.events = this.events.slice(this.events.length - this.maxEvents);
+    }
+    return full;
+  }
+  // ── Convenience recorders ─────────────────────────────────────────────
+  recordRuleRegistered(ruleId, meta = {}) {
+    return this.record({ kind: "rule", action: "registered", subject: ruleId, metadata: meta });
+  }
+  recordRuleModified(ruleId, diff, meta = {}) {
+    return this.record({ kind: "rule", action: "modified", subject: ruleId, metadata: meta, diff });
+  }
+  recordRuleRemoved(ruleId, meta = {}) {
+    return this.record({ kind: "rule", action: "removed", subject: ruleId, metadata: meta });
+  }
+  recordContractAdded(contractId, meta = {}) {
+    return this.record({ kind: "contract", action: "added", subject: contractId, metadata: meta });
+  }
+  recordContractModified(contractId, diff, meta = {}) {
+    return this.record({ kind: "contract", action: "modified", subject: contractId, metadata: meta, diff });
+  }
+  recordExpectationSatisfied(name, meta = {}) {
+    return this.record({ kind: "expectation", action: "satisfied", subject: name, metadata: meta });
+  }
+  recordExpectationViolated(name, meta = {}) {
+    return this.record({ kind: "expectation", action: "violated", subject: name, metadata: meta });
+  }
+  recordGateTransition(gateName, from, to, meta = {}) {
+    return this.record({
+      kind: "gate",
+      action: to,
+      subject: gateName,
+      metadata: { ...meta, from, to },
+      diff: { before: from, after: to }
+    });
+  }
+  recordBuildAudit(score, delta, meta = {}) {
+    return this.record({
+      kind: "build",
+      action: "audit-complete",
+      subject: "completeness",
+      metadata: { ...meta, score, delta }
+    });
+  }
+  recordFactIntroduced(factTag, meta = {}) {
+    return this.record({ kind: "fact", action: "introduced", subject: factTag, metadata: meta });
+  }
+  recordFactDeprecated(factTag, meta = {}) {
+    return this.record({ kind: "fact", action: "deprecated", subject: factTag, metadata: meta });
+  }
+  // ── Access ──────────────────────────────────────────────────────────────
+  /** Return a shallow copy of all events. */
+  getEvents() {
+    return [...this.events];
+  }
+  /** Total number of recorded events. */
+  get size() {
+    return this.events.length;
+  }
+  /** Clear all events (primarily for testing). */
+  clear() {
+    this.events = [];
+  }
+};
+function createProjectChronicle(options) {
+  return new ProjectChronicle(options);
+}
+
+// src/chronos/timeline.ts
+var Timeline = class {
+  constructor(chronicle) {
+    this.chronicle = chronicle;
+  }
+  // ── Queries ─────────────────────────────────────────────────────────────
+  /**
+   * Query events with optional filtering.
+   * Returns matching events sorted chronologically (oldest first).
+   */
+  getTimeline(filter) {
+    let events = this.chronicle.getEvents();
+    if (!filter) return events;
+    events = applyFilter(events, filter);
+    return events;
+  }
+  /**
+   * Get all events since a timestamp (inclusive).
+   */
+  getEventsSince(timestamp) {
+    return this.getTimeline({ since: timestamp });
+  }
+  /**
+   * Compute a behavioral delta between two timestamps.
+   */
+  getDelta(from, to) {
+    const events = this.getTimeline({ since: from, until: to });
+    return buildDelta(from, to, events);
+  }
+  /**
+   * Get full history for a specific subject (rule id, gate name, etc.).
+   * Sorted chronologically.
+   */
+  getHistory(subjectId) {
+    return this.getTimeline({ subject: subjectId });
+  }
+};
+function applyFilter(events, filter) {
+  return events.filter((e) => {
+    if (filter.kind) {
+      const kinds = Array.isArray(filter.kind) ? filter.kind : [filter.kind];
+      if (!kinds.includes(e.kind)) return false;
+    }
+    if (filter.action) {
+      const actions = Array.isArray(filter.action) ? filter.action : [filter.action];
+      if (!actions.includes(e.action)) return false;
+    }
+    if (filter.subject) {
+      const subjects = Array.isArray(filter.subject) ? filter.subject : [filter.subject];
+      if (!subjects.includes(e.subject)) return false;
+    }
+    if (filter.since != null && e.timestamp < filter.since) return false;
+    if (filter.until != null && e.timestamp > filter.until) return false;
+    return true;
+  });
+}
+var ADD_ACTIONS = /* @__PURE__ */ new Set(["registered", "added", "introduced", "opened"]);
+var REMOVE_ACTIONS = /* @__PURE__ */ new Set(["removed", "deprecated", "closed"]);
+var MODIFY_ACTIONS = /* @__PURE__ */ new Set(["modified", "updated"]);
+function buildDelta(from, to, events) {
+  const summary = {};
+  const added = /* @__PURE__ */ new Set();
+  const removed = /* @__PURE__ */ new Set();
+  const modified = /* @__PURE__ */ new Set();
+  for (const e of events) {
+    summary[e.kind] = (summary[e.kind] ?? 0) + 1;
+    if (ADD_ACTIONS.has(e.action)) {
+      added.add(e.subject);
+      removed.delete(e.subject);
+    } else if (REMOVE_ACTIONS.has(e.action)) {
+      removed.add(e.subject);
+      added.delete(e.subject);
+    } else if (MODIFY_ACTIONS.has(e.action)) {
+      modified.add(e.subject);
+    }
+  }
+  return {
+    from,
+    to,
+    events,
+    summary,
+    added: [...added],
+    removed: [...removed],
+    modified: [...modified]
+  };
+}
+function createTimeline(chronicle) {
+  return new Timeline(chronicle);
+}
+
+// src/chronos/hooks.ts
+function enableProjectChronicle(registry, engine, options = {}) {
+  const chronicle = options.chronicle ?? createProjectChronicle();
+  const recordSteps = options.recordSteps ?? true;
+  const recordConstraints = options.recordConstraints ?? true;
+  const origRegisterRule = registry.registerRule.bind(registry);
+  const origRegisterModule = registry.registerModule.bind(registry);
+  const origStep = engine.step.bind(engine);
+  const origCheckConstraints = engine.checkConstraints.bind(engine);
+  registry.registerRule = function hookedRegisterRule(descriptor) {
+    origRegisterRule(descriptor);
+    chronicle.recordRuleRegistered(descriptor.id, {
+      description: descriptor.description,
+      hasContract: !!descriptor.contract,
+      eventTypes: descriptor.eventTypes
+    });
+    if (descriptor.contract) {
+      chronicle.recordContractAdded(descriptor.id, {
+        behavior: descriptor.contract.behavior,
+        examplesCount: descriptor.contract.examples?.length ?? 0,
+        invariantsCount: descriptor.contract.invariants?.length ?? 0
+      });
+    }
+  };
+  registry.registerModule = function hookedRegisterModule(module2) {
+    origRegisterModule(module2);
+    for (const rule of module2.rules) {
+      chronicle.recordRuleRegistered(rule.id, {
+        description: rule.description,
+        hasContract: !!rule.contract,
+        eventTypes: rule.eventTypes,
+        registeredVia: "module"
+      });
+      if (rule.contract) {
+        chronicle.recordContractAdded(rule.id, {
+          behavior: rule.contract.behavior,
+          examplesCount: rule.contract.examples?.length ?? 0,
+          invariantsCount: rule.contract.invariants?.length ?? 0
+        });
+      }
+    }
+  };
+  if (recordSteps) {
+    engine.step = function hookedStep(events) {
+      const result = origStep(events);
+      const factTags = /* @__PURE__ */ new Set();
+      for (const fact2 of result.state.facts) {
+        factTags.add(fact2.tag);
+      }
+      chronicle.record({
+        kind: "build",
+        action: "step-complete",
+        subject: "engine",
+        metadata: {
+          eventsProcessed: events.length,
+          eventTags: events.map((e) => e.tag),
+          factsAfter: result.state.facts.length,
+          diagnosticsCount: result.diagnostics.length
+        }
+      });
+      for (const diag of result.diagnostics) {
+        if (diag.kind === "constraint-violation") {
+          chronicle.record({
+            kind: "expectation",
+            action: "violated",
+            subject: extractSubjectFromDiag(diag),
+            metadata: { message: diag.message, data: diag.data }
+          });
+        }
+      }
+      return result;
+    };
+  }
+  if (recordConstraints) {
+    engine.checkConstraints = function hookedCheckConstraints() {
+      const diagnostics = origCheckConstraints();
+      chronicle.record({
+        kind: "build",
+        action: "constraints-checked",
+        subject: "engine",
+        metadata: {
+          violations: diagnostics.length
+        }
+      });
+      for (const diag of diagnostics) {
+        chronicle.record({
+          kind: "expectation",
+          action: "violated",
+          subject: extractSubjectFromDiag(diag),
+          metadata: { message: diag.message }
+        });
+      }
+      return diagnostics;
+    };
+  }
+  function disconnect() {
+    registry.registerRule = origRegisterRule;
+    registry.registerModule = origRegisterModule;
+    engine.step = origStep;
+    engine.checkConstraints = origCheckConstraints;
+  }
+  return { chronicle, disconnect };
+}
+function recordAudit(chronicle, report, previousScore) {
+  const delta = previousScore != null ? report.score - previousScore : 0;
+  chronicle.recordBuildAudit(report.score, delta, {
+    rating: report.rating,
+    rulesCovered: report.rules.covered,
+    rulesTotal: report.rules.total,
+    constraintsCovered: report.constraints.covered,
+    constraintsTotal: report.constraints.total,
+    contractsCovered: report.contracts.withContracts,
+    contractsTotal: report.contracts.total
+  });
+}
+function extractSubjectFromDiag(diag) {
+  const data = diag.data;
+  if (data?.constraintId && typeof data.constraintId === "string") return data.constraintId;
+  if (data?.ruleId && typeof data.ruleId === "string") return data.ruleId;
+  return "unknown";
+}
+
+// src/chronos/diff.ts
+function diffRegistries(before, after) {
+  const beforeRules = toIdMap(before.rules);
+  const afterRules = toIdMap(after.rules);
+  const beforeConstraints = toIdMap(before.constraints);
+  const afterConstraints = toIdMap(after.constraints);
+  return {
+    rulesAdded: setDiff(afterRules, beforeRules),
+    rulesRemoved: setDiff(beforeRules, afterRules),
+    rulesModified: findModified(beforeRules, afterRules),
+    constraintsAdded: setDiff(afterConstraints, beforeConstraints),
+    constraintsRemoved: setDiff(beforeConstraints, afterConstraints),
+    constraintsModified: findModified(beforeConstraints, afterConstraints)
+  };
+}
+function diffContracts(before, after) {
+  const beforeMap = toRecord(before.coverage);
+  const afterMap = toRecord(after.coverage);
+  const contractsAdded = [];
+  const contractsRemoved = [];
+  for (const [id, has] of Object.entries(afterMap)) {
+    if (has && !beforeMap[id]) {
+      contractsAdded.push(id);
+    }
+  }
+  for (const [id, had] of Object.entries(beforeMap)) {
+    if (had && !afterMap[id]) {
+      contractsRemoved.push(id);
+    }
+  }
+  const countTrue = (r) => Object.values(r).filter(Boolean).length;
+  const totalBefore = Object.keys(beforeMap).length;
+  const totalAfter = Object.keys(afterMap).length;
+  return {
+    contractsAdded,
+    contractsRemoved,
+    coverageBefore: totalBefore > 0 ? countTrue(beforeMap) / totalBefore : 0,
+    coverageAfter: totalAfter > 0 ? countTrue(afterMap) / totalAfter : 0
+  };
+}
+function diffExpectations(before, after) {
+  const beforeMap = toRecord(before.expectations);
+  const afterMap = toRecord(after.expectations);
+  const allKeys = /* @__PURE__ */ new Set([...Object.keys(beforeMap), ...Object.keys(afterMap)]);
+  const newlySatisfied = [];
+  const newlyViolated = [];
+  const unchanged = [];
+  for (const key of allKeys) {
+    const was = beforeMap[key] ?? false;
+    const is = afterMap[key] ?? false;
+    if (!was && is) {
+      newlySatisfied.push(key);
+    } else if (was && !is) {
+      newlyViolated.push(key);
+    } else {
+      unchanged.push(key);
+    }
+  }
+  return { newlySatisfied, newlyViolated, unchanged };
+}
+function formatDelta(diff) {
+  const lines = [];
+  if (diff.rulesAdded.length > 0)
+    lines.push(`+ Rules added: ${diff.rulesAdded.join(", ")}`);
+  if (diff.rulesRemoved.length > 0)
+    lines.push(`- Rules removed: ${diff.rulesRemoved.join(", ")}`);
+  if (diff.rulesModified.length > 0)
+    lines.push(`~ Rules modified: ${diff.rulesModified.join(", ")}`);
+  if (diff.constraintsAdded.length > 0)
+    lines.push(`+ Constraints added: ${diff.constraintsAdded.join(", ")}`);
+  if (diff.constraintsRemoved.length > 0)
+    lines.push(`- Constraints removed: ${diff.constraintsRemoved.join(", ")}`);
+  if (diff.constraintsModified.length > 0)
+    lines.push(`~ Constraints modified: ${diff.constraintsModified.join(", ")}`);
+  return lines.length > 0 ? lines.join("\n") : "No behavioral changes.";
+}
+function formatCommitMessage(diff) {
+  const praxisDiff = {
+    rulesAdded: diff.rulesAdded,
+    rulesRemoved: diff.rulesRemoved,
+    rulesModified: diff.rulesModified,
+    contractsAdded: [],
+    contractsRemoved: [],
+    expectationsAdded: diff.constraintsAdded,
+    expectationsRemoved: diff.constraintsRemoved,
+    gateChanges: []
+  };
+  return commitFromDiff(praxisDiff);
+}
+function formatReleaseNotes(diffs) {
+  const sections = [];
+  const allAdded = [];
+  const allRemoved = [];
+  const allModified = [];
+  for (const diff of diffs) {
+    allAdded.push(...diff.rulesAdded, ...diff.constraintsAdded);
+    allRemoved.push(...diff.rulesRemoved, ...diff.constraintsRemoved);
+    allModified.push(...diff.rulesModified, ...diff.constraintsModified);
+  }
+  const added = [...new Set(allAdded)];
+  const removed = [...new Set(allRemoved)];
+  const modified = [...new Set(allModified)];
+  if (added.length > 0) {
+    sections.push(`### Added
+${added.map((id) => `- ${id}`).join("\n")}`);
+  }
+  if (modified.length > 0) {
+    sections.push(`### Changed
+${modified.map((id) => `- ${id}`).join("\n")}`);
+  }
+  if (removed.length > 0) {
+    sections.push(`### Removed
+${removed.map((id) => `- ${id}`).join("\n")}`);
+  }
+  if (sections.length === 0) return "No behavioral changes in this release.";
+  return `## Release Notes
+
+${sections.join("\n\n")}`;
+}
+function toIdMap(input) {
+  if (input instanceof Map) return input;
+  const map = /* @__PURE__ */ new Map();
+  for (const item of input) map.set(item.id, item);
+  return map;
+}
+function setDiff(a, b) {
+  const result = [];
+  for (const key of a.keys()) {
+    if (!b.has(key)) result.push(key);
+  }
+  return result;
+}
+function findModified(before, after) {
+  const result = [];
+  for (const [key, beforeVal] of before) {
+    const afterVal = after.get(key);
+    if (afterVal && beforeVal.description !== afterVal.description) {
+      result.push(key);
+    }
+  }
+  return result;
+}
+function toRecord(input) {
+  if (input instanceof Map) {
+    const result = {};
+    for (const [k, v] of input) result[k] = v;
+    return result;
+  }
+  return input;
+}
+function commitFromDiff(diff) {
+  const parts = [];
+  const bodyParts = [];
+  const totalAdded = diff.rulesAdded.length + diff.contractsAdded.length + diff.expectationsAdded.length;
+  const totalRemoved = diff.rulesRemoved.length + diff.contractsRemoved.length + diff.expectationsRemoved.length;
+  const totalModified = diff.rulesModified.length;
+  if (totalAdded > 0 && totalRemoved === 0 && totalModified === 0) {
+    if (diff.rulesAdded.length > 0) {
+      const scope = inferScope2(diff.rulesAdded);
+      parts.push(`feat(${scope}): add ${fmtIds(diff.rulesAdded)}`);
+    } else if (diff.contractsAdded.length > 0) {
+      parts.push(`feat(contracts): add contracts for ${fmtIds(diff.contractsAdded)}`);
+    } else {
+      parts.push(`feat(expectations): add ${fmtIds(diff.expectationsAdded)}`);
+    }
+  } else if (totalRemoved > 0 && totalAdded === 0) {
+    if (diff.rulesRemoved.length > 0) {
+      const scope = inferScope2(diff.rulesRemoved);
+      parts.push(`refactor(${scope}): remove ${fmtIds(diff.rulesRemoved)}`);
+    } else {
+      parts.push(`refactor: remove ${totalRemoved} item(s)`);
+    }
+  } else if (totalModified > 0) {
+    const scope = inferScope2(diff.rulesModified);
+    parts.push(`refactor(${scope}): update ${fmtIds(diff.rulesModified)}`);
+  } else {
+    parts.push("chore: behavioral state update");
+  }
+  if (diff.rulesAdded.length > 0) bodyParts.push(`Rules added: ${diff.rulesAdded.join(", ")}`);
+  if (diff.rulesRemoved.length > 0) bodyParts.push(`Rules removed: ${diff.rulesRemoved.join(", ")}`);
+  if (diff.rulesModified.length > 0) bodyParts.push(`Rules modified: ${diff.rulesModified.join(", ")}`);
+  const subject = parts[0] || "chore: update";
+  return bodyParts.length > 0 ? `${subject}
+
+${bodyParts.join("\n")}` : subject;
+}
+function inferScope2(ids) {
+  if (ids.length === 0) return "rules";
+  const prefixes = ids.map((id) => {
+    const slash = id.indexOf("/");
+    return slash > 0 ? id.slice(0, slash) : id;
+  });
+  const unique = new Set(prefixes);
+  return unique.size === 1 ? prefixes[0] : "rules";
+}
+function fmtIds(ids) {
+  if (ids.length <= 3) return ids.join(", ");
+  return `${ids.slice(0, 2).join(", ")} (+${ids.length - 2} more)`;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AcknowledgeContractGap,
@@ -6218,12 +7935,15 @@ function expectationGate(config = {}) {
   PraxisDBStore,
   PraxisRegistry,
   PraxisSchemaRegistry,
+  ProjectChronicle,
   ReactiveLogicEngine,
   RegistryIntrospector,
   RuleResult,
   StateDocsGenerator,
   TerminalAdapter,
+  Timeline,
   ValidateContracts,
+  analyzeDependencyGraph,
   attachAllIntegrations,
   attachTauriToEngine,
   attachToEngine,
@@ -6249,16 +7969,19 @@ function expectationGate(config = {}) {
   createPraxisDBStore,
   createPraxisEngine,
   createPraxisLocalFirst,
+  createProjectChronicle,
   createReactiveEngine,
   createSchemaRegistry,
   createSchemaTemplate,
   createStateDocsGenerator,
   createTauriPraxisAdapter,
   createTerminalAdapter,
+  createTimeline,
   createTimerActor,
   createUIModule,
   createUnifiedApp,
   createUnumAdapter,
+  crossReferenceContracts,
   dataRules,
   defineConstraint,
   defineContract,
@@ -6267,17 +7990,33 @@ function expectationGate(config = {}) {
   defineGate,
   defineModule,
   defineRule,
+  diffContracts,
+  diffExpectations,
+  diffLedgers,
+  diffRegistries,
   dirtyGuardRule,
+  enableProjectChronicle,
   errorDisplayRule,
   expectBehavior,
   expectationGate,
   fact,
   filterEvents,
   filterFacts,
+  findContractGaps,
+  findContradictions,
+  findDeadRules,
   findEvent,
   findFact,
+  findGaps,
+  findShadowedRules,
+  findUnreachableStates,
   formRules,
+  formatBehavioralCommit,
+  formatBuildOutput,
+  formatDelta,
   formatGate,
+  formatLedger,
+  formatReleaseNotes,
   formatReport,
   formatValidationReport,
   formatValidationReportJSON,
@@ -6285,6 +8024,7 @@ function expectationGate(config = {}) {
   formatVerificationReport,
   generateDocs,
   generateId,
+  generateLedger,
   generateTauriConfig,
   getContract,
   getEventPath,
@@ -6304,12 +8044,17 @@ function expectationGate(config = {}) {
   navigationRules,
   noInteractionWhileLoadingConstraint,
   offlineIndicatorRule,
+  recordAudit,
   registerSchema,
   resizeEvent,
   runTerminalCommand,
   schemaToCanvas,
   semverContract,
+  suggest,
+  suggestAll,
   toastRules,
+  traceDerivation,
+  traceImpact,
   uiModule,
   uiStateChanged,
   validateContracts,
@@ -6317,5 +8062,7 @@ function expectationGate(config = {}) {
   validateSchema,
   validateWithGuardian,
   verify,
+  verifyContractExamples,
+  verifyInvariants,
   viewportRule
 });