@plures/praxis 1.2.0 → 1.2.11

package/dist/node/index.cjs

@@ -246,7 +246,8 @@ __export(adapter_exports, {
   InMemoryPraxisDB: () => InMemoryPraxisDB,
   PluresDBPraxisAdapter: () => PluresDBPraxisAdapter,
   createInMemoryDB: () => createInMemoryDB,
-  createPluresDB: () => createPluresDB
+  createPluresDB: () => createPluresDB,
+  createPraxisLocalFirst: () => createPraxisLocalFirst
 });
 function createInMemoryDB() {
   return new InMemoryPraxisDB();
@@ -254,6 +255,16 @@ function createInMemoryDB() {
 function createPluresDB(config) {
   return new PluresDBPraxisAdapter(config);
 }
+async function createPraxisLocalFirst(options = {}) {
+  const { pollInterval, ...localOptions } = options;
+  const mod = await import("@plures/pluresdb/local-first");
+  const LocalFirstCtor = mod.PluresDBLocalFirst ?? mod.default;
+  if (!LocalFirstCtor) {
+    throw new Error("Failed to load PluresDBLocalFirst from @plures/pluresdb/local-first");
+  }
+  const db = new LocalFirstCtor(localOptions);
+  return new PluresDBPraxisAdapter({ db, pollInterval });
+}
 var InMemoryPraxisDB, PluresDBPraxisAdapter;
 var init_adapter = __esm({
   "src/core/pluresdb/adapter.ts"() {
@@ -391,7 +402,14 @@ var init_adapter = __esm({
 // src/index.ts
 var src_exports = {};
 __export(src_exports, {
+  AcknowledgeContractGap: () => AcknowledgeContractGap,
   ActorManager: () => ActorManager,
+  BehaviorLedger: () => BehaviorLedger,
+  ContractAdded: () => ContractAdded,
+  ContractGapAcknowledged: () => ContractGapAcknowledged,
+  ContractMissing: () => ContractMissing,
+  ContractUpdated: () => ContractUpdated,
+  ContractValidated: () => ContractValidated,
   FrameworkAgnosticReactiveEngine: () => ReactiveLogicEngine2,
   InMemoryPraxisDB: () => InMemoryPraxisDB,
   LogicEngine: () => LogicEngine,
@@ -406,6 +424,7 @@ __export(src_exports, {
   RegistryIntrospector: () => RegistryIntrospector,
   StateDocsGenerator: () => StateDocsGenerator,
   TerminalAdapter: () => TerminalAdapter,
+  ValidateContracts: () => ValidateContracts,
   attachAllIntegrations: () => attachAllIntegrations,
   attachTauriToEngine: () => attachTauriToEngine,
   attachToEngine: () => attachToEngine,
@@ -413,6 +432,7 @@ __export(src_exports, {
   canvasToMermaid: () => canvasToMermaid,
   canvasToSchema: () => canvasToSchema,
   canvasToYaml: () => canvasToYaml,
+  createBehaviorLedger: () => createBehaviorLedger,
   createCanvasEditor: () => createCanvasEditor,
   createFrameworkAgnosticReactiveEngine: () => createReactiveEngine2,
   createInMemoryDB: () => createInMemoryDB,
@@ -424,6 +444,7 @@ __export(src_exports, {
   createPluresDBGenerator: () => createPluresDBGenerator,
   createPraxisDBStore: () => createPraxisDBStore,
   createPraxisEngine: () => createPraxisEngine,
+  createPraxisLocalFirst: () => createPraxisLocalFirst,
   createReactiveEngine: () => createReactiveEngine,
   createSchemaRegistry: () => createSchemaRegistry,
   createSchemaTemplate: () => createSchemaTemplate,
@@ -434,6 +455,7 @@ __export(src_exports, {
   createUnifiedApp: () => createUnifiedApp,
   createUnumAdapter: () => createUnumAdapter,
   defineConstraint: () => defineConstraint,
+  defineContract: () => defineContract,
   defineEvent: () => defineEvent,
   defineFact: () => defineFact,
   defineModule: () => defineModule,
@@ -442,12 +464,17 @@ __export(src_exports, {
   filterFacts: () => filterFacts,
   findEvent: () => findEvent,
   findFact: () => findFact,
+  formatValidationReport: () => formatValidationReport,
+  formatValidationReportJSON: () => formatValidationReportJSON,
+  formatValidationReportSARIF: () => formatValidationReportSARIF,
   generateDocs: () => generateDocs,
   generateId: () => generateId,
   generateTauriConfig: () => generateTauriConfig,
+  getContract: () => getContract,
   getEventPath: () => getEventPath,
   getFactPath: () => getFactPath,
   getSchemaPath: () => getSchemaPath,
+  isContract: () => isContract,
   loadSchema: () => loadSchema,
   loadSchemaFromFile: () => loadSchemaFromFile,
   loadSchemaFromJson: () => loadSchemaFromJson,
@@ -455,6 +482,7 @@ __export(src_exports, {
   registerSchema: () => registerSchema,
   runTerminalCommand: () => runTerminalCommand,
   schemaToCanvas: () => schemaToCanvas,
+  validateContracts: () => validateContracts,
   validateForGeneration: () => validateForGeneration,
   validateSchema: () => validateSchema,
   validateWithGuardian: () => validateWithGuardian
@@ -466,6 +494,17 @@ init_protocol();
 var 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
    */
@@ -474,6 +513,7 @@ var PraxisRegistry = class {
       throw new Error(`Rule with id "${descriptor.id}" already registered`);
     }
     this.rules.set(descriptor.id, descriptor);
+    this.trackContractCompliance(descriptor.id, descriptor);
   }
   /**
    * Register a constraint
@@ -483,6 +523,7 @@ var PraxisRegistry = class {
       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)
@@ -531,6 +572,69 @@ var PraxisRegistry = class {
   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/index.ts
@@ -1175,19 +1279,25 @@ function defineEvent(tag) {
   };
 }
 function defineRule(options) {
+  const contract = options.contract ?? options.meta?.contract;
+  const meta = contract ? { ...options.meta ?? {}, contract } : options.meta;
   return {
     id: options.id,
     description: options.description,
     impl: options.impl,
-    meta: options.meta
+    contract,
+    meta
   };
 }
 function defineConstraint(options) {
+  const contract = options.contract ?? options.meta?.contract;
+  const meta = contract ? { ...options.meta ?? {}, contract } : options.meta;
   return {
     id: options.id,
     description: options.description,
     impl: options.impl,
-    meta: options.meta
+    contract,
+    meta
   };
 }
 function defineModule(options) {
@@ -1210,6 +1320,461 @@ function findFact(facts, definition) {
   return facts.find(definition.is);
 }
 
+// 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);
+}
+
+// src/decision-ledger/facts-events.ts
+var ContractMissing = defineFact("ContractMissing");
+var ContractValidated = defineFact("ContractValidated");
+var AcknowledgeContractGap = defineEvent("ACKNOWLEDGE_CONTRACT_GAP");
+var ValidateContracts = defineEvent("VALIDATE_CONTRACTS");
+var ContractGapAcknowledged = defineFact("ContractGapAcknowledged");
+var ContractAdded = defineEvent("CONTRACT_ADDED");
+var ContractUpdated = defineEvent("CONTRACT_UPDATED");
+var ContractGapEmitted = defineEvent("CONTRACT_GAP_EMITTED");
+
+// src/decision-ledger/validation.ts
+function validateContracts(registry, options = {}) {
+  const {
+    incompleteSeverity = "warning",
+    requiredFields = ["behavior", "examples"],
+    artifactIndex
+  } = options;
+  const complete = [];
+  const incomplete = [];
+  const missing = [];
+  for (const rule of registry.getAllRules()) {
+    const contract = getContractFromDescriptor(rule);
+    if (!contract) {
+      missing.push(rule.id);
+      if (options.missingSeverity) {
+        incomplete.push({
+          ruleId: rule.id,
+          missing: ["contract"],
+          severity: options.missingSeverity,
+          message: `Rule '${rule.id}' has no contract`
+        });
+      }
+      continue;
+    }
+    const gaps = validateContract(contract, requiredFields, artifactIndex);
+    if (gaps.length > 0) {
+      incomplete.push({
+        ruleId: rule.id,
+        missing: gaps,
+        severity: incompleteSeverity,
+        message: `Rule '${rule.id}' contract is incomplete: missing ${gaps.join(", ")}`
+      });
+    } else {
+      complete.push({ ruleId: rule.id, contract });
+    }
+  }
+  for (const constraint of registry.getAllConstraints()) {
+    const contract = getContractFromDescriptor(constraint);
+    if (!contract) {
+      missing.push(constraint.id);
+      if (options.missingSeverity) {
+        incomplete.push({
+          ruleId: constraint.id,
+          missing: ["contract"],
+          severity: options.missingSeverity,
+          message: `Constraint '${constraint.id}' has no contract`
+        });
+      }
+      continue;
+    }
+    const gaps = validateContract(contract, requiredFields, artifactIndex);
+    if (gaps.length > 0) {
+      incomplete.push({
+        ruleId: constraint.id,
+        missing: gaps,
+        severity: incompleteSeverity,
+        message: `Constraint '${constraint.id}' contract is incomplete: missing ${gaps.join(", ")}`
+      });
+    } else {
+      complete.push({ ruleId: constraint.id, contract });
+    }
+  }
+  const total = registry.getAllRules().length + registry.getAllConstraints().length;
+  return {
+    complete,
+    incomplete,
+    missing,
+    total,
+    timestamp: (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+function validateContract(contract, requiredFields, artifactIndex) {
+  const missing = [];
+  if (requiredFields.includes("behavior") && isFieldEmpty(contract.behavior)) {
+    missing.push("behavior");
+  }
+  if (requiredFields.includes("examples") && (!contract.examples || contract.examples.length === 0)) {
+    missing.push("examples");
+  }
+  if (requiredFields.includes("invariants") && (!contract.invariants || contract.invariants.length === 0)) {
+    missing.push("invariants");
+  }
+  if (artifactIndex?.tests && !artifactIndex.tests.has(contract.ruleId)) {
+    missing.push("tests");
+  }
+  if (artifactIndex?.spec && !artifactIndex.spec.has(contract.ruleId)) {
+    missing.push("spec");
+  }
+  return missing;
+}
+function isFieldEmpty(value) {
+  return !value || value.trim() === "";
+}
+function formatValidationReport(report) {
+  const lines = [];
+  lines.push("Contract Validation Report");
+  lines.push("=".repeat(50));
+  lines.push("");
+  lines.push(`Total: ${report.total}`);
+  lines.push(`Complete: ${report.complete.length}`);
+  lines.push(`Incomplete: ${report.incomplete.length}`);
+  lines.push(`Missing: ${report.missing.length}`);
+  lines.push("");
+  if (report.complete.length > 0) {
+    lines.push("\u2713 Complete Contracts:");
+    for (const { ruleId, contract } of report.complete) {
+      lines.push(`  \u2713 ${ruleId} (v${contract.version || "1.0.0"})`);
+    }
+    lines.push("");
+  }
+  if (report.incomplete.length > 0) {
+    lines.push("\u2717 Incomplete Contracts:");
+    for (const gap of report.incomplete) {
+      const icon = gap.severity === "error" ? "\u2717" : gap.severity === "warning" ? "\u26A0" : "\u2139";
+      lines.push(`  ${icon} ${gap.ruleId} - Missing: ${gap.missing.join(", ")}`);
+      if (gap.message) {
+        lines.push(`     ${gap.message}`);
+      }
+    }
+    lines.push("");
+  }
+  if (report.missing.length > 0) {
+    lines.push("\u2717 No Contract:");
+    for (const ruleId of report.missing) {
+      lines.push(`  \u2717 ${ruleId}`);
+    }
+    lines.push("");
+  }
+  lines.push(`Validated at: ${report.timestamp}`);
+  return lines.join("\n");
+}
+function formatValidationReportJSON(report) {
+  return JSON.stringify(report, null, 2);
+}
+function formatValidationReportSARIF(report) {
+  const results = report.incomplete.map((gap) => {
+    const primaryMissing = gap.missing.length > 0 ? gap.missing[0] : "contract";
+    return {
+      ruleId: `decision-ledger/${primaryMissing}`,
+      level: gap.severity === "error" ? "error" : gap.severity === "warning" ? "warning" : "note",
+      message: {
+        text: gap.message || `Missing: ${gap.missing.join(", ")}`
+      },
+      locations: [
+        {
+          physicalLocation: {
+            artifactLocation: {
+              uri: "registry"
+            },
+            region: {
+              startLine: 1
+            }
+          }
+        }
+      ],
+      properties: {
+        ruleId: gap.ruleId,
+        missing: gap.missing
+      }
+    };
+  });
+  const sarif = {
+    version: "2.1.0",
+    $schema: "https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/Schemata/sarif-schema-2.1.0.json",
+    runs: [
+      {
+        tool: {
+          driver: {
+            name: "Praxis Decision Ledger",
+            version: "1.0.0",
+            informationUri: "https://github.com/plures/praxis",
+            rules: [
+              {
+                id: "decision-ledger/contract",
+                shortDescription: {
+                  text: "Rule or constraint missing contract"
+                }
+              },
+              {
+                id: "decision-ledger/behavior",
+                shortDescription: {
+                  text: "Contract missing behavior description"
+                }
+              },
+              {
+                id: "decision-ledger/examples",
+                shortDescription: {
+                  text: "Contract missing examples"
+                }
+              },
+              {
+                id: "decision-ledger/invariants",
+                shortDescription: {
+                  text: "Contract missing invariants"
+                }
+              },
+              {
+                id: "decision-ledger/tests",
+                shortDescription: {
+                  text: "Contract missing tests"
+                }
+              },
+              {
+                id: "decision-ledger/spec",
+                shortDescription: {
+                  text: "Contract missing spec"
+                }
+              }
+            ]
+          }
+        },
+        results
+      }
+    ]
+  };
+  return JSON.stringify(sarif, null, 2);
+}
+
+// src/decision-ledger/ledger.ts
+var BehaviorLedger = class _BehaviorLedger {
+  entries = [];
+  entryMap = /* @__PURE__ */ new Map();
+  /**
+   * Append a new entry to the ledger.
+   *
+   * @param entry The entry to append
+   * @throws Error if entry ID already exists
+   */
+  append(entry) {
+    if (this.entryMap.has(entry.id)) {
+      throw new Error(`Ledger entry with ID '${entry.id}' already exists`);
+    }
+    if (entry.supersedes) {
+      const superseded = this.entryMap.get(entry.supersedes);
+      if (superseded && superseded.status === "active") {
+        const updatedEntry = {
+          ...superseded,
+          status: "superseded"
+        };
+        this.entryMap.set(entry.supersedes, updatedEntry);
+      }
+    }
+    this.entries.push(entry);
+    this.entryMap.set(entry.id, entry);
+  }
+  /**
+   * Get an entry by ID.
+   *
+   * @param id The entry ID
+   * @returns The entry, or undefined if not found
+   */
+  getEntry(id) {
+    return this.entryMap.get(id);
+  }
+  /**
+   * Get all entries (in order of append) with current status.
+   *
+   * @returns Array of all entries with current status from the map
+   */
+  getAllEntries() {
+    return this.entries.map((entry) => this.entryMap.get(entry.id));
+  }
+  /**
+   * Get entries for a specific rule ID.
+   *
+   * @param ruleId The rule ID
+   * @returns Array of entries for this rule with current status
+   */
+  getEntriesForRule(ruleId) {
+    return this.entries.map((entry) => this.entryMap.get(entry.id)).filter((entry) => entry.contract.ruleId === ruleId);
+  }
+  /**
+   * Get the latest active entry for a rule.
+   *
+   * @param ruleId The rule ID
+   * @returns The latest active entry, or undefined if none
+   */
+  getLatestEntry(ruleId) {
+    const entries = this.getEntriesForRule(ruleId);
+    const activeEntries = entries.filter((entry) => entry.status === "active");
+    if (activeEntries.length === 0) {
+      return void 0;
+    }
+    return activeEntries[activeEntries.length - 1];
+  }
+  /**
+   * Get all active assumptions across all entries.
+   *
+   * @returns Map of assumption ID to assumption
+   */
+  getActiveAssumptions() {
+    const assumptions = /* @__PURE__ */ new Map();
+    for (const entry of this.entries) {
+      const currentEntry = this.entryMap.get(entry.id);
+      if (currentEntry.status !== "active") {
+        continue;
+      }
+      for (const assumption of currentEntry.contract.assumptions || []) {
+        if (assumption.status === "active") {
+          assumptions.set(assumption.id, assumption);
+        }
+      }
+    }
+    return assumptions;
+  }
+  /**
+   * Find assumptions that impact a specific artifact type.
+   *
+   * @param impactType The artifact type ('spec', 'tests', 'code')
+   * @returns Array of assumptions
+   */
+  findAssumptionsByImpact(impactType) {
+    const assumptions = [];
+    for (const entry of this.entries) {
+      const currentEntry = this.entryMap.get(entry.id);
+      if (currentEntry.status !== "active") {
+        continue;
+      }
+      for (const assumption of currentEntry.contract.assumptions || []) {
+        if (assumption.status === "active" && assumption.impacts.includes(impactType)) {
+          assumptions.push(assumption);
+        }
+      }
+    }
+    return assumptions;
+  }
+  /**
+   * Get ledger statistics.
+   */
+  getStats() {
+    const currentEntries = this.entries.map((e) => this.entryMap.get(e.id));
+    const active = currentEntries.filter((e) => e.status === "active").length;
+    const superseded = currentEntries.filter((e) => e.status === "superseded").length;
+    const deprecated = currentEntries.filter((e) => e.status === "deprecated").length;
+    const uniqueRules = new Set(currentEntries.map((e) => e.contract.ruleId)).size;
+    return {
+      totalEntries: this.entries.length,
+      activeEntries: active,
+      supersededEntries: superseded,
+      deprecatedEntries: deprecated,
+      uniqueRules
+    };
+  }
+  /**
+   * Export ledger as JSON.
+   *
+   * @returns JSON string with current entry status
+   */
+  toJSON() {
+    return JSON.stringify(
+      {
+        version: "1.0.0",
+        // Export entries with current status from the map
+        entries: this.entries.map((entry) => this.entryMap.get(entry.id)),
+        stats: this.getStats()
+      },
+      null,
+      2
+    );
+  }
+  /**
+   * Import ledger from JSON.
+   * 
+   * Note: The JSON must contain entries in the order they were originally appended.
+   * If a superseding entry appears before the entry it supersedes, the superseding
+   * logic will not work correctly. The toJSON method preserves this order.
+   *
+   * @param json The JSON string
+   * @returns A new BehaviorLedger instance
+   */
+  static fromJSON(json) {
+    const data = JSON.parse(json);
+    const ledger = new _BehaviorLedger();
+    for (const entry of data.entries || []) {
+      ledger.append(entry);
+    }
+    return ledger;
+  }
+};
+function createBehaviorLedger() {
+  return new BehaviorLedger();
+}
+
+// src/decision-ledger/logic-ledger.ts
+var import_node_crypto = require("crypto");
+var import_node_fs = require("fs");
+var import_node_path = __toESM(require("path"), 1);
+
+// src/decision-ledger/scanner.ts
+var import_node_fs2 = require("fs");
+var import_node_path2 = __toESM(require("path"), 1);
+
 // src/runtime/terminal-adapter.ts
 async function defaultExecutor(command, options) {
   try {
@@ -1330,15 +1895,15 @@ var TerminalAdapter = class {
    * @param path - PluresDB path for storing results
    * @param data - Data to sync
    */
-  async syncToPluresDB(path, data) {
+  async syncToPluresDB(path3, data) {
     if (!this.db) return;
     try {
-      await this.db.set(path, {
+      await this.db.set(path3, {
         ...data,
         nodeId: this.state.nodeId,
         syncedAt: Date.now()
       });
-      const historyPath = `${path}/history`;
+      const historyPath = `${path3}/history`;
       const historyKey = `${historyPath}/${data.timestamp}`;
       await this.db.set(historyKey, data);
     } catch (error) {
@@ -1807,8 +2372,8 @@ var PraxisDBStore = class {
   async persistFact(fact) {
     const payload = fact.payload;
     const id = payload?.id ?? generateId();
-    const path = getFactPath(fact.tag, id);
-    await this.db.set(path, fact);
+    const path3 = getFactPath(fact.tag, id);
+    await this.db.set(path3, fact);
   }
   /**
    * Get a fact by tag and id
@@ -1818,8 +2383,8 @@ var PraxisDBStore = class {
    * @returns The fact or undefined if not found
    */
   async getFact(factTag, id) {
-    const path = getFactPath(factTag, id);
-    return this.db.get(path);
+    const path3 = getFactPath(factTag, id);
+    return this.db.get(path3);
   }
   /**
    * Append an event to the event stream
@@ -1829,15 +2394,15 @@ var PraxisDBStore = class {
    * @param event The event to append
    */
   async appendEvent(event) {
-    const path = getEventPath(event.tag);
-    const existingEvents = await this.db.get(path) ?? [];
+    const path3 = getEventPath(event.tag);
+    const existingEvents = await this.db.get(path3) ?? [];
     const entry = {
       event,
       timestamp: Date.now(),
       sequence: existingEvents.length
     };
     const newEvents = [...existingEvents, entry];
-    await this.db.set(path, newEvents);
+    await this.db.set(path3, newEvents);
     await this.triggerRulesForEvents([event]);
   }
   /**
@@ -1852,15 +2417,15 @@ var PraxisDBStore = class {
       eventsByTag.set(event.tag, [...existing, event]);
     }
     for (const [tag, tagEvents] of eventsByTag) {
-      const path = getEventPath(tag);
-      const existingEvents = await this.db.get(path) ?? [];
+      const path3 = getEventPath(tag);
+      const existingEvents = await this.db.get(path3) ?? [];
       let sequence = existingEvents.length;
       const newEntries = tagEvents.map((event) => ({
         event,
         timestamp: Date.now(),
         sequence: sequence++
       }));
-      await this.db.set(path, [...existingEvents, ...newEntries]);
+      await this.db.set(path3, [...existingEvents, ...newEntries]);
     }
     await this.triggerRulesForEvents(events);
   }
@@ -1872,8 +2437,8 @@ var PraxisDBStore = class {
    * @returns Array of event stream entries
    */
   async getEvents(eventTag, options) {
-    const path = getEventPath(eventTag);
-    const events = await this.db.get(path) ?? [];
+    const path3 = getEventPath(eventTag);
+    const events = await this.db.get(path3) ?? [];
     let result = events;
     if (options?.since !== void 0) {
       const sinceTimestamp = options.since;
@@ -1892,7 +2457,7 @@ var PraxisDBStore = class {
    * @returns Unsubscribe function
    */
   watchFacts(factTag, callback) {
-    const path = getFactPath(factTag);
+    const path3 = getFactPath(factTag);
     if (!this.factWatchers.has(factTag)) {
       this.factWatchers.set(factTag, /* @__PURE__ */ new Set());
     }
@@ -1900,7 +2465,7 @@ var PraxisDBStore = class {
     if (watchers) {
       watchers.add(callback);
     }
-    const unsubscribe = this.db.watch(path, (fact) => {
+    const unsubscribe = this.db.watch(path3, (fact) => {
       callback([fact]);
     });
     this.subscriptions.push(unsubscribe);
@@ -2024,13 +2589,13 @@ var PraxisSchemaRegistry = class {
    * @param schema The schema to register
    */
   async register(schema) {
-    const path = getSchemaPath(schema.name);
+    const path3 = getSchemaPath(schema.name);
     const storedSchema = {
       schema,
       registeredAt: Date.now(),
       version: schema.version
     };
-    await this.db.set(path, storedSchema);
+    await this.db.set(path3, storedSchema);
   }
   /**
    * Get a schema by name
@@ -2039,8 +2604,8 @@ var PraxisSchemaRegistry = class {
    * @returns The stored schema or undefined if not found
    */
   async get(schemaName) {
-    const path = getSchemaPath(schemaName);
-    return this.db.get(path);
+    const path3 = getSchemaPath(schemaName);
+    return this.db.get(path3);
   }
   /**
    * Check if a schema is registered
@@ -3348,29 +3913,29 @@ function createMockTauriBridge() {
       tauriVersion: "mock"
     },
     fs: {
-      async readFile(path) {
-        const data = storage.get(path);
+      async readFile(path3) {
+        const data = storage.get(path3);
         if (data instanceof Uint8Array) return data;
-        throw new Error(`File not found: ${path}`);
+        throw new Error(`File not found: ${path3}`);
       },
-      async readTextFile(path) {
-        const data = storage.get(path);
+      async readTextFile(path3) {
+        const data = storage.get(path3);
         if (typeof data === "string") return data;
-        throw new Error(`File not found: ${path}`);
+        throw new Error(`File not found: ${path3}`);
       },
-      async writeFile(path, data) {
-        storage.set(path, data);
+      async writeFile(path3, data) {
+        storage.set(path3, data);
       },
-      async writeTextFile(path, data) {
-        storage.set(path, data);
+      async writeTextFile(path3, data) {
+        storage.set(path3, data);
       },
-      async exists(path) {
-        return storage.has(path);
+      async exists(path3) {
+        return storage.has(path3);
       },
       async mkdir(_path, _options) {
       },
-      async remove(path, _options) {
-        storage.delete(path);
+      async remove(path3, _options) {
+        storage.delete(path3);
       },
       async rename(oldPath, newPath) {
         const data = storage.get(oldPath);
@@ -3690,7 +4255,14 @@ async function attachAllIntegrations(engine, registry, options = {}) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  AcknowledgeContractGap,
   ActorManager,
+  BehaviorLedger,
+  ContractAdded,
+  ContractGapAcknowledged,
+  ContractMissing,
+  ContractUpdated,
+  ContractValidated,
   FrameworkAgnosticReactiveEngine,
   InMemoryPraxisDB,
   LogicEngine,
@@ -3705,6 +4277,7 @@ async function attachAllIntegrations(engine, registry, options = {}) {
   RegistryIntrospector,
   StateDocsGenerator,
   TerminalAdapter,
+  ValidateContracts,
   attachAllIntegrations,
   attachTauriToEngine,
   attachToEngine,
@@ -3712,6 +4285,7 @@ async function attachAllIntegrations(engine, registry, options = {}) {
   canvasToMermaid,
   canvasToSchema,
   canvasToYaml,
+  createBehaviorLedger,
   createCanvasEditor,
   createFrameworkAgnosticReactiveEngine,
   createInMemoryDB,
@@ -3723,6 +4297,7 @@ async function attachAllIntegrations(engine, registry, options = {}) {
   createPluresDBGenerator,
   createPraxisDBStore,
   createPraxisEngine,
+  createPraxisLocalFirst,
   createReactiveEngine,
   createSchemaRegistry,
   createSchemaTemplate,
@@ -3733,6 +4308,7 @@ async function attachAllIntegrations(engine, registry, options = {}) {
   createUnifiedApp,
   createUnumAdapter,
   defineConstraint,
+  defineContract,
   defineEvent,
   defineFact,
   defineModule,
@@ -3741,12 +4317,17 @@ async function attachAllIntegrations(engine, registry, options = {}) {
   filterFacts,
   findEvent,
   findFact,
+  formatValidationReport,
+  formatValidationReportJSON,
+  formatValidationReportSARIF,
   generateDocs,
   generateId,
   generateTauriConfig,
+  getContract,
   getEventPath,
   getFactPath,
   getSchemaPath,
+  isContract,
   loadSchema,
   loadSchemaFromFile,
   loadSchemaFromJson,
@@ -3754,6 +4335,7 @@ async function attachAllIntegrations(engine, registry, options = {}) {
   registerSchema,
   runTerminalCommand,
   schemaToCanvas,
+  validateContracts,
   validateForGeneration,
   validateSchema,
   validateWithGuardian