@plures/praxis 1.3.0 → 1.4.0

package/dist/node/cli/index.cjs

@@ -3517,6 +3517,1065 @@ var init_cloud = __esm({
   }
 });
 
+// src/core/protocol.ts
+var PRAXIS_PROTOCOL_VERSION;
+var init_protocol = __esm({
+  "src/core/protocol.ts"() {
+    "use strict";
+    PRAXIS_PROTOCOL_VERSION = "1.0.0";
+  }
+});
+
+// src/core/rule-result.ts
+var RuleResult;
+var init_rule_result = __esm({
+  "src/core/rule-result.ts"() {
+    "use strict";
+    RuleResult = class _RuleResult {
+      /** The kind of result */
+      kind;
+      /** Facts produced (only for 'emit') */
+      facts;
+      /** Fact tags to retract (only for 'retract') */
+      retractTags;
+      /** Optional reason (for noop/skip/retract — useful for debugging) */
+      reason;
+      /** The rule ID that produced this result (set by engine) */
+      ruleId;
+      constructor(kind, facts, retractTags, reason) {
+        this.kind = kind;
+        this.facts = facts;
+        this.retractTags = retractTags;
+        this.reason = reason;
+      }
+      /**
+       * Rule produced facts.
+       *
+       * @example
+       * return RuleResult.emit([
+       *   { tag: 'sprint.behind', payload: { deficit: 5 } }
+       * ]);
+       */
+      static emit(facts) {
+        if (facts.length === 0) {
+          throw new Error(
+            "RuleResult.emit() requires at least one fact. Use RuleResult.noop() or RuleResult.skip() when a rule has nothing to say."
+          );
+        }
+        return new _RuleResult("emit", facts, []);
+      }
+      /**
+       * Rule evaluated but had nothing to report.
+       * Unlike returning [], this is explicit and traceable.
+       *
+       * @example
+       * if (ctx.completedHours >= expectedHours) {
+       *   return RuleResult.noop('Sprint is on pace');
+       * }
+       */
+      static noop(reason) {
+        return new _RuleResult("noop", [], [], reason);
+      }
+      /**
+       * Rule decided to skip because preconditions were not met.
+       * Distinct from noop: skip means "I can't evaluate", noop means "I evaluated and found nothing".
+       *
+       * @example
+       * if (!ctx.sprintName) {
+       *   return RuleResult.skip('No active sprint');
+       * }
+       */
+      static skip(reason) {
+        return new _RuleResult("skip", [], [], reason);
+      }
+      /**
+       * Rule retracts previously emitted facts by tag.
+       * Used when a condition that previously produced facts is no longer true.
+       *
+       * @example
+       * // Sprint was behind, but caught up
+       * if (ctx.completedHours >= expectedHours) {
+       *   return RuleResult.retract(['sprint.behind'], 'Sprint caught up');
+       * }
+       */
+      static retract(tags, reason) {
+        if (tags.length === 0) {
+          throw new Error("RuleResult.retract() requires at least one tag.");
+        }
+        return new _RuleResult("retract", [], tags, reason);
+      }
+      /** Whether this result produced facts */
+      get hasFacts() {
+        return this.facts.length > 0;
+      }
+      /** Whether this result retracts facts */
+      get hasRetractions() {
+        return this.retractTags.length > 0;
+      }
+    };
+  }
+});
+
+// src/core/engine.ts
+function safeClone(value) {
+  if (value === null || typeof value !== "object") {
+    return value;
+  }
+  if (typeof globalThis.structuredClone === "function") {
+    try {
+      return globalThis.structuredClone(value);
+    } catch {
+    }
+  }
+  if (Array.isArray(value)) {
+    return [...value];
+  }
+  return { ...value };
+}
+var LogicEngine;
+var init_engine = __esm({
+  "src/core/engine.ts"() {
+    "use strict";
+    init_protocol();
+    init_rule_result();
+    LogicEngine = class {
+      state;
+      registry;
+      factDedup;
+      maxFacts;
+      constructor(options) {
+        this.registry = options.registry;
+        this.factDedup = options.factDedup ?? "last-write-wins";
+        this.maxFacts = options.maxFacts ?? 1e3;
+        this.state = {
+          context: options.initialContext,
+          facts: options.initialFacts ?? [],
+          meta: options.initialMeta ?? {},
+          protocolVersion: PRAXIS_PROTOCOL_VERSION
+        };
+      }
+      /**
+       * Get the current state (immutable copy)
+       */
+      getState() {
+        return {
+          context: safeClone(this.state.context),
+          facts: [...this.state.facts],
+          meta: this.state.meta ? safeClone(this.state.meta) : void 0,
+          protocolVersion: this.state.protocolVersion
+        };
+      }
+      /**
+       * Get the current context
+       */
+      getContext() {
+        return safeClone(this.state.context);
+      }
+      /**
+       * Get current facts
+       */
+      getFacts() {
+        return [...this.state.facts];
+      }
+      /**
+       * Process events through the engine.
+       * Applies all registered rules and checks all registered constraints.
+       *
+       * @param events Events to process
+       * @returns Result with new state and diagnostics
+       */
+      step(events) {
+        const config = {
+          ruleIds: this.registry.getRuleIds(),
+          constraintIds: this.registry.getConstraintIds()
+        };
+        return this.stepWithConfig(events, config);
+      }
+      /**
+       * Process events with specific rule and constraint configuration.
+       *
+       * @param events Events to process
+       * @param config Step configuration
+       * @returns Result with new state and diagnostics
+       */
+      stepWithConfig(events, config) {
+        const diagnostics = [];
+        let newState = { ...this.state };
+        const stateWithEvents = {
+          ...newState,
+          events
+          // current batch — rules can read state.events
+        };
+        const newFacts = [];
+        const retractions = [];
+        const eventTags = new Set(events.map((e) => e.tag));
+        for (const ruleId of config.ruleIds) {
+          const rule = this.registry.getRule(ruleId);
+          if (!rule) {
+            diagnostics.push({
+              kind: "rule-error",
+              message: `Rule "${ruleId}" not found in registry`,
+              data: { ruleId }
+            });
+            continue;
+          }
+          if (rule.eventTypes) {
+            const filterTags = Array.isArray(rule.eventTypes) ? rule.eventTypes : [rule.eventTypes];
+            if (!filterTags.some((t) => eventTags.has(t))) {
+              continue;
+            }
+          }
+          try {
+            const rawResult = rule.impl(stateWithEvents, events);
+            if (rawResult instanceof RuleResult) {
+              rawResult.ruleId = ruleId;
+              switch (rawResult.kind) {
+                case "emit":
+                  newFacts.push(...rawResult.facts);
+                  break;
+                case "retract":
+                  retractions.push(...rawResult.retractTags);
+                  break;
+                case "noop":
+                case "skip":
+                  if (rawResult.reason) {
+                    diagnostics.push({
+                      kind: "rule-error",
+                      // reused kind — could add 'rule-trace' in protocol v2
+                      message: `[${rawResult.kind}] ${ruleId}: ${rawResult.reason}`,
+                      data: { ruleId, resultKind: rawResult.kind, reason: rawResult.reason }
+                    });
+                  }
+                  break;
+              }
+            } else if (Array.isArray(rawResult)) {
+              newFacts.push(...rawResult);
+            }
+          } catch (error) {
+            diagnostics.push({
+              kind: "rule-error",
+              message: `Error executing rule "${ruleId}": ${error instanceof Error ? error.message : String(error)}`,
+              data: { ruleId, error }
+            });
+          }
+        }
+        let existingFacts = newState.facts;
+        if (retractions.length > 0) {
+          const retractSet = new Set(retractions);
+          existingFacts = existingFacts.filter((f) => !retractSet.has(f.tag));
+        }
+        let mergedFacts;
+        switch (this.factDedup) {
+          case "last-write-wins": {
+            const factMap = /* @__PURE__ */ new Map();
+            for (const f of existingFacts) factMap.set(f.tag, f);
+            for (const f of newFacts) factMap.set(f.tag, f);
+            mergedFacts = Array.from(factMap.values());
+            break;
+          }
+          case "append":
+            mergedFacts = [...existingFacts, ...newFacts];
+            break;
+          case "none":
+          default:
+            mergedFacts = [...existingFacts, ...newFacts];
+            break;
+        }
+        if (this.maxFacts > 0 && mergedFacts.length > this.maxFacts) {
+          mergedFacts = mergedFacts.slice(mergedFacts.length - this.maxFacts);
+        }
+        newState = {
+          ...newState,
+          facts: mergedFacts
+        };
+        for (const constraintId of config.constraintIds) {
+          const constraint = this.registry.getConstraint(constraintId);
+          if (!constraint) {
+            diagnostics.push({
+              kind: "constraint-violation",
+              message: `Constraint "${constraintId}" not found in registry`,
+              data: { constraintId }
+            });
+            continue;
+          }
+          try {
+            const result = constraint.impl(newState);
+            if (result === false) {
+              diagnostics.push({
+                kind: "constraint-violation",
+                message: `Constraint "${constraintId}" violated`,
+                data: { constraintId, description: constraint.description }
+              });
+            } else if (typeof result === "string") {
+              diagnostics.push({
+                kind: "constraint-violation",
+                message: result,
+                data: { constraintId, description: constraint.description }
+              });
+            }
+          } catch (error) {
+            diagnostics.push({
+              kind: "constraint-violation",
+              message: `Error checking constraint "${constraintId}": ${error instanceof Error ? error.message : String(error)}`,
+              data: { constraintId, error }
+            });
+          }
+        }
+        this.state = newState;
+        return {
+          state: newState,
+          diagnostics
+        };
+      }
+      /**
+       * Update the context directly (for exceptional cases).
+       * Generally, context should be updated through rules.
+       *
+       * @param updater Function that produces new context from old context
+       */
+      updateContext(updater) {
+        this.state = {
+          ...this.state,
+          context: updater(this.state.context)
+        };
+      }
+      /**
+       * Atomically update context AND process events in a single call.
+       *
+       * This avoids the fragile pattern of calling updateContext() then step()
+       * separately, where rules could see stale context if the ordering is wrong.
+       *
+       * @param updater Function that produces new context from old context
+       * @param events Events to process after context is updated
+       * @returns Result with new state and diagnostics
+       *
+       * @example
+       * engine.stepWithContext(
+       *   ctx => ({ ...ctx, sprintName: sprint.name, items: sprint.items }),
+       *   [{ tag: 'sprint.update', payload: { name: sprint.name } }]
+       * );
+       */
+      stepWithContext(updater, events) {
+        this.state = {
+          ...this.state,
+          context: updater(this.state.context)
+        };
+        return this.step(events);
+      }
+      /**
+       * Add facts directly (for exceptional cases).
+       * Generally, facts should be added through rules.
+       *
+       * @param facts Facts to add
+       */
+      addFacts(facts) {
+        this.state = {
+          ...this.state,
+          facts: [...this.state.facts, ...facts]
+        };
+      }
+      /**
+       * Check all constraints without processing any events.
+       *
+       * Useful for validation-only scenarios (e.g., form validation,
+       * pre-save checks) where you want constraint diagnostics without
+       * triggering any rules.
+       *
+       * @returns Array of constraint violation diagnostics (empty = all passing)
+       */
+      checkConstraints() {
+        return this.stepWithConfig([], {
+          ruleIds: [],
+          constraintIds: this.registry.getConstraintIds()
+        }).diagnostics;
+      }
+      /**
+       * Clear all facts
+       */
+      clearFacts() {
+        this.state = {
+          ...this.state,
+          facts: []
+        };
+      }
+      /**
+       * Reset the engine to initial state
+       */
+      reset(options) {
+        this.state = {
+          context: options.initialContext,
+          facts: options.initialFacts ?? [],
+          meta: options.initialMeta ?? {},
+          protocolVersion: PRAXIS_PROTOCOL_VERSION
+        };
+      }
+    };
+  }
+});
+
+// src/core/completeness.ts
+function auditCompleteness(manifest, registryRuleIds, registryConstraintIds, rulesWithContracts, config) {
+  const threshold = config?.threshold ?? 90;
+  const domainBranches = manifest.branches.filter((b) => b.kind === "domain");
+  const coveredDomain = domainBranches.filter((b) => b.coveredBy && registryRuleIds.includes(b.coveredBy));
+  const uncoveredDomain = domainBranches.filter((b) => !b.coveredBy || !registryRuleIds.includes(b.coveredBy));
+  const invariantBranches = manifest.branches.filter((b) => b.kind === "invariant");
+  const coveredInvariants = invariantBranches.filter((b) => b.coveredBy && registryConstraintIds.includes(b.coveredBy));
+  const uncoveredInvariants = invariantBranches.filter((b) => !b.coveredBy || !registryConstraintIds.includes(b.coveredBy));
+  const needContracts = manifest.rulesNeedingContracts;
+  const haveContracts = needContracts.filter((id) => rulesWithContracts.includes(id));
+  const missingContracts = needContracts.filter((id) => !rulesWithContracts.includes(id));
+  const neededFields = manifest.stateFields.filter((f) => f.usedByRule);
+  const coveredFields = neededFields.filter((f) => f.inContext);
+  const missingFields = neededFields.filter((f) => !f.inContext);
+  const coveredTransitions = manifest.transitions.filter((t) => t.eventTag);
+  const missingTransitions = manifest.transitions.filter((t) => !t.eventTag);
+  const ruleScore = domainBranches.length > 0 ? coveredDomain.length / domainBranches.length * 40 : 40;
+  const constraintScore = invariantBranches.length > 0 ? coveredInvariants.length / invariantBranches.length * 20 : 20;
+  const contractScore = needContracts.length > 0 ? haveContracts.length / needContracts.length * 15 : 15;
+  const contextScore = neededFields.length > 0 ? coveredFields.length / neededFields.length * 15 : 15;
+  const eventScore = manifest.transitions.length > 0 ? coveredTransitions.length / manifest.transitions.length * 10 : 10;
+  const score = Math.round(ruleScore + constraintScore + contractScore + contextScore + eventScore);
+  const rating = score >= 90 ? "complete" : score >= 70 ? "good" : score >= 50 ? "partial" : "incomplete";
+  const report = {
+    score,
+    rating,
+    rules: { total: domainBranches.length, covered: coveredDomain.length, uncovered: uncoveredDomain },
+    constraints: { total: invariantBranches.length, covered: coveredInvariants.length, uncovered: uncoveredInvariants },
+    contracts: { total: needContracts.length, withContracts: haveContracts.length, missing: missingContracts },
+    context: { total: neededFields.length, covered: coveredFields.length, missing: missingFields },
+    events: { total: manifest.transitions.length, covered: coveredTransitions.length, missing: missingTransitions }
+  };
+  if (config?.strict && score < threshold) {
+    throw new Error(`Praxis completeness ${score}/100 (${rating}) \u2014 below threshold ${threshold}. ${uncoveredDomain.length} uncovered rules, ${uncoveredInvariants.length} uncovered invariants, ${missingContracts.length} missing contracts.`);
+  }
+  return report;
+}
+function formatReport(report) {
+  const lines = [];
+  const icon = report.rating === "complete" ? "\u2705" : report.rating === "good" ? "\u{1F7E2}" : report.rating === "partial" ? "\u{1F7E1}" : "\u{1F534}";
+  lines.push(`${icon} Praxis Completeness: ${report.score}/100 (${report.rating})`);
+  lines.push("");
+  lines.push(`Rules:       ${report.rules.covered}/${report.rules.total} domain branches covered (${pct(report.rules.covered, report.rules.total)})`);
+  lines.push(`Constraints: ${report.constraints.covered}/${report.constraints.total} invariants covered (${pct(report.constraints.covered, report.constraints.total)})`);
+  lines.push(`Contracts:   ${report.contracts.withContracts}/${report.contracts.total} rules have contracts (${pct(report.contracts.withContracts, report.contracts.total)})`);
+  lines.push(`Context:     ${report.context.covered}/${report.context.total} state fields in context (${pct(report.context.covered, report.context.total)})`);
+  lines.push(`Events:      ${report.events.covered}/${report.events.total} transitions have events (${pct(report.events.covered, report.events.total)})`);
+  if (report.rules.uncovered.length > 0) {
+    lines.push("");
+    lines.push("Uncovered domain logic:");
+    for (const b of report.rules.uncovered) {
+      lines.push(`  \u274C ${b.location}: ${b.condition}${b.note ? ` \u2014 ${b.note}` : ""}`);
+    }
+  }
+  if (report.constraints.uncovered.length > 0) {
+    lines.push("");
+    lines.push("Uncovered invariants:");
+    for (const b of report.constraints.uncovered) {
+      lines.push(`  \u274C ${b.location}: ${b.condition}${b.note ? ` \u2014 ${b.note}` : ""}`);
+    }
+  }
+  if (report.contracts.missing.length > 0) {
+    lines.push("");
+    lines.push("Rules missing contracts:");
+    for (const id of report.contracts.missing) {
+      lines.push(`  \u{1F4DD} ${id}`);
+    }
+  }
+  if (report.events.missing.length > 0) {
+    lines.push("");
+    lines.push("State transitions without events:");
+    for (const t of report.events.missing) {
+      lines.push(`  \u26A1 ${t.location}: ${t.description}`);
+    }
+  }
+  return lines.join("\n");
+}
+function pct(a, b) {
+  if (b === 0) return "100%";
+  return Math.round(a / b * 100) + "%";
+}
+var init_completeness = __esm({
+  "src/core/completeness.ts"() {
+    "use strict";
+  }
+});
+
+// src/decision-ledger/types.ts
+function isContract(obj) {
+  if (typeof obj !== "object" || obj === null) {
+    return false;
+  }
+  const contract = obj;
+  return typeof contract.ruleId === "string" && typeof contract.behavior === "string" && Array.isArray(contract.examples) && contract.examples.length > 0 && contract.examples.every(
+    (ex) => typeof ex === "object" && ex !== null && typeof ex.given === "string" && typeof ex.when === "string" && typeof ex.then === "string"
+  ) && Array.isArray(contract.invariants) && contract.invariants.every((inv) => typeof inv === "string");
+}
+function defineContract(options) {
+  if (options.examples.length === 0) {
+    throw new Error("Contract must have at least one example");
+  }
+  if (options.assumptions) {
+    for (const assumption of options.assumptions) {
+      if (assumption.confidence < 0 || assumption.confidence > 1) {
+        throw new Error(
+          `Assumption '${assumption.id}' has invalid confidence value ${assumption.confidence}. Must be between 0.0 and 1.0`
+        );
+      }
+    }
+  }
+  return {
+    ruleId: options.ruleId,
+    behavior: options.behavior,
+    examples: options.examples,
+    invariants: options.invariants,
+    assumptions: options.assumptions,
+    references: options.references,
+    version: options.version || "1.0.0",
+    timestamp: (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+function getContract(meta) {
+  if (!meta || !meta.contract) {
+    return void 0;
+  }
+  if (isContract(meta.contract)) {
+    return meta.contract;
+  }
+  return void 0;
+}
+function getContractFromDescriptor(descriptor) {
+  if (!descriptor) {
+    return void 0;
+  }
+  if (descriptor.contract && isContract(descriptor.contract)) {
+    return descriptor.contract;
+  }
+  return getContract(descriptor.meta);
+}
+var init_types2 = __esm({
+  "src/decision-ledger/types.ts"() {
+    "use strict";
+  }
+});
+
+// src/mcp/server.ts
+var server_exports = {};
+__export(server_exports, {
+  createPraxisMcpServer: () => createPraxisMcpServer
+});
+function createPraxisMcpServer(options) {
+  const {
+    name = "@plures/praxis",
+    version = "1.0.0",
+    initialContext,
+    registry,
+    initialFacts
+  } = options;
+  const engine = new LogicEngine({
+    initialContext,
+    registry,
+    initialFacts
+  });
+  const server2 = new import_mcp.McpServer({
+    name,
+    version
+  });
+  server2.tool(
+    "praxis.inspect",
+    "List all registered rules, constraints, and their contracts",
+    {
+      filter: import_zod.z.string().optional().describe("Filter rule/constraint IDs by pattern (substring match)"),
+      includeContracts: import_zod.z.boolean().optional().describe("Include full contract details (default: false)")
+    },
+    async (params) => {
+      const filter = params.filter;
+      const includeContracts = params.includeContracts ?? false;
+      let rules = registry.getAllRules();
+      let constraints = registry.getAllConstraints();
+      if (filter) {
+        rules = rules.filter((r) => r.id.includes(filter));
+        constraints = constraints.filter((c) => c.id.includes(filter));
+      }
+      const ruleInfos = rules.map((r) => {
+        const contract = getContractFromDescriptor(r);
+        return {
+          id: r.id,
+          description: r.description,
+          eventTypes: r.eventTypes,
+          hasContract: !!contract,
+          contract: includeContracts ? contract : void 0,
+          meta: r.meta
+        };
+      });
+      const constraintInfos = constraints.map((c) => {
+        const contract = getContractFromDescriptor(c);
+        return {
+          id: c.id,
+          description: c.description,
+          hasContract: !!contract,
+          contract: includeContracts ? contract : void 0,
+          meta: c.meta
+        };
+      });
+      const output = {
+        rules: ruleInfos,
+        constraints: constraintInfos,
+        summary: {
+          totalRules: ruleInfos.length,
+          totalConstraints: constraintInfos.length,
+          rulesWithContracts: ruleInfos.filter((r) => r.hasContract).length,
+          constraintsWithContracts: constraintInfos.filter((c) => c.hasContract).length
+        }
+      };
+      return { content: [{ type: "text", text: JSON.stringify(output, null, 2) }] };
+    }
+  );
+  server2.tool(
+    "praxis.evaluate",
+    "Run a specific rule against given events and return the result",
+    {
+      ruleId: import_zod.z.string().describe("The rule ID to evaluate"),
+      events: import_zod.z.array(import_zod.z.object({
+        tag: import_zod.z.string(),
+        payload: import_zod.z.unknown()
+      })).describe("Events to process through the rule")
+    },
+    async (params) => {
+      const rule = registry.getRule(params.ruleId);
+      if (!rule) {
+        return {
+          content: [{ type: "text", text: JSON.stringify({ error: `Rule "${params.ruleId}" not found` }) }]
+        };
+      }
+      const state = engine.getState();
+      const stateWithEvents = { ...state, events: params.events };
+      try {
+        const rawResult = rule.impl(stateWithEvents, params.events);
+        let output;
+        if (rawResult instanceof RuleResult) {
+          output = {
+            ruleId: params.ruleId,
+            resultKind: rawResult.kind,
+            facts: rawResult.facts,
+            retractedTags: rawResult.retractTags,
+            reason: rawResult.reason,
+            diagnostics: []
+          };
+        } else if (Array.isArray(rawResult)) {
+          output = {
+            ruleId: params.ruleId,
+            resultKind: "emit",
+            facts: rawResult,
+            retractedTags: [],
+            diagnostics: []
+          };
+        } else {
+          output = {
+            ruleId: params.ruleId,
+            resultKind: "noop",
+            facts: [],
+            retractedTags: [],
+            diagnostics: []
+          };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(output, null, 2) }] };
+      } catch (error) {
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify({
+              error: `Rule evaluation failed: ${error instanceof Error ? error.message : String(error)}`,
+              ruleId: params.ruleId
+            })
+          }]
+        };
+      }
+    }
+  );
+  server2.tool(
+    "praxis.audit",
+    "Run completeness audit against a manifest and return the report",
+    {
+      branches: import_zod.z.array(import_zod.z.object({
+        location: import_zod.z.string(),
+        condition: import_zod.z.string(),
+        kind: import_zod.z.enum(["domain", "invariant", "ui", "transport", "wiring", "transform"]),
+        coveredBy: import_zod.z.string().nullable(),
+        note: import_zod.z.string().optional()
+      })).describe("Logic branches to audit"),
+      stateFields: import_zod.z.array(import_zod.z.object({
+        source: import_zod.z.string(),
+        field: import_zod.z.string(),
+        inContext: import_zod.z.boolean(),
+        usedByRule: import_zod.z.boolean()
+      })).describe("State fields to check context coverage"),
+      transitions: import_zod.z.array(import_zod.z.object({
+        description: import_zod.z.string(),
+        eventTag: import_zod.z.string().nullable(),
+        location: import_zod.z.string()
+      })).describe("State transitions to check event coverage"),
+      rulesNeedingContracts: import_zod.z.array(import_zod.z.string()).describe("Rule IDs that should have contracts"),
+      threshold: import_zod.z.number().optional().describe("Minimum passing score (default: 90)")
+    },
+    async (params) => {
+      const rulesWithContracts = registry.getAllRules().filter((r) => getContractFromDescriptor(r)).map((r) => r.id);
+      const report = auditCompleteness(
+        {
+          branches: params.branches,
+          stateFields: params.stateFields,
+          transitions: params.transitions,
+          rulesNeedingContracts: params.rulesNeedingContracts
+        },
+        registry.getRuleIds(),
+        registry.getConstraintIds(),
+        rulesWithContracts,
+        { threshold: params.threshold }
+      );
+      const output = {
+        report,
+        formatted: formatReport(report)
+      };
+      return { content: [{ type: "text", text: JSON.stringify(output, null, 2) }] };
+    }
+  );
+  server2.tool(
+    "praxis.suggest",
+    "Given a gap or description, suggest rules/constraints to add",
+    {
+      gap: import_zod.z.string().describe("Description of the gap or failing expectation"),
+      context: import_zod.z.record(import_zod.z.string(), import_zod.z.unknown()).optional().describe("Current context for suggestions")
+    },
+    async (params) => {
+      const existingRules = registry.getAllRules();
+      const _constraints = registry.getAllConstraints();
+      void _constraints;
+      const suggestions = [];
+      const gapLower = params.gap.toLowerCase();
+      const relatedRules = existingRules.filter(
+        (r) => r.description.toLowerCase().includes(gapLower) || gapLower.includes(r.id.toLowerCase())
+      );
+      if (relatedRules.length > 0) {
+        for (const rule of relatedRules) {
+          suggestions.push({
+            type: "constraint",
+            id: `${rule.id}/guard`,
+            description: `Add a constraint to guard the behavior described by rule "${rule.id}"`,
+            rationale: `Rule "${rule.id}" (${rule.description}) exists but may not fully cover: ${params.gap}`
+          });
+        }
+      }
+      const invariantTerms = ["must", "never", "always", "require", "valid", "invalid", "prevent"];
+      if (invariantTerms.some((t) => gapLower.includes(t))) {
+        suggestions.push({
+          type: "constraint",
+          id: suggestId(params.gap, "constraint"),
+          description: `Constraint: ${params.gap}`,
+          rationale: "Gap description contains invariant language \u2014 a constraint would encode this guarantee"
+        });
+      }
+      const ruleTerms = ["when", "if", "show", "emit", "trigger", "display", "update"];
+      if (ruleTerms.some((t) => gapLower.includes(t))) {
+        suggestions.push({
+          type: "rule",
+          id: suggestId(params.gap, "rule"),
+          description: `Rule: ${params.gap}`,
+          rationale: "Gap description contains conditional behavior \u2014 a rule would implement this logic"
+        });
+      }
+      const contractGaps = registry.getContractGaps();
+      if (contractGaps.length > 0) {
+        const relatedGaps = contractGaps.filter(
+          (g) => gapLower.includes(g.ruleId.toLowerCase())
+        );
+        for (const g of relatedGaps) {
+          suggestions.push({
+            type: "contract",
+            id: g.ruleId,
+            description: `Add contract for "${g.ruleId}" \u2014 missing: ${g.missing.join(", ")}`,
+            rationale: `Related rule "${g.ruleId}" lacks a contract, which could prevent this gap`
+          });
+        }
+      }
+      const eventTerms = ["transition", "change", "happen", "occur", "fire", "dispatch"];
+      if (eventTerms.some((t) => gapLower.includes(t))) {
+        suggestions.push({
+          type: "event",
+          id: suggestId(params.gap, "event"),
+          description: `Event for: ${params.gap}`,
+          rationale: "Gap description suggests a state transition \u2014 an event would make it observable"
+        });
+      }
+      if (suggestions.length === 0) {
+        suggestions.push({
+          type: "rule",
+          id: suggestId(params.gap, "rule"),
+          description: `Rule: ${params.gap}`,
+          rationale: "No existing rules or constraints cover this gap \u2014 a new rule is recommended"
+        });
+      }
+      const output = { suggestions };
+      return { content: [{ type: "text", text: JSON.stringify(output, null, 2) }] };
+    }
+  );
+  server2.tool(
+    "praxis.facts",
+    "Get the current fact state of the engine",
+    {},
+    async () => {
+      const facts = engine.getFacts();
+      const output = {
+        facts,
+        count: facts.length
+      };
+      return { content: [{ type: "text", text: JSON.stringify(output, null, 2) }] };
+    }
+  );
+  server2.tool(
+    "praxis.step",
+    "Step the engine with events and return the new state",
+    {
+      events: import_zod.z.array(import_zod.z.object({
+        tag: import_zod.z.string(),
+        payload: import_zod.z.unknown()
+      })).describe("Events to process")
+    },
+    async (params) => {
+      const result = engine.step(params.events);
+      const output = {
+        facts: result.state.facts,
+        diagnostics: result.diagnostics,
+        factCount: result.state.facts.length
+      };
+      return { content: [{ type: "text", text: JSON.stringify(output, null, 2) }] };
+    }
+  );
+  server2.tool(
+    "praxis.contracts",
+    "List all contracts with their coverage status",
+    {
+      filter: import_zod.z.string().optional().describe("Filter by rule/constraint ID (substring match)")
+    },
+    async (params) => {
+      const rules = registry.getAllRules();
+      const constraints = registry.getAllConstraints();
+      let contracts = [
+        ...rules.map((r) => ({
+          ruleId: r.id,
+          hasContract: !!getContractFromDescriptor(r),
+          contract: getContractFromDescriptor(r),
+          type: "rule"
+        })),
+        ...constraints.map((c) => ({
+          ruleId: c.id,
+          hasContract: !!getContractFromDescriptor(c),
+          contract: getContractFromDescriptor(c),
+          type: "constraint"
+        }))
+      ];
+      if (params.filter) {
+        contracts = contracts.filter((c) => c.ruleId.includes(params.filter));
+      }
+      const total = contracts.length;
+      const withContracts = contracts.filter((c) => c.hasContract).length;
+      const output = {
+        contracts,
+        coverage: {
+          total,
+          withContracts,
+          percentage: total > 0 ? Math.round(withContracts / total * 100) : 100
+        }
+      };
+      return { content: [{ type: "text", text: JSON.stringify(output, null, 2) }] };
+    }
+  );
+  return {
+    /** The underlying MCP server instance */
+    mcpServer: server2,
+    /** The underlying Praxis engine */
+    engine,
+    /** Start the server on stdio transport */
+    async start() {
+      const transport = new import_stdio.StdioServerTransport();
+      await server2.connect(transport);
+    }
+  };
+}
+function suggestId(description, type) {
+  const slug = description.toLowerCase().replace(/[^a-z0-9\s]/g, "").trim().split(/\s+/).slice(0, 3).join("-");
+  return `suggested/${type}/${slug}`;
+}
+var import_mcp, import_stdio, import_zod;
+var init_server = __esm({
+  "src/mcp/server.ts"() {
+    "use strict";
+    import_mcp = require("@modelcontextprotocol/sdk/server/mcp.js");
+    import_stdio = require("@modelcontextprotocol/sdk/server/stdio.js");
+    import_zod = require("zod");
+    init_engine();
+    init_rule_result();
+    init_completeness();
+    init_types2();
+  }
+});
+
+// src/core/rules.ts
+var rules_exports = {};
+__export(rules_exports, {
+  PraxisRegistry: () => PraxisRegistry
+});
+var PraxisRegistry;
+var init_rules = __esm({
+  "src/core/rules.ts"() {
+    "use strict";
+    PraxisRegistry = class {
+      rules = /* @__PURE__ */ new Map();
+      constraints = /* @__PURE__ */ new Map();
+      compliance;
+      contractGaps = [];
+      constructor(options = {}) {
+        const defaultEnabled = typeof process !== "undefined" ? process.env?.NODE_ENV !== "production" : false;
+        this.compliance = {
+          enabled: defaultEnabled,
+          requiredFields: ["behavior", "examples", "invariants"],
+          missingSeverity: "warning",
+          ...options.compliance
+        };
+      }
+      /**
+       * Register a rule
+       */
+      registerRule(descriptor) {
+        if (this.rules.has(descriptor.id)) {
+          throw new Error(`Rule with id "${descriptor.id}" already registered`);
+        }
+        this.rules.set(descriptor.id, descriptor);
+        this.trackContractCompliance(descriptor.id, descriptor);
+      }
+      /**
+       * Register a constraint
+       */
+      registerConstraint(descriptor) {
+        if (this.constraints.has(descriptor.id)) {
+          throw new Error(`Constraint with id "${descriptor.id}" already registered`);
+        }
+        this.constraints.set(descriptor.id, descriptor);
+        this.trackContractCompliance(descriptor.id, descriptor);
+      }
+      /**
+       * Register a module (all its rules and constraints)
+       */
+      registerModule(module2) {
+        for (const rule of module2.rules) {
+          this.registerRule(rule);
+        }
+        for (const constraint of module2.constraints) {
+          this.registerConstraint(constraint);
+        }
+      }
+      /**
+       * Get a rule by ID
+       */
+      getRule(id) {
+        return this.rules.get(id);
+      }
+      /**
+       * Get a constraint by ID
+       */
+      getConstraint(id) {
+        return this.constraints.get(id);
+      }
+      /**
+       * Get all registered rule IDs
+       */
+      getRuleIds() {
+        return Array.from(this.rules.keys());
+      }
+      /**
+       * Get all registered constraint IDs
+       */
+      getConstraintIds() {
+        return Array.from(this.constraints.keys());
+      }
+      /**
+       * Get all rules
+       */
+      getAllRules() {
+        return Array.from(this.rules.values());
+      }
+      /**
+       * Get all constraints
+       */
+      getAllConstraints() {
+        return Array.from(this.constraints.values());
+      }
+      /**
+      * Get collected contract gaps from registration-time validation.
+      */
+      getContractGaps() {
+        return [...this.contractGaps];
+      }
+      /**
+      * Clear collected contract gaps.
+      */
+      clearContractGaps() {
+        this.contractGaps = [];
+      }
+      trackContractCompliance(id, descriptor) {
+        if (!this.compliance.enabled) {
+          return;
+        }
+        const gaps = this.validateDescriptorContract(id, descriptor);
+        for (const gap of gaps) {
+          this.contractGaps.push(gap);
+          if (this.compliance.onGap) {
+            this.compliance.onGap(gap);
+          } else {
+            const label = gap.severity === "error" ? "ERROR" : gap.severity === "warning" ? "WARN" : "INFO";
+            console.warn(`[Praxis][${label}] Contract gap for "${gap.ruleId}": missing ${gap.missing.join(", ")}`);
+          }
+        }
+      }
+      validateDescriptorContract(id, descriptor) {
+        const requiredFields = this.compliance.requiredFields ?? ["behavior", "examples", "invariants"];
+        const missingSeverity = this.compliance.missingSeverity ?? "warning";
+        const contract = descriptor.contract ?? (descriptor.meta?.contract && typeof descriptor.meta.contract === "object" ? descriptor.meta.contract : void 0);
+        if (!contract) {
+          return [
+            {
+              ruleId: id,
+              missing: ["contract"],
+              severity: missingSeverity,
+              message: `Contract missing for "${id}"`
+            }
+          ];
+        }
+        const missing = [];
+        if (requiredFields.includes("behavior") && (!contract.behavior || contract.behavior.trim() === "")) {
+          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 (missing.length === 0) {
+          return [];
+        }
+        return [
+          {
+            ruleId: id,
+            missing,
+            severity: "warning",
+            message: `Contract for "${id}" is incomplete: missing ${missing.join(", ")}`
+          }
+        ];
+      }
+    };
+  }
+});
+
 // node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/lib/typescript.js
 var require_typescript = __commonJS({
   "node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/lib/typescript.js"(exports2, module2) {
@@ -214475,217 +215534,6 @@ var init_verify = __esm({
   }
 });
 
-// src/core/rules.ts
-var PraxisRegistry;
-var init_rules = __esm({
-  "src/core/rules.ts"() {
-    "use strict";
-    PraxisRegistry = class {
-      rules = /* @__PURE__ */ new Map();
-      constraints = /* @__PURE__ */ new Map();
-      compliance;
-      contractGaps = [];
-      constructor(options = {}) {
-        const defaultEnabled = typeof process !== "undefined" ? process.env?.NODE_ENV !== "production" : false;
-        this.compliance = {
-          enabled: defaultEnabled,
-          requiredFields: ["behavior", "examples", "invariants"],
-          missingSeverity: "warning",
-          ...options.compliance
-        };
-      }
-      /**
-       * Register a rule
-       */
-      registerRule(descriptor) {
-        if (this.rules.has(descriptor.id)) {
-          throw new Error(`Rule with id "${descriptor.id}" already registered`);
-        }
-        this.rules.set(descriptor.id, descriptor);
-        this.trackContractCompliance(descriptor.id, descriptor);
-      }
-      /**
-       * Register a constraint
-       */
-      registerConstraint(descriptor) {
-        if (this.constraints.has(descriptor.id)) {
-          throw new Error(`Constraint with id "${descriptor.id}" already registered`);
-        }
-        this.constraints.set(descriptor.id, descriptor);
-        this.trackContractCompliance(descriptor.id, descriptor);
-      }
-      /**
-       * Register a module (all its rules and constraints)
-       */
-      registerModule(module2) {
-        for (const rule of module2.rules) {
-          this.registerRule(rule);
-        }
-        for (const constraint of module2.constraints) {
-          this.registerConstraint(constraint);
-        }
-      }
-      /**
-       * Get a rule by ID
-       */
-      getRule(id) {
-        return this.rules.get(id);
-      }
-      /**
-       * Get a constraint by ID
-       */
-      getConstraint(id) {
-        return this.constraints.get(id);
-      }
-      /**
-       * Get all registered rule IDs
-       */
-      getRuleIds() {
-        return Array.from(this.rules.keys());
-      }
-      /**
-       * Get all registered constraint IDs
-       */
-      getConstraintIds() {
-        return Array.from(this.constraints.keys());
-      }
-      /**
-       * Get all rules
-       */
-      getAllRules() {
-        return Array.from(this.rules.values());
-      }
-      /**
-       * Get all constraints
-       */
-      getAllConstraints() {
-        return Array.from(this.constraints.values());
-      }
-      /**
-      * Get collected contract gaps from registration-time validation.
-      */
-      getContractGaps() {
-        return [...this.contractGaps];
-      }
-      /**
-      * Clear collected contract gaps.
-      */
-      clearContractGaps() {
-        this.contractGaps = [];
-      }
-      trackContractCompliance(id, descriptor) {
-        if (!this.compliance.enabled) {
-          return;
-        }
-        const gaps = this.validateDescriptorContract(id, descriptor);
-        for (const gap of gaps) {
-          this.contractGaps.push(gap);
-          if (this.compliance.onGap) {
-            this.compliance.onGap(gap);
-          } else {
-            const label = gap.severity === "error" ? "ERROR" : gap.severity === "warning" ? "WARN" : "INFO";
-            console.warn(`[Praxis][${label}] Contract gap for "${gap.ruleId}": missing ${gap.missing.join(", ")}`);
-          }
-        }
-      }
-      validateDescriptorContract(id, descriptor) {
-        const requiredFields = this.compliance.requiredFields ?? ["behavior", "examples", "invariants"];
-        const missingSeverity = this.compliance.missingSeverity ?? "warning";
-        const contract = descriptor.contract ?? (descriptor.meta?.contract && typeof descriptor.meta.contract === "object" ? descriptor.meta.contract : void 0);
-        if (!contract) {
-          return [
-            {
-              ruleId: id,
-              missing: ["contract"],
-              severity: missingSeverity,
-              message: `Contract missing for "${id}"`
-            }
-          ];
-        }
-        const missing = [];
-        if (requiredFields.includes("behavior") && (!contract.behavior || contract.behavior.trim() === "")) {
-          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 (missing.length === 0) {
-          return [];
-        }
-        return [
-          {
-            ruleId: id,
-            missing,
-            severity: "warning",
-            message: `Contract for "${id}" is incomplete: missing ${missing.join(", ")}`
-          }
-        ];
-      }
-    };
-  }
-});
-
-// src/decision-ledger/types.ts
-function isContract(obj) {
-  if (typeof obj !== "object" || obj === null) {
-    return false;
-  }
-  const contract = obj;
-  return typeof contract.ruleId === "string" && typeof contract.behavior === "string" && Array.isArray(contract.examples) && contract.examples.length > 0 && contract.examples.every(
-    (ex) => typeof ex === "object" && ex !== null && typeof ex.given === "string" && typeof ex.when === "string" && typeof ex.then === "string"
-  ) && Array.isArray(contract.invariants) && contract.invariants.every((inv) => typeof inv === "string");
-}
-function defineContract(options) {
-  if (options.examples.length === 0) {
-    throw new Error("Contract must have at least one example");
-  }
-  if (options.assumptions) {
-    for (const assumption of options.assumptions) {
-      if (assumption.confidence < 0 || assumption.confidence > 1) {
-        throw new Error(
-          `Assumption '${assumption.id}' has invalid confidence value ${assumption.confidence}. Must be between 0.0 and 1.0`
-        );
-      }
-    }
-  }
-  return {
-    ruleId: options.ruleId,
-    behavior: options.behavior,
-    examples: options.examples,
-    invariants: options.invariants,
-    assumptions: options.assumptions,
-    references: options.references,
-    version: options.version || "1.0.0",
-    timestamp: (/* @__PURE__ */ new Date()).toISOString()
-  };
-}
-function getContract(meta) {
-  if (!meta || !meta.contract) {
-    return void 0;
-  }
-  if (isContract(meta.contract)) {
-    return meta.contract;
-  }
-  return void 0;
-}
-function getContractFromDescriptor(descriptor) {
-  if (!descriptor) {
-    return void 0;
-  }
-  if (descriptor.contract && isContract(descriptor.contract)) {
-    return descriptor.contract;
-  }
-  return getContract(descriptor.meta);
-}
-var init_types2 = __esm({
-  "src/decision-ledger/types.ts"() {
-    "use strict";
-  }
-});
-
 // src/dsl/index.ts
 function defineFact(tag) {
   return {
@@ -217810,6 +218658,25 @@ cloudCmd.command("usage").description("View cloud usage metrics").action(async (
     process.exit(1);
   }
 });
+program.command("mcp").description("Start the Praxis MCP server (Model Context Protocol) for AI assistant integration").option("--name <name>", "Server name", "@plures/praxis").option("--version <version>", "Server version", "1.0.0").action(async (options) => {
+  try {
+    const { createPraxisMcpServer: createPraxisMcpServer2 } = await Promise.resolve().then(() => (init_server(), server_exports));
+    const { PraxisRegistry: PraxisRegistry2 } = await Promise.resolve().then(() => (init_rules(), rules_exports));
+    const registry = new PraxisRegistry2({
+      compliance: { enabled: false }
+    });
+    const server2 = createPraxisMcpServer2({
+      name: options.name,
+      version: options.version,
+      initialContext: {},
+      registry
+    });
+    await server2.start();
+  } catch (error) {
+    console.error("Error starting MCP server:", error);
+    process.exit(1);
+  }
+});
 program.command("verify <type>").description("Verify project implementation (e.g., implementation)").option("-d, --detailed", "Show detailed analysis").action(async (type, options) => {
   try {
     const { verify: verify2 } = await Promise.resolve().then(() => (init_verify(), verify_exports));