matrx-graph 0.2.259__tar.gz → 0.2.261__tar.gz

{matrx_graph-0.2.259 → matrx_graph-0.2.261}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: matrx-graph
-Version: 0.2.259
+Version: 0.2.261
 Summary: Channel-based, super-step workflow orchestration engine for the Matrx ecosystem
 Project-URL: Homepage, https://github.com/AI-Matrix-Engine/aidream-current
 Project-URL: Repository, https://github.com/AI-Matrix-Engine/aidream-current

{matrx_graph-0.2.259 → matrx_graph-0.2.261}/matrx_graph/actions/decorator.py

@@ -270,6 +270,7 @@ def register_node(
     launches_nodes: bool = False,
     values_are: Literal["deterministic", "outside", "ai"] = "ai",
     extra_output_handles: tuple[str, ...] = (),
+    output_in_run_row: bool = True,
     node_registry: NodeRegistry | None = None,
     action_registry: ActionRegistry | None = None,
     overwrite: bool = False,
@@ -337,6 +338,7 @@ def register_node(
             launches_nodes=launches_nodes,
             values_are=values_are,
             extra_output_handles=extra_output_handles,
+            output_in_run_row=output_in_run_row,
         )
         adapter = _ActionExecutor(spec=spec, fn=fn, admin_only=admin_only)
         (node_registry or default_registry()).register(adapter, overwrite=overwrite)

{matrx_graph-0.2.259 → matrx_graph-0.2.261}/matrx_graph/actions/spec.py

@@ -125,6 +125,7 @@ def build_action_node_spec(
     launches_nodes: bool = False,
     extra_output_handles: tuple[str, ...] = (),
     values_are: str = "ai",
+    output_in_run_row: bool = True,
 ) -> NodeSpec:
     """Build the NodeSpec that represents this action in the graph engine.
 
@@ -180,6 +181,7 @@ def build_action_node_spec(
         dynamic_output=dynamic_output,
         launches_nodes=launches_nodes,
         values_are=values_are,
+        output_in_run_row=output_in_run_row,
     )
 
 

{matrx_graph-0.2.259 → matrx_graph-0.2.261}/matrx_graph/db/migrations/0100_baseline_post_reorg.sql

@@ -907,6 +907,7 @@ BEGIN
 
     CREATE TABLE workflow.work_item (
         id               UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+        organization_id  UUID NOT NULL,
         run_id           UUID NOT NULL REFERENCES workflow.run(id) ON DELETE CASCADE,
         set_name         TEXT NOT NULL DEFAULT 'default',
         seq              BIGINT GENERATED BY DEFAULT AS IDENTITY,

{matrx_graph-0.2.259 → matrx_graph-0.2.261}/matrx_graph/db/run_store.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import json
+import logging
 from collections.abc import Sequence
 from datetime import UTC, datetime
 from typing import Any
@@ -13,6 +14,8 @@ from matrx_graph.errors import ExecutionError
 from matrx_graph.failure import RunFailure, failure_from_text
 from matrx_graph.types.primitives import RunControlStatus, RunStatus
 
+logger = logging.getLogger(__name__)
+
 RECOVERABLE_STATUSES: tuple[str, ...] = ("errored", "paused", "interrupted", "awaiting_input")
 """Statuses the resume/recovery APIs may claim. Parked, awaiting a user.
 ``awaiting_input`` (INPUT-SURFACE.md park-not-die) is a start-time park —
@@ -843,6 +846,52 @@ class RunStore:
         failure: RunFailure | None = None,
         cancel_reason: str | None = None,
         stopped: dict[str, Any] | None = None,
+    ) -> bool:
+        """The terminal write, which never leaves a run "running" because the write itself failed.
+
+        When the write raises (a statement timeout on a huge output, a dropped connection), the run
+        is ended FAILED with a small error naming the write that failed and no output payload, then
+        the original error is re-raised for the caller to log. 2026-10-05: run 70601b15 finished all
+        its steps, its 11 MB final write timed out, every caller only logged it, and the run read
+        "running" forever."""
+        try:
+            return await self._apply_result(
+                run_id, status=status, steps_executed=steps_executed, output=output, interrupt=interrupt,
+                error=error, last_checkpoint_id=last_checkpoint_id, failure=failure,
+                cancel_reason=cancel_reason, stopped=stopped,
+            )
+        except Exception as exc:
+            if status is RunStatus.FAILED:
+                raise
+            try:
+                await self.mark_failed(
+                    run_id,
+                    error={
+                        "cause": "final_write_failed",
+                        "message": "The run finished its steps, but saving its final result failed, so it is "
+                                   "marked failed instead of staying 'running'. Its steps' results are kept.",
+                        "technical": f"{type(exc).__name__}: {str(exc)[:500]} (intended status: "
+                                     f"{getattr(status, 'value', status)})",
+                    },
+                    steps_executed=steps_executed,
+                )
+            except Exception:  # noqa: BLE001 — the reaper is the last backstop; the original error re-raises
+                logger.exception("[wf:%s] fallback failed-status write also failed", run_id[:8])
+            raise
+
+    async def _apply_result(
+        self,
+        run_id: str,
+        *,
+        status: RunStatus,
+        steps_executed: int,
+        output: dict[str, Any] | None,
+        interrupt: dict[str, Any] | None,
+        error: str | None,
+        last_checkpoint_id: str | None,
+        failure: RunFailure | None = None,
+        cancel_reason: str | None = None,
+        stopped: dict[str, Any] | None = None,
     ) -> bool:
         """Convenience: translate a scheduler RunResult into one workflow.run update.
 

{matrx_graph-0.2.259 → matrx_graph-0.2.261}/matrx_graph/executor/scheduler.py

@@ -257,6 +257,12 @@ def _reset_app_context(token: Any) -> None:
         pass
 
 
+def elided_output_marker(node_id: str, step: int) -> dict[str, Any]:
+    """What ``workflow.run.output`` holds for a step that keeps its output out of the run row."""
+    return {"__kind": "node_output_elided", "node_id": node_id, "step": step,
+            "where": "workflow.node_outcome"}
+
+
 @dataclass(slots=True)
 class Invocation:
     """One scheduled call to a node executor within a super-step.
@@ -1458,6 +1464,11 @@ class Scheduler:
                 # Capture outputs for return value
                 for r in results:
                     if r.output is not None:
+                        if not self._output_in_run_row(r.invocation.node_id):
+                            last_outputs[r.invocation.node_id] = elided_output_marker(
+                                r.invocation.node_id, step
+                            )
+                            continue
                         last_outputs[r.invocation.node_id] = (
                             r.settled_dump
                             if r.settled_dump is not None
@@ -1822,6 +1833,16 @@ class Scheduler:
             stopped=declared_run_stop(self.graph, last_outputs),
         )
 
+    def _output_in_run_row(self, node_id: str) -> bool:
+        """False when the node's spec keeps its output out of the run row (``NodeSpec.output_in_run_row``)."""
+        node = self.graph.nodes.get(node_id)
+        if node is None:
+            return True
+        try:
+            return bool(getattr(self.registry.get(node.spec_type).spec, "output_in_run_row", True))
+        except Exception:  # noqa: BLE001 — an unknown spec keeps today's behavior
+            return True
+
     async def _run_step(
         self,
         run_id: str,

{matrx_graph-0.2.259 → matrx_graph-0.2.261}/matrx_graph/types/node_spec.py

@@ -122,6 +122,12 @@ class NodeSpec(BaseModel, Generic[InputT, OutputT, ConfigT]):
     # as "anything may still fire" and never refuses on reachability; a census
     # test fails any executor that calls ``ctx.send`` without declaring it.
     launches_nodes: bool = False
+    # RUN-ROW OUTPUT (2026-10-05). False when this step's output is a large working document that
+    # the NEXT step consumes (the news monitor's run document, ~2 MB). The output is still persisted
+    # in full on the step's own ``workflow.node_outcome`` row and still flows to the next step; only
+    # the ``workflow.run.output`` aggregate gets a small ``node_output_elided`` marker naming where it
+    # is. Without it a 20-step run wrote ~11 MB into one row and its final write timed out.
+    output_in_run_row: bool = True
     default_join_policy: Literal["all", "any"] | None = Field(
         default=None,
         description=(

{matrx_graph-0.2.259 → matrx_graph-0.2.261}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "matrx-graph"
-version = "0.2.259"
+version = "0.2.261"
 description = "Channel-based, super-step workflow orchestration engine for the Matrx ecosystem"
 readme = "README.md"
 license = { text = "MIT" }

matrx_graph-0.2.261/tests/test_a_failed_final_write_ends_the_run_failed.py

@@ -0,0 +1,46 @@
+"""A run whose final write fails ends FAILED, never "running" forever.
+
+2026-10-05: run 70601b15 finished all 19 steps; its 11 MB completion write timed out; every caller of
+``RunStore.apply_result`` only logged the error, so the run read "running" with no end. The terminal
+write now falls back to a small FAILED write naming what failed, then re-raises for the caller.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import pytest
+
+from matrx_graph.types.primitives import RunStatus
+
+RUN = "6f1e2d3c-4b5a-4968-8776-655443322111"
+
+
+async def test_a_timed_out_completion_write_ends_the_run_failed(monkeypatch) -> None:
+    from matrx_graph.db import run_store as module
+    from matrx_graph.db.run_store import RunStore
+
+    writes: list[dict[str, Any]] = []
+
+    class _Result:
+        rows_affected = 1
+        updated_rows: list = []
+
+    class _Model:
+        @staticmethod
+        async def update_where(filters, **values):
+            if values.get("status") == "completed":
+                raise TimeoutError("statement timeout writing an 11 MB output")
+            writes.append(values)
+            return _Result()
+
+    monkeypatch.setattr(module, "get_model", lambda _name: _Model)
+    with pytest.raises(TimeoutError):
+        await RunStore().apply_result(
+            RUN, status=RunStatus.COMPLETED, steps_executed=19, output={"deliver": {"x": 1}},
+            interrupt=None, error=None, last_checkpoint_id=None,
+        )
+    assert writes and writes[-1]["status"] == "failed", writes
+    error = writes[-1]["error"]
+    assert error.get("cause") == "final_write_failed", error
+    assert "output" not in writes[-1], "the fallback must not carry the payload that failed"

matrx_graph-0.2.261/tests/test_a_large_step_output_stays_out_of_the_run_row.py

@@ -0,0 +1,77 @@
+"""A step can keep its large output out of the run row (``NodeSpec.output_in_run_row=False``).
+
+2026-10-05: the news monitor's 20 steps each output its ~2 MB run document; the run row's ``output``
+(and the ``run_completed`` event) is every step's output merged, so one run wrote ~11 MB into one row
+and its final write timed out, leaving the run "running". A step that declares
+``output_in_run_row=False`` still hands its full output to the next step (and keeps it on its own
+node_outcome row), while the run's ``last_outputs`` holds only a small marker naming where it is.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict
+
+from matrx_graph import (
+    ActionRegistry,
+    ActionTier,
+    Definition,
+    MemoryCheckpointer,
+    NodeCategory,
+    NodeRegistry,
+    RunStatus,
+    Scheduler,
+    compile_graph,
+    register_node,
+)
+from matrx_graph.types.result import NodeResult, success
+from tests._fixtures import make_app_context
+
+BIG = "x" * 200_000
+
+
+class _In(BaseModel):
+    model_config = ConfigDict(extra="allow")
+
+
+class _Doc(BaseModel):
+    doc: str = ""
+
+
+class _Size(BaseModel):
+    received: int = 0
+
+
+def _registry() -> NodeRegistry:
+    nreg, areg = NodeRegistry(), ActionRegistry()
+
+    @register_node(name="test.big_doc", category=NodeCategory.DATA, determinism=ActionTier.PURE,
+                   input_schema=_In, output_schema=_Doc, output_in_run_row=False,
+                   node_registry=nreg, action_registry=areg)
+    async def _big(_ctx, inputs: _In) -> NodeResult[_Doc]:
+        return success(_Doc(doc=BIG))
+
+    @register_node(name="test.reads_doc", category=NodeCategory.DATA, determinism=ActionTier.PURE,
+                   input_schema=_In, output_schema=_Size, node_registry=nreg, action_registry=areg)
+    async def _reads(_ctx, inputs: _In) -> NodeResult[_Size]:
+        return success(_Size(received=len(getattr(inputs, "doc", "") or "")))
+
+    return nreg
+
+
+async def test_a_large_step_output_reaches_the_next_step_but_not_the_run_row() -> None:
+    nreg = _registry()
+    definition = Definition.model_validate({
+        "nodes": [
+            {"id": "a", "type": "test.big_doc", "position": {"x": 0, "y": 0}, "data": {}},
+            {"id": "b", "type": "test.reads_doc", "position": {"x": 100, "y": 0}, "data": {}},
+        ],
+        "edges": [{"id": "e", "source": "a", "target": "b", "data": {"kind": "data"}}],
+    })
+    scheduler = Scheduler(compile_graph(definition, registry=nreg), MemoryCheckpointer(), make_app_context(),
+                          registry=nreg)
+    result = await scheduler.run(run_id="run-large-step", inputs={})
+    assert result.status is RunStatus.COMPLETED
+    assert result.last_outputs["b"]["received"] == len(BIG), "the next step must still get the full output"
+    marker = result.last_outputs["a"]
+    assert marker.get("__kind") == "node_output_elided" and marker.get("node_id") == "a", marker
+    assert len(str(result.last_outputs)) < 2_000

{matrx_graph-0.2.259 → matrx_graph-0.2.261}/tests/test_standalone_db_models.py

@@ -23,7 +23,7 @@ MODEL_TABLES = {
 }
 
 
-def _baseline_columns(table: str) -> set[str]:
+def _baseline_table_body(table: str) -> str:
     sql = BASELINE.read_text(encoding="utf-8")
     match = re.search(
         rf"CREATE TABLE workflow\.{table} \(\n(?P<body>.*?)\n    \);",
@@ -31,8 +31,12 @@ def _baseline_columns(table: str) -> set[str]:
         flags=re.DOTALL,
     )
     assert match is not None, f"workflow.{table} missing from standalone baseline"
+    return match.group("body")
+
+
+def _baseline_columns(table: str) -> set[str]:
     columns: set[str] = set()
-    for line in match.group("body").splitlines():
+    for line in _baseline_table_body(table).splitlines():
         column_match = re.match(r"^ {8}([a-z][a-z0-9_]*)\s+", line)
         if column_match is not None:
             columns.add(column_match.group(1))
@@ -70,3 +74,13 @@ def test_node_data_slot_uses_canonical_created_by_owner() -> None:
     assert "created_by" in fields
     assert fields["created_by"].null is False
     assert "user_id" not in fields
+
+
+def test_work_item_standalone_schema_requires_organization_context() -> None:
+    fields = build_standalone_models("standalone_work_item_organization_test")["WfWorkItem"]._fields
+    assert fields["organization_id"].null is False
+    assert re.search(
+        r"^        organization_id\s+UUID NOT NULL,",
+        _baseline_table_body("work_item"),
+        flags=re.MULTILINE,
+    )