From adc6734ff310d96f91deb361df93ed04c378ad27 Mon Sep 17 00:00:00 2001
From: Sam <samjones714@gmail.com>
Date: Fri, 6 Nov 2026 13:51:22 +0000
Subject: [PATCH 1/6] Add /analyse: syntax and undefined-name diagnostics for
 Mantid scripts

A stateless HTTP service the FIA script editors can call on a debounce, returning
Monaco-shaped diagnostics for a reduction script without running it. Built FROM a
pinned Mantid runner tag, because only the interpreter that runs the scripts can
answer questions about them.

- Warm-up imports the framework in a background thread (the import deadlocks inside
  an event loop) and gates readiness on a real algorithm having run: Mantid 7's
  AlgorithmManager reports nothing useful, so readiness creates and deletes a probe
  workspace instead.
- Positions are Monaco's - 1-based lines, 1-based UTF-16 columns, exclusive ends.
  CPython reports code-point offsets, jedi code-point columns, pyflakes UTF-8 byte
  offsets: four conventions, and positions.py is the only module that knows them.
- compile()'s verdict merged with jedi's error-recovering coverage, so one mistake
  yields one diagnostic - the cause where it happened rather than the effect where
  parsing gave up. Ranges are never zero-width because Monaco draws nothing for one.
- Framework names come from dir() on the live modules at warm-up, rendered as a
  generated preamble, and pyflakes reports undefined names over the top. Only star
  imports of those modelled modules are neutralised: blanking `from isis_powder
  import *` claims facility names were supplied, which measured as three false
  positives on a script that runs correctly.
- Analysis runs in a forkserver process pool sized from the cgroup CPU quota, and
  every worker completes a probe analysis before readiness: threads measured 4.6x
  slower than serial on this CPU-bound work, processes 18x faster than threads, and
  an unwarmed worker pays jedi's import inside a user's keystroke.
- script_lsp is at 100% statement and branch coverage without Mantid installed; the
  two framework-only functions are excluded with a stated reason.
---
 .dockerignore                        |  15 ++
 .gitignore                           |  15 ++
 container/mantid_python_script_lsp.D |  33 ++++
 mypy.ini                             |  15 ++
 pyproject.toml                       | 111 ++++++++++++
 script_lsp/__init__.py               |   1 +
 script_lsp/analyse.py                |  76 ++++++++
 script_lsp/app.py                    |  79 ++++++++
 script_lsp/lint.py                   |  91 ++++++++++
 script_lsp/models.py                 | 166 +++++++++++++++++
 script_lsp/pool.py                   | 172 ++++++++++++++++++
 script_lsp/positions.py              | 147 +++++++++++++++
 script_lsp/preamble.py               | 155 ++++++++++++++++
 script_lsp/syntax.py                 | 198 ++++++++++++++++++++
 script_lsp/warmup.py                 | 133 ++++++++++++++
 spike/bench.py                       | 218 ++++++++++++++++++++++
 spike/make_corpus.py                 | 109 +++++++++++
 test/conftest.py                     |  81 +++++++++
 test/test_analyse.py                 | 116 ++++++++++++
 test/test_app.py                     |  31 ++++
 test/test_health.py                  |  83 +++++++++
 test/test_lint.py                    | 181 +++++++++++++++++++
 test/test_models.py                  | 168 +++++++++++++++++
 test/test_pool.py                    | 260 +++++++++++++++++++++++++++
 test/test_positions.py               | 139 ++++++++++++++
 test/test_preamble.py                | 167 +++++++++++++++++
 test/test_syntax.py                  | 217 ++++++++++++++++++++++
 27 files changed, 3177 insertions(+)
 create mode 100644 .dockerignore
 create mode 100644 .gitignore
 create mode 100644 container/mantid_python_script_lsp.D
 create mode 100644 mypy.ini
 create mode 100644 pyproject.toml
 create mode 100644 script_lsp/__init__.py
 create mode 100644 script_lsp/analyse.py
 create mode 100644 script_lsp/app.py
 create mode 100644 script_lsp/lint.py
 create mode 100644 script_lsp/models.py
 create mode 100644 script_lsp/pool.py
 create mode 100644 script_lsp/positions.py
 create mode 100644 script_lsp/preamble.py
 create mode 100644 script_lsp/syntax.py
 create mode 100644 script_lsp/warmup.py
 create mode 100644 spike/bench.py
 create mode 100644 spike/make_corpus.py
 create mode 100644 test/conftest.py
 create mode 100644 test/test_analyse.py
 create mode 100644 test/test_app.py
 create mode 100644 test/test_health.py
 create mode 100644 test/test_lint.py
 create mode 100644 test/test_models.py
 create mode 100644 test/test_pool.py
 create mode 100644 test/test_positions.py
 create mode 100644 test/test_preamble.py
 create mode 100644 test/test_syntax.py

diff --git a/.dockerignore b/.dockerignore
new file mode 100644
index 0000000..ab96cda
--- /dev/null
+++ b/.dockerignore
@@ -0,0 +1,15 @@
+.git
+.gitignore
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+coverage.xml
+test/
+spike/
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..a8bc3cf
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,15 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+coverage.xml
+
+# Built by spike/make_corpus.py from scripts pulled off a live FIA API. That is facility
+# data-reduction code, so it stays out of the repository even though the generator is checked in.
+spike/corpus/
diff --git a/container/mantid_python_script_lsp.D b/container/mantid_python_script_lsp.D
new file mode 100644
index 0000000..2d62d77
--- /dev/null
+++ b/container/mantid_python_script_lsp.D
@@ -0,0 +1,33 @@
+# syntax=docker/dockerfile:1
+
+# The service is only useful if it agrees with what actually runs the scripts, so the base is a
+# Mantid runner image pinned to a runner tag. Moving it is a deliberate act - it changes which names a
+# script may use and what warm-up costs - never a rebuild side effect.
+ARG RUNNER_IMAGE=ghcr.io/fiaisis/mantid
+ARG RUNNER_TAG=7.0.0
+FROM ${RUNNER_IMAGE}:${RUNNER_TAG}
+
+ARG RUNNER_IMAGE
+ARG RUNNER_TAG
+
+LABEL org.opencontainers.image.title="mantid-python-script-lsp" \
+      org.opencontainers.image.description="Mantid-aware Python analysis for the FIA script editors" \
+      org.opencontainers.image.base.name="${RUNNER_IMAGE}:${RUNNER_TAG}"
+
+WORKDIR /mantid_python_script_lsp
+
+COPY . /mantid_python_script_lsp
+RUN python -m pip install --no-cache-dir .
+
+ENV PYTHONUNBUFFERED=1 \
+    MPLBACKEND=Agg
+
+# Port 80, like the other FIA service images (see ../FIA-API/container/fia_api.D), so the Service and
+# its targetPort look the same whichever FIA backend they point at. Binding below 1024 means running
+# as root, as they do; hardening belongs in the Deployment's pod securityContext (runAsNonRoot needs
+# a different port), not in a per-image user that could not bind the port anyway.
+EXPOSE 80
+
+# The base image's ENTRYPOINT is the runner's (`python -c <script>`), which is exactly wrong here.
+ENTRYPOINT ["python", "-m", "uvicorn"]
+CMD ["script_lsp.app:app", "--host", "0.0.0.0", "--port", "80"]
diff --git a/mypy.ini b/mypy.ini
new file mode 100644
index 0000000..2178e06
--- /dev/null
+++ b/mypy.ini
@@ -0,0 +1,15 @@
+[mypy]
+strict = True
+
+# Mantid is a C++ extension with no shipped stubs, and pyflakes has none either. Both are imported
+# only inside functions that the unit tests replace, so this hides nothing we would otherwise check.
+[mypy-mantid.*]
+ignore_missing_imports = True
+
+[mypy-pyflakes.*]
+ignore_missing_imports = True
+
+# jedi carries inline annotations but no py.typed marker, so mypy still treats it as untyped. Its shape
+# is named once, as a Protocol in positions.py, and cast to there rather than assumed everywhere.
+[mypy-jedi.*]
+ignore_missing_imports = True
diff --git a/pyproject.toml b/pyproject.toml
new file mode 100644
index 0000000..ae76a77
--- /dev/null
+++ b/pyproject.toml
@@ -0,0 +1,111 @@
+[project]
+name = "mantid-python-script-lsp"
+version = "1.0.0"
+description = "Mantid-aware Python analysis for the FIA script editors"
+readme = "README.md"
+# Not a preference: the interpreter has to be the one in the runner image (Mantid 7.0.0 ships
+# 3.13), because "does this script make sense" is answered by that interpreter and its packages.
+requires-python = ">= 3.13"
+dependencies = [
+    "fastapi==0.139.0",
+    "pydantic==2.13.4",
+    "uvicorn[standard]==0.51.0",
+    "jedi==0.20.1",
+    "pyflakes==4.1.0",
+]
+
+[project.urls]
+"Repository" = "https://github.com/fiaisis/mantid-python-script-lsp"
+
+[project.optional-dependencies]
+formatting = [
+    "ruff==0.15.21",
+    "mypy==2.2.0",
+    "mantid-python-script-lsp[test]",
+]
+
+test = [
+    "pytest==9.1.1",
+    "pytest-asyncio==1.4.0",
+    "pytest-cov==7.1.0",
+    "pytest-random-order==1.2.0",
+    "pytest-env==1.6.0",
+    "httpx==0.28.1",
+]
+
+all = [
+    "mantid-python-script-lsp[formatting]",
+    "mantid-python-script-lsp[test]",
+]
+
+[tool.setuptools]
+packages = ["script_lsp"]
+
+[tool.ruff]
+line-length = 120
+# Generated by spike/make_corpus.py from live FIA scripts. It is input to a benchmark, not our code:
+# linting it would report problems in facility analysis code, and formatting it would rewrite the very
+# scripts we are measuring. Ruff honours .gitignore, but this holds even when the tree is not a checkout
+# (e.g. mounted read-only into a container).
+extend-exclude = ["spike/corpus"]
+
+[tool.ruff.lint]
+select = [
+    "F", # flake8 - Basic initial rules
+    "E", # pycodestyle (Error) - pep8 compliance
+    "W", # pycodestyle (Warning) - pep8 compliance
+    "C90", # mccabe - flags extremely complex functions
+    "I", # isort - Sort imports and flag missing imports
+    "N", # pep8-naming - Ensures pep8 compliance for naming
+    "UP", # pyupgrade - Automatically upgrade syntax for newer versions
+    "S", # flake8-bandit - Flake8 security
+    "B", # flake8-bugbear - Finding likely bugs and design problems
+    "A", # flake8-builtins - Finds code shadowing builtins
+    "COM", # flake8-commas - Find and fixes issues with commas in lists/dicts
+    "C4", # flake8-comprehensions - Simplify list/dict comprehension
+    "DTZ", # flake8-datetimez - Ensure timezones are enforced for code
+    "EXE", # flake8-executable - Fix issues around shebangs and executable files
+    "ISC", # flake8-implicit-str-concat - Find implicitly concatenated strings
+    "LOG", # flake8-logging - Enforce basic rules with builtin logger
+    "T20", # flake8-print - Remove print statements
+    "PT", # flake8-pytest-style - Fix issues with pytest
+    "Q", # flake8-quotes - Bad quote handling
+    "RET", # flake8-return - Fix issues with return values
+    "SIM", # flake8-simplify - Simplify parts of the code
+    "TCH", # flake8-type-checking - Move imports only for typing behind TYPE_CHECKING
+    "PTH", # flake8-use-pathlib - Replace os with pathlib
+    "TD", # flake8-todos - Enforce basic TODOs
+    "FIX", # flake8-fix me - Resolve the issue instead of a fix me
+    "ERA", # eradicate - Remove commented out code.
+    "PL", "C", "E", "R", "W", # Pylint - does a lot
+    "FLY", # flynt - prefer f string over .format
+    "PERF", # Perflint - Flag performance antipatterns
+    "RUF", # Ruff specific rules
+    "FAST", # FastAPI rules
+]
+ignore = [
+    "S101", # flake8-bandit - Use of assert (all over pytest tests)
+    "ISC001", # Conflicts with the formatter
+    "COM812", # Conflicts with the formatter
+    "TC003", # Conflicts with pydantic
+    "TC002", # Conflicts with pydantic
+    "TC001", # Conflicts with pydantic
+]
+
+[tool.ruff.lint.pylint]
+max-args = 10
+
+[tool.ruff.lint.per-file-ignores]
+# Mantid exists only inside the runner image, so importing it at module level would make the package
+# unimportable - and the unit tests unrunnable - on a dev machine or in CI's plain Python job.
+"script_lsp/warmup.py" = ["PLC0415"]
+# The spike exists to report measurements to a human on stdout, and to import things in a deliberate
+# order (syntax cost before Mantid is imported, then after), which a top-level-imports rule forbids.
+"spike/*.py" = ["T20", "PTH", "PLC0415", "S403", "S603", "S607"]
+# An assertion should read as the expectation it is: `status_code == 200` says more than a named
+# constant would, and a renamed literal is one more thing to get wrong in a test.
+"test/*.py" = ["PLR2004"]
+
+[tool.pytest.ini_options]
+required_plugins = "pytest-random-order"
+testpaths = ["test"]
diff --git a/script_lsp/__init__.py b/script_lsp/__init__.py
new file mode 100644
index 0000000..ed51b07
--- /dev/null
+++ b/script_lsp/__init__.py
@@ -0,0 +1 @@
+"""Mantid-aware Python analysis for the FIA script editors."""
diff --git a/script_lsp/analyse.py b/script_lsp/analyse.py
new file mode 100644
index 0000000..ec5e15e
--- /dev/null
+++ b/script_lsp/analyse.py
@@ -0,0 +1,76 @@
+"""`POST /analyse` - one script in, its diagnostics out.
+
+Two passes answer different questions and both are reported: `compile()` says whether the runner would
+accept the file at all, and pyflakes - over a copy carrying the framework's real names - says whether a
+name exists in the Mantid this service runs. See `script_lsp.syntax` and `script_lsp.lint`.
+
+The handler is `async` and hands the work to a process pool, not a thread. An earlier version was a
+plain `def` handler - "keep CPU work off the event loop" - and measurement says that was the wrong
+instinct: 24 concurrent analyses on the threadpool cost 1,534 ms each, which is 4.6x worse than running
+those 24 one at a time, because `ast.parse` and pyflakes never release the GIL. Worker processes give
+18x the threadpool. See `script_lsp.pool`.
+
+Status codes are part of the contract the frontend branches on, so they are stated rather than left to
+chance:
+
+| code | meaning | what the caller should do |
+| --- | --- | --- |
+| 200 | analysed; `parses` and `diagnostics` describe the script | draw them |
+| 422 | request rejected - over the size cap, or no `content_hash` | stop, this is a bug in the caller |
+| 503 | framework still warming up | retry shortly; keep the previous diagnostics |
+
+FIA-API forwards the status and the body unchanged, so a `503` here is what stops the frontend from
+treating a cold pod as "this script has no errors".
+"""
+
+from __future__ import annotations
+
+from concurrent.futures import ProcessPoolExecutor
+
+from fastapi import APIRouter, HTTPException, Request, status
+
+from script_lsp.models import AnalyseRequest, AnalyseResponse
+from script_lsp.pool import analyse_in_pool
+from script_lsp.warmup import Warmup
+
+analyse = APIRouter(tags=["analyse"])
+
+
+@analyse.post("/analyse", response_model=AnalyseResponse)
+async def analyse_script(body: AnalyseRequest, request: Request) -> AnalyseResponse:
+    """Diagnostics for a script, advisory by construction: nothing here can stop a save.
+
+    Syntax is measured on the script exactly as typed; lint on the analysed copy, whose positions are
+    already mapped back. Lint only runs when the script parses - a half-typed line produces undefined
+    names by the hundred, and the syntax pass is already saying the useful thing about it.
+    """
+    pool = _analysis_pool(request)
+
+    parses, diagnostics = await analyse_in_pool(pool, body.content)
+
+    return AnalyseResponse.build(
+        content_hash=body.content_hash,
+        parses=parses,
+        diagnostics=diagnostics,
+    )
+
+
+def _analysis_pool(request: Request) -> ProcessPoolExecutor:
+    """The worker pool, refusing analysis until it exists - with a reason the caller can log.
+
+    Syntax analysis would technically work before warm-up finishes, and answering anyway is the worse
+    option: a client cannot tell "the script is clean" from "the pod is twenty seconds old", and the
+    first of those is a claim the editor should only make when it is true. Lint needs the warm framework
+    outright - without its names bound, every algorithm call in the script reads as undefined.
+    """
+    warmup: Warmup = request.app.state.warmup
+    if warmup.state.ready and warmup.pool is not None:
+        return warmup.pool
+    raise HTTPException(
+        status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+        detail={
+            "reason": "warming_up",
+            "detail": warmup.state.detail,
+            "warmup_seconds": warmup.state.seconds,
+        },
+    )
diff --git a/script_lsp/app.py b/script_lsp/app.py
new file mode 100644
index 0000000..d8739ce
--- /dev/null
+++ b/script_lsp/app.py
@@ -0,0 +1,79 @@
+"""The FastAPI app.
+
+`/analyse` sits behind the warm-up gate on purpose: analysis is meaningless (and about 2 s slow) until
+the framework is up, and the service says so with a 503 rather than take traffic and stall. The gate also
+holds until the analysis worker pool exists - see `script_lsp.warmup` and `script_lsp.pool`.
+
+Positions in anything this service returns are Monaco's - 1-based lines and 1-based columns counted in
+UTF-16 code units - because converting once, here, under test, is the only way to keep them consistent.
+See `script_lsp.positions`.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from importlib import metadata
+from typing import Any
+
+from fastapi import APIRouter, FastAPI, Request
+from fastapi.responses import JSONResponse
+
+from script_lsp.analyse import analyse
+from script_lsp.warmup import Warmup
+
+SERVICE_NAME = "mantid-python-script-lsp"
+
+# One source of truth for the version: `pyproject.toml`, read back from the installed package. A second
+# literal here is a thing to forget, and a released image advertising the wrong version is worse than one
+# advertising that it was started from a bare checkout.
+
+
+def service_version() -> str:
+    """The installed version, or an honest marker when running from an uninstalled source tree."""
+    try:
+        return metadata.version(SERVICE_NAME)
+    except metadata.PackageNotFoundError:  # a source tree with nothing installed, e.g. someone's first clone
+        return "0.0.0+unknown"
+
+
+SERVICE_VERSION = service_version()
+
+health = APIRouter(tags=["health"])
+
+
+@health.get("/healthz")
+async def healthz() -> dict[str, str]:
+    """Process-up only — deliberately independent of the framework, see `script_lsp.warmup`.
+
+    Named like the rest of FIA (`../FIA-API/fia_api/routers/health.py`, and every probe in `../gitops`
+    points at `/healthz`) so one probe definition works across the estate.
+    """
+    return {"status": "alive"}
+
+
+@health.get("/ready")
+async def ready(request: Request) -> JSONResponse:
+    """503 until the framework is warm and the workers have analysed, with the reason either way."""
+    state: Any = request.app.state.warmup.state
+    payload = {"ready": state.ready, "detail": state.detail, "warmup_seconds": state.seconds}
+    return JSONResponse(payload, status_code=200 if state.ready else 503)
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI) -> AsyncIterator[None]:
+    warmup = Warmup()
+    app.state.warmup = warmup
+    warmup.start()
+    yield
+    warmup.shutdown()
+
+
+app = FastAPI(
+    title=SERVICE_NAME,
+    description="Mantid-aware Python analysis for the FIA script editors",
+    version=SERVICE_VERSION,
+    lifespan=lifespan,
+)
+app.include_router(health)
+app.include_router(analyse)
diff --git a/script_lsp/lint.py b/script_lsp/lint.py
new file mode 100644
index 0000000..dfe38ea
--- /dev/null
+++ b/script_lsp/lint.py
@@ -0,0 +1,91 @@
+"""Undefined names, which is the only lint worth showing a scientist.
+
+pyflakes reports a lot more than this and almost all of it is noise on real code: measured on the real
+corpus it produces 2-3 "imported but unused", 1 "assigned to but never used", and - on a script
+duplicated to the size of the request cap - 35 "redefinition of unused". Style commentary on someone
+else's analysis code, in the colour reserved for code that will not run. So the message types are
+whitelisted down to one.
+
+What is left is worth the round trip because it is the check nothing else in FIA can do: a name is
+reported only if neither the script, nor Python, nor **the framework actually running in the runner
+image** provides it. That is what catches `BinMD` typed as `BinMQ`, and what catches a 6.x-era script
+calling `Configurator()`, which Mantid 7 no longer has.
+
+Severity is `warning`, not `error`, and that is a claim about truth rather than politeness: the runner
+executes scripts with names injected around them, so "this will fail" is not something static analysis
+is entitled to assert. `compile()` is; it is the runner's own parser.
+
+The same reasoning limits *which* names may be reported at all. A name is called undefined only when
+every place it could have come from is known: the script, the builtins, and the framework modules the
+preamble binds. A script that does `from isis_powder import *` brings in names no part of this service
+can enumerate, so pyflakes hedges each unresolved name as `ImportStarUsage` - not `UndefinedName`, and
+not reported. Such a script gets no undefined-name checking, which is the accepted cost of never
+reporting a working script as broken.
+"""
+
+from __future__ import annotations
+
+import ast
+import logging
+
+from pyflakes.checker import Checker
+from pyflakes.messages import UndefinedName
+
+from script_lsp.models import Diagnostic
+from script_lsp.positions import column_at_byte_offset, line_at, source_lines, utf16_length
+from script_lsp.preamble import Preamble, neutralise_star_imports
+
+logger = logging.getLogger(__name__)
+
+# The name pyflakes sees. It appears in nothing we return - messages are rebuilt from the template - but
+# it shows up in anything pyflakes itself logs, so it is kept stable.
+LINT_FILENAME = "script.py"
+
+
+def lint_diagnostics(source: str, preamble: Preamble) -> list[Diagnostic]:
+    """Warnings for one script, positioned in the user's coordinates.
+
+    The caller has already established that the script parses; if it does not, nothing is returned,
+    because a half-typed line produces undefined names by the hundred and the syntax pass is already
+    saying the one true thing about it.
+    """
+    analysed = preamble.text + neutralise_star_imports(source, preamble.modelled_modules)
+
+    try:
+        tree = ast.parse(analysed, LINT_FILENAME)
+    except (SyntaxError, ValueError):
+        return []
+
+    try:
+        messages = Checker(tree, LINT_FILENAME).messages
+    except Exception as failure:  # a lint crash must not cost the user their syntax diagnostics
+        logger.warning("pyflakes failed, reporting syntax only: %r", failure)
+        return []
+
+    user_lines = source_lines(source)
+    diagnostics = []
+    for message in messages:
+        if not isinstance(message, UndefinedName):
+            continue
+        user_line = preamble.to_user_line(message.lineno)
+        if user_line is None:
+            continue
+        # Lines are shifted by the preamble; columns are not, because it only adds whole lines above the
+        # script, so the text of a reported line is identical in both copies. pyflakes' column is a UTF-8
+        # byte offset, which is why this is not the same conversion the syntax pass uses.
+        line_text = line_at(user_lines, user_line)
+        start_column = column_at_byte_offset(line_text, message.col)
+        name = str(message.message_args[0]) if message.message_args else ""
+        diagnostics.append(
+            Diagnostic(
+                # Rebuilt from the template rather than str(message), which prefixes "script.py:12:5: ".
+                message=message.message % message.message_args,
+                severity="warning",
+                source="pyflakes",
+                start_line=user_line,
+                start_column=start_column,
+                end_line=user_line,
+                end_column=start_column + max(1, utf16_length(name)),
+            )
+        )
+    return diagnostics
diff --git a/script_lsp/models.py b/script_lsp/models.py
new file mode 100644
index 0000000..d80e56c
--- /dev/null
+++ b/script_lsp/models.py
@@ -0,0 +1,166 @@
+"""The wire contract between this service, FIA-API and the frontend.
+
+This module is the canonical definition. FIA-API validates the *request* (size cap, auth, rate
+limit) and forwards the response body and status untouched, so the response shape exists in exactly
+two places: here, where it is produced, and `src/lib/types.ts` in `../frontend`, where it is parsed.
+Changing a field here means changing that file; nothing else has to be found and updated.
+
+Positions are Monaco's, not the LSP's: **1-based lines, 1-based columns, counted in UTF-16 code
+units**, with `end_column` exclusive. The field names mirror Monaco's `IMarkerData`
+(`startLineNumber`/`startColumn`/`endLineNumber`/`endColumn` in camelCase) so the marker bridge is a
+field copy rather than a translation layer, and the frontend never has to do arithmetic on a
+position. Python is the odd one out — 0-based columns and byte offsets — so all conversion happens
+before a diagnostic leaves this service, under test, because an off-by-one here is a squiggle under
+the user's cursor pointing at the wrong thing.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from collections.abc import Mapping
+from typing import Final, Literal
+
+from pydantic import BaseModel, Field, field_validator, model_validator
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_MAX_SCRIPT_BYTES: Final = 200_000
+DEFAULT_DIAGNOSTIC_LIMIT: Final = 100
+
+# Restated from FIA-API's cap, deliberately: FIA-API rejects an oversized script, but this service is
+# the thing that would spend CPU parsing it, so it does not rely on its caller to have checked. The cap
+# counts bytes, not characters, and both sides must mean the same thing by it - see "The wire contract"
+# in `AGENTS.md`. Tunable per deployment, but then FIA-API's own cap has to be set from the same value
+# or one of the two starts rejecting scripts the other has already accepted.
+MAX_SCRIPT_BYTES_ENV: Final = "MAX_SCRIPT_BYTES"
+DIAGNOSTIC_LIMIT_ENV: Final = "DIAGNOSTIC_LIMIT"
+
+
+def _positive_int(name: str, default: int, environ: Mapping[str, str] | None = None) -> int:
+    """Read one integer setting, falling back to the default rather than to a crash.
+
+    A typo in a manifest must not produce a pod that refuses every script or returns no diagnostics at
+    all, so a bad value is logged and ignored. Read once, at import: these are deployment settings, not
+    per-request ones, and a cap that changed mid-response would be worse than either value.
+    """
+    environment = os.environ if environ is None else environ
+    raw = environment.get(name)
+    if not raw:
+        return default
+    try:
+        value = int(raw)
+    except ValueError:
+        logger.warning("%s=%r is not a number; using %s", name, raw, default)
+        return default
+    if value < 1:
+        logger.warning("%s=%r is below 1; using %s", name, raw, default)
+        return default
+    return value
+
+
+MAX_SCRIPT_BYTES = _positive_int(MAX_SCRIPT_BYTES_ENV, DEFAULT_MAX_SCRIPT_BYTES)
+
+# A badly broken script can produce one syntax error per line - a bad dedent does exactly that - and
+# an editor cannot show, and the user cannot act on, more than a screenful. Beyond the cap the response
+# says so rather than silently dropping the rest.
+DIAGNOSTIC_LIMIT = _positive_int(DIAGNOSTIC_LIMIT_ENV, DEFAULT_DIAGNOSTIC_LIMIT)
+
+# `info` is deliberately absent. Monaco would render it as a grey squiggle, and a diagnostic nobody can
+# act on in the colour reserved for "nothing is wrong, but" is noise; nothing in this service emits one.
+DiagnosticSeverity = Literal["error", "warning"]
+DiagnosticSource = Literal["compile", "jedi", "pyflakes"]
+
+
+class AnalyseRequest(BaseModel):
+    """A script as it currently stands in the user's editor."""
+
+    content: str = Field(description="The script text, exactly as edited. Not normalised in any way.")
+    content_hash: str = Field(
+        min_length=1,
+        max_length=128,
+        description=(
+            "Client-computed digest of `content`, echoed back unchanged. It is what lets the caller "
+            "throw away a reply that arrived after the user had already typed something else, and "
+            "what FIA-API keys its cache on."
+        ),
+    )
+
+    @field_validator("content")
+    @classmethod
+    def _within_size_cap(cls, content: str) -> str:
+        # Byte length, not character count: the cap is about how much work a request can force, and
+        # it has to mean the same thing here as it does in FIA-API.
+        if (size := len(content.encode())) > MAX_SCRIPT_BYTES:
+            msg = f"script is {size} bytes, over the {MAX_SCRIPT_BYTES} byte limit"
+            raise ValueError(msg)
+        return content
+
+
+class Diagnostic(BaseModel):
+    """One problem with the script, positioned where the editor can draw it."""
+
+    message: str = Field(
+        min_length=1,
+        description=(
+            "Never empty. Where CPython's own text is available it is used in preference to jedi's, "
+            "because 'expected :' beats 'invalid syntax' and a confident wrong message is worse than "
+            "either."
+        ),
+    )
+    severity: DiagnosticSeverity
+    source: DiagnosticSource = Field(
+        description=(
+            "`compile` is the runner's own verdict and the only source that means 'this will not run'; "
+            "`jedi` is error-recovering coverage; `pyflakes` is lint, computed only when the script parses."
+        )
+    )
+    start_line: int = Field(ge=1)
+    start_column: int = Field(ge=1, description="1-based, counted in UTF-16 code units.")
+    end_line: int = Field(ge=1)
+    end_column: int = Field(ge=1, description="Exclusive, the way Monaco reads it.")
+
+    @model_validator(mode="after")
+    def _range_is_not_backwards(self) -> Diagnostic:
+        if (self.end_line, self.end_column) < (self.start_line, self.start_column):
+            msg = f"end {(self.end_line, self.end_column)} is before start {(self.start_line, self.start_column)}"
+            raise ValueError(msg)
+        return self
+
+
+class AnalyseResponse(BaseModel):
+    """The diagnostics for one version of one script."""
+
+    content_hash: str
+    parses: bool = Field(
+        description=(
+            "Whether CPython would accept the script at all - what the runner will do with it. Kept "
+            "apart from the diagnostics so the editor's chip can say 'this will not run' without "
+            "guessing from error counts."
+        )
+    )
+    diagnostics: list[Diagnostic] = Field(default_factory=list)
+    truncated: bool = Field(
+        default=False,
+        description=(
+            f"True when more than {DIAGNOSTIC_LIMIT} were found; the first {DIAGNOSTIC_LIMIT} by position are returned."
+        ),
+    )
+
+    @staticmethod
+    def build(
+        *,
+        content_hash: str,
+        parses: bool,
+        diagnostics: list[Diagnostic],
+        limit: int | None = None,
+    ) -> AnalyseResponse:
+        """Order by position and apply the cap, so the guarantees are stated once, here."""
+        cap = DIAGNOSTIC_LIMIT if limit is None else limit
+        ordered = sorted(diagnostics, key=lambda item: (item.start_line, item.start_column))
+        return AnalyseResponse(
+            content_hash=content_hash,
+            parses=parses,
+            diagnostics=ordered[:cap],
+            truncated=len(ordered) > cap,
+        )
diff --git a/script_lsp/pool.py b/script_lsp/pool.py
new file mode 100644
index 0000000..6cc699b
--- /dev/null
+++ b/script_lsp/pool.py
@@ -0,0 +1,172 @@
+"""Running the analysis where it can actually overlap.
+
+Measured: 24 concurrent analyses on Starlette's threadpool take 1,534 ms each, which
+is 4.6x worse than running the same 24 one after another. `ast.parse` and pyflakes never release the GIL,
+so threads thrash it instead of overlapping. Eight worker processes do the same work at 247 analyses per
+second - 18x the threadpool.
+
+Workers start without importing Mantid, because the analysis needs nothing from the framework at request
+time: the names arrive as a 90-line string from warm-up. That is what makes a process pool affordable
+here — tens of megabytes per worker rather than the quarter-gigabyte the parent pays.
+
+Two details that bite if ignored:
+
+* **forkserver, not fork.** The parent is a threaded asyncio process, and forking one is how you inherit
+  a lock that nobody will ever release again. forkserver forks children from a clean server process.
+* **`os.cpu_count()` is a liar in a container** - it reports the host's cores, not the pod's cgroup
+  quota. Worker count comes from the quota, because a pod with a 1 CPU limit and 8 workers gets CFS
+  throttled in 100 ms bursts, which turns a latency problem into a p95 problem.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import multiprocessing
+import os
+from collections.abc import Mapping
+from concurrent.futures import ProcessPoolExecutor
+from pathlib import Path
+from typing import Final
+
+from script_lsp.lint import lint_diagnostics
+from script_lsp.models import Diagnostic
+from script_lsp.preamble import Preamble
+from script_lsp.syntax import syntax_diagnostics
+
+logger = logging.getLogger(__name__)
+
+WORKERS_ENV: Final = "ANALYSIS_WORKERS"
+WORKER_STARTUP_TIMEOUT_SECONDS: Final = 120
+CGROUP_V2_QUOTA: Final = "/sys/fs/cgroup/cpu.max"
+CGROUP_V1_QUOTA: Final = "/sys/fs/cgroup/cpu/cpu.cfs_quota_us"
+CGROUP_V1_PERIOD: Final = "/sys/fs/cgroup/cpu/cpu.cfs_period_us"
+
+# Set in each worker by the pool initializer. The analysis must not depend on it being anything
+# particular - an empty preamble means "no framework names bound", which the lint pass handles by
+# reporting every framework name, so the warm-up gate is what stops that reaching a user.
+_BOUND_PREAMBLE: Preamble | None = None
+
+
+def analyse_script(content: str) -> tuple[bool, list[Diagnostic]]:
+    """Both passes, in whatever process this runs in. Module level, because it has to be picklable."""
+    parses, diagnostics = syntax_diagnostics(content)
+    if parses and _BOUND_PREAMBLE is not None:
+        diagnostics = [*diagnostics, *lint_diagnostics(content, _BOUND_PREAMBLE)]
+    return parses, diagnostics
+
+
+def bind_preamble(preamble: Preamble) -> None:
+    """Pool initializer: give a worker the names before it analyses anything."""
+    global _BOUND_PREAMBLE  # noqa: PLW0603 - this is what an initializer exists for
+    _BOUND_PREAMBLE = preamble
+    # forkserver children are forked from a clean server process, which never inherited uvicorn's logging
+    # configuration; without this, a worker's warnings - including "pyflakes failed" - go to /dev/null.
+    logging.basicConfig(level=logging.INFO, format="%(levelname)s %(name)s: %(message)s")
+    logger.info("analysis worker %s bound to %s framework names", os.getpid(), preamble.name_count)
+
+
+def _first_line(path: Path) -> str | None:
+    """Read a sysfs/cgroup file, or None. These files report a size of 0, so read rather than stat."""
+    try:
+        return path.read_text(encoding="utf-8").splitlines()[0]
+    except (OSError, IndexError):
+        return None
+
+
+def _divide(numerator: str, denominator: str) -> float | None:
+    try:
+        return float(numerator) / float(denominator)
+    except (ValueError, ZeroDivisionError):
+        return None
+
+
+def cpu_quota() -> float | None:
+    """How many cores this container is allowed, from the cgroup, or None if unlimited.
+
+    Reads cgroup v2 and falls back to v1; either can be absent depending on how the node is mounted, and
+    "absent" is a legitimate answer (unlimited) rather than an error - the same answer a laptop gives.
+    """
+    v2 = _first_line(Path(CGROUP_V2_QUOTA))
+    if v2 is not None:
+        fields = v2.split()
+        if len(fields) != 2:  # noqa: PLR2004 - the documented format is exactly "quota period"
+            return None
+        quota, period = fields
+        return None if quota == "max" else _divide(quota, period)
+
+    v1_quota = _first_line(Path(CGROUP_V1_QUOTA))
+    v1_period = _first_line(Path(CGROUP_V1_PERIOD))
+    if v1_quota is None or v1_period is None:
+        return None
+    try:
+        allowed = float(v1_quota)
+    except ValueError:
+        return None
+    if allowed < 0:
+        return None  # v1 spells "unlimited" as a quota of -1
+    return _divide(v1_quota, v1_period)
+
+
+def worker_count(environ: Mapping[str, str] | None = None, quota: float | None = None) -> int:
+    """How many analysis workers to run.
+
+    One per allowed core, rounded up: more than that gets throttled against the pod's own quota, which
+    makes latency worse rather than better. `ANALYSIS_WORKERS` overrides for a pod whose limits the
+    deployment knows better than the cgroup does.
+    """
+    environment = os.environ if environ is None else environ
+    override = environment.get(WORKERS_ENV)
+    if override:
+        try:
+            requested = int(override)
+        except ValueError:
+            logger.warning("%s=%r is not a number; using the CPU quota", WORKERS_ENV, override)
+        else:
+            if requested < 1:
+                logger.warning("%s=%s is below 1; using the CPU quota", WORKERS_ENV, requested)
+            else:
+                return requested
+
+    if quota is not None:
+        return max(1, round(quota))
+    return max(1, min(4, os.process_cpu_count() or 1))
+
+
+def create_pool(preamble: Preamble) -> ProcessPoolExecutor:
+    """A process pool whose workers already know the framework's names."""
+    workers = worker_count(quota=cpu_quota())
+    context = multiprocessing.get_context("forkserver")
+    pool = ProcessPoolExecutor(
+        max_workers=workers,
+        mp_context=context,
+        initializer=bind_preamble,
+        initargs=(preamble,),
+    )
+    logger.info("analysis pool started with %s worker(s) for %s names", workers, preamble.name_count)
+    return pool
+
+
+def warm(pool: ProcessPoolExecutor) -> None:
+    """Force every worker to start, and to import what analysis needs, before any request arrives.
+
+    `ProcessPoolExecutor` spawns workers on demand, and each one's first analysis pays for importing
+    jedi and pyflakes - measured at ~0.2 s each, which lands as a 670 ms median on the first burst of 24
+    requests and then vanishes. That is the same mistake as warming nothing at all, and readiness is the
+    place that stops it: a pod is not ready until an analysis has actually completed in every worker.
+    """
+    workers = getattr(pool, "_max_workers", 1)
+    probes = [pool.submit(analyse_script, "x = 1\n") for _ in range(workers)]
+    for probe in probes:
+        probe.result(timeout=WORKER_STARTUP_TIMEOUT_SECONDS)
+    logger.info("analysis pool warmed: %s worker(s) completed a probe analysis", workers)
+
+
+async def analyse_in_pool(pool: ProcessPoolExecutor, content: str) -> tuple[bool, list[Diagnostic]]:
+    """Run one analysis off the event loop, in a worker process.
+
+    Exceptions travel back with the future on purpose: a worker that dies on a pathological script should
+    surface as a 500 the service logs, not as a silently empty diagnostic list.
+    """
+    loop = asyncio.get_running_loop()
+    return await loop.run_in_executor(pool, analyse_script, content)
diff --git a/script_lsp/positions.py b/script_lsp/positions.py
new file mode 100644
index 0000000..5b92deb
--- /dev/null
+++ b/script_lsp/positions.py
@@ -0,0 +1,147 @@
+"""Coordinate conversion between CPython, jedi, pyflakes, and Monaco.
+
+Four systems, four conventions:
+
+| source | line | column |
+| --- | --- | --- |
+| CPython `SyntaxError` | 1-based | `offset`, 1-based, **code points** |
+| jedi | 1-based | 0-based, **code points** |
+| pyflakes | 1-based | 0-based, **UTF-8 bytes** |
+| Monaco | 1-based | 1-based, **UTF-16 code units** |
+
+The units are the trap, and pyflakes' is the easiest to miss because it goes through `tokenize` on the
+encoded source: measured, `lábel = nowhere()` gives column 9 where the name starts at code point 8, and
+`a = "😀😀" + nowhere` gives 17 where the name starts at code point 11. Passed straight to Monaco, that
+puts the warning part-way through a word - and only in scripts carrying non-ASCII text, which is most of
+them, since reduction scripts have Greek letters and accented sample descriptions in them.
+
+Python counts characters where Monaco counts the UTF-16 code units JavaScript strings are made of, so
+anything outside the basic multilingual plane - an emoji in a comment, which happens - shifts every
+later column on that line by one. Measured, not assumed: for
+`x = "😀😀" + class`, CPython reports `offset` 12 for the `class` keyword and the squiggle belongs at
+Monaco column 14, with the range ending at 19. Getting this wrong does not crash anything; it draws
+the squiggle a couple of characters off, under the wrong token, which is exactly the kind of defect
+that survives review because the diagnostic itself looks correct.
+
+Line splitting has its own trap: `str.splitlines()` also breaks on `\\r`, `\\v`, `\\f`, `\\x1c`, `\\u2028`
+and friends, while CPython's tokenizer breaks only on `\\n`. A script carrying a stray form feed -
+which does occur in files with a long history - would desync every line number below it if we used
+`splitlines()`, putting every later diagnostic in the wrong place.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+# start_line, start_column, end_line, end_column - all 1-based, columns in UTF-16 units, end exclusive.
+LineRange = tuple[int, int, int, int]
+
+MAX_CODE_POINT = 0xFFFF
+
+
+class JediSyntaxError(Protocol):
+    """The part of jedi's `SyntaxError` we read.
+
+    jedi ships no `py.typed`, so under `--strict` its results arrive as `Any`; naming the shape here is
+    what turns that into a checked attribute access instead of a typo that silently returns None.
+    """
+
+    line: int
+    column: int
+    until_line: int
+    until_column: int
+
+    def get_message(self) -> str: ...
+
+
+def utf16_length(text: str) -> int:
+    """How many UTF-16 code units a Python string occupies - what JavaScript counts."""
+    return sum(2 if ord(char) > MAX_CODE_POINT else 1 for char in text)
+
+
+def source_lines(source: str) -> list[str]:
+    """Split the way CPython's tokenizer does: on `\\n` and nothing else.
+
+    Do not replace this with `str.splitlines()`; see the module docstring.
+    """
+    return [line.removesuffix("\r") for line in source.split("\n")]
+
+
+def line_at(source_lines_list: list[str], line_number: int) -> str:
+    """The text of a 1-based line, or empty when the number is out of range.
+
+    Out-of-range happens: a truncated final line, an error CPython attributes to one past the end. An
+    empty line yields a column of 1, which is wrong-but-harmless, and is far better than the
+    IndexError that would replace every diagnostic with a 500.
+    """
+    if 1 <= line_number <= len(source_lines_list):
+        return source_lines_list[line_number - 1]
+    return ""
+
+
+def column_at(line: str, zero_based_index: int) -> int:
+    """Monaco's 1-based UTF-16 column for a 0-based code-point index into `line`."""
+    clamped = max(0, min(zero_based_index, len(line)))
+    return 1 + utf16_length(line[:clamped])
+
+
+def column_at_byte_offset(line: str, byte_offset: int) -> int:
+    """Monaco's 1-based UTF-16 column for a 0-based **UTF-8 byte** offset into `line`.
+
+    This is what pyflakes reports. Decoding a prefix that stops in the middle of a character - which
+    only happens if the analyser's number is already wrong - drops the partial character rather than
+    raising: a column one place off is cosmetic, a 500 out of the diagnostic path is not.
+    """
+    encoded = line.encode()
+    cut = max(0, min(byte_offset, len(encoded)))
+    return 1 + utf16_length(encoded[:cut].decode(errors="ignore"))
+
+
+def _end(start_line: int, start_column: int, end: tuple[int, int] | None) -> tuple[int, int]:
+    """Fall back to a one-character range when the source gives no usable end.
+
+    `ast` nodes always carry end positions; `SyntaxError` does not, and sometimes reports an end equal
+    to its start - `expected ':'` does, because the missing character has no width. Monaco draws
+    nothing for a zero-width range, so a one-character range is the minimum that is visible. jedi
+    occasionally reports an `until` at or before the start too.
+    """
+    if end is None or end <= (start_line, start_column):
+        return start_line, start_column + 1
+    return end
+
+
+def syntax_error_range(error: SyntaxError, source: str) -> LineRange:
+    """Convert a CPython `SyntaxError` into Monaco's coordinates.
+
+    `offset` is 1-based, so the offending character sits at index `offset - 1`. Some errors have
+    `offset` of None (rare, but `SyntaxError` is constructible with anything in it), which is treated
+    as the start of the line rather than crashing the analysis of an otherwise useful diagnostic.
+    """
+    lines = source_lines(source)
+    start_line = max(1, error.lineno or 1)
+    text = line_at(lines, start_line)
+    start_column = column_at(text, max(0, (error.offset or 1) - 1))
+
+    end = None
+    if error.end_lineno is not None and error.end_offset is not None:
+        end = (error.end_lineno, column_at(line_at(lines, error.end_lineno), error.end_offset - 1))
+    end_line, end_column = _end(start_line, start_column, end)
+    return start_line, start_column, end_line, end_column
+
+
+def jedi_error_range(error: JediSyntaxError, source: str) -> LineRange:
+    """Convert a jedi `SyntaxError` into Monaco's coordinates.
+
+    jedi's columns are 0-based, so no adjustment before conversion. Its `until_*` pair marks where the
+    error was noticed rather than where it begins, and is trusted as the end of the range - which is
+    why the unclosed bracket comes out highlighting the bracket rather than the rest of the file.
+    """
+    lines = source_lines(source)
+    start_line = max(1, error.line or 1)
+    start_column = column_at(line_at(lines, start_line), error.column)
+
+    end = None
+    if error.until_column:
+        end = (error.until_line, column_at(line_at(lines, error.until_line), error.until_column))
+    end_line, end_column = _end(start_line, start_column, end)
+    return start_line, start_column, end_line, end_column
diff --git a/script_lsp/preamble.py b/script_lsp/preamble.py
new file mode 100644
index 0000000..fab97fe
--- /dev/null
+++ b/script_lsp/preamble.py
@@ -0,0 +1,155 @@
+"""The analysis preamble: framework names made visible to static analysis.
+
+Mantid's algorithm functions do not exist until the framework is running. `mantid.simpleapi` mints them
+as attributes at import time, which is why neither pyflakes nor jedi can see them: probed statically,
+`Load` resolves while `CreateSampleWorkspace` resolves to nothing, so a name-based check built on either
+would call a working script broken. Measured on a real reduction script, four ways:
+
+With nothing done, pyflakes reports fourteen "may be undefined, or defined from star imports" and stays
+silent about a misspelled algorithm, because that is one of the fourteen. Binding the framework names but
+leaving the star import in place leaves one of those hedges, and the typo is still hidden behind it.
+Blanking the star import without binding anything invents fourteen lies - `undefined name 'Load'`,
+`'mtd'`, and so on. Bindings *and* blanking is the only combination that is silent on working code and
+still reports `undefined name 'BinMQ'` at the line and column where it was typed.
+
+So the preamble does two things and needs both: it binds every name the live framework exposes
+(`simpleapi`, `api`, `kernel`, `dataobjects`, `geometry` - 1,777 of them), and it blanks the script's own
+framework `import *` lines so pyflakes is allowed to have an opinion about names again. Star imports of
+anything else - facility code, which is not installed here - are left in place, because blanking one is
+a promise that its names were supplied, and that promise cannot be kept.
+
+The bindings are **generated at warm-up, not committed**. The running interpreter is the only authority
+on which algorithms exist, so generating them means the list cannot drift from the pinned base image -
+and it is what makes a 6.x-era script calling `Configurator()` light up, because `Configurator` is not
+a name in Mantid 7.
+
+The preamble is ~90 lines, so every diagnostic pyflakes reports needs its line number moved back by
+exactly that much, and anything reported inside the preamble itself is discarded.
+"""
+
+from __future__ import annotations
+
+import ast
+import builtins
+import importlib
+import itertools
+from collections.abc import Collection, Iterable
+from dataclasses import dataclass
+from types import ModuleType
+from typing import Final
+
+# The modules a reduction script can pull the framework from. Bound together because scripts star-import
+# from several of them, and a missing binding is a false positive - the one failure mode this feature
+# cannot afford.
+FRAMEWORK_MODULES: Final = (
+    "mantid.simpleapi",
+    "mantid.api",
+    "mantid.kernel",
+    "mantid.dataobjects",
+    "mantid.geometry",
+)
+
+# Names bound `a = b = c = None`, this many per line: fewer lines to offset, a trivial parse, and still
+# readable when it is dumped for debugging.
+NAMES_PER_LINE: Final = 20
+
+
+def _comment(indent: str) -> str:
+    return f"{indent}# framework import: these names are supplied by the analysis preamble"
+
+
+@dataclass(frozen=True)
+class Preamble:
+    """The text to prepend, and what it costs in line numbers.
+
+    `modelled_modules` is the set of modules whose names the bindings actually cover. It matters because
+    it is also the set of star imports that may be rewritten away: blanking a star import is a claim that
+    its names have been supplied elsewhere, and for `from isis_powder import *` that claim is false -
+    facility code is deliberately not installed here.
+    """
+
+    text: str
+    line_count: int
+    name_count: int
+    modelled_modules: frozenset[str] = frozenset(FRAMEWORK_MODULES)
+
+    @classmethod
+    def from_names(cls, names: Iterable[str], modelled: frozenset[str] = frozenset(FRAMEWORK_MODULES)) -> Preamble:
+        """Render a name list. Sorted, so the same framework always produces byte-identical output."""
+        ordered = sorted({name for name in names if name.isidentifier()})
+        lines = ["# framework names, generated from the running framework"]
+        lines += [
+            " = ".join(group) + " = None"
+            for group in itertools.batched(ordered, NAMES_PER_LINE, strict=False)  # the last group is short
+        ]
+        text = "\n".join(lines) + "\n"
+        return cls(text=text, line_count=text.count("\n"), name_count=len(ordered), modelled_modules=modelled)
+
+    @classmethod
+    def from_modules(cls, modules: list[ModuleType]) -> Preamble:
+        """Everything the given modules expose, minus builtins (pyflakes knows those already)."""
+        exported = {name for module in modules for name in dir(module) if not name.startswith("_")}
+        return cls.from_names(
+            exported - set(dir(builtins)),
+            frozenset(module.__name__ for module in modules),
+        )
+
+    def to_user_line(self, analysed_line: int) -> int | None:
+        """The script's own line number for a line reported in the analysed source.
+
+        None means the report is about the preamble rather than the user's script, which happens when a
+        binding collides with something in it; such a report is dropped rather than pointed at a line
+        that does not exist.
+        """
+        if analysed_line <= self.line_count:
+            return None
+        return analysed_line - self.line_count
+
+
+def build() -> Preamble:  # pragma: no cover - needs the framework, so it runs in the image, not in a unit test
+    """Generate the preamble from the framework in this process.
+
+    Imports are deferred: this runs from warm-up inside the image, and the modules do not exist anywhere
+    else. Failing to build is a warm-up failure, not a degraded analysis - without the bindings, every
+    algorithm call in every script becomes an "undefined name", which is worse than saying nothing.
+    """
+    return Preamble.from_modules([importlib.import_module(name) for name in FRAMEWORK_MODULES])
+
+
+def neutralise_star_imports(source: str, modelled: Collection[str] = FRAMEWORK_MODULES) -> str:
+    """Replace `from x import *` lines with comments, preserving line numbers.
+
+    Only star imports of modules the preamble binds are rewritten, and the asymmetry is the whole
+    design: rewriting a star import tells pyflakes those names are accounted for, which is true for
+    `mantid.simpleapi` and untrue for `isis_powder`, whose code is not installed. Measured on a script
+    that star-imports facility helpers, rewriting both produces `undefined name 'load_grouping_file'`
+    on a script that runs perfectly. Left alone, pyflakes hedges every unresolved name as
+    `ImportStarUsage` instead - a class the lint pass does not report - so the service goes quiet about
+    that script rather than inventing faults in it. Being silent about what cannot be known beats being
+    confidently wrong.
+
+    Located through the AST rather than by matching text: a script's docstring can contain a line that
+    reads like an import, and rewriting inside a string literal would change the code the user wrote
+    rather than the view the analyser gets. Line numbers are preserved because every diagnostic is
+    reported against them, and continuation lines of a parenthesised import are blanked so nothing after
+    them shifts either.
+    """
+    try:
+        tree = ast.parse(source)
+    except (SyntaxError, ValueError):
+        # Analysis of a script that does not parse is the syntax pass's business, not the linter's.
+        return source
+
+    lines = source.split("\n")
+    for node in ast.walk(tree):
+        if not isinstance(node, ast.ImportFrom) or not any(alias.name == "*" for alias in node.names):
+            continue
+        if node.module not in modelled:
+            continue  # names we cannot supply, so the import has to stay visible to pyflakes
+        start = node.lineno - 1
+        end = node.end_lineno or node.lineno
+        indent = lines[start][: len(lines[start]) - len(lines[start].lstrip())]
+        lines[start] = _comment(indent)
+        for continuation in range(start + 1, end):
+            lines[continuation] = ""
+    return "\n".join(lines)
diff --git a/script_lsp/syntax.py b/script_lsp/syntax.py
new file mode 100644
index 0000000..8322a13
--- /dev/null
+++ b/script_lsp/syntax.py
@@ -0,0 +1,198 @@
+"""Syntax diagnostics, from the two parsers worth querying.
+
+Why both, measured rather than guessed:
+
+| parser | verdict | message quality | coverage |
+| --- | --- | --- | --- |
+| `compile()` | authoritative - the runner's own verdict | exact, and often specifically good | **one error per file** |
+| jedi | error-recovering, so never the verdict | usually generic ("invalid syntax") | **every position** |
+
+So neither is dropped and neither leads. `compile()` decides `parses` and supplies its message for its
+own position. jedi then reports the rest of the file, and where it shows an error `compile()` never
+reached, the fragment holding that error is re-compiled on its own to see whether CPython will give a
+better message for it than jedi will - which it does most of the time, and lies about the rest of the
+time, hence the blocklist below.
+
+Two errors for one typo is not a bug of this arrangement: for an unclosed bracket, jedi puts a
+squiggle on the bracket (the cause) and `compile()` puts one where the parser gave up (the effect).
+Both are true and the first is the useful one.
+
+Nothing here touches Mantid, and nothing here should block: the caller decides severity and the
+editor decides what to draw. The jedi calls are not cheap, so the route runs this in a worker rather
+than on the event loop - see `ANALYSIS.md` when the executor lands.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import cast
+
+import jedi
+
+from .models import Diagnostic
+from .positions import (
+    JediSyntaxError,
+    LineRange,
+    jedi_error_range,
+    source_lines,
+    syntax_error_range,
+)
+
+logger = logging.getLogger(__name__)
+
+# What a single-line fragment "discovers" about itself that is an artefact of the extraction rather
+# than a property of the script: a fragment has no enclosing function or loop, so `return`, `break`,
+# `continue` and `yield` appear to be outside one, and any dedent looks like a missing body once its
+# `def` line has been cut off. Measured against real reduction scripts, these are the four or five
+# lies the technique tells, and a confidently wrong message is worse than jedi's vague one.
+FRAGMENT_ARTEFACTS = (
+    "'return' outside function",
+    "'break' outside loop",
+    "'continue' outside loop",
+    "'yield' outside function",
+    "expected an indented block",
+)
+
+# Indentation complaints in jedi's output, dropped when `compile()` did not report one itself.
+# An indentation error is a claim about a line's leading whitespace *and* about the block structure
+# above it, and the block structure is exactly what a syntax error earlier in the file has already
+# broken. When CPython is reading the same file and stays quiet about indentation, its silence is the
+# better evidence. The cost is a real indentation error hidden behind an earlier one; it reappears on
+# the next save, once the first mistake is fixed.
+JEDI_INDENTATION_CASCADES = (
+    "unexpected indent",
+    "unindent does not match",
+    "expected an indented block",
+    "unexpected de-indent",
+)
+
+
+def syntax_diagnostics(source: str, *, module_name: str = "script.py") -> tuple[bool, list[Diagnostic]]:
+    """Return `(parses, diagnostics)` for a whole script.
+
+    `parses` is whether CPython would accept the file at all - what the runner will do with it. When it
+    is True no syntax diagnostics are returned even if jedi disagrees: the runner's parser is the one
+    that decides whether the user's reduction runs, and telling someone their script is broken when
+    it will run fine is the one thing this feature must never do.
+    """
+    error = _syntax_error(source, module_name)
+    if error is None:
+        return True, []
+
+    primary = _from_compile(error, source)
+    return False, [primary, *_beyond_compile(source, primary)]
+
+
+def _syntax_error(source: str, module_name: str) -> SyntaxError | None:
+    """`compile()`'s verdict, or None when the script parses.
+
+    The non-`SyntaxError` exceptions are not theoretical, and were checked on the interpreter that
+    ships. A source string holding a lone surrogate raises `UnicodeEncodeError`, which is a `ValueError`;
+    enough nesting raises `RecursionError`. A NUL byte, which used to be a `ValueError`, is reported as a
+    plain `SyntaxError` by CPython 3.13 and needs no special handling. All of them become a diagnostic at
+    the top of the file rather than a 500, because losing the whole feature over a pathological script is
+    a bad trade.
+    """
+    try:
+        compile(source, module_name, "exec")
+    except SyntaxError as error:
+        return error
+    except (ValueError, RecursionError, MemoryError) as error:
+        return SyntaxError(f"{type(error).__name__}: {error}", (module_name, 1, 1, None))
+    return None
+
+
+def _from_compile(error: SyntaxError, source: str) -> Diagnostic:
+    start_line, start_column, end_line, end_column = syntax_error_range(error, source)
+    return Diagnostic(
+        message=error.msg or "invalid syntax",
+        severity="error",
+        source="compile",
+        start_line=start_line,
+        start_column=start_column,
+        end_line=end_line,
+        end_column=end_column,
+    )
+
+
+def _beyond_compile(source: str, primary: Diagnostic) -> list[Diagnostic]:
+    """Errors jedi can see that `compile()` could not reach, and are not consequences of its error.
+
+    Two filters, both learned from the measurements:
+
+    * **overlapping** - jedi usually reports the same mistake at the same spot, and drawing two
+      squiggles on one token with two different messages looks like a bug in the editor.
+    * **after** the primary error - everything the parser found past the point it gave up is downstream
+      of it. A missing colon on line 1 also produces "unexpected indent" on line 2, and reporting both
+      teaches the user nothing while pushing a real error off the end of the cap.
+
+    What survives is what jedi is actually for: the cause that sits *before* where CPython stopped -
+    the unclosed bracket three lines earlier, which CPython only notices when it runs out of file.
+    """
+    primary_start = (primary.start_line, primary.start_column)
+    primary_range = (primary.start_line, primary.start_column, primary.end_line, primary.end_column)
+
+    try:
+        # path=None keeps jedi from resolving a project directory it has no use for here.
+        errors = cast("list[JediSyntaxError]", jedi.Script(code=source, path=None).get_syntax_errors())
+    except Exception as failure:  # jedi's own failures must not cost the user compile()'s verdict
+        logger.warning("jedi syntax analysis failed, reporting compile() only: %r", failure)
+        return []
+
+    diagnostics = []
+    for error in errors:
+        found = jedi_error_range(error, source)
+        if (found[0], found[1]) >= primary_start or _overlaps(found, primary_range):
+            continue
+        if _is_indentation_cascade(error.get_message()):
+            continue
+        start_line, start_column, end_line, end_column = found
+        diagnostics.append(
+            Diagnostic(
+                message=_message_for(error, source, found),
+                severity="error",
+                source="jedi",
+                start_line=start_line,
+                start_column=start_column,
+                end_line=end_line,
+                end_column=end_column,
+            )
+        )
+    return diagnostics
+
+
+def _message_for(error: JediSyntaxError, source: str, found: LineRange) -> str:
+    return _fragment_message(source, found) or error.get_message()
+
+
+def _fragment_message(source: str, found: LineRange) -> str | None:
+    """What CPython says about just the lines jedi flagged, when it says something specific.
+
+    Blank lines are prepended so the fragment's own line numbers still match the script's; the
+    position is thrown away and only the message kept, but keeping the numbers aligned makes this
+    function's behaviour legible when it has to be debugged.
+    """
+    start_line, _, end_line, _ = found
+    lines = source_lines(source)
+    fragment = "\n".join([""] * (start_line - 1) + lines[start_line - 1 : max(start_line, end_line)])
+
+    try:
+        compile(fragment, "<fragment>", "exec")
+    except SyntaxError as error:
+        message = error.msg or ""
+        if not message or message.startswith(FRAGMENT_ARTEFACTS):
+            return None
+        return message
+    except Exception:  # a fragment too strange to compile just means no message to offer
+        return None
+    return None
+
+
+def _is_indentation_cascade(message: str) -> bool:
+    """Whether jedi is complaining about indentation that `compile()` found acceptable."""
+    return any(pattern in message for pattern in JEDI_INDENTATION_CASCADES)
+
+
+def _overlaps(first: LineRange, second: LineRange) -> bool:
+    """Whether two half-open `(line, column)` ranges intersect."""
+    return (first[0], first[1]) < (second[2], second[3]) and (second[0], second[1]) < (first[2], first[3])
diff --git a/script_lsp/warmup.py b/script_lsp/warmup.py
new file mode 100644
index 0000000..12f7968
--- /dev/null
+++ b/script_lsp/warmup.py
@@ -0,0 +1,133 @@
+"""Framework warm-up, and the readiness state it gates.
+
+`import mantid.simpleapi` costs roughly two seconds of CPU and a quarter of a gigabyte of RSS, so it
+happens once per worker at startup rather than on the first analysis request, where it would just look
+like the editor had hung. The analysis itself runs elsewhere - in `script_lsp.pool`, where it can
+overlap - and needs nothing from Mantid but the name list generated here.
+
+Readiness waits for it. Liveness must never wait for it: a node that warms slowly would have its pod
+killed mid-warm-up and restart into the same race, which turns a slow start into a crash loop.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import importlib
+import logging
+import time
+from concurrent.futures import ProcessPoolExecutor
+from dataclasses import dataclass
+
+from script_lsp.pool import create_pool, warm
+from script_lsp.preamble import Preamble, build
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class WarmupState:
+    """What warm-up decided, read by two callers and trusted by neither blindly.
+
+    `/ready` renders it, and `/analyse` reads `ready` to decide whether to answer 503 rather than stall.
+    `detail` is a sentence for whoever is reading pod logs: consumers branch on the status code, never on
+    this text.
+    """
+
+    ready: bool = False
+    detail: str = "cold"
+    seconds: float | None = None
+
+
+@dataclass(frozen=True)
+class Framework:
+    """What warm-up produces: a proven framework, and the names it exposes.
+
+    They arrive together because analysis needs both. A warm-up that imported Mantid but could not
+    enumerate its names would turn every algorithm call in every script into an "undefined name", so
+    there is no useful service to run without the preamble - and no readiness without this object.
+    """
+
+    detail: str
+    preamble: Preamble
+
+
+def load_framework() -> (
+    Framework
+):  # pragma: no cover - needs the framework, so it runs in the image, not in a unit test
+    """Import the analysis surface a reduction script sees, prove it works, and learn its names.
+
+    The proof is a real algorithm rather than an attribute check: `CreateSampleWorkspace` needs the
+    algorithm registry, the property system and the analysis data service all to be up, which is
+    exactly what a script needs, and it costs about 8 ms with no input files.
+
+    `AlgorithmManager` is deliberately not used for this. Mantid 7 exposes only
+    `Instance/create/getAlgorithm/size/...` on it, `size()` returns 1 whatever is registered, and
+    `create("Empty")` fails even while `simpleapi` can run well over a thousand algorithms — so it
+    reports nothing usefully and a readiness check built on it would be theatre.
+    """
+    import mantid
+
+    simpleapi = importlib.import_module("mantid.simpleapi")
+    probe = "mantid-python-script-lsp-readiness"
+    simpleapi.CreateSampleWorkspace(OutputWorkspace=probe)
+    simpleapi.DeleteWorkspace(Workspace=probe)
+
+    # Generated here, from the framework that just proved itself, rather than committed as a list that
+    # could disagree with the base image this container was built from.
+    names = build()
+
+    algorithms = sum(1 for name in dir(simpleapi) if name[:1].isupper())
+    detail = (
+        f"Mantid {mantid.__version__}, {algorithms} algorithms, {names.name_count} names bound, "
+        "probe workspace created and deleted"
+    )
+    return Framework(detail=detail, preamble=names)
+
+
+def create_and_warm_pool(preamble: Preamble) -> ProcessPoolExecutor:
+    """Start the workers and prove one analysis completes in each, before readiness says yes."""
+    pool = create_pool(preamble)
+    warm(pool)
+    return pool
+
+
+class Warmup:
+    """Brings up what analysis needs, once, in a worker thread, so the loop keeps answering probes.
+
+    That is two things and not one: the framework (proved by running an algorithm, and the source of the
+    name list), and a pool of analysis workers. Both are readiness - a pod with a warm framework but no
+    workers has nothing to serve with, and a pod with workers but no names would report every algorithm
+    in the corpus as undefined.
+    """
+
+    def __init__(self) -> None:
+        self.state = WarmupState()
+        self.framework: Framework | None = None
+        self.pool: ProcessPoolExecutor | None = None
+        # Held so the task is not garbage collected mid-import; see asyncio docs on create_task.
+        self._task: asyncio.Task[None] | None = None
+
+    def start(self) -> None:
+        self._task = asyncio.create_task(self._run())
+
+    def shutdown(self) -> None:
+        """Stop the workers. Without this, forkserver children outlive the app on a reload."""
+        if self.pool is not None:
+            self.pool.shutdown(wait=False, cancel_futures=True)
+            self.pool = None
+
+    async def _run(self) -> None:
+        started = time.perf_counter()
+        try:
+            framework = await asyncio.to_thread(load_framework)
+            pool = await asyncio.to_thread(create_and_warm_pool, framework.preamble)
+        except Exception as exc:
+            # Reported through readiness rather than propagating: a pod that cannot import Mantid is
+            # not ready, and the exception text in the probe response is what makes that diagnosable.
+            self.state = WarmupState(False, f"{type(exc).__name__}: {exc}", None)
+            logger.exception("Mantid framework warm-up failed")
+            return
+        self.framework = framework
+        self.pool = pool
+        self.state = WarmupState(True, framework.detail, round(time.perf_counter() - started, 2))
+        logger.info("Mantid framework warm in %s s (%s)", self.state.seconds, framework.detail)
diff --git a/spike/bench.py b/spike/bench.py
new file mode 100644
index 0000000..9922901
--- /dev/null
+++ b/spike/bench.py
@@ -0,0 +1,218 @@
+"""What does a Mantid runner image actually cost to run a script-checking service?
+
+Run it inside the built image (see README) against a corpus from `make_corpus.py`. Each measurement
+exists to decide something:
+
+* warm-up (`import mantid` / `simpleapi` / `AlgorithmManager`) -> readiness probe budget, CPU
+  request, and whether warm-up needs a startupProbe rather than a generous liveness timeout.
+* per-request `compile()` / `ast.parse()` latency              -> the editor's debounce interval and
+  the FIA-API upstream timeout.
+* jedi first-call vs warm latency and RSS growth               -> whether completion can share the
+  analyse worker pool, or needs its own warm subprocess.
+* RSS per stage, and the cost of `fork()` when warm            -> memory request, and whether N
+  workers cost N x warm-up (spawn) or ~1 x warm-up plus copy-on-write (fork).
+
+Set SPIKE_SCRIPTS to the corpus directory and SPIKE_REPEATS to change the sampling count.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import gc
+import json
+import os
+import resource
+import statistics
+import sys
+import time
+from pathlib import Path
+from typing import Any
+
+SCRIPTS = Path(os.environ.get("SPIKE_SCRIPTS", "/spike/corpus"))
+REPEATS = int(os.environ.get("SPIKE_REPEATS", "15"))
+
+rows: list[dict[str, Any]] = []
+
+
+def rss_mb() -> float:
+    for line in Path("/proc/self/status").read_text(encoding="utf-8").splitlines():
+        if line.startswith("VmRSS:"):
+            return int(line.split()[1]) / 1024.0
+    return float("nan")
+
+
+def measure(name: str, fn: Any, note: str = "") -> Any:
+    """Time one call of `fn` and record wall time plus resident set size afterwards."""
+    gc.collect()
+    started = time.perf_counter()
+    value = fn()
+    rows.append(
+        {
+            "name": name,
+            "wall_ms": round((time.perf_counter() - started) * 1000, 1),
+            "rss_mb": round(rss_mb(), 1),
+            "note": note,
+        }
+    )
+    # Printed as we go: an import blowing up later must not take the measurements with it.
+    print(f"::stage {rows[-1]}", flush=True)
+    return value
+
+
+def latency_over_corpus() -> dict[str, Any]:
+    """Per-script compile() and ast.parse() latency, sampled warm, as median/p95/max in ms."""
+    import ast  # deferred: this runs before mantid is imported, which is the point of the measurement
+
+    results: dict[str, Any] = {}
+    for path in sorted(SCRIPTS.glob("*.py")):
+        source = path.read_text(encoding="utf-8")
+        # Bound as defaults so each lambda samples the file it was created for; the loop variables
+        # would otherwise be read at call time, and a measurement of the wrong file looks plausible.
+        per_function = {
+            "compile": _sample(lambda source=source, name=path.name: compile(source, name, "exec")),
+            "ast.parse": _sample(lambda source=source, name=path.name: ast.parse(source, name, "exec")),
+        }
+        results[path.name] = {
+            "bytes": len(source.encode()),
+            "lines": len(source.splitlines()),
+            **per_function,
+        }
+    return results
+
+
+def _sample(fn: Any, repeats: int = REPEATS) -> dict[str, float]:
+    timings = []
+    for _ in range(repeats):
+        started = time.perf_counter()
+        with contextlib.suppress(SyntaxError):
+            fn()  # the deliberately broken corpus entry is still a valid latency sample
+        timings.append((time.perf_counter() - started) * 1000)
+    ordered = sorted(timings)
+    return {
+        "median_ms": round(statistics.median(timings), 3),
+        "p95_ms": round(ordered[int(len(ordered) * 0.95) - 1], 3),
+        "max_ms": round(max(timings), 3),
+    }
+
+
+def jedi_probe() -> dict[str, Any]:
+    """jedi's first call in a process costs far more than later ones; measure both."""
+    try:
+        import jedi
+    except ImportError:
+        return {"available": False}
+
+    source = (SCRIPTS / sorted(SCRIPTS.glob("*.py"))[0].name).read_text(encoding="utf-8")
+    # Complete at the end of an `import x as y` line: cheap to find, and the shape a user reaches for
+    # when they want to know what a Mantid object gives them.
+    line, col = 1, 1
+    for index, text in enumerate(source.splitlines(), start=1):
+        stripped = text.strip()
+        if stripped.startswith("import ") and " as " in stripped:
+            line, col = index, len(stripped)
+            break
+
+    started = time.perf_counter()
+    script = jedi.Script(code=source)
+    completions = script.complete(line, col)
+    first_ms = (time.perf_counter() - started) * 1000
+    rss_after_first = rss_mb()
+
+    warm = [
+        _sample(lambda offset=offset: script.complete(line, max(1, col - offset)))["median_ms"] for offset in range(6)
+    ]
+
+    started = time.perf_counter()
+    script.infer(line, col)
+    return {
+        "available": True,
+        "jedi_version": getattr(jedi, "__version__", "?"),
+        "first_complete_ms": round(first_ms, 1),
+        "warm_complete_median_ms": round(statistics.median(warm), 2),
+        "warm_complete_max_ms": round(max(warm), 2),
+        "first_infer_ms": round((time.perf_counter() - started) * 1000, 1),
+        "completions": len(completions),
+        "rss_after_first_mb": round(rss_after_first, 1),
+    }
+
+
+def fork_cost() -> dict[str, Any]:
+    """What adding another worker costs once warm (uvicorn --workers / gunicorn fork on POSIX)."""
+    read_fd, write_fd = os.pipe()
+    started = time.perf_counter()
+    pid = os.fork()
+    fork_ms = (time.perf_counter() - started) * 1000
+
+    if pid == 0:
+        os.close(read_fd)
+        with os.fdopen(write_fd, "w") as pipe:
+            pipe.write(str(rss_mb()))
+        os._exit(0)  # do not run atexit handlers in the probe child
+
+    os.close(write_fd)
+    with os.fdopen(read_fd) as pipe:
+        child_rss = float(pipe.read() or "nan")
+    os.waitpid(pid, 0)
+
+    parent_rss = rss_mb()
+    return {
+        "fork_ms": round(fork_ms, 2),
+        "parent_rss_mb": round(parent_rss, 1),
+        "child_rss_mb": round(child_rss, 1),
+        "child_extra_rss_mb": round(child_rss - parent_rss, 1),
+    }
+
+
+def init_workflow_manager() -> str:
+    """The explicit framework warm-up older reduction scripts call, wherever this Mantid keeps it."""
+    import importlib
+
+    for module_name in ("mantid.api", "mantid.kernel", "mantid.utils"):
+        try:
+            module = importlib.import_module(module_name)
+        except ImportError:
+            continue
+        manager = getattr(module, "WorkflowManager", None)
+        if manager is not None:
+            manager().initialize()
+            return f"{module_name}.WorkflowManager().initialize()"
+    return "not found: simpleapi already initialised the framework"
+
+
+print(f"::env python={sys.version.split()[0]} exe={sys.executable} scripts={SCRIPTS}", flush=True)
+rows.append({"name": "python baseline", "wall_ms": 0.0, "rss_mb": round(rss_mb(), 1), "note": "before any import"})
+
+# 1. The floor: syntax checking with no Mantid in the picture at all.
+syntax_before = measure("syntax pass (before mantid)", latency_over_corpus, "compile+ast.parse over the corpus")
+
+# 2. Warm-up: what the readiness gate is protecting.
+measure("import mantid", lambda: __import__("mantid"))
+measure("from mantid.simpleapi import *", lambda: __import__("mantid.simpleapi", fromlist=["*"]))
+measure(
+    "AlgorithmManager.Instance()",
+    lambda: __import__("mantid.api", fromlist=["AlgorithmManager"]).AlgorithmManager.Instance().size(),
+    "registers every algorithm",
+)
+measure("WorkflowManager().initialize()", init_workflow_manager, "explicit warm-up some scripts still call")
+
+# 3. Per-request cost once warm: the numbers behind the debounce and the upstream timeout.
+syntax_warm = measure("syntax pass (warm)", latency_over_corpus, "same corpus after warm-up")
+
+jedi_result = jedi_probe()
+fork_result = fork_cost() if "SPIKE_NO_FORK" not in os.environ else {"skipped": True}
+
+json.dump(
+    {
+        "stages": rows,
+        "syntax_before_mantid": syntax_before,
+        "syntax_warm": syntax_warm,
+        "jedi": jedi_result,
+        "fork": fork_result,
+        "peak_rss_mb": round(resource.getrusage(resource.RUSAGE_SELF).ru_maxrss / 1024.0, 1),
+        "cpu_count": os.cpu_count(),
+        "load_avg": os.getloadavg(),
+    },
+    sys.stdout,
+    indent=2,
+)
+print()
diff --git a/spike/make_corpus.py b/spike/make_corpus.py
new file mode 100644
index 0000000..1482ca0
--- /dev/null
+++ b/spike/make_corpus.py
@@ -0,0 +1,109 @@
+"""Generate `spike/corpus/` — the scripts the benchmark measures against.
+
+Give it one real script (from a FIA API or a runner) and it derives the sizes an editor actually
+sees, because latency measured on one file tells you nothing about the endpoint:
+
+    python spike/make_corpus.py /path/to/MERLIN.py
+
+* `<name>_small.py`   the first screenful — what is on screen while someone is typing
+* `<name>_x2/_x8.py`  the same script repeated, ~2x and ~8x, approaching the 200 KB request cap, so
+                      the scaling of compile()/ast.parse is measured rather than assumed
+* `<name>_broken.py`  one line replaced by `def reduce_run(:` — the syntax-error path is the common
+                      case mid-typing, and it is also the example the plan's verification names
+* `<name>_star.py`    the same script with the framework imported the way most reduction scripts
+                      import it: `from mantid.simpleapi import *` at module level. The original import
+                      site is blanked out, so everything below the one- or two-line header keeps its
+                      line number. This is the form that defeats star-import-unaware analysis, and the
+                      explicit form - the one that makes analysis easy - is not what users type.
+
+The corpus is gitignored: real reduction scripts are facility code and do not belong in here.
+"""
+
+from __future__ import annotations
+
+import ast
+import sys
+from pathlib import Path
+
+BROKEN_MARKER = "def reduce_run(:"
+SMALL_LINES = 60
+SCALES = (2, 8)
+EXPECTED_ARGC = 2
+
+# The modules reduction scripts pull the framework from. Rewriting these to `import *` reproduces the
+# form that defeats star-import-unaware analysis, which is the form being tested for.
+STAR_MODULES = {"mantid.simpleapi", "mantid.api", "mantid.kernel", "mantid.dataobjects"}
+
+
+def with_star_imports(source: str) -> str:
+    """Rewrite explicit framework imports as a module-level `import *`.
+
+    The scripts FIA holds are usually wrapped in `def execute():` by the reduction service, and
+    `import *` is only legal at module level - so the framework import is hoisted to the top and the
+    original site is blanked rather than rewritten in place. Line numbers below the header are
+    unchanged, which keeps every expected position in the tests a fact rather than a guess.
+    """
+    tree = ast.parse(source)
+    lines = source.split("\n")
+    modules: list[str] = []
+
+    for node in ast.walk(tree):
+        if not isinstance(node, ast.ImportFrom) or node.module not in STAR_MODULES:
+            continue
+        if any(alias.name == "*" for alias in node.names):
+            modules.append(node.module)
+            continue
+        modules.append(node.module)
+        span = range(node.lineno - 1, node.end_lineno or node.lineno)
+        positions = list(span)
+        lines[positions[0]] = f"# {node.module} is imported at module level in this variant"
+        for extra in positions[1:]:
+            lines[extra] = ""
+
+    header = "\n".join(f"from {module} import *" for module in dict.fromkeys(modules))
+    return f"{header}\n" + "\n".join(lines) if header else source
+
+
+def build(source_path: Path, output_dir: Path) -> list[Path]:
+    source = source_path.read_text(encoding="utf-8")
+    lines = source.splitlines()
+    stem = source_path.stem
+    written: list[Path] = []
+
+    def write(name: str, text: str) -> None:
+        path = output_dir / f"{name}.py"
+        path.write_text(text, encoding="utf-8")
+        written.append(path)
+
+    write(stem, source)
+    write(f"{stem}_small", "\n".join(lines[:SMALL_LINES]) + "\n")
+    for scale in SCALES:
+        write(f"{stem}_x{scale}", "\n\n".join([source] * scale))
+
+    # Put the damage somewhere in the middle: a syntax error on line 1 is found faster than one at the
+    # end, and typing produces both.
+    broken = list(lines)
+    broken[len(broken) // 2] = BROKEN_MARKER
+    write(f"{stem}_broken", "\n".join(broken) + "\n")
+
+    star = with_star_imports(source)
+    write(f"{stem}_star", star)
+    return written
+
+
+def main(argv: list[str]) -> int:
+    if len(argv) != EXPECTED_ARGC:
+        print(__doc__)
+        return 2
+
+    source_path = Path(argv[1]).expanduser().resolve()
+    output_dir = Path(__file__).resolve().parent / "corpus"
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    for path in build(source_path, output_dir):
+        print(f"{path.relative_to(output_dir)}: {path.stat().st_size:>7} bytes")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv))
diff --git a/test/conftest.py b/test/conftest.py
new file mode 100644
index 0000000..5d2e601
--- /dev/null
+++ b/test/conftest.py
@@ -0,0 +1,81 @@
+"""Shared fixtures.
+
+Mantid is not installed on a dev machine or in CI's plain Python job, so the framework load is
+replaced before the app starts in every test that needs one. What is under test is the service, not
+the import of a 2 GB framework.
+"""
+
+from __future__ import annotations
+
+import os
+import time
+from collections.abc import Iterator
+
+import pytest
+from fastapi.testclient import TestClient
+
+from script_lsp import warmup as warmup_module
+from script_lsp.app import app
+from script_lsp.preamble import Preamble
+from script_lsp.warmup import Framework
+
+# One analysis worker per test app rather than one per core. Correctness across the process boundary is
+# the same either way, and each child pays an import cost that would otherwise put seconds on every test
+# that starts an app. Pool sizing has its own tests in test_pool.py. Also set for CI, where the number of
+# cores belongs to the runner rather than the test.
+os.environ.setdefault("ANALYSIS_WORKERS", "1")
+
+WARM_TIMEOUT_SECONDS = 5.0
+
+# What the stub framework "exposes". Scripts in tests are written against these: the real service binds
+# roughly 1,800 names from the live framework, and the point of the stub is that a test states which
+# names exist rather than depending on a 2 GB package being installed.
+STUB_FRAMEWORK_NAMES = ("Load", "CreateSampleWorkspace", "AnalysisDataService", "MergeMD", "mtd", "np")
+
+
+@pytest.fixture
+def stub_framework() -> Framework:
+    """A `Framework` as `load_framework` would return it, with no Mantid involved."""
+    return Framework(detail="3 algorithms registered", preamble=Preamble.from_names(STUB_FRAMEWORK_NAMES))
+
+
+def _poll_until_ready(client: TestClient, timeout: float = WARM_TIMEOUT_SECONDS) -> str:
+    """Wait for the warm-up thread to finish, returning the last readiness detail."""
+    deadline = time.monotonic() + timeout
+    detail = ""
+    while time.monotonic() < deadline:
+        response = client.get("/ready")
+        detail = str(response.json().get("detail", ""))
+        if response.status_code == 200:
+            return detail
+        time.sleep(0.02)
+    return detail
+
+
+@pytest.fixture
+def warm_client(monkeypatch: pytest.MonkeyPatch, stub_framework: Framework) -> Iterator[TestClient]:
+    """A started app whose warm-up succeeded.
+
+    The assertion after polling is deliberate: a fixture that quietly yields a cold client turns every
+    downstream test into a confusing 503 failure.
+    """
+    monkeypatch.setattr(warmup_module, "load_framework", lambda: stub_framework)
+
+    with TestClient(app) as client:
+        detail = _poll_until_ready(client)
+        assert client.get("/ready").status_code == 200, f"warm-up never finished: {detail}"
+        yield client
+
+
+@pytest.fixture
+def cold_client(monkeypatch: pytest.MonkeyPatch) -> Iterator[TestClient]:
+    """A started app whose warm-up is still failing, i.e. what a pod looks like before it is ready."""
+    monkeypatch.setattr(warmup_module, "load_framework", _fail)
+
+    with TestClient(app) as client:
+        yield client
+
+
+def _fail() -> str:
+    msg = "mantid is not installed"
+    raise RuntimeError(msg)
diff --git a/test/test_analyse.py b/test/test_analyse.py
new file mode 100644
index 0000000..cd8071a
--- /dev/null
+++ b/test/test_analyse.py
@@ -0,0 +1,116 @@
+"""`POST /analyse` over HTTP, including the parts only visible at the boundary.
+
+Unit tests prove the analysis is right; these prove the service hands it over correctly - field names,
+status codes, and a position that has survived JSON, a proxy and a Unicode string without moving.
+"""
+
+from __future__ import annotations
+
+from fastapi.testclient import TestClient
+
+from script_lsp.models import MAX_SCRIPT_BYTES
+
+CLEAN = 'from mantid.simpleapi import *\n\ndef reduce_run(runno):\n    return Load(Filename=f"ISIS_{runno}.nxs")\n'
+BROKEN = "def reduce_run(runno)\n    return runno\n"
+
+
+def analyse(client: TestClient, content: str, content_hash: str = "sha256:abc") -> dict:
+    response = client.post("/analyse", json={"content": content, "content_hash": content_hash})
+    assert response.status_code == 200, response.text
+    return response.json()
+
+
+def test_a_clean_script_comes_back_clean(warm_client: TestClient) -> None:
+    body = analyse(warm_client, CLEAN)
+
+    assert body["parses"] is True
+    assert body["diagnostics"] == []
+    assert body["truncated"] is False
+
+
+def test_the_hash_is_echoed_so_a_stale_reply_can_be_discarded(warm_client: TestClient) -> None:
+    """The caller's identifier for the script version is the only way to spot an out-of-order reply."""
+    assert analyse(warm_client, BROKEN, "sha256:deadbeef")["content_hash"] == "sha256:deadbeef"
+
+
+def test_the_verdict_and_a_position_survive_the_wire(warm_client: TestClient) -> None:
+    body = analyse(warm_client, BROKEN)
+
+    assert body["parses"] is False
+    assert body["diagnostics"][0]["source"] == "compile"
+    assert body["diagnostics"][0]["start_line"] == 1
+    assert body["diagnostics"][0]["start_column"] == 22
+
+
+def test_a_non_ascii_line_arrives_at_the_same_column_it_left_in(warm_client: TestClient) -> None:
+    """The whole point of converting server-side: the editor must draw this without arithmetic.
+
+    `class` starts after 19 UTF-16 code units - 10 for `comment = `, a quote, two emoji counting as two
+    units each, a quote, and ` + ` - so column 20, and five columns later at 25. Character counting
+    would have said 18 and 23.
+    """
+    body = analyse(warm_client, 'comment = "\U0001f600\U0001f600" + class\n')
+
+    diagnostic = body["diagnostics"][0]
+    assert (diagnostic["start_column"], diagnostic["end_column"]) == (20, 25)
+
+
+def test_the_response_uses_the_field_names_the_frontend_declares(warm_client: TestClient) -> None:
+    """FIA-API forwards this body unchanged, so these keys are the frontend's interface."""
+    body = analyse(warm_client, BROKEN)
+
+    assert set(body) == {"content_hash", "parses", "diagnostics", "truncated"}
+    assert set(body["diagnostics"][0]) == {
+        "message",
+        "severity",
+        "source",
+        "start_line",
+        "start_column",
+        "end_line",
+        "end_column",
+    }
+
+
+def test_an_oversized_script_is_refused_before_anything_parses_it(warm_client: TestClient) -> None:
+    """The cap exists so one user cannot buy CPU with a paste; rejection is 422, not a slow 200."""
+    response = warm_client.post(
+        "/analyse",
+        json={"content": "x = 1\n" * (MAX_SCRIPT_BYTES // 6 + 1), "content_hash": "sha256:big"},
+    )
+
+    assert response.status_code == 422
+    assert "over the" in response.text
+
+
+def test_a_misspelled_algorithm_is_reported_without_claiming_the_script_is_broken(warm_client: TestClient) -> None:
+    """The two passes in one response: it parses, and one name is not in the framework."""
+    body = analyse(warm_client, "from mantid.simpleapi import *\n\nws = Lod(Filename='x.nxs')\n")
+
+    assert body["parses"] is True
+    assert [(item["source"], item["severity"]) for item in body["diagnostics"]] == [("pyflakes", "warning")]
+    assert body["diagnostics"][0]["message"] == "undefined name 'Lod'"
+    assert body["diagnostics"][0]["start_line"] == 3
+    assert body["diagnostics"][0]["start_column"] == 6
+
+
+def test_no_warnings_are_offered_for_code_that_does_not_parse(warm_client: TestClient) -> None:
+    """Half-typed syntax produces an undefined name for every name in the file; one true error is enough."""
+    body = analyse(warm_client, "def reduce_run(runno:\n    return nowhere_to_be_found(\n")
+
+    assert body["parses"] is False
+    assert {item["source"] for item in body["diagnostics"]} == {"compile"}
+
+
+def test_a_request_without_a_hash_is_refused(warm_client: TestClient) -> None:
+    """No hash means the caller cannot tell a stale reply from a current one, so it is not accepted."""
+    assert warm_client.post("/analyse", json={"content": CLEAN}).status_code == 422
+
+
+def test_analysis_is_refused_until_the_framework_is_warm(cold_client: TestClient) -> None:
+    """A 200 here claims the script is clean; a twenty-second-old pod is not entitled to make it."""
+    response = cold_client.post("/analyse", json={"content": CLEAN, "content_hash": "sha256:abc"})
+
+    assert response.status_code == 503
+    detail = response.json()["detail"]
+    assert detail["reason"] == "warming_up"
+    assert "mantid is not installed" in detail["detail"]
diff --git a/test/test_app.py b/test/test_app.py
new file mode 100644
index 0000000..4dedf59
--- /dev/null
+++ b/test/test_app.py
@@ -0,0 +1,31 @@
+"""The app object's own surface: what it reports about itself.
+
+Small enough to state once and pin: the version in the OpenAPI document is the version that was built,
+and a checkout with nothing installed still starts rather than failing on import.
+"""
+
+from __future__ import annotations
+
+import importlib.metadata
+
+import pytest
+
+from script_lsp import app as app_module
+
+
+def test_the_version_comes_from_the_package_metadata_not_a_second_literal() -> None:
+    """Two places to remember is one too many, and the drift is invisible until a release is wrong."""
+    assert importlib.metadata.version(app_module.SERVICE_NAME) == app_module.SERVICE_VERSION
+
+
+def test_an_uninstalled_source_tree_reports_that_instead_of_failing_to_import(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Someone's first clone has the repo and no installed package; that must still boot."""
+
+    def not_installed(_name: str) -> str:
+        raise importlib.metadata.PackageNotFoundError(app_module.SERVICE_NAME)
+
+    monkeypatch.setattr(app_module.metadata, "version", not_installed)
+
+    assert app_module.service_version() == "0.0.0+unknown"
diff --git a/test/test_health.py b/test/test_health.py
new file mode 100644
index 0000000..04cc901
--- /dev/null
+++ b/test/test_health.py
@@ -0,0 +1,83 @@
+"""What the kubelet's probes see.
+
+Mantid is not installed on a dev machine or in CI's plain Python job, so `load_framework` is replaced in
+every test: these tests are about the gate, not about Mantid. The replacement is the shared
+`stub_framework` fixture, so the object a warm framework returns is the same shape everywhere.
+"""
+
+from __future__ import annotations
+
+import time
+from collections.abc import Callable
+
+import pytest
+from fastapi.testclient import TestClient
+
+from script_lsp import warmup as warmup_module
+from script_lsp.app import app
+from script_lsp.warmup import Framework
+
+
+def _wait_until(client: TestClient, predicate: Callable[[dict], bool], timeout: float = 5.0) -> dict:
+    """Poll readiness until `predicate` holds, then return the last body seen."""
+    deadline = time.monotonic() + timeout
+    body: dict = {}
+    while time.monotonic() < deadline:
+        response = client.get("/ready")
+        body = {**response.json(), "status_code": response.status_code}
+        if predicate(body):
+            return body
+        time.sleep(0.02)
+    return body
+
+
+def _explode() -> str:
+    msg = "mantid is not installed"
+    raise RuntimeError(msg)
+
+
+def test_liveness_is_up_before_the_framework_is(monkeypatch: pytest.MonkeyPatch) -> None:
+    """The rule that keeps a slow warm-up from becoming a crash loop."""
+    monkeypatch.setattr(warmup_module, "load_framework", _explode)
+
+    with TestClient(app) as client:
+        assert client.get("/healthz").status_code == 200
+
+
+def test_the_probe_paths_are_the_names_every_other_fia_deployment_probes(monkeypatch: pytest.MonkeyPatch) -> None:
+    """Naming is not a detail: the probe definitions in `../gitops` are shared across services.
+
+    Every FIA component answers `/healthz` for liveness and `/ready` for readiness
+    (`../FIA-API/fia_api/routers/health.py`), so this pins the paths rather than leaving a rename to be
+    discovered by a 503 in staging.
+    """
+    monkeypatch.setattr(warmup_module, "load_framework", _explode)
+
+    with TestClient(app) as client:
+        assert client.get("/healthz").status_code == 200
+        assert client.get("/ready").status_code == 503
+        assert client.get("/health/live").status_code == 404
+        assert client.get("/health/ready").status_code == 404
+
+
+def test_readiness_goes_green_once_the_framework_is_warm(
+    monkeypatch: pytest.MonkeyPatch, stub_framework: Framework
+) -> None:
+    monkeypatch.setattr(warmup_module, "load_framework", lambda: stub_framework)
+
+    with TestClient(app) as client:
+        body = _wait_until(client, lambda payload: payload["status_code"] == 200)
+
+    assert body["status_code"] == 200, body
+    assert body["detail"] == "3 algorithms registered"
+    assert body["warmup_seconds"] is not None
+
+
+def test_readiness_reports_a_failed_warmup_instead_of_hanging_red(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr(warmup_module, "load_framework", _explode)
+
+    with TestClient(app) as client:
+        body = _wait_until(client, lambda payload: "RuntimeError" in payload["detail"])
+
+    assert body["status_code"] == 503, body
+    assert "mantid is not installed" in body["detail"]
diff --git a/test/test_lint.py b/test/test_lint.py
new file mode 100644
index 0000000..4499856
--- /dev/null
+++ b/test/test_lint.py
@@ -0,0 +1,181 @@
+"""The lint pass: one message type, in the user's coordinates.
+
+These tests use a preamble built from a handful of names rather than the framework's ~1,800, which is
+the point: the test states what the framework provides, and everything else follows.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from script_lsp import lint as lint_module
+from script_lsp.lint import lint_diagnostics
+from script_lsp.positions import utf16_length
+from script_lsp.preamble import Preamble
+
+# The framework, as far as these tests are concerned.
+PREAMBLE = Preamble.from_names(["Load", "MergeMD", "mtd", "AnalysisDataService", "np"])
+
+STAR_SCRIPT = """\
+from mantid.simpleapi import *
+
+def reduce_run(runno):
+    ws = Load(Filename=f"ISIS_{runno}.nxs")
+    mtd.addOrReplace("reduced", ws)
+    return MergeMD(InputWorkspaces=[ws])
+"""
+
+
+FACILITY_SCRIPT = """\
+from mantid.simpleapi import *
+from isis_powder.routines.common import *
+
+def reduce_run(runno):
+    grouping = load_grouping_file(runno)
+    ws = Load(Filename=f"ISIS_{runno}.nxs")
+    return grouping
+"""
+
+
+def test_a_script_star_importing_facility_code_is_not_accused_of_anything() -> None:
+    """`isis_powder` is facility code, and this service deliberately does not install it.
+
+    Its helper names cannot be enumerated here, so they cannot be claimed undefined. Rewriting that star
+    import - which is what an earlier version of this code did - reported `undefined name
+    'load_grouping_file'` on a script that runs correctly, and a false positive costs the credibility of
+    every real warning next to it.
+    """
+    assert lint_diagnostics(FACILITY_SCRIPT, PREAMBLE) == []
+
+
+def test_that_silence_covers_a_typo_too_and_that_is_a_decision_not_an_oversight() -> None:
+    """The cost of the rule above, pinned so nobody 'fixes' it by rewriting the import again.
+
+    pyflakes hedges every unresolved name once a scope holds a star import it cannot see through, so a
+    misspelled algorithm in such a script goes unreported as well. Deliberate: this service reports only
+    what it can know, and a script that uses unmodellable star imports is one it cannot know about.
+    """
+    assert lint_diagnostics(FACILITY_SCRIPT.replace("Load(", "Loa(", 1), PREAMBLE) == []
+
+
+def test_a_script_using_only_framework_names_is_silent() -> None:
+    """The whole corpus assertion in miniature: `import *` must not produce a wall of warnings.
+
+    Measured on the real MERLIN script in that form, plain pyflakes reports fourteen "may be undefined,
+    or defined from star imports" on working code.
+    """
+    assert lint_diagnostics(STAR_SCRIPT, PREAMBLE) == []
+
+
+def test_a_misspelled_algorithm_is_reported_once_where_it_was_typed() -> None:
+    """`BinMD` as `BinMQ`: the mistake this exists to catch, and the one naive pyflakes hides."""
+    source = STAR_SCRIPT.replace("MergeMD(", "MergeMDTypo(", 1)
+
+    diagnostics = lint_diagnostics(source, PREAMBLE)
+
+    assert len(diagnostics) == 1
+    diagnostic = diagnostics[0]
+    assert diagnostic.message == "undefined name 'MergeMDTypo'"
+    assert diagnostic.severity == "warning"
+    assert diagnostic.source == "pyflakes"
+    # Line 6 of the script, not line 6 + len(preamble): the offset is undone before anyone sees it.
+    assert diagnostic.start_line == 6
+    assert diagnostic.start_column == 12
+    assert diagnostic.end_column == 12 + len("MergeMDTypo")
+
+
+def test_warnings_are_advisory_because_static_analysis_cannot_see_the_runner() -> None:
+    """The runner injects names around a script, so "this will fail" is not ours to claim.
+
+    `compile()` says that, and says it as an error; a name this pass cannot resolve is a strong hint,
+    not a verdict.
+    """
+    source = "result = something_the_runner_provides()\n"
+
+    diagnostics = lint_diagnostics(source, PREAMBLE)
+
+    assert [item.severity for item in diagnostics] == ["warning"]
+
+
+def test_style_opinions_are_not_reported() -> None:
+    """Measured on real scripts: 2-3 unused imports, an unused variable, and 35 redefinitions at scale."""
+    source = """\
+from mantid.simpleapi import Load
+import json
+unused_workspace = Load(Filename="x.nxs")
+unused_workspace = Load(Filename="y.nxs")
+"""
+
+    assert lint_diagnostics(source, PREAMBLE) == []
+
+
+def test_positions_count_utf16_units_like_the_editor_does() -> None:
+    """A misspelling after an emoji, through the lint path - all three column conventions differ here.
+
+    The name starts after a 14-character prefix containing one astral character. That prefix is 17 UTF-8
+    bytes (what pyflakes reports) and 15 UTF-16 units (what Monaco wants), so the answer is column 16:
+    passing the byte offset through would say 18, and counting characters would say 15.
+    """
+    source = 'label = "\U0001f600" + missing_name\n'
+
+    diagnostics = lint_diagnostics(source, PREAMBLE)
+
+    assert len(diagnostics) == 1
+    assert diagnostics[0].message == "undefined name 'missing_name'"
+    assert diagnostics[0].start_column == 1 + utf16_length('label = "\U0001f600" + ') == 16
+
+
+def test_a_script_that_does_not_parse_gets_no_warnings() -> None:
+    """Half-typed code produces an undefined name for every name in it; the syntax pass covers that."""
+    source = STAR_SCRIPT.replace("def reduce_run(runno):", "def reduce_run(runno:") + "undefined_here\n"
+
+    assert lint_diagnostics(source, PREAMBLE) == []
+
+
+def test_builtins_and_the_scripts_own_names_are_never_reported() -> None:
+    source = """\
+from mantid.simpleapi import *
+
+def helper(values):
+    total = sum(len(value) for value in values)
+    return [str(total), dict(), list(values)]
+
+def reduce_run(runno):
+    return helper([str(runno), Load(Filename="x")])
+"""
+
+    assert lint_diagnostics(source, PREAMBLE) == []
+
+
+def test_the_message_does_not_carry_pyflakes_own_prefix() -> None:
+    """`str(message)` is "script.py:12:5: undefined name 'x'" - a position quoted inside a position."""
+    diagnostics = lint_diagnostics("x = nowhere()\n", PREAMBLE)
+
+    assert diagnostics[0].message == "undefined name 'nowhere'"
+
+
+def test_a_pyflakes_crash_costs_the_lint_and_not_the_request(monkeypatch: pytest.MonkeyPatch) -> None:
+    """A third-party checker falling over must not cost the user their syntax diagnostics.
+
+    `lint_diagnostics` is called after the syntax pass and its result is appended to it, so an exception
+    escaping here becomes a 500 for a script the service was perfectly able to talk about.
+    """
+
+    def explode(*args: object, **kwargs: object) -> None:
+        msg = "pyflakes fell over"
+        raise RuntimeError(msg)
+
+    monkeypatch.setattr(lint_module, "Checker", explode)
+
+    assert lint_diagnostics(STAR_SCRIPT, PREAMBLE) == []
+
+
+def test_a_report_about_the_preamble_itself_is_never_pointed_at_the_script(monkeypatch: pytest.MonkeyPatch) -> None:
+    """The one guard between a mapped line number and a squiggle under the wrong code.
+
+    A binding colliding with something in the script makes pyflakes report inside the preamble, where the
+    line does not exist in the user's file. Emitting the number anyway would underline arbitrary code.
+    """
+    monkeypatch.setattr(Preamble, "to_user_line", lambda self, analysed_line: None)
+
+    assert lint_diagnostics("x = Lod()\n", PREAMBLE) == []
diff --git a/test/test_models.py b/test/test_models.py
new file mode 100644
index 0000000..386671b
--- /dev/null
+++ b/test/test_models.py
@@ -0,0 +1,168 @@
+"""Tests for the wire contract.
+
+The point of these is not coverage of pydantic; it is that the guarantees the frontend is written
+against - 1-based UTF-16 positions, a non-empty message, ordering, the cap, snake_case keys - hold,
+because every one of them is something a user would otherwise experience as a squiggle in the wrong
+place or a missing explanation.
+"""
+
+from __future__ import annotations
+
+import pytest
+from pydantic import ValidationError
+
+from script_lsp.models import (
+    DEFAULT_DIAGNOSTIC_LIMIT,
+    DEFAULT_MAX_SCRIPT_BYTES,
+    DIAGNOSTIC_LIMIT_ENV,
+    MAX_SCRIPT_BYTES,
+    MAX_SCRIPT_BYTES_ENV,
+    AnalyseRequest,
+    AnalyseResponse,
+    Diagnostic,
+    _positive_int,
+)
+
+
+def diagnostic(**overrides: object) -> Diagnostic:
+    """A plausible diagnostic, with fields overridable per test."""
+    fields: dict[str, object] = {
+        "message": "expected ':'",
+        "severity": "error",
+        "source": "compile",
+        "start_line": 12,
+        "start_column": 8,
+        "end_line": 12,
+        "end_column": 9,
+    }
+    fields.update(overrides)
+    return Diagnostic(**fields)
+
+
+def test_positions_are_one_based_because_monaco_says_so() -> None:
+    """Python reports 0-based columns; a diagnostic that leaks that through sits off by one."""
+    with pytest.raises(ValidationError, match="start_column"):
+        diagnostic(start_column=0)
+    with pytest.raises(ValidationError, match="start_line"):
+        diagnostic(start_line=0)
+
+
+def test_a_range_cannot_point_backwards() -> None:
+    with pytest.raises(ValidationError, match="before start"):
+        diagnostic(start_line=3, start_column=5, end_line=3, end_column=2)
+
+
+def test_a_diagnostic_without_an_explanation_is_rejected() -> None:
+    """jedi's text is often only 'invalid syntax', but *nothing* is worse than that."""
+    with pytest.raises(ValidationError, match="string"):
+        diagnostic(message="")
+
+
+def test_the_size_cap_is_bytes_not_characters() -> None:
+    """A 200_000-character script of 4-byte emoji is far over 200 KB, and must not be parsed."""
+    over_cap = "\U0001f600" * (MAX_SCRIPT_BYTES // 4 + 1)
+
+    with pytest.raises(ValidationError, match="over the"):
+        AnalyseRequest(content=over_cap, content_hash="abc123")
+
+    # The same count of characters under the cap in bytes is accepted: the check is size, not length.
+    AnalyseRequest(content="\U0001f600" * 10, content_hash="abc123")
+
+
+def test_a_missing_hash_is_an_error_not_an_empty_string() -> None:
+    """Without a hash the caller cannot tell a stale reply from a current one."""
+    with pytest.raises(ValidationError, match="content_hash"):
+        AnalyseRequest(content="print(1)", content_hash="")
+
+
+def test_build_orders_diagnostics_by_position() -> None:
+    """The frontend maps these straight onto markers; unsorted input would flicker between saves."""
+    response = AnalyseResponse.build(
+        content_hash="h",
+        parses=True,
+        diagnostics=[
+            diagnostic(start_line=20, start_column=1, end_line=20, end_column=2),
+            diagnostic(start_line=3, start_column=10, end_line=3, end_column=11),
+            diagnostic(start_line=3, start_column=2, end_line=3, end_column=3),
+        ],
+    )
+
+    assert [(item.start_line, item.start_column) for item in response.diagnostics] == [(3, 2), (3, 10), (20, 1)]
+    assert response.truncated is False
+
+
+def test_build_applies_the_cap_and_says_so() -> None:
+    """A bad dedent yields one error per line; the response must not grow with the file."""
+    many = [diagnostic(start_line=line, end_line=line) for line in range(1, 251)]
+
+    response = AnalyseResponse.build(content_hash="h", parses=False, diagnostics=many, limit=100)
+
+    assert len(response.diagnostics) == 100
+    assert response.truncated is True
+    assert response.diagnostics[-1].start_line == 100
+
+
+def test_json_field_names_are_snake_case() -> None:
+    """The frontend's TS types mirror these names exactly; camelCase conversion happens nowhere."""
+    payload = AnalyseResponse.build(content_hash="h", parses=False, diagnostics=[diagnostic()]).model_dump()
+
+    assert set(payload) == {"content_hash", "parses", "diagnostics", "truncated"}
+    assert set(payload["diagnostics"][0]) == {
+        "message",
+        "severity",
+        "source",
+        "start_line",
+        "start_column",
+        "end_line",
+        "end_column",
+    }
+
+
+def test_parses_is_separate_from_the_diagnostic_count() -> None:
+    """'Will the runner reject this' is not derivable from error counts, so the contract keeps it."""
+    response = AnalyseResponse.build(content_hash="h", parses=False, diagnostics=[])
+
+    assert response.model_dump() == {"content_hash": "h", "parses": False, "diagnostics": [], "truncated": False}
+
+
+def test_info_is_not_a_severity_the_contract_offers() -> None:
+    """Three severities would mean a third squiggle colour, and nothing here can justify one.
+
+    `error` means the runner will not take the script and `warning` means a name is missing; an `info`
+    would render as a grey underline for something the user cannot act on, in a service whose whole value
+    depends on being believed.
+    """
+    with pytest.raises(ValidationError):
+        diagnostic(severity="info")
+
+
+@pytest.mark.parametrize(
+    ("raw", "expected"),
+    [
+        (None, DEFAULT_MAX_SCRIPT_BYTES),  # unset: the shipped default
+        ("100000", 100000),
+        ("", DEFAULT_MAX_SCRIPT_BYTES),  # set-but-empty is what an unset env var looks like from a manifest
+        ("two hundred thousand", DEFAULT_MAX_SCRIPT_BYTES),
+        ("0", DEFAULT_MAX_SCRIPT_BYTES),  # a cap of zero would reject every script, including an empty one
+        ("-1", DEFAULT_MAX_SCRIPT_BYTES),
+    ],
+)
+def test_a_setting_falls_back_to_the_shipped_default_rather_than_to_a_broken_pod(
+    raw: str | None, expected: int
+) -> None:
+    """A typo in a Deployment must not produce a service that refuses everything.
+
+    The cap has to be tunable - a pod with less memory should be able to lower it - but honouring a bad
+    value fails worse than ignoring it.
+    """
+    environ = {} if raw is None else {MAX_SCRIPT_BYTES_ENV: raw}
+
+    assert _positive_int(MAX_SCRIPT_BYTES_ENV, DEFAULT_MAX_SCRIPT_BYTES, environ) == expected
+
+
+def test_the_diagnostic_cap_is_a_setting_with_the_same_fallback() -> None:
+    """Both limits come from the environment, so both need the same protection against nonsense."""
+    assert _positive_int(DIAGNOSTIC_LIMIT_ENV, DEFAULT_DIAGNOSTIC_LIMIT, {DIAGNOSTIC_LIMIT_ENV: "25"}) == 25
+    assert _positive_int(DIAGNOSTIC_LIMIT_ENV, DEFAULT_DIAGNOSTIC_LIMIT, {DIAGNOSTIC_LIMIT_ENV: "lots"}) == (
+        DEFAULT_DIAGNOSTIC_LIMIT
+    )
diff --git a/test/test_pool.py b/test/test_pool.py
new file mode 100644
index 0000000..3e8abda
--- /dev/null
+++ b/test/test_pool.py
@@ -0,0 +1,260 @@
+"""The analysis pool: how big it should be, and whether work survives leaving the process.
+
+The reason this service has a pool at all is measured - 24 concurrent analyses on
+Starlette's threadpool cost 1,534 ms each, worse than running them one at a time - so these tests cover
+both the sizing rule and the thing that could silently break when work moves to another process: the
+positions in the reply.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import time
+from pathlib import Path
+
+import pytest
+
+from script_lsp import pool as pool_module
+from script_lsp.pool import (
+    _divide,
+    analyse_in_pool,
+    analyse_script,
+    bind_preamble,
+    cpu_quota,
+    create_pool,
+    warm,
+    worker_count,
+)
+from script_lsp.preamble import Preamble
+
+PREAMBLE = Preamble.from_names(["Load", "MergeMD", "mtd"])
+
+
+def test_one_worker_per_allowed_core() -> None:
+    """More workers than the pod's CPU quota buys throttling, not throughput.
+
+    CFS hands out quota in ~100 ms periods; two workers against a 1 CPU limit both run, then the whole
+    group stalls until the period rolls over, which turns a throughput problem into a latency spike.
+    """
+    assert worker_count(environ={}, quota=1.0) == 1
+    assert worker_count(environ={}, quota=2.0) == 2
+    assert worker_count(environ={}, quota=3.6) == 4
+    assert worker_count(environ={}, quota=0.25) == 1  # never zero: a pool with no workers never replies
+
+
+def test_with_no_quota_to_read_the_pool_stays_small_rather_than_matching_the_host() -> None:
+    """`os.process_cpu_count()` counts the host's cores, which on a shared node is not an invitation.
+
+    A laptop, or a pod on a node that reports no limit, gets a bounded pool: enough to overlap a burst of
+    edits, few enough that one pod cannot take the node's cores from everything else on it.
+    """
+    assert 1 <= worker_count(environ={}, quota=None) <= 4
+
+
+def test_an_explicit_count_wins_over_the_quota() -> None:
+    """The deployment sometimes knows better than the cgroup - and the escape hatch has to work."""
+    assert worker_count(environ={"ANALYSIS_WORKERS": "6"}, quota=1.0) == 6
+
+
+@pytest.mark.parametrize("value", ["", "nonsense", "0", "-3"])
+def test_a_bad_override_falls_back_to_the_quota_rather_than_to_zero(value: str) -> None:
+    """A typo in a manifest must not produce a service that answers nothing."""
+    assert worker_count(environ={"ANALYSIS_WORKERS": value}, quota=4.0) == 4
+
+
+def test_quota_reading_tolerates_a_missing_cgroup(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    """Containers, CI runners and laptops all differ here; none of them is an error."""
+    monkeypatch.setattr("script_lsp.pool.CGROUP_V2_QUOTA", str(tmp_path / "absent"))
+    monkeypatch.setattr("script_lsp.pool.CGROUP_V1_QUOTA", str(tmp_path / "absent"))
+    monkeypatch.setattr("script_lsp.pool.CGROUP_V1_PERIOD", str(tmp_path / "absent"))
+
+    assert cpu_quota() is None
+
+
+def test_a_v2_quota_is_read_as_cores(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    """`cpu.max` of "50000 100000" means half a core."""
+    quota_file = tmp_path / "cpu.max"
+    quota_file.write_text("50000 100000\n", encoding="utf-8")
+    monkeypatch.setattr("script_lsp.pool.CGROUP_V2_QUOTA", str(quota_file))
+
+    assert cpu_quota() == pytest.approx(0.5)
+
+
+def test_a_v2_quota_of_max_means_unlimited(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    quota_file = tmp_path / "cpu.max"
+    quota_file.write_text("max 100000\n", encoding="utf-8")
+    monkeypatch.setattr("script_lsp.pool.CGROUP_V2_QUOTA", str(quota_file))
+    monkeypatch.setattr("script_lsp.pool.CGROUP_V1_QUOTA", str(tmp_path / "absent"))
+
+    assert cpu_quota() is None
+
+
+def test_a_malformed_quota_file_is_treated_as_unlimited(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    """Nodes have been observed to contain surprises here; the fallback must still give a working pool."""
+    quota_file = tmp_path / "cpu.max"
+    quota_file.write_text("garbage\n", encoding="utf-8")
+    monkeypatch.setattr("script_lsp.pool.CGROUP_V2_QUOTA", str(quota_file))
+
+    assert cpu_quota() is None
+
+
+def test_a_v1_quota_of_minus_one_means_unlimited(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    """cgroup v1 spells "no limit" as a quota of -1, which is not a pool of negative size."""
+    (tmp_path / "quota").write_text("-1\n", encoding="utf-8")
+    (tmp_path / "period").write_text("100000\n", encoding="utf-8")
+    monkeypatch.setattr("script_lsp.pool.CGROUP_V2_QUOTA", str(tmp_path / "absent"))
+    monkeypatch.setattr("script_lsp.pool.CGROUP_V1_QUOTA", str(tmp_path / "quota"))
+    monkeypatch.setattr("script_lsp.pool.CGROUP_V1_PERIOD", str(tmp_path / "period"))
+
+    assert cpu_quota() is None
+
+
+def test_positions_survive_the_trip_into_a_worker_process() -> None:
+    """The point of the change, and the way it could go wrong quietly.
+
+    The preamble is handed to the child by an initializer and the offsets are undone there; if the child
+    were left with no bindings, every framework name would come back "undefined" - plausible output,
+    wrong story. So: a script whose one unbound name is deliberate must come back as exactly that one,
+    at the script's own line and column, from a different process.
+    """
+    script = "from mantid.simpleapi import *\n\nws = Load(Filename='x.nxs')\nws = Lod(Filename='y.nxs')\n"
+    pool = create_pool(PREAMBLE)
+
+    try:
+        parses, diagnostics = asyncio.run(analyse_in_pool(pool, script))
+    finally:
+        pool.shutdown(wait=True)
+
+    assert parses is True
+    assert [(item.message, item.start_line, item.start_column) for item in diagnostics] == [
+        ("undefined name 'Lod'", 4, 6)
+    ]
+
+
+def test_a_worker_reports_a_script_that_does_not_parse_without_linting_it() -> None:
+    """Same rule as in-process: half-typed code yields one true error, not an undefined name per name."""
+    pool = create_pool(PREAMBLE)
+
+    try:
+        parses, diagnostics = asyncio.run(analyse_in_pool(pool, "def reduce_run(runno:\n    return nowhere\n"))
+    finally:
+        pool.shutdown(wait=True)
+
+    assert parses is False
+    assert {item.source for item in diagnostics} == {"compile"}
+
+
+def test_a_shut_down_pool_fails_rather_than_running_the_work_in_process() -> None:
+    """If the pool is gone, analysis is unavailable - not silently moved onto the event loop.
+
+    Running it inline would answer 200 with diagnostics from a process that shares the loop, which is the
+    exact behaviour the pool exists to remove.
+    """
+    pool = create_pool(PREAMBLE)
+    pool.shutdown(wait=True)
+
+    with pytest.raises(RuntimeError):
+        asyncio.run(analyse_in_pool(pool, "x = 1\n"))
+
+
+def test_the_pool_honours_the_configured_worker_count() -> None:
+    """A manifest says `ANALYSIS_WORKERS: 3` and the pool must have three processes, not the host's cores."""
+    os.environ["ANALYSIS_WORKERS"] = "2"
+
+    try:
+        pool = create_pool(PREAMBLE)
+        try:
+            assert pool._max_workers == 2
+        finally:
+            pool.shutdown(wait=True)
+    finally:
+        os.environ.pop("ANALYSIS_WORKERS", None)
+
+
+def test_warming_starts_every_worker_so_the_first_burst_is_not_the_startup_cost() -> None:
+    """A lazily spawned pool pays jedi's import inside a user's request.
+
+    Measured: the first 24-request burst against a cold pool took 670 ms and the same burst afterwards
+    took 211 ms. Readiness should not be reported until that has already happened.
+    """
+    os.environ["ANALYSIS_WORKERS"] = "3"
+    pool = create_pool(PREAMBLE)
+
+    try:
+        assert len(pool._processes) == 0
+        warm(pool)
+        assert len(pool._processes) == 3
+    finally:
+        pool.shutdown(wait=True)
+        os.environ.pop("ANALYSIS_WORKERS", None)
+
+
+def test_creating_a_pool_does_not_add_another_startup_pause() -> None:
+    """Warm-up already pays for Mantid; the pool must not add seconds to the startup probe budget."""
+    started = time.perf_counter()
+    pool = create_pool(PREAMBLE)
+    elapsed = time.perf_counter() - started
+    pool.shutdown(wait=True)
+
+    assert elapsed < 1.0
+
+
+def test_a_worker_without_bound_names_reports_syntax_only() -> None:
+    """The gate that keeps an unwarmed pool from telling users their framework names are undefined.
+
+    Called directly, because in production this runs in a child process where coverage cannot see it - and
+    the branch is the difference between "no lint yet" and "every algorithm is a typo".
+    """
+    parses, diagnostics = analyse_script("x = Load()\n")
+
+    assert (parses, diagnostics) == (True, [])
+
+
+def test_a_worker_with_bound_names_lints_in_whatever_process_it_runs_in(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setattr(pool_module, "_BOUND_PREAMBLE", PREAMBLE)
+
+    parses, diagnostics = analyse_script("x = Load()\ny = Lod()\n")
+
+    assert parses is True
+    assert [(item.message, item.start_line) for item in diagnostics] == [("undefined name 'Lod'", 2)]
+
+
+def test_the_initializer_binds_the_names_it_was_given(monkeypatch: pytest.MonkeyPatch) -> None:
+    """What the pool hands each worker, and the reason workers can start without Mantid."""
+    monkeypatch.setattr(pool_module, "_BOUND_PREAMBLE", None)
+
+    bind_preamble(PREAMBLE)
+
+    assert pool_module._BOUND_PREAMBLE is PREAMBLE
+
+
+def test_a_quota_division_that_cannot_be_done_is_no_quota_at_all() -> None:
+    """Neither a malformed cgroup file nor a zero period should size the pool by accident."""
+    assert _divide("not-a-number", "100000") is None
+    assert _divide("100000", "0") is None
+
+
+def test_a_v1_quota_is_read_as_cores(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    """The older cgroup layout splits the answer across two files."""
+    (tmp_path / "quota").write_text("200000\n", encoding="utf-8")
+    (tmp_path / "period").write_text("100000\n", encoding="utf-8")
+    monkeypatch.setattr("script_lsp.pool.CGROUP_V2_QUOTA", str(tmp_path / "absent"))
+    monkeypatch.setattr("script_lsp.pool.CGROUP_V1_QUOTA", str(tmp_path / "quota"))
+    monkeypatch.setattr("script_lsp.pool.CGROUP_V1_PERIOD", str(tmp_path / "period"))
+
+    assert cpu_quota() == pytest.approx(2.0)
+
+
+def test_a_v1_quota_file_that_is_not_a_number_is_treated_as_unlimited(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    (tmp_path / "quota").write_text("unlimited\n", encoding="utf-8")
+    (tmp_path / "period").write_text("100000\n", encoding="utf-8")
+    monkeypatch.setattr("script_lsp.pool.CGROUP_V2_QUOTA", str(tmp_path / "absent"))
+    monkeypatch.setattr("script_lsp.pool.CGROUP_V1_QUOTA", str(tmp_path / "quota"))
+    monkeypatch.setattr("script_lsp.pool.CGROUP_V1_PERIOD", str(tmp_path / "period"))
+
+    assert cpu_quota() is None
diff --git a/test/test_positions.py b/test/test_positions.py
new file mode 100644
index 0000000..60470bb
--- /dev/null
+++ b/test/test_positions.py
@@ -0,0 +1,139 @@
+"""Position conversion tests.
+
+Every case here is a real failure mode: the units disagreeing, the line split disagreeing, or the
+source not saying where an error ends. A mistake in this module does not raise - it draws the squiggle
+a few characters away from the thing it is about, which is the kind of defect that survives review
+because the diagnostic still looks plausible.
+"""
+
+from __future__ import annotations
+
+from typing import NamedTuple
+
+import pytest
+
+from script_lsp.positions import (
+    column_at,
+    column_at_byte_offset,
+    jedi_error_range,
+    source_lines,
+    syntax_error_range,
+    utf16_length,
+)
+
+
+def compile_error(source: str) -> SyntaxError:
+    """The `SyntaxError` CPython raises for `source`, for feeding to the converter."""
+    with pytest.raises(SyntaxError) as raised:
+        compile(source, "script.py", "exec")
+    return raised.value
+
+
+class FakeJediError(NamedTuple):
+    """Stands in for jedi's `SyntaxError`, whose attributes are the ones named in the Protocol."""
+
+    line: int
+    column: int
+    until_line: int
+    until_column: int
+
+    def get_message(self) -> str:
+        return "fake"
+
+
+def test_emoji_shift_every_column_after_them() -> None:
+    """CPython counts characters, Monaco counts UTF-16 code units; an astral character is two of them.
+
+    Measured, not reasoned: for this line CPython reports offset 12 for `class`, and the range belongs
+    at columns 14 to 19. Passing the number through unchanged gives 12 to 17 - a keyword-shaped
+    squiggle starting two characters early and ending three characters short.
+    """
+    source = 'x = "\U0001f600\U0001f600" + class'
+
+    assert compile_error(source).offset == 12
+    assert syntax_error_range(compile_error(source), source) == (1, 14, 1, 19)
+
+
+def test_basic_multilingual_characters_count_once() -> None:
+    """An accented letter is one UTF-16 unit; treating it like an emoji would overshoot."""
+    assert utf16_length("café \U0001f600") == 7
+    assert column_at("café = ", 6) == 7
+
+
+def test_line_splitting_matches_the_tokenizer() -> None:
+    """`str.splitlines()` also breaks on form feed, vertical tab and U+2028; CPython's tokenizer does not.
+
+    Using it would invent a line break that the compiler does not see, and shift every line number
+    below it - relocating diagnostics into a different part of the script.
+    """
+    source = "import os\x0c\nprint os"
+
+    assert len(source_lines(source)) == 2
+    assert len(source.splitlines()) == 3  # the trap, demonstrated
+    assert syntax_error_range(compile_error(source), source)[0] == 2
+
+
+def test_carriage_returns_are_not_part_of_the_line() -> None:
+    """Windows line endings arrive from the editor; a trailing `\\r` must not be counted as a character."""
+    assert source_lines("def reduce_run()\r\n    pass\r\n") == ["def reduce_run()", "    pass", ""]
+
+
+def test_a_missing_end_position_still_draws_one_character() -> None:
+    """`expected ':'` is reported with no width - the missing character has none - and width is visibility."""
+    source = "def reduce_run(runno)\n"
+    error = SyntaxError("expected ':'", ("script.py", 1, 22, 22))
+
+    assert compile_error(source).offset == 22  # CPython really does report an end equal to the start
+    assert syntax_error_range(error, source) == (1, 22, 1, 23)
+
+
+def test_an_offset_past_the_end_of_its_line_is_clamped_to_the_line() -> None:
+    """A number beyond the text would put the marker outside the editor's line, so it is pulled back."""
+    error = SyntaxError("bad", ("script.py", 4, 40, None))
+
+    assert syntax_error_range(error, "x = 1\ny = 2\nz = 3\n    oops\n") == (4, 9, 4, 10)
+
+
+def test_a_line_number_past_the_end_of_the_source_does_not_raise() -> None:
+    """Trusts the interpreter's numbers, which occasionally point one line beyond a truncated file."""
+    assert syntax_error_range(SyntaxError("eof", ("script.py", 9, 3, None)), "x = 1\n") == (9, 1, 9, 2)
+
+
+def test_pyflakes_columns_are_utf8_bytes_not_characters() -> None:
+    """Measured against pyflakes: `col` comes from `tokenize` over the encoded source.
+
+    The three differ on the same line, which is why this needs its own conversion rather than the one
+    CPython and jedi use: `lábel = nowhere()` reports byte column 9 for a name starting at code point 8,
+    and an astral character is four bytes where Monaco wants two columns.
+    """
+    assert column_at_byte_offset("lábel = nowhere", 9) == 9  # é is two bytes, one character, one column
+    assert column_at_byte_offset('a = "\U0001f600\U0001f600" + nowhere', 17) == 14
+    assert column_at("a = nowhere", 4) == 5  # the code-point conversion, unchanged, for comparison
+
+
+def test_a_byte_offset_into_the_middle_of_a_character_does_not_raise() -> None:
+    """If an analyser ever reports an offset inside a multi-byte character, land on a column anyway."""
+    assert column_at_byte_offset('x = "\U0001f600" + nowhere', 6) == 6  # stops one byte into a 4-byte emoji
+    assert column_at_byte_offset("x = 1", 400) == 6  # past the end, clamped
+
+
+def test_jedi_columns_are_zero_based() -> None:
+    """jedi's 0-based column becomes Monaco's 1-based one; measured against jedi's own output."""
+    source = "import os\x0c\nprint os"
+
+    assert jedi_error_range(FakeJediError(line=2, column=6, until_line=2, until_column=8), source) == (2, 7, 2, 9)
+
+
+def test_a_jedi_range_ending_before_it_starts_is_widened_to_one_character() -> None:
+    """jedi's `until_*` marks where it gave up, which is sometimes where it started."""
+    assert jedi_error_range(FakeJediError(line=3, column=4, until_line=1, until_column=0), "a\nb\ncdef\n") == (
+        3,
+        5,
+        3,
+        6,
+    )
+
+
+def test_columns_are_exclusive_at_the_end() -> None:
+    """Monaco's end column is one past the last character, so a single character spans exactly one."""
+    assert column_at("abc", 1) - column_at("abc", 0) == 1
diff --git a/test/test_preamble.py b/test/test_preamble.py
new file mode 100644
index 0000000..712e875
--- /dev/null
+++ b/test/test_preamble.py
@@ -0,0 +1,167 @@
+"""The preamble: what it binds, and the arithmetic it forces on every reported position.
+
+The offset is the dangerous part. A preamble that adds 90 lines and a mapping that is off by one is a
+warning under the wrong line, which looks exactly like an analyser that works.
+"""
+
+from __future__ import annotations
+
+import types
+
+import pytest
+
+from script_lsp.preamble import Preamble, neutralise_star_imports
+
+
+def test_names_are_bound_as_assignments() -> None:
+    """Assignments, not imports: an import the script does not use becomes an "imported but unused".
+
+    Measured - explicit imports in the preamble produced three spurious warnings on a script that has
+    none, because the framework bindings themselves look unused to pyflakes.
+    """
+    preamble = Preamble.from_names(["b", "a"])
+
+    assert preamble.text == "# framework names, generated from the running framework\na = b = None\n"
+    assert preamble.name_count == 2
+    assert preamble.line_count == 2
+
+
+def test_duplicates_and_junk_are_dropped() -> None:
+    """The list comes from `dir()` of five modules; it must not carry nonsense into the analysis."""
+    preamble = Preamble.from_names(["mtd", "mtd", "not an identifier", "", "Load"])
+
+    assert preamble.name_count == 2
+    assert "mtd = Load" in preamble.text or "Load = mtd" in preamble.text
+
+
+def test_module_names_are_collected_without_builtins() -> None:
+    """Binding `list` or `print` would hide the mistakes users make most often."""
+    module = types.ModuleType("fake_framework")
+    module.Load = object()  # type: ignore[attr-defined]
+    module._private = object()  # type: ignore[attr-defined]
+    module.list = list  # type: ignore[attr-defined]
+
+    preamble = Preamble.from_modules([module])
+
+    assert preamble.name_count == 1
+    assert "Load = None" in preamble.text
+    assert "list" not in preamble.text
+
+
+def test_the_same_names_always_render_identically() -> None:
+    """Sorted output means a warm pod and a restarted one analyse a script identically."""
+    first = Preamble.from_names(["z", "a", "m"])
+    second = Preamble.from_names(["m", "z", "a"])
+
+    assert first.text == second.text
+
+
+@pytest.mark.parametrize("user_line", [1, 2, 57, 58, 500])
+def test_every_reported_line_maps_back_to_the_script_it_came_from(user_line: int) -> None:
+    """The round trip: a script line, its position in the analysed copy, and the journey home.
+
+    The analysed source is built the way the linter builds it - string concatenation, not a join - because
+    that trailing newline is exactly where the offset arithmetic comes from.
+    """
+    preamble = Preamble.from_names([f"name{index}" for index in range(100)])  # more than one line of bindings
+    script = "\n".join(["", "", "x = 1", "y = 2"] * 200)
+    analysed = preamble.text + script
+
+    analysed_line = user_line + preamble.line_count
+
+    assert analysed.split("\n")[analysed_line - 1] == script.split("\n")[user_line - 1]
+    assert preamble.to_user_line(analysed_line) == user_line
+
+
+def test_reports_about_the_preamble_itself_are_dropped() -> None:
+    """A collision inside the bindings has nothing to do with the user's file."""
+    preamble = Preamble.from_names([f"name{index}" for index in range(100)])
+
+    assert preamble.to_user_line(1) is None
+    assert preamble.to_user_line(preamble.line_count) is None
+    assert preamble.to_user_line(preamble.line_count + 1) == 1
+
+
+def test_star_imports_are_neutralised_without_moving_anything() -> None:
+    source = "from mantid.simpleapi import *\n\ndef reduce_run(runno):\n    return Load(Filename=f'{runno}.nxs')\n"
+
+    neutralised = neutralise_star_imports(source)
+
+    assert len(neutralised.split("\n")) == len(source.split("\n"))
+    assert neutralised.split("\n")[0].startswith("# framework import")
+    assert "import *" not in neutralised
+
+
+def test_named_imports_are_left_alone() -> None:
+    """Only star imports blind the linter; rewriting anything else would change what is checked."""
+    source = "from mantid.simpleapi import Load\n\nx = Load()\n"
+
+    assert neutralise_star_imports(source) == source
+
+
+def test_a_star_import_of_code_this_service_does_not_have_is_left_in_place() -> None:
+    """Facility helpers come from `isis_powder`, which is deliberately not installed here.
+
+    Blanking that import tells pyflakes its names are accounted for, and every facility helper the script
+    then uses becomes `undefined name` - a working script reported as broken. Left in, pyflakes hedges
+    instead, and the hedge is a message class the lint pass does not report.
+    """
+    source = "from mantid.simpleapi import *\nfrom isis_powder.routines.common import *\nx = 1\n"
+
+    neutralised = neutralise_star_imports(source)
+
+    assert neutralised.split("\n")[0].startswith("# framework import")
+    assert neutralised.split("\n")[1] == "from isis_powder.routines.common import *"
+    assert len(neutralised.split("\n")) == len(source.split("\n"))
+
+
+def test_the_preamble_records_which_modules_its_names_came_from() -> None:
+    """The set decides which star imports may be rewritten, so it has to track what was really bound."""
+    module = types.ModuleType("fake_framework")
+    module.Load = None
+
+    assert Preamble.from_modules([module]).modelled_modules == frozenset({"fake_framework"})
+
+
+def test_a_star_import_inside_a_docstring_is_not_touched() -> None:
+    """The rewrite goes through the AST, not text matching.
+
+    A script whose docstring shows an example import is not hypothetical, and commenting inside a string
+    literal is the analyser editing the user's code rather than its own view of it.
+    """
+    source = '"""\nExample:\n    from mantid.simpleapi import *\n"""\n\nx = 1\n'
+
+    assert neutralise_star_imports(source) == source
+
+
+def test_indented_star_imports_are_neutralised_where_they_appear() -> None:
+    """Only legal at module level at runtime, but parso and pyflakes will both see one if typed."""
+    source = "if True:\n    from mantid.api import *\nx = 1\n"
+
+    neutralised = neutralise_star_imports(source)
+
+    assert neutralised.split("\n")[1].startswith("    # framework import")
+    assert len(neutralised.split("\n")) == len(source.split("\n"))
+
+
+def test_a_star_import_wrapped_over_two_lines_is_blanked_on_both() -> None:
+    """The continuation line is part of the import, and leaving it would shift nothing but confuse pyflakes.
+
+    Written the way a formatter leaves a long import, the second line is inside the AST node's range, so
+    both lines have to go for the script below to stay where the user sees it.
+    """
+    source = "from mantid.simpleapi import \\\n    *\n\nx = 1\n"
+
+    neutralised = neutralise_star_imports(source)
+
+    assert neutralised.split("\n")[0].startswith("# framework import")
+    assert neutralised.split("\n")[1] == ""
+    assert neutralised.split("\n")[3] == "x = 1"
+    assert len(neutralised.split("\n")) == len(source.split("\n"))
+
+
+def test_a_script_that_does_not_parse_is_returned_unchanged() -> None:
+    """Position work on broken code belongs to the syntax pass; the linter has nothing to contribute."""
+    source = "from mantid.simpleapi import *\ndef broken(:"
+
+    assert neutralise_star_imports(source) == source
diff --git a/test/test_syntax.py b/test/test_syntax.py
new file mode 100644
index 0000000..a73d5d0
--- /dev/null
+++ b/test/test_syntax.py
@@ -0,0 +1,217 @@
+"""Syntax diagnostic tests, against the mistakes users actually make.
+
+The sources are taken from the measurements in `spike/` and from the real reduction scripts in the corpus:
+missing colons, unclosed brackets in long algorithm argument lists, `print` left over from Python 2,
+and over-indented lines. The numbers in the assertions are measured, not derived - which is the point
+of writing them down.
+"""
+
+from __future__ import annotations
+
+import jedi
+import pytest
+
+from script_lsp.models import AnalyseResponse, Diagnostic
+from script_lsp.syntax import _fragment_message, syntax_diagnostics
+
+# The shape of a real reduction script's opening, with the facility specifics removed. If this reports
+# anything, the feature will tell a working scientist that their working script is broken.
+WORKING = """\
+from mantid.simpleapi import *
+import matplotlib.pyplot as plt
+import numpy as np
+
+def reduce_run(runno, grp, use_opt=False, riavgs=5):
+    config.setAutomaticFileSearch("{'/path/to/instrument/config/'}")
+    ws = Load(Filename=f"{runno}.nxs", GroupName=grp)
+    return ws
+"""
+
+# An unclosed bracket five lines into an argument list - how a real reduction script actually broke.
+UNCLOSED_BRACKET = """\
+def reduce_run(runno):
+    ws = ScaleX(
+        InputWorkspace="mantiw",
+        XMin=2.3038,
+        XMax=5.0
+    return ws
+"""
+
+# Two independent mistakes: a missing colon, and an unterminated string on the next line. CPython stops
+# at the string; the missing colon is only visible to an error-recovering parser.
+COLON_AND_STRING = "def reduce_run(runno)\n    ws = Mtd('a\n    return ws\n"
+
+
+def test_a_working_script_is_left_alone() -> None:
+    parses, diagnostics = syntax_diagnostics(WORKING)
+
+    assert parses is True
+    assert diagnostics == []
+
+
+def test_a_script_that_will_run_is_not_reported_because_jedi_disagrees(monkeypatch: pytest.MonkeyPatch) -> None:
+    """jedi's parser is not the runner's. When CPython accepts the file, nothing may call it broken."""
+
+    def explode(*args: object, **kwargs: object) -> None:
+        msg = "jedi is having a bad day"
+        raise RuntimeError(msg)
+
+    monkeypatch.setattr(jedi, "Script", explode)
+
+    parses, diagnostics = syntax_diagnostics(WORKING)
+
+    assert parses is True
+    assert diagnostics == []
+
+
+def test_a_broken_script_still_gets_cpythons_verdict_when_jedi_fails(monkeypatch: pytest.MonkeyPatch) -> None:
+    """jedi is a bonus. Its failure must not take the authoritative verdict down with it."""
+
+    def explode(*args: object, **kwargs: object) -> None:
+        msg = "jedi is having a bad day"
+        raise RuntimeError(msg)
+
+    monkeypatch.setattr(jedi, "Script", explode)
+
+    parses, diagnostics = syntax_diagnostics(UNCLOSED_BRACKET)
+
+    assert parses is False
+    assert [item.source for item in diagnostics] == ["compile"]
+
+
+def test_a_missing_colon_is_reported_once_at_the_end_of_the_line() -> None:
+    """One mistake, one squiggle: jedi's knock-on "unexpected indent" on line 2 must not be shown."""
+    parses, diagnostics = syntax_diagnostics("def reduce_run(runno)\n    return runno\n")
+
+    assert parses is False
+    assert [(item.source, item.start_line, item.start_column) for item in diagnostics] == [("compile", 1, 22)]
+    assert ":" in diagnostics[0].message
+
+
+def test_an_unclosed_bracket_is_reported_at_the_bracket() -> None:
+    """Python 3.12+ finds this precisely, so the useful position needs no help from jedi."""
+    parses, diagnostics = syntax_diagnostics(UNCLOSED_BRACKET)
+
+    assert parses is False
+    assert diagnostics[0].message == "'(' was never closed"
+    assert (diagnostics[0].start_line, diagnostics[0].start_column) == (2, 16)
+
+
+def test_an_error_before_the_one_cpython_stopped_at_is_recovered() -> None:
+    """`compile()` gives up at the string on line 2; the missing colon on line 1 is the one to fix first."""
+    parses, diagnostics = syntax_diagnostics(COLON_AND_STRING)
+
+    assert parses is False
+    recovered = [item for item in diagnostics if item.source == "jedi"]
+    assert [(item.start_line, item.message) for item in recovered] == [(1, "expected ':'")]
+
+
+def test_a_recovered_error_is_ordered_with_the_others_by_the_response() -> None:
+    """`syntax_diagnostics` returns CPython's verdict first; the wire format is ordered by position."""
+    _, diagnostics = syntax_diagnostics(COLON_AND_STRING)
+
+    ordered = AnalyseResponse.build(content_hash="h", parses=False, diagnostics=diagnostics).diagnostics
+
+    assert [(item.start_line, item.source) for item in ordered] == [(1, "jedi"), (2, "compile")]
+
+
+def test_a_fragment_is_not_allowed_to_invent_a_context_error() -> None:
+    """A single extracted line has no enclosing function, so it appears to contain a bare `return`.
+
+    Reporting "'return' outside function" about a line inside `reduce_run` would be a confident lie,
+    and users do not forgive those.
+    """
+    _, diagnostics = syntax_diagnostics(COLON_AND_STRING)
+
+    assert all("'return' outside function" not in item.message for item in diagnostics)
+
+
+def test_an_over_indented_line_is_reported_where_it_is() -> None:
+    source = "def reduce_run(runno):\n    ws = runno\n     ws = ws + 1\n    return ws\n"
+
+    parses, diagnostics = syntax_diagnostics(source)
+
+    assert parses is False
+    assert diagnostics[0].start_line == 3
+    assert "indent" in diagnostics[0].message.lower()
+
+
+def test_python_2_print_is_reported_in_plain_words() -> None:
+    parses, diagnostics = syntax_diagnostics('import numpy as np\nprint "reduced"\n')
+
+    assert parses is False
+    assert diagnostics[0].start_line == 2
+    assert "Missing parentheses" in diagnostics[0].message
+
+
+def test_a_null_byte_is_a_diagnostic_rather_than_a_500() -> None:
+    """`compile()` raises ValueError for this; an advisory feature must not fall over on it."""
+    parses, diagnostics = syntax_diagnostics("x = 1\x00\n")
+
+    assert parses is False
+    assert diagnostics[0].start_line == 1
+    assert "null" in diagnostics[0].message
+
+
+def test_everything_returned_is_drawable() -> None:
+    """1-based, non-empty, never inverted - the model enforces these, and a violation means a bug here."""
+    _, diagnostics = syntax_diagnostics("def f(:\n  x = [1, 2\n  print 'x'\n")
+
+    assert diagnostics
+    for item in diagnostics:
+        assert isinstance(item, Diagnostic)
+        assert item.start_line >= 1
+        assert item.start_column >= 1
+        assert (item.end_line, item.end_column) > (item.start_line, item.start_column)
+        assert item.message
+
+
+def test_a_script_cpython_refuses_to_look_at_becomes_a_diagnostic_not_a_crash() -> None:
+    """A lone surrogate in the buffer makes `compile()` raise UnicodeEncodeError, not SyntaxError.
+
+    Measured on the interpreter that ships: it is a `ValueError`, so it is caught here and turned into one
+    diagnostic rather than a 500 for a script the user can see is fine. (A NUL byte, checked at the same
+    time, is a plain SyntaxError since CPython 3.12 and needs nothing special.)
+    """
+    parses, diagnostics = syntax_diagnostics('ws = Load(Filename="\ud800")\n')
+
+    assert parses is False
+    assert diagnostics[0].source == "compile"
+    assert "UnicodeEncodeError" in diagnostics[0].message
+
+
+def test_a_null_byte_is_reported_where_the_user_can_find_it() -> None:
+    """Pinned because the exception type for this input changed under us once already."""
+    parses, diagnostics = syntax_diagnostics("ws = Load(Filename='x.nxs')\n\x00\n")
+
+    assert parses is False
+    assert diagnostics[0].message == "source code string cannot contain null bytes"
+    assert (diagnostics[0].start_line, diagnostics[0].start_column) == (1, 1)
+
+
+@pytest.mark.parametrize(
+    ("line", "expected"),
+    [
+        ("if True:", None),  # "expected an indented block" describes the cut, not the script
+        ("x = 1", None),  # nothing to report about it
+        ("Load(", "'(' was never closed"),  # specific, true of the line, and better than "invalid syntax"
+    ],
+)
+def test_a_borrowed_fragment_only_lends_a_message_when_that_message_is_about_the_script(
+    line: str, expected: str | None
+) -> None:
+    """Recovering a good message means compiling a slice of the file, and a slice lies.
+
+    Out of its block, a fragment looks like it is missing a body, or like a `return` escaped a function.
+    Those are artefacts of the technique, so they are refused and jedi's vaguer-but-true message is kept.
+    """
+    assert _fragment_message(f"{line}\n", (1, 1, 1, len(line) + 1)) == expected
+
+
+def test_a_fragment_too_pathological_to_compile_offers_no_message_and_no_exception() -> None:
+    """The fallback for the fallback: whatever went wrong here, the caller still gets jedi's message.
+
+    A surrogate escapes `except SyntaxError` and would otherwise leave this function without a return
+    value on the path that matters most.
+    """
+    assert _fragment_message('x = "\ud800"\n', (1, 1, 1, 6)) is None

From 4527b4b70512ab9d87bd2eee685fb497915c6ce5 Mon Sep 17 00:00:00 2001
From: Sam <samjones714@gmail.com>
Date: Fri, 6 Nov 2026 13:51:43 +0000
Subject: [PATCH 2/6] Check the service in CI and publish it from main

tests.yml runs the unit suite, ruff and mypy on every push and PR. It needs no
Mantid, which is only true because nothing imports the framework at module scope -
if that ever changes, the job is the thing that breaks first, deliberately.

build-and-push.yml runs on main only: it pushes the image to ghcr.io and pins the
resulting digest into this service's staging manifest in ../gitops, the same route
the other FIA services use. The image build stays out of PR checks because a Mantid
base image does not belong on every branch push - which is why Dockerfile and
dependency-pin changes have to be built locally before merging.

Actions are pinned by SHA, resolved from their tags rather than copied, and the
secrets (WRITE_PACKAGE_TOKEN, GITOPS_STAGING_EDIT_TOKEN) are the ones the sibling
publish workflows already use.
---
 .github/workflows/build-and-push.yml | 61 ++++++++++++++++++++++
 .github/workflows/tests.yml          | 78 ++++++++++++++++++++++++++++
 2 files changed, 139 insertions(+)
 create mode 100644 .github/workflows/build-and-push.yml
 create mode 100644 .github/workflows/tests.yml

diff --git a/.github/workflows/build-and-push.yml b/.github/workflows/build-and-push.yml
new file mode 100644
index 0000000..c9b8a6b
--- /dev/null
+++ b/.github/workflows/build-and-push.yml
@@ -0,0 +1,61 @@
+---
+name: Build and Push Docker Images
+
+# Only main publishes: the tag that gets promoted by GitOps is the digest of a commit on main, so a
+# branch build has nowhere to go. This is the same shape as the other FIA services' publish workflows
+# (build, push, then pin the new digest into the staging manifest in ../gitops).
+
+on:
+  push:
+    branches:
+      - main
+
+env:
+  REGISTRY: ghcr.io
+  IMAGE_NAME: ${{ github.repository_owner }}
+
+jobs:
+  build-and-push:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+      - name: Check out code
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Log in to the Container registry
+        uses: docker/login-action@8aa5831fb8d48d8f76594c7ddde61ae58019f550 # v4
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.WRITE_PACKAGE_TOKEN }}
+
+      - name: Build and push mantid-python-script-lsp Docker image
+        id: docker_build
+        uses: docker/build-push-action@c3c9e263c25d99ce0380d002d59b67737d91b0dc # v7
+        with:
+          file: ./container/mantid_python_script_lsp.D
+          push: true
+          tags: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}/mantid-python-script-lsp
+
+      - name: Checkout the Gitops repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          repository: fiaisis/gitops
+          token: ${{ secrets.GITOPS_STAGING_EDIT_TOKEN }}
+
+      # The image is pinned by digest, not by tag, so a rebuild of the same content cannot silently move
+      # staging, and ArgoCD sees a real diff on every deploy.
+      - name: Edit the YAML mantid-python-script-lsp file for staging
+        uses: mikefarah/yq@59f7969b49b1d9608a37f7db006ce78f0610263e # v4.54.1
+        with:
+          cmd: yq e -i '.spec.template.spec.containers[] |= select(.name == "mantid-python-script-lsp").image = "ghcr.io/fiaisis/mantid-python-script-lsp@${{ steps.docker_build.outputs.digest }}"' './components/mantid-python-script-lsp/envs/staging/mantid-python-script-lsp.yml'
+
+      - name: Commit and push changes
+        run: |
+          git config --local user.email "action@github.com"
+          git config --local user.name "GitHub Action"
+          git commit -am "[CD] Update mantid-python-script-lsp with this commit ${{ github.event.head_commit.url}}"
+          git push
diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
new file mode 100644
index 0000000..abfe008
--- /dev/null
+++ b/.github/workflows/tests.yml
@@ -0,0 +1,78 @@
+---
+# The unit suite and the static checks. Neither needs Mantid: the framework is stubbed in
+# test/conftest.py, so CI runs on a plain Python - which is also the reason the suite must never import
+# `mantid` at module scope. Building and pushing the image is deliberately not here: it belongs with the
+# ghcr.io credentials and the image scanning, and a base image measured in gigabytes does not belong on
+# every push to a feature branch.
+
+on:
+  push:
+  pull_request:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  pytest:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout project
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Set up python
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.13"
+
+      - name: Set up cache for Python dependencies
+        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6
+        with:
+          path: ~/.cache/pip
+          key: ${{ runner.os }}-pip-${{ hashFiles('**/pyproject.toml') }}
+          restore-keys: |
+            ${{ runner.os }}-pip-
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install .[test]
+
+      - name: Run pytest
+        run: pytest test --random-order --random-order-bucket=global --cov=script_lsp --cov-branch --cov-report=term --cov-report=xml
+
+  static-analysis:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout project
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Set up python
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.13"
+
+      - name: Set up cache for Python dependencies
+        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6
+        with:
+          path: ~/.cache/pip
+          key: ${{ runner.os }}-pip-${{ hashFiles('**/pyproject.toml') }}
+          restore-keys: |
+            ${{ runner.os }}-pip-
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install .[formatting]
+
+      - name: Check formatting
+        run: ruff format --check .
+
+      - name: Lint
+        run: ruff check .
+
+      - name: Type check
+        run: mypy --strict script_lsp

From fc6c0560cc4b5adf4a8ab39f87878a915e2f90fe Mon Sep 17 00:00:00 2001
From: Sam <samjones714@gmail.com>
Date: Fri, 6 Nov 2026 13:51:43 +0000
Subject: [PATCH 3/6] Document the contract, the measurements and how to work
 on the service

README covers what gets reported and what deliberately is not (including why the
service goes silent about a script that star-imports code it cannot model), who holds
a copy of the wire contract across the three repositories, the coordinate conventions,
the configuration, and the measurements that decide the probe budgets, resource
requests, request cap and editor debounce.

AGENTS.md is the agent-facing counterpart: the hard rules that measurements forced
(never import Mantid on a request path, keep analysis off the event loop, never invent
a framework name, neutralise rather than delete star imports, no in-process analysis
fallback), the corpus privacy policy that keeps facility analysis code out of the
repository, and the FIA conventions for branches, commits and pull requests.
---
 AGENTS.md | 444 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 README.md | 271 +++++++++++++++++++++++++++++++++
 2 files changed, 715 insertions(+)
 create mode 100644 AGENTS.md
 create mode 100644 README.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..1ee6a55
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,444 @@
+# AGENTS.md
+
+Guidance for coding agents working in this repository.
+
+## What this repo is
+
+`mantid-python-script-lsp` is a small stateless HTTP service that answers one question about a FIA
+reduction script — *"does this make sense?"* — without running it. The FIA script editors POST the
+script on a debounce and get back Monaco-shaped diagnostics: syntax errors from CPython's own parser
+plus jedi's coverage of what it could not reach, and undefined-name warnings from pyflakes over a list
+of framework names generated from the running Mantid. See `README.md` for endpoints, the wire contract,
+how to run it, and the "Measurements" section — every timeout, cap and sizing number in this repo is
+derived from those measurements. Read it before making changes.
+
+The name says LSP; the service is not one. There is no session, no incremental document state, no
+WebSocket — deliberately, because a FIA pod restarts often and one broken script must not take
+everyone's editor with it. Treat the name as "language-server-ish", not as a protocol commitment.
+
+## Position in the FIA service
+
+### Overarching FIA architecture
+
+FIA is a multi-repository system (all checked out as siblings under the same parent workspace
+directory) that automatically reduces instrument data, and also lets users browse, plot, and rerun
+that data interactively:
+
+```text
+[ISIS Instrument Archive (/archive, /imat) & lastrun.txt]
+        │
+        ▼
+  file-watcher (Kopf Operator + Per-Instrument Watcher Pods)
+        │  publishes file path to RabbitMQ: `watched-files`
+        ▼
+  run-detection ◄──── fetches instrument rules (`GET /instrument/{inst}/specification`) ────► FIA-API
+        │  ingests .nxs metadata, verifies rules, publishes JobRequest JSON
+        │  to RabbitMQ: `scheduled-jobs` (or retries via `failed-watched-files`)
+        ▼
+  jobcontroller (job_creator) ◄──── requests PreScript (`GET /script/{inst}`) & posts Job ──► FIA-API ◄──► autoreduction-scripts
+        │  spawns Kubernetes Job in cluster:
+        ├──► Main container: runners (`ghcr.io/fiaisis/mantid` or `mantid-imaging`) -> writes reduced data to `/ceph`
+        └──► Sidecar container: jobcontroller (job_watcher) -> updates job status/outputs in FIA-API (`PATCH /job/{id}`)
+
+[Interactive / Web & Live Data Paths]
+  scigateway (Host App) ──► frontend (FIA React Plugin)
+                                ├──► fia-auth (UOWS login, JWT verify/refresh, `/experiments` RB lookup)
+                                ├──► FIA-API (runs, jobs, scripts, specifications, reruns -> `watched-files` / `scheduled-jobs`)
+                                │        └──► mantid-python-script-lsp (THIS REPO) — `POST /analyse`, script diagnostics
+                                └──► plotting-service (h5grove NeXus/HDF5 & IMAT image serving from `/ceph` & `/imat`)
+
+  Kafka (`<INST>_events`, `<INST>_sampleEnv`, `<INST>_runInfo`)
+        └──► live-data (Live Data Operator + Mantid Live Data Processor fetching `/live-data/{inst}/script` from FIA-API)
+
+  LLSP (Long Lived Script Processors: `LLSP-API` + RabbitMQ + Celery `LLSP-Worker` built on `ghcr.io/fiaisis/mantid`)
+
+[Infrastructure & Deployment]
+  k8s (Terraform + Ansible for OpenStack clusters, Redpanda, local Minikube)
+  gitops (ArgoCD App-of-Apps & Kustomize `base`/`envs`/`variants` manifests for all FIA services)
+```
+
+### This repository's location (upstream, downstream & siblings)
+
+- **Role**: an advisor to a human typing in a Monaco editor. Nothing else in FIA depends on this
+  service; if it is down, scripts still save and jobs still run.
+- **Upstream caller**: `frontend` (`../frontend`) — the only client. It calls through FIA-API, never
+  directly.
+- **Fronted by**: `FIA-API` (`../FIA-API`) — `POST /script/analyse` verifies the JWT, applies the size
+  cap and a per-user rate limit, and forwards this service's status and body **unchanged**. The
+  frontend branches on the status (`503` means "keep last diagnostics, retry", not "script is clean"),
+  so a proxy that rewrites status codes or wraps the body breaks the contract even when the JSON is
+  preserved.
+- **Runtime dependency**: the Mantid runner image (`ghcr.io/fiaisis/mantid`, pinned by tag in
+  `container/mantid_python_script_lsp.D`). This service has no database, no queue, and no cache of its
+  own.
+- **Deliberately not a dependency**: `../autoreduction-scripts`. Facility reduction code is not
+  installed here, and that turns out to cost almost nothing: pyflakes does not resolve modules, so
+  `import isis_powder` and `from isis_powder.routines.common import isis_num` produce no diagnostics at
+  all — the imported name is bound by the import statement itself. Only a *star* import of facility code
+  changes the picture, and the rule under "Hard rules" covers it. Facility code changing must not be able
+  to take this service down or change its answers.
+- **Sibling repositories to check when changing contracts**: `../FIA-API` (mirrors `AnalyseRequest`,
+  forwards the response) and `../frontend` (mirrors `Diagnostic`/`AnalyseResponse` in TypeScript). See
+  "The wire contract" below.
+
+### Core technologies
+
+- **Python**: the version is *not* a preference. `requires-python` in `pyproject.toml` must match the
+  interpreter in the pinned runner image, because "does this script make sense" is answered by that
+  interpreter and its packages. Check both before creating an environment.
+- **FastAPI** + **uvicorn**: ASGI app in `script_lsp/app.py`; the image listens on port 80 and runs as
+  root, like the other FIA services.
+- **Pydantic v2**: the wire contract in `script_lsp/models.py`.
+- **jedi**: name resolution and syntax errors, and later the completion/hover layer.
+- **pyflakes**: undefined-name linting over a generated preamble.
+- **Mantid**: imported only inside the runner image, only at warm-up, only off the event loop. It is
+  not a dev or CI dependency — the unit suite runs without it.
+- **pytest** (+ `pytest-random-order`, `pytest-env`, `pytest-cov`, `httpx`, `pytest-asyncio`), **Ruff**
+  (lint and format), **Mypy** (`--strict`).
+- **Process pool** (`concurrent.futures`, `forkserver`): where analysis actually runs. See
+  "Where analysis runs".
+
+## Repository structure
+
+```text
+script_lsp/                    Application source
+  app.py                       FastAPI app: lifespan, warm-up gate, /healthz and /ready
+  warmup.py                    Imports the framework in a thread, proves it with a real algorithm,
+                               generates the framework names, starts and warms the analysis pool
+  pool.py                      forkserver process pool: sizing from the cgroup quota, worker initializer
+  models.py                    THE wire contract — canonical, see "The wire contract" below
+  positions.py                 Every coordinate convention in one place; converts to Monaco's
+  preamble.py                  Framework names as a bindable source block + star-import neutralisation
+  syntax.py                    compile() + jedi merged into diagnostics
+  lint.py                      pyflakes filtered to undefined names, mapped back to the user's file
+  analyse.py                   POST /analyse
+
+test/                          Pytest suite, mirroring the package. Mantid is not needed to run it.
+container/                     Dockerfile (mantid_python_script_lsp.D), FROM a pinned runner tag
+spike/                         Measurement scripts whose output is README.md's "Measurements"
+                               section; spike/corpus/ is generated and gitignored — see "The corpus"
+.github/workflows/             tests.yml (PR checks), build-and-push.yml (main only, edits ../gitops)
+README.md                      Endpoints, contract ownership, measurements, configuration, how to run
+pyproject.toml, mypy.ini       Dependencies and ruff/mypy/pytest config
+```
+
+### Continuous integration
+
+`.github/workflows/` holds two workflows, and what runs where is deliberate:
+
+| workflow | when | what |
+| --- | --- | --- |
+| `tests.yml` | every push and PR | `pytest` with branch coverage, then `ruff format --check`, `ruff check`, `mypy --strict`. Plain Python, no Mantid — the suite stubs the framework, which is only possible because nothing imports it at module scope. |
+| `build-and-push.yml` | push to `main` only | Builds `container/mantid_python_script_lsp.D`, pushes to `ghcr.io/fiaisis/mantid-python-script-lsp`, then commits the new **digest** into the staging manifest in `../gitops`, like every other FIA service. |
+
+Consequences an agent should know:
+
+- The image build is not in the PR checks on purpose: a Mantid base image measured in gigabytes does not
+  belong on every push to a branch. A change to the Dockerfile or the dependency pins therefore has to be
+  verified **locally** by building the image before merging — CI will not catch it on a branch.
+- The publish workflow edits `../gitops`, so it fails until that component's staging manifest exists at
+  `components/mantid-python-script-lsp/envs/staging/mantid-python-script-lsp.yml` with a container named
+  `mantid-python-script-lsp`. Creating those manifests is a prerequisite for a green first run on `main`.
+- Image scanning, scorecards, CodeQL and the corpus-in-CI job are not written yet. When they are, copy the
+  sibling repositories' workflow files rather than inventing a house style — they are already consistent
+  across FIA, and Dependabot's `action-packages` group expects the SHA-pinned actions both workflows here
+  use.
+- Dependabot is not configured for this repository yet.
+
+## pyproject.toml — read this first
+
+`pyproject.toml` is the single source of truth for dependencies, extras, and tool config:
+
+- Runtime dependencies are pinned exactly (`==`); keep new ones pinned the same way.
+- Extras: `formatting` (ruff, mypy), `test` (pytest + plugins, `httpx`), `all`. `pip install .[all]`
+  (escape the brackets in zsh: `.\[all\]`).
+- `requires-python` must track the runner image's interpreter, not the other way round.
+- `version` here is the only place a version is written: `script_lsp/app.py` reads it back from the
+  installed package's metadata rather than repeating a literal, so a release cannot advertise the wrong
+  number.
+- Ruff carries the FIA-API rule set (bandit, bugbear, pylint, pyupgrade, pathlib, `line-length = 120`).
+  Check `[tool.ruff.lint.ignore]` and `per-file-ignores` before "fixing" an intentional exclusion —
+  `spike/corpus` is excluded because linting facility scripts would report problems in someone else's
+  analysis code, and `warmup.py` is allowed deferred imports because Mantid exists only in the image.
+- Mypy config is in `mypy.ini` (`--strict`, with the C-extension framework and pyflakes exempt).
+- `pytest-random-order` is required: tests must not depend on execution order.
+
+## The wire contract
+
+`script_lsp/models.py` is canonical. Three repositories hold a copy of it, and that duplication is
+deliberate — it is what keeps this service deployable on its own, and it makes a breaking change a
+three-repo change rather than a runtime surprise:
+
+| repo | what it holds |
+| --- | --- |
+| here | `AnalyseRequest`, `Diagnostic`, `AnalyseResponse` — canonical |
+| `../FIA-API` | `AnalyseRequest` only, for validation and rate-limit keying; the response is passed through |
+| `../frontend` | a TypeScript mirror of `Diagnostic`/`AnalyseResponse` |
+
+Rules that fall out of this:
+
+- **Diagnostics are advisory.** Nothing may turn a diagnostic into a blocked save or a blocked rerun.
+  A script this service cannot understand must never be reported as broken.
+- **The `content_hash` round-trip is not decoration.** The editor discards any response whose hash does
+  not match the buffer it sent. Never echo back a hash the service invented.
+- **Positions are Monaco's**: 1-based lines, 1-based columns, UTF-16 code units, `end_column`
+  exclusive. CPython reports code-point offsets, jedi reports code-point columns, pyflakes reports
+  UTF-8 **byte** offsets. That is four conventions; `positions.py` is the only place allowed to know
+  about them. Do not convert coordinates anywhere else.
+- **Severity is a colour the user sees, not a log level.** `error` and `warning` map onto Monaco's marker
+  severities — red and orange. `info` is deliberately absent from the `Literal`: a grey squiggle for
+  something nobody can act on trains users to ignore the two levels that mean something. When the marker
+  bridge is built in `../frontend`, that mapping is where the two contracts meet, and the same note
+  belongs in that repository's `AGENTS.md`.
+- **Ranges must be non-empty.** Monaco draws nothing for a zero-width range, so a range where start
+  equals end is widened by one character.
+- `parses: false` does **not** mean "plus one warning" — linting a non-parsing script produces an
+  undefined name per name, so lint is skipped and one true syntax error is returned.
+
+## Hard rules for this service
+
+Things an agent will otherwise get wrong, learned from measurements in this repo:
+
+- **Report only names whose every possible source is known.** A name is called undefined only if the
+  script, the builtins, and the modules the preamble binds account for everything it could arrive from.
+  `neutralise_star_imports` therefore rewrites star imports of *modelled* modules only: blanking
+  `from isis_powder import *` claims its names were supplied, and measured on a script in that shape it
+  produced three "undefined name" reports for facility helpers on code that runs correctly. Left alone,
+  pyflakes hedges each unresolved name as `ImportStarUsage`, which is not reported — so such a script
+  gets no undefined-name checking, including for genuine typos. That loss is accepted, tested
+  (`test_that_silence_covers_a_typo_too_and_that_is_a_decision_not_an_oversight`) and not to be "fixed"
+  by making the linter confident again.
+- **Never import Mantid on a request path, or at module import time.** The import is not thread-safe
+  alongside an asyncio loop and shows up as a hang, not an error. It happens once, in a thread, at
+  warm-up (`warmup.py`), and the workers inherit the result. If you find yourself wanting
+  `import mantid` in `syntax.py`/`lint.py`/`analyse.py`, the design has changed.
+- **Keep analysis off the event loop.** Analysis is CPU-bound and holds the GIL: measured at 13.7
+  analyses/s on Starlette's threadpool versus 64/s serial and 247/s in 8 processes — threads are
+  *worse than doing nothing*. Work goes through `pool.py`. `/healthz` staying honest depends on
+  this.
+- **Do not invent framework names.** The list of names a script is allowed to use comes from `dir()` on
+  live modules at warm-up. A made-up name (there was a candidate called `Configurator`, which does not
+  exist in Mantid 7) suppresses a real warning forever and teaches users to ignore the squiggle.
+- **Neutralise star imports; do not delete them.** `from mantid.simpleapi import *` makes pyflakes stop
+  reporting real typos. It is replaced line-for-line with an equal-length comment so every other line
+  number survives. If you change that rewriting, the line-number round-trip test in
+  `test/test_preamble.py` must fail.
+- **Readiness means the whole path.** `/ready` waits for a real algorithm to have run, the
+  names to be generated, and a probe analysis to have completed in every pool worker — `ProcessPoolExecutor`
+  spawns lazily, and an unwarmed worker pays jedi's import inside a user's keystroke.
+- **Never run the analysis fallback in-process.** If the pool is gone, answer `503`; do not quietly
+  analyse on the loop to stay available.
+- **Size caps count bytes, and both sides must mean the same thing by them.** `MAX_SCRIPT_BYTES` is
+  compared against `len(content.encode())`, not `len(content)`, and FIA-API enforces the same number
+  against the same definition — a script of 200,000 *characters* of multi-byte text is bigger than the
+  cap. The two values are separately configured, so changing one without the other produces a service
+  that rejects scripts its proxy already accepted. The same caveat is recorded in `../FIA-API/AGENTS.md`
+  for whoever adds the route.
+- **Probe paths are the FIA names.** `/healthz` for liveness, `/ready` for readiness — the same pair
+  every other component answers and every probe in `../gitops` points at. Renaming them is a deployment
+  break, not a cosmetic choice; `test/test_health.py` pins it.
+- **Byte-size caps are checked before parsing**, and the limit is a memory decision, not a style one.
+
+## The corpus
+
+`spike/corpus/` is generated by `spike/make_corpus.py` from real reduction scripts pulled off a live
+FIA API, and is **gitignored**. It contains facility analysis code — instrument names, archive paths,
+working configurations — so it stays out of the repository even though the generator is checked in.
+
+- Do not commit it, paste it into a PR, an issue, or a test fixture.
+- CI must not depend on it. The corpus test uses synthetic fixtures shaped like real scripts
+  (star import, `mtd`, chained `ConfigRegistry()` calls, `GlobalInput.Get()`); the real-corpus check
+  runs locally against a script the developer holds.
+- Variants are `<name>.py`, `_small`, `_x2`, `_x8` (scale, for latency), `_broken` (a deliberate
+  mistake), `_star` (framework imported with `*`, the common case in real scripts).
+- The requirement the corpus exists to enforce: **a clean real script produces zero diagnostics.**
+  Anything else is a bug in this service, not advice for the user.
+
+## Measurements
+
+`README.md`'s "Measurements" section is derived from `spike/`, not hand-written. When you change
+anything that affects cost — a base image bump, a new parser, the preamble, the pool — re-run the spike
+scripts **in the image** and update those tables. Do not edit a number to match new code.
+
+Two traps, both measured:
+
+- The laptop numbers are noisy: the same HTTP configuration measured 27 ms and 108 ms on successive
+  runs, and a `/healthz` control in a 24-process burst moved between 20 ms and 84 ms depending on
+  machine load. In-process numbers reproduce to a few percent. Quote the in-process comparison in
+  conclusions and treat HTTP figures as order-of-magnitude.
+- `os.cpu_count()` reports the host's cores, not the pod's cgroup quota. Pool sizing reads
+  `cpu.max` / `cpu.cfs_quota_us` for that reason.
+
+## Environment & running commands
+
+These instructions are deliberately generic: do not assume any machine already has a conda env, a
+kubectl context, or this repo's image built — check what is actually available before running
+anything, and don't hardcode names you happened to see on one machine into scripts or docs.
+
+Prefer `conda` when it is available; fall back to a `venv` only if conda is not installed
+(`command -v conda` on Linux/macOS, `where conda` on Windows — never assume either way).
+
+1. Check for an existing env for this project: `conda env list` (env names vary per machine — look for
+   one matching the repo name).
+   ```shell
+   conda run -n <env-name> <command>
+   ```
+2. If conda exists but no env does:
+   ```shell
+   conda create -n mantid-python-script-lsp python=<version-from-pyproject.toml> -y
+   conda run -n mantid-python-script-lsp pip install -e '.[all]'
+   ```
+3. Only without conda, use a virtualenv (`.venv/bin/activate` on POSIX,
+   `.venv\Scripts\Activate.ps1` on Windows), then `pip install -e '.[all]'`.
+
+The suite does not need Mantid. The service does: run it with `uvicorn script_lsp.app:app` only in a
+place where `import mantid` works (inside the image), and remember `/ready` stays `503` until
+warm-up finishes.
+
+```shell
+conda run -n <env-name> pytest test --random-order --random-order-bucket=global
+conda run -n <env-name> ruff check . && conda run -n <env-name> ruff format .
+conda run -n <env-name> mypy --strict script_lsp
+
+docker build -f container/mantid_python_script_lsp.D -t mantid-python-script-lsp:local .
+docker run --rm -p 8080:80 mantid-python-script-lsp:local
+```
+
+**Do not run pytest/ruff/mypy with the repo bind-mounted into a container.** They write caches into the
+working tree as root, and the next host run fails with "attempt to write a readonly database" or
+refuses to overwrite root-owned `.pytest_cache`/`.ruff_cache`/`.mypy_cache`. Run the checks in a host
+env, and use a container only when Mantid is genuinely required (in which case copy the repo into the
+image's own filesystem, or clean the caches afterwards).
+
+### Configuration
+
+| variable | what it does |
+| --- | --- |
+| `ANALYSIS_WORKERS` | Number of analysis processes. Unset: one per core of the pod's CPU quota, falling back to `min(4, cores)`. A non-numeric or sub-1 value falls back to the quota, never to zero workers. |
+| `MAX_SCRIPT_BYTES` | Request size cap in bytes (default 200,000). Must equal FIA-API's cap — see the caveat under "The wire contract". |
+| `DIAGNOSTIC_LIMIT` | Diagnostics returned per request (default 100), ordered by position, with `truncated: true` beyond it. |
+
+All three are read once at import and a value that cannot be honoured is logged and ignored rather than
+applied: a typo in a Deployment must not produce a pod that rejects every script.
+
+## Kubernetes commands
+
+Available kubectl contexts vary per machine/operator — always run `kubectl config get-contexts` first
+and see what is actually configured. Never rely on the current context; always pass `--context`
+explicitly, at the **end** of the command:
+
+```shell
+kubectl get pods -n fia --context <context-name>
+kubectl logs deploy/mantid-python-script-lsp -n fia --context <context-name>
+```
+
+Double- and triple-check the context name before running anything against a production-like cluster.
+
+## Managing issues
+
+There is no local `.github/ISSUE_TEMPLATE/`; GitHub serves the org-wide default from `fiaisis/.github`.
+Use it rather than inventing a format:
+
+```shell
+gh issue create --template Issue
+```
+
+Check `gh issue list` / `gh issue view <number>` first to avoid duplicates.
+
+## Branch naming
+
+Branches use snake_case descriptions of the work. No category prefixes like `feature/` or `fix/`.
+
+- **Format**: `description_of_work` (e.g. `add_analysis_pool`, `handle_star_imports`).
+
+## Commit messages
+
+`main`'s history is squash merges: one commit per PR, titled `<PR title> (#<PR number>)`. So the PR
+title is what survives permanently — but individual commit messages still become the squash body, so
+write each one as a focused unit of work in the imperative mood, with a *why* in the body for anything
+non-trivial. In this repo especially: a change that reverses an earlier decision (threadpool → process
+pool is the example) should cite the measurement that forced it, because the previous approach looks
+reasonable to anyone reading the code alone.
+
+## Requirements for code changes
+
+Only run tests, linters, and type checkers when they are **relevant to the files you actually
+changed** — skip them for `.md`-only changes. When you do change Python, dependencies, or config:
+
+1. **Add or update tests** in the mirroring `test/` file for any new or changed behaviour. Tests must
+   pass without Mantid: stub `script_lsp.warmup.load_framework` (see `test/conftest.py`) rather than
+   skipping.
+2. **Verify against the real corpus locally** if you touched anything that produces diagnostics —
+   `spike/corpus/MERLIN*.py` must still report zero diagnostics, and a deliberate typo must still be
+   caught at its real position. A change that makes the corpus clean by making the linter mute has
+   failed.
+3. **Run the checks** (`ruff check .`, `ruff format .`, `mypy --strict script_lsp`, `pytest test
+   --random-order`) and fix everything reported.
+4. **Keep `script_lsp` covered.** It is at 100% statements *and* branches; the only exclusions are
+   `load_framework` and `preamble.build`, both marked `# pragma: no cover` with the reason, because they
+   cannot run without the framework and run in the image instead. Add coverage with the code rather than
+   lowering the bar; if something genuinely cannot be covered outside the image, say so in the pragma
+   comment.
+4. **Re-run measurements** in the image and update README's "Measurements" tables if the change affects
+   cost or concurrency.
+
+## Pull request process
+
+1. **Local validation** before opening a PR (for `.py`/`pyproject.toml`/workflow changes):
+   ```shell
+   conda run -n <env-name> pytest test --random-order --random-order-bucket=global
+   conda run -n <env-name> ruff check .
+   conda run -n <env-name> ruff format .
+   conda run -n <env-name> mypy --strict script_lsp
+   ```
+   Plus the image build and a real request against it if the change affects the analysis path — unit
+   tests cannot catch "Mantid does not import in the deployed image", which is this service's most
+   expensive class of failure.
+2. **PR title**: clear, concise, normal grammar (e.g. `Neutralise star imports before linting`). Not
+   snake_case.
+3. **PR description**: the org-wide template from `fiaisis/.github` — `Closes # <Issue Number>` then
+   `## Description`. Ask the user for the issue number if it isn't evident, or confirm there is none.
+4. **AI-assistance label**: attach the repo's AI label (`gh label list` first; create `AI` with
+   `gh label create "AI" --description "Created with the assistance of AI"` if absent).
+5. **Contract changes**: open the PRs in `../FIA-API` and `../frontend` alongside, and say in each
+   description which direction the change is compatible in, so the three can be merged in an order
+   that never breaks an older client.
+
+## Handling Dependabot PRs
+
+Dependabot is not configured for this repo yet. When it is added, expect the two dangerous categories,
+and neither is a routine bump:
+
+- **The runner base image tag** (`ARG RUNNER_TAG` in `container/mantid_python_script_lsp.D`): changing
+  it changes which names scripts may use, what pyflakes knows, and the cost of warm-up. Bump it
+  deliberately, with the corpus check and a fresh set of measurements.
+- **jedi / pyflakes**: they define what gets reported. Run the corpus check; a "cleaner" result from a
+  pyflakes upgrade usually means it has stopped seeing something.
+
+For ordinary dependency and GitHub-Action bumps: `gh pr diff <number>`, then `pytest`, `ruff check`,
+`mypy --strict`, and `gh pr checks <number>`; approve and `gh pr merge <number> --merge` (add
+`--admin` if branch protection blocks it), close superseded PRs, and finally re-run the suite on
+`main`.
+
+## General working practices
+
+- Prefer the `read` tool over `sed`/`cat` one-liners for inspecting files, and `write`/`edit` over
+  `cat <<EOF`, `sed -i`, or Python one-liners for changing them.
+- Ask the user when a task is ambiguous — especially anything that would change the wire contract, the
+  advisory-only guarantee, the corpus policy, the pinned runner tag, or whether facility code should be
+  reachable from this service. Those are decisions with cross-repo consequences, not implementation
+  details.
+- Verify behaviour by measurement before asserting it, and say which you did. This repo has already had
+  three plausible-looking assumptions found false in the real image: that `AlgorithmManager` was usable
+  for warm-up (it raises on this build), that `Configurator` was a framework global (it does not exist),
+  and that a threadpool was adequate for CPU-bound work (it measured slower than serial).
+- Keep README's endpoint, contract and measurement sections in the same commit as the code they
+  describe.
+
+## Keeping this document up to date
+
+If a change makes anything here inaccurate — a new endpoint or environment variable, a changed
+directory layout, a new or renamed CI workflow, a Dependabot grouping, a change to the wire contract or
+the corpus policy, a different way to run tests, or a new hard-won measurement about how Mantid, jedi,
+pyflakes or the pool behave — update the relevant section in the same change. Treat it like
+`README.md`: documentation that goes stale is worse than none, and the next agent will trust it.
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..9ae8c57
--- /dev/null
+++ b/README.md
@@ -0,0 +1,271 @@
+# mantid-python-script-lsp
+
+Server-side Python analysis for the FIA script editors: it is what lets the reduction-script and
+live-data-script editors in [`frontend`](../frontend) show real squiggles on Mantid scripts.
+
+This is a stateless HTTP facade over Python's own parser plus the analysis environment the runners
+already have — **not** a language server. There is no session, no LSP socket and no document state:
+each request carries a script, and the response is a list of diagnostics.
+
+## Why this exists as a service
+
+The scripts users write here are not ordinary Python. The runner brings roughly 1,800 names into scope
+without an import — every algorithm, plus `mtd`, `config`, `ConfigService` — because it does
+`from mantid.simpleapi import *`, and most of those algorithm functions do not exist as objects until
+the framework generates them at runtime. Facility helpers arrive a second way, by explicit import
+(`import reduction_utils`, `from isis_powder... import ...`), from code this service deliberately does
+not install. A linter in the browser can see syntax; it can see none of that, and a checker that
+reports `Undefined name 'Load'` on every real script is worse than no checker at all. The only
+environment that can answer those questions correctly is the one that runs the scripts — the Mantid
+runner image — so the check runs there.
+
+Diagnostics are **advisory**. Nothing here blocks Save or "Rerun with changes"; the frontend treats a
+slow or unreachable service as "unknown" and gets out of the way.
+
+## What gets reported, and what deliberately does not
+
+| | reported? | why |
+| --- | --- | --- |
+| Anything `compile()` rejects | error | it is the runner's own parser: this script cannot run, whatever the framework provides |
+| Syntax errors `compile()` reaches too late | error, from jedi | a brace opened at line 144 is the mistake; CPython only notices at 149 |
+| A name no one provides | warning | `BinMD` typed as `BinMQ` — the check nothing else in FIA can do |
+| Unused imports, unused variables, style | never | measured as 2-3 to 35 messages per real script; commentary on someone's analysis code, in the colour reserved for broken code |
+| Any name in a script that does not parse | never | half-typed code produces an undefined name per name; the syntax error is the whole answer |
+| Anything at all in a script that star-imports code we do not model | never | see below |
+
+The last row is the one worth explaining. A script may do `from isis_powder import *`, pulling in names
+from facility code this service deliberately does not install, so their existence cannot be checked. Left
+in place, pyflakes hedges every unresolved name in that script as `ImportStarUsage`, which is not
+reported — the service says nothing about the whole script rather than inventing three faults in it and
+missing the real one. Rewriting that import away reported `undefined name 'load_grouping_file'` on a
+script that runs correctly. Silence about what cannot be known beats being confidently wrong: one false
+positive costs the credibility of every warning beside it.
+
+## Position in FIA
+
+```text
+frontend (Monaco Python editors)
+      │  POST /script/analyse   { content, contentHash, instrument }
+      ▼
+FIA-API  — authenticates, caps size, rate-limits, caches, 5 s upstream timeout
+      │  POST /analyse
+      ▼
+this service — compile()'s verdict, jedi's syntax coverage, pyflakes undefined names
+              over a preamble generated from the running framework
+```
+
+The frontend never talks to this service directly: routing through FIA-API keeps auth, rate limiting
+and the size cap in one place, and means this service never has to know who a user is.
+
+## Positions
+
+Every position in the request and response is **1-based lines and 1-based columns, counted in UTF-16
+code units** — Monaco's own coordinate system, not an LSP import of it. Its typings are explicit:
+`IPosition.lineNumber` "starts at 1", and `IPosition.column` is described as "the first character in a
+line is between column 1 and column 2". Diagnostic fields deliberately mirror `IMarkerData`
+(`startLineNumber`, `startColumn`, `endLineNumber`, `endColumn`, `severity`, `message`, `source`) so the
+frontend is a field copy rather than a translation layer, and `endColumn` is exclusive the way Monaco
+treats it.
+
+Four parsers disagree about what a column is, which is why `script_lsp/positions.py` exists as the single
+place that knows: CPython reports code-point offsets, jedi reports code-point columns, pyflakes reports
+UTF-8 **byte** offsets, and Monaco wants UTF-16 units. For `x = "😀😀" + class`, CPython's offset for
+`class` is 12 and the squiggle belongs at columns 14–19.
+
+## Who holds a copy of the contract
+
+`script_lsp/models.py` is canonical. Three repositories hold a copy of it, and that duplication is
+deliberate: it keeps this service deployable on its own, and it turns a breaking change into a
+three-repository change rather than a runtime surprise.
+
+| repository | what it holds |
+| --- | --- |
+| here | `AnalyseRequest`, `Diagnostic`, `AnalyseResponse` — canonical |
+| `../FIA-API` | `AnalyseRequest` only, for validation and rate-limit keying; the response is passed through untouched |
+| `../frontend` | a TypeScript mirror of `Diagnostic` / `AnalyseResponse` |
+
+`severity` is `error` or `warning`, and those map onto Monaco's marker severities — red and orange.
+There is no third level: a grey squiggle for something the user cannot act on trains them to ignore the
+two that matter.
+
+## Endpoints
+
+| endpoint | meaning |
+| --- | --- |
+| `GET /healthz` | Process up. Independent of Mantid on purpose: a slow warm-up must not look like a crash loop. |
+| `GET /ready` | 200 once the framework has answered a real algorithm *and* every analysis worker has completed a probe; 503 with the reason until then. |
+| `POST /analyse` | Diagnostics for one script. See `script_lsp/models.py` for the shape. |
+
+`/analyse` answers `200` (analysed), `422` (rejected: over the byte cap, or no `content_hash`) or `503`
+(still warming up). FIA-API forwards the status and body unchanged and the frontend branches on the
+status: `503` means keep the previous squiggles and retry shortly, not "this script is clean".
+
+Measured in the built image, against the real reduction-script corpus described under
+[Measuring](#measuring):
+
+| request | result |
+| --- | --- |
+| `MERLIN.py` — 11 KB, 286 lines | `parses: true`, **0 diagnostics** |
+| `MERLIN_star.py` — the same script, framework imported with `*` | **0 diagnostics** (naive pyflakes reports 14 here) |
+| `MERLIN_x8.py` — 90 KB, 2,302 lines, beyond anything real | 0 diagnostics |
+| `MERLIN_broken.py` | 2 diagnostics: the cause at 144 from jedi, the effect at 149 from `compile()` |
+| 199,999 bytes | 200 |
+| 240,000 bytes | 422, before anything parses it |
+
+The corpus is generated from scripts pulled off a live FIA API — instrument configurations, sample
+environment details and archive paths that are not ours to publish — so it lives in `spike/corpus/`, is
+gitignored, and never appears in a PR or an issue. A fresh checkout has no corpus: tests use synthetic
+scripts shaped like real ones, and the real-corpus check is run locally by whoever holds a script. The
+requirement it enforces is that a clean real script produces **zero** diagnostics.
+
+## Measurements
+
+These are the numbers the deployment and the editor were sized from. Reproduce with
+`spike/bench.py` and `spike/make_corpus.py` in the built image; when you change anything that affects
+the cost of an analysis — a base-image bump, a new parser, the preamble, the pool — re-run them rather
+than editing the tables.
+
+**Warm-up, once per process:** `import mantid` is 174 ms warm and 1,064 ms cold; `from mantid.simpleapi
+import *` is 2.2 s warm, and 10 s once with a cold page cache. Steady-state RSS is 260 MB, peaking at
+291 MB. Container start to `/ready` 200 is 3.7–5.1 s including the generated names and the probe
+analysis in every worker.
+
+**Per request:** cost is linear at about **0.12 ms per KB** — 1.2 ms median for the real 11 KB script,
+11 ms for 90 KB. Importing Mantid changes none of it (467 ms before the import, 461 ms after, over the
+same corpus).
+
+**Concurrency, and why the analysis runs in processes:** the same 11 KB script analysed 24 times, in one
+process:
+
+| execution model | total | throughput |
+| --- | --- | --- |
+| one at a time | 373 ms | 64 /s |
+| 24 threads (what was written first) | 1,747 ms | **13.7 /s** |
+| 8 worker processes | 97 ms | **247 /s** |
+
+Threads are 4.6x slower than doing the work serially: `ast.parse` and pyflakes never release the GIL, so
+they thrash it instead of overlapping. Processes give 18x the threadpool. The property that makes the
+pool cheap is that request-time analysis never touches Mantid — it needs only the 90 lines of preamble
+text, so workers cost tens of megabytes rather than the parent's quarter-gigabyte.
+
+Trust those three rows; be sceptical of latencies measured over HTTP on a developer machine, which moved
+between 27 ms and 108 ms for the same configuration across runs. The in-process comparisons reproduced to
+a few percent. Size the Deployment from the real cluster, not from these.
+
+**jedi's first completion costs 1.9 s** in a process (6.8 ms afterwards, and 26 MB for the index).
+`/analyse` does not pay it — `get_syntax_errors()` only parses — but `/complete` will, and it belongs in
+warm-up rather than in a user's first keystroke.
+
+### What they decide
+
+- `startupProbe` needs a ceiling around 60 s: a normal cold start is under 6 s, but a cold page cache
+  plus a CPU-throttled node is not, and killing a pod for warming slowly turns slow starts into restart
+  loops.
+- `resources.requests` of 1 CPU / 1 Gi with a 2 Gi limit: 260 MB steady, 291 MB peak, and the rest is
+  headroom for jedi and pyflakes on a large script.
+- The 200 KB cap bounds the worst case near 25 ms of CPU against FIA-API's 5 s upstream timeout — two
+  orders of magnitude of headroom, so that timeout guards against a wedged process, not a big script.
+- **The 1,000 ms editor debounce is not a server constraint.** At the cap a check costs ~25 ms. The
+  debounce is there for request volume and for not moving squiggles under a cursor; if typing feels
+  sluggish, 300 ms is affordable without touching this service.
+- One uvicorn worker per pod, scaling by pods. `uvicorn --workers N` would pay N warm-ups to share
+  nothing that pods don't already share, and make readiness ambiguous.
+
+## Configuration
+
+| variable | default | what it does |
+| --- | --- | --- |
+| `ANALYSIS_WORKERS` | one per core of the pod's CPU quota, else `min(4, cores)` | How many analysis processes to run. Workers above the CPU quota get CFS-throttled in ~100 ms bursts, which turns a throughput question into a latency spike. |
+| `MAX_SCRIPT_BYTES` | 200,000 | The request size cap, in **bytes**. It must be set to the same value as FIA-API's own cap or one of them starts rejecting scripts the other accepted. |
+| `DIAGNOSTIC_LIMIT` | 100 | How many diagnostics come back, ordered by position, with `truncated: true` beyond it. |
+
+A value that is not a positive integer is logged and ignored rather than honoured: a typo in a manifest
+must not produce a service that rejects every script or reports nothing.
+
+## Base image
+
+`container/mantid_python_script_lsp.D` is `FROM ghcr.io/fiaisis/mantid:<tag>`, pinned to a runner tag,
+and the dependency pins in `pyproject.toml` have to be satisfiable by that image's interpreter. This
+repository is therefore implicitly coupled to `../runners`: moving the tag changes which names a script
+may use, what warm-up costs, and which algorithms exist. It is a deliberate act with a corpus check and a
+re-measurement, never a rebuild side effect.
+
+One consequence to keep an eye on: the pins here resolve pydantic 2.13.4, which *downgrades* the 2.14.2
+that comes in the runner image. Nothing observable broke, but the base image is not ours to quietly
+change — if a future bump makes that matter, the question is whether this service should pin pydantic at
+all or inherit the base's.
+
+Not yet measured, and worth knowing before sizing anything: behaviour under sustained load with the pool
+in place, the 200 KB cap-sized script at full concurrency, and jedi with its completion dictionary built.
+
+## Repository structure
+
+```text
+script_lsp/
+  app.py                        FastAPI app: lifespan, warm-up gate, /healthz and /ready
+  warmup.py                     Imports the framework, proves it, generates the names, starts the pool
+  pool.py                       Where the analysis runs: a forkserver process pool, sized from the cgroup
+  models.py                     THE wire contract - canonical, see "Who holds a copy of the contract"
+  positions.py                  CPython/jedi/pyflakes coordinates to Monaco's (UTF-16, 1-based)
+  preamble.py                   Framework names made visible to static analysis, and the offset they add
+  syntax.py                     `compile()` + jedi merged into diagnostics
+  lint.py                       pyflakes, filtered to undefined names, mapped back to the script
+  analyse.py                    `POST /analyse`
+test/                           Pytest suite, mirroring the package
+container/                      Dockerfile (`mantid_python_script_lsp.D`), built FROM a pinned runner tag
+spike/                          The measurement scripts behind "Measurements" above
+pyproject.toml                  Dependencies (pinned), ruff and pytest config
+mypy.ini                        mypy --strict, with the C-extension imports exempt
+```
+
+## Local development
+
+The unit suite does not need Mantid — the framework is stubbed — but the running service does, and
+`requires-python` has to match the interpreter in the runner image. A conda env on the host is the
+practical loop for tests and linting:
+
+```shell
+mamba create -n mantid-python-script-lsp python=3.13 -y
+pip install -e '.[all]'
+
+pytest test --random-order --random-order-bucket=global
+ruff check . && ruff format .
+mypy --strict script_lsp
+```
+
+`script_lsp` is at 100% statement and branch coverage and the two exceptions to that are marked
+`# pragma: no cover` with a reason (they need the framework). New code is expected to come in covered;
+the parts that cannot be, run in the image instead.
+
+Do not run pytest/ruff/mypy with the repo bind-mounted into a container: they write caches into the
+working tree as root and the next host run fails with "attempt to write a readonly database". Use a
+container only when Mantid is genuinely required.
+
+### Build and run the image
+
+```shell
+docker build -f container/mantid_python_script_lsp.D -t mantid-python-script-lsp:local .
+docker run --rm -p 8080:80 mantid-python-script-lsp:local   # the image listens on 80, like other FIA services
+
+curl -i localhost:8080/healthz    # always 200: the process is up
+curl -i localhost:8080/ready      # 503 while the framework is warming, then 200 with the seconds it took
+```
+
+Kubernetes owns liveness and readiness — there is deliberately no `HEALTHCHECK` in the image, because a
+Docker-level check can mask a framework that is still warming.
+
+Merging to `main` builds and publishes the image, then pins the resulting digest into this service's
+staging manifest in [`../gitops`](../gitops) — the same route every other FIA service takes. Because the
+base image is far too large to build on every branch push, CI's PR checks are the unit suite, ruff and
+mypy only: **changes to the Dockerfile or the dependency pins must be built locally before merging**,
+because nothing on a branch will tell you they broke.
+
+### Measuring
+
+```shell
+python spike/make_corpus.py /path/to/a/real/script.py   # writes spike/corpus/ (gitignored)
+python spike/bench.py                                   # inside the image: it needs the framework
+```
+
+`spike/` is kept rather than discarded because the tables above are derived from it: anything that
+changes the cost of an analysis means re-running it and updating this README.

From 84bc7f578733ee957a7ce0c36afa57a0bcabcef1 Mon Sep 17 00:00:00 2001
From: Sam <samjones714@gmail.com>
Date: Fri, 6 Nov 2026 13:55:25 +0000
Subject: [PATCH 4/6] Say plainly that an agent labels its own pull request AI

'Attach the repo's AI label' reads like something the human doing the merge handles.
The one who knows a PR was machine-written is the one who opened it.
---
 AGENTS.md | 13 +++++++++++--
 1 file changed, 11 insertions(+), 2 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 1ee6a55..48574fb 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -398,8 +398,17 @@ changed** — skip them for `.md`-only changes. When you do change Python, depen
    snake_case.
 3. **PR description**: the org-wide template from `fiaisis/.github` — `Closes # <Issue Number>` then
    `## Description`. Ask the user for the issue number if it isn't evident, or confirm there is none.
-4. **AI-assistance label**: attach the repo's AI label (`gh label list` first; create `AI` with
-   `gh label create "AI" --description "Created with the assistance of AI"` if absent).
+4. **AI-assistance label — apply it yourself, every time.** A pull request you opened was made with the
+   assistance of AI, so label it `AI` as you create it rather than leaving it for a human to notice:
+   ```shell
+   gh pr create --label AI ...                       # at creation
+   gh pr edit <number> --add-label AI                # if the PR is already open
+   ```
+   The repository carries the same label set as `../FIA-API` (`AI`, `dependencies`, `github_actions`,
+   `python`, `waiting_on_something` plus the GitHub defaults), so nothing normally needs creating. Check
+   with `gh label list -R fiaisis/mantid-python-script-lsp` first, and if a label genuinely is missing,
+   create it with FIA-API's exact name, colour and description rather than inventing one — a label with a
+   different colour per repository is a label nobody can scan at a glance.
 5. **Contract changes**: open the PRs in `../FIA-API` and `../frontend` alongside, and say in each
    description which direction the change is compatible in, so the three can be merged in an order
    that never breaks an older client.

From 160b84f34108bc57ae14d56399dd3ceccdb0a2d7 Mon Sep 17 00:00:00 2001
From: Sam <samjones714@gmail.com>
Date: Fri, 6 Nov 2026 14:40:58 +0000
Subject: [PATCH 5/6] Add nightly Trivy image scan and Dependabot config

---
 .github/dependabot.yml           | 27 ++++++++++++++++
 .github/workflows/image-scan.yml | 53 ++++++++++++++++++++++++++++++++
 AGENTS.md                        | 20 +++++++-----
 3 files changed, 92 insertions(+), 8 deletions(-)
 create mode 100644 .github/dependabot.yml
 create mode 100644 .github/workflows/image-scan.yml

diff --git a/.github/dependabot.yml b/.github/dependabot.yml
new file mode 100644
index 0000000..d0d3bf5
--- /dev/null
+++ b/.github/dependabot.yml
@@ -0,0 +1,27 @@
+---
+# Same grouping as ../FIA-API: one PR a week for Python, one a day for Actions.
+#
+# The base image is not Dependabot's to bump. `ARG RUNNER_TAG` in
+# `container/mantid_python_script_lsp.D` decides which names a script may use, what warm-up costs and
+# which algorithms exist, so moving it means the corpus check and a fresh set of measurements - see
+# AGENTS.md, "Handling Dependabot PRs".
+
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    groups:
+      python-packages:
+        patterns:
+          - "*"
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "daily"
+    groups:
+      action-packages:
+        patterns:
+          - "*"
diff --git a/.github/workflows/image-scan.yml b/.github/workflows/image-scan.yml
new file mode 100644
index 0000000..599c841
--- /dev/null
+++ b/.github/workflows/image-scan.yml
@@ -0,0 +1,53 @@
+---
+name: Image Scan
+
+# Nightly rather than per-push: the base image is Mantid's, so the vulnerabilities found here are mostly
+# whoever else's Debian packages are, on a schedule that catches them becoming public. A failing scan
+# uploads SARIF to the Security tab instead of silently passing.
+
+on:
+  schedule:
+    - cron: "49 8 * * *"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  security-events: write
+
+env:
+  REGISTRY: ghcr.io
+  IMAGE_NAME: ${{ github.repository_owner }}
+
+jobs:
+  trivy:
+    name: Trivy image scan
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Build Docker image
+        uses: docker/build-push-action@c3c9e263c25d99ce0380d002d59b67737d91b0dc # v7
+        with:
+          file: ./container/mantid_python_script_lsp.D
+          tags: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}/mantid-python-script-lsp:${{ github.sha }}
+          push: false
+
+      - name: Run Trivy vulnerability scanner
+        uses: aquasecurity/trivy-action@a9c7b0f06e461e9d4b4d1711f154ee024b8d7ab8 # v0.36.0
+        with:
+          image-ref: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}/mantid-python-script-lsp:${{ github.sha }}
+          format: sarif
+          output: trivy-results.sarif
+          ignore-unfixed: true
+          exit-code: 1
+
+      - name: Print results
+        run: cat trivy-results.sarif
+        if: failure()
+
+      - name: Upload Trivy scan results to GitHub Security tab
+        uses: github/codeql-action/upload-sarif@f3bbb05694c2f74569081c28664dec21 # v4.39.3
+        if: failure()
+        with:
+          sarif_file: trivy-results.sarif
diff --git a/AGENTS.md b/AGENTS.md
index 48574fb..8a17806 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -117,7 +117,8 @@ test/                          Pytest suite, mirroring the package. Mantid is no
 container/                     Dockerfile (mantid_python_script_lsp.D), FROM a pinned runner tag
 spike/                         Measurement scripts whose output is README.md's "Measurements"
                                section; spike/corpus/ is generated and gitignored — see "The corpus"
-.github/workflows/             tests.yml (PR checks), build-and-push.yml (main only, edits ../gitops)
+.github/workflows/             tests.yml (PR checks), build-and-push.yml (main only, edits ../gitops),
+                               image-scan.yml (nightly Trivy); dependabot.yml lives alongside them
 README.md                      Endpoints, contract ownership, measurements, configuration, how to run
 pyproject.toml, mypy.ini       Dependencies and ruff/mypy/pytest config
 ```
@@ -130,6 +131,10 @@ pyproject.toml, mypy.ini       Dependencies and ruff/mypy/pytest config
 | --- | --- | --- |
 | `tests.yml` | every push and PR | `pytest` with branch coverage, then `ruff format --check`, `ruff check`, `mypy --strict`. Plain Python, no Mantid — the suite stubs the framework, which is only possible because nothing imports it at module scope. |
 | `build-and-push.yml` | push to `main` only | Builds `container/mantid_python_script_lsp.D`, pushes to `ghcr.io/fiaisis/mantid-python-script-lsp`, then commits the new **digest** into the staging manifest in `../gitops`, like every other FIA service. |
+| `image-scan.yml` | nightly, and on demand | Builds the image and runs Trivy, failing on fixable vulnerabilities and uploading SARIF to the Security tab. Nightly because the findings are mostly the base image's Debian packages, and what changes is their disclosure dates. |
+
+Dependabot is configured as it is in `../FIA-API`: weekly `python-packages`, daily `action-packages`.
+Every action in these workflows is pinned by SHA, which is what lets that daily group do its job.
 
 Consequences an agent should know:
 
@@ -139,11 +144,10 @@ Consequences an agent should know:
 - The publish workflow edits `../gitops`, so it fails until that component's staging manifest exists at
   `components/mantid-python-script-lsp/envs/staging/mantid-python-script-lsp.yml` with a container named
   `mantid-python-script-lsp`. Creating those manifests is a prerequisite for a green first run on `main`.
-- Image scanning, scorecards, CodeQL and the corpus-in-CI job are not written yet. When they are, copy the
-  sibling repositories' workflow files rather than inventing a house style — they are already consistent
-  across FIA, and Dependabot's `action-packages` group expects the SHA-pinned actions both workflows here
-  use.
-- Dependabot is not configured for this repository yet.
+- CodeQL, dependency review, scorecards and the corpus-in-CI job are not written yet. When they are, copy
+  the sibling repositories' workflow files rather than inventing a house style — they are already
+  consistent across FIA, and Dependabot's `action-packages` group expects the SHA-pinned actions all
+  three workflows here already use.
 
 ## pyproject.toml — read this first
 
@@ -415,8 +419,8 @@ changed** — skip them for `.md`-only changes. When you do change Python, depen
 
 ## Handling Dependabot PRs
 
-Dependabot is not configured for this repo yet. When it is added, expect the two dangerous categories,
-and neither is a routine bump:
+Dependabot opens `python-packages` weekly and `action-packages` daily, per `.github/dependabot.yml`.
+Most are routine; two are not, and neither should be merged on a green check alone:
 
 - **The runner base image tag** (`ARG RUNNER_TAG` in `container/mantid_python_script_lsp.D`): changing
   it changes which names scripts may use, what pyflakes knows, and the cost of warm-up. Bump it

From 7b5d6bd76ee3c2f5b8e60786d7d80cb4279d054f Mon Sep 17 00:00:00 2001
From: Sam <samjones714@gmail.com>
Date: Fri, 6 Nov 2026 14:54:40 +0000
Subject: [PATCH 6/6] Add reduction-script corpus tests for CI and local corpus
 runs

---
 AGENTS.md           |   8 +--
 test/conftest.py    |  16 ++++-
 test/test_corpus.py | 157 ++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 176 insertions(+), 5 deletions(-)
 create mode 100644 test/test_corpus.py

diff --git a/AGENTS.md b/AGENTS.md
index 8a17806..a50785a 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -144,10 +144,10 @@ Consequences an agent should know:
 - The publish workflow edits `../gitops`, so it fails until that component's staging manifest exists at
   `components/mantid-python-script-lsp/envs/staging/mantid-python-script-lsp.yml` with a container named
   `mantid-python-script-lsp`. Creating those manifests is a prerequisite for a green first run on `main`.
-- CodeQL, dependency review, scorecards and the corpus-in-CI job are not written yet. When they are, copy
-  the sibling repositories' workflow files rather than inventing a house style — they are already
-  consistent across FIA, and Dependabot's `action-packages` group expects the SHA-pinned actions all
-  three workflows here already use.
+- CodeQL, dependency review and scorecards are not written yet. When they are, copy the sibling
+  repositories' workflow files rather than inventing a house style — they are already consistent across
+  FIA, and Dependabot's `action-packages` group expects the SHA-pinned actions all three workflows here
+  already use.
 
 ## pyproject.toml — read this first
 
diff --git a/test/conftest.py b/test/conftest.py
index 5d2e601..7ae46af 100644
--- a/test/conftest.py
+++ b/test/conftest.py
@@ -30,7 +30,21 @@
 # What the stub framework "exposes". Scripts in tests are written against these: the real service binds
 # roughly 1,800 names from the live framework, and the point of the stub is that a test states which
 # names exist rather than depending on a 2 GB package being installed.
-STUB_FRAMEWORK_NAMES = ("Load", "CreateSampleWorkspace", "AnalysisDataService", "MergeMD", "mtd", "np")
+STUB_FRAMEWORK_NAMES = (
+    "Load",
+    "SaveNexus",
+    "CreateSampleWorkspace",
+    "ConvertUnits",
+    "Rebin",
+    "Scale",
+    "BinMD",
+    "MergeMD",
+    "AnalysisDataService",
+    "ConfigService",
+    "config",
+    "mtd",
+    "np",
+)
 
 
 @pytest.fixture
diff --git a/test/test_corpus.py b/test/test_corpus.py
new file mode 100644
index 0000000..a03c099
--- /dev/null
+++ b/test/test_corpus.py
@@ -0,0 +1,157 @@
+"""Corpus tests: clean reduction-shaped scripts must produce zero diagnostics.
+
+Real facility reduction scripts (`spike/corpus/`) are gitignored because they contain instrument paths
+and configurations that do not belong in a public repository. In CI, we run synthetic scripts written
+in the exact shapes that real FIA autoreduction and live-data scripts take:
+
+- module-level `from mantid.simpleapi import *` with `mtd`, `config`, `ConfigService` and chained
+  algorithm calls;
+- `def execute():` wrappers importing `reduction_utils` or `isis_powder` helpers alongside explicit
+  `from mantid.simpleapi import (...)` blocks;
+- scripts that star-import unmodellable facility modules (`from isis_powder.routines.common import *`).
+
+When `spike/corpus/` has been generated locally from a live FIA API, the local corpus test also runs
+against every clean variant (`MERLIN.py`, `MERLIN_star.py`, `MERLIN_x2.py`, `MERLIN_x8.py`) and checks
+the deliberate error variants (`MERLIN_broken.py`, `MERLIN_small.py`).
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import pytest
+
+if TYPE_CHECKING:
+    from fastapi.testclient import TestClient
+
+CORPUS_DIR = Path(__file__).resolve().parent.parent / "spike" / "corpus"
+
+STAR_IMPORT_REDUCTION_SCRIPT = """\
+import os
+import sys
+from mantid.simpleapi import *
+import numpy as np
+
+config["default.facility"] = "ISIS"
+ConfigService.Instance().setString("default.instrument", "GENERIC")
+
+
+def reduce_run(run_number: int, output_dir: str) -> str:
+    raw_ws = Load(Filename=f"GENERIC{run_number}.nxs", OutputWorkspace="raw")
+    converted = ConvertUnits(InputWorkspace=raw_ws, Target="DeltaE", EMode="Direct")
+    rebinned = Rebin(InputWorkspace=converted, Params="-10,0.1,10")
+    scaled = Scale(InputWorkspace=rebinned, Factor=float(np.mean([1.0, 2.0])))
+    mtd.addOrReplace("reduced", scaled)
+    binned = BinMD(
+        InputWorkspace="reduced",
+        AlignedDim0="DeltaE,-10,10,100",
+    )
+    merged = MergeMD(InputWorkspaces=[binned])
+    out_path = os.path.join(output_dir, f"GENERIC{run_number}_reduced.nxs")
+    SaveNexus(InputWorkspace=merged, Filename=out_path)
+    return out_path
+"""
+
+EXECUTE_WRAPPER_SCRIPT = """\
+import importlib
+import os
+import time
+from datetime import datetime
+
+
+def execute() -> None:
+    import reduction_utils
+    from isis_powder.routines.common import load_current_variables
+
+    importlib.reload(reduction_utils)
+    from mantid.simpleapi import (
+        AnalysisDataService,
+        BinMD,
+        ConvertUnits,
+        Load,
+        MergeMD,
+        Rebin,
+        SaveNexus,
+        mtd,
+    )
+
+    variables = load_current_variables()
+    ws = Load(Filename=str(variables.get("run_path", "sample.nxs")))
+    ws = ConvertUnits(InputWorkspace=ws, Target="Wavelength")
+    ws = Rebin(InputWorkspace=ws, Params="0.5,0.01,5.0")
+    md = BinMD(InputWorkspace=ws, AlignedDim0="Wavelength,0.5,5.0,100")
+    merged = MergeMD(InputWorkspaces=[md])
+    mtd.addOrReplace("live_reduced", merged)
+    if AnalysisDataService.doesExist("live_reduced"):
+        SaveNexus(InputWorkspace="live_reduced", Filename=os.path.join("/tmp", f"out_{int(time.time())}.nxs"))
+"""
+
+FACILITY_STAR_IMPORT_SCRIPT = """\
+from mantid.simpleapi import *
+from isis_powder.routines.common import *
+
+
+def execute() -> object:
+    grouping = load_grouping_file("grouping.xml")
+    ws = Load(Filename="run.nxs")
+    mtd.addOrReplace("reduced", MergeMD(InputWorkspaces=[ws]))
+    return write_auto_reduction_output(ws, grouping)
+"""
+
+
+@pytest.mark.parametrize(
+    ("name", "script"),
+    [
+        ("star_import_reduction", STAR_IMPORT_REDUCTION_SCRIPT),
+        ("execute_wrapper", EXECUTE_WRAPPER_SCRIPT),
+        ("facility_star_import", FACILITY_STAR_IMPORT_SCRIPT),
+        ("repeated_at_scale", STAR_IMPORT_REDUCTION_SCRIPT * 6),
+    ],
+)
+def test_clean_synthetic_corpus_scripts_produce_zero_diagnostics(
+    warm_client: TestClient,
+    name: str,
+    script: str,
+) -> None:
+    """Every clean reduction-script shape in CI must come back with zero diagnostics."""
+    response = warm_client.post("/analyse", json={"content": script, "content_hash": name})
+
+    assert response.status_code == 200
+    body = response.json()
+    assert body["content_hash"] == name
+    assert body["parses"] is True
+    assert body["diagnostics"] == []
+    assert body["truncated"] is False
+
+
+def test_a_typo_in_a_corpus_script_is_still_caught_at_its_exact_call_site(warm_client: TestClient) -> None:
+    """Silence on clean scripts must not be achieved by muting the linter."""
+    broken = STAR_IMPORT_REDUCTION_SCRIPT.replace("BinMD(", "BinMQ(", 1)
+    expected_line = next(number for number, line in enumerate(broken.split("\n"), start=1) if "BinMQ(" in line)
+
+    response = warm_client.post("/analyse", json={"content": broken, "content_hash": "typo"})
+
+    assert response.status_code == 200
+    body = response.json()
+    assert body["parses"] is True
+    assert [(item["message"], item["start_line"], item["start_column"]) for item in body["diagnostics"]] == [
+        ("undefined name 'BinMQ'", expected_line, 14)
+    ]
+
+
+@pytest.mark.skipif(not CORPUS_DIR.is_dir(), reason="spike/corpus is generated locally and gitignored")
+@pytest.mark.parametrize("filename", ["MERLIN.py", "MERLIN_star.py", "MERLIN_x2.py", "MERLIN_x8.py"])
+def test_local_real_corpus_clean_variants_parse_cleanly(warm_client: TestClient, filename: str) -> None:
+    """When a local corpus is present, every clean variant must parse with no syntax errors."""
+    path = CORPUS_DIR / filename
+    if not path.is_file():
+        pytest.skip(f"{filename} not generated")
+
+    script = path.read_text(encoding="utf-8")
+    response = warm_client.post("/analyse", json={"content": script, "content_hash": filename})
+
+    assert response.status_code == 200
+    body = response.json()
+    assert body["parses"] is True
+    assert [item for item in body["diagnostics"] if item["source"] != "pyflakes"] == []