hippo-memory 1.70.0 → 1.72.0

package/dist/store/search-rows.js

@@ -1,12 +1,13 @@
 import { isFtsAvailable, closeHippoDb } from '../db/index.js';
 import { tokenize } from '../util/tokenize.js';
-import { isPersonalScope, scopeAdmitSql } from './recall-scope.js';
+import { isPersonalScope } from '../core/recall-scope.js';
+import { scopeAdmitSql } from './rule-sql.js';
 import { ftsTermParts, RAREST_TERM_COUNT, rarestFtsQuery } from '../core/prompt-recall.js';
 import { errorMessage, log } from '../util/log.js';
 import { originInSql } from '../core/project-identity.js';
 import { topVectorMatches } from '../db/vector-store.js';
 import { MEMORY_SELECT_COLUMNS, MEMORY_SEARCH_COLUMNS, DEFAULT_SEARCH_CANDIDATE_LIMIT, rowToEntry, } from './rows.js';
-import { openStore } from './open.js';
+import { onHandle, openStore } from './open.js';
 import { escapeLike } from '../util/escape.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) {
@@ -26,9 +27,13 @@ function withProject(scope, col, origin) {
         return scope;
     // A string is the shape published callers passed before a project could carry several names.
     const originProjects = [origin].flat();
-    return { sql: `${scope.sql} AND (${col}origin_project = '' OR ${originInSql(originProjects, `${col}origin_project`)})`, params: [...scope.params, ...originProjects] };
+    return {
+        sql: `${scope.sql} AND (${col}origin_project = '' OR ${originInSql(originProjects, `${col}origin_project`)})`,
+        params: [...scope.params, ...originProjects],
+    };
 }
-/** Scope rule for recall: none requested is default-deny; 'exact' narrows to the request; 'additive' adds it to the default set, unless it is personal, which only `ownScope` opens. */
+/** Scope rule for recall: none requested is default-deny; 'exact' narrows to the request; 'additive' adds it to the default set, unless it is personal,
+ * which only `ownScope` opens. */
 export function recallScopeFilter(requestedScope, mode, ownScope) {
     if (!requestedScope || (mode === 'additive' && isPersonalScope(requestedScope)))
         return { mode: 'default-deny', ownScope };
@@ -62,19 +67,14 @@ function loadSearchRows(db, query, limit, tenantId, options = {}) {
     return selectAllCandidates(db, p, limit);
 }
 function searchPredicates(tenantId, scopeFilter, includeSuperseded, originProjects) {
-    // 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).
+    // tenantId undefined = no tenant filter (legacy callers / cross-deployment helpers); set = strict isolation via the composite idx_memories_tenant_created.
     const tenantPredicate = tenantId !== undefined ? ` AND m.tenant_id = ?` : '';
     const tenantOnlyPredicate = tenantId !== undefined ? ` WHERE tenant_id = ?` : '';
     const tenantParams = tenantId !== undefined ? [tenantId] : [];
     // Defensive: kind='archived' is a transient sentinel inside archiveRawMemory's SAVEPOINT, so this only
     // guards against a dropped SAVEPOINT, a persisted 'archived' state, or direct-SQL writes.
     const archivedClauseAlias = ` AND m.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.
+    // Tenant-only path: with no tenant `tenantOnlyPredicate` is '', so the archived clause switches between ' AND' and ' WHERE' by caller context.
     const archivedClauseTenantOnly = tenantId !== undefined ? ` AND kind != 'archived'` : ` WHERE kind != 'archived'`;
     const aliasScope = withProject(recallScopeClause('m.', scopeFilter), 'm.', originProjects);
     const plainScope = withProject(recallScopeClause('', scopeFilter), '', originProjects);
@@ -89,7 +89,8 @@ function searchPredicates(tenantId, scopeFilter, includeSuperseded, originProjec
 }
 /** 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 ?`;
+    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);
@@ -98,11 +99,8 @@ function selectAllCandidates(db, p, limit) {
 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).
-        // SAFETY: MEMORY_SEARCH_COLUMNS aliases every column to the same name
-        // MEMORY_SELECT_COLUMNS uses (plus bm25_score), matching MemoryRow.
+        // memories_fts has no tenant_id column; filter via the joined memories row (cheap with idx_memories_tenant_created).
+        // SAFETY: MEMORY_SEARCH_COLUMNS aliases every column like MEMORY_SELECT_COLUMNS (plus bm25_score), matching MemoryRow.
         return db.prepare(`
         SELECT ${MEMORY_SEARCH_COLUMNS}
         FROM memories m
@@ -146,52 +144,23 @@ function selectLikeCandidates(db, terms, p, limit) {
     LIMIT ?
   `).all(...p.tenantParams, ...p.scopeParams, Math.max(limit, LIKE_WINDOW_ROWS), ...params, 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.
- */
+/** Load likely search candidates: FTS5 when available, else LIKE, then full-store fallback. With `tenantId` every SELECT filters by it; omitted = no filter. */
 export function loadSearchEntries(hippoRoot, query, limit = DEFAULT_SEARCH_CANDIDATE_LIMIT, tenantId) {
-    const db = openStore(hippoRoot);
-    try {
+    return onHandle(hippoRoot, (db) => {
         return loadSearchRows(db, query, limit, tenantId).map(rowToEntry);
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    }, openStore);
 }
-/**
- * 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.
- *
- * - `requestedScope` undefined / '': default-deny on `unknown:legacy`, admitting `ownScope`, the caller's personal scope.
- * - `requestedScope` non-empty string: exact match on `m.scope = requestedScope`.
- *
- * Private scopes: SQL applies a conservative `NOT LIKE '%:private:%'` before the LIMIT window so private
- * rows cannot starve admitted ones; `passesScopeFilterForRecall` stays the exact JS post-filter.
- *
- * Consumers: `api.recall`, `cmdRecall`/`cmdExplain` direct CLI paths
- * and `searchBothHybrid` recall mode. Background pipelines
- * (`consolidate`, `embeddings`, `refine-llm`, ...) keep using
- * `loadSearchEntries` so they can see quarantined rows when needed.
- *
- * `tenantId` is optional because searchBothHybrid's is; undefined means no tenant filter.
- */
+/** Recall-mode loader: scope predicate in SQL so `unknown:legacy` cannot leak. Empty `requestedScope` default-denies (admits `ownScope`); else exact match.
+ * SQL `NOT LIKE '%:private:%'` runs before the LIMIT so private rows cannot starve admitted ones; `passesScopeFilterForRecall` is the exact post-filter. */
 export function loadRecallSearchEntries(hippoRoot, query, limit = DEFAULT_SEARCH_CANDIDATE_LIMIT, tenantId, requestedScope, explicitScopeMode = 'exact', includeSuperseded = true, originProjects, ownScope) {
-    const db = openStore(hippoRoot);
-    try {
+    return onHandle(hippoRoot, (db) => {
         return loadRecallSearchEntriesFromDb(db, query, { limit, tenantId, requestedScope, explicitScopeMode, includeSuperseded, originProjects, ownScope });
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    }, openStore);
 }
 // Split out so callers with an already-open db (the prompt-recall path) skip
 // the initStore+open/close cycle per store per call.
 export function loadRecallSearchEntriesFromDb(db, query, options = {}) {
-    const { limit = DEFAULT_SEARCH_CANDIDATE_LIMIT, tenantId, requestedScope, explicitScopeMode = 'exact', includeSuperseded = true, originProjects, ownScope } = options;
+    const { limit = DEFAULT_SEARCH_CANDIDATE_LIMIT, tenantId, requestedScope, explicitScopeMode = 'exact', includeSuperseded = true, originProjects, ownScope, } = options;
     const scopeFilter = recallScopeFilter(requestedScope, explicitScopeMode, ownScope);
     return loadSearchRows(db, query, limit, tenantId, { scopeFilter, includeSuperseded, originProjects }).map(rowToEntry);
 }

package/dist/store/sessions.d.ts

@@ -1,3 +1,4 @@
+import type { JsonObject } from './working-memory.js';
 import { type TaskSnapshot, type SessionEvent } from './rows.js';
 /** A shared-store caller's task state bucket: its owner and every name its project's rows carry. */
 export interface ContinuityKey {
@@ -26,36 +27,11 @@ type SnapshotInput = {
 };
 export declare function saveActiveTaskSnapshot(hippoRoot: string, tenantId: string, snapshot: SnapshotInput, key?: ContinuityKey): TaskSnapshot;
 export declare function loadActiveTaskSnapshot(hippoRoot: string, tenantId: string, key?: ContinuityKey): TaskSnapshot | null;
-/**
- * Default freshness bound for AMBIENT active-task-snapshot reads: 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).
- */
+/** Default freshness bound for AMBIENT active-task-snapshot reads: 72h rather than 48h so a Friday-evening orphan still offers continuity on Monday;
+ * override via `loadFreshActiveTaskSnapshot`'s `opts.maxAgeMs`; deliberately no env knob. */
 export declare const SNAPSHOT_AMBIENT_MAX_AGE_MS: number;
-/**
- * Bounded read for AMBIENT active-task-snapshot surfaces (UserPromptSubmit
- * hook context, MCP recall block), so snapshots expire. 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.
- */
+/** Bounded read for AMBIENT snapshot surfaces so orphaned snapshots expire. The owner (both session ids non-empty and `===`) always sees its own state;
+ * all others, null ids included (null === null is no match), get it only if age(updated_at) <= maxAgeMs (default `SNAPSHOT_AMBIENT_MAX_AGE_MS`), else null. */
 export declare function loadFreshActiveTaskSnapshot(hippoRoot: string, tenantId: string, opts?: {
     maxAgeMs?: number;
     sessionId?: string | null;
@@ -66,15 +42,8 @@ export declare function freshActiveSnapshot(snapshot: TaskSnapshot | null, opts?
     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
- * session-end death path.
- * Only one `active` row exists per tenant (per owner and project when keyed) 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`).
- */
+/** Close the `active` task snapshot(s) owned by `sessionId` at session end; the WHERE scopes on `session_id` too so an ending session can never close a
+ * newer session's snapshot. Returns the number of rows closed. */
 export declare function closeTaskSnapshotsForSession(hippoRoot: string, tenantId: string, sessionId: string, status?: string, key?: ContinuityKey): number;
 interface SessionEventInput {
     session_id: string;
@@ -83,7 +52,7 @@ interface SessionEventInput {
     task?: string | null;
     source?: string;
     scope?: string | null;
-    metadata?: Record<string, unknown>;
+    metadata?: JsonObject;
 }
 export declare function appendSessionEvent(hippoRoot: string, tenantId: string, event: SessionEventInput): SessionEvent;
 export declare function listSessionEvents(hippoRoot: string, tenantId: string, options?: {
@@ -91,17 +60,11 @@ export declare function listSessionEvents(hippoRoot: string, tenantId: string, o
     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.
- */
+/** Session_ids with a `session_complete` event newer than `sinceMs`; bounds the sleep auto-promotion scan 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.
- */
+/** 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;
 /** One caller's claim on a session id. */
 export interface SessionOwnerBinding {

package/dist/store/sessions.js

@@ -1,3 +1,4 @@
+import { HOUR_MS } from '../util/time.js';
 import { isSharedStore } from '../core/config.js';
 import { closeHippoDb, HOOK_DB_WAIT_MS, scopedBusyWait, withWriteScope } from '../db/index.js';
 import { raiseMinBinary } from '../db/meta.js';
@@ -24,8 +25,9 @@ export function continuityStamp(key) {
 }
 // An unkeyed write acts on the tenant's newest or every active row, which on a shared store belong to other owners.
 function assertKeyedOnSharedStore(fn, hippoRoot, key) {
-    if (!key && isSharedStore(hippoRoot))
+    if (!key && isSharedStore(hippoRoot)) {
         throw new Error(`${fn}: a shared store keeps one task snapshot per owner and project, so this write needs their continuity key`);
+    }
 }
 function insertSnapshot(db, tenantId, snapshot, now, stamp) {
     const result = db.prepare(`
@@ -73,8 +75,7 @@ export function saveActiveTaskSnapshot(hippoRoot, tenantId, snapshot, key) {
 export function loadActiveTaskSnapshot(hippoRoot, tenantId, key) {
     assertTenantId('loadActiveTaskSnapshot', tenantId);
     const owned = key ? continuityWhere(key) : null;
-    const db = openStore(hippoRoot);
-    try {
+    return onHandle(hippoRoot, (db) => {
         // 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
@@ -92,47 +93,17 @@ export function loadActiveTaskSnapshot(hippoRoot, tenantId, key) {
         if (!key)
             writeActiveTaskMirror(hippoRoot, tenantId, loaded);
         return loaded;
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    }, openStore);
 }
-/**
- * Default freshness bound for AMBIENT active-task-snapshot reads: 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. */
+/** Default freshness bound for AMBIENT active-task-snapshot reads: 72h rather than 48h so a Friday-evening orphan still offers continuity on Monday;
+ * override via `loadFreshActiveTaskSnapshot`'s `opts.maxAgeMs`; deliberately no env knob. */
+export const SNAPSHOT_AMBIENT_MAX_AGE_MS = 72 * HOUR_MS;
+/** A usable session id: non-null, non-empty string; named 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), so snapshots expire. 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.
- */
+/** Bounded read for AMBIENT snapshot surfaces so orphaned snapshots expire. The owner (both session ids non-empty and `===`) always sees its own state;
+ * all others, null ids included (null === null is no match), get it only if age(updated_at) <= maxAgeMs (default `SNAPSHOT_AMBIENT_MAX_AGE_MS`), else null. */
 export function loadFreshActiveTaskSnapshot(hippoRoot, tenantId, opts = {}, key) {
     return freshActiveSnapshot(loadActiveTaskSnapshot(hippoRoot, tenantId, key), opts);
 }
@@ -170,15 +141,8 @@ export function clearActiveTaskSnapshot(hippoRoot, tenantId, clearedStatus = 'cl
         closeHippoDb(db);
     }
 }
-/**
- * Close the `active` task snapshot(s) owned by `sessionId`, for the
- * session-end death path.
- * Only one `active` row exists per tenant (per owner and project when keyed) 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`).
- */
+/** Close the `active` task snapshot(s) owned by `sessionId` at session end; the WHERE scopes on `session_id` too so an ending session can never close a
+ * newer session's snapshot. Returns the number of rows closed. */
 export function closeTaskSnapshotsForSession(hippoRoot, tenantId, sessionId, status = 'session-ended', key) {
     assertTenantId('closeTaskSnapshotsForSession', tenantId);
     if (key)
@@ -242,8 +206,7 @@ export function appendSessionEvent(hippoRoot, tenantId, event) {
 }
 export function listSessionEvents(hippoRoot, tenantId, options = {}) {
     assertTenantId('listSessionEvents', tenantId);
-    const db = openStore(hippoRoot);
-    try {
+    return onHandle(hippoRoot, (db) => {
         const clauses = ['tenant_id = ?'];
         const params = [tenantId];
         if (options.session_id) {
@@ -267,19 +230,12 @@ export function listSessionEvents(hippoRoot, tenantId, options = {}) {
       LIMIT ?
     `).all(...params);
         return rows.map(rowToSessionEvent).reverse();
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    }, openStore);
 }
-/**
- * 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.
- */
+/** Session_ids with a `session_complete` event newer than `sinceMs`; bounds the sleep auto-promotion scan to a fixed window. */
 export function findPromotableSessions(hippoRoot, tenantId, sinceMs) {
     assertTenantId('findPromotableSessions', tenantId);
-    const db = openStore(hippoRoot);
-    try {
+    return onHandle(hippoRoot, (db) => {
         // SAFETY: rows' shape matches the single `session_id` column selected
         // above.
         const rows = db.prepare(`
@@ -287,29 +243,19 @@ export function findPromotableSessions(hippoRoot, tenantId, sinceMs) {
       WHERE event_type = 'session_complete' AND created_at >= ? AND tenant_id = ?
     `).all(new Date(sinceMs).toISOString(), tenantId);
         return rows;
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    }, openStore);
 }
-/**
- * Idempotency guard — true if a trace-layer memory with this source_session_id
- * already exists.
- */
+/** 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 {
+    return onHandle(hippoRoot, (db) => {
         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);
-    }
+    }, openStore);
 }
 /** The owner a session id is bound to, or null. */
 function selectSessionOwnerAt(db, tenantId, sessionId) {

package/dist/store/set-aside.d.ts

@@ -0,0 +1,14 @@
+import type { DatabaseSyncLike } from '../db/index.js';
+import { type MemoryEntry } from '../core/memory.js';
+export declare const SYNC_ACTOR = "agent-memories";
+export type SetAsideWhy = 'note-gone' | 'note-changed' | 'handover' | 'project-merge' | 'project-repair';
+export type SetAsideResult = {
+    readonly kind: 'untagged';
+    readonly entry: MemoryEntry;
+} | {
+    readonly kind: 'dormant';
+    readonly id: string;
+};
+/** Design 6's set-aside on the caller's transaction: a pinned row only loses the tag, any other goes dormant, restorable. */
+export declare function setAsideRow(db: DatabaseSyncLike, tag: string, row: MemoryEntry, why: SetAsideWhy): SetAsideResult;
+//# sourceMappingURL=set-aside.d.ts.map

package/dist/store/set-aside.js

@@ -0,0 +1,23 @@
+// Takes an imported agent note out of recall on the caller's transaction; the note sync and the project repair both use it.
+import { appendAuditEvent } from './audit.js';
+import { insertDormantRow } from './dormant.js';
+import { calculateStrength } from '../core/memory.js';
+import { deleteEntryRowInTx, setEntryTagsInTx } from './entry-writes.js';
+export const SYNC_ACTOR = 'agent-memories';
+/** Design 6's set-aside on the caller's transaction: a pinned row only loses the tag, any other goes dormant, restorable. */
+export function setAsideRow(db, tag, row, why) {
+    const untagged = { ...row, tags: row.tags.filter((t) => t !== tag) };
+    const audit = (metadata) => appendAuditEvent(db, { tenantId: row.tenantId, actor: SYNC_ACTOR, op: 'agent_memory_set_aside', targetId: row.id, metadata });
+    if (row.pinned) {
+        setEntryTagsInTx(db, untagged);
+        audit({ why, untagged: true });
+        return { kind: 'untagged', entry: untagged };
+    }
+    const now = new Date();
+    // Sleep's dormant move skips kept rows, so the steps are written out here without its filter.
+    insertDormantRow(db, { entry: untagged, strength: calculateStrength(row, now), reason: 'source-deleted', dormantAt: now.toISOString() });
+    deleteEntryRowInTx(db, row, SYNC_ACTOR);
+    audit({ why });
+    return { kind: 'dormant', id: row.id };
+}
+//# sourceMappingURL=set-aside.js.map

package/dist/store/sqlite/busy.d.ts

@@ -0,0 +1,3 @@
+/** A held lock in any store: SQLite's busy codes or a port's StoreBusyError. */
+export declare function isStoreBusy<E>(error: E): boolean;
+//# sourceMappingURL=busy.d.ts.map

package/dist/store/sqlite/busy.js

@@ -0,0 +1,8 @@
+// Busy detection lives with the adapter, so the port names no SQLite error code.
+import { isSqliteBusy } from '../../db/busy.js';
+import { StoreBusyError } from '../port.js';
+/** A held lock in any store: SQLite's busy codes or a port's StoreBusyError. */
+export function isStoreBusy(error) {
+    return error instanceof StoreBusyError || isSqliteBusy(error);
+}
+//# sourceMappingURL=busy.js.map

package/dist/store/sqlite/connector-events-group.js

@@ -1,22 +1,19 @@
 // hippo.db's half of the ConnectorEvents store group: each call on a handle of its own.
-import { archiveDeletedArtifact, eventSeenAt, githubRouting, insertDlq, logEvent, seenEvent } from '../connectors/github.js';
+import { archiveDeletedArtifact, githubEventRecord, githubEventSeenAt, githubRouting, insertGitHubDlq, markGitHubEventSeen } from '../connectors/github.js';
 import { insertSlackDlq, markSlackEventSeen, rawMemoryIdForArtifactAt, slackEventRecord, slackEventSeenAt, slackTeamRoute } from '../connectors/slack.js';
 import { onHandle } from '../open.js';
 function eventRecord(hippoRoot, event) {
-    if (event.connector === 'slack')
-        return slackEventRecord(hippoRoot, event.eventId);
-    const logged = seenEvent(hippoRoot, event.idempotencyKey);
-    return logged ? { seen: true, memoryId: logged.memoryId } : { seen: false };
+    return event.connector === 'slack' ? slackEventRecord(hippoRoot, event.eventId) : githubEventRecord(hippoRoot, event.idempotencyKey);
 }
 function markEventSeen(hippoRoot, event) {
     if (event.connector === 'slack')
         return markSlackEventSeen(hippoRoot, event.eventId, null);
     const { idempotencyKey, deliveryId, eventName } = event;
-    logEvent(hippoRoot, { idempotencyKey, deliveryId, eventName, memoryId: null });
+    markGitHubEventSeen(hippoRoot, { idempotencyKey, deliveryId, eventName, memoryId: null });
 }
 function deletionTarget(hippoRoot, { event, artifactRef, tenantId }) {
     return onHandle(hippoRoot, (db) => {
-        const seen = event.connector === 'slack' ? slackEventSeenAt(db, event.eventId) : eventSeenAt(db, event.idempotencyKey);
+        const seen = event.connector === 'slack' ? slackEventSeenAt(db, event.eventId) : githubEventSeenAt(db, event.idempotencyKey);
         return seen ? { seen: true } : { seen: false, memoryId: rawMemoryIdForArtifactAt(db, artifactRef, tenantId) };
     });
 }
@@ -32,7 +29,7 @@ export function sqliteConnectorEvents(hippoRoot) {
         archiveDeletedArtifact: (archive) => archiveArtifact(hippoRoot, archive),
         slackTeamRoute: (teamId) => slackTeamRoute(hippoRoot, teamId),
         githubRouting: (query) => githubRouting(hippoRoot, query),
-        parkDeadLetter: (letter) => (letter.connector === 'slack' ? insertSlackDlq(hippoRoot, letter) : insertDlq(hippoRoot, letter)),
+        parkDeadLetter: (letter) => (letter.connector === 'slack' ? insertSlackDlq(hippoRoot, letter) : insertGitHubDlq(hippoRoot, letter)),
     };
 }
 /** The group as a served store answers it: each call runs at once and resolves through a Promise, so a throw rejects as another store's would. */

package/dist/store/sqlite/connector-writes-group.js

@@ -1,4 +1,4 @@
-import { eventMemoryAt, logEventAt } from '../connectors/github.js';
+import { githubEventMemoryAt, markGitHubEventSeenAt } from '../connectors/github.js';
 import { markSlackEventSeenAt, slackEventMemoryAt } from '../connectors/slack.js';
 import { stampOriginProject } from '../entry-row.js';
 import { writeEntryMirrors } from '../entry-writes.js';
@@ -13,10 +13,10 @@ function logEvent(db, event, memoryId) {
     if (event.connector === 'slack')
         return markSlackEventSeenAt(db, event.eventId, memoryId);
     const { idempotencyKey, deliveryId, eventName } = event;
-    return logEventAt(db, { idempotencyKey, deliveryId, eventName, memoryId });
+    return markGitHubEventSeenAt(db, { idempotencyKey, deliveryId, eventName, memoryId });
 }
 function loggedMemory(db, event) {
-    return event.connector === 'slack' ? slackEventMemoryAt(db, event.eventId) : eventMemoryAt(db, event.idempotencyKey);
+    return event.connector === 'slack' ? slackEventMemoryAt(db, event.eventId) : githubEventMemoryAt(db, event.idempotencyKey);
 }
 /** The record, then the log row, go in after the memory row and ahead of its remember row, as a second store must order them. */
 function writeWithCompanions(db, { entry, actor, event, quarantine }) {

package/dist/store/sqlite/entry-writes-group.js

@@ -2,12 +2,12 @@
 import { ConflictError, NotFoundError } from '../../core/api-errors.js';
 import { appendAuditEvent } from '../audit.js';
 import { isSqliteBusy, withWriteScope } from '../../db/index.js';
-import { errorMessage, log } from '../../util/log.js';
+import { errorFields, errorMessage, log } from '../../util/log.js';
 import { entryAfterOutcome } from '../../core/memory.js';
 import { archiveRawMemory } from '../raw-archive.js';
-import { ownScopeTouches } from '../recall-scope.js';
+import { ownScopeTouches } from '../../core/recall-scope.js';
 import { recordTraceOutcome } from '../recall-trace.js';
-import { RejectedValueError } from '../rejection.js';
+import { RejectedValueError } from '../../core/api-errors.js';
 import { markSummaryDirtyInTx } from '../summary-dirty.js';
 import { auditRejectionRefusal } from '../audit-event.js';
 import { deleteEntryCore } from '../delete-and-batch.js';
@@ -155,7 +155,7 @@ function cleanArchivedMirrors(db, hippoRoot, id) {
         removeEntryMirrors(hippoRoot, id);
     }
     catch (mirrorErr) {
-        log.error(`archiveRaw: mirror cleanup failed for ${id} (will retry via reaper on next openHippoDb): ${errorMessage(mirrorErr)}`);
+        log.error(`archiveRaw: mirror cleanup failed for ${id} (will retry via reaper on next openHippoDb): ${errorMessage(mirrorErr)}`, errorFields(mirrorErr));
         return;
     }
     try {

package/dist/store/sqlite/error-codec.js

@@ -1,16 +1,19 @@
-// A thrown error crosses the worker boundary as plain data and arrives as an instance of its class: the server's mappers test `instanceof`, `errcode` and fields.
+// A thrown error crosses the worker boundary as plain data and arrives as an instance
+// of its class: the server's mappers test `instanceof`, `errcode` and fields.
 import { BadRequestError, ConflictError, ForbiddenError, NotFoundError } from '../../core/api-errors.js';
-import { IncompatibleBinaryError, StoreBusyError } from '../../db/index.js';
+import { RawAppendOnlyError } from '../../core/raw-append-only.js';
+import { IncompatibleBinaryError } from '../../db/index.js';
+import { StoreBusyError } from '../port.js';
 import { BodyTimeoutError, BodyTooLargeError, HttpError } from '../../util/http-util.js';
 import { errorMessage, log } from '../../util/log.js';
-import { ScopeForbiddenError } from '../recall-scope.js';
-import { RejectedValueError } from '../rejection.js';
+import { ScopeForbiddenError } from '../../core/recall-scope.js';
+import { RejectedValueError } from '../../core/api-errors.js';
 import { OtherStoreFolderError, SqliteBlockedError, StoreNotPortedError } from '../../util/sqlite-blocked.js';
 // Every class the server maps by, at or below the store layer. Abstract ApiError is absent: only its four subclasses are thrown.
 const CLASSES = [
     Error, TypeError, RangeError, SyntaxError, ReferenceError, EvalError, URIError,
     HttpError, BodyTooLargeError, BodyTimeoutError,
-    BadRequestError, ForbiddenError, NotFoundError, ConflictError, RejectedValueError, ScopeForbiddenError,
+    BadRequestError, ForbiddenError, NotFoundError, ConflictError, RejectedValueError, ScopeForbiddenError, RawAppendOnlyError,
     SqliteBlockedError, StoreNotPortedError, OtherStoreFolderError,
     StoreBusyError, IncompatibleBinaryError,
 ];

package/dist/store/sqlite/executor.d.ts

@@ -23,6 +23,7 @@ export interface SqliteExecutor {
     /** Stops the writer thread as a crash would: its running and queued calls reject, and the next write starts a fresh thread. */
     terminateWriter(): void;
 }
-/** Threads for the hippo.db under `hippoRoot`: one writer and two readers. The first call starts the writer for the store's setup; a reader starts at its own first call. */
+/** Threads for the hippo.db under `hippoRoot`: one writer and two readers. The first
+ * call starts the writer for the store's setup; a reader starts at its own first call. */
 export declare function createSqliteExecutor(hippoRoot: string, opts?: ExecutorOptions): SqliteExecutor;
 //# sourceMappingURL=executor.d.ts.map

package/dist/store/sqlite/executor.js

@@ -2,11 +2,12 @@
 import { fileURLToPath } from 'node:url';
 import { SHARE_ENV, Worker } from 'node:worker_threads';
 import { addAuditWriteFailures } from '../audit.js';
-import { getHippoDbPath, SERVER_DB_WAIT_MS, StoreBusyError } from '../../db/index.js';
+import { getHippoDbPath, SERVER_DB_WAIT_MS } from '../../db/index.js';
+import { StoreBusyError } from '../port.js';
 import { autoCheckpointPages } from '../../db/wal-checkpointer.js';
 import { envStoreQueueMax } from '../../util/env.js';
 import { DeadlineExceededError } from '../../util/http-util.js';
-import { errorMessage, log } from '../../util/log.js';
+import { errorFields, errorMessage, log } from '../../util/log.js';
 import { requestScopes } from '../../util/request-scope.js';
 import { decodeError } from './error-codec.js';
 import { workerCounts } from './executor-counts.js';
@@ -27,6 +28,10 @@ const DEFAULT_WRITE_GRACE_MS = 2000;
 function laneOf(mode) {
     return { mode, queue: [], running: undefined, worker: undefined, stopping: undefined, commitFlag: undefined };
 }
+// A thread that will not stop leaves a live worker behind, so the rejection is logged rather than dropped.
+function terminateLogged(worker) {
+    worker.terminate().catch((err) => log.warn('the store worker did not terminate cleanly', errorFields(err)));
+}
 /** Gives `pending`'s caller its one answer; a second call does nothing. */
 function finish(pending, answer) {
     if (pending.answered)
@@ -153,7 +158,7 @@ class WorkerPool {
     #stopReader(lane, worker, pending) {
         finish(pending, () => pending.fail(new DeadlineExceededError(READ_LATE)));
         lane.stopping = worker;
-        void worker.terminate();
+        terminateLogged(worker);
     }
     // Before its commit flag a stopped write is a known rollback; after it the thread is left to finish, since stopping it could not undo the write.
     #stopWriter(lane, worker, pending) {
@@ -195,7 +200,8 @@ class WorkerPool {
         return this.#exits.size;
     }
     terminateWriter() {
-        void this.#writer.worker?.terminate();
+        if (this.#writer.worker)
+            terminateLogged(this.#writer.worker);
     }
     #pump(lane) {
         if (lane.running !== undefined)
@@ -279,7 +285,8 @@ class WorkerPool {
             finish(pending, () => pending.fail(new StoreBusyError(WORKER_GONE, { cause })));
     }
 }
-/** Threads for the hippo.db under `hippoRoot`: one writer and two readers. The first call starts the writer for the store's setup; a reader starts at its own first call. */
+/** Threads for the hippo.db under `hippoRoot`: one writer and two readers. The first
+ * call starts the writer for the store's setup; a reader starts at its own first call. */
 export function createSqliteExecutor(hippoRoot, opts = {}) {
     return new WorkerPool(hippoRoot, opts);
 }

package/dist/store/sqlite/graph-reads-group.js

@@ -1,5 +1,5 @@
 // hippo.db's half of the GraphReads store group: one read snapshot around the walk the CLI graph commands run.
-import { canReadScope } from '../recall-scope.js';
+import { canReadScope } from '../../core/recall-scope.js';
 import { withGraphReadSnapshot } from '../graph-reads.js';
 import { graphViewRows } from '../graph-view-rows.js';
 export function sqliteGraphReads(hippoRoot) {