@cairn-tool/cairn 2.0.0

package/dist/usage/db/migrations.js

@@ -0,0 +1,38 @@
+import { latestVersion } from "../../sqlite-store.js";
+import { SCHEMA_V1 } from "./schema.js";
+/**
+ * The usage store's schema versions.
+ *
+ * This is a **fifth hand-owned version**, and the first in this project that is
+ * migrated rather than discarded. `CACHE_VERSION` in the old JSON shard store
+ * and the one in `src/url-cache.ts` are private and self-invalidating: a
+ * mismatch throws the file away and costs a re-parse. This one cannot work that
+ * way. Once `archive run --include transcripts` has run and the source logs are
+ * pruned, the database is the only surviving record of that usage, so a version
+ * bump has to carry the data forward.
+ *
+ * That makes the rules different, and they are worth stating:
+ *
+ * - **Never edit a shipped migration.** A database in the field has already run
+ *   it; changing it means two databases claim the same version with different
+ *   shapes. Add a new one instead.
+ * - **A migration must be able to run on real data**, not just on an empty file.
+ * - **A database from the future is refused, not guessed at.** A newer `cairn`
+ *   may have written columns this build knows nothing about, and opening it
+ *   read-write risks dropping them on the next write.
+ *
+ * `PRAGMA user_version` is the store, because SQLite keeps it in the file header
+ * where it costs no table and cannot itself need migrating.
+ */
+export const MIGRATIONS = [
+    {
+        version: 1,
+        description: "Initial schema: files, events, and the materialized day rollup",
+        up(db) {
+            db.exec(SCHEMA_V1);
+        },
+    },
+];
+/** The version a database this build writes ends up at. */
+export const LATEST_VERSION = latestVersion(MIGRATIONS);
+//# sourceMappingURL=migrations.js.map

package/dist/usage/db/migrations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrations.js","sourceRoot":"","sources":["../../../src/usage/db/migrations.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAExC;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,CAAC,MAAM,UAAU,GAAyB;IAC9C;QACE,OAAO,EAAE,CAAC;QACV,WAAW,EAAE,gEAAgE;QAC7E,EAAE,CAAC,EAAE;YACH,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QACrB,CAAC;KACF;CACF,CAAC;AAEF,2DAA2D;AAC3D,MAAM,CAAC,MAAM,cAAc,GAAW,aAAa,CAAC,UAAU,CAAC,CAAC"}

package/dist/usage/db/open.d.ts

@@ -0,0 +1,33 @@
+import type { StoreHandle } from "../../sqlite-store.js";
+import { StoreTooNewError } from "../../sqlite-store.js";
+/**
+ * Where the usage store lives.
+ *
+ * `XDG_DATA_HOME`, not `XDG_CACHE_HOME`. The JSON shard store this replaced was
+ * a cache — losing it cost a re-parse and nothing else. This is data: once
+ * transcripts have been archived and pruned, it is the only record of that usage
+ * left on the machine, and a cache directory is somewhere tools are entitled to
+ * delete without asking.
+ */
+export declare function getUsageDatabasePath(env?: NodeJS.ProcessEnv, homedir?: string): string;
+export { StoreTooNewError as DatabaseTooNewError } from "../../sqlite-store.js";
+export interface OpenOptions {
+    path: string;
+    /** Open without migrating, and refuse to create. For readers and status. */
+    readOnly?: boolean;
+    /**
+     * Apply pending migrations. Default true. When false, an out-of-date store
+     * opens as-is, which is what `usage migrate --check` needs.
+     */
+    migrate?: boolean;
+}
+export type OpenResult = StoreHandle;
+/**
+ * Opens the usage store, migrating it forward.
+ *
+ * The mechanics live in `src/sqlite-store.ts`, shared with the archive index;
+ * what belongs here is only which migrations apply and what the thing is called
+ * when something goes wrong.
+ */
+export declare function openUsageDatabase(options: OpenOptions): OpenResult;
+export { StoreTooNewError };

package/dist/usage/db/open.js

@@ -0,0 +1,37 @@
+import os from "node:os";
+import path from "node:path";
+import { openStore, StoreTooNewError } from "../../sqlite-store.js";
+import { MIGRATIONS } from "./migrations.js";
+/**
+ * Where the usage store lives.
+ *
+ * `XDG_DATA_HOME`, not `XDG_CACHE_HOME`. The JSON shard store this replaced was
+ * a cache — losing it cost a re-parse and nothing else. This is data: once
+ * transcripts have been archived and pruned, it is the only record of that usage
+ * left on the machine, and a cache directory is somewhere tools are entitled to
+ * delete without asking.
+ */
+export function getUsageDatabasePath(env = process.env, homedir = os.homedir()) {
+    const configured = env.XDG_DATA_HOME?.trim();
+    const base = configured ? configured : path.join(homedir, ".local", "share");
+    return path.join(base, "cairn", "usage.db");
+}
+export { StoreTooNewError as DatabaseTooNewError } from "../../sqlite-store.js";
+/**
+ * Opens the usage store, migrating it forward.
+ *
+ * The mechanics live in `src/sqlite-store.ts`, shared with the archive index;
+ * what belongs here is only which migrations apply and what the thing is called
+ * when something goes wrong.
+ */
+export function openUsageDatabase(options) {
+    return openStore({
+        path: options.path,
+        migrations: MIGRATIONS,
+        label: "usage database",
+        ...(options.readOnly === true ? { readOnly: true } : {}),
+        ...(options.migrate === false ? { migrate: false } : {}),
+    });
+}
+export { StoreTooNewError };
+//# sourceMappingURL=open.js.map

package/dist/usage/db/open.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"open.js","sourceRoot":"","sources":["../../../src/usage/db/open.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,OAAO,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACpE,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE7C;;;;;;;;GAQG;AACH,MAAM,UAAU,oBAAoB,CAClC,MAAyB,OAAO,CAAC,GAAG,EACpC,UAAkB,EAAE,CAAC,OAAO,EAAE;IAE9B,MAAM,UAAU,GAAG,GAAG,CAAC,aAAa,EAAE,IAAI,EAAE,CAAC;IAC7C,MAAM,IAAI,GAAG,UAAU,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;IAC7E,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC;AAC9C,CAAC;AAED,OAAO,EAAE,gBAAgB,IAAI,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAehF;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAoB;IACpD,OAAO,SAAS,CAAC;QACf,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,UAAU,EAAE,UAAU;QACtB,KAAK,EAAE,gBAAgB;QACvB,GAAG,CAAC,OAAO,CAAC,QAAQ,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACxD,GAAG,CAAC,OAAO,CAAC,OAAO,KAAK,KAAK,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACzD,CAAC,CAAC;AACL,CAAC;AAED,OAAO,EAAE,gBAAgB,EAAE,CAAC"}

package/dist/usage/db/schema.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The usage store's tables.
+ *
+ * Two grains live here on purpose. `event` is the per-occurrence decomposition —
+ * roughly 2.5M rows over a full corpus — and answers anything sub-day,
+ * per-turn, or sequential. The `day*` tables are a materialized rollup of those
+ * same events, about 82k rows, and are what every report that exists today
+ * reads: keeping them means a rollup never scans the event table, and means the
+ * reports produce byte-identical output to the JSON shard cache they replaced,
+ * because they are fed the same `DayBucket` shape from the same numbers.
+ *
+ * Writing both is cheap. Deriving the buckets from `event` at query time instead
+ * would make every report pay for a grain it does not use, and deriving them at
+ * import time from anything but the provider's own bucket would risk the two
+ * disagreeing — see `tests/unit/usage-events.test.ts`, which is what pins them
+ * together.
+ */
+export declare const SCHEMA_V1 = "\nCREATE TABLE meta(\n  key   TEXT PRIMARY KEY,\n  value TEXT NOT NULL\n);\n\nCREATE TABLE file(\n  id                INTEGER PRIMARY KEY,\n  provider          TEXT    NOT NULL,\n  relative          TEXT    NOT NULL,\n  path              TEXT    NOT NULL,\n  size              INTEGER NOT NULL,\n  mtime_ms          REAL    NOT NULL,\n  session_id        TEXT    NOT NULL,\n  kind              TEXT    NOT NULL,\n  parent_session_id TEXT,\n  agent_id          TEXT,\n  agent_type        TEXT,\n  agent_path        TEXT,\n  spawn_depth       INTEGER,\n  project           TEXT    NOT NULL,\n  title             TEXT,\n  git_branch        TEXT,\n  tool_version      TEXT,\n  first_ts          TEXT    NOT NULL,\n  last_ts           TEXT    NOT NULL,\n  malformed_lines   INTEGER NOT NULL DEFAULT 0,\n  imported_at       TEXT    NOT NULL,\n  UNIQUE(provider, relative)\n);\n\nCREATE TABLE event(\n  id             INTEGER PRIMARY KEY,\n  file_id        INTEGER NOT NULL REFERENCES file(id) ON DELETE CASCADE,\n  ts             TEXT    NOT NULL,\n  day            TEXT    NOT NULL,\n  kind           TEXT    NOT NULL,\n  model          TEXT,\n  tool           TEXT,\n  name           TEXT,\n  status         TEXT,\n  duration_ms    INTEGER,\n  depth          INTEGER,\n  input          INTEGER,\n  output         INTEGER,\n  cache_read     INTEGER,\n  cache_write    INTEGER,\n  cache_write_5m INTEGER,\n  cache_write_1h INTEGER,\n  thinking       INTEGER,\n  web_search     INTEGER,\n  web_fetch      INTEGER,\n  requests       INTEGER\n);\n\nCREATE TABLE day(\n  id          INTEGER PRIMARY KEY,\n  file_id     INTEGER NOT NULL REFERENCES file(id) ON DELETE CASCADE,\n  day         TEXT    NOT NULL,\n  prompts     INTEGER NOT NULL DEFAULT 0,\n  errors      INTEGER NOT NULL DEFAULT 0,\n  compactions INTEGER NOT NULL DEFAULT 0,\n  UNIQUE(file_id, day)\n);\n\nCREATE TABLE day_model(\n  day_id         INTEGER NOT NULL REFERENCES day(id) ON DELETE CASCADE,\n  model          TEXT    NOT NULL,\n  input          INTEGER NOT NULL DEFAULT 0,\n  output         INTEGER NOT NULL DEFAULT 0,\n  cache_read     INTEGER NOT NULL DEFAULT 0,\n  cache_write    INTEGER NOT NULL DEFAULT 0,\n  cache_write_5m INTEGER NOT NULL DEFAULT 0,\n  cache_write_1h INTEGER NOT NULL DEFAULT 0,\n  thinking       INTEGER NOT NULL DEFAULT 0,\n  web_search     INTEGER NOT NULL DEFAULT 0,\n  web_fetch      INTEGER NOT NULL DEFAULT 0,\n  requests       INTEGER NOT NULL DEFAULT 0,\n  PRIMARY KEY(day_id, model)\n);\n\nCREATE TABLE day_tool(\n  day_id INTEGER NOT NULL REFERENCES day(id) ON DELETE CASCADE,\n  tool   TEXT    NOT NULL,\n  calls  INTEGER NOT NULL DEFAULT 0,\n  PRIMARY KEY(day_id, tool)\n);\n\nCREATE TABLE day_skill(\n  day_id INTEGER NOT NULL REFERENCES day(id) ON DELETE CASCADE,\n  skill  TEXT    NOT NULL,\n  calls  INTEGER NOT NULL DEFAULT 0,\n  PRIMARY KEY(day_id, skill)\n);\n\nCREATE TABLE day_command(\n  day_id  INTEGER NOT NULL REFERENCES day(id) ON DELETE CASCADE,\n  command TEXT    NOT NULL,\n  calls   INTEGER NOT NULL DEFAULT 0,\n  PRIMARY KEY(day_id, command)\n);\n\nCREATE TABLE day_agent(\n  day_id    INTEGER NOT NULL REFERENCES day(id) ON DELETE CASCADE,\n  agent     TEXT    NOT NULL,\n  count     INTEGER NOT NULL DEFAULT 0,\n  max_depth INTEGER NOT NULL DEFAULT 0,\n  PRIMARY KEY(day_id, agent)\n);\n\nCREATE TABLE day_hook(\n  day_id    INTEGER NOT NULL REFERENCES day(id) ON DELETE CASCADE,\n  hook      TEXT    NOT NULL,\n  count     INTEGER NOT NULL DEFAULT 0,\n  failures  INTEGER NOT NULL DEFAULT 0,\n  cancelled INTEGER NOT NULL DEFAULT 0,\n  total_ms  INTEGER NOT NULL DEFAULT 0,\n  max_ms    INTEGER NOT NULL DEFAULT 0,\n  PRIMARY KEY(day_id, hook)\n);\n\nCREATE INDEX file_provider_session ON file(provider, session_id);\nCREATE INDEX file_project          ON file(project);\nCREATE INDEX file_kind             ON file(provider, kind);\nCREATE INDEX day_file              ON day(file_id);\nCREATE INDEX day_day               ON day(day);\nCREATE INDEX event_file_ts         ON event(file_id, ts);\nCREATE INDEX event_day_kind        ON event(day, kind);\n";

package/dist/usage/db/schema.js

@@ -0,0 +1,147 @@
+/**
+ * The usage store's tables.
+ *
+ * Two grains live here on purpose. `event` is the per-occurrence decomposition —
+ * roughly 2.5M rows over a full corpus — and answers anything sub-day,
+ * per-turn, or sequential. The `day*` tables are a materialized rollup of those
+ * same events, about 82k rows, and are what every report that exists today
+ * reads: keeping them means a rollup never scans the event table, and means the
+ * reports produce byte-identical output to the JSON shard cache they replaced,
+ * because they are fed the same `DayBucket` shape from the same numbers.
+ *
+ * Writing both is cheap. Deriving the buckets from `event` at query time instead
+ * would make every report pay for a grain it does not use, and deriving them at
+ * import time from anything but the provider's own bucket would risk the two
+ * disagreeing — see `tests/unit/usage-events.test.ts`, which is what pins them
+ * together.
+ */
+export const SCHEMA_V1 = `
+CREATE TABLE meta(
+  key   TEXT PRIMARY KEY,
+  value TEXT NOT NULL
+);
+
+CREATE TABLE file(
+  id                INTEGER PRIMARY KEY,
+  provider          TEXT    NOT NULL,
+  relative          TEXT    NOT NULL,
+  path              TEXT    NOT NULL,
+  size              INTEGER NOT NULL,
+  mtime_ms          REAL    NOT NULL,
+  session_id        TEXT    NOT NULL,
+  kind              TEXT    NOT NULL,
+  parent_session_id TEXT,
+  agent_id          TEXT,
+  agent_type        TEXT,
+  agent_path        TEXT,
+  spawn_depth       INTEGER,
+  project           TEXT    NOT NULL,
+  title             TEXT,
+  git_branch        TEXT,
+  tool_version      TEXT,
+  first_ts          TEXT    NOT NULL,
+  last_ts           TEXT    NOT NULL,
+  malformed_lines   INTEGER NOT NULL DEFAULT 0,
+  imported_at       TEXT    NOT NULL,
+  UNIQUE(provider, relative)
+);
+
+CREATE TABLE event(
+  id             INTEGER PRIMARY KEY,
+  file_id        INTEGER NOT NULL REFERENCES file(id) ON DELETE CASCADE,
+  ts             TEXT    NOT NULL,
+  day            TEXT    NOT NULL,
+  kind           TEXT    NOT NULL,
+  model          TEXT,
+  tool           TEXT,
+  name           TEXT,
+  status         TEXT,
+  duration_ms    INTEGER,
+  depth          INTEGER,
+  input          INTEGER,
+  output         INTEGER,
+  cache_read     INTEGER,
+  cache_write    INTEGER,
+  cache_write_5m INTEGER,
+  cache_write_1h INTEGER,
+  thinking       INTEGER,
+  web_search     INTEGER,
+  web_fetch      INTEGER,
+  requests       INTEGER
+);
+
+CREATE TABLE day(
+  id          INTEGER PRIMARY KEY,
+  file_id     INTEGER NOT NULL REFERENCES file(id) ON DELETE CASCADE,
+  day         TEXT    NOT NULL,
+  prompts     INTEGER NOT NULL DEFAULT 0,
+  errors      INTEGER NOT NULL DEFAULT 0,
+  compactions INTEGER NOT NULL DEFAULT 0,
+  UNIQUE(file_id, day)
+);
+
+CREATE TABLE day_model(
+  day_id         INTEGER NOT NULL REFERENCES day(id) ON DELETE CASCADE,
+  model          TEXT    NOT NULL,
+  input          INTEGER NOT NULL DEFAULT 0,
+  output         INTEGER NOT NULL DEFAULT 0,
+  cache_read     INTEGER NOT NULL DEFAULT 0,
+  cache_write    INTEGER NOT NULL DEFAULT 0,
+  cache_write_5m INTEGER NOT NULL DEFAULT 0,
+  cache_write_1h INTEGER NOT NULL DEFAULT 0,
+  thinking       INTEGER NOT NULL DEFAULT 0,
+  web_search     INTEGER NOT NULL DEFAULT 0,
+  web_fetch      INTEGER NOT NULL DEFAULT 0,
+  requests       INTEGER NOT NULL DEFAULT 0,
+  PRIMARY KEY(day_id, model)
+);
+
+CREATE TABLE day_tool(
+  day_id INTEGER NOT NULL REFERENCES day(id) ON DELETE CASCADE,
+  tool   TEXT    NOT NULL,
+  calls  INTEGER NOT NULL DEFAULT 0,
+  PRIMARY KEY(day_id, tool)
+);
+
+CREATE TABLE day_skill(
+  day_id INTEGER NOT NULL REFERENCES day(id) ON DELETE CASCADE,
+  skill  TEXT    NOT NULL,
+  calls  INTEGER NOT NULL DEFAULT 0,
+  PRIMARY KEY(day_id, skill)
+);
+
+CREATE TABLE day_command(
+  day_id  INTEGER NOT NULL REFERENCES day(id) ON DELETE CASCADE,
+  command TEXT    NOT NULL,
+  calls   INTEGER NOT NULL DEFAULT 0,
+  PRIMARY KEY(day_id, command)
+);
+
+CREATE TABLE day_agent(
+  day_id    INTEGER NOT NULL REFERENCES day(id) ON DELETE CASCADE,
+  agent     TEXT    NOT NULL,
+  count     INTEGER NOT NULL DEFAULT 0,
+  max_depth INTEGER NOT NULL DEFAULT 0,
+  PRIMARY KEY(day_id, agent)
+);
+
+CREATE TABLE day_hook(
+  day_id    INTEGER NOT NULL REFERENCES day(id) ON DELETE CASCADE,
+  hook      TEXT    NOT NULL,
+  count     INTEGER NOT NULL DEFAULT 0,
+  failures  INTEGER NOT NULL DEFAULT 0,
+  cancelled INTEGER NOT NULL DEFAULT 0,
+  total_ms  INTEGER NOT NULL DEFAULT 0,
+  max_ms    INTEGER NOT NULL DEFAULT 0,
+  PRIMARY KEY(day_id, hook)
+);
+
+CREATE INDEX file_provider_session ON file(provider, session_id);
+CREATE INDEX file_project          ON file(project);
+CREATE INDEX file_kind             ON file(provider, kind);
+CREATE INDEX day_file              ON day(file_id);
+CREATE INDEX day_day               ON day(day);
+CREATE INDEX event_file_ts         ON event(file_id, ts);
+CREATE INDEX event_day_kind        ON event(day, kind);
+`;
+//# sourceMappingURL=schema.js.map

package/dist/usage/db/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../../src/usage/db/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgIxB,CAAC"}

package/dist/usage/db/store.d.ts

@@ -0,0 +1,74 @@
+import type { SqliteDatabase, SqliteStatement } from "../../sqlite.js";
+import type { FileAggregate, ParsedFile } from "../events.js";
+export interface StoredFile {
+    id: number;
+    size: number;
+    mtimeMs: number;
+}
+/**
+ * Every transcript this provider already has a row for, keyed by its path
+ * relative to the log root — the same key the JSON shards used.
+ */
+export declare function storedFiles(db: SqliteDatabase, provider: string): Map<string, StoredFile>;
+/** The prepared statements one import run reuses across every file it writes. */
+export interface WriteStatements {
+    deleteFile: SqliteStatement;
+    insertFile: SqliteStatement;
+    insertEvent: SqliteStatement;
+    insertDay: SqliteStatement;
+    insertDayModel: SqliteStatement;
+    insertDayTool: SqliteStatement;
+    insertDaySkill: SqliteStatement;
+    insertDayCommand: SqliteStatement;
+    insertDayAgent: SqliteStatement;
+    insertDayHook: SqliteStatement;
+}
+export declare function prepareWrites(db: SqliteDatabase): WriteStatements;
+/**
+ * Writes one parsed transcript, replacing any row it already had.
+ *
+ * The delete is what makes a re-import idempotent: `ON DELETE CASCADE` clears
+ * the file's events and day buckets, so a transcript that grew is rewritten
+ * whole rather than accumulating a second copy of everything it already held.
+ */
+export declare function writeParsedFile(statements: WriteStatements, parsed: ParsedFile, relative: string, importedAt: string, existingId?: number): void;
+/**
+ * Drops rows for transcripts a complete walk did not find.
+ *
+ * Only ever called after a walk that looked at everything. A walk pruned by
+ * `--since` or `--no-subagents` has no evidence about the files it skipped, and
+ * deleting them would evict entries the next full import would have to re-parse
+ * from scratch — the invariant the JSON shard store called `partial`.
+ */
+export declare function deleteMissing(db: SqliteDatabase, provider: string, seen: ReadonlySet<string>): number;
+export interface SelectFilter {
+    providers: readonly string[];
+    /** Inclusive day bounds, pushed down purely to narrow the row set. */
+    since?: string;
+    until?: string;
+    /** When false, subagent transcripts are left out of the walk entirely. */
+    subagents: boolean;
+}
+/**
+ * Hydrates the selection as `FileAggregate`s.
+ *
+ * The shape is exactly what the JSON shard store returned, so every rollup in
+ * `aggregate.ts` runs against it unchanged. Child tables are read with one query
+ * each rather than per file: the whole corpus is around 82k day rows, so seven
+ * scans cost less than the round trips a per-file query would make.
+ */
+export declare function selectFiles(db: SqliteDatabase, filter: SelectFilter): FileAggregate[];
+export interface StoreStatus {
+    path: string;
+    present: boolean;
+    schemaVersion: number;
+    files: number;
+    days: number;
+    events: number;
+    bytes: number;
+    /** Most recent import as an ISO instant, or null when the store is empty. */
+    updatedAt: string | null;
+    /** Row counts per provider, so a caller can see what a store actually holds. */
+    providers: Record<string, number>;
+}
+export declare function storeStatus(db: SqliteDatabase): Omit<StoreStatus, "path" | "present" | "bytes">;

package/dist/usage/db/store.js

@@ -0,0 +1,280 @@
+import { emptyBucket, emptyTokens, utcDay } from "../events.js";
+/**
+ * Reading and writing the usage store.
+ *
+ * Nothing here decides *what* to import — that is `import.ts` — and nothing here
+ * filters by anything the pure helpers in `filter.ts` already own. SQL narrows
+ * the row set for speed; `clipToWindow` and `matchesProject` still decide
+ * membership, so the selection a report sees is defined by the same code that
+ * defined it when the store was a directory of JSON shards.
+ */
+/**
+ * `node:sqlite` rejects `undefined`, and every optional column here is optional
+ * because the provider genuinely had nothing to record.
+ */
+function bind(value) {
+    return value ?? null;
+}
+function text(value) {
+    return typeof value === "string" && value ? value : undefined;
+}
+function int(value) {
+    return typeof value === "number" ? value : 0;
+}
+/**
+ * Every transcript this provider already has a row for, keyed by its path
+ * relative to the log root — the same key the JSON shards used.
+ */
+export function storedFiles(db, provider) {
+    const rows = db
+        .prepare("SELECT id, relative, size, mtime_ms FROM file WHERE provider = ?")
+        .all(provider);
+    const found = new Map();
+    for (const row of rows) {
+        found.set(String(row.relative), {
+            id: Number(row.id),
+            size: Number(row.size),
+            mtimeMs: Number(row.mtime_ms),
+        });
+    }
+    return found;
+}
+export function prepareWrites(db) {
+    return {
+        deleteFile: db.prepare("DELETE FROM file WHERE id = ?"),
+        insertFile: db.prepare(`INSERT INTO file(provider, relative, path, size, mtime_ms, session_id, kind,
+         parent_session_id, agent_id, agent_type, agent_path, spawn_depth, project,
+         title, git_branch, tool_version, first_ts, last_ts, malformed_lines, imported_at)
+       VALUES(?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)`),
+        insertEvent: db.prepare(`INSERT INTO event(file_id, ts, day, kind, model, tool, name, status, duration_ms, depth,
+         input, output, cache_read, cache_write, cache_write_5m, cache_write_1h,
+         thinking, web_search, web_fetch, requests)
+       VALUES(?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)`),
+        insertDay: db.prepare("INSERT INTO day(file_id, day, prompts, errors, compactions) VALUES(?,?,?,?,?)"),
+        insertDayModel: db.prepare(`INSERT INTO day_model(day_id, model, input, output, cache_read, cache_write,
+         cache_write_5m, cache_write_1h, thinking, web_search, web_fetch, requests)
+       VALUES(?,?,?,?,?,?,?,?,?,?,?,?)`),
+        insertDayTool: db.prepare("INSERT INTO day_tool(day_id, tool, calls) VALUES(?,?,?)"),
+        insertDaySkill: db.prepare("INSERT INTO day_skill(day_id, skill, calls) VALUES(?,?,?)"),
+        insertDayCommand: db.prepare("INSERT INTO day_command(day_id, command, calls) VALUES(?,?,?)"),
+        insertDayAgent: db.prepare("INSERT INTO day_agent(day_id, agent, count, max_depth) VALUES(?,?,?,?)"),
+        insertDayHook: db.prepare(`INSERT INTO day_hook(day_id, hook, count, failures, cancelled, total_ms, max_ms)
+       VALUES(?,?,?,?,?,?,?)`),
+    };
+}
+/**
+ * Writes one parsed transcript, replacing any row it already had.
+ *
+ * The delete is what makes a re-import idempotent: `ON DELETE CASCADE` clears
+ * the file's events and day buckets, so a transcript that grew is rewritten
+ * whole rather than accumulating a second copy of everything it already held.
+ */
+export function writeParsedFile(statements, parsed, relative, importedAt, existingId) {
+    if (existingId !== undefined)
+        statements.deleteFile.run(existingId);
+    const aggregate = parsed.aggregate;
+    const inserted = statements.insertFile.run(aggregate.provider, relative, aggregate.file, aggregate.size, aggregate.mtimeMs, aggregate.sessionId, aggregate.kind, bind(aggregate.parentSessionId), bind(aggregate.agentId), bind(aggregate.agentType), bind(aggregate.agentPath), bind(aggregate.spawnDepth), aggregate.project, bind(aggregate.title), bind(aggregate.gitBranch), bind(aggregate.toolVersion), aggregate.firstTs, aggregate.lastTs, aggregate.malformedLines, importedAt);
+    const fileId = Number(inserted.lastInsertRowid);
+    for (const event of parsed.events) {
+        const day = utcDay(event.ts);
+        if (!day)
+            continue;
+        const tokens = event.tokens;
+        statements.insertEvent.run(fileId, event.ts, day, event.kind, bind(event.model), bind(event.tool), bind(event.name), bind(event.status), bind(event.durationMs), bind(event.depth), bind(tokens?.input), bind(tokens?.output), bind(tokens?.cacheRead), bind(tokens?.cacheWrite), bind(tokens?.cacheWrite5m), bind(tokens?.cacheWrite1h), bind(tokens?.thinking), bind(tokens?.webSearch), bind(tokens?.webFetch), bind(tokens?.requests));
+    }
+    for (const [day, bucket] of Object.entries(aggregate.days)) {
+        const dayRow = statements.insertDay.run(fileId, day, bucket.prompts, bucket.errors, bucket.compactions);
+        const dayId = Number(dayRow.lastInsertRowid);
+        for (const [model, tokens] of Object.entries(bucket.models)) {
+            statements.insertDayModel.run(dayId, model, tokens.input, tokens.output, tokens.cacheRead, tokens.cacheWrite, tokens.cacheWrite5m, tokens.cacheWrite1h, tokens.thinking, tokens.webSearch, tokens.webFetch, tokens.requests);
+        }
+        for (const [tool, calls] of Object.entries(bucket.tools)) {
+            statements.insertDayTool.run(dayId, tool, calls);
+        }
+        for (const [skill, calls] of Object.entries(bucket.skills)) {
+            statements.insertDaySkill.run(dayId, skill, calls);
+        }
+        for (const [command, calls] of Object.entries(bucket.commands)) {
+            statements.insertDayCommand.run(dayId, command, calls);
+        }
+        for (const [agent, totals] of Object.entries(bucket.agents)) {
+            statements.insertDayAgent.run(dayId, agent, totals.count, totals.maxDepth);
+        }
+        for (const [hook, totals] of Object.entries(bucket.hooks)) {
+            statements.insertDayHook.run(dayId, hook, totals.count, totals.failures, totals.cancelled, totals.totalMs, totals.maxMs);
+        }
+    }
+}
+/**
+ * Drops rows for transcripts a complete walk did not find.
+ *
+ * Only ever called after a walk that looked at everything. A walk pruned by
+ * `--since` or `--no-subagents` has no evidence about the files it skipped, and
+ * deleting them would evict entries the next full import would have to re-parse
+ * from scratch — the invariant the JSON shard store called `partial`.
+ */
+export function deleteMissing(db, provider, seen) {
+    const rows = db.prepare("SELECT id, relative FROM file WHERE provider = ?").all(provider);
+    const remove = db.prepare("DELETE FROM file WHERE id = ?");
+    let removed = 0;
+    for (const row of rows) {
+        if (seen.has(String(row.relative)))
+            continue;
+        remove.run(Number(row.id));
+        removed += 1;
+    }
+    return removed;
+}
+/**
+ * Hydrates the selection as `FileAggregate`s.
+ *
+ * The shape is exactly what the JSON shard store returned, so every rollup in
+ * `aggregate.ts` runs against it unchanged. Child tables are read with one query
+ * each rather than per file: the whole corpus is around 82k day rows, so seven
+ * scans cost less than the round trips a per-file query would make.
+ */
+export function selectFiles(db, filter) {
+    if (filter.providers.length === 0)
+        return [];
+    const placeholders = filter.providers.map(() => "?").join(",");
+    const conditions = [`f.provider IN (${placeholders})`];
+    const parameters = [...filter.providers];
+    if (!filter.subagents)
+        conditions.push("f.kind <> 'subagent'");
+    const fileRows = db
+        .prepare(`SELECT * FROM file f WHERE ${conditions.join(" AND ")} ORDER BY f.id`)
+        .all(...parameters);
+    const byId = new Map();
+    for (const row of fileRows) {
+        const id = Number(row.id);
+        byId.set(id, {
+            file: String(row.path),
+            size: Number(row.size),
+            mtimeMs: Number(row.mtime_ms),
+            provider: String(row.provider),
+            sessionId: String(row.session_id),
+            kind: String(row.kind),
+            ...(text(row.parent_session_id) ? { parentSessionId: text(row.parent_session_id) } : {}),
+            ...(text(row.agent_id) ? { agentId: text(row.agent_id) } : {}),
+            ...(text(row.agent_type) ? { agentType: text(row.agent_type) } : {}),
+            ...(text(row.agent_path) ? { agentPath: text(row.agent_path) } : {}),
+            ...(typeof row.spawn_depth === "number" ? { spawnDepth: row.spawn_depth } : {}),
+            project: String(row.project),
+            ...(text(row.title) ? { title: text(row.title) } : {}),
+            ...(text(row.git_branch) ? { gitBranch: text(row.git_branch) } : {}),
+            ...(text(row.tool_version) ? { toolVersion: text(row.tool_version) } : {}),
+            firstTs: String(row.first_ts),
+            lastTs: String(row.last_ts),
+            days: {},
+            malformedLines: Number(row.malformed_lines),
+        });
+    }
+    if (byId.size === 0)
+        return [];
+    const dayConditions = [...conditions];
+    const dayParameters = [...parameters];
+    if (filter.since) {
+        dayConditions.push("d.day >= ?");
+        dayParameters.push(filter.since);
+    }
+    if (filter.until) {
+        dayConditions.push("d.day <= ?");
+        dayParameters.push(filter.until);
+    }
+    const buckets = new Map();
+    const dayRows = db
+        .prepare(`SELECT d.id, d.file_id, d.day, d.prompts, d.errors, d.compactions
+         FROM day d JOIN file f ON f.id = d.file_id
+        WHERE ${dayConditions.join(" AND ")}`)
+        .all(...dayParameters);
+    for (const row of dayRows) {
+        const aggregate = byId.get(Number(row.file_id));
+        if (!aggregate)
+            continue;
+        const bucket = emptyBucket();
+        bucket.prompts = int(row.prompts);
+        bucket.errors = int(row.errors);
+        bucket.compactions = int(row.compactions);
+        aggregate.days[String(row.day)] = bucket;
+        buckets.set(Number(row.id), bucket);
+    }
+    if (buckets.size === 0)
+        return [...byId.values()];
+    const child = (table, columns) => db
+        .prepare(`SELECT c.day_id, ${columns}
+           FROM ${table} c
+           JOIN day d ON d.id = c.day_id
+           JOIN file f ON f.id = d.file_id
+          WHERE ${dayConditions.join(" AND ")}`)
+        .all(...dayParameters);
+    for (const row of child("day_model", `c.model, c.input, c.output, c.cache_read, c.cache_write, c.cache_write_5m,
+     c.cache_write_1h, c.thinking, c.web_search, c.web_fetch, c.requests`)) {
+        const bucket = buckets.get(Number(row.day_id));
+        if (!bucket)
+            continue;
+        bucket.models[String(row.model)] = {
+            ...emptyTokens(),
+            input: int(row.input),
+            output: int(row.output),
+            cacheRead: int(row.cache_read),
+            cacheWrite: int(row.cache_write),
+            cacheWrite5m: int(row.cache_write_5m),
+            cacheWrite1h: int(row.cache_write_1h),
+            thinking: int(row.thinking),
+            webSearch: int(row.web_search),
+            webFetch: int(row.web_fetch),
+            requests: int(row.requests),
+        };
+    }
+    const counts = [
+        ["day_tool", "tool", "tools"],
+        ["day_skill", "skill", "skills"],
+        ["day_command", "command", "commands"],
+    ];
+    for (const [table, column, target] of counts) {
+        for (const row of child(table, `c.${column} AS key, c.calls`)) {
+            const bucket = buckets.get(Number(row.day_id));
+            if (!bucket)
+                continue;
+            bucket[target][String(row.key)] = int(row.calls);
+        }
+    }
+    for (const row of child("day_agent", "c.agent, c.count, c.max_depth")) {
+        const bucket = buckets.get(Number(row.day_id));
+        if (!bucket)
+            continue;
+        bucket.agents[String(row.agent)] = { count: int(row.count), maxDepth: int(row.max_depth) };
+    }
+    for (const row of child("day_hook", "c.hook, c.count, c.failures, c.cancelled, c.total_ms, c.max_ms")) {
+        const bucket = buckets.get(Number(row.day_id));
+        if (!bucket)
+            continue;
+        bucket.hooks[String(row.hook)] = {
+            count: int(row.count),
+            failures: int(row.failures),
+            cancelled: int(row.cancelled),
+            totalMs: int(row.total_ms),
+            maxMs: int(row.max_ms),
+        };
+    }
+    return [...byId.values()];
+}
+export function storeStatus(db) {
+    const one = (sql) => Number(db.prepare(sql).get()?.n ?? 0);
+    const providers = {};
+    for (const row of db
+        .prepare("SELECT provider, COUNT(*) AS n FROM file GROUP BY provider ORDER BY provider")
+        .all()) {
+        providers[String(row.provider)] = Number(row.n);
+    }
+    const updated = db.prepare("SELECT MAX(imported_at) AS at FROM file").get()?.at;
+    return {
+        schemaVersion: Number(db.prepare("PRAGMA user_version").get()?.user_version ?? 0),
+        files: one("SELECT COUNT(*) AS n FROM file"),
+        days: one("SELECT COUNT(*) AS n FROM day"),
+        events: one("SELECT COUNT(*) AS n FROM event"),
+        updatedAt: typeof updated === "string" ? updated : null,
+        providers,
+    };
+}
+//# sourceMappingURL=store.js.map