graphrefly 0.5.0__tar.gz → 0.7.0__tar.gz

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

@@ -2,6 +2,30 @@
 
 <!-- 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
+
+- Inspector + data_class
+  ([`5bfb409`](https://github.com/graphrefly/graphrefly-py/commit/5bfb409eb62a82cc72d7b4d404981789ded3a3ca))
+
+### Features
+
+- 3.1c
+  ([`914e424`](https://github.com/graphrefly/graphrefly-py/commit/914e424e7f934b71e407da187536c16cb63ee43a))
+
+
 ## v0.5.0 (2026-04-05)
 
 ### Chores

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: graphrefly
-Version: 0.5.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
@@ -8,7 +8,7 @@ Project-URL: Documentation, https://py.graphrefly.dev
 Author: David Chen
 License-Expression: MIT
 License-File: LICENSE
-Keywords: ai-agents,asyncio,callbag,diamond-resolution,durable-workflow,graph,llm,observable,orchestration,reactive,reactive-programming,signals,state-management,streaming,zero-dependency
+Keywords: ai-agents,asyncio,automation,causal-tracing,durable-workflow,graph,human-in-the-loop,llm,natural-language,observable,orchestration,reactive,signals,state-management,streaming,workflow,zero-dependency
 Classifier: Development Status :: 3 - Alpha
 Classifier: Framework :: AsyncIO
 Classifier: Intended Audience :: Developers
@@ -25,9 +25,9 @@ Description-Content-Type: text/markdown
 
 # GraphReFly
 
-**Reactive graph protocol for human + LLM co-operation.**
+**Describe what matters. It watches, filters, and explains — persistently.**
 
-One primitive. Zero dependencies. Composable nodes with glitch-free diamond resolution, two-phase push propagation, durable streaming, and async runners for asyncio and trio.
+You're buried under emails, alerts, feeds, and messages. You can't process it all. GraphReFly lets you describe automations in plain language, review them visually, run them persistently, and trace every decision back to its source.
 
 [![PyPI](https://img.shields.io/pypi/v/graphrefly?color=blue)](https://pypi.org/project/graphrefly/)
 [![license](https://img.shields.io/github/license/graphrefly/graphrefly-py)](./LICENSE)
@@ -37,6 +37,18 @@ One primitive. Zero dependencies. Composable nodes with glitch-free diamond reso
 
 ---
 
+<!-- TODO: Demo 0 GIF/video — NL → flow view → running → "why was this flagged?" -->
+
+## What can you do with it?
+
+**Email triage** — "Watch my inbox. Urgent emails from my team go to a priority list. Newsletters get summarized weekly. Everything else, count by sender." It watches, classifies, and alerts — and when you ask "why was this flagged?", it walks you through the reasoning.
+
+**Spending alerts** — Connect bank transactions to budget categories. Get a push notification when monthly dining exceeds your target. No polling, no manual checks — changes propagate the moment data arrives.
+
+**Knowledge management** — Notes, bookmarks, highlights flow in. Contradictions surface automatically. Related ideas link themselves. Your second brain stays current without you maintaining it.
+
+---
+
 ## Quick start
 
 ```bash
@@ -56,20 +68,24 @@ count.push(3)
 # → doubled: 6
 ```
 
+## How it works
+
+You describe what you need — an LLM composes a reactive graph (like SQL for data flows). The graph runs persistently, checkpoints its state, and traces every decision through a causal chain. Ask "why?" at any point and get a human-readable explanation from source to conclusion.
+
 ## Why GraphReFly?
 
-Most state libraries solve **one** problem well. GraphReFly solves the space between them:
-
-|  | Redux / Zustand | RxPY | Pydantic AI | TC39 Signals | **GraphReFly** |
-|--|-----------------|------|-------------|-------------|---------------|
-| Simple store API | yes | no | no | yes | **yes** |
-| Streaming operators | no | yes | no | no | **yes** |
-| Diamond resolution | no | n/a | n/a | partial | **glitch-free** |
-| Graph introspection | no | no | no | no | **describe / observe / diagram** |
-| Durable checkpoints | no | no | no | no | **file / SQLite / IndexedDB** |
-| LLM orchestration | no | no | partial | no | **agent_loop / chat_stream / tool_registry** |
-| Async runners | n/a | asyncio | asyncio | n/a | **asyncio / trio** |
-| Dependencies | varies | 0 | many | n/a | **0** |
+|  | Redux / Zustand | RxPY | Pydantic AI | LangGraph | TC39 Signals | **GraphReFly** |
+|--|-----------------|------|-------------|-----------|-------------|---------------|
+| Simple store API | yes | no | no | no | yes | **yes** |
+| Streaming operators | no | yes | no | no | no | **yes** |
+| Diamond resolution | no | n/a | n/a | n/a | partial | **glitch-free** |
+| Graph introspection | no | no | no | checkpoints | no | **describe / observe / diagram** |
+| Causal tracing | no | no | no | no | no | **explain every decision** |
+| Durable checkpoints | no | no | no | yes | no | **file / SQLite / IndexedDB** |
+| LLM orchestration | no | no | partial | yes | no | **agent_loop / chat_stream / tool_registry** |
+| NL → graph composition | no | no | no | no | no | **graph_from_spec / llm_compose** |
+| Async runners | n/a | asyncio | asyncio | asyncio | n/a | **asyncio / trio** |
+| Dependencies | varies | 0 | many | many | n/a | **0** |
 
 ## One primitive
 

{graphrefly-0.5.0 → graphrefly-0.7.0}/README.md

@@ -1,8 +1,8 @@
 # GraphReFly
 
-**Reactive graph protocol for human + LLM co-operation.**
+**Describe what matters. It watches, filters, and explains — persistently.**
 
-One primitive. Zero dependencies. Composable nodes with glitch-free diamond resolution, two-phase push propagation, durable streaming, and async runners for asyncio and trio.
+You're buried under emails, alerts, feeds, and messages. You can't process it all. GraphReFly lets you describe automations in plain language, review them visually, run them persistently, and trace every decision back to its source.
 
 [![PyPI](https://img.shields.io/pypi/v/graphrefly?color=blue)](https://pypi.org/project/graphrefly/)
 [![license](https://img.shields.io/github/license/graphrefly/graphrefly-py)](./LICENSE)
@@ -12,6 +12,18 @@ One primitive. Zero dependencies. Composable nodes with glitch-free diamond reso
 
 ---
 
+<!-- TODO: Demo 0 GIF/video — NL → flow view → running → "why was this flagged?" -->
+
+## What can you do with it?
+
+**Email triage** — "Watch my inbox. Urgent emails from my team go to a priority list. Newsletters get summarized weekly. Everything else, count by sender." It watches, classifies, and alerts — and when you ask "why was this flagged?", it walks you through the reasoning.
+
+**Spending alerts** — Connect bank transactions to budget categories. Get a push notification when monthly dining exceeds your target. No polling, no manual checks — changes propagate the moment data arrives.
+
+**Knowledge management** — Notes, bookmarks, highlights flow in. Contradictions surface automatically. Related ideas link themselves. Your second brain stays current without you maintaining it.
+
+---
+
 ## Quick start
 
 ```bash
@@ -31,20 +43,24 @@ count.push(3)
 # → doubled: 6
 ```
 
+## How it works
+
+You describe what you need — an LLM composes a reactive graph (like SQL for data flows). The graph runs persistently, checkpoints its state, and traces every decision through a causal chain. Ask "why?" at any point and get a human-readable explanation from source to conclusion.
+
 ## Why GraphReFly?
 
-Most state libraries solve **one** problem well. GraphReFly solves the space between them:
-
-|  | Redux / Zustand | RxPY | Pydantic AI | TC39 Signals | **GraphReFly** |
-|--|-----------------|------|-------------|-------------|---------------|
-| Simple store API | yes | no | no | yes | **yes** |
-| Streaming operators | no | yes | no | no | **yes** |
-| Diamond resolution | no | n/a | n/a | partial | **glitch-free** |
-| Graph introspection | no | no | no | no | **describe / observe / diagram** |
-| Durable checkpoints | no | no | no | no | **file / SQLite / IndexedDB** |
-| LLM orchestration | no | no | partial | no | **agent_loop / chat_stream / tool_registry** |
-| Async runners | n/a | asyncio | asyncio | n/a | **asyncio / trio** |
-| Dependencies | varies | 0 | many | n/a | **0** |
+|  | Redux / Zustand | RxPY | Pydantic AI | LangGraph | TC39 Signals | **GraphReFly** |
+|--|-----------------|------|-------------|-----------|-------------|---------------|
+| Simple store API | yes | no | no | no | yes | **yes** |
+| Streaming operators | no | yes | no | no | no | **yes** |
+| Diamond resolution | no | n/a | n/a | n/a | partial | **glitch-free** |
+| Graph introspection | no | no | no | checkpoints | no | **describe / observe / diagram** |
+| Causal tracing | no | no | no | no | no | **explain every decision** |
+| Durable checkpoints | no | no | no | yes | no | **file / SQLite / IndexedDB** |
+| LLM orchestration | no | no | partial | yes | no | **agent_loop / chat_stream / tool_registry** |
+| NL → graph composition | no | no | no | no | no | **graph_from_spec / llm_compose** |
+| Async runners | n/a | asyncio | asyncio | asyncio | n/a | **asyncio / trio** |
+| Dependencies | varies | 0 | many | many | n/a | **0** |
 
 ## One primitive
 

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

@@ -124,13 +124,41 @@ Union-find over node identity merges components when nodes list dependencies at
 - **~~Sink adapter silent error swallowing (Phase 5.2b–5.2d, noted 2026-04-04, resolved 2026-04-04):~~** All per-record sinks now return a `SinkHandle` (or `BufferedSinkHandle`) with a reactive `errors` companion node. The `_create_sink_error_handler()` factory always writes to the errors node; if a user callback is also provided, it fires first. `dispose()` sends `TEARDOWN` to the errors node. Mirrors TS implementation. Re-entrant batch drain protection applied via `contextlib.suppress(Exception)` around `errors_node.down()`.
 - **~~TS buffered sinks missing ERROR flush (Phase 5.3c, noted 2026-04-04, resolved 2026-04-04):~~** Both TS and PY buffered sinks now use `messageTier(msg[0]) >= 3` / `message_tier(msg[0]) >= 3` to flush on any terminal (COMPLETE, ERROR, TEARDOWN). Previously both used hardcoded `COMPLETE || TEARDOWN` checks and silently dropped buffered data on upstream ERROR.
 - **~~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, 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, 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` 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.
 
@@ -298,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)
@@ -316,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)
 
@@ -363,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) |
@@ -385,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)
@@ -521,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.5.0 → graphrefly-0.7.0}/docs/roadmap.md

@@ -299,9 +299,9 @@ Composition layer over 3.2 (`reactive_log`), 4.1 (sagas), 4.2 (event bus), 4.3 (
 
 ### 5.2 — ORM Adapters
 
-- [ ] SQLAlchemy ORM integration
-- [ ] Django ORM integration
-- [ ] Tortoise ORM integration
+- [x] SQLAlchemy ORM integration
+- [x] Django ORM integration
+- [x] Tortoise ORM integration
 - [x] `from_sqlite(db, query)` / `to_sqlite(db, table)` — SQLite via duck-typed `SqliteDbLike` (`query()` method); one-shot source + per-record sink; sync
 
 ### 5.3 — Adapters

{graphrefly-0.5.0/website/public → graphrefly-0.7.0}/llms.txt

@@ -1,6 +1,8 @@
 # GraphReFly — graphrefly (Python)
 
-GraphReFly is a reactive graph protocol for human + LLM co-operation. This package is the Python implementation (`graphrefly`).
+Describe automations in plain language. Review them visually. Run them persistently. Trace every decision back to its source.
+
+GraphReFly is a reactive graph engine for human + LLM co-operation. An LLM composes a reactive graph from a natural-language description (like SQL for data flows). The graph runs persistently, checkpoints state, and traces every decision through a causal chain — enabling explainability ("why was this flagged?"), auditability, and progressive trust accumulation. This package is the Python implementation (`graphrefly`). Zero dependencies.
 
 ## Authoritative behavior
 

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

@@ -1,6 +1,6 @@
 [project]
 name = "graphrefly"
-version = "0.5.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"
@@ -9,19 +9,21 @@ authors = [{ name = "David Chen" }]
 keywords = [
 	"reactive",
 	"graph",
+	"automation",
+	"workflow",
+	"llm",
+	"ai-agents",
+	"orchestration",
 	"state-management",
 	"signals",
 	"streaming",
-	"llm",
-	"ai-agents",
 	"observable",
-	"orchestration",
+	"causal-tracing",
+	"human-in-the-loop",
+	"natural-language",
 	"durable-workflow",
-	"diamond-resolution",
-	"zero-dependency",
 	"asyncio",
-	"callbag",
-	"reactive-programming",
+	"zero-dependency",
 ]
 classifiers = [
 	"Development Status :: 3 - Alpha",

{graphrefly-0.5.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.5.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.5.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.5.0 → graphrefly-0.7.0}/src/graphrefly/core/guard.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 from collections.abc import Callable, Mapping
+from dataclasses import dataclass
 from typing import Any, Literal, TypedDict
 
 type GuardAction = str
@@ -255,11 +256,19 @@ def access_hint_for_guard(guard: GuardFn) -> str:
     return "+".join(allowed)
 
 
-def record_mutation(actor: Mapping[str, Any]) -> dict[str, Any]:
+@dataclass(frozen=True, slots=True)
+class MutationRecord:
+    """Snapshot for :attr:`~graphrefly.core.node.NodeImpl.last_mutation`."""
+
+    actor: dict[str, Any]
+    timestamp_ns: int
+
+
+def record_mutation(actor: Mapping[str, Any]) -> MutationRecord:
     """Snapshot for :attr:`~graphrefly.core.node.NodeImpl.last_mutation`."""
     from graphrefly.core.clock import wall_clock_ns
 
-    return {"actor": dict(normalize_actor(actor)), "timestamp_ns": wall_clock_ns()}
+    return MutationRecord(actor=dict(normalize_actor(actor)), timestamp_ns=wall_clock_ns())
 
 
 __all__ = [
@@ -267,6 +276,7 @@ __all__ = [
     "GuardAction",
     "GuardDenied",
     "GuardFn",
+    "MutationRecord",
     "access_hint_for_guard",
     "compose_guards",
     "normalize_actor",