graphrefly 0.7.0__tar.gz → 0.8.0__tar.gz

{graphrefly-0.7.0 → graphrefly-0.8.0}/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 <!-- version list -->
 
+## v0.8.0 (2026-04-06)
+
+### Features
+
+- 8.1 + django integration
+  ([`5dcfd3d`](https://github.com/graphrefly/graphrefly-py/commit/5dcfd3d78561e7ae8cdc905f95f9b4922926881e))
+
+
 ## v0.7.0 (2026-04-06)
 
 ### Features

{graphrefly-0.7.0 → graphrefly-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: graphrefly
-Version: 0.7.0
+Version: 0.8.0
 Summary: Reactive graph protocol for human + LLM co-operation. Composable nodes, glitch-free diamond resolution, two-phase push, durable streaming. Zero dependencies.
 Project-URL: Homepage, https://py.graphrefly.dev
 Project-URL: Repository, https://github.com/graphrefly/graphrefly-py

{graphrefly-0.7.0 → graphrefly-0.8.0}/docs/optimizations.md

@@ -139,6 +139,7 @@ Union-find over node identity merges components when nodes list dependencies at
 - **~~`to_json()` → `to_dict()` + `to_json_string()` (Phase 1.4, noted 2026-04-05, resolved 2026-04-05):~~** PY: `to_json()` renamed to `to_json_string()`; `to_dict()` added as alias of `snapshot()`; `to_json` alias removed (pre-1.0, no backward compat needed). TS: `toJSON()` renamed to `toObject()`; `toJSON()` kept as ECMAScript hook. Spec §3.8 updated.
 - **~~Initial value, cached state, and equals interaction (all phases, noted 2026-04-05, resolved 2026-04-05):~~** Resolved with `_SENTINEL` / `NO_VALUE` sentinel (TS: `Symbol.for("graphrefly/NO_VALUE")`, PY: `_SENTINEL = object()`). Replaces the `_has_emitted_data` boolean flag entirely. One field (`_cached`) instead of two — impossible to desync. Key semantics: (1) When `initial` option is present (even as `None`), `_cached = initial` — `equals` IS called on first emission. (2) When `initial` is absent, `_cached = _SENTINEL` — first emission always DATA. (3) INVALIDATE / `reset_on_teardown` set `_cached = _SENTINEL`. (4) Resubscribable: terminal reset now also sets `_cached = _SENTINEL` — new subscriber always gets DATA. (5) Reconnect: cache retained → same-value emits RESOLVED — correct. (6) `get()` returns `None` when `_cached is _SENTINEL`. Spec §2.5 updated.
 - **Auto-edge registration is local-only (Phase 1.1, noted 2026-04-05):** `Graph.add()` auto-registers edges for deps within the same `Graph` instance only. Cross-subgraph deps still require explicit `connect()`. Consistent with spec: cross-subgraph edges are explicit wiring.
+- **Reduction primitives cross-language parity (Phase 8.1, noted 2026-04-06, QA 2026-04-06):** Both TS and PY implement `stratify`, `funnel`, `feedback`, `budget_gate`/`budgetGate`, and `scorer` in `patterns/reduction`. All five follow the orchestration factory pattern (`_base_meta`, `_register_step`). Key alignment: (1) `stratify` buffers DIRTY until DATA arrives — on classifier miss, emits `[DIRTY, RESOLVED]` to preserve spec §1.3.1 (both). (2) `funnel` bridges stages via `subscribe` forwarding DIRTY/DATA/RESOLVED/COMPLETE/ERROR to preserve two-phase protocol. TODO(8.2): replace with graph-visible bridge nodes. (3) `feedback` counter node is source of truth (resettable via `graph.set()`); uses `continue` (not `return`) on max_iterations so remaining batch messages process. Counter name is `__feedback_<condition>` to support multiple loops per graph. (4) `budget_gate`/`budgetGate` force-flushes all buffered items on terminal regardless of budget; sends RESUME before terminal if paused; forwards constraint ERROR downstream, silences constraint COMPLETE, forwards unknown constraint types via default. (5) `scorer` coerces `None`/`undefined` to 0 before multiplication (no TypeError/NaN divergence). TS `ScoredItem` is a plain object; PY `ScoredItem` is a class with `__slots__` and `__eq__`. Meta keys: `reduction: True`, `reduction_type: "<name>"`. Both repos: 22 tests each.
 
 ---
 

{graphrefly-0.7.0 → graphrefly-0.8.0}/docs/roadmap.md

@@ -293,7 +293,7 @@ Composition layer over 3.2 (`reactive_log`), 4.1 (sagas), 4.2 (event bus), 4.3 (
 ### 5.1 — Framework compat
 
 - [x] FastAPI integration
-- [ ] Django integration
+- [x] Django integration
 - [x] asyncio / trio Runner protocol
 - [x] Async utilities: `to_async_iter`, `first_value_from_async`, `settled`
 
@@ -487,11 +487,11 @@ Reusable patterns for taking heterogeneous massive inputs and producing prioriti
 
 Composable building blocks between sources and sinks.
 
-- [ ] `stratify(source, rules)` → Graph — route input to different reduction branches based on classifier fn. Each branch gets independent operator chains. Rules are reactive — an LLM can rewrite them at runtime.
-- [ ] `funnel(sources, stages)` → Graph — multi-source merge with sequential reduction stages. Each stage is a named subgraph. Stages are pluggable — swap a stage by graph composition.
-- [ ] `feedback(graph, condition, reentry)` → Graph — introduce a cycle: when condition node fires, route output back to reentry point. Bounded by max iterations + budget constraints.
-- [ ] `budget_gate(source, constraints)` → Node — pass-through respecting reactive constraint nodes (token budget, network IO, cost ceiling). Backpressure via PAUSE/RESUME.
-- [ ] `scorer(sources, weights)` → Node — reactive multi-signal scoring. Weights are nodes (LLM or human can adjust live). Output: sorted, prioritized items with full score breakdown in meta.
+- [x] `stratify(source, rules)` → Graph — route input to different reduction branches based on classifier fn. Each branch gets independent operator chains. Rules are reactive — an LLM can rewrite them at runtime.
+- [x] `funnel(sources, stages)` → Graph — multi-source merge with sequential reduction stages. Each stage is a named subgraph. Stages are pluggable — swap a stage by graph composition.
+- [x] `feedback(graph, condition, reentry)` → Graph — introduce a cycle: when condition node fires, route output back to reentry point. Bounded by max iterations + budget constraints.
+- [x] `budget_gate(source, constraints)` → Node — pass-through respecting reactive constraint nodes (token budget, network IO, cost ceiling). Backpressure via PAUSE/RESUME.
+- [x] `scorer(sources, weights)` → Node — reactive multi-signal scoring. Weights are nodes (LLM or human can adjust live). Output: sorted, prioritized items with full score breakdown in meta.
 
 ### 8.2 — Domain templates (opinionated Graph factories)
 

{graphrefly-0.7.0 → graphrefly-0.8.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "graphrefly"
-version = "0.7.0"
+version = "0.8.0"
 description = "Reactive graph protocol for human + LLM co-operation. Composable nodes, glitch-free diamond resolution, two-phase push, durable streaming. Zero dependencies."
 readme = "README.md"
 license = "MIT"
@@ -60,6 +60,7 @@ dev = [
 	"ruff>=0.9",
 	"mypy>=1.14",
 	"croniter>=2.0",
+	"django>=4.2",
 	"fastapi>=0.100",
 	"httpx>=0.24",
 	"pillow>=12.2.0",

{graphrefly-0.7.0 → graphrefly-0.8.0}/src/graphrefly/compat/trio_runner.py

@@ -24,7 +24,7 @@ from typing import TYPE_CHECKING, Any
 if TYPE_CHECKING:
     from collections.abc import Callable, Coroutine
 
-    import trio  # type: ignore[import-not-found]
+    import trio
 
 
 class TrioRunner:

{graphrefly-0.7.0 → graphrefly-0.8.0}/src/graphrefly/core/dynamic_node.py

@@ -13,7 +13,10 @@ import threading
 from collections.abc import Callable, Mapping
 from contextlib import suppress
 from types import MappingProxyType
-from typing import Any
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from graphrefly.core.guard import MutationRecord
 
 from graphrefly.core.node import _SENTINEL
 from graphrefly.core.protocol import Messages, MessageType, emit_with_batch, propagates_to_meta
@@ -184,7 +187,7 @@ class DynamicNodeImpl[T]:
         self._on_resubscribe = on_resubscribe
         self._auto_complete = complete_when_deps_complete
         self._describe_kind = describe_kind
-        self._last_mutation: dict[str, Any] | None = None
+        self._last_mutation: MutationRecord | None = None
         self._resubscribable = resubscribable
         self._reset_on_teardown = reset_on_teardown
         self._thread_safe = bool(thread_safe)
@@ -255,7 +258,7 @@ class DynamicNodeImpl[T]:
         return self._meta
 
     @property
-    def last_mutation(self) -> dict[str, Any] | None:
+    def last_mutation(self) -> MutationRecord | None:
         return self._last_mutation
 
     @property

{graphrefly-0.7.0 → graphrefly-0.8.0}/src/graphrefly/core/node.py

@@ -14,6 +14,7 @@ from graphrefly.core.guard import (
     Actor,
     GuardAction,
     GuardDenied,
+    MutationRecord,
     normalize_actor,
     record_mutation,
 )
@@ -253,10 +254,10 @@ class NodeImpl[T]:
             msg = "node option 'guard' must be callable or None"
             raise TypeError(msg)
         self._guard: Callable[[Actor, GuardAction], bool] | None = raw_guard
-        self._last_mutation: dict[str, Any] | None = None
+        self._last_mutation: MutationRecord | None = None
 
         self._cache_lock = threading.Lock() if self._thread_safe else None
-        self._cached: Any = opts["initial"] if "initial" in opts else _SENTINEL
+        self._cached: Any = opts.get("initial", _SENTINEL)
         self._status: NodeStatus = "disconnected" if self._has_deps else "settled"
 
         # Versioning (GRAPHREFLY-SPEC §7)
@@ -367,7 +368,7 @@ class NodeImpl[T]:
                 else:
                     self._cached = m[1]  # type: ignore[misc]
                 if self._versioning is not None:
-                    advance_version(self._versioning, m[1], self._hash_fn)
+                    advance_version(self._versioning, m[1], self._hash_fn)  # type: ignore[misc]
             if t is MessageType.INVALIDATE:
                 # GRAPHREFLY-SPEC §1.2: clear cached state; do not auto-emit from here.
                 if self._cleanup is not None:
@@ -761,7 +762,7 @@ class NodeImpl[T]:
         return None if v is _SENTINEL else v
 
     @property
-    def last_mutation(self) -> dict[str, Any] | None:
+    def last_mutation(self) -> MutationRecord | None:
         """Last non-internal ``write`` attribution (``actor``, ``timestamp_ns``), if any."""
         return self._last_mutation
 
@@ -991,4 +992,13 @@ def node(
 # Public alias for type hints
 Node = NodeImpl
 
-__all__ = ["NO_VALUE", "Node", "NodeActions", "NodeFn", "NodeImpl", "NodeStatus", "SubscribeHints", "node"]
+__all__ = [
+    "NO_VALUE",
+    "Node",
+    "NodeActions",
+    "NodeFn",
+    "NodeImpl",
+    "NodeStatus",
+    "SubscribeHints",
+    "node",
+]

{graphrefly-0.7.0 → graphrefly-0.8.0}/src/graphrefly/core/timer.py

@@ -5,6 +5,10 @@ from_timer creates a new Node per reset)."""
 from __future__ import annotations
 
 import threading
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
 
 
 class ResettableTimer:
@@ -16,7 +20,7 @@ class ResettableTimer:
         self._timer: threading.Timer | None = None
         self._lock = threading.Lock()
 
-    def start(self, delay_seconds: float, callback: callable) -> None:
+    def start(self, delay_seconds: float, callback: Callable[[], Any]) -> None:
         """Schedule callback after delay_seconds. Cancels any pending timer."""
         with self._lock:
             if self._timer is not None:

{graphrefly-0.7.0 → graphrefly-0.8.0}/src/graphrefly/extra/adapters.py

@@ -2022,6 +2022,7 @@ def from_csv(
         def drain() -> None:
             try:
                 headers: list[str] | None = list(columns) if columns else None
+                rows_iter: Iterable[list[str]]
                 if parse_line is not None:
                     rows_iter = (parse_line(line) for line in source)
                 else:
@@ -2475,7 +2476,7 @@ def from_nats(
                 async for msg in sub:
                     if not active[0]:
                         return
-                    actions.emit(_nats_msg_to_nats_message(msg, deserialize))  # type: ignore[arg-type]
+                    actions.emit(_nats_msg_to_nats_message(msg, deserialize))
                 # Iterator exhausted — subscription closed (inline, matching TS pattern).
                 if active[0]:
                     actions.down([(MessageType.COMPLETE,)])
@@ -2501,7 +2502,7 @@ def from_nats(
                 for msg in sub_or_coro:
                     if not active[0]:
                         return
-                    actions.emit(_nats_msg_to_nats_message(msg, deserialize))  # type: ignore[arg-type]
+                    actions.emit(_nats_msg_to_nats_message(msg, deserialize))
                 # Iterator exhausted — subscription closed.
                 if active[0]:
                     actions.down([(MessageType.COMPLETE,)])
@@ -2512,10 +2513,10 @@ def from_nats(
         t = threading.Thread(target=_run, daemon=True)
         t.start()
 
-        def cleanup() -> None:
+        def _sync_cleanup() -> None:
             active[0] = False
 
-        return cleanup
+        return _sync_cleanup
 
     return node(start, describe_kind="producer", complete_when_deps_complete=False)
 
@@ -2769,12 +2770,12 @@ def to_rabbitmq(
         if msg[0] is MessageType.DATA:
             value = msg[1] if len(msg) > 1 else None
             try:
-                rk = routing_key_extractor(value)  # type: ignore[misc]
+                rk = routing_key_extractor(value)
             except Exception as err:
                 handler(SinkTransportError(stage="routing_key", error=err, value=value))
                 return True
             try:
-                body = serialize(value)  # type: ignore[misc]
+                body = serialize(value)
             except Exception as err:
                 handler(SinkTransportError(stage="serialize", error=err, value=value))
                 return True
@@ -2908,7 +2909,7 @@ def to_file(
         if msg[0] is MessageType.DATA:
             value = msg[1] if len(msg) > 1 else None
             try:
-                line = serialize(value)  # type: ignore[misc]
+                line = serialize(value)
             except Exception as err:
                 handler(SinkTransportError(stage="serialize", error=err, value=value))
                 return True
@@ -3004,15 +3005,11 @@ def to_csv(
             header_written[0] = True
             header = delimiter.join(_escape_csv_field(c, delimiter) for c in columns)
             data = delimiter.join(
-                _escape_csv_field(cell_extractor(row, c), delimiter)  # type: ignore[misc]
-                for c in columns
+                _escape_csv_field(cell_extractor(row, c), delimiter) for c in columns
             )
             return header + "\n" + data + "\n"
         return (
-            delimiter.join(
-                _escape_csv_field(cell_extractor(row, c), delimiter)  # type: ignore[misc]
-                for c in columns
-            )
+            delimiter.join(_escape_csv_field(cell_extractor(row, c), delimiter) for c in columns)
             + "\n"
         )
 
@@ -3108,7 +3105,7 @@ def to_clickhouse(
         if msg[0] is MessageType.DATA:
             value = msg[1] if len(msg) > 1 else None
             try:
-                transformed = transform(value)  # type: ignore[misc]
+                transformed = transform(value)
             except Exception as err:
                 handler(SinkTransportError(stage="serialize", error=err, value=value))
                 return True
@@ -3224,7 +3221,7 @@ def to_s3(
         else:
             body = json.dumps(batch_data)
             content_type = "application/json"
-        key = key_generator(seq, wall_clock_ns())  # type: ignore[misc]
+        key = key_generator(seq, wall_clock_ns())
         try:
             client.put_object(Bucket=bucket, Key=key, Body=body, ContentType=content_type)
         except Exception as err:
@@ -3254,7 +3251,7 @@ def to_s3(
         if msg[0] is MessageType.DATA:
             value = msg[1] if len(msg) > 1 else None
             try:
-                transformed = transform(value)  # type: ignore[misc]
+                transformed = transform(value)
             except Exception as err:
                 handler(SinkTransportError(stage="serialize", error=err, value=value))
                 return True
@@ -3330,7 +3327,7 @@ def to_postgres(
         if msg[0] is MessageType.DATA:
             value = msg[1] if len(msg) > 1 else None
             try:
-                sql, params = to_sql(value, table)  # type: ignore[misc]
+                sql, params = to_sql(value, table)
             except Exception as err:
                 handler(SinkTransportError(stage="serialize", error=err, value=value))
                 return True
@@ -3390,7 +3387,7 @@ def to_mongo(
         if msg[0] is MessageType.DATA:
             value = msg[1] if len(msg) > 1 else None
             try:
-                doc = to_document(value)  # type: ignore[misc]
+                doc = to_document(value)
             except Exception as err:
                 handler(SinkTransportError(stage="serialize", error=err, value=value))
                 return True
@@ -3456,7 +3453,7 @@ def to_loki(
         if msg[0] is MessageType.DATA:
             value = msg[1] if len(msg) > 1 else None
             try:
-                line = to_line(value)  # type: ignore[misc]
+                line = to_line(value)
             except Exception as err:
                 handler(SinkTransportError(stage="serialize", error=err, value=value))
                 return True
@@ -3523,7 +3520,7 @@ def to_tempo(
         if msg[0] is MessageType.DATA:
             value = msg[1] if len(msg) > 1 else None
             try:
-                spans = to_resource_spans(value)  # type: ignore[misc]
+                spans = to_resource_spans(value)
             except Exception as err:
                 handler(SinkTransportError(stage="serialize", error=err, value=value))
                 return True
@@ -3792,7 +3789,7 @@ def to_sqlite(
         if msg[0] is MessageType.DATA:
             value = msg[1] if len(msg) > 1 else None
             try:
-                sql, params = to_sql(value, table)  # type: ignore[misc]
+                sql, params = to_sql(value, table)
             except Exception as err:
                 handler(SinkTransportError(stage="serialize", error=err, value=value))
                 return True

{graphrefly-0.7.0 → graphrefly-0.8.0}/src/graphrefly/extra/cascading_cache.py

@@ -5,6 +5,9 @@ from __future__ import annotations
 from collections import OrderedDict
 from typing import TYPE_CHECKING, Any, Generic, Protocol, TypeVar, runtime_checkable
 
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
 from graphrefly.core.protocol import MessageType
 from graphrefly.core.sugar import state
 
@@ -155,7 +158,7 @@ class CascadingCache(Generic[V]):  # noqa: UP046
 
     def __init__(
         self,
-        tiers: list[CacheTier],
+        tiers: Sequence[CacheTier],
         *,
         max_size: int = 0,
         eviction: EvictionPolicy | None = None,
@@ -171,7 +174,7 @@ class CascadingCache(Generic[V]):  # noqa: UP046
         for i in range(hit_tier):
             tier = self._tiers[i]
             if _tier_has_save(tier):
-                tier.save(key, value)  # type: ignore[union-attr]
+                tier.save(key, value)
 
     def _cascade(self, key: str, nd: Node[Any]) -> None:
         for tier_index, tier in enumerate(self._tiers):
@@ -199,10 +202,10 @@ class CascadingCache(Generic[V]):  # noqa: UP046
                         # Demote to deepest tier with save before evicting
                         for i in range(len(self._tiers) - 1, -1, -1):
                             if _tier_has_save(self._tiers[i]):
-                                self._tiers[i].save(victim, value)  # type: ignore[union-attr]
+                                self._tiers[i].save(victim, value)
                                 for j in range(i):
                                     if _tier_has_clear(self._tiers[j]):
-                                        self._tiers[j].clear(victim)  # type: ignore[union-attr]
+                                        self._tiers[j].clear(victim)
                                 break
                     nd.down([(MessageType.TEARDOWN,)])
                     del self._entries[victim]
@@ -236,10 +239,9 @@ class CascadingCache(Generic[V]):  # noqa: UP046
         if self._write_through:
             for tier in self._tiers:
                 if _tier_has_save(tier):
-                    tier.save(key, value)  # type: ignore[union-attr]
+                    tier.save(key, value)
         elif self._tiers and _tier_has_save(self._tiers[0]):
-            self._tiers[0].save(key, value)  # type: ignore[union-attr]
-
+            self._tiers[0].save(key, value)
         if key in self._entries:
             self._entries[key].down([(MessageType.DATA, value)])
             if self._eviction is not None:
@@ -271,7 +273,7 @@ class CascadingCache(Generic[V]):  # noqa: UP046
                 self._eviction.delete(key)
         for tier in self._tiers:
             if _tier_has_clear(tier):
-                tier.clear(key)  # type: ignore[union-attr]
+                tier.clear(key)
 
     def has(self, key: str) -> bool:
         """Check if a key is in the in-memory entries."""
@@ -284,7 +286,7 @@ class CascadingCache(Generic[V]):  # noqa: UP046
 
 
 def cascading_cache(
-    tiers: list[CacheTier],
+    tiers: Sequence[CacheTier],
     *,
     max_size: int = 0,
     eviction: EvictionPolicy | None = None,
@@ -398,5 +400,10 @@ def tiered_storage(
         ```
     """
     tiers = [_CheckpointTier(a) for a in adapters]
-    inner = CascadingCache(tiers, max_size=max_size, eviction=eviction, write_through=True)
+    inner: CascadingCache[Any] = CascadingCache(
+        tiers,
+        max_size=max_size,
+        eviction=eviction,
+        write_through=True,
+    )
     return TieredStorage(inner)

{graphrefly-0.7.0 → graphrefly-0.8.0}/src/graphrefly/extra/resilience.py

@@ -796,7 +796,7 @@ def fallback(source: Node[Any], fb: Any) -> Node[Any]:
                     actions.down([m])
 
         unsub_holder[0] = source.subscribe(sink)
-        unsub = unsub_holder[0]
+        unsub: Callable[[], None] = unsub_holder[0]  # type: ignore[assignment]
 
         def cleanup() -> None:
             unsub()
@@ -853,7 +853,8 @@ def timeout(source: Node[Any], timeout_ns: int) -> Node[Any]:
                 done[0] = True
                 # §5.10: ResettableTimer (not from_timer) — resettable
                 # deadline; from_timer adds Node overhead per DATA reset.
-                unsub_holder[0]()
+                if unsub_holder[0] is not None:
+                    unsub_holder[0]()
                 actions.down([(MessageType.ERROR, TimeoutError(timeout_ns))])
 
             to_timer.start(delay_s, fire)
@@ -890,7 +891,7 @@ def timeout(source: Node[Any], timeout_ns: int) -> Node[Any]:
 
         arm_timer()
         unsub_holder[0] = source.subscribe(sink)
-        unsub = unsub_holder[0]
+        unsub: Callable[[], None] = unsub_holder[0]  # type: ignore[assignment]
 
         def cleanup() -> None:
             done[0] = True

{graphrefly-0.7.0 → graphrefly-0.8.0}/src/graphrefly/graph/graph.py

@@ -10,11 +10,11 @@ import threading
 from collections import deque
 from contextlib import contextmanager, suppress
 from dataclasses import dataclass, field
-from typing import TYPE_CHECKING, Any, ClassVar
+from typing import TYPE_CHECKING, Any, ClassVar, cast
 
 from graphrefly.core.clock import monotonic_ns
 from graphrefly.core.guard import GuardDenied, normalize_actor
-from graphrefly.core.meta import describe_node, resolve_describe_fields
+from graphrefly.core.meta import DescribeDetail, describe_node, resolve_describe_fields
 from graphrefly.core.node import NodeImpl
 from graphrefly.core.protocol import Messages, MessageType, is_batching, message_tier
 from graphrefly.core.sugar import state
@@ -23,7 +23,7 @@ if TYPE_CHECKING:
     from collections.abc import Callable, Iterator
 
 
-class DescribeResult(dict):
+class DescribeResult(dict[str, Any]):
     """Dict subclass returned by :meth:`Graph.describe`.
 
     Provides an ``expand()`` method for re-reading the live graph at a higher
@@ -34,7 +34,7 @@ class DescribeResult(dict):
     def expand(self, detail_or_fields: Any = None) -> DescribeResult:
         """Re-read the live graph at a higher detail level or with explicit fields."""
         fn = object.__getattribute__(self, "_expand_fn")
-        return fn(detail_or_fields)
+        return cast("DescribeResult", fn(detail_or_fields))
 
 
 @dataclass(frozen=True, slots=True)
@@ -1050,7 +1050,7 @@ class Graph:
         detail: str | None = None,
         fields: list[str] | None = None,
         format: str | None = None,
-    ) -> dict[str, Any]:
+    ) -> DescribeResult:
         """Static structure snapshot (GRAPHREFLY-SPEC §3.6, Appendix B).
 
         ``nodes`` keys are qualified paths (including ``::__meta__::`` for companions).
@@ -1099,7 +1099,7 @@ class Graph:
         if format == "spec":
             include_fields: set[str] | None = {"type", "deps"}
         else:
-            include_fields = resolve_describe_fields(detail, fields)
+            include_fields = resolve_describe_fields(cast("DescribeDetail | None", detail), fields)
 
         targets = _collect_observe_targets(self, "")
         paths_by_id = {id(n): p for p, n in targets}
@@ -2057,7 +2057,14 @@ class Graph:
                 va = na.get(key)
                 vb = nb.get(key)
                 if va != vb:
-                    changed_nodes.append({"path": p, "field": key, "from": va, "to": vb})
+                    changed_nodes.append(
+                        GraphDiffNodeChange(
+                            path=p,
+                            field=key,
+                            from_value=va,
+                            to_value=vb,
+                        )
+                    )
 
         a_edges = {(e["from"], e["to"]) for e in a.get("edges", [])}
         b_edges = {(e["from"], e["to"]) for e in b.get("edges", [])}