hippo-memory 1.43.3 → 1.45.0

package/dist/src/recall-history.js

@@ -1,235 +0,0 @@
-/**
- * J1 anchoring detector (recall-recurrence) — pure module.
- *
- * Implements two detection rules from ROADMAP-RESEARCH.md L546:
- *   R1 query_repeat: same queryHash within recentRepeatWindow returned
- *     same topMemoryId (caller is re-asking the same question).
- *   R2 memory_dominance: same topMemoryId across >= minDominance distinct
- *     queryHashes (memory acts as a fixed-point anchor regardless of what
- *     the agent asks).
- *
- * Per the plan v3 architectural decision: each pipeline (api.recall via
- * HTTP, cmdRecall, MCP hippo_recall) owns its OWN ring buffer Map keyed
- * by (tenant, session). No cross-pipeline sharing (the typical multi-
- * process deployment makes IPC ring-sharing impractical; per-pipeline
- * is correct because each pipeline has its own top-1 ranking anyway).
- *
- * Plan: docs/plans/2026-05-26-j1-anchoring-detector.md.
- * Composes with J3.2: AnchoringHint + PlanningFallacyHint are independent
- * signals; both can fire on the same recall.
- */
-const DEFAULT_MIN_DOMINANCE = 3;
-const DEFAULT_RECENT_REPEAT_WINDOW = 5;
-const DEFAULT_COOLDOWN = 3;
-// ---------------------------------------------------------------------------
-// Query text normalization + hashing
-// ---------------------------------------------------------------------------
-/**
- * Normalize + hash a query text into a 32-bit integer.
- * Lowercase → strip non-alphanumeric → split → drop empty + short tokens →
- * sort tokens → join → FNV-1a 32-bit.
- *
- * Token sort + dedup means semantically-equivalent queries with reordered
- * words collide intentionally (the roadmap's "semantically-distinct" v1
- * uses textual normalization; embedding-based distinctness is J1-v2).
- *
- * Deterministic across processes; stable across Node + V8 versions.
- */
-export function hashQueryText(query) {
-    if (!query)
-        return 0;
-    // Token dedup before join: the R2 contract says "distinct queries"
-    // means semantically distinct, so `foo bar` and `foo foo bar` should
-    // collapse to the same hash. Without dedup, simple phrasing
-    // variations (typos, doubled tokens, intensifiers) would inflate
-    // distinct-query counts and trip R2 on essentially the same question.
-    // Codex round-1 catch.
-    // Unicode-aware tokenization (codex round-3 P2 catch): the prior
-    // ASCII-only [^a-z0-9\s] pattern stripped every non-Latin letter, so
-    // Japanese, Arabic, Cyrillic, accented-Latin etc. queries collapsed
-    // to empty token set -> hash 0 -> false R1 collisions across distinct
-    // non-English queries. \p{L} = any Unicode letter, \p{N} = any Unicode
-    // number, \p{M} = combining marks (preserve composed accented chars).
-    // Requires the /u flag and Node >= 12.
-    const normalized = query
-        .toLowerCase()
-        .replace(/[^\p{L}\p{N}\p{M}\s]/gu, ' ')
-        .split(/\s+/)
-        .filter((t) => t.length > 0);
-    // Drop tokens shorter than 3 chars to match the normalizer contract
-    // (filler / stop words). Without this, `a login bug` vs `login bug`
-    // hash differently and inflate R2 distinct-query counts, firing
-    // memory_dominance on repeated phrasings of the same question.
-    // Codex round-4 P2 catch. Matches the same >=3 filter in
-    // src/forward-claim-detector.ts for class-resolver tokens.
-    const filtered = normalized.filter((t) => t.length >= 3);
-    // Fallback when the >=3 filter would collapse the entire query to
-    // empty: CJK queries like `测试` / `环境` are 2-char tokens; English
-    // acronyms like `AI` / `UI` are 2 chars. Without this fallback they
-    // all hash to fnv1a32(''), producing false R1 collisions across
-    // distinct short-token queries. Codex round-5 P2 catch.
-    const tokens = filtered.length > 0 ? filtered : normalized;
-    const deduped = Array.from(new Set(tokens)).sort();
-    return fnv1a32(deduped.join(' '));
-}
-function fnv1a32(text) {
-    // FNV-1a 32-bit. Offset basis 2166136261, prime 16777619.
-    let hash = 2166136261;
-    for (let i = 0; i < text.length; i++) {
-        hash ^= text.charCodeAt(i);
-        // 32-bit multiply via Math.imul — handles overflow correctly.
-        hash = Math.imul(hash, 16777619);
-    }
-    // Coerce to unsigned 32-bit for stable comparison.
-    return hash >>> 0;
-}
-// ---------------------------------------------------------------------------
-// Anchoring detection
-// ---------------------------------------------------------------------------
-/**
- * Detect anchoring patterns in the recall history against the current
- * recall's (queryHash, topMemoryId).
- *
- * Rule precedence: R2 (memory_dominance) wins on tie. When both R1 and R2
- * fire on the same recall, return only the R2 hint — R2's signal is the
- * cognitively stronger one (a memory dominating multiple DIFFERENT queries
- * is a fixed-point anchor; R1 alone is just a literal re-ask).
- *
- * Cooldown: if the immediately-prior recall fired a hint on the SAME
- * topMemoryId within `cooldown=3` history entries, suppress. Prevents
- * spam when the agent repeatedly recalls within the dominance window.
- * Cooldown is per-memory, not per-rule: if R2 fired on M (cooldown
- * engaged for M), and the next recall has top=N + repeated query →
- * R1 fires on N (different memory, not in cooldown).
- *
- * @returns AnchoringHint when a pattern fires; null otherwise.
- */
-export function detectAnchoring(history, currentQueryHash, currentTopMemoryId, opts = {}) {
-    if (currentTopMemoryId === null)
-        return null;
-    const minDominance = opts.minDominance ?? DEFAULT_MIN_DOMINANCE;
-    const recentRepeatWindow = opts.recentRepeatWindow ?? DEFAULT_RECENT_REPEAT_WINDOW;
-    const cooldown = opts.cooldown ?? DEFAULT_COOLDOWN;
-    // Cooldown gate: was the most-recent hint (across the last `cooldown`
-    // entries) for THIS memory? If yes, suppress regardless of rule.
-    const cooldownSlice = history.slice(-cooldown);
-    for (const entry of cooldownSlice) {
-        if (entry.anchoredOn === currentTopMemoryId) {
-            return null;
-        }
-    }
-    // R2 check FIRST (wins on tie). Count distinct queryHashes in history
-    // where topMemoryId === currentTopMemoryId (excluding null tops).
-    const matchingQueryHashes = new Set();
-    for (const entry of history) {
-        if (entry.topMemoryId === currentTopMemoryId) {
-            matchingQueryHashes.add(entry.queryHash);
-        }
-    }
-    // Include current query in the count.
-    matchingQueryHashes.add(currentQueryHash);
-    const queryCount = matchingQueryHashes.size;
-    if (queryCount >= minDominance) {
-        return {
-            reason: 'memory_dominance',
-            memoryId: currentTopMemoryId,
-            queryCount,
-            summary: `Memory ${currentTopMemoryId} has been the top result for ${queryCount} distinct queries in this session and may be anchoring your reasoning.`,
-            source: 'j1-recurrence',
-        };
-    }
-    // R1 check: is currentQueryHash present in the last `recentRepeatWindow`
-    // entries AND was that entry's topMemoryId === currentTopMemoryId?
-    const r1Slice = history.slice(-recentRepeatWindow);
-    for (const entry of r1Slice) {
-        if (entry.queryHash === currentQueryHash && entry.topMemoryId === currentTopMemoryId) {
-            return {
-                reason: 'query_repeat',
-                memoryId: currentTopMemoryId,
-                summary: `Same query phrasing as a recent recall returned the same top result (${currentTopMemoryId}); you may be re-asking the same question.`,
-                source: 'j1-recurrence',
-            };
-        }
-    }
-    return null;
-}
-// ---------------------------------------------------------------------------
-// RingBuffer + caller-side state helpers
-// ---------------------------------------------------------------------------
-const MAX_HISTORY = 10;
-const DEFAULT_MAX_SESSIONS = 1000;
-/**
- * Bounded FIFO ring of RecallHistoryEntry. Newest entries pushed via
- * append; oldest evicted when the ring is full. The class is intentionally
- * a thin wrapper around an array so snapshotRing returns a readonly view
- * without copying on the hot path.
- */
-export class RingBuffer {
-    entries = [];
-    append(entry) {
-        this.entries.push(entry);
-        if (this.entries.length > MAX_HISTORY) {
-            this.entries.shift();
-        }
-    }
-    snapshot() {
-        return this.entries;
-    }
-    size() {
-        return this.entries.length;
-    }
-}
-/**
- * Build the (tenant, session) key for a per-session ring Map. Uses a NUL
- * (`\x00`) byte as delimiter because tenant ids and session ids are
- * validated elsewhere to reject NUL chars — guarantees collision-free
- * concatenation regardless of what `:` or other delimiters might appear
- * inside either field (notably API-key-derived subjects can contain `:`).
- */
-export function buildSessionKey(tenantId, sessionId) {
-    return `${tenantId}\x00${sessionId}`;
-}
-/**
- * Get-or-create a RingBuffer for a session key. Caps total tracked keys
- * at `maxSessions` (default 1000) with LRU eviction — when the cap is
- * hit, deletes the oldest-inserted key before inserting the new one.
- * Map iteration order preserves insertion order per ECMA-262 spec, so
- * "oldest" = first key returned by Map.prototype.keys().
- */
-export function getOrCreateRing(map, key, maxSessions = DEFAULT_MAX_SESSIONS) {
-    const existing = map.get(key);
-    if (existing) {
-        // LRU touch: delete + re-insert to move to back of iteration order.
-        map.delete(key);
-        map.set(key, existing);
-        return existing;
-    }
-    if (map.size >= maxSessions) {
-        const oldest = map.keys().next().value;
-        if (oldest !== undefined)
-            map.delete(oldest);
-    }
-    const ring = new RingBuffer();
-    map.set(key, ring);
-    return ring;
-}
-/**
- * Append a recall to a ring. The `anchoredOn` argument carries the
- * memoryId of the AnchoringHint that fired on THIS recall (or undefined
- * if no hint). detectAnchoring reads it next time for cooldown gating.
- */
-export function appendRecall(ring, queryHash, topMemoryId, anchoredOn) {
-    const entry = {
-        queryHash,
-        topMemoryId,
-        ts: new Date().toISOString(),
-    };
-    if (anchoredOn !== undefined)
-        entry.anchoredOn = anchoredOn;
-    ring.append(entry);
-}
-/** Snapshot a ring as a readonly RecallHistorySnapshot. */
-export function snapshotRing(ring) {
-    return ring.snapshot();
-}
-//# sourceMappingURL=recall-history.js.map

package/dist/src/recall-history.js.map

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

package/dist/src/recall-scope.js

@@ -1,89 +0,0 @@
-/**
- * v1.25.0 — recall-side scope predicates, extracted from api.ts into a leaf
- * module so shared.ts (which api.ts imports) can apply the same default-deny
- * rule to searchBothHybrid's internal candidate loads without an import
- * cycle. Mirrors the v39 `project-identity.ts` precedent. api.ts imports
- * these for its own call sites AND re-exports them for back-compat
- * (`api.isPrivateScope`, test imports of `passesScopeFilterForRecall`).
- */
-import { RECALL_DEFAULT_DENY_SCOPES } from './store.js';
-/**
- * v1.2.1: source-agnostic private-scope detector. A scope string is treated
- * as private when it has the shape `<lowercase-source>:private:<rest>`.
- *
- * Examples that match:
- *   slack:private:Cabc, github:private:owner/repo, jira:private:PROJ-1
- * Examples that DO NOT match:
- *   slack:public:Cgeneral, acme:public:my-private-channel, null, '',
- *   'unknown:legacy', 'private' (alone), 'private:foo' (no source prefix).
- *
- * Used by api.recall, mcp/server.ts (hippo_recall + hippo_context),
- * cli.ts (cmdRecall + cmdExplain + continuity), shared.ts (searchBothHybrid
- * recall mode). Keep these in sync — the export is the single source of
- * truth so connector work cannot drift.
- */
-export const PRIVATE_SCOPE_RE = /^[a-z][a-z0-9_-]*:private:/;
-function isScopeString(value) {
-    return typeof value === 'string';
-}
-/** True when `scope` matches the `<source>:private:*` shape. */
-export function isPrivateScope(scope) {
-    if (!isScopeString(scope))
-        return false;
-    return PRIVATE_SCOPE_RE.test(scope);
-}
-/**
- * Recall-side scope filter — the canonical JS half of the recall default-deny
- * rule (the SQL half lives in `loadSearchRows` via `loadRecallSearchEntries`).
- *
- * - When `requested` is set and non-empty: exact match required.
- * - When `requested` is undefined/empty: default-deny on any
- *   `<source>:private:*` scope and on the `RECALL_DEFAULT_DENY_SCOPES`
- *   quarantine buckets. `null` and public scopes pass.
- *
- * @internal v1.7.2 — exported for test parity with
- * `RECALL_DEFAULT_DENY_SCOPES` (single-source-of-truth verification). NOT part
- * of the public API surface; not re-exported from `src/index.ts`. Subject to
- * change without semver bump.
- */
-export function passesScopeFilterForRecall(scope, requested) {
-    if (requested !== undefined && requested !== '') {
-        return scope === requested;
-    }
-    if (scope === null)
-        return true;
-    if (isPrivateScope(scope))
-        return false;
-    // SAFETY: RECALL_DEFAULT_DENY_SCOPES (v1.7.2, single source of truth
-    // shared with the SQL clause in loadSearchRows) is a readonly tuple of
-    // string literals. Cast the array to readonly string[] so .includes()
-    // accepts arbitrary string scopes without a cast on the input (codex
-    // P0-2: casting `scope` would defeat the constant's safety).
-    if (RECALL_DEFAULT_DENY_SCOPES.includes(scope))
-        return false;
-    return true;
-}
-/**
- * v1.25.0 — the CLI `--scope` variant of the recall filter (JS half of the
- * SQL 'default-deny-or-exact' mode in loadSearchRows).
- *
- * The CLI flag predates the envelope column as a TAG-boost ranking hint
- * (`scope:<v>` tags, HIPPO_SCOPE, detectScope()), so an explicit `--scope X`
- * UNLOCKS envelope scope X in addition to the default-admitted set — it does
- * NOT narrow the result to X (that would return zero rows for every
- * tag-scoped workflow, whose envelope scope is NULL). api.recall keeps the
- * narrowing 'exact' semantics via `passesScopeFilterForRecall`.
- *
- * Note the unlock applies to whatever scope was explicitly named — including
- * a private scope or a quarantine bucket (`--scope unknown:legacy`). That is
- * deliberate owner access, identical in reach to api.recall's exact-match
- * for the same input; only NON-requested private/quarantine scopes stay
- * denied.
- */
-export function passesCliRecallScopeFilter(scope, requested) {
-    if (requested !== undefined && requested !== '' && scope === requested) {
-        return true;
-    }
-    return passesScopeFilterForRecall(scope, undefined);
-}
-//# sourceMappingURL=recall-scope.js.map

package/dist/src/recall-scope.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"recall-scope.js","sourceRoot":"","sources":["../../src/recall-scope.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,0BAA0B,EAAE,MAAM,YAAY,CAAC;AAExD;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,4BAA4B,CAAC;AAE7D,SAAS,aAAa,CAAC,KAAgC;IACrD,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC;AACnC,CAAC;AAED,gEAAgE;AAChE,MAAM,UAAU,cAAc,CAAC,KAAgC;IAC7D,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACxC,OAAO,gBAAgB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AACtC,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,0BAA0B,CACxC,KAAoB,EACpB,SAA6B;IAE7B,IAAI,SAAS,KAAK,SAAS,IAAI,SAAS,KAAK,EAAE,EAAE,CAAC;QAChD,OAAO,KAAK,KAAK,SAAS,CAAC;IAC7B,CAAC;IACD,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAChC,IAAI,cAAc,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACxC,qEAAqE;IACrE,uEAAuE;IACvE,sEAAsE;IACtE,qEAAqE;IACrE,6DAA6D;IAC7D,IAAK,0BAAgD,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACpF,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,0BAA0B,CACxC,KAAoB,EACpB,SAA6B;IAE7B,IAAI,SAAS,KAAK,SAAS,IAAI,SAAS,KAAK,EAAE,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACvE,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,0BAA0B,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;AACtD,CAAC"}

package/dist/src/recall-trace.js

@@ -1,183 +0,0 @@
-/**
- * LC1 — retrieval-trace persistence
- * (docs/plans/2026-08-02-lc1-recall-trace-persistence.md).
- *
- * Single producer for the `recall_traces` / `recall_trace_results` /
- * `recall_trace_outcomes` tables (schema v40). Every recall on the three
- * wired paths (api.recall, api.getContext, CLI cmdRecall) writes a trace
- * row: the ids + ranks + scores actually returned. Outcome events that
- * resolve their targets from last-retrieval state link back to the trace
- * they judge via `recordTraceOutcome`. This is the (query, shown, outcome)
- * training triple every Track LC learned component needs.
- *
- * All writes here are fail-soft: a broken trace write must never break the
- * surrounding recall or outcome call. Failures are logged to stderr and
- * swallowed (matches the api.ts ~2843 "audit emit failed" precedent — no
- * new debug env var).
- */
-import { createHash } from 'node:crypto';
-import { openHippoDb, closeHippoDb } from './db.js';
-/**
- * Strip a RerankStep down to {stage, multiplier, scoreBefore, scoreAfter}
- * before persisting (F3 privacy fix, codex cross-model finding). `note` is
- * free-form human text — the CLI's goal-boost step embeds matched goal tag
- * text there, so persisting it verbatim would leak raw user content into
- * training data via `rerank_json`. Only the four structured fields survive;
- * any other/future free-form field is dropped by construction (allowlist,
- * not a denylist).
- */
-function sanitizeRerankSteps(steps) {
-    return steps.map((s) => ({
-        stage: s.stage,
-        multiplier: s.multiplier,
-        scoreBefore: s.scoreBefore,
-        scoreAfter: s.scoreAfter,
-    }));
-}
-/**
- * Insert a `recall_traces` row + its `recall_trace_results` rows in ONE
- * transaction, on the connection handed in. Fail-soft: never throws —
- * logs to stderr and returns null on any failure.
- *
- * Connection policy (per the plan): api.recall calls this directly on its
- * own already-open handle. api.getContext and CLI cmdRecall go through
- * `writeRecallTraceAtRoot` instead, since their audit handles are already
- * closed by the time tracing runs.
- */
-export function writeRecallTrace(db, input) {
-    try {
-        const queryHash = createHash('sha256').update(input.query).digest('hex').slice(0, 16);
-        const ts = new Date().toISOString();
-        db.exec('BEGIN');
-        try {
-            const insertTrace = db.prepare(`
-        INSERT INTO recall_traces (ts, tenant_id, session_id, pipeline, query_hash, query_length, result_count, explain_mode)
-        VALUES (?, ?, ?, ?, ?, ?, ?, ?)
-      `);
-            const traceResult = insertTrace.run(ts, input.tenantId, input.sessionId ?? null, input.pipeline, queryHash, input.query.length, input.results.length, input.explainMode ? 1 : 0);
-            const traceId = Number(traceResult.lastInsertRowid);
-            const insertResult = db.prepare(`
-        INSERT INTO recall_trace_results (trace_id, tenant_id, memory_id, result_rank, score, rerank_json)
-        VALUES (?, ?, ?, ?, ?, ?)
-      `);
-            input.results.forEach((r, i) => {
-                insertResult.run(traceId, input.tenantId, r.memoryId, i + 1, r.score, r.rerankSteps && r.rerankSteps.length > 0 ? JSON.stringify(sanitizeRerankSteps(r.rerankSteps)) : null);
-            });
-            db.exec('COMMIT');
-            return traceId;
-        }
-        catch (error) {
-            db.exec('ROLLBACK');
-            throw error;
-        }
-    }
-    catch (error) {
-        // eslint-disable-next-line no-console
-        console.error(`[hippo] recall trace write failed: ${error instanceof Error ? error.message : String(error)}`);
-        return null;
-    }
-}
-/**
- * Convenience wrapper: opens a fresh short-lived connection at `root`,
- * writes the trace, and closes. Returns the new trace id, or null on any
- * failure (fail-soft).
- *
- * Used at api.getContext and CLI cmdRecall — sites where the block's own
- * convention is per-call handles (writeEntry, saveIndex) and the earlier
- * audit handles are already closed. NOT used by api.recall, which must
- * reuse the caller's open handle (v1.11.5 no-side-effects contract,
- * tests/api-recall-no-side-effects.test.ts).
- *
- * F1 structural fix (replaces the earlier stamp-then-clear design): this
- * function does NOT touch the `last_trace_id` meta key. Stamping lived here
- * originally, on its own connection, separate from the `last_retrieval_ids`
- * write in `saveIndex` — two connections meant two commits, so a crash or
- * a failed second write could advance one without the other. LOCKSTEP
- * INVARIANT: `last_trace_id` must only ever advance in the SAME write as
- * `last_retrieval_ids`. The caller now does: call this function FIRST, set
- * `localIndex.last_trace_id` from the returned id, THEN call `saveIndex`
- * once — `saveIndex` persists both meta keys in one transaction
- * (store.ts). Call sites that trace WITHOUT advancing `last_retrieval_ids`
- * (CLI cmdRecall's zero-result path, getContext's empty-result path) simply
- * never touch `localIndex` at all — they can't desync by construction.
- *
- * Fail-soft: never throws, including on connection failure.
- */
-export function writeRecallTraceAtRoot(root, input) {
-    let db;
-    try {
-        db = openHippoDb(root);
-    }
-    catch (error) {
-        // eslint-disable-next-line no-console
-        console.error(`[hippo] recall trace connection failed: ${error instanceof Error ? error.message : String(error)}`);
-        return null;
-    }
-    try {
-        return writeRecallTrace(db, input);
-    }
-    finally {
-        closeHippoDb(db);
-    }
-}
-/**
- * Record an outcome event against a trace, linking the (query, shown,
- * outcome) triple. Called ONLY where the credited ids actually come from
- * the last-retrieval mechanism (api.outcomeForLastRecall and any outcome
- * flow that resolves its targets from last-retrieval state) or from an
- * SDK caller's explicit `traceId` opt — never unconditionally from
- * api.outcome, which would mislink an explicit-id caller to a stale,
- * unrelated trace.
- *
- * Lives in its own append-only table, not audit_log metadata: audit_log is
- * pruned by `pruneAuditLog`, and pruning must never erase training data.
- *
- * F4 validation (codex cross-model finding): `traceId`/`memoryIds` reach
- * this function from caller-side state (`last_trace_id` / applied outcome
- * ids) that can go stale relative to the trace it names — a forgotten
- * memory, a tenant switch mid-session, or a race between two callers. Two
- * checks run before the insert, both skip silently (console.error one
- * line) rather than throw:
- *   1. The named trace must exist and belong to `input.tenantId` — a
- *      tenant mismatch or a dangling id (deleted trace) skips.
- *   2. `input.memoryIds` is intersected against the trace's OWN
- *      `recall_trace_results.memory_id` set — only ids that trace actually
- *      returned are recorded. An id that was never in this trace's result
- *      set (stale caller state) is silently dropped rather than recorded
- *      as a false credit. If the intersection is empty, no row is written.
- *
- * Fail-soft: never throws.
- */
-export function recordTraceOutcome(db, input) {
-    try {
-        // SAFETY: row shape matches the single `tenant_id` column named in the
-        // SELECT above; sqlite returns undefined when no row matches.
-        const trace = db.prepare(`SELECT tenant_id FROM recall_traces WHERE id = ?`).get(input.traceId);
-        if (!trace || trace.tenant_id !== input.tenantId) {
-            // eslint-disable-next-line no-console
-            console.error(`[hippo] recall trace outcome skipped: trace ${input.traceId} missing or tenant mismatch`);
-            return;
-        }
-        // SAFETY: row shape matches the single `memory_id` column named in the
-        // SELECT above.
-        const memberRows = db
-            .prepare(`SELECT memory_id FROM recall_trace_results WHERE trace_id = ?`)
-            .all(input.traceId);
-        const members = new Set(memberRows.map((r) => r.memory_id));
-        const credited = input.memoryIds.filter((id) => members.has(id));
-        if (credited.length === 0) {
-            // eslint-disable-next-line no-console
-            console.error(`[hippo] recall trace outcome skipped: no credited ids intersect trace ${input.traceId}'s results`);
-            return;
-        }
-        db.prepare(`
-      INSERT INTO recall_trace_outcomes (trace_id, ts, tenant_id, outcome, memory_ids_json)
-      VALUES (?, ?, ?, ?, ?)
-    `).run(input.traceId, new Date().toISOString(), input.tenantId, input.outcome, JSON.stringify(credited));
-    }
-    catch (error) {
-        // eslint-disable-next-line no-console
-        console.error(`[hippo] recall trace outcome write failed: ${error instanceof Error ? error.message : String(error)}`);
-    }
-}
-//# sourceMappingURL=recall-trace.js.map

package/dist/src/recall-trace.js.map

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