@plures/praxis 1.4.4 → 2.0.3

package/dist/node/unified/index.d.cts

@@ -0,0 +1,240 @@
+import { R as RuleResult } from '../rule-result-B9GMivAn.cjs';
+export { f as fact } from '../rule-result-B9GMivAn.cjs';
+import { e as PraxisDiagnostics, b as PraxisFact } from '../protocol-DcyGMmWY.cjs';
+
+/** 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/node/unified/index.d.ts

@@ -0,0 +1,240 @@
+import { R as RuleResult } from '../rule-result-Bo3sFMmN.js';
+export { f as fact } from '../rule-result-Bo3sFMmN.js';
+import { e as PraxisDiagnostics, b as PraxisFact } from '../protocol-DcyGMmWY.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/node/unified/index.js

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