@opensip-cli/datastore 0.1.0

package/dist/schema/tool-state.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Generic host-owned keyed tool state (ADR-0042 — the third-party persistence
+ * parity mechanism). ONE table serves every tool: each row is one opaque JSON
+ * payload under a `(tool, key)` identity, so tools share the table but never
+ * see each other's rows — the exact pattern the ADR-0036 baseline pair proved.
+ * Tools reach it ONLY through the `ToolStateRepo` / the `cli.toolState` seams;
+ * they never own schema.
+ *
+ * Durability note: unlike baselines (drop-and-recapture, CI-ephemeral), tool
+ * state is DURABLE tool data — a release never drops these rows.
+ */
+export declare const toolState: import("drizzle-orm/sqlite-core").SQLiteTableWithColumns<{
+    name: "tool_state";
+    schema: undefined;
+    columns: {
+        tool: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "tool";
+            tableName: "tool_state";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        stableId: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "stable_id";
+            tableName: "tool_state";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        key: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "key";
+            tableName: "tool_state";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        payload: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "payload";
+            tableName: "tool_state";
+            dataType: "json";
+            columnType: "SQLiteTextJson";
+            data: unknown;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        updatedAt: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "updated_at";
+            tableName: "tool_state";
+            dataType: "number";
+            columnType: "SQLiteInteger";
+            data: number;
+            driverParam: number;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+    };
+    dialect: "sqlite";
+}>;
+//# sourceMappingURL=tool-state.d.ts.map

package/dist/schema/tool-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-state.d.ts","sourceRoot":"","sources":["../../src/schema/tool-state.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AACH,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAUrB,CAAC"}

package/dist/schema/tool-state.js

@@ -0,0 +1,20 @@
+import { integer, primaryKey, sqliteTable, text } from 'drizzle-orm/sqlite-core';
+/**
+ * Generic host-owned keyed tool state (ADR-0042 — the third-party persistence
+ * parity mechanism). ONE table serves every tool: each row is one opaque JSON
+ * payload under a `(tool, key)` identity, so tools share the table but never
+ * see each other's rows — the exact pattern the ADR-0036 baseline pair proved.
+ * Tools reach it ONLY through the `ToolStateRepo` / the `cli.toolState` seams;
+ * they never own schema.
+ *
+ * Durability note: unlike baselines (drop-and-recapture, CI-ephemeral), tool
+ * state is DURABLE tool data — a release never drops these rows.
+ */
+export const toolState = sqliteTable('tool_state', {
+    tool: text('tool').notNull(), // human `name` value (for compat + current queries)
+    stableId: text('stable_id'), // tool stable UUID (additive per ADR-0048; null for legacy)
+    key: text('key').notNull(),
+    payload: text('payload', { mode: 'json' }),
+    updatedAt: integer('updated_at').notNull(),
+}, (t) => [primaryKey({ columns: [t.tool, t.key] })]);
+//# sourceMappingURL=tool-state.js.map

package/dist/schema/tool-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-state.js","sourceRoot":"","sources":["../../src/schema/tool-state.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,yBAAyB,CAAC;AAEjF;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,WAAW,CAClC,YAAY,EACZ;IACE,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE,oDAAoD;IAClF,QAAQ,EAAE,IAAI,CAAC,WAAW,CAAC,EAAE,4DAA4D;IACzF,GAAG,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,OAAO,EAAE;IAC1B,OAAO,EAAE,IAAI,CAAC,SAAS,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;IAC1C,SAAS,EAAE,OAAO,CAAC,YAAY,CAAC,CAAC,OAAO,EAAE;CAC3C,EACD,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,UAAU,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAClD,CAAC"}

package/dist/schema-version.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The DB schema version this CLI supports = the count of migrations it bundles.
+ *
+ * Returns `undefined` when the bundled journal cannot be read or parsed (a
+ * broken install). Callers treat `undefined` as "skip the version guard": the
+ * subsequent `migrate()` reads the same journal and will surface the canonical
+ * {@link DataStoreMigrationError} loudly, so skipping here hides nothing — it
+ * just declines to invent a version we cannot determine. We still warn so the
+ * anomaly is observable rather than silent.
+ */
+export declare function readSupportedDbVersion(migrationsFolder: string): number | undefined;
+/**
+ * True when the on-disk database was stamped by a CLI that knew MORE migrations
+ * than this one (`dbVersion > supportedVersion`) — i.e. the user downgraded the
+ * CLI after a newer version advanced the schema.
+ *
+ * The forward direction (`dbVersion <= supportedVersion`, including the `0` of a
+ * fresh or pre-guard "legacy" database) is always safe: Drizzle's migrator
+ * applies any pending migrations and we re-stamp afterward. Only the future
+ * database is blocked.
+ */
+export declare function isDbNewerThanCli(dbVersion: number, supportedVersion: number): boolean;
+//# sourceMappingURL=schema-version.d.ts.map

package/dist/schema-version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-version.d.ts","sourceRoot":"","sources":["../src/schema-version.ts"],"names":[],"mappings":"AAsBA;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CAAC,gBAAgB,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAcnF;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,GAAG,OAAO,CAErF"}

package/dist/schema-version.js

@@ -0,0 +1,55 @@
+/**
+ * schema-version — derives the DB schema version this CLI supports from the
+ * bundled Drizzle migration journal, and owns the version-guard math.
+ *
+ * The "supported version" is simply the number of migrations this build ships
+ * (the journal's entry count). It is monotonic: every new migration increments
+ * it automatically, so there is NO constant to hand-bump when a migration is
+ * added. We stamp this integer into the SQLite header (`PRAGMA user_version`)
+ * after a successful migrate, and compare it on the next open to detect a
+ * database written by a NEWER CLI than the one now opening it (the downgrade
+ * direction Drizzle's own migrator cannot detect — see {@link isDbNewerThanCli}).
+ */
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { logger } from '@opensip-cli/core';
+/**
+ * The DB schema version this CLI supports = the count of migrations it bundles.
+ *
+ * Returns `undefined` when the bundled journal cannot be read or parsed (a
+ * broken install). Callers treat `undefined` as "skip the version guard": the
+ * subsequent `migrate()` reads the same journal and will surface the canonical
+ * {@link DataStoreMigrationError} loudly, so skipping here hides nothing — it
+ * just declines to invent a version we cannot determine. We still warn so the
+ * anomaly is observable rather than silent.
+ */
+export function readSupportedDbVersion(migrationsFolder) {
+    const journalPath = join(migrationsFolder, 'meta', '_journal.json');
+    try {
+        const parsed = JSON.parse(readFileSync(journalPath, 'utf8'));
+        return Array.isArray(parsed.entries) ? parsed.entries.length : undefined;
+    }
+    catch (error) {
+        logger.warn({
+            evt: 'datastore.schema-version.journal-unreadable',
+            module: 'datastore:schema-version',
+            journalPath,
+            err: error,
+        });
+        return undefined;
+    }
+}
+/**
+ * True when the on-disk database was stamped by a CLI that knew MORE migrations
+ * than this one (`dbVersion > supportedVersion`) — i.e. the user downgraded the
+ * CLI after a newer version advanced the schema.
+ *
+ * The forward direction (`dbVersion <= supportedVersion`, including the `0` of a
+ * fresh or pre-guard "legacy" database) is always safe: Drizzle's migrator
+ * applies any pending migrations and we re-stamp afterward. Only the future
+ * database is blocked.
+ */
+export function isDbNewerThanCli(dbVersion, supportedVersion) {
+    return dbVersion > supportedVersion;
+}
+//# sourceMappingURL=schema-version.js.map

package/dist/schema-version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-version.js","sourceRoot":"","sources":["../src/schema-version.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAO3C;;;;;;;;;GASG;AACH,MAAM,UAAU,sBAAsB,CAAC,gBAAwB;IAC7D,MAAM,WAAW,GAAG,IAAI,CAAC,gBAAgB,EAAE,MAAM,EAAE,eAAe,CAAC,CAAC;IACpE,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,WAAW,EAAE,MAAM,CAAC,CAAmB,CAAC;QAC/E,OAAO,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC;IAC3E,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,CAAC,IAAI,CAAC;YACV,GAAG,EAAE,6CAA6C;YAClD,MAAM,EAAE,0BAA0B;YAClC,WAAW;YACX,GAAG,EAAE,KAAK;SACX,CAAC,CAAC;QACH,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,gBAAgB,CAAC,SAAiB,EAAE,gBAAwB;IAC1E,OAAO,SAAS,GAAG,gBAAgB,CAAC;AACtC,CAAC"}

package/dist/tool-state-repo.d.ts

@@ -0,0 +1,51 @@
+import { type DataStore } from './data-store.js';
+/**
+ * Per-payload size ceiling (UTF-8 bytes of the JSON serialization). Exceeding
+ * it ERRORS (a typed `ValidationError`) rather than evicting — silent eviction
+ * hides bugs; an explicit cap teaches the tool author to shard or summarize.
+ * Documented on the `cli.toolState` seam JSDoc (ADR-0042).
+ */
+export declare const TOOL_STATE_MAX_PAYLOAD_BYTES: number;
+/**
+ * The generic host-owned keyed tool-state repository (ADR-0042). One repo over
+ * the shared `tool_state` table, scoped by the `tool` column — every tool gets
+ * durable keyed JSON persistence without owning schema, the same generic-table
+ * pattern the ADR-0036 baseline pair proved. Tools consume it through the
+ * `cli.toolState` seams; the payload is opaque to the host.
+ *
+ * ## Versioning convention for toolState values
+ *
+ * For any key whose value shape a tool treats as versioned, the tool SHOULD
+ * include a top-level numeric `"__version": N` (starting at 1) inside the
+ * object it puts. The host never reads or enforces it — use
+ * `extractPayloadVersion` (from '@opensip-cli/core') inside your tool code
+ * when you `get` a key to decide projection/migration.
+ *
+ * Keys that are truly schemaless (arbitrary user data) may omit `__version`.
+ * See the payload schema evolution plan / ADR-0050 for safe vs. major rules.
+ */
+export declare class ToolStateRepo {
+    private readonly datastore;
+    constructor(datastore: DataStore);
+    /** Read one payload, or undefined when the key has never been put. */
+    get(tool: string, key: string): unknown;
+    /**
+     * Upsert one payload under `(tool, key)`.
+     *
+     * Callers that version the state for a stable key SHOULD put an object
+     * whose top level contains `"__version": 1` (or higher after a breaking change
+     * per the evolution rules). The host stores it opaquely; on read the caller
+     * uses `extractPayloadVersion(payload)` to inspect.
+     *
+     * @throws {ValidationError} when the JSON serialization exceeds
+     *   {@link TOOL_STATE_MAX_PAYLOAD_BYTES} (error, never evict).
+     */
+    put(tool: string, key: string, payload: unknown): void;
+    /** Delete one key (no-op when absent). */
+    delete(tool: string, key: string): void;
+    /** List this tool's keys, sorted (never another tool's). */
+    list(tool: string): readonly string[];
+    /** Delete ALL of this tool's state rows; returns the deleted count. */
+    clear(tool: string): number;
+}
+//# sourceMappingURL=tool-state-repo.d.ts.map

package/dist/tool-state-repo.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-state-repo.d.ts","sourceRoot":"","sources":["../src/tool-state-repo.ts"],"names":[],"mappings":"AAGA,OAAO,EAA2B,KAAK,SAAS,EAAyB,MAAM,iBAAiB,CAAC;AAKjG;;;;;GAKG;AACH,eAAO,MAAM,4BAA4B,QAAa,CAAC;AAEvD;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAmB;gBAEjC,SAAS,EAAE,SAAS;IAIhC,sEAAsE;IACtE,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO;IAUvC;;;;;;;;;;OAUG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI;IA4BtD,0CAA0C;IAC1C,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI;IAOvC,4DAA4D;IAC5D,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE;IAUrC,uEAAuE;IACvE,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;CAU5B"}

package/dist/tool-state-repo.js

@@ -0,0 +1,110 @@
+import { logger, ValidationError } from '@opensip-cli/core';
+import { and, asc, eq } from 'drizzle-orm';
+import { requireDrizzleDataStore } from './data-store.js';
+import { toolState } from './schema/tool-state.js';
+const MODULE_NAME = 'datastore:tool-state-repo';
+/**
+ * Per-payload size ceiling (UTF-8 bytes of the JSON serialization). Exceeding
+ * it ERRORS (a typed `ValidationError`) rather than evicting — silent eviction
+ * hides bugs; an explicit cap teaches the tool author to shard or summarize.
+ * Documented on the `cli.toolState` seam JSDoc (ADR-0042).
+ */
+export const TOOL_STATE_MAX_PAYLOAD_BYTES = 256 * 1024;
+/**
+ * The generic host-owned keyed tool-state repository (ADR-0042). One repo over
+ * the shared `tool_state` table, scoped by the `tool` column — every tool gets
+ * durable keyed JSON persistence without owning schema, the same generic-table
+ * pattern the ADR-0036 baseline pair proved. Tools consume it through the
+ * `cli.toolState` seams; the payload is opaque to the host.
+ *
+ * ## Versioning convention for toolState values
+ *
+ * For any key whose value shape a tool treats as versioned, the tool SHOULD
+ * include a top-level numeric `"__version": N` (starting at 1) inside the
+ * object it puts. The host never reads or enforces it — use
+ * `extractPayloadVersion` (from '@opensip-cli/core') inside your tool code
+ * when you `get` a key to decide projection/migration.
+ *
+ * Keys that are truly schemaless (arbitrary user data) may omit `__version`.
+ * See the payload schema evolution plan / ADR-0050 for safe vs. major rules.
+ */
+export class ToolStateRepo {
+    datastore;
+    constructor(datastore) {
+        this.datastore = requireDrizzleDataStore(datastore);
+    }
+    /** Read one payload, or undefined when the key has never been put. */
+    get(tool, key) {
+        const row = this.datastore.db
+            .select({ payload: toolState.payload })
+            .from(toolState)
+            .where(and(eq(toolState.tool, tool), eq(toolState.key, key)))
+            .limit(1)
+            .get();
+        return row?.payload ?? undefined;
+    }
+    /**
+     * Upsert one payload under `(tool, key)`.
+     *
+     * Callers that version the state for a stable key SHOULD put an object
+     * whose top level contains `"__version": 1` (or higher after a breaking change
+     * per the evolution rules). The host stores it opaquely; on read the caller
+     * uses `extractPayloadVersion(payload)` to inspect.
+     *
+     * @throws {ValidationError} when the JSON serialization exceeds
+     *   {@link TOOL_STATE_MAX_PAYLOAD_BYTES} (error, never evict).
+     */
+    put(tool, key, payload) {
+        const bytes = Buffer.byteLength(JSON.stringify(payload) ?? 'null', 'utf8');
+        if (bytes > TOOL_STATE_MAX_PAYLOAD_BYTES) {
+            // @fitness-ignore-next-line result-pattern-consistency -- documented @throws boundary (the cap errors, never evicts); exceptions propagate to the public Result/CommandOutcome boundary, matching the BaselineRepo/file-cache precedent
+            throw new ValidationError(`tool_state payload for '${tool}/${key}' is ${bytes} bytes — over the ` +
+                `${TOOL_STATE_MAX_PAYLOAD_BYTES}-byte cap (ADR-0042). Shard or summarize the payload.`, { code: 'VALIDATION.TOOL_STATE.PAYLOAD_TOO_LARGE' });
+        }
+        const updatedAt = Date.now();
+        this.datastore.db
+            .insert(toolState)
+            .values({ tool, key, payload, updatedAt })
+            .onConflictDoUpdate({
+            target: [toolState.tool, toolState.key],
+            set: { payload, updatedAt },
+        })
+            .run();
+        logger.debug({
+            evt: 'datastore.tool_state.put',
+            module: MODULE_NAME,
+            tool,
+            key,
+            bytes,
+        });
+    }
+    /** Delete one key (no-op when absent). */
+    delete(tool, key) {
+        this.datastore.db
+            .delete(toolState)
+            .where(and(eq(toolState.tool, tool), eq(toolState.key, key)))
+            .run();
+    }
+    /** List this tool's keys, sorted (never another tool's). */
+    list(tool) {
+        return this.datastore.db
+            .select({ key: toolState.key })
+            .from(toolState)
+            .where(eq(toolState.tool, tool))
+            .orderBy(asc(toolState.key))
+            .all()
+            .map((r) => r.key);
+    }
+    /** Delete ALL of this tool's state rows; returns the deleted count. */
+    clear(tool) {
+        const result = this.datastore.db.delete(toolState).where(eq(toolState.tool, tool)).run();
+        logger.info({
+            evt: 'datastore.tool_state.clear.complete',
+            module: MODULE_NAME,
+            tool,
+            count: result.changes,
+        });
+        return result.changes;
+    }
+}
+//# sourceMappingURL=tool-state-repo.js.map

package/dist/tool-state-repo.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-state-repo.js","sourceRoot":"","sources":["../src/tool-state-repo.ts"],"names":[],"mappings":"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"}

package/migrations/0000_sticky_white_tiger.sql

@@ -0,0 +1,39 @@
+CREATE TABLE `session_checks` (
+	`id` integer PRIMARY KEY AUTOINCREMENT NOT NULL,
+	`session_id` text NOT NULL,
+	`check_slug` text NOT NULL,
+	`passed` integer NOT NULL,
+	`violation_count` integer,
+	`duration_ms` integer NOT NULL,
+	FOREIGN KEY (`session_id`) REFERENCES `sessions`(`id`) ON UPDATE no action ON DELETE cascade
+);
+--> statement-breakpoint
+CREATE INDEX `session_checks_session_idx` ON `session_checks` (`session_id`);--> statement-breakpoint
+CREATE TABLE `session_findings` (
+	`id` integer PRIMARY KEY AUTOINCREMENT NOT NULL,
+	`session_check_id` integer NOT NULL,
+	`rule_id` text NOT NULL,
+	`severity` text NOT NULL,
+	`message` text NOT NULL,
+	`file_path` text,
+	`line` integer,
+	`column` integer,
+	`suggestion` text,
+	`category` text,
+	FOREIGN KEY (`session_check_id`) REFERENCES `session_checks`(`id`) ON UPDATE no action ON DELETE cascade
+);
+--> statement-breakpoint
+CREATE INDEX `session_findings_check_idx` ON `session_findings` (`session_check_id`);--> statement-breakpoint
+CREATE TABLE `sessions` (
+	`id` text PRIMARY KEY NOT NULL,
+	`tool` text NOT NULL,
+	`timestamp` integer NOT NULL,
+	`cwd` text NOT NULL,
+	`recipe` text,
+	`score` integer NOT NULL,
+	`passed` integer NOT NULL,
+	`summary` text NOT NULL,
+	`duration_ms` integer NOT NULL
+);
+--> statement-breakpoint
+CREATE INDEX `sessions_tool_timestamp_idx` ON `sessions` (`tool`,"timestamp" DESC);

package/migrations/0001_easy_harry_osborn.sql

@@ -0,0 +1,18 @@
+CREATE TABLE `graph_baseline_meta` (
+	`id` integer PRIMARY KEY NOT NULL,
+	`captured_at` integer NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE `graph_baseline_signals` (
+	`fingerprint` text PRIMARY KEY NOT NULL,
+	`captured_at` integer NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE `graph_catalog` (
+	`id` integer PRIMARY KEY NOT NULL,
+	`language` text NOT NULL,
+	`cache_key` text NOT NULL,
+	`files_fingerprint` text NOT NULL,
+	`built_at` text NOT NULL,
+	`payload` text NOT NULL
+);

package/migrations/0002_plain_amazoness.sql

@@ -0,0 +1,5 @@
+CREATE TABLE `fit_baseline` (
+	`id` integer PRIMARY KEY NOT NULL,
+	`captured_at` integer NOT NULL,
+	`payload` text NOT NULL
+);

package/migrations/0003_mysterious_khan.sql

@@ -0,0 +1,6 @@
+CREATE TABLE `session_tool_payload` (
+	`session_id` text PRIMARY KEY NOT NULL,
+	`tool` text NOT NULL,
+	`payload` text NOT NULL,
+	FOREIGN KEY (`session_id`) REFERENCES `sessions`(`id`) ON UPDATE no action ON DELETE cascade
+);

package/migrations/0004_narrow_bloodscream.sql

@@ -0,0 +1,3 @@
+DROP TABLE `session_checks`;--> statement-breakpoint
+DROP TABLE `session_findings`;--> statement-breakpoint
+ALTER TABLE `sessions` DROP COLUMN `summary`;

package/migrations/0005_lying_luke_cage.sql

@@ -0,0 +1,7 @@
+CREATE TABLE `graph_shard_fragment` (
+	`shard_id` text PRIMARY KEY NOT NULL,
+	`language` text NOT NULL,
+	`cache_key` text NOT NULL,
+	`shard_fingerprint` text NOT NULL,
+	`payload` text NOT NULL
+);

package/migrations/0006_mean_photon.sql

@@ -0,0 +1,12 @@
+CREATE TABLE `tool_baseline_entries` (
+	`tool` text NOT NULL,
+	`fingerprint` text NOT NULL,
+	`payload` text,
+	`captured_at` integer NOT NULL,
+	PRIMARY KEY(`tool`, `fingerprint`)
+);
+--> statement-breakpoint
+CREATE TABLE `tool_baseline_meta` (
+	`tool` text PRIMARY KEY NOT NULL,
+	`captured_at` integer NOT NULL
+);

package/migrations/0007_parallel_chamber.sql

@@ -0,0 +1,3 @@
+DROP TABLE `graph_baseline_meta`;--> statement-breakpoint
+DROP TABLE `graph_baseline_signals`;--> statement-breakpoint
+DROP TABLE `fit_baseline`;

package/migrations/0008_flaky_victor_mancha.sql

@@ -0,0 +1,7 @@
+CREATE TABLE `tool_state` (
+	`tool` text NOT NULL,
+	`key` text NOT NULL,
+	`payload` text,
+	`updated_at` integer NOT NULL,
+	PRIMARY KEY(`tool`, `key`)
+);

package/migrations/0009_stable_tool_identity.sql

@@ -0,0 +1,9 @@
+-- Additive columns for tool stable UUID (ADR-0048). Legacy rows get NULL;
+-- new writes from provenance (when stableId present in manifest) or future
+-- ratchet paths can populate it. The `tool` column retains the human name
+-- for current queries/compat.
+ALTER TABLE `tool_state` ADD COLUMN `stable_id` text;
+--> statement-breakpoint
+ALTER TABLE `tool_baseline_entries` ADD COLUMN `stable_id` text;
+--> statement-breakpoint
+ALTER TABLE `tool_baseline_meta` ADD COLUMN `stable_id` text;

package/migrations/0010_add_timestamp_iso_and_payload_version.sql

@@ -0,0 +1,11 @@
+-- Add columns for timestamp fidelity (original ISO) and basic payload versioning.
+-- Existing rows: timestamp_iso null (hydrate falls back to reconstructed), payload_version defaults to 1.
+-- NOTE: statements are split by drizzle's breakpoint marker so each runs as its
+-- own prepared statement (better-sqlite3 rejects multi-statement strings).
+ALTER TABLE sessions ADD COLUMN timestamp_iso TEXT;
+--> statement-breakpoint
+ALTER TABLE session_tool_payload ADD COLUMN payload_version INTEGER NOT NULL DEFAULT 1;
+--> statement-breakpoint
+-- Backfill timestamp_iso for old rows (approximate from ms epoch).
+-- Note: for exact original, re-persist sessions after upgrade.
+UPDATE sessions SET timestamp_iso = strftime('%Y-%m-%dT%H:%M:%fZ', timestamp / 1000, 'unixepoch') WHERE timestamp_iso IS NULL;

package/migrations/0011_payload_version_safety_and_notes.sql

@@ -0,0 +1,21 @@
+-- Phase 7: Payload schema evolution — outer column safety + notes.
+-- The `payload_version` column is created by migration 0010 (NOT NULL DEFAULT 1).
+-- This migration intentionally carries NO further DDL: SQLite has no
+-- `ADD COLUMN IF NOT EXISTS`, and drizzle's migrator does not emulate it, so
+-- re-adding the column here would fail with "duplicate column name". The
+-- migration exists to document the two-level versioning model and to run a
+-- harmless, idempotent backfill. No JSON rewrite of historical payloads is
+-- performed or required (projection on read is the strategy; see plan + ADR-0050).
+
+-- Notes for operators / future migrations:
+-- * payload_version (created in 0010) = outer storage contract version (bumped
+--   only for host-visible changes between session-store and tools).
+-- * The tool-owned inner version lives as "__version" (number) at the top level
+--   of the JSON blob in the `payload` column.
+-- * Legacy rows (column=1 or absent, or no __version in JSON) are treated as v1
+--   with `fidelity: 'projection'`.
+-- * Migrations on these tables must remain append-only. Backfills only for safe
+--   host columns (timestamp_iso precedent); never rewrite tool JSON.
+
+-- Backfill any rows that somehow missed the DEFAULT (belt-and-suspenders).
+UPDATE session_tool_payload SET payload_version = 1 WHERE payload_version IS NULL;

package/migrations/0012_overrated_talon.sql

@@ -0,0 +1,21 @@
+CREATE TABLE `session_dashboard_contributions` (
+	`session_id` text NOT NULL,
+	`tool` text NOT NULL,
+	`contribution` text NOT NULL,
+	`version` integer DEFAULT 1 NOT NULL,
+	PRIMARY KEY(`session_id`, `tool`),
+	FOREIGN KEY (`session_id`) REFERENCES `sessions`(`id`) ON UPDATE no action ON DELETE cascade
+);
+--> statement-breakpoint
+CREATE TABLE `session_host_metrics` (
+	`session_id` text PRIMARY KEY NOT NULL,
+	`tty_busy_ms` integer,
+	`render_ms` integer,
+	`persist_ms` integer,
+	`egress_ms` integer,
+	`total_command_ms` integer,
+	FOREIGN KEY (`session_id`) REFERENCES `sessions`(`id`) ON UPDATE no action ON DELETE cascade
+);
+--> statement-breakpoint
+ALTER TABLE `sessions` ADD `completed_at` integer;--> statement-breakpoint
+ALTER TABLE `sessions` ADD `completed_at_iso` text;

package/migrations/0013_lovely_zarda.sql

@@ -0,0 +1 @@
+DROP TABLE `session_dashboard_contributions`;