@plures/praxis 1.4.0 → 2.0.0

package/src/chronos/project-chronicle.ts

@@ -0,0 +1,198 @@
+/**
+ * Project Chronicle — Core Event Store
+ *
+ * Records project lifecycle events (rule registrations, contract changes,
+ * gate transitions, build events, etc.) as a queryable, append-only log.
+ *
+ * This is the development-lifecycle counterpart to runtime Chronos:
+ * where runtime Chronos records "user typed, rule fired, fact emitted",
+ * project-level Chronos records "rule registered, contract updated,
+ * gate opened, completeness score changed."
+ */
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+/** The kind of project lifecycle event. */
+export type ProjectEventKind =
+  | 'rule'
+  | 'contract'
+  | 'expectation'
+  | 'gate'
+  | 'build'
+  | 'fact';
+
+/**
+ * A single project lifecycle event.
+ *
+ * Immutable once recorded — the chronicle is append-only.
+ */
+export interface ProjectEvent {
+  /** Event kind (rule, contract, expectation, gate, build, fact). */
+  kind: ProjectEventKind;
+  /**
+   * Action that occurred.
+   * Examples: 'registered', 'modified', 'removed', 'satisfied', 'violated',
+   *           'opened', 'closed', 'blocked', 'audit-complete', 'introduced', 'deprecated'.
+   */
+  action: string;
+  /** The subject (rule id, contract id, gate name, fact tag, etc.). */
+  subject: string;
+  /** Unix ms timestamp. */
+  timestamp: number;
+  /** Arbitrary metadata for this event. */
+  metadata: Record<string, unknown>;
+  /** Optional before/after diff for modifications. */
+  diff?: { before: unknown; after: unknown };
+}
+
+/** Options for creating a ProjectChronicle. */
+export interface ProjectChronicleOptions {
+  /** Maximum events to retain (0 = unlimited, default 10_000). */
+  maxEvents?: number;
+  /** Optional clock function (for testing). */
+  now?: () => number;
+}
+
+// ─── ProjectChronicle ───────────────────────────────────────────────────────
+
+/**
+ * In-memory, append-only chronicle of project lifecycle events.
+ *
+ * Thread-safe for single-threaded JS; immutable snapshots via `getEvents()`.
+ */
+export class ProjectChronicle {
+  private events: ProjectEvent[] = [];
+  private readonly maxEvents: number;
+  private readonly now: () => number;
+
+  constructor(options: ProjectChronicleOptions = {}) {
+    this.maxEvents = options.maxEvents ?? 10_000;
+    this.now = options.now ?? (() => Date.now());
+  }
+
+  // ── Recording ───────────────────────────────────────────────────────────
+
+  /**
+   * Record a project event. Returns the recorded event (with timestamp filled in).
+   */
+  record(
+    event: Omit<ProjectEvent, 'timestamp'> & { timestamp?: number },
+  ): ProjectEvent {
+    const full: ProjectEvent = {
+      kind: event.kind,
+      action: event.action,
+      subject: event.subject,
+      timestamp: event.timestamp ?? this.now(),
+      metadata: event.metadata,
+      diff: event.diff,
+    };
+    this.events.push(full);
+
+    // Evict oldest if over cap
+    if (this.maxEvents > 0 && this.events.length > this.maxEvents) {
+      this.events = this.events.slice(this.events.length - this.maxEvents);
+    }
+
+    return full;
+  }
+
+  // ── Convenience recorders ─────────────────────────────────────────────
+
+  recordRuleRegistered(ruleId: string, meta: Record<string, unknown> = {}): ProjectEvent {
+    return this.record({ kind: 'rule', action: 'registered', subject: ruleId, metadata: meta });
+  }
+
+  recordRuleModified(
+    ruleId: string,
+    diff: { before: unknown; after: unknown },
+    meta: Record<string, unknown> = {},
+  ): ProjectEvent {
+    return this.record({ kind: 'rule', action: 'modified', subject: ruleId, metadata: meta, diff });
+  }
+
+  recordRuleRemoved(ruleId: string, meta: Record<string, unknown> = {}): ProjectEvent {
+    return this.record({ kind: 'rule', action: 'removed', subject: ruleId, metadata: meta });
+  }
+
+  recordContractAdded(contractId: string, meta: Record<string, unknown> = {}): ProjectEvent {
+    return this.record({ kind: 'contract', action: 'added', subject: contractId, metadata: meta });
+  }
+
+  recordContractModified(
+    contractId: string,
+    diff: { before: unknown; after: unknown },
+    meta: Record<string, unknown> = {},
+  ): ProjectEvent {
+    return this.record({ kind: 'contract', action: 'modified', subject: contractId, metadata: meta, diff });
+  }
+
+  recordExpectationSatisfied(name: string, meta: Record<string, unknown> = {}): ProjectEvent {
+    return this.record({ kind: 'expectation', action: 'satisfied', subject: name, metadata: meta });
+  }
+
+  recordExpectationViolated(name: string, meta: Record<string, unknown> = {}): ProjectEvent {
+    return this.record({ kind: 'expectation', action: 'violated', subject: name, metadata: meta });
+  }
+
+  recordGateTransition(
+    gateName: string,
+    from: string,
+    to: string,
+    meta: Record<string, unknown> = {},
+  ): ProjectEvent {
+    return this.record({
+      kind: 'gate',
+      action: to,
+      subject: gateName,
+      metadata: { ...meta, from, to },
+      diff: { before: from, after: to },
+    });
+  }
+
+  recordBuildAudit(
+    score: number,
+    delta: number,
+    meta: Record<string, unknown> = {},
+  ): ProjectEvent {
+    return this.record({
+      kind: 'build',
+      action: 'audit-complete',
+      subject: 'completeness',
+      metadata: { ...meta, score, delta },
+    });
+  }
+
+  recordFactIntroduced(factTag: string, meta: Record<string, unknown> = {}): ProjectEvent {
+    return this.record({ kind: 'fact', action: 'introduced', subject: factTag, metadata: meta });
+  }
+
+  recordFactDeprecated(factTag: string, meta: Record<string, unknown> = {}): ProjectEvent {
+    return this.record({ kind: 'fact', action: 'deprecated', subject: factTag, metadata: meta });
+  }
+
+  // ── Access ──────────────────────────────────────────────────────────────
+
+  /** Return a shallow copy of all events. */
+  getEvents(): ProjectEvent[] {
+    return [...this.events];
+  }
+
+  /** Total number of recorded events. */
+  get size(): number {
+    return this.events.length;
+  }
+
+  /** Clear all events (primarily for testing). */
+  clear(): void {
+    this.events = [];
+  }
+}
+
+/**
+ * Create a new ProjectChronicle instance.
+ */
+export function createProjectChronicle(
+  options?: ProjectChronicleOptions,
+): ProjectChronicle {
+  return new ProjectChronicle(options);
+}

package/src/chronos/timeline.ts

@@ -0,0 +1,152 @@
+/**
+ * Timeline — Queryable view over ProjectChronicle events
+ *
+ * Provides filtering, range queries, subject history, and behavioral deltas.
+ */
+
+import type { ProjectEvent, ProjectEventKind } from './project-chronicle.js';
+import type { ProjectChronicle } from './project-chronicle.js';
+
+// ─── Filter Types ───────────────────────────────────────────────────────────
+
+/** Filter criteria for timeline queries. All fields are optional (AND logic). */
+export interface TimelineFilter {
+  /** Filter by event kind(s). */
+  kind?: ProjectEventKind | ProjectEventKind[];
+  /** Filter by action string(s). */
+  action?: string | string[];
+  /** Filter by subject (exact match or array). */
+  subject?: string | string[];
+  /** Only events at or after this timestamp (inclusive). */
+  since?: number;
+  /** Only events at or before this timestamp (inclusive). */
+  until?: number;
+}
+
+/** Summary of changes between two points in time. */
+export interface BehavioralDelta {
+  /** Time range of this delta. */
+  from: number;
+  to: number;
+  /** Events within the range. */
+  events: ProjectEvent[];
+  /** Summary counts by kind. */
+  summary: Record<ProjectEventKind, number>;
+  /** Subjects that were added (first 'registered' / 'added' / 'introduced'). */
+  added: string[];
+  /** Subjects that were removed ('removed' / 'deprecated'). */
+  removed: string[];
+  /** Subjects that were modified. */
+  modified: string[];
+}
+
+// ─── Timeline Class ─────────────────────────────────────────────────────────
+
+/**
+ * Queryable timeline wrapping a ProjectChronicle.
+ *
+ * All query methods return new arrays — never the internal event store.
+ */
+export class Timeline {
+  constructor(private readonly chronicle: ProjectChronicle) {}
+
+  // ── Queries ─────────────────────────────────────────────────────────────
+
+  /**
+   * Query events with optional filtering.
+   * Returns matching events sorted chronologically (oldest first).
+   */
+  getTimeline(filter?: TimelineFilter): ProjectEvent[] {
+    let events = this.chronicle.getEvents();
+    if (!filter) return events;
+    events = applyFilter(events, filter);
+    return events;
+  }
+
+  /**
+   * Get all events since a timestamp (inclusive).
+   */
+  getEventsSince(timestamp: number): ProjectEvent[] {
+    return this.getTimeline({ since: timestamp });
+  }
+
+  /**
+   * Compute a behavioral delta between two timestamps.
+   */
+  getDelta(from: number, to: number): BehavioralDelta {
+    const events = this.getTimeline({ since: from, until: to });
+    return buildDelta(from, to, events);
+  }
+
+  /**
+   * Get full history for a specific subject (rule id, gate name, etc.).
+   * Sorted chronologically.
+   */
+  getHistory(subjectId: string): ProjectEvent[] {
+    return this.getTimeline({ subject: subjectId });
+  }
+}
+
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+function applyFilter(events: ProjectEvent[], filter: TimelineFilter): ProjectEvent[] {
+  return events.filter(e => {
+    if (filter.kind) {
+      const kinds = Array.isArray(filter.kind) ? filter.kind : [filter.kind];
+      if (!kinds.includes(e.kind)) return false;
+    }
+    if (filter.action) {
+      const actions = Array.isArray(filter.action) ? filter.action : [filter.action];
+      if (!actions.includes(e.action)) return false;
+    }
+    if (filter.subject) {
+      const subjects = Array.isArray(filter.subject) ? filter.subject : [filter.subject];
+      if (!subjects.includes(e.subject)) return false;
+    }
+    if (filter.since != null && e.timestamp < filter.since) return false;
+    if (filter.until != null && e.timestamp > filter.until) return false;
+    return true;
+  });
+}
+
+const ADD_ACTIONS = new Set(['registered', 'added', 'introduced', 'opened']);
+const REMOVE_ACTIONS = new Set(['removed', 'deprecated', 'closed']);
+const MODIFY_ACTIONS = new Set(['modified', 'updated']);
+
+function buildDelta(from: number, to: number, events: ProjectEvent[]): BehavioralDelta {
+  const summary: Record<string, number> = {};
+  const added = new Set<string>();
+  const removed = new Set<string>();
+  const modified = new Set<string>();
+
+  for (const e of events) {
+    summary[e.kind] = (summary[e.kind] ?? 0) + 1;
+
+    if (ADD_ACTIONS.has(e.action)) {
+      added.add(e.subject);
+      removed.delete(e.subject); // re-added overrides removal
+    } else if (REMOVE_ACTIONS.has(e.action)) {
+      removed.add(e.subject);
+      added.delete(e.subject); // removed overrides addition
+    } else if (MODIFY_ACTIONS.has(e.action)) {
+      modified.add(e.subject);
+    }
+  }
+
+  return {
+    from,
+    to,
+    events,
+    summary: summary as Record<ProjectEventKind, number>,
+    added: [...added],
+    removed: [...removed],
+    modified: [...modified],
+  };
+}
+
+/**
+ * Create a Timeline for a given chronicle.
+ */
+export function createTimeline(chronicle: ProjectChronicle): Timeline {
+  return new Timeline(chronicle);
+}

package/src/decision-ledger/analyzer-types.ts

@@ -0,0 +1,280 @@
+/**
+ * Decision Ledger — Analyzer Types
+ *
+ * Types for the graph analysis engine that understands the entire rule graph
+ * and finds what's missing, broken, or unreachable.
+ */
+
+// ─── Dependency Graph ───────────────────────────────────────────────────────
+
+/** A node in the fact dependency graph */
+export interface FactNode {
+  /** The fact tag */
+  tag: string;
+  /** Rules that produce this fact */
+  producedBy: string[];
+  /** Rules that read/consume this fact */
+  consumedBy: string[];
+}
+
+/** An edge in the dependency graph (rule → fact or fact → rule) */
+export interface DependencyEdge {
+  from: string;
+  to: string;
+  type: 'produces' | 'consumes';
+}
+
+/** The full dependency graph */
+export interface DependencyGraph {
+  /** Fact nodes keyed by tag */
+  facts: Map<string, FactNode>;
+  /** All edges */
+  edges: DependencyEdge[];
+  /** Rule IDs that produce facts */
+  producers: Map<string, string[]>; // ruleId → fact tags produced
+  /** Rule IDs that consume facts */
+  consumers: Map<string, string[]>; // ruleId → fact tags consumed
+}
+
+// ─── Derivation Chains ──────────────────────────────────────────────────────
+
+/** A single step in a derivation chain */
+export interface DerivationStep {
+  type: 'event' | 'rule-fired' | 'fact-produced' | 'fact-read';
+  id: string; // event tag, rule id, or fact tag
+  description: string;
+}
+
+/** A chain showing how a fact was derived */
+export interface DerivationChain {
+  /** The target fact tag */
+  targetFact: string;
+  /** Ordered steps from origin to target */
+  steps: DerivationStep[];
+  /** Depth of the chain */
+  depth: number;
+}
+
+// ─── Dead Rules ─────────────────────────────────────────────────────────────
+
+/** A rule that can never fire given known event types */
+export interface DeadRule {
+  ruleId: string;
+  description: string;
+  /** Event types the rule requires */
+  requiredEventTypes: string[];
+  /** Why it's dead */
+  reason: string;
+}
+
+// ─── Unreachable States ─────────────────────────────────────────────────────
+
+/** A fact combination that no rule sequence can produce */
+export interface UnreachableState {
+  /** The fact tags that can't be produced together */
+  factTags: string[];
+  /** Why it's unreachable */
+  reason: string;
+}
+
+// ─── Shadowed Rules ─────────────────────────────────────────────────────────
+
+/** A rule that always loses to another */
+export interface ShadowedRule {
+  /** The shadowed rule */
+  ruleId: string;
+  /** The rule that shadows it */
+  shadowedBy: string;
+  /** Shared event types */
+  sharedEventTypes: string[];
+  /** Why it's shadowed */
+  reason: string;
+}
+
+// ─── Contradictions ─────────────────────────────────────────────────────────
+
+/** Two rules that produce conflicting facts */
+export interface Contradiction {
+  /** First rule */
+  ruleA: string;
+  /** Second rule */
+  ruleB: string;
+  /** The conflicting fact tag */
+  conflictingTag: string;
+  /** Description of the conflict */
+  reason: string;
+}
+
+// ─── Gaps ───────────────────────────────────────────────────────────────────
+
+/** An expected behavior with no covering rule */
+export interface Gap {
+  /** The expectation name */
+  expectationName: string;
+  /** What's missing */
+  description: string;
+  /** Related rule IDs that partially cover */
+  partialCoverage: string[];
+  /** The type of gap */
+  type: 'no-rule' | 'partial-coverage' | 'no-contract';
+}
+
+// ─── Impact Analysis ────────────────────────────────────────────────────────
+
+/** Impact of removing a fact */
+export interface ImpactReport {
+  /** The fact being analyzed */
+  factTag: string;
+  /** Rules that would stop firing */
+  affectedRules: string[];
+  /** Facts that would disappear (transitively) */
+  affectedFacts: string[];
+  /** Total downstream impact depth */
+  depth: number;
+}
+
+// ─── Contract Verification ──────────────────────────────────────────────────
+
+/** Result of running a contract example against its rule */
+export interface ExampleVerification {
+  /** The example index */
+  index: number;
+  /** Given/When/Then description */
+  given: string;
+  when: string;
+  expectedThen: string;
+  /** Whether it passed */
+  passed: boolean;
+  /** Actual output if different */
+  actualOutput?: string;
+  /** Error if execution failed */
+  error?: string;
+}
+
+/** Contract verification result for a single rule */
+export interface ContractVerificationResult {
+  ruleId: string;
+  /** Example verification results */
+  examples: ExampleVerification[];
+  /** Whether all examples passed */
+  allPassed: boolean;
+  /** Number of passing examples */
+  passCount: number;
+  /** Number of failing examples */
+  failCount: number;
+}
+
+/** Invariant check result */
+export interface InvariantCheck {
+  /** The invariant statement */
+  invariant: string;
+  /** The rule it belongs to */
+  ruleId: string;
+  /** Whether it holds */
+  holds: boolean;
+  /** Explanation */
+  explanation: string;
+}
+
+/** Contract gap finding (deeper than registration-time) */
+export interface ContractCoverageGap {
+  ruleId: string;
+  /** What's not covered */
+  description: string;
+  /** Type of gap */
+  type: 'missing-edge-case' | 'missing-error-path' | 'missing-boundary' | 'cross-reference-broken';
+}
+
+/** Cross-reference result */
+export interface CrossReference {
+  /** Rule whose contract references another rule's facts */
+  sourceRuleId: string;
+  /** The referenced fact tag */
+  referencedFactTag: string;
+  /** The rule that produces the referenced fact (or null if missing) */
+  producerRuleId: string | null;
+  /** Whether the producer exists */
+  valid: boolean;
+}
+
+// ─── Suggestions ────────────────────────────────────────────────────────────
+
+/** Types of findings that can generate suggestions */
+export type FindingType = 'dead-rule' | 'gap' | 'contradiction' | 'unreachable-state' | 'shadowed-rule' | 'contract-gap';
+
+/** An actionable fix suggestion */
+export interface Suggestion {
+  /** What finding this addresses */
+  findingType: FindingType;
+  /** Related entity ID */
+  entityId: string;
+  /** Human-readable suggestion */
+  message: string;
+  /** Suggested action type */
+  action: 'remove' | 'add-rule' | 'modify' | 'merge' | 'add-priority' | 'add-event-type' | 'add-contract';
+  /** Priority (higher = more important) */
+  priority: number;
+  /** Optional code skeleton */
+  skeleton?: string;
+}
+
+// ─── Full Analysis Report ───────────────────────────────────────────────────
+
+/** The complete analysis report from the decision ledger analyzer */
+export interface AnalysisReport {
+  /** Timestamp of the analysis */
+  timestamp: string;
+  /** Fact derivation chains */
+  factDerivationChains: DerivationChain[];
+  /** Rules that can never fire */
+  deadRules: DeadRule[];
+  /** Fact combos no rule can produce */
+  unreachableStates: UnreachableState[];
+  /** Rules always overshadowed by another */
+  shadowedRules: ShadowedRule[];
+  /** Rules producing conflicting facts */
+  contradictions: Contradiction[];
+  /** Expected behaviors with no covering rule */
+  gaps: Gap[];
+  /** Actionable fix suggestions */
+  suggestions: Suggestion[];
+  /** Summary statistics */
+  summary: {
+    totalRules: number;
+    totalConstraints: number;
+    deadRuleCount: number;
+    unreachableStateCount: number;
+    shadowedRuleCount: number;
+    contradictionCount: number;
+    gapCount: number;
+    suggestionCount: number;
+    healthScore: number; // 0-100
+  };
+}
+
+// ─── Ledger Diff ────────────────────────────────────────────────────────────
+
+/** A change between two analysis runs */
+export interface LedgerDiffEntry {
+  type: 'added' | 'removed' | 'changed';
+  category: 'dead-rule' | 'unreachable-state' | 'shadowed-rule' | 'contradiction' | 'gap' | 'suggestion';
+  description: string;
+  /** Entity ID (rule, state, etc.) */
+  entityId: string;
+}
+
+/** Diff between two analysis reports */
+export interface LedgerDiff {
+  /** Timestamp of the diff */
+  timestamp: string;
+  /** Before report timestamp */
+  beforeTimestamp: string;
+  /** After report timestamp */
+  afterTimestamp: string;
+  /** Changes found */
+  changes: LedgerDiffEntry[];
+  /** Score change */
+  scoreDelta: number;
+  /** Summary */
+  summary: string;
+}