docs(types): note runtime/type mismatch on act format= overloads

The format= overloads narrow the thunk's generic element type, observable on
parsed_repr (S | None), not on .value — ComputedModelOutputThunk.value is
typed `-> str` unconditionally. parsed_repr also currently routes through
Instruction._parse (returns str), so parsed_repr.some_field type-checks but
AttributeErrors at runtime: the same silent-failure shape generative-computing#1274 set out to
fix, relocated to parsed_repr. Add a TODO pointing at the coordinated .parsed
redesign (PR generative-computing#1282) as the proper fix, out of scope here. PR body updated to
match (was claiming .value narrows to MyModel).

Assisted-by: Claude Code

Author: planetf1

mellea/stdlib/session.py

@@ -390,6 +390,14 @@ def cleanup(self) -> None:
 
             deregister_session_plugins(self.id)
 
+    # The format= overloads below narrow the thunk's generic element type. That narrowing
+    # is observable on `parsed_repr: S | None`, NOT on `.value` — ComputedModelOutputThunk.value
+    # is typed `-> str` unconditionally (mellea/core/base.py). There is also a runtime gap:
+    # parsed_repr currently goes through Instruction._parse, which returns a plain str, so
+    # `result.parsed_repr.some_field` type-checks but raises AttributeError at runtime.
+    # TODO: a coherent end state has the thunk's `.parsed` generic over S backed by a runtime
+    # path that delivers S. That is a coordinated change tracked by PR #1282 and is out of
+    # scope here; these overloads only land the static format= narrowing where they can.
     @overload
     def act(
         self,