Engines(refactor[mock]): Rename ConcreteEngine to MockEngine

why: "Concrete" named the in-memory simulator engine, but every real
engine (subprocess, control_mode, imsg) is equally a concrete
implementation. Across the Python/Rust ecosystem "Concrete*" is a
test-only convention for "a minimal instantiable ABC subclass", the
opposite of this docs/doctest workhorse, and the word already carries
its id/type sense throughout ops/query/objects. "Mock" names the engine
by its role: the no-tmux, in-memory stand-in.

what:
- Rename ConcreteEngine -> MockEngine and AsyncConcreteEngine ->
  AsyncMockEngine; module concrete.py -> mock.py
- EngineKind.CONCRETE ("concrete") -> EngineKind.MOCK ("mock");
  EngineSpec.concrete() -> EngineSpec.mock(); registry key becomes
  "mock" (available_engines() re-sorts accordingly)
- Rename the benchmark engine key/label; update RESULTS.md and
  grid.json to match
- Keep docstrings describing the in-memory simulation so the name's
  test-double flavor does not mislead doctest readers
- Leave "concrete" untouched where it means a concrete id/target/pane
  handle (ops, query, objects, workspace)

Author: tony

docs/experimental.md

@@ -25,8 +25,8 @@ inspect ``ok``/``status``, or opt into raising with ``raise_for_status()``:
 ```python
 >>> from libtmux.experimental.ops import HasSession, run
 >>> from libtmux.experimental.ops._types import SessionId
->>> from libtmux.experimental.engines import ConcreteEngine
->>> result = run(HasSession(target=SessionId("$0")), ConcreteEngine())
+>>> from libtmux.experimental.engines import MockEngine
+>>> result = run(HasSession(target=SessionId("$0")), MockEngine())
 >>> result.ok
 True
 >>> result.raise_for_status() is result
@@ -46,12 +46,12 @@ only *how* and *where* the command runs.
 | Engine | Transport | Use it for |
 | --- | --- | --- |
 | ``SubprocessEngine`` | one ``tmux`` process per command | the classic path; reproduces today's libtmux behavior |
-| ``ConcreteEngine`` | in-memory, no tmux | tests and dry runs (deterministic, fabricated output) |
+| ``MockEngine`` | in-memory, no tmux | tests and dry runs (deterministic, fabricated output) |
 | ``ControlModeEngine`` | a persistent ``tmux -C`` connection | many commands over one long-lived session |
 | ``ImsgEngine`` | tmux's native binary peer protocol | an opt-in easter egg |
 
 Each has an ``Async*`` counterpart (``AsyncSubprocessEngine``,
-``AsyncConcreteEngine``, ``AsyncControlModeEngine``) behind ``AsyncTmuxEngine``.
+``AsyncMockEngine``, ``AsyncControlModeEngine``) behind ``AsyncTmuxEngine``.
 Construct one directly, bind it to a live server with
 ``SubprocessEngine.for_server(server)``, or select one by name from the engine
 registry:
@@ -61,8 +61,8 @@ registry:
 >>> from libtmux.experimental.ops import HasSession, run
 >>> from libtmux.experimental.ops._types import SessionId
 >>> available_engines()
-('concrete', 'control_mode', 'imsg', 'subprocess')
->>> engine = create_engine("concrete")
+('control_mode', 'imsg', 'mock', 'subprocess')
+>>> engine = create_engine("mock")
 >>> run(HasSession(target=SessionId("$0")), engine).status
 'complete'
 ```
@@ -77,11 +77,11 @@ later operation can target something that does not exist yet. ``execute``
 ```python
 >>> from libtmux.experimental.ops import LazyPlan, SplitWindow, SendKeys
 >>> from libtmux.experimental.ops._types import WindowId
->>> from libtmux.experimental.engines import ConcreteEngine
+>>> from libtmux.experimental.engines import MockEngine
 >>> plan = LazyPlan()
 >>> pane = plan.add(SplitWindow(target=WindowId("@1")))
 >>> _ = plan.add(SendKeys(target=pane, keys="echo hi", enter=True))
->>> outcome = plan.execute(ConcreteEngine())
+>>> outcome = plan.execute(MockEngine())
 >>> outcome.ok
 True
 >>> [r.status for r in outcome.results]
@@ -107,11 +107,11 @@ many times tmux is invoked:
 ```python
 >>> from libtmux.experimental.ops import LazyPlan, SplitWindow, SendKeys, FoldingPlanner
 >>> from libtmux.experimental.ops._types import WindowId
->>> from libtmux.experimental.engines import ConcreteEngine
+>>> from libtmux.experimental.engines import MockEngine
 >>> plan = LazyPlan()
 >>> pane = plan.add(SplitWindow(target=WindowId("@1")))
 >>> _ = plan.add(SendKeys(target=pane, keys="echo hi", enter=True))
->>> plan.execute(ConcreteEngine(), planner=FoldingPlanner()).ok
+>>> plan.execute(MockEngine(), planner=FoldingPlanner()).ok
 True
 ```
 
@@ -125,11 +125,11 @@ description into a few dispatches (its async twin is ``arun``):
 
 ```python
 >>> from libtmux.experimental.fluent import plan
->>> from libtmux.experimental.engines import ConcreteEngine
+>>> from libtmux.experimental.engines import MockEngine
 >>> p = plan()
 >>> pane = p.new_session("dev").window().pane()
 >>> _ = pane.do(lambda c: c.send_keys("vim")).split().do(lambda c: c.send_keys("htop"))
->>> p.run(ConcreteEngine()).ok
+>>> p.run(MockEngine()).ok
 True
 ```
 
@@ -147,10 +147,10 @@ duplicating it:
 
 ```python
 >>> from libtmux.experimental.fluent import plan
->>> from libtmux.experimental.engines import ConcreteEngine
+>>> from libtmux.experimental.engines import MockEngine
 >>> p = plan()
 >>> _ = p.find_or_create_session("dev").window().pane()
->>> p.run(ConcreteEngine()).ok
+>>> p.run(MockEngine()).ok
 True
 ```
 

scripts/bench-results/RESULTS.md

@@ -24,7 +24,7 @@ Shape = `windows x panes-per-window`. Structural builds (no shell-readiness wait
 | builder / imsg | 20.6 | 31.1 | 62.6 | 153.4 | 262.0 (13x) |
 | builder / control_mode | 2.5 | 9.4 | 26.5 | 103.3 | 166.7 (21x) |
 | **pipelined (prototype)** | **1.4** | **7.9** | **20.2** | **65.3** | **115.7 (30x)** |
-| concrete (offline, in-memory) | 0.1 | 0.1 | 0.3 | 1.3 | 1.5 |
+| mock (offline, in-memory) | 0.1 | 0.1 | 0.3 | 1.3 | 1.5 |
 
 Full percentiles at 8x4 (ms):
 
@@ -35,7 +35,7 @@ Full percentiles at 8x4 (ms):
 | imsg | 222 | 283 | 262 | 342 | 421 | 455 | 455 |
 | control_mode | 118 | 180 | 167 | 215 | 216 | 398 | 398 |
 | pipelined | 97 | 123 | 116 | 156 | 165 | 194 | 194 |
-| concrete | 1 | 2 | 2 | 2 | 2 | 2 | 2 |
+| mock | 1 | 2 | 2 | 2 | 2 | 2 | 2 |
 
 Reads:
 
@@ -46,7 +46,7 @@ Reads:
 - **pipelined** (prototype: batch independent creates into ~3 `run_batch`
   round-trips instead of ~34) is fastest overall, ~1.4x over control_mode. Not
   the 11x the round-trip count implies, because the build is **tmux-server-bound**
-  (one shell fork per pane), not round-trip-bound. `concrete` (offline, 1.5 ms)
+  (one shell fork per pane), not round-trip-bound. `mock` (offline, 1.5 ms)
   is the Python floor: the plan/compile layer is negligible; the time is tmux.
 
 ## With vs without shell-readiness wait

scripts/bench-results/grid.json

@@ -144,7 +144,7 @@
     "max_ms": 37.03230095561594
   },
   {
-    "engine": "concrete",
+    "engine": "mock",
     "shape": "1x1",
     "panes": 1,
     "wait": false,
@@ -360,7 +360,7 @@
     "max_ms": 44.18608907144517
   },
   {
-    "engine": "concrete",
+    "engine": "mock",
     "shape": "1x4",
     "panes": 4,
     "wait": false,
@@ -576,7 +576,7 @@
     "max_ms": 78.33038899116218
   },
   {
-    "engine": "concrete",
+    "engine": "mock",
     "shape": "3x3",
     "panes": 9,
     "wait": false,
@@ -792,7 +792,7 @@
     "max_ms": 260.35256509203464
   },
   {
-    "engine": "concrete",
+    "engine": "mock",
     "shape": "5x4",
     "panes": 20,
     "wait": false,
@@ -1008,7 +1008,7 @@
     "max_ms": 454.6383459819481
   },
   {
-    "engine": "concrete",
+    "engine": "mock",
     "shape": "8x4",
     "panes": 32,
     "wait": false,

scripts/bench_engines.py

@@ -29,7 +29,7 @@
   subprocess    builder on SubprocessEngine     (one tmux fork per op)
   control_mode  builder on ControlModeEngine    (one persistent ``tmux -C``)
   imsg          builder on ImsgEngine           (AF_UNIX imsg, socket-injected)
-  concrete      builder on ConcreteEngine       (offline, in-memory: Python floor)
+  mock          builder on MockEngine       (offline, in-memory: Python floor)
   pipelined     prototype: batch independent creates via run_batch (control_mode)
 
 Timing (``run`` = in-process build-only, the clean signal; ``--hyperfine`` also
@@ -71,9 +71,9 @@
 import typer
 
 from libtmux.experimental.engines import (
-    ConcreteEngine,
     ControlModeEngine,
     ImsgEngine,
+    MockEngine,
     SubprocessEngine,
 )
 from libtmux.experimental.engines.base import CommandRequest
@@ -230,9 +230,7 @@ class Impl:
         "control_mode", "builder", lambda s: ControlModeEngine.for_server(s)
     ),
     "imsg": Impl("imsg", "builder", lambda s: ImsgForServer(s), needs_preboot=True),
-    "concrete": Impl(
-        "concrete", "offline", lambda s: ConcreteEngine(), preflight=False
-    ),
+    "mock": Impl("mock", "offline", lambda s: MockEngine(), preflight=False),
     "pipelined": Impl(
         "pipelined", "pipelined", lambda s: ControlModeEngine.for_server(s)
     ),
@@ -353,7 +351,7 @@ def summarize(samples: list[float]) -> dict[str, float]:
 def run(
     shapes: str = typer.Option("1x1,1x4,3x3,5x4,8x4", help="comma WxP shapes"),
     engines: str = typer.Option(
-        "classic,subprocess,control_mode,imsg,concrete,pipelined",
+        "classic,subprocess,control_mode,imsg,mock,pipelined",
         help="comma engine names",
     ),
     wait: bool = typer.Option(False, help="ALSO measure with shell-readiness wait"),

src/libtmux/experimental/engines/__init__.py

@@ -3,7 +3,7 @@
 An *engine* executes a rendered tmux command and returns a structured result.
 Engines are interchangeable behind the :class:`~.base.TmuxEngine` /
 :class:`~.base.AsyncTmuxEngine` protocols, so the same typed operation can run
-through a subprocess (classic), an in-memory simulator (concrete), a persistent
+through a subprocess (classic), an in-memory simulator (mock), a persistent
 ``tmux -C`` control connection, an async transport, or (as an easter egg) tmux's
 native binary peer protocol -- and return the *same* typed result.
 
@@ -26,13 +26,13 @@
     SupportsTmuxVersion,
     TmuxEngine,
 )
-from libtmux.experimental.engines.concrete import AsyncConcreteEngine, ConcreteEngine
 from libtmux.experimental.engines.control_mode import (
     ControlModeEngine,
     ControlModeError,
     ControlModeParser,
 )
 from libtmux.experimental.engines.imsg import ImsgEngine
+from libtmux.experimental.engines.mock import AsyncMockEngine, MockEngine
 from libtmux.experimental.engines.registry import (
     available_engines,
     create_engine,
@@ -41,20 +41,20 @@
 from libtmux.experimental.engines.subprocess import SubprocessEngine
 
 __all__ = (
-    "AsyncConcreteEngine",
     "AsyncControlModeEngine",
+    "AsyncMockEngine",
     "AsyncSubprocessEngine",
     "AsyncTmuxEngine",
     "CommandRequest",
     "CommandResult",
-    "ConcreteEngine",
     "ControlModeEngine",
     "ControlModeError",
     "ControlModeParser",
     "ControlNotification",
     "EngineKind",
     "EngineSpec",
     "ImsgEngine",
+    "MockEngine",
     "SubprocessEngine",
     "SupportsTmuxVersion",
     "TmuxEngine",

src/libtmux/experimental/engines/base.py

@@ -100,7 +100,7 @@ class EngineKind(str, enum.Enum):
     """Named engine families."""
 
     SUBPROCESS = "subprocess"
-    CONCRETE = "concrete"
+    MOCK = "mock"
     CONTROL_MODE = "control_mode"
     IMSG = "imsg"
 
@@ -139,9 +139,9 @@ def subprocess(cls, *, protocol_version: int | None = None) -> EngineSpec:
         return cls(kind=EngineKind.SUBPROCESS, protocol_version=protocol_version)
 
     @classmethod
-    def concrete(cls) -> EngineSpec:
-        """Build a concrete (in-memory) engine spec."""
-        return cls(kind=EngineKind.CONCRETE)
+    def mock(cls) -> EngineSpec:
+        """Build a mock (in-memory) engine spec."""
+        return cls(kind=EngineKind.MOCK)
 
     @classmethod
     def control_mode(cls) -> EngineSpec:

…libtmux/experimental/engines/concrete.py src/libtmux/experimental/engines/mock.pysrc/libtmux/experimental/engines/concrete.py renamed to src/libtmux/experimental/engines/mock.py src/libtmux/experimental/engines/concrete.py renamed to src/libtmux/experimental/engines/mock.py

@@ -1,10 +1,10 @@
 """Deterministic, in-memory engines for tests and docs (no tmux server).
 
-The concrete engines simulate just enough tmux behaviour to exercise the
+The mock engines simulate just enough tmux behaviour to exercise the
 operation contract offline: creation commands that ask for an id
 (``-P -F '#{pane_id}'``) get a fabricated, monotonic id, ``capture-pane`` returns
 canned lines, and everything else succeeds with empty output. A sync
-(:class:`ConcreteEngine`) and async (:class:`AsyncConcreteEngine`) variant share
+(:class:`MockEngine`) and async (:class:`AsyncMockEngine`) variant share
 the same simulation, so the same operation returns the same typed result through
 either, with no tmux required.
 """
@@ -65,7 +65,7 @@ def _new_counters() -> dict[str, int]:
     return {"pane_id": 0, "window_id": 0, "session_id": 0}
 
 
-class ConcreteEngine:
+class MockEngine:
     """Execute operations against an in-memory simulation (synchronous).
 
     Parameters
@@ -84,7 +84,7 @@ class ConcreteEngine:
     --------
     >>> from libtmux.experimental.ops import SplitWindow, CapturePane, run
     >>> from libtmux.experimental.ops._types import WindowId, PaneId
-    >>> engine = ConcreteEngine(capture_lines=("hello", "world"))
+    >>> engine = MockEngine(capture_lines=("hello", "world"))
     >>> run(SplitWindow(target=WindowId("@1")), engine).new_pane_id
     '%1'
     >>> run(SplitWindow(target=WindowId("@1")), engine).new_pane_id
@@ -106,16 +106,16 @@ def run_batch(self, requests: Sequence[CommandRequest]) -> list[CommandResult]:
         return [self.run(req) for req in requests]
 
 
-class AsyncConcreteEngine:
-    """Async sibling of :class:`ConcreteEngine` for offline async tests/docs.
+class AsyncMockEngine:
+    """Async sibling of :class:`MockEngine` for offline async tests/docs.
 
     Examples
     --------
     >>> import asyncio
     >>> from libtmux.experimental.ops import SplitWindow, arun
     >>> from libtmux.experimental.ops._types import WindowId
     >>> async def main():
-    ...     return await arun(SplitWindow(target=WindowId("@1")), AsyncConcreteEngine())
+    ...     return await arun(SplitWindow(target=WindowId("@1")), AsyncMockEngine())
     >>> asyncio.run(main()).new_pane_id
     '%1'
     """

src/libtmux/experimental/engines/registry.py

@@ -11,8 +11,8 @@
 
 from libtmux import exc
 from libtmux.experimental.engines.base import EngineKind
-from libtmux.experimental.engines.concrete import ConcreteEngine
 from libtmux.experimental.engines.control_mode import ControlModeEngine
+from libtmux.experimental.engines.mock import MockEngine
 from libtmux.experimental.engines.subprocess import SubprocessEngine
 
 if t.TYPE_CHECKING:
@@ -34,7 +34,7 @@ def available_engines() -> tuple[str, ...]:
     Examples
     --------
     >>> from libtmux.experimental.engines import available_engines
-    >>> "concrete" in available_engines()
+    >>> "mock" in available_engines()
     True
     >>> "subprocess" in available_engines()
     True
@@ -48,8 +48,8 @@ def create_engine(name: str | EngineKind, **kwargs: t.Any) -> TmuxEngine:
     Examples
     --------
     >>> from libtmux.experimental.engines import create_engine
-    >>> create_engine("concrete")
-    <libtmux.experimental.engines.concrete.ConcreteEngine object at ...>
+    >>> create_engine("mock")
+    <libtmux.experimental.engines.mock.MockEngine object at ...>
     >>> create_engine("nope")
     Traceback (most recent call last):
     ...
@@ -65,5 +65,5 @@ def create_engine(name: str | EngineKind, **kwargs: t.Any) -> TmuxEngine:
 
 
 register_engine(EngineKind.SUBPROCESS.value, SubprocessEngine)
-register_engine(EngineKind.CONCRETE.value, ConcreteEngine)
+register_engine(EngineKind.MOCK.value, MockEngine)
 register_engine(EngineKind.CONTROL_MODE.value, ControlModeEngine)