hippo-memory 1.69.0 → 1.70.0

package/dist/incidents.js

@@ -1,349 +0,0 @@
-/**
- * Incident first-class object.
- *
- * An incident is a postmortem capsule: a recorded operational event with a
- * lifecycle and optional linked receipts (the memories that are its evidence).
- * The `incidents` table is the source of truth: an incident stays `open`
- * regardless of memory decay. A memory row still mirrors the incident for
- * recall surfaces but is NOT canonical — memory_id is NULLABLE with ON DELETE
- * SET NULL so forget/consolidate/archive gracefully orphans the incident row.
- *
- * Lifecycle: open -> resolved (a resolution was recorded; the incident stays on
- * record with resolution_text + resolved_at) or open|resolved -> closed
- * (retired with closed_at). This is NOT decision's supersede: there is no
- * superseded_by self-FK, no supersede CAS, and no supersede trigger.
- *
- * Tenant scoping: every helper requires tenantId. BEFORE INSERT/UPDATE triggers
- * enforce incidents.tenant_id == the referenced memory's tenant_id. Mirrors the
- * v30 decisions pattern (src/decisions.ts).
- *
- * Dual-write atomicity: `saveIncident` writes the memory + incidents row inside
- * writeEntry's SAVEPOINT 'write_entry' (store.ts) via the afterWrite hook, so a
- * failure in any step rolls all of them back. Pattern matches saveDecision.
- *
- * linked_memory_ids ("linked receipts"): a JSON-encoded array of memory ids on
- * the row, default `[]`. On save, every id must exist in the SAME tenant; a
- * cross-tenant or nonexistent id is rejected (throw) before the insert.
- */
-import { BadRequestError, ConflictError, NotFoundError } from './api-errors.js';
-import { openHippoDb, closeHippoDb } from './db.js';
-import { writeEntry } from './store/entry-writes.js';
-import { assertTenantId } from './tenant.js';
-import { createMemory, Layer } from './memory.js';
-import { appendAuditEvent } from './audit.js';
-import { objectHalfLifeDays } from './half-life-migration.js';
-import { keysetAfter } from './keyset.js';
-export const VALID_INCIDENT_STATES = new Set([
-    'open',
-    'resolved',
-    'closed',
-]);
-function parseLinkedMemoryIds(raw) {
-    try {
-        // SAFETY: JSON.parse output is arbitrary; narrowed by Array.isArray plus
-        // the per-element string check below before use as string[].
-        const parsed = JSON.parse(raw);
-        if (Array.isArray(parsed)) {
-            return parsed.filter((x) => typeof x === 'string');
-        }
-        return [];
-    }
-    catch {
-        // A malformed list column reads as empty instead of failing the incident read.
-        return [];
-    }
-}
-function rowToIncident(row) {
-    return {
-        id: row.id,
-        memoryId: row.memory_id,
-        tenantId: row.tenant_id,
-        incidentText: row.incident_text,
-        context: row.context,
-        // SAFETY: status is DB-constrained to VALID_INCIDENT_STATES; this module
-        // is the only writer and always inserts one of those literal strings.
-        status: row.status,
-        resolutionText: row.resolution_text,
-        resolvedAt: row.resolved_at,
-        closedAt: row.closed_at,
-        linkedMemoryIds: parseLinkedMemoryIds(row.linked_memory_ids),
-        createdAt: row.created_at,
-    };
-}
-const INCIDENT_COLS = `
-  id, memory_id, tenant_id, incident_text, context, status,
-  resolution_text, resolved_at, closed_at, linked_memory_ids, created_at
-`;
-// ---------------------------------------------------------------------------
-// Public API
-// ---------------------------------------------------------------------------
-// Validate every linked receipt BEFORE inserting the row. Each must be a
-// memory in the SAME tenant; a cross-tenant or nonexistent id rejects the
-// whole write rather than recording an unverifiable receipt.
-function validateLinkedMemoryIds(db, tenantId, linkInput) {
-    const validated = [];
-    for (const linkId of linkInput) {
-        // SAFETY: row shape matches the single `id` column named in the SELECT above.
-        const exists = db.prepare(`SELECT id FROM memories WHERE id = ? AND tenant_id = ?`).get(linkId, tenantId);
-        if (!exists) {
-            throw new NotFoundError(`saveIncident: linked memory ${linkId} not found for tenant ${tenantId}`);
-        }
-        validated.push(linkId);
-    }
-    return validated;
-}
-/** The afterWrite body: link validation, INSERT, reload, open audit, all in one SAVEPOINT. */
-function writeIncidentRow(db, memoryId, tenantId, opts, actor, now) {
-    const validated = validateLinkedMemoryIds(db, tenantId, opts.linkedMemoryIds ?? []);
-    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, opts.incidentText, opts.context ?? null, JSON.stringify(validated), now);
-    const incidentId = Number(result.lastInsertRowid ?? 0);
-    // SAFETY: row's shape matches the columns named in INCIDENT_COLS above.
-    const row = db.prepare(`SELECT ${INCIDENT_COLS} FROM incidents WHERE id = ?`)
-        .get(incidentId);
-    if (!row)
-        throw new Error('saveIncident: failed to reload saved incident row');
-    // GDPR-light metadata: id + flag only, no incident_text.
-    appendAuditEvent(db, {
-        tenantId,
-        actor,
-        op: 'incident_open',
-        targetId: String(incidentId),
-        metadata: {
-            incident_id: incidentId,
-            has_context: opts.context !== undefined && opts.context !== null && opts.context !== '',
-            linked_memory_count: validated.length,
-        },
-    });
-    return row;
-}
-/**
- * Create an incident. Writes the memory mirror + the incidents row atomically
- * inside writeEntry's SAVEPOINT 'write_entry'.
- *
- * The memory mirror: tags ['incident', ...extraTags], source 'incident',
- * confidence 'verified', the half-life objectHalfLifeDays picks, content =
- * "<text>\n\nContext: <context>" when context is given.
- *
- * linked_memory_ids are validated BEFORE insert: each must exist in the SAME
- * tenant. A cross-tenant or nonexistent id throws and rolls back the whole
- * write. The validated ids are stored as JSON.stringify(validated).
- */
-export function saveIncident(hippoRoot, tenantId, opts, actor = 'cli') {
-    assertTenantId('saveIncident', tenantId);
-    if (!opts.incidentText)
-        throw new BadRequestError('saveIncident: incidentText is required');
-    const now = new Date().toISOString();
-    const content = opts.context
-        ? `${opts.incidentText}\n\nContext: ${opts.context}`
-        : opts.incidentText;
-    const tags = ['incident', ...(opts.extraTags ?? [])];
-    const mem = createMemory(content, {
-        tags,
-        layer: Layer.Semantic,
-        confidence: 'verified',
-        source: 'incident',
-        baseHalfLifeDays: objectHalfLifeDays(hippoRoot),
-        tenantId,
-    });
-    // Populated inside afterWrite so the linked-id validation, the INSERT, and the
-    // memory write all share one SAVEPOINT.
-    let savedRow;
-    writeEntry(hippoRoot, mem, {
-        actor,
-        afterWrite: (db, memoryId) => {
-            savedRow = writeIncidentRow(db, memoryId, tenantId, opts, actor, now);
-        },
-    });
-    if (!savedRow) {
-        // Unreachable unless afterWrite threw first; defensive.
-        throw new Error('saveIncident: afterWrite did not populate the row');
-    }
-    return rowToIncident(savedRow);
-}
-/**
- * Resolve an open incident (open -> resolved). Records resolution_text +
- * resolved_at; the incident stays on record. CAS guard: WHERE status='open';
- * 0 changes distinguishes not-found from not-open so callers surface the right
- * error. Emits incident_resolve.
- */
-export function resolveIncident(hippoRoot, tenantId, id, resolutionText, actor = 'cli') {
-    assertTenantId('resolveIncident', tenantId);
-    if (!resolutionText || !resolutionText.trim()) {
-        throw new BadRequestError('resolveIncident: resolutionText is required (non-empty)');
-    }
-    const now = new Date().toISOString();
-    const db = openHippoDb(hippoRoot);
-    try {
-        db.exec('BEGIN IMMEDIATE');
-        try {
-            const updateResult = db.prepare(`
-        UPDATE incidents
-        SET status = 'resolved', resolution_text = ?, resolved_at = ?
-        WHERE id = ? AND tenant_id = ? AND status = 'open'
-      `).run(resolutionText, now, id, tenantId);
-            if (updateResult.changes === 0) {
-                // SAFETY: row shape matches the single `status` column named in the SELECT above.
-                const existing = db.prepare(`SELECT status FROM incidents WHERE id = ? AND tenant_id = ?`).get(id, tenantId);
-                if (!existing) {
-                    throw new NotFoundError(`resolveIncident: incident ${id} not found for tenant ${tenantId}`);
-                }
-                throw new ConflictError(`resolveIncident: incident ${id} is not open (status='${existing.status}'); only open incidents can be resolved.`);
-            }
-            // SAFETY: row's shape matches the columns named in INCIDENT_COLS above.
-            const row = db.prepare(`SELECT ${INCIDENT_COLS} FROM incidents WHERE id = ? AND tenant_id = ?`)
-                .get(id, tenantId);
-            if (!row)
-                throw new NotFoundError(`resolveIncident: incident ${id} not found after UPDATE`);
-            appendAuditEvent(db, {
-                tenantId,
-                actor,
-                op: 'incident_resolve',
-                targetId: String(id),
-                metadata: { incident_id: id },
-            });
-            db.exec('COMMIT');
-            return rowToIncident(row);
-        }
-        catch (e) {
-            try {
-                db.exec('ROLLBACK');
-            }
-            catch {
-                // Ignore rollback failures — the throw below is what matters.
-            }
-            throw e;
-        }
-    }
-    finally {
-        closeHippoDb(db);
-    }
-}
-/**
- * Close (retire) an incident from open or resolved (open|resolved -> closed).
- * Updates closed_at only; the memory mirror is not mutated. CAS guard: WHERE
- * status IN ('open','resolved'); 0 changes distinguishes not-found from
- * wrong-state. Emits incident_close.
- */
-export function closeIncident(hippoRoot, tenantId, id, actor = 'cli') {
-    assertTenantId('closeIncident', tenantId);
-    const now = new Date().toISOString();
-    const db = openHippoDb(hippoRoot);
-    try {
-        db.exec('BEGIN IMMEDIATE');
-        try {
-            const updateResult = db.prepare(`
-        UPDATE incidents
-        SET status = 'closed', closed_at = ?
-        WHERE id = ? AND tenant_id = ? AND status IN ('open', 'resolved')
-      `).run(now, id, tenantId);
-            if (updateResult.changes === 0) {
-                // SAFETY: row shape matches the single `status` column named in the SELECT above.
-                const existing = db.prepare(`SELECT status FROM incidents WHERE id = ? AND tenant_id = ?`).get(id, tenantId);
-                if (!existing) {
-                    throw new NotFoundError(`closeIncident: incident ${id} not found for tenant ${tenantId}`);
-                }
-                throw new ConflictError(`closeIncident: incident ${id} is already closed (status='${existing.status}'); only open or resolved incidents can be closed.`);
-            }
-            // SAFETY: row's shape matches the columns named in INCIDENT_COLS above.
-            const row = db.prepare(`SELECT ${INCIDENT_COLS} FROM incidents WHERE id = ? AND tenant_id = ?`)
-                .get(id, tenantId);
-            if (!row)
-                throw new NotFoundError(`closeIncident: incident ${id} not found after UPDATE`);
-            appendAuditEvent(db, {
-                tenantId,
-                actor,
-                op: 'incident_close',
-                targetId: String(id),
-                metadata: { incident_id: id },
-            });
-            db.exec('COMMIT');
-            return rowToIncident(row);
-        }
-        catch (e) {
-            try {
-                db.exec('ROLLBACK');
-            }
-            catch {
-                // Ignore rollback failures — the throw below is what matters.
-            }
-            throw e;
-        }
-    }
-    finally {
-        closeHippoDb(db);
-    }
-}
-export function loadIncidentById(hippoRoot, tenantId, id) {
-    assertTenantId('loadIncidentById', tenantId);
-    const db = openHippoDb(hippoRoot);
-    try {
-        // SAFETY: row's shape matches the columns named in INCIDENT_COLS above.
-        const row = db.prepare(`SELECT ${INCIDENT_COLS} FROM incidents WHERE id = ? AND tenant_id = ?`)
-            .get(id, tenantId);
-        return row ? rowToIncident(row) : null;
-    }
-    finally {
-        closeHippoDb(db);
-    }
-}
-export function loadIncidents(hippoRoot, tenantId, opts = {}) {
-    assertTenantId('loadIncidents', tenantId);
-    const limit = opts.limit ?? 100;
-    const after = keysetAfter('created_at', 'id', opts.after);
-    const db = openHippoDb(hippoRoot);
-    try {
-        let rows;
-        if (opts.status) {
-            if (!VALID_INCIDENT_STATES.has(opts.status)) {
-                throw new BadRequestError(`loadIncidents: status must be one of ${Array.from(VALID_INCIDENT_STATES).join('|')}; got ${opts.status}`);
-            }
-            // SAFETY: rows' shape matches the columns named in INCIDENT_COLS above.
-            rows = db.prepare(`
-        SELECT ${INCIDENT_COLS} FROM incidents
-        WHERE tenant_id = ? AND status = ?${after.sql}
-        ORDER BY created_at DESC, id DESC
-        LIMIT ?
-      `).all(tenantId, opts.status, ...after.params, limit);
-        }
-        else {
-            // SAFETY: rows' shape matches the columns named in INCIDENT_COLS above.
-            rows = db.prepare(`
-        SELECT ${INCIDENT_COLS} FROM incidents
-        WHERE tenant_id = ?${after.sql}
-        ORDER BY created_at DESC, id DESC
-        LIMIT ?
-      `).all(tenantId, ...after.params, limit);
-        }
-        return rows.map(rowToIncident);
-    }
-    finally {
-        closeHippoDb(db);
-    }
-}
-export function loadOpenIncidents(hippoRoot, tenantId, opts = {}) {
-    return loadIncidents(hippoRoot, tenantId, { status: 'open', limit: opts.limit });
-}
-/**
- * Resolve a memory id to the table id of the OPEN incident backed by that
- * memory, or null when the memory has no open incident row. Extracted so a
- * memory-id-based lookup is unit-testable at the store layer (mirror of
- * resolveActiveDecisionIdByMemory).
- */
-export function resolveActiveIncidentIdByMemory(hippoRoot, tenantId, memoryId) {
-    assertTenantId('resolveActiveIncidentIdByMemory', tenantId);
-    const db = openHippoDb(hippoRoot);
-    try {
-        // SAFETY: row shape matches the single `id` column named in the SELECT above.
-        const row = db.prepare(`SELECT id FROM incidents WHERE memory_id = ? AND tenant_id = ? AND status = 'open' ORDER BY id DESC LIMIT 1`).get(memoryId, tenantId);
-        return row ? row.id : null;
-    }
-    finally {
-        closeHippoDb(db);
-    }
-}
-//# sourceMappingURL=incidents.js.map

package/dist/instruction-detect.js

@@ -1,27 +0,0 @@
-/** Prompt-injection detection for untrusted memory content. Same shape as secret-detect.ts; leaf module, no store/api/shared imports. */
-const INSTRUCTION_PATTERNS = [
-    { name: 'override-instructions', re: /\b(?:ignore|disregard|forget)\b[^.\n]{0,40}\b(?:previous|prior|above)\b[^.\n]{0,40}\binstructions?\b/i },
-    { name: 'role-reassignment', re: /\b(?:you are now|act as|pretend to be)\b[^.\n]{0,40}\b(?:an?\s+)?(?:ai|assistant|agent|system)\b/i },
-    { name: 'chat-role-markup', re: /<\|im_start\|>|<\|system\|>|\[INST\]|<\/?system>|###\s*system\s*:/i },
-    { name: 'system-prompt-reference', re: /\b(?:(?:override|ignore|bypass|replace|reveal)\b[^.\n]{0,40}\b(?:system prompt|developer message)|(?:system prompt|developer message)\b[^.\n]{0,40}\b(?:override|ignore|bypass|replace|reveal))\b/i },
-    // "always"/"never" alone (ordinary PR prose) doesn't flag without an agent-facing target nearby too.
-    { name: 'standing-order', re: /\b(?:from now on|whenever you|always|never)\b[^.\n]{0,50}\b(?:you must|(?:the ai|the assistant|the agent|claude|copilot)\s+(?:must|should|will)\b)/i },
-    { name: 'concealment', re: /\b(?:do not|never|don't)\b[^.\n]{0,40}\b(?:tell|mention|reveal)\b[^.\n]{0,40}\bthe user\b/i },
-    { name: 'remote-script-exec', re: /\b(?:curl|wget)\b[^\n|]{0,80}\|\s*(?:sudo\s+)?(?:sh|bash|zsh)\b|\biex\s*\(\s*(?:iwr|invoke-webrequest|new-object\s+net\.webclient)/i },
-    { name: 'exfiltration', re: /\b(?:send|post|upload|exfiltrate)\b[^.\n]{0,40}\b(?:secrets?|tokens?|api[- ]?keys?|credentials?|env(?:ironment)? variables?)\b/i },
-    { name: 'unicode-tag-chars', re: /[\u{E0000}-\u{E007F}]/u },
-];
-// A stray zero-width char has legitimate uses (ZWJ); only a run of 3+ adjacent ones reads as smuggling.
-const ZERO_WIDTH_RUN_RE = /[\u200B-\u200F\u2060-\u2064]{3,}/;
-export function detectInstruction(content) {
-    for (const { name, re } of INSTRUCTION_PATTERNS) {
-        if (re.test(content)) {
-            return { flagged: true, reason: `pattern:${name}` };
-        }
-    }
-    if (ZERO_WIDTH_RUN_RE.test(content)) {
-        return { flagged: true, reason: 'pattern:zero-width-smuggling' };
-    }
-    return { flagged: false, reason: null };
-}
-//# sourceMappingURL=instruction-detect.js.map

package/dist/json.d.ts

@@ -1,7 +0,0 @@
-export type JsonValue = string | number | boolean | null | JsonValue[] | {
-    [key: string]: JsonValue;
-};
-export declare function isJsonString(value: JsonValue | undefined): value is string;
-/** Windows PowerShell 5.1 saves JSON with a UTF-8 byte order mark that JSON.parse rejects, so one leading mark is dropped. */
-export declare function readJsonFile(file: string): JsonValue;
-//# sourceMappingURL=json.d.ts.map

package/dist/json.js

@@ -1,11 +0,0 @@
-// Leaf module: the one value space JSON.parse can produce, so boundary guards narrow a shared type.
-import * as fs from 'fs';
-export function isJsonString(value) {
-    return typeof value === 'string';
-}
-/** Windows PowerShell 5.1 saves JSON with a UTF-8 byte order mark that JSON.parse rejects, so one leading mark is dropped. */
-export function readJsonFile(file) {
-    const text = fs.readFileSync(file, 'utf8');
-    return JSON.parse(text.codePointAt(0) === 0xfeff ? text.slice(1) : text);
-}
-//# sourceMappingURL=json.js.map

package/dist/ledger-db.d.ts

@@ -1,10 +0,0 @@
-import { openHippoDb } from './db.js';
-export interface LedgerRootOpts {
-    /** The store serves many people, so the global store of the user running it belongs to none of them. */
-    readonly sharedStore?: boolean;
-}
-/** `hippoRoot` when it holds a store, else the global store (the prompt hook fires where no local one exists), else null. */
-export declare function ledgerRoot(hippoRoot: string, opts?: LedgerRootOpts): string | null;
-/** Runs `fn` on ledgerRoot's store. Best-effort: undefined on any failure, because a ledger failure must not break context or recall. */
-export declare function withLedgerDb<T>(hippoRoot: string, fn: (db: ReturnType<typeof openHippoDb>) => T, opts?: LedgerRootOpts): T | undefined;
-//# sourceMappingURL=ledger-db.d.ts.map

package/dist/ledger-db.js

@@ -1,42 +0,0 @@
-// The store the token ledger writes to for a caller's root; context, recall and the session hooks share it.
-import { closeHippoDb, isSqliteBusy, noteStoreBusy, openHippoDb } from './db.js';
-import { getGlobalRoot } from './shared.js';
-import { isInitialized } from './store/open.js';
-/** `hippoRoot` when it holds a store, else the global store (the prompt hook fires where no local one exists), else null. */
-export function ledgerRoot(hippoRoot, opts) {
-    if (isInitialized(hippoRoot))
-        return hippoRoot;
-    if (opts?.sharedStore)
-        return null;
-    const globalRoot = getGlobalRoot();
-    return isInitialized(globalRoot) ? globalRoot : null;
-}
-/** Runs `fn` on ledgerRoot's store. Best-effort: undefined on any failure, because a ledger failure must not break context or recall. */
-export function withLedgerDb(hippoRoot, fn, opts) {
-    let root = null;
-    try {
-        root = ledgerRoot(hippoRoot, opts);
-    }
-    catch {
-        // An unreadable store root means no ledger write; the ledger must never break context or recall.
-        return undefined;
-    }
-    if (root === null)
-        return undefined;
-    let db;
-    try {
-        db = openHippoDb(root);
-        return fn(db);
-    }
-    catch (error) {
-        // Best effort, but a busy store is the one failure an operator can act on, so it warns once.
-        if (isSqliteBusy(error))
-            noteStoreBusy('token ledger row skipped');
-        return undefined;
-    }
-    finally {
-        if (db)
-            closeHippoDb(db);
-    }
-}
-//# sourceMappingURL=ledger-db.js.map