solver-support 0.2.2__tar.gz → 0.3.1__tar.gz

{solver_support-0.2.2/solver_support.egg-info → solver_support-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: solver-support
-Version: 0.2.2
+Version: 0.3.1
 Summary: Generic Conjure / Savile Row / Fast Downward / SymK / ENHSP / UPF solver pipeline
 Author: András Salamon
 License-Expression: BSD-3-Clause
@@ -29,12 +29,13 @@ Dynamic: license-file
 # solver-support
 
 A generic, domain-agnostic pipeline for running constraint-modelling and
-planning solvers: **Conjure** / **Savile Row** (+ SAT/CP backends), **Fast
-Downward**, **SymK**, **ENHSP**, and **UPF**-constructed models. It handles the
-mechanics that every such run needs — building solver command lines from a model
-registry, spawning subprocesses with timeouts and clean teardown, naming the
-per-run files, parsing solver output into a uniform timing / cost-layer model,
-and driving the horizon (increasing-difficulty) loop.
+planning solvers: **Conjure** / **Savile Row** (driving a SAT solver, **Minion**,
+**OR-Tools CP-SAT**, **Gecode** or **Chuffed**), **Fast Downward**, **SymK**,
+**ENHSP**, and **UPF**-constructed models. It handles the mechanics that every
+such run needs — building solver command lines from a model registry, spawning
+subprocesses with timeouts and clean teardown, naming the per-run files, parsing
+solver output into a uniform timing / cost-layer model, and driving the horizon
+(increasing-difficulty) loop.
 
 It carries **no** notion of any particular problem domain or objective. A
 consumer supplies:
@@ -47,14 +48,17 @@ consumer supplies:
 
 ## Status
 
-**Alpha.** The pipeline is in day-to-day use by two consumers and is covered by
-its own test suite, but this is the first public release and the API may still
-shift between 0.x versions.
+**Alpha.** The pipeline is in day-to-day use by several consumers and is covered
+by its own test suite, but the API may still shift between 0.x releases. Each
+release's changes are listed on the
+[releases page](https://github.com/ott2/solver-support/releases).
 
-The package ships **unwired**: a bare `import solver_support` gives a pipeline
-that resolves no model registry and interprets no objective, because it has no
-way to guess either. A consumer registers its scoring, registry paths, warning
-logger and UPF CLI once, before first use.
+The package ships **unwired**, by design and on every release: a bare
+`import solver_support` gives a pipeline that resolves no model registry and
+interprets no objective, because it has no way to guess either. Constructing a
+`ModelRegistry` *raises* rather than falling back on a guess. A consumer
+registers its scoring, registry paths, warning logger and UPF CLI once, before
+first use — see [Usage](#usage).
 
 ## Installation
 
@@ -63,7 +67,8 @@ pip install solver-support
 ```
 
 Requires Python 3.9 or newer (3.9.6 is the system Python on macOS, and is
-supported deliberately). The only runtime dependencies are `psutil` and `PyYAML`.
+supported deliberately — each release is built and tested against it). The only
+runtime dependencies are `psutil` and `PyYAML`.
 
 ## Usage
 
@@ -83,15 +88,18 @@ extraction, warning logger, UPF CLI — with a worked example.
 
 ## Development
 
-Clone and install editable. A consumer under development alongside it is
-normally installed into the same virtualenv, so both are importable and edits to
-either take effect immediately:
+To work on this package, clone and install it editable:
 
 ```bash
 git clone https://github.com/ott2/solver-support
 pip install -e solver-support
 ```
 
+Consumers pin a **released** version from PyPI rather than the working tree, so a
+change here reaches them only when it is released. To try an unreleased change
+against a consumer, install this editable into that consumer's environment
+deliberately — it is not the default arrangement.
+
 ## Tests
 
 `pytest tests/` — the core's own suite, and the home for solver-level

{solver_support-0.2.2 → solver_support-0.3.1}/README.md

@@ -1,12 +1,13 @@
 # solver-support
 
 A generic, domain-agnostic pipeline for running constraint-modelling and
-planning solvers: **Conjure** / **Savile Row** (+ SAT/CP backends), **Fast
-Downward**, **SymK**, **ENHSP**, and **UPF**-constructed models. It handles the
-mechanics that every such run needs — building solver command lines from a model
-registry, spawning subprocesses with timeouts and clean teardown, naming the
-per-run files, parsing solver output into a uniform timing / cost-layer model,
-and driving the horizon (increasing-difficulty) loop.
+planning solvers: **Conjure** / **Savile Row** (driving a SAT solver, **Minion**,
+**OR-Tools CP-SAT**, **Gecode** or **Chuffed**), **Fast Downward**, **SymK**,
+**ENHSP**, and **UPF**-constructed models. It handles the mechanics that every
+such run needs — building solver command lines from a model registry, spawning
+subprocesses with timeouts and clean teardown, naming the per-run files, parsing
+solver output into a uniform timing / cost-layer model, and driving the horizon
+(increasing-difficulty) loop.
 
 It carries **no** notion of any particular problem domain or objective. A
 consumer supplies:
@@ -19,14 +20,17 @@ consumer supplies:
 
 ## Status
 
-**Alpha.** The pipeline is in day-to-day use by two consumers and is covered by
-its own test suite, but this is the first public release and the API may still
-shift between 0.x versions.
+**Alpha.** The pipeline is in day-to-day use by several consumers and is covered
+by its own test suite, but the API may still shift between 0.x releases. Each
+release's changes are listed on the
+[releases page](https://github.com/ott2/solver-support/releases).
 
-The package ships **unwired**: a bare `import solver_support` gives a pipeline
-that resolves no model registry and interprets no objective, because it has no
-way to guess either. A consumer registers its scoring, registry paths, warning
-logger and UPF CLI once, before first use.
+The package ships **unwired**, by design and on every release: a bare
+`import solver_support` gives a pipeline that resolves no model registry and
+interprets no objective, because it has no way to guess either. Constructing a
+`ModelRegistry` *raises* rather than falling back on a guess. A consumer
+registers its scoring, registry paths, warning logger and UPF CLI once, before
+first use — see [Usage](#usage).
 
 ## Installation
 
@@ -35,7 +39,8 @@ pip install solver-support
 ```
 
 Requires Python 3.9 or newer (3.9.6 is the system Python on macOS, and is
-supported deliberately). The only runtime dependencies are `psutil` and `PyYAML`.
+supported deliberately — each release is built and tested against it). The only
+runtime dependencies are `psutil` and `PyYAML`.
 
 ## Usage
 
@@ -55,15 +60,18 @@ extraction, warning logger, UPF CLI — with a worked example.
 
 ## Development
 
-Clone and install editable. A consumer under development alongside it is
-normally installed into the same virtualenv, so both are importable and edits to
-either take effect immediately:
+To work on this package, clone and install it editable:
 
 ```bash
 git clone https://github.com/ott2/solver-support
 pip install -e solver-support
 ```
 
+Consumers pin a **released** version from PyPI rather than the working tree, so a
+change here reaches them only when it is released. To try an unreleased change
+against a consumer, install this editable into that consumer's environment
+deliberately — it is not the default arrangement.
+
 ## Tests
 
 `pytest tests/` — the core's own suite, and the home for solver-level

{solver_support-0.2.2 → solver_support-0.3.1}/docs/solver-runner.md

@@ -37,13 +37,13 @@ SolverResult(command, returncode, stdout, stderr, duration,
 
 Three easily-confused numbers:
 
-- `default_timeout` (a `SolverRunner` parameter) — the *limit*;
+- `timeout` (a `SolverRunner` parameter) — the *limit*;
 - `duration` (a `SolverResult` field) — the *actual* time it ran, whether it
   finished or was killed;
 - `timed_out` (a `SolverResult` field) — whether that limit was hit.
 
 ```python
-runner = SolverRunner(default_timeout=10.0)
+runner = SolverRunner(timeout=10.0)
 
 runner.run(['sleep', '3'])    # duration ~3.0,  timed_out False, returncode 0
 runner.run(['sleep', '15'])   # duration ~10.0, timed_out True,  returncode -1
@@ -87,7 +87,7 @@ SolverResult(ls /nonexistent) -> FAILED (rc=1, t=0.01s)
 ```python
 from solver_support import SolverRunner
 
-runner = SolverRunner(default_timeout=30.0)
+runner = SolverRunner(timeout=30.0)
 result = runner.run(['savilerow', 'model.eprime', 'problem.param'])
 
 if result.timed_out:

{solver_support-0.2.2 → solver_support-0.3.1}/docs/timing-model.md

@@ -146,6 +146,68 @@ wires only the objective-file route will find continue-scan stops at the first
 solving horizon on those backends instead of improving — wire
 `set_raw_objective_from_solution` to use them for optimisation models.
 
+#### The three time limits, and how they relate
+
+A Savile Row run is bounded three times over, and the three are **not**
+interchangeable. Getting the relationship wrong is silent, so it is worth
+stating once:
+
+| limit | set by | what it actually bounds |
+|---|---|---|
+| `-timelimit T` | `build_savilerow_command(timeout=T)` | tailoring. Nominally translation *plus* solving, but Savile Row stops binding it once a solver is running |
+| the solver's own (`--time=S`, …) | `build_savilerow_command(solver_timeout=S)` | search |
+| the external kill | `SolverRunner(timeout=…)` | the whole process tree |
+
+**The first two are consecutive, so they add.** Savile Row tailors, and only
+then launches the solver, so the wall clock the pair permits is `T + S` — not
+`max(T, S)`. Left unsplit (`S` defaulting to `T`) that is `2T`, which is why an
+external kill set at `T` can fire while the toolchain is still inside the limits
+it was given.
+
+**An early kill costs every statistic, not just the tail.** Savile Row
+accumulates `SATVars`, `SATClauses`, `SolverNodes` and the
+`SavileRowTotalTime` / `SolverTotalTime` split in memory and writes the `.info`
+once, after the solver returns. Kill the tree and the output directory holds an
+`.eprime` and perhaps an `.eprime-minion`, never an `.eprime-info`, so
+`extract_savilerow_info` has nothing to read and the run cannot say even whether
+it reached the solver.
+
+So size the external kill with `savilerow_backstop(T, S)` — `T + S` plus grace
+for the flush — and it comes to mean "the toolchain ignored its limits", a
+genuine fault rather than an ordinary and lossy way for a run to end.
+
+**To hold a run to a wall-clock budget, shrink the pair, not the backstop.**
+Give the solver `S = T - (what tailoring will cost)`. The core picks no reserve
+policy: a horizon scan can estimate from the previous horizon's
+`SavileRowTotalTime`, a single-shot run has nothing to estimate from, and only
+the caller knows which it is.
+
+#### Verdicts: refuted vs gave up
+
+`No solution found.` is what Savile Row prints **both** when the solver proved
+there is none and when it stopped at its own limit without deciding, and
+`solution_found` is False for both. The first is a result; the second
+establishes nothing. `SolverStatsExtractor.savilerow_verdict` separates them and
+`_record_savilerow_times` records the answer on the phase as `verdict`:
+
+| verdict | evidence | meaning |
+|---|---|---|
+| `sat` / `unsat` | `SolverSatisfiable` present | decided (`proven_optimal` too, on optimisation models) |
+| `unknown` | absent, with `verdict_reason` | `solver-limit`, `tailoring-limit`, `memory`, `encoding-limit`, or `unexplained` |
+| `error` | `SavileRowUncaughtException` | Savile Row itself failed |
+| `killed` | no `.info` at all | recorded by the caller, from the phase's `timed_out` / `launch_failed` |
+
+Decidedness keys on `SolverSatisfiable` being **present**, deliberately not on
+the solver having run: Savile Row can settle an instance during tailoring and
+never invoke a solver, leaving `SolverTotalTime: 0` beside a perfectly good
+verdict. Testing "did the solver run?" reports every one of those as undecided.
+
+**A horizon's `unsat` is about the bound, not the problem.** It means "not at
+this horizon", never "not at all" — refuting horizons 1..N says nothing about
+N+1. Only the registry knows which models decide the problem itself
+(`get_proves_unsat`), which is why the run-level `outcome` is derived in
+`RunSummary.finalize` and never aggregated from these.
+
 ### Fast Downward / SymK (PDDL models)
 
 - **Shape**: not a horizon scan — one `solving` phase whose A\* (blind) / symbolic
@@ -210,15 +272,46 @@ solving horizon on those backends instead of improving — wire
 - **Split is Savile-Row-only and best-effort.** `savilerow_time` / `solver_time`
   are `None` for planners and for any Savile Row horizon whose `.info` was
   missing.
+- **In-band limits add; the external kill must sit above their sum.** See "the
+  three time limits" above. `savilerow_backstop` derives it from the same
+  numbers the builder gets.
+- **A clean exit is not an answer.** A solver given its own limit stops *itself*
+  and exits 0, so every phase of a fruitless run can succeed. Run success is
+  decided by `outcome`, never by exit codes.
+
+## outcomes
+
+`final_status` answers two questions at once — what was learned, and why the run
+stopped — so `RunSummary.finalize` records them separately. `final_status` keeps
+its meaning; these sit alongside it.
+
+| field | values |
+|---|---|
+| `outcome` | `solved` / `unsat` / `unknown` / `error` |
+| `stop_reason` | `complete` / `time` / `horizons` / `interrupt` / `error` |
+
+`success` is `outcome in {solved, unsat}`: **a run succeeded if it produced a
+definitive answer in the budget it was given.** A proof that no solution exists
+answers the question as surely as a solution does, even though the planner that
+produced it exits non-zero.
+
+`unsat` requires the caller to pass `finalize(..., proves_unsat=True)`, normally
+from the registry's `get_proves_unsat`. The core cannot tell from the output — a
+bounded CP model and a complete planner print the same thing — and left False no
+run is ever concluded unsat, which understates rather than overstates what was
+proved. A status that stopped early (`timeout`, `hlim`, `stopped`) is never
+`unsat` however complete the model.
 
 ## what the core owns
 
 | concern | location |
 |---------|----------|
 | per-solver stat parsers, cost-layer assembly, dispatch | `solver_stats.py` |
+| per-run Savile Row verdict (refuted vs gave up) | `solver_stats.py` (`savilerow_verdict`) |
 | Savile Row `.info` split recording (per horizon) | `solver_horizon.py` (`_record_savilerow_times`) |
 | stats attached to a phase after each solve | `solver_runner.py`, `solver_horizon.py` |
-| the phase model (`RunSummary` / `PhaseResult`) | `run_summary.py` |
+| the phase model (`RunSummary` / `PhaseResult`), outcome and success | `run_summary.py` |
+| relating the in-band limits to the external kill | `command_builders.py` (`savilerow_backstop`) |
 
 Turning these per-phase stats into a unified per-horizon curve for display, a
 single "preprocess" baseline, and plots is the **consumer's** job — it reads the

{solver_support-0.2.2 → solver_support-0.3.1}/pyproject.toml

@@ -11,10 +11,16 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "solver-support"
-# Single-sourced from solver_support.__version__, so a release bump touches one
-# line and the installed metadata can never disagree with what the package
-# reports at runtime.
-dynamic = ["version"]
+# The single source of the version. `solver_support.__version__` reads it back
+# from the installed distribution metadata, so there is no literal in the
+# package to drift from this one.
+#
+# Static rather than `dynamic = ["version"]` with a `{attr = ...}` pointing into
+# the package: PEP 621 treats `version` as a static field, and `dynamic` is the
+# escape hatch for a version that genuinely cannot be known without building.
+# Ours can. Carrying a `.devN` suffix between releases keeps the working tree
+# from claiming a version that is already tagged and published.
+version = "0.3.1"
 description = "Generic Conjure / Savile Row / Fast Downward / SymK / ENHSP / UPF solver pipeline"
 readme = "README.md"
 requires-python = ">=3.9"
@@ -72,9 +78,6 @@ dev = [
 [tool.setuptools]
 zip-safe = false
 
-[tool.setuptools.dynamic]
-version = {attr = "solver_support.__version__"}
-
 [tool.setuptools.packages.find]
 include = ["solver_support*"]
 

{solver_support-0.2.2 → solver_support-0.3.1}/solver_support/__init__.py

@@ -13,7 +13,28 @@ unconfigured pipeline. A consumer registers its scoring (see :mod:`objective`)
 and its packaging paths (see :mod:`model_registry`) once at its own import time.
 """
 
-__version__ = "0.2.2"
+# Read back from the installed distribution metadata; the version itself is
+# declared once, in pyproject.toml. There is deliberately no literal here to
+# drift from it - the failure being avoided is a release where the metadata says
+# one thing and `__version__` another, each individually plausible and nothing
+# catching the disagreement.
+#
+# Resolved eagerly rather than behind a PEP 562 `__getattr__`: the lookup scans
+# sys.path for a matching .dist-info, which costs a fraction of a millisecond,
+# and this module already imports psutil, PyYAML and every solver backend below.
+# Deferring it would save nothing measurable against that.
+#
+# The fallback fires only in a source tree that was never installed. Note an
+# *editable* install pins its .dist-info at install time, so a checkout whose
+# version has moved on still reports the older one here until it is reinstalled
+# - the price of single-sourcing from metadata rather than from a literal.
+try:
+    from importlib.metadata import PackageNotFoundError as _PackageNotFoundError
+    from importlib.metadata import version as _version
+
+    __version__ = _version("solver-support")
+except _PackageNotFoundError:  # a source tree, never installed
+    __version__ = "0+unknown"
 
 # --- model registry (loader + command builders + packaging injection) ---
 from .model_registry import (
@@ -25,6 +46,7 @@ from .model_registry import (
     set_resource_root,
     set_user_config_finder,
 )
+from .command_builders import savilerow_backstop, SAVILEROW_FLUSH_GRACE
 
 # --- run configuration singleton ---
 from .global_state import global_state, GlobalState
@@ -85,6 +107,8 @@ __all__ = [
     "set_default_config_path",
     "set_resource_root",
     "set_user_config_finder",
+    "savilerow_backstop",
+    "SAVILEROW_FLUSH_GRACE",
     # run config
     "global_state",
     "GlobalState",

{solver_support-0.2.2 → solver_support-0.3.1}/solver_support/command_builders.py

@@ -21,6 +21,41 @@ from typing import List, Optional
 from .model_registry import ModelRegistryError
 
 
+#: Seconds of slack between the in-band limits and the external kill. Savile Row
+#: needs a moment *after* its own limit fires to write the ``.info`` file (it
+#: accumulates every statistic in memory and flushes once), and Conjure to
+#: translate a solution back. A kill set exactly at the in-band limit races that
+#: flush and generally wins, so the run that was about to report its statistics
+#: reports nothing at all - the failure is worst precisely for the instances
+#: where all the work was tailoring, which are the ones the limit bounded.
+SAVILEROW_FLUSH_GRACE = 30
+
+
+def savilerow_backstop(timeout: int, solver_timeout: Optional[int] = None,
+                       grace: int = SAVILEROW_FLUSH_GRACE) -> int:
+    """The external timeout that cannot preempt Savile Row's own limits.
+
+    Savile Row's ``-timelimit`` and the backend solver's own limit are budgets
+    spent *one after the other* - it tailors, then runs the solver - so the wall
+    clock they jointly permit is their SUM, not the larger of the two. An
+    external kill below that sum will sometimes fire while the toolchain is
+    still inside the limits it was given, and because Savile Row writes its
+    ``.info`` only at the very end, firing early discards every statistic the
+    run had gathered.
+
+    Sized from the same numbers that reach :meth:`build_savilerow_command`, so
+    the two cannot drift apart. Passing this to the runner makes an external
+    kill mean "the toolchain ignored its limits", which is a genuine fault,
+    rather than an ordinary and silently lossy way for a run to end.
+
+    This is a *backstop*, not a wall-clock budget. To hold a run to ``T``
+    seconds of wall clock, do not shrink this - shrink the in-band pair so that
+    their sum is ``T`` (give the solver ``T`` minus what tailoring will cost)
+    and let the backstop sit above it, unreached.
+    """
+    return timeout + (timeout if solver_timeout is None else solver_timeout) + grace
+
+
 class CommandBuilderMixin:
     """The ``build_*_command`` methods mixed into :class:`ModelRegistry`."""
 
@@ -108,7 +143,8 @@ class CommandBuilderMixin:
                                objective_file_path: Optional[str] = None,
                                extra_options: Optional[List[str]] = None,
                                solver_name: str = 'kissat',
-                               tune: Optional[str] = None) -> List[str]:
+                               tune: Optional[str] = None,
+                               solver_timeout: Optional[int] = None) -> List[str]:
         """
         Build a Savile Row command with proper flags for horizon scanning.
 
@@ -120,7 +156,28 @@ class CommandBuilderMixin:
             model_path: path to the model file
             param_path: path to the parameter file
             use_srjava: use Java savilerow instead of savilerow-native
-            timeout: override timeout in seconds (uses default_timeout if None)
+            timeout: Savile Row's own ``-timelimit``, in seconds (uses
+                ``default_timeout`` if None). Covers tailoring *plus* solving,
+                but stops binding once a solver is running - so in practice it
+                bounds tailoring.
+            solver_timeout: the backend solver's own limit, if it should differ
+                from ``timeout``. Defaults to ``timeout``, which is what every
+                caller got before this existed.
+
+                These are two budgets spent one after the other, not one budget
+                named twice: Savile Row tailors, and only then runs the solver.
+                Passing the same number to both grants up to ``2 x timeout`` of
+                wall clock, which is why an external kill set at ``timeout``
+                fires mid-search and takes the statistics with it - Savile Row
+                accumulates them in memory and writes the ``.info`` once, after
+                the solver it launched returns.
+
+                The split is what lets a caller keep a real wall-clock budget:
+                reserve what tailoring will cost and give the solver the rest.
+                The core picks no reserve policy - a horizon scan can measure
+                the previous horizon's ``SavileRowTotalTime``, a single-shot run
+                cannot - so the number is the caller's. See
+                :func:`savilerow_backstop` for sizing the external kill.
             objective_file_path: path for intermediate objective values file (default: obj.txt)
             extra_options: additional command line options to pass to Savile Row
             solver_name: name of the solver configuration to use (default: 'kissat').
@@ -226,12 +283,18 @@ class CommandBuilderMixin:
             # The solver's own limit, in whatever flag and unit that solver
             # speaks. A config may override the dialect (or set it to null to
             # suppress it) without the core having to learn a new backend.
+            #
+            # Defaults to `timeout`, so a caller that says nothing gets exactly
+            # the argv it always got. Note the two limits are consecutive
+            # budgets - Savile Row tailors, then runs the solver - so leaving
+            # them equal permits roughly twice `timeout` of wall clock.
             option = solver_config.get('solver_timeout_option', spec['timeout_option'])
             if option:
                 scale = spec['timeout_scale']
+                budget = timeout if solver_timeout is None else solver_timeout
                 # Left untouched when the solver already speaks seconds, so those
                 # argvs keep their exact previous form (--time=45, never 45.0).
-                value = timeout if scale == 1 else int(timeout * scale)
+                value = budget if scale == 1 else int(budget * scale)
                 args.extend(["-solver-options", option.format(value=value)])
             # Savile Row's own limit covers translation plus solving and is always
             # in seconds. Always added, so a backend with no limit of its own is

{solver_support-0.2.2 → solver_support-0.3.1}/solver_support/run_summary.py

@@ -105,17 +105,49 @@ _NON_SOLVING_PHASES = frozenset({"translation", "modelling", "visualisation"})
 # visualiser or .sol export would silently flip a solved run to success=False.)
 _OPTIONAL_PHASES = frozenset({"visualisation", "export"})
 
-# final_status values the orchestrator uses to mean "this run did not produce a
-# solution / could not run". On these, overall success is False regardless of
-# whether each individual subprocess exited 0 — a solver that runs cleanly but
-# yields no solution (all horizons UNSAT, or a planner that returns no plan) is
-# not a success. `final_status` is the orchestrator's verdict; `all(phase.success)`
-# only knows that subprocesses didn't crash, so the verdict wins. See
-# [[upf-noplan-success-reporting]] and docs/server-harness.md.
-# 'hlim' (horizon scan exhausted its budget without deciding) is a no-solution
-# outcome too, so it also forces success False; it is kept as a distinct status
-# string so consumers can tell "ran out of horizons" from a genuine failure.
-_FAILURE_STATUSES = frozenset({"failed", "launch-failed", "hlim"})
+# --- what a run concluded, and why it stopped ---
+#
+# `final_status` alone cannot answer "did this run learn anything?", because it
+# conflates two independent questions. 'timeout' covers both a run that found a
+# solution before the budget ran out and one that found nothing; 'failed' covers
+# both a planner proving no plan exists and a crash. So the two questions are
+# recorded separately:
+#
+#   outcome      what was learned:  solved / unsat / unknown / error
+#   stop_reason  why it ended:      complete / time / horizons / interrupt / error
+#
+# `final_status` keeps its current meaning and is untouched - it is the
+# orchestrator's own label, and consumers key on it.
+OUTCOMES = ('solved', 'unsat', 'unknown', 'error')
+STOP_REASONS = ('complete', 'time', 'horizons', 'interrupt', 'error')
+
+# A run succeeded if it produced a DEFINITIVE ANSWER in the budget it was given
+# - a solution, or a sound proof that none exists. Both answer the question the
+# run was asked; 'unknown' and 'error' do not. Note this is decided on the
+# outcome and not on exit codes: a planner proving unsatisfiability exits
+# non-zero and its phase records success=False, yet the run succeeded.
+_SUCCESS_OUTCOMES = frozenset({'solved', 'unsat'})
+
+# final_status values where the search RAN TO COMPLETION, so "no solution" can
+# be a verdict rather than an interruption. On any other status the search
+# stopped early and the outcome can only be 'unknown', however complete the
+# model - which is what stops 'hlim' being read as a proof. ('failed' is here
+# because that is the status a planner's proven-unsat arrives under: it exits
+# non-zero, having answered the question.)
+_COMPLETED_STATUSES = frozenset({"done", "success", "failed"})
+
+# final_status -> why the run stopped. Statuses absent here leave stop_reason
+# empty rather than guessing: an unrecognised label is a consumer's own, and
+# inventing a reason for it would put words in its mouth.
+_STOP_REASONS_BY_STATUS = {
+    "done": "complete",
+    "success": "complete",
+    "failed": "complete",
+    "launch-failed": "error",
+    "timeout": "time",
+    "hlim": "horizons",
+    "stopped": "interrupt",
+}
 
 
 @dataclass
@@ -136,6 +168,12 @@ class RunSummary:
     success: bool = False                   # Overall success
     solution_found: bool = False            # Whether solution was found
     final_status: str = ""                  # Final status message
+    # What the run concluded and why it stopped - the two questions final_status
+    # conflates (see OUTCOMES / STOP_REASONS above). Derived by finalize();
+    # empty on a summary that was never finalized, and on one loaded from a file
+    # written before these existed.
+    outcome: str = ""                       # solved / unsat / unknown / error
+    stop_reason: str = ""                   # complete / time / horizons / interrupt / error
     score: Optional[int] = None             # Total score the model reported (scored/upf models only)
     startat: Optional[int] = None           # Starting horizon for Savile Row models (if specified)
     stopat: Optional[int] = None            # Highest horizon tried, if the default cap (100) was overridden
@@ -177,8 +215,42 @@ class RunSummary:
         """
         self.success = all(p.success for p in self.required_phases)
 
-    def finalize(self, final_status: str = "done") -> None:
-        """Finalize the summary with end time and overall success status."""
+    def _derive_outcome(self, final_status: str, proves_unsat: bool,
+                        has_timeout_solution: bool) -> str:
+        """What this run learned: solved / unsat / unknown / error."""
+        # A solution in hand wins over any status label: a run that solved the
+        # instance and was then interrupted, or that banked an anytime solution
+        # before its budget expired, still solved it.
+        if self.solution_found or has_timeout_solution:
+            return 'solved'
+
+        if final_status == "launch-failed":
+            return 'error'
+
+        if final_status in _COMPLETED_STATUSES:
+            # The search finished and produced nothing. From a model that
+            # decides the problem that IS the answer; from any other model it
+            # means something went wrong, because a bounded model that finishes
+            # unsolved has not concluded anything -- it has merely stopped.
+            return 'unsat' if proves_unsat else 'error'
+
+        # 'timeout', 'hlim', 'stopped', or a label this core does not know: the
+        # search stopped early. Nothing was decided, and no completeness of the
+        # model can change that -- refuting horizons 1..N says nothing about
+        # N+1, which is exactly why 'hlim' must never become 'unsat'.
+        return 'unknown'
+
+    def finalize(self, final_status: str = "done",
+                 proves_unsat: bool = False) -> None:
+        """Finalize the summary: end time, outcome, stop reason, success.
+
+        ``proves_unsat`` says whether this run's model is a complete decision
+        procedure, i.e. whether its "no solution" is a sound proof. The core
+        cannot know that from the output - a bounded CP model and a planner print
+        the same thing - so the caller supplies it, normally from the registry's
+        ``get_proves_unsat``. Left False, a no-solution run is never concluded
+        unsat, which is the safe direction: understating what was proved.
+        """
         self.end_time = datetime.now()
         self.final_status = final_status
 
@@ -191,23 +263,19 @@ class RunSummary:
             for phase in self.phases
         )
 
-        if final_status in _FAILURE_STATUSES:
-            # The orchestrator already judged this run a failure (no solution
-            # produced, or the tool could not be launched). Don't let cleanly
-            # exiting subprocesses (e.g. all-UNSAT horizons) override that — a
-            # run that found no solution is not a success.
-            self.success = False
-        elif self.phases:
-            # Overall success is decided by the REQUIRED phases only: best-effort
-            # post-processing (visualisation/.sol export) is non-fatal and must
-            # not fail an otherwise-solved run. A valid timeout solution also
-            # counts (the final solving horizon itself shows as timed-out).
-            required = self.required_phases
-            self.success = (bool(required)
-                            and all(p.success for p in required)) or has_timeout_solution
-        else:
-            self.success = False
-        
+        self.outcome = self._derive_outcome(
+            final_status, proves_unsat, has_timeout_solution)
+        self.stop_reason = _STOP_REASONS_BY_STATUS.get(final_status, "")
+        # Decided on the answer, not on exit codes. The previous rule -- "no
+        # declared failure status AND every required phase exited 0" -- called a
+        # run successful whenever its subprocesses were tidy, so a horizon scan
+        # that ran out of time having found nothing reported success=True: the
+        # solvers had each stopped themselves cleanly at the limit they were
+        # given. Under this rule that run is 'unknown', and a planner's
+        # proven-unsat (which exits non-zero) is a success.
+        self.success = self.outcome in _SUCCESS_OUTCOMES
+
+
         # Extract the highest score from any phase that has one
         scores = []
         for phase in self.phases: