hippo-memory 1.60.0 → 1.62.0

package/dist/store/search-rows.js

@@ -0,0 +1,260 @@
+import { envForceLikePath } from '../env.js';
+import { isFtsAvailable, closeHippoDb } from '../db.js';
+import { tokenize } from '../tokenize.js';
+import { RECALL_DEFAULT_DENY_SCOPES } from '../recall-scope.js';
+import { RAREST_TERM_COUNT, rarestPromptTerms } from '../prompt-recall.js';
+import { log } from '../log.js';
+import { topVectorMatches } from '../vector-store.js';
+import { MEMORY_SELECT_COLUMNS, MEMORY_SEARCH_COLUMNS, DEFAULT_SEARCH_CANDIDATE_LIMIT, rowToEntry, } from './rows.js';
+import { openStore } from './open.js';
+/** The recall scope rule for a table column prefix (`m.` or none); `passesScopeFilterForRecall` in recall-scope.ts is its JS twin. */
+function recallScopeClause(col, scopeFilter) {
+    if (scopeFilter === undefined)
+        return { sql: '', params: [] };
+    if (scopeFilter.mode === 'exact')
+        return { sql: ` AND ${col}scope = ?`, params: [scopeFilter.value] };
+    // `IS NULL OR` admits NULL scopes, which NOT IN alone drops. NOT LIKE denies a superset of private scopes before the
+    // window cut so private rows cannot starve admitted ones; the anchored JS regex stays the exact post-filter.
+    const placeholders = RECALL_DEFAULT_DENY_SCOPES.map(() => '?').join(', ');
+    const admitted = `${col}scope IS NULL OR (${col}scope NOT IN (${placeholders}) AND ${col}scope NOT LIKE '%:private:%')`;
+    if (scopeFilter.mode === 'default-deny')
+        return { sql: ` AND (${admitted})`, params: [...RECALL_DEFAULT_DENY_SCOPES] };
+    // The trailing arm keeps a deliberately requested scope loadable, private or quarantined included.
+    return { sql: ` AND (${admitted} OR ${col}scope = ?)`, params: [...RECALL_DEFAULT_DENY_SCOPES, scopeFilter.value] };
+}
+// In SQL, not after the window cut, so other projects' matches cannot crowd the project's own rows out of the LIMIT.
+function withProject(scope, col, originProject) {
+    if (originProject === undefined)
+        return scope;
+    return { sql: `${scope.sql} AND (${col}origin_project = '' OR ${col}origin_project = ?)`, params: [...scope.params, originProject] };
+}
+/** Scope rule for recall: none requested is default-deny; 'exact' narrows to the request; 'additive' adds it to the default set. */
+export function recallScopeFilter(requestedScope, mode) {
+    if (!requestedScope)
+        return { mode: 'default-deny' };
+    return mode === 'additive' ? { mode: 'default-deny-or-exact', value: requestedScope } : { mode: 'exact', value: requestedScope };
+}
+const FTS_QUERY_SYNTAX_RE = /fts5: syntax error|unterminated string/i;
+function loadSearchRows(db, query, limit, tenantId, scopeFilter, includeSuperseded = true, originProject) {
+    const p = searchPredicates(tenantId, scopeFilter, includeSuperseded, originProject);
+    const terms = Array.from(new Set(tokenize(query)));
+    if (terms.length === 0) {
+        // F3 (v1.7.0) self-review: empty-query path is the second uncapped
+        // path (codex diff-pass caught the full-store fallback at the bottom;
+        // this no-terms path had the same shape). Apply LIMIT so all four
+        // candidate paths honour the caller's cap when set.
+        return selectAllCandidates(db, p, limit);
+    }
+    // v1.7.1 — test/diagnostic hook: `HIPPO_FORCE_LIKE_PATH=1` forces the
+    // LIKE-fallback path here only. Gated at the read-call site so writes
+    // (`syncFtsRow`, `deleteFtsRow`, `raw-archive.ts::archiveRaw`) keep using
+    // `isFtsAvailable` honestly and never silently skip FTS index sync.
+    // Lets tests exercise the LIKE branch deterministically without
+    // poisoning the on-disk FTS state.
+    const forceLikePath = envForceLikePath();
+    if (!forceLikePath && isFtsAvailable(db)) {
+        const rows = selectFtsCandidates(db, terms, p, limit);
+        if (rows.length > 0)
+            return rows;
+    }
+    const rows = selectLikeCandidates(db, terms, p, limit);
+    if (rows.length > 0)
+        return rows;
+    // F3 (v1.7.0) codex P1: pre-v1.7.0 the full-store fallback ignored
+    // `limit` and could return the whole tenant store. With scorerWindow
+    // now reported on RecallResult, an unbounded fallback would lie about
+    // candidate-pool size. Apply LIMIT here so all four paths honour the
+    // caller's cap.
+    return selectAllCandidates(db, p, limit);
+}
+function searchPredicates(tenantId, scopeFilter, includeSuperseded, originProject) {
+    // tenantId undefined = no tenant filter (legacy callers / cross-deployment
+    // helpers). tenantId set = strict tenant isolation, leveraging the composite
+    // idx_memories_tenant_created (leading column tenant_id, O(log n) lookup).
+    const tenantPredicate = tenantId !== undefined ? ` AND m.tenant_id = ?` : '';
+    const tenantPredicateNoAlias = tenantId !== undefined ? ` AND tenant_id = ?` : '';
+    const tenantOnlyPredicate = tenantId !== undefined ? ` WHERE tenant_id = ?` : '';
+    const tenantParams = tenantId !== undefined ? [tenantId] : [];
+    // v1.12.6 — belt-and-suspenders against `kind='archived'` leaking into recall.
+    // `kind='archived'` is a transient sentinel inside `archiveRawMemory`'s
+    // SAVEPOINT (src/raw-archive.ts:56): UPDATE kind = 'archived' immediately
+    // followed by DELETE, both inside one savepoint that commits or rolls back
+    // atomically. SQLite atomicity guarantees no concurrent reader sees the
+    // intermediate state. This filter is defensive-only against:
+    //   (a) future bugs that drop the SAVEPOINT,
+    //   (b) future bugs that introduce kind='archived' as a persisted state,
+    //   (c) external direct-SQL writes that bypass archiveRawMemory.
+    // tenantOnlyPredicate starts with " WHERE tenant_id = ?" when tenant is set;
+    // when unset, we have no WHERE yet, so the archived clause needs both AND
+    // and WHERE forms. The "tenant-only" path always has WHERE (from tenant or
+    // we synthesize one).
+    const archivedClauseAlias = ` AND m.kind != 'archived'`;
+    const archivedClauseNoAlias = ` AND kind != 'archived'`;
+    // For the "tenant-only" path: if no tenant set, tenantOnlyPredicate is '',
+    // so prepend WHERE; if tenant set, append AND. handled in each call site
+    // by always joining `tenantOnlyPredicate + archivedClauseTenantOnly` where
+    // the latter switches between " AND" and " WHERE" based on caller context.
+    const archivedClauseTenantOnly = tenantId !== undefined ? ` AND kind != 'archived'` : ` WHERE kind != 'archived'`;
+    const aliasScope = withProject(recallScopeClause('m.', scopeFilter), 'm.', originProject);
+    const plainScope = withProject(recallScopeClause('', scopeFilter), '', originProject);
+    const scopeParams = aliasScope.params;
+    const currentAlias = includeSuperseded ? '' : ' AND m.superseded_by IS NULL';
+    const currentNoAlias = includeSuperseded ? '' : ' AND superseded_by IS NULL';
+    return {
+        tenantPredicate, tenantPredicateNoAlias, tenantOnlyPredicate, tenantParams,
+        archivedClauseAlias, archivedClauseNoAlias, archivedClauseTenantOnly,
+        aliasScope, plainScope, scopeParams, currentAlias, currentNoAlias,
+    };
+}
+/** Every admitted row, oldest first; the no-terms path and the last-resort fallback share it. */
+function selectAllCandidates(db, p, limit) {
+    const sql = `SELECT ${MEMORY_SELECT_COLUMNS} FROM memories${p.tenantOnlyPredicate}${p.archivedClauseTenantOnly}${p.plainScope.sql}${p.currentNoAlias} ORDER BY created ASC, id ASC LIMIT ?`;
+    // SAFETY: sql selects exactly MEMORY_SELECT_COLUMNS, whose column list
+    // matches MemoryRow's field set.
+    return db.prepare(sql).all(...p.tenantParams, ...p.scopeParams, limit);
+}
+/** FTS5 bm25 matches; empty when none match or FTS5 cannot run the query. */
+function selectFtsCandidates(db, terms, p, limit) {
+    try {
+        const ftsQuery = terms.map((t) => `"${t.replace(/"/g, '""')}"`).join(' OR ');
+        // memories_fts virtual table has no tenant_id column; filter via the
+        // joined memories row (cheap with idx_memories_tenant_created leading
+        // on tenant_id).
+        // F1 (v1.7.0): MEMORY_SEARCH_COLUMNS adds bm25_score as the trailing
+        // result column. Every other column is m.<col> AS <col> so rowToEntry
+        // sees the same shape it always has.
+        // SAFETY: MEMORY_SEARCH_COLUMNS aliases every column to the same name
+        // MEMORY_SELECT_COLUMNS uses (plus bm25_score), matching MemoryRow.
+        return db.prepare(`
+        SELECT ${MEMORY_SEARCH_COLUMNS}
+        FROM memories m
+        JOIN memories_fts f ON f.id = m.id
+        WHERE memories_fts MATCH ?${p.tenantPredicate}${p.archivedClauseAlias}${p.aliasScope.sql}${p.currentAlias}
+        ORDER BY bm25(memories_fts), m.updated_at DESC, m.content ASC, m.id ASC
+        LIMIT ?
+      `).all(ftsQuery, ...p.tenantParams, ...p.scopeParams, limit);
+    }
+    catch (err) {
+        // A query FTS5 cannot parse is expected input; anything else means the index itself is broken.
+        const message = err instanceof Error ? err.message : String(err);
+        if (!FTS_QUERY_SYNTAX_RE.test(message))
+            log.once('fts-match-fallback', 'warn', `FTS search failed, using the slower LIKE match: ${message}`);
+        return [];
+    }
+}
+function selectLikeCandidates(db, terms, p, limit) {
+    const escapeLike = (term) => term.replace(/[%_\\]/g, '\\$&');
+    const where = terms.map(() => `(LOWER(content) LIKE ? ESCAPE '\\' OR LOWER(tags_json) LIKE ? ESCAPE '\\')`).join(' OR ');
+    const params = terms.flatMap((term) => {
+        const like = `%${escapeLike(term)}%`;
+        return [like, like];
+    });
+    // SAFETY: this query selects exactly MEMORY_SELECT_COLUMNS, matching
+    // MemoryRow's field set.
+    return db.prepare(`
+    SELECT ${MEMORY_SELECT_COLUMNS}
+    FROM memories
+    WHERE (${where})${p.tenantPredicateNoAlias}${p.archivedClauseNoAlias}${p.plainScope.sql}${p.currentNoAlias}
+    ORDER BY updated_at DESC, created DESC, content ASC, id ASC
+    LIMIT ?
+  `).all(...params, ...p.tenantParams, ...p.scopeParams, limit);
+}
+/**
+ * Load likely search candidates directly from SQLite.
+ * Uses FTS5 when available, falls back to LIKE matching, then full-store fallback.
+ *
+ * When `tenantId` is provided, every SELECT (FTS join, LIKE, fallback) filters
+ * by tenant_id. Cross-tenant memories never surface. Omitted = no filter.
+ */
+export function loadSearchEntries(hippoRoot, query, limit = DEFAULT_SEARCH_CANDIDATE_LIMIT, tenantId) {
+    const db = openStore(hippoRoot);
+    try {
+        return loadSearchRows(db, query, limit, tenantId).map(rowToEntry);
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+/**
+ * v1.7.1 — recall-mode loader. Pushes the recall-side scope predicate into
+ * SQL so `unknown:legacy` cannot leak via any consumer that hasn't remembered
+ * to re-filter (root-cause-over-patches: codex flagged this on v1.6.5 review).
+ *
+ * - `requestedScope` undefined / '': default-deny on `unknown:legacy`.
+ * - `requestedScope` non-empty string: exact match on `m.scope = requestedScope`.
+ *
+ * Private-scope (`<source>:private:*`) exclusion: SQL applies a conservative
+ * pre-window approximation (`NOT LIKE '%:private:%'`, v1.25.0 — codex P2:
+ * post-window-only filtering let private rows starve admitted candidates out
+ * of the LIMIT window); the exact anchored regex
+ * (`passesScopeFilterForRecall`) remains the authoritative JS post-filter in
+ * the recall consumers.
+ *
+ * Consumers: `api.recall` (v1.7.1+), `cmdRecall`/`cmdExplain` direct CLI paths
+ * and `searchBothHybrid` recall mode (v1.25.0). Background pipelines
+ * (`consolidate`, `embeddings`, `refine-llm`, ...) keep using
+ * `loadSearchEntries` so they can see quarantined rows when needed.
+ *
+ * `tenantId` widened to optional in v1.25.0 for the searchBothHybrid recall
+ * mode (its `tenantId` option is optional); `loadSearchRows` already treats
+ * undefined as "no tenant filter" for legacy callers.
+ */
+export function loadRecallSearchEntries(hippoRoot, query, limit = DEFAULT_SEARCH_CANDIDATE_LIMIT, tenantId, requestedScope, explicitScopeMode = 'exact', includeSuperseded = true, originProject) {
+    const db = openStore(hippoRoot);
+    try {
+        return loadRecallSearchEntriesFromDb(db, query, limit, tenantId, requestedScope, explicitScopeMode, includeSuperseded, originProject);
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+// Split out so callers with an already-open db (Z1 prompt-recall path) skip
+// the initStore+open/close cycle per store per call.
+export function loadRecallSearchEntriesFromDb(db, query, limit = DEFAULT_SEARCH_CANDIDATE_LIMIT, tenantId, requestedScope, explicitScopeMode = 'exact', includeSuperseded = true, originProject) {
+    return loadSearchRows(db, query, limit, tenantId, recallScopeFilter(requestedScope, explicitScopeMode), includeSuperseded, originProject).map(rowToEntry);
+}
+/** The rows nearest `queryVector` that pass `spec`, nearest first. */
+export function loadVectorCandidateEntries(hippoRoot, queryVector, spec) {
+    const scope = recallScopeClause('m.', spec.scope);
+    const tenant = spec.tenantId !== undefined ? ' AND m.tenant_id = ?' : '';
+    const current = spec.includeSuperseded ? '' : ' AND m.superseded_by IS NULL';
+    const params = [...(spec.tenantId !== undefined ? [spec.tenantId] : []), ...scope.params];
+    const db = openStore(hippoRoot);
+    try {
+        const matches = topVectorMatches(db, queryVector, spec.limit ?? 50, `${tenant} AND m.kind != 'archived'${scope.sql}${current}`, params);
+        if (matches.length === 0)
+            return [];
+        // SAFETY: the SELECT names exactly MEMORY_SELECT_COLUMNS, matching MemoryRow's field set.
+        const rows = db.prepare(`SELECT ${MEMORY_SELECT_COLUMNS} FROM memories WHERE id IN (${matches.map(() => '?').join(', ')})`)
+            .all(...matches.map((m) => m.id));
+        const byId = new Map(rows.map((r) => [r.id, rowToEntry(r)]));
+        return matches.flatMap((m) => byId.get(m.id) ?? []);
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+/** Rarest-K prompt terms for this connection's FTS index, as a space-joined query string.
+ *  Without FTS, returns the first 32 terms, as before rarest-term selection. */
+export function pickRarestFtsQuery(db, terms, maxTerms = RAREST_TERM_COUNT) {
+    // The LIKE path has no bm25 ranking to bound, so it keeps the pre-rarest 32-term query.
+    if (!isFtsAvailable(db))
+        return terms.slice(0, 32).join(' ');
+    db.exec(`CREATE VIRTUAL TABLE IF NOT EXISTS temp.z1_rarest_vocab USING fts5vocab(main, 'memories_fts', 'row')`);
+    // unicode61 splits `journal_mode` into two vocab terms; a term's count is its rarest part's (an upper bound).
+    const partsOf = (t) => t.split(/[^\p{L}\p{N}]+/u).filter(Boolean);
+    const vocab = Array.from(new Set(terms.flatMap(partsOf)));
+    if (vocab.length === 0)
+        return '';
+    // SAFETY: rows' shape matches the two columns named in the SELECT.
+    const rows = db
+        .prepare(`SELECT term, doc FROM temp.z1_rarest_vocab WHERE term IN (${vocab.map(() => '?').join(', ')})`)
+        .all(...vocab);
+    const counts = new Map(rows.map((r) => [r.term, r.doc]));
+    const docCount = (t) => {
+        const parts = partsOf(t);
+        return parts.length === 0 ? 0 : Math.min(...parts.map((x) => counts.get(x) ?? 0));
+    };
+    return rarestPromptTerms(terms, docCount, maxTerms).join(' ');
+}
+//# sourceMappingURL=search-rows.js.map

package/dist/store/sessions.d.ts

@@ -0,0 +1,83 @@
+import { type TaskSnapshot, type SessionEvent } from './rows.js';
+export declare function saveActiveTaskSnapshot(hippoRoot: string, tenantId: string, snapshot: {
+    task: string;
+    summary: string;
+    next_step: string;
+    source?: string;
+    session_id?: string | null;
+    scope?: string | null;
+}): TaskSnapshot;
+export declare function loadActiveTaskSnapshot(hippoRoot: string, tenantId: string): TaskSnapshot | null;
+/**
+ * Default freshness bound for AMBIENT active-task-snapshot reads (DF1,
+ * docs/plans/2026-08-23-df1-snapshot-lifecycle.md): 72h, chosen over 48h so
+ * a Friday-evening orphan still offers continuity on Monday morning.
+ * Exported so callers can override via `loadFreshActiveTaskSnapshot`'s
+ * `opts.maxAgeMs`; deliberately no env knob (Simplicity First).
+ */
+export declare const SNAPSHOT_AMBIENT_MAX_AGE_MS: number;
+/**
+ * Bounded read for AMBIENT active-task-snapshot surfaces (UserPromptSubmit
+ * hook context, MCP recall block) — the never-expires fix for DF1. A
+ * snapshot written by `hippo pre-compact` has no death path tied to the
+ * session that owns it, so an orphaned row would otherwise inject into
+ * every prompt of every later session forever. Wraps `loadActiveTaskSnapshot`
+ * (unchanged, still the source of truth for explicit continuity surfaces),
+ * then applies, in order:
+ *
+ * 1. Owner match — ONLY when both `opts.sessionId` and the snapshot's
+ *    `session_id` are non-null, non-empty strings and strictly equal
+ *    (`===`). Owner reads are unbounded: the session that owns the snapshot
+ *    can always see its own working state, regardless of age.
+ * 2. Age check — everything else, including absent-vs-absent ids. A
+ *    null/undefined/empty id on EITHER side never counts as an owner match;
+ *    it falls through here instead. (`runPreCompact` can legitimately save a
+ *    snapshot with `session_id = null`; a null-equals-null "match" would
+ *    reopen indefinite ambient injection for exactly those rows.) Returns
+ *    the snapshot only when `age(updated_at) <= maxAgeMs` (default
+ *    `SNAPSHOT_AMBIENT_MAX_AGE_MS`); otherwise null.
+ *
+ * No SQL change — age derives from the existing `updated_at` column.
+ */
+export declare function loadFreshActiveTaskSnapshot(hippoRoot: string, tenantId: string, opts?: {
+    maxAgeMs?: number;
+    sessionId?: string | null;
+}): TaskSnapshot | null;
+export declare function clearActiveTaskSnapshot(hippoRoot: string, tenantId: string, clearedStatus?: string): boolean;
+/**
+ * Close the `active` task snapshot(s) owned by `sessionId`, for the T3
+ * session-end death path (DF1, docs/plans/2026-08-23-df1-snapshot-lifecycle.md).
+ * Only one `active` row exists per tenant in practice (supersession happens
+ * at save), but the WHERE clause scopes on `session_id` too — not just
+ * `status='active' AND tenant_id=?` — so an ending session can never close a
+ * different, newer session's active snapshot. Returns the number of rows
+ * closed (0 when no active row is owned by `sessionId`).
+ */
+export declare function closeTaskSnapshotsForSession(hippoRoot: string, tenantId: string, sessionId: string, status?: string): number;
+export declare function appendSessionEvent(hippoRoot: string, tenantId: string, event: {
+    session_id: string;
+    event_type: string;
+    content: string;
+    task?: string | null;
+    source?: string;
+    scope?: string | null;
+    metadata?: Record<string, unknown>;
+}): SessionEvent;
+export declare function listSessionEvents(hippoRoot: string, tenantId: string, options?: {
+    session_id?: string;
+    task?: string;
+    limit?: number;
+}): SessionEvent[];
+/**
+ * Return session_ids with a `session_complete` event newer than `sinceMs`.
+ * Used by the sleep auto-promotion pass to bound scanning to a fixed window.
+ */
+export declare function findPromotableSessions(hippoRoot: string, tenantId: string, sinceMs: number): Array<{
+    session_id: string;
+}>;
+/**
+ * Idempotency guard — true if a trace-layer memory with this source_session_id
+ * already exists.
+ */
+export declare function traceExistsForSession(hippoRoot: string, tenantId: string, session_id: string): boolean;
+//# sourceMappingURL=sessions.d.ts.map

package/dist/store/sessions.js

@@ -0,0 +1,272 @@
+import { closeHippoDb } from '../db.js';
+import { assertTenantId } from '../tenant.js';
+import { redactSecretsStrict } from '../secret-detect.js';
+import { rowToTaskSnapshot, rowToSessionEvent, } from './rows.js';
+import { writeActiveTaskMirror, removeActiveTaskMirror, writeRecentSessionMirror } from './mirrors.js';
+import { openStore } from './open.js';
+export function saveActiveTaskSnapshot(hippoRoot, tenantId, snapshot) {
+    assertTenantId('saveActiveTaskSnapshot', tenantId);
+    const db = openStore(hippoRoot);
+    const now = new Date().toISOString();
+    try {
+        db.exec('BEGIN');
+        db.prepare(`UPDATE task_snapshots SET status = 'superseded', updated_at = ? WHERE status = 'active' AND tenant_id = ?`).run(now, tenantId);
+        const result = db.prepare(`
+      INSERT INTO task_snapshots(task, summary, next_step, status, source, session_id, scope, tenant_id, created_at, updated_at)
+      VALUES (?, ?, ?, 'active', ?, ?, ?, ?, ?, ?)
+    `).run(redactSecretsStrict(snapshot.task), redactSecretsStrict(snapshot.summary), redactSecretsStrict(snapshot.next_step), snapshot.source ?? 'cli', snapshot.session_id ?? null, snapshot.scope ?? null, tenantId, now, now);
+        db.exec('COMMIT');
+        const id = Number(result.lastInsertRowid ?? 0);
+        // SAFETY: row's shape matches the ten columns named in the SELECT above.
+        const row = db.prepare(`
+      SELECT id, task, summary, next_step, status, source, session_id, scope, created_at, updated_at
+      FROM task_snapshots
+      WHERE id = ?
+    `).get(id);
+        if (!row) {
+            throw new Error('Failed to reload saved active task snapshot');
+        }
+        const loaded = rowToTaskSnapshot(row);
+        writeActiveTaskMirror(hippoRoot, tenantId, loaded);
+        return loaded;
+    }
+    catch (error) {
+        try {
+            db.exec('ROLLBACK');
+        }
+        catch {
+            // Ignore nested rollback failures.
+        }
+        throw error;
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+export function loadActiveTaskSnapshot(hippoRoot, tenantId) {
+    assertTenantId('loadActiveTaskSnapshot', tenantId);
+    const db = openStore(hippoRoot);
+    try {
+        // SAFETY: row's shape matches the ten columns named in the SELECT above.
+        const row = db.prepare(`
+      SELECT id, task, summary, next_step, status, source, session_id, scope, created_at, updated_at
+      FROM task_snapshots
+      WHERE status = 'active' AND tenant_id = ?
+      ORDER BY updated_at DESC, id DESC
+      LIMIT 1
+    `).get(tenantId);
+        if (!row) {
+            removeActiveTaskMirror(hippoRoot, tenantId);
+            return null;
+        }
+        const loaded = rowToTaskSnapshot(row);
+        writeActiveTaskMirror(hippoRoot, tenantId, loaded);
+        return loaded;
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+/**
+ * Default freshness bound for AMBIENT active-task-snapshot reads (DF1,
+ * docs/plans/2026-08-23-df1-snapshot-lifecycle.md): 72h, chosen over 48h so
+ * a Friday-evening orphan still offers continuity on Monday morning.
+ * Exported so callers can override via `loadFreshActiveTaskSnapshot`'s
+ * `opts.maxAgeMs`; deliberately no env knob (Simplicity First).
+ */
+export const SNAPSHOT_AMBIENT_MAX_AGE_MS = 72 * 60 * 60 * 1000;
+/** A usable session id: non-null, non-empty string. Named predicate (not an
+ * inline `typeof` check) so the owner-match rule in
+ * `loadFreshActiveTaskSnapshot` states its contract once. */
+function isNonEmptySessionId(value) {
+    return typeof value === 'string' && value.length > 0;
+}
+/**
+ * Bounded read for AMBIENT active-task-snapshot surfaces (UserPromptSubmit
+ * hook context, MCP recall block) — the never-expires fix for DF1. A
+ * snapshot written by `hippo pre-compact` has no death path tied to the
+ * session that owns it, so an orphaned row would otherwise inject into
+ * every prompt of every later session forever. Wraps `loadActiveTaskSnapshot`
+ * (unchanged, still the source of truth for explicit continuity surfaces),
+ * then applies, in order:
+ *
+ * 1. Owner match — ONLY when both `opts.sessionId` and the snapshot's
+ *    `session_id` are non-null, non-empty strings and strictly equal
+ *    (`===`). Owner reads are unbounded: the session that owns the snapshot
+ *    can always see its own working state, regardless of age.
+ * 2. Age check — everything else, including absent-vs-absent ids. A
+ *    null/undefined/empty id on EITHER side never counts as an owner match;
+ *    it falls through here instead. (`runPreCompact` can legitimately save a
+ *    snapshot with `session_id = null`; a null-equals-null "match" would
+ *    reopen indefinite ambient injection for exactly those rows.) Returns
+ *    the snapshot only when `age(updated_at) <= maxAgeMs` (default
+ *    `SNAPSHOT_AMBIENT_MAX_AGE_MS`); otherwise null.
+ *
+ * No SQL change — age derives from the existing `updated_at` column.
+ */
+export function loadFreshActiveTaskSnapshot(hippoRoot, tenantId, opts = {}) {
+    const snapshot = loadActiveTaskSnapshot(hippoRoot, tenantId);
+    if (!snapshot)
+        return null;
+    const callerSessionId = opts.sessionId;
+    const isOwnerMatch = isNonEmptySessionId(callerSessionId) &&
+        isNonEmptySessionId(snapshot.session_id) &&
+        callerSessionId === snapshot.session_id;
+    if (isOwnerMatch)
+        return snapshot;
+    const maxAgeMs = opts.maxAgeMs ?? SNAPSHOT_AMBIENT_MAX_AGE_MS;
+    const ageMs = Date.now() - Date.parse(snapshot.updated_at);
+    return ageMs <= maxAgeMs ? snapshot : null;
+}
+export function clearActiveTaskSnapshot(hippoRoot, tenantId, clearedStatus = 'cleared') {
+    assertTenantId('clearActiveTaskSnapshot', tenantId);
+    const db = openStore(hippoRoot);
+    const now = new Date().toISOString();
+    try {
+        // SAFETY: active's shape matches the single `id` column selected above.
+        const active = db.prepare(`SELECT id FROM task_snapshots WHERE status = 'active' AND tenant_id = ? ORDER BY updated_at DESC, id DESC LIMIT 1`).get(tenantId);
+        if (!active?.id) {
+            removeActiveTaskMirror(hippoRoot, tenantId);
+            return false;
+        }
+        db.prepare(`UPDATE task_snapshots SET status = ?, updated_at = ? WHERE id = ? AND tenant_id = ?`).run(clearedStatus, now, active.id, tenantId);
+        removeActiveTaskMirror(hippoRoot, tenantId);
+        return true;
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+/**
+ * Close the `active` task snapshot(s) owned by `sessionId`, for the T3
+ * session-end death path (DF1, docs/plans/2026-08-23-df1-snapshot-lifecycle.md).
+ * Only one `active` row exists per tenant in practice (supersession happens
+ * at save), but the WHERE clause scopes on `session_id` too — not just
+ * `status='active' AND tenant_id=?` — so an ending session can never close a
+ * different, newer session's active snapshot. Returns the number of rows
+ * closed (0 when no active row is owned by `sessionId`).
+ */
+export function closeTaskSnapshotsForSession(hippoRoot, tenantId, sessionId, status = 'session-ended') {
+    assertTenantId('closeTaskSnapshotsForSession', tenantId);
+    const db = openStore(hippoRoot);
+    const now = new Date().toISOString();
+    try {
+        const result = db.prepare(`UPDATE task_snapshots SET status = ?, updated_at = ? WHERE status = 'active' AND tenant_id = ? AND session_id = ?`).run(status, now, tenantId, sessionId);
+        return Number(result.changes ?? 0);
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+export function appendSessionEvent(hippoRoot, tenantId, event) {
+    assertTenantId('appendSessionEvent', tenantId);
+    const db = openStore(hippoRoot);
+    const now = new Date().toISOString();
+    // v1.2: scope is wired through. Default-deny in api.recall + cmdRecall
+    // continuity reads applies to slack:private:* and 'unknown:legacy' rows.
+    try {
+        const result = db.prepare(`
+      INSERT INTO session_events(session_id, task, event_type, content, source, scope, metadata_json, tenant_id, created_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(event.session_id, event.task ?? null, event.event_type, event.content, event.source ?? 'cli', event.scope ?? null, JSON.stringify(event.metadata ?? {}), tenantId, now);
+        const id = Number(result.lastInsertRowid ?? 0);
+        // SAFETY: row's shape matches the nine columns named in the SELECT
+        // above.
+        const row = db.prepare(`
+      SELECT id, session_id, task, event_type, content, source, scope, metadata_json, created_at
+      FROM session_events
+      WHERE id = ?
+    `).get(id);
+        if (!row) {
+            throw new Error('Failed to reload saved session event');
+        }
+        const loaded = rowToSessionEvent(row);
+        // SAFETY: recentRows' shape matches the nine columns named in the
+        // SELECT above.
+        const recentRows = db.prepare(`
+      SELECT id, session_id, task, event_type, content, source, scope, metadata_json, created_at
+      FROM session_events
+      WHERE session_id = ? AND tenant_id = ?
+      ORDER BY created_at DESC, id DESC
+      LIMIT ?
+    `).all(loaded.session_id, tenantId, 20);
+        const recent = recentRows.map(rowToSessionEvent).reverse();
+        writeRecentSessionMirror(hippoRoot, tenantId, recent);
+        return loaded;
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+export function listSessionEvents(hippoRoot, tenantId, options = {}) {
+    assertTenantId('listSessionEvents', tenantId);
+    const db = openStore(hippoRoot);
+    try {
+        const clauses = ['tenant_id = ?'];
+        const params = [tenantId];
+        if (options.session_id) {
+            clauses.push('session_id = ?');
+            params.push(options.session_id);
+        }
+        if (options.task) {
+            clauses.push('task = ?');
+            params.push(options.task);
+        }
+        const limit = Math.max(1, Math.trunc(options.limit ?? 8));
+        params.push(limit);
+        const where = `WHERE ${clauses.join(' AND ')}`;
+        // SAFETY: rows' shape matches the nine columns named in the SELECT
+        // above.
+        const rows = db.prepare(`
+      SELECT id, session_id, task, event_type, content, source, scope, metadata_json, created_at
+      FROM session_events
+      ${where}
+      ORDER BY created_at DESC, id DESC
+      LIMIT ?
+    `).all(...params);
+        return rows.map(rowToSessionEvent).reverse();
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+/**
+ * Return session_ids with a `session_complete` event newer than `sinceMs`.
+ * Used by the sleep auto-promotion pass to bound scanning to a fixed window.
+ */
+export function findPromotableSessions(hippoRoot, tenantId, sinceMs) {
+    assertTenantId('findPromotableSessions', tenantId);
+    const db = openStore(hippoRoot);
+    try {
+        // SAFETY: rows' shape matches the single `session_id` column selected
+        // above.
+        const rows = db.prepare(`
+      SELECT DISTINCT session_id FROM session_events
+      WHERE event_type = 'session_complete' AND created_at >= ? AND tenant_id = ?
+    `).all(new Date(sinceMs).toISOString(), tenantId);
+        return rows;
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+/**
+ * Idempotency guard — true if a trace-layer memory with this source_session_id
+ * already exists.
+ */
+export function traceExistsForSession(hippoRoot, tenantId, session_id) {
+    assertTenantId('traceExistsForSession', tenantId);
+    const db = openStore(hippoRoot);
+    try {
+        const row = db.prepare(`
+      SELECT 1 FROM memories
+      WHERE source_session_id = ? AND layer = 'trace' AND tenant_id = ?
+      LIMIT 1
+    `).get(session_id, tenantId);
+        return !!row;
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+//# sourceMappingURL=sessions.js.map