aec-agent-core 1.0.0.dev0__tar.gz

aec_agent_core-1.0.0.dev0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2026 Sean O'Connell
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

aec_agent_core-1.0.0.dev0/PKG-INFO

@@ -0,0 +1,75 @@
+Metadata-Version: 2.4
+Name: aec-agent-core
+Version: 1.0.0.dev0
+Summary: The shared core of LLM agents that review and produce architecture, engineering and construction documents: model connections, vision calls, guards and records, Word and Excel, and a figure helper. No user interface of its own.
+Author-email: Sean O'Connell <soconnell345@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/soconnell345-geotech/GeotechStaffEngineer
+Project-URL: Repository, https://github.com/soconnell345-geotech/GeotechStaffEngineer
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.26
+Requires-Dist: scipy>=1.13
+Requires-Dist: deepagents<0.7.25,>=0.6.8
+Requires-Dist: langchain<1.4.6,>=1.3
+Requires-Dist: langgraph<1.3,>=1.2
+Requires-Dist: typing_extensions>=4.13
+Requires-Dist: openai<3.29.1
+Requires-Dist: langchain-openai>=1.3
+Requires-Dist: matplotlib>=3.8
+Requires-Dist: plotly>=5
+Requires-Dist: python-docx>=1.1
+Requires-Dist: markdown-it-py>=3
+Requires-Dist: openpyxl>=3.1
+Requires-Dist: planlens>=0.14
+Provides-Extra: anthropic
+Requires-Dist: langchain-anthropic>=1.4; extra == "anthropic"
+Dynamic: license-file
+
+# aec-agent-core
+
+The shared core of LLM agents that review and produce architecture,
+engineering and construction (AEC) documents. It holds what an agent runs
+below its chat page: the model connections, the vision calls and the file
+tools beside them, the figure helper with its plotting box, the agent's
+guards, limits and kept work, Word and Excel in and out, the run record and
+its checks, and the switches. It has no user interface of its own.
+
+Two applications are built on it:
+
+- **GeotechStaffEngineer** (`pip install geotech-staff-engineer`), the
+  geotechnical engineering agent, which pins this package exactly;
+- a document review application.
+
+## Status
+
+**1.0.0.dev0: an empty package.** It exists so that its build, its tests and
+the applications' pins on it can be checked before any code moves in. The
+only thing in it today is `aec_agent_core.install_aliases`, which lets a
+module keep answering to its old import path after it moves here, as the
+same module object (so an import or a test patch by either name reaches the
+one copy of the code).
+
+It is not yet published; GeotechStaffEngineer installs it from its own
+repository (`pip install -e packages/aec-agent-core`) until it is.
+
+## Install
+
+```
+pip install aec-agent-core              # once published
+pip install "aec-agent-core[anthropic]" # with Claude through LangChain
+```
+
+## Licence
+
+MIT, as GeotechStaffEngineer. See `LICENSE`.

aec_agent_core-1.0.0.dev0/README.md

@@ -0,0 +1,37 @@
+# aec-agent-core
+
+The shared core of LLM agents that review and produce architecture,
+engineering and construction (AEC) documents. It holds what an agent runs
+below its chat page: the model connections, the vision calls and the file
+tools beside them, the figure helper with its plotting box, the agent's
+guards, limits and kept work, Word and Excel in and out, the run record and
+its checks, and the switches. It has no user interface of its own.
+
+Two applications are built on it:
+
+- **GeotechStaffEngineer** (`pip install geotech-staff-engineer`), the
+  geotechnical engineering agent, which pins this package exactly;
+- a document review application.
+
+## Status
+
+**1.0.0.dev0: an empty package.** It exists so that its build, its tests and
+the applications' pins on it can be checked before any code moves in. The
+only thing in it today is `aec_agent_core.install_aliases`, which lets a
+module keep answering to its old import path after it moves here, as the
+same module object (so an import or a test patch by either name reaches the
+one copy of the code).
+
+It is not yet published; GeotechStaffEngineer installs it from its own
+repository (`pip install -e packages/aec-agent-core`) until it is.
+
+## Install
+
+```
+pip install aec-agent-core              # once published
+pip install "aec-agent-core[anthropic]" # with Claude through LangChain
+```
+
+## Licence
+
+MIT, as GeotechStaffEngineer. See `LICENSE`.

aec_agent_core-1.0.0.dev0/aec_agent_core/__init__.py

@@ -0,0 +1,166 @@
+"""aec-agent-core: what document agents run below their chat pages.
+
+1.0.0.dev0 is the empty package of the app split's step 10 (BACKLOG INF-32;
+``module_work/APP_SPLIT_PLAN.md``). It holds one thing, the alias helper
+step 11 uses when it moves a module in here, so the module's old import
+path keeps working until step 16 takes the aliases out:
+
+    # in the old package's __init__.py, e.g. funhouse_agent/__init__.py
+    from aec_agent_core import install_aliases
+    install_aliases({"funhouse_agent.vision_tools": "aec_agent_core.vision_tools"})
+
+From then on ``import funhouse_agent.vision_tools`` (or ``from
+funhouse_agent import vision_tools``) gives the very module object that
+``aec_agent_core.vision_tools`` is, with no stub file left at the old path.
+So git follows the move as a rename, and a test that patches by the old
+name (``monkeypatch.setattr("funhouse_agent.vision_tools.x", ...)``)
+patches the real module, which a re-exporting stub would silently not do.
+
+An alias also covers what lies under the name: with the table above,
+``funhouse_agent.vision_tools.sub`` is ``aec_agent_core.vision_tools.sub``.
+
+The alias is LAZY: nothing is imported until the old name is looked up (an
+import, or ``importlib.util.find_spec``, which imports the target). The module
+keeps its own ``__name__``, ``__spec__`` and ``__file__`` (the new ones).
+"""
+
+from __future__ import annotations
+
+import importlib
+import importlib.abc
+import importlib.machinery
+import sys
+import threading
+from typing import Mapping
+
+__version__ = "1.0.0.dev0"
+
+__all__ = ["install_aliases", "remove_aliases", "aliases", "resolve_alias",
+           "__version__"]
+
+_LOCK = threading.Lock()
+#: old dotted name -> new dotted name, for every installed alias.
+_TABLE: dict[str, str] = {}
+
+
+def _valid_name(name: object) -> bool:
+    return (isinstance(name, str) and bool(name)
+            and all(part.isidentifier() for part in name.split(".")))
+
+
+def resolve_alias(fullname: str) -> str | None:
+    """The new name an old dotted name stands for, or None if none does.
+
+    The longest matching alias wins, so ``a.b`` -> ``x`` and ``a.b.c`` ->
+    ``y`` send ``a.b.c.d`` to ``y.d``.
+    """
+    with _LOCK:
+        table = dict(_TABLE)
+    name = fullname
+    rest: list[str] = []
+    while name:
+        new = table.get(name)
+        if new is not None:
+            return ".".join([new, *reversed(rest)])
+        name, _, last = name.rpartition(".")
+        rest.append(last)
+    return None
+
+
+class _AliasLoader(importlib.abc.Loader):
+    """Hands the import system the already-imported real module."""
+
+    def __init__(self, target: str):
+        self._target = target
+
+    def create_module(self, spec):
+        return importlib.import_module(self._target)
+
+    def exec_module(self, module):
+        # The import system has just set module.__spec__ to the ALIAS spec
+        # (it always does, even on an existing module); put the module's own
+        # back, so reload, pickle by reference and find_spec see the real
+        # module. Nothing else on the module was overwritten: __name__,
+        # __loader__, __package__ and __file__ were already set.
+        spec = _REAL_SPECS.get(self._target)
+        if spec is not None and module is sys.modules.get(self._target):
+            module.__spec__ = spec
+
+
+#: The real spec of every module an alias handed out, kept before the import
+#: system overwrote it (see _AliasLoader.exec_module).
+_REAL_SPECS: dict[str, object] = {}
+
+
+class _AliasFinder(importlib.abc.MetaPathFinder):
+    """Finds an old (aliased) name and answers with the new module."""
+
+    def find_spec(self, fullname, path=None, target=None):
+        new = resolve_alias(fullname)
+        if new is None or new == fullname:
+            return None
+        module = importlib.import_module(new)
+        _REAL_SPECS.setdefault(new, module.__spec__)
+        is_pkg = hasattr(module, "__path__")
+        return importlib.machinery.ModuleSpec(
+            fullname, _AliasLoader(new), is_package=is_pkg)
+
+
+_FINDER = _AliasFinder()
+
+
+def _ensure_finder() -> None:
+    # First in line, so a stale file left at an old path cannot shadow the
+    # moved module.
+    if _FINDER not in sys.meta_path:
+        sys.meta_path.insert(0, _FINDER)
+
+
+def install_aliases(table: Mapping[str, str]) -> None:
+    """Make each old dotted name import as the module of its new name.
+
+    ``table`` maps old name -> new name, both full dotted module names.
+    Installing the same pair twice is harmless; pointing an old name at a
+    different new name, aliasing a name to itself, or aliasing a name that
+    is already imported as a DIFFERENT module raises ``ValueError``, because
+    each would leave two copies of the code or an alias that never applies.
+    """
+    pairs = dict(table)
+    for old, new in pairs.items():
+        if not (_valid_name(old) and _valid_name(new)):
+            raise ValueError(f"not a dotted module name: {old!r} -> {new!r}")
+        if old == new or new.startswith(old + ".") or old.startswith(new + "."):
+            raise ValueError(f"an alias cannot point into itself: {old} -> {new}")
+    with _LOCK:
+        for old, new in pairs.items():
+            have = _TABLE.get(old)
+            if have is not None and have != new:
+                raise ValueError(
+                    f"{old} is already an alias of {have}, not {new}")
+            loaded = sys.modules.get(old)
+            if loaded is not None and loaded is not sys.modules.get(new):
+                raise ValueError(
+                    f"{old} is already imported as its own module; an alias "
+                    f"to {new} would leave two copies")
+        _TABLE.update(pairs)
+        _ensure_finder()
+
+
+def remove_aliases(*olds: str) -> None:
+    """Take aliases out (all of them when no name is given).
+
+    A module already imported by an old name stays in ``sys.modules`` under
+    it; this only stops new imports from resolving. For tests, and for
+    step 16.
+    """
+    with _LOCK:
+        for old in (olds or tuple(_TABLE)):
+            _TABLE.pop(old, None)
+        if not _TABLE and _FINDER in sys.meta_path:
+            sys.meta_path.remove(_FINDER)
+
+
+def aliases() -> dict[str, str]:
+    """A copy of the installed aliases, old name -> new name."""
+    with _LOCK:
+        return dict(_TABLE)

aec_agent_core-1.0.0.dev0/aec_agent_core.egg-info/PKG-INFO

@@ -0,0 +1,75 @@
+Metadata-Version: 2.4
+Name: aec-agent-core
+Version: 1.0.0.dev0
+Summary: The shared core of LLM agents that review and produce architecture, engineering and construction documents: model connections, vision calls, guards and records, Word and Excel, and a figure helper. No user interface of its own.
+Author-email: Sean O'Connell <soconnell345@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/soconnell345-geotech/GeotechStaffEngineer
+Project-URL: Repository, https://github.com/soconnell345-geotech/GeotechStaffEngineer
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.26
+Requires-Dist: scipy>=1.13
+Requires-Dist: deepagents<0.7.25,>=0.6.8
+Requires-Dist: langchain<1.4.6,>=1.3
+Requires-Dist: langgraph<1.3,>=1.2
+Requires-Dist: typing_extensions>=4.13
+Requires-Dist: openai<3.29.1
+Requires-Dist: langchain-openai>=1.3
+Requires-Dist: matplotlib>=3.8
+Requires-Dist: plotly>=5
+Requires-Dist: python-docx>=1.1
+Requires-Dist: markdown-it-py>=3
+Requires-Dist: openpyxl>=3.1
+Requires-Dist: planlens>=0.14
+Provides-Extra: anthropic
+Requires-Dist: langchain-anthropic>=1.4; extra == "anthropic"
+Dynamic: license-file
+
+# aec-agent-core
+
+The shared core of LLM agents that review and produce architecture,
+engineering and construction (AEC) documents. It holds what an agent runs
+below its chat page: the model connections, the vision calls and the file
+tools beside them, the figure helper with its plotting box, the agent's
+guards, limits and kept work, Word and Excel in and out, the run record and
+its checks, and the switches. It has no user interface of its own.
+
+Two applications are built on it:
+
+- **GeotechStaffEngineer** (`pip install geotech-staff-engineer`), the
+  geotechnical engineering agent, which pins this package exactly;
+- a document review application.
+
+## Status
+
+**1.0.0.dev0: an empty package.** It exists so that its build, its tests and
+the applications' pins on it can be checked before any code moves in. The
+only thing in it today is `aec_agent_core.install_aliases`, which lets a
+module keep answering to its old import path after it moves here, as the
+same module object (so an import or a test patch by either name reaches the
+one copy of the code).
+
+It is not yet published; GeotechStaffEngineer installs it from its own
+repository (`pip install -e packages/aec-agent-core`) until it is.
+
+## Install
+
+```
+pip install aec-agent-core              # once published
+pip install "aec-agent-core[anthropic]" # with Claude through LangChain
+```
+
+## Licence
+
+MIT, as GeotechStaffEngineer. See `LICENSE`.

aec_agent_core-1.0.0.dev0/aec_agent_core.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+LICENSE
+README.md
+pyproject.toml
+aec_agent_core/__init__.py
+aec_agent_core.egg-info/PKG-INFO
+aec_agent_core.egg-info/SOURCES.txt
+aec_agent_core.egg-info/dependency_links.txt
+aec_agent_core.egg-info/requires.txt
+aec_agent_core.egg-info/top_level.txt
+tests/test_core_aliases.py

aec_agent_core-1.0.0.dev0/aec_agent_core.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

aec_agent_core-1.0.0.dev0/aec_agent_core.egg-info/requires.txt

@@ -0,0 +1,17 @@
+numpy>=1.26
+scipy>=1.13
+deepagents<0.7.25,>=0.6.8
+langchain<1.4.6,>=1.3
+langgraph<1.3,>=1.2
+typing_extensions>=4.13
+openai<3.29.1
+langchain-openai>=1.3
+matplotlib>=3.8
+plotly>=5
+python-docx>=1.1
+markdown-it-py>=3
+openpyxl>=3.1
+planlens>=0.14
+
+[anthropic]
+langchain-anthropic>=1.4

aec_agent_core-1.0.0.dev0/aec_agent_core.egg-info/top_level.txt

@@ -0,0 +1 @@
+aec_agent_core

aec_agent_core-1.0.0.dev0/pyproject.toml

@@ -0,0 +1,77 @@
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+# The core both agents run below their chat pages (the app split, BACKLOG
+# INF-26 / INF-32; plan module_work/APP_SPLIT_PLAN.md sections 1.1 and 2.3).
+# Step 10 (this file): the package exists, EMPTY apart from the alias helper,
+# with its build, CI and a wheel test. Step 11 moves the code in. Step 12
+# publishes it, on the owner's word; until then nothing publishes it (the
+# publish workflow builds the repository root only).
+[project]
+name = "aec-agent-core"
+# Kept equal to geotech-staff-engineer's exact pin on it (its pyproject) and
+# to aec_agent_core.__version__; webapp/tests/test_wheels.py checks all three.
+version = "1.0.0.dev0"
+description = "The shared core of LLM agents that review and produce architecture, engineering and construction documents: model connections, vision calls, guards and records, Word and Excel, and a figure helper. No user interface of its own."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+authors = [
+    {name = "Sean O'Connell", email = "soconnell345@gmail.com"},
+]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Scientific/Engineering",
+]
+# The list of plan section 1.1, at the caps and floors geotech-staff-engineer
+# has today (its pyproject carries the reasons for each; keep the two in
+# step: webapp/tests/test_version_guard.py reads the agent-stack caps in both
+# files). Step 10 installs nothing new: every line here is already a core
+# requirement of geotech-staff-engineer.
+dependencies = [
+    # numpy 1.26, not 2.0 (INF-53): Foundry's transforms repos hold 1.26.4.
+    "numpy>=1.26",
+    # The plotting box lets the model's code import scipy.
+    "scipy>=1.13",
+    # The agent stack, capped at the versions the offline gate exercised
+    # (INF-03, 2026-10-27).
+    "deepagents>=0.6.8,<0.7.25",
+    "langchain>=1.3,<1.4.6",
+    "langgraph>=1.2,<1.3",
+    # langchain-protocol needs typing_extensions.TypedDict(extra_items=...)
+    # (PEP 728), 4.13 or later; some hosts ship an older one.
+    "typing_extensions>=4.13",
+    # openai 3.x builds its own client on httpx2; 3.29.0 is the highest tested.
+    "openai<3.29.1",
+    "langchain-openai>=1.3",
+    # The figure helper, the plotting box and the chart stack.
+    "matplotlib>=3.8",
+    "plotly>=5",
+    # Word out (and in), Excel out and in.
+    "python-docx>=1.1",
+    "markdown-it-py>=3",
+    "openpyxl>=3.1",
+    # The document layer; the core binds its review tools.
+    "planlens>=0.14",
+]
+
+[project.optional-dependencies]
+# Claude through LangChain. GSE asks for it; a GPT-only host need not.
+anthropic = ["langchain-anthropic>=1.4"]
+
+[project.urls]
+Homepage = "https://github.com/soconnell345-geotech/GeotechStaffEngineer"
+Repository = "https://github.com/soconnell345-geotech/GeotechStaffEngineer"
+
+[tool.setuptools.packages.find]
+include = ["aec_agent_core*"]
+exclude = ["*.tests", "*.tests.*", "tests*"]

aec_agent_core-1.0.0.dev0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

aec_agent_core-1.0.0.dev0/tests/test_core_aliases.py

@@ -0,0 +1,212 @@
+"""The alias helper step 11 uses to keep old import paths working
+(``aec_agent_core.install_aliases``; plan ``module_work/APP_SPLIT_PLAN.md``,
+section 4, "Moves that git can follow").
+
+Each test builds a throwaway pair of packages on disk: ``old_<n>`` (the
+package a module moved out of) and ``new_<n>`` (the one it moved into).
+
+The alias table is process-wide, and from step 11 the apps install their
+own tables before these tests run. So a test removes only the aliases it
+added and checks only its own entries, never that the table is exactly its
+own.
+"""
+
+from __future__ import annotations
+
+import importlib
+import importlib.util
+import itertools
+import pickle
+import sys
+import textwrap
+
+import pytest
+
+import aec_agent_core as core
+
+_COUNTER = itertools.count()
+
+
+@pytest.fixture
+def pair(tmp_path, monkeypatch):
+    """(old, new) package names on sys.path; cleaned up afterwards."""
+    n = next(_COUNTER)
+    old, new = f"old_pkg_{n}", f"new_pkg_{n}"
+
+    def write(rel, text=""):
+        path = tmp_path / rel
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(textwrap.dedent(text), encoding="utf-8")
+
+    write(f"{old}/__init__.py")
+    write(f"{new}/__init__.py")
+    write(f"{new}/tool.py", """
+        VALUE = 1
+
+        def answer():
+            return VALUE
+
+        def made_here():
+            return 42
+        """)
+    write(f"{new}/box/__init__.py", "NAME = 'box'\n")
+    write(f"{new}/box/child.py", "WHO = 'child'\n")
+    monkeypatch.syspath_prepend(str(tmp_path))
+    importlib.invalidate_caches()
+    before = core.aliases()
+    yield old, new, write
+    added = [name for name in core.aliases() if name not in before]
+    if added:                  # remove_aliases() with no name removes ALL
+        core.remove_aliases(*added)
+    for name in list(sys.modules):
+        if name.split(".")[0] in (old, new):
+            del sys.modules[name]
+
+
+def test_the_old_name_is_the_same_module_object(pair):
+    old, new, _ = pair
+    core.install_aliases({f"{old}.tool": f"{new}.tool"})
+    moved = importlib.import_module(f"{old}.tool")
+    real = importlib.import_module(f"{new}.tool")
+    assert moved is real
+    assert sys.modules[f"{old}.tool"] is real
+
+
+def test_from_import_and_the_parent_attribute(pair):
+    old, new, _ = pair
+    core.install_aliases({f"{old}.tool": f"{new}.tool"})
+    exec(f"from {old} import tool as t1\nimport {old}.tool as t2\n"
+         f"assert t1 is t2", {})
+    parent = sys.modules[old]
+    assert parent.tool is sys.modules[f"{new}.tool"]
+
+
+def test_the_module_keeps_its_own_name_spec_and_file(pair):
+    old, new, _ = pair
+    core.install_aliases({f"{old}.tool": f"{new}.tool"})
+    mod = importlib.import_module(f"{old}.tool")
+    assert mod.__name__ == f"{new}.tool"
+    assert mod.__spec__.name == f"{new}.tool"
+    assert mod.__file__.endswith("tool.py") and new in mod.__file__
+    # so reload still works on the real module
+    assert importlib.reload(mod) is mod
+
+
+def test_a_patch_by_the_old_name_reaches_the_real_module(pair, monkeypatch):
+    old, new, _ = pair
+    core.install_aliases({f"{old}.tool": f"{new}.tool"})
+    monkeypatch.setattr(f"{old}.tool.VALUE", 7)
+    real = importlib.import_module(f"{new}.tool")
+    assert real.answer() == 7
+
+
+def test_install_is_lazy(pair):
+    old, new, _ = pair
+    core.install_aliases({f"{old}.tool": f"{new}.tool"})
+    assert f"{new}.tool" not in sys.modules
+    assert f"{old}.tool" not in sys.modules
+
+
+def test_a_package_alias_covers_what_lies_under_it(pair):
+    old, new, _ = pair
+    core.install_aliases({f"{old}.box": f"{new}.box"})
+    child = importlib.import_module(f"{old}.box.child")
+    assert child is importlib.import_module(f"{new}.box.child")
+    assert importlib.import_module(f"{old}.box").NAME == "box"
+
+
+def test_the_longest_alias_wins(pair):
+    old, new, _ = pair
+    core.install_aliases({f"{old}.box": f"{new}.box",
+                          f"{old}.box.other": f"{new}.tool"})
+    assert core.resolve_alias(f"{old}.box.other") == f"{new}.tool"
+    assert core.resolve_alias(f"{old}.box.child") == f"{new}.box.child"
+    assert core.resolve_alias(f"{old}.nothing") is None
+
+
+def test_find_spec_by_the_old_name(pair):
+    old, new, _ = pair
+    core.install_aliases({f"{old}.tool": f"{new}.tool"})
+    spec = importlib.util.find_spec(f"{old}.tool")
+    assert spec is not None and spec.name == f"{old}.tool"
+
+
+def test_a_stale_file_at_the_old_path_does_not_shadow_the_move(pair):
+    old, new, write = pair
+    write(f"{old}/tool.py", "STALE = True\n")
+    importlib.invalidate_caches()
+    core.install_aliases({f"{old}.tool": f"{new}.tool"})
+    mod = importlib.import_module(f"{old}.tool")
+    assert not hasattr(mod, "STALE")
+    assert mod is importlib.import_module(f"{new}.tool")
+
+
+def test_pickle_by_reference_uses_the_real_name(pair):
+    old, new, _ = pair
+    core.install_aliases({f"{old}.tool": f"{new}.tool"})
+    fn = importlib.import_module(f"{old}.tool").made_here
+    assert pickle.loads(pickle.dumps(fn)) is fn
+    assert new.encode() in pickle.dumps(fn)
+
+
+def test_installing_the_same_pair_twice_is_harmless(pair):
+    old, new, _ = pair
+    core.install_aliases({f"{old}.tool": f"{new}.tool"})
+    core.install_aliases({f"{old}.tool": f"{new}.tool"})
+    assert core.aliases()[f"{old}.tool"] == f"{new}.tool"
+    assert sys.meta_path.count(core._FINDER) == 1
+
+
+@pytest.mark.parametrize("table", [
+    {"a.b": "a.b"},
+    {"a.b": "a.b.c"},
+    {"a.b.c": "a.b"},
+    {"a..b": "x"},
+    {"a.b": ""},
+    {"a-b.c": "x.y"},
+])
+def test_aliases_that_could_never_apply_are_refused(table):
+    before = core.aliases()
+    with pytest.raises(ValueError):
+        core.install_aliases(table)
+    after = core.aliases()
+    assert all(after.get(old) == before.get(old) for old in table)
+
+
+def test_repointing_an_alias_is_refused(pair):
+    old, new, _ = pair
+    core.install_aliases({f"{old}.tool": f"{new}.tool"})
+    with pytest.raises(ValueError, match="already an alias"):
+        core.install_aliases({f"{old}.tool": f"{new}.box"})
+
+
+def test_an_old_name_already_imported_as_its_own_module_is_refused(pair):
+    old, new, write = pair
+    write(f"{old}/tool.py", "OWN = True\n")
+    importlib.invalidate_caches()
+    importlib.import_module(f"{old}.tool")
+    with pytest.raises(ValueError, match="two copies"):
+        core.install_aliases({f"{old}.tool": f"{new}.tool"})
+
+
+def test_remove_aliases_stops_new_imports(pair):
+    old, new, _ = pair
+    core.install_aliases({f"{old}.tool": f"{new}.tool"})
+    core.remove_aliases(f"{old}.tool")
+    assert f"{old}.tool" not in core.aliases()
+    # The finder leaves sys.meta_path with the last alias, and stays while
+    # any other alias (an app's table) is still installed.
+    if core.aliases():
+        assert core._FINDER in sys.meta_path
+    else:
+        assert core._FINDER not in sys.meta_path
+    with pytest.raises(ModuleNotFoundError):
+        importlib.import_module(f"{old}.tool")
+
+
+def test_a_missing_target_is_an_import_error(pair):
+    old, new, _ = pair
+    core.install_aliases({f"{old}.gone": f"{new}.gone"})
+    with pytest.raises(ModuleNotFoundError):
+        importlib.import_module(f"{old}.gone")
+