@plures/praxis 1.2.13 → 1.3.0

package/README.md

@@ -318,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/)
 
@@ -458,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
@@ -1116,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)

package/dist/browser/chunk-MJK3IYTJ.js

@@ -0,0 +1,384 @@
+// src/core/protocol.ts
+var PRAXIS_PROTOCOL_VERSION = "1.0.0";
+
+// src/core/rule-result.ts
+var RuleResult = class _RuleResult {
+  /** The kind of result */
+  kind;
+  /** Facts produced (only for 'emit') */
+  facts;
+  /** Fact tags to retract (only for 'retract') */
+  retractTags;
+  /** Optional reason (for noop/skip/retract — useful for debugging) */
+  reason;
+  /** The rule ID that produced this result (set by engine) */
+  ruleId;
+  constructor(kind, facts, retractTags, reason) {
+    this.kind = kind;
+    this.facts = facts;
+    this.retractTags = retractTags;
+    this.reason = reason;
+  }
+  /**
+   * Rule produced facts.
+   *
+   * @example
+   * return RuleResult.emit([
+   *   { tag: 'sprint.behind', payload: { deficit: 5 } }
+   * ]);
+   */
+  static emit(facts) {
+    if (facts.length === 0) {
+      throw new Error(
+        "RuleResult.emit() requires at least one fact. Use RuleResult.noop() or RuleResult.skip() when a rule has nothing to say."
+      );
+    }
+    return new _RuleResult("emit", facts, []);
+  }
+  /**
+   * Rule evaluated but had nothing to report.
+   * Unlike returning [], this is explicit and traceable.
+   *
+   * @example
+   * if (ctx.completedHours >= expectedHours) {
+   *   return RuleResult.noop('Sprint is on pace');
+   * }
+   */
+  static noop(reason) {
+    return new _RuleResult("noop", [], [], reason);
+  }
+  /**
+   * Rule decided to skip because preconditions were not met.
+   * Distinct from noop: skip means "I can't evaluate", noop means "I evaluated and found nothing".
+   *
+   * @example
+   * if (!ctx.sprintName) {
+   *   return RuleResult.skip('No active sprint');
+   * }
+   */
+  static skip(reason) {
+    return new _RuleResult("skip", [], [], reason);
+  }
+  /**
+   * Rule retracts previously emitted facts by tag.
+   * Used when a condition that previously produced facts is no longer true.
+   *
+   * @example
+   * // Sprint was behind, but caught up
+   * if (ctx.completedHours >= expectedHours) {
+   *   return RuleResult.retract(['sprint.behind'], 'Sprint caught up');
+   * }
+   */
+  static retract(tags, reason) {
+    if (tags.length === 0) {
+      throw new Error("RuleResult.retract() requires at least one tag.");
+    }
+    return new _RuleResult("retract", [], tags, reason);
+  }
+  /** Whether this result produced facts */
+  get hasFacts() {
+    return this.facts.length > 0;
+  }
+  /** Whether this result retracts facts */
+  get hasRetractions() {
+    return this.retractTags.length > 0;
+  }
+};
+
+// src/core/engine.ts
+function safeClone(value) {
+  if (value === null || typeof value !== "object") {
+    return value;
+  }
+  if (typeof globalThis.structuredClone === "function") {
+    try {
+      return globalThis.structuredClone(value);
+    } catch {
+    }
+  }
+  if (Array.isArray(value)) {
+    return [...value];
+  }
+  return { ...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 ?? [],
+      meta: options.initialMeta ?? {},
+      protocolVersion: PRAXIS_PROTOCOL_VERSION
+    };
+  }
+  /**
+   * Get the current state (immutable copy)
+   */
+  getState() {
+    return {
+      context: safeClone(this.state.context),
+      facts: [...this.state.facts],
+      meta: this.state.meta ? safeClone(this.state.meta) : void 0,
+      protocolVersion: this.state.protocolVersion
+    };
+  }
+  /**
+   * Get the current context
+   */
+  getContext() {
+    return safeClone(this.state.context);
+  }
+  /**
+   * Get current facts
+   */
+  getFacts() {
+    return [...this.state.facts];
+  }
+  /**
+   * Process events through the engine.
+   * Applies all registered rules and checks all registered constraints.
+   *
+   * @param events Events to process
+   * @returns Result with new state and diagnostics
+   */
+  step(events) {
+    const config = {
+      ruleIds: this.registry.getRuleIds(),
+      constraintIds: this.registry.getConstraintIds()
+    };
+    return this.stepWithConfig(events, config);
+  }
+  /**
+   * Process events with specific rule and constraint configuration.
+   *
+   * @param events Events to process
+   * @param config Step configuration
+   * @returns Result with new state and diagnostics
+   */
+  stepWithConfig(events, config) {
+    const diagnostics = [];
+    let newState = { ...this.state };
+    const stateWithEvents = {
+      ...newState,
+      events
+      // current batch — rules can read state.events
+    };
+    const newFacts = [];
+    const retractions = [];
+    const eventTags = new Set(events.map((e) => e.tag));
+    for (const ruleId of config.ruleIds) {
+      const rule = this.registry.getRule(ruleId);
+      if (!rule) {
+        diagnostics.push({
+          kind: "rule-error",
+          message: `Rule "${ruleId}" not found in registry`,
+          data: { ruleId }
+        });
+        continue;
+      }
+      if (rule.eventTypes) {
+        const filterTags = Array.isArray(rule.eventTypes) ? rule.eventTypes : [rule.eventTypes];
+        if (!filterTags.some((t) => eventTags.has(t))) {
+          continue;
+        }
+      }
+      try {
+        const rawResult = rule.impl(stateWithEvents, events);
+        if (rawResult instanceof RuleResult) {
+          rawResult.ruleId = ruleId;
+          switch (rawResult.kind) {
+            case "emit":
+              newFacts.push(...rawResult.facts);
+              break;
+            case "retract":
+              retractions.push(...rawResult.retractTags);
+              break;
+            case "noop":
+            case "skip":
+              if (rawResult.reason) {
+                diagnostics.push({
+                  kind: "rule-error",
+                  // reused kind — could add 'rule-trace' in protocol v2
+                  message: `[${rawResult.kind}] ${ruleId}: ${rawResult.reason}`,
+                  data: { ruleId, resultKind: rawResult.kind, reason: rawResult.reason }
+                });
+              }
+              break;
+          }
+        } else if (Array.isArray(rawResult)) {
+          newFacts.push(...rawResult);
+        }
+      } catch (error) {
+        diagnostics.push({
+          kind: "rule-error",
+          message: `Error executing rule "${ruleId}": ${error instanceof Error ? error.message : String(error)}`,
+          data: { ruleId, error }
+        });
+      }
+    }
+    let existingFacts = newState.facts;
+    if (retractions.length > 0) {
+      const retractSet = new Set(retractions);
+      existingFacts = existingFacts.filter((f) => !retractSet.has(f.tag));
+    }
+    let mergedFacts;
+    switch (this.factDedup) {
+      case "last-write-wins": {
+        const factMap = /* @__PURE__ */ new Map();
+        for (const f of existingFacts) factMap.set(f.tag, f);
+        for (const f of newFacts) factMap.set(f.tag, f);
+        mergedFacts = Array.from(factMap.values());
+        break;
+      }
+      case "append":
+        mergedFacts = [...existingFacts, ...newFacts];
+        break;
+      case "none":
+      default:
+        mergedFacts = [...existingFacts, ...newFacts];
+        break;
+    }
+    if (this.maxFacts > 0 && mergedFacts.length > this.maxFacts) {
+      mergedFacts = mergedFacts.slice(mergedFacts.length - this.maxFacts);
+    }
+    newState = {
+      ...newState,
+      facts: mergedFacts
+    };
+    for (const constraintId of config.constraintIds) {
+      const constraint = this.registry.getConstraint(constraintId);
+      if (!constraint) {
+        diagnostics.push({
+          kind: "constraint-violation",
+          message: `Constraint "${constraintId}" not found in registry`,
+          data: { constraintId }
+        });
+        continue;
+      }
+      try {
+        const result = constraint.impl(newState);
+        if (result === false) {
+          diagnostics.push({
+            kind: "constraint-violation",
+            message: `Constraint "${constraintId}" violated`,
+            data: { constraintId, description: constraint.description }
+          });
+        } else if (typeof result === "string") {
+          diagnostics.push({
+            kind: "constraint-violation",
+            message: result,
+            data: { constraintId, description: constraint.description }
+          });
+        }
+      } catch (error) {
+        diagnostics.push({
+          kind: "constraint-violation",
+          message: `Error checking constraint "${constraintId}": ${error instanceof Error ? error.message : String(error)}`,
+          data: { constraintId, error }
+        });
+      }
+    }
+    this.state = newState;
+    return {
+      state: newState,
+      diagnostics
+    };
+  }
+  /**
+   * Update the context directly (for exceptional cases).
+   * Generally, context should be updated through rules.
+   *
+   * @param updater Function that produces new context from old context
+   */
+  updateContext(updater) {
+    this.state = {
+      ...this.state,
+      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.
+   *
+   * @param facts Facts to add
+   */
+  addFacts(facts) {
+    this.state = {
+      ...this.state,
+      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
+   */
+  clearFacts() {
+    this.state = {
+      ...this.state,
+      facts: []
+    };
+  }
+  /**
+   * Reset the engine to initial state
+   */
+  reset(options) {
+    this.state = {
+      context: options.initialContext,
+      facts: options.initialFacts ?? [],
+      meta: options.initialMeta ?? {},
+      protocolVersion: PRAXIS_PROTOCOL_VERSION
+    };
+  }
+};
+function createPraxisEngine(options) {
+  return new LogicEngine(options);
+}
+
+export {
+  PRAXIS_PROTOCOL_VERSION,
+  LogicEngine,
+  createPraxisEngine
+};

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

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

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

@@ -1,7 +1,7 @@
 import {
   LogicEngine,
   createPraxisEngine
-} from "./chunk-VOMLVI6V.js";
+} from "./chunk-MJK3IYTJ.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-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 { 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
      *