@psiclawops/hypermem 0.9.6 → 0.9.9

package/dist/open-domain.js

@@ -17,9 +17,113 @@
  * raw message history regardless of quality gate.
  */
 // ── Open-domain signal patterns ───────────────────────────────────────────
-const BROAD_INTERROGATIVE = /\b(what did|what does|what has|what was|what were|what is|how did|how does|how has|tell me about|describe|explain|summarize|overview|recap|what do you know about|what have|who is|who was|who did)\b/i;
-const SPECIFIC_ANCHOR = /\b([A-Z][a-z]{2,}(?:\s+[A-Z][a-z]{2,})+|v\d+\.\d+|#\d{2,}|https?:\/\/|[A-Z]{2,}-\d+)\b/;
+const BROAD_INTERROGATIVE = /\b(what did|what does|what has|what was|what were|what is|what are|how did|how does|how has|tell me about|describe|explain|summarize|overview|recap|what do you know about|what have|who is|who was|who did)\b/i;
+// LoCoMo category-3/open-domain questions are often inferential rather than
+// classic WH recall. Keep this benchmark-agnostic: these are question shapes
+// that need raw dialogue evidence, not answer terms.
+const INFERENTIAL_OPEN_DOMAIN = /\b(what might|would\b.*\b(enjoy|consider|considered|likely|pursue|be)\b|could\b.*\b(enjoy|consider|likely|pursue|be)\b|should\b.*\b(enjoy|consider|likely|pursue|be)\b|is it likely|which country|in what country|what fields?|suspected health|financial status)\b/i;
+const SPECIFIC_NON_DIALOG_ANCHOR = /\b(v\d+\.\d+|#\d{2,}|https?:\/\/|[A-Z]{2,}-\d+)\b/;
 const TEMPORAL_SIGNALS = /\b(before|after|when|last\s+\w+|yesterday|today|recently|between|since|until|ago|this\s+week|this\s+month|in\s+(january|february|march|april|may|june|july|august|september|october|november|december))\b/i;
+const OPEN_DOMAIN_FACETS = [
+    {
+        name: 'education-career',
+        pattern: /\b(educat\w*|field|fields|career|pursue|certification|training|study|school|college|class|degree)\b/i,
+        terms: ['education', 'school', 'college', 'study', 'class', 'degree', 'training', 'certificate', 'certification', 'career', 'work', 'job', 'interest', 'interested'],
+    },
+    {
+        name: 'financial-status',
+        pattern: /\b(financial|status|wealth|wealthy|money|afford|income|class|expensive|cost)\b/i,
+        terms: ['money', 'financial', 'finance', 'wealth', 'wealthy', 'income', 'afford', 'expensive', 'cost', 'job', 'work', 'salary', 'rent', 'house', 'apartment', 'vacation', 'donate', 'donation', 'charity', 'fundraiser'],
+    },
+    {
+        name: 'social-circle',
+        pattern: /\b(friend|friends|besides|teammate|teammates|team|group|social)\b/i,
+        terms: ['friend', 'friends', 'teammate', 'teammates', 'team', 'group', 'club', 'community', 'classmate', 'coworker', 'game', 'games', 'gaming', 'video', 'online', 'player', 'players'],
+    },
+    {
+        name: 'reading-preference',
+        pattern: /\b(read|reading|book|books|author|novel|writer|lewis|greene|green)\b/i,
+        terms: ['read', 'reading', 'book', 'books', 'author', 'authors', 'novel', 'writer', 'story', 'stories', 'fiction', 'fantasy', 'literature', 'library', 'recommendation', 'recommend'],
+    },
+    {
+        name: 'activity-pet',
+        pattern: /\b(indoor|activity|activities|dog|dogs|puppy|pet|happy|hobby|hobbies|treat|treats)\b/i,
+        terms: ['indoor', 'activity', 'activities', 'dog', 'dogs', 'puppy', 'pet', 'happy', 'hobby', 'hobbies', 'cook', 'cooking', 'bake', 'baking', 'recipe', 'treat', 'treats', 'kitchen', 'homemade', 'cookie', 'cookies', 'biscuit', 'biscuits'],
+    },
+    {
+        name: 'health-status',
+        pattern: /\b(health|problem|problems|suspected|medical|condition|weight|exercise|diet|symptom|symptoms)\b/i,
+        terms: ['health', 'medical', 'condition', 'problem', 'problems', 'weight', 'exercise', 'diet', 'doctor', 'symptom', 'symptoms'],
+    },
+    {
+        name: 'travel-country',
+        pattern: /\b(country|visiting|visit|visited|travel|trip|vacation|pendant|souvenir|mother)\b/i,
+        terms: ['country', 'visit', 'visited', 'visiting', 'travel', 'trip', 'vacation', 'souvenir', 'pendant', 'mother', 'abroad'],
+    },
+    {
+        name: 'civic-patriotic',
+        pattern: /\b(patriotic|patriot|country|flag|military|veteran|service|civic|community)\b/i,
+        terms: ['patriotic', 'patriot', 'country', 'flag', 'military', 'veteran', 'service', 'civic', 'community', 'charity', 'fundraiser', 'volunteer', 'memorial', 'parade', 'independence', 'america', 'american', 'national', 'vote', 'voting', 'election'],
+    },
+];
+const QUERY_INITIAL_WORDS = new Set([
+    'what', 'which', 'would', 'could', 'should', 'is', 'in', 'how', 'who',
+]);
+export function extractOpenDomainAnchors(query) {
+    const anchors = [];
+    const tokens = query.match(/\b[A-Z][a-zA-Z]{2,}\b/g) ?? [];
+    for (const token of tokens) {
+        const lower = token.toLowerCase();
+        if (QUERY_INITIAL_WORDS.has(lower))
+            continue;
+        anchors.push(lower);
+    }
+    return [...new Set(anchors)];
+}
+function matchedOpenDomainFacets(query) {
+    return OPEN_DOMAIN_FACETS.filter(facet => facet.pattern.test(query));
+}
+export function expandOpenDomainQueryTerms(query, terms) {
+    const expanded = [...extractOpenDomainAnchors(query), ...terms];
+    for (const facet of matchedOpenDomainFacets(query)) {
+        expanded.push(...facet.terms);
+    }
+    return [...new Set(expanded)].slice(0, 40);
+}
+function toFtsAndQuery(anchorTerms, facetTerms, limit) {
+    const anchors = [...new Set(anchorTerms)]
+        .map(w => w.replace(/"/g, '').trim())
+        .filter(Boolean)
+        .slice(0, 4);
+    const facets = [...new Set(facetTerms)]
+        .map(w => w.replace(/"/g, '').trim())
+        .filter(Boolean)
+        .slice(0, limit);
+    if (anchors.length === 0 || facets.length === 0)
+        return null;
+    const anchorQuery = anchors.map(w => `"${w}"*`).join(' OR ');
+    const facetQuery = facets.map(w => `"${w}"*`).join(' OR ');
+    return `(${anchorQuery}) AND (${facetQuery})`;
+}
+export function scoreOpenDomainEvidence(content, query, baseTerms) {
+    const lower = content.toLowerCase();
+    let score = 0;
+    for (const anchor of extractOpenDomainAnchors(query)) {
+        if (lower.includes(anchor))
+            score += 8;
+    }
+    for (const term of baseTerms) {
+        if (lower.includes(term))
+            score += term.length >= 6 ? 2 : 1;
+    }
+    for (const facet of matchedOpenDomainFacets(query)) {
+        for (const term of facet.terms) {
+            if (lower.includes(term))
+                score += 1;
+        }
+    }
+    return score;
+}
 /**
  * Returns true if the query looks like an open-domain question:
  * broad, exploratory, no specific anchors, no temporal signals.
@@ -27,18 +131,25 @@ const TEMPORAL_SIGNALS = /\b(before|after|when|last\s+\w+|yesterday|today|recent
 export function isOpenDomainQuery(query) {
     if (!query || query.trim().length < 8)
         return false;
-    // Has temporal signals → temporal path handles it
-    if (TEMPORAL_SIGNALS.test(query))
+    // Has temporal signals → temporal path handles it, unless the query is also
+    // a broad/inferential open-domain question. LoCoMo category-3 questions often
+    // mention dates while still requiring raw-message inference rather than a
+    // pure temporal answer.
+    const broad = BROAD_INTERROGATIVE.test(query) || INFERENTIAL_OPEN_DOMAIN.test(query);
+    if (TEMPORAL_SIGNALS.test(query) && !broad)
         return false;
-    // Has specific named entity / version / ticket anchor → not open-domain
-    if (SPECIFIC_ANCHOR.test(query))
+    // Version, ticket, and URL anchors usually belong to specific retrieval paths.
+    // Do not exclude named people/places here: LoCoMo open-domain questions often
+    // ask broad questions about a named speaker, and the entity is the useful
+    // retrieval anchor rather than a reason to bypass raw-message recall.
+    if (SPECIFIC_NON_DIALOG_ANCHOR.test(query))
         return false;
     // Must match a broad interrogative pattern
-    if (!BROAD_INTERROGATIVE.test(query))
+    if (!broad)
         return false;
     // Sanity: query should not be too long (long queries are usually specific)
     const wordCount = query.trim().split(/\s+/).length;
-    if (wordCount > 20)
+    if (wordCount > 28)
         return false;
     return true;
 }
@@ -48,23 +159,55 @@ export function isOpenDomainQuery(query) {
  * Strips stop words, question words, and punctuation.
  * Returns up to 6 prefix-matched terms joined with OR.
  */
-export function buildOpenDomainFtsQuery(query) {
+function tokenizeOpenDomainQuery(query) {
     const STOP_WORDS = new Set([
         'what', 'did', 'does', 'has', 'was', 'were', 'is', 'are', 'how',
         'tell', 'me', 'about', 'describe', 'explain', 'summarize', 'overview',
         'recap', 'who', 'do', 'you', 'know', 'have', 'the', 'a', 'an', 'of',
         'in', 'on', 'at', 'to', 'for', 'and', 'or', 'but', 'with', 'from',
+        'their', 'them', 'they', 'your', 'his', 'her', 'him', 'she', 'he',
+        'would', 'could', 'should', 'might', 'likely', 'considered', 'consider',
+        'besides', 'while', 'make', 'doing', 'person',
     ]);
     const terms = query
         .toLowerCase()
-        .replace(/[^a-z0-9\s]/g, ' ')
+        .replace(/[^a-z0-9\s-]/g, ' ')
+        .replace(/-/g, ' ')
         .split(/\s+/)
-        .filter(w => w.length >= 3 && !STOP_WORDS.has(w))
-        .slice(0, 6)
-        .map(w => `"${w}"*`);
-    if (terms.length === 0)
+        .map(w => w.trim())
+        .filter(w => w.length >= 3 && !STOP_WORDS.has(w));
+    return expandOpenDomainQueryTerms(query, terms);
+}
+function toFtsOrQuery(terms, limit) {
+    const unique = [...new Set(terms)]
+        .slice(0, limit)
+        .map(w => `"${w.replace(/"/g, '')}"*`);
+    if (unique.length === 0)
         return null;
-    return terms.join(' OR ');
+    return unique.join(' OR ');
+}
+export function buildOpenDomainFtsQuery(query) {
+    return toFtsOrQuery(tokenizeOpenDomainQuery(query), 8);
+}
+/**
+ * Build multiple prompt-only FTS probes for broad open-domain questions.
+ * The primary query favors specific terms; the secondary query preserves the
+ * natural query order so shorter but important entity/activity terms are not
+ * lost when the broad question contains many long words.
+ */
+export function buildOpenDomainFtsQueries(query) {
+    const terms = tokenizeOpenDomainQuery(query);
+    const anchors = extractOpenDomainAnchors(query);
+    const baseTerms = terms.filter(term => !anchors.includes(term));
+    const facetQueries = matchedOpenDomainFacets(query)
+        .map(facet => toFtsAndQuery(anchors, facet.terms, 10))
+        .filter((q) => Boolean(q));
+    const queries = [
+        ...facetQueries,
+        toFtsOrQuery(terms, 10),
+        toFtsOrQuery(baseTerms, 12),
+    ].filter((q) => Boolean(q));
+    return [...new Set(queries)];
 }
 /**
  * Search raw message history via FTS5 for open-domain queries.
@@ -76,11 +219,12 @@ export function buildOpenDomainFtsQuery(query) {
  * @param limit — max results (default 10)
  */
 export function searchOpenDomain(db, query, existingContent, limit = 10) {
-    const ftsQuery = buildOpenDomainFtsQuery(query);
-    if (!ftsQuery)
+    const ftsQueries = buildOpenDomainFtsQueries(query);
+    if (ftsQueries.length === 0)
         return [];
     try {
-        const rows = db.prepare(`
+        const rowsById = new Map();
+        const hitStmt = db.prepare(`
       WITH fts_matches AS (
         SELECT rowid, rank
         FROM messages_fts
@@ -89,9 +233,13 @@ export function searchOpenDomain(db, query, existingContent, limit = 10) {
         LIMIT ?
       )
       SELECT
+        m.id,
+        m.conversation_id AS conversationId,
         m.role,
         m.text_content AS content,
-        m.created_at AS createdAt
+        m.created_at AS createdAt,
+        m.message_index AS messageIndex,
+        fts_matches.rank AS rank
       FROM messages m
       JOIN fts_matches ON m.id = fts_matches.rowid
       WHERE m.role IN ('user', 'assistant')
@@ -99,7 +247,61 @@ export function searchOpenDomain(db, query, existingContent, limit = 10) {
         AND trim(m.text_content) != ''
         AND m.is_heartbeat = 0
       ORDER BY fts_matches.rank
-    `).all(ftsQuery, limit * 2);
+    `);
+        const neighborStmt = db.prepare(`
+      SELECT
+        id,
+        conversation_id AS conversationId,
+        role,
+        text_content AS content,
+        created_at AS createdAt,
+        message_index AS messageIndex
+      FROM messages
+      WHERE conversation_id = ?
+        AND message_index BETWEEN ? AND ?
+        AND role IN ('user', 'assistant')
+        AND text_content IS NOT NULL
+        AND trim(text_content) != ''
+        AND is_heartbeat = 0
+      ORDER BY message_index ASC
+    `);
+        for (const ftsQuery of ftsQueries) {
+            const hits = hitStmt.all(ftsQuery, limit * 2);
+            for (const hit of hits) {
+                if (!rowsById.has(hit.id))
+                    rowsById.set(hit.id, hit);
+                // Preserve local dialogue context. Open-domain answers often live in the
+                // assistant turn adjacent to a broad user turn, or vice versa.
+                if (hit.conversationId == null)
+                    continue;
+                const messageIndex = hit.messageIndex ?? 0;
+                const neighbors = neighborStmt.all(hit.conversationId, messageIndex - 2, messageIndex + 2);
+                for (const neighbor of neighbors) {
+                    if (!rowsById.has(neighbor.id))
+                        rowsById.set(neighbor.id, {
+                            ...neighbor,
+                            rank: hit.rank,
+                        });
+                }
+            }
+        }
+        const baseTerms = tokenizeOpenDomainQuery(query);
+        for (const row of rowsById.values()) {
+            row.anchorScore = scoreOpenDomainEvidence(row.content ?? '', query, baseTerms);
+        }
+        const rows = [...rowsById.values()].sort((a, b) => {
+            const scoreA = a.anchorScore ?? 0;
+            const scoreB = b.anchorScore ?? 0;
+            if (scoreA !== scoreB)
+                return scoreB - scoreA;
+            const rankA = a.rank ?? Number.MAX_SAFE_INTEGER;
+            const rankB = b.rank ?? Number.MAX_SAFE_INTEGER;
+            if (rankA !== rankB)
+                return rankA - rankB;
+            if ((a.conversationId ?? 0) !== (b.conversationId ?? 0))
+                return (a.conversationId ?? 0) - (b.conversationId ?? 0);
+            return (a.messageIndex ?? 0) - (b.messageIndex ?? 0);
+        });
         // Deduplicate against existing context and filter short content
         const seen = new Set();
         const results = [];

package/dist/profiles.js

@@ -108,21 +108,21 @@ export const lightProfile = {
 // ---------------------------------------------------------------------------
 const STANDARD_COMPOSITOR = {
     // ── Primary budget controls ──
-    budgetFraction: 0.703, // 90k effective at 128k window
+    budgetFraction: 0.60, // operational default: ~77k effective at 128k before reserve
     reserveFraction: 0.25, // balanced — leaves room for large tool results
     historyFraction: 0.40, // ~27k tokens of conversation history
     memoryFraction: 0.40, // ~27k tokens for facts/wiki/semantic
     // ── Absolute fallback ──
     defaultTokenBudget: 90000,
     // ── History internals ──
-    maxHistoryMessages: 500,
-    warmHistoryBudgetFraction: 0.40,
-    keystoneHistoryFraction: 0.20,
-    keystoneMaxMessages: 15,
+    maxHistoryMessages: 250,
+    warmHistoryBudgetFraction: 0.27,
+    keystoneHistoryFraction: 0.15,
+    keystoneMaxMessages: 12,
     keystoneMinSignificance: 0.5,
     // ── Memory internals ──
-    maxFacts: 30,
-    maxCrossSessionContext: 4000,
+    maxFacts: 25,
+    maxCrossSessionContext: 0,
     maxTotalTriggerTokens: 4000,
     wikiTokenCap: 600,
     // ── Tool gradient (internal — safe floor enforced automatically) ──
@@ -173,14 +173,14 @@ const EXTENDED_COMPOSITOR = {
     // ── Absolute fallback ──
     defaultTokenBudget: 160000,
     // ── History internals ──
-    maxHistoryMessages: 1000,
-    warmHistoryBudgetFraction: 0.45,
-    keystoneHistoryFraction: 0.25,
-    keystoneMaxMessages: 30,
+    maxHistoryMessages: 500,
+    warmHistoryBudgetFraction: 0.27,
+    keystoneHistoryFraction: 0.15,
+    keystoneMaxMessages: 12,
     keystoneMinSignificance: 0.4,
     // ── Memory internals ──
-    maxFacts: 60,
-    maxCrossSessionContext: 12000,
+    maxFacts: 25,
+    maxCrossSessionContext: 4000,
     maxTotalTriggerTokens: 10000,
     wikiTokenCap: 800,
     // ── Tool gradient (internal — safe floor enforced automatically) ──

package/dist/question-shape.d.ts

@@ -0,0 +1,73 @@
+/**
+ * question-shape.ts — Heuristic v1 multi-hop question shape detector
+ *
+ * Sprint A of the multi-hop closure plan: deterministic, no model call.
+ * Classifies a query as 'multi-hop' when it appears to require bridging
+ * evidence across two or more distinct named entities or entity+facet pairs.
+ *
+ * Detection logic (all deterministic):
+ *   - Extract named entities (TitleCase spans, quoted strings, capitalized 2+ tokens)
+ *   - Extract facet terms from the LoCoMo answer-bearing noun lexicon
+ *   - Multi-hop if: (2+ entities) OR (1 entity + 1 facet), PLUS a relation word
+ *
+ * False-positive gate: temporal-anchor / single-hop-span queries are NOT
+ * multi-hop even when they have multiple entity tokens. A FP-rate check
+ * hook is available via `questionShapeFalsePositiveScore`.
+ *
+ * Exported symbols:
+ *   detectQuestionShape(query)  → QuestionShape
+ *   questionShapeFalsePositiveScore(query) → number  (0 = likely real, 1 = likely FP)
+ */
+export interface QuestionShape {
+    /** 'multi-hop' = requires bridging evidence across 2+ entities or entity+facet */
+    kind: 'multi-hop' | 'single-hop';
+    /** Named entity tokens extracted from the query */
+    entities: string[];
+    /** Facet terms matched from the LoCoMo facet lexicon */
+    facets: string[];
+    /**
+     * Confidence in the multi-hop classification. 0–1.
+     * For 'single-hop', this is a confidence in NOT being multi-hop.
+     */
+    confidence: number;
+}
+export declare const QUESTION_SHAPE_FACETS: Array<{
+    name: string;
+    terms: string[];
+}>;
+/**
+ * Extract named entity candidates from a query string.
+ * Returns deduplicated lowercase entity tokens.
+ */
+export declare function extractQueryEntities(query: string): string[];
+/**
+ * Extract facet terms from a query string using the LoCoMo facet lexicon.
+ * Returns matched facet group names (deduplicated).
+ */
+export declare function extractQueryFacets(query: string): string[];
+/**
+ * Extract matched facet terms (raw tokens, not group names) from a query.
+ * Used for structured handoff header annotation.
+ */
+export declare function extractQueryFacetTerms(query: string): string[];
+/**
+ * Estimate the probability that a 'multi-hop' classification is a false positive.
+ * Returns 0.0 (clearly multi-hop) to 1.0 (clearly single-hop / FP).
+ *
+ * High FP score → do not apply structured handoff even if multi-hop shape detected.
+ * Spec threshold: FP rate > 0.30 on held-out single-hop-multi-entity set →
+ * add a negative check. This function provides that check.
+ */
+export declare function questionShapeFalsePositiveScore(query: string): number;
+/**
+ * Detect whether a query has multi-hop shape.
+ *
+ * Multi-hop criteria (all must be true):
+ *   1. 2+ named entities OR (1 entity + 1 facet group)
+ *   2. At least one relation/intersection word
+ *   3. False-positive score < 0.60
+ *
+ * Returns a QuestionShape with extracted entities, facets, and confidence.
+ */
+export declare function detectQuestionShape(query: string): QuestionShape;
+//# sourceMappingURL=question-shape.d.ts.map

package/dist/question-shape.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"question-shape.d.ts","sourceRoot":"","sources":["../src/question-shape.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,MAAM,WAAW,aAAa;IAC5B,kFAAkF;IAClF,IAAI,EAAE,WAAW,GAAG,YAAY,CAAC;IACjC,mDAAmD;IACnD,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,wDAAwD;IACxD,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB;;;OAGG;IACH,UAAU,EAAE,MAAM,CAAC;CACpB;AAiBD,eAAO,MAAM,qBAAqB,EAAE,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAA;CAAE,CAmC1E,CAAC;AA+CF;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAuB5D;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAc1D;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAS9D;AAYD;;;;;;;GAOG;AACH,wBAAgB,+BAA+B,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAyBrE;AAID;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,aAAa,CA0BhE"}

package/dist/question-shape.js

@@ -0,0 +1,230 @@
+/**
+ * question-shape.ts — Heuristic v1 multi-hop question shape detector
+ *
+ * Sprint A of the multi-hop closure plan: deterministic, no model call.
+ * Classifies a query as 'multi-hop' when it appears to require bridging
+ * evidence across two or more distinct named entities or entity+facet pairs.
+ *
+ * Detection logic (all deterministic):
+ *   - Extract named entities (TitleCase spans, quoted strings, capitalized 2+ tokens)
+ *   - Extract facet terms from the LoCoMo answer-bearing noun lexicon
+ *   - Multi-hop if: (2+ entities) OR (1 entity + 1 facet), PLUS a relation word
+ *
+ * False-positive gate: temporal-anchor / single-hop-span queries are NOT
+ * multi-hop even when they have multiple entity tokens. A FP-rate check
+ * hook is available via `questionShapeFalsePositiveScore`.
+ *
+ * Exported symbols:
+ *   detectQuestionShape(query)  → QuestionShape
+ *   questionShapeFalsePositiveScore(query) → number  (0 = likely real, 1 = likely FP)
+ */
+// ── Relation lexicon ──────────────────────────────────────────────────────
+// Spec: "relation/intersection word" — signals that the question asks about
+// a shared attribute, comparison, or intersection across entities.
+const RELATION_WORDS = new Set([
+    'common', 'share', 'shared', 'both', 'same', 'between',
+    'bought', 'lost', 'planned', 'pursued', 'interested',
+    'also', 'together', 'neither', 'either',
+    'compare', 'comparing', 'overlap', 'overlapping', 'link', 'connect',
+    'relationship', 'relation', 'difference', 'similar', 'similarity',
+]);
+// ── Facet lexicon ─────────────────────────────────────────────────────────
+// LoCoMo answer-bearing nouns. Kept minimal for Sprint A; promoted in Sprint B.
+export const QUESTION_SHAPE_FACETS = [
+    {
+        name: 'job',
+        terms: ['job', 'jobs', 'work', 'career', 'occupation', 'profession', 'employment', 'fired', 'hired', 'promotion'],
+    },
+    {
+        name: 'death',
+        terms: ['death', 'died', 'passed away', 'funeral', 'loss', 'deceased', 'passing'],
+    },
+    {
+        name: 'hobby',
+        terms: ['hobby', 'hobbies', 'activity', 'activities', 'interest', 'interests', 'passion', 'pastime', 'free time'],
+    },
+    {
+        name: 'purchase',
+        terms: ['bought', 'purchase', 'purchased', 'buy', 'buying', 'item', 'items', 'shopping', 'order', 'ordered'],
+    },
+    {
+        name: 'venue',
+        terms: ['place', 'places', 'venue', 'venues', 'location', 'where', 'meet', 'met', 'visited', 'restaurant', 'bar', 'club'],
+    },
+    {
+        name: 'activity',
+        terms: ['planned', 'planning', 'event', 'events', 'trip', 'trips', 'vacation', 'travel'],
+    },
+    {
+        name: 'time',
+        terms: ['month', 'months', 'year', 'years', 'january', 'february', 'march', 'april', 'may', 'june',
+            'july', 'august', 'september', 'october', 'november', 'december', 'spring', 'summer', 'fall', 'winter'],
+    },
+    {
+        name: 'relationship',
+        terms: ['friend', 'friends', 'partner', 'boyfriend', 'girlfriend', 'husband', 'wife', 'family',
+            'sibling', 'brother', 'sister', 'parent', 'mother', 'father', 'colleague', 'coworker'],
+    },
+];
+// Flat set for quick lookup
+const FACET_TERM_SET = new Set(QUESTION_SHAPE_FACETS.flatMap(f => f.terms));
+// ── Temporal-anchor / single-hop span patterns ────────────────────────────
+// Used by the FP-score hook. A temporal question about one entity's history
+// looks multi-hop by entity count but should not trigger structured handoff.
+const TEMPORAL_SINGLE_HOP_PATTERNS = [
+    /\bwhen (did|was|were|is|are)\b/i,
+    /^what (year|month|date) did\b/i,
+    /\b(first|last)\s+(time|year|month|day|week)\b/i,
+    /\bhow long (ago|since|has|have)\b/i,
+    /\b(how many|what number|count of)\b/i,
+    /\b(date|dates|year|years)\s+(of|for|when|that)\b/i,
+];
+// Strong single-hop signals — query is about a single subject's attribute
+const SINGLE_HOP_SUBJECT_PATTERNS = [
+    /^(what|who|where|which|when|how) (is|was|are|were|did|does|do) [A-Z][a-z]+/,
+    /^(tell me|describe|explain|summarize)/i,
+    /\b(his|her|their|its) (name|job|career|hobby|hobbies|death|purchase|friend|partner)\b/i,
+];
+// ── Entity extraction ─────────────────────────────────────────────────────
+/** TitleCase word pattern (starts with capital, >= 2 chars) */
+const TITLE_CASE_WORD = /\b[A-Z][a-z][a-zA-Z]*\b/g;
+/** Quoted string pattern */
+const QUOTED_STRING = /["']([^"']{2,30})["']/g;
+/** ALL-CAPS abbreviation (e.g. VR, NBA, UCSF) */
+const ALLCAPS_ABBREV = /\b[A-Z]{2,6}\b/g;
+const COMMON_TITLE_CASE_STOP_WORDS = new Set([
+    'The', 'A', 'An', 'In', 'On', 'At', 'To', 'For', 'Of', 'And', 'Or', 'But',
+    'By', 'Is', 'It', 'If', 'So', 'Do', 'Be', 'My', 'We', 'He', 'She', 'They',
+    'You', 'Me', 'Us', 'His', 'Her', 'Its', 'Our', 'Your', 'Who', 'What', 'How',
+    'When', 'Where', 'Which', 'Why', 'Would', 'Could', 'Should', 'Did', 'Does',
+    'Was', 'Were', 'Has', 'Have', 'Had', 'Will', 'Can', 'May', 'Might', 'Shall',
+    'Just', 'Also', 'Both', 'Each', 'With', 'From', 'That', 'This', 'These', 'Those',
+    'Any', 'All', 'Not', 'Now', 'Well', 'Too', 'Very', 'More', 'Most', 'Some',
+    'Same', 'Last', 'Next', 'New', 'Old', 'Then', 'Than', 'Into', 'Upon',
+]);
+/**
+ * Extract named entity candidates from a query string.
+ * Returns deduplicated lowercase entity tokens.
+ */
+export function extractQueryEntities(query) {
+    const candidates = new Set();
+    // Quoted strings first (highest confidence)
+    for (const m of query.matchAll(QUOTED_STRING)) {
+        const val = m[1].trim();
+        if (val.length >= 2)
+            candidates.add(val.toLowerCase());
+    }
+    // TitleCase words (excluding common stop words)
+    for (const m of query.matchAll(TITLE_CASE_WORD)) {
+        const word = m[0];
+        if (!COMMON_TITLE_CASE_STOP_WORDS.has(word)) {
+            candidates.add(word.toLowerCase());
+        }
+    }
+    // ALL-CAPS abbreviations
+    for (const m of query.matchAll(ALLCAPS_ABBREV)) {
+        candidates.add(m[0].toLowerCase());
+    }
+    return [...candidates];
+}
+/**
+ * Extract facet terms from a query string using the LoCoMo facet lexicon.
+ * Returns matched facet group names (deduplicated).
+ */
+export function extractQueryFacets(query) {
+    const lower = query.toLowerCase();
+    const matchedFacets = new Set();
+    for (const facet of QUESTION_SHAPE_FACETS) {
+        for (const term of facet.terms) {
+            if (lower.includes(term)) {
+                matchedFacets.add(facet.name);
+                break;
+            }
+        }
+    }
+    return [...matchedFacets];
+}
+/**
+ * Extract matched facet terms (raw tokens, not group names) from a query.
+ * Used for structured handoff header annotation.
+ */
+export function extractQueryFacetTerms(query) {
+    const lower = query.toLowerCase();
+    const matched = [];
+    for (const term of FACET_TERM_SET) {
+        if (lower.includes(term))
+            matched.push(term);
+    }
+    return [...new Set(matched)];
+}
+// ── Relation word detection ───────────────────────────────────────────────
+function hasRelationWord(query) {
+    const lower = query.toLowerCase();
+    const words = lower.split(/\s+/);
+    return words.some(w => RELATION_WORDS.has(w.replace(/[^a-z]/g, '')));
+}
+// ── False-positive scoring ────────────────────────────────────────────────
+/**
+ * Estimate the probability that a 'multi-hop' classification is a false positive.
+ * Returns 0.0 (clearly multi-hop) to 1.0 (clearly single-hop / FP).
+ *
+ * High FP score → do not apply structured handoff even if multi-hop shape detected.
+ * Spec threshold: FP rate > 0.30 on held-out single-hop-multi-entity set →
+ * add a negative check. This function provides that check.
+ */
+export function questionShapeFalsePositiveScore(query) {
+    let fpScore = 0;
+    for (const pattern of TEMPORAL_SINGLE_HOP_PATTERNS) {
+        if (pattern.test(query)) {
+            fpScore += 0.35;
+            break;
+        }
+    }
+    for (const pattern of SINGLE_HOP_SUBJECT_PATTERNS) {
+        if (pattern.test(query)) {
+            fpScore += 0.25;
+            break;
+        }
+    }
+    // Short queries with < 7 words are unlikely to be true multi-hop
+    const wordCount = query.trim().split(/\s+/).length;
+    if (wordCount < 7)
+        fpScore += 0.15;
+    // If query has no relation word at all, reduce confidence
+    if (!hasRelationWord(query))
+        fpScore += 0.30;
+    return Math.min(1.0, fpScore);
+}
+// ── Main detector ─────────────────────────────────────────────────────────
+/**
+ * Detect whether a query has multi-hop shape.
+ *
+ * Multi-hop criteria (all must be true):
+ *   1. 2+ named entities OR (1 entity + 1 facet group)
+ *   2. At least one relation/intersection word
+ *   3. False-positive score < 0.60
+ *
+ * Returns a QuestionShape with extracted entities, facets, and confidence.
+ */
+export function detectQuestionShape(query) {
+    if (!query || !query.trim()) {
+        return { kind: 'single-hop', entities: [], facets: [], confidence: 0.9 };
+    }
+    const entities = extractQueryEntities(query);
+    const facets = extractQueryFacets(query);
+    const fpScore = questionShapeFalsePositiveScore(query);
+    const hasEnoughSignals = entities.length >= 2 ||
+        (entities.length >= 1 && facets.length >= 1);
+    const hasRelation = hasRelationWord(query);
+    const isSafe = fpScore < 0.35;
+    if (hasEnoughSignals && hasRelation && isSafe) {
+        // Confidence: scale down by FP score
+        const baseConfidence = Math.min(1.0, 0.5 + (entities.length * 0.15) + (facets.length * 0.10));
+        const confidence = Math.max(0.1, baseConfidence * (1 - fpScore));
+        return { kind: 'multi-hop', entities, facets, confidence };
+    }
+    // Single-hop: confidence is inverse of multi-hop signals
+    const singleHopConfidence = Math.min(1.0, 0.5 + fpScore * 0.5);
+    return { kind: 'single-hop', entities, facets, confidence: singleHopConfidence };
+}
+//# sourceMappingURL=question-shape.js.map