Build AI methods with your coding agent, then run them anywhere: as an MCP for chatbots, as a webapp for people, or via API for your software.
feature/Validator-read-scope · L-261016-d1e014 (#1445)
Louis Choquelf87b30b2ca51
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 15906b238..73373a539 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -1,5 +1,11 @@# Changelog+## [Unreleased]++### Changed++- **A bundle validator receives the read scope, plugin API version 8 (Breaking)**: `BundleValidatorProtocol.validate_bundles` takes `read_scope`, the scope the host named for the validation, `None` when it named none, so a validator dispatching the validation to another process hands the method's trees to its worker through that scope's blob store and the worker reads them by digest under it, as a run's worker reads under the run's read scope. The API server's `POST /v1/validate` hands its validator the request's `read_scope` on every arm, never the caller's own id, and `PLUGIN_API_VERSION` moves to 8, so a plugin declaring `targets_api = 7` is refused at discovery with `PluginApiVersionMismatchError`.+## [v0.88.0] - 2026-10-16### Addeddiff --git a/api/pipelex_api/routes/pipelex/pipeline.py b/api/pipelex_api/routes/pipelex/pipeline.pyindex 722424316..b9f428ef4 100644--- a/api/pipelex_api/routes/pipelex/pipeline.py+++ b/api/pipelex_api/routes/pipelex/pipeline.py@@ -555,6 +555,11 @@ class ApiRunner(PipelexMTHDSProtocol):`method_dir` is the directory a method tree the request carries was written as, by `files` orfetched by `method_ref`: the validation loads it whole, with this runner's `methods_dirs`, inplace of `mthds_contents`, which is then None, and its refusals are the method's verdict.++ This runner's `read_scope` is handed to the validator as the scope of the blob store a dispatched+ arm hands the method's trees to its worker through. The route builds a validating runner with the+ `read_scope` its request names, `None` when it names none, and never with the caller's id a run+ would fall back to: nothing lists or erases what a validation would leave under that prefix."""# Resolve the effective mode FIRST — a per-request override the deployment policy forbids# is refused (403) here, before any validator dispatch / library load. Mirrors start().@@ -585,6 +590,8 @@ class ApiRunner(PipelexMTHDSProtocol):graph_pipe_code=graph_pipe_code,# The files submitted with the contents, which the validation's dry run reads, the template check included.submitted_files=self.submitted_files,+ # The scope the host named, under which a dispatched validator's worker reads the method's trees.+ read_scope=self.read_scope,)# The core seam types its valid arm at the protocol-level ValidationReport (a leaf type)# to stay import-acyclic in core; every registered validator in fact produces the canonicaldiff --git a/api/pipelex_api/routes/pipelex/validate.py b/api/pipelex_api/routes/pipelex/validate.pyindex d539958d5..d1e317659 100644--- a/api/pipelex_api/routes/pipelex/validate.py+++ b/api/pipelex_api/routes/pipelex/validate.py@@ -138,10 +138,12 @@ class ValidateRequest(MthdsContentsRequest, CallerAnalyticsGroupsMixin):read_scope: str | None = Field(default=None,description=(- "PIPELEX-API EXTENSION (not part of the MTHDS Protocol) — the scope of the blob store a hash entry of `files` "- "resolves in, as a run's `read_scope`: a multi-tenant host sends the one of the organization it serves. Omit it "- "and the caller's own id is the scope. Only a validation carrying it records the tree it read in the blob "- "store, so a dry run without one leaves nothing stored."+ "PIPELEX-API EXTENSION (not part of the MTHDS Protocol) — the scope the validation reads the method under, as a "+ "run's `read_scope`: a multi-tenant host sends the one of the organization it serves. A hash entry of `files` "+ "resolves in that scope's blob store, the tree the validation read is recorded there, and the runner hands the "+ "scope to its validator, so a validation dispatched to a worker hands it the method through that store. Omit it "+ "and a hash entry resolves in the caller's own id's store, but nothing is recorded and the validator is handed "+ "no scope, so a dry run without one leaves nothing stored."),)@@ -379,6 +381,10 @@ async def validate_mthds(request: Request, request_data: ValidateRequest) -> JSO# The validation is done for the caller: its dry runs and `pipe_dry_run` event carry the# authenticated user and the body's groups, exactly as a run of this request would.user_id = get_request_user_id(request)+ # The scope the host named, which the validator reads the method under: a dispatched validator hands the method's+ # trees to its worker through that scope's blob store. Never the caller's id a run falls back to, a prefix no host+ # lists or erases, where a validation must leave nothing stored.+ read_scope = request_data.read_scope# Verdict-as-value: the runner resolves the orchestration mode and dispatches through the bundle# validator registry, returning either a validation verdict or a classified fault report.# Only `ErrorReport`s with validation diagnostics are invalid-bundle verdicts (→ 200@@ -388,6 +394,7 @@ async def validate_mthds(request: Request, request_data: ValidateRequest) -> JSOverdict = await ApiRunner(user_id=user_id,extras=request_data.analytics_groups,+ read_scope=read_scope,submitted_files=decode_bundle_resources(resources=request_data.resources),).validate_verdict(mthds_contents=request_data.mthds_contents,@@ -411,7 +418,7 @@ async def validate_mthds(request: Request, request_data: ValidateRequest) -> JSOensure_method_holds_a_bundle(request_method=request_method, label=f"Method package {fetched.label}")ensure_python_allowed(request_method=request_method, label=f"Method package {fetched.label}")else:- blob_store = RunnerBlobStore.make_for_scope(scope=resolve_blob_scope(request, read_scope=request_data.read_scope))+ blob_store = RunnerBlobStore.make_for_scope(scope=resolve_blob_scope(request, read_scope=read_scope))sent_method = await read_request_method(documents=tree_documents_of(body=await request.body()), blob_store=blob_store)if sent_method is None:# Unreachable: the envelope's selector validator already 422'd a body with no `files`.@@ -421,8 +428,9 @@ async def validate_mthds(request: Request, request_data: ValidateRequest) -> JSOensure_method_holds_a_bundle(request_method=request_method, label="This method")ensure_python_allowed(request_method=request_method, label="This method")# A dry run records the tree only under the scope a host named: without one, the fallback scope is the- # caller's own id, a prefix no host lists or erases, and a validation must leave nothing stored there.- if request_data.read_scope is not None:+ # caller's own id, a prefix no host lists or erases, and a validation must leave nothing stored there. Under+ # one, the tree is held there before the validator is called, so a dispatched validator names it by digest.+ if read_scope is not None:await record_request_method(request_method=request_method, blob_store=blob_store)validated_contents = _bundle_texts(request_method=request_method)# The entry pipe of the tree, the one a selector-less run executes, is the graph's pipe and the default the@@ -437,6 +445,7 @@ async def validate_mthds(request: Request, request_data: ValidateRequest) -> JSOmethods_dirs=written.methods_dirs,user_id=user_id,extras=request_data.analytics_groups,+ read_scope=read_scope,).validate_verdict(mthds_contents=None,mthds_sources=None,diff --git a/api/tests/unit/test_method_requirements_refusal.py b/api/tests/unit/test_method_requirements_refusal.pyindex 2c0c31c62..8ccd4ccac 100644--- a/api/tests/unit/test_method_requirements_refusal.py+++ b/api/tests/unit/test_method_requirements_refusal.py@@ -108,6 +108,7 @@ class _UnreachableValidator:submitted_files: Mapping[str, bytes] | None, # noqa: ARG002method_dir: Path | None, # noqa: ARG002methods_dirs: Sequence[Path] | None, # noqa: ARG002+ read_scope: str | None, # noqa: ARG002) -> ErrorReport:self.calls += 1msg = "A method refused for its requirements must not reach the validator."diff --git a/api/tests/unit/test_validate_caller_identity.py b/api/tests/unit/test_validate_caller_identity.pyindex 8d1363b6c..8cd48ddd5 100644--- a/api/tests/unit/test_validate_caller_identity.py+++ b/api/tests/unit/test_validate_caller_identity.py@@ -67,6 +67,7 @@ class _RecordingBundleValidator:submitted_files: Mapping[str, bytes] | None, # noqa: ARG002method_dir: Path | None, # noqa: ARG002methods_dirs: Sequence[Path] | None, # noqa: ARG002+ read_scope: str | None, # noqa: ARG002) -> ErrorReport:self.caller_identities.append(caller_identity)return ErrorReport(diff --git a/api/tests/unit/test_validate_dispatch.py b/api/tests/unit/test_validate_dispatch.pyindex c6d5044da..af06243b8 100644--- a/api/tests/unit/test_validate_dispatch.py+++ b/api/tests/unit/test_validate_dispatch.py@@ -52,6 +52,7 @@ class _StubBundleValidator:submitted_files: Mapping[str, bytes] | None,method_dir: Path | None,methods_dirs: Sequence[Path] | None,+ read_scope: str | None,) -> ErrorReport:self.calls.append({@@ -64,6 +65,7 @@ class _StubBundleValidator:"submitted_files": submitted_files,"method_dir": method_dir,"methods_dirs": methods_dirs,+ "read_scope": read_scope,})if self._error is not None:diff --git a/api/tests/unit/test_validate_graph_target.py b/api/tests/unit/test_validate_graph_target.pyindex c873f8cc1..a9100d469 100644--- a/api/tests/unit/test_validate_graph_target.py+++ b/api/tests/unit/test_validate_graph_target.py@@ -55,6 +55,7 @@ class _RecordingBundleValidator:submitted_files: Mapping[str, bytes] | None, # noqa: ARG002method_dir: Path | None, # noqa: ARG002methods_dirs: Sequence[Path] | None, # noqa: ARG002+ read_scope: str | None, # noqa: ARG002) -> ErrorReport:self.graph_pipe_codes.append(graph_pipe_code)return ErrorReport(diff --git a/api/tests/unit/test_validate_read_scope.py b/api/tests/unit/test_validate_read_scope.pynew file mode 100644index 000000000..489a72e4a--- /dev/null+++ b/api/tests/unit/test_validate_read_scope.py@@ -0,0 +1,168 @@+"""`/validate` hands its validator the read scope its request names, and nothing else.++A validator that dispatches the validation to another process hands the method's trees to its worker+through a blob store, and the scope of that store must be the trusted one the host named for the request,+the organization on a multi-tenant host, as a run's worker reads under the run's read scope. Every+failure here is silent by construction: a keyword left out of `ApiRunner(...)` or `validate_bundles(...)`+still answers 200, and only the worker finds no tree. So these tests read the scope off the call a+recording validator receives, on each arm of the request, and check that a `files` tree is already held+under the scope when the validator is called, so it can name the tree by digest.++A request without a `read_scope` hands the validator none, even on a deployment that identifies its+callers, where a run would fall back to the caller's id: nothing lists or erases what a validation would+leave under that prefix.+"""++import base64+from collections.abc import Awaitable, Callable, Mapping, Sequence+from pathlib import Path+from typing import Any++import pytest+from fastapi import FastAPI, Request, Response+from fastapi.testclient import TestClient+from mthds.method_tree.digest import digest_of_contents+from pipelex.base_exceptions import ErrorReport, ValidationErrorCategory, ValidationErrorItem+from pipelex.plugins.bundle_validator_registry import BundleValidatorRegistry+from pipelex.system.caller_identity import CallerIdentity+from pipelex.tools.storage.in_memory_storage_provider import InMemoryStorageProvider+from pytest_mock import MockerFixture++from pipelex_api.api_config import ApiConfig+from pipelex_api.exception_handlers import register_exception_handlers+from pipelex_api.routes import router as api_router+from pipelex_api.security import RequestUser+from tests.unit._constants import STUB_METHOD_ADDRESS, VALID_MTHDS++_PIPELINE_NS = "pipelex_api.routes.pipelex.pipeline"+_MODE = "temporal"+_USER_ID = "user_42"+_READ_SCOPE = "org-a"+_METHOD_REF = f"{STUB_METHOD_ADDRESS}@v0.1.0"+_TEMPLATE = b"<h1>{{ text }}</h1>"+_TEMPLATE_B64 = base64.b64encode(_TEMPLATE).decode("ascii")+++class _RecordingBundleValidator:+ """Records the read scope of every validation dispatched to it, and what the blob store held then."""++ def __init__(self, *, blob_storage: InMemoryStorageProvider) -> None:+ self._blob_storage = blob_storage+ self.read_scopes: list[str | None] = []+ self.held_keys: list[set[str]] = []++ async def validate_bundles(+ self,+ *,+ mthds_contents: list[str] | None, # noqa: ARG002+ mthds_sources: list[str] | None, # noqa: ARG002+ allow_signatures: bool, # noqa: ARG002+ library_dirs: Sequence[Path] | None, # noqa: ARG002+ caller_identity: CallerIdentity | None, # noqa: ARG002+ graph_pipe_code: str | None, # noqa: ARG002+ submitted_files: Mapping[str, bytes] | None, # noqa: ARG002+ method_dir: Path | None, # noqa: ARG002+ methods_dirs: Sequence[Path] | None, # noqa: ARG002+ read_scope: str | None,+ ) -> ErrorReport:+ self.read_scopes.append(read_scope)+ self.held_keys.append(set(self._blob_storage.root))+ return ErrorReport(+ error_type="ValidateBundleError",+ message="bundle is invalid",+ title="Validate bundle error",+ type_uri="https://errors.pipelex.com/validate-bundle-error/",+ validation_errors=[ValidationErrorItem(category=ValidationErrorCategory.BLUEPRINT_VALIDATION, message="bad ref")],+ )+++def _build_client(*, user_id: str | None) -> TestClient:+ app = FastAPI()++ if user_id is not None:+ authenticated_user = RequestUser(user_id=user_id)++ async def authenticate(request: Request, call_next: Callable[[Request], Awaitable[Response]]) -> Response:+ request.state.user = authenticated_user+ return await call_next(request)++ app.middleware("http")(authenticate)++ app.include_router(api_router, prefix="/v1")+ register_exception_handlers(app)+ return TestClient(app)+++def _register_recording_validator(mocker: MockerFixture, *, blob_storage: InMemoryStorageProvider) -> _RecordingBundleValidator:+ config = ApiConfig(orchestration_mode=_MODE, allow_request_orchestration_mode_override=False)+ mocker.patch(f"{_PIPELINE_NS}.get_api_config", return_value=config)+ validator = _RecordingBundleValidator(blob_storage=blob_storage)+ mocker.patch(f"{_PIPELINE_NS}.get_bundle_validator_registry", return_value=BundleValidatorRegistry({_MODE: validator}))+ return validator+++_REQUEST_METHODS = [+ pytest.param({"mthds_contents": [VALID_MTHDS]}, id="mthds_contents"),+ pytest.param({"mthds_contents": [VALID_MTHDS], "resources": {"templates/page.html": _TEMPLATE_B64}}, id="mthds_contents-with-resources"),+ pytest.param({"files": {"main.mthds": VALID_MTHDS}}, id="files"),+ pytest.param({"method_ref": _METHOD_REF}, id="method_ref"),+]+++class TestValidateReadScope:+ @pytest.mark.parametrize("request_method", _REQUEST_METHODS)+ def test_the_validator_receives_the_read_scope_the_request_names(+ self,+ mocker: MockerFixture,+ blob_storage: InMemoryStorageProvider,+ install_method_package: Callable[..., Path],+ request_method: dict[str, Any],+ ) -> None:+ install_method_package(files={"documents.mthds": VALID_MTHDS})+ validator = _register_recording_validator(mocker, blob_storage=blob_storage)+ client = _build_client(user_id=_USER_ID)++ response = client.post("/v1/validate", json={**request_method, "read_scope": _READ_SCOPE})++ assert response.status_code == 200, response.text+ assert response.json()["is_valid"] is False+ assert validator.read_scopes == [_READ_SCOPE]++ @pytest.mark.parametrize("user_id", [pytest.param(_USER_ID, id="identified-caller"), pytest.param(None, id="single-tenant")])+ @pytest.mark.parametrize("request_method", _REQUEST_METHODS)+ def test_a_request_without_a_read_scope_hands_the_validator_none_never_the_callers_id(+ self,+ mocker: MockerFixture,+ blob_storage: InMemoryStorageProvider,+ install_method_package: Callable[..., Path],+ request_method: dict[str, Any],+ user_id: str | None,+ ) -> None:+ install_method_package(files={"documents.mthds": VALID_MTHDS})+ validator = _register_recording_validator(mocker, blob_storage=blob_storage)+ client = _build_client(user_id=user_id)++ response = client.post("/v1/validate", json=request_method)++ assert response.status_code == 200, response.text+ assert validator.read_scopes == [None]+ assert validator.held_keys == [set()]++ def test_a_files_tree_is_held_under_the_read_scope_before_the_validator_is_called(+ self, mocker: MockerFixture, blob_storage: InMemoryStorageProvider+ ) -> None:+ """A dispatched validator names the tree by its digest, so the tree must already be in the scope's blob store."""+ validator = _register_recording_validator(mocker, blob_storage=blob_storage)+ client = _build_client(user_id=_USER_ID)+ contents = {"main.mthds": VALID_MTHDS.encode("utf-8"), "templates/page.html": _TEMPLATE}++ response = client.post(+ "/v1/validate",+ json={"files": {"main.mthds": VALID_MTHDS, "templates/page.html": {"base64": _TEMPLATE_B64}}, "read_scope": _READ_SCOPE},+ )++ assert response.status_code == 200, response.text+ digest_hex = digest_of_contents(contents).removeprefix("sha256:")+ (held_keys,) = validator.held_keys+ assert f"{_READ_SCOPE}/trees/{digest_hex}" in held_keys+ assert all(key.startswith(f"{_READ_SCOPE}/") for key in held_keys)diff --git a/docs/api-server/openapi/pipelex-api.openapi.yaml b/docs/api-server/openapi/pipelex-api.openapi.yamlindex 394fa3a14..23aae1dfc 100644--- a/docs/api-server/openapi/pipelex-api.openapi.yaml+++ b/docs/api-server/openapi/pipelex-api.openapi.yaml@@ -8280,10 +8280,12 @@ components:- type: string- type: 'null'title: Read Scope- description: 'PIPELEX-API EXTENSION (not part of the MTHDS Protocol) — the scope of the blob store a hash entry- of `files` resolves in, as a run''s `read_scope`: a multi-tenant host sends the one of the organization it serves.- Omit it and the caller''s own id is the scope. Only a validation carrying it records the tree it read in the blob- store, so a dry run without one leaves nothing stored.'+ description: 'PIPELEX-API EXTENSION (not part of the MTHDS Protocol) — the scope the validation reads the method+ under, as a run''s `read_scope`: a multi-tenant host sends the one of the organization it serves. A hash entry+ of `files` resolves in that scope''s blob store, the tree the validation read is recorded there, and the runner+ hands the scope to its validator, so a validation dispatched to a worker hands it the method through that store.+ Omit it and a hash entry resolves in the caller''s own id''s store, but nothing is recorded and the validator+ is handed no scope, so a dry run without one leaves nothing stored.'type: objecttitle: ValidateRequestdescription: 'The shared `mthds_contents` + `allow_signatures` payload, plus optional per-file sources.diff --git a/docs/api-server/pipe-validate.md b/docs/api-server/pipe-validate.mdindex 4293c9a20..c91c4ab92 100644--- a/docs/api-server/pipe-validate.md+++ b/docs/api-server/pipe-validate.md@@ -20,7 +20,7 @@ Validate MTHDS content by parsing, loading, and dry-running pipes without execut- `files` (object, optional): The method as a map of file entries, the MTHDS standard's method tree, each value the file's text, `{"base64": "…"}` or `{"sha256": "…", "size": n}`, read as on a run — see [Validating a method tree](#validating-a-method-tree). Exactly one of `mthds_contents` / `files` / `method_ref`- `dependencies` (object, optional): **Pipelex-API extension.** The method packages the method calls by address that the runner cannot fetch, each a map of file entries keyed by its address, as on a [run](pipe-run.md#sending-the-method-packages-the-method-calls). Accompanies `files`- `method_ref` (string, optional): **Pipelex-API extension.** Validate a published method by address — `github.com/<owner>/<repo>` plus an optional package selector and `@<tag>` — resolved by this server through the same fetch path as a [`method_ref` run](pipe-run.md#running-a-method-by-address-method_ref): the repository is fetched at the tag, the package located by manifest identity, and its tree read from the commit's git objects and validated as a tree sent in `files` is — see [Validating a method tree](#validating-a-method-tree). Exactly one of `mthds_contents` / `files` / `method_ref`; `mthds_sources` cannot accompany it. A package holding Python and a `requirements.txt` has its requirements checked on this server against the package set of the deployment's PipeFunc sandbox before anything is validated, and a requirement the sandbox does not meet, or a line the standard refuses, makes the verdict `is_valid: false` with one item per line, whose `source` is `requirements.txt` and whose `line` is the line's number-- `read_scope` (string, optional): **Pipelex-API extension.** The scope of the blob store a hash entry of `files` resolves in, as a run's `read_scope`; omitted, the caller's own id is the scope — see [Sending files by hash](pipe-run.md#sending-files-by-hash). Only a validation carrying it records the tree it read in the blob store, so a dry run without one leaves nothing stored+- `read_scope` (string, optional): **Pipelex-API extension.** The scope the validation reads the method under, as a run's `read_scope`, which a multi-tenant host sends for the organization it serves. A hash entry of `files` resolves in that scope's blob store — see [Sending files by hash](pipe-run.md#sending-files-by-hash) — and the runner hands the scope to its validator, so a validation dispatched to a worker can hand it the method through that store — see [Where validation runs](#where-validation-runs). Omitted, a hash entry resolves in the caller's own id's store, but only a validation carrying it records the tree it read in the blob store, and the validator is handed no scope, so a dry run without one leaves nothing stored- `allow_signatures` (boolean, optional, default `false`): controls only the **sweep mechanics** for `PipeSignature` placeholders — whether signature pipes are mock-run during the dry-run sweep and therefore listed in `validated_pipes`. It does **not** change the verdict: an unimplemented signature is never a rejection, it is a *runnability fact* reported via `pending_signatures` + `is_runnable` in both modes- `mthds_sources` (list[str] | null, optional): per-file sources, parallel to `mthds_contents` — see [Sourcing submitted files](#sourcing-submitted-files). When present it must match `mthds_contents` in length (a mismatch is a 422 request error), and it accompanies `mthds_contents` alone, since a tree's files are named by their tree paths- `resources` (object | null, optional): **Pipelex-API extension.** The files the bundle's steps read, such as a `PipeDocGen` step's `template_file`, as a map from the path the step names to the file's bytes in standard base64 — see [Sending the files the steps read](#sending-the-files-the-steps-read-resources). It accompanies `mthds_contents` or `files`, whose tree each file joins; beside `method_ref` it is a 422@@ -191,6 +191,8 @@ The files are checked as files on disk are. An `.html` template file is checkedValidation is **`orchestration_mode`-aware**, the same way `/start` is: the runner resolves the effective backend (the deployment default plus the optional per-request `orchestration_mode` override) and dispatches through the bundle-validator registry. Validation is inherently blocking, so there is no delivery axis here — only the backend varies. On the orchestrator-agnostic base — and for `orchestration_mode: direct` — the whole job runs **in-process in one library load on the API side**. On an orchestrator flavor whose mode is selected (e.g. `temporal`), the whole job is **dispatched to a worker** instead, and the API side assembles the same canonical report from the worker's result without loading a library. Either way the verdict is byte-identical: the backend changes, the contract does not. A per-request override the deployment forbids is refused with a 403.+The validator is handed the request's `read_scope`, the scope a run of the same request reads under, so a validator that dispatches to a worker can hand it the method's trees through that scope's blob store and the worker read them by digest, as a run's worker reads its method's files under the run's read scope. A tree sent in `files` is already recorded there when the validator is called. A request without a `read_scope` hands the validator none, never the caller's own id, so a dispatched validation stores nothing under a prefix no host lists or erases.+> **Resource note for deployment.** When validation runs in-process (the agnostic base, or `direct` mode), the API server loads the method library to validate, so a deployment that receives large or frequent in-process `/validate` traffic should be sized for that load (memory + CPU for library assembly and the graph dry-run). On a distributed-execution flavor that dispatches validation to a worker, the library work happens worker-side; size the workers accordingly.The graph is best-effort: a bundle that validates but whose graph dry-run fails still returns 200 on the valid arm with `graph_spec: null`.diff --git a/docs/under-the-hood/orchestrator-plugins.md b/docs/under-the-hood/orchestrator-plugins.mdindex 29b898c27..49afe4405 100644--- a/docs/under-the-hood/orchestrator-plugins.md+++ b/docs/under-the-hood/orchestrator-plugins.md@@ -73,16 +73,20 @@ class BundleValidatorProtocol(Protocol):async def validate_bundles(self,*,- mthds_contents: list[str],+ mthds_contents: list[str] | None,mthds_sources: list[str] | None,allow_signatures: bool,library_dirs: "Sequence[Path] | None",caller_identity: CallerIdentity | None,graph_pipe_code: str | None,+ submitted_files: "Mapping[str, bytes] | None",+ method_dir: "Path | None",+ methods_dirs: "Sequence[Path] | None",+ read_scope: str | None,) -> BundleValidationVerdict: ...```-The `library_dirs` annotation is a quoted forward reference because `Sequence` and `Path` are imported under `TYPE_CHECKING` in `bundle_validator_registry.py`; a plugin that imports them at module scope can use the unquoted form.+The quoted annotations are forward references because `Mapping`, `Sequence` and `Path` are imported under `TYPE_CHECKING` in `bundle_validator_registry.py`; a plugin that imports them at module scope can use the unquoted form.Two contract points distinguish it from `OrchestratorProtocol.execute`:@@ -95,6 +99,10 @@ The seam is deliberately typed at the MTHDS-protocol level (`ValidationReport` f`graph_pipe_code` names the pipe the verdict's best-effort `graph_spec` is drawn from. It is resolved the way a run resolves its entry pipe, so a bare pipe code or a qualified `domain.pipe_code` both work, and `None` keeps the default target: the `main_pipe` of the primary blueprint, the first one declaring one. A host passes a target when it knows the pipe a selector-less run of the same request would execute and the bundles do not say so themselves — a method package fetched by address, whose manifest's `main_pipe` outranks the bundles' own declaration and may be the only entry pipe there is. It is required for the same reason as `caller_identity`: a validator that dropped it would silently graph another pipe. A target that does not resolve degrades the graph to `None` like any other graph-arm failure and never changes the verdict. The in-process arm hands it to `validate_bundles_in_process`; a worker-dispatched arm must carry it to the worker's graph arm.+`submitted_files`, `method_dir` and `methods_dirs` say what the method is made of besides its contents. `submitted_files` are the files submitted with `mthds_contents` that their steps read, such as a `PipeDocGen` step's template file, keyed by the path the step names. `method_dir` names a method sent as a tree, or fetched by address, in place of `mthds_contents`, which is then `None`: the directory the host wrote the tree into and holds as written, with the dependency trees it ships in `methods_dirs`. Each is required, `None` meaning there is none, so a validator cannot drop the files a valid method needs and refuse it for a missing file.++`read_scope` is the scope the host named for the validation: on a multi-tenant host, the organization it serves, the same trusted prefix a run of the request reads under. A worker-dispatched arm hands the method's trees to its worker through that scope's blob store, as an orchestrator copies a job's trees into the store its workers read before it dispatches ([the method file store slot](#the-method-file-store-slot)): it holds every tree it validates there, names each by its digest, and the worker reads them through its method file store under the scope, building every key from it and never from what the request names. `None` means the host named no scope, as a single-tenant deployment does, or a multi-tenant host serving a caller who belongs to no organization, and then no blob store is scoped to the caller: a worker-dispatched arm has none to hand the method through and must not make one up, such as one under the caller's id, where nothing lists or erases what a validation would leave. The in-process arm reads every file in its own process and ignores it. It is required for the same reason as `caller_identity`; a host runner passes the read scope it was built with, which `pipelex-api` builds from the request's own `read_scope` and never from the caller's id.+A plugin contributes one per token, right next to its orchestrator:```pythondiff --git a/docs/under-the-hood/writing-an-inference-plugin.md b/docs/under-the-hood/writing-an-inference-plugin.mdindex 9745f9691..56cebd57b 100644--- a/docs/under-the-hood/writing-an-inference-plugin.md+++ b/docs/under-the-hood/writing-an-inference-plugin.md@@ -110,7 +110,7 @@ class HelloInferencePlugin:name = "hello_inference"# The plugin API version this plugin was written against, as a literal: never import the# runtime's PLUGIN_API_VERSION here, or the check that catches a breaking runtime upgrade always passes.- targets_api = 7+ targets_api = 8def register(self, registrar: PluginRegistrar) -> None:registrar.add_inference_backend(family=InferenceFamily.LLM, sdk="hello", make_worker=_make_hello_llm_worker)diff --git a/pipelex/pipeline/direct_bundle_validator.py b/pipelex/pipeline/direct_bundle_validator.pyindex 59857ba11..ad44c011b 100644--- a/pipelex/pipeline/direct_bundle_validator.py+++ b/pipelex/pipeline/direct_bundle_validator.py@@ -47,6 +47,9 @@ class DirectBundleValidator:submitted_files: Mapping[str, bytes] | None,method_dir: Path | None,methods_dirs: Sequence[Path] | None,+ # The in-process arm reads every file of the method in this process, from the trees its libraries hold, and+ # reads no blob store, so the scope a dispatched arm hands its worker the trees through has no use here.+ read_scope: str | None, # ruff: ignore[unused-method-argument]) -> PipelexValidationReport | ErrorReport:try:return await validate_bundles_in_process(diff --git a/pipelex/plugins/bundle_validator_registry.py b/pipelex/plugins/bundle_validator_registry.pyindex 85c1fa8e5..fbbf783ed 100644--- a/pipelex/plugins/bundle_validator_registry.py+++ b/pipelex/plugins/bundle_validator_registry.py@@ -90,6 +90,21 @@ class BundleValidatorProtocol(Protocol):hold the dependency trees the caller ships with it. Both are required for the same reason as``caller_identity``, ``None`` meaning the method came as contents. A worker-dispatched arm readsthe tree's files on the host, where it is called, and hands them to its worker as trees.++ ``read_scope`` is the scope the host named for the validation: on a multi-tenant host, the+ organization it serves, the trusted prefix a run of the same request reads under+ (``pipelex.tools.uri.uri_read_scope``). It is the scope of the blob store a worker-dispatched arm+ hands the method to its worker through, as a run's orchestrator and worker do under the run's read+ scope: the arm holds every tree it validates in that store, a tree the host already recorded there+ included, names each by its digest, and the worker reads them through its method file store under+ the scope, building every key from it and never from what the request names. ``None`` means the+ host named no scope, as a single-tenant deployment does, or a multi-tenant host serving a caller+ who belongs to no organization: no blob store is then scoped to the caller, so a worker-dispatched+ arm has none to hand the method through and must not make one up, such as one under the caller's+ id, where nothing lists or erases what a validation would leave.+ The in-process arm reads every file in its own process and ignores it. It is required for the+ same reason as ``caller_identity``: a validator that dropped it would read the method under no+ scope."""async def validate_bundles(@@ -104,6 +119,7 @@ class BundleValidatorProtocol(Protocol):submitted_files: "Mapping[str, bytes] | None",method_dir: "Path | None",methods_dirs: "Sequence[Path] | None",+ read_scope: str | None,) -> BundleValidationVerdict: ...diff --git a/pipelex/plugins/contract.py b/pipelex/plugins/contract.pyindex c3566422e..392294e02 100644--- a/pipelex/plugins/contract.py+++ b/pipelex/plugins/contract.py@@ -74,7 +74,14 @@ if TYPE_CHECKING:# ``RenderResources.load``, which reads an image, a stylesheet or a font joined under the prefix from the document's# method tree; and the error that arm raises for a URL naming no such file (``TemplateUrlRefusedError``), which an engine# lets pass as it came. An engine written before them ignores ``base_url`` and keeps refusing a relative URL, as it did.-PLUGIN_API_VERSION: int = 7+#+# v8 changed what a host hands a bundle validator: ``validate_bundles`` takes ``read_scope``, the scope the host named for+# the validation, ``None`` when it named none, so a validator dispatching the validation to another process hands the+# method's trees to its worker through that scope's blob store and the worker reads them under it, as a run's worker+# reads under the run's read scope (``BundleValidatorProtocol``). A validator written against v7 would be called with a+# keyword it does not accept on its first validation; the bump turns that into a discovery-time mismatch naming the+# plugin.+PLUGIN_API_VERSION: int = 8@runtime_checkablediff --git a/tests/unit/pipelex/pipeline/test_direct_bundle_validator.py b/tests/unit/pipelex/pipeline/test_direct_bundle_validator.pyindex 60087ba13..8ba40e7dc 100644--- a/tests/unit/pipelex/pipeline/test_direct_bundle_validator.py+++ b/tests/unit/pipelex/pipeline/test_direct_bundle_validator.py@@ -5,7 +5,8 @@ covered by test_validation_report.py / the integration test_protocol_validate.pysweep is returned verbatim as the valid arm; a ``ValidateBundleError`` is converted to itsstructured ``ErrorReport`` (the invalid arm) rather than propagated. Also pins argumentpassthrough, including the ``library_dirs`` host context, the explicit ``graph_pipe_code`` target-and the ``log_context`` label.+and the ``log_context`` label, and that the read scope stops here: the in-process arm reads every+file in its own process, through no blob store, so the sweep is never handed one."""from __future__ import annotations@@ -45,6 +46,7 @@ class TestDirectBundleValidator:submitted_files=submitted_files,method_dir=None,methods_dirs=None,+ read_scope="org_acme",)assert verdict is report@@ -79,6 +81,7 @@ class TestDirectBundleValidator:submitted_files=None,method_dir=None,methods_dirs=None,+ read_scope=None,)assert isinstance(verdict, ErrorReport)@@ -103,4 +106,5 @@ class TestDirectBundleValidator:submitted_files=None,method_dir=None,methods_dirs=None,+ read_scope=None,)diff --git a/tests/unit/pipelex/plugins/test_bundle_validator_registry.py b/tests/unit/pipelex/plugins/test_bundle_validator_registry.pyindex 9fbeb9f80..34888566b 100644--- a/tests/unit/pipelex/plugins/test_bundle_validator_registry.py+++ b/tests/unit/pipelex/plugins/test_bundle_validator_registry.py@@ -2,17 +2,19 @@Pins the seam independent of the real DIRECT/Temporal validators: a validator registered fora mode is the one the registry hands back; a second registration for the same mode fails loud-naming both plugins; an empty registry reports the mode as absent.+naming both plugins; an empty registry reports the mode as absent; and the protocol requires the+read scope a worker-dispatched validator reads the method's trees under."""from __future__ import annotations+import inspectfrom types import SimpleNamespacefrom typing import TYPE_CHECKING, castimport pytest-from pipelex.plugins.bundle_validator_registry import BundleValidatorRegistry+from pipelex.plugins.bundle_validator_registry import BundleValidatorProtocol, BundleValidatorRegistryfrom pipelex.plugins.contract import PLUGIN_API_VERSIONfrom pipelex.plugins.exceptions import DuplicateBundleValidatorErrorfrom pipelex.plugins.registrar import PluginOrigin, PluginRegistrar@@ -43,6 +45,7 @@ class _FakeBundleValidator:submitted_files: Mapping[str, bytes] | None,method_dir: Path | None,methods_dirs: Sequence[Path] | None,+ read_scope: str | None,) -> PipelexValidationReport | ErrorReport:raise NotImplementedError@@ -95,3 +98,11 @@ class TestBundleValidatorRegistry:assert registry.get_optional(mode=DIRECT_ORCHESTRATION_MODE) is Noneassert not registry.has(mode="temporal")assert registry.modes == []++ def test_the_protocol_requires_the_read_scope_by_keyword(self) -> None:+ """A host must name the read scope, ``None`` included, so a dispatched validator never reads under a scope it guessed."""+ read_scope = inspect.signature(BundleValidatorProtocol.validate_bundles).parameters["read_scope"]++ assert read_scope.kind is inspect.Parameter.KEYWORD_ONLY+ assert read_scope.default is inspect.Parameter.empty+ assert read_scope.annotation == str | Nonediff --git a/tests/unit/pipelex/plugins/test_plugin_discovery.py b/tests/unit/pipelex/plugins/test_plugin_discovery.pyindex 346b5872c..f77f5c13d 100644--- a/tests/unit/pipelex/plugins/test_plugin_discovery.py+++ b/tests/unit/pipelex/plugins/test_plugin_discovery.py@@ -165,13 +165,13 @@ class TestPluginDiscovery:_build_registrar_with(mocker=mocker, plugins=[future_plugin])assert "from_the_future" in str(exc_info.value)- def test_a_plugin_written_before_crates_named_their_trees_is_refused(self, mocker: MockerFixture) -> None:- """Plugin API v6 handed validators `bundle_resources` and executors the call's `files`; a v6 plugin would fail on its first call."""- v6_plugin = _InferencePlugin(name="written_against_v6", sdk="v6_sdk", targets_api=6)+ def test_a_plugin_written_before_validators_received_the_read_scope_is_refused(self, mocker: MockerFixture) -> None:+ """Plugin API v7 handed validators no `read_scope`; a v7 validator would fail on its first validation."""+ v7_plugin = _InferencePlugin(name="written_against_v7", sdk="v7_sdk", targets_api=7)with pytest.raises(PluginApiVersionMismatchError) as exc_info:- _build_registrar_with(mocker=mocker, plugins=[v6_plugin])- assert "written_against_v6" in str(exc_info.value)- assert PLUGIN_API_VERSION == 7+ _build_registrar_with(mocker=mocker, plugins=[v7_plugin])+ assert "written_against_v7" in str(exc_info.value)+ assert PLUGIN_API_VERSION == 8def test_duplicate_inference_backend_names_both(self, mocker: MockerFixture) -> None:with pytest.raises(DuplicateInferenceBackendError) as exc_info: