hippo-memory 1.59.0 → 1.61.0

package/dist/store/delete-and-batch.js

@@ -0,0 +1,310 @@
+import { AUTO_DELETABLE_SQL } from '../memory.js';
+import { openHippoDb, closeHippoDb } from '../db.js';
+import { checkRejectionGuard, RejectedValueError } from '../rejection.js';
+import { markSummaryDirtyInTx } from '../summary-dirty.js';
+import { insertDormantRow } from '../dormant.js';
+import { log } from '../log.js';
+import { MEMORY_SELECT_COLUMNS, rowToEntry } from './rows.js';
+import { audit } from './audit-event.js';
+import { deleteFtsRow, stampOriginProject, upsertEntryRow } from './entry-row.js';
+import { purgeMirrorBestEffort, mirrorBestEffort, writeMarkdownMirror } from './mirrors.js';
+import { openStore } from './open.js';
+/** Tables whose rows keep a first-class object's backing memory in `memory_id` (ON DELETE SET NULL); tests/dormant-memories.test.ts pins it to the schema. */
+export const MEMORY_BACKED_TABLES = ['predictions', 'decisions', 'incidents', 'processes', 'policies', 'skills', 'project_briefs', 'customer_notes'];
+/** Deleting a memory that backs an object nulls the object's link, and no restore can repair it, so no automatic pass may. */
+const AUTOMATIC_DELETE_SQL = `${AUTO_DELETABLE_SQL}${MEMORY_BACKED_TABLES.map((t) => ` AND NOT EXISTS (SELECT 1 FROM ${t} WHERE ${t}.memory_id = memories.id)`).join('')}`;
+/** Ids of memories that back a first-class object, for passes that plan deletes before making them. A table missing from an older schema is skipped. */
+export function memoriesBackingObjects(hippoRoot) {
+    const ids = new Set();
+    const db = openHippoDb(hippoRoot);
+    try {
+        for (const table of MEMORY_BACKED_TABLES) {
+            try {
+                // SAFETY: SELECT of one nullable TEXT column, filtered to non-null.
+                const rows = db.prepare(`SELECT memory_id FROM ${table} WHERE memory_id IS NOT NULL`).all();
+                for (const r of rows)
+                    ids.add(r.memory_id);
+            }
+            catch (err) {
+                // A missing table is an older schema; any other error could hide a backing memory, so the caller stops.
+                if (!(err instanceof Error && err.message.includes('no such table')))
+                    throw err;
+            }
+        }
+    }
+    finally {
+        closeHippoDb(db);
+    }
+    return ids;
+}
+/**
+ * AT1 (plan §4, round-2 fix, designed from source): db-scoped delete core.
+ * `deleteEntry` used to open+close its OWN connection, which meant it could
+ * never compose inside a caller's transaction (unlike writeEntry/
+ * writeEntryDbOnly, which already split this way). Split identically: row-
+ * meta SELECT, `DELETE FROM memories`, FTS delete, `forget` audit, DAG
+ * dirty-mark. NO filesystem I/O — the caller's own transaction may still be
+ * rolled back, and mirror writes must only happen post-commit.
+ *
+ * `opts.suppressForgetAudit` (default false, off): two AT1 callers set this
+ * so a removed non-raw row does NOT ALSO emit a `forget` row, because each
+ * already writes its own aggregate audit trail — `src/reject-flow.ts`'s
+ * `rejectValue` (single `reject_value` row covering every same-digest row
+ * removed) and `resolveConflict` (`conflict_resolve` row per resolution).
+ * Default keeps `deleteEntry` byte-identical to its pre-split behavior.
+ *
+ * Returns `{tenantId, dagParentId}` for the removed row, or `null` if no row with `id`
+ * existed or `automatic` refused it (pinned, raw, kept for good or backing an object at DELETE time, so a late pin wins).
+ */
+export function deleteEntryCore(db, id, opts) {
+    // SAFETY: row's shape matches the three columns named in the SELECT above.
+    const row = db
+        .prepare(`SELECT id, tenant_id, dag_parent_id FROM memories WHERE id = ?`)
+        .get(id);
+    if (!row?.id)
+        return null;
+    const guard = opts?.automatic ? ` AND ${AUTOMATIC_DELETE_SQL}` : '';
+    if (Number(db.prepare(`DELETE FROM memories WHERE id = ?${guard}`).run(id).changes ?? 0) === 0)
+        return null;
+    deleteFtsRow(db, id);
+    if (!opts?.suppressForgetAudit) {
+        audit(db, 'forget', id, opts?.reason ? { reason: opts.reason } : undefined, opts?.actor ?? 'cli', row.tenant_id);
+    }
+    // v0.30 / E2 — DAG live-coupling: forget of a child under a level-2
+    // summary marks parent dirty. Non-atomic with the DELETE (no SAVEPOINT
+    // wrapper here, same as pre-split deleteEntry); markSummaryDirtyInTx is
+    // idempotent so any future child mutation re-marks parent if this fails.
+    // Acceptable degradation, mirrors the pre-split audit best-effort posture.
+    if (row.dag_parent_id) {
+        markSummaryDirtyInTx(db, row.dag_parent_id, row.tenant_id ?? 'default', opts?.actor ?? 'cli');
+    }
+    return { tenantId: row.tenant_id ?? 'default', dagParentId: row.dag_parent_id ?? null };
+}
+/**
+ * Delete an entry from SQLite and mirrors.
+ *
+ * `opts.actor` defaults to 'cli'. The api.* layer threads `ctx.actor` so HTTP
+ * callers land with `api_key:<key_id>` in the audit log without a duplicate
+ * emit from the api wrapper.
+ *
+ * Thin wrapper over `deleteEntryCore` (open → core → mirrors → close);
+ * behavior is byte-identical to the pre-split implementation for every
+ * existing caller.
+ */
+export function deleteEntry(hippoRoot, id, opts) {
+    const db = openStore(hippoRoot);
+    try {
+        db.exec('BEGIN IMMEDIATE');
+        let result;
+        try {
+            result = deleteEntryCore(db, id, opts);
+            db.exec('COMMIT');
+        }
+        catch (err) {
+            if (db.isTransaction !== false)
+                db.exec('ROLLBACK');
+            throw err;
+        }
+        if (!result)
+            return false;
+        purgeMirrorBestEffort(hippoRoot, id, false, 'deleteEntry');
+        return true;
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+// The child fields a level-2/3 summary is built from (loadChildrenOfSummary, generateDagSummary).
+const SUMMARY_INPUTS = ['content', 'created', 'dag_parent_id', 'kind'];
+function mergeOwnChanges(base, ours, live) {
+    const row = { ...live };
+    const loaded = new Map(Object.entries(base));
+    for (const [key, value] of Object.entries(ours)) {
+        if (JSON.stringify(value) !== JSON.stringify(loaded.get(key)))
+            Object.assign(row, { [key]: value });
+    }
+    return row;
+}
+/** Consolidation's flush, one transaction. With `snapshot` (rows as the caller loaded them), a write keeps only
+ *  the fields the caller changed, takes the rest from the live row, and never resurrects a row that is gone.
+ *
+ *  `dormant` (src/dormant.ts): each move's snapshot is inserted into `dormant_memories` and its `memories` row
+ *  leaves exactly like a delete (FTS row, DAG parent dirty-mark, mirrors), in the same transaction, so a memory
+ *  is never in both places or in neither. Deletes and moves both skip rows that are no longer auto-deletable
+ *  (pinned, raw, kept for good or backing an object since the caller decided). Returns the ids that left `memories`, deleted or moved. */
+export function batchWriteAndDelete(hippoRoot, toWrite, toDeleteIds, opts) {
+    const dormantMoves = opts?.dormant ?? [];
+    if (toWrite.length === 0 && toDeleteIds.length === 0 && dormantMoves.length === 0)
+        return [];
+    const db = openStore(hippoRoot);
+    try {
+        // BEGIN IMMEDIATE (codex delta-review P2): the AT1 tombstone probes below
+        // READ before the first write. Under a deferred BEGIN, that read pins a
+        // WAL snapshot; a concurrent writer (e.g. `hippo reject`) committing
+        // between probe and first upsert would make the later write-lock upgrade
+        // fail with SQLITE_BUSY and roll back the ENTIRE batch — the exact race
+        // the probe exists to contain. Taking the write lock up front serializes
+        // the probe and the writes on one consistent snapshot.
+        db.exec('BEGIN IMMEDIATE');
+        // v0.30 / E2 — DAG live-coupling: BEFORE deletes, snapshot dag_parent_id
+        // for every doomed row so we can mark parents dirty post-COMMIT. Done
+        // inside the same BEGIN so the SELECT sees pre-delete state.
+        // independent-review-critic R1 HIGH: consolidate.ts/sleep flushes through
+        // this path every cycle; without these hooks parents NEVER get marked
+        // dirty for the dominant mutation source (decay, merge, garbage-collect).
+        const dirty = { parents: new Set(), tenantById: new Map() };
+        const deletableIds = [];
+        if (toDeleteIds.length > 0) {
+            // A row pinned after the caller decided to delete it survives.
+            const placeholders = toDeleteIds.map(() => '?').join(',');
+            for (const row of selectAutoDeletableRows(db, placeholders, toDeleteIds, dirty))
+                deletableIds.push(row.id);
+        }
+        // v39: batch writers bypass writeEntry, so stamp store-derived origins here too (a NULL origin hides new
+        // memories from ambient context). A row queued twice keeps only its last version, the one the merge compares.
+        const stampedWrites = [...new Map(toWrite.map((e) => [e.id, stampOriginProject(hippoRoot, e)])).values()];
+        const { written, batchRejectedSkips } = applyBatchWrites(db, stampedWrites, opts?.snapshot, dirty);
+        const removedIds = moveDormantAndDelete(db, dormantMoves, deletableIds, dirty);
+        // Fire dirty-mark for every collected parent INSIDE the BEGIN, so the
+        // dirty flag commits atomically with the writes + deletes.
+        for (const parentId of dirty.parents) {
+            markSummaryDirtyInTx(db, parentId, dirty.tenantById.get(parentId) ?? 'default', 'batch');
+        }
+        db.exec('COMMIT');
+        if (batchRejectedSkips > 0) {
+            log.warn(`batchWriteAndDelete: skipped ${batchRejectedSkips} write(s) whose content matches a rejected value (tombstone hit during the batch transaction)`);
+        }
+        // Sync mirrors once after all DB writes. Entries skipped above were
+        // never inserted — writing their markdown mirror would resurrect the
+        // exact content the skip just kept out of the DB.
+        mirrorBestEffort('markdown mirrors', () => {
+            for (const entry of written)
+                writeMarkdownMirror(hippoRoot, entry);
+        });
+        for (const id of removedIds)
+            purgeMirrorBestEffort(hippoRoot, id, false, 'batchWriteAndDelete');
+        return removedIds;
+    }
+    catch (error) {
+        try {
+            db.exec('ROLLBACK');
+        }
+        catch { /* ignore */ }
+        throw error;
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+/** Moves eligible dormant rows out, deletes them with the doomed rows, and returns every removed id. */
+function moveDormantAndDelete(db, dormantMoves, deletableIds, dirty) {
+    // Dormant moves: same eligibility and DAG bookkeeping as deletes.
+    const movable = [];
+    if (dormantMoves.length > 0) {
+        const byId = new Map(dormantMoves.map((m) => [m.entry.id, m]));
+        const placeholders = dormantMoves.map(() => '?').join(',');
+        for (const row of selectAutoDeletableRows(db, placeholders, [...byId.keys()], dirty))
+            movable.push(byId.get(row.id));
+    }
+    for (const move of movable) {
+        insertDormantRow(db, move);
+    }
+    const removedIds = [...deletableIds, ...movable.map((m) => m.entry.id)];
+    for (const id of removedIds) {
+        db.prepare('DELETE FROM memories WHERE id = ?').run(id);
+        deleteFtsRow(db, id);
+    }
+    return removedIds;
+}
+/** The still auto-deletable rows among `ids`, recording each one's DAG parent as dirty. */
+function selectAutoDeletableRows(db, placeholders, ids, dirty) {
+    // SAFETY: rows' shape matches the three columns named in the SELECT.
+    const rows = db.prepare(`SELECT id, dag_parent_id, tenant_id FROM memories WHERE id IN (${placeholders}) AND ${AUTOMATIC_DELETE_SQL}`).all(...ids);
+    for (const row of rows) {
+        if (row.dag_parent_id) {
+            dirty.parents.add(row.dag_parent_id);
+            dirty.tenantById.set(row.dag_parent_id, row.tenant_id ?? 'default');
+        }
+    }
+    return rows;
+}
+function applyBatchWrites(db, stampedWrites, snapshot, dirty) {
+    // AT1 P1 fix (codex, batch-transaction rejection race): the producer-side
+    // check (e.g. consolidate.ts's merge pass) runs BEFORE this transaction,
+    // on a different connection. A `hippo reject X` that commits in that
+    // window is invisible to it — a queued same-id write of X already
+    // sitting in `toWrite` (decay/replay re-persist, or a merge built before
+    // the reject) would silently re-INSERT the just-rejected row via the
+    // blind bypass. Fix: one indexed point probe per batch entry, on THIS
+    // connection, INSIDE this transaction — closes the race regardless of
+    // which write class hits it. N is small per sleep, so the extra query
+    // per entry is cheap.
+    //
+    // Skip, don't throw: the batch must still complete for every OTHER
+    // entry. Skipping is correct for every write class here — a merge
+    // summary skip just means that rollup is absent this cycle (its source
+    // facts stay merely demoted, recoverable next sleep); a skipped
+    // demotion/replay re-persist of a rejected-removed row means it stays
+    // gone, which is the entire point of the tombstone.
+    let batchRejectedSkips = 0;
+    const written = [];
+    const readLiveRow = db.prepare(`SELECT ${MEMORY_SELECT_COLUMNS} FROM memories WHERE id = ?`);
+    for (const entry of stampedWrites) {
+        const base = snapshot?.get(entry.id);
+        // SAFETY: MEMORY_SELECT_COLUMNS is the MemoryRow shape rowToEntry reads.
+        const liveRow = readLiveRow.get(entry.id);
+        const live = liveRow ? rowToEntry(liveRow) : undefined;
+        const row = base && live ? mergeOwnChanges(base, entry, live) : entry;
+        if (isRejectedBatchWrite(db, row)) {
+            batchRejectedSkips++;
+            continue;
+        }
+        if (base && !live)
+            continue;
+        written.push(row);
+        // AT1 (plan §3, corrected): bypass the rejection guard here.
+        // Consolidation merges are DETERMINISTIC CONCATENATION (mergeContents,
+        // consolidate.ts:736-751) of already-guarded leaf facts, not an LLM
+        // paraphrase — refusing mid-batch would abort the whole consolidation
+        // transaction. The bypass is safe because consolidate.ts's merge pass
+        // now checks the merged content's rejection digest against the
+        // tenant's tombstones BEFORE ever pushing a merge into pendingWrites,
+        // skipping that merge entirely on a hit, AND because the point-probe
+        // immediately above closes the race window between that producer
+        // check and this COMMIT. The guard itself still belongs on leaf
+        // inserts, which write through writeEntry / writeEntryDbOnly and stay
+        // guarded (bypassRejectionGuard defaults false).
+        upsertEntryRow(db, row, true);
+        // Hook for writes: a new child, or a change to what its summary reads, marks the parent dirty; decay alone does not.
+        if (row.dag_parent_id && (!live || SUMMARY_INPUTS.some((k) => row[k] !== live[k]))) {
+            dirty.parents.add(row.dag_parent_id);
+            dirty.tenantById.set(row.dag_parent_id, row.tenantId);
+        }
+    }
+    return { written, batchRejectedSkips };
+}
+/** True, after auditing the refusal, when the write would introduce a rejected value. */
+function isRejectedBatchWrite(db, row) {
+    const entryTenantId = row.tenantId ?? 'default';
+    // Codex delta-review P2 fix: reuse checkRejectionGuard rather than a
+    // bare tombstone probe — the guard's content-INTRODUCTION
+    // classification must apply here too. A tombstone can legitimately
+    // coexist with a live same-content row (resolveConflict deliberately
+    // excludes keepId from its sweep; unreject-then-re-reject windows), and
+    // an unconditional skip would starve that row of decay/replay metadata
+    // updates forever. The guard throws only when the write is new-row or
+    // changes content TO the rejected value; unchanged same-id re-persists
+    // pass through, exactly as on the writeEntry path.
+    try {
+        checkRejectionGuard(db, entryTenantId, row.id, row.content);
+    }
+    catch (err) {
+        if (err instanceof RejectedValueError) {
+            audit(db, 'reject_refusal', row.id, { digest: err.digest, reason: err.reason }, 'sleep-batch', entryTenantId);
+            return true;
+        }
+        throw err;
+    }
+    return false;
+}
+//# sourceMappingURL=delete-and-batch.js.map

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

@@ -0,0 +1,92 @@
+import type { MemoryEntry } from '../memory.js';
+import { type DatabaseSyncLike } from '../db.js';
+/**
+ * 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.
+ */
+export declare function readEntry(hippoRoot: string, id: string, tenantId?: string): MemoryEntry | null;
+/**
+ * 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 (docs/plans/2026-05-05-dag-recall.md Task 1.5)
+ * to fetch parent summaries for a set of overflowed leaves.
+ */
+export declare function loadEntriesByIds(hippoRoot: string, ids: readonly string[], tenantId?: string): MemoryEntry[];
+/**
+ * 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 (v1.6.2 codex fix): when `cap` is provided, the NEWEST
+ * `cap` rows are loaded — `ORDER BY created DESC LIMIT cap` server-side,
+ * reversed to oldest-first client-side. Pre-v1.6.2 ordered ASC + LIMIT,
+ * which silently dropped the newest rows and broke fresh-tail in assemble.
+ *
+ * Returns `[]` for an empty sessionId. Final order: `created ASC, id ASC`.
+ */
+export declare function loadSessionRawMemories(hippoRoot: string, sessionId: string, tenantId?: string, cap?: number): MemoryEntry[];
+/**
+ * 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.
+ *
+ * v1.6.3 codex P1 / senior P0: an earlier draft of this helper ran an
+ * unscoped COUNT, which let a no-scope caller infer the existence of
+ * private rows by comparing `totalRaw` against `items.length`. This
+ * version SQL-encodes the same default-deny rule `passesScopeFilterForRecall`
+ * applies in TS:
+ *   - explicit scope passed: exact-match
+ *   - no scope: rows where scope IS NULL, or scope is NOT a `<source>:private:*`
+ *     pattern AND not the `unknown:legacy` quarantine bucket.
+ *
+ * `tenantId` is optional for back-compat. Pass `undefined` only when
+ * intentionally counting cross-tenant; `assemble()` passes `ctx.tenantId`.
+ */
+export declare function countSessionRawMemories(hippoRoot: string, sessionId: string, tenantId?: string, scope?: string): number;
+/**
+ * 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."
+ *
+ * v1.6.2 codex review fix: pre-v1.6.2 was tenant-wide only. With multiple
+ * concurrent sessions in a tenant, fresh-tail recall surfaced unrelated
+ * rows from other sessions and stamped them `isFreshTail=true`. Callers
+ * that want session-scoped fresh-tail now pass `sessionId`. The
+ * tenant-wide form (no sessionId) still exists for "anything new across
+ * the whole tenant" — pass undefined to opt in.
+ *
+ * Bounded count cap at 200 — beyond that the caller should filter via
+ * tags/scope rather than time-windowed recall.
+ *
+ * Deprecation note (v1.6.5) — the **tenant-wide call shape** (omitting
+ * `sessionId`) is rarely the right shape for "what did I just see in this
+ * conversation". `api.recall` enforces session scoping when
+ * `HIPPO_REQUIRE_SESSION_SCOPED_FRESH_TAIL=1` is set, throwing
+ * `RecallContractError` instead. Tenant-wide remains the back-compat default
+ * but is discouraged for new callers. Passing `sessionId` is fully supported
+ * and recommended; this function is NOT deprecated as a whole.
+ */
+export declare function loadFreshRawMemories(hippoRoot: string, count: number, tenantId?: string, sessionId?: string): MemoryEntry[];
+/**
+ * Direct DAG children of a parent summary. Tenant scoped. Returns only rows
+ * whose `dag_parent_id` matches `parentId`; does NOT walk recursively.
+ * Used by `drillDown` (Task 3).
+ */
+export declare function loadChildrenOf(hippoRoot: string, parentId: string, tenantId?: string): MemoryEntry[];
+/**
+ * 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.
+ */
+export declare function loadAllEntries(hippoRoot: string, tenantId?: string): MemoryEntry[];
+/** Every memory row on an open connection, so a caller can read inside its own transaction. */
+export declare function selectAllEntries(db: DatabaseSyncLike, tenantId?: string): MemoryEntry[];
+/** Live rows whose source starts with `prefix`, on the caller's handle; LIKE folds case, so the prefix is checked again exactly. */
+export declare function selectLiveEntriesBySourcePrefix(db: DatabaseSyncLike, tenantId: string, prefix: string): MemoryEntry[];
+export declare function loadContentsWithTag(hippoRoot: string, tenantId: string, tag: string): string[];
+//# sourceMappingURL=entry-reads.d.ts.map

package/dist/store/entry-reads.js

@@ -0,0 +1,255 @@
+import { closeHippoDb } from '../db.js';
+import { MEMORY_SELECT_COLUMNS, rowToEntry, parseJsonArray } from './rows.js';
+import { openStore } from './open.js';
+/**
+ * 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.
+ */
+export function readEntry(hippoRoot, id, tenantId) {
+    const db = openStore(hippoRoot);
+    try {
+        // 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);
+    }
+}
+/**
+ * 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 (docs/plans/2026-05-05-dag-recall.md Task 1.5)
+ * to fetch parent summaries for a set of overflowed leaves.
+ */
+export function loadEntriesByIds(hippoRoot, ids, tenantId) {
+    if (ids.length === 0)
+        return [];
+    const capped = ids.slice(0, 500);
+    const db = openStore(hippoRoot);
+    try {
+        const placeholders = capped.map(() => '?').join(',');
+        // T2: no ORDER BY meant row order followed SQLite's IN(...) scan order
+        // (undefined w.r.t. the caller's `ids` order). created ASC, id ASC
+        // makes it deterministic.
+        // 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_id = ? 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);
+    }
+}
+/**
+ * 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 (v1.6.2 codex fix): when `cap` is provided, the NEWEST
+ * `cap` rows are loaded — `ORDER BY created DESC LIMIT cap` server-side,
+ * reversed to oldest-first client-side. Pre-v1.6.2 ordered ASC + LIMIT,
+ * which silently dropped the newest rows and broke fresh-tail in assemble.
+ *
+ * Returns `[]` for an empty sessionId. Final order: `created ASC, id ASC`.
+ */
+export function loadSessionRawMemories(hippoRoot, sessionId, tenantId, cap) {
+    if (!sessionId)
+        return [];
+    const db = openStore(hippoRoot);
+    try {
+        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);
+        if (tenantId !== undefined) {
+            sql += ' AND tenant_id = ?';
+            params.push(tenantId);
+        }
+        if (cap !== undefined && cap > 0) {
+            sql += ' ORDER BY created DESC, id DESC LIMIT ?';
+            params.push(cap);
+            // SAFETY: sql starts from MEMORY_SELECT_COLUMNS, matching MemoryRow.
+            const rows = db.prepare(sql).all(...params);
+            return rows.reverse().map(rowToEntry);
+        }
+        sql += ' ORDER BY created ASC, id ASC';
+        // SAFETY: sql starts from MEMORY_SELECT_COLUMNS, matching MemoryRow.
+        const rows = db.prepare(sql).all(...params);
+        return rows.map(rowToEntry);
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+/**
+ * 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.
+ *
+ * v1.6.3 codex P1 / senior P0: an earlier draft of this helper ran an
+ * unscoped COUNT, which let a no-scope caller infer the existence of
+ * private rows by comparing `totalRaw` against `items.length`. This
+ * version SQL-encodes the same default-deny rule `passesScopeFilterForRecall`
+ * applies in TS:
+ *   - explicit scope passed: exact-match
+ *   - no scope: rows where scope IS NULL, or scope is NOT a `<source>:private:*`
+ *     pattern AND not the `unknown:legacy` quarantine bucket.
+ *
+ * `tenantId` is optional for back-compat. Pass `undefined` only when
+ * intentionally counting cross-tenant; `assemble()` passes `ctx.tenantId`.
+ */
+export function countSessionRawMemories(hippoRoot, sessionId, tenantId, scope) {
+    if (!sessionId)
+        return 0;
+    const db = openStore(hippoRoot);
+    try {
+        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);
+        if (tenantId !== undefined) {
+            sql += ' AND tenant_id = ?';
+            params.push(tenantId);
+        }
+        if (scope !== undefined && scope !== '') {
+            sql += ' AND scope = ?';
+            params.push(scope);
+        }
+        else {
+            // SQL-ify the TS default-deny: scope IS NULL OR (NOT LIKE '%:private:%'
+            // AND != 'unknown:legacy'). Mirrors api.passesScopeFilterForRecall.
+            sql += ` AND (scope IS NULL OR (scope NOT LIKE '%:private:%' AND scope != 'unknown:legacy'))`;
+        }
+        // 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);
+    }
+}
+/**
+ * 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."
+ *
+ * v1.6.2 codex review fix: pre-v1.6.2 was tenant-wide only. With multiple
+ * concurrent sessions in a tenant, fresh-tail recall surfaced unrelated
+ * rows from other sessions and stamped them `isFreshTail=true`. Callers
+ * that want session-scoped fresh-tail now pass `sessionId`. The
+ * tenant-wide form (no sessionId) still exists for "anything new across
+ * the whole tenant" — pass undefined to opt in.
+ *
+ * Bounded count cap at 200 — beyond that the caller should filter via
+ * tags/scope rather than time-windowed recall.
+ *
+ * Deprecation note (v1.6.5) — the **tenant-wide call shape** (omitting
+ * `sessionId`) is rarely the right shape for "what did I just see in this
+ * conversation". `api.recall` enforces session scoping when
+ * `HIPPO_REQUIRE_SESSION_SCOPED_FRESH_TAIL=1` is set, throwing
+ * `RecallContractError` instead. Tenant-wide remains the back-compat default
+ * but is discouraged for new callers. Passing `sessionId` is fully supported
+ * and recommended; this function is NOT deprecated as a whole.
+ */
+export function loadFreshRawMemories(hippoRoot, count, tenantId, sessionId) {
+    if (count <= 0)
+        return [];
+    const capped = Math.min(count, 200);
+    const db = openStore(hippoRoot);
+    try {
+        const params = [];
+        let sql = `SELECT ${MEMORY_SELECT_COLUMNS} FROM memories WHERE kind = 'raw' AND superseded_by IS NULL`;
+        if (tenantId !== undefined) {
+            sql += ' AND tenant_id = ?';
+            params.push(tenantId);
+        }
+        if (sessionId !== undefined && sessionId !== '') {
+            sql += ' AND source_session_id = ?';
+            params.push(sessionId);
+        }
+        // T2: tie tail keeps the LIMIT window keyed on `created` while making
+        // same-`created` rows deterministic. `content` before `id` (codex
+        // review): ids are random UUIDs, so an id-only tail would pick WHICH
+        // same-created rows make the window per-instance; content is
+        // cross-ingest-stable.
+        sql += ' ORDER BY created DESC, content ASC, id ASC LIMIT ?';
+        params.push(capped);
+        // SAFETY: sql starts from MEMORY_SELECT_COLUMNS, matching MemoryRow.
+        const rows = db.prepare(sql).all(...params);
+        return rows.map(rowToEntry);
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+/**
+ * Direct DAG children of a parent summary. Tenant scoped. Returns only rows
+ * whose `dag_parent_id` matches `parentId`; does NOT walk recursively.
+ * Used by `drillDown` (Task 3).
+ */
+export function loadChildrenOf(hippoRoot, parentId, tenantId) {
+    const db = openStore(hippoRoot);
+    try {
+        // 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 dag_parent_id = ? AND tenant_id = ? ORDER BY created ASC, id ASC`).all(parentId, tenantId)
+            : db.prepare(`SELECT ${MEMORY_SELECT_COLUMNS} FROM memories WHERE dag_parent_id = ? ORDER BY created ASC, id ASC`).all(parentId);
+        return rows.map(rowToEntry);
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+/**
+ * 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.
+ */
+export function loadAllEntries(hippoRoot, tenantId) {
+    const db = openStore(hippoRoot);
+    try {
+        return selectAllEntries(db, tenantId);
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+/** Every memory row on an open connection, so a caller can read inside its own transaction. */
+export function selectAllEntries(db, tenantId) {
+    // 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 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);
+}
+/** 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) {
+    // SAFETY: selects exactly MEMORY_SELECT_COLUMNS, matching MemoryRow's field set.
+    const rows = db.prepare(`SELECT ${MEMORY_SELECT_COLUMNS} FROM memories WHERE tenant_id = ? AND superseded_by IS NULL AND source LIKE ? ESCAPE '\\'`).all(tenantId, `${prefix.replace(/[%_\\]/g, '\\$&')}%`);
+    return rows.map(rowToEntry).filter((entry) => entry.source.startsWith(prefix));
+}
+// Content of every tenant row tagged `tag`, without reading the rest of the store.
+// `instr` is a substring prefilter over the raw JSON; `includes` below re-checks exactly.
+export function loadContentsWithTag(hippoRoot, tenantId, tag) {
+    const db = openStore(hippoRoot);
+    try {
+        /** 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`).all(tenantId, JSON.stringify(tag));
+        return rows.filter((r) => parseJsonArray(r.tags_json).includes(tag)).map((r) => r.content);
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+//# sourceMappingURL=entry-reads.js.map