hippo-memory 1.70.0 → 1.71.0

package/dist/objects/skills.js

@@ -1,34 +1,11 @@
-/**
- * Skills as a first-class, versioned object.
- *
- * A `skill` is a reusable, agent-followable capability: an `instructions` body
- * plus an optional `trigger` ("when to apply"), evolving via the supersede delta
- * lifecycle. "Executable" is scoped to an agent-followable INSTRUCTION that, once
- * exported into the agent's in-force rules (AGENTS.md / CLAUDE.md) via
- * `exportSkills`, is executed by the agent reading it. Literal code/command
- * execution is deferred (security; a future sandbox). The distinguishing
- * capability is therefore the EXPORT renderer, not a runtime.
- *
- * Reuses the process/decision supersede machinery verbatim (superseded_by self-FK
- * + CAS + INSERT-preflight + server-derived version + change_summary + supersede
- * tenant-match trigger). It DROPS process's `steps` (a skill's content is a single
- * `instructions` body) and ADDS `trigger` (stored in the `trigger_text` column -
- * `trigger` is a SQLite reserved keyword).
- *
- * The `skills` 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 renders ACTIVE skills only.
- */
+/** Skill object: an agent-followable `instructions` body plus an optional `trigger`, evolving via supersession.
+ *  `exportSkills` renders ACTIVE skills into AGENTS.md / CLAUDE.md rules; running code from a skill is deferred (security).
+ *  `trigger` is stored in `trigger_text` because it is a SQLite reserved keyword. */
 import { BadRequestError } from '../core/api-errors.js';
 import { assertTenantId } from '../store/tenant.js';
 import { checkText, requireLine } from './fields.js';
 import { closeObjectAt, listObjectsAt, objectByIdAt, saveObjectAt } from './lifecycle.js';
 import { sqliteObjects } from '../store/sqlite/objects-group.js';
-// ---------------------------------------------------------------------------
-// Domain types
-// ---------------------------------------------------------------------------
 export const VALID_SKILL_STATES = new Set([
     'active',
     'superseded',
@@ -42,9 +19,6 @@ export const MAX_SKILL_TRIGGER_LEN = 1024;
 /** Aggregate bound on a single export render so the export body is never unbounded.
  *  Realistic active-skill counts are tens; 1000 is a generous bound. */
 export const MAX_EXPORT_SKILLS = 1000;
-// ---------------------------------------------------------------------------
-// Validation
-// ---------------------------------------------------------------------------
 /** The trigger as stored, or null for none. One line, because a newline would forge a heading inside the exported **When:** line. */
 function checkTrigger(trigger) {
     if (trigger === undefined || trigger === null || trigger.trim().length === 0)
@@ -57,9 +31,7 @@ function checkTrigger(trigger) {
     }
     return trigger;
 }
-/** Recall-surface content for the memory mirror: name + optional trigger +
- *  instructions. Named (mirrors buildProcessContent) so the recall surface is
- *  deterministic + unit-testable. */
+/** Recall-surface content for the memory mirror: name, optional trigger, instructions. */
 function buildSkillContent(skillName, instructions, trigger) {
     let content = skillName;
     if (trigger)
@@ -96,22 +68,11 @@ export const SKILL = {
         };
     },
 };
-// ---------------------------------------------------------------------------
-// Public API
-// ---------------------------------------------------------------------------
-/**
- * Create a skill (or a new version that supersedes an existing one). Writes the
- * memory mirror + the skills row in the `objects` store group's one transaction. When
- * supersedesSkillId is given, the referenced ACTIVE row is preflighted (status +
- * version) BEFORE the INSERT, then CAS-UPDATEd -> superseded in the same transaction;
- * the new version = predecessor.version + 1 (server-derived).
- */
+/** Create a skill, or a new version superseding an existing one, in the `objects` store group's one transaction. */
 export function saveSkill(hippoRoot, tenantId, opts, actor = 'cli') {
     return saveObjectAt(SKILL, { hippoRoot, tenantId, actor }, opts);
 }
-/**
- * Close (retire) an active skill. A superseded row is terminal.
- */
+/** Close (retire) an active skill; a superseded row is terminal. */
 export function closeSkill(hippoRoot, tenantId, id, actor = 'cli') {
     return closeObjectAt(hippoRoot, SKILL, tenantId, id, actor);
 }
@@ -124,15 +85,8 @@ export function loadSkills(hippoRoot, tenantId, opts = {}) {
 export function loadActiveSkills(hippoRoot, tenantId, opts = {}) {
     return loadSkills(hippoRoot, tenantId, { status: 'active', limit: opts.limit });
 }
-/**
- * Render the tenant's ACTIVE skills into ONE AGENTS.md / CLAUDE.md-style markdown
- * block (one H2 per skill, ordered by skill_name ASC for determinism), and RETURN
- * the string. Does NOT write any file. Returns '' when there are no active skills.
- *
- * skill_name is single-line (validated on save) so it cannot break the H2 header;
- * instructions are emitted verbatim (operator content). Bounded by MAX_EXPORT_SKILLS
- * active rows; each field is capped on save, so the rendered string is bounded.
- */
+/** Render the tenant's ACTIVE skills into one AGENTS.md / CLAUDE.md-style markdown block (H2 per skill, ordered by skill_name) and return it; writes no file.
+ *  Bounded by MAX_EXPORT_SKILLS rows; instructions are emitted verbatim. */
 export function exportSkills(hippoRoot, tenantId) {
     assertTenantId('exportSkills', tenantId);
     return skillsBlock(sqliteObjects(hippoRoot).activeSkillsByName(tenantId, MAX_EXPORT_SKILLS));

package/dist/postinstall.js

@@ -9,9 +9,8 @@ function main() {
     if (envSkipPostinstall())
         return;
     try {
-        // Repair-only, for users who opted in (a Codex update can restore the real binary over our shim).
-        // Swapping the binary from postinstall is a consent violation that supply-chain scanners read as
-        // hijacking, so first install is `hippo hook install codex` only.
+        // Repair-only, for users who opted in (a Codex update can restore the real binary over our shim): swapping the binary from postinstall
+        // is a consent violation that supply-chain scanners read as hijacking, so first install is `hippo hook install codex` only.
         repairCodexWrapperIfInstalled();
     }
     catch (err) {
@@ -31,16 +30,8 @@ function main() {
         // Never fail package install because the install hint could not be printed.
     }
 }
-/**
- * Read-only nudge: if Claude Code is detected on the machine and the Hippo
- * UserPromptSubmit hook is NOT yet installed, print a short message pointing
- * the user at `hippo init`. No config writes. Silent otherwise.
- *
- * We avoid aggressively auto-patching ~/.claude/settings.json from a package
- * postinstall — that's surprising, breaks the principle of least authority,
- * and trips security scanners. A one-line visible prompt is the friendly
- * middle ground.
- */
+/** Read-only nudge: if Claude Code is detected and the Hippo UserPromptSubmit hook is not installed, point the user at `hippo init`.
+ * It never patches ~/.claude/settings.json from a package postinstall: surprising, against least authority, and trips security scanners. */
 function printClaudeCodeNudge() {
     const claudeDir = claudeConfigDir(os.homedir());
     if (!fs.existsSync(claudeDir))
@@ -76,12 +67,8 @@ function printClaudeCodeNudge() {
     line('To skip this message on future installs: export HIPPO_SKIP_POSTINSTALL=1');
     line('');
 }
-/**
- * Read-only nudge: if the Codex CLI is on PATH and the Hippo session-capture
- * wrapper is NOT installed, print the opt-in command. Mirrors the Claude Code
- * nudge above — same least-authority reasoning: we tell the user what to run,
- * we never swap their binary for them.
- */
+/** Read-only nudge: if the Codex CLI is on PATH and the session-capture wrapper is not installed, print the opt-in command;
+ * same least-authority reasoning as the Claude Code nudge, we never swap the user's binary. */
 function printCodexNudge() {
     if (isCodexWrapperInstalled())
         return;

package/dist/predictions/planning-fallacy.d.ts

@@ -1,15 +1,8 @@
 import type { AppendAuditOpts } from '../store/audit.js';
 import { type ForwardClaimMatch } from '../learn/forward-claim-detector.js';
 import type { PlanningFallacyEvidence } from '../store/planning-fallacy-evidence.js';
-/**
- * Surface delivered on `RecallResult.planningFallacyHint` when an
- * agent's recall query carries a forward-prediction phrase AND the closest
- * matching prediction class has closed historical data.
- *
- * The agent sees its track record at the moment of forecasting, anchoring
- * on the outside view (Lovallo-Kahneman 2003) rather than the inside-view
- * inside the planning fallacy.
- */
+/** Surface delivered on `RecallResult.planningFallacyHint` when a recall query carries a forward-prediction phrase and the closest class has closed history,
+ *  so the agent sees its own track record at the moment of forecasting. */
 export interface PlanningFallacyHint {
     classTag: string;
     /** Verbatim PredictionBaserate.summary, e.g.
@@ -17,50 +10,34 @@ export interface PlanningFallacyHint {
     baserateSummary: string;
     /** Discriminator vs hypothetical future manual-override hints. */
     source: 'j3.2-auto';
-    /** The regex match snippet that triggered detection. Lets the agent
-     *  see WHY the hint appeared and self-correct if detection misfires
-     *  (e.g. "I wasn't predicting; ignore"). */
+    /** The regex match snippet that triggered detection, so the agent sees WHY the hint appeared and can self-correct if detection misfired. */
     detectedPhrase: string;
     nClosed: number;
     /** Null only when every closed-row had estimate_value=0 (ratio undefined). */
     meanRatio: number | null;
 }
-/**
- * "Watching" variant emitted when the forward-claim regex matched but no
- * PlanningFallacyHint baserate was returned. Silence was the most common
- * real-world failure: a natural-language query carries a
- * forward-claim phrase but its non-stopword tokens don't overlap with
- * any prediction class tag, so hippo emitted nothing despite
- * the regex match. The watching variant surfaces the detection event
- * + a one-line suggestion so the agent can either re-tag the prediction
- * or pass the suggestion through to the user.
- */
+/** "Watching" variant emitted when the forward-claim regex matched but no baserate hint was returned (no prediction class tag overlaps the query's tokens).
+ *  It surfaces the detection plus a one-line suggestion so the agent can re-tag the prediction or pass the suggestion to the user. */
 export interface PlanningFallacyWatching {
     /** The forward-claim phrase the detector matched (verbatim regex match snippet). */
     detectedPhrase: string;
-    /** Why hippo couldn't produce a baserate hint despite the match.
-     *  - 'no_class_match': no class scored >=1 on token overlap.
-     *  - 'tiebreak': >=2 classes tied at the same best score (silent on ambiguity). */
+    /** Why hippo could not produce a baserate hint despite the match: 'no_class_match' (no class scored >=1 on token overlap)
+     *  or 'tiebreak' (>=2 classes tied at the best score; silent on ambiguity). */
     reason: 'no_class_match' | 'tiebreak';
     /** One-line agent-facing suggestion for how the user can give hippo
      *  enough signal to produce a baserate next time. */
     suggestion: string;
 }
-/**
- * What `decidePlanningFallacy` hands to recall. Carries EITHER `hint` (baserate
- * available) OR `watching` (regex fired, no baserate), or NEITHER (mode=off,
- * no queryText, no regex match, or nClosed=0 silent path). Never both.
- */
+/** What `decidePlanningFallacy` hands to recall: EITHER `hint` (baserate available) OR `watching` (regex fired, no baserate), or NEITHER (mode=off,
+ *  no queryText, no regex match, or nClosed=0). Never both. */
 export interface PlanningFallacyOutput {
     hint?: PlanningFallacyHint;
     watching?: PlanningFallacyWatching;
 }
 export type AutodebiasMode = 'off' | 'regex';
 export interface ComputePlanningFallacyHintOpts {
-    /** Override env. When undefined, reads process.env.HIPPO_AUTODEBIAS at
-     *  call time (per-call to allow test-time env toggling without module
-     *  reload). 'off' short-circuits to null BEFORE the regex gate so the
-     *  AUTODEBIAS=off path pays zero work. */
+    /** Override env; undefined reads process.env.HIPPO_AUTODEBIAS per call (so tests can toggle it).
+     *  'off' short-circuits to null before the regex gate. */
     mode?: AutodebiasMode;
 }
 /** The output a claim earns from its evidence, and the audit row that records the decision when there is one. */

package/dist/rerankers/clef.js

@@ -1,15 +1,14 @@
 import { envClefEndpoint, envClefEndpointToken, envClefTimeoutMs, envCloudflareAccountId, envCloudflareApiToken } from '../util/env.js';
 import { buildRelevanceRequest, JEV_DEFAULT_TOP_K, rankByScores } from './jev.js';
 import { createOutageWarning } from './outage-warning.js';
-import { rerankerPost } from './remote.js';
+import { rerankerPost, RERANKER_MAX_REPLY_BYTES } from './remote.js';
+import { readCappedJson } from '../util/capped-json.js';
 import { isJsonObject } from '../util/json.js';
 import { errorMessage } from '../util/log.js';
 const RAY_ID_MAX_CHARS = 64;
 const CLEF_MODELS = ['clef-flash', 'clef'];
 const DEFAULT_TIMEOUT_MS = 15_000;
 const MAX_TIMEOUT_MS = 120_000;
-// 64 answers fit in a few KB; 1 MiB leaves room for a verbose envelope.
-const MAX_REPLY_BYTES = 1024 * 1024;
 // Workers AI rejects a request with more than 64 questions, one per candidate here.
 const MAX_CANDIDATES = 64;
 const ACCOUNT_ID = /^[0-9a-f]{32}$/i;
@@ -111,33 +110,6 @@ export function parseClefReply(body, n, model, requireModel) {
         outputTokens: isNumber(usage.output_tokens) ? usage.output_tokens : undefined,
     };
 }
-// The timeout bounds time, not bytes: a hostile endpoint could stream a huge 2xx body into memory.
-async function readCappedJson(resp) {
-    if (!resp.body)
-        throw new Error('reply has no body');
-    const reader = resp.body.getReader();
-    const decoder = new TextDecoder();
-    let raw = '';
-    let received = 0;
-    for (;;) {
-        const { done, value } = await reader.read();
-        if (done)
-            break;
-        received += value.byteLength;
-        if (received > MAX_REPLY_BYTES) {
-            await reader.cancel();
-            throw new Error(`reply over ${MAX_REPLY_BYTES} bytes`);
-        }
-        raw += decoder.decode(value, { stream: true });
-    }
-    raw += decoder.decode();
-    try {
-        return JSON.parse(raw);
-    }
-    catch {
-        throw new Error('reply is not JSON');
-    }
-}
 async function requestScores(model, query, head, route) {
     const { state, questions } = buildRelevanceRequest(query, head);
     // Strict parse: parseInt would read "15s" as 15 ms, and Node clamps a delay past 2^31-1 to 1 ms.
@@ -153,7 +125,7 @@ async function requestScores(model, query, head, route) {
         await resp.body?.cancel();
         throw new Error(`HTTP ${resp.status}${ray ? `, ray ${ray}` : ''}`);
     }
-    const body = await readCappedJson(resp);
+    const body = await readCappedJson(resp, RERANKER_MAX_REPLY_BYTES);
     const parsed = parseClefReply(body, head.length, model, route.backend === 'cloudflare');
     if (isRejection(parsed))
         throw new Error(parsed);

package/dist/rerankers/cross-encoder.js

@@ -7,9 +7,8 @@ const DEFAULT_CROSS_ENCODER_TOP_K = 50;
 const MODEL_NAME = 'Xenova/ms-marco-MiniLM-L-6-v2';
 const _require = createRequire(import.meta.url);
 const TRANSFORMERS_PACKAGES = ['@huggingface/transformers', '@xenova/transformers'];
-// Returns the ESM entry URL, the same build src/store/embeddings/index.ts imports. A
-// require-style resolve picks the CommonJS build and puts a second copy of
-// the library, with its own ONNX sessions, in the process.
+// Returns the ESM entry URL, the same build src/store/embeddings/index.ts imports; a require-style resolve picks the CommonJS build and
+// puts a second copy of the library, with its own ONNX sessions, in the process.
 function resolveTransformersPackage() {
     for (const name of TRANSFORMERS_PACKAGES) {
         try {
@@ -47,9 +46,8 @@ async function loadTransformersModule() {
 }
 let pipelineLoading = null;
 const outage = createOutageWarning('cross-encoder', 'falling back to identity ordering');
-// NOT the text-classification pipeline: this model is a num_labels=1
-// regression head, and that pipeline softmaxes a length-1 logit vector, which
-// is identically 1.0 for every input. Read the logit, then squash it.
+// NOT the text-classification pipeline: this is a num_labels=1 regression head and that pipeline softmaxes a length-1 logit vector (always 1.0).
+// Read the logit, then squash it.
 async function buildPipeline() {
     try {
         const mod = await loadTransformersModule();

package/dist/rerankers/jev.js

@@ -1,7 +1,9 @@
 import { envJevModel, envJevTimeoutMs, envTypesafeApiKey } from '../util/env.js';
 import { redactSecretsStrict } from '../util/secret-detect.js';
 import { createOutageWarning } from './outage-warning.js';
-import { rerankerPost } from './remote.js';
+import { rerankerPost, RERANKER_MAX_REPLY_BYTES } from './remote.js';
+import { readCappedJson } from '../util/capped-json.js';
+import { isJsonNumber, isJsonObject } from '../util/json.js';
 import { compareScoresDesc } from '../core/compare.js';
 import { errorMessage } from '../util/log.js';
 const REQUEST_ID_MAX_CHARS = 64;
@@ -19,14 +21,16 @@ function truncate(s, n) {
 // Number.isFinite rejects a string or null without coercing it, which the
 // declared type cannot promise about a third-party payload.
 function isProbability(v) {
-    return v !== undefined && Number.isFinite(v) && v >= 0 && v <= 1;
+    return isJsonNumber(v) && Number.isFinite(v) && v >= 0 && v <= 1;
 }
 // A half-scored list ranks worse than the order it would replace, so one bad
 // answer voids the whole response.
-function parseScores(answers, n) {
+function parseScores(body, n) {
+    const answers = isJsonObject(body) ? body.answers : undefined;
     const out = [];
     for (let i = 1; i <= n; i++) {
-        const v = answers?.[`c${i}`]?.noul;
+        const answer = isJsonObject(answers) ? answers[`c${i}`] : undefined;
+        const v = isJsonObject(answer) ? answer.noul : undefined;
         if (!isProbability(v))
             return null;
         out.push(v);
@@ -67,8 +71,7 @@ async function requestScores(query, head) {
         await resp.body?.cancel();
         throw new Error(`HTTP ${resp.status}${requestId ? `, request ${requestId}` : ''}`);
     }
-    const body = await resp.json();
-    const scores = parseScores(body.answers, head.length);
+    const scores = parseScores(await readCappedJson(resp, RERANKER_MAX_REPLY_BYTES), head.length);
     if (!scores)
         throw new Error('incomplete or out-of-range answers');
     return scores;

package/dist/rerankers/llm.d.ts

@@ -1,14 +1,5 @@
 import type { RerankerFn } from './types.js';
-/**
- * Track 3 reranker: listwise LLM rerank. Uses a customer-supplied
- * OpenAI-compatible endpoint. Gated on HIPPO_LLM_RERANKER_URL to prevent
- * accidental cost.
- *
- * Skeleton only; full characterisation is deferred.
- *
- * Timeout: defaults to 30s for the whole call, retries included; overridable
- * via HIPPO_LLM_RERANKER_TIMEOUT_MS. On timeout or any failure the reranker
- * falls back to identity ordering; recall must not hang on a wedged endpoint.
- */
+/** Track 3 reranker (skeleton): listwise LLM rerank on a customer-supplied OpenAI-compatible endpoint, gated on HIPPO_LLM_RERANKER_URL against accidental cost.
+ * Timeout is 30s for the whole call, retries included (HIPPO_LLM_RERANKER_TIMEOUT_MS); any failure falls back to identity ordering, so recall never hangs. */
 export declare function createLlmReranker(): RerankerFn;
 //# sourceMappingURL=llm.d.ts.map

package/dist/rerankers/llm.js

@@ -1,21 +1,14 @@
 import { envLlmRerankerKey, envLlmRerankerModel, envLlmRerankerTimeoutMs, envLlmRerankerUrl } from '../util/env.js';
 import { redactSecretsStrict } from '../util/secret-detect.js';
 import { createOutageWarning } from './outage-warning.js';
-import { rerankerPost } from './remote.js';
+import { rerankerPost, RERANKER_MAX_REPLY_BYTES } from './remote.js';
+import { readCappedJson } from '../util/capped-json.js';
+import { isJsonObject, isJsonString } from '../util/json.js';
 import { errorMessage } from '../util/log.js';
 const DEFAULT_LLM_RERANK_TOP_K = 20;
 const DEFAULT_TIMEOUT_MS = 30_000;
-/**
- * Track 3 reranker: listwise LLM rerank. Uses a customer-supplied
- * OpenAI-compatible endpoint. Gated on HIPPO_LLM_RERANKER_URL to prevent
- * accidental cost.
- *
- * Skeleton only; full characterisation is deferred.
- *
- * Timeout: defaults to 30s for the whole call, retries included; overridable
- * via HIPPO_LLM_RERANKER_TIMEOUT_MS. On timeout or any failure the reranker
- * falls back to identity ordering; recall must not hang on a wedged endpoint.
- */
+/** Track 3 reranker (skeleton): listwise LLM rerank on a customer-supplied OpenAI-compatible endpoint, gated on HIPPO_LLM_RERANKER_URL against accidental cost.
+ * Timeout is 30s for the whole call, retries included (HIPPO_LLM_RERANKER_TIMEOUT_MS); any failure falls back to identity ordering, so recall never hangs. */
 export function createLlmReranker() {
     const outage = createOutageWarning('llm', 'keeping the input order');
     return async (query, results, options) => {
@@ -42,6 +35,14 @@ export function createLlmReranker() {
         }));
     };
 }
+/** The first choice's message text, or '' when the reply has none. */
+function replyText(body) {
+    const choices = isJsonObject(body) ? body.choices : undefined;
+    const choice = Array.isArray(choices) ? choices[0] : undefined;
+    const message = isJsonObject(choice) ? choice.message : undefined;
+    const content = isJsonObject(message) ? message.content : undefined;
+    return isJsonString(content) ? content : '';
+}
 /** One chat-completions call; rejects with the reason when the reply holds no usable permutation. */
 async function requestPermutation(url, query, head) {
     const key = envLlmRerankerKey();
@@ -69,8 +70,7 @@ async function requestPermutation(url, query, head) {
         await resp.body?.cancel();
         throw new Error(`HTTP ${resp.status}`);
     }
-    const j = await resp.json();
-    const txt = j.choices?.[0]?.message?.content ?? '';
+    const txt = replyText(await readCappedJson(resp, RERANKER_MAX_REPLY_BYTES));
     const m = txt.match(/\[\s*(\d+(?:\s*,\s*\d+)*)\s*\]/);
     const parsed = m ? m[1].split(',').map((s) => parseInt(s.trim(), 10)) : [];
     const isPermutation = parsed.length === head.length &&

package/dist/rerankers/outage-warning.d.ts

@@ -2,6 +2,7 @@ export interface OutageWarning {
     failed(reason: string): void;
     answered(): void;
 }
-/** Warns when `name` starts failing, at most every five minutes while it keeps failing, and once when it answers again. `fallback` says what recall does meanwhile. */
+/** Warns when `name` starts failing, at most every five minutes while it keeps failing,
+ * and once when it answers again. `fallback` says what recall does meanwhile. */
 export declare function createOutageWarning(name: string, fallback: string): OutageWarning;
 //# sourceMappingURL=outage-warning.d.ts.map

package/dist/rerankers/outage-warning.js

@@ -1,7 +1,8 @@
 // One way for a reranker to report that it stopped working, without a line per recall.
 import { log } from '../util/log.js';
 const REPEAT_MS = 5 * 60_000;
-/** Warns when `name` starts failing, at most every five minutes while it keeps failing, and once when it answers again. `fallback` says what recall does meanwhile. */
+/** Warns when `name` starts failing, at most every five minutes while it keeps failing,
+ * and once when it answers again. `fallback` says what recall does meanwhile. */
 export function createOutageWarning(name, fallback) {
     let failures = 0;
     let unreported = 0;

package/dist/rerankers/remote.d.ts

@@ -1,3 +1,4 @@
+export declare const RERANKER_MAX_REPLY_BYTES: number;
 /** POST a scoring request. A dropped connection, 429 or 5xx is retried, since scoring changes nothing on the far side. */
 export declare function rerankerPost(url: string, init: RequestInit, budgetMs: number): Promise<Response>;
 //# sourceMappingURL=remote.d.ts.map

package/dist/rerankers/remote.js

@@ -2,6 +2,8 @@
 import { fetchWithRetry } from '../util/http-retry.js';
 // A Retry-After longer than this would outlast most budgets, so the answer is handed back and the reranker falls back.
 const RETRY_WAIT_CAP_MS = 2_000;
+// Every reranker reads its reply through this cap; the largest honest reply is a few KB, and 1 MiB leaves room for a verbose envelope.
+export const RERANKER_MAX_REPLY_BYTES = 1024 * 1024;
 /** POST a scoring request. A dropped connection, 429 or 5xx is retried, since scoring changes nothing on the far side. */
 export async function rerankerPost(url, init, budgetMs) {
     // The budget bounds the whole call, retries included, so recall never waits past the configured timeout.

package/dist/rerankers/types.d.ts

@@ -1,18 +1,6 @@
 import type { SearchResult } from '../core/search-types.js';
-/**
- * A reranker reorders (and optionally rescales) the candidate set produced
- * by hybridSearch's BM25 + cosine + MMR pipeline. Rerankers run AFTER MMR
- * de-duplication and BEFORE token-budget filtering, so the reranker sees
- * the full diversity-balanced candidate pool but does not see candidates
- * already filtered out by score-zero or supersession.
- *
- * Rerankers MUST be deterministic for a given (query, results) input
- * unless explicitly documented as stochastic (the LLM track, and the
- * hosted jev reranker, whose scores move slightly run to run).
- * Determinism is required for paired A/B and for the workload-validity gate.
- *
- * @returns Reordered (and optionally rescaled) results.
- */
+/** Reorders hybridSearch's candidates AFTER MMR de-duplication and BEFORE token-budget filtering, so it sees the full diverse pool.
+ * MUST be deterministic for a given (query, results) unless documented stochastic (LLM track, hosted jev): paired A/B and the validity gate need it. */
 export type RerankerFn = (query: string, results: SearchResult[], options?: RerankerOptions) => Promise<RerankResult[]>;
 /** JSON-serializable value. Per-track reranker config is opaque to the seam
  *  but must still be a concrete, serializable shape rather than `unknown`. */

package/dist/search/boosts.d.ts

@@ -1,10 +1,8 @@
 import { type MemoryEntry } from '../core/memory.js';
 import { type TemporalDirection, type TemporalRange } from './temporal.js';
-export declare const CHURN_STALE_RANK_MULTIPLIER = 0.5;
 export declare const STRENGTH_RANK_FLOOR = 0.5;
 export declare const STRENGTH_RANK_SPAN = 0.5;
 export declare function churnStaleFactor(entry: MemoryEntry): number;
-export declare function recencyBoost(entry: MemoryEntry, now: Date): number;
 /** Retrieval-time outcome nudge in [0.85, 1.15]; the bm25-outcome eval baseline ranks with it too. */
 export declare function outcomeMultiplier(entry: MemoryEntry): number;
 /** A DAG summary is a topic summary (level 2) or an entity profile (level 3); both take the same deboost. */

package/dist/search/boosts.js

@@ -5,7 +5,7 @@ import { pathBoostMultiplier } from './path-context.js';
 import { scopeMatch } from '../sharing/scope.js';
 import { temporalBoost } from './temporal.js';
 import { DAY_MS } from '../util/time.js';
-export const CHURN_STALE_RANK_MULTIPLIER = 0.5; // SHORTCUT: untuned; measure on real recall before any default.
+const CHURN_STALE_RANK_MULTIPLIER = 0.5; // SHORTCUT: untuned; measure on real recall before any default.
 const DECISION_TAG_BOOST = 1.2;
 // A memory tagged for the active scope outranks a neutral one; one tagged for another scope is demoted.
 const SCOPE_MATCH_BOOST = 1.5;
@@ -27,7 +27,7 @@ const FRESHNESS_WINDOW_MS = 7 * DAY_MS;
 export function churnStaleFactor(entry) {
     return entry.tags.includes(CHURN_STALE_TAG) ? CHURN_STALE_RANK_MULTIPLIER : 1.0;
 }
-export function recencyBoost(entry, now) {
+function recencyBoost(entry, now) {
     if (isRecencyAblated())
         return 1; // EVAL-ONLY ablation (see ablation.ts)
     const created = new Date(entry.created);

package/dist/search/goal-boost.d.ts

@@ -0,0 +1,23 @@
+import type { MemoryEntry } from '../core/memory.js';
+import type { RerankStep } from '../core/search-types.js';
+import type { ActiveGoals, GoalRecallLogRow } from '../store/goals.js';
+/** Options of {@link boostByGoals}. */
+export interface GoalStackBoostOpts {
+    sessionId: string;
+    tenantId: string;
+    limit: number;
+    /** Side-channel: one goal-boost `RerankStep` per boosted row, keyed by `entry.id` (a map because the helper re-spreads rows); only populated when passed. */
+    trace?: Map<string, RerankStep>;
+}
+/** The boosted, re-sorted rows and the `goal_recall_log` rows they earn. */
+export interface GoalStackBoost<R> {
+    results: R[];
+    log: GoalRecallLogRow[];
+}
+/** The goal-stack boost over goals already read, touching no store; a caller skips it under an explicit goal tag. Its log covers the top
+ *  `limit` rows and keeps those whose memory is global, since only the store can tell them apart; {@link localGoalRecallRows} drops those before the write. */
+export declare function boostByGoals<R extends {
+    entry: MemoryEntry;
+    score: number;
+}>(results: R[], active: ActiveGoals, opts: GoalStackBoostOpts): GoalStackBoost<R>;
+//# sourceMappingURL=goal-boost.d.ts.map

package/dist/search/goal-boost.js

@@ -0,0 +1,90 @@
+// src/search/goal-boost.ts: the goal-stack boost over goals already read; it ranks rows and touches no store.
+import { compareScoresDesc } from '../core/compare.js';
+const MAX_FINAL_MULTIPLIER = 3.0;
+/** The capped boost for one row whose tags match `matches` active goals. */
+function goalBoostMultiplier(entry, tags, matches, goalsByTag, policiesByGoalId) {
+    // Base 2.0x for first match, +0.5x per additional, capped at 3.0x.
+    let multiplier = Math.min(2.0 + 0.5 * (matches.length - 1), MAX_FINAL_MULTIPLIER);
+    // Compose per-policy multipliers per matched tag.
+    for (const tag of matches) {
+        const goal = goalsByTag.get(tag);
+        const policy = policiesByGoalId.get(goal.id);
+        if (!policy)
+            continue;
+        if (policy.policyType === 'error-prioritized' && tags.includes('error')) {
+            multiplier *= policy.errorPriority;
+        }
+        else if (policy.policyType === 'schema-fit-biased') {
+            // Linearly weight schema_fit in [0,1] up to (weightSchemaFit)x.
+            // Default 1.0 is a no-op.
+            multiplier *=
+                1.0 +
+                    Math.max(0, policy.weightSchemaFit - 1.0) *
+                        (entry.schema_fit ?? 0.5);
+        }
+        else if (policy.policyType === 'recency-first') {
+            multiplier *= policy.weightRecency;
+        }
+        else if (policy.policyType === 'hybrid') {
+            multiplier *= policy.weightOutcome;
+        }
+    }
+    // Hard cap AFTER all composition.
+    return Math.min(multiplier, MAX_FINAL_MULTIPLIER);
+}
+/** Log rows for the top `limit` boosted rows, one per matched goal. */
+function buildGoalRecallLog(boosted, matchesByEntryId, goalsByTag, opts) {
+    const { sessionId, tenantId, limit } = opts;
+    const recalledAt = new Date().toISOString();
+    const log = [];
+    for (const r of boosted.slice(0, limit)) {
+        const matches = matchesByEntryId.get(r.entry.id);
+        if (!matches || matches.length === 0)
+            continue;
+        for (const tag of matches) {
+            const goal = goalsByTag.get(tag);
+            if (!goal)
+                continue;
+            log.push({ goalId: goal.id, memoryId: r.entry.id, tenantId, sessionId, recalledAt, score: r.score });
+        }
+    }
+    return log;
+}
+/** The goal-stack boost over goals already read, touching no store; a caller skips it under an explicit goal tag. Its log covers the top
+ *  `limit` rows and keeps those whose memory is global, since only the store can tell them apart; {@link localGoalRecallRows} drops those before the write. */
+export function boostByGoals(results, active, opts) {
+    const { trace } = opts;
+    if (active.goals.length === 0)
+        return { results, log: [] };
+    const goalsByTag = new Map(active.goals.map((g) => [g.goalName, g]));
+    const policiesByGoalId = active.policies;
+    // Goal-tag matches per boosted row, keyed by entry id; a side table (not a spread-on marker property) so `boosted` stays exactly R[] with no cast-then-strip.
+    const matchesByEntryId = new Map();
+    const boosted = results
+        .map((r) => {
+        const tags = r.entry.tags ?? [];
+        const matches = tags.filter((t) => goalsByTag.has(t));
+        if (matches.length === 0)
+            return r;
+        const multiplier = goalBoostMultiplier(r.entry, tags, matches, goalsByTag, policiesByGoalId);
+        // Recall-trace side-channel: record the goal-boost step BEFORE the
+        // score is mutated, keyed by entry id; a pure read of r.score.
+        if (trace) {
+            trace.set(r.entry.id, {
+                stage: 'goal-boost',
+                multiplier,
+                scoreBefore: r.score,
+                scoreAfter: r.score * multiplier,
+                note: matches.join(', '),
+            });
+        }
+        matchesByEntryId.set(r.entry.id, matches);
+        // SAFETY: spreading a generic-constrained `r: R` widens to the spread's plain object type; only `score` changes, so the value still satisfies R.
+        return { ...r, score: r.score * multiplier };
+    })
+        // Deliberately a PLAIN stable score sort with no compareEntryIdentity tail: re-sorting an already deterministic ranking inherits its determinism via
+        // stability, and ties keep the prior (meaningful) rank instead of reordering by content.
+        .sort((a, b) => compareScoresDesc(a.score, b.score));
+    return { results: boosted, log: buildGoalRecallLog(boosted, matchesByEntryId, goalsByTag, opts) };
+}
+//# sourceMappingURL=goal-boost.js.map

package/dist/search/hybrid.d.ts

@@ -43,6 +43,8 @@ export interface HybridSearchOptions {
     vectorCandidates?: HybridVectorCandidates;
     /** Where vectors are read; hippo.db under `hippoRoot` when unset. */
     store?: HippoStore;
+    /** The deadline a caller already started for this recall's query embedding; a fresh budget when unset. */
+    queryEmbedDeadline?: AbortSignal;
 }
 /** BM25 blended with cosine similarity when stored vectors and a provider are available, BM25 * strength * recency otherwise. */
 export declare function hybridSearch(query: string, entries: MemoryEntry[], options?: HybridSearchOptions): Promise<SearchResult[]>;