aether-context 0.3.0__py3-none-any.whl

aether_context/ui.py

@@ -0,0 +1,253 @@
+# aether-context (Unlimited Context)
+# Copyright (c) 2026 Aether AI
+# SPDX-License-Identifier: Apache-2.0
+"""Terminal presentation seam for the ``aether-context`` console script.
+
+Stdlib only — the core dependency contract is numpy and nothing else, so there is no
+``rich``/``colorama`` here. This module owns *how* CLI output looks; the commands in
+:mod:`aether_context.cli` own *what* it says.
+
+Three degradations, all decided once at import of the writer and never at each call site:
+
+``color``
+    ANSI is emitted only when the stream is a real tty and the environment does not veto it
+    (``NO_COLOR`` wins over everything, ``FORCE_COLOR`` turns it back on, ``TERM=dumb``
+    disables). On Windows the VT100 mode is switched on explicitly; if that call fails the
+    styling silently falls back to plain text rather than printing escape soup.
+
+``unicode``
+    Box-drawing and glyphs are only used when the stream's encoding can actually represent
+    them. A ``cp1252`` console (still the Windows default for a redirected pipe) gets the
+    ASCII table instead of a ``UnicodeEncodeError``.
+
+``width``
+    Rules and padding follow ``COLUMNS``/the real terminal size, clamped so output stays
+    readable in a 40-column pane and does not sprawl on an ultrawide one.
+
+Because color is off whenever stdout is not a tty, every command's output is plain text under
+pytest, in a pipe, and in CI — so tests assert on words, never on escape sequences.
+"""
+from __future__ import annotations
+
+import os
+import shutil
+import sys
+from typing import IO, Final
+
+#: Rules and headers never render narrower/wider than this, whatever the terminal reports.
+_MIN_WIDTH: Final = 40
+_MAX_WIDTH: Final = 78
+
+# --- ANSI SGR codes ---------------------------------------------------------------------
+_RESET: Final = "\033[0m"
+_CODES: Final[dict[str, str]] = {
+    "bold": "\033[1m",
+    "dim": "\033[2m",
+    "cyan": "\033[36m",
+    "green": "\033[32m",
+    "yellow": "\033[33m",
+    "red": "\033[31m",
+    "blue": "\033[34m",
+}
+
+#: Status markers. The bracket text is load-bearing: `doctor` has always reported `[ok]` /
+#: `[fail]` / `[skip]`, scripts grep for it, and the suite asserts on it — so color and glyphs
+#: decorate that text, they never replace it.
+_MARKS: Final[dict[str, tuple[str, str, str]]] = {
+    # key: (unicode glyph, ascii glyph, color)
+    "ok": ("✓", "+", "green"),
+    "warn": ("△", "!", "yellow"),
+    "fail": ("✗", "x", "red"),
+    "skip": ("·", "-", "dim"),
+}
+
+
+class Console:
+    """A styled writer bound to one stream, with its capabilities resolved once.
+
+    Construct with the stream you intend to write to (``sys.stdout`` for reports,
+    ``sys.stderr`` for errors) so the capability probe matches the destination: piping stdout
+    to a file must not strip color from an error still going to the terminal.
+    """
+
+    def __init__(self, stream: IO[str] | None = None) -> None:
+        self.stream: IO[str] = stream if stream is not None else sys.stdout
+        self.color: bool = _supports_color(self.stream)
+        self.unicode: bool = _supports_unicode(self.stream)
+        self.width: int = _terminal_width()
+
+    # --- primitives ---------------------------------------------------------------------
+    def style(self, text: str, *names: str) -> str:
+        """Wrap ``text`` in the named SGR styles, or return it unchanged when color is off."""
+        if not self.color or not names:
+            return text
+        codes = "".join(_CODES[n] for n in names if n in _CODES)
+        return f"{codes}{text}{_RESET}" if codes else text
+
+    def line(self, text: str = "") -> None:
+        """Write one line to the bound stream, folded to ASCII when the stream can't encode.
+
+        Every command's output funnels through here, so the fold covers prose too — not just
+        the box-drawing set. Without it a ``cp1252`` pipe turns each em dash in a sentence into
+        a ``?``, which looks like a bug in the tool rather than a limitation of the console.
+        """
+        print(_ascii_fold(text) if not self.unicode else text, file=self.stream)
+
+    def glyph(self, kind: str) -> str:
+        """The bare status glyph for ``kind`` (``ok``/``warn``/``fail``/``skip``)."""
+        uni, ascii_, color = _MARKS[kind]
+        return self.style(uni if self.unicode else ascii_, color)
+
+    # --- composed output ----------------------------------------------------------------
+    def banner(self, title: str, subtitle: str = "") -> None:
+        """The product wordmark: a boxed title with an optional subtitle beneath it."""
+        inner = min(self.width, _MAX_WIDTH) - 2
+        if self.unicode:
+            top, bottom, side = "╭" + "─" * inner + "╮", \
+                "╰" + "─" * inner + "╯", "│"
+        else:
+            top = bottom = "+" + "-" * inner + "+"
+            side = "|"
+        self.line(self.style(top, "cyan"))
+        self.line(
+            self.style(side, "cyan")
+            + self.style(title.center(inner), "bold", "cyan")
+            + self.style(side, "cyan")
+        )
+        if subtitle:
+            self.line(
+                self.style(side, "cyan")
+                + self.style(subtitle.center(inner), "dim")
+                + self.style(side, "cyan")
+            )
+        self.line(self.style(bottom, "cyan"))
+
+    def heading(self, text: str) -> None:
+        """A section header: a blank line, then the title, then a rule the same width."""
+        self.line()
+        self.line(self.style(text, "bold"))
+        char = "─" if self.unicode else "-"
+        self.line(self.style(char * min(len(text), self.width), "dim"))
+
+    def field(self, label: str, value: str, *, pad: int = 12) -> None:
+        """An indented ``label   value`` row, labels left-aligned to a common column."""
+        self.line(f"  {self.style(label.ljust(pad), 'dim')} {value}")
+
+    def check(self, kind: str, text: str, fix: str = "") -> None:
+        """One diagnostic row — ``glyph [kind] text`` — plus an optional indented fix line.
+
+        ``kind`` is one of ``ok``/``warn``/``fail``/``skip`` and is printed literally inside
+        the brackets, which is the contract the doctor's output has always had.
+        """
+        self.line(f"  {self.glyph(kind)} [{kind}] {text}")
+        if fix:
+            self.line(f"        {self.style('fix:', 'dim')} {self.style(fix, 'bold')}")
+
+    def step(self, index: int, total: int, text: str) -> None:
+        """A numbered wizard step header, e.g. ``[1/3] Pool size``."""
+        self.line()
+        self.line(f"{self.style(f'[{index}/{total}]', 'cyan')} {self.style(text, 'bold')}")
+
+    def note(self, text: str) -> None:
+        """A dimmed aside — context the user can skim past."""
+        self.line(self.style(f"  {text}", "dim"))
+
+    def command(self, text: str, comment: str = "") -> None:
+        """A copy-pasteable command line, optionally trailed by a dimmed comment."""
+        tail = f"   {self.style('# ' + comment, 'dim')}" if comment else ""
+        self.line(f"  {self.style(text, 'bold', 'cyan')}{tail}")
+
+    def bar(self, fraction: float, slots: int = 24) -> str:
+        """A fixed-width meter for ``fraction`` in [0, 1], as a string (never printed)."""
+        fraction = max(0.0, min(1.0, fraction))
+        filled = round(fraction * slots)
+        full, empty = ("█", "░") if self.unicode else ("#", ".")
+        return self.style(full * filled, "cyan") + self.style(empty * (slots - filled), "dim")
+
+
+# --- text folding ---------------------------------------------------------------------------
+#: Typographic characters used in CLI prose, mapped to their ASCII equivalents.
+_FOLD: Final[dict[int, str]] = str.maketrans({
+    "—": "-", "–": "-", "≈": "~", "→": "->", "·": "-", "…": "...",
+    "“": '"', "”": '"', "‘": "'", "’": "'", "×": "x",
+})
+
+
+def _ascii_fold(text: str) -> str:
+    """Replace typographic characters with ASCII, dropping anything still unrepresentable.
+
+    The translation table covers what the CLI's own prose uses; the final pass is a backstop
+    for interpolated values (a path, a model name, an exception message) that could carry
+    anything at all.
+    """
+    folded = text.translate(_FOLD)
+    return folded.encode("ascii", "replace").decode("ascii")
+
+
+# --- capability probes ----------------------------------------------------------------------
+def _supports_color(stream: IO[str]) -> bool:
+    """Decide whether to emit ANSI on ``stream``.
+
+    ``NO_COLOR`` (any value, per no-color.org) disables unconditionally; ``FORCE_COLOR``
+    re-enables it even off a tty, which is how CI logs keep their color. Otherwise color needs
+    a real tty, a terminal that is not ``dumb``, and — on Windows — a console that accepts the
+    VT100 mode switch.
+    """
+    if os.environ.get("NO_COLOR") is not None:
+        return False
+    if os.environ.get("FORCE_COLOR"):
+        return True
+    if os.environ.get("TERM") == "dumb":
+        return False
+    try:
+        if not stream.isatty():
+            return False
+    except (AttributeError, ValueError):  # detached/closed stream
+        return False
+    if sys.platform == "win32":
+        return _enable_windows_vt()
+    return True
+
+
+def _enable_windows_vt() -> bool:
+    """Turn on VT100 processing for the Windows console. False if it cannot be enabled.
+
+    Windows Terminal and conhost on Windows 10+ support ANSI once
+    ``ENABLE_VIRTUAL_TERMINAL_PROCESSING`` is set on the output handle. Older consoles reject
+    the flag, and we would rather print clean text than raw escape bytes.
+    """
+    try:
+        import ctypes
+
+        kernel32 = ctypes.windll.kernel32  # type: ignore[attr-defined]
+        handle = kernel32.GetStdHandle(-11)  # STD_OUTPUT_HANDLE
+        mode = ctypes.c_uint32()
+        if not kernel32.GetConsoleMode(handle, ctypes.byref(mode)):
+            return False
+        return bool(kernel32.SetConsoleMode(handle, mode.value | 0x0004))
+    except Exception:  # noqa: BLE001 - any failure here just means "no color"
+        return False
+
+
+def _supports_unicode(stream: IO[str]) -> bool:
+    """True when ``stream``'s encoding can represent the box-drawing/glyph set.
+
+    Probed by actually encoding the widest character we use. A Windows console still running
+    ``cp1252`` fails here and gets the ASCII table, instead of raising ``UnicodeEncodeError``
+    in the middle of a report.
+    """
+    encoding = getattr(stream, "encoding", None) or "ascii"
+    try:
+        "─╭✓█".encode(encoding)
+    except (UnicodeEncodeError, LookupError):
+        return False
+    return True
+
+
+def _terminal_width() -> int:
+    """The usable output width, clamped to a readable range."""
+    try:
+        columns = shutil.get_terminal_size().columns
+    except (OSError, ValueError):
+        columns = _MAX_WIDTH
+    return max(_MIN_WIDTH, min(columns, _MAX_WIDTH))

aether_context/witness.py

@@ -0,0 +1,356 @@
+# aether-context (Unlimited Context)
+# Copyright (c) 2026 Aether AI
+# SPDX-License-Identifier: Apache-2.0
+"""+/- retention witness — page-replacement scoring + budget eviction.
+
+This is the *fidelity field* that decides which encoded slices stay resident in the
+context pool and which fade out. It is a **pure scoring function over access
+events**, with no external tiering or promotion coupling.
+
+Why score on salience, not recency
+-----------------------------------
+The naive cache evicts on recency/frequency (LRU/LFU). For a long coding run that is
+exactly backwards: the load-bearing fact established an hour ago is rare and old, so an
+LRU policy throws it out first. Two rules fix it:
+
+  1. **Score retention on SURPRISE x IMPACT x UNIQUENESS, not frequency.** The geometric
+     mean (see :func:`retention_score`) means one weak driver can't be masked by a strong
+     one — a slice has to be salient on every axis to score high. In coding terms:
+     surprise ~ content density, impact ~ query relevance, uniqueness ~ 1/(1+similar).
+  2. **A salient slice fades by *idle time*, never by raw frequency**, and **re-hardens**
+     the instant it is relevant again.
+
+Temporal lock-in (anti-thrash)
+------------------------------
+A pure score-ranked governor can *thrash*: a slice paged in from disk on this turn, with
+only a floor-level salience, becomes eligible for eviction on the very next turn — so the
+attention loop evicts it, immediately cold-misses it back, and the window flaps. To break
+that loop a freshly touched slice gets a short **temporal lock-in**: for ``pin_periods``
+after its last touch it carries a :data:`DEFAULT_PIN_BONUS` *immunity bonus* on its
+eviction score. The bonus is deliberately small — it lets a just-paged-in slice survive a
+wave of *comparable-salience* churn, but it never lets a low slice outrank a genuinely
+load-bearing one, so salience still wins where it matters. The bonus affects **eviction
+ordering only** — :meth:`rank` / :meth:`score` (used for retrieval) are unchanged.
+
+The lifecycle of a slice id
+---------------------------
+  * :meth:`Witness.touch` — **harden** (or re-harden): register the slice and lift its
+    score toward the access salience. A re-touch never demotes a still-strong slice.
+  * :meth:`Witness.decay` — **fade**: recompute every slice's live score from how long it
+    has been idle. Monotone non-increasing in elapsed time, never negative.
+  * :meth:`Witness.rank` — order ids by current score, highest (most retained) first.
+  * :meth:`Witness.budget_evict` — drop the lowest-score slices first until the pool fits
+    under its byte ceiling, then stop. Returns the evicted ids.
+
+Fail-soft: the witness is an *optimization* over the pool, never a correctness gate. It
+only ever returns ids; the pool is the single source of truth for slice payloads.
+"""
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+
+from aether_context._log import get_logger
+
+_log = get_logger(__name__)
+
+# --- retention math constants -----------------------------------------------
+#: At or above this retention score a slice is considered salient ("hardened"): it is
+#: the last thing the budget governor will evict.
+SALIENT_THRESHOLD: float = 0.60
+#: Exponential fade rate per unit of idle time. Tuned so a unit-salience slice retains
+#: ~37% of its score after ~20 idle units (1 / DEFAULT_DECAY_RATE), i.e. a slow, steady
+#: fade rather than a cliff — old-but-salient slices survive a long run.
+DEFAULT_DECAY_RATE: float = 0.05
+#: How many idle units a slice stays *temporally locked in* (immune-boosted) after a touch.
+#: Short by design: just long enough that a freshly paged-in slice survives the immediate
+#: next eviction pass rather than flapping straight back to disk.
+DEFAULT_PIN_PERIODS: float = 3.0
+#: Eviction-score bonus a locked-in (recently touched) slice carries. Small on purpose: it
+#: lets a fresh slice beat *comparable-salience* churn, but cannot lift a low slice above a
+#: genuinely load-bearing one — salience still wins where it counts.
+DEFAULT_PIN_BONUS: float = 0.25
+
+
+def _clamp_unit(x: float) -> float:
+    """Clamp a float into the closed unit interval ``[0.0, 1.0]``."""
+    return max(0.0, min(1.0, float(x)))
+
+
+def retention_score(surprise: float, impact: float, uniqueness: float) -> float:
+    """Retention in ``[0,1]`` = geometric mean of the three drivers.
+
+    The geometric mean is deliberate: one weak driver can't be masked by a strong one
+    (unlike a sum), so a slice must be salient on every axis to score high. All inputs
+    are clamped to ``[0,1]`` first.
+
+      surprise    content density / novelty of the slice, normalized to [0,1]
+      impact      query relevance / magnitude of the slice, normalized to [0,1]
+      uniqueness  ``1 / (1 + neighbors_in_embedding_space)`` -> rarer = higher
+    """
+    s = _clamp_unit(surprise)
+    i = _clamp_unit(impact)
+    u = _clamp_unit(uniqueness)
+    return (s * i * u) ** (1.0 / 3.0)
+
+
+def squash(x: float, scale: float) -> float:
+    """``tanh`` squash of a raw magnitude to ``[0,1]`` at a given scale.
+
+    Used to normalize an unbounded magnitude (e.g. a raw relevance distance) into a
+    driver for :func:`retention_score`. A non-positive ``scale`` is a safe no-op (0.0).
+    """
+    if scale <= 0:
+        return 0.0
+    return math.tanh(abs(x) / scale)
+
+
+def uniqueness_from_neighbors(neighbor_count: int) -> float:
+    """``1 / (1 + max(0, neighbor_count))`` — rarer slices (fewer neighbors) score higher."""
+    return 1.0 / (1.0 + max(0, neighbor_count))
+
+
+@dataclass
+class _Entry:
+    """Per-slice retention state: a base score anchored at its last touch time.
+
+    The *live* score is ``base * exp(-rate * (now - last_touch))`` — recomputed lazily
+    so a slice that has been idle longer has faded further. Only the base score and the
+    anchor time are stored; the decayed value is always derived.
+    """
+
+    base: float        # score at last_touch (in [0,1])
+    last_touch: float  # the ``now`` at which ``base`` was set
+
+
+class Witness:
+    """The +/- fidelity field over slice ids: harden, fade, re-harden, rank, evict.
+
+    Pure bookkeeping over access events. Holds only ``{slice_id -> _Entry}``; never the
+    slice payloads (those live in the context pool). Stateless with respect to the pool:
+    callers feed it ids + saliences and read back rankings / eviction lists.
+    """
+
+    def __init__(
+        self,
+        decay_rate: float = DEFAULT_DECAY_RATE,
+        *,
+        pin_periods: float = DEFAULT_PIN_PERIODS,
+        pin_bonus: float = DEFAULT_PIN_BONUS,
+    ) -> None:
+        """Create an empty witness.
+
+        ``decay_rate`` (> 0) sets how fast idle slices fade; the default gives a slow,
+        steady fade so old-but-salient slices survive a long run. A non-positive value
+        falls back to :data:`DEFAULT_DECAY_RATE`.
+
+        ``pin_periods`` / ``pin_bonus`` configure the temporal lock-in (anti-thrash): a
+        slice touched within ``pin_periods`` of the eviction ``now`` carries ``pin_bonus``
+        on its eviction score. Pass ``pin_periods <= 0`` (or ``pin_bonus <= 0``) to disable
+        the lock-in entirely — eviction then ranks on pure salience.
+        """
+        self._decay_rate: float = decay_rate if decay_rate > 0 else DEFAULT_DECAY_RATE
+        self._pin_periods: float = max(0.0, float(pin_periods))
+        self._pin_bonus: float = max(0.0, float(pin_bonus))
+        self._entries: dict[str, _Entry] = {}
+        # Permanently retained ids. Distinct from the temporal lock-in above,
+        # which only holds a *recently touched* slice back against comparable
+        # churn and expires. A permanent slice never fades and is never
+        # evicted, at any pressure, until it is explicitly released.
+        self._permanent: set[str] = set()
+
+    # -- harden / re-harden ----------------------------------------------------
+    def touch(self, slice_id: str, salience: float, now: float = 0.0) -> float:
+        """**Harden** (or re-harden) ``slice_id`` toward ``salience`` at time ``now``.
+
+        On first touch the slice is registered with ``salience`` (clamped to ``[0,1]``).
+        On re-touch the new base is ``max(decayed_current_score, salience)`` so a strong
+        re-touch lifts a faded slice back up and a *weak* re-touch never demotes a still-
+        strong slice. The anchor time is reset to ``now`` either way (the slice is fresh).
+
+        Returns the slice's new (base) score.
+        """
+        s = _clamp_unit(salience)
+        existing = self._entries.get(slice_id)
+        if existing is not None:
+            decayed = self._decayed_score(existing, now)
+            s = max(decayed, s)
+        self._entries[slice_id] = _Entry(base=s, last_touch=float(now))
+        return s
+
+    # -- permanence ------------------------------------------------------------
+    def pin(self, slice_id: str) -> None:
+        """Retain ``slice_id`` permanently: never faded, never evicted.
+
+        For the load-bearing content an agent must not lose no matter how long
+        it runs -- its operating doctrine, its skills, its grounding. Those are
+        resident because of *what they are*, not because they happened to
+        embed near the current query, and salience ranking cannot express that:
+        a slice that is never queried decays exactly like one that is
+        irrelevant.
+
+        Pinning an id the witness has not seen is allowed and remembered, so
+        callers may pin before or after the first touch without ordering care.
+        """
+        self._permanent.add(str(slice_id))
+
+    def unpin(self, slice_id: str) -> None:
+        """Release ``slice_id`` back to ordinary fade and eviction."""
+        self._permanent.discard(str(slice_id))
+
+    def is_permanent(self, slice_id: str) -> bool:
+        """True when ``slice_id`` is permanently retained."""
+        return str(slice_id) in self._permanent
+
+    @property
+    def permanent_ids(self) -> frozenset[str]:
+        """The permanently retained ids (a snapshot)."""
+        return frozenset(self._permanent)
+
+    # -- fade ------------------------------------------------------------------
+    def decay(self, now: float) -> None:
+        """**Fade** every slice: collapse each live (decayed) score into its base at ``now``.
+
+        After this call each slice's stored base equals its decayed value as of ``now`` and
+        its anchor is ``now``. The result is monotone non-increasing in elapsed time and
+        never negative. Calling repeatedly with non-decreasing ``now`` keeps fading.
+        """
+        for slice_id, entry in self._entries.items():
+            if slice_id in self._permanent:
+                # Re-anchor without fading: a permanent slice is as fresh at
+                # hour ten as at minute one.
+                self._entries[slice_id] = _Entry(base=entry.base, last_touch=float(now))
+                continue
+            faded = self._decayed_score(entry, now)
+            self._entries[slice_id] = _Entry(base=faded, last_touch=float(now))
+
+    def _decayed_score(self, entry: _Entry, now: float) -> float:
+        """Live score for an entry as of ``now``: ``base * exp(-rate * max(0, elapsed))``."""
+        elapsed = float(now) - entry.last_touch
+        if elapsed <= 0.0:
+            return entry.base  # no negative-time lift; un-aged slices keep their base
+        return entry.base * math.exp(-self._decay_rate * elapsed)
+
+    # -- read ------------------------------------------------------------------
+    def score(self, slice_id: str, now: float | None = None) -> float:
+        """Current retention score of ``slice_id`` (0.0 if unknown).
+
+        If ``now`` is given, returns the decayed-as-of-``now`` score without mutating
+        state; otherwise returns the stored base score (the value as of its last touch
+        or the last :meth:`decay`).
+        """
+        entry = self._entries.get(slice_id)
+        if entry is None:
+            return 0.0
+        if now is None:
+            return entry.base
+        return self._decayed_score(entry, now)
+
+    def ids(self) -> list[str]:
+        """All known slice ids, ordered highest-score first (alias of :meth:`rank`)."""
+        return self.rank()
+
+    def rank(self, now: float | None = None) -> list[str]:
+        """Slice ids ordered by score, **highest (most retained) first**.
+
+        Ties break on insertion order (Python dict order) for determinism. If ``now`` is
+        given, ranks by the decayed-as-of-``now`` score without mutating state.
+        """
+        scored = [(sid, self.score(sid, now=now)) for sid in self._entries]
+        # stable sort by descending score; ties keep dict insertion order
+        scored.sort(key=lambda pair: pair[1], reverse=True)
+        return [sid for sid, _ in scored]
+
+    def forget(self, slice_id: str) -> None:
+        """Drop a slice id from the witness. A no-op if it is unknown (safe to call)."""
+        self._entries.pop(slice_id, None)
+
+    # -- temporal lock-in ------------------------------------------------------
+    def _is_pinned(self, entry: _Entry, now: float | None) -> bool:
+        """Whether ``entry`` is temporally locked in (touched within ``pin_periods`` of ``now``)."""
+        if now is None or self._pin_periods <= 0.0 or self._pin_bonus <= 0.0:
+            return False
+        return (float(now) - entry.last_touch) < self._pin_periods
+
+    def _eviction_score(self, entry: _Entry, now: float | None) -> float:
+        """Eviction-ranking score: base salience plus the lock-in bonus if pinned.
+
+        Distinct from :meth:`score`: this drives **eviction order only** and never affects
+        retrieval ranking. The bonus is *added* (not multiplied) so it lifts a fresh slice
+        above comparable churn without overriding a genuinely load-bearing salience.
+        """
+        if self._is_pinned(entry, now):
+            return entry.base + self._pin_bonus
+        return entry.base
+
+    def eviction_order(self, now: float | None = None) -> list[str]:
+        """Slice ids ordered **most-evictable first** (lowest eviction score first).
+
+        Ranks on :meth:`_eviction_score`, so when ``now`` is given a temporally locked-in
+        slice is held back behind comparable-salience churn (see the module docstring).
+        Ties break on insertion order for determinism. With ``now=None`` (or the lock-in
+        disabled) this is simply ascending salience.
+        """
+        scored = [
+            (sid, self._eviction_score(e, now))
+            for sid, e in self._entries.items()
+            if sid not in self._permanent
+        ]
+        # stable ascending sort; ties keep dict insertion order (most-evictable first)
+        scored.sort(key=lambda pair: pair[1])
+        # Permanent ids rank last unconditionally: they are not candidates at
+        # any score, so no amount of pressure can order them forward.
+        return [sid for sid, _ in scored] + [
+            sid for sid in self._entries if sid in self._permanent
+        ]
+
+    # -- budget eviction -------------------------------------------------------
+    def budget_evict(
+        self, ceiling_bytes: int, bytes_per_slice: int, now: float | None = None
+    ) -> list[str]:
+        """Evict the **most-evictable** slices first until the pool fits under ``ceiling_bytes``.
+
+        Each retained slice costs ``bytes_per_slice``. Slices are dropped in
+        :meth:`eviction_order` (least-retained first, with the temporal lock-in applied
+        when ``now`` is given) and eviction **stops the instant** the remaining count fits,
+        so the pool ends exactly at or below the ceiling. The witness drops the evicted ids
+        from its own bookkeeping.
+
+        Returns the evicted ids in eviction order (most-evictable / lowest score first). A
+        no-op (``[]``) when the pool already fits or ``bytes_per_slice`` is non-positive.
+        """
+        if bytes_per_slice <= 0:
+            return []
+        max_slices = max(0, ceiling_bytes // bytes_per_slice)
+        order = self.eviction_order(now=now)  # most-evictable first
+        if len(order) <= max_slices:
+            return []
+        # drop the most-evictable prefix; keep the `max_slices` most-retained survivors
+        evicted = order[: len(order) - max_slices]
+        # A permanent slice is not evictable at any pressure. Without this the
+        # prefix would reach the permanent tail once the ceiling fell below the
+        # permanent count -- exactly the moment the guarantee matters most, and
+        # the pool would silently drop the agent's doctrine to make room for
+        # whatever it happened to be reading.
+        evicted = [sid for sid in evicted if sid not in self._permanent]
+        if not evicted:
+            return []
+        for sid in evicted:
+            del self._entries[sid]
+        _log.debug(
+            "budget_evict dropped %d slice(s) to fit %d bytes (%d per slice)",
+            len(evicted), ceiling_bytes, bytes_per_slice,
+        )
+        return evicted
+
+
+__all__ = [
+    "Witness",
+    "retention_score",
+    "squash",
+    "uniqueness_from_neighbors",
+    "SALIENT_THRESHOLD",
+    "DEFAULT_DECAY_RATE",
+    "DEFAULT_PIN_PERIODS",
+    "DEFAULT_PIN_BONUS",
+]