hippo-memory 1.69.0 → 1.70.0

package/dist/processes.js

@@ -1,371 +0,0 @@
-/**
- * Process first-class object.
- *
- * A `process` is a "living process map": a named, ordered list of steps that
- * evolves over time. Unlike `incident` (open->resolved->closed, no supersede),
- * `process` REUSES the `decision` supersede path as its delta mechanism: a
- * process evolves by being superseded by a NEW VERSION that records what
- * changed (`change_summary`) and the full new state (`steps`), carrying a
- * server-derived `version` counter. The version chain (walk `superseded_by`)
- * is the changelog. Computed structural step-diffing is a deferred v2 read-side
- * feature; the row stores enough to reconstruct any delta
- * (predecessor.steps + successor.steps + change_summary).
- *
- * The `processes` table is the source of truth: a process stays `active`
- * regardless of memory decay. A memory row mirrors the process for recall but
- * is NOT canonical — memory_id is NULLABLE with ON DELETE SET NULL so
- * forget/consolidate/archive gracefully orphans the process row.
- *
- * Lifecycle: active -> superseded (a newer version replaces it; superseded_by
- * points to the successor) or active -> closed (retired with no successor;
- * only an active head closes).
- *
- * Tenant scoping: every helper requires tenantId. BEFORE INSERT/UPDATE triggers
- * enforce processes.tenant_id == the referenced memory's tenant_id, and a
- * superseded_by same-tenant trigger makes cross-tenant supersession
- * unrepresentable. Mirrors the v30 decisions pattern (src/decisions.ts).
- *
- * Dual-write atomicity: `saveProcess` writes the memory + processes row (and,
- * when superseding, the predecessor's UPDATE) inside writeEntry's SAVEPOINT
- * 'write_entry' via the afterWrite hook, so a failure in any step rolls all of
- * them back. Pattern matches saveDecision (decisions.ts).
- */
-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_PROCESS_STATES = new Set([
-    'active',
-    'superseded',
-    'closed',
-]);
-function isString(v) {
-    return typeof v === 'string';
-}
-/** DoS / abuse caps on the steps body (untrusted at the HTTP/SDK boundary). */
-export const MAX_PROCESS_STEPS = 200;
-export const MAX_PROCESS_STEP_LEN = 2000;
-// ---------------------------------------------------------------------------
-// steps validation (untrusted input)
-// ---------------------------------------------------------------------------
-/**
- * Validate + normalise the steps body. Returns the trimmed step strings
- * (trim-then-store, so ' x ' is stored as 'x'). Throws on a non-array, a
- * non-string / empty element, or a cap breach. Mirrors the incident DoS-cap
- * discipline.
- */
-export function validateProcessSteps(steps) {
-    if (!Array.isArray(steps)) {
-        throw new BadRequestError('saveProcess: steps must be an array of strings');
-    }
-    if (steps.length > MAX_PROCESS_STEPS) {
-        throw new BadRequestError(`saveProcess: steps exceeds the ${MAX_PROCESS_STEPS}-step cap (got ${steps.length})`);
-    }
-    const out = [];
-    for (let i = 0; i < steps.length; i++) {
-        const raw = steps[i];
-        if (!isString(raw)) {
-            throw new BadRequestError(`saveProcess: step ${i + 1} is not a string`);
-        }
-        const trimmed = raw.trim();
-        if (trimmed.length === 0) {
-            throw new BadRequestError(`saveProcess: step ${i + 1} is empty`);
-        }
-        if (trimmed.length > MAX_PROCESS_STEP_LEN) {
-            throw new BadRequestError(`saveProcess: step ${i + 1} exceeds the ${MAX_PROCESS_STEP_LEN}-char cap`);
-        }
-        out.push(trimmed);
-    }
-    return out;
-}
-/** Defensive parse: a malformed legacy steps value reads back as []. */
-function parseSteps(raw) {
-    try {
-        const parsed = JSON.parse(raw);
-        if (Array.isArray(parsed) && parsed.every(isString)) {
-            return parsed;
-        }
-        return [];
-    }
-    catch {
-        // Legacy garbage reads back as no steps, per the docblock.
-        return [];
-    }
-}
-function rowToProcess(row) {
-    return {
-        id: row.id,
-        memoryId: row.memory_id,
-        tenantId: row.tenant_id,
-        processName: row.process_name,
-        description: row.description,
-        steps: parseSteps(row.steps),
-        version: row.version,
-        // SAFETY: processes.status has a DB CHECK constraint restricting it to
-        // 'active' | 'superseded' | 'closed' (CREATE TABLE processes, db.ts).
-        status: row.status,
-        supersededBy: row.superseded_by,
-        supersededAt: row.superseded_at,
-        changeSummary: row.change_summary,
-        closedAt: row.closed_at,
-        createdAt: row.created_at,
-    };
-}
-const PROCESS_COLS = `
-  id, memory_id, tenant_id, process_name, description, steps, version, status,
-  superseded_by, superseded_at, change_summary, closed_at, created_at
-`;
-/** The recall-surface content for the memory mirror: name + numbered steps +
- *  optional description, so `hippo recall` shows the process body. */
-function buildProcessContent(processName, steps, description) {
-    const numbered = steps.map((s, i) => `${i + 1}. ${s}`).join('\n');
-    let content = processName;
-    if (numbered)
-        content += `\n\n${numbered}`;
-    if (description)
-        content += `\n\nDescription: ${description}`;
-    return content;
-}
-// Preflight the supersede target BEFORE inserting the new row. The new
-// row's autoincrement id could otherwise collide with a non-existent
-// supersedesProcessId (e.g. superseding id 1 on an empty store), making
-// the row supersede itself. Validating first means the new row is never a
-// candidate for its own supersede UPDATE. Mirrors saveDecision.
-// The same SELECT reads the predecessor version so the
-// successor's version is server-derived, never client-supplied.
-function preflightProcessSupersede(db, tenantId, supersedesId) {
-    // SAFETY: SELECT status, version FROM processes; row shape matches
-    // the two selected columns 1:1.
-    const pred = db.prepare(`SELECT status, version FROM processes WHERE id = ? AND tenant_id = ?`).get(supersedesId, tenantId);
-    if (!pred) {
-        throw new NotFoundError(`saveProcess: process ${supersedesId} to supersede not found for tenant ${tenantId}`);
-    }
-    if (pred.status !== 'active') {
-        throw new ConflictError(`saveProcess: process ${supersedesId} is not active (status='${pred.status}'); only active processes can be superseded.`);
-    }
-    return pred.version + 1;
-}
-function insertProcessRow(db, memoryId, w, version) {
-    const result = db.prepare(`
-    INSERT INTO processes(
-      memory_id, tenant_id, process_name, description, steps, version,
-      status, superseded_by, superseded_at, change_summary, closed_at, created_at
-    ) VALUES (?, ?, ?, ?, ?, ?, 'active', NULL, NULL, ?, NULL, ?)
-  `).run(memoryId, w.tenantId, w.processName, w.description ?? null, JSON.stringify(w.steps), version, w.changeSummary, w.now);
-    return Number(result.lastInsertRowid ?? 0);
-}
-function supersedeProcessRow(db, w, supersedesId, processId, version) {
-    const sup = db.prepare(`
-    UPDATE processes
-    SET status = 'superseded', superseded_by = ?, superseded_at = ?
-    WHERE id = ? AND tenant_id = ? AND status = 'active' AND id != ?
-  `).run(processId, w.now, supersedesId, w.tenantId, processId);
-    if (sup.changes === 0) {
-        throw new ConflictError(`saveProcess: process ${supersedesId} could not be superseded (no longer active or self-reference).`);
-    }
-    appendAuditEvent(db, {
-        tenantId: w.tenantId,
-        actor: w.actor,
-        op: 'process_supersede',
-        targetId: String(supersedesId),
-        metadata: {
-            process_id: supersedesId,
-            superseded_by: processId,
-            new_version: version,
-        },
-    });
-}
-/** The afterWrite body: preflight, INSERT, supersede, reload, create audit, all in one SAVEPOINT. */
-function writeProcessRow(db, memoryId, w) {
-    const version = w.supersedesId !== undefined ? preflightProcessSupersede(db, w.tenantId, w.supersedesId) : 1;
-    const processId = insertProcessRow(db, memoryId, w, version);
-    if (w.supersedesId !== undefined)
-        supersedeProcessRow(db, w, w.supersedesId, processId, version);
-    // SAFETY: SELECT ${PROCESS_COLS} enumerates every ProcessRow field
-    // 1:1 (see PROCESS_COLS above).
-    const row = db.prepare(`SELECT ${PROCESS_COLS} FROM processes WHERE id = ?`)
-        .get(processId);
-    if (!row)
-        throw new Error('saveProcess: failed to reload saved process row');
-    // GDPR-light metadata: ids + counts only, no process_name / step text.
-    appendAuditEvent(db, {
-        tenantId: w.tenantId,
-        actor: w.actor,
-        op: 'process_create',
-        targetId: String(processId),
-        metadata: {
-            process_id: processId,
-            version,
-            step_count: w.steps.length,
-            has_description: w.description !== undefined && w.description !== null && w.description !== '',
-        },
-    });
-    return row;
-}
-/**
- * Create a process (or a new version that supersedes an existing one). Writes
- * the memory mirror + the processes row atomically inside writeEntry's SAVEPOINT
- * 'write_entry'. When supersedesProcessId is given, the referenced ACTIVE row is
- * preflighted (status + version) BEFORE the INSERT, then UPDATEd -> superseded in
- * the SAME SAVEPOINT (CAS: WHERE status='active' AND id != <new id>; throws on
- * changes===0 so a duplicate supersede aborts the whole write). The new row's
- * version = predecessor.version + 1 (server-derived); change_summary carries the
- * delta note. A fresh create has version 1 and change_summary NULL.
- */
-export function saveProcess(hippoRoot, tenantId, opts, actor = 'cli') {
-    assertTenantId('saveProcess', tenantId);
-    if (!opts.processName || opts.processName.trim().length === 0) {
-        throw new BadRequestError('saveProcess: processName is required');
-    }
-    const steps = validateProcessSteps(opts.steps);
-    const isSupersede = opts.supersedesProcessId !== undefined;
-    // change_summary is only meaningful on a supersession; NULL on a fresh create.
-    const changeSummary = isSupersede ? (opts.changeSummary ?? null) : null;
-    const now = new Date().toISOString();
-    const content = buildProcessContent(opts.processName, steps, opts.description);
-    const tags = ['process', ...(opts.extraTags ?? [])];
-    const mem = createMemory(content, {
-        tags,
-        layer: Layer.Semantic,
-        confidence: 'verified',
-        source: 'process',
-        baseHalfLifeDays: objectHalfLifeDays(hippoRoot),
-        tenantId,
-    });
-    const w = {
-        tenantId,
-        actor,
-        processName: opts.processName,
-        description: opts.description,
-        steps,
-        changeSummary,
-        supersedesId: opts.supersedesProcessId,
-        now,
-    };
-    let savedRow;
-    writeEntry(hippoRoot, mem, {
-        actor,
-        afterWrite: (db, memoryId) => {
-            savedRow = writeProcessRow(db, memoryId, w);
-        },
-    });
-    if (!savedRow) {
-        throw new Error('saveProcess: afterWrite did not populate the row');
-    }
-    return rowToProcess(savedRow);
-}
-/**
- * Close (retire) an active process with no successor. Updates the processes row
- * only; the memory mirror is not mutated. CAS guard: WHERE status='active'; 0
- * changes distinguishes not-found from not-active. A superseded row is already
- * terminal in the chain and cannot be closed.
- */
-export function closeProcess(hippoRoot, tenantId, id, actor = 'cli') {
-    assertTenantId('closeProcess', tenantId);
-    const now = new Date().toISOString();
-    const db = openHippoDb(hippoRoot);
-    try {
-        db.exec('BEGIN IMMEDIATE');
-        try {
-            const updateResult = db.prepare(`
-        UPDATE processes
-        SET status = 'closed', closed_at = ?
-        WHERE id = ? AND tenant_id = ? AND status = 'active'
-      `).run(now, id, tenantId);
-            if (updateResult.changes === 0) {
-                // SAFETY: SELECT status FROM processes; row shape matches the
-                // single selected column.
-                const existing = db.prepare(`SELECT status FROM processes WHERE id = ? AND tenant_id = ?`).get(id, tenantId);
-                if (!existing) {
-                    throw new NotFoundError(`closeProcess: process ${id} not found for tenant ${tenantId}`);
-                }
-                throw new ConflictError(`closeProcess: process ${id} is not active (status='${existing.status}'); only active processes can be closed.`);
-            }
-            // SAFETY: SELECT ${PROCESS_COLS} enumerates every ProcessRow field
-            // 1:1 (see PROCESS_COLS above).
-            const row = db.prepare(`SELECT ${PROCESS_COLS} FROM processes WHERE id = ? AND tenant_id = ?`)
-                .get(id, tenantId);
-            if (!row)
-                throw new NotFoundError(`closeProcess: process ${id} not found after UPDATE`);
-            appendAuditEvent(db, {
-                tenantId,
-                actor,
-                op: 'process_close',
-                targetId: String(id),
-                metadata: { process_id: id },
-            });
-            db.exec('COMMIT');
-            return rowToProcess(row);
-        }
-        catch (e) {
-            try {
-                db.exec('ROLLBACK');
-            }
-            catch {
-                // Ignore rollback failures — the throw below is what matters.
-            }
-            throw e;
-        }
-    }
-    finally {
-        closeHippoDb(db);
-    }
-}
-export function loadProcessById(hippoRoot, tenantId, id) {
-    assertTenantId('loadProcessById', tenantId);
-    const db = openHippoDb(hippoRoot);
-    try {
-        // SAFETY: SELECT ${PROCESS_COLS} enumerates every ProcessRow field 1:1
-        // (see PROCESS_COLS above).
-        const row = db.prepare(`SELECT ${PROCESS_COLS} FROM processes WHERE id = ? AND tenant_id = ?`)
-            .get(id, tenantId);
-        return row ? rowToProcess(row) : null;
-    }
-    finally {
-        closeHippoDb(db);
-    }
-}
-export function loadProcesses(hippoRoot, tenantId, opts = {}) {
-    assertTenantId('loadProcesses', 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_PROCESS_STATES.has(opts.status)) {
-                throw new BadRequestError(`loadProcesses: status must be one of ${Array.from(VALID_PROCESS_STATES).join('|')}; got ${opts.status}`);
-            }
-            // SAFETY: SELECT ${PROCESS_COLS} enumerates every ProcessRow field
-            // 1:1 (see PROCESS_COLS above).
-            rows = db.prepare(`
-        SELECT ${PROCESS_COLS} FROM processes
-        WHERE tenant_id = ? AND status = ?${after.sql}
-        ORDER BY created_at DESC, id DESC
-        LIMIT ?
-      `).all(tenantId, opts.status, ...after.params, limit);
-        }
-        else {
-            // SAFETY: SELECT ${PROCESS_COLS} enumerates every ProcessRow field
-            // 1:1 (see PROCESS_COLS above).
-            rows = db.prepare(`
-        SELECT ${PROCESS_COLS} FROM processes
-        WHERE tenant_id = ?${after.sql}
-        ORDER BY created_at DESC, id DESC
-        LIMIT ?
-      `).all(tenantId, ...after.params, limit);
-        }
-        return rows.map(rowToProcess);
-    }
-    finally {
-        closeHippoDb(db);
-    }
-}
-export function loadActiveProcesses(hippoRoot, tenantId, opts = {}) {
-    return loadProcesses(hippoRoot, tenantId, { status: 'active', limit: opts.limit });
-}
-//# sourceMappingURL=processes.js.map