iCode-TUI 0.29.1__py3-none-any.whl

chrys/service/workflows/orphans.py

@@ -0,0 +1,209 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Restore-only repair of interrupted runs; the log alone owns terminal facts.
+
+A read-only tail check skips finished runs. Unfinished logs are rechecked under
+one reconciliation lock through the descriptor that receives the orphan terminal.
+Torn tails are separated before append. No recovery events are published live.
+"""
+
+from __future__ import annotations
+
+import errno
+import logging
+import os
+from collections.abc import Iterable, Iterator
+from dataclasses import dataclass
+from pathlib import Path
+from typing import BinaryIO, Final
+
+from chrys.foundation.platform.files import secure_open_owner_only_append, secure_open_owner_verified_binary
+from chrys.foundation.trajectory.envelope import (
+    EnvelopeError,
+    EventDraft,
+    TrajectoryEvent,
+    build_event,
+    decode_event_line,
+    encode_event_line,
+    peek_envelope_header,
+)
+from chrys.foundation.trajectory.ids import new_analytics_id
+from chrys.foundation.util.lock import FileLock
+from chrys.service.workflows.layout import EVENTS_FILE, iter_run_dirs
+from chrys.service.workflows.outcomes import ORPHAN_REASON_PROCESS_TERMINATED, RunOutcome
+from chrys.service.workflows.store import WORKFLOW_EVENT_TYPES, RunRecord, RunTerminal, read_run_header
+
+logger = logging.getLogger(__name__)
+
+MAX_EVENTS_BYTES: Final = 256 * 1024 * 1024
+"""Bounds reverse scanning, including malformed or sparse files, without allocating the whole log."""
+_TAIL_BLOCK_BYTES: Final = 64 * 1024
+RECONCILE_LOCK_FILE: Final = ".reconcile.lock"
+RECONCILE_LOCK_TIMEOUT: Final = 30.0  # seconds
+
+
+@dataclass(frozen=True, slots=True)
+class OrphanReconciliation:
+    """What one pass did: runs given a terminal, runs already terminal, runs it could not judge."""
+
+    reconciled: tuple[str, ...] = ()
+    already_finished: tuple[str, ...] = ()
+    skipped: tuple[str, ...] = ()
+    truncated: bool = False
+
+
+def reconcile_orphaned_runs(session_dir: Path) -> OrphanReconciliation:
+    """Give every unfinished run under *session_dir* its ``orphaned`` terminal; idempotent."""
+    run_dirs, truncated = iter_run_dirs(session_dir)
+    reconciled: list[str] = []
+    finished: list[str] = []
+    skipped: list[str] = []
+    for run_dir in run_dirs:
+        try:
+            outcome = _reconcile_run(run_dir)
+        except OSError, ValueError:  # EnvelopeError is a ValueError
+            if not run_dir.exists():  # the session was deleted under a reconciliation a cancelled restore left running
+                logger.debug("workflow run %s was deleted during reconciliation", run_dir.name)
+            else:
+                logger.warning("workflow run %s could not be reconciled", run_dir.name, exc_info=True)
+            skipped.append(run_dir.name)
+            continue
+        (reconciled if outcome else finished).append(run_dir.name)
+    return OrphanReconciliation(tuple(reconciled), tuple(finished), tuple(skipped), truncated)
+
+
+def read_run_terminal(run_dir: Path) -> RunTerminal | None:
+    """Read a durable terminal without repairing files or acquiring the session's execution lock."""
+    try:
+        with secure_open_owner_verified_binary(run_dir / EVENTS_FILE) as handle:
+            _last, record = _last_complete(_reverse_complete_lines(handle))
+    except OSError as exc:
+        if exc.errno == errno.ENOENT:
+            return None
+        raise
+    return _terminal(record) if record is not None and record.event_type == RunRecord.RUN_FINISHED else None
+
+
+def _reverse_complete_lines(handle: BinaryIO) -> Iterator[bytes]:
+    """Scan backward from one EOF snapshot; ignore its torn tail, and stop on demand.
+
+    Only a line crossing block boundaries is retained. The existing ceiling
+    bounds pathological scans, not file size: a large live log needs one tail
+    block in the ordinary case. Joining a split line once avoids quadratic
+    copying for large records.
+    """
+    position = handle.seek(0, os.SEEK_END)
+    scanned = 0
+    fragments: list[bytes] = []
+    torn_tail = True
+    while position:
+        if scanned == MAX_EVENTS_BYTES:
+            raise ValueError(f"{EVENTS_FILE} tail exceeds the {MAX_EVENTS_BYTES}-byte scan ceiling")
+        length = min(position, _TAIL_BLOCK_BYTES, MAX_EVENTS_BYTES - scanned)
+        position -= length
+        handle.seek(position)
+        pieces = handle.read(length).split(b"\n")
+        scanned += length
+        for piece in reversed(pieces[1:]):
+            if torn_tail:
+                torn_tail = False
+            else:
+                yield piece + b"".join(reversed(fragments))
+            fragments.clear()
+        if not torn_tail:
+            fragments.append(pieces[0])
+    if not torn_tail:
+        yield b"".join(reversed(fragments))
+
+
+def _terminal(record: TrajectoryEvent) -> RunTerminal:
+    reason = record.payload.get("reason")
+    return RunTerminal(
+        outcome=str(record.payload.get("outcome", "")),
+        last_seq=record.sequence,
+        reason=reason if isinstance(reason, str) else "",
+        finished_at=record.occurred_at,
+    )
+
+
+def _reconcile_run(run_dir: Path) -> bool:
+    """Append once, without creating any directories if deletion races restoration."""
+    if read_run_terminal(run_dir) is not None:
+        return False
+    with FileLock(run_dir / RECONCILE_LOCK_FILE, timeout=RECONCILE_LOCK_TIMEOUT):
+        return _reconcile_run_locked(run_dir)
+
+
+def _reconcile_run_locked(run_dir: Path) -> bool:
+    header = read_run_header(run_dir)
+    run_id = header.get("run_id")
+    session_id = header.get("session_id")
+    if not isinstance(run_id, str) or not run_id or not isinstance(session_id, str):
+        raise ValueError("run header lacks its identity")
+    events_path = run_dir / EVENTS_FILE
+    handle = secure_open_owner_only_append(events_path)
+    try:
+        # Read through the descriptor being appended to: the file examined is the file written.
+        with os.fdopen(os.dup(handle.fd), "rb") as reader:
+            last, last_record = _last_complete(_reverse_complete_lines(reader))
+            if last_record is not None and last_record.event_type == RunRecord.RUN_FINISHED:
+                return False
+            sequence = (last.sequence if last is not None else _highest_sequence(_reverse_complete_lines(reader))) + 1
+            size = reader.seek(0, os.SEEK_END)
+            if size:
+                reader.seek(-1, os.SEEK_END)
+            tail = bool(size and reader.read(1) != b"\n")
+        draft = EventDraft(
+            event_type=RunRecord.RUN_FINISHED,
+            payload={"outcome": RunOutcome.ORPHANED.value, "reason": ORPHAN_REASON_PROCESS_TERMINATED},
+        )
+        event = build_event(
+            draft,
+            sequence=sequence,
+            runtime_id=run_id,
+            coverage_id=last.coverage_id if last is not None else new_analytics_id(),
+            session_id=session_id,
+            branch_id=last.branch_id if last is not None else new_analytics_id(),
+        )
+        line = (b"\n" if tail else b"") + encode_event_line(event)
+        _write_all(handle.fd, line)
+        os.fsync(handle.fd)
+    finally:
+        os.close(handle.fd)
+    return True
+
+
+def _last_complete(lines: Iterable[bytes]) -> tuple[TrajectoryEvent | None, TrajectoryEvent | None]:
+    """Read newest-first lines for the last envelope and last workflow record.
+
+    The two differ when the store closed its writer after the terminal: the
+    runtime markers that follow ``workflow.log.run.finished`` are the writer's,
+    not the run's.
+    """
+    last: TrajectoryEvent | None = None
+    for raw in lines:
+        try:
+            event = decode_event_line(raw)
+        except EnvelopeError:
+            continue
+        if last is None:
+            last = event
+        if event.event_type in WORKFLOW_EVENT_TYPES:
+            return last, event
+    return last, None
+
+
+def _highest_sequence(lines: Iterable[bytes]) -> int:
+    highest = 0
+    for raw in lines:
+        header = peek_envelope_header(raw)
+        if header is not None:
+            highest = max(highest, header.sequence)
+    return highest
+
+
+def _write_all(fd: int, data: bytes) -> None:
+    view = memoryview(data)
+    while view:
+        written = os.write(fd, view)
+        view = view[written:]

chrys/service/workflows/outcomes.py

@@ -0,0 +1,46 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Run outcomes, cancellation reasons and their presentation status."""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Final, Literal
+
+
+class RunOutcome(Enum):
+    """Terminal outcomes, including restore-only orphan reconciliation."""
+
+    COMPLETED = "completed"
+    NODE_FAILED = "node_failed"
+    LOOP_EXHAUSTED = "loop_exhausted"
+    CANCELLED = "cancelled"
+    WORKER_LOST = "worker_lost"
+    STORAGE_FAILED = "storage_failed"
+    ORPHANED = "orphaned"
+
+
+REASON_DEADLINE_EXCEEDED: Final = "deadline_exceeded"
+"""``WorkflowRunFinished.reason`` when the run-level timeout cancelled the run."""
+REASON_SHUTDOWN: Final = "shutdown"
+"""``WorkflowRunFinished.reason`` when the owning engine shut down under the run."""
+REASON_INTERNAL_ERROR: Final = "internal_error"
+"""``WorkflowRunFinished.reason`` when the runner itself failed and cancelled the run to converge it."""
+ORPHAN_REASON_PROCESS_TERMINATED: Final = "process_terminated"
+
+type RunStatus = Literal["running", "completed", "failed", "cancelled", "interrupted"]
+
+
+def run_status(outcome: str | None, reason: str | None, *, active: bool) -> RunStatus:
+    """Project stored or live outcome facts to the status shown in history."""
+    if outcome == RunOutcome.COMPLETED.value:
+        return "completed"
+    if outcome == RunOutcome.CANCELLED.value:
+        if reason in {REASON_DEADLINE_EXCEEDED, REASON_INTERNAL_ERROR}:
+            return "failed"
+        return "interrupted" if reason == REASON_SHUTDOWN else "cancelled"
+    if outcome == RunOutcome.ORPHANED.value:
+        return "interrupted"
+    if outcome:
+        return "failed"
+    return "running" if active else "interrupted"

chrys/service/workflows/protocol.py

@@ -0,0 +1,210 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Wire contract between the main process and a workflow worker host.
+
+Newline-framed JSON over the worker's stdio. The main process owns stdin/stdout
+of the child: every frame the child writes is protocol, and the host moves the
+user's ``fd 1``/``fd 2`` elsewhere before any user code runs. The two sides use
+disjoint request-id spaces (main odd from 1, worker even from 2), so one reader
+per side can demultiplex responses by id without agreement on ordering.
+
+The host is a standalone stdlib file that cannot import this module; it carries
+its own copy of the names below, and ``tests/service/workflows/test_protocol.py``
+pins the two copies to each other.
+
+Frames:
+
+* request      ``{"id": int, "method": str, "params": {...}}``
+* response     ``{"id": int, "result": {...}}`` or ``{"id": int, "error": {"code", "message", "data"}}``
+* notification ``{"method": str, "params": {...}}``
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping
+from dataclasses import dataclass
+from enum import StrEnum
+from typing import Any, Final
+
+from chrys.service.workflows.scheduler import AttemptRef
+
+PROTOCOL_VERSION: Final = 2
+PYTHON_FLOOR: Final = (3, 9)
+"""Oldest interpreter that can run the host and the injected SDK."""
+
+
+class Method(StrEnum):
+    """Every method name on the wire."""
+
+    # worker → main, first frame
+    HELLO = "hello"
+    # main → worker requests
+    LOAD = "load"
+    RUN_PYTHON = "run_python"
+    EVAL_OUTGOING = "eval_outgoing"
+    EVAL_LOOP_UNTIL = "eval_loop_until"
+    COMBINE = "combine"
+    CANCEL = "cancel"
+    NATIVE_OUTPUT = "native_output"
+    SHUTDOWN = "shutdown"
+    # worker → main during an attempt
+    ASK = "ask"
+    EMIT = "emit"
+
+
+class ErrorCode(StrEnum):
+    """Worker failure codes; the runner maps attempt failures onto scheduler retry classes."""
+
+    USER_EXCEPTION = "user_exception"
+    VALUE_NOT_SERIALIZABLE = "value_not_serializable"
+    VALUE_TOO_LARGE = "value_too_large"
+    PROTOCOL_LIMIT = "protocol_limit"
+    ASK_UNAVAILABLE = "ask_unavailable"
+    ATTEMPT_TERMINATED = "attempt_terminated"
+    LOAD_FAILED = "load_failed"
+    INVALID_PARAMS = "invalid_params"
+    UNKNOWN_METHOD = "unknown_method"
+    INTERNAL = "internal"
+
+
+_MIB = 1024 * 1024
+
+
+@dataclass(frozen=True, slots=True)
+class ProtocolLimits:
+    """Resource bounds and deadlines shared with the standalone worker."""
+
+    # one frame, either direction; a larger value is value_too_large, any other frame protocol_limit
+    max_frame_bytes: int = 16 * _MIB
+    # WorkflowValue.data shape: nesting depth, total containers + scalars, one string's length
+    max_payload_depth: int = 64
+    max_payload_items: int = 200_000
+    max_string_chars: int = 4 * _MIB
+    # main → worker requests in flight
+    max_pending_requests: int = 256
+    # both directions, per run; exceeding either is a worker_lost-class failure
+    max_run_frames: int = 1_000_000
+    max_run_bytes: int = 4 * 1024 * _MIB
+    # join sources kept in memory for one combine call
+    max_join_retained_bytes: int = 12 * _MIB
+    # ctx.emit per attempt: sliding one-second rate, count, and bytes
+    emit_rate_per_s: int = 200
+    max_emits_per_attempt: int = 10_000
+    max_emit_bytes_per_attempt: int = 8 * _MIB
+    # main-side deadline in seconds for eval_outgoing / eval_loop_until / combine
+    eval_deadline: float = 30.0
+    # sync bodies and default-executor offloads; evaluations have their own pool
+    worker_thread_pool_size: int = 8
+    eval_thread_pool_size: int = 2
+    # cumulative abandoned work, attributed by the worker to the pool that actually owns it
+    worker_leak_budget: int = 8
+    eval_leak_budget: int = 2
+    load_timeout: float = 60.0  # seconds; includes executing the module and building its manifest
+    hello_timeout: float = 15.0  # seconds
+    shutdown_grace: float = 3.0  # seconds
+    # after cancelling an async body the host waits this many seconds for it to unwind before acknowledging;
+    # a body that keeps swallowing the cancellation is reported like a leaked thread
+    cancel_drain: float = 1.0
+    # captured sys.stdout/sys.stderr per attempt, and the run-level native tail
+    captured_output_bytes: int = 64 * 1024
+    native_output_tail_bytes: int = 64 * 1024
+
+
+LIMITS: Final = ProtocolLimits()
+
+
+class ProtocolError(ValueError):
+    """A frame that does not fit the contract; the connection is not recoverable."""
+
+
+def encode_frame(frame: Mapping[str, Any]) -> bytes:
+    """Serialize one frame; raises :class:`ProtocolError` above the frame cap.
+
+    Frames carry filesystem identity (the entry path and the workspace, which on
+    POSIX may hold surrogateescaped bytes), so every str must survive the byte
+    form unchanged: lone surrogates pass through. Whether a *value* is valid
+    Unicode is the value layer's rule, checked where the value is produced.
+    """
+    line = json.dumps(frame, ensure_ascii=False, sort_keys=True, separators=(",", ":"), allow_nan=False)
+    data = line.encode("utf-8", "surrogatepass") + b"\n"
+    if len(data) > LIMITS.max_frame_bytes:
+        raise ProtocolError(f"frame of {len(data)} bytes exceeds max_frame_bytes.")
+    return data
+
+
+def decode_frame(line: bytes) -> dict[str, Any]:
+    """Parse one line into a frame dict, validating the envelope shape only."""
+    if len(line) > LIMITS.max_frame_bytes:
+        raise ProtocolError(f"frame of {len(line)} bytes exceeds max_frame_bytes.")
+    try:
+        frame = json.loads(line.decode("utf-8", "surrogatepass"))
+    except (UnicodeDecodeError, ValueError) as exc:
+        raise ProtocolError(f"frame is not UTF-8 JSON: {exc}") from exc
+    if not isinstance(frame, dict):
+        raise ProtocolError("frame is not a JSON object.")
+    if "id" in frame:
+        if not isinstance(frame["id"], int) or isinstance(frame["id"], bool) or frame["id"] < 1:
+            raise ProtocolError("frame id must be a positive int.")
+        if "method" in frame:
+            _check_request(frame)
+        elif ("result" in frame) == ("error" in frame):
+            raise ProtocolError("response carries exactly one of result/error.")
+        elif "error" in frame:
+            _check_error(frame["error"])
+        elif not isinstance(frame["result"], dict):
+            raise ProtocolError("response result must be an object.")
+    else:
+        _check_request(frame)
+    return frame
+
+
+def _check_request(frame: dict[str, Any]) -> None:
+    if not isinstance(frame.get("method"), str) or not frame["method"]:
+        raise ProtocolError("request method must be a non-empty string.")
+    if not isinstance(frame.get("params"), dict):
+        raise ProtocolError("request params must be an object.")
+
+
+def _check_error(error: Any) -> None:
+    if (
+        not isinstance(error, dict)
+        or not isinstance(error.get("code"), str)
+        or not isinstance(error.get("message"), str)
+    ):
+        raise ProtocolError("error must carry a string code and message.")
+    if not isinstance(error.get("data", {}), dict):
+        raise ProtocolError("error data must be an object.")
+
+
+def ref_to_wire(ref: AttemptRef) -> dict[str, Any]:
+    return {
+        "run_id": ref.run_id,
+        "node_id": ref.node_id,
+        "activation_id": ref.activation_id,
+        "attempt": ref.attempt,
+    }
+
+
+def ref_from_wire(payload: Any) -> AttemptRef:
+    if not isinstance(payload, dict):
+        raise ProtocolError("ref must be an object.")
+    try:
+        run_id, node_id, activation_id, attempt = (
+            payload["run_id"],
+            payload["node_id"],
+            payload["activation_id"],
+            payload["attempt"],
+        )
+    except KeyError as exc:
+        raise ProtocolError(f"ref is missing {exc.args[0]!r}.") from exc
+    if not all(isinstance(part, str) and part for part in (run_id, node_id, activation_id)):
+        raise ProtocolError("ref ids must be non-empty strings.")
+    if not isinstance(attempt, int) or isinstance(attempt, bool) or attempt < 1:
+        raise ProtocolError("ref attempt must be an int >= 1.")
+    return AttemptRef(run_id=run_id, node_id=node_id, activation_id=activation_id, attempt=attempt)
+
+
+def ref_key(ref: AttemptRef) -> str:
+    """The wire identity of an attempt: what the fence on both sides keys on."""
+    return f"{ref.run_id}|{ref.node_id}|{ref.activation_id}|{ref.attempt}"

chrys/service/workflows/records.py

@@ -0,0 +1,142 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Service-owned conversion from immutable run artifacts and log records to lifecycle facts."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+from chrys.foundation.events import types as events
+from chrys.foundation.events.workflow import WorkflowRunEvent
+from chrys.foundation.models.ask_user import AskUserQuestion
+from chrys.foundation.trajectory.envelope import TrajectoryEvent
+from chrys.foundation.util.time import parse_created_at
+from chrys.service.state.workflow import decode_workflow_model
+from chrys.service.workflows.layout import OUTPUT_INDEX_FILE
+from chrys.service.workflows.store import (
+    MAX_OUTPUT_INDEX_BYTES,
+    RunRecord,
+    read_json_object,
+    read_run_header,
+    read_run_input,
+    read_run_spec,
+)
+
+
+def record_timestamp(value: object) -> datetime:
+    parsed = parse_created_at(value)
+    return parsed if parsed is not None and parsed.tzinfo is not None else datetime(1970, 1, 1, tzinfo=UTC)
+
+
+def run_started_event(
+    header: Mapping[str, Any], spec: Mapping[str, Any], input_text: str, *, seq: int = 0
+) -> events.WorkflowRunStarted:
+    """The same start fact for live publication and historical replay."""
+    return events.WorkflowRunStarted(
+        seq=seq,
+        run_id=header["run_id"],
+        session_id=header["session_id"],
+        input_text=input_text,
+        workflow_id=header["workflow_id"],
+        source_kind=header["source_kind"],
+        canonical_path=header["canonical_path"],
+        title=header["title"],
+        spec_digest=header["spec_digest"],
+        manifest=dict(spec["manifest"]),
+        resolved_nodes=[dict(node) for node in spec["resolved_nodes"]],
+        model=decode_workflow_model(header["model"]),
+        timestamp=record_timestamp(header["started_at"]),
+    )
+
+
+def read_run_started(directory: Path, *, seq: int = 0) -> events.WorkflowRunStarted:
+    return run_started_event(read_run_header(directory), read_run_spec(directory), read_run_input(directory), seq=seq)
+
+
+def decode_run_event(record: TrajectoryEvent, *, directory: Path) -> WorkflowRunEvent | None:
+    """Decode the run-log namespace; trajectory runtime markers have no workflow projection."""
+    kind, payload = record.event_type, record.payload
+    if kind == RunRecord.RUN_STARTED:
+        return read_run_started(directory, seq=record.sequence)
+    common: dict[str, Any] = {
+        "run_id": record.runtime_id,
+        "session_id": record.session_id,
+        "seq": record.sequence,
+        "timestamp": record_timestamp(record.occurred_at),
+    }
+    if kind in {
+        RunRecord.NODE_STATE,
+        RunRecord.NODE_OUTPUT,
+        RunRecord.NODE_ASK,
+        RunRecord.NODE_ANSWER,
+        RunRecord.LOOP_ITERATION,
+        RunRecord.RUN_NOTICE,
+    }:
+        ref = {"activation_id": payload["activation"], "attempt": payload["attempt"]}
+        if kind == RunRecord.LOOP_ITERATION:
+            return events.WorkflowLoopIteration(
+                **common, **ref, loop_id=payload["node"], iteration=payload["iteration"], verdict=payload["verdict"]
+            )
+        ref["node_id"] = payload["node"]
+        if kind == RunRecord.NODE_STATE:
+            return events.WorkflowNodeStateChanged(
+                **common,
+                **ref,
+                state=payload["state"],
+                iteration=payload["iteration"],
+                failure_phase=payload["failure_phase"],
+                invocation_id=payload.get("invocation", ""),
+                error=payload.get("error", ""),
+                error_class=payload.get("error_class", ""),
+            )
+        if kind == RunRecord.NODE_OUTPUT:
+            return events.WorkflowNodeOutput(
+                **common, **ref, kind=payload["kind"], ordinal=payload["ordinal"], summary_text=payload["summary"]
+            )
+        if kind == RunRecord.NODE_ASK:
+            # Only the bounded summary is stored: a replayed ask is that summary as one open question.
+            question = AskUserQuestion(question=payload["prompt"])
+            return events.WorkflowNodeAskUser(**common, **ref, request_id=payload["request"], questions=(question,))
+        if kind == RunRecord.NODE_ANSWER:
+            return events.WorkflowNodeAnswered(**common, **ref, request_id=payload["request"], answer=payload["answer"])
+        return events.WorkflowRunNotice(**common, **ref, code=payload["code"], message=payload["message"])
+    if kind == RunRecord.RUN_FINISHED:
+        outputs = payload.get("outputs", [])
+        omitted = payload.get("outputs_omitted", 0)
+        if omitted:
+            try:
+                outputs = read_json_object(directory / OUTPUT_INDEX_FILE, MAX_OUTPUT_INDEX_BYTES)["outputs"]
+                if len(outputs) != omitted:
+                    raise ValueError("Output count does not match the terminal.")
+            except (OSError, ValueError, KeyError, TypeError) as exc:
+                raise ValueError(f"Cannot read workflow output index: {exc}") from exc
+        if not isinstance(outputs, list):
+            raise ValueError("Workflow outputs must be an array.")
+        summaries = []
+        for output in outputs:
+            if (
+                not isinstance(output, dict)
+                or not isinstance(output.get("node"), str)
+                or not isinstance(output.get("activation"), str)
+                or type(output.get("attempt")) is not int
+                or output["attempt"] < 0
+            ):
+                raise ValueError("Invalid workflow output identity in terminal or output index.")
+            summaries.append(
+                events.WorkflowOutputSummary(
+                    node_id=output["node"], activation_id=output["activation"], attempt=output["attempt"]
+                )
+            )
+        return events.WorkflowRunFinished(
+            **common,
+            outcome=payload["outcome"],
+            outputs=summaries,
+            error=payload.get("error", ""),
+            duration=payload.get("duration", 0),
+            reason=payload.get("reason", ""),
+            node_id=payload.get("node", ""),
+        )
+    return None