solver-support 0.3.2__tar.gz → 0.4.0__tar.gz

{solver_support-0.3.2/solver_support.egg-info → solver_support-0.4.0}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: solver-support
-Version: 0.3.2
+Version: 0.4.0
 Summary: Generic Conjure / Savile Row / Fast Downward / SymK / ENHSP / UPF solver pipeline
 Author: András Salamon
 License-Expression: BSD-3-Clause
 Project-URL: Homepage, https://github.com/ott2/solver-support
 Project-URL: Repository, https://github.com/ott2/solver-support
 Project-URL: Issues, https://github.com/ott2/solver-support/issues
-Classifier: Development Status :: 3 - Alpha
+Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: Science/Research
 Classifier: Operating System :: OS Independent
@@ -48,8 +48,10 @@ consumer supplies:
 
 ## Status
 
-**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
+**Beta.** The pipeline is in day-to-day use by several consumers and is covered
+by its own test suite. The injection seams and the run-summary vocabulary
+(`outcome`, `stop_reason`, `verdict`) are stable: later releases add to them
+rather than rename them. Other 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).
 
@@ -70,6 +72,37 @@ Requires Python 3.9 or newer (3.9.6 is the system Python on macOS, and is
 supported deliberately — each release is built and tested against it). The only
 runtime dependencies are `psutil` and `PyYAML`.
 
+## Quick start
+
+The package ships no model registry, but it carries a commented starter one
+(Fast Downward, SymK, ENHSP and Savile Row) to copy and edit. Writing it out
+does not wire it; you point the registry at it:
+
+```python
+from pathlib import Path
+from solver_support import (
+    write_starter_config, set_default_config_path, set_resource_root,
+    global_state, SolverRunner, FastDownwardSolver, fd_backstop,
+)
+
+config = write_starter_config("config/models.yaml")   # once; then edit it
+set_default_config_path(config)
+set_resource_root(".")            # where the models' `path:` entries resolve
+
+registry = global_state.model_registry
+runner = SolverRunner(instance="p01", model="pddl", solver="fd", timeout=60,
+                      timestamp="run1", summary_file=Path("p01.json"))
+try:
+    plan = FastDownwardSolver(runner).solve(
+        Path("p01.pddl"), model_path=str(registry.get_model_path("pddl")),
+        watchdog=fd_backstop(60))         # let the planner's own limit fire
+    status = "done" if plan else "failed"
+except TimeoutError:
+    status = "timeout"
+runner.finalize_summary(status, proves_unsat=registry.get_proves_unsat("pddl"))
+print(runner.summary.outcome)     # solved / unsat / unknown / error
+```
+
 ## Usage
 
 See [`docs/injection-api.md`](https://github.com/ott2/solver-support/blob/main/docs/injection-api.md)
@@ -125,4 +158,4 @@ config — that shape is the contract the loader implements.
 BSD-3-Clause — see
 [`LICENSE`](https://github.com/ott2/solver-support/blob/main/LICENSE).
 
-By András Salamon, with Claude Opus 4.8 and 5.
+By András Salamon, with Claude Opus 4.8, 5 and 5.5.

{solver_support-0.3.2 → solver_support-0.4.0}/README.md

@@ -20,8 +20,10 @@ consumer supplies:
 
 ## Status
 
-**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
+**Beta.** The pipeline is in day-to-day use by several consumers and is covered
+by its own test suite. The injection seams and the run-summary vocabulary
+(`outcome`, `stop_reason`, `verdict`) are stable: later releases add to them
+rather than rename them. Other 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).
 
@@ -42,6 +44,37 @@ Requires Python 3.9 or newer (3.9.6 is the system Python on macOS, and is
 supported deliberately — each release is built and tested against it). The only
 runtime dependencies are `psutil` and `PyYAML`.
 
+## Quick start
+
+The package ships no model registry, but it carries a commented starter one
+(Fast Downward, SymK, ENHSP and Savile Row) to copy and edit. Writing it out
+does not wire it; you point the registry at it:
+
+```python
+from pathlib import Path
+from solver_support import (
+    write_starter_config, set_default_config_path, set_resource_root,
+    global_state, SolverRunner, FastDownwardSolver, fd_backstop,
+)
+
+config = write_starter_config("config/models.yaml")   # once; then edit it
+set_default_config_path(config)
+set_resource_root(".")            # where the models' `path:` entries resolve
+
+registry = global_state.model_registry
+runner = SolverRunner(instance="p01", model="pddl", solver="fd", timeout=60,
+                      timestamp="run1", summary_file=Path("p01.json"))
+try:
+    plan = FastDownwardSolver(runner).solve(
+        Path("p01.pddl"), model_path=str(registry.get_model_path("pddl")),
+        watchdog=fd_backstop(60))         # let the planner's own limit fire
+    status = "done" if plan else "failed"
+except TimeoutError:
+    status = "timeout"
+runner.finalize_summary(status, proves_unsat=registry.get_proves_unsat("pddl"))
+print(runner.summary.outcome)     # solved / unsat / unknown / error
+```
+
 ## Usage
 
 See [`docs/injection-api.md`](https://github.com/ott2/solver-support/blob/main/docs/injection-api.md)
@@ -97,4 +130,4 @@ config — that shape is the contract the loader implements.
 BSD-3-Clause — see
 [`LICENSE`](https://github.com/ott2/solver-support/blob/main/LICENSE).
 
-By András Salamon, with Claude Opus 4.8 and 5.
+By András Salamon, with Claude Opus 4.8, 5 and 5.5.

{solver_support-0.3.2 → solver_support-0.4.0}/docs/injection-api.md

@@ -28,6 +28,12 @@ candidates bind when the registry is constructed rather than at import. Until a
 default config path is registered, constructing `ModelRegistry()` raises
 `ModelRegistryError` rather than guessing a consumer's config.
 
+To start a config from scratch, `write_starter_config(path)` writes out the
+commented starter registry that ships as package data (`starter_config_text()`
+returns its text). Writing it out wires nothing. The registry still raises until
+`set_default_config_path` names it, so a starter file on disk can never change
+what an unwired core does.
+
 ### 2. objective extraction (`solver_support.objective`)
 
 The core asks for a solution's objective at a few points but does not know how a

{solver_support-0.3.2 → solver_support-0.4.0}/docs/solver-runner.md

@@ -21,13 +21,15 @@ the pipeline branches on.
 
 ```python
 SolverResult(command, returncode, stdout, stderr, duration,
-             timed_out=False, interrupted=False)
+             timed_out=False, interrupted=False, launch_failed=False,
+             ok_returncodes=None)
 ```
 
 | field | meaning |
 |-------|---------|
 | `command: List[str]` | the command and arguments that ran |
-| `returncode: int` | process return code (0 for success) |
+| `returncode: int` | process return code |
+| `ok_returncodes` | the codes that count as success; `{0}` unless the caller says otherwise |
 | `stdout: str` / `stderr: str` | captured output, kept separate |
 | `duration: float` | **actual** seconds the command ran |
 | `timed_out: bool` | it was killed for exceeding the timeout |
@@ -54,9 +56,30 @@ a component of it — see the invariants in [`timing-model.md`](timing-model.md)
 
 ### properties
 
-- `success: bool` — completed with return code 0, no timeout, no interruption.
+- `success: bool` — exited with one of its `ok_returncodes`, no timeout, no
+  interruption, no launch failure.
 - `failed: bool` — the inverse; useful as a direct `if` on a run.
 
+### solvers that answer through the exit code
+
+Some solvers put the *answer* in the exit code, so for them a non-zero exit is
+the solver doing its job. Every DIMACS SAT solver exits 10 for SATISFIABLE and
+20 for UNSATISFIABLE; read against `{0}`, a refutation would be logged as
+`Command failed` and recorded as `success=False`. Pass the solver's set to `run`
+or `run_phase`:
+
+```python
+from solver_support.solver_runner import DIMACS_SAT_RETURNCODES
+
+result = runner.run(['kissat', 'model.cnf'], ok_returncodes=DIMACS_SAT_RETURNCODES)
+result.success      # True for 0 (unknown), 10 (sat) and 20 (unsat)
+result.returncode   # which of them
+```
+
+`success` then means "the process ran and answered", not what the answer was:
+read `returncode` (or the parsed stats) for that. The runner never picks the set
+by detecting the solver from the command, so detection cannot decide success.
+
 Note that `failed` covers three *different* outcomes, and the pipeline usually
 cares which: check `timed_out` and `interrupted` before treating a run as a
 genuine solver failure. A timed-out anytime solver may still have banked a

{solver_support-0.3.2 → solver_support-0.4.0}/docs/timing-model.md

@@ -238,6 +238,73 @@ N+1. Only the registry knows which models decide the problem itself
 - **Timeout**: the final, cut-off layer is bounded by `end_hint = duration -
   translate_time` (the search-relative kill time), so the blown-up deepest bound
   does not collapse to ~0.
+- **Its own limit, and the backstop above it**: `--search-time-limit T` is a CPU
+  rlimit on the search alone, while the runner's watchdog counts wall clock over
+  translation plus search. A watchdog at `T` therefore always fires first, and
+  the run loses the exit 23 and the final statistics block it would have
+  written. Size the watchdog with `fd_backstop(T, translate_allowance)`, which
+  is `T`, plus translation, plus `FD_EXIT_GRACE`, and pass it as
+  `FastDownwardSolver.solve(..., watchdog=...)`. The runner's own timeout stays
+  the in-band limit. Then an external kill once again means the planner ignored
+  its limit. As with Savile Row, this is a
+  backstop and not a budget: to hold a run to a wall-clock `T`, shrink the search
+  limit.
+
+#### Verdicts: proof, limit, or rejection
+
+Fast Downward answers through its **exit code** (`driver/returncodes.py`), so
+`run_phase` is handed `FD_ANSWER_RETURNCODES` and a proof is not logged as a
+failed command. `SolverStatsExtractor.fd_verdict` reads the code, plus the log
+where the code is ambiguous, into the same vocabulary as the Savile Row verdict.
+`FastDownwardSolver` records it on the `solving` phase:
+
+| exit | verdict | `verdict_reason` |
+|---|---|---|
+| 0–3 (plan; 1–3 then hit a limit) | `sat` | |
+| 10, 11 | `unsat` | (the planner's own claim) |
+| 12, see below | `unsat` / `unknown` | `exhausted`, or `search-limit` / `bounded` / `portfolio` / `incomplete` |
+| 13 (26.6+) | `unknown` | `bounded` |
+| 20 / 21 | `unknown` | `translate-memory` / `translate-limit` |
+| 22, 24 / 23 | `unknown` | `memory` / `search-limit` |
+| 34, 37 | `error` | `unsupported` (`unknown`/`portfolio` for an anytime portfolio) |
+| 31, 33, 36 | `error` | `input-error` |
+| 30, 32, 35, a signal | `error` | `crash` |
+| killed by the runner | `killed` | |
+
+**Exit 12 is ambiguous by construction.** Before 26.6 the planner exits
+`found_solution() ? 0 : 12` however the search ended, so the log decides:
+
+- `Time limit reached. Abort search.` (the search's `max_time=`) gives
+  `search-limit`.
+- `Completely explored state space -- no solution!` gives `unsat`/`exhausted`,
+  or `bounded` if the `--search` string has a `bound=`. The log looks the same
+  either way, so the argv is read for it. The translator's
+  `Generating unsolvable task` lands here too, since the search then exhausts a
+  trivially false goal.
+- SymK prints no exhaustion line. Its last `BOUND: L < U` line, with `L ≥ U`, is
+  `exhausted` when `U` is infinity (`2147483647`) and `bounded` otherwise.
+- A portfolio's 12 is always `portfolio`. It can mask its components'
+  time-outs, and its exhaustion line may come from a component that pruned
+  unsafely.
+- Anything else is `incomplete`: EHC giving up, or a 26.6 search that the
+  planner itself judged incomplete (`Search terminated without finding a
+  plan!`).
+
+**`exhausted` is this library's reading, not the planner's.** It is sound only
+if the search is complete and prunes safely. A relaxation heuristic prunes
+infinite-valued states even on a task with axioms, where infinity is not a
+dead end, so `astar(ff())` there "exhausts" without proving anything. The log
+cannot reveal this. From 26.6 the planner checks it (upstream issue1201): a
+safe exhaustion exits 11 and an unsafe one exits 12 with no exhaustion line, so
+`exhausted` only ever comes from older planners and SymK. Whether it becomes a
+run-level `unsat` is decided by the registry's `proves-unsat`, which a tune
+preset can switch off.
+
+**The planner's own time limit is a timeout.** `search-limit` and
+`translate-limit` make `solve()` raise `TimeoutError`, exactly as a watchdog
+kill does, and so does an anytime portfolio that ends without a plan. Every other
+no-plan ending returns `None`, and the run's `outcome` is derived from the
+verdict.
 
 ### UPF (via the consumer's UPF CLI; PDDL or constructed models)
 
@@ -319,16 +386,41 @@ 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.
 
+For a planner, being able to prove depends on the **search** as well as the model.
+`get_proves_unsat(model, tune=..., solver_name=...)` is the model's
+`proves-unsat` AND the effective tune's. A tune preset may carry
+`proves-unsat: false` (for example a relaxation heuristic that prunes unsafely
+on tasks with axioms), which takes the claim away. A tune can never grant it to
+a model that cannot prove. `finalize` keeps the value on the summary as
+`proves_unsat`, and a later `finalize` that passes None reuses it. So a
+re-finalize that folds in a late phase, as `horizon_utils` does, cannot drop it.
+
+**A `solving` phase's verdict decides a completed run.** `failed` is the status
+of both a planner's proof and its crash, so `proves_unsat` alone would promote
+every crash of a complete model to `unsat`. Where the `solving` phase recorded a
+`verdict` (Fast Downward and SymK do, see above), it decides instead:
+
+| verdict | `proves_unsat` | outcome |
+|---|---|---|
+| `unsat` | True | `unsat` |
+| `unsat` | False | `unknown`: the search ran out, but cannot prove |
+| `unknown` / `killed` | either | `unknown` |
+| `error` | either | `error` |
+
+A run with no verdict is read as before. Per-horizon verdicts
+(`solving-horizon-N`) are about one bound each and never decide the run.
+
 ## 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`) |
+| per-run Fast Downward / SymK verdict (exit code + log) | `solver_stats.py` (`fd_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`), outcome and success | `run_summary.py` |
-| relating the in-band limits to the external kill | `command_builders.py` (`savilerow_backstop`) |
+| relating the in-band limits to the external kill | `command_builders.py` (`savilerow_backstop`, `fd_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.3.2 → solver_support-0.4.0}/pyproject.toml

@@ -20,7 +20,7 @@ name = "solver-support"
 # 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.2"
+version = "0.4.0"
 description = "Generic Conjure / Savile Row / Fast Downward / SymK / ENHSP / UPF solver pipeline"
 readme = "README.md"
 requires-python = ">=3.9"
@@ -29,7 +29,7 @@ authors = [
     {name = "András Salamon"},
 ]
 classifiers = [
-    "Development Status :: 3 - Alpha",
+    "Development Status :: 4 - Beta",
     "Intended Audience :: Developers",
     "Intended Audience :: Science/Research",
     "Operating System :: OS Independent",
@@ -81,6 +81,11 @@ zip-safe = false
 [tool.setuptools.packages.find]
 include = ["solver_support*"]
 
+# The starter registry `write_starter_config` copies out. Package data, not a
+# default: nothing loads it unless a user writes it out and wires it.
+[tool.setuptools.package-data]
+solver_support = ["starter/*.yaml"]
+
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 python_files = ["test_*.py"]

{solver_support-0.3.2 → solver_support-0.4.0}/solver_support/__init__.py

@@ -45,8 +45,12 @@ from .model_registry import (
     set_default_config_path,
     set_resource_root,
     set_user_config_finder,
+    starter_config_text,
+    write_starter_config,
+)
+from .command_builders import (
+    savilerow_backstop, SAVILEROW_FLUSH_GRACE, fd_backstop, FD_EXIT_GRACE,
 )
-from .command_builders import savilerow_backstop, SAVILEROW_FLUSH_GRACE
 
 # --- run configuration singleton ---
 from .global_state import global_state, GlobalState
@@ -68,8 +72,12 @@ from .solver_upfplan import UpfPlanSolver
 from .solver_horizon import HorizonBasedSolver, SavileRowSolver, ConjureSolver
 
 # --- execution, stats, run model ---
-from .solver_runner import SolverRunner, SolverResult, SolverExecutableError
-from .solver_stats import SolverStatsExtractor, detect_solver_from_command
+from .solver_runner import (
+    SolverRunner, SolverResult, SolverExecutableError, DIMACS_SAT_RETURNCODES,
+)
+from .solver_stats import (
+    SolverStatsExtractor, detect_solver_from_command, FD_ANSWER_RETURNCODES,
+)
 from .run_summary import RunSummary, PhaseResult, create_run_summary
 
 # --- file naming and horizon loop ---
@@ -107,8 +115,12 @@ __all__ = [
     "set_default_config_path",
     "set_resource_root",
     "set_user_config_finder",
+    "starter_config_text",
+    "write_starter_config",
     "savilerow_backstop",
     "SAVILEROW_FLUSH_GRACE",
+    "fd_backstop",
+    "FD_EXIT_GRACE",
     # run config
     "global_state",
     "GlobalState",
@@ -130,6 +142,8 @@ __all__ = [
     "SolverRunner",
     "SolverResult",
     "SolverExecutableError",
+    "DIMACS_SAT_RETURNCODES",
+    "FD_ANSWER_RETURNCODES",
     "SolverStatsExtractor",
     "detect_solver_from_command",
     "RunSummary",

{solver_support-0.3.2 → solver_support-0.4.0}/solver_support/command_builders.py

@@ -56,6 +56,35 @@ def savilerow_backstop(timeout: int, solver_timeout: Optional[int] = None,
     return timeout + (timeout if solver_timeout is None else solver_timeout) + grace
 
 
+#: Seconds of slack above Fast Downward's in-band search limit. The driver turns
+#: SIGXCPU into exit 23 and the search then prints its final statistics block
+#: ("Actual search time", expansions); the grace lets that land. It is also what
+#: absorbs the gap between the CPU seconds the limit counts and the wall-clock
+#: seconds the watchdog counts, which a loaded machine widens.
+FD_EXIT_GRACE = 30
+
+
+def fd_backstop(timeout: int, translate_allowance: Optional[int] = None,
+                grace: int = FD_EXIT_GRACE) -> int:
+    """The external timeout that cannot preempt Fast Downward's own limit.
+
+    :meth:`build_fd_command` passes ``--search-time-limit T``, a CPU rlimit
+    on the *search* alone, while the runner's watchdog kills at ``T`` seconds of
+    wall clock over translation *plus* search. CPU time never exceeds the wall
+    time since search began, so a watchdog at ``T`` always fires first and the
+    in-band limit never gets to: the run is SIGTERMed instead of exiting 23, its
+    statistics are lost, and its verdict can only say ``killed``.
+
+    Sized like :func:`savilerow_backstop`: the search limit, plus what
+    translation may take before it (``translate_allowance``, defaulting to the
+    search limit, since translation is unbounded in band and only the caller
+    knows its cost), plus grace. The same caveat applies: this is a backstop,
+    not a wall-clock budget. To hold a run to ``T``, shrink the search limit.
+    """
+    allowance = timeout if translate_allowance is None else translate_allowance
+    return timeout + allowance + grace
+
+
 class CommandBuilderMixin:
     """The ``build_*_command`` methods mixed into :class:`ModelRegistry`."""
 

{solver_support-0.3.2 → solver_support-0.4.0}/solver_support/model_registry.py

@@ -581,26 +581,51 @@ class ModelRegistry(CommandBuilderMixin):
             return False
         return model_config.get('objective-in-solution', False)
 
-    def get_proves_unsat(self, model_type: str) -> bool:
-        """Whether a model can soundly conclude unsatisfiability.
-
-        True only for complete decision procedures (the pddl* planning models
-        and the upf/upflocal viewpoints, flagged ``proves-unsat: true``) whose
-        'no solution' run is a genuine unsat proof. Bounded CP models carry no
-        such field and so default to False - their 'failed'/'no solution' is an
-        error or an unfinished horizon search, never an unsat verdict.
+    def get_proves_unsat(self, model_type: str, tune: Optional[str] = None,
+                         solver_name: Optional[str] = None) -> bool:
+        """Whether a run of this model can soundly conclude unsatisfiability.
+
+        True only for complete decision procedures (planning models, flagged
+        ``proves-unsat: true``) whose 'no solution' run is a genuine unsat
+        proof. Bounded CP models carry no such field and so default to False -
+        their 'failed'/'no solution' is an error or an unfinished horizon
+        search, never an unsat verdict.
+
+        For a planner, completeness also depends on the *search*: the same model
+        proves unsat under blind A* and not under a relaxation heuristic that
+        prunes unsafely on a task with axioms. So a tune preset may carry
+        ``proves-unsat: false``, and the answer is the model's flag AND the
+        effective tune's. A tune can only take the claim away, never grant it to
+        a model that cannot prove.
 
         Args:
             model_type: The model type.
+            tune: The explicit ``--tune``, if any. Otherwise the model's pinned
+                ``tune:``, then the solver's ``default_tune`` - the resolution
+                the solver used to build its command.
+            solver_name: The solver that ran, if not the model's own ``solver:``.
 
         Returns:
-            True if the model declares ``proves-unsat: true``, else False.
+            True if the model declares ``proves-unsat: true`` and the effective
+            tune does not declare ``proves-unsat: false``, else False.
         """
         try:
             _, model_config = self.resolve_model_variant(model_type)
         except (ValueError, ModelRegistryError):
             return False
-        return model_config.get('proves-unsat', False)
+        if not model_config.get('proves-unsat', False):
+            return False
+        solver_name = solver_name or model_config.get('solver')
+        if not solver_name:
+            return True
+        try:
+            solver_config = self.get_solver_config(self.get_tune_backend(solver_name))
+        except ModelRegistryError:
+            return True
+        tunes = solver_config.get('tune', {})
+        tune = tune or model_config.get('tune')
+        name = tune if tune in tunes else solver_config.get('default_tune')
+        return bool(tunes.get(name, {}).get('proves-unsat', True))
 
     def get_model_status(self, model_type: str) -> Tuple[Optional[str], Optional[str]]:
         """Return a model's health status and an optional detail string.
@@ -800,6 +825,39 @@ class ModelRegistry(CommandBuilderMixin):
         return self.get_tune_regime(solver_name, tune) == 'anytime'
 
 
+def starter_config_text() -> str:
+    """The starter ``models.yaml`` shipped with the package, as text.
+
+    A commented example registry - Fast Downward, SymK, ENHSP and Savile Row -
+    for a new user to copy and edit. It is never loaded implicitly: the core
+    still ships unwired, and :class:`ModelRegistry` still raises until a config
+    path is set. Unlike :meth:`ModelRegistry.dump_config` it keeps its comments,
+    which is what makes it fit to start from.
+    """
+    from importlib.resources import files
+    return files('solver_support').joinpath('starter', 'models.yaml').read_text(
+        encoding='utf-8')
+
+
+def write_starter_config(path, overwrite: bool = False) -> Path:
+    """Write the starter ``models.yaml`` to ``path`` and return the path.
+
+    The quick start for a new user, who then wires it with
+    :func:`set_default_config_path`. Writing it out does *not* wire it: having
+    a starter file on disk must never change what an unwired registry does.
+
+    Raises:
+        FileExistsError: if ``path`` exists and ``overwrite`` is False - an edited
+            registry is the user's work, and a starter is not worth losing it for.
+    """
+    path = Path(path)
+    if path.exists() and not overwrite:
+        raise FileExistsError(f"{path} already exists (pass overwrite=True to replace it)")
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(starter_config_text(), encoding='utf-8')
+    return path
+
+
 def get_default_registry() -> ModelRegistry:
     """
     Get a default model registry instance.

{solver_support-0.3.2 → solver_support-0.4.0}/solver_support/run_summary.py

@@ -133,9 +133,20 @@ _SUCCESS_OUTCOMES = frozenset({'solved', 'unsat'})
 # 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.)
+# non-zero, having answered the question. It is also the status of a crash, which
+# is why a solving phase's `verdict`, where there is one, decides between them.)
 _COMPLETED_STATUSES = frozenset({"done", "success", "failed"})
 
+# A completed run with no solution, read through its solving phase's verdict
+# (see SolverStatsExtractor.fd_verdict). `unsat` is handled separately: it needs
+# the model's proves_unsat as well.
+_OUTCOME_BY_VERDICT = {
+    'unknown': 'unknown',   # stopped at a limit, or a search that cannot refute
+    'killed': 'unknown',
+    'error': 'error',
+    'sat': 'error',         # claimed a plan, yet none reached the summary
+}
+
 # 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.
@@ -174,6 +185,10 @@ class RunSummary:
     # written before these existed.
     outcome: str = ""                       # solved / unsat / unknown / error
     stop_reason: str = ""                   # complete / time / horizons / interrupt / error
+    # Whether this run's model AND search can prove unsatisfiability (the
+    # registry's get_proves_unsat), as last given to finalize(). Kept so that a
+    # later re-finalize - after appending a phase, say - cannot drop it.
+    proves_unsat: bool = False
     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
@@ -228,11 +243,22 @@ class RunSummary:
             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'
+            verdict = self._solving_verdict()
+            if verdict is None:
+                # No account of how the search ended, so read the status alone.
+                # 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'
+            # The solver said how its search ended. Only a refutation from a
+            # search that can prove one is a proof; an exhausted search that
+            # cannot (an unsafe heuristic, a tune switched off) concluded
+            # nothing, but nothing went wrong either.
+            if verdict == 'unsat':
+                return 'unsat' if proves_unsat else 'unknown'
+            return _OUTCOME_BY_VERDICT.get(verdict, 'error')
 
         # 'timeout', 'hlim', 'stopped', or a label this core does not know: the
         # search stopped early. Nothing was decided, and no completeness of the
@@ -240,19 +266,35 @@ class RunSummary:
         # N+1, which is exactly why 'hlim' must never become 'unsat'.
         return 'unknown'
 
+    def _solving_verdict(self) -> Optional[str]:
+        """The ``verdict`` the ``solving`` phase recorded, if it recorded one.
+
+        Only the single-phase solvers' ``solving`` phase: a horizon scan's
+        per-horizon verdicts are about one bound each, and never decide the run.
+        """
+        phase = self.get_phase("solving")
+        if phase is None:
+            return None
+        return phase.solver_stats.get('verdict')
+
     def finalize(self, final_status: str = "done",
-                 proves_unsat: bool = False) -> None:
+                 proves_unsat: Optional[bool] = None) -> 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.
+        ``proves_unsat`` says whether this run's model, under the search it
+        ran, 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. None keeps the value from the previous
+        finalize, so re-finalizing to fold in a late phase cannot drop it.
         """
         self.end_time = datetime.now()
         self.final_status = final_status
+        if proves_unsat is not None:
+            self.proves_unsat = proves_unsat
+        proves_unsat = self.proves_unsat
 
         # Check if we have a successful timeout-based solution phase: an anytime
         # run that found a solution before the budget ran out still succeeded.