-
Run a task by name and wait for its results.
-
The same as await client.<topic>.<task>.run(**parameters), for names held as
-strings. Names may be spelled as the platform publishes them or with underscores.
+
Discover the task (cached), resolve and validate the parameters, submit, and hydrate the results.
Parameters:
@@ -293,8 +317,9 @@
- Override the client's shallow-validation setting for this call.
-The master switch: False skips deep validation too.
+ Override the client's schema-validation setting for this call.
+False skips deep validation too, but never the signature binding that
+builds the payload.
|
@@ -318,6 +343,23 @@
None
|
+
+
+ check_schemas
+ |
+
+ bool | None
+ |
+
+
+ Override the client's supported-schema setting for this call.
+Falls back to validate when neither is set.
+
+ |
+
+ None
+ |
+
@@ -333,11 +375,11 @@
- dict
+ TaskResult
|
- The results of the finished job.
+ The hydrated results of the finished job.
|
@@ -370,7 +412,7 @@
- If the parameters do not match the task's schema.
+ If the parameters or referenced objects fail validation.
|
diff --git a/packages/evo-compute/pyproject.toml b/packages/evo-compute/pyproject.toml
index 12b6f641..aea2a238 100644
--- a/packages/evo-compute/pyproject.toml
+++ b/packages/evo-compute/pyproject.toml
@@ -42,6 +42,10 @@ dev = [
{include-group = "test"},
]
+[tool.pytest.ini_options]
+# The parity suites share one harness module, so `tests` has to be importable under any import mode.
+pythonpath = ["tests"]
+
[tool.ruff]
src = ["src", "tests"]
line-length = 120
diff --git a/packages/evo-compute/src/evo/compute/__init__.py b/packages/evo-compute/src/evo/compute/__init__.py
index 3605ea56..60726269 100644
--- a/packages/evo-compute/src/evo/compute/__init__.py
+++ b/packages/evo-compute/src/evo/compute/__init__.py
@@ -16,6 +16,8 @@
from .endpoints.models import TaskResource
from .engine import ComputeClient
from .exceptions import ParameterValidationError
+from .outputs import ResultNode, TaskResult
+from .resolution import ReferenceResolver
__all__ = [
"ComputeClient",
@@ -24,6 +26,9 @@
"JobProgress",
"JobStatusEnum",
"ParameterValidationError",
+ "ReferenceResolver",
+ "ResultNode",
"TaskResource",
+ "TaskResult",
"tasks",
]
diff --git a/packages/evo-compute/src/evo/compute/discovery.py b/packages/evo-compute/src/evo/compute/discovery.py
index 5993280e..4d867ad9 100644
--- a/packages/evo-compute/src/evo/compute/discovery.py
+++ b/packages/evo-compute/src/evo/compute/discovery.py
@@ -15,11 +15,18 @@
and result schemas for each. The catalogue is paginated by the service; this client fetches
every page and caches the combined result with a time-to-live. The convenience accessors
(:meth:`get_topics`, :meth:`get_topic_tasks`, :meth:`get_task`) read from that cache.
+
+A fetched catalogue is also checked against the closed annotation vocabulary the engine
+understands. An annotation this SDK has never heard of means the platform has moved on and
+the schema can only be partly interpreted, so it is reported as a warning -- never a
+failure. The unrecognised part may not even be one this call depends on, and refusing to
+run would make the SDK the blocker the moment the platform ships a new annotation.
"""
from __future__ import annotations
import asyncio
+import logging
import time
from uuid import UUID
@@ -27,11 +34,14 @@
from .endpoints.api import DiscoveryApi
from .endpoints.models import TaskResource
+from .validation import unknown_annotation_keys
__all__ = [
"DiscoveryClient",
]
+logger = logging.getLogger("compute.discovery")
+
DEFAULT_CACHE_TTL_SECONDS = 300.0
"""Default time-to-live for the cached task catalogue, in seconds."""
@@ -64,6 +74,7 @@ def __init__(
self._mutex = asyncio.Lock()
self._cache: list[TaskResource] = []
self._cache_expiry: float | None = None
+ self._reported_annotations: set[str] = set()
@classmethod
def from_context(
@@ -129,6 +140,29 @@ async def _fetch(self) -> None:
break
self._cache = tasks
self._cache_expiry = time.monotonic() + self._cache_ttl_seconds
+ self._report_unknown_annotations(tasks)
+
+ def _report_unknown_annotations(self, tasks: list[TaskResource]) -> None:
+ """Warn once about each annotation the platform publishes and this SDK cannot read.
+
+ Reported per key rather than per task, and only the first time a key is seen, so a
+ catalogue that has moved ahead of the installed SDK costs one line rather than one
+ per task per cache expiry.
+ """
+ carriers: dict[str, list[str]] = {}
+ for task in tasks:
+ for key in unknown_annotation_keys(task.parameters) | unknown_annotation_keys(task.results):
+ if key not in self._reported_annotations:
+ carriers.setdefault(key, []).append(f"{task.topic}.{task.name}")
+ if not carriers:
+ return
+ self._reported_annotations |= carriers.keys()
+ logger.warning(
+ "the compute catalogue uses schema annotations this SDK does not recognise: %s. "
+ "Those parts of the affected schemas cannot be interpreted, so a task may need "
+ "arguments in their wire form; upgrading evo-compute may add support for them.",
+ "; ".join(f"{key!r} on {', '.join(sorted(names))}" for key, names in sorted(carriers.items())),
+ )
async def _catalogue(self, force_refresh: bool) -> list[TaskResource]:
"""Return the cached catalogue, fetching it first if it is stale or forced."""
diff --git a/packages/evo-compute/src/evo/compute/engine.py b/packages/evo-compute/src/evo/compute/engine.py
index 5531bee6..5cb13dc6 100644
--- a/packages/evo-compute/src/evo/compute/engine.py
+++ b/packages/evo-compute/src/evo/compute/engine.py
@@ -19,11 +19,15 @@
client = ComputeClient(context)
result = await client.geostatistics.kriging.run(source=..., target=..., ...)
+A call is checked, resolved, checked again and submitted: required parameters first
+(before anything reaches the network), then :mod:`~evo.compute.resolution` turns the
+caller's objects and attributes into the references the schema declares, then optional
+deep validation runs on that resolved payload -- the form the platform actually receives.
+What comes back is hydrated against the task's ``results`` schema by
+:mod:`~evo.compute.outputs`, so the objects a task wrote can be loaded straight back.
+
Topic, task and parameter names are the platform's names with hyphens replaced by
underscores, so ``normal-score`` is reached as ``client.geostatistics.normal_score``.
-Parameters are sent in the form the task's schema declares, and only the ones the
-caller passes: unset optional parameters are left to the platform's defaults.
-
The catalogue is fetched the first time a task is ``run(...)``. It is then held by the
underlying :class:`~evo.compute.discovery.DiscoveryClient`, so repeated runs are served
from there until its cache expires.
@@ -42,6 +46,8 @@
from .discovery import DEFAULT_CACHE_TTL_SECONDS, DiscoveryClient
from .endpoints.models import TaskResource
from .exceptions import ParameterValidationError
+from .outputs import TaskResult
+from .resolution import ReferenceResolver
from .validation import validate_parameters
__all__ = [
@@ -129,7 +135,7 @@ def _signature_from_schema(spec: TaskResource) -> inspect.Signature:
parameters.append(inspect.Parameter("preview", inspect.Parameter.KEYWORD_ONLY, default=False, annotation=bool))
if properties and not names:
parameters.append(inspect.Parameter("parameters", inspect.Parameter.VAR_KEYWORD, annotation=Any))
- return inspect.Signature(parameters, return_annotation=dict)
+ return inspect.Signature(parameters, return_annotation=TaskResult)
def _check_fallback_parameters(spec: TaskResource, parameters: dict[str, Any], label: str) -> None:
@@ -154,11 +160,21 @@ class ComputeClient:
:param context: An authenticated Evo context.
:param cache_ttl_seconds: How long a discovered task catalogue is cached.
- :param validate: Validate parameters against the task schema before submitting
- (required-field presence). Defaults to ``True``. This is the master switch:
- ``False`` turns off deep validation too, whatever ``deep_validation`` says.
+ :param validate: Check the parameters against the task's JSON Schema before submitting
+ (required-field presence, and, under ``deep_validation``, the whole payload).
+ Defaults to ``True``. ``False`` turns off deep validation too, whatever
+ ``deep_validation`` says. It does *not* make the call unchecked: the parameters are
+ still bound to the signature synthesised from the schema, so an unknown or missing
+ required argument is still rejected. That is how the payload is built, not a
+ validation pass, and there is no useful call to make without it.
:param deep_validation: Additionally run full JSON Schema Draft 2020-12 validation.
Defaults to ``False``. Only consulted when ``validate`` is ``True``.
+ :param check_schemas: Check that each referenced geoscience object is of a schema the
+ task declares support for. Defaults to following ``validate``. Independent of it
+ because the cost and the question differ: schema validation is local and free,
+ while this loads each referenced object's metadata. Pass ``False`` to keep
+ validation but skip the requests, or ``True`` alongside ``validate=False`` to keep
+ the guard that catches an object the task cannot read.
"""
def __init__(
@@ -168,12 +184,16 @@ def __init__(
cache_ttl_seconds: float = DEFAULT_CACHE_TTL_SECONDS,
validate: bool = True,
deep_validation: bool = False,
+ check_schemas: bool | None = None,
) -> None:
+ self._context = context
self._org_id: UUID = context.get_org_id()
self._connector: APIConnector = context.get_connector()
self._discovery = DiscoveryClient(self._connector, self._org_id, cache_ttl_seconds=cache_ttl_seconds)
+ self._resolver = ReferenceResolver(context)
self._validate = validate
self._deep_validation = deep_validation
+ self._check_schemas = check_schemas
# -- dynamic namespace ------------------------------------------------- #
@@ -210,24 +230,25 @@ async def arun(
*,
validate: bool | None = None,
deep_validation: bool | None = None,
- ) -> dict:
- """Run a task by name and wait for its results.
-
- The same as ``await client...run(**parameters)``, for names held as
- strings. Names may be spelled as the platform publishes them or with underscores.
+ check_schemas: bool | None = None,
+ ) -> TaskResult:
+ """Discover the task (cached), resolve and validate the parameters, submit, and hydrate the results.
:param topic: The task topic.
:param task: The task name.
:param parameters: The task parameters, plus ``preview=True`` to run a preview task.
- :param validate: Override the client's shallow-validation setting for this call.
- The master switch: ``False`` skips deep validation too.
+ :param validate: Override the client's schema-validation setting for this call.
+ ``False`` skips deep validation too, but never the signature binding that
+ builds the payload.
:param deep_validation: Override the client's deep-validation setting for this call.
Only consulted when validation is enabled.
+ :param check_schemas: Override the client's supported-schema setting for this call.
+ Falls back to ``validate`` when neither is set.
- :return: The results of the finished job.
+ :return: The hydrated results of the finished job.
:raises AttributeError: If the topic does not advertise the task.
- :raises ParameterValidationError: If the parameters do not match the task's schema.
+ :raises ParameterValidationError: If the parameters or referenced objects fail validation.
"""
spec = await self._resolve_spec(topic, task)
label = f"{topic}.{_normalise(task)}"
@@ -253,9 +274,18 @@ async def arun(
validate = self._validate
if deep_validation is None:
deep_validation = self._deep_validation
- # ``validate`` is the master switch; deep validation only runs underneath it.
+ if check_schemas is None:
+ check_schemas = self._check_schemas if self._check_schemas is not None else validate
+ # ``validate`` masters the schema checks; ``check_schemas`` stands on its own.
if validate:
- validate_parameters(spec, wire_parameters, deep=deep_validation, task_label=label)
+ # Required fields first: a missing parameter is worth reporting before resolution
+ # spends a request loading the objects the other parameters name.
+ validate_parameters(spec, wire_parameters, task_label=label)
+ wire_parameters = await self._resolver.resolve(
+ spec, wire_parameters, check_schemas=check_schemas, task_label=label
+ )
+ if validate and deep_validation:
+ validate_parameters(spec, wire_parameters, deep=True, task_label=label)
job: JobClient[dict] = await JobClient.submit(
connector=self._connector,
@@ -266,7 +296,7 @@ async def arun(
result_type=dict,
preview=preview,
)
- return await job.wait_for_results()
+ return TaskResult(await job.wait_for_results(), spec.results, self._context)
async def _resolve_spec(self, topic: str, task: str) -> TaskResource:
"""Return the discovery spec for ``topic``/``task``, whether spelled with hyphens or underscores.
@@ -338,7 +368,7 @@ def _make_run(client: ComputeClient, topic: str, task: str):
discovery is never triggered by attribute access alone.
"""
- async def run(**parameters: Any) -> dict:
+ async def run(**parameters: Any) -> TaskResult:
try:
return await client.arun(topic, task, parameters)
finally:
diff --git a/packages/evo-compute/src/evo/compute/outputs.py b/packages/evo-compute/src/evo/compute/outputs.py
new file mode 100644
index 00000000..55ccf9b9
--- /dev/null
+++ b/packages/evo-compute/src/evo/compute/outputs.py
@@ -0,0 +1,200 @@
+# Copyright © 2026 Bentley Systems, Incorporated
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+# http://www.apache.org/licenses/LICENSE-2.0
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Output hydration: the references a task returns, back as typed objects.
+
+A task's results are references too -- ``{"reference": "", "name": ..., "schema_id":
+...}`` for an object it wrote, a JMESPath expression for the attribute it filled in. The
+task's published ``results`` schema marks each of those with an ``output`` annotation, which
+is all :class:`TaskResult` needs to hand the caller a loadable object instead of a URL::
+
+ result = await client.geostatistics.kriging.run(...)
+ grid = await result.target.load()
+ frame = await result.target.to_dataframe()
+ estimates = await result.target.attribute.to_dataframe()
+
+An ``output: attribute`` node names an attribute rather than an object, so it carries the
+same two annotations the input side uses to place one: ``attribute_from``, a relative JSON
+pointer to the object the attribute lives on, and ``attribute_path``, the container each
+object family keeps attributes in. A task publishes one expression for every family it
+supports, so the container it names can be the wrong one for the object actually written --
+:meth:`ResultNode.load` repairs it from ``attribute_path`` rather than reporting a miss.
+
+:class:`TaskResult` and :class:`ResultNode` subclass :class:`dict`, so the raw payload is
+still available exactly as the platform sent it -- ``result["target"]["reference"]`` and
+``result == {...}`` behave as they did before hydration existed. Attribute access and the
+loaders are additions on top, driven entirely by the schema; nothing here is task-specific.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from typing import TYPE_CHECKING, Any
+
+from evo.common import IContext
+from evo.objects import ObjectSchema
+from evo.objects.typed import BaseObject, object_from_reference
+
+# ``attribute_path`` means the same thing on the way in and on the way out, so both sides
+# read it through the same helpers rather than agreeing by convention.
+from .resolution import _container_for, _container_of, _pointer_value
+from .tasks.common.source_target import AnyTypedAttribute
+
+if TYPE_CHECKING:
+ import pandas as pd
+
+__all__ = [
+ "ResultNode",
+ "TaskResult",
+]
+
+
+class ResultNode(dict):
+ """One object in a task's result payload, viewed through its ``results`` schema.
+
+ Nested objects and arrays of objects are hydrated into further nodes, so the whole
+ result is reachable by attribute access. Nodes annotated ``output: geoscience-object``
+ or ``output: attribute`` additionally offer :meth:`load` and :meth:`to_dataframe`.
+ """
+
+ def __init__(
+ self,
+ payload: dict,
+ schema: dict[str, Any] | None,
+ context: IContext,
+ *,
+ root: dict | None = None,
+ path: tuple[str, ...] = (),
+ ) -> None:
+ """
+ :param payload: The raw payload for this node.
+ :param schema: The ``results`` subschema describing it, if the task published one.
+ :param context: An authenticated Evo context, used to load referenced objects.
+ :param root: The whole result payload, which ``attribute_from`` pointers index into.
+ :param path: Where this node sits in that payload, which they are relative to.
+ """
+ self._schema = schema if isinstance(schema, dict) else {}
+ self._context = context
+ self._root: dict = self if root is None else root
+ self._path = path
+ properties = self._schema.get("properties", {}) or {}
+ super().__init__(
+ {
+ name: _hydrate(value, properties.get(name), context, self._root, (*path, name))
+ for name, value in payload.items()
+ }
+ )
+
+ def __getattr__(self, name: str) -> Any:
+ # Result fields are whatever the payload carried, so they cannot be declared up
+ # front. Only fires for names that are not real attributes of the dict itself.
+ if name.startswith("_") or name not in self:
+ raise AttributeError(name)
+ return self[name]
+
+ def __dir__(self) -> list[str]:
+ return sorted(set(super().__dir__()) | {key for key in self if isinstance(key, str) and key.isidentifier()})
+
+ async def load(self) -> BaseObject | AnyTypedAttribute:
+ """Load whatever this node refers to, as its typed class.
+
+ :return: The typed object for an ``output: geoscience-object`` node, or the typed
+ attribute for an ``output: attribute`` one.
+
+ :raises TypeError: If this node is not annotated as either.
+ :raises ValueError: If an attribute's owning object cannot be identified, or the
+ attribute is not on it.
+ """
+ match self._schema.get("output"):
+ case "geoscience-object":
+ return await object_from_reference(self._context, self["reference"])
+ case "attribute":
+ return await self._load_attribute()
+ raise TypeError("this result is not a geoscience object or attribute reference")
+
+ async def to_dataframe(self, *keys: str) -> pd.DataFrame:
+ """Load what this node refers to and read it into a DataFrame.
+
+ :param keys: Attributes to include, if the object's type accepts a selection. An
+ ``output: attribute`` node is a single column and takes none.
+
+ :raises TypeError: If this node is not a geoscience object or attribute reference.
+ """
+ loaded = await self.load()
+ if isinstance(loaded, BaseObject):
+ return await loaded.to_dataframe(*keys)
+ if keys:
+ raise TypeError("an attribute result is a single column and takes no keys")
+ return await loaded.to_dataframe()
+
+ async def _load_attribute(self) -> AnyTypedAttribute:
+ """The typed attribute this node names, on the object ``attribute_from`` points to."""
+ leaf = (self._schema.get("properties") or {}).get("reference") or {}
+ pointer = leaf.get("attribute_from")
+ reference = _pointer_value(pointer, [*self._path, "reference"], self._root) if pointer else None
+ if not isinstance(reference, str):
+ raise ValueError(f"cannot tell which object this attribute belongs to (attribute_from={pointer!r})")
+
+ owner = await object_from_reference(self._context, reference)
+ expression = self["reference"]
+ if (match := _search(owner, expression)) is None:
+ expression = _healed(expression, leaf.get("attribute_path"), owner.metadata.schema_id)
+ match = _search(owner, expression)
+ if match is None:
+ raise ValueError(f"{expression!r} matches no attribute on {reference}")
+
+ # Every family that can carry a compute attribute exposes its ``attribute_path``
+ # container as ``attributes`` -- ``locations.attributes`` on a pointset,
+ # ``cell_attributes`` on a grid -- so the typed lookup needs no per-family code.
+ container = getattr(owner, "attributes", None)
+ found = None if container is None else container[match.get("key") or match["name"]]
+ if found is None or not found.exists:
+ raise ValueError(f"{expression!r} is not an attribute {type(owner).__name__} exposes")
+ return found
+
+
+class TaskResult(ResultNode):
+ """What a task returned, hydrated against the ``results`` schema it published.
+
+ A :class:`dict` of the raw payload, plus attribute access and typed loaders for the
+ parts the schema marks as outputs. A task that publishes no ``results`` schema simply
+ yields the payload unhydrated.
+ """
+
+
+def _hydrate(value: Any, schema: Any, context: IContext, root: dict, path: tuple[str, ...]) -> Any:
+ """Wrap the objects inside ``value``, leaving scalars and nulls as they came."""
+ if isinstance(value, dict):
+ return ResultNode(value, schema, context, root=root, path=path)
+ if isinstance(value, list):
+ items = schema.get("items") if isinstance(schema, dict) else None
+ return [_hydrate(item, items, context, root, (*path, str(index))) for index, item in enumerate(value)]
+ return value
+
+
+def _search(owner: BaseObject, expression: str) -> Mapping[str, Any] | None:
+ """The first attribute a JMESPath expression selects on an object, if it selects any."""
+ found = owner.search(expression)
+ if isinstance(found, Sequence) and not isinstance(found, (str, bytes)):
+ found = found[0] if len(found) else None
+ return found if isinstance(found, Mapping) else None
+
+
+def _healed(expression: str, containers: Any, schema: ObjectSchema) -> str:
+ """Point an attribute expression at the container this object's family actually uses.
+
+ A task supporting several object families publishes one expression for all of them, so a
+ result can name ``locations.attributes`` for an object that keeps its attributes under
+ ``cell_attributes``. ``attribute_path`` says which is right; the predicate is left alone.
+ """
+ if (container := _container_for(containers, schema)) is None:
+ return expression
+ return container + expression[len(_container_of(expression)) :]
diff --git a/packages/evo-compute/src/evo/compute/resolution.py b/packages/evo-compute/src/evo/compute/resolution.py
new file mode 100644
index 00000000..9346e919
--- /dev/null
+++ b/packages/evo-compute/src/evo/compute/resolution.py
@@ -0,0 +1,608 @@
+# Copyright © 2026 Bentley Systems, Incorporated
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+# http://www.apache.org/licenses/LICENSE-2.0
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Reference resolution: friendly Python inputs in, wire-shaped payload out.
+
+Compute tasks address data by reference -- an object URL, a JMESPath expression naming an
+attribute, a File API URL. Asking callers to build those by hand is the ergonomic gap the
+typed geostatistics tasks close with :class:`~evo.compute.tasks.Source` /
+:class:`~evo.compute.tasks.Target`. :class:`ReferenceResolver` generalises that: it reads
+the reference annotations off *any* task's published schema, so one walker serves every
+task in the catalogue with no per-task code.
+
+The annotations it acts on (the closed vocabulary the platform publishes):
+
+.. code-block:: text
+
+ reference_to: geoscience-object -> a validated object URL
+ reference_to: attribute -> a JMESPath expression
+ reference_to: file -> a File API URL
+ supported_schemas: [...] -> object families/versions the leaf accepts
+ attribute_from: -> which sibling object an attribute lives on
+ attribute_path: {pattern: [...]} -> per-object-family JMESPath container
+ target: attribute -> a create/update attribute slot
+ discriminator: -> tagged union; pick the branch by the tag
+
+Resolution reuses the very helpers the hand-written runners use
+(:mod:`evo.compute.tasks.common.source_target`), so the two paths agree on the wire by
+construction rather than by convention. It is also idempotent: a value that is already in
+its wire form -- a URL string, a ready JMESPath expression, a ``{"operation": ...}`` dict
+-- passes through untouched, so there is nothing to switch off.
+
+``supported_schemas`` is enforced as a hard error when the referenced object's schema can
+be established, either from a typed object the caller already holds or from a metadata
+download. When the object cannot be loaded (a cross-hub reference, a transient objects-API
+failure) the check is downgraded to a logged warning: an availability problem must not
+block a job the platform would happily accept, and the platform re-checks server side.
+"""
+
+from __future__ import annotations
+
+import logging
+import operator
+import re
+from dataclasses import dataclass, field
+from typing import Any
+from uuid import UUID
+
+from evo.common import IContext
+from evo.objects import DownloadedObject, ObjectMetadata, ObjectReference, ObjectSchema, SchemaVersion
+from evo.objects.typed import BaseObject
+
+from .endpoints.models import TaskResource
+from .exceptions import ParameterValidationError
+
+# The engine deliberately shares the typed tasks' conversion helpers rather than
+# reimplementing them, so a generic call and a hand-written runner cannot drift apart.
+from .tasks.common.source_target import (
+ AnyTypedAttribute,
+ _convert_object_reference,
+ _get_attribute_expression,
+ _source_from_attribute,
+ _validate_target_attribute,
+)
+
+__all__ = [
+ "ReferenceResolver",
+]
+
+logger = logging.getLogger("compute.resolution")
+
+# A JMESPath filter projection, e.g. ``locations.attributes[?name=='grade']``. Its presence
+# is what separates a ready-made expression from a bare attribute name.
+_PROJECTION = "[?"
+
+# A File API v2 reference: an absolute URL, or the service-relative path form. Deliberately
+# loose -- the aim is to catch a local filename, not to spell out a grammar this package has
+# no File API client to check against.
+_FILE_REFERENCE = re.compile(r"(?:https://|/file/)", re.IGNORECASE)
+
+# What a caller may hand over in place of an object: anything ``_convert_object_reference``
+# accepts, plus the bare object id ``_as_uuid`` expands.
+_OBJECT_HANDLE = (str, UUID, BaseObject, DownloadedObject, ObjectMetadata)
+
+# One bound of a ``supported_schemas`` version range, e.g. ``>=1.2`` or ``<2``.
+_BOUND = re.compile(r"(?P>=|<=|>|<|==|=)?\s*(?P\d+(?:\.\d+)*)")
+
+_COMPARISONS = {
+ ">=": operator.ge,
+ "<=": operator.le,
+ ">": operator.gt,
+ "<": operator.lt,
+ "=": operator.eq,
+ "==": operator.eq,
+}
+
+
+@dataclass
+class _Walk:
+ """State shared by one :meth:`ReferenceResolver.resolve` pass.
+
+ ``resolved`` is filled in as the walk proceeds so an ``attribute_from`` pointer can read
+ a sibling object that was resolved moments earlier; ``supplied`` is the caller's original
+ payload, consulted when a pointer names a parameter the walk has not reached yet.
+ """
+
+ schema: dict[str, Any]
+ label: str
+ supplied: dict[str, Any]
+ check_schemas: bool = True
+ resolved: dict[str, Any] = field(default_factory=dict)
+
+
+class ReferenceResolver:
+ """Resolves a task's caller-supplied parameters into the payload the platform expects.
+
+ One instance serves every task. Object schemas are cached for the lifetime of the
+ resolver, so an object referenced by several parameters is only fetched once.
+
+ :param context: An authenticated Evo context, used to load referenced objects.
+ """
+
+ def __init__(self, context: IContext) -> None:
+ self._context = context
+ self._schemas: dict[str, ObjectSchema | None] = {}
+
+ async def resolve(
+ self,
+ spec: TaskResource,
+ parameters: dict[str, Any],
+ *,
+ check_schemas: bool = True,
+ task_label: str | None = None,
+ ) -> dict[str, Any]:
+ """Resolve every reference in ``parameters`` against the task's parameter schema.
+
+ :param spec: The discovered task, carrying its ``parameters`` JSON Schema.
+ :param parameters: The parameters the caller supplied, keyed by wire name.
+ :param check_schemas: Enforce ``supported_schemas`` on object references.
+ :param task_label: A ``topic.task`` label for error messages; derived from ``spec``
+ when omitted.
+
+ :return: A new payload with every reference in the form the schema declares.
+
+ :raises ParameterValidationError: If a value cannot be resolved to a reference, or
+ names an object outside a leaf's ``supported_schemas``.
+ """
+ schema = spec.parameters or {}
+ walk = _Walk(
+ schema=schema,
+ label=task_label or f"{spec.topic}.{spec.name.replace('-', '_')}",
+ supplied=parameters,
+ check_schemas=check_schemas,
+ )
+ properties = schema.get("properties", {}) or {}
+ for name, value in parameters.items():
+ node = _deref(properties.get(name, {}), schema)
+ walk.resolved[name] = await self._resolve_node(node, value, [name], walk)
+ return walk.resolved
+
+ # -- the walk ---------------------------------------------------------- #
+
+ async def _resolve_node(self, node: dict[str, Any], value: Any, path: list[str], walk: _Walk) -> Any:
+ """Resolve one value against the schema node that describes it."""
+ if value is None:
+ return None
+ node = _deref(node, walk.schema)
+
+ # A tagged union describes several shapes; only the tagged branch's annotations apply.
+ if (discriminator := _discriminator_of(node)) is not None:
+ node = _select_branch(node, value, discriminator, walk.schema) or node
+
+ match node.get("reference_to"):
+ case "geoscience-object":
+ return await self._resolve_object(node, value, path, walk)
+ case "attribute":
+ return await self._resolve_attribute(node, value, path, walk)
+ case "file":
+ return _resolve_file(value, path, walk)
+
+ if node.get("target") == "attribute":
+ return await self._resolve_target_attribute(node, value, path, walk)
+
+ # One of the SDK's typed parameter models (Source, Target, a filter, a sub-block frame,
+ # ...). Dumping it yields the shape the schema describes. This happens before the walk
+ # looks for ``properties`` because a union or optional slot has none of its own, and a
+ # model left alone there would reach the wire as a model.
+ if not isinstance(value, (dict, AnyTypedAttribute)) and hasattr(value, "model_dump"):
+ value = value.model_dump(mode="json", by_alias=True)
+
+ if properties := node.get("properties"):
+ if (frame := self._frame_from_attribute(properties, value, path, walk)) is not None:
+ # Carry on into the walk below rather than returning: the frame's object leaf
+ # has to face ``supported_schemas`` like any other.
+ value = frame
+ elif (frame := await self._frame_from_object(properties, value, path, walk)) is not None:
+ _graft(walk.resolved, path, frame)
+ return frame
+ if isinstance(value, dict):
+ # Register the container before descending so a child's ``attribute_from``
+ # can read a sibling object that this same pass has already resolved.
+ resolved: dict[str, Any] = {}
+ _graft(walk.resolved, path, resolved)
+ for key, child in value.items():
+ child_node = _deref(properties.get(key, {}), walk.schema)
+ resolved[key] = await self._resolve_node(child_node, child, [*path, key], walk)
+ return resolved
+
+ if node.get("type") == "array" and isinstance(value, list):
+ items = _deref(node.get("items", {}), walk.schema)
+ return [
+ await self._resolve_node(items, item, [*path, str(index)], walk) for index, item in enumerate(value)
+ ]
+
+ return value
+
+ # -- leaves ------------------------------------------------------------ #
+
+ async def _resolve_object(self, node: dict[str, Any], value: Any, path: list[str], walk: _Walk) -> str:
+ """A ``reference_to: geoscience-object`` leaf: any object handle in, its URL out."""
+ reference = self._object_reference(value, path, walk)
+ # Remember what the caller already knew. An ``attribute_from`` pointer reads the
+ # resolved URL back, and should not pay for a download to learn what the object in
+ # hand had already said.
+ if (metadata := _metadata_of(value)) is not None:
+ self._schemas[reference] = metadata.schema_id
+
+ supported = node.get("supported_schemas")
+ if not walk.check_schemas or not supported:
+ return reference
+
+ schema = await self._object_schema(value, reference)
+ if schema is None:
+ logger.warning(
+ "%s: could not load %s to check it against supported_schemas %s; "
+ "submitting unchecked -- the platform will validate it.",
+ _describe(path, walk),
+ reference,
+ supported,
+ )
+ elif not any(_schema_matches(schema, pattern) for pattern in supported):
+ raise _invalid(path, walk, f"object schema {str(schema)!r} is not one of {supported}")
+ return reference
+
+ async def _resolve_attribute(self, node: dict[str, Any], value: Any, path: list[str], walk: _Walk) -> Any:
+ """A ``reference_to: attribute`` leaf: a typed attribute or a name in, JMESPath out."""
+ if isinstance(value, AnyTypedAttribute):
+ try:
+ return _get_attribute_expression(value)
+ except ValueError as error:
+ raise _invalid(path, walk, str(error)) from None
+ if not isinstance(value, str):
+ # Nothing downstream would catch this: an attribute reference is a string on the
+ # wire, and deep validation relaxes reference leaves.
+ raise _invalid(path, walk, f"expected an attribute name or expression, got {type(value).__name__}")
+ if _PROJECTION in value:
+ return value # already an expression
+ container = await self._attribute_container(node, path, walk)
+ return f"{container}[?name=='{value}']"
+
+ async def _resolve_target_attribute(self, node: dict[str, Any], value: Any, path: list[str], walk: _Walk) -> Any:
+ """A ``target: attribute`` slot: which attribute to create, or which one to update."""
+ if isinstance(value, AnyTypedAttribute):
+ # The slot names the attribute only; the object it belongs to is its sibling.
+ # Mirrors ``source_target._validate_target_attribute`` for that half alone.
+ if value.exists:
+ return {"operation": "update", "reference": _get_attribute_expression(value)}
+ return {"operation": "create", "name": value.name}
+ if isinstance(value, str):
+ return {"operation": "create", "name": value}
+ if hasattr(value, "model_dump"): # a Source/Target-style model built by the caller
+ value = value.model_dump(mode="json", by_alias=True)
+ if isinstance(value, dict) and (branch := _select_branch(node, value, "operation", walk.schema)) is not None:
+ return await self._resolve_node(branch, value, path, walk)
+ return value
+
+ # -- object identity --------------------------------------------------- #
+
+ def _object_reference(self, value: Any, path: list[str], walk: _Walk) -> str:
+ """The URL for an object handle: a UUID is expanded, everything else is delegated."""
+ if (object_id := _as_uuid(value)) is not None:
+ return str(ObjectReference.new(self._context.get_environment(), object_id=object_id))
+ try:
+ return _convert_object_reference(value)
+ except (TypeError, ValueError) as error:
+ raise _invalid(path, walk, str(error)) from None
+
+ async def _object_schema(self, value: Any, reference: str | None = None) -> ObjectSchema | None:
+ """The schema of a referenced object, from metadata in hand or a metadata download.
+
+ Returns ``None`` when the object cannot be loaded, which callers treat as "unknown"
+ rather than as a failure. Both the answer and a failure to get one are cached, so a
+ repeated reference costs at most one request.
+ """
+ if (metadata := _metadata_of(value)) is not None:
+ return metadata.schema_id
+ if reference is None:
+ if (object_id := _as_uuid(value)) is not None:
+ reference = str(ObjectReference.new(self._context.get_environment(), object_id=object_id))
+ elif isinstance(value, str):
+ reference = value
+ else:
+ return None
+ if reference in self._schemas:
+ return self._schemas[reference]
+
+ try:
+ downloaded = await DownloadedObject.from_context(self._context, reference)
+ except Exception as error:
+ # Deliberately broad: any reason the object cannot be read -- a cross-hub
+ # reference, a permissions gap, an outage -- leaves its schema unknown, which
+ # the caller downgrades to a warning rather than a refusal to submit.
+ logger.debug("could not load %s: %s", reference, error)
+ schema = None
+ else:
+ schema = downloaded.metadata.schema_id
+ self._schemas[reference] = schema
+ return schema
+
+ # -- attribute placement ----------------------------------------------- #
+
+ async def _attribute_container(self, node: dict[str, Any], path: list[str], walk: _Walk) -> str:
+ """The JMESPath container an attribute name sits in, chosen by its object's family.
+
+ A pointset keeps attributes under ``locations.attributes`` and a block model under
+ ``attributes``, so the container is only knowable once the owning object -- named by
+ ``attribute_from`` -- is known. ``attributes`` is the fallback when the schema says
+ nothing or the object cannot be identified.
+ """
+ containers = node.get("attribute_path")
+ pointer = node.get("attribute_from")
+ if not containers or not pointer:
+ return "attributes"
+ owner = _pointer_value(pointer, path, walk.resolved, walk.supplied)
+ if owner is None or (schema := await self._object_schema(owner)) is None:
+ return "attributes"
+ if (container := _container_for(containers, schema)) is None:
+ return "attributes"
+ return container
+
+ def _frame_from_attribute(
+ self, properties: dict[str, Any], value: Any, path: list[str], walk: _Walk
+ ) -> dict[str, Any] | None:
+ """Expand a bare typed attribute into the ``{object, attribute}`` frame it implies.
+
+ ``run(source=pointset.attributes["grade"])`` is how the typed tasks are called; the
+ attribute already knows the object it belongs to, so an ``{object, attribute}``
+ parameter can be filled from it alone. The frame is handed back unwalked so its object
+ leaf goes through the ordinary path. Returns ``None`` when this is not that case.
+ """
+ if isinstance(value, dict) or not isinstance(value, AnyTypedAttribute):
+ return None
+ if not {"object", "attribute"} <= properties.keys():
+ return None
+ target = _deref(properties["attribute"], walk.schema).get("target") == "attribute"
+ try:
+ model = _validate_target_attribute(value) if target else _source_from_attribute(value)
+ except ValueError as error:
+ raise _invalid(path, walk, str(error)) from None
+
+ frame: dict[str, Any] = model.model_dump(mode="json", by_alias=True)
+ # The object came with the attribute, so its schema is already in hand; seed the cache
+ # so the leaf can be held to ``supported_schemas`` without paying for a download.
+ if (metadata := _metadata_of(value._obj)) is not None:
+ self._schemas[frame["object"]] = metadata.schema_id
+ return frame
+
+ async def _frame_from_object(
+ self, properties: dict[str, Any], value: Any, path: list[str], walk: _Walk
+ ) -> dict[str, Any] | None:
+ """Expand a bare object into the one-key frame a parameter wraps it in.
+
+ Some parameters are an object and nothing else -- declustering's ``grid``, for one --
+ and the typed tasks let the object be passed straight in rather than spelled out as
+ ``{"object": ...}``. Returns ``None`` when this node is not such a frame.
+ """
+ if isinstance(value, dict) or not isinstance(value, _OBJECT_HANDLE) or len(properties) != 1:
+ return None
+ ((name, leaf),) = properties.items()
+ if _deref(leaf, walk.schema).get("reference_to") != "geoscience-object":
+ return None
+ return {name: await self._resolve_node(leaf, value, [*path, name], walk)}
+
+
+# --------------------------------------------------------------------------- #
+# Schema helpers.
+# --------------------------------------------------------------------------- #
+
+
+def _sole_non_null_branch(node: dict[str, Any]) -> dict[str, Any] | None:
+ """The one real branch of an optional wrapper such as ``anyOf: [X, {"type": "null"}]``.
+
+ The catalogue inlines an optional sub-object and adds ``null`` to its ``type``, but the
+ same schema is just as often written as a union with a null branch. Left uncollapsed,
+ the node carries no ``properties`` of its own and the walk returns everything below it
+ untouched -- a typed attribute inside an optional filter would reach the wire as an
+ object. A tagged union has more than one real branch and is left for the discriminator.
+ """
+ branches = node.get("anyOf") or node.get("oneOf")
+ if not isinstance(branches, list):
+ return None
+ real = [branch for branch in branches if isinstance(branch, dict) and branch.get("type") != "null"]
+ return real[0] if len(real) == 1 and len(real) < len(branches) else None
+
+
+def _deref(node: Any, root: dict[str, Any]) -> dict[str, Any]:
+ """Resolve a local ``$ref`` and collapse an optional wrapper, keeping annotations alongside."""
+ if not isinstance(node, dict):
+ return {}
+ if (branch := _sole_non_null_branch(node)) is not None:
+ node = {**{key: value for key, value in node.items() if key not in ("anyOf", "oneOf")}, **branch}
+ reference = node.get("$ref")
+ if not isinstance(reference, str) or not reference.startswith("#/"):
+ return node
+ target: Any = root
+ for part in reference[2:].split("/"):
+ if not isinstance(target, dict) or part not in target:
+ return node
+ target = target[part]
+ if not isinstance(target, dict):
+ return node
+ return {**target, **{key: value for key, value in node.items() if key != "$ref"}}
+
+
+def _discriminator_of(node: dict[str, Any]) -> str | None:
+ """The property a tagged union is keyed on, or ``None`` if this node is not one."""
+ if not node.get("oneOf") and not node.get("anyOf"):
+ return None
+ discriminator = node.get("discriminator")
+ if isinstance(discriminator, dict):
+ discriminator = discriminator.get("propertyName")
+ return discriminator if isinstance(discriminator, str) else None
+
+
+def _select_branch(node: dict[str, Any], value: Any, key: str, root: dict[str, Any]) -> dict[str, Any] | None:
+ """The ``oneOf``/``anyOf`` branch whose ``key`` constant matches ``value[key]``."""
+ if not isinstance(value, dict) or key not in value:
+ return None
+ for branch in node.get("oneOf") or node.get("anyOf") or []:
+ resolved = _deref(branch, root)
+ if resolved.get("properties", {}).get(key, {}).get("const") == value[key]:
+ return resolved
+ return None
+
+
+def _schema_matches(schema: ObjectSchema, pattern: str) -> bool:
+ """Whether an object schema satisfies a ``supported_schemas``/``attribute_path`` pattern.
+
+ Patterns name an object family and an optional version range, ``pointset/[>=1.2,<2]``.
+ An unparseable bound is treated as satisfied: the family is the part that decides which
+ container an attribute lives in, and over-rejecting a legitimate object is the worse
+ failure.
+ """
+ family, _, bounds = pattern.partition("/")
+ if schema.sub_classification != family:
+ return False
+ return all(_version_satisfies(schema.version, bound) for bound in bounds.strip("[]").split(",") if bound.strip())
+
+
+def _version_satisfies(version: SchemaVersion, bound: str) -> bool:
+ match = _BOUND.fullmatch(bound.strip())
+ if match is None:
+ return True
+ expected = tuple(int(part) for part in match.group("version").split("."))
+ # Compare only as precisely as the bound is written, so ``<2`` admits ``1.9.9``.
+ actual = (version.major, version.minor, version.patch)[: len(expected)]
+ return _COMPARISONS[match.group("op") or ">="](actual, expected)
+
+
+def _container_of(template: str) -> str:
+ """The container an ``attribute_path`` template selects within.
+
+ ``locations.attributes[?attribute_type=='scalar']`` -> ``locations.attributes``. The
+ predicate narrows by attribute type, which a lookup by name does not need.
+ """
+ index = template.find("[")
+ return template[:index] if index != -1 else template
+
+
+def _container_for(containers: Any, schema: ObjectSchema) -> str | None:
+ """The ``attribute_path`` container an object of this schema keeps its attributes in.
+
+ ``None`` when the map says nothing about the object's family, which leaves the caller to
+ decide whether to guess or to leave a reference alone.
+ """
+ if not isinstance(containers, dict):
+ return None
+ for pattern, templates in containers.items():
+ if _schema_matches(schema, pattern):
+ return _container_of(templates[0] if isinstance(templates, list) else templates)
+ return None
+
+
+# --------------------------------------------------------------------------- #
+# Value helpers.
+# --------------------------------------------------------------------------- #
+
+
+def _as_uuid(value: Any) -> UUID | None:
+ """``value`` as a bare object id, or ``None`` if it is not one."""
+ if isinstance(value, UUID):
+ return value
+ if isinstance(value, str) and not value.startswith("http"):
+ try:
+ return UUID(value)
+ except ValueError:
+ return None
+ return None
+
+
+def _metadata_of(value: Any) -> ObjectMetadata | None:
+ """The metadata a caller-supplied object already carries, if it is one."""
+ if isinstance(value, ObjectMetadata):
+ return value
+ if isinstance(value, (BaseObject, DownloadedObject)):
+ return value.metadata
+ return None
+
+
+def _resolve_file(value: Any, path: list[str], walk: _Walk) -> str:
+ """A ``reference_to: file`` leaf: a File API URL, or a handle that carries one.
+
+ The reference is held to a File API shape because nothing downstream would: deep
+ validation relaxes reference leaves, so a local filename would otherwise be submitted as
+ if it were a URL. Building a URL from a local path, and uploading local bytes, are
+ deferred until the import/converter tasks that need them are supported.
+ """
+ if isinstance(value, str):
+ reference = value
+ else:
+ url = getattr(value, "url", None)
+ if url is None:
+ url = getattr(getattr(value, "metadata", None), "url", None)
+ if url is None:
+ raise _invalid(path, walk, f"cannot resolve a file reference from {type(value).__name__}")
+ reference = str(url)
+ if _FILE_REFERENCE.match(reference) is None:
+ raise _invalid(path, walk, f"expected a File API URL, got {reference!r}")
+ return reference
+
+
+def _pointer_value(pointer: str, path: list[str], *roots: dict[str, Any]) -> Any:
+ """Follow an ``attribute_from`` pointer to the object the attribute belongs to.
+
+ Absolute (``/target/object``) indexes from the payload root. Relative (``1/object``)
+ climbs at least that many levels from the attribute's own position -- at least, because
+ the platform writes the same pointer whether the attribute sits directly under a frame
+ or deeper inside that frame's filter, so the nearest enclosing frame that owns the named
+ object is the intended one. ``roots`` are consulted in order, so a resolution pass can
+ prefer the payload it has already resolved and fall back to the caller's original values
+ for pointers the walk has not reached yet.
+ """
+ if pointer.startswith("/"):
+ return _index([segment for segment in pointer.split("/") if segment], roots)
+
+ head, _, rest = pointer.partition("/")
+ try:
+ climb = max(int(head), 1)
+ except ValueError:
+ return None
+ tail = [segment for segment in rest.split("/") if segment]
+ for levels in range(climb, len(path) + 1):
+ if (value := _index(path[:-levels] + tail, roots)) is not None:
+ return value
+ return None
+
+
+def _index(segments: list[str], roots: tuple[dict[str, Any], ...]) -> Any:
+ for root in roots:
+ current: Any = root
+ for segment in segments:
+ if not isinstance(current, dict) or segment not in current:
+ current = None
+ break
+ current = current[segment]
+ if current is not None:
+ return current
+ return None
+
+
+def _graft(root: dict[str, Any], path: list[str], container: dict[str, Any]) -> None:
+ """Attach ``container`` at ``path``, so pointers can read it before it is filled in."""
+ current = root
+ for segment in path[:-1]:
+ nested = current.get(segment)
+ if not isinstance(nested, dict):
+ nested = {}
+ current[segment] = nested
+ current = nested
+ if path:
+ current[path[-1]] = container
+
+
+def _describe(path: list[str], walk: _Walk) -> str:
+ return f"{walk.label}.run(): {'.'.join(path)}"
+
+
+def _invalid(path: list[str], walk: _Walk, message: str) -> ParameterValidationError:
+ location = ".".join(path)
+ detail = f"{location}: {message}"
+ return ParameterValidationError(f"{walk.label}.run(): {detail}", task=walk.label, errors=[detail])
diff --git a/packages/evo-compute/src/evo/compute/validation.py b/packages/evo-compute/src/evo/compute/validation.py
index 84e115bb..1a3a5036 100644
--- a/packages/evo-compute/src/evo/compute/validation.py
+++ b/packages/evo-compute/src/evo/compute/validation.py
@@ -207,6 +207,12 @@ def _iter_schema_nodes(node: Any) -> Iterator[dict[str, Any]]:
def unknown_annotation_keys(schema: dict[str, Any] | None) -> set[str]:
"""Return schema keys that are neither standard JSON Schema nor a known annotation.
+ Two callers, for two audiences. :class:`~evo.compute.discovery.DiscoveryClient` calls it
+ on every fetched catalogue and *warns*, so a caller on an SDK that predates an annotation
+ the platform now publishes learns that the schema is only partly interpreted rather than
+ being blocked by it. The conformance test calls it on bundled schemas and *fails*, so the
+ same drift stops a release rather than reaching users as a warning.
+
:param schema: A task ``parameters`` or ``results`` JSON Schema (or ``None``).
:return: The set of unrecognised annotation keys; empty when the schema only uses
diff --git a/packages/evo-compute/tests/data/discovery-resolution.json b/packages/evo-compute/tests/data/discovery-resolution.json
new file mode 100644
index 00000000..3b1f3f1a
--- /dev/null
+++ b/packages/evo-compute/tests/data/discovery-resolution.json
@@ -0,0 +1,258 @@
+{
+ "limit": 100,
+ "offset": 0,
+ "total": 2,
+ "count": 2,
+ "results": [
+ {
+ "key": "demo/estimate",
+ "topic": "demo",
+ "name": "estimate",
+ "display_name": "Estimate",
+ "version": "1.0.0",
+ "description": "A task shaped like the catalogue's real estimation tasks: nested source/target frames, a recursive filter union behind $ref, and a create-or-update attribute slot.",
+ "parameters": {
+ "type": "object",
+ "additionalProperties": false,
+ "$defs": {
+ "FilterCondition": {
+ "type": "object",
+ "additionalProperties": false,
+ "properties": {
+ "type": {"const": "condition"},
+ "operator": {"type": "string", "enum": ["equal", "greater_than"]},
+ "threshold": {"type": ["number", "null"], "default": null},
+ "attribute": {
+ "type": "string",
+ "reference_to": "attribute",
+ "attribute_from": "/source/object",
+ "attribute_path": {
+ "pointset/[>=1.2,<2]": ["locations.attributes[?attribute_type=='category']"],
+ "block-model/[>=1.0,<2]": ["attributes[?attribute_type=='Utf8']"]
+ }
+ }
+ },
+ "required": ["type", "operator", "attribute"]
+ },
+ "AllOfFilter": {
+ "type": "object",
+ "additionalProperties": false,
+ "properties": {
+ "type": {"const": "all_of"},
+ "filters": {"type": "array", "items": {"$ref": "#/$defs/FilterExpression"}}
+ },
+ "required": ["type", "filters"]
+ },
+ "FilterExpression": {
+ "discriminator": "type",
+ "oneOf": [{"$ref": "#/$defs/FilterCondition"}, {"$ref": "#/$defs/AllOfFilter"}]
+ },
+ "Filter": {
+ "type": "object",
+ "additionalProperties": false,
+ "properties": {
+ "where": {"$ref": "#/$defs/FilterExpression"}
+ },
+ "required": ["where"]
+ }
+ },
+ "properties": {
+ "source": {
+ "type": "object",
+ "additionalProperties": false,
+ "properties": {
+ "object": {
+ "type": "string",
+ "format": "uri",
+ "reference_to": "geoscience-object",
+ "supported_schemas": ["pointset/[>=1.2,<2]", "block-model/[>=1.0,<2]"]
+ },
+ "attribute": {
+ "type": "string",
+ "reference_to": "attribute",
+ "attribute_from": "1/object",
+ "attribute_path": {
+ "pointset/[>=1.2,<2]": ["locations.attributes[?attribute_type=='scalar']"],
+ "block-model/[>=1.0,<2]": ["attributes[?attribute_type=='Float64']"]
+ }
+ },
+ "filter": {
+ "type": "object",
+ "additionalProperties": false,
+ "composite": "filter",
+ "default": null,
+ "properties": {
+ "where": {"$ref": "#/$defs/FilterExpression"}
+ }
+ }
+ },
+ "required": ["object", "attribute"]
+ },
+ "target": {
+ "type": "object",
+ "additionalProperties": false,
+ "properties": {
+ "object": {
+ "type": "string",
+ "format": "uri",
+ "reference_to": "geoscience-object",
+ "supported_schemas": ["pointset/[>=1.2,<2]", "block-model/[>=1.0,<2]"]
+ },
+ "attribute": {
+ "target": "attribute",
+ "oneOf": [
+ {
+ "type": "object",
+ "additionalProperties": false,
+ "properties": {
+ "operation": {"const": "create"},
+ "name": {"type": "string"}
+ },
+ "required": ["operation", "name"]
+ },
+ {
+ "type": "object",
+ "additionalProperties": false,
+ "properties": {
+ "operation": {"const": "update"},
+ "reference": {
+ "type": "string",
+ "reference_to": "attribute",
+ "attribute_from": "2/object",
+ "attribute_path": {
+ "pointset/[>=1.2,<2]": ["locations.attributes[?attribute_type=='scalar']"],
+ "block-model/[>=1.0,<2]": ["attributes[?attribute_type=='Float64']"]
+ }
+ }
+ },
+ "required": ["operation", "reference"]
+ }
+ ]
+ },
+ "filter": {
+ "default": null,
+ "composite": "filter",
+ "anyOf": [{"$ref": "#/$defs/Filter"}, {"type": "null"}]
+ }
+ },
+ "required": ["object", "attribute"]
+ },
+ "report": {
+ "type": ["string", "null"],
+ "reference_to": "file",
+ "default": null
+ },
+ "seeds": {
+ "type": "array",
+ "items": {"type": "integer"},
+ "default": null
+ },
+ "grid": {
+ "type": "object",
+ "additionalProperties": false,
+ "default": null,
+ "properties": {
+ "object": {
+ "type": "string",
+ "format": "uri",
+ "reference_to": "geoscience-object"
+ }
+ },
+ "required": ["object"]
+ },
+ "discretisation": {
+ "default": null,
+ "anyOf": [
+ {
+ "type": "object",
+ "additionalProperties": false,
+ "properties": {
+ "nx": {"type": "integer"},
+ "ny": {"type": "integer"},
+ "nz": {"type": "integer"}
+ }
+ },
+ {"type": "null"}
+ ]
+ },
+ "options": {
+ "type": "object",
+ "additionalProperties": false,
+ "default": null,
+ "properties": {
+ "label": {"type": "string"},
+ "retries": {"type": "integer"}
+ }
+ }
+ },
+ "required": ["source", "target"]
+ },
+ "results": {
+ "type": "object",
+ "properties": {
+ "message": {"type": "string"},
+ "target": {
+ "type": "object",
+ "output": "geoscience-object",
+ "properties": {
+ "reference": {"type": "string", "format": "uri", "reference_to": "geoscience-object"},
+ "name": {"type": "string"},
+ "description": {"type": ["string", "null"]},
+ "schema_id": {"type": "string"},
+ "attribute": {
+ "type": "object",
+ "output": "attribute",
+ "properties": {
+ "reference": {
+ "type": "string",
+ "reference_to": "attribute",
+ "attribute_from": "2/reference",
+ "attribute_path": {
+ "pointset/[>=1.2,<2]": ["locations.attributes[?attribute_type=='scalar']"],
+ "block-model/[>=1.0,<2]": ["attributes[?attribute_type=='Float64']"]
+ }
+ },
+ "name": {"type": "string"}
+ }
+ }
+ }
+ },
+ "extras": {
+ "type": ["array", "null"],
+ "items": {
+ "type": "object",
+ "output": "geoscience-object",
+ "properties": {
+ "reference": {"type": "string", "format": "uri", "reference_to": "geoscience-object"},
+ "name": {"type": "string"}
+ }
+ }
+ },
+ "report": {
+ "type": ["object", "null"],
+ "output": "file",
+ "properties": {
+ "reference": {"type": "string", "reference_to": "file"},
+ "name": {"type": "string"}
+ }
+ }
+ }
+ }
+ },
+ {
+ "key": "demo/import",
+ "topic": "demo",
+ "name": "import",
+ "display_name": "Import",
+ "version": "1.0.0",
+ "description": "A task whose only input is a file reference.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "file": {"type": "string", "reference_to": "file"}
+ },
+ "required": ["file"]
+ }
+ }
+ ]
+}
diff --git a/packages/evo-compute/tests/data/discovery-tasks.json b/packages/evo-compute/tests/data/discovery-tasks.json
index 5c7d0c72..09529dc2 100644
--- a/packages/evo-compute/tests/data/discovery-tasks.json
+++ b/packages/evo-compute/tests/data/discovery-tasks.json
@@ -14,9 +14,10 @@
"parameters": {
"type": "object",
"properties": {
- "source": {"type": "object", "reference_to": "geoscience-object"},
+ "source": {"type": "string", "format": "uri", "reference_to": "geoscience-object"},
"power": {"type": ["number", "null"], "default": null},
"method": {"type": "string", "enum": ["cell", "polygon"], "default": "cell"},
+ "settings": {"type": "object"},
"options": {"default": null}
},
"required": ["source"]
@@ -24,7 +25,24 @@
"results": {
"type": "object",
"properties": {
- "target": {"type": "object", "output": "geoscience-object"}
+ "message": {"type": "string"},
+ "target": {
+ "type": "object",
+ "output": "geoscience-object",
+ "properties": {
+ "reference": {"type": "string", "format": "uri", "reference_to": "geoscience-object"},
+ "name": {"type": "string"},
+ "schema_id": {"type": "string"},
+ "attribute": {
+ "type": "object",
+ "output": "attribute",
+ "properties": {
+ "reference": {"type": "string", "reference_to": "attribute"},
+ "name": {"type": "string"}
+ }
+ }
+ }
+ }
}
}
},
@@ -38,7 +56,7 @@
"parameters": {
"type": "object",
"properties": {
- "distribution": {"type": "object", "reference_to": "geoscience-object"}
+ "distribution": {"type": "string", "format": "uri", "reference_to": "geoscience-object"}
},
"required": ["distribution"]
}
@@ -54,9 +72,9 @@
"parameters": {
"type": "object",
"properties": {
- "source": {"type": "object", "reference_to": "geoscience-object"},
- "target": {"type": "object", "reference_to": "geoscience-object"},
- "variogram": {"type": "object", "reference_to": "geoscience-object"}
+ "source": {"type": "string", "format": "uri", "reference_to": "geoscience-object"},
+ "target": {"type": "string", "format": "uri", "reference_to": "geoscience-object"},
+ "variogram": {"type": "string", "format": "uri", "reference_to": "geoscience-object"}
},
"required": ["source", "target", "variogram"]
}
diff --git a/packages/evo-compute/tests/data/discovery-validation.json b/packages/evo-compute/tests/data/discovery-validation.json
index 8143c156..14c48e35 100644
--- a/packages/evo-compute/tests/data/discovery-validation.json
+++ b/packages/evo-compute/tests/data/discovery-validation.json
@@ -14,7 +14,7 @@
"parameters": {
"type": "object",
"properties": {
- "source": {"type": "object", "reference_to": "geoscience-object"},
+ "source": {"type": "string", "format": "uri", "reference_to": "geoscience-object"},
"mode": {"type": "string", "enum": ["fast", "accurate"]},
"iterations": {"type": "integer", "minimum": 1, "default": null}
},
diff --git a/packages/evo-compute/tests/test_behavior_parity.py b/packages/evo-compute/tests/test_behavior_parity.py
new file mode 100644
index 00000000..dcae4a5e
--- /dev/null
+++ b/packages/evo-compute/tests/test_behavior_parity.py
@@ -0,0 +1,535 @@
+# Copyright © 2026 Bentley Systems, Incorporated
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+# http://www.apache.org/licenses/LICENSE-2.0
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Behavior parity between the hand-written task runners and the generic engine.
+
+The companion suite in :mod:`test_payload_parity` shows the two paths agree on what they
+send. This one shows they agree on what they refuse to send. Each case declares one set of
+*invalid* inputs, hands that same set to a typed runner and to the discovery-driven engine,
+and requires that neither reaches ``JobClient.submit`` and that both raise a comparable
+error.
+
+This suite states the contract it holds the engine to:
+
+* Neither path submits a job. A job that the platform will reject is worse than a local
+ error, so this is the part that actually matters and it is asserted on every case.
+* Both raise a :class:`ValueError` -- pydantic's ``ValidationError`` on the runner side, the
+ SDK's own :class:`~evo.compute.exceptions.ParameterValidationError` on the engine side.
+* Both name the parameter at fault, so a caller can act on either message.
+
+What is deliberately *not* promised is identical text or identical precision. A parameter
+model knows the branch a caller meant and can fault the field inside it; a JSON Schema
+``anyOf`` with no discriminator does not, so the engine reports the parameter and leaves the
+branch open. ``test_an_unknown_kriging_method`` pins both messages side by side rather than
+asserting a likeness that does not exist.
+
+**Value checks are opt-in.** The engine only reproduces the runner's value-level refusals
+under ``deep_validation=True``, which is what these tests use and what a caller who wants
+this behavior has to ask for. Left off -- the default -- the engine still refuses a missing
+parameter, an unknown one, and a reference it cannot resolve, but a value the schema
+disallows is sent for the platform to reject. ``TestWhereTheTwoPathsDiffer`` pins that
+boundary explicitly.
+
+Every task class opens with a case proving its *valid* inputs are accepted by both paths.
+Without it a broken fixture would refuse everything and the whole suite would pass for the
+wrong reason.
+
+The harness is shared with :mod:`test_payload_parity`: same mocked catalogue derived from
+each runner's own parameter model, same fake context, so the two suites cannot drift into
+testing different engines. As there, that makes this a test of the two code paths against
+each other rather than of either against the live catalogue -- the constraints exercised here
+are the ones the runners' own models publish. One of them publishes nothing:
+``SearchNeighborhood`` hand-writes its own wire form, so the fixture can only advertise it as
+an opaque object and the two paths go uncompared inside ``neighborhood``, the most-shared
+nested parameter here. ``TestWhereTheTwoPathsDiffer`` asserts that gap rather than let the
+silence read as agreement.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Iterator
+from contextlib import contextmanager
+from typing import Any
+from unittest import IsolatedAsyncioTestCase, mock
+
+from pydantic import ValidationError
+
+from evo.compute import ComputeClient, DiscoveryClient, ParameterValidationError
+from evo.compute.tasks import CreateAttribute, Source, Target
+from evo.compute.tasks.geostatistics.conditioned_simulator import ConSimRunner
+from evo.compute.tasks.geostatistics.declustering import DeclusteringGrid, DeclusteringRunner, DeclusteringSource
+from evo.compute.tasks.geostatistics.kriging import KrigingMethod, KrigingRunner
+from evo.compute.tasks.geostatistics.location_wise import LocationWiseRunner, LocationWiseTarget
+from test_payload_parity import (
+ GRADE_ATTRIBUTE,
+ GRID_URL,
+ POINTSET_URL,
+ SIMULATIONS_ATTRIBUTE,
+ TARGET_URL,
+ VARIOGRAM_URL,
+ FakeContext,
+ _capture_submit,
+ _search,
+ _SubmitCaptured,
+ task_spec,
+)
+
+#: Where ``JobClient`` is looked up on each path, so submission can be captured there.
+RUNNER_MODULE = "evo.compute.tasks.common.runner"
+ENGINE_MODULE = "evo.compute.engine"
+
+
+# --------------------------------------------------------------------------- #
+# Harness
+# --------------------------------------------------------------------------- #
+
+
+class BehaviorParityTestCase(IsolatedAsyncioTestCase):
+ """Runs one set of inputs through both paths and compares how each refuses it."""
+
+ def setUp(self) -> None:
+ super().setUp()
+ self.context = FakeContext()
+ # Deep validation is what makes the engine as strict about values as a parameter
+ # model is. See TestWhereTheTwoPathsDiffer for what the default does without it.
+ self.client = ComputeClient(self.context, deep_validation=True)
+
+ # -- running one path -------------------------------------------------- #
+
+ @contextmanager
+ def engine(self, **options: Any) -> Iterator[None]:
+ """Point the engine calls inside at a client configured differently from the fixture's."""
+ previous, self.client = self.client, ComputeClient(self.context, **options)
+ try:
+ yield
+ finally:
+ self.client = previous
+
+ async def _attempt(self, module: str, call) -> tuple[mock.AsyncMock, Exception | None]:
+ """Run ``call`` with submission captured: what ``submit`` saw, and what was raised.
+
+ Only the two error types the contract admits are caught, so a bug in this harness --
+ an ``AttributeError`` out of a malformed fixture, say -- fails the test rather than
+ passing for a refusal that never happened.
+ """
+ raised: Exception | None = None
+ with _capture_submit(module) as submit:
+ try:
+ await call()
+ except _SubmitCaptured:
+ pass # the payload is recorded; this path accepted the inputs
+ except (ValueError, TypeError) as error: # which of the two it is, is the question under test
+ raised = error
+ return submit, raised
+
+ def _runner_call(self, runner_cls, inputs: dict[str, Any]):
+ # Built inside the call so that a model the inputs cannot even construct is a refusal
+ # by the runner, which is where a caller would meet it, rather than a test error.
+ return lambda: runner_cls(self.context, runner_cls.params_type(**inputs))
+
+ def _engine_call(self, runner_cls, inputs: dict[str, Any]):
+ task = getattr(self.client.geostatistics, runner_cls.task.replace("-", "_"))
+ return lambda: task.run(**inputs)
+
+ def _catalogue(self, runner_cls):
+ """Serve the engine the task's schema, derived from the runner's own parameter model."""
+ return mock.patch.object(DiscoveryClient, "list_tasks", mock.AsyncMock(return_value=[task_spec(runner_cls)]))
+
+ async def runner_refusal(self, runner_cls, **inputs: Any) -> Exception:
+ """The error the hand-written runner raises for ``inputs``, having submitted nothing."""
+ submit, error = await self._attempt(RUNNER_MODULE, self._runner_call(runner_cls, inputs))
+ return self._refused("runner", submit, error)
+
+ async def engine_refusal(self, runner_cls, **inputs: Any) -> Exception:
+ """The error the generic engine raises for the same inputs, having submitted nothing."""
+ with self._catalogue(runner_cls):
+ submit, error = await self._attempt(ENGINE_MODULE, self._engine_call(runner_cls, inputs))
+ return self._refused("engine", submit, error)
+
+ def _refused(self, path: str, submit: mock.AsyncMock, error: Exception | None) -> Exception:
+ self.assertEqual(0, submit.await_count, f"the {path} submitted a job for parameters it should have refused")
+ if error is None:
+ self.fail(f"the {path} accepted parameters it should have refused")
+ return error
+
+ # -- comparing the two ------------------------------------------------- #
+
+ async def assertBothRefuse(self, runner_cls, parameter: str, **inputs: Any) -> tuple[Exception, Exception]:
+ """Require both paths to refuse ``inputs`` locally, blaming ``parameter``.
+
+ Returns both errors so a case that wants to say more about them can.
+ """
+ runner_error = await self.runner_refusal(runner_cls, **inputs)
+ engine_error = await self.engine_refusal(runner_cls, **inputs)
+ self.assertIsInstance(runner_error, ValueError, f"the runner raised {type(runner_error).__name__}")
+ self.assertIsInstance(engine_error, ParameterValidationError)
+ for path, error in (("runner", runner_error), ("engine", engine_error)):
+ self.assertBlames(path, error, parameter)
+ return runner_error, engine_error
+
+ def assertBlames(self, path: str, error: Exception, parameter: str) -> None:
+ """Require ``error`` to name ``parameter`` as a whole word, not as part of another name.
+
+ A plain substring would let a case pass on an error about a different parameter:
+ ``source`` is inside ``source_filter``, ``variogram`` inside ``variogram_model``.
+ """
+ self.assertRegex(
+ str(error), rf"\b{re.escape(parameter)}\b", f"the {path}'s message does not name {parameter!r}"
+ )
+
+ async def assertBothAccept(self, runner_cls, **inputs: Any) -> None:
+ """Require both paths to get as far as submitting, which is what makes a refusal mean something."""
+ await self.assertRunnerAccepts(runner_cls, **inputs)
+ await self.assertEngineAccepts(runner_cls, **inputs)
+
+ async def assertRunnerAccepts(self, runner_cls, **inputs: Any) -> dict[str, Any]:
+ """Require the runner to submit, and return the payload it submitted."""
+ submit, error = await self._attempt(RUNNER_MODULE, self._runner_call(runner_cls, inputs))
+ self.assertEqual(1, submit.await_count, f"the runner refused parameters it should have accepted: {error}")
+ return submit.await_args.kwargs["parameters"]
+
+ async def assertEngineAccepts(self, runner_cls, **inputs: Any) -> dict[str, Any]:
+ """Require the engine to submit, and return the payload it submitted."""
+ with self._catalogue(runner_cls):
+ submit, error = await self._attempt(ENGINE_MODULE, self._engine_call(runner_cls, inputs))
+ self.assertEqual(1, submit.await_count, f"the engine refused parameters it should have accepted: {error}")
+ return submit.await_args.kwargs["parameters"]
+
+
+# --------------------------------------------------------------------------- #
+# Valid baselines, one per task
+# --------------------------------------------------------------------------- #
+
+
+def declustering_inputs(**overrides: Any) -> dict[str, Any]:
+ inputs: dict[str, Any] = dict(
+ source=DeclusteringSource(object=POINTSET_URL),
+ grid=DeclusteringGrid(object=GRID_URL),
+ target=Target(object=TARGET_URL, attribute=CreateAttribute(name="weights")),
+ neighborhood=_search(),
+ power=2.5,
+ )
+ inputs.update(overrides)
+ return inputs
+
+
+def kriging_inputs(**overrides: Any) -> dict[str, Any]:
+ # Keyed by wire name: ``KrigingParameters`` populates by alias, so one set of inputs
+ # serves both paths without restating anything.
+ inputs: dict[str, Any] = dict(
+ source=Source(object=POINTSET_URL, attribute=GRADE_ATTRIBUTE),
+ target=Target(object=TARGET_URL, attribute=CreateAttribute(name="kriged_grade")),
+ variogram=VARIOGRAM_URL,
+ neighborhood=_search(),
+ kriging_method=KrigingMethod.ORDINARY,
+ )
+ inputs.update(overrides)
+ return inputs
+
+
+def consim_inputs(**overrides: Any) -> dict[str, Any]:
+ inputs: dict[str, Any] = dict(
+ source_object=POINTSET_URL,
+ source_attribute=GRADE_ATTRIBUTE,
+ target_object=GRID_URL,
+ neighborhood=_search(),
+ variogram_model=VARIOGRAM_URL,
+ )
+ inputs.update(overrides)
+ return inputs
+
+
+def location_wise_inputs(**overrides: Any) -> dict[str, Any]:
+ inputs: dict[str, Any] = dict(
+ source=Source(object=POINTSET_URL, attribute=SIMULATIONS_ATTRIBUTE),
+ target=LocationWiseTarget(object=GRID_URL),
+ summary=True,
+ )
+ inputs.update(overrides)
+ return inputs
+
+
+# --------------------------------------------------------------------------- #
+# Declustering
+# --------------------------------------------------------------------------- #
+
+
+class TestDeclusteringBehaviorParity(BehaviorParityTestCase):
+ async def test_valid_parameters_are_accepted_by_both(self) -> None:
+ """The guard for everything below: this baseline is a job both paths would run."""
+ await self.assertBothAccept(DeclusteringRunner, **declustering_inputs())
+
+ async def test_a_missing_required_parameter(self) -> None:
+ """Caught as the call is bound to the schema's signature, so this refusal needs no validation."""
+ inputs = declustering_inputs()
+ del inputs["grid"]
+ await self.assertBothRefuse(DeclusteringRunner, "grid", **inputs)
+
+ async def test_a_power_below_the_allowed_range(self) -> None:
+ """``power`` must be positive, and the bound is published in the schema as well as the model."""
+ await self.assertBothRefuse(DeclusteringRunner, "power", **declustering_inputs(power=-1.0))
+
+ async def test_a_power_that_is_not_a_number(self) -> None:
+ """Neither path lets a word through where a number belongs."""
+ await self.assertBothRefuse(DeclusteringRunner, "power", **declustering_inputs(power="strong"))
+
+ async def test_a_create_target_without_a_name(self) -> None:
+ """A nested field is as required as a top-level one, and both paths say which one it is."""
+ target = {"object": TARGET_URL, "attribute": {"operation": "create"}}
+ await self.assertBothRefuse(DeclusteringRunner, "target", **declustering_inputs(target=target))
+
+ async def test_an_object_reference_that_is_not_a_url(self) -> None:
+ """The reference is checked as it is converted, so this one does not need deep validation."""
+ runner_error, engine_error = await self.assertBothRefuse(
+ DeclusteringRunner, "source", **declustering_inputs(source="not-a-url")
+ )
+ for error in (runner_error, engine_error):
+ self.assertIn("Reference must be a valid HTTPS URL", str(error))
+
+
+# --------------------------------------------------------------------------- #
+# Kriging
+# --------------------------------------------------------------------------- #
+
+
+class TestKrigingBehaviorParity(BehaviorParityTestCase):
+ async def test_valid_parameters_are_accepted_by_both(self) -> None:
+ await self.assertBothAccept(KrigingRunner, **kriging_inputs())
+
+ async def test_a_missing_required_parameter(self) -> None:
+ inputs = kriging_inputs()
+ del inputs["variogram"]
+ await self.assertBothRefuse(KrigingRunner, "variogram", **inputs)
+
+ async def test_a_required_parameter_explicitly_set_to_none(self) -> None:
+ """Supplying ``None`` is not the same as leaving a parameter out, and neither path accepts it."""
+ await self.assertBothRefuse(KrigingRunner, "source", **kriging_inputs(source=None))
+
+ async def test_an_unknown_kriging_method(self) -> None:
+ """Both refuse an unknown method, but only the model can say which branch was meant.
+
+ ``method`` is an untagged union in the model, so the schema derived from it is an
+ ``anyOf`` with no discriminator. Pydantic reports every branch it tried; the engine
+ has no way to pick one, so it reports the parameter and stops there. This is the
+ precision the engine does not promise, written out rather than glossed over.
+ """
+ runner_error, engine_error = await self.assertBothRefuse(
+ KrigingRunner, "kriging_method", **kriging_inputs(kriging_method={"type": "magic"})
+ )
+ self.assertIn("kriging_method.SimpleKriging.type", str(runner_error))
+ self.assertIn(
+ "kriging_method: {'type': 'magic'} is not valid under any of the given schemas", str(engine_error)
+ )
+
+ async def test_a_kriging_method_missing_its_own_field(self) -> None:
+ """Simple kriging needs a mean; a well-formed tag is not a well-formed method."""
+ await self.assertBothRefuse(
+ KrigingRunner, "kriging_method", **kriging_inputs(kriging_method={"type": "simple"})
+ )
+
+ async def test_a_block_discretization_outside_its_range(self) -> None:
+ """1 to 9 per axis, on both paths."""
+ discretization = {"nx": 99, "ny": 3, "nz": 2}
+ await self.assertBothRefuse(
+ KrigingRunner, "block_discretization", **kriging_inputs(block_discretization=discretization)
+ )
+
+ async def test_an_attribute_that_is_not_a_name_or_expression(self) -> None:
+ """Reference leaves are relaxed for deep validation, so resolution is the only gate -- and it holds."""
+ source = {"object": POINTSET_URL, "attribute": 12345}
+ _, engine_error = await self.assertBothRefuse(KrigingRunner, "source", **kriging_inputs(source=source))
+ self.assertIn("source.attribute: expected an attribute name or expression, got int", str(engine_error))
+
+ async def test_a_variogram_that_is_not_an_object_url(self) -> None:
+ """A bare filename is not a geoscience object, however plausible it looks."""
+ await self.assertBothRefuse(KrigingRunner, "variogram", **kriging_inputs(variogram="variogram.json"))
+
+
+# --------------------------------------------------------------------------- #
+# Conditional simulation (consim)
+# --------------------------------------------------------------------------- #
+
+
+class TestConSimBehaviorParity(BehaviorParityTestCase):
+ async def test_valid_parameters_are_accepted_by_both(self) -> None:
+ await self.assertBothAccept(ConSimRunner, **consim_inputs())
+
+ async def test_a_missing_required_parameter(self) -> None:
+ inputs = consim_inputs()
+ del inputs["variogram_model"]
+ await self.assertBothRefuse(ConSimRunner, "variogram_model", **inputs)
+
+ async def test_more_simulations_than_the_task_allows(self) -> None:
+ runner_error, engine_error = await self.assertBothRefuse(
+ ConSimRunner, "number_of_simulations", **consim_inputs(number_of_simulations=500)
+ )
+ self.assertIn("less than or equal to 100", str(runner_error))
+ self.assertIn("500 is greater than the maximum of 100", str(engine_error))
+
+ async def test_fewer_lines_than_the_task_allows(self) -> None:
+ await self.assertBothRefuse(ConSimRunner, "number_of_lines", **consim_inputs(number_of_lines=0))
+
+ async def test_an_unknown_kriging_method(self) -> None:
+ """A closed set of strings is the one union shape the engine can be precise about."""
+ _, engine_error = await self.assertBothRefuse(
+ ConSimRunner, "kriging_method", **consim_inputs(kriging_method="magic")
+ )
+ self.assertIn("kriging_method: must be one of ['simple', 'ordinary'], got 'magic'", str(engine_error))
+
+ async def test_a_filter_with_an_unknown_operator(self) -> None:
+ """A filter is a parameter like any other, and its contents are checked like any other."""
+ source_filter = {
+ "where": {"type": "condition", "attribute": GRADE_ATTRIBUTE, "operator": "roughly"},
+ }
+ await self.assertBothRefuse(ConSimRunner, "source_filter", **consim_inputs(source_filter=source_filter))
+
+ async def test_a_discretization_outside_its_range(self) -> None:
+ """A sub-object that is not optional is descended into, so the engine names the axis too."""
+ discretization = {"nx": 0, "ny": 1, "nz": 1}
+ _, engine_error = await self.assertBothRefuse(
+ ConSimRunner, "block_discretization", **consim_inputs(block_discretization=discretization)
+ )
+ self.assertIn("block_discretization.nx: 0 is less than the minimum of 1", str(engine_error))
+
+
+# --------------------------------------------------------------------------- #
+# Location-wise
+# --------------------------------------------------------------------------- #
+
+
+class TestLocationWiseBehaviorParity(BehaviorParityTestCase):
+ async def test_valid_parameters_are_accepted_by_both(self) -> None:
+ await self.assertBothAccept(LocationWiseRunner, **location_wise_inputs())
+
+ async def test_a_missing_required_parameter(self) -> None:
+ inputs = location_wise_inputs()
+ del inputs["target"]
+ await self.assertBothRefuse(LocationWiseRunner, "target", **inputs)
+
+ async def test_an_empty_list_of_cutoffs(self) -> None:
+ """Asking for probabilities above no cutoffs at all is a mistake both paths catch."""
+ await self.assertBothRefuse(
+ LocationWiseRunner,
+ "probability_above_cutoff",
+ **location_wise_inputs(probability_above_cutoff={"cutoffs": []}),
+ )
+
+ async def test_quantiles_that_are_not_a_list(self) -> None:
+ await self.assertBothRefuse(LocationWiseRunner, "quantiles", **location_wise_inputs(quantiles="all"))
+
+ async def test_quantiles_that_are_not_numbers(self) -> None:
+ """A list of the right shape but the wrong contents is still refused."""
+ await self.assertBothRefuse(LocationWiseRunner, "quantiles", **location_wise_inputs(quantiles=["low", "high"]))
+
+ async def test_a_source_without_an_attribute(self) -> None:
+ await self.assertBothRefuse(
+ LocationWiseRunner, "source", **location_wise_inputs(source={"object": POINTSET_URL})
+ )
+
+
+# --------------------------------------------------------------------------- #
+# Where the two paths differ
+# --------------------------------------------------------------------------- #
+
+
+class TestWhereTheTwoPathsDiffer(BehaviorParityTestCase):
+ """The cases the contract above does not cover, asserted as they are rather than left implied."""
+
+ async def test_a_misspelled_parameter_reaches_the_platform_from_the_runner_only(self) -> None:
+ """DIVERGENCE, the engine is stricter: a parameter model ignores what it does not recognise.
+
+ None of these models set ``extra="forbid"``, so a typo is dropped in silence and the
+ job runs with a default the caller did not intend. The engine binds the call to a
+ signature synthesised from the schema, so the same typo is a refusal -- and one that
+ does not depend on validation being switched on.
+ """
+ misspelled = declustering_inputs(powr=2.5)
+ del misspelled["power"]
+
+ payload = await self.assertRunnerAccepts(DeclusteringRunner, **misspelled)
+ self.assertNotIn("powr", payload)
+ self.assertEqual(2.0, payload["power"], "the runner should have fallen back to its own default")
+
+ error = await self.engine_refusal(DeclusteringRunner, **misspelled)
+ self.assertIn("got an unexpected keyword argument 'powr'", str(error))
+
+ async def test_a_value_the_model_coerces_is_refused_by_the_engine(self) -> None:
+ """DIVERGENCE, the engine is stricter: pydantic reads ``"500"`` as ``500``; JSON Schema does not.
+
+ The runner submits the number it parsed. The engine has no model to parse with, and
+ forwarding the string as it stands would fail at the platform, so it refuses instead.
+ """
+ coerced = consim_inputs(number_of_lines="500")
+ await self.assertRunnerAccepts(ConSimRunner, **coerced)
+ error = await self.engine_refusal(ConSimRunner, **coerced)
+ self.assertIn("number_of_lines: expected type integer, got str", str(error))
+
+ async def test_an_unsupported_object_handle_is_refused_by_both_but_not_alike(self) -> None:
+ """DIVERGENCE, in the error type: the runner raises ``TypeError``, outside the contract.
+
+ ``_convert_object_reference`` raises ``TypeError`` for a value that is no kind of
+ object handle, and pydantic re-wraps ``ValueError`` but not ``TypeError``, so it
+ surfaces raw rather than as a ``ValidationError``. The engine meets it later and
+ elsewhere: an int never looks like the object frame ``source`` declares, so it is
+ deep validation rather than resolution that stops it. Both refuse and neither
+ submits, so the part of the contract that matters holds; the ``except ValueError`` a
+ caller might write around either path does not.
+ """
+ unsupported = declustering_inputs(source=12345)
+ runner_error = await self.runner_refusal(DeclusteringRunner, **unsupported)
+ engine_error = await self.engine_refusal(DeclusteringRunner, **unsupported)
+ self.assertIsInstance(runner_error, TypeError)
+ self.assertNotIsInstance(runner_error, ValidationError)
+ self.assertIn("Cannot convert object reference from type int", str(runner_error))
+ self.assertIsInstance(engine_error, ParameterValidationError)
+ self.assertIn("source: expected type object, got int", str(engine_error))
+
+ async def test_value_checks_are_opt_in_on_the_engine(self) -> None:
+ """The clarified expectation: without ``deep_validation`` a bad value is the platform's to catch."""
+ too_many = consim_inputs(number_of_simulations=500)
+ with self.engine(): # the default
+ await self.assertEngineAccepts(ConSimRunner, **too_many)
+ with self.engine(deep_validation=True):
+ await self.engine_refusal(ConSimRunner, **too_many)
+
+ async def test_the_default_engine_still_refuses_the_mistakes_it_can_see(self) -> None:
+ """Deep validation buys value checks, not the whole of them: three refusals survive without it."""
+ with self.engine(): # the default
+ missing = consim_inputs()
+ del missing["variogram_model"]
+ self.assertBlames("engine", await self.engine_refusal(ConSimRunner, **missing), "variogram_model")
+
+ unknown = consim_inputs(number_of_liness=500)
+ self.assertBlames("engine", await self.engine_refusal(ConSimRunner, **unknown), "number_of_liness")
+
+ unresolvable = consim_inputs(variogram_model="variogram.json")
+ self.assertBlames("engine", await self.engine_refusal(ConSimRunner, **unresolvable), "variogram_model")
+
+ async def test_the_neighborhood_is_not_compared_field_by_field(self) -> None:
+ """NOT A DIVERGENCE but a gap in the fixture, asserted so that it is not mistaken for parity.
+
+ ``SearchNeighborhood`` hand-writes its own wire form, so its fields stop describing
+ what it sends and ``_writes_its_own_wire_form`` has to advertise it as an opaque
+ object. Deep validation then has nothing to check inside it, and three of the four
+ tasks covered here take a neighborhood -- the most-shared nested parameter in the
+ suite is the one the two paths are not compared on.
+
+ The live catalogue publishes the real schema, so this is the fixture falling short of
+ the engine rather than the engine falling short of the runner.
+ """
+ nonsense = {"ellipsoid": {"ranges": {"major": "wide"}}, "max_samples": 20}
+
+ runner_error = await self.runner_refusal(KrigingRunner, **kriging_inputs(neighborhood=nonsense))
+ self.assertBlames("runner", runner_error, "neighborhood")
+
+ payload = await self.assertEngineAccepts(KrigingRunner, **kriging_inputs(neighborhood=nonsense))
+ self.assertEqual(nonsense, payload["neighborhood"], "the engine saw something the fixture cannot show it")
diff --git a/packages/evo-compute/tests/test_discovery.py b/packages/evo-compute/tests/test_discovery.py
index 5dea640b..22e3ef34 100644
--- a/packages/evo-compute/tests/test_discovery.py
+++ b/packages/evo-compute/tests/test_discovery.py
@@ -23,7 +23,7 @@
from evo.common.utils import get_header_metadata
from data import load_test_data
-from evo.compute import DiscoveryClient, TaskResource
+from evo.compute import DiscoveryClient, TaskResource, discovery
from evo.compute.discovery import DEFAULT_CACHE_TTL_SECONDS
from evo.compute.endpoints.api import DiscoveryApi
from evo.compute.endpoints.models import DiscoveryResponse
@@ -275,3 +275,43 @@ async def test_from_context(self) -> None:
with self.set_discovery_response():
tasks = await client.list_tasks()
self.assertTrue(tasks)
+
+ # -- annotations this SDK does not know -------------------------------- #
+
+ def catalogue_with_annotation(self, key: str) -> dict:
+ """The bundled catalogue with ``key`` planted on the first task's source parameter."""
+ catalogue = json.loads(json.dumps(self.catalogue))
+ catalogue["results"][0]["parameters"]["properties"]["source"][key] = "something-new"
+ return catalogue
+
+ async def test_an_unrecognised_annotation_is_warned_about_not_raised(self) -> None:
+ """The platform moving ahead of the SDK must not stop a caller from running a task."""
+ with self.set_discovery_response(self.catalogue_with_annotation("invented_here")):
+ with self.assertLogs("compute.discovery", level="WARNING") as logged:
+ tasks = await self.client.list_tasks()
+ self.assertEqual(len(self.catalogue["results"]), len(tasks))
+ self.assertIn("'invented_here'", logged.output[0])
+ self.assertIn(f"{tasks[0].topic}.{tasks[0].name}", logged.output[0])
+
+ async def test_a_catalogue_the_sdk_fully_understands_says_nothing(self) -> None:
+ with self.set_discovery_response():
+ with mock.patch.object(discovery.logger, "warning") as warning:
+ await self.client.list_tasks()
+ warning.assert_not_called()
+
+ async def test_the_same_annotation_is_not_reported_again_on_a_refetch(self) -> None:
+ """One line per unknown key, not one per cache expiry."""
+ with self.set_discovery_response(self.catalogue_with_annotation("invented_here")):
+ with mock.patch.object(discovery.logger, "warning") as warning:
+ await self.client.list_tasks()
+ self.clock.advance(DEFAULT_CACHE_TTL_SECONDS + 1)
+ await self.client.list_tasks()
+ warning.assert_called_once()
+
+ async def test_a_result_schema_annotation_is_caught_too(self) -> None:
+ catalogue = json.loads(json.dumps(self.catalogue))
+ catalogue["results"][0]["results"] = {"type": "object", "invented_here": True}
+ with self.set_discovery_response(catalogue):
+ with self.assertLogs("compute.discovery", level="WARNING") as logged:
+ await self.client.list_tasks()
+ self.assertIn("'invented_here'", logged.output[0])
diff --git a/packages/evo-compute/tests/test_engine.py b/packages/evo-compute/tests/test_engine.py
index 2faac28a..337640aa 100644
--- a/packages/evo-compute/tests/test_engine.py
+++ b/packages/evo-compute/tests/test_engine.py
@@ -25,6 +25,22 @@
from evo.compute import ComputeClient, ParameterValidationError
+def _object_url(suffix: str) -> str:
+ """A structurally valid geoscience object URL, which reference resolution insists on."""
+ return (
+ "https://unittest.localhost/geoscience-object"
+ "/orgs/00000000-0000-0000-0000-000000000001"
+ "/workspaces/00000000-0000-0000-0000-000000000002"
+ f"/objects/00000000-0000-0000-0000-0000000000{suffix}"
+ )
+
+
+SOURCE_URL = _object_url("10")
+TARGET_URL = _object_url("20")
+VARIOGRAM_URL = _object_url("30")
+FILE_URL = "https://unittest.localhost/file/v2/orgs/00000000-0000-0000-0000-000000000001/files/mesh"
+
+
def _task(topic: str, name: str, properties: dict[str, Any], required: list[str] | None = None) -> dict[str, Any]:
"""A catalogue entry for a task the shared fixture does not describe."""
return {
@@ -49,6 +65,9 @@ def get_connector(self):
def get_org_id(self):
return self._org_id
+ def get_cache(self):
+ return None
+
class TestComputeClient(TestWithConnector):
def setUp(self) -> None:
@@ -87,20 +106,20 @@ def test_attribute_access_does_not_trigger_discovery(self) -> None:
async def test_run_discovers_then_submits(self) -> None:
"""run() fetches the catalogue, then submits the resolved task."""
with self.catalogue_response(), self.mock_job_client() as submit:
- result = await self.client.geostatistics.declustering.run(source="obj-1")
+ result = await self.client.geostatistics.declustering.run(source=SOURCE_URL)
submit.assert_awaited_once()
kwargs = submit.await_args.kwargs
self.assertEqual("geostatistics", kwargs["topic"])
self.assertEqual("declustering", kwargs["task"])
- self.assertEqual({"source": "obj-1"}, kwargs["parameters"])
+ self.assertEqual({"source": SOURCE_URL}, kwargs["parameters"])
self.assertFalse(kwargs["preview"])
self.assertEqual({"ok": True}, result)
async def test_hyphenated_task_names_are_reachable_with_underscores(self) -> None:
"""``normal_score`` resolves to the platform's ``normal-score``."""
with self.catalogue_response(), self.mock_job_client() as submit:
- await self.client.geostatistics.normal_score.run(distribution="dist-1")
+ await self.client.geostatistics.normal_score.run(distribution=SOURCE_URL)
self.assertEqual("normal-score", submit.await_args.kwargs["task"])
async def test_hyphenated_topics_and_parameters_are_reachable_with_underscores(self) -> None:
@@ -165,22 +184,22 @@ async def test_fallback_parameters_still_reject_missing_and_unexpected_names(sel
async def test_arun_takes_the_names_the_platform_publishes(self) -> None:
with self.catalogue_response(), self.mock_job_client() as submit:
- await self.client.arun("geostatistics", "normal-score", {"distribution": "dist-1"})
+ await self.client.arun("geostatistics", "normal-score", {"distribution": SOURCE_URL})
self.assertEqual("normal-score", submit.await_args.kwargs["task"])
- self.assertEqual({"distribution": "dist-1"}, submit.await_args.kwargs["parameters"])
+ self.assertEqual({"distribution": SOURCE_URL}, submit.await_args.kwargs["parameters"])
async def test_catalogue_is_cached_across_runs(self) -> None:
"""The catalogue is fetched once and reused for later runs (any task/topic)."""
with self.catalogue_response(), self.mock_job_client():
- await self.client.geostatistics.declustering.run(source="obj-1")
- await self.client.geostatistics.kriging.run(source="s", target="t", variogram="v")
+ await self.client.geostatistics.declustering.run(source=SOURCE_URL)
+ await self.client.geostatistics.kriging.run(source=SOURCE_URL, target=TARGET_URL, variogram=VARIOGRAM_URL)
self.assertEqual(1, self.transport.request.call_count)
async def test_catalogue_is_shared_across_topics(self) -> None:
"""One catalogue fetch serves every topic, not just the first one touched."""
with self.catalogue_response(), self.mock_job_client() as submit:
- await self.client.geostatistics.declustering.run(source="obj-1")
- await self.client.converter.obj_import.run(file="mesh.obj")
+ await self.client.geostatistics.declustering.run(source=SOURCE_URL)
+ await self.client.converter.obj_import.run(file=FILE_URL)
self.assertEqual(1, self.transport.request.call_count)
self.assertEqual("converter", submit.await_args.kwargs["topic"])
@@ -194,7 +213,7 @@ async def test_a_run_reads_the_catalogue_once(self) -> None:
self.client._discovery, "list_tasks", wraps=self.client._discovery.list_tasks
) as list_tasks,
):
- await self.client.geostatistics.normal_score.run(distribution="dist-1")
+ await self.client.geostatistics.normal_score.run(distribution=SOURCE_URL)
list_tasks.assert_awaited_once()
# -- parameter forwarding ---------------------------------------------- #
@@ -202,7 +221,7 @@ async def test_a_run_reads_the_catalogue_once(self) -> None:
async def test_schema_defaults_are_not_forwarded(self) -> None:
"""Unset optionals are omitted so the platform applies its own defaults."""
with self.catalogue_response(), self.mock_job_client() as submit:
- await self.client.geostatistics.declustering.run(source="obj-1")
+ await self.client.geostatistics.declustering.run(source=SOURCE_URL)
parameters = submit.await_args.kwargs["parameters"]
self.assertNotIn("method", parameters) # schema default "cell" must not be sent
@@ -211,28 +230,30 @@ async def test_schema_defaults_are_not_forwarded(self) -> None:
async def test_explicit_falsy_values_are_forwarded(self) -> None:
"""A supplied ``0``/``False`` is a real value, not an omission."""
with self.catalogue_response(), self.mock_job_client() as submit:
- await self.client.geostatistics.declustering.run(source="obj-1", power=0.0)
+ await self.client.geostatistics.declustering.run(source=SOURCE_URL, power=0.0)
- self.assertEqual({"source": "obj-1", "power": 0.0}, submit.await_args.kwargs["parameters"])
+ self.assertEqual({"source": SOURCE_URL, "power": 0.0}, submit.await_args.kwargs["parameters"])
async def test_explicit_none_is_forwarded(self) -> None:
"""An explicit ``None`` reaches the wire for a nullable parameter."""
with self.catalogue_response(), self.mock_job_client() as submit:
- await self.client.geostatistics.declustering.run(source="obj-1", power=None)
+ await self.client.geostatistics.declustering.run(source=SOURCE_URL, power=None)
- self.assertEqual({"source": "obj-1", "power": None}, submit.await_args.kwargs["parameters"])
+ self.assertEqual({"source": SOURCE_URL, "power": None}, submit.await_args.kwargs["parameters"])
# -- preview flag ------------------------------------------------------ #
async def test_preview_is_off_by_default_even_for_feature_flagged_tasks(self) -> None:
with self.catalogue_response(), self.mock_job_client() as submit:
- await self.client.geostatistics.kriging.run(source="s", target="t", variogram="v")
+ await self.client.geostatistics.kriging.run(source=SOURCE_URL, target=TARGET_URL, variogram=VARIOGRAM_URL)
self.assertFalse(submit.await_args.kwargs["preview"])
async def test_preview_can_be_enabled(self) -> None:
"""The preview flag is passed to the job, not sent as a task parameter."""
with self.catalogue_response(), self.mock_job_client() as submit:
- await self.client.geostatistics.kriging.run(source="s", target="t", variogram="v", preview=True)
+ await self.client.geostatistics.kriging.run(
+ source=SOURCE_URL, target=TARGET_URL, variogram=VARIOGRAM_URL, preview=True
+ )
self.assertTrue(submit.await_args.kwargs["preview"])
self.assertNotIn("preview", submit.await_args.kwargs["parameters"])
@@ -257,7 +278,7 @@ async def test_unexpected_parameter_raises_validation_error(self) -> None:
"""An unknown keyword argument is rejected, and the error names the task."""
with self.catalogue_response(), self.mock_job_client() as submit:
with self.assertRaises(ParameterValidationError) as ctx:
- await self.client.geostatistics.declustering.run(source="obj-1", bogus=1)
+ await self.client.geostatistics.declustering.run(source=SOURCE_URL, bogus=1)
self.assertIn("geostatistics.declustering.run():", str(ctx.exception))
self.assertIn("bogus", str(ctx.exception))
@@ -270,7 +291,7 @@ async def test_unexpected_parameter_raises_validation_error(self) -> None:
async def test_signature_is_synthesised_after_caching(self) -> None:
"""Once a task is cached, run() advertises a schema-shaped signature."""
with self.catalogue_response(), self.mock_job_client():
- await self.client.geostatistics.declustering.run(source="obj-1")
+ await self.client.geostatistics.declustering.run(source=SOURCE_URL)
run = self.client.geostatistics.declustering.run
signature = inspect.signature(run)
@@ -285,12 +306,13 @@ async def test_signature_is_synthesised_after_caching(self) -> None:
async def test_signature_annotations_follow_the_schema(self) -> None:
"""Parameter annotations are derived from each property's JSON Schema type."""
with self.catalogue_response(), self.mock_job_client():
- await self.client.geostatistics.declustering.run(source="obj-1")
+ await self.client.geostatistics.declustering.run(source=SOURCE_URL)
parameters = inspect.signature(self.client.geostatistics.declustering.run).parameters
self.assertEqual(Literal["cell", "polygon"], parameters["method"].annotation) # enum
self.assertEqual(Optional[float], parameters["power"].annotation) # ["number", "null"]
- self.assertEqual(dict, parameters["source"].annotation) # object
+ self.assertEqual(str, parameters["source"].annotation) # reference leaf
+ self.assertEqual(dict, parameters["settings"].annotation) # object
self.assertEqual(Any, parameters["options"].annotation) # no declared type
self.assertEqual(bool, parameters["preview"].annotation)
@@ -301,7 +323,7 @@ async def test_signature_is_refreshed_on_a_reused_proxy(self) -> None:
self.assertNotIn("source", inspect.signature(run).parameters)
with self.catalogue_response(), self.mock_job_client():
- await run(source="obj-1")
+ await run(source=SOURCE_URL)
self.assertIn("source", inspect.signature(run).parameters)
self.assertIn("source", inspect.signature(task_proxy.run).parameters)
@@ -309,7 +331,7 @@ async def test_signature_is_refreshed_on_a_reused_proxy(self) -> None:
async def test_dir_lists_cached_topics_and_tasks(self) -> None:
"""After a run, tab-completion surfaces the cached topics/tasks."""
with self.catalogue_response(), self.mock_job_client():
- await self.client.geostatistics.declustering.run(source="obj-1")
+ await self.client.geostatistics.declustering.run(source=SOURCE_URL)
self.assertIn("geostatistics", dir(self.client))
self.assertIn("converter", dir(self.client))
diff --git a/packages/evo-compute/tests/test_outputs.py b/packages/evo-compute/tests/test_outputs.py
new file mode 100644
index 00000000..9afab383
--- /dev/null
+++ b/packages/evo-compute/tests/test_outputs.py
@@ -0,0 +1,314 @@
+# Copyright © 2026 Bentley Systems, Incorporated
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+# http://www.apache.org/licenses/LICENSE-2.0
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Hydration of a task's results against the ``results`` schema it publishes.
+
+The payload stays exactly what the platform sent -- these are ``dict`` subclasses, so a
+caller who was indexing the raw JSON keeps working. What is added is attribute access and,
+for the nodes the schema marks ``output: geoscience-object`` or ``output: attribute``, a
+loader that turns the reference back into a typed object or attribute.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Iterator, Mapping, Sequence
+from contextlib import contextmanager
+from typing import Any
+from unittest import IsolatedAsyncioTestCase, mock
+
+from evo.common.test_tools import TestWithConnector
+from evo.objects import ObjectSchema
+from evo.objects.typed import BaseObject
+
+from data import load_test_data
+from evo import jmespath
+from evo.compute import ComputeClient, ResultNode, TaskResult
+from test_resolution import (
+ BLOCK_MODEL,
+ BLOCK_MODEL_URL,
+ POINTSET,
+ POINTSET_URL,
+ SCHEMAS_BY_URL,
+ TARGET_URL,
+ FakeContext,
+)
+
+RESULTS = {
+ "message": "estimated 1000 blocks",
+ "target": {
+ "reference": TARGET_URL,
+ "name": "estimated grid",
+ "description": None,
+ "schema_id": "/objects/pointset/1.2.0/pointset.schema.json",
+ "attribute": {"reference": "locations.attributes[?name=='estimate']", "name": "estimate"},
+ },
+ "extras": [{"reference": POINTSET_URL, "name": "extra"}],
+ "report": None,
+}
+
+# The two families the fixture's ``attribute_path`` knows about, each keeping its attributes
+# somewhere else -- which is what makes an expression written for one wrong for the other.
+POINTSET_DOCUMENT = {"locations": {"attributes": [{"name": "estimate", "key": "abc"}]}}
+BLOCK_MODEL_DOCUMENT = {"attributes": [{"name": "estimate", "key": "abc"}]}
+
+
+def loaded_object(document: dict, schema: ObjectSchema = POINTSET) -> mock.MagicMock:
+ """Stands in for the typed object a result reference downloads to."""
+ obj = mock.MagicMock(spec=BaseObject)
+ obj.metadata.schema_id = schema
+ obj.to_dataframe = mock.AsyncMock(return_value="dataframe")
+ obj.search = lambda expression: jmespath.search(expression, document)
+ obj.attributes = _FakeAttributes(jmespath.search("attributes || locations.attributes", document))
+ return obj
+
+
+class _FakeAttributes:
+ """The name-or-key lookup every typed attribute collection offers."""
+
+ def __init__(self, attributes: Sequence[Mapping[str, Any]]) -> None:
+ self._attributes = attributes
+
+ def __getitem__(self, name: str) -> mock.Mock:
+ for attribute in self._attributes:
+ if name in (attribute["name"], attribute["key"]):
+ found = mock.Mock(exists=True, to_dataframe=mock.AsyncMock(return_value="attribute dataframe"))
+ found.name = attribute["name"]
+ return found
+ return mock.Mock(exists=False)
+
+
+class HydrationTestCase(IsolatedAsyncioTestCase):
+ def setUp(self) -> None:
+ catalogue = load_test_data("discovery-resolution.json")
+ self.schema = catalogue["results"][0]["results"]
+ self.context = FakeContext()
+ self.result = TaskResult(RESULTS, self.schema, self.context)
+
+ @contextmanager
+ def loaded_object(self) -> Iterator[mock.AsyncMock]:
+ """Stub the typed-object download the object loaders delegate to."""
+ obj = mock.Mock()
+ obj.to_dataframe = mock.AsyncMock(return_value="dataframe")
+ loader = mock.AsyncMock(return_value=obj)
+ with mock.patch("evo.compute.outputs.object_from_reference", loader):
+ yield loader
+
+ @contextmanager
+ def objects_service(self, **by_url: mock.MagicMock) -> Iterator[mock.AsyncMock]:
+ """Serve a different typed object per reference, as the objects service would."""
+ loader = mock.AsyncMock(side_effect=lambda _context, reference: by_url[reference])
+ with mock.patch("evo.compute.outputs.object_from_reference", loader):
+ yield loader
+
+
+class TestRawPayloadIsPreserved(HydrationTestCase):
+ """Hydration adds to the payload; it never rewrites it."""
+
+ def test_the_result_still_equals_the_payload_the_platform_sent(self) -> None:
+ self.assertEqual(RESULTS, self.result)
+ self.assertIsInstance(self.result, dict)
+
+ def test_it_still_serialises_as_the_same_json(self) -> None:
+ self.assertEqual(json.loads(json.dumps(RESULTS)), json.loads(json.dumps(self.result)))
+
+ def test_index_access_reaches_every_level(self) -> None:
+ self.assertEqual(TARGET_URL, self.result["target"]["reference"])
+ self.assertEqual("estimate", self.result["target"]["attribute"]["name"])
+
+
+class TestAttributeAccess(HydrationTestCase):
+ """The schema shapes the payload, so it can be read as attributes."""
+
+ def test_nested_objects_become_nodes(self) -> None:
+ self.assertIsInstance(self.result.target, ResultNode)
+ self.assertEqual("estimated grid", self.result.target.name)
+ self.assertEqual("estimate", self.result.target.attribute.name)
+
+ def test_arrays_of_outputs_become_lists_of_nodes(self) -> None:
+ self.assertEqual(1, len(self.result.extras))
+ self.assertIsInstance(self.result.extras[0], ResultNode)
+ self.assertEqual(POINTSET_URL, self.result.extras[0].reference)
+
+ def test_a_nullable_output_that_came_back_null_stays_none(self) -> None:
+ self.assertIsNone(self.result.report)
+
+ def test_an_unknown_field_raises_attribute_error(self) -> None:
+ with self.assertRaises(AttributeError):
+ _ = self.result.nonexistent
+
+ def test_tab_completion_lists_the_fields_that_came_back(self) -> None:
+ self.assertLessEqual({"message", "target", "extras"}, set(dir(self.result)))
+
+
+class TestObjectOutputs(HydrationTestCase):
+ """``output: geoscience-object`` closes the DataFrame -> task -> DataFrame loop."""
+
+ async def test_load_downloads_the_object_the_task_wrote(self) -> None:
+ with self.loaded_object() as loader:
+ loaded = await self.result.target.load()
+ loader.assert_awaited_once_with(self.context, TARGET_URL)
+ self.assertIs(loader.return_value, loaded)
+
+ async def test_to_dataframe_reads_the_loaded_object(self) -> None:
+ with self.loaded_object() as loader:
+ frame = await self.result.target.to_dataframe()
+ self.assertEqual("dataframe", frame)
+ loader.return_value.to_dataframe.assert_awaited_once_with()
+
+ async def test_an_item_of_an_output_array_loads_too(self) -> None:
+ with self.loaded_object() as loader:
+ await self.result.extras[0].load()
+ loader.assert_awaited_once_with(self.context, POINTSET_URL)
+
+ async def test_loading_something_that_is_no_kind_of_reference_is_refused(self) -> None:
+ """A file output is a reference the SDK has no loader for; it is not guessed at."""
+ result = TaskResult({**RESULTS, "report": {"reference": "/file/v2/x", "name": "log"}}, self.schema, None)
+ with self.assertRaises(TypeError):
+ await result.report.load()
+
+ def test_a_file_output_is_left_as_its_reference(self) -> None:
+ """File outputs are surfaced as references until the File API layer lands."""
+ result = TaskResult({**RESULTS, "report": {"reference": "/file/v2/x", "name": "log"}}, self.schema, None)
+ self.assertEqual("/file/v2/x", result.report.reference)
+
+
+class TestAttributeOutputs(HydrationTestCase):
+ """``output: attribute`` names an attribute on a sibling object, not an object."""
+
+ async def test_sdk_array_and_object_search_proxies_load(self) -> None:
+ owner = loaded_object(POINTSET_DOCUMENT)
+ for expression, proxy_type in (
+ ("locations.attributes[?name=='estimate']", jmespath.JMESPathArrayProxy),
+ ("locations.attributes[0]", jmespath.JMESPathObjectProxy),
+ ):
+ with self.subTest(expression=expression):
+ self.assertIsInstance(owner.search(expression), proxy_type)
+ results = {
+ **RESULTS,
+ "target": {**RESULTS["target"], "attribute": {"reference": expression, "name": "estimate"}},
+ }
+ result = TaskResult(results, self.schema, self.context)
+ with self.objects_service(**{TARGET_URL: owner}):
+ attribute = await result.target.attribute.load()
+ self.assertEqual("estimate", attribute.name)
+
+ async def test_the_attribute_is_loaded_from_the_object_attribute_from_points_at(self) -> None:
+ with self.objects_service(**{TARGET_URL: loaded_object(POINTSET_DOCUMENT)}) as loader:
+ attribute = await self.result.target.attribute.load()
+ # ``2/reference`` climbs out of the attribute node to the target that owns it, so the
+ # other object in the payload is not what gets downloaded.
+ loader.assert_awaited_once_with(self.context, TARGET_URL)
+ self.assertEqual("estimate", attribute.name)
+
+ async def test_an_expression_written_for_another_family_is_healed(self) -> None:
+ """One expression is published for every family a task supports; only one can be right."""
+ results = {**RESULTS, "target": {**RESULTS["target"], "reference": BLOCK_MODEL_URL}}
+ result = TaskResult(results, self.schema, self.context)
+ block_model = loaded_object(BLOCK_MODEL_DOCUMENT, BLOCK_MODEL)
+ # Without healing there is nothing to find: the published expression names a
+ # container this family does not have.
+ self.assertIsNone(block_model.search(results["target"]["attribute"]["reference"]))
+ with self.objects_service(**{BLOCK_MODEL_URL: block_model}):
+ attribute = await result.target.attribute.load()
+ self.assertEqual("estimate", attribute.name)
+
+ async def test_to_dataframe_reads_the_attribute_alone(self) -> None:
+ with self.objects_service(**{TARGET_URL: loaded_object(POINTSET_DOCUMENT)}):
+ frame = await self.result.target.attribute.to_dataframe()
+ self.assertEqual("attribute dataframe", frame)
+
+ async def test_an_attribute_is_one_column_and_takes_no_keys(self) -> None:
+ with self.objects_service(**{TARGET_URL: loaded_object(POINTSET_DOCUMENT)}):
+ with self.assertRaises(TypeError):
+ await self.result.target.attribute.to_dataframe("estimate")
+
+ async def test_an_attribute_the_object_does_not_have_is_reported(self) -> None:
+ results = {**RESULTS, "target": {**RESULTS["target"], "attribute": {"reference": "attributes[?name=='x']"}}}
+ result = TaskResult(results, self.schema, self.context)
+ with self.objects_service(**{TARGET_URL: loaded_object(POINTSET_DOCUMENT)}):
+ with self.assertRaises(ValueError) as context:
+ await result.target.attribute.load()
+ self.assertIn("matches no attribute", str(context.exception))
+
+ async def test_an_attribute_with_no_pointer_cannot_name_its_object(self) -> None:
+ node = ResultNode(
+ {"reference": "attributes[?name=='estimate']", "name": "estimate"},
+ {"output": "attribute", "properties": {"reference": {"reference_to": "attribute"}}},
+ self.context,
+ )
+ with self.assertRaises(ValueError) as context:
+ await node.load()
+ self.assertIn("which object this attribute belongs to", str(context.exception))
+
+
+class TestTasksWithoutAResultSchema(HydrationTestCase):
+ """A task that advertises no ``results`` block still yields a usable payload."""
+
+ def test_the_payload_is_returned_as_it_came(self) -> None:
+ result = TaskResult({"message": "done"}, None, self.context)
+ self.assertEqual({"message": "done"}, result)
+ self.assertEqual("done", result.message)
+
+ async def test_nothing_claims_to_be_an_object(self) -> None:
+ result = TaskResult({"target": {"reference": TARGET_URL}}, None, self.context)
+ with self.assertRaises(TypeError):
+ await result.target.load()
+
+
+class TestEngineHydration(TestWithConnector):
+ """``run(...)`` returns the hydrated result, not the bare payload."""
+
+ def setUp(self) -> None:
+ super().setUp()
+ self.context = FakeContext(self.connector)
+ self.catalogue = load_test_data("discovery-resolution.json")
+
+ @contextmanager
+ def catalogue_response(self) -> Iterator[None]:
+ with self.transport.set_http_response(
+ status_code=200,
+ content=json.dumps(self.catalogue),
+ headers={"Content-Type": "application/json"},
+ ):
+ yield
+
+ @contextmanager
+ def mock_job_client(self) -> Iterator[None]:
+ job = mock.Mock()
+ job.wait_for_results = mock.AsyncMock(return_value=RESULTS)
+ with mock.patch("evo.compute.engine.JobClient") as mock_job_client:
+ mock_job_client.submit = mock.AsyncMock(return_value=job)
+ yield
+
+ @contextmanager
+ def objects_service(self) -> Iterator[None]:
+ async def load(_context: Any, reference: str) -> mock.Mock:
+ return mock.Mock(metadata=mock.Mock(schema_id=SCHEMAS_BY_URL[str(reference)]))
+
+ with mock.patch("evo.compute.resolution.DownloadedObject.from_context", mock.AsyncMock(side_effect=load)):
+ yield
+
+ async def run_task(self) -> Any:
+ client = ComputeClient(self.context)
+ with self.catalogue_response(), self.objects_service(), self.mock_job_client():
+ return await client.demo.estimate.run(
+ source={"object": POINTSET_URL, "attribute": "locations.attributes[?name=='grade']"},
+ target={"object": TARGET_URL, "attribute": "estimate"},
+ )
+
+ async def test_the_result_is_hydrated_against_the_result_schema(self) -> None:
+ result = await self.run_task()
+ self.assertIsInstance(result, TaskResult)
+ self.assertEqual("estimated grid", result.target.name)
+
+ async def test_the_result_is_still_the_payload_the_platform_sent(self) -> None:
+ self.assertEqual(RESULTS, await self.run_task())
diff --git a/packages/evo-compute/tests/test_payload_parity.py b/packages/evo-compute/tests/test_payload_parity.py
new file mode 100644
index 00000000..8d7d95a7
--- /dev/null
+++ b/packages/evo-compute/tests/test_payload_parity.py
@@ -0,0 +1,657 @@
+# Copyright © 2026 Bentley Systems, Incorporated
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+# http://www.apache.org/licenses/LICENSE-2.0
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Payload parity between the hand-written task runners and the generic engine.
+
+Each case declares one set of inputs, hands that same set to a typed runner and to the
+discovery-driven engine, and asserts that ``JobClient.submit`` was given the same
+``parameters`` payload by both -- equal in value *and* in type, so a ``1`` never passes
+for a ``1.0``.
+
+Feeding both paths the same inputs is the point. It is the difference between the engine
+being a drop-in replacement for a runner and the engine merely being *capable* of the same
+payload if the caller formats it by hand. The engine earns it through
+:mod:`~evo.compute.resolution`, which turns objects and attributes into the references a
+task's schema declares, reusing ``tasks/common/source_target.py`` so that both paths agree
+by construction rather than by coincidence.
+
+Where the two genuinely disagree, a test says so outright instead of hiding it by reshaping
+the input. Two do: a runner materialises its own client-side field defaults where the engine
+sends only what it was given, and a runner passes a bare attribute name straight through
+where the engine expands it into the JMESPath the platform expects.
+
+One case is deliberately not stated as a single input set. ``source_filter`` is a runner-only
+argument -- ``exclude=True`` on the model, folded into ``source`` before anything is sent --
+so the catalogue does not advertise it and the engine will not take it. That case compares
+wire shapes instead, and the test beside it pins the rejection so the asymmetry stays visible
+rather than reading as parity.
+
+Discovery is mocked rather than recorded, so the suite needs no catalogue fixture and no
+credentials. :func:`task_spec` derives each task's schema from the runner's own parameter
+model: the wire names, which of them are required, and the reference annotations the
+resolver reads. That makes this a test of the two code paths against each other, not of the
+SDK against the live catalogue -- that is schema conformance, and is tested separately.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from contextlib import contextmanager
+from typing import Any, get_args
+from unittest import IsolatedAsyncioTestCase, mock
+
+from evo.common.test_tools import ORG as TEST_ORG
+from evo.objects import ObjectReference
+from evo.objects.typed import Attribute, PendingAttribute
+from evo.objects.typed.base import BaseObject
+from pydantic import BaseModel
+
+from evo.compute import ComputeClient, DiscoveryClient, ParameterValidationError, TaskResource
+from evo.compute.tasks import CreateAttribute, SearchNeighborhood, Source, Target, UpdateAttribute
+from evo.compute.tasks.common import Ellipsoid, EllipsoidRanges, Filter, FilterCondition, Rotation
+from evo.compute.tasks.common.source_target import _convert_object_reference, _get_attribute_expression
+from evo.compute.tasks.geostatistics.conditioned_simulator import ConSimRunner
+from evo.compute.tasks.geostatistics.declustering import DeclusteringGrid, DeclusteringRunner, DeclusteringSource
+from evo.compute.tasks.geostatistics.kriging import BlockDiscretization, KrigingMethod, KrigingRunner
+from evo.compute.tasks.geostatistics.location_wise import (
+ LocationWiseRunner,
+ LocationWiseTarget,
+ MeanAboveCutoff,
+ ProbabilityAboveCutoff,
+)
+
+# --------------------------------------------------------------------------- #
+# Shared inputs
+# --------------------------------------------------------------------------- #
+
+
+def _obj_url(suffix: str) -> str:
+ """A structurally valid geoscience object URL, which the parameter models insist on."""
+ return (
+ "https://hub.test.evo.bentley.com/geoscience-object"
+ "/orgs/00000000-0000-0000-0000-000000000001"
+ "/workspaces/00000000-0000-0000-0000-000000000002"
+ f"/objects/00000000-0000-0000-0000-0000000000{suffix}"
+ )
+
+
+POINTSET_URL = _obj_url("10")
+GRID_URL = _obj_url("20")
+TARGET_URL = _obj_url("30")
+VARIOGRAM_URL = _obj_url("40")
+
+GRADE_ATTRIBUTE = "locations.attributes[?name=='grade']"
+SIMULATIONS_ATTRIBUTE = "locations.attributes[?name=='simulations']"
+
+
+def _typed_object(url: str) -> mock.MagicMock:
+ """Stands in for a typed geoscience object, which the models resolve down to its URL."""
+ obj = mock.MagicMock(spec=BaseObject)
+ obj.metadata.url = ObjectReference(url)
+ return obj
+
+
+def _existing_attribute(key: str, url: str, schema_path: str = "") -> mock.MagicMock:
+ """Stands in for an attribute already on an object, which resolves to a key-based expression."""
+ attribute = mock.MagicMock(spec=Attribute)
+ attribute.key = key
+ attribute.exists = True
+ attribute._context = mock.MagicMock(schema_path=schema_path)
+ attribute._obj = _typed_object(url)
+ return attribute
+
+
+def _pending_attribute(name: str, url: str) -> PendingAttribute:
+ """An attribute that does not exist yet, which resolves to a create operation."""
+ parent = mock.MagicMock()
+ parent._obj = _typed_object(url)
+ return PendingAttribute(parent, name)
+
+
+def _search(min_samples: int | None = 4) -> SearchNeighborhood:
+ return SearchNeighborhood(
+ ellipsoid=Ellipsoid(
+ ranges=EllipsoidRanges(major=200.0, semi_major=150.0, minor=100.0),
+ rotation=Rotation(dip_azimuth=45.0, dip=10.0, pitch=5.0),
+ ),
+ max_samples=20,
+ min_samples=min_samples,
+ )
+
+
+# --------------------------------------------------------------------------- #
+# Type-strict comparison
+# --------------------------------------------------------------------------- #
+
+
+def payload_differences(expected: Any, actual: Any, path: str = "parameters") -> list[str]:
+ """Compare two payloads by value *and* concrete type, reporting every divergence.
+
+ ``==`` alone is too forgiving here: ``1 == 1.0`` and ``True == 1``, yet the platform
+ reads those as different JSON types.
+ """
+ if type(expected) is not type(actual):
+ return [f"{path}: expected {type(expected).__name__} {expected!r}, got {type(actual).__name__} {actual!r}"]
+
+ if isinstance(expected, dict):
+ differences = []
+ for key in sorted(set(expected) - set(actual)):
+ differences.append(f"{path}.{key}: missing, expected {expected[key]!r}")
+ for key in sorted(set(actual) - set(expected)):
+ differences.append(f"{path}.{key}: unexpected, got {actual[key]!r}")
+ for key in expected.keys() & actual.keys():
+ differences += payload_differences(expected[key], actual[key], f"{path}.{key}")
+ return differences
+
+ if isinstance(expected, list):
+ if len(expected) != len(actual):
+ return [f"{path}: expected {len(expected)} item(s), got {len(actual)}"]
+ differences = []
+ for index, (left, right) in enumerate(zip(expected, actual)):
+ differences += payload_differences(left, right, f"{path}[{index}]")
+ return differences
+
+ return [] if expected == actual else [f"{path}: expected {expected!r}, got {actual!r}"]
+
+
+# --------------------------------------------------------------------------- #
+# Harness
+# --------------------------------------------------------------------------- #
+
+
+class FakeContext:
+ """Minimal duck-typed IContext exposing just what the runners and the engine use."""
+
+ def __init__(self) -> None:
+ self._connector = mock.Mock()
+ self._org_id = TEST_ORG.id
+
+ def get_connector(self):
+ return self._connector
+
+ def get_org_id(self):
+ return self._org_id
+
+ def get_environment(self):
+ return mock.Mock()
+
+
+class _SubmitCaptured(Exception):
+ """Raised in place of a real submission, once the payload has been recorded."""
+
+
+@contextmanager
+def _capture_submit(module: str) -> Iterator[mock.AsyncMock]:
+ """Patch ``JobClient`` in ``module`` so submission stops as soon as the payload is known."""
+ submit = mock.AsyncMock(side_effect=_SubmitCaptured)
+ with mock.patch(f"{module}.JobClient") as job_client:
+ job_client.submit = submit
+ yield submit
+
+
+_REFERENCE_ANNOTATIONS = {
+ _convert_object_reference: {"reference_to": "geoscience-object"},
+ _get_attribute_expression: {"reference_to": "attribute"},
+}
+
+
+def _annotation_for(field) -> dict[str, str] | None:
+ """The catalogue annotation a model field corresponds to, if it carries a reference.
+
+ The models already say this, in the validator each reference field is annotated with, so
+ reading it back keeps the mocked schema honest without hand-writing any annotations.
+ """
+ for meta in field.metadata:
+ if (annotation := _REFERENCE_ANNOTATIONS.get(getattr(meta, "func", None))) is not None:
+ return annotation
+ if {CreateAttribute, UpdateAttribute} & set(get_args(field.annotation)):
+ return {"target": "attribute"}
+ return None
+
+
+def _models_reachable_from(model: type[BaseModel], seen: dict[str, type[BaseModel]]) -> dict[str, type[BaseModel]]:
+ """Index every model in ``model``'s field graph by name, matching pydantic's ``$defs`` keys."""
+ if model.__name__ in seen:
+ return seen
+ seen[model.__name__] = model
+ for field in model.model_fields.values():
+ for annotation in (field.annotation, *get_args(field.annotation)):
+ for member in (annotation, *get_args(annotation)):
+ if isinstance(member, type) and issubclass(member, BaseModel):
+ _models_reachable_from(member, seen)
+ return seen
+
+
+def _renest_folded_filters(schema: dict[str, Any], folded: dict[str, Any]) -> None:
+ """Advertise a folded filter where the payload carries it, tagged as the catalogue tags it.
+
+ ``source_filter`` is an input to the model that never reaches the wire: the serializer
+ writes it to ``source.filter``. The catalogue describes the wire, so it advertises the
+ filter under ``source`` and marks it ``composite: "filter"`` -- the annotation for a
+ sub-object the platform composes from a group of fields.
+ """
+ for name, prop in folded.items():
+ owner, _, leaf = name.rpartition("_")
+ if leaf != "filter":
+ continue
+ reference = schema.get("properties", {}).get(owner, {}).get("$ref", "")
+ if (block := schema.get("$defs", {}).get(reference.rpartition("/")[2])) is not None:
+ block.setdefault("properties", {})[leaf] = dict(prop, composite="filter")
+
+
+def _writes_its_own_wire_form(model: type[BaseModel]) -> bool:
+ """Whether ``model`` hand-writes what it sends, rather than serialising its own fields.
+
+ A plain ``@model_serializer`` replaces the payload outright, so the model's fields stop
+ describing what reaches the wire -- ``SearchNeighborhood`` validates ``ellipsoid.ranges``
+ and sends ``ellipsoid.ellipsoid_ranges``. A ``mode="wrap"`` serializer defers to the
+ handler and only adds to what it returns, so those models still describe themselves.
+
+ Advertising such a model's fields anyway would fault every payload built from it. Nothing
+ in this module notices, because deep validation is off here; :mod:`test_behavior_parity`
+ turns it on and is where that would surface. The cost is that nothing inside such a model
+ is compared field by field in the derived-schema fixture.
+ """
+ decorators = model.__pydantic_decorators__.model_serializers.values()
+ return any(decorator.info.mode == "plain" for decorator in decorators)
+
+
+def task_spec(runner_cls) -> TaskResource:
+ """The discovery spec the engine would fetch for ``runner_cls``, built from its own model.
+
+ Departures from a plain ``model_json_schema`` keep this a fair stand-in for the catalogue,
+ which describes the wire and nothing else. Fields the runner folds into another field are
+ ``exclude=True`` -- inputs to the model that never reach the wire -- so they are advertised
+ where the payload carries them rather than at the top level. Reference leaves carry the
+ annotations the resolver reads, without which it would leave a caller's objects and
+ attributes untouched. And a model that hand-writes its own wire form is advertised as the
+ opaque object it is, because its fields are no longer a description of what it sends.
+ """
+ model = runner_cls.params_type
+ schema = model.model_json_schema(by_alias=True, mode="validation")
+ properties = schema.get("properties", {})
+ folded = {field.alias or name for name, field in model.model_fields.items() if field.exclude}
+ schema["properties"] = {name: prop for name, prop in properties.items() if name not in folded}
+ schema["required"] = [name for name in schema.get("required", []) if name not in folded]
+ _renest_folded_filters(schema, {name: properties[name] for name in folded if name in properties})
+
+ models = _models_reachable_from(model, {})
+ definitions = schema.get("$defs", {})
+ for name, block in ((model.__name__, schema), *definitions.items()):
+ if (owner := models.get(name)) is None:
+ continue
+ if name in definitions and _writes_its_own_wire_form(owner):
+ definitions[name] = {"type": "object"}
+ continue
+ for field_name, field in owner.model_fields.items():
+ key = field.alias or field_name
+ if key in block.get("properties", {}) and (annotation := _annotation_for(field)) is not None:
+ block["properties"][key].update(annotation)
+ return TaskResource(topic=runner_cls.topic, name=runner_cls.task, parameters=schema)
+
+
+class PayloadParityTestCase(IsolatedAsyncioTestCase):
+ """Runs one job through both paths and compares what each hands to ``JobClient.submit``."""
+
+ def setUp(self) -> None:
+ super().setUp()
+ self.context = FakeContext()
+ self.client = ComputeClient(self.context)
+
+ async def runner_payload(self, runner_cls, params) -> dict[str, Any]:
+ """The payload the hand-written runner submits for ``params``."""
+ with _capture_submit("evo.compute.tasks.common.runner") as submit:
+ with self.assertRaises(_SubmitCaptured):
+ await runner_cls(self.context, params)
+ return submit.await_args.kwargs["parameters"]
+
+ async def engine_payload(self, runner_cls, **parameters: Any) -> dict[str, Any]:
+ """The payload the generic engine submits for the same job, described as plain JSON."""
+ catalogue = mock.patch.object(
+ DiscoveryClient, "list_tasks", mock.AsyncMock(return_value=[task_spec(runner_cls)])
+ )
+ with catalogue, _capture_submit("evo.compute.engine") as submit:
+ with self.assertRaises(_SubmitCaptured):
+ await getattr(self.client.geostatistics, runner_cls.task.replace("-", "_")).run(**parameters)
+ return submit.await_args.kwargs["parameters"]
+
+ async def payload_difference(self, runner_cls, **inputs: Any) -> list[str]:
+ """How the two payloads differ when both paths are given ``inputs``."""
+ runner_payload = await self.runner_payload(runner_cls, runner_cls.params_type(**inputs))
+ engine_payload = await self.engine_payload(runner_cls, **inputs)
+ return payload_differences(runner_payload, engine_payload)
+
+ async def assertSameInputsParity(self, runner_cls, **inputs: Any) -> None:
+ """Require both paths to submit the same payload when handed the same inputs."""
+ differences = await self.payload_difference(runner_cls, **inputs)
+ if differences:
+ self.fail("engine payload diverges from the runner payload:\n " + "\n ".join(differences))
+
+ def assertPayloadParity(self, runner_payload: dict[str, Any], engine_payload: dict[str, Any]) -> None:
+ differences = payload_differences(runner_payload, engine_payload)
+ if differences:
+ self.fail("engine payload diverges from the runner payload:\n " + "\n ".join(differences))
+
+
+# --------------------------------------------------------------------------- #
+# Declustering
+# --------------------------------------------------------------------------- #
+
+
+class TestDeclusteringPayloadParity(PayloadParityTestCase):
+ def _inputs(self, **overrides: Any) -> dict[str, Any]:
+ inputs: dict[str, Any] = dict(
+ source=DeclusteringSource(object=POINTSET_URL),
+ grid=DeclusteringGrid(object=GRID_URL),
+ target=Target(object=TARGET_URL, attribute=CreateAttribute(name="weights")),
+ neighborhood=_search(),
+ power=2.5,
+ )
+ inputs.update(overrides)
+ return inputs
+
+ async def test_inverse_distance_weighting(self) -> None:
+ """The everyday call: source, grid, target and a search, with an explicit power."""
+ await self.assertSameInputsParity(DeclusteringRunner, **self._inputs())
+
+ async def test_knn_mode_sends_a_null_power(self) -> None:
+ """KNN mode is a literal ``null`` power, not an omitted one; both paths must forward it."""
+ runner_payload = await self.runner_payload(
+ DeclusteringRunner, DeclusteringRunner.params_type(**self._inputs(power=None))
+ )
+ self.assertIn("power", runner_payload)
+ self.assertIsNone(runner_payload["power"])
+ await self.assertSameInputsParity(DeclusteringRunner, **self._inputs(power=None))
+
+ async def test_a_typed_attribute_target_becomes_a_create_operation(self) -> None:
+ """The target is given as the attribute itself, and both paths expand it the same way."""
+ await self.assertSameInputsParity(
+ DeclusteringRunner, **self._inputs(target=_pending_attribute("weights", TARGET_URL))
+ )
+
+ async def test_search_without_min_samples_omits_the_key(self) -> None:
+ """An unset ``min_samples`` is dropped by the neighborhood serializer, not sent as null."""
+ runner_payload = await self.runner_payload(
+ DeclusteringRunner, DeclusteringRunner.params_type(**self._inputs(neighborhood=_search(min_samples=None)))
+ )
+ self.assertNotIn("min_samples", runner_payload["neighborhood"])
+ await self.assertSameInputsParity(DeclusteringRunner, **self._inputs(neighborhood=_search(min_samples=None)))
+
+ async def test_integer_power_is_not_accepted_as_the_float_the_runner_sends(self) -> None:
+ """Guards the comparison itself: the engine's ``2`` must not pass for the runner's ``2.0``."""
+ runner_payload = await self.runner_payload(
+ DeclusteringRunner, DeclusteringRunner.params_type(**self._inputs(power=2.0))
+ )
+ engine_payload = await self.engine_payload(DeclusteringRunner, **self._inputs(power=2))
+ self.assertEqual(
+ ["parameters.power: expected float 2.0, got int 2"],
+ payload_differences(runner_payload, engine_payload),
+ )
+
+ async def test_bare_objects_fill_in_their_frames(self) -> None:
+ """``source``/``grid`` are an object and nothing else, so the object goes straight in."""
+ await self.assertSameInputsParity(
+ DeclusteringRunner,
+ **self._inputs(source=_typed_object(POINTSET_URL), grid=_typed_object(GRID_URL)),
+ )
+
+
+# --------------------------------------------------------------------------- #
+# Kriging
+# --------------------------------------------------------------------------- #
+
+
+class TestKrigingPayloadParity(PayloadParityTestCase):
+ def _inputs(self, **overrides: Any) -> dict[str, Any]:
+ # Keyed by wire name throughout: ``KrigingParameters`` populates by alias, so one set
+ # of inputs serves the runner and the engine without any restating.
+ inputs: dict[str, Any] = dict(
+ source=Source(object=POINTSET_URL, attribute=GRADE_ATTRIBUTE),
+ target=Target(object=TARGET_URL, attribute=CreateAttribute(name="kriged_grade")),
+ variogram=VARIOGRAM_URL,
+ neighborhood=_search(),
+ kriging_method=KrigingMethod.ORDINARY,
+ )
+ inputs.update(overrides)
+ return inputs
+
+ async def test_ordinary_kriging(self) -> None:
+ """``neighborhood``/``kriging_method`` are the aliases of ``search``/``method``."""
+ await self.assertSameInputsParity(KrigingRunner, **self._inputs())
+
+ async def test_simple_kriging_with_block_discretization(self) -> None:
+ """A tagged method object and an optional sub-block frame survive both paths intact."""
+ await self.assertSameInputsParity(
+ KrigingRunner,
+ **self._inputs(
+ kriging_method=KrigingMethod.simple(mean=12.5),
+ block_discretization=BlockDiscretization(nx=3, ny=3, nz=2),
+ ),
+ )
+
+ async def test_typed_attributes_become_urls_and_jmespath_expressions(self) -> None:
+ """An attribute that already exists resolves to a key lookup, and to an *update* target."""
+ runner_payload = await self.runner_payload(
+ KrigingRunner,
+ KrigingRunner.params_type(
+ **self._inputs(
+ source=_existing_attribute("src-key-1", POINTSET_URL, schema_path="locations.attributes"),
+ target=_existing_attribute("tgt-key-9", TARGET_URL),
+ )
+ ),
+ )
+ self.assertEqual("locations.attributes[?key=='src-key-1']", runner_payload["source"]["attribute"])
+ self.assertEqual(
+ {"operation": "update", "reference": "attributes[?key=='tgt-key-9']"}, runner_payload["target"]["attribute"]
+ )
+ await self.assertSameInputsParity(
+ KrigingRunner,
+ **self._inputs(
+ source=_existing_attribute("src-key-1", POINTSET_URL, schema_path="locations.attributes"),
+ target=_existing_attribute("tgt-key-9", TARGET_URL),
+ ),
+ )
+
+ async def test_a_folded_filter_reaches_the_wire_as_a_nested_one(self) -> None:
+ """WIRE SHAPE, NOT SAME INPUTS: ``source_filter`` is an argument only the runner has.
+
+ It is ``exclude=True`` on the model and folded into ``source`` before anything is sent,
+ so the catalogue never advertises it and the engine rejects it -- the test below pins
+ that. What is worth asserting is that the shape the runner folds a filter into is the
+ shape an engine caller writes by hand, so this case compares payloads, not inputs.
+ """
+ source_filter = Filter(where=FilterCondition(attribute=GRADE_ATTRIBUTE, operator="greater_than", threshold=0.5))
+ runner_payload = await self.runner_payload(
+ KrigingRunner, KrigingRunner.params_type(**self._inputs(), source_filter=source_filter)
+ )
+ self.assertNotIn("source_filter", runner_payload)
+
+ nested = {"object": POINTSET_URL, "attribute": GRADE_ATTRIBUTE, "filter": source_filter.model_dump()}
+ engine_payload = await self.engine_payload(KrigingRunner, **self._inputs(source=nested))
+ self.assertPayloadParity(runner_payload, engine_payload)
+
+ async def test_the_folded_filter_fields_are_not_offered_as_engine_parameters(self) -> None:
+ """Folding a filter is runner-side work, so ``source_filter`` is not a task parameter."""
+ self.assertNotIn("source_filter", task_spec(KrigingRunner).parameters["properties"])
+ with self.assertRaises(ParameterValidationError) as caught:
+ await self.engine_payload(
+ KrigingRunner,
+ **self._inputs(),
+ source_filter={"where": {"type": "condition", "attribute": GRADE_ATTRIBUTE, "operator": "in"}},
+ )
+ self.assertIn("source_filter", str(caught.exception))
+
+ async def test_references_inside_a_composite_filter_are_resolved(self) -> None:
+ """WIRE SHAPE, NOT SAME INPUTS: a ``composite`` node is walked like any other.
+
+ The catalogue tags ``source.filter`` ``composite: "filter"``. That annotation only
+ names the group of fields the platform composes, so it must not stop resolution at
+ the node: the attribute the condition filters on carries ``reference_to: attribute``
+ and has to reach the wire as an expression from both paths.
+
+ The engine caller spells out ``values: None`` because the runner does. Its serializer
+ dumps the filter model whole, and unlike the top-level payload that dump keeps the
+ unset keys, so an engine caller matching it has to send them too.
+ """
+ attribute = _existing_attribute("filter-key-2", POINTSET_URL, schema_path="locations.attributes")
+ source_filter = Filter(where=FilterCondition(attribute=attribute, operator="greater_than", threshold=0.5))
+ runner_payload = await self.runner_payload(
+ KrigingRunner, KrigingRunner.params_type(**self._inputs(), source_filter=source_filter)
+ )
+
+ nested = {
+ "object": POINTSET_URL,
+ "attribute": GRADE_ATTRIBUTE,
+ "filter": {
+ "where": {
+ "type": "condition",
+ "attribute": attribute,
+ "operator": "greater_than",
+ "threshold": 0.5,
+ "values": None,
+ }
+ },
+ }
+ engine_payload = await self.engine_payload(KrigingRunner, **self._inputs(source=nested))
+
+ self.assertEqual(
+ "locations.attributes[?key=='filter-key-2']", engine_payload["source"]["filter"]["where"]["attribute"]
+ )
+ self.assertPayloadParity(runner_payload, engine_payload)
+
+ async def test_an_unset_method_is_defaulted_by_the_runner_only(self) -> None:
+ """DIVERGENCE: the runner materialises its ``method`` default; the engine sends nothing.
+
+ The engine forwards only what the caller passed, leaving the platform to apply its own
+ default. Both reach the same job, but not by the same payload. This one is by design,
+ unlike the resolution gaps this suite found, which were fixed rather than recorded.
+ """
+ inputs = self._inputs()
+ del inputs["kriging_method"]
+ self.assertEqual(
+ ["parameters.kriging_method: missing, expected {'type': 'ordinary'}"],
+ await self.payload_difference(KrigingRunner, **inputs),
+ )
+
+ async def test_a_bare_attribute_name_is_expanded_by_the_engine_only(self) -> None:
+ """DIVERGENCE: the runner passes a bare attribute name through; the engine expands it.
+
+ ``_get_attribute_expression`` treats any string as an expression already written, so a
+ name reaches the platform as a name. The engine reads the leaf's ``reference_to:
+ attribute`` and projects the name into the container that attribute's family keeps its
+ attributes in -- ``attributes`` unless the schema names another through
+ ``attribute_path``, which is the container the typed paths above resolve to as well.
+ Only the engine's payload is one the platform can look the attribute up from.
+ """
+ self.assertEqual(
+ ["parameters.source.attribute: expected 'grade', got \"attributes[?name=='grade']\""],
+ await self.payload_difference(
+ KrigingRunner, **self._inputs(source=Source(object=POINTSET_URL, attribute="grade"))
+ ),
+ )
+
+
+# --------------------------------------------------------------------------- #
+# Conditional simulation (consim)
+# --------------------------------------------------------------------------- #
+
+
+class TestConSimPayloadParity(PayloadParityTestCase):
+ #: The runner materialises these from its own field defaults, so an engine caller has to
+ #: pass them for the two payloads to agree. Sending them on both paths is what makes this
+ #: one set of inputs rather than two.
+ RUNNER_DEFAULTS: dict[str, Any] = {
+ "block_discretization": {"nx": 1, "ny": 1, "nz": 1},
+ "kriging_method": "simple",
+ "number_of_lines": 500,
+ "number_of_simulations": 1,
+ "random_seed": 38239342,
+ "number_of_simulations_to_save": 5,
+ "perform_validation": False,
+ }
+
+ def _inputs(self, **overrides: Any) -> dict[str, Any]:
+ inputs: dict[str, Any] = dict(
+ source_object=POINTSET_URL,
+ source_attribute=GRADE_ATTRIBUTE,
+ target_object=GRID_URL,
+ neighborhood=_search(),
+ variogram_model=VARIOGRAM_URL,
+ **self.RUNNER_DEFAULTS,
+ )
+ inputs.update(overrides)
+ return inputs
+
+ async def test_minimal_conditional_simulation(self) -> None:
+ """The flat source shape: object and attribute as separate scalars, not a frame."""
+ await self.assertSameInputsParity(ConSimRunner, **self._inputs())
+
+ async def test_multiple_simulations_with_quantiles(self) -> None:
+ """Counts stay ints and cutoffs stay floats across both paths."""
+ await self.assertSameInputsParity(
+ ConSimRunner,
+ **self._inputs(
+ number_of_simulations=25,
+ number_of_simulations_to_save=3,
+ random_seed=7,
+ location_wise_quantiles=[0.1, 0.5, 0.9],
+ probability_above_cutoff=[1.0, 2.5],
+ ),
+ )
+
+ async def test_unset_defaults_are_supplied_by_the_runner_only(self) -> None:
+ """DIVERGENCE: seven client-side defaults the engine leaves to the platform."""
+ inputs = self._inputs()
+ for name in self.RUNNER_DEFAULTS:
+ del inputs[name]
+ differences = await self.payload_difference(ConSimRunner, **inputs)
+ self.assertEqual(
+ sorted(f"parameters.{name}" for name in self.RUNNER_DEFAULTS),
+ sorted(difference.split(":")[0] for difference in differences),
+ )
+
+
+# --------------------------------------------------------------------------- #
+# Location-wise
+# --------------------------------------------------------------------------- #
+
+
+class TestLocationWisePayloadParity(PayloadParityTestCase):
+ def _inputs(self, **overrides: Any) -> dict[str, Any]:
+ inputs: dict[str, Any] = dict(
+ source=Source(object=POINTSET_URL, attribute=SIMULATIONS_ATTRIBUTE),
+ target=LocationWiseTarget(object=GRID_URL),
+ summary=True,
+ )
+ inputs.update(overrides)
+ return inputs
+
+ async def test_summary_only(self) -> None:
+ """The plain-model control: no aliases, no defaults, no folded fields."""
+ await self.assertSameInputsParity(LocationWiseRunner, **self._inputs())
+
+ async def test_all_statistics(self) -> None:
+ """Quantiles and cutoff lists keep their float element types."""
+ await self.assertSameInputsParity(
+ LocationWiseRunner,
+ **self._inputs(
+ quantiles=[0.1, 0.5, 0.9],
+ probability_above_cutoff=ProbabilityAboveCutoff(cutoffs=[1.0, 2.0]),
+ mean_above_cutoff=MeanAboveCutoff(cutoffs=[1.5]),
+ ),
+ )
+
+ async def test_unset_optionals_stay_off_the_wire(self) -> None:
+ """Neither path invents a statistics block the caller never asked for."""
+ runner_payload = await self.runner_payload(LocationWiseRunner, LocationWiseRunner.params_type(**self._inputs()))
+ for unset in ("quantiles", "probability_above_cutoff", "mean_above_cutoff"):
+ self.assertNotIn(unset, runner_payload)
+ await self.assertSameInputsParity(LocationWiseRunner, **self._inputs())
diff --git a/packages/evo-compute/tests/test_resolution.py b/packages/evo-compute/tests/test_resolution.py
new file mode 100644
index 00000000..2913a715
--- /dev/null
+++ b/packages/evo-compute/tests/test_resolution.py
@@ -0,0 +1,630 @@
+# Copyright © 2026 Bentley Systems, Incorporated
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+# http://www.apache.org/licenses/LICENSE-2.0
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Reference resolution against a task schema shaped like the ones the platform publishes.
+
+``tests/data/discovery-resolution.json`` mirrors the real catalogue rather than a convenient
+simplification: reference leaves are declared as URL *strings*, attribute leaves carry the
+``attribute_from``/``attribute_path`` pair, the filter union sits behind ``$ref``, and the
+target attribute is a create-or-update ``oneOf``. Resolution is only as good as the shapes it
+is tested against, so the fixture has to be the awkward one.
+
+The objects service is stubbed at :meth:`DownloadedObject.from_context`, which is the single
+point where resolution reaches the platform.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Iterator
+from contextlib import contextmanager
+from typing import Any
+from unittest import IsolatedAsyncioTestCase, mock
+from uuid import UUID
+
+from evo.common import Environment
+from evo.common.test_tools import TestWithConnector
+from evo.objects import ObjectMetadata, ObjectReference, ObjectSchema, SchemaVersion
+from evo.objects.typed import Attribute, PendingAttribute
+from evo.objects.typed.base import BaseObject
+
+from data import load_test_data
+from evo.compute import ComputeClient, ParameterValidationError, ReferenceResolver, TaskResource
+from evo.compute.tasks import Source, Target
+from evo.compute.tasks.geostatistics.kriging import BlockDiscretization
+
+HUB_URL = "https://unittest.localhost/"
+ORG_ID = UUID(int=1)
+WORKSPACE_ID = UUID(int=2)
+
+
+def _object_url(suffix: str) -> str:
+ return (
+ f"{HUB_URL.rstrip('/')}/geoscience-object"
+ f"/orgs/{ORG_ID}/workspaces/{WORKSPACE_ID}"
+ f"/objects/00000000-0000-0000-0000-0000000000{suffix}"
+ )
+
+
+POINTSET_URL = _object_url("10")
+BLOCK_MODEL_URL = _object_url("20")
+TARGET_URL = _object_url("30")
+
+POINTSET = ObjectSchema("objects", "pointset", SchemaVersion(1, 2, 0))
+BLOCK_MODEL = ObjectSchema("objects", "block-model", SchemaVersion(1, 0, 0))
+
+SCHEMAS_BY_URL = {POINTSET_URL: POINTSET, BLOCK_MODEL_URL: BLOCK_MODEL, TARGET_URL: POINTSET}
+
+
+class FakeContext:
+ """Minimal duck-typed IContext exposing just what reference resolution uses."""
+
+ def __init__(self, connector: Any = None) -> None:
+ self._connector = connector
+
+ def get_environment(self) -> Environment:
+ return Environment(hub_url=HUB_URL, org_id=ORG_ID, workspace_id=WORKSPACE_ID)
+
+ def get_connector(self) -> Any:
+ return self._connector
+
+ def get_org_id(self) -> UUID:
+ return ORG_ID
+
+ def get_cache(self) -> None:
+ return None
+
+
+def typed_object(url: str, schema: ObjectSchema | None = POINTSET) -> mock.MagicMock:
+ """Stands in for a typed geoscience object the caller already holds."""
+ obj = mock.MagicMock(spec=BaseObject)
+ obj.metadata.url = ObjectReference(url)
+ obj.metadata.schema_id = schema
+ return obj
+
+
+def existing_attribute(key: str, url: str, schema_path: str = "", schema: ObjectSchema = POINTSET) -> mock.MagicMock:
+ """An attribute already on an object, which resolves to a key-based expression."""
+ attribute = mock.MagicMock(spec=Attribute)
+ attribute.key = key
+ attribute.exists = True
+ attribute._context = mock.MagicMock(schema_path=schema_path)
+ attribute._obj = typed_object(url, schema)
+ return attribute
+
+
+def pending_attribute(name: str, url: str, schema: ObjectSchema = POINTSET) -> PendingAttribute:
+ """An attribute that does not exist yet, which resolves to a create operation."""
+ parent = mock.MagicMock()
+ parent._obj = typed_object(url, schema)
+ return PendingAttribute(parent, name)
+
+
+class ResolutionTestCase(IsolatedAsyncioTestCase):
+ """A resolver over the ``demo/estimate`` spec, with the objects service stubbed out."""
+
+ def setUp(self) -> None:
+ catalogue = load_test_data("discovery-resolution.json")
+ self.spec = TaskResource.model_validate(catalogue["results"][0])
+ self.import_spec = TaskResource.model_validate(catalogue["results"][1])
+ self.resolver = ReferenceResolver(FakeContext())
+
+ @contextmanager
+ def objects_service(self, *, unavailable: bool = False) -> Iterator[mock.AsyncMock]:
+ """Stub the metadata download resolution falls back to for a bare reference."""
+
+ async def load(_context: Any, reference: str) -> mock.Mock:
+ if unavailable:
+ raise RuntimeError("objects service unavailable")
+ return mock.Mock(metadata=mock.Mock(schema_id=SCHEMAS_BY_URL[str(reference)]))
+
+ loader = mock.AsyncMock(side_effect=load)
+ with mock.patch("evo.compute.resolution.DownloadedObject.from_context", loader):
+ yield loader
+
+ async def resolve(self, **parameters: Any) -> dict[str, Any]:
+ return await self.resolver.resolve(self.spec, parameters)
+
+
+class TestObjectReferences(ResolutionTestCase):
+ """``reference_to: geoscience-object`` -- any handle in, one validated URL out."""
+
+ async def frame(self, source_object: Any) -> Any:
+ with self.objects_service():
+ resolved = await self.resolve(source={"object": source_object, "attribute": "grade"})
+ return resolved["source"]["object"]
+
+ async def test_a_url_string_is_passed_through_verbatim(self) -> None:
+ """The caller's own reference is submitted as written, version pin and all."""
+ self.assertEqual(POINTSET_URL, await self.frame(POINTSET_URL))
+
+ async def test_an_object_reference_resolves_to_its_string(self) -> None:
+ self.assertEqual(POINTSET_URL, await self.frame(ObjectReference(POINTSET_URL)))
+
+ async def test_a_typed_object_resolves_to_its_url(self) -> None:
+ self.assertEqual(POINTSET_URL, await self.frame(typed_object(POINTSET_URL)))
+
+ async def test_object_metadata_resolves_to_its_url(self) -> None:
+ metadata = mock.MagicMock(spec=ObjectMetadata)
+ metadata.url = ObjectReference(POINTSET_URL)
+ metadata.schema_id = POINTSET
+ self.assertEqual(POINTSET_URL, await self.frame(metadata))
+
+ async def test_a_bare_uuid_is_expanded_in_the_client_workspace(self) -> None:
+ """A caller who only has an object id gets the URL built for them."""
+ object_id = UUID("00000000-0000-0000-0000-000000000010")
+ self.assertEqual(POINTSET_URL, await self.frame(object_id))
+ self.assertEqual(POINTSET_URL, await self.frame(str(object_id)))
+
+ async def test_an_unusable_reference_is_reported_against_its_location(self) -> None:
+ with self.assertRaises(ParameterValidationError) as ctx:
+ await self.frame("not-a-reference")
+ self.assertIn("source.object", str(ctx.exception))
+ self.assertEqual(1, len(ctx.exception.errors))
+
+ async def test_an_unsupported_handle_type_is_rejected(self) -> None:
+ with self.assertRaises(ParameterValidationError) as ctx:
+ await self.frame(12345)
+ self.assertIn("source.object", str(ctx.exception))
+
+
+class TestSupportedSchemas(ResolutionTestCase):
+ """``supported_schemas`` -- a hard error when it can be checked, a warning when it cannot."""
+
+ async def test_a_typed_object_is_checked_without_touching_the_network(self) -> None:
+ with self.objects_service() as loader:
+ await self.resolve(
+ source={"object": typed_object(POINTSET_URL), "attribute": "locations.attributes[?name=='grade']"},
+ target={"object": typed_object(TARGET_URL), "attribute": "estimate"},
+ )
+ loader.assert_not_awaited()
+
+ async def test_an_object_outside_the_supported_set_is_rejected(self) -> None:
+ unsupported = ObjectSchema("objects", "triangle-mesh", SchemaVersion(2, 1, 0))
+ with self.objects_service():
+ with self.assertRaises(ParameterValidationError) as ctx:
+ await self.resolve(source={"object": typed_object(POINTSET_URL, unsupported), "attribute": "grade"})
+ self.assertIn("source.object", str(ctx.exception))
+ self.assertIn("triangle-mesh", str(ctx.exception))
+
+ async def test_a_bare_reference_is_checked_by_loading_the_object_once(self) -> None:
+ """The same object named twice costs one metadata request, not two."""
+ with self.objects_service() as loader:
+ await self.resolve(
+ source={"object": POINTSET_URL, "attribute": "grade"},
+ target={"object": POINTSET_URL, "attribute": "estimate"},
+ )
+ self.assertEqual(1, loader.await_count)
+
+ async def test_an_unloadable_object_warns_instead_of_blocking(self) -> None:
+ """An objects-service outage must not stop a job the platform would accept."""
+ with self.objects_service(unavailable=True):
+ with self.assertLogs("compute.resolution", level="WARNING") as logs:
+ resolved = await self.resolve(source={"object": POINTSET_URL, "attribute": "grade"})
+ self.assertEqual(POINTSET_URL, resolved["source"]["object"])
+ self.assertIn("supported_schemas", logs.output[0])
+
+ async def test_the_check_is_skipped_when_validation_is_off(self) -> None:
+ unsupported = ObjectSchema("objects", "triangle-mesh", SchemaVersion(2, 1, 0))
+ with self.objects_service() as loader:
+ resolved = await self.resolver.resolve(
+ self.spec,
+ {"source": {"object": typed_object(POINTSET_URL, unsupported), "attribute": "grade"}},
+ check_schemas=False,
+ )
+ self.assertEqual(POINTSET_URL, resolved["source"]["object"])
+ loader.assert_not_awaited()
+
+ async def test_the_declared_version_range_is_honoured(self) -> None:
+ """``pointset/[>=1.2,<2]`` admits 1.9.9 but neither 1.1.0 nor 2.0.0."""
+ accepted = [SchemaVersion(1, 2, 0), SchemaVersion(1, 9, 9)]
+ rejected = [SchemaVersion(1, 1, 0), SchemaVersion(2, 0, 0)]
+ for version in accepted:
+ with self.subTest(version=str(version)), self.objects_service():
+ await self.resolve(
+ source={"object": typed_object(POINTSET_URL, ObjectSchema("objects", "pointset", version))}
+ )
+ for version in rejected:
+ with self.subTest(version=str(version)), self.objects_service():
+ with self.assertRaises(ParameterValidationError):
+ await self.resolve(
+ source={"object": typed_object(POINTSET_URL, ObjectSchema("objects", "pointset", version))}
+ )
+
+
+class TestAttributeReferences(ResolutionTestCase):
+ """``reference_to: attribute`` -- a name or a typed attribute in, JMESPath out."""
+
+ async def source_attribute(self, attribute: Any, object_: Any = POINTSET_URL) -> Any:
+ with self.objects_service():
+ resolved = await self.resolve(source={"object": object_, "attribute": attribute})
+ return resolved["source"]["attribute"]
+
+ async def test_an_existing_typed_attribute_resolves_by_key(self) -> None:
+ attribute = existing_attribute("abc", POINTSET_URL, schema_path="locations.attributes")
+ self.assertEqual("locations.attributes[?key=='abc']", await self.source_attribute(attribute))
+
+ async def test_a_pending_typed_attribute_resolves_by_name(self) -> None:
+ self.assertEqual(
+ "attributes[?name=='grade']", await self.source_attribute(pending_attribute("grade", POINTSET_URL))
+ )
+
+ async def test_a_ready_expression_is_left_alone(self) -> None:
+ """A caller who already speaks JMESPath is not second-guessed."""
+ expression = "locations.attributes[?name=='grade']"
+ self.assertEqual(expression, await self.source_attribute(expression))
+
+ async def test_a_bare_name_is_placed_by_the_owning_objects_family(self) -> None:
+ """A pointset keeps attributes under ``locations``; a block model does not."""
+ self.assertEqual("locations.attributes[?name=='grade']", await self.source_attribute("grade"))
+ self.assertEqual("attributes[?name=='grade']", await self.source_attribute("grade", object_=BLOCK_MODEL_URL))
+
+ async def test_a_bare_name_falls_back_when_the_object_is_unknown(self) -> None:
+ with self.objects_service(unavailable=True), self.assertLogs("compute.resolution", level="WARNING"):
+ resolved = await self.resolve(source={"object": POINTSET_URL, "attribute": "grade"})
+ self.assertEqual("attributes[?name=='grade']", resolved["source"]["attribute"])
+
+ async def test_a_value_that_is_not_an_attribute_at_all_is_rejected(self) -> None:
+ """Deep validation relaxes reference leaves, so this is the only place it can be caught."""
+ with self.objects_service():
+ with self.assertRaises(ParameterValidationError) as ctx:
+ await self.source_attribute(12345)
+ self.assertIn("source.attribute", str(ctx.exception))
+ self.assertIn("int", str(ctx.exception))
+
+ async def test_a_filter_attribute_is_placed_by_an_absolute_pointer(self) -> None:
+ """``attribute_from: /source/object`` reaches across the payload, not just up it."""
+ with self.objects_service():
+ resolved = await self.resolve(
+ source={
+ "object": POINTSET_URL,
+ "attribute": "grade",
+ "filter": {"where": {"type": "condition", "operator": "equal", "attribute": "domain"}},
+ }
+ )
+ condition = resolved["source"]["filter"]["where"]
+ self.assertEqual("locations.attributes[?name=='domain']", condition["attribute"])
+ self.assertEqual("equal", condition["operator"])
+
+ async def test_a_nested_filter_union_resolves_every_branch(self) -> None:
+ """The union is recursive and behind ``$ref``; every leaf still gets resolved."""
+ with self.objects_service():
+ resolved = await self.resolve(
+ source={
+ "object": BLOCK_MODEL_URL,
+ "attribute": "grade",
+ "filter": {
+ "where": {
+ "type": "all_of",
+ "filters": [
+ {"type": "condition", "operator": "equal", "attribute": "domain"},
+ {"type": "condition", "operator": "greater_than", "attribute": "zone"},
+ ],
+ }
+ },
+ }
+ )
+ filters = resolved["source"]["filter"]["where"]["filters"]
+ self.assertEqual(
+ ["attributes[?name=='domain']", "attributes[?name=='zone']"],
+ [condition["attribute"] for condition in filters],
+ )
+
+ async def test_an_optional_filter_written_as_a_union_is_walked_too(self) -> None:
+ """``anyOf: [Filter, null]`` describes the same node as a nullable inline object.
+
+ The catalogue inlines an optional sub-object and adds ``null`` to its ``type``, but a
+ schema generated from a model writes the union instead. Both have to be descended
+ into, or a reference inside an optional filter reaches the wire unresolved.
+ """
+ with self.objects_service():
+ resolved = await self.resolve(
+ source={"object": POINTSET_URL, "attribute": "grade"},
+ target={
+ "object": TARGET_URL,
+ "attribute": {"operation": "create", "name": "estimate"},
+ "filter": {"where": {"type": "condition", "operator": "equal", "attribute": "domain"}},
+ },
+ )
+ self.assertEqual("locations.attributes[?name=='domain']", resolved["target"]["filter"]["where"]["attribute"])
+
+
+class TestTargetAttributes(ResolutionTestCase):
+ """``target: attribute`` -- create a new attribute, or update an existing one."""
+
+ async def target_attribute(self, attribute: Any, object_: Any = TARGET_URL) -> Any:
+ with self.objects_service():
+ resolved = await self.resolve(target={"object": object_, "attribute": attribute})
+ return resolved["target"]["attribute"]
+
+ async def test_a_bare_name_creates_the_attribute(self) -> None:
+ self.assertEqual({"operation": "create", "name": "estimate"}, await self.target_attribute("estimate"))
+
+ async def test_a_pending_typed_attribute_creates_the_attribute(self) -> None:
+ self.assertEqual(
+ {"operation": "create", "name": "estimate"},
+ await self.target_attribute(pending_attribute("estimate", TARGET_URL)),
+ )
+
+ async def test_an_existing_typed_attribute_updates_it(self) -> None:
+ attribute = existing_attribute("xyz", TARGET_URL, schema_path="locations.attributes")
+ self.assertEqual(
+ {"operation": "update", "reference": "locations.attributes[?key=='xyz']"},
+ await self.target_attribute(attribute),
+ )
+
+ async def test_an_update_written_out_still_resolves_its_reference(self) -> None:
+ """Choosing the branch by hand does not opt out of resolving what is inside it."""
+ self.assertEqual(
+ {"operation": "update", "reference": "locations.attributes[?name=='estimate']"},
+ await self.target_attribute({"operation": "update", "reference": "estimate"}),
+ )
+
+ async def test_a_create_written_out_is_left_alone(self) -> None:
+ wire = {"operation": "create", "name": "estimate"}
+ self.assertEqual(wire, await self.target_attribute(wire))
+
+
+class TestTypedAttributeShorthand(ResolutionTestCase):
+ """A bare typed attribute names its object too, exactly as the typed tasks accept."""
+
+ async def test_a_source_attribute_fills_in_the_whole_frame(self) -> None:
+ attribute = existing_attribute("abc", POINTSET_URL, schema_path="locations.attributes")
+ with self.objects_service():
+ resolved = await self.resolve(source=attribute)
+ self.assertEqual({"object": POINTSET_URL, "attribute": "locations.attributes[?key=='abc']"}, resolved["source"])
+
+ async def test_a_target_attribute_fills_in_the_whole_frame(self) -> None:
+ with self.objects_service():
+ resolved = await self.resolve(target=pending_attribute("estimate", TARGET_URL))
+ self.assertEqual(
+ {"object": TARGET_URL, "attribute": {"operation": "create", "name": "estimate"}}, resolved["target"]
+ )
+
+ async def test_a_missing_source_attribute_keeps_the_typed_tasks_error(self) -> None:
+ """The mistake and its wording are the same whichever path the caller took."""
+ with self.objects_service():
+ with self.assertRaises(ParameterValidationError) as ctx:
+ await self.resolve(source=pending_attribute("graed", POINTSET_URL))
+ self.assertIn("does not exist on the source object", str(ctx.exception))
+
+ async def test_the_frame_object_still_faces_supported_schemas(self) -> None:
+ """The shorthand is a shorter way to say the same thing, not a way past the checks."""
+ unsupported = ObjectSchema("objects", "triangle-mesh", SchemaVersion(2, 1, 0))
+ for parameter, attribute in (
+ ("source", existing_attribute("abc", POINTSET_URL, schema=unsupported)),
+ ("target", pending_attribute("estimate", TARGET_URL, schema=unsupported)),
+ ):
+ with self.subTest(parameter=parameter), self.objects_service() as loader:
+ with self.assertRaises(ParameterValidationError) as ctx:
+ await self.resolve(**{parameter: attribute})
+ self.assertIn(f"{parameter}.object", str(ctx.exception))
+ # The attribute brought its object's schema along, so checking it is free.
+ loader.assert_not_awaited()
+
+
+class TestFileReferences(ResolutionTestCase):
+ """``reference_to: file`` -- a File API URL, or a handle that carries one."""
+
+ async def test_a_url_string_is_passed_through(self) -> None:
+ resolved = await self.resolver.resolve(self.import_spec, {"file": "https://unittest.localhost/file/v2/x"})
+ self.assertEqual("https://unittest.localhost/file/v2/x", resolved["file"])
+
+ async def test_a_service_relative_path_is_accepted(self) -> None:
+ resolved = await self.resolver.resolve(self.import_spec, {"file": "/file/v2/files/abc"})
+ self.assertEqual("/file/v2/files/abc", resolved["file"])
+
+ async def test_a_handle_carrying_a_url_resolves_to_it(self) -> None:
+ handle = mock.Mock(url="https://unittest.localhost/file/v2/y")
+ resolved = await self.resolver.resolve(self.import_spec, {"file": handle})
+ self.assertEqual("https://unittest.localhost/file/v2/y", resolved["file"])
+
+ async def test_a_local_filename_is_rejected(self) -> None:
+ """Deep validation relaxes reference leaves, so this is the only place it can be caught."""
+ with self.assertRaises(ParameterValidationError) as ctx:
+ await self.resolver.resolve(self.import_spec, {"file": "mesh.obj"})
+ self.assertIn("file", str(ctx.exception))
+ self.assertIn("mesh.obj", str(ctx.exception))
+
+ async def test_a_handle_without_a_url_is_reported(self) -> None:
+ with self.assertRaises(ParameterValidationError) as ctx:
+ await self.resolver.resolve(self.import_spec, {"file": object()})
+ self.assertIn("file", str(ctx.exception))
+
+
+class TestNonReferenceValues(ResolutionTestCase):
+ """Everything the annotations say nothing about survives the walk untouched."""
+
+ async def test_a_typed_parameter_model_is_accepted_and_resolved_through(self) -> None:
+ """The SDK's own ``Source``/``Target`` models are valid engine inputs too."""
+ with self.objects_service():
+ resolved = await self.resolve(
+ source=Source(object=POINTSET_URL, attribute="locations.attributes[?name=='grade']"),
+ target=Target.new_attribute(TARGET_URL, "estimate"),
+ )
+ self.assertEqual(
+ {"object": POINTSET_URL, "attribute": "locations.attributes[?name=='grade']"}, resolved["source"]
+ )
+ self.assertEqual(
+ {"object": TARGET_URL, "attribute": {"operation": "create", "name": "estimate"}}, resolved["target"]
+ )
+
+ async def test_scalars_arrays_and_plain_objects_are_unchanged(self) -> None:
+ with self.objects_service():
+ resolved = await self.resolve(
+ source={"object": POINTSET_URL, "attribute": "grade"},
+ seeds=[3, 1, 4],
+ options={"label": "run-1", "retries": 2},
+ )
+ self.assertEqual([3, 1, 4], resolved["seeds"])
+ self.assertEqual({"label": "run-1", "retries": 2}, resolved["options"])
+
+ async def test_an_explicit_none_survives_resolution(self) -> None:
+ """A nullable reference set to ``None`` stays ``None`` rather than being resolved."""
+ with self.objects_service():
+ resolved = await self.resolve(source={"object": POINTSET_URL, "attribute": "grade"}, report=None)
+ self.assertIsNone(resolved["report"])
+
+ async def test_an_undeclared_parameter_is_left_for_the_platform_to_judge(self) -> None:
+ resolved = await self.resolver.resolve(self.spec, {"mystery": {"a": 1}})
+ self.assertEqual({"a": 1}, resolved["mystery"])
+
+ async def test_a_typed_model_in_an_optional_slot_is_dumped(self) -> None:
+ """An ``X | None`` slot has no ``properties`` of its own, but a model there is still ours."""
+ with self.objects_service():
+ resolved = await self.resolve(
+ source={"object": POINTSET_URL, "attribute": "grade"},
+ discretisation=BlockDiscretization(nx=3, ny=3, nz=2),
+ )
+ self.assertEqual({"nx": 3, "ny": 3, "nz": 2}, resolved["discretisation"])
+
+
+class TestBareObjectFrames(ResolutionTestCase):
+ """A parameter that is an object and nothing else accepts the object itself."""
+
+ async def resolve_grid(self, grid: Any) -> Any:
+ with self.objects_service():
+ resolved = await self.resolve(source={"object": POINTSET_URL, "attribute": "grade"}, grid=grid)
+ return resolved["grid"]
+
+ async def test_a_typed_object_fills_in_the_frame(self) -> None:
+ """``run(grid=block_model)`` is how the typed tasks are called, so it works here too."""
+ grid = typed_object(BLOCK_MODEL_URL, BLOCK_MODEL)
+ self.assertEqual({"object": BLOCK_MODEL_URL}, await self.resolve_grid(grid))
+
+ async def test_a_url_fills_in_the_frame(self) -> None:
+ self.assertEqual({"object": BLOCK_MODEL_URL}, await self.resolve_grid(BLOCK_MODEL_URL))
+
+ async def test_the_written_out_frame_is_left_alone(self) -> None:
+ self.assertEqual({"object": BLOCK_MODEL_URL}, await self.resolve_grid({"object": BLOCK_MODEL_URL}))
+
+
+class EngineResolutionTestCase(TestWithConnector):
+ """A client over the ``demo`` catalogue, with the objects service and job client stubbed out."""
+
+ def setUp(self) -> None:
+ super().setUp()
+ self.context = FakeContext(self.connector)
+ self.catalogue = load_test_data("discovery-resolution.json")
+
+ @contextmanager
+ def catalogue_response(self) -> Iterator[None]:
+ with self.transport.set_http_response(
+ status_code=200,
+ content=json.dumps(self.catalogue),
+ headers={"Content-Type": "application/json"},
+ ):
+ yield
+
+ @contextmanager
+ def mock_job_client(self, results: dict | None = None) -> Iterator[mock.AsyncMock]:
+ job = mock.Mock()
+ job.wait_for_results = mock.AsyncMock(return_value={} if results is None else results)
+ submit = mock.AsyncMock(return_value=job)
+ with mock.patch("evo.compute.engine.JobClient") as mock_job_client:
+ mock_job_client.submit = submit
+ yield submit
+
+ @contextmanager
+ def objects_service(self) -> Iterator[mock.AsyncMock]:
+ async def load(_context: Any, reference: str) -> mock.Mock:
+ return mock.Mock(metadata=mock.Mock(schema_id=SCHEMAS_BY_URL[str(reference)]))
+
+ with mock.patch("evo.compute.resolution.DownloadedObject.from_context", mock.AsyncMock(side_effect=load)):
+ yield
+
+
+class TestEngineResolution(EngineResolutionTestCase):
+ """The engine resolves between its two validation passes, then submits the resolved payload."""
+
+ async def test_run_submits_the_resolved_payload(self) -> None:
+ client = ComputeClient(self.context)
+ with self.catalogue_response(), self.objects_service(), self.mock_job_client() as submit:
+ await client.demo.estimate.run(
+ source=existing_attribute("abc", POINTSET_URL, schema_path="locations.attributes"),
+ target=pending_attribute("estimate", TARGET_URL),
+ )
+
+ self.assertEqual(
+ {
+ "source": {"object": POINTSET_URL, "attribute": "locations.attributes[?key=='abc']"},
+ "target": {"object": TARGET_URL, "attribute": {"operation": "create", "name": "estimate"}},
+ },
+ submit.await_args.kwargs["parameters"],
+ )
+
+ async def test_deep_validation_judges_the_resolved_payload(self) -> None:
+ """Typed objects would fail a schema that asks for URL strings; resolved ones pass."""
+ client = ComputeClient(self.context, deep_validation=True)
+ with self.catalogue_response(), self.objects_service(), self.mock_job_client() as submit:
+ await client.demo.estimate.run(
+ source={"object": typed_object(POINTSET_URL), "attribute": "grade"},
+ target={"object": typed_object(TARGET_URL), "attribute": "estimate"},
+ )
+ submit.assert_awaited_once()
+
+ async def test_a_missing_required_parameter_is_caught_before_any_object_is_loaded(self) -> None:
+ """Nothing is worth a request until the call itself is known to be well formed."""
+ client = ComputeClient(self.context)
+ with self.catalogue_response(), self.objects_service() as _, self.mock_job_client() as submit:
+ with mock.patch("evo.compute.resolution.DownloadedObject.from_context", mock.AsyncMock()) as loader:
+ with self.assertRaises(ParameterValidationError):
+ await client.demo.estimate.run(source={"object": POINTSET_URL, "attribute": "grade"})
+ loader.assert_not_awaited()
+ submit.assert_not_awaited()
+
+
+class TestSupportedSchemaSwitch(EngineResolutionTestCase):
+ """``check_schemas`` is independent of ``validate``, defaulting to follow it."""
+
+ UNSUPPORTED = ObjectSchema("objects", "triangle-mesh", SchemaVersion(2, 1, 0))
+
+ async def run_with_an_unsupported_source(self, client: ComputeClient, **overrides: Any) -> mock.AsyncMock:
+ with self.catalogue_response(), self.objects_service(), self.mock_job_client() as submit:
+ await client.arun(
+ "demo",
+ "estimate",
+ {
+ "source": {"object": typed_object(POINTSET_URL, self.UNSUPPORTED), "attribute": "grade"},
+ "target": {"object": typed_object(TARGET_URL), "attribute": "estimate"},
+ },
+ **overrides,
+ )
+ return submit
+
+ async def test_the_check_follows_validation_by_default(self) -> None:
+ for validate, expect_rejection in ((True, True), (False, False)):
+ with self.subTest(validate=validate):
+ client = ComputeClient(self.context, validate=validate)
+ if expect_rejection:
+ with self.assertRaises(ParameterValidationError):
+ await self.run_with_an_unsupported_source(client)
+ else:
+ submit = await self.run_with_an_unsupported_source(client)
+ submit.assert_awaited_once()
+
+ async def test_the_check_survives_validation_being_turned_off(self) -> None:
+ """The guard that catches an object the task cannot read is worth keeping on its own."""
+ client = ComputeClient(self.context, validate=False, check_schemas=True)
+ with self.assertRaises(ParameterValidationError) as ctx:
+ await self.run_with_an_unsupported_source(client)
+ self.assertIn("triangle-mesh", str(ctx.exception))
+
+ async def test_the_check_can_be_dropped_while_validation_stays_on(self) -> None:
+ """Skipping it costs the request each referenced object would otherwise need."""
+ client = ComputeClient(self.context, check_schemas=False)
+ submit = await self.run_with_an_unsupported_source(client)
+ submit.assert_awaited_once()
+
+ async def test_the_client_setting_is_overridden_per_call(self) -> None:
+ client = ComputeClient(self.context, check_schemas=False)
+ with self.assertRaises(ParameterValidationError):
+ await self.run_with_an_unsupported_source(client, check_schemas=True)
diff --git a/packages/evo-compute/tests/test_schema_conformance.py b/packages/evo-compute/tests/test_schema_conformance.py
index a8020537..e01aace3 100644
--- a/packages/evo-compute/tests/test_schema_conformance.py
+++ b/packages/evo-compute/tests/test_schema_conformance.py
@@ -59,13 +59,13 @@ def test_vocabulary_matches_expected_set(self) -> None:
self.assertEqual(_EXPECTED_VOCABULARY, KNOWN_SCHEMA_ANNOTATIONS)
def test_bundled_catalogue_uses_only_known_annotations(self) -> None:
- catalogue = load_test_data("discovery-tasks.json")
offenders: dict[str, set[str]] = {}
- for result in catalogue["results"]:
- task = TaskResource.model_validate(result)
- unknown = _unknown_keys_for_task(task)
- if unknown:
- offenders[task.name] = unknown
+ for fixture in ("discovery-tasks.json", "discovery-resolution.json"):
+ for result in load_test_data(fixture)["results"]:
+ task = TaskResource.model_validate(result)
+ unknown = _unknown_keys_for_task(task)
+ if unknown:
+ offenders[f"{fixture}:{task.name}"] = unknown
self.assertEqual({}, offenders, f"unknown schema annotations found: {offenders}")
def test_unknown_annotation_is_flagged(self) -> None:
diff --git a/packages/evo-compute/tests/test_validation.py b/packages/evo-compute/tests/test_validation.py
index 744a2c9a..941360d6 100644
--- a/packages/evo-compute/tests/test_validation.py
+++ b/packages/evo-compute/tests/test_validation.py
@@ -407,6 +407,15 @@ def test_union_with_several_matching_branches_keeps_the_generic_message(self) ->
class TestEngineValidation(TestWithConnector):
"""Engine-level tests for the validation toggles (shallow default, deep opt-in)."""
+ # Reference resolution runs between the two validation passes, so the engine-level
+ # tests have to name an object the way a caller really would.
+ SOURCE_URL = (
+ "https://unittest.localhost/geoscience-object"
+ "/orgs/00000000-0000-0000-0000-000000000001"
+ "/workspaces/00000000-0000-0000-0000-000000000002"
+ "/objects/00000000-0000-0000-0000-000000000010"
+ )
+
def setUp(self) -> None:
super().setUp()
self.context = FakeContext(self.connector, TEST_ORG.id)
@@ -434,14 +443,14 @@ async def test_shallow_is_on_by_default_deep_is_off(self) -> None:
"""By default an enum violation slips through (deep off) and the job is submitted."""
client = ComputeClient(self.context)
with self.catalogue_response(), self.mock_job_client() as submit:
- await client.demo.widget.run(source="obj-1", mode="turbo")
+ await client.demo.widget.run(source=self.SOURCE_URL, mode="turbo")
submit.assert_awaited_once()
async def test_deep_validation_rejects_bad_enum(self) -> None:
client = ComputeClient(self.context, deep_validation=True)
with self.catalogue_response(), self.mock_job_client() as submit:
with self.assertRaises(ParameterValidationError) as ctx:
- await client.demo.widget.run(source="obj-1", mode="turbo")
+ await client.demo.widget.run(source=self.SOURCE_URL, mode="turbo")
self.assertIn("mode", str(ctx.exception))
submit.assert_not_awaited()
@@ -449,7 +458,7 @@ async def test_deep_validation_rejects_constraint_violation(self) -> None:
client = ComputeClient(self.context, deep_validation=True)
with self.catalogue_response(), self.mock_job_client() as submit:
with self.assertRaises(ParameterValidationError):
- await client.demo.widget.run(source="obj-1", mode="fast", iterations=0)
+ await client.demo.widget.run(source=self.SOURCE_URL, mode="fast", iterations=0)
submit.assert_not_awaited()
async def test_deep_validation_rejects_explicit_none_for_a_non_nullable_field(self) -> None:
@@ -457,7 +466,7 @@ async def test_deep_validation_rejects_explicit_none_for_a_non_nullable_field(se
client = ComputeClient(self.context, deep_validation=True)
with self.catalogue_response(), self.mock_job_client() as submit:
with self.assertRaises(ParameterValidationError) as ctx:
- await client.demo.widget.run(source="obj-1", mode="fast", iterations=None)
+ await client.demo.widget.run(source=self.SOURCE_URL, mode="fast", iterations=None)
self.assertIn("iterations", str(ctx.exception))
submit.assert_not_awaited()
@@ -465,21 +474,21 @@ async def test_deep_validation_accepts_reference_string(self) -> None:
"""Deep validation passes when the required reference is supplied as a string."""
client = ComputeClient(self.context, deep_validation=True)
with self.catalogue_response(), self.mock_job_client() as submit:
- await client.demo.widget.run(source="obj-1", mode="fast")
+ await client.demo.widget.run(source=self.SOURCE_URL, mode="fast")
submit.assert_awaited_once()
async def test_deep_validation_can_be_forced_per_call(self) -> None:
client = ComputeClient(self.context) # deep off at the client level
with self.catalogue_response(), self.mock_job_client() as submit:
with self.assertRaises(ParameterValidationError):
- await client.arun("demo", "widget", {"source": "obj-1", "mode": "turbo"}, deep_validation=True)
+ await client.arun("demo", "widget", {"source": self.SOURCE_URL, "mode": "turbo"}, deep_validation=True)
submit.assert_not_awaited()
async def test_validation_can_be_disabled_per_call(self) -> None:
"""With validation off, a required field set to ``None`` goes out for the platform to reject."""
client = ComputeClient(self.context)
with self.catalogue_response(), self.mock_job_client() as submit:
- await client.arun("demo", "widget", {"source": "obj-1", "mode": None}, validate=False)
+ await client.arun("demo", "widget", {"source": self.SOURCE_URL, "mode": None}, validate=False)
submit.assert_awaited_once()
self.assertIsNone(submit.await_args.kwargs["parameters"]["mode"])
@@ -487,27 +496,31 @@ async def test_validation_on_catches_required_set_to_none(self) -> None:
client = ComputeClient(self.context)
with self.catalogue_response(), self.mock_job_client() as submit:
with self.assertRaises(ParameterValidationError):
- await client.arun("demo", "widget", {"source": "obj-1", "mode": None})
+ await client.arun("demo", "widget", {"source": self.SOURCE_URL, "mode": None})
submit.assert_not_awaited()
async def test_validate_off_at_the_client_disables_deep_validation_too(self) -> None:
"""``validate`` is the master switch, so ``deep_validation=True`` under it does nothing."""
client = ComputeClient(self.context, validate=False, deep_validation=True)
with self.catalogue_response(), self.mock_job_client() as submit:
- await client.demo.widget.run(source="obj-1", mode="turbo")
+ await client.demo.widget.run(source=self.SOURCE_URL, mode="turbo")
submit.assert_awaited_once()
async def test_validate_off_per_call_disables_deep_validation_too(self) -> None:
client = ComputeClient(self.context, deep_validation=True)
with self.catalogue_response(), self.mock_job_client() as submit:
- await client.arun("demo", "widget", {"source": "obj-1", "mode": "turbo"}, validate=False)
+ await client.arun("demo", "widget", {"source": self.SOURCE_URL, "mode": "turbo"}, validate=False)
submit.assert_awaited_once()
async def test_validate_off_per_call_overrides_deep_validation_on_per_call(self) -> None:
client = ComputeClient(self.context)
with self.catalogue_response(), self.mock_job_client() as submit:
await client.arun(
- "demo", "widget", {"source": "obj-1", "mode": "turbo"}, validate=False, deep_validation=True
+ "demo",
+ "widget",
+ {"source": self.SOURCE_URL, "mode": "turbo"},
+ validate=False,
+ deep_validation=True,
)
submit.assert_awaited_once()