aether-colony 1.1.0

package/bin/lib/state-guard.js

@@ -0,0 +1,602 @@
+#!/usr/bin/env node
+/**
+ * State Guard Module
+ *
+ * Enforces the Iron Law: phase advancement requires fresh verification evidence.
+ * Provides StateGuard class with idempotency checks, file locking, and structured errors.
+ *
+ * @module bin/lib/state-guard
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { EventTypes, createEvent } = require('./event-types');
+
+/**
+ * Error codes for StateGuard errors
+ */
+const StateGuardErrorCodes = {
+  E_IRON_LAW_VIOLATION: 'E_IRON_LAW_VIOLATION',
+  E_IDEMPOTENCY_CHECK: 'E_IDEMPOTENCY_CHECK',
+  E_LOCK_TIMEOUT: 'E_LOCK_TIMEOUT',
+  E_INVALID_TRANSITION: 'E_INVALID_TRANSITION',
+  E_STATE_NOT_FOUND: 'E_STATE_NOT_FOUND',
+  E_STATE_INVALID: 'E_STATE_INVALID',
+};
+
+/**
+ * StateGuardError - Structured error for state guard violations
+ */
+class StateGuardError extends Error {
+  /**
+   * @param {string} code - Error code from StateGuardErrorCodes
+   * @param {string} message - Human-readable error message
+   * @param {object} details - Additional error context
+   * @param {string|null} recovery - Recovery suggestion for user
+   */
+  constructor(code, message, details = {}, recovery = null) {
+    super(message);
+    this.name = 'StateGuardError';
+    this.code = code;
+    this.details = details;
+    this.recovery = recovery;
+    this.timestamp = new Date().toISOString();
+
+    // Maintain proper stack trace in V8 environments
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, StateGuardError);
+    }
+  }
+
+  /**
+   * Convert error to structured JSON object
+   * @returns {object} Structured error representation
+   */
+  toJSON() {
+    return {
+      error: {
+        name: this.name,
+        code: this.code,
+        message: this.message,
+        details: this.details,
+        recovery: this.recovery,
+        timestamp: this.timestamp,
+      },
+    };
+  }
+
+  /**
+   * Convert error to string for console output
+   * @returns {string} Formatted error string
+   */
+  toString() {
+    let str = `${this.code}: ${this.message}`;
+    if (this.recovery) {
+      str += `\n  Recovery: ${this.recovery}`;
+    }
+    return str;
+  }
+}
+
+/**
+ * FileLock - PID-based file locking with stale lock detection
+ */
+class FileLock {
+  /**
+   * @param {string} lockDir - Directory for lock files (default: .aether/locks)
+   * @param {object} options - Lock configuration options
+   */
+  constructor(lockDir = '.aether/locks', options = {}) {
+    this.lockDir = lockDir;
+    this.lockTimeout = options.lockTimeout || 300000; // 5 minutes
+    this.retryInterval = options.retryInterval || 500;  // 500ms
+    this.maxRetries = options.maxRetries || 100;     // 50 seconds max wait
+    this.currentLock = null;
+    this.currentPidFile = null;
+  }
+
+  /**
+   * Acquire lock on a file
+   * @param {string} filePath - Path to file to lock
+   * @returns {Promise<boolean>} True if lock acquired, false otherwise
+   */
+  async acquire(filePath) {
+    const lockFile = path.join(this.lockDir, `${path.basename(filePath)}.lock`);
+    const pidFile = `${lockFile}.pid`;
+
+    // Ensure lock directory exists
+    if (!fs.existsSync(this.lockDir)) {
+      fs.mkdirSync(this.lockDir, { recursive: true });
+    }
+
+    // Check for stale lock
+    if (fs.existsSync(lockFile)) {
+      const lockPid = this.readPidFile(pidFile);
+      if (lockPid && !this.isProcessRunning(lockPid)) {
+        console.log(`Lock stale (PID ${lockPid} not running), cleaning up...`);
+        this.cleanupLock(lockFile, pidFile);
+      }
+    }
+
+    // Try to acquire with retry
+    for (let retry = 0; retry < this.maxRetries; retry++) {
+      try {
+        // Atomic lock creation using exclusive flag
+        const fd = fs.openSync(lockFile, 'wx');
+        fs.writeSync(fd, process.pid.toString());
+        fs.closeSync(fd);
+
+        // Write PID file
+        fs.writeFileSync(pidFile, process.pid.toString());
+
+        this.currentLock = lockFile;
+        this.currentPidFile = pidFile;
+        return true;
+      } catch (err) {
+        if (err.code !== 'EEXIST') throw err;
+
+        // Wait before retry
+        if (retry < this.maxRetries - 1) {
+          await this.sleep(this.retryInterval);
+        }
+      }
+    }
+
+    return false;
+  }
+
+  /**
+   * Release the current lock
+   */
+  release() {
+    if (this.currentLock) {
+      this.cleanupLock(this.currentLock, this.currentPidFile);
+      this.currentLock = null;
+      this.currentPidFile = null;
+    }
+  }
+
+  /**
+   * Check if a process is running
+   * @param {string} pid - Process ID to check
+   * @returns {boolean} True if process is running
+   */
+  isProcessRunning(pid) {
+    try {
+      process.kill(parseInt(pid), 0);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Read PID from PID file
+   * @param {string} pidFile - Path to PID file
+   * @returns {string|null} PID or null if file doesn't exist
+   */
+  readPidFile(pidFile) {
+    try {
+      return fs.readFileSync(pidFile, 'utf8').trim();
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Clean up lock files
+   * @param {string} lockFile - Path to lock file
+   * @param {string} pidFile - Path to PID file
+   */
+  cleanupLock(lockFile, pidFile) {
+    try { fs.unlinkSync(lockFile); } catch {}
+    try { fs.unlinkSync(pidFile); } catch {}
+  }
+
+  /**
+   * Sleep for specified milliseconds
+   * @param {number} ms - Milliseconds to sleep
+   * @returns {Promise<void>}
+   */
+  sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+  }
+}
+
+/**
+ * StateGuard - Enforces Iron Law and manages phase transitions
+ */
+class StateGuard {
+  /**
+   * @param {string} stateFilePath - Path to COLONY_STATE.json
+   * @param {object} options - Configuration options
+   */
+  constructor(stateFilePath, options = {}) {
+    this.stateFile = stateFilePath;
+    this.lock = options.lock || new FileLock(options.lockDir);
+    this.locked = false;
+    this.worker = options.worker || process.env.WORKER_NAME || 'state-guard';
+  }
+
+  /**
+   * Acquire lock on state file
+   * @returns {Promise<void>}
+   * @throws {StateGuardError} If lock cannot be acquired
+   */
+  async acquireLock() {
+    const acquired = await this.lock.acquire(this.stateFile);
+    if (!acquired) {
+      throw new StateGuardError(
+        StateGuardErrorCodes.E_LOCK_TIMEOUT,
+        `Could not acquire lock on ${this.stateFile} after ${this.lock.maxRetries} retries`,
+        { lockFile: `${this.stateFile}.lock`, maxRetries: this.lock.maxRetries },
+        'Check for stuck processes or manually remove stale lock file'
+      );
+    }
+    this.locked = true;
+  }
+
+  /**
+   * Release lock on state file
+   * Safe to call even if not locked
+   */
+  releaseLock() {
+    this.lock.release();
+    this.locked = false;
+  }
+
+  /**
+   * Load and parse state file
+   * @returns {object} Parsed state object
+   * @throws {StateGuardError} If file missing or invalid
+   */
+  loadState() {
+    // Check if file exists
+    if (!fs.existsSync(this.stateFile)) {
+      throw new StateGuardError(
+        StateGuardErrorCodes.E_STATE_NOT_FOUND,
+        `State file not found: ${this.stateFile}`,
+        { path: this.stateFile },
+        'Run: aether init'
+      );
+    }
+
+    // Read and parse
+    let content;
+    try {
+      content = fs.readFileSync(this.stateFile, 'utf8');
+    } catch (err) {
+      throw new StateGuardError(
+        StateGuardErrorCodes.E_STATE_INVALID,
+        `Failed to read state file: ${err.message}`,
+        { path: this.stateFile, error: err.message },
+        'Check file permissions and disk space'
+      );
+    }
+
+    let state;
+    try {
+      state = JSON.parse(content);
+    } catch (err) {
+      throw new StateGuardError(
+        StateGuardErrorCodes.E_STATE_INVALID,
+        `Invalid JSON in state file: ${err.message}`,
+        { path: this.stateFile, error: err.message },
+        'Restore from backup or reinitialize'
+      );
+    }
+
+    // Validate basic structure
+    if (!state.version || typeof state.current_phase !== 'number' || !Array.isArray(state.events)) {
+      throw new StateGuardError(
+        StateGuardErrorCodes.E_STATE_INVALID,
+        'State file missing required fields: version, current_phase, events',
+        { path: this.stateFile, hasVersion: !!state.version, hasPhase: typeof state.current_phase === 'number', hasEvents: Array.isArray(state.events) },
+        'Restore from backup or reinitialize'
+      );
+    }
+
+    return state;
+  }
+
+  /**
+   * Save state atomically (write to temp, then rename)
+   * @param {object} state - State object to save
+   */
+  saveState(state) {
+    // Update timestamp
+    state.last_updated = new Date().toISOString();
+
+    // Write to temp file first (atomic write)
+    const tempFile = `${this.stateFile}.tmp`;
+    fs.writeFileSync(tempFile, JSON.stringify(state, null, 2), 'utf8');
+
+    // Atomic rename
+    fs.renameSync(tempFile, this.stateFile);
+  }
+
+  /**
+   * Check if evidence has all required fields and is fresh
+   * @param {object} state - Current state object
+   * @param {number} phase - Phase number
+   * @param {object} evidence - Evidence object to validate
+   * @returns {boolean} True if evidence is fresh and valid
+   */
+  hasFreshEvidence(state, phase, evidence) {
+    // Evidence must be an object
+    if (!evidence || typeof evidence !== 'object') {
+      return false;
+    }
+
+    // Required fields
+    const requiredFields = ['checkpoint_hash', 'test_results', 'timestamp'];
+    for (const field of requiredFields) {
+      if (!(field in evidence)) {
+        return false;
+      }
+    }
+
+    // Validate timestamp is ISO 8601 format
+    const timestamp = new Date(evidence.timestamp);
+    if (isNaN(timestamp.getTime())) {
+      return false;
+    }
+
+    // Check evidence is fresh (after state initialization)
+    const stateInitTime = new Date(state.initialized_at || '1970-01-01T00:00:00Z');
+    if (timestamp <= stateInitTime) {
+      return false;
+    }
+
+    // Check evidence is from current session (not inherited)
+    // Evidence timestamp should be after state initialization
+    const evidenceAge = Date.now() - timestamp.getTime();
+    const sessionAge = Date.now() - stateInitTime.getTime();
+    if (evidenceAge > sessionAge) {
+      return false;
+    }
+
+    return true;
+  }
+
+  /**
+   * Enforce Iron Law: phase advancement requires fresh verification evidence
+   * @param {object} state - Current state object
+   * @param {number} phase - Phase number
+   * @param {object} evidence - Evidence object
+   * @throws {StateGuardError} If Iron Law is violated
+   */
+  enforceIronLaw(state, phase, evidence) {
+    if (!this.hasFreshEvidence(state, phase, evidence)) {
+      const requiredFields = ['checkpoint_hash', 'test_results', 'timestamp'];
+      const providedFields = evidence && typeof evidence === 'object' ? Object.keys(evidence) : [];
+      const missing = requiredFields.filter(f => !providedFields.includes(f));
+
+      throw new StateGuardError(
+        StateGuardErrorCodes.E_IRON_LAW_VIOLATION,
+        `Phase ${phase} advancement requires fresh verification evidence`,
+        {
+          phase,
+          missing,
+          provided: providedFields,
+          evidence_timestamp: evidence?.timestamp,
+          state_initialized_at: state.initialized_at
+        },
+        `Provide verification evidence: ${missing.length > 0 ? missing.join(', ') : 'fresh timestamp after state initialization'}`
+      );
+    }
+  }
+
+  /**
+   * Check idempotency - prevent rebuilding completed phases or skipping ahead
+   * @param {object} state - Current state object
+   * @param {number} fromPhase - Phase we're trying to advance from
+   * @returns {object} Result with canProceed flag and reason
+   */
+  checkIdempotency(state, fromPhase) {
+    const currentPhase = state.current_phase;
+
+    if (currentPhase > fromPhase) {
+      return {
+        canProceed: false,
+        reason: 'already_complete',
+        currentPhase: currentPhase,
+        message: `Phase ${fromPhase} already completed (currently at phase ${currentPhase})`
+      };
+    }
+
+    if (currentPhase < fromPhase) {
+      return {
+        canProceed: false,
+        reason: 'previous_incomplete',
+        currentPhase: currentPhase,
+        message: `Cannot advance from phase ${fromPhase} - currently at phase ${currentPhase} (previous phases incomplete)`
+      };
+    }
+
+    return { canProceed: true };
+  }
+
+  /**
+   * Validate phase transition is sequential
+   * @param {number} fromPhase - Current phase
+   * @param {number} toPhase - Target phase
+   * @throws {StateGuardError} If transition is invalid
+   */
+  validateTransition(fromPhase, toPhase) {
+    if (toPhase !== fromPhase + 1) {
+      throw new StateGuardError(
+        StateGuardErrorCodes.E_INVALID_TRANSITION,
+        `Invalid phase transition: ${fromPhase} -> ${toPhase}`,
+        { from: fromPhase, to: toPhase, expected: fromPhase + 1 },
+        'Phase transitions must be sequential (n -> n+1)'
+      );
+    }
+  }
+
+  /**
+   * Add an event to the state events array
+   * @param {object} state - Current state object
+   * @param {string} type - Event type from EventTypes
+   * @param {object} details - Event details
+   * @returns {object} The created event
+   */
+  addEvent(state, type, details = {}) {
+    // Ensure events array exists
+    if (!state.events) {
+      state.events = [];
+    }
+
+    // Create event using event-types helper
+    const event = createEvent(type, this.worker, details);
+
+    // Add to state events
+    state.events.push(event);
+
+    return event;
+  }
+
+  /**
+   * Transition state from one phase to another
+   * @param {object} state - Current state object
+   * @param {number} fromPhase - Current phase
+   * @param {number} toPhase - Target phase
+   * @param {object} evidence - Verification evidence
+   * @returns {object} Updated state object
+   */
+  transitionState(state, fromPhase, toPhase, evidence) {
+    // Update phase
+    state.current_phase = toPhase;
+
+    // Update last_updated timestamp
+    state.last_updated = new Date().toISOString();
+
+    // Add phase_transition event using addEvent method
+    this.addEvent(state, EventTypes.PHASE_TRANSITION, {
+      from: fromPhase,
+      to: toPhase,
+      evidence_id: evidence?.checkpoint_hash || null,
+      checkpoint_hash: evidence?.checkpoint_hash || null
+    });
+
+    return state;
+  }
+
+  /**
+   * Get events from state with optional filtering
+   * @param {object} state - State object containing events array
+   * @param {object} options - Filter options
+   * @param {string} [options.type] - Filter by event type
+   * @param {string} [options.since] - Filter events after this ISO 8601 timestamp
+   * @param {number} [options.limit] - Limit number of events returned (most recent first)
+   * @returns {object[]} Array of matching events
+   */
+  static getEvents(state, options = {}) {
+    if (!state || !Array.isArray(state.events)) {
+      return [];
+    }
+
+    let events = [...state.events];
+
+    // Filter by type
+    if (options.type) {
+      events = events.filter(e => e.type === options.type);
+    }
+
+    // Filter by timestamp (events after 'since')
+    if (options.since) {
+      const sinceDate = new Date(options.since);
+      if (!isNaN(sinceDate.getTime())) {
+        events = events.filter(e => new Date(e.timestamp) > sinceDate);
+      }
+    }
+
+    // Sort by timestamp descending (most recent first)
+    events.sort((a, b) => new Date(b.timestamp) - new Date(a.timestamp));
+
+    // Limit results
+    if (options.limit && options.limit > 0) {
+      events = events.slice(0, options.limit);
+    }
+
+    return events;
+  }
+
+  /**
+   * Get the most recent event of a specific type
+   * @param {object} state - State object containing events array
+   * @param {string} [type] - Optional event type to filter by
+   * @returns {object|null} Most recent event or null if none found
+   */
+  static getLatestEvent(state, type = null) {
+    const events = StateGuard.getEvents(state, { type, limit: 1 });
+    return events.length > 0 ? events[0] : null;
+  }
+
+  /**
+   * Advance phase with full guard enforcement
+   * @param {number} fromPhase - Current phase number
+   * @param {number} toPhase - Target phase number
+   * @param {object} evidence - Verification evidence
+   * @returns {Promise<object>} Result object with status
+   */
+  async advancePhase(fromPhase, toPhase, evidence) {
+    // Acquire lock
+    await this.acquireLock();
+
+    try {
+      // Load state
+      const state = this.loadState();
+
+      // Check idempotency (STATE-02)
+      const idempotency = this.checkIdempotency(state, fromPhase);
+      if (!idempotency.canProceed) {
+        if (idempotency.reason === 'already_complete') {
+          // Return success but indicate already complete
+          return {
+            status: 'already_complete',
+            from: fromPhase,
+            to: toPhase,
+            currentPhase: idempotency.currentPhase
+          };
+        }
+        // Previous incomplete - throw error
+        throw new StateGuardError(
+          StateGuardErrorCodes.E_IDEMPOTENCY_CHECK,
+          idempotency.message,
+          { reason: idempotency.reason, currentPhase: idempotency.currentPhase },
+          'Complete previous phases before advancing'
+        );
+      }
+
+      // Validate transition
+      this.validateTransition(fromPhase, toPhase);
+
+      // Enforce Iron Law (STATE-01)
+      this.enforceIronLaw(state, fromPhase, evidence);
+
+      // Transition state
+      const updatedState = this.transitionState(state, fromPhase, toPhase, evidence);
+
+      // Save state
+      this.saveState(updatedState);
+
+      return {
+        status: 'transitioned',
+        from: fromPhase,
+        to: toPhase
+      };
+
+    } finally {
+      // Always release lock
+      this.releaseLock();
+    }
+  }
+}
+
+module.exports = {
+  StateGuard,
+  StateGuardError,
+  StateGuardErrorCodes,
+  FileLock,
+};