@plures/praxis 0.2.0

package/src/examples/svelte-counter/index.ts

@@ -0,0 +1,168 @@
+/**
+ * Svelte Counter Example
+ * 
+ * Demonstrates Svelte v5 integration with a simple counter.
+ * Shows how to connect Praxis logic to reactive Svelte stores.
+ */
+
+import {
+  createPraxisEngine,
+  PraxisRegistry,
+  defineFact,
+  defineEvent,
+  defineRule,
+  findEvent,
+} from "../../index.js";
+import { createPraxisStore, createDerivedStore } from "../../integrations/svelte.js";
+
+// Define the context type
+interface CounterContext {
+  count: number;
+  history: number[];
+}
+
+// Define facts
+const CountIncremented = defineFact<"CountIncremented", { amount: number }>(
+  "CountIncremented"
+);
+const CountDecremented = defineFact<"CountDecremented", { amount: number }>(
+  "CountDecremented"
+);
+const CountReset = defineFact<"CountReset", {}>("CountReset");
+
+// Define events
+const Increment = defineEvent<"INCREMENT", { amount?: number }>("INCREMENT");
+const Decrement = defineEvent<"DECREMENT", { amount?: number }>("DECREMENT");
+const Reset = defineEvent<"RESET", {}>("RESET");
+
+// Define rules
+const incrementRule = defineRule<CounterContext>({
+  id: "counter.increment",
+  description: "Increment the counter",
+  impl: (state, events) => {
+    const incrementEvent = findEvent(events, Increment);
+    if (!incrementEvent) {
+      return [];
+    }
+
+    const amount = incrementEvent.payload.amount ?? 1;
+    state.context.count += amount;
+    state.context.history.push(state.context.count);
+
+    return [CountIncremented.create({ amount })];
+  },
+});
+
+const decrementRule = defineRule<CounterContext>({
+  id: "counter.decrement",
+  description: "Decrement the counter",
+  impl: (state, events) => {
+    const decrementEvent = findEvent(events, Decrement);
+    if (!decrementEvent) {
+      return [];
+    }
+
+    const amount = decrementEvent.payload.amount ?? 1;
+    state.context.count -= amount;
+    state.context.history.push(state.context.count);
+
+    return [CountDecremented.create({ amount })];
+  },
+});
+
+const resetRule = defineRule<CounterContext>({
+  id: "counter.reset",
+  description: "Reset the counter",
+  impl: (state, events) => {
+    const resetEvent = findEvent(events, Reset);
+    if (!resetEvent) {
+      return [];
+    }
+
+    state.context.count = 0;
+    state.context.history = [0];
+
+    return [CountReset.create({})];
+  },
+});
+
+// Create and configure the engine
+function createCounterEngine() {
+  const registry = new PraxisRegistry<CounterContext>();
+  registry.registerRule(incrementRule);
+  registry.registerRule(decrementRule);
+  registry.registerRule(resetRule);
+
+  const engine = createPraxisEngine<CounterContext>({
+    initialContext: {
+      count: 0,
+      history: [0],
+    },
+    registry,
+  });
+
+  return engine;
+}
+
+// Create Svelte stores
+function createCounterStores() {
+  const engine = createCounterEngine();
+
+  const stateStore = createPraxisStore(engine);
+  const countStore = createDerivedStore(engine, (ctx: CounterContext) => ctx.count);
+  const historyStore = createDerivedStore(engine, (ctx: CounterContext) => ctx.history);
+
+  return {
+    engine,
+    stateStore,
+    countStore,
+    historyStore,
+    // Helper methods
+    increment: (amount?: number) => {
+      engine.step([Increment.create({ amount })]);
+    },
+    decrement: (amount?: number) => {
+      engine.step([Decrement.create({ amount })]);
+    },
+    reset: () => {
+      engine.step([Reset.create({})]);
+    },
+  };
+}
+
+// Example usage (non-Svelte demonstration)
+function runExample() {
+  console.log("=== Svelte Counter Example ===\n");
+
+  const { engine, countStore } = createCounterStores();
+
+  // Subscribe to count changes
+  console.log("Subscribing to count changes...\n");
+  const unsubscribe = countStore.subscribe((count) => {
+    console.log(`Count changed: ${count}`);
+  });
+
+  // Dispatch some events
+  console.log("\nIncrementing by 1:");
+  engine.step([Increment.create({})]);
+
+  console.log("\nIncrementing by 5:");
+  engine.step([Increment.create({ amount: 5 })]);
+
+  console.log("\nDecrementing by 2:");
+  engine.step([Decrement.create({ amount: 2 })]);
+
+  console.log("\nResetting:");
+  engine.step([Reset.create({})]);
+
+  console.log("\nContext:", engine.getContext());
+
+  unsubscribe();
+}
+
+// Run example if executed directly
+if (import.meta.url === `file://${process.argv[1]}`) {
+  runExample();
+}
+
+export { createCounterEngine, createCounterStores, runExample };

package/src/flows.ts

@@ -0,0 +1,268 @@
+/**
+ * Flows and actors for orchestrating state transitions in Praxis.
+ * Flows represent sequences of state transitions.
+ * Actors are entities that maintain their own state and respond to events.
+ */
+
+import type { PraxisState, PraxisEvent, StepResult, StepFunction } from './types.js';
+
+/**
+ * A flow represents a sequence of events that need to occur.
+ */
+export interface Flow<E extends PraxisEvent = PraxisEvent> {
+  /** Unique identifier for the flow */
+  id: string;
+  /** Description of what the flow accomplishes */
+  description?: string;
+  /** Steps in the flow */
+  steps: FlowStep<E>[];
+  /** Current step index */
+  currentStep: number;
+  /** Whether the flow is complete */
+  complete: boolean;
+  /** Optional metadata */
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * A step in a flow.
+ */
+export interface FlowStep<E extends PraxisEvent = PraxisEvent> {
+  /** Step identifier */
+  id: string;
+  /** Expected event type for this step */
+  expectedEventType: string;
+  /** Optional validation function */
+  validate?: (event: E) => boolean;
+  /** Optional timeout in milliseconds */
+  timeout?: number;
+}
+
+/**
+ * An actor maintains its own state and responds to events.
+ */
+export interface Actor<
+  S extends PraxisState = PraxisState,
+  E extends PraxisEvent = PraxisEvent
+> {
+  /** Unique identifier for the actor */
+  id: string;
+  /** Current state of the actor */
+  state: S;
+  /** Step function for processing events */
+  step: StepFunction<S, E>;
+  /** Optional metadata */
+  metadata?: {
+    type?: string;
+    created?: number;
+    [key: string]: unknown;
+  };
+}
+
+/**
+ * Create a new flow.
+ */
+export function createFlow<E extends PraxisEvent = PraxisEvent>(
+  id: string,
+  steps: FlowStep<E>[],
+  description?: string
+): Flow<E> {
+  return {
+    id,
+    description,
+    steps,
+    currentStep: 0,
+    complete: false,
+  };
+}
+
+/**
+ * Advance a flow with an event.
+ * Returns an updated flow and whether the flow accepted the event.
+ */
+export function advanceFlow<E extends PraxisEvent = PraxisEvent>(
+  flow: Flow<E>,
+  event: E
+): { flow: Flow<E>; accepted: boolean } {
+  if (flow.complete) {
+    return { flow, accepted: false };
+  }
+
+  const currentStep = flow.steps[flow.currentStep];
+  if (!currentStep) {
+    return { flow, accepted: false };
+  }
+
+  // Check if event matches expected type
+  if (currentStep.expectedEventType !== event.type) {
+    return { flow, accepted: false };
+  }
+
+  // Validate event if validator is provided
+  if (currentStep.validate && !currentStep.validate(event)) {
+    return { flow, accepted: false };
+  }
+
+  // Advance to next step
+  const nextStep = flow.currentStep + 1;
+  const complete = nextStep >= flow.steps.length;
+
+  const updatedFlow: Flow<E> = {
+    ...flow,
+    currentStep: nextStep,
+    complete,
+  };
+
+  return { flow: updatedFlow, accepted: true };
+}
+
+/**
+ * Check if a flow is waiting for a specific event type.
+ */
+export function isFlowWaitingFor<E extends PraxisEvent = PraxisEvent>(
+  flow: Flow<E>,
+  eventType: string
+): boolean {
+  if (flow.complete) {
+    return false;
+  }
+  const currentStep = flow.steps[flow.currentStep];
+  return currentStep?.expectedEventType === eventType;
+}
+
+/**
+ * Create a new actor.
+ */
+export function createActor<
+  S extends PraxisState = PraxisState,
+  E extends PraxisEvent = PraxisEvent
+>(
+  id: string,
+  initialState: S,
+  stepFunction: StepFunction<S, E>,
+  type?: string
+): Actor<S, E> {
+  return {
+    id,
+    state: initialState,
+    step: stepFunction,
+    metadata: {
+      type,
+      created: Date.now(),
+    },
+  };
+}
+
+/**
+ * Process an event through an actor.
+ * Returns the updated actor and any effects.
+ */
+export function processActorEvent<
+  S extends PraxisState = PraxisState,
+  E extends PraxisEvent = PraxisEvent
+>(actor: Actor<S, E>, event: E): { actor: Actor<S, E>; result: StepResult<S> } {
+  const result = actor.step(actor.state, event);
+
+  const updatedActor: Actor<S, E> = {
+    ...actor,
+    state: result.state,
+  };
+
+  return { actor: updatedActor, result };
+}
+
+/**
+ * Actor system for managing multiple actors.
+ */
+export class ActorSystem<
+  S extends PraxisState = PraxisState,
+  E extends PraxisEvent = PraxisEvent
+> {
+  private actors: Map<string, Actor<S, E>> = new Map();
+
+  /**
+   * Register an actor in the system.
+   */
+  register(actor: Actor<S, E>): void {
+    if (this.actors.has(actor.id)) {
+      throw new Error(`Actor with id '${actor.id}' already exists`);
+    }
+    this.actors.set(actor.id, actor);
+  }
+
+  /**
+   * Unregister an actor from the system.
+   */
+  unregister(id: string): boolean {
+    return this.actors.delete(id);
+  }
+
+  /**
+   * Get an actor by ID.
+   */
+  get(id: string): Actor<S, E> | undefined {
+    return this.actors.get(id);
+  }
+
+  /**
+   * Get all actors.
+   */
+  getAll(): Actor<S, E>[] {
+    return Array.from(this.actors.values());
+  }
+
+  /**
+   * Send an event to a specific actor.
+   */
+  send(actorId: string, event: E): StepResult<S> | undefined {
+    const actor = this.actors.get(actorId);
+    if (!actor) {
+      return undefined;
+    }
+
+    const { actor: updatedActor, result } = processActorEvent(actor, event);
+    this.actors.set(actorId, updatedActor);
+
+    return result;
+  }
+
+  /**
+   * Broadcast an event to all actors.
+   * Returns a map of actor IDs to their results.
+   */
+  broadcast(event: E): Map<string, StepResult<S>> {
+    const results = new Map<string, StepResult<S>>();
+
+    for (const [id, actor] of this.actors) {
+      const { actor: updatedActor, result } = processActorEvent(actor, event);
+      this.actors.set(id, updatedActor);
+      results.set(id, result);
+    }
+
+    return results;
+  }
+
+  /**
+   * Clear all actors from the system.
+   */
+  clear(): void {
+    this.actors.clear();
+  }
+
+  /**
+   * Get the number of actors in the system.
+   */
+  size(): number {
+    return this.actors.size;
+  }
+}
+
+/**
+ * Create a new actor system.
+ */
+export function createActorSystem<
+  S extends PraxisState = PraxisState,
+  E extends PraxisEvent = PraxisEvent
+>(): ActorSystem<S, E> {
+  return new ActorSystem<S, E>();
+}

package/src/index.ts

@@ -0,0 +1,154 @@
+/**
+ * Praxis - Practical, Provable Application Logic
+ * 
+ * A typed, functional application logic engine built on strong types.
+ * 
+ * Core concepts:
+ * - Facts: typed propositions about the domain
+ * - Events: temporally ordered facts meant to drive change
+ * - Rules: pure functions that derive new facts from context + events
+ * - Constraints: invariants that must always hold
+ * - Flows: orchestrated behaviors
+ * - Actors: effectful units that perform side effects
+ * 
+ * @example
+ * ```typescript
+ * import { createPraxisEngine, PraxisRegistry, defineFact, defineEvent, defineRule } from "@plures/praxis";
+ * 
+ * // Define facts and events
+ * const UserLoggedIn = defineFact<"UserLoggedIn", { userId: string }>("UserLoggedIn");
+ * const Login = defineEvent<"LOGIN", { username: string }>("LOGIN");
+ * 
+ * // Define rules
+ * const loginRule = defineRule({
+ *   id: "auth.login",
+ *   description: "Process login event",
+ *   impl: (state, events) => {
+ *     const loginEvent = events.find(Login.is);
+ *     if (loginEvent) {
+ *       return [UserLoggedIn.create({ userId: loginEvent.payload.username })];
+ *     }
+ *     return [];
+ *   }
+ * });
+ * 
+ * // Create engine
+ * const registry = new PraxisRegistry();
+ * registry.registerRule(loginRule);
+ * 
+ * const engine = createPraxisEngine({
+ *   initialContext: {},
+ *   registry
+ * });
+ * 
+ * // Dispatch events
+ * const result = engine.step([Login.create({ username: "alice" })]);
+ * console.log(result.state.facts); // [{ tag: "UserLoggedIn", payload: { userId: "alice" } }]
+ * ```
+ */
+
+// Core protocol (language-neutral types)
+export type {
+  PraxisFact,
+  PraxisEvent,
+  PraxisState,
+  PraxisDiagnostics,
+  PraxisStepConfig,
+  PraxisStepResult,
+  PraxisStepFn,
+} from "./core/protocol.js";
+export { PRAXIS_PROTOCOL_VERSION } from "./core/protocol.js";
+
+// Rules and constraints
+export type {
+  RuleId,
+  ConstraintId,
+  RuleFn,
+  ConstraintFn,
+  RuleDescriptor,
+  ConstraintDescriptor,
+  PraxisModule,
+} from "./core/rules.js";
+export { PraxisRegistry } from "./core/rules.js";
+
+// Engine
+export type { PraxisEngineOptions } from "./core/engine.js";
+export { LogicEngine, createPraxisEngine } from "./core/engine.js";
+
+// Actors
+export type { Actor } from "./core/actors.js";
+export { ActorManager, createTimerActor } from "./core/actors.js";
+
+// Introspection
+export type {
+  RuleNode,
+  ConstraintNode,
+  GraphEdge,
+  RegistryGraph,
+  RuleSchema,
+  ConstraintSchema,
+  RegistrySchema,
+  RegistryStats,
+} from "./core/introspection.js";
+export { RegistryIntrospector, createIntrospector } from "./core/introspection.js";
+
+// DSL helpers
+export {
+  defineFact,
+  defineEvent,
+  defineRule,
+  defineConstraint,
+  defineModule,
+  filterEvents,
+  filterFacts,
+  findEvent,
+  findFact,
+} from "./dsl/index.js";
+export type {
+  FactDefinition,
+  EventDefinition,
+  DefineRuleOptions,
+  DefineConstraintOptions,
+  DefineModuleOptions,
+} from "./dsl/index.js";
+
+// Terminal Node Runtime
+export type {
+  TerminalExecutionResult,
+  TerminalNodeState,
+  TerminalAdapterOptions,
+} from "./runtime/terminal-adapter.js";
+export {
+  TerminalAdapter,
+  createTerminalAdapter,
+  runTerminalCommand,
+} from "./runtime/terminal-adapter.js";
+
+// Schema Types (including Terminal Node types)
+export type {
+  PraxisSchema,
+  NodeDefinition,
+  NodeBindings,
+  TerminalNodeProps,
+  OrchestrationDefinition,
+  ValidationResult,
+  ValidationError,
+  ModelDefinition,
+  ComponentDefinition,
+  LogicDefinition,
+} from "./core/schema/types.js";
+export { validateSchema, createSchemaTemplate } from "./core/schema/types.js";
+
+// Schema Loader (supports JSON, YAML, and TS)
+export type {
+  LoaderOptions,
+  LoaderResult,
+} from "./core/schema/loader.js";
+export {
+  loadSchema,
+  loadSchemaFromJson,
+  loadSchemaFromYaml,
+  loadSchemaFromFile,
+  validateForGeneration,
+} from "./core/schema/loader.js";
+

package/src/integrations/pluresdb.ts

@@ -0,0 +1,93 @@
+/**
+ * PluresDB Integration (Placeholder)
+ * 
+ * Future integration with pluresdb - reactive graph datastore and event source/sink.
+ * This module will provide adapters for:
+ * - Storing Praxis state in pluresdb
+ * - Sourcing events from pluresdb
+ * - Sinking events to pluresdb
+ * - Reactive queries and subscriptions
+ */
+
+import type { LogicEngine } from "../core/engine.js";
+import type { PraxisEvent, PraxisFact } from "../core/protocol.js";
+
+/**
+ * Placeholder for pluresdb adapter
+ * 
+ * Future implementation will provide:
+ * - Event sourcing (persist events to pluresdb)
+ * - State snapshots (persist state to pluresdb)
+ * - Event replay (rebuild state from events)
+ * - Reactive queries (subscribe to state changes)
+ */
+export interface PluresDBAdapter<TContext = unknown> {
+  /**
+   * Persist events to pluresdb
+   */
+  persistEvents(events: PraxisEvent[]): Promise<void>;
+
+  /**
+   * Persist facts to pluresdb
+   */
+  persistFacts(facts: PraxisFact[]): Promise<void>;
+
+  /**
+   * Load events from pluresdb
+   */
+  loadEvents(query?: unknown): Promise<PraxisEvent[]>;
+
+  /**
+   * Subscribe to new events from pluresdb
+   */
+  subscribeToEvents(
+    callback: (events: PraxisEvent[]) => void,
+    query?: unknown
+  ): () => void;
+
+  /**
+   * Attach the adapter to an engine
+   */
+  attachEngine(engine: LogicEngine<TContext>): void;
+}
+
+/**
+ * Create a pluresdb adapter (placeholder implementation)
+ * 
+ * @example
+ * // Future usage:
+ * const adapter = createPluresDBAdapter({
+ *   connection: pluresdbClient,
+ *   collection: "myapp-events"
+ * });
+ * adapter.attachEngine(engine);
+ */
+export function createPluresDBAdapter<TContext = unknown>(
+  _options: unknown
+): PluresDBAdapter<TContext> {
+  return {
+    async persistEvents(_events: PraxisEvent[]): Promise<void> {
+      // TODO: Implement pluresdb event persistence
+      throw new Error("PluresDB integration not yet implemented");
+    },
+    async persistFacts(_facts: PraxisFact[]): Promise<void> {
+      // TODO: Implement pluresdb fact persistence
+      throw new Error("PluresDB integration not yet implemented");
+    },
+    async loadEvents(_query?: unknown): Promise<PraxisEvent[]> {
+      // TODO: Implement pluresdb event loading
+      throw new Error("PluresDB integration not yet implemented");
+    },
+    subscribeToEvents(
+      _callback: (events: PraxisEvent[]) => void,
+      _query?: unknown
+    ): () => void {
+      // TODO: Implement pluresdb event subscription
+      throw new Error("PluresDB integration not yet implemented");
+    },
+    attachEngine(_engine: LogicEngine<TContext>): void {
+      // TODO: Implement engine attachment
+      throw new Error("PluresDB integration not yet implemented");
+    },
+  };
+}