[Story-1003] Add Matter Redesign schema foundation

Story 1003Epic 995📜 The Evidentiary RecordMatter Intelligence9 files · +1616/−26

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

How it flows

sequenceDiagram
  autonumber
  participant firm as Firm
  participant user as User
  participant system as System
  participant matter as Matter
  firm->>firm: Set matter template
  user->>system: Create new matter
  system->>system: Capture MatterTemplateSnapshot
  system->>matter: Freeze proceeding kinds + filing types
  user->>user: Add live ProceedingStage
  user-->>system: Link via RelatedMatterLink

src/domains/{matter_type,matter,proceeding}/entity.py

Methodin → outwhat it does
MatterTemplate(type)setup-time matter creation playbook, versioned per firm
MatterTemplateSnapshot(class)frozen copy of template captured at matter creation
RelatedMatterLink(class)edge between two matters with a typed relationship

What changed, file by file

alembic/versions/2b4c6d8e0f13_0069_matter_redesign_schema_foundation.py+751

Alembic migration that creates the new matter-redesign tables, RLS policies and updated_at triggers for the ADR-zero-ninety schema.

new methodsignature
_enable_template_rls(table_name) → None
_disable_template_rls(table_name) → None
_enable_content_rls(table_name) → None
_disable_content_rls(table_name) → None
_create_updated_at_trigger(table_name) → None
_drop_updated_at_trigger(table_name) → None
upgrade() → None
downgrade() → None
New fields: revision : strdown_revision : str | Sequence[str] | Nonebranch_labels : str | Sequence[str] | Nonedepends_on : str | Sequence[str] | None
src/domains/matter/entity.py+373 −10

Adds SQLModel classes for the matter-owned snapshot, frozen proceeding kinds and filing types, participant labels, and related-matter link and carry-forward.

new classsignature
MatterTemplateSnapshot(class)
MatterSnapshotProceedingKind(class)
MatterSnapshotFilingType(class)
MatterParticipantLabel(class)
RelatedMatterLink(class)
RelatedMatterCarryForward(class)
New fields: id : UUIDfirm_id : UUIDmatter_id : UUIDmatter_template_id : UUIDtemplate_version : intmatter_type_id : UUIDtemplate_key : strtemplate_name : strsnapshot_reason : strcreated_by_user_id : UUID | Nonesnapshot_id : UUIDsource_proceeding_kind_id : UUID | Nonekey : strname : strdescription : str | Nonestatus : strdisplay_order : intsource_filing_type_id : UUID | Nonerequired : boolcode : strlabel : stralign : strsource_matter_id : UUIDtarget_matter_id : UUIDrelationship_type : strnotes : str | Nonerelated_matter_link_id : UUIDsource_kind : strcarry_mode : str
src/domains/matter_type/entity.py+132 −8

Adds the MatterTemplate SQLModel class — the setup-time playbook from which each new matter takes a frozen snapshot.

new classsignature
MatterTemplate(type)
New fields: id : UUIDfirm_id : UUID | Nonematter_type_id : UUIDsource : strkey : strname : strdescription : str | Nonestatus : strversion : intdefault_proceeding_kind_id : UUID | Nonedefault_proceeding_kind_matter_type_id : UUID | None
src/domains/proceeding/entity.py+99 −3

Adds the ProceedingStage SQLModel class for live, user-authored runtime stages within a proceeding, independent of any template.

new classsignature
ProceedingStage(class)
New fields: id : UUIDfirm_id : UUIDmatter_id : UUIDproceeding_id : UUIDstage_key : str | Nonetitle : strdescription : str | Nonestage_date : date | Noneoccurred_at : datetime | Noneposition : intstatus : strcreated_by_user_id : UUID | Noneupdated_by_user_id : UUID | None

What this PR does NOT do

SQLModel classes added
Alembic migration registered
RLS + updated_at triggers
Backfill plan + tests
No endpoint to create matter
No template authoring UI
No app or contract impact
No runtime filing storage

Files changed (9)

File±
alembic/env.py+8 −2
alembic/versions/2b4c6d8e0f13_0069_matter_redesign_schema_foundation.py ★+751
docs/notes/story-1003-backfill-plan.md+42
docs/walkthroughs/story-1003-walkthrough.html+105
src/domains/matter/entity.py ★+373 −10
src/domains/matter_type/entity.py ★+132 −8
src/domains/proceeding/entity.py+99 −3
src/shared/db/entities.py+22 −3
tests/unit/test_matter_redesign_schema_migration.py+84