hippo-memory 1.15.0 → 1.17.0

package/dist/processes.js

@@ -0,0 +1,330 @@
+/**
+ * E2 process first-class object (docs/plans/2026-05-29-e2-process-object.md).
+ *
+ * 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 { openHippoDb, closeHippoDb } from './db.js';
+import { writeEntry, assertTenantId } from './store.js';
+import { createMemory, Layer, PROCESS_HALF_LIFE_DAYS } from './memory.js';
+import { appendAuditEvent } from './audit.js';
+export const VALID_PROCESS_STATES = new Set([
+    'active',
+    'superseded',
+    'closed',
+]);
+/** 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 Error('saveProcess: steps must be an array of strings');
+    }
+    if (steps.length > MAX_PROCESS_STEPS) {
+        throw new Error(`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 (typeof raw !== 'string') {
+            throw new Error(`saveProcess: step ${i + 1} is not a string`);
+        }
+        const trimmed = raw.trim();
+        if (trimmed.length === 0) {
+            throw new Error(`saveProcess: step ${i + 1} is empty`);
+        }
+        if (trimmed.length > MAX_PROCESS_STEP_LEN) {
+            throw new Error(`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((s) => typeof s === 'string')) {
+            return parsed;
+        }
+        return [];
+    }
+    catch {
+        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,
+        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;
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * 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 Error('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',
+        tenantId,
+    });
+    mem.half_life_days = PROCESS_HALF_LIFE_DAYS;
+    let savedRow;
+    writeEntry(hippoRoot, mem, {
+        actor,
+        afterWrite: (db, memoryId) => {
+            // 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 (codex P1
+            // 2026-05-28). The same SELECT reads the predecessor version so the
+            // successor's version is server-derived, never client-supplied.
+            let version = 1;
+            if (opts.supersedesProcessId !== undefined) {
+                const pred = db.prepare(`SELECT status, version FROM processes WHERE id = ? AND tenant_id = ?`).get(opts.supersedesProcessId, tenantId);
+                if (!pred) {
+                    throw new Error(`saveProcess: process ${opts.supersedesProcessId} to supersede not found for tenant ${tenantId}`);
+                }
+                if (pred.status !== 'active') {
+                    throw new Error(`saveProcess: process ${opts.supersedesProcessId} is not active (status='${pred.status}'); only active processes can be superseded.`);
+                }
+                version = pred.version + 1;
+            }
+            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, tenantId, opts.processName, opts.description ?? null, JSON.stringify(steps), version, changeSummary, now);
+            const processId = Number(result.lastInsertRowid ?? 0);
+            if (opts.supersedesProcessId !== undefined) {
+                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, now, opts.supersedesProcessId, tenantId, processId);
+                if (sup.changes === 0) {
+                    throw new Error(`saveProcess: process ${opts.supersedesProcessId} could not be superseded (no longer active or self-reference).`);
+                }
+                appendAuditEvent(db, {
+                    tenantId,
+                    actor,
+                    op: 'process_supersede',
+                    targetId: String(opts.supersedesProcessId),
+                    metadata: {
+                        process_id: opts.supersedesProcessId,
+                        superseded_by: processId,
+                        new_version: version,
+                    },
+                });
+            }
+            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');
+            savedRow = row;
+            // GDPR-light metadata: ids + counts only, no process_name / step text.
+            appendAuditEvent(db, {
+                tenantId,
+                actor,
+                op: 'process_create',
+                targetId: String(processId),
+                metadata: {
+                    process_id: processId,
+                    version,
+                    step_count: steps.length,
+                    has_description: opts.description !== undefined && opts.description !== null && opts.description !== '',
+                },
+            });
+        },
+    });
+    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) {
+                const existing = db.prepare(`SELECT status FROM processes WHERE id = ? AND tenant_id = ?`).get(id, tenantId);
+                if (!existing) {
+                    throw new Error(`closeProcess: process ${id} not found for tenant ${tenantId}`);
+                }
+                throw new Error(`closeProcess: process ${id} is not active (status='${existing.status}'); only active processes can be closed.`);
+            }
+            const row = db.prepare(`SELECT ${PROCESS_COLS} FROM processes WHERE id = ? AND tenant_id = ?`)
+                .get(id, tenantId);
+            if (!row)
+                throw new Error(`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 {
+        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 db = openHippoDb(hippoRoot);
+    try {
+        let rows;
+        if (opts.status) {
+            if (!VALID_PROCESS_STATES.has(opts.status)) {
+                throw new Error(`loadProcesses: status must be one of ${Array.from(VALID_PROCESS_STATES).join('|')}; got ${opts.status}`);
+            }
+            rows = db.prepare(`
+        SELECT ${PROCESS_COLS} FROM processes
+        WHERE tenant_id = ? AND status = ?
+        ORDER BY created_at DESC, id DESC
+        LIMIT ?
+      `).all(tenantId, opts.status, limit);
+        }
+        else {
+            rows = db.prepare(`
+        SELECT ${PROCESS_COLS} FROM processes
+        WHERE tenant_id = ?
+        ORDER BY created_at DESC, id DESC
+        LIMIT ?
+      `).all(tenantId, 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

package/dist/processes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"processes.js","sourceRoot":"","sources":["../src/processes.ts"],"names":[],"mappings":"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"}

package/dist/project-briefs.d.ts

@@ -0,0 +1,126 @@
+/**
+ * E2 project_brief first-class object
+ * (docs/plans/2026-05-30-e2-project-brief-object.md).
+ *
+ * A `project_brief` is the living, repo-scoped summary of a repository's state: a
+ * `summary` body scoped to a `repo`, evolving via the supersede delta lifecycle.
+ * "Auto-refreshes from receipts" is scoped to a DETERMINISTIC (no-LLM) assembler:
+ * `refreshBrief` gathers the repo's recent receipts (memory rows tagged
+ * `path:<repo>`) and assembles them into the brief body. The distinguishing
+ * capability is therefore the refresh assembler (analog of skill's export
+ * renderer), not an LLM/async pipeline (deferred).
+ *
+ * Reuses the skill/process supersede machinery verbatim (superseded_by self-FK +
+ * CAS + INSERT-preflight + server-derived version + change_summary + supersede
+ * tenant-match trigger). It DROPS skill's `skill_name`/`trigger_text` and ADDS
+ * `repo` (the repo-scoping dimension) + `summary` (the brief body).
+ *
+ * The `project_briefs` 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 newer version replaces it) or active ->
+ * closed (retired).
+ */
+export type BriefStatus = 'active' | 'superseded' | 'closed';
+export declare const VALID_BRIEF_STATES: ReadonlySet<BriefStatus>;
+/** Field caps (untrusted at the HTTP/SDK boundary). summary is a body, so a larger
+ *  cap than the 4096 short-field convention. */
+export declare const MAX_REPO_LEN = 256;
+export declare const MAX_BRIEF_SUMMARY_LEN = 8192;
+export declare const MAX_CHANGE_SUMMARY_LEN = 4096;
+/** Bound the receipts gathered per refresh (a refresh reads memories; cap the scan
+ *  + the rendered body). Realistic repos have far fewer recent receipts than this. */
+export declare const MAX_BRIEF_RECEIPTS = 50;
+/** Truncate each receipt's headline in the assembled digest. */
+export declare const MAX_RECEIPT_HEADLINE_LEN = 200;
+export interface ProjectBrief {
+    id: number;
+    /** Nullable: ON DELETE SET NULL lets memory deletion proceed without breaking
+     *  the brief row. */
+    memoryId: string | null;
+    tenantId: string;
+    /** The repo identifier this brief is scoped to (e.g. `hippo`). */
+    repo: string;
+    /** The brief body. */
+    summary: string;
+    /** Server-derived: 1 on a fresh create, predecessor.version + 1 on supersede. */
+    version: number;
+    status: BriefStatus;
+    supersededBy: number | null;
+    supersededAt: string | null;
+    /** The per-version delta note; set on a successor row only (NULL on a v1). */
+    changeSummary: string | null;
+    closedAt: string | null;
+    createdAt: string;
+}
+export interface SaveProjectBriefOpts {
+    repo: string;
+    summary: string;
+    /** The delta note for a supersession; ignored (stored NULL) on a fresh create. */
+    changeSummary?: string;
+    /** Table id of an ACTIVE brief this new version supersedes. */
+    supersedesBriefId?: number;
+    /** Extra memory tags merged after ['project_brief']. */
+    extraTags?: string[];
+    /** Internal: set by refreshBrief to the receipt count so the audit metadata can
+     *  mark the write as an auto-refresh (vs a manual supersede) WITHOUT a 4th audit
+     *  op. Not part of the public CLI/HTTP surface. */
+    refreshReceiptCount?: number;
+}
+export interface ListProjectBriefsOpts {
+    status?: BriefStatus;
+    /** Filter to a single repo. */
+    repo?: string;
+    limit?: number;
+}
+/**
+ * Create a project_brief (or a new version that supersedes an existing one). Writes
+ * the memory mirror + the project_briefs row atomically inside writeEntry's
+ * SAVEPOINT. When supersedesBriefId 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).
+ */
+export declare function saveProjectBrief(hippoRoot: string, tenantId: string, opts: SaveProjectBriefOpts, actor?: string): ProjectBrief;
+/**
+ * Close (retire) an active brief. CAS guard WHERE status='active'; 0 changes
+ * distinguishes not-found from not-active. A superseded row is terminal.
+ */
+export declare function closeProjectBrief(hippoRoot: string, tenantId: string, id: number, actor?: string): ProjectBrief;
+export declare function loadProjectBriefById(hippoRoot: string, tenantId: string, id: number): ProjectBrief | null;
+export declare function loadProjectBriefs(hippoRoot: string, tenantId: string, opts?: ListProjectBriefsOpts): ProjectBrief[];
+/**
+ * The repo's CURRENT active brief, or null. By convention there is one active brief
+ * per (tenant, repo); if an operator created more than one (the DB does not prevent
+ * it, consistent with every other E2 object), the MOST-RECENT active row wins.
+ */
+export declare function loadActiveBriefForRepo(hippoRoot: string, tenantId: string, repo: string): ProjectBrief | null;
+/**
+ * Assemble the repo's recent receipts into a deterministic markdown digest, and
+ * return it WITH the receipt count (the count feeds refreshBrief's change_summary +
+ * audit metadata). NO LLM. Always returns a non-empty, valid summary (a brief
+ * `summary` is NOT NULL), including the zero-receipts case.
+ *
+ * A "receipt" = a tenant memory row carrying the repo's `path:<repo>` tag. The
+ * brief's OWN memory mirror (source='project_brief') is excluded so a brief never
+ * becomes its own receipt on the next refresh. The match is against the JSON-array
+ * serialization (each element is a double-quoted string `"path:hippo"`); the
+ * surrounding quotes are load-bearing — they stop `hip` matching `path:hippo`.
+ * `repo` is LIKE-escaped + parameterized (operator-supplied; security.md).
+ */
+export declare function assembleBriefFromReceipts(hippoRoot: string, tenantId: string, repo: string): {
+    markdown: string;
+    receiptCount: number;
+};
+/**
+ * Auto-refresh the repo's brief from its receipts: assemble the digest, then create
+ * a new version. If the repo already has an active brief it is superseded (the
+ * change_summary records the auto-refresh + the audit metadata carries
+ * `refreshed: true`); otherwise a v1 is created. Returns the new brief.
+ *
+ * The assemble (a read of `memories`) happens BEFORE writeEntry opens its SAVEPOINT;
+ * a concurrent receipt write landing between the read and the brief write simply
+ * appears in the NEXT refresh — the brief is a derived snapshot, not a transactional
+ * aggregate, so no consistency invariant is violated.
+ */
+export declare function refreshBrief(hippoRoot: string, tenantId: string, repo: string, actor?: string): ProjectBrief;
+//# sourceMappingURL=project-briefs.d.ts.map

package/dist/project-briefs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-briefs.d.ts","sourceRoot":"","sources":["../src/project-briefs.ts"],"names":[],"mappings":"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"}