@plures/praxis 1.3.0 → 1.4.4

package/src/chronos/diff.ts

@@ -0,0 +1,336 @@
+/**
+ * Behavioral Diff Engine
+ *
+ * Compares registry snapshots, contract coverage, and expectation status
+ * to produce human-readable deltas and conventional commit messages.
+ *
+ * This is the foundation for "commit from state" — describing WHAT changed
+ * in behavioral terms rather than file terms.
+ */
+
+import type { RuleDescriptor, ConstraintDescriptor } from '../core/rules.js';
+import type { PraxisDiff } from '../project/types.js';
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+/** Snapshot of a registry's state (used for before/after comparison). */
+export interface RegistrySnapshot {
+  rules: Map<string, RuleDescriptor> | Array<RuleDescriptor>;
+  constraints: Map<string, ConstraintDescriptor> | Array<ConstraintDescriptor>;
+}
+
+/** Diff result for registries. */
+export interface RegistryDiff {
+  rulesAdded: string[];
+  rulesRemoved: string[];
+  rulesModified: string[];
+  constraintsAdded: string[];
+  constraintsRemoved: string[];
+  constraintsModified: string[];
+}
+
+/** Contract coverage snapshot. */
+export interface ContractCoverage {
+  /** rule id → has contract */
+  coverage: Map<string, boolean> | Record<string, boolean>;
+}
+
+/** Diff result for contract coverage. */
+export interface ContractDiff {
+  contractsAdded: string[];
+  contractsRemoved: string[];
+  coverageBefore: number;
+  coverageAfter: number;
+}
+
+/** Expectation satisfaction snapshot. */
+export interface ExpectationSnapshot {
+  /** expectation name → satisfied */
+  expectations: Map<string, boolean> | Record<string, boolean>;
+}
+
+/** Diff result for expectations. */
+export interface ExpectationDiff {
+  newlySatisfied: string[];
+  newlyViolated: string[];
+  unchanged: string[];
+}
+
+/** Full behavioral diff combining all dimensions. */
+export interface FullBehavioralDiff {
+  registry: RegistryDiff;
+  contracts: ContractDiff;
+  expectations: ExpectationDiff;
+}
+
+// ─── Registry Diff ──────────────────────────────────────────────────────────
+
+/**
+ * Compare two registry snapshots.
+ *
+ * Detects rules/constraints that were added, removed, or modified
+ * (description or contract changed).
+ */
+export function diffRegistries(before: RegistrySnapshot, after: RegistrySnapshot): RegistryDiff {
+  const beforeRules = toIdMap(before.rules);
+  const afterRules = toIdMap(after.rules);
+  const beforeConstraints = toIdMap(before.constraints);
+  const afterConstraints = toIdMap(after.constraints);
+
+  return {
+    rulesAdded: setDiff(afterRules, beforeRules),
+    rulesRemoved: setDiff(beforeRules, afterRules),
+    rulesModified: findModified(beforeRules, afterRules),
+    constraintsAdded: setDiff(afterConstraints, beforeConstraints),
+    constraintsRemoved: setDiff(beforeConstraints, afterConstraints),
+    constraintsModified: findModified(beforeConstraints, afterConstraints),
+  };
+}
+
+// ─── Contract Diff ──────────────────────────────────────────────────────────
+
+/**
+ * Compare contract coverage between two snapshots.
+ */
+export function diffContracts(before: ContractCoverage, after: ContractCoverage): ContractDiff {
+  const beforeMap = toRecord(before.coverage);
+  const afterMap = toRecord(after.coverage);
+
+  const contractsAdded: string[] = [];
+  const contractsRemoved: string[] = [];
+
+  // Check for newly added contracts
+  for (const [id, has] of Object.entries(afterMap)) {
+    if (has && !beforeMap[id]) {
+      contractsAdded.push(id);
+    }
+  }
+
+  // Check for removed contracts
+  for (const [id, had] of Object.entries(beforeMap)) {
+    if (had && !afterMap[id]) {
+      contractsRemoved.push(id);
+    }
+  }
+
+  const countTrue = (r: Record<string, boolean>) =>
+    Object.values(r).filter(Boolean).length;
+  const totalBefore = Object.keys(beforeMap).length;
+  const totalAfter = Object.keys(afterMap).length;
+
+  return {
+    contractsAdded,
+    contractsRemoved,
+    coverageBefore: totalBefore > 0 ? countTrue(beforeMap) / totalBefore : 0,
+    coverageAfter: totalAfter > 0 ? countTrue(afterMap) / totalAfter : 0,
+  };
+}
+
+// ─── Expectation Diff ───────────────────────────────────────────────────────
+
+/**
+ * Compare expectation satisfaction between two snapshots.
+ */
+export function diffExpectations(
+  before: ExpectationSnapshot,
+  after: ExpectationSnapshot,
+): ExpectationDiff {
+  const beforeMap = toRecord(before.expectations);
+  const afterMap = toRecord(after.expectations);
+  const allKeys = new Set([...Object.keys(beforeMap), ...Object.keys(afterMap)]);
+
+  const newlySatisfied: string[] = [];
+  const newlyViolated: string[] = [];
+  const unchanged: string[] = [];
+
+  for (const key of allKeys) {
+    const was = beforeMap[key] ?? false;
+    const is = afterMap[key] ?? false;
+    if (!was && is) {
+      newlySatisfied.push(key);
+    } else if (was && !is) {
+      newlyViolated.push(key);
+    } else {
+      unchanged.push(key);
+    }
+  }
+
+  return { newlySatisfied, newlyViolated, unchanged };
+}
+
+// ─── Formatting ─────────────────────────────────────────────────────────────
+
+/**
+ * Format a RegistryDiff as a human-readable delta string.
+ */
+export function formatDelta(diff: RegistryDiff): string {
+  const lines: string[] = [];
+
+  if (diff.rulesAdded.length > 0)
+    lines.push(`+ Rules added: ${diff.rulesAdded.join(', ')}`);
+  if (diff.rulesRemoved.length > 0)
+    lines.push(`- Rules removed: ${diff.rulesRemoved.join(', ')}`);
+  if (diff.rulesModified.length > 0)
+    lines.push(`~ Rules modified: ${diff.rulesModified.join(', ')}`);
+  if (diff.constraintsAdded.length > 0)
+    lines.push(`+ Constraints added: ${diff.constraintsAdded.join(', ')}`);
+  if (diff.constraintsRemoved.length > 0)
+    lines.push(`- Constraints removed: ${diff.constraintsRemoved.join(', ')}`);
+  if (diff.constraintsModified.length > 0)
+    lines.push(`~ Constraints modified: ${diff.constraintsModified.join(', ')}`);
+
+  return lines.length > 0 ? lines.join('\n') : 'No behavioral changes.';
+}
+
+/**
+ * Generate a conventional commit message from a registry diff.
+ *
+ * Uses the same logic as `commitFromState` in `project/` but works
+ * directly from a RegistryDiff.
+ */
+export function formatCommitMessage(diff: RegistryDiff): string {
+  const praxisDiff: PraxisDiff = {
+    rulesAdded: diff.rulesAdded,
+    rulesRemoved: diff.rulesRemoved,
+    rulesModified: diff.rulesModified,
+    contractsAdded: [],
+    contractsRemoved: [],
+    expectationsAdded: diff.constraintsAdded,
+    expectationsRemoved: diff.constraintsRemoved,
+    gateChanges: [],
+  };
+
+  return commitFromDiff(praxisDiff);
+}
+
+/**
+ * Aggregate multiple diffs into release notes.
+ */
+export function formatReleaseNotes(diffs: RegistryDiff[]): string {
+  const sections: string[] = [];
+  const allAdded: string[] = [];
+  const allRemoved: string[] = [];
+  const allModified: string[] = [];
+
+  for (const diff of diffs) {
+    allAdded.push(...diff.rulesAdded, ...diff.constraintsAdded);
+    allRemoved.push(...diff.rulesRemoved, ...diff.constraintsRemoved);
+    allModified.push(...diff.rulesModified, ...diff.constraintsModified);
+  }
+
+  // Deduplicate
+  const added = [...new Set(allAdded)];
+  const removed = [...new Set(allRemoved)];
+  const modified = [...new Set(allModified)];
+
+  if (added.length > 0) {
+    sections.push(`### Added\n${added.map(id => `- ${id}`).join('\n')}`);
+  }
+  if (modified.length > 0) {
+    sections.push(`### Changed\n${modified.map(id => `- ${id}`).join('\n')}`);
+  }
+  if (removed.length > 0) {
+    sections.push(`### Removed\n${removed.map(id => `- ${id}`).join('\n')}`);
+  }
+
+  if (sections.length === 0) return 'No behavioral changes in this release.';
+  return `## Release Notes\n\n${sections.join('\n\n')}`;
+}
+
+// ─── Internal helpers ───────────────────────────────────────────────────────
+
+function toIdMap(
+  input: Map<string, { id: string; description: string }> | Array<{ id: string; description: string }>,
+): Map<string, { id: string; description: string }> {
+  if (input instanceof Map) return input;
+  const map = new Map<string, { id: string; description: string }>();
+  for (const item of input) map.set(item.id, item);
+  return map;
+}
+
+function setDiff(a: Map<string, unknown>, b: Map<string, unknown>): string[] {
+  const result: string[] = [];
+  for (const key of a.keys()) {
+    if (!b.has(key)) result.push(key);
+  }
+  return result;
+}
+
+function findModified(
+  before: Map<string, { id: string; description: string }>,
+  after: Map<string, { id: string; description: string }>,
+): string[] {
+  const result: string[] = [];
+  for (const [key, beforeVal] of before) {
+    const afterVal = after.get(key);
+    if (afterVal && beforeVal.description !== afterVal.description) {
+      result.push(key);
+    }
+  }
+  return result;
+}
+
+function toRecord(input: Map<string, boolean> | Record<string, boolean>): Record<string, boolean> {
+  if (input instanceof Map) {
+    const result: Record<string, boolean> = {};
+    for (const [k, v] of input) result[k] = v;
+    return result;
+  }
+  return input;
+}
+
+// ── Inline commit message generation (mirrors project/project.ts logic) ──
+
+function commitFromDiff(diff: PraxisDiff): string {
+  const parts: string[] = [];
+  const bodyParts: string[] = [];
+
+  const totalAdded = diff.rulesAdded.length + diff.contractsAdded.length + diff.expectationsAdded.length;
+  const totalRemoved = diff.rulesRemoved.length + diff.contractsRemoved.length + diff.expectationsRemoved.length;
+  const totalModified = diff.rulesModified.length;
+
+  if (totalAdded > 0 && totalRemoved === 0 && totalModified === 0) {
+    if (diff.rulesAdded.length > 0) {
+      const scope = inferScope(diff.rulesAdded);
+      parts.push(`feat(${scope}): add ${fmtIds(diff.rulesAdded)}`);
+    } else if (diff.contractsAdded.length > 0) {
+      parts.push(`feat(contracts): add contracts for ${fmtIds(diff.contractsAdded)}`);
+    } else {
+      parts.push(`feat(expectations): add ${fmtIds(diff.expectationsAdded)}`);
+    }
+  } else if (totalRemoved > 0 && totalAdded === 0) {
+    if (diff.rulesRemoved.length > 0) {
+      const scope = inferScope(diff.rulesRemoved);
+      parts.push(`refactor(${scope}): remove ${fmtIds(diff.rulesRemoved)}`);
+    } else {
+      parts.push(`refactor: remove ${totalRemoved} item(s)`);
+    }
+  } else if (totalModified > 0) {
+    const scope = inferScope(diff.rulesModified);
+    parts.push(`refactor(${scope}): update ${fmtIds(diff.rulesModified)}`);
+  } else {
+    parts.push('chore: behavioral state update');
+  }
+
+  if (diff.rulesAdded.length > 0) bodyParts.push(`Rules added: ${diff.rulesAdded.join(', ')}`);
+  if (diff.rulesRemoved.length > 0) bodyParts.push(`Rules removed: ${diff.rulesRemoved.join(', ')}`);
+  if (diff.rulesModified.length > 0) bodyParts.push(`Rules modified: ${diff.rulesModified.join(', ')}`);
+
+  const subject = parts[0] || 'chore: update';
+  return bodyParts.length > 0 ? `${subject}\n\n${bodyParts.join('\n')}` : subject;
+}
+
+function inferScope(ids: string[]): string {
+  if (ids.length === 0) return 'rules';
+  const prefixes = ids.map(id => {
+    const slash = id.indexOf('/');
+    return slash > 0 ? id.slice(0, slash) : id;
+  });
+  const unique = new Set(prefixes);
+  return unique.size === 1 ? prefixes[0] : 'rules';
+}
+
+function fmtIds(ids: string[]): string {
+  if (ids.length <= 3) return ids.join(', ');
+  return `${ids.slice(0, 2).join(', ')} (+${ids.length - 2} more)`;
+}

package/src/chronos/hooks.ts

@@ -0,0 +1,227 @@
+/**
+ * Auto-Recording Hooks — wire ProjectChronicle into PraxisRegistry & LogicEngine
+ *
+ * Opt-in: call `enableProjectChronicle(registry, engine)` to start recording.
+ * The hooks use Proxy wrapping to intercept method calls without modifying
+ * the original classes.
+ */
+
+import type { PraxisRegistry, RuleDescriptor, PraxisModule } from '../core/rules.js';
+import type { LogicEngine } from '../core/engine.js';
+import type { PraxisEvent, PraxisStepResult, PraxisDiagnostics } from '../core/protocol.js';
+import { ProjectChronicle, createProjectChronicle } from './project-chronicle.js';
+import type { CompletenessReport } from '../core/completeness.js';
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+/** Handle returned by enableProjectChronicle for cleanup. */
+export interface ChronicleHandle {
+  /** The underlying chronicle being written to. */
+  chronicle: ProjectChronicle;
+  /** Disconnect all hooks (restores original methods). */
+  disconnect: () => void;
+}
+
+/** Options for enabling project chronicle hooks. */
+export interface EnableChronicleOptions {
+  /** Provide an existing chronicle (otherwise a new one is created). */
+  chronicle?: ProjectChronicle;
+  /** Record engine step results (fact production/retraction). Default: true. */
+  recordSteps?: boolean;
+  /** Record constraint check results. Default: true. */
+  recordConstraints?: boolean;
+}
+
+// ─── Hook Implementation ────────────────────────────────────────────────────
+
+/**
+ * Enable project-level chronicle recording.
+ *
+ * Wraps registry's `registerRule`, `registerModule` and engine's `step`,
+ * `checkConstraints` methods to automatically record events.
+ *
+ * @returns A handle with the chronicle and a `disconnect()` to undo all hooks.
+ *
+ * @example
+ * ```ts
+ * const { chronicle, disconnect } = enableProjectChronicle(registry, engine);
+ * registry.registerRule(myRule); // auto-recorded
+ * engine.step(events);          // step results auto-recorded
+ * console.log(chronicle.size);  // number of events recorded
+ * disconnect();                 // stop recording
+ * ```
+ */
+export function enableProjectChronicle<TContext = unknown>(
+  registry: PraxisRegistry<TContext>,
+  engine: LogicEngine<TContext>,
+  options: EnableChronicleOptions = {},
+): ChronicleHandle {
+  const chronicle = options.chronicle ?? createProjectChronicle();
+  const recordSteps = options.recordSteps ?? true;
+  const recordConstraints = options.recordConstraints ?? true;
+
+  // Keep originals for cleanup
+  const origRegisterRule = registry.registerRule.bind(registry);
+  const origRegisterModule = registry.registerModule.bind(registry);
+  const origStep = engine.step.bind(engine);
+  const origCheckConstraints = engine.checkConstraints.bind(engine);
+
+  // ── Hook: registerRule ──────────────────────────────────────────────────
+
+  registry.registerRule = function hookedRegisterRule(
+    descriptor: RuleDescriptor<TContext>,
+  ): void {
+    origRegisterRule(descriptor);
+    chronicle.recordRuleRegistered(descriptor.id, {
+      description: descriptor.description,
+      hasContract: !!descriptor.contract,
+      eventTypes: descriptor.eventTypes,
+    });
+    if (descriptor.contract) {
+      chronicle.recordContractAdded(descriptor.id, {
+        behavior: descriptor.contract.behavior,
+        examplesCount: descriptor.contract.examples?.length ?? 0,
+        invariantsCount: descriptor.contract.invariants?.length ?? 0,
+      });
+    }
+  };
+
+  // ── Hook: registerModule ────────────────────────────────────────────────
+
+  registry.registerModule = function hookedRegisterModule(
+    module: PraxisModule<TContext>,
+  ): void {
+    // Call original (which calls registerRule/registerConstraint internally)
+    // But we need to unhook registerRule temporarily to avoid double recording.
+    // Instead, record the module-level event and let the rules record individually.
+    origRegisterModule(module);
+
+    // Record a module-level event for each rule that was part of this module
+    for (const rule of module.rules) {
+      chronicle.recordRuleRegistered(rule.id, {
+        description: rule.description,
+        hasContract: !!rule.contract,
+        eventTypes: rule.eventTypes,
+        registeredVia: 'module',
+      });
+      if (rule.contract) {
+        chronicle.recordContractAdded(rule.id, {
+          behavior: rule.contract.behavior,
+          examplesCount: rule.contract.examples?.length ?? 0,
+          invariantsCount: rule.contract.invariants?.length ?? 0,
+        });
+      }
+    }
+  };
+
+  // ── Hook: engine.step ───────────────────────────────────────────────────
+
+  if (recordSteps) {
+    engine.step = function hookedStep(events: PraxisEvent[]): PraxisStepResult {
+      const result = origStep(events);
+
+      // Record each fact that was produced
+      const factTags = new Set<string>();
+      for (const fact of result.state.facts) {
+        factTags.add(fact.tag);
+      }
+
+      // Record step event
+      chronicle.record({
+        kind: 'build',
+        action: 'step-complete',
+        subject: 'engine',
+        metadata: {
+          eventsProcessed: events.length,
+          eventTags: events.map(e => e.tag),
+          factsAfter: result.state.facts.length,
+          diagnosticsCount: result.diagnostics.length,
+        },
+      });
+
+      // Record any rule errors or constraint violations
+      for (const diag of result.diagnostics) {
+        if (diag.kind === 'constraint-violation') {
+          chronicle.record({
+            kind: 'expectation',
+            action: 'violated',
+            subject: extractSubjectFromDiag(diag),
+            metadata: { message: diag.message, data: diag.data },
+          });
+        }
+      }
+
+      return result;
+    };
+  }
+
+  // ── Hook: engine.checkConstraints ───────────────────────────────────────
+
+  if (recordConstraints) {
+    engine.checkConstraints = function hookedCheckConstraints(): PraxisDiagnostics[] {
+      const diagnostics = origCheckConstraints();
+
+      chronicle.record({
+        kind: 'build',
+        action: 'constraints-checked',
+        subject: 'engine',
+        metadata: {
+          violations: diagnostics.length,
+        },
+      });
+
+      for (const diag of diagnostics) {
+        chronicle.record({
+          kind: 'expectation',
+          action: 'violated',
+          subject: extractSubjectFromDiag(diag),
+          metadata: { message: diag.message },
+        });
+      }
+
+      return diagnostics;
+    };
+  }
+
+  // ── Disconnect ──────────────────────────────────────────────────────────
+
+  function disconnect(): void {
+    registry.registerRule = origRegisterRule;
+    registry.registerModule = origRegisterModule;
+    engine.step = origStep;
+    engine.checkConstraints = origCheckConstraints;
+  }
+
+  return { chronicle, disconnect };
+}
+
+/**
+ * Record a completeness audit result into the chronicle.
+ *
+ * Standalone utility — call after `auditCompleteness()`.
+ */
+export function recordAudit(
+  chronicle: ProjectChronicle,
+  report: CompletenessReport,
+  previousScore?: number,
+): void {
+  const delta = previousScore != null ? report.score - previousScore : 0;
+  chronicle.recordBuildAudit(report.score, delta, {
+    rating: report.rating,
+    rulesCovered: report.rules.covered,
+    rulesTotal: report.rules.total,
+    constraintsCovered: report.constraints.covered,
+    constraintsTotal: report.constraints.total,
+    contractsCovered: report.contracts.withContracts,
+    contractsTotal: report.contracts.total,
+  });
+}
+
+// ─── Internals ──────────────────────────────────────────────────────────────
+
+function extractSubjectFromDiag(diag: PraxisDiagnostics): string {
+  const data = diag.data as Record<string, unknown> | undefined;
+  if (data?.constraintId && typeof data.constraintId === 'string') return data.constraintId;
+  if (data?.ruleId && typeof data.ruleId === 'string') return data.ruleId;
+  return 'unknown';
+}

package/src/chronos/index.ts

@@ -0,0 +1,83 @@
+/**
+ * Chronos — Project-Level Chronicle
+ *
+ * Records and queries the development lifecycle of a Praxis application:
+ * rule registrations, contract changes, gate transitions, build audits, etc.
+ *
+ * @example
+ * ```ts
+ * import {
+ *   createProjectChronicle,
+ *   createTimeline,
+ *   enableProjectChronicle,
+ *   diffRegistries,
+ * } from '@plures/praxis';
+ *
+ * // Manual recording
+ * const chronicle = createProjectChronicle();
+ * chronicle.recordRuleRegistered('auth/login', { description: 'Login rule' });
+ *
+ * // Auto-recording via hooks
+ * const { chronicle: autoChronicle, disconnect } = enableProjectChronicle(registry, engine);
+ * registry.registerRule(myRule); // automatically recorded
+ *
+ * // Querying
+ * const timeline = createTimeline(autoChronicle);
+ * const ruleEvents = timeline.getTimeline({ kind: 'rule' });
+ * const delta = timeline.getDelta(startTs, endTs);
+ *
+ * // Behavioral diff
+ * const diff = diffRegistries(snapshotBefore, snapshotAfter);
+ * console.log(formatCommitMessage(diff));
+ * ```
+ */
+
+// ── Project Chronicle (core event store) ────────────────────────────────────
+export {
+  ProjectChronicle,
+  createProjectChronicle,
+} from './project-chronicle.js';
+export type {
+  ProjectEvent,
+  ProjectEventKind,
+  ProjectChronicleOptions,
+} from './project-chronicle.js';
+
+// ── Timeline (queryable view) ───────────────────────────────────────────────
+export {
+  Timeline,
+  createTimeline,
+} from './timeline.js';
+export type {
+  TimelineFilter,
+  BehavioralDelta,
+} from './timeline.js';
+
+// ── Hooks (auto-recording) ──────────────────────────────────────────────────
+export {
+  enableProjectChronicle,
+  recordAudit,
+} from './hooks.js';
+export type {
+  ChronicleHandle,
+  EnableChronicleOptions,
+} from './hooks.js';
+
+// ── Diff (behavioral comparison) ────────────────────────────────────────────
+export {
+  diffRegistries,
+  diffContracts,
+  diffExpectations,
+  formatDelta,
+  formatCommitMessage,
+  formatReleaseNotes,
+} from './diff.js';
+export type {
+  RegistrySnapshot,
+  RegistryDiff,
+  ContractCoverage,
+  ContractDiff,
+  ExpectationSnapshot,
+  ExpectationDiff,
+  FullBehavioralDiff,
+} from './diff.js';