[loop-cycle-65] feat: scaffold three-phase loop skeleton (#324) (#330)

src/loop/schema.py

@@ -0,0 +1,43 @@
+"""Data schema for the three-phase loop.
+
+Each phase passes a ContextPayload forward. The schema is intentionally
+minimal — Timmy decides what fields matter as the loop matures.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class ContextPayload:
+    """Immutable context packet passed between loop phases.
+
+    Attributes:
+        source: Where this payload originated (e.g. "user", "timer", "event").
+        content: The raw content string to process.
+        timestamp: When the payload was created.
+        token_count: Estimated token count for budget tracking. -1 = unknown.
+        metadata: Arbitrary key-value pairs for phase-specific data.
+    """
+
+    source: str
+    content: str
+    timestamp: datetime = field(default_factory=lambda: datetime.now(UTC))
+    token_count: int = -1
+    metadata: dict = field(default_factory=dict)
+
+    def with_metadata(self, **kwargs: object) -> ContextPayload:
+        """Return a new payload with additional metadata merged in."""
+        merged = {**self.metadata, **kwargs}
+        return ContextPayload(
+            source=self.source,
+            content=self.content,
+            timestamp=self.timestamp,
+            token_count=self.token_count,
+            metadata=merged,
+        )