Skip to content

Changelog

Everything worth noting lands here. The format follows Keep a Changelog, and versions follow semantic versioning. While we're pre-1.0, treat the minor version as the place breaking changes can show up.

[Unreleased]

Security

  • CI audits uv.lock against the OSV vulnerability database whenever it changes and every Monday. Dependabot proposes monthly updates to the packages cpomdp names directly, the pre-commit hooks and the workflow actions. A version reaches the lock only once it is seven days old (ADR-093). None of this changes what an install of cpomdp resolves to.
  • The lock moves past every advisory the audit found when it was added, in eight packages. pillow, which examples installs, moves to 13.0.0. filelock, which rxinfer brings in through juliapkg, moves to 4.2.4.

[0.5.1] — 2026-10-30

A bug-fix release for the November workshop. No number changes. GATE-D4 moves from v0.5.1 to v0.5.2 (ADR-092).

Fixed

  • The sdist leaves out CI's JAX compilation cache. .gitignore named .jax_cache/ and CI writes .jax-cache/, so the publish job built its sdist after the test step had filled the cache. PyPI refused CI's 0.5.0 sdist at its 100 MB limit, so the wheel went out alone and a clean sdist was uploaded by hand the next day.
  • A type checker accepts CallableSensor and FixedSensor as an ObservationModel, and CallableDynamicsNoise as a DynamicsNoiseModel. Both protocols declared is_fixed as a writable attribute, which a frozen dataclass cannot satisfy, so ty 0.0.91 refused every sensor passed as observation_model. is_fixed is read-only to a type checker on both now (#206). The lock moves ty from 0.0.46 to 0.0.91, so CI's type gate checks this. The older version never checked whether a protocol member is writable. At runtime is_fixed stays the plain attribute 0.5.0 declared, so a subclass that sets it on the instance still runs (#211).
  • The Raises sections of Agent and Agent.from_backend name the ValueError for a built-in selector= built for another model or graph (#191).

[0.5.0] — 2026-10-16

Warrant plumbing and the slogdet oracle audit. The two-level SearchWarrant becomes a shared three-level Warrant that checks can reach, and a check now reports what it found alongside how well it was warranted and what it was measured against. The audit half confirmed what v0.4.3 left behind: the kernel's log-determinant guard was never applied to the NumPy oracle the headline H* = 7 is checked against.

The H = 7 numbers did not move. They are bit-identical across the guard, so it corrected an exposure rather than a result.

The research apparatus this release adds lives in cpomdp._lab, a private package. The test suite and the unpublished research package build on it, and none of it is public API (ADR-069).

A world and an agent that cannot reach one another. cpomdp._lab.harness separates the process that produces observations from the model an agent filters with, so how wrong that model is about the process becomes measurable rather than zero by construction. Actions arrive from a declared sequence. The agents do not choose them, which is what leaves several of them comparable under one trajectory and what cuts the control loop, and every run carries that second fact rather than leaving it to a comment.

cpomdp._lab.constructors declares the two axes a model can be wrong along, one for what its parameters get wrong and one for what its filter does. Both are versioned, so a cell added after results are seen shows up in the diff.

The cross gets its two numbers. cpomdp._lab.scoring scores every cell of the declared constructor cross with two divergences, what the model gets wrong and what the filter gets wrong, and nothing else: the result has no slot for an entropy, so the one term the ledger forbids reaching by subtraction cannot be reached that way. Every separation is a ratio, printed beside the conditioning of every matrix it inverted. The check that the two divergences and the entropy add up to the measured free energy is a separate object, the one place an entropy is estimated. And a difference between two numbers scored against one reference is read at the error on the difference, which the shared reference makes far smaller than the sum of the two bars.

The control bracket. cpomdp.control grows a finite-horizon regulator beside the steady-state one. The private cpomdp._lab.bracket holds the two costs every controller under one plan sits between: the plan with the state observed exactly, and the best any controller that has to infer the state from readings can do. Their difference is the price of inference under that plan, and the width is the object reported, since either end alone is a number in cost units that nothing calibrates. Both ends are closed forms. The ceiling is reached twice, by the separation principle and by propagating the joint second moment of state and estimate, and the two share no arithmetic past the Riccati recursions, so their agreement to machine precision is the fixed-noise signature: certainty equivalence is optimal, and no use of the readings beats it.

Added

  • LQRController and InadmissiblePartitionError are exported at the top level, and each has an API page. LQRSelector cannot be built without the first, and the graph EFE selector raises the second (ADR-069).
  • CouplingGraphBackend.partition reads back the carry partition's clusters. An agent's selector check compares it, since a driver planning on another partition scores a different plant from the one the agent filters.
  • CouplingGraphBackend.stack_observations takes one step's readings keyed by node, the form CouplingGraph.infer takes, and returns the vector infer_states takes. It refuses a missing node, a node with no sensor and a reading of the wrong width. The vector's ascending node order lived in a private layout, so readings of one width stacked in a dict's insertion order filtered each node against another's reading.
  • LinearGaussianModel.observation_noise_at(state) reads R at a state on any model. A model with no sensor or a fixed one returns observation_noise. A state-dependent sensor is linearized at state. The graph EFE paths and probe_model read R through it (ADR-076).
  • cpomdp._lab.harness — a world and an agent held apart, so what an agent's model gets wrong about the process is a measurable quantity rather than zero by construction. World runs the process and hands out observations, exposing no accessor that returns its model or a parameter of it. ScoredAgent runs its own model and has no constructor slot for a World. drive advances one world per step and folds the same reading into every agent, over an ExogenousActionSequence declared before the run. Imposing the actions is what makes the entropy of the true process cancel between agents, and it cuts the control loop: DrivenRun.control_loop carries that as a ModellingChoice with no default, saying what was chosen and where the choice is contestable. A state-dependent R(x) is read at the state that produced the reading, and Q(x) at the predicted mean, rather than at the point the filter evaluates them: the filter drops a Jensen term the world must not drop too, since the distance between them is the inference gap under study (ADR-048, superseding ADR-047's refusal). Both are re-checked on every step, because construction probes them at one state only. The two fail differently and the check follows that: the sensor draw is cholesky, so a noise that loses definiteness returns NaN, while the dynamics draw is svd and returns a finite state drawn from |Q|. An indefinite Q(x) is refused; a noiseless state direction stays legal.
  • cpomdp._lab.constructors — the two axes a model can be wrong along, each declared and versioned. ModelSpec holds parameters and builds a fresh model per call, sharing no array between builds, so two models that agree do so by value rather than by pointing at one object. Perturbation names a parameter and scales it. InferenceRule names one of four ways to infer. Both are records rather than functions, so a declared set can be read in a diff. A scale the filter would not read is refused rather than built, since the cell would otherwise report a label for a model identical to the correct one.
  • cpomdp._lab.degraded — WrongFixedRBackend and DiagonalCovarianceBackend, two filters that infer worse than the model they are built for and name how. Each keeps model pointing at the model being scored, so a degradation is never an anonymous mismatch between two models.
  • cpomdp._lab.scoring — the three-term evaluator. build_cross enumerates the declared model and inference axes in full and carries a ProductCompletenessCertificate at PROVED, refusing a cross that comes up short. Decomposition holds a misspecification term and an inference gap, both KL divergences in nats and both in closed form on a linear-Gaussian model. gaussian_kl is built from non-negative parts and subtracts nothing, so a reading near zero is a small divergence rather than a cancellation. ThreeTermEvaluator.score walks a driven run and returns a CellScore with a RunConditioning beside it: the condition number of every predictive and posterior covariance the terms factored, per step. The run carries the sequence that drove it, and the score reads the actions from there, so readings cannot be scored against another sequence that reuses the tag. score_cross scores every cell, reports the cell where both terms move, and refuses to name a separation without one. A Separation is the pinned term, the moving term and their ratio, and render prints no separation without its ratio and its worst conditioning on the same line.
  • cpomdp._lab.additivity — whether E[F] = H(p*) + D₁ + D₂ closes, with both sides measured on their own. AdditivityCheck takes an EntropyEstimator explicitly and is the only object that estimates one; GaussianEntropy is the closed form and MonteCarloEntropy samples with a standard-error bar. variational_free_energy is computed term by term from the cell filter's belief, never through the identity. The residual's bound is four terms, δ_F + δ_H + δ₁ + δ₂, and a worked case shows it failing to close when δ_F is dropped.
  • cpomdp._lab.resolution — the error on a difference. A Bar is split into a signed common-mode part, what the reference's error puts on the value, and an own part. Two values against one reference subtract the first in their difference, so resolution_threshold reads |Δ common-mode| + Σ own rather than the sum of the two bars. It reads bars only, which is what makes it pre-registered. resolve reports BELOW, ABOVE or NOT_RESOLVED, the measured tie that is neither confirmation nor refutation. The module imports nothing first-party, asserted in the boundary test, so the seam and the reference filter reach it without reaching the evaluator.
  • cpomdp.control — the finite-horizon schedule. lqr_schedule runs the control Riccati recursion backward a declared number of steps from a zero terminal cost and keeps every gain, where LQRController iterates to a fixed point and keeps one. It takes the two costs as precision and effort, the names a StateGoal gives them, and LQRSchedule keeps them under those names. LQRSchedule.first_gain is the gain a receding-horizon planner at horizon H applies at every step; the steady-state gain is its limit and differs from it at every finite H, by an amount that shrinks with H and reads as an error when the horizons are not matched. kalman_schedule writes the exact filter's gains and covariances down before a reading exists, since under fixed noise they never see one. The two are the dual pair and are called alike: lqr_schedule(model, horizon=...) and kalman_schedule(model, horizon=...), each returning a schedule that reports its horizon. They are read alike too. gains[k], costs_to_go[k] and covariances[k] all belong to step k of the plan, so costs_to_go[0] prices the whole plan and covariances[0] is the prior's. The Control page of the API reference opens the schedule in plain terms.
  • cpomdp._lab.bracket — the control bracket, private until its leg under state-dependent noise lands. full_information_cost is J_lower, the plan priced with the state observed. CertaintyEquivalentController acts on the estimate as if it were the state, and closed_loop_cost prices it, or any data-independent gain sequence, by propagating the joint second moment of state and estimate; nothing is sampled. optimal_cost is J* by the separation principle, and the two reach one number by different arithmetic. control_bracket returns the floor and ceiling as a ControlBracket, and control_efficiency reads η_ctrl from it: the share of the width an agent recovers, within-model, with a bar that is the agent's own divided by the width, the floor below which η_ctrl cannot be told from zero. A goal the dynamics do not hold, a noise that depends on the state, and a bracket of zero width are all refused.
  • cpomdp._lab.reference — the exact reference filter's substrate, reached by module path and not re-exported at the package top. QuadratureGrid and GridDensity are a declared lattice and log-values on it, and gaussian_on is the one place a Gaussian is put on that lattice. averaged_inference_gap sweeps an observation box and returns an InferenceGap: the rule's expected divergence from the exact posterior under p*, beside the predictive mass the box caught and the worst edge ratio. A rule may answer Void for a reading it could not converge on. The sweep then reports that node as NaN, sums its weight into voided_mass, and averages the answered readings normalised to their own mass, the conditional reading a clipped box already gets (ADR-060).
  • cpomdp._lab.reference.ladder — the rule ladder. A Rung is a factory: the likelihood a reading is conditioned on goes in, and the rule(prior, observation) callable the gap measures comes out, with everything the rung reads from the model closed over at construction. All five of ADR-056's rungs are built: PLUG_IN, the Kalman update with the noise read once at the prior mean; SINGLE_STEP and ITERATED, the Spinello–Stilwell scheme under ADR-057's modification at a budget of one and at ADR-058's budget and tolerance, with the noise's slope taken by automatic differentiation and one observation channel only (ADR-062); BELIEF_SMOOTHED, the Kalman update with the noise averaged under the prior on its own grid (ADR-061); and EXACT_RUNG, the reference at the top. LADDER is the declared v1 set of the five, in the order the battery's D1 leg is registered over. iterated_update runs the scheme on one reading at any budget and returns its count, so the cost of an iterating rung is read off a result and not a loop body. RuleLadder is the declared, versioned set the rungs sit in, refused without an exact rung the same way an InferenceSet is refused without an exact cell. The Gaussian rungs read the channel through GaussianChannel, a second small protocol beside ObservationLikelihood that adds the observation matrix and observation_noise_at, so the exact rung is not asked for either.
  • research.explorations.threshold — GATE-D4's threshold T takes a value. The reference engine's error field is measured across the fit window at the binding cell, its shift on the fitted exponent replaces the registered σ_p, and T = 5.962e−4 nats is registered at D = 0.5, f = 0.078157 under a declared lattice (research/gate_d4_registration.md, PRE-REGISTRATION and RESULT of 2026-09-11).
  • research.checks.ladder — the ladder's first reading. Five rungs on d4-family-v1 at the binding cell, at the fifteen spreads and on the two lattices T was registered under, each gap with a bar measured by refinement and carried whole as its own. One row per adjacent pair resolves the ordering through cpomdp._lab.resolution at every spread, NOT_RESOLVED where the bars overlap, and every ordering row is COMPUTED since the bar is measured and not certified. Two rows read route 6 off the same numbers, one reports the R6 signal beside T with no verdict on the gate, and the completeness certificate is a one-axis product over the declared ladder. Registered under D1 of the battery before it was read. Read once: three of the four registered orderings fire at the binding cell. The belief-smoothed rung sits with the plug-in, two to four decades above both Spinello–Stilwell rungs, and above the registered window those two fall behind the plug-in. Both route 6 mechanisms resolve at every spread. The battery's RESULT of 2026-09-12 carries the table. A tenth row reads the lattice at every spread on both lattices against the two bars T was registered under. The suite stays out of the manifest, since it runs the reference engine and three of its rows fire by recorded result. The slow test path pins its ids and outcomes instead.
  • research.spinello_stilwell.gap_rescaling — route 1's empirical half, on the reported gap. The printed scheme and ADR-057's modification run through the gap at four unit choices, at rung (36)'s budget of one and at rung (35)'s declared budget. The modification's gap is unit-free to roundoff at both. The printed scheme's moves by four per cent at a budget of one and reaches the same fixed point at the declared budget wherever it converges. Q1 of the rung record closes on it.

  • warrantlib.CompletenessEvidence (warrantlib 0.3.0) — the two predicates a PROVED completeness claim rests on, held once in a base, with a leaf per domain shape under it. CompletenessCertificate keeps its name, its fields and its rendering, and is now the tree leaf, |A|^H over one versioned action set. ProductCompletenessCertificate is the cross, carrying an AxisDeclaration per axis so 3 x 4 and 2 x 6 are not both reported as 12. A leaf defining its own __post_init__ is refused at class creation, since it would shadow the gate. Evidence now crosses the wire through a tag/class registry, and a kind extends under the same SCHEMA_VERSION because kind self-describes and unknown-kind refusal is the designed failure.

  • warrantlib.manifest (warrantlib 0.3.0) — the checks a suite is registered to report, declared in a generated TOML file and reconciled against what a run actually produced. A count could say a suite got shorter. It could not say which check left, and it was satisfied by a different check arriving in place of the one that went. The manifest names both directions: declared and not reported, reported and not declared. Generate or refresh one with python -m warrantlib.manifest <path>, and ask whether it is current with --check. The file compares as text rather than as parsed content, so a layout the writer no longer produces counts as stale. --layout-only asks that half on its own, from the ids the file already declares and without running a suite. Reading a suite's ids means running it, so on a project whose suites are symbolic the plain --check costs a full re-derivation to answer a question about whitespace. --warrant-detail, or -vv, prints each check's own line the way a suite run on its own does. The pytest plugin collects the manifest, turning every declared check into an item. The item exists because the check was declared, so a check that stops reporting still has a row and the row fails naming it.

  • A pytest plugin (warrantlib 0.3.0), which pytest loads wherever warrantlib is installed, and so wherever cpomdp is. It needs pytest 8 or newer, which the warrantlib[pytest] extra pins, and -p no:warrant switches it off. A test hands its findings to the run with the record_check fixture, and the run reports them in the warrant vocabulary: the progress letter separates a void check from one measured elsewhere, -v prints NOT TRIGGERED where it would have printed PASSED, and the run closes with the registered / tested here / fired accounting rather than a count of dots. A fired check fails its test, and so does an unresolved one, because a falsifier that ran and could not decide has not left the claim standing. The pytest outcome underneath stays one of pytest's own three: junitxml branches on that and nothing else, so a fourth value would write the row as no row at all. Categories stay standard too, so N passed still counts what it always did and assert_outcomes still sees it. Loaded through the pytest11 entry point, so no configuration is needed. dependencies stays empty and importing warrantlib still pulls in no pytest, which a test asserts in a clean interpreter.
  • report_to_dict / report_from_dict / SCHEMA_VERSION (warrantlib 0.3.0) — a report as a machine record and back. Every value is JSON-ready and the key order is fixed, so two runs of one suite produce the same bytes and a diff shows what changed rather than what moved. Enums travel as their values. Reading goes through the constructor, so a record naming PROVED with its evidence stripped still does not construct. A record from an unknown schema version, an evidence kind with no class behind it, or an enum value that has since been renamed is refused rather than mapped to whatever fits: Tier.A became Tier.EXACT once already, and a reader guessing its way through that rename would have reported a status change nobody made. Nothing here touches a filesystem. A JSON Schema for the record ships beside the code at warrantlib/report.schema.json, for a consumer reading a ledger without Python, and the suite validates the writer's own output against it.
  • CheckReport.check_id (warrantlib 0.3.0) — the check as a key, beside the prose name it already carried. Dot-separated segments of letters, digits and underscores, refused at construction if anything else appears. The name is what a summary line reads and is reworded whenever the wording improves; the key is what a manifest declares before a run and what joins one run's report to the next. Deriving the key from the name would tie the two together, so the first rewording would read as one check dropped and one added. Required rather than defaulted: a report with no key is reconcilable with nothing, which is every job the field exists for. Every check in research.checks and in examples/ffg/crossover.py now declares one, and NoiseFamily carries the key those ids are built from.
  • The fourth D3 falsifier is pre-registered on both axes and answered on both. Extension: {−4,…,2} gives H* = 6 against a bar of H* ≤ 6 registered a commit earlier, and extension saturates there. Refinement: H* = 7 at step-0.5 and step-0.25 alike, |ΔH*| = 0 against a bar of 1, the two cells agreeing to the digit across 86 times the policies. Each row is a PROVED report carrying its completeness certificates and a Provenance whose ordering git can check. The step-0.5 cell was a re-measurement: the write-up published it before any commit built the set, and the numbers hold.
  • cpomdp.enumeration.ChunkedEFESearch — the exhaustive search run in blocks, at a footprint the block sets rather than |A|^H. It enumerates the same set as EnumeratedEFESearch, earns the same PROVED certificate and takes the same model, set and horizon, with chunk in place of a policy budget. evaluate returns a SearchResult with the argmin, its G, its index and the certificate. The front-loaded search returns EnumeratedSearchResult, a SearchResult that adds the score vector. The two paths agree under ==, ties included (ADR-036). Both drivers take it, and the refinement cells of the fourth falsifier ran on it. evaluate composes with jit, vmap and lax.scan, where a callback checks the loop's count when the program runs. The searches and their drivers have an API page.
  • cpomdp.enumeration.ExhaustiveEFESearch, the base both exhaustive searches share (ADR-083). It declares evaluate, policies_at, n_policies, horizon, cost_per_plan and warrant. The drivers take any ExhaustiveEFESearch, so a third search or a wrapper drives them with no edit to either.
  • Provenance (warrantlib 0.2.0) — which ref registered a claim and which one measured it, plus one line saying what a reviewer will find at the first. A PROVED report requires one, on the same terms as it requires evidence, and carries them as a tuple for the same reason the evidence is one. A ref is a git commit SHA, an http(s) URL or a DOI; a path, a branch, a tag and HEAD are refused, because each resolves to a different tree every time it is read. Where the two refs name one commit the render says the ordering is not established by history, which is the honest reading whenever a check and the derivation behind it land together. The type cannot order two refs, only compare them, so tests/test_provenance_ordering.py asks git. Three of the suite's nine sources fail that check today and are marked xfail: the hand derivation in research/c4_hand_derivation.md landed 2026-08-17, after the suites citing it, which ADR-037 already discloses (ADR-041).
  • warrantlib — the vocabulary every check labels itself from, published as its own distribution. cpomdp's top level re-exports Warrant alone, the type its selectors and searches report. cpomdp.enumeration keeps CompletenessCertificate, which v0.4.4 shipped there. The rest is imported from warrantlib (ADR-069). It depends on the standard library alone, so a suite can label its findings without a numerical stack; cpomdp depends on it and adds nothing to it (ADR-039). Warrant carries the prover class (PROVED, CERTIFIED, CORROBORATED), Outcome what a registered falsifier did, Tier what it was measured against (EXACT, BOUNDED, COMPUTED), and CheckReport all four with a reason. CERTIFIED is new: validated numerics prove a universal over a compact domain, which is stronger than a sample and weaker than a decision, and forcing it into either neighbour overclaims or throws away the bound (ADR-035). Every member is a word rather than a letter, so a row says what it means without a reader knowing the ordering. The prover sub-modes read the same way in prose: Prover 3 · sample, Prover 3 · enumeration, Prover 3 · validated. The canonical table is at research/warrant_ledger.md.
  • warrantlib.SymbolicReduction — evidence for a PROVED claim decided by argument rather than by enumeration (Provers 1 and 2). A CAS establishes that one expression equals another and has nothing to say about whether those are the expressions the analytic claim is about, which the warrant ledger records as a human obligation. The type carries the claim, where the setup was hand derived against the problem, and the assumptions the identity is contingent on. Blank fields do not construct, so a correspondence nobody can fill honestly routes a check to CORROBORATED instead of passing silently. Blank means blank to a reader: whitespace, the zero-width formatting characters, a line break into a one-line render, and a field that is not text are all refused, with assumptions checked entry by entry.
  • check_summary prints n registered, m tested here, k fired, then counts per (warrant × outcome). Registering four falsifiers and testing two is a different claim from testing four, and one number cannot carry both.
  • A host-side ln det behind a Cholesky positive-definiteness guard, private to cpomdp.diagnostics, NaN otherwise. slogdet reports a sign separately, so reading only the magnitude returns ln 2 for diag(-1, -2), a plausible number for a matrix whose log-determinant does not exist. epistemic_value and the crossover demo's oracle both route through it.
  • examples/ffg/crossover.py gains flip_margin_error, the error the already-declared COND_CEILING allows on a difference of two scores. H* = 7 rested on a bare inequality between two computed floats with nothing said about how far apart they had to be. The bar is derived from a ceiling tests/test_rollout_hygiene.py already enforces rather than invented for the claim. warrant_numbers.md records the derivation, that it was written after the measurement, and why a stricter guard cannot rescue a failing result.
  • A References page rendering the whole bibliography, docs/references.md. mkdocs-bibtex only emits the keys a page cites, so eleven entries in docs/references.bib were invisible on the site. Four sources join them: the ASME paper the applied surge work reads against (GT2024-124905), Greitzer 1976 for the compressor dynamics that notes disclaim modelling, and ISO 5167 parts 1 and 2, where flow-rate uncertainty for a differential-pressure element is standardised and where pulsating flow is explicitly excluded.
  • Koudahl, Kouw and de Vries (2021) is cited wherever the fixed-sensor collapse is claimed, rather than ADR-003 alone. An ADR records a decision. The proof that expected free energy reduces to KL control under a fixed linear-Gaussian sensor is theirs, and the README, both example galleries and two API pages asserted it without saying so. Friston et al. (2015) gets the same treatment where the T-maze is named.
  • examples/surge_margin.py, the gallery's first applied demo: anti-surge margin on a compressor whose flow meter is a differential-pressure element. The square-root law makes the meter's variance R(Q) ∝ 1/Q², so the state-dependent noise comes from the instrument rather than a modelling choice. A fixed-R twin collapses onto its economic optimum and the R(Q) agent is held off it. The offset has a closed form, κ/(ΛQ) + R/Q with κ the Kalman gain, an epistemic part and a pragmatic one, and every grid argmin lands within a grid step of it. Run in closed loop, the library's own Agent settles where that law puts it with κ at the filter's steady state, much nearer the preference than its first step aimed. A Coriolis meter at the same accuracy flips the offset's sign, and the library's Agent with it settles past the surge line. Eleven registered falsifiers, all CORROBORATED. docs/guides/surge_margin.md leads with those results for a reader who runs compressors. docs/guides/surge_margin_derivation.md derives the meter model and the law, fixes the one calibration constant and lists what the demo does not model. Both sit under a new Applications section of the docs.
  • Agent.selector, read-only: the selector that chooses the agent's actions. For an ObservationGoal with no horizon set, agent.selector.horizon reads back the horizon taken from the model, and agent.selector.cost_per_cycle gives what each sample_action costs. Agent, EFESelector, FFGEFESelector and LQRController print what they were built with, so an agent typed at a prompt shows the horizon or the gain it chose. The Agent page shows how to compare horizons.
  • The two grid selectors answer the same questions. candidates on each is the grid searched, shape (n_candidates, p), so an example plotting the scores reads it rather than rebuilding it. FFGEFESelector.warrant reads CORROBORATED, as EFESelector.warrant does. Both default to 21 candidates, as ObservationGoal does, and FFGEFESelector aims at the whole joint state when info_node is left out, as it does on the goal. n_candidates is the grid's total count everywhere. ObservationGoal called it a resolution, which reads as per axis.

Fixed

  • The README called inference JIT-compilable end to end. The backends and selectors are. The Agent is not. It holds its belief, so a jitted agent.infer_states filtered every observation against the belief it was traced with, and the next eager call raised UnexpectedTracerError. The Agent docstring, its API page and the README now say it is eager, and the page shows a backend driven under jax.lax.scan.
  • No page said which public names survive jit, vmap and grad, and KalmanBackend.infer_states called itself an eager orchestrator while it traces. The backends page now carries one row per public name, and tests/test_transform_table.py runs every row but RxInfer's. A row that traces runs under jit, vmap and grad, and a row that does not is shown failing under jit. The README and InferenceBackend point at it.
  • KalmanBackend, its API page and the README called the filter exact for any linear-Gaussian model, and said RxInferBackend re-derives the same answers. Under a state-dependent R(x) or Q(x) the filter reads the noise at the predicted mean, a first-order plug-in, and RxInferBackend refuses such a model. Each now says the filter is exact under fixed noise, and the oracle agrees only there.
  • The LQRController docstring and the backends page said the Agent's filter is solved once at construction, as ADR-002 and ADR-003 planned. Every release has filtered per step. Both now say so, and ADR-086 records the per-step filter as the default and the steady-state one as the opt-in. The README points at ADR-086 beside ADR-003. It said all inference runs as message passing over a factor graph, and now says that of branching models, which is where CouplingGraphBackend does it.
  • Public docstrings cited build-plan labels a pip user cannot look up, "Phase 1A", "item E" and "standing rule 6" among them. They are gone, and tests/test_docstring_labels.py fails on one in any docstring outside cpomdp._lab. The ADR numbers stay, and the docs home links DECISIONS.md, which is append-only, so an ADR a release cites reads the same there later. Coupling and GaussianCoupling illustrated themselves with chemotaxis proteins, which ADR-015 keeps out of the core. Their examples are generic now.
  • Pre-rename names survived in the model's formula, in two error messages and in the guide: dynamics @ state + control @ action, "dynamics must be a square matrix", "(dynamics, control) may not be stabilisable" and dynamics=dynamics. Each now names dynamics_matrix and control_matrix. The EFE module's definition reads the sensor from observation_model, where it said observation. Belief's docstring said its covariance is checked for positive semi-definiteness elsewhere. Its constructor checks it.
  • EFESelector described varying-sequence search as a deferred v0.4 GradientEFESelector seam, in its rendered class docstring and in the ValueError a p > 1 caller hits. That search shipped in v0.4.4 as EnumeratedEFESearch, whose own docstring says it supports p >= 1 and varying sequences (ADR-031). No such class has ever existed under src/. The name is still a planned continuous-action selector elsewhere, so only these two strings were wrong, not the name itself. The error path was the worse of the two: it told a caller to reimplement a search the package already had. Both now name EnumeratedEFESearch and the FiniteActionSet it needs.
  • The NumPy oracle in examples/ffg/crossover.py discarded slogdet's sign on both halves of its per-step epistemic. v0.4.3 fixed the shipped kernel and the changelog did not say whether the oracle path went with it. It did not. Both paths now reject a matrix with an even number of negative eigenvalues, which a two-route agreement check cannot catch on its own: two routes that both discard the sign agree, and are both wrong.
  • The crossover falsifiers computed their outcome from |ΔG| > bound, a magnitude test on a direction question. Nothing could emit FIRED, and a reversed argmin would have printed as a survivor beside a hardcoded "argmin is cue-ward". Outcome and detail are now computed from the exhaustive argmin, and the measurement is injectable so a refuting result is something a test can execute.
  • CompletenessCertificate(expected=9, visited=8, warrant=PROVED) used to construct and read complete = False, a certificate recording its own shortfall with the contradiction one attribute access away. It now raises. The honest label for a partial enumeration is CORROBORATED.
  • Citations rendered as literal [^key] on the published site. mkdocs-bibtex rewrites [@key] into footnote syntax, and footnotes was missing from markdown_extensions, so four API pages shipped a raw key where a reference should have been and no page carried a bibliography at all. Enabling the extension fixes every citation in the tree at once. No prose contained [^ beforehand, so nothing existing changes meaning.
  • The README is the PyPI page, and its two figures and five links were relative paths, which PyPI does not resolve. They are absolute now, so the page renders the same on PyPI, on GitHub and on the docs site. The figures are pinned to the commit that last changed them, so a later rename on main cannot break a published page, and the docs site still serves its own copies.
  • The README's pymdp table said only C and D are spelled differently. It and the Agent docstring now map A, B and infer_policies as well, and say that model.A and model.C are control-theory letters for pymdp's B and A.
  • Importing cpomdp has switched JAX to 64-bit floats for the whole process since 0.2.0, and only that release's changelog said so. The README's install section and the package docstring now say it, and what turning the flag off again does.
  • cpomdp._lab.additivity.variational_free_energy and RxInferBackend refuse a state-dependent sensor. Both read the plain observation_noise whatever the model carried, so a model with R(x) was priced or filtered against a constant without saying so. AdditivityCheck already refused through predicted_belief. A direct call did not. RxInferBackend refuses a state-dependent Q(x) too, since its Julia model takes one fixed Q as well, and it refuses before Julia starts.
  • InferenceBackend said nothing about state-dependent noise. It now states the rule those refusals follow: a backend honours the model's observation_model and dynamics_noise_model, or refuses the model.
  • Every cpomdp wheel shipped cpomdp/juliapkg.json, where juliapkg finds it from any Python in the environment. The next import juliacall by anything there, cpomdp imported or not, added RxInfer to that environment's Julia project and precompiled it. The wheel ships no such file now. The first RxInferBackend declares RxInfer to juliapkg where the environment does not already, then starts Julia (ADR-085).
  • RxInfer is declared as the range 5.4, where it was pinned to exactly 5.4.0. cpomdp[rxinfer] takes RxInfer's releases within 5.x and can share an environment that needs one of them. CI pins 5.4.0.
  • The README said only that the RxInfer backend bootstraps itself on first use. It now says that first build needs network access, may download Julia, and installs and precompiles RxInfer into a Julia project it names, and how to provision one ahead of time.
  • probe_model added the plain dynamics_noise to every predicted covariance, whatever Q(x) the model carried. The EFE kernel adds Q at the predicted mean, so a Q(x) model under a fixed sensor reported a constant epistemic value the kernel never computes. The probe now takes Q at each predicted mean as the kernel does. Where a sampled Q is not a covariance it raises, instead of dropping that sample from epistemic_range. The report gains dynamics_noise_varies and dynamics_noise_spread, and flattens needs both noises constant. Under Q(x) the action reaches the recursion with R fixed.
  • CouplingGraph checks each sensor's width against the node it observes. A one-column C on a two-dimensional node used to construct, and CouplingGraphBackend broadcast it across the node's block, so the sensor read the sum of the node's components and the filter returned a plausible posterior from the wrong model.
  • CouplingGraphBackend.block and marginal refuse a node outside the graph and name the valid range. block(-1) returned an empty range, so an epistemic term aimed at it scored zero. marginal(-1, belief) failed inside a reduction, and block(5) on five nodes raised a bare IndexError.
  • CouplingGraphBackend cuts a prior by its partition before it filters from it, on every surface. Under an all-singleton partition infer_states kept only each node's own block of a correlated prior. severed_mass and predicted_belief used all of it. So the severed mass counted correlation the filter had already dropped, and the EFE predicted from it. The full-joint partition is unchanged. A mixed partition such as [[0, 1, 3, 4], [2]] over a correlated prior also returns a different posterior now, since the dense path inverts the cut prior (ADR-077).
  • Every refusal of a covariance that is not positive-definite gave one reason, "a noiseless or degenerate sensor sends the information gain to infinity". A semi-definite dynamics_noise on a GaussianTransition or coupling_noise on a Coupling was blamed on a sensor the caller never passed. Each refusal now gives its own caller's reason. An FFG factor's says its information form inverts the matrix. A sensor's R keeps the information-gain reason, and the harness says it draws the reading through a Cholesky factor. The graph path still needs a definite Q where the flat model accepts a semi-definite one, because its transition factor inverts Q, and CouplingGraphBackend says so.
  • Malformed graph inputs raise an error that names the argument. A reading on a node with no sensor raised a bare KeyError: 1 from CouplingGraph.infer, now infer_root, and a prior over the wrong dimension raised cannot add messages of shape (2, 2) and (1, 1). GaussianTransition.from_ou(0.0, ...) raised ZeroDivisionError, and a negative tau or dt blamed dynamics_noise, an argument the caller never passed. A dimension of 1.5 was truncated to 1. A CouplingGraphBackend over a graph with no sensor failed in a zero-size reduction and now refuses, saying it has none.
  • The graph EFE rollouts and searches skipped the checks FFGEFESelector makes on its target. policy_efe_ffg, policy_efe_ffg_trace, the crossover statistic and both searches' over_backend scored on a carry partition that severs an EFE-load-bearing edge, and the searches certified the argmin PROVED. None of them checked the joint-state indices they were aimed at. JAX clamps an out-of-range gather, so index 99 on a 3-state joint scored as index 2. An empty block gave a zero epistemic and a repeated one gave NaN. All of them now refuse a severing partition, a node outside the graph and an empty or repeated node list through one check. A search makes it once at construction, so scoring each policy costs nothing extra.
  • FiniteActionSet refuses a non-finite action and names its row. A NaN action scored NaN on every policy that took it, and a search over the set still certified it PROVED. A repeated action is still accepted and counts toward |A|.
  • When every policy scored NaN, both searches returned the first declared sequence as their best and certified it PROVED. The front-loaded search scored it NaN and the chunked one +inf. With no finite score there is no argmin, so the result now carries a NaN best_policy and best_g and a best_index of -1. A driver raises ValueError on such a run, and returns a NaN action only under a trace, where it cannot raise. The certificate still holds, because it certifies that every policy was scored. policies_at, now on both searches, refuses an index outside the enumeration, -1 included, which would otherwise decode to a real policy. Under jit or vmap it decodes such an index to a NaN policy.
  • Each exhaustive search re-traced and recompiled its rollout on every plan, a fixed cost per plan that cost_per_plan does not count. A driver paid it every agent step. Each search now compiles once, on its first plan, and takes the belief and the preference as arguments. tests/test_search_compilation.py counts the traces across two plans and holds the compiled scores equal to the eager path's under ==.
  • FFGEFESelector refuses a backend with no control matrix or with more than one action dimension, as EFESelector does. A control-free backend returned the grid's first action, and p = 2 constructed and then failed at the first select. The two selectors now share one check.
  • ObservationGoal, EFESelector and FFGEFESelector check action_bounds through one helper, as two finite scalars with the lower first. Each compared the pair with Python's <, which stops at the first element that differs, so action_bounds=([-1, 5], [1, -5]) constructed with its second axis inverted and the selectors then failed inside JAX's linspace. An infinite bound and a fractional n_candidates are refused too, and ObservationGoal.action_bounds holds two floats. ObservationGoal and EFESelector check horizon through one helper as well. A fractional horizon passed both and failed later inside range or jnp.repeat.
  • When no candidate scores a finite G, EFESelector and FFGEFESelector return NaN, and Agent.sample_action refuses it, naming the noise. Both selectors returned the first candidate, which looks decisive. With R(x) = 1 - x0² at x0 = 2 every score was NaN and the selector returned the lower bound. The selectors stay jit-safe. The Agent's check reads the p action entries back to the host once per cycle, and a refused action is not remembered for the next predict.

Changed

  • Breaking: a coupled CouplingGraphBackend's model is refused where a plant is taken: by KalmanBackend, RxInferBackend, the private ChainBackend, Agent, EFESelector, EnumeratedEFESearch, ChunkedEFESearch, LQRController, lqr_schedule, kalman_schedule, probe_model, expected_free_energy, policy_efe and policy_efe_trace. The private research harness refuses it too, in World, ScoredAgent, WrongFixedRBackend and every InferenceRule cell. The model leaves out the couplings, so each of them computed on a different plant with nothing raised. A copy made with dataclasses.replace, jax.tree.map or through a jit boundary is refused too. A model rebuilt field by field through the LinearGaussianModel constructor is not marked, and is taken as a plant. Agent.from_backend(graph, StateGoal(...)) ran LQR that way and is refused as well. backend.to_flat_model() keeps the couplings, and a graph with none is its own plant (ADR-091).
  • Breaking: a public class spells an acronym in capitals, as EFESelector and LQRController already did. FfgEfeSelector is FFGEFESelector, EnumeratedEfeSearch and ChunkedEfeSearch are EnumeratedEFESearch and ChunkedEFESearch, and PolicyEfeTrace is PolicyEFETrace. The classes new in this release take the same casing: EFEResult and ExhaustiveEFESearch (ADR-088).
  • Breaking: Agent.qs is gone. It was a read-only alias of Agent.belief, so one posterior had two names and the README told users to pick either. pymdp's qs is agent.belief.
  • Breaking: Agent takes a model or a backend, never both. Agent(model, objective) filters with the default per-step KalmanBackend, and Agent.from_backend(backend, objective) takes any other engine, a CouplingGraphBackend included, and plans under backend.model. The backend= argument is gone. Passing both let the agent plan on one model and filter on another without raising: with R = 1 against R = 100 the posterior was 0.020 where it should be 1.005. ScoredAgent takes the same two forms, ScoredAgent(model) and ScoredAgent.from_backend(backend). It refused a backend built from another model, and now cannot be given one.
  • Breaking: selector= takes a Preference, and a goal configures only the selector the Agent builds. Agent(model, goal) searches as the goal says, and Agent(model, preference, selector=...) searches as the selector says. A goal beside selector= is refused, and so is either half of the second form without the other. The goal and the selector both described the search, and the selector won in silence: a goal that declared the action box (-0.1, 0.1) returned the action 1.5. A selector with no goal was dropped, and the agent tracked. A StateGoal beside a selector paid a Riccati solve for a controller the Agent then discarded, which raised on a plant with no stabilising gain. A built-in selector reads the Preference in its own space, an observation for the EFE selectors and the search drivers and a state for LQRSelector, and a target of the wrong length is refused. The old pairing of a goal with a selector reading the other space cannot be written: Agent(model, StateGoal(target), selector=EFESelector(...)) pursued C · x = target and settled away from the target whenever C is not the identity. Every built-in selector, search and search driver names the model it scores under as model, and a graph-scored one names its graph as backend. One scoring a different plant is refused. One built from an equal copy, such as a model rebuilt from the same config, is taken. A graph-scored one is compared on its interface model, its couplings and its carry partition, and a coupling unreadable under a trace counts as different. A graph backend whose couplings cannot be read passes only as the same object, and a flat selector is refused on a coupled graph. A custom selector is not checked (ADR-080).
  • Breaking: an ObservationGoal goes to EFE wherever a noise depends on the state, on a flat model and a graph alike. The dispatch read the sensor and the backend's type. A model whose only state dependence was Q(x) was refused as a fixed sensor and told to pass a StateGoal. Q(x) moves the information term through the predicted covariance, and such a model now gets an EFESelector. A CouplingGraphBackend with fixed sensors got an FFGEFESelector whose information term was the same for every action. A flat model with the same sensors was refused. Both are refused now, and the message names the selector to pass with a Preference for EFE with a flat information term. examples/ffg/epistemic_dissociation_figure.py hands both of its agents one FFGEFESelector that way (ADR-081).
  • Breaking: on the LQR path Agent refuses a StateGoal target the dynamics do not hold at zero action, where A · target ≠ target. LQR regulates the offset from the target and charges for effort, so it settled short. With A = 0.9 and a target of 1 the state came to rest at 0.8432. CertaintyEquivalentController already refused such a goal, and the two refusals now share one equilibrium check. StateGoal's docstring states the requirement.
  • Breaking: Agent.model, KalmanBackend.model and KalmanBackend.steady_state are read-only. Assigning agent.model changed what the agent reported while its backend, selector and controller kept the old model. A steady-state KalmanBackend kept its frozen gain under a reassigned model, and setting steady_state afterwards raised on the next step. Build a new Agent or backend instead. model is read-only on ScoredAgent, LQRController, ChainBackend, RxInferBackend, WrongFixedRBackend and DiagonalCovarianceBackend too. Each builds a filter, a gain or a factor from it at construction. Assigning agent.belief now requires a Belief over the model's state. A list was accepted and failed on the next step. InferenceBackend.model is declared a read-only property, which a plain attribute still satisfies.
  • Breaking: CouplingGraph.root, dims, couplings and observation_models are read-only, and observation_models is a read-only mapping. Construction is the only place the wiring is checked. A sensor added afterwards to node 7 of a two-node graph skipped the range check and reached the backend. Build a new graph instead.
  • Breaking: CouplingGraph takes no root. The root is the one node no coupling points to, so a stated root could only repeat the couplings or contradict them. Drop the argument. graph.root still reads it back.
  • Breaking: CouplingGraph.infer is infer_root(readings, prior). It takes the readings first and the prior second, the order infer_states(observation, prior) takes. It was the one inference call that took the belief first. A call in the old order raises a TypeError that names readings, since a Belief is not a mapping of readings. The new name says what comes back: the root's marginal, from a prior over the root alone. infer_states returns a belief over every node, and a bare infer beside it read as its twin.
  • Breaking: an ObservationGoal's horizon defaults to None, and the Agent reads it off the model: the shortest horizon at which the target moves the expected free energy, found by differentiating the candidate grid's scores with respect to the target once, at the prior. On a double integrator observed in position a push reaches the reading only after two steps. At the old default of 1 every candidate scored the same, and the agent pushed at full effort toward action_bounds[0], away from a goal at +1. A noise that reads velocity breaks that tie at horizon 1, and the push it picks there is the same for every target. An explicit horizon too short for the target to move the scores is refused, naming the shortest that works. Single integrators keep horizon 1 (ADR-068).
  • EFESelector and FFGEFESelector break a tie toward the candidate nearest zero. They took the first candidate, the lower bound. A tie means the action reaches nothing the scores read. On that double integrator, an EFESelector built by hand at horizon 1 scored every candidate 1.163426662195336 and returned action_bounds[0] on every step. It now rests. Two tied candidates equally near zero, ±h on a grid without zero, give the point between them. Scores within a relative 1e-11 of the best count as tied, since the graph backend leaves roundoff of about 1e-12 on such a tie. Choosing costs two more passes over the k scores per cycle.
  • EFESelector and FFGEFESelector compile their scoring once, on the first select, and reuse it. Each select re-traced the grid under an eager vmap, and at horizon above 1 the rollout's scan compiled again on every call, a fixed cost per step that cost_per_cycle never counted. A test counts the traces across three beliefs and finds one.
  • The batched condition number rollout_conditioning computed inline is now a private function of its own, so a rollout and a scored cell read the same number for the same matrix.
  • CouplingGraph works out its parent map and collect order once, at construction. The factored filter path rebuilt and re-sorted both on every belief-propagation pass, once or twice a step, though neither depends on anything but the wiring.
  • Breaking: validate_step_inputs and rxinfer_chemotaxis_tree_root are private, as _validate_step_inputs and _rxinfer_chemotaxis_tree_root. v0.4.4 exported them from cpomdp.backends.base and cpomdp.backends.rxinfer. The first is the shape check the built-in backends share and the second is the RxInfer test oracle, and a cpomdp user calls neither (ADR-069). import cpomdp no longer leaves cpomdp.jax behind.
  • Breaking: ChainBackend is private, at cpomdp.ffg._chain. v0.4.4 published it at cpomdp.ffg.chain. It returns KalmanBackend's numbers at two extra inversions per step and exists to show that the message algebra is the Kalman filter on a chain, which tests/test_ffg_chain.py holds it to. Filter with KalmanBackend. The flagship example's agreement check between the two moves into that test file, on the same model and the same scripted inputs (ADR-076).
  • Breaking: the graph model's message passing is private. GaussianTransition.predict and CouplingGraph.infer_all take a leading underscore. GaussianCoupling's message_to_parent and message_to_child are private methods of Coupling, and cpomdp.ffg.message is cpomdp.ffg._message. v0.4.4 published them on the top-level construction classes, typed on a CanonicalGaussian no page documents. They are the hot path the energy work will change. A user builds the graph and runs it through CouplingGraphBackend or CouplingGraph.infer_root, and neither needs them (ADR-069, ADR-073).
  • Breaking: a fixed observation_model or dynamics_noise_model must now restate the model's observation_noise / dynamics_noise exactly, and a sensor's linearized observation matrix must equal observation_matrix. LinearGaussianModel previously accepted the two disagreeing and left which one was read to the consumer: the EFE kernel reads the object where the filter reads the field, so a model could score against one noise and filter against another. A state-dependent object may still vary — it is the fixed case that restates the field and must restate it exactly. This is a construction-time break: LinearGaussianModel(observation_matrix=[[1., 0.]], observation_noise=[[1.]], observation_model=FixedSensor([[1., 0.]], observation_noise=[[0.5]]), ...) built before and now raises. Pass the same value twice, or drop the redundant field.
  • Breaking: an observation_noise or dynamics_noise passed beside a state-dependent object must be that object's value at prior.mean exactly, as beside a fixed one. The field used to take any covariance there, and nothing read it. With observation_noise=[[123.0]] beside a CallableSensor, model.observation_noise returned 123. Every filter used R(x). A field now holds one value whichever object is carried. Omit it and the model reads it from the object. dataclasses.replace(model, prior=...) on such a model raises instead of keeping the noise of the old prior. Pass the noises an object supplies as None to read them again. WrongFixedRBackend takes the constant it scales as its own observation_noise= (ADR-071).
  • observation_matrix is optional beside an observation_model, read from the sensor's C on the same rule. A model with R(x) used to need C typed twice, once for the sensor and once for the model (ADR-071).
  • LinearGaussianModel's observation_noise is optional when an observation_model is given. Omitted, it is the sensor's R at prior.mean, read once at construction (ADR-064). A state-dependent sensor used to need a positive-definite R beside it that almost nothing read, so the channel was described twice. A fixed sensor's own R comes back unchanged and meets the restatement guard above by construction. With no sensor the field is still required. A value passed beside a sensor must be that R, as the entry above on state-dependent objects says.
  • Refusing state-dependent noise is one function, require_fixed_noise, in the internal _validation module. The closed forms in control and scoring, the free energy, RxInferBackend and the steady-state KalmanBackend each held a copy of it. The control and scoring messages are unchanged. The free energy's refusal, new in this release, takes its own wording. The steady-state refusal now names the slot that varies. The test it makes is state_dependent beside it. KalmanBackend, ChainBackend, the Agent and the harness's World each spelled that test out again, and now call it. ModelStructure.validate skipped its Q check beside any dynamics_noise_model, and now skips it only beside a state-dependent one.
  • LinearGaussianModel's dynamics_noise is optional when a dynamics_noise_model is given, on the rule observation_noise follows. Omitted, it is the dynamics noise's Q at prior.mean (ADR-065). With no dynamics-noise object the field is still required.
  • ModelSpec takes observation_noise and dynamics_noise as None beside the matching noise object and passes the None to the model, which derives the value (ADR-066). A perturbation naming a noise the spec leaves out is refused, as one naming an absent control_matrix already was. observation_matrix may be None beside a sensor too. A perturbation of a field the spec's object supplies is refused with one message, fixed object or not, since the model refuses the scaled field either way (ADR-071).
  • The symbolic CI job reconciles the three symbolic suites against research/registered_checks.toml instead of comparing three hand-typed strings. The strings said 23 registered, 23 tested here, none fired and two more like it. They could report that a suite got shorter. They could not say which check left, and a check renamed or swapped for another left the count untouched, so the gate passed. Every one of the 70 checks is now an item that fails by name, in both directions: declared and not reported, reported and not declared.
  • Breaking: cpomdp and warrantlib require Python 3.11, up from 3.10. The check manifest is TOML so the generated file can say what it is and how to regenerate it, and tomllib reads TOML from the standard library only from 3.11. Taking tomli instead would have ended warrantlib's "the standard library is the only dependency", which is the property that makes it installable beside a check suite wanting nothing else. Python 3.10 reaches end of life in October 2026, which is what makes the trade cheap rather than what makes it right (ADR-045). The published warrantlib 0.2.0 keeps its >=3.10 metadata, so an existing 3.10 install resolves as it always did.
  • cpomdp-research requires warrantlib>=0.3, for CheckReport.check_id.
  • The crossover falsifiers name their action mode. H* = 7 is an open-loop number: the sweep scores whole length-H sequences with no re-planning, driving neither RecedingHorizonSelector nor OpenLoopSelector. The same statistic under a receding-horizon driver is a different quantity and is unmeasured. The declaration now travels with the number in the PROVED details, in warrant_numbers.md, in the ledger and in the README, and a test asserts it so the qualifier cannot be dropped silently.
  • cpomdp requires jax>=0.4.36, up from >=0.4. The search results register with JAX through field metadata, which older releases cannot read, so import cpomdp.enumeration failed on them.
  • cpomdp requires warrantlib>=0.3,<0.4, up from >=0.1. The tree builds the completeness certificates 0.3 introduced, and against 0.2 the modules that build them failed to import. The cap is there because warrantlib's minor versions break before 1.0, as cpomdp's do. Breaking for anyone pinning warrantlib below 0.3 (ADR-070).
  • cpomdp.__version__ reads the installed package metadata, so pyproject.toml is the one place the version is set. CITATION.cff restates it for GitHub and Zenodo, and a test fails when the two disagree.
  • Breaking: the model's fields are dynamics_matrix, control_matrix, observation_model and dynamics_noise_model (were dynamics, control, observation, process_noise). One rule now covers every field: _matrix is a linear map, _noise a fixed covariance, _model the state-dependent stand-in for one of them. Before this the fixed process noise was dynamics_noise and the state-dependent one process_noise, the same channel under two roots, while A was dynamics and C was observation_matrix. Keyword-only construction is what made the names load-bearing: every argument after the first is typed out at each call site, so a member on its own scheme is a question the caller has to answer each time. GaussianTransition.dynamics and the CouplingGraphBackend(control=...) argument move with it, as do the demo constants (SENSOR is OBSERVATION_MATRIX, PROCESS_NOISE is DYNAMICS_NOISE). LinearGaussianModel.observation_model holds the declaration, and no backend carries a member of the same name. No numerical behaviour moved.
  • Breaking: LinearGaussianModel drops its .A, .B, .C, .Q and .R properties. Each field has its role name only. In pymdp A is the likelihood and C the preferences, so model.A handed a pymdp user the dynamics matrix with no error, and every field carried two public names.
  • Breaking: the dynamics-noise classes take the observation side's names. DynamicsNoise is DynamicsNoiseModel, the protocol the dynamics_noise_model field holds, as observation_model holds an ObservationModel. CallableProcessNoise is CallableDynamicsNoise, and takes noise_fn and noise_params (were q_fn and q_params), as CallableSensor does. A user who had written R(x) could not write Q(x) by analogy, and "process" and "dynamics" named one channel. A noise object passed for a matrix field now raises a TypeError naming the slot it belongs in. It used to fail inside float(). The API page is "Dynamics noise", and no longer says a plain matrix satisfies the protocol. A constant Q goes in dynamics_noise.
  • Breaking: ObservationModel.linearize(state, /), ObservationModel.gaussianize(mean, cov, /) and DynamicsNoiseModel.noise_at(state, /) take their arguments by position, so an implementation may name them as it likes. FixedSensor, CallableSensor and CallableDynamicsNoise name them that way. The flat sensors called the state x, and linearize(state=...) worked on the graph factors and failed on them. CallableDynamicsNoise.noise_at reads a list as an array, as the sensors do.
  • Breaking: SensorReport is ProbeReport, named for probe_model, which returns it. It reports on Q as well as the sensor. Each field now carries the name of the object it describes: rank and full_row_rank are observation_matrix_rank and observation_matrix_full_row_rank. definite, indefinite_at, non_constant, noise_spread and loewner_comparable are observation_noise_definite, observation_noise_indefinite_at, observation_noise_varies, observation_noise_spread and observation_noise_loewner_ordered. report.noise_spread read as covering both noises and covered only R. The summary says "R varies" and "Q varies" where it said "non-constant".
  • Breaking: Belief.ndim is Belief.n_states and FiniteActionSet.action_dim is FiniteActionSet.n_controls, the names LinearGaussianModel gives the same two dimensions. In NumPy and JAX ndim is an array's rank. A belief over two states read prior.ndim == 2 beside prior.mean.ndim == 1.
  • Breaking: the epistemic term's aim is info_node on every graph entry point: ObservationGoal, FFGEFESelector, policy_efe_ffg, policy_efe_ffg_trace, both over_backend class methods and the crossover functions. None, the default, is the whole joint state, and a sequence of nodes aims at their joint marginal. The graph APIs took target, a name the goals use for a desired value, so a goal vector passed there gave G = nan and a different action with no raise. They then took info_block, the joint-state indices, while the goal took a node, with a different default on each. A caller converted with backend.block(node) and passed the backend twice, and on scalar nodes info_block=(0,) read as node 0 until a node grew (ADR-090). ObservationGoal.info_target becomes info_node. StateGoal.target and ObservationGoal.target keep the name, which now has one meaning.
  • Breaking: expected_free_energy, policy_efe and policy_efe_ffg return an EFEResult with fields g, pragmatic and epistemic. They returned (G, {"pragmatic": ..., "epistemic": ...}), and their trace siblings a NamedTuple, so one family answered in two forms and a misspelt key failed only when it ran. EFEResult and PolicyEFETrace are frozen dataclasses registered with JAX, read by name as the search results are. Neither indexes nor unpacks, so result[0] and G, parts = ... both fail, and a caller reads result.g. NumPy refuses to read a record as one array, so np.argmin(batch) raises where it returned an index past the candidates. A vmap over candidate actions returns one EFEResult with every field batched, ranked by jnp.argmin(batch.g) (ADR-087). The old pair fitted jax.value_and_grad(..., has_aux=True) as it stood. A function differentiated that way now returns (result.g, result), and jax.grad takes one returning result.g.
  • Breaking: PolicyEFETrace's moment fields are predicted_mean, predicted_cov, posterior_cov and predicted_observation_cov, renamed from mu_pred, sigma_pred, sigma_post and s. RolloutConditioning's fields follow them. cond_sigma_pred is cond_predicted_cov, cond_s is cond_predicted_observation_cov, cond_sigma_post is cond_posterior_cov and min_eig_sigma_post is min_eig_posterior_cov. trace.s could not be read without the docstring. S also went by four names across the docstrings, and is the predicted observation covariance in every public one now. g, pragmatic and epistemic keep their names, which EFEResult shares.
  • ObservationGoal.preference is the Preference the expected free energy functions score against, built once from the goal's target and precision. Passing the goal itself to expected_free_energy, policy_efe or a sibling raised 'ObservationGoal' object has no attribute 'goal'. It now raises a TypeError naming the goal's .preference. A StateGoal is refused as aiming at a state, and a bare goal vector with how to wrap it. The functions take one type, the Preference pytree that passes through jit and vmap, and refuse anything else, so a goal's search settings never reach a score that would ignore them.
  • Breaking: Preference calls its vector target, as StateGoal, ObservationGoal and LQRController.action do. Preference(goal=...) and preference.goal become Preference(target=...) and preference.target. The wish a user typed as a goal's target reached the selector under another name.
  • Breaking: LQRController takes its weights as precision and effort, the names a StateGoal carries, where they were goal_precision and effort_penalty, and LQRController.action takes target where it took goal. A StateGoal whose effort had the wrong size raised "effort_penalty must be 1x1", naming a parameter the caller never typed. The refusal says effort now, and StateGoal refuses at construction an effort that is not square, symmetric and positive-definite. Its docstring no longer calls the two weights Q and R, the letters of the model's noises.
  • Breaking: ObservationGoal takes action_bounds by keyword. StateGoal already takes everything after its first argument by keyword, so this was the odd one out in a public pair a reader meets together. The two positional slots also transposed without raising for a 2-D increasing target, since (lo, hi) then satisfies the target's shape check and the target satisfies lo < hi. 24 call sites moved to keywords.
  • Breaking: FixedSensor takes observation_noise by keyword. The observation pair is (m, n) against (m, m), so the two are distinguishable by shape only when m != n, and a 1-D sensor is the case where they coincide. Only the noise is content-checked, and a square symmetric observation matrix passes that check, so a transposed pair built a sensor whose Jacobian was its noise. CallableSensor is left alone: its arguments are a matrix, a callable and a pytree, so a swap raises rather than going quiet. 46 call sites moved to keywords.
  • Breaking: a graph node takes the sensor a flat model takes. GaussianObservation and CallableGaussianObservation are removed. Pass a FixedSensor or a CallableSensor in CouplingGraph's observation_models, with the same arguments. The two pairs had identical constructors and fields, and each failed in the other's slot. LinearGaussianModel refused the graph classes, and a FixedSensor on a graph node constructed and then raised at the first filter step. A node now takes any ObservationModel, and the graph reads C and R through linearize as the flat model does (ADR-073).
  • Breaking: CouplingGraph's observations is observation_models, as argument and attribute. It holds sensors, and the paired CouplingGraphBackend uses the word for readings: rollout takes stacked observations and n_observations counts reading rows. A graph with one two-row sensor had len(graph.observations) == 1 and backend.n_observations == 2. The new name matches LinearGaussianModel.observation_model.
  • Breaking: GaussianTransition takes dynamics_noise by keyword, and GaussianTransition.from_ou takes stationary_var and dt by keyword. Both follow LinearGaussianModel for the same reason, and the transition factor is the worse of the two: its dynamics_matrix and dynamics_noise are both (n, n) at every dimension, so a transposed pair needs no square-shape coincidence to pass. Only the noise is content-checked. from_ou's tau and dt are both positive scalars in the same time unit and A = exp(-dt/tau) is finite either way round. 45 call sites moved to keywords.
  • Breaking: an edge is one class. GaussianCoupling is removed, and Coupling holds the edge's matrix and noise itself: Coupling(parent, child, coupling_matrix, coupling_noise=...). v0.4.4 wrapped the two in a GaussianCoupling passed as Coupling's factor, so one concept took two classes and a user had to learn which went inside which. The matrix was coupling there. It is coupling_matrix now, after the _matrix suffix every other linear map carries. coupling_noise is keyword-only. A scalar edge's gain and noise are both (1, 1), and only the noise is content-checked, so GaussianCoupling([[0.05]], [[0.9]]) built an edge with the two swapped (ADR-075).
  • Breaking: Coupling takes no tau. The edge's time-constant was required and read by nothing. In the chemotaxis example it restated the timescale the child's GaussianTransition.from_ou already took, and other callers made one up. A node's timescale is its transition. efe_relevant is keyword-only, so a stale positional tau fails on arity. It used to land in efe_relevant and blame a flag the caller never set. Coupling checks its fields at construction. A node index that is not an int and an efe_relevant that is not a bool raise TypeError, and a NumPy bool is stored as a bool. A coupling_matrix that is not 2-D and a coupling_noise that is not positive-definite raise ValueError (ADR-075).
  • CouplingGraph checks a fixed sensor's R when it is built: square to match C, and positive-definite, since it is inverted every step. A sensor that implements only the protocol and returned a zero or indefinite R gave a NaN or wrong belief.
  • CouplingGraphBackend refuses a state-dependent sensor whose R is not positive-definite at the predicted mean, as ChainBackend does. It returned a finite belief that was wrong.
  • Breaking: CouplingGraphBackend takes a required keyword prior, the belief over the joint state before any reading. Its model.prior was an N(0, I) placeholder, so an Agent built on the backend planned and filtered from a belief the caller never chose, and to_flat_model() carried the same placeholder. The flagship example overwrote agent.belief to work around it. Pass the starting belief at construction.
  • Breaking: CouplingGraphBackend has one name for each size it knows. n_total is backend.model.n_states, dims is backend.graph.dims and n_observations is backend.model.n_observations. Each was the same number under a second name, and n_total was the only place the joint width was not called n_states. The Agent leaves an info_node range check to backend.block, which names the valid nodes.
  • Breaking: CouplingGraphBackend.observation_model is removed. It returned (C, R) with R linearized at zero, so under a state-dependent sensor it handed out R(0) as the noise the EFE reads. On the same object backend.model.observation_model was a sensor. Read C as backend.model.observation_matrix, as on every backend, and R at a mean as backend.model.observation_noise_at(mean). Under a state-dependent sensor backend.model.observation_noise is now R at the prior mean, the rule every flat model follows (ADR-064). It was R at zero.
  • Breaking: CouplingGraphBackend.observation_noise_at(mean) is backend.model.observation_noise_at(mean), an accessor every LinearGaussianModel now has. C was read off the model and R off the backend, so code reading R at a mean over a flat and a graph backend branched on which it held. A fixed graph's model returns the R built at construction, so nothing is rebuilt per call (ADR-076).
  • Breaking: one protocol describes a graph backend, GraphBackend in cpomdp.backends.base. It was EfeBackend, a name that suggested KalmanBackend cannot score EFE, and cpomdp.diagnostics.ProbeBackend restated part of it for probe_model. ProbeBackend is removed, and probe_model takes a CouplingGraphBackend as before. GraphBackend declares no dims, n_total or observation_model, which the entries above retire. Like EfeBackend before it, it carries no promise (ADR-069).
  • Breaking: CouplingGraphBackend.partition_error is severed_mass, the name its docstring already used, and it returns a 0-d JAX array where it returned a host float. It composes under jit and lax.scan, and float(...) reads one value. rollout is gone. It was a second compiled filter beside infer_states, returned a Belief with a time axis that broke Belief's invariant, and always paid the dense solve, even on the partition chosen for its cheap pass. A per-run profile is a lax.scan over infer_states and severed_mass, and the diagnostic's solve is a separate call (ADR-089).
  • Breaking: CouplingGraphBackend.readout and its readout_node argument are removed. readout(belief) was marginal(readout_node, belief), and the argument did nothing else. Read any node, the root included, with marginal(node, belief).
  • Breaking: CouplingGraphBackend.graph and transitions are read-only, as model already was. The model and the factors are built from them at construction, so an assignment left both describing the old graph. Build a new backend instead.
  • Breaking: every LinearGaussianModel argument after dynamics is keyword-only. The four matrices are two maps and two covariances of the same rank, and only the covariances are content-checked, so a transposed pair constructed in silence whenever the maps were square and symmetric. LinearGaussianModel(Q, C, A, R, prior) built a model and returned a posterior of [0.900, -0.444] where the answer is [0.896, -0.434]. Detecting the mistake after the fact needs a rule for which of two same-shaped matrices is which. Naming them at the call site needs none. One positional construction existed in the tree, examples/efe_collapse_figure.py, now converted. ty reports the arity error statically, so a stale positional call fails the type gate rather than running.
  • Breaking: sensor_model is now observation_matrix, on the same classes plus _JointObservation and epistemic_value. C is the observation matrix in the same literature that gives R its name, so the two halves of the measurement equation now read from one vocabulary. C is not observation_model: that name means the whole channel, the model field the entry above renames. The 2026-06-13 sketch wanted plain observation for C, which the state-dependent sensor field later claimed. The .C alias is unchanged, and no numerical behaviour moved.
  • Breaking: sensor_noise is now observation_noise, on LinearGaussianModel, FixedSensor, CallableSensor and epistemic_value. R is the observation noise covariance in the state-space literature this library writes in, and it is the noun in "state-dependent observation noise", the phrase the R(x) work is published under. The backends already said it. observation_noise_at has always been the state-dependent accessor, so the model was the one place still calling R a sensor quantity. The 2026-06-13 naming sketch in DECISIONS.md proposed observation_noise at the outset. The code drifted. The .R alias is unchanged, and no numerical behaviour moved.
  • The repository is a uv workspace. cpomdp stays the root; packages/warrantlib and research are members, sharing one uv.lock and one .venv. warrantlib publishes to PyPI beside cpomdp. cpomdp-research never publishes, and holds the check suites along with the scipy and sympy they need, which have left cpomdp's dev group (ADR-039).
  • CompletenessCertificate is defined in warrantlib beside SymbolicReduction, the other evidence kind, and re-exported from cpomdp.enumeration where an enumeration produces one. It used to live in cpomdp.enumeration, which made the warrant module import it at call time to run the isinstance guard behind PROVED.
  • The check suites moved to research/src/research/checks/. The research.checks.<module> import path is unchanged, and so is every registered count.
  • Breaking: SearchWarrant is removed from cpomdp.enumeration. Import Warrant from cpomdp or warrantlib, the one enum it was an alias of. Its members are the same objects, so EFESelector.warrant still reads CORROBORATED and EnumeratedEFESearch.warrant still reads PROVED.
  • Breaking: EnumeratedEFESearch.cost_per_cycle is cost_per_plan, the name the drivers already used for one search. cost_per_cycle now means one thing everywhere, the cost of one agent step, and only selectors report it. Read as per step, the search's figure overstated the open-loop driver by a factor of H, and the README did exactly that.
  • Breaking: the certificate travels with the decision. EnumeratedEFESearch loses its certificate property, and evaluate returns the certificate on the result. EnumeratedSearchResult is a frozen dataclass read by name. It no longer unpacks or indexes. It subclasses SearchResult, the chunked search's result, and gains best_g, best_index and certificate. A driver's certificate is the last plan's, None before its first, because the chunked search earns one per run.
  • Breaking: EnumeratedEFESearch and its over_backend refuse a set of more than max_policies policies, 2^21 unless set, with a PolicyBudgetError. |A|^H is exact before anything is allocated, and an oversized set used to take a memory-capped host down without raising. The error gives the count, the step evaluations of one plan and a floor on the memory, and names ChunkedEFESearch, which both drivers take. max_policies=None lifts the budget. The set is now decoded from its indices rather than built through itertools.product on the host (ADR-083).
  • PROVED without evidence does not construct, enforced in CheckReport. Two kinds qualify, one per decisive prover: a completeness certificate for an exhaustive enumeration, a SymbolicReduction for a theorem or a symbolic identity (Provers 1 and 2). Evidence is a tuple, so a claim quantified over several enumerations carries all their certificates rather than one of them. Every item is checked for its kind, so a path naming where the proof lives cannot satisfy the precondition by being present.
  • A check that never ran carries no warrant. CORROBORATED asserts sampling-grade evidence was obtained, so attributing it to a falsifier void by construction claims evidence that does not exist. That cell reads —, enforced at construction.
  • examples/ffg/crossover.py --check reports its falsifiers on two axes. Rows 1 and 2 read PROVED from the enumeration certificates and BOUNDED from the error bound. The H* = 7 upper-bound qualifier now travels in both detail strings, not only in the write-up. The declared set clips the reach at -2 while -3 reaches the goal in one step. A margin inside its bound reports NOT RESOLVED rather than raising, since a tie is a finding about the measurement and an exception erases it.
  • ADR-029 said the check vocabulary must never ship in cpomdp. ADR-035 reverses that on placement and extends it on content: three outcomes become five, NOT RUN HERE promoted from a prose rule to a member, NOT RESOLVED added for a genuine tie. PASS is absent from the enum. A falsifier does not pass, and printing PASS beside a prover column that disambiguates it inverts the rule the prover column exists to satisfy.

[0.4.4] — 2026-08-04

The multi-step slice of expected free energy. Scoring one policy over a horizon was already here; this release adds searching over a policy family and certifying that the search was exhaustive, which is what the crossover measurement needed. The headline is H* = 7: the horizon at which the best plan on the coupled-tree cue task stops being a direct reach and becomes a two-phase sense-then-commit walk. Every horizon is a complete enumeration, so the flip is decided rather than sampled.

Nothing on the H = 1 path moved. The existing suite passes unmodified and the one-step arithmetic stays byte-identical to 0.4.3.

examples/crossover_horizon_figure.py puts the same crossover on the flat Kalman/EFE route, with a frozen-R twin as its control. examples/ffg/cue_maze.py builds the cue task for any number of dimensions. About 390 lines duplicated across eight scripts moved into examples/gallery.py, and every committed asset re-renders byte-identical across the move. Three example checks that could exit zero on a failure are now gated in tests/test_example_checks.py. Two demos were removed.

Added

  • cpomdp.enumeration — the exhaustive search family, deliberately a separate object from EFESelector's continuous grid so the two warrants cannot be confused. FiniteActionSet is versioned, so an action added after results are seen shows up in the diff rather than in the prose. EnumeratedEfeSearch enumerates A^H and returns the argmin policy with the full G vector. CompletenessCertificate asserts expected against visited and raises IncompleteEnumerationError on a mismatch, which is what earns the search a PROVED warrant where a grid earns only CORROBORATED (ADR-030, ADR-031).
  • EnumeratedEfeSearch.over_backend scores enumerated policies on an FFG backend instead of a flat model. Scoring is injected as a strategy, so the enumeration, the certificate and the cost accounting are shared rather than duplicated. A reduce-to-flat oracle gates it: on a coupling-free backend it reproduces the flat search exactly (ADR-034).
  • RecedingHorizonSelector and OpenLoopSelector, both ActionSelectors wrapping the enumerated search. They stay separate because the two modes genuinely differ, and a measurement has to declare which one it used. Both report cost_per_plan = |A|^H · H and a replan_interval. Neither reports the grid's n_candidates × horizon, which would under-count the real work by a factor of |A|^(H−1).
  • policy_efe_trace, returning a PolicyEfeTrace: the per-step g, pragmatic, epistemic, μ⁺, Σ⁺, Σ_post and S that the rollout scan already computed and then discarded. It sits beside the hot path rather than in it, so the selector stays allocation-free. Its sums equal the scalars policy_efe returns under assert_array_equal, which is the proof that it is the same arithmetic and not a second implementation.
  • policy_efe_ffg and policy_efe_ffg_trace, the H-step rollout on a coupling graph, with the epistemic term aimed at a named node at the coupling-resolved μ⁺. Gated from both ends: at H = 1 it is byte-identical to the one-step FFG kernel, and with no coupling it matches policy_efe (ADR-032).
  • cpomdp.crossover — crossover_statistic, crossover_horizon and CrossoverStatistic. The horizon aggregation is the symmetric between-policy contrast ΔG = Δc − Δε. At H = 1 it collapses to the anchors Δε = 1.7232, Δc = 4.4910, ΔG = +2.7678 nats, pinned at a tolerance of 1e-4 (ADR-033).
  • diagnostics.rollout_conditioning — per-step cond(Σ⁺), cond(S), cond(Σ_post), the minimum eigenvalue of the posterior covariance, and a positive-definiteness flag, computed host-side. Three S re-inversions under R(x) against a contracting Σ is where orders of magnitude go missing quietly. The eigenvalue bar is an assertion and not a clamp, because a clamp launders the failure it was meant to catch.
  • examples/ffg/crossover.py — the crossover measurement, gated. It prints the exhaustive argmin per horizon, the mechanism split (disclosed as post-selection, because the pair it scores was found by the search), an independent NumPy kernel on the headline number, the counterfactual showing the flip is epistemically driven, and the conditioning against its registered bars.
  • examples/ffg/crossover_sweep.py — the constant-action null. A constant walk overshoots the cue and never exploits, so the constant family cannot express the two-phase plan at all. That null is the reason the exhaustive search is necessary, which is why it ships as a check rather than as a footnote.
  • A slow pytest marker for the exhaustive gate. Pull requests run without it; merges to main and releases run with it.

  • examples/crossover_horizon_figure.py — a showcase of the epistemic/pragmatic crossover on an open plane, and the first demo of it on the flat Kalman/EFE route rather than the factor graph. An augmented state x = (p, g) carries a position the control moves and a static latent goal it does not. R(p) makes the channel that reads g sharp only near a beacon off the direct path. The animation runs the same world once per planning horizon: at short H the agent settles where its prior said without ever checking, and past a crossing it detours to the beacon, finds out it was wrong, and goes to the real goal. Nothing changes but H. The margin ΔG(H) = G(detour, H) − G(direct, H), in nats, crosses zero exactly once, because the epistemic pull is flat while the pragmatic gradient decays under it. A frozen-R twin re-runs the whole sweep with R pinned and never crosses, so the behaviour is attributable to the state-dependent sensor and the horizon together rather than to the beacon-and-goal geometry. Under a fixed sensor the epistemic term is the same for both plans at every horizon, so it drops out of the margin. The term itself stays nonzero and grows with H (ADR-003). Renders the animation plus a three-panel companion. --check prints the sweep and asserts what the figures claim, gated in tests/test_example_checks.py. Its crossing lands at H = 7, which is the same integer as this release's registered H* and is unrelated to it: different model, different backend, whole-state epistemic rather than node-restricted, and no search at all. The demo says so in its own output, and neither number should be quoted as the other.

  • examples/ffg/cue_maze.py. The cue-maze task, built for any n_dims >= 1. A hidden context decides which of two goals pays, the prior points at the wrong one, and a cue elsewhere in the arena reads the context sharply while the agent stands on it. axis_action_set grows as 2·n·|magnitudes| + 1 rather than as a product grid, so two dimensions cost exactly what the corridor did. enumeration_cost prices a sweep before you commit to it, and best_reachable_noise catches the failure that motivated it. A cue the action lattice cannot land on is one no policy can read, and the null that produces is indistinguishable from "information is never worth the detour". It is pure geometry.
  • examples/gallery.py. The shared machinery the demos were each copying: three palettes, the GIF writer, the figure and still writers, the bacillus glyph as a style object, the covariance-ellipse geometry, the EFE sweep and decomposition panel, the action grid, and the two-route agreement report. Roughly 390 lines of duplication removed. Eight scripts touched. Every committed asset re-renders byte-identical to its pre-refactor baseline. tests/test_horizon_dimensions.py builds its arena from cue_maze rather than inlining a copy of it.
  • tests/test_cue_maze_parity.py. cue_maze.build_maze(1) is claimed to reproduce epistemic_dissociation_figure.build_backend(cue_x=CUE_DETOUR_X) element for element, and the registered crossover is measured on the latter. The claim held on two files kept in sync by hand. Now it holds on dims, root, A, Q, B, the coupling and its noise, C, and R(x) sampled the length of the corridor rather than at one point. The frozen twins are excluded, because they genuinely differ and cue_maze.py says why.
  • mkdocs_hooks.py. Expands --8<-- snippet includes and rewrites the relative links inside them to site-local targets, so examples/README.md can carry links that work both on GitHub and on the published site without hard-coding either. tests/test_docs_hooks.py gates it, dead links included.

Changed

  • EFESelector now reports a warrant of CORROBORATED. It samples a continuum, so it can corroborate a universal over the action space but never decide one. The enumerated search's PROVED prints in different words for exactly that reason.
  • examples/ffg/crossover.py --check reports the four registered falsifiers one line each, in three-valued outcomes, rather than closing on a single PASS. A falsifier that is void by construction did not pass a test, and one the gate skips now says so instead of borrowing the write-up's answer (ADR-029).

  • The README's crossover section says what the horizon result is for. It now cites arXiv:2607.20306, which establishes that R(x) makes the epistemic term non-constant, and separates that from the question this repo answers: the horizon at which the term starts changing which plan gets picked. The answer given is the one-dimensional H* = 7, with its warrant stated (exhaustive over the declared {0, ±1, ±2}, completeness certificate, upper bound because the grid clips the reach), and the plane figure is labelled as the readable illustration rather than the proof. examples/README.md carries the same distinction at length.

  • examples/bacillus_uncertain_food.py is gated. check_backend_agreement — KalmanBackend against the FFG ChainBackend on one scripted input sequence, atol=1e-7 — now runs in tests/test_example_checks.py. The README's flagship had no test of any kind before this.
  • gallery.precision_field samples the model's own noise_fn instead of re-deriving the well from its parameters, and takes the channel to read as a required argument. It had been asserting the sensor was a CallableSensor and then ignoring it, so on the flagship it drew the right channel by coincidence of how that model's block_diag is ordered. A demo with a different layout would have got a silently wrong figure that still passed the assert. One vmap replaces the res² Python-level calls, so the field is also cheaper to draw. The flagship's field agrees with the old computation to 2e-15, float noise from the vmap and nothing else, well under the width of a contour band.
  • gallery.print_two_route_agreement is check_two_route_agreement and raises on a disagreement. It printed FAIL and returned, and neither caller was gated, so a broken equivalence would have exited zero. coupling_graph_figure.check and chemotaxis_figure.check are public and run in tests/test_example_checks.py.
  • DECISIONS.md states at the top that a path inside an ADR is the path as of that ADR's date. examples/bacillus_seeking_food.py and examples/bacillus_lqr.py are named by ADR-008 and ADR-013 and no longer exist, which the append-only rule requires and which the file previously left the reader to work out.
  • mkdocs_hooks.py skips a fenced block wherever it is indented, and skips inline code spans. Both were anchored at column zero, so a fence inside a numbered step, which is ordinary markdown, had its links rewritten and reported dead, and mkdocs build --strict aborted the docs deploy on a correct README edit. Reference definitions ([label]: path) are now repointed and dead-link checked too. They resolve to real anchors and previously escaped both, so the repository's layout shipped to the site. A four-space indented code block is still not recognised, and the module docstring says so and says why: the same pattern matches four-space list continuation, so closing it would trade a loud build failure for a silently wrong link. All four included sources rewrite byte-identically across the change.
  • cue_maze.enumeration_cost takes context_dim. It hardcoded a joint width of 1 + 2·n_dims while build_maze builds context_dim + 2·n_dims, and the estimate is quadratic in that width, so a two-wide context was priced 1.44x low and a four-wide one 2.56x low, on top of the 1.6x floor the docstring already warns about, against a number whose whole job is to stop a sweep taking the machine down. tests/test_horizon_dimensions.py recovers the width the estimate charged for and pins it to the built backend's own n_total across five (n_dims, context_dim) pairs.
  • The slow pytest marker is a wall-clock rule now, not a description of one test. Anything past conftest.SLOW_TEST_SECONDS (20s) carries it and runs on merge-to-main and release rather than on pull requests. conftest.py measures each run and prints any unmarked test that has drifted over, so the rule does not depend on anyone remembering it. One test crosses the line and is newly marked: test_double_integrator_horizon.py::test_h2_choice_matches_brute_force_oracle (~21s). Marks are decided on an isolated run on the owner's development machine, which conftest.py now records as the reference. Wall clock is machine-relative, and without one the same suite marks differently per reviewer. Pull-request coverage is unaffected at 93.8% against the 80% gate.

Removed

  • The ## The journey section of examples/README.md, and with it the gallery entries for bacillus_seeking_food.py, bacillus_lqr.py, efe_collapse_figure.py and internal_noise_figure.py. efe_collapse_figure.py and internal_noise_figure.py stay, keep their check() gates, and keep their figures, which DECISIONS.md still cites. docs/assets/bacillus.gif and docs/assets/bacillus_lqr.gif had no other referrer and go with the section, 4.2 MB of them.
  • examples/bacillus_lqr.py. Every claim it demonstrated is asserted elsewhere and more strongly: the LQR reduction at exact array equality in tests/test_agent.py::test_state_goal_path_is_byte_identical_to_lqr, and the epistemic collapse three times over in tests/test_efe.py, tests/test_theorem.py and efe_collapse_figure.py's gated check(). Nothing imported it.
  • examples/bacillus_seeking_food.py. It had stopped being a demo and become an undeclared dependency: bacillus_uncertain_food.py imported its beacon falloff, its palette, its glyph and its precision field at module scope, so the README's flagship could not run without it and no test would have said so. The shared parts are now gallery.beacon_noise, gallery.precision_field and gallery.SMALL_BACILLUS; the beacon geometry moved into the flagship, which is the only thing that used it. The flagship's GIF re-renders byte-identical to the committed one across the move. Its own claims were already asserted in tests/test_agent.py, tests/test_efe_selector.py and tests/test_efe.py, whose TestPrecisionControlsBalance was written for it. ADR-008 and ADR-013 still name the path; DECISIONS.md is append-only, so those references stand as the historical record.

Deferred and unsupported

Named here so each boundary is a statement rather than an omission. Each has an issue.

  • A closed-loop FfgEfeSelector above H = 1 stays unsupported, not untested. The rollout it would need now exists and the FFG-backed drivers would make it nearly free, but nothing in scope uses it. (#52)
  • No pruning of the |A|^H search. A pruner that cannot prove what it discarded would destroy the completeness certificate, which is the only reason the search is worth having, so it waits for a design that starts at the certificate. (#53)
  • No continuous or gradient search over varying sequences. This one is a deliberate wall: gradient ascent on a non-convex objective corroborates and cannot decide, so letting it near the enumerated evidence would downgrade the certificate that evidence exists to earn. It is registered as a separate, separately-labelled track. (#54)
  • Q(x) above H = 1 remains undocumented and unclaimed. It may work; nothing says so and nothing tests it. (#56)

[0.4.3] — 2026-07-27

Closes the code-side divergences found by auditing the library against the paper written about it (PAPER_DIVERGENCE.md). The paper's own quoted numbers are unchanged and both demonstrations' --check gates still pass; the paper-side items are tracked separately.

Added

  • cpomdp.diagnostics — the conditions a state-dependent sensor has to meet, asked over the states an action can actually reach. probe_model(model, belief, actions) predicts under each candidate action and reports a SensorReport: whether C has full row rank, whether R stays positive definite, whether R moves at all across the reachable means, and whether the epistemic value moves with it. is_positive_definite, epistemic_value and loewner_order are exposed alongside for use on their own. probe_model and SensorReport are re-exported at the top level. A declared R(x) that no action can move now has something that says so.
  • tests/test_theorem.py — one test per published claim: the pinning result and its rank-deficient counterexample, the dual effect on both the posterior covariance and the gain, the impossibility of a fixed noise schedule, the scalar monotonicity, the zero-innovation realisation, the planning-reduction equivalence, the level-set construction where the covariance moves but the epistemic value does not, and the worked one-step numbers (gains 2/3 and 2/7, ½ln3 and ½ln(7/5)).
  • tests/test_diagnostics.py covering the new module.
  • examples/efe_collapse_figure.py --check now also asserts the dual effect directly — the posterior variance and the Kalman gain moving across the action grid — rather than only the epistemic scalar that rides on it.

Fixed

  • The FFG epistemic term had no positive-definiteness guard. _efe_step mapped a non-positive-definite R to NaN so it would lose the selector's argmin; _state_info_gain, the term the coupling-graph path actually scores, discarded the determinant signs and returned a finite, plausible-but-wrong value that could win. Both now share one _logdet_pd helper, which tests positive definiteness by Cholesky rather than by determinant sign — the sign passes any matrix with an even number of negative eigenvalues, diag(-1, -2) among them.
  • CouplingGraphBackend.model handed out a frozen R. For a state-dependent graph the flat model carried the noise evaluated once at a representative state, so anything filtering with it silently used the wrong noise at every step. The model now carries a _JointObservation that linearizes each node's R at that node's slice of the mean, the same point the backend's own filter uses.
  • Agent could not see a graph's state-dependence. Because that flat model declared no observation model, a coupled R(x) backend read as a fixed sensor and a StateGoal was accepted onto it, silently selecting actions with the certainty-equivalent LQR controller. It now raises, as it always did on the flat path.
  • The theorem's own model class could not be flattened. A single chain with no couplings raised NotImplementedError; it now emits a faithful state-dependent flat model, verified to reproduce the native filter to ~1e-16. It is a state-dependent model, not a fixed one — no fixed one exists.
  • examples/ffg/epistemic_dissociation_figure.py numbered its first two results the opposite way round to the write-up, and printed them out of order. Result 4 asserted only that the best action B rates below the pragmatic-only agent is cue-ward; it now asserts the claim actually made, that every such action is.

Changed

  • The IncompatibleLinearizationError message gains a closing sentence: the guard reads the sensor's declared state-dependence, and a declared R(x) that ignores the state is constant in fact and does flatten. The original two sentences are unchanged, so the message is now a strict extension of what came before. Whether R really varies over reachable means is what cpomdp.diagnostics.probe_model is for.
  • Trimmed prose in src/ that had gone stale: references to an rfcs/ directory that does not exist, sensors and selectors described as arriving in a release that has shipped, and the unqualified claim that the predicted covariance is action-independent — true of a single step, false over a horizon under R(x) or Q(x).

[0.4.2] — 2026-07-18

Archival release accompanying the paper. No library code changed — the public API and numerics are identical to 0.4.1. The changes are in the example check suite, which the paper's reproducibility claims quote, and are now gated in CI.

Added

  • A single-chain theorem-instance check on the EFE-collapse demo (examples/efe_collapse_figure.py --check): the model class of the paper's section 3.1 — one node, no couplings, additive control, a state-dependent R(x) sensor — run through the flat KalmanBackend(CallableSensor) route, asserting Theorem 1 clauses (i) and (iii): the one-step epistemic value varies across the action grid, its frozen-R twin is flat (the ADR-003 collapse), and R(μ⁻) traces a curve. Runs with no plotting deps.
  • tests/test_example_checks.py runs both demos' check() gates in CI, so their paper-facing assertions fire on every test run rather than only when the script is run by hand.

Changed

  • Strengthened Result 4 of the epistemic-dissociation demo (examples/ffg/epistemic_dissociation_figure.py --check): _boundary_scan now also returns the pragmatic term, and Result 4 prints and asserts the horizon-1 ordering epistemic pull < pragmatic gradient — the "reaches without walking" claim, previously an unasserted diagnostic number, is now a checked fact.

[0.4.1] — 2026-07-13

Maintenance release cut for the paper-1 Zenodo archive. No library code changed — the public API and numerics are identical to 0.4.0.

Changed

  • Reworked the epistemic-dissociation flagship figure (examples/ffg/epistemic_dissociation_figure.py): renamed the candidate action to u to stop it clashing with "Agent A", moved the R(mu+u) label into a clean gap, and added paper-facing assertions that pin Result 2 at the geometry where only B's edge over A survives. Regenerated docs/assets/epistemic_dissociation_boundary.png.

[0.4.0] — 2026-07-06

Forney factor-graph (FFG) message passing — the continuous-state generalisation of the Kalman/EFE path to a branching model the chain cannot draw cleanly (ADR-012, ADR-014). The chain is the degenerate case and stays validated byte-numerically against the Kalman filter.

Added

  • FFG message passing in canonical/information form, owned from-scratch in JAX, reachable under cpomdp.ffg.* (the model-construction symbols are also re-exported at the top level — see the public-surface entry below, ADR-021):
  • CanonicalGaussian (cpomdp.ffg.message) — the (Λ, h) message payload; factor product is addition, marginalisation a Schur complement, moment form a readout view.
  • Tier-1 linear-Gaussian factor nodes (cpomdp.ffg.factors.linear_gaussian): GaussianObservation, GaussianTransition, GaussianCoupling.
  • ChainBackend (cpomdp.ffg.chain) — an InferenceBackend over a linear chain, numerically identical to KalmanBackend (atol 1e-7, the keystone gate), including state-dependent R(x)/Q(x) parity.
  • CouplingGraph (cpomdp.ffg.graph) — the v0.4 core representation: integer-indexed nodes coupled into a rooted tree with a shared node of degree > 2, inferred by a hand-authored deepest-first tree-collect schedule (only the root crosses moment form, so the inversion cost is per-root, not per-node). levels() is deferred (ADR-015).
  • CouplingGraphBackend (cpomdp.backends.coupling) — the branching FFG as a recursive Gaussian filter satisfying InferenceBackend (issue #25): driven-relaxation composition (each node's own dynamics + its structural parent's drive every slice, ADR-017), the exact full-joint carry (ADR-016), marginal/readout for any node, and to_flat_model (structural couplings as within-slice pseudo-observations). Validated at atol 1e-7 against an independent NumPy joint-precision oracle, KalmanBackend, and RxInferBackend on the flattened model.
  • Carry partition on CouplingGraphBackend (ADR-016): a partition of the node set controls which between-cluster correlations survive the time boundary — [[all]] (the default) keeps the exact full joint, singletons fully factor it. The carry factors the joint covariance (not the precision), so every node's marginal stays exact within a slice (ADR-017); only the cross-cluster correlation carried forward is dropped. A pure partition_error reports the severed mass (a covariance magnitude, not a rate), and rollout profiles it over a whole sequence in one traced lax.scan pass. A fully-factored (singleton) partition runs cheap two-pass tree belief propagation (CouplingGraph.infer_all, plus GaussianCoupling.message_to_child and CanonicalGaussian.__sub__) in place of the dense joint solve — O(tree) rather than O(n³), matching the dense path to atol 1e-7. The exact endpoint stays byte-identical under [[all]].
  • State-dependent sensing R(x) on the branching backend (issue #27, ADR-019): a CallableGaussianObservation factor and a two-pass linearisation that reads R at the coupling-resolved predictive mean μ⁺ — the dual effect (observation_noise_at, predicted_belief).
  • FfgEfeSelector scores the per-candidate epistemic term over the FFG, so an Agent with an ObservationGoal(info_target=…) seeks information through a branch. severed_efe_edges / InadmissiblePartitionError reject a carry partition that would sever an EFE-relevant edge (ADR-018).
  • IncompatibleLinearizationError (cpomdp.backends.coupling): to_flat_model raises it when a coupled R(x) model is asked to flatten. A mean-shifting coupling makes μ⁺ ≠ μ⁻, so no fixed linear-Gaussian model reproduces R(μ⁺) (ADR-019, ADR-020).
  • Public surface (ADR-021): the branching construction symbols (CouplingGraph, Coupling, CouplingGraphBackend, IncompatibleLinearizationError, the four Gaussian factors) and the selector family (ActionSelector, EFESelector, FfgEfeSelector, LQRSelector) now sit in the top-level cpomdp namespace. FfgEfeSelector gains EFESelector's n_candidates / horizon / cost_per_cycle.
  • Examples: epistemic_dissociation_figure.py, the v0.4 flagship — two agents on one maze, differing only in a state-dependent vs. fixed cue sensor; the R(x) agent resolves the hidden context through a branch and crosses to the reward, the fixed-sensor agent collapses to LQR, and the R(x) model can't be flattened (IncompatibleLinearizationError). bacillus_uncertain_food.py, the instrumental-epistemics demo — the beacon resolves an explicit food latent rather than the agent's own position (ADR-013), on both KalmanBackend and ChainBackend. coupling_graph_figure.py, the difference demo — a branching tree resolved natively vs. the hand-flattened joint precision. chemotaxis_figure.py, the same on a real branching network (the E. coli chemotaxis pathway's shape, native FFG vs flattened Kalman) — illustrative only, no biophysics (ADR-020).

Validation

  • RxInfer oracle (behind the rxinfer marker) extended to the branching tree, alongside the existing chain checks; jit/grad/vmap smoke tests gate every new public inference entry point.

[0.3.0] — 2026-06-22

Epistemic action selection. v0.2 could perceive and pursue a goal; v0.3 lets the agent seek information — it minimises Expected Free Energy G = pragmatic − epistemic, so it will detour to where its sensor is sharp, localise, then act. Under a fixed sensor this collapses exactly to the v0.2 LQR behaviour (ADR-003), so that path is unchanged.

Added

  • Expected Free Energy action selection: expected_free_energy (the one-step kernel) and EFESelector (a front-loaded candidate grid, argmin G). Observation-space cross-entropy pragmatic minus state info-gain epistemic (ADR-005).
  • State-dependent sensing and dynamics: CallableSensor for R(x) and CallableProcessNoise for Q(x), honoured in both the planner and the Kalman filter (ADR-006, ADR-008). The fixed-matrix path stays byte-identical.
  • Typed objectives: StateGoal (state-space → LQR) and ObservationGoal (observation-space → EFE). The Agent dispatches on the objective's type, so an illegal pairing is unrepresentable rather than a runtime check (ADR-007).
  • H-step horizon: EFESelector(horizon=H) scores constant-action policies over an H-step rollout (default H=1), making delayed consequences visible — e.g. acting on velocity to steer an observed position (ADR-009).
  • ModelStructure: optional, declarable factor / Markov-blanket / sensory-channel metadata on a model, with inspection and an opt-in, experimental validate() that checks the declaration against the matrix sparsity (ADR-010).
  • Public building blocks for the above: ObservationModel, FixedSensor, DynamicsNoise.

Changed

  • Breaking (pre-1.0): Agent takes a typed objective instead of goal=/goal_precision= keywords. Agent(model, goal=[1.0, 0.0]) becomes Agent(model, StateGoal([1.0, 0.0])); observation-seeking uses ObservationGoal(...) (ADR-007).

[0.2.0] — 2026-06-16

The array backend moves from NumPy to JAX (ADR-004). v0.1 was a proof of concept; this is the groundwork for the autodiff and batching v0.3 is aiming at.

Changed

  • The core runs on jax.numpy. Belief and LinearGaussianModel now hold jax.Arrays, and the Kalman filter and LQR are pure jnp. If you were reaching past the public API and expecting numpy.ndarray off belief.mean, you'll get a jax.Array now — both still hand off to NumPy, so most code won't notice.
  • Importing cpomdp switches JAX into float64 mode (jax_enable_x64) process-wide. The library is validated to 1e-9 against the RxInfer oracle and JAX defaults to float32, so this keeps the numbers right — but it does change float behaviour for any other JAX code in the same process.

Added

  • Belief and LinearGaussianModel are registered JAX pytrees, so they flow through jit, vmap, and grad as data.
  • The Kalman step is split into pure, jit-compiled kernels — one filter step now vmaps over a batch of beliefs.

Dependencies

  • Added jax and jaxtyping. NumPy stays: JAX pulls it in anyway, and the RxInfer backend still hands real NumPy arrays across the Julia bridge.

[0.1.1] — 2026-06-15

A metadata-only re-release, functionally identical to 0.1.0. The 0.1.0 release has been removed from PyPI, so use 0.1.1.

Changed

  • Trimmed the author entry in the package metadata.
  • README: the DECISIONS.md link is now an absolute URL, so it resolves on PyPI.

[0.1.0] — 2026-06-15

The first cut. Linear-Gaussian active inference, end to end: perceive with a Kalman filter, act with LQR, all behind a pymdp-style Agent.

Added

  • Agent, the stateful façade you actually drive. infer_states to perceive, sample_action to act, the same loop pymdp users know. It remembers the last action it took, so you don't have to thread that back in by hand. Build it without a goal and it's a pure tracker that perceives but won't act.
  • LinearGaussianModel, the generative model. Matrices are named for their role (dynamics, control, sensor_model, dynamics_noise, sensor_noise), with the control-theory letters (A/B/C/Q/R) kept as aliases for when you're reading the maths.
  • Belief, an immutable Gaussian belief: a mean and a covariance, validated on the way in.
  • KalmanBackend, exact Kalman filtering. Has an optional steady-state mode that solves the gain once up front and reuses it.
  • LQRController, steady-state LQR action selection. For a linear-Gaussian sensor this is the expected-free-energy-optimal action rather than a stand-in for it (the why is in DECISIONS.md, ADR-003).
  • RxInferBackend, an optional RxInfer (Julia) backend. It re-derives the same filtering results through completely separate machinery and exists as a correctness oracle for the native path. Lives behind the rxinfer extra so the core install stays Julia-free.
  • InferenceBackend, the protocol the backends satisfy, so you can drop in your own engine.

This is pre-alpha. The API works and is tested against the RxInfer oracle, but it can still move before 1.0.