[Story-1004] Expose Matter Redesign API contracts

Story 1004Epic 995📜 The Evidentiary RecordMatter Intelligence19 files · +7735/−2849

PR #246 · pramaan-io/pramaan-functions · merged 2026-06-03

How it flows

sequenceDiagram
  autonumber
  participant client as Client
  participant router as App Router
  participant service as Redesign Service
  participant store as DB
  client->>router: POST template-snapshot
  router->>service: create snapshot
  service->>store: resolve firm + matter
  service->>service: copy vocabulary
  store-->>service: frozen view
  service-->>client: snapshot view

app-api.json · +5429 — new methods

Methodin → outwhat it does
MatterRedesignService(class)
_current_user_id(session) → UUID | None
_visible_template_clause(firm_id) → Any

What changed, file by file

src/domains/matter/redesign_service.py+719

Hosts snapshot creation, related matter linking, and carry-forward operations — implements the distinct contracts the PR exposes for the redesign.

new classsignature
MatterRedesignService(class)
_current_user_id(session) → UUID | None
_visible_template_clause(firm_id) → Any
_matter_by_number(session, firm_id, matter_number) → Matter
_visible_template(session, firm_id, matter_template_id) → MatterTemplate
_snapshot_for_matter(session, firm_id, matter) → MatterTemplateSnapshot
_snapshot_proceeding_kind_view(row) → MatterSnapshotProceedingKindView
_snapshot_filing_type_view(row) → MatterSnapshotFilingTypeView
_participant_label_view(row) → MatterParticipantLabelView
_snapshot_view(session, matter, snapshot) → MatterTemplateSnapshotView
create_template_snapshot(session, matter_id, req) → MatterTemplateSnapshotView
_copy_snapshot_vocabulary(session, firm_id, matter, snapshot) → None
get_template_snapshot(session, matter_id) → MatterTemplateSnapshotView
_related_link_view(link, source_number, target_number) → RelatedMatterLinkView
_matter_number_map(session, firm_id, matter_ids) → dict[UUID, int]
_related_link_for_matter(session, firm_id, matter, related_matter_link_id) → RelatedMatterLink
list_related_matters(session, matter_id) → RelatedMatterLinkListResponse
create_related_matter(session, matter_id, req) → RelatedMatterLinkView
_carry_forward_view(row) → RelatedMatterCarryForwardView
list_carry_forward_records(session, matter_id, related_matter_link_id) → RelatedMatterCarryForwardListResponse
create_carry_forward_record(session, matter_id, related_matter_link_id, req) → RelatedMatterCarryForwardView
src/domains/proceeding/service.py+200 −2

Adds list, create, and update for runtime proceeding stages, exposing the user-authored stage timeline through the service layer.

new methodsignature
_stage_view(stage, matter_number) → ProceedingStageView
list_proceeding_stages(session, matter_id, proceeding_id) → ProceedingStageListResponse
create_proceeding_stage(session, matter_id, proceeding_id, req) → ProceedingStageView
update_proceeding_stage(session, matter_id, proceeding_id, stage_id, req) → ProceedingStageView
src/app_api/router_matters.py+174

Wires the redesign service methods to app API routes, exposing snapshot, related matter, proceeding stage, and carry-forward endpoints.

new methodsignature
get_matter_template_snapshot(matter_id, db) → MatterTemplateSnapshotView
create_matter_template_snapshot(matter_id, req, db, _) → MatterTemplateSnapshotView
list_related_matters(matter_id, db) → RelatedMatterLinkListResponse
create_related_matter(matter_id, req, db, _) → RelatedMatterLinkView
list_matter_proceeding_stages(matter_id, proceeding_id, db) → ProceedingStageListResponse
create_matter_proceeding_stage(matter_id, proceeding_id, req, db, _) → ProceedingStageView
update_matter_proceeding_stage(matter_id, proceeding_id, stage_id, req, db, _) → ProceedingStageView
list_related_matter_carry_forward_records(matter_id, related_matter_link_id, db) → RelatedMatterCarryForwardListResponse
create_related_matter_carry_forward_record(matter_id, related_matter_link_id, req, db, _) → RelatedMat
src/domains/matter_type/template_service.py+116

Adds listing and detail operations for matter templates, kept separate from the old matter type semantics per the PR's contract split.

new classsignature
MatterTemplateService(class)
_visible_template_clause(firm_id) → Any
_list_item(template) → MatterTemplateListItem
_detail_view(template) → MatterTemplateDetailView
list_matter_templates(session) → MatterTemplateListResponse
get_matter_template(session, matter_template_id) → MatterTemplateDetailView
src/domains/matter/dtos/related_matter.py+112

Defines request, view, and response DTOs for related matter links and carry-forward or provenance records.

new classsignature
RelatedMatterRelationshipType(class)
RelatedMatterStatus(class)
RelatedMatterCarryForwardSourceKind(class)
RelatedMatterCarryMode(class)
RelatedMatterLinkCreateRequest(class)
trim_notes() → RelatedMatterLinkCreateRequest
RelatedMatterLinkView(class)
RelatedMatterLinkListResponse(class)
RelatedMatterCarryForwardCreateRequest(class)
RelatedMatterCarryForwardView(class)
RelatedMatterCarryForwardListResponse(class)
New fields: target_matter_id : UUIDrelationship_type : RelatedMatterRelationshipTypenotes : str | Noneid : UUIDsource_matter_id : UUIDsource_matter_number : inttarget_matter_number : intstatus : RelatedMatterStatuscreated_by_user_id : UUID | Nonesource_kind : RelatedMatterCarryForwardSourceKindcarry_mode : RelatedMatterCarryModerelated_matter_link_id : UUID
src/domains/matter/dtos/template_snapshot.py+107

Defines DTOs for matter-owned template snapshots, including copied vocabulary views for proceeding kinds, filing types, and participant labels.

new classsignature
MatterSnapshotVocabularyStatus(class)
MatterParticipantLabelAlign(class)
MatterTemplateSnapshotCreateRequest(class)
MatterSnapshotProceedingKindView(class)
MatterSnapshotFilingTypeView(class)
MatterParticipantLabelView(class)
MatterTemplateSnapshotView(class)
New fields: matter_template_id : UUIDsnapshot_reason : strid : UUIDsnapshot_id : UUIDsource_proceeding_kind_id : UUID | Nonekey : strname : strdescription : str | Nonestatus : MatterSnapshotVocabularyStatusdisplay_order : intsource_filing_type_id : UUID | Nonerequired : boolcode : strlabel : stralign : MatterParticipantLabelAlignmatter_id : UUIDmatter_number : inttemplate_version : intmatter_type_id : UUIDtemplate_key : strtemplate_name : strcreated_by_user_id : UUID | None
src/domains/proceeding/dtos/stage.py+65

Defines DTOs for proceeding stages with validators that require a date or timestamp on create.

new classsignature
ProceedingStageStatus(class)
ProceedingStageCreateRequest(class)
require_date_or_timestamp() → ProceedingStageCreateRequest
ProceedingStageUpdateRequest(class)
ProceedingStageView(class)
ProceedingStageListResponse(class)
New fields: stage_key : str | Nonetitle : strdescription : str | Nonestage_date : date | Noneoccurred_at : datetime | Noneposition : intstatus : ProceedingStageStatusid : UUIDmatter_id : UUIDmatter_number : intproceeding_id : UUIDcreated_by_user_id : UUID | Noneupdated_by_user_id : UUID | None
src/domains/matter_type/dtos/matter_template.py+59

Defines list, detail, and response DTOs for matter templates, kept as a separate contract from matter type DTOs.

new classsignature
MatterTemplateSource(class)
MatterTemplateStatus(class)
MatterTemplateListItem(class)
MatterTemplateDetailView(class)
MatterTemplateListResponse(class)
New fields: id : UUIDmatter_type_id : UUIDsource : MatterTemplateSourcekey : strname : strdescription : str | Nonestatus : MatterTemplateStatusversion : intdefault_proceeding_kind_id : UUID | Nonedefault_proceeding_kind_matter_type_id : UUID | Nonetotal : int
src/app_api/router_matter_templates.py+42

Adds app API routes that list matter templates and fetch one by id, exposing the new template contract read endpoints.

new methodsignature
list_matter_templates(db) → MatterTemplateListResponse
get_matter_template(matter_template_id, db) → MatterTemplateDetailView

What does NOT happen

Five contracts stay five contracts
Snapshot freezes source template version
Cross-firm links rejected at the door
Whole-repo ruff still fails on pre-existing Alembic lint debt
Unit tests hit unrelated identity DB privilege issues
Scoped mypy surfaces pre-existing SQLModel typing debt

Files changed (19)

File±
docs/walkthroughs/story-1004-walkthrough.html+108
openapi/app-api.json ★+5429 −2845
src/app_api/app.py+2
src/app_api/router_matter_templates.py+42
src/app_api/router_matters.py+174
src/domains/matter/dtos/__init__.py+38
src/domains/matter/dtos/related_matter.py+112
src/domains/matter/dtos/template_snapshot.py+107
src/domains/matter/entity.py+2 −2
src/domains/matter/redesign_service.py ★+719
src/domains/matter_type/dtos/__init__.py+12
src/domains/matter_type/dtos/matter_template.py+59
src/domains/matter_type/template_service.py+116
src/domains/proceeding/dtos/__init__.py+12
src/domains/proceeding/dtos/stage.py+65
src/domains/proceeding/service.py ★+200 −2
tests/integration/test_app_matter_redesign.py+407
tests/unit/test_matter_redesign_dtos.py+123
tests/unit/test_matter_redesign_schema_migration.py+8