cctally 1.50.0 → 1.51.0

package/bin/_cctally_record.py

@@ -170,6 +170,7 @@ from _cctally_core import (
     compute_week_bounds,
     parse_date_str,
     _canonicalize_optional_iso,
+    _reset_aware_floor,
     make_week_ref,
     _get_alerts_config,
     _AlertsConfigError,
@@ -2174,6 +2175,78 @@ def _read_reset_zero_marker():
     return (week_start_date, cur_end_canon, baseline_pct, first_zero_iso)
 
 
+@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)
+    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"),
+    )
+
+
 def _fire_in_place_credit(conn, week_start_date, cur_end_canon, weekly_percent,
                           *, observed_pre_credit_pct, effective_dt):
     """Emit/refresh the in-place weekly-credit artifacts (issue #19 + #128).
@@ -2238,6 +2311,422 @@ def _fire_in_place_credit(conn, week_start_date, cur_end_canon, weekly_percent,
         eprint(f"[record-usage] post-credit cleanup failed: {exc}")
 
 
+def _resolve_reset_aware_hwm(conn, week_start_date, week_start_at, week_end_at):
+    """The floored MAX(weekly_percent) the statusline _hwm_clamp computes:
+    MAX over snapshots captured at/after the latest in-week clamp floor. The
+    floor is the latest effective across BOTH `week_reset_events` and
+    `weekly_credit_floors` (`_reset_aware_floor`) so a manual partial credit
+    (record-credit M2, #209) lowers the resolved HWM without re-anchoring the
+    week — used both as the `--from` default and as the assertion source of
+    truth in the record-credit tests."""
+    floor_iso = _reset_aware_floor(conn, week_start_date, week_start_at, week_end_at)
+    if floor_iso is not None:
+        row = conn.execute(
+            "SELECT MAX(weekly_percent) FROM weekly_usage_snapshots "
+            " WHERE week_start_date = ? AND unixepoch(captured_at_utc) >= unixepoch(?)",
+            (week_start_date, floor_iso),
+        ).fetchone()
+    else:
+        row = conn.execute(
+            "SELECT MAX(weekly_percent) FROM weekly_usage_snapshots "
+            " WHERE week_start_date = ?",
+            (week_start_date,),
+        ).fetchone()
+    return None if not row or row[0] is None else float(row[0])
+
+
+def _insert_credit_snapshot(conn, plan, *, five_hour=(None, None, None)):
+    """Insert the post-credit snapshot at plan.to_pct, tagged source='record-credit'."""
+    fhp, fhr, fhk = five_hour
+    # Normalize effective to a +00:00 UTC spelling in the payload (matches the
+    # stored weekly_credit_floors.effective_at_utc on a non-UTC host).
+    effective_utc = parse_iso_datetime(
+        plan.effective_iso, "snapshot.effective"
+    ).astimezone(dt.timezone.utc).isoformat(timespec="seconds")
+    payload = json.dumps(
+        {"kind": "record-credit", "from": plan.from_pct, "to": plan.to_pct,
+         "effective": effective_utc},
+        separators=(",", ":"),
+    )
+    conn.execute(
+        "INSERT INTO weekly_usage_snapshots "
+        "(captured_at_utc, week_start_date, week_end_date, week_start_at, "
+        " week_end_at, weekly_percent, page_url, source, payload_json, "
+        " five_hour_percent, five_hour_resets_at, five_hour_window_key) "
+        "VALUES (?,?,?,?,?,?,?,?,?,?,?,?)",
+        (plan.captured_iso, plan.week_start_date,
+         parse_iso_datetime(plan.week_end_at, "we").date().isoformat(),
+         plan.week_start_at, plan.week_end_at, plan.to_pct, None,
+         "record-credit", payload, fhp, fhr, fhk),
+    )
+    conn.commit()
+    return conn.total_changes
+
+
+def _resolve_prior_5h(conn, at_dt):
+    """Return the most-recent snapshot's (five_hour_percent, five_hour_resets_at,
+    five_hour_window_key) iff that 5h window is still active (resets_at > at_dt),
+    else (None, None, None) — so the synthetic row doesn't blank the live 5h
+    display, and never inflates the 5h HWM (copies an already-<=MAX value)."""
+    row = conn.execute(
+        "SELECT five_hour_percent, five_hour_resets_at, five_hour_window_key "
+        "FROM weekly_usage_snapshots "
+        "WHERE five_hour_resets_at IS NOT NULL AND five_hour_window_key IS NOT NULL "
+        "ORDER BY unixepoch(captured_at_utc) DESC, id DESC LIMIT 1").fetchone()
+    if row is None:
+        return (None, None, None)
+    try:
+        if parse_iso_datetime(row[1], "prior.5h_resets") > at_dt:
+            return (row[0], row[1], int(row[2]))
+    except ValueError:
+        pass
+    return (None, None, None)
+
+
+def _apply_credit(conn, plan, *, five_hour=(None, None, None)):
+    """Apply the M2 same-window partial-credit artifacts (record-credit, #209,
+    spec §4). Unlike the >=25pp auto-credit path (`_fire_in_place_credit`), this
+    writes NO `week_reset_events` row — the window-resolution code never sees a
+    credit, so the week is NOT re-anchored. It only lowers the clamp floor.
+
+    Side-effect ordering mirrors `_fire_in_place_credit`'s discipline: the
+    INSERT OR IGNORE of the floor row is dedup-gated by UNIQUE(week_start_date,
+    effective_at_utc), but the hwm force-write, stale-replay DELETE, and
+    synthetic-snapshot INSERT run UNCONDITIONALLY so a rerun finishes a crash-
+    half-applied credit (memory: project_dedup_must_not_gate_side_effects). All
+    are individually idempotent (file overwrite; DELETE on a stable predicate;
+    the synthetic snapshot is re-INSERTed only after `_force_clear_credit` or on
+    the completion path where none exists yet).
+
+    `plan.effective_iso` is `floor_to_hour(at)`. parse_iso_datetime returns a
+    host-local-offset aware datetime; convert to UTC so `effective_at_utc`
+    persists with a +00:00 spelling, not a host offset, in the `*_utc` column.
+    On the completion / --force re-apply path the CALLER passes a `plan` whose
+    `effective_iso` is the EXISTING floor row's `effective_at_utc` (NOT a fresh
+    floor_to_hour(now)) — spec §4a completion-effective reuse."""
+    c = _cctally()
+    effective_dt = parse_iso_datetime(plan.effective_iso, "effective").astimezone(dt.timezone.utc)
+    effective_iso = effective_dt.isoformat(timespec="seconds")
+    pre_credit = float(plan.from_pct)
+
+    # 4a. INSERT the credit floor (no week_reset_events row — the whole point).
+    conn.execute(
+        "INSERT OR IGNORE INTO weekly_credit_floors "
+        "(week_start_date, effective_at_utc, observed_pre_credit_pct, applied_at_utc) "
+        "VALUES (?, ?, ?, ?)",
+        (plan.week_start_date, effective_iso, pre_credit, now_utc_iso()),
+    )
+    conn.commit()
+
+    # 4b. Force-write hwm-7d so the external statusline render reflects the
+    # post-credit value (the normal write-site monotonic guard would refuse to
+    # decrease the file).
+    try:
+        (_cctally_core.APP_DIR / "hwm-7d").write_text(
+            f"{plan.week_start_date} {plan.to_pct}\n"
+        )
+    except OSError:
+        pass
+
+    # 4c. Stale-replay DELETE: drop pre-credit-valued replays that land at/after
+    # the floor (the gotcha_statusline_replay_race_after_credit defense; same
+    # 1.0pp band as the auto path). unixepoch() on both sides for offset safety.
+    try:
+        conn.execute(
+            "DELETE FROM weekly_usage_snapshots "
+            "WHERE week_start_date = ? "
+            "  AND unixepoch(captured_at_utc) >= unixepoch(?) "
+            "  AND ABS(weekly_percent - ?) < 1.0",
+            (plan.week_start_date, effective_iso, pre_credit),
+        )
+        conn.commit()
+    except sqlite3.DatabaseError as exc:
+        eprint(f"[record-credit] post-credit cleanup failed: {exc}")
+
+    # 4d. INSERT the synthetic post-credit snapshot at plan.to_pct.
+    c._insert_credit_snapshot(conn, plan, five_hour=five_hour)
+
+    # 4e. Clear a stale same-week reset-zero marker so the next record-usage
+    # tick can't confirm a phantom reset-to-zero off it.
+    _clear_reset_zero_marker()
+
+
+def _force_clear_credit(conn, week_start_date):
+    """--force scope (M2, spec §4): delete ONLY this week's command-owned
+    synthetic snapshots (`source='record-credit'`) + its `weekly_credit_floors`
+    row(s). Never touches real status-line snapshots, and never
+    `week_reset_events` / `percent_milestones` — a partial credit writes
+    neither (no event row -> no segmentation; no milestones)."""
+    conn.execute("DELETE FROM weekly_usage_snapshots "
+                 " WHERE week_start_date=? AND source='record-credit'", (week_start_date,))
+    conn.execute("DELETE FROM weekly_credit_floors "
+                 " WHERE week_start_date=?", (week_start_date,))
+    conn.commit()
+
+
+def _count_stale_replays(conn, plan):
+    """Count the pre-credit replay rows the _apply_credit stale-replay DELETE
+    (step 4c, inline) will touch (captured at/after the credit moment within a
+    1.0pp band of from), for the preview / --json `staleReplaysDeleted` field.
+    Read-only."""
+    row = conn.execute(
+        "SELECT COUNT(*) FROM weekly_usage_snapshots "
+        " WHERE week_start_date = ? "
+        "   AND unixepoch(captured_at_utc) >= unixepoch(?) "
+        "   AND ABS(weekly_percent - ?) < 1.0",
+        (plan.week_start_date, plan.effective_iso, float(plan.from_pct)),
+    ).fetchone()
+    return int(row[0]) if row and row[0] is not None else 0
+
+
+def _credit_preview_text(plan, *, stale_replays, dry_run):
+    """Human preview (spec §5). Shown before the confirm prompt and as the
+    whole body under --dry-run."""
+    eff_dt = parse_iso_datetime(plan.effective_iso, "effective").astimezone(dt.timezone.utc)
+    cap_dt = parse_iso_datetime(plan.captured_iso, "captured").astimezone(dt.timezone.utc)
+    we_dt = parse_iso_datetime(plan.week_end_at, "week_end").astimezone(dt.timezone.utc)
+    src = {
+        "hwm": "current HWM",
+        "explicit": "explicit",
+        "prior_credit": "prior credit",
+    }.get(plan.from_source, plan.from_source)
+    lines = [
+        "record-credit — weekly in-place credit",
+        f"  week:          {plan.week_start_date} -> "
+        f"{we_dt.strftime('%Y-%m-%d %H:%M')} UTC",
+        f"  from -> to:    {plan.from_pct:g}% -> {plan.to_pct:g}%   (from: {src})",
+        f"  effective:     {eff_dt.strftime('%Y-%m-%d %H:%M')} UTC  "
+        f"(floored from {cap_dt.strftime('%Y-%m-%d %H:%M')})",
+        "  writes:",
+        f"    + weekly_credit_floors  (effective={plan.effective_iso}, "
+        f"pre_credit={plan.from_pct:g})",
+        f"    ~ hwm-7d                {plan.from_pct:g} -> {plan.to_pct:g}",
+        f"    - stale replays         {stale_replays} rows",
+        f"    + snapshot              captured={plan.captured_iso}, "
+        f"weekly_percent={plan.to_pct:g}",
+        "  note: same week — no window re-anchor (no week_reset_events row)",
+    ]
+    if dry_run:
+        lines.append("  (dry-run — nothing written)")
+    return "\n".join(lines)
+
+
+def _credit_json(plan, *, applied, dry_run, forced, stale_replays, hwm_before):
+    """The --json envelope (schemaVersion 1, spec §5); all datetimes …Z."""
+    def _z(iso):
+        return parse_iso_datetime(iso, "z").astimezone(
+            dt.timezone.utc).isoformat(timespec="seconds").replace("+00:00", "Z")
+    return {
+        "schemaVersion": 1,
+        "applied": applied,
+        "dryRun": dry_run,
+        "forced": forced,
+        "week": {
+            "weekStartDate": plan.week_start_date,
+            "weekStartAt": _z(plan.week_start_at),
+            "weekEndAt": _z(plan.week_end_at),
+        },
+        "credit": {
+            "fromPct": plan.from_pct,
+            "toPct": plan.to_pct,
+            "fromSource": plan.from_source,
+            "effectiveAtUtc": _z(plan.effective_iso),
+        },
+        "actions": {
+            "creditFloorInserted": applied,
+            "hwm7dBefore": hwm_before,
+            "hwm7dAfter": plan.to_pct if applied else hwm_before,
+            "staleReplaysDeleted": stale_replays,
+            "postCreditSnapshotInserted": applied,
+        },
+    }
+
+
+def cmd_record_credit(args) -> int:
+    now = _command_as_of()
+    try:
+        at_dt = _parse_credit_at(getattr(args, "at", None), now)
+    except ValueError as e:
+        eprint(f"record-credit: {e}")
+        return 2
+    conn = None
+    try:
+        conn = open_db()
+        # 1. Resolve the week.
+        if getattr(args, "week", None):
+            week_start_date = args.week
+            ws_at, we_at = _get_canonical_boundary_for_date(conn, week_start_date)
+            if not ws_at or not we_at:
+                eprint(f"record-credit: no snapshot for --week {week_start_date}")
+                return 2
+        else:
+            fetched = _fetch_current_week_snapshots(conn, at_dt)
+            if fetched is None:
+                eprint("record-credit: no snapshot week contains --at; pass --week")
+                return 2
+            ws_at, we_at, _samples = fetched
+            ws_at = ws_at if isinstance(ws_at, str) else ws_at.isoformat(timespec="seconds")
+            we_at = we_at if isinstance(we_at, str) else we_at.isoformat(timespec="seconds")
+            week_start_date = parse_iso_datetime(ws_at, "ws_at").date().isoformat()
+
+        # Resolve any existing credit FLOOR for this week up front — needed
+        # both for the --from default fallback (a half-applied credit empties
+        # the post-credit segment, so the reset-aware HWM reads NULL) and the
+        # apply-time completion/refuse/force branch (M2 keys on
+        # weekly_credit_floors, NOT week_reset_events — a partial credit never
+        # writes a reset-event row). Latest floor wins (a --force re-apply at a
+        # new effective leaves the old row only until _force_clear_credit
+        # deletes it; pick the newest defensively).
+        existing = conn.execute(
+            "SELECT id, effective_at_utc, observed_pre_credit_pct "
+            "FROM weekly_credit_floors WHERE week_start_date=? "
+            "ORDER BY unixepoch(effective_at_utc) DESC, id DESC LIMIT 1",
+            (week_start_date,)).fetchone()
+
+        # 2. Resolve --from default.
+        if getattr(args, "from_pct", None) is not None:
+            from_pct, from_source = float(args.from_pct), "explicit"
+        elif existing is not None and existing[2] is not None:
+            # A credit floor already exists for this week (completion or
+            # --force re-record). Its recorded observed_pre_credit_pct is the
+            # AUTHENTIC pre-credit baseline; prefer it over the reset-aware
+            # HWM. The post-credit segment's MAX(weekly_percent) would
+            # otherwise pick up the post-credit value (31) or a later real
+            # status-line reading, mis-deriving the baseline and causing the
+            # stale-replay DELETE to (wrongly) match real history. fromSource
+            # is 'prior_credit' (spec §5).
+            from_pct, from_source = float(existing[2]), "prior_credit"
+        else:
+            hwm = _resolve_reset_aware_hwm(conn, week_start_date, ws_at, we_at)
+            if hwm is None:
+                eprint("record-credit: no usage history for the week; pass --from")
+                return 2
+            from_pct, from_source = hwm, "hwm"
+
+        is_force = getattr(args, "force", False)
+
+        # 2a. Classify the existing-floor state (M2, spec §4/§5). A
+        #     `weekly_credit_floors` row may be:
+        #       - half-applied (floor row present, NO command-owned snapshot
+        #         at/after its effective): a crash between 4a and 4d. A plain
+        #         rerun FINISHES it, reusing the existing effective_at_utc (NOT
+        #         a fresh floor_to_hour(now)) so no stale [old,new) replay leaks
+        #         into the floored MAX (spec §4a completion-effective reuse).
+        #       - fully applied (floor row + command-owned snapshot): refuse by
+        #         default; --force clears + re-records at a fresh effective.
+        is_completion = False
+        if existing is not None and not is_force:
+            owned = conn.execute(
+                "SELECT 1 FROM weekly_usage_snapshots "
+                " WHERE week_start_date=? AND source='record-credit' "
+                "   AND unixepoch(captured_at_utc) >= unixepoch(?) LIMIT 1",
+                (week_start_date, existing[1])).fetchone()
+            is_completion = owned is None
+
+        # The effective the plan should carry: a half-applied completion reuses
+        # the EXISTING floor row's effective; a first credit / --force re-apply
+        # uses floor_to_hour(at) (computed inside _build_credit_plan).
+        reuse_effective = existing[1] if is_completion else None
+
+        # 3. Validate + build plan.
+        try:
+            plan = _build_credit_plan(
+                week_start_date=week_start_date, week_start_at=ws_at,
+                week_end_at=we_at, from_pct=from_pct, from_source=from_source,
+                to_pct=args.to, at_dt=at_dt, now=now,
+                effective_override=reuse_effective,
+            )
+        except ValueError as e:
+            eprint(f"record-credit: {e}")
+            return 2
+
+        # 4. Output + confirm matrix (spec §5).
+        is_json = getattr(args, "json", False)
+        is_dry = getattr(args, "dry_run", False)
+        is_yes = getattr(args, "yes", False)
+        stale_replays = _count_stale_replays(conn, plan)
+        hwm_before = _resolve_reset_aware_hwm(conn, week_start_date, ws_at, we_at)
+        if hwm_before is None:
+            hwm_before = plan.from_pct
+
+        # --dry-run: preview only, write nothing, exit 0 (TTY or not,
+        # with/without --json).
+        if is_dry:
+            if is_json:
+                print(json.dumps(_credit_json(
+                    plan, applied=False, dry_run=True, forced=False,
+                    stale_replays=stale_replays, hwm_before=hwm_before)))
+            else:
+                print(_credit_preview_text(plan, stale_replays=stale_replays,
+                                           dry_run=True))
+            return 0
+
+        # --json (not dry-run) must be paired with --yes; never prompts.
+        if is_json and not is_yes:
+            eprint("record-credit: --json requires --yes or --dry-run")
+            return 2
+
+        # No --yes: prompt (TTY) or refuse (non-TTY).
+        if not is_yes:
+            if not sys.stdin.isatty():
+                eprint("record-credit: stdin not a TTY: pass --yes to apply "
+                       "or --dry-run to preview")
+                return 2
+            print(_credit_preview_text(plan, stale_replays=stale_replays,
+                                       dry_run=False))
+            try:
+                reply = input("Proceed? [y/N] ")
+            except EOFError:
+                reply = ""
+            if reply.strip().lower() not in ("y", "yes"):
+                print("aborted — nothing written")
+                return 0
+
+        # 4a. Existing-floor handling (M2; state classified at step 2a).
+        #     _apply_credit commits the floor row + cleanup BEFORE the synthetic
+        #     snapshot, so a crash in between leaves a half-applied credit
+        #     (floor row, no command-owned snapshot). `existing` /
+        #     `is_completion` were resolved up front (above) keyed on
+        #     week_start_date / weekly_credit_floors.
+        forced = False
+        if existing is not None and not is_force:
+            if not is_completion:
+                # Fully applied -> refuse by default.
+                eprint(f"record-credit: a credit is already recorded for this "
+                       f"week (effective={existing[1]}, pre_credit={existing[2]}); "
+                       f"pass --force to re-record")
+                return 2
+            # else: half-applied -> fall through (completion path; the plan
+            # reuses the existing effective and the apply steps are idempotent).
+        elif existing is not None and is_force:
+            _force_clear_credit(conn, plan.week_start_date)
+            forced = True
+
+        five_hour = _resolve_prior_5h(conn, at_dt)
+        _apply_credit(conn, plan, five_hour=five_hour)
+
+        if is_json:
+            print(json.dumps(_credit_json(
+                plan, applied=True, dry_run=False, forced=forced,
+                stale_replays=stale_replays, hwm_before=hwm_before)))
+        else:
+            print(f"record-credit: applied — week {plan.week_start_date} "
+                  f"{plan.from_pct:g}% -> {plan.to_pct:g}% "
+                  f"(effective {plan.effective_iso})")
+        return 0
+    except sqlite3.DatabaseError as e:
+        # Documented exit 3 (docs/commands/record-credit.md "3 — a database
+        # error"). The inner ValueError->2 / EOFError paths return before
+        # reaching here, so this only catches genuine DB failures from
+        # open_db() through _apply_credit/output. Plain-text on stderr,
+        # matching the record-credit: <msg> convention of the validation paths.
+        eprint(f"record-credit: {e}")
+        return 3
+    finally:
+        if conn is not None:
+            conn.close()
+
+
 def cmd_record_usage(args: argparse.Namespace) -> int:
     """Record usage data from Claude Code status line rate_limits."""
     c = _cctally()
@@ -2758,38 +3247,43 @@ def cmd_record_usage(args: argparse.Namespace) -> int:
             eprint(f"[record-usage] reset-event detection failed: {exc}")
 
         # 7-day usage is monotonically non-decreasing within a billing week
-        # — UNTIL Anthropic issues an in-place weekly credit. When a
-        # week_reset_events row exists for THIS week_end_at, the MAX query
-        # filters to samples captured at-or-after the segment's
-        # effective_reset_at_utc so a fresh post-credit OAuth value (e.g.
-        # 2%) lands instead of being held back by stale pre-credit history
-        # (e.g. 67%). When no event row exists, COALESCE defaults to
-        # epoch-zero so the filter is a no-op and legacy clamp behavior
-        # is preserved byte-identically.
+        # — UNTIL an in-place weekly credit lowers it. There are TWO credit
+        # shapes and BOTH must floor this clamp, or a real post-credit tick
+        # is suppressed and never stored:
+        #   (a) an Anthropic mid-week reset / >=25pp auto-credit writes a
+        #       `week_reset_events` row (it also re-anchors the window); and
+        #   (b) a manual `record-credit` partial credit writes a
+        #       `weekly_credit_floors` row WITHOUT re-anchoring the week
+        #       (record-credit M2, #209).
+        # `_reset_aware_floor` returns the LATEST in-week effective across
+        # both legs. The MAX query then filters to samples captured at-or-
+        # after that floor, so a fresh post-credit OAuth value (e.g. 37%
+        # after a 46->31 credit) lands instead of being held back by stale
+        # pre-credit history (46%). Without the credit-floor leg, the 37%
+        # tick is `round(37,1) < round(46,1)` -> should_insert=False ->
+        # never stored, cascading to every latest-snapshot surface
+        # (the M2 linchpin; spec §4a, test S13).
+        # When neither leg has a row, the floor is None -> '1970-...' epoch-
+        # zero default -> the filter is a no-op and legacy clamp behavior is
+        # preserved byte-identically.
         # NB: comparison wrapped with ``unixepoch()`` on BOTH sides.
-        # ``captured_at_utc`` is stored with `Z` suffix, but
-        # ``effective_reset_at_utc`` may have a non-UTC offset on
-        # historical backfill rows written before Bug 3 was fixed
-        # (parse_iso_datetime returned host-local). Lex string compare
-        # on mixed offsets silently mis-orders moments for non-UTC
-        # hosts (CLAUDE.md gotcha: 5h-block cross-reset flag — "all
-        # comparisons go through unixepoch(), NOT lex
-        # BETWEEN/`<`/`>`"). Same rule applies here.
+        # ``captured_at_utc`` is stored with `Z` suffix, but the floor may
+        # carry a non-UTC / +00:00 offset spelling. Lex string compare on
+        # mixed offsets silently mis-orders moments for non-UTC hosts
+        # (CLAUDE.md gotcha: 5h-block cross-reset flag — "all comparisons go
+        # through unixepoch(), NOT lex BETWEEN/`<`/`>`"). Same rule here, and
+        # inside `_reset_aware_floor`'s own ORDER BY.
+        clamp_floor_iso = _reset_aware_floor(
+            conn, week_start_date, week_start_at, week_end_at,
+        ) or "1970-01-01T00:00:00Z"
         max_row = conn.execute(
             """
             SELECT MAX(weekly_percent) AS v
               FROM weekly_usage_snapshots
              WHERE week_start_date = ?
-               AND unixepoch(captured_at_utc) >= unixepoch(COALESCE(
-                 (SELECT effective_reset_at_utc
-                    FROM week_reset_events
-                   WHERE new_week_end_at = ?
-                   ORDER BY id DESC
-                   LIMIT 1),
-                 '1970-01-01T00:00:00Z'
-               ))
+               AND unixepoch(captured_at_utc) >= unixepoch(?)
             """,
-            (week_start_date, week_end_at),
+            (week_start_date, clamp_floor_iso),
         ).fetchone()
         if max_row and max_row["v"] is not None and round(weekly_percent, 1) < round(float(max_row["v"]), 1):
             should_insert = False

package/bin/_cctally_statusline.py

@@ -500,20 +500,22 @@ def _build_statusline_injections(warn_once):
                     # (_apply_reset_events_to_subweeks: post-reset window
                     # start_ts := effective_reset_at_utc) by flooring the
                     # MAX to snapshots captured at/after the latest reset
-                    # effective WITHIN this window. unixepoch() on both
-                    # sides — reset rows carry mixed offset spellings
-                    # (+00:00 / +03:00) while captured_at_utc uses 'Z', so a
-                    # lexical compare would misorder them (same rule as the
-                    # 5h-block cross-reset flag).
-                    floor_row = conn.execute(
-                        "SELECT MAX(effective_reset_at_utc) "
-                        "FROM week_reset_events "
-                        "WHERE unixepoch(effective_reset_at_utc) >= unixepoch(?) "
-                        "  AND unixepoch(effective_reset_at_utc) <  unixepoch(?)",
-                        (week_start_dt.isoformat(), week_end_dt.isoformat()),
-                    ).fetchone()
-                    floor_iso = (
-                        floor_row[0] if floor_row and floor_row[0] else None
+                    # effective WITHIN this window.
+                    #
+                    # The floor is the LATEST in-week effective across BOTH
+                    # `week_reset_events` (Anthropic resets / >=25pp auto-
+                    # credits) and `weekly_credit_floors` (manual `record-
+                    # credit` partial credits — record-credit M2, #209): a
+                    # partial credit lowers the clamp floor WITHOUT re-
+                    # anchoring the week, so without the credit-floor leg the
+                    # statusline would re-clamp the post-credit 31% back UP to
+                    # the stale pre-credit 46% peak. `_reset_aware_floor`
+                    # unions both legs with `unixepoch()` ordering (mixed
+                    # Z / +00:00 offset spellings; lexical MAX would misorder
+                    # them — same rule as the 5h-block cross-reset flag).
+                    floor_iso = c._reset_aware_floor(
+                        conn, week_start_date,
+                        week_start_dt.isoformat(), week_end_dt.isoformat(),
                     )
                     if floor_iso is not None:
                         row = conn.execute(

package/bin/cctally

@@ -212,6 +212,7 @@ WeekRef = _cctally_core.WeekRef
 _canonicalize_optional_iso = _cctally_core._canonicalize_optional_iso
 make_week_ref = _cctally_core.make_week_ref
 _get_latest_row_for_week = _cctally_core._get_latest_row_for_week
+_reset_aware_floor = _cctally_core._reset_aware_floor
 get_latest_usage_for_week = _cctally_core.get_latest_usage_for_week
 
 # === Path constants — re-exported from _cctally_core ================
@@ -634,6 +635,9 @@ cmd_sync_week = _cctally_sync_week.cmd_sync_week
 # module-private (no external caller).
 _cctally_project = _load_sibling("_cctally_project")
 cmd_project = _cctally_project.cmd_project
+# Re-exported so the record-credit tests can assert `project`'s per-week MAX
+# is reset-aware-floored (S15, #209).
+_load_week_snapshots = _cctally_project._load_week_snapshots
 # Shared per-project cost compute (#19/#121, spec §7.1). Re-exported so the
 # per-project budget display (cmd_budget) and the Task 3 firing path reach it
 # via the cctally namespace.
@@ -840,6 +844,22 @@ _weekly_pct_week_avg_projection = _cctally_record._weekly_pct_week_avg_projectio
 _compute_block_totals = _cctally_record._compute_block_totals
 maybe_update_five_hour_block = _cctally_record.maybe_update_five_hour_block
 cmd_record_usage = _cctally_record.cmd_record_usage
+CreditPlan = _cctally_record.CreditPlan
+_parse_credit_at = _cctally_record._parse_credit_at
+_build_credit_plan = _cctally_record._build_credit_plan
+_resolve_reset_aware_hwm = _cctally_record._resolve_reset_aware_hwm
+_insert_credit_snapshot = _cctally_record._insert_credit_snapshot
+_resolve_prior_5h = _cctally_record._resolve_prior_5h
+_apply_credit = _cctally_record._apply_credit
+_fire_in_place_credit = _cctally_record._fire_in_place_credit
+_force_clear_credit = _cctally_record._force_clear_credit
+_count_stale_replays = _cctally_record._count_stale_replays
+_credit_preview_text = _cctally_record._credit_preview_text
+_credit_json = _cctally_record._credit_json
+_arm_reset_zero_marker = _cctally_record._arm_reset_zero_marker
+_read_reset_zero_marker = _cctally_record._read_reset_zero_marker
+_clear_reset_zero_marker = _cctally_record._clear_reset_zero_marker
+cmd_record_credit = _cctally_record.cmd_record_credit
 _hook_tick_log_line = _cctally_record._hook_tick_log_line
 _hook_tick_log_rotate_if_needed = _cctally_record._hook_tick_log_rotate_if_needed
 _hook_tick_throttle_age_seconds = _cctally_record._hook_tick_throttle_age_seconds