feat: add tree forking, custom step tracking, and session sharing

Implement three foundational schema features from the design doc:

- Tree forking with lineage tracking (migration 022): parent_tree_id,
  root_tree_id, fork_depth columns with self-referential FKs and
  composite analytics index
- Custom step enhancement: CustomStepSchema with source tracking
  (ad-hoc, step-library, forked-tree) for backward-compatible JSONB
- Session sharing (migration 023): session_shares and session_share_views
  tables with account-scoped visibility, cryptographic tokens, view
  tracking, and allow_public_shares account policy

Includes 21 new integration tests (9 forking, 12 sharing), SaaS
consultant-recommended denormalizations, rate limiting on public share
access, and test fixture fix for invite code requirement.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

backend/app/schemas/session.py

@@ -1,9 +1,25 @@
 from datetime import datetime
-from typing import Optional, Any
+from typing import Optional, Any, Literal
 from uuid import UUID
 from pydantic import BaseModel, Field, validator
 
 
+class CustomStepSchema(BaseModel):
+    """Enhanced custom step with source tracking.
+
+    Backward compatible: old sessions without new fields load with defaults.
+    """
+    type: str  # "decision" | "action" | "solution"
+    content: str
+    notes: Optional[str] = None
+
+    # Source tracking (new fields, optional for backward compatibility)
+    source: Literal["ad-hoc", "step-library", "forked-tree"] = "ad-hoc"
+    source_step_id: Optional[UUID] = None
+    inserted_at: Optional[datetime] = None
+    inserted_after_node_id: Optional[str] = None
+
+
 class DecisionRecord(BaseModel):
     node_id: str
     question: Optional[str] = None
@@ -24,7 +40,7 @@ class SessionCreate(BaseModel):
 class SessionUpdate(BaseModel):
     path_taken: Optional[list[str]] = None
     decisions: Optional[list[DecisionRecord]] = None
-    custom_steps: Optional[list[dict[str, Any]]] = None
+    custom_steps: Optional[list[CustomStepSchema]] = None
     ticket_number: Optional[str] = Field(None, max_length=100)
     client_name: Optional[str] = Field(None, max_length=255)
     scratchpad: Optional[str] = None

backend/app/schemas/session_share.py

@@ -0,0 +1,47 @@
+from datetime import datetime
+from typing import Optional, Literal
+from uuid import UUID
+from pydantic import BaseModel, Field
+
+
+class ShareCreate(BaseModel):
+    visibility: Literal["public", "account"] = Field("public", description="Share visibility")
+    share_name: Optional[str] = Field(None, max_length=100, description="Optional label for the share")
+    expires_at: Optional[datetime] = Field(None, description="Optional expiration datetime")
+
+
+class ShareResponse(BaseModel):
+    id: UUID
+    session_id: UUID
+    account_id: UUID
+    share_token: str
+    share_name: Optional[str] = None
+    visibility: str
+    created_by: UUID
+    created_at: datetime
+    updated_at: datetime
+    expires_at: Optional[datetime] = None
+    view_count: int
+    last_viewed_at: Optional[datetime] = None
+    is_active: bool
+    share_url: Optional[str] = None
+
+    class Config:
+        from_attributes = True
+
+
+class SharePublicView(BaseModel):
+    """Read-only session data returned when accessing a share link."""
+    session_id: UUID
+    tree_name: str
+    tree_description: Optional[str] = None
+    tree_structure: dict
+    path_taken: list[str]
+    decisions: list[dict]
+    custom_steps: list[dict] = Field(default_factory=list)
+    started_at: datetime
+    completed_at: Optional[datetime] = None
+    ticket_number: Optional[str] = None
+    client_name: Optional[str] = None
+    share_name: Optional[str] = None
+    visibility: str

backend/app/schemas/tree.py

@@ -40,6 +40,24 @@ class TreeUpdate(BaseModel):
     tags: Optional[list[str]] = Field(None, max_length=10, description="List of tag names to assign (replaces existing)")
 
 
+class ForkCreate(BaseModel):
+    fork_reason: Optional[str] = Field(None, max_length=255, description="Brief reason for forking")
+    name: Optional[str] = Field(None, min_length=1, max_length=255, description="Name for the fork (defaults to 'Fork of {original name}')")
+
+
+class ForkInfo(BaseModel):
+    """Fork metadata included in tree responses."""
+    parent_tree_id: Optional[UUID] = None
+    root_tree_id: Optional[UUID] = None
+    fork_reason: Optional[str] = None
+    fork_depth: int = 0
+    parent_updated_at: Optional[datetime] = None
+    has_parent_updates: bool = False
+
+    class Config:
+        from_attributes = True
+
+
 class TreeResponse(TreeBase):
     id: UUID
     tree_structure: dict[str, Any]
@@ -48,6 +66,7 @@ class TreeResponse(TreeBase):
     category_id: Optional[UUID] = None
     category_info: Optional[CategoryInfo] = None
     tags: list[str] = []  # List of tag names
+    fork_info: Optional[ForkInfo] = None
     is_active: bool
     is_public: bool
     is_default: bool