@plures/praxis 1.4.4 → 2.0.0

package/src/unified/types.ts

@@ -0,0 +1,148 @@
+/**
+ * Praxis Unified Reactive Layer — Types
+ *
+ * The types that define the unified state/rules/logging surface.
+ * Developers interact with query() and mutate() — everything else is internal.
+ */
+
+import type { PraxisFact, PraxisDiagnostics } from '../core/protocol.js';
+
+// ── Store Contract ──────────────────────────────────────────────────────────
+// Any reactive store that supports subscribe(). Works with Svelte writable,
+// Solid signals, or any framework with a subscribe pattern.
+
+/** Minimal store contract — anything with subscribe() */
+export interface Subscribable<T> {
+  subscribe(cb: (value: T) => void): (() => void) | { unsubscribe(): void };
+}
+
+/** Writable store contract — subscribe + set + update */
+export interface WritableStore<T> extends Subscribable<T> {
+  set(value: T): void;
+  update(updater: (current: T) => T): void;
+}
+
+// ── Graph Schema ────────────────────────────────────────────────────────────
+
+/** Schema definition for a graph path */
+export 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);
+ */
+export function definePath<T>(
+  path: string,
+  initial: T,
+  opts?: Omit<PathSchema<T>, 'path' | 'initial'>
+): PathSchema<T> {
+  return { path, initial, ...opts };
+}
+
+// ── Query Options ───────────────────────────────────────────────────────────
+
+export 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;
+}
+
+// ── Reactive Query Result ───────────────────────────────────────────────────
+
+/**
+ * A reactive reference returned by query().
+ * Has a Svelte-compatible subscribe() and a .current getter.
+ */
+export 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;
+}
+
+// ── Mutation Result ─────────────────────────────────────────────────────────
+
+export 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[];
+}
+
+// ── Rule Definition (v2) ────────────────────────────────────────────────────
+
+export 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[]) => import('../core/rule-result.js').RuleResult;
+}
+
+// ── Constraint Definition (v2) ──────────────────────────────────────────────
+
+export 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;
+}
+
+// ── Liveness Monitor ────────────────────────────────────────────────────────
+
+export 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;
+}
+
+// ── App Definition ──────────────────────────────────────────────────────────
+
+export 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;
+  };
+}

package/dist/node/{chunk-ZO2LU4G4.js → chunk-WFRHXZBP.js}

@@ -1,9 +1,9 @@
-import {
-  createPraxisEngine
-} from "./chunk-JZDJU2DO.js";
 import {
   PraxisRegistry
 } from "./chunk-TEMFJOIH.js";
+import {
+  createPraxisEngine
+} from "./chunk-JZDJU2DO.js";
 
 // src/core/reactive-engine.svelte.ts
 import * as $ from "svelte/internal/client";

package/dist/node/{validate-5PSWJTIC.js → validate-BY7JNY7H.js}

@@ -9,10 +9,10 @@ import {
   writeLogicLedgerEntry
 } from "./chunk-7CSWBDFL.js";
 import "./chunk-PGVSB6NR.js";
-import "./chunk-IG5BJ2MT.js";
 import {
   PraxisRegistry
 } from "./chunk-TEMFJOIH.js";
+import "./chunk-IG5BJ2MT.js";
 import "./chunk-QGM4M3NI.js";
 
 // src/cli/commands/validate.ts