agentic-orchestrator 0.1.26 → 0.1.28

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

@@ -0,0 +1,523 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { atomicWriteJson, ensureDir, nowIso, readJson } from '../../core/fs.js';
+import { runGit } from '../../core/git.js';
+import { parseUnifiedDiff } from '../../core/patch.js';
+import type { PatchValidationResult } from './patch-service.js';
+import type { WorktreeWatchdogService } from './worktree-watchdog-service.js';
+
+export type ViolationSeverity = 'info' | 'warning' | 'error' | 'critical';
+export type CheckpointValidationStatus = 'valid' | 'invalid' | 'skipped';
+const INTERACTIVE_METRICS_HISTORY_LIMIT = 200;
+
+export interface InteractiveExecutionConfig {
+  checkpointIntervalMs: number;
+  watchdogPollIntervalMs: number;
+  maxUncommittedChanges: number;
+  validationOnCheckpoint: boolean;
+  revertOnViolation: boolean;
+  violationSeverity: ViolationSeverity;
+}
+
+export interface CreateCheckpointInput {
+  featureId: string;
+  sessionId?: string | null;
+  trigger: 'interval' | 'change_threshold' | 'final';
+}
+
+export interface CheckpointRecord {
+  checkpoint_id: string;
+  timestamp: string;
+  files_changed: string[];
+  validation_status: CheckpointValidationStatus;
+  violations: string[];
+  severity?: ViolationSeverity;
+  diff_snapshot: string;
+}
+
+interface InteractiveCheckpointMetric {
+  recorded_at: string;
+  feature_id: string;
+  checkpoint_id: string;
+  trigger: CreateCheckpointInput['trigger'];
+  validation_status: CheckpointValidationStatus;
+  checkpoint_latency_ms: number;
+  validation_latency_ms: number;
+  diff_capture_latency_ms: number;
+  files_changed: number;
+}
+
+interface InteractiveMetricsSnapshot {
+  schema_version: number;
+  updated_at: string;
+  totals: {
+    checkpoint_count: number;
+    valid_count: number;
+    invalid_count: number;
+    skipped_count: number;
+    files_changed_total: number;
+  };
+  histories: {
+    checkpoint_latency_ms: number[];
+    validation_latency_ms: number[];
+    diff_capture_latency_ms: number[];
+  };
+  latest: InteractiveCheckpointMetric | null;
+}
+
+interface UpdateStateFn {
+  (
+    featureId: string,
+    expectedVersion: number | null,
+    updater: (
+      frontMatter: Record<string, unknown>,
+      body: string,
+    ) => Promise<{ frontMatter?: Record<string, unknown>; body?: string }>,
+  ): Promise<Record<string, unknown>>;
+}
+
+interface CheckpointServiceDependencies {
+  repoRoot: string;
+  featurePathResolver: (featureId: string) => string;
+  worktreePathResolver: (featureId: string) => string;
+  validateDiff: (
+    featureId: string,
+    parsedDiff: ReturnType<typeof parseUnifiedDiff>,
+  ) => Promise<PatchValidationResult>;
+  watchdog: WorktreeWatchdogService;
+  provider: CheckpointProviderPort;
+  readState: (featureId: string) => Promise<{ frontMatter: Record<string, unknown> }>;
+  updateState: UpdateStateFn;
+  config: InteractiveExecutionConfig;
+}
+
+/**
+ * Minimal provider contract used by checkpoint validation for agent notifications.
+ *
+ * This keeps application services decoupled from provider-layer runtime interfaces.
+ */
+export interface CheckpointProviderPort {
+  sendMessage?: (sessionId: string, message: string) => Promise<void>;
+}
+
+function readStringArray(value: unknown): string[] {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return value
+    .filter((item): item is string => typeof item === 'string')
+    .map((item) => item.trim())
+    .filter((item) => item.length > 0);
+}
+
+function extractViolationMessages(error: unknown): string[] {
+  const envelope =
+    error && typeof error === 'object'
+      ? (error as { normalizedResponse?: { error?: { details?: Record<string, unknown> } } })
+          .normalizedResponse
+      : undefined;
+  const details = envelope?.error?.details;
+  if (!details || typeof details !== 'object') {
+    return ['Checkpoint validation failed'];
+  }
+
+  const violations = details['violations'];
+  if (!Array.isArray(violations)) {
+    const message =
+      typeof envelope?.error?.details?.message === 'string' ? envelope.error.details.message : null;
+    return message ? [message] : ['Checkpoint validation failed'];
+  }
+
+  const rendered = violations
+    .map((entry) => {
+      if (!entry || typeof entry !== 'object') {
+        return null;
+      }
+      const pathValue = (entry as { path?: unknown }).path;
+      const reasonValue = (entry as { reason?: unknown }).reason;
+      const normalizedPath = typeof pathValue === 'string' ? pathValue : 'unknown_path';
+      const normalizedReason =
+        typeof reasonValue === 'string' ? reasonValue : 'constraint_violation';
+      return `${normalizedPath}: ${normalizedReason}`;
+    })
+    .filter((value): value is string => typeof value === 'string');
+
+  return rendered.length > 0 ? rendered : ['Checkpoint validation failed'];
+}
+
+function severityRank(severity: ViolationSeverity): number {
+  switch (severity) {
+    case 'info':
+      return 0;
+    case 'warning':
+      return 1;
+    case 'error':
+      return 2;
+    case 'critical':
+      return 3;
+    default:
+      return 1;
+  }
+}
+
+function clampHistory(values: number[]): number[] {
+  if (values.length <= INTERACTIVE_METRICS_HISTORY_LIMIT) {
+    return values;
+  }
+  return values.slice(values.length - INTERACTIVE_METRICS_HISTORY_LIMIT);
+}
+
+function toFiniteNumberArray(value: unknown): number[] {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return value.filter(
+    (entry): entry is number => typeof entry === 'number' && Number.isFinite(entry),
+  );
+}
+
+function buildEmptyInteractiveMetricsSnapshot(): InteractiveMetricsSnapshot {
+  return {
+    schema_version: 1,
+    updated_at: nowIso(),
+    totals: {
+      checkpoint_count: 0,
+      valid_count: 0,
+      invalid_count: 0,
+      skipped_count: 0,
+      files_changed_total: 0,
+    },
+    histories: {
+      checkpoint_latency_ms: [],
+      validation_latency_ms: [],
+      diff_capture_latency_ms: [],
+    },
+    latest: null,
+  };
+}
+
+/**
+ * Captures and validates interactive-mode checkpoints against plan/policy/locks.
+ */
+export class CheckpointService {
+  private readonly repoRoot: string;
+  private readonly featurePathResolver: (featureId: string) => string;
+  private readonly worktreePathResolver: (featureId: string) => string;
+  private readonly validateDiff: (
+    featureId: string,
+    parsedDiff: ReturnType<typeof parseUnifiedDiff>,
+  ) => Promise<PatchValidationResult>;
+  private readonly watchdog: WorktreeWatchdogService;
+  private readonly provider: CheckpointProviderPort;
+  private readonly readState: (
+    featureId: string,
+  ) => Promise<{ frontMatter: Record<string, unknown> }>;
+  private readonly updateState: UpdateStateFn;
+  private readonly config: InteractiveExecutionConfig;
+  private readonly inFlightByFeature = new Map<string, Promise<void>>();
+
+  constructor(dependencies: CheckpointServiceDependencies) {
+    this.repoRoot = dependencies.repoRoot;
+    this.featurePathResolver = dependencies.featurePathResolver;
+    this.worktreePathResolver = dependencies.worktreePathResolver;
+    this.validateDiff = dependencies.validateDiff;
+    this.watchdog = dependencies.watchdog;
+    this.provider = dependencies.provider;
+    this.readState = dependencies.readState;
+    this.updateState = dependencies.updateState;
+    this.config = dependencies.config;
+  }
+
+  async createCheckpoint(input: CreateCheckpointInput): Promise<{
+    checkpoint: CheckpointRecord;
+    valid: boolean;
+    blockMerge: boolean;
+  }> {
+    return await this.withFeatureLock(input.featureId, async () => {
+      const checkpointStartedAt = Date.now();
+      const worktreePath = this.worktreePathResolver(input.featureId);
+      const filesChanged = await this.watchdog.getChangedFiles(input.featureId);
+
+      const diffCaptureStartedAt = Date.now();
+      const diffResult = await runGit(this.repoRoot, ['diff', '--no-ext-diff', '--binary'], {
+        cwd: worktreePath,
+      });
+      const diffText = diffResult.code === 0 ? diffResult.stdout : '';
+      const diffCaptureLatencyMs = Date.now() - diffCaptureStartedAt;
+
+      const checkpointId = `checkpoint-${Date.now()}-${crypto.randomUUID().slice(0, 8)}`;
+      const checkpointDir = path.join(this.featurePathResolver(input.featureId), 'checkpoints');
+      await ensureDir(checkpointDir);
+      const checkpointFile = `${checkpointId}.diff`;
+      const checkpointPath = path.join(checkpointDir, checkpointFile);
+      await fs.writeFile(checkpointPath, diffText, 'utf8');
+
+      let validationStatus: CheckpointValidationStatus = 'skipped';
+      let violations: string[] = [];
+      let severity: ViolationSeverity | undefined;
+      let validationResult: PatchValidationResult | null = null;
+      let validationLatencyMs = 0;
+
+      if (this.config.validationOnCheckpoint && diffText.trim().length > 0) {
+        const validationStartedAt = Date.now();
+        try {
+          const parsedDiff = parseUnifiedDiff(diffText);
+          validationResult = await this.validateDiff(input.featureId, parsedDiff);
+          validationStatus = validationResult.valid ? 'valid' : 'invalid';
+          violations = validationResult.violations;
+        } catch (error) {
+          validationStatus = 'invalid';
+          violations = extractViolationMessages(error);
+        } finally {
+          validationLatencyMs = Date.now() - validationStartedAt;
+        }
+      }
+
+      if (validationStatus === 'invalid') {
+        severity = this.config.violationSeverity;
+        await this.notifyAgent(input, checkpointId, filesChanged, violations, severity);
+        if (this.config.revertOnViolation && filesChanged.length > 0) {
+          await runGit(this.repoRoot, ['checkout', '--', ...filesChanged], {
+            cwd: worktreePath,
+          });
+        }
+      }
+
+      const checkpointRecord: CheckpointRecord = {
+        checkpoint_id: checkpointId,
+        timestamp: nowIso(),
+        files_changed: filesChanged,
+        validation_status: validationStatus,
+        violations,
+        severity,
+        diff_snapshot: path
+          .join('.aop', 'features', input.featureId, 'checkpoints', checkpointFile)
+          .replaceAll('\\\\', '/'),
+      };
+
+      await this.recordCheckpoint(input.featureId, checkpointRecord);
+      this.watchdog.resetChangeCount(input.featureId);
+
+      const checkpointLatencyMs = Date.now() - checkpointStartedAt;
+      await this.recordInteractiveMetrics({
+        recorded_at: checkpointRecord.timestamp,
+        feature_id: input.featureId,
+        checkpoint_id: checkpointRecord.checkpoint_id,
+        trigger: input.trigger,
+        validation_status: checkpointRecord.validation_status,
+        checkpoint_latency_ms: checkpointLatencyMs,
+        validation_latency_ms: validationLatencyMs,
+        diff_capture_latency_ms: diffCaptureLatencyMs,
+        files_changed: filesChanged.length,
+      });
+
+      const blockMerge =
+        validationStatus === 'invalid' &&
+        severity !== undefined &&
+        severityRank(severity) >= severityRank('error');
+
+      return {
+        checkpoint: checkpointRecord,
+        valid: validationResult?.valid ?? validationStatus !== 'invalid',
+        blockMerge,
+      };
+    });
+  }
+
+  async getCheckpoints(featureId: string): Promise<CheckpointRecord[]> {
+    const state = await this.readState(featureId);
+    return this.readCheckpoints(state.frontMatter);
+  }
+
+  private async notifyAgent(
+    input: CreateCheckpointInput,
+    checkpointId: string,
+    filesChanged: string[],
+    violations: string[],
+    severity: ViolationSeverity,
+  ): Promise<void> {
+    if (!input.sessionId || typeof this.provider.sendMessage !== 'function') {
+      return;
+    }
+
+    const payload = {
+      type: 'checkpoint_violation',
+      severity,
+      checkpoint_id: checkpointId,
+      trigger: input.trigger,
+      files_changed: filesChanged,
+      violations,
+      action_taken: this.config.revertOnViolation ? 'reverted' : 'none',
+    };
+
+    try {
+      await this.provider.sendMessage(input.sessionId, JSON.stringify(payload));
+    } catch {
+      // Notification failure must not break checkpoint persistence.
+    }
+  }
+
+  private async recordCheckpoint(featureId: string, checkpoint: CheckpointRecord): Promise<void> {
+    await this.updateState(featureId, null, (frontMatter, body) => {
+      const current = this.readCheckpoints(frontMatter);
+      return Promise.resolve({
+        frontMatter: {
+          execution_mode: frontMatter['execution_mode'] ?? 'interactive',
+          checkpoints: [...current, checkpoint],
+        },
+        body,
+      });
+    });
+  }
+
+  private readCheckpoints(frontMatter: Record<string, unknown>): CheckpointRecord[] {
+    const raw = frontMatter['checkpoints'];
+    if (!Array.isArray(raw)) {
+      return [];
+    }
+    const normalized: CheckpointRecord[] = [];
+    for (const entry of raw) {
+      if (!entry || typeof entry !== 'object') {
+        continue;
+      }
+      const record = entry as Record<string, unknown>;
+      const checkpointId =
+        typeof record['checkpoint_id'] === 'string' ? record['checkpoint_id'] : null;
+      const timestamp = typeof record['timestamp'] === 'string' ? record['timestamp'] : null;
+      const validationStatus =
+        record['validation_status'] === 'valid' ||
+        record['validation_status'] === 'invalid' ||
+        record['validation_status'] === 'skipped'
+          ? record['validation_status']
+          : null;
+      const diffSnapshot =
+        typeof record['diff_snapshot'] === 'string' ? record['diff_snapshot'] : null;
+      if (!checkpointId || !timestamp || !validationStatus || !diffSnapshot) {
+        continue;
+      }
+      const severityValue =
+        record['severity'] === 'info' ||
+        record['severity'] === 'warning' ||
+        record['severity'] === 'error' ||
+        record['severity'] === 'critical'
+          ? (record['severity'] as ViolationSeverity)
+          : undefined;
+      normalized.push({
+        checkpoint_id: checkpointId,
+        timestamp,
+        files_changed: readStringArray(record['files_changed']),
+        validation_status: validationStatus,
+        violations: readStringArray(record['violations']),
+        severity: severityValue,
+        diff_snapshot: diffSnapshot,
+      });
+    }
+    return normalized;
+  }
+
+  private interactiveMetricsPath(): string {
+    return path.join(this.repoRoot, '.aop', 'analytics', 'interactive-mode.json');
+  }
+
+  private normalizeMetricsSnapshot(snapshot: unknown): InteractiveMetricsSnapshot {
+    if (!snapshot || typeof snapshot !== 'object') {
+      return buildEmptyInteractiveMetricsSnapshot();
+    }
+    const record = snapshot as Record<string, unknown>;
+    const totalsRaw =
+      record['totals'] && typeof record['totals'] === 'object'
+        ? (record['totals'] as Record<string, unknown>)
+        : {};
+    const historiesRaw =
+      record['histories'] && typeof record['histories'] === 'object'
+        ? (record['histories'] as Record<string, unknown>)
+        : {};
+    return {
+      schema_version: 1,
+      updated_at: typeof record['updated_at'] === 'string' ? record['updated_at'] : nowIso(),
+      totals: {
+        checkpoint_count:
+          typeof totalsRaw['checkpoint_count'] === 'number' ? totalsRaw['checkpoint_count'] : 0,
+        valid_count: typeof totalsRaw['valid_count'] === 'number' ? totalsRaw['valid_count'] : 0,
+        invalid_count:
+          typeof totalsRaw['invalid_count'] === 'number' ? totalsRaw['invalid_count'] : 0,
+        skipped_count:
+          typeof totalsRaw['skipped_count'] === 'number' ? totalsRaw['skipped_count'] : 0,
+        files_changed_total:
+          typeof totalsRaw['files_changed_total'] === 'number'
+            ? totalsRaw['files_changed_total']
+            : 0,
+      },
+      histories: {
+        checkpoint_latency_ms: toFiniteNumberArray(historiesRaw['checkpoint_latency_ms']),
+        validation_latency_ms: toFiniteNumberArray(historiesRaw['validation_latency_ms']),
+        diff_capture_latency_ms: toFiniteNumberArray(historiesRaw['diff_capture_latency_ms']),
+      },
+      latest:
+        record['latest'] && typeof record['latest'] === 'object'
+          ? (record['latest'] as InteractiveCheckpointMetric)
+          : null,
+    };
+  }
+
+  private async recordInteractiveMetrics(metric: InteractiveCheckpointMetric): Promise<void> {
+    try {
+      const filePath = this.interactiveMetricsPath();
+      await ensureDir(path.dirname(filePath));
+      const existing = await readJson<InteractiveMetricsSnapshot>(filePath, null);
+      const snapshot = this.normalizeMetricsSnapshot(existing);
+
+      snapshot.updated_at = nowIso();
+      snapshot.totals.checkpoint_count += 1;
+      snapshot.totals.files_changed_total += metric.files_changed;
+      if (metric.validation_status === 'valid') {
+        snapshot.totals.valid_count += 1;
+      } else if (metric.validation_status === 'invalid') {
+        snapshot.totals.invalid_count += 1;
+      } else {
+        snapshot.totals.skipped_count += 1;
+      }
+
+      snapshot.histories.checkpoint_latency_ms = clampHistory([
+        ...snapshot.histories.checkpoint_latency_ms,
+        metric.checkpoint_latency_ms,
+      ]);
+      snapshot.histories.validation_latency_ms = clampHistory([
+        ...snapshot.histories.validation_latency_ms,
+        metric.validation_latency_ms,
+      ]);
+      snapshot.histories.diff_capture_latency_ms = clampHistory([
+        ...snapshot.histories.diff_capture_latency_ms,
+        metric.diff_capture_latency_ms,
+      ]);
+      snapshot.latest = metric;
+
+      await atomicWriteJson(filePath, snapshot);
+    } catch {
+      // Performance metrics persistence is best-effort and must not fail checkpoints.
+    }
+  }
+
+  private async withFeatureLock<T>(featureId: string, operation: () => Promise<T>): Promise<T> {
+    const existing = this.inFlightByFeature.get(featureId);
+    if (existing !== undefined) {
+      await existing.catch(() => undefined);
+    }
+
+    let release: (() => void) | null = null;
+    const gate = new Promise<void>((resolve) => {
+      release = resolve;
+    });
+    this.inFlightByFeature.set(featureId, gate);
+
+    try {
+      return await operation();
+    } finally {
+      release?.();
+      if (this.inFlightByFeature.get(featureId) === gate) {
+        this.inFlightByFeature.delete(featureId);
+      }
+    }
+  }
+}

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

@@ -0,0 +1,132 @@
+import { ERROR_CODES } from '../../core/error-codes.js';
+import { fail } from '../../core/response.js';
+import { STATUS, GATE_RESULT } from '../../core/constants.js';
+import type { RuntimeSessionsSnapshot } from '../../core/runtime-sessions.js';
+import { readStringField, readObjectField } from '../../core/utils/field-readers.js';
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type AnyRecord = Record<string, any>;
+
+interface FeatureSendMessageProvider {
+  sendMessage?(sessionId: string, message: string): Promise<void>;
+  getSessionInfo?(sessionId: string): Promise<{ active: boolean; provider: string }>;
+}
+
+export interface FeatureSendMessageServicePort {
+  readState(featureId: string): Promise<{ frontMatter: AnyRecord; body: string; raw: string }>;
+  getRuntimeSessions(): Promise<RuntimeSessionsSnapshot>;
+  getProvider(): FeatureSendMessageProvider | null;
+}
+
+export class FeatureSendMessageService {
+  private readonly port: FeatureSendMessageServicePort;
+
+  constructor(port: FeatureSendMessageServicePort) {
+    this.port = port;
+  }
+
+  private async waitForSessionToBecomeActive(sessionId: string): Promise<void> {
+    const provider = this.port.getProvider();
+    if (!provider?.getSessionInfo) {
+      return;
+    }
+
+    const timeoutMs = 5000;
+    const pollIntervalMs = 250;
+    const deadline = Date.now() + timeoutMs;
+
+    while (Date.now() <= deadline) {
+      const sessionInfo = await provider.getSessionInfo(sessionId).catch(() => null);
+      if (sessionInfo?.active) {
+        return;
+      }
+      await new Promise<void>((resolve) => {
+        setTimeout(resolve, pollIntervalMs);
+      });
+    }
+  }
+
+  async featureSendMessage(featureId: string | null, message: string | null): Promise<unknown> {
+    if (!featureId) {
+      throw {
+        normalizedResponse: fail(ERROR_CODES.INVALID_ARGUMENT, 'feature_id is required', {
+          retryable: false,
+          requires_human: false,
+        }),
+      };
+    }
+    if (!message) {
+      throw {
+        normalizedResponse: fail(
+          ERROR_CODES.INVALID_ARGUMENT,
+          'message is required and must not be empty',
+          { retryable: false, requires_human: false },
+        ),
+      };
+    }
+
+    const runtimeSessions = await this.port.getRuntimeSessions();
+    const featureSession = runtimeSessions.feature_sessions?.[featureId];
+    if (!featureSession) {
+      throw {
+        normalizedResponse: {
+          ok: false,
+          error: { code: 'session_not_found', message: 'No active session cluster for feature' },
+        },
+      };
+    }
+
+    const state = await this.port.readState(featureId);
+    const status = typeof state.frontMatter.status === 'string' ? state.frontMatter.status : '';
+    const gates = readObjectField(state.frontMatter, 'gates');
+
+    let targetRole = 'orchestrator';
+    let targetSessionId = runtimeSessions.orchestrator_session_id;
+
+    if (status === STATUS.PLANNING) {
+      targetRole = 'planner';
+      targetSessionId = featureSession.planner_session_id;
+    } else if (status === STATUS.BUILDING) {
+      targetRole = 'builder';
+      targetSessionId = featureSession.builder_session_id;
+    } else if (status === STATUS.QA || status === STATUS.READY_TO_MERGE) {
+      targetRole = 'qa';
+      targetSessionId = featureSession.qa_session_id;
+    } else if (status === STATUS.BLOCKED) {
+      const fastGate = readStringField(gates, 'fast');
+      const fullGate = readStringField(gates, 'full');
+      if (fastGate === GATE_RESULT.FAIL && fullGate !== GATE_RESULT.FAIL) {
+        targetRole = 'builder';
+        targetSessionId = featureSession.builder_session_id;
+      } else {
+        targetRole = 'qa';
+        targetSessionId = featureSession.qa_session_id;
+      }
+    }
+
+    if (!targetSessionId || targetSessionId === 'unassigned' || targetSessionId === 'unknown') {
+      targetRole = 'orchestrator';
+      targetSessionId = runtimeSessions.orchestrator_session_id;
+    }
+
+    const provider = this.port.getProvider();
+    if (!provider?.sendMessage) {
+      throw {
+        normalizedResponse: {
+          ok: false,
+          error: { code: 'provider_unsupported', message: 'Provider does not support sendMessage' },
+        },
+      };
+    }
+
+    await this.waitForSessionToBecomeActive(targetSessionId);
+    await provider.sendMessage(targetSessionId, message);
+    return {
+      feature_id: featureId,
+      session_id: targetSessionId,
+      target_role: targetRole,
+      status,
+      delivered: true,
+    };
+  }
+}

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

@@ -67,6 +67,12 @@ export interface PatchServicePort {
   ): Promise<AnyRecord>;
 }
 
+export interface PatchValidationResult {
+  valid: boolean;
+  violations: string[];
+  changed_files: string[];
+}
+
 /**
  * Manages patch validation and atomic application.
  *
@@ -313,11 +319,7 @@ export class PatchService {
     const profile = this.gateSelectionService.resolveProfile(resolvedProfile.profileName);
     const parsedDiff = parseUnifiedDiff(unifiedDiff);
 
-    await this.validatePatchPaths(featureId, parsedDiff, plan);
-    await this.assertPlanLocksHeld(
-      featureId,
-      plan ?? { contracts: { openapi: 'none', events: 'none', db: 'none' } },
-    );
+    await this.validateDiff(featureId, parsedDiff, plan);
 
     const repoRoot = this.port.getRepoRoot();
     const worktree = this.port.worktreePath(featureId);
@@ -387,4 +389,26 @@ export class PatchService {
       },
     };
   }
+
+  async validateDiff(
+    featureId: string,
+    parsedDiff: unknown,
+    planOverride?: AnyRecord | null,
+  ): Promise<PatchValidationResult> {
+    const plan = planOverride ?? (await this.loadAcceptedPlan(featureId));
+    const changedFiles = await this.validatePatchPaths(
+      featureId,
+      parsedDiff as ReturnType<typeof parseUnifiedDiff>,
+      plan,
+    );
+    await this.assertPlanLocksHeld(
+      featureId,
+      plan ?? { contracts: { openapi: 'none', events: 'none', db: 'none' } },
+    );
+    return {
+      valid: true,
+      violations: [],
+      changed_files: changedFiles,
+    };
+  }
 }