Harden Convex phase result contracts

Author: Ronak-IIITD

UPDATES.md

@@ -2,7 +2,33 @@
 
 ## 0) Last Updated + Changelog
 
-**Last updated:** 2026-05-23
+**Last updated:** 2026-05-25
+
+### 2026-05-25 (Convex Phase Schema Hardening + Agent Contract Alignment)
+**Summary:** Tightened the remaining loose Convex phase-result contracts, aligned the agent’s persisted result types to the real bridge payloads, and fixed a phase 6 report schema mismatch that previously made Convex less compatible than the runtime bridges.
+
+**What changed:**
+1. **Shared Convex phase validators (`convex/phaseValidators.ts`, `convex/schema.ts`, `convex/integrations-mutations.ts`):**
+   - Extracted shared phase validators so the table schema and `savePhaseResult` mutation validate against the same payload definitions.
+   - Replaced the remaining loose `v.any()` phase surfaces with structured validators for repo dependencies/components, transformation change lists, validation comparison payloads, and report subtrees.
+   - Updated `savePhaseResult` to take a typed `{ payload: { field, result } }` object so field/result pairs are validated together instead of accepting any blob.
+2. **Agent payload normalization and typing (`agent/src/bridges/python-subprocess.ts`, `agent/src/api/convex.ts`, `agent/src/orchestrator.ts`):**
+   - Added structured TypeScript result types for persisted phase payloads and removed `unknown` from the Convex wrapper’s phase result API.
+   - Normalized subprocess mapping outputs to preserve target context, confidence breakdowns, and canonical research-spec payloads instead of leaving snake_case/raw extractor objects to drift into persistence.
+   - Normalized patch validation metadata (`schemaVersion`, `payloadType`) and tightened the orchestrator’s Convex handoff to use typed persisted phase results.
+3. **Phase 6 report contract fix (`agent/src/phases/phase6-report.ts`, `agent/src/phases/types.ts`):**
+   - Exported a concrete `Phase6Report` type and aligned `Phase6Context.report` to it.
+   - Fixed the persisted report contract to use the actual `diffPreview` field and full report structure (`whatChanged`, `why`, `observedImpact`, `testResults`, `recommendation`) instead of the stale `{ summary, diff, metadata }` schema.
+4. **Regression coverage (`agent/src/api/convex.test.ts`, `agent/src/bridges/python-subprocess.test.ts`):**
+   - Added a Convex client regression test covering the new nested phase result payload contract.
+   - Added subprocess bridge coverage for normalized mapping context, confidence breakdowns, canonicalized research specs, and validation metadata passthrough.
+
+**Verification:**
+- `cd agent && bun test src/api/convex.test.ts src/bridges/python-subprocess.test.ts src/phases/phase6-report.test.ts`
+- `cd agent && bun run build`
+
+**Notes:**
+- A standalone TypeScript check for `convex/*.ts` was not runnable in this checkout because `convex/_generated/server` is absent, so Convex’s generated type bindings are not available locally.
 
 ### 2026-05-23 (Paper-to-Code PDF Upload Flow)
 **Summary:** Finished the missing PDF upload transport for the Paper-to-Code page and aligned the UI with the backend’s actual patch-generation response.
@@ -52,8 +78,8 @@
 - `cd agent && bun test src/bridges/python-subprocess.test.ts`
 - `cd agent && bun run build`
 
-### 2026-05-23 (CI Failure Fixes — Ruff Format, Test Mock, Benchmark AST Revert)
-**Summary:** Fixed three CI failures: ruff formatting in test files, a test that failed due to incomplete mocking of the validation runner, and a benchmark regression caused by AST-affecting changes to expected benchmark files.
+### 2026-05-23 (CI Failure Fixes — Ruff Format, Test Mock, Benchmark AST Revert, python-multipart Dep)
+**Summary:** Fixed four CI/suite failures: ruff formatting in test files, a test that failed due to incomplete mocking of the validation runner, a benchmark regression caused by AST-affecting changes to expected benchmark files, and a missing `python-multipart` dependency for FastAPI file uploads.
 
 **What changed:**
 1. **Ruff formatting (`core/tests/unit/test_patch_generator.py`, `core/tests/unit/test_cli.py`):**
@@ -62,10 +88,12 @@
    - `test_run_accepts_camel_case_patch_payload` now properly mocks `_check_torch_available`, `_run_training_test`, `_run_numerical_correctness`, `_run_regression_snapshot`, and `_score_diff_readability` — preventing the test from running real benchmark subprocesses and failing when torch is unavailable.
 3. **Benchmark AST revert (`core/benchmarks/expected/*.py`, `core/benchmarks/papers/*.py`):**
    - Reverted N806 variable renames (`B,T,C` -> `b,t,c`) and F401 import removals from benchmark expected/papers files that changed the AST and caused benchmark AST matching failures (score dropped from 1.0 → 0.75 for 5 of 10 cases).
+4. **Missing dependency (`core/pyproject.toml`):**
+   - Added `python-multipart>=0.0.9` to the `product` extras — required by the new PDF upload endpoint (`UploadFile = File(...)`). Without it, importing the server module (and any test importing it) raises a `RuntimeError` at route definition time.
 
 **Verification:**
 - `cd core && ruff check src/ tests/ && ruff format --check src/ tests/`
-- `cd core && python -m pytest tests/unit/test_validation_runner.py tests/unit/test_cli.py tests/unit/test_patch_generator.py -q`
+- `cd core && python -m pytest tests/ -x -q --tb=short`
 
 ### 2026-05-22 (Benchmark Regression + LoRA Smoke Fix)
 **Summary:** Restored benchmark parity after the new smoke-test scaffolding and fixed the generated LoRA runtime contract.

agent/src/api/convex.test.ts

@@ -57,6 +57,68 @@ describe('ConvexClientWrapper auth and approval semantics', () => {
     );
   });
 
+  it('wraps typed phase results in the savePhaseResult payload contract', async () => {
+    const client = new ConvexClientWrapper('https://deployment.example');
+
+    mutationMock.mockResolvedValueOnce(undefined);
+
+    await client.savePhaseResult('integration-id', 6, {
+      metadata: {
+        integrationId: 'integration-id',
+        repoUrl: '/repo',
+        paper: 'Attention Is All You Need',
+        algorithm: 'FlashAttention',
+        createdAt: '2026-05-25T00:00:00.000Z',
+      },
+      summary: {
+        status: 'completed',
+        confidence: 95,
+        changesMade: 2,
+        filesModified: ['src/model.py'],
+        newFiles: ['src/flash_attention.py'],
+      },
+      whatChanged: 'Replaced attention blocks.',
+      why: 'Improves throughput.',
+      observedImpact: {
+        metricsComparison: {
+          speedup: 1.2,
+          numerical_correctness: {
+            status: 'passed',
+          },
+        },
+        meetsExpectations: true,
+      },
+      riskNotes: [],
+      diffPreview: 'Modified: src/model.py',
+      testResults: {
+        unitTestsPassed: true,
+        benchmarkResults: {
+          speedup: 1.2,
+        },
+      },
+      recommendation: {
+        action: 'approve',
+        confidence: 95,
+        notes: 'Ready for integration.',
+      },
+    });
+
+    expect(mutationMock).toHaveBeenCalledWith(
+      'integrations:savePhaseResult',
+      expect.objectContaining({
+        id: 'integration-id',
+        payload: {
+          field: 'phase6Result',
+          result: expect.objectContaining({
+            diffPreview: 'Modified: src/model.py',
+            recommendation: expect.objectContaining({ action: 'approve' }),
+          }),
+        },
+        authKey: 'convex-secret',
+      }),
+    );
+  });
+
   it('waitForApproval only resolves true on explicit approved action for phase', async () => {
     vi.useFakeTimers();
     const client = new ConvexClientWrapper('https://deployment.example');

agent/src/api/convex.ts

@@ -1,4 +1,12 @@
 import { ConvexHttpClient } from 'convex/browser';
+import type {
+  MappingResult,
+  PatchResult,
+  RepoAnalysisResult,
+  ResearchSpecResult,
+  ValidationResult,
+} from '../bridges/python-subprocess.js';
+import type { Phase6Report } from '../phases/phase6-report.js';
 import { logger } from '../utils/logger.js';
 import { config } from '../utils/config.js';
 
@@ -18,6 +26,22 @@ export type IntegrationStatus =
 
 export type ExecutionMode = 'step_approval' | 'autonomous';
 
+export type PhaseResultField =
+  | 'phase1Result'
+  | 'phase2Result'
+  | 'phase3Result'
+  | 'phase4Result'
+  | 'phase5Result'
+  | 'phase6Result';
+
+export type PersistedPhaseResult =
+  | RepoAnalysisResult
+  | ResearchSpecResult
+  | MappingResult
+  | PatchResult
+  | ValidationResult
+  | Phase6Report;
+
 export interface Integration {
   _id: string;
   repoUrl: string;
@@ -27,12 +51,12 @@ export interface Integration {
   mode: ExecutionMode;
   yoloMode?: boolean;
   currentPhase: number;
-  phase1Result?: unknown;
-  phase2Result?: unknown;
-  phase3Result?: unknown;
-  phase4Result?: unknown;
-  phase5Result?: unknown;
-  phase6Result?: unknown;
+  phase1Result?: RepoAnalysisResult;
+  phase2Result?: ResearchSpecResult;
+  phase3Result?: MappingResult;
+  phase4Result?: PatchResult;
+  phase5Result?: ValidationResult;
+  phase6Result?: Phase6Report;
   confidence?: number;
   createdAt: number;
   updatedAt: number;
@@ -64,6 +88,25 @@ export class ConvexClientWrapper {
   private client: ConvexHttpClient;
   private authKey: string;
 
+  private getPhaseResultField(phase: number): PhaseResultField {
+    switch (phase) {
+      case 1:
+        return 'phase1Result';
+      case 2:
+        return 'phase2Result';
+      case 3:
+        return 'phase3Result';
+      case 4:
+        return 'phase4Result';
+      case 5:
+        return 'phase5Result';
+      case 6:
+        return 'phase6Result';
+      default:
+        throw new Error(`Unsupported phase result field for phase ${phase}`);
+    }
+  }
+
   private getAuthArgs(): { authKey: string } {
     if (!this.authKey) {
       throw new Error(`${CONVEX_AUTH_ENV_KEY} is not configured`);
@@ -134,12 +177,14 @@ export class ConvexClientWrapper {
     logger.info('Updated integration status', { id, status, phase, ...details });
   }
 
-  async savePhaseResult(id: string, phase: number, result: unknown): Promise<void> {
-    const field = `phase${phase}Result`;
+  async savePhaseResult(id: string, phase: number, result: PersistedPhaseResult): Promise<void> {
+    const field = this.getPhaseResultField(phase);
     await this.callMutation('integrations:savePhaseResult', {
       id,
-      field,
-      result,
+      payload: {
+        field,
+        result,
+      },
       updatedAt: Date.now(),
     });
   }