feat(retrieval): seventh meta-belief consumer — adaptive posterior_temperature (#758)

[robotrocketscience]

Closes #758. Sub-task D of umbrella #480 (adaptive meta-belief layer). Pattern reuse of the #756 / #757 / #759 / #760 family.

Scope

Wires the sweeper delivery path for meta:retrieval.posterior_temperature. The decoder surface (resolve_posterior_temperature_with_meta, the [0.5, 2.0] guard band, the log-linear decode, the static_default = 0.5 → T = 1.0 cold-start byte-identity) was already shipped by #796 / PR #807. What this PR adds is the learning loop: an env flag, a sweeper subscription, and an idempotent installer.

Changes

• ENV_META_BELIEF_POSTERIOR_TEMPERATURE = "AELFRICE_META_BELIEF_POSTERIOR_TEMPERATURE" — new env var, default-OFF, accepts 1 / true / yes / on / enabled.
• is_meta_belief_posterior_temperature_enabled() -> bool — mirrors is_meta_belief_expansion_gate_token_threshold_enabled.
• install_posterior_temperature_meta_belief(store, *, now_ts) -> bool — idempotent. Relevance signal only (weight 1.0). 30-day posterior decay. Cold-start value 0.5.
• get_active_meta_belief_consumers() extended to include META_POSTERIOR_TEMPERATURE_KEY when the new flag is on, so the Live close-the-loop relevance-signal infrastructure — #756 / #480 prereq #779 UPS sweeper delivers relevance evidence.
• 26 new tests in tests/test_posterior_temperature_meta.py. Full suite green (4206 pass on pre-rebase HEAD; tests reverified post-rebase against current main with PR feat(retrieval): ζ bounded posterior-contribution rerank surface (#817, closes #800) #826 / ζ surface merged).

resolve_posterior_temperature_with_meta is not modified — it already reads the meta-belief whenever store is supplied (locked behavior from #796). The new flag controls only whether the sweeper feeds evidence in.

Two-axis flag state machine (intentional)

AELFRICE_USE_GAMMA_POSTERIOR_TEMPERATURE	AELFRICE_META_BELIEF_POSTERIOR_TEMPERATURE	Effective behavior
off	off	log-additive baseline; meta-belief never read or written
on	off	γ rerank with fixed cold-start T = 1.0; no learning
off	on	sweeper writes evidence to the meta-belief; γ rerank not active so T unused
on	on	full adaptive loop: γ rerank reads T, sweeper updates it

Both flags default-OFF until bench-corpus evidence clears the gate.

Decisions deferred to reviewer

1. Signal direction inversion vs issue-body spec

The issue body (#758 § Acceptance) specifies:

very-low-relevance run pushes temperature higher (flattens distribution → more exploration); very-high-relevance run pushes temperature lower (sharpens).

The shipped substrate semantics (this PR + the #796 decoder) deliver the opposite direction:

• evidence = 1.0 (high relevance, referenced) increments the Beta-Bernoulli posterior α → posterior value → 1.0 → log-linear decode → T → CEIL = 2.0 (flatter / more exploration).
• evidence = 0.0 (low relevance, not referenced) increments β → value → 0.0 → T → FLOOR = 0.5 (sharper / more exploitation).

Both directions are defensible bandit policies — issue body wants exploit-on-win, substrate gives explore-on-win — but they are not equivalent. The tests in this PR pin the substrate direction; they would fail if the decode were inverted. Default-OFF ships are safe either way (no production behavior change until both flags flip), but the direction must be ratified before the flip-default PR.

Three resolution paths if the issue-body direction is preferred:

• (a) Invert the decoder. Change T = exp(log_floor + v * (log_ceil - log_floor)) to T = exp(log_ceil - v * (log_ceil - log_floor)) in resolve_posterior_temperature_with_meta. Cold-start byte-identity at value = 0.5 is preserved (still T = 1.0). Modifies surface shipped under feat(retrieval): Boltzmann softmax rerank surface — precursor to #758 (operator path B) #796.
• (b) Invert the evidence at the sweeper-side. Pass 1 - referenced instead of referenced for this specific consumer key. Sweeper-local; surface unchanged. Requires a per-consumer "invert" attribute or a custom write path.
• (c) Accept the substrate direction. Update the issue body's acceptance language. Bandit-policy defensible: when retrieval is landing well, broaden the next K; when it's missing, sharpen on what scored highest.

My recommendation is (c) — explore-on-win is the standard ε-decreasing posture and the substrate already happens to match it. But this is the reviewer's call.

2. Guard band [0.5, 2.0] vs issue-body [0.1, 10.0]

The issue body specifies T ∈ [0.1, 10.0]. #796 ratified the shipped bounds at [POSTERIOR_TEMPERATURE_FLOOR, POSTERIOR_TEMPERATURE_CEIL] = [0.5, 2.0] because the cold-start byte-identity requirement pins decode(0.5) = 1.0, and [0.5, 2.0] has geometric mean exactly 1.0 with no float error. This PR does not change those bounds. If the wider [0.1, 10.0] band is actually wanted, the bounds change should land separately and choose a static_default that decodes to 1.0 under the new band (v = log(1.0) / (log(10.0) - log(0.1)) + log(0.1) / (log(10.0) - log(0.1)) = 0.5, so static_default = 0.5 still works — the bound change is the simple part; the harder part is whether [0.5, 2.0] is in fact too narrow once adaptive learning is live).

Bench gate

Per #758 the gate is #437 A/B: meta-belief-driven vs hardcoded baseline, ≥+2pp recall-at-k. The labeled rerank-relevance corpus that this gate needs is currently the deliverable of #819, which is in-flight. Ship default-OFF; flip-default after #819's corpus exists and the A/B clears.

Commits

1. feat(retrieval): install_posterior_temperature_meta_belief + adaptive-flag query for #758
2. feat(retrieval): include posterior_temperature in get_active_meta_belief_consumers (#758)
3. test(retrieval): coverage for #758 posterior_temperature meta-belief consumer
4. docs(changelog): note adaptive posterior_temperature consumer (#758)

Rebased onto github/main (ca0b09ce) post-#826 ζ-surface merge; CHANGELOG [Unreleased] ### Added conflict resolved by keeping both bullets.

Summary by CodeRabbit

• New Features

  • Added adaptive posterior temperature meta-belief consumer with environment flag control (ships default-OFF; backward-compatible).

• Documentation

  • Updated changelog documenting the new posterior temperature meta-belief feature and configuration options.

• Tests

  • Added 26 new tests covering meta-belief installation, temperature resolution, evidence responsiveness, and integration behavior.

[sourcery-ai]

Sorry @robotrocketscience, you have reached your weekly rate limit of 500000 diff characters.

Please try again later or upgrade to continue using Sourcery

[github-actions]

PR-size soft cap

This PR is over the advisory size threshold:

• 380 changed lines (limit: 200)
• 3 changed files (limit: 3)

Bigger PRs collide with more open work, which under the parallel-session workflow tends to produce repeated attn:merge-conflict cycles (see #602). When practical, split into smaller PRs that each touch a focused surface.

This is advisory only — nothing is blocked. If the size is intentional (large refactor, module removal, generated code), apply the size:override label and this comment will be removed on the next push.

[robotrocketscience]

[claim:review:bagheera:2026-05-14T23:37:01Z]

[robotrocketscience]

[claim:review:clarke:2026-05-14T23:37:44Z]

[robotrocketscience]

[release:review:clarke:2026-05-14T23:37:49Z]

[robotrocketscience]

[claim:review:oppenheimer:2026-05-14T23:38:50Z]

[robotrocketscience]

[release:review:oppenheimer:2026-05-14T23:38:55Z]

[coderabbitai]

Warning

Rate limit exceeded

@yoshi280 has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 40 minutes and 53 seconds before requesting another review.

You’ve run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 2301cb8b-d25b-43f7-bfa2-3e00611b2d22

📥 Commits

Reviewing files that changed from the base of the PR and between af67607 and d664fd7.

📒 Files selected for processing (3)

• CHANGELOG/v3.md
• src/aelfrice/retrieval.py
• tests/test_posterior_temperature_meta.py

📝 Walkthrough

Walkthrough

This PR implements the seventh meta-belief consumer (posterior_temperature) with feature gating, idempotent store installation, active-consumer wiring, and 26 comprehensive tests covering flag parsing, constant values, idempotent installation, cold-start resolution, evidence responsiveness, determinism, and consumer discovery integration.

Changes

Posterior Temperature Meta-Belief Integration

Layer / File(s)	Summary
Feature flag and enablement predicate src/aelfrice/retrieval.py, tests/test_posterior_temperature_meta.py	ENV_META_BELIEF_POSTERIOR_TEMPERATURE constant gates feature availability; is_meta_belief_posterior_temperature_enabled() resolver honors truthy/falsy tokens and "enabled" spelling. Tests validate flag parsing for unset, truthy, and falsey cases.
Meta-belief installer and idempotency src/aelfrice/retrieval.py, tests/test_posterior_temperature_meta.py	install_posterior_temperature_meta_belief() idempotently installs meta:retrieval.posterior_temperature using relevance-only signal weights, static default 0.5, and configured posterior decay seconds. Installation tests verify first-call insertion, second-call no-op, and stored metadata.
Consumer activation and integration src/aelfrice/retrieval.py, tests/test_posterior_temperature_meta.py	get_active_meta_belief_consumers() docstring and logic updated to include META_POSTERIOR_TEMPERATURE_KEY when the flag is enabled. Integration tests assert posterior-temperature is excluded when off, included when on, and returned list is alphabetically sorted.
Behavior validation tests tests/test_posterior_temperature_meta.py	Cold-start tests assert static default 0.5 resolves to exactly 1.0 via geometric-mean formula. Responsiveness tests apply 100 strong positive and negative relevance updates, verifying temperature stays bounded and moves monotonically. Determinism tests confirm identical evidence sequences produce identical resolved values.
Changelog documentation CHANGELOG/v3.md	Unreleased entry documents the new seventh meta-belief consumer, its feature flag, API surface, independence from gamma rerank temperature, default-OFF shipping, and 26-test coverage.

🎯 2 (Simple) | ⏱️ ~12 minutes

Suggested labels

author-fourier

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 79.17% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and specifically describes the main change: adding a seventh meta-belief consumer for adaptive posterior temperature control, referenced with the PR number.
Description check	✅ Passed	The PR description comprehensively covers all template sections: summary, linked issues (#758, #480), type of change (feat), verification checklist items addressed, detailed test plan and notes for reviewer including deferred decisions.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/issue-758-posterior-temperature-adaptive-consumer

Tip

💬 Introducing Slack Agent: The best way for teams to turn conversations into code.

Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.

• Generate code and open pull requests
• Plan features and break down work
• Investigate incidents and troubleshoot customer tickets together
• Automate recurring tasks and respond to alerts with triggers
• Summarize progress and report instantly

Built for teams:

• Shared memory across your entire org—no repeating context
• Per-thread sandboxes to safely plan and execute work
• Governance built-in—scoped access, auditability, and budget controls

One agent for your entire SDLC. Right inside Slack.

👉 Get started

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[robotrocketscience]

Review: rebased and ready

PR by sister session, 4 commits all signed (G), CI green, BEHIND main was the only blocker.

Rebase: clean — no conflicts. Main moved 7 commits via #821 (hot-path); this PR's only file overlap was CHANGELOG/v3.md, which was already in the post-#811-split shape on this branch (the author was aware of the split when authoring), so the rebase applied without manual intervention.

Code-side verification:

• New env flag AELFRICE_META_BELIEF_POSTERIOR_TEMPERATURE and is_meta_belief_posterior_temperature_enabled() predicate — pattern mirrors the existing meta-belief consumers ([v3.x] B: meta:retrieval.temporal_half_life_seconds — first-meta-belief pattern validator (#480 sub-task) #756 / [v3.x] C: meta:retrieval.bm25f_field_weights — adaptive per-field weights (#480 sub-task) #757 / [v3.x] E: meta:retrieval.bfs_depth_budget — adaptive L2 depth cap (#480 sub-task) #759 / [v3.x] F: meta:retrieval.expansion_gate_thresholds — adaptive #741 knobs (#480 sub-task) #760).
• META_POSTERIOR_TEMPERATURE_KEY added to get_active_meta_belief_consumers()'s sort-and-return; canonical-sort property preserved.
• install_posterior_temperature_meta_belief() — idempotent, single-signal (SIGNAL_RELEVANCE only), 30d decay matching the rest of the [exploration] Adaptive half-life as a Bayesian-engine-governed meta-belief #480 family.
• Cold-start byte-identity preserved: static_default = 0.5 decodes to T = 1.0 via resolve_posterior_temperature_with_meta (geometric mean of FLOOR=0.5 and CEIL=2.0 in log space), which is the existing baseline.
• Two-flag composition called out in the docstring: γ-rerank is gated by ENV_USE_GAMMA_POSTERIOR_TEMPERATURE (feat(retrieval): Boltzmann softmax rerank surface — precursor to #758 (operator path B) #796), this flag separately gates whether T learns from relevance evidence. Independent axes, both default-OFF.

Pre-push gates:

• pytest -x -q --timeout=120 → 4270 passed, 62 skipped, 75 xfailed in 121s.
• Targeted: tests/test_posterior_temperature_meta.py → 26 passed in 6s.
• Discretion grep on git diff main...HEAD → 0 hits.

Verdict: ready-to-merge. Adding label, releasing claim.

[robotrocketscience]

[release:review:bagheera:2026-05-14T23:41:26Z]

[github-actions]

merge-train: blocked

branch is not fast-forward on main (branch base 2dd86dfedbbd206cf0489d32fc507a5502b5e72c, current main 5f71d80204707a116b36b0fa6e54b22c0e41826b). Rebase locally (git rebase github/main), force-push, and re-add the label.

The ready-to-merge label has been removed. Address the issue above and re-add the label when you're ready for another attempt.

[robotrocketscience]

[claim:review:clarke:2026-05-14T23:43:36Z]

[robotrocketscience]

Approve-equivalent — content correct; needs rebase (#828 landed in the gap)

4 atomic signed commits, well-factored: surface (feat constants + is_meta_belief_*_enabled), wiring (get_active_meta_belief_consumers), tests (26 in a dedicated module), docs (CHANGELOG entry). +377/-3 across 3 files; the install function and flag predicate are tight copies of the #757 / #760 patterns — same shape, same _ENV_TRUTHY ∪ {"enabled"} token set, same 30-day decay.

Two-axis flag separation honored. resolve_posterior_temperature_with_meta is intentionally NOT touched here — the decoder ships in #796 and already reads the meta-belief when store is supplied. The new flag (AELFRICE_META_BELIEF_POSTERIOR_TEMPERATURE) gates only the sweeper-delivery path. The 2×2 state table in the PR body matches the code: γ-flag-only = fixed cold-start T=1.0; meta-flag-only = sweeper writes evidence but γ-rerank isn't consumed (no behavior change); both on = adaptive learning.

Verification: CI green (pytest 3.12 + 3.13, all 20+ gates). Discretion grep on the full diff returns zero hits. git merge-tree --write-tree against current main returns single SHA 4704b9d1 — rebase clean, no markers.

Blocker: NOT-FF on current main 5f71d802 (PR #828 / #827 heredoc fix merged in the gap). Author needs git fetch github main && git rebase github/main && git push --force-with-lease.

Swapping attn:review → attn:merge-conflict. After rebase, jump directly to ready-to-merge — content is shipped-shape.

[robotrocketscience]

[release:review:clarke:2026-05-14T23:44:55Z]

[robotrocketscience]

[claim:conflict:prince:2026-05-14T23:50:27Z]

[robotrocketscience]

[release:conflict:prince:2026-05-14T23:53:14Z]

[robotrocketscience]

[claim:review:oppenheimer:2026-05-15T01:16:50Z]

[robotrocketscience]

[claim:review:bagheera:2026-05-15T01:17:21Z]

[robotrocketscience]

[release:review:bagheera:2026-05-15T01:17:26Z]

[robotrocketscience]

Approve — rebased onto current main, ready-to-merge after CI

Picked this up post-prince's rebase to 5f71d802; current main moved to 04a68ba5 4 min after they pushed (single chore commit, scripts/sync-repo-settings.sh, zero file overlap with this PR). Rebased the 4 commits onto current main rather than bouncing back — three review cycles for a 1-commit gap with no conflicts is wasteful.

Rebase result:

• New head af67607e (was 812a9dfd)
• 4 commits all re-signed (G), same author, identical content delta
• git diff origin/main...HEAD byte-identical to pre-rebase: +377/-3 across CHANGELOG/v3.md, src/aelfrice/retrieval.py, tests/test_posterior_temperature_meta.py
• Discretion grep on full diff: 0 hits
• Force-pushed with explicit --force-with-lease=<branch>:812a9dfd... to avoid stale-lease overwrite (per locked memory on PR feat(rebuilder): post-compact <working-state> hot-start (#587) #591)

Code review (concur with clarke + bagheera): seventh meta-belief consumer follows the established #756 / #757 / #759 / #760 pattern — env-flag + predicate, idempotent install function, single-signal (SIGNAL_RELEVANCE), 30-day decay. Two-flag composition correct: this PR delivers evidence; #796's γ-rerank consumes it. Cold-start byte-identity preserved.

Will add ready-to-merge after CI confirms green on af67607e.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/aelfrice/retrieval.py`:
- Around line 396-398: The comment contains an ambiguous Unicode character "γ"
(e.g., in the phrase "γ-rerank" and references to
ENV_USE_GAMMA_POSTERIOR_TEMPERATURE); replace all occurrences of the glyph with
the ASCII word "gamma" (e.g., "gamma-rerank",
"ENV_USE_GAMMA_POSTERIOR_TEMPERATURE") in the comment block near the
sweeper/meta-belief explanation so lint (RUF003) and text searches work
reliably.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 26c9b469-4ade-4a60-a644-5abd9ad41172

📥 Commits

Reviewing files that changed from the base of the PR and between 04a68ba and af67607.

📒 Files selected for processing (3)

• CHANGELOG/v3.md
• src/aelfrice/retrieval.py
• tests/test_posterior_temperature_meta.py

[robotrocketscience]

[release:review:oppenheimer:2026-05-15T01:24:19Z]

[github-actions]

merge-train: blocked

branch is not fast-forward on main (branch base 04a68ba52cb32d78e17a02190c9daba9653667a8, current main 9cbbc7a05d0250ca8619a1f45b02e233c98fb956). Rebase locally (git rebase github/main), force-push, and re-add the label.

The ready-to-merge label has been removed. Address the issue above and re-add the label when you're ready for another attempt.

[github-actions]

merge-train: blocked

1 review thread(s) are unresolved on these files: src/aelfrice/retrieval.py. Resolve them on the PR (click 'Resolve conversation' on each) and re-add the label.

The ready-to-merge label has been removed. Address the issue above and re-add the label when you're ready for another attempt.

[robotrocketscience]

Resolving the RUF003 γ-glyph thread as wontfix-here: existing src/aelfrice/retrieval.py on main already contains 13 occurrences of γ (and the parallel ζ symbol on the #817 surface), and RUF003 is not enabled in the project's ruff config — this is a coderabbit advisory, not a CI gate. Replacing γ only in the new lines this PR adds would be a style regression against the surrounding code. If the project wants ASCII-only mathematical names, the right move is a separate sweep across src/aelfrice/retrieval.py + src/aelfrice/scoring.py and a ruff config flip — not piecemeal in this PR.

Re-adding ready-to-merge.

[github-actions]

merge-train: merged d664fd7 → main via FF push.

[robotrocketscience]

[claim:review:clarke:2026-05-15T03:07:01Z]

[robotrocketscience]

[release:review:clarke:2026-05-15T03:07:54Z]