agentic-orchestrator 0.1.0

package/apps/control-plane/src/application/services/feature-state-service.ts

@@ -0,0 +1,125 @@
+import { nowIso } from '../../core/fs.js';
+import { fail } from '../../core/response.js';
+import { ERROR_CODES } from '../../core/error-codes.js';
+import { STATUS } from '../../core/constants.js';
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type AnyRecord = Record<string, any>;
+
+type StateReadResult = {
+  frontMatter: AnyRecord;
+  body: string;
+  raw?: string;
+};
+
+type StateUpdater = (
+  frontMatter: AnyRecord,
+  body: string
+) => Promise<{ frontMatter?: AnyRecord; body?: string }>;
+
+const LEGAL_TRANSITIONS = {
+  [STATUS.PLANNING]: [STATUS.BUILDING, STATUS.BLOCKED, STATUS.PLANNING],
+  [STATUS.BUILDING]: [STATUS.QA, STATUS.BLOCKED, STATUS.BUILDING],
+  [STATUS.QA]: [STATUS.READY_TO_MERGE, STATUS.BLOCKED, STATUS.QA],
+  [STATUS.READY_TO_MERGE]: [STATUS.MERGED, STATUS.BLOCKED, STATUS.READY_TO_MERGE],
+  [STATUS.BLOCKED]: [STATUS.PLANNING, STATUS.BUILDING, STATUS.QA, STATUS.BLOCKED],
+  [STATUS.MERGED]: [STATUS.MERGED],
+  [STATUS.FAILED]: [STATUS.FAILED, STATUS.BLOCKED]
+};
+
+function isTransitionLegal(from: string, to: string): boolean {
+  const allowed = (LEGAL_TRANSITIONS as Record<string, string[]>)[from] ?? [];
+  return allowed.includes(to);
+}
+
+function readVersion(frontMatter: AnyRecord): number {
+  const raw = frontMatter.version;
+  if (typeof raw === 'number' && Number.isFinite(raw)) {
+    return raw;
+  }
+  return 0;
+}
+
+export interface FeatureStateServicePort {
+  withFeatureLock<T>(featureId: string, operation: () => Promise<T>): Promise<T>;
+  readState(featureId: string): Promise<StateReadResult>;
+  writeState(featureId: string, frontMatter: AnyRecord, body?: string): Promise<void>;
+}
+
+export class FeatureStateService {
+  private readonly port: FeatureStateServicePort;
+
+  constructor(port: FeatureStateServicePort) {
+    this.port = port;
+  }
+
+  async updateState(featureId: string, expectedVersion: number | null, updater: StateUpdater): Promise<AnyRecord> {
+    return await this.port.withFeatureLock(featureId, async () => {
+      const current = await this.port.readState(featureId);
+      if (expectedVersion != null && current.frontMatter.version !== expectedVersion) {
+        throw {
+          normalizedResponse: fail(ERROR_CODES.VERSION_CONFLICT, 'state version conflict', {
+            expected_version: expectedVersion,
+            actual_version: current.frontMatter.version,
+            retryable: true,
+            requires_human: false
+          })
+        };
+      }
+
+      const next = await updater(structuredClone(current.frontMatter), current.body);
+      const merged: AnyRecord = {
+        ...current.frontMatter,
+        ...next.frontMatter,
+        version: readVersion(current.frontMatter) + 1,
+        last_updated: nowIso()
+      };
+
+      if (!isTransitionLegal(current.frontMatter.status, merged.status)) {
+        throw {
+          normalizedResponse: fail(ERROR_CODES.INVALID_STATUS_TRANSITION, 'illegal state status transition', {
+            from: current.frontMatter.status,
+            to: merged.status,
+            retryable: false,
+            requires_human: true
+          })
+        };
+      }
+
+      await this.port.writeState(featureId, merged, next.body ?? current.body);
+      return merged;
+    });
+  }
+
+  async featureStateGet(featureId: string): Promise<{ data: { front_matter: AnyRecord; body: string } }> {
+    const state = await this.port.readState(featureId);
+    return {
+      data: {
+        front_matter: state.frontMatter,
+        body: state.body
+      }
+    };
+  }
+
+  async featureStatePatch(
+    featureId: string,
+    expectedVersion: number | null,
+    patch: AnyRecord | null | undefined
+  ): Promise<{ data: { feature_id: string; version: number; status: string } }> {
+    const updated = await this.updateState(featureId, expectedVersion, (frontMatter, body) => {
+      const nextFront = { ...frontMatter, ...(patch?.front_matter ?? {}) };
+      return Promise.resolve({
+        frontMatter: nextFront,
+        body: patch?.body ?? body
+      });
+    });
+
+    return {
+      data: {
+        feature_id: featureId,
+        version: updated.version,
+        status: updated.status
+      }
+    };
+  }
+}

package/apps/control-plane/src/application/services/gate-service.ts

@@ -0,0 +1,232 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { pathExists } from '../../core/fs.js';
+import { runGateMode } from '../../core/gates.js';
+import { ERROR_CODES } from '../../core/error-codes.js';
+import { fail } from '../../core/response.js';
+import { GATE_RESULT, STATUS } from '../../core/constants.js';
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type AnyRecord = Record<string, any>;
+
+type StateUpdater = (
+  frontMatter: AnyRecord,
+  body: string
+) => Promise<{ frontMatter?: AnyRecord; body?: string }>;
+
+type GateRunResult = {
+  overall: 'pass' | 'fail';
+  coverage_status: 'pass' | 'fail' | 'na';
+  evidence_path: string;
+  latest_path: string;
+  coverage: unknown;
+  thresholds: unknown;
+};
+
+function normalizeRepoPathForState(repoRoot: string, absolutePath: string): string {
+  const relative = path.relative(repoRoot, absolutePath).replaceAll('\\\\', '/');
+  if (!relative || relative === '.') {
+    return '.';
+  }
+  return relative;
+}
+
+function deriveStatusFromGateResult(currentStatus: string, mode: string, overall: 'pass' | 'fail'): string {
+  if (overall === 'fail') {
+    return STATUS.BLOCKED;
+  }
+
+  if (currentStatus === STATUS.BUILDING && mode === 'fast' && overall === 'pass') {
+    return STATUS.QA;
+  }
+
+  if (currentStatus === STATUS.QA && mode === 'full' && overall === 'pass') {
+    return STATUS.READY_TO_MERGE;
+  }
+
+  return currentStatus;
+}
+
+export interface GateServicePort {
+  getRepoRoot(): string;
+  getGatesConfig(): AnyRecord;
+  getPolicySnapshot(): AnyRecord;
+  readState(featureId: string): Promise<{ frontMatter: AnyRecord }>;
+  updateState(featureId: string, expectedVersion: number | null, updater: StateUpdater): Promise<AnyRecord>;
+  worktreePath(featureId: string): string;
+  logsPath(featureId: string): string;
+  evidencePath(featureId: string): string;
+}
+
+export class GateService {
+  private readonly port: GateServicePort;
+
+  constructor(port: GateServicePort) {
+    this.port = port;
+  }
+
+  gatesList(profileName: string | null = null): { data: AnyRecord } {
+    const gatesConfig = this.port.getGatesConfig();
+    if (profileName) {
+      return {
+        data: {
+          profile: profileName,
+          config: gatesConfig.profiles[profileName] ?? null
+        }
+      };
+    }
+
+    return {
+      data: {
+        profiles: gatesConfig.profiles
+      }
+    };
+  }
+
+  gateProfileAndMode(profileName: string, mode: string): AnyRecord {
+    const profile = this.port.getGatesConfig().profiles[profileName];
+    if (!profile || !profile.modes?.[mode]) {
+      throw {
+        normalizedResponse: fail(ERROR_CODES.UNKNOWN_GATE_PROFILE_OR_MODE, 'Unknown gate profile or mode', {
+          profile: profileName,
+          mode,
+          retryable: false,
+          requires_human: true
+        })
+      };
+    }
+    return profile;
+  }
+
+  async gatesRun(
+    featureId: string,
+    profileName: string | null,
+    mode: string
+  ): Promise<{
+    data: {
+      feature_id: string;
+      mode: string;
+      profile: string;
+      overall: string;
+      coverage: unknown;
+      evidence_path: string;
+    };
+    evidence: { log_path: string };
+  }> {
+    const state = await this.port.readState(featureId);
+    const effectiveProfileName = profileName ?? state.frontMatter.gate_profile ?? 'default';
+    const profile = this.gateProfileAndMode(effectiveProfileName, mode);
+    const repoRoot = this.port.getRepoRoot();
+
+    const runResult = (await runGateMode({
+      featureId,
+      mode,
+      profileName: effectiveProfileName,
+      profile,
+      policy: this.port.getPolicySnapshot() as Parameters<typeof runGateMode>[0]['policy'],
+      worktreePath: this.port.worktreePath(featureId),
+      logDirectory: this.port.logsPath(featureId),
+      evidenceDirectory: this.port.evidencePath(featureId)
+    })) as GateRunResult;
+
+    const nextStateStatus = deriveStatusFromGateResult(state.frontMatter.status, mode, runResult.overall);
+
+    await this.port.updateState(featureId, state.frontMatter.version, (frontMatter, body) =>
+      Promise.resolve({
+        frontMatter: {
+          status: nextStateStatus,
+          status_reason: runResult.overall === 'fail' ? `Gate mode ${mode} failed` : frontMatter.status_reason,
+          gates: {
+            ...frontMatter.gates,
+            [mode]: runResult.overall === 'pass' ? GATE_RESULT.PASS : GATE_RESULT.FAIL
+          },
+          evidence: {
+            last_gate_mode: mode,
+            last_gate_evidence_path: normalizeRepoPathForState(repoRoot, runResult.evidence_path),
+            coverage_status: runResult.coverage_status
+          }
+        },
+        body
+      })
+    );
+
+    if (runResult.overall === 'fail' && runResult.coverage_status === 'fail') {
+      throw {
+        normalizedResponse: fail(
+          ERROR_CODES.COVERAGE_BELOW_MINIMUM,
+          'Coverage thresholds not met',
+          {
+            feature_id: featureId,
+            mode,
+            coverage: runResult.coverage,
+            thresholds: runResult.thresholds,
+            retryable: true,
+            requires_human: false
+          },
+          {
+            log_path: normalizeRepoPathForState(repoRoot, runResult.latest_path)
+          }
+        )
+      };
+    }
+
+    return {
+      data: {
+        feature_id: featureId,
+        mode,
+        profile: effectiveProfileName,
+        overall: runResult.overall,
+        coverage: runResult.coverage,
+        evidence_path: normalizeRepoPathForState(repoRoot, runResult.evidence_path)
+      },
+      evidence: {
+        log_path: normalizeRepoPathForState(repoRoot, runResult.latest_path)
+      }
+    };
+  }
+
+  async evidenceLatest(featureId: string): Promise<{ data: { feature_id: string; latest: AnyRecord | null; path?: string } }> {
+    const repoRoot = this.port.getRepoRoot();
+    const evidenceDir = this.port.evidencePath(featureId);
+    if (!(await pathExists(evidenceDir))) {
+      return {
+        data: {
+          feature_id: featureId,
+          latest: null
+        }
+      };
+    }
+
+    const files = (await fs.readdir(evidenceDir))
+      .filter((file) => file.endsWith('.json'))
+      .map((file) => path.join(evidenceDir, file));
+
+    if (files.length === 0) {
+      return {
+        data: {
+          feature_id: featureId,
+          latest: null
+        }
+      };
+    }
+
+    const withStats = await Promise.all(
+      files.map(async (file) => {
+        const stat = await fs.stat(file);
+        return { file, mtimeMs: stat.mtimeMs };
+      })
+    );
+
+    withStats.sort((a, b) => b.mtimeMs - a.mtimeMs);
+    const latestFile = withStats[0].file;
+    const latest = JSON.parse(await fs.readFile(latestFile, 'utf8'));
+
+    return {
+      data: {
+        feature_id: featureId,
+        latest,
+        path: normalizeRepoPathForState(repoRoot, latestFile)
+      }
+    };
+  }
+}

package/apps/control-plane/src/application/services/lock-service.ts

@@ -0,0 +1,298 @@
+import crypto from 'node:crypto';
+import { nowIso, pathExists } from '../../core/fs.js';
+import { ERROR_CODES } from '../../core/error-codes.js';
+import { fail } from '../../core/response.js';
+import { STATUS } from '../../core/constants.js';
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type AnyRecord = Record<string, any>;
+
+type StateUpdater = (
+  frontMatter: AnyRecord,
+  body: string
+) => Promise<{ frontMatter?: AnyRecord; body?: string }>;
+
+interface CollisionQueueDrivePort {
+  reDriveBlockedQueue(): Promise<{ data: { processed: number; retried: number; still_blocked: number } }>;
+}
+
+export interface LockServicePort {
+  withIndexLock<T>(operation: () => Promise<T>): Promise<T>;
+  readIndex(): Promise<AnyRecord>;
+  writeIndex(index: AnyRecord): Promise<void>;
+  updateState(featureId: string, expectedVersion: number | null, updater: StateUpdater): Promise<AnyRecord>;
+  statePath(featureId: string): string;
+  getPolicySnapshot(): AnyRecord;
+  collisionQueueService?: CollisionQueueDrivePort;
+}
+
+function normalizeSet(array: string[]): string[] {
+  return [...new Set(array)].sort((a, b) => a.localeCompare(b));
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export class LockService {
+  private readonly port: LockServicePort;
+
+  constructor(port: LockServicePort) {
+    this.port = port;
+  }
+
+  async locksAcquire(resource: string | null, featureId: string | null, waitTimeoutSeconds: number | null = null) {
+    const policy = this.port.getPolicySnapshot();
+
+    if (!resource || !policy.locks.resources.includes(resource)) {
+      throw {
+        normalizedResponse: fail(ERROR_CODES.INVALID_ARGUMENT, 'Unknown lock resource', {
+          resource,
+          retryable: false,
+          requires_human: true
+        })
+      };
+    }
+
+    if (!featureId) {
+      throw {
+        normalizedResponse: fail(ERROR_CODES.INVALID_ARGUMENT, 'feature_id is required', {
+          retryable: false,
+          requires_human: true
+        })
+      };
+    }
+
+    const behavior = policy.locks.acquire_behavior ?? 'wait';
+    const timeoutMs = (waitTimeoutSeconds ?? policy.locks.default_wait_timeout_seconds) * 1000;
+    const backoffCfg = policy.locks.acquire_backoff;
+    let backoffMs = backoffCfg.initial_ms;
+    const started = Date.now();
+
+    while (true) {
+      const result: AnyRecord = await this.port.withIndexLock(async () => {
+        const index = await this.port.readIndex();
+        const holder = index.locks[resource];
+        const lease = index.lock_leases[resource];
+
+        let staleReclaimed = false;
+        if (holder && lease && new Date(lease.expires_at).getTime() < Date.now()) {
+          staleReclaimed = true;
+          index.locks[resource] = null;
+          index.lock_leases[resource] = null;
+        }
+
+        if (!index.locks[resource] || index.locks[resource] === featureId) {
+          const leaseId = crypto.randomUUID();
+          const expiresAt = new Date(Date.now() + policy.locks.lease_ttl_seconds * 1000).toISOString();
+          index.locks[resource] = featureId;
+          index.lock_leases[resource] = {
+            holder: featureId,
+            lease_id: leaseId,
+            expires_at: expiresAt
+          };
+          index.version += 1;
+          index.updated_at = nowIso();
+          await this.port.writeIndex(index);
+
+          await this.port.updateState(featureId, null, (frontMatter, body) =>
+            Promise.resolve({
+              frontMatter: {
+                locks: {
+                  held: normalizeSet([...(frontMatter.locks?.held ?? []), resource])
+                }
+              },
+              body
+            })
+          );
+
+          return {
+            acquired: true,
+            staleReclaimed,
+            lease_id: leaseId,
+            expires_at: expiresAt
+          };
+        }
+
+        return {
+          acquired: false,
+          holder: index.locks[resource]
+        };
+      });
+
+      if (result.acquired) {
+        return {
+          data: {
+            resource,
+            feature_id: featureId,
+            lease_id: result.lease_id,
+            expires_at: result.expires_at,
+            stale_reclaimed: result.staleReclaimed
+          },
+          evidence: result.staleReclaimed
+            ? {
+                code: ERROR_CODES.STALE_LOCK_RECLAIMED,
+                message: `Reclaimed stale lock for ${resource}`
+              }
+            : undefined
+        };
+      }
+
+      if (behavior === 'fail') {
+        throw {
+          normalizedResponse: fail(ERROR_CODES.LOCK_CONFLICT, 'Lock is held by another feature', {
+            resource,
+            holder: result.holder,
+            retryable: true,
+            requires_human: false
+          })
+        };
+      }
+
+      if (Date.now() - started > timeoutMs) {
+        throw {
+          normalizedResponse: fail(ERROR_CODES.LOCK_CONFLICT, 'Timed out waiting for lock', {
+            resource,
+            retryable: true,
+            requires_human: false
+          })
+        };
+      }
+
+      await sleep(backoffMs + Math.floor(Math.random() * (backoffCfg.jitter_ms ?? 0)));
+      backoffMs = Math.min(backoffCfg.max_ms, Math.floor(backoffMs * backoffCfg.multiplier));
+    }
+  }
+
+  async locksRelease(resource: string | null, featureId: string | null) {
+    if (!resource || !featureId) {
+      throw {
+        normalizedResponse: fail(ERROR_CODES.INVALID_ARGUMENT, 'resource and feature_id are required', {
+          retryable: false,
+          requires_human: true
+        })
+      };
+    }
+
+    await this.port.withIndexLock(async () => {
+      const index = await this.port.readIndex();
+      const holder = index.locks[resource];
+      if (holder && holder !== featureId) {
+        throw {
+          normalizedResponse: fail(ERROR_CODES.LOCK_CONFLICT, 'Cannot release lock held by another feature', {
+            resource,
+            holder,
+            retryable: false,
+            requires_human: true
+          })
+        };
+      }
+
+      index.locks[resource] = null;
+      index.lock_leases[resource] = null;
+      index.version += 1;
+      index.updated_at = nowIso();
+      await this.port.writeIndex(index);
+    });
+
+    await this.port.updateState(featureId, null, (frontMatter, body) =>
+      Promise.resolve({
+        frontMatter: {
+          locks: {
+            held: (frontMatter.locks?.held ?? []).filter((item) => item !== resource)
+          }
+        },
+        body
+      })
+    );
+
+    if (this.port.collisionQueueService) {
+      await this.port.collisionQueueService.reDriveBlockedQueue().catch(() => ({
+        data: { processed: 0, retried: 0, still_blocked: 0 }
+      }));
+    }
+
+    return {
+      data: {
+        resource,
+        feature_id: featureId,
+        released: true
+      }
+    };
+  }
+
+  async renewLeases(featureIds: string[]): Promise<void> {
+    const policy = this.port.getPolicySnapshot();
+    const set = new Set(featureIds);
+    await this.port.withIndexLock(async () => {
+      const index = await this.port.readIndex();
+      let changed = false;
+      for (const [resource, lease] of Object.entries(index.lock_leases as Record<string, AnyRecord>)) {
+        if (!lease || !set.has(lease.holder)) {
+          continue;
+        }
+        index.lock_leases[resource] = {
+          ...lease,
+          expires_at: new Date(Date.now() + policy.locks.lease_ttl_seconds * 1000).toISOString()
+        };
+        changed = true;
+      }
+      if (changed) {
+        index.version += 1;
+        index.updated_at = nowIso();
+        await this.port.writeIndex(index);
+      }
+    });
+  }
+
+  async recoverFromState(): Promise<{ data: { recovered: boolean; stale_features: string[]; active: unknown } }> {
+    const index = await this.port.readIndex();
+    const staleFeatures: string[] = [];
+
+    await this.port.withIndexLock(async () => {
+      const current = await this.port.readIndex();
+      for (const [resource, lease] of Object.entries(current.lock_leases as Record<string, AnyRecord>)) {
+        if (!lease) {
+          continue;
+        }
+        if (new Date(lease.expires_at).getTime() < Date.now()) {
+          const holder = lease.holder;
+          if (typeof holder === 'string' && holder.length > 0) {
+            staleFeatures.push(holder);
+          }
+          current.lock_leases[resource] = null;
+          current.locks[resource] = null;
+        }
+      }
+      if (staleFeatures.length > 0) {
+        current.version += 1;
+        current.updated_at = nowIso();
+        await this.port.writeIndex(current);
+      }
+    });
+
+    for (const featureId of normalizeSet(staleFeatures)) {
+      const statePath = this.port.statePath(featureId);
+      if (!(await pathExists(statePath))) {
+        continue;
+      }
+      await this.port.updateState(featureId, null, (frontMatter, body) =>
+        Promise.resolve({
+          frontMatter: {
+            status: STATUS.BLOCKED,
+            status_reason: 'Lease expired and was reclaimed'
+          },
+          body
+        })
+      );
+    }
+
+    return {
+      data: {
+        recovered: true,
+        stale_features: normalizeSet(staleFeatures),
+        active: index.active
+      }
+    };
+  }
+}