hippo-memory 1.69.0 → 1.71.0

package/dist/dormant.js

@@ -1,137 +0,0 @@
-import { rejectionDigest } from './rejection.js';
-import { escapeLike } from './escape.js';
-const DEFAULT_LIST_LIMIT = 20;
-/**
- * Insert (or refresh) the dormant snapshot for `move.entry`. Does not touch
- * the `memories` row: the caller deletes it in the same transaction, so the
- * memory is never in both places or in neither.
- */
-export function insertDormantRow(db, move) {
-    db.prepare(`
-    INSERT INTO dormant_memories (tenant_id, id, content, entry_json, reason, strength, dormant_at)
-    VALUES (?, ?, ?, ?, ?, ?, ?)
-    ON CONFLICT(tenant_id, id) DO UPDATE SET
-      content = excluded.content,
-      entry_json = excluded.entry_json,
-      reason = excluded.reason,
-      strength = excluded.strength,
-      dormant_at = excluded.dormant_at
-  `).run(move.entry.tenantId, move.entry.id, move.entry.content, JSON.stringify(move.entry), move.reason, move.strength, move.dormantAt);
-}
-/**
- * Parse a stored snapshot back into a MemoryEntry, or null when the row no
- * longer matches the snapshot it carries (edited by hand, or truncated).
- */
-function parseSnapshot(row) {
-    try {
-        // SAFETY: entry_json is only written by insertDormantRow from a MemoryEntry;
-        // the id / tenant / content checks below reject a row edited out of shape.
-        const entry = JSON.parse(row.entry_json);
-        if (entry.id !== row.id || entry.tenantId !== row.tenant_id || entry.content !== row.content) {
-            return null;
-        }
-        return entry;
-    }
-    catch {
-        // A row that will not parse is out of shape, so it is not restorable.
-        return null;
-    }
-}
-function rowToDormantMemory(row) {
-    const entry = parseSnapshot(row);
-    return {
-        id: row.id,
-        tenantId: row.tenant_id,
-        content: row.content,
-        tags: entry && Array.isArray(entry.tags) ? entry.tags.map(String) : [],
-        strength: row.strength,
-        reason: row.reason,
-        dormantAt: row.dormant_at,
-    };
-}
-// The snapshot's scope as a `scope` column, so recall-scope's SQL fragments read it as they read memories.scope.
-const DORMANT_WITH_SCOPE = `(SELECT *, CASE WHEN json_valid(entry_json) THEN json_extract(entry_json, '$.scope') END AS scope FROM dormant_memories)`;
-const EVERY_SCOPE = { sql: '1', params: [] };
-/** A tenant's dormant memories whose scope `admit` passes, newest first, optionally filtered by search terms. */
-export function listDormantRows(db, tenantId, opts = {}, admit = EVERY_SCOPE) {
-    const terms = (opts.query ?? '').trim().split(/\s+/).filter((t) => t.length > 0);
-    const limit = opts.limit !== undefined && Number.isFinite(opts.limit) && opts.limit >= 1
-        ? Math.floor(opts.limit)
-        : DEFAULT_LIST_LIMIT;
-    const termClauses = terms.map(() => ` AND content LIKE ? ESCAPE '\\'`).join('');
-    // SAFETY: rows' shape matches the seven columns named in the SELECT.
-    const rows = db.prepare(`SELECT tenant_id, id, content, entry_json, reason, strength, dormant_at
-       FROM ${DORMANT_WITH_SCOPE}
-      WHERE tenant_id = ? AND ${admit.sql}${termClauses}
-      ORDER BY dormant_at DESC, id ASC
-      LIMIT ?`).all(tenantId, ...admit.params, ...terms.map((t) => `%${escapeLike(t)}%`), limit);
-    return rows.map(rowToDormantMemory);
-}
-/**
- * The stored snapshot for a tenant's dormant memory, or null when the tenant
- * has no dormant memory with that id (another tenant's id reads as absent).
- */
-export function readDormantSnapshot(db, tenantId, id) {
-    // SAFETY: row's shape matches the seven columns named in the SELECT.
-    const row = db.prepare(`SELECT tenant_id, id, content, entry_json, reason, strength, dormant_at
-       FROM dormant_memories WHERE tenant_id = ? AND id = ?`).get(tenantId, id);
-    return row ? toSnapshot(row) : null;
-}
-/** Every dormant memory of a tenant whose snapshot still reads back. */
-export function listDormantSnapshots(db, tenantId) {
-    // SAFETY: rows' shape matches the seven columns named in the SELECT.
-    const rows = db.prepare(`SELECT tenant_id, id, content, entry_json, reason, strength, dormant_at
-       FROM dormant_memories WHERE tenant_id = ?`).all(tenantId);
-    return rows.flatMap((row) => toSnapshot(row) ?? []);
-}
-/** Readable snapshots whose entry's source starts with `prefix`; a malformed snapshot is passed over, not an error. */
-export function dormantSnapshotsBySourcePrefix(db, tenantId, prefix) {
-    // SAFETY: rows' shape matches the seven columns named in the SELECT.
-    const rows = db.prepare(`SELECT tenant_id, id, content, entry_json, reason, strength, dormant_at
-       FROM dormant_memories
-      WHERE tenant_id = ?
-        AND CASE WHEN json_valid(entry_json) THEN json_extract(entry_json, '$.source') END LIKE ? ESCAPE '\\'`).all(tenantId, `${escapeLike(prefix)}%`);
-    return rows.flatMap((row) => toSnapshot(row) ?? []).filter((s) => String(s.entry.source).startsWith(prefix));
-}
-function toSnapshot(row) {
-    const entry = parseSnapshot(row);
-    return entry ? { entry, reason: row.reason, strength: row.strength, dormantAt: row.dormant_at } : null;
-}
-/** Put `entry` in place of a tenant's dormant memory `id`, keeping when and why that one went dormant. */
-export function replaceDormantEntry(db, tenantId, id, entry) {
-    db.prepare(`UPDATE dormant_memories SET id = ?, content = ?, entry_json = ? WHERE tenant_id = ? AND id = ?`)
-        .run(entry.id, entry.content, JSON.stringify(entry), tenantId, id);
-}
-/** Whether a tenant has a dormant memory with this id whose scope `admit` passes (snapshot readable or not). */
-export function hasDormantRow(db, tenantId, id, admit = EVERY_SCOPE) {
-    return db.prepare(`SELECT 1 FROM ${DORMANT_WITH_SCOPE} WHERE tenant_id = ? AND id = ? AND ${admit.sql}`).get(tenantId, id, ...admit.params) !== undefined;
-}
-/** Delete a tenant's dormant memory. Returns false when there was none. */
-export function deleteDormantRow(db, tenantId, id) {
-    const result = db.prepare(`DELETE FROM dormant_memories WHERE tenant_id = ? AND id = ?`).run(tenantId, id);
-    return Number(result.changes ?? 0) > 0;
-}
-/** Deletes the tenant's dormant copies of a rejected digest whose snapshot scope `inReach` admits, so the value cannot linger; returns their ids. */
-export function purgeDormantByDigest(db, tenantId, digest, inReach) {
-    // SAFETY: rows' shape matches the three columns named in the SELECT.
-    const rows = db.prepare(`SELECT id, content, CASE WHEN json_valid(entry_json) THEN json_extract(entry_json, '$.scope') END AS scope
-       FROM dormant_memories WHERE tenant_id = ?`).all(tenantId);
-    const removed = [];
-    for (const row of rows) {
-        if (rejectionDigest(row.content) !== digest || !inReach(row.scope))
-            continue;
-        deleteDormantRow(db, tenantId, row.id);
-        removed.push(row.id);
-    }
-    return removed;
-}
-export function expiredDormantKeys(db, cutoffIso) {
-    const sql = `SELECT tenant_id AS tenantId, id FROM dormant_memories WHERE dormant_at < ?`;
-    // SAFETY: rows' shape matches the two columns named in the SELECT.
-    return db.prepare(sql).all(cutoffIso);
-}
-export function deleteExpiredDormantRow(db, key, cutoffIso) {
-    const sql = `DELETE FROM dormant_memories WHERE tenant_id = ? AND id = ? AND dormant_at < ?`;
-    return Number(db.prepare(sql).run(key.tenantId, key.id, cutoffIso).changes ?? 0);
-}
-//# sourceMappingURL=dormant.js.map

package/dist/embedding-provider.d.ts

@@ -1,77 +0,0 @@
-/**
- * Pluggable embedding providers for Hippo.
- *
- * The local `@huggingface/transformers` path stays the zero-DEPENDENCY DEFAULT. Opt-in
- * API providers (OpenAI / Voyage / Cohere) let a user bring a frontier embedder
- * (e.g. text-embedding-3-large) for frontier-class retrieval. They use the native
- * `fetch` global (Node >= 22.16, see package.json engines; NO new dependency) and
- * read their key from a conventional env var. The provider is selected by
- * `config.embeddings.provider` (default `'local'`).
- *
- * Design contract:
- *   - Local provider `id` is the BARE model string; the STORED identity adds a `#t<N>`
- *     embed-text-format suffix (`embeddingIndexIdentity`), so older stores reindex once:
- *     their vectors were computed over path-contaminated text.
- *   - API provider `id` is `${kind}:${model}`; switching to/from an API embedder
- *     (or a dimension change) flips the identity and triggers the existing
- *     reindex-on-change path.
- *   - `resolveEmbeddingProvider` throws on an invalid config (unknown provider,
- *     bad apiBaseUrl); `embedMemory` turns that into a warning. `isAvailable()` is provider-aware
- *     (local -> dependency installed; api -> key present). `embed()` MAY throw on
- *     a hard transport/auth failure so a reindex can abort atomically; hot paths
- *     wrap it and fall back to BM25.
- *
- * The exact request/response shapes for the API providers are documented from each
- * vendor's public embeddings API; they are unit-tested here against a mocked
- * `fetch` and are integration-verified in Workstream C (real API calls are
- * egress-blocked in the build sandbox).
- */
-import { type EmbeddingRole } from './local-embedding.js';
-export type EmbeddingProviderKind = 'local' | 'openai' | 'voyage' | 'cohere';
-export declare const API_PROVIDER_KINDS: readonly EmbeddingProviderKind[];
-export interface EmbeddingProvider {
-    readonly kind: EmbeddingProviderKind;
-    readonly model: string;
-    /**
-     * Identity recorded in DB meta to drive reindex-on-change.
-     * local -> bare model string (back-compat); api -> `${kind}:${model}`.
-     */
-    readonly id: string;
-    /** Known fixed output dimension, if any (undefined for local / unknown). */
-    readonly dimensions?: number;
-    /** Env var holding this provider's API key (undefined for the local provider). */
-    readonly keyEnv?: string;
-    /** local -> dependency installed; api -> key present. NEVER throws. */
-    isAvailable(): boolean;
-    /**
-     * Batch-embed. Returns one row per input in order; a row is `[]` when that
-     * single item could not be embedded. MAY throw on a hard transport/auth
-     * failure (so a reindex aborts before saving a partial index).
-     */
-    embed(texts: string[], role?: EmbeddingRole): Promise<number[][]>;
-}
-export interface ResolveProviderOptions {
-    /** Explicit model override (mirrors resolveEmbeddingModel's explicitModel). */
-    model?: string;
-    /** Explicit provider override (mainly for tests). */
-    provider?: EmbeddingProviderKind;
-}
-/**
- * Build the active embedding provider from config (or an explicit override).
- * Never throws for a missing key — that surfaces via `isAvailable()` on the hot
- * paths and as a hard error only from the explicit `hippo embed` command. The
- * only hard throw is an invalid config (e.g. an insecure apiBaseUrl), a
- * deliberate loud failure; hot-path callers (search) wrap this in try/catch.
- */
-export declare function resolveEmbeddingProvider(hippoRoot: string, opts?: ResolveProviderOptions): EmbeddingProvider;
-/**
- * The reindex identity for the active provider. Use this (NOT resolveEmbeddingModel)
- * everywhere `embeddingModelRequiresReindex` / stored-model comparisons happen.
- */
-export declare function resolveEmbeddingIdentity(hippoRoot: string, opts?: ResolveProviderOptions): string;
-/**
- * Provider-aware availability for a store: local -> dependency installed;
- * api -> key present. Use at the call sites that decide whether to embed.
- */
-export declare function isEmbeddingConfigured(hippoRoot: string): boolean;
-//# sourceMappingURL=embedding-provider.d.ts.map

package/dist/embeddings.d.ts

@@ -1,101 +0,0 @@
-/**
- * Optional embedding-based semantic search for Hippo.
- * Uses @huggingface/transformers (local, zero API keys, ~22MB model).
- * Falls back silently if the library is not installed.
- */
-import { MemoryEntry } from './memory.js';
-import { type DatabaseSyncLike } from './db.js';
-import { EMBEDDING_MODEL_META_KEY } from './vector-store.js';
-import { type EmbeddingProvider } from './embedding-provider.js';
-import type { HippoStore } from './store-port.js';
-export { EMBEDDING_MODEL_META_KEY };
-/**
- * Bump whenever `embeddingInputText`'s composition changes in a way that
- * changes the resulting vectors for existing entries. Folded into the stored
- * index identity (see `embeddingIndexIdentity`) so a text-format change is
- * treated exactly like an embedding-model change: the next embed-touching
- * operation detects the mismatch and reindexes automatically. Format 2 =
- * `path:*` tags excluded (see `embeddingInputText`); format 1 (implicit, no
- * suffix) = `${content} ${tags.join(' ')}` including path tags.
- */
-export declare const EMBED_TEXT_FORMAT = 2;
-/**
- * The stored-index identity for a given embedding provider id: folds
- * `EMBED_TEXT_FORMAT` into the provider id so index-identity comparisons
- * automatically invalidate on either a model change OR a text-format change.
- * This is the ONE choke point both `embeddingModelRequiresReindex` (compare
- * side) and `saveStoredEmbeddingModel` (save side) go through — they MUST
- * version identically, or every call reindexes in a loop (or none ever do).
- */
-export declare function embeddingIndexIdentity(providerId: string): string;
-/**
- * Build the text embedded for a memory entry: content plus its tags, joined
- * by a space and trimmed — the same shape as the legacy
- * `` `${e.content} ${e.tags.join(' ')}`.trim() `` composition, minus `path:*`
- * tags.
- *
- * `path:*` tags are excluded because they are auto-derived from
- * `process.cwd()` (see `extractPathTags` in cli.ts) and carry every path
- * component of the store's location, INCLUDING the store directory name
- * itself. That means identical content embeds to a DIFFERENT vector
- * depending on WHERE the store happens to live — e.g. a fresh benchmark run
- * under `tempfile.mkdtemp()` gets a new directory name (hence new path
- * tokens, hence a new vector) every single run, even with byte-identical
- * content ingested in byte-identical order. This was diagnosed as the
- * DOMINANT root cause of cross-fresh-ingest recall-rank variance measured on
- * LoCoMo (mean evidence-recall@5 stdev 0.0175 across 4 fresh re-ingests of
- * identical data; see `benchmarks/LOCOMO_INVESTIGATION.md`, "Determinism
- * characterization"). It is a real product defect beyond benchmarks too:
- * retrieval semantics should not depend on a project directory's name.
- *
- * Only `path:*` is excluded. Other tags (`conv:`, `session:`, `speaker:`,
- * `dia:`, `error`, `scope:`, etc.) remain embedded — they carry semantic
- * meaning. Path relevance at recall time is already handled explicitly by
- * the v39 scope-isolation layer (`origin_project`, `pathOverlapScore`), so
- * embedding-level path tokens are redundant with a dedicated mechanism
- * rather than a feature.
- */
-export declare function embeddingInputText(entry: {
-    content: string;
-    tags: string[];
-}): string;
-/**
- * Persist the stored-index identity for `model` (see `embeddingIndexIdentity`).
- * Versioning happens INSIDE this function, not at call sites, so every caller
- * — current and future — gets the identity format for free. Must stay
- * consistent with the compare side in `embeddingModelRequiresReindex`.
- */
-export declare function saveStoredEmbeddingModel(hippoRoot: string, model: string): void;
-/** What a store's vector index was built by: the stored identity, and whether any vector exists. */
-export interface EmbeddingIndexState {
-    readonly storedModel: string | null;
-    readonly hasVectors: boolean;
-}
-/** The model the index was built by: the stored identity, else the default model when vectors exist. */
-export declare function indexedModel(state: EmbeddingIndexState): string | null;
-/** The one rebuild rule every store applies to its indexed model. */
-export declare function indexNeedsRebuild(indexed: string | null, providerId: string): boolean;
-/** Whether a vector write under the index identity `model` first drops the stored index, which another model built. */
-export declare function replacesIndex(state: EmbeddingIndexState, model: string): boolean;
-export declare function resolveIndexedEmbeddingModel(hippoRoot: string, index?: Record<string, number[]>): string | null;
-export declare function embeddingModelRequiresReindex(hippoRoot: string, model: string, index?: Record<string, number[]>): boolean;
-/** hippo.db's index state, the meta row and the EXISTS on one handle. */
-export declare function embeddingIndexStateAt(hippoRoot: string): EmbeddingIndexState;
-export declare function embeddingIndexStateOn(db: DatabaseSyncLike): EmbeddingIndexState;
-/**
- * Cosine similarity between two vectors. Handles unnormalized vectors.
- * Returns 0 for empty or mismatched vectors.
- */
-export declare function cosineSimilarity(a: number[], b: number[]): number;
-/** Every stored vector keyed by memory id; `{}` when none. Search reads only the rows it ranks via `loadStoredVectors`. */
-export declare function loadEmbeddingIndex(hippoRoot: string): Record<string, number[]>;
-/** Stored vectors for `ids` only. */
-export declare function loadStoredVectors(hippoRoot: string, ids: readonly string[]): Map<string, number[]>;
-/** Replace every stored vector with `index`; `model` defaults to the stored index identity. */
-export declare function saveEmbeddingIndex(hippoRoot: string, index: Record<string, number[]>, model?: string): void;
-/** Embed a single memory entry and cache the result in the embedding index; with `store`, through its vectorWrites, never opening hippo.db. */
-export declare function embedMemory(hippoRoot: string, entry: MemoryEntry, model?: string, store?: HippoStore): Promise<void>;
-/** Embeds every entry with no cached vector, prunes vectors of deleted memories, and returns how many it embedded; `provider` defaults to the
- *  configured one. With `store`, every tenant's memories with no vector for the provider's model go through its `vectorWrites`, never hippo.db. */
-export declare function embedAll(hippoRoot: string, model?: string, provider?: EmbeddingProvider, store?: HippoStore): Promise<number>;
-//# sourceMappingURL=embeddings.d.ts.map

package/dist/extract.js

@@ -1,133 +0,0 @@
-import { Layer, createMemory } from './memory.js';
-import { writeEntry } from './store/entry-writes.js';
-import { loadConfig } from './config.js';
-import { RejectedValueError } from './rejection.js';
-import { redactSecretsStrict } from './secret-detect.js';
-import { fetchWithRetry, llmTimeoutMs } from './http-retry.js';
-import { neverAutoShareTags } from './shared.js';
-import { log } from './log.js';
-import { isJsonString } from './json.js';
-import { certainDefect } from './memory-quality.js';
-const EXTRACTION_PROMPT = `You are extracting factual statements from a conversation or memory entry. Extract 1-8 standalone factual statements that would be useful to remember later.
-
-Rules:
-- Each fact must be a complete, standalone sentence
-- Include the speaker's name in every fact (e.g. "Alice prefers..." not "She prefers...")
-- Preserve specific details: names, numbers, dates, paths, IDs
-- Return a JSON array of objects with: content (string), tags (array of "speaker:X" and "topic:Y" strings), valence ("neutral", "positive", "negative", or "critical")
-- Return an empty array [] for small talk with no extractable facts
-- Output ONLY the JSON array, no preamble or explanation
-
-Input text:
-`;
-export async function extractFacts(text, opts) {
-    const model = opts.model ?? 'claude-sonnet-4-6';
-    const fetchFn = opts.fetcher ?? fetch;
-    let res;
-    try {
-        res = await fetchWithRetry('https://api.anthropic.com/v1/messages', {
-            method: 'POST',
-            headers: {
-                'content-type': 'application/json',
-                'x-api-key': opts.apiKey,
-                'anthropic-version': '2023-06-01',
-            },
-            body: JSON.stringify({
-                model,
-                max_tokens: 1200,
-                messages: [{ role: 'user', content: EXTRACTION_PROMPT + redactSecretsStrict(text) }],
-            }),
-        }, { timeoutMs: llmTimeoutMs(), fetchFn });
-    }
-    catch (err) {
-        opts.onError?.(`request failed: ${err instanceof Error ? err.message : String(err)}`);
-        return [];
-    }
-    if (!res.ok) {
-        opts.onError?.(`HTTP ${res.status}`);
-        return [];
-    }
-    try {
-        const data = await res.json();
-        const raw = data.content?.[0]?.text?.trim() ?? '';
-        if (!raw)
-            return [];
-        const parsed = JSON.parse(raw);
-        if (!Array.isArray(parsed))
-            return [];
-        const validValences = new Set(['neutral', 'positive', 'negative', 'critical']);
-        const facts = [];
-        for (const item of parsed) {
-            if (facts.length >= 8)
-                break;
-            if (!item ||
-                !isJsonString(item.content) ||
-                item.content.length < 3)
-                continue;
-            const itemTags = item.tags;
-            const tags = Array.isArray(itemTags)
-                ? itemTags.filter((t) => isJsonString(t))
-                : [];
-            // SAFETY: validValences.has(item.valence) above confirms item.valence is one of the four literal strings of EmotionalValence.
-            const valence = validValences.has(item.valence)
-                ? item.valence
-                : 'neutral';
-            facts.push({ content: item.content, tags, valence });
-        }
-        return facts;
-    }
-    catch (err) {
-        opts.onError?.(`unparseable response: ${err instanceof Error ? err.message : String(err)}`);
-        return [];
-    }
-}
-const INHERITABLE_PREFIXES = ['conv:', 'session:', 'scope:', 'path:'];
-export function storeExtractedFacts(hippoRoot, source, facts) {
-    const inheritedTags = [
-        ...source.tags.filter((t) => INHERITABLE_PREFIXES.some((p) => t.startsWith(p))),
-        ...neverAutoShareTags([source]),
-    ];
-    const entries = [];
-    let rejected = 0;
-    const baseHalfLifeDays = loadConfig(hippoRoot).defaultHalfLifeDays;
-    for (const fact of facts) {
-        const defect = certainDefect(fact.content);
-        if (defect !== null) {
-            log.warn(`storeExtractedFacts: skipped automatic quality defect (${defect})`);
-            continue;
-        }
-        const tags = ['extracted', ...inheritedTags, ...fact.tags];
-        const entry = { ...createMemory(fact.content, {
-                layer: Layer.Semantic,
-                tags,
-                emotional_valence: fact.valence,
-                confidence: 'inferred',
-                source: source.source,
-                extracted_from: source.id,
-                scope: source.scope,
-                // Without it createMemory stamps 'default', and extracted facts leave
-                // the tenant of the episodic memory they were extracted from.
-                tenantId: source.tenantId,
-                baseHalfLifeDays,
-            }), origin_project: source.origin_project };
-        // A refusal is per-VALUE: one rejected fact must not
-        // drop the rest of this batch. writeEntry has already audited the
-        // refusal (reject_refusal) before rethrowing, so skip-and-count here.
-        try {
-            writeEntry(hippoRoot, entry);
-        }
-        catch (err) {
-            if (err instanceof RejectedValueError) {
-                rejected++;
-                continue;
-            }
-            throw err;
-        }
-        entries.push(entry);
-    }
-    if (rejected > 0) {
-        log.warn(`storeExtractedFacts: skipped ${rejected} rejected value(s)`);
-    }
-    return entries;
-}
-//# sourceMappingURL=extract.js.map

package/dist/forward-claim-detector.d.ts

@@ -1,36 +0,0 @@
-/**
- * Forward-claim detector: pure-function regex set + token extraction.
- *
- * No DB. No state. No dependencies beyond stdlib regex + String.
- *
- * The detector's job is to decide whether a recall query carries a
- * forward-prediction phrase ("will take ~3 days", "ship by Friday",
- * "ETA in 2 weeks"). Calibration is intentionally HIGH-PRECISION /
- * LOW-RECALL: better to fire on 20% of real forward-claims than 80% with
- * 40% noise. Cry-wolf failure dominates planning-fallacy hint UX (Lovallo-
- * Kahneman 2003 inside-vs-outside view).
- *
- * Iteration signal: the `recall_autodebias_hint_no_class_match` audit op
- * (emitted by computePlanningFallacyOutput when a phrase matches but no class
- * resolves) is the telemetry channel for deciding whether to add an
- * embedding-based detector.
- */
-export interface ForwardClaimMatch {
-    /** The regex match snippet, e.g. "will take" or "~3 days". Surfaced
-     *  to the calling agent in `PlanningFallacyHint.detectedPhrase` so they
-     *  see WHY the hint appeared. */
-    phrase: string;
-    /** Lower-cased non-stop-word tokens (len >= 3, alpha or alphanumeric)
-     *  extracted from the FULL query, NOT just the match. Used by the
-     *  orchestrator's class resolver to score overlap with class_tag tokens. */
-    classQueryTokens: string[];
-}
-/**
- * Detect whether a recall query carries a forward-prediction phrase.
- *
- * @returns first-match phrase + extracted class-resolution tokens when
- *   any pattern matches; null otherwise. Token extraction runs only on a
- *   match — non-forward queries pay zero work beyond the regex gate.
- */
-export declare function detectForwardClaim(queryText: string): ForwardClaimMatch | null;
-//# sourceMappingURL=forward-claim-detector.d.ts.map

package/dist/forward-claim-detector.js

@@ -1,112 +0,0 @@
-/**
- * Forward-claim detector: pure-function regex set + token extraction.
- *
- * No DB. No state. No dependencies beyond stdlib regex + String.
- *
- * The detector's job is to decide whether a recall query carries a
- * forward-prediction phrase ("will take ~3 days", "ship by Friday",
- * "ETA in 2 weeks"). Calibration is intentionally HIGH-PRECISION /
- * LOW-RECALL: better to fire on 20% of real forward-claims than 80% with
- * 40% noise. Cry-wolf failure dominates planning-fallacy hint UX (Lovallo-
- * Kahneman 2003 inside-vs-outside view).
- *
- * Iteration signal: the `recall_autodebias_hint_no_class_match` audit op
- * (emitted by computePlanningFallacyOutput when a phrase matches but no class
- * resolves) is the telemetry channel for deciding whether to add an
- * embedding-based detector.
- */
-/**
- * Each pattern is intentionally narrow:
- * adding a pattern should require evidence from the
- * `recall_autodebias_hint_no_class_match` audit channel that real forward-
- * claims are slipping through, NOT speculative "this might match more".
- *
- * Word boundaries (`\b`) are mandatory: prevent `~5 days` inside
- * `~5 days_ago` from matching, and prevent `ETA` substring matches inside
- * a longer token (e.g. `BETAtesting`).
- */
-// Reused fragment for ALL duration-suffix patterns. Requires a digit + unit
-// so 'will take ownership' / 'ship in Docker' (no time component) don't
-// match: verb-only patterns fire on everyday non-estimate queries that share a class-token.
-// Accepts `<N> unit` (3 days), `a/an unit` (a week — implicit 1), and
-// `one unit` so natural English forward-claims aren't lost.
-const DURATION_TAIL = String.raw `(?:about|around|~|≈)?\s*(?:\d+|a|an|one)\s*(?:day|week|month|hour|hr|min(?:ute)?|sec(?:ond)?)s?\b`;
-const FORWARD_CLAIM_PATTERNS = [
-    // Verb + duration tail. Old pattern `/\b(?:will|should...) take\b/i`
-    // matched `who will take ownership of auth?` because there was no
-    // quantifier requirement. Now requires `<verb> take <N> <unit>`.
-    new RegExp(String.raw `\b(?:will|should|gonna|going\s+to)\s+take\s+${DURATION_TAIL}`, 'i'),
-    // Ship + by/in + duration-or-day. Old pattern `/\bship(?:ping)?\s+(?:by|in)\b/i`
-    // matched `how does this ship in Docker?`. Now requires either a
-    // duration tail OR a literal day-of-week reference.
-    new RegExp(String.raw `\bship(?:ping|s)?\s+(?:by|in)\s+(?:(?:about|around)\s+)?(?:next\s+)?(?:${DURATION_TAIL}|(?:monday|tuesday|wednesday|thursday|friday|saturday|sunday))\b`, 'i'),
-    /\bestimate(?:d)?\s+(?:at\s+)?(?:~|≈|about|around)?\s*\d+/i,
-    /\b(?:by|in|within)\s+(?:about|around|~)?\s*\d+\s*(?:day|week|month|hour)s?\b/i,
-    /\bETA\s*(?:is|:)?\s*\d+/i,
-    /\b(?:by|before)\s+next\s+(?:week|month|sprint|monday|tuesday|wednesday|thursday|friday|saturday|sunday)\b/i,
-    // Standalone tilde duration: '~3 days for migration', 'estimate ~3 days'.
-    // Lookbehind asserts start-of-string OR whitespace before the tilde
-    // because \b before ~ requires a word char immediately preceding (~ is
-    // not a word character), so /\b~/ would only match in 'foo~3 days'
-    // (malformed) and silently miss the legitimate cases.
-    /(?<=^|\s)~\s*\d+\s*(?:day|week|month|hour)s?\b/i,
-    // Should + verb + duration tail. Same tightening as the leading 'will
-    // take' rule: 'should ship by EOD' must include a quantifier.
-    new RegExp(String.raw `\bshould\s+(?:be|ship|finish|complete|land)\s+(?:by|in|within)\s+(?:(?:about|around)\s+)?(?:next\s+)?(?:${DURATION_TAIL}|(?:monday|tuesday|wednesday|thursday|friday|saturday|sunday))\b`, 'i'),
-];
-/**
- * Pronouns + function words + modal verbs the regex set already gates on.
- * Dropped before class-resolution so the overlap signal comes from
- * domain tokens ("migration", "auth", "refactor") rather than connectives.
- */
-const STOP_WORDS = new Set([
-    'the', 'a', 'an', 'and', 'or', 'but', 'for', 'to', 'in', 'on', 'at', 'of',
-    'by', 'with', 'my', 'your', 'our', 'their', 'its', 'it', 'this', 'that',
-    'these', 'those', 'will', 'should', 'can', 'i', 'we', 'they', 'he', 'she',
-    'is', 'be', 'was', 'are', 'were', 'has', 'have', 'had', 'do', 'does', 'did',
-    'from', 'as', 'so', 'than', 'then',
-    // Verbs that appear inside FORWARD_CLAIM_PATTERNS themselves — they're
-    // signal for the regex gate but NOT signal for class resolution (you
-    // wouldn't name a prediction class "take" or "ship"). Listing here so
-    // they don't pollute the classQueryTokens overlap score.
-    'take', 'taken', 'takes', 'ship', 'ships', 'finish', 'complete', 'land',
-    'eta', 'estimate', 'estimated', 'next', 'about', 'around',
-    // Duration units appear in every forward-claim phrase by design (the
-    // regex set REQUIRES a `<N> <unit>` quantifier after the verb). Letting
-    // them through to class resolution lets a class tag containing 'days'
-    // win or tie on the unit token instead of the domain token.
-    'day', 'days', 'week', 'weeks', 'month', 'months',
-    'hour', 'hours', 'hr', 'hrs',
-    'min', 'mins', 'minute', 'minutes', 'sec', 'secs', 'second', 'seconds',
-]);
-/**
- * Detect whether a recall query carries a forward-prediction phrase.
- *
- * @returns first-match phrase + extracted class-resolution tokens when
- *   any pattern matches; null otherwise. Token extraction runs only on a
- *   match — non-forward queries pay zero work beyond the regex gate.
- */
-export function detectForwardClaim(queryText) {
-    if (!queryText)
-        return null;
-    for (const pat of FORWARD_CLAIM_PATTERNS) {
-        const m = queryText.match(pat);
-        if (m) {
-            const tokens = extractClassQueryTokens(queryText);
-            return { phrase: m[0], classQueryTokens: tokens };
-        }
-    }
-    return null;
-}
-function extractClassQueryTokens(queryText) {
-    return queryText
-        .toLowerCase()
-        // Strip everything that's not alphanum or whitespace or hyphen / underscore.
-        .replace(/[^a-z0-9\s_-]/g, ' ')
-        // Split on whitespace AND hyphen AND underscore so `migration-effort`
-        // produces ['migration', 'effort'] — matching the class-tag split
-        // pattern in resolveClassFromTokens (split on /[-_\s]+/).
-        .split(/[\s_-]+/)
-        .filter((t) => t.length >= 3 && !STOP_WORDS.has(t) && !/^\d+$/.test(t));
-}
-//# sourceMappingURL=forward-claim-detector.js.map