Skip to content

[doc] Spec for windowed predicate semantics #202

Description

@InauguralPhysicist

Context

Six predicate rewrites (converged, stable, improving, diverging, oscillating, equilibrium) need an unambiguous target. Without a shared spec, reviewers will argue six different definitions of "improving" on six different PRs.

Task

Write docs/predicates.md. For each predicate document:

  1. The windowed formula in pseudocode
  2. A canonical pass/fail trace (sequence of dHs → expected truth value at each step)
  3. The pointwise behavior it replaces (for the changelog)
  4. Partial-window behavior (count < N): default false — match consumer intuition ("we haven't seen enough yet to claim anything")

The six

Predicate Formula (window of last N dHs)
converged full window AND all |dH_i| < dh_zero AND entropy < h_low
stable full window AND all |dH_i| < dh_small AND entropy >= h_low AND no consecutive sign flips
improving count ≥ 3 AND entropy_now < entropy_oldest AND bounce_count < K (suggest K = N/4)
diverging mirror of improving (monotone non-decreasing)
oscillating count ≥ 3 AND sign_flip_count ≥ ceil(N/3)
equilibrium full window AND |mean(window)| < dh_zero AND variance(window) < dh_zero²

Acceptance

  • docs/predicates.md exists with the six specs and example traces.
  • Each spec cites the pointwise behavior it replaces.
  • Linked from README.md predicates section.

Why

Predicate rewrite PRs need an unambiguous target. This issue is also a good first contribution — pure spec writing, no C changes.

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Type

    No type

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions