config: one configuration could produce a grounded answer with no source

`Config(max_passages=0)` returned an answer whose `kind` was "grounded",
whose `to_payload()["grounded"]` was true, and which had no sources and no
text. Composition slices the accepted passages to `accepted[:max_passages]`,
so zero passages were quoted while the trace still said passages had been
accepted — the refusal branch never ran, because retrieval had not failed.
That is the one outcome this project says it does not have, reached through
the constructor instead of through the corpus. `max_passages=-1`, a plausible
spelling of "no limit", was quieter and no better: `[:-1]` drops the last
accepted passage.

`cairn.toml` could not reach either, because `load_config` checked the bounds
after building the object. Nothing else did — and this is a reference
implementation whose whole invitation is that an agency imports it. There were
also no tests over configuration loading at all.

The bounds move onto `Config.__post_init__`, so a file and a caller are held
to the same rules and there is one place they are stated. `load_config`'s
duplicate check is gone. Three tests: the unusable values are refused by both
routes, and every usable configuration still grounds on at least one source or
refuses with none.

No behaviour change for any valid configuration: the bundle re-records
byte-identical and the gate returns the same run id.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PR8WtSFsAW68eGYW13eb8j

Author: ChelseaKR

cairn/config.py

@@ -57,6 +57,38 @@ class Config:
         default_factory=lambda: dict(_DEMO_CONTACTS)
     )
 
+    def __post_init__(self) -> None:
+        """Validate on construction, not only on load.
+
+        These bounds used to live in :func:`load_config`, which meant they
+        held for `cairn.toml` and for nothing else. This is a reference
+        implementation an agency is invited to import, and
+        ``Config(max_passages=0)`` — a plausible reading of "no limit" —
+        produced a **grounded answer with no sources and no text**: composition
+        sliced the accepted passages to nothing while the trace still said
+        passages had been accepted, so `kind` stayed "grounded" and
+        `to_payload()["grounded"]` stayed true. That is the one thing this
+        project says cannot happen, arriving through the constructor rather
+        than through the corpus. A negative value was quieter and no better:
+        `accepted[:-1]` silently drops the *last* accepted passage rather than
+        meaning "all of them".
+
+        The invariant is a property of the configuration, so it is enforced
+        where the configuration is made.
+        """
+        if not 0.0 < self.threshold <= 1.0:
+            raise ConfigError(
+                "retrieval.threshold must be in (0, 1]: scores are bounded cosine"
+            )
+        if self.max_passages < 1:
+            raise ConfigError(
+                "retrieval.max_passages must be >= 1: composing zero passages "
+                "would emit an answer with no source behind it, which is the "
+                "one outcome this system does not have"
+            )
+        if self.candidates < 1:
+            raise ConfigError("retrieval.candidates must be >= 1")
+
     def contact_for(self, lang: str) -> str:
         """The human channel a refusal in ``lang`` should point to. Falls back
         to the single ``contact`` string, which is what a deployment that
@@ -109,7 +141,9 @@ def load_config(path: str | Path | None = None) -> Config:
     language = data.get("language", {})
     defaults = Config()
     contact = _get(refusal, "contact", str, defaults.contact)
-    cfg = Config(
+    # Bounds are checked by Config itself (see __post_init__), so a file and a
+    # caller cannot be held to two different sets of rules.
+    return Config(
         corpus_path=_get(corpus, "path", str, defaults.corpus_path),
         index_path=_get(index, "path", str, defaults.index_path),
         threshold=_get(retrieval, "threshold", float, defaults.threshold),
@@ -122,8 +156,3 @@ def load_config(path: str | Path | None = None) -> Config:
         contact=contact,
         contact_by_language=_contacts(refusal),
     )
-    if not 0.0 < cfg.threshold <= 1.0:
-        raise ConfigError("retrieval.threshold must be in (0, 1]: scores are bounded cosine")
-    if cfg.max_passages < 1 or cfg.candidates < 1:
-        raise ConfigError("retrieval.max_passages and retrieval.candidates must be >= 1")
-    return cfg

tests/test_answering.py

@@ -6,10 +6,11 @@
 calibration drift silently.
 """
 
+import tempfile
 import unittest
 from pathlib import Path
 
-from cairn.config import Config
+from cairn.config import Config, ConfigError, load_config
 from cairn.engine import ask
 from cairn.index import build_index
 from cairn.retrieve import retrieve
@@ -112,6 +113,69 @@ def test_empty_and_nonsense_queries_refuse(self):
                 self.assertEqual(self.answer(question).kind, "refusal")
 
 
+class TestNoConfigurationCanEmitAnUnsourcedAnswer(EngineHarness):
+    """The core promise, held against the configuration rather than the corpus.
+
+    "There is no code path that emits an answer without supporting corpus
+    passages" was true of every corpus and every question, and false of one
+    configuration. `Config(max_passages=0)` — a plausible reading of "no
+    limit" — sliced the accepted passages away in composition while the trace
+    still said passages had been accepted, so `kind` stayed `"grounded"`,
+    `to_payload()["grounded"]` stayed true, and what came back was an empty
+    answer with no sources under it. A negative value was quieter: `[:-1]`
+    drops the last accepted passage rather than meaning "all of them".
+
+    `cairn.toml` could not reach either, because `load_config` checked the
+    bounds. Nothing else did, and this is a reference implementation whose
+    whole invitation is that somebody imports it. The bounds live on `Config`
+    now, and nothing here had a test.
+    """
+
+    UNUSABLE = (
+        ("max_passages", 0),
+        ("max_passages", -1),
+        ("candidates", 0),
+        ("threshold", 0.0),
+        ("threshold", 1.5),
+    )
+
+    def test_a_configuration_that_could_break_the_promise_is_refused(self):
+        for key, value in self.UNUSABLE:
+            with self.subTest(**{key: value}):
+                with self.assertRaises(ConfigError):
+                    Config(**{key: value})
+
+    def test_the_file_and_the_constructor_are_held_to_the_same_bounds(self):
+        # Two sets of rules is how the caller-side hole opened in the first
+        # place: the loader enforced them and the type did not.
+        for key, value in self.UNUSABLE:
+            with self.subTest(**{key: value}), tempfile.TemporaryDirectory() as tmp:
+                path = Path(tmp) / "cairn.toml"
+                path.write_text(f"[retrieval]\n{key} = {value}\n", encoding="utf-8")
+                with self.assertRaises(ConfigError):
+                    load_config(path)
+
+    def test_every_usable_configuration_grounds_on_at_least_one_source(self):
+        for cfg in (
+            Config(),
+            Config(max_passages=1),
+            Config(max_passages=8),
+            Config(candidates=1),
+            Config(threshold=0.99),
+            Config(cross_language_fallback=False),
+        ):
+            for question in (IN_CORPUS[0][0], OFF_TOPIC[0]):
+                with self.subTest(cfg=cfg.max_passages, question=question):
+                    answer = ask(question, self.index, cfg).answer
+                    payload = answer.to_payload()
+                    self.assertEqual(payload["grounded"], answer.kind == "grounded")
+                    if answer.kind == "grounded":
+                        self.assertTrue(answer.sources, "grounded with nothing under it")
+                        self.assertTrue(answer.text.strip())
+                    else:
+                        self.assertEqual(answer.sources, ())
+
+
 class TestThresholdCalibration(EngineHarness):
     """The default threshold is a measurement, and this is the measurement."""