feat(server): add PATCH /projects/{project_identifier}/retention

[sahildayal]

Closes #12268

Summary

Adds PATCH /v1/projects/{project_identifier}/retention — set which trace-retention policy a project uses, or reset it to the default.

Retention policies are standalone, reusable entities (ProjectTraceRetentionPolicy) that projects point at via Project.trace_retention_policy_id. This endpoint only changes that pointer: it never creates, edits, or deletes a policy. Policy CRUD stays with the existing GraphQL mutations, per the issue's recommendation to start with reference-by-id only.

API shape

// PATCH /v1/projects/my-project/retention
{ "policy_id": "<ProjectTraceRetentionPolicy GlobalID>" }   // assign
{ "policy_id": null }                                       // reset to the default policy
// 200
{ "data": { "project_id": "<Project GlobalID>", "policy_id": "<GlobalID or null>" } }

policy_id is required but nullable. That is deliberate: with an optional field, "omitted" and "explicitly null" are indistinguishable in Pydantic, and one of those means reset this project's retention. Making it required means a malformed call is a 422 rather than a silent reset. There's a test pinning that.

null maps to trace_retention_policy_id = NULL, which the schema already defines as "use the default policy" — so the response echoes null rather than inventing the default policy's ID.

Errors

• 422 — malformed policy_id, or the field omitted entirely
• 404 — well-formed policy ID that doesn't resolve, or unknown project
• Validation happens before the write, so a failed call leaves the assignment untouched (tested).

Permissions

require_admin + is_not_locked, matching the ADMIN requirement in the issue and the existing update_project / delete_project routes in this router. The underlying GraphQL mutations carry IsAdminIfAuthEnabled as well.

Tests

Nine tests in TestSetProjectRetentionPolicy (tests/unit/server/api/routers/v1/test_projects.py), all passing on SQLite:

• assigns a policy and persists it
• accepts a project GlobalID as the identifier
• null resets to the default policy
• reassigns between two policies
• assignment does not mutate the policy itself — policies are shared, so this guards against a future refactor turning assign into edit
• 404 unknown policy, and the project's assignment is unchanged
• 404 unknown project
• 422 malformed policy_id
• 422 when policy_id is omitted

Also registered the route in _ADMIN_ONLY_ENDPOINTS in tests/integration/_helpers.py — the coverage assert runs at import time, so a missing entry fails the whole integration suite.

I could not run the Postgres matrix locally (no local Postgres/Docker), so that path is covered only by CI here.

Open question from the issue

The issue asks whether this endpoint should also accept an inline policy definition ({"cron_expression": ..., "rule": {...}}) that creates and attaches a policy in one call. I followed the issue's own recommendation and implemented reference-by-id only. Happy to add inline creation if you'd like it, though it does seem like it belongs with policy CRUD rather than here.

Note on overlap

This touches projects.py, as does #15409 (POST /projects/{id}/clear, for #12267). The two add separate handlers in different parts of the file so they should merge independently, but I'm happy to rebase whichever lands second.