Story-2790 · functions lane · read contract

Matter intake can load the right participant roles

The Add-Matter form can now request the pickable participant labels configured for one matter type, in the order defined by the firm's mapping catalog.

Endpoint contract

GET /app/matter-types/{matter_type_id}/participant-labels requires matters:read and returns a response-only DTO:

{
  "participantLabels": [
    {
      "participantLabelId": "…",
      "participantLabelNumber": 2,
      "participantLabelNumberFormatted": "PL-002",
      "name": "Claimant",
      "ordering": 1
    }
  ]
}

The OpenAPI snapshot and generated permission map carry the new path, schemas, operation ID, and permission requirement.

Selection and isolation rules

Matter type	Must be live and visible inside the caller's firm-scoped RLS session. Foreign or unavailable IDs return the same 404.
Mapping	Must have `is_client_side_option = true`.
Participant label	Must be live, so archived catalog rows do not appear in a picker.
Ordering	Sorted by mapping `ordering`, with the firm-local label number as a deterministic tie-breaker.

Acceptance evidence

Contract	Full response DTO round-trip validates every field and camelCase alias.
Picker behavior	Integration coverage rejects non-client and archived options, then proves requested ordering.
Firm isolation	A second firm's caller receives 404 for the first firm's matter type and can read only its own mapping.
Authorization	A caller without `matters:read` receives 403.
Query shape	One option and five options produce the same request query count.

Scope and rollback

This Story adds one read route, response DTOs, a firm-scoped service query, contract artifacts, and focused tests. It adds no migration, enum, write path, cloud capability, or compatibility mechanism. Rollback removes the route and its generated contract entries; catalog data remains unchanged.

Governing issue: pramaan-spec#2790.