@plures/praxis 1.4.0 → 2.0.0

package/dist/browser/integrations/svelte.d.ts

@@ -1,5 +1,7 @@
-import { P as PraxisState, a as PraxisEvent, L as LogicEngine } from '../reactive-engine.svelte-DjynI82A.js';
-export { o as ReactiveEngineOptions, p as ReactiveLogicEngine, s as createReactiveEngine } from '../reactive-engine.svelte-DjynI82A.js';
+import { L as LogicEngine } from '../reactive-engine.svelte-BwWadvAW.js';
+export { R as ReactiveEngineOptions, a as ReactiveLogicEngine, c as createReactiveEngine } from '../reactive-engine.svelte-BwWadvAW.js';
+import { P as PraxisState, a as PraxisEvent } from '../rule-result-DcXWe9tn.js';
+import '../rules-BaWMqxuG.js';
 
 /**
  * Svelte v5 Integration

package/dist/browser/integrations/svelte.js

@@ -1,8 +1,9 @@
 import {
   ReactiveLogicEngine,
   createReactiveEngine
-} from "../chunk-N63K4KWS.js";
-import "../chunk-MJK3IYTJ.js";
+} from "../chunk-4IRUGWR3.js";
+import "../chunk-JZDJU2DO.js";
+import "../chunk-IG5BJ2MT.js";
 
 // src/integrations/svelte.ts
 function createPraxisStore(engine) {

package/dist/browser/project/index.d.ts

@@ -0,0 +1,177 @@
+import { d as PraxisModule } from '../rules-BaWMqxuG.js';
+import '../rule-result-DcXWe9tn.js';
+
+/**
+ * Praxis Project Logic — Types
+ *
+ * Types for developer workflow rules: gates, semver contracts,
+ * commit generation, and branch management.
+ */
+type GateStatus = 'open' | 'closed' | 'blocked';
+interface GateConfig {
+    /** Expectations that must be satisfied for the gate to open */
+    expects: string[];
+    /** Action when gate is satisfied */
+    onSatisfied?: string;
+    /** Action when gate is violated */
+    onViolation?: string;
+}
+interface GateState {
+    name: string;
+    status: GateStatus;
+    /** Which expectations are satisfied */
+    satisfied: string[];
+    /** Which expectations are not satisfied */
+    unsatisfied: string[];
+    /** Timestamp of last status change */
+    lastChanged: number;
+}
+interface SemverContractConfig {
+    /** Files/sources that contain version strings */
+    sources: string[];
+    /** Invariants about version consistency */
+    invariants: string[];
+}
+interface SemverReport {
+    /** Whether all sources have consistent versions */
+    consistent: boolean;
+    /** Version found in each source */
+    versions: Record<string, string>;
+    /** Invariant violations */
+    violations: string[];
+}
+interface PraxisDiff {
+    /** Rules added since last commit */
+    rulesAdded: string[];
+    /** Rules removed */
+    rulesRemoved: string[];
+    /** Rules modified */
+    rulesModified: string[];
+    /** Contracts added */
+    contractsAdded: string[];
+    /** Contracts removed */
+    contractsRemoved: string[];
+    /** Expectations added */
+    expectationsAdded: string[];
+    /** Expectations removed */
+    expectationsRemoved: string[];
+    /** Gate state changes */
+    gateChanges: Array<{
+        gate: string;
+        from: GateStatus;
+        to: GateStatus;
+    }>;
+}
+interface BranchRulesConfig {
+    /** Naming convention pattern (e.g., 'feat/{name}', 'fix/{issue}') */
+    naming: string;
+    /** Conditions required for merge */
+    mergeConditions: string[];
+}
+interface PredefinedGateConfig {
+    /** Whether to enable this gate */
+    enabled?: boolean;
+    /** Custom expectations to add */
+    additionalExpects?: string[];
+}
+
+/**
+ * Praxis Project Logic
+ *
+ * Developer workflow rules: gates, semver contracts, commit message
+ * generation from behavioral deltas, and branch management.
+ *
+ * @example
+ * ```ts
+ * import { defineGate, semverContract, commitFromState } from '@plures/praxis/project';
+ *
+ * const testGate = defineGate('test', {
+ *   expects: ['all-tests-pass', 'no-type-errors'],
+ *   onSatisfied: 'merge-allowed',
+ *   onViolation: 'merge-blocked',
+ * });
+ *
+ * const diff = { rulesAdded: ['auth/login'], ... };
+ * const message = commitFromState(diff);
+ * // → "feat(rules): add auth/login rule"
+ * ```
+ */
+
+/**
+ * Context type for gates. Apps extend their context with gate state.
+ */
+interface GateContext {
+    gates?: Record<string, GateState>;
+    expectations?: Record<string, boolean>;
+}
+/**
+ * Define a feature gate — a condition that must be satisfied before
+ * proceeding with a workflow step (deploy, merge, release, etc.).
+ *
+ * @example
+ * ```ts
+ * const testGate = defineGate('test', {
+ *   expects: ['all-tests-pass', 'no-type-errors'],
+ *   onSatisfied: 'deploy-allowed',
+ *   onViolation: 'deploy-blocked',
+ * });
+ * registry.registerModule(testGate);
+ * ```
+ */
+declare function defineGate(name: string, config: GateConfig): PraxisModule<GateContext>;
+/**
+ * Create a semver contract module that checks version consistency
+ * across multiple sources (package.json, Cargo.toml, etc.).
+ *
+ * @example
+ * ```ts
+ * const version = semverContract({
+ *   sources: ['package.json', 'src/version.ts', 'README.md'],
+ *   invariants: ['All sources must have the same version'],
+ * });
+ * ```
+ */
+declare function semverContract(config: SemverContractConfig): PraxisModule;
+/**
+ * Generate a conventional commit message from a behavioral delta.
+ *
+ * Unlike file-based commit messages, this describes WHAT behavioral
+ * changes occurred — rule additions, contract changes, expectation shifts.
+ *
+ * @example
+ * ```ts
+ * const msg = commitFromState({
+ *   rulesAdded: ['auth/login', 'auth/logout'],
+ *   contractsAdded: ['auth/login'],
+ *   ...empty
+ * });
+ * // → "feat(rules): add auth/login, auth/logout\n\nContracts added: auth/login"
+ * ```
+ */
+declare function commitFromState(diff: PraxisDiff): string;
+/**
+ * Create branch management rules.
+ *
+ * @example
+ * ```ts
+ * const branches = branchRules({
+ *   naming: 'feat/{name}',
+ *   mergeConditions: ['tests-pass', 'review-approved'],
+ * });
+ * ```
+ */
+declare function branchRules(config: BranchRulesConfig): PraxisModule;
+/**
+ * Create a lint gate — blocks workflow until linting passes.
+ */
+declare function lintGate(config?: PredefinedGateConfig): PraxisModule<GateContext>;
+/**
+ * Create a format gate — blocks workflow until formatting is correct.
+ */
+declare function formatGate(config?: PredefinedGateConfig): PraxisModule<GateContext>;
+/**
+ * Create an expectation gate — blocks workflow until expectations are verified.
+ */
+declare function expectationGate(config?: PredefinedGateConfig): PraxisModule<GateContext>;
+
+export { type BranchRulesConfig, type GateConfig, type GateState, type GateStatus, type PraxisDiff, type PredefinedGateConfig, type SemverContractConfig, type SemverReport, branchRules, commitFromState, defineGate, expectationGate, formatGate, lintGate, semverContract };

package/dist/browser/project/index.js

@@ -0,0 +1,19 @@
+import {
+  branchRules,
+  commitFromState,
+  defineGate,
+  expectationGate,
+  formatGate,
+  lintGate,
+  semverContract
+} from "../chunk-BQOYZBWA.js";
+import "../chunk-IG5BJ2MT.js";
+export {
+  branchRules,
+  commitFromState,
+  defineGate,
+  expectationGate,
+  formatGate,
+  lintGate,
+  semverContract
+};

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

@@ -0,0 +1,224 @@
+import { b as PraxisFact, P as PraxisState, a as PraxisEvent, c as PraxisStepResult, d as PraxisStepConfig, e as PraxisDiagnostics } from './rule-result-DcXWe9tn.js';
+import { P as PraxisRegistry } from './rules-BaWMqxuG.js';
+
+/**
+ * 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 { LogicEngine as L, type PraxisEngineOptions as P, type ReactiveEngineOptions as R, ReactiveLogicEngine as a, createPraxisEngine as b, createReactiveEngine as c };

package/dist/browser/rule-result-DcXWe9tn.d.ts

@@ -0,0 +1,206 @@
+/**
+ * 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;
+
+/**
+ * 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;
+}
+/**
+ * A rule function that returns a typed RuleResult.
+ * New API — replaces the old PraxisFact[] return type.
+ */
+type TypedRuleFn<TContext = unknown> = (state: PraxisState & {
+    context: TContext;
+    events: PraxisEvent[];
+}, events: PraxisEvent[]) => RuleResult;
+/**
+ * Convenience: create a fact object (just a shorthand)
+ */
+declare function fact(tag: string, payload: unknown): PraxisFact;
+
+export { type PraxisState as P, RuleResult as R, type TypedRuleFn as T, type PraxisEvent as a, type PraxisFact as b, type PraxisStepResult as c, type PraxisStepConfig as d, type PraxisDiagnostics as e, PRAXIS_PROTOCOL_VERSION as f, type PraxisStepFn as g, fact as h };