graphrefly 0.6.0__tar.gz → 0.7.0__tar.gz

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

@@ -2,6 +2,17 @@
 
 <!-- version list -->
 
+## v0.7.0 (2026-04-06)
+
+### Features
+
+- Central timer util
+  ([`d1285d5`](https://github.com/graphrefly/graphrefly-py/commit/d1285d5c4c95928b1c27e10ca77204ee0f8aaa5e))
+
+- Redesign initial + cached
+  ([`86d8506`](https://github.com/graphrefly/graphrefly-py/commit/86d850623e4e09fda1e8547ab67ca6e4cefb2a48))
+
+
 ## v0.6.0 (2026-04-05)
 
 ### Chores

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: graphrefly
-Version: 0.6.0
+Version: 0.7.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.6.0 → graphrefly-0.7.0}/docs/optimizations.md

@@ -126,24 +126,38 @@ Union-find over node identity merges components when nodes list dependencies at
 - **~~Synchronous SQLite blocking in `to_sqlite` sink (Phase 5.2b, noted 2026-04-04, resolved 2026-04-04):~~** Both TS and PY now accept `batch_insert` / `batchInsert` (default `False`) and `max_batch_size` / `maxBatchSize` (default `1000`). DATA values are buffered and flushed inside a `BEGIN`/`COMMIT` transaction on terminal messages (`message_tier >= 3`), at `max_batch_size` threshold, or on `dispose()`. On insert error, the first error triggers `break` + `ROLLBACK`. BEGIN failure preserves pending data for retry via manual `flush()`. Both return `BufferedSinkHandle` when batch mode is enabled.
 - **CheckpointAdapter refactored to key-value (Phase 3.1c, noted 2026-04-05, resolved 2026-04-05):** `CheckpointAdapter` changed from blob-based (`save(data)` / `load()`) to key-value (`save(key, data)` / `load(key)` / `clear(key)`). Unifies checkpoint persistence and cache storage under one interface. Both TS and PY updated. `save_graph_checkpoint` / `restore_graph_checkpoint` pass `graph.name` as key. `auto_checkpoint` passes `self.name` as key. `FileCheckpointAdapter` now takes a directory (one file per key, sanitized filenames). `DictCheckpointAdapter` no longer takes an internal key in constructor. `SqliteCheckpointAdapter` no longer takes a fixed key — caller provides it. Pre-1.0, all downstream consumers updated, no legacy shims.
 - **`tiered_storage` uses `CheckpointAdapter[]` directly (Phase 3.1c, noted 2026-04-05, resolved 2026-04-05):** With key-value `CheckpointAdapter`, `tiered_storage` wraps adapters as `CacheTier`s naturally. No separate `CacheTier` interface needed for end users — `CheckpointAdapter` serves both checkpoint and cache use cases.
-- **`equals` must never see undefined/None (all phases, noted 2026-04-05):** `_emit_auto_value` must skip `equals()` when `_cached` is still `None` (initial state before first DATA). TS fixed in `node.ts`; PY needs matching fix in `node.py`. Spec §2.5 updated: `equals` only compares two real DATA values, never `undefined`/`None`. **Audit all custom `equals` in PY** to verify none depend on seeing `None`. See also TS `docs/optimizations.md` and roadmap hotfix section.
-- **`_cached is None` sentinel is ambiguous with `[(DATA, None)]` and INVALIDATE (noted 2026-04-05):** The current guard uses `self._cached is not None` to detect "never emitted." This conflates: (a) never emitted, (b) emitted `[(DATA, None)]`, (c) reset via INVALIDATE/`reset_on_teardown`. **Proposed fix:** Add `_has_emitted_data: bool` flag (initially `False`, set `True` on first `_emit_auto_value`, reset on INVALIDATE/`reset_on_teardown`). Both TS and PY. Counter-argument: `_run_fn` skips `None` returns so auto-emit can never produce `None`; the `actions.emit(None)` path is exotic. Deferred: decide and implement in both languages.
-- **Derived node error observability gap (all phases, noted 2026-04-05, partially resolved 2026-04-05):** When a derived node's `fn` or `equals` throws, the node emits `[(ERROR, err)]` and status becomes `"errored"`. But `graph.get()` returns `None` — indistinguishable from "never computed." Resolution: spec §2.2 updated to emphasize `status` as source of truth and `describe()` as the primary diagnostic — `get()` is a value accessor only. Still needed: wrap `equals`/`fn` errors with node name context before emitting ERROR — deferred to next chat.
-- **PY `retry` lock scope around `connect()` (Phase 3.1, noted 2026-04-05):** In `resilience.py`, `schedule_retry_or_finish` calls `fire()` which calls `connect()` while holding the internal lock. `connect()` runs `source.subscribe(sink)` outside the lock, creating a window where concurrent `cleanup()` could miss the new subscription — a potential resource leak on rapid teardown + retry. Mitigation deferred: the window is narrow and only affects concurrent unsubscribe during active retry.
-- **PY `SqliteCheckpointAdapter` default `check_same_thread=True` (Phase 3.1, noted 2026-04-05):** Python's `sqlite3.connect()` defaults to `check_same_thread=True`, raising `ProgrammingError` if `save()` is called from a timer/debounce thread while `load()` runs on the main thread. Not an issue in single-threaded usage (the common case). Deferred: add `check_same_thread=False` + a `threading.Lock` if multi-threaded checkpoint usage becomes a pattern.
-- **Sink `value = msg[1] if len(msg) > 1 else None` silent None coercion (Phase 5.2–5.3, noted 2026-04-05):** All per-record sinks extract DATA payload via `msg[1] if len(msg) > 1 else None`, silently treating a malformed DATA (missing payload) as `None`. This masks upstream bugs. Deferred: pre-existing pattern across all sinks; fixing would require a coordinated change to all adapters + a spec decision on whether payload-less DATA is valid.
-- **Sink `suppress(Exception)` in `dispose()` hides teardown bugs (Phase 5.2–5.3, noted 2026-04-05):** All sinks use `with suppress(Exception)` around `errors_node.down([(MessageType.TEARDOWN,)])` in `dispose()`. This silently swallows teardown errors (double-dispose, graph corruption). Deferred: pre-existing pattern across all sinks; narrowing the suppression requires auditing what errors are actually possible during teardown.
-- **`from_django_orm` and `from_tortoise` have identical implementations (Phase 5.2, noted 2026-04-05):** Both sources iterate a sync iterable and emit DATA per row. Bodies are character-identical. Intentional: separate entry points with distinct docstrings and `from_tortoise` includes an async-guard that rejects unawaited coroutines/async iterables. A shared `_from_sync_iterable` helper could reduce duplication but would obscure the distinct adapter semantics. Deferred: revisit if more iterable-based sources are added.
+- **~~`equals` must never see undefined/None (all phases, noted 2026-04-05, resolved 2026-04-05):~~** Superseded by `_SENTINEL` / `NO_VALUE` sentinel below. Original fix used `_has_emitted_data` flag; the sentinel approach replaced both.
+- **~~`_cached is None` sentinel is ambiguous with `[(DATA, None)]` and INVALIDATE (noted 2026-04-05, resolved 2026-04-05):~~** Superseded by `_SENTINEL` / `NO_VALUE` sentinel below.
+- **~~Derived node error observability gap (all phases, noted 2026-04-05, resolved 2026-04-05):~~** `fn`/`equals`/`on_message` errors now wrapped with `RuntimeError(f'Node "{name}": fn threw')` / `equals threw` / `on_message threw` with `__cause__`. Both TS and PY.
+- **~~PY `retry` lock scope around `connect()` (Phase 3.1, noted 2026-04-05, resolved 2026-04-05):~~** Verified that `connect()` already runs outside the lock. Added clarifying comment.
+- **PY `SqliteCheckpointAdapter` default `check_same_thread=True` (Phase 3.1, noted 2026-04-05):** Python's `sqlite3.connect()` defaults to `check_same_thread=True`, raising `ProgrammingError` if `save()` is called from a timer/debounce thread while `load()` runs on the main thread. `check_same_thread=False` + `threading.Lock` fix was prepared but reverted by linter. Deferred: re-apply when multi-threaded checkpoint usage becomes a pattern.
+- **~~Payload-less DATA spec note (Phase 5.2–5.3, noted 2026-04-05, resolved 2026-04-05):~~** Spec clarified: payload-less DATA (`(DATA,)`) is not valid per protocol — all DATA tuples must carry a payload. Sink `msg[1] if len(msg) > 1 else None` coercion retained as defensive guard; upstream producers are the source of truth.
+- **~~Sink `dispose()` error routing (Phase 5.2–5.3, noted 2026-04-05, resolved 2026-04-05):~~** All 20 PY sink `dispose()` functions now route errors to the `errors` companion node before suppressing.
+- **~~`from_django_orm` and `from_tortoise` have identical implementations (Phase 5.2, noted 2026-04-05, resolved 2026-04-05):~~** Extracted `_from_sync_rows` helper. Both entry points kept with distinct validation.
+- **~~Auto-edge registration from constructor deps (all phases, noted 2026-04-05, resolved 2026-04-05):~~** `Graph.add()` now auto-registers edges from constructor deps. Eliminates dual-bookkeeping bug surface.
+- **~~ResettableTimer primitive (Phase 3.1, noted 2026-04-05, resolved 2026-04-05):~~** `ResettableTimer` in `core/timer.py`. `retry`, `rate_limiter`, `timeout` refactored to use it.
+- **~~`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.
 
 ---
 
+## Cross-language parity fixes (2026-04-05)
+
+- **~~PY error wrapping missing original message (resolved 2026-04-05):~~** `RuntimeError(f'Node "{name}": fn threw')` omitted the original error message. TS included it: `fn threw: ${errMsg}`. Fixed all 3 PY sites (`fn threw`, `equals threw`, `on_message threw`) to include `{err}`. TS `onMessage` error was also not wrapped — now wraps as `Node "${name}": onMessage threw: ${errMsg}` with `{ cause }`.
+- **~~PY `Graph.add()` missing reverse edge scan (resolved 2026-04-05):~~** PY only did forward auto-edge registration. TS did both forward + reverse (existing nodes whose deps include the new node). Fixed: PY now does the reverse scan, matching TS.
+- **~~PY `_emit_sequential` terminal routing (resolved 2026-04-05):~~** PY appended terminals to the same queue as DATA/RESOLVED. TS routed them to `pendingPhase3`. Fixed: PY terminals now go to `bs.pending_phase3`.
+- **~~PY `emit_with_batch` default strategy (resolved 2026-04-05):~~** PY defaulted to `"sequential"`, TS to `"partition"`. Fixed: PY default changed to `"partition"`.
+- **~~PY `retry` sink missing `stopped` guard (resolved 2026-04-05):~~** TS checked `if (stopped) return;` at top of retry subscribe callback. PY had no such guard. Fixed: added `if stopped[0]: return`.
+- **~~PY `fallback` plain-value path used `down()` (resolved 2026-04-05):~~** TS used `a.emit(fb)` (goes through equals + DIRTY/DATA wrapping). PY used `actions.down([(DATA, fb), (COMPLETE,)])` (bypassed equals). Fixed: PY now uses `actions.emit(fb)` then `actions.down([(COMPLETE,)])`.
+
 ## Cross-language implementation notes
 
 **Keep this section in sync with `graphrefly-ts/docs/optimizations.md` § Cross-language implementation notes** so you can open both files side by side.
 
-- **Dual-bookkeeping of derived deps + connect edges (all phases, noted 2026-04-05):** In both TS and PY, `derived([depA, depB], fn)` declares reactive deps at the node level (DIRTY/DATA propagation), but `Graph` only records named edges via explicit `graph.connect(from, to)`. Both declarations are required: the node deps drive the reactive engine, the connect edges drive `describe()` / `to_mermaid()` / `to_d2()` output. If a dep is added/removed in the derived call but the corresponding `connect` is not updated (or vice versa), the introspection output diverges from actual dataflow. All graph factories (orchestration, cqrs, memory, messaging) follow this dual pattern. A future improvement could auto-register edges from constructor deps when a node is `add()`-ed — but this requires the Graph to inspect the node's internal dep list, which currently crosses the node/graph encapsulation boundary. Deferred: revisit if the divergence-risk causes real bugs.
+- **~~Dual-bookkeeping of derived deps + connect edges (all phases, noted 2026-04-05, resolved 2026-04-05):~~** `Graph.add()` now auto-registers edges from constructor deps in both TS and PY. Eliminates the divergence risk between node-level deps and graph-level edge registry. All graph factories no longer need explicit `connect()` calls for constructor deps.
 
-- **Resilience composition parity (Phase 3.1c, 2026-04-05):** Both TS and PY implement `fallback(source, fb)`, `timeout(source, timeoutNs/timeout_ns)`, `cache(source, ttlNs/ttl_ns)`, `cascadingCache`/`cascading_cache`, and `tieredStorage`/`tiered_storage`. `CacheEvictionPolicy`/`EvictionPolicy` use aligned method names: `insert`/`touch`/`delete`/`evict(count)`/`size()`. `CacheTier`: `load` is required; `save`/`clear` are optional (TS `?` modifier; PY uses `hasattr` checks). `tieredStorage`/`tiered_storage` returns a wrapper with `.cache` property exposing the inner `CascadingCache` in both languages. Eviction demotes to deepest tier with `save` before removing — value is preserved in cold storage. Cache miss sentinel: TS `undefined`, PY `None`. `TimeoutError`: TS extends `Error`; PY subclasses `builtins.TimeoutError` so `except TimeoutError` catches both. Validation: TS `RangeError`, PY `ValueError` — language convention. `cache()` replay emits raw `DATA` (no DIRTY/RESOLVED) on both sides. §5.10 timer exception: `timeout`, `retry`, `rateLimiter`/`rate_limiter` all use `setTimeout`/`threading.Timer` for resettable deadlines — documented with inline `§5.10` comments; a reusable resettable timer primitive is deferred.
+- **Resilience composition parity (Phase 3.1c, 2026-04-05):** Both TS and PY implement `fallback(source, fb)`, `timeout(source, timeoutNs/timeout_ns)`, `cache(source, ttlNs/ttl_ns)`, `cascadingCache`/`cascading_cache`, and `tieredStorage`/`tiered_storage`. `CacheEvictionPolicy`/`EvictionPolicy` use aligned method names: `insert`/`touch`/`delete`/`evict(count)`/`size()`. `CacheTier`: `load` is required; `save`/`clear` are optional (TS `?` modifier; PY uses `hasattr` checks). `tieredStorage`/`tiered_storage` returns a wrapper with `.cache` property exposing the inner `CascadingCache` in both languages. Eviction demotes to deepest tier with `save` before removing — value is preserved in cold storage. Cache miss sentinel: TS `undefined`, PY `None`. `TimeoutError`: TS extends `Error`; PY subclasses `builtins.TimeoutError` so `except TimeoutError` catches both. Validation: TS `RangeError`, PY `ValueError` — language convention. `cache()` replay emits raw `DATA` (no DIRTY/RESOLVED) on both sides. §5.10 timer exception: `timeout`, `retry`, `rateLimiter`/`rate_limiter` now use `ResettableTimer` (`core/timer.py` in PY, `core/timer.ts` in TS) — a reusable primitive extracted from the repeated `setTimeout`/`threading.Timer` pattern.
 - **Progressive disclosure parity (Phase 3.3b, 2026-04-04):** Both TS and PY `describe()` support `detail` (`"minimal"` / `"standard"` / `"full"`) and `fields` (GraphQL-style field selection with dotted meta paths like `"meta.label"`). Default changed from returning all fields to `"minimal"` (type + deps only) in both languages — pre-1.0, no backward compat concern. `format: "spec"` / `format="spec"` forces minimal fields. Both return an `expand()` method on the result for re-reading with higher detail. TS `expand` is a property on the result object; PY `describe()` returns a `DescribeResult` (dict subclass) with `expand()` as a method — `json.dumps(graph.describe())` works safely in both languages (TS `JSON.stringify` drops functions; PY `expand` is not a dict key). `observe()` supports `detail` with the same three levels: `"minimal"` (DATA events only in events list, counts still tracked), `"standard"` (current behavior), `"full"` (implies structured + timeline + causal + derived). `ObserveResult` has `expand()` in both languages. TS `expand` is a method on the result object; PY `expand` is a method on the `ObserveResult` dataclass. Internal callers (`snapshot`, `auto_checkpoint`, `dump_graph`, AI pattern functions) explicitly pass the detail level they need. Diagram methods (`to_mermaid`/`toMermaid`, `to_d2`/`toD2`) only use paths/edges so minimal default is fine — intentional, no detail option needed. `"standard"` includes versioning (`v`); `"full"` adds `guard` and `last_mutation`/`lastMutation` (runtime attribution, not restored by `restore()`). `snapshot()` / `auto_checkpoint` strip `last_mutation`/`guard` from persisted nodes so snapshot → restore → snapshot is idempotent — use `describe(detail="full")` for audit snapshots that include attribution. Unrecognized `detail` strings silently fall back to `"minimal"` — no runtime validation; we'll revisit if real-world usage shows this causes confusion. Dict/object filters (`meta_has`, `status`, etc.) operate on whatever fields the chosen detail level provides; at `"minimal"`, fields like `meta` and `status` are absent, so filters that depend on them silently exclude all nodes. Users should pass `detail="standard"` or higher when using these filters. Spec Appendix B `status` field changed from `required` to optional (schema applies at `detail >= "standard"`).
 - **SQLite adapter parity (Phase 5.2b, 2026-04-04):** Both TS and PY use duck-typed `SqliteDbLike` with a `query(sql, params)` method — matching the `PostgresClientLike`/`ClickHouseClientLike` convention. TS `SqliteDbLike.query()` returns `unknown[]`; PY `SqliteDbLike.query()` returns `list[Any]`. Both are fully synchronous (no Promises/async). `from_sqlite`/`fromSqlite` is one-shot (DATA per row, then COMPLETE); compose with `switch_map` + `from_timer` for periodic re-query. `to_sqlite`/`toSqlite` follows per-record sink pattern (same as `to_postgres`/`toPostgres`). Default insert SQL uses JSON column; custom `to_sql` override available. TS uses `node:sqlite` `DatabaseSync` or `better-sqlite3`; PY uses stdlib `sqlite3` — both zero-dep from GraphReFly's perspective (user provides instance).
 - **Storage & sink adapter pattern parity (Phase 5.2d, 2026-04-04):** All 5.2d sinks follow the same pattern in both TS and PY: duck-typed client protocols, `on_message` intercepting `DATA`, `SinkTransportError` for serialize/send failures. All sinks return a `SinkHandle` with `dispose()` + `errors: Node[SinkTransportError | None]`. `dispose()` sends `TEARDOWN` to the errors node. Buffered sinks (`to_clickhouse`, `to_s3`, `to_file`, `to_csv`) return a `BufferedSinkHandle` adding `flush()`. TS `SinkHandle` has optional `flush?: ...`; PY uses separate `BufferedSinkHandle` dataclass (intentional — more Pythonic). Checkpoint adapters (`checkpoint_to_s3`, `checkpoint_to_redis`) wire `graph.auto_checkpoint()`. PY uses `threading.Timer` for flush timers; TS uses `setTimeout`. PY `to_postgres` calls `client.execute(sql, params)` (psycopg2/3 style); TS calls `client.query(sql, params)` (pg style). PY `json.dumps` includes spaces after separators; TS `JSON.stringify` does not — NDJSON output is semantically equivalent but not byte-identical across languages.
@@ -312,14 +326,14 @@ Cross-language: `graphrefly-ts/docs/optimizations.md` §15. **Python (shipped):*
 | **`snapshot()`** | Both: `{ version: 1, ...describe() }` — flat `version` field, sorted `nodes` keys. |
 | **`restore(data)`** | Both: validate `data.name` matches graph name; skip `derived`/`operator`/`effect` types; silently ignore unknown/failing paths. |
 | **`from_snapshot(data, build?)`** | Both: optional `build` callback registers topology before `restore()` applies values. Without `build`, both use registry-based reconstruction (mounts → topo node creation via factories → edges → restore). |
-| **`to_json()` / `toJSON()`** | Python returns compact JSON **string** with trailing newline. TS returns a plain sorted-key **object** (for `JSON.stringify(graph)`). Language-appropriate. |
-| **`toJSONString()`** | TS only — `JSON.stringify(toJSON()) + "\n"`. Python's `to_json()` serves the same role. |
+| **`to_json_string()` / `toJSON()`** | Python `to_json_string()` returns compact JSON **string** with trailing newline. TS `toJSON()` returns a plain sorted-key **object** (for `JSON.stringify(graph)`). Language-appropriate. |
+| **`toJSONString()`** | TS only — `JSON.stringify(toJSON()) + "\n"`. Python's `to_json_string()` serves the same role. |
 
 **Intentional divergence:**
 
 | Topic | Python | TypeScript | Rationale |
 |-------|--------|------------|-----------|
-| `to_json` return type | `to_json()` → `str` (no universal `__json__` hook in Python) | `toJSON()` → plain object (ECMAScript `JSON.stringify` protocol) | Language idiom |
+| `to_json_string` return type | `to_json_string()` → `str` (no universal `__json__` hook in Python) | `toJSON()` → plain object (ECMAScript `JSON.stringify` protocol) | Language idiom |
 | `_parse_snapshot_envelope` | Validates `version`, `name`, `nodes`, `edges`, `subgraphs` types | Only validates `data.name` match | Python is stricter; both correct |
 
 ### Ingest adapters (roadmap 5.2c / 5.3b) — deferred items (QA)
@@ -330,7 +344,7 @@ Applies to `src/extra/adapters.ts` and `graphrefly.extra.adapters`. **Keep the t
 |------|--------|-------|
 | **`fromRedisStream` / `from_redis_stream` never emits COMPLETE** | Documented limitation (2026-04-03) | Long-lived stream consumers intentionally never complete. The consumer loop runs until teardown. This is expected behavior for persistent stream sources (same as Kafka). Document in JSDoc/docstrings. |
 | **`fromRedisStream` / `from_redis_stream` does not disconnect client** | Documented limitation (2026-04-03) | The caller owns the Redis client lifecycle. The adapter does not call `disconnect()` on teardown — the caller is responsible for closing the connection. Same contract as `fromKafka` (caller owns `consumer.connect()`/`disconnect()`). |
-| **PY `from_csv` / `from_ndjson` thread not joined on cleanup** | Documented limitation (2026-04-03) | Python file-ingest adapters run in a daemon thread. On teardown, `active[0] = False` signals the thread to exit but does not `join()` it. The daemon flag ensures the thread does not block process exit. A future optimization could add optional `join(timeout)` on cleanup for stricter resource control. |
+| **PY `from_csv` / `from_ndjson` thread cleanup** | Resolved (2026-04-05) | `t.join(timeout=1)` added after stop flag. |
 
 ### Ingest adapters — intentional cross-language divergences (parity review 2026-04-03)
 
@@ -377,10 +391,10 @@ Applies to `src/extra/adapters.ts` and `graphrefly.extra.adapters`. **Keep the t
 | Node internals | Class-based `NodeImpl`, all methods on class | Class-based `NodeImpl`, V8 hidden class optimization, prototype methods |
 | Dep-value identity check | Before cleanup (skip cleanup+fn on no-op) | Before cleanup (skip cleanup+fn on no-op) |
 | `INVALIDATE` (§1.2) | Cleanup + clear `_cached` + `_last_dep_values`; terminal passthrough (§9); no auto recompute | Same |
-| `Graph` Phase 1.1 | `thread_safe` + `RLock`; TEARDOWN after unlock on `remove`; `disconnect` registry-only (§C resolved) | Registry only; `connect` / `disconnect` errors aligned; §C resolved |
+| `Graph` Phase 1.1 | `thread_safe` + `RLock`; TEARDOWN after unlock on `remove`; `disconnect` registry-only (§C resolved); `add()` auto-registers edges from constructor deps | Registry only; `connect` / `disconnect` errors aligned; §C resolved; `add()` auto-registers edges from constructor deps |
 | `Graph` Phase 1.2 | Aligned: `::` path separator, mount `remove` + subtree TEARDOWN, qualified paths, `edges()`, signal mounts-first, `resolve` strips leading name, `:` in names OK; see §14 | Same; see §14 |
 | `Graph` Phase 1.3 | `describe`, `observe`, `GRAPH_META_SEGMENT`, `signal`→meta, `describe_kind` on sugar; see §15 | TS: `describe()`, `observe()`, `GRAPH_META_SEGMENT`, `describeKind` on sugar; see graphrefly-ts §15 | `observe()` order: both use full-path code-point sort (resolved 2026-03-31; see §15) |
-| `Graph` Phase 1.4 | `destroy`, `snapshot` (flat `version: 1`), `restore` (name check + type filter + silent catch), `from_snapshot(data, build=)`, `to_json()` → str + `\n`; see §16 | `destroy`, `snapshot`, `restore`, `fromSnapshot(data, build?)`, `toJSON()` → object, `toJSONString()` → str + `\n`; see §16 |
+| `Graph` Phase 1.4 | `destroy`, `snapshot` (flat `version: 1`), `restore` (name check + type filter + silent catch), `from_snapshot(data, build=)`, `to_json_string()` → str + `\n`; see §16 | `destroy`, `snapshot`, `restore`, `fromSnapshot(data, build?)`, `toJSON()` → object, `toJSONString()` → str + `\n`; see §16 |
 | `Graph` Phase 1.5 | **Python:** `Actor`, `GuardDenied`, `policy()`, `compose_guards`, node `guard` opt, `down`/`set`/`signal`/`subscribe`/`describe` actor params, `internal` propagation bypass, `remove`/unmount subtree TEARDOWN `internal=True`; see built-in §8 | **TypeScript:** aligned — `GraphActorOptions`, `NodeTransportOptions`, scoped `describe`/`observe`, `GuardDenied.node` getter mirrors `nodeName` |
 | `policy()` semantics | Deny-overrides: any matching deny blocks; if no deny, any matching allow permits; no match → deny | Same (aligned from parity round) |
 | `DEFAULT_ACTOR` | `{"type": "system", "id": ""}` | `{ type: "system", id: "" }` (aligned) |
@@ -399,7 +413,7 @@ Applies to `src/extra/adapters.ts` and `graphrefly.extra.adapters`. **Keep the t
 | `from_event_emitter` / `fromEvent` | Generic emitter (`add_method=`, `remove_method=`) | DOM `addEventListener` API |
 | `to_array` / `toArray` | Reactive `Node[list]` | Reactive `Node<T[]>` |
 | `to_list` (blocking) | Py-only sync bridge | N/A |
-| Extra Phase 3.1 (resilience) | `graphrefly.extra.{backoff,resilience,checkpoint}`; see §6 below | `src/extra/{backoff,resilience,checkpoint}.ts`; see §6 below |
+| Extra Phase 3.1 (resilience) | `graphrefly.extra.{backoff,resilience,checkpoint}` + `core/timer.py` (`ResettableTimer`); see §6 below | `src/extra/{backoff,resilience,checkpoint}.ts` + `core/timer.ts` (`ResettableTimer`); see §6 below |
 | Extra Phase 3.2 (data structures) | `graphrefly.extra.data_structures` (`reactive_map`, …); see §17 | `reactiveMap` + `reactive-base` (`Versioned` snapshots); see §17 |
 
 ### 18. CQRS reactive log snapshot shape (Phase 4.5 — cross-language note)
@@ -535,7 +549,7 @@ Both repos now ship a Pulsar-inspired messaging domain layer under `patterns.mes
 
 | Topic | Python | TypeScript | Rationale |
 |-------|--------|------------|-----------|
-| Timer base | `monotonic_ns()` (nanoseconds via `time.monotonic_ns()`) | `monotonicNs()` (nanoseconds via `performance.now()`) | Both centralised in `core/clock`; nanosecond internal tracking |
+| Timer base | `monotonic_ns()` (nanoseconds via `time.monotonic_ns()`); `ResettableTimer` in `core/timer.py` | `monotonicNs()` (nanoseconds via `performance.now()`); `ResettableTimer` in `core/timer.ts` | Both centralised in `core/clock`; nanosecond internal tracking; `ResettableTimer` used by `retry`, `rate_limiter`, `timeout` |
 | Thread safety | `CircuitBreaker` + `TokenBucket` use `threading.Lock`; retry uses `threading.Timer` | Single-threaded (`setTimeout`) | Spec §6.1 |
 | `CircuitBreaker` params | `cooldown` (seconds, implicit) | `cooldownSeconds` (seconds, explicit) | Naming convention |
 | `CircuitOpenError` base | `RuntimeError` | `Error` | Language convention |

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

@@ -1,6 +1,6 @@
 [project]
 name = "graphrefly"
-version = "0.6.0"
+version = "0.7.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"

{graphrefly-0.6.0 → graphrefly-0.7.0}/src/graphrefly/__init__.py

@@ -15,6 +15,7 @@ from graphrefly.core import (
     Message,
     Messages,
     MessageType,
+    NO_VALUE,
     Node,
     NodeActions,
     NodeFn,
@@ -115,6 +116,7 @@ __all__ = [
     "Message",
     "MessageType",
     "Messages",
+    "NO_VALUE",
     "Node",
     "PipeOperator",
     "NodeActions",

{graphrefly-0.6.0 → graphrefly-0.7.0}/src/graphrefly/core/__init__.py

@@ -18,6 +18,7 @@ from graphrefly.core.guard import (
 )
 from graphrefly.core.meta import describe_node, meta_snapshot
 from graphrefly.core.node import (
+    NO_VALUE,
     Node,
     NodeActions,
     NodeFn,
@@ -64,6 +65,7 @@ from graphrefly.core.sugar import (
     producer,
     state,
 )
+from graphrefly.core.timer import ResettableTimer
 from graphrefly.core.versioning import (
     V0,
     V1,
@@ -87,6 +89,7 @@ __all__ = [
     "GuardDenied",
     "GuardFn",
     "Message",
+    "NO_VALUE",
     "MessageType",
     "Messages",
     "Node",
@@ -95,6 +98,7 @@ __all__ = [
     "NodeFn",
     "NodeImpl",
     "NodeStatus",
+    "ResettableTimer",
     "SubscribeHints",
     "monotonic_ns",
     "wall_clock_ns",

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

@@ -15,6 +15,7 @@ from contextlib import suppress
 from types import MappingProxyType
 from typing import Any
 
+from graphrefly.core.node import _SENTINEL
 from graphrefly.core.protocol import Messages, MessageType, emit_with_batch, propagates_to_meta
 
 # ---------------------------------------------------------------------------
@@ -189,7 +190,7 @@ class DynamicNodeImpl[T]:
         self._thread_safe = bool(thread_safe)
         self._inspector_hook: Callable[[dict[str, Any]], None] | None = None
 
-        self._cached: T | None = None
+        self._cached: Any = _SENTINEL
         self._status: str = "disconnected"
         self._terminal = False
         self._connected = False
@@ -277,8 +278,10 @@ class DynamicNodeImpl[T]:
         lock = self._cache_lock
         if lock is not None:
             with lock:
-                return self._cached
-        return self._cached
+                v = self._cached
+        else:
+            v = self._cached
+        return None if v is _SENTINEL else v
 
     def down(
         self,
@@ -346,6 +349,12 @@ class DynamicNodeImpl[T]:
     ) -> Callable[[], None]:
         if self._terminal and self._resubscribable:
             self._terminal = False
+            lock = self._cache_lock
+            if lock is not None:
+                with lock:
+                    self._cached = _SENTINEL
+            else:
+                self._cached = _SENTINEL
             self._status = "disconnected"
             if self._on_resubscribe is not None:
                 self._on_resubscribe()
@@ -519,11 +528,14 @@ class DynamicNodeImpl[T]:
             if t is MessageType.INVALIDATE:
                 if lock is not None:
                     with lock:
-                        self._cached = None
+                        self._cached = _SENTINEL
                 else:
-                    self._cached = None
-            if t is MessageType.DATA or t is MessageType.RESOLVED:
+                    self._cached = _SENTINEL
+                self._status = "dirty"
+            if t is MessageType.DATA:
                 self._status = "settled"
+            elif t is MessageType.RESOLVED:
+                self._status = "resolved"
             elif t is MessageType.DIRTY:
                 self._status = "dirty"
             elif t is MessageType.COMPLETE:
@@ -536,9 +548,9 @@ class DynamicNodeImpl[T]:
                 if self._reset_on_teardown:
                     if lock is not None:
                         with lock:
-                            self._cached = None
+                            self._cached = _SENTINEL
                     else:
-                        self._cached = None
+                        self._cached = _SENTINEL
                 try:
                     self._propagate_to_meta(t)
                 finally:
@@ -561,7 +573,13 @@ class DynamicNodeImpl[T]:
                 cached_snapshot = self._cached
         else:
             cached_snapshot = self._cached
-        unchanged = self._equals(cached_snapshot, value)
+        try:
+            unchanged = cached_snapshot is not _SENTINEL and self._equals(cached_snapshot, value)
+        except Exception as eq_err:
+            wrapped = RuntimeError(f'Node "{self._name}": equals threw: {eq_err}')
+            wrapped.__cause__ = eq_err
+            self._down_internal([(MessageType.ERROR, wrapped)])
+            return
         if unchanged:
             msgs: Messages = (
                 [(MessageType.RESOLVED,)]

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

@@ -32,6 +32,12 @@ from graphrefly.core.versioning import (
     default_hash,
 )
 
+# Internal sentinel: "no cached value has been set or emitted."
+# Distinct from None so that None can be a valid emitted value.
+_SENTINEL = object()
+
+NO_VALUE = _SENTINEL
+
 # --- Status & typing (graphrefly-ts node.ts) ---------------------------------
 
 type NodeStatus = str  # structural: same strings as TS NodeStatus
@@ -203,6 +209,7 @@ class NodeImpl[T]:
         "_meta",
         "_name",
         "_on_message",
+        "_on_resubscribe",
         "_opts",
         "_producer_started",
         "_resubscribable",
@@ -236,6 +243,7 @@ class NodeImpl[T]:
         self._thread_safe: bool = bool(opts.get("thread_safe", True))
 
         self._on_message = opts.get("on_message")
+        self._on_resubscribe: Callable[[], None] | None = opts.get("on_resubscribe")
         self._fn = fn
         self._deps = deps
         self._has_deps = len(deps) > 0
@@ -248,7 +256,7 @@ class NodeImpl[T]:
         self._last_mutation: dict[str, Any] | None = None
 
         self._cache_lock = threading.Lock() if self._thread_safe else None
-        self._cached: T | None = opts.get("initial")
+        self._cached: Any = opts["initial"] if "initial" in opts else _SENTINEL
         self._status: NodeStatus = "disconnected" if self._has_deps else "settled"
 
         # Versioning (GRAPHREFLY-SPEC §7)
@@ -257,7 +265,7 @@ class NodeImpl[T]:
         self._versioning: NodeVersionInfo | None = (
             create_versioning(
                 versioning_level,
-                self._cached,
+                None if self._cached is _SENTINEL else self._cached,
                 id=opts.get("versioning_id"),
                 hash_fn=self._hash_fn,
             )
@@ -368,9 +376,9 @@ class NodeImpl[T]:
                     cb()
                 if lock is not None:
                     with lock:
-                        self._cached = None
+                        self._cached = _SENTINEL
                 else:
-                    self._cached = None
+                    self._cached = _SENTINEL
                 self._last_dep_values = None
             self._status = _status_after_message(self._status, m)
             if t is MessageType.COMPLETE or t is MessageType.ERROR:
@@ -379,9 +387,9 @@ class NodeImpl[T]:
                 if self._reset_on_teardown:
                     if lock is not None:
                         with lock:
-                            self._cached = None
+                            self._cached = _SENTINEL
                     else:
-                        self._cached = None
+                        self._cached = _SENTINEL
                 # Invoke cleanup for compute nodes (deps+fn) — spec §2.4
                 if self._cleanup is not None:
                     cb = self._cleanup
@@ -416,7 +424,16 @@ class NodeImpl[T]:
                 cached_snapshot = self._cached
         else:
             cached_snapshot = self._cached
-        unchanged = self._equals(cached_snapshot, value)
+        # §2.5: equals() only compares two real DATA values. _SENTINEL
+        # disambiguates "never emitted" from "emitted None" and
+        # "reset via INVALIDATE/reset_on_teardown".
+        try:
+            unchanged = cached_snapshot is not _SENTINEL and self._equals(cached_snapshot, value)
+        except Exception as eq_err:
+            wrapped = RuntimeError(f'Node "{self._name}": equals threw: {eq_err}')
+            wrapped.__cause__ = eq_err
+            self.down([(MessageType.ERROR, wrapped)], internal=True)
+            return
         if unchanged:
             if was_dirty:
                 self.down([(MessageType.RESOLVED,)], internal=True)
@@ -470,7 +487,9 @@ class NodeImpl[T]:
                 return
             self._emit_auto_value(out)
         except Exception as err:
-            self.down([(MessageType.ERROR, err)], internal=True)
+            wrapped = RuntimeError(f'Node "{self._name}": fn threw: {err}')
+            wrapped.__cause__ = err
+            self.down([(MessageType.ERROR, wrapped)], internal=True)
 
     def _run_fn(self) -> None:
         if self._fn is None:
@@ -519,7 +538,9 @@ class NodeImpl[T]:
                     if self._on_message(msg, index, self._actions):
                         continue
                 except Exception as err:
-                    self.down([(MessageType.ERROR, err)], internal=True)
+                    wrapped = RuntimeError(f'Node "{self._name}": on_message threw: {err}')
+                    wrapped.__cause__ = err
+                    self.down([(MessageType.ERROR, wrapped)], internal=True)
                     return
             if self._fn is None:
                 if t is MessageType.COMPLETE and len(self._deps) > 1:
@@ -623,7 +644,15 @@ class NodeImpl[T]:
     ) -> None:
         if self._terminal and self._resubscribable:
             self._terminal = False
+            lock = self._cache_lock
+            if lock is not None:
+                with lock:
+                    self._cached = _SENTINEL
+            else:
+                self._cached = _SENTINEL
             self._status = "disconnected" if self._has_deps else "settled"
+            if self._on_resubscribe is not None:
+                self._on_resubscribe()
 
         h = hints or SubscribeHints()
         self._sink_count += 1
@@ -726,8 +755,10 @@ class NodeImpl[T]:
         lock = self._cache_lock
         if lock is not None:
             with lock:
-                return self._cached
-        return self._cached
+                v = self._cached
+        else:
+            v = self._cached
+        return None if v is _SENTINEL else v
 
     @property
     def last_mutation(self) -> dict[str, Any] | None:
@@ -760,7 +791,7 @@ class NodeImpl[T]:
             self._hash_fn = hash_fn
         self._versioning = create_versioning(
             level,
-            self._cached,
+            None if self._cached is _SENTINEL else self._cached,
             id=id,
             hash_fn=self._hash_fn,
         )
@@ -960,4 +991,4 @@ def node(
 # Public alias for type hints
 Node = NodeImpl
 
-__all__ = ["Node", "NodeActions", "NodeFn", "NodeImpl", "NodeStatus", "SubscribeHints", "node"]
+__all__ = ["NO_VALUE", "Node", "NodeActions", "NodeFn", "NodeImpl", "NodeStatus", "SubscribeHints", "node"]

{graphrefly-0.6.0 → graphrefly-0.7.0}/src/graphrefly/core/protocol.py

@@ -306,7 +306,7 @@ def emit_with_batch(
     messages: Messages,
     *,
     phase: int = 2,
-    strategy: EmitStrategy = "sequential",
+    strategy: EmitStrategy = "partition",
     defer_when: DeferWhen = "batching",
     subgraph_lock: object | None = None,
 ) -> None:
@@ -428,11 +428,11 @@ def _emit_sequential(
 
             queue.append(_wrap_deferred_subgraph(_emit, subgraph_lock))
         elif kind in _TERMINAL_TYPES and _should_defer_phase2(bs, defer_when):
-            # Terminal: defer so preceding deferred flushes first.
+            # Terminal: always route to phase-3 queue so all phase-2 drains first.
             def _emit_term(m: Message = msg, s: Callable[[Messages], None] = sink) -> None:
                 s([m])
 
-            queue.append(_wrap_deferred_subgraph(_emit_term, subgraph_lock))
+            bs.pending_phase3.append(_wrap_deferred_subgraph(_emit_term, subgraph_lock))
         else:
             sink([msg])
 

{graphrefly-0.6.0 → graphrefly-0.7.0}/src/graphrefly/core/sugar.py

@@ -14,7 +14,10 @@ def state(initial: Any, **opts: Any) -> Node[Any]:
     """Create a manually-settable source node with a fixed initial value.
 
     Args:
-        initial: The initial cached value for the node.
+        initial: The initial cached value for the node. Because ``initial`` is
+            provided, ``equals`` is called on the first ``down()`` emission — if
+            the value matches ``initial``, the node emits ``RESOLVED`` instead
+            of ``DATA`` (spec §2.5).
         **opts: Additional node options passed through to :func:`~graphrefly.core.node.node`.
 
     Returns:

graphrefly-0.7.0/src/graphrefly/core/timer.py

@@ -0,0 +1,39 @@
+"""Resettable deadline timer — centralised primitive for timeout, retry,
+and rate_limiter (§5.10 exception: these need cancel/restart;
+from_timer creates a new Node per reset)."""
+
+from __future__ import annotations
+
+import threading
+
+
+class ResettableTimer:
+    """Thread-safe resettable deadline timer."""
+
+    __slots__ = ("_timer", "_lock")
+
+    def __init__(self) -> None:
+        self._timer: threading.Timer | None = None
+        self._lock = threading.Lock()
+
+    def start(self, delay_seconds: float, callback: callable) -> None:
+        """Schedule callback after delay_seconds. Cancels any pending timer."""
+        with self._lock:
+            if self._timer is not None:
+                self._timer.cancel()
+            self._timer = threading.Timer(delay_seconds, callback)
+            self._timer.daemon = True
+            self._timer.start()
+
+    def cancel(self) -> None:
+        """Cancel the pending timer (if any)."""
+        with self._lock:
+            if self._timer is not None:
+                self._timer.cancel()
+                self._timer = None
+
+    @property
+    def pending(self) -> bool:
+        """Whether a timer is currently pending."""
+        with self._lock:
+            return self._timer is not None