@plures/praxis 0.2.0 → 1.0.0

package/core/logic-engine/psf-adapter.ts

@@ -0,0 +1,269 @@
+/**
+ * PSF-Aware Logic Engine Adapter
+ * 
+ * This module connects the logic engine to the Praxis Schema Format (PSF).
+ * It enables schema-driven rule evaluation and constraint checking.
+ */
+
+import type { PSFSchema, PSFRule, PSFConstraint, PSFExpression } from '../schema-engine/psf.js';
+import type { PraxisFact, PraxisEvent, PraxisState } from '../../src/core/protocol.js';
+import type { RuleDescriptor, ConstraintDescriptor } from '../../src/core/rules.js';
+
+/**
+ * PSF Adapter options
+ */
+export interface PSFAdapterOptions {
+  /** Enable expression caching */
+  cacheExpressions?: boolean;
+  /** Sandbox for expression evaluation */
+  sandbox?: Record<string, unknown>;
+}
+
+/**
+ * Compiled expression
+ */
+interface CompiledExpression {
+  fn: Function;
+  source: string;
+}
+
+/**
+ * PSF Adapter for Logic Engine
+ * 
+ * Converts PSF rules and constraints to logic engine format.
+ */
+export class PSFLogicAdapter {
+  private options: Required<PSFAdapterOptions>;
+  private expressionCache: Map<string, CompiledExpression> = new Map();
+  private sandbox: Record<string, unknown>;
+
+  constructor(options: PSFAdapterOptions = {}) {
+    this.options = {
+      cacheExpressions: options.cacheExpressions ?? true,
+      sandbox: options.sandbox ?? {},
+    };
+    this.sandbox = { ...this.options.sandbox };
+  }
+
+  /**
+   * Convert PSF rules to logic engine rule descriptors
+   */
+  convertRules<TContext = unknown>(rules: PSFRule[]): RuleDescriptor<TContext>[] {
+    return rules.map((rule) => this.convertRule<TContext>(rule));
+  }
+
+  /**
+   * Convert a single PSF rule to rule descriptor
+   */
+  convertRule<TContext = unknown>(rule: PSFRule): RuleDescriptor<TContext> {
+    const whenFn = rule.when ? this.compileExpression(rule.when, ['state', 'events']) : null;
+    const thenFn = this.compileExpression(rule.then, ['state', 'events']);
+
+    return {
+      id: rule.id,
+      description: rule.description,
+      meta: {
+        triggers: rule.triggers,
+        priority: rule.priority,
+        ...rule.meta,
+      },
+      impl: (state: PraxisState & { context: TContext }, events: PraxisEvent[]): PraxisFact[] => {
+        // Filter events by triggers if specified
+        let filteredEvents = events;
+        if (rule.triggers && rule.triggers.length > 0) {
+          filteredEvents = events.filter((e) => rule.triggers!.includes(e.tag));
+          if (filteredEvents.length === 0) {
+            return [];
+          }
+        }
+
+        // Check condition
+        if (whenFn) {
+          try {
+            const conditionResult = whenFn.fn.call(this.sandbox, state, filteredEvents);
+            if (!conditionResult) {
+              return [];
+            }
+          } catch (error) {
+            console.error(`Error evaluating rule condition "${rule.id}":`, error);
+            return [];
+          }
+        }
+
+        // Execute action
+        try {
+          const result = thenFn.fn.call(this.sandbox, state, filteredEvents);
+          if (Array.isArray(result)) {
+            return result;
+          }
+          return [];
+        } catch (error) {
+          console.error(`Error executing rule action "${rule.id}":`, error);
+          return [];
+        }
+      },
+    };
+  }
+
+  /**
+   * Convert PSF constraints to logic engine constraint descriptors
+   */
+  convertConstraints<TContext = unknown>(constraints: PSFConstraint[]): ConstraintDescriptor<TContext>[] {
+    return constraints.map((constraint) => this.convertConstraint<TContext>(constraint));
+  }
+
+  /**
+   * Convert a single PSF constraint to constraint descriptor
+   */
+  convertConstraint<TContext = unknown>(constraint: PSFConstraint): ConstraintDescriptor<TContext> {
+    const checkFn = this.compileExpression(constraint.check, ['state']);
+
+    return {
+      id: constraint.id,
+      description: constraint.description,
+      meta: {
+        severity: constraint.severity,
+        ...constraint.meta,
+      },
+      impl: (state: PraxisState & { context: TContext }): boolean | string => {
+        try {
+          const result = checkFn.fn.call(this.sandbox, state);
+          if (result === true) {
+            return true;
+          }
+          return constraint.errorMessage;
+        } catch (error) {
+          return `Error checking constraint "${constraint.id}": ${error}`;
+        }
+      },
+    };
+  }
+
+  /**
+   * Load a complete PSF schema into the logic engine
+   */
+  loadSchema<TContext = unknown>(schema: PSFSchema): {
+    rules: RuleDescriptor<TContext>[];
+    constraints: ConstraintDescriptor<TContext>[];
+  } {
+    // Add schema facts and events to sandbox for expression evaluation
+    this.sandbox = {
+      ...this.options.sandbox,
+      Facts: this.createFactHelpers(schema),
+      Events: this.createEventHelpers(schema),
+    };
+
+    return {
+      rules: this.convertRules<TContext>(schema.rules),
+      constraints: this.convertConstraints<TContext>(schema.constraints),
+    };
+  }
+
+  /**
+   * Compile a PSF expression to a function
+   */
+  private compileExpression(expr: PSFExpression, args: string[]): CompiledExpression {
+    const source = 'inline' in expr ? expr.inline : `/* ref: ${expr.ref} */ null`;
+    const cacheKey = `${args.join(',')}:${source}`;
+
+    if (this.options.cacheExpressions && this.expressionCache.has(cacheKey)) {
+      return this.expressionCache.get(cacheKey)!;
+    }
+
+    try {
+      // Create function from expression
+      const fn = new Function(...args, `return (${source});`);
+      const compiled: CompiledExpression = { fn, source };
+
+      if (this.options.cacheExpressions) {
+        this.expressionCache.set(cacheKey, compiled);
+      }
+
+      return compiled;
+    } catch (error) {
+      // Return a safe no-op function on compilation error
+      console.error(`Error compiling expression: ${source}`, error);
+      return {
+        fn: () => null,
+        source,
+      };
+    }
+  }
+
+  /**
+   * Create fact helper functions for expression evaluation
+   */
+  private createFactHelpers(schema: PSFSchema): Record<string, unknown> {
+    const helpers: Record<string, unknown> = {};
+
+    for (const fact of schema.facts) {
+      helpers[fact.tag] = {
+        tag: fact.tag,
+        create: (payload: unknown) => ({ tag: fact.tag, payload }),
+        is: (f: PraxisFact) => f.tag === fact.tag,
+      };
+    }
+
+    return helpers;
+  }
+
+  /**
+   * Create event helper functions for expression evaluation
+   */
+  private createEventHelpers(schema: PSFSchema): Record<string, unknown> {
+    const helpers: Record<string, unknown> = {};
+
+    for (const event of schema.events) {
+      helpers[event.tag] = {
+        tag: event.tag,
+        create: (payload: unknown) => ({ tag: event.tag, payload }),
+        is: (e: PraxisEvent) => e.tag === event.tag,
+      };
+    }
+
+    return helpers;
+  }
+
+  /**
+   * Clear expression cache
+   */
+  clearCache(): void {
+    this.expressionCache.clear();
+  }
+}
+
+/**
+ * Create a PSF logic adapter
+ */
+export function createPSFLogicAdapter(options?: PSFAdapterOptions): PSFLogicAdapter {
+  return new PSFLogicAdapter(options);
+}
+
+/**
+ * Schema-aware engine factory
+ */
+export interface SchemaAwareEngineOptions<TContext = unknown> {
+  schema: PSFSchema;
+  initialContext: TContext;
+  sandbox?: Record<string, unknown>;
+}
+
+/**
+ * Create a schema-aware logic engine from PSF
+ */
+export async function createSchemaAwareEngine<TContext = unknown>(
+  options: SchemaAwareEngineOptions<TContext>
+): Promise<{
+  rules: RuleDescriptor<TContext>[];
+  constraints: ConstraintDescriptor<TContext>[];
+  adapter: PSFLogicAdapter;
+}> {
+  const adapter = new PSFLogicAdapter({ sandbox: options.sandbox });
+  const { rules, constraints } = adapter.loadSchema<TContext>(options.schema);
+
+  return {
+    rules,
+    constraints,
+    adapter,
+  };
+}

package/core/logic-engine/rules.ts

@@ -0,0 +1,16 @@
+/**
+ * Rules and Constraints
+ * 
+ * Re-exports rules and constraints from the main source.
+ */
+
+export {
+  PraxisRegistry,
+  type RuleId,
+  type ConstraintId,
+  type RuleFn,
+  type ConstraintFn,
+  type RuleDescriptor,
+  type ConstraintDescriptor,
+  type PraxisModule,
+} from '../../src/core/rules.js';

package/core/schema-engine/compiler.ts

@@ -0,0 +1,431 @@
+/**
+ * PSF Compiler
+ * 
+ * Compiles TypeScript DSL definitions to PSF format.
+ * This enables code → schema synchronization.
+ */
+
+import type {
+  PSFSchema,
+  PSFFact,
+  PSFEvent,
+  PSFRule,
+  PSFConstraint,
+  PSFModel,
+  PSFComponent,
+  PSFPayloadSchema,
+  PSFField,
+  PSFFieldType,
+  PSFExpression,
+} from './psf.js';
+import { PSF_VERSION, generatePSFId } from './psf.js';
+
+/**
+ * Reserved JavaScript keywords (O(1) lookup)
+ */
+const RESERVED_KEYWORDS = new Set([
+  'break', 'case', 'catch', 'class', 'const', 'continue', 'debugger',
+  'default', 'delete', 'do', 'else', 'export', 'extends', 'finally',
+  'for', 'function', 'if', 'import', 'in', 'instanceof', 'new',
+  'return', 'super', 'switch', 'this', 'throw', 'try', 'typeof',
+  'var', 'void', 'while', 'with', 'yield', 'let', 'static',
+  'enum', 'await', 'implements', 'interface', 'package', 'private',
+  'protected', 'public',
+]);
+
+/**
+ * Source location information for error reporting
+ */
+export interface SourceLocation {
+  file?: string;
+  line?: number;
+  column?: number;
+}
+
+/**
+ * Compilation error
+ */
+export interface CompilationError {
+  message: string;
+  code: string;
+  location?: SourceLocation;
+  severity: 'error' | 'warning';
+}
+
+/**
+ * Compilation result
+ */
+export interface CompilationResult {
+  success: boolean;
+  schema?: PSFSchema;
+  errors: CompilationError[];
+  warnings: CompilationError[];
+}
+
+/**
+ * DSL Fact definition input
+ */
+export interface DSLFact {
+  tag: string;
+  description?: string;
+  payload: Record<string, string>;
+}
+
+/**
+ * DSL Event definition input
+ */
+export interface DSLEvent {
+  tag: string;
+  description?: string;
+  payload: Record<string, string>;
+}
+
+/**
+ * DSL Rule definition input
+ */
+export interface DSLRule {
+  id: string;
+  description: string;
+  triggers?: string[];
+  when?: string;
+  then: string;
+  priority?: number;
+}
+
+/**
+ * DSL Constraint definition input
+ */
+export interface DSLConstraint {
+  id: string;
+  description: string;
+  check: string;
+  errorMessage: string;
+}
+
+/**
+ * DSL Model definition input
+ */
+export interface DSLModel {
+  name: string;
+  description?: string;
+  fields: DSLModelField[];
+}
+
+/**
+ * DSL Model Field input
+ */
+export interface DSLModelField {
+  name: string;
+  type: string;
+  optional?: boolean;
+  default?: unknown;
+  description?: string;
+}
+
+/**
+ * DSL Component definition input
+ */
+export interface DSLComponent {
+  name: string;
+  type: 'form' | 'display' | 'list' | 'navigation' | 'editor' | 'custom';
+  description?: string;
+  model?: string;
+  props?: Array<{
+    name: string;
+    type: string;
+    required?: boolean;
+    default?: unknown;
+    description?: string;
+  }>;
+  events?: Array<{
+    name: string;
+    payload?: string;
+    description?: string;
+  }>;
+}
+
+/**
+ * DSL Schema input
+ */
+export interface DSLSchema {
+  id?: string;
+  name: string;
+  description?: string;
+  facts?: DSLFact[];
+  events?: DSLEvent[];
+  rules?: DSLRule[];
+  constraints?: DSLConstraint[];
+  models?: DSLModel[];
+  components?: DSLComponent[];
+}
+
+/**
+ * PSF Compiler class
+ */
+export class PSFCompiler {
+  private errors: CompilationError[] = [];
+  private warnings: CompilationError[] = [];
+
+  /**
+   * Compile DSL schema to PSF format
+   */
+  compile(input: DSLSchema): CompilationResult {
+    this.errors = [];
+    this.warnings = [];
+
+    try {
+      const schema = this.compileToPSF(input);
+
+      return {
+        success: this.errors.length === 0,
+        schema: this.errors.length === 0 ? schema : undefined,
+        errors: this.errors,
+        warnings: this.warnings,
+      };
+    } catch (error) {
+      this.addError('compilation-failed', error instanceof Error ? error.message : 'Unknown compilation error');
+      return {
+        success: false,
+        errors: this.errors,
+        warnings: this.warnings,
+      };
+    }
+  }
+
+  /**
+   * Compile DSL to PSF schema
+   */
+  private compileToPSF(input: DSLSchema): PSFSchema {
+    const now = new Date().toISOString();
+
+    return {
+      $version: PSF_VERSION,
+      id: input.id || generatePSFId('schema'),
+      name: input.name,
+      description: input.description,
+      createdAt: now,
+      modifiedAt: now,
+      facts: this.compileFacts(input.facts || []),
+      events: this.compileEvents(input.events || []),
+      rules: this.compileRules(input.rules || []),
+      constraints: this.compileConstraints(input.constraints || []),
+      models: this.compileModels(input.models || []),
+      components: this.compileComponents(input.components || []),
+      flows: [],
+      docs: {},
+    };
+  }
+
+  /**
+   * Compile facts
+   */
+  private compileFacts(facts: DSLFact[]): PSFFact[] {
+    return facts.map((fact) => {
+      if (!this.isValidIdentifier(fact.tag)) {
+        this.addError('invalid-identifier', `Invalid fact tag: ${fact.tag}`);
+      }
+
+      return {
+        id: generatePSFId('fact'),
+        tag: fact.tag,
+        description: fact.description,
+        payload: this.compilePayload(fact.payload),
+      };
+    });
+  }
+
+  /**
+   * Compile events
+   */
+  private compileEvents(events: DSLEvent[]): PSFEvent[] {
+    return events.map((event) => {
+      if (!this.isValidIdentifier(event.tag)) {
+        this.addError('invalid-identifier', `Invalid event tag: ${event.tag}`);
+      }
+
+      return {
+        id: generatePSFId('event'),
+        tag: event.tag,
+        description: event.description,
+        payload: this.compilePayload(event.payload),
+      };
+    });
+  }
+
+  /**
+   * Compile payload to PSF format
+   */
+  private compilePayload(payload: Record<string, string>): PSFPayloadSchema {
+    const properties: Record<string, { type: PSFFieldType; description?: string }> = {};
+
+    for (const [key, typeStr] of Object.entries(payload)) {
+      properties[key] = {
+        type: this.parseFieldType(typeStr),
+      };
+    }
+
+    return {
+      type: 'object',
+      properties,
+      required: Object.keys(payload),
+    };
+  }
+
+  /**
+   * Compile rules
+   */
+  private compileRules(rules: DSLRule[]): PSFRule[] {
+    return rules.map((rule) => ({
+      id: rule.id,
+      description: rule.description,
+      triggers: rule.triggers,
+      when: rule.when ? this.parseExpression(rule.when) : undefined,
+      then: this.parseExpression(rule.then),
+      priority: rule.priority,
+    }));
+  }
+
+  /**
+   * Compile constraints
+   */
+  private compileConstraints(constraints: DSLConstraint[]): PSFConstraint[] {
+    return constraints.map((constraint) => ({
+      id: constraint.id,
+      description: constraint.description,
+      check: this.parseExpression(constraint.check),
+      errorMessage: constraint.errorMessage,
+    }));
+  }
+
+  /**
+   * Compile models
+   */
+  private compileModels(models: DSLModel[]): PSFModel[] {
+    return models.map((model) => ({
+      id: generatePSFId('model'),
+      name: model.name,
+      description: model.description,
+      fields: this.compileFields(model.fields),
+    }));
+  }
+
+  /**
+   * Compile model fields
+   */
+  private compileFields(fields: DSLModelField[]): PSFField[] {
+    return fields.map((field) => ({
+      name: field.name,
+      type: this.parseFieldType(field.type),
+      optional: field.optional,
+      default: field.default,
+      description: field.description,
+    }));
+  }
+
+  /**
+   * Compile components
+   */
+  private compileComponents(components: DSLComponent[]): PSFComponent[] {
+    return components.map((component) => ({
+      id: generatePSFId('component'),
+      name: component.name,
+      type: component.type,
+      description: component.description,
+      model: component.model,
+      props: (component.props || []).map((prop) => ({
+        name: prop.name,
+        type: prop.type,
+        required: prop.required,
+        default: prop.default,
+        description: prop.description,
+      })),
+      events: (component.events || []).map((event) => ({
+        name: event.name,
+        payload: event.payload,
+        description: event.description,
+      })),
+    }));
+  }
+
+  /**
+   * Parse field type string to PSF field type
+   */
+  private parseFieldType(typeStr: string): PSFFieldType {
+    // Handle array types
+    if (typeStr.endsWith('[]')) {
+      const innerType = typeStr.slice(0, -2);
+      return { array: this.parseFieldType(innerType) };
+    }
+
+    // Handle reference types
+    if (typeStr.startsWith('ref:')) {
+      return { reference: typeStr.slice(4) };
+    }
+
+    // Handle enum types
+    if (typeStr.startsWith('enum:')) {
+      const values = typeStr.slice(5).split('|').map((v) => v.trim());
+      return { enum: values };
+    }
+
+    // Handle basic types
+    const basicTypes = ['string', 'number', 'boolean', 'date', 'datetime', 'uuid'] as const;
+    if (basicTypes.includes(typeStr as typeof basicTypes[number])) {
+      return typeStr as PSFFieldType;
+    }
+
+    // Default to string if unknown
+    this.addWarning('unknown-type', `Unknown type "${typeStr}", defaulting to string`);
+    return 'string';
+  }
+
+  /**
+   * Parse expression string to PSF expression
+   */
+  private parseExpression(expr: string): PSFExpression {
+    // Check if it's a reference
+    if (expr.startsWith('$ref:')) {
+      return { ref: expr.slice(5) };
+    }
+
+    // Otherwise treat as inline TypeScript
+    return { inline: expr, language: 'typescript' };
+  }
+
+  /**
+   * Check if string is valid JavaScript identifier
+   */
+  private isValidIdentifier(str: string): boolean {
+    const identifierRegex = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/;
+    return identifierRegex.test(str) && !RESERVED_KEYWORDS.has(str);
+  }
+
+  /**
+   * Add error
+   */
+  private addError(code: string, message: string, location?: SourceLocation): void {
+    this.errors.push({ code, message, location, severity: 'error' });
+  }
+
+  /**
+   * Add warning
+   */
+  private addWarning(code: string, message: string, location?: SourceLocation): void {
+    this.warnings.push({ code, message, location, severity: 'warning' });
+  }
+}
+
+/**
+ * Create a PSF compiler
+ */
+export function createPSFCompiler(): PSFCompiler {
+  return new PSFCompiler();
+}
+
+/**
+ * Compile DSL to PSF (convenience function)
+ */
+export function compileToPSF(input: DSLSchema): CompilationResult {
+  const compiler = new PSFCompiler();
+  return compiler.compile(input);
+}