graphrefly 0.8.0__tar.gz → 0.9.0__tar.gz

{graphrefly-0.8.0 → graphrefly-0.9.0}/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 <!-- version list -->
 
+## v0.9.0 (2026-04-06)
+
+### Features
+
+- 8.3
+  ([`39b0a9e`](https://github.com/graphrefly/graphrefly-py/commit/39b0a9e8e2a034a27352b2ea054182d58065903f))
+
+
 ## v0.8.0 (2026-04-06)
 
 ### Features

{graphrefly-0.8.0 → graphrefly-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: graphrefly
-Version: 0.8.0
+Version: 0.9.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

{graphrefly-0.8.0 → graphrefly-0.9.0}/docs/optimizations.md

@@ -139,6 +139,9 @@ Union-find over node identity merges components when nodes list dependencies at
 - **~~`to_json()` → `to_dict()` + `to_json_string()` (Phase 1.4, noted 2026-04-05, resolved 2026-04-05):~~** PY: `to_json()` renamed to `to_json_string()`; `to_dict()` added as alias of `snapshot()`; `to_json` alias removed (pre-1.0, no backward compat needed). TS: `toJSON()` renamed to `toObject()`; `toJSON()` kept as ECMAScript hook. Spec §3.8 updated.
 - **~~Initial value, cached state, and equals interaction (all phases, noted 2026-04-05, resolved 2026-04-05):~~** Resolved with `_SENTINEL` / `NO_VALUE` sentinel (TS: `Symbol.for("graphrefly/NO_VALUE")`, PY: `_SENTINEL = object()`). Replaces the `_has_emitted_data` boolean flag entirely. One field (`_cached`) instead of two — impossible to desync. Key semantics: (1) When `initial` option is present (even as `None`), `_cached = initial` — `equals` IS called on first emission. (2) When `initial` is absent, `_cached = _SENTINEL` — first emission always DATA. (3) INVALIDATE / `reset_on_teardown` set `_cached = _SENTINEL`. (4) Resubscribable: terminal reset now also sets `_cached = _SENTINEL` — new subscriber always gets DATA. (5) Reconnect: cache retained → same-value emits RESOLVED — correct. (6) `get()` returns `None` when `_cached is _SENTINEL`. Spec §2.5 updated.
 - **Auto-edge registration is local-only (Phase 1.1, noted 2026-04-05):** `Graph.add()` auto-registers edges for deps within the same `Graph` instance only. Cross-subgraph deps still require explicit `connect()`. Consistent with spec: cross-subgraph edges are explicit wiring.
+- **GraphSpec cross-language parity (Phase 8.3, noted 2026-04-06, QA 2026-04-06):** Both TS and PY implement `compileSpec`/`compile_spec`, `decompileGraph`/`decompile_graph`, `llmCompose`/`llm_compose`, `llmRefine`/`llm_refine`, `specDiff`/`spec_diff`, and `validateSpec`/`validate_spec` in `patterns/graphspec`. Key alignment: (1) `GraphSpec` schema is identical JSON shape — `nodes`, `templates`, `feedback` top-level keys. TS uses TypeScript types; PY uses TypedDict. (2) `compile_spec` resolves nodes in dependency order (state/producer first, then derived/effect/operator). Catalog is passed explicitly (`GraphSpecCatalog`) — no global registry. (3) Template instantiation creates mounted subgraphs via `graph.mount()`. `$param` bindings resolve to top-level nodes. (4) Feedback edges wire via §8.1 `feedback()` primitive. (5) `decompile_graph` uses `describe(detail="standard")`, skips `__meta__` and `__feedback_*` internal nodes. Template detection via meta-based recovery (primary) + structural fingerprinting (fallback; includes dep names for accuracy). (6) `spec_diff` is pure JSON comparison — template-aware, feedback-aware. (7) LLM APIs (`llm_compose`/`llm_refine`) share identical system prompt and validation pipeline. (8) `validate_spec` checks bind targets exist in outer nodes, rejects feedback self-cycles, validates template param completeness. QA fixes: idempotent unsub in feedback(), deterministic output node selection in decompile, `contextlib.suppress` for connect dedup. Both repos: 35 tests each.
+- **Feedback bare DATA to reentry/counter — deferred to 8.2 (Phase 8.1, noted 2026-04-06, decided 2026-04-06):** Both TS and PY `feedback()` send bare `[DATA]` to `reentry` and `counter` nodes without a preceding `DIRTY`. This is a deliberate protocol shortcut: the feedback subscriber operates outside the normal two-phase push because it is a subscribe-based bridge (not a node). Acceptable because feedback reentry targets are always state nodes (which re-derive DIRTY internally via `down()`). Will be resolved when feedback is rearchitected as a graph-visible bridge node in 8.2 — at that point the bridge node participates in two-phase push naturally.
+- **`llm_compose`/`llm_refine` sync (PY) vs async (TS) — intentional divergence (Phase 8.3, noted 2026-04-06):** PY: synchronous, adapter must return `LLMResponse` directly. TS: `async function` returning `Promise<GraphSpec>`. PY design invariant: no `async def` / `Awaitable` in public APIs. TS spec §5.10 allows `await` at system boundaries (LLM adapter is external I/O, not reactive scheduling). Both are correct for their language idiom. Adapter contracts differ: PY adapters must be sync; TS adapters return Promise-compatible values.
 - **Reduction primitives cross-language parity (Phase 8.1, noted 2026-04-06, QA 2026-04-06):** Both TS and PY implement `stratify`, `funnel`, `feedback`, `budget_gate`/`budgetGate`, and `scorer` in `patterns/reduction`. All five follow the orchestration factory pattern (`_base_meta`, `_register_step`). Key alignment: (1) `stratify` buffers DIRTY until DATA arrives — on classifier miss, emits `[DIRTY, RESOLVED]` to preserve spec §1.3.1 (both). (2) `funnel` bridges stages via `subscribe` forwarding DIRTY/DATA/RESOLVED/COMPLETE/ERROR to preserve two-phase protocol. TODO(8.2): replace with graph-visible bridge nodes. (3) `feedback` counter node is source of truth (resettable via `graph.set()`); uses `continue` (not `return`) on max_iterations so remaining batch messages process. Counter name is `__feedback_<condition>` to support multiple loops per graph. (4) `budget_gate`/`budgetGate` force-flushes all buffered items on terminal regardless of budget; sends RESUME before terminal if paused; forwards constraint ERROR downstream, silences constraint COMPLETE, forwards unknown constraint types via default. (5) `scorer` coerces `None`/`undefined` to 0 before multiplication (no TypeError/NaN divergence). TS `ScoredItem` is a plain object; PY `ScoredItem` is a class with `__slots__` and `__eq__`. Meta keys: `reduction: True`, `reduction_type: "<name>"`. Both repos: 22 tests each.
 
 ---

{graphrefly-0.8.0 → graphrefly-0.9.0}/docs/roadmap.md

@@ -501,15 +501,19 @@ Pre-wired graphs for common "info → action" domains. Users fork/extend.
 - [ ] `issue_tracker_graph(opts)` → Graph — findings → extraction → verifiable assertions → regression detection → distillation → prioritized queue
 - [ ] `content_moderation_graph(opts)` → Graph — ingest → LLM classification → human review → feedback → policy refinement
 - [ ] `data_quality_graph(opts)` → Graph — DB/API ingest → schema validation → anomaly detection → drift alerting → remediation suggestions
+- [ ] Rearchitect `feedback()` as graph-visible bridge node (replaces subscribe-based shortcut; enables proper DIRTY→DATA two-phase on reentry/counter; resolves bare-DATA protocol gap)
+- [ ] Rearchitect `funnel()` bridges as graph-visible nodes (replaces subscribe forwarding; resolves §5.9 imperative trigger violation + teardown leak)
+- [ ] `stratify` two-dep gating: gate classification on both source and rules settling (eliminates stale-rules race when both updated in same `batch()`)
 
 ### 8.3 — LLM graph composition
 
-- [ ] `GraphSpec` schema — JSON schema for declarative graph topology. Serializable, diffable.
-- [ ] `compile_spec(spec)` → Graph — instantiate from spec
-- [ ] `decompile_graph(graph)` → GraphSpec — extract spec from running graph
-- [ ] `llm_compose(problem, adapter, opts)` → GraphSpec — LLM generates topology from natural language
-- [ ] `llm_refine(graph, feedback, adapter)` → GraphSpec — LLM modifies existing topology
-- [ ] `spec_diff(spec_a, spec_b)` — structural diff between specs
+- [x] `GraphSpec` schema — JSON schema for declarative graph topology. Serializable, diffable.
+- [x] `compile_spec(spec, catalog)` → Graph — instantiate from spec (dep-order resolution, templates via `mount()`, feedback via §8.1)
+- [x] `decompile_graph(graph)` → GraphSpec — extract spec from running graph (meta-based + structural fingerprint template detection)
+- [x] `llm_compose(problem, adapter, opts)` → GraphSpec — LLM generates topology from natural language
+- [x] `llm_refine(spec, feedback, adapter)` → GraphSpec — LLM modifies existing topology
+- [x] `spec_diff(spec_a, spec_b)` — structural diff between specs (template-aware, feedback-aware)
+- [x] `validate_spec(spec)` → GraphSpecValidation — structural validation (types, deps, templates, feedback, bind targets)
 
 ### 8.4 — Audit & accountability
 

{graphrefly-0.8.0 → graphrefly-0.9.0}/pyproject.toml

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

{graphrefly-0.8.0 → graphrefly-0.9.0}/src/graphrefly/core/dynamic_node.py

@@ -19,7 +19,13 @@ if TYPE_CHECKING:
     from graphrefly.core.guard import MutationRecord
 
 from graphrefly.core.node import _SENTINEL
-from graphrefly.core.protocol import Messages, MessageType, emit_with_batch, propagates_to_meta
+from graphrefly.core.protocol import (
+    Messages,
+    MessageType,
+    emit_with_batch,
+    message_tier,
+    propagates_to_meta,
+)
 
 # ---------------------------------------------------------------------------
 # Public types
@@ -506,9 +512,7 @@ class DynamicNodeImpl[T]:
 
         # singleDep DIRTY skip optimization
         if self._can_skip_dirty():
-            has_phase2 = any(
-                m[0] is MessageType.DATA or m[0] is MessageType.RESOLVED for m in messages
-            )
+            has_phase2 = any(message_tier(m[0]) == 2 for m in messages)
             if has_phase2:
                 filtered = [m for m in messages if m[0] is not MessageType.DIRTY]
                 if filtered:

{graphrefly-0.8.0 → graphrefly-0.9.0}/src/graphrefly/core/node.py

@@ -18,7 +18,13 @@ from graphrefly.core.guard import (
     normalize_actor,
     record_mutation,
 )
-from graphrefly.core.protocol import Messages, MessageType, emit_with_batch, propagates_to_meta
+from graphrefly.core.protocol import (
+    Messages,
+    MessageType,
+    emit_with_batch,
+    message_tier,
+    propagates_to_meta,
+)
 from graphrefly.core.subgraph_locks import (
     acquire_subgraph_write_lock_with_defer,
     ensure_registered,
@@ -824,12 +830,7 @@ class NodeImpl[T]:
             sink_messages = terminal_passthrough
         self._handle_local_lifecycle(lifecycle_messages)
         if self._can_skip_dirty():
-            has_phase2 = False
-            for m in sink_messages:
-                t = m[0]
-                if t is MessageType.DATA or t is MessageType.RESOLVED:
-                    has_phase2 = True
-                    break
+            has_phase2 = any(message_tier(m[0]) == 2 for m in sink_messages)
             if has_phase2:
                 filtered = [m for m in sink_messages if m[0] is not MessageType.DIRTY]
                 if filtered:

{graphrefly-0.8.0 → graphrefly-0.9.0}/src/graphrefly/core/protocol.py

@@ -359,7 +359,7 @@ def _emit_partition(
     # skip partition_for_batch allocation entirely.
     if len(messages) == 1:
         t = messages[0][0]
-        if t is MessageType.DATA or t is MessageType.RESOLVED:
+        if message_tier(t) == 2:
             if _should_defer_phase2(bs, defer_when):
 
                 def _emit_single() -> None:

{graphrefly-0.8.0 → graphrefly-0.9.0}/src/graphrefly/patterns/__init__.py

@@ -3,6 +3,7 @@
 from graphrefly.patterns import (
     ai,
     cqrs,
+    graphspec,
     memory,
     messaging,
     orchestration,
@@ -10,4 +11,13 @@ from graphrefly.patterns import (
     reduction,
 )
 
-__all__ = ["ai", "cqrs", "memory", "messaging", "orchestration", "reactive_layout", "reduction"]
+__all__ = [
+    "ai",
+    "cqrs",
+    "graphspec",
+    "memory",
+    "messaging",
+    "orchestration",
+    "reactive_layout",
+    "reduction",
+]