a

core/schema/models/timeline.py

@@ -1,4 +1,4 @@
-"""Timeline schema — source of truth for frame sequences."""
+"""Timeline schema — source of truth for source material sequences."""
 
 from dataclasses import dataclass, field
 from datetime import datetime
@@ -9,21 +9,27 @@ from uuid import UUID
 @dataclass
 class Timeline:
     """
-    The frame sequence from a source video.
+    A user-created selection of source material.
 
-    Independent of stages — exists before any stage runs.
-    Frames stored in MinIO as JPEGs, metadata here.
-    One timeline per job.
+    Exists before any job runs. Holds source references (chunk paths,
+    asset IDs) and extraction config.
+
+    Frame cache: extracted frames live at media/timelines/{id}/frames/
+    as JPEGs. Any job on this timeline reads from the cache. Cache is
+    rebuildable from chunks (clear + re-extract). For ephemeral sources
+    (streams), the cache is the only record.
+
+    Many jobs can work on the same timeline.
     """
 
     id: UUID
+    name: str = ""
     source_asset_id: Optional[UUID] = None
-    source_video: str = ""
+    chunk_paths: List[str] = field(default_factory=list)
     profile_name: str = ""
+    status: str = "created"  # created | cached | ready
     fps: float = 2.0
-
-    frames_prefix: str = ""  # s3: timeline/{id}/frames/
-    frames_manifest: Dict[int, str] = field(default_factory=dict)  # seq → s3 key
-    frames_meta: List[Dict[str, Any]] = field(default_factory=list)
+    frame_count: int = 0
+    source_ephemeral: bool = False  # True for streams — cache can't be rebuilt
 
     created_at: Optional[datetime] = None