arbiter-engine 0.2.8__tar.gz → 0.2.9__tar.gz

{arbiter_engine-0.2.8 → arbiter_engine-0.2.9}/CHANGELOG.md

@@ -34,6 +34,26 @@ useful-looking document and the less trustworthy one.
 
 ## [Unreleased]
 
+## [0.2.9] — 2026-09-25
+
+### Fixed
+
+- **`model_describe` and `gaps` work over every history this package ships.**
+  Both asked the session's history for `series_keys()`, which only the
+  in-memory store implemented, so a session built over
+  `SqliteObservationHistory` or `CalendarHistory` raised `AttributeError`, and
+  `rollout` ran with no seeded past (`precondition_unmet`). Both stores now list
+  their series. A history of the caller's own that implements only the five
+  `ObservationHistory` methods gets `unconsumed_observations: None` -- the report
+  could not be made -- rather than a crash or an empty list.
+- **A forecast is graded through whatever history the session reads.** The
+  ledger read the in-memory store's private series and skipped any other, so
+  a forecast made over `SqliteObservationHistory`, in a model declaring a
+  `calendar:`, or in a model with any derived indicator matured `ungradeable`
+  every time: measured, none of twelve graded in each case, against twelve of
+  twelve on the plain store. It reads through `get_values` now, and all four
+  grade alike. No calibration figure moves for a session that graded before.
+
 ## [0.2.8] — 2026-09-25
 
 ### Added

{arbiter_engine-0.2.8 → arbiter_engine-0.2.9}/CITATION.cff

@@ -9,7 +9,7 @@ authors:
     alias: "james-sheen"
   - name: "The Arbiter Project Authors"
 license: Apache-2.0
-version: "0.2.8"
+version: "0.2.9"
 date-released: "2026-09-25"
 repository-code: "https://github.com/james-sheen/arbiter"
 url: "https://github.com/james-sheen/arbiter"

{arbiter_engine-0.2.8 → arbiter_engine-0.2.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: arbiter-engine
-Version: 0.2.8
+Version: 0.2.9
 Summary: A detection engine that reports what it did not check.
 Project-URL: Homepage, https://github.com/james-sheen/arbiter
 Project-URL: Source, https://github.com/james-sheen/arbiter

{arbiter_engine-0.2.8 → arbiter_engine-0.2.9}/arbiter_engine/api.py

@@ -536,7 +536,7 @@ class EngineSession:
                 })
         return records
 
-    def unconsumed_observations(self) -> List[Dict[str, Any]]:
+    def unconsumed_observations(self) -> Optional[List[Dict[str, Any]]]:
         """Series this session holds that no declared indicator will ever read.
 
         This rules the second half of issue #1. ``add_observations``
@@ -564,9 +564,18 @@ class EngineSession:
         # report on the other input surface counted them as read. One
         # declaration, two verdicts, and the only way to silence the wrong one
         # was to declare the property a second time.
+        # A HISTORY THAT CANNOT LIST ITS SERIES CANNOT BE ASKED
+        # THIS, and the answer says so rather than crashing or claiming the
+        # empty list. `series_keys` is not one of the ABC's five methods; both
+        # stores this engine ships implement it, and a caller's own need not.
+        # `None` is the engine's convention for *not measured*, and every
+        # consumer in the family already reads this key through `or []`.
+        keys = getattr(self.history, "series_keys", None)
+        if keys is None:
+            return None
         declared: Dict[str, set] = self.readable_properties()
         records: List[Dict[str, Any]] = []
-        for entity_id, prop in self.history.series_keys():
+        for entity_id, prop in keys():
             entity = self.entities.get(entity_id)
             if entity is None:
                 reason = "unknown_entity"

{arbiter_engine-0.2.8 → arbiter_engine-0.2.9}/arbiter_engine/history/calendar.py

@@ -226,3 +226,8 @@ class CalendarHistory(ObservationHistory):
 
     def get_observation_count(self, entity_id: str, property_name: str) -> int:
         return self.inner.get_observation_count(entity_id, property_name)
+
+    def series_keys(self):
+        """The series the history underneath holds -- a calendar changes which
+        instants count, never which series exist."""
+        return self.inner.series_keys()

{arbiter_engine-0.2.8 → arbiter_engine-0.2.9}/arbiter_engine/history/sqlite_store.py

@@ -135,6 +135,24 @@ class SqliteObservationHistory(ObservationHistory):
         return [(_from_seconds(ts), text if text is not None else str(number))
                 for ts, number, text in rows]
 
+    def series_keys(self) -> List[Tuple[str, str]]:
+        """Every ``(entity_id, property_name)`` this store holds a series for.
+
+        Not one of the ABC's five, and the in-memory store had it
+        from on -- so every reader that enumerates a history was
+        written against the default and this class was never asked. Two of
+        them crashed on it: `model_describe` and `gaps` raised AttributeError
+        for any session built over this store, and `rollout` ran with no
+        imagined past behind it, declining `precondition_unmet`. Nothing
+        downstream had constructed one until a vertical kept its readings
+        across runs, which is the one use this class exists for.
+        """
+        with self._lock:
+            rows = self._connection.execute(
+                "SELECT DISTINCT entity_id, property FROM obs"
+                " ORDER BY entity_id, property").fetchall()
+        return [(str(entity_id), str(prop)) for entity_id, prop in rows]
+
     def get_observations(self, entity_id: str, start: datetime,
                          end: datetime) -> List[Observation]:
         with self._lock:

{arbiter_engine-0.2.8 → arbiter_engine-0.2.9}/arbiter_engine/residual/predict_vs_mirror.py

@@ -48,7 +48,7 @@ import uuid
 from collections import deque
 from dataclasses import dataclass, field
 from datetime import datetime, timedelta
-from ..clock import as_naive_utc, now_utc
+from ..clock import as_naive_utc, as_of, now_utc
 # the id the yardstick is filed under, read from the module that
 # owns it rather than re-spelled here. Two spellings of one literal is how
 # the exclusion below would silently stop excluding anything.
@@ -698,18 +698,47 @@ class PredictionLedger:
         property_name: str,
         start: datetime,
         end: datetime,
+        now: Optional[datetime] = None,
     ) -> List[Tuple[datetime, float]]:
-        """Numeric observations for (entity, property) in [start, end],
-        read defensively from the in-memory histories."""
+        """Numeric observations for (entity, property) in [start, end], read
+        through each history's own `get_values` -- never its internals.
+
+        This read the in-memory store's private `_history` dict and
+        SKIPPED any history without one. `check` hands the ledger the session's
+        READING history, which is the raw store only when the model declares
+        neither a calendar nor a derived indicator; otherwise it is a view, and
+        so is the durable store. Measured, the same twenty minutes of one tank
+        filing a forecast a minute: the in-memory store graded 12 of 12; the
+        durable store, a declared calendar and a model with one derived
+        indicator graded NONE, all twelve `ungradeable`. A calibration figure
+        that could never be anything but empty, reported without an error --
+        beside a comment in `check` saying the view was passed so that a
+        derived forecast WOULD have something to score against.
+
+        `get_values` is the one reader every history implements, and it ends
+        at the engine's clock -- so the read is pinned to the GRADING instant,
+        `now`, which a caller may pass explicitly and which the private dict
+        never consulted. The window reaches back to `start`, a microsecond
+        wider because the stores bound it exclusively, and is then cut to
+        exactly `[start, end]`. A calendar view answers a window in OPEN time,
+        which reaches further back in wall time, and the cut is what makes
+        that harmless.
+        """
         out: List[Tuple[datetime, float]] = []
-        for history in histories or []:
-            raw = getattr(history, "_history", None)
-            if not isinstance(raw, dict):
-                continue
-            for ts, value in raw.get((entity_id, property_name)) or []:
-                if (isinstance(ts, datetime) and isinstance(value, (int, float))
-                        and start <= ts <= end):
-                    out.append((ts, float(value)))
+        at = as_naive_utc(now) if now is not None else now_utc()
+        span = at - start + timedelta(microseconds=1)
+        if span.total_seconds() <= 0:
+            return out
+        with as_of(at):
+            for history in histories or []:
+                reader = getattr(history, "get_values", None)
+                if reader is None:
+                    continue
+                for ts, value in reader(entity_id, property_name, span) or []:
+                    if (isinstance(ts, datetime)
+                            and isinstance(value, (int, float))
+                            and start <= ts <= end):
+                        out.append((ts, float(value)))
         return out
 
     def _grade_distribution_record(
@@ -743,7 +772,7 @@ class PredictionLedger:
             return None
         observations = self._observations_for(
             list(histories), record.entity_id, record.indicator or "",
-            record.predicted_at, window_end)
+            record.predicted_at, window_end, now)
         if not observations:
             record.verdict = GRADE_UNGRADEABLE
             record.graded_at = now
@@ -779,7 +808,7 @@ class PredictionLedger:
             return None
         observations = self._observations_for(
             list(histories), record.entity_id, record.indicator or "",
-            record.predicted_at, window_end)
+            record.predicted_at, window_end, now)
         target = record.predicted_at + timedelta(seconds=record.horizon_s)
         # AND EACH READING GRADES ONE HORIZON, not every horizon
         # whose window contains it. This took the observation closest to the

{arbiter_engine-0.2.8 → arbiter_engine-0.2.9}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "arbiter-engine"
-version = "0.2.8"
+version = "0.2.9"
 description = "A detection engine that reports what it did not check."
 requires-python = ">=3.10"
 license = "Apache-2.0"

arbiter_engine-0.2.9/tests/test_every_history_the_engine_ships_can_be_described.py

@@ -0,0 +1,260 @@
+"""Every history this engine ships can be described, gapped and rolled from.
+
+`SqliteObservationHistory` and `CalendarHistory` have been supported names since
+0.2.3. `model_describe` and `gaps` both asked the session's history for
+`series_keys()` -- a method the in-memory store has and the ABC does not
+require -- and so both RAISED AttributeError for any session built over either
+of the other two. `rollout` checked for the method and, finding none, ran with
+no imagined past, declining `precondition_unmet`.
+
+NOTHING DOWNSTREAM HAD EVER CONSTRUCTED ONE, which is how it survived. The first
+caller was a vertical keeping its readings across separate runs -- the one use
+the durable store exists for -- and its first `detect` died in the describe
+call. Every test of the durable store here fed it and read it back through
+`get_values`, which is the half that worked.
+
+So this is asked of EVERY history the engine ships, through the verbs a caller
+actually uses, rather than of one method on one class.
+"""
+
+from __future__ import annotations
+
+import pathlib
+from datetime import datetime, timedelta
+
+import pytest
+
+from arbiter_engine import api
+from arbiter_engine.history.calendar import (CalendarHistory,
+                                                          SessionCalendar)
+from arbiter_engine.history.observation import \
+    InMemoryObservationHistory
+from arbiter_engine.history.sqlite_store import \
+    SqliteObservationHistory
+from arbiter_engine.interfaces import ObservationHistory
+
+MODEL = """
+domain:
+  id: histories
+  name: every shipped history
+  entity_types: [Tank]
+  indicators:
+    Tank:
+      - name: level
+        type: NUMERIC
+        axioms: [BOUNDEDNESS]
+        warning: 80
+        critical: 90
+"""
+
+AT = datetime(2026, 9, 25, 12, 0)
+
+
+def _always_open():
+    """A calendar with no sessions, which counts every instant -- the history
+    underneath is what is under test, not the calendar."""
+    return SessionCalendar()
+
+
+HISTORIES = {
+    "in_memory": lambda: InMemoryObservationHistory(),
+    "sqlite": lambda: SqliteObservationHistory(":memory:"),
+    "calendar_over_memory": lambda: CalendarHistory(
+        InMemoryObservationHistory(), _always_open()),
+    "calendar_over_sqlite": lambda: CalendarHistory(
+        SqliteObservationHistory(":memory:"), _always_open()),
+}
+
+
+def _session(history, tmp_path):
+    path = tmp_path / "model.yaml"
+    path.write_text(MODEL)
+    session = api.EngineSession(history=history)
+    session.load_model(str(path))
+    session.add_entity("tank-1", "Tank", {"level": 50.0})
+    with api.as_of(AT):
+        session.add_observations("tank-1", "level",
+                                 [(AT - timedelta(minutes=5 - i), 50.0 + i)
+                                  for i in range(5)])
+        # A series no indicator reads -- the report this breaks exists for it.
+        session.add_observations("tank-1", "levle",
+                                 [(AT - timedelta(minutes=1), 1.0)])
+    return session
+
+
+@pytest.fixture(params=sorted(HISTORIES))
+def shipped(request, tmp_path):
+    return request.param, _session(HISTORIES[request.param](), tmp_path)
+
+
+class TestTheVerbsThatEnumerateAHistory:
+
+    def test_model_describe_answers(self, shipped):
+        name, session = shipped
+        with api.as_of(AT):
+            payload = api.model_describe(session).to_dict()
+        assert "unconsumed_observations" in payload, name
+
+    def test_gaps_answers(self, shipped):
+        name, session = shipped
+        with api.as_of(AT):
+            api.check(session)
+            api.gaps(session).to_dict()
+
+    def test_the_unread_series_is_reported_the_same_way_by_all_of_them(
+            self, shipped):
+        """Same feed, same report, whichever store holds it -- the store is a
+        durability choice and must not change what the engine says."""
+        name, session = shipped
+        records = session.unconsumed_observations()
+        assert [(r["entity_id"], r["property"], r["reason"]) for r in records] == [
+            ("tank-1", "levle", "undeclared_property")], name
+
+    def test_a_rollout_is_seeded_from_it(self, shipped):
+        """`precondition_unmet` is what a rollout says when it could not read
+        the past; on a store the engine ships, it must never say it."""
+        name, session = shipped
+        with api.as_of(AT):
+            payload = api.rollout(session, horizon_s=120.0,
+                                  step_s=60.0).to_dict()["simulation"]
+        reasons = {d["reason"] for d in payload.get("not_checked", [])}
+        assert "precondition_unmet" not in reasons, (name, reasons)
+
+
+class TestTheDurableStoreListsItsSeries:
+
+    def test_distinct_and_ordered(self):
+        store = SqliteObservationHistory(":memory:")
+        for entity, prop in (("b", "x"), ("a", "y"), ("a", "x"), ("a", "x")):
+            store.add(entity, prop, 1.0, AT)
+        assert store.series_keys() == [("a", "x"), ("a", "y"), ("b", "x")]
+
+    def test_it_survives_the_process(self, tmp_path):
+        path = str(tmp_path / "h.sqlite")
+        SqliteObservationHistory(path).add("tank-1", "level", 1.0, AT)
+        assert SqliteObservationHistory(path).series_keys() == [("tank-1", "level")]
+
+
+class _OnlyTheAbc(ObservationHistory):
+    """A caller's own history, implementing exactly the five methods required."""
+
+    def __init__(self):
+        self._inner = InMemoryObservationHistory()
+
+    def add(self, *args, **kwargs):
+        return self._inner.add(*args, **kwargs)
+
+    def get_values(self, *args, **kwargs):
+        return self._inner.get_values(*args, **kwargs)
+
+    def get_states(self, *args, **kwargs):
+        return self._inner.get_states(*args, **kwargs)
+
+    def get_observations(self, *args, **kwargs):
+        return self._inner.get_observations(*args, **kwargs)
+
+    def get_observation_count(self, *args, **kwargs):
+        return self._inner.get_observation_count(*args, **kwargs)
+
+
+class TestAHistoryThatCannotListItsSeriesSaysSo:
+    """The ABC does not require `series_keys`, so a caller's history may lack it.
+    The report it feeds cannot be made then -- and `[]` would say it was made
+    and found nothing."""
+
+    def test_the_report_is_none_not_empty(self, tmp_path):
+        session = _session(_OnlyTheAbc(), tmp_path)
+        assert session.unconsumed_observations() is None
+
+    def test_describe_still_answers(self, tmp_path):
+        session = _session(_OnlyTheAbc(), tmp_path)
+        with api.as_of(AT):
+            payload = api.model_describe(session).to_dict()
+        assert payload["unconsumed_observations"] is None
+
+
+FORECAST_MODEL = """
+domain:
+  id: graded
+  name: a forecast graded through every view
+  entity_types: [Tank]
+  indicators:
+    Tank:
+      - name: level
+        type: NUMERIC
+        axioms: [BOUNDEDNESS]
+        warning: 1000
+        critical: 2000
+        window: 1h
+        dynamics: {model: random_walk}
+"""
+
+#: A calendar open around the clock is still a declared calendar, so the view
+#: `check` hands the ledger is the calendar wrapper -- which is the point.
+CALENDAR = ("  calendar:\n    sessions:\n      - {days: [mon, tue, wed, thu, fri, "
+            "sat, sun], open: '00:00', close: '23:59'}\n")
+
+#: One derived indicator anywhere in the model wraps the whole reading history.
+DERIVED = ("      - name: double\n        type: NUMERIC\n        axioms: [BOUNDEDNESS]\n"
+           "        warning: 1000\n        critical: 2000\n"
+           "        derived: {expression: \"level + level\"}\n")
+
+VIEWS = {
+    "in_memory": (FORECAST_MODEL, InMemoryObservationHistory),
+    "sqlite": (FORECAST_MODEL, lambda: SqliteObservationHistory(":memory:")),
+    "calendar": (FORECAST_MODEL.replace("  entity_types:", CALENDAR + "  entity_types:"),
+                 InMemoryObservationHistory),
+    "derived": (FORECAST_MODEL + DERIVED, InMemoryObservationHistory),
+}
+
+
+def _graded(model_text, history, tmp_path):
+    """Twenty minutes of one tank, a forecast filed each minute from the
+    seventh, one fresh session per minute over the same two stores."""
+    import random
+
+    tmp_path.mkdir(parents=True, exist_ok=True)
+    path = tmp_path / "m.yaml"
+    path.write_text(model_text)
+    rng, level, ledger = random.Random(1), 100.0, None
+    for minute in range(20):
+        at = AT + timedelta(minutes=minute)
+        level += rng.gauss(0.0, 1.0)
+        with api.as_of(at):
+            session = api.EngineSession(history=history, ledger=ledger)
+            session.load_model(str(path))
+            session.add_entity("t1", "Tank", {"level": level})
+            session.add_observations("t1", "level", [(at, level)])
+            ledger = session.ledger
+            api.check(session)
+            if minute >= 6:
+                api.project(session, horizon_s=60.0)
+    return ledger.calibration(), type(session.reading_history()).__name__
+
+
+class TestAForecastIsGradedThroughEveryView:
+    """The ledger read the in-memory store's private dict and skipped anything
+    else, so the durable store, a declared calendar and one derived indicator
+    each graded NONE of twelve forecasts -- every one `ungradeable`."""
+
+    @pytest.mark.parametrize("view", sorted(VIEWS))
+    def test_it_grades_what_the_plain_store_grades(self, view, tmp_path):
+        text, make = VIEWS[view]
+        cal, name = _graded(text, make(), tmp_path / view)
+        plain_text, plain_store = VIEWS["in_memory"]
+        control, _ = _graded(plain_text, plain_store(), tmp_path / "control")
+        assert control["confirmed"] + control["falsified"] > 0, (
+            "the control graded nothing, so parity with it would be free")
+        assert cal["ungradeable"] == 0, (view, name, cal["ungradeable"])
+        assert (cal["confirmed"], cal["falsified"]) == (
+            control["confirmed"], control["falsified"]), (view, name)
+
+    def test_the_views_are_really_different_objects(self, tmp_path):
+        """Non-vacuity: if every case were the plain store underneath, the
+        parity above would be free."""
+        names = {view: _graded(text, make(), tmp_path / view)[1]
+                 for view, (text, make) in VIEWS.items()}
+        assert names == {"in_memory": "InMemoryObservationHistory",
+                         "sqlite": "SqliteObservationHistory",
+                         "calendar": "CalendarHistory",
+                         "derived": "DerivedHistoryView"}, names