@plures/praxis 1.2.12 → 1.2.41

package/README.md

@@ -1,5 +1,11 @@
 # Praxis
 
+<!-- plures-readme-banner -->
+[![CI](https://github.com/plures/praxis/actions/workflows/ci.yml/badge.svg)](https://github.com/plures/praxis/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/%40plures%2Fpraxis.svg)](https://www.npmjs.com/package/@plures/praxis)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+
 **Typed, visual-first application logic for Svelte, Node, and the browser.**
 
 [![npm version](https://img.shields.io/npm/v/@plures/praxis.svg)](https://www.npmjs.com/package/@plures/praxis)
@@ -312,6 +318,8 @@ See [src/decision-ledger/README.md](./src/decision-ledger/README.md) for complet
 ## Documentation
 - [Getting Started](./GETTING_STARTED.md)
 - [Framework Guide](./FRAMEWORK.md)
+- [Praxis-Core API](./docs/core/praxis-core-api.md) - Stable API surface & guarantees
+- [Extending Praxis-Core](./docs/core/extending-praxis-core.md) - Extension guidelines
 - [Decision Ledger Guide](./src/decision-ledger/README.md)
 - [Examples](./examples/)
 
@@ -452,6 +460,44 @@ This protocol is:
 
 ## Framework Architecture
 
+Praxis is organized as a **monorepo** with clearly separated packages. See [MONOREPO.md](./MONOREPO.md) for the complete organization plan.
+
+### Target Monorepo Structure
+
+```
+praxis/
+├── packages/                       # Published npm packages
+│   ├── praxis-core/               # Core logic library (zero dependencies)
+│   │   └── src/
+│   │       ├── logic/             # Facts, events, rules, constraints, engine
+│   │       ├── schema/            # Schema definitions and validation
+│   │       ├── decision-ledger/   # Contracts and behavior specifications
+│   │       └── protocol/          # Core protocol types
+│   ├── praxis-cli/                # Command-line interface
+│   │   └── src/
+│   │       ├── commands/          # CLI commands
+│   │       └── generators/        # Code generators
+│   ├── praxis-svelte/             # Svelte 5 integration
+│   │   └── src/
+│   │       ├── components/        # Reactive Svelte components
+│   │       ├── generators/        # Component generators
+│   │       └── runtime/           # Svelte runtime integration
+│   ├── praxis-cloud/              # Cloud sync and relay
+│   │   └── src/
+│   │       ├── relay/             # Cloud relay server
+│   │       └── sync/              # Sync protocol
+│   └── praxis/                    # Main package (re-exports all)
+├── apps/                          # Example applications
+├── tools/                         # Development tools
+├── ui/                            # UI components and tools
+├── docs/                          # Documentation
+└── examples/                      # Simple examples and demos
+```
+
+### Current Structure (In Transition)
+
+The existing code is currently located in:
+
 ```
 /praxis
 ├── core/                          # Core framework
@@ -1110,6 +1156,10 @@ MIT License - see [LICENSE](./LICENSE) for details.
 
 Contributions are welcome! Please read our [Contributing Guide](./CONTRIBUTING.md) to get started.
 
+**Automated Updates**: This repository uses batched bot updates to reduce commit churn. Dependency updates are grouped weekly and include audit trails. See the [Bot Update Policy](./docs/BOT_UPDATE_POLICY.md) for details.
+
+**Dogfooding Plures Tools**: We actively dogfood all Plures tools during development. If you encounter friction while using any tool, please file a [Dogfooding Friction Report](https://github.com/plures/praxis/issues/new/choose). See the [Dogfooding Quick Start](./docs/DOGFOODING_QUICK_START.md) for details.
+
 - 🐛 [Report a bug](https://github.com/plures/praxis/issues/new?template=bug_report.yml)
 - 💡 [Request a feature](https://github.com/plures/praxis/issues/new?template=enhancement.yml)
 - 📖 [Improve documentation](https://github.com/plures/praxis/issues/new?template=bug_report.yml)
@@ -1131,3 +1181,16 @@ Please review our [Code of Conduct](./CODE_OF_CONDUCT.md) before participating.
 ---
 
 Built with ❤️ by the plures team
+
+---
+
+<!-- plures-readme-standard-sections -->
+## Overview
+
+## Install
+
+## Development
+
+## Contributing
+
+## License

package/dist/browser/{chunk-VOMLVI6V.js → chunk-BBP2F7TT.js}

@@ -20,8 +20,12 @@ function safeClone(value) {
 var LogicEngine = class {
   state;
   registry;
+  factDedup;
+  maxFacts;
   constructor(options) {
     this.registry = options.registry;
+    this.factDedup = options.factDedup ?? "last-write-wins";
+    this.maxFacts = options.maxFacts ?? 1e3;
     this.state = {
       context: options.initialContext,
       facts: options.initialFacts ?? [],
@@ -77,6 +81,7 @@ var LogicEngine = class {
     const diagnostics = [];
     let newState = { ...this.state };
     const newFacts = [];
+    const eventTags = new Set(events.map((e) => e.tag));
     for (const ruleId of config.ruleIds) {
       const rule = this.registry.getRule(ruleId);
       if (!rule) {
@@ -87,6 +92,12 @@ var LogicEngine = class {
         });
         continue;
       }
+      if (rule.eventTypes) {
+        const filterTags = Array.isArray(rule.eventTypes) ? rule.eventTypes : [rule.eventTypes];
+        if (!filterTags.some((t) => eventTags.has(t))) {
+          continue;
+        }
+      }
       try {
         const ruleFacts = rule.impl(newState, events);
         newFacts.push(...ruleFacts);
@@ -98,9 +109,29 @@ var LogicEngine = class {
         });
       }
     }
+    let mergedFacts;
+    switch (this.factDedup) {
+      case "last-write-wins": {
+        const factMap = /* @__PURE__ */ new Map();
+        for (const f of newState.facts) factMap.set(f.tag, f);
+        for (const f of newFacts) factMap.set(f.tag, f);
+        mergedFacts = Array.from(factMap.values());
+        break;
+      }
+      case "append":
+        mergedFacts = [...newState.facts, ...newFacts];
+        break;
+      case "none":
+      default:
+        mergedFacts = [...newState.facts, ...newFacts];
+        break;
+    }
+    if (this.maxFacts > 0 && mergedFacts.length > this.maxFacts) {
+      mergedFacts = mergedFacts.slice(mergedFacts.length - this.maxFacts);
+    }
     newState = {
       ...newState,
-      facts: [...newState.facts, ...newFacts]
+      facts: mergedFacts
     };
     for (const constraintId of config.constraintIds) {
       const constraint = this.registry.getConstraint(constraintId);
@@ -153,6 +184,29 @@ var LogicEngine = class {
       context: updater(this.state.context)
     };
   }
+  /**
+   * Atomically update context AND process events in a single call.
+   *
+   * This avoids the fragile pattern of calling updateContext() then step()
+   * separately, where rules could see stale context if the ordering is wrong.
+   *
+   * @param updater Function that produces new context from old context
+   * @param events Events to process after context is updated
+   * @returns Result with new state and diagnostics
+   *
+   * @example
+   * engine.stepWithContext(
+   *   ctx => ({ ...ctx, sprintName: sprint.name, items: sprint.items }),
+   *   [{ tag: 'sprint.update', payload: { name: sprint.name } }]
+   * );
+   */
+  stepWithContext(updater, events) {
+    this.state = {
+      ...this.state,
+      context: updater(this.state.context)
+    };
+    return this.step(events);
+  }
   /**
    * Add facts directly (for exceptional cases).
    * Generally, facts should be added through rules.
@@ -165,6 +219,21 @@ var LogicEngine = class {
       facts: [...this.state.facts, ...facts]
     };
   }
+  /**
+   * Check all constraints without processing any events.
+   *
+   * Useful for validation-only scenarios (e.g., form validation,
+   * pre-save checks) where you want constraint diagnostics without
+   * triggering any rules.
+   *
+   * @returns Array of constraint violation diagnostics (empty = all passing)
+   */
+  checkConstraints() {
+    return this.stepWithConfig([], {
+      ruleIds: [],
+      constraintIds: this.registry.getConstraintIds()
+    }).diagnostics;
+  }
   /**
    * Clear all facts
    */

package/dist/browser/{chunk-K377RW4V.js → chunk-FCEH7WMH.js}

@@ -1,6 +1,6 @@
 import {
   createPraxisEngine
-} from "./chunk-VOMLVI6V.js";
+} from "./chunk-BBP2F7TT.js";
 
 // src/core/rules.ts
 var PraxisRegistry = class {

package/dist/browser/{engine-YJZV4SLD.js → engine-65QDGCAN.js}

@@ -1,7 +1,7 @@
 import {
   LogicEngine,
   createPraxisEngine
-} from "./chunk-VOMLVI6V.js";
+} from "./chunk-BBP2F7TT.js";
 export {
   LogicEngine,
   createPraxisEngine

package/dist/browser/index.d.ts

@@ -1,5 +1,5 @@
-import { L as LogicEngine, P as PraxisState, a as PraxisEvent, b as PraxisRegistry, R as RuleDescriptor, C as ConstraintDescriptor, c as PraxisFact, d as RuleFn, e as Contract, f as ConstraintFn, g as PraxisModule } from './reactive-engine.svelte-9aS0kTa8.js';
-export { n as ConstraintId, l as PRAXIS_PROTOCOL_VERSION, h as PraxisDiagnostics, o as PraxisEngineOptions, i as PraxisStepConfig, k as PraxisStepFn, j as PraxisStepResult, q as ReactiveEngineOptions, r as ReactiveLogicEngine, m as RuleId, p as createPraxisEngine, s as createReactiveEngine } from './reactive-engine.svelte-9aS0kTa8.js';
+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-Cqd8Mod2.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-Cqd8Mod2.js';
 import { LocalFirstOptions } from '@plures/pluresdb/local-first';
 
 /**
@@ -435,6 +435,11 @@ interface DefineRuleOptions<TContext = unknown> {
     id: string;
     description: string;
     impl: RuleFn<TContext>;
+    /**
+     * Optional event type filter — only evaluate this rule when at least one
+     * event in the batch has a matching `tag`. Accepts a single tag or array.
+     */
+    eventTypes?: string | string[];
     contract?: Contract;
     meta?: Record<string, unknown>;
 }
@@ -1103,6 +1108,86 @@ interface PraxisLocalFirstOptions extends LocalFirstOptions {
  */
 declare function createPraxisLocalFirst(options?: PraxisLocalFirstOptions): Promise<PluresDBPraxisAdapter>;
 
+/**
+ * Chronicle Types
+ *
+ * Core types for the Chronicle causal tracking system.
+ * Records state transitions as a causal graph stored in PluresDB.
+ */
+/**
+ * Direction for traversing causal chains.
+ */
+type TraceDirection = 'backward' | 'forward' | 'both';
+/**
+ * A recorded state transition event passed to Chronicle.
+ */
+interface ChronicleEvent {
+    /** Path to the changed value (fact or event stream path) */
+    path: string;
+    /** Value before the change (undefined for creates) */
+    before?: unknown;
+    /** Value after the change */
+    after?: unknown;
+    /** Parent span/node ID that caused this change */
+    cause?: string;
+    /** Session or request ID grouping related changes */
+    context?: string;
+    /** Additional metadata key-value pairs */
+    metadata: Record<string, string>;
+}
+/**
+ * A Chronicle node representing a single recorded state transition.
+ */
+interface ChronicleNode {
+    /** Unique node ID: `chronos:{timestamp}-{counter}` */
+    id: string;
+    /** Timestamp (ms since epoch) when this node was recorded */
+    timestamp: number;
+    /** The recorded state transition */
+    event: ChronicleEvent;
+}
+
+/**
+ * Chronicle Interface and PluresDbChronicle Implementation
+ *
+ * Records state transitions as a causal graph in PluresDB.
+ * Attached to PraxisDBStore via `.withChronicle()` for zero-effort observability.
+ */
+
+/**
+ * Chronicle interface — records state transitions as a causal graph.
+ *
+ * Automatically attached to any PraxisDBStore at runtime via `.withChronicle()`.
+ * Records state diffs as graph nodes with causal edges.
+ */
+interface Chronicle {
+    /**
+     * Record a state transition and return the created node.
+     */
+    record(event: ChronicleEvent): Promise<ChronicleNode>;
+    /**
+     * Trace causality backward or forward from a node.
+     *
+     * @param nodeId Starting node ID
+     * @param direction `'backward'` follows incoming edges, `'forward'` follows outgoing edges
+     * @param maxDepth Maximum traversal depth (prevents cycles / infinite loops)
+     */
+    trace(nodeId: string, direction: TraceDirection, maxDepth: number): Promise<ChronicleNode[]>;
+    /**
+     * Return all Chronicle nodes recorded within a timestamp range.
+     *
+     * @param start Inclusive start timestamp (ms)
+     * @param end Inclusive end timestamp (ms)
+     */
+    range(start: number, end: number): Promise<ChronicleNode[]>;
+    /**
+     * Return all Chronicle nodes belonging to a context (session/request).
+     *
+     * @param contextId The context identifier
+     */
+    subgraph(contextId: string): Promise<ChronicleNode[]>;
+}
+
 /**
  * PraxisDB Store
  *
@@ -1182,9 +1267,26 @@ declare class PraxisDBStore<TContext = unknown> {
     private subscriptions;
     private factWatchers;
     private onRuleError;
+    private chronicle?;
     constructor(options: PraxisDBStoreOptions<TContext> & {
         onRuleError?: RuleErrorHandler;
     });
+    /**
+     * Attach a Chronicle observer to this store.
+     *
+     * Every subsequent `storeFact` and `appendEvent` call will be recorded as a
+     * causal graph node in PluresDB, enabling full observability for free.
+     *
+     * @param chronicle Chronicle implementation to attach
+     * @returns `this` for fluent chaining
+     *
+     * @example
+     * ```typescript
+     * const store = createPraxisDBStore(db, registry)
+     *   .withChronicle(createChronicle(db));
+     * ```
+     */
+    withChronicle(chronicle: Chronicle): this;
     /**
      * Store a fact in PluresDB
      *

package/dist/browser/index.js

@@ -2,12 +2,12 @@ import {
   PraxisRegistry,
   ReactiveLogicEngine,
   createReactiveEngine
-} from "./chunk-K377RW4V.js";
+} from "./chunk-FCEH7WMH.js";
 import {
   LogicEngine,
   PRAXIS_PROTOCOL_VERSION,
   createPraxisEngine
-} from "./chunk-VOMLVI6V.js";
+} from "./chunk-BBP2F7TT.js";
 import {
   InMemoryPraxisDB,
   PluresDBPraxisAdapter,
@@ -586,6 +586,7 @@ function defineRule(options) {
     id: options.id,
     description: options.description,
     impl: options.impl,
+    eventTypes: options.eventTypes,
     contract,
     meta
   };
@@ -884,6 +885,53 @@ function validateForGeneration(schema) {
   };
 }
 
+// src/core/chronicle/context.ts
+var ChronicleContext = class {
+  static _stack = [];
+  /**
+   * Get the current active span, if any.
+   */
+  static get current() {
+    return this._stack[this._stack.length - 1];
+  }
+  /**
+   * Run a synchronous function within a causal span.
+   * The span is automatically popped when the function returns.
+   */
+  static run(span, fn) {
+    this._stack.push(span);
+    try {
+      return fn();
+    } finally {
+      this._stack.pop();
+    }
+  }
+  /**
+   * Run an async function within a causal span.
+   * The span is popped after the promise settles.
+   */
+  static async runAsync(span, fn) {
+    this._stack.push(span);
+    try {
+      return await fn();
+    } finally {
+      this._stack.pop();
+    }
+  }
+  /**
+   * Create a child span that inherits the current contextId.
+   *
+   * @param spanId ID for the new span
+   * @returns A new ChronicleSpan with the current contextId
+   */
+  static childSpan(spanId) {
+    return {
+      spanId,
+      contextId: this.current?.contextId
+    };
+  }
+};
+
 // src/core/pluresdb/store.ts
 var PRAXIS_PATHS = {
   /** Base path for all Praxis data */
@@ -919,12 +967,32 @@ var PraxisDBStore = class {
   subscriptions = [];
   factWatchers = /* @__PURE__ */ new Map();
   onRuleError;
+  chronicle;
   constructor(options) {
     this.db = options.db;
     this.registry = options.registry;
     this.context = options.initialContext ?? {};
     this.onRuleError = options.onRuleError ?? defaultErrorHandler;
   }
+  /**
+   * Attach a Chronicle observer to this store.
+   *
+   * Every subsequent `storeFact` and `appendEvent` call will be recorded as a
+   * causal graph node in PluresDB, enabling full observability for free.
+   *
+   * @param chronicle Chronicle implementation to attach
+   * @returns `this` for fluent chaining
+   *
+   * @example
+   * ```typescript
+   * const store = createPraxisDBStore(db, registry)
+   *   .withChronicle(createChronicle(db));
+   * ```
+   */
+  withChronicle(chronicle) {
+    this.chronicle = chronicle;
+    return this;
+  }
   /**
    * Store a fact in PluresDB
    *
@@ -939,7 +1007,31 @@ var PraxisDBStore = class {
     if (!constraintResult.valid) {
       throw new Error(`Constraint violation: ${constraintResult.errors.join(", ")}`);
     }
+    let before;
+    if (this.chronicle) {
+      const payload = fact.payload;
+      const id = payload?.id;
+      if (id) {
+        before = await this.getFact(fact.tag, id);
+      }
+    }
     await this.persistFact(fact);
+    if (this.chronicle) {
+      const payload = fact.payload;
+      const id = payload?.id ?? "";
+      const span = ChronicleContext.current;
+      try {
+        await this.chronicle.record({
+          path: getFactPath(fact.tag, id),
+          before,
+          after: fact,
+          cause: span?.spanId,
+          context: span?.contextId,
+          metadata: { factTag: fact.tag, operation: "storeFact" }
+        });
+      } catch {
+      }
+    }
     await this.triggerRules([fact]);
   }
   /**
@@ -953,7 +1045,31 @@ var PraxisDBStore = class {
       throw new Error(`Constraint violation: ${constraintResult.errors.join(", ")}`);
     }
     for (const fact of facts) {
+      let before;
+      if (this.chronicle) {
+        const payload = fact.payload;
+        const id = payload?.id;
+        if (id) {
+          before = await this.getFact(fact.tag, id);
+        }
+      }
       await this.persistFact(fact);
+      if (this.chronicle) {
+        const payload = fact.payload;
+        const id = payload?.id ?? "";
+        const span = ChronicleContext.current;
+        try {
+          await this.chronicle.record({
+            path: getFactPath(fact.tag, id),
+            before,
+            after: fact,
+            cause: span?.spanId,
+            context: span?.contextId,
+            metadata: { factTag: fact.tag, operation: "storeFacts" }
+          });
+        } catch {
+        }
+      }
     }
     await this.triggerRules(facts);
   }
@@ -995,7 +1111,29 @@ var PraxisDBStore = class {
     };
     const newEvents = [...existingEvents, entry];
     await this.db.set(path, newEvents);
-    await this.triggerRulesForEvents([event]);
+    let eventNodeId;
+    if (this.chronicle) {
+      const span = ChronicleContext.current;
+      try {
+        const node = await this.chronicle.record({
+          path,
+          before: existingEvents.length > 0 ? existingEvents[existingEvents.length - 1] : void 0,
+          after: entry,
+          cause: span?.spanId,
+          context: span?.contextId,
+          metadata: { eventTag: event.tag, sequence: String(entry.sequence), operation: "appendEvent" }
+        });
+        eventNodeId = node.id;
+      } catch {
+      }
+    }
+    const outerSpan = ChronicleContext.current;
+    const ruleSpan = eventNodeId ? { spanId: eventNodeId, contextId: outerSpan?.contextId } : outerSpan;
+    if (ruleSpan && this.chronicle) {
+      await ChronicleContext.runAsync(ruleSpan, () => this.triggerRulesForEvents([event]));
+    } else {
+      await this.triggerRulesForEvents([event]);
+    }
   }
   /**
    * Append multiple events to their respective streams
@@ -1008,6 +1146,7 @@ var PraxisDBStore = class {
       const existing = eventsByTag.get(event.tag) ?? [];
       eventsByTag.set(event.tag, [...existing, event]);
     }
+    let lastEventNodeId;
     for (const [tag, tagEvents] of eventsByTag) {
       const path = getEventPath(tag);
       const existingEvents = await this.db.get(path) ?? [];
@@ -1018,8 +1157,30 @@ var PraxisDBStore = class {
         sequence: sequence++
       }));
       await this.db.set(path, [...existingEvents, ...newEntries]);
+      if (this.chronicle) {
+        const span = ChronicleContext.current;
+        for (const entry of newEntries) {
+          try {
+            const node = await this.chronicle.record({
+              path,
+              after: entry,
+              cause: span?.spanId,
+              context: span?.contextId,
+              metadata: { eventTag: tag, sequence: String(entry.sequence), operation: "appendEvents" }
+            });
+            lastEventNodeId = node.id;
+          } catch {
+          }
+        }
+      }
+    }
+    const outerSpan = ChronicleContext.current;
+    const ruleSpan = lastEventNodeId ? { spanId: lastEventNodeId, contextId: outerSpan?.contextId } : outerSpan;
+    if (ruleSpan && this.chronicle) {
+      await ChronicleContext.runAsync(ruleSpan, () => this.triggerRulesForEvents(events));
+    } else {
+      await this.triggerRulesForEvents(events);
     }
-    await this.triggerRulesForEvents(events);
   }
   /**
    * Get events from a stream
@@ -1132,6 +1293,21 @@ var PraxisDBStore = class {
       if (constraintResult.valid) {
         for (const fact of derivedFacts) {
           await this.persistFact(fact);
+          if (this.chronicle) {
+            const payload = fact.payload;
+            const id = payload?.id ?? "";
+            const span = ChronicleContext.current;
+            try {
+              await this.chronicle.record({
+                path: getFactPath(fact.tag, id),
+                after: fact,
+                cause: span?.spanId,
+                context: span?.contextId,
+                metadata: { factTag: fact.tag, operation: "derivedFact" }
+              });
+            } catch {
+            }
+          }
         }
       }
     }
@@ -2713,7 +2889,7 @@ function generateTauriConfig(config) {
 
 // src/integrations/unified.ts
 async function createUnifiedApp(config) {
-  const { createPraxisEngine: createPraxisEngine2 } = await import("./engine-YJZV4SLD.js");
+  const { createPraxisEngine: createPraxisEngine2 } = await import("./engine-65QDGCAN.js");
   const { createInMemoryDB: createInMemoryDB2 } = await import("./adapter-CIMBGDC7.js");
   const db = config.db || createInMemoryDB2();
   const pluresdb = createPluresDBAdapter({

package/dist/browser/integrations/svelte.d.ts

@@ -1,5 +1,5 @@
-import { L as LogicEngine, P as PraxisState, a as PraxisEvent } from '../reactive-engine.svelte-9aS0kTa8.js';
-export { q as ReactiveEngineOptions, r as ReactiveLogicEngine, s as createReactiveEngine } from '../reactive-engine.svelte-9aS0kTa8.js';
+import { P as PraxisState, a as PraxisEvent, L as LogicEngine } from '../reactive-engine.svelte-Cqd8Mod2.js';
+export { o as ReactiveEngineOptions, p as ReactiveLogicEngine, s as createReactiveEngine } from '../reactive-engine.svelte-Cqd8Mod2.js';
 
 /**
  * Svelte v5 Integration

package/dist/browser/integrations/svelte.js

@@ -1,8 +1,8 @@
 import {
   ReactiveLogicEngine,
   createReactiveEngine
-} from "../chunk-K377RW4V.js";
-import "../chunk-VOMLVI6V.js";
+} from "../chunk-FCEH7WMH.js";
+import "../chunk-BBP2F7TT.js";
 
 // src/integrations/svelte.ts
 function createPraxisStore(engine) {