nilometer 0.0.0-stage → 0.1.0

package/core/schema/007_pricing.sql

@@ -0,0 +1,95 @@
+-- 007_pricing: dated API list prices and the per-request cost view (D-005, D-006, D-020).
+--
+-- prices is replaced from core/pricing/prices.json on every ingest. request_costs prices each
+-- deduplicated request at the row in effect on its UTC day, in SQL, from unrounded values. The
+-- displayed label for these numbers is "observed tokens at API list price" (README principle 3):
+-- a projection, never "what you would have spent".
+
+CREATE TABLE prices (
+  model_id                       TEXT NOT NULL, -- source: prices.json model_id (exact message.model string)
+  effective_from                 TEXT NOT NULL, -- source: prices.json effective_from, YYYY-MM-DD; 0000-01-01 = since release (D-020)
+  input_per_mtok                 REAL NOT NULL, -- source: pricing page, base input USD per million tokens
+  output_per_mtok                REAL NOT NULL, -- source: pricing page, output
+  cache_write_5m_per_mtok        REAL NOT NULL, -- source: pricing page, 5-minute cache writes
+  cache_write_1h_per_mtok        REAL NOT NULL, -- source: pricing page, 1-hour cache writes
+  cache_read_per_mtok            REAL NOT NULL, -- source: pricing page, cache hits and refreshes
+  fast_input_per_mtok            REAL,          -- source: pricing page, fast mode input; NULL when not published
+  fast_output_per_mtok           REAL,          -- source: pricing page, fast mode output
+  fast_cache_write_5m_per_mtok   REAL,          -- source: pricing page, caching multipliers on fast input
+  fast_cache_write_1h_per_mtok   REAL,          -- source: pricing page, caching multipliers on fast input
+  fast_cache_read_per_mtok       REAL,          -- source: pricing page, caching multipliers on fast input
+  standard_rate_max_input_tokens INTEGER,       -- source: prices.json; NULL when the full context window is standard-priced
+  source_url                     TEXT NOT NULL, -- source: page the rates were read from
+  verified_on                    TEXT NOT NULL, -- source: day the page was read, YYYY-MM-DD
+  PRIMARY KEY (model_id, effective_from)
+) STRICT;
+
+ALTER TABLE requests ADD COLUMN service_tier TEXT; -- source: message.usage.service_tier when it's a string
+ALTER TABLE requests ADD COLUMN inference_geo TEXT; -- source: message.usage.inference_geo when it's a string
+
+-- Projected: each deduplicated request at API list price, or NULL cost with the reason it can't be priced.
+CREATE VIEW request_costs AS
+WITH matched AS (
+  SELECT
+    d.*,
+    r.service_tier,
+    r.inference_geo,
+    substr(d.timestamp_utc, 1, 10) AS day_utc,
+    d.input_tokens + d.cache_read_tokens + COALESCE(d.cache_write_5m_tokens, 0)
+      + COALESCE(d.cache_write_1h_tokens, 0) + COALESCE(d.cache_write_unsplit_tokens, 0) AS total_input_tokens,
+    (SELECT p.effective_from FROM prices p
+       WHERE p.model_id = d.model AND p.effective_from <= substr(d.timestamp_utc, 1, 10)
+       ORDER BY p.effective_from DESC LIMIT 1) AS price_effective_from
+  FROM requests_dedup d
+  JOIN requests r ON r.raw_line_id = d.raw_line_id
+),
+rated AS (
+  SELECT
+    m.*,
+    p.verified_on,
+    p.standard_rate_max_input_tokens,
+    CASE
+      WHEN m.timestamp_utc IS NULL THEN 'unparsed_timestamp'
+      WHEN p.model_id IS NULL THEN 'no_price_row'
+      WHEN m.speed = 'fast' AND p.fast_input_per_mtok IS NULL THEN 'fast_rate_unknown'
+      WHEN m.service_tier IS NOT NULL AND m.service_tier <> 'standard' THEN 'service_tier_not_standard'
+      WHEN p.standard_rate_max_input_tokens IS NOT NULL
+           AND m.total_input_tokens > p.standard_rate_max_input_tokens THEN 'long_context_rate_unverified'
+      ELSE NULL
+    END AS unpriced_reason,
+    CASE WHEN m.speed = 'fast' THEN p.fast_input_per_mtok ELSE p.input_per_mtok END AS rate_input,
+    CASE WHEN m.speed = 'fast' THEN p.fast_output_per_mtok ELSE p.output_per_mtok END AS rate_output,
+    CASE WHEN m.speed = 'fast' THEN p.fast_cache_write_5m_per_mtok ELSE p.cache_write_5m_per_mtok END AS rate_write_5m,
+    CASE WHEN m.speed = 'fast' THEN p.fast_cache_write_1h_per_mtok ELSE p.cache_write_1h_per_mtok END AS rate_write_1h,
+    CASE WHEN m.speed = 'fast' THEN p.fast_cache_read_per_mtok ELSE p.cache_read_per_mtok END AS rate_read,
+    CASE WHEN m.inference_geo = 'us' THEN 1.1 ELSE 1.0 END AS geo_multiplier
+  FROM matched m
+  LEFT JOIN prices p ON p.model_id = m.model AND p.effective_from = m.price_effective_from
+)
+SELECT
+  raw_line_id, dedup_key, model, day_utc, timestamp_utc, speed, service_tier, inference_geo,
+  input_tokens, output_tokens, cache_read_tokens,
+  cache_write_5m_tokens, cache_write_1h_tokens, cache_write_unsplit_tokens,
+  unpriced_reason,
+  price_effective_from,
+  verified_on,
+  -- 1 when unsplit cache writes were priced at the 5-minute rate, so the cost is a lower bound.
+  CASE WHEN unpriced_reason IS NULL AND cache_write_unsplit_tokens > 0 THEN 1 ELSE 0 END AS is_lower_bound,
+  CASE WHEN unpriced_reason IS NULL THEN input_tokens * rate_input * geo_multiplier / 1e6 END AS input_usd,
+  CASE WHEN unpriced_reason IS NULL THEN output_tokens * rate_output * geo_multiplier / 1e6 END AS output_usd,
+  CASE WHEN unpriced_reason IS NULL THEN cache_read_tokens * rate_read * geo_multiplier / 1e6 END AS cache_read_usd,
+  CASE WHEN unpriced_reason IS NULL
+       THEN (COALESCE(cache_write_5m_tokens, 0) + COALESCE(cache_write_unsplit_tokens, 0)) * rate_write_5m * geo_multiplier / 1e6 END AS cache_write_5m_usd,
+  CASE WHEN unpriced_reason IS NULL THEN COALESCE(cache_write_1h_tokens, 0) * rate_write_1h * geo_multiplier / 1e6 END AS cache_write_1h_usd,
+  CASE WHEN unpriced_reason IS NULL THEN
+    (input_tokens * rate_input + output_tokens * rate_output + cache_read_tokens * rate_read
+     + (COALESCE(cache_write_5m_tokens, 0) + COALESCE(cache_write_unsplit_tokens, 0)) * rate_write_5m
+     + COALESCE(cache_write_1h_tokens, 0) * rate_write_1h) * geo_multiplier / 1e6
+  END AS total_usd
+FROM rated;
+
+-- Observed: requests that couldn't be priced, and why (D-005: never $0, never a family fallback).
+CREATE VIEW unpriced_requests AS
+SELECT raw_line_id, dedup_key, model, day_utc, speed, service_tier, unpriced_reason
+FROM request_costs
+WHERE unpriced_reason IS NOT NULL;

package/core/schema/008_interruptions.sql

@@ -0,0 +1,263 @@
+-- 008_interruptions: conversation links, resolved reset times, and the interruption metrics (P6.1).
+--
+-- Rules: D-004 (limit hits), D-021 (mid-task), D-022 (resumption), D-023 (lockout, merging hits).
+-- Every metric has a summary view (obs_<metric>) returning covers_from/covers_to, and an events
+-- view listing the rows behind its number, so each number can be re-summed from its events
+-- (README principles 4 and 5). Timestamps are UTC text, `YYYY-MM-DDTHH:MM:SS.sssZ`, which sorts
+-- chronologically. Spans subtract whole milliseconds, which is the timestamps' precision, so
+-- they carry no floating-point noise.
+
+ALTER TABLE parsed_lines ADD COLUMN uuid TEXT; -- source: uuid when it's a non-empty string
+ALTER TABLE parsed_lines ADD COLUMN parent_uuid TEXT; -- source: parentUuid when it's a non-empty string (D-021)
+ALTER TABLE parsed_lines ADD COLUMN origin_kind TEXT; -- source: origin.kind when it's a string (D-022)
+ALTER TABLE parsed_lines ADD COLUMN user_content TEXT CHECK (user_content IN ('tool_result', 'prompt')); -- derived: user lines only; 'tool_result' when message.content holds a tool_result block
+ALTER TABLE parsed_lines ADD COLUMN is_meta INTEGER NOT NULL DEFAULT 0 CHECK (is_meta IN (0, 1)); -- source: isMeta === true (1) or anything else (0)
+ALTER TABLE events ADD COLUMN reset_at_utc TEXT; -- derived: limit hits only; reset_text resolved against the hit's timestamp (D-023)
+
+-- Parent lookups and "next line in this session" lookups.
+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);
+
+-- Observed: the time span each source's data covers, from the data present (README principle 5).
+CREATE VIEW source_coverage AS
+SELECT 'session_logs' AS source, MIN(timestamp_utc) AS covers_from, MAX(timestamp_utc) AS covers_to
+FROM parsed_lines
+WHERE timestamp_utc IS NOT NULL
+UNION ALL
+SELECT
+  'status_line',
+  strftime('%Y-%m-%dT%H:%M:%fZ', MIN(captured_at_s), 'unixepoch'),
+  strftime('%Y-%m-%dT%H:%M:%fZ', MAX(captured_at_s), 'unixepoch')
+FROM status_readings
+WHERE status = 'ok';
+
+-- Observed: logged limit hits, one per distinct line (copies of a uuid in one session count once), with the D-021 position.
+CREATE VIEW logged_limit_hits AS
+WITH copies AS (
+  SELECT
+    p.raw_line_id, p.session_id, p.uuid, p.parent_uuid, p.timestamp_utc, p.is_sidechain,
+    e.window, e.reset_text, e.reset_at_utc,
+    ROW_NUMBER() OVER (
+      -- A line without a uuid is its own group: NULL uuids must not merge with each other.
+      PARTITION BY p.session_id, p.uuid, CASE WHEN p.uuid IS NULL THEN p.raw_line_id END
+      ORDER BY f.root, f.relative_path, l.first_run_id, l.line_number
+    ) AS copy_rank
+  FROM events e
+  JOIN parsed_lines p ON p.raw_line_id = e.raw_line_id
+  JOIN raw_lines l ON l.id = e.raw_line_id
+  JOIN source_files f ON f.id = l.source_file_id
+  WHERE e.class = 'limit_hit'
+)
+SELECT
+  c.raw_line_id, c.session_id, c.uuid, c.parent_uuid, c.timestamp_utc, c.is_sidechain,
+  c.window, c.reset_text, c.reset_at_utc,
+  COALESCE((
+    SELECT CASE
+      WHEN par.user_content = 'tool_result' THEN 'mid_task'
+      WHEN par.user_content = 'prompt' AND par.is_meta = 0 THEN 'turn_start'
+      ELSE 'unknown'
+    END
+    FROM parsed_lines par
+    JOIN raw_lines pl ON pl.id = par.raw_line_id
+    JOIN source_files pf ON pf.id = pl.source_file_id
+    WHERE par.session_id = c.session_id AND par.uuid = c.parent_uuid
+    ORDER BY pf.root, pf.relative_path, pl.first_run_id, pl.line_number
+    LIMIT 1
+  ), 'unknown') AS position
+FROM copies c
+WHERE c.copy_rank = 1;
+
+-- Observed: status line windows that reached 100%, one row per (window, resets_at), from init onward (D-023).
+CREATE VIEW status_limit_groups AS
+WITH at_limit AS (
+  SELECT
+    w.raw_line_id, w.window, w.resets_at, s.session_id, s.captured_at_s,
+    ROW_NUMBER() OVER (PARTITION BY w.window, w.resets_at ORDER BY s.captured_at_s, w.raw_line_id) AS reading_rank,
+    COUNT(*) OVER (PARTITION BY w.window, w.resets_at) AS readings_at_limit
+  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') AND w.used_percentage >= 100
+)
+SELECT
+  raw_line_id, window, resets_at, session_id, readings_at_limit,
+  strftime('%Y-%m-%dT%H:%M:%fZ', captured_at_s, 'unixepoch') AS first_at_utc,
+  strftime('%Y-%m-%dT%H:%M:%fZ', resets_at, 'unixepoch') AS reset_at_utc,
+  CASE window WHEN 'five_hour' THEN 5 * 3600 ELSE 7 * 86400 END AS window_seconds
+FROM at_limit
+WHERE reading_rank = 1;
+
+-- Observed: every rate-limit interruption, logged hits merged with status line groups without double-counting (D-004, D-023).
+CREATE VIEW obs_limit_hits_events AS
+WITH logged AS (
+  SELECT
+    h.*,
+    (SELECT g.raw_line_id FROM status_limit_groups g
+       WHERE (h.window IS NULL OR h.window = g.window)
+         AND unixepoch(h.timestamp_utc, 'subsec') > g.resets_at - g.window_seconds
+         AND unixepoch(h.timestamp_utc, 'subsec') <= g.resets_at
+       ORDER BY g.resets_at, g.window
+       LIMIT 1) AS status_raw_line_id
+  FROM logged_limit_hits h
+),
+merged AS (
+  SELECT
+    'session_log' AS source,
+    l.raw_line_id,
+    l.status_raw_line_id,
+    l.session_id,
+    l.timestamp_utc AS hit_at_utc,
+    COALESCE(l.window, g.window) AS window,
+    -- The payload's resets_at is exact; reset text has minute precision.
+    COALESCE(g.reset_at_utc, l.reset_at_utc) AS reset_at_utc,
+    CASE WHEN g.raw_line_id IS NOT NULL THEN 'status_line' WHEN l.reset_at_utc IS NOT NULL THEN 'log_text' END AS reset_source,
+    l.reset_text,
+    l.position,
+    l.is_sidechain
+  FROM logged l
+  LEFT JOIN status_limit_groups g ON g.raw_line_id = l.status_raw_line_id
+  UNION ALL
+  SELECT 'status_line', g.raw_line_id, g.raw_line_id, g.session_id, g.first_at_utc, g.window,
+         g.reset_at_utc, 'status_line', NULL, 'unknown', 0
+  FROM status_limit_groups g
+  WHERE NOT EXISTS (SELECT 1 FROM logged l WHERE l.status_raw_line_id = g.raw_line_id)
+)
+SELECT
+  m.*,
+  (round(unixepoch(m.reset_at_utc, 'subsec') * 1000) - round(unixepoch(m.hit_at_utc, 'subsec') * 1000)) / 1000.0 AS hit_to_reset_seconds,
+  (SELECT MIN(d.timestamp_utc) FROM requests_dedup d
+     WHERE d.session_id = m.session_id AND d.timestamp_utc > m.hit_at_utc) AS next_session_request_at_utc,
+  (SELECT p.timestamp_utc FROM parsed_lines p
+     WHERE p.session_id = m.session_id AND p.user_content = 'prompt' AND p.is_meta = 0
+       AND p.timestamp_utc > m.hit_at_utc
+     ORDER BY p.timestamp_utc, p.raw_line_id LIMIT 1) AS next_session_prompt_at_utc,
+  -- origin.kind as written (D-022): never relabeled as automatic or manual.
+  (SELECT p.origin_kind FROM parsed_lines p
+     WHERE p.session_id = m.session_id AND p.user_content = 'prompt' AND p.is_meta = 0
+       AND p.timestamp_utc > m.hit_at_utc
+     ORDER BY p.timestamp_utc, p.raw_line_id LIMIT 1) AS next_session_prompt_origin_kind,
+  m.reset_at_utc > (SELECT covers_to FROM source_coverage WHERE source = 'session_logs') AS reset_after_coverage
+FROM merged m;
+
+-- Observed: count of rate-limit interruptions, by source and window.
+CREATE VIEW obs_limit_hits AS
+SELECT
+  COUNT(e.raw_line_id) AS hits,
+  COUNT(e.raw_line_id) FILTER (WHERE e.source = 'session_log') AS logged_hits,
+  COUNT(e.raw_line_id) FILTER (WHERE e.source = 'status_line') AS status_line_only_hits,
+  COUNT(e.raw_line_id) FILTER (WHERE e.window = 'five_hour') AS five_hour_hits,
+  COUNT(e.raw_line_id) FILTER (WHERE e.window = 'seven_day') AS seven_day_hits,
+  COUNT(e.raw_line_id) FILTER (WHERE e.window IS NULL) AS unknown_window_hits,
+  (SELECT covers_from FROM source_coverage WHERE source = 'session_logs') AS covers_from,
+  (SELECT covers_to FROM source_coverage WHERE source = 'session_logs') AS covers_to,
+  (SELECT covers_from FROM source_coverage WHERE source = 'status_line') AS status_line_covers_from,
+  (SELECT covers_to FROM source_coverage WHERE source = 'status_line') AS status_line_covers_to
+FROM obs_limit_hits_events e;
+
+-- Observed: the interruptions that stopped the model while it was continuing its own tool loop (D-021).
+CREATE VIEW obs_mid_task_interruptions_events AS
+SELECT * FROM obs_limit_hits_events WHERE position = 'mid_task';
+
+-- Observed: mid-task interruptions, beside turn-start and unknown-position counts (D-021).
+CREATE VIEW obs_mid_task_interruptions AS
+SELECT
+  COUNT(e.raw_line_id) FILTER (WHERE e.position = 'mid_task') AS mid_task,
+  COUNT(e.raw_line_id) FILTER (WHERE e.position = 'turn_start') AS turn_start,
+  COUNT(e.raw_line_id) FILTER (WHERE e.position = 'unknown') AS position_unknown,
+  (SELECT covers_from FROM source_coverage WHERE source = 'session_logs') AS covers_from,
+  (SELECT covers_to FROM source_coverage WHERE source = 'session_logs') AS covers_to
+FROM obs_limit_hits_events e;
+
+-- Observed: which merged lockout interval each hit with a known reset belongs to (D-023).
+CREATE VIEW obs_lockout_interval_hits AS
+WITH spans AS (
+  SELECT
+    raw_line_id,
+    hit_at_utc AS start_utc,
+    -- A reset in the hit's own minute can precede the hit by seconds; the span is then empty.
+    MAX(reset_at_utc, hit_at_utc) AS end_utc
+  FROM obs_limit_hits_events
+  WHERE hit_at_utc IS NOT NULL AND reset_at_utc IS NOT NULL
+),
+ordered AS (
+  SELECT
+    s.*,
+    MAX(end_utc) OVER (ORDER BY start_utc, end_utc, raw_line_id
+                       ROWS BETWEEN UNBOUNDED PRECEDING AND 1 PRECEDING) AS previous_end_utc
+  FROM spans s
+)
+SELECT
+  raw_line_id, start_utc, end_utc,
+  -- A span starting after every earlier span has ended opens a new interval; touching spans merge.
+  SUM(CASE WHEN previous_end_utc IS NULL OR start_utc > previous_end_utc THEN 1 ELSE 0 END)
+    OVER (ORDER BY start_utc, end_utc, raw_line_id) AS interval_number
+FROM ordered;
+
+-- Observed: merged lockout intervals, hit → reset, with the first Claude Code request at or after each reset (D-023).
+CREATE VIEW obs_lockout_intervals AS
+WITH grouped AS (
+  SELECT
+    interval_number,
+    MIN(start_utc) AS locked_from_utc,
+    MAX(end_utc) AS locked_until_utc,
+    COUNT(*) AS hits
+  FROM obs_lockout_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
+)
+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
+FROM with_next w;
+
+-- Observed: total elapsed lockout time (hit → reset, overlaps counted once), beside hits whose reset is unknown.
+CREATE VIEW obs_lockout_time AS
+SELECT
+  (SELECT COUNT(*) FROM obs_lockout_intervals) AS intervals,
+  (SELECT TOTAL(lockout_seconds) FROM obs_lockout_intervals) AS lockout_seconds,
+  (SELECT COUNT(*) FROM obs_lockout_interval_hits) AS hits_with_known_reset,
+  (SELECT COUNT(*) FROM obs_limit_hits_events WHERE reset_at_utc IS NULL OR hit_at_utc IS NULL) AS hits_with_unknown_reset,
+  (SELECT covers_from FROM source_coverage WHERE source = 'session_logs') AS covers_from,
+  (SELECT covers_to FROM source_coverage WHERE source = 'session_logs') AS covers_to;
+
+-- Observed: sessions whose last limit hit has no later request in that session (D-022).
+CREATE VIEW obs_sessions_not_resumed_events AS
+WITH ranked AS (
+  SELECT
+    e.session_id, e.raw_line_id, e.hit_at_utc, e.reset_at_utc, e.reset_after_coverage,
+    ROW_NUMBER() OVER (PARTITION BY e.session_id ORDER BY e.hit_at_utc DESC, e.raw_line_id DESC) AS hit_rank,
+    COUNT(*) OVER (PARTITION BY e.session_id) AS hits
+  FROM obs_limit_hits_events e
+  WHERE e.session_id IS NOT NULL AND e.session_id <> '<missing>' AND e.hit_at_utc IS NOT NULL
+)
+SELECT
+  session_id,
+  raw_line_id AS last_hit_raw_line_id,
+  hit_at_utc AS last_hit_at_utc,
+  reset_at_utc,
+  reset_after_coverage,
+  hits
+FROM ranked r
+WHERE hit_rank = 1
+  AND NOT EXISTS (
+    SELECT 1 FROM requests_dedup d WHERE d.session_id = r.session_id AND d.timestamp_utc > r.hit_at_utc
+  );
+
+-- Observed: sessions not resumed after a limit hit, with those whose reset was after log coverage counted separately.
+CREATE VIEW obs_sessions_not_resumed AS
+SELECT
+  (SELECT COUNT(DISTINCT session_id) FROM obs_limit_hits_events
+     WHERE session_id IS NOT NULL AND session_id <> '<missing>' AND hit_at_utc IS NOT NULL) AS sessions_with_hits,
+  COUNT(n.session_id) AS sessions_not_resumed,
+  COUNT(n.session_id) FILTER (WHERE n.reset_after_coverage = 1) AS reset_after_coverage,
+  COUNT(n.session_id) FILTER (WHERE n.reset_at_utc IS NULL) AS reset_unknown,
+  (SELECT covers_from FROM source_coverage WHERE source = 'session_logs') AS covers_from,
+  (SELECT covers_to FROM source_coverage WHERE source = 'session_logs') AS covers_to
+FROM obs_sessions_not_resumed_events n;

package/core/schema/009_headroom.sql

@@ -0,0 +1,84 @@
+-- 009_headroom: last observed usage and peak usage per rate-limit window, from init onward (P6.2, D-024).
+--
+-- A window instance is (window, resets_at). Readings come only from the status line, so these
+-- metrics cover the status line's span, not the logs' (README principle 5). The last reading is a
+-- lower bound on the window's final usage: budget spent after the last Claude Code turn isn't seen.
+
+-- Observed: valid plan-window readings, each with its window instance and whether it was captured after that reset.
+CREATE VIEW window_readings AS
+SELECT
+  w.raw_line_id,
+  w.window,
+  w.resets_at,
+  strftime('%Y-%m-%dT%H:%M:%fZ', w.resets_at, 'unixepoch') AS reset_at_utc,
+  w.used_percentage,
+  s.session_id,
+  s.captured_at_s,
+  strftime('%Y-%m-%dT%H:%M:%fZ', s.captured_at_s, 'unixepoch') AS captured_at_utc,
+  s.captured_at_s > w.resets_at AS captured_after_reset
+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');
+
+-- Observed: per window instance, reading counts, 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 captured_after_reset = 0) AS readings,
+  COUNT(*) FILTER (WHERE captured_after_reset = 1) AS readings_after_reset,
+  MIN(captured_at_utc) FILTER (WHERE captured_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
+FROM window_readings
+GROUP BY window, resets_at;
+
+-- Observed: last observed usage before each window's reset, with that reading's time (a lower bound on final usage).
+CREATE VIEW obs_window_headroom AS
+WITH ranked AS (
+  SELECT
+    r.*,
+    ROW_NUMBER() OVER (PARTITION BY r.window, r.resets_at ORDER BY r.captured_at_s DESC, r.raw_line_id DESC) AS latest_rank
+  FROM window_readings r
+  WHERE r.captured_after_reset = 0
+)
+SELECT
+  i.window,
+  i.reset_at_utc,
+  r.used_percentage AS last_used_percentage,
+  r.captured_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
+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: highest observed usage in each window, with the reading it came from.
+CREATE VIEW obs_window_peak AS
+WITH ranked AS (
+  SELECT
+    r.*,
+    ROW_NUMBER() OVER (PARTITION BY r.window, r.resets_at ORDER BY r.used_percentage DESC, r.captured_at_s, r.raw_line_id) AS peak_rank
+  FROM window_readings r
+  WHERE r.captured_after_reset = 0
+)
+SELECT
+  i.window,
+  i.reset_at_utc,
+  r.used_percentage AS peak_used_percentage,
+  r.captured_at_utc AS peak_reading_at_utc,
+  r.raw_line_id AS peak_reading_raw_line_id,
+  i.readings,
+  i.readings_after_reset,
+  i.window_open,
+  i.covers_from,
+  i.covers_to
+FROM window_instances i
+LEFT JOIN ranked r ON r.window = i.window AND r.resets_at = i.resets_at AND r.peak_rank = 1;

package/core/schema/010_attribution.sql

@@ -0,0 +1,106 @@
+-- 010_attribution: where observed usage goes, by model and repository, and budget used outside Claude Code (P6.3).
+--
+-- Model and repository metrics are log-derived and cover the logs' span; unattributed usage is
+-- status-line-derived and covers the status line's span (README principle 5). Token sums are
+-- per request after dedup (D-001, D-007). A token type with no requests reporting it sums to NULL.
+
+-- Observed: every deduplicated request with the model and repository it's attributed to.
+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
+FROM requests_dedup d
+JOIN request_repositories r ON r.raw_line_id = d.raw_line_id;
+
+-- Observed: tokens per model per token type, with request counts and unknowns.
+CREATE VIEW obs_usage_by_model AS
+SELECT
+  model,
+  COUNT(*) AS requests,
+  SUM(input_tokens) AS input_tokens,
+  SUM(output_tokens) AS output_tokens,
+  SUM(cache_read_tokens) AS cache_read_tokens,
+  SUM(cache_write_5m_tokens) AS cache_write_5m_tokens,
+  SUM(cache_write_1h_tokens) AS cache_write_1h_tokens,
+  SUM(cache_write_unsplit_tokens) AS cache_write_unsplit_tokens,
+  COUNT(*) FILTER (WHERE dedup_key IS NULL) AS unkeyed_requests,
+  COUNT(*) FILTER (WHERE timestamp_utc IS NULL) AS requests_without_timestamp,
+  MIN(timestamp_utc) AS first_request_at_utc,
+  MAX(timestamp_utc) AS last_request_at_utc,
+  (SELECT covers_from FROM source_coverage WHERE source = 'session_logs') AS covers_from,
+  (SELECT covers_to FROM source_coverage WHERE source = 'session_logs') AS covers_to
+FROM obs_usage_events
+GROUP BY model;
+
+-- Observed: tokens per repository (git root, or the working directory outside git; NULL when no cwd) per token type.
+CREATE VIEW obs_usage_by_repo AS
+SELECT
+  repository,
+  repo_kind,
+  COUNT(*) AS requests,
+  SUM(input_tokens) AS input_tokens,
+  SUM(output_tokens) AS output_tokens,
+  SUM(cache_read_tokens) AS cache_read_tokens,
+  SUM(cache_write_5m_tokens) AS cache_write_5m_tokens,
+  SUM(cache_write_1h_tokens) AS cache_write_1h_tokens,
+  SUM(cache_write_unsplit_tokens) AS cache_write_unsplit_tokens,
+  COUNT(*) FILTER (WHERE timestamp_utc IS NULL) AS requests_without_timestamp,
+  (SELECT covers_from FROM source_coverage WHERE source = 'session_logs') AS covers_from,
+  (SELECT covers_to FROM source_coverage WHERE source = 'session_logs') AS covers_to
+FROM obs_usage_events
+GROUP BY repository, repo_kind;
+
+-- Observed: consecutive readings of one window, the change between them, and Claude Code requests in between (D-025).
+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.captured_at_s) OVER w AS previous_captured_at_s
+  FROM window_readings r
+  WHERE r.captured_after_reset = 0
+  WINDOW w AS (PARTITION BY r.window, r.resets_at ORDER BY r.captured_at_s, r.raw_line_id)
+)
+SELECT
+  o.window,
+  o.reset_at_utc,
+  o.previous_raw_line_id,
+  o.raw_line_id,
+  strftime('%Y-%m-%dT%H:%M:%fZ', o.previous_captured_at_s, 'unixepoch') AS previous_captured_at_utc,
+  o.captured_at_utc,
+  o.used_percentage - o.previous_used_percentage AS change_percentage_points,
+  -- Captures are whole seconds: include the previous capture's second, and one second past this capture.
+  (SELECT COUNT(*) FROM requests_dedup d
+     WHERE d.timestamp_utc >= strftime('%Y-%m-%dT%H:%M:%fZ', o.previous_captured_at_s, 'unixepoch')
+       AND d.timestamp_utc < strftime('%Y-%m-%dT%H:%M:%fZ', o.captured_at_s + 1, 'unixepoch')) AS requests_between
+FROM ordered o
+WHERE o.previous_raw_line_id IS NOT NULL;
+
+-- Observed: reading pairs whose usage rose with no Claude Code request in between (D-025).
+CREATE VIEW obs_unattributed_usage_events AS
+SELECT * FROM window_reading_pairs
+WHERE requests_between = 0 AND change_percentage_points > 0;
+
+-- Observed: per window, percentage points consumed with no Claude Code request in between (a lower bound), beside pair counts.
+CREATE VIEW obs_unattributed_usage AS
+SELECT
+  i.window,
+  i.reset_at_utc,
+  i.readings,
+  (SELECT COUNT(*) FROM window_reading_pairs p WHERE p.window = i.window AND p.reset_at_utc = i.reset_at_utc) AS pairs,
+  (SELECT COUNT(*) FROM window_reading_pairs p
+     WHERE p.window = i.window AND p.reset_at_utc = i.reset_at_utc AND p.requests_between = 0) AS pairs_without_requests,
+  (SELECT COUNT(*) FROM window_reading_pairs p
+     WHERE p.window = i.window AND p.reset_at_utc = i.reset_at_utc AND p.change_percentage_points < 0) AS decreasing_pairs,
+  -- Fewer than two readings means no pair was observed: unknown, not 0.
+  CASE WHEN i.readings >= 2 THEN
+    (SELECT TOTAL(e.change_percentage_points) FROM obs_unattributed_usage_events e
+       WHERE e.window = i.window AND e.reset_at_utc = i.reset_at_utc)
+  END AS unattributed_percentage_points,
+  i.window_open,
+  i.covers_from,
+  i.covers_to
+FROM window_instances i;

package/core/schema/011_projections.sql

@@ -0,0 +1,83 @@
+-- 011_projections: projections derived from observations, kept apart from observed views (P6.4, D-026, D-027).
+--
+-- Every view here is a projection: it carries the proj_ prefix, and no obs_ view may read from it
+-- (README principle 2; enforced by tests/unit/core/metrics/structure.test.ts). plan_prices is user
+-- data entered with the plan-price command: not derived, never rebuilt, never committed.
+
+CREATE TABLE plan_prices (
+  effective_month TEXT PRIMARY KEY, -- source: user entry, YYYY-MM (local calendar month from which the price applies)
+  plan_name       TEXT NOT NULL,    -- source: user entry, the plan's name as the user writes it
+  usd_per_month   REAL NOT NULL,    -- source: user entry, the plan's USD list price per month (README, Currency)
+  entered_at      TEXT NOT NULL,    -- derived: ISO-8601 UTC time the row was written
+  CHECK (effective_month GLOB '[0-9][0-9][0-9][0-9]-[0-1][0-9]'),
+  CHECK (usd_per_month >= 0)
+) STRICT;
+
+-- Projected: when each window's limit would be reached at its average rate since the window began (D-026).
+CREATE VIEW proj_burn_rate AS
+WITH timed AS (
+  SELECT
+    h.*,
+    unixepoch(h.reset_at_utc) - CASE h.window WHEN 'five_hour' THEN 5 * 3600 ELSE 7 * 86400 END AS window_start_s,
+    unixepoch(h.last_reading_at_utc, 'subsec') AS last_reading_s
+  FROM obs_window_headroom h
+)
+SELECT
+  window,
+  reset_at_utc,
+  strftime('%Y-%m-%dT%H:%M:%fZ', window_start_s, 'unixepoch') AS window_start_utc,
+  last_used_percentage,
+  last_reading_at_utc,
+  window_open,
+  last_used_percentage >= 100 AS limit_reached,
+  -- Unknown without a reading after the window start: the premise (0% at the start) can't apply.
+  CASE WHEN last_reading_s > window_start_s
+       THEN last_used_percentage * 3600.0 / (last_reading_s - window_start_s)
+  END AS projected_percentage_points_per_hour,
+  CASE WHEN last_reading_s > window_start_s AND last_used_percentage > 0 AND last_used_percentage < 100
+       THEN strftime('%Y-%m-%dT%H:%M:%fZ',
+                     window_start_s + (last_reading_s - window_start_s) * 100.0 / last_used_percentage,
+                     'unixepoch')
+  END AS projected_limit_at_utc,
+  CASE WHEN last_reading_s > window_start_s AND last_used_percentage > 0 AND last_used_percentage < 100
+       THEN window_start_s + (last_reading_s - window_start_s) * 100.0 / last_used_percentage < unixepoch(reset_at_utc)
+  END AS projected_limit_before_reset,
+  covers_from,
+  covers_to
+FROM timed;
+
+-- Projected: observed tokens at API list price per local calendar month, beside the plan price entered for that month (D-027).
+CREATE VIEW proj_api_list_price AS
+WITH months AS (
+  SELECT
+    strftime('%Y-%m', timestamp_utc, 'localtime') AS month,
+    COUNT(*) AS requests,
+    COUNT(*) FILTER (WHERE unpriced_reason IS NULL) AS priced_requests,
+    COUNT(*) FILTER (WHERE unpriced_reason IS NOT NULL) AS unpriced_requests,
+    COUNT(*) FILTER (WHERE is_lower_bound = 1) AS lower_bound_requests,
+    COUNT(*) FILTER (WHERE unpriced_reason IS NULL AND day_utc < verified_on) AS priced_before_verified_requests,
+    MAX(verified_on) AS verified_on,
+    TOTAL(total_usd) AS priced_usd,
+    MIN(timestamp_utc) AS covers_from,
+    MAX(timestamp_utc) AS covers_to
+  FROM request_costs
+  WHERE timestamp_utc IS NOT NULL
+  GROUP BY month
+)
+SELECT
+  m.month,
+  m.requests,
+  m.priced_requests,
+  m.unpriced_requests,
+  m.lower_bound_requests,
+  m.priced_before_verified_requests,
+  m.verified_on,
+  -- No priced request in the month: the cost is unknown, not $0.
+  CASE WHEN m.priced_requests > 0 THEN m.priced_usd END AS api_list_price_usd,
+  (SELECT p.plan_name FROM plan_prices p WHERE p.effective_month <= m.month
+     ORDER BY p.effective_month DESC LIMIT 1) AS plan_name,
+  (SELECT p.usd_per_month FROM plan_prices p WHERE p.effective_month <= m.month
+     ORDER BY p.effective_month DESC LIMIT 1) AS plan_usd_per_month,
+  m.covers_from,
+  m.covers_to
+FROM months m;