agentwrangler 0.1.0

package/dist/query/api/spend-flavor.js

@@ -0,0 +1,234 @@
+/**
+ * src/query/api/spend-flavor.ts — Token-flavor decomposition + cache efficiency.
+ *
+ * Surface 1 (§1): getFlavorDecomposition() — breakdown by token flavor with cap-proxy weights.
+ * Surface 2 (§2): getCacheEfficiency() — cache read:write ratio diagnostic.
+ *
+ * Subscription cap-proxy weights displayed:
+ *   fresh input        1×
+ *   output             1×
+ *   cache writes       1×
+ *   cache read         0.1× (UNVERIFIED coefficient)
+ *
+ * API list-equivalent dollars remain a separate pricing-snapshot metric. This view
+ * deliberately reconciles to capWeightedTokens(); it does not pretend that output
+ * tokens share the model's input price or apply API write premiums to a subscription cap.
+ *
+ * Vocabulary: docs/plans/blog-dashboard-taxonomy-IA.md §1a
+ */
+import { capWeightedTokens, resolveCapReadCoeff } from "../cap-weighted.js";
+import { getQueryDb } from "../db-context.js";
+import { buildResponse } from "../envelope.js";
+/** Display labels — verbatim from taxonomy §1a / A1 §04 */
+const FLAVOR_LABELS = {
+    fresh_input: "fresh input",
+    output: "output (incl. thinking)",
+    cache_write_5m: "cache write (5 min)",
+    cache_write_1h: "cache write (1 hr)",
+    cache_write_other: "cache write (unspecified)",
+    cache_read: "cache read",
+};
+/** Cap-proxy weights. API prices are intentionally not represented by this chart. */
+const CAP_WEIGHTS = {
+    fresh_input: 1.0,
+    output: 1.0,
+    cache_write_5m: 1.0,
+    cache_write_1h: 1.0,
+    cache_write_other: 1.0,
+    cache_read: 0.1, // default; overridden by coeff at runtime
+};
+// ---------------------------------------------------------------------------
+// Reuse-band logic
+// ---------------------------------------------------------------------------
+/**
+ * Classify raw cache read:creation values without assigning a health label.
+ * A zero creation denominator remains distinct from no data and reuse dominance.
+ */
+export function classifyCacheReuseBand(cacheReadTokens, cacheCreationTokens, turns) {
+    if (turns === 0)
+        return "NO_DATA";
+    if (cacheCreationTokens === 0)
+        return "NO_DENOMINATOR";
+    const readToCreation = cacheReadTokens / cacheCreationTokens;
+    if (readToCreation < 1)
+        return "WRITE_HEAVY";
+    if (readToCreation < 4)
+        return "MIXED_REUSE";
+    return "REUSE_DOMINANT";
+}
+/** @deprecated Use classifyCacheReuseBand with raw counts and turns. */
+export const classifyCacheEfficiency = classifyCacheReuseBand;
+// ---------------------------------------------------------------------------
+// Window resolution (matches the pattern in trends.ts)
+// ---------------------------------------------------------------------------
+const PRESET_DAYS = {
+    "24h": 1,
+    "7d": 7,
+    "30d": 30,
+};
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+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" };
+}
+const FLAVOR_SQL = `
+  SELECT
+    COALESCE(SUM(input_tokens), 0)                              AS raw_input,
+    COALESCE(SUM(output_tokens), 0)                             AS raw_output,
+    COALESCE(SUM(cache_write_5m), 0)                            AS raw_cw5m,
+    COALESCE(SUM(cache_write_1h), 0)                            AS raw_cw1h,
+    COALESCE(SUM(cache_write_other), 0)                         AS raw_cw_other,
+    COALESCE(SUM(cache_read_tokens), 0)                         AS raw_cr,
+    COUNT(*)                                                    AS turns
+  FROM turns
+  WHERE ts >= ? AND ts < ? AND provisional = 0
+`;
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+function buildFlavors(agg, coeff) {
+    const raws = {
+        fresh_input: agg.raw_input,
+        output: agg.raw_output,
+        cache_write_5m: agg.raw_cw5m,
+        cache_write_1h: agg.raw_cw1h,
+        cache_write_other: agg.raw_cw_other,
+        cache_read: agg.raw_cr,
+    };
+    const weights = {
+        ...CAP_WEIGHTS,
+        cache_read: coeff, // override with resolved coeff
+    };
+    const totalRaw = Object.values(raws).reduce((s, v) => s + v, 0);
+    const totalWeighted = Object.keys(raws).reduce((s, k) => s + raws[k] * weights[k], 0);
+    const keys = [
+        "fresh_input",
+        "output",
+        "cache_write_5m",
+        "cache_write_1h",
+        "cache_write_other",
+        "cache_read",
+    ];
+    return keys.map((flavor) => {
+        const raw_tokens = raws[flavor];
+        const weight = weights[flavor];
+        const weighted_tokens = raw_tokens * weight;
+        return {
+            flavor,
+            label: FLAVOR_LABELS[flavor],
+            weight,
+            raw_tokens,
+            weighted_tokens,
+            weighted_share: totalWeighted > 0 ? weighted_tokens / totalWeighted : 0,
+            raw_share: totalRaw > 0 ? raw_tokens / totalRaw : 0,
+        };
+    });
+}
+// ---------------------------------------------------------------------------
+// Public API methods
+// ---------------------------------------------------------------------------
+/**
+ * Token-flavor decomposition over a window.
+ *
+ * Endpoint: GET /api/overview/flavor?preset=7d
+ *
+ * claim_kind: PROXY (reconciled turns only, provisional=0).
+ *
+ * Internal reconciliation: total_weighted_tokens === SUM(flavors[].weighted_tokens).
+ * total_weighted_tokens uses the same cap-proxy weights as capWeightedTokens().
+ */
+export function getFlavorDecomposition(filter) {
+    const db = getQueryDb();
+    const win = resolveWindow(filter);
+    const { from, to } = win;
+    const coeff = resolveCapReadCoeff(db);
+    const agg = db.prepare(FLAVOR_SQL).get(from, to);
+    const flavors = buildFlavors(agg, coeff);
+    const total_raw_tokens = flavors.reduce((s, f) => s + f.raw_tokens, 0);
+    const total_weighted_tokens = flavors.reduce((s, f) => s + f.weighted_tokens, 0);
+    const cacheCreation = agg.raw_cw5m + agg.raw_cw1h + agg.raw_cw_other;
+    const cacheTotal = agg.raw_cr + cacheCreation;
+    const cache_efficiency_ratio = cacheTotal > 0 ? agg.raw_cr / cacheTotal : null;
+    const capRow = capWeightedTokens(db, { fromIso: from, toIso: to, coeff })[0];
+    const data = {
+        flavors,
+        total_raw_tokens,
+        total_weighted_tokens,
+        cache_efficiency_ratio,
+        cache_read_share: cache_efficiency_ratio,
+        cache_read_tokens: agg.raw_cr,
+        cache_creation_tokens: cacheCreation,
+        reuse_band: classifyCacheReuseBand(agg.raw_cr, cacheCreation, agg.turns),
+        cap_weighted_tokens: capRow?.cap_weighted_tokens ?? 0,
+        coeff_used: coeff,
+        coeff_unverified: true,
+        turns: agg.turns,
+    };
+    return buildResponse(data, {
+        claim_kind: "PROXY",
+        n: 6,
+        window: win,
+        qualification: {
+            provisional_excluded: true,
+            unpriced_turns: 0,
+            claim_kinds_count: 1,
+            note: "",
+        },
+    });
+}
+/**
+ * Cache read:write efficiency KPI over a window.
+ *
+ * Derives from capWeightedTokens() — no additional SQL.
+ * Uses raw token counts (not pricing-weighted) so the ratio is exact.
+ *
+ * Endpoint: GET /api/overview/flavor (embedded in FlavorDecomposition).
+ * Also exported as a standalone function for independent use.
+ */
+export function getCacheEfficiency(filter) {
+    const db = getQueryDb();
+    const win = resolveWindow(filter);
+    const { from, to } = win;
+    const rows = capWeightedTokens(db, { fromIso: from, toIso: to });
+    const row = rows[0];
+    const cache_read_tokens = row?.cache_read_tokens ?? 0;
+    const cache_creation_tokens = row?.cache_creation_tokens ?? 0;
+    const cacheTotal = cache_read_tokens + cache_creation_tokens;
+    const ratio = cacheTotal > 0 ? cache_read_tokens / cacheTotal : null;
+    const data = {
+        ratio,
+        cache_read_tokens,
+        cache_creation_tokens,
+        reuse_band: classifyCacheReuseBand(cache_read_tokens, cache_creation_tokens, row?.turns ?? 0),
+        cap_weighted_tokens: row?.cap_weighted_tokens ?? 0,
+        coeff_used: resolveCapReadCoeff(db),
+        coeff_unverified: true,
+        turns: row?.turns ?? 0,
+    };
+    return buildResponse(data, {
+        claim_kind: "PROXY",
+        n: 1,
+        window: win,
+        qualification: {
+            provisional_excluded: true,
+            unpriced_turns: 0,
+            claim_kinds_count: 1,
+            note: "",
+        },
+    });
+}

package/dist/query/api/trends.js

@@ -0,0 +1,155 @@
+/**
+ * src/query/api/trends.ts — LocalQueryAPI: spend-over-time trends method.
+ *
+ * Mirrors the window resolution and response-building pattern in overview.ts.
+ * The FROZEN overview contract (api/index.ts) is not modified by this file.
+ */
+import { resolveCapReadCoeff } from "../cap-weighted.js";
+import { getQueryDb } from "../db-context.js";
+import { buildResponse } from "../envelope.js";
+import { cacheWriteByBucket, capWeightedByBucket, sessionCostSeries, spendByBucket, spendByBucketAndModel, spendByBucketAndWorkspace, } from "../trends.js";
+import { cachedQuery } from "./overview.js";
+/**
+ * Detect spike buckets: mean + 2 × population stddev.
+ * Returns empty set when fewer than 3 buckets (insufficient baseline).
+ */
+export function detectSpikes(rows) {
+    if (rows.length < 3)
+        return new Set();
+    const vals = rows.map((r) => r.cache_creation_tokens);
+    const mean = vals.reduce((s, v) => s + v, 0) / vals.length;
+    const variance = vals.reduce((s, v) => s + (v - mean) ** 2, 0) / vals.length;
+    const stddev = Math.sqrt(variance);
+    const threshold = mean + 2 * stddev;
+    return new Set(rows.filter((r) => r.cache_creation_tokens > threshold).map((r) => r.bucket));
+}
+// ---------------------------------------------------------------------------
+// Internal helpers (mirrors overview.ts pattern, not re-exported from index)
+// ---------------------------------------------------------------------------
+const PRESET_DAYS = {
+    "24h": 1,
+    "7d": 7,
+    "30d": 30,
+};
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+function adoptionBucketExpr(bucket) {
+    if (bucket === "day")
+        return "date(adopted_at, 'localtime')";
+    if (bucket === "week")
+        return "strftime('%Y-%W', adopted_at)";
+    return "strftime('%Y-%m', adopted_at)";
+}
+function adoptionMarkers(db, from, to, bucket, workspaceId) {
+    const bucketSql = adoptionBucketExpr(bucket);
+    const base = `SELECT rec_id, detector_id, lever, adopted_at, ${bucketSql} AS bucket
+                  FROM recommendations
+                 WHERE adopted_at IS NOT NULL
+                   AND adopted_at >= ? AND adopted_at < ?
+                   AND state IN ('ADOPTED', 'MEASURING', 'MEASURED_EFFECTIVE',
+                                 'MEASURED_NO_EFFECT')`;
+    const tail = "ORDER BY adopted_at ASC, rec_id ASC";
+    if (workspaceId !== undefined) {
+        return db
+            .prepare(`${base} AND scope_workspace_id = ? ${tail}`)
+            .all(from, to, workspaceId);
+    }
+    return db.prepare(`${base} ${tail}`).all(from, to);
+}
+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" };
+}
+// ---------------------------------------------------------------------------
+// Public API method
+// ---------------------------------------------------------------------------
+/**
+ * Cache-write spike timeline over a window.
+ *
+ * Endpoint: GET /api/trends/cache-write?preset=7d&bucket=day
+ *
+ * Reconciliation: SUM(data.buckets[].cache_creation_tokens) equals
+ * cache_creation_tokens from capWeightedTokens() for the same window.
+ *
+ * spike_buckets: server-computed via detectSpikes() (mean + 2σ).
+ * Skipped when < 3 buckets in the window.
+ */
+export function getCacheWriteTrend(filter, bucket = "day", workspaceId) {
+    const db = getQueryDb();
+    const win = resolveWindow(filter);
+    const { from, to } = win;
+    const buckets = cacheWriteByBucket(db, from, to, bucket, workspaceId);
+    const spikes = detectSpikes(buckets);
+    const data = {
+        buckets,
+        spike_buckets: [...spikes],
+    };
+    return buildResponse(data, {
+        claim_kind: "LIST_EQUIV",
+        n: buckets.length,
+        window: win,
+        qualification: {
+            provisional_excluded: true,
+            unpriced_turns: 0,
+            claim_kinds_count: 1,
+            note: "",
+        },
+    });
+}
+/**
+ * Fetch spend-over-time data grouped by the requested bucket size.
+ *
+ * Endpoint: GET /api/trends?preset=&bucket=day|week|month&workspace_id=
+ *
+ * Reconciliation: SUM(data.buckets[].cost_equiv_u) equals the cost_equiv_u
+ * returned by GET /api/overview for the same window (both exclude provisional).
+ */
+export function getTrends(filter, bucket = "day", workspaceId) {
+    const db = getQueryDb();
+    const win = resolveWindow(filter);
+    const { from, to } = win;
+    const coeff = cachedQuery(db, "resolveCapReadCoeff", from, to, workspaceId, () => resolveCapReadCoeff(db));
+    const buckets = cachedQuery(db, `spendByBucket:${bucket}`, from, to, workspaceId, () => spendByBucket(db, from, to, bucket, workspaceId));
+    const by_model = cachedQuery(db, `spendByBucketAndModel:${bucket}`, from, to, workspaceId, () => spendByBucketAndModel(db, from, to, bucket, workspaceId));
+    const by_workspace = workspaceId === undefined
+        ? cachedQuery(db, `spendByBucketAndWorkspace:${bucket}`, from, to, undefined, () => spendByBucketAndWorkspace(db, from, to, bucket))
+        : [];
+    const sessions = cachedQuery(db, "sessionCostSeries", from, to, workspaceId, () => sessionCostSeries(db, from, to, workspaceId));
+    const cap_weighted = cachedQuery(db, `capWeightedByBucket:${bucket}`, from, to, workspaceId, () => capWeightedByBucket(db, from, to, bucket, coeff, workspaceId));
+    const adoption_markers = cachedQuery(db, `adoptionMarkers:${bucket}`, from, to, workspaceId, () => adoptionMarkers(db, from, to, bucket, workspaceId));
+    const data = {
+        bucket,
+        buckets,
+        by_model,
+        by_workspace,
+        sessions,
+        cap_weighted,
+        cap_read_coeff: coeff,
+        adoption_markers,
+    };
+    return buildResponse(data, {
+        claim_kind: "LIST_EQUIV",
+        n: buckets.length,
+        window: win,
+        qualification: {
+            provisional_excluded: true,
+            unpriced_turns: 0,
+            claim_kinds_count: 1,
+            note: "",
+        },
+    });
+}

package/dist/query/cap-weighted.js

@@ -0,0 +1,119 @@
+/**
+ * src/query/cap-weighted.ts — cap-weighted token meter (Data Model v2 §2A).
+ *
+ * A single scalar that estimates a turn's draw on the *rate-limit cap* (not its
+ * dollar cost). It exists because the frozen `context_tokens` generated column
+ * and the §2 spend rollups sum `input + cache_read + cache_write_*` at FULL
+ * weight, which over-counts cache reads ~10× for cap attribution (economics
+ * brief verdict A2). This module is ADDITIVE and QUERY-SIDE: it never alters
+ * `context_tokens` (frozen) and adds nothing to the schema.
+ *
+ *   cap_weighted_tokens
+ *     =  full(cache_write_5m + cache_write_1h + cache_write_other)  -- cache CREATES: full weight
+ *     +  COEFF × cache_read_tokens                                  -- cached re-reads: ~0.1× (unverified)
+ *     +  full(input_tokens + output_tokens)                        -- fresh input + generation: full weight
+ *
+ * COEFF lives in `user_config.cap_read_coeff` (TEXT; cast to REAL), default 0.1,
+ * carrying a visible "unverified" caveat wherever a cap-weighted figure is
+ * surfaced. Both regimes ship — 0.1× (default) and 1.0× (upper bound) — selected
+ * at runtime by passing `coeff` explicitly.
+ *
+ * The weighting expression is exported once (`capWeightExprSql` / `capWeightForTurn`)
+ * so the D8/D6/D9 detectors reuse a single source of truth instead of re-deriving it.
+ */
+/**
+ * Default cap-read coefficient. UNVERIFIED — Anthropic has not published a cap
+ * coefficient for cache reads. Surface the caveat wherever a cap-weighted figure
+ * is shown. Callers may override with the 1.0× upper-bound regime.
+ */
+export const DEFAULT_CAP_READ_COEFF = 0.1;
+/**
+ * Resolve the cap-read coefficient from `user_config.cap_read_coeff`.
+ * Falls back to DEFAULT_CAP_READ_COEFF when the row is absent or unparseable
+ * (mirrors the `limit_tokens` read pattern — config rows are not seeded by a
+ * migration, callers default). Never throws.
+ */
+export function resolveCapReadCoeff(db) {
+    const row = db.prepare("SELECT value FROM user_config WHERE key = 'cap_read_coeff'").get();
+    if (!row || row.value === null)
+        return DEFAULT_CAP_READ_COEFF;
+    // Treat empty/whitespace-only as absent.
+    const trimmed = row.value.trim();
+    if (trimmed === "")
+        return DEFAULT_CAP_READ_COEFF;
+    const n = Number(trimmed);
+    // Valid range: (0, 1] — a cap-read weight can't be ≤0 or exceed full weight.
+    if (!Number.isFinite(n) || n <= 0 || n > 1)
+        return DEFAULT_CAP_READ_COEFF;
+    return n;
+}
+/**
+ * The per-turn cap-weighted token SQL expression for a `turns` row aliased `alias`.
+ * `coeff` is validated and inlined as a numeric literal so callers keep using
+ * anonymous `?` params for their own predicates (better-sqlite3 forbids mixing
+ * named and anonymous params in one statement). Deliberately NOT `context_tokens`.
+ */
+export function capWeightExprSql(alias, coeff) {
+    if (!Number.isFinite(coeff)) {
+        throw new Error(`capWeightExprSql: coeff must be finite, got ${coeff}`);
+    }
+    return (`((${alias}.cache_write_5m + ${alias}.cache_write_1h + ${alias}.cache_write_other)` +
+        ` + ${coeff} * ${alias}.cache_read_tokens` +
+        ` + (${alias}.input_tokens + ${alias}.output_tokens))`);
+}
+/** Pure JS mirror of the SQL expression — for unit tests and in-memory callers. */
+export function capWeightForTurn(t, coeff) {
+    return (t.cache_write_5m +
+        t.cache_write_1h +
+        t.cache_write_other +
+        coeff * t.cache_read_tokens +
+        (t.input_tokens + t.output_tokens));
+}
+/** Whitelisted GROUP BY dimensions (guards against SQL injection via `groupBy`). */
+const GROUP_COLUMNS = {
+    workspace_id: "t.workspace_id",
+    session_id: "t.session_id",
+    model: "t.model",
+};
+/**
+ * Cap-weighted tokens over [fromIso, toIso), optionally grouped by
+ * workspace_id / session_id / model. Reads the raw usage fields directly; never
+ * references `context_tokens`. Returns a single group=null row when `groupBy` is
+ * omitted. This is the entry point T5/T6/T2 consume.
+ */
+export function capWeightedTokens(db, opts) {
+    const coeff = opts.coeff ?? resolveCapReadCoeff(db);
+    const expr = capWeightExprSql("t", coeff);
+    const groupCol = opts.groupBy ? GROUP_COLUMNS[opts.groupBy] : null;
+    const selectGroup = groupCol ?? "NULL";
+    const provClause = opts.includeProvisional ? "" : "AND t.provisional = 0";
+    const groupByClause = groupCol ? `GROUP BY ${groupCol}` : "";
+    const rows = db
+        .prepare(`SELECT ${selectGroup}                                            AS "group",
+              SUM(${expr})                                              AS cap_weighted_raw,
+              COALESCE(SUM(t.cache_write_5m + t.cache_write_1h
+                           + t.cache_write_other), 0)                   AS cache_creation_tokens,
+              COALESCE(SUM(t.cache_read_tokens), 0)                     AS cache_read_tokens,
+              COALESCE(SUM(t.input_tokens + t.output_tokens), 0)        AS input_output_tokens,
+              COUNT(*)                                                  AS turns
+         FROM turns t
+        WHERE t.ts >= ? AND t.ts < ? ${provClause}
+        ${groupByClause}
+        ORDER BY cap_weighted_raw DESC, "group" ASC`)
+        .all(opts.fromIso, opts.toIso);
+    // A no-group query always yields one row (aggregate over zero turns → group=null,
+    // sums 0). Drop that empty global row so callers see an empty array when there is
+    // no data, matching the grouped case.
+    return rows
+        .filter((r) => r.turns > 0)
+        .map((r) => ({
+        group: r.group,
+        cap_weighted_tokens: Math.round(r.cap_weighted_raw ?? 0),
+        cache_creation_tokens: r.cache_creation_tokens,
+        cache_read_weighted: Math.round(coeff * r.cache_read_tokens),
+        cache_read_tokens: r.cache_read_tokens,
+        input_output_tokens: r.input_output_tokens,
+        cache_read_to_creation_ratio: r.cache_creation_tokens > 0 ? r.cache_read_tokens / r.cache_creation_tokens : null,
+        turns: r.turns,
+    }));
+}

package/dist/query/db-context.js

@@ -0,0 +1,42 @@
+/**
+ * src/query/db-context.ts — DB handle for the LocalQueryAPI read layer.
+ *
+ * WHY THIS EXISTS (interface note for reviewers):
+ * The frozen LocalQueryAPI method signatures (query/api/overview.ts) take no
+ * `db` parameter, and the daemon router (src/daemon/router.ts, off-limits to
+ * WP2) calls them without forwarding the `db` it receives. So the query layer
+ * needs its own way to reach the database. This module provides it:
+ *
+ *   - Tests call `setQueryDb(fixtureDb)` to inject the seeded fixture DB.
+ *   - In production, `getQueryDb()` lazily opens a read connection to the same
+ *     on-disk DB file the daemon uses (resolved via daemon config / AW_DB_PATH).
+ *     better-sqlite3 in WAL mode supports multiple connections to one file, so
+ *     a second read-only-in-practice connection alongside the daemon's writer
+ *     is safe.
+ *
+ * The lazy-open is only reached when no DB has been injected. Ideally the daemon
+ * boot would call `setQueryDb(db)` so the query layer shares the daemon's single
+ * connection — but that is a daemon/** change outside WP2's ownership. Flagged,
+ * not blocking: the lazy read connection is correct for the spend-path reads.
+ */
+import { loadConfig } from "../daemon/config.js";
+import { openDb } from "../db/open.js";
+let active = null;
+/** Inject the DB the query layer should use (tests; optional daemon wiring). */
+export function setQueryDb(db) {
+    active = db;
+}
+/** Clear the injected DB (tests, between cases). Does not close the handle. */
+export function resetQueryDb() {
+    active = null;
+}
+/**
+ * Return the active query DB, lazily opening the configured on-disk DB the
+ * first time if none was injected.
+ */
+export function getQueryDb() {
+    if (active !== null)
+        return active;
+    active = openDb(loadConfig().dbPath);
+    return active;
+}

package/dist/query/envelope.js

@@ -0,0 +1,71 @@
+/**
+ * src/query/envelope.ts — FROZEN API response envelope for the LocalQueryAPI.
+ *
+ * FROZEN in WP0 — changing this shape invalidates every downstream track;
+ * amend only via plan decision.
+ *
+ * All LocalQueryAPI methods return `ApiResponse<T>` so the UI always has the
+ * same structural envelope to read. The UI never inspects `meta` for business
+ * logic (that is the API's job); it uses it for display labels and drilldown.
+ *
+ * WP2 fills `overview.ts`, WP4 fills `settings.ts`. WP3 and WP4 build against
+ * this frozen shape — do not add fields silently.
+ */
+// ---------------------------------------------------------------------------
+// Builder
+// ---------------------------------------------------------------------------
+/**
+ * Default meta for stub responses (WP2/WP4 will replace with real values).
+ * The window defaults to the last 7 days.
+ */
+function defaultWindow() {
+    const to = new Date();
+    const from = new Date(to.getTime() - 7 * 24 * 60 * 60 * 1000);
+    return {
+        from: from.toISOString(),
+        to: to.toISOString(),
+        preset: "7d",
+    };
+}
+function defaultQualification() {
+    return {
+        provisional_excluded: false,
+        unpriced_turns: 0,
+        claim_kinds_count: 1,
+        note: "",
+    };
+}
+/**
+ * Build a stub `ApiResponse<null>` for method stubs.
+ * WP2/WP4 replace `data` and fill in real `meta` values.
+ */
+export function stubResponse(claim_kind = "N_A", drilldown_ids = {}) {
+    return {
+        data: null,
+        meta: {
+            n: 0,
+            window: defaultWindow(),
+            qualification: defaultQualification(),
+            metric_definition_version: "observe-1",
+            claim_kind,
+            drilldown_ids,
+        },
+    };
+}
+/**
+ * Build a complete `ApiResponse<T>` with the given data and meta overrides.
+ * Callers provide the parts they know; the rest gets safe defaults.
+ */
+export function buildResponse(data, meta) {
+    return {
+        data,
+        meta: {
+            n: 0,
+            window: defaultWindow(),
+            qualification: defaultQualification(),
+            metric_definition_version: "observe-1",
+            drilldown_ids: {},
+            ...meta,
+        },
+    };
+}