hippo-memory 1.69.0 → 1.71.0

package/dist/store/sqlite/objects-group.js

@@ -0,0 +1,316 @@
+// hippo.db's half of the Objects store group: every statement the typed objects run, each call on a handle of its own.
+import { appendAuditEvent } from '../audit.js';
+import { getMeta, withWriteScopeOr } from '../../db/index.js';
+import { escapeLike } from '../../util/escape.js';
+import { keysetAfter } from '../../util/keyset.js';
+import { calculateStrength, deriveHalfLife } from '../../core/memory.js';
+import { scopeAdmitSql } from '../recall-scope.js';
+import { stampOriginProject, upsertEntryRow } from '../entry-row.js';
+import { auditEntryWrite, writeEntryMirrors } from '../entry-writes.js';
+import { markGraphDirty } from '../graph-queue.js';
+import { removeGraphEntitiesForObject } from '../graph-writes.js';
+import { LEGACY_TYPED_HALF_LIFE, onHandle, openStore, TYPED_HALF_LIFE_META_KEY } from '../open.js';
+import { isObjectRefusal, } from '../port.js';
+import { auditingRefusal } from './entry-writes-group.js';
+import { insertSpec, rowSpec } from './object-rows.js';
+export function sqliteObjects(hippoRoot) {
+    return {
+        listObjects: (tenantId, kind, query) => onHandle(hippoRoot, (db) => listRows(db, tenantId, kind, query)),
+        objectById(tenantId, kind, id) {
+            const row = onHandle(hippoRoot, (db) => selectRow(db, kind, tenantId, id));
+            return row ? rowSpec(kind).rowTo(row) : null;
+        },
+        closeObject: (tenantId, kind, id, close) => closeAt(hippoRoot, tenantId, kind, id, close),
+        saveObject: (tenantId, kind, save) => saveAt(hippoRoot, tenantId, kind, save),
+        openIncident: (tenantId, open) => openIncidentAt(hippoRoot, tenantId, open),
+        resolveIncident: (tenantId, id, resolve) => onHandle(hippoRoot, (db) => resolveRow(db, tenantId, id, resolve)),
+        policiesInForce: (tenantId, query) => onHandle(hippoRoot, (db) => policiesInForce(db, tenantId, query)),
+        activeSkillsByName: (tenantId, limit) => onHandle(hippoRoot, (db) => activeSkillsByName(db, tenantId, limit)),
+        briefReceipts: (tenantId, tag, limit) => onHandle(hippoRoot, (db) => briefReceipts(db, tenantId, tag, limit)),
+    };
+}
+/** The group as a served store answers it: each call runs at once and resolves through a Promise, so a throw rejects as another store's would. */
+export function servedObjects(sync) {
+    return {
+        listObjects: async (tenantId, kind, query) => sync.listObjects(tenantId, kind, query),
+        objectById: async (tenantId, kind, id) => sync.objectById(tenantId, kind, id),
+        closeObject: async (tenantId, kind, id, close) => sync.closeObject(tenantId, kind, id, close),
+        saveObject: async (tenantId, kind, save) => sync.saveObject(tenantId, kind, save),
+        openIncident: async (tenantId, open) => sync.openIncident(tenantId, open),
+        resolveIncident: async (tenantId, id, resolve) => sync.resolveIncident(tenantId, id, resolve),
+        policiesInForce: async (tenantId, query) => sync.policiesInForce(tenantId, query),
+        activeSkillsByName: async (tenantId, limit) => sync.activeSkillsByName(tenantId, limit),
+        briefReceipts: async (tenantId, tag, limit) => sync.briefReceipts(tenantId, tag, limit),
+    };
+}
+/** The newest object in `status` that a memory mirrors, for the CLI flags that name an object by its memory id. */
+export function objectIdByMemory(hippoRoot, tenantId, kind, status, memoryId) {
+    return onHandle(hippoRoot, (db) => {
+        const row = db.prepare(`SELECT id FROM ${rowSpec(kind).table} WHERE memory_id = ? AND tenant_id = ? AND status = ? ORDER BY id DESC LIMIT 1`).get(memoryId, tenantId, status);
+        return row ? row.id : null;
+    });
+}
+function selectRow(db, kind, tenantId, id) {
+    const spec = rowSpec(kind);
+    return db.prepare(`SELECT ${spec.cols} FROM ${spec.table} WHERE id = ? AND tenant_id = ?`).get(id, tenantId);
+}
+function listRows(db, tenantId, kind, query) {
+    const spec = rowSpec(kind);
+    const clauses = ['tenant_id = ?'];
+    const params = [tenantId];
+    if (query.status) {
+        clauses.push('status = ?');
+        params.push(query.status);
+    }
+    if (query.filter && spec.filterColumn) {
+        clauses.push(`${spec.filterColumn} = ?`);
+        params.push(query.filter);
+    }
+    const after = keysetAfter('created_at', 'id', query.after);
+    // SAFETY: the SELECT names spec.cols, the columns the kind's row declares, whatever the WHERE clause holds.
+    const rows = db.prepare(`
+    SELECT ${spec.cols} FROM ${spec.table}
+    WHERE ${clauses.join(' AND ')}${after.sql}
+    ORDER BY created_at DESC, id DESC
+    LIMIT ?
+  `).all(...params, ...after.params, query.limit);
+    return rows.map((row) => spec.rowTo(row));
+}
+/** The status guard sits in the UPDATE, so zero rows changed means missing or not closable; the reread tells which. */
+function closeRow(db, tenantId, kind, id, close) {
+    const spec = rowSpec(kind);
+    return withWriteScopeOr(db, 'close_object', (rollback) => {
+        const marks = close.from.map(() => '?').join(', ');
+        const updated = db.prepare(`UPDATE ${spec.table} SET status = 'closed', closed_at = ? WHERE id = ? AND tenant_id = ? AND status IN (${marks})`).run(close.at, id, tenantId, ...close.from);
+        if (updated.changes === 0) {
+            const existing = db.prepare(`SELECT status FROM ${spec.table} WHERE id = ? AND tenant_id = ?`)
+                .get(id, tenantId);
+            return rollback(existing ? { refused: 'status', status: existing.status } : { refused: 'missing' });
+        }
+        const row = selectRow(db, kind, tenantId, id);
+        if (!row)
+            return rollback({ refused: 'vanished' });
+        appendAuditEvent(db, { tenantId, actor: close.actor, op: spec.closeOp, targetId: String(id), metadata: { [spec.idKey]: id } });
+        return spec.rowTo(row);
+    });
+}
+function closeAt(hippoRoot, tenantId, kind, id, close) {
+    const { graphType } = rowSpec(kind);
+    return onHandle(hippoRoot, (db) => {
+        const closed = closeRow(db, tenantId, kind, id, close);
+        if (isObjectRefusal(closed) || !graphType)
+            return closed;
+        // Each graph write takes its own write lock, so both wait for the commit. The rows
+        // go at once because the rebuild queue is keyed by a mirror memory that may be gone.
+        removeGraphEntitiesForObject(hippoRoot, tenantId, graphType, closed.id);
+        markGraphDirty(hippoRoot, tenantId, closed.memoryId);
+        return closed;
+    });
+}
+/** Runs before the INSERT, so the new row's id can never be the id it replaces. */
+function successorVersion(db, tenantId, kind, replaced) {
+    const pred = db.prepare(`SELECT status, ${insertSpec(kind).versioned ? 'version' : '0 AS version'} FROM ${rowSpec(kind).table} WHERE id = ? AND tenant_id = ?`).get(replaced, tenantId);
+    if (!pred)
+        return { refused: 'missing' };
+    if (pred.status !== 'active')
+        return { refused: 'status', status: pred.status };
+    return { version: pred.version + 1 };
+}
+function insertRow(db, row) {
+    const insert = insertSpec(row.kind);
+    const cols = ['memory_id', 'tenant_id', ...insert.columns];
+    const values = [row.memoryId, row.tenantId, ...insert.values(row.save.fields)];
+    if (insert.versioned) {
+        cols.push('version', 'change_summary');
+        values.push(row.version, row.save.supersedesId === undefined ? null : row.save.changeSummary ?? null);
+    }
+    const result = db.prepare(`
+    INSERT INTO ${rowSpec(row.kind).table}(${cols.join(', ')}, status, superseded_by, superseded_at, closed_at, created_at)
+    VALUES (${cols.map(() => '?').join(', ')}, 'active', NULL, NULL, NULL, ?)
+  `).run(...values, row.save.at);
+    return Number(result.lastInsertRowid ?? 0);
+}
+/** The status guard sits in the UPDATE, so a row another writer retired since the preflight fails the whole save; false says so. */
+function supersedeRow(db, row, replaced, id) {
+    const spec = rowSpec(row.kind);
+    const insert = insertSpec(row.kind);
+    const updated = db.prepare(`
+    UPDATE ${spec.table}
+    SET status = 'superseded', superseded_by = ?, superseded_at = ?
+    WHERE id = ? AND tenant_id = ? AND status = 'active' AND id != ?
+  `).run(id, row.save.at, replaced, row.tenantId, id);
+    if (updated.changes === 0)
+        return false;
+    const own = insert.versioned
+        ? { [spec.idKey]: replaced, superseded_by: id, new_version: row.version }
+        : { [spec.idKey]: replaced, superseded_by: id };
+    appendAuditEvent(db, {
+        tenantId: row.tenantId,
+        actor: row.save.actor,
+        op: insert.supersedeOp,
+        targetId: String(replaced),
+        metadata: { ...own, ...insert.supersedeMeta?.(row.save.fields) },
+    });
+    return true;
+}
+/** The object half of a save, inside the scope that holds the mirror memory: a refusal or a throw here leaves no row, memory or audit event. */
+function writeObjectRow(db, tenantId, kind, memoryId, save) {
+    const replaced = save.supersedesId;
+    const next = replaced === undefined ? { version: 1 } : successorVersion(db, tenantId, kind, replaced);
+    if (isObjectRefusal(next))
+        return next;
+    const row = { tenantId, kind, memoryId, save, version: next.version };
+    const id = insertRow(db, row);
+    if (replaced !== undefined && !supersedeRow(db, row, replaced, id))
+        return { refused: 'raced' };
+    const saved = selectRow(db, kind, tenantId, id);
+    if (!saved)
+        return { refused: 'vanished' };
+    appendAuditEvent(db, {
+        tenantId,
+        actor: save.actor,
+        op: insertSpec(kind).createOp,
+        targetId: String(id),
+        metadata: { [rowSpec(kind).idKey]: id, ...insertSpec(kind).createMeta(save.fields, next.version) },
+    });
+    return saved;
+}
+function refusalOf(written) {
+    return 'refused' in written;
+}
+/** Until the typed migration has run, a mirror goes in on the flat half-life that migration
+ * moves; the flag is read under the save's write lock, so the two cannot interleave. */
+function onStoreHalfLife(db, mirror) {
+    if (getMeta(db, TYPED_HALF_LIFE_META_KEY, '') !== '')
+        return mirror;
+    const legacy = { ...mirror, half_life_days: deriveHalfLife(LEGACY_TYPED_HALF_LIFE, mirror) };
+    return { ...legacy, strength: calculateStrength(legacy) };
+}
+/** One write scope on one handle holds the mirror, the row `writeRow` adds, the successor link and every audit row, the mirror's remember row last. */
+function withMirror(hippoRoot, write, writeRow) {
+    return onHandle(hippoRoot, (db) => auditingRefusal(db, write.actor, () => {
+        let mirror = stampOriginProject(hippoRoot, write.mirror);
+        const written = withWriteScopeOr(db, 'write_entry', (rollback) => {
+            mirror = onStoreHalfLife(db, mirror);
+            upsertEntryRow(db, mirror);
+            const row = writeRow(db, mirror.id);
+            if (refusalOf(row))
+                return rollback(row);
+            auditEntryWrite(db, mirror, write.actor);
+            return row;
+        });
+        if (refusalOf(written))
+            return written;
+        // The graph mark takes its own write lock, so it waits for the commit.
+        if (write.graphTenant !== undefined)
+            markGraphDirty(hippoRoot, write.graphTenant, mirror.id);
+        writeEntryMirrors(hippoRoot, mirror);
+        return written;
+    }), openStore);
+}
+function saveAt(hippoRoot, tenantId, kind, save) {
+    const spec = rowSpec(kind);
+    const write = { mirror: save.mirror, actor: save.actor, graphTenant: spec.graphType ? tenantId : undefined };
+    const written = withMirror(hippoRoot, write, (db, memoryId) => writeObjectRow(db, tenantId, kind, memoryId, save));
+    return isObjectRefusal(written) ? written : spec.rowTo(written);
+}
+/** The linked ids are checked once the mirror is in and before the INSERT, so a refusal undoes the mirror with it. */
+function openIncidentRow(db, tenantId, memoryId, open) {
+    const { incidentText, context, linkedMemoryIds } = open.fields;
+    for (const linkId of linkedMemoryIds) {
+        const held = db.prepare(`SELECT id FROM memories WHERE id = ? AND tenant_id = ?`).get(linkId, tenantId);
+        if (!held)
+            return { refused: 'unlinked', memoryId: linkId };
+    }
+    const result = db.prepare(`
+    INSERT INTO incidents(
+      memory_id, tenant_id, incident_text, context,
+      status, resolution_text, resolved_at, closed_at, linked_memory_ids, created_at
+    ) VALUES (?, ?, ?, ?, 'open', NULL, NULL, NULL, ?, ?)
+  `).run(memoryId, tenantId, incidentText, context ?? null, JSON.stringify(linkedMemoryIds), open.at);
+    const id = Number(result.lastInsertRowid ?? 0);
+    const row = selectRow(db, 'incident', tenantId, id);
+    if (!row)
+        return { refused: 'vanished' };
+    appendAuditEvent(db, {
+        tenantId,
+        actor: open.actor,
+        op: 'incident_open',
+        targetId: String(id),
+        metadata: { incident_id: id, has_context: context !== undefined && context !== '', linked_memory_count: linkedMemoryIds.length },
+    });
+    return row;
+}
+function openIncidentAt(hippoRoot, tenantId, open) {
+    const write = { mirror: open.mirror, actor: open.actor };
+    const written = withMirror(hippoRoot, write, (db, memoryId) => openIncidentRow(db, tenantId, memoryId, open));
+    return 'refused' in written ? written : rowSpec('incident').rowTo(written);
+}
+/** The status guard sits in the UPDATE, so zero rows changed means missing or not open; the reread tells which. */
+function resolveRow(db, tenantId, id, resolve) {
+    return withWriteScopeOr(db, 'resolve_incident', (rollback) => {
+        const updated = db.prepare(`
+      UPDATE incidents
+      SET status = 'resolved', resolution_text = ?, resolved_at = ?
+      WHERE id = ? AND tenant_id = ? AND status = 'open'
+    `).run(resolve.text, resolve.at, id, tenantId);
+        if (updated.changes === 0) {
+            const existing = db.prepare(`SELECT status FROM incidents WHERE id = ? AND tenant_id = ?`)
+                .get(id, tenantId);
+            return rollback(existing ? { refused: 'status', status: existing.status } : { refused: 'missing' });
+        }
+        const row = selectRow(db, 'incident', tenantId, id);
+        if (!row)
+            return rollback({ refused: 'vanished' });
+        appendAuditEvent(db, { tenantId, actor: resolve.actor, op: 'incident_resolve', targetId: String(id), metadata: { incident_id: id } });
+        return rowSpec('incident').rowTo(row);
+    });
+}
+/** The successor is joined in so a superseded version is kept only while the row that replaced it is not yet in force. */
+function policiesInForce(db, tenantId, query) {
+    const { asOf, name } = query;
+    const nameClause = name !== undefined ? 'AND p.policy_name = ?' : '';
+    const params = [tenantId, asOf, asOf, asOf];
+    if (name !== undefined)
+        params.push(name);
+    // SAFETY: the SELECT names the policy row's own columns, each under the alias p.
+    const rows = db.prepare(`
+      SELECT p.id, p.memory_id, p.tenant_id, p.policy_name, p.policy_text,
+             p.valid_from, p.valid_to, p.version, p.status, p.superseded_by,
+             p.superseded_at, p.change_summary, p.closed_at, p.created_at
+      FROM policies p
+      LEFT JOIN policies s ON s.id = p.superseded_by
+      WHERE p.tenant_id = ? AND p.status != 'closed'
+        AND p.valid_from <= ? AND (p.valid_to IS NULL OR ? < p.valid_to)
+        AND (p.status = 'active' OR (s.id IS NOT NULL AND s.valid_from > ?))
+        ${nameClause}
+      ORDER BY p.valid_from DESC, p.id DESC
+      LIMIT ?
+    `).all(...params, query.limit);
+    return rows.map(rowSpec('policy').rowTo);
+}
+function activeSkillsByName(db, tenantId, limit) {
+    // SAFETY: the SELECT names the skill row's own column list.
+    const rows = db.prepare(`
+      SELECT ${rowSpec('skill').cols} FROM skills
+      WHERE tenant_id = ? AND status = 'active'
+      ORDER BY skill_name ASC, id ASC
+      LIMIT ?
+    `).all(tenantId, limit);
+    return rows.map(rowSpec('skill').rowTo);
+}
+/** The quotes around the tag stop `path:hip` matching a memory tagged `path:hippo`. */
+function briefReceipts(db, tenantId, tag, limit) {
+    const admit = scopeAdmitSql('');
+    // SAFETY: the SELECT names the four columns a receipt holds.
+    return db.prepare(`
+      SELECT id, created, source, content FROM memories
+      WHERE tenant_id = ?
+        AND source != 'project_brief'
+        AND LOWER(tags_json) LIKE ? ESCAPE '\\'
+        AND ${admit.sql}
+      ORDER BY created DESC, id DESC
+      LIMIT ?
+    `).all(tenantId, `%"${escapeLike(tag)}"%`, ...admit.params, limit);
+}
+//# sourceMappingURL=objects-group.js.map

package/dist/store/sqlite/predictions-group.d.ts

@@ -0,0 +1,5 @@
+import type { Predictions, Sync } from '../port.js';
+export declare function sqlitePredictions(hippoRoot: string): Sync<Predictions>;
+/** The group as a served store answers it: each call runs at once and resolves through a Promise, so a throw rejects as another store's would. */
+export declare function servedPredictions(sync: Sync<Predictions>): Predictions;
+//# sourceMappingURL=predictions-group.d.ts.map

package/dist/store/sqlite/predictions-group.js

@@ -0,0 +1,28 @@
+// hippo.db's half of the Predictions store group: each method is one call into the queries the CLI and the MCP tools run.
+import { closePrediction, computePredictionBaserate, loadAllPredictions, loadOpenPredictions, loadPredictionById, loadPredictionsByClass, writePrediction, } from '../predictions.js';
+export function sqlitePredictions(hippoRoot) {
+    return {
+        savePrediction: (tenantId, input, actor) => writePrediction(hippoRoot, tenantId, input, actor),
+        closePrediction: (tenantId, id, close, actor) => closePrediction(hippoRoot, tenantId, id, close, actor),
+        predictionById: (tenantId, id) => loadPredictionById(hippoRoot, tenantId, id),
+        listPredictions(tenantId, { classTag, closureState, limit, after }) {
+            if (closureState === 'open')
+                return loadOpenPredictions(hippoRoot, tenantId, { classTag, limit, after });
+            if (classTag === undefined)
+                return loadAllPredictions(hippoRoot, tenantId, { limit, after });
+            return loadPredictionsByClass(hippoRoot, tenantId, classTag, { closureState, limit, after });
+        },
+        predictionBaserate: (tenantId, classTag, actor) => computePredictionBaserate(hippoRoot, tenantId, classTag, actor),
+    };
+}
+/** The group as a served store answers it: each call runs at once and resolves through a Promise, so a throw rejects as another store's would. */
+export function servedPredictions(sync) {
+    return {
+        savePrediction: async (tenantId, input, actor) => sync.savePrediction(tenantId, input, actor),
+        closePrediction: async (tenantId, id, close, actor) => sync.closePrediction(tenantId, id, close, actor),
+        predictionById: async (tenantId, id) => sync.predictionById(tenantId, id),
+        listPredictions: async (tenantId, query) => sync.listPredictions(tenantId, query),
+        predictionBaserate: async (tenantId, classTag, actor) => sync.predictionBaserate(tenantId, classTag, actor),
+    };
+}
+//# sourceMappingURL=predictions-group.js.map

package/dist/store/sqlite/quarantine-group.d.ts

@@ -0,0 +1,5 @@
+import type { Quarantine, Sync } from '../port.js';
+export declare function sqliteQuarantine(hippoRoot: string): Sync<Quarantine>;
+/** The group as a served store answers it: each call runs at once and resolves through a Promise, so a throw rejects as another store's would. */
+export declare function servedQuarantine(sync: Sync<Quarantine>): Quarantine;
+//# sourceMappingURL=quarantine-group.d.ts.map

package/dist/store/sqlite/quarantine-group.js

@@ -0,0 +1,38 @@
+// hippo.db's half of the Quarantine store group: each method is one call on its own handle.
+import { errorFields, errorMessage, log } from '../../util/log.js';
+import { readEntry } from '../entry-reads.js';
+import { writeEntryMirrors } from '../entry-writes.js';
+import { onHandle } from '../open.js';
+import { approveQuarantinedAt, listQuarantinedAt, rejectQuarantinedAt } from '../quarantine.js';
+/** After the commit, best effort: a failed rewrite leaves the markdown mirror showing the quarantine scope, which still hides the memory. */
+function rewriteMirror(hippoRoot, tenantId, id) {
+    try {
+        const restored = readEntry(hippoRoot, id, tenantId);
+        if (restored)
+            writeEntryMirrors(hippoRoot, restored);
+    }
+    catch (err) {
+        log.error(`quarantine: mirror rewrite failed for ${id}: ${errorMessage(err)}`, errorFields(err));
+    }
+}
+export function sqliteQuarantine(hippoRoot) {
+    return {
+        listQuarantined: (tenantId, query) => onHandle(hippoRoot, (db) => listQuarantinedAt(db, tenantId, query)),
+        approveQuarantined(tenantId, id, actor) {
+            const result = onHandle(hippoRoot, (db) => approveQuarantinedAt(db, tenantId, id, actor));
+            if (result.outcome === 'approved')
+                rewriteMirror(hippoRoot, tenantId, id);
+            return result;
+        },
+        rejectQuarantined: (tenantId, id, actor) => onHandle(hippoRoot, (db) => rejectQuarantinedAt(db, tenantId, id, actor)),
+    };
+}
+/** The group as a served store answers it: each call runs at once and resolves through a Promise, so a throw rejects as another store's would. */
+export function servedQuarantine(sync) {
+    return {
+        listQuarantined: async (tenantId, query) => sync.listQuarantined(tenantId, query),
+        approveQuarantined: async (tenantId, id, actor) => sync.approveQuarantined(tenantId, id, actor),
+        rejectQuarantined: async (tenantId, id, actor) => sync.rejectQuarantined(tenantId, id, actor),
+    };
+}
+//# sourceMappingURL=quarantine-group.js.map

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

@@ -0,0 +1,23 @@
+import type { HippoStore, RecallWrites, StoreGroups, Sync } from '../port.js';
+/** The store a request runs on: the served one, else hippo.db under its root, as the CLI and SDK callers have it. */
+export declare function storeFor(ctx: {
+    readonly hippoRoot: string;
+    readonly store?: HippoStore;
+}): HippoStore;
+/** Not on the synchronous store: the nearest-row scan yields to the event loop, so this group answers only through Promises. */
+type AsyncOnly = 'vectors';
+/** The port as hippo.db answers it: each call runs to its end and returns the value, so no write scope spans an await. */
+export type SqliteSyncStore = Sync<Omit<HippoStore, AsyncOnly>>;
+/** The built-in store: hippo.db under the port's own method names, each call on its own short-lived handles, so close has nothing to release. */
+export declare function sqliteSyncStore(hippoRoot: string): SqliteSyncStore & Sync<Omit<StoreGroups, AsyncOnly>>;
+/** `sqliteSyncStore` as a served store: each method runs at once and answers through a Promise, so a throw rejects as another store's would. */
+export declare function sqliteStore(hippoRoot: string): HippoStore & StoreGroups;
+/** What a finished recall wrote after its audit rows: the trace's id, null when none was asked or its write failed, and the ids strengthened. */
+interface RecallFinish {
+    readonly traceId: number | null;
+    readonly strengthened: ReadonlySet<string>;
+}
+/** sqliteStore's finishRecall, for the synchronous recall that cannot await the port. */
+export declare function finishRecallAt(hippoRoot: string, writes: RecallWrites): RecallFinish;
+export {};
+//# sourceMappingURL=store.d.ts.map