graphrefly 0.9.0__tar.gz → 0.10.0__tar.gz

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

@@ -2,6 +2,14 @@
 
 <!-- version list -->
 
+## v0.10.0 (2026-04-06)
+
+### Features
+
+- 8.2
+  ([`abe2102`](https://github.com/graphrefly/graphrefly-py/commit/abe210208ff248d883ac319855108aa4d345812f))
+
+
 ## v0.9.0 (2026-04-06)
 
 ### Features

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: graphrefly
-Version: 0.9.0
+Version: 0.10.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.9.0 → graphrefly-0.10.0}/docs/optimizations.md

@@ -139,10 +139,21 @@ 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.
+- **Core `bridge()` helper (Phase 8.2, noted 2026-04-06, QA 2026-04-06):** Both TS and PY export `bridge(from, to, opts?)` / `bridge(from_node, to_node, *, name, down)` from `core/bridge`. Creates a graph-visible effect node that intercepts messages from `from` via `on_message` and forwards to `to.down()`. TS updated in QA: default forwards **all standard types** (DATA, DIRTY, RESOLVED, COMPLETE, ERROR, TEARDOWN, PAUSE, RESUME, INVALIDATE). Terminal types always cause bridge self-termination regardless of `down` filter. `funnel()` explicitly excludes TEARDOWN from inter-stage bridges. `DEFAULT_DOWN` exported for callers. **PY needs update** to match: (1) `DEFAULT_DOWN` should include all standard types, (2) terminal self-termination regardless of `down`, (3) `funnel()` should exclude TEARDOWN explicitly.
 - **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.
+- **~~Feedback bare DATA to reentry/counter — deferred to 8.2 (Phase 8.1, noted 2026-04-06, resolved 2026-04-06):~~** Resolved in 8.2. `feedback()` now uses a graph-registered effect node (`__feedback_effect_<condition>`) that intercepts condition messages via `on_message` and forwards to reentry/counter. The effect participates in two-phase push naturally. Old subscribe-based bridge removed. Both TS and PY.
 - **`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.
+- **Domain templates cross-language parity (Phase 8.2, noted 2026-04-06):** Both TS and PY implement `observability_graph`/`observabilityGraph`, `issue_tracker_graph`/`issueTrackerGraph`, `content_moderation_graph`/`contentModerationGraph`, `data_quality_graph`/`dataQualityGraph` in `patterns/domain_templates` / `patterns/domain-templates`. Key alignment: (1) All four use source injection (option B) — user passes a source node, template wires the topology. (2) Same well-known node names across both. (3) Null guard on derived fns: PY returns `None`, TS returns `undefined` — both skip computation when source hasn't emitted real data. (4) PY `derived` fn signature is `(vals, actions)` vs TS `(vals) => ...`. (5) Options: PY uses `@dataclass`, TS uses interface types. (6) Meta keys: `domain_template: True`, `template_type: "<name>"`. Both repos: TS 24 tests, PY 21 tests.
+- **Intentional cross-language divergences (Phase 8.2, noted 2026-04-06 parity):** (A) Bridge `down` option type: TS `readonly symbol[]`, PY `Sequence[MessageType] | None` — idiomatic to each language. (B) `BridgeOptions`: TS exports a named type alias, PY uses keyword args on the function — Pythonic kwargs pattern. (C) `batch()` syntax: TS callback `batch(() => { ... })`, PY context manager `with batch(): ...` — per spec §6.1. (E) `ScoredItem`: TS is a plain object / type alias, PY is a class with `__slots__`, `__eq__`, `__repr__` — PY more ergonomic for debugging; runtime payloads identical.
+- **`content_moderation_graph` review accumulator read-modify-write (Phase 8.2, noted 2026-04-06 QA, patched 2026-04-06):** The `__review_accumulator` effect uses `review_queue.get()` + spread + `review_queue.down()` to append items. TS is single-threaded (safe). PY's GIL protects against true races but the pattern is fragile under async event loops — consider reactive scan/reduce if PY ever supports async node fns. QA patch: wrapped `review_queue.down()` in `with batch():` to defer propagation until the current cycle completes, preventing re-entrant dispatch into downstream feedback nodes.
+- **`data_quality_graph` baseline updater re-entrant `down()` (Phase 8.2, noted 2026-04-06 QA, patched 2026-04-06):** The `__baseline_updater` effect calls `baseline.down()` during its own compute, which triggers synchronous downstream propagation into `drift_node` and `output_node` while the source update cycle is still in progress. QA patch: wrapped `baseline.down()` in `with batch():` to defer propagation. Same pattern as review accumulator above.
+- **`budget_gate` `buffer.pop(0)` is O(n) (Phase 8.1, noted 2026-04-06 QA, deferred):** `flush_buffer` in `budget_gate` calls `buffer.pop(0)` in a while loop — O(n²) for full drain. Should use `collections.deque.popleft()`. Low priority: budget_gate buffers are typically small.
+- **`stratify` `pending_dirty` not reset on TEARDOWN (Phase 8.1, noted 2026-04-06 QA, deferred):** The `pending_dirty` mutable flag in `stratify`'s `on_message` handler is never cleared on TEARDOWN. Default dispatch handles TEARDOWN via `return False`, but stale dirty state persists if the node is reused. Low impact: graphs are not typically restarted without reconstruction.
+- **~~Bridge `_DEFAULT_DOWN` excludes PAUSE/RESUME (Phase 8.2, noted 2026-04-06 QA, resolved 2026-04-06 parity):~~** Resolved: `DEFAULT_DOWN` now includes all 9 standard types (DATA, DIRTY, RESOLVED, COMPLETE, ERROR, TEARDOWN, PAUSE, RESUME, INVALIDATE), matching TS. `funnel()` explicitly excludes TEARDOWN via `down` filter. Renamed from `_DEFAULT_DOWN` to `DEFAULT_DOWN` (public export).
+- **Unbounded review queue growth in `content_moderation_graph` (Phase 8.2, noted 2026-04-06 QA, deferred):** The `review_queue` state node accumulates items without bound — every new review item copies and extends the list. O(n²) memory churn over time. Cap/eviction is domain-specific; consider adding `max_queue_size` option or reactive scan/reduce if templates grow beyond demo use.
+- **Bridge/feedback node detection in `decompile_graph` uses naming convention (Phase 8.2, noted 2026-04-06 QA, deferred):** `decompile_graph` skips internal nodes via `path.startswith("__bridge_")` and `path.startswith("__feedback_effect_")` — name-based, not metadata-based. Works because naming is convention-controlled by `bridge()`, `funnel()`, and `feedback()`. A more robust approach would tag bridge nodes via `meta={"_bridge": True}` and check that in decompile. Low priority: naming convention is stable and internally generated.
+- **Feedback effect perpetually dirty status (Phase 8.1/8.2, noted 2026-04-06 QA):** The `__feedback_effect_<condition>` node forwards DIRTY via default dispatch but consumes DATA. The effect stays in "dirty" status between emissions. Cosmetic — effects don't need to settle. `describe()` may show "dirty" for feedback effects between cycles. Not a bug.
+- **Reduction primitives cross-language parity (Phase 8.1, noted 2026-04-06, QA 2026-04-06, updated 8.2 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` now uses `bridge()` from `core/bridge` for inter-stage wiring — graph-visible effect nodes (`__bridge_<from>→<stage>_input`) replace the old subscribe-based bridges. Visible in `describe()`, participates in two-phase push. (3) `feedback` counter node is source of truth (resettable via `graph.set()`); feedback wiring now uses a graph-registered effect node (`__feedback_effect_<condition>`) instead of raw subscribe. 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.9.0 → graphrefly-0.10.0}/docs/roadmap.md

@@ -10,6 +10,58 @@
 
 ---
 
+## Harness Engineering Sprint — Priority Build Order
+
+> **Context:** Mirrors the TS harness engineering sprint (`graphrefly-ts/docs/roadmap.md`). Python tracks TS for core parity on the audit/accountability layer (§9.2). Eval harness is TS-primary (corpus, rubrics, runner). MCP server and framework infiltration packages are TS-only. Python focus: §9.2 parity + §8.2 rearchitecture debt + backpressure.
+>
+> **Design reference:** `~/src/graphrefly-ts/archive/docs/SESSION-harness-engineering-strategy.md`
+
+### Wave 1 (Python): Eval parity prep (Weeks 1-3)
+
+No new Python deliverables — Wave 1 is TS-primary (eval runner, CI, blog). Python work during this window:
+
+#### 9.0 — Architecture debt (8.2 rearchitecture) [HIGH PRIORITY]
+
+These fix protocol violations identified post-8.2 ship. Must land before §9.2 audit layer, which assumes clean two-phase propagation on all paths.
+
+- [x] Rearchitect `feedback()` as graph-visible bridge node (8.2 → 9.0) — replaces subscribe-based shortcut; enables proper DIRTY→DATA two-phase on reentry/counter; resolves bare-DATA protocol gap
+- [x] Rearchitect `funnel()` bridges as graph-visible nodes (8.2 → 9.0) — replaces subscribe forwarding; resolves §5.9 imperative trigger violation + teardown leak
+- [ ] `stratify` two-dep gating (8.2 → 9.0) — gate classification on both source and rules settling (eliminates stale-rules race)
+
+### Wave 2 (Python): Audit & accountability parity (Weeks 4-9)
+
+#### 9.2 — Audit & accountability (8.4 → 9.2) — TS parity
+
+- [ ] `explain_path(graph, from_node, to_node)` — walk backward through graph derivation chain. Human + LLM readable causal chain. (8.4 → 9.2)
+- [ ] `audit_trail(graph, opts)` → Graph — wraps graph with `reactive_log` recording every mutation, actor, timestamp, causal chain. (8.4 → 9.2)
+- [ ] `policy_enforcer(graph, policies)` — reactive constraint enforcement. Policies are nodes. Violations → alert subgraph. (8.4 → 9.2)
+- [ ] `compliance_snapshot(graph)` — point-in-time export for regulatory archival. (8.4 → 9.2)
+
+#### 9.2b — Backpressure protocol (8.5 → 9.2b)
+
+TS has this shipped; Python needs parity for production reduction pipelines.
+
+- [ ] Backpressure protocol — formalize PAUSE/RESUME for throughput control across graph boundaries (8.5 → 9.2b)
+
+### Wave 3 (Python): Polish & publish (Weeks 10-15)
+
+- [ ] `llms.txt` for AI agent discovery (7 → 9.3)
+- [ ] PyPI publish: `graphrefly-py` (7 → 9.3)
+- [ ] Docs site at `py.graphrefly.dev` (7 → 9.3)
+
+### Deferred (post-Wave 3)
+
+- §7.2 Showcase demos (Pyodide/WASM lab) — after TS demos prove the pattern
+- §7.2b Universal reduction demos — after Demo 0 + Demo 6
+- §7.3 Scenario tests — after demos
+- §7.4 Inspection stress tests
+- §7.5 Foreseen building blocks
+- §8.5 `peer_graph`, `sharded_graph`, adaptive sampling — distributed scale
+- §6.2 V2 schema, §6.3 V3 caps+refs — versioning depth
+- Free-threaded Python 3.14 benchmark suite — perf exploration
+
+---
+
 ## Phase 0: Foundation
 
 ### 0.1 — Project scaffold
@@ -497,12 +549,12 @@ Composable building blocks between sources and sinks.
 
 Pre-wired graphs for common "info → action" domains. Users fork/extend.
 
-- [ ] `observability_graph(opts)` → Graph — OTel ingest → stratified reduction → correlation → SLO verification → alert prioritization → sink
-- [ ] `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)
+- [x] `observability_graph(opts)` → Graph — OTel ingest → stratified reduction → correlation → SLO verification → alert prioritization → sink
+- [x] `issue_tracker_graph(opts)` → Graph — findings → extraction → verifiable assertions → regression detection → distillation → prioritized queue
+- [x] `content_moderation_graph(opts)` → Graph — ingest → LLM classification → human review → feedback → policy refinement
+- [x] `data_quality_graph(opts)` → Graph — DB/API ingest → schema validation → anomaly detection → drift alerting → remediation suggestions
+- [x] 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)
+- [x] 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

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

@@ -1,6 +1,6 @@
 [project]
 name = "graphrefly"
-version = "0.9.0"
+version = "0.10.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.9.0 → graphrefly-0.10.0}/src/graphrefly/core/__init__.py

@@ -1,5 +1,6 @@
 """Core node primitives and protocol types for graphrefly."""
 
+from graphrefly.core.bridge import DEFAULT_DOWN, bridge
 from graphrefly.core.cancellation import CancellationToken, cancellation_token
 from graphrefly.core.clock import monotonic_ns, wall_clock_ns
 from graphrefly.core.dynamic_node import DynamicNodeImpl, dynamic_node
@@ -80,6 +81,8 @@ from graphrefly.core.versioning import (
 
 __all__ = [
     "Actor",
+    "bridge",
+    "DEFAULT_DOWN",
     "CancellationToken",
     "cancellation_token",
     "DynamicNodeImpl",

graphrefly-0.10.0/src/graphrefly/core/bridge.py

@@ -0,0 +1,146 @@
+"""bridge — graph-visible message forwarding between two nodes.
+
+Replaces ad-hoc ``subscribe()`` bridges that bypass graph topology.
+The returned node is an effect that intercepts messages from ``from_node``
+and forwards them to ``to_node.down()``. Register it with ``graph.add()`` to
+make the bridge visible in ``describe()`` and ``snapshot()``.
+
+**Upstream path:** The bridge node has ``from_node`` as its dep, so anything
+downstream of the bridge that calls ``up()`` naturally reaches ``from_node``.
+If ``to_node`` is used as a dep by other nodes and those nodes send ``up()``,
+the messages reach ``to_node``'s deps (not ``from_node``). For full upstream
+relay across the bridge boundary, wire the bridge as a dep of ``to_node``'s
+consumers or use ``graph.connect()``.
+
+**ABAC / guards:** ``to_node.down()`` is called without transport options,
+so any ABAC guard on ``to_node`` receives ``actor = None``. Upstream
+(``up()``) messages propagate through the dep chain the same way — no actor
+is injected on either path. Both paths are intentionally unguarded; if
+``to_node`` requires a specific actor, provide a guarded wrapper node and
+bridge to that instead.
+
+**Default forwarding:** All standard message types are forwarded by
+default, including TEARDOWN, PAUSE, RESUME, and INVALIDATE. Use the
+``down`` option to restrict which types are forwarded. Callers that need
+to exclude TEARDOWN (e.g. inter-stage wiring in ``funnel()``) pass an
+explicit ``down`` sequence without TEARDOWN.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+from graphrefly.core.node import NodeImpl, node
+from graphrefly.core.protocol import MessageType
+
+DEFAULT_DOWN: frozenset[MessageType] = frozenset(
+    {
+        MessageType.DATA,
+        MessageType.DIRTY,
+        MessageType.RESOLVED,
+        MessageType.COMPLETE,
+        MessageType.ERROR,
+        MessageType.TEARDOWN,
+        MessageType.PAUSE,
+        MessageType.RESUME,
+        MessageType.INVALIDATE,
+    }
+)
+
+# All standard message types the bridge understands. Types outside this set
+# are "unknown" and must always be forwarded (spec §1.3.6).
+_STANDARD_TYPES: frozenset[MessageType] = frozenset(
+    {
+        MessageType.DATA,
+        MessageType.DIRTY,
+        MessageType.RESOLVED,
+        MessageType.COMPLETE,
+        MessageType.ERROR,
+        MessageType.TEARDOWN,
+        MessageType.PAUSE,
+        MessageType.RESUME,
+        MessageType.INVALIDATE,
+    }
+)
+
+
+def bridge(
+    from_node: NodeImpl[Any],
+    to_node: NodeImpl[Any],
+    *,
+    name: str | None = None,
+    down: Sequence[MessageType] | None = None,
+) -> NodeImpl[Any]:
+    """Create a graph-visible bridge node that forwards messages.
+
+    The bridge is a real node (effect) — it shows up in ``describe()``,
+    participates in two-phase push, and cleans up on TEARDOWN. Register
+    it via ``graph.add()`` to make it part of the graph topology.
+
+    **Unknown message types** (custom domain signals not in the standard
+    protocol set) are always forwarded to ``to_node``, regardless of the
+    ``down`` option. This satisfies spec §1.3.6 ("unknown types forward
+    unchanged").
+
+    **COMPLETE / ERROR**: when forwarded, the bridge also transitions to
+    terminal state so graph-wide completion detection works correctly.
+
+    Args:
+        from_node: Source node to observe.
+        to_node: Target node to forward messages to via ``to_node.down()``.
+        name: Optional node name (for graph registration / describe).
+        down: Standard message types to forward. Default: all standard
+            types. Unknown (non-standard) types always forward per spec
+            §1.3.6 regardless of this option.
+
+    Returns:
+        A bridge effect node. Add to a graph with ``graph.add(name, bridge(...))``.
+
+    Example:
+        ```python
+        from graphrefly import bridge, state, Graph
+
+        a = state(0)
+        b = state(0)
+        br = bridge(a, b, name="__bridge_a_b")
+        g = Graph("test")
+        g.add("a", a)
+        g.add("b", b)
+        g.add("__bridge_a_b", br)
+        g.connect("a", "__bridge_a_b")
+        ```
+    """
+    allowed_down = frozenset(down if down is not None else DEFAULT_DOWN)
+
+    def on_message(msg: Any, dep_index: int, actions: Any) -> bool:  # noqa: ARG001
+        t = msg[0]
+
+        # Unknown types (custom domain signals) always forward — spec §1.3.6.
+        if t not in _STANDARD_TYPES:
+            to_node.down([msg])
+            return True
+
+        # Known type, not in allowed_down — consume without forwarding.
+        if t not in allowed_down:
+            return True
+
+        # Forward the message to the target.
+        to_node.down([msg])
+
+        # For terminal types, return False so default dispatch also handles
+        # terminal state on the bridge itself (bridge completes when from completes).
+        return t is not MessageType.COMPLETE and t is not MessageType.ERROR
+
+    return node(
+        [from_node],
+        None,
+        on_message=on_message,
+        describe_kind="effect",
+        name=name,
+    )
+
+
+__all__ = ["DEFAULT_DOWN", "bridge"]

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

@@ -3,6 +3,7 @@
 from graphrefly.patterns import (
     ai,
     cqrs,
+    domain_templates,
     graphspec,
     memory,
     messaging,
@@ -14,6 +15,7 @@ from graphrefly.patterns import (
 __all__ = [
     "ai",
     "cqrs",
+    "domain_templates",
     "graphspec",
     "memory",
     "messaging",