doc: windowed predicate semantics spec (#202) - #226
Merged
Conversation
Rewrites docs/PREDICATES.md as the unambiguous target spec the predicate rewrites (#204-#209) implement against. Per #202, each predicate now documents: the windowed formula in pseudocode, a canonical dH-sequence trace with expected truth at each step, the pointwise behavior it replaces, and the partial-window default (count < N -> false, "not enough seen yet"). Direction: all six windowed, restoring the original trajectory semantics. The foundational design (EigenChat docs/api/predicates.md) defines these as trajectory claims — improving = "positive trajectory", diverging = "moving away", with `loop while improving` usage that must be robust to a single noisy tick. The early C runtime simplified five of the six to single-step checks, which flickered under noise (#207) and drove the iLambdaAi observer-scale trap. This spec is the target that undoes that. - Six windowed formulas with derived constants K = N/4 (bounce tolerance) and FLIPS = ceil(N/3) (oscillation threshold). - Implementation-status table: converged shipped (#204); stable/ oscillating/improving/diverging/equilibrium target (#205-#209). The doc stays honest about shipped vs target, and notes report follows the implementations. - Mutual-exclusion section documents both the target (exclusive bands) and a pre-rewrite note that the five pointwise predicates are NOT yet mutually exclusive — cross-referencing tests/test_predicate_matrix.eigs (#200), which pins current behavior and updates as each rewrite lands. Kept the existing uppercase docs/PREDICATES.md (already linked from README) rather than creating a lowercase duplicate. No code change; PREDICATES.md is not in the executable-doc checker (SPEC.md/COMPARISON.md only), so no CI example drift. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Implements #202: the unambiguous spec the predicate rewrites (#204–#209) implement against.
Direction: all six windowed
This resolves the conflict between #202 (windows all six) and the transitional
PREDICATES.md(windowedconverged, others pointwise "by design"). The foundational design — EigenChat'sdocs/api/predicates.md, the pre-C implementation — defines these as trajectory claims:improving= "positive trajectory in semantic spacetime",diverging= "moving away from solution", with canonicalloop while improvingusage that must survive a single noisy tick. The early C runtime simplified five of the six to single-step checks, which flicker under noise (#207) and drove the iLambdaAi observer-scale trap. This spec restores the original windowed intent.What each predicate now documents (per #202)
dH-sequence trace → expected truth at each stepcount < N → false("not enough seen yet")Derived constants:
K = N/4 = 2(bounce tolerance for improving/diverging),FLIPS = ceil(N/3) = 4(oscillation threshold).Honesty about shipped vs target
convergedshipped ([refactor] Rewriteconvergedwith windowed semantics #204);stable/oscillating/improving/diverging/equilibriumare target ([refactor] Rewritestablewith windowed semantics #205–[refactor] Rewriteequilibriumwith windowed near-stationary #209). Until each rewrite lands, the runtime evaluates the documented pointwise body.diverging; quiet-at-high-entropy co-firesstable+equilibrium) — cross-referencingtests/test_predicate_matrix.eigs([test] Pin current predicate behavior + Newton sqrt baseline #200), which pins current behavior and updates as each rewrite lands.Notes
docs/PREDICATES.md(already linked from README) rather than creating a lowercasepredicates.mdduplicate.PREDICATES.mdis not in the executable-doc checker (SPEC.md/COMPARISON.mdonly), so no example-drift CI risk. Converged examples verified against the live runtime.Closes #202.
🤖 Generated with Claude Code