@cleocode/core 2026.6.12 → 2026.6.13

package/dist/store/selfimprove-dhq-schema.d.ts

@@ -0,0 +1,284 @@
+/**
+ * Drizzle ORM schema for the **self-improvement DHQ** table (`selfimprove_dhq`),
+ * the durable sink for the P5 self-improvement loop (T11889 · T11889-A · T11911).
+ *
+ * One row per Dogfood-Harness-Question (DHQ) emitted by `cleo selfimprove run`:
+ * the loop replays a canned dogfood scenario, diffs the resulting LAFS envelopes
+ * against a golden, and — on regression — UPSERTs exactly ONE row here through the
+ * leased Gate-3 accessor ({@link ./selfimprove-dhq-store.ts}). On green it writes
+ * nothing. The table is dual-scope: co-located inside EACH scope's consolidated
+ * `cleo.db` (project + global) via the `drizzle-cleo-project` / `drizzle-cleo-global`
+ * migration sets, exactly like the `_writer_leases` (T11627) and `pi_session_*`
+ * (T11899) runtime-infrastructure tables. It is NOT part of the exodus target shape
+ * under `schema/cleo-project/`.
+ *
+ * ## Idempotency invariant — at most ONE open DHQ per `question_hash`
+ *
+ * A repeated regression must UPSERT the SAME open row rather than spam N duplicates.
+ * This is enforced by the **partial UNIQUE index**
+ * `ux_selfimprove_dhq_open ON selfimprove_dhq (question_hash) WHERE status = 'open'`.
+ * drizzle-orm does **not** surface partial-`WHERE` indexes in its typed schema API
+ * (cf. `writer-lease-schema.ts` `_writer_leases.active`, `conduit-schema.ts`
+ * `project_agent_refs.enabled`), so the partial index is emitted as **raw SQL in the
+ * baseline migration** — this module declares only the full-column table plus the two
+ * non-partial indexes drizzle CAN model. The runtime bootstrap asserts the partial
+ * index exists via {@link assertSelfimproveDhqOpenIndexPresent} so a missing index
+ * (a migration that never ran, or a dropped index) fails loudly instead of silently
+ * permitting two open rows for the same `question_hash`.
+ *
+ * @module
+ * @task T11911
+ * @task T11889
+ * @epic T11889
+ * @see ./selfimprove-dhq-store.ts — the Gate-3 accessor over these tables
+ * @see ./writer-lease-schema.ts — the partial-UNIQUE-index-via-raw-SQL precedent
+ * @see ../../migrations/drizzle-cleo-project — project migration (raw partial index)
+ * @see ../../migrations/drizzle-cleo-global — global migration (raw partial index)
+ */
+import type { DatabaseSync } from 'node:sqlite';
+/**
+ * The physical name of the self-improvement DHQ table. Exported so the engine, the
+ * store accessor, the bootstrap assertion, and tests all reference one source of
+ * truth.
+ */
+export declare const SELFIMPROVE_DHQ_TABLE: "selfimprove_dhq";
+/**
+ * The physical name of the partial-UNIQUE active-row index (`WHERE status = 'open'`).
+ * Asserted present at bootstrap because drizzle cannot emit it — it lives as raw SQL
+ * in the baseline migration.
+ */
+export declare const SELFIMPROVE_DHQ_OPEN_INDEX: "ux_selfimprove_dhq_open";
+/**
+ * `selfimprove_dhq` — one row per self-improvement-loop DHQ.
+ *
+ * The at-most-one-open-per-`question_hash` invariant is enforced by the raw-SQL
+ * partial-UNIQUE index `ux_selfimprove_dhq_open ON selfimprove_dhq (question_hash)
+ * WHERE status = 'open'` (emitted in the baseline migration — drizzle cannot model
+ * partial `WHERE`). This declaration intentionally carries only the full-column
+ * table plus the two non-partial indexes; do NOT add a `.unique()` on
+ * `question_hash` here (it would emit a NON-partial unique that wrongly forbids a
+ * second non-open row for the same hash).
+ */
+export declare const selfimproveDhq: import("drizzle-orm/sqlite-core").SQLiteTableWithColumns<{
+    name: "selfimprove_dhq";
+    schema: undefined;
+    columns: {
+        id: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: string;
+            tableName: "selfimprove_dhq";
+            dataType: "number int53";
+            data: number;
+            driverParam: number;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: true;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}>;
+        dhqId: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: string;
+            tableName: "selfimprove_dhq";
+            dataType: "string";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}>;
+        scenario: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: string;
+            tableName: "selfimprove_dhq";
+            dataType: "string";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}>;
+        questionHash: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: string;
+            tableName: "selfimprove_dhq";
+            dataType: "string";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}>;
+        title: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: string;
+            tableName: "selfimprove_dhq";
+            dataType: "string";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}>;
+        regressionJson: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: string;
+            tableName: "selfimprove_dhq";
+            dataType: "string";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}>;
+        status: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: string;
+            tableName: "selfimprove_dhq";
+            dataType: "string";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}>;
+        severity: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: string;
+            tableName: "selfimprove_dhq";
+            dataType: "string";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}>;
+        prUrl: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: string;
+            tableName: "selfimprove_dhq";
+            dataType: "string";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}>;
+        runId: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: string;
+            tableName: "selfimprove_dhq";
+            dataType: "string";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}>;
+        createdAt: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: string;
+            tableName: "selfimprove_dhq";
+            dataType: "number int53";
+            data: number;
+            driverParam: number;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}>;
+        updatedAt: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: string;
+            tableName: "selfimprove_dhq";
+            dataType: "number int53";
+            data: number;
+            driverParam: number;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}>;
+    };
+    dialect: "sqlite";
+}>;
+/**
+ * Assert that the raw-SQL partial-UNIQUE open-row index is physically present on the
+ * given native `cleo.db` handle.
+ *
+ * Because drizzle cannot emit a partial-`WHERE` index, the at-most-one-open-DHQ
+ * invariant depends entirely on the hand-written baseline migration having run. This
+ * check makes a missing index a loud, immediate failure at bootstrap rather than a
+ * silent loss of the idempotency guarantee (which would let the loop spam duplicate
+ * open rows).
+ *
+ * @param nativeDb - The native `DatabaseSync` handle for a scope's `cleo.db`.
+ * @throws {Error} `E_SELFIMPROVE_DHQ_INDEX_MISSING` if `ux_selfimprove_dhq_open` is
+ *   absent (the migration did not run, or the partial index was dropped).
+ *
+ * @example
+ * ```ts
+ * const nativeDb = (handle.db as { $client: DatabaseSync }).$client;
+ * assertSelfimproveDhqOpenIndexPresent(nativeDb); // throws if the index is missing
+ * ```
+ *
+ * @task T11911
+ */
+export declare function assertSelfimproveDhqOpenIndexPresent(nativeDb: DatabaseSync): void;
+//# sourceMappingURL=selfimprove-dhq-schema.d.ts.map

package/dist/store/selfimprove-dhq-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"selfimprove-dhq-schema.d.ts","sourceRoot":"","sources":["../../src/store/selfimprove-dhq-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAGhD;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,EAAG,iBAA0B,CAAC;AAEhE;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,EAAG,yBAAkC,CAAC;AAE7E;;;;;;;;;;GAUG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAmC1B,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,oCAAoC,CAAC,QAAQ,EAAE,YAAY,GAAG,IAAI,CAajF"}

package/dist/store/selfimprove-dhq-schema.js

@@ -0,0 +1,128 @@
+/**
+ * Drizzle ORM schema for the **self-improvement DHQ** table (`selfimprove_dhq`),
+ * the durable sink for the P5 self-improvement loop (T11889 · T11889-A · T11911).
+ *
+ * One row per Dogfood-Harness-Question (DHQ) emitted by `cleo selfimprove run`:
+ * the loop replays a canned dogfood scenario, diffs the resulting LAFS envelopes
+ * against a golden, and — on regression — UPSERTs exactly ONE row here through the
+ * leased Gate-3 accessor ({@link ./selfimprove-dhq-store.ts}). On green it writes
+ * nothing. The table is dual-scope: co-located inside EACH scope's consolidated
+ * `cleo.db` (project + global) via the `drizzle-cleo-project` / `drizzle-cleo-global`
+ * migration sets, exactly like the `_writer_leases` (T11627) and `pi_session_*`
+ * (T11899) runtime-infrastructure tables. It is NOT part of the exodus target shape
+ * under `schema/cleo-project/`.
+ *
+ * ## Idempotency invariant — at most ONE open DHQ per `question_hash`
+ *
+ * A repeated regression must UPSERT the SAME open row rather than spam N duplicates.
+ * This is enforced by the **partial UNIQUE index**
+ * `ux_selfimprove_dhq_open ON selfimprove_dhq (question_hash) WHERE status = 'open'`.
+ * drizzle-orm does **not** surface partial-`WHERE` indexes in its typed schema API
+ * (cf. `writer-lease-schema.ts` `_writer_leases.active`, `conduit-schema.ts`
+ * `project_agent_refs.enabled`), so the partial index is emitted as **raw SQL in the
+ * baseline migration** — this module declares only the full-column table plus the two
+ * non-partial indexes drizzle CAN model. The runtime bootstrap asserts the partial
+ * index exists via {@link assertSelfimproveDhqOpenIndexPresent} so a missing index
+ * (a migration that never ran, or a dropped index) fails loudly instead of silently
+ * permitting two open rows for the same `question_hash`.
+ *
+ * @module
+ * @task T11911
+ * @task T11889
+ * @epic T11889
+ * @see ./selfimprove-dhq-store.ts — the Gate-3 accessor over these tables
+ * @see ./writer-lease-schema.ts — the partial-UNIQUE-index-via-raw-SQL precedent
+ * @see ../../migrations/drizzle-cleo-project — project migration (raw partial index)
+ * @see ../../migrations/drizzle-cleo-global — global migration (raw partial index)
+ */
+import { index, integer, sqliteTable, text } from 'drizzle-orm/sqlite-core';
+/**
+ * The physical name of the self-improvement DHQ table. Exported so the engine, the
+ * store accessor, the bootstrap assertion, and tests all reference one source of
+ * truth.
+ */
+export const SELFIMPROVE_DHQ_TABLE = 'selfimprove_dhq';
+/**
+ * The physical name of the partial-UNIQUE active-row index (`WHERE status = 'open'`).
+ * Asserted present at bootstrap because drizzle cannot emit it — it lives as raw SQL
+ * in the baseline migration.
+ */
+export const SELFIMPROVE_DHQ_OPEN_INDEX = 'ux_selfimprove_dhq_open';
+/**
+ * `selfimprove_dhq` — one row per self-improvement-loop DHQ.
+ *
+ * The at-most-one-open-per-`question_hash` invariant is enforced by the raw-SQL
+ * partial-UNIQUE index `ux_selfimprove_dhq_open ON selfimprove_dhq (question_hash)
+ * WHERE status = 'open'` (emitted in the baseline migration — drizzle cannot model
+ * partial `WHERE`). This declaration intentionally carries only the full-column
+ * table plus the two non-partial indexes; do NOT add a `.unique()` on
+ * `question_hash` here (it would emit a NON-partial unique that wrongly forbids a
+ * second non-open row for the same hash).
+ */
+export const selfimproveDhq = sqliteTable(SELFIMPROVE_DHQ_TABLE, {
+    /** Surrogate primary key (autoincrement via INTEGER PRIMARY KEY rowid alias). */
+    id: integer('id').primaryKey(),
+    /** Stable `'DHQ-###'` handle for the question. */
+    dhqId: text('dhq_id').notNull(),
+    /** The scenario name replayed when this DHQ was raised. */
+    scenario: text('scenario').notNull(),
+    /** sha256 of the normalized regression signature — the idempotency key. */
+    questionHash: text('question_hash').notNull(),
+    /** Human-readable DHQ title. */
+    title: text('title').notNull(),
+    /** The envelope-diff payload (the evidence) as serialized JSON. */
+    regressionJson: text('regression_json').notNull(),
+    /**
+     * Lifecycle status — `open` while the regression is live; advanced to a terminal
+     * value as the DHQ is worked. The partial-UNIQUE index keys on `status = 'open'`.
+     */
+    status: text('status').notNull().default('open'),
+    /** Severity classification (nullable until triaged), e.g. `P0`..`P3`. */
+    severity: text('severity'),
+    /** The draft PR URL once egress fires (nullable until a PR is opened). */
+    prUrl: text('pr_url'),
+    /** Ties the row to ONE loop run. */
+    runId: text('run_id').notNull(),
+    /** Creation timestamp (epoch ms). */
+    createdAt: integer('created_at').notNull(),
+    /** Last-update timestamp (epoch ms). */
+    updatedAt: integer('updated_at').notNull(),
+}, (table) => [
+    index('ix_selfimprove_dhq_status').on(table.status),
+    index('ix_selfimprove_dhq_scenario').on(table.scenario),
+]);
+/**
+ * Assert that the raw-SQL partial-UNIQUE open-row index is physically present on the
+ * given native `cleo.db` handle.
+ *
+ * Because drizzle cannot emit a partial-`WHERE` index, the at-most-one-open-DHQ
+ * invariant depends entirely on the hand-written baseline migration having run. This
+ * check makes a missing index a loud, immediate failure at bootstrap rather than a
+ * silent loss of the idempotency guarantee (which would let the loop spam duplicate
+ * open rows).
+ *
+ * @param nativeDb - The native `DatabaseSync` handle for a scope's `cleo.db`.
+ * @throws {Error} `E_SELFIMPROVE_DHQ_INDEX_MISSING` if `ux_selfimprove_dhq_open` is
+ *   absent (the migration did not run, or the partial index was dropped).
+ *
+ * @example
+ * ```ts
+ * const nativeDb = (handle.db as { $client: DatabaseSync }).$client;
+ * assertSelfimproveDhqOpenIndexPresent(nativeDb); // throws if the index is missing
+ * ```
+ *
+ * @task T11911
+ */
+export function assertSelfimproveDhqOpenIndexPresent(nativeDb) {
+    const row = nativeDb
+        .prepare(`SELECT name FROM sqlite_master WHERE type = 'index' AND name = ?`)
+        .get(SELFIMPROVE_DHQ_OPEN_INDEX);
+    if (!row) {
+        throw new Error(`E_SELFIMPROVE_DHQ_INDEX_MISSING: partial-unique open-row index ` +
+            `"${SELFIMPROVE_DHQ_OPEN_INDEX}" is absent from this cleo.db. The DHQ ` +
+            `baseline migration (drizzle-cleo-{project,global}/…_t11889-selfimprove-dhq) ` +
+            `did not run, so the at-most-one-open-DHQ-per-question_hash invariant is ` +
+            `unenforced.`);
+    }
+}
+//# sourceMappingURL=selfimprove-dhq-schema.js.map

package/dist/store/selfimprove-dhq-schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"selfimprove-dhq-schema.js","sourceRoot":"","sources":["../../src/store/selfimprove-dhq-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAGH,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,yBAAyB,CAAC;AAE5E;;;;GAIG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,iBAA0B,CAAC;AAEhE;;;;GAIG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,yBAAkC,CAAC;AAE7E;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,WAAW,CACvC,qBAAqB,EACrB;IACE,iFAAiF;IACjF,EAAE,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC,UAAU,EAAE;IAC9B,kDAAkD;IAClD,KAAK,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC,OAAO,EAAE;IAC/B,2DAA2D;IAC3D,QAAQ,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC,OAAO,EAAE;IACpC,2EAA2E;IAC3E,YAAY,EAAE,IAAI,CAAC,eAAe,CAAC,CAAC,OAAO,EAAE;IAC7C,gCAAgC;IAChC,KAAK,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC,OAAO,EAAE;IAC9B,mEAAmE;IACnE,cAAc,EAAE,IAAI,CAAC,iBAAiB,CAAC,CAAC,OAAO,EAAE;IACjD;;;OAGG;IACH,MAAM,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC;IAChD,yEAAyE;IACzE,QAAQ,EAAE,IAAI,CAAC,UAAU,CAAC;IAC1B,0EAA0E;IAC1E,KAAK,EAAE,IAAI,CAAC,QAAQ,CAAC;IACrB,oCAAoC;IACpC,KAAK,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC,OAAO,EAAE;IAC/B,qCAAqC;IACrC,SAAS,EAAE,OAAO,CAAC,YAAY,CAAC,CAAC,OAAO,EAAE;IAC1C,wCAAwC;IACxC,SAAS,EAAE,OAAO,CAAC,YAAY,CAAC,CAAC,OAAO,EAAE;CAC3C,EACD,CAAC,KAAK,EAAE,EAAE,CAAC;IACT,KAAK,CAAC,2BAA2B,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC;IACnD,KAAK,CAAC,6BAA6B,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC;CACxD,CACF,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,oCAAoC,CAAC,QAAsB;IACzE,MAAM,GAAG,GAAG,QAAQ;SACjB,OAAO,CAAC,kEAAkE,CAAC;SAC3E,GAAG,CAAC,0BAA0B,CAAiC,CAAC;IACnE,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,MAAM,IAAI,KAAK,CACb,iEAAiE;YAC/D,IAAI,0BAA0B,yCAAyC;YACvE,8EAA8E;YAC9E,0EAA0E;YAC1E,aAAa,CAChB,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/store/selfimprove-dhq-store.d.ts

@@ -0,0 +1,175 @@
+/**
+ * Store-layer accessor for the self-improvement DHQ table (`selfimprove_dhq`) —
+ * T11889 · T11889-A · T11911.
+ *
+ * This module is the ONLY place that touches the native `cleo.db` handle for the
+ * self-improvement loop's DHQ persistence. It lives INSIDE the store chokepoint
+ * (`packages/core/src/store/**`), the Gate-3 allowlist, so it may extract the native
+ * `DatabaseSync` that {@link openDualScopeDb} already holds (via drizzle's `$client`)
+ * and run prepared statements over it — exactly the established `pi-session-store.ts`
+ * pattern. It NEVER calls `new DatabaseSync(` itself.
+ *
+ * The durable adapter (`packages/core/src/selfimprove/dhq-adapter.ts`, T11889-C)
+ * sits OUTSIDE the chokepoint, so it must NOT open a raw handle; it calls these
+ * accessors and wraps every WRITE in `withWriterLease('project', 'bulk', …)` so the
+ * write is serialized against any other writer on the `(project, bulk)` lane. The
+ * lease SERIALIZES the write; the "only ever writes `selfimprove_dhq`, never a live
+ * `tasks`/`brain` row" guarantee comes from this accessor's prepared statements
+ * targeting ONLY `selfimprove_dhq` — adapter discipline, not the lease.
+ *
+ * Physical model (see the `t11889-selfimprove-dhq` migration):
+ *  - `selfimprove_dhq(id, dhq_id, scenario, question_hash, title, regression_json,
+ *    status, severity, pr_url, run_id, created_at, updated_at)` — one row per DHQ.
+ *  - Idempotency: a raw-SQL partial-UNIQUE index `ux_selfimprove_dhq_open` keys on
+ *    `question_hash WHERE status = 'open'`, so at most one open row per hash.
+ *
+ * @module
+ * @task T11911
+ * @task T11889
+ * @epic T11889
+ */
+export { assertSelfimproveDhqOpenIndexPresent, SELFIMPROVE_DHQ_OPEN_INDEX, SELFIMPROVE_DHQ_TABLE, } from './selfimprove-dhq-schema.js';
+/** A persisted DHQ row, decoded from `selfimprove_dhq`. */
+export interface SelfimproveDhqRow {
+    /** Stable `'DHQ-###'` handle for the question. */
+    readonly dhqId: string;
+    /** The scenario name replayed when this DHQ was raised. */
+    readonly scenario: string;
+    /** sha256 of the normalized regression signature — the idempotency key. */
+    readonly questionHash: string;
+    /** Human-readable DHQ title. */
+    readonly title: string;
+    /** The envelope-diff payload (the evidence) as serialized JSON. */
+    readonly regressionJson: string;
+    /** Lifecycle status — `'open'` while the regression is live. */
+    readonly status: string;
+    /** Severity classification, or `null` until triaged. */
+    readonly severity: string | null;
+    /** The draft PR URL once egress fires, or `null`. */
+    readonly prUrl: string | null;
+    /** Ties the row to ONE loop run. */
+    readonly runId: string;
+    /** Creation timestamp (epoch ms). */
+    readonly createdAt: number;
+    /** Last-update timestamp (epoch ms). */
+    readonly updatedAt: number;
+}
+/**
+ * Fields required to UPSERT one open DHQ. `status` is fixed to `'open'` by the
+ * accessor (the partial-UNIQUE index keys on it); terminal-status transitions go
+ * through {@link updateSelfimproveDhqStatus} instead.
+ */
+export interface SelfimproveDhqUpsert {
+    /** Stable `'DHQ-###'` handle (used only on first insert for a hash). */
+    readonly dhqId: string;
+    /** The scenario name replayed. */
+    readonly scenario: string;
+    /** sha256 of the normalized regression signature — the idempotency key. */
+    readonly questionHash: string;
+    /** Human-readable DHQ title. */
+    readonly title: string;
+    /** The envelope-diff payload (the evidence) as serialized JSON. */
+    readonly regressionJson: string;
+    /** Severity classification, or `null` until triaged. */
+    readonly severity: string | null;
+    /** Ties the row to ONE loop run. */
+    readonly runId: string;
+    /** The timestamp to stamp on insert/update (epoch ms). */
+    readonly now: number;
+}
+/** Narrow shape of the native handle methods this accessor uses. */
+type NativeRunResult = {
+    changes: number | bigint;
+    lastInsertRowid: number | bigint;
+};
+interface NativeStatement {
+    run(...params: ReadonlyArray<string | number | null>): NativeRunResult;
+    get(...params: ReadonlyArray<string | number | null>): Record<string, unknown> | undefined;
+    all(...params: ReadonlyArray<string | number | null>): Array<Record<string, unknown>>;
+}
+interface NativeHandle {
+    prepare(sql: string): NativeStatement;
+}
+/**
+ * Extract the native `DatabaseSync` handle for the PROJECT-scope `cleo.db`.
+ *
+ * Routes through {@link openDualScopeDb} (the dual-scope chokepoint) — which applies
+ * the pragma SSoT, runs the consolidated migrations (creating `selfimprove_dhq`),
+ * and manages the singleton cache — then extracts the native handle drizzle holds on
+ * `$client`. NEVER opens a raw connection (Gate 3): it reuses the handle the
+ * chokepoint already owns.
+ *
+ * @param cwd - Working directory for project resolution (defaults to `cwd`).
+ * @returns The live native handle.
+ * @throws When the chokepoint returns a handle without `$client`.
+ */
+export declare function getSelfimproveDhqNativeDb(cwd?: string): Promise<NativeHandle>;
+/**
+ * Return the open DHQ row for a `question_hash`, or `null` when none is open.
+ *
+ * @param native - The native project `cleo.db` handle.
+ * @param questionHash - The regression-signature hash.
+ * @returns The open row or `null`.
+ */
+export declare function readOpenSelfimproveDhq(native: NativeHandle, questionHash: string): SelfimproveDhqRow | null;
+/**
+ * Return all DHQ rows for a scenario in stable creation order (`created_at ASC`).
+ *
+ * @param native - The native project `cleo.db` handle.
+ * @param scenario - The scenario name.
+ * @returns The ordered rows (empty when the scenario has none).
+ */
+export declare function readSelfimproveDhqByScenario(native: NativeHandle, scenario: string): SelfimproveDhqRow[];
+/**
+ * Insert (or, on a repeated open regression, refresh) exactly ONE open DHQ row for a
+ * `question_hash`.
+ *
+ * The partial-UNIQUE index `ux_selfimprove_dhq_open (question_hash) WHERE status =
+ * 'open'` makes this idempotent: a second open regression for the same hash updates
+ * the existing open row's `updated_at` / `run_id` / `severity` instead of inserting a
+ * duplicate. The caller MUST already hold the PROJECT/`bulk` writer lease — this
+ * accessor performs the raw write and does NOT acquire the lease itself (the lease
+ * boundary lives in `dhq-adapter.ts`, outside the chokepoint).
+ *
+ * @param native - The native project `cleo.db` handle (leased section).
+ * @param row - The DHQ to upsert.
+ */
+export declare function upsertOpenSelfimproveDhq(native: NativeHandle, row: SelfimproveDhqUpsert): void;
+/**
+ * Advance an open DHQ to a terminal status (e.g. `'fixed'` / `'dismissed'`) for a
+ * `question_hash`. Frees the partial-UNIQUE slot so a future regression of the same
+ * hash can open a new row.
+ *
+ * The caller MUST hold the writer lease.
+ *
+ * @param native - The native project `cleo.db` handle (leased section).
+ * @param questionHash - The regression-signature hash whose open row to advance.
+ * @param status - The new (non-open) status.
+ * @param now - The update timestamp (epoch ms).
+ * @returns The number of rows updated (0 when no open row exists).
+ */
+export declare function updateSelfimproveDhqStatus(native: NativeHandle, questionHash: string, status: string, now: number): number;
+/**
+ * Record the draft PR URL on the open DHQ row for a `question_hash`.
+ *
+ * The caller MUST hold the writer lease.
+ *
+ * @param native - The native project `cleo.db` handle (leased section).
+ * @param questionHash - The regression-signature hash whose open row to annotate.
+ * @param prUrl - The draft PR URL.
+ * @param now - The update timestamp (epoch ms).
+ * @returns The number of rows updated (0 when no open row exists).
+ */
+export declare function setSelfimproveDhqPrUrl(native: NativeHandle, questionHash: string, prUrl: string, now: number): number;
+/**
+ * Bootstrap check: open the project `cleo.db` (running migrations) and assert the
+ * partial-UNIQUE open-row index is physically present.
+ *
+ * Convenience wrapper over {@link getSelfimproveDhqNativeDb} +
+ * {@link assertSelfimproveDhqOpenIndexPresent} for callers that only have a `cwd`.
+ *
+ * @param cwd - Working directory for project resolution.
+ * @throws `E_SELFIMPROVE_DHQ_INDEX_MISSING` if the index is absent.
+ */
+export declare function assertSelfimproveDhqReady(cwd?: string): Promise<void>;
+//# sourceMappingURL=selfimprove-dhq-store.d.ts.map

package/dist/store/selfimprove-dhq-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"selfimprove-dhq-store.d.ts","sourceRoot":"","sources":["../../src/store/selfimprove-dhq-store.ts"],"names":[],"mappings":"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"}