Merge lab into test/document-module-set-helper

Resolve the overlap with #19 by preserving the whole-cascade stylesheet
helpers alongside #31's document-source/module-set helpers.

Maintainer validation:
- document/module contract and composition guards: 15 passed
- all 54 touched Python test modules: 366 passed
- py_compile: clean
- git diff --check: clean

tests/helpers/import_state.py

@@ -31,6 +31,7 @@ safe for callers that pass both a parent package and a child module.
 """
 
 import sys
+import types
 from contextlib import contextmanager
 
 _ABSENT = object()
@@ -167,3 +168,33 @@ def preserve_import_state(*module_names):
         # Phase 2: restore all parent-package attributes.
         for name, (_, saved_attr) in saved.items():
             _restore_parent_attr(name, saved_attr)
+
+
+# Names under these prefixes are the ones a leaked stub actually breaks: a
+# later test doing ``import src.x`` or ``import core.x`` silently gets the
+# empty stub instead of the real module.
+_GUARDED_PREFIXES = ("src.", "core.")
+
+
+def bare_module_stubs():
+    """Return the ``src.*``/``core.*`` names currently bound to a bare stub.
+
+    A bare stub is a plain :class:`types.ModuleType` with no on-disk
+    ``__file__`` — the object ``types.ModuleType(name)`` produces. That is the
+    same "is this a fake?" test the ``clear_fake_*`` helpers above use, so a
+    module imported from disk is never reported.
+
+    ``MagicMock`` stand-ins are deliberately out of scope: they answer every
+    attribute, so they fail loudly at use rather than silently, and several
+    test modules install them on purpose.
+    """
+    found = set()
+    for name, mod in list(sys.modules.items()):
+        if not name.startswith(_GUARDED_PREFIXES):
+            continue
+        if type(mod) is not types.ModuleType:
+            continue
+        if getattr(mod, "__file__", None):
+            continue
+        found.add(name)
+    return found

tests/helpers/unix_sockets.py

@@ -0,0 +1,46 @@
+"""Bind an AF_UNIX socket at a path the kernel will actually accept.
+
+``sun_path`` is 104 bytes on macOS, terminator included, so a bind path longer
+than 103 characters fails with ``OSError: AF_UNIX path too long``. pytest's
+``tmp_path`` is rooted at ``$TMPDIR``, which on stock macOS is a 49-character
+``/var/folders/<2>/<30>/T/`` path; adding ``pytest-of-<user>/pytest-<n>/`` and
+the test's own (truncated) name spends the rest of the budget before the
+filename is appended.
+
+That is why this reads as flaky rather than broken. Linux allows 108 bytes and
+roots ``$TMPDIR`` at ``/tmp``, so it never bites there; on macOS whether it
+bites depends on the length of ``$TMPDIR``, the test's name, and how many
+digits pytest's run counter is currently using. A run under a shortened
+``$TMPDIR`` passes, the same checkout under the default one does not.
+
+The path is resolved before it is handed back, for the same reason the rest of
+this change resolves temp paths: on macOS ``/tmp`` is a symlink to
+``/private/tmp``, and a test that binds one spelling and asserts on the other
+is comparing two names for the same socket.
+"""
+
+import os
+import shutil
+import socket
+import tempfile
+from contextlib import contextmanager
+
+# Short enough to leave room for the socket's own name under every platform's
+# sun_path budget. A relative root would depend on the working directory.
+_SHORT_ROOT = os.path.realpath(tempfile.gettempdir() if os.name == "nt" else "/tmp")
+
+
+@contextmanager
+def bound_unix_socket(name="docker.sock"):
+    """Yield the path of a listening AF_UNIX socket, cleaned up on exit."""
+    directory = os.path.realpath(tempfile.mkdtemp(prefix="odysseus-sock-", dir=_SHORT_ROOT))
+    path = os.path.join(directory, name)
+    if len(path) > 103:  # pragma: no cover - guards the guard
+        raise AssertionError(f"socket path is {len(path)} bytes, over the limit: {path}")
+    sock = socket.socket(socket.AF_UNIX)
+    try:
+        sock.bind(path)
+        yield path
+    finally:
+        sock.close()
+        shutil.rmtree(directory, ignore_errors=True)