cctally 1.65.0 → 1.67.0

package/bin/_cctally_forecast.py

@@ -2,7 +2,7 @@
 
 Holds `cmd_report`, `cmd_forecast`, `cmd_budget`, the forecast core cluster
 (window resolvers, ForecastInputs/ForecastOutput/BudgetRow, _compute_forecast,
-the forecast render helpers, _iso_z), and the 10 budget render/snapshot helpers.
+the forecast render helpers), and the 10 budget render/snapshot helpers.
 
 Honest *name* imports are KERNEL-ONLY (_cctally_core) + stdlib. Every library
 kernel + sibling helper this module needs (build_forecast_view, build_trend_view,
@@ -18,9 +18,10 @@ cluster (get_recent_weeks, _apply_reset_events_to_weekrefs,
 _get_canonical_boundary_for_date) lives in _cctally_weekrefs.py (re-exported on
 the cctally ns); both are reached via c.
 
-_iso_z is defined HERE (intra-module) and re-exported in bin/cctally AFTER the
-dashboard _iso_z binding so cctally._iso_z stays the forecast version
-(the dt-only variant _lib_diff_kernel + _cctally_five_hour depend on).
+_iso_z is honest-imported from the canonical _lib_json_envelope (#279 S6 W4);
+the former intra-module dt-only copy collapsed onto it, and bin/cctally binds
+that single canonical (the old dashboard-then-forecast double-bind is gone).
+_lib_diff_kernel + _cctally_five_hour reach it unchanged via the cctally ns.
 
 Spec: docs/superpowers/specs/2026-05-31-extract-forecast-budget-cmd-design.md
 """
@@ -51,37 +52,55 @@ from _cctally_core import (
     BUDGET_PERIODS as _CCTALLY_BUDGET_PERIODS,
 )
 
+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 —
+    deliberately kept out of ``bin/cctally``'s eager-load block so
+    ``bin/cctally`` stays byte-untouched (spec §2 re-export continuity).
+    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 ForecastInputs, BudgetRow, ForecastOutput, _compute_forecast
+
+# #279 S6 W4: the canonical None-safe UTC-Z serializer. forecast's former local
+# _iso_z (dt-only, no None guard) collapses to this single definition; the union
+# behavior is exactly the canonical (forecast gains a None guard it never
+# exercises). doctor's _iso_z deliberately keeps its own divergent copy.
+_ensure_sibling_loaded("_lib_json_envelope")
+from _lib_json_envelope import _iso_z
+
 
 def _cctally():
     """Resolve the current `cctally` module at call-time (§2)."""
     return sys.modules["cctally"]
 
 
-# === moved verbatim from bin/cctally (class ForecastInputs -> _build_budget_no_budget_snapshot) ===
-@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]
+# ``ForecastInputs`` / ``BudgetRow`` / ``ForecastOutput`` / ``_compute_forecast``
+# now live in ``bin/_lib_forecast.py`` (#279 S4 F2); honest-imported at module
+# top so the ``bin/cctally`` re-exports and this module's own callers resolve
+# them unchanged.
 
 
 def _resolve_forecast_now(as_of: str | None) -> dt.datetime:
@@ -340,40 +359,54 @@ def _select_dollars_per_percent(
     if p_now >= 10.0 and p_now > 0:
         return spent_usd / p_now, "this_week"
 
-    # Path 2: trailing 4-week median.
-    # Fetch all eligible prior weeks then Python-filter (legacy rows may carry
-    # non-UTC offsets that break lexical compare against an ISO-UTC bound).
-    rows = conn.execute(
-        "SELECT week_start_at, week_end_at, MAX(weekly_percent) AS final_pct, "
-        "       MAX(captured_at_utc) AS latest_cap "
+    # Path 2: trailing 4-week median, reset-aware floored (#290).
+    import statistics
+    # Bounded candidate selection: the <=12 most-recent prior weeks. The median
+    # needs 4 eligible; 12 leaves margin so flooring a credited week below 1%
+    # can't starve it, while keeping this hot path (live forecast view +
+    # dashboard refresh) from materializing all history.
+    cand = conn.execute(
+        "SELECT DISTINCT week_start_at, week_end_at, week_start_date "
         "FROM weekly_usage_snapshots "
         "WHERE week_start_at IS NOT NULL AND week_end_at IS NOT NULL "
-        "GROUP BY week_start_at "
-        "HAVING MAX(weekly_percent) >= 1"
+        "  AND datetime(week_start_at) < datetime(?) "
+        "ORDER BY datetime(week_start_at) DESC LIMIT 12",
+        (current_week_start.isoformat(),),
     ).fetchall()
-    by_instant: dict[dt.datetime, dict] = {}
-    for r in rows:
-        try:
-            ws = parse_iso_datetime(r[0], "week_start_at")
-            we = parse_iso_datetime(r[1], "week_end_at")
-        except ValueError:
-            continue
-        slot = by_instant.get(ws)
-        final_pct = float(r[2])
-        if slot is None:
-            by_instant[ws] = {"we": we, "final_pct": final_pct}
-        else:
-            slot["final_pct"] = max(slot["final_pct"], final_pct)
-
+    we_by_ws: dict[dt.datetime, dt.datetime] = {}
+    rows_in: list = []
+    ws_iso_list = [row[0] for row in cand]
+    if ws_iso_list:
+        placeholders = ",".join("?" * len(ws_iso_list))
+        snap = conn.execute(
+            "SELECT week_start_date, week_start_at, week_end_at, "
+            "       captured_at_utc, weekly_percent "
+            "FROM weekly_usage_snapshots "
+            "WHERE week_start_at IN (" + placeholders + ")",
+            ws_iso_list,
+        ).fetchall()
+        for wsd, ws_iso, we_iso, cap_iso, pct in snap:
+            if pct is None:
+                continue
+            try:
+                ws = parse_iso_datetime(ws_iso, "week_start_at")
+                we = parse_iso_datetime(we_iso, "week_end_at")
+            except ValueError:
+                continue
+            we_by_ws.setdefault(ws, we)  # first-wins; all rows share one instant
+            rows_in.append((ws, wsd, ws_iso, we_iso, cap_iso, pct))
+    floored = c._floored_week_max(conn, rows_in)  # {ws_instant -> floored max}
     eligible: list[tuple[dt.datetime, dt.datetime, float]] = [
-        (ws, v["we"], v["final_pct"])
-        for ws, v in by_instant.items()
-        if ws < current_week_start and v["we"] < now_utc and v["final_pct"] >= 1.0
+        (ws, we_by_ws[ws], floored[ws])
+        for ws in floored
+        if ws in we_by_ws
+        and ws < current_week_start
+        and we_by_ws[ws] < now_utc
+        and floored[ws] >= 1.0
     ]
     eligible.sort(key=lambda x: x[0], reverse=True)
     prior = eligible[:4]
     if len(prior) >= 4:
-        import statistics
         values: list[float] = []
         for ws, we, final_pct in prior:
             if use_weekref_cost_cache:
@@ -519,99 +552,7 @@ def _load_forecast_inputs(
     )
 
 
-@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, …)."""
-    c = _cctally()
-    # 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 = c.project_linear(
-            inputs.p_now, inputs.remaining_hours, r_avg, r_avg
-        )
-    else:
-        a, b = c.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,
-    )
+# (moved to bin/_lib_forecast.py, #279 S4 F2 — honest-imported at module top)
 
 
 def _parse_forecast_targets(raw: str) -> list[int]:
@@ -636,10 +577,6 @@ def _parse_forecast_targets(raw: str) -> list[int]:
 TOOL_VERSION = "forecast-v1"  # Bumped on material JSON-schema changes.
 
 
-def _iso_z(d: dt.datetime) -> str:
-    return d.astimezone(dt.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
-
-
 def _build_forecast_json_payload(out: ForecastOutput) -> dict:
     """Dict shape for the forecast JSON endpoint and for the dashboard
     envelope's ``forecast.explain`` subtree (design spec §2.2).
@@ -701,7 +638,11 @@ def _build_forecast_json_payload(out: ForecastOutput) -> dict:
 
 
 def _emit_forecast_json(out: ForecastOutput) -> str:
-    return json.dumps(_build_forecast_json_payload(out), indent=2)
+    # Stamp at the CLI boundary ONLY — never in _build_forecast_json_payload,
+    # which also feeds the dashboard `explain` subtree (spec gate F3).
+    return json.dumps(
+        _cctally().stamp_schema_version(_build_forecast_json_payload(out)),
+        indent=2)
 
 
 def _render_forecast_status_line(out: ForecastOutput, color: bool) -> str:
@@ -1070,7 +1011,9 @@ def cmd_report(args: argparse.Namespace) -> int:
                 c._share_render_and_emit(snap, args)
                 return 0
             if args.json:
-                print(json.dumps({"current": None, "trend": []}, indent=2))
+                print(json.dumps(
+                    c.stamp_schema_version({"current": None, "trend": []}),
+                    indent=2))
             else:
                 print("No data yet. Add record-usage to your status line script (see record-usage --help).")
             return 0
@@ -1192,7 +1135,12 @@ def cmd_report(args: argparse.Namespace) -> int:
             "current": current_row,
             "trend": trend,
             "weekStartRule": week_start_name,
-            "generatedAt": now_utc_iso(),
+            # Honor the CCTALLY_AS_OF testing hook (matches cache-report's
+            # generatedAt, #279 S7 W6) — real behavior is unchanged since
+            # _command_as_of() returns wall-clock when the hook is unset, but the
+            # field becomes deterministic under the hook so report --json is
+            # golden-testable.
+            "generatedAt": now_utc_iso(now_utc=_command_as_of()),
             "currentWeek": {
                 "weekStartDate": current_ref.week_start.isoformat(),
                 "weekEndDate": current_ref.week_end.isoformat() if current_ref.week_end else None,
@@ -1258,7 +1206,7 @@ def cmd_report(args: argparse.Namespace) -> int:
             return 0
 
         if args.json:
-            print(json.dumps(output, indent=2))
+            print(json.dumps(c.stamp_schema_version(output), indent=2))
             return 0
 
         if current_row is not None:
@@ -1373,7 +1321,8 @@ def cmd_forecast(args: argparse.Namespace) -> int:
     if args.json and args.status_line:
         print("forecast: --json and --status-line are mutually exclusive",
               file=sys.stderr)
-        return 1
+        # cctally-native usage error → exit 2 (docs/cli-contract.md; #279 S6 W2).
+        return 2
 
     # Resolve display tz via the unified --tz / config.display.tz pipeline.
     # The renderer reads it back from args._resolved_tz.
@@ -1384,7 +1333,8 @@ def cmd_forecast(args: argparse.Namespace) -> int:
         targets = _parse_forecast_targets(args.targets)
     except ValueError as exc:
         print(f"forecast: {exc}", file=sys.stderr)
-        return 1
+        # cctally-native usage error → exit 2 (docs/cli-contract.md; #279 S6 W2).
+        return 2
 
     now_utc = _resolve_forecast_now(args.as_of)
     conn = open_db()
@@ -1457,10 +1407,10 @@ def cmd_forecast(args: argparse.Namespace) -> int:
             c._share_render_and_emit(snap, args)
             return 0
         if args.json:
-            print(json.dumps({
+            print(json.dumps(c.stamp_schema_version({
                 "error": "no_current_week_data",
                 "meta": {"generated_at": _iso_z(now_utc), "tool_version": TOOL_VERSION},
-            }, indent=2))
+            }), indent=2))
         elif args.status_line:
             pass  # silent segment
         else:
@@ -2168,6 +2118,7 @@ def _cmd_budget_set_project(args: argparse.Namespace) -> int:
     basename = os.path.basename(root) or root
     if getattr(args, "json", False):
         print(json.dumps({
+            "schemaVersion": _BUDGET_JSON_SCHEMA_VERSION,
             "status": "set",
             "project_key": root,
             "budget_usd": amount,
@@ -2227,6 +2178,7 @@ def _cmd_budget_unset_project(args: argparse.Namespace) -> int:
     basename = os.path.basename(root) or root
     if getattr(args, "json", False):
         print(json.dumps({
+            "schemaVersion": _BUDGET_JSON_SCHEMA_VERSION,
             "status": "unset" if removed else "noop",
             "project_key": root,
         }))
@@ -2301,6 +2253,7 @@ def _cmd_budget_set(args: argparse.Namespace, period=None) -> int:
     c._reconcile_budget_on_config_write(validated)
     if getattr(args, "json", False):
         print(json.dumps({
+            "schemaVersion": _BUDGET_JSON_SCHEMA_VERSION,
             "status": "set",
             "weekly_usd": weekly_usd,
             "period": stored_period,
@@ -2339,7 +2292,9 @@ def _cmd_budget_unset(args: argparse.Namespace) -> int:
         c.save_config(config)
 
     if getattr(args, "json", False):
-        print(json.dumps({"status": "unset", "weekly_usd": None}))
+        print(json.dumps({
+            "schemaVersion": _BUDGET_JSON_SCHEMA_VERSION,
+            "status": "unset", "weekly_usd": None}))
         return 0
     print("Weekly budget cleared")
     return 0
@@ -2409,6 +2364,7 @@ def _cmd_budget_set_codex(args: argparse.Namespace, period=None) -> int:
     thresholds = codex["alert_thresholds"]
     if getattr(args, "json", False):
         print(json.dumps({
+            "schemaVersion": _BUDGET_JSON_SCHEMA_VERSION,
             "status": "set",
             "vendor": "codex",
             "amount_usd": amount_usd,
@@ -2449,6 +2405,7 @@ def _cmd_budget_unset_codex(args: argparse.Namespace) -> int:
 
     if getattr(args, "json", False):
         print(json.dumps({
+            "schemaVersion": _BUDGET_JSON_SCHEMA_VERSION,
             "status": "unset" if removed else "noop", "vendor": "codex",
         }))
         return 0