@pellux/goodvibes-sdk 0.30.3 → 0.33.1

package/dist/platform/knowledge/home-graph/generated-pages.js

@@ -1,11 +1,12 @@
 import { GoodVibesSdkError } from '@pellux/goodvibes-errors';
 import { materializeGeneratedKnowledgeProjection, } from '../generated-projections.js';
 import { yieldEvery, yieldToEventLoop } from '../cooperative.js';
-import { HOME_GRAPH_CONNECTOR_ID, buildHomeGraphMetadata, edgeIsActive, homeGraphNodeId, homeGraphSourceId, isGeneratedPageSource, namespacedCanonicalUri, readStringArray, readHomeAssistantMetadataString, readRecord, uniqueStrings, } from './helpers.js';
+import { HOME_GRAPH_CONNECTOR_ID, buildHomeGraphMetadata, edgeIsActive, factSourceIds, homeGraphNodeId, homeGraphSourceId, isGeneratedPageSource, namespacedCanonicalUri, readStringArray, readHomeAssistantMetadataString, readRecord, uniqueStrings, } from './helpers.js';
 import { findHomeAssistantNode, missingDevicePassportFields, readHomeGraphState, renderHomeGraphState, safeHomeGraphFilename, } from './state.js';
 import { issuesForScope, renderDevicePassportPage, renderPacketPage, renderRoomPage, } from './rendering.js';
 import { deriveRepairProfileFacts } from '../semantic/repair-profile.js';
-import { semanticHash, semanticSlug } from '../semantic/utils.js';
+import { semanticFactId, semanticHash, semanticSlug } from '../semantic/utils.js';
+import { upsertSourceLinkedRepairProfileFact } from '../semantic/self-improvement-promotion.js';
 import { sourceAuthorityBoostForAnswer } from '../semantic/answer-source-ranking.js';
 import { compareHomeGraphPageSources, isUsefulHomeGraphPageFact, isUsefulHomeGraphPageSource } from './page-quality.js';
 export const HOME_GRAPH_PAGE_POLICY_VERSION = 'homegraph-pages-v7';
@@ -39,6 +40,10 @@ async function generateHomeGraphPagesForCurrentState(context, options) {
         ? Date.now() + Math.max(1_000, Math.trunc(effectiveOptions.maxRunMs))
         : undefined;
     const state = readHomeGraphState(context.store, context.spaceId);
+    const sourceLookup = buildDevicePassportSourceLookup(state.sources, state.nodes, state.edges);
+    const extractionsBySourceId = new Map(context.store
+        .listExtractionsForSources(new Set(state.sources.map((source) => source.id)))
+        .map((extraction) => [extraction.sourceId, extraction]));
     if (effectiveOptions.devicePassports !== false) {
         const allDevices = prioritizeNodesForGeneratedPages(state.nodes.filter((node) => node.kind === 'ha_device' && node.status !== 'stale'));
         const devices = limitRecords(allDevices, effectiveOptions.maxDevicePassports);
@@ -53,6 +58,9 @@ async function generateHomeGraphPagesForCurrentState(context, options) {
             try {
                 const page = await refreshHomeGraphDevicePassport({
                     ...context,
+                    state,
+                    sourceLookup,
+                    extractionsBySourceId,
                     input: {
                         knowledgeSpaceId: context.spaceId,
                         deviceId,
@@ -120,6 +128,7 @@ function deadlineReached(deadlineAt) {
 }
 export async function refreshHomeGraphDevicePassport(context) {
     const { store, artifactStore, spaceId, installationId, input } = context;
+    throwIfAborted(context.signal);
     if (!input.deviceId) {
         throw new GoodVibesSdkError('refreshDevicePassport requires deviceId.', {
             category: 'bad_request',
@@ -127,7 +136,8 @@ export async function refreshHomeGraphDevicePassport(context) {
             operation: 'homegraph.refreshDevicePassport',
         });
     }
-    const state = readHomeGraphState(store, spaceId);
+    const state = context.state ?? readHomeGraphState(store, spaceId);
+    throwIfAborted(context.signal);
     const device = findHomeAssistantNode(state.nodes, 'ha_device', input.deviceId);
     if (!device) {
         throw new GoodVibesSdkError(`Unknown Home Assistant device: ${input.deviceId}`, {
@@ -142,15 +152,25 @@ export async function refreshHomeGraphDevicePassport(context) {
         && edge.toKind === 'node'
         && edge.toId === device.id
         && edge.relation === 'belongs_to_device'))));
-    const sources = sourcesForDevicePassport(device.id, buildDevicePassportSourceLookup(state.sources, state.nodes, state.edges));
-    const pageProfileFacts = await upsertDevicePageProfileFacts({ store, spaceId, installationId, device, sources });
+    const sourceLookup = context.sourceLookup ?? buildDevicePassportSourceLookup(state.sources, state.nodes, state.edges);
+    const sources = sourcesForDevicePassport(device.id, sourceLookup);
+    const pageProfileFacts = await buildDevicePageProfileFacts({
+        store,
+        spaceId,
+        installationId,
+        device,
+        sources,
+        extractionsBySourceId: context.extractionsBySourceId,
+        signal: context.signal,
+    });
+    throwIfAborted(context.signal);
     const semanticFacts = uniqueNodesById([
         ...semanticFactsForNode(device.id, sources, state.nodes, state.edges),
-        ...pageProfileFacts,
+        ...pageProfileFacts.map((fact) => fact.node),
     ]);
     const scopedNodeIds = new Set([device.id, ...entities.map((node) => node.id)]);
     const issues = filterDevicePassportIssues(issuesForScope(state.issues, state.edges, scopedNodeIds, sources), sources);
-    const missingFields = missingDevicePassportFields(device, sources);
+    const missingFields = missingDevicePassportFields(device, sources, semanticFacts);
     const markdown = renderDevicePassportPage({ spaceId, device, entities, sources, issues, missingFields, semanticFacts });
     const pageContentHash = semanticHash(markdown);
     const passportId = homeGraphNodeId(spaceId, 'ha_device_passport', input.deviceId);
@@ -160,51 +180,76 @@ export async function refreshHomeGraphDevicePassport(context) {
         ? existingPassportMetadata.refreshedAt
         : undefined;
     const { passport, generated } = await store.batch(async () => {
-        const passport = await store.upsertNode({
-            id: passportId,
-            kind: 'ha_device_passport',
-            slug: `${device.slug}-passport`,
-            title: `${device.title} passport`,
-            summary: `Living device profile for ${device.title}.`,
-            aliases: [`${device.title} passport`],
-            confidence: 80,
-            metadata: buildHomeGraphMetadata(spaceId, installationId, {
-                homeAssistant: { installationId, objectKind: 'device_passport', objectId: input.deviceId },
-                deviceId: input.deviceId,
-                missingFields,
-                pageContentHash,
-                refreshedAt: existingPassportMetadata.pageContentHash === pageContentHash && previousRefreshedAt !== undefined
-                    ? previousRefreshedAt
-                    : Date.now(),
-            }),
-        });
-        await store.upsertEdge({
-            fromKind: 'node',
-            fromId: passport.id,
-            toKind: 'node',
-            toId: device.id,
-            relation: 'source_for',
-            metadata: buildHomeGraphMetadata(spaceId, installationId),
-        });
-        const generated = await materializeGeneratedMarkdown({
-            store,
-            artifactStore,
-            spaceId,
-            installationId,
-            filename: `${safeHomeGraphFilename(device.title)}-passport.md`,
-            markdown,
-            projectionKind: 'device-passport',
-            canonicalValue: `device-passport:${input.deviceId}`,
-            title: `${device.title} passport`,
-            summary: `Living device profile for ${device.title}.`,
-            tags: ['homeassistant', 'home-graph', 'generated-page', 'device-passport'],
-            targetNodeId: passport.id,
-            metadata: {
-                ...(input.metadata ?? {}),
-                deviceId: input.deviceId,
-            },
-        });
-        return { passport, generated };
+        throwIfAborted(context.signal);
+        const priorRecords = captureDevicePassportRefreshRecords(store, passportId, pageProfileFacts.map((fact) => fact.node.id));
+        const writtenNodeIds = new Set();
+        const writtenEdgeKeys = [];
+        async function rollbackWrittenRecords() {
+            await restoreDevicePassportRefreshRecords(store, priorRecords, writtenNodeIds, writtenEdgeKeys);
+        }
+        let passport;
+        try {
+            passport = await store.upsertNode({
+                id: passportId,
+                kind: 'ha_device_passport',
+                slug: `${device.slug}-passport`,
+                title: `${device.title} passport`,
+                summary: `Living device profile for ${device.title}.`,
+                aliases: [`${device.title} passport`],
+                status: 'active',
+                confidence: 80,
+                metadata: buildHomeGraphMetadata(spaceId, installationId, {
+                    homeAssistant: { installationId, objectKind: 'device_passport', objectId: input.deviceId },
+                    deviceId: input.deviceId,
+                    missingFields,
+                    pageContentHash,
+                    refreshedAt: existingPassportMetadata.pageContentHash === pageContentHash && previousRefreshedAt !== undefined
+                        ? previousRefreshedAt
+                        : Date.now(),
+                }),
+            });
+            writtenNodeIds.add(passport.id);
+            await store.upsertEdge({
+                fromKind: 'node',
+                fromId: passport.id,
+                toKind: 'node',
+                toId: device.id,
+                relation: 'source_for',
+                metadata: buildHomeGraphMetadata(spaceId, installationId),
+            });
+            writtenEdgeKeys.push({ fromKind: 'node', fromId: passport.id, toKind: 'node', toId: device.id, relation: 'source_for' });
+            throwIfAborted(context.signal);
+            for (const factPlan of pageProfileFacts) {
+                writtenNodeIds.add(factPlan.node.id);
+                writtenEdgeKeys.push({ fromKind: 'source', fromId: factPlan.source.id, toKind: 'node', toId: factPlan.node.id, relation: 'supports_fact' }, { fromKind: 'node', fromId: factPlan.node.id, toKind: 'node', toId: device.id, relation: 'describes' });
+                const fact = await upsertDevicePageProfileFact(store, spaceId, installationId, device, factPlan);
+                throwIfAborted(context.signal);
+            }
+            const generated = await materializeGeneratedMarkdown({
+                store,
+                artifactStore,
+                spaceId,
+                installationId,
+                filename: `${safeHomeGraphFilename(device.title)}-passport.md`,
+                markdown,
+                projectionKind: 'device-passport',
+                canonicalValue: `device-passport:${input.deviceId}`,
+                title: `${device.title} passport`,
+                summary: `Living device profile for ${device.title}.`,
+                tags: ['homeassistant', 'home-graph', 'generated-page', 'device-passport'],
+                targetNodeId: passport.id,
+                signal: context.signal,
+                metadata: {
+                    ...(input.metadata ?? {}),
+                    deviceId: input.deviceId,
+                },
+            });
+            return { passport, generated };
+        }
+        catch (error) {
+            await rollbackWrittenRecords();
+            throw error;
+        }
     });
     return {
         ok: true,
@@ -220,6 +265,91 @@ export async function refreshHomeGraphDevicePassport(context) {
         artifactCreated: generated.artifactCreated,
     };
 }
+function throwIfAborted(signal) {
+    if (!signal?.aborted)
+        return;
+    throw new GoodVibesSdkError('Home Graph device passport refresh was cancelled.', {
+        category: 'timeout',
+        source: 'runtime',
+        operation: 'homegraph.refreshDevicePassport',
+    });
+}
+function captureDevicePassportRefreshRecords(store, passportId, factIds) {
+    const nodeIds = uniqueStrings([passportId, ...factIds]);
+    const edgeKeys = [];
+    const passport = store.getNode(passportId);
+    if (passport) {
+        for (const edge of store.edgesFor('node', passport.id)) {
+            if (edge.fromKind === 'node' && edge.fromId === passport.id && edge.relation === 'source_for') {
+                edgeKeys.push(edgeKey(edge));
+            }
+        }
+    }
+    for (const factId of factIds) {
+        const fact = store.getNode(factId);
+        if (!fact)
+            continue;
+        for (const edge of store.edgesFor('node', fact.id)) {
+            if ((edge.toKind === 'node' && edge.toId === fact.id && edge.relation === 'supports_fact')
+                || (edge.fromKind === 'node' && edge.fromId === fact.id && edge.relation === 'describes')) {
+                edgeKeys.push(edgeKey(edge));
+            }
+        }
+    }
+    return {
+        nodes: new Map(nodeIds.map((id) => [id, store.getNode(id)])),
+        edges: new Map(edgeKeys.map((key) => [edgeKeyId(key), findDevicePassportRefreshEdge(store, key)])),
+    };
+}
+async function restoreDevicePassportRefreshRecords(store, prior, writtenNodeIds, writtenEdgeKeys) {
+    const edgeIds = uniqueStrings([
+        ...writtenEdgeKeys.map(edgeKeyId),
+        ...prior.edges.keys(),
+    ]);
+    for (const id of edgeIds) {
+        const priorEdge = prior.edges.get(id);
+        const current = findDevicePassportRefreshEdgeByKeyId(store, id);
+        if (priorEdge) {
+            await store.replaceEdgeRecord(priorEdge);
+        }
+        else if (current) {
+            await store.deleteEdge(current.id);
+        }
+    }
+    const nodeIds = uniqueStrings([...writtenNodeIds, ...prior.nodes.keys()]);
+    for (const id of nodeIds) {
+        const priorNode = prior.nodes.get(id);
+        const current = store.getNode(id);
+        if (priorNode) {
+            await store.replaceNodeRecord(priorNode);
+        }
+        else if (current) {
+            await store.deleteNode(id);
+        }
+    }
+}
+function edgeKey(edge) {
+    return {
+        fromKind: edge.fromKind,
+        fromId: edge.fromId,
+        toKind: edge.toKind,
+        toId: edge.toId,
+        relation: edge.relation,
+    };
+}
+function edgeKeyId(key) {
+    return `${key.fromKind}:${key.fromId}->${key.toKind}:${key.toId}:${key.relation}`;
+}
+function findDevicePassportRefreshEdge(store, key) {
+    return store.edgesFor(key.fromKind, key.fromId).find((edge) => edgeKeyId(edgeKey(edge)) === edgeKeyId(key)) ?? null;
+}
+function findDevicePassportRefreshEdgeByKeyId(store, keyId) {
+    for (const edge of store.listEdges()) {
+        if (edgeKeyId(edgeKey(edge)) === keyId)
+            return edge;
+    }
+    return null;
+}
 export async function generateHomeGraphRoomPage(context) {
     const { store, artifactStore, spaceId, installationId, input } = context;
     const state = readHomeGraphState(store, spaceId);
@@ -304,8 +434,10 @@ async function materializeGeneratedMarkdown(input) {
         pagePolicyVersion: HOME_GRAPH_PAGE_POLICY_VERSION,
         pageEditable: true,
         regeneration,
+        ...(input.targetNodeId ? { generatedTargetNodeId: input.targetNodeId } : {}),
     };
     const homeGraphMetadata = buildHomeGraphMetadata(input.spaceId, input.installationId, metadata);
+    throwIfAborted(input.signal);
     const generated = await materializeGeneratedKnowledgeProjection({
         store: input.store,
         artifactStore: input.artifactStore,
@@ -322,6 +454,7 @@ async function materializeGeneratedMarkdown(input) {
         metadata: homeGraphMetadata,
         sourceMetadata: homeGraphMetadata,
         artifactMetadata: homeGraphMetadata,
+        signal: input.signal,
         edgeMetadata: buildHomeGraphMetadata(input.spaceId, input.installationId, {
             homeGraphGeneratedPage: true,
             projectionKind: input.projectionKind,
@@ -383,30 +516,43 @@ function generatedPagePriority(node) {
         score -= 8;
     return score;
 }
-function semanticFactsLinkedToSources(sources, nodes, edges) {
+function semanticFactsForNode(nodeId, sources, nodes, edges) {
     const sourceIds = new Set(sources.map((source) => source.id));
-    const factIds = new Set(edges.filter((edge) => (edgeIsActive(edge)
+    const nodesById = new Map(nodes.map((node) => [node.id, node]));
+    const subjectFactIds = factIdsDescribingNode(edges, nodeId);
+    const edgeSupportedFactIds = sourceSupportedFactIds(edges, sourceIds);
+    const supportedFactIds = new Set();
+    for (const fact of nodesById.values()) {
+        if (fact.kind !== 'fact')
+            continue;
+        if (!factHasSubjectLink(fact, nodeId, subjectFactIds))
+            continue;
+        const hasSource = edgeSupportedFactIds.has(fact.id)
+            || factSourceIds(fact).some((sourceId) => sourceIds.has(sourceId));
+        if (hasSource)
+            supportedFactIds.add(fact.id);
+    }
+    return nodes.filter((node) => supportedFactIds.has(node.id) && isUsefulHomeGraphPageFact(node));
+}
+function sourceSupportedFactIds(edges, sourceIds) {
+    return new Set(edges.filter((edge) => (edgeIsActive(edge)
         && edge.fromKind === 'source'
         && sourceIds.has(edge.fromId)
         && edge.toKind === 'node'
         && edge.relation === 'supports_fact')).map((edge) => edge.toId));
-    return nodes.filter((node) => factIds.has(node.id) && isUsefulHomeGraphPageFact(node));
 }
-function semanticFactsForNode(nodeId, sources, nodes, edges) {
-    const factIds = new Set();
-    for (const edge of edges) {
-        if (edgeIsActive(edge)
-            && edge.fromKind === 'node'
-            && edge.toKind === 'node'
-            && edge.toId === nodeId
-            && edge.relation === 'describes') {
-            factIds.add(edge.fromId);
-        }
-    }
-    for (const fact of semanticFactsLinkedToSources(sources, nodes, edges)) {
-        factIds.add(fact.id);
-    }
-    return nodes.filter((node) => factIds.has(node.id) && isUsefulHomeGraphPageFact(node));
+function factIdsDescribingNode(edges, nodeId) {
+    return new Set(edges.filter((edge) => (edgeIsActive(edge)
+        && edge.fromKind === 'node'
+        && edge.toKind === 'node'
+        && edge.toId === nodeId
+        && edge.relation === 'describes')).map((edge) => edge.fromId));
+}
+function factHasSubjectLink(fact, nodeId, describedFactIds) {
+    if (describedFactIds.has(fact.id))
+        return true;
+    return readStringArray(fact.metadata.subjectIds).includes(nodeId)
+        || readStringArray(fact.metadata.linkedObjectIds).includes(nodeId);
 }
 function buildDevicePassportSourceLookup(sources, nodes, edges) {
     const sourcesById = new Map(sources.map((source) => [source.id, source]));
@@ -463,8 +609,8 @@ function buildDevicePassportSourceLookup(sources, nodes, edges) {
             const fact = nodesById.get(factId);
             if (!fact || fact.status === 'stale')
                 continue;
-            if (fact.sourceId)
-                addSourceForNode(nodeId, fact.sourceId);
+            for (const sourceId of factSourceIds(fact))
+                addSourceForNode(nodeId, sourceId);
             for (const sourceId of sourceIdsByFactId.get(factId) ?? []) {
                 addSourceForNode(nodeId, sourceId);
             }
@@ -490,28 +636,44 @@ function filterDevicePassportIssues(issues, sources) {
         return issues;
     return issues.filter((issue) => issue.code !== 'homegraph.device.missing_manual');
 }
-async function upsertDevicePageProfileFacts(input) {
-    return input.store.batch(async () => {
-        const facts = [];
-        const sources = input.sources
-            .filter(isUsefulHomeGraphPageSource)
-            .sort(compareHomeGraphPageSources)
-            .slice(0, MAX_PROFILE_SOURCES_PER_DEVICE_PAGE);
-        for (const source of sources) {
-            const extraction = input.store.getExtractionBySourceId(source.id);
-            const sourceText = extractedPageSourceText(source, extraction);
-            if (!sourceText.trim())
-                continue;
-            const profileFacts = deriveRepairProfileFacts({
-                query: `complete features specifications ${input.device.title}`,
-                source,
-                text: sourceText,
+async function buildDevicePageProfileFacts(input) {
+    throwIfAborted(input.signal);
+    const facts = [];
+    const sources = input.sources
+        .filter(isUsefulHomeGraphPageSource)
+        .sort(compareHomeGraphPageSources)
+        .slice(0, MAX_PROFILE_SOURCES_PER_DEVICE_PAGE);
+    for (const source of sources) {
+        throwIfAborted(input.signal);
+        const extraction = input.extractionsBySourceId?.get(source.id) ?? input.store.getExtractionBySourceId(source.id);
+        const sourceText = extractedPageSourceText(extraction);
+        if (!sourceText.trim())
+            continue;
+        const profileFacts = deriveRepairProfileFacts({
+            query: `complete features specifications ${input.device.title}`,
+            source,
+            text: sourceText,
+        });
+        for (const profileFact of profileFacts) {
+            throwIfAborted(input.signal);
+            const authorityBoost = sourceAuthorityBoostForAnswer(source);
+            const subjectIds = [input.device.id];
+            const sourceIds = [source.id];
+            const now = Date.now();
+            const factId = semanticFactId({
+                spaceId: input.spaceId,
+                kind: profileFact.kind,
+                title: profileFact.title,
+                value: profileFact.value,
+                summary: profileFact.summary,
+                subjectIds,
+                fallbackScope: source.id,
             });
-            for (const profileFact of profileFacts) {
-                const fact = await input.store.upsertNode({
-                    id: `sem-fact-${semanticHash(input.spaceId, source.id, input.device.id, profileFact.title, profileFact.value ?? profileFact.summary)}`,
+            facts.push({
+                node: {
+                    id: factId,
                     kind: 'fact',
-                    slug: semanticSlug(`${input.spaceId}-${input.device.title}-${profileFact.title}-${source.id}`),
+                    slug: semanticSlug(`${input.spaceId}-${profileFact.title}-${profileFact.summary}-${source.id}`),
                     title: profileFact.title,
                     summary: profileFact.summary,
                     aliases: profileFact.aliases,
@@ -525,52 +687,59 @@ async function upsertDevicePageProfileFacts(input) {
                         evidence: profileFact.evidence,
                         labels: profileFact.labels,
                         sourceId: source.id,
+                        sourceIds,
                         subject: input.device.title,
-                        subjectIds: [input.device.id],
-                        targetHints: [{ id: input.device.id, kind: input.device.kind, title: input.device.title }],
-                        linkedObjectIds: [input.device.id],
+                        subjectIds,
+                        targetHints: [{ id: input.device.id, title: input.device.title, kind: input.device.kind }],
+                        linkedObjectIds: subjectIds,
                         extractor: 'page-profile',
+                        sourceAuthority: authorityBoost >= 120 ? 'official-vendor' : authorityBoost > 0 ? 'vendor' : 'secondary',
                     }),
-                });
-                await input.store.upsertEdge({
-                    fromKind: 'source',
-                    fromId: source.id,
-                    toKind: 'node',
-                    toId: fact.id,
-                    relation: 'supports_fact',
-                    weight: PAGE_PROFILE_SOURCE_WEIGHT,
-                    metadata: buildHomeGraphMetadata(input.spaceId, input.installationId, {
-                        linkedBy: 'generated-page-profile',
-                    }),
-                });
-                await input.store.upsertEdge({
-                    fromKind: 'node',
-                    fromId: fact.id,
-                    toKind: 'node',
-                    toId: input.device.id,
-                    relation: 'describes',
-                    weight: PAGE_PROFILE_DESCRIBES_WEIGHT,
-                    metadata: buildHomeGraphMetadata(input.spaceId, input.installationId, {
-                        linkedBy: 'generated-page-profile',
-                        sourceId: source.id,
-                    }),
-                });
-                facts.push(fact);
-            }
+                    createdAt: now,
+                    updatedAt: now,
+                },
+                source,
+                title: profileFact.title,
+                summary: profileFact.summary,
+                evidence: profileFact.evidence,
+                classification: profileFact,
+                authority: authorityBoost >= 120 ? 'official-vendor' : authorityBoost > 0 ? 'vendor' : 'secondary',
+            });
         }
-        return facts;
+    }
+    return facts;
+}
+async function upsertDevicePageProfileFact(store, spaceId, installationId, device, fact) {
+    return upsertSourceLinkedRepairProfileFact({
+        store,
+        spaceId,
+        source: fact.source,
+        subjects: [device],
+        authority: fact.authority,
+        title: fact.title,
+        summary: fact.summary,
+        evidence: fact.evidence,
+        classification: fact.classification,
+        extractor: 'page-profile',
+        confidence: 72,
+        supportWeight: PAGE_PROFILE_SOURCE_WEIGHT,
+        describesWeight: PAGE_PROFILE_DESCRIBES_WEIGHT,
+        edgeMetadata: {
+            linkedBy: 'generated-page-profile',
+        },
+        metadataBuilder: (metadata) => buildHomeGraphMetadata(spaceId, installationId, metadata),
     });
 }
-function extractedPageSourceText(source, extraction) {
-    const structure = readRecord(extraction?.structure);
+function extractedPageSourceText(extraction) {
+    if (!extraction)
+        return '';
+    const structure = readRecord(extraction.structure);
     const nestedStructure = readRecord(structure.structure);
-    const metadata = readRecord(extraction?.metadata);
+    const metadata = readRecord(extraction.metadata);
     const nestedMetadata = readRecord(structure.metadata);
     return [
-        source.summary,
-        source.description,
-        extraction?.excerpt,
-        ...(extraction?.sections ?? []),
+        extraction.excerpt,
+        ...extraction.sections,
         typeof structure.searchText === 'string' ? structure.searchText : undefined,
         typeof structure.text === 'string' ? structure.text : undefined,
         typeof structure.content === 'string' ? structure.content : undefined,

package/dist/platform/knowledge/home-graph/helpers.d.ts

@@ -1,4 +1,4 @@
-import type { KnowledgeEdgeRecord, KnowledgeNodeKind, KnowledgeSourceRecord, KnowledgeReferenceKind, KnowledgeIssueUpsertInput } from '../types.js';
+import type { KnowledgeEdgeRecord, KnowledgeNodeKind, KnowledgeNodeRecord, KnowledgeSourceRecord, KnowledgeReferenceKind, KnowledgeIssueUpsertInput } from '../types.js';
 import type { HomeGraphKnowledgeTarget, HomeGraphNodeKind, HomeGraphObjectInput, HomeGraphObjectKind, HomeGraphSpaceInput } from './types.js';
 export declare const HOME_GRAPH_CONNECTOR_ID = "homeassistant";
 export declare function resolveHomeGraphSpace(input?: HomeGraphSpaceInput): {
@@ -18,12 +18,13 @@ export declare function buildHomeGraphNodeInput(spaceId: string, installationId:
     readonly kind: KnowledgeNodeKind;
     readonly slug: string;
     readonly title: string;
-    readonly summary?: string;
+    readonly summary?: string | undefined;
     readonly aliases: readonly string[];
     readonly metadata: Record<string, unknown>;
 };
 export declare function edgeIsActive(edge: KnowledgeEdgeRecord): boolean;
 export declare function isGeneratedPageSource(source: KnowledgeSourceRecord): boolean;
+export declare function factSourceIds(fact: KnowledgeNodeRecord): string[];
 export declare function belongsToSpace(record: {
     readonly metadata?: Record<string, unknown>;
 } | undefined | null, spaceId: string): boolean;
@@ -32,7 +33,7 @@ export declare function homeAssistantSpaceComponent(spaceId: string): string | u
 export declare function targetToReference(target: HomeGraphKnowledgeTarget): {
     readonly kind: KnowledgeReferenceKind;
     readonly id: string;
-    readonly nodeKind?: HomeGraphNodeKind;
+    readonly nodeKind?: HomeGraphNodeKind | undefined;
 };
 export declare function buildIssue(spaceId: string, installationId: string, code: string, message: string, subject: {
     readonly nodeId?: string;

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

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

package/dist/platform/knowledge/home-graph/helpers.js

@@ -1,5 +1,6 @@
 import { createHash } from 'node:crypto';
 import { isGeneratedKnowledgeSource, } from '../generated-projections.js';
+import { isActiveKnowledgeEdge } from '../projection-utils.js';
 import { HOME_ASSISTANT_KNOWLEDGE_SPACE_PREFIX, getKnowledgeSpaceId, homeAssistantKnowledgeSpaceId, knowledgeSpaceMetadata, normalizeHomeAssistantInstallationId, normalizeKnowledgeSpaceId, normalizeSpaceComponent, } from '../spaces.js';
 export const HOME_GRAPH_CONNECTOR_ID = 'homeassistant';
 const NODE_KIND_BY_OBJECT = {
@@ -118,11 +119,18 @@ function homeGraphObjectId(kind, object) {
     }
 }
 export function edgeIsActive(edge) {
-    return edge.metadata.linkStatus !== 'unlinked';
+    return isActiveKnowledgeEdge(edge);
 }
 export function isGeneratedPageSource(source) {
     return isGeneratedKnowledgeSource(source);
 }
+export function factSourceIds(fact) {
+    return uniqueStrings([
+        ...readStringArray(fact.metadata.sourceIds),
+        readString(fact.metadata.sourceId),
+        fact.sourceId,
+    ]);
+}
 export function belongsToSpace(record, spaceId) {
     if (!record)
         return false;
@@ -310,8 +318,7 @@ function stableJson(value) {
             return Object.fromEntries(Object.entries(entry).sort(([left], [right]) => left.localeCompare(right)));
         });
     }
-    catch (error) {
-        void error;
+    catch {
         return String(value);
     }
 }

package/dist/platform/knowledge/home-graph/import-export.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"import-export.d.ts","sourceRoot":"","sources":["../../../../src/platform/knowledge/home-graph/import-export.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAGlD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,cAAc,EACrB,KAAK,EAAE;IAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;CAAE,GACnE,eAAe,CAajB;AAED,wBAAsB,oBAAoB,CACxC,KAAK,EAAE,cAAc,EACrB,KAAK,EAAE;IAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAA;CAAE,GACnG,OAAO,CAAC;IACT,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAClB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE;QAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC;CACxJ,CAAC,CA2BD"}
+{"version":3,"file":"import-export.d.ts","sourceRoot":"","sources":["../../../../src/platform/knowledge/home-graph/import-export.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAGlD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,cAAc,EACrB,KAAK,EAAE;IAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;CAAE,GACnE,eAAe,CAajB;AAED,wBAAsB,oBAAoB,CACxC,KAAK,EAAE,cAAc,EACrB,KAAK,EAAE;IAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAA;CAAE,GACnG,OAAO,CAAC;IACT,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAClB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE;QAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC;CACxJ,CAAC,CA6BD"}