nilometer 0.0.0-stage → 0.1.0

package/core/schema/025_model_fallback.sql

@@ -0,0 +1,77 @@
+-- 025_model_fallback: a request refused by one model and retried by another is its own event (D-080, step G2.8).
+--
+-- Claude Code writes a system line with subtype model_refusal_fallback when a model refuses a
+-- request and another model retries it, naming both models, the requestId, and a refusal
+-- category (observed 2026-10-03). The refused request writes no request line, so no token count
+-- exists for it. Until now the line was ignored_type; it's the only place the refusal is recorded.
+--
+-- parsed_lines and events are rebuilt because SQLite can't change a CHECK constraint in place.
+-- Both are derived: the parser version bump that ships with this migration re-derives them from
+-- raw_lines, so the rows copied here only keep the database consistent until then.
+
+-- Dozens of views read parsed_lines and events by name. A modern ALTER TABLE ... RENAME re-checks
+-- every view, and fails while the old table is dropped and the new one not yet renamed. Legacy
+-- rename leaves views untouched; they resolve to the rebuilt tables by name once this finishes.
+PRAGMA legacy_alter_table = ON;
+
+CREATE TABLE parsed_lines_025 (
+  raw_line_id   INTEGER PRIMARY KEY REFERENCES raw_lines (id), -- derived: the line these fields came from
+  class         TEXT NOT NULL,    -- derived: classification, first matching rule wins
+  session_id    TEXT,             -- source: sessionId ('<missing>' if absent or not a string); NULL when malformed
+  type          TEXT,             -- source: type ('<missing>' if absent or not a string); NULL when malformed
+  subtype       TEXT,             -- source: subtype when it's a string, else NULL
+  timestamp_raw TEXT,             -- source: timestamp as JSON text of its value; NULL when absent or malformed
+  timestamp_utc TEXT,             -- derived: timestamp normalized to UTC with milliseconds; NULL when it doesn't parse
+  cwd           TEXT,             -- source: cwd when it's a string, else NULL
+  git_branch    TEXT,             -- source: gitBranch when it's a string, else NULL
+  cc_version    TEXT,             -- source: version (Claude Code version) when it's a string, else NULL
+  is_sidechain  INTEGER NOT NULL, -- source: isSidechain === true (1) or anything else (0)
+  uuid          TEXT,             -- source: uuid when it's a non-empty string
+  parent_uuid   TEXT,             -- source: parentUuid when it's a non-empty string (D-021)
+  origin_kind   TEXT,             -- source: origin.kind when it's a string (D-022)
+  user_content  TEXT,             -- derived: user lines only; 'tool_result' when message.content holds a tool_result block, else 'prompt'
+  is_meta       INTEGER NOT NULL DEFAULT 0, -- source: isMeta === true (1) or anything else (0)
+  CHECK (class IN ('malformed', 'limit_hit', 'api_error', 'synthetic_other', 'request', 'retry_notice', 'model_fallback', 'ignored_type')),
+  CHECK (is_sidechain IN (0, 1)),
+  CHECK (user_content IN ('tool_result', 'prompt')),
+  CHECK (is_meta IN (0, 1))
+) STRICT;
+INSERT INTO parsed_lines_025 (raw_line_id, class, session_id, type, subtype, timestamp_raw, timestamp_utc, cwd,
+  git_branch, cc_version, is_sidechain, uuid, parent_uuid, origin_kind, user_content, is_meta)
+  SELECT raw_line_id, class, session_id, type, subtype, timestamp_raw, timestamp_utc, cwd,
+    git_branch, cc_version, is_sidechain, uuid, parent_uuid, origin_kind, user_content, is_meta
+  FROM parsed_lines;
+DROP TABLE parsed_lines;
+ALTER TABLE parsed_lines_025 RENAME TO parsed_lines;
+CREATE INDEX parsed_lines_session_uuid ON parsed_lines (session_id, uuid);
+CREATE INDEX parsed_lines_session_time ON parsed_lines (session_id, timestamp_utc);
+CREATE INDEX parsed_lines_request_time ON parsed_lines (timestamp_utc) WHERE class = 'request';
+
+CREATE TABLE events_025 (
+  raw_line_id               INTEGER PRIMARY KEY REFERENCES raw_lines (id), -- derived: the event line
+  class                     TEXT NOT NULL,    -- derived: 'limit_hit', 'api_error', 'synthetic_other', 'retry_notice', or 'model_fallback'
+  error                     TEXT,             -- source: error when it's a string
+  api_error_status          NUMERIC,          -- source: apiErrorStatus, or error.status for retry notices
+  window                    TEXT,             -- derived: 'five_hour' or 'seven_day' parsed from limit-hit text (D-004)
+  reset_text                TEXT,             -- derived: text after 'resets ' in limit-hit text (D-004)
+  unknown_error_key         TEXT,             -- derived: report label for an api_error's unrecognized or missing error
+  retry_rate_limits_present INTEGER NOT NULL, -- derived: 1 when a retry notice's error.rateLimits is present and not null (D-019)
+  reset_at_utc              TEXT,             -- derived: limit hits only; reset_text resolved against the hit's timestamp (D-023)
+  quota_window              TEXT,             -- source: quotaLimits.rateLimitType when it's 'five_hour' or 'seven_day' (limit hits only, D-067)
+  quota_resets_at_utc       TEXT,             -- source: quotaLimits.resetsAt (Unix seconds, whole, 1..253402300799) as ISO-8601 UTC (limit hits only, D-067)
+  fallback_original_model   TEXT,             -- source: originalModel when it's a string (model fallbacks only, D-080)
+  fallback_model            TEXT,             -- source: fallbackModel when it's a string (model fallbacks only, D-080)
+  fallback_request_id       TEXT,             -- source: requestId when it's a string (model fallbacks only, D-080)
+  refusal_category          TEXT,             -- source: apiRefusalCategory when it's a string (model fallbacks only, D-080); stored, never shown
+  CHECK (class IN ('limit_hit', 'api_error', 'synthetic_other', 'retry_notice', 'model_fallback')),
+  CHECK (quota_window IN ('five_hour', 'seven_day'))
+);
+INSERT INTO events_025 (raw_line_id, class, error, api_error_status, window, reset_text, unknown_error_key,
+  retry_rate_limits_present, reset_at_utc, quota_window, quota_resets_at_utc)
+  SELECT raw_line_id, class, error, api_error_status, window, reset_text, unknown_error_key,
+    retry_rate_limits_present, reset_at_utc, quota_window, quota_resets_at_utc
+  FROM events;
+DROP TABLE events;
+ALTER TABLE events_025 RENAME TO events;
+
+PRAGMA legacy_alter_table = OFF;

package/core/schema/026_changed_readings.sql

@@ -0,0 +1,106 @@
+-- 026_changed_readings: a value that changed without a new response is its own observation (D-086, step G3.1).
+--
+-- D-044 dates a reading by its session's last API response, on the premise that an idle session
+-- repeats that response's numbers. Since Claude Code 2.1.281 an idle session sometimes carries the
+-- account's later total instead (found 2026-10-19, weekly pass 3). Those captures were dated back to
+-- the response, and keeping the latest capture per response replaced the response's own value.
+-- Here the captures of one response are split into runs of the same value: the first run is dated
+-- by the response, as before; each later run, by its first capture. Columns are unchanged.
+
+DROP VIEW window_readings;
+
+-- Observed: one row per observation of a plan window. Captures of one API response's numbers are dated by that response's first line (D-044, D-045); a value that changed after it, by its first capture (D-086).
+CREATE VIEW window_readings AS
+WITH readings AS (
+  SELECT
+    w.raw_line_id, w.window, w.resets_at, w.used_percentage, s.session_id, s.captured_at_s,
+    -- The response behind the latest request line in this session, inside this window, at or before
+    -- the capture (+1 s for whole-second captures). An unkeyed line is its own response.
+    (SELECT COALESCE(rq.dedup_key, 'line:' || rq.raw_line_id)
+       FROM parsed_lines p
+       JOIN requests rq ON rq.raw_line_id = p.raw_line_id
+       WHERE p.session_id = s.session_id AND p.class = 'request'
+         AND p.timestamp_utc > strftime('%Y-%m-%dT%H:%M:%fZ',
+               w.resets_at - CASE w.window WHEN 'five_hour' THEN 5 * 3600 ELSE 7 * 86400 END, 'unixepoch')
+         AND p.timestamp_utc < strftime('%Y-%m-%dT%H:%M:%fZ', s.captured_at_s + 1, 'unixepoch')
+       ORDER BY p.timestamp_utc DESC, p.raw_line_id DESC
+       LIMIT 1) AS response_key
+  FROM rate_limit_windows w
+  JOIN status_readings s ON s.raw_line_id = w.raw_line_id
+  WHERE s.status = 'ok' AND w.validity = 'valid' AND w.window IN ('five_hour', 'seven_day')
+),
+dated AS (
+  SELECT
+    r.*,
+    -- The response's first line: when its numbers first existed.
+    (SELECT MIN(p.timestamp_utc)
+       FROM requests rq
+       JOIN parsed_lines p ON p.raw_line_id = rq.raw_line_id
+       WHERE (r.response_key LIKE 'line:%' AND rq.raw_line_id = CAST(substr(r.response_key, 6) AS INTEGER))
+          OR rq.dedup_key = r.response_key) AS response_first_utc,
+    -- The previous capture of the same response, in capture order.
+    LAG(r.used_percentage) OVER captures AS previous_used_percentage
+  FROM readings r
+  -- A capture-time fallback is its own group: NULL response keys must not merge (D-044).
+  WINDOW captures AS (
+    PARTITION BY r.window, r.resets_at, r.session_id, r.response_key,
+                 CASE WHEN r.response_key IS NULL THEN r.raw_line_id END
+    ORDER BY r.captured_at_s, r.raw_line_id
+  )
+),
+runs AS (
+  SELECT
+    d.*,
+    -- A new run starts at the first capture and at every change of more than 0.01 points: payloads
+    -- carry computed values such as 7.000000000000001, which are the same number (D-044, D-086).
+    SUM(CASE WHEN d.previous_used_percentage IS NULL
+               OR abs(d.used_percentage - d.previous_used_percentage) > 0.01 THEN 1 ELSE 0 END)
+      OVER (
+        PARTITION BY d.window, d.resets_at, d.session_id, d.response_key,
+                     CASE WHEN d.response_key IS NULL THEN d.raw_line_id END
+        ORDER BY d.captured_at_s, d.raw_line_id
+        ROWS UNBOUNDED PRECEDING
+      ) AS run
+  FROM dated d
+),
+observed AS (
+  SELECT
+    u.*,
+    -- A later run's value didn't come from the response, so it's dated when it was first seen.
+    CASE
+      WHEN u.response_first_utc IS NULL THEN strftime('%Y-%m-%dT%H:%M:%fZ', u.captured_at_s, 'unixepoch')
+      WHEN u.run = 1 THEN u.response_first_utc
+      ELSE strftime('%Y-%m-%dT%H:%M:%fZ', MIN(u.captured_at_s) OVER run_captures, 'unixepoch')
+    END AS observed_at_utc,
+    ROW_NUMBER() OVER run_captures_latest AS copy_rank
+  FROM runs u
+  WINDOW
+    run_captures AS (
+      PARTITION BY u.window, u.resets_at, u.session_id, u.response_key,
+                   CASE WHEN u.response_key IS NULL THEN u.raw_line_id END, u.run
+    ),
+    run_captures_latest AS (
+      PARTITION BY u.window, u.resets_at, u.session_id, u.response_key,
+                   CASE WHEN u.response_key IS NULL THEN u.raw_line_id END, u.run
+      ORDER BY u.captured_at_s DESC, u.raw_line_id DESC
+    )
+)
+SELECT
+  raw_line_id,
+  window,
+  resets_at,
+  strftime('%Y-%m-%dT%H:%M:%fZ', resets_at, 'unixepoch') AS reset_at_utc,
+  used_percentage,
+  session_id,
+  captured_at_s,
+  strftime('%Y-%m-%dT%H:%M:%fZ', captured_at_s, 'unixepoch') AS captured_at_utc,
+  observed_at_utc,
+  unixepoch(observed_at_utc, 'subsec') AS observed_at_s,
+  CASE
+    WHEN response_key IS NULL THEN 'capture'
+    WHEN run = 1 THEN 'last_request'
+    ELSE 'changed_capture'
+  END AS observed_via,
+  unixepoch(observed_at_utc, 'subsec') > resets_at AS after_reset
+FROM observed
+WHERE copy_rank = 1;

package/core/schema/027_weekly_crossings.sql

@@ -0,0 +1,32 @@
+-- 027_weekly_crossings: when each weekly window was first read at or above 75% and 90% (D-087, step G3.2).
+--
+-- Interruptions count only limits that were hit. Weekly pass 3 found a week that reached 99% with
+-- no hit: a weekly window at 91% with four and a half days left, and the work around it. This view
+-- states the observed part, the first reading at or above each level and the time left before the
+-- reset, without inferring why usage changed afterwards (principle 3).
+
+-- Observed: per weekly window and level (75, 90), the first counted reading at or above it and the seconds from it to the window's reset, from init onward (D-087).
+CREATE VIEW obs_weekly_crossings AS
+WITH levels (threshold) AS (VALUES (75), (90)),
+at_level AS (
+  SELECT
+    l.threshold, r.window, r.resets_at, r.reset_at_utc, r.raw_line_id, r.used_percentage,
+    r.observed_at_utc, r.observed_at_s,
+    ROW_NUMBER() OVER (
+      PARTITION BY l.threshold, r.window, r.resets_at ORDER BY r.observed_at_s, r.raw_line_id
+    ) AS reading_rank
+  FROM window_readings r
+  JOIN levels l ON r.used_percentage >= l.threshold
+  -- Counted readings only: one after its reset belongs to no window (D-024).
+  WHERE r.window = 'seven_day' AND r.after_reset = 0
+)
+SELECT
+  window,
+  reset_at_utc,
+  threshold,
+  observed_at_utc AS first_at_utc,
+  used_percentage,
+  resets_at - observed_at_s AS seconds_before_reset,
+  raw_line_id
+FROM at_level
+WHERE reading_rank = 1;

package/core/schema/028_stale_readings.sql

@@ -0,0 +1,196 @@
+-- 028_stale_readings: a reading below an earlier one in its window is stale, kept and not used (D-089, step G4.1).
+--
+-- Within one window usage only rises, but about 1% of real readings came in lower than an earlier
+-- reading in the same window, in every Claude Code version and model (found in the 2026-10-22
+-- click-through: a 5-hour window locked at 100% from 01:17 showed a "last observed" 73% at 01:59).
+-- Such a reading is marked stale. It stays a row, counted and listed in explain (principle 1), but
+-- isn't the window's last observed value, isn't part of a reading pair, and isn't drawn on the line.
+-- Peaks and crossings are unaffected: a stale reading is below an earlier one by definition.
+
+DROP VIEW window_reading_pairs;
+DROP VIEW obs_window_headroom;
+DROP VIEW window_instances;
+DROP VIEW window_readings;
+
+-- Observed: one row per observation of a plan window, as in 026 (D-044, D-045, D-086), with stale = 1 when a counted reading is more than 1 point below an earlier counted one in its window (D-089).
+CREATE VIEW window_readings AS
+WITH readings AS (
+  SELECT
+    w.raw_line_id, w.window, w.resets_at, w.used_percentage, s.session_id, s.captured_at_s,
+    -- The response behind the latest request line in this session, inside this window, at or before
+    -- the capture (+1 s for whole-second captures). An unkeyed line is its own response.
+    (SELECT COALESCE(rq.dedup_key, 'line:' || rq.raw_line_id)
+       FROM parsed_lines p
+       JOIN requests rq ON rq.raw_line_id = p.raw_line_id
+       WHERE p.session_id = s.session_id AND p.class = 'request'
+         AND p.timestamp_utc > strftime('%Y-%m-%dT%H:%M:%fZ',
+               w.resets_at - CASE w.window WHEN 'five_hour' THEN 5 * 3600 ELSE 7 * 86400 END, 'unixepoch')
+         AND p.timestamp_utc < strftime('%Y-%m-%dT%H:%M:%fZ', s.captured_at_s + 1, 'unixepoch')
+       ORDER BY p.timestamp_utc DESC, p.raw_line_id DESC
+       LIMIT 1) AS response_key
+  FROM rate_limit_windows w
+  JOIN status_readings s ON s.raw_line_id = w.raw_line_id
+  WHERE s.status = 'ok' AND w.validity = 'valid' AND w.window IN ('five_hour', 'seven_day')
+),
+dated AS (
+  SELECT
+    r.*,
+    -- The response's first line: when its numbers first existed.
+    (SELECT MIN(p.timestamp_utc)
+       FROM requests rq
+       JOIN parsed_lines p ON p.raw_line_id = rq.raw_line_id
+       WHERE (r.response_key LIKE 'line:%' AND rq.raw_line_id = CAST(substr(r.response_key, 6) AS INTEGER))
+          OR rq.dedup_key = r.response_key) AS response_first_utc,
+    -- The previous capture of the same response, in capture order.
+    LAG(r.used_percentage) OVER captures AS previous_used_percentage
+  FROM readings r
+  -- A capture-time fallback is its own group: NULL response keys must not merge (D-044).
+  WINDOW captures AS (
+    PARTITION BY r.window, r.resets_at, r.session_id, r.response_key,
+                 CASE WHEN r.response_key IS NULL THEN r.raw_line_id END
+    ORDER BY r.captured_at_s, r.raw_line_id
+  )
+),
+runs AS (
+  SELECT
+    d.*,
+    -- A new run starts at the first capture and at every change of more than 0.01 points: payloads
+    -- carry computed values such as 7.000000000000001, which are the same number (D-044, D-086).
+    SUM(CASE WHEN d.previous_used_percentage IS NULL
+               OR abs(d.used_percentage - d.previous_used_percentage) > 0.01 THEN 1 ELSE 0 END)
+      OVER (
+        PARTITION BY d.window, d.resets_at, d.session_id, d.response_key,
+                     CASE WHEN d.response_key IS NULL THEN d.raw_line_id END
+        ORDER BY d.captured_at_s, d.raw_line_id
+        ROWS UNBOUNDED PRECEDING
+      ) AS run
+  FROM dated d
+),
+observed AS (
+  SELECT
+    u.*,
+    -- A later run's value didn't come from the response, so it's dated when it was first seen.
+    CASE
+      WHEN u.response_first_utc IS NULL THEN strftime('%Y-%m-%dT%H:%M:%fZ', u.captured_at_s, 'unixepoch')
+      WHEN u.run = 1 THEN u.response_first_utc
+      ELSE strftime('%Y-%m-%dT%H:%M:%fZ', MIN(u.captured_at_s) OVER run_captures, 'unixepoch')
+    END AS observed_at_utc,
+    ROW_NUMBER() OVER run_captures_latest AS copy_rank
+  FROM runs u
+  WINDOW
+    run_captures AS (
+      PARTITION BY u.window, u.resets_at, u.session_id, u.response_key,
+                   CASE WHEN u.response_key IS NULL THEN u.raw_line_id END, u.run
+    ),
+    run_captures_latest AS (
+      PARTITION BY u.window, u.resets_at, u.session_id, u.response_key,
+                   CASE WHEN u.response_key IS NULL THEN u.raw_line_id END, u.run
+      ORDER BY u.captured_at_s DESC, u.raw_line_id DESC
+    )
+),
+counted AS (
+  SELECT
+    raw_line_id,
+    window,
+    resets_at,
+    strftime('%Y-%m-%dT%H:%M:%fZ', resets_at, 'unixepoch') AS reset_at_utc,
+    used_percentage,
+    session_id,
+    captured_at_s,
+    strftime('%Y-%m-%dT%H:%M:%fZ', captured_at_s, 'unixepoch') AS captured_at_utc,
+    observed_at_utc,
+    unixepoch(observed_at_utc, 'subsec') AS observed_at_s,
+    CASE
+      WHEN response_key IS NULL THEN 'capture'
+      WHEN run = 1 THEN 'last_request'
+      ELSE 'changed_capture'
+    END AS observed_via,
+    unixepoch(observed_at_utc, 'subsec') > resets_at AS after_reset
+  FROM observed
+  WHERE copy_rank = 1
+)
+SELECT
+  c.*,
+  -- Usage within one window only rises, so a counted reading more than 1 point below an earlier one
+  -- in the same window, from any session, carries a number from before that earlier reading (D-089).
+  CASE
+    WHEN c.after_reset = 0 AND c.used_percentage < MAX(c.used_percentage) OVER (
+      PARTITION BY c.window, c.resets_at ORDER BY c.observed_at_s, c.raw_line_id
+      ROWS BETWEEN UNBOUNDED PRECEDING AND 1 PRECEDING
+    ) - 1 THEN 1
+    ELSE 0
+  END AS stale
+FROM counted c;
+
+-- Observed: per window instance, observation counts (stale ones also on their own), whether it is still open, and the status line coverage.
+CREATE VIEW window_instances AS
+SELECT
+  window,
+  resets_at,
+  reset_at_utc,
+  COUNT(*) FILTER (WHERE after_reset = 0) AS readings,
+  COUNT(*) FILTER (WHERE after_reset = 1) AS readings_after_reset,
+  MIN(observed_at_utc) FILTER (WHERE after_reset = 0) AS first_reading_at_utc,
+  -- Open: no status line reading at all was captured at or after this reset, so later usage may still come.
+  resets_at > (SELECT MAX(captured_at_s) FROM status_readings WHERE status = 'ok') AS window_open,
+  (SELECT covers_from FROM source_coverage WHERE source = 'status_line') AS covers_from,
+  (SELECT covers_to FROM source_coverage WHERE source = 'status_line') AS covers_to,
+  -- Counted readings marked stale: in readings above, and used for no value (D-089).
+  COUNT(*) FILTER (WHERE after_reset = 0 AND stale = 1) AS readings_stale
+FROM window_readings
+GROUP BY window, resets_at;
+
+-- Observed: last observed usage before each window's reset that isn't stale, with when it was observed (a lower bound on final usage; D-024, D-044, D-089).
+CREATE VIEW obs_window_headroom AS
+WITH ranked AS (
+  SELECT
+    r.*,
+    ROW_NUMBER() OVER (PARTITION BY r.window, r.resets_at ORDER BY r.observed_at_s DESC, r.raw_line_id DESC) AS latest_rank
+  FROM window_readings r
+  WHERE r.after_reset = 0 AND r.stale = 0
+)
+SELECT
+  i.window,
+  i.reset_at_utc,
+  r.used_percentage AS last_used_percentage,
+  r.observed_at_utc AS last_reading_at_utc,
+  r.raw_line_id AS last_reading_raw_line_id,
+  i.readings,
+  i.readings_after_reset,
+  i.first_reading_at_utc,
+  i.window_open,
+  i.covers_from,
+  i.covers_to,
+  i.readings_stale
+FROM window_instances i
+LEFT JOIN ranked r ON r.window = i.window AND r.resets_at = i.resets_at AND r.latest_rank = 1;
+
+-- Observed: consecutive non-stale observations of one window, the change between them, and Claude Code responses in between (D-025, D-045, D-089).
+CREATE VIEW window_reading_pairs AS
+WITH ordered AS (
+  SELECT
+    r.*,
+    LAG(r.raw_line_id) OVER w AS previous_raw_line_id,
+    LAG(r.used_percentage) OVER w AS previous_used_percentage,
+    LAG(r.observed_at_utc) OVER w AS previous_observed_at_utc
+  FROM window_readings r
+  WHERE r.after_reset = 0 AND r.stale = 0
+  WINDOW w AS (PARTITION BY r.window, r.resets_at ORDER BY r.observed_at_s, r.raw_line_id)
+)
+SELECT
+  o.window,
+  o.reset_at_utc,
+  o.previous_raw_line_id,
+  o.raw_line_id,
+  o.previous_observed_at_utc,
+  o.observed_at_utc,
+  o.used_percentage - o.previous_used_percentage AS change_percentage_points,
+  -- Distinct responses with any line from the previous observation up to one second past this one.
+  (SELECT COUNT(DISTINCT COALESCE(rq.dedup_key, 'line:' || rq.raw_line_id))
+     FROM parsed_lines p
+     JOIN requests rq ON rq.raw_line_id = p.raw_line_id
+     WHERE p.class = 'request'
+       AND p.timestamp_utc >= o.previous_observed_at_utc
+       AND p.timestamp_utc < strftime('%Y-%m-%dT%H:%M:%fZ', o.observed_at_s + 1, 'unixepoch')) AS requests_between
+FROM ordered o
+WHERE o.previous_raw_line_id IS NOT NULL;

package/core/schema/029_lockout_sessions.sql

@@ -0,0 +1,68 @@
+-- 029_lockout_sessions: how many sessions each lockout refused requests from (D-090, step G4.2).
+--
+-- One lockout can refuse many requests: on 2026-09-24, 13 within 3 minutes across 3 sessions, 6 of
+-- them in subagents. Shown as "13 hits", that read as 13 separate limits. The report now leads with
+-- lockouts and calls the hit lines refused requests, naming the sessions they came from.
+
+DROP VIEW obs_lockout_intervals;
+
+-- Observed: elapsed lockout intervals (limit hit to reset, overlapping hits merged), with the next request after each reset, logged auto-continuations, and the sessions and refused requests in each (D-023, D-077, D-090).
+CREATE VIEW obs_lockout_intervals AS
+WITH interval_hits AS MATERIALIZED (
+  -- Computed once for everything below: interval membership is the costly part.
+  SELECT raw_line_id, start_utc, end_utc, interval_number FROM obs_lockout_interval_hits
+),
+grouped AS (
+  SELECT
+    interval_number,
+    MIN(start_utc) AS locked_from_utc,
+    MAX(end_utc) AS locked_until_utc,
+    COUNT(*) AS hits
+  FROM interval_hits
+  GROUP BY interval_number
+),
+with_next AS (
+  SELECT
+    g.*,
+    (SELECT MIN(d.timestamp_utc) FROM requests_dedup d WHERE d.timestamp_utc >= g.locked_until_utc) AS next_request_at_utc
+  FROM grouped g
+),
+sessions AS (
+  SELECT
+    h.interval_number,
+    -- A logged hit names its session; a status-line-only hit is a spool reading, which names one too.
+    COUNT(DISTINCT COALESCE(p.session_id, s.session_id)) AS sessions,
+    -- Hits from the session logs: each is a request the limit refused.
+    COUNT(p.raw_line_id) AS refused_requests
+  FROM interval_hits h
+  LEFT JOIN parsed_lines p ON p.raw_line_id = h.raw_line_id
+  LEFT JOIN status_readings s ON s.raw_line_id = h.raw_line_id
+  GROUP BY h.interval_number
+),
+resumed AS (
+  SELECT
+    h.interval_number,
+    COUNT(*) AS auto_continuations,
+    MIN((round(unixepoch(m.continued_at_utc, 'subsec') * 1000) - round(unixepoch(g.locked_until_utc, 'subsec') * 1000)) / 1000.0)
+      AS first_seconds
+  FROM auto_continuation_marks m
+  JOIN interval_hits h ON h.raw_line_id = m.hit_raw_line_id
+  JOIN grouped g ON g.interval_number = h.interval_number
+  GROUP BY h.interval_number
+)
+SELECT
+  w.*,
+  (round(unixepoch(w.locked_until_utc, 'subsec') * 1000) - round(unixepoch(w.locked_from_utc, 'subsec') * 1000)) / 1000.0 AS lockout_seconds,
+  (round(unixepoch(w.next_request_at_utc, 'subsec') * 1000) - round(unixepoch(w.locked_until_utc, 'subsec') * 1000)) / 1000.0 AS reset_to_next_request_seconds,
+  w.locked_until_utc > (SELECT covers_to FROM source_coverage WHERE source = 'session_logs') AS reset_after_coverage,
+  -- How many sessions Claude Code resumed by itself after this reset, as logged; 0 when none.
+  COALESCE(r.auto_continuations, 0) AS auto_continuations,
+  -- The earliest of those, seconds after the reset; NULL when none.
+  r.first_seconds AS first_auto_continuation_seconds,
+  -- Distinct sessions with a hit in this lockout (D-090).
+  COALESCE(n.sessions, 0) AS sessions,
+  -- Its logged hits, each a refused request; the rest of its hits are status line readings at 100% (D-023, D-090).
+  COALESCE(n.refused_requests, 0) AS refused_requests
+FROM with_next w
+LEFT JOIN resumed r ON r.interval_number = w.interval_number
+LEFT JOIN sessions n ON n.interval_number = w.interval_number;

package/core/schema/030_repository_aliases.sql

@@ -0,0 +1,81 @@
+-- 030_repository_aliases: a renamed or moved project's old path counts under its new one (D-092, step G4.5).
+--
+-- Nothing in the logs links a repository's old path to its new one (D-028), so a renamed or moved
+-- project shows twice. The first real case: this project under its old name on the old Mac, a
+-- directory that no longer exists, beside its current checkout. The user enters the link with
+-- `nilometer alias set`; it's user data, like plan prices, and rebuilds never touch it. Each
+-- request keeps the path it was attributed to before the alias, so every number still traces.
+
+-- User data: one row per old path; entering the same old path again replaces its target.
+CREATE TABLE repository_aliases (
+  from_repository TEXT PRIMARY KEY, -- source: user entry, a repository path exactly as attributed (the old name or place)
+  to_repository   TEXT NOT NULL,    -- source: user entry, the repository path its requests count under
+  entered_at      TEXT NOT NULL,    -- derived: ISO-8601 UTC time the row was written
+  CHECK (from_repository <> to_repository)
+) STRICT;
+
+DROP VIEW request_repositories;
+
+-- Observed: each deduplicated request's repository (worktrees and subfolders count as their repository, D-028, D-049), after any alias the user entered (D-092), with the path it had before.
+CREATE VIEW request_repositories AS
+WITH attributed AS (
+  SELECT
+    d.raw_line_id,
+    d.cwd,
+    CASE
+      WHEN r.cwd IS NULL THEN 'unresolved'
+      WHEN r.repo_root IS NOT NULL AND r.root_exists = 1 THEN 'repo'
+      WHEN r.repo_root IS NOT NULL THEN 'missing'
+      ELSE r.kind
+    END AS repo_kind,
+    COALESCE(r.repo_root, d.cwd) AS repository,
+    r.resolved_via
+  FROM requests_dedup d
+  LEFT JOIN repositories r ON r.cwd = d.cwd
+),
+normalized AS MATERIALIZED (
+  SELECT
+    raw_line_id,
+    cwd,
+    repo_kind,
+    CASE
+      WHEN repository GLOB '[A-Za-z]:[\/]*'
+      THEN upper(substr(repository, 1, 1)) || replace(substr(repository, 2), char(92), '/')
+      ELSE repository
+    END AS repository,
+    resolved_via
+  FROM attributed
+),
+targets AS (
+  -- An aliased request takes its target's kind, so the two count as one row: a repository when any
+  -- request under the target is one, else whatever the target has, else its own.
+  SELECT
+    a.from_repository,
+    a.to_repository,
+    (SELECT m.repo_kind FROM normalized m WHERE m.repository = a.to_repository
+       ORDER BY m.repo_kind = 'repo' DESC, m.repo_kind LIMIT 1) AS to_kind
+  FROM repository_aliases a
+)
+SELECT
+  n.raw_line_id,
+  n.cwd,
+  CASE WHEN t.from_repository IS NULL THEN n.repo_kind ELSE COALESCE(t.to_kind, n.repo_kind) END AS repo_kind,
+  COALESCE(t.to_repository, n.repository) AS repository,
+  n.resolved_via,
+  -- The repository the request had before an alias moved it; NULL when no alias applies.
+  CASE WHEN t.from_repository IS NULL THEN NULL ELSE n.repository END AS aliased_from
+FROM normalized n
+LEFT JOIN targets t ON t.from_repository = n.repository;
+
+DROP VIEW obs_usage_events;
+
+-- Observed: every deduplicated request with its repository, as obs_usage_by_repo sums it (D-028), and the path an alias moved it from (D-092).
+CREATE VIEW obs_usage_events AS
+SELECT
+  d.raw_line_id, d.dedup_key, d.session_id, d.timestamp_utc, d.model,
+  r.repository, r.repo_kind,
+  d.input_tokens, d.output_tokens, d.cache_read_tokens,
+  d.cache_write_5m_tokens, d.cache_write_1h_tokens, d.cache_write_unsplit_tokens,
+  r.aliased_from
+FROM requests_dedup d
+JOIN request_repositories r ON r.raw_line_id = d.raw_line_id;