@plures/praxis 1.0.3 → 1.1.1

package/docs/core/code-canvas-sync.md

@@ -10,18 +10,18 @@ flowchart LR
         PSF[schema.psf.json]
         TS[TypeScript Files]
     end
-    
+
     subgraph Sync["Sync Engine"]
         Parser[PSF Parser]
         Generator[Code Generator]
         Watcher[File Watcher]
     end
-    
+
     subgraph Canvas["CodeCanvas (Visual)"]
         Visual[Visual Editor]
         Preview[Live Preview]
     end
-    
+
     PSF <--> Parser
     Parser <--> Visual
     Visual --> Generator
@@ -48,6 +48,7 @@ flowchart LR
 ### Hybrid Workflow
 
 Work in both modes simultaneously:
+
 - Use Canvas for visual design and high-level structure
 - Use code editor for detailed logic and fine-tuning
 - Changes sync automatically in both directions
@@ -75,23 +76,23 @@ export const config: CanvasConfig = {
   sync: {
     // Enable bidirectional sync
     enabled: true,
-    
+
     // Watch for file changes
     watchFiles: true,
-    
+
     // Debounce time for file changes (ms)
     debounce: 500,
-    
+
     // How to handle conflicts
-    conflictResolution: 'ask',  // 'ask' | 'canvas' | 'code' | 'merge'
-    
+    conflictResolution: 'ask', // 'ask' | 'canvas' | 'code' | 'merge'
+
     // Auto-regenerate code on Canvas changes
     autoGenerate: true,
-    
+
     // Files to generate
     generateTargets: ['types', 'components', 'docs'],
   },
-  
+
   // Code generation settings
   generation: {
     output: './src/generated',
@@ -109,11 +110,13 @@ export const config: CanvasConfig = {
 With `watchFiles: true`, changes sync in real-time:
 
 **Code → Canvas:**
+
 - Edit `schema.psf.json` in VS Code
 - Save the file
 - Canvas updates within 500ms (configurable debounce)
 
 **Canvas → Code:**
+
 - Make changes in Canvas visual editor
 - Click "Save" or auto-save triggers
 - `schema.psf.json` updates immediately
@@ -140,18 +143,21 @@ Shows a dialog to choose which version to keep:
 #### `'canvas'`
 
 Canvas changes always win:
+
 - Canvas overwrites code changes
 - Safe when primarily designing visually
 
 #### `'code'`
 
 Code changes always win:
+
 - Code overwrites Canvas changes
 - Safe when primarily coding
 
 #### `'merge'`
 
 Attempts to merge changes:
+
 - Works for independent changes (different models, components)
 - Conflicts still require manual resolution
 
@@ -235,7 +241,7 @@ canvas.on('sync:complete', (result) => {
 canvas.on('sync:conflict', (conflict) => {
   console.log('Conflict:', conflict);
   // Handle conflict programmatically
-  conflict.resolve('canvas');  // or 'code' or custom merge
+  conflict.resolve('canvas'); // or 'code' or custom merge
 });
 ```
 
@@ -319,11 +325,13 @@ When merging branches with schema changes:
 Choose whether to commit generated files:
 
 **Commit generated files:**
+
 - ✅ Works without build step
 - ✅ Code review shows generated changes
 - ❌ More merge conflicts
 
 **.gitignore generated files:**
+
 - ✅ Cleaner commits
 - ✅ Fewer conflicts
 - ❌ Requires build step
@@ -365,11 +373,13 @@ Add to your project README:
 ## Development
 
 ### Visual Development
+
 \`\`\`bash
 praxis canvas ./src/schema.psf.json
 \`\`\`
 
 ### Code Generation
+
 \`\`\`bash
 praxis generate --schema ./src/schema.psf.json
 \`\`\`
@@ -380,11 +390,13 @@ praxis generate --schema ./src/schema.psf.json
 ### Sync Not Working
 
 1. **Check Canvas is running:**
+
    ```bash
    praxis canvas status
    ```
 
 2. **Check file watcher:**
+
    ```bash
    praxis canvas --debug
    ```
@@ -427,15 +439,15 @@ const handler = createSyncHandler({
   // Called when code changes
   onCodeChange: async (schema) => {
     // Custom logic before Canvas update
-    return schema;  // Transformed schema
+    return schema; // Transformed schema
   },
-  
+
   // Called when Canvas changes
   onCanvasChange: async (schema) => {
     // Custom logic before code update
-    return schema;  // Transformed schema
+    return schema; // Transformed schema
   },
-  
+
   // Custom conflict resolution
   onConflict: async (local, remote) => {
     // Return merged schema
@@ -457,7 +469,7 @@ const watcher = createPSFWatcher('./schema.psf.json');
 watcher.on('change', async (schema) => {
   // Update external system (e.g., database, API)
   await updateExternalSystem(schema);
-  
+
   // Notify other tools
   eventBus.emit('schema-updated', schema);
 });

package/docs/core/logic-engine.md

@@ -12,7 +12,9 @@ Facts are typed propositions about your domain. They represent "what is true" or
 import { defineFact } from '@plures/praxis';
 
 // Define a fact type
-const UserLoggedIn = defineFact<'UserLoggedIn', { userId: string; timestamp: number }>('UserLoggedIn');
+const UserLoggedIn = defineFact<'UserLoggedIn', { userId: string; timestamp: number }>(
+  'UserLoggedIn'
+);
 
 // Create a fact instance
 const fact = UserLoggedIn.create({ userId: 'user-123', timestamp: Date.now() });
@@ -25,12 +27,12 @@ if (UserLoggedIn.is(someFact)) {
 
 #### Fact Properties
 
-| Property | Type | Description |
-|----------|------|-------------|
-| `tag` | string | Unique identifier for the fact type |
-| `payload` | object | Data associated with the fact |
-| `timestamp` | number | When the fact was created |
-| `metadata` | object | Optional additional metadata |
+| Property    | Type   | Description                         |
+| ----------- | ------ | ----------------------------------- |
+| `tag`       | string | Unique identifier for the fact type |
+| `payload`   | object | Data associated with the fact       |
+| `timestamp` | number | When the fact was created           |
+| `metadata`  | object | Optional additional metadata        |
 
 ### Events
 
@@ -62,39 +64,41 @@ const loginRule = defineRule<AuthContext>({
   impl: (state, events) => {
     const loginEvent = events.find(Login.is);
     if (!loginEvent) return [];
-    
+
     // Validate credentials (pure logic only)
-    const user = state.context.users.find(u => 
-      u.username === loginEvent.payload.username
-    );
-    
+    const user = state.context.users.find((u) => u.username === loginEvent.payload.username);
+
     if (user) {
       // Modify state (within the pure function)
       state.context.currentUser = user;
-      
+
       // Return facts to emit
-      return [UserLoggedIn.create({ 
-        userId: user.id, 
-        timestamp: Date.now() 
-      })];
+      return [
+        UserLoggedIn.create({
+          userId: user.id,
+          timestamp: Date.now(),
+        }),
+      ];
     }
-    
-    return [LoginFailed.create({ 
-      reason: 'Invalid credentials' 
-    })];
+
+    return [
+      LoginFailed.create({
+        reason: 'Invalid credentials',
+      }),
+    ];
   },
 });
 ```
 
 #### Rule Properties
 
-| Property | Type | Required | Description |
-|----------|------|----------|-------------|
-| `id` | string | Yes | Unique rule identifier |
-| `description` | string | Yes | What the rule does |
-| `impl` | function | Yes | Pure function implementation |
-| `priority` | number | No | Execution order (higher = first) |
-| `triggers` | string[] | No | Event types that activate this rule |
+| Property      | Type     | Required | Description                         |
+| ------------- | -------- | -------- | ----------------------------------- |
+| `id`          | string   | Yes      | Unique rule identifier              |
+| `description` | string   | Yes      | What the rule does                  |
+| `impl`        | function | Yes      | Pure function implementation        |
+| `priority`    | number   | No       | Execution order (higher = first)    |
+| `triggers`    | string[] | No       | Event types that activate this rule |
 
 ### Constraints
 
@@ -114,13 +118,13 @@ const positiveBalance = defineConstraint<BankContext>({
 
 #### Constraint Properties
 
-| Property | Type | Required | Description |
-|----------|------|----------|-------------|
-| `id` | string | Yes | Unique constraint identifier |
-| `description` | string | Yes | What the constraint ensures |
-| `check` | function | Yes | Returns true if valid |
-| `errorMessage` | string | Yes | Error when violated |
-| `severity` | string | Yes | `error` or `warning` |
+| Property       | Type     | Required | Description                  |
+| -------------- | -------- | -------- | ---------------------------- |
+| `id`           | string   | Yes      | Unique constraint identifier |
+| `description`  | string   | Yes      | What the constraint ensures  |
+| `check`        | function | Yes      | Returns true if valid        |
+| `errorMessage` | string   | Yes      | Error when violated          |
+| `severity`     | string   | Yes      | `error` or `warning`         |
 
 ## Creating an Engine
 
@@ -155,20 +159,20 @@ const engine = createPraxisEngine({
 const engine = createPraxisEngine({
   // Required: Initial application state
   initialContext: { count: 0 },
-  
+
   // Required: Registry with rules and constraints
   registry,
-  
+
   // Optional: Enable history for undo/redo
   enableHistory: true,
   maxHistorySize: 100,
-  
+
   // Optional: Custom reducer for state transitions
   reducer: (state, event) => {
     // Custom state transition logic
     return state;
   },
-  
+
   // Optional: Middleware
   middleware: [
     (state, events, next) => {
@@ -176,7 +180,7 @@ const engine = createPraxisEngine({
       const result = next(state, events);
       console.log('After:', result);
       return result;
-    }
+    },
   ],
 });
 ```
@@ -207,20 +211,20 @@ For more control, use the step function directly:
 ```typescript
 const result = engine.step([Login.create({ username: 'alice', password: 'secret' })]);
 
-console.log(result.state.context);  // Updated context
-console.log(result.state.facts);    // Emitted facts
-console.log(result.effects);        // Side effects to execute
-console.log(result.violations);     // Constraint violations
+console.log(result.state.context); // Updated context
+console.log(result.state.facts); // Emitted facts
+console.log(result.effects); // Side effects to execute
+console.log(result.violations); // Constraint violations
 ```
 
 ### Step Result
 
-| Property | Type | Description |
-|----------|------|-------------|
+| Property        | Type   | Description               |
+| --------------- | ------ | ------------------------- |
 | `state.context` | object | Updated application state |
-| `state.facts` | array | Facts emitted by rules |
-| `effects` | array | Side effects to execute |
-| `violations` | array | Constraint violations |
+| `state.facts`   | array  | Facts emitted by rules    |
+| `effects`       | array  | Side effects to execute   |
+| `violations`    | array  | Constraint violations     |
 
 ## State Management
 
@@ -233,9 +237,9 @@ const state1 = engine.getState();
 engine.dispatch([Increment.create({})]);
 const state2 = engine.getState();
 
-console.log(state1 === state2);  // false
-console.log(state1.context.count);  // 0
-console.log(state2.context.count);  // 1
+console.log(state1 === state2); // false
+console.log(state1.context.count); // 0
+console.log(state2.context.count); // 1
 ```
 
 ### Subscriptions
@@ -263,18 +267,18 @@ const engine = createPraxisEngine({
   enableHistory: true,
 });
 
-engine.dispatch([Increment.create({})]);  // count: 1
-engine.dispatch([Increment.create({})]);  // count: 2
+engine.dispatch([Increment.create({})]); // count: 1
+engine.dispatch([Increment.create({})]); // count: 2
 
-engine.undo();  // count: 1
-engine.redo();  // count: 2
+engine.undo(); // count: 1
+engine.redo(); // count: 2
 
 // Access history
 const snapshots = engine.getSnapshots();
-console.log(snapshots.length);  // 3 (initial + 2 changes)
+console.log(snapshots.length); // 3 (initial + 2 changes)
 
 // Go to specific snapshot
-engine.goToSnapshot(0);  // count: 0
+engine.goToSnapshot(0); // count: 0
 ```
 
 ## Rule Execution
@@ -318,7 +322,7 @@ Facts emitted by rules can trigger other rules:
 const loginRule = defineRule({
   id: 'auth.login',
   triggers: ['LOGIN'],
-  impl: (state, events) => [UserLoggedIn.create({ userId: '123' })]
+  impl: (state, events) => [UserLoggedIn.create({ userId: '123' })],
 });
 
 // Rule 2: UserLoggedIn triggers welcome notification
@@ -326,12 +330,12 @@ const welcomeRule = defineRule({
   id: 'notify.welcome',
   impl: (state, events) => {
     // This runs after loginRule because facts are processed
-    const loggedIn = state.facts.find(f => f.tag === 'UserLoggedIn');
+    const loggedIn = state.facts.find((f) => f.tag === 'UserLoggedIn');
     if (loggedIn) {
       return [ShowNotification.create({ message: 'Welcome!' })];
     }
     return [];
-  }
+  },
 });
 ```
 
@@ -358,14 +362,14 @@ if (result.violations.length > 0) {
 ```typescript
 const softConstraint = defineConstraint({
   id: 'warn.lowBalance',
-  severity: 'warning',  // Allows state change, logs warning
+  severity: 'warning', // Allows state change, logs warning
   check: (state) => state.context.balance > 100,
   errorMessage: 'Balance is getting low',
 });
 
 const hardConstraint = defineConstraint({
   id: 'error.overdraft',
-  severity: 'error',  // Prevents state change
+  severity: 'error', // Prevents state change
   check: (state) => state.context.balance >= 0,
   errorMessage: 'Insufficient funds',
 });
@@ -410,7 +414,7 @@ for (const fact of result.state.facts) {
 ```typescript
 // Get all registered rules
 const rules = registry.getRules();
-console.log(rules.map(r => r.id));
+console.log(rules.map((r) => r.id));
 
 // Get all constraints
 const constraints = registry.getConstraints();
@@ -447,12 +451,7 @@ For isolated stateful units:
 ```typescript
 import { createActor, createActorSystem } from '@plures/praxis';
 
-const counterActor = createActor(
-  'counter-1',
-  { count: 0 },
-  counterStepFunction,
-  'counter'
-);
+const counterActor = createActor('counter-1', { count: 0 }, counterStepFunction, 'counter');
 
 const system = createActorSystem();
 system.register(counterActor);
@@ -495,16 +494,16 @@ Rules should have no side effects:
 // ❌ Bad: Side effect in rule
 const badRule = defineRule({
   impl: (state, events) => {
-    fetch('/api/data');  // Side effect!
+    fetch('/api/data'); // Side effect!
     return [];
-  }
+  },
 });
 
 // ✅ Good: Return effect descriptor
 const goodRule = defineRule({
   impl: (state, events) => {
     return [FetchDataRequested.create({ url: '/api/data' })];
-  }
+  },
 });
 ```
 
@@ -534,7 +533,7 @@ const typedRule = defineRule<AppContext>({
     // TypeScript knows the shape of state.context
     const user = state.context.user;
     return [];
-  }
+  },
 });
 ```
 
@@ -549,14 +548,10 @@ describe('Login Rule', () => {
       initialContext: { users: [{ username: 'alice', id: '1' }] },
       registry,
     });
-    
-    const result = engine.step([
-      Login.create({ username: 'alice', password: 'valid' })
-    ]);
-    
-    expect(result.state.facts).toContainEqual(
-      expect.objectContaining({ tag: 'UserLoggedIn' })
-    );
+
+    const result = engine.step([Login.create({ username: 'alice', password: 'valid' })]);
+
+    expect(result.state.facts).toContainEqual(expect.objectContaining({ tag: 'UserLoggedIn' }));
   });
 });
 ```

package/docs/core/pluresdb-integration.md

@@ -5,6 +5,7 @@ PluresDB is Praxis's local-first reactive datastore. This document explains how
 ## Overview
 
 PluresDB provides:
+
 - **Local-first storage**: Data lives on the device
 - **Reactive queries**: Automatic UI updates on data changes
 - **Sync**: Automatic synchronization when connected
@@ -17,18 +18,18 @@ flowchart TB
         Engine[Logic Engine]
         UI[UI Components]
     end
-    
+
     subgraph PluresDB["PluresDB"]
         Local[(Local Store)]
         Sync[Sync Engine]
         CRDT[CRDT Resolver]
     end
-    
+
     subgraph Cloud["Praxis Cloud"]
         Relay[Relay Server]
         Remote[(Remote Store)]
     end
-    
+
     Engine <--> Local
     UI <--> Local
     Local <--> Sync
@@ -57,18 +58,18 @@ import { createPluresDB } from '@plures/praxis';
 const db = createPluresDB({
   // Database name (stored in IndexedDB)
   name: 'my-app-db',
-  
+
   // Schema version (increment to migrate)
   version: 1,
-  
+
   // Collections to create
   collections: ['users', 'posts', 'comments'],
-  
+
   // Sync configuration (optional)
   sync: {
     enabled: true,
     endpoint: 'https://your-sync-server.com',
-    interval: 5000,  // ms
+    interval: 5000, // ms
   },
 });
 ```
@@ -167,10 +168,7 @@ await db.users.updateById('user-123', {
 });
 
 // Update matching documents
-await db.users.updateMany(
-  { role: 'guest' },
-  { $set: { active: false } }
-);
+await db.users.updateMany({ role: 'guest' }, { $set: { active: false } });
 
 // Replace document
 await db.users.replaceById('user-123', {
@@ -199,7 +197,7 @@ PluresDB queries are reactive - they automatically update when data changes.
 ```typescript
 // Subscribe to all users
 const unsubscribe = db.users.subscribe(
-  {},  // Query
+  {}, // Query
   (users) => {
     console.log('Users updated:', users);
   }
@@ -214,10 +212,10 @@ unsubscribe();
 ```svelte
 <script lang="ts">
   import { db } from '../db';
-  
+
   // Reactive query as a store
   const users = db.users.query({});
-  
+
   // Derived query
   const activeUsers = db.users.query({ active: true });
 </script>
@@ -351,10 +349,10 @@ const db = createPluresDB({
       name: 'documents',
       schema: {
         id: { type: 'uuid' },
-        title: { type: 'string', crdt: 'lww' },  // Last-write-wins
-        content: { type: 'string', crdt: 'rga' },  // Sequence CRDT
-        tags: { type: 'array', crdt: 'or-set' },  // Add-wins set
-        viewCount: { type: 'number', crdt: 'counter' },  // Counter
+        title: { type: 'string', crdt: 'lww' }, // Last-write-wins
+        content: { type: 'string', crdt: 'rga' }, // Sequence CRDT
+        tags: { type: 'array', crdt: 'or-set' }, // Add-wins set
+        viewCount: { type: 'number', crdt: 'counter' }, // Counter
       },
     },
   ],
@@ -436,10 +434,7 @@ const db = createPluresDB({
 const posts = await db.posts.find({ authorId: 'user-123' });
 
 // Uses compound index
-const recentPosts = await db.posts.find(
-  { authorId: 'user-123' },
-  { sort: { createdAt: -1 } }
-);
+const recentPosts = await db.posts.find({ authorId: 'user-123' }, { sort: { createdAt: -1 } });
 
 // Uses multikey index for array
 const taggedPosts = await db.posts.find({ tags: 'javascript' });
@@ -456,9 +451,7 @@ From your PSF schema:
   "models": [
     {
       "name": "Post",
-      "fields": [
-        { "name": "authorId", "type": "string" }
-      ],
+      "fields": [{ "name": "authorId", "type": "string" }],
       "relationships": [
         {
           "name": "author",
@@ -476,21 +469,15 @@ From your PSF schema:
 
 ```typescript
 // Include related documents
-const posts = await db.posts.find(
-  {},
-  { include: ['author'] }
-);
+const posts = await db.posts.find({}, { include: ['author'] });
 
 // Each post has author populated
-posts.forEach(post => {
+posts.forEach((post) => {
   console.log(`${post.title} by ${post.author.username}`);
 });
 
 // Nested includes
-const posts = await db.posts.find(
-  {},
-  { include: ['author', 'comments.author'] }
-);
+const posts = await db.posts.find({}, { include: ['author', 'comments.author'] });
 ```
 
 ## Integration with Logic Engine
@@ -560,7 +547,7 @@ engine.subscribe((state) => {
 ```typescript
 const db = createPluresDB({
   name: 'my-app',
-  version: 2,  // Increment version
+  version: 2, // Increment version
   collections: ['users', 'posts'],
   migrations: [
     {
@@ -578,9 +565,12 @@ const db = createPluresDB({
       },
       down: async (db) => {
         // Rollback migration
-        await db.users.updateMany({}, {
-          $unset: { role: true },
-        });
+        await db.users.updateMany(
+          {},
+          {
+            $unset: { role: true },
+          }
+        );
       },
     },
   ],
@@ -601,7 +591,7 @@ const db = createPluresDB({
         username: { type: 'string', required: true },
         email: { type: 'string', required: true, unique: true },
       },
-      validate: true,  // Enable validation
+      validate: true, // Enable validation
     },
   ],
 });