@plures/praxis 1.2.12 → 1.2.41

package/dist/node/index.d.ts

@@ -1,9 +1,9 @@
-import { P as PraxisState, a as PraxisEvent, b as PraxisFact } from './protocol-Qek7ebBl.js';
-export { g as PRAXIS_PROTOCOL_VERSION, e as PraxisDiagnostics, d as PraxisStepConfig, f as PraxisStepFn, c as PraxisStepResult } from './protocol-Qek7ebBl.js';
-import { L as LogicEngine, P as PraxisRegistry, b as RuleDescriptor, C as ConstraintDescriptor, d as RuleFn, e as Contract, f as ConstraintFn, g as PraxisModule, M as MissingArtifact, S as Severity, V as ValidationReport, A as Assumption } from './reactive-engine.svelte-CRNqHlbv.js';
-export { i as ConstraintId, p as ContractGap, D as DefineContractOptions, E as Example, j as PraxisEngineOptions, a as ReactiveEngineOptions, R as ReactiveLogicEngine, o as Reference, h as RuleId, k as createPraxisEngine, c as createReactiveEngine, l as defineContract, m as getContract, n as isContract } from './reactive-engine.svelte-CRNqHlbv.js';
-import { P as PraxisDB, U as UnsubscribeFn$1 } from './terminal-adapter-B-UK_Vdz.js';
-export { C as CommandExecutor, I as InMemoryPraxisDB, g as PluresDBAdapterConfig, f as PluresDBInstance, j as PluresDBPraxisAdapter, h as PraxisLocalFirstOptions, T as TerminalAdapter, d as TerminalAdapterOptions, a as TerminalExecutionResult, b as TerminalNodeState, i as createInMemoryDB, e as createMockExecutor, k as createPluresDB, l as createPraxisLocalFirst, c as createTerminalAdapter, r as runTerminalCommand } from './terminal-adapter-B-UK_Vdz.js';
+import { P as PraxisState, a as PraxisEvent, b as PraxisFact } from './protocol-BocKczNv.js';
+export { f as PRAXIS_PROTOCOL_VERSION, e as PraxisDiagnostics, d as PraxisStepConfig, g as PraxisStepFn, c as PraxisStepResult } from './protocol-BocKczNv.js';
+import { L as LogicEngine, P as PraxisRegistry, b as RuleDescriptor, C as ConstraintDescriptor, d as ConstraintFn, e as Contract, f as RuleFn, g as PraxisModule, M as MissingArtifact, S as Severity, V as ValidationReport, A as Assumption } from './reactive-engine.svelte-D-xTDxT5.js';
+export { h as ConstraintId, i as ContractGap, D as DefineContractOptions, E as Example, j as PraxisEngineOptions, R as ReactiveEngineOptions, a as ReactiveLogicEngine, k as Reference, l as RuleId, m as createPraxisEngine, c as createReactiveEngine, n as defineContract, o as getContract, p as isContract } from './reactive-engine.svelte-D-xTDxT5.js';
+import { P as PraxisDB, U as UnsubscribeFn$1 } from './terminal-adapter-CvIvgTo4.js';
+export { C as CommandExecutor, I as InMemoryPraxisDB, a as PluresDBAdapterConfig, b as PluresDBInstance, d as PluresDBPraxisAdapter, e as PraxisLocalFirstOptions, T as TerminalAdapter, f as TerminalAdapterOptions, g as TerminalExecutionResult, h as TerminalNodeState, i as createInMemoryDB, j as createMockExecutor, k as createPluresDB, l as createPraxisLocalFirst, c as createTerminalAdapter, r as runTerminalCommand } from './terminal-adapter-CvIvgTo4.js';
 import { PraxisSchema, ValidationResult, ModelDefinition, FieldDefinition, ComponentDefinition, LogicDefinition } from './schema.js';
 export { NodeBindings, NodeDefinition, OrchestrationDefinition, TerminalNodeProps, ValidationError, createSchemaTemplate, validateSchema } from './schema.js';
 import '@plures/pluresdb/local-first';
@@ -441,6 +441,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>;
 }
@@ -838,6 +843,154 @@ declare function loadSchema(filePath: string, options?: LoaderOptions): Promise<
  */
 declare function loadSchemaFromFile(filePath: string, options?: LoaderOptions): Promise<LoaderResult>;
 
+/**
+ * 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';
+/**
+ * Causal relationship type between Chronicle nodes.
+ * - `causes`: node A caused node B (explicit causal link)
+ * - `context`: node B belongs to the same session/request as node A
+ * - `follows`: node B happened after node A in the same context
+ */
+type EdgeType = 'causes' | 'context' | 'follows';
+/**
+ * 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;
+}
+/**
+ * A directed edge in the causal graph connecting two Chronicle nodes.
+ */
+interface ChronicleEdge {
+    /** Source node ID */
+    from: string;
+    /** Target node ID */
+    to: string;
+    /** Type of causal relationship */
+    type: EdgeType;
+}
+
+/**
+ * Chronicle Interface and PluresDbChronicle Implementation
+ *
+ * Records state transitions as a causal graph in PluresDB.
+ * Attached to PraxisDBStore via `.withChronicle()` for zero-effort observability.
+ */
+
+/**
+ * Storage path constants for Chronicle data in PluresDB.
+ *
+ * Layout:
+ * - `/_praxis/chronos/nodes/{nodeId}` — ChronicleNode documents
+ * - `/_praxis/chronos/edges/out/{nodeId}` — outgoing ChronicleEdge arrays
+ * - `/_praxis/chronos/edges/in/{nodeId}` — incoming ChronicleEdge arrays
+ * - `/_praxis/chronos/context/{contextId}` — ordered nodeId arrays per context
+ * - `/_praxis/chronos/index` — global ordered nodeId array (for range queries)
+ */
+declare const CHRONICLE_PATHS: {
+    readonly BASE: "/_praxis/chronos";
+    readonly NODES: "/_praxis/chronos/nodes";
+    readonly EDGES_OUT: "/_praxis/chronos/edges/out";
+    readonly EDGES_IN: "/_praxis/chronos/edges/in";
+    readonly CONTEXT: "/_praxis/chronos/context";
+    readonly INDEX: "/_praxis/chronos/index";
+};
+/**
+ * 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[]>;
+}
+/**
+ * PluresDB-backed implementation of the Chronicle interface.
+ *
+ * Stores causal graph nodes and edges in PluresDB under `/_praxis/chronos/`.
+ * Shares the same PluresDB instance as PraxisDBStore so the JS Chronos UI
+ * can read from the same data layer.
+ *
+ * @example
+ * ```typescript
+ * const db = createInMemoryDB();
+ * const chronicle = new PluresDbChronicle(db);
+ *
+ * const store = createPraxisDBStore(db, registry).withChronicle(chronicle);
+ * // All storeFact / appendEvent calls are now recorded automatically.
+ * ```
+ */
+declare class PluresDbChronicle implements Chronicle {
+    private readonly db;
+    constructor(db: PraxisDB);
+    record(event: ChronicleEvent): Promise<ChronicleNode>;
+    trace(nodeId: string, direction: TraceDirection, maxDepth: number): Promise<ChronicleNode[]>;
+    range(start: number, end: number): Promise<ChronicleNode[]>;
+    subgraph(contextId: string): Promise<ChronicleNode[]>;
+    private addEdge;
+    private _traceRecursive;
+}
+/**
+ * Create a PluresDB-backed Chronicle instance.
+ *
+ * @param db The PraxisDB instance to store causal graph data in
+ */
+declare function createChronicle(db: PraxisDB): PluresDbChronicle;
+
 /**
  * PraxisDB Store
  *
@@ -917,9 +1070,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
      *
@@ -1241,6 +1411,137 @@ declare class PluresDBGenerator {
  */
 declare function createPluresDBGenerator(outputDir: string, options?: Partial<PluresDBGeneratorOptions>): PluresDBGenerator;
 
+/**
+ * Chronicle Context
+ *
+ * Synchronous causal context propagation for Chronicle span tracking.
+ * Equivalent to Rust's `tracing` crate span context, adapted for TypeScript.
+ *
+ * @example
+ * ```typescript
+ * // Run code attributed to a specific span/session
+ * await ChronicleContext.runAsync(
+ *   { spanId: 'route-decision-1', contextId: 'session-abc' },
+ *   async () => {
+ *     await store.storeFact(fact); // attributed to route-decision-1 / session-abc
+ *   }
+ * );
+ * ```
+ */
+interface ChronicleSpan {
+    /** The span/operation ID (becomes the `cause` field on Chronicle nodes) */
+    spanId?: string;
+    /** Session or request ID grouping related spans */
+    contextId?: string;
+}
+/**
+ * Stack-based synchronous causal context propagation.
+ *
+ * Uses a call-stack approach for environments without AsyncLocalStorage.
+ * Works correctly for synchronous and sequentially-awaited async code.
+ * For concurrent async flows, use `runAsync` per logical operation.
+ */
+declare class ChronicleContext {
+    private static readonly _stack;
+    /**
+     * Get the current active span, if any.
+     */
+    static get current(): ChronicleSpan | undefined;
+    /**
+     * Run a synchronous function within a causal span.
+     * The span is automatically popped when the function returns.
+     */
+    static run<T>(span: ChronicleSpan, fn: () => T): T;
+    /**
+     * Run an async function within a causal span.
+     * The span is popped after the promise settles.
+     */
+    static runAsync<T>(span: ChronicleSpan, fn: () => Promise<T>): Promise<T>;
+    /**
+     * 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: string): ChronicleSpan;
+}
+
+/**
+ * Chronicle MCP Tools
+ *
+ * Exposes Chronicle query functionality as MCP-compatible tool handlers.
+ * Register these tools with any MCP server to surface Chronos querying
+ * capabilities for troubleshooting, auditing, and AI training data extraction.
+ *
+ * @example
+ * ```typescript
+ * const chronicle = createChronicle(db);
+ * const tools = createChronosMcpTools(chronicle);
+ *
+ * // MCP server registration (framework-agnostic)
+ * server.registerTool('chronos.trace', tools.trace);
+ * server.registerTool('chronos.search', tools.search);
+ * ```
+ */
+
+/**
+ * Parameters for the `chronos.trace` MCP tool.
+ */
+interface ChronosTraceParams {
+    /** ID of the Chronicle node to start tracing from */
+    nodeId: string;
+    /** Direction to traverse the causal graph (default: `'backward'`) */
+    direction?: TraceDirection;
+    /** Maximum traversal depth (default: 10) */
+    maxDepth?: number;
+}
+/**
+ * Parameters for the `chronos.search` MCP tool.
+ */
+interface ChronosSearchParams {
+    /** Search query matched against node paths, metadata, and serialised payloads */
+    query: string;
+    /** Optional context ID — restricts search to a single session/request subgraph */
+    contextId?: string;
+    /** Inclusive start timestamp in ms (default: 0) */
+    since?: number;
+    /** Inclusive end timestamp in ms (default: now) */
+    until?: number;
+    /** Maximum number of results (default: no limit) */
+    limit?: number;
+}
+/**
+ * Uniform result envelope for MCP tool calls.
+ */
+interface McpToolResult<T> {
+    /** Whether the tool call succeeded */
+    success: boolean;
+    /** Returned data (present on success) */
+    data?: T;
+    /** Error message (present on failure) */
+    error?: string;
+}
+/**
+ * Chronos MCP tools bound to a Chronicle instance.
+ */
+interface ChronosMcpTools {
+    /**
+     * `chronos.trace` — trace causality backward/forward from a Chronicle node.
+     */
+    trace(params: ChronosTraceParams): Promise<McpToolResult<ChronicleNode[]>>;
+    /**
+     * `chronos.search` — search Chronicle nodes by path, metadata, or payload content.
+     */
+    search(params: ChronosSearchParams): Promise<McpToolResult<ChronicleNode[]>>;
+}
+/**
+ * Create Chronos MCP tools bound to a Chronicle instance.
+ *
+ * @param chronicle Chronicle instance to query
+ * @returns Object with `trace` and `search` tool handlers
+ */
+declare function createChronosMcpTools(chronicle: Chronicle): ChronosMcpTools;
+
 /**
  * PluresDB Integration
  *
@@ -3052,4 +3353,4 @@ declare function attachAllIntegrations<TContext = unknown>(engine: LogicEngine<T
     dispose: () => void;
 }>;
 
-export { AcknowledgeContractGap, type ActivityState, type Actor, ActorManager, Assumption, BehaviorLedger, type CanvasDocument, type CanvasEdge, type CanvasEdgeStyle, type CanvasEditorConfig, type CanvasNode, type CanvasNodeStyle, ComponentDefinition, ConstraintDescriptor, ConstraintFn, type ConstraintNode, type ConstraintSchema, Contract, ContractAdded, ContractGapAcknowledged, ContractMissing, ContractUpdated, ContractValidated, type DefineConstraintOptions, type DefineModuleOptions, type DefineRuleOptions, type EventDefinition, type EventStreamEntry, type FactDefinition, ReactiveLogicEngine as FrameworkAgnosticReactiveEngine, type ReactiveEngineOptions as FrameworkAgnosticReactiveEngineOptions, type GeneratedDoc, type GeneratedPluresDBFile, type GraphEdge, type GuardianError, type GuardianResult, type GuardianWarning, type LedgerEntry, type LedgerEntryStatus, type LifecycleState, type LoaderOptions, type LoaderResult, LogicDefinition, LogicEngine, MissingArtifact, ModelDefinition, PRAXIS_PATHS, type PluresDBAdapter, type PluresDBAdapterOptions, PluresDBGenerator, type PluresDBGeneratorOptions, PraxisDB, PraxisDBStore, type PraxisDBStoreOptions, PraxisEvent, PraxisFact, PraxisModule, PraxisRegistry, PraxisSchema, PraxisSchemaRegistry, PraxisState, type RegistryGraph, RegistryIntrospector, type RegistrySchema, type RegistryStats, RuleDescriptor, RuleFn, type RuleNode, type RuleSchema, Severity, 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 TransitionDoc, type UnifiedApp, type UnifiedAppConfig, UnsubscribeFn$1 as UnsubscribeFn, type UnumAdapter, type UnumAdapterConfig, type UnumChannel, type UnumIdentity, type UnumMessage, type UnumStore, ValidateContracts, type ValidateOptions, ValidationReport, ValidationResult, attachAllIntegrations, attachTauriToEngine, attachToEngine, attachUnumToEngine, canvasToMermaid, canvasToSchema, canvasToYaml, createBehaviorLedger, createCanvasEditor, createReactiveEngine as createFrameworkAgnosticReactiveEngine, createIntrospector, createMockTauriBridge, createPluresDBAdapter, createPluresDBGenerator, createPraxisDBStore, createSchemaRegistry, createStateDocsGenerator, createTauriPraxisAdapter, createTimerActor, createUnifiedApp, createUnumAdapter, defineConstraint, defineEvent, defineFact, defineModule, defineRule, filterEvents, filterFacts, findEvent, findFact, formatValidationReport, formatValidationReportJSON, formatValidationReportSARIF, generateDocs, generateId, generateTauriConfig, getEventPath, getFactPath, getSchemaPath, loadSchema, loadSchemaFromFile, loadSchemaFromJson, loadSchemaFromYaml, registerSchema, schemaToCanvas, validateContracts, validateForGeneration, validateWithGuardian };
+export { AcknowledgeContractGap, type ActivityState, type Actor, ActorManager, Assumption, BehaviorLedger, CHRONICLE_PATHS, type CanvasDocument, type CanvasEdge, type CanvasEdgeStyle, type CanvasEditorConfig, type CanvasNode, type CanvasNodeStyle, type Chronicle, ChronicleContext, type ChronicleEdge, type ChronicleEvent, type ChronicleNode, type ChronicleSpan, type ChronosMcpTools, type ChronosSearchParams, type ChronosTraceParams, ComponentDefinition, ConstraintDescriptor, ConstraintFn, type ConstraintNode, type ConstraintSchema, Contract, ContractAdded, ContractGapAcknowledged, ContractMissing, ContractUpdated, ContractValidated, type DefineConstraintOptions, type DefineModuleOptions, type DefineRuleOptions, type EdgeType, type EventDefinition, type EventStreamEntry, type FactDefinition, ReactiveLogicEngine as FrameworkAgnosticReactiveEngine, type ReactiveEngineOptions as FrameworkAgnosticReactiveEngineOptions, type GeneratedDoc, type GeneratedPluresDBFile, type GraphEdge, type GuardianError, type GuardianResult, type GuardianWarning, type LedgerEntry, type LedgerEntryStatus, type LifecycleState, type LoaderOptions, type LoaderResult, LogicDefinition, LogicEngine, type McpToolResult, MissingArtifact, ModelDefinition, PRAXIS_PATHS, type PluresDBAdapter, type PluresDBAdapterOptions, PluresDBGenerator, type PluresDBGeneratorOptions, PluresDbChronicle, PraxisDB, PraxisDBStore, type PraxisDBStoreOptions, PraxisEvent, PraxisFact, PraxisModule, PraxisRegistry, PraxisSchema, PraxisSchemaRegistry, PraxisState, type RegistryGraph, RegistryIntrospector, type RegistrySchema, type RegistryStats, RuleDescriptor, RuleFn, type RuleNode, type RuleSchema, Severity, 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 TraceDirection, type TransitionDoc, type UnifiedApp, type UnifiedAppConfig, UnsubscribeFn$1 as UnsubscribeFn, type UnumAdapter, type UnumAdapterConfig, type UnumChannel, type UnumIdentity, type UnumMessage, type UnumStore, ValidateContracts, type ValidateOptions, ValidationReport, ValidationResult, attachAllIntegrations, attachTauriToEngine, attachToEngine, attachUnumToEngine, canvasToMermaid, canvasToSchema, canvasToYaml, createBehaviorLedger, createCanvasEditor, createChronicle, createChronosMcpTools, createReactiveEngine as createFrameworkAgnosticReactiveEngine, createIntrospector, createMockTauriBridge, createPluresDBAdapter, createPluresDBGenerator, createPraxisDBStore, createSchemaRegistry, createStateDocsGenerator, createTauriPraxisAdapter, createTimerActor, createUnifiedApp, createUnumAdapter, defineConstraint, defineEvent, defineFact, defineModule, defineRule, filterEvents, filterFacts, findEvent, findFact, formatValidationReport, formatValidationReportJSON, formatValidationReportSARIF, generateDocs, generateId, generateTauriConfig, getEventPath, getFactPath, getSchemaPath, loadSchema, loadSchemaFromFile, loadSchemaFromJson, loadSchemaFromYaml, registerSchema, schemaToCanvas, validateContracts, validateForGeneration, validateWithGuardian };