graphrefly 0.18.0__tar.gz → 0.20.0__tar.gz

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

@@ -2,6 +2,56 @@
 
 <!-- version list -->
 
+## v0.20.0 (2026-04-11)
+
+### Chores
+
+- Add integrations page
+  ([`7f16d1b`](https://github.com/graphrefly/graphrefly-py/commit/7f16d1b9d9b5aadb5875e4bcb08e6decae469d1f))
+
+- Update docs
+  ([`0f2d779`](https://github.com/graphrefly/graphrefly-py/commit/0f2d779eeddcf9eec9ed339bcae4dbf6899363d3))
+
+### Features
+
+- Fix bug
+  ([`e5f9cc4`](https://github.com/graphrefly/graphrefly-py/commit/e5f9cc440a854cde0aac1060f02121b85ce06831))
+
+
+## v0.19.0 (2026-04-10)
+
+### Chores
+
+- 9.0 initial test (needs revisit)
+  ([`f47a8b4`](https://github.com/graphrefly/graphrefly-py/commit/f47a8b4d32e999d4f867465f678d576184fc111d))
+
+### Features
+
+- Add start
+  ([`4a008dc`](https://github.com/graphrefly/graphrefly-py/commit/4a008dcda7704e14be12a7111b1d0b9188c736b3))
+
+- Address optimization items
+  ([`371f9e2`](https://github.com/graphrefly/graphrefly-py/commit/371f9e25e590ded4150fd6aed7e0de3933b8f0f3))
+
+- Consolidate inspection tools
+  ([`94aa9af`](https://github.com/graphrefly/graphrefly-py/commit/94aa9af3e3d793103496bfcc71a0a4bbb38f5ea3))
+
+- Fix
+  ([`222e66f`](https://github.com/graphrefly/graphrefly-py/commit/222e66f4d8954aa772534c9fc796eea3ba30a304))
+
+- Fix async pytest
+  ([`f25ae08`](https://github.com/graphrefly/graphrefly-py/commit/f25ae0885fd824320b498fd2d923f6e4f6ebb0f5))
+
+- Fix inspection tool
+  ([`09c90f2`](https://github.com/graphrefly/graphrefly-py/commit/09c90f273613fbae1fd7987397d85d4b6fabec8d))
+
+- Fix retries and reingestions
+  ([`55d1a3d`](https://github.com/graphrefly/graphrefly-py/commit/55d1a3d0beff848a6ecefb054e42d194050d5c37))
+
+- Reusable harness patterns
+  ([`84bafbb`](https://github.com/graphrefly/graphrefly-py/commit/84bafbb8476c1d00ae373bbc757d4bf813ce16c8))
+
+
 ## v0.18.0 (2026-04-08)
 
 ### Features

graphrefly-0.20.0/CLAUDE.md

@@ -0,0 +1,61 @@
+# graphrefly-py
+
+Python implementation of the GraphReFly reactive graph protocol.
+
+**All operational docs (roadmap, optimizations, test guidance, docs guidance, skills, archive) live in `~/src/graphrefly-ts`.** See that repo's `CLAUDE.md` for the full agent context.
+
+## Commands
+
+uv workspace managed by mise. `mise trust && mise install` to set up uv. `uv sync` to install dependencies.
+
+- Test: `uv run pytest`
+- Lint: `uv run ruff check src/ tests/`
+- Lint fix: `uv run ruff check --fix src/ tests/`
+- Format: `uv run ruff format src/ tests/`
+- Type check: `uv run mypy src/`
+
+## Documentation workflow (critical)
+
+- Follow cross-language standard in `~/src/graphrefly-ts/docs/docs-guidance.md`.
+- `website/src/content/docs/api/*.md` pages are generated; do not hand-edit.
+- For docs updates in this repo:
+  1. Update source docstrings.
+  2. Run `pnpm --dir website docs:gen`.
+  3. Validate with `pnpm --dir website docs:gen:check` and `pnpm --dir website sync-docs:check`.
+- Keep `llms.txt` concise and source-oriented; avoid long static API inventories that drift.
+
+## Package naming
+
+- Distribution name: `graphrefly-py`
+- Import path: `graphrefly`
+
+## Layout
+
+- `src/graphrefly/core/` — message protocol, `node` primitive, batch, sugar constructors (Phase 0)
+- `src/graphrefly/graph/` — `Graph` container, describe/observe, snapshot (Phase 1+)
+- `src/graphrefly/extra/` — operators, sources, data structures, resilience (Phase 2–3)
+- `src/graphrefly/patterns/` — domain-layer APIs: orchestration, messaging, memory, AI, CQRS, reactive layout (Phase 4+)
+- `src/graphrefly/compat/` — async runners: asyncio, trio (Phase 5+)
+- `src/graphrefly/integrations/` — framework integrations: FastAPI (Phase 5+)
+
+## Key references
+
+| Doc | Location |
+|-----|----------|
+| Behavior spec | `~/src/graphrefly/GRAPHREFLY-SPEC.md` |
+| Composition guide | `~/src/graphrefly/COMPOSITION-GUIDE.md` |
+| Roadmap, optimizations, test/docs guidance, skills, archive | `~/src/graphrefly-ts/` (single source of truth) |
+| Reactive collaboration harness (§9.0) — 7-stage loop, gate, `promptNode`, strategy model | `~/src/graphrefly-ts/archive/docs/SESSION-reactive-collaboration-harness.md` |
+| Harness engineering strategy — 8 requirements, wave plan, MCP priority | `~/src/graphrefly-ts/archive/docs/SESSION-harness-engineering-strategy.md` |
+| Marketing & positioning — pillars, wave plan, reply playbooks, blog plan | `~/src/graphrefly-ts/archive/docs/SESSION-marketing-promotion-strategy.md` |
+| Predecessor (patterns, concurrency) | `~/src/callbag-recharge-py` (reference only, not spec) |
+
+## Design invariants (spec §5.8–5.12)
+
+1. **No polling.** Use reactive timer sources (`from_timer`, `from_cron`).
+2. **No imperative triggers.** Use reactive `NodeInput` signals.
+3. **No raw async primitives.** Async boundaries belong in sources and runners, not node fns.
+4. **Central timer and `message_tier`.** Use `core/clock.py`; never hardcode type checks.
+5. **Phase 4+ APIs must be developer-friendly.** No protocol internals in primary surface.
+6. **Thread safety.** Per-subgraph `RLock`, per-node `_cache_lock`. Design for GIL and free-threaded Python.
+7. **No `async def` in public APIs.** Return `Node[T]`, `Graph`, `None`, or plain synchronous values.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: graphrefly
-Version: 0.18.0
+Version: 0.20.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
@@ -25,15 +25,15 @@ Description-Content-Type: text/markdown
 
 # GraphReFly
 
-**Describe what matters. It watches, filters, and explains — persistently.**
+**The reactive harness layer for agent workflows.** Describe in plain language, review visually, run persistently, trace every decision.
 
-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.
+GraphReFly makes long-running human + LLM co-operation reactive, resumable, and causally explainable. State pushes downstream on change (no re-reading), nodes have lifecycles (not infinite append), and every decision has a traceable causal chain — the substrate underneath tools, agents, and personal automations.
 
 [![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)
 [![Python](https://img.shields.io/pypi/pyversions/graphrefly)](https://pypi.org/project/graphrefly/)
 
-[Docs](https://py.graphrefly.dev) | [Spec](https://py.graphrefly.dev/spec/) | [TypeScript](https://graphrefly.dev) | [API Reference](https://py.graphrefly.dev/api/)
+[Docs](https://graphrefly.dev/py/) | [Spec](https://graphrefly.dev/spec/) | [TypeScript](https://graphrefly.dev) | [Python API](https://graphrefly.dev/py/api/)
 
 ---
 
@@ -72,6 +72,23 @@ count.push(3)
 
 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.
 
+## Harness engineering coverage
+
+The eight requirements of a production agent harness cluster into a handful of composed blocks that sit on top of the reactive graph primitives:
+
+| Need | GraphReFly |
+|---|---|
+| Context & state | `persistent_state()` — `auto_checkpoint` + `snapshot` / `restore` + incremental diff |
+| Agent memory | `agent_memory()` — `distill` + vectors + knowledge graph + tiers, OpenViking decay |
+| Control flow & resilience | `resilient_pipeline()` — `rate_limiter → breaker → retry → timeout → fallback`, correct ordering built in |
+| Execution & policy | `guarded_execution()` — Actor / Guard ABAC + `policy()` + `budget_gate` + scoped describe |
+| Observability & causality | `graph_lens()` — reactive topology, health, flow, and `why(node)` causal chains as structured data |
+| Human governance | `gate` — reactive `pending` / `is_open` with `approve` / `reject` / `modify(fn, n)` |
+| Verification | Multi-model eval harness with regression gates |
+| Continuous improvement | Strategy model: `root_cause × intervention → success_rate` |
+
+The library computes structured facts reactively; LLMs and UIs render them. Natural language is never the library's job — which keeps the whole stack model-agnostic and testable.
+
 ## Why GraphReFly?
 
 |  | Redux / Zustand | RxPY | Pydantic AI | LangGraph | TC39 Signals | **GraphReFly** |

{graphrefly-0.18.0 → graphrefly-0.20.0}/README.md

@@ -1,14 +1,14 @@
 # GraphReFly
 
-**Describe what matters. It watches, filters, and explains — persistently.**
+**The reactive harness layer for agent workflows.** Describe in plain language, review visually, run persistently, trace every decision.
 
-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.
+GraphReFly makes long-running human + LLM co-operation reactive, resumable, and causally explainable. State pushes downstream on change (no re-reading), nodes have lifecycles (not infinite append), and every decision has a traceable causal chain — the substrate underneath tools, agents, and personal automations.
 
 [![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)
 [![Python](https://img.shields.io/pypi/pyversions/graphrefly)](https://pypi.org/project/graphrefly/)
 
-[Docs](https://py.graphrefly.dev) | [Spec](https://py.graphrefly.dev/spec/) | [TypeScript](https://graphrefly.dev) | [API Reference](https://py.graphrefly.dev/api/)
+[Docs](https://graphrefly.dev/py/) | [Spec](https://graphrefly.dev/spec/) | [TypeScript](https://graphrefly.dev) | [Python API](https://graphrefly.dev/py/api/)
 
 ---
 
@@ -47,6 +47,23 @@ count.push(3)
 
 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.
 
+## Harness engineering coverage
+
+The eight requirements of a production agent harness cluster into a handful of composed blocks that sit on top of the reactive graph primitives:
+
+| Need | GraphReFly |
+|---|---|
+| Context & state | `persistent_state()` — `auto_checkpoint` + `snapshot` / `restore` + incremental diff |
+| Agent memory | `agent_memory()` — `distill` + vectors + knowledge graph + tiers, OpenViking decay |
+| Control flow & resilience | `resilient_pipeline()` — `rate_limiter → breaker → retry → timeout → fallback`, correct ordering built in |
+| Execution & policy | `guarded_execution()` — Actor / Guard ABAC + `policy()` + `budget_gate` + scoped describe |
+| Observability & causality | `graph_lens()` — reactive topology, health, flow, and `why(node)` causal chains as structured data |
+| Human governance | `gate` — reactive `pending` / `is_open` with `approve` / `reject` / `modify(fn, n)` |
+| Verification | Multi-model eval harness with regression gates |
+| Continuous improvement | Strategy model: `root_cause × intervention → success_rate` |
+
+The library computes structured facts reactively; LLMs and UIs render them. Natural language is never the library's job — which keeps the whole stack model-agnostic and testable.
+
 ## Why GraphReFly?
 
 |  | Redux / Zustand | RxPY | Pydantic AI | LangGraph | TC39 Signals | **GraphReFly** |

graphrefly-0.20.0/llms.txt

@@ -0,0 +1,114 @@
+# GraphReFly — Python package (`graphrefly`)
+
+The reactive harness layer for agent workflows. Reactive graph runtime for human + LLM co-operation — causal tracing, persistent checkpoints, policy enforcement, zero runtime dependencies.
+
+Keywords: harness engineering, agent harness, reactive graph, causal trace, explain_path, agent orchestration, LLM co-operation, human-in-the-loop, reactive middleware, universal reduction layer.
+
+This file is an AI-oriented index for the Python repo. It points to source-of-truth docs and generated API references instead of maintaining a long, drift-prone inline API catalog.
+
+## Canonical behavior and docs authority
+
+- Behavior spec: `~/src/graphrefly/GRAPHREFLY-SPEC.md`
+- Composition guidance: `~/src/graphrefly/COMPOSITION-GUIDE.md`
+- Docs conventions (cross-language): `~/src/graphrefly-ts/docs/docs-guidance.md`
+- Roadmap/state (cross-language): `~/src/graphrefly-ts/docs/roadmap.md`
+- Testing standard (cross-language): `~/src/graphrefly-ts/docs/test-guidance.md`
+
+## Active strategy docs (cross-language, live in graphrefly-ts)
+
+- `~/src/graphrefly-ts/archive/docs/SESSION-reactive-collaboration-harness.md` — 7-stage reactive collaboration loop, gate port, `prompt_node`, `valve` rename, strategy model, `harness_loop()` factory
+- `~/src/graphrefly-ts/archive/docs/SESSION-harness-engineering-strategy.md` — 8-requirement coverage, three-wave announcement plan, MCP Server priority, eval system design
+- `~/src/graphrefly-ts/archive/docs/SESSION-marketing-promotion-strategy.md` — positioning pillars, wave plan, reply-marketing playbooks, competitive intel, prompt optimization algorithms, blog content plan
+
+## Primary links
+
+- Python docs: https://graphrefly.dev/py/
+- Python API reference: https://graphrefly.dev/py/api/
+- TypeScript docs: https://graphrefly.dev
+
+## Package entry points
+
+- Root: `from graphrefly import ...`
+- Subpackages: `graphrefly.core`, `graphrefly.graph`, `graphrefly.extra`, `graphrefly.patterns`, `graphrefly.compat`, `graphrefly.integrations`
+
+## Public API by subpackage
+
+Full export lists live in the generated API pages under `website/src/content/docs/api/`. The descriptions below explain *what lives in each subpackage and why*, so an LLM reading this cold can navigate without consuming the drift-prone catalog. Python uses snake_case (`from_timer`, `switch_map`, `agent_loop`) — the behavior parity with TypeScript holds, the naming does not.
+
+### `graphrefly.core` — `src/graphrefly/core/`
+
+The minimal reactive substrate. One primitive (`node`) plus sugar constructors (`state`, `derived`, `producer`, `effect`, `pipe`, `dynamic_node`). Protocol internals: `MessageType` enum (`DATA`, `DIRTY`, `RESOLVED`, `COMPLETE`, `ERROR`, `TEARDOWN`, `INVALIDATE`, `PAUSE`, `RESUME`), dispatch (`dispatch_messages`, `is_phase2_message`), two-phase batch semantics (`batch`, `is_batching`, `partition_for_batch`, `down_with_batch`), guard / policy (`policy`, `policy_from_rules`, `compose_guards`, `GuardDenied`, `access_hint_for_guard`), actor identity (`Actor`, `system_actor`, `normalize_actor`), meta snapshots (`meta_snapshot`, `describe_node`), versioning (`create_versioning`, `advance_version`, `default_hash`, `is_v1`), and the central clock (`monotonic_ns`, `wall_clock_ns`). **Anything outside this package must not call `time.time_ns()` / `time.monotonic_ns()` directly — use `src/graphrefly/core/clock.py`.** Also holds the `Runner` protocol and default-runner resolution (`get_default_runner`, `set_default_runner`, `resolve_runner`) for asyncio/trio backends. Thread-safety invariants (per-subgraph `RLock`, per-node `_cache_lock`) are enforced here.
+
+### `graphrefly.graph` — `src/graphrefly/graph/`
+
+The `Graph` container: reactive node registry with `register` / `resolve` / `describe` / `observe` / `snapshot` / `diff` / `diagram` / `spy` / `mount` / `unmount` / `teardown`. `reachable(graph, start_path, options=None)` computes the dependency closure from a node path — foundation for `explain_path` (causal walkback) and persistence scope.
+
+### `graphrefly.extra` — `src/graphrefly/extra/`
+
+Everything reactive that isn't the primitive. Organized into focused modules:
+
+- **Tier 1 operators** (`tier1.py`) — transform (`map`, `filter`, `scan`, `reduce`), limiting (`take`, `skip`, `take_while`, `take_until`), selection (`first`, `last`, `find`, `element_at`), utility (`start_with`, `tap`, `distinct_until_changed`, `pairwise`), combination (`combine`, `with_latest_from`), merging (`merge`, `zip`, `concat`, `race`).
+- **Tier 2 operators** (`tier2.py`) — higher-order (`switch_map`, `concat_map`, `flat_map`, `exhaust_map`), timing (`debounce`, `throttle`, `delay`), sampling (`sample`, `audit`, `timeout`), buffering (`buffer`, `buffer_count`, `buffer_time`), windowing (`window`, `window_count`, `window_time`), `interval`, `repeat`, `pausable`, `rescue`. **Note:** the existing `gate(control)` here is a boolean control gate and is being renamed to `valve` per §9.0; the new human-approval `gate` lives under `patterns.orchestration`.
+- **Sources** (`sources.py`) — synchronous (`of`, `empty`, `never`, `throw_error`, `from_iter`, `from_timer`, `from_cron`), async bridges (`from_awaitable`, `from_async_iter`), network / IO (`from_http`, `from_event_emitter`, `from_fs_watch`, `from_webhook`, `from_websocket`, `from_mcp`, `from_git_hook`), multicast / caching (`share`, `cached`, `replay`), collectors (`for_each`, `to_list`, `to_array`, `first_value_from`), sinks (`to_sse`, `to_websocket`). **All async boundaries must enter through sources** — node fns and operators never contain `async def` or raw awaitables.
+- **Data structures** (`data_structures.py` + dedicated files) — `reactive_map`, `reactive_log` + `log_slice`, `reactive_index`, `reactive_list`, `pubsub`.
+- **Resilience** (`resilience.py` + `backoff.py`) — `retry`, `circuit_breaker` + `CircuitOpenError`, `token_bucket`, `token_tracker`, `rate_limiter`, `with_breaker`, `with_status`; backoff strategies (`constant`, `linear`, `exponential`, `fibonacci`, `decorrelated_jitter`, `with_max_attempts`, `resolve_backoff_preset`).
+- **Cron** (`cron.py`) — `parse_cron`, `matches_cron`.
+- **Checkpoint** (`checkpoint.py`) — `Memory` / `Dict` / `File` / `Sqlite` adapters, `save_graph_checkpoint` / `restore_graph_checkpoint`, `checkpoint_node_value`. Auto-checkpoint is gated by `message_tier >= 3`. See `docs/ADAPTER-CONTRACT.md` for the adapter contract.
+- **Composite** (`composite.py`) — `verifiable(source, opts)` wraps a node with verification tracking; `distill(raw, extract, opts)` compacts raw data into a budget-bounded summary (the reactive memory primitive that `agent_memory` plugs into).
+- **Backpressure** (`backpressure.py`) — watermark controller for PAUSE/RESUME flow control.
+
+### `graphrefly.patterns` — `src/graphrefly/patterns/` (Phase 4+ domain APIs)
+
+Developer-facing factories that compose primitives into recognizable patterns. **Protocol internals never surface here** — sensible defaults, minimal boilerplate, clear errors. Python uses `with batch():` context managers instead of TypeScript's callback form, and `Node.__or__` maps to the TS `pipe()`.
+
+- **Orchestration** (`orchestration.py`) — `pipeline`, `task`, `branch`, the boolean control `gate` *(being renamed to `valve`)*, `approval`, `for_each`, `join`, `loop`, `sub_pipeline`, `sensor`, `wait`, `on_failure`. The §9.0 port of the human-approval gate (`pending` / `count` / `is_open` reactive nodes and `approve` / `reject` / `modify(fn, n=1)` / `open` / `close` methods) also lands here.
+- **Messaging** (`messaging.py`) — `topic` (TopicGraph), `subscription` (SubscriptionGraph with cursor / `pull` / `ack`), `job_queue`, `job_flow`, `topic_bridge`. These are the primitives the §9.0 harness loop uses for static-topology sinks and cursor-driven readers.
+- **Memory** (`memory.py`) — `collection`, `light_collection`, `vector_index`, `knowledge_graph`, `decay(source, opts)` (OpenViking exponential decay, 7-day default half-life). `decay` is the priority-scoring primitive for the §9.0 QUEUE stage.
+- **AI** (`ai.py`) — `from_llm`, `streaming_prompt_node`, `stream_extractor`, `chat_stream`, `tool_registry`, `system_prompt_builder`, `llm_extractor`, `llm_consolidator`, `agent_memory` (default: distill + vectors + KG + tiers), `agent_loop` (ReAct inner loop), `knobs_as_tools`, `gauges_as_context`, `validate_graph_def`. The §9.0 `prompt_node` factory (wraps any LLM call in a derived node with retry / cache / structured output) also lives here and is what plugs into `distill` as `extract_fn` / `consolidate_fn`.
+- **CQRS** (`cqrs.py`) — `cqrs(name, opts=None)` creates a commands / events / projections / sagas Graph.
+- **Reactive layout** (`reactive_layout/`) — `reactive_layout`, `reactive_block_layout`, `analyze_and_measure`, `compute_line_breaks`, `compute_char_positions`. DOM-free Knuth-Plass line breaking as a `state → derived` graph.
+
+### `graphrefly.compat` — `src/graphrefly/compat/`
+
+Async runner bindings. `AsyncioRunner` wraps a Graph in an asyncio event loop; `TrioRunner` does the same for trio. These are the only places allowed to orchestrate coroutines — node fns and operators stay synchronous. Runners resolve via `graphrefly.core.resolve_runner` so downstream code can inject a specific backend.
+
+### `graphrefly.integrations` — `src/graphrefly/integrations/`
+
+Framework integrations. `fastapi.GraphReflyRouter(graph)` exposes `GET /describe`, `GET /snapshot`, `WS /observe` over a registered `Graph`. Keep these thin — all logic belongs in `core` / `extra` / `patterns`.
+
+### Design docs that back the above
+
+- Phase 4+ factory authors must read `~/src/graphrefly/COMPOSITION-GUIDE.md` before composing primitives — covers lazy activation, subscription ordering, null guards, feedback cycles, `prompt_node` SENTINEL, wiring order.
+- Backlog / anti-patterns / deferred follow-ups: `~/src/graphrefly-ts/docs/optimizations.md` (cross-language).
+- Historical design decisions and parity notes: `~/src/graphrefly-ts/archive/optimizations/` (cross-language).
+
+## Generated docs workflow
+
+Python API pages are generated from docstrings:
+
+- Generator: `website/scripts/gen_api_docs.py`
+- Output: `website/src/content/docs/api/*.md`
+- Commands:
+  - `pnpm --dir website docs:gen`
+  - `pnpm --dir website docs:gen:check`
+  - `pnpm --dir website sync-docs`
+  - `pnpm --dir website sync-docs:check`
+
+Do not hand-edit generated API pages.
+
+## Core design invariants
+
+- No polling; propagation is reactive.
+- No imperative triggers outside graph/message flow.
+- No raw async primitives inside reactive layer logic.
+- Use `src/graphrefly/core/clock.py` and `message_tier` helpers for timing/tier semantics.
+- Keep Phase 4+ surfaces developer-oriented (hide protocol internals from primary API docs).
+- Thread safety: per-subgraph `RLock`, per-node `_cache_lock`; no `async def` / `Awaitable` in public APIs.
+
+## Harness engineering coverage
+
+GraphReFly covers the 8 requirements of a production agent harness — context/state control, execution boundary, control flow, verification, observability, policy/safety, human governance, continuous improvement. Mapping lives in `README.md` and `~/src/graphrefly-ts/archive/docs/SESSION-harness-engineering-strategy.md`.
+
+## Reactive collaboration loop (§9.0)
+
+`harness_loop()` wires a static topology: INTAKE → TRIAGE → QUEUE → GATE → EXECUTE → VERIFY → REFLECT. Static topology + flowing data (the Kafka insight). Humans steer via `gate.modify(fn, n)`. Strategy model (`root_cause × intervention → success_rate`) feeds TRIAGE routing. Design source: `~/src/graphrefly-ts/archive/docs/SESSION-reactive-collaboration-harness.md`.

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

@@ -1,6 +1,6 @@
 [project]
 name = "graphrefly"
-version = "0.18.0"
+version = "0.20.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"
@@ -90,6 +90,7 @@ quote-style = "double"
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
+pythonpath = ["tests"]
 asyncio_mode = "auto"
 addopts = "-m 'not benchmark'"
 markers = [

{graphrefly-0.18.0 → graphrefly-0.20.0}/src/graphrefly/__init__.py

@@ -37,7 +37,6 @@ from graphrefly.core import (
     defer_down,
     defer_set,
     derived,
-    describe_node,
     dispatch_messages,
     down_with_batch,
     dynamic_node,
@@ -47,7 +46,6 @@ from graphrefly.core import (
     is_batching,
     is_phase2_message,
     is_v1,
-    meta_snapshot,
     monotonic_ns,
     node,
     normalize_actor,
@@ -74,7 +72,6 @@ from graphrefly.graph import (
     GraphDiffResult,
     GraphObserveSource,
     ObserveResult,
-    SpyHandle,
     TraceEntry,
     reachable,
 )
@@ -93,7 +90,6 @@ __all__ = [
     "NodeVersionInfo",
     "ObserveResult",
     "PATH_SEP",
-    "SpyHandle",
     "TraceEntry",
     "V0",
     "V1",
@@ -138,13 +134,11 @@ __all__ = [
     "compose_guards",
     "defer_down",
     "defer_set",
-    "describe_node",
     "dispatch_messages",
     "down_with_batch",
     "ensure_registered",
     "is_batching",
     "is_phase2_message",
-    "meta_snapshot",
     "node",
     "normalize_actor",
     "partition_for_batch",

{graphrefly-0.18.0 → graphrefly-0.20.0}/src/graphrefly/compat/async_utils.py

@@ -11,6 +11,7 @@ import asyncio
 import contextlib
 from typing import TYPE_CHECKING, Any
 
+from graphrefly.core.node import NO_VALUE
 from graphrefly.core.protocol import MessageType
 
 if TYPE_CHECKING:
@@ -101,13 +102,11 @@ async def first_value_from_async(source: Node[Any]) -> Any:
         assert value == 42
     """
     # Fast path: already settled with a cached value.
-    # ``source.get()`` returns ``None`` when no value is cached, so
-    # ``is not None`` doubles as the "has value" sentinel while still
-    # returning falsy values like ``0``, ``False``, ``""``.
+    # Uses NO_VALUE sentinel so ``None`` as a real domain value is not skipped.
     status = source.status
     if status in ("settled", "resolved"):
-        v = source.get()
-        if v is not None:
+        v = getattr(source, "_cached", NO_VALUE)
+        if v is not NO_VALUE:
             return v
 
     loop = asyncio.get_running_loop()
@@ -163,12 +162,11 @@ async def settled(source: Node[Any]) -> Any:
         value = await settled(b)
         assert value == 20
     """
-    # Fast path: already settled (see ``first_value_from_async`` for the
-    # ``is not None`` rationale).
+    # Fast path: already settled — uses NO_VALUE sentinel so ``None`` is not skipped.
     status = source.status
     if status in ("settled", "resolved"):
-        v = source.get()
-        if v is not None:
+        v = getattr(source, "_cached", NO_VALUE)
+        if v is not NO_VALUE:
             return v
 
     loop = asyncio.get_running_loop()

{graphrefly-0.18.0 → graphrefly-0.20.0}/src/graphrefly/compat/asyncio_runner.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import asyncio
+import threading
 from typing import TYPE_CHECKING, Any
 
 if TYPE_CHECKING:
@@ -29,10 +30,12 @@ class AsyncioRunner:
         asyncio.run(main())
     """
 
-    __slots__ = ("_loop",)
+    __slots__ = ("_loop", "_scheduled", "_completed")
 
     def __init__(self, loop: asyncio.AbstractEventLoop) -> None:
         self._loop = loop
+        self._scheduled = 0
+        self._completed = 0
 
     @classmethod
     def from_running(cls) -> AsyncioRunner:
@@ -50,11 +53,12 @@ class AsyncioRunner:
         on_error: Callable[[BaseException], None],
     ) -> Callable[[], None]:
         task: asyncio.Task[Any] | None = None
-        cancelled = False
+        cancelled = threading.Event()
 
         def _create_task() -> None:
             nonlocal task
-            if cancelled:
+            if cancelled.is_set():
+                self._completed += 1
                 coro.close()
                 return
 
@@ -71,19 +75,42 @@ class AsyncioRunner:
                     on_error(err)
                 else:
                     on_result(result)
+                finally:
+                    self._completed += 1
 
             task = self._loop.create_task(_wrapper())
 
-        # Thread-safe: schedule task creation on the event loop.
-        self._loop.call_soon_threadsafe(_create_task)
+        # Increment eagerly on the calling thread so __repr__ is always consistent.
+        self._scheduled += 1
+        try:
+            self._loop.call_soon_threadsafe(_create_task)
+        except RuntimeError:
+            # Loop closed — cannot schedule; close the coroutine and balance the counter.
+            self._completed += 1
+            coro.close()
 
         def cancel() -> None:
-            nonlocal cancelled
-            cancelled = True
+            cancelled.set()
             if task is not None:
                 task.cancel()
 
         return cancel
 
+    def would_block_deadlock(self) -> bool:
+        """True if blocking the current thread would starve this runner's loop."""
+        try:
+            loop = asyncio.get_running_loop()
+        except RuntimeError:
+            return False
+        return loop is self._loop
+
+    def __repr__(self) -> str:
+        pending = self._scheduled - self._completed
+        running = self._loop.is_running()
+        return (
+            f"AsyncioRunner(scheduled={self._scheduled}, completed={self._completed}, "
+            f"pending={pending}, loop_running={running})"
+        )
+
 
 __all__ = ["AsyncioRunner"]

{graphrefly-0.18.0 → graphrefly-0.20.0}/src/graphrefly/compat/trio_runner.py

@@ -8,6 +8,7 @@ Usage::
     from graphrefly.compat.trio_runner import TrioRunner
     from graphrefly.core.runner import set_default_runner
 
+
     async def main():
         async with trio.open_nursery() as nursery:
             runner = TrioRunner(nursery)
@@ -19,6 +20,7 @@ Usage::
 
 from __future__ import annotations
 
+import threading
 from typing import TYPE_CHECKING, Any
 
 if TYPE_CHECKING:
@@ -34,10 +36,12 @@ class TrioRunner:
     Cancel scopes provide best-effort cancellation.
     """
 
-    __slots__ = ("_nursery",)
+    __slots__ = ("_nursery", "_scheduled", "_completed")
 
     def __init__(self, nursery: trio.Nursery) -> None:
         self._nursery = nursery
+        self._scheduled = 0
+        self._completed = 0
 
     def schedule(
         self,
@@ -48,11 +52,12 @@ class TrioRunner:
         import trio as _trio
 
         cancel_scope = _trio.CancelScope()
-        cancelled = False
+        cancelled = threading.Event()
 
         async def _wrapper() -> None:
             with cancel_scope:
-                if cancelled:
+                if cancelled.is_set():
+                    self._completed += 1
                     coro.close()
                     return
                 try:
@@ -67,15 +72,34 @@ class TrioRunner:
                     on_error(err)
                 else:
                     on_result(result)
+                finally:
+                    self._completed += 1
 
+        self._scheduled += 1
         self._nursery.start_soon(_wrapper)
 
         def cancel() -> None:
-            nonlocal cancelled
-            cancelled = True
+            cancelled.set()
             cancel_scope.cancel()
 
         return cancel
 
+    def would_block_deadlock(self) -> bool:
+        """True if blocking the current thread would starve the trio nursery."""
+        try:
+            import trio as _trio
+
+            _trio.lowlevel.current_trio_token()
+            return True
+        except RuntimeError:
+            return False
+
+    def __repr__(self) -> str:
+        pending = self._scheduled - self._completed
+        return (
+            f"TrioRunner(scheduled={self._scheduled}, completed={self._completed}, "
+            f"pending={pending})"
+        )
+
 
 __all__ = ["TrioRunner"]

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

@@ -17,7 +17,6 @@ from graphrefly.core.guard import (
     record_mutation,
     system_actor,
 )
-from graphrefly.core.meta import describe_node, meta_snapshot
 from graphrefly.core.node import (
     NO_VALUE,
     Node,
@@ -112,7 +111,6 @@ __all__ = [
     "compose_guards",
     "defer_down",
     "defer_set",
-    "describe_node",
     "dispatch_messages",
     "down_with_batch",
     "ensure_registered",
@@ -121,7 +119,6 @@ __all__ = [
     "is_terminal_message",
     "message_tier",
     "propagates_to_meta",
-    "meta_snapshot",
     "node",
     "normalize_actor",
     "partition_for_batch",