@pellux/goodvibes-sdk 0.26.7 → 0.26.9

package/dist/_internal/platform/knowledge/home-graph/review.js

@@ -0,0 +1,183 @@
+import { belongsToSpace, buildHomeGraphMetadata, readRecord } from './helpers.js';
+export async function reviewHomeGraphFact(store, spaceId, installationId, input) {
+    const reviewedAt = Date.now();
+    if (input.issueId) {
+        const issue = store.getIssue(input.issueId);
+        if (!issue || !belongsToSpace(issue, spaceId))
+            throw new Error(`Unknown Home Graph issue: ${input.issueId}`);
+        const subjectNode = issue.nodeId ? store.getNode(issue.nodeId) : null;
+        const appliedFacts = await applyHomeGraphReviewFacts(store, spaceId, issue, subjectNode, input);
+        const suppression = buildSuppression(input, issue, reviewedAt);
+        const updatedIssue = await store.upsertIssue({
+            id: issue.id,
+            severity: issue.severity,
+            code: issue.code,
+            message: issue.message,
+            status: issueStatusForAction(input.action, issue.status),
+            sourceId: issue.sourceId,
+            nodeId: issue.nodeId,
+            metadata: buildHomeGraphMetadata(spaceId, installationId, {
+                review: reviewMetadata(input, reviewedAt),
+                ...(suppression ? { suppression } : {}),
+            }),
+        });
+        const node = appliedFacts?.node ?? subjectNode ?? undefined;
+        return {
+            ok: true,
+            spaceId,
+            issue: updatedIssue,
+            ...(node ? { node } : {}),
+            ...(suppression ? { suppression } : {}),
+            ...(appliedFacts?.facts ? { appliedFacts: appliedFacts.facts } : {}),
+        };
+    }
+    if (input.nodeId) {
+        const node = store.getNode(input.nodeId);
+        if (!node || !belongsToSpace(node, spaceId))
+            throw new Error(`Unknown Home Graph node: ${input.nodeId}`);
+        const facts = normalizeReviewFacts(input);
+        const updated = await store.upsertNode({
+            id: node.id,
+            kind: node.kind,
+            slug: node.slug,
+            title: node.title,
+            summary: node.summary,
+            aliases: node.aliases,
+            status: input.action === 'forget' ? 'stale' : node.status,
+            confidence: input.action === 'accept' ? 100 : node.confidence,
+            sourceId: node.sourceId,
+            metadata: buildHomeGraphMetadata(spaceId, installationId, {
+                ...facts,
+                review: reviewMetadata(input, reviewedAt),
+            }),
+        });
+        return { ok: true, spaceId, node: updated, ...(Object.keys(facts).length > 0 ? { appliedFacts: facts } : {}) };
+    }
+    if (input.sourceId) {
+        const source = store.getSource(input.sourceId);
+        if (!source || !belongsToSpace(source, spaceId))
+            throw new Error(`Unknown Home Graph source: ${input.sourceId}`);
+        const updated = await store.upsertSource({
+            id: source.id,
+            connectorId: source.connectorId,
+            sourceType: source.sourceType,
+            title: source.title,
+            sourceUri: source.sourceUri,
+            canonicalUri: source.canonicalUri,
+            summary: source.summary,
+            description: source.description,
+            tags: source.tags,
+            folderPath: source.folderPath,
+            status: input.action === 'forget' ? 'stale' : source.status,
+            artifactId: source.artifactId,
+            contentHash: source.contentHash,
+            lastCrawledAt: source.lastCrawledAt,
+            crawlError: source.crawlError,
+            sessionId: source.sessionId,
+            metadata: buildHomeGraphMetadata(spaceId, installationId, {
+                review: reviewMetadata(input, reviewedAt),
+            }),
+        });
+        return { ok: true, spaceId, source: updated };
+    }
+    throw new Error('reviewFact requires issueId, nodeId, or sourceId.');
+}
+async function applyHomeGraphReviewFacts(store, spaceId, issue, node, input) {
+    if (!node || !belongsToSpace(node, spaceId))
+        return undefined;
+    const facts = deriveIssueFacts(issue, input);
+    if (Object.keys(facts).length === 0)
+        return undefined;
+    const updated = await store.upsertNode({
+        id: node.id,
+        kind: node.kind,
+        slug: node.slug,
+        title: node.title,
+        summary: node.summary,
+        aliases: node.aliases,
+        status: node.status,
+        confidence: Math.max(node.confidence, input.action === 'accept' ? 100 : node.confidence),
+        sourceId: node.sourceId,
+        metadata: facts,
+    });
+    return { node: updated, facts };
+}
+function deriveIssueFacts(issue, input) {
+    const facts = normalizeReviewFacts(input);
+    if (issue.code === 'homegraph.device.unknown_battery') {
+        const category = readCategory(input);
+        const batteryType = readString(facts.batteryType);
+        if (batteryType && batteryType !== 'none' && typeof facts.batteryPowered !== 'boolean') {
+            return { ...facts, batteryPowered: true };
+        }
+        if (facts.batteryPowered === false && !batteryType) {
+            return { ...facts, batteryType: 'none' };
+        }
+        if (Object.keys(facts).length > 0)
+            return facts;
+        if (input.action === 'reject' || input.action === 'resolve' || category === 'not_applicable') {
+            return { batteryPowered: false, batteryType: 'none' };
+        }
+    }
+    if (issue.code === 'homegraph.device.missing_manual') {
+        const category = readCategory(input);
+        if (Object.keys(facts).length > 0)
+            return facts;
+        if (input.action === 'reject' || input.action === 'resolve' || category === 'not_applicable') {
+            return { manualRequired: false };
+        }
+    }
+    return facts;
+}
+function normalizeReviewFacts(input) {
+    const value = readRecord(input.value);
+    const fact = readRecord(value.fact);
+    const source = Object.keys(fact).length > 0 ? fact : value;
+    const allowed = {};
+    for (const key of [
+        'batteryPowered',
+        'batteryType',
+        'manualRequired',
+        'manufacturer',
+        'model',
+        'serial',
+        'firmware',
+        'installDate',
+        'purchaseDate',
+        'warrantyExpiration',
+    ]) {
+        if (key in source)
+            allowed[key] = source[key];
+    }
+    return allowed;
+}
+function reviewMetadata(input, reviewedAt) {
+    return {
+        action: input.action,
+        reviewer: input.reviewer ?? 'homeassistant',
+        reviewedAt,
+        ...(input.value ? { value: input.value } : {}),
+    };
+}
+function buildSuppression(input, issue, reviewedAt) {
+    if (!['accept', 'reject', 'resolve'].includes(input.action))
+        return undefined;
+    return {
+        suppressed: true,
+        action: input.action,
+        reviewedAt,
+        reviewer: input.reviewer ?? 'homeassistant',
+        issueId: issue.id,
+        code: issue.code,
+        subjectId: issue.metadata.subjectId ?? issue.nodeId ?? issue.sourceId ?? issue.id,
+    };
+}
+function issueStatusForAction(action, current) {
+    return action === 'reject' || action === 'resolve' || action === 'accept' ? 'resolved' : current;
+}
+function readCategory(input) {
+    return readString(readRecord(input.value).category)?.toLowerCase().replace(/[-\s]+/g, '_');
+}
+function readString(value) {
+    return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+}

package/dist/_internal/platform/knowledge/home-graph/search.d.ts

@@ -9,5 +9,5 @@ export interface HomeGraphSearchState {
     readonly extractionBySourceId: ReadonlyMap<string, KnowledgeExtractionRecord>;
 }
 export declare function readHomeGraphSearchState(store: KnowledgeStore, spaceId: string): HomeGraphSearchState;
-export declare function scoreHomeGraphResults(query: string, sources: readonly KnowledgeSourceRecord[], nodes: readonly KnowledgeNodeRecord[], extractionBySourceId: (sourceId: string) => KnowledgeExtractionRecord | null | undefined, limit: number): HomeGraphSearchResult[];
+export declare function scoreHomeGraphResults(query: string, sources: readonly KnowledgeSourceRecord[], nodes: readonly KnowledgeNodeRecord[], edges: readonly KnowledgeEdgeRecord[], extractionBySourceId: (sourceId: string) => KnowledgeExtractionRecord | null | undefined, limit: number): HomeGraphSearchResult[];
 //# sourceMappingURL=search.d.ts.map

package/dist/_internal/platform/knowledge/home-graph/search.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../../../../src/_internal/platform/knowledge/home-graph/search.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,KAAK,EACV,mBAAmB,EACnB,yBAAyB,EACzB,mBAAmB,EACnB,qBAAqB,EACtB,MAAM,aAAa,CAAC;AAErB,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAMxD,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,SAAS,qBAAqB,EAAE,CAAC;IACnD,QAAQ,CAAC,KAAK,EAAE,SAAS,mBAAmB,EAAE,CAAC;IAC/C,QAAQ,CAAC,KAAK,EAAE,SAAS,mBAAmB,EAAE,CAAC;IAC/C,QAAQ,CAAC,oBAAoB,EAAE,WAAW,CAAC,MAAM,EAAE,yBAAyB,CAAC,CAAC;CAC/E;AAED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,GAAG,oBAAoB,CAqBrG;AAED,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,SAAS,qBAAqB,EAAE,EACzC,KAAK,EAAE,SAAS,mBAAmB,EAAE,EACrC,oBAAoB,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,yBAAyB,GAAG,IAAI,GAAG,SAAS,EACxF,KAAK,EAAE,MAAM,GACZ,qBAAqB,EAAE,CA+CzB"}
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../../../../src/_internal/platform/knowledge/home-graph/search.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,KAAK,EACV,mBAAmB,EACnB,yBAAyB,EACzB,mBAAmB,EACnB,qBAAqB,EACtB,MAAM,aAAa,CAAC;AAErB,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AA6DxD,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,SAAS,qBAAqB,EAAE,CAAC;IACnD,QAAQ,CAAC,KAAK,EAAE,SAAS,mBAAmB,EAAE,CAAC;IAC/C,QAAQ,CAAC,KAAK,EAAE,SAAS,mBAAmB,EAAE,CAAC;IAC/C,QAAQ,CAAC,oBAAoB,EAAE,WAAW,CAAC,MAAM,EAAE,yBAAyB,CAAC,CAAC;CAC/E;AAED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,GAAG,oBAAoB,CAqBrG;AAED,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,SAAS,qBAAqB,EAAE,EACzC,KAAK,EAAE,SAAS,mBAAmB,EAAE,EACrC,KAAK,EAAE,SAAS,mBAAmB,EAAE,EACrC,oBAAoB,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,yBAAyB,GAAG,IAAI,GAAG,SAAS,EACxF,KAAK,EAAE,MAAM,GACZ,qBAAqB,EAAE,CA+DzB"}

package/dist/_internal/platform/knowledge/home-graph/search.js

@@ -2,6 +2,58 @@ import { belongsToSpace, edgeIsActive, readRecord } from './helpers.js';
 const MAX_FIELD_CHARS = 4_096;
 const MAX_SECTION_COUNT = 32;
 const MAX_SEARCH_TEXT_CHARS = 64 * 1024;
+const MAX_ANSWER_EXCERPT_CHARS = 640;
+const ANCHOR_SCOPE_LIMIT = 5;
+const STOPWORDS = new Set([
+    'a',
+    'about',
+    'all',
+    'an',
+    'and',
+    'are',
+    'as',
+    'at',
+    'available',
+    'be',
+    'can',
+    'could',
+    'do',
+    'does',
+    'for',
+    'from',
+    'has',
+    'have',
+    'how',
+    'i',
+    'in',
+    'is',
+    'it',
+    'me',
+    'my',
+    'of',
+    'on',
+    'or',
+    'our',
+    'show',
+    'tell',
+    'that',
+    'the',
+    'this',
+    'to',
+    'use',
+    'what',
+    'which',
+    'with',
+]);
+const SHORT_MEANINGFUL_TOKENS = new Set(['ac', 'av', 'dc', 'ha', 'ip', 'ir', 'lg', 'pc', 'tv']);
+const QUERY_EXPANSIONS = {
+    capability: ['capabilities', 'feature', 'features', 'function', 'functions', 'mode', 'modes', 'spec', 'specs', 'support', 'supports'],
+    capabilities: ['capability', 'feature', 'features', 'function', 'functions', 'mode', 'modes', 'spec', 'specs', 'support', 'supports'],
+    feature: ['features', 'capability', 'capabilities', 'function', 'functions', 'mode', 'modes', 'spec', 'specs', 'support', 'supports'],
+    features: ['feature', 'capability', 'capabilities', 'function', 'functions', 'mode', 'modes', 'spec', 'specs', 'support', 'supports'],
+    television: ['tv', 'media_player'],
+    tv: ['television', 'media_player'],
+};
 export function readHomeGraphSearchState(store, spaceId) {
     const sources = store.listSources(10_000).filter((source) => belongsToSpace(source, spaceId));
     const nodes = store.listNodes(10_000).filter((node) => belongsToSpace(node, spaceId));
@@ -23,54 +75,81 @@ export function readHomeGraphSearchState(store, spaceId) {
     }
     return { spaceId, sources, nodes, edges, extractionBySourceId };
 }
-export function scoreHomeGraphResults(query, sources, nodes, extractionBySourceId, limit) {
-    const tokens = tokenize(query);
+export function scoreHomeGraphResults(query, sources, nodes, edges, extractionBySourceId, limit) {
+    const tokens = tokenizeQuery(query);
     if (tokens.length === 0)
         return [];
+    const expandedTokens = expandTokens(tokens);
+    const anchors = selectAnchorNodes(tokens, nodes);
+    const anchorIds = new Set(anchors.map((anchor) => anchor.node.id));
+    const sourceLinks = buildSourceLinkIndex(edges);
+    const useAnchorScope = anchors.length > 0 && anchors.length <= ANCHOR_SCOPE_LIMIT;
     const sourceResults = sources.map((source) => {
         const extraction = extractionBySourceId(source.id);
-        const baseScore = scoreFields(tokens, [
+        if (isPendingDocumentationCandidate(source, extraction)) {
+            return sourceResult(source, extraction, 0);
+        }
+        const linkedNodeIds = sourceLinks.get(source.id) ?? new Set();
+        const linkedToAnchor = useAnchorScope && intersects(linkedNodeIds, anchorIds);
+        const identityScore = scoreFields(tokens, [
             source.title,
             source.summary,
             source.description,
             source.sourceUri,
             source.canonicalUri,
             source.tags.join(' '),
+        ]);
+        const contentScore = scoreFields(expandedTokens, [
             extraction?.title,
             extraction?.summary,
             extraction?.excerpt,
             readSearchText(extraction),
             ...limitedSections(extraction),
         ]);
-        return {
-            kind: 'source',
-            id: source.id,
-            score: baseScore > 0 ? baseScore + (extraction ? 8 : 0) : 0,
-            title: source.title ?? source.sourceUri ?? source.id,
-            summary: extraction?.summary ?? source.summary,
-            source,
-        };
+        const baseScore = identityScore + contentScore;
+        const linkBoost = linkedToAnchor ? 120 + relationBoost(source.id, anchorIds, edges) : 0;
+        const indexedBoost = source.status === 'indexed' ? 18 : source.status === 'stale' ? 6 : 0;
+        const extractionBoost = extraction ? 20 : 0;
+        const score = baseScore > 0 || linkBoost > 0
+            ? baseScore + linkBoost + indexedBoost + extractionBoost
+            : 0;
+        return sourceResult(source, extraction, score, selectRelevantExcerpt(expandedTokens, source, extraction));
     });
     const nodeResults = nodes.map((node) => {
-        const baseScore = scoreFields(tokens, [
-            node.title,
-            node.summary,
-            node.aliases.join(' '),
-            readNodeMetadataText(node),
-        ]);
+        const baseScore = scoreFields(tokens, nodeIdentityFields(node));
+        const anchorBoost = anchorIds.has(node.id) ? 40 + nodeKindBoost(node.kind) : 0;
         return {
             kind: 'node',
             id: node.id,
-            score: baseScore > 0 ? baseScore + Math.round(node.confidence / 20) : 0,
+            score: baseScore > 0 ? baseScore + anchorBoost + Math.round(node.confidence / 20) : 0,
             title: node.title,
             summary: node.summary,
+            excerpt: node.summary,
             node,
         };
     });
-    return [...sourceResults, ...nodeResults]
+    let results = [...sourceResults, ...nodeResults]
         .filter((entry) => entry.score > 0)
-        .sort((a, b) => b.score - a.score || a.id.localeCompare(b.id))
-        .slice(0, Math.max(1, limit));
+        .sort(compareHomeGraphResults);
+    const anchoredSourceResults = useAnchorScope
+        ? results.filter((result) => result.source && intersects(sourceLinks.get(result.source.id) ?? new Set(), anchorIds))
+        : [];
+    if (anchoredSourceResults.length > 0) {
+        results = anchoredSourceResults.sort(compareHomeGraphResults);
+    }
+    const strongResults = pruneWeakTokenCoverage(results, tokens);
+    return strongResults.slice(0, Math.max(1, limit));
+}
+function sourceResult(source, extraction, score, excerpt) {
+    return {
+        kind: 'source',
+        id: source.id,
+        score,
+        title: source.title ?? source.sourceUri ?? source.id,
+        summary: extraction?.summary ?? source.summary,
+        ...(excerpt ? { excerpt } : {}),
+        source,
+    };
 }
 function limitedSections(extraction) {
     if (!extraction)
@@ -103,6 +182,168 @@ function readNodeMetadataText(node) {
     ].filter((value) => typeof value === 'string' && value.trim().length > 0);
     return values.length > 0 ? values.join(' ') : undefined;
 }
+function nodeIdentityFields(node) {
+    return [
+        node.title,
+        node.summary,
+        node.aliases.join(' '),
+        readNodeMetadataText(node),
+    ].filter((value) => typeof value === 'string' && value.trim().length > 0);
+}
+function selectAnchorNodes(tokens, nodes) {
+    return nodes.map((node) => {
+        const baseScore = scoreFields(tokens, nodeIdentityFields(node));
+        return {
+            node,
+            score: baseScore > 0 ? baseScore + nodeKindBoost(node.kind) : 0,
+        };
+    })
+        .filter((entry) => entry.score >= 10)
+        .sort((a, b) => b.score - a.score || a.node.id.localeCompare(b.node.id))
+        .slice(0, 12);
+}
+function buildSourceLinkIndex(edges) {
+    const links = new Map();
+    for (const edge of edges) {
+        if (edge.fromKind === 'source' && edge.toKind === 'node') {
+            addSourceLink(links, edge.fromId, edge.toId);
+        }
+        else if (edge.fromKind === 'node' && edge.toKind === 'source') {
+            addSourceLink(links, edge.toId, edge.fromId);
+        }
+    }
+    return links;
+}
+function addSourceLink(links, sourceId, nodeId) {
+    const current = links.get(sourceId) ?? new Set();
+    current.add(nodeId);
+    links.set(sourceId, current);
+}
+function relationBoost(sourceId, anchorIds, edges) {
+    let boost = 0;
+    for (const edge of edges) {
+        const connectsAnchor = (edge.fromKind === 'source' && edge.fromId === sourceId && edge.toKind === 'node' && anchorIds.has(edge.toId))
+            || (edge.fromKind === 'node' && anchorIds.has(edge.fromId) && edge.toKind === 'source' && edge.toId === sourceId);
+        if (!connectsAnchor)
+            continue;
+        if (edge.relation === 'has_manual')
+            boost = Math.max(boost, 45);
+        else if (edge.relation === 'source_for')
+            boost = Math.max(boost, 25);
+        else
+            boost = Math.max(boost, 15);
+    }
+    return boost;
+}
+function nodeKindBoost(kind) {
+    switch (kind) {
+        case 'ha_device':
+        case 'ha_entity':
+            return 20;
+        case 'ha_area':
+        case 'ha_room':
+        case 'ha_automation':
+        case 'ha_script':
+        case 'ha_scene':
+            return 12;
+        case 'ha_integration':
+            return 6;
+        default:
+            return 0;
+    }
+}
+function intersects(left, right) {
+    for (const value of left) {
+        if (right.has(value))
+            return true;
+    }
+    return false;
+}
+function isPendingDocumentationCandidate(source, extraction) {
+    return !extraction
+        && source.status !== 'indexed'
+        && source.metadata.homeGraphSourceKind === 'documentation-candidate';
+}
+function selectRelevantExcerpt(tokens, source, extraction) {
+    const chunks = candidateExcerptChunks(source, extraction);
+    let best;
+    for (const chunk of chunks) {
+        const text = cleanWhitespace(chunk);
+        if (!text)
+            continue;
+        const score = scoreFields(tokens, [text]);
+        if (!best || score > best.score || (score === best.score && text.length < best.text.length)) {
+            best = { score, text };
+        }
+    }
+    if (!best || best.score <= 0)
+        return firstBoundedText(chunks, MAX_ANSWER_EXCERPT_CHARS);
+    return clampAroundBestToken(best.text, tokens, MAX_ANSWER_EXCERPT_CHARS);
+}
+function candidateExcerptChunks(source, extraction) {
+    const searchText = readSearchText(extraction);
+    return [
+        extraction?.excerpt,
+        extraction?.summary,
+        ...limitedSections(extraction),
+        ...sentenceChunks(searchText),
+        source.description,
+        source.summary,
+    ].filter((value) => typeof value === 'string' && value.trim().length > 0);
+}
+function sentenceChunks(value) {
+    const text = cleanWhitespace(value ?? '');
+    if (!text)
+        return [];
+    const matches = text.match(/[^.!?\n]+[.!?]?/g) ?? [text];
+    return matches.map((entry) => entry.trim()).filter(Boolean).slice(0, 80);
+}
+function clampAroundBestToken(value, tokens, maxLength) {
+    const text = cleanWhitespace(value);
+    if (text.length <= maxLength)
+        return text;
+    const lower = text.toLowerCase();
+    const index = tokens
+        .map((token) => lower.indexOf(token.toLowerCase()))
+        .filter((entry) => entry >= 0)
+        .sort((a, b) => a - b)[0] ?? 0;
+    const start = Math.max(0, index - Math.floor(maxLength / 3));
+    const end = Math.min(text.length, start + maxLength);
+    const prefix = start > 0 ? '...' : '';
+    const suffix = end < text.length ? '...' : '';
+    return `${prefix}${text.slice(start, end).trim()}${suffix}`;
+}
+function cleanWhitespace(value) {
+    return value.replace(/\s+/g, ' ').trim();
+}
+function pruneWeakTokenCoverage(results, tokens) {
+    if (results.length <= 1 || tokens.length <= 1)
+        return [...results];
+    const topCoverage = tokenCoverage(tokens, resultText(results[0]));
+    if (topCoverage < 2)
+        return [...results];
+    return results.filter((result) => tokenCoverage(tokens, resultText(result)) >= Math.max(1, topCoverage - 1));
+}
+function tokenCoverage(tokens, text) {
+    const haystack = text.toLowerCase();
+    let count = 0;
+    for (const token of tokens) {
+        if (fieldIncludesToken(haystack, token))
+            count += 1;
+    }
+    return count;
+}
+function resultText(result) {
+    return [
+        result.title,
+        result.summary,
+        result.excerpt,
+        result.source?.description,
+        result.source?.sourceUri,
+        result.source?.canonicalUri,
+        result.source?.tags.join(' '),
+    ].filter((value) => typeof value === 'string').join(' ');
+}
 function firstBoundedText(values, maxLength) {
     for (const value of values) {
         if (typeof value !== 'string')
@@ -117,8 +358,31 @@ function firstBoundedText(values, maxLength) {
 function clampText(value, maxLength) {
     return value.length <= maxLength ? value : value.slice(0, maxLength);
 }
-function tokenize(value) {
-    return value.toLowerCase().split(/[^a-z0-9_.:-]+/).map((entry) => entry.trim()).filter(Boolean);
+function tokenizeQuery(value) {
+    const tokens = value.toLowerCase()
+        .split(/[^a-z0-9_.:-]+/)
+        .map((entry) => entry.trim())
+        .filter((entry) => isMeaningfulToken(entry));
+    return [...new Set(tokens)];
+}
+function expandTokens(tokens) {
+    const expanded = new Set();
+    for (const token of tokens) {
+        expanded.add(token);
+        for (const synonym of QUERY_EXPANSIONS[token] ?? []) {
+            expanded.add(synonym);
+        }
+    }
+    return [...expanded];
+}
+function isMeaningfulToken(token) {
+    if (!token || STOPWORDS.has(token))
+        return false;
+    if (token.length === 1)
+        return false;
+    if (token.length <= 2 && !SHORT_MEANINGFUL_TOKENS.has(token))
+        return false;
+    return true;
 }
 function scoreFields(tokens, fields) {
     let score = 0;
@@ -128,9 +392,30 @@ function scoreFields(tokens, fields) {
         if (!haystack)
             continue;
         for (const token of tokens) {
-            if (haystack.includes(token))
-                score += 10;
+            if (fieldIncludesToken(haystack, token))
+                score += token.length <= 3 ? 14 : 10;
         }
     }
     return score;
 }
+function fieldIncludesToken(haystack, token) {
+    if (token.length <= 3 || token.includes('_') || token.includes('-')) {
+        return new RegExp(`(?:^|[^a-z0-9])${escapeRegExp(token)}(?:$|[^a-z0-9])`).test(haystack);
+    }
+    return haystack.includes(token);
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function compareHomeGraphResults(left, right) {
+    return right.score - left.score
+        || resultKindPriority(right) - resultKindPriority(left)
+        || left.id.localeCompare(right.id);
+}
+function resultKindPriority(result) {
+    if (result.source)
+        return 2;
+    if (result.node)
+        return 1;
+    return 0;
+}

package/dist/_internal/platform/knowledge/home-graph/service.d.ts

@@ -1,6 +1,7 @@
 import type { ArtifactStore } from '../../artifacts/index.js';
 import type { KnowledgeStore } from '../store.js';
 import type { KnowledgeEdgeRecord, KnowledgeIssueRecord, KnowledgeNodeRecord, KnowledgeSourceRecord } from '../types.js';
+import { type HomeGraphReviewResult } from './review.js';
 import type { HomeGraphAskInput, HomeGraphAskResult, HomeGraphDevicePassportResult, HomeGraphExport, HomeGraphIngestArtifactInput, HomeGraphIngestNoteInput, HomeGraphIngestResult, HomeGraphIngestUrlInput, HomeGraphLinkInput, HomeGraphLinkResult, HomeGraphProjectionInput, HomeGraphProjectionResult, HomeGraphReviewInput, HomeGraphSpaceInput, HomeGraphSnapshotInput, HomeGraphStatus, HomeGraphSyncResult } from './types.js';
 export declare class HomeGraphService {
     private readonly store;
@@ -30,13 +31,7 @@ export declare class HomeGraphService {
         readonly spaceId: string;
         readonly issues: readonly KnowledgeIssueRecord[];
     }>;
-    reviewFact(input: HomeGraphReviewInput): Promise<{
-        readonly ok: true;
-        readonly spaceId: string;
-        readonly issue?: KnowledgeIssueRecord;
-        readonly node?: KnowledgeNodeRecord;
-        readonly source?: KnowledgeSourceRecord;
-    }>;
+    reviewFact(input: HomeGraphReviewInput): Promise<HomeGraphReviewResult>;
     listSources(input?: HomeGraphSpaceInput & {
         readonly limit?: number;
     }): Promise<{

package/dist/_internal/platform/knowledge/home-graph/service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../../../../../src/_internal/platform/knowledge/home-graph/service.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../../../../../src/_internal/platform/knowledge/home-graph/service.ts"],"names":[],"mappings":"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"}