@pellux/goodvibes-sdk 0.28.12 → 0.28.14

package/dist/_internal/platform/knowledge/semantic/gap-repair.d.ts

@@ -24,6 +24,8 @@ export interface WebGapRepairOptions {
     readonly searchService: GapRepairSearch;
     readonly ingestService: GapRepairIngest;
     readonly maxResults?: number;
+    readonly maxSearches?: number;
+    readonly maxSources?: number;
     readonly minDistinctDomains?: number;
     readonly minConfidence?: number;
     readonly maxIngest?: number;

package/dist/_internal/platform/knowledge/semantic/gap-repair.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gap-repair.d.ts","sourceRoot":"","sources":["../../../../../src/_internal/platform/knowledge/semantic/gap-repair.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,gBAAgB,EAChB,iBAAiB,EAElB,MAAM,2BAA2B,CAAC;AAEnC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AACvD,OAAO,KAAK,EACV,4BAA4B,EAG7B,MAAM,YAAY,CAAC;AAGpB,UAAU,eAAe;IACvB,MAAM,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;CAC/D;AAED,UAAU,eAAe;IACvB,SAAS,CAAC,KAAK,EAAE;QACf,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;QACrB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QACxB,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;QAClC,QAAQ,CAAC,UAAU,CAAC,EAAE,mBAAmB,CAAC;QAC1C,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;QAC9B,QAAQ,CAAC,iBAAiB,CAAC,EAAE,OAAO,CAAC;QACrC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KAC7C,GAAG,OAAO,CAAC;QAAE,QAAQ,CAAC,MAAM,EAAE;YAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;YAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,CAAC,CAAC;CACpF;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,aAAa,EAAE,eAAe,CAAC;IACxC,QAAQ,CAAC,aAAa,EAAE,eAAe,CAAC;IACxC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;CACnC;AAmBD,wBAAgB,6BAA6B,CAAC,OAAO,EAAE,mBAAmB,GAAG,4BAA4B,CAExG"}
+{"version":3,"file":"gap-repair.d.ts","sourceRoot":"","sources":["../../../../../src/_internal/platform/knowledge/semantic/gap-repair.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,gBAAgB,EAChB,iBAAiB,EAElB,MAAM,2BAA2B,CAAC;AAEnC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AACvD,OAAO,KAAK,EACV,4BAA4B,EAG7B,MAAM,YAAY,CAAC;AAIpB,UAAU,eAAe;IACvB,MAAM,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;CAC/D;AAED,UAAU,eAAe;IACvB,SAAS,CAAC,KAAK,EAAE;QACf,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;QACrB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QACxB,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;QAClC,QAAQ,CAAC,UAAU,CAAC,EAAE,mBAAmB,CAAC;QAC1C,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;QAC9B,QAAQ,CAAC,iBAAiB,CAAC,EAAE,OAAO,CAAC;QACrC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KAC7C,GAAG,OAAO,CAAC;QAAE,QAAQ,CAAC,MAAM,EAAE;YAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;YAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,CAAC,CAAC;CACpF;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,aAAa,EAAE,eAAe,CAAC;IACxC,QAAQ,CAAC,aAAa,EAAE,eAAe,CAAC;IACxC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;CACnC;AA0BD,wBAAgB,6BAA6B,CAAC,OAAO,EAAE,mBAAmB,GAAG,4BAA4B,CAExG"}

package/dist/_internal/platform/knowledge/semantic/gap-repair.js

@@ -1,11 +1,12 @@
 import { canonicalizeUri } from '../internal.js';
+import { withTimeout } from './timeouts.js';
 import { readString, scoreSemanticText, tokenizeSemanticQuery, uniqueStrings } from './utils.js';
 export function createWebKnowledgeGapRepairer(options) {
     return async (request) => repairKnowledgeGapsWithWeb(request, options);
 }
 async function repairKnowledgeGapsWithWeb(request, options) {
-    const query = buildGapRepairQuery(request);
-    if (!query) {
+    const queries = buildGapRepairQueries(request);
+    if (queries.length === 0) {
         return {
             searched: false,
             ingestedSourceIds: [],
@@ -13,47 +14,77 @@ async function repairKnowledgeGapsWithWeb(request, options) {
             reason: 'No concrete subject was available for gap repair.',
         };
     }
-    let response;
-    try {
-        response = await withTimeout(options.searchService.search({
-            query,
-            maxResults: Math.max(2, Math.min(12, options.maxResults ?? 6)),
-            verbosity: 'snippets',
-            safeSearch: 'moderate',
-            metadata: {
-                purpose: 'knowledge-gap-repair',
-                knowledgeSpaceId: request.spaceId,
-            },
-        }), Math.max(1_000, options.searchTimeoutMs ?? 8_000), 'Semantic gap repair search timed out.');
+    const existing = existingSources(request);
+    const sourceLimit = Math.max(2, Math.min(5, request.maxSources ?? options.maxSources ?? options.maxIngest ?? 5));
+    const searchLimit = Math.max(1, Math.min(5, options.maxSearches ?? queries.length));
+    const existingCandidates = selectExistingRepairSources(request, options, sourceLimit);
+    const searchResults = new Map();
+    const providerIds = new Set();
+    let lastError;
+    for (const query of queries.slice(0, searchLimit)) {
+        if (request.signal?.aborted || deadlineExceeded(request.deadlineAt))
+            break;
+        try {
+            const timeoutMs = operationTimeout(request.deadlineAt, options.searchTimeoutMs ?? 8_000);
+            if (timeoutMs <= 0)
+                break;
+            const response = await withTimeout(options.searchService.search({
+                query,
+                maxResults: Math.max(sourceLimit, Math.min(8, options.maxResults ?? sourceLimit)),
+                verbosity: 'snippets',
+                safeSearch: 'moderate',
+                trustedHosts: trustedHostsForRepair(request),
+                metadata: {
+                    purpose: 'knowledge-gap-repair',
+                    knowledgeSpaceId: request.spaceId,
+                },
+            }), Math.max(1_000, timeoutMs), 'Semantic gap repair search timed out.');
+            if (response.providerId)
+                providerIds.add(response.providerId);
+            for (const result of response.results) {
+                const canonical = canonicalizeUri(result.url);
+                if (!canonical || searchResults.has(canonical))
+                    continue;
+                searchResults.set(canonical, { ...result, searchQuery: query, searchProviderId: response.providerId });
+            }
+            const partial = mergeRepairCandidates(existingCandidates, selectGapRepairCandidates([...searchResults.values()], existing, options, request, sourceLimit), sourceLimit);
+            if (hasEnoughRepairEvidence(partial, options))
+                break;
+        }
+        catch (error) {
+            lastError = error instanceof Error ? error.message : String(error);
+            if (deadlineExceeded(request.deadlineAt))
+                break;
+        }
     }
-    catch (error) {
+    const allResults = [...searchResults.values()];
+    const candidates = mergeRepairCandidates(existingCandidates, selectGapRepairCandidates(allResults, existing, options, request, sourceLimit), sourceLimit);
+    if (!hasEnoughRepairEvidence(candidates, options)) {
         return {
             searched: true,
-            query,
+            query: queries[0],
+            evidenceSufficient: false,
+            acceptedSourceIds: existingCandidates.map((candidate) => candidate.existingSourceId).filter((id) => Boolean(id)),
             ingestedSourceIds: [],
-            skippedUrls: [],
-            reason: error instanceof Error ? error.message : String(error),
-        };
-    }
-    const existing = new Set(request.sources.flatMap((source) => [
-        canonicalizeUri(source.canonicalUri ?? ''),
-        canonicalizeUri(source.sourceUri ?? ''),
-    ].filter((value) => Boolean(value))));
-    const candidates = selectGapRepairCandidates(response.results, existing, options, query, request);
-    if (candidates.length < Math.max(2, options.minDistinctDomains ?? 2)) {
-        return {
-            searched: true,
-            query,
-            ingestedSourceIds: [],
-            skippedUrls: response.results.map((result) => result.url),
-            sourceAssessments: buildSourceAssessments(response.results, candidates, existing, options, query, request),
-            reason: 'Fewer than two distinct external sources were found for source-backed gap repair.',
+            skippedUrls: allResults.map((result) => result.url),
+            sourceAssessments: [
+                ...existingCandidates.map((candidate) => candidateToAssessment(candidate, true)),
+                ...buildSourceAssessments(allResults, candidates, existing, options, request),
+            ],
+            reason: lastError ?? 'Insufficient distinct source-backed evidence was found for gap repair.',
         };
     }
     const ingestedSourceIds = [];
     const skippedUrls = [];
-    for (const result of candidates.slice(0, Math.max(2, Math.min(4, options.maxIngest ?? 2)))) {
+    const existingSourceIds = candidates.map((candidate) => candidate.existingSourceId).filter((id) => Boolean(id));
+    const newCandidates = candidates.filter((candidate) => !candidate.existingSourceId);
+    for (const result of newCandidates.slice(0, Math.max(0, Math.min(sourceLimit - existingSourceIds.length, options.maxIngest ?? sourceLimit)))) {
+        if (request.signal?.aborted || deadlineExceeded(request.deadlineAt))
+            break;
         try {
+            const timeoutMs = operationTimeout(request.deadlineAt, options.ingestTimeoutMs ?? 10_000);
+            if (timeoutMs <= 0)
+                break;
             const ingested = await withTimeout(options.ingestService.ingestUrl({
                 url: result.url,
                 ...(result.title ? { title: result.title } : {}),
@@ -64,8 +95,9 @@ async function repairKnowledgeGapsWithWeb(request, options) {
                     knowledgeSpaceId: request.spaceId,
                     sourceDiscovery: {
                         purpose: 'semantic-gap-repair',
-                        query,
-                        providerId: response.providerId,
+                        query: result.searchQuery,
+                        searchQueries: queries.slice(0, searchLimit),
+                        providerId: result.searchProviderId ?? [...providerIds][0],
                         gapIds: request.gaps.map((gap) => gap.id),
                         gapQuestions: request.gaps.map((gap) => gap.title),
                         originalSourceIds: request.sources.map((source) => source.id),
@@ -76,11 +108,12 @@ async function repairKnowledgeGapsWithWeb(request, options) {
                         sourceDomain: result.domain ?? safeDomain(result.url),
                         trustReason: result.reasons.join(', '),
                         agreementSourceCount: candidates.length,
+                        checkedSourceLimit: sourceLimit,
                         selectedUrl: result.url,
                         searchedAt: Date.now(),
                     },
                 },
-            }), Math.max(1_000, options.ingestTimeoutMs ?? 10_000), 'Semantic gap repair source ingest timed out.');
+            }), Math.max(1_000, timeoutMs), 'Semantic gap repair source ingest timed out.');
             if (ingested.source.status === 'indexed' || ingested.source.status === 'pending') {
                 ingestedSourceIds.push(ingested.source.id);
             }
@@ -92,27 +125,35 @@ async function repairKnowledgeGapsWithWeb(request, options) {
     }
     return {
         searched: true,
-        query,
+        query: queries[0],
+        evidenceSufficient: true,
+        acceptedSourceIds: uniqueStrings([...existingSourceIds, ...ingestedSourceIds]),
         ingestedSourceIds,
         skippedUrls,
-        sourceAssessments: buildSourceAssessments(response.results, candidates, existing, options, query, request),
-        ...(ingestedSourceIds.length < 2 ? { reason: 'Gap repair searched but fewer than two sources were ingested.' } : {}),
+        sourceAssessments: [
+            ...existingCandidates.map((candidate) => candidateToAssessment(candidate, candidates.some((entry) => entry.url === candidate.url))),
+            ...buildSourceAssessments(allResults, candidates, existing, options, request),
+        ],
+        ...(existingSourceIds.length + ingestedSourceIds.length < 1 ? { reason: 'Gap repair searched but did not accept usable sources.' } : {}),
     };
 }
-function buildGapRepairQuery(request) {
+function buildGapRepairQueries(request) {
     const subject = bestSubject(request);
     if (!subject)
-        return null;
-    const gapTerms = uniqueStrings(request.gaps.flatMap((gap) => [
+        return [];
+    const gapTerms = clampSearchTerms(uniqueStrings(request.gaps.flatMap((gap) => [
         gap.title,
         gap.summary,
         readString(gap.metadata.reason),
-    ])).join(' ');
+    ])).join(' '));
+    const profileTerms = inferGapProfileTerms(request);
     return uniqueStrings([
-        subject,
-        gapTerms,
-        'official specifications features',
-    ]).join(' ');
+        [subject, gapTerms, 'official specifications'].filter(Boolean).join(' '),
+        [subject, profileTerms, 'product specifications'].filter(Boolean).join(' '),
+        [subject, profileTerms, 'features ports connectivity audio display'].filter(Boolean).join(' '),
+        [subject, 'manufacturer product page specifications'].join(' '),
+        [subject, 'datasheet manual specifications'].join(' '),
+    ].map((query) => query.replace(/\s+/g, ' ').trim()).filter(Boolean));
 }
 function bestSubject(request) {
     const linked = request.linkedObjects[0];
@@ -129,8 +170,39 @@ function bestSubject(request) {
         source?.title,
     ]).join(' ') || null;
 }
-function selectGapRepairCandidates(results, existingCanonicalUris, options, query, request) {
-    const tokens = tokenizeSemanticQuery(query);
+function inferGapProfileTerms(request) {
+    const text = request.gaps.map((gap) => `${gap.title} ${gap.summary ?? ''}`).join(' ').toLowerCase();
+    const terms = [];
+    if (/\b(port|ports|hdmi|usb|optical|rf|antenna|ethernet|rs-?232|composite|component|input|output|i\/o)\b/.test(text)) {
+        terms.push('ports inputs outputs connectivity');
+    }
+    if (/\b(bluetooth|wifi|wi-fi|wireless|network)\b/.test(text))
+        terms.push('wireless bluetooth wi-fi network');
+    if (/\b(refresh|hz|hdr|dolby|vision|gaming|vrr|allm|freesync)\b/.test(text))
+        terms.push('refresh rate hdr gaming vrr allm');
+    if (/\b(audio|speaker|sound|earc|arc)\b/.test(text))
+        terms.push('audio speakers earc arc');
+    if (/\b(display|screen|resolution|panel|lcd|oled|qled|nanocell)\b/.test(text))
+        terms.push('display resolution panel');
+    return uniqueStrings([
+        ...terms,
+        ...tokenizeSemanticQuery(text)
+            .filter((token) => token.length >= 3)
+            .filter((token) => !['what', 'does', 'have', 'which', 'with', 'from', 'that', 'this', 'current', 'source', 'text'].includes(token))
+            .slice(0, 12),
+    ]).join(' ');
+}
+function clampSearchTerms(value) {
+    return tokenizeSemanticQuery(value).slice(0, 24).join(' ');
+}
+function existingSources(request) {
+    return new Set(request.sources.flatMap((source) => [
+        canonicalizeUri(source.canonicalUri ?? ''),
+        canonicalizeUri(source.sourceUri ?? ''),
+    ].filter((value) => Boolean(value))));
+}
+function selectGapRepairCandidates(results, existingCanonicalUris, options, request, sourceLimit) {
+    const tokens = tokenizeSemanticQuery([bestSubject(request), inferGapProfileTerms(request)].filter(Boolean).join(' '));
     const minimumConfidence = Math.max(1, Math.min(100, options.minConfidence ?? 70));
     const byDomain = new Map();
     for (const result of results) {
@@ -143,14 +215,52 @@ function selectGapRepairCandidates(results, existingCanonicalUris, options, quer
         const domain = result.domain ?? safeDomain(result.url);
         if (!domain || byDomain.has(domain))
             continue;
-        const assessment = assessGapRepairSource(result, query, request);
+        const assessment = assessGapRepairSource(result, result.searchQuery, request);
         if (assessment.confidence < minimumConfidence)
             continue;
         byDomain.set(domain, { ...result, confidence: assessment.confidence, reasons: assessment.reasons });
     }
     return [...byDomain.values()]
-        .sort((left, right) => right.confidence - left.confidence || left.rank - right.rank)
-        .slice(0, Math.max(2, Math.min(8, options.maxResults ?? 6)));
+        .sort(compareRepairCandidates)
+        .slice(0, sourceLimit);
+}
+function selectExistingRepairSources(request, options, sourceLimit) {
+    const minimumConfidence = Math.max(1, Math.min(100, options.minConfidence ?? 70));
+    const byDomain = new Map();
+    for (const source of request.sources) {
+        if (source.status !== 'indexed' || isGeneratedOrSyntheticSource(source))
+            continue;
+        const url = source.sourceUri ?? source.canonicalUri;
+        if (!url)
+            continue;
+        const domain = safeDomain(url);
+        if (!domain || byDomain.has(domain))
+            continue;
+        const snippet = [source.summary, source.description, source.tags.join(' ')].filter(Boolean).join(' ');
+        const result = {
+            rank: 0,
+            url,
+            domain,
+            displayUrl: url,
+            type: 'organic',
+            providerId: 'indexed',
+            metadata: source.metadata,
+            searchQuery: request.query,
+            searchProviderId: 'indexed',
+            ...(source.title ? { title: source.title } : {}),
+            ...(snippet ? { snippet } : {}),
+        };
+        const assessment = assessGapRepairSource(result, request.query, request);
+        if (assessment.confidence < minimumConfidence && !isOfficialOrVendorSource(assessment.reasons))
+            continue;
+        byDomain.set(domain, {
+            ...result,
+            existingSourceId: source.id,
+            confidence: Math.max(assessment.confidence, isOfficialOrVendorSource(assessment.reasons) ? 82 : assessment.confidence),
+            reasons: uniqueStrings([...assessment.reasons, 'already-indexed']),
+        });
+    }
+    return [...byDomain.values()].sort(compareRepairCandidates).slice(0, sourceLimit);
 }
 function assessGapRepairSource(result, query, request) {
     const searchable = [result.title, result.snippet, result.url, result.domain].filter(Boolean).join(' ').toLowerCase();
@@ -194,26 +304,61 @@ function assessGapRepairSource(result, query, request) {
         reasons.push('source-purpose');
     }
     if (domain && identities.manufacturers.some((manufacturer) => manufacturer.length >= 2 && domain.includes(manufacturer.toLowerCase()))) {
-        score += 10;
+        score += 28;
         reasons.push('manufacturer-domain');
     }
+    if (domain && isOfficialVendorDomain(domain, identities.manufacturers)) {
+        score += 28;
+        reasons.push('official-vendor-domain');
+    }
     return {
         url: result.url,
         ...(result.title ? { title: result.title } : {}),
         ...(domain ? { domain } : {}),
         rank: result.rank,
+        query: result.searchQuery,
         confidence: Math.max(0, Math.min(100, score)),
         reasons,
         ...(reasons.length > 0 ? { trustReason: reasons.join(', ') } : {}),
     };
 }
-function buildSourceAssessments(results, candidates, existingCanonicalUris, options, query, request) {
+function mergeRepairCandidates(existingCandidates, searchCandidates, sourceLimit) {
+    const byCanonical = new Map();
+    for (const candidate of [...existingCandidates, ...searchCandidates]) {
+        const key = canonicalizeUri(candidate.url) ?? candidate.url;
+        const current = byCanonical.get(key);
+        if (!current || compareRepairCandidates(candidate, current) < 0)
+            byCanonical.set(key, candidate);
+    }
+    return [...byCanonical.values()].sort(compareRepairCandidates).slice(0, sourceLimit);
+}
+function hasEnoughRepairEvidence(candidates, options) {
+    if (candidates.some((candidate) => candidate.reasons.includes('official-vendor-domain')))
+        return true;
+    const required = Math.max(2, options.minDistinctDomains ?? 2);
+    return new Set(candidates.map((candidate) => candidate.domain ?? safeDomain(candidate.url)).filter(Boolean)).size >= required;
+}
+function compareRepairCandidates(left, right) {
+    return sourceAuthorityScore(right) - sourceAuthorityScore(left)
+        || right.confidence - left.confidence
+        || left.rank - right.rank;
+}
+function sourceAuthorityScore(candidate) {
+    if (candidate.reasons.includes('official-vendor-domain'))
+        return 3;
+    if (candidate.reasons.includes('manufacturer-domain'))
+        return 2;
+    if (candidate.existingSourceId)
+        return 1;
+    return 0;
+}
+function buildSourceAssessments(results, candidates, existingCanonicalUris, options, request) {
     const accepted = new Set(candidates.map((candidate) => canonicalizeUri(candidate.url)));
     const acceptedDomains = new Set(candidates.map((candidate) => candidate.domain ?? safeDomain(candidate.url)).filter(Boolean));
     const minimumConfidence = Math.max(1, Math.min(100, options.minConfidence ?? 70));
-    const tokens = tokenizeSemanticQuery(query);
+    const tokens = tokenizeSemanticQuery([bestSubject(request), inferGapProfileTerms(request)].filter(Boolean).join(' '));
     return results.map((result) => {
-        const assessment = assessGapRepairSource(result, query, request);
+        const assessment = assessGapRepairSource(result, result.searchQuery, request);
         const canonical = canonicalizeUri(result.url);
         const domain = result.domain ?? safeDomain(result.url);
         const isAccepted = Boolean(canonical && accepted.has(canonical));
@@ -237,6 +382,20 @@ function buildSourceAssessments(results, candidates, existingCanonicalUris, opti
         };
     });
 }
+function candidateToAssessment(candidate, accepted) {
+    return {
+        url: candidate.url,
+        ...(candidate.title ? { title: candidate.title } : {}),
+        ...(candidate.domain ? { domain: candidate.domain } : {}),
+        rank: candidate.rank,
+        query: candidate.searchQuery,
+        accepted,
+        confidence: candidate.confidence,
+        reasons: candidate.reasons,
+        trustReason: candidate.reasons.join(', '),
+        ...(accepted ? {} : { rejectionReason: 'not-selected' }),
+    };
+}
 function sourceIdentityHints(request) {
     const subjects = uniqueStrings([
         ...request.linkedObjects.flatMap((node) => [node.title, ...node.aliases]),
@@ -251,9 +410,26 @@ function sourceIdentityHints(request) {
     const manufacturers = uniqueStrings(request.linkedObjects.flatMap((node) => [
         readString(node.metadata.manufacturer),
         readString(node.metadata.vendor),
-    ]).concat(request.sources.flatMap((source) => manufacturerHints(`${source.title ?? ''} ${source.sourceUri ?? ''} ${source.canonicalUri ?? ''}`))));
+    ]).concat(request.sources.flatMap((source) => manufacturerHints(`${source.title ?? ''} ${source.sourceUri ?? ''} ${source.canonicalUri ?? ''}`)))
+        .map((manufacturer) => manufacturer?.trim().toLowerCase())
+        .filter((manufacturer) => Boolean(manufacturer)));
     return { models, manufacturers, subjects };
 }
+function trustedHostsForRepair(request) {
+    const manufacturers = sourceIdentityHints(request).manufacturers;
+    const hosts = [];
+    if (manufacturers.includes('lg'))
+        hosts.push('lg.com', 'www.lg.com');
+    if (manufacturers.includes('sony'))
+        hosts.push('sony.com', 'www.sony.com');
+    if (manufacturers.includes('samsung'))
+        hosts.push('samsung.com', 'www.samsung.com');
+    if (manufacturers.includes('apple'))
+        hosts.push('apple.com', 'support.apple.com');
+    if (manufacturers.includes('espressif') || manufacturers.includes('esp32'))
+        hosts.push('espressif.com', 'docs.espressif.com');
+    return uniqueStrings(hosts);
+}
 function isGenericSubject(value) {
     return /^(tv|television|device|manual|user guide|owner manual|home assistant|service|provider|integration)$/i.test(value.trim());
 }
@@ -264,6 +440,34 @@ function manufacturerHints(value) {
     const hints = value.match(/\b(lg|samsung|sony|vizio|tcl|hisense|philips|panasonic|kasa|tp-link|ecobee|honeywell|ring|arlo|nest|eufy|aqara|sonoff|shelly|lutron|leviton|ikea|bosch|ge|whirlpool|frigidaire|apple|espressif|esp32|nabu casa|home assistant)\b/gi) ?? [];
     return uniqueStrings(hints.map((hint) => hint.toLowerCase()));
 }
+function isGeneratedOrSyntheticSource(source) {
+    return source.tags.includes('generated-page')
+        || source.metadata.projectionKind === 'device-passport'
+        || source.metadata.projectionKind === 'room-page';
+}
+function isOfficialVendorDomain(domain, manufacturers) {
+    const lower = domain.toLowerCase();
+    if (manufacturers.some((manufacturer) => manufacturer === 'lg' && /(^|\.)lg\.com$/.test(lower)))
+        return true;
+    if (manufacturers.some((manufacturer) => manufacturer === 'sony' && /(^|\.)sony\.(com|net)$/.test(lower)))
+        return true;
+    if (manufacturers.some((manufacturer) => manufacturer === 'samsung' && /(^|\.)samsung\.com$/.test(lower)))
+        return true;
+    if (manufacturers.some((manufacturer) => manufacturer === 'apple' && /(^|\.)apple\.com$/.test(lower)))
+        return true;
+    return manufacturers.some((manufacturer) => manufacturer.length >= 4 && lower.includes(manufacturer.toLowerCase()) && /\b(support|docs?|developer|product)\b/.test(lower));
+}
+function isOfficialOrVendorSource(reasons) {
+    return reasons.includes('official-vendor-domain') || reasons.includes('manufacturer-domain');
+}
+function deadlineExceeded(deadlineAt) {
+    return typeof deadlineAt === 'number' && Date.now() >= deadlineAt;
+}
+function operationTimeout(deadlineAt, fallbackMs) {
+    if (typeof deadlineAt !== 'number')
+        return fallbackMs;
+    return Math.min(fallbackMs, Math.max(0, deadlineAt - Date.now()));
+}
 function hasIdentity(searchable, value) {
     const normalized = value.trim().toLowerCase();
     if (!normalized)
@@ -282,19 +486,6 @@ function safeDomain(url) {
         return undefined;
     }
 }
-async function withTimeout(promise, timeoutMs, message) {
-    let timer;
-    const timeout = new Promise((_, reject) => {
-        timer = setTimeout(() => reject(new Error(message)), timeoutMs);
-    });
-    try {
-        return await Promise.race([promise, timeout]);
-    }
-    finally {
-        if (timer)
-            clearTimeout(timer);
-    }
-}
 async function yieldToEventLoop() {
     await new Promise((resolve) => setTimeout(resolve, 0));
 }

package/dist/_internal/platform/knowledge/semantic/self-improvement-tasks.d.ts

@@ -0,0 +1,12 @@
+import type { KnowledgeNodeRecord, KnowledgeRefinementTaskRecord, KnowledgeRefinementTaskState, KnowledgeRefinementTaskTrigger } from '../types.js';
+import type { KnowledgeStore } from '../store.js';
+export interface RefinementTaskGapContext {
+    readonly gap: KnowledgeNodeRecord;
+    readonly sources: readonly {
+        readonly id: string;
+    }[];
+    readonly linkedObjects: readonly KnowledgeNodeRecord[];
+}
+export declare function upsertRefinementTaskForGap(store: KnowledgeStore, spaceId: string, context: RefinementTaskGapContext, trigger: KnowledgeRefinementTaskTrigger, state: KnowledgeRefinementTaskState, message: string, data?: Record<string, unknown>): Promise<KnowledgeRefinementTaskRecord>;
+export declare function updateRefinementTask(store: KnowledgeStore, task: KnowledgeRefinementTaskRecord, state: KnowledgeRefinementTaskState, message: string, data?: Record<string, unknown>): Promise<KnowledgeRefinementTaskRecord>;
+//# sourceMappingURL=self-improvement-tasks.d.ts.map

package/dist/_internal/platform/knowledge/semantic/self-improvement-tasks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"self-improvement-tasks.d.ts","sourceRoot":"","sources":["../../../../../src/_internal/platform/knowledge/semantic/self-improvement-tasks.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,mBAAmB,EACnB,6BAA6B,EAC7B,4BAA4B,EAC5B,8BAA8B,EAC/B,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAGlD,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,GAAG,EAAE,mBAAmB,CAAC;IAClC,QAAQ,CAAC,OAAO,EAAE,SAAS;QAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACrD,QAAQ,CAAC,aAAa,EAAE,SAAS,mBAAmB,EAAE,CAAC;CACxD;AAED,wBAAsB,0BAA0B,CAC9C,KAAK,EAAE,cAAc,EACrB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,wBAAwB,EACjC,OAAO,EAAE,8BAA8B,EACvC,KAAK,EAAE,4BAA4B,EACnC,OAAO,EAAE,MAAM,EACf,IAAI,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACjC,OAAO,CAAC,6BAA6B,CAAC,CAiCxC;AAED,wBAAsB,oBAAoB,CACxC,KAAK,EAAE,cAAc,EACrB,IAAI,EAAE,6BAA6B,EACnC,KAAK,EAAE,4BAA4B,EACnC,OAAO,EAAE,MAAM,EACf,IAAI,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACjC,OAAO,CAAC,6BAA6B,CAAC,CAmBxC"}

package/dist/_internal/platform/knowledge/semantic/self-improvement-tasks.js

@@ -0,0 +1,79 @@
+import { readString, semanticHash, semanticMetadata } from './utils.js';
+export async function upsertRefinementTaskForGap(store, spaceId, context, trigger, state, message, data = {}) {
+    const subject = context.linkedObjects[0];
+    const id = `kref-${semanticHash(spaceId, context.gap.id, subject?.id ?? 'unscoped')}`;
+    const existing = store.getRefinementTask(id);
+    const attemptCount = existing?.attemptCount ?? 0;
+    return store.upsertRefinementTask({
+        id,
+        spaceId,
+        ...(subject ? {
+            subjectKind: 'node',
+            subjectId: subject.id,
+            subjectTitle: subjectTitle(subject),
+            subjectType: subject.kind,
+        } : {}),
+        gapId: context.gap.id,
+        state,
+        trigger,
+        priority: refinementPriority(context.gap),
+        budget: {
+            maxSearches: 5,
+            maxSources: 5,
+            maxLlmCalls: 1,
+        },
+        attemptCount,
+        appendTrace: [trace(state, message, data)],
+        metadata: semanticMetadata(spaceId, {
+            gapTitle: context.gap.title,
+            gapKind: readString(context.gap.metadata.gapKind) ?? 'unknown',
+            sourceIds: context.sources.map((source) => source.id),
+            linkedObjectIds: context.linkedObjects.map((node) => node.id),
+            policyVersion: 'knowledge-refinement-v1',
+        }),
+    });
+}
+export async function updateRefinementTask(store, task, state, message, data = {}) {
+    return store.upsertRefinementTask({
+        id: task.id,
+        spaceId: task.spaceId,
+        subjectKind: task.subjectKind,
+        subjectId: task.subjectId,
+        subjectTitle: task.subjectTitle,
+        subjectType: task.subjectType,
+        gapId: task.gapId,
+        issueId: task.issueId,
+        state,
+        priority: task.priority,
+        trigger: task.trigger,
+        budget: task.budget,
+        attemptCount: state === 'searching' ? task.attemptCount + 1 : task.attemptCount,
+        ...(state === 'blocked' || state === 'failed' ? { blockedReason: message } : {}),
+        appendTrace: [trace(state, message, data)],
+        metadata: task.metadata,
+    });
+}
+function trace(state, message, data = {}) {
+    return {
+        at: Date.now(),
+        state,
+        message,
+        ...(Object.keys(data).length > 0 ? { data } : {}),
+    };
+}
+function refinementPriority(gap) {
+    const severity = readString(gap.metadata.severity);
+    const kind = readString(gap.metadata.gapKind);
+    if (severity === 'error')
+        return 'urgent';
+    if (severity === 'warning' || kind === 'intrinsic_features')
+        return 'high';
+    return 'normal';
+}
+function subjectTitle(subject) {
+    return [
+        readString(subject.metadata.manufacturer),
+        readString(subject.metadata.model),
+        subject.title,
+    ].filter(Boolean).join(' ');
+}

package/dist/_internal/platform/knowledge/semantic/self-improvement.d.ts

@@ -4,6 +4,10 @@ interface SelfImproveContext {
     readonly store: KnowledgeStore;
     readonly gapRepairer?: KnowledgeSemanticGapRepairer | null;
     readonly activeGapRepairs: Set<string>;
+    readonly enrichSource?: (sourceId: string, options: {
+        readonly force?: boolean;
+        readonly knowledgeSpaceId?: string;
+    }) => Promise<unknown>;
 }
 export declare function runKnowledgeSemanticSelfImprovement(context: SelfImproveContext, input?: KnowledgeSemanticSelfImproveInput): Promise<KnowledgeSemanticSelfImproveResult>;
 export {};

package/dist/_internal/platform/knowledge/semantic/self-improvement.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"self-improvement.d.ts","sourceRoot":"","sources":["../../../../../src/_internal/platform/knowledge/semantic/self-improvement.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAUlD,OAAO,KAAK,EACV,4BAA4B,EAC5B,iCAAiC,EACjC,kCAAkC,EACnC,MAAM,YAAY,CAAC;AAkBpB,UAAU,kBAAkB;IAC1B,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC;IAC/B,QAAQ,CAAC,WAAW,CAAC,EAAE,4BAA4B,GAAG,IAAI,CAAC;IAC3D,QAAQ,CAAC,gBAAgB,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CACxC;AAUD,wBAAsB,mCAAmC,CACvD,OAAO,EAAE,kBAAkB,EAC3B,KAAK,GAAE,iCAAsC,GAC5C,OAAO,CAAC,kCAAkC,CAAC,CAmL7C"}
+{"version":3,"file":"self-improvement.d.ts","sourceRoot":"","sources":["../../../../../src/_internal/platform/knowledge/semantic/self-improvement.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAQlD,OAAO,KAAK,EACV,4BAA4B,EAC5B,iCAAiC,EACjC,kCAAkC,EACnC,MAAM,YAAY,CAAC;AAYpB,UAAU,kBAAkB;IAC1B,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC;IAC/B,QAAQ,CAAC,WAAW,CAAC,EAAE,4BAA4B,GAAG,IAAI,CAAC;IAC3D,QAAQ,CAAC,gBAAgB,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACvC,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE;QAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CAC3I;AAUD,wBAAsB,mCAAmC,CACvD,OAAO,EAAE,kBAAkB,EAC3B,KAAK,GAAE,iCAAsC,GAC5C,OAAO,CAAC,kCAAkC,CAAC,CA0N7C"}