hippo-memory 1.70.0 → 1.71.0

package/dist/store/entry-reads.js

@@ -1,32 +1,22 @@
 import { closeHippoDb } from '../db/index.js';
 import { MEMORY_SELECT_COLUMNS, rowToEntry, parseJsonArray } from './rows.js';
-import { openStore } from './open.js';
+import { onHandle, openStore } from './open.js';
 import { escapeLike } from '../util/escape.js';
 import { originInSql } from '../core/project-identity.js';
 import { scopeAdmitSql } from './recall-scope.js';
 const MAX_IDS_PER_READ = 500;
 // The plus keeps SQLite on the primary key for an id list: with a bare tenant_id it walks every row of the tenant instead.
 export const TENANT_IS = '+tenant_id = ?';
-/**
- * Read a memory entry by ID.
- *
- * When `tenantId` is provided, the read is scoped to that tenant (cross-tenant
- * lookups return null). When omitted, no tenant filter is applied — preserves
- * legacy single-tenant callers and the writeEntry/readEntry round-trip.
- */
+/** Read a memory entry by ID. With `tenantId` the read is tenant-scoped (cross-tenant returns null); omitted, no tenant filter is applied. */
 export function readEntry(hippoRoot, id, tenantId) {
-    const db = openStore(hippoRoot);
-    try {
+    return onHandle(hippoRoot, (db) => {
         // SAFETY: both branches select exactly MEMORY_SELECT_COLUMNS, matching
         // MemoryRow's field set.
         const row = tenantId !== undefined
             ? db.prepare(`SELECT ${MEMORY_SELECT_COLUMNS} FROM memories WHERE id = ? AND tenant_id = ?`).get(id, tenantId)
             : db.prepare(`SELECT ${MEMORY_SELECT_COLUMNS} FROM memories WHERE id = ?`).get(id);
         return row ? rowToEntry(row) : null;
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    }, openStore);
 }
 /** Ids per `IN (...)` list: far under SQLite's bound-parameter limit, with room for the tenant filter. */
 export const ID_CHUNK = 500;
@@ -41,8 +31,7 @@ export function chunked(items, size = ID_CHUNK) {
 export function heldIdLookup(hippoRoot, tenantId, ids) {
     const held = new Map();
     const lookUp = (asked) => {
-        const db = openStore(hippoRoot);
-        try {
+        onHandle(hippoRoot, (db) => {
             for (const chunk of chunked([...new Set(asked)])) {
                 for (const id of chunk)
                     held.set(id, false);
@@ -51,10 +40,7 @@ export function heldIdLookup(hippoRoot, tenantId, ids) {
                 for (const row of rows)
                     held.set(row.id, true);
             }
-        }
-        finally {
-            closeHippoDb(db);
-        }
+        }, openStore);
     };
     if (ids.length > 0)
         lookUp(ids);
@@ -99,48 +85,30 @@ export function selectChildrenByParent(db, parentIds, tenantId) {
     }
     return byParent;
 }
-/**
- * Batched lookup. Caps at 500 ids per call to keep the IN(?,?,...) clause
- * within SQLite limits. Tenant filter is enforced when `tenantId` is passed.
- * Used by DAG-aware recall to fetch parent summaries for a set of overflowed leaves.
- */
+/** Batched lookup, capped at 500 ids per call to keep IN(?,?,...) within SQLite limits; tenant filter enforced when `tenantId` is passed. */
 export function loadEntriesByIds(hippoRoot, ids, tenantId) {
     if (ids.length === 0)
         return [];
     const capped = ids.slice(0, MAX_IDS_PER_READ);
-    const db = openStore(hippoRoot);
-    try {
+    return onHandle(hippoRoot, (db) => {
         const placeholders = capped.map(() => '?').join(',');
-        // Without ORDER BY, rows follow SQLite's IN(...) scan order, which is undefined w.r.t. `ids`.
-        // SAFETY: both branches select exactly MEMORY_SELECT_COLUMNS, matching
-        // MemoryRow's field set.
+        // Without ORDER BY, rows follow SQLite's IN(...) scan order, undefined w.r.t. `ids`.
+        // SAFETY: both branches select exactly MEMORY_SELECT_COLUMNS, matching MemoryRow's field set.
         const rows = tenantId !== undefined
             ? db.prepare(`SELECT ${MEMORY_SELECT_COLUMNS} FROM memories WHERE id IN (${placeholders}) AND ${TENANT_IS} ORDER BY created ASC, content ASC, id ASC`).all(...capped, tenantId)
             : db.prepare(`SELECT ${MEMORY_SELECT_COLUMNS} FROM memories WHERE id IN (${placeholders}) ORDER BY created ASC, content ASC, id ASC`).all(...capped);
         return rows.map(rowToEntry);
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    }, openStore);
 }
 function originClause(origins) {
     return origins === undefined ? '' : ` AND (origin_project = '' OR ${originInSql(origins)})`;
 }
-/**
- * All `kind='raw'` rows for a given session, tenant-scoped, returned
- * oldest-first. Used by `api.assemble` to walk a session's chronological
- * context. Excludes superseded rows.
- *
- * Cap semantics: when `cap` is provided, the NEWEST `cap` rows are loaded (DESC LIMIT server-side,
- * reversed client-side); ASC + LIMIT would drop the newest rows and break fresh-tail in assemble.
- *
- * Returns `[]` for an empty sessionId. Final order: `created ASC, id ASC`.
- */
+/** All `kind='raw'` rows for a session, tenant-scoped, oldest-first, excluding superseded; `[]` for an empty sessionId.
+ * With `cap`, the NEWEST rows are loaded (DESC LIMIT, reversed client-side); ASC + LIMIT would drop the newest and break fresh-tail in assemble. */
 export function loadSessionRawMemories(hippoRoot, sessionId, tenantId, cap, origins) {
     if (!sessionId)
         return [];
-    const db = openStore(hippoRoot);
-    try {
+    return onHandle(hippoRoot, (db) => {
         const params = [];
         let sql = `SELECT ${MEMORY_SELECT_COLUMNS} FROM memories WHERE kind = 'raw' AND source_session_id = ? AND superseded_by IS NULL`;
         params.push(sessionId);
@@ -161,29 +129,14 @@ export function loadSessionRawMemories(hippoRoot, sessionId, tenantId, cap, orig
         // SAFETY: sql starts from MEMORY_SELECT_COLUMNS, matching MemoryRow.
         const rows = db.prepare(sql).all(...params);
         return rows.map(rowToEntry);
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    }, openStore);
 }
-/**
- * Pre-cap, scope-aware row count for a session. Lets `assemble` report
- * the full session size even when `rowCap` truncates the loaded window,
- * WITHOUT leaking rows the caller wouldn't have been allowed to load.
- *
- * An unscoped COUNT would let a no-scope caller infer private rows by comparing `totalRaw`
- * against `items.length`, so this SQL-encodes the default-deny rule `passesScopeFilterForRecall` applies in TS:
- *   - explicit scope passed: exact-match
- *   - no scope: `scopeAdmitSql`'s default deny, which admits `ownScope`, the caller's personal scope.
- *
- * `tenantId` is optional for back-compat. Pass `undefined` only when
- * intentionally counting cross-tenant; `assemble()` passes `ctx.tenantId`.
- */
+/** Pre-cap, scope-aware row count for a session, so `assemble` reports the full size without leaking rows the caller could not load. Mirrors
+ * `passesScopeFilterForRecall`'s default-deny: explicit scope matches exactly, none admits only `ownScope`. `tenantId` undefined counts cross-tenant. */
 export function countSessionRawMemories(hippoRoot, sessionId, tenantId, scope, ownScope, origins) {
     if (!sessionId)
         return 0;
-    const db = openStore(hippoRoot);
-    try {
+    return onHandle(hippoRoot, (db) => {
         const params = [];
         let sql = `SELECT COUNT(*) AS c FROM memories WHERE kind = 'raw' AND source_session_id = ? AND superseded_by IS NULL`;
         params.push(sessionId);
@@ -205,31 +158,15 @@ export function countSessionRawMemories(hippoRoot, sessionId, tenantId, scope, o
         // SAFETY: row's shape matches the single `COUNT(*) AS c` column above.
         const row = db.prepare(sql).get(...params);
         return Number(row?.c ?? 0);
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    }, openStore);
 }
-/**
- * Last N kind='raw' memories by `created` desc. Tenant scoped. When
- * `sessionId` is supplied, also constrains to a specific session — that
- * is the correct shape for "what did I just see in THIS session."
- *
- * Without `sessionId`, concurrent sessions in a tenant surface each other's rows as fresh tail;
- * pass undefined only for "anything new across the whole tenant".
- *
- * Bounded count cap at 200 — beyond that the caller should filter via
- * tags/scope rather than time-windowed recall.
- *
- * The tenant-wide shape is the back-compat default but discouraged; `api.recall` throws
- * `RecallContractError` for it when `HIPPO_REQUIRE_SESSION_SCOPED_FRESH_TAIL=1` is set.
- */
+/** Last N kind='raw' memories by `created` desc, tenant-scoped, max 200; pass `sessionId` or concurrent sessions show up in each other's fresh tail.
+ * The tenant-wide shape is discouraged: `api.recall` throws `RecallContractError` for it when `HIPPO_REQUIRE_SESSION_SCOPED_FRESH_TAIL=1`. */
 export function loadFreshRawMemories(hippoRoot, count, tenantId, sessionId, origins) {
     if (count <= 0)
         return [];
     const capped = Math.min(count, 200);
-    const db = openStore(hippoRoot);
-    try {
+    return onHandle(hippoRoot, (db) => {
         const params = [];
         let sql = `SELECT ${MEMORY_SELECT_COLUMNS} FROM memories WHERE kind = 'raw' AND superseded_by IS NULL`;
         if (tenantId !== undefined) {
@@ -249,35 +186,52 @@ export function loadFreshRawMemories(hippoRoot, count, tenantId, sessionId, orig
         // SAFETY: sql starts from MEMORY_SELECT_COLUMNS, matching MemoryRow.
         const rows = db.prepare(sql).all(...params);
         return rows.map(rowToEntry);
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    }, openStore);
 }
-/**
- * Load all entries from SQLite.
- *
- * When `tenantId` is provided, results are scoped to that tenant. Omitting it
- * yields all rows (legacy behavior used by consolidate/autolearn etc.). Recall
- * paths that surface results to a user MUST pass a resolved tenant.
- */
+/** Load all entries from SQLite; omitting `tenantId` yields all rows (legacy). Recall paths that surface results to a user MUST pass a resolved tenant. */
 export function loadAllEntries(hippoRoot, tenantId) {
+    return onHandle(hippoRoot, (db) => {
+        return selectAllEntries(db, tenantId);
+    }, openStore);
+}
+/** Every tenant's memory ids in loadAllEntries' order, for a caller that reads the rows a page at a time instead of holding them all. */
+export function loadAllEntryIds(hippoRoot) {
+    return onHandle(hippoRoot, (db) => {
+        // SAFETY: the SELECT names exactly the one column read.
+        return db.prepare('SELECT id FROM memories ORDER BY created ASC, id ASC').all().map((row) => row.id);
+    }, openStore);
+}
+/** Every entry plus a by-id lookup of each as loaded, rebuilt from its row on first use, so no deep copy of the store is kept. */
+export function loadAllEntriesWithBase(hippoRoot) {
     const db = openStore(hippoRoot);
+    let rows;
     try {
-        return selectAllEntries(db, tenantId);
+        rows = selectAllRows(db);
     }
     finally {
         closeHippoDb(db);
     }
+    const byId = new Map(rows.map((row) => [row.id, row]));
+    const built = new Map();
+    const get = (id) => {
+        let entry = built.get(id);
+        const row = byId.get(id);
+        if (!entry && row)
+            built.set(id, (entry = rowToEntry(row)));
+        return entry;
+    };
+    return { entries: rows.map(rowToEntry), base: { get } };
 }
-/** Every memory row on an open connection, so a caller can read inside its own transaction. */
-export function selectAllEntries(db, tenantId) {
+function selectAllRows(db, tenantId) {
     // SAFETY: both branches select exactly MEMORY_SELECT_COLUMNS, matching
     // MemoryRow's field set.
-    const rows = tenantId !== undefined
+    return tenantId !== undefined
         ? db.prepare(`SELECT ${MEMORY_SELECT_COLUMNS} FROM memories WHERE tenant_id = ? ORDER BY created ASC, id ASC`).all(tenantId)
         : db.prepare(`SELECT ${MEMORY_SELECT_COLUMNS} FROM memories ORDER BY created ASC, id ASC`).all();
-    return rows.map(rowToEntry);
+}
+/** Every memory row on an open connection, so a caller can read inside its own transaction. */
+export function selectAllEntries(db, tenantId) {
+    return selectAllRows(db, tenantId).map(rowToEntry);
 }
 /** Live rows whose source starts with `prefix`, on the caller's handle; LIKE folds case, so the prefix is checked again exactly. */
 export function selectLiveEntriesBySourcePrefix(db, tenantId, prefix) {
@@ -288,32 +242,24 @@ export function selectLiveEntriesBySourcePrefix(db, tenantId, prefix) {
 // Content of every team-visible tenant row tagged `tag`, without reading the rest of the store; `origins` keeps one project's rows and user-global ones.
 // No owner: a personal or connector-private row must never answer `duplicate` for, or stop, a team copy. `instr` prefilters; `includes` re-checks.
 export function loadContentsWithTag(hippoRoot, tenantId, tag, origins) {
-    const db = openStore(hippoRoot);
-    try {
+    return onHandle(hippoRoot, (db) => {
         const inProject = origins === undefined ? '' : ` AND (origin_project = '' OR ${originInSql(origins)})`;
         const admit = scopeAdmitSql('');
         /** SAFETY: rows' shape matches the two columns named in the SELECT below. */
         const rows = db.prepare(`SELECT content, tags_json FROM memories WHERE tenant_id = ? AND instr(tags_json, ?) > 0${inProject} AND ${admit.sql}`).all(tenantId, JSON.stringify(tag), ...(origins ?? []), ...admit.params);
         return rows.filter((r) => parseJsonArray(r.tags_json).includes(tag)).map((r) => r.content);
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    }, openStore);
 }
 /** Live raw rows whose artifact_ref matches a LIKE pattern, for one tenant; the store is set up first when it is new. */
 export function loadVaultRawRows(hippoRoot, likeParam, tenantId) {
-    const db = openStore(hippoRoot);
-    try {
+    return onHandle(hippoRoot, (db) => {
         // SAFETY: query selects exactly the columns of VaultRawRow, in the same
         // names, from the memories table this module owns.
         return db
             .prepare(`SELECT id, artifact_ref, tags_json, scope FROM memories
            WHERE artifact_ref LIKE ? ESCAPE '\\' AND tenant_id = ? AND kind = 'raw'`)
             .all(likeParam, tenantId);
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    }, openStore);
 }
 /** Reads memories from a store whose schema may predate some columns; `columns` is the table's real column set. */
 export function selectPreviewRows(db, columns, tenantId) {
@@ -352,10 +298,10 @@ export function selectRowsOutsideSourcePrefixAt(db, tenantId, sourcePrefix, orig
     return db.prepare(`SELECT id, content, source FROM memories
       WHERE tenant_id = ? AND superseded_by IS NULL AND substr(source, 1, ${sourcePrefix.length}) != ?${visible}`).all(...params);
 }
-/** Content of a tenant's live rows written by `source` and tagged `tag` that no extraction produced, in loadAllEntries' order and in every scope; `exceptSessionId` drops one session's own rows. */
+/** Content of a tenant's live rows written by `source` and tagged `tag` that no extraction produced,
+ * in loadAllEntries' order and in every scope; `exceptSessionId` drops one session's own rows. */
 export function loadLiveContentsBySourceAndTag(hippoRoot, tenantId, source, tag, exceptSessionId) {
-    const db = openStore(hippoRoot);
-    try {
+    return onHandle(hippoRoot, (db) => {
         /** SAFETY: rows' shape matches the two columns named in the SELECT below. */
         const rows = db.prepare(`SELECT content, tags_json FROM memories
        WHERE tenant_id = ? AND source = ? AND instr(tags_json, ?) > 0
@@ -363,23 +309,16 @@ export function loadLiveContentsBySourceAndTag(hippoRoot, tenantId, source, tag,
          AND (source_session_id IS NULL OR source_session_id != ?)
        ORDER BY created ASC, id ASC`).all(tenantId, source, JSON.stringify(tag), exceptSessionId);
         return rows.filter((r) => parseJsonArray(r.tags_json).includes(tag)).map((r) => r.content);
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    }, openStore);
 }
 /** Every tenant's distilled rows nothing has superseded, in loadAllEntries' order: the rows that can be each other's duplicate. */
 export function loadCurrentDistilledEntries(hippoRoot) {
-    const db = openStore(hippoRoot);
-    try {
+    return onHandle(hippoRoot, (db) => {
         // SAFETY: selects exactly MEMORY_SELECT_COLUMNS, matching MemoryRow's field set.
         const rows = db.prepare(`SELECT ${MEMORY_SELECT_COLUMNS} FROM memories
        WHERE COALESCE(kind, 'distilled') = 'distilled' AND COALESCE(superseded_by, '') = ''
        ORDER BY created ASC, id ASC`).all();
         return rows.map(rowToEntry);
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    }, openStore);
 }
 //# sourceMappingURL=entry-reads.js.map

package/dist/store/entry-row.d.ts

@@ -1,7 +1,8 @@
 import type { MemoryEntry } from '../core/memory.js';
 import { openHippoDb } from '../db/index.js';
 export declare function upsertEntryRow(db: ReturnType<typeof openHippoDb>, entry: MemoryEntry): void;
-/** The row alone, with no rejection guard or full-text row, for `upsertEntryRow` and for `batchWriteAndDelete`, which probes tombstones and indexes per batch. Returns whether the row is new. */
+/** The row alone, with no rejection guard or full-text row, for `upsertEntryRow` and for
+ * `batchWriteAndDelete`, which probes tombstones and indexes per batch. Returns whether the row is new. */
 export declare function upsertMemoryRow(db: ReturnType<typeof openHippoDb>, entry: MemoryEntry): boolean;
 export declare function syncFtsRow(db: ReturnType<typeof openHippoDb>, entry: MemoryEntry, isNewRow?: boolean): void;
 export declare function ftsRowExists(db: ReturnType<typeof openHippoDb>, id: string): boolean;
@@ -13,40 +14,10 @@ export declare function ftsDrift(hippoRoot: string, repair: boolean): {
     memories: number;
     fts: number;
 } | null;
-/**
- * Write a memory entry to SQLite and refresh compatibility mirrors.
- *
- * `opts.actor` defaults to 'cli' so unauthenticated direct-CLI callers still
- * get the right audit attribution. The HTTP server and api.* layer pass
- * the resolved actor (`api_key:<key_id>` / `localhost:cli`) so audit events
- * land with one row per write, no double-emit.
- *
- * `opts.afterWrite` is invoked inside the same SAVEPOINT as the memories
- * INSERT (mirrors archiveRawMemory's shape in raw-archive.ts). On callback
- * throw, the SAVEPOINT rolls back — the memory row never lands, and the
- * filesystem mirrors / audit emit never run. Used by connectors to
- * stamp idempotency rows atomically with the memory write.
- */
-/**
- * Stamp origin_project from the store's own location when the entry has
- * never been stamped (v39 memory scope isolation). The store dir is
- * `<project>/.hippo`, so its parent resolves to the owning project; the
- * home/global store resolves to '' (user-global). Callers that know a better
- * origin (shareMemory, syncGlobalToLocal) set entry.origin_project before
- * writing and this is a no-op. Returns a stamped copy; never mutates.
- *
- * NULL is PRESERVED, not re-stamped: it means no known project (a legacy row with no evidence, or a write to a
- * shared store that named none) and ambient context denies it, so a writeback must not launder it.
- */
+/** Stamp origin_project from the store's own location (parent of `<project>/.hippo`; the home store is '' = user-global) when never stamped; returns a copy.
+ * NULL is PRESERVED: it means no known project and ambient context denies it, so a writeback must not launder it. */
 export declare function stampOriginProject(hippoRoot: string, entry: MemoryEntry): MemoryEntry;
-/**
- * Import-time variant for a mirror with no origin field (an explicit null stays null): used only where evidence exists
- * for rows that predate the origin column - the legacy-markdown bootstrap and
- * rebuildIndex import, which are the markdown-store equivalent of the v39 SQL
- * backfill. Same evidence order as the migration: the provenance source
- * (`shared:<project>:` / `promoted:<localRoot>`) wins over the destination
- * store's location, so a shared row imported into the global store keeps its
- * owning project instead of becoming user-global.
- */
+/** Import-time variant for a mirror with no origin field (an explicit null stays null), for rows predating the origin column.
+ * Like the v39 backfill, the provenance source (`shared:<project>:` / `promoted:<localRoot>`) wins over the destination store's location. */
 export declare function stampOriginProjectForImport(hippoRoot: string, entry: MemoryEntry): MemoryEntry;
 //# sourceMappingURL=entry-row.d.ts.map

package/dist/store/entry-row.js

@@ -1,12 +1,14 @@
+import { DEFAULT_TENANT_ID } from '../util/env.js';
 import { closeHippoDb, ftsRowCounts, openHippoDb, isFtsAvailable, repairFtsDrift } from '../db/index.js';
 import { fallbackOrigin, originFromSource } from '../core/project-identity.js';
 import { checkRejectionGuard } from './rejection.js';
 import { errorMessage, log } from '../util/log.js';
 export function upsertEntryRow(db, entry) {
-    checkRejectionGuard(db, entry.tenantId ?? 'default', entry.id, entry.content);
+    checkRejectionGuard(db, entry.tenantId ?? DEFAULT_TENANT_ID, entry.id, entry.content);
     syncFtsRow(db, entry, upsertMemoryRow(db, entry));
 }
-/** The row alone, with no rejection guard or full-text row, for `upsertEntryRow` and for `batchWriteAndDelete`, which probes tombstones and indexes per batch. Returns whether the row is new. */
+/** The row alone, with no rejection guard or full-text row, for `upsertEntryRow` and for
+ * `batchWriteAndDelete`, which probes tombstones and indexes per batch. Returns whether the row is new. */
 export function upsertMemoryRow(db, entry) {
     const isNewRow = db.prepare(`SELECT 1 FROM memories WHERE id = ?`).get(entry.id) === undefined;
     db.prepare(UPSERT_MEMORY_SQL).run(...memoryRowValues(entry));
@@ -102,7 +104,7 @@ function memoryRowValues(entry) {
         entry.scope ?? null,
         entry.owner ?? null,
         entry.artifact_ref ?? null,
-        entry.tenantId ?? 'default',
+        entry.tenantId ?? DEFAULT_TENANT_ID,
         entry.origin_project ?? null,
         entry.descendant_count ?? 0,
         entry.earliest_at ?? null,
@@ -181,45 +183,15 @@ export function ftsDrift(hippoRoot, repair) {
         closeHippoDb(db);
     }
 }
-/**
- * Write a memory entry to SQLite and refresh compatibility mirrors.
- *
- * `opts.actor` defaults to 'cli' so unauthenticated direct-CLI callers still
- * get the right audit attribution. The HTTP server and api.* layer pass
- * the resolved actor (`api_key:<key_id>` / `localhost:cli`) so audit events
- * land with one row per write, no double-emit.
- *
- * `opts.afterWrite` is invoked inside the same SAVEPOINT as the memories
- * INSERT (mirrors archiveRawMemory's shape in raw-archive.ts). On callback
- * throw, the SAVEPOINT rolls back — the memory row never lands, and the
- * filesystem mirrors / audit emit never run. Used by connectors to
- * stamp idempotency rows atomically with the memory write.
- */
-/**
- * Stamp origin_project from the store's own location when the entry has
- * never been stamped (v39 memory scope isolation). The store dir is
- * `<project>/.hippo`, so its parent resolves to the owning project; the
- * home/global store resolves to '' (user-global). Callers that know a better
- * origin (shareMemory, syncGlobalToLocal) set entry.origin_project before
- * writing and this is a no-op. Returns a stamped copy; never mutates.
- *
- * NULL is PRESERVED, not re-stamped: it means no known project (a legacy row with no evidence, or a write to a
- * shared store that named none) and ambient context denies it, so a writeback must not launder it.
- */
+/** Stamp origin_project from the store's own location (parent of `<project>/.hippo`; the home store is '' = user-global) when never stamped; returns a copy.
+ * NULL is PRESERVED: it means no known project and ambient context denies it, so a writeback must not launder it. */
 export function stampOriginProject(hippoRoot, entry) {
     if (entry.origin_project !== undefined)
         return entry;
     return { ...entry, origin_project: fallbackOrigin(hippoRoot) };
 }
-/**
- * Import-time variant for a mirror with no origin field (an explicit null stays null): used only where evidence exists
- * for rows that predate the origin column - the legacy-markdown bootstrap and
- * rebuildIndex import, which are the markdown-store equivalent of the v39 SQL
- * backfill. Same evidence order as the migration: the provenance source
- * (`shared:<project>:` / `promoted:<localRoot>`) wins over the destination
- * store's location, so a shared row imported into the global store keeps its
- * owning project instead of becoming user-global.
- */
+/** Import-time variant for a mirror with no origin field (an explicit null stays null), for rows predating the origin column.
+ * Like the v39 backfill, the provenance source (`shared:<project>:` / `promoted:<localRoot>`) wins over the destination store's location. */
 export function stampOriginProjectForImport(hippoRoot, entry) {
     if (entry.origin_project !== undefined)
         return entry;

package/dist/store/entry-writes.d.ts

@@ -6,26 +6,20 @@ export interface WriteEntryOptions {
     /** Runs after the row commits and before the mirrors, on an idle connection; keep it best-effort. */
     afterCommit?: () => void;
 }
+/** Write an entry to SQLite and refresh mirrors; `opts.afterWrite` runs in the same SAVEPOINT as the INSERT, so a throw rolls the row back.
+ * `opts.actor` defaults to 'cli'; the api layer passes the resolved actor so the audit log gets one row per write. */
 export declare function writeEntry(hippoRoot: string, entry: MemoryEntry, opts?: WriteEntryOptions): void;
-/** writeEntry for each of `entries` in one transaction, so all land or none; each keeps its audit row, and mirrors follow the commit. Returns how many were written. */
+/** writeEntry for each of `entries` in one transaction, so all land or none; each
+ * keeps its audit row, and mirrors follow the commit. Returns how many were written. */
 export declare function writeEntriesTogether(hippoRoot: string, entries: readonly MemoryEntry[]): number;
-/** writeEntry for each of `entries` on one open store, so the open and its lock wait are paid once; each row commits alone, and none opens the store when the list is empty. */
+/** writeEntry for each of `entries` on one open store, so the open and its lock wait are
+ * paid once; each row commits alone, and none opens the store when the list is empty. */
 export declare function writeEntriesSeparately(hippoRoot: string, entries: readonly MemoryEntry[]): void;
-/** Adds `tag` to each of a tenant's rows that lacks it, in `ids` order, each read fresh on one open store and committed alone; an id the tenant does not hold is skipped. */
+/** Adds `tag` to each of a tenant's rows that lacks it, in `ids` order, each read fresh
+ * on one open store and committed alone; an id the tenant does not hold is skipped. */
 export declare function addTagToEntries(hippoRoot: string, tenantId: string, ids: readonly string[], tag: string): void;
-/**
- * DB-only write path. Caller owns the open `db` handle. Runs upsert +
- * afterWrite hook + audit row inside one withWriteScope. Caller
- * is responsible for opening `db`, optionally wrapping in a larger BEGIN/
- * COMMIT (e.g. supersede's BEGIN IMMEDIATE), closing `db`, AND calling
- * `writeEntryMirrors` after the larger tx commits — mirrors must run
- * post-commit so a rolled-back tx never leaves orphan markdown.
- *
- * Audit-order note: the audit row is emitted INSIDE the write scope, so audit
- * commits atomically with the row INSERT. A subsequent mirror failure cannot
- * leave a recorded audit entry without its corresponding DB row. This is a
- * documented hardening over the prior writeEntry-as-monolith ordering.
- */
+/** DB-only write path: upsert, afterWrite hook and audit row inside one withWriteScope; the caller owns `db` and must call `writeEntryMirrors` after any
+ * outer tx commits, so a rolled-back tx never leaves orphan markdown. The audit row commits atomically with the INSERT. */
 export declare function writeEntryDbOnly(db: DatabaseSyncLike, entry: MemoryEntry, opts?: {
     actor?: string;
     afterWrite?: (db: DatabaseSyncLike, memoryId: string) => void;

package/dist/store/entry-writes.js

@@ -7,17 +7,16 @@ import { auditRejectionRefusal, audit } from './audit-event.js';
 import { selectEntriesByIds } from './entry-reads.js';
 import { stampOriginProject, upsertEntryRow, syncFtsRow, deleteFtsRow } from './entry-row.js';
 import { mirrorBestEffort, writeMarkdownMirror } from './mirrors.js';
-import { openStore } from './open.js';
+import { onHandle, openStore } from './open.js';
+/** Write an entry to SQLite and refresh mirrors; `opts.afterWrite` runs in the same SAVEPOINT as the INSERT, so a throw rolls the row back.
+ * `opts.actor` defaults to 'cli'; the api layer passes the resolved actor so the audit log gets one row per write. */
 export function writeEntry(hippoRoot, entry, opts) {
-    const db = openStore(hippoRoot);
-    try {
+    onHandle(hippoRoot, (db) => {
         writeEntryOn(db, hippoRoot, entry, opts);
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    }, openStore);
 }
-/** writeEntry for each of `entries` in one transaction, so all land or none; each keeps its audit row, and mirrors follow the commit. Returns how many were written. */
+/** writeEntry for each of `entries` in one transaction, so all land or none; each
+ * keeps its audit row, and mirrors follow the commit. Returns how many were written. */
 export function writeEntriesTogether(hippoRoot, entries) {
     const stamped = entries.map((entry) => stampOriginProject(hippoRoot, entry));
     const db = openStore(hippoRoot);
@@ -40,23 +39,20 @@ export function writeEntriesTogether(hippoRoot, entries) {
     }
     return stamped.length;
 }
-/** writeEntry for each of `entries` on one open store, so the open and its lock wait are paid once; each row commits alone, and none opens the store when the list is empty. */
+/** writeEntry for each of `entries` on one open store, so the open and its lock wait are
+ * paid once; each row commits alone, and none opens the store when the list is empty. */
 export function writeEntriesSeparately(hippoRoot, entries) {
     if (entries.length === 0)
         return;
-    const db = openStore(hippoRoot);
-    try {
+    onHandle(hippoRoot, (db) => {
         for (const entry of entries)
             writeEntryOn(db, hippoRoot, entry);
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    }, openStore);
 }
-/** Adds `tag` to each of a tenant's rows that lacks it, in `ids` order, each read fresh on one open store and committed alone; an id the tenant does not hold is skipped. */
+/** Adds `tag` to each of a tenant's rows that lacks it, in `ids` order, each read fresh
+ * on one open store and committed alone; an id the tenant does not hold is skipped. */
 export function addTagToEntries(hippoRoot, tenantId, ids, tag) {
-    const db = openStore(hippoRoot);
-    try {
+    onHandle(hippoRoot, (db) => {
         const live = selectEntriesByIds(db, ids, tenantId);
         for (const id of new Set(ids)) {
             const entry = live.get(id);
@@ -64,10 +60,7 @@ export function addTagToEntries(hippoRoot, tenantId, ids, tag) {
                 continue;
             writeEntryOn(db, hippoRoot, { ...entry, tags: [...entry.tags, tag] });
         }
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    }, openStore);
 }
 /** writeEntry on the caller's open store, so a loop of writes opens the store once; each row still commits alone. */
 function writeEntryOn(db, hippoRoot, entry, opts) {
@@ -86,19 +79,8 @@ function writeEntryOn(db, hippoRoot, entry, opts) {
         throw error;
     }
 }
-/**
- * DB-only write path. Caller owns the open `db` handle. Runs upsert +
- * afterWrite hook + audit row inside one withWriteScope. Caller
- * is responsible for opening `db`, optionally wrapping in a larger BEGIN/
- * COMMIT (e.g. supersede's BEGIN IMMEDIATE), closing `db`, AND calling
- * `writeEntryMirrors` after the larger tx commits — mirrors must run
- * post-commit so a rolled-back tx never leaves orphan markdown.
- *
- * Audit-order note: the audit row is emitted INSIDE the write scope, so audit
- * commits atomically with the row INSERT. A subsequent mirror failure cannot
- * leave a recorded audit entry without its corresponding DB row. This is a
- * documented hardening over the prior writeEntry-as-monolith ordering.
- */
+/** DB-only write path: upsert, afterWrite hook and audit row inside one withWriteScope; the caller owns `db` and must call `writeEntryMirrors` after any
+ * outer tx commits, so a rolled-back tx never leaves orphan markdown. The audit row commits atomically with the INSERT. */
 export function writeEntryDbOnly(db, entry, opts) {
     // Inside a caller's transaction (e.g. supersede's BEGIN IMMEDIATE) the scope is a SAVEPOINT,
     // so a throw here rolls back only this write and leaves the outer open.