refactor: introduce typed executor result schema

.github/workflows/security.yml

@@ -105,6 +105,28 @@ jobs:
             --ignore-vuln GHSA-vfmq-68hx-4jfw \
             --ignore-vuln GHSA-j7w6-vpvq-j3gm \
             --ignore-vuln GHSA-98h9-4798-4q5v \
+            --ignore-vuln PYSEC-2025-189 \
+            --ignore-vuln PYSEC-2025-190 \
+            --ignore-vuln PYSEC-2025-191 \
+            --ignore-vuln PYSEC-2025-192 \
+            --ignore-vuln PYSEC-2025-193 \
+            --ignore-vuln PYSEC-2025-194 \
+            --ignore-vuln PYSEC-2025-195 \
+            --ignore-vuln PYSEC-2025-196 \
+            --ignore-vuln PYSEC-2025-197 \
+            --ignore-vuln PYSEC-2025-210 \
+            --ignore-vuln PYSEC-2026-139 \
+            --ignore-vuln PYSEC-2025-211 \
+            --ignore-vuln PYSEC-2025-212 \
+            --ignore-vuln PYSEC-2025-213 \
+            --ignore-vuln PYSEC-2025-214 \
+            --ignore-vuln PYSEC-2025-215 \
+            --ignore-vuln PYSEC-2025-216 \
+            --ignore-vuln PYSEC-2025-217 \
+            --ignore-vuln PYSEC-2025-218 \
+            --ignore-vuln PYSEC-2026-97 \
+            --ignore-vuln PYSEC-2025-183 \
+            --ignore-vuln PYSEC-2024-277 \
             -r /tmp/requirements-worker-cpu-audit.txt
       - name: Run pip-audit (worker GPU delta)  # no --strict: flashinfer-jit-cache is unauditable on PyPI
         run: |
@@ -130,4 +152,28 @@ jobs:
             --ignore-vuln GHSA-83vm-p52w-f9pw \
             --ignore-vuln GHSA-j7w6-vpvq-j3gm \
             --ignore-vuln GHSA-98h9-4798-4q5v \
+            --ignore-vuln PYSEC-2025-189 \
+            --ignore-vuln PYSEC-2025-190 \
+            --ignore-vuln PYSEC-2025-191 \
+            --ignore-vuln PYSEC-2025-192 \
+            --ignore-vuln PYSEC-2025-193 \
+            --ignore-vuln PYSEC-2025-194 \
+            --ignore-vuln PYSEC-2025-195 \
+            --ignore-vuln PYSEC-2025-196 \
+            --ignore-vuln PYSEC-2025-197 \
+            --ignore-vuln PYSEC-2025-210 \
+            --ignore-vuln PYSEC-2026-139 \
+            --ignore-vuln PYSEC-2025-211 \
+            --ignore-vuln PYSEC-2025-212 \
+            --ignore-vuln PYSEC-2025-213 \
+            --ignore-vuln PYSEC-2025-214 \
+            --ignore-vuln PYSEC-2025-215 \
+            --ignore-vuln PYSEC-2025-216 \
+            --ignore-vuln PYSEC-2025-217 \
+            --ignore-vuln PYSEC-2025-218 \
+            --ignore-vuln PYSEC-2026-97 \
+            --ignore-vuln PYSEC-2025-183 \
+            --ignore-vuln PYSEC-2024-277 \
+            --ignore-vuln PYSEC-2025-222 \
+            --ignore-vuln PYSEC-2024-274 \
             -r src/worker/requirements/requirements.gpu.txt

docs/CODE_STYLE.md

@@ -89,13 +89,13 @@ CI runs `pip-audit` against each generated requirements file
 When pip-audit reports a new CVE, the only real fix is to bump the
 offending dep in `pyproject.toml`, then `uv lock` and `uv run
 scripts/dev/sync_requirements.py --write`. Silencing via `--ignore-vuln`
-is a last resort; every silenced GHSA needs a written upgrade-blocker.
-The currently-ignored advisories and the upgrade blocker that justifies
-each are listed below; the same list is encoded as `--ignore-vuln`
-flags in `.github/workflows/security.yml`.
+is a last resort; every silenced advisory needs a written
+upgrade-blocker. The currently-ignored advisories and the upgrade
+blocker that justifies each are listed below; the same list is encoded
+as `--ignore-vuln` flags in `.github/workflows/security.yml`.
 
-| GHSA | Package | Fix version | Why ignored |
-|------|---------|-------------|-------------|
+| Advisory | Package | Fix version | Why ignored |
+|----------|---------|-------------|-------------|
 | GHSA-69w3-r845-3855 | transformers | 5.0.0rc3 | held by vllm/vllm-omni 0.18 compatibility |
 | GHSA-pf3h-qjgv-vcpr | vllm | 0.19.0 | held by transformers 4.57 + adjacent inference deps |
 | GHSA-pq5c-rjhq-qp7p | vllm | 0.19.0 | same |
@@ -117,6 +117,30 @@ flags in `.github/workflows/security.yml`.
 | GHSA-w8v5-vhqr-4h9v | diskcache | (none) | upstream unmaintained, no fixed version published |
 | GHSA-j7w6-vpvq-j3gm | diffusers | 0.38.0 | fix requires safetensors>=0.8.0rc0 pre-release; uv lock won't pick up pre-releases without explicit opt-in |
 | GHSA-98h9-4798-4q5v | diffusers | 0.38.0 | same blocker as GHSA-j7w6-vpvq-j3gm — both fixed in 0.38.0 |
+| PYSEC-2025-189 | torch | (none) | no fix version published |
+| PYSEC-2025-190 | torch | (none) | same |
+| PYSEC-2025-191 | torch | (none) | same |
+| PYSEC-2025-192 | torch | (none) | same |
+| PYSEC-2025-193 | torch | (none) | same |
+| PYSEC-2025-194 | torch | (none) | same |
+| PYSEC-2025-195 | torch | (none) | same |
+| PYSEC-2025-196 | torch | (none) | same |
+| PYSEC-2025-197 | torch | (none) | same |
+| PYSEC-2025-210 | torch | (none) | same |
+| PYSEC-2026-139 | torch | (none) | same |
+| PYSEC-2025-211 | transformers | (none) | no fix version published; transformers also held by vllm-omni 0.18 |
+| PYSEC-2025-212 | transformers | (none) | same |
+| PYSEC-2025-213 | transformers | (none) | same |
+| PYSEC-2025-214 | transformers | (none) | same |
+| PYSEC-2025-215 | transformers | (none) | same |
+| PYSEC-2025-216 | transformers | (none) | same |
+| PYSEC-2025-217 | transformers | (none) | same |
+| PYSEC-2025-218 | transformers | (none) | same |
+| PYSEC-2026-97 | nltk | (none) | no fix version published |
+| PYSEC-2025-183 | pyjwt | (none) | no fix version published |
+| PYSEC-2024-277 | joblib | (none) | no fix version published |
+| PYSEC-2025-222 | vllm | (none) | no fix version published; held by vllm-omni 0.18 pin |
+| PYSEC-2024-274 | gradio | (none) | no fix version published; vllm-omni 0.18 pins gradio==5.50 |
 
 When a blocker lifts (e.g. transformers 5 ↔ vllm 0.19 line stabilizes),
 drop the corresponding `--ignore-vuln` flag from the workflow and the

docs/EXECUTORS.md

@@ -22,6 +22,26 @@ Helper utilities live in `src/worker/executors/utils/` (`artifacts`,
 `src/worker/executors/mixins/` (`data`, `governance`, `inference`,
 `training`).
 
+## Result schema
+
+Every executor's `run()` returns a subclass of `BaseExecutorResult`
+(`src/shared/schemas/result.py`). The base class carries two
+cross-cutting fields:
+
+- `children: dict[str, BaseExecutorResult]` — per-child results when
+  merged tasks share a dispatch.
+- `artifacts: ArtifactContext | None` (wire key `_artifacts`) —
+  resolution context for relative artifact refs.
+
+Per-executor subclasses live next to the executor they describe — e.g.
+`VLLMResult` in `src/worker/executors/vllm_executor.py`, `LoRAResult` in
+`src/worker/executors/lora_sft_executor.py`. They add executor-specific
+fields (`items`, `usage`, `final_lora`, `command`, …).
+
+Artifact-bearing fields use `ArtifactRef` (`{"path": rel_path}`);
+relative paths resolve against the producer's `_artifacts` context via
+`artifact_to_source` / `_render_artifact_ref`.
+
 ## Agent executor (utu / youtu-agent)
 
 `AgentExecutor` requires the following env vars to run; the executor

sdk/pyproject.toml

@@ -13,7 +13,7 @@ license-files = ["LICENSE"]
 dependencies = [
     "httpx>=0.27.0",
     "pandas>=2.3.3",
-    "pydantic>=2.0.0",
+    "pydantic>=2.12.3",
     "pyyaml>=6.0.0",
 ]
 

sdk/src/flowmesh/models/__init__.py

@@ -1,5 +1,6 @@
 """FlowMesh SDK data models."""
 
+from .artifacts import ArtifactContext, ArtifactRef
 from .common import (
     LogEntry,
     LogEvent,
@@ -19,7 +20,7 @@
     NodeWorkerInfo,
     WorkerRegisterResponse,
 )
-from .results import PathResponse, ResultEnvelope
+from .results import BaseExecutorResult, PathResponse, ResultEnvelope
 from .tasks import HardwareUsage, TaskInfo, TaskUsage
 from .traces import (
     ActiveWaitBreakdown,
@@ -54,7 +55,10 @@
 
 __all__ = [
     "ActiveWaitBreakdown",
+    "ArtifactContext",
+    "ArtifactRef",
     "AssetSummary",
+    "BaseExecutorResult",
     "CPUInfo",
     "CriticalPathSummary",
     "E2EBreakdown",

sdk/src/flowmesh/models/artifacts.py

@@ -0,0 +1,10 @@
+from pydantic import BaseModel, Field
+
+
+class ArtifactRef(BaseModel):
+    path: str
+
+
+class ArtifactContext(BaseModel):
+    base_dir: str
+    base_url: str | None = Field(default=None, exclude_if=lambda v: v is None)

sdk/src/flowmesh/models/results.py

@@ -1,20 +1,45 @@
 """Result-related models."""
 
+# This is necessary to allow for the recursive type hint of `children` in
+# `BaseExecutorResult`.
+from __future__ import annotations
+
 from typing import Any
 
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, ConfigDict, Field, SerializeAsAny
+
+from .artifacts import ArtifactContext
 
 
 class PathResponse(BaseModel):
     ok: bool
     path: str
 
 
+class BaseExecutorResult(BaseModel):
+    model_config = ConfigDict(extra="allow", serialize_by_alias=True)
+
+    ok: bool = True
+    children: dict[str, SerializeAsAny[BaseExecutorResult]] = Field(
+        default_factory=dict, exclude_if=lambda v: not v
+    )
+    artifacts_: ArtifactContext | None = Field(default=None, alias="_artifacts")
+
+    @classmethod
+    def __pydantic_init_subclass__(cls, **kwargs: Any) -> None:
+        super().__pydantic_init_subclass__(**kwargs)
+        if "artifacts_" in cls.__annotations__:
+            raise TypeError(
+                f"{cls.__name__} may not redefine the internal "
+                "BaseExecutorResult.artifacts_ field"
+            )
+
+
 class ResultEnvelope(BaseModel):
     """Canonical on-disk shape of ``results.json`` (mirrors the server)."""
 
     task_id: str
-    result: dict[str, Any]
+    result: SerializeAsAny[BaseExecutorResult]
     worker_id: str | None = None
     metadata: dict[str, Any] | None = None
     received_at: str | None = Field(default=None)

sdk/src/flowmesh/resources/results.py

@@ -198,10 +198,9 @@ def _finalize_materialize(
         return {}, json_path, extracted
 
     envelope = ResultEnvelope.model_validate_json(json_path.read_text())
-    if _wants_artifacts(sections):
-        ctx = envelope.result["_artifacts"]
-        ctx["base_dir"] = (output_dir / task_id).resolve().as_posix()
-        ctx.pop("base_url", None)
+    if _wants_artifacts(sections) and (ctx := envelope.result.artifacts_):
+        ctx.base_dir = (output_dir / task_id).resolve().as_posix()
+        ctx.base_url = None
     payload = envelope.model_dump(mode="json")
     json_path.write_text(json.dumps(payload, indent=2))
     return payload, json_path, extracted