@plures/praxis 1.1.3 → 1.2.10

package/dist/node/integrations/svelte.cjs

@@ -50,6 +50,17 @@ var $ = __toESM(require("svelte/internal/client"), 1);
 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
    */
@@ -58,6 +69,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
@@ -67,6 +79,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)
@@ -115,6 +128,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/core/protocol.ts

package/dist/node/integrations/svelte.d.cts

@@ -1,5 +1,5 @@
-import { L as LogicEngine } from '../reactive-engine.svelte-1M4m_C_v.cjs';
-export { a as ReactiveEngineOptions, R as ReactiveLogicEngine, c as createReactiveEngine } from '../reactive-engine.svelte-1M4m_C_v.cjs';
+import { L as LogicEngine } from '../reactive-engine.svelte-BFIZfawz.cjs';
+export { a as ReactiveEngineOptions, R as ReactiveLogicEngine, c as createReactiveEngine } from '../reactive-engine.svelte-BFIZfawz.cjs';
 import { P as PraxisState, a as PraxisEvent } from '../protocol-Qek7ebBl.cjs';
 
 /**

package/dist/node/integrations/svelte.d.ts

@@ -1,5 +1,5 @@
-import { L as LogicEngine } from '../reactive-engine.svelte-ChNFn4Hj.js';
-export { a as ReactiveEngineOptions, R as ReactiveLogicEngine, c as createReactiveEngine } from '../reactive-engine.svelte-ChNFn4Hj.js';
+import { L as LogicEngine } from '../reactive-engine.svelte-CRNqHlbv.js';
+export { a as ReactiveEngineOptions, R as ReactiveLogicEngine, c as createReactiveEngine } from '../reactive-engine.svelte-CRNqHlbv.js';
 import { P as PraxisState, a as PraxisEvent } from '../protocol-Qek7ebBl.js';
 
 /**

package/dist/node/integrations/svelte.js

@@ -1,7 +1,9 @@
 import {
   ReactiveLogicEngine,
   createReactiveEngine
-} from "../chunk-R45WXWKH.js";
+} from "../chunk-PRPQO6R5.js";
+import "../chunk-R2PSBPKQ.js";
+import "../chunk-VOMLVI6V.js";
 import "../chunk-QGM4M3NI.js";
 
 // src/integrations/svelte.ts

package/dist/node/{reactive-engine.svelte-1M4m_C_v.d.cts → reactive-engine.svelte-BFIZfawz.d.cts}

@@ -1,5 +1,167 @@
 import { P as PraxisState, a as PraxisEvent, b as PraxisFact, c as PraxisStepResult, d as PraxisStepConfig } from './protocol-Qek7ebBl.cjs';
 
+/**
+ * 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;
+}
+/**
+ * Type guard to check if an object is a valid Contract.
+ */
+declare function isContract(obj: unknown): obj is Contract;
+/**
+ * Options for defining a contract.
+ */
+interface DefineContractOptions {
+    /** ID of the rule or constraint */
+    ruleId: string;
+    /** Canonical behavior description */
+    behavior: string;
+    /** Given/When/Then examples */
+    examples: Example[];
+    /** Invariants that must hold */
+    invariants: string[];
+    /** Optional assumptions */
+    assumptions?: Assumption[];
+    /** Optional references */
+    references?: Reference[];
+    /** Optional version */
+    version?: string;
+}
+/**
+ * Define a contract for a rule or constraint.
+ *
+ * @example
+ * const loginContract = defineContract({
+ *   ruleId: 'auth.login',
+ *   behavior: 'Process login events and create user session facts',
+ *   examples: [
+ *     {
+ *       given: 'User provides valid credentials',
+ *       when: 'LOGIN event is received',
+ *       then: 'UserSessionCreated fact is emitted'
+ *     }
+ *   ],
+ *   invariants: ['Session must have unique ID']
+ * });
+ */
+declare function defineContract(options: DefineContractOptions): Contract;
+/**
+ * Extract contract from rule/constraint metadata.
+ */
+declare function getContract(meta?: Record<string, unknown>): Contract | undefined;
+/**
+ * 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;
+}
+/**
+ * Result of contract validation.
+ */
+interface ValidationReport {
+    /** Rules/constraints with complete contracts */
+    complete: Array<{
+        ruleId: string;
+        contract: Contract;
+    }>;
+    /** Rules/constraints with incomplete contracts */
+    incomplete: ContractGap[];
+    /** Rules/constraints with no contract at all */
+    missing: string[];
+    /** Total number of rules/constraints validated */
+    total: number;
+    /** Timestamp of validation */
+    timestamp: string;
+}
+
 /**
  * Rules and Constraints System
  *
@@ -47,6 +209,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>;
 }
@@ -60,6 +224,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>;
 }
@@ -75,6 +241,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.
@@ -82,6 +267,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
      */
@@ -118,6 +306,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;
 }
 
 /**
@@ -297,4 +495,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, PraxisRegistry as P, ReactiveLogicEngine as R, type ReactiveEngineOptions as a, type RuleDescriptor as b, createReactiveEngine as c, type RuleFn as d, type ConstraintFn as e, type PraxisModule as f, type RuleId as g, type ConstraintId as h, type PraxisEngineOptions as i, createPraxisEngine as j };
+export { type Assumption as A, type ConstraintDescriptor as C, type DefineContractOptions as D, type Example as E, LogicEngine as L, type MissingArtifact as M, PraxisRegistry as P, ReactiveLogicEngine as R, type Severity as S, type ValidationReport as V, type ReactiveEngineOptions as a, type RuleDescriptor as b, createReactiveEngine as c, type RuleFn as d, type Contract as e, type ConstraintFn as f, type PraxisModule as g, type RuleId as h, type ConstraintId as i, type PraxisEngineOptions as j, createPraxisEngine as k, defineContract as l, getContract as m, isContract as n, type Reference as o, type ContractGap as p };

package/dist/node/{reactive-engine.svelte-ChNFn4Hj.d.ts → reactive-engine.svelte-CRNqHlbv.d.ts}

@@ -1,5 +1,167 @@
 import { P as PraxisState, a as PraxisEvent, b as PraxisFact, c as PraxisStepResult, d as PraxisStepConfig } from './protocol-Qek7ebBl.js';
 
+/**
+ * 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;
+}
+/**
+ * Type guard to check if an object is a valid Contract.
+ */
+declare function isContract(obj: unknown): obj is Contract;
+/**
+ * Options for defining a contract.
+ */
+interface DefineContractOptions {
+    /** ID of the rule or constraint */
+    ruleId: string;
+    /** Canonical behavior description */
+    behavior: string;
+    /** Given/When/Then examples */
+    examples: Example[];
+    /** Invariants that must hold */
+    invariants: string[];
+    /** Optional assumptions */
+    assumptions?: Assumption[];
+    /** Optional references */
+    references?: Reference[];
+    /** Optional version */
+    version?: string;
+}
+/**
+ * Define a contract for a rule or constraint.
+ *
+ * @example
+ * const loginContract = defineContract({
+ *   ruleId: 'auth.login',
+ *   behavior: 'Process login events and create user session facts',
+ *   examples: [
+ *     {
+ *       given: 'User provides valid credentials',
+ *       when: 'LOGIN event is received',
+ *       then: 'UserSessionCreated fact is emitted'
+ *     }
+ *   ],
+ *   invariants: ['Session must have unique ID']
+ * });
+ */
+declare function defineContract(options: DefineContractOptions): Contract;
+/**
+ * Extract contract from rule/constraint metadata.
+ */
+declare function getContract(meta?: Record<string, unknown>): Contract | undefined;
+/**
+ * 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;
+}
+/**
+ * Result of contract validation.
+ */
+interface ValidationReport {
+    /** Rules/constraints with complete contracts */
+    complete: Array<{
+        ruleId: string;
+        contract: Contract;
+    }>;
+    /** Rules/constraints with incomplete contracts */
+    incomplete: ContractGap[];
+    /** Rules/constraints with no contract at all */
+    missing: string[];
+    /** Total number of rules/constraints validated */
+    total: number;
+    /** Timestamp of validation */
+    timestamp: string;
+}
+
 /**
  * Rules and Constraints System
  *
@@ -47,6 +209,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>;
 }
@@ -60,6 +224,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>;
 }
@@ -75,6 +241,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.
@@ -82,6 +267,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
      */
@@ -118,6 +306,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;
 }
 
 /**
@@ -297,4 +495,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, PraxisRegistry as P, ReactiveLogicEngine as R, type ReactiveEngineOptions as a, type RuleDescriptor as b, createReactiveEngine as c, type RuleFn as d, type ConstraintFn as e, type PraxisModule as f, type RuleId as g, type ConstraintId as h, type PraxisEngineOptions as i, createPraxisEngine as j };
+export { type Assumption as A, type ConstraintDescriptor as C, type DefineContractOptions as D, type Example as E, LogicEngine as L, type MissingArtifact as M, PraxisRegistry as P, ReactiveLogicEngine as R, type Severity as S, type ValidationReport as V, type ReactiveEngineOptions as a, type RuleDescriptor as b, createReactiveEngine as c, type RuleFn as d, type Contract as e, type ConstraintFn as f, type PraxisModule as g, type RuleId as h, type ConstraintId as i, type PraxisEngineOptions as j, createPraxisEngine as k, defineContract as l, getContract as m, isContract as n, type Reference as o, type ContractGap as p };