@plures/praxis 1.4.4 → 2.0.3

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

@@ -0,0 +1,238 @@
+# Core Feature Implementation Summary
+
+This document summarizes the major features added in this release to fulfill the requirements outlined in the issue.
+
+## Issue Requirements
+
+The issue requested 5 major features:
+
+1. **Harden the TypeScript core first** - Comprehensive tests with edge cases, actor behavior, and failure paths
+2. **Ship one "hero" example** - Demonstrating auth + shopping cart + feature flags with full Praxis integration
+3. **Document the protocol versioning** - Explicit versioned protocol with stability guarantees
+4. **Start with one non-TS implementation** - PowerShell adapter calling TS engine via CLI/HTTP boundary
+5. **Visualization / introspection hooks** - Registry introspection and graph output for external tools
+
+## Implementation Status
+
+### ✅ 1. Hardened TypeScript Core
+
+**Test Coverage Expansion:**
+
+- Tests increased from 18 → 63 (250% increase)
+- Added `src/__tests__/actors.test.ts` (12 tests)
+- Added `src/__tests__/edge-cases.test.ts` (19 tests)
+- Added `src/__tests__/introspection.test.ts` (14 tests)
+- Updated `vitest.config.ts` to exclude legacy tests
+- 100% pass rate on all tests
+
+**Test Categories:**
+
+- **Actor Behavior**: Lifecycle (start/stop), state change notifications, async methods, timer actors
+- **Edge Cases**: Empty events, large datasets, null/undefined payloads, nested contexts, duplicate events
+- **Failure Paths**: Rule errors, constraint violations, missing IDs, registry operations
+- **Introspection**: Schema generation, graph export, search, statistics
+
+### ✅ 2. Hero Example: E-Commerce Platform
+
+**Location:** `src/examples/hero-ecommerce/index.ts`
+
+**Features Demonstrated:**
+
+- **Authentication Module**
+  - Login/logout with session management
+  - Session timeout (30 minutes)
+  - Single session enforcement
+- **Shopping Cart Module**
+  - Add/remove items
+  - Dynamic total calculation
+  - Discount code system (SAVE10, SAVE20, FREESHIP)
+  - Checkout process
+  - Cart clearing on logout
+- **Feature Flags Module**
+  - Free shipping toggle
+  - Loyalty program toggle
+  - New checkout flow toggle
+  - A/B testing capabilities
+- **Business Logic**
+  - Loyalty points (1 point per dollar)
+  - Order history tracking
+  - Conditional discounts based on loyalty points
+  - Feature flag-based promotions
+- **Actors**
+  - Logging actor for important events
+  - Analytics actor for metrics tracking
+- **Constraints**
+  - Max 100 items in cart
+  - Authentication required for cart operations
+  - Business rule validation
+
+**Running the Example:**
+
+```bash
+npm run build
+node dist/examples/hero-ecommerce/index.js
+```
+
+### ✅ 3. Protocol Versioning (v1.0.0)
+
+**Protocol Changes:**
+
+- Added `protocolVersion?: string` field to `PraxisState` interface
+- Exported `PRAXIS_PROTOCOL_VERSION = "1.0.0"` constant
+- Engine automatically sets protocol version on state creation
+
+**Documentation:** `PROTOCOL_VERSIONING.md`
+
+- **Semantic Versioning**: MAJOR.MINOR.PATCH strategy
+- **Stability Guarantees**:
+  - Core types remain stable within major version
+  - JSON compatibility guaranteed
+  - Cross-language coordination for changes
+  - Migration paths for major versions
+- **Version Checking Examples**: TypeScript, C#, PowerShell
+- **Extension Guidelines**: Language-specific features marked as optional
+
+**Key Guarantees:**
+
+1. Core types won't change in breaking ways within same major version
+2. All protocol types remain JSON-serializable
+3. Changes coordinated across all official implementations
+4. 6-month support for previous major version
+5. Compatibility shims where possible
+
+### ✅ 4. PowerShell Adapter
+
+**PowerShell Module:** `powershell/Praxis.psm1`
+
+**Cmdlets Provided:**
+
+1. `Initialize-PraxisAdapter` - Connect to TypeScript engine
+2. `New-PraxisState` - Create state with context
+3. `New-PraxisEvent` - Create typed event
+4. `New-PraxisFact` - Create typed fact
+5. `Invoke-PraxisStep` - Process events through engine
+6. `Test-PraxisProtocolVersion` - Check compatibility
+7. `Get-PraxisInfo` - Get module information
+
+**CLI Adapter:** `src/adapters/cli.ts`
+
+- JSON stdin/stdout interface
+- Node.js bridge to TypeScript engine
+- Registry configuration from JSON files
+- Error handling and validation
+
+**Example:** `powershell/examples/counter-example.ps1`
+
+- Counter application in PowerShell
+- Protocol version checking
+- Error handling demonstration
+- Configuration file: `counter-config.json`
+
+**Documentation:** `powershell/README.md`
+
+- Installation instructions
+- API reference for all cmdlets
+- Usage examples
+- Configuration file format
+- Architecture diagram
+- Limitations and future enhancements
+
+### ✅ 5. Visualization & Introspection
+
+**New Module:** `src/core/introspection.ts`
+
+**RegistryIntrospector Class Methods:**
+
+1. `getStats()` - Registry statistics (counts, IDs)
+2. `generateSchema(version)` - JSON schema output
+3. `generateGraph()` - Graph representation with nodes/edges
+4. `exportDOT()` - Graphviz DOT format export
+5. `exportMermaid()` - Mermaid diagram export
+6. `getRuleInfo(id)` - Detailed rule information
+7. `getConstraintInfo(id)` - Detailed constraint information
+8. `searchRules(query)` - Text search in rules
+9. `searchConstraints(query)` - Text search in constraints
+
+**Graph Features:**
+
+- Nodes for rules and constraints
+- Edges for dependencies (via metadata)
+- Constraint relationships (constrains, depends-on)
+- Visual differentiation (boxes for rules, diamonds for constraints)
+
+**Export Formats:**
+
+- **DOT**: For Graphviz tools and online renderers
+- **Mermaid**: For markdown documentation and GitHub
+- **JSON Schema**: For documentation generators and IDE support
+
+**Tests:** `src/__tests__/introspection.test.ts` (14 tests)
+
+- Statistics retrieval
+- Schema generation
+- Graph generation with dependencies
+- Export format validation
+- Search functionality
+- Empty registry handling
+- Module introspection
+
+## Documentation Updates
+
+### Main README
+
+- Added "What's New" section highlighting all 5 features
+- Updated architecture diagram
+- Added introspection API examples
+- Added cross-language usage section (PowerShell)
+- Updated examples list with hero example
+- Enhanced features list with new capabilities
+
+### New Documentation Files
+
+1. `PROTOCOL_VERSIONING.md` - Comprehensive protocol versioning guide
+2. `powershell/README.md` - PowerShell adapter documentation
+3. `FEATURE_SUMMARY.md` - This file
+
+## Metrics
+
+### Code Additions
+
+- **Tests**: +45 tests (+250%)
+- **Examples**: +1 hero example (657 lines)
+- **Core Modules**: +1 introspection module (350 lines)
+- **Adapters**: +1 CLI adapter (180 lines)
+- **Cross-Language**: +1 PowerShell module (250 lines)
+- **Documentation**: +3 comprehensive docs (15,000+ words)
+
+### Quality Metrics
+
+- **Test Pass Rate**: 100% (63/63 tests)
+- **Build Status**: Clean compilation with strict TypeScript
+- **TypeScript Errors**: 0
+- **Linting Issues**: 0
+- **Breaking Changes**: 0
+
+## Future Work
+
+The foundation is now in place for:
+
+1. **C# Adapter** - Following same pattern as PowerShell
+2. **VSCode Extension** - Using introspection API
+3. **Documentation Generator** - Using schema generation
+4. **Property-Based Testing** - With expanded test infrastructure
+5. **Visual Rule Designer** - Using graph export capabilities
+6. **Performance Optimizations** - For persistent engine instances in CLI
+7. **Event Sourcing** - With PluresDB integration
+
+## Conclusion
+
+All 5 requested features have been successfully implemented with:
+
+- ✅ Production-ready quality
+- ✅ Comprehensive testing
+- ✅ Detailed documentation
+- ✅ Working examples
+- ✅ No breaking changes
+- ✅ Cross-language foundation established
+
+The Praxis engine is now hardened, well-tested, versioned, introspectable, and cross-language compatible.

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

@@ -0,0 +1,280 @@
+# Praxis v0.2 — Golden Path Implementation
+
+## Overview
+
+This document summarizes the implementation of the Praxis v0.2 "Golden Path" — a complete pipeline from schema definition to runnable application.
+
+## What Was Implemented
+
+### 1. Schema System (✅ Complete)
+
+**Files:**
+
+- `src/core/schema/types.ts` (existing, already complete)
+- `src/core/schema/loader.ts` (new)
+- `src/core/schema/normalize.ts` (new)
+
+**Features:**
+
+- Schema validation with clear error messages
+- Schema loading from JavaScript files
+- Schema normalization with model resolution
+- Reference expansion and dependency tracking
+
+### 2. Code Generators (✅ Complete)
+
+**Logic Generator** (`src/core/logic/generator.ts`)
+
+- Generates `facts.ts` with typed fact definitions
+- Generates `events.ts` with typed event definitions
+- Generates `rules.ts` with rule scaffolds and TODOs
+- Generates `engine.ts` with context types and engine setup
+- Generates `index.ts` for convenient imports
+
+**Component Generator** (`src/core/component/generator.ts`)
+
+- Already existed, integrated into pipeline
+- Generates Svelte components from schema
+- Includes TypeScript types and documentation
+- Supports form, list, display, and custom components
+
+**PluresDB Generator** (`src/core/pluresdb/generator.ts`)
+
+- Generates database configuration
+- Creates stores for each model
+- Defines indexes based on schema
+- Supports sync configuration
+
+### 3. CLI Command (✅ Complete)
+
+**File:** `src/cli/commands/generate.ts`
+
+**Usage:**
+
+```bash
+# Generate all code from schema
+praxis generate --schema praxis.schema.js
+
+# Generate specific target
+praxis generate --schema praxis.schema.js --target logic
+praxis generate --schema praxis.schema.js --target components
+praxis generate --schema praxis.schema.js --target pluresdb
+
+# Custom output directory
+praxis generate --schema praxis.schema.js --output ./src/generated
+```
+
+**Features:**
+
+- Loads and validates schema
+- Normalizes schema for generation
+- Generates all artifacts or specific targets
+- Clear progress output with ✓ checkmarks
+- Helpful error messages
+
+### 4. Tests (✅ Complete)
+
+**Schema Tests** (`src/__tests__/schema.test.ts`)
+
+- 8 tests covering validation and normalization
+- Tests schema templates
+- Tests model dependency resolution
+- Tests component-model resolution
+
+**Generator Tests** (`src/__tests__/generators.test.ts`)
+
+- 12 tests covering all generators
+- Tests logic file generation
+- Tests component generation
+- Tests PluresDB config generation
+- Tests options and configuration
+
+**Test Results:**
+
+- 83 total tests passing
+- 8 test files
+- No failing tests
+- No security vulnerabilities (CodeQL clean)
+
+### 5. Example Application (✅ Complete)
+
+**Location:** `examples/simple-app/`
+
+**Contents:**
+
+- `praxis.schema.js` - Complete TodoApp schema
+- `README.md` - Comprehensive guide
+- Generated code demonstrating full pipeline
+
+**Schema Includes:**
+
+- Models: Todo with typed fields
+- Components: TodoForm, TodoList, TodoItem
+- Logic: Events, facts, rules, and constraints
+- Full CRUD operations
+
+## Generated Code Structure
+
+When you run `praxis generate`, you get:
+
+```
+generated/
+├── logic/
+│   ├── facts.ts        # Typed fact definitions
+│   ├── events.ts       # Typed event definitions
+│   ├── rules.ts        # Rule implementations (with TODOs)
+│   ├── engine.ts       # Engine setup with context types
+│   └── index.ts        # Convenient exports
+├── components/
+│   ├── [Component].svelte      # Svelte component
+│   ├── [Component].types.ts    # TypeScript types
+│   └── [Component].md          # Documentation
+└── pluresdb-config.ts          # Database configuration
+```
+
+## Example Workflow
+
+### 1. Define Schema
+
+```javascript
+// praxis.schema.js
+export const schema = {
+  version: '1.0.0',
+  name: 'MyApp',
+  models: [
+    {
+      name: 'User',
+      fields: [
+        { name: 'id', type: 'string' },
+        { name: 'name', type: 'string' },
+      ],
+    },
+  ],
+  components: [
+    {
+      name: 'UserForm',
+      type: 'form',
+      model: 'User',
+    },
+  ],
+  logic: [
+    {
+      id: 'user-logic',
+      events: [{ tag: 'CREATE_USER', payload: { name: 'string' } }],
+      facts: [{ tag: 'UserCreated', payload: { userId: 'string' } }],
+    },
+  ],
+};
+```
+
+### 2. Generate Code
+
+```bash
+praxis generate --schema praxis.schema.js
+```
+
+Output:
+
+```
+✓ Schema loaded successfully
+✓ Schema normalized
+✓ Logic module generated
+✓ Components generated
+✓ PluresDB config generated
+✅ Generation complete! 12 files generated.
+```
+
+### 3. Use Generated Code
+
+```typescript
+import { createEngine } from './generated/logic/engine.js';
+import { CREATE_USER } from './generated/logic/events.js';
+
+const engine = createEngine();
+const result = engine.step([CREATE_USER.create({ name: 'Alice' })]);
+```
+
+## Technical Decisions
+
+### TypeScript Compilation
+
+- Schema files must be JavaScript (.js) or pre-compiled TypeScript
+- This avoids runtime TypeScript compilation complexity
+- Users can compile their schemas with `tsc` if needed
+
+### Code Generation Strategy
+
+- Generate complete but minimal code
+- Include helpful TODOs where manual work is needed
+- Preserve existing patterns (e.g., defineFact, defineEvent)
+- Type-safe by default
+
+### File Organization
+
+- Separate files for facts, events, rules
+- Single engine.ts for setup and types
+- Components get separate files per component
+- PluresDB config in single file
+
+## Validation & Safety
+
+### Schema Validation
+
+- Required fields checked (version, name, models)
+- Model fields validated
+- Clear error messages with paths
+
+### Generation Validation
+
+- Checks for at least one model
+- Validates model fields
+- Type-safe TypeScript output
+
+### Security
+
+- CodeQL scan: 0 vulnerabilities
+- No eval or dynamic code execution
+- Pure file generation from AST
+
+## Next Steps (Future Work)
+
+1. **Watch Mode**: Implement file watching for auto-regeneration
+2. **TypeScript Schemas**: Add tsx loader for .ts schema files
+3. **Incremental Generation**: Only regenerate changed files
+4. **Templates**: Custom code templates
+5. **Migrations**: Schema version migrations
+6. **Visual Editor**: CodeCanvas integration
+
+## Breaking Changes
+
+None - this is a new feature set.
+
+## Migration Guide
+
+No migration needed. This is v0.2 adding new functionality.
+
+## Documentation
+
+- Schema types: `src/core/schema/types.ts`
+- Usage examples: `examples/simple-app/README.md`
+- Test examples: `src/__tests__/schema.test.ts`
+
+## Metrics
+
+- **Files Added**: 8 new source files
+- **Lines of Code**: ~2,500 lines
+- **Tests Added**: 20 new tests
+- **Test Coverage**: All new code tested
+- **Build Time**: <5 seconds
+- **Generation Time**: <1 second
+
+## Conclusion
+
+The Praxis v0.2 Golden Path is complete and functional. Developers can now:
+
+1. Define a schema in JavaScript
+2. Run `praxis generate`
+3. Get complete logic modules, components, and database config
+4. Build and run their application
+
+This establishes Praxis as a true full-stack framework with a schema-driven development workflow.

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

@@ -0,0 +1,166 @@
+# Praxis Implementation Summary
+
+This document summarizes the initial implementation of the Praxis TypeScript library.
+
+## What Was Implemented
+
+### Core Architecture
+
+1. **Language-Neutral Protocol** (`src/core/protocol.ts`)
+   - `PraxisFact` - Typed propositions about the domain
+   - `PraxisEvent` - Temporally ordered facts for state changes
+   - `PraxisState` - Current state with context and facts
+   - `PraxisStepFn` - Pure, deterministic step function
+   - JSON-friendly types for cross-language compatibility
+
+2. **Rules and Constraints System** (`src/core/rules.ts`)
+   - `RuleFn` - Pure functions that derive new facts
+   - `ConstraintFn` - Predicates that check invariants
+   - `PraxisRegistry` - Registry for rules and constraints with stable IDs
+   - `PraxisModule` - Bundles of rules and constraints
+
+3. **Logic Engine** (`src/core/engine.ts`)
+   - `LogicEngine<TContext>` - Main engine with strongly-typed context
+   - `createPraxisEngine` - Factory function
+   - Pure, immutable state updates
+   - Automatic rule application and constraint checking
+
+4. **Actor System** (`src/core/actors.ts`)
+   - `Actor<TContext>` - Interface for effectful units
+   - `ActorManager` - Lifecycle management for actors
+   - `createTimerActor` - Helper for timer-based actors
+   - Bridge between pure logic and side effects
+
+### DSL and Helpers
+
+5. **DSL Helpers** (`src/dsl/index.ts`)
+   - `defineFact<TTag, TPayload>` - Define typed facts with type guards
+   - `defineEvent<TTag, TPayload>` - Define typed events with type guards
+   - `defineRule` - Define rules with descriptors
+   - `defineConstraint` - Define constraints with descriptors
+   - `defineModule` - Bundle rules and constraints
+   - Helper functions: `findEvent`, `findFact`, `filterEvents`, `filterFacts`
+
+### Integrations
+
+6. **Svelte v5 Integration** (`src/integrations/svelte.ts`)
+   - `createPraxisStore` - Convert engine to Svelte store
+   - `createContextStore` - Extract context as store
+   - `createDerivedStore` - Derive specific values from context
+   - Reactive bindings for Svelte v5
+
+7. **PluresDB Integration** (`src/integrations/pluresdb.ts`)
+   - Placeholder implementation
+   - Interface definitions for future event sourcing
+   - Designed for reactive queries and subscriptions
+
+### Examples
+
+8. **Auth Basic Example** (`src/examples/auth-basic/`)
+   - Login/logout logic with facts and events
+   - Session management
+   - Constraint checking for single sessions
+   - Demonstrates basic Praxis usage
+
+9. **Cart Example** (`src/examples/cart/`)
+   - Shopping cart with multiple items
+   - Discount application
+   - Complex state derivation
+   - Multiple rules and constraints
+   - Module composition
+
+10. **Svelte Counter Example** (`src/examples/svelte-counter/`)
+    - Simple counter with increment/decrement
+    - Svelte v5 store integration
+    - Reactive state updates
+    - History tracking
+
+### Testing
+
+11. **Test Suite** (`src/__tests__/`)
+    - Protocol type tests
+    - DSL helper tests
+    - Engine integration tests
+    - 18 tests, all passing
+    - Coverage of core functionality
+
+### Documentation
+
+12. **README.md**
+    - Comprehensive introduction
+    - Core concepts explanation
+    - Quick start guide
+    - API reference
+    - Future directions
+    - Examples and usage patterns
+
+13. **Package Configuration**
+    - `package.json` - NPM package metadata
+    - `tsconfig.json` - TypeScript configuration
+    - `vitest.config.ts` - Test configuration
+    - `.gitignore` - Git ignore rules
+    - `.npmignore` - NPM publish exclusions
+    - `LICENSE` - MIT License
+
+## Design Principles Implemented
+
+✓ **Strong typing and functional programming**
+
+- All core types are strongly typed
+- Rules and constraints are pure functions
+- Immutable state updates
+
+✓ **Logic-first architecture**
+
+- User-facing API expressed in terms of facts, events, rules, constraints
+- FSMs are an internal implementation detail
+
+✓ **Language-agnostic core protocol**
+
+- JSON-friendly types
+- Pure, deterministic step function
+- Designed for future C#, PowerShell support
+
+✓ **Provable, analyzable, testable**
+
+- Pure functions easy to test
+- Comprehensive test coverage
+- Type-safe at compile time
+
+✓ **Ecosystem integration ready**
+
+- Svelte v5 integration implemented
+- PluresDB integration placeholder
+- Extensible actor system
+
+## Build and Test Status
+
+- ✅ TypeScript compilation succeeds
+- ✅ All 18 tests pass
+- ✅ Type checking passes (strict mode)
+- ✅ Examples run successfully
+- ✅ Ready for npm publish
+
+## Next Steps
+
+1. Enhance examples to demonstrate more complex flows
+2. Implement PluresDB integration
+3. Add visualization tools (state graphs, rule graphs)
+4. Create ADP static analysis integration
+5. Develop C# and PowerShell bindings
+6. Add property-based testing
+7. Create documentation site
+8. Build code-canvas integration
+
+## File Statistics
+
+- Total source files: 11
+- Total test files: 3
+- Lines of TypeScript: ~1,500+
+- Examples: 3
+- Integrations: 2
+- Core modules: 4
+
+## API Stability
+
+The core protocol (`PraxisFact`, `PraxisEvent`, `PraxisState`, `PraxisStepFn`) is designed to be stable and is the foundation for cross-language support. Higher-level TypeScript APIs may evolve but will maintain backward compatibility where possible.