@plures/praxis 1.2.0 → 1.2.11

package/dist/node/validate-CNHUULQE.js

@@ -0,0 +1,180 @@
+import {
+  ContractMissing,
+  formatValidationReport,
+  formatValidationReportJSON,
+  formatValidationReportSARIF,
+  validateContracts
+} from "./chunk-5RH7UAQC.js";
+import {
+  writeLogicLedgerEntry
+} from "./chunk-WZ6B3LZ6.js";
+import {
+  PraxisRegistry
+} from "./chunk-R2PSBPKQ.js";
+import "./chunk-QGM4M3NI.js";
+
+// src/cli/commands/validate.ts
+async function validateCommand(options) {
+  const outputFormat = options.output || "console";
+  const strict = options.strict || false;
+  const registry = await loadRegistry(options.registry);
+  const artifactIndex = await buildArtifactIndex(registry, {
+    includeTests: options.tests ?? true,
+    includeSpec: options.spec ?? true
+  });
+  const report = validateContracts(registry, {
+    strict,
+    requiredFields: ["behavior", "examples", "invariants"],
+    missingSeverity: strict ? "error" : "warning",
+    artifactIndex
+  });
+  if (options.emitFacts) {
+    const facts = gapsToFacts(report.incomplete);
+    const events = gapsToEvents(report.incomplete);
+    await emitGapArtifacts({ facts, events, gapOutput: options.gapOutput });
+  }
+  if (options.ledger) {
+    await writeLedgerSnapshots(registry, {
+      rootDir: options.ledger,
+      author: options.author ?? "system",
+      artifactIndex
+    });
+  }
+  switch (outputFormat) {
+    case "json":
+      console.log(formatValidationReportJSON(report));
+      break;
+    case "sarif":
+      console.log(formatValidationReportSARIF(report));
+      break;
+    case "console":
+    default:
+      console.log(formatValidationReport(report));
+      break;
+  }
+  if (strict && (report.incomplete.length > 0 || report.missing.length > 0)) {
+    const incompleteErrors = report.incomplete.filter((gap) => gap.severity === "error").length;
+    const totalErrors = incompleteErrors + report.missing.length;
+    if (totalErrors > 0) {
+      console.error(`
+\u274C Validation failed: ${totalErrors} error(s) found`);
+      process.exit(1);
+    }
+  }
+  if (outputFormat === "console") {
+    if (report.incomplete.length === 0 && report.missing.length === 0) {
+      console.log("\n\u2705 All contracts validated successfully!");
+    } else {
+      const warningCount = report.incomplete.filter((gap) => gap.severity === "warning").length;
+      if (warningCount > 0) {
+        console.log(`
+\u26A0\uFE0F  ${warningCount} warning(s) found`);
+      }
+    }
+  }
+}
+async function loadRegistry(registryPath) {
+  const registry = new PraxisRegistry();
+  if (registryPath) {
+    try {
+      const module = await import(resolveRegistryPath(registryPath));
+      const candidate = module.registry ?? module.default ?? module.createRegistry?.();
+      if (candidate && candidate instanceof PraxisRegistry) {
+        return candidate;
+      }
+      throw new Error("Registry module did not export a PraxisRegistry instance");
+    } catch (error) {
+      console.warn(`Warning: Could not load registry from ${registryPath}:`, error);
+    }
+  }
+  return registry;
+}
+function resolveRegistryPath(registryPath) {
+  if (registryPath.startsWith(".") || registryPath.startsWith("/")) {
+    return new URL(registryPath, `file://${process.cwd()}/`).href;
+  }
+  return registryPath;
+}
+async function buildArtifactIndex(registry, options) {
+  const index = {};
+  const ruleIds = new Set(registry.getRuleIds().concat(registry.getConstraintIds()));
+  if (options.includeTests) {
+    index.tests = /* @__PURE__ */ new Set();
+    for (const id of ruleIds) {
+      if (await hasArtifactFile("tests", id)) {
+        index.tests.add(id);
+      }
+    }
+  }
+  if (options.includeSpec) {
+    index.spec = /* @__PURE__ */ new Set();
+    for (const id of ruleIds) {
+      if (await hasArtifactFile("spec", id)) {
+        index.spec.add(id);
+      }
+    }
+  }
+  return index;
+}
+async function writeLedgerSnapshots(registry, options) {
+  const { rootDir, author, artifactIndex } = options;
+  const processDescriptor = async (descriptor) => {
+    if (!descriptor.contract && !descriptor.meta?.contract) {
+      return;
+    }
+    const contract = descriptor.contract ?? descriptor.meta?.contract;
+    await writeLogicLedgerEntry(contract, {
+      rootDir,
+      author,
+      testsPresent: artifactIndex?.tests?.has(contract.ruleId) ?? false,
+      specPresent: artifactIndex?.spec?.has(contract.ruleId) ?? false
+    });
+  };
+  for (const descriptor of registry.getAllRules()) {
+    await processDescriptor(descriptor);
+  }
+  for (const descriptor of registry.getAllConstraints()) {
+    await processDescriptor(descriptor);
+  }
+}
+async function hasArtifactFile(type, ruleId) {
+  const fs = await import("fs/promises");
+  const path = await import("path");
+  const candidateDirs = type === "tests" ? ["src/__tests__", "tests", "test"] : ["spec", "specs"];
+  const sanitized = ruleId.replace(/[^a-zA-Z0-9_-]/g, "_");
+  for (const dir of candidateDirs) {
+    const fullDir = path.resolve(process.cwd(), dir);
+    try {
+      const entries = await fs.readdir(fullDir);
+      if (entries.some((file) => file.includes(sanitized))) {
+        return true;
+      }
+    } catch {
+    }
+  }
+  return false;
+}
+function gapsToFacts(gaps) {
+  return gaps.map(
+    (gap) => ContractMissing.create({
+      ruleId: gap.ruleId,
+      missing: gap.missing,
+      severity: gap.severity,
+      message: gap.message
+    })
+  );
+}
+function gapsToEvents(_gaps) {
+  return [];
+}
+async function emitGapArtifacts(payload) {
+  if (payload.gapOutput) {
+    const fs = await import("fs/promises");
+    await fs.writeFile(payload.gapOutput, JSON.stringify(payload, null, 2));
+  } else {
+    console.log(JSON.stringify(payload, null, 2));
+  }
+}
+export {
+  validateCommand
+};

package/docs/core/pluresdb-integration.md

@@ -50,28 +50,28 @@ npm install @plures/praxis
 
 ### Configuration
 
-Configure PluresDB in your application:
+You can choose network-only (previous default) or the new local-first unified API (auto-detects WASM/Tauri/IPC/network).
+
+**Network (unchanged):**
 
 ```typescript
 import { createPluresDB } from '@plures/praxis';
+import { PluresNode } from '@plures/pluresdb';
 
-const db = createPluresDB({
-  // Database name (stored in IndexedDB)
-  name: 'my-app-db',
+const db = createPluresDB(new PluresNode({ autoStart: true }));
+```
 
-  // Schema version (increment to migrate)
-  version: 1,
+**Local-first (auto-detect):**
+
+```typescript
+import { createPraxisLocalFirst } from '@plures/praxis';
 
-  // Collections to create
-  collections: ['users', 'posts', 'comments'],
+// Auto mode picks the best backend (WASM in browser, Tauri/IPC on desktop, network fallback)
+const db = await createPraxisLocalFirst({ mode: 'auto' });
 
-  // Sync configuration (optional)
-  sync: {
-    enabled: true,
-    endpoint: 'https://your-sync-server.com',
-    interval: 5000, // ms
-  },
-});
+// Optional: override
+// const db = await createPraxisLocalFirst({ mode: 'wasm', dbName: 'my-app' });
+// const db = await createPraxisLocalFirst({ mode: 'ipc', channelName: 'my-channel' });
 ```
 
 ### From Schema

package/docs/decision-ledger/BEHAVIOR_LEDGER.md

@@ -0,0 +1,225 @@
+# Decision Ledger Integration - Behavior Ledger
+
+**Status**: Active  
+**Version**: 1.0.0  
+**Created**: 2025-01-26  
+**Last Updated**: 2025-01-26
+
+---
+
+## Entry 1: Initial Decision Ledger Integration
+
+**ID**: `decision-ledger-v1`  
+**Timestamp**: 2025-01-26T00:00:00Z  
+**Status**: Active  
+**Author**: System
+
+### Canonical Behavior
+
+The Decision Ledger Integration provides a mechanism for Praxis applications to:
+
+1. **Define Contracts for Rules/Constraints** with:
+   - Canonical behavior description
+   - Given/When/Then examples that become test vectors
+   - TLA+-friendly invariants or Praxis-level invariants
+   - Explicit assumptions with confidence levels
+   - References to documentation, tickets, and external links
+
+2. **Validate Compliance** at build-time and runtime:
+   - Build-time: `praxis validate` CLI scans registry modules
+   - Runtime: Lightweight validation when registering rules
+   - Structured diagnostics (JSON, console, optional SARIF)
+
+3. **Track Missing Artifacts** as first-class facts:
+   - Fact: `ContractMissing` with ruleId, missing artifacts, severity
+   - Event: `ACKNOWLEDGE_CONTRACT_GAP` for explicit acknowledgment
+   - Rule: Policy enforcement for contract debt
+
+4. **Maintain Immutable History**:
+   - Append-only ledger of behavior changes
+   - Assumption invalidation tracking
+   - Versioned behavior snapshots
+
+### Examples (Given/When/Then)
+
+#### Example 1: Defining a Contract for a Rule
+
+**Given**: A rule `auth.login` that processes login events  
+**When**: Developer defines the contract with behavior, examples, and invariants  
+**Then**: The contract is registered and can be validated
+
+```typescript
+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',
+    'Session must have timestamp'
+  ],
+  assumptions: [
+    {
+      id: 'assume-unique-username',
+      statement: 'Usernames are unique across the system',
+      confidence: 0.9,
+      justification: 'Standard practice in authentication systems',
+      impacts: ['spec', 'tests']
+    }
+  ],
+  references: [
+    { type: 'doc', url: 'https://docs.example.com/auth' }
+  ]
+});
+```
+
+#### Example 2: Build-time Validation
+
+**Given**: A registry with rules and their contracts  
+**When**: `praxis validate` command is run  
+**Then**: Validation report shows contract coverage and gaps
+
+```bash
+$ praxis validate
+✓ auth.login - Contract complete (behavior, examples, tests)
+✗ cart.addItem - Missing: tests
+✗ order.process - Missing: contract
+```
+
+#### Example 3: Runtime Validation
+
+**Given**: A rule without a complete contract  
+**When**: Rule is registered at runtime with `strictContracts: true`  
+**Then**: ContractMissing fact is created and policy can enforce action
+
+```typescript
+const registry = createRegistry({ strictContracts: true });
+registry.registerRule(ruleWithoutContract);
+// ContractMissing fact is emitted
+// Policy may warn, error, or allow based on configuration
+```
+
+#### Example 4: Contract Gap Acknowledgment
+
+**Given**: A missing contract has been identified  
+**When**: Developer acknowledges the gap with justification  
+**Then**: ACKNOWLEDGE_CONTRACT_GAP event is recorded
+
+```typescript
+acknowledgeContractGap({
+  ruleId: 'legacy.process',
+  missing: ['spec', 'tests'],
+  justification: 'Legacy rule to be deprecated in v2.0',
+  expiresAt: '2025-12-31'
+});
+```
+
+### Invariants
+
+1. **Contract Immutability**: Once a contract version is published, its core behavior description cannot be changed; only new versions can be created
+2. **Ledger Append-Only**: The behavior ledger is append-only; entries can be superseded but never deleted
+3. **Assumption Traceability**: Every assumption must have a stable ID and impacts declaration
+4. **Example Completeness**: Every contract must have at least one Given/When/Then example
+5. **Validation Determinism**: Running `praxis validate` multiple times on the same codebase produces identical results
+
+### Assumptions
+
+#### A1: Contract Storage Location
+- **ID**: `assume-contract-in-meta`
+- **Statement**: Contracts are stored in the `meta` field of RuleDescriptor and ConstraintDescriptor
+- **Confidence**: 0.95
+- **Justification**: The existing `meta` field is designed for extensibility and already exists in the Praxis architecture
+- **Derived From**: Analysis of src/core/rules.ts and src/dsl/index.ts
+- **Impacts**: Implementation (contract storage), Tests (contract retrieval)
+- **Status**: Active
+
+#### A2: JSON Serialization
+- **ID**: `assume-json-serializable`
+- **Statement**: All contract data must be JSON-serializable for cross-language compatibility
+- **Confidence**: 1.0
+- **Justification**: Praxis protocol requirement for all data structures
+- **Derived From**: src/core/protocol.ts PRAXIS_PROTOCOL_VERSION documentation
+- **Impacts**: Spec (type definitions), Implementation (contract types)
+- **Status**: Active
+
+#### A3: CLI Extension Pattern
+- **ID**: `assume-commander-pattern`
+- **Statement**: New CLI commands follow the Commander.js pattern established in src/cli/index.ts
+- **Confidence**: 1.0
+- **Justification**: Existing CLI uses Commander.js for all commands
+- **Derived From**: src/cli/index.ts lines 9-12
+- **Impacts**: Implementation (validate command)
+- **Status**: Active
+
+#### A4: Test Framework
+- **ID**: `assume-vitest`
+- **Statement**: Tests use Vitest framework with describe/it/expect pattern
+- **Confidence**: 1.0
+- **Justification**: All existing tests use Vitest
+- **Derived From**: src/__tests__/dsl.test.ts, package.json scripts
+- **Impacts**: Tests (testing approach)
+- **Status**: Active
+
+#### A5: Contract Optional by Default
+- **ID**: `assume-contract-optional`
+- **Statement**: Contracts are optional by default; strict enforcement requires opt-in configuration
+- **Confidence**: 0.85
+- **Justification**: Backward compatibility with existing Praxis code that doesn't have contracts
+- **Derived From**: User requirements for "integration" rather than breaking change
+- **Impacts**: Implementation (validation logic), Tests (default behavior)
+- **Status**: Active
+
+### References
+
+- **Design Doc**: Problem statement provided by user
+- **Praxis Core**: src/core/rules.ts - Rule and Constraint descriptors
+- **Praxis DSL**: src/dsl/index.ts - Helper functions for defining rules
+- **Praxis Protocol**: src/core/protocol.ts - Core protocol versioning and types
+- **CLI Pattern**: src/cli/index.ts - Command structure
+
+### Changes from Previous Version
+
+N/A - Initial version
+
+---
+
+## Schema
+
+**Ledger Entry Schema**:
+```typescript
+interface LedgerEntry {
+  id: string;
+  timestamp: string;
+  status: 'active' | 'superseded' | 'deprecated';
+  author: string;
+  behavior: {
+    canonical: string;
+    examples: Array<{
+      given: string;
+      when: string;
+      then: string;
+    }>;
+    invariants: string[];
+  };
+  assumptions: Array<{
+    id: string;
+    statement: string;
+    confidence: number;
+    justification: string;
+    derivedFrom: string;
+    impacts: Array<'spec' | 'tests' | 'code'>;
+    status: 'active' | 'revised' | 'invalidated';
+  }>;
+  references: Array<{
+    type: string;
+    url?: string;
+    description?: string;
+  }>;
+  supersedes?: string;
+}
+```

package/docs/decision-ledger/DecisionLedger.tla

@@ -0,0 +1,180 @@
+--------------------------- MODULE DecisionLedger ---------------------------
+(*
+ * TLA+ Specification for Praxis Decision Ledger Integration
+ *
+ * This spec models the core invariants and behaviors of the Decision Ledger,
+ * ensuring correctness of contract validation and ledger immutability.
+ *)
+
+EXTENDS Naturals, Sequences, FiniteSets, TLC
+
+CONSTANTS
+    RuleIds,        \* Set of all possible rule IDs
+    MaxLedgerSize   \* Maximum ledger entries for model checking
+
+VARIABLES
+    ledger,         \* Append-only sequence of ledger entries
+    contracts,      \* Map: RuleId -> Contract
+    facts,          \* Set of current facts (including ContractMissing)
+    acknowledged    \* Set of acknowledged contract gaps
+
+vars == <<ledger, contracts, facts, acknowledged>>
+
+(*--algorithm DecisionLedger
+
+variables
+    ledger = <<>>;
+    contracts = [r \in {} |-> {}];
+    facts = {};
+    acknowledged = {};
+
+define
+    \* Type invariants
+    TypeOK ==
+        /\ ledger \in Seq([
+            id: STRING,
+            ruleId: RuleIds,
+            timestamp: Nat,
+            status: {"active", "superseded", "deprecated"}
+        ])
+        /\ contracts \in [RuleIds -> [
+            behavior: STRING,
+            examples: SUBSET [given: STRING, when: STRING, then: STRING],
+            invariants: SUBSET STRING
+        ]]
+        /\ facts \in SUBSET [
+            type: STRING,
+            ruleId: RuleIds,
+            data: [missing: SUBSET STRING, severity: STRING]
+        ]
+        /\ acknowledged \in SUBSET [ruleId: RuleIds, justification: STRING]
+
+    \* Ledger is append-only (monotonic growth and immutability)
+    LedgerAppendOnly ==
+        /\ Len(ledger') >= Len(ledger)
+        /\ \A i \in 1..Len(ledger) :
+            \* Once an entry is in the ledger, it never changes in any field
+            ledger'[i] = ledger[i]
+
+    \* No duplicate ledger entry IDs
+    LedgerUnique ==
+        \A i, j \in 1..Len(ledger) :
+            i # j => ledger[i].id # ledger[j].id
+
+    \* Every contract must have at least one example
+    ContractExampleCompleteness ==
+        \A r \in DOMAIN contracts :
+            contracts[r].examples # {}
+
+    \* ContractMissing facts are accurate
+    ContractMissingAccuracy ==
+        \A f \in facts :
+            f.type = "ContractMissing" =>
+                /\ f.ruleId \notin DOMAIN contracts
+                \/ contracts[f.ruleId].examples = {}
+                \/ contracts[f.ruleId].behavior = ""
+
+    \* Acknowledged gaps are recorded
+    AcknowledgedGapsRecorded ==
+        \A a \in acknowledged :
+            \E f \in facts :
+                /\ f.type = "ContractMissing"
+                /\ f.ruleId = a.ruleId
+
+    \* Validation is deterministic
+    ValidationDeterministic ==
+        \* Given the same contracts, validation produces the same facts
+        \A r \in RuleIds :
+            (r \in DOMAIN contracts /\ contracts[r].behavior # "" /\ contracts[r].examples # {})
+                => ~\E f \in facts : f.type = "ContractMissing" /\ f.ruleId = r
+
+end define;
+
+\* Add a contract for a rule
+procedure AddContract(ruleId, behavior, examples, invariants)
+begin
+    AddContract:
+        if ruleId \notin DOMAIN contracts then
+            contracts := contracts @@ (ruleId :> [
+                behavior |-> behavior,
+                examples |-> examples,
+                invariants |-> invariants
+            ]);
+            \* Remove ContractMissing fact if it exists
+            facts := {f \in facts : ~(f.type = "ContractMissing" /\ f.ruleId = ruleId)};
+        end if;
+    return;
+end procedure;
+
+\* Register a rule and validate contract
+procedure RegisterRule(ruleId, hasContract)
+begin
+    RegisterRule:
+        if ~hasContract /\ ruleId \notin DOMAIN contracts then
+            \* Create ContractMissing fact
+            facts := facts \union {[
+                type |-> "ContractMissing",
+                ruleId |-> ruleId,
+                data |-> [missing |-> {"behavior", "examples"}, severity |-> "warning"]
+            ]};
+        end if;
+    return;
+end procedure;
+
+\* Acknowledge a contract gap
+procedure AcknowledgeGap(ruleId, justification)
+begin
+    AcknowledgeGap:
+        acknowledged := acknowledged \union {[
+            ruleId |-> ruleId,
+            justification |-> justification
+        ]};
+    return;
+end procedure;
+
+\* Append to ledger (immutable)
+procedure AppendLedger(entryId, ruleId, timestamp, status)
+begin
+    AppendLedger:
+        if Len(ledger) < MaxLedgerSize then
+            ledger := Append(ledger, [
+                id |-> entryId,
+                ruleId |-> ruleId,
+                timestamp |-> timestamp,
+                status |-> status
+            ]);
+        end if;
+    return;
+end procedure;
+
+end algorithm; *)
+
+=============================================================================
+
+\* Key Invariants (for model checking):
+\* 
+\* INVARIANT LedgerAppendOnly
+\*   The ledger is append-only; existing entries are never modified or deleted
+\*
+\* INVARIANT LedgerUnique
+\*   No two ledger entries have the same ID
+\*
+\* INVARIANT ContractExampleCompleteness
+\*   Every contract has at least one example
+\*
+\* INVARIANT ContractMissingAccuracy
+\*   ContractMissing facts accurately reflect missing contracts
+\*
+\* INVARIANT ValidationDeterministic
+\*   Validation produces deterministic results given the same inputs
+\*
+\* PROPERTY Safety
+\*   []TypeOK /\ []LedgerAppendOnly /\ []LedgerUnique
+\*
+\* PROPERTY Liveness
+\*   Eventually all rules have contracts: <>(DOMAIN contracts = RuleIds)
+\*
+\* Model Checking Notes:
+\* - Set MaxLedgerSize = 5 for tractable model checking
+\* - Set RuleIds = {"rule1", "rule2", "rule3"} for small test cases
+\* - Check temporal properties with TLC