tensoracle 0.3.1__tar.gz → 0.3.2__tar.gz

{tensoracle-0.3.1 → tensoracle-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: tensoracle
-Version: 0.3.1
+Version: 0.3.2
 Summary: Build, save, reuse, and execute TensorRT engines from safetensors weights
 Project-URL: documentation, https://sync-dev-org.github.io/tensoracle/
 Project-URL: repository, https://github.com/sync-dev-org/tensoracle
@@ -253,6 +253,8 @@ The caller selects the CUDA device and context, orders inputs written on other s
 
 Tensoracle neither allocates or frees device buffers, copies data, nor calls stream or device synchronization. TensorRT itself may allocate internal resources or act synchronously for some networks and plugins. Execution units reject HOST-location tensors, externally supplied shape tensor values, and data-dependent output sizes at creation. Ordinary networks that compute shapes internally from input dimensions are supported. CUDA graphs, profile switching, and caller-owned TensorRT workspace memory are outside this API.
 
+Networks with outputs marked as shape tensors emit `tensoracle.ShapeTensorOutputWarning` during building and when creating an execution unit (`create_execution()` or `EngineExecution(handle)`). The warning names the affected tensors: `create_execution()` cannot handle these engines, and calling it crashes the process. Building continues by default. To stop either operation safely, turn this warning into an exception with `warnings.filterwarnings("error", category=tensoracle.ShapeTensorOutputWarning)` after importing `warnings` and `tensoracle`. Saved engines retain the shape output names outside the cache conditions; older files without these names are reused without an execution warning.
+
 ## Build a cubin plugin
 
 Follow [Prepare a TensorRT SDK](https://github.com/sync-dev-org/tensoracle/blob/main/docs/tensorrt-sdk.md) to acquire and verify the headers and native library for a build SDK, including the fixed inputs for SDK 11.2.1.2 and the `TENSORRT_ROOT` setup.

{tensoracle-0.3.1 → tensoracle-0.3.2}/README.md

@@ -223,6 +223,8 @@ The caller selects the CUDA device and context, orders inputs written on other s
 
 Tensoracle neither allocates or frees device buffers, copies data, nor calls stream or device synchronization. TensorRT itself may allocate internal resources or act synchronously for some networks and plugins. Execution units reject HOST-location tensors, externally supplied shape tensor values, and data-dependent output sizes at creation. Ordinary networks that compute shapes internally from input dimensions are supported. CUDA graphs, profile switching, and caller-owned TensorRT workspace memory are outside this API.
 
+Networks with outputs marked as shape tensors emit `tensoracle.ShapeTensorOutputWarning` during building and when creating an execution unit (`create_execution()` or `EngineExecution(handle)`). The warning names the affected tensors: `create_execution()` cannot handle these engines, and calling it crashes the process. Building continues by default. To stop either operation safely, turn this warning into an exception with `warnings.filterwarnings("error", category=tensoracle.ShapeTensorOutputWarning)` after importing `warnings` and `tensoracle`. Saved engines retain the shape output names outside the cache conditions; older files without these names are reused without an execution warning.
+
 ## Build a cubin plugin
 
 Follow [Prepare a TensorRT SDK](https://github.com/sync-dev-org/tensoracle/blob/main/docs/tensorrt-sdk.md) to acquire and verify the headers and native library for a build SDK, including the fixed inputs for SDK 11.2.1.2 and the `TENSORRT_ROOT` setup.

{tensoracle-0.3.1 → tensoracle-0.3.2}/docs/index.md

@@ -155,6 +155,8 @@ The caller selects the CUDA device and context, orders inputs written on other s
 
 Tensoracle neither allocates or frees device buffers, copies data, nor calls stream or device synchronization. TensorRT itself may allocate internal resources or act synchronously for some networks and plugins. Execution units reject HOST-location tensors, externally supplied shape tensor values, and data-dependent output sizes at creation. Ordinary networks that compute shapes internally from input dimensions are supported. CUDA graphs, profile switching, and caller-owned TensorRT workspace memory are outside this API.
 
+Networks with outputs marked as shape tensors emit `tensoracle.ShapeTensorOutputWarning` during building and when creating an execution unit (`create_execution()` or `EngineExecution(handle)`). The warning names the affected tensors: `create_execution()` cannot handle these engines, and calling it crashes the process. Building continues by default. To stop either operation safely, turn this warning into an exception with `warnings.filterwarnings("error", category=tensoracle.ShapeTensorOutputWarning)` after importing `warnings` and `tensoracle`. Saved engines retain the shape output names outside the cache conditions; older files without these names are reused without an execution warning.
+
 `TensorSpec` accepts optional `location=trt.TensorLocation.DEVICE` and `format=trt.TensorFormat.LINEAR`. `open_engine` checks these only when declared, together with tensor names, modes, dtypes, build-time shapes, and profiles. An `EngineIOError` names the tensor, field, observed value, expected value, and saved file path. The execution unit does not accept a second declaration.
 
 ### Build a standard graph

{tensoracle-0.3.1 → tensoracle-0.3.2}/src/tensoracle/__init__.py

@@ -15,6 +15,7 @@ __all__ = [
     "InputShape",
     "OutputComparison",
     "PluginLibraryError",
+    "ShapeTensorOutputWarning",
     "TensorSpec",
     "build_serialized_engine",
     "compare_outputs",
@@ -23,7 +24,14 @@ __all__ = [
 
 _MODULES = {
     **dict.fromkeys(
-        ("BuilderSettings", "EngineBuild", "InputShape", "build_serialized_engine"), "._build"
+        (
+            "BuilderSettings",
+            "EngineBuild",
+            "InputShape",
+            "ShapeTensorOutputWarning",
+            "build_serialized_engine",
+        ),
+        "._build",
     ),
     **dict.fromkeys(
         (

{tensoracle-0.3.1 → tensoracle-0.3.2}/src/tensoracle/_build.py

@@ -1,5 +1,6 @@
 """Build serialized TensorRT engines from caller-defined network graphs."""
 
+import warnings
 from collections.abc import Callable, Mapping, Sequence
 from dataclasses import dataclass, field
 from pathlib import Path
@@ -11,6 +12,21 @@ from ._memory import release_host_memory
 from ._plugins import register_libraries
 
 
+class ShapeTensorOutputWarning(UserWarning):
+    """Shape tensor outputs cannot be handled by tensoracle execution units."""
+
+
+def _warn_shape_tensor_outputs(names: tuple[str, ...], *, stacklevel: int) -> None:
+    if names:
+        warnings.warn(
+            f"TensorRT outputs {', '.join(repr(name) for name in names)} are shape tensors; "
+            "tensoracle.create_execution() cannot handle this engine and calling it will "
+            "crash the process.",
+            ShapeTensorOutputWarning,
+            stacklevel=stacklevel + 1,
+        )
+
+
 @dataclass(frozen=True)
 class InputShape:
     """The minimum, preferred, and maximum dimensions of one input."""
@@ -76,6 +92,17 @@ def build_serialized_engine(
     logger: trt.ILogger | None = None,
 ) -> bytes:
     """Register ``plugins`` before calling ``graph`` and serializing its engine."""
+    plan, _ = _build_serialized_engine(graph, declaration, plugins=plugins, logger=logger)
+    return plan
+
+
+def _build_serialized_engine(
+    graph: Callable[[trt.INetworkDefinition], None],
+    declaration: EngineBuild,
+    *,
+    plugins: Sequence[Path] = (),
+    logger: trt.ILogger | None = None,
+) -> tuple[bytes, tuple[str, ...]]:
     if declaration.precision not in ("fp32", "fp16"):
         raise ValueError(f"unsupported precision: {declaration.precision}")
     if declaration.settings.tf32:
@@ -93,6 +120,13 @@ def build_serialized_engine(
         builder = trt.Builder(logger or trt.Logger(trt.Logger.ERROR))
         network = builder.create_network(0)
         graph(network)
+        shape_tensor_outputs = []
+        for index in range(network.num_outputs):
+            tensor = network.get_output(index)
+            if tensor.is_shape_tensor:
+                shape_tensor_outputs.append(tensor.name)
+        output_names = tuple(shape_tensor_outputs)
+        _warn_shape_tensor_outputs(output_names, stacklevel=3)
         config = builder.create_builder_config()
         config.clear_flag(trt.BuilderFlag.TF32)
         config.set_memory_pool_limit(
@@ -129,7 +163,7 @@ def build_serialized_engine(
         serialized = builder.build_serialized_network(network, config)
         if serialized is None:
             raise RuntimeError("TensorRT failed to build the serialized engine")
-        return bytes(serialized)
+        return bytes(serialized), output_names
     finally:
         # Tensor references also keep the network alive, including in exception frames.
         inputs.clear()

{tensoracle-0.3.1 → tensoracle-0.3.2}/src/tensoracle/_cache.py

@@ -9,12 +9,13 @@ import platform
 import tempfile
 from collections.abc import Callable, Mapping, Sequence
 from dataclasses import asdict, dataclass
+from dataclasses import field as dataclass_field
 from pathlib import Path
 from typing import TYPE_CHECKING
 
 import tensorrt as trt
 
-from ._build import EngineBuild, build_serialized_engine
+from ._build import EngineBuild, _build_serialized_engine
 from ._plugins import register_libraries
 
 if TYPE_CHECKING:
@@ -49,6 +50,7 @@ class EngineHandle:
     engine: trt.ICudaEngine
     runtime: trt.Runtime
     path: Path
+    _shape_tensor_outputs: tuple[str, ...] = dataclass_field(default=(), repr=False)
 
     def create_execution(self) -> "EngineExecution":
         """Create an independent execution context with explicit close semantics."""
@@ -103,16 +105,29 @@ def open_engine(
         try:
             fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
         except FileExistsError:
-            plan = _read_plan(path, conditions)
-            return _open_plan(plan, path, declaration, io, actual_logger)
+            plan, shape_tensor_outputs = _read_plan(path, conditions)
+            return _open_plan(
+                plan,
+                path,
+                declaration,
+                io,
+                actual_logger,
+                shape_tensor_outputs=shape_tensor_outputs,
+            )
         else:
             os.close(fd)
 
     temporary: Path | None = None
     try:
-        plan = build_serialized_engine(graph, declaration, plugins=plugins, logger=actual_logger)
-        handle = _open_plan(plan, path, declaration, io, actual_logger)
+        plan, shape_tensor_outputs = _build_serialized_engine(
+            graph, declaration, plugins=plugins, logger=actual_logger
+        )
+        handle = _open_plan(
+            plan, path, declaration, io, actual_logger, shape_tensor_outputs=shape_tensor_outputs
+        )
         header = {"conditions": conditions, "plan_sha256": hashlib.sha256(plan).hexdigest()}
+        if shape_tensor_outputs:
+            header["shape_tensor_outputs"] = list(shape_tensor_outputs)
         header_bytes = _json_bytes(header)
         fd, filename = tempfile.mkstemp(prefix=f".{digest}.", dir=path.parent)
         temporary = Path(filename)
@@ -279,7 +294,7 @@ def _conditions(
     }
 
 
-def _read_plan(path: Path, conditions: dict) -> memoryview:
+def _read_plan(path: Path, conditions: dict) -> tuple[memoryview, tuple[str, ...]]:
     data = path.read_bytes()
     offset = len(_MAGIC)
     if not data.startswith(_MAGIC) or len(data) < offset + 8:
@@ -294,12 +309,17 @@ def _read_plan(path: Path, conditions: dict) -> memoryview:
         raise CorruptEngineError(f"invalid TensorRT engine header: {path}") from error
     if not isinstance(header, dict) or not isinstance(header.get("conditions"), dict):
         raise CorruptEngineError(f"invalid TensorRT engine header: {path}")
+    shape_tensor_outputs = header.get("shape_tensor_outputs", [])
+    if not isinstance(shape_tensor_outputs, list) or any(
+        not isinstance(name, str) for name in shape_tensor_outputs
+    ):
+        raise CorruptEngineError(f"invalid TensorRT engine header: {path}")
     if header["conditions"] != conditions:
         raise EngineConditionError(f"TensorRT engine conditions differ: {path}")
     plan = memoryview(data)[header_end:]
     if header.get("plan_sha256") != hashlib.sha256(plan).hexdigest():
         raise CorruptEngineError(f"TensorRT engine checksum differs: {path}")
-    return plan
+    return plan, tuple(shape_tensor_outputs)
 
 
 def _open_plan(
@@ -308,6 +328,8 @@ def _open_plan(
     declaration: EngineBuild,
     io: EngineIO,
     logger: trt.ILogger,
+    *,
+    shape_tensor_outputs: tuple[str, ...] = (),
 ) -> EngineHandle:
     runtime = trt.Runtime(logger)
     engine = runtime.deserialize_cuda_engine(plan)
@@ -349,7 +371,7 @@ def _open_plan(
             actual_range = (io.inputs[name].shape,) * 3
         if actual_range != expected_range:
             _io_mismatch(path, name, "profile range", actual_range, expected_range)
-    return EngineHandle(engine, runtime, path)
+    return EngineHandle(engine, runtime, path, _shape_tensor_outputs=shape_tensor_outputs)
 
 
 def _io_mismatch(path: Path, name: str, field: str, observed: object, expected: object) -> None:

{tensoracle-0.3.1 → tensoracle-0.3.2}/src/tensoracle/_execution.py

@@ -7,6 +7,8 @@ from typing import TYPE_CHECKING, Self
 
 import tensorrt as trt
 
+from ._build import _warn_shape_tensor_outputs
+
 if TYPE_CHECKING:
     from ._cache import EngineHandle
 
@@ -51,6 +53,7 @@ class EngineExecution:
             self._context = engine.create_execution_context()
             if self._context is None:
                 raise RuntimeError("TensorRT failed to create an execution context")
+            _warn_shape_tensor_outputs(handle._shape_tensor_outputs, stacklevel=2)
             # Probe output dimensions before accepting the engine. A ranged engine
             # still requires an explicit caller setting after this capability check.
             self._set_shapes(initial_shapes, creating=True)

{tensoracle-0.3.1 → tensoracle-0.3.2}/src/tensoracle/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.3.1'
-__version_tuple__ = version_tuple = (0, 3, 1)
+__version__ = version = '0.3.2'
+__version_tuple__ = version_tuple = (0, 3, 2)
 
 __commit_id__ = commit_id = None

{tensoracle-0.3.1 → tensoracle-0.3.2}/tests/test_build.py

@@ -202,6 +202,7 @@ def test_tf32_is_disabled_and_other_builder_settings_are_applied(monkeypatch):
 
     class Network:
         num_inputs = 1
+        num_outputs = 0
 
         def get_input(self, index):
             return type("Input", (), {"name": "features", "shape": (1, 3, 2)})()

{tensoracle-0.3.1 → tensoracle-0.3.2}/tests/test_build_memory.py

@@ -64,7 +64,7 @@ def test_unavailable_host_memory_release_preserves_the_build_result(monkeypatch,
         return b"serialized plan"
 
     builder = SimpleNamespace(
-        create_network=lambda flags: SimpleNamespace(num_inputs=0),
+        create_network=lambda flags: SimpleNamespace(num_inputs=0, num_outputs=0),
         create_builder_config=lambda: SimpleNamespace(
             clear_flag=lambda flag: None,
             set_memory_pool_limit=lambda pool, limit: None,

{tensoracle-0.3.1 → tensoracle-0.3.2}/tests/test_cache.py

@@ -72,7 +72,7 @@ def test_read_large_saved_plan_keeps_other_threads_running(tmp_path):
 
     measurements = []
     for _ in range(3):
-        loaded, measured = _heartbeat_during(lambda: cache._read_plan(path, conditions))
+        (loaded, _), measured = _heartbeat_during(lambda: cache._read_plan(path, conditions))
         assert len(loaded) == 512 * 1024 * 1024
         assert hashlib.sha256(loaded).hexdigest() == digest
         measurements.append(measured)
@@ -97,7 +97,7 @@ def test_save_large_built_plan_keeps_other_threads_running(tmp_path, monkeypatch
     monkeypatch.setenv("XDG_CACHE_HOME", str(tmp_path / "cache"))
     monkeypatch.setattr(cache, "_gpu_name", lambda: "GPU A")
     builder = SimpleNamespace(
-        create_network=lambda flags: SimpleNamespace(num_inputs=0),
+        create_network=lambda flags: SimpleNamespace(num_inputs=0, num_outputs=0),
         create_builder_config=lambda: SimpleNamespace(
             clear_flag=lambda flag: None,
             set_memory_pool_limit=lambda pool, limit: None,
@@ -131,7 +131,7 @@ def test_save_large_built_plan_keeps_other_threads_running(tmp_path, monkeypatch
     for _ in range(3):
         handle, measured = _heartbeat_during(save)
         conditions = cache._conditions("heartbeat", "1", (weights,), (), declaration)
-        loaded = cache._read_plan(handle.path, conditions)
+        loaded, _ = cache._read_plan(handle.path, conditions)
         assert len(loaded) == len(plan)
         assert hashlib.sha256(loaded).digest() == hashlib.sha256(plan).digest()
         measurements.append(measured)
@@ -422,7 +422,7 @@ def test_build_failure_removes_placeholder_and_partial_files(tmp_path, monkeypat
     monkeypatch.setenv("XDG_CACHE_HOME", str(tmp_path / "cache"))
     monkeypatch.setattr(cache, "_gpu_name", lambda: "GPU A")
     monkeypatch.setattr(
-        cache, "build_serialized_engine", lambda graph, declaration, plugins, logger: graph(None)
+        cache, "_build_serialized_engine", lambda graph, declaration, plugins, logger: graph(None)
     )
     weights = tmp_path / "weights.safetensors"
     _weights(weights)
@@ -537,6 +537,7 @@ def test_each_declared_condition_selects_a_distinct_cache_entry(tmp_path, monkey
 
     class FakeNetwork:
         num_inputs = 1
+        num_outputs = 0
 
         def get_input(self, index):
             return type("Input", (), {"name": "features", "shape": state["shape"]})()

tensoracle-0.3.2/tests/test_shape_tensor_outputs.py

@@ -0,0 +1,282 @@
+"""Warn about shape tensor outputs before unsafe TensorRT shape inference."""
+
+import hashlib
+import json
+import subprocess
+import sys
+import warnings
+
+import numpy as np
+import pytest
+import tensorrt as trt
+from safetensors.numpy import save_file
+
+import tensoracle
+from test_execution import Context, Engine, _handle
+
+
+def _graph(network, *, output_kind="shape"):
+    features = network.add_input("features", trt.float32, (3, 2))
+    result = network.add_identity(features).get_output(0)
+    result.name = "result"
+    network.mark_output(result)
+    if output_kind != "ordinary":
+        dimensions = network.add_shape(features).get_output(0)
+        dimensions.name = "dimensions"
+        if output_kind == "shape":
+            assert network.mark_output_for_shapes(dimensions)
+        else:
+            network.mark_output(dimensions)
+
+
+def _declaration():
+    return tensoracle.EngineBuild(
+        "fp32",
+        {"features": tensoracle.InputShape.fixed((3, 2))},
+        tensoracle.BuilderSettings(optimization_level=0),
+    )
+
+
+def _io(output_kind="shape"):
+    outputs = {"result": tensoracle.TensorSpec(trt.float32, (3, 2))}
+    if output_kind != "ordinary":
+        outputs["dimensions"] = tensoracle.TensorSpec(trt.int64, (2,))
+    return tensoracle.EngineIO({"features": tensoracle.TensorSpec(trt.float32, (3, 2))}, outputs)
+
+
+@pytest.fixture
+def weights(tmp_path, monkeypatch):
+    monkeypatch.setenv("XDG_CACHE_HOME", str(tmp_path / "cache"))
+    path = tmp_path / "weights.safetensors"
+    save_file({"unused": np.zeros(1, dtype=np.float32)}, path)
+    return path
+
+
+def _open(weights, *, output_kind="shape", graph=None, force_rebuild=False):
+    return tensoracle.open_engine(
+        graph if graph is not None else lambda network: _graph(network, output_kind=output_kind),
+        _declaration(),
+        name="shape-output",
+        graph_version="1",
+        weights=(weights,),
+        io=_io(output_kind),
+        force_rebuild=force_rebuild,
+    )
+
+
+def _read_file(path):
+    data = path.read_bytes()
+    offset = len(b"TENSORACLE\x01")
+    header_end = offset + 8 + int.from_bytes(data[offset : offset + 8], "big")
+    return json.loads(data[offset + 8 : header_end]), data[header_end:]
+
+
+def _write_file(path, header, plan):
+    encoded = json.dumps(header, sort_keys=True, separators=(",", ":")).encode()
+    path.write_bytes(b"TENSORACLE\x01" + len(encoded).to_bytes(8, "big") + encoded + plan)
+
+
+def _assert_warning(message):
+    assert "dimensions" in message
+    assert "shape tensor" in message
+    assert "create_execution()" in message
+    assert "cannot" in message
+    assert "process" in message and "crash" in message
+
+
+@pytest.mark.gpu
+@pytest.mark.req("REQ-TENSORACLE-018")
+@pytest.mark.req("REQ-TENSORACLE-002")
+def test_shape_output_build_warns_once_and_returns_plan():
+    """A shape tensor output warns about the execution crash while returning plan bytes."""
+    with warnings.catch_warnings(record=True) as caught:
+        warnings.simplefilter("always")
+        plan = tensoracle.build_serialized_engine(_graph, _declaration())
+    assert isinstance(plan, bytes) and plan
+    assert len(caught) == 1
+    assert caught[0].category is tensoracle.ShapeTensorOutputWarning
+    assert issubclass(caught[0].category, UserWarning)
+    assert "ShapeTensorOutputWarning" in tensoracle.__all__
+    _assert_warning(str(caught[0].message))
+
+
+@pytest.mark.gpu
+@pytest.mark.req("REQ-TENSORACLE-007")
+@pytest.mark.req("REQ-TENSORACLE-018")
+@pytest.mark.req("REQ-TENSORACLE-002")
+def test_shape_output_cache_records_names_without_changing_conditions(weights):
+    """Shape output names are saved outside conditions and do not change the cache identity."""
+    with warnings.catch_warnings(record=True) as caught:
+        warnings.simplefilter("always")
+        handle = _open(weights)
+    assert len(caught) == 1
+    assert caught[0].category is tensoracle.ShapeTensorOutputWarning
+    _assert_warning(str(caught[0].message))
+    header, plan = _read_file(handle.path)
+    assert header["shape_tensor_outputs"] == ["dimensions"]
+    assert "shape_tensor_outputs" not in header["conditions"]
+    assert header["plan_sha256"] == hashlib.sha256(plan).hexdigest()
+    digest = hashlib.sha256(
+        json.dumps(header["conditions"], sort_keys=True, separators=(",", ":")).encode()
+    ).hexdigest()
+    assert handle.path.name == f"{digest}.engine"
+    ordinary = _open(weights, output_kind="ordinary", force_rebuild=True)
+    ordinary_header, _ = _read_file(ordinary.path)
+    assert ordinary.path == handle.path
+    assert ordinary_header["conditions"] == header["conditions"]
+
+
+@pytest.mark.gpu
+@pytest.mark.req("REQ-TENSORACLE-018")
+@pytest.mark.req("REQ-TENSORACLE-002")
+@pytest.mark.parametrize("entry", ["create_execution", "EngineExecution"])
+def test_saved_shape_output_warns_before_inference_in_another_process(weights, entry):
+    """A later process can turn the execution warning into an exception before unsafe inference."""
+    category = tensoracle.ShapeTensorOutputWarning
+    with warnings.catch_warnings():
+        warnings.simplefilter("ignore", category)
+        handle = _open(weights)
+    child = """
+import json
+import sys
+import warnings
+from pathlib import Path
+import tensorrt as trt
+import tensoracle
+
+def forbidden(network):
+    raise AssertionError('saved engine was rebuilt')
+
+handle = tensoracle.open_engine(
+    forbidden,
+    tensoracle.EngineBuild('fp32', {'features': tensoracle.InputShape.fixed((3, 2))},
+                         tensoracle.BuilderSettings(optimization_level=0)),
+    name='shape-output', graph_version='1', weights=(Path(sys.argv[1]),),
+    io=tensoracle.EngineIO({'features': tensoracle.TensorSpec(trt.float32, (3, 2))},
+                          {'result': tensoracle.TensorSpec(trt.float32, (3, 2)),
+                           'dimensions': tensoracle.TensorSpec(trt.int64, (2,))}),
+)
+warnings.filterwarnings('error', category=tensoracle.ShapeTensorOutputWarning)
+try:
+    if sys.argv[2] == 'create_execution':
+        handle.create_execution()
+    else:
+        tensoracle.EngineExecution(handle)
+except tensoracle.ShapeTensorOutputWarning as warning:
+    print(json.dumps({'path': str(handle.path), 'message': str(warning)}))
+else:
+    raise AssertionError('execution did not raise the warning')
+"""
+    result = subprocess.run(
+        [sys.executable, "-c", child, str(weights), entry],
+        capture_output=True,
+        text=True,
+        check=False,
+        timeout=60,
+    )
+    assert result.returncode == 0, result.stdout + result.stderr
+    observed = json.loads(result.stdout.splitlines()[-1])
+    assert observed["path"] == str(handle.path)
+    _assert_warning(observed["message"])
+
+
+@pytest.mark.gpu
+@pytest.mark.req("REQ-TENSORACLE-018")
+@pytest.mark.req("REQ-TENSORACLE-002")
+@pytest.mark.req("REQ-TENSORACLE-007")
+@pytest.mark.parametrize("entry", ["build_serialized_engine", "open_engine"])
+def test_shape_output_warning_as_error_stops_build_without_cache_files(weights, entry):
+    """Turning the build warning into an error leaves no engine or temporary engine file."""
+    category = tensoracle.ShapeTensorOutputWarning
+    with warnings.catch_warnings():
+        warnings.filterwarnings("error", category=category)
+        with pytest.raises(category) as caught:
+            if entry == "build_serialized_engine":
+                tensoracle.build_serialized_engine(_graph, _declaration())
+            else:
+                _open(weights)
+    _assert_warning(str(caught.value))
+    cache_directory = weights.parent / "cache" / "tensoracle"
+    assert all(path.name.startswith("weight-") for path in cache_directory.glob("*"))
+
+
+@pytest.mark.gpu
+@pytest.mark.req("REQ-TENSORACLE-007")
+@pytest.mark.req("REQ-TENSORACLE-018")
+def test_saved_engine_without_shape_output_metadata_is_reused_without_warning(weights):
+    """An older header loads without rebuilding or warning when creating an execution unit."""
+    first = _open(weights, output_kind="ordinary")
+    header, plan = _read_file(first.path)
+    header.pop("shape_tensor_outputs", None)
+    _write_file(first.path, header, plan)
+    legacy_bytes = first.path.read_bytes()
+
+    def forbidden(network):
+        pytest.fail("saved engine was rebuilt")
+
+    with warnings.catch_warnings(record=True) as caught:
+        warnings.simplefilter("always")
+        reopened = _open(weights, output_kind="ordinary", graph=forbidden)
+        with reopened.create_execution() as execution:
+            assert execution.get_tensor_shape("result") == (3, 2)
+    assert caught == []
+    assert reopened.path == first.path
+    assert reopened.path.read_bytes() == legacy_bytes
+
+
+@pytest.mark.gpu
+@pytest.mark.req("REQ-TENSORACLE-018")
+@pytest.mark.parametrize("output_kind", ["ordinary", "shape-layer"])
+def test_ordinary_outputs_including_shape_layer_outputs_never_warn(weights, output_kind):
+    """Ordinary marked outputs stay supported even when their values come from a shape layer."""
+    with warnings.catch_warnings(record=True) as caught:
+        warnings.simplefilter("always")
+        assert tensoracle.build_serialized_engine(
+            lambda network: _graph(network, output_kind=output_kind), _declaration()
+        )
+        handle = _open(weights, output_kind=output_kind)
+        reopened = _open(weights, output_kind=output_kind)
+        for checked in (handle, reopened):
+            with checked.create_execution() as execution:
+                assert execution.get_tensor_shape("result") == (3, 2)
+                if output_kind == "shape-layer":
+                    assert execution.get_tensor_shape("dimensions") == (2,)
+    assert caught == []
+
+
+@pytest.mark.gpu
+@pytest.mark.req("REQ-TENSORACLE-008")
+@pytest.mark.req("REQ-TENSORACLE-002")
+@pytest.mark.parametrize("metadata", [None, "dimensions", {}, [1], ["dimensions", False]])
+def test_invalid_shape_output_metadata_is_a_corrupt_engine(weights, metadata):
+    """A present shape output record must be a list of tensor names to load a saved engine."""
+    handle = _open(weights, output_kind="ordinary")
+    header, plan = _read_file(handle.path)
+    header["shape_tensor_outputs"] = metadata
+    _write_file(handle.path, header, plan)
+    with pytest.raises(tensoracle.CorruptEngineError, match="header"):
+        _open(weights, output_kind="ordinary")
+
+
+@pytest.mark.req("REQ-TENSORACLE-018")
+@pytest.mark.req("REQ-TENSORACLE-002")
+def test_execution_warning_as_error_releases_context_before_inference(monkeypatch):
+    """A warning raised as an error releases the new context without probing output shapes."""
+    category = tensoracle.ShapeTensorOutputWarning
+    engine = Engine(fixed=True)
+    monkeypatch.setattr(
+        Context, "infer_shapes", lambda context: pytest.fail("inference was called")
+    )
+    handle = _handle(engine)
+    object.__setattr__(handle, "_shape_tensor_outputs", ("dimensions",))
+    execution = tensoracle.EngineExecution.__new__(tensoracle.EngineExecution)
+    with warnings.catch_warnings():
+        warnings.filterwarnings("error", category=category)
+        with pytest.raises(category) as caught:
+            execution.__init__(handle)
+    _assert_warning(str(caught.value))
+    assert len(engine.contexts) == 1
+    assert engine.latest is None
+    with pytest.raises(RuntimeError, match="closed"):
+        execution.get_tensor_shape("result")
+    assert execution._handle is None