Story-1084 | functions lane | walkthrough

Participant Labels become a firm-owned catalog

The backend now has a dedicated settings catalog for labels like Claimant, Respondent, Witness, and Counsel. Each firm gets its own list, its own numbering, and its own archive/delete lifecycle.

Why this exists

Participant labels are vocabulary. If they stay hidden inside matter templates or matter snapshots, a firm cannot manage them as reusable settings. Story-1084 creates the catalog first, before later tickets wire it into templates or runtime matter rows.

Important boundary: this story creates business.participant_labels. It does not modify business.matter_participant_labels, which remains the legacy matter-owned snapshot table for now.

Behavior

Create: a firm admin creates a label and receives a firm-local reference such as PL-001.
List: normal lists show only live labels. Management lists use includeArchived=true.
Archive: archived labels disappear from picker-style lists but remain manageable.
Unarchive: an archived label can return to live.
Delete: delete is logical. The row becomes availability='deleted' and is hidden from app lists.
Guard: if a future durable reference uses a label, delete returns pramaan.participant_label.in_use and the user must archive instead.

Files to read

src/domains/participant_label/entity.py

The table contract: firm ownership, lifecycle fields, numbering, constraints, and indexes.

src/domains/participant_label/service.py

The behavior contract: list, create, update, archive, unarchive, and guarded soft delete.

src/domains/participant_label/router.py

The app API surface under /app/participant-labels, with writes gated by settings:write.

alembic/versions/7e4a9c2d1f08_0082_participant_labels_catalog.py

The database migration: new table, updated-at trigger, RLS policies, app grants, and reference-counter kind.

openapi/app-api.json

The committed API contract that frontend code generation will mirror.

What did not change

This story does not attach participant labels to matter templates, does not migrate old matter labels, and does not change matter creation. It is the settings catalog foundation only.