Add reusable experiment support across runs

[Cedric Vidal (cedricvidal)]

Summary

Split the reusable experiment-support layer from #1031 into a standalone change targeting main.

• Add optional experimentId request/response types and persistence, exact or missing-value filtering, two-phase server grouping, and bulk-resubmission preservation.
• Add CLI and Portal submission, list, filter, grouping, member-fetch, column, summary, clone, and detail support while keeping Portal/CLI capability parity.
• Add Cosmos-compatible migration 031 with a sparse single-field requests.experimentId index, required-migration registration, focused tests, generated OpenAPI, and CLI command snapshots.
• Document experiment correlation, filtering, grouping, resubmission, and indexing without including GEPA-specific optimizer behavior.

Demos

N/A — no recording was produced for this extracted capability PR.

Before

N/A

After

N/A

Testing

Passed:

• pnpm test apps/api/src/endpoints.test.ts apps/api/src/grouping.test.ts apps/api/src/routes/requests/run-query.test.ts packages/db-migrations/src/031-add-experiment-id-index.test.ts packages/db-migrations/src/check-migrations.test.ts — focused API/filter/grouping/migration tests passed (229 tests across the executed focused runs).
• pnpm test apps/cli/src/commands/run.test.ts apps/cli/src/cli-commands.test.ts apps/api/src/openapi-snapshot.test.ts — CLI and generated snapshot tests passed.
• pnpm --filter api generate:openapi && pnpm test -u apps/api/src/openapi-snapshot.test.ts apps/cli/src/cli-commands.test.ts && pnpm test apps/api/src/openapi-snapshot.test.ts apps/cli/src/cli-commands.test.ts — regenerated and verified OpenAPI and CLI snapshots.
• pnpm --filter shared build
• pnpm --filter telemetry build && pnpm --filter api build
• pnpm --filter cli build
• pnpm --filter portal build
• pnpm --filter db-migrations build
• pnpm --filter portal lint
• pnpm headers:check
• git diff --check
• Reviewed origin/main...HEAD: exactly 21 experiment-support files; no apps/gepa-optimizer/**, GEPA CI/config, root optimizer docs, or GEPA-specific content.

Not runnable in this checkout: pnpm --filter shared lint and pnpm --filter api lint because the repository install does not provide the eslint executable. The equivalent TypeScript builds and focused tests above passed.

Documentation and compatibility

Updated docs/architecture/app-design.md with the experiment correlation/filtering/grouping contract and migration 031 index behavior.

This is additive and backward-compatible: experimentId is optional, existing runs remain unchanged, and the sparse index avoids entries for runs without an experiment. Deploy migration 031 before relying on experiment-filter query efficiency.

Checklist

• If Portal features changed, keep CLI capabilities in sync.
• If Portal components changed, update their Storybook stories. — N/A: only page-level flows changed; there are no corresponding component stories.
• If database changes require a migration, include up() / down() and keep it CosmosDB-compatible.
• If dependencies changed, update the lockfile and regenerate NOTICE / NOTICE-REVIEW.txt with pnpm notice as needed. — N/A: no dependency changes.
• Video showing the behavior before the suggested change — N/A: additive extracted capability.
• Video showing the behavior after the suggested change — N/A: no recording produced.

[github-actions]

Test Results (Node.js 22)

test: Run #256

Tests 📝	Passed ✅	Failed ❌	Skipped ⏭️	Pending ⏳	Other ❓	Flaky 🍂	Duration ⏱️
3235	3235	0	0	0	0	0	1m30s

🎉 All tests passed!

Github Test Reporter

[Wassim Chegham (manekinekko)]

Requesting changes for the Cosmos-incompatible index migration and the reserved experiment-key collision. The experiment badge placement is non-blocking. These findings came from the end-to-end review of dependent #1031 and belong on this originating PR.

[Wassim Chegham (manekinekko)]

[P2] Create a Cosmos-supported index and propagate real migration failures

Cosmos DB for MongoDB does not support sparse indexes. This requests a sparse index, then catches every creation error and lets up() resolve successfully. The migration can therefore be recorded as applied, and readiness can pass, without the experiment index. A mocked unsupported-index rejection reproduces the false-success behavior; permission and transient failures are swallowed too.

Please use a supported non-sparse index on Cosmos, tolerate only recognized idempotency conditions, and verify the installed index before declaring success. The repository's migration 029 already handles this sparse-index compatibility distinction.

[Wassim Chegham (manekinekko)]

[P2] Prevent real experiment IDs from colliding with the missing-value sentinel

Creation accepts experimentId: "no-experiment", but this removes that real value from the phase-two keys and substitutes only missing/null predicates. For ?groupBy=experiment&experimentId=no-experiment, the resulting match requires both experimentId === "no-experiment" and an absent/null value, so the group disappears. Without the filter, the real experiment also collides with the missing-value bucket. The Portal member-fetch helper interprets this same key as __empty__.

Please reject reserved sentinel IDs at creation or use collision-free group keys consistently in pagination and member fetching. Add a case with a real experiment named no-experiment, not just documents lacking the field.

[Wassim Chegham (manekinekko)]

[P3] Display experiment metadata independently of AGENTS.md

This badge is inside the enclosing run.agentsMdPromptId guard. Runs with an experiment ID but no AGENTS.md therefore never show their experiment on the detail page, even though those fields are independent. This includes the GEPA optimizer's empty seed, which deliberately omits AGENTS.md.

Please render the experiment ID in the general run metadata, outside the AGENTS.md card, so baseline and ordinary experiment runs expose the same correlation information.

[Cedric Vidal (cedricvidal)]

Wassim Chegham (@manekinekko) this PR is not yet ready for review, I accidently opened it

[Cedric Vidal (cedricvidal)]

Historical recovery reference: the correlation-only Experiment support here is superseded by the canonical Experiment model beginning at #1512; the adapted GEPA layer remains #1031. The complete chain is registered in native stack #1518. This PR remains open and unchanged for recovery/history.