graphrefly 0.16.0__tar.gz → 0.18.0__tar.gz

{graphrefly-0.16.0 → graphrefly-0.18.0}/.claude/skills/dev-dispatch/SKILL.md

@@ -22,7 +22,7 @@ Load context and plan the implementation in a single pass. **Parallelize all rea
 Read in parallel:
 
 - **`~/src/graphrefly/GRAPHREFLY-SPEC.md`** — primary behavioral authority; read sections relevant to the task
-- **`~/src/graphrefly/COMPOSITION-GUIDE.md`** — composition patterns and 坑 (read when building Phase 4+ factories that compose primitives — covers lazy activation, subscription ordering, null guards, Versioned navigation, factory wiring order)
+- **`~/src/graphrefly/COMPOSITION-GUIDE.md`** — composition patterns and insights (read when building Phase 4+ factories that compose primitives — covers lazy activation, subscription ordering, null guards, Versioned navigation, factory wiring order)
 - `docs/optimizations.md` — **active work items**, anti-patterns, and **deferred follow-ups** (read when touching protocol, batch, node lifecycle, or parity). Resolved decisions are archived in `archive/optimizations/*.jsonl` — search there for historical context (see `docs/docs-guidance.md` § "Optimization decision log")
 - **`docs/test-guidance.md`** — checklists for the layer you touch (protocol, node, graph, operators)
 - **`docs/roadmap.md`** — phase alignment and acceptance criteria (active/open items only; completed phases archived to `archive/roadmap/*.jsonl`)

{graphrefly-0.16.0 → graphrefly-0.18.0}/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 <!-- version list -->
 
+## v0.18.0 (2026-04-08)
+
+### Features
+
+- Address optimizations
+  ([`beddc97`](https://github.com/graphrefly/graphrefly-py/commit/beddc979beda1b8320f4eb94f997c7ee142abed4))
+
+
+## v0.17.0 (2026-04-07)
+
+### Features
+
+- 9.0 part 2
+  ([`1f2bcb7`](https://github.com/graphrefly/graphrefly-py/commit/1f2bcb704ab86e62901114a08433f42edf6a5415))
+
+
 ## v0.16.0 (2026-04-07)
 
 ### Features

{graphrefly-0.16.0 → graphrefly-0.18.0}/CLAUDE.md

@@ -31,8 +31,9 @@ install dependencies.
 ## Key docs
 
 - `~/src/graphrefly/GRAPHREFLY-SPEC.md` — protocol and behavioral specification (shared with graphrefly-ts)
-- `~/src/graphrefly/COMPOSITION-GUIDE.md` — **composition guide** — 坑, patterns, recipes for Phase 4+ factory authors. Read before building factories that compose primitives.
+- `~/src/graphrefly/COMPOSITION-GUIDE.md` — **composition guide** — insights, patterns, recipes for Phase 4+ factory authors. **Read before building factories that compose primitives.** Covers: lazy activation, subscription ordering, null guards, feedback cycles, promptNode SENTINEL, wiring order.
 - `~/src/graphrefly/composition-guide.jsonl` — machine-readable composition entries (appendable)
+- `archive/optimizations/` — **Optimizations archive** — built-in optimizations, resolved design decisions, cross-language parity notes, proposed improvements. Check before introducing new optimizations or debugging perf issues.
 - `docs/roadmap.md` — phased implementation plan
 - `docs/docs-guidance.md` — how to write and maintain documentation here
 - `docs/test-guidance.md` — testing conventions and organization

{graphrefly-0.16.0 → graphrefly-0.18.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: graphrefly
-Version: 0.16.0
+Version: 0.18.0
 Summary: Reactive harness layer for agent workflows. Describe automations in plain language, trace every decision, enforce policies, persist checkpoints. Zero dependencies.
 Project-URL: Homepage, https://py.graphrefly.dev
 Project-URL: Repository, https://github.com/graphrefly/graphrefly-py

{graphrefly-0.16.0 → graphrefly-0.18.0}/archive/optimizations/qa-design-decisions.jsonl

@@ -7,4 +7,5 @@
 {"id": "ingest-adapters-intentional-divergences", "title": "Ingest adapters intentional divergences", "status": "documented", "body": "### Ingest adapters — intentional cross-language divergences (parity review 2026-04-03)\n\n| Aspect | TypeScript | Python | Rationale |\n|--------|-----------|--------|-----------|\n| **`KafkaConsumerLike` protocol** | KafkaJS shape: `subscribe({topic, fromBeginning})`, `run({eachMessage})`, `disconnect()` | confluent-kafka shape: `subscribe(topics: list)`, `run(callback)` | Each port targets its ecosystem's dominant Kafka client library. Both are duck-typed; users plug in their library's consumer directly. |\n| **`RedisClientLike` protocol** | ioredis shape: `xadd(key, id, ...fieldsAndValues)`, `xread(...args)` — variadic positional | redis-py shape: `xadd(name, fields: dict)`, `xread(streams: dict)` — dict-based | Same reasoning: each port matches the dominant Redis client for its ecosystem. Serialize defaults match (`string[]` vs `dict[str, str]`). |\n| **`toSSE` / `to_sse` return type** | `ReadableStream<Uint8Array>` (Web Streams API) | `Iterator[str]` (Python generator) | Language-native streaming idiom. TS uses Web Streams for SSE (compatible with `Response` constructor); PY uses generators (compatible with WSGI/ASGI streaming responses). |\n| **`fromPrometheus` / `fromClickHouseWatch` `signal` option** | `signal: AbortSignal` for external cancellation | No equivalent; uses `active[0]` flag on teardown | PY has no standard `AbortSignal`. External cancellation in PY is handled by unsubscribing (which triggers the cleanup/stop function). Both ports stop cleanly on teardown. |\n| **`SyslogMessage` field naming** | camelCase: `appName`, `procId`, `msgId` | snake_case: `app_name`, `proc_id`, `msg_id` | Language convention applied to output data structures. Each port follows its ecosystem's naming idiom. |\n| **`fromCSV` / `fromNDJSON` source type** | `AsyncIterable<string>` (async streams with chunk buffering) | `Iterable[str]` (sync iterators via threads) | PY uses threads for I/O concurrency; sync iterables are natural for `csv.reader` integration. TS uses async iteration for streaming I/O. |\n| **`PulsarConsumerLike` protocol** | `pulsar-client` JS shape: `receive()` returns Promise, `acknowledge(msg)` returns Promise, getter methods (`getData()`, `getTopicName()`, etc.) | `pulsar-client` PY shape: `receive()` blocking, `acknowledge(msg)` sync, attribute methods (`data()`, `topic_name()`, etc.) | Each port matches the native Pulsar client API for its ecosystem. TS uses async loop; PY uses threaded blocking loop. |\n| **`PulsarProducerLike.send()` call shape** | Single object: `send({data, partitionKey, properties})` | Positional + kwargs: `send(data, partition_key=..., properties=...)` | Matches respective native Pulsar client SDK calling conventions. |\n| **`PulsarMessage` field naming** | camelCase: `messageId`, `publishTime`, `eventTime` | snake_case: `message_id`, `publish_time`, `event_time` | Language convention applied to output data structures. |\n| **`NATSClientLike` protocol** | nats.js shape: `subscribe()` returns `AsyncIterable`, `publish(subject, data)` | Dual: sync iterable (threaded drain) or async iterable/coroutine (via `Runner`). Auto-detected at subscribe time. Optional `runner` kwarg. | TS uses native async iteration. PY auto-detects sync vs async subscriptions: sync uses threaded drain, async uses `resolve_runner().schedule()`. Both support queue groups. |\n| **`RabbitMQChannelLike` protocol** | amqplib shape: `consume(queue, callback)` returns `Promise<{consumerTag}>`, `cancel(tag)`, `ack(msg)`, `publish(exchange, routingKey, content)` | pika shape: `basic_consume(queue, on_message_callback, auto_ack)`, `start_consuming()`, `basic_ack(delivery_tag)`, `basic_publish(exchange, routing_key, body)` | Each port matches its ecosystem's dominant AMQP library. Pika requires `start_consuming()` to enter the event loop; amqplib's consume is promise-based. |\n| **`RabbitMQMessage` field naming** | camelCase: `routingKey`, `deliveryTag` | snake_case: `routing_key`, `delivery_tag` | Language convention applied to output data structures. |"}
 {"id": "deferred-follow-ups", "title": "Deferred follow-ups (QA)", "status": "deferred", "body": "## Deferred follow-ups (QA)\n\nNon-blocking items tracked for later; not optimizations per se. Keep this section **identical** in `graphrefly-ts/docs/optimizations.md` and here (aside from language-specific labels in the first table).\n\n| Item | Notes |\n|------|-------|\n| **`lastDepValues` + `is` / referential equality (resolved 2026-03-31 — keep + document)** | Default `is` identity check is correct for the common immutable-value case. The `node(equals=)` option already exists for custom comparison. Document clearly that mutable dep values should use a custom `equals` function. No code change needed. |\n| **`sideEffects: false` in `package.json`** | TypeScript package only. Safe while the library has no import-time side effects. Revisit if global registration or polyfills are added at module load. |\n| **JSDoc / docstrings on `node()` and public APIs** | `docs/docs-guidance.md`: JSDoc on new TS exports; docstrings on new Python public APIs. |\n| **Roadmap §0.3 checkboxes** | Mark Phase 0.3 items when the team agrees the milestone is complete. |"}
 {"id": "ai-deferred-optimizations", "title": "AI surface deferred optimizations", "status": "deferred", "body": "### AI surface (Phase 4.4) — deferred optimizations (QA 2026-03-31)\n\n| Item | Status | Notes |\n|------|--------|-------|\n| **Re-indexes entire store on every change** | Deferred | Decision: diff-based indexing using `Versioned` snapshot version field to track indexed entries. Deferred to after Phase 6 — current N is small enough that full re-index is acceptable pre-1.0. |\n| **Budget packing always includes first item** | Documented behavior | The retrieval budget packer always includes the first ranked result even if it exceeds `max_tokens`. This is intentional \"never return empty\" semantics — a query that matches at least one entry always returns something. Callers who need strict budget enforcement should post-filter. |\n| **Retrieval pipeline auto-wires when vectors/KG enabled** | Documented behavior | When `embed_fn` or `enable_knowledge_graph` is set, the retrieval pipeline automatically wires vector search and KG expansion into the retrieval derived node. There is no explicit opt-in/opt-out per retrieval stage — the presence of the capability implies its use. Callers who need selective retrieval should use the individual nodes directly. |"}
+{"id": "per-node-resource-tracking", "title": "Per-node resource tracking and subscriber audit", "status": "proposed", "body": "### Per-node resource tracking and subscriber audit (proposed)\n\nDiscovered during harnessLoop 9.0 debugging (TS): the #1 time sink was identifying orphan effects (subscriberCount=0 on terminal side-effects). A subscriber audit would have caught this instantly.\n\n**Lightweight (near-term):** `node.stats()` returning `{ activations, last_activated_at, subscriber_count, memory_estimate? }`. Activation count and subscriber count are trivially trackable. Memory estimate via rough serialization heuristic.\n\n**Rich (Phase 1 describe extension):** `graph.resource_profile()` walks all nodes, returns per-node stats + aggregate. This is the 'reactive DevTools' direction — aligns with inspection-as-test-harness philosophy.\n\n**Subscriber audit (highest ROI):** `graph.audit()` returning `{ orphan_effects: list[Node] }` — nodes with `_fn` (compute/effect) but `_sink_count == 0`. Would have saved most debugging time.\n\n**Memory concern:** TopicGraph instances hold reactive logs that grow unbounded. Long-running harness loops with hundreds of items accumulate. `resource_profile()` could surface this.\n\n**Proposed API surface:**\n- `node.stats() -> NodeStats` — per-node resource snapshot\n- `graph.audit() -> AuditResult` — orphan detection, unbounded log warnings\n- `graph.resource_profile() -> ResourceProfile` — aggregate memory + activation heatmap"}
 {"id": "tier2-deferred-semantics", "title": "Tier 2 deferred semantics", "status": "deferred", "body": "### Tier 2 extra operators (roadmap 2.2) — deferred semantics (QA)\n\nApplies to `src/extra/operators.ts` and `graphrefly.extra.tier2`. **Keep the table below identical in both repos’ `docs/optimizations.md`.**\n\n| Item | Status | Notes |\n|------|--------|-------|\n| **~~`sample` + `undefined` as `T`~~** | Resolved (2026-04-07) | Fixed in TS: `sample` now tracks source DATA via local `NO_VALUE` sentinel. Python had no ambiguity. |\n| **`mergeMap` / `merge_map` + `ERROR`** | Documented limitation (2026-03-31) | When the outer stream or one inner emits `ERROR`, other inner subscriptions may keep running until they complete or unsubscribe. Rx-style “first error cancels all sibling inners” is **not** specified or implemented. Current behavior (inner errors don’t cascade) is arguably more useful for parallel work — no change needed. Document in JSDoc/docstrings. |"}

{graphrefly-0.16.0 → graphrefly-0.18.0}/archive/optimizations/summary-table.jsonl

@@ -45,3 +45,5 @@
 {"id": "summary-45", "topic": "Extra Phase 3.1 (resilience)", "python": "`graphrefly.extra.{backoff,resilience,checkpoint}` + `core/timer.py` (`ResettableTimer`); see §6 below", "typescript": "`src/extra/{backoff,resilience,checkpoint}.ts` + `core/timer.ts` (`ResettableTimer`); see §6 below"}
 {"id": "summary-46", "topic": "Extra Phase 3.2 (data structures)", "python": "`graphrefly.extra.data_structures` (`reactive_map`, …); see §17", "typescript": "`reactiveMap` + `reactive-base` (`Versioned` snapshots); see §17"}
 {"id": "summary-47", "topic": "Core hook shape", "python": "`NodeImpl._set_inspector_hook()` installs an internal, opt-in hook with `dep_message` and `run` events.", "typescript": "`NodeImpl._setInspectorHook()` mirrors the same hook contract (`dep_message`, `run`)."}
+{"id": "summary-48", "topic": "Per-node resource tracking (proposed)", "python": "`node.stats()`, `graph.audit()`, `graph.resource_profile()` — proposed", "typescript": "`node.stats()`, `graph.audit()`, `graph.resourceProfile()` — proposed"}
+{"id": "summary-49", "topic": "Subscriber audit (proposed, highest ROI)", "python": "Detect orphan effects (`_sink_count == 0` on effect nodes)", "typescript": "Detect orphan effects (`_sinkCount === 0` on effect nodes)"}

{graphrefly-0.16.0 → graphrefly-0.18.0}/docs/optimizations.md

@@ -8,7 +8,7 @@
 
 - **PY `ReactiveMapBundle` parity — `.get(key)`, `.has(key)`, `.size` (noted 2026-04-07):**
   - **Level A: DONE (2026-04-07).** Added `.get(key)`, `.has(key)`, `.size` to PY `ReactiveMapBundle` matching TS signatures. PY harness `strategy.py` updated to use `.get(key)` instead of Versioned navigation.
-  - **Level B: Deferred (post-1.0).** `ReactiveMapBundle.node` (TS) / `.data` (PY) emits `Versioned<{ map: ReadonlyMap<K,V> }>` / `Versioned(version, MappingProxyType)`. The `Versioned` wrapper is a protocol optimization (efficient RESOLVED dedup via version comparison) that leaks into composition code when using the node as a derived dep. **Proposed fix:** `.node` / `.data` emits the unwrapped map directly; version-based equality handled internally via `equals` option on the state node. Consumers see `ReadonlyMap<K,V>` / `MappingProxyType`, not `Versioned`. Breaking change — defer to post-1.0 audit of all `Versioned` usage.
+  - **Level B: DONE (PY, 2026-04-07).** Removed `Versioned` wrapper from all reactive bundle APIs (ReactiveMap, ReactiveLog, ReactiveList, ReactiveIndex). `.data` / `.entries` / `.items` / `.ordered` now emit unwrapped domain types (`MappingProxyType`, `tuple`, etc.). Internal version counter drives efficient equality without leaking into composition code (spec §5.12). All downstream consumers updated (messaging, cqrs, ai, domain-templates, composite, harness/strategy).
 
 - **Whole-repo `emit` → `down` audit + `up` / backpressure / `message_tier` sweep (all phases, noted 2026-04-07):**
   - **TS: DONE (2026-04-07).** Renames: `emitWithBatch` → `downWithBatch`, `_emitToSinks` → `_downToSinks`, `_emitAutoValue` → `_downAutoValue`, `_boundEmitToSinks` → `_boundDownToSinks`, `_emitSequential` → `_downSequential`, `emitLine` → `flushLine` (reactive-layout). Batch param `emit` → `sink`. `up()` audit: no asymmetries. `messageTier()` audit: already clean. `NodeActions.emit()` kept (different semantics from `actions.down()`). CQRS `CommandActions.emit()` kept (domain concept). Spec updated (`_emitAutoValue` → `_downAutoValue`).
@@ -42,16 +42,22 @@ Non-blocking items tracked for later. **Keep this section identical in both repo
 
 | Item | Notes |
 |------|-------|
-| **`lastDepValues` + `Object.is` / referential equality (resolved 2026-03-31 — keep + document)** | Default `Object.is` identity check is correct for the common immutable-value case. The `node({ equals })` option already exists for custom comparison. Document clearly that mutable dep values should use a custom `equals` function. No code change needed. |
+| **`lastDepValues` + `Object.is` / referential equality (resolved 2026-03-31 — documented)** | Default identity check is correct for the common immutable-value case. The `node(equals=...)` option already exists for custom comparison. Mutable dep values should use a custom `equals` function. **Documented in `node()` docstring (2026-04-07).** |
 | **`sideEffects: false` in `package.json`** | TypeScript package only. Safe while the library has no import-time side effects. Revisit if global registration or polyfills are added at module load. |
-| **JSDoc / docstrings on `node()` and public APIs** | `docs/docs-guidance.md`: JSDoc on new TS exports; docstrings on new Python public APIs. |
+| **JSDoc / docstrings on `node()` and public APIs** | `docs/docs-guidance.md`: JSDoc on new TS exports; docstrings on new Python public APIs. `node()` equals guidance added (2026-04-07). `flat_map` ERROR behavior documented (2026-04-07). `from_redis_stream` COMPLETE/disconnect documented (2026-04-07). |
 | **Roadmap §0.3 checkboxes** | Mark Phase 0.3 items when the team agrees the milestone is complete. |
 
+### Factory teardown — `dispose()` pattern (D1/D2, noted 2026-04-07)
+
+| Item | Status | Notes |
+|------|--------|-------|
+| **Phase 4+ factories don't register internal nodes on the graph** | **DONE (TS + PY, 2026-04-07)** | Added `Graph.addDisposer(fn)` / `Graph.add_disposer(fn)` — general-purpose disposer registration drained on `destroy()` **before** TEARDOWN signal. TS: Fixed `harnessLoop`, `strategyModel`, `agentMemory`, `feedback`, `gate`, `contentModerationGraph`, `funnel` bridge, `ChatStreamGraph`, `ToolRegistryGraph`. PY: Fixed `harness_loop`, `reduction.py`, `ChatStreamGraph`, `ToolRegistryGraph`, `AgentMemoryGraph`. Dead `_version` counter removed from all reactive bundles (TS + PY). |
+
 ### AI surface (Phase 4.4) — deferred optimizations
 
 | Item | Status | Notes |
 |------|--------|-------|
-| **Re-indexes entire store on every change** | Deferred | Decision: diff-based indexing using `Versioned` snapshot version field to track indexed entries. Deferred to after Phase 6 — current N is small enough that full re-index is acceptable pre-1.0. |
+| **Re-indexes entire store on every change** | Deferred | Decision: diff-based indexing using internal version counter to track indexed entries. Deferred to after Phase 6 — current N is small enough that full re-index is acceptable pre-1.0. |
 | **Budget packing always includes first item** | Documented behavior | The retrieval budget packer always includes the first ranked result even if it exceeds `maxTokens`. This is intentional "never return empty" semantics — a query that matches at least one entry always returns something. Callers who need strict budget enforcement should post-filter. |
 | **Retrieval pipeline auto-wires when vectors/KG enabled** | Documented behavior | When `embedFn` or `enableKnowledgeGraph` is set, the retrieval pipeline automatically wires vector search and KG expansion into the retrieval derived node. There is no explicit opt-in/opt-out per retrieval stage — the presence of the capability implies its use. Callers who need selective retrieval should use the individual nodes directly. |
 
@@ -59,14 +65,14 @@ Non-blocking items tracked for later. **Keep this section identical in both repo
 
 | Item | Status | Notes |
 |------|--------|-------|
-| **`mergeMap` / `merge_map` + `ERROR`** | Documented limitation (2026-03-31) | When the outer stream or one inner emits `ERROR`, other inner subscriptions may keep running until they complete or unsubscribe. Rx-style "first error cancels all sibling inners" is **not** specified or implemented. Current behavior (inner errors don't cascade) is arguably more useful for parallel work — no change needed. Document in JSDoc/docstrings. |
+| **`mergeMap` / `merge_map` + `ERROR`** | **Documented (PY docstring, 2026-04-07)** | Inner errors propagate downstream but do not cancel sibling inners. Outer ERROR cancels all inners. Current behavior is intentional for parallel work. **Documented in `flat_map` docstring.** |
 
 ### Ingest adapters — deferred items
 
 | Item | Status | Notes |
 |------|--------|-------|
-| **`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()`). |
+| **`fromRedisStream` / `from_redis_stream` never emits COMPLETE** | **Documented (PY docstring, 2026-04-07)** | Long-lived stream consumers intentionally never complete. **Documented in `from_redis_stream` docstring.** |
+| **`fromRedisStream` / `from_redis_stream` does not disconnect client** | **Documented (PY docstring, 2026-04-07)** | The caller owns the Redis client lifecycle. **Documented in `from_redis_stream` docstring.** |
 | **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. |
 
 ### Intentional cross-language divergences

{graphrefly-0.16.0 → graphrefly-0.18.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "graphrefly"
-version = "0.16.0"
+version = "0.18.0"
 description = "Reactive harness layer for agent workflows. Describe automations in plain language, trace every decision, enforce policies, persist checkpoints. Zero dependencies."
 readme = "README.md"
 license = "MIT"

{graphrefly-0.16.0 → graphrefly-0.18.0}/src/graphrefly/core/__init__.py

@@ -26,7 +26,6 @@ from graphrefly.core.node import (
     NodeImpl,
     NodeStatus,
     SubscribeHints,
-    cleanup_result,
     node,
 )
 from graphrefly.core.protocol import (

{graphrefly-0.16.0 → graphrefly-0.18.0}/src/graphrefly/core/node.py

@@ -976,6 +976,14 @@ def node(
         **kwargs: Any option key accepted by :class:`NodeImpl` (e.g. ``name``,
             ``initial``, ``equals``, ``guard``, ``thread_safe``).
 
+    **Equality (``equals``):** The default ``equals`` uses identity (``is``)
+    for immutable values.  If your node produces *mutable* dep values
+    (dicts, lists) that are modified in place, provide a custom ``equals``
+    function — otherwise downstream nodes may skip updates because the
+    identity check sees the *same* object::
+
+        node([source], compute_fn, equals=lambda a, b: a == b)
+
     Returns:
         A new :class:`NodeImpl` instance.
 

{graphrefly-0.16.0 → graphrefly-0.18.0}/src/graphrefly/extra/__init__.py

@@ -110,7 +110,6 @@ from graphrefly.extra.data_structures import (
     ReactiveListBundle,
     ReactiveLogBundle,
     ReactiveMapBundle,
-    Versioned,
     log_slice,
     pubsub,
     reactive_index,
@@ -214,7 +213,6 @@ __all__ = [
     "ReactiveListBundle",
     "ReactiveLogBundle",
     "ReactiveMapBundle",
-    "Versioned",
     "NS_PER_MS",
     "NS_PER_SEC",
     "CacheTier",

{graphrefly-0.16.0 → graphrefly-0.18.0}/src/graphrefly/extra/adapters.py

@@ -1848,6 +1848,15 @@ def from_redis_stream(
 
     Uses XREAD with BLOCK to reactively consume stream entries.
 
+    **Lifecycle notes:**
+
+    - This source intentionally **never emits** ``COMPLETE``. Long-lived
+      stream consumers are expected to run indefinitely; completion would
+      tear down downstream operators prematurely.
+    - The caller **owns the Redis client lifecycle**. ``from_redis_stream``
+      does not close or disconnect the client on teardown — call
+      ``client.close()`` yourself when the graph is destroyed.
+
     Args:
         client: Redis client instance with ``xread`` method (caller owns connection).
         key: Redis stream key.

{graphrefly-0.16.0 → graphrefly-0.18.0}/src/graphrefly/extra/composite.py

@@ -113,11 +113,9 @@ class DistillBundle:
 
 
 def _snapshot_map(store: ReactiveMapBundle) -> Mapping[str, Any]:
-    snap = store.data.get()
+    snap = store.entries.get()
     if snap is None:
         return {}
-    if hasattr(snap, "value"):
-        return cast("Mapping[str, Any]", snap.value)
     return cast("Mapping[str, Any]", snap)
 
 
@@ -218,9 +216,9 @@ def distill(
         )
 
     compact = derived(
-        [store.data, context_node],
+        [store.entries, context_node],
         lambda deps, _a: _pack_compact(
-            deps[0].value if hasattr(deps[0], "value") else deps[0],
+            deps[0],
             deps[1],
             score,
             cost,
@@ -228,8 +226,8 @@ def distill(
         ),
     )
     size = derived(
-        [store.data],
-        lambda deps, _a: len(deps[0].value if hasattr(deps[0], "value") else deps[0]),
+        [store.entries],
+        lambda deps, _a: len(deps[0]) if deps[0] is not None else 0,
         initial=0,
     )
     compact.subscribe(lambda _msgs: None)
@@ -260,8 +258,9 @@ def _compute_evictions(
     evict: Callable[[str, Any], Any],
 ) -> list[str]:
     out: list[str] = []
-    current = get(store.data)
-    snapshot = current.value if hasattr(current, "value") else current
+    snapshot = get(store.entries)
+    if snapshot is None:
+        return out
     for key, mem in snapshot.items():
         verdict = evict(key, mem)
         if isinstance(verdict, Node):