hippo-memory 1.68.0 → 1.69.0

package/dist/server-detect.js

@@ -1,5 +1,6 @@
 import { existsSync, readFileSync, writeFileSync, unlinkSync, renameSync } from 'node:fs';
 import { join } from 'node:path';
+import { envHealthProbeMs } from './env.js';
 // Pidfile sits directly inside hippoRoot. `hippoRoot` is the `.hippo`
 // directory itself (the same convention used by api.ts / store.ts /
 // openHippoDb), so this resolves to `${hippoRoot}/server.pid`.
@@ -8,7 +9,7 @@ const PIDFILE = 'server.pid';
  * How long detectServer waits for the `/health` liveness probe before
  * treating the pidfile as stale. Short by design: the probe only fires on
  * the rare path where a pidfile exists and its pid is live, and the target
- * is always loopback, so a healthy server answers well within this bound.
+ * is always loopback, so a healthy server answers well within this bound. HIPPO_HEALTH_PROBE_MS overrides it.
  */
 const HEALTH_PROBE_TIMEOUT_MS = 300;
 /**
@@ -84,7 +85,7 @@ async function healthMatchesPidfile(hippoRoot, info) {
     // returns null WITHOUT unlinking. The pidfile survives for the next probe.
     try {
         const res = await fetch(`${info.url}/health`, {
-            signal: AbortSignal.timeout(HEALTH_PROBE_TIMEOUT_MS),
+            signal: AbortSignal.timeout(envHealthProbeMs() ?? HEALTH_PROBE_TIMEOUT_MS),
         });
         if (!res.ok || !res.body) {
             removePidfile(hippoRoot);

package/dist/server.d.ts

@@ -11,7 +11,11 @@ export { HttpError } from './http-util.js';
 export { promptHookContext, type CallerProject } from './prompt-hook.js';
 export type { JsonValue } from './json.js';
 export { captureSessionTexts, type SessionCaptureRequest, type SessionCaptureResult } from './capture/session-texts.js';
-export { hasGroup, sqliteStore, type HippoStore, type KeyAudit, type KeyListQuery, type KeyMint, type KeyRevoke, type KeyWrites, type RecallSearchArgs, type RecallWrites, type SelfKeyMint, type StoreGroup, type StoreGroups, type VectorReads, type VectorBackfillQuery, type VectorRowWrite, type VectorWrite, type VectorWriteResult, type VectorWrites, } from './store-port.js';
+export { hasGroup, sqliteStore, type AmbientCandidateRequest, type ContextReads, type EntryRemoval, type EntryTarget, type EntryWrite, type EntryWrites, type HippoStore, type KeyAudit, type KeyListQuery, type KeyMint, type KeyRevoke, type KeyWrites, type OutcomeWrite, type RawArchive, type RecallSearchArgs, type RecallWrites, type SelfKeyMint, type StoreGroup, type StoreGroups, type SupersedeWrite, type VectorReads, type VectorBackfillQuery, type VectorRowWrite, type VectorWrite, type VectorWriteResult, type VectorWrites, } from './store-port.js';
+export { entryAfterOutcome } from './memory.js';
+export { rejectionDigest, RejectedValueError } from './rejection.js';
+export { ownScopeTouches } from './recall-scope.js';
+export { BadRequestError, ConflictError } from './api-errors.js';
 export type { HippoDbContext, StoreReply } from './api/types.js';
 export type { ApiKeyListItem, ApiKeyListRow, ApiKeyRecord, ListApiKeysOpts, NewApiKey } from './auth.js';
 export type { KeysetPosition } from './keyset.js';
@@ -25,6 +29,11 @@ export type { RecallTraceInput } from './recall-trace.js';
 export type { StrengthenOptions } from './store/entry-writes.js';
 export type { OriginFilter, RecallScopeFilter, VectorCandidateSpec } from './store/search-rows.js';
 export type { ContinuityKey } from './store/sessions.js';
+export type { SessionEvent, TaskSnapshot } from './store/rows.js';
+export type { SessionHandoff } from './handoff.js';
+export type { AmbientLoadResult, AmbientRecallRequest, ContextCandidateFilter, RecentOrigins } from './store/candidates.js';
+export type { AmbientStoreFilter } from './ambient-store.js';
+export type { AmbientTallies } from './ambient.js';
 export type { TokenUse } from './token-ledger.js';
 export type { EmbeddingIndexState } from './embeddings.js';
 export type { PhysicsParticle } from './physics.js';
@@ -32,6 +41,10 @@ export { StoreBusyError } from './db.js';
 export { decodeVector, EMBEDDING_MODEL_META_KEY, encodeVector, rankVectorRows, type VectorMatch, type VectorRow } from './vector-store.js';
 export { bufferToFloat32, float32ToBuffer } from './physics-state.js';
 export { replacesIndex } from './embeddings.js';
+export { passesScopeFilterForRecall, RECALL_DEFAULT_DENY_SCOPES } from './recall-scope.js';
+export { SECRET_TAGS } from './secret-detect.js';
+export { tallyAmbientEntries } from './ambient.js';
+export { ftsTermParts, rarestFtsQuery } from './prompt-recall.js';
 export { OTHER_STORE_MARKER, OtherStoreFolderError, withSqliteAllowed } from './db.js';
 export { authCreate, type AuthCreateOpts, type AuthCreateResult } from './api.js';
 export { isSharedStore } from './config.js';

package/dist/server.js

@@ -47,12 +47,22 @@ export { promptHookContext } from './prompt-hook.js';
 export { captureSessionTexts } from './capture/session-texts.js';
 // An add-on serves from another database by passing serve() its own HippoStore.
 export { hasGroup, sqliteStore, } from './store-port.js';
+// An add-on store's entry writes apply an outcome, guard tombstones and check reach exactly as hippo.db does.
+export { entryAfterOutcome } from './memory.js';
+export { rejectionDigest, RejectedValueError } from './rejection.js';
+export { ownScopeTouches } from './recall-scope.js';
+export { BadRequestError, ConflictError } from './api-errors.js';
 export { StoreBusyError } from './db.js';
 // An add-on store encodes, decodes and ranks vectors and particles with hippo.db's own code, and drops the index by its rule,
 // so both stores keep the same bytes and return the same ids in the same order.
 export { decodeVector, EMBEDDING_MODEL_META_KEY, encodeVector, rankVectorRows } from './vector-store.js';
 export { bufferToFloat32, float32ToBuffer } from './physics-state.js';
 export { replacesIndex } from './embeddings.js';
+// An add-on's ContextReads applies hippo.db's scope, secret, tally and rarest-term rules with the same code.
+export { passesScopeFilterForRecall, RECALL_DEFAULT_DENY_SCOPES } from './recall-scope.js';
+export { SECRET_TAGS } from './secret-detect.js';
+export { tallyAmbientEntries } from './ambient.js';
+export { ftsTermParts, rarestFtsQuery } from './prompt-recall.js';
 // store copy --db writes the marker and reads the old hippo.db under the waiver.
 export { OTHER_STORE_MARKER, OtherStoreFolderError, withSqliteAllowed } from './db.js';
 // An add-on's install step mints the first admin key into a store folder it names, which `hippo auth create` cannot reach.
@@ -98,17 +108,17 @@ const VERSION = PACKAGE_VERSION;
 const LOOPBACK_HOSTS = new Set(['127.0.0.1', '::1', 'localhost']);
 /** The /v1 routes in dispatch order; the first entry whose method and path match handles the request. */
 const V1_ROUTES = [
-    { method: 'POST', path: '/v1/memories', handler: handleCreateMemory },
+    { method: 'POST', path: '/v1/memories', storeReady: 'entryWrites', handler: handleCreateMemory },
     { method: 'GET', path: '/v1/graph', handler: handleGetGraph },
     { method: 'GET', path: '/v1/memories', storeReady: 'base', handler: handleRecallMemories },
     { method: 'GET', pattern: '/v1/sessions/:id/assemble', handler: handleAssembleSession },
     { method: 'GET', pattern: '/v1/recall/drill/:id', handler: handleDrillRecall },
-    { method: 'POST', pattern: '/v1/memories/:id/archive', handler: handleArchiveMemory },
-    { method: 'POST', pattern: '/v1/memories/:id/supersede', handler: handleSupersedeMemory },
+    { method: 'POST', pattern: '/v1/memories/:id/archive', storeReady: 'entryWrites', handler: handleArchiveMemory },
+    { method: 'POST', pattern: '/v1/memories/:id/supersede', storeReady: 'entryWrites', handler: handleSupersedeMemory },
     { method: 'POST', pattern: '/v1/memories/:id/promote', handler: handlePromoteMemory },
-    { method: 'DELETE', pattern: '/v1/memories/:id', handler: handleForgetMemory },
-    { method: 'POST', path: '/v1/outcome', handler: handleApplyOutcome },
-    { method: 'GET', path: '/v1/context', handler: handleGetContext },
+    { method: 'DELETE', pattern: '/v1/memories/:id', storeReady: 'entryWrites', handler: handleForgetMemory },
+    { method: 'POST', path: '/v1/outcome', storeReady: 'entryWrites', handler: handleApplyOutcome },
+    { method: 'GET', path: '/v1/context', storeReady: 'contextReads', handler: handleGetContext },
     { method: 'POST', path: '/v1/sleep', handler: handleSleep },
     { method: 'POST', path: '/v1/auth/keys', storeReady: 'keyWrites', handler: handleCreateAuthKey },
     { method: 'GET', path: '/v1/auth/keys', storeReady: 'keyWrites', handler: handleListAuthKeys },

package/dist/store/audit-event.d.ts

@@ -11,7 +11,7 @@ export declare function audit(db: ReturnType<typeof openHippoDb>, op: AuditOp, t
 /**
  * Refusal audit for the rejected-value guard. Written by the
  * transaction OWNER post-rollback — writeEntry's catch (no outer tx exists
- * there, so this lands in a fresh implicit transaction) and api.supersede's
+ * there, so this lands in a fresh implicit transaction) and commitSupersede's
  * catch (after its own ROLLBACK) — never inside a scope the caller's own
  * rollback could claw back. Best-effort `audit()` semantics: never throws.
  */

package/dist/store/audit-event.js

@@ -23,7 +23,7 @@ export function audit(db, op, targetId, metadata, actor = 'cli', tenantId) {
 /**
  * Refusal audit for the rejected-value guard. Written by the
  * transaction OWNER post-rollback — writeEntry's catch (no outer tx exists
- * there, so this lands in a fresh implicit transaction) and api.supersede's
+ * there, so this lands in a fresh implicit transaction) and commitSupersede's
  * catch (after its own ROLLBACK) — never inside a scope the caller's own
  * rollback could claw back. Best-effort `audit()` semantics: never throws.
  */

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

@@ -0,0 +1,9 @@
+import { type DatabaseSyncLike } from '../db.js';
+import type { EntryWrites, SupersedeWrite } from '../store-port.js';
+/** Each call on its own handle; mirrors and the forgotten counter follow the commit, so a rolled-back write leaves neither. */
+export declare function sqliteEntryWrites(hippoRoot: string): EntryWrites;
+/** Reach, the CAS on the old row, the successor's insert and the supersede row in one BEGIN IMMEDIATE transaction. Two racing supersedes: one CAS wins. */
+export declare function commitSupersede(db: DatabaseSyncLike, write: SupersedeWrite): void;
+/** A mirror left on disk would bring the archived row back on the next import; on failure the reaper retries, as mirror_cleaned_at stays NULL. */
+export declare function cleanArchivedMirrors(db: DatabaseSyncLike, hippoRoot: string, id: string): void;
+//# sourceMappingURL=entry-writes-group.d.ts.map

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

@@ -0,0 +1,157 @@
+// hippo.db's half of the EntryWrites store group: the queries remember, outcome, supersede, archive and forget run today.
+import { ConflictError, NotFoundError } from '../api-errors.js';
+import { appendAuditEvent } from '../audit.js';
+import { isSqliteBusy, withWriteScope } from '../db.js';
+import { log } from '../log.js';
+import { entryAfterOutcome } from '../memory.js';
+import { archiveRawMemory } from '../raw-archive.js';
+import { ownScopeTouches } from '../recall-scope.js';
+import { RejectedValueError } from '../rejection.js';
+import { markSummaryDirtyInTx } from '../summary-dirty.js';
+import { auditRejectionRefusal } from './audit-event.js';
+import { deleteEntryCore } from './delete-and-batch.js';
+import { selectEntriesByIds } from './entry-reads.js';
+import { stampOriginProject } from './entry-row.js';
+import { writeEntryDbOnly, writeEntryMirrors } from './entry-writes.js';
+import { updateStatsUnlessBusy } from './index-and-stats.js';
+import { purgeMirrorBestEffort, removeEntryMirrors } from './mirrors.js';
+import { onHandle, openStore } from './open.js';
+import { selectMemoryReach } from './tenant-lookup.js';
+/** Each call on its own handle; mirrors and the forgotten counter follow the commit, so a rolled-back write leaves neither. */
+export function sqliteEntryWrites(hippoRoot) {
+    return {
+        async writeEntry({ entry, actor }) {
+            const stamped = stampOriginProject(hippoRoot, entry);
+            onHandle(hippoRoot, (db) => writeInOwnTenant(db, stamped, actor), openStore);
+            writeEntryMirrors(hippoRoot, stamped);
+        },
+        async applyOutcome(outcome) {
+            const applied = onHandle(hippoRoot, (db) => applyOutcomeOn(db, outcome), openStore);
+            for (const entry of applied)
+                writeEntryMirrors(hippoRoot, entry);
+            return applied.map((entry) => entry.id);
+        },
+        async supersede(write) {
+            const successor = stampOriginProject(hippoRoot, write.successor);
+            onHandle(hippoRoot, (db) => commitSupersede(db, { ...write, successor }));
+            writeEntryMirrors(hippoRoot, successor);
+        },
+        async archiveRaw(archive) {
+            const archivedAt = onHandle(hippoRoot, (db) => {
+                const at = withWriteScope(db, 'archive_raw_in_reach', () => {
+                    assertInReach(db, archive, archive.id);
+                    return archiveRawMemory(db, archive.id, { reason: archive.reason, who: archive.actor });
+                });
+                cleanArchivedMirrors(db, hippoRoot, archive.id);
+                return at;
+            });
+            updateStatsUnlessBusy(hippoRoot, { forgotten: 1 }, `removed ${archive.id}`);
+            return archivedAt;
+        },
+        async forget(removal) {
+            onHandle(hippoRoot, (db) => withWriteScope(db, 'forget_in_reach', () => {
+                assertInReach(db, removal, removal.id);
+                if (!deleteEntryCore(db, removal.id, { actor: removal.actor }))
+                    throw notFound(removal.id);
+            }), openStore);
+            purgeMirrorBestEffort(hippoRoot, removal.id, false, 'deleteEntry');
+            updateStatsUnlessBusy(hippoRoot, { forgotten: 1 }, `removed ${removal.id}`);
+        },
+    };
+}
+function notFound(id) {
+    return new NotFoundError(`memory not found: ${id}`);
+}
+/** Another tenant's row, or another person's personal row, answers as missing, so a caller learns nothing about it. */
+function assertInReach(db, target, id) {
+    const reach = selectMemoryReach(db, id);
+    if (reach?.tenantId !== target.tenantId || !ownScopeTouches(target.ownScope, reach.scope))
+        throw notFound(id);
+}
+/** hippo.db's upsert would move the row into the writer's tenant, so a store write refuses an id another tenant holds. */
+function assertIdInTenant(db, entry) {
+    const holder = selectMemoryReach(db, entry.id)?.tenantId;
+    if (holder !== undefined && holder !== entry.tenantId)
+        throw new ConflictError(`Memory ${entry.id} belongs to another tenant`);
+}
+/** The refusal row lands after the rollback, in a fresh implicit transaction the aborted one cannot undo. */
+function writeInOwnTenant(db, entry, actor) {
+    try {
+        withWriteScope(db, 'write_entry_in_tenant', () => {
+            assertIdInTenant(db, entry);
+            writeEntryDbOnly(db, entry, { actor });
+        });
+    }
+    catch (err) {
+        if (err instanceof RejectedValueError)
+            auditRejectionRefusal(db, err, actor);
+        throw err;
+    }
+}
+/** The reads, rewrites and outcome rows share one BEGIN IMMEDIATE transaction, hippo.db's form of the port's row lock; the caller writes the mirrors after. */
+function applyOutcomeOn(db, outcome) {
+    return withWriteScope(db, 'apply_outcome', () => {
+        const live = selectEntriesByIds(db, outcome.ids, outcome.tenantId);
+        const applied = [];
+        for (const id of outcome.ids) {
+            const entry = live.get(id);
+            if (!entry || !ownScopeTouches(outcome.ownScope, entry.scope))
+                continue;
+            const updated = entryAfterOutcome(entry, outcome.good);
+            writeEntryDbOnly(db, updated, { actor: outcome.actor });
+            live.set(id, updated);
+            appendAuditEvent(db, { tenantId: outcome.tenantId, actor: outcome.actor, op: 'outcome', targetId: id, metadata: { good: outcome.good } });
+            applied.push(updated);
+        }
+        return applied;
+    });
+}
+/** Reach, the CAS on the old row, the successor's insert and the supersede row in one BEGIN IMMEDIATE transaction. Two racing supersedes: one CAS wins. */
+export function commitSupersede(db, write) {
+    const { tenantId, actor, oldId, successor } = write;
+    db.exec('BEGIN IMMEDIATE');
+    try {
+        assertInReach(db, write, oldId);
+        // SAFETY: RETURNING names one column, dag_parent_id; no row means another writer got there first.
+        const won = db.prepare('UPDATE memories SET superseded_by = ? WHERE id = ? AND tenant_id = ? AND superseded_by IS NULL RETURNING dag_parent_id')
+            .get(successor.id, oldId, tenantId);
+        if (!won)
+            throw new ConflictError(`Memory ${oldId} already superseded by another writer`);
+        // After the CAS, so a lost race marks no parent for rebuild.
+        if (won.dag_parent_id)
+            markSummaryDirtyInTx(db, won.dag_parent_id, tenantId, actor);
+        assertIdInTenant(db, successor);
+        writeEntryDbOnly(db, successor, { actor });
+        appendAuditEvent(db, { tenantId, actor, op: 'supersede', targetId: oldId, metadata: { newId: successor.id } });
+        db.exec('COMMIT');
+    }
+    catch (err) {
+        try {
+            db.exec('ROLLBACK');
+        }
+        catch { /* already rolled back */ }
+        // The refusal row lands after ROLLBACK, in a fresh implicit transaction the aborted one cannot undo.
+        if (err instanceof RejectedValueError)
+            auditRejectionRefusal(db, err, actor);
+        throw err;
+    }
+}
+/** A mirror left on disk would bring the archived row back on the next import; on failure the reaper retries, as mirror_cleaned_at stays NULL. */
+export function cleanArchivedMirrors(db, hippoRoot, id) {
+    try {
+        removeEntryMirrors(hippoRoot, id);
+    }
+    catch (mirrorErr) {
+        log.error(`archiveRaw: mirror cleanup failed for ${id} (will retry via reaper on next openHippoDb): ${mirrorErr instanceof Error ? mirrorErr.message : String(mirrorErr)}`);
+        return;
+    }
+    try {
+        db.prepare(`UPDATE raw_archive SET mirror_cleaned_at = ? WHERE memory_id = ?`).run(new Date().toISOString(), id);
+    }
+    catch (err) {
+        if (!isSqliteBusy(err))
+            throw err;
+        log.warnThenDebug('archive-mirror-stamp-busy', `archived ${id}; the store was busy, so the mirror reaper will re-check it on the next open`);
+    }
+}
+//# sourceMappingURL=entry-writes-group.js.map

package/dist/store/handoffs.d.ts

@@ -23,7 +23,10 @@ export declare function loadHandoffById(hippoRoot: string, tenantId: string, id:
 export declare function stampHandoffOutcome(hippoRoot: string, tenantId: string, sessionId: string, outcome: HandoffOutcome): number;
 /** Auto-write a handoff at session-end from the session's active snapshot, else from `derived`, its transcript state.
  * @param evidence best-effort git state; outcome comes from the newest session_complete event.
- * @returns null when neither source is the session's, a newer handoff covers the snapshot, or the session's latest handoff was not read off its transcript or already holds `derived`. */
-export declare function writeSessionEndHandoff(hippoRoot: string, tenantId: string, sessionId: string, evidence: HandoffEvidence | null, derived?: Pick<TaskSnapshot, 'task' | 'summary' | 'next_step'> | null, key?: ContinuityKey): SessionHandoff | null;
+ * @param options.inPlace rewrite an earlier transcript read instead of adding a revision, for a close that runs after every reply.
+ * @returns null when neither source is the session's, a newer handoff covers the snapshot, the session's latest handoff was not read off its transcript or already holds `derived`, or, in place, a handoff landed after the read. */
+export declare function writeSessionEndHandoff(hippoRoot: string, tenantId: string, sessionId: string, evidence: HandoffEvidence | null, derived?: Pick<TaskSnapshot, 'task' | 'summary' | 'next_step'> | null, key?: ContinuityKey, options?: {
+    inPlace?: boolean;
+}): SessionHandoff | null;
 export {};
 //# sourceMappingURL=handoffs.d.ts.map

package/dist/store/handoffs.js

@@ -128,10 +128,32 @@ export function stampHandoffOutcome(hippoRoot, tenantId, sessionId, outcome) {
         closeHippoDb(db);
     }
 }
+/** Rewrites the session's newest handoff when it is still a transcript read, in one statement so a handoff written meanwhile is never overwritten; null when none was rewritten. */
+function replaceTranscriptHandoff(hippoRoot, tenantId, handoff, key) {
+    const { conditions, params } = handoffConditions(tenantId, handoff.sessionId, {}, key);
+    const newest = `SELECT id FROM session_handoffs WHERE ${conditions.join(' AND ')} ORDER BY created_at DESC, id DESC LIMIT 1`;
+    const db = openStore(hippoRoot);
+    try {
+        const result = db.prepare(`
+      UPDATE session_handoffs SET repo_root = ?, task_id = ?, summary = ?, next_action = ?, artifacts_json = ?, scope = ?, created_at = ?,
+        constraints_json = ?, evidence_json = ?, outcome = ?, target_runtime = ?, card_id = ?
+      WHERE id = (${newest}) AND json_valid(evidence_json) AND json_extract(evidence_json, '$.derivedFrom') = 'transcript'
+    `).run(handoff.repoRoot ?? null, handoff.taskId ?? null, handoff.summary, handoff.nextAction ?? null, JSON.stringify(handoff.artifacts ?? []), handoff.scope ?? null, new Date().toISOString(), JSON.stringify(handoff.constraints ?? []), handoff.evidence ? JSON.stringify(handoff.evidence) : null, handoff.outcome ?? null, handoff.targetRuntime ?? null, handoff.cardId ?? null, ...params);
+        if (Number(result.changes ?? 0) === 0)
+            return null;
+        // SAFETY: row's shape matches HANDOFF_COLUMNS.
+        const row = db.prepare(`SELECT ${HANDOFF_COLUMNS} FROM session_handoffs WHERE id = (${newest})`).get(...params);
+        return row ? rowToSessionHandoff(row) : null;
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
 /** Auto-write a handoff at session-end from the session's active snapshot, else from `derived`, its transcript state.
  * @param evidence best-effort git state; outcome comes from the newest session_complete event.
- * @returns null when neither source is the session's, a newer handoff covers the snapshot, or the session's latest handoff was not read off its transcript or already holds `derived`. */
-export function writeSessionEndHandoff(hippoRoot, tenantId, sessionId, evidence, derived = null, key) {
+ * @param options.inPlace rewrite an earlier transcript read instead of adding a revision, for a close that runs after every reply.
+ * @returns null when neither source is the session's, a newer handoff covers the snapshot, the session's latest handoff was not read off its transcript or already holds `derived`, or, in place, a handoff landed after the read. */
+export function writeSessionEndHandoff(hippoRoot, tenantId, sessionId, evidence, derived = null, key, options = {}) {
     assertTenantId('writeSessionEndHandoff', tenantId);
     if (key)
         continuityStamp(key); // a partial key is a caller bug, so fail loud rather than write nothing
@@ -139,7 +161,10 @@ export function writeSessionEndHandoff(hippoRoot, tenantId, sessionId, evidence,
     const existing = loadLatestHandoff(hippoRoot, tenantId, sessionId, {}, key);
     let snapshot;
     let handoffEvidence = evidence;
-    if (active && active.session_id === sessionId) {
+    let fromTranscript = false;
+    // After every reply the transcript is newer than the last compaction's snapshot, which the open chat keeps for the next one.
+    const snapshotGivesWay = options.inPlace === true && derived !== null && active?.source === 'pre-compact';
+    if (active && active.session_id === sessionId && !snapshotGivesWay) {
         // Strict '>': a same-millisecond tie must not swallow the session's only write (test 6e).
         if (existing && existing.updatedAt > active.updated_at)
             return null;
@@ -154,13 +179,14 @@ export function writeSessionEndHandoff(hippoRoot, tenantId, sessionId, evidence,
             return null;
         snapshot = { ...derived, scope: null };
         handoffEvidence = { ...evidence, derivedFrom: 'transcript' };
+        fromTranscript = true;
     }
     const outcome = sessionOutcome(hippoRoot, tenantId, sessionId);
     // A same-task refresh carries forward envelope fields nobody cleared; a scope
     // mismatch must not leak private metadata into an unscoped envelope.
     const carryForward = existing != null && existing.taskId === snapshot.task
         && (existing.scope ?? null) === (snapshot.scope ?? null);
-    return saveSessionHandoff(hippoRoot, tenantId, {
+    const handoff = {
         version: 1,
         sessionId,
         repoRoot: carryForward ? existing.repoRoot : undefined,
@@ -174,7 +200,11 @@ export function writeSessionEndHandoff(hippoRoot, tenantId, sessionId, evidence,
         constraints: carryForward ? existing.constraints : undefined,
         targetRuntime: carryForward ? existing.targetRuntime : undefined,
         cardId: carryForward ? existing.cardId : undefined,
-    }, key);
+    };
+    // A miss means a handoff landed since the read, and a new transcript row would hide it.
+    if (fromTranscript && options.inPlace && existing)
+        return replaceTranscriptHandoff(hippoRoot, tenantId, handoff, key);
+    return saveSessionHandoff(hippoRoot, tenantId, handoff, key);
 }
 function sessionOutcome(hippoRoot, tenantId, sessionId) {
     const db = openHippoDb(hippoRoot);

package/dist/store/open.d.ts

@@ -9,6 +9,8 @@ export declare function initStore(hippoRoot: string): void;
 export declare function openStore(hippoRoot: string, opts?: {
     busyWaitMs?: number;
 }): DatabaseSyncLike;
+/** One call on a handle of its own, closed after; pass openStore where the call also sets up mirror folders and legacy rows. */
+export declare function onHandle<T>(hippoRoot: string, fn: (db: DatabaseSyncLike) => T, open?: (hippoRoot: string) => DatabaseSyncLike): T;
 /** `meta` key holding the default half-life base a store's memories are on (src/half-life-migration.ts). */
 export declare const HALF_LIFE_BASE_META_KEY = "default_half_life_base";
 /** `meta` key set once no memory of a decision, incident or other object sits on the old flat 90 days. */

package/dist/store/open.js

@@ -46,6 +46,16 @@ export function openStore(hippoRoot, opts) {
         throw error;
     }
 }
+/** One call on a handle of its own, closed after; pass openStore where the call also sets up mirror folders and legacy rows. */
+export function onHandle(hippoRoot, fn, open = openHippoDb) {
+    const db = open(hippoRoot);
+    try {
+        return fn(db);
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
 /** `meta` key holding the default half-life base a store's memories are on (src/half-life-migration.ts). */
 export const HALF_LIFE_BASE_META_KEY = 'default_half_life_base';
 /** `meta` key set once no memory of a decision, incident or other object sits on the old flat 90 days. */

package/dist/store/search-rows.js

@@ -2,7 +2,7 @@ import { envForceLikePath } from '../env.js';
 import { isFtsAvailable, closeHippoDb } from '../db.js';
 import { tokenize } from '../tokenize.js';
 import { isPersonalScope, scopeAdmitSql } from '../recall-scope.js';
-import { RAREST_TERM_COUNT, rarestPromptTerms } from '../prompt-recall.js';
+import { ftsTermParts, RAREST_TERM_COUNT, rarestFtsQuery } from '../prompt-recall.js';
 import { log } from '../log.js';
 import { originInSql } from '../project-identity.js';
 import { topVectorMatches } from '../vector-store.js';
@@ -210,9 +210,7 @@ export function pickRarestFtsQuery(db, terms, maxTerms = RAREST_TERM_COUNT) {
     if (!isFtsAvailable(db))
         return terms.slice(0, 32).join(' ');
     db.exec(`CREATE VIRTUAL TABLE IF NOT EXISTS temp.z1_rarest_vocab USING fts5vocab(main, 'memories_fts', 'row')`);
-    // unicode61 splits `journal_mode` into two vocab terms; a term's count is its rarest part's (an upper bound).
-    const partsOf = (t) => t.split(/[^\p{L}\p{N}]+/u).filter(Boolean);
-    const vocab = Array.from(new Set(terms.flatMap(partsOf)));
+    const vocab = Array.from(new Set(terms.flatMap(ftsTermParts)));
     if (vocab.length === 0)
         return '';
     // SAFETY: rows' shape matches the two columns named in the SELECT.
@@ -220,10 +218,6 @@ export function pickRarestFtsQuery(db, terms, maxTerms = RAREST_TERM_COUNT) {
         .prepare(`SELECT term, doc FROM temp.z1_rarest_vocab WHERE term IN (${vocab.map(() => '?').join(', ')})`)
         .all(...vocab);
     const counts = new Map(rows.map((r) => [r.term, r.doc]));
-    const docCount = (t) => {
-        const parts = partsOf(t);
-        return parts.length === 0 ? 0 : Math.min(...parts.map((x) => counts.get(x) ?? 0));
-    };
-    return rarestPromptTerms(terms, docCount, maxTerms).join(' ');
+    return rarestFtsQuery(terms, (part) => counts.get(part) ?? 0, maxTerms);
 }
 //# sourceMappingURL=search-rows.js.map

package/dist/store/sessions.d.ts

@@ -60,6 +60,11 @@ export declare function loadFreshActiveTaskSnapshot(hippoRoot: string, tenantId:
     maxAgeMs?: number;
     sessionId?: string | null;
 }, key?: ContinuityKey): TaskSnapshot | null;
+/** `loadFreshActiveTaskSnapshot`'s owner-match-or-age rule, for a snapshot a store read. */
+export declare function freshActiveSnapshot(snapshot: TaskSnapshot | null, opts?: {
+    maxAgeMs?: number;
+    sessionId?: string | null;
+}): TaskSnapshot | null;
 export declare function clearActiveTaskSnapshot(hippoRoot: string, tenantId: string, clearedStatus?: string): boolean;
 /**
  * Close the `active` task snapshot(s) owned by `sessionId`, for the

package/dist/store/sessions.js

@@ -142,7 +142,10 @@ function isNonEmptySessionId(value) {
  * No SQL change — age derives from the existing `updated_at` column.
  */
 export function loadFreshActiveTaskSnapshot(hippoRoot, tenantId, opts = {}, key) {
-    const snapshot = loadActiveTaskSnapshot(hippoRoot, tenantId, key);
+    return freshActiveSnapshot(loadActiveTaskSnapshot(hippoRoot, tenantId, key), opts);
+}
+/** `loadFreshActiveTaskSnapshot`'s owner-match-or-age rule, for a snapshot a store read. */
+export function freshActiveSnapshot(snapshot, opts = {}) {
     if (!snapshot)
         return null;
     const callerSessionId = opts.sessionId;

package/dist/store-port.d.ts

@@ -1,13 +1,17 @@
+import type { AmbientTallies } from './ambient.js';
+import { type AmbientStoreFilter } from './ambient-store.js';
 import { type ApiKeyListRow, type ApiKeyRecord, type ListApiKeysOpts, type NewApiKey } from './auth.js';
 import { type AppendAuditOpts, type AuditEvent, type ListAuditAfterOpts } from './audit.js';
 import type { ContinuityBlock } from './api/recall-types.js';
 import { type EmbeddingIndexState } from './embeddings.js';
 import { type ActiveGoals, type GetActiveGoalsOpts, type GoalRecallLogRow } from './goals.js';
+import type { SessionHandoff } from './handoff.js';
 import type { JsonValue } from './json.js';
 import type { MemoryEntry } from './memory.js';
 import type { PhysicsParticle } from './physics.js';
 import { type PlanningFallacyEvidence } from './predictions/planning-fallacy.js';
 import { type RecallTraceInput } from './recall-trace.js';
+import { type AmbientLoadResult, type AmbientRecallRequest, type ContextCandidateFilter, type RecentOrigins } from './store/candidates.js';
 import { type StrengthenOptions } from './store/entry-writes.js';
 import { type OriginFilter, type VectorCandidateSpec } from './store/search-rows.js';
 import { type ContinuityKey } from './store/sessions.js';
@@ -102,6 +106,71 @@ export interface KeyAudit {
     /** The highest audit id ever assigned, pruned rows included, 0 before the first; a tail that sees it drop knows the log was restored. */
     auditHighId(): Promise<number>;
 }
+/** One ambient load: the pins, the `recentNeeded` newest rows `admit` keeps, and the prompt-recall candidates. */
+export interface AmbientCandidateRequest {
+    readonly recentNeeded: number;
+    /** Sees each row in the order `loadAmbientCandidates` reads them, since the delivery ledger counts its refusals. */
+    readonly admit: (e: MemoryEntry) => boolean;
+    readonly recall?: AmbientRecallRequest;
+    readonly origins?: RecentOrigins;
+}
+/** The reads behind getContext beyond the base `continuity`: its fallback handoff, candidate rows and ambient tallies.
+ *  getContext with a query under an embedding provider needs `vectors` too, and answers 501 without it. */
+export interface ContextReads {
+    /** The newest handoff of the last `maxAgeMs` that is its session's highest id, has no outcome or a partial or failed one, and
+     *  passes recall's default scope deny, as `loadLatestHandoff` with `unfinishedOnly` and `scopeFilter: 'default-deny'`. Rejects an empty tenant id. */
+    unfinishedHandoff(tenantId: string, maxAgeMs: number, key: ContinuityKey | null): Promise<SessionHandoff | null>;
+    /** As `loadAmbientCandidates`; `recall` searches with the query `rarestFtsQuery` builds from FTS document counts over every tenant's rows,
+     *  and finds nothing when no term is indexed. Core keeps only `tenantId`'s rows that its own admit passes, whatever the store returns. */
+    ambientCandidates(tenantId: string, request: AmbientCandidateRequest): Promise<AmbientLoadResult>;
+    /** As `loadContextCandidates`: at most `filter.cap` live rows, pins and then the least decayed first, returned by created, then id. */
+    contextCandidates(tenantId: string, filter: ContextCandidateFilter): Promise<MemoryEntry[]>;
+    /** As `loadAmbientTallies`: one aggregate over the live, unarchived rows `filter` admits, less other projects' secret-tagged rows. */
+    ambientTallies(tenantId: string, filter: AmbientStoreFilter): Promise<AmbientTallies>;
+}
+export interface EntryWrite {
+    readonly entry: MemoryEntry;
+    readonly actor: string;
+}
+/** Who acts on which of a tenant's rows; `ownScope` is the caller's personal scope, so every other personal row is out of reach. */
+export interface EntryTarget {
+    readonly tenantId: string;
+    readonly actor: string;
+    readonly ownScope: string | null;
+}
+export interface OutcomeWrite extends EntryTarget {
+    readonly ids: readonly string[];
+    readonly good: boolean;
+}
+export interface SupersedeWrite extends EntryTarget {
+    readonly oldId: string;
+    readonly successor: MemoryEntry;
+}
+export interface EntryRemoval extends EntryTarget {
+    readonly id: string;
+}
+export interface RawArchive extends EntryRemoval {
+    readonly reason: string;
+}
+/** The memory-row writes behind remember, outcome, supersede, archive and forget. Each writes its audit rows in the write's own transaction,
+ *  a child row's change marks its level 2 or 3 summary parent dirty (one summary_marked_dirty row on the flip), and the schema's rules hold. */
+export interface EntryWrites {
+    /** Upserts the row, its full-text row and one remember row ({kind, scope}) in the entry's tenant; an id another tenant holds rejects in the transaction with ConflictError `Memory <id>
+     *  belongs to another tenant`. Content the write brings into a tenant that tombstoned it rejects with RejectedValueError and writes one reject_refusal row after the rollback, best effort. */
+    writeEntry(write: EntryWrite): Promise<void>;
+    /** For each id in order, a row of the tenant within reach gets `entryAfterOutcome`, a rewrite as writeEntry does and one outcome row ({good}); other ids are skipped, a repeated id builds
+     *  on its first outcome. Each read holds the row's lock to commit (SELECT ... FOR UPDATE), so a supersede between read and rewrite is not undone. Resolves to the ids applied, repeats kept. */
+    applyOutcome(outcome: OutcomeWrite): Promise<string[]>;
+    /** Sets the old row's superseded_by where it is within reach and not yet superseded, both checked in the transaction, else rejects with NotFoundError `memory not found: <oldId>` or
+     *  ConflictError `Memory <oldId> already superseded by another writer`. Then writes the successor as writeEntry does and one supersede row ({newId}), all or nothing. */
+    supersede(write: SupersedeWrite): Promise<void>;
+    /** Moves a raw row to raw_archive (metadata only, no content), deletes it and its full-text row and writes one archive_raw row ({reason});
+     *  resolves to the archived_at written. A row out of reach rejects with NotFoundError `memory not found: <id>`, any other kind with BadRequestError. */
+    archiveRaw(archive: RawArchive): Promise<string>;
+    /** Deletes the row and its full-text row and writes one forget row; a raw row rejects, being append-only. A row out of reach rejects with
+     *  NotFoundError `memory not found: <id>`. Archive and forget then add one to the store-wide forgotten counter, best effort. */
+    forget(removal: EntryRemoval): Promise<void>;
+}
 /** A key to insert and the actor and metadata of its auth_create row, whose tenant and target are the key's. Neither holds the plaintext. */
 export interface KeyMint {
     readonly key: NewApiKey;
@@ -139,6 +208,8 @@ export interface StoreGroups {
     readonly keyWrites: KeyWrites;
     /** embedMemory and embedAll with a store need it and `vectors`. */
     readonly vectorWrites: VectorWrites;
+    readonly entryWrites: EntryWrites;
+    readonly contextReads: ContextReads;
 }
 export type StoreGroup = 'base' | keyof StoreGroups;
 export declare function hasGroup(store: HippoStore, group: StoreGroup): boolean;