arbiter-engine 0.2.6__tar.gz → 0.2.7__tar.gz

{arbiter_engine-0.2.6 → arbiter_engine-0.2.7}/CHANGELOG.md

@@ -34,7 +34,42 @@ useful-looking document and the less trustworthy one.
 
 ## [Unreleased]
 
-_Nothing yet._
+## [0.2.7] — 2026-09-25
+
+### Added
+
+- **Every fitted transition proposal now carries a `replay`**: what adopting it
+  would have caught, as counts against the corpus that recorded what happened.
+  `n` and `r_squared` say how well a gain fits the data it was fitted on, which
+  is a different question.
+- **`replay_unavailable` (`REPLAY_UNAVAILABLE`) is the answer when no corpus was
+  supplied.** It carries its reason and no counts: a proposal nobody could test
+  is not a proposal that failed, and a zero cannot tell those apart. No rate is
+  reported, for the reason the surprise score reports none.
+- **`hypothesize(session, entity_id)` — what could explain a finding, ranked.**
+  The inverse of `gaps`: that verb says what the model does not declare, this
+  says what the world might be doing given what it does. Each candidate is a
+  DECLARED causal ancestor, scored by the same inference `infer` runs, carrying
+  the reading that would discriminate it and the declared action that could test
+  it. `MAX_HOPS` bounds the walk. It ranks nothing the author did not connect.
+- **`arbiter_engine.producers.baseline_learner`, a reference producer.** A
+  damped-trend exponential smoother, shipped because the engine's own baseline
+  is a random walk and a random walk is the right floor and a poor opponent. It
+  gets no privilege: it reads a session through `reading_history()` and files
+  through `ingest_forecasts` like any outside forecaster. `MINIMUM_POINTS` is
+  the series length below which it returns nothing rather than a fitted number.
+- **`model_describe(session, surprises=...)`** takes the corpus to replay
+  against. The model is restored afterwards whether or not the replay ran --
+  deriving and adopting stay separate.
+
+### Changed
+
+- **The proposal surface now records WHO may write a fitted gain down, and it
+  is not this package.** A tool downstream -- a separate distribution, a
+  separate command, a proposal named by a person, a basis recorded in the file
+  -- may adopt one into a model it owns. Nothing here opens a model for
+  writing, and a test compares the file's bytes rather than reading this source
+  for a call. The first such writer is `bmc-sensor-audit adopt`.
 
 ## [0.2.6] — 2026-09-24
 

{arbiter_engine-0.2.6 → arbiter_engine-0.2.7}/CITATION.cff

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

{arbiter_engine-0.2.6 → arbiter_engine-0.2.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: arbiter-engine
-Version: 0.2.6
+Version: 0.2.7
 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
@@ -514,7 +514,7 @@ The engine is open. The knowledge and the operations are not.
 
 ## Status
 
-**v0.2.** 95 Python files, 93 modules importing on the declared dependencies alone, 15 supported
+**v0.2.** 98 Python files, 96 modules importing on the declared dependencies alone, 15 supported
 names — **counted in this repository**, which is the package you are holding.
 
 That basis is stated because it is easy to get wrong in a way nobody notices. The build adds one
@@ -523,7 +523,7 @@ are holding — and this line published the smaller figure until 2026-08-12, whe
 falsify it with `find . -name '*.py' | wc -l`. A checkable false claim, in the Status section of a
 project whose subject is checkable claims. Count the artifact, never an earlier stage of it.
 
-The import figure carries the same hazard one layer down, and it depends on what you have installed. Sweeping the package where `scipy` happens to be present imports 94; on the declared dependencies alone it is the 93 above, because `propagation.lp_confidence` is the one module that needs `scipy` and it is a deep path outside the supported surface. Count the artifact **in the state the reader will have it**, not in the state the person measuring happens to be standing in — this line quoted the with-`scipy` figure until 2026-08-12, which no reader installing normally could reproduce.
+The import figure carries the same hazard one layer down, and it depends on what you have installed. Sweeping the package where `scipy` happens to be present imports 97; on the declared dependencies alone it is the 96 above, because `propagation.lp_confidence` is the one module that needs `scipy` and it is a deep path outside the supported surface. Count the artifact **in the state the reader will have it**, not in the state the person measuring happens to be standing in — this line quoted the with-`scipy` figure until 2026-08-12, which no reader installing normally could reproduce.
 
 **The supported-name count went stale in exactly the way this section warns about.** It read
 three short for the release that added `SqliteObservationHistory`, `SessionCalendar` and
@@ -540,7 +540,7 @@ committed by the paragraph. The figures are described here now rather than quote
 rule the changelog states for its own errata: a correction that reproduces the string it corrects
 is that string to a checker.
 
-**And the count is of SUBMODULES: the root package is not one of them.** Walking `arbiter_engine` for what it contains gives 93; adding the package you imported to reach them gives 94. Both are honest and they are answers to different questions, so a reader who recounts and gets one more has not found a defect — they have used the other convention. Stated because someone did exactly that from outside, and a number published without its predicate can only be agreed with or disagreed with, never checked. **Every figure in this paragraph moved by one when `assumptions` landed, and nothing went red for two rounds** -- the guard that compares them to the artifact only runs when a built tree exists, so it is silent in every session that does not build one. A check conditioned on an artifact is not a check that runs.
+**And the count is of SUBMODULES: the root package is not one of them.** Walking `arbiter_engine` for what it contains gives 96; adding the package you imported to reach them gives 97. Both are honest and they are answers to different questions, so a reader who recounts and gets one more has not found a defect — they have used the other convention. Stated because someone did exactly that from outside, and a number published without its predicate can only be agreed with or disagreed with, never checked. **Every figure in this paragraph moved by TWO when the reference producer landed, and by one when `assumptions` did, and that earlier move went unnoticed for two rounds** -- the guard that compares them to the artifact only runs when a built tree exists, so it is silent in every session that does not build one. A check conditioned on an artifact is not a check that runs.
 
 Honest boundaries, stated because you would otherwise find them yourself:
 

{arbiter_engine-0.2.6 → arbiter_engine-0.2.7}/README.md

@@ -476,7 +476,7 @@ The engine is open. The knowledge and the operations are not.
 
 ## Status
 
-**v0.2.** 95 Python files, 93 modules importing on the declared dependencies alone, 15 supported
+**v0.2.** 98 Python files, 96 modules importing on the declared dependencies alone, 15 supported
 names — **counted in this repository**, which is the package you are holding.
 
 That basis is stated because it is easy to get wrong in a way nobody notices. The build adds one
@@ -485,7 +485,7 @@ are holding — and this line published the smaller figure until 2026-08-12, whe
 falsify it with `find . -name '*.py' | wc -l`. A checkable false claim, in the Status section of a
 project whose subject is checkable claims. Count the artifact, never an earlier stage of it.
 
-The import figure carries the same hazard one layer down, and it depends on what you have installed. Sweeping the package where `scipy` happens to be present imports 94; on the declared dependencies alone it is the 93 above, because `propagation.lp_confidence` is the one module that needs `scipy` and it is a deep path outside the supported surface. Count the artifact **in the state the reader will have it**, not in the state the person measuring happens to be standing in — this line quoted the with-`scipy` figure until 2026-08-12, which no reader installing normally could reproduce.
+The import figure carries the same hazard one layer down, and it depends on what you have installed. Sweeping the package where `scipy` happens to be present imports 97; on the declared dependencies alone it is the 96 above, because `propagation.lp_confidence` is the one module that needs `scipy` and it is a deep path outside the supported surface. Count the artifact **in the state the reader will have it**, not in the state the person measuring happens to be standing in — this line quoted the with-`scipy` figure until 2026-08-12, which no reader installing normally could reproduce.
 
 **The supported-name count went stale in exactly the way this section warns about.** It read
 three short for the release that added `SqliteObservationHistory`, `SessionCalendar` and
@@ -502,7 +502,7 @@ committed by the paragraph. The figures are described here now rather than quote
 rule the changelog states for its own errata: a correction that reproduces the string it corrects
 is that string to a checker.
 
-**And the count is of SUBMODULES: the root package is not one of them.** Walking `arbiter_engine` for what it contains gives 93; adding the package you imported to reach them gives 94. Both are honest and they are answers to different questions, so a reader who recounts and gets one more has not found a defect — they have used the other convention. Stated because someone did exactly that from outside, and a number published without its predicate can only be agreed with or disagreed with, never checked. **Every figure in this paragraph moved by one when `assumptions` landed, and nothing went red for two rounds** -- the guard that compares them to the artifact only runs when a built tree exists, so it is silent in every session that does not build one. A check conditioned on an artifact is not a check that runs.
+**And the count is of SUBMODULES: the root package is not one of them.** Walking `arbiter_engine` for what it contains gives 96; adding the package you imported to reach them gives 97. Both are honest and they are answers to different questions, so a reader who recounts and gets one more has not found a defect — they have used the other convention. Stated because someone did exactly that from outside, and a number published without its predicate can only be agreed with or disagreed with, never checked. **Every figure in this paragraph moved by TWO when the reference producer landed, and by one when `assumptions` did, and that earlier move went unnoticed for two rounds** -- the guard that compares them to the artifact only runs when a built tree exists, so it is silent in every session that does not build one. A check conditioned on an artifact is not a check that runs.
 
 Honest boundaries, stated because you would otherwise find them yourself:
 

{arbiter_engine-0.2.6 → arbiter_engine-0.2.7}/STANCE.md

@@ -79,6 +79,28 @@ declaration.
 its own stated spread. It does not order producers, recommend one, or carry a
 reputation between sessions.
 
+## The reference producer, which gets none of the above either
+
+The package ships one: `arbiter_engine.producers.baseline_learner`, a
+damped-trend exponential smoother. It exists because the engine's own baseline
+is a **random walk** — it predicts the last value and widens with the horizon —
+and a random walk is the right floor and a poor opponent. Anything that notices
+a series is going somewhere beats it, so *beats the baseline* against a random
+walk alone says almost nothing.
+
+**It is a producer, not a feature.** It reads a session through
+`reading_history()`, the accessor this engine tells every reader to use, and
+files ordinary records through `ingest_forecasts`. It imports no checker, is
+handed no privilege an outside forecaster would be refused, and is scored by
+exactly the rules above — including `not_a_producers_submission` if its records
+carry a `source`. A baseline with access the competition lacks is not a
+baseline, and the suite asserts its import surface as well as its score.
+
+**It refuses rather than guessing.** A series shorter than its minimum gets no
+forecast, and one whose points are not ordered in time is refused rather than
+sorted — re-ordering a series nobody gave you that way is how a producer comes
+to score well on data it invented.
+
 ## Why the engine sets its own records aside
 
 The engine is a producer too. `rollout` files what it projected; every

{arbiter_engine-0.2.6 → arbiter_engine-0.2.7}/arbiter_engine/api.py

@@ -754,7 +754,16 @@ _FEEDERS_ON_THE_SUPPORTED_SURFACE = (
 )
 
 
-def _proposed_transitions(session: EngineSession) -> Dict[str, Any]:
+def _replay_proposal(session: EngineSession, proposal: Any,
+                     surprises: Any) -> Dict[str, Any]:
+    """One proposal's replay, or the refusal that stands in for it."""
+    from arbiter_engine.surprises import replay_proposal
+
+    return replay_proposal(session, proposal, surprises)
+
+
+def _proposed_transitions(session: EngineSession,
+                          surprises: Any = None) -> Dict[str, Any]:
     """Fitted gains, their support, and any that contradict a declaration.
 
     Reported from `model_describe` rather than from a verb of its
@@ -767,6 +776,32 @@ def _proposed_transitions(session: EngineSession) -> Dict[str, Any]:
     author's claim about the system, and an engine that silently replaced it
     with a fitted number would leave nobody able to say what the model
     asserts -- the file would no longer be the model.
+
+    RULED 2026-09-25, A VERTICAL MAY WRITE ONE DOWN; THIS ENGINE
+    STILL MAY NOT. The phase plan asked for an `adopt <proposal_id>` verb,
+    and this package had refused one twice -- here and in
+    `causal/discovery.py`. The ruling separates the two things that question
+    runs together. What is refused above is an ENGINE acting on its own
+    measurement: a process handed a file to read, rewriting it, on a number
+    nobody asked it for. What is now permitted is a tool DOWNSTREAM of this
+    one, whose own author maintains the file, invoked by a person who typed
+    the proposal's name, writing the number with a basis beside it saying
+    where it came from. The file still says what the model asserts. It now
+    says the author chose to assert a fitted number, and says so in the file.
+
+    THE DISTANCE IS THE WHOLE OF THE RULING, AND NONE OF IT IS HERE: a
+    separate distribution, a separate command, a named proposal, a recorded
+    basis, and a gate that refuses a number which would have caught nothing.
+    Take any one of those away and what is left is the thing refused above.
+
+    So nothing in this package opens a model for writing, and the shipped
+    suite holds that by RUNNING this surface -- the replay included, which
+    substitutes a proposal to measure it -- and comparing the model file's
+    bytes, size and modification time afterwards. Not by reading this source
+    for a `write` call, which is a check on text about a claim concerning
+    behaviour. The first downstream writer is `bmc-sensor-audit adopt`, which
+    writes a fitted `gain` and its `gain_basis` into the supplemental file that
+    vertical's operator already maintains by hand.
     """
     from arbiter_engine.twin.transition_learner import (
         MINIMUM_PAIRED_SAMPLES, learn_transitions,
@@ -816,7 +851,14 @@ def _proposed_transitions(session: EngineSession) -> Dict[str, Any]:
              # author's behalf is the one thing this surface does not do.
              "residual_autocorrelation": p.residual_autocorrelation,
              "gain_sigma_assumes_independent_residuals":
-                 p.standard_error_assumes_independence}
+                 p.standard_error_assumes_independence,
+             # WOULD ADOPTING THIS HAVE CAUGHT MORE. A proposal is a
+             # number somebody has to decide about, and `n` and `r_squared`
+             # answer how well it fits the data it was fitted on, which is not
+             # the same question. Without a corpus this is a REFUSAL carrying
+             # its reason, never a zero: a proposal nobody could test is not a
+             # proposal that failed.
+             "replay": _replay_proposal(session, p, surprises)}
             for p in proposals],
         "not_fitted": [
             {"edge": r.location, "reason": r.reason, "detail": r.detail}
@@ -1051,7 +1093,8 @@ def _transition_coverage(model, session: Optional[EngineSession] = None
     }
 
 
-def model_describe(session: EngineSession) -> Envelope:
+def model_describe(session: EngineSession,
+                   surprises: Any = None) -> Envelope:
     """What domain is loaded: entity types, indicators, declared axioms.
 
     This is the grounding tool. An agent calls it before reasoning so it
@@ -1150,7 +1193,7 @@ def model_describe(session: EngineSession) -> Envelope:
         # ones the author declared. Proposals: nothing here has changed the
         # model, and a `gain: estimate` transition projects no value until a
         # number is adopted into the YAML.
-        "proposed_transitions": _proposed_transitions(session),
+        "proposed_transitions": _proposed_transitions(session, surprises),
         # the list, mounted where a MODEL fact belongs. `check` has
         # carried it since it was added; this verb, whose whole question is
         # *did my model load the way I wrote it*, did not -- so a reader
@@ -2461,6 +2504,49 @@ def entail(session: EngineSession, adopt: bool = False) -> Envelope:
     return _WithPayload(envelope, payload)
 
 
+def hypothesize(session: EngineSession, entity_id: str,
+                report_above: Optional[float] = None) -> Envelope:
+    """What could explain a finding on `entity_id`, ranked, with what to read next.
+
+    THE INVERSE OF `gaps`. That verb says what the MODEL does not declare; this
+    says what the WORLD might be doing given what it does — the same question
+    turned around, and the one an operator has after a finding names an entity
+    that is wrong.
+
+    Each candidate is a DECLARED causal ancestor, scored by the same inference
+    `infer` runs, and carries the reading that would discriminate it and the
+    declared action that could test it. Nothing here searches for a cause
+    outside the graph: an engine proposing causes nobody declared would be doing
+    the inference this project removed from `role:` and from flow direction.
+
+    **It is only as good as the evidence severity.** With every breach at
+    `warning` and no `causal.evidence_severity:` declared, no finding counts as
+    evidence, every posterior sits at its prior, and the ranking is an ordering
+    of priors rather than of explanations. Measured on the shipped substation
+    specimen: with both panels in the warning band the supply outranks the
+    feeder 0.0104 to 0.0018, and with both below critical the feeder ranks first
+    at 0.962. Same topology, same question, opposite answers — so read the
+    `evidence_severity_not_declared` stamp before reading this ranking.
+    """
+    from arbiter_engine.inference.hypothesis import (
+        hypothesize as _hypothesize)
+
+    if session.model is None:
+        return unavailable_envelope("no domain model loaded")
+    try:
+        sub, ranked = _hypothesize(session, entity_id, report_above=report_above)
+    except Exception as exc:  # noqa: BLE001 - see `_raised`
+        sub, ranked = _raised("inference", exc, {"candidates": 0}), []
+
+    envelope = Envelope(
+        checked=CheckedSummary(invariants=0, entities=len(session.entities)),
+        findings=list(sub.findings), questions=[_q(q) for q in sub.questions])
+    payload = envelope.to_dict()
+    payload["hypothesis"] = sub.to_dict()
+    payload["hypothesis"]["candidates"] = ranked
+    return _WithPayload(envelope, payload)
+
+
 def infer(session: EngineSession, target: str,
           do: Optional[Dict[str, int]] = None,
           report_above: Optional[float] = None) -> Envelope:

arbiter_engine-0.2.7/arbiter_engine/inference/hypothesis.py

@@ -0,0 +1,182 @@
+"""What could explain a finding, and what reading would tell the candidates apart.
+
+Phase B4. `gaps` says what the MODEL does not declare. This says what
+the WORLD might be doing given what it does declare, which is the same question
+turned around: a finding names an entity that is wrong, and an operator's next
+move is to decide where to look.
+
+THE PHASE PLAN CALLED THIS A PROMOTION AND IT IS NOT. `twin/hypothesis_generator.py`
+was named as the thing to promote. Measured: it walks a topology for STRUCTURAL
+patterns -- conservation, feedback loops, property bounds, monotonicity -- and
+emits a `TopologyHypothesis` carrying a `precondition_pattern`, a `confidence`
+and a `tenant_id`. None of that is `(cause, evidence_needed, test_action)` for a
+finding, and `tenant_id` is an orchestrator concept this engine does not have.
+Promoting it would have shipped the wrong verb wearing the right name, and
+carried a multi-tenant field into a domain-free package.
+
+So this is a composition over machinery that already exists, which is the
+cheaper and more honest build: the causal subgraph supplies the candidates, the
+inference runner scores them, and the model supplies the two things neither of
+those knows -- which reading would discriminate, and whether an action is
+declared that could test it.
+
+IT RUNS UNDER THE `inference` DISCIPLINE AND DECLARES NO VOCABULARY OF ITS OWN.
+The discipline set is closed and so is each discipline's decline vocabulary, and
+BOTH refused an eighth member when this verb first asked for one -- which is the
+refuse-what-you-cannot-read rule working on its own author. Using `inference` is
+also the truer answer: this runs that discipline's machinery on a causal
+question, and an eighth name for the seventh engine would be a second record of
+one thing.
+
+Its two refusals therefore share `not_identifiable`, distinguished by their
+detail. This project normally SPLITS a reason into named arms rather than
+sharing one, so that is a debt and not a design: growing a published closed
+vocabulary has a measured cost on a fail-closed consumer -- one broke this month
+on exactly such an addition -- and that decision should not ride along inside
+the commit that ships a feature.
+
+WHAT IT REFUSES. It ranks only DECLARED causal ancestors. It does not search for
+a cause outside the graph, does not invent an edge, and does not rank an entity
+the author never connected -- the same refusal `infer` makes, for the same
+reason: an engine that proposed causes nobody declared would be doing the
+inference this project removed from `role:` and from flow direction.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional, Set, Tuple
+
+from ..subenvelope import Decline, SubEnvelope
+from .causal import CausalGraph, causal_subgraph
+from .runner import Query, run_inference
+
+#: How far upstream a hypothesis may reach. BOUNDED, and the bound is the point:
+#: an unbounded ancestor walk over a graph with a cycle does not return, and the
+#: project rule is that verification stays in P. The graph's own `cycle()` check
+#: guards the declaration; this guards the walk.
+MAX_HOPS = 4
+
+
+def _ancestors(graph: CausalGraph, node: str,
+               max_hops: int = MAX_HOPS) -> List[Tuple[str, int]]:
+    """`(node, hops)` upstream of `node`, nearest first, each reported once."""
+    seen: Set[str] = {node}
+    out: List[Tuple[str, int]] = []
+    frontier = [node]
+    for hop in range(1, max_hops + 1):
+        nxt: List[str] = []
+        for current in frontier:
+            for parent in graph.parents.get(current, ()) or ():
+                if parent in seen:
+                    continue
+                seen.add(parent)
+                out.append((parent, hop))
+                nxt.append(parent)
+        if not nxt:
+            break
+        frontier = nxt
+    return out
+
+
+def _readable_properties(model, entity_type: str) -> List[str]:
+    """What the model says can be read on this type, in declared order."""
+    indicators = (getattr(model, "indicators", None) or {}).get(entity_type) or []
+    names: List[str] = []
+    for indicator in indicators:
+        name = getattr(indicator, "name", None)
+        if name is None and isinstance(indicator, dict):
+            name = indicator.get("name")
+        if name:
+            names.append(str(name))
+    return names
+
+
+def _test_action(model, entity_type: str) -> Optional[str]:
+    """A declared action that applies to this type, or None.
+
+    NAMED, NEVER INVENTED. An engine that suggested an action nobody declared
+    would be recommending a thing it cannot know is safe, on a system it cannot
+    see. `None` here means the model declares no way to test this candidate,
+    which is a fact about the model and is worth reporting as one.
+    """
+    for template in (getattr(model, "action_templates", None) or ()):
+        applies = getattr(template, "applies_to", None)
+        name = getattr(template, "name", None)
+        if applies is None and isinstance(template, dict):
+            applies, name = template.get("applies_to"), template.get("name")
+        if applies == entity_type and name:
+            return str(name)
+    return None
+
+
+def hypothesize(session: Any, entity_id: str, *,
+                report_above: Optional[float] = None
+                ) -> Tuple[SubEnvelope, List[Dict[str, Any]]]:
+    """Rank the declared causes of a finding on `entity_id`.
+
+    Returns the sub-envelope and the ranked candidates, which the caller
+    attaches -- the shape `entail` already uses, because `SubEnvelope` is
+    frozen and a verb that mutated one would be the only thing here that did.
+
+    Each candidate carries the posterior `infer` computes for it, the reading
+    that would discriminate it, and the declared action that could test it --
+    or an honest `None` where the model offers neither.
+    """
+    checked: Dict[str, Any] = {"candidates": 0, "ranked": 0, "max_hops": MAX_HOPS}
+    declines: List[Decline] = []
+
+    if getattr(session, "model", None) is None:
+        return (SubEnvelope("inference", {"candidates": 0}, source="unavailable",
+                            reason="no domain model loaded"), [])
+
+    graph = causal_subgraph(session.model, session.graph, session.entities)
+    if entity_id not in graph.nodes:
+        declines.append(Decline(
+            "not_identifiable", {"entity": entity_id},
+            detail=(f"`{entity_id}` is not in the declared causal subgraph, so "
+                    f"there is nothing upstream of it to rank. An edge enters "
+                    f"that graph by declaring `edge_direction: causal`; this "
+                    f"verb does not search for one.")))
+        return SubEnvelope("inference", checked, not_checked=declines), []
+
+    candidates = _ancestors(graph, entity_id)
+    checked["candidates"] = len(candidates)
+    if not candidates:
+        declines.append(Decline(
+            "not_identifiable", {"entity": entity_id},
+            detail=(f"`{entity_id}` has no declared causal ancestor within "
+                    f"{MAX_HOPS} hops, so the model offers nothing that could "
+                    f"explain a finding on it. That is a statement about the "
+                    f"model and not about the system.")))
+        return SubEnvelope("inference", checked, not_checked=declines), []
+
+    ranked: List[Dict[str, Any]] = []
+    for node, hops in candidates:
+        sub = run_inference(session, Query(target=node), report_above=None)
+        payload = sub.to_dict()
+        posterior = (payload.get("checked") or {}).get("posterior")
+        entity_type = graph.entity_type.get(node, "")
+        properties = _readable_properties(session.model, entity_type)
+        ranked.append({
+            "cause": node,
+            "entity_type": entity_type,
+            "hops": hops,
+            "posterior": posterior,
+            # The FIRST declared readable property, which is the model's own
+            # ordering rather than this verb's opinion about which matters.
+            "evidence_needed": (f"{node}.{properties[0]}" if properties else None),
+            "test_action": _test_action(session.model, entity_type),
+        })
+
+    # Nearest first on a tie, because a cause two hops away explains a finding
+    # only through one that is nearer, and asking about the nearer one first is
+    # how an operator narrows rather than guesses.
+    ranked.sort(key=lambda row: (-(row["posterior"] or 0.0), row["hops"],
+                                 row["cause"]))
+    checked["ranked"] = len(ranked)
+    if report_above is not None:
+        ranked = [r for r in ranked
+                  if r["posterior"] is not None and r["posterior"] >= report_above]
+        checked["reported"] = len(ranked)
+
+    return SubEnvelope("inference", checked, not_checked=declines), ranked

arbiter_engine-0.2.7/arbiter_engine/producers/__init__.py

@@ -0,0 +1,25 @@
+"""Reference producers. They have no special status and that is the point.
+
+Phase B3. `STANCE.md` says what a producer is and what this engine owes
+one: a record naming a `source` is filed, fitted a baseline, and graded, and the
+only thing the source changes is whether the eight shadow axioms run over it.
+Until now nothing in this repository walked through that door, so the whole
+producer path was exercised by fixtures and a consumer asking *what does a
+reasonable forecaster score here* had nothing to compare against.
+
+WHAT MAKES THIS A PRODUCER AND NOT AN ENGINE FEATURE. Everything here reads the
+session through `reading_history()` -- the accessor the engine tells every
+reader to use -- and emits ordinary forecast records through
+`ingest_forecasts`. It imports no checker, touches no envelope, and is handed no
+privilege the engine would refuse an outside forecaster. If any of that stopped
+being true the comparison it exists to support would stop meaning anything: a
+baseline with access the competition lacks is not a baseline.
+"""
+
+from .baseline_learner import (
+    BASELINE_MODEL_ID, MINIMUM_POINTS, SeriesRefused, forecast_series,
+    forecast_session,
+)
+
+__all__ = ["BASELINE_MODEL_ID", "MINIMUM_POINTS", "SeriesRefused",
+           "forecast_series", "forecast_session"]

arbiter_engine-0.2.7/arbiter_engine/producers/baseline_learner.py

@@ -0,0 +1,163 @@
+"""A damped-trend exponential smoother, stated as quantiles.
+
+The engine's own baseline is a random walk -- it predicts the last
+value and widens with the horizon -- and every producer this engine grades is
+scored against it. A random walk is the right FLOOR and a poor opponent: it is
+beaten by anything that notices a series is going somewhere, so a producer that
+beats it has shown almost nothing.
+
+So this is the next thing up, and deliberately not further: Holt's linear method
+with a damping factor, which is the smallest model that carries a trend and does
+not extrapolate it forever. It is fitted by grid search over the three
+parameters against one-step-ahead error on the series itself, which is honest
+for a baseline and would not be for a claim.
+
+WHAT IT REFUSES. A series shorter than `MINIMUM_POINTS` gets no forecast rather
+than a fitted one -- three points can be fitted to perfectly and say nothing. A
+series whose points are not strictly ordered in time is refused outright rather
+than sorted, because re-ordering somebody's series silently is how a producer
+scores well on data nobody gave it.
+
+THE SPREAD IS THE RESIDUAL SPREAD, not a confidence interval. The quantiles come
+from the one-step residuals scaled by the square root of the horizon in steps --
+the random walk's own widening rule, applied to a better centre. Naming it an
+interval would claim a distributional result this does not have.
+"""
+
+from __future__ import annotations
+
+import math
+from datetime import datetime, timedelta
+from typing import Any, Dict, Iterable, List, Optional, Sequence, Tuple
+
+#: What the records say they came from. A producer names itself; the engine does
+#: not name it, and `ingest_forecasts(source=)` is a separate statement about
+#: who filed rather than about who computed.
+BASELINE_MODEL_ID = "baseline-learner/holt-damped/1"
+
+#: Below this a fit is arithmetic rather than evidence.
+MINIMUM_POINTS = 12
+
+#: The grid. Small on purpose: a baseline that is tuned finely is no longer a
+#: baseline, it is an entry.
+_ALPHAS = (0.2, 0.4, 0.6, 0.8)
+_BETAS = (0.05, 0.15, 0.3)
+_PHIS = (0.8, 0.9, 0.98)
+
+#: The two the contract requires, plus the median the shadow check reads.
+_Z = {"q05": -1.6448536269514722, "q50": 0.0, "q95": 1.6448536269514722}
+
+
+class SeriesRefused(ValueError):
+    """The series cannot be forecast, and the reason is not a number."""
+
+
+def _ordered(points: Sequence[Tuple[datetime, float]]
+             ) -> List[Tuple[datetime, float]]:
+    rows = list(points)
+    for earlier, later in zip(rows, rows[1:]):
+        if later[0] <= earlier[0]:
+            raise SeriesRefused(
+                "the series is not strictly ordered in time; refusing rather "
+                "than sorting, because re-ordering a series nobody gave you "
+                "that way is how a producer scores well on data it invented")
+    return rows
+
+
+def _holt(values: Sequence[float], alpha: float, beta: float,
+          phi: float) -> Tuple[float, float, List[float]]:
+    """Level, trend and the one-step residuals, in one pass."""
+    level = values[0]
+    trend = values[1] - values[0]
+    residuals: List[float] = []
+    for actual in values[1:]:
+        predicted = level + phi * trend
+        residuals.append(actual - predicted)
+        previous = level
+        level = alpha * actual + (1.0 - alpha) * predicted
+        trend = beta * (level - previous) + (1.0 - beta) * phi * trend
+    return level, trend, residuals
+
+
+def _fit(values: Sequence[float]) -> Tuple[float, float, float, float]:
+    """`(level, trend, phi, sigma)` for the grid point with least squared error."""
+    best = None
+    for alpha in _ALPHAS:
+        for beta in _BETAS:
+            for phi in _PHIS:
+                level, trend, residuals = _holt(values, alpha, beta, phi)
+                sse = sum(r * r for r in residuals)
+                if best is None or sse < best[0]:
+                    n = max(1, len(residuals))
+                    best = (sse, level, trend, phi, math.sqrt(sse / n))
+    _sse, level, trend, phi, sigma = best
+    return level, trend, phi, sigma
+
+
+def forecast_series(points: Sequence[Tuple[datetime, float]], *,
+                    entity_id: str, property_name: str,
+                    horizon_s: float,
+                    issued_at: Optional[datetime] = None
+                    ) -> Optional[Dict[str, Any]]:
+    """One forecast record, or `None` when the series cannot support one.
+
+    Returns a plain dict in the shape `ingest_forecasts` reads. Nothing here
+    constructs an engine object: a producer that had to import the contract to
+    file would be a producer only this repository could write.
+    """
+    rows = _ordered(points)
+    if len(rows) < MINIMUM_POINTS:
+        return None
+
+    values = [float(v) for _when, v in rows]
+    level, trend, phi, sigma = _fit(values)
+
+    step_s = (rows[-1][0] - rows[-2][0]).total_seconds()
+    if step_s <= 0:
+        raise SeriesRefused("the last two points share an instant")
+    steps = max(1.0, horizon_s / step_s)
+
+    # Damped trend summed over the horizon, which is what `phi` is for: the
+    # contribution of each further step shrinks, so the forecast flattens
+    # instead of running away.
+    ahead = level + sum(phi ** k for k in range(1, int(steps) + 1)) * trend
+    spread = sigma * math.sqrt(steps)
+
+    return {
+        "model_id": BASELINE_MODEL_ID,
+        "entity_id": entity_id,
+        "property": property_name,
+        "issued_at": issued_at or rows[-1][0],
+        "horizon_s": float(horizon_s),
+        "quantiles": {name: ahead + z * spread for name, z in _Z.items()},
+        "sample_count": len(rows),
+    }
+
+
+def forecast_session(session: Any, *, horizon_s: float,
+                     issued_at: Optional[datetime] = None
+                     ) -> List[Dict[str, Any]]:
+    """Every numeric series this session can support a forecast for.
+
+    Reads `reading_history()`, which is the store the engine tells every reader
+    to ask -- `session.history` is what was FED, and the two differ whenever a
+    calendar or a derived indicator is declared.
+    """
+    history = session.reading_history()
+    out: List[Dict[str, Any]] = []
+    for key, points in (history.get_all_numeric_series() or {}).items():
+        # `entity_id.property_name`, split on the LAST dot: a property name
+        # carries none in this engine and an entity id may, so splitting on the
+        # first would silently forecast a property nobody named.
+        entity_id, _, property_name = str(key).rpartition(".")
+        if not entity_id or not property_name:
+            continue
+        try:
+            record = forecast_series(
+                points, entity_id=entity_id, property_name=property_name,
+                horizon_s=horizon_s, issued_at=issued_at)
+        except SeriesRefused:
+            continue
+        if record is not None:
+            out.append(record)
+    return out