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/models/__init__.py

@@ -15,6 +15,7 @@ from .step_category import StepCategory
 from .step_library import StepLibrary, StepRating, StepUsageLog
 from .refresh_token import RefreshToken
 from .audit_log import AuditLog
+from .session_share import SessionShare, SessionShareView
 
 __all__ = [
     "User",
@@ -38,4 +39,6 @@ __all__ = [
     "StepUsageLog",
     "RefreshToken",
     "AuditLog",
+    "SessionShare",
+    "SessionShareView",
 ]

backend/app/models/account.py

@@ -1,7 +1,7 @@
 import uuid
 from datetime import datetime, timezone
 from typing import Optional, TYPE_CHECKING
-from sqlalchemy import String, DateTime, ForeignKey
+from sqlalchemy import String, DateTime, ForeignKey, Boolean
 from sqlalchemy.orm import Mapped, mapped_column, relationship
 from sqlalchemy.dialects.postgresql import UUID
 from app.core.database import Base
@@ -26,6 +26,13 @@ class Account(Base):
     stripe_customer_id: Mapped[Optional[str]] = mapped_column(String(255), nullable=True)
     created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=lambda: datetime.now(timezone.utc))
     updated_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=lambda: datetime.now(timezone.utc), onupdate=lambda: datetime.now(timezone.utc))
+    allow_public_shares: Mapped[bool] = mapped_column(
+        Boolean,
+        nullable=False,
+        default=True,
+        server_default="true",
+        comment="Policy: engineers can create public shares. Only affects NEW shares (grandfathered)."
+    )
 
     # Relationships
     owner: Mapped["User"] = relationship("User", foreign_keys=[owner_id], back_populates="owned_account")

backend/app/models/session.py

@@ -1,12 +1,15 @@
 import uuid
 from datetime import datetime, timezone
-from typing import Optional, Any
+from typing import Optional, Any, TYPE_CHECKING
 from sqlalchemy import String, DateTime, ForeignKey, Boolean, Text
 import sqlalchemy as sa
 from sqlalchemy.orm import Mapped, mapped_column, relationship
 from sqlalchemy.dialects.postgresql import UUID, JSONB
 from app.core.database import Base
 
+if TYPE_CHECKING:
+    from app.models.session_share import SessionShare
+
 
 class Session(Base):
     __tablename__ = "sessions"
@@ -53,3 +56,4 @@ class Session(Base):
     tree: Mapped["Tree"] = relationship("Tree", back_populates="sessions")
     user: Mapped["User"] = relationship("User", back_populates="sessions")
     attachments: Mapped[list["Attachment"]] = relationship("Attachment", back_populates="session")
+    shares: Mapped[list["SessionShare"]] = relationship("SessionShare", back_populates="session", cascade="all, delete-orphan")

backend/app/models/session_share.py

@@ -0,0 +1,152 @@
+import uuid
+from datetime import datetime, timezone
+from typing import Optional, TYPE_CHECKING
+from sqlalchemy import String, DateTime, ForeignKey, Boolean, Integer, CheckConstraint
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+from sqlalchemy.dialects.postgresql import UUID
+from app.core.database import Base
+
+if TYPE_CHECKING:
+    from app.models.session import Session
+    from app.models.user import User
+    from app.models.account import Account
+
+
+class SessionShare(Base):
+    __tablename__ = "session_shares"
+    __table_args__ = (
+        CheckConstraint(
+            "visibility IN ('public', 'account')",
+            name='ck_session_shares_visibility'
+        ),
+    )
+
+    id: Mapped[uuid.UUID] = mapped_column(
+        UUID(as_uuid=True),
+        primary_key=True,
+        default=uuid.uuid4
+    )
+    session_id: Mapped[uuid.UUID] = mapped_column(
+        UUID(as_uuid=True),
+        ForeignKey("sessions.id", ondelete="CASCADE"),
+        nullable=False,
+        index=True
+    )
+    account_id: Mapped[uuid.UUID] = mapped_column(
+        UUID(as_uuid=True),
+        ForeignKey("accounts.id", ondelete="CASCADE"),
+        nullable=False,
+        index=True,
+        comment="Account that owns this share (denormalized from session at creation)"
+    )
+    share_token: Mapped[str] = mapped_column(
+        String(64),
+        unique=True,
+        nullable=False,
+        index=True,
+        comment="URL-safe random token (48 bytes -> 64 base64 chars)"
+    )
+    share_name: Mapped[Optional[str]] = mapped_column(
+        String(100),
+        nullable=True,
+        comment="Optional label: 'Training link', 'Customer escalation #1234'"
+    )
+    visibility: Mapped[str] = mapped_column(
+        String(20),
+        nullable=False,
+        default="public",
+        comment="public = anyone with link, account = account members only"
+    )
+    created_by: Mapped[uuid.UUID] = mapped_column(
+        UUID(as_uuid=True),
+        ForeignKey("users.id", ondelete="CASCADE"),
+        nullable=False,
+        index=True
+    )
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        default=lambda: datetime.now(timezone.utc)
+    )
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        default=lambda: datetime.now(timezone.utc),
+        onupdate=lambda: datetime.now(timezone.utc)
+    )
+    expires_at: Mapped[Optional[datetime]] = mapped_column(
+        DateTime(timezone=True),
+        nullable=True,
+        index=True,
+        comment="Optional expiration for time-limited shares"
+    )
+    view_count: Mapped[int] = mapped_column(
+        Integer,
+        nullable=False,
+        default=0
+    )
+    last_viewed_at: Mapped[Optional[datetime]] = mapped_column(
+        DateTime(timezone=True),
+        nullable=True
+    )
+    is_active: Mapped[bool] = mapped_column(
+        Boolean,
+        nullable=False,
+        default=True,
+        index=True
+    )
+
+    # Relationships
+    session: Mapped["Session"] = relationship("Session", back_populates="shares")
+    account: Mapped["Account"] = relationship("Account")
+    creator: Mapped["User"] = relationship("User", foreign_keys=[created_by])
+    views: Mapped[list["SessionShareView"]] = relationship(
+        "SessionShareView",
+        back_populates="share",
+        cascade="all, delete-orphan"
+    )
+
+
+class SessionShareView(Base):
+    __tablename__ = "session_share_views"
+
+    id: Mapped[uuid.UUID] = mapped_column(
+        UUID(as_uuid=True),
+        primary_key=True,
+        default=uuid.uuid4
+    )
+    share_id: Mapped[uuid.UUID] = mapped_column(
+        UUID(as_uuid=True),
+        ForeignKey("session_shares.id", ondelete="CASCADE"),
+        nullable=False,
+        index=True
+    )
+    session_id: Mapped[uuid.UUID] = mapped_column(
+        UUID(as_uuid=True),
+        ForeignKey("sessions.id", ondelete="CASCADE"),
+        nullable=False,
+        index=True,
+        comment="Denormalized from share for analytics queries"
+    )
+    viewer_id: Mapped[Optional[uuid.UUID]] = mapped_column(
+        UUID(as_uuid=True),
+        ForeignKey("users.id", ondelete="SET NULL"),
+        nullable=True,
+        index=True,
+        comment="NULL for public shares (unauthenticated views)"
+    )
+    viewed_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        default=lambda: datetime.now(timezone.utc),
+        index=True
+    )
+    viewer_ip: Mapped[Optional[str]] = mapped_column(
+        String(45),  # IPv6 max length
+        nullable=True
+    )
+    viewer_user_agent: Mapped[Optional[str]] = mapped_column(
+        String(500),
+        nullable=True
+    )
+
+    # Relationships
+    share: Mapped["SessionShare"] = relationship("SessionShare", back_populates="views")
+    viewer: Mapped[Optional["User"]] = relationship("User")

backend/app/models/tree.py

@@ -79,10 +79,62 @@ class Tree(Base):
     )
     usage_count: Mapped[int] = mapped_column(Integer, default=0)
 
+    # Fork tracking
+    parent_tree_id: Mapped[Optional[uuid.UUID]] = mapped_column(
+        UUID(as_uuid=True),
+        ForeignKey("trees.id", ondelete="SET NULL"),
+        nullable=True,
+        index=True
+    )
+    fork_reason: Mapped[Optional[str]] = mapped_column(
+        String(255),
+        nullable=True,
+        comment="Brief reason: 'Added Cisco Meraki steps for our network'"
+    )
+    parent_updated_at: Mapped[Optional[datetime]] = mapped_column(
+        DateTime(timezone=True),
+        nullable=True,
+        comment="Snapshot of parent's updated_at when fork created. Compare to detect parent updates."
+    )
+
+    # Fork lineage tracking
+    root_tree_id: Mapped[Optional[uuid.UUID]] = mapped_column(
+        UUID(as_uuid=True),
+        ForeignKey("trees.id", ondelete="SET NULL"),
+        nullable=True,
+        index=True,
+        comment="Original tree at root of fork chain (NULL for non-forked trees)"
+    )
+    fork_depth: Mapped[int] = mapped_column(
+        Integer,
+        nullable=False,
+        default=0,
+        server_default="0",
+        comment="Fork depth: 0 = original, 1 = direct fork, 2 = fork of fork, etc."
+    )
+
     # Relationships
     author: Mapped[Optional["User"]] = relationship("User", foreign_keys=[author_id], back_populates="trees")
     team: Mapped[Optional["Team"]] = relationship("Team", back_populates="trees")
     account: Mapped[Optional["Account"]] = relationship("Account", foreign_keys=[account_id], back_populates="trees")
+
+    # Fork relationships (self-referential)
+    parent: Mapped[Optional["Tree"]] = relationship(
+        "Tree",
+        remote_side="Tree.id",
+        foreign_keys=[parent_tree_id],
+        back_populates="forks"
+    )
+    forks: Mapped[list["Tree"]] = relationship(
+        "Tree",
+        foreign_keys=[parent_tree_id],
+        back_populates="parent"
+    )
+    root: Mapped[Optional["Tree"]] = relationship(
+        "Tree",
+        remote_side="Tree.id",
+        foreign_keys=[root_tree_id]
+    )
     sessions: Mapped[list["Session"]] = relationship("Session", back_populates="tree")
 
     # New organization relationships