observatory: introduce Region/Session model with enter_context API

Lays the data model and runtime state machine for the worldview adopted
in RFC §4.4-4.5: a lightweight Region (named scope from enter_context;
nests freely; pure labelling) and a heavyweight Session (the outermost
Region; owns lens lifecycle hooks).

interfaces.py
  - Add Session dataclass: id, name, start_ts, end_ts, start_data,
    end_data. Holds per-session lens hook payloads.
  - RecordDigest gains session_id and region_stack (snapshot of the
    active region path at collect() time, outermost first). Both default
    to "" / [] so existing record reload paths and tests keep working.
  - SessionResult now carries an ordered `sessions: List[Session]` list
    in addition to the legacy flat start_data/end_data dicts; the flat
    views remain a union across sessions for transitional consumers.
  - Module docstring spells out the Worldview block (Region/Session/
    Record/Archive/Report) so anyone opening the file lands on the
    same vocabulary as the RFC.

observatory.py
  - Add enter_context(region_name=None, config=None):
      * outermost (region_stack empty): pushes a Region; if region_name
        is omitted, auto-generates "default" / "default-2" / ... ;
        opens a Session and fires on_session_start.
      * inner (region_stack non-empty): with a name, pushes a labelled
        Region (no Session change); without a name, pure config-only
        override (no Region pushed).
  - Add _open_session / _close_session helpers; on_session_end fires
    cleanly even on exception inside the with-block.
  - Reuse path: enable_context becomes a thin alias of enter_context()
    (no name) so existing call sites keep working.
  - collect() now stamps each Record with the active session_id and
    a copy of the active region_stack.
  - clear() resets _sessions, _active_session_id, _region_stack, and
    _config_stack alongside the legacy state.

tests/test_region_session.py (new)
  Twelve focused unit tests covering: outermost with/without name,
  inner without name = config-only, inner with name = labelled
  Region inside the same Session, sibling outermost = multiple
  Sessions, default-name auto-increment, on_session_start/end fire
  exactly once per Session boundary (not per inner Region), collect
  outside any context is a no-op, time-ordered records, name
  uniqueness enforcement, on_session_end on exception, and the
  enable_context alias still working.

Verification
  PYTHONPATH=~ python -m pytest \
    ~/executorch/devtools/observatory/tests/ -v
  → 41 passed, 1 pre-existing unrelated failure
    (test_per_layer_accuracy_lens, "psnr" key, untouched here).

Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

Author: quic-boyuc

devtools/observatory/interfaces.py

@@ -8,14 +8,30 @@
 
 This module is the source-of-truth contract for:
 1. Frontend view composition (`ViewList` + typed blocks/specs).
-2. Runtime record/session objects (`ObservationContext`, `RecordDigest`, etc.).
+2. Runtime record/session objects (`ObservationContext`, `RecordDigest`,
+   `Session`).
 3. Analyze-phase graph layer contribution via fx_viewer payload types.
 
-Architecture model:
-1. Runtime phase (`observe`/`digest`) captures raw record data.
-2. Analyze phase (`analyze`) computes global and per-record derived data.
-3. Frontend phase (`Frontend.*`) maps typed data into renderable view blocks.
+Worldview (cf. RFC §4.4 / §4.5):
+
+  Region   lightweight named scope from `Observatory.enter_context(name, ...)`;
+           can nest; pure labelling (no lens hooks fire at region boundaries).
+  Session  the heavyweight scope; emerges automatically from the *outermost*
+           Region; lens `on_session_start` / `on_session_end` fire at Session
+           boundaries.
+  Record   one `Observatory.collect(name, artifact)` item; carries `session_id`
+           + `region_stack` (snapshot at collect time); stored time-ordered.
+  Archive  one Observatory invocation: `sessions[]` + `records[]`; the only
+           thing persisted raw (`--output-archive`).
+  Report   derived output: `analyze` runs once per archive, then per-session
+           `Frontend.dashboard` renders Report (HTML) and Report (JSON).
 
+Architecture model:
+1. Runtime phase (`observe` then `digest`): produce one Record per
+   `collect()` call, tagged with the active session_id and region_stack.
+2. Analyze phase (`analyze`): pure-data, runs once per archive over all
+   records + sessions.
+3. Frontend phase (`Frontend.*`): per-session dashboard + per-record views.
 """
 
 from __future__ import annotations
@@ -565,20 +581,68 @@ class ObservationContext:
 
 @dataclass
 class RecordDigest:
-    """Persistent observation item.
+    """One Record. The canonical persisted unit produced by `collect()`.
 
-    This is the canonical persisted unit produced by runtime capture.
+    Fields:
+        name: Display name (deduplicated to "name #2", "name #3" on collision).
+        timestamp: Seconds since epoch at the moment `collect()` fires.
+        session_id: Active session at collect time. Equals the outermost
+            region_name on the runtime stack.
+        region_stack: Snapshot of the active region path at collect time;
+            outermost first. Used by the left-panel tree-view to group
+            records under collapsible region nodes.
+        data: Per-lens digest map keyed by `lens.get_name()`.
     """
 
     name: str
     timestamp: float
+    session_id: str = ""
+    region_stack: List[str] = field(default_factory=list)
     data: Dict[str, Serializable] = field(default_factory=dict)
 
 
+@dataclass
+class Session:
+    """Heavyweight scope opened by an outermost `enter_context` call.
+
+    A Session begins when an outermost `Observatory.enter_context(...)` is
+    entered and ends when that outermost block exits. Lens `on_session_start`
+    and `on_session_end` hooks fire at Session boundaries (not at inner
+    Regions).
+
+    Fields:
+        id: Unique session identifier within an archive. Equals `name` for
+            single-archive runs; prefixed `<archive_label>:<name>` when
+            loaded via `--compare`.
+        name: Human-facing label (the outermost region_name, or an
+            auto-generated default like "default" / "default-2").
+        start_ts: Seconds since epoch when the Session opened.
+        end_ts: Seconds since epoch when the Session closed (None while open).
+        start_data: Per-lens payload from `on_session_start`, keyed by
+            `lens.get_name()`.
+        end_data: Per-lens payload from `on_session_end`.
+    """
+
+    id: str
+    name: str
+    start_ts: float
+    end_ts: Optional[float] = None
+    start_data: Dict[str, Serializable] = field(default_factory=dict)
+    end_data: Dict[str, Serializable] = field(default_factory=dict)
+
+
 @dataclass
 class SessionResult:
-    """Session start/end data from lens hooks."""
+    """Aggregate of all Sessions in an Archive.
+
+    Wraps an ordered list of `Session` instances plus the legacy flat
+    `start_data`/`end_data` views. The flat views are unions across all
+    sessions (last-write-wins on collision) and exist for transitional
+    compatibility with code paths that have not yet migrated to the
+    per-Session model.
+    """
 
+    sessions: List[Session] = field(default_factory=list)
     start_data: Dict[str, Serializable] = field(default_factory=dict)
     end_data: Dict[str, Serializable] = field(default_factory=dict)
 

devtools/observatory/observatory.py

@@ -6,13 +6,33 @@
 
 """Observatory runtime core.
 
+Worldview (cf. RFC §4.4 / §4.5):
+
+  Region   lightweight named scope from `Observatory.enter_context(name, ...)`;
+           can nest; pure labelling (no lens hooks at region boundaries).
+  Session  heavyweight scope; emerges automatically from the outermost
+           Region. Lens `on_session_start` / `on_session_end` fire here.
+  Record   one `Observatory.collect(name, artifact)` item; carries
+           `session_id` + `region_stack` snapshot.
+  Archive  one Observatory invocation: `sessions[]` + `records[]`.
+  Report   derived analysis (HTML / JSON) over the Archive.
+
 Lifecycle summary:
-1. Runtime capture: `observe -> digest`.
+1. Runtime: `observe` then `digest` per `collect()`.
 2. Analysis: per-lens `analyze(records, config)`.
 3. Assembly: merge frontend blocks + graph assets/layers.
 4. Rendering/export: JSON and HTML reports.
 
 The runtime enforces strict typed interfaces from `interfaces.py`.
+
+`enter_context(region_name=None, config=None)` is the primary entry API.
+- Outermost (region stack empty on entry): if `region_name` is omitted, an
+  auto-generated default name (`"default"`, `"default-2"`, …) is used. Pushes
+  a Region and opens a Session (fires `on_session_start`).
+- Inner (region stack non-empty on entry): if `region_name` is omitted, the
+  call is a config-only override — the region stack and Session are unchanged.
+- `enable_context(...)` is preserved as a thin alias that opens an unnamed
+  outermost / config-only inner block, matching the semantics above.
 """
 
 from __future__ import annotations
@@ -42,6 +62,7 @@
     ObservationContext,
     RecordAnalysis,
     RecordDigest,
+    Session,
     SessionResult,
     ViewList,
     validate_view_list,
@@ -81,14 +102,30 @@ def floatstr(
 
 
 class Observatory:
-    """Global registry for collecting and rendering observability artifacts."""
+    """Global registry: opens a Session, accumulates Records into an Archive,
+    and emits a Report on export.
+
+    Class-level state (per-process; reset via `clear()`):
+        _records: time-ordered Records keyed by deduplicated name.
+        _ignored_graphs: substrings that suppress matching `collect()` calls.
+        _session_result: legacy SessionResult plus the per-Session list.
+        _sessions: ordered dict of Session by id (insertion = display order).
+        _active_session_id: name of the currently-open Session (or None).
+        _lens_registry: ordered list of registered Lens classes.
+        _lenses_initialized: flag for one-time default-lens registration.
+        _config_stack: Context frames (one per `enter_context` call).
+        _region_stack: active Region names; outermost first, innermost last.
+    """
 
     _records: Dict[str, RecordDigest] = {}
     _ignored_graphs: Set[str] = set()
     _session_result: SessionResult = SessionResult()
+    _sessions: Dict[str, Session] = {}
+    _active_session_id: Optional[str] = None
     _lens_registry: List[Type[Lens]] = []
     _lenses_initialized: bool = False
     _config_stack: List[Dict[str, Any]] = []
+    _region_stack: List[str] = []
 
     @classmethod
     def register_lens(cls, lens_cls: Type[Lens], append=True) -> None:
@@ -126,13 +163,33 @@ def _ensure_default_lenses(cls) -> None:
 
     @classmethod
     @contextmanager
-    def enable_context(cls, config: Optional[Dict[str, Any]] = None) -> ContextManager[None]:
-        """Enable observation context with nested config overrides.
+    def enter_context(
+        cls,
+        region_name: Optional[str] = None,
+        config: Optional[Dict[str, Any]] = None,
+    ) -> ContextManager[None]:
+        """Push a Region onto the runtime stack (and a Session at outermost).
+
+        Behaviour by call position:
+        1. Outermost (region stack empty on entry):
+           - With ``region_name``: pushes the named Region and opens a Session
+             with the same ``id`` and ``name``.
+           - Without ``region_name``: auto-generates a non-duplicating default
+             ("default", "default-2", ...), pushes it as a Region, and opens
+             a Session with that name.
+        2. Inner (region stack non-empty on entry):
+           - With ``region_name``: pushes a labelled Region; the active
+             Session is unchanged (regions do not fire lens session hooks).
+           - Without ``region_name``: config-only override - the config frame
+             is pushed but no Region is added to the stack.
+
+        Lens lifecycle: ``on_session_start`` / ``on_session_end`` fire only
+        at Session boundaries (outermost-region entry/exit). Inner Regions
+        are pure labelling.
 
-        Session hooks run once per outermost context:
-        1. On first enter, auto-collection patches are installed and
-           `on_session_start` hooks are called.
-        2. On last exit, `on_session_end` hooks are called and patches removed.
+        Notes:
+            ``region_name`` must be unique within an Archive. Re-using a name
+            for a sibling outermost block raises ``RuntimeError``.
         """
 
         cls._ensure_default_lenses()
@@ -150,34 +207,100 @@ def merge_config_dict(base: Dict[str, Any], new: Dict[str, Any]) -> Dict[str, An
         parent_config = cls._config_stack[-1] if cls._config_stack else {}
         context_config = merge_config_dict(parent_config, config or {})
 
-        is_outermost_start = len(cls._config_stack) == 0
+        is_outermost = len(cls._region_stack) == 0
+        push_region = region_name is not None or is_outermost
+
+        if push_region:
+            if region_name is None:
+                # Outermost without name: auto-generate a non-duplicating default.
+                effective_name = cls._next_default_session_name()
+            else:
+                effective_name = region_name
+                if is_outermost and effective_name in cls._sessions:
+                    raise RuntimeError(
+                        f"Session name {effective_name!r} already used in this archive."
+                    )
+        else:
+            # Inner without name: config-only override.
+            effective_name = None
+
         cls._config_stack.append(context_config)
-        hook_ctx = ObservationContext(config=context_config)
 
-        if is_outermost_start:
-            for lens in cls._lens_registry:
-                try:
-                    data = lens.on_session_start(hook_ctx)
-                    if data:
-                        cls._session_result.start_data[lens.get_name()] = data
-                except Exception as exc:
-                    logging.error("[Observatory] Lens %s failed on_session_start: %s", lens, exc)
+        if push_region and is_outermost:
+            cls._open_session(effective_name)
+
+        if push_region:
+            cls._region_stack.append(effective_name)
 
         try:
             yield
         finally:
-            is_outermost_end = len(cls._config_stack) == 1
+            if push_region:
+                cls._region_stack.pop()
+            cls._config_stack.pop()
+            if push_region and is_outermost:
+                cls._close_session(effective_name)
 
-            if is_outermost_end:
-                for lens in cls._lens_registry:
-                    try:
-                        data = lens.on_session_end(hook_ctx)
-                        if data:
-                            cls._session_result.end_data[lens.get_name()] = data
-                    except Exception as exc:
-                        logging.error("[Observatory] Lens %s failed on_session_end: %s", lens, exc)
+    @classmethod
+    @contextmanager
+    def enable_context(cls, config: Optional[Dict[str, Any]] = None) -> ContextManager[None]:
+        """Backwards-compatible alias for ``enter_context`` without a name.
 
-            cls._config_stack.pop()
+        Outermost call opens an auto-named Session; nested calls are
+        config-only overrides. Prefer ``enter_context(region_name, config)``
+        for new code so the tree view picks up labelled regions.
+        """
+
+        with cls.enter_context(region_name=None, config=config):
+            yield
+
+    @classmethod
+    def _next_default_session_name(cls) -> str:
+        """Return the next non-duplicating default Session name."""
+
+        if "default" not in cls._sessions:
+            return "default"
+        n = 2
+        while f"default-{n}" in cls._sessions:
+            n += 1
+        return f"default-{n}"
+
+    @classmethod
+    def _open_session(cls, name: str) -> None:
+        """Open a Session and fire `on_session_start` on every active lens."""
+
+        active_config = cls._config_stack[-1] if cls._config_stack else {}
+        hook_ctx = ObservationContext(config=active_config)
+        session = Session(id=name, name=name, start_ts=time.time())
+        for lens in cls._lens_registry:
+            try:
+                data = lens.on_session_start(hook_ctx)
+                if data:
+                    session.start_data[lens.get_name()] = data
+                    cls._session_result.start_data[lens.get_name()] = data
+            except Exception as exc:
+                logging.error("[Observatory] Lens %s failed on_session_start: %s", lens, exc)
+        cls._sessions[name] = session
+        cls._session_result.sessions.append(session)
+        cls._active_session_id = name
+
+    @classmethod
+    def _close_session(cls, name: str) -> None:
+        """Fire `on_session_end` on every active lens and close the Session."""
+
+        active_config = cls._config_stack[-1] if cls._config_stack else {}
+        hook_ctx = ObservationContext(config=active_config)
+        session = cls._sessions[name]
+        for lens in cls._lens_registry:
+            try:
+                data = lens.on_session_end(hook_ctx)
+                if data:
+                    session.end_data[lens.get_name()] = data
+                    cls._session_result.end_data[lens.get_name()] = data
+            except Exception as exc:
+                logging.error("[Observatory] Lens %s failed on_session_end: %s", lens, exc)
+        session.end_ts = time.time()
+        cls._active_session_id = None
 
     @classmethod
     def _get_current_context(cls) -> Optional[ObservationContext]:
@@ -223,7 +346,12 @@ def collect(cls, name: str, artifact: Any) -> None:
         ctx = ObservationContext(config=active_config)
         ctx.shared_state["record_name"] = name
 
-        record = RecordDigest(name=name, timestamp=datetime.now().timestamp())
+        record = RecordDigest(
+            name=name,
+            timestamp=datetime.now().timestamp(),
+            session_id=cls._active_session_id or "",
+            region_stack=list(cls._region_stack),
+        )
         t_start = time.perf_counter()
 
         for lens in cls._lens_registry:
@@ -256,6 +384,10 @@ def clear(cls) -> None:
 
         cls._records.clear()
         cls._session_result = SessionResult()
+        cls._sessions.clear()
+        cls._active_session_id = None
+        cls._region_stack.clear()
+        cls._config_stack.clear()
 
         for lens in cls._lens_registry:
             try: