@plures/praxis 1.4.0 → 2.0.0

package/dist/browser/rules-BaWMqxuG.d.ts

@@ -0,0 +1,277 @@
+import { P as PraxisState, a as PraxisEvent, R as RuleResult, b as PraxisFact } from './rule-result-DcXWe9tn.js';
+
+/**
+ * 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;
+}
+
+/**
+ * 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;
+}
+
+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-6MVRT7CK.js";
+import {
+  RuleResult,
+  fact
+} from "../chunk-IG5BJ2MT.js";
+export {
+  RuleResult,
+  createApp,
+  defineConstraint,
+  defineModule,
+  definePath,
+  defineRule,
+  fact
+};