hippo-memory 1.60.0 → 1.61.0

package/dist/dag.js

@@ -1,5 +1,6 @@
 import { createMemory, Layer } from './memory.js';
-import { writeEntry, loadAllDirtySummaries, loadChildrenOfSummary, applyRebuildResult, clearSummaryDirtyAfterBuild, } from './store.js';
+import { writeEntry } from './store/entry-writes.js';
+import { loadAllDirtySummaries, loadChildrenOfSummary, applyRebuildResult, clearSummaryDirtyAfterBuild, } from './store/summaries.js';
 import { RejectedValueError } from './rejection.js';
 import { redactSecretsStrict } from './secret-detect.js';
 import { fetchWithRetry, llmTimeoutMs } from './http-retry.js';
@@ -145,7 +146,7 @@ export async function buildDag(hippoRoot, facts, opts) {
             // The tombstone check itself is tenant-scoped for free: writeEntry ->
             // writeEntryDbOnly -> upsertEntryRow calls
             // checkRejectionGuard(db, entry.tenantId ?? 'default', ...)
-            // (store.ts:1172), reading tenantId off the entry being written. Now
+            // (store/entry-writes.ts), reading tenantId off the entry being written. Now
             // that summaryEntry carries factTenant instead of the implicit
             // 'default', the guard consults that tenant's tombstones — no
             // separate check needed here (unlike consolidate.ts's merge pass,
@@ -170,7 +171,7 @@ export async function buildDag(hippoRoot, facts, opts) {
                 result.factsLinked++;
             }
             // v0.30 / E3 — cancel the cascade of dirty-marks fired by member
-            // writeEntry calls (E2 hook on writeEntryDbOnly at store.ts:1214).
+            // writeEntry calls (E2 hook on writeEntryDbOnly in store/entry-writes.ts).
             // The summary we just built IS fresh, no rebuild needed. Without this,
             // E3 in the SAME sleep cycle would re-rebuild every new summary
             // (2x LLM cost). plan-eng-r1 HIGH must-fix.
@@ -236,7 +237,7 @@ export async function rebuildDirtySummaries(hippoRoot, opts) {
                     result.zeroChildSkipped++;
                 // changed=false → race lost / row vanished; silently skip. `refused`
                 // is always false here — applyRebuildResult only checks the
-                // tombstone when bumpRebuildCount is true (store.ts:3398).
+                // tombstone when bumpRebuildCount is true (store/summaries.ts).
                 continue;
             }
             // Derive label from summary's existing entity tags (mirrors clusterFacts)
@@ -272,7 +273,7 @@ export async function rebuildDirtySummaries(hippoRoot, opts) {
         catch (err) {
             // Per-summary failure isolation — one throw doesn't abort the queue.
             // independent-review MED #2 fold: log enough to triage in production
-            // (audit() wraps its own writes try/catch per store.ts:2566, so a
+            // (audit() wraps its own writes try/catch per store/audit-event.ts, so a
             // throw here is exotic: SQLite I/O error, prepare failure, etc).
             result.failed++;
             log.error(`rebuildDirtySummaries: summary ${summary.id} (tenant ${summary.tenantId}) failed: ${err instanceof Error ? err.message : String(err)}`);

package/dist/dashboard-actions.d.ts

@@ -0,0 +1,20 @@
+import type { MemoryEntry } from './memory.js';
+import { type ActionBody } from './dashboard-params.js';
+/** What an action hands the router: a status, a JSON body, and whether the store changed. */
+export interface ActionResult {
+    status: number;
+    body: unknown;
+    /** True when a write committed, so the router drops the snapshot. */
+    changed: boolean;
+    /** The live entry an action acted on, so the router can build the detail after the cache is dropped. */
+    entry?: MemoryEntry;
+}
+/** Sets `pinned`; the audit row says `remember` with actor `dashboard`, the same op the old star toggle wrote. */
+export declare function pinMemory(hippoRoot: string, tenantId: string, rawId: string, body: ActionBody): ActionResult;
+/** Marks a memory wrong, the same signal as `hippo outcome --bad`. */
+export declare function markWrong(hippoRoot: string, tenantId: string, rawId: string): ActionResult;
+/** Deletes a memory like `hippo forget`; a raw receipt is append-only and answers 409 with the archive hint. */
+export declare function forgetMemory(hippoRoot: string, tenantId: string, rawId: string): ActionResult;
+/** Keeps one side of an open conflict and weakens the other; every refusal maps to its own status. */
+export declare function resolveOpenConflict(hippoRoot: string, tenantId: string, conflictId: number, body: ActionBody): ActionResult;
+//# sourceMappingURL=dashboard-actions.d.ts.map

package/dist/dashboard-actions.js

@@ -0,0 +1,88 @@
+// The four dashboard writes, each a thin call into an existing store or api function; the router owns HTTP and the cache.
+import * as api from './api.js';
+import { NotFoundError } from './api-errors.js';
+import { listMemoryConflicts, resolveConflict } from './store/conflicts.js';
+import { readEntry } from './store/entry-reads.js';
+import { writeEntry } from './store/entry-writes.js';
+import { ParamError, parseMemoryId } from './dashboard-params.js';
+import { isLiveMemory } from './dashboard-snapshot.js';
+const ACTOR = 'dashboard';
+function notFound() {
+    return { status: 404, body: { error: 'Not found' }, changed: false };
+}
+function liveEntry(hippoRoot, tenantId, id) {
+    const entry = readEntry(hippoRoot, id, tenantId);
+    return entry !== null && isLiveMemory(entry) ? entry : null;
+}
+/** Sets `pinned`; the audit row says `remember` with actor `dashboard`, the same op the old star toggle wrote. */
+export function pinMemory(hippoRoot, tenantId, rawId, body) {
+    const id = parseMemoryId(rawId);
+    const { pinned } = body;
+    if (pinned === undefined)
+        throw new ParamError('pinned must be true or false');
+    const entry = liveEntry(hippoRoot, tenantId, id);
+    if (entry === null)
+        return notFound();
+    const next = { ...entry, pinned };
+    writeEntry(hippoRoot, next, { actor: ACTOR });
+    return { status: 200, body: null, changed: true, entry: next };
+}
+/** Marks a memory wrong, the same signal as `hippo outcome --bad`. */
+export function markWrong(hippoRoot, tenantId, rawId) {
+    const id = parseMemoryId(rawId);
+    if (liveEntry(hippoRoot, tenantId, id) === null)
+        return notFound();
+    const ctx = { hippoRoot, tenantId, actor: api.adminActor(ACTOR) };
+    // outcome() answers `applied: 0` for a missing or other-tenant id instead of throwing.
+    if (api.outcome(ctx, [id], false).applied === 0)
+        return notFound();
+    const entry = readEntry(hippoRoot, id, tenantId);
+    return entry === null ? notFound() : { status: 200, body: null, changed: true, entry };
+}
+/** Deletes a memory like `hippo forget`; a raw receipt is append-only and answers 409 with the archive hint. */
+export function forgetMemory(hippoRoot, tenantId, rawId) {
+    const id = parseMemoryId(rawId);
+    if (liveEntry(hippoRoot, tenantId, id) === null)
+        return notFound();
+    const ctx = { hippoRoot, tenantId, actor: api.adminActor(ACTOR) };
+    try {
+        const done = api.forget(ctx, id);
+        return { status: 200, body: done, changed: true };
+    }
+    catch (err) {
+        if (err instanceof NotFoundError)
+            return notFound();
+        // Same match as cmdForget: the append-only trigger names itself in the message.
+        if (err instanceof Error && /append-only/i.test(err.message)) {
+            const error = `Cannot forget ${id}: it is a raw, append-only memory. Archive it instead: hippo forget ${id} --archive --reason "<why>"`;
+            return { status: 409, body: { error }, changed: false };
+        }
+        throw err;
+    }
+}
+/** Keeps one side of an open conflict and weakens the other; every refusal maps to its own status. */
+export function resolveOpenConflict(hippoRoot, tenantId, conflictId, body) {
+    const { keep } = body;
+    if (keep === undefined)
+        throw new ParamError('keep must be a memory id');
+    parseMemoryId(keep);
+    const conflict = listMemoryConflicts(hippoRoot, '*', tenantId).find((c) => c.id === conflictId);
+    if (!conflict)
+        return notFound();
+    const already = () => ({ status: 409, body: { error: 'This conflict is already resolved' }, changed: false });
+    if (conflict.status !== 'open')
+        return already();
+    if (keep !== conflict.memory_a_id && keep !== conflict.memory_b_id) {
+        throw new ParamError('keep must be one of the two memories in the conflict');
+    }
+    if (liveEntry(hippoRoot, tenantId, conflict.memory_a_id) === null || liveEntry(hippoRoot, tenantId, conflict.memory_b_id) === null) {
+        return notFound();
+    }
+    const resolved = resolveConflict(hippoRoot, conflictId, keep, false, tenantId, { rejectedBy: ACTOR });
+    // Both guards passed above, so null here is a race with another resolver.
+    if (resolved === null)
+        return already();
+    const result = { ok: true, conflictId, keptId: keep, weakenedId: resolved.loserId };
+    return { status: 200, body: result, changed: true };
+}
+//# sourceMappingURL=dashboard-actions.js.map

package/dist/dashboard-params.d.ts

@@ -0,0 +1,45 @@
+import { type Chip } from './dashboard-snapshot.js';
+/** A request field failed validation; the router answers 400 with this plain message. */
+export declare class ParamError extends Error {
+}
+export declare const SORT_KEYS: readonly ["content", "layer", "strength", "retrievals", "last", "age", "confidence", "scope"];
+export type SortKey = (typeof SORT_KEYS)[number];
+export type SortDir = 'asc' | 'desc';
+export declare const LIMIT_DEFAULT = 100;
+export declare const LIMIT_MAX = 500;
+export declare const SEARCH_MIN = 2;
+export declare const SEARCH_MAX = 200;
+export interface Brush {
+    amin: number;
+    amax: number;
+    smin: number;
+    smax: number;
+}
+export interface MemoryQuery {
+    offset: number;
+    limit: number;
+    sort: SortKey;
+    dir: SortDir;
+    chip: Chip;
+    /** Layer indices in wire order, ascending, no duplicates. */
+    layers: number[];
+    brush: Brush;
+    /** Lowercased search text, or null when none or shorter than the minimum. */
+    q: string | null;
+}
+/** Parses and validates the query of `GET /api/projects/:key/memories`. */
+export declare function parseMemoryQuery(params: URLSearchParams): MemoryQuery;
+/** Search text for `GET /api/search`: 2 to 200 characters after trim, returned as typed (trimmed). */
+export declare function parseSearchText(params: URLSearchParams): string;
+/** A memory id from a path segment. */
+export declare function parseMemoryId(raw: string): string;
+/** The only fields a dashboard POST reads; a field of the wrong type arrives as undefined. */
+export interface ActionBody {
+    pinned?: boolean;
+    keep?: string;
+}
+/** Parses a POST body once at the boundary; an empty body is `{}` and invalid JSON is a 400. */
+export declare function parseActionBody(text: string): ActionBody;
+/** A conflict id from a path segment: a positive integer. */
+export declare function parseConflictId(raw: string): number;
+//# sourceMappingURL=dashboard-params.d.ts.map

package/dist/dashboard-params.js

@@ -0,0 +1,127 @@
+// One shared parser for every dashboard query and path field, so no route trusts `parseInt` or an unchecked id.
+import { LAYERS } from './dashboard-snapshot.js';
+/** A request field failed validation; the router answers 400 with this plain message. */
+export class ParamError extends Error {
+}
+export const SORT_KEYS = ['content', 'layer', 'strength', 'retrievals', 'last', 'age', 'confidence', 'scope'];
+const CHIPS = ['all', 'risk', 'pinned', 'conflict'];
+const MEMORY_ID = /^[A-Za-z0-9_-]+$/;
+const INTEGER = /^-?\d+$/;
+export const LIMIT_DEFAULT = 100;
+export const LIMIT_MAX = 500;
+export const SEARCH_MIN = 2;
+export const SEARCH_MAX = 200;
+function integerParam(params, name, fallback, min, max) {
+    const raw = params.get(name);
+    if (raw === null)
+        return fallback;
+    const n = INTEGER.test(raw.trim()) ? Number(raw) : Number.NaN;
+    if (!Number.isInteger(n) || n < min || n > max) {
+        throw new ParamError(`${name} must be a whole number from ${min} to ${max}`);
+    }
+    return n;
+}
+function oneOf(params, name, allowed, fallback) {
+    const raw = params.get(name);
+    if (raw === null)
+        return fallback;
+    const hit = allowed.find((a) => a === raw);
+    if (hit === undefined)
+        throw new ParamError(`${name} must be one of ${allowed.join(', ')}`);
+    return hit;
+}
+function finiteParam(params, name) {
+    const raw = params.get(name);
+    if (raw === null)
+        return null;
+    const n = raw.trim() === '' ? Number.NaN : Number(raw);
+    if (!Number.isFinite(n))
+        throw new ParamError(`${name} must be a number`);
+    return n;
+}
+function layersParam(params) {
+    const raw = params.get('layers');
+    if (raw === null)
+        return LAYERS.map((_, i) => i);
+    const picked = new Set();
+    for (const part of raw.split(',')) {
+        const i = LAYERS.findIndex((l) => l === part.trim());
+        if (i === -1)
+            throw new ParamError(`layers must be a comma list of ${LAYERS.join(', ')}`);
+        picked.add(i);
+    }
+    return [...picked].sort((a, b) => a - b);
+}
+function rangeParam(params, lo, hi) {
+    const min = finiteParam(params, lo);
+    const max = finiteParam(params, hi);
+    if (min !== null && max !== null && min > max)
+        throw new ParamError(`${lo} must not exceed ${hi}`);
+    return [min ?? Number.NEGATIVE_INFINITY, max ?? Number.POSITIVE_INFINITY];
+}
+/** Search text for the memories route: shorter than the minimum means no filter; longer than the maximum is a 400. */
+function optionalSearch(params) {
+    const raw = params.get('q');
+    if (raw === null)
+        return null;
+    const q = raw.trim();
+    if (q.length > SEARCH_MAX)
+        throw new ParamError(`q must be at most ${SEARCH_MAX} characters`);
+    return q.length < SEARCH_MIN ? null : q.toLowerCase();
+}
+/** Parses and validates the query of `GET /api/projects/:key/memories`. */
+export function parseMemoryQuery(params) {
+    const [amin, amax] = rangeParam(params, 'amin', 'amax');
+    const [smin, smax] = rangeParam(params, 'smin', 'smax');
+    const sort = oneOf(params, 'sort', SORT_KEYS, 'strength');
+    return {
+        offset: integerParam(params, 'offset', 0, 0, Number.MAX_SAFE_INTEGER),
+        limit: integerParam(params, 'limit', LIMIT_DEFAULT, 1, LIMIT_MAX),
+        sort,
+        // Weakest first by default, like the mockup; retrievals starts with the most.
+        dir: oneOf(params, 'dir', ['asc', 'desc'], sort === 'retrievals' ? 'desc' : 'asc'),
+        chip: oneOf(params, 'chip', CHIPS, 'all'),
+        layers: layersParam(params),
+        brush: { amin, amax, smin, smax },
+        q: optionalSearch(params),
+    };
+}
+/** Search text for `GET /api/search`: 2 to 200 characters after trim, returned as typed (trimmed). */
+export function parseSearchText(params) {
+    const q = (params.get('q') ?? '').trim();
+    if (q.length < SEARCH_MIN || q.length > SEARCH_MAX) {
+        throw new ParamError(`q must be ${SEARCH_MIN} to ${SEARCH_MAX} characters`);
+    }
+    return q;
+}
+/** A memory id from a path segment. */
+export function parseMemoryId(raw) {
+    if (!MEMORY_ID.test(raw))
+        throw new ParamError('Invalid memory id');
+    return raw;
+}
+/** Parses a POST body once at the boundary; an empty body is `{}` and invalid JSON is a 400. */
+export function parseActionBody(text) {
+    let raw;
+    try {
+        raw = JSON.parse(text === '' ? '{}' : text);
+    }
+    catch {
+        throw new ParamError('Body is not valid JSON');
+    }
+    const pinned = raw?.pinned;
+    const keep = raw?.keep;
+    // String(x) === x is true only for a string, which is the check without a typeof.
+    return {
+        pinned: pinned === true || pinned === false ? pinned : undefined,
+        keep: String(keep) === keep ? keep : undefined,
+    };
+}
+/** A conflict id from a path segment: a positive integer. */
+export function parseConflictId(raw) {
+    const n = INTEGER.test(raw) ? Number(raw) : Number.NaN;
+    if (!Number.isSafeInteger(n) || n < 1)
+        throw new ParamError('Invalid conflict id');
+    return n;
+}
+//# sourceMappingURL=dashboard-params.js.map

package/dist/dashboard-queries.d.ts

@@ -0,0 +1,15 @@
+import { type MemoryEntry } from './memory.js';
+import { type Snapshot } from './dashboard-snapshot.js';
+import type { MemoryQuery } from './dashboard-params.js';
+import type { MemoryDetail, MemoryPage, Overview, ProjectDetail, SearchResult } from './dashboard-types.js';
+/** The overview of one snapshot, built once and reused until the snapshot is replaced. */
+export declare function buildOverview(snap: Snapshot): Overview;
+/** Summary and scatter for one project key, or null when the key is unknown. */
+export declare function buildProjectDetail(snap: Snapshot, key: string): ProjectDetail | null;
+/** One page of a project's memories under the query's sort and filters, or null when the key is unknown. */
+export declare function buildMemoryPage(snap: Snapshot, key: string, query: MemoryQuery): MemoryPage | null;
+/** Substring search over content and tags across every project; it reads the snapshot and never touches recall. */
+export declare function buildSearch(snap: Snapshot, text: string): SearchResult;
+/** Full detail read fresh from the store, never from the snapshot, so the drawer is current inside the coalescing window. */
+export declare function buildMemoryDetail(hippoRoot: string, tenantId: string, entry: MemoryEntry, snapshotId: number, nowMs: number, embedded: boolean): MemoryDetail;
+//# sourceMappingURL=dashboard-queries.d.ts.map