hippo-memory 1.69.0 → 1.71.0

package/dist/store/connectors/github.js

@@ -0,0 +1,180 @@
+// The GitHub connector's tables: event log, dead-letter queue, tenant routing and backfill cursors.
+import { withWriteScope } from '../../db/index.js';
+import { archiveRawMemory } from '../raw-archive.js';
+import { onHandle } from '../open.js';
+export function eventSeenAt(db, idempotencyKey) {
+    const row = db.prepare(`SELECT 1 FROM github_event_log WHERE idempotency_key = ?`).get(idempotencyKey);
+    return !!row;
+}
+export function eventMemoryAt(db, idempotencyKey) {
+    // SAFETY: the SELECT projects exactly the memory_id column of github_event_log.
+    const row = db.prepare(`SELECT memory_id FROM github_event_log WHERE idempotency_key = ?`).get(idempotencyKey);
+    return row?.memory_id ?? null;
+}
+/** False when the key was already logged, so a caller inside a write scope can roll its own row back. */
+export function logEventAt(db, entry) {
+    const inserted = db.prepare(`INSERT OR IGNORE INTO github_event_log (idempotency_key, delivery_id, event_name, ingested_at, memory_id) VALUES (?, ?, ?, ?, ?)`).run(entry.idempotencyKey, entry.deliveryId, entry.eventName, new Date().toISOString(), entry.memoryId);
+    return Number(inserted.changes ?? 0) !== 0;
+}
+/** The memory an already-seen key points at, or null when the key is new. */
+export function seenEvent(hippoRoot, idempotencyKey) {
+    return onHandle(hippoRoot, (db) => eventSeenAt(db, idempotencyKey) ? { memoryId: eventMemoryAt(db, idempotencyKey) } : null);
+}
+export function logEvent(hippoRoot, entry) {
+    onHandle(hippoRoot, (db) => { logEventAt(db, entry); });
+}
+/** Archives every active raw row of one tenant's artifact and logs the delete event; a failed archive rolls back the batch and the log row. */
+export function archiveDeletedArtifact(hippoRoot, del) {
+    return onHandle(hippoRoot, (db) => {
+        if (eventSeenAt(db, del.idempotencyKey))
+            return { duplicate: true, archived: 0 };
+        const logged = { idempotencyKey: del.idempotencyKey, deliveryId: del.deliveryId, eventName: del.eventName };
+        // SAFETY: the SELECT projects only the `id` column.
+        const rows = db
+            .prepare(`SELECT id FROM memories WHERE artifact_ref = ? AND tenant_id = ? AND kind = 'raw'`)
+            .all(del.artifactRef, del.tenantId);
+        const memoryIds = rows.map((r) => r.id);
+        if (memoryIds.length === 0) {
+            // Still logged, so a retry of the same delete answers 'duplicate'.
+            logEventAt(db, { ...logged, memoryId: null });
+            return { duplicate: false, archived: 0 };
+        }
+        withWriteScope(db, 'github_delete_all', () => {
+            for (const id of memoryIds)
+                archiveRawMemory(db, id, { reason: del.reason, who: del.who });
+            logEventAt(db, { ...logged, memoryId: memoryIds[0] });
+        });
+        return { duplicate: false, archived: memoryIds.length };
+    });
+}
+function insertGitHubDlqAt(db, row) {
+    const result = db
+        .prepare(`INSERT INTO github_dlq
+        (tenant_id, raw_payload, error, event_name, delivery_id, signature,
+         installation_id, repo_full_name, received_at, bucket)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+        .run(row.tenantId, row.rawPayload, row.error, row.eventName ?? null, row.deliveryId ?? null, row.signature, row.installationId ?? null, row.repoFullName ?? null, new Date().toISOString(), row.bucket);
+    return Number(result.lastInsertRowid);
+}
+export function insertGitHubDlq(hippoRoot, row) {
+    return onHandle(hippoRoot, (db) => insertGitHubDlqAt(db, row));
+}
+const SELECT_COLUMNS = `id, tenant_id, raw_payload, error, event_name, delivery_id,
+            signature, installation_id, repo_full_name, retry_count,
+            received_at, retried_at, bucket`;
+function rowToItem(r) {
+    return {
+        id: Number(r.id),
+        tenantId: String(r.tenant_id),
+        rawPayload: String(r.raw_payload),
+        error: String(r.error),
+        eventName: r.event_name == null ? null : String(r.event_name),
+        deliveryId: r.delivery_id == null ? null : String(r.delivery_id),
+        signature: r.signature == null ? null : String(r.signature),
+        installationId: r.installation_id == null ? null : String(r.installation_id),
+        repoFullName: r.repo_full_name == null ? null : String(r.repo_full_name),
+        retryCount: Number(r.retry_count ?? 0),
+        receivedAt: String(r.received_at),
+        retriedAt: r.retried_at == null ? null : String(r.retried_at),
+        bucket: r.bucket == null ? 'parse_error' : String(r.bucket),
+    };
+}
+function listGitHubDlqAt(db, tenantId, limit) {
+    // SAFETY: SELECT_COLUMNS projects exactly DlqRawRow's fields.
+    const rows = db
+        .prepare(`SELECT ${SELECT_COLUMNS}
+         FROM github_dlq
+        WHERE tenant_id = ?
+        ORDER BY received_at ASC
+        LIMIT ?`)
+        .all(tenantId, limit);
+    return rows.map(rowToItem);
+}
+export function listGitHubDlq(hippoRoot, tenantId, limit) {
+    return onHandle(hippoRoot, (db) => listGitHubDlqAt(db, tenantId, limit));
+}
+function githubDlqEntryAt(db, id) {
+    // SAFETY: SELECT_COLUMNS projects exactly DlqRawRow's fields.
+    const row = db
+        .prepare(`SELECT ${SELECT_COLUMNS}
+         FROM github_dlq
+        WHERE id = ?`)
+        .get(id);
+    if (!row)
+        return null;
+    return rowToItem(row);
+}
+export function githubDlqEntry(hippoRoot, id) {
+    return onHandle(hippoRoot, (db) => githubDlqEntryAt(db, id));
+}
+export function bumpGitHubDlqRetryCount(hippoRoot, id) {
+    onHandle(hippoRoot, (db) => {
+        db.prepare(`UPDATE github_dlq
+          SET retry_count = retry_count + 1,
+              retried_at = ?
+        WHERE id = ?`).run(new Date().toISOString(), id);
+    });
+}
+export function githubRouting(hippoRoot, args) {
+    return onHandle(hippoRoot, (db) => {
+        // SAFETY: the SELECT projects exactly one column, `c`, as a COUNT(*).
+        const instCount = db
+            .prepare(`SELECT COUNT(*) AS c FROM github_installations`)
+            .get().c;
+        // SAFETY: the SELECT projects exactly one column, `c`, as a COUNT(*).
+        const repoCount = db
+            .prepare(`SELECT COUNT(*) AS c FROM github_repositories`)
+            .get().c;
+        const counts = { installations: Number(instCount), repositories: Number(repoCount) };
+        if (args.installationId) {
+            // SAFETY: the SELECT projects exactly the tenant_id column of github_installations.
+            const row = db
+                .prepare(`SELECT tenant_id FROM github_installations WHERE installation_id = ?`)
+                .get(args.installationId);
+            return { ...counts, tenant: row?.tenant_id ?? null };
+        }
+        if ((counts.installations === 0 && counts.repositories === 0) || !args.repoFullName) {
+            return { ...counts, tenant: null };
+        }
+        // SAFETY: the SELECT projects exactly the tenant_id column of github_repositories.
+        const row = db
+            .prepare(`SELECT tenant_id FROM github_repositories WHERE repo_full_name = ? ORDER BY added_at, tenant_id LIMIT 1`)
+            .get(args.repoFullName);
+        return { ...counts, tenant: row?.tenant_id ?? null };
+    });
+}
+export function readCursors(hippoRoot, tenantId, repo) {
+    return onHandle(hippoRoot, (db) => {
+        // SAFETY: the SELECT names exactly the three HWM columns.
+        const row = db
+            .prepare(`SELECT issues_hwm, issue_comments_hwm, pr_review_comments_hwm
+         FROM github_cursors WHERE tenant_id = ? AND repo_full_name = ?`)
+            .get(tenantId, repo);
+        return {
+            issues: row?.issues_hwm ?? null,
+            issueComments: row?.issue_comments_hwm ?? null,
+            prReviewComments: row?.pr_review_comments_hwm ?? null,
+        };
+    });
+}
+export function writeHwm(hippoRoot, tenantId, repo, column, value) {
+    onHandle(hippoRoot, (db) => {
+        db.prepare(`INSERT INTO github_cursors (tenant_id, repo_full_name, ${column}, updated_at)
+       VALUES (?, ?, ?, ?)
+       ON CONFLICT(tenant_id, repo_full_name)
+       DO UPDATE SET ${column} = excluded.${column}, updated_at = excluded.updated_at`).run(tenantId, repo, value, new Date().toISOString());
+    });
+}
+/** Sets all three HWMs to `since` for a first run; COALESCE keeps any HWM a stream has already saved. */
+export function seedCursors(hippoRoot, tenantId, repo, since) {
+    onHandle(hippoRoot, (db) => {
+        db.prepare(`INSERT INTO github_cursors (tenant_id, repo_full_name, issues_hwm, issue_comments_hwm, pr_review_comments_hwm, updated_at)
+         VALUES (?, ?, ?, ?, ?, ?)
+         ON CONFLICT(tenant_id, repo_full_name) DO UPDATE SET
+           issues_hwm = COALESCE(github_cursors.issues_hwm, excluded.issues_hwm),
+           issue_comments_hwm = COALESCE(github_cursors.issue_comments_hwm, excluded.issue_comments_hwm),
+           pr_review_comments_hwm = COALESCE(github_cursors.pr_review_comments_hwm, excluded.pr_review_comments_hwm),
+           updated_at = excluded.updated_at`).run(tenantId, repo, since, since, since, new Date().toISOString());
+    });
+}
+//# sourceMappingURL=github.js.map

package/dist/store/connectors/slack.d.ts

@@ -0,0 +1,69 @@
+import type { DatabaseSyncLike } from '../../db/index.js';
+export declare function slackCursorAt(db: DatabaseSyncLike, tenantId: string, channelId: string): string | null;
+export declare function saveSlackCursorAt(db: DatabaseSyncLike, tenantId: string, channelId: string, latestTs: string): void;
+export declare function slackCursor(hippoRoot: string, tenantId: string, channelId: string): string | null;
+export declare function saveSlackCursor(hippoRoot: string, tenantId: string, channelId: string, latestTs: string): void;
+export declare function slackEventSeenAt(db: DatabaseSyncLike, eventId: string): boolean;
+/** Records the event unless a row already holds its id; false means another writer got there first. */
+export declare function markSlackEventSeenAt(db: DatabaseSyncLike, eventId: string, memoryId: string | null): boolean;
+export declare function slackEventMemoryAt(db: DatabaseSyncLike, eventId: string): string | null;
+/** What the event log holds for one event id; `memoryId` is null for an event seen without a memory. */
+export type SlackEventRecord = {
+    seen: false;
+} | {
+    seen: true;
+    memoryId: string | null;
+};
+export declare function slackEventRecord(hippoRoot: string, eventId: string): SlackEventRecord;
+export declare function markSlackEventSeen(hippoRoot: string, eventId: string, memoryId: string | null): void;
+/** The raw memory a Slack message became. The tenant filter keeps one tenant's deletion from reaching another's row with the same ref. */
+export declare function rawMemoryIdForArtifactAt(db: DatabaseSyncLike, artifactRef: string, tenantId: string): string | null;
+export type DlqBucket = 'parse_error' | 'unroutable' | 'signature_fail';
+export interface DlqItem {
+    id: number;
+    tenantId: string;
+    teamId: string | null;
+    rawPayload: string;
+    error: string;
+    receivedAt: string;
+    retriedAt: string | null;
+    bucket: DlqBucket | string;
+    retryCount: number;
+    signature: string | null;
+    slackTimestamp: string | null;
+}
+/** One row to park; the two Slack-only columns are stored NULL when left out. */
+export interface SlackDlqInsert {
+    tenantId: string;
+    teamId?: string | null;
+    rawPayload: string;
+    error: string;
+    bucket: DlqBucket;
+    signature: string | null;
+    slackTimestamp?: string | null;
+}
+/** Counts a failed replay and leaves `retried_at` alone, so the row still reads as never drained. */
+export declare function bumpSlackDlqRetryCountAt(db: DatabaseSyncLike, id: number): void;
+export declare function insertSlackDlq(hippoRoot: string, row: SlackDlqInsert): number;
+export declare function listSlackDlq(hippoRoot: string, tenantId: string, limit: number): DlqItem[];
+export declare function slackDlqEntry(hippoRoot: string, id: number): DlqItem | null;
+export declare function markSlackDlqRetried(hippoRoot: string, id: number): void;
+export declare function bumpSlackDlqRetryCount(hippoRoot: string, id: number): void;
+/** The tenant a team maps to, or how many workspaces are registered when it maps to none. */
+export type SlackTeamRoute = {
+    tenantId: string;
+} | {
+    tenantId: null;
+    workspaceCount: number;
+};
+export declare function slackTeamRouteAt(db: DatabaseSyncLike, teamId: string): SlackTeamRoute;
+export declare function slackTeamRoute(hippoRoot: string, teamId: string): SlackTeamRoute;
+export interface SlackWorkspace {
+    teamId: string;
+    tenantId: string;
+    addedAt: string;
+}
+export declare function upsertSlackWorkspace(hippoRoot: string, teamId: string, tenantId: string): SlackWorkspace;
+export declare function listSlackWorkspaces(hippoRoot: string): SlackWorkspace[];
+export declare function removeSlackWorkspace(hippoRoot: string, teamId: string): boolean;
+//# sourceMappingURL=slack.d.ts.map

package/dist/store/connectors/slack.js

@@ -0,0 +1,177 @@
+// Every statement the Slack connector runs on hippo.db: backfill cursors, the event log, the dead-letter queue and workspace routing.
+// `xAt(db, ...)` runs on the caller's handle; the same name without `At` opens hippo.db for that one call.
+import { onHandle } from '../open.js';
+// Backfill cursors
+export function slackCursorAt(db, tenantId, channelId) {
+    // SAFETY: the SELECT names the single `latest_ts` column; sqlite returns undefined when no row matches.
+    const row = db
+        .prepare(`SELECT latest_ts FROM slack_cursors WHERE tenant_id=? AND channel_id=?`)
+        .get(tenantId, channelId);
+    return row?.latest_ts ?? null;
+}
+export function saveSlackCursorAt(db, tenantId, channelId, latestTs) {
+    db.prepare(`INSERT INTO slack_cursors (tenant_id, channel_id, latest_ts, updated_at) VALUES (?,?,?,?)
+       ON CONFLICT(tenant_id, channel_id) DO UPDATE SET latest_ts = excluded.latest_ts, updated_at = excluded.updated_at`).run(tenantId, channelId, latestTs, new Date().toISOString());
+}
+export function slackCursor(hippoRoot, tenantId, channelId) {
+    return onHandle(hippoRoot, (db) => slackCursorAt(db, tenantId, channelId));
+}
+export function saveSlackCursor(hippoRoot, tenantId, channelId, latestTs) {
+    onHandle(hippoRoot, (db) => saveSlackCursorAt(db, tenantId, channelId, latestTs));
+}
+// Event log
+export function slackEventSeenAt(db, eventId) {
+    const row = db.prepare(`SELECT 1 FROM slack_event_log WHERE event_id = ?`).get(eventId);
+    return !!row;
+}
+/** Records the event unless a row already holds its id; false means another writer got there first. */
+export function markSlackEventSeenAt(db, eventId, memoryId) {
+    const inserted = db
+        .prepare(`INSERT OR IGNORE INTO slack_event_log (event_id, ingested_at, memory_id) VALUES (?, ?, ?)`)
+        .run(eventId, new Date().toISOString(), memoryId);
+    return Number(inserted.changes ?? 0) !== 0;
+}
+export function slackEventMemoryAt(db, eventId) {
+    // SAFETY: the SELECT names only `memory_id`, a nullable column; .get() returns undefined when no row matches.
+    const row = db.prepare(`SELECT memory_id FROM slack_event_log WHERE event_id = ?`).get(eventId);
+    return row?.memory_id ?? null;
+}
+export function slackEventRecord(hippoRoot, eventId) {
+    return onHandle(hippoRoot, (db) => slackEventSeenAt(db, eventId) ? { seen: true, memoryId: slackEventMemoryAt(db, eventId) } : { seen: false });
+}
+export function markSlackEventSeen(hippoRoot, eventId, memoryId) {
+    onHandle(hippoRoot, (db) => markSlackEventSeenAt(db, eventId, memoryId));
+}
+// Deletion lookup
+/** The raw memory a Slack message became. The tenant filter keeps one tenant's deletion from reaching another's row with the same ref. */
+export function rawMemoryIdForArtifactAt(db, artifactRef, tenantId) {
+    // SAFETY: the SELECT projects only `id`; .get() returns undefined when no row matches.
+    const row = db
+        .prepare(`SELECT id FROM memories WHERE artifact_ref = ? AND tenant_id = ? AND kind = 'raw'`)
+        .get(artifactRef, tenantId);
+    return row?.id ?? null;
+}
+function rowToItem(r) {
+    return {
+        id: Number(r.id),
+        tenantId: String(r.tenant_id),
+        teamId: r.team_id == null ? null : String(r.team_id),
+        rawPayload: String(r.raw_payload),
+        error: String(r.error),
+        receivedAt: String(r.received_at),
+        retriedAt: r.retried_at == null ? null : String(r.retried_at),
+        bucket: r.bucket == null ? 'parse_error' : String(r.bucket),
+        retryCount: Number(r.retry_count ?? 0),
+        signature: r.signature == null ? null : String(r.signature),
+        slackTimestamp: r.slack_timestamp == null ? null : String(r.slack_timestamp),
+    };
+}
+function insertSlackDlqAt(db, row) {
+    const result = db
+        .prepare(`INSERT INTO slack_dlq
+        (tenant_id, team_id, raw_payload, error, received_at, bucket, signature, slack_timestamp)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?)`)
+        .run(row.tenantId, row.teamId ?? null, row.rawPayload, row.error, new Date().toISOString(), row.bucket, row.signature, row.slackTimestamp ?? null);
+    return Number(result.lastInsertRowid);
+}
+function listSlackDlqAt(db, tenantId, limit) {
+    // SAFETY: row shape matches the columns named in the SELECT below.
+    const rows = db
+        .prepare(`SELECT id, tenant_id, team_id, raw_payload, error, received_at, retried_at,
+              bucket, retry_count, signature, slack_timestamp
+         FROM slack_dlq
+        WHERE tenant_id = ?
+        ORDER BY received_at ASC
+        LIMIT ?`)
+        .all(tenantId, limit);
+    return rows.map(rowToItem);
+}
+function slackDlqEntryAt(db, id) {
+    // SAFETY: row shape matches the columns named in the SELECT below.
+    const row = db
+        .prepare(`SELECT id, tenant_id, team_id, raw_payload, error, received_at, retried_at,
+              bucket, retry_count, signature, slack_timestamp
+         FROM slack_dlq
+        WHERE id = ?`)
+        .get(id);
+    if (!row)
+        return null;
+    return rowToItem(row);
+}
+function markSlackDlqRetriedAt(db, id) {
+    db.prepare(`UPDATE slack_dlq SET retried_at = ?, retry_count = retry_count + 1 WHERE id = ?`)
+        .run(new Date().toISOString(), id);
+}
+/** Counts a failed replay and leaves `retried_at` alone, so the row still reads as never drained. */
+export function bumpSlackDlqRetryCountAt(db, id) {
+    db.prepare(`UPDATE slack_dlq SET retry_count = retry_count + 1 WHERE id = ?`).run(id);
+}
+export function insertSlackDlq(hippoRoot, row) {
+    return onHandle(hippoRoot, (db) => insertSlackDlqAt(db, row));
+}
+export function listSlackDlq(hippoRoot, tenantId, limit) {
+    return onHandle(hippoRoot, (db) => listSlackDlqAt(db, tenantId, limit));
+}
+export function slackDlqEntry(hippoRoot, id) {
+    return onHandle(hippoRoot, (db) => slackDlqEntryAt(db, id));
+}
+export function markSlackDlqRetried(hippoRoot, id) {
+    onHandle(hippoRoot, (db) => markSlackDlqRetriedAt(db, id));
+}
+export function bumpSlackDlqRetryCount(hippoRoot, id) {
+    onHandle(hippoRoot, (db) => bumpSlackDlqRetryCountAt(db, id));
+}
+export function slackTeamRouteAt(db, teamId) {
+    // SAFETY: the SELECT names only `tenant_id`; .get() returns undefined when no row matches.
+    const row = db
+        .prepare(`SELECT tenant_id FROM slack_workspaces WHERE team_id = ?`)
+        .get(teamId);
+    if (row?.tenant_id)
+        return { tenantId: row.tenant_id };
+    // SAFETY: `COUNT(*) AS c` always returns one row shaped { c }, as a number or a bigint.
+    const total = db
+        .prepare(`SELECT COUNT(*) AS c FROM slack_workspaces`)
+        .get().c;
+    return { tenantId: null, workspaceCount: Number(total) };
+}
+export function slackTeamRoute(hippoRoot, teamId) {
+    return onHandle(hippoRoot, (db) => slackTeamRouteAt(db, teamId));
+}
+/** Upserts on team_id: operators move a workspace between tenants without a delete first. */
+function upsertSlackWorkspaceAt(db, teamId, tenantId) {
+    const addedAt = new Date().toISOString();
+    db.prepare(`INSERT INTO slack_workspaces (team_id, tenant_id, added_at)
+     VALUES (?, ?, ?)
+     ON CONFLICT(team_id) DO UPDATE SET
+       tenant_id = excluded.tenant_id,
+       added_at = excluded.added_at`).run(teamId, tenantId, addedAt);
+    return { teamId, tenantId, addedAt };
+}
+function listSlackWorkspacesAt(db) {
+    // SAFETY: the SELECT names team_id, tenant_id and added_at, all NOT NULL text columns of slack_workspaces.
+    const rows = db
+        .prepare(`SELECT team_id, tenant_id, added_at FROM slack_workspaces ORDER BY team_id`)
+        .all();
+    return rows.map((r) => ({
+        teamId: r.team_id,
+        tenantId: r.tenant_id,
+        addedAt: r.added_at,
+    }));
+}
+/** True when a row was deleted, so the caller can report not-found without a second lookup. */
+function removeSlackWorkspaceAt(db, teamId) {
+    const result = db
+        .prepare(`DELETE FROM slack_workspaces WHERE team_id = ?`)
+        .run(teamId);
+    return Number(result.changes) > 0;
+}
+export function upsertSlackWorkspace(hippoRoot, teamId, tenantId) {
+    return onHandle(hippoRoot, (db) => upsertSlackWorkspaceAt(db, teamId, tenantId));
+}
+export function listSlackWorkspaces(hippoRoot) {
+    return onHandle(hippoRoot, listSlackWorkspacesAt);
+}
+export function removeSlackWorkspace(hippoRoot, teamId) {
+    return onHandle(hippoRoot, (db) => removeSlackWorkspaceAt(db, teamId));
+}
+//# sourceMappingURL=slack.js.map

package/dist/store/dashboard-reads.d.ts

@@ -0,0 +1,27 @@
+import type { ConfidenceInputs, MemoryEntry, StrengthInputs } from '../core/memory.js';
+export type DashboardRow = StrengthInputs & ConfidenceInputs & Pick<MemoryEntry, 'id' | 'content' | 'tags' | 'layer' | 'scope' | 'origin_project' | 'kind' | 'superseded_by'>;
+export interface ExcludedCounts {
+    superseded: number;
+    archived: number;
+    quarantined: number;
+}
+export interface DashboardRows {
+    /** Rows `isLiveMemory` admits, by created then id as `loadAllEntries` orders them. */
+    readonly live: DashboardRow[];
+    /** Every other row of the tenant, counted under the first of quarantined, superseded and archived that fits it. */
+    readonly excluded: ExcludedCounts;
+}
+/** One tenant's live rows and the counts of the rest, read in one transaction so the two agree. */
+export declare function loadDashboardRows(hippoRoot: string, tenantId: string): DashboardRows;
+/** The dashboard's one read-only connection, kept across refreshes for the commit signal; it opens on the first read that finds a database. */
+export declare class DashboardConnection {
+    private readonly hippoRoot;
+    private db;
+    constructor(hippoRoot: string);
+    /** `PRAGMA data_version`, which moves when another connection commits; null while the store has no hippo.db. */
+    dataVersion(): number | null;
+    /** Ids with a stored vector: none before the connection opens, null on a store older than the vector table (schema v52). */
+    embeddedIds(): ReadonlySet<string> | null;
+    close(): void;
+}
+//# sourceMappingURL=dashboard-reads.d.ts.map

package/dist/store/dashboard-reads.js

@@ -0,0 +1,88 @@
+// The dashboard snapshot's read of one tenant: live rows with only the columns it shows, and SQL counts of the rows it leaves out.
+import * as fs from 'fs';
+import { closeHippoDb, getHippoDbPath, openHippoDbReadOnly } from '../db/index.js';
+import { withReadSnapshot } from '../db/busy.js';
+import { pragmaDataVersion } from '../db/meta.js';
+import { tableExists } from '../db/tables.js';
+import { storedVectorIds } from '../db/vector-store.js';
+import { onHandle, openStore } from './open.js';
+import { QUARANTINE_SCOPE_PREFIX } from './quarantine.js';
+import { parseJsonArray } from './rows.js';
+const LIVE_COLUMNS = 'id, created, last_retrieved, retrieval_count, half_life_days, layer, tags_json, emotional_valence, outcome_positive, outcome_negative, pinned, confidence, content, superseded_by, kind, scope, origin_project';
+// SQL twins of isQuarantineScope and of the two halves of isLiveMemory; substr compares bytes, as startsWith does, where LIKE would fold case.
+const QUARANTINED = `(scope IS NOT NULL AND substr(scope, 1, ${QUARANTINE_SCOPE_PREFIX.length}) = '${QUARANTINE_SCOPE_PREFIX}')`;
+const SUPERSEDED_BY = `(superseded_by IS NOT NULL AND superseded_by <> '')`;
+const KIND = `COALESCE(kind, 'distilled')`;
+const LIVE = `NOT ${SUPERSEDED_BY} AND ${KIND} IN ('raw', 'distilled') AND NOT ${QUARANTINED}`;
+// The defaults are rowToEntry's, so a row reads the same here as through the full mapper.
+function toDashboardRow(row) {
+    // SAFETY: layer and kind are columns the write path only fills from those two unions.
+    return {
+        id: row.id,
+        created: row.created,
+        last_retrieved: row.last_retrieved,
+        retrieval_count: Number(row.retrieval_count ?? 0),
+        half_life_days: Number(row.half_life_days ?? 7),
+        layer: row.layer,
+        tags: parseJsonArray(row.tags_json, { table: 'memories', id: row.id, column: 'tags_json' }),
+        emotional_valence: row.emotional_valence ?? 'neutral',
+        outcome_positive: Number(row.outcome_positive ?? 0),
+        outcome_negative: Number(row.outcome_negative ?? 0),
+        pinned: Boolean(row.pinned),
+        confidence: row.confidence ?? 'observed',
+        content: row.content,
+        superseded_by: row.superseded_by ?? null,
+        kind: (row.kind ?? 'distilled'),
+        scope: row.scope ?? null,
+        origin_project: row.origin_project ?? null,
+    };
+}
+/** One tenant's live rows and the counts of the rest, read in one transaction so the two agree. */
+export function loadDashboardRows(hippoRoot, tenantId) {
+    return onHandle(hippoRoot, (db) => {
+        return withReadSnapshot(db, () => {
+            // SAFETY: the SELECT names exactly LiveRow's columns.
+            const live = db.prepare(`SELECT ${LIVE_COLUMNS} FROM memories WHERE tenant_id = ? AND ${LIVE} ORDER BY created ASC, id ASC`).all(tenantId);
+            // SAFETY: the SELECT names exactly these two fields, and `why` is one of the three CASE arms or NULL.
+            const counts = db.prepare(`
+        SELECT CASE WHEN ${QUARANTINED} THEN 'quarantined' WHEN ${SUPERSEDED_BY} OR ${KIND} = 'superseded' THEN 'superseded' WHEN ${KIND} = 'archived' THEN 'archived' END AS why,
+               COUNT(*) AS n
+        FROM memories WHERE tenant_id = ? AND NOT (${LIVE}) GROUP BY why
+      `).all(tenantId);
+            const excluded = { superseded: 0, archived: 0, quarantined: 0 };
+            for (const { why, n } of counts)
+                if (why !== null)
+                    excluded[why] = Number(n);
+            return { live: live.map(toDashboardRow), excluded };
+        });
+    }, openStore);
+}
+/** The dashboard's one read-only connection, kept across refreshes for the commit signal; it opens on the first read that finds a database. */
+export class DashboardConnection {
+    hippoRoot;
+    db = null;
+    constructor(hippoRoot) {
+        this.hippoRoot = hippoRoot;
+    }
+    /** `PRAGMA data_version`, which moves when another connection commits; null while the store has no hippo.db. */
+    dataVersion() {
+        if (this.db === null) {
+            if (!fs.existsSync(getHippoDbPath(this.hippoRoot)))
+                return null;
+            this.db = openHippoDbReadOnly(this.hippoRoot);
+        }
+        return pragmaDataVersion(this.db);
+    }
+    /** Ids with a stored vector: none before the connection opens, null on a store older than the vector table (schema v52). */
+    embeddedIds() {
+        if (this.db === null)
+            return new Set();
+        return tableExists(this.db, 'memory_vectors') ? storedVectorIds(this.db) : null;
+    }
+    close() {
+        if (this.db !== null)
+            closeHippoDb(this.db);
+        this.db = null;
+    }
+}
+//# sourceMappingURL=dashboard-reads.js.map

package/dist/store/delete-and-batch.d.ts

@@ -1,22 +1,15 @@
-import { type MemoryEntry } from '../memory.js';
-import { openHippoDb, type DatabaseSyncLike } from '../db.js';
-import { type DormantMove } from '../dormant.js';
+import { type MemoryEntry } from '../core/memory.js';
+import { openHippoDb, type DatabaseSyncLike } from '../db/index.js';
+import { type DormantMove } from './dormant.js';
+import { type WriteBudget } from '../util/write-budget.js';
 /** Tables whose rows keep a first-class object's backing memory in `memory_id` (ON DELETE SET NULL); tests/dormant-memories.test.ts pins it to the schema. */
 export declare const MEMORY_BACKED_TABLES: readonly ["predictions", "decisions", "incidents", "processes", "policies", "skills", "project_briefs", "customer_notes"];
 /** Ids of memories that back a first-class object, for passes that plan deletes before making them. A table missing from an older schema is skipped. */
 export declare function memoriesBackingObjects(hippoRoot: string): Set<string>;
 /** memoriesBackingObjects on the caller's handle. */
 export declare function memoriesBackingObjectsOn(db: DatabaseSyncLike): Set<string>;
-/**
- * db-scoped delete core, so a delete can compose inside a caller's transaction.
- * NO filesystem I/O: the caller's transaction may still roll back, and mirrors are written post-commit.
- *
- * `opts.suppressForgetAudit` (default false): `rejectValue` and `resolveConflict` set it because each
- * writes its own aggregate audit row, so a removed row must not ALSO emit a `forget` row.
- *
- * Returns `{tenantId, dagParentId}` for the removed row, or `null` if no row with `id`
- * existed or `automatic` refused it (pinned, raw, kept for good or backing an object at DELETE time, so a late pin wins).
- */
+/** db-scoped delete core, composable inside a caller's transaction; NO filesystem I/O, mirrors are written post-commit. `suppressForgetAudit` is set by
+ * rejectValue and resolveConflict (own audit row). Returns `{tenantId, dagParentId}`, or null if absent or `automatic` refused it. */
 export declare function deleteEntryCore(db: ReturnType<typeof openHippoDb>, id: string, opts?: {
     actor?: string;
     suppressForgetAudit?: boolean;
@@ -26,35 +19,17 @@ export declare function deleteEntryCore(db: ReturnType<typeof openHippoDb>, id:
     tenantId: string;
     dagParentId: string | null;
 } | null;
-/**
- * Delete an entry from SQLite and mirrors.
- *
- * `opts.actor` defaults to 'cli'. The api.* layer threads `ctx.actor` so HTTP
- * callers land with `api_key:<key_id>` in the audit log without a duplicate
- * emit from the api wrapper.
- *
- * Thin wrapper over `deleteEntryCore` (open → core → mirrors → close);
- * behavior is byte-identical to the pre-split implementation for every
- * existing caller.
- */
+/** Delete an entry from SQLite and mirrors; thin wrapper over `deleteEntryCore` (open, core, mirrors, close).
+ * `opts.actor` defaults to 'cli'; the api layer threads `ctx.actor` so HTTP callers land as `api_key:<key_id>` in the audit log. */
 export declare function deleteEntry(hippoRoot: string, id: string, opts?: {
     actor?: string;
     reason?: string;
     automatic?: boolean;
 }): boolean;
-/** deleteEntry on the caller's open store, so a loop of deletes opens the store once; each delete still commits alone. */
-export declare function deleteEntryOn(db: DatabaseSyncLike, hippoRoot: string, id: string, opts?: {
-    actor?: string;
-    reason?: string;
-    automatic?: boolean;
-}): boolean;
-/** Writes, deletes and dormant moves in one transaction. With `snapshot` (rows as the caller loaded them), a write keeps only
- *  the fields the caller changed, takes the rest from the live row, and never resurrects a row that is gone.
- *
- *  `dormant` (src/dormant.ts): each move's snapshot is inserted into `dormant_memories` and its `memories` row
- *  leaves exactly like a delete (FTS row, DAG parent dirty-mark, mirrors), in the same transaction, so a memory
- *  is never in both places or in neither. Deletes and moves both skip rows that are no longer auto-deletable
- *  (pinned, raw, kept for good or backing an object since the caller decided). Returns the ids that left `memories`, deleted or moved. */
+/** Each row as the caller loaded it, by id; a `ReadonlyMap` fits. */
+export type LoadedRows = Pick<ReadonlyMap<string, MemoryEntry>, 'get'>;
+/** Writes, deletes and dormant moves in one transaction. With `snapshot`, a write keeps only the fields the caller changed and never resurrects a gone row.
+ * Dormant moves (src/store/dormant.ts) leave `memories` like a delete; both skip rows no longer auto-deletable. Returns ids that left `memories`. */
 export declare function batchWriteAndDelete(hippoRoot: string, toWrite: MemoryEntry[], toDeleteIds: string[], opts?: {
     snapshot?: ReadonlyMap<string, MemoryEntry>;
     dormant?: DormantMove[];
@@ -65,20 +40,21 @@ export interface FlushComponent {
     deletes: readonly string[];
     dormant: readonly DormantMove[];
 }
-/** Tags a flush error with the ids of the component it stopped at, for the partial sleep audit row; the first tag wins. */
-export declare function noteFailedUnit(err: Error, component: FlushComponent | undefined): void;
 /** The ids noteFailedUnit tagged `err` with, if a flush threw it. */
 export declare function failedUnitOf(err: Error | null): string[] | undefined;
-/** batchWriteAndDelete on the caller's open store from component `from`, each component whole, closing the transaction at the
- *  first component boundary after `holdMs`. Returns the next component's index and the ids that left `memories`. */
-export declare function batchWriteAndDeleteOn(db: DatabaseSyncLike, hippoRoot: string, components: readonly FlushComponent[], from: number, opts: {
-    snapshot?: ReadonlyMap<string, MemoryEntry>;
-    holdMs: number;
-    clock?: () => number;
-}): FlushChunk;
-/** Where the next transaction starts, and the ids this one removed from `memories`. */
-export interface FlushChunk {
-    next: number;
-    removedIds: string[];
-}
+/** Deletes each target in its own transaction on one store handle; `true` where the row went. */
+export declare function deleteEntriesOneByOne(hippoRoot: string, targets: readonly {
+    id: string;
+    reason: string;
+}[], opts: {
+    actor?: string;
+    automatic?: boolean;
+}): boolean[];
+/** Commits whole components in transactions of about `budget.holdMs`, letting other writers in between; returns the ids that left `memories`.
+ * The snapshot keeps what other writers changed after the caller loaded its rows. */
+export declare function commitInChunks(hippoRoot: string, components: readonly FlushComponent[], opts: {
+    snapshot: LoadedRows;
+    budget: WriteBudget;
+    busyWaitMs: number;
+}): Promise<string[]>;
 //# sourceMappingURL=delete-and-batch.d.ts.map