agentwrangler 0.1.0

package/dist/query/api/cost-per-success.js

@@ -0,0 +1,104 @@
+/**
+ * src/query/api/cost-per-success.ts — observed cost-per-delivery proxies.
+ *
+ * The merged-PR ratio intentionally uses lifecycle state='MERGED' only;
+ * checks_conclusion is not required.
+ */
+import { buildResponse } from "../envelope.js";
+/**
+ * Derive state-based delivery proxy metrics for the half-open [from, to) window.
+ */
+export function getCostPerSuccess(db, workspaceId, from, to) {
+    const workItemFilter = workspaceId === null ? "" : " AND wi.workspace_id = ?";
+    const sessionFilter = workspaceId === null ? "" : " AND s.workspace_id = ?";
+    const params = workspaceId === null
+        ? [from, to, from, to, from, to]
+        : [
+            from,
+            to,
+            workspaceId,
+            from,
+            to,
+            workspaceId,
+            workspaceId,
+            from,
+            to,
+            workspaceId,
+            workspaceId,
+        ];
+    const row = db
+        .prepare(`WITH merged_work_items AS (
+         SELECT wi.work_item_id
+           FROM work_items wi
+          WHERE wi.state = 'MERGED'
+            AND wi.merged_at >= ? AND wi.merged_at < ?${workItemFilter}
+       ),
+       closed_unmerged_work_items AS (
+         SELECT wi.work_item_id
+           FROM work_items wi
+          WHERE wi.state = 'CLOSED'
+            AND wi.closed_at >= ? AND wi.closed_at < ?${workItemFilter}
+       ),
+       merged_session_costs AS (
+         SELECT DISTINCT s.session_id, s.cost_equiv_u
+           FROM sessions s
+           JOIN session_work_links swl ON swl.session_id = s.session_id
+           JOIN merged_work_items mwi ON mwi.work_item_id = swl.work_item_id
+          WHERE 1 = 1${sessionFilter}
+       ),
+       in_window_sessions AS (
+         SELECT s.session_id, s.cost_equiv_u
+           FROM sessions s
+          WHERE s.first_turn_at >= ? AND s.first_turn_at < ?${sessionFilter}
+       ),
+       commit_sessions AS (
+         SELECT iws.session_id, iws.cost_equiv_u
+           FROM in_window_sessions iws
+          WHERE EXISTS (
+            SELECT 1
+              FROM tool_events te
+             WHERE te.session_id = iws.session_id
+               AND te.commit_sha IS NOT NULL
+          )
+       )
+       SELECT
+         (SELECT COUNT(*) FROM merged_work_items) AS merged_pr_count,
+         (SELECT COUNT(*) FROM closed_unmerged_work_items) AS closed_unmerged_count,
+         CASE WHEN (SELECT COUNT(*) FROM merged_work_items) = 0 THEN NULL
+              ELSE (SELECT COALESCE(SUM(cost_equiv_u), 0) FROM merged_session_costs) * 1.0
+                   / (SELECT COUNT(*) FROM merged_work_items)
+         END AS cost_per_merged_pr_u,
+         (SELECT COUNT(*) FROM commit_sessions) AS commit_session_count,
+         CASE WHEN (SELECT COUNT(*) FROM commit_sessions) = 0 THEN NULL
+              ELSE (SELECT COALESCE(SUM(cost_equiv_u), 0) FROM commit_sessions) * 1.0
+                   / (SELECT COUNT(*) FROM commit_sessions)
+         END AS cost_per_commit_session_u,
+         CASE WHEN (SELECT COUNT(*) FROM in_window_sessions) = 0 THEN NULL
+              ELSE (SELECT COUNT(*)
+                      FROM in_window_sessions iws
+                     WHERE EXISTS (
+                       SELECT 1
+                         FROM session_work_links swl
+                         JOIN work_items wi ON wi.work_item_id = swl.work_item_id
+                        WHERE swl.session_id = iws.session_id${workItemFilter}
+                     )) * 100.0 / (SELECT COUNT(*) FROM in_window_sessions)
+         END AS linkage_coverage_pct`)
+        .get(...params);
+    const data = {
+        ...row,
+        n: row.merged_pr_count,
+        window: { from, to },
+    };
+    return buildResponse(data, {
+        claim_kind: "OBS_PROXY",
+        n: data.merged_pr_count,
+        window: { from, to },
+        qualification: {
+            provisional_excluded: false,
+            unpriced_turns: 0,
+            claim_kinds_count: 1,
+            note: "Directional (OBS_PROXY): survivorship bias (heavy-spend sessions that never open a PR are invisible); reviewer-dependence (merge is a human decision, not a quality guarantee); linkage-coverage cap (only linkage_coverage_pct% of in-window sessions are linked to a PR, so unlinked spend is excluded). cost_per_merged_pr_u uses lifecycle attribution: each merged PR carries the full cost of every linked session whenever it ran, so narrowing the window changes the PR population, not the per-PR cost.",
+        },
+        ...(workspaceId === null ? {} : { drilldown_ids: { workspace_id: workspaceId } }),
+    });
+}

package/dist/query/api/delivery.js

@@ -0,0 +1,92 @@
+/**
+ * src/query/api/delivery.ts — query-only L2a delivery metrics.
+ *
+ * Delivery is inferred from the presence of a harvested commit SHA; SHA values
+ * never leave the database through this query surface.
+ */
+import { buildResponse } from "../envelope.js";
+/**
+ * Derive delivery proxy metrics for sessions with turns in [from, to).
+ *
+ * Reconciled turns only contribute to money figures. Sessions without tool
+ * events still count in the total and total-spend denominator, but are neither
+ * commit nor abandoned sessions.
+ */
+export function getDeliveryMetrics(db, opts) {
+    const workspaceFilter = opts.workspaceId === null ? "" : " AND t.workspace_id = ?";
+    const params = opts.workspaceId === null ? [opts.from, opts.to] : [opts.from, opts.to, opts.workspaceId];
+    const row = db
+        .prepare(`WITH in_window_turns AS (
+         SELECT t.session_id, t.workspace_id, t.cost_equiv_u, t.provisional
+           FROM turns t
+          WHERE t.ts >= ? AND t.ts < ?${workspaceFilter}
+       ),
+       in_window_sessions AS (
+         SELECT DISTINCT session_id, workspace_id
+           FROM in_window_turns
+       ),
+       session_flags AS (
+         SELECT iws.session_id,
+                EXISTS (
+                  SELECT 1
+                    FROM tool_events te
+                   WHERE te.session_id = iws.session_id
+                     AND te.commit_sha IS NOT NULL
+                ) AS is_commit_session,
+                EXISTS (
+                  SELECT 1
+                    FROM tool_events te
+                   WHERE te.session_id = iws.session_id
+                     AND te.tool_name IN ('Bash', 'Write', 'Edit', 'NotebookEdit')
+                )
+                AND NOT EXISTS (
+                  SELECT 1
+                    FROM tool_events te
+                   WHERE te.session_id = iws.session_id
+                     AND te.commit_sha IS NOT NULL
+                ) AS is_abandoned_session
+           FROM in_window_sessions iws
+       ),
+       session_spend AS (
+         SELECT session_id,
+                COALESCE(SUM(CASE WHEN provisional = 0 THEN cost_equiv_u END), 0) AS spend_u
+           FROM in_window_turns
+          GROUP BY session_id
+       )
+       SELECT COALESCE(SUM(sf.is_commit_session), 0) AS commit_session_count,
+              COUNT(sf.session_id) AS total_session_count,
+              CASE WHEN COUNT(sf.session_id) = 0 THEN NULL
+                   ELSE SUM(sf.is_commit_session) * 1.0 / COUNT(sf.session_id)
+              END AS commit_session_rate,
+              CASE WHEN SUM(sf.is_commit_session) = 0 THEN NULL
+                   ELSE SUM(CASE WHEN sf.is_commit_session THEN ss.spend_u ELSE 0 END) * 1.0
+                        / SUM(sf.is_commit_session)
+              END AS spend_per_commit_session_u,
+              COALESCE(SUM(CASE WHEN sf.is_abandoned_session THEN ss.spend_u ELSE 0 END), 0)
+                AS abandoned_spend_u,
+              CASE WHEN COALESCE(SUM(ss.spend_u), 0) = 0 THEN NULL
+                   ELSE SUM(CASE WHEN sf.is_abandoned_session THEN ss.spend_u ELSE 0 END) * 1.0
+                        / SUM(ss.spend_u)
+              END AS abandoned_spend_share
+         FROM session_flags sf
+         JOIN session_spend ss USING (session_id)`)
+        .get(...params);
+    const data = {
+        ...row,
+        from: opts.from,
+        to: opts.to,
+        workspace_id: opts.workspaceId,
+    };
+    return buildResponse(data, {
+        claim_kind: "OBS_PROXY",
+        n: data.commit_session_count,
+        window: { from: opts.from, to: opts.to },
+        qualification: {
+            provisional_excluded: true,
+            unpriced_turns: 0,
+            claim_kinds_count: 1,
+            note: "Commit SHA presence is an observed delivery proxy.",
+        },
+        ...(opts.workspaceId === null ? {} : { drilldown_ids: { workspace_id: opts.workspaceId } }),
+    });
+}

package/dist/query/api/effectiveness.js

@@ -0,0 +1,254 @@
+/**
+ * src/query/api/effectiveness.ts — EF1 delivery-path and abandoned-spend metrics.
+ *
+ * These functions surface per-session delivery signals (turns to first commit,
+ * deep-abandoned classification) and split the RV9a abandoned spend by session
+ * depth. SEC-101: only counts, durations, booleans, and microUSD integers are
+ * returned — no transcript content, commit SHAs, or tool names.
+ */
+import { buildResponse } from "../envelope.js";
+// ---------------------------------------------------------------------------
+// computeSessionDelivery
+// ---------------------------------------------------------------------------
+/**
+ * Compute EF1 delivery signals for one session.
+ *
+ * firstCommitTs is the MIN(ts) from tool_events where commit_sha IS NOT NULL.
+ * turns_to_first_commit counts non-sidechain turns (is_sidechain=0) with ts <= firstCommitTs.
+ * deep_abandoned is true only for RECONCILED sessions with >= 10 user turns and no commit.
+ */
+export function computeSessionDelivery(db, sessionId) {
+    const commitRow = db
+        .prepare(`SELECT MIN(ts) AS first_commit_ts
+         FROM tool_events
+        WHERE session_id = ? AND commit_sha IS NOT NULL`)
+        .get(sessionId);
+    const firstCommitTs = commitRow.first_commit_ts;
+    let turns_to_first_commit = null;
+    if (firstCommitTs !== null) {
+        const countRow = db
+            .prepare(`SELECT COUNT(*) AS n
+           FROM turns
+          WHERE session_id = ? AND is_sidechain = 0 AND ts <= ?`)
+            .get(sessionId, firstCommitTs);
+        turns_to_first_commit = countRow.n;
+    }
+    const sessRow = db
+        .prepare("SELECT user_turn_count, state FROM sessions WHERE session_id = ?")
+        .get(sessionId);
+    const user_turn_count = sessRow?.user_turn_count ?? 0;
+    const state = sessRow?.state ?? "";
+    const deep_abandoned = user_turn_count >= 10 && firstCommitTs === null && state === "RECONCILED";
+    return { turns_to_first_commit, deep_abandoned };
+}
+// ---------------------------------------------------------------------------
+// getAbandonedSpendSplit
+// ---------------------------------------------------------------------------
+/**
+ * Split the RV9a abandoned spend into deep (>= 10 user turns) and early (< 10).
+ *
+ * Uses the exact same abandoned-session definition and window as
+ * getDeliveryMetrics so that deep + early === getDeliveryMetrics(...).abandoned_spend_u.
+ * Provisional turns are excluded from spend exactly as delivery does.
+ */
+export function getAbandonedSpendSplit(db, opts) {
+    const workspaceFilter = opts.workspaceId === null ? "" : " AND t.workspace_id = ?";
+    const params = opts.workspaceId === null ? [opts.from, opts.to] : [opts.from, opts.to, opts.workspaceId];
+    const row = db
+        .prepare(`WITH in_window_turns AS (
+         SELECT t.session_id, t.workspace_id, t.cost_equiv_u, t.provisional
+           FROM turns t
+          WHERE t.ts >= ? AND t.ts < ?${workspaceFilter}
+       ),
+       in_window_sessions AS (
+         SELECT DISTINCT session_id, workspace_id
+           FROM in_window_turns
+       ),
+       session_flags AS (
+         SELECT iws.session_id,
+                EXISTS (
+                  SELECT 1
+                    FROM tool_events te
+                   WHERE te.session_id = iws.session_id
+                     AND te.commit_sha IS NOT NULL
+                ) AS is_commit_session,
+                EXISTS (
+                  SELECT 1
+                    FROM tool_events te
+                   WHERE te.session_id = iws.session_id
+                     AND te.tool_name IN ('Bash', 'Write', 'Edit', 'NotebookEdit')
+                )
+                AND NOT EXISTS (
+                  SELECT 1
+                    FROM tool_events te
+                   WHERE te.session_id = iws.session_id
+                     AND te.commit_sha IS NOT NULL
+                ) AS is_abandoned_session
+           FROM in_window_sessions iws
+       ),
+       session_spend AS (
+         SELECT session_id,
+                COALESCE(SUM(CASE WHEN provisional = 0 THEN cost_equiv_u END), 0) AS spend_u
+           FROM in_window_turns
+          GROUP BY session_id
+       )
+       SELECT
+         COALESCE(SUM(
+           CASE WHEN sf.is_abandoned_session AND s.user_turn_count >= 10
+                THEN ss.spend_u ELSE 0 END
+         ), 0) AS deep_abandoned_spend_u,
+         COALESCE(SUM(
+           CASE WHEN sf.is_abandoned_session AND s.user_turn_count < 10
+                THEN ss.spend_u ELSE 0 END
+         ), 0) AS early_abandoned_spend_u
+         FROM session_flags sf
+         JOIN session_spend ss USING (session_id)
+         JOIN sessions s USING (session_id)`)
+        .get(...params);
+    return {
+        deep_abandoned_spend_u: row.deep_abandoned_spend_u,
+        early_abandoned_spend_u: row.early_abandoned_spend_u,
+    };
+}
+/**
+ * Classify all no-commit RECONCILED sessions and return an aggregate proxy.
+ *
+ * A no-commit session S (state='RECONCILED', no tool_events.commit_sha):
+ *   - PENDING  : now < last_turn_at + windowHours (window not elapsed yet)
+ *   - UNRESOLVED: matured AND another session S' in the same workspace has
+ *                  first_turn_at in (last_turn_at, last_turn_at + windowHours]
+ *   - RESOLVED  : matured AND no such follow-up session found
+ *   - EXCLUDED  : session has a commit (not counted in no_commit_session_count)
+ *
+ * Time arithmetic uses Date.parse on ISO strings; Date.now() is never called.
+ */
+export function getClosureProxy(db, opts) {
+    const windowHours = opts.windowHours ?? 48;
+    const nowMs = Date.parse(opts.now);
+    const windowMs = windowHours * 3600 * 1000;
+    const note = `Directional: a re-open within ${windowHours}h may be unrelated work; burst-working operators will false-flag as unresolved. PENDING until the window elapses.`;
+    const workspaceFilter = opts.workspaceId === null ? "" : " AND s.workspace_id = ?";
+    const params = opts.workspaceId === null ? [] : [opts.workspaceId];
+    const candidates = db
+        .prepare(`SELECT s.session_id, s.workspace_id, s.last_turn_at
+         FROM sessions s
+        WHERE s.state = 'RECONCILED'
+          AND s.last_turn_at IS NOT NULL
+          AND NOT EXISTS (
+            SELECT 1 FROM tool_events te
+             WHERE te.session_id = s.session_id AND te.commit_sha IS NOT NULL
+          )${workspaceFilter}`)
+        .all(...params);
+    const emptyProxy = () => ({
+        no_commit_session_count: 0,
+        resolved_count: 0,
+        unresolved_count: 0,
+        pending_count: 0,
+        resolved_share: null,
+        window_hours: windowHours,
+        workspace_id: opts.workspaceId,
+    });
+    if (candidates.length === 0) {
+        return buildResponse(emptyProxy(), {
+            claim_kind: "EXPERIMENTAL",
+            n: 0,
+            window: { from: opts.now, to: opts.now },
+            qualification: { provisional_excluded: false, unpriced_turns: 0, claim_kinds_count: 1, note },
+            ...(opts.workspaceId === null ? {} : { drilldown_ids: { workspace_id: opts.workspaceId } }),
+        });
+    }
+    // Fetch all sessions in the candidate workspaces for the follow-up check.
+    const uniqueWsIds = [...new Set(candidates.map((c) => c.workspace_id))];
+    const placeholders = uniqueWsIds.map(() => "?").join(",");
+    const wsSessions = db
+        .prepare(`SELECT session_id, workspace_id, first_turn_at
+         FROM sessions
+        WHERE workspace_id IN (${placeholders}) AND first_turn_at IS NOT NULL`)
+        .all(...uniqueWsIds);
+    const byWs = new Map();
+    for (const s of wsSessions) {
+        const arr = byWs.get(s.workspace_id) ?? [];
+        arr.push(s);
+        byWs.set(s.workspace_id, arr);
+    }
+    let resolved_count = 0;
+    let unresolved_count = 0;
+    let pending_count = 0;
+    for (const c of candidates) {
+        const lastMs = Date.parse(c.last_turn_at);
+        const matured = nowMs >= lastMs + windowMs;
+        if (!matured) {
+            pending_count++;
+            continue;
+        }
+        const siblings = byWs.get(c.workspace_id) ?? [];
+        const reopened = siblings.some((s2) => {
+            if (s2.session_id === c.session_id)
+                return false;
+            const s2Ms = Date.parse(s2.first_turn_at);
+            return s2Ms > lastMs && s2Ms <= lastMs + windowMs;
+        });
+        if (reopened) {
+            unresolved_count++;
+        }
+        else {
+            resolved_count++;
+        }
+    }
+    const no_commit_session_count = resolved_count + unresolved_count + pending_count;
+    const maturedCount = resolved_count + unresolved_count;
+    const resolved_share = maturedCount === 0 ? null : resolved_count / maturedCount;
+    const proxy = {
+        no_commit_session_count,
+        resolved_count,
+        unresolved_count,
+        pending_count,
+        resolved_share,
+        window_hours: windowHours,
+        workspace_id: opts.workspaceId,
+    };
+    return buildResponse(proxy, {
+        claim_kind: "EXPERIMENTAL",
+        n: no_commit_session_count,
+        window: { from: opts.now, to: opts.now },
+        qualification: { provisional_excluded: false, unpriced_turns: 0, claim_kinds_count: 1, note },
+        ...(opts.workspaceId === null ? {} : { drilldown_ids: { workspace_id: opts.workspaceId } }),
+    });
+}
+/**
+ * Per-session closure status for drill-down.
+ *
+ * Same logic as getClosureProxy but for a single session.
+ * Time arithmetic uses Date.parse on ISO strings; Date.now() is never called.
+ */
+export function getSessionClosureStatus(db, sessionId, opts) {
+    const windowHours = opts.windowHours ?? 48;
+    const windowMs = windowHours * 3600 * 1000;
+    // A session with any commit is EXCLUDED from the no-commit classification.
+    const hasCommit = db
+        .prepare("SELECT 1 FROM tool_events WHERE session_id = ? AND commit_sha IS NOT NULL LIMIT 1")
+        .get(sessionId);
+    if (hasCommit)
+        return "EXCLUDED";
+    const sess = db
+        .prepare("SELECT workspace_id, last_turn_at, state FROM sessions WHERE session_id = ?")
+        .get(sessionId);
+    // If the session is missing or not a RECONCILED no-commit session, it cannot mature.
+    if (!sess || sess.state !== "RECONCILED" || sess.last_turn_at === null)
+        return "PENDING";
+    const nowMs = Date.parse(opts.now);
+    const lastMs = Date.parse(sess.last_turn_at);
+    const matured = nowMs >= lastMs + windowMs;
+    if (!matured)
+        return "PENDING";
+    const followups = db
+        .prepare(`SELECT session_id, first_turn_at FROM sessions
+        WHERE workspace_id = ? AND session_id != ?
+          AND first_turn_at IS NOT NULL AND first_turn_at > ?`)
+        .all(sess.workspace_id, sessionId, sess.last_turn_at);
+    const reopened = followups.some((s2) => {
+        const s2Ms = Date.parse(s2.first_turn_at);
+        return s2Ms > lastMs && s2Ms <= lastMs + windowMs;
+    });
+    return reopened ? "UNRESOLVED" : "RESOLVED";
+}

package/dist/query/api/efficiency-headroom.js

@@ -0,0 +1,74 @@
+/**
+ * src/query/api/efficiency-headroom.ts — BM2 efficiency headroom.
+ *
+ * "How far am I from my own modeled ceiling?" — the sum of modeled weekly
+ * savings across the OPEN recommendations (state PROPOSED or ADOPTED, non-null
+ * savings) expressed as a fraction of the trailing-7d actual spend.
+ *
+ * Honesty contract: this is a MODELED ceiling built from unvalidated per-detector
+ * fractions (e.g. D6's avoidance fraction is UNVALIDATED). It is "modeled headroom
+ * — if every open recommendation were applied", never a "$X wasted" headline
+ * (INT-5). The frozen envelope has no MODELED ClaimKind, so it rides as
+ * EXPERIMENTAL with the caveat carried in the qualification note.
+ *
+ * FR-REC-103 is respected: this is a SEPARATE surface from listRecommendations,
+ * which still never sums modeled savings into an "achieved" total.
+ *
+ * SEC-101: sums of existing aggregates (recommendations.modeled_savings_u_per_wk,
+ * turns.cost_equiv_u) only — no transcript content.
+ */
+import { buildResponse } from "../envelope.js";
+/**
+ * Compute the efficiency-headroom ratio over [from, to). The headroom numerator
+ * is window-independent (it sums the current open recommendation set); the
+ * denominator is the actual spend in the window (default trailing 7d).
+ */
+export function getEfficiencyHeadroom(db, opts) {
+    const { from, to } = opts;
+    const recs = db
+        .prepare(`SELECT COALESCE(SUM(modeled_savings_u_per_wk), 0) AS sum_u,
+              COUNT(modeled_savings_u_per_wk) AS with_savings,
+              COUNT(*) AS open_total
+         FROM recommendations
+        WHERE state IN ('PROPOSED', 'ADOPTED')`)
+        .get();
+    const spend = db
+        .prepare(`SELECT COALESCE(SUM(cost_equiv_u), 0) AS actual_u
+         FROM turns
+        WHERE ts >= ? AND ts < ? AND provisional = 0`)
+        .get(from, to);
+    const headroom_u_per_wk = recs.sum_u ?? 0;
+    const actual_u_per_wk = spend.actual_u;
+    const openRecsExist = recs.open_total > 0;
+    // Null when: no spend (avoid /0 → ∞/NaN), or open recs exist but none carries a
+    // savings figure (an all-null modeled set is not a defensible ceiling).
+    let headroom_pct;
+    if (actual_u_per_wk === 0) {
+        headroom_pct = null;
+    }
+    else if (openRecsExist && recs.with_savings === 0) {
+        headroom_pct = null;
+    }
+    else {
+        headroom_pct = headroom_u_per_wk / actual_u_per_wk;
+    }
+    const data = {
+        headroom_u_per_wk,
+        actual_u_per_wk,
+        headroom_pct,
+        open_rec_count: recs.with_savings,
+        from,
+        to,
+    };
+    return buildResponse(data, {
+        claim_kind: "EXPERIMENTAL",
+        n: recs.with_savings,
+        window: { from, to },
+        qualification: {
+            provisional_excluded: true,
+            unpriced_turns: 0,
+            claim_kinds_count: 1,
+            note: "Modeled headroom — if every open recommendation were applied; built from unvalidated per-detector fractions.",
+        },
+    });
+}

package/dist/query/api/headroom-trend.js

@@ -0,0 +1,105 @@
+/**
+ * src/query/api/headroom-trend.ts — percent-native headroom over time.
+ *
+ * This is an additive query-side view over the calibrated limit and the two
+ * cap-read coefficient regimes. It deliberately does not introduce an
+ * absolute-cap denominator: the configured limit is the only denominator.
+ */
+import { DEFAULT_CAP_READ_COEFF } from "../cap-weighted.js";
+import { getQueryDb } from "../db-context.js";
+import { buildResponse } from "../envelope.js";
+import { capWeightedByBucket } from "../trends.js";
+const UPPER_BOUND_COEFF = 1.0;
+const CAVEAT_NOTE = "Percent-native headroom (no absolute-cap denominator); cap coefficient is unverified.";
+const PRESET_DAYS = {
+    "24h": 1,
+    "7d": 7,
+    "30d": 30,
+};
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+function configGet(db, key) {
+    const row = db.prepare("SELECT value FROM user_config WHERE key = ?").get(key);
+    return row?.value ?? null;
+}
+function resolveWindow(filter, now = new Date()) {
+    const nowIso = now.toISOString();
+    if (filter.preset !== undefined) {
+        const from = new Date(now.getTime() - PRESET_DAYS[filter.preset] * MS_PER_DAY).toISOString();
+        return { from, to: nowIso, preset: filter.preset };
+    }
+    if (filter.from !== undefined && filter.to !== undefined) {
+        return { from: filter.from, to: filter.to };
+    }
+    if (filter.from !== undefined) {
+        return { from: filter.from, to: nowIso };
+    }
+    if (filter.to !== undefined) {
+        const from = new Date(new Date(filter.to).getTime() - 7 * MS_PER_DAY).toISOString();
+        return { from, to: filter.to };
+    }
+    const from = new Date(now.getTime() - 7 * MS_PER_DAY).toISOString();
+    return { from, to: nowIso, preset: "7d" };
+}
+function readLimitTokens(db) {
+    const limitRaw = configGet(db, "limit_tokens");
+    if (limitRaw === null)
+        return null;
+    const limit = Number(limitRaw);
+    return Number.isFinite(limit) && limit > 0 ? limit : null;
+}
+/**
+ * Return percent-native headroom against the calibrated limit for each trend
+ * bucket, using both the 0.1× headline and 1.0× upper-bound cap regimes.
+ */
+export function getHeadroomTrend(filter, bucket = "day", workspaceId) {
+    const db = getQueryDb();
+    const window = resolveWindow(filter);
+    const limitTokens = readLimitTokens(db);
+    if (limitTokens === null) {
+        return buildResponse({ state: "NO_LIMIT" }, {
+            claim_kind: "LIST_EQUIV",
+            n: 0,
+            window,
+            qualification: {
+                provisional_excluded: true,
+                unpriced_turns: 0,
+                claim_kinds_count: 1,
+                note: CAVEAT_NOTE,
+            },
+        });
+    }
+    const headlineRows = capWeightedByBucket(db, window.from, window.to, bucket, DEFAULT_CAP_READ_COEFF, workspaceId);
+    const upperRows = capWeightedByBucket(db, window.from, window.to, bucket, UPPER_BOUND_COEFF, workspaceId);
+    const headlineByBucket = new Map(headlineRows.map((row) => [row.bucket, row]));
+    const upperByBucket = new Map(upperRows.map((row) => [row.bucket, row]));
+    const bucketKeys = new Set([...headlineByBucket.keys(), ...upperByBucket.keys()]);
+    const points = [...bucketKeys].sort().map((bucketKey) => {
+        const capWeightedHeadline = headlineByBucket.get(bucketKey)?.cap_weighted_tokens ?? 0;
+        const capWeightedUpper = upperByBucket.get(bucketKey)?.cap_weighted_tokens ?? 0;
+        return {
+            bucket: bucketKey,
+            headroom_headline: (limitTokens - capWeightedHeadline) / limitTokens,
+            headroom_upper: (limitTokens - capWeightedUpper) / limitTokens,
+            cap_weighted_headline: capWeightedHeadline,
+            cap_weighted_upper: capWeightedUpper,
+        };
+    });
+    return buildResponse({
+        state: "OK",
+        bucket,
+        points,
+        cap_read_coeff_headline: DEFAULT_CAP_READ_COEFF,
+        cap_read_coeff_upper: UPPER_BOUND_COEFF,
+        coefficient_unverified: true,
+    }, {
+        claim_kind: "LIST_EQUIV",
+        n: points.length,
+        window,
+        qualification: {
+            provisional_excluded: true,
+            unpriced_turns: 0,
+            claim_kinds_count: 1,
+            note: CAVEAT_NOTE,
+        },
+    });
+}