rocket-engine 0.0.2b1__py3-none-any.whl

rocket_engine/adapters/meep/__init__.py

@@ -0,0 +1,167 @@
+"""Meep FDTD adapter: run_optical behind the ToolAdapter port."""
+
+import json
+import re
+import subprocess
+from pathlib import Path
+
+from ...execution.errors import ExecutionError
+from ...interfaces import ToolAdapter
+from ..errors import AdapterError
+
+OPERATION = "run_optical"
+_TOOL = "meep"
+_DUMP = "meep_dump.json"
+_TIMEOUT_S = 600
+_FLUX_RE = re.compile(r"^(flux|force|(?:electric|magnetic|total)-energy"
+                       r"|ldos|harminv)\d*:,", re.M)
+
+
+class MeepAdapter(ToolAdapter):
+    """run_optical via meep: in-API dump plus HDF5 telemetry.
+
+    Serves the run_optical operation with tool `meep`. The driver
+    runs under subprocess python (pymeep env) and reports via
+    get_fluxes/get_dft_array/get_array/Harminv.modes dumped to
+    JSON; HDF5 field files stay as artifacts. Deterministic S1
+    telemetry lines are the fallback, never the first channel.
+
+    Job keys:
+        script (required): Driver python script path.
+        workdir: Run directory (default ".").
+        timeout_s: Budget in seconds (default 600).
+
+    Args:
+        runner: Optional isolated runner; direct subprocess when None.
+    """
+
+    def __init__(self, runner=None):
+        self._runner = runner
+
+    def capabilities(self, target):
+        """Report the served operation and tool.
+
+        Args:
+            target: Target the capabilities are reported for.
+
+        Returns:
+            Capability mapping with operations and tool.
+        """
+        return {"operations": [OPERATION], "tool": _TOOL, "dump": _DUMP}
+
+    def preflight(self, job):
+        """Check operation, script, and meep importability.
+
+        Args:
+            job: Solver job with operation run_optical plus script.
+
+        Returns:
+            Checked mapping with script and timeout.
+
+        Raises:
+            AdapterError: unsupported_operation, invalid_reference
+                for a missing script, missing_dependency with
+                BLOCKED-needs-host when meep is not importable.
+        """
+        if job.get("operation") != OPERATION:
+            raise AdapterError(
+                "unsupported_operation",
+                f"Meep handles {OPERATION}, got {job.get('operation')}.")
+        script = job.get("script")
+        if not script or not Path(script).is_file():
+            raise AdapterError(
+                "invalid_reference", f"Driver script not found: {script}.")
+        try:
+            __import__(_TOOL)
+        except ImportError as exc:
+            raise AdapterError(
+                "missing_dependency",
+                "BLOCKED-needs-host: meep not importable "
+                "(need pymeep==1.35.0 via the conda env).",
+            ) from exc
+        timeout = job.get("timeout_s", _TIMEOUT_S)
+        if (not isinstance(timeout, (int, float))
+                or isinstance(timeout, bool) or not timeout > 0):
+            raise AdapterError("invalid_command", f"Bad timeout: {timeout!r}.")
+        checked = {"script": str(script), "timeout_s": timeout}
+        if self._runner is not None:
+            try:
+                self._runner.preflight()
+            except ExecutionError as exc:
+                raise AdapterError(exc.code, str(exc)) from exc
+        return checked
+
+    def execute(self, job):
+        """Run the driver script under a timeout.
+
+        Args:
+            job: Solver job with operation run_optical plus script.
+
+        Returns:
+            Native output with exit_code, stdout/stderr, dump, file.
+        """
+        checked = self.preflight(job)
+        workdir = job.get("workdir", ".")
+        if not Path(workdir).is_dir():
+            raise AdapterError(
+                "invalid_reference", f"Workdir not found: {workdir}.")
+        try:
+            proc = subprocess.run(
+                ["python3", checked["script"]], capture_output=True,
+                text=True, timeout=checked["timeout_s"], cwd=workdir)
+        except subprocess.TimeoutExpired as exc:
+            raise AdapterError(
+                "runner_unavailable", "Meep run timed out.") from exc
+        dump_path = Path(workdir) / _DUMP
+        dump = None
+        if dump_path.is_file():
+            try:
+                dump = json.loads(dump_path.read_text())
+            except ValueError:
+                dump = None
+        return {"exit_code": proc.returncode, "stdout": proc.stdout,
+                "stderr": proc.stderr, "dump": dump,
+                "dump_file": _DUMP}
+
+    def parse(self, native_output):
+        """Parse the in-API dump, else S1 telemetry, else violation.
+
+        Args:
+            native_output: Native output with the dump mapping.
+
+        Returns:
+            {total, violations[], measurements[], source}.
+
+        Raises:
+            AdapterError: runner_unavailable with no dump and no
+                telemetry (a failed run must never parse as clean).
+        """
+        dump = native_output.get("dump")
+        if isinstance(dump, dict):
+            measurements = []
+            for flux in dump.get("fluxes") or []:
+                try:
+                    measurements.append({"name": "flux", "value": float(flux),
+                                         "unit": "a.u."})
+                except (TypeError, ValueError):
+                    continue
+            trans = dump.get("transmission")
+            if isinstance(trans, (int, float)) and not isinstance(trans, bool):
+                measurements.append({"name": "transmission",
+                                     "value": float(trans), "unit": "ratio"})
+            return {"total": 0, "violations": [], "measurements": measurements,
+                    "source": "dump",
+                    "dump_file": native_output.get("dump_file", _DUMP)}
+        text = (native_output.get("stdout") or "")
+        if _FLUX_RE.search(text):
+            return {"total": 0, "violations": [],
+                    "measurements": [{"name": "telemetry", "value": 1.0,
+                                      "unit": "count"}],
+                    "source": "stdio_fallback"}
+        if native_output.get("exit_code", 0) != 0:
+            return {"total": 1, "violations": [
+                {"rule": "optical_fail", "severity": "error",
+                 "message": "Meep run left no dump or telemetry."}],
+                "measurements": [], "source": "stdio_fallback"}
+        raise AdapterError(
+            "runner_unavailable", "Meep output has no dump verdict.")

rocket_engine/adapters/meow/README.md

@@ -0,0 +1,7 @@
+# MEOW eigenmode adapter
+
+MeowAdapter serves run_em. It stages project-provided waveguide/device inputs and a simulation job, runs MEOW through its local mode-solving and SAX EME backends, and returns transmission, reflection, phase, mode, and convergence evidence.
+
+The adapter is registered in Engine as the meow solver. Its focused qualification case is a silicon strip waveguide at 1550 nm with two modes: a matched guide transmits T=1/R=0, while an abrupt 0.5-to-1.0 μm width step lowers transmission and produces reflection. A missing dependency reports missing_dependency.
+
+Engine code does not import the Tidy3D client or call its cloud service. The local smoke has a network-disabled check. FDTD and FEM support remain outside the proven scope. See the [MEOW-LIVE ticket](../../../docs/tickets/MEOW-LIVE.md).

rocket_engine/adapters/meow/__init__.py

@@ -0,0 +1,190 @@
+"""Meow EME smoke: smallest honest strip-waveguide S-matrix.
+
+A 500x220nm Si strip on SiO2 at 1550nm, 2 modes solved with
+meow's tidy3d FDE backend and cascaded over a 10um cell with
+meow's SAX EME backend. Verified against meow 0.15.0 over
+tidy3d 2.10.0: the matched guide transmits T=1.0/R=0.0, while
+an abrupt 0.5->1.0um width step drops the fundamental to
+T=0.877/R=0.0009 — the good-vs-bad signal. Solver imports stay
+lazy so bare envs fail loud (`missing_dependency`), never
+fake-green. Engine code never imports the tidy3d client: its
+version is read from installed metadata, and the smoke path
+runs with the network amputated (see the locality test). A
+full `deck.tool: meow` Engine adapter is follow-up, out of
+scope.
+"""
+
+from importlib import metadata as _metadata
+
+from ..errors import AdapterError
+
+MEOW_PIN = "0.15.0"
+TIDY3D_PIN = "2.10.0"
+
+WL_UM = 1.55
+CELL_UM = 10.0
+NUM_MODES = 2
+SI_HEIGHT_UM = 0.22
+X_HALF_UM = 2.0
+Y_HALF_UM = 2.0
+NX = 61
+NY = 41
+
+
+def meow_version():
+    """Proven solver version, observable per run (uv.lock pin).
+
+    Returns:
+        Installed meow version, or "unknown" when the package
+            carries no version attribute.
+
+    Raises:
+        AdapterError: missing_dependency when meow is not
+            importable.
+    """
+    try:
+        import meow
+    except ImportError as exc:
+        raise AdapterError(
+            "missing_dependency",
+            f"meow is not importable: {exc} "
+            "(uv sync).",
+        ) from exc
+    return getattr(meow, "__version__", "unknown")
+
+
+def tidy3d_version():
+    """FDE backend version, read from metadata (never a client import).
+
+    Returns:
+        Installed tidy3d version from package metadata.
+
+    Raises:
+        AdapterError: missing_dependency when tidy3d is not
+            installed.
+    """
+    try:
+        return _metadata.version("tidy3d")
+    except _metadata.PackageNotFoundError as exc:
+        raise AdapterError(
+            "missing_dependency",
+            f"tidy3d is not installed: {exc} "
+            "(uv sync).",
+        ) from exc
+
+
+def run_eme_smoke(*, widths_um=(0.5,), wl_um=WL_UM, cell_length_um=CELL_UM,
+                  num_modes=NUM_MODES):
+    """Run the EME smoke live; return the fundamental S-parameters.
+
+    Returns `{meow_version, tidy3d_version, wl_um, widths_um[],
+    cell_length_um, num_modes, neff_re[], neff_im[], transmission,
+    reflection, s21_phase_rad, ports}` — plain floats, JSON-friendly.
+    `transmission`/`reflection` are |S21|^2/|S11|^2 of the
+    fundamental; `neff_*` is the input guide's modal basis.
+
+    Args:
+        widths_um: Strip widths in um, one cross-section each.
+        wl_um: Wavelength in um (positive).
+        cell_length_um: EME cell length in um (positive).
+        num_modes: Modes per cross-section (at least 1).
+
+    Returns:
+        Fundamental S-parameter evidence mapping (versions,
+            widths, modal basis, transmission/reflection, ports).
+
+    Raises:
+        AdapterError: invalid_command on bad parameters,
+            missing_dependency where meow is uninstalled.
+    """
+    try:
+        widths = [float(w) for w in widths_um]
+    except (TypeError, ValueError) as exc:
+        raise AdapterError(
+            "invalid_command",
+            f"EME smoke needs a list of widths in um, got {widths_um!r}.",
+        ) from exc
+    if not widths or any(not w > 0 for w in widths):
+        raise AdapterError(
+            "invalid_command",
+            f"EME smoke needs positive widths in um, got {widths_um!r}.",
+        )
+    if not wl_um > 0 or not cell_length_um > 0:
+        raise AdapterError(
+            "invalid_command",
+            f"EME smoke needs positive wl/cell_length, got wl_um={wl_um!r} "
+            f"cell_length_um={cell_length_um!r}.",
+        )
+    if not isinstance(num_modes, int) or num_modes < 1:
+        raise AdapterError(
+            "invalid_command", f"EME smoke needs num_modes >= 1, got {num_modes!r}."
+        )
+    try:
+        import numpy as np
+
+        from meow import MATERIALS, CrossSection, Environment, Mesh2D, Rectangle
+        from meow.eme import compute_s_matrix
+        from meow.fde.tidy3d import compute_modes_tidy3d
+        from meow.structures import Structure2D
+    except ImportError as exc:
+        raise AdapterError(
+            "missing_dependency",
+            f"meow is not importable: {exc} "
+            "(uv sync).",
+        ) from exc
+    env = Environment(wl=wl_um)
+    mesh = Mesh2D(
+        x=np.linspace(-X_HALF_UM, X_HALF_UM, NX),
+        y=np.linspace(-Y_HALF_UM, Y_HALF_UM, NY),
+    )
+    silicon = MATERIALS["silicon"]
+    oxide = MATERIALS["silicon_oxide"]
+
+    def _strip(width):
+        return CrossSection(
+            structures=[
+                Structure2D(
+                    material=oxide,
+                    geometry=Rectangle(
+                        x_min=-X_HALF_UM, x_max=X_HALF_UM,
+                        y_min=-Y_HALF_UM, y_max=0.0,
+                    ),
+                ),
+                Structure2D(
+                    material=silicon,
+                    geometry=Rectangle(
+                        x_min=-width / 2, x_max=width / 2,
+                        y_min=0.0, y_max=SI_HEIGHT_UM,
+                    ),
+                ),
+            ],
+            mesh=mesh,
+            env=env,
+        )
+
+    molten = [
+        compute_modes_tidy3d(_strip(width), num_modes=num_modes)
+        for width in widths
+    ]
+    s_dense, port_map = compute_s_matrix(
+        molten, cell_lengths=[cell_length_um] * len(widths)
+    )
+    matrix = np.asarray(s_dense, dtype=complex)
+    i_in = port_map["left@0"]
+    i_out = port_map["right@0"]
+    s21 = matrix[i_out, i_in]
+    s11 = matrix[i_in, i_in]
+    return {
+        "meow_version": meow_version(),
+        "tidy3d_version": tidy3d_version(),
+        "wl_um": wl_um,
+        "widths_um": widths,
+        "cell_length_um": cell_length_um,
+        "num_modes": num_modes,
+        "neff_re": [float(np.real(mode.neff)) for mode in molten[0]],
+        "neff_im": [float(np.imag(mode.neff)) for mode in molten[0]],
+        "transmission": float(abs(s21) ** 2),
+        "reflection": float(abs(s11) ** 2),
+        "s21_phase_rad": float(np.angle(s21)),
+        "ports": dict(port_map),
+    }

rocket_engine/adapters/meow/_driver.py

@@ -0,0 +1,227 @@
+"""Staged meow EME driver: job JSON in, framed result envelope on stdout.
+
+The adapter copies this file into the run workdir next to
+`meow_job.json` and executes `python meow_driver.py meow_job.json`.
+The envelope is framed between ROCKETEDA-ENVELOPE-BEGIN/END marker
+lines; solver warnings may share stdout — the adapter extracts the
+frame and logs the rest, never fatal.
+
+Cross-sections are built from the project spec (`doc` widths_um /
+wl_um / cell_length_um): nothing is hardcoded — widths, wavelength,
+cell length, and both mode counts ride the job. Each device solves
+twice (base then refined modes) so the envelope always carries
+two-resolution convergence evidence. The mesh, materials, and strip
+stack mirror the MEOW-LIVE smoke exactly (500x220nm Si on SiO2,
+2.0um half-window, 61x41 grid). Mode solving uses meow's tidy3d FDE
+backend — the local CPU eigensolver proven in the smoke (no
+`tidy3d.web` import anywhere on this path). FDTD/FEM stay out:
+proposed, not proven.
+
+Envelope: `{"ok": true, "meow_version, "tidy3d_version, "result":
+{wl_um, widths_um[], cell_length_um, base, refined, convergence,
+ports}}` or `{"ok": false, "error": {code, message, token,
+line}}`. Exit 0 on sim success, 2 on a malformed device, 3 when
+meow is not importable. Anything else explodes with a traceback
+and exit 1, which parse() reports as runner_unavailable rather
+than mistaking a tool crash for physics.
+"""
+
+import json
+import re
+import sys
+
+_QUOTED_RE = re.compile(r"""['\"]([^'\"]+)['\"]""")
+_TOKEN_KEYS = ("widths_um", "wl_um", "cell_length_um", "modes", "device")
+
+X_HALF_UM = 2.0
+Y_HALF_UM = 2.0
+NX = 61
+NY = 41
+SI_HEIGHT_UM = 0.22
+
+_ENVELOPE_BEGIN = "ROCKETEDA-ENVELOPE-BEGIN"
+_ENVELOPE_END = "ROCKETEDA-ENVELOPE-END"
+
+
+def _token(doc, message):
+    names = list(_TOKEN_KEYS) + [str(doc.get("device") or "")]
+    for name in names:
+        if name and re.search(r"\b" + re.escape(name) + r"\b", message):
+            return name
+    for match in _QUOTED_RE.finditer(message):
+        return match.group(1)
+    return None
+
+
+def _find_line(text, token):
+    if not token:
+        return None
+    for number, line in enumerate(text.splitlines(), 1):
+        if token in line:
+            return number
+    return None
+
+
+def _emit(payload):
+    """Print one marker-framed JSON envelope on stdout.
+
+    Marker literals mirror src/adapters/meow/_envelope.py — this
+    file stages standalone, so change both or neither.
+    """
+    print(_ENVELOPE_BEGIN)
+    print(json.dumps(payload))
+    print(_ENVELOPE_END)
+
+
+def _fail(code, message, token, line):
+    _emit(
+        {
+            "ok": False,
+            "error": {
+                "code": code,
+                "message": message,
+                "token": token,
+                "line": line,
+            },
+        }
+    )
+
+
+def main(argv):
+    """Run one staged meow EME solve: job JSON in, envelope on stdout.
+
+    Args:
+        argv: Argument vector; argv[1] is the staged job JSON path.
+
+    Returns:
+        Process exit code: 0 on sim success, 2 on a malformed
+            device, 3 when meow is not importable.
+
+    Raises:
+        ValueError: Bad device geometry (raised and caught inside
+            main into the invalid_device envelope — never escapes).
+    """
+    with open(argv[1], encoding="utf-8") as handle:
+        job = json.load(handle)
+    text = job.get("text", "")
+    doc = job["doc"]
+    try:
+        import numpy as np
+
+        import meow
+        from meow import MATERIALS, CrossSection, Environment, Mesh2D, Rectangle
+        from meow.eme import compute_s_matrix
+        from meow.fde.tidy3d import compute_modes_tidy3d
+        from meow.structures import Structure2D
+    except ImportError as exc:
+        _fail(
+            "missing_dependency",
+            f"meow is not importable: {exc} "
+            "(uv sync).",
+            None,
+            None,
+        )
+        return 3
+    try:
+        widths = [float(w) for w in doc["widths_um"]]
+        wl_um = float(doc["wl_um"])
+        cell_um = float(doc["cell_length_um"])
+        if not widths or any(not w > 0 for w in widths):
+            raise ValueError(f"widths_um must be positive: {widths!r}.")
+        if not wl_um > 0 or not cell_um > 0:
+            raise ValueError("wl_um/cell_length_um must be positive.")
+        env = Environment(wl=wl_um)
+        mesh = Mesh2D(
+            x=np.linspace(-X_HALF_UM, X_HALF_UM, NX),
+            y=np.linspace(-Y_HALF_UM, Y_HALF_UM, NY),
+        )
+        silicon = MATERIALS["silicon"]
+        oxide = MATERIALS["silicon_oxide"]
+
+        def _strip(width):
+            return CrossSection(
+                structures=[
+                    Structure2D(
+                        material=oxide,
+                        geometry=Rectangle(
+                            x_min=-X_HALF_UM, x_max=X_HALF_UM,
+                            y_min=-Y_HALF_UM, y_max=0.0,
+                        ),
+                    ),
+                    Structure2D(
+                        material=silicon,
+                        geometry=Rectangle(
+                            x_min=-width / 2, x_max=width / 2,
+                            y_min=0.0, y_max=SI_HEIGHT_UM,
+                        ),
+                    ),
+                ],
+                mesh=mesh,
+                env=env,
+            )
+
+        def _solve(num_modes):
+            molten = [
+                compute_modes_tidy3d(_strip(width), num_modes=num_modes)
+                for width in widths
+            ]
+            dense, port_map = compute_s_matrix(
+                molten, cell_lengths=[cell_um] * len(widths)
+            )
+            matrix = np.asarray(dense, dtype=complex)
+            s21 = matrix[port_map["right@0"], port_map["left@0"]]
+            s11 = matrix[port_map["left@0"], port_map["left@0"]]
+            return {
+                "num_modes": num_modes,
+                "neff_re": [float(np.real(m.neff)) for m in molten[0]],
+                "neff_im": [float(np.imag(m.neff)) for m in molten[0]],
+                "transmission": float(abs(s21) ** 2),
+                "reflection": float(abs(s11) ** 2),
+                "s21_phase_rad": float(np.angle(s21)),
+            }, dict(port_map)
+
+        modes = doc["modes"]
+        base, ports = _solve(int(modes["base"]))
+        refined, _ = _solve(int(modes["refined"]))
+    except (ValueError, KeyError, TypeError) as exc:
+        message = f"{type(exc).__name__}: {exc}"
+        token = _token(doc, message)
+        _fail("invalid_device", message, token, _find_line(text, token))
+        return 2
+    try:
+        from importlib import metadata as _metadata
+
+        tidy3d_version = _metadata.version("tidy3d")
+    except Exception:
+        tidy3d_version = "unknown"
+    _emit(
+        {
+            "ok": True,
+            "meow_version": getattr(meow, "__version__", "unknown"),
+            "tidy3d_version": tidy3d_version,
+            "result": {
+                "wl_um": wl_um,
+                "widths_um": widths,
+                "cell_length_um": cell_um,
+                "base": base,
+                "refined": refined,
+                "convergence": {
+                    "dT": abs(
+                        refined["transmission"] - base["transmission"]
+                    ),
+                    "dR": abs(
+                        refined["reflection"] - base["reflection"]
+                    ),
+                    "dneff": abs(
+                        refined["neff_re"][0] - base["neff_re"][0]
+                    ),
+                },
+                "ports": ports,
+            },
+        }
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv))

rocket_engine/adapters/meow/_envelope.py

@@ -0,0 +1,108 @@
+"""Marker-delimited stdout envelope extraction for the meow sim driver.
+
+The driver contract used to be "exactly one JSON document on
+stdout", but solver libraries print warnings there anyway: tidy3d
+logs its unwritable-config warning to stdout on import, which
+turned healthy solves into `runner_unavailable` (MEOW-STDOUT).
+The driver now frames its envelope between BEGIN/END marker
+lines; this module finds that frame and falls back to a tolerant
+JSON scan for unmarked streams (older staged drivers, canned
+test envelopes). Anything outside the envelope is solver
+chatter: it is logged at warning level and never fatal.
+
+Marker contract: the literal marker strings below are duplicated
+in `src/adapters/meow/_driver.py`, which is staged standalone
+into run workdirs and cannot import this module. Change both or
+neither.
+"""
+
+import json
+import logging
+
+_LOGGER = logging.getLogger(__name__)
+
+BEGIN_MARKER = "ROCKETEDA-ENVELOPE-BEGIN"
+END_MARKER = "ROCKETEDA-ENVELOPE-END"
+_CHATTER_PREVIEW = 500
+
+
+def _log_chatter(chatter):
+    """Log solver chatter at warning level, truncated, never fatal."""
+    text = (chatter or "").strip()
+    if text:
+        _LOGGER.warning(
+            "meow driver stdout chatter (%d bytes, never fatal): %s",
+            len(text),
+            text[:_CHATTER_PREVIEW],
+        )
+
+
+def _scan_candidates(stdout):
+    """[(value, start, end)] for every top-level JSON value in order."""
+    decoder = json.JSONDecoder()
+    found = []
+    index = 0
+    while index < len(stdout):
+        if stdout[index] not in "{[":
+            index += 1
+            continue
+        try:
+            value, end = decoder.raw_decode(stdout, index)
+        except ValueError:
+            index += 1
+            continue
+        found.append((value, index, end))
+        index = end if end > index else index + 1
+    return found
+
+
+def extract_envelope(stdout):
+    """Extract the driver's JSON envelope from possibly noisy stdout.
+
+    Clean streams parse exactly as before; marked streams use the
+    BEGIN/END frame authoritatively (a decoy JSON object in the
+    chatter never wins); unmarked noisy streams fall back to a
+    tolerant scan preferring the envelope-shaped value. Solver
+    chatter is logged at warning level and never fatal.
+
+    Args:
+        stdout: Raw driver stdout, possibly with solver warnings
+            or banners around the JSON envelope.
+
+    Returns:
+        Parsed envelope value (the adapter validates its shape),
+            or None when no envelope is present.
+
+    Caution: A corrupt marked frame returns None rather than
+        scanning for a substitute — the frame is authoritative,
+        so garbage inside it is a corrupt envelope, not chatter.
+    """
+    if not isinstance(stdout, str):
+        return None
+    try:
+        return json.loads(stdout)
+    except ValueError:
+        pass
+    begin = stdout.find(BEGIN_MARKER)
+    if begin >= 0:
+        end = stdout.find(END_MARKER, begin + len(BEGIN_MARKER))
+        if end > begin:
+            frame = stdout[begin + len(BEGIN_MARKER):end]
+            try:
+                value = json.loads(frame.strip())
+            except ValueError:
+                _log_chatter(stdout)
+                return None
+            _log_chatter(stdout[:begin] + stdout[end + len(END_MARKER):])
+            return value
+    candidates = _scan_candidates(stdout)
+    if not candidates:
+        _log_chatter(stdout)
+        return None
+    for value, start, end in reversed(candidates):
+        if isinstance(value, dict) and "ok" in value:
+            _log_chatter(stdout[:start] + stdout[end:])
+            return value
+    value, start, end = candidates[-1]
+    _log_chatter(stdout[:start] + stdout[end:])
+    return value