@plures/praxis 1.4.4 → 2.0.3

package/dist/browser/{rules-i1LHpnGd.d.ts → rules-BaWMqxuG.d.ts}

@@ -1,130 +1,4 @@
-/**
- * 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;
+import { P as PraxisState, a as PraxisEvent, R as RuleResult, b as PraxisFact } from './rule-result-DcXWe9tn.js';
 
 /**
  * Decision Ledger - Contract Types
@@ -225,83 +99,6 @@ interface ContractGap {
     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;
-}
-/**
- * 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;
-
 /**
  * Rules and Constraints System
  *
@@ -477,4 +274,4 @@ declare class PraxisRegistry<TContext = unknown> {
     private validateDescriptorContract;
 }
 
-export { type ConstraintDescriptor as C, type PraxisState as P, type RuleDescriptor as R, type TypedRuleFn as T, type PraxisEvent as a, PraxisRegistry as b, type PraxisFact as c, type PraxisStepResult as d, type PraxisStepConfig as e, type PraxisDiagnostics as f, type ConstraintFn as g, type Contract as h, type RuleFn as i, type PraxisModule as j, type ConstraintId as k, PRAXIS_PROTOCOL_VERSION as l, type PraxisStepFn as m, type RuleId as n, RuleResult as o, fact as p };
+export { type ConstraintDescriptor as C, PraxisRegistry as P, type RuleDescriptor as R, type ConstraintFn as a, type Contract as b, type RuleFn as c, type PraxisModule as d, type ConstraintId as e, type RuleId as f };

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

@@ -0,0 +1,239 @@
+import { e as PraxisDiagnostics, b as PraxisFact, R as RuleResult } from '../rule-result-DcXWe9tn.js';
+export { h as fact } from '../rule-result-DcXWe9tn.js';
+
+/** Minimal store contract — anything with subscribe() */
+interface Subscribable<T> {
+    subscribe(cb: (value: T) => void): (() => void) | {
+        unsubscribe(): void;
+    };
+}
+/** Schema definition for a graph path */
+interface PathSchema<T = unknown> {
+    /** The graph path (e.g., 'sprint/current') */
+    path: string;
+    /** Default/initial value */
+    initial: T;
+    /** Optional TTL for staleness detection (ms) */
+    staleTtl?: number;
+    /** Whether this path is a collection (maps over children) */
+    collection?: boolean;
+}
+/**
+ * Define a typed graph path.
+ * This is the primary API for declaring what data exists in your app.
+ *
+ * @example
+ * const Sprint = definePath<SprintInfo | null>('sprint/current', null);
+ * const Items = definePath<WorkItem[]>('sprint/items', [], { collection: true });
+ * const Loading = definePath<boolean>('sprint/loading', false);
+ */
+declare function definePath<T>(path: string, initial: T, opts?: Omit<PathSchema<T>, 'path' | 'initial'>): PathSchema<T>;
+interface QueryOptions<T> {
+    /** Filter function for collections */
+    where?: (item: T extends (infer U)[] ? U : T) => boolean;
+    /** Select/map function */
+    select?: (item: T) => unknown;
+    /** Sort comparator */
+    sort?: (a: any, b: any) => number;
+    /** Limit results */
+    limit?: number;
+}
+/**
+ * A reactive reference returned by query().
+ * Has a Svelte-compatible subscribe() and a .current getter.
+ */
+interface ReactiveRef<T> extends Subscribable<T> {
+    /** Current value (synchronous read) */
+    readonly current: T;
+    /** Svelte store contract — subscribe returns unsubscribe fn */
+    subscribe(cb: (value: T) => void): () => void;
+}
+interface MutationResult {
+    /** Whether the mutation was accepted */
+    accepted: boolean;
+    /** Constraint violations that blocked the mutation (if any) */
+    violations: PraxisDiagnostics[];
+    /** Facts emitted by rules triggered by this mutation */
+    facts: PraxisFact[];
+}
+interface UnifiedRule {
+    /** Unique rule ID */
+    id: string;
+    /** Human-readable description */
+    description?: string;
+    /** Graph paths this rule watches — auto-subscribed */
+    watch: string[];
+    /** Rule evaluation function — receives watched values by path */
+    evaluate: (values: Record<string, any>, facts: PraxisFact[]) => RuleResult;
+}
+interface UnifiedConstraint {
+    /** Unique constraint ID */
+    id: string;
+    /** Human-readable description */
+    description?: string;
+    /** Graph paths this constraint reads */
+    watch: string[];
+    /** Validation function — return true if valid, string if violated */
+    validate: (values: Record<string, any>) => true | string;
+}
+interface LivenessConfig {
+    /** Paths that must update within `timeoutMs` after init */
+    expect: string[];
+    /** Milliseconds to wait before flagging staleness (default: 5000) */
+    timeoutMs?: number;
+    /** Callback when a path is stale */
+    onStale?: (path: string, elapsed: number) => void;
+}
+interface PraxisAppConfig {
+    /** App name (used in Chronos context) */
+    name: string;
+    /** Graph schema — all paths the app uses */
+    schema: PathSchema[];
+    /** Business rules */
+    rules?: UnifiedRule[];
+    /** Constraints */
+    constraints?: UnifiedConstraint[];
+    /** Liveness monitoring */
+    liveness?: LivenessConfig;
+    /** Chronos options */
+    chronos?: {
+        batchMs?: number;
+        maxBatch?: number;
+    };
+}
+
+/**
+ * Praxis Unified Reactive Layer — Core
+ *
+ * createApp() → query() / mutate()
+ *
+ * The developer defines a schema + rules. Praxis handles:
+ * - Reactive state (backed by Unum graph DB)
+ * - Automatic rule evaluation on state changes
+ * - Constraint enforcement on mutations
+ * - Chronos logging for every state change
+ * - Liveness monitoring (detect broken plumbing)
+ * - Svelte-compatible store contract
+ */
+
+interface TimelineEntry {
+    id: string;
+    timestamp: number;
+    path: string;
+    kind: 'mutation' | 'rule-eval' | 'constraint-check' | 'liveness';
+    data: Record<string, unknown>;
+}
+interface PraxisApp {
+    /** Reactive query — returns a Svelte-compatible store */
+    query: <T>(path: string, opts?: QueryOptions<T>) => ReactiveRef<T>;
+    /** Write to the graph — validates through constraints first */
+    mutate: (path: string, value: unknown) => MutationResult;
+    /** Batch multiple mutations atomically */
+    batch: (fn: (mutate: (path: string, value: unknown) => void) => void) => MutationResult;
+    /** Current facts */
+    facts: () => PraxisFact[];
+    /** Current constraint violations */
+    violations: () => PraxisDiagnostics[];
+    /** Timeline (Chronos entries) */
+    timeline: () => TimelineEntry[];
+    /** Force re-evaluate all rules */
+    evaluate: () => void;
+    /** Cleanup */
+    destroy: () => void;
+    /** Liveness status — which paths are stale */
+    liveness: () => Record<string, {
+        stale: boolean;
+        lastUpdated: number;
+        elapsed: number;
+    }>;
+}
+/**
+ * Create a Praxis application.
+ *
+ * This is the single entry point. It creates the reactive graph,
+ * wires rules and constraints, starts Chronos logging, and returns
+ * query() and mutate() — the only two functions a developer needs.
+ *
+ * @example
+ * ```ts
+ * import { createApp, definePath, defineRule } from '@plures/praxis';
+ *
+ * const Sprint = definePath<SprintInfo | null>('sprint/current', null);
+ * const Loading = definePath<boolean>('sprint/loading', false);
+ *
+ * const app = createApp({
+ *   name: 'sprint-log',
+ *   schema: [Sprint, Loading],
+ *   rules: [sprintBehindRule, capacityRule],
+ *   constraints: [noCloseWithoutHoursConstraint],
+ * });
+ *
+ * // In a Svelte component:
+ * const sprint = app.query<SprintInfo | null>('sprint/current');
+ * // $sprint is reactive — updates automatically
+ *
+ * // To write:
+ * app.mutate('sprint/current', sprintData);
+ * // Constraints validated, rules re-evaluated, Chronos logged — all automatic
+ * ```
+ */
+declare function createApp(config: PraxisAppConfig): PraxisApp;
+
+/**
+ * Praxis Unified — Rule DSL helpers
+ *
+ * Developers define rules as plain objects with watch paths.
+ * No manual subscriptions, no wirePraxis(), no context mapping.
+ */
+
+/**
+ * Define a rule that watches graph paths and auto-evaluates.
+ *
+ * @example
+ * const sprintBehind = defineRule({
+ *   id: 'sprint.behind',
+ *   watch: ['sprint/current'],
+ *   evaluate: (values) => {
+ *     const sprint = values['sprint/current'];
+ *     if (!sprint) return RuleResult.skip('No sprint');
+ *     const pace = sprint.currentDay / sprint.totalDays;
+ *     const work = sprint.completedHours / sprint.totalHours;
+ *     if (work >= pace) return RuleResult.retract(['sprint.behind']);
+ *     return RuleResult.emit([fact('sprint.behind', { pace, work })]);
+ *   }
+ * });
+ */
+declare function defineRule(rule: UnifiedRule): UnifiedRule;
+/**
+ * Define a constraint that validates mutations before they're applied.
+ *
+ * @example
+ * const noCloseWithoutHours = defineConstraint({
+ *   id: 'no-close-without-hours',
+ *   description: 'Cannot close a work item with 0 completed hours',
+ *   watch: ['sprint/items'],
+ *   validate: (values) => {
+ *     const items = values['sprint/items'] ?? [];
+ *     const bad = items.find(i => i.state === 'Closed' && !i.completedWork);
+ *     if (bad) return `Item #${bad.id} cannot be closed with 0 hours`;
+ *     return true;
+ *   }
+ * });
+ */
+declare function defineConstraint(constraint: UnifiedConstraint): UnifiedConstraint;
+/**
+ * Compose multiple rules into a named module.
+ *
+ * @example
+ * const sprintModule = defineModule('sprint-health', [
+ *   sprintBehindRule,
+ *   capacityRule,
+ *   endNearRule,
+ * ]);
+ */
+declare function defineModule(name: string, rules: UnifiedRule[]): {
+    name: string;
+    rules: UnifiedRule[];
+};
+
+export { type LivenessConfig, type MutationResult, type PathSchema, type PraxisApp, type PraxisAppConfig, type QueryOptions, type ReactiveRef, RuleResult, type UnifiedConstraint, type UnifiedRule, createApp, defineConstraint, defineModule, definePath, defineRule };

package/dist/browser/unified/index.js

@@ -0,0 +1,20 @@
+import {
+  createApp,
+  defineConstraint,
+  defineModule,
+  definePath,
+  defineRule
+} from "../chunk-IUEKGHQN.js";
+import {
+  RuleResult,
+  fact
+} from "../chunk-IG5BJ2MT.js";
+export {
+  RuleResult,
+  createApp,
+  defineConstraint,
+  defineModule,
+  definePath,
+  defineRule,
+  fact
+};