docs(limitations): the exposure-as-evidence path has not existed since #1162 (#1267)

[robotrocketscience]

Refs #1267. Does not close it — #1267's first acceptance criterion is an
operator decision on direction, and that is still open. What this lands is the
measurement that decision should be taken against, plus the one concrete doc
defect the measurement exposed.

Attribution first

The premise correction below was reached independently, but not first. The
framing comment on #1267
got there earlier and went further — it enumerates the apply_feedback call
sites exhaustively, confirms both defaults by calling them, and backs it with
the live store (594 beliefs sitting exactly on their ingest prior after 13,812
exposures). It is the record on the premise; this section is context for the
change, not a claim of discovery.

What is new here is the doc defect that enumeration could not surface, and
the guard against it recurring. The deferred-feedback sweeper stopped being an
apply_feedback caller at #1162, so it correctly does not appear in that
table — but LIMITATIONS.md still described it as one.

The issue's stated asymmetry does not hold on main

#1267 opens with:

The system has an automatic, evidence-driven channel that moves posteriors
up, and none that moves them down.

I drove every production apply_feedback route against a fresh store rather
than reading the constants. Both halves of that sentence are wrong, in
opposite directions.

channel	direction	wired	default	moves α/β at default?
hook retrieval exposure, HOOK_RETRIEVAL_VALENCE = +0.1	up	hot path, every pack, every fire	off (#1086)	no
deferred-feedback sweeper (#191), +0.05	up	manual CLI only	audit-only (#1162)	no
sentiment-from-prose (#193/#606), −1.0 / −1.5, escalating −2.0	down	hot path, UserPromptSubmit (hook.py:976)	off (opt-in)	no
aelf feedback <id> used|harmful	both	manual	n/a	yes

CHANNEL 1 — hook retrieval exposure (valence +0.1)
  DEFAULT (unset)                        a/b (1.0, 1.0) -> (1.0, 1.0)  moved=False
  AELFRICE_EXPOSURE_UPDATES_POSTERIOR=1  a/b (1.0, 1.0) -> (1.1, 1.0)  moved=True

CHANNEL 2 — sentiment-from-prose (UserPromptSubmit, #193/#606)
  is_enabled(default config) = False
  detect_sentiment("no that's wrong") -> (negative, -1.5)
  negative signal    a/b (1.0, 1.0) -> (1.0, 2.5)   moved_down=True
  escalated negative a/b (1.0, 2.5) -> (1.0, 4.5)
  magnitude vs exposure: 10x .. 20x

CHANNEL 3 — deferred-feedback sweeper (#191, audit-only since #1162)
  is_enqueue_on_retrieve_enabled(default) = False
  sweep mutated=False alpha_withheld=0.0 would_apply=0

Correction 1 — the "up" channel is off. #1267 quotes
HOOK_RETRIEVAL_VALENCE = 0.1 and the apply_feedback call in
record_retrieval, and both are real. But that call passes
update_posterior=_exposure_updates_posterior(), and the resolver has read
os.environ.get(ENV, "0") == "1" since #1086. The issue notes the gate
parenthetically without its default, which reads as an always-on channel. At
default it writes the audit row and leaves α/β untouched.

Correction 2 — an automatic down-channel exists. #1267 says the negative
path is only aelf feedback <id> harmful plus two MCP sites. It misses
sentiment_feedback.py:315. That lane is wired into UserPromptSubmit at
hook.py:976, fires on every prompt before the turn's retrieval,
regex-matches the user's prose and distributes a negative valence across
the previous turn's pack — valence = magnitude if POSITIVE else -magnitude,
with a correction-frequency escalator at −2.0. That is 10–20× the exposure
magnitude. No human types a command for it to fire.

So the corrected statement is symmetric, not asymmetric: at default
settings no automatic channel moves a posterior in either direction. Both
automatic channels are opt-in and off. The residual gap is much narrower than
#1267 describes — it is a config combination (opt into exposure but not
sentiment ⇒ up-only), not a design asymmetry.

I have not edited #1267's body; the finding is posted there as a comment and
the disposition is the operator's.

The doc defect this exposed

LIMITATIONS.md claimed a mutation path that has not fired since #1162:

The one residual exposure-as-evidence path is the v1.6 (#191)
deferred-feedback sweeper: retrieval still enqueues each surfaced
belief, and the manual aelf sweep-feedback pass applies a small alpha
bump (default +0.05) … (#1091 flagged this sweep for the same
audit-only treatment).

Three stale claims. sweep_deferred_feedback is documented "Writes
nothing (#1162)" and returns mutated=False / alpha_withheld=0.0;
is_enqueue_on_retrieve_enabled() is default False and retrieval.py:4098
honours it; and #1091 is merged, with #1162 having delivered the treatment.
A reader auditing where their posteriors come from was pointed at a path that
no longer exists.

This is squarely #1267's third acceptance criterion — "the docs stop
describing posterior movement as evidence of correctness while the only
automatic input is exposure." The rest of that bullet was already accurate on
exposure; only the sweeper clause was stale.

Why the script ships

Per the standing finding that published numbers must ship the script that
produced them, benchmarks/posterior_channel_audit.py is committed rather
than pasted. It exits non-zero if any channel departs from the documented
posture, so it is a regression guard on the defaults as well as a
measurement — this doc entry cannot go stale silently the way the last one
did. It clears ambient AELFRICE_* before importing aelfrice, because
several of these resolvers read the environment and a developer's own opt-ins
would otherwise change the reported defaults. No live store is read; every
belief is synthetic.

What is deliberately not here

• No change to any default. Nothing is flipped on or off.
• No new mechanism. A belief's posterior is its ingest-time prior for life unless a human types a command — no automatic channel moves it in either direction (carried from #1255) #1267 rules out refutation-by-edit (closed on
  measurement in exp(refutation): run proposal 17's kill experiment — re-derive the refutation-by-edit fire set and measure its precision (#1177) #1255), posterior decay (docs: ARCHITECTURE and PHILOSOPHY assert posterior decay that has no production caller #1218), and auto-demotion on
  contradiction (refactor(feedback): remove unreachable CONTRADICTS-edge auto-demote path (per #605) #814); none of them is proposed.
• No edit to A belief's posterior is its ingest-time prior for life unless a human types a command — no automatic channel moves it in either direction (carried from #1255) #1267's body, and the issue stays open on its decision.

Verification

• benchmarks/posterior_channel_audit.py — exits 0 on this branch.
• Discretion grep on added lines — clean.
• Rebased on github/main, fast-forward; three atomic signed commits.

Pre-PR gate status — read this before re-running it

The gate's rebase, discretion and sibling-PR steps all pass. Its pytest step
passed in full on this exact tree on the first invocation (which then
aborted at step 5 only because the branch was not yet pushed). Re-runs
afterwards failed, and the failures are wall-clock artifacts of this
workstation, not of the diff — which is two docs files plus a benchmarks/
script that no test imports.

Full suite, no -x: 6888 passed, 5 failed, and every failure is a timing
assertion:

test	mode
test_doctor_cli_exit_1_when_broken	Timeout (>5.0s) — passes in isolation
test_commit_limit_capped	Timeout (>5.0s)
test_force_push_after_real_rebase_passes	Timeout (>5.0s)
test_mass_bounded_and_order_invariant_for_any_shape	Timeout (>5.0s)
test_ac11_per_query_overhead_within_budget	assert elapsed < 1.0 → 1.519s

The three subprocess timeouts are the 5s global timeout in pyproject.toml
meeting a saturated box: test_commit_limit_capped does 20 commits ≈ 41 git
spawns, and that work alone — with no aelfrice code in the loop — measured
12.5–14.5 s here at load average 13.75.

test_ac11_per_query_overhead_within_budget is the one that is not a timeout,
so I checked it against the possibility that #1274 (merged into main an hour
ago, and touching retrieval.py) had added per-query overhead. It had not:
order_for_injection / resolve_order_policy are reached only from hook.py
at the render boundary, never from retrieve(). Timed both trees:

tree	100 × retrieve()
pre-#1274 (9258d87f)	1.176 / 1.240 / 1.313 / 1.366 / 1.515 s
this branch	1.270 / 1.342 / 1.373 / 1.396 / 1.664 s

Indistinguishable, and both over the 1.0 s ceiling — the assertion is an
uncalibrated absolute wall-clock budget that this machine no longer meets on
main. It is green on CI (#1276 merged with pytest (3.12) and (3.13)
SUCCESS 40 minutes ago), and CI runs the same unfiltered
pytest tests/ --ignore=tests/e2e, so CI is the authority here — that is
what the required checks on this PR will settle.

[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

[coderabbitai]

Warning

Review limit reached

@robotrocketscience, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 37 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 1acd603e-2417-48a7-a6ea-97643267b7c5

📥 Commits

Reviewing files that changed from the base of the PR and between db99848 and 49423f0.

📒 Files selected for processing (3)

• CHANGELOG/v4.md
• benchmarks/posterior_channel_audit.py
• docs/user/LIMITATIONS.md

---

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.}

[github-actions]

PR-size soft cap

This PR is over the advisory size threshold:

• 249 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.

[sourcery-ai]

Reviewer's Guide

Documents that there is currently no automatic exposure-as-evidence path at defaults, corrects LIMITATIONS and CHANGELOG around feedback channels, and adds a benchmark script that audits which feedback channels move posteriors under default configuration and guards against regressions.

Sequence diagram for posterior_channel_audit benchmark over feedback channels

sequenceDiagram
    participant Script as posterior_channel_audit
    participant Env as os_environ
    participant Store as MemoryStore
    participant Exposure as record_retrieval
    participant Sentiment as apply_sentiment_to_pending
    participant Sweeper as sweep_deferred_feedback

    Script->>Env: clear AELFRICE_* variables

    rect rgb(230,230,250)
        Script->>Store: _seed("b1")
        Script->>Exposure: record_retrieval(Store, [Belief("b1")])
        Exposure-->>Store: write audit row only (default)
        Script->>Store: _ab(Store, "b1")
        Store-->>Script: alpha,beta unchanged
        Script-->>Script: record "automatic UP channel off by default"
    end

    rect rgb(230,255,230)
        Script->>Sentiment: detect_sentiment("no that's wrong")
        Sentiment-->>Script: negative signal (BASE_VALENCE)
        Script->>Store: _seed("b2")
        Script->>Sentiment: apply_sentiment_to_pending(Store, signal, ["b2"])
        Sentiment-->>Store: increase beta (down-channel)
        Script->>Sentiment: apply_sentiment_to_pending(Store, signal, ["b2"], escalated=True)
        Sentiment-->>Store: further increase beta (ESCALATED_NEGATIVE_VALENCE)
        Script-->>Script: record "automatic DOWN channel exists but is opt-in"
    end

    rect rgb(255,240,230)
        Script->>Store: _seed("b3")
        Script->>Sweeper: sweep_deferred_feedback(Store)
        Sweeper-->>Script: mutated=False, alpha_withheld=0.0
        Script->>Store: _ab(Store, "b3")
        Store-->>Script: alpha,beta unchanged
        Script-->>Script: record "no residual exposure-as-evidence path"
    end

    Script-->>Script: aggregate failures and print VERDICT
    Script-->>Script: exit non-zero if any channel moves posterior at defaults

Loading

File-Level Changes

Change	Details	Files
Clarify documentation of feedback channels, exposure, and sentiment so it matches current default behavior and removes the stale exposure-as-evidence path description.	Update LIMITATIONS to state that retrieval exposure is audit-only by default and that the deferred-feedback sweeper is audit-only and default-off on enqueueing Clarify that there is currently no residual exposure-as-evidence path unless explicit opt-ins are configured Document that sentiment-from-prose is an opt-in downwards channel and that user affect is not parsed by default	docs/user/LIMITATIONS.md
Record the documentation fix and add a note about the new audit script in the v4 changelog.	Add a changelog entry explaining that LIMITATIONS previously claimed a residual exposure-as-evidence path that has not existed since [Umbrella] Inert, unreachable, and decorative mechanisms — graph substrate and the delete list #1162 Describe that the new benchmark script drives all apply_feedback routes at defaults and fails if any channel’s behavior departs from the documented posture	CHANGELOG/v4.md
Introduce a standalone benchmark/audit script that programmatically verifies which feedback channels move belief posteriors at default settings and fails if defaults drift.	Clear ambient AELFRICE_* environment variables before importing to ensure defaults are measured, not local overrides Seed a synthetic in-memory store and exercise hook retrieval exposure with and without the exposure gate, checking that at defaults it writes audit rows but does not move alpha/beta and that enabling the env applies +valence Exercise the sentiment-from-prose path to verify it is disabled by default but, when used, applies negative valence with base and escalated magnitudes larger than exposure Exercise the deferred-feedback sweeper to verify enqueue-on-retrieve is default-off and the sweep is audit-only with no posterior mutation Aggregate failures across channels, print a summary verdict, and exit non-zero if any observed behavior contradicts the documented default posture	benchmarks/posterior_channel_audit.py

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[robotrocketscience]

[claim:review:Setr:2026-08-01T03:38:55Z]

[robotrocketscience]

[claim:review:Garsecg:2026-08-01T03:39:05Z]

[robotrocketscience]

[release:review:Garsecg:2026-08-01T03:39:11Z]

[github-actions]

merge-train: merged 49423f0 → main via FF push.

[robotrocketscience]

[claim:review:Gylf:2026-08-01T03:43:45Z]

[robotrocketscience]

[release:review:Gylf:2026-08-01T03:43:51Z]

[robotrocketscience]

Review — the doc fix is right; the guard behind it was not falsifiable

The premise correction and the LIMITATIONS.md edit both hold up. I re-derived
the load-bearing claims independently rather than reading them:

claim	how checked	result
enqueue is default-off	is_enqueue_on_retrieve_enabled() on a cleared env	False
retrieve() honours that gate	retrieval.py:4098	gated, confirmed
sweeper writes nothing	eligible row swept, feedback_history counted	0 rows, α/β unmoved
exposure is default-off	record_retrieval at default vs =1	(1.0,1.0) vs (1.1,1.0)
an automatic down channel exists	detect_sentiment → apply_sentiment_to_pending	β 1.0 → 2.5 → 4.5

So the entry that had to go was genuinely stale, and the replacement text is
accurate. The problem is the thing the PR body and the CHANGELOG both lean on:

…fails non-zero if any default moves, so the entry cannot go stale silently
again.

Two independent reasons that did not hold. Both are now fixed and pushed to
this branch (4b8b3969, 838e2901) — details below so you can back either out
if you disagree.

1. The channel-3 check could not fail — 4b8b3969

channel_3_sweeper seeds a belief and calls sweep_deferred_feedback(store)
on a store with nothing enqueued. sweep_deferred_feedback does all of its
work inside for row_id, belief_id, ... in pending:, and pending is empty, so
the classification loop never runs. The script's own output says so —
would_apply=0 is printed in the PR body as evidence, and it is actually the
tell that nothing was exercised.

Its other assertion is weaker still. result.mutated is a SweepResult field
declared mutated: bool = False at deferred_feedback.py:140 and never
assigned anywhere in src/ — grep -rn "mutated\s*=" src/ | grep -v "mutated: bool"
returns empty. if result.mutated or ... reads a dataclass default.

Demonstrated rather than argued. I restored the pre-#1162 behaviour by putting
the mutation back on the would_apply branch and re-ran the script unchanged:

CHANNEL 3 — deferred-feedback sweeper (#191, audit-only since #1162)
  is_enqueue_on_retrieve_enabled(default) = False
  sweep mutated=False alpha_withheld=0.0 would_apply=0
  a/b (1.0, 1.0) -> (1.0, 1.0)  moved=False
ORIGINAL EXIT=0

A fully reverted, actively mutating sweeper passes the guard.

The fix enqueues one exposure row and backdates it past the grace window so the
row is eligible, then asserts would_apply == 1 alongside the unmoved
posterior. The count is what makes the rest load-bearing: it proves the
eligibility ladder ran and elected to apply — precisely the state the old
sweeper mutated in. It also now asserts no feedback_history row was written
and that alpha_withheld accounts for the withheld epsilon. Against that same
restored mutating branch:

  enqueued 1 row, backdated 1860s (grace=1800s) -> eligible
  sweep would_apply=1 alpha_withheld=0.05 epsilon=0.05
  a/b (1.0, 1.0) -> (1.05, 1.0)  moved=True  feedback_history rows=1
FIXED EXIT=1

and on this branch unmodified it exits 0 with moved=False, rows=0.

Channels 1 and 2 were already falsifiable — channel 1 drives both env states and
compares them, channel 2 asserts a real β move. Only channel 3 needed this.

2. Nothing invokes the script — 838e2901

grep -rn "posterior_channel_audit" .github/ returns nothing. bench-smoke.yml
does carry a benchmarks/** path filter, but its two run steps are
pytest tests/test_bench_smoke.py and pytest tests/test_recalibrate.py — no
workflow executes benchmarks/*.py. A guard that nothing runs cannot keep a doc
entry honest, which is the same shape as #1278.

I wired it into tests/test_benchmarks_dir.py, which the required
pytest (3.12) / (3.13) checks already collect and which already imports from
benchmarks/. Driven as a subprocess, not an import, specifically because the
script deletes every ambient AELFRICE_* variable at module scope — correct for
measuring defaults, but it must not leak into the rest of the session.
@pytest.mark.timeout(120) since the 5s global would be tight for a subprocess
spawn on a loaded box.

I mutation-tested the test itself rather than trusting a green run: with the
mutating sweeper restored it fails with assert 1 == 0 and surfaces both
FAIL: lines; reverted, it passes in 0.80s. Full file: 18 passed.

On the pre-PR gate note

Your reading of test_ac11_per_query_overhead_within_budget matches what I see —
it is an absolute wall-clock assertion, and the two-tree timing you posted rules
out #1274 as the cause. CI is the authority and CI is green. Nothing to do here.

Verdict

Approving on content. The two commits above are additive — no default, no
behaviour and no doc text changed; the diff is one benchmark script and one
test. Holding the merge label until CI reports on the pushed commits.

[robotrocketscience]

Correction to my review above — this PR was already merged when I posted it

My previous comment closed with "approving on content" and "holding the merge
label until CI reports on the pushed commits." Both were wrong, and in a way
worth recording rather than quietly editing.

This PR merged at 03:40:14Z. The queue scan that routed me here ran at
03:38:30Z and listed it as attn:review; I claimed it about a minute later,
by which point the merge-train had already taken it. I did not re-check state
during the review, so I reviewed a merged branch and pushed two commits onto it
after the fact — which is why they triggered no checks and why the PR head still
reads 49423f03.

I have restored this branch to 49423f03, exactly what merged, so it is no
longer carrying commits that are not in main.

The findings themselves stand, and now describe main rather than this
branch. They are re-filed as #1290 against current main:

1. channel_3_sweeper swept an empty deferred-feedback queue, so
   sweep_deferred_feedback never entered its classification loop; and its other
   assertion read result.mutated, a SweepResult field default never assigned
   anywhere in src/. Restoring the pre-[Umbrella] Inert, unreachable, and decorative mechanisms — graph substrate and the delete list #1162 mutating sweeper and re-running
   the script unmodified exits 0 — the guard could not fail.
2. Nothing invokes benchmarks/posterior_channel_audit.py. bench-smoke has a
   benchmarks/** path filter but runs only test_bench_smoke.py and
   test_recalibrate.py, so the CHANGELOG's "cannot go stale silently again"
   did not hold.

Nothing in #1290 changes a default, a behaviour, or any doc text — the premise
work and the LIMITATIONS.md fix in this PR are correct and I verified each
load-bearing claim independently. #1290 only makes the guard behind them
falsifiable and puts it on the required pytest job.

[robotrocketscience]

[release:review:Setr:2026-08-01T04:18:25Z]