graphrefly 0.4.0__tar.gz → 0.6.0__tar.gz

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

@@ -2,6 +2,32 @@
 
 <!-- version list -->
 
+## 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
+
+- Fix mobile nav
+  ([`a372c40`](https://github.com/graphrefly/graphrefly-py/commit/a372c40274d1cd7ec57b69414ada245605177334))
+
+### Features
+
+- Address optimization items
+  ([`8911fd4`](https://github.com/graphrefly/graphrefly-py/commit/8911fd41a177fe9cfaa7e8932f24f2c2af44135a))
+
+
 ## v0.4.0 (2026-04-04)
 
 ### Features

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

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

@@ -119,13 +119,34 @@ Union-find over node identity merges components when nodes list dependencies at
 - **`Graph.signal`:** `GuardDenied` aborts the walk on first rejection; nodes visited earlier in the traversal may already have received the message (non-transactional). Prefer guards that allow **system** `signal` when using `destroy()` / lifecycle if you need guaranteed completion.
 - **`Graph.remove` / `_teardown_mounted_graph`:** after the registry drops a name, primary `TEARDOWN` uses `Node.down(..., internal=True)` so a guard cannot reject teardown **after** unregister (would orphan the node instance).
 
+## Open design decisions
+
+- **~~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):** `_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.
+
 ---
 
 ## 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.
 
-- **Storage & sink adapter pattern parity (Phase 5.2d, 2026-04-03):** 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. Buffered sinks (`to_clickhouse`, `to_s3`, `to_file`, `to_csv`) return a `BufferedSinkHandle` with `dispose()` + `flush()`. Per-record sinks (`to_postgres`, `to_mongo`, `to_loki`, `to_tempo`) return an unsubscribe callable. 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.
+- **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.
+
+- **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.
+- **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.
 
 ### 1. Message type wire encoding
 
@@ -638,7 +659,7 @@ Both ports now align on the following:
    | `from_http` external cancellation | No external signal (deferred); unsubscribe suppresses late emissions | Supports external `AbortSignal` via options | Language/runtime cancellation primitives |
    | AbortSignal on async sources | Not supported (deferred) | `signal` option on `fromTimer`, `fromPromise`, `fromAsyncIter` | TS has native AbortSignal; Py deferred |
 
-   **Resolved (2026-03-31):** When implemented, async sources (`from_timer`, `from_awaitable`, `from_async_iter`) will accept the same `CancellationToken` protocol from parity follow-up #7 (a small interface with `.is_cancelled` property and `.on_cancel(fn)` callback registration, backed by `threading.Event`). `TEARDOWN`-via-unsubscribe remains the primary cancellation path; the token is for external/cooperative cancellation. Implementation deferred until a concrete user hits the gap, but the cancellation token design is settled.
+   **Resolved (2026-03-31, implemented 2026-04-04):** `CancellationToken` protocol and `cancellation_token()` factory implemented in `core/cancellation.py`. Exported from `graphrefly.core`. Backed by `threading.Event` with lock-protected callback list, `is_cancelled` property, `on_cancel(fn)` returning an unsubscribe callable, and `cancel()` method. Wiring into async sources (`from_timer`, `from_awaitable`, `from_async_iter`) deferred — the protocol is ready. `TEARDOWN`-via-unsubscribe remains the primary cancellation path; the token is for external/cooperative cancellation.
 
 ## Resolved design decisions (cross-language, 2026-04-03)
 

{graphrefly-0.4.0 → graphrefly-0.6.0}/docs/roadmap.md

@@ -299,10 +299,10 @@ 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
-- [ ] `from_sqlite(db, query)` / `to_sqlite(db, table)` — SQLite via sqlite3/better-sqlite interface
+- [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
 
@@ -330,14 +330,14 @@ Connectors for the universal reduction layer (Phase 8). Each wraps an external p
 
 ### 5.3c — Storage & sink adapters
 
-- [ ] `to_clickhouse(table, opts)` — buffered batch insert sink
-- [ ] `to_s3(bucket, opts)` — object storage sink (Parquet/NDJSON, partitioned; via `boto3`)
-- [ ] `to_postgres(table, opts)` / `to_mongo(collection, opts)` — document/relational sink
-- [ ] `to_loki(opts)` / `to_tempo(opts)` — Grafana stack sinks
-- [ ] `checkpoint_to_s3(bucket, opts)` — graph snapshot persistence to object storage
-- [ ] `checkpoint_to_redis(prefix, opts)` — fast checkpoint for ephemeral infra
-- [ ] `to_file(path, opts)` — file sink
-- [ ] `to_csv(path, opts)` — CSV file sink
+- [x] `to_clickhouse(table, opts)` — buffered batch insert sink
+- [x] `to_s3(bucket, opts)` — object storage sink (Parquet/NDJSON, partitioned; via `boto3`)
+- [x] `to_postgres(table, opts)` / `to_mongo(collection, opts)` — document/relational sink
+- [x] `to_loki(opts)` / `to_tempo(opts)` — Grafana stack sinks
+- [x] `checkpoint_to_s3(bucket, opts)` — graph snapshot persistence to object storage
+- [x] `checkpoint_to_redis(prefix, opts)` — fast checkpoint for ephemeral infra
+- [x] `to_file(path, opts)` — file sink
+- [x] `to_csv(path, opts)` — CSV file sink
 
 ### 5.4 — LLM tool integration
 

{graphrefly-0.4.0/website/public → graphrefly-0.6.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.4.0 → graphrefly-0.6.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "graphrefly"
-version = "0.4.0"
+version = "0.6.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",
@@ -60,6 +62,8 @@ dev = [
 	"croniter>=2.0",
 	"fastapi>=0.100",
 	"httpx>=0.24",
+	"pillow>=12.2.0",
+	"trio>=0.33.0",
 ]
 
 [tool.semantic_release]

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

@@ -1,5 +1,6 @@
 """Core node primitives and protocol types for graphrefly."""
 
+from graphrefly.core.cancellation import CancellationToken, cancellation_token
 from graphrefly.core.clock import monotonic_ns, wall_clock_ns
 from graphrefly.core.dynamic_node import DynamicNodeImpl, dynamic_node
 from graphrefly.core.guard import (
@@ -77,6 +78,8 @@ from graphrefly.core.versioning import (
 
 __all__ = [
     "Actor",
+    "CancellationToken",
+    "cancellation_token",
     "DynamicNodeImpl",
     "DeferWhen",
     "EmitStrategy",

graphrefly-0.6.0/src/graphrefly/core/cancellation.py

@@ -0,0 +1,91 @@
+"""Cooperative cancellation token for async/LLM boundaries.
+
+The ``CancellationToken`` protocol provides a small interface for cooperative
+cancellation that mirrors TypeScript's ``AbortSignal`` pattern.  It is backed
+by ``threading.Event`` and is fully reactive (no polling — callbacks fire
+immediately on cancellation).
+
+Usage::
+
+    token = cancellation_token()
+    token.on_cancel(lambda: print("cancelled"))
+    token.cancel()  # fires callback synchronously
+
+Pass into ``LLMAdapter.invoke()`` via ``LLMInvokeOptions`` so adapters can
+react to cancellation without polling.
+"""
+
+from __future__ import annotations
+
+import threading
+from contextlib import suppress
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+
+@runtime_checkable
+class CancellationToken(Protocol):
+    """Cooperative cancellation token (cross-language: TS ``AbortSignal``)."""
+
+    @property
+    def is_cancelled(self) -> bool:
+        """Whether cancellation has been requested."""
+        ...
+
+    def on_cancel(self, fn: Callable[[], None]) -> Callable[[], None]:
+        """Register a callback to fire on cancellation.
+
+        Returns an unsubscribe callable that removes the callback.
+        If already cancelled, ``fn`` fires synchronously before returning.
+        """
+        ...
+
+
+class _CancellationTokenImpl:
+    """Concrete cancellation token backed by ``threading.Event``."""
+
+    __slots__ = ("_event", "_callbacks", "_lock")
+
+    def __init__(self) -> None:
+        self._event = threading.Event()
+        self._callbacks: list[Callable[[], None]] = []
+        self._lock = threading.Lock()
+
+    @property
+    def is_cancelled(self) -> bool:
+        return self._event.is_set()
+
+    def on_cancel(self, fn: Callable[[], None]) -> Callable[[], None]:
+        with self._lock:
+            if self._event.is_set():
+                fn()
+                return lambda: None
+            self._callbacks.append(fn)
+
+        def _unsub() -> None:
+            with self._lock, suppress(ValueError):
+                self._callbacks.remove(fn)
+
+        return _unsub
+
+    def cancel(self) -> None:
+        """Request cancellation.  Fires all registered callbacks synchronously."""
+        with self._lock:
+            if self._event.is_set():
+                return
+            self._event.set()
+            cbs = list(self._callbacks)
+            self._callbacks.clear()
+        for cb in cbs:
+            cb()
+
+
+def cancellation_token() -> _CancellationTokenImpl:
+    """Create a new cancellation token.
+
+    Returns a concrete token with ``cancel()``, ``is_cancelled``, and
+    ``on_cancel(fn)`` methods.
+    """
+    return _CancellationTokenImpl()

{graphrefly-0.4.0 → graphrefly-0.6.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",