hippo-memory 1.69.0 → 1.70.0

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

@@ -0,0 +1,84 @@
+import { type DatabaseSyncLike } from '../../db/index.js';
+/** One github_event_log row to write; `memoryId` is null for an event that produced no memory. */
+export interface GithubEventLogEntry {
+    idempotencyKey: string;
+    deliveryId: string;
+    eventName: string;
+    memoryId: string | null;
+}
+export declare function eventSeenAt(db: DatabaseSyncLike, idempotencyKey: string): boolean;
+export declare function eventMemoryAt(db: DatabaseSyncLike, idempotencyKey: string): string | null;
+/** False when the key was already logged, so a caller inside a write scope can roll its own row back. */
+export declare function logEventAt(db: DatabaseSyncLike, entry: GithubEventLogEntry): boolean;
+/** The memory an already-seen key points at, or null when the key is new. */
+export declare function seenEvent(hippoRoot: string, idempotencyKey: string): {
+    memoryId: string | null;
+} | null;
+export declare function logEvent(hippoRoot: string, entry: GithubEventLogEntry): void;
+export interface ArtifactDeletion {
+    tenantId: string;
+    artifactRef: string;
+    idempotencyKey: string;
+    deliveryId: string;
+    eventName: string;
+    reason: string;
+    who: string;
+}
+/** 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 declare function archiveDeletedArtifact(hippoRoot: string, del: ArtifactDeletion): {
+    duplicate: boolean;
+    archived: number;
+};
+export type DlqBucket = 'parse_error' | 'unroutable' | 'signature_failed' | 'unhandled';
+export interface DlqItem {
+    id: number;
+    tenantId: string;
+    rawPayload: string;
+    error: string;
+    eventName: string | null;
+    deliveryId: string | null;
+    signature: string | null;
+    installationId: string | null;
+    repoFullName: string | null;
+    retryCount: number;
+    receivedAt: string;
+    retriedAt: string | null;
+    bucket: DlqBucket | string;
+}
+/** One github_dlq row to write, already redacted by the caller; the four GitHub-only columns are stored NULL when left out. */
+export interface GithubDlqWrite {
+    tenantId: string;
+    rawPayload: string;
+    error: string;
+    eventName?: string | null;
+    deliveryId?: string | null;
+    signature: string | null;
+    installationId?: string | null;
+    repoFullName?: string | null;
+    bucket: DlqBucket;
+}
+export declare function insertDlq(hippoRoot: string, row: GithubDlqWrite): number;
+export declare function listDlqRows(hippoRoot: string, tenantId: string, limit: number): DlqItem[];
+export declare function dlqEntry(hippoRoot: string, id: number): DlqItem | null;
+export declare function bumpDlqRetry(hippoRoot: string, id: number): void;
+/** What the routing tables say about one webhook; `tenant` is the installation match, or the repo match when no installation was sent. */
+export interface GithubRouting {
+    installations: number;
+    repositories: number;
+    tenant: string | null;
+}
+export declare function githubRouting(hippoRoot: string, args: {
+    installationId?: string | null;
+    repoFullName?: string | null;
+}): GithubRouting;
+export type HwmColumn = 'issues_hwm' | 'issue_comments_hwm' | 'pr_review_comments_hwm';
+export interface StoredCursors {
+    issues: string | null;
+    issueComments: string | null;
+    prReviewComments: string | null;
+}
+export declare function readCursors(hippoRoot: string, tenantId: string, repo: string): StoredCursors;
+export declare function writeHwm(hippoRoot: string, tenantId: string, repo: string, column: HwmColumn, value: string): void;
+/** Sets all three HWMs to `since` for a first run; COALESCE keeps any HWM a stream has already saved. */
+export declare function seedCursors(hippoRoot: string, tenantId: string, repo: string, since: string): void;
+//# sourceMappingURL=github.d.ts.map

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 insertDlqAt(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 insertDlq(hippoRoot, row) {
+    return onHandle(hippoRoot, (db) => insertDlqAt(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 listDlqAt(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 listDlqRows(hippoRoot, tenantId, limit) {
+    return onHandle(hippoRoot, (db) => listDlqAt(db, tenantId, limit));
+}
+function dlqEntryAt(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 dlqEntry(hippoRoot, id) {
+    return onHandle(hippoRoot, (db) => dlqEntryAt(db, id));
+}
+export function bumpDlqRetry(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,92 @@
+// 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 { 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),
+        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) {
+    const db = openStore(hippoRoot);
+    try {
+        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 };
+        });
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+/** 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