hippo-memory 1.67.0 → 1.69.0

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/key-writes.d.ts

@@ -0,0 +1,9 @@
+import { type AppendAuditOpts } from '../audit.js';
+import { type DatabaseSyncLike } from '../db.js';
+import type { KeyMint, SelfKeyMint } from '../store-port.js';
+/** The auth_create row a mint writes; the plaintext never reaches it. */
+export declare function createAuditOf({ key, actor, metadata }: KeyMint): AppendAuditOpts;
+export declare function createKeyAt(db: DatabaseSyncLike, mint: KeyMint): void;
+/** IMMEDIATE takes the write lock before the count, so two mints for one owner cannot both see room under the cap. */
+export declare function createSelfKeyAt(db: DatabaseSyncLike, mint: SelfKeyMint): string[];
+//# sourceMappingURL=key-writes.d.ts.map

package/dist/store/key-writes.js

@@ -0,0 +1,30 @@
+// hippo.db's half of the KeyWrites store group.
+import { appendAuditEvent } from '../audit.js';
+import { insertApiKey, listLiveOwnedKeyIds, revokeApiKey } from '../auth.js';
+import { withWriteScope } from '../db.js';
+/** The auth_create row a mint writes; the plaintext never reaches it. */
+export function createAuditOf({ key, actor, metadata }) {
+    return { tenantId: key.tenantId, actor, op: 'auth_create', targetId: key.keyId, metadata };
+}
+export function createKeyAt(db, mint) {
+    withWriteScope(db, 'create_api_key', () => {
+        insertApiKey(db, mint.key);
+        appendAuditEvent(db, createAuditOf(mint));
+    });
+}
+/** IMMEDIATE takes the write lock before the count, so two mints for one owner cannot both see room under the cap. */
+export function createSelfKeyAt(db, mint) {
+    const { key, actor, perSubject } = mint;
+    return withWriteScope(db, 'create_self_api_key', () => {
+        const live = listLiveOwnedKeyIds(db, key.tenantId, key.ownerSubject, Date.parse(key.createdAt));
+        const replaced = live.slice(0, Math.max(0, live.length - perSubject + 1));
+        insertApiKey(db, key);
+        for (const keyId of replaced) {
+            revokeApiKey(db, keyId, key.createdAt);
+            appendAuditEvent(db, { tenantId: key.tenantId, actor, op: 'auth_revoke', targetId: keyId, metadata: { replacedBy: key.keyId } });
+        }
+        appendAuditEvent(db, createAuditOf(mint));
+        return replaced;
+    });
+}
+//# sourceMappingURL=key-writes.js.map

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/vector-writes.d.ts

@@ -0,0 +1,6 @@
+import { type DatabaseSyncLike } from '../db.js';
+import type { MemoryEntry } from '../memory.js';
+import type { VectorBackfillQuery, VectorWrite, VectorWriteResult } from '../store-port.js';
+export declare function entriesWithoutVectorAt(db: DatabaseSyncLike, query: VectorBackfillQuery): MemoryEntry[];
+export declare function writeVectorsAt(db: DatabaseSyncLike, write: VectorWrite): VectorWriteResult;
+//# sourceMappingURL=vector-writes.d.ts.map

package/dist/store/vector-writes.js

@@ -0,0 +1,59 @@
+// hippo.db's half of the VectorWrites store group.
+import { setMeta, withWriteScope } from '../db.js';
+import { embeddingIndexStateOn, replacesIndex } from '../embeddings.js';
+import { float32ToBuffer } from '../physics-state.js';
+import { EMBEDDING_MODEL_META_KEY, upsertVectors } from '../vector-store.js';
+import { chunked } from './entry-reads.js';
+import { MEMORY_SELECT_COLUMNS, rowToEntry } from './rows.js';
+const MAX_BACKFILL_PAGE = 500;
+export function entriesWithoutVectorAt(db, query) {
+    if (!Number.isInteger(query.limit))
+        throw new RangeError('limit must be an integer');
+    const limit = Math.max(1, Math.min(query.limit, MAX_BACKFILL_PAGE));
+    const tenantClause = query.tenantId === undefined ? '' : ' AND tenant_id = ?';
+    const tenantArgs = query.tenantId === undefined ? [] : [query.tenantId];
+    // SAFETY: selects exactly MEMORY_SELECT_COLUMNS, matching MemoryRow's field set.
+    const rows = db.prepare(`SELECT ${MEMORY_SELECT_COLUMNS} FROM memories WHERE id > ?${tenantClause}
+       AND NOT EXISTS (SELECT 1 FROM memory_vectors v WHERE v.memory_id = memories.id AND v.model = ?)
+     ORDER BY id LIMIT ?`).all(query.afterId ?? '', ...tenantArgs, query.model, limit);
+    return rows.map(rowToEntry);
+}
+function ownedIds(db, ids, tenantId) {
+    const owned = new Set();
+    for (const chunk of chunked([...new Set(ids)])) {
+        // SAFETY: the SELECT names one column, id.
+        const rows = db.prepare(`SELECT id FROM memories WHERE tenant_id = ? AND id IN (${chunk.map(() => '?').join(', ')})`).all(tenantId, ...chunk);
+        for (const row of rows)
+            owned.add(row.id);
+    }
+    return owned;
+}
+// savePhysicsState opens its own transaction and overwrites, so the first particle for a memory is inserted here instead.
+function insertNewParticles(db, rows) {
+    const stmt = db.prepare(`
+    INSERT INTO memory_physics (memory_id, position_blob, velocity_blob, mass, charge, temperature, last_simulation)
+    VALUES (?, ?, ?, ?, ?, ?, ?) ON CONFLICT(memory_id) DO NOTHING
+  `);
+    for (const { memoryId, particle: p } of rows) {
+        if (p)
+            stmt.run(memoryId, float32ToBuffer(p.position), float32ToBuffer(p.velocity), p.mass, p.charge, p.temperature, p.lastSimulation);
+    }
+}
+export function writeVectorsAt(db, write) {
+    return withWriteScope(db, 'write_vectors', () => {
+        const replaces = replacesIndex(embeddingIndexStateOn(db), write.model);
+        if (replaces && !write.replaceIndex)
+            return { written: 0, modelMismatch: true };
+        const owned = ownedIds(db, write.rows.map((r) => r.memoryId), write.tenantId);
+        const rows = write.rows.filter((r) => owned.has(r.memoryId) && r.vector.length > 0 && r.vector.every(Number.isFinite));
+        if (rows.length === 0)
+            return { written: 0, modelMismatch: false };
+        if (replaces)
+            db.exec('DELETE FROM memory_vectors; DELETE FROM memory_physics;');
+        const written = upsertVectors(db, rows.map((r) => [r.memoryId, r.vector]), write.model);
+        insertNewParticles(db, rows);
+        setMeta(db, EMBEDDING_MODEL_META_KEY, write.model);
+        return { written, modelMismatch: false };
+    });
+}
+//# sourceMappingURL=vector-writes.js.map

package/dist/store-port.d.ts

@@ -1,12 +1,17 @@
-import { type ApiKeyRecord } from './auth.js';
+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';
@@ -48,6 +53,44 @@ export interface VectorReads {
     /** The particles of `ids` only; an empty list reads nothing. */
     physicsParticles(ids: readonly string[]): Promise<Map<string, PhysicsParticle>>;
 }
+/** One memory's vector, computed by the caller's embedding provider. */
+export interface VectorRowWrite {
+    readonly memoryId: string;
+    readonly vector: readonly number[];
+    /** Kept only when the memory has no particle yet, under `memoryId` whatever its own memoryId says. */
+    readonly particle?: PhysicsParticle;
+}
+export interface VectorWrite {
+    readonly tenantId: string;
+    /** The index identity the vectors were built by, `embeddingIndexIdentity(provider.id)`. */
+    readonly model: string;
+    /** Set only by embedAll's rebuild, so a write that read the index state before another process rebuilt it cannot drop that rebuild. */
+    readonly replaceIndex: boolean;
+    readonly rows: readonly VectorRowWrite[];
+}
+export interface VectorWriteResult {
+    readonly written: number;
+    /** True when another model built the index and `replaceIndex` is false; the store then keeps nothing and `written` is 0. */
+    readonly modelMismatch: boolean;
+}
+export interface VectorBackfillQuery {
+    readonly model: string;
+    /** Only ids above this one in byte order; unset starts at the first. */
+    readonly afterId?: string;
+    /** Clamped to 1..500; a non-integer rejects with RangeError `limit must be an integer`. */
+    readonly limit: number;
+    /** Every tenant when unset, since the backfill covers the whole store. */
+    readonly tenantId?: string;
+}
+/** The writes behind embed on write and the backfill: core computes each vector, the store only keeps it.
+ *  A store deletes a memory's vector and particle when the memory is deleted (hippo.db does it by trigger and foreign-key cascade). */
+export interface VectorWrites {
+    /** Memories of any kind with no vector stored under `query.model`, by id ascending in byte order. */
+    entriesWithoutVector(query: VectorBackfillQuery): Promise<MemoryEntry[]>;
+    /** In one transaction: refuses with `modelMismatch` if `replacesIndex` and not `replaceIndex`; else, when a row is writable (memory in `tenantId`, vector non-empty
+     *  and finite), drops every vector and particle if `replacesIndex`, keeps each writable row under `model` with its particle where none exists, sets `model`. No audit row. */
+    writeVectors(write: VectorWrite): Promise<VectorWriteResult>;
+}
 export interface KeyRevoke {
     readonly tenantId: string;
     readonly keyId: string;
@@ -63,11 +106,110 @@ 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;
+    readonly actor: string;
+    readonly metadata: Readonly<Record<string, JsonValue>>;
+}
+export interface SelfKeyMint extends KeyMint {
+    readonly key: NewApiKey & {
+        readonly ownerSubject: string;
+        readonly expiresAt: string;
+    };
+    /** Live keys the owner may hold in the tenant once this one is in. */
+    readonly perSubject: number;
+}
+/** `listApiKeyRows`'s filters, always inside one tenant. */
+export interface KeyListQuery extends Omit<ListApiKeysOpts, 'tenantId'> {
+    readonly tenantId: string;
+}
+export interface KeyWrites {
+    /** Inserts the key and appends its auth_create row in one transaction; with either one failing, neither is written. A key id taken in any tenant
+     *  rejects, since keys are looked up by id alone. */
+    createApiKey(mint: KeyMint): Promise<void>;
+    /** One transaction, serialized per (tenant, owner) before the count (hippo.db BEGIN IMMEDIATE, Postgres pg_advisory_xact_lock on the pair): revoke at `key.createdAt`
+     *  the owner's oldest live keys in the key's tenant down to `perSubject - 1`, insert the key, append an auth_revoke row `{ replacedBy: <new key id> }` per revoked key,
+     *  then the auth_create row; resolves to the revoked ids. Live: unrevoked, expires_at null or Date.parse(expires_at) after createdAt (NaN counts as expired). */
+    createSelfApiKey(mint: SelfKeyMint): Promise<string[]>;
+    /** As `listApiKeyRows`: newest inserted first, each with its scope grants; `active` drops revoked rows and an expires_at not above now's toISOString. */
+    listApiKeys(query: KeyListQuery): Promise<ApiKeyListRow[]>;
+}
 /** The optional groups: a store sets each one whole or leaves it unset, and a route or MCP tool names the one it needs. */
 export interface StoreGroups {
     /** Unset on a store built before them, where hybrid and physics recall under an embedding provider answer 501. */
     readonly vectors: VectorReads;
     readonly keyAudit: KeyAudit;
+    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;