Archive v0.3: Model/Test detail, evolution timeline and comparison

apps/api/src/app.ts

@@ -25,7 +25,14 @@ type ControlPlanner = Pick<
 >;
 type ArchiveRepository = Pick<
   PgArchiveRepository,
-  "ping" | "listModels" | "listTests" | "listRuns" | "getRun"
+  | "ping"
+  | "listModels"
+  | "listTests"
+  | "listRuns"
+  | "getRun"
+  | "getModel"
+  | "getTest"
+  | "compareLatest"
 >;
 
 export interface AppDependencies {
@@ -156,6 +163,78 @@ export function createApp(deps: AppDependencies) {
     return c.json({ tests: await deps.archive.listTests() });
   });
 
+  app.get("/v1/archive/models/:modelId", async (c) => {
+    if (!deps.archive) {
+      return c.json({ error: "archive_unavailable" }, 503);
+    }
+
+    const modelId = c.req.param("modelId");
+    if (!UUID_RE.test(modelId)) {
+      return c.json({ error: "invalid_model_id" }, 400);
+    }
+
+    const model = await deps.archive.getModel(modelId);
+    if (!model) {
+      return c.json({ error: "archive_model_not_found" }, 404);
+    }
+
+    return c.json({ model });
+  });
+
+  app.get("/v1/archive/tests/:testCaseId", async (c) => {
+    if (!deps.archive) {
+      return c.json({ error: "archive_unavailable" }, 503);
+    }
+
+    const testCaseId = c.req.param("testCaseId");
+    if (!UUID_RE.test(testCaseId)) {
+      return c.json({ error: "invalid_test_case_id" }, 400);
+    }
+
+    const test = await deps.archive.getTest(testCaseId);
+    if (!test) {
+      return c.json({ error: "archive_test_not_found" }, 404);
+    }
+
+    return c.json({ test });
+  });
+
+  app.get("/v1/archive/compare", async (c) => {
+    if (!deps.archive) {
+      return c.json({ error: "archive_unavailable" }, 503);
+    }
+
+    const rawModelIds = c.req.query("modelIds");
+    const testCaseId = c.req.query("testCaseId");
+    const modelIds = rawModelIds
+      ?.split(",")
+      .map((value) => value.trim())
+      .filter(Boolean);
+
+    if (
+      !modelIds ||
+      modelIds.length < 2 ||
+      modelIds.length > 4 ||
+      new Set(modelIds).size !== modelIds.length ||
+      modelIds.some((modelId) => !UUID_RE.test(modelId))
+    ) {
+      return c.json({ error: "invalid_model_ids" }, 400);
+    }
+    if (!testCaseId || !UUID_RE.test(testCaseId)) {
+      return c.json({ error: "invalid_test_case_id" }, 400);
+    }
+
+    const comparison = await deps.archive.compareLatest({
+      modelIds,
+      testCaseId,
+    });
+    if (!comparison) {
+      return c.json({ error: "archive_comparison_not_found" }, 404);
+    }
+
+    return c.json({ comparison });
+  });
+
   app.get("/v1/archive/runs", async (c) => {
     if (!deps.archive) {
       return c.json({ error: "archive_unavailable" }, 503);

apps/api/test/archive-api.test.ts

@@ -105,6 +105,160 @@ const archiveRun = {
   ],
 } as const;
 
+const archiveModelDetail = {
+  id: MODEL_ID,
+  provider: archiveRun.provider,
+  canonicalSlug: "deepseek-flash",
+  marketingName: "DeepSeek Flash",
+  status: "active",
+  runCount: 1,
+  latestRunAt: archiveRun.completedAt,
+  family: {
+    id: "00000000-0000-4000-8000-000000000031",
+    slug: "deepseek",
+    displayName: "DeepSeek",
+  },
+  track: {
+    id: "00000000-0000-4000-8000-000000000032",
+    slug: "flash",
+    displayName: "Flash",
+    trackType: "fast",
+  },
+  releasedAt: "2026-09-01T00:00:00.000Z",
+  retiredAt: null,
+  canonicalSourceId: "00000000-0000-4000-8000-000000000033",
+  snapshots: [
+    {
+      id: "00000000-0000-4000-8000-000000000034",
+      providerSnapshotId: "deepseek-flash-202609",
+      validFrom: "2026-09-01T00:00:00.000Z",
+      validTo: null,
+      sourceId: "00000000-0000-4000-8000-000000000033",
+    },
+  ],
+  relations: [],
+  testCoverage: [
+    {
+      testCaseId: TEST_CASE_ID,
+      familySlug: archiveRun.test.familySlug,
+      familyName: archiveRun.test.familyName,
+      version: archiveRun.test.version,
+      caseSlug: archiveRun.test.caseSlug,
+      runCount: 1,
+      latestRunAt: archiveRun.completedAt,
+    },
+  ],
+  recentRuns: [archiveRun],
+  timeline: [
+    {
+      id: `run:${RUN_ID}`,
+      kind: "run",
+      occurredAt: archiveRun.completedAt,
+      title: "Run · exact-modelapse",
+      description: "E4 · exact match",
+      runId: RUN_ID,
+      testCaseId: TEST_CASE_ID,
+      snapshotId: null,
+      relatedModelId: null,
+    },
+  ],
+} as const;
+
+const archiveTestDetail = {
+  testCaseId: TEST_CASE_ID,
+  familySlug: archiveRun.test.familySlug,
+  familyName: archiveRun.test.familyName,
+  variantSlug: archiveRun.test.variantSlug,
+  variantName: archiveRun.test.variantName,
+  category: "smoke",
+  artifactType: "text",
+  version: archiveRun.test.version,
+  caseSlug: archiveRun.test.caseSlug,
+  evaluator: {
+    slug: "exact-text",
+    version: "1.0.0",
+    kind: "deterministic",
+  },
+  runCount: 1,
+  origin: "modelapse",
+  canonicalSourceId: null,
+  versionStatus: "published",
+  definitionSha256:
+    "1111111111111111111111111111111111111111111111111111111111111111",
+  license: "Apache-2.0",
+  publishedAt: "2026-09-01T00:00:00.000Z",
+  versionCreatedAt: "2026-08-31T00:00:00.000Z",
+  caseType: "public",
+  caseStatus: "active",
+  activeFrom: "2026-09-01T00:00:00.000Z",
+  activeTo: null,
+  promptSha256:
+    "2222222222222222222222222222222222222222222222222222222222222222",
+  fixtureManifestSha256: null,
+  evaluatorDefinitionSha256: archiveRun.evaluation.definitionSha256,
+  modelCoverage: [
+    {
+      modelId: MODEL_ID,
+      canonicalSlug: "deepseek-flash",
+      marketingName: "DeepSeek Flash",
+      providerSlug: "deepseek",
+      runCount: 1,
+      latestRunAt: archiveRun.completedAt,
+    },
+  ],
+  recentRuns: [archiveRun],
+} as const;
+
+const archiveComparison = {
+  test: {
+    testCaseId: TEST_CASE_ID,
+    familySlug: archiveRun.test.familySlug,
+    familyName: archiveRun.test.familyName,
+    variantSlug: archiveRun.test.variantSlug,
+    variantName: archiveRun.test.variantName,
+    category: "smoke",
+    artifactType: "text",
+    version: archiveRun.test.version,
+    caseSlug: archiveRun.test.caseSlug,
+    evaluator: {
+      slug: "exact-text",
+      version: "1.0.0",
+      kind: "deterministic",
+    },
+    runCount: 1,
+  },
+  rows: [
+    {
+      model: {
+        id: MODEL_ID,
+        provider: archiveRun.provider,
+        canonicalSlug: "deepseek-flash",
+        marketingName: "DeepSeek Flash",
+        status: "active",
+        runCount: 1,
+        latestRunAt: archiveRun.completedAt,
+      },
+      latestRun: archiveRun,
+    },
+    {
+      model: {
+        id: "00000000-0000-4000-8000-000000000035",
+        provider: {
+          id: "00000000-0000-4000-8000-000000000036",
+          slug: "openai",
+          name: "OpenAI",
+        },
+        canonicalSlug: "gpt-test",
+        marketingName: "GPT Test",
+        status: "active",
+        runCount: 0,
+        latestRunAt: null,
+      },
+      latestRun: null,
+    },
+  ],
+} as const;
+
 describe("Archive read API", () => {
   it("exposes public model, test and evaluated Run views without control auth", async () => {
     const app = createApp({
@@ -147,6 +301,11 @@ describe("Archive read API", () => {
         ],
         listRuns: async () => [archiveRun],
         getRun: async (runId) => (runId === RUN_ID ? archiveRun : null),
+        getModel: async (modelId) =>
+          modelId === MODEL_ID ? archiveModelDetail : null,
+        getTest: async (testCaseId) =>
+          testCaseId === TEST_CASE_ID ? archiveTestDetail : null,
+        compareLatest: async () => archiveComparison,
       },
     });
 
@@ -167,6 +326,33 @@ describe("Archive read API", () => {
       ],
     });
 
+    const model = await app.request("/v1/archive/models/" + MODEL_ID);
+    expect(model.status).toBe(200);
+    await expect(model.json()).resolves.toMatchObject({
+      model: {
+        id: MODEL_ID,
+        timeline: [{ kind: "run", runId: RUN_ID }],
+      },
+    });
+
+    const test = await app.request("/v1/archive/tests/" + TEST_CASE_ID);
+    expect(test.status).toBe(200);
+    await expect(test.json()).resolves.toMatchObject({
+      test: {
+        testCaseId: TEST_CASE_ID,
+        definitionSha256: archiveTestDetail.definitionSha256,
+      },
+    });
+
+    const secondModelId = archiveComparison.rows[1].model.id;
+    const comparison = await app.request(
+      `/v1/archive/compare?modelIds=${MODEL_ID},${secondModelId}&testCaseId=${TEST_CASE_ID}`,
+    );
+    expect(comparison.status).toBe(200);
+    await expect(comparison.json()).resolves.toEqual({
+      comparison: archiveComparison,
+    });
+
     const runs = await app.request(
       `/v1/archive/runs?modelId=${MODEL_ID}&testCaseId=${TEST_CASE_ID}&limit=10`,
     );
@@ -187,6 +373,9 @@ describe("Archive read API", () => {
         listTests: async () => [],
         listRuns: async () => [],
         getRun: async () => null,
+        getModel: async () => null,
+        getTest: async () => null,
+        compareLatest: async () => null,
       },
     });
 
@@ -196,5 +385,19 @@ describe("Archive read API", () => {
     expect(
       (await app.request("/v1/archive/runs?limit=101")).status,
     ).toBe(400);
+    expect(
+      (await app.request("/v1/archive/models/nope")).status,
+    ).toBe(400);
+    expect(
+      (await app.request("/v1/archive/tests/nope")).status,
+    ).toBe(400);
+    expect(
+      (
+        await app.request(
+          `/v1/archive/compare?modelIds=${MODEL_ID}&testCaseId=${TEST_CASE_ID}`,
+        )
+      ).status,
+    ).toBe(400);
+
   });
 });