@plures/praxis 1.2.0 → 1.2.10

package/dist/browser/{reactive-engine.svelte-C9OpcTHf.d.ts → reactive-engine.svelte-9aS0kTa8.d.ts}

@@ -119,6 +119,105 @@ interface PraxisStepResult {
  */
 type PraxisStepFn = (state: PraxisState, events: PraxisEvent[], config: PraxisStepConfig) => PraxisStepResult;
 
+/**
+ * Decision Ledger - Contract Types
+ *
+ * Types for defining and validating contracts for rules and constraints.
+ * All types are JSON-serializable for cross-language compatibility.
+ */
+/**
+ * A single assumption made during contract definition.
+ */
+interface Assumption {
+    /** Stable unique identifier for the assumption */
+    id: string;
+    /** The assumption statement */
+    statement: string;
+    /** Confidence level (0.0 to 1.0) */
+    confidence: number;
+    /** Justification for the assumption */
+    justification: string;
+    /** What this assumption was derived from */
+    derivedFrom?: string;
+    /** What artifacts this assumption impacts */
+    impacts: Array<'spec' | 'tests' | 'code'>;
+    /** Current status of the assumption */
+    status: 'active' | 'revised' | 'invalidated';
+}
+/**
+ * A reference to external documentation or resources.
+ */
+interface Reference {
+    /** Type of reference (e.g., 'doc', 'ticket', 'issue') */
+    type: string;
+    /** URL to the reference */
+    url?: string;
+    /** Human-readable description */
+    description?: string;
+}
+/**
+ * A Given/When/Then example for a contract.
+ */
+interface Example {
+    /** Initial state or preconditions */
+    given: string;
+    /** Triggering event or action */
+    when: string;
+    /** Expected outcome or postconditions */
+    then: string;
+}
+/**
+ * Contract for a rule or constraint.
+ * Documents the expected behavior, test cases, invariants, and assumptions.
+ */
+interface Contract {
+    /** ID of the rule or constraint this contract applies to */
+    ruleId: string;
+    /** Canonical behavior description */
+    behavior: string;
+    /** Given/When/Then examples (become test vectors) */
+    examples: Example[];
+    /** TLA+-friendly invariants or Praxis-level invariants */
+    invariants: string[];
+    /** Explicit assumptions with confidence levels */
+    assumptions?: Assumption[];
+    /** References to docs, tickets, links */
+    references?: Reference[];
+    /** Contract version (for evolution tracking) */
+    version?: string;
+    /** Timestamp of contract creation */
+    timestamp?: string;
+}
+/**
+ * Severity levels for contract gaps.
+ */
+type Severity = 'warning' | 'error' | 'info';
+/**
+ * Types of missing contract artifacts.
+ */
+/**
+ * Types of artifacts that can be missing from a contract.
+ *
+ * Note: 'tests' and 'spec' are included in this type for future extensibility
+ * and SARIF reporting compatibility, but are not currently validated by the
+ * validateContract function. To check for these, implement custom validation
+ * logic that scans for test files or spec files in your codebase.
+ */
+type MissingArtifact = 'behavior' | 'examples' | 'invariants' | 'tests' | 'spec' | 'contract';
+/**
+ * A gap in contract coverage.
+ */
+interface ContractGap {
+    /** ID of the rule or constraint */
+    ruleId: string;
+    /** What is missing */
+    missing: MissingArtifact[];
+    /** Severity of the gap */
+    severity: Severity;
+    /** Optional human-readable message */
+    message?: string;
+}
+
 /**
  * Rules and Constraints System
  *
@@ -166,6 +265,8 @@ interface RuleDescriptor<TContext = unknown> {
     description: string;
     /** Implementation function */
     impl: RuleFn<TContext>;
+    /** Optional contract for rule behavior */
+    contract?: Contract;
     /** Optional metadata */
     meta?: Record<string, unknown>;
 }
@@ -179,6 +280,8 @@ interface ConstraintDescriptor<TContext = unknown> {
     description: string;
     /** Implementation function */
     impl: ConstraintFn<TContext>;
+    /** Optional contract for constraint behavior */
+    contract?: Contract;
     /** Optional metadata */
     meta?: Record<string, unknown>;
 }
@@ -194,6 +297,25 @@ interface PraxisModule<TContext = unknown> {
     /** Optional module metadata */
     meta?: Record<string, unknown>;
 }
+/**
+ * Compliance validation options for rule/constraint registration.
+ */
+interface RegistryComplianceOptions {
+    /** Enable contract checks during registration (default: true in dev) */
+    enabled?: boolean;
+    /** Required contract fields to be present */
+    requiredFields?: Array<'behavior' | 'examples' | 'invariants'>;
+    /** Severity to use for missing contracts */
+    missingSeverity?: Severity;
+    /** Callback for contract gaps (e.g., to emit facts) */
+    onGap?: (gap: ContractGap) => void;
+}
+/**
+ * PraxisRegistry configuration options.
+ */
+interface PraxisRegistryOptions {
+    compliance?: RegistryComplianceOptions;
+}
 /**
  * Registry for rules and constraints.
  * Maps IDs to their descriptors.
@@ -201,6 +323,9 @@ interface PraxisModule<TContext = unknown> {
 declare class PraxisRegistry<TContext = unknown> {
     private rules;
     private constraints;
+    private readonly compliance;
+    private contractGaps;
+    constructor(options?: PraxisRegistryOptions);
     /**
      * Register a rule
      */
@@ -237,6 +362,16 @@ declare class PraxisRegistry<TContext = unknown> {
      * Get all constraints
      */
     getAllConstraints(): ConstraintDescriptor<TContext>[];
+    /**
+    * Get collected contract gaps from registration-time validation.
+    */
+    getContractGaps(): ContractGap[];
+    /**
+    * Clear collected contract gaps.
+    */
+    clearContractGaps(): void;
+    private trackContractCompliance;
+    private validateDescriptorContract;
 }
 
 /**
@@ -416,4 +551,4 @@ declare class ReactiveLogicEngine<TContext extends object> {
  */
 declare function createReactiveEngine<TContext extends object>(options: ReactiveEngineOptions<TContext>): ReactiveLogicEngine<TContext>;
 
-export { type ConstraintDescriptor as C, LogicEngine as L, type PraxisState as P, type RuleDescriptor as R, type PraxisEvent as a, PraxisRegistry as b, type PraxisFact as c, type RuleFn as d, type ConstraintFn as e, type PraxisModule as f, type PraxisDiagnostics as g, type PraxisStepConfig as h, type PraxisStepResult as i, type PraxisStepFn as j, PRAXIS_PROTOCOL_VERSION as k, type RuleId as l, type ConstraintId as m, type PraxisEngineOptions as n, createPraxisEngine as o, type ReactiveEngineOptions as p, ReactiveLogicEngine as q, createReactiveEngine as r };
+export { type ConstraintDescriptor as C, LogicEngine as L, type PraxisState as P, type RuleDescriptor as R, type PraxisEvent as a, PraxisRegistry as b, type PraxisFact as c, type RuleFn as d, type Contract as e, type ConstraintFn as f, type PraxisModule as g, type PraxisDiagnostics as h, type PraxisStepConfig as i, type PraxisStepResult as j, type PraxisStepFn as k, PRAXIS_PROTOCOL_VERSION as l, type RuleId as m, type ConstraintId as n, type PraxisEngineOptions as o, createPraxisEngine as p, type ReactiveEngineOptions as q, ReactiveLogicEngine as r, createReactiveEngine as s };

package/dist/node/{adapter-K6DOX6XS.js → adapter-75ISSMWD.js}

@@ -2,12 +2,14 @@ import {
   InMemoryPraxisDB,
   PluresDBPraxisAdapter,
   createInMemoryDB,
-  createPluresDB
-} from "./chunk-JQ64KMLN.js";
+  createPluresDB,
+  createPraxisLocalFirst
+} from "./chunk-MBVHLOU2.js";
 import "./chunk-QGM4M3NI.js";
 export {
   InMemoryPraxisDB,
   PluresDBPraxisAdapter,
   createInMemoryDB,
-  createPluresDB
+  createPluresDB,
+  createPraxisLocalFirst
 };

package/dist/node/chunk-5RH7UAQC.js

@@ -0,0 +1,486 @@
+import {
+  getContractFromDescriptor
+} from "./chunk-WZ6B3LZ6.js";
+
+// src/dsl/index.ts
+function defineFact(tag) {
+  return {
+    tag,
+    create(payload) {
+      return { tag, payload };
+    },
+    is(fact) {
+      return fact.tag === tag;
+    }
+  };
+}
+function defineEvent(tag) {
+  return {
+    tag,
+    create(payload) {
+      return { tag, payload };
+    },
+    is(event) {
+      return event.tag === tag;
+    }
+  };
+}
+function defineRule(options) {
+  const contract = options.contract ?? options.meta?.contract;
+  const meta = contract ? { ...options.meta ?? {}, contract } : options.meta;
+  return {
+    id: options.id,
+    description: options.description,
+    impl: options.impl,
+    contract,
+    meta
+  };
+}
+function defineConstraint(options) {
+  const contract = options.contract ?? options.meta?.contract;
+  const meta = contract ? { ...options.meta ?? {}, contract } : options.meta;
+  return {
+    id: options.id,
+    description: options.description,
+    impl: options.impl,
+    contract,
+    meta
+  };
+}
+function defineModule(options) {
+  return {
+    rules: options.rules ?? [],
+    constraints: options.constraints ?? [],
+    meta: options.meta
+  };
+}
+function filterEvents(events, definition) {
+  return events.filter(definition.is);
+}
+function filterFacts(facts, definition) {
+  return facts.filter(definition.is);
+}
+function findEvent(events, definition) {
+  return events.find(definition.is);
+}
+function findFact(facts, definition) {
+  return facts.find(definition.is);
+}
+
+// src/decision-ledger/facts-events.ts
+var ContractMissing = defineFact("ContractMissing");
+var ContractValidated = defineFact("ContractValidated");
+var AcknowledgeContractGap = defineEvent("ACKNOWLEDGE_CONTRACT_GAP");
+var ValidateContracts = defineEvent("VALIDATE_CONTRACTS");
+var ContractGapAcknowledged = defineFact("ContractGapAcknowledged");
+var ContractAdded = defineEvent("CONTRACT_ADDED");
+var ContractUpdated = defineEvent("CONTRACT_UPDATED");
+var ContractGapEmitted = defineEvent("CONTRACT_GAP_EMITTED");
+
+// src/decision-ledger/validation.ts
+function validateContracts(registry, options = {}) {
+  const {
+    incompleteSeverity = "warning",
+    requiredFields = ["behavior", "examples"],
+    artifactIndex
+  } = options;
+  const complete = [];
+  const incomplete = [];
+  const missing = [];
+  for (const rule of registry.getAllRules()) {
+    const contract = getContractFromDescriptor(rule);
+    if (!contract) {
+      missing.push(rule.id);
+      if (options.missingSeverity) {
+        incomplete.push({
+          ruleId: rule.id,
+          missing: ["contract"],
+          severity: options.missingSeverity,
+          message: `Rule '${rule.id}' has no contract`
+        });
+      }
+      continue;
+    }
+    const gaps = validateContract(contract, requiredFields, artifactIndex);
+    if (gaps.length > 0) {
+      incomplete.push({
+        ruleId: rule.id,
+        missing: gaps,
+        severity: incompleteSeverity,
+        message: `Rule '${rule.id}' contract is incomplete: missing ${gaps.join(", ")}`
+      });
+    } else {
+      complete.push({ ruleId: rule.id, contract });
+    }
+  }
+  for (const constraint of registry.getAllConstraints()) {
+    const contract = getContractFromDescriptor(constraint);
+    if (!contract) {
+      missing.push(constraint.id);
+      if (options.missingSeverity) {
+        incomplete.push({
+          ruleId: constraint.id,
+          missing: ["contract"],
+          severity: options.missingSeverity,
+          message: `Constraint '${constraint.id}' has no contract`
+        });
+      }
+      continue;
+    }
+    const gaps = validateContract(contract, requiredFields, artifactIndex);
+    if (gaps.length > 0) {
+      incomplete.push({
+        ruleId: constraint.id,
+        missing: gaps,
+        severity: incompleteSeverity,
+        message: `Constraint '${constraint.id}' contract is incomplete: missing ${gaps.join(", ")}`
+      });
+    } else {
+      complete.push({ ruleId: constraint.id, contract });
+    }
+  }
+  const total = registry.getAllRules().length + registry.getAllConstraints().length;
+  return {
+    complete,
+    incomplete,
+    missing,
+    total,
+    timestamp: (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+function validateContract(contract, requiredFields, artifactIndex) {
+  const missing = [];
+  if (requiredFields.includes("behavior") && isFieldEmpty(contract.behavior)) {
+    missing.push("behavior");
+  }
+  if (requiredFields.includes("examples") && (!contract.examples || contract.examples.length === 0)) {
+    missing.push("examples");
+  }
+  if (requiredFields.includes("invariants") && (!contract.invariants || contract.invariants.length === 0)) {
+    missing.push("invariants");
+  }
+  if (artifactIndex?.tests && !artifactIndex.tests.has(contract.ruleId)) {
+    missing.push("tests");
+  }
+  if (artifactIndex?.spec && !artifactIndex.spec.has(contract.ruleId)) {
+    missing.push("spec");
+  }
+  return missing;
+}
+function isFieldEmpty(value) {
+  return !value || value.trim() === "";
+}
+function formatValidationReport(report) {
+  const lines = [];
+  lines.push("Contract Validation Report");
+  lines.push("=".repeat(50));
+  lines.push("");
+  lines.push(`Total: ${report.total}`);
+  lines.push(`Complete: ${report.complete.length}`);
+  lines.push(`Incomplete: ${report.incomplete.length}`);
+  lines.push(`Missing: ${report.missing.length}`);
+  lines.push("");
+  if (report.complete.length > 0) {
+    lines.push("\u2713 Complete Contracts:");
+    for (const { ruleId, contract } of report.complete) {
+      lines.push(`  \u2713 ${ruleId} (v${contract.version || "1.0.0"})`);
+    }
+    lines.push("");
+  }
+  if (report.incomplete.length > 0) {
+    lines.push("\u2717 Incomplete Contracts:");
+    for (const gap of report.incomplete) {
+      const icon = gap.severity === "error" ? "\u2717" : gap.severity === "warning" ? "\u26A0" : "\u2139";
+      lines.push(`  ${icon} ${gap.ruleId} - Missing: ${gap.missing.join(", ")}`);
+      if (gap.message) {
+        lines.push(`     ${gap.message}`);
+      }
+    }
+    lines.push("");
+  }
+  if (report.missing.length > 0) {
+    lines.push("\u2717 No Contract:");
+    for (const ruleId of report.missing) {
+      lines.push(`  \u2717 ${ruleId}`);
+    }
+    lines.push("");
+  }
+  lines.push(`Validated at: ${report.timestamp}`);
+  return lines.join("\n");
+}
+function formatValidationReportJSON(report) {
+  return JSON.stringify(report, null, 2);
+}
+function formatValidationReportSARIF(report) {
+  const results = report.incomplete.map((gap) => {
+    const primaryMissing = gap.missing.length > 0 ? gap.missing[0] : "contract";
+    return {
+      ruleId: `decision-ledger/${primaryMissing}`,
+      level: gap.severity === "error" ? "error" : gap.severity === "warning" ? "warning" : "note",
+      message: {
+        text: gap.message || `Missing: ${gap.missing.join(", ")}`
+      },
+      locations: [
+        {
+          physicalLocation: {
+            artifactLocation: {
+              uri: "registry"
+            },
+            region: {
+              startLine: 1
+            }
+          }
+        }
+      ],
+      properties: {
+        ruleId: gap.ruleId,
+        missing: gap.missing
+      }
+    };
+  });
+  const sarif = {
+    version: "2.1.0",
+    $schema: "https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/Schemata/sarif-schema-2.1.0.json",
+    runs: [
+      {
+        tool: {
+          driver: {
+            name: "Praxis Decision Ledger",
+            version: "1.0.0",
+            informationUri: "https://github.com/plures/praxis",
+            rules: [
+              {
+                id: "decision-ledger/contract",
+                shortDescription: {
+                  text: "Rule or constraint missing contract"
+                }
+              },
+              {
+                id: "decision-ledger/behavior",
+                shortDescription: {
+                  text: "Contract missing behavior description"
+                }
+              },
+              {
+                id: "decision-ledger/examples",
+                shortDescription: {
+                  text: "Contract missing examples"
+                }
+              },
+              {
+                id: "decision-ledger/invariants",
+                shortDescription: {
+                  text: "Contract missing invariants"
+                }
+              },
+              {
+                id: "decision-ledger/tests",
+                shortDescription: {
+                  text: "Contract missing tests"
+                }
+              },
+              {
+                id: "decision-ledger/spec",
+                shortDescription: {
+                  text: "Contract missing spec"
+                }
+              }
+            ]
+          }
+        },
+        results
+      }
+    ]
+  };
+  return JSON.stringify(sarif, null, 2);
+}
+
+// src/decision-ledger/ledger.ts
+var BehaviorLedger = class _BehaviorLedger {
+  entries = [];
+  entryMap = /* @__PURE__ */ new Map();
+  /**
+   * Append a new entry to the ledger.
+   *
+   * @param entry The entry to append
+   * @throws Error if entry ID already exists
+   */
+  append(entry) {
+    if (this.entryMap.has(entry.id)) {
+      throw new Error(`Ledger entry with ID '${entry.id}' already exists`);
+    }
+    if (entry.supersedes) {
+      const superseded = this.entryMap.get(entry.supersedes);
+      if (superseded && superseded.status === "active") {
+        const updatedEntry = {
+          ...superseded,
+          status: "superseded"
+        };
+        this.entryMap.set(entry.supersedes, updatedEntry);
+      }
+    }
+    this.entries.push(entry);
+    this.entryMap.set(entry.id, entry);
+  }
+  /**
+   * Get an entry by ID.
+   *
+   * @param id The entry ID
+   * @returns The entry, or undefined if not found
+   */
+  getEntry(id) {
+    return this.entryMap.get(id);
+  }
+  /**
+   * Get all entries (in order of append) with current status.
+   *
+   * @returns Array of all entries with current status from the map
+   */
+  getAllEntries() {
+    return this.entries.map((entry) => this.entryMap.get(entry.id));
+  }
+  /**
+   * Get entries for a specific rule ID.
+   *
+   * @param ruleId The rule ID
+   * @returns Array of entries for this rule with current status
+   */
+  getEntriesForRule(ruleId) {
+    return this.entries.map((entry) => this.entryMap.get(entry.id)).filter((entry) => entry.contract.ruleId === ruleId);
+  }
+  /**
+   * Get the latest active entry for a rule.
+   *
+   * @param ruleId The rule ID
+   * @returns The latest active entry, or undefined if none
+   */
+  getLatestEntry(ruleId) {
+    const entries = this.getEntriesForRule(ruleId);
+    const activeEntries = entries.filter((entry) => entry.status === "active");
+    if (activeEntries.length === 0) {
+      return void 0;
+    }
+    return activeEntries[activeEntries.length - 1];
+  }
+  /**
+   * Get all active assumptions across all entries.
+   *
+   * @returns Map of assumption ID to assumption
+   */
+  getActiveAssumptions() {
+    const assumptions = /* @__PURE__ */ new Map();
+    for (const entry of this.entries) {
+      const currentEntry = this.entryMap.get(entry.id);
+      if (currentEntry.status !== "active") {
+        continue;
+      }
+      for (const assumption of currentEntry.contract.assumptions || []) {
+        if (assumption.status === "active") {
+          assumptions.set(assumption.id, assumption);
+        }
+      }
+    }
+    return assumptions;
+  }
+  /**
+   * Find assumptions that impact a specific artifact type.
+   *
+   * @param impactType The artifact type ('spec', 'tests', 'code')
+   * @returns Array of assumptions
+   */
+  findAssumptionsByImpact(impactType) {
+    const assumptions = [];
+    for (const entry of this.entries) {
+      const currentEntry = this.entryMap.get(entry.id);
+      if (currentEntry.status !== "active") {
+        continue;
+      }
+      for (const assumption of currentEntry.contract.assumptions || []) {
+        if (assumption.status === "active" && assumption.impacts.includes(impactType)) {
+          assumptions.push(assumption);
+        }
+      }
+    }
+    return assumptions;
+  }
+  /**
+   * Get ledger statistics.
+   */
+  getStats() {
+    const currentEntries = this.entries.map((e) => this.entryMap.get(e.id));
+    const active = currentEntries.filter((e) => e.status === "active").length;
+    const superseded = currentEntries.filter((e) => e.status === "superseded").length;
+    const deprecated = currentEntries.filter((e) => e.status === "deprecated").length;
+    const uniqueRules = new Set(currentEntries.map((e) => e.contract.ruleId)).size;
+    return {
+      totalEntries: this.entries.length,
+      activeEntries: active,
+      supersededEntries: superseded,
+      deprecatedEntries: deprecated,
+      uniqueRules
+    };
+  }
+  /**
+   * Export ledger as JSON.
+   *
+   * @returns JSON string with current entry status
+   */
+  toJSON() {
+    return JSON.stringify(
+      {
+        version: "1.0.0",
+        // Export entries with current status from the map
+        entries: this.entries.map((entry) => this.entryMap.get(entry.id)),
+        stats: this.getStats()
+      },
+      null,
+      2
+    );
+  }
+  /**
+   * Import ledger from JSON.
+   * 
+   * Note: The JSON must contain entries in the order they were originally appended.
+   * If a superseding entry appears before the entry it supersedes, the superseding
+   * logic will not work correctly. The toJSON method preserves this order.
+   *
+   * @param json The JSON string
+   * @returns A new BehaviorLedger instance
+   */
+  static fromJSON(json) {
+    const data = JSON.parse(json);
+    const ledger = new _BehaviorLedger();
+    for (const entry of data.entries || []) {
+      ledger.append(entry);
+    }
+    return ledger;
+  }
+};
+function createBehaviorLedger() {
+  return new BehaviorLedger();
+}
+
+export {
+  defineFact,
+  defineEvent,
+  defineRule,
+  defineConstraint,
+  defineModule,
+  filterEvents,
+  filterFacts,
+  findEvent,
+  findFact,
+  ContractMissing,
+  ContractValidated,
+  AcknowledgeContractGap,
+  ValidateContracts,
+  ContractGapAcknowledged,
+  ContractAdded,
+  ContractUpdated,
+  validateContracts,
+  formatValidationReport,
+  formatValidationReportJSON,
+  formatValidationReportSARIF,
+  BehaviorLedger,
+  createBehaviorLedger
+};

package/dist/{browser/chunk-JQ64KMLN.js → node/chunk-MBVHLOU2.js}

@@ -132,10 +132,21 @@ var PluresDBPraxisAdapter = class {
 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 });
+}
 
 export {
   InMemoryPraxisDB,
   createInMemoryDB,
   PluresDBPraxisAdapter,
-  createPluresDB
+  createPluresDB,
+  createPraxisLocalFirst
 };