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

{solver_support-0.2.1/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.1
+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.1 → 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.1 → 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.1 → solver_support-0.3.1}/docs/timing-model.md

@@ -76,12 +76,34 @@ fields. All times are seconds unless noted.
   `solver_time`, attaching them to the matching phase. Recorded for *every*
   horizon, so intermediate UNSAT horizons carry the split too.
 - **The rest of the file**: those two are what the phase model needs, but the
-  same `.info` carries the encoding size and search counters (`SATVars`,
-  `SATClauses`, `SolverNodes`, `SolverSatisfiable`, ...).
-  `SolverStatsExtractor.extract_savilerow_info(path)` returns every `Key:Value`
-  pair with keys verbatim and values coerced to int/float, for a consumer
-  reporting those columns; `extract_savilerow_info_times` is the renaming subset
-  of it that the core itself uses.
+  same `.info` carries the encoding size, the search counters, and the outcome
+  flags. All of it is recorded verbatim on the phase under
+  `solver_stats['savilerow_info']`, so a consumer never has to go back to the
+  `.info` files — which matters because that would depend on the run's output
+  directory rather than its summary, and so stops working once those files are
+  cleaned up. `SolverStatsExtractor.extract_savilerow_info(path)` is the parser
+  (keys verbatim, values coerced to int/float, `{}` for a missing file);
+  `extract_savilerow_info_times` is the renaming subset that produces the two
+  fields above.
+- **Nested, not flattened, and deliberately not curated.** `solver_stats` is the
+  core's normalised cross-solver vocabulary; `savilerow_info` is one solver's own
+  keys in its own spelling, so nesting keeps CamelCase off the snake_case
+  namespace. It is verbatim because the backends do not agree on which keys
+  exist — measured on one model:
+
+  | key | minion | ortools | gecode | chuffed | kissat |
+  |---|:-:|:-:|:-:|:-:|:-:|
+  | `SavileRowTotalTime` `SolverTotalTime` `SolverSatisfiable` `SolverTimeOut` `SavileRowTimeOut` `SavileRowClauseOut` | ✓ | ✓ | ✓ | ✓ | ✓ |
+  | `SolverNodes` | ✓ | — | ✓ | ✓ | ✓ |
+  | `SolverFailures` `SolverTotalWallTime` | — | ✓ | ✓ | ✓ | — |
+  | `SolverSetupTime` `SolverSolveTime` `SolverSolutionsFound` | ✓ | — | — | — | — |
+  | `SATVars` `SATClauses` `SolverMemOut` | — | — | — | — | ✓ |
+
+  Any allow-list would already be wrong, and would need extending for every new
+  backend or Savile Row version. Note `SolverSatisfiable` is one of the six every
+  backend emits: it distinguishes a **refuted horizon** from one that gave up —
+  which is *not* problem-level unsat, since a bounded model cannot prove that
+  (see `hlim`, above).
 - **Best-effort**: a hard timeout can kill Savile Row before it writes `.info`,
   leaving the split absent (`None`).
 
@@ -124,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
@@ -188,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.1 → 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.1 → 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.1"
+# 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.1 → 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.1 → solver_support-0.3.1}/solver_support/model_registry.py

@@ -9,6 +9,7 @@ from the original bash run script.
 
 from pathlib import Path
 from typing import Dict, Any, Optional, List, Tuple, Callable
+import copy
 import shutil
 import yaml
 
@@ -95,8 +96,14 @@ class ModelRegistry(CommandBuilderMixin):
         
         self.config = {'models': {}, 'solvers': {}}
         self._savilerow_native_warning_shown = False  # Track if we've shown the warning
+        # Every file merged in, in the order merged, so a caller can report what
+        # actually contributed. Without this the answer is only reconstructible
+        # by re-running the same two searches by hand - and the user-override one
+        # depends on the cwd at construction time, so it is not reproducible
+        # later. See `dump_config`.
+        self.config_sources: List[Path] = []
         self._load_yaml_config(default_yaml)
-        
+
         # Then, load user configuration to override defaults
         user_yaml = config_path or self._find_user_yaml_config()
         if user_yaml:
@@ -145,10 +152,11 @@ class ModelRegistry(CommandBuilderMixin):
         try:
             with open(config_path, 'r') as f:
                 user_config = yaml.safe_load(f)
-            
+
             # Deep merge user config with existing config
             self._deep_merge(self.config, user_config)
-            
+            self.config_sources.append(Path(str(config_path)))
+
         except Exception as e:
             raise ModelRegistryError(f"Failed to load config file {config_path}: {e}")
     
@@ -165,7 +173,76 @@ class ModelRegistry(CommandBuilderMixin):
                 self._deep_merge(base[key], value)
             else:
                 base[key] = value
-    
+
+    def effective_config(self, resolved: bool = False) -> Dict[str, Any]:
+        """The configuration actually in force, as a plain dict.
+
+        A deep copy of the merge of every file in ``config_sources``: the
+        consumer's bundled config first, then any user override merged over it.
+        Answering "what is in force?" otherwise means reading both files and
+        performing the merge by eye - and the override's location depends on the
+        working directory at construction time, so it cannot reliably be
+        reconstructed afterwards.
+
+        With ``resolved``, values a *builder* supplies when a key is absent are
+        written out explicitly - currently a savilerow solver's implicit
+        ``backend: sat``, the one default whose absence changes which arg-set,
+        timeout dialect and binary flag are used. Only real config keys are ever
+        added, so a resolved dump still loads; see :meth:`dump_config` for why
+        loading one back is not what it is for.
+
+        The copy is deep, so a caller may edit the result without disturbing the
+        live registry.
+        """
+        config = copy.deepcopy(self.config)
+        if resolved:
+            for solver_config in config.get('solvers', {}).values():
+                if (isinstance(solver_config, dict)
+                        and solver_config.get('solver_type') == 'savilerow'):
+                    solver_config.setdefault('backend', 'sat')
+        return config
+
+    def dump_config(self, resolved: bool = False, header: bool = True) -> str:
+        """The effective configuration as YAML text, for inspection.
+
+        Intended for a consumer's ``--show-registry``-style flag: it answers what
+        the registry resolved to and which files contributed. It is deliberately
+        *not* a config generator. Two reasons, both stated in the emitted header:
+
+        - Comments are not preserved. A config's comments carry the reasoning for
+          its arg-sets and timeouts, and a YAML round-trip drops all of them, so
+          the dump is a view of the configuration rather than a replacement.
+        - Overrides are deep-merged, so adopting a full dump as a user config
+          pins every key at today's value and silently shadows later changes to
+          the bundled config. A partial override is the supported shape: copy
+          only the keys being changed.
+        """
+        text = yaml.safe_dump(self.effective_config(resolved=resolved),
+                              sort_keys=False, default_flow_style=False,
+                              allow_unicode=True)
+        if not header:
+            return text
+
+        lines = ["# Effective solver-support registry, merged in this order:"]
+        lines.extend(f"#   {i}. {source}"
+                     for i, source in enumerate(self.config_sources, start=1))
+        if not self.config_sources:
+            lines.append("#   (none)")
+        if resolved:
+            lines.append("#")
+            lines.append("# Defaults a builder would supply are written out "
+                         "explicitly here.")
+        lines.extend([
+            "#",
+            "# For reading, not for adopting wholesale. Comments in the source",
+            "# files are not preserved, and overrides are deep-merged - so using",
+            "# this whole file as an override would pin every key at today's",
+            "# value and silently shadow later changes. Copy only what you mean",
+            "# to change.",
+            "",
+        ])
+        return "\n".join(lines) + "\n" + text
+
     def get_model_path(self, model_type: str) -> Path:
         """
         Get the file path for a model type.