cctally 1.65.0 → 1.66.0

package/bin/_cctally_reporting.py

@@ -701,7 +701,7 @@ def cmd_range_cost(args: argparse.Namespace) -> int:
             ),
             "modelBreakdowns": breakdowns,
         }
-        print(json.dumps(output, indent=2))
+        print(json.dumps(c.stamp_schema_version(output), indent=2))
         return 0
 
     if args.breakdown:

package/bin/_cctally_sync_week.py

@@ -111,7 +111,7 @@ def cmd_sync_week(args: argparse.Namespace) -> int:
         }
 
         if args.json:
-            print(json.dumps(payload, indent=2))
+            print(json.dumps(c.stamp_schema_version(payload), indent=2))
         elif not args.quiet:
             print(
                 f"Synced week {payload['weekStartDate']}..{payload['weekEndDate']} "

package/bin/_cctally_telemetry.py

@@ -47,10 +47,8 @@ def _core():
 
 
 def _truthy_env(name: str) -> bool:
-    """A ``1``/``true``/``yes``/any-non-empty env value is truthy; unset,
-    empty, ``0``, ``false``, ``no`` are falsey."""
-    v = os.environ.get(name)
-    return v is not None and v.strip().lower() not in ("", "0", "false", "no")
+    """Canonical implementation lives in ``_cctally_core`` (#279 S1 F1)."""
+    return _core()._truthy_env(name)
 
 
 def resolve_telemetry_state(config: dict) -> tuple[bool, str]:
@@ -347,7 +345,7 @@ def cmd_telemetry(args) -> int:
         "fields": ["token", "version", "os"],
     }
     if getattr(args, "json", False):
-        print(json.dumps(info))
+        print(json.dumps(c.stamp_schema_version(info)))
         return 0
     print(f"telemetry: {'enabled' if enabled else 'disabled'} ({reason})")
     print(

package/bin/_cctally_tui.py

@@ -228,6 +228,37 @@ from _lib_fmt import stable_sum
 # nothing on the default path.
 import _lib_perf as _perf
 
+import importlib.util as _ilu
+
+
+def _ensure_sibling_loaded(name: str) -> None:
+    """Register a NON-eager-loaded ``_lib_*`` sibling in ``sys.modules``.
+
+    ``_lib_forecast`` (#279 S4 F2) is a NEW consumer-only sibling — kept out
+    of ``bin/cctally``'s eager-load block so ``bin/cctally`` stays
+    byte-untouched (spec §2). Under the ``SourceFileLoader`` harness path
+    (``bin/`` absent from ``sys.path``) a bare ``from _lib_forecast import``
+    would miss, so this pre-registers the sibling ``__file__``-relative when
+    it is not already importable (mirrors ``_cctally_cache._load_lib``). The
+    honest import that follows is a ``sys.modules`` hit in every load context.
+    """
+    if name in sys.modules:
+        return
+    try:
+        __import__(name)  # bin/ on sys.path: prod script / conftest / pytest
+        return
+    except ModuleNotFoundError:
+        pass
+    _p = os.path.join(os.path.dirname(__file__), f"{name}.py")
+    _spec = _ilu.spec_from_file_location(name, _p)
+    _mod = _ilu.module_from_spec(_spec)
+    sys.modules[name] = _mod
+    _spec.loader.exec_module(_mod)
+
+
+_ensure_sibling_loaded("_lib_forecast")
+from _lib_forecast import _compute_forecast, ForecastInputs, ForecastOutput, BudgetRow
+
 
 # === Module-level back-ref shims for helpers that STAY in bin/cctally ======
 # Each shim resolves ``sys.modules['cctally'].X`` at CALL TIME (not bind
@@ -257,10 +288,6 @@ def _apply_midweek_reset_override(*args, **kwargs):
     return sys.modules["cctally"]._apply_midweek_reset_override(*args, **kwargs)
 
 
-def _compute_forecast(*args, **kwargs):
-    return sys.modules["cctally"]._compute_forecast(*args, **kwargs)
-
-
 def _resolve_forecast_now(*args, **kwargs):
     return sys.modules["cctally"]._resolve_forecast_now(*args, **kwargs)
 
@@ -313,20 +340,11 @@ def sync_cache(*args, **kwargs):
     return sys.modules["cctally"].sync_cache(*args, **kwargs)
 
 
-# Forecast dataclass shims — used as bare-name constructors inside
-# ``_tui_build_forecast``. The classes themselves stay in bin/cctally
-# alongside the forecast subcommand (``cmd_forecast``); call-time
-# resolution keeps monkeypatches in sync.
-def ForecastInputs(*args, **kwargs):
-    return sys.modules["cctally"].ForecastInputs(*args, **kwargs)
-
-
-def ForecastOutput(*args, **kwargs):
-    return sys.modules["cctally"].ForecastOutput(*args, **kwargs)
-
-
-def BudgetRow(*args, **kwargs):
-    return sys.modules["cctally"].BudgetRow(*args, **kwargs)
+# ``_compute_forecast`` + the forecast dataclasses (``ForecastInputs`` /
+# ``ForecastOutput`` / ``BudgetRow``) now live in ``bin/_lib_forecast.py``
+# (#279 S4 F2) and are honest-imported at module top — used as bare-name
+# constructors inside ``_tui_build_forecast``. Single class def per name in
+# ``_lib_forecast``; everything imports it, so class identity stays unique.
 
 
 # Dashboard back-refs consumed by the TUI's snapshot builders.
@@ -5280,6 +5298,12 @@ def _make_run_sync_now_locked(*, ref, hub, pinned_now, display_tz_pref_override,
         )
 
     def _locked(skip_sync: bool) -> None:
+        # #279 S5 F6.3 (gate P1-1): arm the snapshot-cache owner-thread tripwire
+        # for whichever thread holds sync_lock for THIS rebuild — the periodic
+        # sync thread, or a /api/sync / /api/settings request thread. Overwrite-
+        # on-call, so ownership transfers to the current rebuilder; the guards in
+        # _lib_snapshot_cache then catch a lock-bypassing foreign-thread mutation.
+        _cctally()._load_sibling("_lib_snapshot_cache").mark_owner_thread()
         try:
             if not skip_sync:
                 # ── Decoupled ingest + build (§2.1) ─────────────────────────

package/bin/_lib_alert_dispatch.py

@@ -18,7 +18,6 @@ Spec: docs/superpowers/specs/2026-06-02-alerts-dispatch-severity-seams-design.md
 """
 from __future__ import annotations
 
-import importlib.util as _ilu
 import pathlib
 import sys
 
@@ -36,6 +35,7 @@ def _load_lib(name: str):
     cached = sys.modules.get(name)
     if cached is not None:
         return cached
+    import importlib.util as _ilu
     p = pathlib.Path(__file__).resolve().parent / f"{name}.py"
     spec = _ilu.spec_from_file_location(name, p)
     mod = _ilu.module_from_spec(spec)

package/bin/_lib_blocks.py

@@ -61,6 +61,11 @@ UsageEntry = _lib_jsonl.UsageEntry
 _lib_pricing = _load_lib("_lib_pricing")
 _calculate_entry_cost = _lib_pricing._calculate_entry_cost
 
+# JSON wire-format kernel — the additive camelCase schemaVersion stamp
+# (#279 S6 W1; convention docs/cli-contract.md).
+_lib_json_envelope = _load_lib("_lib_json_envelope")
+stamp_schema_version = _lib_json_envelope.stamp_schema_version
+
 
 @dataclass
 class Block:
@@ -526,4 +531,4 @@ def _blocks_to_json(
             }
         result.append(obj)
 
-    return json.dumps({"blocks": result}, indent=2)
+    return json.dumps(stamp_schema_version({"blocks": result}), indent=2)

package/bin/_lib_credit.py

@@ -0,0 +1,133 @@
+"""Credit-plan decision kernel for cctally's record-credit path.
+
+Pure-fn layer (no I/O at import time): holds the percent-ingress
+sanitizer and the `record-credit` plan builder — values in, a frozen
+`CreditPlan` (or a `ValueError`) out. Every DB read, file write, and
+`eprint` for the in-place-credit machinery stays in the I/O sibling
+`bin/_cctally_record.py`; this module is imported by that sibling (and
+re-exported on the `cctally` namespace via `bin/cctally`), so the
+existing `ns["_build_credit_plan"]` / `ns["_normalize_percent"]` /
+`cctally.CreditPlan` read paths resolve unchanged.
+
+`_normalize_percent` is the single chokepoint that flushes IEEE 754 ULP
+noise out of ingress percents; `_build_credit_plan` validates the
+record-credit inputs and floors the effective moment to the hour. Both
+are pure and stdlib-only apart from two kernel imports
+(`parse_iso_datetime`, `_canonicalize_optional_iso` from `_cctally_core`)
+and the pure hour-floor from `_lib_blocks` — no cross-sibling I/O and no
+`cctally` back-import.
+
+Spec: docs/superpowers/specs/2026-07-09-279-s4-record-kernelization-design.md
+"""
+from __future__ import annotations
+
+import datetime as dt
+from dataclasses import dataclass
+
+from _cctally_core import parse_iso_datetime, _canonicalize_optional_iso
+from _lib_blocks import _floor_to_hour
+
+
+_PERCENT_NORMALIZE_DECIMALS = 10
+
+
+def _normalize_percent(value: "float | int | None") -> "float | None":
+    """Flush IEEE 754 ULP noise out of an ingress percent value.
+
+    Single chokepoint applied at every site where a raw percent enters
+    cctally's runtime path (OAuth fetch, hook-tick OAuth refresh, and
+    the cmd_record_usage CLI ingress). Downstream consumers — HWM
+    files, ``weekly_usage_snapshots.{weekly,five_hour}_percent`` REAL
+    columns, ``five_hour_blocks.final_five_hour_percent``, milestone
+    crossing values, and the SSE envelope's ``used_percent`` field —
+    all read the cleaned value, so a single round here stops
+    ``5h=7.000000000000001`` style strings from reaching any log or
+    serialized surface.
+
+    ``None`` is the canonical absent-percent sentinel; preserve it
+    unchanged so the optional-5h branches stay simple.
+    """
+    if value is None:
+        return None
+    return round(float(value), _PERCENT_NORMALIZE_DECIMALS)
+
+
+@dataclass(frozen=True)
+class CreditPlan:
+    week_start_date: str
+    week_start_at: str
+    week_end_at: str
+    cur_end_canon: str
+    from_pct: float
+    from_source: str          # "hwm" | "explicit" | "prior_credit"
+    to_pct: float
+    effective_iso: str        # weekly_credit_floors.effective_at_utc (floored to hour)
+    captured_iso: str         # synthetic snapshot captured_at_utc (un-floored), 'Z'
+
+
+def _parse_credit_at(value, now):
+    """Parse --at as an aware UTC datetime; default to `now`. Naive => UTC
+    (mirrors bin/_cctally_five_hour.py:88), NOT parse_iso_datetime (host-local)."""
+    if value is None:
+        return now
+    try:
+        parsed = dt.datetime.fromisoformat(value)
+    except ValueError as e:
+        raise ValueError(f"--at: {e}") from e
+    if parsed.tzinfo is None:
+        parsed = parsed.replace(tzinfo=dt.timezone.utc)
+    return parsed.astimezone(dt.timezone.utc)
+
+
+def _build_credit_plan(*, week_start_date, week_start_at, week_end_at,
+                       from_pct, from_source, to_pct, at_dt, now,
+                       effective_override=None):
+    """Validate inputs and build a CreditPlan. Pure (no DB/file I/O).
+    Raises ValueError(msg) on any violation — caller maps to exit 2.
+
+    `effective_override` (an ISO string) is the completion-path reuse of an
+    EXISTING `weekly_credit_floors.effective_at_utc` (spec §4a): when present,
+    the plan's effective is that value rather than `floor_to_hour(at)`, so a
+    rerun of a half-applied credit at a later wall-clock keeps the original
+    floor moment and never leaks a stale pre-credit replay into the floored
+    MAX. The synthetic snapshot's captured timestamp stays the un-floored
+    `at` either way."""
+    to_pct = _normalize_percent(to_pct)
+    from_pct = _normalize_percent(from_pct)
+    # Defensive None-guard (issue #212 N3). `_normalize_percent` returns None
+    # for a None input. The CLI never reaches here with None (`--to` is
+    # required + type=float; `--from` always resolves to a float or the caller
+    # errors out first), but this is a public pure helper called directly by
+    # tests and any future non-CLI caller — surface a None as a clear ValueError
+    # (caller -> exit 2) instead of a TypeError from the `0.0 <= None` compare
+    # immediately below.
+    if to_pct is None or from_pct is None:
+        raise ValueError("--to/--from must be numeric")
+    if not (0.0 <= to_pct <= 100.0) or not (0.0 <= from_pct <= 100.0):
+        raise ValueError("--to/--from must be in [0, 100]")
+    if to_pct >= from_pct:
+        raise ValueError(f"not a credit: to >= from ({to_pct} >= {from_pct})")
+    ws = parse_iso_datetime(week_start_at, "week_start_at")
+    we = parse_iso_datetime(week_end_at, "week_end_at")
+    if not (ws <= at_dt < we):
+        raise ValueError(f"--at {at_dt.isoformat()} is outside the week window")
+    if at_dt > now:
+        raise ValueError("--at is in the future")
+    if effective_override is not None:
+        effective_iso = parse_iso_datetime(
+            effective_override, "effective_override"
+        ).astimezone(dt.timezone.utc).isoformat(timespec="seconds")
+    else:
+        effective_iso = _floor_to_hour(at_dt).isoformat(timespec="seconds")
+    cur_end_canon = _canonicalize_optional_iso(week_end_at, "record-credit.week_end")
+    return CreditPlan(
+        week_start_date=week_start_date,
+        week_start_at=week_start_at,
+        week_end_at=week_end_at,
+        cur_end_canon=cur_end_canon,
+        from_pct=from_pct,
+        from_source=from_source,
+        to_pct=to_pct,
+        effective_iso=effective_iso,
+        captured_iso=at_dt.isoformat(timespec="seconds").replace("+00:00", "Z"),
+    )

package/bin/_lib_doctor.py

@@ -177,6 +177,23 @@ class DoctorState:
     # valid and default to the enabled (opt-out) posture.
     telemetry_enabled: bool = True
     telemetry_reason: str = "enabled"
+    # #279 S2 (F5a): rolling ingest parse-health records read from
+    # cache_meta keys parse_health_claude / parse_health_codex (JSON
+    # dicts; see _cctally_cache._update_parse_health_meta). None = key
+    # absent (pre-first-sync) or cache unreadable — check degrades OK.
+    parse_health_claude: Optional[dict] = None
+    parse_health_codex: Optional[dict] = None
+    # #279 S2 (F5b): PRAGMA quick_check(1) results, gathered ONLY under
+    # doctor_gather_state(deep=True) (CLI cmd_doctor) — the dashboard
+    # rebuild loop calls the gather every rebuild and quick_check on a
+    # large cache.db costs seconds. "ok" | first error line |
+    # "open failed: ..." | None = not run.
+    stats_db_quick_check: Optional[str] = None
+    cache_db_quick_check: Optional[str] = None
+    # #279 S2 (F5c): non-blocking flock probes on the two sync lock files
+    # (name -> True held / False free / None unreadable). Probe never
+    # creates files (doctor read-only contract). None = probe errored.
+    locks_held: Optional[dict] = None
 
 
 @dataclasses.dataclass(frozen=True)
@@ -1207,6 +1224,122 @@ def _check_telemetry(s: DoctorState) -> CheckResult:
     )
 
 
+_PARSE_HEALTH_RECENCY_DAYS = 7
+
+
+def _check_data_parse_health(s: DoctorState) -> CheckResult:
+    details = {"claude": s.parse_health_claude, "codex": s.parse_health_codex}
+    recent, historical_total = [], 0
+    for label, ph in (("claude", s.parse_health_claude),
+                      ("codex", s.parse_health_codex)):
+        if not isinstance(ph, dict):
+            continue
+        malformed = int(ph.get("lines_malformed", 0) or 0)
+        skipped = int(ph.get("lines_skipped", 0) or 0)
+        historical_total += malformed + skipped
+        last_anomaly = ph.get("last_anomaly_at")
+        if not last_anomaly or (malformed + skipped) == 0:
+            continue
+        try:
+            at = dt.datetime.fromisoformat(
+                str(last_anomaly).replace("Z", "+00:00"))
+            if at.tzinfo is None:
+                at = at.replace(tzinfo=dt.timezone.utc)
+        except ValueError:
+            continue
+        if (s.now_utc - at).total_seconds() <= \
+                _PARSE_HEALTH_RECENCY_DAYS * 86400.0:
+            reasons = ph.get("reasons") \
+                if isinstance(ph.get("reasons"), dict) else {}
+            top = max(reasons.items(), key=lambda kv: kv[1])[0] \
+                if reasons else None
+            recent.append((label, malformed, skipped, top))
+    if recent:
+        parts = []
+        for label, malformed, skipped, top in recent:
+            frag = f"{label}: {malformed} malformed / {skipped} drift-skipped"
+            if top:
+                frag += f" (top reason: {top})"
+            parts.append(frag)
+        return CheckResult(
+            id="data.parse_health", title="Ingest parse health",
+            severity="warn",
+            summary="; ".join(parts)
+                    + f" within {_PARSE_HEALTH_RECENCY_DAYS}d",
+            remediation=(
+                "JSONL lines are failing to parse — a Claude Code / Codex "
+                "update may have changed the session format. Check for a "
+                "cctally update or file an issue; `cctally cache-sync "
+                "--rebuild` re-baselines the counters."),
+            details=details,
+        )
+    if s.parse_health_claude is None and s.parse_health_codex is None:
+        summary = "no parse-health data yet (pre-first-sync)"
+    elif historical_total:
+        summary = (f"no recent anomalies ({historical_total} historical; "
+                   f"see details)")
+    else:
+        summary = "no parse anomalies"
+    return CheckResult(
+        id="data.parse_health", title="Ingest parse health",
+        severity="ok", summary=summary, remediation=None, details=details,
+    )
+
+
+def _check_db_integrity(s: DoctorState) -> CheckResult:
+    details = {"stats_quick_check": s.stats_db_quick_check,
+               "cache_quick_check": s.cache_db_quick_check}
+    if s.stats_db_quick_check is not None and s.stats_db_quick_check != "ok":
+        return CheckResult(
+            id="db.integrity", title="Integrity", severity="fail",
+            summary=f"stats.db quick_check: {s.stats_db_quick_check}",
+            remediation=(
+                "stats.db (the non-re-derivable DB) reports corruption. "
+                "Back up the file FIRST, then try "
+                "`sqlite3 <path> \".recover\"` into a fresh file; "
+                "`cctally db recover` does not repair corruption. Please "
+                "file a bug. Do not delete the file."),
+            details=details,
+        )
+    if s.cache_db_quick_check is not None and s.cache_db_quick_check != "ok":
+        return CheckResult(
+            id="db.integrity", title="Integrity", severity="warn",
+            summary=f"cache.db quick_check: {s.cache_db_quick_check}",
+            remediation=("cache.db is re-derivable — run "
+                         "`cctally cache-sync --rebuild`."),
+            details=details,
+        )
+    if s.stats_db_quick_check is None and s.cache_db_quick_check is None:
+        return CheckResult(
+            id="db.integrity", title="Integrity", severity="ok",
+            summary="not checked (fast gather — run `cctally doctor`)",
+            remediation=None, details=details,
+        )
+    return CheckResult(
+        id="db.integrity", title="Integrity", severity="ok",
+        summary="quick_check ok", remediation=None, details=details,
+    )
+
+
+def _check_db_lock_state(s: DoctorState) -> CheckResult:
+    locks = s.locks_held if isinstance(s.locks_held, dict) else {}
+    held = sorted(k for k, v in locks.items() if v is True)
+    details = {"locks": s.locks_held}
+    if held:
+        return CheckResult(
+            id="db.lock_state", title="Locks", severity="ok",
+            summary=(", ".join(held) + " held — an active sync or "
+                     "dashboard is running; a hold persisting across "
+                     "repeated doctor runs may indicate a wedged process"),
+            remediation=None, details=details,
+        )
+    return CheckResult(
+        id="db.lock_state", title="Locks", severity="ok",
+        summary="free" if locks else "no lock files present",
+        remediation=None, details=details,
+    )
+
+
 # Each entry is (category_id, category_title, ((check_id, evaluator_fn_name), ...)).
 # The dotted check_id is the stable JSON-contract ID (spec §5.2) AND the
 # fingerprint identity-slice key (spec §5.5). When an evaluator raises,
@@ -1232,14 +1365,17 @@ _CATEGORY_DEFINITIONS: tuple[tuple[str, str, tuple[tuple[str, str], ...]], ...]
     ("db", "Database", (
         ("db.stats.file", "_check_db_stats_file"),
         ("db.cache.file", "_check_db_cache_file"),
+        ("db.integrity", "_check_db_integrity"),
         ("db.version_ahead", "_check_db_version_ahead"),
         ("db.migrations.applied", "_check_db_migrations_applied"),
         ("db.migrations.pending", "_check_db_migrations_pending"),
+        ("db.lock_state", "_check_db_lock_state"),
     )),
     ("data", "Data", (
         ("data.latest_snapshot_age", "_check_data_latest_snapshot_age"),
         ("data.cache_sync_state", "_check_data_cache_sync_state"),
         ("data.codex_cache", "_check_data_codex_cache"),
+        ("data.parse_health", "_check_data_parse_health"),
         ("data.forked_buckets", "_check_data_forked_buckets"),
         ("data.post_credit_milestones", "_check_data_post_credit_milestones"),
         ("data.conversation_sessions_rollup",
@@ -1320,7 +1456,20 @@ def run_checks(state: DoctorState) -> DoctorReport:
 
 
 def _iso_z(d: dt.datetime) -> str:
-    """Render a UTC datetime as ISO 8601 with trailing 'Z' (share-v2 convention)."""
+    """Render a UTC datetime as ISO 8601 with trailing 'Z' (share-v2 convention).
+
+    DELIBERATELY DIVERGES from the canonical ``_lib_json_envelope._iso_z``
+    (#279 S6 W4) on two axes and therefore KEEPS this local name (gate F11):
+    (1) a NAIVE datetime is treated as UTC via ``replace(tzinfo=utc)`` — the
+    canonical's ``astimezone(utc)`` would reinterpret it as host-local; and
+    (2) microseconds are preserved via ``isoformat()`` — the canonical floors
+    to whole seconds via ``%S``. Renaming this to the canonical would silently
+    degrade the doctor block for the cross-module consumers that resolve it by
+    name through the sibling loader (``_cctally_tui`` and
+    ``_cctally_dashboard_envelope``'s doctor-envelope builders, whose
+    try/except swallows a rename). Divergence pinned by
+    ``tests/test_lib_doctor.py::test_doctor_iso_z_naive_means_utc_and_keeps_microseconds``.
+    """
     if d.tzinfo is None:
         d = d.replace(tzinfo=dt.timezone.utc)
     s = d.astimezone(dt.timezone.utc).isoformat()

package/bin/_lib_five_hour.py

@@ -23,11 +23,45 @@ Spec: docs/superpowers/specs/2026-05-13-bin-cctally-split-design.md
 from __future__ import annotations
 
 import datetime as dt
+import math
 
 
 _FIVE_HOUR_JITTER_FLOOR_SECONDS = 600  # 10 minutes; tolerance band for resets_at jitter
 
 
+def five_hour_milestone_range(pct: float, max_existing: "int | None") -> range:
+    """Which integer 5h-% thresholds ``maybe_update_five_hour_block`` should
+    attempt to record for ``pct``, given the ACTIVE segment's highest already-
+    recorded threshold ``max_existing`` (#279 S4 F4).
+
+    Mirrors the milestone-detection loop's fencing exactly (glue call site:
+    ``maybe_update_five_hour_block``'s 5h-% milestone loop):
+
+      - ``current_floor = math.floor(pct + 1e-9)`` — the 1e-9 snap flushes the
+        ``0.50 * 100 == 49.99…`` ULP so the N threshold is not missed.
+      - ``current_floor < 1`` → empty range (the ``if current_floor >= 1``
+        glue guard).
+      - ``start_threshold = current_floor`` when ``max_existing is None``
+        (first observation records ONLY the current floor — no synthetic
+        1..floor-1 backfill), else ``int(max_existing) + 1``.
+      - result = ``range(start_threshold, current_floor + 1)`` — empty when
+        ``start_threshold > current_floor`` (already at/above the floor),
+        which the glue reads as ``if milestone_range:``.
+
+    Pure: the MAX(percent_threshold) probe that yields ``max_existing``, the
+    marginal-cost lookup, the per-threshold INSERT, and the alert plumbing all
+    stay in glue. (The weekly ``maybe_record_milestone`` loop shares this
+    fencing formula but keeps its own range in glue — its crossing decision
+    early-returns BEFORE the cost sync when covered, a structure this
+    range-only kernel does not encapsulate; spec §6 defers it.)
+    """
+    current_floor = math.floor(pct + 1e-9)
+    if current_floor < 1:
+        return range(0)
+    start_threshold = current_floor if max_existing is None else int(max_existing) + 1
+    return range(start_threshold, current_floor + 1)
+
+
 def _floor_to_ten_minutes(d: dt.datetime) -> dt.datetime:
     """Floor a datetime to the previous 10-minute boundary.
 

package/bin/_lib_forecast.py

@@ -0,0 +1,144 @@
+"""Forecast decision kernel for cctally.
+
+Pure-fn layer (no I/O at import time): the forecast inputs/output/budget
+dataclasses plus `_compute_forecast` — the projection + budget-headroom
+math. Values in (`ForecastInputs`), a `ForecastOutput` out. No DB reads,
+no config loads, no `_cctally()` accessor: the projection routes through
+`project_linear` (the shared, pure primitive whose real home is
+`_lib_budget`).
+
+Imported by `_cctally_forecast.py` (and `_cctally_tui.py`) and re-exported
+on the `cctally` namespace via `bin/cctally`, so the existing
+`cctally.ForecastInputs` / `mod.ForecastOutput` / `inspect.getsource(
+cctally._compute_forecast)` read paths resolve unchanged (re-export
+continuity, spec §2). Single definition of each dataclass lives here;
+everything else imports it, so class identity stays unique.
+
+Spec: docs/superpowers/specs/2026-07-09-279-s4-record-kernelization-design.md
+"""
+from __future__ import annotations
+
+import datetime as dt
+from dataclasses import dataclass
+
+from _lib_budget import project_linear
+
+
+@dataclass
+class ForecastInputs:
+    now_utc: dt.datetime
+    week_start_at: dt.datetime
+    week_end_at: dt.datetime
+    elapsed_hours: float
+    elapsed_fraction: float
+    remaining_hours: float
+    remaining_days: float
+    # Current state
+    p_now: float
+    five_hour_percent: float | None
+    spent_usd: float
+    snapshot_count: int
+    latest_snapshot_at: dt.datetime
+    # Rate inputs
+    p_24h_ago: float | None
+    t_24h_actual_hours: float | None
+    # $/1% selection
+    dollars_per_percent: float
+    dollars_per_percent_source: str  # "this_week" | "trailing_4wk_median" | "this_week_sparse"
+    # Confidence
+    confidence: str  # "high" | "low"
+    low_confidence_reasons: list[str]
+
+
+@dataclass
+class BudgetRow:
+    target_percent: int
+    pct_headroom: float | None     # None when already past target
+    dollars_per_day: float | None
+    percent_per_day: float | None
+
+
+@dataclass
+class ForecastOutput:
+    inputs: ForecastInputs
+    r_avg: float                   # pct per hour, week-avg
+    r_recent: float | None         # pct per hour, 24h recent; None if no prior sample
+    final_percent_low: float
+    final_percent_high: float
+    week_avg_projection_pct: float  # p_now + r_avg*remaining (smooth estimator)
+    projected_cap: bool
+    already_capped: bool
+    cap_at: dt.datetime | None
+    budgets: list[BudgetRow]
+
+
+def _compute_forecast(inputs: ForecastInputs, targets: list[int]) -> ForecastOutput:
+    """Implements spec §2. targets are sorted desc for stable output (100, 90, …)."""
+    # Rate methods
+    r_avg = inputs.p_now / inputs.elapsed_hours if inputs.elapsed_hours > 0 else 0.0
+    if inputs.p_24h_ago is not None and inputs.t_24h_actual_hours:
+        r_recent: float | None = max(
+            0.0, (inputs.p_now - inputs.p_24h_ago) / inputs.t_24h_actual_hours
+        )
+    else:
+        r_recent = None
+
+    # Projected final % — routed through the shared project_linear primitive
+    # (spec F1). r_recent is None ⇒ collapse to the average projection.
+    if r_recent is None:
+        final_low, final_high = project_linear(
+            inputs.p_now, inputs.remaining_hours, r_avg, r_avg
+        )
+    else:
+        a, b = project_linear(
+            inputs.p_now, inputs.remaining_hours, r_avg, r_recent
+        )
+        final_low, final_high = min(a, b), max(a, b)
+
+    # Smooth week-average projection (additive surface field). Distinct from
+    # the displayed band (which keys off final_high): this is the conservative
+    # week-average value the projected-pace alert axis fires on.
+    # p_now + r_avg*remaining (== project_linear collapsed to the single rate).
+    week_avg_projection_pct = inputs.p_now + r_avg * inputs.remaining_hours
+
+    already_capped = inputs.p_now >= 100.0
+    projected_cap = already_capped or final_high >= 100.0
+
+    cap_at: dt.datetime | None = None
+    if not already_capped and projected_cap:
+        r_pessimistic = max(r_avg, r_recent or 0.0)
+        if r_pessimistic > 0:
+            hours_to_cap = (100.0 - inputs.p_now) / r_pessimistic
+            if hours_to_cap < inputs.remaining_hours:
+                cap_at = inputs.now_utc + dt.timedelta(hours=hours_to_cap)
+
+    # Budgets
+    budgets: list[BudgetRow] = []
+    if not already_capped:
+        for t in sorted(targets, reverse=True):
+            headroom = t - inputs.p_now
+            if headroom <= 0 or inputs.remaining_days <= 0:
+                budgets.append(BudgetRow(target_percent=t, pct_headroom=None,
+                                         dollars_per_day=None, percent_per_day=None))
+                continue
+            dollars_day = (headroom * inputs.dollars_per_percent) / inputs.remaining_days
+            pct_day = headroom / inputs.remaining_days
+            budgets.append(BudgetRow(
+                target_percent=t,
+                pct_headroom=headroom,
+                dollars_per_day=dollars_day,
+                percent_per_day=pct_day,
+            ))
+
+    return ForecastOutput(
+        inputs=inputs,
+        r_avg=r_avg,
+        r_recent=r_recent,
+        final_percent_low=final_low,
+        final_percent_high=final_high,
+        week_avg_projection_pct=week_avg_projection_pct,
+        projected_cap=projected_cap,
+        already_capped=already_capped,
+        cap_at=cap_at,
+        budgets=budgets,
+    )