hippo-memory 1.68.0 → 1.70.0

package/dist/connectors/slack/idempotency.d.ts

@@ -1,17 +0,0 @@
-import type { DatabaseSyncLike } from '../../db.js';
-/**
- * Thrown by the ingest afterWrite hook when a concurrent worker has already
- * inserted slack_event_log for the same event_id. The throw propagates out of
- * writeEntry's SAVEPOINT, rolling back the duplicate memory write so exactly
- * one memory row exists per Slack event_id even under two-worker races.
- *
- * Caller maps to `{status: 'skipped_duplicate'}` at the public API boundary.
- */
-export declare class DuplicateEventError extends Error {
-    readonly eventId: string;
-    constructor(eventId: string);
-}
-export declare function hasSeenEvent(db: DatabaseSyncLike, eventId: string): boolean;
-export declare function markEventSeen(db: DatabaseSyncLike, eventId: string, memoryId: string | null): void;
-export declare function lookupMemoryByEvent(db: DatabaseSyncLike, eventId: string): string | null;
-//# sourceMappingURL=idempotency.d.ts.map

package/dist/connectors/slack/idempotency.js

@@ -1,31 +0,0 @@
-/**
- * Thrown by the ingest afterWrite hook when a concurrent worker has already
- * inserted slack_event_log for the same event_id. The throw propagates out of
- * writeEntry's SAVEPOINT, rolling back the duplicate memory write so exactly
- * one memory row exists per Slack event_id even under two-worker races.
- *
- * Caller maps to `{status: 'skipped_duplicate'}` at the public API boundary.
- */
-export class DuplicateEventError extends Error {
-    eventId;
-    constructor(eventId) {
-        super(`duplicate slack event_id: ${eventId}`);
-        this.name = 'DuplicateEventError';
-        this.eventId = eventId;
-    }
-}
-export function hasSeenEvent(db, eventId) {
-    const row = db.prepare(`SELECT 1 FROM slack_event_log WHERE event_id = ?`).get(eventId);
-    return !!row;
-}
-export function markEventSeen(db, eventId, memoryId) {
-    db.prepare(`INSERT OR IGNORE INTO slack_event_log (event_id, ingested_at, memory_id) VALUES (?, ?, ?)`)
-        .run(eventId, new Date().toISOString(), memoryId);
-}
-export function lookupMemoryByEvent(db, eventId) {
-    // SAFETY: query selects only `memory_id`, a nullable column, so a returned
-    // row has this shape; .get() returns undefined when no row matches.
-    const row = db.prepare(`SELECT memory_id FROM slack_event_log WHERE event_id = ?`).get(eventId);
-    return row?.memory_id ?? null;
-}
-//# sourceMappingURL=idempotency.js.map

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