vnnlib-test-solver 2.0.0__py3-none-any.whl

vnnlib_test_solver/__init__.py

@@ -0,0 +1 @@
+__version__ = "2.0.0"

vnnlib_test_solver/assignments.py

@@ -0,0 +1,163 @@
+"""The section 5.3.1 command-line assignment format.
+
+The one place in this package where the output is compared byte for byte
+rather than merely parsed, so every rule below is separately testable and none
+of them is cosmetic::
+
+    A float32 [2,2]
+    0.5
+    0.3
+    0.4
+    0.2
+    B int32 [1]
+    -1
+
+Variables appear in the order the query declares them, across every network.
+The dimension form has no spaces inside the brackets. Values are row-major,
+one per line. The type is the specification's string form and it is the type
+the query *declares*: the standard's own example prints ``Real`` for four
+variables declared ``float32``, which is either an inconsistency in the
+example or a distinction between declared and analysis types that nothing
+else in the standard defines. The client confirmed the declared-type reading,
+and the one other implementation of this interface prints the declared type
+as well.
+
+Structure comes from the query and values come from configuration. A
+configuration that also described the variables could disagree with the query
+it was pointed at, and produce output that is well formed, plausible and
+wrong. That is the failure this split exists to make impossible.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from typing import Union
+
+from .errors import ConfigError
+from .querymodel import Declaration, QueryModel
+
+Value = Union[int, float]
+
+OPEN_BRACKET = "["
+CLOSE_BRACKET = "]"
+DIMENSION_SEPARATOR = ","
+"""Section 5.3.1's dimension form is [2,2]: no spaces anywhere inside it.
+
+Named rather than written inline because the separator and the brackets are
+the whole of a rule that a byte comparison exists to enforce, and a space
+added to any of them is invisible in a diff of the code and glaring in a diff
+of the output.
+"""
+
+
+def render(model: QueryModel, assignments: Mapping[str, Sequence[Value]]) -> str:
+    """Return the assignment block for ``model``, terminated by a newline.
+
+    Every declared variable appears, in declaration order. The mapping supplies
+    only values, keyed by variable name; nothing about which variables exist or
+    what shape they have is read from it.
+
+    Raises:
+        ConfigError: the supplied values do not fit the query - a variable is
+            missing, a variable is named that the query does not declare, or a
+            value list is not the length the declared shape requires.
+    """
+    _reject_mismatch(model, assignments)
+    lines = []
+    for declaration in model.declarations:
+        lines.append(header(declaration))
+        lines.extend(_format(value) for value in assignments[declaration.name])
+    return "".join(f"{line}\n" for line in lines)
+
+
+def header(declaration: Declaration) -> str:
+    """Render one variable's header line: name, declared type, dimensions."""
+    return f"{declaration.name} {declaration.element_type} {dimensions(declaration)}"
+
+
+def dimensions(declaration: Declaration) -> str:
+    """Render a shape as section 5.3.1 writes it: [2,2], no internal spaces."""
+    inner = DIMENSION_SEPARATOR.join(str(d) for d in declaration.shape)
+    return f"{OPEN_BRACKET}{inner}{CLOSE_BRACKET}"
+
+
+def size(declaration: Declaration) -> int:
+    """The number of values a declaration's shape requires, row-major.
+
+    A shape with no dimensions holds one value, which is what an empty product
+    gives, so this needs no special case.
+    """
+    total = 1
+    for dimension in declaration.shape:
+        total *= dimension
+    return total
+
+
+def _reject_mismatch(
+    model: QueryModel, assignments: Mapping[str, Sequence[Value]]
+) -> None:
+    """Refuse values that do not fit the query, before a byte is emitted.
+
+    All three mismatches are configuration errors rather than query errors: the
+    query parsed and means what it says, and it is the values pointed at it
+    that do not fit.
+
+    **A partial assignment is refused rather than printed.** A rule that
+    supplies values is claiming to give a satisfying assignment, and one that
+    omits a declared variable is not one. Printing it would produce a block
+    that is well formed, shorter than the standard requires, and impossible for
+    a consumer to tell apart from a complete one.
+    """
+    declared = {declaration.name: declaration for declaration in model.declarations}
+
+    # Sorted, because these are set differences and the message must not depend
+    # on iteration order. Declaration order would read better but cannot be
+    # recovered for a name the query never declared.
+    unknown = sorted(set(assignments) - set(declared))
+    if unknown:
+        raise ConfigError(
+            f"the rule assigns a value to {unknown[0]!r}, which {model.path} does not "
+            f"declare; a rule supplies values, and the query decides which variables "
+            f"exist"
+        )
+
+    missing = sorted(set(declared) - set(assignments))
+    if missing:
+        raise ConfigError(
+            f"the rule assigns no value to {missing[0]!r}, which {model.path} declares; "
+            f"an assignment covers every declared variable or a rule supplies none at "
+            f"all, because a partial assignment is not a satisfying assignment"
+        )
+
+    for name, declaration in declared.items():
+        expected = size(declaration)
+        supplied = len(assignments[name])
+        if supplied != expected:
+            raise ConfigError(
+                f"the rule assigns {supplied} value(s) to {name!r}, which "
+                f"{model.path} declares as {dimensions(declaration)} and so requires "
+                f"{expected}; values are row-major, one per position"
+            )
+
+
+def _format(value: Value) -> str:
+    """Render one value as the shortest string that round-trips to it.
+
+    ``str`` of a TOML integer gives no decimal point and ``str`` of a TOML
+    float keeps one, so ``-1`` and ``1.0`` both survive as the standard's
+    example writes them, and the integer/decimal distinction the configuration
+    chose is preserved. The standard specifies no numeric format, so nothing
+    here reformats beyond that.
+
+    **This is not the same as reproducing what the author typed**, and the
+    difference is worth stating in the one package whose whole claim is control
+    over its own bytes. Python's float repr is the shortest string that
+    round-trips, so a value written in scientific notation is normalised:
+    ``1e10`` renders as ``10000000000.0`` and ``1.5e-8`` as ``1.5e-08``. That
+    property is what a baseline actually needs - it is identical on every
+    platform and every run, where "as typed" would depend on the spelling
+    someone happened to choose. ``inf``, ``-inf`` and ``nan`` pass through as
+    those literals. A test that needs an exact byte sequence rather than a
+    numerically equal one uses ``raw_stdout``.
+    """
+    return str(value)

vnnlib_test_solver/cli.py

@@ -0,0 +1,504 @@
+"""Console entry point: command dispatch per section 5.1, global options per 5.2.
+
+Results go to stdout; the configuration note, warnings and every error go to
+stderr, which section 5.1 requires. Neither the name, the version nor any
+capability is held in code: all of them are answers, and answers come from
+configuration.
+
+Everything bound for stdout goes through ``emit``, which writes bytes. This is
+the only module that writes to stdout at all, so that rule is enforceable by
+reading one file.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from collections.abc import Sequence
+from typing import Any, NoReturn, Optional
+
+from .assignments import render as render_assignment
+from .config import (
+    ENV_VAR,
+    WORKING_DIRECTORY_NAME,
+    Config,
+    load_config,
+    resolve_config_source,
+)
+from .errors import ConfigError, QueryError, UsageError
+from .injection import Injection, resolve
+from .querymodel import QueryModel, read_query
+from .rules import Rule, select
+from .spec import SAT
+from .supports import (
+    CAPABILITIES,
+    MULTIPLE_INPUT_OUTPUT,
+    MULTIPLE_INPUT_OUTPUT_ALIAS,
+    render,
+    response_shape,
+)
+from .validation import soundness_warnings
+from .verify import (
+    VERIFY_COMMAND,
+    VERIFY_OPTIONS,
+    VerifyRequest,
+    add_arguments,
+    answer,
+    check_element_types,
+    check_network_mapping,
+    check_soundness,
+    request_from,
+)
+from .verify import warnings as verify_warnings
+
+PROGRAM = "vnnlibTestSolver"
+DEBUG_ENV_VAR = "VNNLIB_TEST_SOLVER_DEBUG"
+
+SUPPORTS_COMMAND = "supports"
+CAPABILITIES_COMMAND = "capabilities"
+
+GLOBAL_OPTIONS = ("--config", "--name", "--version")
+
+EXIT_OK = 0
+# The standard defines no exit codes. A usage mistake (bad flags, no command,
+# unknown capability) and a configuration mistake (bad TOML, an unsound claim)
+# are different conditions and carry different codes.
+EXIT_USAGE_ERROR = 1
+EXIT_CONFIG_ERROR = 2
+
+
+class _UsageErrorParser(argparse.ArgumentParser):
+    """Exits with EXIT_USAGE_ERROR rather than argparse's own hard-coded 2.
+
+    A mutually-exclusive-group conflict (``--name --version``, or two capability
+    flags at once) is caught inside argparse itself and never reaches main() -
+    the base ``error()`` always calls ``self.exit(2, ...)``. Overriding it here,
+    on the top-level parser, is what lets every usage mistake share one code:
+    ``add_subparsers()`` defaults new sub-parsers to the parent's own class, so
+    ``supports`` and its hidden alias inherit this without being told to.
+    """
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        # argparse resolves any unambiguous prefix to its full option, which
+        # would answer --onnx-e as --onnx-element-types. Section 5.4 defines
+        # eleven exact spellings and this package publishes exactly those, so an
+        # abbreviation is an option that does not exist, not a shorthand.
+        kwargs.setdefault("allow_abbrev", False)
+        super().__init__(*args, **kwargs)
+
+    def error(self, message: str) -> NoReturn:
+        self.print_usage(sys.stderr)
+        self.exit(EXIT_USAGE_ERROR, f"{self.prog}: error: {message}\n")
+
+
+def emit(text: str) -> None:
+    """Write text to stdout as bytes, with no line-ending translation.
+
+    ``print`` and ``sys.stdout`` are text-mode streams, and text mode on Windows
+    turns every newline into a carriage return and a newline. Nothing here asks
+    for that, and section 5.3.1 output is compared byte for byte: bytes that
+    depend on the machine that produced them are not a baseline. A consumer
+    splitting the result line on newlines would also get a trailing carriage
+    return inside the token, so ``sat`` would not equal ``sat``.
+
+    Writing through the underlying binary buffer is what makes the bytes the
+    same everywhere. The text layer is flushed first so that nothing it holds
+    can appear after bytes written past it.
+
+    stderr is deliberately left in text mode. It carries diagnostic prose rather
+    than a format the standard specifies, and argparse writes some of it through
+    a stream this code does not own.
+    """
+    sys.stdout.flush()
+    sys.stdout.buffer.write(text.encode("utf-8"))
+    sys.stdout.buffer.flush()
+
+
+def emit_line(text: str) -> None:
+    """Emit one line, terminated by a single LF on every platform."""
+    emit(f"{text}\n")
+
+
+def inject_stderr(injection: Injection) -> None:
+    """Write the configured noise, before the answer rather than after it.
+
+    Ordering is a decision here rather than something implied. Writing first is
+    what a solver logging its progress would do, it is the order the consuming
+    interface's own stub solvers use, and it is the arrangement that actually
+    proves the two streams do not interfere: noise written before an answer has
+    to survive the answer being written after it, on a different stream, without
+    either being corrupted.
+
+    For ``verify`` this happens before the configured delay is waited out, so a
+    caller reading both streams sees the noise while the solver is still
+    pretending to think, rather than in one burst at the end.
+    """
+    if injection.stderr is not None:
+        print(injection.stderr, file=sys.stderr)
+
+
+def deliver(text: str, injection: Injection) -> int:
+    """Write the answer, honour any crash, and return the exit code.
+
+    ``raw_stdout`` **replaces** the answer rather than adding to it. That is
+    what makes a result line that is not one of the four, a truncated capability
+    response, and no output at all reachable from configuration, which is the
+    whole point of the control - and it is one rule with no special cases rather
+    than a list of what it does and does not override.
+
+    A crash happens **after** the bytes are written and flushed, so that both a
+    crash carrying output and a crash carrying none are configurable: the second
+    is an empty ``raw_stdout`` beside it. The reverse order would make the first
+    unreachable.
+    """
+    # Bound to a local rather than tested through a property, so that the
+    # None case narrows for the type checker in the same place a reader sees
+    # it narrow.
+    replacement = injection.raw_stdout
+    emit(text if replacement is None else replacement)
+    if injection.crash:
+        _crash()
+    return injection.exit_code if injection.exit_code is not None else EXIT_OK
+
+
+def _crash() -> NoReturn:
+    """Terminate abnormally rather than exiting.
+
+    ``os.abort`` raises ``SIGABRT`` on a Unix-like system, which is what the
+    consuming process runner distinguishes from a normal exit: it reports the
+    child as not having exited normally and carries no exit status. On Windows
+    there are no real signals and the process ends with the operating system's
+    own fast-fail status instead. Both were measured on this machine rather than
+    read about, and the test that covers this asserts the right one per platform
+    rather than merely a non-zero code.
+
+    Both streams are flushed first. ``os.abort`` bypasses interpreter shutdown
+    entirely, so anything still buffered is simply lost, and a crash that also
+    silently dropped the output configured beside it would be testing something
+    other than what the configuration says.
+    """
+    sys.stdout.flush()
+    sys.stderr.flush()
+    os.abort()
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = _UsageErrorParser(
+        prog=PROGRAM,
+        description=(
+            "A configurable test solver implementing the VNN-LIB command-line interface."
+        ),
+    )
+    parser.add_argument(
+        "--config",
+        metavar="PATH",
+        help=(
+            "configuration file to answer from; otherwise "
+            f"${ENV_VAR}, then ./{WORKING_DIRECTORY_NAME}. There is no default: "
+            "with none of the three, the run is refused"
+        ),
+    )
+    globals_group = parser.add_mutually_exclusive_group()
+    globals_group.add_argument(
+        "--name", action="store_true", help="print the solver's full name"
+    )
+    globals_group.add_argument(
+        "--version", action="store_true", help="print the solver version"
+    )
+
+    commands = parser.add_subparsers(dest="command", metavar="<command>")
+    # Every sub-parser is built through add_parser, which copies the parent's own
+    # class: each one inherits the usage exit code and the refusal of abbreviated
+    # options without being told to.
+    add_arguments(
+        commands.add_parser(
+            VERIFY_COMMAND,
+            help="answer a query about a network",
+            description="Answer one VNN-LIB query, per standard section 5.3.",
+        )
+    )
+    _add_capability_flags(
+        commands.add_parser(
+            SUPPORTS_COMMAND,
+            help="report whether the solver supports a capability",
+            description="Report one capability, per standard section 5.4.",
+        )
+    )
+    # Section 5.1 names this command 'capabilities' while section 5.4 defines it as
+    # 'supports'. Both are accepted so that neither reading of the standard breaks a
+    # consumer; the alias is given no help text, so only one spelling is documented.
+    _add_capability_flags(commands.add_parser(CAPABILITIES_COMMAND))
+    return parser
+
+
+def _add_capability_flags(command: argparse.ArgumentParser) -> None:
+    """Declare the eleven capability flags, of which exactly one may be given."""
+    group = command.add_mutually_exclusive_group()
+    for capability in CAPABILITIES:
+        group.add_argument(
+            capability,
+            dest="capability",
+            action="store_const",
+            const=capability,
+            help=response_shape(capability),
+        )
+    group.add_argument(
+        MULTIPLE_INPUT_OUTPUT_ALIAS,
+        dest="capability",
+        action="store_const",
+        const=MULTIPLE_INPUT_OUTPUT,
+        help=argparse.SUPPRESS,
+    )
+
+
+def main(argv: Optional[Sequence[str]] = None) -> int:
+    parser = build_parser()
+    args, unrecognised = parser.parse_known_args(argv)
+
+    if unrecognised:
+        return _report_unrecognised(parser, args, unrecognised)
+
+    if args.command is not None and (args.name or args.version):
+        print(
+            f"{PROGRAM}: --name and --version are global options and cannot be "
+            f"combined with the {args.command} command",
+            file=sys.stderr,
+        )
+        return EXIT_USAGE_ERROR
+
+    try:
+        source = resolve_config_source(args.config)
+        config = load_config(source)
+    except ConfigError as exc:
+        print(f"{PROGRAM}: {exc}", file=sys.stderr)
+        return EXIT_CONFIG_ERROR
+
+    if os.environ.get(DEBUG_ENV_VAR):
+        print(
+            f"{PROGRAM}: configuration read from {source.origin}: {source.path}",
+            file=sys.stderr,
+        )
+
+    # A soundness claim the configuration contradicts is a property of the file, not
+    # of the command asked for, so it is reported whichever command runs. It is a
+    # warning: the run still answers, and stdout is untouched.
+    for warning in soundness_warnings(config.capabilities, config.soundness):
+        print(f"{PROGRAM}: warning: {warning}", file=sys.stderr)
+
+    # Resolved once, here, so that every path which delivers an answer takes
+    # the same controls from the same place. A run that is refused never gets
+    # this far, which is deliberate: a solver that cannot report its own errors
+    # because a configuration told it to report something else is not a baseline.
+    injection = resolve(config.injection)
+
+    if args.name:
+        inject_stderr(injection)
+        return deliver(f"{config.solver.name}\n", injection)
+
+    if args.version:
+        inject_stderr(injection)
+        return deliver(f"{config.solver.version}\n", injection)
+
+    if args.command == VERIFY_COMMAND:
+        return _run_verify(args, config)
+
+    if args.command is not None:
+        return _run_supports(args, config, injection)
+
+    parser.print_usage(sys.stderr)
+    print(f"{PROGRAM}: no global option or command given", file=sys.stderr)
+    return EXIT_USAGE_ERROR
+
+
+def _run_verify(args: argparse.Namespace, config: Config) -> int:
+    try:
+        request = request_from(args)
+    except UsageError as exc:
+        print(f"{PROGRAM}: {exc}", file=sys.stderr)
+        return EXIT_USAGE_ERROR
+
+    for warning in verify_warnings(request):
+        print(f"{PROGRAM}: warning: {warning}", file=sys.stderr)
+
+    try:
+        rule = select(config, request.query)
+    except ConfigError as exc:
+        print(f"{PROGRAM}: {exc}", file=sys.stderr)
+        return EXIT_CONFIG_ERROR
+
+    # Everything that can refuse the run happens here, before the result is
+    # printed and before any delay is waited out, so that a run which cannot be
+    # answered fails with nothing on stdout rather than with a result line
+    # already committed to it. Section 5.1 puts errors on stderr; a half-written
+    # answer is not something a consumer can be expected to unpick.
+    try:
+        model = _query_model_for(request, rule)
+        if model is not None:
+            # Section 5.3.2's three conditions, in the order the clause lists
+            # them. The order is fixed rather than incidental: a run that gets
+            # two of them wrong must report the same one every time, or a test
+            # asserting which condition it triggered depends on nothing.
+            check_network_mapping(request, model)
+            check_element_types(model, rule.model_element_types)
+            check_soundness(model, config.soundness.get("sound-for"))
+        assignment = _assignment_for(model, rule)
+    except (QueryError, UsageError) as exc:
+        print(f"{PROGRAM}: {exc}", file=sys.stderr)
+        return EXIT_USAGE_ERROR
+    except ConfigError as exc:
+        print(f"{PROGRAM}: {exc}", file=sys.stderr)
+        return EXIT_CONFIG_ERROR
+
+    # Nothing above this line can be reached by a run that will be refused, so
+    # this is where deliberate misbehaviour starts: the noise goes out before
+    # the solver spends its configured thinking time, not after.
+    injection = resolve(config.injection, rule)
+    inject_stderr(injection)
+
+    # Section 5.3.1: the result is the first line of stdout, and the assignment
+    # block follows it when there is one.
+    #
+    # The result is asked for after the block is built, not before, because a
+    # rule whose delay outlasts the caller's timeout answers timed-out however
+    # it was configured, and an assignment printed under that would contradict
+    # the line above it. Building it either way keeps a configuration that does
+    # not fit its query failing identically whether or not the clock ran out.
+    #
+    # The delay is waited out even when the output is about to be replaced. The
+    # delay is how long the solver claims to think and the replacement is what
+    # it prints, so they are independent, and keeping them so is what lets a
+    # caller test a deadline being reached and unparseable output arriving in
+    # the same run.
+    result = answer(request, rule)
+    text = f"{result}\n"
+    if assignment and result == SAT:
+        text += assignment
+    return deliver(text, injection)
+
+
+def _query_model_for(request: VerifyRequest, rule: Rule) -> Optional[QueryModel]:
+    """Read the query, but only when the run gives a reason to open it.
+
+    Which result a rule gives is decided by the query file's name, so a bare
+    invocation is answerable without the file existing at all. That is not an
+    oversight: it is what lets a caller exercise result handling, rule
+    selection and deadline behaviour without maintaining a corpus of real
+    queries and real models, and it is published as a property of this binary.
+
+    Three things ask for the file to be opened, and they are one policy rather
+    than three rules: the run has handed the solver something whose other half
+    is in the query. A ``--network`` argument gives it a mapping to check
+    against the declarations, which is section 5.3.2's first error condition.
+    Assignment values give it half an assignment, whose other half - names,
+    types, dimensions and order - is in the query. Model element types give it
+    a claim about what the models expose, which means nothing until it is set
+    beside what the query declares, and which would otherwise be a
+    configuration key that silently did nothing.
+
+    Section 5.3.2's third condition, unsound analysis without consent, is
+    deliberately **not** on that list even though it needs the query too. It is
+    driven by a configuration table rather than by anything the run supplies,
+    so honouring it unconditionally would make a real query file mandatory for
+    every invocation of every configuration that mentions soundness. Each
+    entry above is opted into by the rule or the command line that asks for it,
+    which is why none of them changes what an existing configuration does.
+
+    *Assumption*, recorded as an open question: applied to the letter, section
+    5.3.2 would have every invocation read the query, since the declarations
+    are the only source of the required set. That reading would remove the
+    affordance above and make a real query file mandatory for every test anyone
+    writes against this binary. Both directions of the error stay triggerable
+    on demand under the narrower reading, which is the reason a test solver
+    carries the condition at all.
+    """
+    wants_assignment = bool(rule.assignments) and rule.result == SAT
+    if not request.networks and not wants_assignment and not rule.model_element_types:
+        return None
+    return read_query(request.query)
+
+
+def _assignment_for(model: Optional[QueryModel], rule: Rule) -> str:
+    """Return the assignment block to print after the result, or nothing.
+
+    Section 5.3.1 attaches the assignment to ``sat`` and to no other result, so
+    a rule carrying values for a result that is not ``sat`` prints none of them.
+    They are not an error: a configuration is free to describe a satisfying
+    assignment for a query it also has a rule answering ``unsat`` for, and
+    refusing that would be policing something the standard leaves alone.
+    """
+    if model is None or not rule.assignments or rule.result != SAT:
+        return ""
+    return render_assignment(model, rule.assignments)
+
+
+def _run_supports(args: argparse.Namespace, config: Config, injection: Injection) -> int:
+    if args.capability is None:
+        print(
+            f"{PROGRAM}: {args.command} needs exactly one capability; the standard "
+            f"defines {', '.join(CAPABILITIES)}",
+            file=sys.stderr,
+        )
+        return EXIT_USAGE_ERROR
+
+    try:
+        # Named 'response' rather than 'answer' so it cannot be mistaken for the
+        # verify command's answer(), which is imported into this module.
+        response = render(args.capability, config)
+    except ConfigError as exc:
+        print(f"{PROGRAM}: {exc}", file=sys.stderr)
+        return EXIT_CONFIG_ERROR
+
+    inject_stderr(injection)
+    # render() already terminates each line, so the text is delivered whole
+    # rather than a line at a time.
+    return deliver(response, injection)
+
+
+def _report_unrecognised(
+    parser: argparse.ArgumentParser,
+    args: argparse.Namespace,
+    unrecognised: Sequence[str],
+) -> int:
+    """Report the first unrecognised token, in the terms of wherever it appeared.
+
+    Each command draws its arguments from a different closed set, so the message
+    names the set the token was measured against: capabilities after supports,
+    section 5.3's options after verify. argparse would otherwise report every one
+    of them as an unrecognised argument, which says nothing about the set at all.
+    """
+    offender = unrecognised[0]
+
+    if args.command is None:
+        parser.print_usage(sys.stderr)
+        message = f"unrecognised option {offender!r}"
+    elif offender in GLOBAL_OPTIONS:
+        message = (
+            f"{offender} is a global option and must be given before the "
+            f"{args.command} command"
+        )
+    elif args.command == VERIFY_COMMAND:
+        message = _unrecognised_for_verify(offender)
+    else:
+        message = (
+            f"unknown capability {offender!r}; the standard defines "
+            f"{', '.join(CAPABILITIES)}"
+        )
+
+    print(f"{PROGRAM}: {message}", file=sys.stderr)
+    return EXIT_USAGE_ERROR
+
+
+def _unrecognised_for_verify(offender: str) -> str:
+    """Distinguish an option verify does not define from a second query file.
+
+    Section 5.3 gives verify one positional argument, so a token that does not
+    look like an option is a second file rather than a misspelling, and saying so
+    is more use than listing the options it is not.
+    """
+    if offender.startswith("-"):
+        return (
+            f"unknown option {offender!r} for the {VERIFY_COMMAND} command; the "
+            f"standard defines {', '.join(VERIFY_OPTIONS)}"
+        )
+    return f"{VERIFY_COMMAND} takes exactly one query file and {offender!r} is a second"