@plures/praxis 2.0.0 → 2.0.3

package/dist/browser/{chunk-6MVRT7CK.js → chunk-IUEKGHQN.js}

@@ -33,7 +33,8 @@ function createApp(config) {
   }
   const ruleStates = (config.rules ?? []).map((rule) => ({
     rule,
-    lastResult: null
+    lastResult: null,
+    emittedTags: /* @__PURE__ */ new Set()
   }));
   const constraints = config.constraints ?? [];
   const livenessConfig = config.liveness;
@@ -121,12 +122,22 @@ function createApp(config) {
         switch (result.kind) {
           case "emit":
             newFacts.push(...result.facts);
+            for (const f of result.facts) {
+              rs.emittedTags.add(f.tag);
+            }
             break;
           case "retract":
             retractions.push(...result.retractTags);
+            for (const tag of result.retractTags) {
+              rs.emittedTags.delete(tag);
+            }
             break;
           case "noop":
           case "skip":
+            if (rs.emittedTags.size > 0) {
+              retractions.push(...rs.emittedTags);
+              rs.emittedTags.clear();
+            }
             break;
         }
       } catch (err) {
@@ -281,9 +292,8 @@ function createApp(config) {
       const state = paths.get(p);
       const lastUpdated = state?.lastUpdated ?? 0;
       const elapsed = lastUpdated > 0 ? now - lastUpdated : now - initTime;
-      const timeout = livenessConfig?.timeoutMs ?? 5e3;
       result[p] = {
-        stale: state?.updateCount === 0 || elapsed > timeout,
+        stale: !state || state.updateCount === 0,
         lastUpdated,
         elapsed
       };

package/dist/browser/index.js

@@ -32,7 +32,7 @@ import {
   defineModule,
   definePath,
   defineRule
-} from "./chunk-6MVRT7CK.js";
+} from "./chunk-IUEKGHQN.js";
 import {
   LogicEngine,
   PRAXIS_PROTOCOL_VERSION,

package/dist/browser/unified/index.js

@@ -4,7 +4,7 @@ import {
   defineModule,
   definePath,
   defineRule
-} from "../chunk-6MVRT7CK.js";
+} from "../chunk-IUEKGHQN.js";
 import {
   RuleResult,
   fact

package/dist/node/{chunk-6MVRT7CK.js → chunk-IUEKGHQN.js}

@@ -33,7 +33,8 @@ function createApp(config) {
   }
   const ruleStates = (config.rules ?? []).map((rule) => ({
     rule,
-    lastResult: null
+    lastResult: null,
+    emittedTags: /* @__PURE__ */ new Set()
   }));
   const constraints = config.constraints ?? [];
   const livenessConfig = config.liveness;
@@ -121,12 +122,22 @@ function createApp(config) {
         switch (result.kind) {
           case "emit":
             newFacts.push(...result.facts);
+            for (const f of result.facts) {
+              rs.emittedTags.add(f.tag);
+            }
             break;
           case "retract":
             retractions.push(...result.retractTags);
+            for (const tag of result.retractTags) {
+              rs.emittedTags.delete(tag);
+            }
             break;
           case "noop":
           case "skip":
+            if (rs.emittedTags.size > 0) {
+              retractions.push(...rs.emittedTags);
+              rs.emittedTags.clear();
+            }
             break;
         }
       } catch (err) {
@@ -281,9 +292,8 @@ function createApp(config) {
       const state = paths.get(p);
       const lastUpdated = state?.lastUpdated ?? 0;
       const elapsed = lastUpdated > 0 ? now - lastUpdated : now - initTime;
-      const timeout = livenessConfig?.timeoutMs ?? 5e3;
       result[p] = {
-        stale: state?.updateCount === 0 || elapsed > timeout,
+        stale: !state || state.updateCount === 0,
         lastUpdated,
         elapsed
       };

package/dist/node/index.cjs

@@ -7951,7 +7951,8 @@ function createApp(config) {
   }
   const ruleStates = (config.rules ?? []).map((rule) => ({
     rule,
-    lastResult: null
+    lastResult: null,
+    emittedTags: /* @__PURE__ */ new Set()
   }));
   const constraints = config.constraints ?? [];
   const livenessConfig = config.liveness;
@@ -8039,12 +8040,22 @@ function createApp(config) {
         switch (result.kind) {
           case "emit":
             newFacts.push(...result.facts);
+            for (const f of result.facts) {
+              rs.emittedTags.add(f.tag);
+            }
             break;
           case "retract":
             retractions.push(...result.retractTags);
+            for (const tag of result.retractTags) {
+              rs.emittedTags.delete(tag);
+            }
             break;
           case "noop":
           case "skip":
+            if (rs.emittedTags.size > 0) {
+              retractions.push(...rs.emittedTags);
+              rs.emittedTags.clear();
+            }
             break;
         }
       } catch (err) {
@@ -8199,9 +8210,8 @@ function createApp(config) {
       const state2 = paths.get(p);
       const lastUpdated = state2?.lastUpdated ?? 0;
       const elapsed = lastUpdated > 0 ? now - lastUpdated : now - initTime;
-      const timeout = livenessConfig?.timeoutMs ?? 5e3;
       result[p] = {
-        stale: state2?.updateCount === 0 || elapsed > timeout,
+        stale: !state2 || state2.updateCount === 0,
         lastUpdated,
         elapsed
       };

package/dist/node/index.js

@@ -109,7 +109,7 @@ import {
   defineModule as defineModule2,
   definePath,
   defineRule as defineRule2
-} from "./chunk-6MVRT7CK.js";
+} from "./chunk-IUEKGHQN.js";
 import {
   RuleResult,
   fact

package/dist/node/unified/index.cjs

@@ -65,7 +65,8 @@ function createApp(config) {
   }
   const ruleStates = (config.rules ?? []).map((rule) => ({
     rule,
-    lastResult: null
+    lastResult: null,
+    emittedTags: /* @__PURE__ */ new Set()
   }));
   const constraints = config.constraints ?? [];
   const livenessConfig = config.liveness;
@@ -153,12 +154,22 @@ function createApp(config) {
         switch (result.kind) {
           case "emit":
             newFacts.push(...result.facts);
+            for (const f of result.facts) {
+              rs.emittedTags.add(f.tag);
+            }
             break;
           case "retract":
             retractions.push(...result.retractTags);
+            for (const tag of result.retractTags) {
+              rs.emittedTags.delete(tag);
+            }
             break;
           case "noop":
           case "skip":
+            if (rs.emittedTags.size > 0) {
+              retractions.push(...rs.emittedTags);
+              rs.emittedTags.clear();
+            }
             break;
         }
       } catch (err) {
@@ -313,9 +324,8 @@ function createApp(config) {
       const state = paths.get(p);
       const lastUpdated = state?.lastUpdated ?? 0;
       const elapsed = lastUpdated > 0 ? now - lastUpdated : now - initTime;
-      const timeout = livenessConfig?.timeoutMs ?? 5e3;
       result[p] = {
-        stale: state?.updateCount === 0 || elapsed > timeout,
+        stale: !state || state.updateCount === 0,
         lastUpdated,
         elapsed
       };

package/dist/node/unified/index.js

@@ -4,7 +4,7 @@ import {
   defineModule,
   definePath,
   defineRule
-} from "../chunk-6MVRT7CK.js";
+} from "../chunk-IUEKGHQN.js";
 import {
   RuleResult,
   fact

package/docs/README.md

@@ -1,81 +1,77 @@
-# Praxis Documentation
+# Praxis 2.0 Documentation
 
-Welcome to the official Praxis documentation! Praxis is the full-stack application framework for the Plures ecosystem, providing a complete solution for building modern, local-first, distributed applications.
+Welcome to the official Praxis documentation. Praxis is the full-stack declarative application framework for the Plures ecosystem — typed logic, reactive state, local-first data, and visual tooling for Svelte, Node, and the browser.
 
-## 🐕 Dogfooding Plures Tools
-
-**Start here for dogfooding:** [Dogfooding Index](./DOGFOODING_INDEX.md)
-
-We actively dogfood all Plures tools during development. Key resources:
-- [Quick Start Guide](./DOGFOODING_QUICK_START.md) - Get started in 5 minutes
-- [Dogfooding Checklist](./DOGFOODING_CHECKLIST.md) - Daily/weekly/monthly workflows
-- [Plures Tools Inventory](./PLURES_TOOLS_INVENTORY.md) - All available tools
-- [Workflow Examples](./examples/DOGFOODING_WORKFLOW_EXAMPLE.md) - See it in action
+> **New to Praxis?** Start with the [Getting Started guide](../GETTING_STARTED.md).
+> **Upgrading from 1.x?** See the [Migration Guide](../MIGRATION_GUIDE.md).
 
 ## Quick Start
 
 ```bash
-# Install Praxis
 npm install @plures/praxis
-
-# Create a new app
 npx praxis create app my-app
-cd my-app
-npm install
-
-# Start development
-npm run dev
 ```
 
 ## Documentation Index
 
 ### Core Concepts
 
-| Document                                               | Description                                  |
-| ------------------------------------------------------ | -------------------------------------------- |
-| [What is Praxis](./core/what-is-praxis.md)             | Overview of Praxis and its core philosophy   |
-| [Praxis-Core API](./core/praxis-core-api.md)           | Stable API surface and guarantees            |
-| [Extending Praxis-Core](./core/extending-praxis-core.md) | Extension guidelines without breaking changes |
-| [Schema Model](./core/schema-model.md)                 | Understanding the Praxis Schema Format (PSF) |
-| [Logic Engine](./core/logic-engine.md)                 | Facts, events, rules, and constraints        |
-| [UI Generation](./core/ui-generation.md)               | Automatic component generation from schemas  |
-| [PluresDB Integration](./core/pluresdb-integration.md) | Local-first data with reactive storage       |
-| [Code ↔ Canvas Sync](./core/code-canvas-sync.md)      | Bidirectional synchronization                |
-| [CLI Usage](./core/cli-usage.md)                       | Command-line interface reference             |
-| [Building Extensions](./core/building-extensions.md)   | Extending Praxis functionality               |
+| Document | Description |
+|----------|-------------|
+| [What is Praxis](./core/what-is-praxis.md) | Overview and philosophy |
+| [Praxis-Core API](./core/praxis-core-api.md) | Stable API surface and guarantees |
+| [Extending Praxis-Core](./core/extending-praxis-core.md) | Extension guidelines |
+| [Schema Model](./core/schema-model.md) | Praxis Schema Format (PSF) |
+| [Logic Engine](./core/logic-engine.md) | Facts, events, rules, and constraints |
+| [UI Generation](./core/ui-generation.md) | Component generation from schemas |
+| [PluresDB Integration](./core/pluresdb-integration.md) | Local-first data with reactive storage |
+| [Code ↔ Canvas Sync](./core/code-canvas-sync.md) | Bidirectional synchronization |
+| [CLI Usage](./core/cli-usage.md) | Command-line interface reference |
+| [Building Extensions](./core/building-extensions.md) | Extending Praxis |
 
 ### Guides
 
-| Guide                                                         | Description                         |
-| ------------------------------------------------------------- | ----------------------------------- |
-| [Getting Started](./guides/getting-started.md)                | First steps with Praxis             |
-| [Svelte Integration](./guides/svelte-integration.md)          | Using Praxis with Svelte 5          |
-| [Canvas](./guides/canvas.md)                                  | Visual development with CodeCanvas  |
+| Guide | Description |
+|-------|-------------|
+| [Getting Started](./guides/getting-started.md) | First steps with Praxis |
+| [Svelte Integration](./guides/svelte-integration.md) | Using Praxis with Svelte 5 |
+| [Canvas](./guides/canvas.md) | Visual development with CodeCanvas |
 | [History & State Patterns](./guides/history-state-pattern.md) | Undo/redo and time-travel debugging |
-| [Parallel State Patterns](./guides/parallel-state-pattern.md) | Managing parallel state machines    |
-| [Orchestration](./guides/orchestration.md)                    | Distributed system coordination     |
+| [Parallel State Patterns](./guides/parallel-state-pattern.md) | Managing parallel state machines |
+| [Orchestration](./guides/orchestration.md) | Distributed system coordination |
+| [CI/CD Pipeline](./guides/cicd-pipeline.md) | Continuous integration setup |
 
 ### Tutorials
 
-| Tutorial                                           | Description                      |
-| -------------------------------------------------- | -------------------------------- |
-| [Build Your First App](./tutorials/first-app.md)   | Step-by-step beginner tutorial   |
-| [Todo with PluresDB](./tutorials/todo-pluresdb.md) | Local-first todo application     |
-| [Form Builder](./tutorials/form-builder.md)        | Dynamic form creation            |
-| [E-commerce Cart](./tutorials/ecommerce-cart.md)   | Shopping cart with checkout flow |
+| Tutorial | Description |
+|----------|-------------|
+| [Build Your First App](./tutorials/first-app.md) | Step-by-step beginner tutorial |
+| [Todo with PluresDB](./tutorials/todo-pluresdb.md) | Local-first todo application |
+| [Form Builder](./tutorials/form-builder.md) | Dynamic form creation |
+| [E-commerce Cart](./tutorials/ecommerce-cart.md) | Shopping cart with checkout flow |
+
+### Decision Ledger
+
+| Resource | Description |
+|----------|-------------|
+| [Dogfooding Guide](./decision-ledger/DOGFOODING.md) | Decision Ledger workflow |
+| [Behavior Ledger](./decision-ledger/BEHAVIOR_LEDGER.md) | Rule/constraint change log |
+| [Contract Index](./decision-ledger/contract-index.json) | Machine-readable contract inventory |
 
 ### Examples
 
-| Example                                     | Description                  |
-| ------------------------------------------- | ---------------------------- |
-| [Hero Shop](../examples/hero-shop/)         | Full e-commerce application  |
-| [Todo](../examples/todo/)                   | Minimal todo application     |
-| [Form Builder](../examples/form-builder/)   | Dynamic form builder         |
-| [Offline Chat](../examples/offline-chat/)   | Local-first chat application |
-| [Terminal Node](../examples/terminal-node/) | Self-orchestrating node      |
-| [Cloud Sync](../examples/cloud-sync/)       | Multi-client synchronization |
+| Example | Description |
+|---------|-------------|
+| [Unified App](../examples/unified-app/) | `createApp()` with rules and Mermaid docs |
+| [Hero Shop](../examples/hero-shop/) | Full e-commerce application |
+| [Todo](../examples/todo/) | Minimal todo application |
+| [Form Builder](../examples/form-builder/) | Dynamic form builder |
+| [Offline Chat](../examples/offline-chat/) | Local-first chat application |
+| [Terminal Node](../examples/terminal-node/) | Command execution with YAML schemas |
+| [Cloud Sync](../examples/cloud-sync/) | Multi-client synchronization |
+| [Decision Ledger](../examples/decision-ledger/) | Contracts, validation, SARIF output |
 
-## Architecture Overview
+## Architecture
 
 ```mermaid
 flowchart TB
@@ -108,59 +104,19 @@ flowchart TB
     Engine --> StateDocs
 ```
 
-## Key Features
-
-### 🎯 Schema-Driven Development
-
-Define your entire application in PSF (Praxis Schema Format), then generate everything else.
-
-### ⚡ Logic Engine
-
-Pure, functional business logic with facts, events, rules, and constraints.
-
-### 🧩 Component Generation
-
-Automatically generate Svelte components from your schemas.
-
-### 📱 Local-First
-
-Built-in PluresDB integration for offline-capable, reactive data storage.
-
-### 🎨 Visual Development
-
-CodeCanvas provides visual schema and logic editing.
+## Dogfooding
 
-### 📚 Auto-Documentation
+We actively dogfood all Plures tools during development:
 
-State-Docs generates documentation automatically from schemas.
+- [Dogfooding Index](./DOGFOODING_INDEX.md) — overview
+- [Quick Start](./DOGFOODING_QUICK_START.md) — get started in 5 minutes
+- [Checklist](./DOGFOODING_CHECKLIST.md) — daily/weekly/monthly workflows
+- [Tools Inventory](./PLURES_TOOLS_INVENTORY.md) — all available tools
+- [Workflow Example](./examples/DOGFOODING_WORKFLOW_EXAMPLE.md) — see it in action
 
-### 🌐 Cross-Platform
+## 1.x Documentation Archive
 
-Deploy to web, desktop (Tauri), and mobile from a single codebase.
-
-### 🔄 Real-Time Sync
-
-Praxis Cloud provides sync across devices and users.
-
-## Installation Options
-
-### npm
-
-```bash
-npm install @plures/praxis
-```
-
-### Deno
-
-```typescript
-import { createPraxisEngine } from 'jsr:@plures/praxis';
-```
-
-### C# (.NET)
-
-```bash
-dotnet add package Plures.Praxis
-```
+Historical documentation from Praxis 1.x development is preserved in [archive/1.x/](./archive/1.x/).
 
 ## Community
 

package/docs/archive/1.x/CONVERSATIONS_IMPLEMENTATION.md

@@ -0,0 +1,207 @@
+# Praxis Conversations Subsystem Implementation
+
+## Overview
+
+This document summarizes the implementation of the **praxis-conversations** subsystem, a deterministic-first conversation ingestion pipeline integrated into the Praxis framework.
+
+## Implementation Date
+
+February 1, 2024
+
+## Deliverables
+
+### 1. JSON Schemas
+
+Located in `src/conversations/`:
+
+- **conversation.schema.json**: Defines the structure for conversation data including turns, metadata, and classification
+- **candidate.schema.json**: Defines the structure for emission candidates (GitHub issues, documentation, etc.)
+
+### 2. Core Pipeline Modules
+
+The pipeline follows this deterministic flow:
+
+```
+capture → redact → normalize → classify → candidates → gate → emit
+```
+
+**Modules** (all in `src/conversations/`):
+
+- `capture.ts`: Capture conversations from various sources
+- `redact.ts`: Deterministic PII redaction (email, phone, IP, SSN, credit cards)
+- `normalize.ts`: Content normalization (whitespace, code blocks)
+- `classify.ts`: Keyword-based classification (bug-report, feature-request, question, etc.)
+- `candidates.ts`: Generate emission candidates from classified conversations
+- `gate.ts`: Quality gates (minimum length, valid title, metadata, duplicates)
+
+### 3. Emitters
+
+Located in `src/conversations/emitters/`:
+
+- **fs.ts**: Filesystem emitter with dry-run support
+- **github.ts**: GitHub issue emitter with **HARD GATE** on `commit_intent=true`
+
+### 4. CLI Commands
+
+Command: `praxis conversations [subcommand]`
+
+Subcommands:
+- `capture`: Capture a conversation from input
+- `push`: Process through redact + normalize pipeline
+- `classify`: Classify conversation and generate candidate
+- `emit`: Emit candidate to fs or github (with gates)
+
+### 5. Tests & Fixtures
+
+- **Tests**: `src/__tests__/conversations.test.ts` (18 comprehensive tests)
+- **Fixtures**: `test/fixtures/conversations/` (3 test conversations)
+  - bug-report.json
+  - feature-request.json
+  - question.json
+
+All tests passing (18/18 for conversations, 404/408 total)
+
+### 6. Documentation
+
+- **README**: `src/conversations/README.md` (comprehensive guide)
+- Includes schema documentation, CLI usage, and programmatic API examples
+
+## Key Features
+
+1. **Deterministic-first**: No LLM required, all logic is rule-based
+2. **Hard-gated GitHub emitter**: Requires explicit `--commit-intent` flag
+3. **PII redaction**: Automatic removal of sensitive data
+4. **Quality gates**: 4 gates ensure quality before emission
+5. **Dry-run mode**: Test without side effects
+6. **Extensible**: Easy to add new emitters, classifiers, or gates
+
+## Usage Examples
+
+### CLI Usage
+
+```bash
+# Full pipeline
+praxis conversations push -i input.json -o processed.json
+praxis conversations classify -i processed.json -o candidate.json
+praxis conversations emit -i candidate.json -e fs --output-dir ./output
+
+# GitHub emission (requires --commit-intent)
+praxis conversations emit -i candidate.json -e github \
+  --owner myorg --repo myrepo --commit-intent
+```
+
+### Programmatic Usage
+
+```typescript
+import {
+  captureConversation,
+  redactConversation,
+  normalizeConversation,
+  classifyConversation,
+  generateCandidate,
+  applyGates,
+  emitToFS,
+} from '@plures/praxis/conversations';
+
+// Process conversation
+let conv = captureConversation({ turns: [...], metadata: {} });
+conv = redactConversation(conv);
+conv = normalizeConversation(conv);
+conv = classifyConversation(conv);
+
+// Generate and emit candidate
+const candidate = generateCandidate(conv);
+const gated = applyGates(candidate);
+if (gated.gateStatus?.passed) {
+  await emitToFS(gated, { outputDir: './output' });
+}
+```
+
+## Security
+
+- **CodeQL Scan**: 0 vulnerabilities found
+- **PII Redaction**: Implemented for emails, phones, IPs, SSNs, credit cards
+- **GitHub Gate**: Hard-gated to prevent accidental issue creation
+- **Input Validation**: All inputs validated before processing
+
+## Testing
+
+All tests passing:
+- Conversations subsystem: 18/18 tests
+- Full test suite: 404/408 tests (4 skipped)
+
+Run tests:
+```bash
+npm test src/__tests__/conversations.test.ts
+npm test  # Full suite
+```
+
+## Code Review
+
+Code review completed with all feedback addressed:
+- Documented intentionally broad PII patterns (prioritize safety)
+- Optimized label deduplication using Set (O(n) vs O(n²))
+- Added clarifying comments for pattern limitations
+
+## Files Modified/Created
+
+### New Files (19 total)
+
+**Core modules**:
+- src/conversations/candidate.schema.json
+- src/conversations/candidates.ts
+- src/conversations/capture.ts
+- src/conversations/classify.ts
+- src/conversations/conversation.schema.json
+- src/conversations/gate.ts
+- src/conversations/index.ts
+- src/conversations/normalize.ts
+- src/conversations/redact.ts
+- src/conversations/types.ts
+- src/conversations/README.md
+
+**Emitters**:
+- src/conversations/emitters/fs.ts
+- src/conversations/emitters/github.ts
+
+**CLI**:
+- src/cli/commands/conversations.ts
+
+**Tests & Fixtures**:
+- src/__tests__/conversations.test.ts
+- test/fixtures/conversations/bug-report.json
+- test/fixtures/conversations/feature-request.json
+- test/fixtures/conversations/question.json
+
+### Modified Files
+
+- src/cli/index.ts (added conversations commands)
+- .gitignore (added .demo/)
+
+## Compliance with Praxis Decision Ledger
+
+This implementation follows the Praxis Decision Ledger dogfooding guidelines:
+- Deterministic implementation (no LLM dependencies)
+- Comprehensive test coverage
+- Clear contracts and schemas
+- Documentation for all public APIs
+
+## Future Enhancements
+
+Potential improvements for future iterations:
+- Additional emitters (Slack, Discord, email)
+- More sophisticated classification rules
+- Duplicate detection against real GitHub issues
+- Custom PII patterns via configuration
+- Batch processing support
+
+## Conclusion
+
+The praxis-conversations subsystem has been successfully implemented with:
+- Complete deterministic pipeline
+- Hard-gated GitHub emitter
+- Comprehensive tests and documentation
+- Zero security vulnerabilities
+- All code review feedback addressed
+
+The subsystem is ready for use and follows all Praxis framework conventions.