observer: the saturation ceiling is not a rest state (#861)

[InauguralPhysicist]

The bug

A textbook geometric runaway (z is z * z from 2.0) saturates at ±1e308 under the "finite by construction" rule. That turns an unbounded trajectory into a fixed point: the dH window fills with zeros, the relative step goes to exactly 0, and H(1e308) falls under h_low — so every clause of converged is legitimately satisfied, in both channels.

report=converged report_value=converged value=1e+308
  diverging? 0 converged? 1

README.md:158 sells the trajectory words for instability alerts. This is the canonical instability, and the runtime reported maximal stability with rc=0. #422 had recorded this class as caught; that reasoning held only while the value could still grow.

The fix

A slot whose last observed number sits at |value| >= EIGS_NUM_MAX is refused by the rest bands and claimed by diverging, in both channels.

predicate	at the ceiling
converged, equilibrium, stable	forced false
improving	forced false
diverging	forced true, including on a partial window
oscillating	unchanged

Three judgement calls worth reviewing:

1. improving is gated too. H decreases as |x| grows past 1, so a runaway climbing toward the ceiling shows a run of negative dH — and report tries improving before converged. Ungated, the fix would just move the wrong answer one band over. (This mirror of the documented shrinking→diverging case was only half-documented; PREDICATES.md now covers both directions.)
2. diverging fires before the partial-window guard — the evidence is the value's position, not the shape of the flattened window. This is the only predicate that can fire on fewer than 3 samples, and the partial-window rule is amended to say so.
3. A literal ±1e308 that never overflowed reads diverging too. The runtime cannot distinguish it from a saturated value (numbers: saturation breaks associativity by 292 orders of magnitude silently, and makes overflow undetectable in-language #865 item 2). Of the two errors this is the loud one: a diverging solver reporting converged returns 1e308 as an answer.

Arithmetic is unchanged — the Numbers contract is intact — and the entropy constants are untouched. This is a classification gate, the same discipline as #708's opaque band.

Layering: the gate sits with the predicates rather than in vm.c (where #708 must live, since value-is-a-function is only answerable from the binding). So the tape, DAP and step surfaces inherit it for free — verified, not assumed:

$ eigenscript --step sat.tape
z = 1e+308  [diverging]  (21 assigns)

EIGS_NUM_MAX replaces the bare 1e308 literal in num_guard, the JIT bail comparison, and the new gate — three sites that must agree or the observer goes blind to the boundary the arithmetic clamps to.

Validation

New suite section [Observer] observer saturation ceiling (#861) pins the refusal, the negative ceiling, and — the half that matters for regressions — that genuine convergence and a constant one decade below the ceiling (1e307) still certify exactly as before.

Planted fault: with observer_slot_saturated stubbed to return 0 and the binary rebuilt, the new section reproduces the original bug and fails on 9 assertions. Restored, it passes.

gate	result
release suite	3786/3786, 0 failed
ASan+UBSan detect_leaks=1	3784/3784, 0 failed — LeakSanitizer tally at its 0 floor
make jit-smoke	all cases passed
make freestanding-check	both stages OK
doc-example gate	76 passed, 0 failed

Not in scope

• numbers: saturation breaks associativity by 292 orders of magnitude silently, and makes overflow undetectable in-language #865's other two items (saturation breaking associativity by 1e292, log of 0 returning a clamped fudge value) are contract-level changes to the Numbers promise and are left open; only the observer-facing consequence is fixed here.
• observer: entropy is a function of |x| alone with level sets {±x, ±1/x}, so H(x) ≡ H(1/x) — the entropy channel cannot see sign-flip or reciprocal oscillation #862 (H(x) ≡ H(1/x) ≡ H(−x)) is a separate root on the entropy-constant fence. It shows up here as the two channels disagreeing on a pure sign-flip at the ceiling — report says diverging, report_value says oscillating — which PREDICATES.md now notes explicitly.

Closes #861

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Fixes a correctness bug in the observer predicates where numeric overflow saturation at ±1e308 could make an unbounded trajectory appear as a rest state (converged/stable/equilibrium) in both entropy and value channels. The change adds an explicit “saturation ceiling” classification gate (treat ceiling as diverging) and unifies the ceiling constant across the runtime.

Changes:

• Add a saturation-ceiling gate so bindings at |value| >= EIGS_NUM_MAX are never certified as rest/improving and are claimed as diverging (including on partial windows).
• Introduce EIGS_NUM_MAX and use it in num_guard and the JIT’s bailout comparison to keep the saturation boundary consistent.
• Add a new observer regression test section and update SPEC/PREDICATES/COMPARISON docs to describe the saturation rule.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tests/test_observer_saturation.eigs	New regression coverage for saturation-ceiling classification in both channels, including negative ceiling and non-regressions below the ceiling.
tests/run_all_tests.sh	Registers the new observer saturation ceiling test section in the suite.
src/jit.c	Switches JIT bailout threshold from a 1e308 literal to EIGS_NUM_MAX.
src/eigenscript.h	Adds EIGS_NUM_MAX and applies it in num_guard for the saturation clamp.
src/eigenscript.c	Implements observer_slot_saturated() and gates/restores predicate/report behavior at the ceiling.
docs/SPEC.md	Documents that the saturation ceiling is not a rest state and shows an example.
docs/PREDICATES.md	Specifies the saturation rule, including partial-window diverging behavior and channel-disagreement notes.
docs/COMPARISON.md	Notes overflow saturation vs inf and the observer’s ceiling handling when porting numeric code.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.