@plures/praxis 1.2.0 → 1.2.10

package/src/decision-ledger/ledger.ts

@@ -0,0 +1,246 @@
+/**
+ * Decision Ledger - Ledger Storage
+ *
+ * Immutable, append-only ledger for tracking contract history.
+ */
+
+import type { Contract, Assumption } from './types.js';
+
+/**
+ * Status of a ledger entry.
+ */
+export type LedgerEntryStatus = 'active' | 'superseded' | 'deprecated';
+
+/**
+ * A single entry in the behavior ledger.
+ */
+export interface LedgerEntry {
+  /** Unique identifier for this ledger entry */
+  id: string;
+  /** Timestamp of entry creation */
+  timestamp: string;
+  /** Status of this entry */
+  status: LedgerEntryStatus;
+  /** Author or system that created this entry */
+  author: string;
+  /** The contract being recorded */
+  contract: Contract;
+  /** ID of the entry this supersedes (if any) */
+  supersedes?: string;
+  /** Reason for this entry (e.g., 'initial', 'assumption-revised', 'behavior-updated') */
+  reason?: string;
+}
+
+/**
+ * Immutable, append-only behavior ledger.
+ */
+export class BehaviorLedger {
+  private entries: LedgerEntry[] = [];
+  private entryMap: Map<string, LedgerEntry> = new Map();
+
+  /**
+   * Append a new entry to the ledger.
+   *
+   * @param entry The entry to append
+   * @throws Error if entry ID already exists
+   */
+  append(entry: LedgerEntry): void {
+    if (this.entryMap.has(entry.id)) {
+      throw new Error(`Ledger entry with ID '${entry.id}' already exists`);
+    }
+
+    // If this entry supersedes another, mark the old one as superseded
+    // Note: The entries array preserves the original entry for historical record.
+    // Only the map entry is updated to reflect the superseded status for queries.
+    if (entry.supersedes) {
+      const superseded = this.entryMap.get(entry.supersedes);
+      if (superseded && superseded.status === 'active') {
+        // Create a new entry with updated status (immutability)
+        const updatedEntry: LedgerEntry = {
+          ...superseded,
+          status: 'superseded',
+        };
+        // Replace in map but keep original in entries array for history
+        this.entryMap.set(entry.supersedes, updatedEntry);
+      }
+    }
+
+    this.entries.push(entry);
+    this.entryMap.set(entry.id, entry);
+  }
+
+  /**
+   * Get an entry by ID.
+   *
+   * @param id The entry ID
+   * @returns The entry, or undefined if not found
+   */
+  getEntry(id: string): LedgerEntry | undefined {
+    return this.entryMap.get(id);
+  }
+
+  /**
+   * Get all entries (in order of append) with current status.
+   *
+   * @returns Array of all entries with current status from the map
+   */
+  getAllEntries(): LedgerEntry[] {
+    // Return entries with current status from the map
+    return this.entries.map((entry) => this.entryMap.get(entry.id)!);
+  }
+
+  /**
+   * Get entries for a specific rule ID.
+   *
+   * @param ruleId The rule ID
+   * @returns Array of entries for this rule with current status
+   */
+  getEntriesForRule(ruleId: string): LedgerEntry[] {
+    return this.entries
+      .map((entry) => this.entryMap.get(entry.id)!)
+      .filter((entry) => entry.contract.ruleId === ruleId);
+  }
+
+  /**
+   * Get the latest active entry for a rule.
+   *
+   * @param ruleId The rule ID
+   * @returns The latest active entry, or undefined if none
+   */
+  getLatestEntry(ruleId: string): LedgerEntry | undefined {
+    const entries = this.getEntriesForRule(ruleId);
+    const activeEntries = entries.filter((entry) => entry.status === 'active');
+
+    if (activeEntries.length === 0) {
+      return undefined;
+    }
+
+    // Return the most recent active entry
+    return activeEntries[activeEntries.length - 1];
+  }
+
+  /**
+   * Get all active assumptions across all entries.
+   *
+   * @returns Map of assumption ID to assumption
+   */
+  getActiveAssumptions(): Map<string, Assumption> {
+    const assumptions = new Map<string, Assumption>();
+
+    for (const entry of this.entries) {
+      // Get current status from map
+      const currentEntry = this.entryMap.get(entry.id)!;
+      if (currentEntry.status !== 'active') {
+        continue;
+      }
+
+      for (const assumption of currentEntry.contract.assumptions || []) {
+        if (assumption.status === 'active') {
+          assumptions.set(assumption.id, assumption);
+        }
+      }
+    }
+
+    return assumptions;
+  }
+
+  /**
+   * Find assumptions that impact a specific artifact type.
+   *
+   * @param impactType The artifact type ('spec', 'tests', 'code')
+   * @returns Array of assumptions
+   */
+  findAssumptionsByImpact(impactType: 'spec' | 'tests' | 'code'): Assumption[] {
+    const assumptions: Assumption[] = [];
+
+    for (const entry of this.entries) {
+      // Get current status from map
+      const currentEntry = this.entryMap.get(entry.id)!;
+      if (currentEntry.status !== 'active') {
+        continue;
+      }
+
+      for (const assumption of currentEntry.contract.assumptions || []) {
+        if (assumption.status === 'active' && assumption.impacts.includes(impactType)) {
+          assumptions.push(assumption);
+        }
+      }
+    }
+
+    return assumptions;
+  }
+
+  /**
+   * Get ledger statistics.
+   */
+  getStats(): {
+    totalEntries: number;
+    activeEntries: number;
+    supersededEntries: number;
+    deprecatedEntries: number;
+    uniqueRules: number;
+  } {
+    // Get current status from map for all entries
+    const currentEntries = this.entries.map((e) => this.entryMap.get(e.id)!);
+    const active = currentEntries.filter((e) => e.status === 'active').length;
+    const superseded = currentEntries.filter((e) => e.status === 'superseded').length;
+    const deprecated = currentEntries.filter((e) => e.status === 'deprecated').length;
+    const uniqueRules = new Set(currentEntries.map((e) => e.contract.ruleId)).size;
+
+    return {
+      totalEntries: this.entries.length,
+      activeEntries: active,
+      supersededEntries: superseded,
+      deprecatedEntries: deprecated,
+      uniqueRules,
+    };
+  }
+
+  /**
+   * Export ledger as JSON.
+   *
+   * @returns JSON string with current entry status
+   */
+  toJSON(): string {
+    return JSON.stringify(
+      {
+        version: '1.0.0',
+        // Export entries with current status from the map
+        entries: this.entries.map((entry) => this.entryMap.get(entry.id)!),
+        stats: this.getStats(),
+      },
+      null,
+      2
+    );
+  }
+
+  /**
+   * Import ledger from JSON.
+   * 
+   * Note: The JSON must contain entries in the order they were originally appended.
+   * If a superseding entry appears before the entry it supersedes, the superseding
+   * logic will not work correctly. The toJSON method preserves this order.
+   *
+   * @param json The JSON string
+   * @returns A new BehaviorLedger instance
+   */
+  static fromJSON(json: string): BehaviorLedger {
+    const data = JSON.parse(json);
+    const ledger = new BehaviorLedger();
+
+    for (const entry of data.entries || []) {
+      ledger.append(entry);
+    }
+
+    return ledger;
+  }
+}
+
+/**
+ * Create a new behavior ledger.
+ *
+ * @returns A new empty ledger
+ */
+export function createBehaviorLedger(): BehaviorLedger {
+  return new BehaviorLedger();
+}

package/src/decision-ledger/logic-ledger.ts

@@ -0,0 +1,158 @@
+/**
+ * Decision Ledger - Logic Ledger Writer
+ *
+ * Immutable, append-only ledger persisted to disk with index and LATEST snapshots.
+ */
+
+import { createHash } from 'node:crypto';
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import type { Contract, Assumption } from './types.js';
+
+export interface LogicLedgerEntry {
+  ruleId: string;
+  version: number;
+  timestamp: string;
+  canonicalBehavior: {
+    behavior: string;
+    examples: Contract['examples'];
+    invariants: string[];
+  };
+  assumptions: Assumption[];
+  artifacts: {
+    contractPresent: boolean;
+    testsPresent: boolean;
+    specPresent: boolean;
+  };
+  drift: {
+    changeSummary: string;
+    assumptionsInvalidated: string[];
+    assumptionsRevised: string[];
+    conflicts: string[];
+  };
+}
+
+export interface LogicLedgerWriteOptions {
+  rootDir: string;
+  author: string;
+  testsPresent?: boolean;
+  specPresent?: boolean;
+}
+
+export interface LogicLedgerIndex {
+  byRuleId: Record<string, string>;
+}
+
+export async function writeLogicLedgerEntry(
+  contract: Contract,
+  options: LogicLedgerWriteOptions
+): Promise<LogicLedgerEntry> {
+  const rootDir = options.rootDir;
+  const ledgerId = normalizeRuleId(contract.ruleId);
+  const ledgerDir = path.join(rootDir, 'logic-ledger', ledgerId);
+  await fs.mkdir(ledgerDir, { recursive: true });
+
+  const latestPath = path.join(ledgerDir, 'LATEST.json');
+  const latest = await readJson<LogicLedgerEntry | null>(latestPath, null);
+  const nextVersion = latest ? latest.version + 1 : 1;
+
+  const entry: LogicLedgerEntry = {
+    ruleId: contract.ruleId,
+    version: nextVersion,
+    timestamp: new Date().toISOString(),
+    canonicalBehavior: {
+      behavior: contract.behavior,
+      examples: contract.examples,
+      invariants: contract.invariants,
+    },
+    assumptions: contract.assumptions ?? [],
+    artifacts: {
+      contractPresent: true,
+      testsPresent: options.testsPresent ?? false,
+      specPresent: options.specPresent ?? false,
+    },
+    drift: computeDrift(latest, contract),
+  };
+
+  const versionFile = path.join(ledgerDir, `v${String(nextVersion).padStart(4, '0')}.json`);
+  await fs.writeFile(versionFile, JSON.stringify(entry, null, 2));
+  await fs.writeFile(latestPath, JSON.stringify(entry, null, 2));
+
+  await updateIndex(rootDir, contract.ruleId, path.relative(rootDir, ledgerDir));
+
+  return entry;
+}
+
+function computeDrift(previous: LogicLedgerEntry | null, contract: Contract): LogicLedgerEntry['drift'] {
+  if (!previous) {
+    return {
+      changeSummary: 'initial',
+      assumptionsInvalidated: [],
+      assumptionsRevised: [],
+      conflicts: [],
+    };
+  }
+
+  const conflicts: string[] = [];
+  const previousBehavior = JSON.stringify(previous.canonicalBehavior);
+  const nextBehavior = JSON.stringify({
+    behavior: contract.behavior,
+    examples: contract.examples,
+    invariants: contract.invariants,
+  });
+
+  if (previousBehavior !== nextBehavior) {
+    conflicts.push('behavior-changed');
+  }
+
+  const prevAssumptions = new Map(previous.assumptions.map((a) => [a.id, a]));
+  const assumptionsInvalidated: string[] = [];
+  const assumptionsRevised: string[] = [];
+
+  for (const assumption of contract.assumptions ?? []) {
+    const prior = prevAssumptions.get(assumption.id);
+    if (!prior) {
+      continue;
+    }
+
+    if (prior.statement !== assumption.statement || prior.status !== assumption.status) {
+      assumptionsRevised.push(assumption.id);
+    }
+  }
+
+  for (const prior of previous.assumptions) {
+    const current = (contract.assumptions ?? []).find((a) => a.id === prior.id);
+    if (!current || current.status === 'invalidated') {
+      assumptionsInvalidated.push(prior.id);
+    }
+  }
+
+  return {
+    changeSummary: conflicts.length > 0 ? 'updated' : 'no-change',
+    assumptionsInvalidated,
+    assumptionsRevised,
+    conflicts,
+  };
+}
+
+async function updateIndex(rootDir: string, ruleId: string, ledgerDir: string): Promise<void> {
+  const indexPath = path.join(rootDir, 'logic-ledger', 'index.json');
+  const index = await readJson<LogicLedgerIndex>(indexPath, { byRuleId: {} });
+  index.byRuleId[ruleId] = ledgerDir.replace(/\\/g, '/');
+  await fs.mkdir(path.dirname(indexPath), { recursive: true });
+  await fs.writeFile(indexPath, JSON.stringify(index, null, 2));
+}
+
+function normalizeRuleId(ruleId: string): string {
+  const hash = createHash('sha256').update(ruleId).digest('hex').slice(0, 6);
+  return `${ruleId.replace(/[^a-zA-Z0-9_-]/g, '-')}-${hash}`.toLowerCase();
+}
+
+async function readJson<T>(filePath: string, fallback: T): Promise<T> {
+  try {
+    const data = await fs.readFile(filePath, 'utf-8');
+    return JSON.parse(data) as T;
+  } catch {
+    return fallback;
+  }
+}