@plures/praxis 1.4.0 → 2.0.0

package/dist/browser/reactive-engine.svelte-DjynI82A.d.ts

@@ -1,688 +0,0 @@
-/**
- * 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
- *    - Compatibility shims where possible
- */
-/**
- * Protocol version following semantic versioning
- */
-declare const PRAXIS_PROTOCOL_VERSION: "1.0.0";
-/**
- * A fact is a typed proposition about the domain.
- * Examples: UserLoggedIn, CartItem, NetworkOnline
- */
-interface PraxisFact {
-    /** Tag identifying the fact type */
-    tag: string;
-    /** Payload containing the fact data */
-    payload: unknown;
-}
-/**
- * An event is a temporally ordered fact meant to drive change.
- * Examples: LOGIN, LOGOUT, ADD_TO_CART
- */
-interface PraxisEvent {
-    /** Tag identifying the event type */
-    tag: string;
-    /** Payload containing the event data */
-    payload: unknown;
-}
-/**
- * The state of the Praxis engine at a point in time.
- */
-interface PraxisState {
-    /** Application context (domain-specific data) */
-    context: unknown;
-    /** Current facts about the domain */
-    facts: PraxisFact[];
-    /**
-     * Events currently being processed in this step.
-     * Available to rules during execution — guaranteed to contain the exact
-     * events passed to step()/stepWithContext().
-     * Empty outside of step execution.
-     */
-    events?: PraxisEvent[];
-    /** Optional metadata (timestamps, version, etc.) */
-    meta?: Record<string, unknown>;
-    /** Protocol version (for cross-language compatibility) */
-    protocolVersion?: string;
-}
-/**
- * Diagnostic information about constraint violations or rule errors.
- */
-interface PraxisDiagnostics {
-    /** Kind of diagnostic */
-    kind: 'constraint-violation' | 'rule-error';
-    /** Human-readable message */
-    message: string;
-    /** Additional diagnostic data */
-    data?: unknown;
-}
-/**
- * Configuration for a step execution.
- * Specifies which rules and constraints to apply.
- */
-interface PraxisStepConfig {
-    /** IDs of rules to apply during this step */
-    ruleIds: string[];
-    /** IDs of constraints to check during this step */
-    constraintIds: string[];
-}
-/**
- * Result of a step execution.
- */
-interface PraxisStepResult {
-    /** New state after applying rules and checking constraints */
-    state: PraxisState;
-    /** Diagnostics from rule execution and constraint checking */
-    diagnostics: PraxisDiagnostics[];
-}
-/**
- * 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.
- */
-type PraxisStepFn = (state: PraxisState, events: PraxisEvent[], config: PraxisStepConfig) => PraxisStepResult;
-
-/**
- * Decision Ledger - Contract Types
- *
- * Types for defining and validating contracts for rules and constraints.
- * All types are JSON-serializable for cross-language compatibility.
- */
-/**
- * A single assumption made during contract definition.
- */
-interface Assumption {
-    /** Stable unique identifier for the assumption */
-    id: string;
-    /** The assumption statement */
-    statement: string;
-    /** Confidence level (0.0 to 1.0) */
-    confidence: number;
-    /** Justification for the assumption */
-    justification: string;
-    /** What this assumption was derived from */
-    derivedFrom?: string;
-    /** What artifacts this assumption impacts */
-    impacts: Array<'spec' | 'tests' | 'code'>;
-    /** Current status of the assumption */
-    status: 'active' | 'revised' | 'invalidated';
-}
-/**
- * A reference to external documentation or resources.
- */
-interface Reference {
-    /** Type of reference (e.g., 'doc', 'ticket', 'issue') */
-    type: string;
-    /** URL to the reference */
-    url?: string;
-    /** Human-readable description */
-    description?: string;
-}
-/**
- * A Given/When/Then example for a contract.
- */
-interface Example {
-    /** Initial state or preconditions */
-    given: string;
-    /** Triggering event or action */
-    when: string;
-    /** Expected outcome or postconditions */
-    then: string;
-}
-/**
- * Contract for a rule or constraint.
- * Documents the expected behavior, test cases, invariants, and assumptions.
- */
-interface Contract {
-    /** ID of the rule or constraint this contract applies to */
-    ruleId: string;
-    /** Canonical behavior description */
-    behavior: string;
-    /** Given/When/Then examples (become test vectors) */
-    examples: Example[];
-    /** TLA+-friendly invariants or Praxis-level invariants */
-    invariants: string[];
-    /** Explicit assumptions with confidence levels */
-    assumptions?: Assumption[];
-    /** References to docs, tickets, links */
-    references?: Reference[];
-    /** Contract version (for evolution tracking) */
-    version?: string;
-    /** Timestamp of contract creation */
-    timestamp?: string;
-}
-/**
- * Severity levels for contract gaps.
- */
-type Severity = 'warning' | 'error' | 'info';
-/**
- * Types of missing contract artifacts.
- */
-/**
- * Types of artifacts that can be missing from a contract.
- *
- * Note: 'tests' and 'spec' are included in this type for future extensibility
- * and SARIF reporting compatibility, but are not currently validated by the
- * validateContract function. To check for these, implement custom validation
- * logic that scans for test files or spec files in your codebase.
- */
-type MissingArtifact = 'behavior' | 'examples' | 'invariants' | 'tests' | 'spec' | 'contract';
-/**
- * A gap in contract coverage.
- */
-interface ContractGap {
-    /** ID of the rule or constraint */
-    ruleId: string;
-    /** What is missing */
-    missing: MissingArtifact[];
-    /** Severity of the gap */
-    severity: Severity;
-    /** Optional human-readable message */
-    message?: string;
-}
-
-/**
- * The result of evaluating a rule. Every rule MUST return one of:
- * - `RuleResult.emit(facts)` — rule produced facts
- * - `RuleResult.noop(reason?)` — rule evaluated but had nothing to say
- * - `RuleResult.skip(reason?)` — rule decided to skip (preconditions not met)
- * - `RuleResult.retract(tags)` — rule retracts previously emitted facts
- */
-declare class RuleResult {
-    /** The kind of result */
-    readonly kind: 'emit' | 'noop' | 'skip' | 'retract';
-    /** Facts produced (only for 'emit') */
-    readonly facts: PraxisFact[];
-    /** Fact tags to retract (only for 'retract') */
-    readonly retractTags: string[];
-    /** Optional reason (for noop/skip/retract — useful for debugging) */
-    readonly reason?: string;
-    /** The rule ID that produced this result (set by engine) */
-    ruleId?: string;
-    private constructor();
-    /**
-     * Rule produced facts.
-     *
-     * @example
-     * return RuleResult.emit([
-     *   { tag: 'sprint.behind', payload: { deficit: 5 } }
-     * ]);
-     */
-    static emit(facts: PraxisFact[]): RuleResult;
-    /**
-     * Rule evaluated but had nothing to report.
-     * Unlike returning [], this is explicit and traceable.
-     *
-     * @example
-     * if (ctx.completedHours >= expectedHours) {
-     *   return RuleResult.noop('Sprint is on pace');
-     * }
-     */
-    static noop(reason?: string): RuleResult;
-    /**
-     * Rule decided to skip because preconditions were not met.
-     * Distinct from noop: skip means "I can't evaluate", noop means "I evaluated and found nothing".
-     *
-     * @example
-     * if (!ctx.sprintName) {
-     *   return RuleResult.skip('No active sprint');
-     * }
-     */
-    static skip(reason?: string): RuleResult;
-    /**
-     * Rule retracts previously emitted facts by tag.
-     * Used when a condition that previously produced facts is no longer true.
-     *
-     * @example
-     * // Sprint was behind, but caught up
-     * if (ctx.completedHours >= expectedHours) {
-     *   return RuleResult.retract(['sprint.behind'], 'Sprint caught up');
-     * }
-     */
-    static retract(tags: string[], reason?: string): RuleResult;
-    /** Whether this result produced facts */
-    get hasFacts(): boolean;
-    /** Whether this result retracts facts */
-    get hasRetractions(): boolean;
-}
-
-/**
- * Rules and Constraints System
- *
- * This module defines the types and registry for rules and constraints.
- * Rules and constraints are identified by stable IDs and can be described as data,
- * making them portable across languages and suitable for DSL-based definitions.
- */
-
-/**
- * Unique identifier for a rule
- */
-type RuleId = string;
-/**
- * Unique identifier for a constraint
- */
-type ConstraintId = string;
-/**
- * A rule function derives new facts or transitions from context + input facts/events.
- * Rules must be pure - no side effects.
- *
- * Returns either:
- * - `RuleResult` (new API — typed, traceable, supports retraction)
- * - `PraxisFact[]` (legacy — backward compatible, will be deprecated)
- *
- * The state parameter includes `events` — the current batch being processed.
- *
- * @param state Current Praxis state (includes state.events for current batch)
- * @param events Events to process (same as state.events, provided for convenience)
- * @returns RuleResult or array of new facts
- */
-type RuleFn<TContext = unknown> = (state: PraxisState & {
-    context: TContext;
-    events: PraxisEvent[];
-}, events: PraxisEvent[]) => RuleResult | PraxisFact[];
-/**
- * A constraint function checks that an invariant holds.
- * Constraints must be pure - no side effects.
- *
- * @param state Current Praxis state
- * @returns true if constraint is satisfied, false or error message if violated
- */
-type ConstraintFn<TContext = unknown> = (state: PraxisState & {
-    context: TContext;
-}) => boolean | string;
-/**
- * Descriptor for a rule, including its ID, description, and implementation.
- */
-interface RuleDescriptor<TContext = unknown> {
-    /** Unique identifier for the rule */
-    id: RuleId;
-    /** Human-readable description */
-    description: string;
-    /** Implementation function */
-    impl: RuleFn<TContext>;
-    /**
-     * Optional event type filter — only evaluate this rule when at least one
-     * event in the batch has a matching `tag`. When omitted, the rule runs on
-     * every step (catch-all).
-     *
-     * Accepts a single tag string or an array of tags.
-     *
-     * @example
-     * { id: 'sprint-behind', eventTypes: ['sprint.update'], impl: ... }
-     * { id: 'note-check', eventTypes: 'note.update', impl: ... }
-     */
-    eventTypes?: string | string[];
-    /** Optional contract for rule behavior */
-    contract?: Contract;
-    /** Optional metadata */
-    meta?: Record<string, unknown>;
-}
-/**
- * Descriptor for a constraint, including its ID, description, and implementation.
- */
-interface ConstraintDescriptor<TContext = unknown> {
-    /** Unique identifier for the constraint */
-    id: ConstraintId;
-    /** Human-readable description */
-    description: string;
-    /** Implementation function */
-    impl: ConstraintFn<TContext>;
-    /** Optional contract for constraint behavior */
-    contract?: Contract;
-    /** Optional metadata */
-    meta?: Record<string, unknown>;
-}
-/**
- * A Praxis module bundles rules and constraints.
- * Modules can be composed and registered with the engine.
- */
-interface PraxisModule<TContext = unknown> {
-    /** Rules in this module */
-    rules: RuleDescriptor<TContext>[];
-    /** Constraints in this module */
-    constraints: ConstraintDescriptor<TContext>[];
-    /** Optional module metadata */
-    meta?: Record<string, unknown>;
-}
-/**
- * Compliance validation options for rule/constraint registration.
- */
-interface RegistryComplianceOptions {
-    /** Enable contract checks during registration (default: true in dev) */
-    enabled?: boolean;
-    /** Required contract fields to be present */
-    requiredFields?: Array<'behavior' | 'examples' | 'invariants'>;
-    /** Severity to use for missing contracts */
-    missingSeverity?: Severity;
-    /** Callback for contract gaps (e.g., to emit facts) */
-    onGap?: (gap: ContractGap) => void;
-}
-/**
- * PraxisRegistry configuration options.
- */
-interface PraxisRegistryOptions {
-    compliance?: RegistryComplianceOptions;
-}
-/**
- * Registry for rules and constraints.
- * Maps IDs to their descriptors.
- */
-declare class PraxisRegistry<TContext = unknown> {
-    private rules;
-    private constraints;
-    private readonly compliance;
-    private contractGaps;
-    constructor(options?: PraxisRegistryOptions);
-    /**
-     * Register a rule
-     */
-    registerRule(descriptor: RuleDescriptor<TContext>): void;
-    /**
-     * Register a constraint
-     */
-    registerConstraint(descriptor: ConstraintDescriptor<TContext>): void;
-    /**
-     * Register a module (all its rules and constraints)
-     */
-    registerModule(module: PraxisModule<TContext>): void;
-    /**
-     * Get a rule by ID
-     */
-    getRule(id: RuleId): RuleDescriptor<TContext> | undefined;
-    /**
-     * Get a constraint by ID
-     */
-    getConstraint(id: ConstraintId): ConstraintDescriptor<TContext> | undefined;
-    /**
-     * Get all registered rule IDs
-     */
-    getRuleIds(): RuleId[];
-    /**
-     * Get all registered constraint IDs
-     */
-    getConstraintIds(): ConstraintId[];
-    /**
-     * Get all rules
-     */
-    getAllRules(): RuleDescriptor<TContext>[];
-    /**
-     * Get all constraints
-     */
-    getAllConstraints(): ConstraintDescriptor<TContext>[];
-    /**
-    * Get collected contract gaps from registration-time validation.
-    */
-    getContractGaps(): ContractGap[];
-    /**
-    * Clear collected contract gaps.
-    */
-    clearContractGaps(): void;
-    private trackContractCompliance;
-    private validateDescriptorContract;
-}
-
-/**
- * Praxis Logic Engine
- *
- * The logic engine manages state, processes events through rules,
- * checks constraints, and provides a strongly-typed API for application logic.
- */
-
-/**
- * Options for creating a Praxis engine
- */
-interface PraxisEngineOptions<TContext = unknown> {
-    /** Initial context */
-    initialContext: TContext;
-    /** Registry of rules and constraints */
-    registry: PraxisRegistry<TContext>;
-    /** Initial facts (optional) */
-    initialFacts?: PraxisFact[];
-    /** Initial metadata (optional) */
-    initialMeta?: Record<string, unknown>;
-    /**
-     * Fact deduplication strategy (default: 'last-write-wins').
-     *
-     * - 'none': facts accumulate without dedup (original behavior)
-     * - 'last-write-wins': only keep the latest fact per tag (most common)
-     * - 'append': keep all facts but cap at maxFacts
-     */
-    factDedup?: 'none' | 'last-write-wins' | 'append';
-    /**
-     * Maximum number of facts to retain (default: 1000).
-     * When exceeded, oldest facts are evicted (FIFO).
-     * Set to 0 for unlimited (not recommended).
-     */
-    maxFacts?: number;
-}
-/**
- * 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.
- */
-declare class LogicEngine<TContext = unknown> {
-    private state;
-    private readonly registry;
-    private readonly factDedup;
-    private readonly maxFacts;
-    constructor(options: PraxisEngineOptions<TContext>);
-    /**
-     * Get the current state (immutable copy)
-     */
-    getState(): Readonly<PraxisState & {
-        context: TContext;
-    }>;
-    /**
-     * Get the current context
-     */
-    getContext(): TContext;
-    /**
-     * Get current facts
-     */
-    getFacts(): PraxisFact[];
-    /**
-     * 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
-     */
-    step(events: PraxisEvent[]): PraxisStepResult;
-    /**
-     * 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;
-    /**
-     * 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;
-    /**
-     * Atomically update context AND process events in a single call.
-     *
-     * This avoids the fragile pattern of calling updateContext() then step()
-     * separately, where rules could see stale context if the ordering is wrong.
-     *
-     * @param updater Function that produces new context from old context
-     * @param events Events to process after context is updated
-     * @returns Result with new state and diagnostics
-     *
-     * @example
-     * engine.stepWithContext(
-     *   ctx => ({ ...ctx, sprintName: sprint.name, items: sprint.items }),
-     *   [{ tag: 'sprint.update', payload: { name: sprint.name } }]
-     * );
-     */
-    stepWithContext(updater: (context: TContext) => TContext, events: PraxisEvent[]): PraxisStepResult;
-    /**
-     * Add facts directly (for exceptional cases).
-     * Generally, facts should be added through rules.
-     *
-     * @param facts Facts to add
-     */
-    addFacts(facts: PraxisFact[]): void;
-    /**
-     * Check all constraints without processing any events.
-     *
-     * Useful for validation-only scenarios (e.g., form validation,
-     * pre-save checks) where you want constraint diagnostics without
-     * triggering any rules.
-     *
-     * @returns Array of constraint violation diagnostics (empty = all passing)
-     */
-    checkConstraints(): PraxisDiagnostics[];
-    /**
-     * Clear all facts
-     */
-    clearFacts(): void;
-    /**
-     * Reset the engine to initial state
-     */
-    reset(options: PraxisEngineOptions<TContext>): void;
-}
-/**
- * Create a new Praxis logic engine.
- *
- * @param options Engine options
- * @returns New LogicEngine instance
- */
-declare function createPraxisEngine<TContext = unknown>(options: PraxisEngineOptions<TContext>): LogicEngine<TContext>;
-
-/**
- * Praxis Reactive Logic Engine - Svelte 5 Implementation
- *
- * This version uses Svelte 5 runes ($state) for built-in reactivity.
- * The state object is automatically reactive when used in Svelte components.
- */
-
-interface ReactiveEngineOptions<TContext> {
-    initialContext: TContext;
-    initialFacts?: any[];
-    initialMeta?: Record<string, unknown>;
-    registry?: PraxisRegistry<TContext>;
-}
-/**
- * Reactive Logic Engine using Svelte 5 runes.
- * Combines the standard LogicEngine with reactive state management.
- */
-declare class ReactiveLogicEngine<TContext extends object> {
-    state: {
-        context: TContext;
-        facts: any[];
-        meta: Record<string, unknown>;
-    };
-    private _engine;
-    constructor(options: ReactiveEngineOptions<TContext>);
-    /**
-     * Access the reactive context.
-     * In Svelte 5 components, changes to this object will automatically trigger updates.
-     */
-    get context(): TContext;
-    /**
-     * Access the reactive facts list.
-     */
-    get facts(): any[];
-    /**
-     * Access the reactive metadata.
-     */
-    get meta(): Record<string, unknown>;
-    /**
-     * Apply a mutation to the state.
-     * Changes will automatically trigger Svelte reactivity.
-     *
-     * @param mutator A function that receives the state and modifies it.
-     */
-    apply(mutator: (state: {
-        context: TContext;
-        facts: any[];
-        meta: Record<string, unknown>;
-    }) => void): void;
-    /**
-     * Process events through the logic engine and update reactive state.
-     *
-     * @param events Events to process
-     */
-    step(events: PraxisEvent[]): void;
-}
-/**
- * Create a reactive logic engine with Svelte 5 runes.
- *
- * @param options Configuration options
- * @returns A reactive logic engine instance
- *
- * @example
- * ```svelte
- * <script lang="ts">
- *   import { createReactiveEngine } from '@plures/praxis/svelte';
- *
- *   const engine = createReactiveEngine({
- *     initialContext: { count: 0 },
- *     registry
- *   });
- *
- *   // Use $derived for computed values
- *   const count = $derived(engine.context.count);
- *   const doubled = $derived(engine.context.count * 2);
- *
- *   function increment() {
- *     engine.step([Increment.create({ amount: 1 })]);
- *   }
- * </script>
- *
- * <button on:click={increment}>Count: {count}, Doubled: {doubled}</button>
- * ```
- */
-declare function createReactiveEngine<TContext extends object>(options: ReactiveEngineOptions<TContext>): ReactiveLogicEngine<TContext>;
-
-export { type ConstraintDescriptor as C, LogicEngine as L, type PraxisState as P, type RuleDescriptor as R, type PraxisEvent as a, PraxisRegistry as b, type ConstraintFn as c, type Contract as d, type RuleFn as e, type PraxisFact as f, type PraxisModule as g, type ConstraintId as h, PRAXIS_PROTOCOL_VERSION as i, type PraxisDiagnostics as j, type PraxisEngineOptions as k, type PraxisStepConfig as l, type PraxisStepFn as m, type PraxisStepResult as n, type ReactiveEngineOptions as o, ReactiveLogicEngine as p, type RuleId as q, createPraxisEngine as r, createReactiveEngine as s };