@plures/praxis 1.2.13 → 1.2.41

package/src/conversations/normalize.ts

@@ -0,0 +1,51 @@
+/**
+ * Normalization module for praxis-conversations
+ * Handles normalization of conversation content (deterministic)
+ */
+
+import type { Conversation } from './types.js';
+
+/**
+ * Normalize whitespace in text
+ */
+function normalizeWhitespace(text: string): string {
+  return text
+    .replace(/\r\n/g, '\n') // Normalize line endings
+    .replace(/\t/g, '  ') // Replace tabs with spaces
+    .replace(/\n{3,}/g, '\n\n') // Collapse multiple newlines
+    .trim();
+}
+
+/**
+ * Normalize code blocks
+ */
+function normalizeCodeBlocks(text: string): string {
+  // Ensure code blocks have consistent formatting
+  return text.replace(/```(\w+)?\n/g, (_match, lang) => {
+    return lang ? `\`\`\`${lang.toLowerCase()}\n` : '```\n';
+  });
+}
+
+/**
+ * Normalize a single conversation turn
+ */
+function normalizeTurn(content: string): string {
+  let normalized = content;
+  normalized = normalizeWhitespace(normalized);
+  normalized = normalizeCodeBlocks(normalized);
+  return normalized;
+}
+
+/**
+ * Normalize a conversation
+ */
+export function normalizeConversation(conversation: Conversation): Conversation {
+  return {
+    ...conversation,
+    turns: conversation.turns.map(turn => ({
+      ...turn,
+      content: normalizeTurn(turn.content),
+    })),
+    normalized: true,
+  };
+}

package/src/conversations/redact.ts

@@ -0,0 +1,57 @@
+/**
+ * Redaction module for praxis-conversations
+ * Handles PII redaction from conversations (deterministic patterns only)
+ */
+
+import type { Conversation } from './types.js';
+
+/**
+ * Deterministic PII patterns to redact
+ * Note: These patterns prioritize safety over precision
+ * - IP pattern: matches sequences like XXX.XXX.XXX.XXX (may match invalid IPs)
+ * - Card pattern: matches 16-digit sequences (does not validate with Luhn algorithm)
+ */
+const PII_PATTERNS = [
+  // Email addresses
+  { pattern: /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b/g, replacement: '[EMAIL_REDACTED]' },
+  // Phone numbers (simple patterns)
+  { pattern: /\b\d{3}[-.]?\d{3}[-.]?\d{4}\b/g, replacement: '[PHONE_REDACTED]' },
+  // Credit card numbers (basic pattern - intentionally broad for safety)
+  { pattern: /\b\d{4}[\s-]?\d{4}[\s-]?\d{4}[\s-]?\d{4}\b/g, replacement: '[CARD_REDACTED]' },
+  // SSN pattern
+  { pattern: /\b\d{3}-\d{2}-\d{4}\b/g, replacement: '[SSN_REDACTED]' },
+  // IP addresses (basic pattern - may match invalid IPs like 999.999.999.999)
+  { pattern: /\b\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}\b/g, replacement: '[IP_REDACTED]' },
+];
+
+/**
+ * Redact PII from a text string using deterministic patterns
+ */
+export function redactText(text: string): string {
+  let redacted = text;
+  for (const { pattern, replacement } of PII_PATTERNS) {
+    redacted = redacted.replace(pattern, replacement);
+  }
+  return redacted;
+}
+
+/**
+ * Redact PII from a conversation
+ */
+export function redactConversation(conversation: Conversation): Conversation {
+  return {
+    ...conversation,
+    turns: conversation.turns.map(turn => ({
+      ...turn,
+      content: redactText(turn.content),
+    })),
+    metadata: {
+      ...conversation.metadata,
+      // Redact userId if it looks like an email
+      userId: conversation.metadata.userId 
+        ? redactText(conversation.metadata.userId)
+        : undefined,
+    },
+    redacted: true,
+  };
+}

package/src/conversations/types.ts

@@ -0,0 +1,96 @@
+/**
+ * TypeScript types for the praxis-conversations subsystem
+ */
+
+export interface ConversationTurn {
+  role: 'user' | 'assistant' | 'system';
+  content: string;
+  timestamp: string;
+  metadata?: Record<string, unknown>;
+}
+
+export interface ConversationMetadata {
+  source?: string;
+  userId?: string;
+  sessionId?: string;
+  tags?: string[];
+}
+
+export interface Classification {
+  category?: string;
+  confidence?: number;
+  tags?: string[];
+}
+
+export interface Conversation {
+  id: string;
+  timestamp: string;
+  turns: ConversationTurn[];
+  metadata: ConversationMetadata;
+  redacted?: boolean;
+  normalized?: boolean;
+  classified?: boolean;
+  classification?: Classification;
+}
+
+export interface GateResult {
+  name: string;
+  passed: boolean;
+  message?: string;
+}
+
+export interface GateStatus {
+  passed: boolean;
+  reason?: string;
+  gates?: GateResult[];
+}
+
+export interface EmissionResult {
+  success: boolean;
+  timestamp: string;
+  externalId?: string;
+  error?: string;
+}
+
+export interface CandidateMetadata {
+  priority?: 'low' | 'medium' | 'high' | 'critical';
+  labels?: string[];
+  assignees?: string[];
+  source?: {
+    conversationId: string;
+    timestamp: string;
+  };
+}
+
+export interface Candidate {
+  id: string;
+  conversationId: string;
+  type: 'github-issue' | 'github-pr' | 'documentation' | 'feature-request' | 'bug-report';
+  title: string;
+  body: string;
+  metadata: CandidateMetadata;
+  gateStatus?: GateStatus;
+  emitted?: boolean;
+  emissionResult?: EmissionResult;
+}
+
+export interface PipelineOptions {
+  skipRedaction?: boolean;
+  skipNormalization?: boolean;
+  skipClassification?: boolean;
+}
+
+export interface EmitterOptions {
+  dryRun?: boolean;
+  commitIntent?: boolean;
+}
+
+export interface FSEmitterOptions extends EmitterOptions {
+  outputDir: string;
+}
+
+export interface GitHubEmitterOptions extends EmitterOptions {
+  owner: string;
+  repo: string;
+  token?: string;
+}

package/src/core/chronicle/chronicle.ts

@@ -0,0 +1,227 @@
+/**
+ * Chronicle Interface and PluresDbChronicle Implementation
+ *
+ * Records state transitions as a causal graph in PluresDB.
+ * Attached to PraxisDBStore via `.withChronicle()` for zero-effort observability.
+ */
+
+import type { PraxisDB } from '../pluresdb/adapter.js';
+import type { ChronicleEvent, ChronicleEdge, ChronicleNode, EdgeType, TraceDirection } from './types.js';
+
+/**
+ * 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)
+ */
+export const CHRONICLE_PATHS = {
+  BASE: '/_praxis/chronos',
+  NODES: '/_praxis/chronos/nodes',
+  EDGES_OUT: '/_praxis/chronos/edges/out',
+  EDGES_IN: '/_praxis/chronos/edges/in',
+  CONTEXT: '/_praxis/chronos/context',
+  INDEX: '/_praxis/chronos/index',
+} as const;
+
+/**
+ * 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.
+ */
+export 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[]>;
+}
+
+/**
+ * Monotonically-increasing counter for unique node IDs within a process.
+ *
+ * Node.js is single-threaded: the pre-increment here is atomic within a
+ * turn of the event loop, so this counter produces unique IDs for all
+ * concurrent async operations within a single process.
+ */
+let _nodeCounter = 0;
+
+/**
+ * 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.
+ * ```
+ */
+export class PluresDbChronicle implements Chronicle {
+  private readonly db: PraxisDB;
+
+  constructor(db: PraxisDB) {
+    this.db = db;
+  }
+
+  async record(event: ChronicleEvent): Promise<ChronicleNode> {
+    const timestamp = Date.now();
+    const id = `chronos:${timestamp}-${++_nodeCounter}`;
+
+    const node: ChronicleNode = { id, timestamp, event };
+
+    // Persist the node document
+    await this.db.set(`${CHRONICLE_PATHS.NODES}/${id}`, node);
+
+    // Update global time-ordered index
+    const index = (await this.db.get<string[]>(CHRONICLE_PATHS.INDEX)) ?? [];
+    await this.db.set(CHRONICLE_PATHS.INDEX, [...index, id]);
+
+    // If this change was caused by a known span, create a 'causes' edge
+    if (event.cause) {
+      await this.addEdge(event.cause, id, 'causes');
+    }
+
+    // If this change belongs to a context, maintain per-context ordering
+    if (event.context) {
+      const contextPath = `${CHRONICLE_PATHS.CONTEXT}/${event.context}`;
+      const contextNodes = (await this.db.get<string[]>(contextPath)) ?? [];
+
+      // Link to the previous node in the same context with a 'follows' edge
+      if (contextNodes.length > 0) {
+        const prevId = contextNodes[contextNodes.length - 1]!;
+        await this.addEdge(prevId, id, 'follows');
+      }
+
+      await this.db.set(contextPath, [...contextNodes, id]);
+    }
+
+    return node;
+  }
+
+  async trace(nodeId: string, direction: TraceDirection, maxDepth: number): Promise<ChronicleNode[]> {
+    const visited = new Set<string>();
+    const result: ChronicleNode[] = [];
+    await this._traceRecursive(nodeId, direction, maxDepth, 0, visited, result);
+    return result;
+  }
+
+  async range(start: number, end: number): Promise<ChronicleNode[]> {
+    const index = (await this.db.get<string[]>(CHRONICLE_PATHS.INDEX)) ?? [];
+    const result: ChronicleNode[] = [];
+
+    for (const id of index) {
+      const node = await this.db.get<ChronicleNode>(`${CHRONICLE_PATHS.NODES}/${id}`);
+      if (node && node.timestamp >= start && node.timestamp <= end) {
+        result.push(node);
+      }
+    }
+
+    return result;
+  }
+
+  async subgraph(contextId: string): Promise<ChronicleNode[]> {
+    const contextPath = `${CHRONICLE_PATHS.CONTEXT}/${contextId}`;
+    const nodeIds = (await this.db.get<string[]>(contextPath)) ?? [];
+    const result: ChronicleNode[] = [];
+
+    for (const id of nodeIds) {
+      const node = await this.db.get<ChronicleNode>(`${CHRONICLE_PATHS.NODES}/${id}`);
+      if (node) {
+        result.push(node);
+      }
+    }
+
+    return result;
+  }
+
+  // ── Internal helpers ──────────────────────────────────────────────────────
+
+  private async addEdge(from: string, to: string, type: EdgeType): Promise<void> {
+    const edge: ChronicleEdge = { from, to, type };
+
+    const outPath = `${CHRONICLE_PATHS.EDGES_OUT}/${from}`;
+    const outEdges = (await this.db.get<ChronicleEdge[]>(outPath)) ?? [];
+    await this.db.set(outPath, [...outEdges, edge]);
+
+    const inPath = `${CHRONICLE_PATHS.EDGES_IN}/${to}`;
+    const inEdges = (await this.db.get<ChronicleEdge[]>(inPath)) ?? [];
+    await this.db.set(inPath, [...inEdges, edge]);
+  }
+
+  private async _traceRecursive(
+    nodeId: string,
+    direction: TraceDirection,
+    maxDepth: number,
+    depth: number,
+    visited: Set<string>,
+    result: ChronicleNode[]
+  ): Promise<void> {
+    if (depth > maxDepth || visited.has(nodeId)) {
+      return;
+    }
+    visited.add(nodeId);
+
+    const node = await this.db.get<ChronicleNode>(`${CHRONICLE_PATHS.NODES}/${nodeId}`);
+    if (node) {
+      result.push(node);
+    }
+
+    if (direction === 'backward' || direction === 'both') {
+      const inEdges =
+        (await this.db.get<ChronicleEdge[]>(`${CHRONICLE_PATHS.EDGES_IN}/${nodeId}`)) ?? [];
+      for (const edge of inEdges) {
+        await this._traceRecursive(edge.from, direction, maxDepth, depth + 1, visited, result);
+      }
+    }
+
+    if (direction === 'forward' || direction === 'both') {
+      const outEdges =
+        (await this.db.get<ChronicleEdge[]>(`${CHRONICLE_PATHS.EDGES_OUT}/${nodeId}`)) ?? [];
+      for (const edge of outEdges) {
+        await this._traceRecursive(edge.to, direction, maxDepth, depth + 1, visited, result);
+      }
+    }
+  }
+}
+
+/**
+ * Create a PluresDB-backed Chronicle instance.
+ *
+ * @param db The PraxisDB instance to store causal graph data in
+ */
+export function createChronicle(db: PraxisDB): PluresDbChronicle {
+  return new PluresDbChronicle(db);
+}

package/src/core/chronicle/context.ts

@@ -0,0 +1,80 @@
+/**
+ * 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
+ *   }
+ * );
+ * ```
+ */
+export 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.
+ */
+export class ChronicleContext {
+  private static readonly _stack: ChronicleSpan[] = [];
+
+  /**
+   * Get the current active span, if any.
+   */
+  static get current(): ChronicleSpan | undefined {
+    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<T>(span: ChronicleSpan, fn: () => T): T {
+    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<T>(span: ChronicleSpan, fn: () => Promise<T>): Promise<T> {
+    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: string): ChronicleSpan {
+    return {
+      spanId,
+      contextId: this.current?.contextId,
+    };
+  }
+}

package/src/core/chronicle/index.ts

@@ -0,0 +1,53 @@
+/**
+ * Chronicle Module
+ *
+ * Causal graph tracking for Praxis state transitions.
+ * Records every storeFact / appendEvent call as a Chronicle node in PluresDB,
+ * enabling full observability, auditing, and training data extraction.
+ *
+ * @example
+ * ```typescript
+ * import { createInMemoryDB } from '@plures/praxis';
+ * import { createChronicle, createChronosMcpTools, ChronicleContext } from '@plures/praxis';
+ *
+ * const db = createInMemoryDB();
+ * const chronicle = createChronicle(db);
+ * const store = createPraxisDBStore(db, registry).withChronicle(chronicle);
+ *
+ * // Attribute changes to a causal span
+ * await ChronicleContext.runAsync(
+ *   { spanId: 'route-msg-1', contextId: 'session-abc' },
+ *   () => store.storeFact({ tag: 'RouteDecision', payload: { route: 'fast-path' } })
+ * );
+ *
+ * // Trace causality backward from any node
+ * const tools = createChronosMcpTools(chronicle);
+ * const { data } = await tools.trace({ nodeId: '...', direction: 'backward' });
+ * ```
+ */
+
+// Types
+export type {
+  TraceDirection,
+  EdgeType,
+  ChronicleEvent,
+  ChronicleNode,
+  ChronicleEdge,
+} from './types.js';
+
+// Context propagation
+export { ChronicleContext } from './context.js';
+export type { ChronicleSpan } from './context.js';
+
+// Chronicle interface and PluresDB implementation
+export type { Chronicle } from './chronicle.js';
+export { PluresDbChronicle, createChronicle, CHRONICLE_PATHS } from './chronicle.js';
+
+// MCP tools
+export type {
+  ChronosTraceParams,
+  ChronosSearchParams,
+  McpToolResult,
+  ChronosMcpTools,
+} from './mcp.js';
+export { createChronosMcpTools } from './mcp.js';

package/src/core/chronicle/mcp.ts

@@ -0,0 +1,135 @@
+/**
+ * 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);
+ * ```
+ */
+
+import type { Chronicle } from './chronicle.js';
+import type { ChronicleNode, TraceDirection } from './types.js';
+
+/**
+ * Parameters for the `chronos.trace` MCP tool.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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
+ */
+export function createChronosMcpTools(chronicle: Chronicle): ChronosMcpTools {
+  return {
+    async trace(params: ChronosTraceParams): Promise<McpToolResult<ChronicleNode[]>> {
+      try {
+        const nodes = await chronicle.trace(
+          params.nodeId,
+          params.direction ?? 'backward',
+          params.maxDepth ?? 10
+        );
+        return { success: true, data: nodes };
+      } catch (error) {
+        return {
+          success: false,
+          error: error instanceof Error ? error.message : String(error),
+        };
+      }
+    },
+
+    async search(params: ChronosSearchParams): Promise<McpToolResult<ChronicleNode[]>> {
+      try {
+        const query = params.query.toLowerCase();
+
+        let candidates: ChronicleNode[];
+        if (params.contextId) {
+          candidates = await chronicle.subgraph(params.contextId);
+        } else {
+          candidates = await chronicle.range(params.since ?? 0, params.until ?? Date.now());
+        }
+
+        // Full-text match against path, metadata values, and serialised after/before payloads.
+        // NOTE: This is a linear scan suitable for development and moderate datasets.
+        // For production use at scale, consider building a search index in PluresDB.
+        const filtered = candidates.filter((node) => {
+          const inPath = node.event.path.toLowerCase().includes(query);
+          const inMeta = Object.values(node.event.metadata).some((v) =>
+            v.toLowerCase().includes(query)
+          );
+          const inAfter = JSON.stringify(node.event.after ?? '').toLowerCase().includes(query);
+          const inBefore = JSON.stringify(node.event.before ?? '').toLowerCase().includes(query);
+          return inPath || inMeta || inAfter || inBefore;
+        });
+
+        const limited = params.limit !== undefined ? filtered.slice(0, params.limit) : filtered;
+        return { success: true, data: limited };
+      } catch (error) {
+        return {
+          success: false,
+          error: error instanceof Error ? error.message : String(error),
+        };
+      }
+    },
+  };
+}