clearctx 3.0.0

package/src/contract-store.js

@@ -0,0 +1,525 @@
+// contract-store.js
+// Layer 2: Contract lifecycle management with timeout and retry support
+//
+// A Contract is a formal agreement between sessions specifying:
+// - What work needs to be done (title, description, inputs)
+// - Who does the work (assignee)
+// - What outputs are expected (expectedOutputs)
+// - What must be satisfied first (dependencies)
+// - How we know it's done (acceptanceCriteria)
+// - Retry and timeout policies
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { atomicWriteJson, readJsonSafe } = require('./atomic-io');
+const { acquireLock, releaseLock } = require('./file-lock');
+
+/**
+ * ContractStore manages the lifecycle of contracts in a team
+ *
+ * A contract represents a unit of work with formal inputs, outputs,
+ * dependencies, and acceptance criteria. Contracts follow a strict
+ * lifecycle: pending → ready → in_progress → completed/failed
+ *
+ * Features:
+ * - Dependency tracking with cycle detection
+ * - Automatic status transitions when dependencies are satisfied
+ * - Retry support for failed/completed contracts
+ * - Timeout configuration
+ * - Priority levels
+ *
+ * @class
+ */
+class ContractStore {
+  /**
+   * Creates a new ContractStore for a team
+   *
+   * @param {string} [teamName='default'] - The team name (used for directory isolation)
+   */
+  constructor(teamName = 'default') {
+    // Set up the base directory where all multi-session data lives
+    const baseDir = path.join(os.homedir(), '.clearctx');
+
+    // Each team gets its own directory to keep contracts separate
+    this.teamDir = path.join(baseDir, 'team', teamName);
+
+    // The contracts directory holds the index.json file
+    this.contractsDir = path.join(this.teamDir, 'contracts');
+
+    // Path to the main index file that stores all contracts
+    this.indexPath = path.join(this.contractsDir, 'index.json');
+
+    // Directory for lock files
+    this.locksDir = path.join(baseDir, 'locks');
+
+    // Create the directories if they don't exist yet
+    if (!fs.existsSync(this.contractsDir)) {
+      fs.mkdirSync(this.contractsDir, { recursive: true });
+    }
+    if (!fs.existsSync(this.locksDir)) {
+      fs.mkdirSync(this.locksDir, { recursive: true });
+    }
+  }
+
+  /**
+   * Creates a new contract
+   *
+   * This method:
+   * 1. Validates the contractId is unique
+   * 2. Checks for circular dependencies (cycles)
+   * 3. Determines initial status (pending if has dependencies, ready if not)
+   * 4. Saves the contract to the index
+   *
+   * @param {string} contractId - Unique identifier for this contract
+   * @param {Object} options - Contract configuration
+   * @param {string} options.title - Human-readable title
+   * @param {string} [options.description=''] - Longer description of the work
+   * @param {string} options.assignee - Session name who will do the work
+   * @param {string} options.assigner - Session name who created the contract
+   * @param {Object} [options.inputs={}] - Input artifacts and context
+   * @param {Array} [options.inputs.artifacts=[]] - Artifact IDs to read as inputs
+   * @param {string} [options.inputs.context=''] - Free-text instructions
+   * @param {Object} [options.inputs.parameters={}] - Key-value parameters
+   * @param {Array} [options.expectedOutputs=[]] - What the assignee should produce
+   * @param {Array} [options.dependencies=[]] - What must be satisfied before this can start
+   * @param {Array} [options.acceptanceCriteria=[]] - How we know the work is done
+   * @param {boolean} [options.autoComplete=true] - Auto-complete when criteria met
+   * @param {number} [options.timeoutMs=null] - Optional timeout in milliseconds
+   * @param {number} [options.maxRetries=3] - Maximum number of reopen attempts
+   * @param {string} [options.priority='normal'] - Priority level (low|normal|high|urgent)
+   * @returns {Object} The created contract object
+   * @throws {Error} If contractId already exists or circular dependency detected
+   */
+  create(contractId, {
+    title,
+    description = '',
+    assignee,
+    assigner,
+    inputs = {},
+    expectedOutputs = [],
+    dependencies = [],
+    acceptanceCriteria = [],
+    autoComplete = true,
+    timeoutMs = null,
+    maxRetries = 3,
+    priority = 'normal'
+  }) {
+    // Acquire exclusive lock on the contracts index
+    // This prevents race conditions when multiple sessions create contracts
+    acquireLock(this.locksDir, 'contracts-index');
+
+    try {
+      // Read the current index (or get an empty object if file doesn't exist)
+      const index = readJsonSafe(this.indexPath, {});
+
+      // Check if this contractId is already taken
+      if (index[contractId]) {
+        throw new Error(`Contract with ID "${contractId}" already exists`);
+      }
+
+      // Detect circular dependencies before creating the contract
+      // A circular dependency would create a deadlock where contracts wait on each other
+      if (this._detectCycle(contractId, dependencies, index)) {
+        throw new Error(`Circular dependency detected for contract "${contractId}"`);
+      }
+
+      // Normalize the inputs object with defaults
+      const normalizedInputs = {
+        artifacts: inputs.artifacts || [],
+        context: inputs.context || '',
+        parameters: inputs.parameters || {}
+      };
+
+      // Build the complete contract object
+      const now = new Date().toISOString();
+      const contract = {
+        contractId,
+        title,
+        description,
+        assignee,
+        assigner,
+        // Status starts as "pending" if there are dependencies, "ready" if not
+        status: dependencies.length > 0 ? 'pending' : 'ready',
+        priority,
+        createdAt: now,
+        updatedAt: now,
+        startedAt: null,
+        completedAt: null,
+        inputs: normalizedInputs,
+        expectedOutputs,
+        dependencies,
+        acceptanceCriteria,
+        autoComplete,
+        timeoutMs,
+        maxRetries,
+        retryCount: 0,
+        result: null
+      };
+
+      // Add the contract to the index
+      index[contractId] = contract;
+
+      // Save atomically (prevents corruption from partial writes)
+      atomicWriteJson(this.indexPath, index);
+
+      // Return a copy of the contract
+      return { ...contract };
+    } finally {
+      // Always release the lock, even if an error occurred
+      releaseLock(this.locksDir, 'contracts-index');
+    }
+  }
+
+  /**
+   * Starts a contract (transitions from ready → in_progress)
+   *
+   * This is called by the assignee when they begin work.
+   * The contract must be in "ready" status.
+   *
+   * @param {string} contractId - The contract to start
+   * @returns {Object} The updated contract (including inputs for the assignee)
+   * @throws {Error} If contract doesn't exist or is not in "ready" status
+   */
+  start(contractId) {
+    acquireLock(this.locksDir, 'contracts-index');
+
+    try {
+      const index = readJsonSafe(this.indexPath, {});
+      const contract = index[contractId];
+
+      // Verify the contract exists
+      if (!contract) {
+        throw new Error(`Contract "${contractId}" not found`);
+      }
+
+      // Verify the contract is ready to start
+      if (contract.status !== 'ready') {
+        throw new Error(`Contract "${contractId}" is not ready (current status: ${contract.status})`);
+      }
+
+      // Transition to in_progress and record when we started
+      contract.status = 'in_progress';
+      contract.startedAt = new Date().toISOString();
+      contract.updatedAt = new Date().toISOString();
+
+      // Save the updated contract
+      atomicWriteJson(this.indexPath, index);
+
+      return { ...contract };
+    } finally {
+      releaseLock(this.locksDir, 'contracts-index');
+    }
+  }
+
+  /**
+   * Completes a contract (transitions from in_progress → completed)
+   *
+   * This is called when the work is done successfully.
+   *
+   * @param {string} contractId - The contract to complete
+   * @param {Object} [options={}] - Completion details
+   * @param {string} [options.summary=''] - Summary of what was done
+   * @param {Array} [options.publishedArtifacts=[]] - Artifact IDs that were published
+   * @returns {Object} The updated contract
+   * @throws {Error} If contract doesn't exist or is not in "in_progress" status
+   */
+  complete(contractId, { summary = '', publishedArtifacts = [] } = {}) {
+    acquireLock(this.locksDir, 'contracts-index');
+
+    try {
+      const index = readJsonSafe(this.indexPath, {});
+      const contract = index[contractId];
+
+      if (!contract) {
+        throw new Error(`Contract "${contractId}" not found`);
+      }
+
+      if (contract.status !== 'in_progress') {
+        throw new Error(`Contract "${contractId}" is not in progress (current status: ${contract.status})`);
+      }
+
+      // Transition to completed and record the result
+      const now = new Date().toISOString();
+      contract.status = 'completed';
+      contract.completedAt = now;
+      contract.updatedAt = now;
+      contract.result = { summary, publishedArtifacts };
+
+      atomicWriteJson(this.indexPath, index);
+
+      return { ...contract };
+    } finally {
+      releaseLock(this.locksDir, 'contracts-index');
+    }
+  }
+
+  /**
+   * Fails a contract (transitions from in_progress → failed)
+   *
+   * This is called when the work cannot be completed successfully.
+   *
+   * @param {string} contractId - The contract to fail
+   * @param {string} reason - Why the contract failed
+   * @returns {Object} The updated contract
+   * @throws {Error} If contract doesn't exist or is not in "in_progress" status
+   */
+  fail(contractId, reason) {
+    acquireLock(this.locksDir, 'contracts-index');
+
+    try {
+      const index = readJsonSafe(this.indexPath, {});
+      const contract = index[contractId];
+
+      if (!contract) {
+        throw new Error(`Contract "${contractId}" not found`);
+      }
+
+      if (contract.status !== 'in_progress') {
+        throw new Error(`Contract "${contractId}" is not in progress (current status: ${contract.status})`);
+      }
+
+      // Transition to failed and record the reason
+      const now = new Date().toISOString();
+      contract.status = 'failed';
+      contract.completedAt = now;
+      contract.updatedAt = now;
+      contract.result = { reason };
+
+      atomicWriteJson(this.indexPath, index);
+
+      return { ...contract };
+    } finally {
+      releaseLock(this.locksDir, 'contracts-index');
+    }
+  }
+
+  /**
+   * Reopens a failed or completed contract for retry or revision
+   *
+   * For failed contracts: transitions to "ready" for a retry
+   * For completed contracts: transitions to "in_progress" for a revision
+   *
+   * This increments the retryCount and will fail if maxRetries is exceeded.
+   *
+   * @param {string} contractId - The contract to reopen
+   * @param {Object} [options={}] - Reopen configuration
+   * @param {string} [options.reason=''] - Why we're reopening the contract
+   * @param {Object} [options.newInputs=null] - New inputs to merge in
+   * @returns {Object} The updated contract
+   * @throws {Error} If contract doesn't exist, wrong status, or max retries exceeded
+   */
+  reopen(contractId, { reason = '', newInputs = null } = {}) {
+    acquireLock(this.locksDir, 'contracts-index');
+
+    try {
+      const index = readJsonSafe(this.indexPath, {});
+      const contract = index[contractId];
+
+      if (!contract) {
+        throw new Error(`Contract "${contractId}" not found`);
+      }
+
+      // Can only reopen failed or completed contracts
+      if (contract.status !== 'failed' && contract.status !== 'completed') {
+        throw new Error(`Contract "${contractId}" cannot be reopened (current status: ${contract.status})`);
+      }
+
+      // Check if we've exceeded the retry limit
+      if (contract.retryCount >= contract.maxRetries) {
+        throw new Error(`Contract "${contractId}" has exceeded max retries (${contract.maxRetries})`);
+      }
+
+      // Increment the retry counter
+      contract.retryCount += 1;
+
+      // Determine new status based on current status
+      if (contract.status === 'failed') {
+        // Failed contracts go back to ready for a retry
+        contract.status = 'ready';
+      } else {
+        // Completed contracts go to in_progress for a revision
+        contract.status = 'in_progress';
+      }
+
+      // Merge in new inputs if provided
+      if (newInputs) {
+        contract.inputs = {
+          artifacts: newInputs.artifacts || contract.inputs.artifacts,
+          context: newInputs.context || contract.inputs.context,
+          parameters: { ...contract.inputs.parameters, ...(newInputs.parameters || {}) }
+        };
+      }
+
+      // Reset completion timestamp and update the updated timestamp
+      contract.completedAt = null;
+      contract.updatedAt = new Date().toISOString();
+
+      atomicWriteJson(this.indexPath, index);
+
+      return { ...contract };
+    } finally {
+      releaseLock(this.locksDir, 'contracts-index');
+    }
+  }
+
+  /**
+   * Gets a single contract by ID
+   *
+   * @param {string} contractId - The contract to retrieve
+   * @returns {Object|null} The contract object, or null if not found
+   */
+  get(contractId) {
+    const index = readJsonSafe(this.indexPath, {});
+    return index[contractId] ? { ...index[contractId] } : null;
+  }
+
+  /**
+   * Lists contracts with optional filtering
+   *
+   * @param {Object} [filters={}] - Filter criteria
+   * @param {string} [filters.status] - Filter by status
+   * @param {string} [filters.assignee] - Filter by assignee session name
+   * @param {string} [filters.assigner] - Filter by assigner session name
+   * @returns {Array} Array of contracts matching the filters
+   */
+  list({ status, assignee, assigner } = {}) {
+    const index = readJsonSafe(this.indexPath, {});
+
+    // Get all contracts as an array
+    let contracts = Object.values(index);
+
+    // Apply filters if provided
+    if (status) {
+      contracts = contracts.filter(c => c.status === status);
+    }
+    if (assignee) {
+      contracts = contracts.filter(c => c.assignee === assignee);
+    }
+    if (assigner) {
+      contracts = contracts.filter(c => c.assigner === assigner);
+    }
+
+    // Return copies to prevent mutation
+    return contracts.map(c => ({ ...c }));
+  }
+
+  /**
+   * Reassigns a contract to a different session
+   *
+   * @param {string} contractId - The contract to reassign
+   * @param {string} newAssignee - The new assignee session name
+   * @returns {Object} The updated contract
+   * @throws {Error} If contract doesn't exist
+   */
+  reassign(contractId, newAssignee) {
+    acquireLock(this.locksDir, 'contracts-index');
+
+    try {
+      const index = readJsonSafe(this.indexPath, {});
+      const contract = index[contractId];
+
+      if (!contract) {
+        throw new Error(`Contract "${contractId}" not found`);
+      }
+
+      // Update the assignee and timestamp
+      contract.assignee = newAssignee;
+      contract.updatedAt = new Date().toISOString();
+
+      atomicWriteJson(this.indexPath, index);
+
+      return { ...contract };
+    } finally {
+      releaseLock(this.locksDir, 'contracts-index');
+    }
+  }
+
+  /**
+   * Detects circular dependencies in the contract dependency graph
+   *
+   * Uses depth-first search (DFS) to traverse the dependency chain.
+   * If we encounter the starting contractId during traversal, there's a cycle.
+   *
+   * Example cycle: A depends on B, B depends on C, C depends on A
+   *
+   * @private
+   * @param {string} contractId - The contract we're creating
+   * @param {Array} dependencies - The dependencies for this contract
+   * @param {Object} allContracts - All existing contracts in the index
+   * @returns {boolean} True if a cycle is detected, false otherwise
+   */
+  _detectCycle(contractId, dependencies, allContracts) {
+    // Set to track which contracts we've visited in this DFS path
+    // This helps us detect when we've looped back to a contract we're already processing
+    const visited = new Set();
+
+    // Set to track the current path we're exploring
+    // If we see a contract in the current path again, that's a cycle
+    const path = new Set();
+
+    /**
+     * DFS helper function that explores one contract's dependencies
+     *
+     * @param {string} currentId - The contract we're currently exploring
+     * @returns {boolean} True if a cycle is found
+     */
+    const dfs = (currentId) => {
+      // If we've already fully explored this contract, skip it
+      if (visited.has(currentId)) {
+        return false;
+      }
+
+      // If this contract is in our current path, we found a cycle!
+      if (path.has(currentId)) {
+        return true;
+      }
+
+      // Add to the current path
+      path.add(currentId);
+
+      // Get this contract's dependencies
+      const contract = allContracts[currentId];
+      if (contract && contract.dependencies) {
+        // Check each dependency
+        for (const dep of contract.dependencies) {
+          // Only follow "contract" type dependencies
+          if (dep.type === 'contract' && dep.contractId) {
+            // Recursively check this dependency
+            if (dfs(dep.contractId)) {
+              return true; // Cycle found deeper in the graph
+            }
+          }
+        }
+      }
+
+      // Remove from current path (backtrack)
+      path.delete(currentId);
+
+      // Mark as fully visited
+      visited.add(currentId);
+
+      return false;
+    };
+
+    // Check each dependency of the new contract
+    for (const dep of dependencies) {
+      if (dep.type === 'contract' && dep.contractId) {
+        // Start DFS from this dependency
+        // If it eventually leads back to contractId, that's a cycle
+        if (dep.contractId === contractId) {
+          return true; // Direct self-dependency
+        }
+        if (dfs(dep.contractId)) {
+          return true; // Indirect cycle found
+        }
+      }
+    }
+
+    // No cycles detected
+    return false;
+  }
+}
+
+// Export the ContractStore class
+module.exports = ContractStore;