graphrefly 0.5.0__tar.gz → 0.6.0__tar.gz

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

@@ -2,6 +2,19 @@
 
 <!-- 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

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

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

@@ -124,6 +124,16 @@ 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):** `_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.
 
 ---
 
@@ -131,6 +141,10 @@ Union-find over node identity merges components when nodes list dependencies at
 
 **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.
+
+- **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.
 

{graphrefly-0.5.0 → graphrefly-0.6.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.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.5.0 → graphrefly-0.6.0}/pyproject.toml

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

{graphrefly-0.5.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",

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

@@ -0,0 +1,246 @@
+"""Meta companion stores — graphrefly-ts ``src/core/meta.ts``."""
+
+from __future__ import annotations
+
+from contextlib import suppress
+from dataclasses import asdict
+from typing import TYPE_CHECKING, Any, Literal, Protocol
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+from graphrefly.core.dynamic_node import DynamicNodeImpl
+from graphrefly.core.guard import access_hint_for_guard
+from graphrefly.core.node import NodeImpl  # noqa: TC001 — runtime type for describe_node
+from graphrefly.core.versioning import is_v1
+
+__all__ = [
+    "DescribeDetail",
+    "DescribeField",
+    "describe_node",
+    "meta_snapshot",
+    "resolve_describe_fields",
+]
+
+# ---------------------------------------------------------------------------
+# Progressive disclosure types (Phase 3.3b)
+# ---------------------------------------------------------------------------
+
+DescribeDetail = Literal["minimal", "standard", "full"]
+DescribeField = str  # "type", "status", "value", "deps", "meta", "v", etc.
+
+
+def resolve_describe_fields(
+    detail: DescribeDetail | None = None,
+    fields: list[str] | None = None,
+) -> set[str] | None:
+    """Resolve which fields to include. fields overrides detail. None = all fields."""
+    if fields is not None and len(fields) > 0:
+        return set(fields)
+    if detail == "standard":
+        return {"type", "status", "value", "deps", "meta", "v"}
+    if detail == "full":
+        return None  # all
+    # minimal (default)
+    return {"type", "deps"}
+
+
+class _MetaNode(Protocol):
+    """Parent node: read-only ``meta`` mapping (e.g. ``MappingProxyType``)."""
+
+    @property
+    def meta(self) -> Mapping[str, Any]: ...
+
+    def get(self) -> Any: ...
+
+
+def meta_snapshot(node: _MetaNode) -> dict[str, Any]:
+    """Merge current meta field values into a plain dict for describe-style JSON.
+
+    Values come from each companion node's ``get()`` (last settled cache). If a meta
+    field is dirty (``DIRTY`` received, ``DATA`` pending), the snapshot holds the
+    previous value — check ``node.meta[key].status`` when freshness matters.
+    Keys whose companion ``get()`` raises are omitted so describe tooling keeps other
+    fields intact.
+
+    Args:
+        node: Any object with a ``meta`` mapping of ``str -> Node`` and a ``get()`` method.
+
+    Returns:
+        A plain ``dict`` mapping each meta key to its last settled value.
+
+    Example:
+        ```python
+        from graphrefly import state
+        from graphrefly.core.meta import meta_snapshot
+        x = state(0, meta={"version": 1})
+        snap = meta_snapshot(x)
+        # snap == {"version": 1}
+        ```
+    """
+    out: dict[str, Any] = {}
+    for key, child in node.meta.items():
+        with suppress(Exception):
+            out[key] = child.get()
+    return out
+
+
+def _infer_describe_type(n: NodeImpl[Any]) -> str:
+    """Best-effort ``type`` for GRAPHREFLY-SPEC describe node shape (§3.6, Appendix B)."""
+    if n._describe_kind is not None:
+        return n._describe_kind
+    if not n._has_deps:
+        return "state" if n._fn is None else "producer"
+    if n._fn is None:
+        return "derived"
+    if n._manual_emit_used:
+        return "operator"
+    return "derived"
+
+
+def _wants_field(include_fields: set[str] | None, field: str) -> bool:
+    """Return True if *field* should be included given *include_fields*."""
+    if include_fields is None:
+        return True
+    return field in include_fields
+
+
+def _wants_opt_in_field(include_fields: set[str] | None, *names: str) -> bool:
+    """Return True when one of *names* is included in the resolved field set.
+
+    ``None`` means full mode (all fields) so opt-in fields are included.
+    For preset detail levels (``"minimal"``, ``"standard"``), the set won't
+    contain these names, so they stay excluded unless explicitly requested via
+    ``fields``.
+    """
+    if include_fields is None:
+        return True  # full mode → include everything
+    return any(n in include_fields for n in names)
+
+
+def _wants_meta(include_fields: set[str] | None) -> bool:
+    """Return True if any meta content should be included."""
+    if include_fields is None:
+        return True
+    if "meta" in include_fields:
+        return True
+    return any(f.startswith("meta.") for f in include_fields)
+
+
+def _filter_meta(full_meta: dict[str, Any], include_fields: set[str]) -> dict[str, Any]:
+    """When dotted meta paths are requested (e.g. 'meta.label'), return only those keys."""
+    if "meta" in include_fields:
+        return full_meta  # whole meta requested
+    dotted = {f.split(".", 1)[1] for f in include_fields if f.startswith("meta.")}
+    if not dotted:
+        return full_meta
+    return {k: v for k, v in full_meta.items() if k in dotted}
+
+
+def describe_node(
+    n: NodeImpl[Any] | DynamicNodeImpl[Any],
+    include_fields: set[str] | None = None,
+) -> dict[str, Any]:
+    """Build a single-node slice of ``Graph.describe()`` JSON (structure + ``meta`` snapshot).
+
+    The ``meta`` field uses :func:`meta_snapshot` (plain values), matching the
+    spec's describe shape (GRAPHREFLY-SPEC Appendix B). ``type`` is inferred from
+    factory configuration, optional ``describe_kind`` in node options, and the last
+    ``_manual_emit_used`` hint (operator vs derived). Sugar constructors
+    (``effect``, ``producer``, ``derived``) set ``describe_kind`` automatically.
+
+    Args:
+        n: A :class:`~graphrefly.core.node.NodeImpl` or
+           :class:`~graphrefly.core.dynamic_node.DynamicNodeImpl` to describe.
+        include_fields: Optional set of field names to include. ``None`` means all
+            fields (full mode). ``type`` and ``deps`` are always included.
+
+    Returns:
+        A ``dict`` with keys ``type``, ``deps``, and optionally ``status``, ``meta``,
+        ``name``, ``value``, ``v``, ``guard``, and ``last_mutation``.
+
+    Example:
+        ```python
+        from graphrefly import state
+        from graphrefly.core.meta import describe_node
+        x = state(42, name="x")
+        d = describe_node(x)
+        assert d["type"] == "state"
+        assert d["value"] == 42
+        ```
+    """
+    if isinstance(n, DynamicNodeImpl):
+        out: dict[str, Any] = {
+            "type": n._describe_kind or "derived",
+            "deps": [],
+        }
+        if _wants_field(include_fields, "status"):
+            out["status"] = n.status
+        if _wants_meta(include_fields):
+            full_meta = meta_snapshot(n)
+            g = n._guard
+            if g is not None and "access" not in full_meta:
+                full_meta["access"] = access_hint_for_guard(g)
+            if include_fields is not None:
+                out["meta"] = _filter_meta(full_meta, include_fields)
+            else:
+                out["meta"] = full_meta
+        if n.name is not None:
+            out["name"] = n.name
+        if _wants_field(include_fields, "value"):
+            with suppress(Exception):
+                out["value"] = n.get()
+        # Guard access hint (standalone opt-in field)
+        if _wants_opt_in_field(include_fields, "guard") and n._guard is not None:
+            out["guard"] = access_hint_for_guard(n._guard)
+        # last_mutation (opt-in)
+        if _wants_opt_in_field(include_fields, "lastMutation", "last_mutation"):
+            lm = n.last_mutation
+            if lm is not None:
+                out["last_mutation"] = asdict(lm)
+        # Versioning (GRAPHREFLY-SPEC §7)
+        if _wants_field(include_fields, "v") and hasattr(n, "v") and n.v is not None:
+            out["v"] = _versioning_dict(n.v)
+        return out
+
+    out = {
+        "type": _infer_describe_type(n),
+        "deps": [d.name or "" for d in n._deps],
+    }
+    if _wants_field(include_fields, "status"):
+        out["status"] = n.status
+    if _wants_meta(include_fields):
+        full_meta = meta_snapshot(n)
+        g = n._guard
+        if g is not None and "access" not in full_meta:
+            full_meta["access"] = access_hint_for_guard(g)
+        if include_fields is not None:
+            out["meta"] = _filter_meta(full_meta, include_fields)
+        else:
+            out["meta"] = full_meta
+    if n.name is not None:
+        out["name"] = n.name
+    if _wants_field(include_fields, "value"):
+        with suppress(Exception):
+            out["value"] = n.get()
+    # Guard access hint (standalone opt-in field)
+    if _wants_opt_in_field(include_fields, "guard") and n._guard is not None:
+        out["guard"] = access_hint_for_guard(n._guard)
+    # last_mutation (opt-in)
+    if _wants_opt_in_field(include_fields, "lastMutation", "last_mutation"):
+        lm = n.last_mutation
+        if lm is not None:
+            out["last_mutation"] = asdict(lm)
+    # Versioning (GRAPHREFLY-SPEC §7)
+    if _wants_field(include_fields, "v") and n.v is not None:
+        out["v"] = _versioning_dict(n.v)
+    return out
+
+
+def _versioning_dict(v: Any) -> dict[str, Any]:
+    """Convert versioning info to a plain dict for JSON serialization."""
+    d: dict[str, Any] = {"id": v.id, "version": v.version}
+    if is_v1(v):
+        d["cid"] = v.cid
+        d["prev"] = v.prev
+    return d