/**
 * Centralized State Manager for Loki Mode - TypeScript Implementation
 *
 * Provides unified state management with:
 * - File-based caching with chokidar for change detection
 * - Thread-safe operations with file locking
 * - Event bus integration for broadcasting changes
 * - Subscription system for reactive updates
 * - Version history with rollback capability (SYN-015)
 */

import * as fs from "fs";
import * as path from "path";
import { EventEmitter } from "events";

// Try to import chokidar for file watching
let chokidar: typeof import("chokidar") | null = null;
try {
  chokidar = require("chokidar");
} catch {
  // chokidar not available
}

// Try to import event bus
let EventBus: typeof import("../events/bus").EventBus | null = null;
try {
  const eventBusModule = require("../events/bus");
  EventBus = eventBusModule.EventBus;
} catch {
  // Event bus not available
}

/**
 * Managed state files
 */
export const ManagedFile = {
  ORCHESTRATOR: "state/orchestrator.json",
  AUTONOMY: "autonomy-state.json",
  QUEUE_PENDING: "queue/pending.json",
  QUEUE_IN_PROGRESS: "queue/in-progress.json",
  QUEUE_COMPLETED: "queue/completed.json",
  QUEUE_FAILED: "queue/failed.json",
  QUEUE_CURRENT: "queue/current-task.json",
  MEMORY_INDEX: "memory/index.json",
  MEMORY_TIMELINE: "memory/timeline.json",
  DASHBOARD: "dashboard-state.json",
  AGENTS: "state/agents.json",
  RESOURCES: "state/resources.json",
} as const;

export type ManagedFileType = (typeof ManagedFile)[keyof typeof ManagedFile];

/**
 * State change event
 */
export interface StateChange {
  filePath: string;
  oldValue: Record<string, unknown> | null;
  newValue: Record<string, unknown>;
  timestamp: string;
  changeType: "create" | "update" | "delete";
  source: string;
}

/**
 * State change callback type
 */
export type StateCallback = (change: StateChange) => void;

/**
 * Disposable subscription
 */
export interface Disposable {
  dispose(): void;
}

/**
 * Cache entry type
 */
interface CacheEntry {
  data: Record<string, unknown>;
  hash: string;
  mtime: number;
}

/**
 * Default version retention limit (SYN-015)
 */
export const DEFAULT_VERSION_RETENTION = 10;

/**
 * State version data (SYN-015)
 */
export interface StateVersion {
  version: number;
  timestamp: string;
  data: Record<string, unknown>;
  source: string;
  changeType: string;
}

/**
 * Version info summary (without full data) (SYN-015)
 */
export interface VersionInfo {
  version: number;
  timestamp: string;
  source: string;
  changeType: string;
  dataHash: string;
}

/**
 * Subscription filter for selective notifications (SYN-016)
 */
export interface SubscriptionFilter {
  files?: (string | ManagedFileType)[];
  changeTypes?: ("create" | "update" | "delete")[];
}

/**
 * Notification channel interface (SYN-016)
 */
export interface NotificationChannel {
  notify(change: StateChange): void;
  close(): void;
}

/**
 * File-based notification channel for CLI/scripts
 */
export class FileNotificationChannel implements NotificationChannel {
  private notificationFile: string;

  constructor(notificationFile: string) {
    this.notificationFile = notificationFile;
    const dir = path.dirname(notificationFile);
    if (!fs.existsSync(dir)) {
      fs.mkdirSync(dir, { recursive: true });
    }
  }

  notify(change: StateChange): void {
    try {
      const notification = {
        timestamp: change.timestamp,
        filePath: change.filePath,
        changeType: change.changeType,
        source: change.source,
        diff: getStateDiff(change.oldValue, change.newValue),
      };
      fs.appendFileSync(this.notificationFile, JSON.stringify(notification) + "\n");
    } catch {
      // File notification errors shouldn't break state management
    }
  }

  close(): void {
    // No cleanup needed for file channel
  }
}

/**
 * In-memory notification channel for testing
 */
export class InMemoryNotificationChannel implements NotificationChannel {
  public notifications: Array<{
    timestamp: string;
    filePath: string;
    changeType: string;
    source: string;
    oldValue: Record<string, unknown> | null;
    newValue: Record<string, unknown>;
    diff: ReturnType<typeof getStateDiff>;
  }> = [];
  private maxSize: number;

  constructor(maxSize: number = 1000) {
    this.maxSize = maxSize;
  }

  notify(change: StateChange): void {
    const notification = {
      timestamp: change.timestamp,
      filePath: change.filePath,
      changeType: change.changeType,
      source: change.source,
      oldValue: change.oldValue,
      newValue: change.newValue,
      diff: getStateDiff(change.oldValue, change.newValue),
    };
    this.notifications.push(notification);
    if (this.notifications.length > this.maxSize) {
      this.notifications = this.notifications.slice(-this.maxSize);
    }
  }

  getNotifications(): typeof this.notifications {
    return [...this.notifications];
  }

  clear(): void {
    this.notifications = [];
  }

  close(): void {
    this.notifications = [];
  }
}

/**
 * Filtered subscriber entry
 */
interface FilteredSubscriber {
  callback: StateCallback;
  filter: SubscriptionFilter;
}

// -------------------------------------------------------------------------
// Optimistic Updates Types (SYN-014)
// -------------------------------------------------------------------------

/**
 * Conflict resolution strategies for optimistic updates
 */
export enum ConflictStrategy {
  LAST_WRITE_WINS = "last_write_wins",  // Default: latest write overwrites
  MERGE = "merge",                       // Merge compatible changes
  REJECT = "reject",                     // Reject and notify caller
}

/**
 * Version vector for tracking state versions per source
 */
export class VersionVector {
  private versions: Map<string, number>;

  constructor(data?: Record<string, number>) {
    this.versions = new Map(Object.entries(data || {}));
  }

  /**
   * Increment version for a source
   */
  increment(source: string): void {
    this.versions.set(source, (this.versions.get(source) || 0) + 1);
  }

  /**
   * Get version for a source
   */
  get(source: string): number {
    return this.versions.get(source) || 0;
  }

  /**
   * Merge two version vectors (take max of each)
   */
  merge(other: VersionVector): VersionVector {
    const merged = new VersionVector();
    const allSources = new Set([...this.versions.keys(), ...other.versions.keys()]);
    for (const source of allSources) {
      merged.versions.set(source, Math.max(this.get(source), other.get(source)));
    }
    return merged;
  }

  /**
   * Check if this vector dominates (is causally after) another
   */
  dominates(other: VersionVector): boolean {
    // Check if any source in other has a greater version
    for (const [source, version] of other.versions) {
      if (this.get(source) < version) {
        return false;
      }
    }
    // Must have at least one greater version
    for (const [source, version] of this.versions) {
      if (version > other.get(source)) {
        return true;
      }
    }
    return false;
  }

  /**
   * Check if two vectors are concurrent (neither dominates)
   */
  concurrentWith(other: VersionVector): boolean {
    return !this.dominates(other) && !other.dominates(this);
  }

  /**
   * Convert to plain object
   */
  toDict(): Record<string, number> {
    return Object.fromEntries(this.versions);
  }

  /**
   * Create from plain object
   */
  static fromDict(data: Record<string, number>): VersionVector {
    return new VersionVector(data);
  }
}

/**
 * Pending optimistic update
 */
export interface PendingUpdate {
  id: string;
  key: string;
  value: unknown;
  source: string;
  timestamp: string;
  versionVector: VersionVector;
  status: "pending" | "committed" | "rejected";
}

/**
 * Information about a detected conflict
 */
export interface ConflictInfo {
  key: string;
  localValue: unknown;
  remoteValue: unknown;
  localSource: string;
  remoteSource: string;
  localVersion: VersionVector;
  remoteVersion: VersionVector;
  resolution?: string;
  resolvedValue?: unknown;
}

/**
 * Compute MD5-like hash of data
 */
function computeHash(data: Record<string, unknown>): string {
  const content = JSON.stringify(data, Object.keys(data).sort());
  let hash = 0;
  for (let i = 0; i < content.length; i++) {
    const char = content.charCodeAt(i);
    hash = ((hash << 5) - hash) + char;
    hash = hash & hash;
  }
  return hash.toString(16);
}

/**
 * Get diff between old and new values
 */
export function getStateDiff(
  oldValue: Record<string, unknown> | null,
  newValue: Record<string, unknown>
): { added: Record<string, unknown>; removed: Record<string, unknown>; changed: Record<string, unknown> } {
  if (oldValue === null) {
    return { added: newValue, removed: {}, changed: {} };
  }

  const diff: { added: Record<string, unknown>; removed: Record<string, unknown>; changed: Record<string, unknown> } = {
    added: {},
    removed: {},
    changed: {},
  };

  const oldKeys = new Set(Object.keys(oldValue));
  const newKeys = new Set(Object.keys(newValue));

  // Added keys
  for (const key of newKeys) {
    if (!oldKeys.has(key)) {
      diff.added[key] = newValue[key];
    }
  }

  // Removed keys
  for (const key of oldKeys) {
    if (!newKeys.has(key)) {
      diff.removed[key] = oldValue[key];
    }
  }

  // Changed keys
  for (const key of oldKeys) {
    if (newKeys.has(key) && JSON.stringify(oldValue[key]) !== JSON.stringify(newValue[key])) {
      diff.changed[key] = {
        old: oldValue[key],
        new: newValue[key],
      };
    }
  }

  return diff;
}

/**
 * Centralized State Manager
 */
export class StateManager extends EventEmitter {
  private lokiDir: string;
  private cache: Map<string, CacheEntry>;
  private subscribers: Set<StateCallback>;
  private filteredSubscribers: FilteredSubscriber[];
  private notificationChannels: NotificationChannel[];
  private watcher: ReturnType<typeof import("chokidar").watch> | null;
  private eventBus: InstanceType<typeof import("../events/bus.ts").EventBus> | null;
  private enableWatch: boolean;
  private enableEvents: boolean;

  // Optimistic updates tracking (SYN-014)
  private pendingUpdates: Map<string, PendingUpdate[]>;
  private versionVectors: Map<string, VersionVector>;
  private conflictStrategy: ConflictStrategy;

  // State versioning (SYN-015)
  private enableVersioning: boolean;
  private versionRetention: number;
  private versionCounters: Map<string, number>;

  constructor(options: {
    lokiDir?: string;
    enableWatch?: boolean;
    enableEvents?: boolean;
    enableVersioning?: boolean;
    versionRetention?: number;
  } = {}) {
    super();

    this.lokiDir = options.lokiDir || ".loki";
    this.enableWatch = options.enableWatch !== false && chokidar !== null;
    this.enableEvents = options.enableEvents !== false && EventBus !== null;
    this.enableVersioning = options.enableVersioning !== false;
    this.versionRetention = options.versionRetention ?? DEFAULT_VERSION_RETENTION;
    this.cache = new Map();
    this.subscribers = new Set();
    this.filteredSubscribers = [];
    this.notificationChannels = [];
    this.watcher = null;
    this.eventBus = null;

    // Initialize optimistic update tracking (SYN-014)
    this.pendingUpdates = new Map();
    this.versionVectors = new Map();
    this.conflictStrategy = ConflictStrategy.LAST_WRITE_WINS;

    // Initialize version counters (SYN-015)
    this.versionCounters = new Map();

    // Ensure directories exist
    this.ensureDirectories();

    // Start file watching
    if (this.enableWatch) {
      this.startWatching();
    }

    // Initialize event bus
    if (this.enableEvents && EventBus) {
      this.eventBus = new EventBus(this.lokiDir);
    }
  }

  /**
   * Ensure all required directories exist
   */
  private ensureDirectories(): void {
    const directories = [
      this.lokiDir,
      path.join(this.lokiDir, "state"),
      path.join(this.lokiDir, "state", "history"),  // Version history (SYN-015)
      path.join(this.lokiDir, "queue"),
      path.join(this.lokiDir, "memory"),
      path.join(this.lokiDir, "events"),
    ];

    for (const dir of directories) {
      if (!fs.existsSync(dir)) {
        fs.mkdirSync(dir, { recursive: true });
      }
    }
  }

  /**
   * Start file system watcher
   */
  private startWatching(): void {
    if (!chokidar) {
      return;
    }

    this.watcher = chokidar.watch(this.lokiDir, {
      persistent: true,
      ignoreInitial: true,
      ignored: [
        /(^|[/\\])\../, // dot files
        /\.lock$/,       // lock files
        /\.tmp_/,        // temp files
      ],
      depth: 3,
    });

    this.watcher.on("change", (filePath: string) => {
      this.onFileChanged(filePath);
    });

    this.watcher.on("add", (filePath: string) => {
      this.onFileChanged(filePath);
    });
  }

  /**
   * Stop the state manager
   */
  stop(): void {
    if (this.watcher) {
      this.watcher.close();
      this.watcher = null;
    }
    this.cache.clear();
    this.subscribers.clear();
    this.filteredSubscribers = [];

    // Close all notification channels
    for (const channel of this.notificationChannels) {
      try {
        channel.close();
      } catch {
        // Ignore close errors
      }
    }
    this.notificationChannels = [];

    this.removeAllListeners();
  }

  /**
   * Resolve file reference to absolute path
   */
  private resolvePath(fileRef: string | ManagedFileType): string {
    return path.join(this.lokiDir, fileRef);
  }

  /**
   * Read JSON file
   */
  private readFile(filePath: string): Record<string, unknown> | null {
    try {
      if (!fs.existsSync(filePath)) {
        return null;
      }
      const content = fs.readFileSync(filePath, "utf-8");
      return JSON.parse(content);
    } catch (err) {
      // Log error for debugging (corrupted JSON, empty files, etc.)
      console.error(`[StateManager] Error reading file ${filePath}:`, err instanceof Error ? err.message : String(err));
      return null;
    }
  }

  /**
   * Write JSON file atomically
   */
  private writeFile(filePath: string, data: Record<string, unknown>): void {
    const dir = path.dirname(filePath);
    if (!fs.existsSync(dir)) {
      fs.mkdirSync(dir, { recursive: true });
    }

    // Write to temp file first
    const tempPath = path.join(dir, `.tmp_${Date.now()}_${Math.random().toString(36).slice(2)}.json`);

    try {
      fs.writeFileSync(tempPath, JSON.stringify(data, null, 2));
      // Atomic rename
      fs.renameSync(tempPath, filePath);
    } catch (err) {
      // Clean up temp file on error
      if (fs.existsSync(tempPath)) {
        fs.unlinkSync(tempPath);
      }
      throw err;
    }
  }

  /**
   * Get from cache if valid
   */
  private getFromCache(filePath: string): Record<string, unknown> | null {
    const entry = this.cache.get(filePath);
    if (!entry) {
      return null;
    }

    // Check if file still exists and mtime matches
    try {
      const stats = fs.statSync(filePath);
      if (stats.mtimeMs === entry.mtime) {
        return entry.data;
      }
    } catch {
      // File doesn't exist
    }

    return null;
  }

  /**
   * Put in cache
   */
  private putInCache(filePath: string, data: Record<string, unknown>): void {
    try {
      const stats = fs.statSync(filePath);
      this.cache.set(filePath, {
        data,
        hash: computeHash(data),
        mtime: stats.mtimeMs,
      });
    } catch {
      // Can't cache without stats
    }
  }

  /**
   * Invalidate cache entry
   */
  private invalidateCache(filePath: string): void {
    this.cache.delete(filePath);
  }

  /**
   * Get state from a managed file
   */
  getState(
    fileRef: string | ManagedFileType,
    defaultValue: Record<string, unknown> | null = null
  ): Record<string, unknown> | null {
    const filePath = this.resolvePath(fileRef);

    // Try cache first
    const cached = this.getFromCache(filePath);
    if (cached !== null) {
      return cached;
    }

    // Read from file
    const data = this.readFile(filePath);
    if (data === null) {
      return defaultValue;
    }

    // Update cache
    this.putInCache(filePath, data);

    return data;
  }

  /**
   * Set state in a managed file
   */
  setState(
    fileRef: string | ManagedFileType,
    data: Record<string, unknown>,
    source: string = "state-manager",
    saveVersion: boolean = true
  ): StateChange {
    const filePath = this.resolvePath(fileRef);
    const relPath = typeof fileRef === "string" ? fileRef : fileRef;

    // Get old value for change tracking
    const oldValue = this.getState(fileRef);

    // Determine change type
    const changeType = oldValue === null ? "create" : "update";

    // Save version before writing new data (SYN-015)
    if (this.enableVersioning && saveVersion && oldValue !== null) {
      this.saveVersion(fileRef, oldValue, source, changeType);
    }

    // Write to file
    this.writeFile(filePath, data);

    // Update cache
    this.putInCache(filePath, data);

    // Create change object
    const change: StateChange = {
      filePath: relPath,
      oldValue,
      newValue: data,
      timestamp: new Date().toISOString(),
      changeType,
      source,
    };

    // Broadcast change
    this.broadcast(change);

    return change;
  }

  /**
   * Merge updates into existing state
   */
  updateState(
    fileRef: string | ManagedFileType,
    updates: Record<string, unknown>,
    source: string = "state-manager"
  ): StateChange {
    const current = this.getState(fileRef, {});
    const merged = { ...current, ...updates };
    return this.setState(fileRef, merged, source);
  }

  /**
   * Acquire a simple file lock using a lock file
   */
  private acquireLock(filePath: string): { release: () => void } {
    const lockPath = `${filePath}.lock`;
    const lockDir = path.dirname(lockPath);

    if (!fs.existsSync(lockDir)) {
      fs.mkdirSync(lockDir, { recursive: true });
    }

    // Simple lock implementation using exclusive file creation
    let fd: number;
    const maxRetries = 50;
    const retryDelayMs = 100;

    for (let i = 0; i < maxRetries; i++) {
      try {
        fd = fs.openSync(lockPath, fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_WRONLY);
        fs.writeSync(fd, String(process.pid));
        fs.closeSync(fd);

        return {
          release: () => {
            try {
              fs.unlinkSync(lockPath);
            } catch {
              // Lock file may already be removed
            }
          },
        };
      } catch {
        // Lock exists, wait and retry
        if (i < maxRetries - 1) {
          const start = Date.now();
          while (Date.now() - start < retryDelayMs) {
            // Busy wait for a short time
          }
        }
      }
    }

    // Timeout - force acquire lock by removing stale lock
    try {
      fs.unlinkSync(lockPath);
    } catch {
      // Ignore
    }

    fd = fs.openSync(lockPath, fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_WRONLY);
    fs.writeSync(fd, String(process.pid));
    fs.closeSync(fd);

    return {
      release: () => {
        try {
          fs.unlinkSync(lockPath);
        } catch {
          // Lock file may already be removed
        }
      },
    };
  }

  /**
   * Delete a managed state file
   */
  deleteState(
    fileRef: string | ManagedFileType,
    source: string = "state-manager"
  ): StateChange | null {
    const filePath = this.resolvePath(fileRef);
    const relPath = typeof fileRef === "string" ? fileRef : fileRef;

    if (!fs.existsSync(filePath)) {
      return null;
    }

    const oldValue = this.getState(fileRef);

    // Acquire lock before deletion
    const lock = this.acquireLock(filePath);
    try {
      fs.unlinkSync(filePath);
    } finally {
      lock.release();
    }

    // Invalidate cache
    this.invalidateCache(filePath);

    // Create change object
    const change: StateChange = {
      filePath: relPath,
      oldValue,
      newValue: {},
      timestamp: new Date().toISOString(),
      changeType: "delete",
      source,
    };

    // Broadcast change
    this.broadcast(change);

    return change;
  }

  /**
   * Subscribe to state changes with optional filtering
   */
  subscribe(
    callback: StateCallback,
    fileFilter?: (string | ManagedFileType)[],
    changeTypes?: ("create" | "update" | "delete")[]
  ): Disposable {
    // If any filter is specified, use filtered subscribers
    if (fileFilter || changeTypes) {
      const filter: SubscriptionFilter = {
        files: fileFilter,
        changeTypes: changeTypes,
      };
      this.filteredSubscribers.push({ callback, filter });

      return {
        dispose: () => {
          this.filteredSubscribers = this.filteredSubscribers.filter(
            (sub) => sub.callback !== callback
          );
        },
      };
    }

    // No filter, use simple subscriber set
    this.subscribers.add(callback);

    return {
      dispose: () => {
        this.subscribers.delete(callback);
      },
    };
  }

  /**
   * Subscribe with a SubscriptionFilter object
   */
  subscribeFiltered(callback: StateCallback, filter: SubscriptionFilter): Disposable {
    this.filteredSubscribers.push({ callback, filter });

    return {
      dispose: () => {
        this.filteredSubscribers = this.filteredSubscribers.filter(
          (sub) => sub.callback !== callback
        );
      },
    };
  }

  /**
   * Add a notification channel for state changes
   */
  addNotificationChannel(channel: NotificationChannel): Disposable {
    this.notificationChannels.push(channel);

    return {
      dispose: () => {
        const index = this.notificationChannels.indexOf(channel);
        if (index >= 0) {
          this.notificationChannels.splice(index, 1);
          channel.close();
        }
      },
    };
  }

  /**
   * Check if a change matches a subscription filter
   */
  private matchesFilter(change: StateChange, filter: SubscriptionFilter): boolean {
    // Check file filter
    if (filter.files && filter.files.length > 0) {
      const filterPaths = new Set(filter.files);
      if (!filterPaths.has(change.filePath)) {
        return false;
      }
    }

    // Check change type filter
    if (filter.changeTypes && filter.changeTypes.length > 0) {
      if (!filter.changeTypes.includes(change.changeType)) {
        return false;
      }
    }

    return true;
  }

  /**
   * Notify all internal subscribers
   */
  private notifySubscribers(change: StateChange): void {
    // Notify simple subscribers (no filter)
    for (const callback of this.subscribers) {
      try {
        callback(change);
      } catch {
        // Don't let one callback break others
      }
    }

    // Notify filtered subscribers
    for (const { callback, filter } of this.filteredSubscribers) {
      try {
        if (this.matchesFilter(change, filter)) {
          callback(change);
        }
      } catch {
        // Don't let one callback break others
      }
    }
  }

  /**
   * Emit state change event to the event bus
   */
  private emitStateEvent(change: StateChange): void {
    if (!this.eventBus || !this.enableEvents) {
      return;
    }

    try {
      this.eventBus.emitSimple("state", "runner", "state_changed", {
        filePath: change.filePath,
        changeType: change.changeType,
        sourceComponent: change.source,
        timestamp: change.timestamp,
        diff: getStateDiff(change.oldValue, change.newValue),
      });
    } catch {
      // Event bus errors shouldn't break state management
    }
  }

  /**
   * Notify all notification channels
   */
  private notifyChannels(change: StateChange): void {
    for (const channel of this.notificationChannels) {
      try {
        channel.notify(change);
      } catch {
        // Channel errors shouldn't break state management
      }
    }
  }

  /**
   * Broadcast a state change to all subscribers and channels
   *
   * This is the main notification method that:
   * 1. Notifies internal callback subscribers
   * 2. Emits events to the event bus
   * 3. Emits "change" event (EventEmitter)
   * 4. Sends notifications to all registered channels
   */
  private broadcast(change: StateChange): void {
    // 1. Notify internal subscribers
    this.notifySubscribers(change);

    // 2. Emit to event bus
    this.emitStateEvent(change);

    // 3. Emit EventEmitter event
    this.emit("change", change);

    // 4. Notify notification channels
    this.notifyChannels(change);
  }

  /**
   * Handle file change detected by watcher
   */
  private onFileChanged(filePath: string): void {
    // Only handle JSON files
    if (!filePath.endsWith(".json")) {
      return;
    }

    // Ignore lock files and temp files
    if (filePath.includes(".lock") || filePath.includes(".tmp_")) {
      return;
    }

    // Invalidate cache
    this.invalidateCache(filePath);

    // Read new value
    let newValue: Record<string, unknown> | null;
    try {
      newValue = this.readFile(filePath);
    } catch {
      return;
    }

    if (newValue === null) {
      return;
    }

    // Get old value from cache (if available)
    const oldEntry = this.cache.get(filePath);
    const oldValue = oldEntry ? oldEntry.data : null;

    // Update cache
    this.putInCache(filePath, newValue);

    // Create relative path
    let relPath: string;
    try {
      relPath = path.relative(this.lokiDir, filePath);
    } catch {
      relPath = filePath;
    }

    // Create and broadcast change
    const change: StateChange = {
      filePath: relPath,
      oldValue,
      newValue,
      timestamp: new Date().toISOString(),
      changeType: "update",
      source: "external",
    };

    this.broadcast(change);
  }

  // -------------------------------------------------------------------------
  // Convenience Methods
  // -------------------------------------------------------------------------

  /**
   * Get orchestrator state
   */
  getOrchestratorState(): Record<string, unknown> | null {
    return this.getState(ManagedFile.ORCHESTRATOR);
  }

  /**
   * Get autonomy state
   */
  getAutonomyState(): Record<string, unknown> | null {
    return this.getState(ManagedFile.AUTONOMY);
  }

  /**
   * Get queue state by type
   */
  getQueueState(queueType: string = "pending"): Record<string, unknown> | null {
    const queueMap: Record<string, ManagedFileType> = {
      pending: ManagedFile.QUEUE_PENDING,
      "in-progress": ManagedFile.QUEUE_IN_PROGRESS,
      completed: ManagedFile.QUEUE_COMPLETED,
      failed: ManagedFile.QUEUE_FAILED,
      current: ManagedFile.QUEUE_CURRENT,
    };
    const fileRef = queueMap[queueType] || ManagedFile.QUEUE_PENDING;
    return this.getState(fileRef);
  }

  /**
   * Get memory index
   */
  getMemoryIndex(): Record<string, unknown> | null {
    return this.getState(ManagedFile.MEMORY_INDEX);
  }

  /**
   * Set orchestrator state
   */
  setOrchestratorState(
    state: Record<string, unknown>,
    source: string = "orchestrator"
  ): StateChange {
    return this.setState(ManagedFile.ORCHESTRATOR, state, source);
  }

  /**
   * Set autonomy state
   */
  setAutonomyState(
    state: Record<string, unknown>,
    source: string = "autonomy"
  ): StateChange {
    return this.setState(ManagedFile.AUTONOMY, state, source);
  }

  /**
   * Update orchestrator phase
   */
  updateOrchestratorPhase(phase: string, source: string = "orchestrator"): StateChange {
    return this.updateState(
      ManagedFile.ORCHESTRATOR,
      { currentPhase: phase, lastUpdated: new Date().toISOString() },
      source
    );
  }

  /**
   * Update autonomy status
   */
  updateAutonomyStatus(status: string, source: string = "autonomy"): StateChange {
    return this.updateState(
      ManagedFile.AUTONOMY,
      { status, lastRun: new Date().toISOString() },
      source
    );
  }

  /**
   * Get all managed states
   */
  getAllStates(): Record<string, Record<string, unknown>> {
    const states: Record<string, Record<string, unknown>> = {};

    for (const [name, fileRef] of Object.entries(ManagedFile)) {
      const state = this.getState(fileRef);
      if (state !== null) {
        states[name] = state;
      }
    }

    return states;
  }

  /**
   * Refresh all cached entries from disk
   */
  refreshCache(): void {
    for (const [filePath] of this.cache) {
      if (fs.existsSync(filePath)) {
        const data = this.readFile(filePath);
        if (data) {
          this.putInCache(filePath, data);
        }
      } else {
        this.cache.delete(filePath);
      }
    }
  }

  // -------------------------------------------------------------------------
  // Optimistic Updates (SYN-014)
  // -------------------------------------------------------------------------

  /**
   * Set the default conflict resolution strategy
   */
  setConflictStrategy(strategy: ConflictStrategy): void {
    this.conflictStrategy = strategy;
  }

  /**
   * Get the current version vector for a file
   */
  getVersionVector(fileRef: string | ManagedFileType): VersionVector {
    const filePath = this.resolvePath(fileRef);

    if (!this.versionVectors.has(filePath)) {
      // Try to load from file metadata
      const state = this.getState(fileRef);
      if (state && state._version_vector) {
        this.versionVectors.set(
          filePath,
          VersionVector.fromDict(state._version_vector as Record<string, number>)
        );
      } else {
        this.versionVectors.set(filePath, new VersionVector());
      }
    }

    return this.versionVectors.get(filePath)!;
  }

  /**
   * Apply an optimistic update immediately and queue for verification
   *
   * The update is applied to local state immediately but tracked as pending
   * until verified against the canonical state. If conflicts are detected
   * during verification, they are resolved using the configured strategy.
   */
  optimisticUpdate(
    fileRef: string | ManagedFileType,
    key: string,
    value: unknown,
    source: string = "state-manager"
  ): PendingUpdate {
    const filePath = this.resolvePath(fileRef);

    // Get current version vector and increment for this source
    const versionVector = this.getVersionVector(fileRef);
    versionVector.increment(source);

    // Create pending update
    const pending: PendingUpdate = {
      id: `${Date.now()}-${Math.random().toString(36).slice(2)}`,
      key,
      value,
      source,
      timestamp: new Date().toISOString(),
      versionVector: VersionVector.fromDict(versionVector.toDict()),
      status: "pending",
    };

    // Track pending update
    if (!this.pendingUpdates.has(filePath)) {
      this.pendingUpdates.set(filePath, []);
    }
    this.pendingUpdates.get(filePath)!.push(pending);

    // Apply optimistically to local state
    const currentState = this.getState(fileRef, {}) || {};
    currentState[key] = value;
    currentState._version_vector = versionVector.toDict();
    currentState._last_source = source;
    currentState._last_updated = pending.timestamp;

    // Write state with version tracking
    this.writeFile(filePath, currentState);
    this.putInCache(filePath, currentState);

    return pending;
  }

  /**
   * Get all pending updates for a file
   */
  getPendingUpdates(fileRef: string | ManagedFileType): PendingUpdate[] {
    const filePath = this.resolvePath(fileRef);
    return this.pendingUpdates.get(filePath) || [];
  }

  /**
   * Detect conflicts between local pending updates and remote state
   */
  detectConflicts(
    fileRef: string | ManagedFileType,
    remoteState: Record<string, unknown>,
    remoteSource: string
  ): ConflictInfo[] {
    const filePath = this.resolvePath(fileRef);
    const conflicts: ConflictInfo[] = [];
    const pending = this.pendingUpdates.get(filePath) || [];

    if (pending.length === 0) {
      return conflicts;
    }

    // Get remote version vector
    let remoteVv = new VersionVector();
    if (remoteState._version_vector) {
      remoteVv = VersionVector.fromDict(remoteState._version_vector as Record<string, number>);
    }

    const localState = this.getState(fileRef, {}) || {};

    // Check each pending update for conflicts
    for (const update of pending) {
      if (update.status !== "pending") {
        continue;
      }

      const key = update.key;

      // Check if same key was modified in remote state
      if (key in remoteState && key in localState) {
        const localVal = localState[key];
        const remoteVal = remoteState[key];

        // Only conflict if values differ and versions are concurrent
        if (JSON.stringify(localVal) !== JSON.stringify(remoteVal)) {
          if (update.versionVector.concurrentWith(remoteVv)) {
            conflicts.push({
              key,
              localValue: localVal,
              remoteValue: remoteVal,
              localSource: update.source,
              remoteSource,
              localVersion: update.versionVector,
              remoteVersion: remoteVv,
            });
          }
        }
      }
    }

    return conflicts;
  }

  /**
   * Resolve conflicts using the specified strategy
   */
  resolveConflicts(
    fileRef: string | ManagedFileType,
    conflicts: ConflictInfo[],
    strategy?: ConflictStrategy
  ): Record<string, unknown> {
    const resolveStrategy = strategy || this.conflictStrategy;
    const filePath = this.resolvePath(fileRef);

    const localState = this.getState(fileRef, {}) || {};
    const resolvedState = { ...localState };

    for (const conflict of conflicts) {
      if (resolveStrategy === ConflictStrategy.LAST_WRITE_WINS) {
        // Use remote value (assuming remote is more recent)
        resolvedState[conflict.key] = conflict.remoteValue;
        conflict.resolution = "last_write_wins";
        conflict.resolvedValue = conflict.remoteValue;
      } else if (resolveStrategy === ConflictStrategy.MERGE) {
        // Attempt to merge values
        const merged = this.mergeValues(
          conflict.localValue,
          conflict.remoteValue
        );
        resolvedState[conflict.key] = merged;
        conflict.resolution = "merged";
        conflict.resolvedValue = merged;
      } else if (resolveStrategy === ConflictStrategy.REJECT) {
        // Keep local value, mark conflict as rejected
        conflict.resolution = "rejected";
        conflict.resolvedValue = conflict.localValue;
        // Mark pending updates for this key as rejected
        const pending = this.pendingUpdates.get(filePath) || [];
        for (const update of pending) {
          if (update.key === conflict.key && update.status === "pending") {
            update.status = "rejected";
          }
        }
      }
    }

    // Merge version vectors
    let localVv = this.getVersionVector(fileRef);
    for (const conflict of conflicts) {
      localVv = localVv.merge(conflict.remoteVersion);
    }

    resolvedState._version_vector = localVv.toDict();
    this.versionVectors.set(filePath, localVv);

    return resolvedState;
  }

  /**
   * Attempt to merge two values
   *
   * For objects, performs a deep merge.
   * For arrays, concatenates and deduplicates.
   * For other types, prefers remote value.
   */
  private mergeValues(local: unknown, remote: unknown): unknown {
    if (
      typeof local === "object" &&
      typeof remote === "object" &&
      local !== null &&
      remote !== null &&
      !Array.isArray(local) &&
      !Array.isArray(remote)
    ) {
      const merged: Record<string, unknown> = { ...(local as Record<string, unknown>) };
      for (const [key, value] of Object.entries(remote as Record<string, unknown>)) {
        if (key in merged) {
          merged[key] = this.mergeValues(merged[key], value);
        } else {
          merged[key] = value;
        }
      }
      return merged;
    }

    if (Array.isArray(local) && Array.isArray(remote)) {
      // Concatenate and deduplicate (preserving order)
      const seen = new Set<string>();
      const merged: unknown[] = [];
      for (const item of [...local, ...remote]) {
        const itemKey = JSON.stringify(item);
        if (!seen.has(itemKey)) {
          seen.add(itemKey);
          merged.push(item);
        }
      }
      return merged;
    }

    // For scalars, prefer remote
    return remote;
  }

  /**
   * Commit all pending updates for a file
   */
  commitPendingUpdates(fileRef: string | ManagedFileType): number {
    const filePath = this.resolvePath(fileRef);
    const pending = this.pendingUpdates.get(filePath) || [];
    let committed = 0;

    for (const update of pending) {
      if (update.status === "pending") {
        update.status = "committed";
        committed++;
      }
    }

    // Clear committed updates
    this.pendingUpdates.set(
      filePath,
      pending.filter((u) => u.status !== "committed")
    );

    return committed;
  }

  /**
   * Rollback pending updates and restore original state
   */
  rollbackPendingUpdates(
    fileRef: string | ManagedFileType,
    originalState: Record<string, unknown>
  ): number {
    const filePath = this.resolvePath(fileRef);
    const pending = this.pendingUpdates.get(filePath) || [];
    let rolledBack = 0;

    for (const update of pending) {
      if (update.status === "pending") {
        update.status = "rejected";
        rolledBack++;
      }
    }

    // Restore original state
    this.setState(fileRef, originalState, "rollback");

    // Clear pending updates
    this.pendingUpdates.set(filePath, []);

    return rolledBack;
  }

  /**
   * Synchronize local state with remote state, resolving conflicts
   *
   * This is a high-level operation that:
   * 1. Detects conflicts between local pending updates and remote state
   * 2. Resolves conflicts using the specified strategy
   * 3. Commits or rejects pending updates accordingly
   * 4. Returns the final synchronized state
   */
  syncWithRemote(
    fileRef: string | ManagedFileType,
    remoteState: Record<string, unknown>,
    remoteSource: string,
    strategy?: ConflictStrategy
  ): {
    resolvedState: Record<string, unknown>;
    conflicts: ConflictInfo[];
    committed: number;
  } {
    // Detect conflicts
    const conflicts = this.detectConflicts(fileRef, remoteState, remoteSource);

    // Resolve conflicts
    const resolvedState = this.resolveConflicts(fileRef, conflicts, strategy);

    // Apply resolved state
    this.setState(fileRef, resolvedState, "sync");

    // Commit pending updates (non-rejected ones)
    const committed = this.commitPendingUpdates(fileRef);

    return { resolvedState, conflicts, committed };
  }

  // -------------------------------------------------------------------------
  // State Versioning (SYN-015)
  // -------------------------------------------------------------------------

  /**
   * Get a safe key for the file reference (used in history paths)
   */
  private getFileKey(fileRef: string | ManagedFileType): string {
    const relPath = typeof fileRef === "string" ? fileRef : fileRef;
    return relPath.replace(/\//g, "_").replace(/\\/g, "_").replace(".json", "");
  }

  /**
   * Get the history directory for a file reference
   */
  private getHistoryDir(fileRef: string | ManagedFileType): string {
    const fileKey = this.getFileKey(fileRef);
    return path.join(this.lokiDir, "state", "history", fileKey);
  }

  /**
   * Get the next version number for a file
   */
  private getNextVersion(fileRef: string | ManagedFileType): number {
    const fileKey = this.getFileKey(fileRef);
    if (!this.versionCounters.has(fileKey)) {
      // Initialize from existing versions on disk
      const historyDir = this.getHistoryDir(fileRef);
      if (fs.existsSync(historyDir)) {
        const files = fs.readdirSync(historyDir).filter(f => f.endsWith(".json"));
        if (files.length > 0) {
          let maxVersion = 0;
          for (const f of files) {
            const version = parseInt(path.basename(f, ".json"), 10);
            if (!isNaN(version) && version > maxVersion) {
              maxVersion = version;
            }
          }
          this.versionCounters.set(fileKey, maxVersion);
        } else {
          this.versionCounters.set(fileKey, 0);
        }
      } else {
        this.versionCounters.set(fileKey, 0);
      }
    }
    const current = this.versionCounters.get(fileKey) || 0;
    this.versionCounters.set(fileKey, current + 1);
    return current + 1;
  }

  /**
   * Save a version of the state to history
   */
  private saveVersion(
    fileRef: string | ManagedFileType,
    data: Record<string, unknown>,
    source: string,
    changeType: string
  ): number {
    const historyDir = this.getHistoryDir(fileRef);
    if (!fs.existsSync(historyDir)) {
      fs.mkdirSync(historyDir, { recursive: true });
    }

    const version = this.getNextVersion(fileRef);
    const timestamp = new Date().toISOString();

    const versionData: StateVersion = {
      version,
      timestamp,
      data,
      source,
      changeType,
    };

    const versionPath = path.join(historyDir, `${version}.json`);
    this.writeFile(versionPath, versionData as unknown as Record<string, unknown>);

    // Clean up old versions
    this.cleanupOldVersions(fileRef);

    return version;
  }

  /**
   * Remove versions beyond the retention limit
   */
  private cleanupOldVersions(fileRef: string | ManagedFileType): void {
    const historyDir = this.getHistoryDir(fileRef);
    if (!fs.existsSync(historyDir)) {
      return;
    }

    const files = fs.readdirSync(historyDir).filter(f => f.endsWith(".json"));
    if (files.length <= this.versionRetention) {
      return;
    }

    // Sort by version number and remove oldest
    const versionFiles = files
      .map(f => ({ file: f, version: parseInt(path.basename(f, ".json"), 10) }))
      .filter(v => !isNaN(v.version))
      .sort((a, b) => a.version - b.version);

    const toRemove = versionFiles.slice(0, versionFiles.length - this.versionRetention);
    for (const { file } of toRemove) {
      try {
        fs.unlinkSync(path.join(historyDir, file));
      } catch {
        // Ignore removal errors
      }
    }
  }

  /**
   * Get version history for a state file
   */
  getVersionHistory(fileRef: string | ManagedFileType): VersionInfo[] {
    const historyDir = this.getHistoryDir(fileRef);
    if (!fs.existsSync(historyDir)) {
      return [];
    }

    const versions: VersionInfo[] = [];
    const files = fs.readdirSync(historyDir).filter(f => f.endsWith(".json"));

    for (const file of files) {
      try {
        const versionNum = parseInt(path.basename(file, ".json"), 10);
        if (isNaN(versionNum)) continue;

        const versionPath = path.join(historyDir, file);
        const data = this.readFile(versionPath);
        if (data) {
          const versionEntry = data as unknown as StateVersion;
          versions.push({
            version: versionNum,
            timestamp: versionEntry.timestamp || "",
            source: versionEntry.source || "unknown",
            changeType: versionEntry.changeType || "update",
            dataHash: computeHash(versionEntry.data || {}),
          });
        }
      } catch {
        // Skip invalid version files
      }
    }

    // Sort by version descending (newest first)
    versions.sort((a, b) => b.version - a.version);
    return versions;
  }

  /**
   * Get state data at a specific version without restoring
   */
  getStateAtVersion(
    fileRef: string | ManagedFileType,
    version: number
  ): Record<string, unknown> | null {
    const historyDir = this.getHistoryDir(fileRef);
    const versionPath = path.join(historyDir, `${version}.json`);

    if (!fs.existsSync(versionPath)) {
      return null;
    }

    const versionData = this.readFile(versionPath);
    if (versionData) {
      const versionEntry = versionData as unknown as StateVersion;
      return versionEntry.data || null;
    }
    return null;
  }

  /**
   * Restore state to a specific version
   */
  rollback(
    fileRef: string | ManagedFileType,
    version: number,
    source: string = "rollback"
  ): StateChange | null {
    const data = this.getStateAtVersion(fileRef, version);
    if (data === null) {
      return null;
    }

    // Save current state as a version before rollback
    const current = this.getState(fileRef);
    if (current !== null && this.enableVersioning) {
      this.saveVersion(fileRef, current, source, "pre_rollback");
    }

    // Set the restored state (saveVersion=false since we already saved)
    return this.setState(fileRef, data, source, false);
  }

  /**
   * Get the number of versions stored for a file
   */
  getVersionCount(fileRef: string | ManagedFileType): number {
    const historyDir = this.getHistoryDir(fileRef);
    if (!fs.existsSync(historyDir)) {
      return 0;
    }
    return fs.readdirSync(historyDir).filter(f => f.endsWith(".json")).length;
  }

  /**
   * Clear all version history for a file
   */
  clearVersionHistory(fileRef: string | ManagedFileType): number {
    const historyDir = this.getHistoryDir(fileRef);
    if (!fs.existsSync(historyDir)) {
      return 0;
    }

    const files = fs.readdirSync(historyDir).filter(f => f.endsWith(".json"));
    let count = 0;
    for (const file of files) {
      try {
        fs.unlinkSync(path.join(historyDir, file));
        count++;
      } catch {
        // Ignore removal errors
      }
    }

    // Reset version counter
    const fileKey = this.getFileKey(fileRef);
    this.versionCounters.delete(fileKey);

    return count;
  }

  /**
   * Update the version retention limit
   */
  setVersionRetention(retention: number): void {
    if (retention < 1) {
      throw new Error("Version retention must be at least 1");
    }
    this.versionRetention = retention;
  }
}

// Singleton instance
let defaultManager: StateManager | null = null;

/**
 * Get the default state manager instance
 */
export function getStateManager(options?: {
  lokiDir?: string;
  enableWatch?: boolean;
  enableEvents?: boolean;
  enableVersioning?: boolean;
  versionRetention?: number;
}): StateManager {
  if (defaultManager === null) {
    defaultManager = new StateManager(options);
  }
  return defaultManager;
}

/**
 * Reset the default state manager (for testing)
 */
export function resetStateManager(): void {
  if (defaultManager) {
    defaultManager.stop();
    defaultManager = null;
  }
}