@pellux/goodvibes-sdk 0.28.22 → 0.30.1

package/dist/platform/knowledge/semantic/answer-fallback.js

@@ -0,0 +1,204 @@
+import { isLowValueFeatureOrSpecText } from './fact-quality.js';
+import { clampText, normalizeWhitespace, readString } from './utils.js';
+const DEFAULT_ANSWER_FALLBACK_POLICY = {
+    renderInsufficientFacts: ({ query, sourceTitles }) => ({
+        synthesized: false,
+        text: `I found matching sources (${joinFactPhrases(sourceTitles)}), but they have not produced enough source-backed facts to answer "${query}" yet.`,
+    }),
+    renderNoMatch: (query) => ({
+        synthesized: false,
+        text: `No knowledge matched "${query}".`,
+    }),
+};
+export function renderFallbackAnswer(query, mode, evidence, facts, policy = DEFAULT_ANSWER_FALLBACK_POLICY) {
+    const renderInsufficientFacts = policy.renderInsufficientFacts ?? DEFAULT_ANSWER_FALLBACK_POLICY.renderInsufficientFacts;
+    const renderNoMatch = policy.renderNoMatch ?? DEFAULT_ANSWER_FALLBACK_POLICY.renderNoMatch;
+    const factLimit = mode === 'detailed' ? 12 : mode === 'concise' ? 3 : 8;
+    const factPhrases = facts.slice(0, factLimit).map(renderFactPhrase).filter(Boolean);
+    const profile = renderFeatureProfile(query, facts, evidence);
+    if (profile) {
+        return {
+            synthesized: true,
+            text: profile,
+        };
+    }
+    if (factPhrases.length > 0) {
+        return {
+            synthesized: true,
+            text: `${joinFactPhrases(factPhrases)}.`,
+        };
+    }
+    const sourceTitles = evidence
+        .slice(0, mode === 'detailed' ? 6 : mode === 'concise' ? 2 : 4)
+        .map((item) => normalizeWhitespace(item.title))
+        .filter(Boolean);
+    if (sourceTitles.length > 0) {
+        return renderInsufficientFacts({ query, sourceTitles });
+    }
+    return renderNoMatch(query);
+}
+function renderFactPhrase(fact) {
+    const value = readString(fact.metadata.value);
+    const summary = fact.summary ?? readString(fact.metadata.evidence);
+    const phrase = value ? `${fact.title}: ${value}` : summary ? `${fact.title}: ${summary}` : fact.title;
+    const cleaned = normalizeWhitespace(clampText(phrase, 220));
+    if (isRawSourceFragment(cleaned))
+        return '';
+    return isLowValueFeatureOrSpecText(cleaned) ? '' : cleaned;
+}
+function renderFeatureProfile(query, facts, evidence) {
+    if (!/\b(feature|features|capabilit|spec|specs|specification|specifications|support|supports)\b/i.test(query))
+        return null;
+    const phrases = collectProfilePhrases(facts, evidence);
+    const combined = phrases.join(' ');
+    const details = {
+        display: featureProfileTerms(combined, 'display').slice(0, 8),
+        smart: featureProfileTerms(combined, 'smart').slice(0, 5),
+        connectivity: featureProfileTerms(combined, 'connectivity').slice(0, 6),
+        audio: featureProfileTerms(combined, 'audio').slice(0, 5),
+        gaming: featureProfileTerms(combined, 'gaming').slice(0, 5),
+    };
+    const sentences = [];
+    if (details.display.length > 0)
+        sentences.push(`Display: ${joinFactPhrases(details.display)}.`);
+    if (details.smart.length > 0)
+        sentences.push(`Smart TV features: ${joinFactPhrases(details.smart)}.`);
+    if (details.connectivity.length > 0)
+        sentences.push(`Connectivity and ports: ${joinFactPhrases(details.connectivity)}.`);
+    if (details.audio.length > 0)
+        sentences.push(`Audio: ${joinFactPhrases(details.audio)}.`);
+    if (details.gaming.length > 0)
+        sentences.push(`Gaming-related capabilities: ${joinFactPhrases(details.gaming)}.`);
+    if (sentences.length >= 2)
+        return sentences.join(' ');
+    if (sentences.length === 1 && hasSpecificFeatureProfileIntent(query))
+        return sentences[0] ?? null;
+    return null;
+}
+function collectProfilePhrases(facts, evidence) {
+    const phrases = [];
+    for (const fact of facts) {
+        const phrase = renderFactPhrase(fact);
+        if (phrase)
+            phrases.push(phrase);
+    }
+    for (const item of evidence) {
+        const excerpt = readEvidenceExcerpt(item);
+        if (excerpt)
+            phrases.push(excerpt);
+        const title = readEvidenceTitle(item);
+        if (title)
+            phrases.push(title);
+    }
+    return uniqueCaseInsensitive(phrases);
+}
+function readEvidenceTitle(item) {
+    const raw = normalizeWhitespace(item.title ?? '');
+    if (!raw || !hasConcreteFeatureText(raw))
+        return '';
+    const cleaned = normalizeWhitespace(clampText(stripSourceAddressFragments(raw), 220));
+    if (isRawSourceFragment(cleaned))
+        return '';
+    return isLowValueFeatureOrSpecText(cleaned) ? '' : cleaned;
+}
+function readEvidenceExcerpt(item) {
+    const raw = normalizeWhitespace(item.excerpt ?? '');
+    if (!raw)
+        return '';
+    const cleaned = normalizeWhitespace(clampText(stripSourceAddressFragments(raw), 260));
+    if (isRawSourceFragment(cleaned))
+        return '';
+    return isLowValueFeatureOrSpecText(cleaned) ? '' : cleaned;
+}
+function hasConcreteFeatureText(value) {
+    return /\b(hdmi|usb|hdr|hdr10|dolby|vision|earc|arc|bluetooth|wi-?fi|ethernet|voice|remote|game|filmmaker|nanocell|nano\s*cell|4k|uhd|resolution|refresh|ports?|speakers?|audio|display|screen|webos|atsc|ntsc|qam|tuner)\b/i.test(value);
+}
+function featureProfileTerms(value, category) {
+    const termMap = {
+        display: [
+            ['screen size/class', /\b\d{2,3}(?:\.0)?\s*(?:inch|inches|in\.|")\b/i],
+            ['4K UHD resolution', /\b4k\b|\buhd\b|\b3840\s*(?:x|×)\s*2160\b/i],
+            ['NanoCell display', /\bnano\s*cell\b|\bnanocell\b/i],
+            ['display panel technology', /\boled\b|\bqled\b|\bmini[- ]?led\b|\bled\b|\blcd\b/i],
+            ['LCD/LED display', /\blcd\b|\bled\b/i],
+            ['100/120 Hz refresh rate', /\b(?:100|120)\s*hz\b|\btrumotion\s*240\b/i],
+            ['HDR10', /\bhdr10\b/i],
+            ['Dolby Vision', /\bdolby vision\b/i],
+            ['HLG', /\bhlg\b/i],
+            ['Filmmaker Mode', /\bfilmmaker mode\b/i],
+        ],
+        smart: [
+            ['webOS smart TV platform', /\bwebos\b/i],
+            ['vendor smart-home integration', /\bsmartthings\b|\bhomekit\b|\bgoogle home\b|\balexa\b/i],
+            ['Apple AirPlay 2', /\bairplay\s*2?\b/i],
+            ['Apple HomeKit', /\bhomekit\b/i],
+            ['voice assistant support', /\bvoice\b|\balexa\b|\bgoogle assistant\b/i],
+            ['streaming app support', /\bapps?\b|\bstreaming\b/i],
+        ],
+        connectivity: [
+            ['HDMI inputs', /\bhdmi\b/i],
+            ['HDMI ARC/eARC', /\bearc\b|\barc\b/i],
+            ['USB ports', /\busb\b/i],
+            ['Ethernet/LAN', /\bethernet\b|\blan\b|\brj-?45\b/i],
+            ['Wi-Fi/wireless LAN', /\bwi-?fi\b|\bwireless lan\b/i],
+            ['Bluetooth', /\bbluetooth\b/i],
+            ['Optical audio output', /\boptical\b|\btoslink\b/i],
+            ['RF/antenna input', /\brf\b|\bantenna\b/i],
+            ['ATSC/Clear QAM tuner support', /\batsc\b|\bclear qam\b|\bqam\b|\btuner\b/i],
+            ['RS-232C/external control', /\brs-?232c?\b|\bexternal control\b/i],
+        ],
+        audio: [
+            ['speaker/audio output', /\bspeakers?\b|\b(?:10|20|40)\s*w\b|\b2(?:\.0)?\s*ch\b/i],
+            ['Dolby audio formats', /\bdolby atmos\b|\bdolby digital\b|\bdolby audio\b|\btruehd\b|\bpcm\b/i],
+            ['HDMI ARC/eARC audio', /\bearc\b|\barc\b/i],
+        ],
+        gaming: [
+            ['FreeSync/VRR support', /\bfreesync\b|\bvrr\b/i],
+            ['ALLM/low-latency support', /\ballm\b|\blow latency\b/i],
+            ['Game Optimizer/game mode', /\bgame optimizer\b|\bgame mode\b|\bgaming\b/i],
+            ['4K/120 Hz or high-bandwidth HDMI', /\bhdmi\s*2\.1\b|\b4k\s*(?:at|@)?\s*120\b|\b120\s*hz\b/i],
+        ],
+    };
+    return termMap[category]
+        .filter(([, pattern]) => pattern.test(value))
+        .map(([label]) => label);
+}
+function uniqueCaseInsensitive(values) {
+    const seen = new Set();
+    const out = [];
+    for (const value of values) {
+        const key = value.toLowerCase();
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(value);
+    }
+    return out;
+}
+function hasSpecificFeatureProfileIntent(query) {
+    return /\b(hdr|display|screen|refresh|ports?|hdmi|earc|arc|usb|ethernet|optical|rf|antenna|rs-?232c?|audio|speaker|wireless|wi-?fi|bluetooth|gaming|vrr|allm|freesync|smart|webos|tuner|atsc|qam|dolby vision|hlg)\b/i.test(query);
+}
+function isRawSourceFragment(value) {
+    const lower = value.toLowerCase();
+    return /\bsemantic-gap-repair\b/.test(lower)
+        || /\bsource-backed facts identify\b/.test(lower)
+        || /\b(manual\.nz|current page|loading)\b/.test(lower)
+        || /\b[a-z0-9-]+\.(com|net|org|io|dev|tv|ca)\/[a-z0-9/_?=&.#-]+/.test(lower)
+        || /\b[a-z]{2}\/[a-z0-9/_-]+\/[a-z0-9._-]+/.test(lower);
+}
+function stripSourceAddressFragments(value) {
+    return value
+        .replace(/homegraph:\/\/\S+/gi, ' ')
+        .replace(/https?:\/\/\S+/gi, ' ')
+        .replace(/\bsemantic-gap-repair\b/gi, ' ')
+        .replace(/\bgenerated-page\b/gi, ' ')
+        .replace(/\b(?:www\.)?[a-z0-9-]+\.(?:com|net|org|io|dev|tv|ca|co\.uk)(?:\/\S*)?/gi, ' ')
+        .replace(/\b(?:com|net|org|io|dev|tv|ca|co\.uk)\/\S+/gi, ' ');
+}
+function joinFactPhrases(phrases) {
+    if (phrases.length <= 1)
+        return phrases[0] ?? '';
+    if (phrases.length === 2)
+        return `${phrases[0]} and ${phrases[1]}`;
+    return `${phrases.slice(0, -1).join('; ')}; and ${phrases[phrases.length - 1]}`;
+}

package/dist/platform/knowledge/semantic/answer-gaps.d.ts

@@ -0,0 +1,15 @@
+import type { KnowledgeStore } from '../store.js';
+import type { KnowledgeNodeRecord, KnowledgeSourceRecord } from '../types.js';
+import type { KnowledgeSemanticGapInput } from './types.js';
+export declare function shouldPersistNoMatchGap(spaceId: string, query: string, linkedObjects: readonly KnowledgeNodeRecord[]): boolean;
+export declare function persistAnswerGap(store: KnowledgeStore, spaceId: string, query: string, reason: string, context?: {
+    readonly subject?: string;
+    readonly sources?: readonly KnowledgeSourceRecord[];
+    readonly linkedObjects?: readonly KnowledgeNodeRecord[];
+}): Promise<KnowledgeNodeRecord>;
+export declare function persistAnswerGaps(store: KnowledgeStore, spaceId: string, query: string, gaps: readonly KnowledgeSemanticGapInput[], context?: {
+    readonly sources?: readonly KnowledgeSourceRecord[];
+    readonly linkedObjects?: readonly KnowledgeNodeRecord[];
+}): Promise<readonly KnowledgeNodeRecord[]>;
+export declare function isRepairedAnswerGap(node: KnowledgeNodeRecord): boolean;
+//# sourceMappingURL=answer-gaps.d.ts.map

package/dist/platform/knowledge/semantic/answer-gaps.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"answer-gaps.d.ts","sourceRoot":"","sources":["../../../../src/platform/knowledge/semantic/answer-gaps.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,KAAK,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAC9E,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,YAAY,CAAC;AAgB5D,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,EACb,aAAa,EAAE,SAAS,mBAAmB,EAAE,GAC5C,OAAO,CAKT;AAED,wBAAsB,gBAAgB,CACpC,KAAK,EAAE,cAAc,EACrB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,OAAO,GAAE;IACP,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,qBAAqB,EAAE,CAAC;IACpD,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,mBAAmB,EAAE,CAAC;CACpD,GACL,OAAO,CAAC,mBAAmB,CAAC,CA2E9B;AAED,wBAAsB,iBAAiB,CACrC,KAAK,EAAE,cAAc,EACrB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,SAAS,yBAAyB,EAAE,EAC1C,OAAO,GAAE;IACP,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,qBAAqB,EAAE,CAAC;IACpD,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,mBAAmB,EAAE,CAAC;CACpD,GACL,OAAO,CAAC,SAAS,mBAAmB,EAAE,CAAC,CAUzC;AAED,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAKtE"}

package/dist/platform/knowledge/semantic/answer-gaps.js

@@ -0,0 +1,144 @@
+import { normalizeWhitespace, readString, readStringArray, semanticHash, semanticMetadata, tokenizeSemanticQuery, uniqueStrings, } from './utils.js';
+import { GENERIC_ANSWER_INTENT_TOKENS, isBroadKnowledgeSpaceAlias, } from './answer-common.js';
+import { hasAny } from './answer-fact-selection.js';
+export function shouldPersistNoMatchGap(spaceId, query, linkedObjects) {
+    if (linkedObjects.length > 0)
+        return true;
+    if (!isBroadKnowledgeSpaceAlias(spaceId))
+        return true;
+    const subjectTokens = tokenizeSemanticQuery(query).filter((token) => !GENERIC_ANSWER_INTENT_TOKENS.has(token));
+    return subjectTokens.length > 0;
+}
+export async function persistAnswerGap(store, spaceId, query, reason, context = {}) {
+    const linkedObjects = context.linkedObjects ?? [];
+    const sources = context.sources ?? [];
+    const subject = context.subject ?? linkedObjects[0]?.title;
+    const fingerprint = answerGapFingerprint(spaceId, query, subject, linkedObjects[0]?.id);
+    const id = `sem-answer-gap-${fingerprint}`;
+    const existing = store.getNode(id);
+    const node = await store.upsertNode({
+        id,
+        kind: 'knowledge_gap',
+        slug: `answer-gap-${fingerprint}`,
+        title: query,
+        summary: reason,
+        confidence: 70,
+        ...(sources[0] ? { sourceId: sources[0].id } : {}),
+        metadata: semanticMetadata(spaceId, {
+            semanticKind: 'gap',
+            gapKind: 'answer',
+            query,
+            reason,
+            subject,
+            subjectFingerprint: fingerprint,
+            sourceIds: sources.map((source) => source.id),
+            linkedObjectIds: linkedObjects.map((node) => node.id),
+            repairStatus: readString(existing?.metadata.repairStatus) ?? 'open',
+            ...((readStringArray(existing?.metadata.acceptedSourceIds).length > 0) ? { acceptedSourceIds: readStringArray(existing?.metadata.acceptedSourceIds) } : {}),
+            ...(typeof existing?.metadata.promotedFactCount === 'number' ? { promotedFactCount: existing.metadata.promotedFactCount } : {}),
+            ...(typeof existing?.metadata.nextRepairAttemptAt === 'number' ? { nextRepairAttemptAt: existing.metadata.nextRepairAttemptAt } : {}),
+            visibility: 'refinement',
+            displayRole: 'knowledge-gap',
+        }),
+    });
+    for (const source of sources) {
+        await store.upsertEdge({
+            fromKind: 'source',
+            fromId: source.id,
+            toKind: 'node',
+            toId: node.id,
+            relation: 'has_gap',
+            metadata: semanticMetadata(spaceId, { gapKind: 'answer' }),
+        });
+    }
+    for (const object of linkedObjects) {
+        await store.upsertEdge({
+            fromKind: 'node',
+            fromId: object.id,
+            toKind: 'node',
+            toId: node.id,
+            relation: 'has_gap',
+            metadata: semanticMetadata(spaceId, { gapKind: 'answer' }),
+        });
+    }
+    if (!isRepairedAnswerGap(node)) {
+        await store.upsertIssue({
+            id: `sem-answer-gap-issue-${fingerprint}`,
+            severity: 'info',
+            code: 'knowledge.answer_gap',
+            message: `No knowledge answer available for: ${query}`,
+            status: 'open',
+            ...(sources[0] ? { sourceId: sources[0].id } : {}),
+            nodeId: node.id,
+            metadata: semanticMetadata(spaceId, {
+                namespace: `knowledge:${spaceId}:answers`,
+                query,
+                reason,
+                subject,
+                subjectFingerprint: fingerprint,
+                sourceIds: sources.map((source) => source.id),
+                linkedObjectIds: linkedObjects.map((entry) => entry.id),
+            }),
+        });
+    }
+    else {
+        await resolveAnswerGapIssues(store, spaceId, node.id);
+    }
+    return node;
+}
+export async function persistAnswerGaps(store, spaceId, query, gaps, context = {}) {
+    const nodes = [];
+    for (const gap of gaps.slice(0, 8)) {
+        const node = await persistAnswerGap(store, spaceId, gap.question || query, gap.reason ?? 'Answer synthesis identified a missing knowledge gap.', {
+            ...context,
+            ...(gap.subject ? { subject: gap.subject } : {}),
+        });
+        if (!isRepairedAnswerGap(node))
+            nodes.push(node);
+    }
+    return nodes;
+}
+export function isRepairedAnswerGap(node) {
+    const repairStatus = readString(node.metadata.repairStatus);
+    return node.status === 'stale'
+        || repairStatus === 'not_applicable'
+        || (repairStatus === 'repaired' && typeof node.metadata.promotedFactCount === 'number' && node.metadata.promotedFactCount > 0);
+}
+async function resolveAnswerGapIssues(store, spaceId, nodeId) {
+    for (const issue of store.listIssues(Number.MAX_SAFE_INTEGER).filter((entry) => entry.nodeId === nodeId && entry.status === 'open')) {
+        await store.upsertIssue({
+            id: issue.id,
+            severity: issue.severity,
+            code: issue.code,
+            message: issue.message,
+            status: 'resolved',
+            sourceId: issue.sourceId,
+            nodeId: issue.nodeId,
+            metadata: semanticMetadata(spaceId, {
+                ...issue.metadata,
+                resolution: {
+                    reason: 'Answer gap already has accepted repair evidence.',
+                    resolvedBy: 'knowledge-answer',
+                    resolvedAt: Date.now(),
+                },
+            }),
+        });
+    }
+}
+function answerGapFingerprint(spaceId, query, subject, subjectId) {
+    return semanticHash(spaceId, subjectId ?? normalizeGapSubject(subject), answerGapIntent(query));
+}
+function normalizeGapSubject(subject) {
+    return normalizeWhitespace(subject ?? 'unscoped').toLowerCase().replace(/[^a-z0-9._:-]+/g, '-').replace(/^-+|-+$/g, '') || 'unscoped';
+}
+function answerGapIntent(query) {
+    const tokens = new Set(tokenizeSemanticQuery(query));
+    if (hasAny(tokens, ['feature', 'features', 'capability', 'capabilities', 'function', 'functions', 'spec', 'specs', 'specification', 'specifications'])) {
+        return 'features-specifications';
+    }
+    if (hasAny(tokens, ['battery', 'batteries']))
+        return 'battery';
+    if (hasAny(tokens, ['manual', 'documentation', 'source', 'sources']))
+        return 'source-documentation';
+    return uniqueStrings([...tokens].filter((token) => !GENERIC_ANSWER_INTENT_TOKENS.has(token)).sort()).slice(0, 8).join('-') || 'general';
+}

package/dist/platform/knowledge/semantic/answer-quality.d.ts

@@ -0,0 +1,13 @@
+import type { KnowledgeNodeRecord, KnowledgeSourceRecord } from '../types.js';
+export interface CleanSynthesizedAnswerOptions {
+    readonly fallbackText?: string;
+}
+export declare function answerNeedsFeatureGap(input: {
+    readonly query: string;
+    readonly text?: string;
+    readonly facts: readonly KnowledgeNodeRecord[];
+    readonly sources: readonly KnowledgeSourceRecord[];
+    readonly linkedObjects: readonly KnowledgeNodeRecord[];
+}): boolean;
+export declare function cleanSynthesizedAnswer(text: string, featureIntent: boolean, options?: CleanSynthesizedAnswerOptions): string;
+//# sourceMappingURL=answer-quality.d.ts.map

package/dist/platform/knowledge/semantic/answer-quality.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"answer-quality.d.ts","sourceRoot":"","sources":["../../../../src/platform/knowledge/semantic/answer-quality.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAI9E,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AAED,wBAAgB,qBAAqB,CAAC,KAAK,EAAE;IAC3C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,SAAS,mBAAmB,EAAE,CAAC;IAC/C,QAAQ,CAAC,OAAO,EAAE,SAAS,qBAAqB,EAAE,CAAC;IACnD,QAAQ,CAAC,aAAa,EAAE,SAAS,mBAAmB,EAAE,CAAC;CACxD,GAAG,OAAO,CAoBV;AAED,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,MAAM,EACZ,aAAa,EAAE,OAAO,EACtB,OAAO,GAAE,6BAAkC,GAC1C,MAAM,CAiBR"}

package/dist/platform/knowledge/semantic/answer-quality.js

@@ -0,0 +1,83 @@
+import { hasConcreteFeatureSignal, isLowValueFeatureOrSpecText, semanticFactText } from './fact-quality.js';
+import { readStringArray, splitSentences } from './utils.js';
+export function answerNeedsFeatureGap(input) {
+    if (input.linkedObjects.length === 0)
+        return false;
+    const linkedObjectIds = new Set(input.linkedObjects.map((node) => node.id));
+    const concreteFactCount = input.facts.filter((fact) => {
+        const text = semanticFactText(fact);
+        return factLinksToAnswerObject(fact, linkedObjectIds)
+            && hasConcreteFeatureSignal(text)
+            && !isLowValueFeatureOrSpecText(text);
+    }).length;
+    if (concreteFactCount >= 3)
+        return false;
+    const broadQuery = hasBroadFeatureQueryIntent(input.query);
+    if (!broadQuery && concreteFactCount >= 2 && input.text && hasEnoughAnswerSignal(input.query, input.text))
+        return false;
+    const sourceText = input.sources.map((source) => `${source.title} ${source.summary ?? ''} ${source.tags.join(' ')}`).join('\n');
+    const answerText = `${input.text ?? ''}\n${sourceText}`;
+    if (!broadQuery
+        && /manual|specification|product|datasheet|support|source-backed|official-vendor-domain|manufacturer-domain/i.test(answerText)
+        && concreteFactCount >= 2) {
+        return false;
+    }
+    return true;
+}
+export function cleanSynthesizedAnswer(text, featureIntent, options = {}) {
+    if (!featureIntent)
+        return text;
+    const blocks = text.split(/\n{2,}/).map((block) => block.trim()).filter(Boolean);
+    const cleanedBlocks = blocks.map((block) => {
+        const lines = block.split(/\n/).map((line) => line.trim()).filter(Boolean);
+        const kept = lines.filter((line) => !isLowValueFeatureOrSpecText(line));
+        if (kept.length > 0 && kept.length < lines.length)
+            return kept.join('\n');
+        if (lines.length > 1)
+            return kept.join('\n');
+        const sentences = splitSentences(block, 600);
+        const keptSentences = sentences.filter((sentence) => !isLowValueFeatureOrSpecText(sentence));
+        return keptSentences.length > 0 && keptSentences.length < sentences.length
+            ? keptSentences.join(' ')
+            : block;
+    }).filter(Boolean);
+    return cleanedBlocks.length > 0
+        ? cleanedBlocks.join('\n\n')
+        : options.fallbackText ?? '';
+}
+function factLinksToAnswerObject(fact, linkedObjectIds) {
+    if (linkedObjectIds.size === 0)
+        return true;
+    const ids = [
+        ...readStringArray(fact.metadata.linkedObjectIds),
+        ...readStringArray(fact.metadata.subjectIds),
+    ];
+    return ids.some((id) => linkedObjectIds.has(id));
+}
+function hasEnoughAnswerSignal(query, text) {
+    if (isLowValueFeatureOrSpecText(text) || !hasConcreteFeatureSignal(text))
+        return false;
+    const broadQuery = hasBroadFeatureQueryIntent(query);
+    if (broadQuery)
+        return featureSignalFamilyCount(text) >= 3;
+    return queryFeatureTerms(query).some((term) => text.toLowerCase().includes(term));
+}
+function hasBroadFeatureQueryIntent(query) {
+    return /\b(features?|specs?|specifications?|capabilities|what can|what does .* have)\b/i.test(query);
+}
+function queryFeatureTerms(query) {
+    return Array.from(query.toLowerCase().matchAll(/\b(hdmi(?:\s*2\.1)?|usb|hdr10?|dolby vision|dolby|earc|arc|bluetooth|wi-?fi|ethernet|remote|refresh|120\s*hz|60\s*hz|ports?|speakers?|audio|apps?|airplay|homekit|tuner|atsc|qam|gaming|game|vrr|allm)\b/g)).map((match) => match[1].replace(/\s+/g, ' '));
+}
+function featureSignalFamilyCount(text) {
+    const lower = text.toLowerCase();
+    return [
+        /\b(hdmi|earc|arc|ports?|usb|ethernet)\b/,
+        /\b(hdr|hdr10|dolby vision|hlg|filmmaker)\b/,
+        /\b(4k|8k|uhd|resolution|refresh|120\s*hz|60\s*hz|display|screen|panel)\b/,
+        /\b(webos|apps?|streaming|airplay|homekit|chromecast|smart tv)\b/,
+        /\b(wi-?fi|bluetooth|wireless lan)\b/,
+        /\b(audio|speakers?|dolby atmos|sound)\b/,
+        /\b(game|gaming|vrr|allm|freesync|g-sync)\b/,
+        /\b(tuner|atsc|qam|ntsc|broadcast)\b/,
+    ].filter((pattern) => pattern.test(lower)).length;
+}

package/dist/platform/knowledge/semantic/answer-source-ranking.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"answer-source-ranking.d.ts","sourceRoot":"","sources":["../../../../src/platform/knowledge/semantic/answer-source-ranking.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAI9E,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,qBAAqB,CAAC;CACzC;AAED,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,SAAS,2BAA2B,EAAE,EAChD,KAAK,EAAE,SAAS,mBAAmB,EAAE,GACpC,qBAAqB,EAAE,CAwBzB;AAmBD,wBAAgB,6BAA6B,CAAC,MAAM,EAAE,qBAAqB,GAAG,MAAM,CAgBnF"}

package/dist/platform/knowledge/semantic/answer-source-ranking.js

@@ -0,0 +1,73 @@
+import { isGeneratedKnowledgeSource } from '../generated-projections.js';
+import { readRecord, readString } from './utils.js';
+export function rankAnswerSources(evidence, facts) {
+    const evidenceScoreBySource = new Map();
+    for (const item of evidence) {
+        if (!item.source)
+            continue;
+        evidenceScoreBySource.set(item.source.id, Math.max(evidenceScoreBySource.get(item.source.id) ?? 0, item.score));
+    }
+    const factCountBySource = new Map();
+    const promotedFactCountBySource = new Map();
+    for (const fact of facts) {
+        const sourceId = readString(fact.metadata.sourceId) ?? fact.sourceId;
+        if (!sourceId)
+            continue;
+        factCountBySource.set(sourceId, (factCountBySource.get(sourceId) ?? 0) + 1);
+        if (readString(fact.metadata.extractor) === 'repair-promotion') {
+            promotedFactCountBySource.set(sourceId, (promotedFactCountBySource.get(sourceId) ?? 0) + 1);
+        }
+    }
+    const sources = uniqueSources(evidence.flatMap((item) => item.source ? [item.source] : []));
+    const realSources = sources.filter((source) => !isGeneratedKnowledgeSource(source));
+    return (realSources.length > 0 ? realSources : sources)
+        .sort((left, right) => (sourceAnswerQuality(right, evidenceScoreBySource, factCountBySource, promotedFactCountBySource)
+        - sourceAnswerQuality(left, evidenceScoreBySource, factCountBySource, promotedFactCountBySource)
+        || left.id.localeCompare(right.id)));
+}
+function sourceAnswerQuality(source, evidenceScoreBySource, factCountBySource, promotedFactCountBySource) {
+    const discovery = readRecord(source.metadata.sourceDiscovery);
+    const rank = typeof discovery.sourceRank === 'number' ? Math.max(0, 12 - discovery.sourceRank) : 0;
+    return Math.round((evidenceScoreBySource.get(source.id) ?? 0) / 4)
+        + sourceAuthorityBoostForAnswer(source)
+        + Math.min(80, (factCountBySource.get(source.id) ?? 0) * 10)
+        + Math.min(90, (promotedFactCountBySource.get(source.id) ?? 0) * 18)
+        + rank * 4
+        + (source.status === 'indexed' ? 12 : source.status === 'pending' ? 2 : 0)
+        - (isGeneratedKnowledgeSource(source) ? 90 : 0);
+}
+export function sourceAuthorityBoostForAnswer(source) {
+    const discovery = readRecord(source.metadata.sourceDiscovery);
+    const text = [
+        readString(discovery.trustReason),
+        readString(discovery.sourceDomain),
+        source.title,
+        source.summary,
+        source.description,
+        source.url,
+        source.sourceUri,
+        source.canonicalUri,
+    ].filter(Boolean).join(' ').toLowerCase();
+    if (/\bofficial-vendor-domain\b/.test(text))
+        return 140;
+    if (/\bofficial\b/.test(text) && /\b(support|specifications?|manual|product|docs?|datasheet)\b/.test(text) && !isCommercialLowValueSourceText(text))
+        return 120;
+    if (/\bmanufacturer-domain\b/.test(text))
+        return 80;
+    return 0;
+}
+function isCommercialLowValueSourceText(text) {
+    return /\b(shopping|shop now|affiliate|associate program|buy now|add to cart|price comparison|marketplace|retailer|store listing|seller listing|sponsored listing|latest price|compare prices)\b/.test(text)
+        || /(^|\.)amazon\.[a-z.]+\b|(^|\.)ebay\.[a-z.]+\b|(^|\.)walmart\.[a-z.]+\b|(^|\.)bestbuy\.[a-z.]+\b|(^|\.)target\.[a-z.]+\b/.test(text);
+}
+function uniqueSources(values) {
+    const seen = new Set();
+    const result = [];
+    for (const source of values) {
+        if (seen.has(source.id))
+            continue;
+        seen.add(source.id);
+        result.push(source);
+    }
+    return result;
+}

package/dist/platform/knowledge/semantic/answer-space.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"answer-space.d.ts","sourceRoot":"","sources":["../../../../src/platform/knowledge/semantic/answer-space.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAE9E,UAAU,oBAAoB;IAC5B,QAAQ,CAAC,IAAI,CAAC,EAAE,mBAAmB,CAAC;IACpC,QAAQ,CAAC,MAAM,CAAC,EAAE,qBAAqB,CAAC;CACzC;AAED,wBAAgB,wBAAwB,CACtC,gBAAgB,EAAE,MAAM,EACxB,QAAQ,EAAE,SAAS,oBAAoB,EAAE,EACzC,OAAO,EAAE,SAAS,qBAAqB,EAAE,EACzC,aAAa,EAAE,SAAS,mBAAmB,EAAE,GAC5C,MAAM,CAWR"}

package/dist/platform/knowledge/semantic/answer.d.ts

@@ -0,0 +1,4 @@
+import type { KnowledgeSemanticAnswerInput, KnowledgeSemanticAnswerResult } from './types.js';
+import { type KnowledgeAnswerContext } from './answer-common.js';
+export declare function answerKnowledgeQuery(context: KnowledgeAnswerContext, input: KnowledgeSemanticAnswerInput): Promise<KnowledgeSemanticAnswerResult>;
+//# sourceMappingURL=answer.d.ts.map

package/dist/platform/knowledge/semantic/answer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"answer.d.ts","sourceRoot":"","sources":["../../../../src/platform/knowledge/semantic/answer.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,4BAA4B,EAC5B,6BAA6B,EAI9B,MAAM,YAAY,CAAC;AAmBpB,OAAO,EAGL,KAAK,sBAAsB,EAC5B,MAAM,oBAAoB,CAAC;AAwB5B,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,sBAAsB,EAC/B,KAAK,EAAE,4BAA4B,GAClC,OAAO,CAAC,6BAA6B,CAAC,CAiIxC"}