@plures/praxis 1.4.0 → 2.0.0

package/dist/browser/factory/index.js

@@ -0,0 +1,15 @@
+import {
+  dataRules,
+  formRules,
+  inputRules,
+  navigationRules,
+  toastRules
+} from "../chunk-6SJ44Q64.js";
+import "../chunk-IG5BJ2MT.js";
+export {
+  dataRules,
+  formRules,
+  inputRules,
+  navigationRules,
+  toastRules
+};

package/dist/browser/index.d.ts

@@ -1,6 +1,14 @@
-import { L as LogicEngine, P as PraxisState, a as PraxisEvent, b as PraxisRegistry, R as RuleDescriptor, C as ConstraintDescriptor, c as ConstraintFn, d as Contract, e as RuleFn, f as PraxisFact, g as PraxisModule } from './reactive-engine.svelte-DjynI82A.js';
-export { h as ConstraintId, i as PRAXIS_PROTOCOL_VERSION, j as PraxisDiagnostics, k as PraxisEngineOptions, l as PraxisStepConfig, m as PraxisStepFn, n as PraxisStepResult, o as ReactiveEngineOptions, p as ReactiveLogicEngine, q as RuleId, r as createPraxisEngine, s as createReactiveEngine } from './reactive-engine.svelte-DjynI82A.js';
+import { P as PraxisState, a as PraxisEvent, b as PraxisFact } from './rule-result-DcXWe9tn.js';
+export { f as PRAXIS_PROTOCOL_VERSION, e as PraxisDiagnostics, d as PraxisStepConfig, g as PraxisStepFn, c as PraxisStepResult, R as RuleResult, T as TypedRuleFn, h as fact } from './rule-result-DcXWe9tn.js';
+import { P as PraxisRegistry, R as RuleDescriptor, C as ConstraintDescriptor, a as ConstraintFn, b as Contract, c as RuleFn, d as PraxisModule } from './rules-BaWMqxuG.js';
+export { e as ConstraintId, f as RuleId } from './rules-BaWMqxuG.js';
+import { L as LogicEngine } from './reactive-engine.svelte-BwWadvAW.js';
+export { P as PraxisEngineOptions, R as ReactiveEngineOptions, a as ReactiveLogicEngine, b as createPraxisEngine, c as createReactiveEngine } from './reactive-engine.svelte-BwWadvAW.js';
 import { LocalFirstOptions } from '@plures/pluresdb/local-first';
+export { ConditionResult, ConditionStatus, Expectation, ExpectationCondition, ExpectationResult, ExpectationSet, ExpectationSetOptions, VerifiableDescriptor, VerifiableRegistry, VerificationReport, expectBehavior, formatVerificationReport, verify } from './expectations/index.js';
+export { DataRulesConfig, FormRulesConfig, InputRulesConfig, NavigationRulesConfig, SanitizationType, ToastRulesConfig, dataRules, formRules, inputRules, navigationRules, toastRules } from './factory/index.js';
+export { BranchRulesConfig, GateConfig, GateState, GateStatus, PraxisDiff, PredefinedGateConfig, SemverContractConfig, SemverReport, branchRules, commitFromState, defineGate, expectationGate, formatGate, lintGate, semverContract } from './project/index.js';
+export { LivenessConfig, MutationResult, PathSchema, PraxisApp, PraxisAppConfig, QueryOptions, ReactiveRef, UnifiedConstraint, UnifiedRule, createApp, definePath, defineConstraint as defineUnifiedConstraint, defineModule as defineUnifiedModule, defineRule as defineUnifiedRule } from './unified/index.js';
 
 /**
  * Praxis Reactive Logic Engine
@@ -3419,4 +3427,270 @@ declare function attachAllIntegrations<TContext = unknown>(engine: LogicEngine<T
     dispose: () => void;
 }>;
 
-export { type ActivityState, type Actor, ActorManager, type CanvasDocument, type CanvasEdge, type CanvasEdgeStyle, type CanvasEditorConfig, type CanvasNode, type CanvasNodeStyle, type ComponentDefinition, ConstraintDescriptor, ConstraintFn, type ConstraintNode, type ConstraintSchema, type DefineConstraintOptions, type DefineModuleOptions, type DefineRuleOptions, type EventDefinition$1 as EventDefinition, type EventStreamEntry, type FactDefinition$1 as FactDefinition, ReactiveLogicEngine as FrameworkAgnosticReactiveEngine, type ReactiveEngineOptions as FrameworkAgnosticReactiveEngineOptions, type GeneratedDoc, type GeneratedPluresDBFile, type GraphEdge, type GuardianError, type GuardianResult, type GuardianWarning, InMemoryPraxisDB, type LifecycleState, type LoaderOptions, type LoaderResult, type LogicDefinition, LogicEngine, type ModelDefinition, type NodeBindings, type NodeDefinition, type OrchestrationDefinition, PRAXIS_PATHS, type PluresDBAdapter, type PluresDBAdapterConfig, type PluresDBAdapterOptions, PluresDBGenerator, type PluresDBGeneratorOptions, type PluresDBInstance, PluresDBPraxisAdapter, type PraxisDB, PraxisDBStore, type PraxisDBStoreOptions, PraxisEvent, PraxisFact, type PraxisLocalFirstOptions, PraxisModule, PraxisRegistry, type PraxisSchema, PraxisSchemaRegistry, PraxisState, type RegistryGraph, RegistryIntrospector, type RegistrySchema, type RegistryStats, RuleDescriptor, RuleFn, type RuleNode, type RuleSchema, type StateChangeCallback, type StateDoc, type StateDocsConfig, StateDocsGenerator, type StateMachineDoc, type StoredSchema, type TauriAppConfig, type TauriBridge, type TauriCommand, type TauriEvent, type TauriFS, type TauriFileEntry, type TauriMenuItem, type TauriNotification, type TauriNotificationOptions, type TauriPlugin, type TauriPraxisAdapter, type TauriSecurityConfig, type TauriTray, type TauriUpdateConfig, type TauriUpdateInfo, type TauriWindowConfig, type TerminalNodeProps, type TransitionDoc, type UnifiedApp, type UnifiedAppConfig, type UnsubscribeFn, type UnumAdapter, type UnumAdapterConfig, type UnumChannel, type UnumIdentity, type UnumMessage, type UnumStore, type ValidationError, type ValidationResult, attachAllIntegrations, attachTauriToEngine, attachToEngine, attachUnumToEngine, canvasToMermaid, canvasToSchema, canvasToYaml, createCanvasEditor, createReactiveEngine as createFrameworkAgnosticReactiveEngine, createInMemoryDB, createIntrospector, createMockTauriBridge, createPluresDB, createPluresDBAdapter, createPluresDBGenerator, createPraxisDBStore, createPraxisLocalFirst, createSchema, createSchemaRegistry, createSchemaTemplate, createStateDocsGenerator, createTauriPraxisAdapter, createTimerActor, createUnifiedApp, createUnumAdapter, defineConstraint, defineEvent, defineFact, defineModule, defineRule, filterEvents, filterFacts, findEvent, findFact, generateDocs, generateId, generateTauriConfig, getEventPath, getFactPath, getSchemaPath, loadSchemaFromJson, loadSchemaFromYaml, registerSchema, schemaToCanvas, validateForGeneration, validateSchema, validateWithGuardian };
+/**
+ * Praxis UI Rules
+ *
+ * Lightweight, predefined UI-specific rules and constraints.
+ * These govern UI behavior without muddying business logic rules.
+ *
+ * UI rules are separated from domain rules by convention:
+ * - Domain rules: business decisions, data invariants, workflow logic
+ * - UI rules: visibility, loading states, error display, navigation guards
+ *
+ * Ship predefined rules that apps can opt into. Every `if` in the UI
+ * can be governed by Praxis — business rules stay clean, UI rules stay separate.
+ */
+
+/**
+ * Standard UI state fields that UI rules can read from context.
+ * Apps extend their context with these fields to enable UI rules.
+ */
+interface UIContext {
+    /** Whether the app is currently loading data */
+    loading?: boolean;
+    /** Current error message, if any */
+    error?: string | null;
+    /** Whether the app is in offline mode */
+    offline?: boolean;
+    /** Whether there are unsaved changes */
+    dirty?: boolean;
+    /** Current route/view name */
+    route?: string;
+    /** Whether the app has completed initialization */
+    initialized?: boolean;
+    /** Screen width category: 'mobile' | 'tablet' | 'desktop' */
+    viewport?: 'mobile' | 'tablet' | 'desktop';
+    /** Whether a modal/dialog is currently open */
+    modalOpen?: boolean;
+    /** Active panel/tab name */
+    activePanel?: string | null;
+}
+/**
+ * Loading gate: emits ui.loading-gate when data is loading.
+ * UI components can subscribe to this fact to show loading indicators.
+ */
+declare const loadingGateRule: RuleDescriptor<UIContext>;
+/**
+ * Error display: emits ui.error-display with the error message.
+ * Retracts when error clears.
+ */
+declare const errorDisplayRule: RuleDescriptor<UIContext>;
+/**
+ * Offline indicator: emits ui.offline-indicator when the app detects offline state.
+ */
+declare const offlineIndicatorRule: RuleDescriptor<UIContext>;
+/**
+ * Dirty guard: emits ui.unsaved-warning when there are unsaved changes.
+ * Can be used to block navigation or show save prompts.
+ */
+declare const dirtyGuardRule: RuleDescriptor<UIContext>;
+/**
+ * Init gate: blocks UI interactions until app is initialized.
+ */
+declare const initGateRule: RuleDescriptor<UIContext>;
+/**
+ * Viewport-responsive: emits ui.viewport-class based on screen size.
+ */
+declare const viewportRule: RuleDescriptor<UIContext>;
+/**
+ * No interaction while loading: constraint that fails if actions are taken during loading.
+ */
+declare const noInteractionWhileLoadingConstraint: ConstraintDescriptor<UIContext>;
+/**
+ * Must be initialized: constraint that fails if app hasn't completed init.
+ */
+declare const mustBeInitializedConstraint: ConstraintDescriptor<UIContext>;
+/**
+ * The complete UI rules module.
+ * Register this to get all predefined UI rules and constraints.
+ *
+ * @example
+ * import { uiModule } from '@plures/praxis';
+ * registry.registerModule(uiModule);
+ */
+declare const uiModule: PraxisModule<UIContext>;
+/**
+ * Create a customized UI module with only the rules you need.
+ *
+ * @example
+ * const myUI = createUIModule({
+ *   rules: ['ui/loading-gate', 'ui/dirty-guard'],
+ *   constraints: ['ui/must-be-initialized'],
+ * });
+ * registry.registerModule(myUI);
+ */
+declare function createUIModule<TContext extends UIContext>(options: {
+    rules?: string[];
+    constraints?: string[];
+    extraRules?: RuleDescriptor<TContext>[];
+    extraConstraints?: ConstraintDescriptor<TContext>[];
+}): PraxisModule<TContext>;
+/**
+ * Create a UI state change event. Fire this when UIContext fields change.
+ */
+declare function uiStateChanged(changes?: Record<string, unknown>): PraxisEvent;
+/**
+ * Create a navigation request event. Used with dirty guard.
+ */
+declare function navigationRequest(to: string): PraxisEvent;
+/**
+ * Create a resize event. Used with viewport rule.
+ */
+declare function resizeEvent(width: number, height: number): PraxisEvent;
+
+/**
+ * @plures/praxis — Completeness Analysis
+ *
+ * This module provides tools to measure and enforce "Praxis Completeness" —
+ * the degree to which an application's logic is expressed through Praxis
+ * rules, constraints, and contracts rather than scattered conditionals.
+ *
+ * ## Definition: Praxis Logic Completeness
+ *
+ * An application is "Praxis Complete" when:
+ *
+ * 1. **DOMAIN RULES (100%)** — Every business decision that produces user-visible
+ *    behavior change is expressed as a Praxis rule. "If the sprint is behind pace,
+ *    show a warning" is domain logic. It belongs in Praxis.
+ *
+ * 2. **INVARIANTS (100%)** — Every data validity assertion is a Praxis constraint.
+ *    "Sprint hours must not exceed 80" is an invariant. It belongs in Praxis.
+ *
+ * 3. **CONTRACTS (>80%)** — Rules that encode non-obvious behavior have contracts
+ *    (behavior description + examples + invariants). Contracts are documentation
+ *    AND test vectors — they prove the tool isn't the bug.
+ *
+ * 4. **CONTEXT COVERAGE (100%)** — Every piece of application state that rules
+ *    reason about is in the Praxis context. If a rule needs to know about
+ *    connection status, connection status must be in the context.
+ *
+ * 5. **EVENT COVERAGE (100%)** — Every state transition that should trigger rule
+ *    evaluation fires a Praxis event. If notes can be saved, there's a note.save
+ *    event. If sprint refreshes, there's a sprint.refresh event.
+ *
+ * ## What Is NOT Praxis Logic
+ *
+ * - **UI mechanics**: Panel toggle, scroll position, animation state, focus management
+ * - **Data transport**: fetch() calls, WebSocket plumbing, file I/O
+ * - **Framework wiring**: Svelte subscriptions, onMount, store creation
+ * - **Data transformation**: Parsing, formatting, serialization
+ * - **Routing/navigation**: URL handling, panel switching (unless it has business rules)
+ *
+ * The line: "Does this `if` statement encode a business decision or an app invariant?"
+ * If yes → Praxis rule/constraint. If no → leave it.
+ *
+ * ## Measuring Completeness
+ *
+ * ### Quantitative Metrics
+ * - **Rule Coverage**: (domain `if` branches in Praxis) / (total domain `if` branches)
+ * - **Constraint Coverage**: (data invariants in Praxis) / (total data invariants)
+ * - **Contract Coverage**: (rules with contracts) / (rules that need contracts)
+ * - **Context Coverage**: (state fields wired to context) / (state fields rules need)
+ * - **Event Coverage**: (state transitions with events) / (state transitions that matter)
+ *
+ * ### Qualitative Indicators
+ * - Can you change a business rule by editing ONE rule definition? (single source of truth)
+ * - Can you test a business rule without rendering UI? (Praxis engine is headless)
+ * - Can you explain every business rule to a PM by reading the registry? (self-documenting)
+ * - Does the PraxisPanel show all active concerns? (observable)
+ *
+ * ## The Completeness Score
+ *
+ * ```
+ * Score = (
+ *   rulesCovered / totalDomainBranches * 40 +     // Rules are king (40%)
+ *   constraintsCovered / totalInvariants * 20 +    // Invariants matter (20%)
+ *   contractsCovered / rulesNeedingContracts * 15 + // Contracts prevent bugs (15%)
+ *   contextFieldsCovered / totalNeeded * 15 +       // Context = visibility (15%)
+ *   eventsCovered / totalTransitions * 10            // Events = reactivity (10%)
+ * )
+ * ```
+ *
+ * 90+ = Complete | 70-89 = Good | 50-69 = Partial | <50 = Incomplete
+ */
+interface LogicBranch {
+    /** Source file + line */
+    location: string;
+    /** The condition expression */
+    condition: string;
+    /** Classification */
+    kind: 'domain' | 'invariant' | 'ui' | 'transport' | 'wiring' | 'transform';
+    /** If domain/invariant: the Praxis rule/constraint that covers it, or null */
+    coveredBy: string | null;
+    /** Human note */
+    note?: string;
+}
+interface StateField {
+    /** Store or source name */
+    source: string;
+    /** Field path */
+    field: string;
+    /** Whether it's in the Praxis context */
+    inContext: boolean;
+    /** Whether any rule references it */
+    usedByRule: boolean;
+}
+interface StateTransition {
+    /** What changes */
+    description: string;
+    /** The Praxis event tag, or null if missing */
+    eventTag: string | null;
+    /** Source location */
+    location: string;
+}
+interface CompletenessReport {
+    /** Overall score (0-100) */
+    score: number;
+    /** Rating */
+    rating: 'complete' | 'good' | 'partial' | 'incomplete';
+    rules: {
+        total: number;
+        covered: number;
+        uncovered: LogicBranch[];
+    };
+    constraints: {
+        total: number;
+        covered: number;
+        uncovered: LogicBranch[];
+    };
+    contracts: {
+        total: number;
+        withContracts: number;
+        missing: string[];
+    };
+    context: {
+        total: number;
+        covered: number;
+        missing: StateField[];
+    };
+    events: {
+        total: number;
+        covered: number;
+        missing: StateTransition[];
+    };
+}
+interface CompletenessConfig {
+    /** Minimum score to pass (default: 90) */
+    threshold?: number;
+    /** Whether to throw on failure (for CI) */
+    strict?: boolean;
+}
+/**
+ * Run a completeness audit against a Praxis registry and app manifest.
+ *
+ * The manifest is a developer-authored declaration of all logic branches,
+ * state fields, and state transitions in the app. The auditor checks which
+ * ones are covered by Praxis.
+ */
+declare function auditCompleteness(manifest: {
+    branches: LogicBranch[];
+    stateFields: StateField[];
+    transitions: StateTransition[];
+    rulesNeedingContracts: string[];
+}, registryRuleIds: string[], registryConstraintIds: string[], rulesWithContracts: string[], config?: CompletenessConfig): CompletenessReport;
+/**
+ * Format a completeness report as human-readable text.
+ */
+declare function formatReport(report: CompletenessReport): string;
+
+export { type ActivityState, type Actor, ActorManager, type CanvasDocument, type CanvasEdge, type CanvasEdgeStyle, type CanvasEditorConfig, type CanvasNode, type CanvasNodeStyle, type CompletenessConfig, type CompletenessReport, type ComponentDefinition, ConstraintDescriptor, ConstraintFn, type ConstraintNode, type ConstraintSchema, type DefineConstraintOptions, type DefineModuleOptions, type DefineRuleOptions, type EventDefinition$1 as EventDefinition, type EventStreamEntry, type FactDefinition$1 as FactDefinition, ReactiveLogicEngine as FrameworkAgnosticReactiveEngine, type ReactiveEngineOptions as FrameworkAgnosticReactiveEngineOptions, type GeneratedDoc, type GeneratedPluresDBFile, type GraphEdge, type GuardianError, type GuardianResult, type GuardianWarning, InMemoryPraxisDB, type LifecycleState, type LoaderOptions, type LoaderResult, type LogicBranch, type LogicDefinition, LogicEngine, type ModelDefinition, type NodeBindings, type NodeDefinition, type OrchestrationDefinition, PRAXIS_PATHS, type PluresDBAdapter, type PluresDBAdapterConfig, type PluresDBAdapterOptions, PluresDBGenerator, type PluresDBGeneratorOptions, type PluresDBInstance, PluresDBPraxisAdapter, type PraxisDB, PraxisDBStore, type PraxisDBStoreOptions, PraxisEvent, PraxisFact, type PraxisLocalFirstOptions, PraxisModule, PraxisRegistry, type PraxisSchema, PraxisSchemaRegistry, PraxisState, type RegistryGraph, RegistryIntrospector, type RegistrySchema, type RegistryStats, RuleDescriptor, RuleFn, type RuleNode, type RuleSchema, type StateChangeCallback, type StateDoc, type StateDocsConfig, StateDocsGenerator, type StateField, type StateMachineDoc, type StateTransition, type StoredSchema, type TauriAppConfig, type TauriBridge, type TauriCommand, type TauriEvent, type TauriFS, type TauriFileEntry, type TauriMenuItem, type TauriNotification, type TauriNotificationOptions, type TauriPlugin, type TauriPraxisAdapter, type TauriSecurityConfig, type TauriTray, type TauriUpdateConfig, type TauriUpdateInfo, type TauriWindowConfig, type TerminalNodeProps, type TransitionDoc, type UIContext, type UnifiedApp, type UnifiedAppConfig, type UnsubscribeFn, type UnumAdapter, type UnumAdapterConfig, type UnumChannel, type UnumIdentity, type UnumMessage, type UnumStore, type ValidationError, type ValidationResult, attachAllIntegrations, attachTauriToEngine, attachToEngine, attachUnumToEngine, auditCompleteness, canvasToMermaid, canvasToSchema, canvasToYaml, createCanvasEditor, createReactiveEngine as createFrameworkAgnosticReactiveEngine, createInMemoryDB, createIntrospector, createMockTauriBridge, createPluresDB, createPluresDBAdapter, createPluresDBGenerator, createPraxisDBStore, createPraxisLocalFirst, createSchema, createSchemaRegistry, createSchemaTemplate, createStateDocsGenerator, createTauriPraxisAdapter, createTimerActor, createUIModule, createUnifiedApp, createUnumAdapter, defineConstraint, defineEvent, defineFact, defineModule, defineRule, dirtyGuardRule, errorDisplayRule, filterEvents, filterFacts, findEvent, findFact, formatReport, generateDocs, generateId, generateTauriConfig, getEventPath, getFactPath, getSchemaPath, initGateRule, loadSchemaFromJson, loadSchemaFromYaml, loadingGateRule, mustBeInitializedConstraint, navigationRequest, noInteractionWhileLoadingConstraint, offlineIndicatorRule, registerSchema, resizeEvent, schemaToCanvas, uiModule, uiStateChanged, validateForGeneration, validateSchema, validateWithGuardian, viewportRule };