@plures/praxis 1.0.2 → 1.1.0

package/src/core/pluresdb/index.ts

@@ -1,16 +1,16 @@
 /**
  * PluresDB Integration Module
- * 
+ *
  * This module exports all PluresDB-related types and functions for Praxis.
  * It provides the core adapter layer, store, and schema registry.
  */
 
 // Adapter - Core interface and in-memory implementation
-export type { PraxisDB, UnsubscribeFn } from "./adapter.js";
-export { InMemoryPraxisDB, createInMemoryDB } from "./adapter.js";
+export type { PraxisDB, UnsubscribeFn } from './adapter.js';
+export { InMemoryPraxisDB, createInMemoryDB } from './adapter.js';
 
 // Store - Manages facts, events, and reactive updates
-export type { EventStreamEntry, PraxisDBStoreOptions, RuleErrorHandler } from "./store.js";
+export type { EventStreamEntry, PraxisDBStoreOptions, RuleErrorHandler } from './store.js';
 export {
   PraxisDBStore,
   createPraxisDBStore,
@@ -18,20 +18,17 @@ export {
   getFactPath,
   getEventPath,
   generateId,
-} from "./store.js";
+} from './store.js';
 
 // Schema Registry - Schema definitions in PluresDB
-export type { StoredSchema } from "./schema-registry.js";
+export type { StoredSchema } from './schema-registry.js';
 export {
   PraxisSchemaRegistry,
   createSchemaRegistry,
   registerSchema,
   getSchemaPath,
-} from "./schema-registry.js";
+} from './schema-registry.js';
 
 // Config Generator - Generate PluresDB config from schemas
-export type {
-  PluresDBGeneratorOptions,
-  GeneratedPluresDBFile,
-} from "./generator.js";
-export { PluresDBGenerator, createPluresDBGenerator } from "./generator.js";
+export type { PluresDBGeneratorOptions, GeneratedPluresDBFile } from './generator.js';
+export { PluresDBGenerator, createPluresDBGenerator } from './generator.js';

package/src/core/pluresdb/schema-registry.ts

@@ -1,13 +1,13 @@
 /**
  * Praxis Schema Registry for PluresDB
- * 
+ *
  * Registers Praxis schema definitions in PluresDB for type-safe storage
  * and cross-agent schema discovery.
  */
 
-import type { PraxisDB } from "./adapter.js";
-import type { PraxisSchema } from "../schema/types.js";
-import { PRAXIS_PATHS } from "./store.js";
+import type { PraxisDB } from './adapter.js';
+import type { PraxisSchema } from '../schema/types.js';
+import { PRAXIS_PATHS } from './store.js';
 
 /**
  * Get the path for a schema in PluresDB
@@ -31,7 +31,7 @@ export interface StoredSchema {
 
 /**
  * PraxisSchemaRegistry
- * 
+ *
  * Manages schema definitions in PluresDB.
  * Schemas are stored under `/_praxis/schemas/<schemaName>`
  */
@@ -44,24 +44,24 @@ export class PraxisSchemaRegistry {
 
   /**
    * Register a schema in PluresDB
-   * 
+   *
    * @param schema The schema to register
    */
   async register(schema: PraxisSchema): Promise<void> {
     const path = getSchemaPath(schema.name);
-    
+
     const storedSchema: StoredSchema = {
       schema,
       registeredAt: Date.now(),
       version: schema.version,
     };
-    
+
     await this.db.set(path, storedSchema);
   }
 
   /**
    * Get a schema by name
-   * 
+   *
    * @param schemaName The schema name
    * @returns The stored schema or undefined if not found
    */
@@ -72,7 +72,7 @@ export class PraxisSchemaRegistry {
 
   /**
    * Check if a schema is registered
-   * 
+   *
    * @param schemaName The schema name
    * @returns True if the schema exists
    */
@@ -83,7 +83,7 @@ export class PraxisSchemaRegistry {
 
   /**
    * Update a schema (replaces existing)
-   * 
+   *
    * @param schema The updated schema
    */
   async update(schema: PraxisSchema): Promise<void> {
@@ -92,12 +92,12 @@ export class PraxisSchemaRegistry {
 
   /**
    * List all registered schema names
-   * 
+   *
    * Implementation note: This method uses an index stored at `/_praxis/schemas/_index`.
    * When using InMemoryPraxisDB, schemas must be registered using `registerWithIndex()`
    * for them to appear in this listing. When using a full PluresDB implementation,
    * native listing capabilities should be used instead.
-   * 
+   *
    * @returns Array of registered schema names
    */
   async list(): Promise<string[]> {
@@ -108,17 +108,17 @@ export class PraxisSchemaRegistry {
 
   /**
    * Register a schema and update the index
-   * 
+   *
    * @param schema The schema to register
    */
   async registerWithIndex(schema: PraxisSchema): Promise<void> {
     // Register the schema
     await this.register(schema);
-    
+
     // Update the index
     const indexPath = `${PRAXIS_PATHS.SCHEMAS}/_index`;
-    const existingIndex = await this.db.get<string[]>(indexPath) ?? [];
-    
+    const existingIndex = (await this.db.get<string[]>(indexPath)) ?? [];
+
     if (!existingIndex.includes(schema.name)) {
       await this.db.set(indexPath, [...existingIndex, schema.name]);
     }
@@ -127,12 +127,12 @@ export class PraxisSchemaRegistry {
 
 /**
  * Register a schema in PluresDB
- * 
+ *
  * Convenience function for one-off schema registration.
- * 
+ *
  * @param db The PraxisDB instance
  * @param schema The schema to register
- * 
+ *
  * @example
  * ```typescript
  * const db = createInMemoryDB();
@@ -143,17 +143,14 @@ export class PraxisSchemaRegistry {
  * });
  * ```
  */
-export async function registerSchema(
-  db: PraxisDB,
-  schema: PraxisSchema
-): Promise<void> {
+export async function registerSchema(db: PraxisDB, schema: PraxisSchema): Promise<void> {
   const registry = new PraxisSchemaRegistry(db);
   await registry.registerWithIndex(schema);
 }
 
 /**
  * Create a PraxisSchemaRegistry instance
- * 
+ *
  * @param db The PraxisDB instance
  * @returns PraxisSchemaRegistry instance
  */

package/src/core/pluresdb/store.ts

@@ -1,6 +1,6 @@
 /**
  * PraxisDB Store
- * 
+ *
  * Connects Praxis Facts, Events, Rules, and Constraints to PluresDB.
  * Provides CRDT-backed storage for facts and append-only event streams.
  */
@@ -8,22 +8,22 @@
 // Declare process for TypeScript in non-Node environments (e.g., Deno)
 declare const process: { env: { [key: string]: string | undefined } } | undefined;
 
-import type { PraxisDB, UnsubscribeFn } from "./adapter.js";
-import type { PraxisRegistry } from "../rules.js";
-import type { PraxisFact, PraxisEvent, PraxisState } from "../protocol.js";
+import type { PraxisDB, UnsubscribeFn } from './adapter.js';
+import type { PraxisRegistry } from '../rules.js';
+import type { PraxisFact, PraxisEvent, PraxisState } from '../protocol.js';
 
 /**
  * Key paths for Praxis data in PluresDB
  */
 export const PRAXIS_PATHS = {
   /** Base path for all Praxis data */
-  BASE: "/_praxis",
+  BASE: '/_praxis',
   /** Path for facts storage */
-  FACTS: "/_praxis/facts",
+  FACTS: '/_praxis/facts',
   /** Path for events storage */
-  EVENTS: "/_praxis/events",
+  EVENTS: '/_praxis/events',
   /** Path for schema registry */
-  SCHEMAS: "/_praxis/schemas",
+  SCHEMAS: '/_praxis/schemas',
 } as const;
 
 /**
@@ -80,9 +80,9 @@ export interface PraxisDBStoreOptions<TContext = unknown> {
 
 /**
  * PraxisDBStore
- * 
+ *
  * Manages persistence and reactive updates for Praxis state in PluresDB.
- * 
+ *
  * - Facts are stored as CRDT-backed documents under `/_praxis/facts/<factTag>/<id>`
  * - Events are stored as append-only streams under `/_praxis/events/<eventTag>`
  * - Rules are triggered automatically when watched keys change
@@ -98,7 +98,7 @@ export type RuleErrorHandler = (ruleId: string, error: unknown) => void;
  */
 const defaultErrorHandler: RuleErrorHandler = (ruleId, error) => {
   // Default behavior: silent in production, can be overridden
-  if (typeof process !== "undefined" && process.env?.NODE_ENV === "development") {
+  if (typeof process !== 'undefined' && process.env?.NODE_ENV === 'development') {
     console.error(`Error executing rule "${ruleId}":`, error);
   }
 };
@@ -120,10 +120,10 @@ export class PraxisDBStore<TContext = unknown> {
 
   /**
    * Store a fact in PluresDB
-   * 
+   *
    * Facts are stored under `/_praxis/facts/<factTag>/<id>`
    * If no id is provided in the payload, a timestamp-based id is used.
-   * 
+   *
    * @param fact The fact to store
    * @returns Promise that resolves when the fact is stored
    */
@@ -131,31 +131,31 @@ export class PraxisDBStore<TContext = unknown> {
     // Run constraints before storing
     const constraintResult = await this.checkConstraints([fact]);
     if (!constraintResult.valid) {
-      throw new Error(`Constraint violation: ${constraintResult.errors.join(", ")}`);
+      throw new Error(`Constraint violation: ${constraintResult.errors.join(', ')}`);
     }
 
     await this.persistFact(fact);
-    
+
     // Trigger rule evaluation - facts stored directly may trigger derived computations
     await this.triggerRules([fact]);
   }
 
   /**
    * Store multiple facts in PluresDB
-   * 
+   *
    * @param facts The facts to store
    */
   async storeFacts(facts: PraxisFact[]): Promise<void> {
     // Run constraints before storing
     const constraintResult = await this.checkConstraints(facts);
     if (!constraintResult.valid) {
-      throw new Error(`Constraint violation: ${constraintResult.errors.join(", ")}`);
+      throw new Error(`Constraint violation: ${constraintResult.errors.join(', ')}`);
     }
 
     for (const fact of facts) {
       await this.persistFact(fact);
     }
-    
+
     // Trigger rule evaluation
     await this.triggerRules(facts);
   }
@@ -173,7 +173,7 @@ export class PraxisDBStore<TContext = unknown> {
 
   /**
    * Get a fact by tag and id
-   * 
+   *
    * @param factTag The fact type tag
    * @param id The fact id
    * @returns The fact or undefined if not found
@@ -185,35 +185,35 @@ export class PraxisDBStore<TContext = unknown> {
 
   /**
    * Append an event to the event stream
-   * 
+   *
    * Events are stored as append-only streams under `/_praxis/events/<eventTag>`
-   * 
+   *
    * @param event The event to append
    */
   async appendEvent(event: PraxisEvent): Promise<void> {
     const path = getEventPath(event.tag);
-    
+
     // Get existing events for this tag
-    const existingEvents = await this.db.get<EventStreamEntry[]>(path) ?? [];
-    
+    const existingEvents = (await this.db.get<EventStreamEntry[]>(path)) ?? [];
+
     // Create new entry
     const entry: EventStreamEntry = {
       event,
       timestamp: Date.now(),
       sequence: existingEvents.length,
     };
-    
+
     // Append and store
     const newEvents = [...existingEvents, entry];
     await this.db.set(path, newEvents);
-    
+
     // Trigger rules with this event
     await this.triggerRulesForEvents([event]);
   }
 
   /**
    * Append multiple events to their respective streams
-   * 
+   *
    * @param events The events to append
    */
   async appendEvents(events: PraxisEvent[]): Promise<void> {
@@ -223,29 +223,29 @@ export class PraxisDBStore<TContext = unknown> {
       const existing = eventsByTag.get(event.tag) ?? [];
       eventsByTag.set(event.tag, [...existing, event]);
     }
-    
+
     // Append each group
     for (const [tag, tagEvents] of eventsByTag) {
       const path = getEventPath(tag);
-      const existingEvents = await this.db.get<EventStreamEntry[]>(path) ?? [];
+      const existingEvents = (await this.db.get<EventStreamEntry[]>(path)) ?? [];
       let sequence = existingEvents.length;
-      
-      const newEntries = tagEvents.map(event => ({
+
+      const newEntries = tagEvents.map((event) => ({
         event,
         timestamp: Date.now(),
         sequence: sequence++,
       }));
-      
+
       await this.db.set(path, [...existingEvents, ...newEntries]);
     }
-    
+
     // Trigger rules
     await this.triggerRulesForEvents(events);
   }
 
   /**
    * Get events from a stream
-   * 
+   *
    * @param eventTag The event type tag
    * @param options Query options
    * @returns Array of event stream entries
@@ -255,32 +255,32 @@ export class PraxisDBStore<TContext = unknown> {
     options?: { since?: number; limit?: number }
   ): Promise<EventStreamEntry[]> {
     const path = getEventPath(eventTag);
-    const events = await this.db.get<EventStreamEntry[]>(path) ?? [];
-    
+    const events = (await this.db.get<EventStreamEntry[]>(path)) ?? [];
+
     let result = events;
-    
+
     if (options?.since !== undefined) {
       const sinceTimestamp = options.since;
-      result = result.filter(e => e.timestamp > sinceTimestamp);
+      result = result.filter((e) => e.timestamp > sinceTimestamp);
     }
-    
+
     if (options?.limit !== undefined) {
       result = result.slice(-options.limit);
     }
-    
+
     return result;
   }
 
   /**
    * Watch a fact path for changes
-   * 
+   *
    * @param factTag The fact type tag to watch
    * @param callback Called when facts of this type change
    * @returns Unsubscribe function
    */
   watchFacts(factTag: string, callback: (facts: PraxisFact[]) => void): UnsubscribeFn {
     const path = getFactPath(factTag);
-    
+
     // Register the callback
     if (!this.factWatchers.has(factTag)) {
       this.factWatchers.set(factTag, new Set());
@@ -289,14 +289,14 @@ export class PraxisDBStore<TContext = unknown> {
     if (watchers) {
       watchers.add(callback);
     }
-    
+
     // Watch the path in the DB
     const unsubscribe = this.db.watch<PraxisFact>(path, (fact) => {
       callback([fact]);
     });
-    
+
     this.subscriptions.push(unsubscribe);
-    
+
     return () => {
       unsubscribe();
       this.factWatchers.get(factTag)?.delete(callback);
@@ -311,20 +311,20 @@ export class PraxisDBStore<TContext = unknown> {
   ): Promise<{ valid: boolean; errors: string[] }> {
     const constraints = this.registry.getAllConstraints();
     const errors: string[] = [];
-    
+
     // Build a minimal state for constraint checking
     const state: PraxisState & { context: TContext } = {
       context: this.context,
       facts: newFacts,
       meta: {},
     };
-    
+
     for (const constraint of constraints) {
       try {
         const result = constraint.impl(state);
         if (result === false) {
           errors.push(`Constraint "${constraint.id}" violated`);
-        } else if (typeof result === "string") {
+        } else if (typeof result === 'string') {
           errors.push(result);
         }
       } catch (error) {
@@ -333,7 +333,7 @@ export class PraxisDBStore<TContext = unknown> {
         );
       }
     }
-    
+
     return {
       valid: errors.length === 0,
       errors,
@@ -342,12 +342,12 @@ export class PraxisDBStore<TContext = unknown> {
 
   /**
    * Trigger rules when new facts are added
-   * 
+   *
    * This method is called after facts are stored. It can be extended
    * for derived fact computation where rules generate new facts based
    * on existing facts. Currently implemented as a hook point for future
    * enhancements.
-   * 
+   *
    * @param _newFacts The newly stored facts (unused in current implementation)
    */
   private async triggerRules(_newFacts: PraxisFact[]): Promise<void> {
@@ -361,14 +361,14 @@ export class PraxisDBStore<TContext = unknown> {
    */
   private async triggerRulesForEvents(events: PraxisEvent[]): Promise<void> {
     const rules = this.registry.getAllRules();
-    
+
     // Build state for rule evaluation
     const state: PraxisState & { context: TContext } = {
       context: this.context,
       facts: [],
       meta: {},
     };
-    
+
     // Execute each rule
     const derivedFacts: PraxisFact[] = [];
     for (const rule of rules) {
@@ -379,7 +379,7 @@ export class PraxisDBStore<TContext = unknown> {
         this.onRuleError(rule.id, error);
       }
     }
-    
+
     // Store derived facts (without re-triggering rules to avoid infinite loops)
     if (derivedFacts.length > 0) {
       const constraintResult = await this.checkConstraints(derivedFacts);
@@ -419,19 +419,19 @@ export class PraxisDBStore<TContext = unknown> {
 
 /**
  * Create a new PraxisDBStore
- * 
+ *
  * @param db The PraxisDB instance to use
  * @param registry The PraxisRegistry for rules and constraints
  * @param initialContext Optional initial context
  * @param onRuleError Optional error handler for rule execution errors
  * @returns PraxisDBStore instance
- * 
+ *
  * @example
  * ```typescript
  * const db = createInMemoryDB();
  * const registry = new PraxisRegistry();
  * const store = createPraxisDBStore(db, registry);
- * 
+ *
  * await store.storeFact({ tag: "UserLoggedIn", payload: { userId: "alice" } });
  * await store.appendEvent({ tag: "LOGIN", payload: { username: "alice" } });
  * ```

package/src/core/protocol.ts

@@ -1,39 +1,39 @@
 /**
  * Core Praxis Protocol
- * 
+ *
  * Language-neutral, JSON-friendly protocol that forms the foundation of Praxis.
  * This protocol is designed to be stable and portable across languages (TypeScript, C#, PowerShell, etc.)
- * 
+ *
  * The protocol defines the conceptual core of the engine:
  * - Pure, deterministic, data in → data out
  * - No side effects, no global state
  * - All higher-level TypeScript APIs are built on top of this protocol
- * 
+ *
  * ## Protocol Versioning
- * 
+ *
  * The Praxis protocol follows semantic versioning (MAJOR.MINOR.PATCH):
  * - MAJOR: Breaking changes to core protocol types or semantics
  * - MINOR: Backward-compatible additions to protocol (new optional fields)
  * - PATCH: Clarifications, documentation updates, no functional changes
- * 
+ *
  * Current version: 1.0.0
- * 
+ *
  * ### Stability Guarantees
- * 
+ *
  * 1. **Core Types Stability**: The following types are considered stable and will not
  *    change in backward-incompatible ways within the same major version:
  *    - PraxisFact (tag, payload structure)
  *    - PraxisEvent (tag, payload structure)
  *    - PraxisState (context, facts, meta structure)
  *    - PraxisStepFn signature
- * 
+ *
  * 2. **JSON Compatibility**: All protocol types will remain JSON-serializable.
  *    No non-JSON-safe types (functions, symbols, etc.) will be added to the protocol.
- * 
+ *
  * 3. **Cross-Language Compatibility**: Protocol changes will be coordinated across
  *    all official language implementations (TypeScript, C#, PowerShell) to ensure
  *    interoperability.
- * 
+ *
  * 4. **Migration Path**: Major version changes will be accompanied by:
  *    - Migration guide
  *    - Deprecation warnings in previous version
@@ -43,7 +43,7 @@
 /**
  * Protocol version following semantic versioning
  */
-export const PRAXIS_PROTOCOL_VERSION = "1.0.0" as const;
+export const PRAXIS_PROTOCOL_VERSION = '1.0.0' as const;
 
 /**
  * A fact is a typed proposition about the domain.
@@ -86,7 +86,7 @@ export interface PraxisState {
  */
 export interface PraxisDiagnostics {
   /** Kind of diagnostic */
-  kind: "constraint-violation" | "rule-error";
+  kind: 'constraint-violation' | 'rule-error';
   /** Human-readable message */
   message: string;
   /** Additional diagnostic data */
@@ -116,12 +116,12 @@ export interface PraxisStepResult {
 
 /**
  * The core step function of the Praxis engine.
- * 
+ *
  * This is the conceptual heart of the engine:
  * - Takes current state, events, and configuration
  * - Applies rules and checks constraints
  * - Returns new state and diagnostics
- * 
+ *
  * Pure, deterministic, data in → data out.
  * No side effects, no global state.
  */

package/src/core/reactive-engine.svelte.ts

@@ -0,0 +1,65 @@
+/**
+ * Praxis Reactive Logic Engine
+ * 
+ * A Svelte 5 native implementation of the Praxis Logic Engine.
+ * Uses Runes ($state, $derived, $effect) for fine-grained reactivity.
+ */
+
+export interface ReactiveEngineOptions<TContext> {
+    initialContext: TContext;
+    initialFacts?: any[];
+    initialMeta?: Record<string, unknown>;
+}
+
+export class ReactiveLogicEngine<TContext extends object> {
+    // The single source of truth, reactive by default
+    // We use $state.raw for things that shouldn't be deeply reactive if needed,
+    // but for context we usually want deep reactivity.
+    state = $state<{
+        context: TContext;
+        facts: any[];
+        meta: Record<string, unknown>;
+    }>({
+        context: {} as TContext,
+        facts: [],
+        meta: {}
+    });
+
+    constructor(options: ReactiveEngineOptions<TContext>) {
+        this.state.context = options.initialContext;
+        this.state.facts = options.initialFacts ?? [];
+        this.state.meta = options.initialMeta ?? {};
+    }
+
+    /**
+     * Access the reactive context directly.
+     * Consumers can use this in $derived() or $effect().
+     */
+    get context() {
+        return this.state.context;
+    }
+
+    /**
+     * Access the reactive facts list.
+     */
+    get facts() {
+        return this.state.facts;
+    }
+
+    /**
+     * Apply a mutation to the state.
+     * This is the "Action" or "Rule" equivalent.
+     * 
+     * @param mutator A function that receives the state and modifies it.
+     */
+    apply(mutator: (state: { context: TContext; facts: any[]; meta: Record<string, unknown> }) => void) {
+        mutator(this.state);
+    }
+
+    /**
+     * Access the reactive meta.
+     */
+    get meta() {
+        return this.state.meta;
+    }
+}