@plures/praxis 1.0.2 → 1.1.0

package/src/components/index.ts

@@ -1,11 +1,11 @@
 /**
  * Praxis Svelte Components
- * 
+ *
  * Exports types and interfaces for Svelte components in Praxis/RuneBook applications.
- * 
+ *
  * Note: Svelte components (.svelte files) must be imported directly in Svelte applications.
  * This module provides TypeScript types for component props.
- * 
+ *
  * @example
  * ```svelte
  * <script>
@@ -43,4 +43,3 @@ export interface TerminalNodeProps {
  */
 export type { TerminalAdapter } from '../runtime/terminal-adapter.js';
 export { createTerminalAdapter } from '../runtime/terminal-adapter.js';
-

package/src/core/actors.ts

@@ -1,20 +1,20 @@
 /**
  * Actors System
- * 
+ *
  * Actors are effectful units that:
  * - Observe Praxis logic state
  * - Perform side effects (network I/O, database operations, timers, etc.)
  * - Feed new events/facts back into the engine
- * 
+ *
  * Actors provide the bridge between pure logic and the effectful world.
  */
 
-import type { LogicEngine } from "./engine.js";
-import type { PraxisEvent, PraxisState } from "./protocol.js";
+import type { LogicEngine } from './engine.js';
+import type { PraxisEvent, PraxisState } from './protocol.js';
 
 /**
  * Actor interface
- * 
+ *
  * An actor observes state changes and can:
  * - React to state changes (onStateChange)
  * - Perform initialization (onStart)
@@ -38,7 +38,7 @@ export interface Actor<TContext = unknown> {
 
 /**
  * Actor manager
- * 
+ *
  * Manages the lifecycle of actors and coordinates their interaction with the engine.
  */
 export class ActorManager<TContext = unknown> {
@@ -85,7 +85,7 @@ export class ActorManager<TContext = unknown> {
       throw new Error(`Actor "${actorId}" is already started`);
     }
     if (!this.engine) {
-      throw new Error("Actor manager not attached to an engine");
+      throw new Error('Actor manager not attached to an engine');
     }
 
     this.activeActors.add(actorId);

package/src/core/component/generator.ts

@@ -1,6 +1,6 @@
 /**
  * Praxis Component Generator
- * 
+ *
  * Generates Svelte components from schema definitions.
  */
 
@@ -71,10 +71,7 @@ export class ComponentGenerator {
   /**
    * Generate component from definition
    */
-  generateComponent(
-    component: ComponentDefinition,
-    model?: ModelDefinition
-  ): GenerationResult {
+  generateComponent(component: ComponentDefinition, model?: ModelDefinition): GenerationResult {
     const files: GeneratedFile[] = [];
     const errors: GenerationError[] = [];
 
@@ -135,10 +132,7 @@ export class ComponentGenerator {
   /**
    * Generate Svelte component code
    */
-  private generateSvelteComponent(
-    component: ComponentDefinition,
-    model?: ModelDefinition
-  ): string {
+  private generateSvelteComponent(component: ComponentDefinition, model?: ModelDefinition): string {
     const script = this.generateScript(component, model);
     const template = this.generateTemplate(component, model);
     const styles = this.generateStyles(component);
@@ -157,7 +151,7 @@ ${styles ? `<style>\n${styles}\n</style>` : ''}`;
    */
   private generateScript(
     component: ComponentDefinition,
-    _model?: ModelDefinition  // Prefix with _ to indicate intentionally unused
+    _model?: ModelDefinition // Prefix with _ to indicate intentionally unused
   ): string {
     const lines: string[] = [];
 
@@ -169,11 +163,8 @@ ${styles ? `<style>\n${styles}\n</style>` : ''}`;
     if (component.props && component.props.length > 0) {
       component.props.forEach((prop) => {
         const typeAnnotation = this.config.typescript ? `: ${prop.type}` : '';
-        const defaultValue =
-          prop.default !== undefined ? ` = ${JSON.stringify(prop.default)}` : '';
-        lines.push(
-          `  export let ${prop.name}${typeAnnotation}${defaultValue};`
-        );
+        const defaultValue = prop.default !== undefined ? ` = ${JSON.stringify(prop.default)}` : '';
+        lines.push(`  export let ${prop.name}${typeAnnotation}${defaultValue};`);
       });
       lines.push('');
     }
@@ -230,10 +221,7 @@ ${styles ? `<style>\n${styles}\n</style>` : ''}`;
   /**
    * Generate component template
    */
-  private generateTemplate(
-    component: ComponentDefinition,
-    model?: ModelDefinition
-  ): string {
+  private generateTemplate(component: ComponentDefinition, model?: ModelDefinition): string {
     switch (component.type) {
       case 'form':
         return this.generateFormTemplate(component, model);
@@ -251,10 +239,7 @@ ${styles ? `<style>\n${styles}\n</style>` : ''}`;
   /**
    * Generate form template
    */
-  private generateFormTemplate(
-    component: ComponentDefinition,
-    model?: ModelDefinition
-  ): string {
+  private generateFormTemplate(component: ComponentDefinition, model?: ModelDefinition): string {
     const fields = model?.fields || [];
     const formFields = fields
       .map((field) => {
@@ -268,10 +253,7 @@ ${styles ? `<style>\n${styles}\n</style>` : ''}`;
   /**
    * Generate display template
    */
-  private generateDisplayTemplate(
-    component: ComponentDefinition,
-    model?: ModelDefinition
-  ): string {
+  private generateDisplayTemplate(component: ComponentDefinition, model?: ModelDefinition): string {
     const fields = model?.fields || [];
     const displayFields = fields
       .map((field) => {
@@ -287,7 +269,7 @@ ${styles ? `<style>\n${styles}\n</style>` : ''}`;
    */
   private generateListTemplate(
     component: ComponentDefinition,
-    _model?: ModelDefinition  // Prefix with _ to indicate intentionally unused
+    _model?: ModelDefinition // Prefix with _ to indicate intentionally unused
   ): string {
     return `<div class="${component.name.toLowerCase()}">\n  {#each items as item}\n    <div class="item">{item.name}</div>\n  {/each}\n</div>`;
   }

package/src/core/engine.ts

@@ -1,6 +1,6 @@
 /**
  * Praxis Logic Engine
- * 
+ *
  * The logic engine manages state, processes events through rules,
  * checks constraints, and provides a strongly-typed API for application logic.
  */
@@ -12,9 +12,9 @@ import type {
   PraxisStepConfig,
   PraxisStepResult,
   PraxisDiagnostics,
-} from "./protocol.js";
-import { PRAXIS_PROTOCOL_VERSION } from "./protocol.js";
-import { PraxisRegistry } from "./rules.js";
+} from './protocol.js';
+import { PRAXIS_PROTOCOL_VERSION } from './protocol.js';
+import { PraxisRegistry } from './rules.js';
 
 /**
  * Options for creating a Praxis engine
@@ -30,9 +30,39 @@ export interface PraxisEngineOptions<TContext = unknown> {
   initialMeta?: Record<string, unknown>;
 }
 
+/**
+ * Clone helper that avoids structuredClone failures on non-cloneable values
+ * (e.g., functions, timers). Falls back to a shallow copy when necessary.
+ */
+function safeClone<T>(value: T): T {
+  if (value === null || typeof value !== 'object') {
+    return value;
+  }
+
+  // Prefer structuredClone for deep, data-safe copies when available
+  // (handles Map, Set, Date, etc.). Guard for environments that lack it.
+  if (typeof globalThis.structuredClone === 'function') {
+    try {
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+      return globalThis.structuredClone(value);
+    } catch {
+      // fall through to safer copies
+    }
+  }
+
+  if (Array.isArray(value)) {
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+    return [...(value as unknown as unknown[])] as unknown as T;
+  }
+
+  // Shallow copy as a safe fallback for objects containing functions or
+  // other non-structured-clone-able members.
+  return { ...(value as Record<string, unknown>) } as unknown as T;
+}
+
 /**
  * The Praxis Logic Engine
- * 
+ *
  * Manages application logic through facts, events, rules, and constraints.
  * The engine is strongly typed and functional - all state updates are immutable.
  */
@@ -55,9 +85,9 @@ export class LogicEngine<TContext = unknown> {
    */
   getState(): Readonly<PraxisState & { context: TContext }> {
     return {
-      context: structuredClone(this.state.context),
+      context: safeClone(this.state.context),
       facts: [...this.state.facts],
-      meta: this.state.meta ? { ...this.state.meta } : undefined,
+      meta: this.state.meta ? safeClone(this.state.meta) : undefined,
       protocolVersion: this.state.protocolVersion,
     };
   }
@@ -66,7 +96,7 @@ export class LogicEngine<TContext = unknown> {
    * Get the current context
    */
   getContext(): TContext {
-    return structuredClone(this.state.context);
+    return safeClone(this.state.context);
   }
 
   /**
@@ -79,7 +109,7 @@ export class LogicEngine<TContext = unknown> {
   /**
    * Process events through the engine.
    * Applies all registered rules and checks all registered constraints.
-   * 
+   *
    * @param events Events to process
    * @returns Result with new state and diagnostics
    */
@@ -93,15 +123,12 @@ export class LogicEngine<TContext = unknown> {
 
   /**
    * Process events with specific rule and constraint configuration.
-   * 
+   *
    * @param events Events to process
    * @param config Step configuration
    * @returns Result with new state and diagnostics
    */
-  stepWithConfig(
-    events: PraxisEvent[],
-    config: PraxisStepConfig
-  ): PraxisStepResult {
+  stepWithConfig(events: PraxisEvent[], config: PraxisStepConfig): PraxisStepResult {
     const diagnostics: PraxisDiagnostics[] = [];
     let newState = { ...this.state };
 
@@ -111,7 +138,7 @@ export class LogicEngine<TContext = unknown> {
       const rule = this.registry.getRule(ruleId);
       if (!rule) {
         diagnostics.push({
-          kind: "rule-error",
+          kind: 'rule-error',
           message: `Rule "${ruleId}" not found in registry`,
           data: { ruleId },
         });
@@ -123,7 +150,7 @@ export class LogicEngine<TContext = unknown> {
         newFacts.push(...ruleFacts);
       } catch (error) {
         diagnostics.push({
-          kind: "rule-error",
+          kind: 'rule-error',
           message: `Error executing rule "${ruleId}": ${error instanceof Error ? error.message : String(error)}`,
           data: { ruleId, error },
         });
@@ -141,7 +168,7 @@ export class LogicEngine<TContext = unknown> {
       const constraint = this.registry.getConstraint(constraintId);
       if (!constraint) {
         diagnostics.push({
-          kind: "constraint-violation",
+          kind: 'constraint-violation',
           message: `Constraint "${constraintId}" not found in registry`,
           data: { constraintId },
         });
@@ -152,20 +179,20 @@ export class LogicEngine<TContext = unknown> {
         const result = constraint.impl(newState);
         if (result === false) {
           diagnostics.push({
-            kind: "constraint-violation",
+            kind: 'constraint-violation',
             message: `Constraint "${constraintId}" violated`,
             data: { constraintId, description: constraint.description },
           });
-        } else if (typeof result === "string") {
+        } else if (typeof result === 'string') {
           diagnostics.push({
-            kind: "constraint-violation",
+            kind: 'constraint-violation',
             message: result,
             data: { constraintId, description: constraint.description },
           });
         }
       } catch (error) {
         diagnostics.push({
-          kind: "constraint-violation",
+          kind: 'constraint-violation',
           message: `Error checking constraint "${constraintId}": ${error instanceof Error ? error.message : String(error)}`,
           data: { constraintId, error },
         });
@@ -184,7 +211,7 @@ export class LogicEngine<TContext = unknown> {
   /**
    * Update the context directly (for exceptional cases).
    * Generally, context should be updated through rules.
-   * 
+   *
    * @param updater Function that produces new context from old context
    */
   updateContext(updater: (context: TContext) => TContext): void {
@@ -197,7 +224,7 @@ export class LogicEngine<TContext = unknown> {
   /**
    * Add facts directly (for exceptional cases).
    * Generally, facts should be added through rules.
-   * 
+   *
    * @param facts Facts to add
    */
   addFacts(facts: PraxisFact[]): void {
@@ -232,7 +259,7 @@ export class LogicEngine<TContext = unknown> {
 
 /**
  * Create a new Praxis logic engine.
- * 
+ *
  * @param options Engine options
  * @returns New LogicEngine instance
  */

package/src/core/introspection.ts

@@ -1,18 +1,18 @@
 /**
  * Introspection and Visualization Utilities
- * 
+ *
  * Provides APIs to introspect the registry, generate schemas,
  * and export graph representations for external tools.
  */
 
-import type { PraxisRegistry, RuleDescriptor, ConstraintDescriptor } from "./rules.js";
+import type { PraxisRegistry, RuleDescriptor, ConstraintDescriptor } from './rules.js';
 
 /**
  * Graph node representing a rule in the system
  */
 export interface RuleNode {
   id: string;
-  type: "rule";
+  type: 'rule';
   description: string;
   meta?: Record<string, unknown>;
 }
@@ -22,7 +22,7 @@ export interface RuleNode {
  */
 export interface ConstraintNode {
   id: string;
-  type: "constraint";
+  type: 'constraint';
   description: string;
   meta?: Record<string, unknown>;
 }
@@ -33,7 +33,7 @@ export interface ConstraintNode {
 export interface GraphEdge {
   from: string;
   to: string;
-  type: "triggers" | "constrains" | "depends-on";
+  type: 'triggers' | 'constrains' | 'depends-on';
 }
 
 /**
@@ -55,7 +55,7 @@ export interface RegistryGraph {
 export interface RuleSchema {
   id: string;
   description: string;
-  type: "rule";
+  type: 'rule';
   meta?: Record<string, unknown>;
 }
 
@@ -65,7 +65,7 @@ export interface RuleSchema {
 export interface ConstraintSchema {
   id: string;
   description: string;
-  type: "constraint";
+  type: 'constraint';
   meta?: Record<string, unknown>;
 }
 
@@ -119,14 +119,14 @@ export class RegistryIntrospector<TContext = unknown> {
     const rules: RuleSchema[] = this.registry.getAllRules().map((rule) => ({
       id: rule.id,
       description: rule.description,
-      type: "rule" as const,
+      type: 'rule' as const,
       meta: rule.meta,
     }));
 
     const constraints: ConstraintSchema[] = this.registry.getAllConstraints().map((constraint) => ({
       id: constraint.id,
       description: constraint.description,
-      type: "constraint" as const,
+      type: 'constraint' as const,
       meta: constraint.meta,
     }));
 
@@ -143,7 +143,7 @@ export class RegistryIntrospector<TContext = unknown> {
 
   /**
    * Generate a graph representation of the registry
-   * 
+   *
    * This creates nodes for rules and constraints.
    * Edges can be inferred from metadata if rules/constraints
    * document their dependencies.
@@ -156,7 +156,7 @@ export class RegistryIntrospector<TContext = unknown> {
     for (const rule of this.registry.getAllRules()) {
       nodes.push({
         id: rule.id,
-        type: "rule",
+        type: 'rule',
         description: rule.description,
         meta: rule.meta,
       });
@@ -170,7 +170,7 @@ export class RegistryIntrospector<TContext = unknown> {
           edges.push({
             from: String(dep),
             to: rule.id,
-            type: "depends-on",
+            type: 'depends-on',
           });
         }
       }
@@ -180,7 +180,7 @@ export class RegistryIntrospector<TContext = unknown> {
     for (const constraint of this.registry.getAllConstraints()) {
       nodes.push({
         id: constraint.id,
-        type: "constraint",
+        type: 'constraint',
         description: constraint.description,
         meta: constraint.meta,
       });
@@ -194,7 +194,7 @@ export class RegistryIntrospector<TContext = unknown> {
           edges.push({
             from: constraint.id,
             to: String(target),
-            type: "constrains",
+            type: 'constrains',
           });
         }
       }
@@ -205,75 +205,77 @@ export class RegistryIntrospector<TContext = unknown> {
       edges,
       meta: {
         nodeCount: nodes.length,
-        ruleCount: nodes.filter((n) => n.type === "rule").length,
-        constraintCount: nodes.filter((n) => n.type === "constraint").length,
+        ruleCount: nodes.filter((n) => n.type === 'rule').length,
+        constraintCount: nodes.filter((n) => n.type === 'constraint').length,
       },
     };
   }
 
   /**
    * Export graph in DOT format (Graphviz)
-   * 
+   *
    * This can be rendered with Graphviz tools or online services.
    */
   exportDOT(): string {
     const graph = this.generateGraph();
     const lines: string[] = [];
 
-    lines.push("digraph PraxisRegistry {");
-    lines.push("  rankdir=TB;");
-    lines.push("  node [shape=box, style=rounded];");
-    lines.push("");
+    lines.push('digraph PraxisRegistry {');
+    lines.push('  rankdir=TB;');
+    lines.push('  node [shape=box, style=rounded];');
+    lines.push('');
 
     // Add nodes
     for (const node of graph.nodes) {
-      const shape = node.type === "rule" ? "box" : "diamond";
-      const color = node.type === "rule" ? "lightblue" : "lightcoral";
+      const shape = node.type === 'rule' ? 'box' : 'diamond';
+      const color = node.type === 'rule' ? 'lightblue' : 'lightcoral';
       const label = `${node.id}\\n${node.description}`;
-      lines.push(`  "${node.id}" [label="${label}", shape=${shape}, style=filled, fillcolor=${color}];`);
+      lines.push(
+        `  "${node.id}" [label="${label}", shape=${shape}, style=filled, fillcolor=${color}];`
+      );
     }
 
-    lines.push("");
+    lines.push('');
 
     // Add edges
     for (const edge of graph.edges) {
-      const style = edge.type === "constrains" ? "dashed" : "solid";
+      const style = edge.type === 'constrains' ? 'dashed' : 'solid';
       lines.push(`  "${edge.from}" -> "${edge.to}" [label="${edge.type}", style=${style}];`);
     }
 
-    lines.push("}");
+    lines.push('}');
 
-    return lines.join("\n");
+    return lines.join('\n');
   }
 
   /**
    * Export graph in Mermaid format
-   * 
+   *
    * Mermaid is a markdown-friendly diagramming language.
    */
   exportMermaid(): string {
     const graph = this.generateGraph();
     const lines: string[] = [];
 
-    lines.push("graph TB");
+    lines.push('graph TB');
 
     // Add nodes
     for (const node of graph.nodes) {
-      const shape = node.type === "rule" ? "[" : "{" ;
-      const endShape = node.type === "rule" ? "]" : "}";
+      const shape = node.type === 'rule' ? '[' : '{';
+      const endShape = node.type === 'rule' ? ']' : '}';
       const label = `${node.id}<br/>${node.description}`;
       lines.push(`  ${node.id}${shape}"${label}"${endShape}`);
     }
 
-    lines.push("");
+    lines.push('');
 
     // Add edges
     for (const edge of graph.edges) {
-      const arrow = edge.type === "constrains" ? "-.->|constrains|" : "-->|" + edge.type + "|";
+      const arrow = edge.type === 'constrains' ? '-.->|constrains|' : '-->|' + edge.type + '|';
       lines.push(`  ${edge.from} ${arrow} ${edge.to}`);
     }
 
-    return lines.join("\n");
+    return lines.join('\n');
   }
 
   /**