matrx-graph 0.2.76__tar.gz → 0.2.78__tar.gz

{matrx_graph-0.2.76 → matrx_graph-0.2.78}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: matrx-graph
-Version: 0.2.76
+Version: 0.2.78
 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.76 → matrx_graph-0.2.78}/matrx_graph/db/db_requirements.py

@@ -27,6 +27,10 @@ DB_REQUIREMENTS = {
         {"key": "WfRun", "table": "workflow.run"},
         {"key": "WfCheckpoint", "table": "workflow.checkpoint"},
         {"key": "WfNodeOutcome", "table": "workflow.node_outcome"},
+        # The USER's diagnostic log (log.record). A ledger table: SELECT-only
+        # for users, written by the server. Never the platform system_error
+        # queue — workflows are authored by users.
+        {"key": "WfRunLog", "table": "workflow.run_log"},
         {"key": "WfTrigger", "table": "workflow.trigger"},
         {"key": "WfJob", "table": "workflow.job"},
         {"key": "WfNodeEvents", "table": "workflow.node_events"},

matrx_graph-0.2.78/matrx_graph/db/migrations/0110_run_log.sql

@@ -0,0 +1,66 @@
+-- 0110 — workflow.run_log: THE WORKFLOW'S OWN DIAGNOSTIC RECORD.
+-- RECORD of a live migration applied via the Supabase MCP on 2026-08-23
+-- (migration `workflow_run_log_user_diagnostics`). `.sql` files here are
+-- records, not mechanisms — but a standalone install against a bare Matrx
+-- Postgres runs this same provisioner call.
+--
+-- Arman, 2026-08-23:
+--   "we need to give users a way to be able to track their own internal logs
+--    and problems… a place where you can pass it whatever thing you want, and
+--    then it will write to the database in a table that can later be used to
+--    diagnose problems that happened within a workflow that you were able to
+--    work around, but should never have happened."
+--
+-- Nothing on the platform could do this. A workflow that hit a serious problem
+-- and recovered had two options: fail the run, or say nothing. The Agent
+-- Foundry took the second — both Component Artisans refused to build, each
+-- with a correct diagnosis, and the run reported `completed` with no component
+-- and no trace of why.
+--
+-- NOT the platform system_error queue: workflows are authored by USERS, so a
+-- node writing there would let any author inject into our operational alarms.
+-- `ledger` variant — SELECT-only for users (org membership + the
+-- global-readable system org), every write through the server.
+--
+-- Certified: iam.canonical_certify_ok('workflow','run_log','workflow_run_log') = true.
+
+select platform.create_entity_table(
+  p_schema => 'workflow',
+  p_table => 'run_log',
+  p_token => 'workflow_run_log',
+  p_label => 'Workflow Run Log',
+  p_fields => ARRAY[
+    'run_id uuid NOT NULL REFERENCES workflow.run(id)',
+    'definition_id uuid REFERENCES workflow.definition(id)',
+    'node_id text',
+    'step integer',
+    'attempt integer',
+    'severity text NOT NULL DEFAULT ''warning''',
+    'label text NOT NULL',
+    'message text NOT NULL',
+    'payload jsonb NOT NULL DEFAULT ''{}''::jsonb',
+    'payload_kind text',
+    'occurred_at timestamptz NOT NULL DEFAULT now()'
+  ],
+  p_variant => 'ledger',
+  p_versioned => false,
+  p_soft_delete => false,
+  p_visibility => 'none',
+  p_category => false,
+  p_listed => false,
+  p_org_default => true,
+  p_gin_jsonb => true
+);
+
+-- Fixed code-level vocabulary (db-rules §0.4) — a sixth level is a migration,
+-- never a string somebody types.
+alter table workflow.run_log
+  add constraint run_log_severity_check
+  check (severity in ('debug', 'info', 'warning', 'error', 'critical'));
+
+create index if not exists run_log_run_idx
+  on workflow.run_log (run_id, occurred_at desc);
+create index if not exists run_log_definition_label_idx
+  on workflow.run_log (definition_id, label, occurred_at desc);
+create index if not exists run_log_org_severity_idx
+  on workflow.run_log (organization_id, severity, occurred_at desc);

{matrx_graph-0.2.76 → matrx_graph-0.2.78}/matrx_graph/nodes/__init__.py

@@ -58,6 +58,7 @@ from matrx_graph.nodes.http import (
     HttpPostExecutor,
 )
 from matrx_graph.nodes.io.user_input import UserInputExecutor
+from matrx_graph.nodes.log import RecordIssueExecutor
 from matrx_graph.nodes.math_ import MathEvaluateExecutor
 from matrx_graph.nodes.output.to_frontend import ToFrontendExecutor
 from matrx_graph.nodes.pipe.step import PipeStepExecutor
@@ -120,6 +121,8 @@ def register_builtin_nodes(
         WaitUntilExecutor(),
         ThrottleExecutor(),
         NoopExecutor(),
+        # Diagnostics — the workflow's own record of what went wrong
+        RecordIssueExecutor(),
         # Math
         MathEvaluateExecutor(),
         # HTTP

{matrx_graph-0.2.76 → matrx_graph-0.2.78}/matrx_graph/nodes/data/FEATURE.md

@@ -3,6 +3,28 @@
 Data nodes are deterministic transformations and validation boundaries. They
 must not call models or silently invent missing values.
 
+## `data.transform` declares itself DYNAMIC — and the kind lives on the INSTANCE
+
+Its output shape IS the author's expression, so no single `output_kind` can
+describe every instance without lying. The spec sets `dynamic_output=True`
+(2026-08-23, vision audit GAP 2 — it always behaved this way and never said
+so, which is how the boundary lint could not tell it apart from a node that
+forgot). **The honest declaration belongs on the node instance**, as
+`data.output_kind` in the definition, alongside an expression that emits
+`'__kind'` so the payload carries its own identity:
+
+```python
+"config": {"expression": "{'__kind': 'agent_foundry_report', 'kind': inputs['kind'], …}"},
+"output_kind": "agent_foundry_report",
+```
+
+Reference instances: `aidream/workflows/agent_foundry_v1.py`
+(`kind_brief` / `component_briefs` / `foundry_report`) and
+`study_pack_v2.py` (`build_sources`, `pack`). A composition step whose result
+nests other kinds keeps them SECTIONED — each nested object carries its own
+`__kind` and earns a real `content_ir.kind_edge` row; a flattened
+`vars_a_component_key` prefix is addressable by nothing.
+
 ## `data.criteria_gate`
 
 The criteria gate proves workflow completion properties before a consequential

{matrx_graph-0.2.76 → matrx_graph-0.2.78}/matrx_graph/nodes/data/transform.py

@@ -87,6 +87,11 @@ class TransformExecutor:
             HandleSpec(id="in", direction=HandleDirection.INPUT),
             HandleSpec(id="out", direction=HandleDirection.OUTPUT),
         ),
+        # DYNAMIC BY DESIGN — the output shape IS the author's expression, so
+        # no single kind can describe every instance. Declared dynamic (GAP 2,
+        # §10g); the honest declaration lives on the node INSTANCE as
+        # ``data.output_kind`` (see aidream/workflows/study_pack_v2.py::pack).
+        dynamic_output=True,
         determinism=ActionTier.PURE,
         icon="function-square",
     )

{matrx_graph-0.2.76 → matrx_graph-0.2.78}/matrx_graph/nodes/flow/FEATURE.md

@@ -9,6 +9,16 @@ All four are **pass-through**: the input payload flows downstream unchanged,
 so none declares an `output_kind` — runtime `__kind` propagation carries the
 payload's identity (the `data.transform` posture; never declare `"json"`).
 
+🚨 **They DECLARE that** (2026-08-23, vision audit GAP 2): all four set
+`dynamic_output=True` on their `NodeSpec`. They always behaved this way and
+the burndown ledger always said so, but the flag was never set — so the
+coverage board counted them UNCOVERED and the boundary lint could not tell a
+deliberate pass-through from a node that simply forgot. **Dynamic is a
+declaration, not a gap**, and it is what the palette reads to say "depends on
+your setup" instead of "shape not declared" (register item §9.3). Adding a
+pass-through node here without the flag now FAILS CI
+(`scripts/check_kind_boundaries.py`, `NODE_OUTPUT_UNDECLARED`).
+
 ## The durable timer (`flow.sleep` / `flow.wait_until`)
 
 A sleep that blocks a worker coroutine dies with the worker. Ours is the

{matrx_graph-0.2.76 → matrx_graph-0.2.78}/matrx_graph/nodes/flow/noop.py

@@ -68,6 +68,12 @@ class NoopExecutor:
             HandleSpec(id="in", direction=HandleDirection.INPUT, required=False),
             HandleSpec(id="out", direction=HandleDirection.OUTPUT, required=False),
         ),
+        # PASS-THROUGH BY DESIGN — the payload flows out byte-identical, so
+        # this node's real output shape is whatever reached it. Declared
+        # dynamic (GAP 2, KINDS_EVERYWHERE_PLAN §10g) so the coverage board
+        # and the boundary lint read the same posture the burndown ledger
+        # already recorded; runtime __kind propagation carries identity.
+        dynamic_output=True,
         determinism=ActionTier.PURE,
         icon="circle-dot",
     )

{matrx_graph-0.2.76 → matrx_graph-0.2.78}/matrx_graph/nodes/flow/sleep.py

@@ -132,6 +132,11 @@ class SleepExecutor:
             HandleSpec(id="in", direction=HandleDirection.INPUT, required=False),
             HandleSpec(id="out", direction=HandleDirection.OUTPUT, required=False),
         ),
+        # PASS-THROUGH BY DESIGN — the payload flows through unchanged (see
+        # module docstring). Declared dynamic (GAP 2, KINDS_EVERYWHERE_PLAN
+        # §10g) so runtime __kind propagation is the recorded posture rather
+        # than an undeclared NULL.
+        dynamic_output=True,
         determinism=ActionTier.NON_DETERMINISTIC,
         can_interrupt=True,
         icon="clock",
@@ -195,6 +200,11 @@ class WaitUntilExecutor:
             HandleSpec(id="in", direction=HandleDirection.INPUT, required=False),
             HandleSpec(id="out", direction=HandleDirection.OUTPUT, required=False),
         ),
+        # PASS-THROUGH BY DESIGN — the payload flows through unchanged (see
+        # module docstring). Declared dynamic (GAP 2, KINDS_EVERYWHERE_PLAN
+        # §10g) so runtime __kind propagation is the recorded posture rather
+        # than an undeclared NULL.
+        dynamic_output=True,
         determinism=ActionTier.NON_DETERMINISTIC,
         can_interrupt=True,
         icon="calendar-clock",

{matrx_graph-0.2.76 → matrx_graph-0.2.78}/matrx_graph/nodes/flow/throttle.py

@@ -88,6 +88,11 @@ class ThrottleExecutor:
             HandleSpec(id="in", direction=HandleDirection.INPUT, required=False),
             HandleSpec(id="out", direction=HandleDirection.OUTPUT, required=False),
         ),
+        # PASS-THROUGH BY DESIGN — the payload flows through unchanged (see
+        # module docstring). Declared dynamic (GAP 2, KINDS_EVERYWHERE_PLAN
+        # §10g) so runtime __kind propagation is the recorded posture rather
+        # than an undeclared NULL.
+        dynamic_output=True,
         determinism=ActionTier.NON_DETERMINISTIC,
         icon="gauge",
     )

matrx_graph-0.2.78/matrx_graph/nodes/log/FEATURE.md

@@ -0,0 +1,69 @@
+# `log.*` — the workflow's own diagnostic record
+
+Verified against `record.py`, `workflow.run_log` (live), and
+`tests/test_log_record_node.py` on 2026-08-23.
+
+One node: **`log.record`** — *"Record a Problem"*.
+
+## Why it exists
+
+A workflow that hit a serious problem and **worked around it** had exactly two
+options: fail the whole run, or say nothing. The Agent Foundry took the second
+— both Component Artisans refused to build a component, each with a correct
+and well-argued diagnosis, and the run reported `completed` with no component
+and no trace of why. The answer sat in an agent's prose and nothing was ever
+going to read it (Arman, 2026-08-23).
+
+## Why it is not `system_error`
+
+Workflows are authored by **users**. A node that wrote into the platform's own
+error queue would let any author inject rows into our operational alarm
+surface. `workflow.run_log` is the user's own table: `ledger` variant,
+org-scoped, readable by the run's owner, written only by the server. Genuine
+platform defects still go to `system_error` through the server's own paths.
+
+## The contract
+
+| field | why it is separate |
+|---|---|
+| `label` | the STABLE key — "this happened 40 times" needs a key with no run id or timestamp in it |
+| `message` | the human sentence — one field cannot be both, which is why the table splits them too |
+| `payload` + `payload_kind` | the evidence, verbatim, and its registered Shape when it has one. A diagnostic that throws away the evidence is a log line |
+| `severity` | `debug`/`info`/`warning`/`error`/`critical`, CHECK-constrained; closed vocabulary |
+
+Plus the provenance a diagnosis is useless without: `run_id`, `definition_id`,
+`node_id`, `step`, `attempt`, `occurred_at`.
+
+## Four invariants, each pinned by a test
+
+1. **It never fails the run.** Every failure path returns `recorded=false` with
+   a reason and the workflow carries on. A recorder that can break the run it
+   is reporting on would make authors stop reaching for it — the only way this
+   node can truly fail.
+2. **It returns a typed receipt** (`run_log_entry`), whose FIRST field is
+   `recorded`. Arman's rule for agents binds our own nodes identically: *"a key
+   that confirms success, and that is the key you read."* `recorded=false`
+   means the problem happened AND we failed to write it down — strictly worse
+   than the problem, and branchable.
+3. **The organization is the RUN's**, read off the run row (87/87 live runs
+   carry one), falling back to the request. Refuses only when neither has one —
+   the database never guesses (db-rules §0.9). *Reading it off `AppContext`
+   alone refused to write on the very first real run: a detached workflow
+   context legitimately carries no org.*
+4. **Bounded.** `MAX_ENTRIES_PER_RUN` (200) caps a runaway loop, loudly once;
+   `MAX_PAYLOAD_CHARS` (100k) truncates fat evidence with a marker rather than
+   losing the record.
+
+## Traps paid for
+
+* **An input default masks a config.** `severity` is `Severity | None`, not
+  `Severity = "warning"` — with a non-null default, `inputs.severity or
+  config.severity` can never see the author's configured value. Caught on the
+  first live run: a step configured `error` recorded a `warning`. Absence must
+  be representable wherever a config can override.
+
+## Proof
+
+`uv run python scripts/_verify_run_log_node.py` — a real run through the real
+Scheduler + PostgresCheckpointer against the live database, reading the row
+back (10/10). Unit: `packages/matrx-graph/tests/test_log_record_node.py` (8).

matrx_graph-0.2.78/matrx_graph/nodes/log/__init__.py

@@ -0,0 +1,16 @@
+"""``log.*`` — the workflow's own diagnostic record.
+
+A workflow that hits a serious problem and recovers from it must be able to
+SAY SO. Before this pack it could only fail the run or stay silent, and
+silence is what the Agent Foundry chose while shipping no component (Arman,
+2026-08-23). Rows land in ``workflow.run_log`` — the USER's table, org-scoped
+and read by the run's owner, never the platform's ``system_error`` queue.
+"""
+
+from matrx_graph.nodes.log.record import (
+    MAX_ENTRIES_PER_RUN,
+    SEVERITIES,
+    RecordIssueExecutor,
+)
+
+__all__ = ["MAX_ENTRIES_PER_RUN", "SEVERITIES", "RecordIssueExecutor"]

matrx_graph-0.2.78/matrx_graph/nodes/log/record.py

@@ -0,0 +1,348 @@
+"""``log.record`` — the workflow's own diagnostic record.
+
+ARMAN, 2026-08-23, on the Agent Foundry failure that produced this node:
+
+    "we need to trigger some sort of node that is going to write to a
+     persistent place and render a very loud error… we need to give users a
+     way to be able to track their own internal logs and problems… a place
+     where you can pass it whatever thing you want, and then it will write to
+     the database in a table that can later be used to diagnose problems that
+     happened within a workflow that you were able to work around, but should
+     never have happened."
+
+Nothing on the platform could do this. A workflow that hit a serious problem
+and recovered from it had exactly two options — fail the whole run, or say
+nothing at all. The Foundry took the second: both Component Artisans refused
+to build a component, each for a correct and well-argued reason, and the run
+reported `completed` with no component and no trace of why. The diagnosis was
+sitting in an agent's prose and nothing was ever going to read it.
+
+WHY THIS IS NOT `system_error`
+------------------------------
+Workflows are authored by USERS. A node that wrote into the platform's own
+error queue would let any author inject rows into our operational alarm
+surface — noise at best, a channel for abuse at worst. `workflow.run_log` is
+the user's own diagnostic table: org-scoped, readable by the run's owner
+(`ledger` RLS variant), written only by the server. Genuine PLATFORM defects
+still go to `system_error` through the server's own paths; this is for
+"something happened inside MY workflow that shouldn't have."
+
+WHAT MAKES IT USEFUL RATHER THAN A SHRUG
+----------------------------------------
+* **`label` is a stable key, `message` is the sentence.** Grouping "this
+  happened 40 times" needs a key that does not embed a run id or a timestamp;
+  explaining it to a human needs a sentence. Asking one field to be both gives
+  a table you cannot query and prose you cannot read.
+* **`payload` takes whatever you have** — and `payload_kind` records what that
+  was, when it is a registered kind. A diagnostic that throws away the
+  evidence is a log line, not a record.
+* **The node never fails the run.** It exists for the case where the workflow
+  DID work around the problem. A recorder that can break the run it is
+  reporting on would make authors stop reaching for it, which is the only way
+  this node can truly fail.
+* **It returns a typed receipt** (`run_log_entry`), not prose — so a
+  downstream step can branch on `recorded` and the run can prove it told
+  somebody.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, ClassVar, Literal
+
+from pydantic import BaseModel, ConfigDict, Field, JsonValue
+
+from matrx_graph.types.context import NodeExecutionContext
+from matrx_graph.types.handle import HandleDirection, HandleSpec
+from matrx_graph.types.node_spec import NodeSpec
+from matrx_graph.types.primitives import ActionTier, NodeCategory
+from matrx_graph.types.result import NodeResult, success
+from matrx_graph.types.usl import field_extras
+
+log = logging.getLogger(__name__)
+
+Severity = Literal["debug", "info", "warning", "error", "critical"]
+
+#: Mirrors the `run_log_severity_check` CHECK constraint. A closed, code-level
+#: vocabulary (db-rules §0.4) — adding a sixth is a deliberate migration, not a
+#: row somebody types.
+SEVERITIES: tuple[str, ...] = ("debug", "info", "warning", "error", "critical")
+
+#: One record is a diagnostic; ten thousand is an outage in the logger. A run
+#: that trips this is looping, and the cap makes that visible instead of
+#: filling the table.
+MAX_ENTRIES_PER_RUN = 200
+
+#: Payloads are evidence, not archives. Anything past this is truncated with a
+#: marker rather than refused — losing the record because the evidence was fat
+#: is the wrong trade.
+MAX_PAYLOAD_CHARS = 100_000
+
+
+class RecordIssueInput(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    label: str = Field(
+        min_length=1,
+        max_length=200,
+        description=(
+            "A short, STABLE name for this problem — the same words every time "
+            "it happens (e.g. 'component_not_written'). This is what lets you "
+            "ask 'how often does this happen?' later."
+        ),
+        json_schema_extra=field_extras(widget="text", placeholder="component_not_written"),
+    )
+    message: str = Field(
+        default="",
+        description=(
+            "What happened, in a sentence a person can read. Defaults to the "
+            "label when you have nothing more to say."
+        ),
+        json_schema_extra=field_extras(widget="textarea", multiline_rows=2),
+    )
+    # NULLABLE ON PURPOSE. A non-null default here is indistinguishable from
+    # the author choosing "warning", so `inputs.severity or config.severity`
+    # made the step's own configured severity unreachable — caught on the
+    # first live run, which recorded a 'warning' for a step configured
+    # 'error'. Absence must be representable wherever a config can override.
+    severity: Severity | None = Field(
+        default=None,
+        description=(
+            "How bad it is. 'warning' = the workflow carried on but something "
+            "was wrong; 'error'/'critical' = the result is compromised even "
+            "though the run continued. Falls back to the step's configured "
+            "severity."
+        ),
+        json_schema_extra=field_extras(widget="select"),
+    )
+    payload: JsonValue = Field(
+        default=None,
+        description=(
+            "Anything you want kept as evidence — the agent's own answer, the "
+            "value that failed, the step's inputs. Stored verbatim."
+        ),
+        json_schema_extra=field_extras(widget="json"),
+    )
+    payload_kind: str | None = Field(
+        default=None,
+        description=(
+            "The registered Shape of the evidence, when it has one — so the "
+            "record renders through that Shape's component later instead of a "
+            "key/value dump."
+        ),
+    )
+
+
+class RunLogEntry(BaseModel):
+    """The receipt. Mirrored by the registered ``run_log_entry`` kind."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    recorded: bool = Field(
+        description=(
+            "True when the record landed in the database. FALSE means the "
+            "problem happened AND we failed to write it down — branch on this."
+        )
+    )
+    entry_id: str | None = Field(default=None, description="The workflow.run_log row id.")
+    label: str = ""
+    severity: str = "warning"
+    message: str = ""
+    occurred_at: str | None = None
+    #: Populated only when `recorded` is false — why the write did not land.
+    not_recorded_reason: str | None = None
+
+
+class RecordIssueConfig(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    label: str = Field(
+        default="",
+        description=(
+            "Author-time label, used when the step is not given one at run "
+            "time. The input wins when both are present."
+        ),
+        json_schema_extra=field_extras(widget="text"),
+    )
+    severity: Severity = Field(
+        default="warning",
+        json_schema_extra=field_extras(widget="select"),
+    )
+
+
+#: Per-run entry counters, process-local. A hard cap needs no durability: the
+#: point is to stop one runaway loop from writing a million rows in one
+#: process, and a restart legitimately starts a fresh budget.
+_entry_counts: dict[str, int] = {}
+
+
+def _truncate(value: JsonValue) -> tuple[JsonValue, bool]:
+    import json
+
+    try:
+        rendered = json.dumps(value, default=str)
+    except Exception:  # noqa: BLE001 — evidence is never worth an exception
+        return {"unserializable": repr(value)[:2000]}, True
+    if len(rendered) <= MAX_PAYLOAD_CHARS:
+        return value, False
+    return {
+        "truncated": True,
+        "original_chars": len(rendered),
+        "preview": rendered[:MAX_PAYLOAD_CHARS],
+    }, True
+
+
+class RecordIssueExecutor:
+    """Write one diagnostic row. Never fails the run."""
+
+    spec: ClassVar[NodeSpec] = NodeSpec(
+        type="log.record",
+        category=NodeCategory.DATA,
+        display_name="Record a Problem",
+        description=(
+            "Write down something that went wrong, with whatever evidence you "
+            "have, so you can find it later. The workflow keeps going."
+        ),
+        input_schema=RecordIssueInput,
+        output_schema=RunLogEntry,
+        config_schema=RecordIssueConfig,
+        handles=(
+            HandleSpec(id="in", direction=HandleDirection.INPUT, required=False),
+            HandleSpec(id="out", direction=HandleDirection.OUTPUT, required=False),
+        ),
+        determinism=ActionTier.SIDE_EFFECT,
+        icon="clipboard-alert",
+        output_kind="run_log_entry",
+    )
+
+    async def execute(
+        self,
+        ctx: NodeExecutionContext,
+        inputs: RecordIssueInput,
+        config: RecordIssueConfig,
+    ) -> NodeResult[RunLogEntry]:
+        label = (inputs.label or config.label or "").strip() or "unlabelled_issue"
+        severity = inputs.severity or config.severity or "warning"
+        message = (inputs.message or "").strip() or label
+
+        seen = _entry_counts.get(ctx.run_id, 0)
+        if seen >= MAX_ENTRIES_PER_RUN:
+            # Loud once, then quiet — a capped logger that keeps logging its
+            # own cap is the same runaway with extra steps.
+            if seen == MAX_ENTRIES_PER_RUN:
+                _entry_counts[ctx.run_id] = seen + 1
+                log.error(
+                    "[wf:%s] log.record hit %d entries — capping. The run is looping on '%s'.",
+                    ctx.run_id[:8],
+                    MAX_ENTRIES_PER_RUN,
+                    label,
+                )
+            return success(
+                RunLogEntry(
+                    recorded=False,
+                    label=label,
+                    severity=severity,
+                    message=message,
+                    not_recorded_reason=(
+                        f"this run already recorded {MAX_ENTRIES_PER_RUN} entries"
+                    ),
+                )
+            )
+        _entry_counts[ctx.run_id] = seen + 1
+
+        payload, truncated = _truncate(inputs.payload)
+        if truncated:
+            message = f"{message} (evidence truncated)"
+
+        try:
+            from datetime import UTC, datetime
+
+            from matrx_graph.db._registry import get_model
+
+            # THE ORG IS THE RUN'S, not whatever AppContext happens to carry.
+            # An explicit organization is required on every write and the
+            # database never chooses one (db-rules §0.9) — but the authority
+            # here is the run row, which always has one (verified live: 87/87
+            # runs over three days). Reading it off AppContext refused to
+            # write on the very first real run, because a background/detached
+            # workflow context legitimately carries no org.
+            definition_id: str | None = None
+            org: str | None = None
+            run_rows = await (
+                get_model("WfRun").filter(id=ctx.run_id).values("definition_id", "organization_id")
+            )
+            if run_rows:
+                raw_def = run_rows[0].get("definition_id")
+                definition_id = str(raw_def) if raw_def else None
+                raw_org = run_rows[0].get("organization_id")
+                org = str(raw_org) if raw_org else None
+            org = org or ctx.organization_id
+            if not org:
+                return success(
+                    RunLogEntry(
+                        recorded=False,
+                        label=label,
+                        severity=severity,
+                        message=message,
+                        not_recorded_reason=(
+                            "neither the run row nor the request carries an "
+                            "organization — refusing to let the database guess one"
+                        ),
+                    )
+                )
+
+            now = datetime.now(UTC)
+            row: Any = await get_model("WfRunLog").create_item(
+                run_id=ctx.run_id,
+                definition_id=definition_id,
+                node_id=ctx.node_id,
+                step=ctx.step,
+                attempt=ctx.attempt,
+                severity=severity,
+                label=label,
+                message=message,
+                payload={"value": payload} if not isinstance(payload, dict) else payload,
+                payload_kind=(inputs.payload_kind or "").strip() or None,
+                occurred_at=now,
+                organization_id=str(org),
+                created_by=str(ctx.user_id) if ctx.user_id else None,
+            )
+            entry_id = str(getattr(row, "id", "") or "") or None
+
+            # LOUD on the server too. The row is the durable record; this line
+            # is what an operator greps at 3am before anybody opens a board.
+            log.warning(
+                "[wf:%s node=%s] RUN LOG %s — %s: %s (entry %s)",
+                ctx.run_id[:8],
+                ctx.node_id,
+                severity.upper(),
+                label,
+                message[:300],
+                entry_id,
+            )
+            return success(
+                RunLogEntry(
+                    recorded=True,
+                    entry_id=entry_id,
+                    label=label,
+                    severity=severity,
+                    message=message,
+                    occurred_at=now.isoformat(),
+                )
+            )
+        except Exception as exc:  # noqa: BLE001 — the recorder never fails the run
+            log.exception(
+                "[wf:%s node=%s] log.record could NOT write '%s'",
+                ctx.run_id[:8],
+                ctx.node_id,
+                label,
+            )
+            return success(
+                RunLogEntry(
+                    recorded=False,
+                    label=label,
+                    severity=severity,
+                    message=message,
+                    not_recorded_reason=f"{type(exc).__name__}: {exc}"[:500],
+                )
+            )

{matrx_graph-0.2.76 → matrx_graph-0.2.78}/matrx_graph/nodes/output/FEATURE.md

@@ -7,7 +7,9 @@ Verified against `to_frontend.py`, `matrx_graph/types/events.py`
 One node: `output.to_frontend` ("Show on Screen"). It fires a non-blocking
 `node_emitted` event (recorded in `workflow.node_events`, so a re-opened run
 re-renders it) and passes its input through UNCHANGED — it sits on any edge
-without altering routing, and declares no `output_kind` (runtime `__kind`
+without altering routing, and declares no `output_kind` — it declares
+`dynamic_output=True` instead (2026-08-23, GAP 2: the honest posture is a
+DECLARATION, not silence), so runtime `__kind`
 propagation carries the payload's identity). Emission failures are logged,
 never load-bearing — the `ctx.progress` contract.