hippo-memory 1.69.0 → 1.71.0

package/dist/customer-notes.js

@@ -1,336 +0,0 @@
-/**
- * customer_note first-class object.
- *
- * A `customer_note` is a discrete note recorded against an account/customer entity:
- * a `note` body scoped to a `customer`, evolving via the supersede delta lifecycle.
- * Entity-scoping is a free-form `customer` column (the `entities` table is unbuilt,
- * so an FK is deferred). Unlike project_brief's one-summary-per-repo,
- * a customer accrues MANY discrete notes over time, each with its own supersede chain
- * (correct a note -> a new version preserving history; close retires it).
- *
- * Reuses the project_brief/skill supersede machinery verbatim (superseded_by self-FK
- * + CAS + INSERT-preflight + server-derived version + change_summary + supersede
- * tenant-match trigger). It has NO assembler/renderer (the simplest first-class object): the
- * contribution is purely the entity-scoping dimension.
- *
- * The `customer_notes` table is the source of truth (survives memory decay); the
- * memory mirror is for recall. memory_id is NULLABLE with ON DELETE SET NULL.
- *
- * Lifecycle: active -> superseded (a corrected version) or active -> closed (retired).
- */
-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 { markGraphDirty, removeGraphEntitiesForObject } from './graph/write.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_NOTE_STATES = new Set([
-    'active',
-    'superseded',
-    'closed',
-]);
-/** Field caps (untrusted at the HTTP/SDK boundary). note is a body, so a larger cap
- *  than the 4096 short-field convention. */
-export const MAX_CUSTOMER_LEN = 256;
-export const MAX_NOTE_LEN = 8192;
-export const MAX_CHANGE_SUMMARY_LEN = 4096;
-// ---------------------------------------------------------------------------
-// Validation
-// ---------------------------------------------------------------------------
-/**
- * Validate + normalise note fields. `customer` is trimmed and MUST be a single line
- * (no newlines): it becomes a `customer:<lc>` recall tag AND an identifier. `note` is
- * kept verbatim (operator content) but capped. Returns the normalised customer.
- */
-function validateNoteFields(customer, note, changeSummary) {
-    const normalizedCustomer = (customer ?? '').trim();
-    if (normalizedCustomer.length === 0)
-        throw new BadRequestError('saveCustomerNote: customer is required');
-    if (/[\r\n]/.test(normalizedCustomer)) {
-        throw new BadRequestError('saveCustomerNote: customer must be a single line (no newlines)');
-    }
-    if (normalizedCustomer.length > MAX_CUSTOMER_LEN) {
-        throw new BadRequestError(`saveCustomerNote: customer exceeds the ${MAX_CUSTOMER_LEN}-char cap`);
-    }
-    if (!note || note.trim().length === 0) {
-        throw new BadRequestError('saveCustomerNote: note is required');
-    }
-    if (note.length > MAX_NOTE_LEN) {
-        throw new BadRequestError(`saveCustomerNote: note exceeds the ${MAX_NOTE_LEN}-char cap`);
-    }
-    if (changeSummary !== undefined && changeSummary.length > MAX_CHANGE_SUMMARY_LEN) {
-        throw new BadRequestError(`saveCustomerNote: changeSummary exceeds the ${MAX_CHANGE_SUMMARY_LEN}-char cap`);
-    }
-    return { customer: normalizedCustomer };
-}
-function rowToCustomerNote(row) {
-    return {
-        id: row.id,
-        memoryId: row.memory_id,
-        tenantId: row.tenant_id,
-        customer: row.customer,
-        note: row.note,
-        version: row.version,
-        // SAFETY: row.status is DB-constrained to NoteStatus values; every INSERT/
-        // UPDATE in this file writes only the literal 'active' | 'superseded' | 'closed'.
-        status: row.status,
-        supersededBy: row.superseded_by,
-        supersededAt: row.superseded_at,
-        changeSummary: row.change_summary,
-        closedAt: row.closed_at,
-        createdAt: row.created_at,
-    };
-}
-const NOTE_COLS = `
-  id, memory_id, tenant_id, customer, note, version, status,
-  superseded_by, superseded_at, change_summary, closed_at, created_at
-`;
-/** Recall-surface content for the memory mirror: customer + note. Named (mirrors
- *  buildBriefContent) so the recall surface is deterministic + unit-testable. */
-function buildNoteContent(customer, note) {
-    return `${customer}\n\n${note}`;
-}
-// Preflight the supersede target BEFORE inserting the new row (so the new
-// autoincrement id can never be its own supersede target); read the
-// predecessor version in the same SELECT for server-derived versioning.
-function preflightNoteSupersede(db, tenantId, supersedesId) {
-    // SAFETY: SELECT projects exactly status, version; .get() returns that
-    // shape for the matching row, or undefined when no note/tenant pair matches.
-    const pred = db.prepare(`SELECT status, version FROM customer_notes WHERE id = ? AND tenant_id = ?`).get(supersedesId, tenantId);
-    if (!pred) {
-        throw new NotFoundError(`saveCustomerNote: note ${supersedesId} to supersede not found for tenant ${tenantId}`);
-    }
-    if (pred.status !== 'active') {
-        throw new ConflictError(`saveCustomerNote: note ${supersedesId} is not active (status='${pred.status}'); only active notes can be superseded.`);
-    }
-    return pred.version + 1;
-}
-function insertNoteRow(db, memoryId, w, version) {
-    const result = db.prepare(`
-    INSERT INTO customer_notes(
-      memory_id, tenant_id, customer, note, version,
-      status, superseded_by, superseded_at, change_summary, closed_at, created_at
-    ) VALUES (?, ?, ?, ?, ?, 'active', NULL, NULL, ?, NULL, ?)
-  `).run(memoryId, w.tenantId, w.customer, w.note, version, w.changeSummary, w.now);
-    return Number(result.lastInsertRowid ?? 0);
-}
-function supersedeNoteRow(db, w, supersedesId, noteId, version) {
-    const sup = db.prepare(`
-    UPDATE customer_notes
-    SET status = 'superseded', superseded_by = ?, superseded_at = ?
-    WHERE id = ? AND tenant_id = ? AND status = 'active' AND id != ?
-  `).run(noteId, w.now, supersedesId, w.tenantId, noteId);
-    if (sup.changes === 0) {
-        throw new ConflictError(`saveCustomerNote: note ${supersedesId} could not be superseded (no longer active or self-reference).`);
-    }
-    appendAuditEvent(db, {
-        tenantId: w.tenantId,
-        actor: w.actor,
-        op: 'customer_note_supersede',
-        targetId: String(supersedesId),
-        metadata: {
-            note_id: supersedesId,
-            superseded_by: noteId,
-            new_version: version,
-        },
-    });
-}
-/** The afterWrite body: preflight, INSERT, supersede, reload, create audit, all in one SAVEPOINT. */
-function writeNoteRow(db, memoryId, w) {
-    const version = w.supersedesId !== undefined ? preflightNoteSupersede(db, w.tenantId, w.supersedesId) : 1;
-    const noteId = insertNoteRow(db, memoryId, w, version);
-    if (w.supersedesId !== undefined)
-        supersedeNoteRow(db, w, w.supersedesId, noteId, version);
-    // SAFETY: SELECT ${NOTE_COLS} projects exactly the CustomerNoteRow columns;
-    // .get() returns that row, or undefined only if the just-inserted id can't
-    // be found.
-    const row = db.prepare(`SELECT ${NOTE_COLS} FROM customer_notes WHERE id = ?`)
-        .get(noteId);
-    if (!row)
-        throw new Error('saveCustomerNote: failed to reload saved note row');
-    // GDPR-light metadata: ids + flags only, no note text.
-    appendAuditEvent(db, {
-        tenantId: w.tenantId,
-        actor: w.actor,
-        op: 'customer_note_create',
-        targetId: String(noteId),
-        metadata: {
-            note_id: noteId,
-            customer: w.customer,
-            version,
-        },
-    });
-    return row;
-}
-/**
- * Create a customer_note (or a new version that supersedes an existing one). Writes
- * the memory mirror + the customer_notes row atomically inside writeEntry's SAVEPOINT.
- * When supersedesNoteId is given, the referenced ACTIVE row is preflighted (status +
- * version) BEFORE the INSERT, then CAS-UPDATEd -> superseded in the same SAVEPOINT;
- * the new version = predecessor.version + 1 (server-derived).
- *
- * The memory mirror carries a `customer:<lc>` tag (in addition to ['customer_note']
- * + caller extraTags) so scope-aware recall treats the note as entity-local. There is
- * no self-recursion path (customer_note has no receipt-query/refresh).
- */
-export function saveCustomerNote(hippoRoot, tenantId, opts, actor = 'cli') {
-    assertTenantId('saveCustomerNote', tenantId);
-    const { customer } = validateNoteFields(opts.customer, opts.note, opts.changeSummary);
-    const isSupersede = opts.supersedesNoteId !== undefined;
-    const changeSummary = isSupersede ? (opts.changeSummary ?? null) : null;
-    const now = new Date().toISOString();
-    const content = buildNoteContent(customer, opts.note);
-    const tags = ['customer_note', `customer:${customer.toLowerCase()}`, ...(opts.extraTags ?? [])];
-    const mem = createMemory(content, {
-        tags,
-        layer: Layer.Semantic,
-        confidence: 'verified',
-        source: 'customer_note',
-        baseHalfLifeDays: objectHalfLifeDays(hippoRoot),
-        tenantId,
-    });
-    const w = {
-        tenantId, actor, customer, note: opts.note, changeSummary, supersedesId: opts.supersedesNoteId, now,
-    };
-    let savedRow;
-    writeEntry(hippoRoot, mem, {
-        actor,
-        afterWrite: (db, memoryId) => {
-            savedRow = writeNoteRow(db, memoryId, w);
-        },
-        afterCommit: () => markGraphDirty(hippoRoot, tenantId, mem.id),
-    });
-    if (!savedRow) {
-        throw new Error('saveCustomerNote: afterWrite did not populate the row');
-    }
-    return rowToCustomerNote(savedRow);
-}
-/**
- * Close (retire) an active note. CAS guard WHERE status='active'; 0 changes
- * distinguishes not-found from not-active. A superseded row is terminal.
- */
-export function closeCustomerNote(hippoRoot, tenantId, id, actor = 'cli') {
-    assertTenantId('closeCustomerNote', tenantId);
-    const now = new Date().toISOString();
-    const db = openHippoDb(hippoRoot);
-    try {
-        db.exec('BEGIN IMMEDIATE');
-        try {
-            const updateResult = db.prepare(`
-        UPDATE customer_notes
-        SET status = 'closed', closed_at = ?
-        WHERE id = ? AND tenant_id = ? AND status = 'active'
-      `).run(now, id, tenantId);
-            if (updateResult.changes === 0) {
-                // SAFETY: SELECT projects exactly the status column; .get() returns that
-                // shape, or undefined when the id/tenant pair doesn't exist.
-                const existing = db.prepare(`SELECT status FROM customer_notes WHERE id = ? AND tenant_id = ?`).get(id, tenantId);
-                if (!existing) {
-                    throw new NotFoundError(`closeCustomerNote: note ${id} not found for tenant ${tenantId}`);
-                }
-                throw new ConflictError(`closeCustomerNote: note ${id} is not active (status='${existing.status}'); only active notes can be closed.`);
-            }
-            // SAFETY: SELECT ${NOTE_COLS} projects exactly the CustomerNoteRow columns;
-            // .get() returns that row for the just-updated id, or undefined only in an
-            // impossible race since the UPDATE above already matched it.
-            const row = db.prepare(`SELECT ${NOTE_COLS} FROM customer_notes WHERE id = ? AND tenant_id = ?`)
-                .get(id, tenantId);
-            if (!row)
-                throw new NotFoundError(`closeCustomerNote: note ${id} not found after UPDATE`);
-            appendAuditEvent(db, {
-                tenantId,
-                actor,
-                op: 'customer_note_close',
-                targetId: String(id),
-                metadata: { note_id: id },
-            });
-            db.exec('COMMIT');
-            const closed = rowToCustomerNote(row);
-            // Closing removes the object from the graph. Remove its rows DIRECTLY (deterministic),
-            // not only via an enqueued rebuild whose queue item is lost if the mirror is later
-            // forgotten (the queue row cascade-deletes with the memory), which would leave the closed
-            // object stale and could block that forget. Still enqueue when a mirror exists
-            // so a concurrent rebuild re-derives consistently (harmless if it also runs).
-            removeGraphEntitiesForObject(hippoRoot, tenantId, 'customer', closed.id);
-            if (closed.memoryId) {
-                markGraphDirty(hippoRoot, tenantId, closed.memoryId);
-            }
-            return closed;
-        }
-        catch (e) {
-            try {
-                db.exec('ROLLBACK');
-            }
-            catch {
-                // Ignore rollback failures — the throw below is what matters.
-            }
-            throw e;
-        }
-    }
-    finally {
-        closeHippoDb(db);
-    }
-}
-export function loadCustomerNoteById(hippoRoot, tenantId, id) {
-    assertTenantId('loadCustomerNoteById', tenantId);
-    const db = openHippoDb(hippoRoot);
-    try {
-        // SAFETY: SELECT ${NOTE_COLS} projects exactly the CustomerNoteRow columns;
-        // .get() returns that row, or undefined when the id/tenant pair doesn't exist.
-        const row = db.prepare(`SELECT ${NOTE_COLS} FROM customer_notes WHERE id = ? AND tenant_id = ?`)
-            .get(id, tenantId);
-        return row ? rowToCustomerNote(row) : null;
-    }
-    finally {
-        closeHippoDb(db);
-    }
-}
-export function loadCustomerNotes(hippoRoot, tenantId, opts = {}) {
-    assertTenantId('loadCustomerNotes', tenantId);
-    const limit = opts.limit ?? 100;
-    const after = keysetAfter('created_at', 'id', opts.after);
-    if (opts.status && !VALID_NOTE_STATES.has(opts.status)) {
-        throw new BadRequestError(`loadCustomerNotes: status must be one of ${Array.from(VALID_NOTE_STATES).join('|')}; got ${opts.status}`);
-    }
-    const db = openHippoDb(hippoRoot);
-    try {
-        const clauses = ['tenant_id = ?'];
-        const params = [tenantId];
-        if (opts.status) {
-            clauses.push('status = ?');
-            params.push(opts.status);
-        }
-        if (opts.customer) {
-            clauses.push('customer = ?');
-            params.push(opts.customer);
-        }
-        params.push(...after.params, limit);
-        // SAFETY: SELECT ${NOTE_COLS} projects exactly the CustomerNoteRow columns
-        // regardless of the dynamic WHERE clause built above; .all() returns rows
-        // in that shape.
-        const rows = db.prepare(`
-      SELECT ${NOTE_COLS} FROM customer_notes
-      WHERE ${clauses.join(' AND ')}${after.sql}
-      ORDER BY created_at DESC, id DESC
-      LIMIT ?
-    `).all(...params);
-        return rows.map(rowToCustomerNote);
-    }
-    finally {
-        closeHippoDb(db);
-    }
-}
-/**
- * All ACTIVE notes for a customer, newest first. Returns a LIST (a customer accrues
- * MANY notes) - this deliberately DIVERGES from project_brief's
- * loadActiveBriefForRepo, which returns a single brief-or-null because a repo has one
- * evolving summary. A future caller cloning the project_brief shape by analogy must
- * not assume a single-return here; the plural name signals the list contract.
- */
-export function loadActiveNotesForCustomer(hippoRoot, tenantId, customer, opts = {}) {
-    return loadCustomerNotes(hippoRoot, tenantId, { customer, status: 'active', limit: opts.limit });
-}
-//# sourceMappingURL=customer-notes.js.map

package/dist/db.d.ts

@@ -1,9 +0,0 @@
-export type { DatabaseSyncLike } from './db/sqlite.js';
-export { isSqliteBusy, isStoreBusy, StoreBusyError, STORE_BUSY_MESSAGE, execWithBusyRetry, withWriteScope } from './db/busy.js';
-export { getSchemaVersion, getMeta, setMeta, isFtsAvailable } from './db/meta.js';
-export { countTableRows, pruneConsolidationRuns } from './db/tables.js';
-export { getCurrentSchemaVersion, IncompatibleBinaryError, ftsRowCounts, repairFtsDrift } from './db/migrate.js';
-export { getHippoDbPath, HOOK_DB_WAIT_MS, noteStoreBusy, withSharedStoreHandles, SERVER_DB_WAIT_MS, SLEEP_DB_WAIT_MS, scopedBusyWait, withSqliteBlocked, withSqliteAllowed, rethrowIfSqliteBlocked, OTHER_STORE_MARKER, openHippoDb, openHippoDbReadOnly, closeHippoDb, } from './db/open.js';
-export { RequestStores, runWithRequestStores, currentRequestStores, outsideRequestStores } from './db/request-stores.js';
-export { OtherStoreFolderError, SqliteBlockedError } from './db/sqlite-blocked.js';
-//# sourceMappingURL=db.d.ts.map

package/dist/db.js

@@ -1,8 +0,0 @@
-export { isSqliteBusy, isStoreBusy, StoreBusyError, STORE_BUSY_MESSAGE, execWithBusyRetry, withWriteScope } from './db/busy.js';
-export { getSchemaVersion, getMeta, setMeta, isFtsAvailable } from './db/meta.js';
-export { countTableRows, pruneConsolidationRuns } from './db/tables.js';
-export { getCurrentSchemaVersion, IncompatibleBinaryError, ftsRowCounts, repairFtsDrift } from './db/migrate.js';
-export { getHippoDbPath, HOOK_DB_WAIT_MS, noteStoreBusy, withSharedStoreHandles, SERVER_DB_WAIT_MS, SLEEP_DB_WAIT_MS, scopedBusyWait, withSqliteBlocked, withSqliteAllowed, rethrowIfSqliteBlocked, OTHER_STORE_MARKER, openHippoDb, openHippoDbReadOnly, closeHippoDb, } from './db/open.js';
-export { RequestStores, runWithRequestStores, currentRequestStores, outsideRequestStores } from './db/request-stores.js';
-export { OtherStoreFolderError, SqliteBlockedError } from './db/sqlite-blocked.js';
-//# sourceMappingURL=db.js.map

package/dist/decisions.d.ts

@@ -1,94 +0,0 @@
-/**
- * Decision first-class object.
- *
- * `hippo decide` used to write only a tagged memory (tags ['decision'], source
- * 'decision') with a 90-day half-life, so an in-force decision decayed out of
- * recall even though it was never reversed. The `decisions` table is now the
- * source of truth: a decision stays `active` regardless of memory decay, and
- * `hippo decide list --status active` is authoritative. A memory row still
- * mirrors the decision for recall surfaces but is NOT canonical — memory_id is
- * NULLABLE with ON DELETE SET NULL so forget/consolidate/archive gracefully
- * orphans the decision row.
- *
- * Lifecycle: active -> superseded (a newer decision replaces it; superseded_by
- * points to the successor) or active -> closed (retired with no successor).
- *
- * Tenant scoping: every helper requires tenantId. BEFORE INSERT/UPDATE triggers
- * enforce decisions.tenant_id == the referenced memory's tenant_id, and a
- * superseded_by same-tenant trigger makes cross-tenant supersession
- * unrepresentable. Mirrors the predictions pattern (src/predictions.ts).
- *
- * Dual-write atomicity: `saveDecision` writes the memory + decisions row (and,
- * when superseding, the old row's UPDATE) inside writeEntry's SAVEPOINT
- * 'write_entry' (store/entry-writes.ts) via the afterWrite hook, so a failure in any
- * step rolls all of them back. Pattern matches savePrediction (predictions.ts).
- */
-import { type KeysetPosition } from './keyset.js';
-export type DecisionStatus = 'active' | 'superseded' | 'closed';
-export declare const VALID_DECISION_STATES: ReadonlySet<DecisionStatus>;
-export interface Decision {
-    id: number;
-    /** Nullable: ON DELETE SET NULL lets memory deletion (forget / consolidate /
-     *  archive) proceed without breaking the decision row. */
-    memoryId: string | null;
-    tenantId: string;
-    decisionText: string;
-    context: string | null;
-    status: DecisionStatus;
-    /** Successor decision id; set only when status === 'superseded'. */
-    supersededBy: number | null;
-    supersededAt: string | null;
-    closedAt: string | null;
-    createdAt: string;
-}
-export interface SaveDecisionOpts {
-    decisionText: string;
-    context?: string;
-    /** Table id of an ACTIVE decision this one supersedes. The CLI resolves it
-     *  from a `--supersedes <memory-id>` via resolveActiveDecisionIdByMemory;
-     *  HTTP/SDK pass the table id directly. */
-    supersedesDecisionId?: number;
-    /** Extra memory tags merged after ['decision'] (the CLI passes path-context
-     *  tags; HTTP/SDK pass none). */
-    extraTags?: string[];
-}
-export interface ListDecisionsOpts {
-    status?: DecisionStatus;
-    limit?: number;
-    /** Resume after this row: the position the previous page ended on. */
-    after?: KeysetPosition;
-}
-/**
- * Create a decision. Writes the memory mirror + the decisions row atomically
- * inside writeEntry's SAVEPOINT 'write_entry'. When supersedesDecisionId is
- * given, the referenced ACTIVE row is UPDATEd -> superseded in the SAME
- * SAVEPOINT (CAS: WHERE status='active'; throws on changes===0 so a duplicate
- * supersede aborts the whole write rather than orphaning a successor).
- *
- * The memory mirror preserves the legacy `hippo decide` shape: tags
- * ['decision', ...extraTags], source 'decision', confidence 'verified',
- * the half-life objectHalfLifeDays picks, content = "<text>\n\nContext: <context>"
- * when context is given (so existing recall output is unchanged).
- */
-export declare function saveDecision(hippoRoot: string, tenantId: string, opts: SaveDecisionOpts, actor?: string): Decision;
-/**
- * Close (retire) an active decision with no successor. Updates the decisions
- * row only; the memory mirror is not mutated. CAS guard mirrors closePrediction
- * (predictions.ts): WHERE status='active'; 0 changes distinguishes not-found
- * from not-active so callers surface the right error.
- */
-export declare function closeDecision(hippoRoot: string, tenantId: string, id: number, actor?: string): Decision;
-export declare function loadDecisionById(hippoRoot: string, tenantId: string, id: number): Decision | null;
-export declare function loadDecisions(hippoRoot: string, tenantId: string, opts?: ListDecisionsOpts): Decision[];
-export declare function loadActiveDecisions(hippoRoot: string, tenantId: string, opts?: {
-    limit?: number;
-}): Decision[];
-/**
- * Resolve a `--supersedes <memory-id>` (the legacy CLI contract) to the table id
- * of the ACTIVE decision backed by that memory, or null when the memory has no
- * active decision row (a legacy pre-episode decision-tagged memory). Extracted
- * so the CLI's backward-compat path is unit-testable at the store layer without
- * exporting cmdDecide.
- */
-export declare function resolveActiveDecisionIdByMemory(hippoRoot: string, tenantId: string, memoryId: string): number | null;
-//# sourceMappingURL=decisions.d.ts.map