PR #296 · pramaan-io/pramaan-functions · merged 2026-06-10
A matter born with no proceeding.
Why the Add Matter wizard had to be more than a form.
Matter exists, but has no proceedings — the shell is empty.
The fix — Every matter is born with exactly one Main proceeding — type is derived, forum lives on the case.
Roadmap · Matter Intelligence
sequenceDiagram autonumber participant wizard as Wizard participant matter as Matter service participant proc as Proceeding layer participant db as DB wizard->>matter: Submit case matter->>matter: Create matter cabinet matter->>proc: Auto-create Main type proc->>matter: Type row returned matter->>proc: Auto-create Main proceeding matter->>db: Partial unique on is_main wizard-->>matter: Optional forumId matter->>proc: Forum on the docket, not the cabinet
| Method | in → out | what it does |
|---|---|---|
_party_payload | (parties) → list[dict[str, Any]] | |
_matter_ref | (matter) → str | |
_matter_type_display | (matter) → str |
src/domains/matter/service.py+259 −14Matter service that auto-births the Main proceeding, derives the type display, and validates forum ownership, closing the wizard gap per ADR-1159.
| new method | signature |
|---|---|
_party_payload | (parties) → list[dict[str, Any]] |
_matter_ref | (matter) → str |
_matter_type_display | (matter) → str |
_proceeding_shell_items | (session, matter) → list[MatterProceedingShellItem] |
_detail_view | (session, matter, client_name) → MatterDetailView |
_validate_forum | (session, firm_id, forum_id) → None |
_create_main_proceeding_type | (session, firm_id, matter) → MatterProceedingType |
_create_main_proceeding | (session, firm_id, user_id, matter, main_proceeding_type, forum_id) → Proceeding |
_party_payload_for_matter | (session, firm_id, matter, parties) → list[dict[str, Any]] |
Matter DTOs adding the four-block frame view, proceeding shell items, and party payload fields the wizard contract demands.
| new class | signature |
|---|---|
MatterFrameView | (class) |
MatterProceedingShellItem | (class) |
name : strrole : strparticipant_label_id : UUID | Noneparticipant_label_name : str | Nonecore_dispute_text : str | Noneoutcome_sought_text : str | Nonevalue_at_stake_minor : int | Nonevalue_at_stake_currency : str | Nonevalue_at_stake_not_monetary : boolcase_ref : str | Noneid : UUIDmatter_proceeding_type_id : UUIDforum_id : UUID | Noneproceeding_type_name : strtitle : stris_main : boolstatus : strclosed_at : datetime | Nonematter_ref : strtemplate_name : str | Nonetype : stridentity : MatterListItemframe : MatterFrameViewStaging-safe migration that adds the is_main column and partial unique index so every matter can have exactly one Main proceeding.
| new method | signature |
|---|---|
upgrade | () → None |
downgrade | () → None |
revision : strdown_revision : str | Sequence[str] | Nonebranch_labels : str | Sequence[str] | Nonedepends_on : str | Sequence[str] | NoneProceeding entity extended with the is_main flag the partial unique index guards, marking the universal Main proceeding.
is_main : boolMatter entity adjusted to stop writing new type values and to add the value-at-stake-not-monetary field the wizard frame expects.
matter_type : str | Nonevalue_at_stake_not_monetary : boolProceeding DTO exposing the is_main flag so the detail shell can label the universal Main proceeding in responses.
is_main : bool